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

@@ -116,7 +116,7 @@ This replaces a hand-maintained table that had drifted to **40 of 65 ADRs** —
<!-- ADR-INDEX:START — generated by scripts/gen-adr-index.cjs; do not edit by hand -->
### Active decisions (52)
### Active decisions (53)
These govern the system as it stands. Cite these.
@@ -173,6 +173,7 @@ These govern the system as it stands. Cite these.
| [ADR-2346](2346-command-dispatch-completion.md) | Command Dispatch Completion | Accepted | — |
| [ADR-2629](2629-phase-effort-estimation-calibration.md) | Phase effort is estimated against a calibrated smart-zone budget, not a static heuristic | Accepted | — |
| [ADR-2719](2719-emitted-artifact-attribution.md) | Emitted-artifact attribution — replace the committed parity fixtures with a computed conservation law | Accepted | — |
| [ADR-2782](2782-reviewer-lane-capability-surface.md) | Reviewer Lane — the cross-AI reviewer handoff becomes a declared capability surface | Accepted | — |
| [ADR-3660](3660-runtime-artifact-layout-module.md) | Runtime Artifact Layout Module owns per-runtime artifact placement | Accepted | [ADR-1239](1239-gsd-embeddable-orchestration-engine.md) |
### Proposed (8)
@@ -205,7 +206,7 @@ Historical record. **Do not follow these** — each names what replaced it, or w
| [ADR-2264](2264-golden-parity-redesign.md) | Redesign golden-install-parity — single-source manifest builder + split invariant | Superseded | [ADR-2719](2719-emitted-artifact-attribution.md) |
| [ADR-3524](3524-cjs-sdk-hard-seam.md) | CJS↔SDK hard seam — one source of truth per Shared Module | Superseded | [ADR-0174](0174-retire-gsd-sdk-package-boundary.md) |
_68 ADRs. Generated by `scripts/gen-adr-index.cjs` — run `--write` after adding or restatusing an ADR._
_69 ADRs. Generated by `scripts/gen-adr-index.cjs` — run `--write` after adding or restatusing an ADR._
<!-- ADR-INDEX:END -->