mirror of
https://github.com/garrytan/gstack.git
synced 2026-11-19 22:54:36 +01:00
* docs(designs): gstack field wave plan (2026-10-12) and the shared simulated Capy host fixture
Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>
* fix(autoplan): scope keys on rendered surfaces, per-axis provenance, --no-dx and a read-only plan marker
UI scope reads the Implementation plan only and needs a rendered file path or a UI
term next to a visual noun; bare UI words stay weak evidence (sections load, no
Design phase). Scope records sources {ui,dx} (flag|marker|detected), --no-dx turns
DX off, a first-line <!-- gstack-autoplan-scope: ... --> marker is read and never
written, and the first next prints SCOPE: evidence plus a SCOPE_PIN hint. The
snapshot tool's scope output carries uiRequired from the same detector and
autoplan Step 2 uses it instead of a prose grep (field wave item 11).
Intentional pin change: test/review-checklists.test.ts Scope literal and the
source= line shape (source=ui:detected,dx:detected).
Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>
* fix(plan-reality): a receipt per measured number, the rule text for a rule claim, dot-path receipts
Each clause stating a measured quantity (a unit, or a number after measured/costs/
takes/took) needs its own receipt; misses print unreceipted_numbers=<n> and one
NUMBER_UNRECEIPTED: <clause> line each. A line claiming a decision rule must quote
it or link its file:line (unquoted=<n>). Either miss maps to the existing verdict
(incomplete unattended, repair otherwise). RECEIPT_RE accepts dot paths and needs
a hex letter or a commit/backtick context for a sha. New pure checkPlanReality(planText)
runs the same checks over plan prose for gstack-autoplan submit (field wave item 12).
The unreceipted= text token is now pinned as well as the JSON.
Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>
* feat(autoplan): generated DRIVER.md, the compact entry for a parent driving gstack-autoplan
autoplan/DRIVER.md (from autoplan/DRIVER.md.tmpl) is what a parent agent on any host
reads instead of autoplan/SKILL.md: phase order and scope flags, the next/submit/
answer/revise/export loop with the plan-specified submit --record/--attest/
--unavailable, revise --incorporates/--withdraw and next --scaffold, the reviewer
RESULT FORMAT, the gate grammar including all as-is, the run files, the result codes
and the coordinator contract, every list rendered from code (117 lines). gen:skill-docs
emits it as a Claude asset, so normal, out-dir and dry-run inventories and the
freshness check cover it. gstack-autoplan --help and the first next print
DRIVER: <root>/autoplan/DRIVER.md, resolved through an install root's recorded
.source-path (new lib/source-root.ts) (field wave item 13).
Intentional pin change: test/gen-skill-docs-checks.test.ts asset inventory gains
autoplan/DRIVER.md.
Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>
* feat(doctor): --min-revision, a launch Bun found off PATH, planning-only pins SKIP
gstack-doctor --check gains --min-revision <v>|unknown: below it the revision
row FAILs with REVISION_BELOW_MINIMUM naming the Capy wrapper or
bin/gstack-upgrade; unknown says so and never claims the minimum. The runtime
and pins rows name a supported Bun found in $BUN_INSTALL/bin (not on PATH)
with the export/GSTACK_LAUNCH fix (gstack_bun_launch_dir, one helper in
bin/gstack-bun-version.sh). --for a planning-only workflow (autoplan, the plan
reviews, office-hours) reports a repo test-pin mismatch as SKIP pins
(planning-only; ...). New result codes UPGRADE_REFUSED, UPGRADE_FETCH_FAILED,
REVISION_BELOW_MINIMUM, CAPY_WRAPPER_STALE, INSTALL_UNVERIFIED with
troubleshooting anchors; REVISION_UNMET's fix names bin/gstack-upgrade.
Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>
* feat(install): install verdict and install admission at skill start
bin/gstack-install-verdict.sh (Bash) and lib/install-verdict.ts (TypeScript)
are the one reader of the install verdict gstack-capy-install writes to
<state root>/install-verdicts/<sha256(checkout realpath)>.json (checkout,
HEAD, workflow and required components, planning-only pins, trailer). The
source checkout and capy/support.env resolve through gstack_source_root /
sourceRoot, which follow an installed root's .source-path.
gstack-skill-start, after SESSION_KIND: an unattended session (any host)
refuses on a PATH Bun below the supported minimum; with GSTACK_CAPY=1 an
unattended or explicit spawned session also refuses without a passing
verdict for this checkout, HEAD and workflow (INSTALL_UNVERIFIED). A refusal
prints the INSTALL: row, an install-refused instruction block bound to its
SESSION_ID, GSTACK_RESULT ... status=refused run=- and exits 3. Ambient
spawned sessions warn; GSTACK_ALLOW_UNSUPPORTED_RUNTIME=1 admits and says so.
capy/support.env declares GSTACK_MIN_REVISION and GSTACK_CAPY_MIN_WRAPPER.
Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>
* feat(capy-install): launch PATH, Bun reuse and CI pins, setup skip on HEAD, verdict, --check
The GSTACK_LAUNCH line carries PATH=<dir>:$PATH when the certified Bun is not
first on PATH, plus GSTACK_CAPY=1 and GSTACK_INSTALL_VERDICT, and
GSTACK_LAUNCH_PATH: <dir>; the doctor runs with that PATH. A supported Bun in
$BUN_INSTALL/bin is reused instead of downloaded again. Project pins are read
with bin/gstack-runtime-pins.ts (CI lanes included): when every exact pin is
gstack's verified version the archive is installed alongside a different PATH
Bun; any other exact pin is RUNTIME_PIN_CONFLICT. Both ./setup runs are
skipped when this HEAD was set up with the same hosts, model and browser flag
and the check passes (never after a fast-forward); a failed setup ends with
gstack: fail setup and is retried next run. --check certifies only;
GSTACK_CAPY_LOCK_HELD=1 accepts the bootstrapper's held lock; result anchors
come from the generated components table; REV_NOTE names bin/gstack-upgrade.
Intentional pin change: test/gstack-capy-install.test.ts --revision trailer
now names <root>/bin/gstack-upgrade (the old text named a command that never
existed).
Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>
* result codes: PLAN_SECTIONS_INVALID, PLAN_AMEND_PENDING, GSTACK_VERSION_CHANGED, INSTALL_VERDICT_FAILED, ARTIFACT_GATE_UNSETTLED
Troubleshooting anchors for each and the regenerated doctor components table (field wave lane B-core).
Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>
* artifact contract: changes, recommended_basis, carried decisions, attested count, settled-gate check
Findings and decisions carry the user challenge's `changes` value; decisions record recommended_basis, origin,
carried_from and chosen_text; validate refuses a complete run with an unsettled gate (ARTIFACT_GATE_UNSETTLED) and
prints attested=<n>. The gate reply grammar gains `all as-is` and resolves partial replies against prior answers
(field wave B2a/B2b).
Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>
* autoplan: run-state fields, plan-text hashing, version migration and admission modules
RunState gains gstack_version, plan_input/heading, scope_flags, plan_revision, amendments and plan_reality; voices
record receipt kind and reviewed hash. New pure modules: Implementation-plan review hash, scaffold and drift lines
(B1c); gstack_version stamp and legacy decision-id migration (B1a); install-verdict and Bun-minimum admission
with a local verdict shim until lane A's lib/install-verdict.ts lands.
Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>
bin/gstack-autoplan-snapshot.ts exports its section scanner and review projection, and initializes only a plan with
no section headings by wrapping it.
Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>
* autoplan: closable runs - submit --record/--attest/--unavailable, revise, amendment interlock, agreeing-UC defaults, admission
B1a: an older run directory prints GSTACK_VERSION_CHANGED once and migrates legacy decision ids; a newer one refuses.
B1b: submit binds hand-run records (fence, table, severity list, No findings.), attested binds need --attempt,
--attempt is optional with one open attempt, --unavailable/--failed close an outside voice native_only, and submit
caches the plan-reality report by Implementation-plan hash.
B1c: revise reviews a revised plan in the same run as one recoverable transaction (reopen on hash drift plus Eng,
add newly in-scope phases, .r<rev>/.v<k> archives, gate_rev+1 at the gate); PLAN_SECTIONS_INVALID and next --scaffold;
PLAN_CHANGED / PLAN_SOURCE_CHANGED drift hints.
B2a/B2b: user challenges carry changes; agreeing voices with the same changes on a confirmed finding recommend b with
both remedies shown (or the reconcile proposal); accepted changes print APPLY and become pending amendments that next
and export refuse past until revise --incorporates names them or --withdraw drops one; all as-is; partial replies,
DECIDED block, carry-forward and rerun demotion.
Mutating verbs pass admission (GSTACK_CAPY install verdict; unattended Bun minimum; override recorded as a deviation).
Intentional pin rewrite: test/autoplan-answer-invalidation.test.ts reopen tests now revise --incorporates before rerun.
Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>
* feat(upgrade): bin/gstack-upgrade, the unattended fast-forward every fix line names
--check fetches and prints current|behind <installed> -> <remote> (<n>
commits); the default fast-forwards to the remote default branch tip and
reinstalls (bin/gstack-capy-install on a Capy install, else ./setup
--refresh-registered), completing a pending reinstall on the next run. It
refuses (UPGRADE_REFUSED, exit 3, nothing changed) a dirty tracked byte, a
diverged commit, a pinned checkout, the incoming Bun floor and a held
.setup-lock; never stashes or resets; an unreachable remote is
UPGRADE_FETCH_FAILED. Fetches are receipted (fail-open). The unattended
skill-end UPGRADE_AVAILABLE line is followed by UPGRADE_COMMAND naming it.
Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>
* feat(capy): vendored Capy skill, frozen bootstrapper and full wrapper bin/gstack-capy-session
capy/skill/gstack/ is the Drive skill's source of truth. scripts/install.sh
is a frozen bootstrapper: it prints gstack-capy-skill: wrapper <n> (<path>),
clones or fetches under .gstack-capy-install.lock, reads the remote
capy/support.env (FETCH_HEAD), fast-forwards a clean unpinned checkout below
GSTACK_MIN_REVISION (refusing dirty, diverged or pinned checkouts with the
exact commands; GSTACK_CAPY_AUTO_UPGRADE=0 disables), and execs the
checkout's own bin/gstack-capy-session with GSTACK_CAPY_LOCK_HELD=1 so the
held lock is never taken twice. Offline it says the remote minimum is
unknown. A Drive copy older than GSTACK_CAPY_MIN_WRAPPER prints an owner
action (CAPY_WRAPPER_STALE). SKILL.md: check at session start, install
lazily before the first workflow, the GSTACK_LAUNCH line, the trailer rule,
the subagent first-report line, gstack-pregate sealed before any push, and
the autoplan/DRIVER.md pointer. The context-budget fixture gains the skill's
entry.
Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>
* docs: Capy install layers, lazy install, snapshot bake, forward-only recovery, raising the minimum
docs/capy-install.md describes the three layers (Drive bootstrapper, full
wrapper, installer), the lazy install, the GSTACK_LAUNCH line, install
admission, baking gstack into a Capy snapshot, and that recovery after an
interrupted fast-forward completes or refuses the pending install stages
(checking out an older commit is not a rollback). docs/CHANGELOG_STYLE.md
(the release doc; there is no docs/RELEASING.md) says when
GSTACK_MIN_REVISION may be raised.
Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>
* refactor(capy): the stale-copy owner action moves from the frozen bootstrapper to bin/gstack-capy-session
The checkout-owned full wrapper reads GSTACK_CAPY_MIN_WRAPPER through
gstack_support_env_get(gstack_source_root) and compares it with the
bootstrapper revision it was handed, so the rule can change without
recopying the Drive skill. The bootstrapper keeps only what a stale checkout
cannot do: clone, fetch, read the remote minimum, fast-forward, exec.
Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>
* v1.91.96.0: honest install and self-upgrade on Capy; supported minimum 1.91.96.0
Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>
* v1.91.97.0: closable unattended autoplan runs on Capy
Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>
* test: drop the helper-only Capy host fixture test (test-of-test ratchet); lane tests exercise the helper
Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>
* fix(autoplan): revise naming a non-pending decision refuses with AMENDMENT_UNKNOWN, not PLAN_AMEND_PENDING
Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>
* test: bound the new sync spawns in the install-verdict and wrapper tests (spawnSync tripwire)
Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>
* test(autoplan): pin CLI refusals to the result-code registry's fix text
Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>
* fix(gen-skill-docs): emit autoplan/DRIVER.md only when the autoplan template is in the tree (setup fixtures with a skill subset)
Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>
* fix(autoplan): run.lock is linked into place with its owner written; a fresh unreadable lock is held, not stolen
Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>
* ci(paid-pr-profile): the vendored Capy skill is free-only; free-only files are not prompts needing paid coverage
Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>
* chore(harness): non-behavioral HARNESS_VERSION decision for the PR-profile free-only rule
Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>
* test(doctor): lane A runtime and pins cases are platform-neutral (bash paths; a lane-free .bun-version pin)
Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>
* docs(designs): field wave plan with amendments and the gate rev 2-3 review record (ARTIFACT_VALID, 3 gate revisions)
Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>
* fix(capy-install): follow a project's exact Bun pin above the minimum when gstack has its verified archive (adds Bun 1.4.3)
Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>
* docs: the installer follows a verified exact project Bun pin (capy-install, troubleshooting, changelog)
Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>
* fix(capy-install): the install reason names the project's pin and gstack's real minimum
Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>
* ci: run the main-targeted checks after retargeting #3165 to main
Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>
* test(autoplan-admission): the PATH-Bun refusal case needs the POSIX Capy host stub; skip it on Windows
Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>
---------
Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>
320 lines
20 KiB
TypeScript
320 lines
20 KiB
TypeScript
/**
|
|
* autoplan-reconcile — canonical reviewer findings and the reconciliation of
|
|
* an outside pass against the native one (plan B11, B0). Every reviewer
|
|
* returns, beside its prose, a full-read receipt (`INPUT: <phase> <sha256>`)
|
|
* and one ```gstack-findings fence of JSONL rows; `parseReviewResult` checks
|
|
* both. `canonicalRows` binds the rows to run-bound ids
|
|
* (`<run>-<phase>-<voice>-<n>`, the findings.jsonl shape in
|
|
* lib/headless-artifacts.ts). `reconcile` records, for each outside finding,
|
|
* `confirmed`, `disagree` or `new` against the native result from exact ids,
|
|
* keeping disagreement and resolution as separate fields; a parent may hand in
|
|
* a semantic reconciliation that overrides the structural one, validated
|
|
* against the same ids. The consensus table is rendered from these rows, so
|
|
* the reconciliation is the completeness check a prose hash cannot be.
|
|
*/
|
|
import type { FindingRow, Severity, Voice } from './headless-artifacts';
|
|
|
|
export const SEVERITIES: readonly Severity[] = ['Critical', 'High', 'Medium', 'Low', 'Informational'];
|
|
const SEVERITY_ALIASES: Record<string, Severity> = {
|
|
critical: 'Critical', p0: 'Critical', blocker: 'Critical',
|
|
high: 'High', p1: 'High', major: 'High',
|
|
medium: 'Medium', p2: 'Medium', moderate: 'Medium',
|
|
low: 'Low', p3: 'Low', minor: 'Low',
|
|
informational: 'Informational', info: 'Informational', note: 'Informational',
|
|
};
|
|
|
|
export interface CanonicalFinding {
|
|
severity: Severity; title: string; file?: string; line?: number; fix?: string; local_id?: string;
|
|
user_challenge?: boolean; urgent?: boolean; suggested_owner?: string; plan_items?: string[]; dimension?: string;
|
|
/** What a user challenge changes; only these three make it a gate question (plan B2a). */
|
|
changes?: Changes;
|
|
}
|
|
export const CHANGES = ['scope', 'cost', 'direction'] as const;
|
|
export type Changes = typeof CHANGES[number];
|
|
export interface ParsedReviewResult {
|
|
receipt: { ok: boolean; phase?: string; sha256?: string; line?: string };
|
|
findings: CanonicalFinding[];
|
|
fenceFound: boolean;
|
|
errors: string[];
|
|
}
|
|
|
|
export function severityOf(value: unknown): Severity | undefined {
|
|
if (typeof value !== 'string') return undefined;
|
|
return SEVERITY_ALIASES[value.trim().toLowerCase()];
|
|
}
|
|
|
|
/** Parse a reviewer's result: the INPUT receipt for this phase and snapshot, then the canonical findings fence(s). */
|
|
export function parseReviewResult(text: string, expected: { phase: string; sha256: string }): ParsedReviewResult {
|
|
const errors: string[] = [];
|
|
const receipt = parseReceipt(text, expected);
|
|
if (!receipt.ok) errors.push(receipt.error!);
|
|
const { findings, fenceFound } = parseFences(text, errors);
|
|
if (!fenceFound) errors.push('no ```gstack-findings fence');
|
|
return { receipt, findings, fenceFound, errors };
|
|
}
|
|
|
|
/** The full-read receipt: `INPUT: <phase> <sha256>` in the first five non-empty lines, matching this phase and snapshot. */
|
|
export function parseReceipt(text: string, expected: { phase: string; sha256: string }): ParsedReviewResult['receipt'] & { present: boolean; error?: string } {
|
|
const head = text.split('\n').map(l => l.trim()).filter(Boolean).slice(0, 5);
|
|
const receiptLine = head.find(l => /^INPUT:\s*\S+\s+[0-9a-f]{64}\b/i.test(l));
|
|
const m = receiptLine ? /^INPUT:\s*(\S+)\s+([0-9a-f]{64})/i.exec(receiptLine) : null;
|
|
if (!m) return { ok: false, present: false, error: 'no INPUT: <phase> <sha256> line in the first five lines' };
|
|
const ok = m[1]!.toLowerCase() === expected.phase && m[2]!.toLowerCase() === expected.sha256.toLowerCase();
|
|
return { ok, present: true, phase: m[1]!.toLowerCase(), sha256: m[2]!.toLowerCase(), line: receiptLine,
|
|
...(ok ? {} : { error: `receipt names ${m[1]} ${m[2]!.slice(0, 12)}…, expected ${expected.phase} ${expected.sha256.slice(0, 12)}…` }) };
|
|
}
|
|
|
|
function parseFences(text: string, errors: string[]): { findings: CanonicalFinding[]; fenceFound: boolean } {
|
|
const findings: CanonicalFinding[] = [];
|
|
let fenceFound = false;
|
|
for (const fence of text.matchAll(/^[ \t]*(`{3,}|~{3,})gstack-findings[ \t]*\r?\n([\s\S]*?)\r?\n[ \t]*\1[ \t]*$/gm)) {
|
|
fenceFound = true;
|
|
fence[2]!.split('\n').forEach((raw, i) => {
|
|
const line = raw.trim();
|
|
if (!line) return;
|
|
let row: any;
|
|
try { row = JSON.parse(line); } catch (e: any) { errors.push(`findings row ${i + 1}: ${e.message}`); return; }
|
|
if (!row || typeof row !== 'object' || Array.isArray(row)) { errors.push(`findings row ${i + 1}: not an object`); return; }
|
|
const severity = severityOf(row.severity);
|
|
if (!severity) { errors.push(`findings row ${i + 1}: severity ${JSON.stringify(row.severity)} is not one of ${SEVERITIES.join('|')}`); return; }
|
|
if (typeof row.title !== 'string' || !row.title.trim()) { errors.push(`findings row ${i + 1}: title is required`); return; }
|
|
const finding: CanonicalFinding = { severity, title: row.title.trim() };
|
|
if (typeof row.file === 'string' && row.file) finding.file = row.file;
|
|
if (Number.isInteger(row.line)) finding.line = row.line;
|
|
if (typeof row.fix === 'string' && row.fix) finding.fix = row.fix;
|
|
if (typeof row.id === 'string' && row.id) finding.local_id = row.id;
|
|
if (row.user_challenge === true) finding.user_challenge = true;
|
|
if (row.urgent === true) finding.urgent = true;
|
|
if (typeof row.suggested_owner === 'string') finding.suggested_owner = row.suggested_owner;
|
|
if (Array.isArray(row.plan_items)) finding.plan_items = row.plan_items.filter((p: unknown): p is string => typeof p === 'string');
|
|
if (typeof row.dimension === 'string') finding.dimension = row.dimension;
|
|
if (row.changes !== undefined) {
|
|
if (!(CHANGES as readonly unknown[]).includes(row.changes)) { errors.push(`findings row ${i + 1}: changes ${JSON.stringify(row.changes)} is not one of ${CHANGES.join('|')}`); return; }
|
|
finding.changes = row.changes;
|
|
}
|
|
findings.push(finding);
|
|
});
|
|
}
|
|
return { findings, fenceFound };
|
|
}
|
|
|
|
export const RECORD_SHAPES = 'a ```gstack-findings fence, exactly one findings table (Severity and Title columns), one severity-tagged list (`- [High] title`), or an exact `No findings.` line';
|
|
const SEVERITY_HEADER = /^(severity|sev|priority)$/i;
|
|
const TITLE_HEADER = /^(finding|title|issue|summary)$/i;
|
|
const cells = (line: string) => line.trim().replace(/^\|/, '').replace(/\|$/, '').split('|').map(c => c.trim());
|
|
|
|
/** Findings tables in a record: header row with severity and title columns, a delimiter row, then body rows. */
|
|
function recordTables(lines: string[]): Array<{ header: string[]; rows: Array<{ cells: string[]; n: number }> }> {
|
|
const tables: Array<{ header: string[]; rows: Array<{ cells: string[]; n: number }> }> = [];
|
|
for (let i = 0; i + 1 < lines.length; i++) {
|
|
if (!/^\s*\|/.test(lines[i]!) || !/^\s*\|?\s*:?-{3,}/.test(lines[i + 1]!)) continue;
|
|
const header = cells(lines[i]!).map(h => h.replace(/[*_`]/g, '').trim());
|
|
if (!header.some(h => SEVERITY_HEADER.test(h)) || !header.some(h => TITLE_HEADER.test(h))) continue;
|
|
const rows: Array<{ cells: string[]; n: number }> = [];
|
|
let j = i + 2;
|
|
for (; j < lines.length && /^\s*\|/.test(lines[j]!); j++) rows.push({ cells: cells(lines[j]!), n: rows.length + 1 });
|
|
tables.push({ header, rows });
|
|
i = j - 1;
|
|
}
|
|
return tables;
|
|
}
|
|
|
|
const LIST_ITEM = /^\s*(?:[-*+]|\d+[.)])\s+(?:\[([^\]]+)\]|\*\*([^*]+)\*\*|\(([^)]+)\))\s*:?\s*(\S.*)$/;
|
|
|
|
/**
|
|
* Findings from a hand-run record (`submit --record`): the canonical fence
|
|
* when present; else exactly one of a findings table, a severity-tagged list
|
|
* or an exact `No findings.` line. More than one candidate shape, none, or a
|
|
* table row whose severity is not recognized is an error: the parser never
|
|
* guesses a severity.
|
|
*/
|
|
export function parseRecordFindings(text: string): { findings: CanonicalFinding[]; source: 'fence' | 'table' | 'list' | 'none'; errors: string[] } {
|
|
const errors: string[] = [];
|
|
const fenced = parseFences(text, errors);
|
|
if (fenced.fenceFound) return { findings: fenced.findings, source: 'fence', errors };
|
|
const lines = text.split('\n');
|
|
const tables = recordTables(lines);
|
|
const listBlocks: Array<CanonicalFinding[]> = [];
|
|
let current: CanonicalFinding[] | null = null;
|
|
for (const line of lines) {
|
|
const m = LIST_ITEM.exec(line);
|
|
const severity = m ? severityOf(m[1] ?? m[2] ?? m[3]) : undefined;
|
|
if (m && severity) { (current ??= (listBlocks.push([]), listBlocks[listBlocks.length - 1]!)).push({ severity, title: m[4]!.trim() }); continue; }
|
|
if (line.trim()) current = null;
|
|
}
|
|
const none = lines.some(l => l.trim() === 'No findings.');
|
|
const shapes = [...tables.map(() => 'table'), ...listBlocks.map(() => 'list'), ...(none ? ['No findings.'] : [])];
|
|
if (shapes.length === 0) return { findings: [], source: 'none', errors: [`no findings shape; expected ${RECORD_SHAPES}`] };
|
|
if (shapes.length > 1) return { findings: [], source: 'none', errors: [`more than one findings shape (${shapes.join(', ')}); keep exactly one of ${RECORD_SHAPES}`] };
|
|
if (none) return { findings: [], source: 'none', errors };
|
|
if (listBlocks.length) return { findings: listBlocks[0]!, source: 'list', errors };
|
|
const { header, rows } = tables[0]!;
|
|
const col = (re: RegExp) => header.findIndex(h => re.test(h));
|
|
const at = { sev: col(SEVERITY_HEADER), title: col(TITLE_HEADER), file: col(/^(file|location|where)$/i), fix: col(/^(fix|recommendation|remedy|resolution)$/i), id: col(/^(id|#)$/i), uc: col(/^user[ _]challenge$/i), changes: col(/^changes$/i) };
|
|
const findings: CanonicalFinding[] = [];
|
|
for (const row of rows) {
|
|
const cell = (i: number) => (i >= 0 ? (row.cells[i] ?? '').trim() : '');
|
|
const severity = severityOf(cell(at.sev).replace(/[*_`]/g, ''));
|
|
if (!severity) { errors.push(`table row ${row.n}: severity ${JSON.stringify(cell(at.sev))} is not one of ${SEVERITIES.join('|')}`); continue; }
|
|
if (!cell(at.title)) { errors.push(`table row ${row.n}: title is required`); continue; }
|
|
const f: CanonicalFinding = { severity, title: cell(at.title) };
|
|
const loc = /^`?([^`\s:]+?)(?::(\d+))?`?$/.exec(cell(at.file));
|
|
if (loc?.[1]) { f.file = loc[1]; if (loc[2]) f.line = Number(loc[2]); }
|
|
if (cell(at.fix)) f.fix = cell(at.fix);
|
|
if (cell(at.id)) f.local_id = cell(at.id);
|
|
if (/^(yes|true|y)$/i.test(cell(at.uc))) f.user_challenge = true;
|
|
if (cell(at.changes)) {
|
|
if (!(CHANGES as readonly string[]).includes(cell(at.changes).toLowerCase())) { errors.push(`table row ${row.n}: changes ${JSON.stringify(cell(at.changes))} is not one of ${CHANGES.join('|')}`); continue; }
|
|
f.changes = cell(at.changes).toLowerCase() as Changes;
|
|
}
|
|
findings.push(f);
|
|
}
|
|
return { findings, source: 'table', errors };
|
|
}
|
|
|
|
/** Run-bound findings.jsonl rows for one voice of one phase. */
|
|
export function canonicalRows(findings: CanonicalFinding[], ctx: { run: string; phase: string; voice: Voice; model?: string }): FindingRow[] {
|
|
return findings.map((f, i) => ({
|
|
schema_version: 1, run: ctx.run, id: `${ctx.run}-${ctx.phase}-${ctx.voice}-${i + 1}`, phase: ctx.phase, voice: ctx.voice,
|
|
severity: f.severity, title: f.title, disposition: 'open',
|
|
...(ctx.model ? { model: ctx.model } : {}), ...(f.file ? { file: f.file } : {}), ...(f.line !== undefined ? { line: f.line } : {}),
|
|
...(f.fix ? { resolution: f.fix } : {}), ...(f.plan_items?.length ? { plan_items: f.plan_items } : {}),
|
|
...(f.local_id ? { source: f.local_id } : {}),
|
|
...(f.user_challenge ? { user_challenge: true } : {}), ...(f.urgent ? { urgent: true } : {}),
|
|
...(f.suggested_owner ? { suggested_owner: f.suggested_owner } : {}), ...(f.dimension ? { dimension: f.dimension } : {}),
|
|
...(f.changes ? { changes: f.changes } : {}),
|
|
} as FindingRow));
|
|
}
|
|
|
|
export type ReconciliationDisposition = 'confirmed' | 'disagree' | 'new';
|
|
export interface ReconciliationRow {
|
|
outside_id: string; native_id: string | null; disposition: ReconciliationDisposition;
|
|
/** Why this disposition: the matched location or title, or the parent's override reason. */
|
|
resolution: string;
|
|
basis: 'file_line' | 'title' | 'override' | 'none';
|
|
severity: { outside: Severity; native: Severity | null };
|
|
/** A parent override's one shared proposal for both voices' user challenge; the gate renders it as option b. */
|
|
proposal?: string;
|
|
}
|
|
export interface ReconciliationOverride { outside_id: string; native_id?: string | null; disposition: ReconciliationDisposition; resolution: string; proposal?: string }
|
|
|
|
const tokens = (title: string) => new Set(title.toLowerCase().replace(/[^a-z0-9 ]+/g, ' ').split(/\s+/).filter(t => t.length > 2));
|
|
function jaccard(a: Set<string>, b: Set<string>): number {
|
|
if (!a.size || !b.size) return 0;
|
|
let inter = 0;
|
|
for (const t of a) if (b.has(t)) inter++;
|
|
return inter / (a.size + b.size - inter);
|
|
}
|
|
const level = (s: Severity) => SEVERITIES.indexOf(s);
|
|
|
|
/**
|
|
* Structural reconciliation: a file:line match (±3 lines) is `confirmed`
|
|
* unless severities differ by two or more levels (`disagree`); otherwise a
|
|
* title overlap of at least half the words is `confirmed`; else `new`. Each
|
|
* native finding is matched at most once. Overrides replace the structural
|
|
* row for their outside id and must name ids from these two lists.
|
|
*/
|
|
export function reconcile(native: FindingRow[], outside: FindingRow[], overrides: ReconciliationOverride[] = []): { rows: ReconciliationRow[]; native_only: string[]; errors: string[] } {
|
|
const errors: string[] = [];
|
|
const nativeIds = new Set(native.map(n => n.id));
|
|
const outsideIds = new Set(outside.map(o => o.id));
|
|
const byOutside = new Map<string, ReconciliationOverride>();
|
|
for (const o of overrides) {
|
|
if (!outsideIds.has(o.outside_id)) { errors.push(`override names unknown outside id ${o.outside_id}`); continue; }
|
|
if (o.native_id && !nativeIds.has(o.native_id)) { errors.push(`override for ${o.outside_id} names unknown native id ${o.native_id}`); continue; }
|
|
if (!['confirmed', 'disagree', 'new'].includes(o.disposition)) { errors.push(`override for ${o.outside_id}: disposition ${JSON.stringify(o.disposition)} is not confirmed|disagree|new`); continue; }
|
|
if (o.disposition !== 'new' && !o.native_id) { errors.push(`override for ${o.outside_id}: ${o.disposition} needs a native_id`); continue; }
|
|
if (typeof o.resolution !== 'string' || !o.resolution.trim()) { errors.push(`override for ${o.outside_id}: resolution is required`); continue; }
|
|
byOutside.set(o.outside_id, o);
|
|
}
|
|
const used = new Set<string>();
|
|
const rows: ReconciliationRow[] = [];
|
|
for (const o of outside) {
|
|
const override = byOutside.get(o.id);
|
|
if (override) {
|
|
const n = override.native_id ? native.find(x => x.id === override.native_id) : undefined;
|
|
if (n) used.add(n.id);
|
|
rows.push({ outside_id: o.id, native_id: n?.id ?? null, disposition: override.disposition, resolution: override.resolution, basis: 'override', severity: { outside: o.severity, native: n?.severity ?? null },
|
|
...(typeof override.proposal === 'string' && override.proposal.trim() ? { proposal: override.proposal.trim() } : {}) });
|
|
continue;
|
|
}
|
|
let match: FindingRow | undefined;
|
|
let basis: ReconciliationRow['basis'] = 'none';
|
|
if (o.file && o.line !== undefined) {
|
|
match = native.find(n => !used.has(n.id) && n.file === o.file && n.line !== undefined && Math.abs(n.line - o.line!) <= 3);
|
|
if (match) basis = 'file_line';
|
|
}
|
|
if (!match) {
|
|
const ot = tokens(o.title);
|
|
let best = 0;
|
|
for (const n of native) {
|
|
if (used.has(n.id)) continue;
|
|
const score = jaccard(ot, tokens(n.title));
|
|
if (score >= 0.5 && score > best) { best = score; match = n; }
|
|
}
|
|
if (match) basis = 'title';
|
|
}
|
|
if (!match) { rows.push({ outside_id: o.id, native_id: null, disposition: 'new', resolution: 'not raised by the native voice', basis: 'none', severity: { outside: o.severity, native: null } }); continue; }
|
|
used.add(match.id);
|
|
const delta = Math.abs(level(match.severity) - level(o.severity));
|
|
rows.push({
|
|
outside_id: o.id, native_id: match.id, disposition: delta >= 2 ? 'disagree' : 'confirmed',
|
|
resolution: delta >= 2 ? `severity: native ${match.severity}, outside ${o.severity} (${basis === 'file_line' ? `${o.file}:${o.line}` : 'same title'})` : `both voices (${basis === 'file_line' ? `${o.file}:${o.line}` : 'same title'}): ${match.title}`,
|
|
basis, severity: { outside: o.severity, native: match.severity },
|
|
});
|
|
}
|
|
return { rows, native_only: native.filter(n => !used.has(n.id)).map(n => n.id), errors };
|
|
}
|
|
|
|
export interface ConsensusRecord {
|
|
schema_version: 1; phase: string;
|
|
native: { model: string | null; findings: number; by_severity: Record<Severity, number> } | null;
|
|
outside: { model: string | null; provider: string | null; findings: number; by_severity: Record<Severity, number> } | null;
|
|
confirmed: number; disagree: number; new: number; native_only: number;
|
|
rows: ReconciliationRow[]; native_only_ids: string[];
|
|
/** CONFIRMED requires both voices completed. */
|
|
coverage: 'both' | 'native_only' | 'outside_only' | 'none';
|
|
}
|
|
|
|
function bySeverity(rows: FindingRow[]): Record<Severity, number> {
|
|
const out = Object.fromEntries(SEVERITIES.map(s => [s, 0])) as Record<Severity, number>;
|
|
for (const r of rows) out[r.severity]++;
|
|
return out;
|
|
}
|
|
|
|
export function consensusRecord(phase: string, native: { rows: FindingRow[]; model?: string } | null, outside: { rows: FindingRow[]; model?: string; provider?: string } | null, rec: ReturnType<typeof reconcile>): ConsensusRecord {
|
|
const rows = native && outside ? rec.rows : [];
|
|
return {
|
|
schema_version: 1, phase,
|
|
native: native ? { model: native.model ?? null, findings: native.rows.length, by_severity: bySeverity(native.rows) } : null,
|
|
outside: outside ? { model: outside.model ?? null, provider: outside.provider ?? null, findings: outside.rows.length, by_severity: bySeverity(outside.rows) } : null,
|
|
confirmed: rows.filter(r => r.disposition === 'confirmed').length, disagree: rows.filter(r => r.disposition === 'disagree').length,
|
|
new: rows.filter(r => r.disposition === 'new').length, native_only: native && outside ? rec.native_only.length : (native?.rows.length ?? 0),
|
|
rows, native_only_ids: native && outside ? rec.native_only : (native?.rows.map(r => r.id) ?? []),
|
|
coverage: native && outside ? 'both' : native ? 'native_only' : outside ? 'outside_only' : 'none',
|
|
};
|
|
}
|
|
|
|
/** The consensus table and per-finding reconciliation, rendered from canonical ids. */
|
|
export function renderConsensus(c: ConsensusRecord, findings: FindingRow[]): string {
|
|
const title = (id: string | null) => findings.find(f => f.id === id)?.title ?? '';
|
|
const nat = c.native ? `${c.native.model ?? 'unknown'}(native)` : 'native: N/A';
|
|
const out = c.outside ? `${c.outside.model ?? 'unknown'}(${c.outside.provider ?? 'outside'})` : 'outside: N/A';
|
|
const lines = [
|
|
`${c.phase.toUpperCase()} DUAL VOICES — CONSENSUS TABLE:`,
|
|
` Severity ${nat.padEnd(28)} ${out}`,
|
|
...SEVERITIES.map(s => ` ${s.padEnd(15)} ${String(c.native?.by_severity[s] ?? '—').padEnd(28)} ${c.outside?.by_severity[s] ?? '—'}`),
|
|
` Findings ${String(c.native?.findings ?? '—').padEnd(28)} ${c.outside?.findings ?? '—'}`,
|
|
c.coverage === 'both'
|
|
? `CONFIRMED ${c.confirmed} · DISAGREE ${c.disagree} · NEW (outside only) ${c.new} · native only ${c.native_only}. Both completed.`
|
|
: `Consensus: N/A (voice coverage: ${c.coverage.replace('_', ' ')}); confirmed counts require both voices.`,
|
|
'',
|
|
'Reconciliation (each outside finding against the native result):',
|
|
'| outside | native | disposition | resolution |',
|
|
'|---|---|---|---|',
|
|
...c.rows.map(r => `| ${r.outside_id} ${title(r.outside_id)} | ${r.native_id ? `${r.native_id} ${title(r.native_id)}` : '—'} | ${r.disposition} | ${r.resolution} |`),
|
|
...c.native_only_ids.map(id => `| — | ${id} ${title(id)} | native_only | not raised by the outside voice |`),
|
|
];
|
|
return lines.join('\n') + '\n';
|
|
}
|