6 Commits

Author	SHA1	Message	Date
0xdhx	0396d9cab1	enhance(#2483): stop the claude reviewer lane from inheriting CLAUDE.md + auto-memory (#2493) ... * enhance(#2483): env-guard the claude reviewer leg against CLAUDE.md injection The claude reviewer in workflows/review.md was a bare headless `claude -p` spawn run from the project cwd, so it inherited the invoking user's global CLAUDE.md, the project CLAUDE.md, and Claude Code auto-memory. That made it the only reviewer leg seeing anything beyond the prompt file. gather_context assembles PROJECT.md, the roadmap section, every PLAN file, CONTEXT.md, RESEARCH.md and REQUIREMENTS.md into the prompt before any reviewer runs; the gemini leg receives only that prompt and the codex leg runs --ephemeral. Beyond the measured ~4k tokens/spawn, the asymmetry cuts at the workflow's own premise: "independent review" meant something different for the claude leg than for the other two. Guard both dispatch lines with a per-invocation `env CLAUDE_CODE_DISABLE_CLAUDE_MDS=1`. `env`, never `export` — the flag must not leak into the orchestrating session (which may itself be Claude Code on the SELF_CLI="auto" path) or into any later spawn. review.md is the only claude -p call site in the installed tree, so this is two lines on one surface. The self-skip logic is untouched. * enhance(#2483): fix CRLF-fragile split and regenerate workflow baselines Two CI failures from the first push, both mine: 1. lint-tests: the new regression test split readFileSync content on a literal "\n". On a Windows git-autocrlf checkout that leaves a trailing "\r" on every line (local/no-crlf-fragile-split). Use .split(/\r?\n/). 2. golden-install-parity / workflow-size-budget / workflow-compat: editing gsd-core/workflows/review.md changes its content hash and byte size, and both are pinned in committed baselines. Regenerated via the repo's own generators (npm run size:baseline, npm run gen:golden). The regenerated diffs are review.md-only: exactly one hash line per golden-install-parity fixture and one size entry in workflow-size-baseline — no unrelated drift swept in. Full suite now green locally: 2113 pass, 0 fail, 3 skipped (run with HOME and CLAUDE_CONFIG_DIR overridden to throwaway dirs; live profile verified untouched afterward). * enhance(#2483): adapt guard-test matcher to the effort-args dispatch reshape The effortSurface wiring (#2481) reshaped the bare-model dispatch to `claude $CLAUDE_EFFORT_ARGS -p -`; the invocation matcher's dash-first form could no longer see it, and the count assertion failed exactly as designed. The matcher now tolerates variable expansions between `claude` and its first literal flag. Negative-controlled both ways: a stripped guard and a deleted dispatch line each still fail. * enhance(#2483): also guard the claude leg against auto-memory injection CLAUDE_CODE_DISABLE_CLAUDE_MDS suppresses CLAUDE.md file loading; auto-memory is an independently-toggled mechanism with its own flag. Add CLAUDE_CODE_DISABLE_AUTO_MEMORY=1 to both dispatch lines, correct the docs/COMMANDS.md and changeset claims that credited the first flag with covering auto-memory, and extend the regression test to require both flags on every claude invocation (negative-controlled: 2/4 assertions fail with the new flag removed). * enhance(#2483): match the claude binary in command position, not argument position The line-oriented invocation matcher counted any line where the token `claude` was followed by a flag. #2589 (landed on next as 920a5f3f) reshaped the effort-args lookup from --host claude 2>/dev/null | jq -r '.effort_argv_string // ""' to --host claude --pick effort_argv_string which put a flag immediately after `claude` and made the config query read as a third claude dispatch, failing the count assertion. The defect class is a binary name in *argument* position being read as a command. Fixed at the class rather than the instance: tokenise the line and skip any `claude` whose preceding token is a flag. That also covers the latent sibling one line away in review.md (`command -v claude`), which escaped today only because its next token is a redirect. Negative-controlled four ways: stripping CLAUDE_CODE_DISABLE_AUTO_MEMORY=1 fails, stripping the whole env guard fails, adding a genuine third unguarded dispatch (`timeout 900 claude --output-format text -p -`) still fails — so the narrowing did not blind the matcher to reshapes, which is the property the count assertion exists for — and the pre-#2589 jq form of the lookup still passes, so the matcher is not pinned to today's base. * enhance(#2483): carry the claude reviewer's memory guard as declared lane data ADR-2782 Phase 5b replaced the hand-authored per-CLI dispatch legs in review.md with the declared lane table, so the two `env`-prefixed shell lines this PR previously added no longer have a surface to live on. The guard is reimplemented where the lane contract now lives. `SpawnInvoke` gains an optional `env`, the claude lane declares the pair, the resolver folds own string-valued entries into `SpawnPlan.env` (absent or empty resolves to null, so the runner has one shape to test), and the runner passes it to spawn. Production merges it OVER `process.env` into a fresh object for that one child, so nothing reaches the orchestrating session or any other lane in the run. Declared data rather than a handler (D6): the pairs are static per lane, which is precisely what the manifest vocabulary is for. The capability manifest carries the same field, because the lane-fidelity test compares manifest and descriptor over the union of `invoke`'s keys. The regression test is rewritten against the resolver and runner rather than review.md's text. It gains the property the source-text assertions could only approximate: that `process.env` is never mutated. Scope boundary, asserted rather than left in prose: `env` is not part of the trust-disclosure surface, which is safe only while no manifest body reaches the resolver — the registry's reviewer bodies contribute slugs to the parity check and execution resolves from `REVIEWER_LANES`. The new test fails first if that ever changes. * enhance(#2483): restate the guard's mechanism in the docs and changeset Both described the fix as two `env`-prefixed dispatch lines, which is the surface ADR-2782 Phase 5b removed. The user-visible behaviour is unchanged; the carrier is not, and a changeset that ships a description of a mechanism the tree does not have is a CHANGELOG entry nobody can verify against the code. * enhance(#2483): cover the production spawn wiring end to end The unit tests stop at the runner's `deps.spawn` seam — every one injects a spy. Production supplies that seam in `gsd-core/bin/gsd-tools.cjs` as a hand-written object no test constructs, so the chain could be correct all the way to `SpawnPlan.env` and the merge could still be wrong or absent with the suite green. Deleting those four lines was the one mutation that left every other control silent. This runs the real `spawnSync` through `gsd-tools review-lane invoke`, with a `claude` shim on PATH that records the environment it was handed. It asserts both halves in one test: the pair arrives, and an unrelated inherited variable survives — a wiring that REPLACED the environment rather than merging over it would satisfy the first and break every lane's PATH and HOME. POSIX-only; mediating a Windows `.cmd` shim is a separate concern the repo already tests on its own. Noted rather than fixed: `timeout`, `killSignal`, `maxBuffer` and `shell: false` on that same object are equally uncovered. That is the epic's gap, not this change's, and closing it is not in scope here. * enhance(#2483): validate the invoke.env shape and register it as spawn-only `env` was the one spawn-invoke field with no shape enforcement: every sibling in `validateSpawnInvoke` is checked, and a manifest declaring `env` as an array, a string, a number, or an object with non-string values passed validation in silence. That matters more than an ordinary schema gap here, because `resolveLanePlan` DROPS a non-string value rather than coercing it — so an unvalidated manifest declares a pair that never reaches the spawn, which is the failure a memory guard can least afford. Two registrations, not one. `env` was also absent from `SPAWN_ONLY_INVOKE_FIELDS`, which is the list the openai-http arm rejects against — so `invoke.env` was accepted on a transport that issues an HTTP POST and has no child environment at all. It was the only spawn-shaped field accepted there; the other six each produce two errors. Self-found while sweeping the class, not raised in review. Keys are held to the portable POSIX environment-name grammar. That is a policy, not a claim about what an environment can hold: measured, only NUL is actually rejected by `spawnSync`, while `=`, a leading digit, a dash and a space are all carried through to the child (an `A=B` key arrives as the raw entry `A=B=value`). They are refused because a name outside the grammar is not portably addressable by the program meant to read it. `__proto__` is refused for a different and concrete reason. It passes that grammar and is a real own key once a manifest is JSON-parsed, but assigning it onto a plain accumulator goes through the inherited `__proto__` setter rather than creating an own property — and for the string values this field permits the setter is a no-op that does not even change the prototype. The pair would validate and then simply vanish before the spawn. (An environment CAN carry a literal `__proto__` entry; this is about the resolver's accumulator, and the error message says so.) Deliberately narrower than the sibling reserved-name guards in this file, which also reject `constructor`/`prototype`: those guard bracket lookups that resolve prototype members, whereas this reads via `Object.keys` plus an own-value read, where `constructor` assigns as an ordinary key the spawn could carry. `effortChannel` is deliberately left in neither field list: ADR-2782 D2 defines it for both transports, so it is shared rather than spawn-only. Reversion-controlled, three mutations, all three fire a named test: dropping `env` from the discriminator fails `httpTransportRejectsEnv`; removing the `__proto__` arm fails `envRejectsProtoKeyThatWouldSilentlyVanish`; disabling the block fails four. (#2483) * enhance(#2483): amend ADR-2782 D2 for the invoke.env vocabulary widening D2 records the spawn `invoke` shape as a closed vocabulary, and its Amendments section carries a dated entry for every prior widening (Phase 1 #2794, Phase 2 corrections #2795, Phase 5b #2799). This change extended that vocabulary in code without touching the ADR governing it, so the ADR contradicted the implementation — and the repo's own convention, recorded in CONTEXT.md, is that the ADR is amended in the same PR precisely because the prior widenings did it correctly. Adds the `invoke.env` row to the D2 table and a dated Amendments entry. The entry also corrects the authority this change cited. The source comment pointed at D6, which governs the closed `handler` enum — imperative behavior admitted first-party — and says nothing about the `invoke` field vocabulary. That is D2's territory, so the citation never covered the gap. Two claims are corrected rather than restated, both about the trust boundary that justifies leaving `env` out of the D5 disclosure signature: - The regression test does not enforce that boundary. On one forged lane it shows the resolver folds whatever it is handed, so a future path feeding it manifest lanes would not make any assertion in that test fail. Its comment claimed it "will fail first"; that was wrong, and both the comment and the ADR now say the boundary is a property of the production call chain instead. - The ADR is internally inconsistent on whether third-party manifest lanes execute at all: Consequences says adding a reviewer needs "no core patch", while `gsd-tools.cjs` rejects every slug absent from the first-party REVIEWER_LANES map. CONTEXT.md, `workflows/review.md` and the resolver's own header take the first view. #2483 did not create that inconsistency and does not resolve it; the entry records it rather than settling it in its own favour. (#2483) * enhance(#2483): document invoke.env in the capability-manifest reference ADR-2782 points capability and plugin authors at `docs/reference/capability-manifest.md` as where the lane vocabulary must be visible, and its `invoke` row enumerates the spawn sub-shape field by field. `env` was absent from that table while being part of the real shape, so the one document a third-party capability author would actually consult to learn the field exists did not mention it. Squarely Diataxis reference material — a field-by-field schema description — so it goes here rather than in the user-facing prose, which was already updated. States the constraints a manifest author can actually trip, and is explicit that the name grammar is a portability policy rather than an OS limit, so a reader does not take it for a claim about what an environment can hold. (#2483) * enhance(#2483): disclose and sign the reviewer lane's env and residual invoke fields `invoke.env` was undisclosed at install time. That was defensible while manifest lanes could not execute — the premise this PR's own ADR amendment recorded — and #2927/#3062 retired it: `routeReviewLane` now merges installed overlay `reviewer` bodies into its lane map via `mergeReviewerLanes`, which is a field-identical merge by ADR-2782 D1 and deliberately does not deep-validate. An overlay's whole `invoke` therefore reaches `resolveLanePlan`, and `env` reaches the spawned child. A consented third-party capability could set `NODE_OPTIONS=--require ./evil.js` on a reviewer lane with no install-time disclosure and no re-consent. The same file already decided what `env` means in a manifest: MCP servers fold it into the disclosure signature and render each key and value in the consent prompt, with an inline rationale naming this exact shape. Reviewer lanes get the identical treatment. `env` was the ninth unsigned invoke field, not the first. `defaultHost` (the manifest's OWN fallback egress host, used whenever the config key resolves to nothing), `path`, `outputChannel`/`outputArg`, `modelArg`, `effortChannel` and `modelDiscovery` all reach `resolveLanePlan` and none was bound. Enumerating a ninth name leaves the tenth open, so the lane signature carries a RESIDUAL of every other declared `invoke` key — the completeness backstop `rawConfig` already gives the MCP line (#1459 finding 5), and the "sign the whole object" remedy the recorded decision on this class prefers. `defaultHost` is also rendered: `resolvedHost` comes from user config, so a lane whose key is unset displayed "(unresolved …)" — which reads as "no destination" — while the runtime egresses the plan and review text to the address the manifest picked. D4.5 is preserved one level down: the extra element is appended ONLY when the lane declares something beyond the eight already-bound fields, so an env-free lane's signature stays byte-identical and no already-consented capability is re-prompted for a field it does not use. A lane that does declare one re-consents, which is the point. Execution-primitive env names are FLAGGED in the prompt, not refused in the validator. A denylist cannot be the boundary here: `PATH` alone is a complete execution primitive for a spawn lane and can never be refused, the child is an arbitrary third-party binary so the true set spans every interpreter's injection vars, and the MCP `env` this mirrors refuses nothing and discloses everything. Missing a name costs a quieter line, never a boundary. Refs #2483. * enhance(#2483): exercise the real overlay merge path in the guard test The test named for the manifest/first-party boundary did not test it. It built a forged lane locally, handed it straight to `resolveLanePlan`, and asserted that `REVIEWER_LANES` did not contain it — so no assertion in it depended on the claim its name made, and a code path that fed manifest lanes to the resolver would not have made it fail. Its own comment said as much, and named the production chain as the real carrier of the guarantee: "gsd-tools.cjs builds its lane map solely from REVIEWER_LANES". That sentence is now false. #3062 merged overlay reviewer bodies into that map, so the test's premise and its subject both moved. The replacement routes through `mergeReviewerLanes` — the real helper the production path calls — and asserts the overlay lane is admitted, resolves, and carries its `env` into `SpawnPlan.env`. That makes the security property falsifiable instead of narrated. It then asserts what now backs it: the env is disclosed on the surface, rendered key and value in the consent prompt, flagged when the name is an execution primitive, and bound to the signature so a value change, an addition, or a removal each force re-consent. Three further cases, because the finding's generative half is what stops it recurring: the residual backstop is asserted against five fields including one that does not exist (`aFieldThatDoesNotExistYet`), so a future vocabulary widening cannot silently re-open this; a fully-enumerated lane is pinned to its original 8-tuple, which is what keeps the fix from re-prompting every consented capability; and an http lane's manifest-declared `defaultHost` is asserted to reach both the prompt and the signature. Reversion-controlled, seven mutations, all seven fail a named test: env dropped from the surface, the prompt's env line removed, the execution-primitive warning removed, the signature's extra element never appended, the residual emptied, the defaultHost line removed, and the declares-something test un-widened. The last of those was SILENT on its first run and its test was written in response, then the control re-run. Refs #2483. * enhance(#2483): correct the ADR amendment's manifest-lane premise The amendment argued `env` needed no D5 disclosure because a manifest's `invoke` fields never reach `resolveLanePlan`. That was true when written and #3062 retired it 22 hours after this branch's last commit: `routeReviewLane` now builds its lane map from `mergeReviewerLanes(REVIEWER_LANES, loadRegistry({includeInstalled: true}))`, and D1's no-translation-layer rule makes that a field-identical merge, so an overlay's whole `invoke` reaches the resolver and executes. The entry had named this exact trigger — "were manifest lanes ever made executable, `env` must join the disclosed surface in that change, and nothing here will trip if it does not." Nothing tripped. The premise is rewritten to current truth rather than annotated, because an ADR is read in fragments and a superseded paragraph left standing reads as live reasoning to the next author; a one-line dated tombstone points at git for the withdrawn text. The rewritten entry records four things the first draft could not: that the enumeration itself was the defect (`env` was the ninth unbound `invoke` field, and `defaultHost` and `path` are egress-relevant on their own), that the residual is what closes the class, that D4.5's byte-identical-signature property is preserved by appending the residual only when a lane declares something beyond the eight bound fields, and that consent — not shape validation — is the boundary, since no honest env denylist can exclude `PATH`. It also closes the internal inconsistency the previous entry could only record. This ADR, `CONTEXT.md`, `gsd-core/workflows/review.md` and `resolveLanePlan`'s own header all said overlay lanes reach the resolver while the runtime said otherwise; #3062 resolved that in the documents' favour, which is what makes the disclosure mandatory rather than defensive. Refs #2483. * enhance(#2483): record in the manifest reference that invoke fields are consent-bound `docs/reference/capability-manifest.md` is the field table ADR-2782 points capability authors at, and it described `invoke` purely as a schema. A third-party author reading it could not learn that everything they declare there is shown to the user at install and bound to the consent signature — which is exactly what they need to know now that an overlay reviewer lane executes (#2927/#3062). States the two things the schema alone cannot: that `env` and `defaultHost` are named in the consent prompt and the rest is covered by a residual, so any change to a declared `invoke` field forces re-consent; and that `env`'s validation is a portability policy rather than a safety boundary, since `PATH` is a complete execution primitive and cannot be refused. Names that are execution primitives are highlighted in the prompt instead. Refs #2483. * enhance(#2483): add a Security changeset for the reviewer-lane disclosure The existing fragment describes the enhancement this PR was opened for and stays as it is. The disclosure fix is a separate user-visible change of a different type: a capability declaring `invoke.env` or `invoke.defaultHost` will ask for consent once more, and users are entitled to read why in the changelog rather than discover it as an unexplained prompt. Type is `Security` rather than `Changed` because the entry describes a closed code-execution disclosure gap, not a behaviour adjustment. Refs #2483. * enhance(#2483): correct this round's own claim about who gets re-prompted Self-found while auditing the round's claims before publishing them. The changeset and the ADR entry both stated that a capability declaring `invoke.env` or `defaultHost` "will ask for consent once more". That is wrong, and it overstated the cost of the fix in the one direction a maintainer would have had to take on trust. A code change to `disclosureSignature` re-prompts nobody. `hasProjectConsent` matches on the recomputed bundle `contentHash` — the signature has not been the security binding since #1459 CB-1/CB-2 — and the upgrade path's `executableSetChanged(old, new)` compares two disclosures both computed by the CURRENT code, so widening the signature moves both sides of that comparison equally. First-party capabilities never reach the path at all: the install flow blocks a first-party id before trust evaluation. What the widening actually buys is forward-looking, and is the real argument for it: an upgrade whose manifest edits a declared `invoke` field now registers as an executable-surface change and re-consents, where before it could change what the lane runs in silence. Also measured and recorded, because the D4.5 property was stated more strongly than it deserved: of the twelve first-party reviewer capabilities, ZERO are in the byte-identical-signature class — every real lane declares at least `effortChannel`. The property is a guarantee about minimal lanes, not a description of the fleet, and the ADR now says so. Refs #2483. * enhance(#2483): sign and disclose the probe binary and the lane's outer fields Found by this round's own adversarial review, and it is the same defect one level out: the `invoke` residual cannot reach the lane body's OUTER fields, and `probeLane` SPAWNS `probe.binary` with `--help` before dispatch (`review-lane-runner.cts`, the `command-exists`/`command-capability` arms). An overlay naming an arbitrary probe binary therefore executes it — unsigned and undisclosed, exactly as `invoke.env` was, and reachable on the same #3062 path. The lane element now carries a second residual over the outer fields, and the probe binary is shown in the consent prompt when it differs from the dispatch binary — it is a program that runs, and the user is entitled to see it. TWO fields stay excluded, and that is a decision rather than an omission: `reviewsSection` and `timeoutFloorMs` are ADR-2782's cosmetic carve-outs (matrix A10/A13), where re-consenting would present a prompt carrying no security information. A test pins that they remain excluded, so a later widening cannot quietly reverse D4.5 while claiming to complete this fix. Also corrects a miscount introduced by the previous commit: the source comment said the enumeration had fallen behind by "seven fields" and omitted `fallbackModel`, while asserting `env` was the ninth. `resolveLanePlan` reads twelve `inv.*` fields and four were bound, so the number is eight. The comment now states the derivation rather than just the total. Reversion-controlled: emptying the outer residual fails "repointing the probe binary must force re-consent"; removing the render line fails its own named assertion. Refs #2483. * enhance(#2483): refuse execution-primitive env names as defence in depth Adopts the review's B5 after this round's own adversarial pass refuted my reason for declining it. I had argued a denylist was worthless because `PATH` can never be refused. That was wrong on the facts: no shipped reviewer manifest declares `PATH`, so it can be refused, and it is the most complete primitive in the set — repoint it at a directory holding a fake binary and the declared `invoke.binary` is irrelevant. A list that cannot be exhaustive can still close the highest-confidence, lowest-legitimacy routes. So the validator now rejects `PATH`, `NODE_OPTIONS`, `LD_PRELOAD`, `DYLD_INSERT_LIBRARIES`, `BASH_ENV`, `PYTHONPATH`, `PERL5OPT`, `RUBYOPT`, `GIT_SSH_COMMAND`, `JAVA_TOOL_OPTIONS` and their siblings on a reviewer lane. A lane needing a specific executable declares an absolute `invoke.binary` instead of reshaping the child's environment. The comment states plainly that this is defence in depth and NOT the boundary — the boundary is install-time consent, which discloses every declared pair and binds it to the signature, so an unlisted name is still SEEN before it runs. That framing is load-bearing: a future reader who mistakes the denylist for the control will under-invest in the one that is, which is the failure mode I was trying to avoid by declining it outright. Two tests: the rejection itself across ten names, and a guard asserting no shipped reviewer capability declares a denied key — so if the list ever outgrows its evidence, that surfaces as a decision rather than a silent removal. Refs #2483. * enhance(#2483): fix two stale D5 enumerations elsewhere in the ADR The previous commit rewrote the amendment's premise but swept only the amendment. Two normative passages earlier in the same ADR still enumerated the old closed field list and now contradicted it: the `executableSetChanged` trigger list, and the split-binding note asserting the seven manifest-derived fields were "everything that is SHA-pinned". That is the failure the rewrite-don't-annotate rule exists to prevent, one section over — an ADR is read in fragments, and a fragment carries no supersession marker, so a reader landing on either passage would have taken the superseded enumeration as current. Both now name the residual as the mechanism rather than restating a list, which is also what stops them going stale the next time the vocabulary widens. Found by this round's adversarial review, which grepped the whole document rather than the section under edit. Refs #2483. * enhance(#2483): stop the probe disclosure claiming a spawn that does not happen The probe line added one commit ago rendered "probes by running: <binary> --help" for every lane. That is false for `kind: "command-exists"`, which only calls `hasBinary` — a PATH/filesystem scan that starts no process. Only `command-capability` spawns. A false statement in a consent prompt is worse than a missing one: the prompt is the surface a user is asked to trust, and this one overstated what a lane does. Worse, the test I wrote to prove the fix used `command-exists` — the kind that does NOT spawn — so it pinned the wrong claim and would have kept the error green forever. The surface now carries `probeKind` and the two kinds render differently: a spawn is described as a spawn, a presence check as a presence check. The test exercises both, and asserts the `command-exists` path never emits the spawn wording. Also corrects the field-count parenthetical to state its derivation unambiguously — `resolveLanePlan` reads thirteen `inv.*` fields including `env` (twelve before this PR), four were bound, so eight were unbound before `env` and nine including it. The bare "twelve" was true only of the pre-PR tree and read as a claim about the current one. And retires two comments that argued AGAINST the validator denylist this round then shipped. Leaving them would have handed the next reader the reasoning for removing it. Reversion-controlled: conflating the two probe kinds fails a named test. Refs #2483. * enhance(#2483): match the reviewer-lane env denylist case-insensitively The denylist added one commit ago compared exact case, so `Path`, `path`, `node_options` and `Node_Options` all passed it. Windows environment lookup is case-insensitive, so those reach the child as `PATH` and `NODE_OPTIONS` — the exact inputs the list names. An exactly-cased denylist is worse than none: it reads as a control while admitting the input it was written to refuse, and the next reader has no reason to doubt it. Members are stored uppercase and the key is folded before lookup; the name grammar already constrains keys to ASCII, so a plain fold is sufficient. Reversion-controlled: restoring the exact-case compare fails `envDenylistIsCaseInsensitive` on `Path`. Refs #2483. * enhance(#2483): correct the docs that still described the denylist as absent Both the ADR and the manifest reference still said `env` carries no denylist and that `PATH` "can never be refused" — written when that was this round's position, and left standing after the round reversed it. A reader landing on either passage would have taken the superseded argument as current, which is precisely the failure the rewrite-don't- annotate rule exists to prevent. Both now describe the denylist, name `PATH`'s inclusion and the case-insensitive match, and keep the limit explicit: the list cannot be complete against an arbitrary child and disclosure runs before validation, so consent remains the boundary. The ADR's byte-identical-signature claim is also corrected rather than softened. With the outer residual in place, a lane producing no residual is one the validator rejects — it declares no `flags`, `probe`, `emptyOutput`, `evidenceClass`, `requiresBinaries` or `promptBudgetKey`. So the property is about the ENCODING, not a claim that any real signature is unchanged, and it is not the argument for the change being safe. That argument is that consent binds to the bundle contentHash and no existing consent is invalidated at all. Refs #2483. * test(#2483): cover the three new lane disclosure fields in the injection-safety parity guard The PARITY test in section N exists to catch a renderer field that skips `renderValueForPrompt` (#3248). Its payload manifest is hand-maintained, so it covers the fields that existed when it was written — slug, binary, args, hostConfigKey, handler — and none of the fields this PR adds. This PR renders three further manifest-supplied values into consent-prompt lines: `invoke.env` (keys and values), `invoke.defaultHost` and `probe.binary`. The gap was silent rather than theoretical: with the lane env line reverted to the pre-#3248 raw form, the whole 948-test lane/capability/trust-disclosure suite stayed green. Two manifests, because the shapes render disjoint lines — `defaultHost` only on the openai-http branch, `env`/`probe` only where declared, and the probe line only when the probe binary differs from the dispatch binary. Non-vacuity is asserted on the typed disclosure object and on structural line counts, not by substring-matching rendered prose: CONTRIBUTING.md forbids raw text matching on test output, and this section's own header promises structural assertions only, so a prose match here would have made that promise false. Negative-controlled three ways against the merged tree, each producing exactly one named failure: env rendered raw, defaultHost rendered raw, probe binary rendered raw. * docs(#2483): extend the #3248 render-site comment to the fields this PR adds The comment enumerates every manifest-supplied value that must pass through `renderValueForPrompt`, and it stopped at `handler` — the reviewer-lane fields that existed when #3248 landed. This PR renders three more (`defaultHost`, the probe binary, and the env keys and values), so the list understated its own contract in the one place a future author would check before adding a fourth. A comment enumerating a closed set is a set that can silently fall behind the code it describes; the parity test added alongside is what makes the omission fail loudly rather than read as deliberate. --------- Co-authored-by: Tom Boucher <trekkie@nomorestars.com>	2026-08-11 17:42:41 -04:00
Tom Boucher	3f6b063fbb	chore(#2799): invoke_reviewers and write_reviews iterate declared lanes (#2861) ... * chore(#2799): resolve reviewer lanes into executable invocation plans Phase 5b of ADR-2782. Adds the resolver and runner that let invoke_reviewers iterate declared lanes instead of hand-authored per-CLI bash. Five additive descriptor amendments, each forced by a lane that ships today: - LaneHandler gains 'opencode' — the lane rebuilds its review from assistant text parts of a --format json stream; a plain stdout copy re-breaks #1936. - modelConfigKey — antigravity's key is review.models.agy, not .antigravity, so resolving by slug silently dropped a configured model. - defaultHost/fallbackModel — Phase 4 federated every *_host with a default of empty string; the real fallback only existed in the bash. - args becomes an argv template with a closed four-placeholder vocabulary. Positional splicing produced 'codex --model M -o F exec --ephemeral', which is not a valid invocation: codex injects in the middle, twice. - kimi-code lane, with the bounded command-capability probe (needle --output-format) that tells Kimi Code from the legacy python kimi-cli. Parity gate re-pointed: the workflow-text families it scanned are the text this phase deletes, so they are replaced by descriptor-to-registry parity plus an anti-parity check that no bespoke leg returns. jq, curl and external timeout/gtimeout all drop out of the review path. Refs #2782 * chore(#2799): add review-lane query surface and widen the manifest vocabulary Adds the gsd-tools 'review-lane' route (plan/invoke/sections) the workflow loops over, projects all twelve lanes into their capability manifests, and widens capability-validator for the amendments. opencode admitted to VALID_LANE_HANDLERS under the second arm of the enum's own admission rule: one lane, justified by a documented upstream defect data cannot express (#1936 — the agent can end its turn with zero output tokens and --format default then drops the assistant text entirely). Two bugs caught by an end-to-end stub run and fixed here: - loadConfigResolved returns a provenance wrapper, not the config; using it directly resolved every key to undefined, which reads as 'nothing configured' and silently dropped every model override. - hasBinary used shell:true with an args array (Node 26 DEP0190). Replaced with a PATH scan that spawns nothing at all. Refs #2782 * chore(#2799): iterate declared lanes in invoke_reviewers and write_reviews Replaces the eleven hand-authored per-CLI bash legs with a loop over resolved lanes, and renders REVIEWS.md sections from each lane's declared reviewsSection instead of thirteen hardcoded headings. review.md drops from 1104 lines to 507 (61KB to 28.7KB). Parity gate re-pointed, as agreed: the leg-marker and section-heading families scanned exactly the text this phase deletes, so they are replaced by descriptor-to-registry parity in both directions, plus an anti-parity check that fires if a bespoke leg is ever re-added. Enum, emitting sites and the Object.keys lock moved together. The budget-trim helper is hoisted out of the Ollama leg: it was always lane-agnostic, and any lane may now declare a promptBudgetKey. Refs #2782 * feat(#2799): bind the consented egress host and re-verify it at invocation Completes ADR-2782 D5. Rule 1 was recorded in the ADR as delivered by Phase 3 but was not implemented: ConsentRecord had no host field and nothing in the tree bound one, so this phase's rule-4 comparison had no baseline. ConsentRecord gains an OPTIONAL reviewerHost. Optional is the whole design: isValidConsentRecord does not require it, so every record already on disk stays valid and no re-consent storm fires (D4 rule 5). It is deliberately excluded from disclosureSignature — the loader has no config resolver, so folding a config-derived value in would make loader and lifecycle compute different signatures for the same manifest and re-prompt forever. Install resolves hostConfigKey (falling back to the lane's declared defaultHost, which is what the invocation path uses) and records it. Invocation re-resolves and blocks on mismatch rather than silently redirecting. Absence allows: no record, or a record predating the field, means nothing to compare — denying there would break every existing local-model user on upgrade. Refs #2782 * test(#2799): cover the resolver, runner and handlers; retarget the parity suites Adds the golden invocation-plan table (one row per shipped lane, derived from the bash legs rather than the descriptor types) plus runner coverage for the probe, empty-output policy, the three handlers and the egress check. Retargets the existing suites onto the new contract: descriptor-to-registry parity, the anti-parity check, the opencode handler, and the twelfth lane. Two corrections found by running them: - modelConfigKey was required; that breaks D4 rule 2, since a reviewer manifest authored before this phase would fail validation on upgrade. It is optional, read as null when absent. - the antigravity non-zero-exit test pre-seeded the transcript, which asserted that a STALE entry leaks through — the exact bug the watermark prevents. The spawn now appends, as the real tool does. Refs #2782 * fix(#2799): restore agy --add-dir and the self-report prompt in the handler Retargeting the three legacy reviewer suites off the deleted bash surfaced two real regressions in the port, both #2176: - --add-dir was dropped. Without it agy's permission context never receives the cwd repo, so the agent anchors on its own scratch dir and reviews the plan text in isolation — the exact failure the Review Instructions forbid. It is capability-probed, because an older agy rejects the unknown flag outright and a lane that fails to start is worse than one running on the prompt anchor. - the prompt lost the clause mandating a REVIEWED-WITHOUT-REPO-ACCESS self-report, which is what makes a blind review distinguishable from a grounded one. antigravity now builds its own prompt variant. Also ports the #2073 mode-2 cli.log diagnostic, which was dropped: a pinned model that 404s exits 0 with empty stdout AND an empty transcript, so agy's own log is the only evidence that anything failed. The three suites now assert against the plan and the handler instead of matching fence text, so they no longer need allow-test-rule exemptions. Refs #2782 * docs(#2799): document the declared lanes, the new flag, and dropped prerequisites COMMANDS.md gains --kimi-code and replaces the jq-prerequisite paragraph, which is now false: no lane requires jq, curl or an external timeout. Adds the changed-egress-destination behavior, since a blocked lane is something a user can hit. CONFIGURATION.md records that the model config key is declared per lane rather than derived from the flag — antigravity's is review.models.agy — and adds review.models.kimi-code. reviewer-instances.md now routes an instance through its lane's single invocation seam instead of a copied per-adapter bash block, which is what lets a cross-cutting fix reach instances for free. That required implementing the --model/--agent/--as flags it documents; --model re-resolves through the lane's argv template rather than splicing, so the flag lands where the lane declares it rather than ahead of a subcommand. CONTEXT.md glossary gains both new modules. Refs #2782 * chore(#2799): drop the stale emitted-drift acknowledgment The only entry was #2797's, acknowledging COMMENT-ONLY GROWTH in review.md. That file now shrinks by ~32KB and every emitted hash that moved is attributable to this diff, so the ack no longer explains anything. Removing the last entry means removing the file: its presence is the alarm, and an empty one signals nothing. Verified by deleting it and re-running the attribution and provenance gates plus lint:ci — all green without it. Refs #2782 * docs(#2799): record the Phase 5b vocabulary widenings in ADR-2782 Five additive amendments, each forced by a lane that ships today, plus two corrections the phase had to make rather than work around: - D5 rule 1 was recorded as delivered by Phase 3 and was not implemented, so this phase's rule-4 comparison had no baseline. Recorded because an ADR asserting a rule was delivered is exactly what stops a later phase checking. - The DEFECT.GENERATIVE-FIX gate is re-pointed: its workflow-text families scanned the text this phase deletes. Also records that D7's 'skip the probe where no bounding mechanism exists' carve-out is obsolete — in practice it meant the Antigravity lane ran unbounded on every stock macOS host, which ships neither timeout nor gtimeout. Refs #2782 * fix(#2799): close four defects found by adversarial review Two confirmed bugs, both reproduced before fixing: - resolveLanePlan was not total. An openai-http lane with a missing or non-object invoke dereferenced inv.hostConfigKey and threw, contradicting the module's own documented contract; the spawn branch guarded correctly and the http branch did not. The CLI seam resolves every selected lane in one map, so one malformed overlay manifest would have aborted the whole review rather than dropping its own lane. Guarded, plus a per-lane try/catch at the seam so a throw can never take down siblings. - A reviewer-instance model was silently dropped for any lane declaring modelConfigKey null (cursor, qwen, coderabbit). reviewer_instances validates that cli is a known slug but never that the slug accepts a model, so a user could configure one, get a clean run, and never learn a different model reviewed their plan. Now warns explicitly. Two hardening fixes: - The slug is concatenated into artifact paths, so LANE_SLUG_RE is enforced in the resolver rather than inherited from a validator that does not run on this path — the module documents itself as the overlay-manifest trust boundary, so it should not depend on someone else having checked. - normalizeHost mangled a scheme-less value: new URL('localhost:11434') parses with an empty hostname, so it became 'localhost://11434' and was compared and requested as if real. An empty hostname now means not-a-URL. Also documents the one gap that cannot be closed here: the antigravity watermark is keyed by workspace, so two concurrent reviews of the same repo share a transcript. agy exposes no per-invocation id to filter on, so the handler now states which half of its never-stale guarantee actually holds. Refs #2782 * test(#2799): retarget the remaining eight review.md-asserting suites The remote runner found 37 failures the local sweep missed (it hit the shell's two-minute cap before reaching these). All eight extract per-CLI bash from review.md that this phase deletes; each protects a real invariant, so each is retargeted onto the plan, the runner or the handler rather than removed. Three real defects surfaced by doing so: - effort args never reached ANY lane. model-resolver.cjs exports no resolveExecution, so effortFor silently returned [] every time. Restored by calling the same bounded resolve-execution query the bash legs used — and NOT with --raw, which prints the resolved effort rather than the picked field, so claude got 'low' instead of '--effort low'. - the timeout guidance lost 'a silent empty output is a timeout kill, not a crash' — the operator note that exists because of the Codex 0xc0000142 misdiagnosis. Restored. - the opencode handler dropped EMPTY assistant text parts. The shipped jq was , and only substitutes for false/null — an empty string is truthy in jq and contributed a blank line. Found by a property test shrinking to ['', '']. The opencode property suite no longer spawns jq at all, which deletes the #2099 hang mechanism it was architected around rather than mitigating it. Refs #2782 * fix(#2799): register the two new generated modules, and untrack them The remote runner caught build output committed to git. Both new modules compile from src/*.cts into gsd-core/bin/lib/*.cjs, and every sibling generated that way is gitignored and eslint-ignored (ADR-457) - including Phase 1's own review-lane-descriptor.cjs. Mine were neither, so repo-invariants' "each bin/lib/*.cjs is linted xor ignored according to migration state" failed. Registered both in .gitignore and eslint.config.mjs alongside the Phase 1 module, and dropped them from the index. Nothing about the shipped behaviour changes; the artifacts are rebuilt by build:lib. This is the new-.cts-module registration ripple, and it is the one part of it I had not completed - the CONTEXT.md glossary and the inventory manifest were already done. Refs #2782 * chore(#2799): backfill changeset pr number to 2861 * chore(#2799): backfill changeset pr number to 2861 --------- Co-authored-by: Test <test@example.com>	2026-07-30 12:48:06 -04:00
Tom Boucher	6a9babda69	chore(#2798): declare the eleven reviewer lanes as manifest data (#2837) ... * chore(#2798): declare the eleven reviewer lanes as manifest data Phase 5a of epic #2782, delivering ADR-2782 D9 (roster half) and D3. - Five reviewers GSD never installs into become lane-only role:reviewer capabilities with no runtime body, no runtimeCompat and no install surface: gemini, coderabbit, ollama, lm-studio, llama-cpp. Before this they had no descriptor at all and lived as a hardcoded NON_RUNTIME_REVIEWER_SLUGS tail, which is now deleted outright. - The six hosts that are ALSO reviewers gain a reviewer body alongside their runtime body. Their runtime bodies are byte-identical to next -- verified per capability against the git blob, not asserted -- so no install behaviour moves. - KNOWN_REVIEWER_SLUGS derives from declared bodies via an exported deriveReviewerSlugs(registry). hostBehaviors.reviewerCli survives as a derived legacy alias for one release; where a capability carries both, the body wins and the slug appears once. Alias removal is Phase 7 (#2801). THE KEYSTONE: the roster is the SAME ELEVEN SLUGS as before -- antigravity, claude, coderabbit, codex, cursor, gemini, llama_cpp, lm_studio, ollama, opencode, qwen. This phase changes HOW the roster is derived, not WHO is in it, and the test asserts that literal list rather than a count. kimi-code is deliberately NOT declared here. It is net-new with no invoke_reviewers leg, so declaring it now would make it selectable but not invocable -- present in --all, selected, emitting an empty section for the whole 5a-to-5b window -- and would break Phase 1's parity assertion. It lands in 5b alongside the iteration that can run it. Legacy kimi (the Python CLI) is not a reviewer at all and gains nothing. The highest-value test is declaredManifestLanesMatchThePhase1Descriptor: it deep-compares all eleven declared bodies against REVIEWER_LANES field-by-field, including probe and invoke sub-fields. All eleven are byte-identical, key order included. The epic's premise is that the manifest and the core descriptor describe the same lane with NO translation layer, and Phase 2's review already caught one divergence that every other test missed. Two ADR corrections folded in, as Phases 1-3 each did: 1. PHASE ORDER. The ADR runs Phase 4 (federated config) before 5a and #2798 claims a dependency on 4. That is inverted and makes Phase 4 unsatisfiable: D9 assigns review.<host>_host to lane capabilities that do not exist until THIS phase creates them, and a federated config slice must live inside capabilities/<id>/capability.json. Real graph: Phase 2 -> 5a -> 4. 2. #2798's INVENTORY acceptance item is vacuous. The inventory catalogs bin/lib/*.cjs modules, not capability directories -- antigravity, opencode and qwen appear zero times in it -- and gen-inventory-manifest --check passes with the five new dirs and no edit. Also corrected a stale line in Phase 2's own ADR amendment: it recorded the slug pattern as /^[a-z][a-z0-9_-]*$/, but Phase 2's security review widened the shipped pattern to /^[a-z0-9][a-z0-9_-]*$/ to match Phase 1's exported LANE_SLUG_RE. The prose had not followed the code. Closes #2798 * fix(#2798): catalogue reviewer capabilities in the generated matrix The capability matrix rendered exactly two tables, feature and runtime, via renderTable(caps, role) filtering on c.role === role. ADR-2782 D3 added a THIRD role, so every role:"reviewer" capability was silently dropped from the first-party catalogue. The drift guard did not catch it, and could not: --check compares generated output against the committed file, and both omitted the five lanes identically, so it reported "up to date" while five shipped capabilities were invisible in the one document that is supposed to list what ships. A guard blind to an entire role is not guarding. This phase is what exposed it -- it ships the first role:"reviewer" capabilities -- so it is fixed here rather than deferred (CLAUDE.md: a defect found while working is fixed in the current change, which overrides one-concern-per-PR). Verified red-before-green: with a lane row deleted from the matrix, --check now exits 1; restored, it exits 0. Before this fix the lanes were absent entirely, so there was nothing for the guard to compare. Phase 6 (#2800) still owns enriching the matrix with lane-specific detail (slug/flag/transport columns) and the locale parity gate. This is the narrower fix: the capabilities APPEAR at all. * fix(#2798): close two hardening gaps and record three limits durably Isolated security review (5 targets, no blockers) reproduced two gaps in the new deriveReviewerSlugs. Both are unreachable through the checked-in registry -- it is generated, JSON-sourced and code-reviewed -- but the function is EXPORTED for reuse and carries no other validation, so it must not depend on its caller. - A whitespace-only slug passed the length>0 test verbatim and occupied a roster entry it could never match. Slugs are now trimmed before the emptiness test. A blank body correctly falls through to the legacy alias rather than DROPPING the lane, which would have been worse than the blank slug. - KNOWN_REVIEWER_SLUGS is computed at require() time, so an uncaught throw there breaks import for EVERY consumer rather than degrading selection. It is now guarded, yielding an empty roster on a malformed registry. That is a visible degradation, not a silent one: under D4 an explicitly requested reviewer that is unavailable is an ERROR, so /gsd:review --claude against an empty roster fails loudly. This also removes an asymmetry -- the sibling capability-trust module documents its collectors as TOTAL and wraps them for exactly this reason. Also records three findings that previously existed ONLY in squash-merged PR bodies, which is not a durable record: - ADR-2782 D5 gains an implementation note explaining why the resolved host is deliberately EXCLUDED from the disclosure signature. Rule 1 says consent binds the resolved host; the loader has no config resolver, so folding it in would make the loader and lifecycle compute different signatures for one manifest and re-prompt forever. The binding is split: signature covers the SHA-pinned manifest fields, the consent record stores the resolved host, and Phase 5b re-resolves at invocation -- which is where rule 4 already puts the check. A reader comparing rule 1 to the code would otherwise conclude it is unimplemented. - CONTEXT.md's capability-trust entry still described THREE executable surfaces. Phase 3 added the fourth and made that false; corrected here, since it is drift this epic introduced rather than Phase 6's new-glossary-term work. - stableJson documents the NaN/Infinity/undefined -> null signature collision and why it is unreachable (JSON grammar has no such literal, so JSON.parse throws first). Reachability rests entirely on the ingest path staying JSON.parse-only, so the note lives where someone would break it. * chore(#2798): backfill changeset pr number to 2837	2026-07-29 16:58:02 -04:00
Tom Boucher	46e84d5e39	chore(#2795): reviewer manifest body + registry harvest, validation, forward-compat (#2823) ... * chore(#2795): reviewer manifest body + registry harvest, validation, forward-compat Phase 2 of epic #2782 under ADR-2782. Delivers D1, D2, D3, D7, D8 and the four Phase-1 vocabulary amendments (A1-A4). - VALID_ROLES gains "reviewer"; the reviewer body is admissible on role:runtime (a host that is also a reviewer keeps one manifest) and on the new role:reviewer (a lane that is not an install target). A reviewer body on role:feature is an error: declaring one is an assertion of lane-ness. - validateReviewerBody + validateLaneProbe + validateLaneInvoke: nine closed enums, a transport discriminator selecting mutually-exclusive invoke sub-shapes, bounded probes (D7), and outputArg required-iff outputChannel is file-arg and forbidden otherwise. - Absent-safe (D4.1): only `undefined` is absent. null/{}/[]/false/0 are malformed assertions and error. 39 of 39 shipped capabilities depend on this. - collectReviewerWarnings: an unknown field inside the body warns, never errors, so a forward-built manifest degrades visibly instead of failing the build. - D8 uniqueness (slug / flags / reviewsSection) lives in validateCrossCapability, so it is enforced at build time over first-party AND at load time over the merged first-party union overlay set, with first-party-wins falling out of the loader's existing ordering rather than a new provenance check. - Config harvest widened past the role==="feature" branch in both the generator and the ownership loop. The often-cited cause of the stranded reviewer config keys -- the runtime body forbidding feature-only fields -- is not the mechanism: `config` is not in FEATURE_FIELDS_FORBIDDEN_ON_RUNTIME. The cause is two harvest sites that never read it. Verified inert: no shipped capability declares config on a non-feature role, and the generated registry is unchanged. Three ADR corrections are folded in (Phase 1 set the precedent of amending in-phase): the misattributed config-stranding cause, D3's inverted profile-membership claim, and the specified capability folder names for lm_studio / llama_cpp, which would have failed the id kebab-case invariant. Closes #2795 * chore(#2795): collapse nine enum checks into one validateEnumField helper Standards-axis review findings, both applied: - Duplicated Code: the enum-membership + enumerate-the-members error shape repeated near-verbatim at nine call sites. Routing them through one helper makes "the error names its valid members" structural rather than a convention repeated nine times, where it would drift. That property is load-bearing until Phase 6 ships the prose reference, because these errors are currently the only documentation of the vocabulary. - Speculative Generality: the isReservedName() pre-check on every enum field was inert. A VALID_* set never contains __proto__/constructor/prototype, so membership alone already rejects them, and "must be one of: ..." is more actionable than "is a reserved name". The literal guards remain where they do real work -- the key-derived write sites in the registry generator and the claim() accumulator. The reserved-name test now asserts all three reserved names are rejected via enum membership, rather than one name via a branch that no longer exists. * fix(#2795): align lane slug grammar with Phase 1 and wire the load-time diagnostic channel Spec-axis review findings, both applied. (1) The slug grammar had diverged from Phase 1's core descriptor. Phase 1 exports LANE_SLUG_RE = /^[a-z0-9][a-z0-9_-]*$/ (leading digit permitted); the manifest validator required a leading LETTER. A slug the core descriptor accepts -- a model-named lane such as 4o-mini -- would have been rejected by the manifest validator, which is exactly the translation layer ADR-2782 exists to delete. It was inert only because all eleven shipped slugs begin with a letter, so nothing else would have caught it until a third party shipped such a lane. The grammar cannot be reduced to one definition: Phase 1's module compiles to gitignored build output, and capability-validator.cjs is a committed plain .cjs that must load on a fresh worktree before build:lib has ever run. That makes this the repo's DEFECT.GENERATIVE-FIX class, so the duplication now carries a parity assertion -- laneSlugGrammarMatchesPhase1Descriptor -- which compares both the source grammar and the accept/reject verdict for a shared input set, and fails if the two ever drift again. (2) collectReviewerWarnings had exactly one caller: the build-time generator, which only ever sees first-party in-repo manifests. The real third-party overlay loader never called it and ValidatorModule did not declare it, so ADR-2782 D4.3 -- an unknown field inside a reviewer body is ignored WITH A WARNING -- surfaced nowhere at runtime, which is precisely the case D4.3 exists for. loadRegistry now collects those diagnostics on the accept path, behind a typeof-guard (an older built validator without the function still loads) and a try/catch (ADR-1244 D2's never-crash contract outranks a diagnostic). They land in a NEW OverlayMeta.diagnostics field rather than OverlayMeta.warnings, because warnings records capabilities that were SKIPPED and a consumer treating every entry as inactive would mislabel a working lane. Covered end-to-end by overlayLaneWithUnknownFieldIsAcceptedAndDiagnosed, which drives a real global-scope overlay through loadRegistry and asserts the lane is accepted, produces no skip warning, and yields a diagnostic naming the field. * fix(#2795): make the reviewer validators honour their documented totality contract Isolated adversarial review finding (MAJOR), reproduced by execution. validateReviewerBody documents itself as "TOTAL: returns an array of error strings for ANY input and never throws", and the overlay loader contracts every validator to RETURN errors -- #1461 OVL-1 records a validator that THREW and would have crashed every consumer of loadRegistry. The contract was false at ten sites: JSON.stringify throws on a BigInt and on a circular structure, and every enum/scalar rejection path interpolated the rejected value into its own rejection message. Reading the value could throw too, before any message was built, via a throwing getter or a Proxy get/ownKeys trap. Not reachable through a capability.json today -- every ingestion path is a plain JSON.parse of file text, which cannot express any of those shapes. Fixed anyway: the contract is stated on an EXPORTED function, and a caller must not have to re-derive today's reachability analysis to know whether it holds. Two layers, because serialization safety alone is insufficient: - describeValue() renders any value without throwing, so messages stay useful (a BigInt now reads "got: 10n" rather than degrading to a generic fallback). - A structural try/catch around validateReviewerBody and collectReviewerWarnings makes the guarantee absolute rather than argued, covering read-time throws that fire before any message exists. The same review found the property test guarding this contract was FALSE CONFIDENCE, which is the more important half. fc.anything() at default constraints emits no BigInt, no circular reference, no getter and no Proxy -- 20,000 sampled draws produced zero of each -- so the test was named for a contract its generator could not reach. Even withBigInt is insufficient under whole-value fuzzing, because the defect needs an exotic value in a specifically NAMED field and random key names never land on one. The property is now field-targeted across all twelve reviewer fields, and a companion test enumerates the shapes fast-check cannot generate at all (BigInt, circular, throwing getter, symbol, function, null-prototype) across scalar positions, array-element positions, and read-time traps. Verified red-before-green: with the fix reverted both property tests fail; with it restored all 119 pass. * chore(#2795): backfill changeset pr number to 2823	2026-07-29 10:55:45 -04:00
Tom Boucher	8b44a0da43	chore(#2794): single-source the reviewer invocation contract + parity assertion (#2820) ... * chore(#2794): single-source the reviewer invocation contract Phase 1 of epic #2782 (ADR-2782). Introduces one core descriptor table as the declared contract for all 11 cross-AI reviewer lanes, and the DEFECT.GENERATIVE-FIX parity assertion the roster has never had. The lane contract lived in three unrelated surfaces — the roster, ~640 lines of hand-authored per-CLI bash in invoke_reviewers, and the write_reviews section headings — so cross-cutting fixes landed per-leg (#2494 and #2605 were the same empty-output defect filed twice). - src/review-lane-descriptor.cts: frozen table declaring per lane the slug, flags, probe, invoke shape, timeout floor, empty-output policy, REVIEWS.md section, evidence class, required binaries, prompt-budget key and handler. Field names track ADR-2782 D1/D2/D6/D7 verbatim so Phase 2 harvests the shape with no translation layer. It declares; it does not execute — invoke_reviewers iterates in Phase 5b. - checkReviewerLaneParity: bidirectional parity across descriptor, roster, invoke_reviewers legs and write_reviews sections. Forward-only would miss the failure it exists to catch (#2718 added a leg, #2781 was the drift). ADR-1517 instance headings are exempt per D8. - Legs carry an explicit <!-- reviewer-lane: slug --> marker; five non-lane bold labels share the bold-then-fence shape a heuristic matcher would key on. - ADR-2782 D4: an explicitly-flagged reviewer that cannot run is now an error in both the core module and the workflow prose that mirrors it. A code-only change would be unobservable — the module has no production caller; the workflow narrates the policy. Discovery paths (--all, review.default_reviewers) stay lenient. - Fixes the qwen leg, the last one discarding stderr to /dev/null. Two ADR-2782 D2 vocabulary widenings were forced by surveying the shipped legs: promptChannel 'none' (CodeRabbit is fed no prompt) and outputChannel 'file-arg' (Codex writes via -o and discards stdout, #1698). Both are additive and closed; Phase 2 owns the validator. Closes #2690 Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> * fix(#2794): make the parity checker total and pin the lane slug grammar Findings from the orthogonal review passes. Spec axis — the module claimed its vocabulary tracked ADR-2782 D1/D2 "verbatim" while diverging in three undisclosed ways, which is the translation layer Phase 2 was supposed to be spared: - `transport` moves from `invoke.transport` to the LANE level, a sibling of `probe`/`invoke`, exactly as D1's manifest example places it. The nested form read better as a TS discriminated union; the union is now discriminated at the lane level instead, which costs nothing. - The header and the CONTEXT.md glossary now enumerate all FOUR widenings (adding `outputArg` and `flags[]`), not two. Standards axis — CLAUDE.md requires a fast-check property test for a parser, and `checkReviewerLaneParity` parses markdown for markers and headings. Adding one found two real defects that the hand-written matrix missed: - NOT TOTAL: a malformed descriptor entry threw on `lane.flags` iteration, contradicting the module's own "never throws" claim. Every field is now narrowed from `unknown` at the trust boundary and reported as MALFORMED_LANE / INVALID_SLUG. This matters because Phase 2 feeds this function third-party overlay data, and a parity gate that crashes is indistinguishable from one never run. - SILENT GRAMMAR MISMATCH: LEG_MARKER_RE captures only [a-z0-9_-], so a slug outside that class was unmatchable — its marker could be present and correct and the scan would still report LEG_MARKER_MISSING forever. LANE_SLUG_RE now pins the grammar and a violating slug is reported INVALID_SLUG. A loud named violation beats a silent miss. Generators are document-shaped, not writer-seeded (CONTRIBUTING #2371): seeding from the module's own matchers could only produce documents those matchers already recognize. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> * fix(#2794): register the new bin/lib module in the ESLint ignore list The remote runner caught this; lint:ci did not, because the invariant lives in the test suite rather than the lint chain: tests/repo-invariants.test.cjs "each bin/lib/*.cjs is linted xor ignored according to migration state" -> tsc-generated bin/lib modules not yet added to ESLint ignore list: review-lane-descriptor.cjs Adding a src/*.cts module ripples to six surfaces (.gitignore, the ESLint ignore list, docs/INVENTORY-MANIFEST.json, the CONTEXT.md glossary, the capability/inventory manifests, and any size baseline). The other five were covered; this was the miss. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> * docs(#2794): amend ADR-2782 D1/D2/D8 with the vocabulary Phase 1 surfaced Building the Phase 1 descriptor table against all eleven shipped legs is the first time every lane's contract was written in one place, and it surfaced four cases the ADR's original survey did not cover. Amending the design lock rather than diverging from it, so Phase 2 (#2795) implements the manifest validator against the amended vocabulary instead of rediscovering the gaps. All four are additive widenings of closed enums; no decision reverses: - D2 promptChannel gains `none` — coderabbit is fed no prompt at all, it reviews the working-tree diff. - D2 outputChannel gains `file-arg` — the ADR called a file-writing lane a shape a real CLI *could* take; codex already is one, writing via -o/--output-last-message and discarding stdout (#1698). - D2 gains `outputArg`, required iff file-arg — knowing the review lands in a file is useless without the argument naming it. - D1 `flag` becomes `flags[]` and D8's uniqueness flattens across lanes — antigravity is selected by both --antigravity and --agy, which a single-valued field cannot express. This is the same evidence path that produced the openai-http transport: the vocabulary widens on a lane that exists, under review, never on speculation. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> * chore(#2794): backfill changeset pr number to 2820 --------- Co-authored-by: Claude Opus 5 <noreply@anthropic.com>	2026-07-29 07:31:32 -04:00
Tom Boucher	7f13ee5373	enhance(#2793): ADR-2782 — reviewer lane becomes a declared capability surface (#2809) ... * docs(#2793): add ADR-2782 — reviewer lane capability surface Design lock for epic #2782. Declares a reviewer lane as capability data rather than a core patch across three unrelated surfaces. Key decisions: - D2 transport discriminator (spawn | openai-http) — a survey of all twelve lanes found three that are HTTP endpoints with no binary, which invalidated the single-invoke-shape draft. - D4 the reviewer body is optional and absent-safe at every layer. - D5 a fourth executable-surface disclosure class covering the lane binary or host AND its egress payload classes. - D6 handler is a closed first-party enum, upholding ADR-1016; the consequence — third-party lanes are data-only — is stated plainly. - D7 probe kinds wider than existence, and every probe bounded. Amends ADR-857, ADR-894, ADR-1016, ADR-1244. Also records the D7/D8-extended-by-ADR-1244 marker on ADR-857 that ADR-1244 D8 promised but never added. Closes #2793 * docs(#2793): address orthogonal review findings on ADR-2782 Two blockers from the isolated adversarial pass: - D5 disclosed the spawn binary but not its args, reopening the #1459 bug class already fixed for MCP servers (binary python3 + args -c <program>). args are now disclosed and signature-bound. - hostConfigKey resolves from .planning/config.json, which is mutable after consent with no integrity check, so a lane consented against localhost could be silently redirected to a remote host by an ordinary PR. The resolved host is now consent-bound and re-verified on the invocation path; a mismatch blocks the lane. Majors and spec gaps: - D4 gains an explicit-selection carve-out. Absent-safe governs discovery, never a lane the user named; the current selector records that as info, which Phase 1 now corrects. - D4 gains a warning delivery channel. - D6 enumerates the handler closed-enum members; a closed enum whose membership is left to the implementing phase is not closed. - D6 records aider and plandex as concrete lanes the vocabulary cannot express, rather than claiming sufficiency it did not verify. - D2 gains evidenceClass, requiresBinaries, promptBudgetKey for per-lane divergence that was only prose, and motivates the one-member outputChannel enum. - reviewer.requires renamed requiresBinaries — it collided with the envelope requires (capability deps) at a different nesting depth. - Antigravity two-level timeout: Context cited it then dropped it; now explicitly delegated to the handler. - D9 gains a per-key ownership table, including three keys that stay central because they are policy across lanes, not lane properties. - Phase table maps every decision D1-D9 to a delivering phase; D6 handler modules and D5 invocation-time re-verification were previously unclaimed. - American English per house style.	2026-07-28 22:26:26 -04:00