golem15/msd-core
4
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

chore(#2798): declare the eleven reviewer lanes as manifest data (#2837)

Browse Source 
* 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
This commit is contained in:
Tom Boucher
2026-07-29 16:58:02 -04:00
committed by GitHub
parent 982e83f0f7
commit 6a9babda69
20 changed files with 1740 additions and 37 deletions
Download Patch File Download Diff File Expand all files Collapse all files

67
docs/adr/2782-reviewer-lane-capability-surface.md
View File

@@ -330,6 +330,32 @@ Therefore, normatively:
A host change is a change of *who receives the user's plans*. It is the most security-relevant
mutation in this design, and it must not be reachable by editing a JSON file.
> **Implementation note added by Phase 3 (#2796) — how rule 1 is actually satisfied.**
>
> The resolved host is **deliberately excluded from the disclosure signature**, and a reader
> comparing rule 1 to `capability-trust.cts` must not mistake that for the rule being unimplemented.
>
> `signatureForManifest(manifest, stagedDir?)` is the single consent key that **both** the loader and
> the lifecycle compute, explicitly so the two "can never drift". The loader has **no config
> resolver** — `hostConfigKey` names a key in `.planning/config.json`, which is outside the SHA-pinned
> bundle. Folding the resolved host into the signature would therefore make the loader and the
> lifecycle compute *different* signatures for the same manifest, producing a permanent
> false-mismatch loop that re-prompts forever.
>
> So the binding is split, and rule 1 still holds end to end:
> - the **signature** binds the manifest-derived lane fields (`slug`, `transport`, `binary`, `args`,
> `hostConfigKey`, `promptChannel`, `handler`) — everything that is SHA-pinned;
> - the **consent record** additionally stores the resolved host, which is what rule 1 requires;
> - **Phase 5b re-resolves and compares at invocation** and blocks on mismatch, which is where rule 4
> already places the check.
>
> `reviewsSection` and `timeoutFloorMs` are excluded for a different reason: a cosmetic change must
> not force re-consent, because a prompt carrying no security information is how users learn to click
> through — the same failure this decision cites when rejecting a per-run egress prompt.
>
> *(Recorded here rather than in the PR that made the decision. A squash-merged PR body is not a
> durable record: it is invisible to anyone reading the ADR later, which is exactly who needs this.)*
**Stated honestly, and consistent with ADR-1244 D5's own acknowledgment that there is no sandbox:**
even with the above, consent-at-install remains a weaker gate for a *standing egress channel* than
for a hook. A user consents once; the lane thereafter receives every plan on every review run.
@@ -659,6 +685,41 @@ lane and they are deliberately not the same string:
| `reviewer.slug` | `lm_studio` | snake | the shipped roster and `review.lm_studio_host`, which D9 leaves unchanged |
| `reviewer.flags` | `--lm-studio` | kebab | the shipped flag |
Phase 2 therefore validates `reviewer.slug` against its own pattern (`/^[a-z][a-z0-9_-]*$/`) rather
than reusing `KEBAB_RE`, which would have rejected two shipped lanes. Phase 5a must create
`capabilities/lm-studio/` and `capabilities/llama-cpp/`, each declaring the snake-case slug.
Phase 2 therefore validates `reviewer.slug` against its own pattern rather than reusing `KEBAB_RE`,
which would have rejected two shipped lanes. Phase 5a must create `capabilities/lm-studio/` and
`capabilities/llama-cpp/`, each declaring the snake-case slug.
*(Corrected 2026-07-29: this paragraph first recorded the pattern as `/^[a-z][a-z0-9_-]*$/`. Phase 2's
own security review caught that as a divergence from Phase 1's exported `LANE_SLUG_RE`, which permits
a leading digit — a model-named lane such as `4o-mini` would have been accepted by the core descriptor
and rejected by the manifest validator, reintroducing exactly the translation layer this epic deletes.
The shipped pattern is `/^[a-z0-9][a-z0-9_-]*$/`, and a parity assertion now fails if the two ever
drift again.)*
### 2026-07-29 — Phase 4 and Phase 5a are swapped (ordering correction from Phase 5a)
**The phase table above runs Phase 4 (federated config) before Phase 5a (lane declarations), and
#2798 states "Depends on Phases 2 and 4". That ordering is inverted, and it makes Phase 4
unsatisfiable.**
D9's ownership table assigns `review.ollama_host` to the `ollama` lane, `review.lm_studio_host` to
`lm_studio`, and `review.llama_cpp_host` to `llama_cpp`. A federated `config` slice lives inside a
`capabilities/<id>/capability.json` — and **those capability directories do not exist until Phase 5a
creates them**. Verified before the swap: `capabilities/{ollama,lm_studio,llama_cpp,gemini,coderabbit}`
were all absent, and only the six `reviewerCli`-flagged runtime capabilities existed.
So in the stated order Phase 4 has nowhere to put three of its five key families, and its own "Done
when" — *"`review.<host>_host` owned by lane capabilities"* — cannot be met. Shipping it unmet would
be a failed deployment under `CI.GATE.acceptance-criteria-required`.
5a's stated dependency on Phase 4 is likewise unfounded: declaring a `reviewer` body requires only the
manifest vocabulary from Phase 2. **The real dependency graph is `Phase 2 → 5a → 4`**, with
`5a → 5b → 6` unchanged. Nothing about either phase's *content* changes — only their order.
**A second correction, to #2798's acceptance list.** It requires "`docs/INVENTORY.md` updated +
`node scripts/gen-inventory-manifest.cjs --write` run **after** `build:lib`". That rests on a false
premise: the inventory catalogs `bin/lib/*.cjs` **modules**, not capability directories —
`antigravity`, `opencode` and `qwen` appear zero times in it, and `INVENTORY-MANIFEST.json`'s six
families contain no `capabilities/` entry at all. `gen-inventory-manifest.cjs --check` passes with the
five new capability directories added and no inventory edit. The item is vacuous for this phase, and
inventing an edit to satisfy it would introduce drift rather than prevent it.

23
docs/reference/capability-matrix.md
View File

@@ -102,6 +102,29 @@ emission), so their extension-point and hook-kind cells are `—`.
| `windsurf` | runtime | core | `>=1.6.0` | — | — | first-party |
| `zcode` | runtime | core | `>=1.6.0` | — | — | first-party |
### Reviewer capabilities (role: reviewer) — 5
Reviewer capabilities declare a cross-AI **reviewer lane** — one external CLI or
model endpoint `/gsd:review` hands a plan to (ADR-2782 D3). They are not install
targets: they emit no skills, agents, hooks or surface files, so their
extension-point and hook-kind cells are `—`. A host that is *also* a reviewer
(Claude, Codex, Cursor, OpenCode, Qwen, Antigravity) keeps one manifest and
appears under **runtime** above, carrying its lane alongside its runtime body;
only lanes that GSD never installs into appear here.
Because a lane receives the plan text, requirements, research findings and
`CONTEXT.md` decisions, it is a disclosed executable surface and is consent-gated
at install like any other — see
[the trust model](../explanation/capability-trust-model.md).
| id | role | tier | engines.gsd | extension points | hook kinds | source |
|---|---|---|---|---|---|---|
| `coderabbit` | reviewer | full | `>=1.8.0` | — | — | first-party |
| `gemini` | reviewer | full | `>=1.8.0` | — | — | first-party |
| `llama-cpp` | reviewer | full | `>=1.8.0` | — | — | first-party |
| `lm-studio` | reviewer | full | `>=1.8.0` | — | — | first-party |
| `ollama` | reviewer | full | `>=1.8.0` | — | — | first-party |
---
## Third-party capabilities