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.
This commit is contained in:
Tom Boucher
2026-07-28 22:26:26 -04:00
committed by GitHub
parent 84bfef0818
commit 7f13ee5373
6 changed files with 566 additions and 2 deletions

View File

@@ -8,6 +8,7 @@
- **Materializes:** [ADR-58](58-runtime-install-policy-module.md) (the typed `InstallPlan` projection)
- **Builds on:** [ADR-3660](3660-runtime-artifact-layout-module.md) (artifact layout), [ADR-894](894-capability-declaration-format.md) (the `role: runtime` body, already validated)
- **Subsumed by:** [ADR-1239](1239-gsd-embeddable-orchestration-engine.md) (GSD as an Embeddable Orchestration Engine) — read it first; see the amendment below
- **Amended by:** [ADR-2782](2782-reviewer-lane-capability-surface.md) (Reviewer Lane capability surface) — a `role: "runtime"` capability may now carry a `reviewer` body **alongside** its runtime body. The runtime body itself remains closed and unchanged, and no feature-only field becomes permissible on it. ADR-2782 D6 **upholds** this ADR's closed-vocabulary principle: the lane's `handler` is a closed enum of first-party names (the `ConverterName` construction of Decision 3), never an open escape hatch, so §Alternatives #2 stands unreversed.
## Amendment (2026-07-16): subsumed by ADR-1239 (EoS) — this ADR is the *declarative adapter*, not the whole architecture