From 635c1c675490c58ab38181d6659477325ae77d06 Mon Sep 17 00:00:00 2001 From: Arye Kogan Date: Tue, 7 Jul 2026 13:00:08 +0300 Subject: [PATCH] docs: add acceptance review lane ADR --- docs/design/README.md | 7 +- docs/design/contracts/providers.md | 2 + docs/design/core/README.md | 4 + docs/design/core/authorization.md | 3 + docs/design/core/bootstrap.md | 4 +- docs/design/core/orchestration.md | 3 +- docs/design/core/plan-intake.md | 3 + docs/design/core/records.md | 4 + .../decisions/0034-acceptance-review-lane.md | 133 ++++++++++++++++++ docs/design/decisions/README.md | 16 ++- docs/design/security-model.md | 3 +- 11 files changed, 170 insertions(+), 12 deletions(-) create mode 100644 docs/design/decisions/0034-acceptance-review-lane.md diff --git a/docs/design/README.md b/docs/design/README.md index 4dfa7a2..73cc219 100644 --- a/docs/design/README.md +++ b/docs/design/README.md @@ -107,6 +107,8 @@ M5a slice. Current reconciliation notes: +- [ADR 0034](./decisions/0034-acceptance-review-lane.md) settles the verifier/reviewer lane as + governed evidence: not Jig-core, Worker, Forge, Owner/Doorbell, or a fifth provider seam. - [ADR 0027](./decisions/0027-packaging-sdk-boundary.md) settles the target internal package direction: `jig-sdk`, `jig-cli`, and `jig-testkit`, with the root package remaining private. - [ADR 0028](./decisions/0028-codex-app-server-transport.md) selects owned stdio app-server as the @@ -142,8 +144,9 @@ consolidates existing security design only; it cites the existing `SEC-*`, `FENC Design reconciles _to_ the product layer. The current design maps back to the ID-bearing commitments in [the five guarantees](../product/guarantees.md) and names product conflicts where found. No product conflicts are known. The product clarification treats verification before landing -as a policy/config-owned acceptance/review lane; this design reflects that boundary without -claiming a shipped runtime/config/schema implementation beyond existing evidence. The current +as a policy/config-owned acceptance/review lane; [ADR 0034](./decisions/0034-acceptance-review-lane.md) +anchors that boundary without claiming a shipped runtime/config/schema implementation beyond +existing evidence. The current runtime is now a private four-package workspace (`jig-sdk`, `jig-cli`, `jig-mcp`, `jig-testkit`) and remains pre-session-observable; Codex-transport direction must still be read as design direction, not shipped public API. diff --git a/docs/design/contracts/providers.md b/docs/design/contracts/providers.md index 9307b7a..894afab 100644 --- a/docs/design/contracts/providers.md +++ b/docs/design/contracts/providers.md @@ -108,6 +108,8 @@ ports, but it does not get to redefine: This file therefore describes each seam as an owns / implements / must-not contract, while leaving adapter mechanics, schemas, and manifest detail for later work. +[ADR 0034](../decisions/0034-acceptance-review-lane.md) also fixes that the verifier/reviewer is a +governed evidence lane outside this provider set, not a fifth seam. ## Provider extension and package posture diff --git a/docs/design/core/README.md b/docs/design/core/README.md index 6423748..081cbd4 100644 --- a/docs/design/core/README.md +++ b/docs/design/core/README.md @@ -296,6 +296,10 @@ The domain model of this group — each entity's owns / reads / does-not-own, th | Review lane | Governed assessment lane selected by launch-bound policy/configuration. Emits a verdict or evidence assessment for the runner/policy to consume; does not land work, hold forge credentials, redefine policy, or transition lifecycle directly. | MERGE-1, MERGE-3, CFG-1 | | Run records | Durable, ordered, structured records — the evidence itself; state/summary/metrics are pure projections of an append-only log; exportable write-once, redacted. The source of notices and "ask why." | SEE-1..6 | +The review lane boundary is settled by +[ADR 0034](../decisions/0034-acceptance-review-lane.md): it is governed evidence, not Jig-core, +Worker, Forge, Owner/Doorbell, or a fifth provider seam. + Operator-surface detail (the CLI / SDK / embed contract) lives in [`../contracts/driving.md`](../contracts/driving.md). diff --git a/docs/design/core/authorization.md b/docs/design/core/authorization.md index fd0cc10..17d1e2d 100644 --- a/docs/design/core/authorization.md +++ b/docs/design/core/authorization.md @@ -125,6 +125,9 @@ out by the runner on the worker's behalf. | Runner | Executing any privileged action that a grant permits | Fence decision, owner decision | Holding the worker's authority boundary open | | Verifier/reviewer lane | No authorization authority; emits evidence assessment or verdict for policy/orchestration to consume | Bound policy requirement, work/evidence under review | Granting requests, landing work, weakening policy, holding credentials | +[ADR 0034](../decisions/0034-acceptance-review-lane.md) is the authority for keeping the +verifier/reviewer lane outside authorization, Forge, and provider-seam ownership. + ## Fixed category boundary CFG-10 fixes the category line. The Fence applies that fixed line; it does not learn or improvise diff --git a/docs/design/core/bootstrap.md b/docs/design/core/bootstrap.md index 432e893..b25ec9c 100644 --- a/docs/design/core/bootstrap.md +++ b/docs/design/core/bootstrap.md @@ -178,7 +178,9 @@ append/replay rules. [`plan-intake.md`](./plan-intake.md) owns plan admission and the policy/evidence shape bootstrap consumes. Bootstrap delegates load/validate there, then binds the admitted references it returns. Bootstrap does not reinterpret unknown format, policy content, acceptance strength, or evidence -categories locally. +categories locally. The launch-bound acceptance/review posture follows +[ADR 0034](../decisions/0034-acceptance-review-lane.md)'s verifier boundary; bootstrap preserves +the selected posture but does not define reviewer implementation or schema. ### Fence and Doorbell wiring seam diff --git a/docs/design/core/orchestration.md b/docs/design/core/orchestration.md index 4760dd2..345a1ab 100644 --- a/docs/design/core/orchestration.md +++ b/docs/design/core/orchestration.md @@ -116,7 +116,8 @@ checkpoint. component performs it. - The runner can invoke a governed verifier/reviewer lane when policy requires one, but it does not perform code review logic itself, accept worker self-review as proof, or implement forge-specific - API mechanics directly. + API mechanics directly. The lane boundary is settled in + [ADR 0034](../decisions/0034-acceptance-review-lane.md). - Parallel-workspace concurrency across work items (ISO-4) is a named extension point here, realized per story in the "Phase 6 realization" note under the work-item transition table below. Resume-after-interruption mechanics are a named extension point here and are owned by diff --git a/docs/design/core/plan-intake.md b/docs/design/core/plan-intake.md index 34295cc..c5ab2d0 100644 --- a/docs/design/core/plan-intake.md +++ b/docs/design/core/plan-intake.md @@ -288,6 +288,9 @@ observes directly. Their category semantics are: Review / acceptance is a verdict or evidence assessment from the governed lane that policy requires. The lane may be a mechanical evidence check, structured independent review, real code review, owner review, or specialist review, but this doc does not turn those levels into a schema. +The lane boundary is settled in [ADR 0034](../decisions/0034-acceptance-review-lane.md): the +verifier/reviewer emits governed evidence, not lifecycle, Forge, authorization, or provider-seam +authority. Its category semantics are: - policy decides whether review is required and for which classes of change; diff --git a/docs/design/core/records.md b/docs/design/core/records.md index f8bb5e5..be2ce68 100644 --- a/docs/design/core/records.md +++ b/docs/design/core/records.md @@ -306,6 +306,10 @@ Records remains the durable evidence substrate for both runtime decisions and la - verifier/reviewer outputs are recorded as governed evidence inputs; the reviewer does not append around the runner-owned record path or become a records authority. +This acceptance/review evidence boundary is settled by +[ADR 0034](../decisions/0034-acceptance-review-lane.md); this file preserves the append/project +posture without freezing verdict event families or fields. + This surface is also a downstream contract for the execution-host seam. The capability / attestation and future acceptance/review event families must be framable against this engine's append-and-project model; this file therefore preserves the records/evidence surface as a core-owned seam without diff --git a/docs/design/decisions/0034-acceptance-review-lane.md b/docs/design/decisions/0034-acceptance-review-lane.md new file mode 100644 index 0000000..357b44e --- /dev/null +++ b/docs/design/decisions/0034-acceptance-review-lane.md @@ -0,0 +1,133 @@ +--- +title: "ADR 0034 — Acceptance/review lane and verifier boundary" +status: applied +--- + +# ADR 0034 — Acceptance/review lane and verifier boundary + +## Context + +PR #82 clarified that verification before merge/landing is a configurable acceptance/review lane +selected by owner-controlled policy and configuration before launch. That clarification is now +present in the product and design layers, but the decision was spread across the docs without a +single decision record. + +The boundary matters because the lane touches several authority surfaces at once: Worker produces +work, verifier/reviewer assesses evidence, Runner enforces policy and consumes verdicts, Forge +performs deterministic external operations only when Runner invokes it, Doorbell carries owner +decisions, Records carries durable evidence, and Execution host remains the proof boundary for +SEC-2. + +## Decision + +Jig models acceptance/review as a governed evidence lane, not as a new provider seam or a second +authority path. + +### 1. Verifier/reviewer is a governed evidence lane + +The verifier/reviewer lane is independent assessment under owner-selected policy. It may be a +human, agent, deterministic checker, ordinary code review, explicit owner review, or specialist +review when policy requires that posture. + +It is not Jig-core, Worker/Agent, Forge, Owner/Doorbell, or a fifth provider seam. It does not hold +landing credentials, grant worker requests, redefine policy, invoke Forge, author lifecycle +transitions directly, or substitute for owner judgment. + +### 2. Acceptance strength is owner-selected before launch + +Policy and configuration select the required acceptance/review strength before launch. That chosen +posture is part of the launch-bound governance contract alongside policy, work profile, repo floors, +and other binding inputs. + +Worker, reviewer, Forge provider, runtime, and resume paths cannot downgrade the required +acceptance/review strength mid-run. A weaker or missing lane reduces autonomy, routes to Doorbell, +or stops according to the bound policy; it never lowers the bar. + +### 3. Runner consumes verdicts but does not review + +Runner may invoke or consume an implemented acceptance/review lane when launch-bound policy requires +one. Runner evaluates whether the required evidence and verdicts satisfy policy before lifecycle +progress, Doorbell escalation, or Forge invocation. + +Runner does not become a code reviewer, specialist reviewer, or forge API implementation. It +consumes governed evidence; it does not perform the review judgment itself. + +### 4. PR creation, status, and comment can precede final acceptance + +Some review modes require a branch or PR to exist before review can happen. Runner may push, open or +update PRs, post statuses, or post comments under policy to enable review or surface blocked work. +These are runner-invoked Forge operations and must remain policy-governed. + +Those operations are not acceptance. Merge/landing remains gated on required evidence and +acceptance verdicts, and `done` remains distinct from `landed`. + +### 5. Self-review and weak verdicts fail closed + +Worker self-report or self-review cannot satisfy acceptance. Missing, stale, self-reported, weak, +or inconclusive acceptance evidence routes to Doorbell or stops according to the bound policy. + +No component may convert weak review evidence into permission to proceed by lowering the acceptance +requirement. + +### 6. Records carry verdicts through the governed evidence path + +Verifier/reviewer outputs are durable evidence inputs. When an acceptance/review lane is +implemented, its verdicts and supporting evidence must go through the governed records/evidence path +Runner and policy consume. + +This ADR does not freeze event families, field names, schema shape, reviewer taxonomy, or provider +method signatures. Those remain future records-contract and implementation decisions. + +### 7. SEC-2 remains execution-host proof + +Reviewers can assess evidence, diffs, and outputs. They do not prove no-phone-home. SEC-2 remains +the execution-host confinement and core proof boundary, judged from containment evidence rather than +reviewer assertion. + +This ADR does not claim progress on SEC-2 and must not be cited as closing that evidence gap. + +## Consequences + +- Design docs may cite this ADR as the authority for the verifier/reviewer boundary introduced by + PR #82. +- The four provider seams remain Agent, Execution host, Forge, and Work source. +- Forge remains deterministic and runner-invoked; it does not become a reviewer or policy authority. +- Runner-owned PR/status/comment operations may happen before final acceptance when policy needs a + review surface, but they do not themselves satisfy acceptance. +- Runtime work that adds richer acceptance/review lanes must preserve launch-bound strength, + fail-closed weak evidence, and governed records/evidence routing. + +## Implementation follow-up / deferred + +- Runtime/config/policy support for richer acceptance/review lanes. +- Field-level records-contract changes for verdicts, if needed. +- Reviewer taxonomy, if policy later needs one. +- Concrete UI/operator surfaces for routed acceptance gaps. +- SEC-2 adversarial no-phone-home evidence; this remains outside this ADR. + +## Reconciles to + +- `MERGE-1` — landing requires independent evidence, never worker self-report alone. +- `MERGE-2` — push, PR creation, and merge are runner authority. +- `MERGE-3` — done conditions and acceptance strength are policy-bound. +- `MERGE-4` — done and merged remain separate milestones. +- `MERGE-5` — blocked work may surface in the normal PR flow without becoming acceptance. +- `FENCE-3` — the worker never holds privileged credentials. +- `GUARD-1` — the policy and acceptance posture in force are fixed at launch. +- `CFG-1` — policy is the governance contract. +- `SEC-2` — no-phone-home remains execution-host confinement proof. +- `SEC-3` — forge credentials remain runner-held, not worker-held. +- `SEE-1`, `SEE-2`, `SEE-3`, `SEE-6` — verdicts are governed evidence records and exportable from + the same evidence path. + +## Related + +- [Product overview](../../product/jig.md#acceptance-before-landing) +- [Product concepts](../../product/concepts.md#runner-worker-and-verifier--the-authority-boundary) +- [Product guarantees](../../product/guarantees.md#15-merge-on-evidence) +- [Core overview](../core/README.md) +- [Orchestration](../core/orchestration.md) +- [Plan intake](../core/plan-intake.md) +- [Records](../core/records.md) +- [Provider contracts](../contracts/providers.md) +- [Security model](../security-model.md) diff --git a/docs/design/decisions/README.md b/docs/design/decisions/README.md index c7b21cb..2b3d894 100644 --- a/docs/design/decisions/README.md +++ b/docs/design/decisions/README.md @@ -13,8 +13,8 @@ dispositions) and grows as new design decisions are made. plain-language one-liner for titles that lean on internal shorthand (`S-00n`, `INV-nnn`, `ISO-n`, `SURF-nnn`); it restates the ADR's own title/decision, it does not reinterpret it — read the ADR itself for the binding text. The **Date** column is read from each ADR's own trailing -`- Date:` line; ADRs 0001–0025 carry one, ADRs 0026–0032 do not yet, so those cells are left -blank rather than guessed. **Status** is uniformly `applied` across all 32 ADRs today — see +`- Date:` line; ADRs 0001–0025 carry one, ADRs 0026–0034 do not yet, so those cells are left +blank rather than guessed. **Status** is uniformly `applied` across all 34 ADRs today — see ["What 'applied' means here"](#what-applied-means-here) below before reading it as "shipped in code." @@ -91,11 +91,12 @@ reference to real (Phase 5–8), and records tamper-evidence (Phase 9). | 0024 | Phase 8 real work-source integration: the seed-vs-candidate intake chokepoint, richer provenance, and the two-authorities crossing | Real work-source importers must cross a single validated intake chokepoint; provenance is enriched without the source becoming a second scheduling authority | 2026-07-04 | applied | | 0025 | Phase 9 records-integrity: sidecar tamper-evidence, active resume-blocked-missing-approval, the tamper-vs-changed-basis split, and the resume driver-binding fold-in | Adds sidecar tamper-evidence (an env-keyed HMAC) over run records and activates the resume re-approval gate for safety-relevant changes | 2026-07-04 | applied | -## Posture decisions (0026–0032) +## Posture decisions (0026–0034) Cross-cutting posture settled after the phase series: what a green conformance run does and does not prove, the packaging/SDK boundary, the Codex transport seam, guided setup, observation -surfaces, durable control records, and local audit exports. +surfaces, durable control records, local audit exports, the MCP adapter package, and the governed +acceptance/review lane. | # | Title | Gloss | Date | Status | | ---- | ----------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | ---- | ------- | @@ -107,10 +108,11 @@ surfaces, durable control records, and local audit exports. | 0031 | Owner decisions and stops are durable control records | Places `decide` and `stop` on the operator port as additive control records consumed by existing replay/resume semantics | — | applied | | 0032 | Export audit records are write-once JSON artifacts | Places `export` on the operator port, settles JSON export encoding, and records export audit events outside finalized run logs | — | applied | | 0033 | MCP adapter lives in a private jig-mcp package | Places MCP in its own private adapter package that depends on `jig-sdk`, exposes settled operator verbs, and creates no stability promise | — | applied | +| 0034 | Acceptance/review lane and verifier boundary | Settles the verifier/reviewer lane as governed evidence, not Jig-core, Worker, Forge, Owner/Doorbell, or a fifth provider seam | — | applied | ## Open questions -- **ADRs 0026–0033 carry no `- Date:` line.** Every ADR from 0001–0025 has one; 0026–0033 do not. - Rather than invent a date, the Date column is left blank for those eight. Whether to add a - `- Date:` line to 0026–0033 (and, if so, what date to use — authoring date vs. merge date) is a +- **ADRs 0026–0034 carry no `- Date:` line.** Every ADR from 0001–0025 has one; 0026–0034 do not. + Rather than invent a date, the Date column is left blank for those nine. Whether to add a + `- Date:` line to 0026–0034 (and, if so, what date to use — authoring date vs. merge date) is a genuine decision about this log's own convention and is not resolved here. diff --git a/docs/design/security-model.md b/docs/design/security-model.md index e347958..54e5ea8 100644 --- a/docs/design/security-model.md +++ b/docs/design/security-model.md @@ -34,7 +34,8 @@ governs, never a party jig-core takes on faith ([`contracts/providers.md`](./con line; they are never handed across it (STACK-5). A provider seam may still use a bounded, manifest-governed read or transport credential where its job requires one, but never landing or policy authority. The verifier/reviewer is separate from those seams: it can assess work or -evidence, but it cannot become the owner, runner, Forge provider, or execution host proof. +evidence, but it cannot become the owner, runner, Forge provider, or execution host proof. That +boundary is settled by [ADR 0034](./decisions/0034-acceptance-review-lane.md). ## The fence + fail-closed authorization spine