diff --git a/docs/design/README.md b/docs/design/README.md index 28f7740..4dfa7a2 100644 --- a/docs/design/README.md +++ b/docs/design/README.md @@ -29,12 +29,12 @@ decision records and reference material. | Glossary | [`glossary.md`](./glossary.md) | overview | grows as new ubiquitous-language terms are named | | Core overview | `core/README.md` | overview | — | | Domain model (configuration + runtime/observation groups) | [`domain/configuration-and-work.md`](./domain/configuration-and-work.md), [`domain/runtime-and-observation.md`](./domain/runtime-and-observation.md) | **draft** | later hardening / downstream waves; jig-core and the provider seams are specified in `core/` and `contracts/`, not here | -| Core lifecycle | [`core/bootstrap.md`](./core/bootstrap.md), [`core/orchestration.md`](./core/orchestration.md) | **draft** | later hardening / Wave 5 findings / implementation planning | +| Core lifecycle | [`core/bootstrap.md`](./core/bootstrap.md), [`core/orchestration.md`](./core/orchestration.md) | **draft** | later hardening / review-lane implementation planning / Wave 5 findings | | Core authorization | [`core/authorization.md`](./core/authorization.md) | **draft** | later hardening / conformance-policy detail / implementation planning | | Core data ports | [`core/plan-intake.md`](./core/plan-intake.md), [`core/records.md`](./core/records.md) | **draft** | implementation planning / later core-parts pass | | Contracts overview | `contracts/README.md` | overview | — | | Data contracts | `contracts/{execution-plan, observability-records}-contract-v0.md` | contract v0 | field-level schema (intentionally not frozen) | -| Driving / providers | [`contracts/driving.md`](./contracts/driving.md), [`contracts/providers.md`](./contracts/providers.md) | **draft** | package implementation / remaining EVRUN evidence gates | +| Driving / providers | [`contracts/driving.md`](./contracts/driving.md), [`contracts/providers.md`](./contracts/providers.md) | **draft** | package implementation / acceptance-lane integration / remaining EVRUN evidence gates | | Provider realization roadmap | [`contracts/provider-realization-roadmap.md`](./contracts/provider-realization-roadmap.md) | roadmap | grows as later provider-realization phases land | | Security model | [`security-model.md`](./security-model.md) | **draft** | grows as new controls are designed | | Decisions | `decisions/*` | log | grows as decisions are made | @@ -52,9 +52,9 @@ entity model, the structure diagram, and the bootstrap→core flow. Then the per - [`bootstrap.md`](./core/bootstrap.md) — the launch / composition root: load, validate, bind, wire, identify, ready. - [`plan-intake.md`](./core/plan-intake.md) — parse + validate a plan instance; reject unknown - formats. + formats; carry policy-owned evidence and acceptance expectations at launch. - [`orchestration.md`](./core/orchestration.md) — the runner: run/work-item state machines, - eligibility, runner-only actions. + eligibility, policy/evidence evaluation, governed review-lane consumption, runner-only actions. - [`authorization.md`](./core/authorization.md) — the fence, doorbell, and capability attestation (the fail-closed spine). - [`records.md`](./core/records.md) — the append-only event log, pure projections, and export. @@ -96,8 +96,9 @@ Every interface at jig's boundary — what others call or implement — in three (output). - [`providers.md`](./contracts/providers.md) — the four swappable provider seams, provider extractability posture, conformance/testkit routing, and the Codex app-server adapter constraint - from ADR 0028; the chronological Phase 5-8 ADR-realization history for those seams is split out - into [`provider-realization-roadmap.md`](./contracts/provider-realization-roadmap.md). + from ADR 0028; Forge remains a deterministic runner-invoked adapter, not another reviewer or + policy authority. The chronological Phase 5-8 ADR-realization history for those seams is split + out into [`provider-realization-roadmap.md`](./contracts/provider-realization-roadmap.md). ## [`decisions/`](./decisions/) — the decision log @@ -140,9 +141,12 @@ 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 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. +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 +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. ## Historical planning track @@ -159,4 +163,6 @@ already complete. - provider package publication or a third-party provider ecosystem commitment; - remaining EVRUN no-phone-home/idempotency, prompt-size / bounded-context behavior, Windows / Git Bash support, and other evidence gates that ADR 0028 leaves open; +- runtime/config/policy implementation of the richer acceptance/review lane, including any records + or verdict handling required before Forge landing; - the implementation code itself. diff --git a/docs/design/contracts/providers.md b/docs/design/contracts/providers.md index fd00a21..9307b7a 100644 --- a/docs/design/contracts/providers.md +++ b/docs/design/contracts/providers.md @@ -15,8 +15,8 @@ governed in [`../core/`](../core/README.md). reports; holds no credentials. - The **Execution host** port — where the worker runs; provides isolation and reports its isolation strength honestly. -- The **Forge** port — the push / PR / merge target; respects branch protection and merge - queues. +- The **Forge** port — the deterministic adapter for runner-invoked push / PR / status / comment / + merge operations; respects branch protection and merge queues. - The **Work source** port — where work items originate. - The posture that seams are authority boundaries: credentials and irreversible authority stay where the fence and runner govern them, never with a provider. @@ -40,7 +40,7 @@ inventory in [`../notes/runtime-design-m5a.md`](../notes/runtime-design-m5a.md). progress. - **Execution host port** — abstracts where the worker is contained. - **Forge port** — abstracts the code host a run pushes to, opens PRs against, and merges - through. + through; it translates authorized requests into deterministic forge operations. - **Work source port** — abstracts where work items originate. It may supply provenance or future import/sync behavior, but the validated execution plan remains jig's only runtime scheduling input; the Work source seam never bypasses the plan. @@ -101,6 +101,7 @@ ports, but it does not get to redefine: - what counts as authorization or escalation; - what counts as evidence or completion; +- what counts as an acceptance/review verdict; - what `done`, `landed`, `blocked`, or `parked` mean; - where credentials and irreversible authority live; - how work becomes eligible to run. @@ -161,7 +162,8 @@ relationships these seams participate in: requests crossing the Fence's `authorize(request, boundPolicy) → grant | deny | route` decision from [`../core/authorization.md`](../core/authorization.md). - The **Forge** port is invoked by the runner at the `done → landed` boundary named in - [`../core/orchestration.md`](../core/orchestration.md); the worker does not invoke it. + [`../core/orchestration.md`](../core/orchestration.md), and for deterministic PR/status/comment + surfacing the runner has already authorized. The worker and verifier/reviewer do not invoke it. - The **Work source** port may supply provenance or import/sync behavior before runtime execution, but it does not bypass validated plan intake; the validated execution plan remains jig's only runtime scheduling input. @@ -310,24 +312,27 @@ authorization, or log semantics they already own. ### Forge port Seed interface preserved: **Forge port** — abstracts the code host a run pushes to, opens PRs -against, and merges through. +against, comments/statuses on, and merges through. This section deepens the existing Forge seed in place rather than replacing it. The preserved port line above, the file-level Owns / Interface / Notes / diagram, and the port-invocation point that the runner invokes this seam at the `done -> landed` boundary remain the governing seed statements for this seam. The Forge provider implements behind that port, consuming the runner-owned orchestration surface from [`../core/orchestration.md`](../core/orchestration.md), the -evidence-sufficiency and GUARD-2 preconditions from [`../core/plan-intake.md`](../core/plan-intake.md) -and [`../core/authorization.md`](../core/authorization.md), and the records/log surface from +evidence-sufficiency, acceptance/review, and GUARD-2 preconditions from +[`../core/plan-intake.md`](../core/plan-intake.md) and +[`../core/authorization.md`](../core/authorization.md), and the records/log surface from [`../core/records.md`](../core/records.md) read-only. It does not redefine evidence sufficiency, -GUARD-2 detection or re-approval, done-versus-landed semantics, blocked-state ownership, or log -consistency those core and prior-wave surfaces already own. +review verdict sufficiency, GUARD-2 detection or re-approval, done-versus-landed semantics, +blocked-state ownership, or log consistency those core and prior-wave surfaces already own. **Core owns** - The rule that push, PR creation, and merge are runner authority, never worker authority. - The meaning of `done` versus `landed`, and the evidence gate that must already be satisfied before landing is attempted. +- The review/acceptance gate that must already be satisfied, when launch-bound policy requires an + implemented lane, before landing is attempted. - The decision that branch protection, merge queues, and other forge-side controls are respected as governing constraints, not bypass targets. - The record/evidence boundary for what is attempted, blocked, or landed. @@ -348,6 +353,8 @@ consistency those core and prior-wave surfaces already own. - A concrete integration to the code host behind the runner-owned seam. - The mechanics needed for the runner to push, open PRs, and merge through the forge. +- The mechanics needed for the runner to post statuses and comments through the forge when the + runner has already authorized that surfacing. - Truthful surfacing of forge-side constraints and outcomes back to the core. - A runner-exclusive landing adapter that executes push / PR / merge only as the runner's delegate, never as worker-held authority and never as an alternate policy or lifecycle owner. @@ -368,8 +375,9 @@ consistency those core and prior-wave surfaces already own. - Redefine what counts as evidence-met, done, or landed. - Hide forge-side blockers or silently widen authority around branch protection or queues. - Become a second policy or state authority for merge decisions. -- Re-judge evidence sufficiency, capability freshness, or completion readiness that core already - judged before invoking the seam. +- Re-judge evidence sufficiency, review verdict sufficiency, capability freshness, or completion + readiness that core already judged before invoking the seam. +- Act as another agent, reviewer, or owner-decision substitute. - Detect, classify, or capture GUARD-2 rule-governing-surface re-approval on its own; that remains with the plan/policy/evidence and authority-spine surfaces this seam consumes. - Redefine blocked-state ownership, invent a second records fallback, or treat forge-surface @@ -435,8 +443,9 @@ to the invariant ledger in this pass. If future numbering is needed, the next av behavior only; landing authority stays runner-owned. - **Execution-host confinement is proven, not trusted by self-report.** The no-phone-home guarantee is a core-owned boundary the host must substantiate. -- **Forge is runner-invoked only.** Push, PR, and merge pass through a runner-owned seam after - policy-bound evidence gates, never directly from the worker. +- **Forge is deterministic and runner-invoked only.** Push, PR, status, comment, and merge pass + through a runner-owned adapter after policy-bound evidence and acceptance gates, never directly + from the worker or reviewer. - **Work source never bypasses validated plan intake.** Provenance can enter; runtime scheduling does not. - **Capabilities are attested, not assumed.** Missing, stale, or failed proof reduces autonomy diff --git a/docs/design/core/README.md b/docs/design/core/README.md index 9f42c5b..6423748 100644 --- a/docs/design/core/README.md +++ b/docs/design/core/README.md @@ -66,7 +66,7 @@ how work is done`") direction LR runner("`**Runner** -holds the keys`") + orchestrates + enforces`") fence("`**Fence** grants or denies`") doorbell("`**Doorbell** @@ -77,6 +77,13 @@ the evidence log`") runner ~~~ fence ~~~ doorbell ~~~ records end + subgraph reviewLane["Governed acceptance lane — independent assessment"] + direction LR + + review("`**Verifier / reviewer** +policy-owned verdict`") + end + subgraph seams["Seams — swappable, governed at the boundary"] direction LR @@ -102,26 +109,33 @@ supplies work items`") lt2["jig-core (trusted)"] l3(" ") - lt3["swappable seam"] + lt3["governed lane"] l4(" ") - lt4["you"] + lt4["swappable seam"] + + l5(" ") + lt5["you"] - l1 ~~~ lt1 ~~~ l2 ~~~ lt2 ~~~ l3 ~~~ lt3 ~~~ l4 ~~~ lt4 + l1 ~~~ lt1 ~~~ l2 ~~~ lt2 ~~~ l3 ~~~ lt3 ~~~ l4 ~~~ lt4 ~~~ l5 ~~~ lt5 end owner -->|authors, starts| config config -->|plan + policy| core + core -->|invokes when policy requires| reviewLane + reviewLane -->|verdict / evidence| core core -->|drives + governs| seams seams ~~~ legend classDef ownerBox fill:#f6f4ed,stroke:#77736d,stroke-width:2px,color:#2b2b2b,rx:16,ry:16; classDef youAuthor fill:#eeeeff,stroke:#5549d8,stroke-width:2px,color:#29226f,rx:16,ry:16; classDef trusted fill:#e3f6f0,stroke:#007a62,stroke-width:2px,color:#003f34,rx:16,ry:16; + classDef governed fill:#f5eefc,stroke:#6b3fa0,stroke-width:2px,color:#32194f,rx:16,ry:16; classDef seam fill:#fff0ea,stroke:#a43f22,stroke-width:2px,color:#4d1f12,rx:16,ry:16; classDef legendAuthor fill:#eeeeff,stroke:#5549d8,stroke-width:2px,color:#29226f,rx:6,ry:6; classDef legendTrusted fill:#e3f6f0,stroke:#007a62,stroke-width:2px,color:#003f34,rx:6,ry:6; + classDef legendGoverned fill:#f5eefc,stroke:#6b3fa0,stroke-width:2px,color:#32194f,rx:6,ry:6; classDef legendSeam fill:#fff0ea,stroke:#a43f22,stroke-width:2px,color:#4d1f12,rx:6,ry:6; classDef legendYou fill:#f6f4ed,stroke:#77736d,stroke-width:2px,color:#2b2b2b,rx:6,ry:6; classDef legendText fill:transparent,stroke:transparent,color:#666666; @@ -129,16 +143,19 @@ supplies work items`") class owner ownerBox; class track,plan,policy,profile youAuthor; class runner,fence,doorbell,records trusted; + class review governed; class worker,host,forge,source seam; class l1 legendAuthor; class l2 legendTrusted; - class l3 legendSeam; - class l4 legendYou; - class lt1,lt2,lt3,lt4 legendText; + class l3 legendGoverned; + class l4 legendSeam; + class l5 legendYou; + class lt1,lt2,lt3,lt4,lt5 legendText; style config fill:#fbfaf7,stroke:#b8b8b1,stroke-width:2px,color:#2b2b2b,rx:18,ry:18 style core fill:#fbfaf7,stroke:#b8b8b1,stroke-width:2px,color:#2b2b2b,rx:18,ry:18 + style reviewLane fill:#fbfaf7,stroke:#b8b8b1,stroke-width:2px,color:#2b2b2b,rx:18,ry:18 style seams fill:#fbfaf7,stroke:#b8b8b1,stroke-width:2px,color:#2b2b2b,rx:18,ry:18 style legend fill:transparent,stroke:transparent,color:transparent @@ -269,47 +286,50 @@ The domain model of this group — each entity's owns / reads / does-not-own, th ### B. Jig-core — the trusted runner (governs the seams) -| Entity | Responsibility (owns) | Product IDs | -| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------- | -| Operator surface | The thin entry point (CLI / MCP / SDK / embed) the owner drives jig through: one command becomes one control-plane call with SDK/operator-owned records; the edge holds no run logic and imports no provider contracts. | jig.md; SEE-1 | -| Runner | Jig's trusted orchestrator. Resolves eligibility/order, drives each work item, holds credentials and the sole authority to push/PR/merge, and performs irreversible actions only under policy + evidence. Governs the seams; is not a seam. | concepts; FENCE-3, MERGE-2, SEC-3 | -| Fence | Runtime authorization: authorizes every worker request before it executes, fail-closed; grant / deny / route by fixed category; cannot be loosened mid-run. | FENCE-1, FENCE-2, GUARD-1, CFG-10 | -| Doorbell | Escalation surface: routes ambiguous/risky/unproven actions to the owner; parks durably (survives interruption); grants are narrow, not blanket. | DOOR-1, DOOR-2, DOOR-3 | -| Capability attestation | Earned-trust gate: requires fresh, positive proof a driver can perform a capability safely; missing or stale proof means less autonomy, not a weaker guarantee. | EARN-1, EARN-2, STACK-4, DRIVE-1, DRIVE-3 | -| 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 | +| Entity | Responsibility (owns) | Product IDs | +| ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------- | +| Operator surface | The thin entry point (CLI / MCP / SDK / embed) the owner drives jig through: one command becomes one control-plane call with SDK/operator-owned records; the edge holds no run logic and imports no provider contracts. | jig.md; SEE-1 | +| Runner | Jig's trusted orchestrator. Resolves eligibility/order, drives each work item, invokes governed review/verification lanes when implemented and policy requires them, holds credentials and the sole authority to push/PR/merge, and performs irreversible actions only under policy + evidence. Governs the seams; is not a seam. | concepts; FENCE-3, MERGE-2, SEC-3 | +| Fence | Runtime authorization: authorizes every worker request before it executes, fail-closed; grant / deny / route by fixed category; cannot be loosened mid-run. | FENCE-1, FENCE-2, GUARD-1, CFG-10 | +| Doorbell | Escalation surface: routes ambiguous/risky/unproven actions to the owner; parks durably (survives interruption); grants are narrow, not blanket. | DOOR-1, DOOR-2, DOOR-3 | +| Capability attestation | Earned-trust gate: requires fresh, positive proof a driver can perform a capability safely; missing or stale proof means less autonomy, not a weaker guarantee. | EARN-1, EARN-2, STACK-4, DRIVE-1, DRIVE-3 | +| 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 | Operator-surface detail (the CLI / SDK / embed contract) lives in [`../contracts/driving.md`](../contracts/driving.md). ### C. The four seams — swappable, governed at the authority boundary -| Entity | Responsibility (owns) | Product IDs | -| ---------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------- | -| Agent (= worker) | The contained coding agent: reads a work item, writes code, runs checks, reports. Holds no credentials; cannot push/PR/merge or widen its own authority. | concepts; FENCE-3 | -| Execution host | Where the worker runs; provides isolation/containment and reports its isolation strength honestly; local-first today. | STACK-2, STACK-5, DRIVE-3, ISO-4 | -| Forge | The code host: push/PR/merge target; respects branch protection and merge queues; where a block surfaces as a real PR. | STACK-2, MERGE-5 | -| Work source | Where work items originate (an extension seam; the plan is the hard input). | STACK-2 | +| Entity | Responsibility (owns) | Product IDs | +| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------- | +| Agent (= worker) | The contained coding agent: reads a work item, writes code, runs checks, reports. Holds no credentials; cannot push/PR/merge or widen its own authority. | concepts; FENCE-3 | +| Execution host | Where the worker runs; provides isolation/containment and reports its isolation strength honestly; local-first today. | STACK-2, STACK-5, DRIVE-3, ISO-4 | +| Forge | Deterministic adapter for runner-invoked push/PR/status/comment/merge operations; respects branch protection and merge queues; where a block surfaces as a real PR. | STACK-2, MERGE-5 | +| Work source | Where work items originate (an extension seam; the plan is the hard input). | STACK-2 | ### D. What you observe (run artifacts) -| Entity | Responsibility (owns) | Product IDs | -| -------- | ----------------------------------------------------------------------------------------------------------------- | ---------------- | -| Run | One execution of a plan under a policy; reconstructible end to end. | jig.md | -| Evidence | What gates landing — automated checks + review + capability proof; never the worker's self-report alone. | MERGE-1, MERGE-3 | -| Notice | A triaged attention item per parked/blocked/stale/overdue condition: what it is, how urgent, what you can do now. | SEE-5 | +| Entity | Responsibility (owns) | Product IDs | +| -------- | ------------------------------------------------------------------------------------------------------------------------------------- | ---------------- | +| Run | One execution of a plan under a policy; reconstructible end to end. | jig.md | +| Evidence | What gates landing — automated checks + governed review/acceptance verdicts + capability proof; never the worker's self-report alone. | MERGE-1, MERGE-3 | +| Notice | A triaged attention item per parked/blocked/stale/overdue condition: what it is, how urgent, what you can do now. | SEE-5 | The domain model of this group — Run, Evidence, Notice, and the Run-records event-log entity they derive from, each with its owns / reads / does-not-own, the runtime seam, and the lifecycle terms it carries — is authored in [`../domain/runtime-and-observation.md`](../domain/runtime-and-observation.md). ## The spine in one paragraph The owner authors a track (plan + policy + work profile) and starts a run through the operator -surface (one command, one control-plane call, SDK/operator-owned records). The runner binds the policy -at launch, resolves which work items are eligible from their dependencies, and drives each by -handing work to the worker (the agent seam) running inside the execution host. Every action the -worker wants goes through the fence, which grants, denies, or routes it by fixed category; -routed or risky calls ring the doorbell for the owner. The runner — never the worker — pushes, -opens PRs, and merges through the forge, and only on evidence. Every decision lands in run -records, from which the owner inspects, asks "why," and works a queue of notices. +surface (one command, one control-plane call, SDK/operator-owned records). The runner binds the +policy at launch, resolves which work items are eligible from their dependencies, and drives each +by handing work to the worker (the agent seam) running inside the execution host. Every action the +worker wants goes through the fence, which grants, denies, or routes it by fixed category; routed +or risky calls ring the doorbell for the owner. When launch-bound policy/configuration requires an +implemented acceptance lane, the runner consumes the verifier/reviewer verdict as evidence input. +The runner — never the worker — pushes, opens PRs, and merges through the forge, and only on +policy-sufficient evidence. Every decision lands in run records, from which the owner inspects, +asks "why," and works a queue of notices. ## The two lifecycles diff --git a/docs/design/core/authorization.md b/docs/design/core/authorization.md index 7fa5cc0..fd0cc10 100644 --- a/docs/design/core/authorization.md +++ b/docs/design/core/authorization.md @@ -12,7 +12,8 @@ assertion. The Fence owns the classifier behind `authorize(request, boundPolicy)`, the Doorbell owns durable, narrow escalation, and capability attestation gates autonomy on proof. The work-item and run state machines remain [`orchestration.md`](./orchestration.md)'s territory; policy content and -rule-governing-surface declaration remain outside this file. +rule-governing-surface declaration remain outside this file. Review/verification verdicts are +evidence inputs consumed by policy/orchestration, not a second authorization system. ## Owns @@ -25,6 +26,8 @@ rule-governing-surface declaration remain outside this file. granting narrowly when the owner decides (DOOR-1, DOOR-2, DOOR-3). - Gating autonomy on capability attestation: fresh, positive proof a driver can perform an action safely before that action is auto-grantable (EARN-1, EARN-2, STACK-4, DRIVE-1). +- Routing ambiguous, risky, unproven, stale, self-reported, or inconclusive acceptance conditions + to the Doorbell or fail-closed outcome according to the bound policy. ## Interface @@ -114,12 +117,13 @@ out by the runner on the worker's behalf. ## Authority model -| Part | Owns | Reads | Does not own | -| --------------------------- | ---------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------- | --------------------------------------------------------------------- | -| Fence classifier | Classifying a request as `grant`, `deny`, or `route` using the fixed CFG-10 boundary, declared scope, and bound policy | Worker request, bound policy, declared authority expectations, capability proof status | Work-item transition table, policy authoring, provider implementation | -| Doorbell escalation | Durable routing to an owner decision point and narrow human grants | Routed request, bound policy, prior escalation context | Policy content, run/work-item stop mechanics, records storage engine | -| Capability-attestation gate | Whether autonomy may rely on a driver's proof for this action in this run context | Driver proof, run context, requested action class | Conformance-suite design, provider adapter implementation | -| Runner | Executing any privileged action that a grant permits | Fence decision, owner decision | Holding the worker's authority boundary open | +| Part | Owns | Reads | Does not own | +| --------------------------- | ---------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------- | ---------------------------------------------------------------------- | +| Fence classifier | Classifying a request as `grant`, `deny`, or `route` using the fixed CFG-10 boundary, declared scope, and bound policy | Worker request, bound policy, declared authority expectations, capability proof status | Work-item transition table, policy authoring, provider implementation | +| Doorbell escalation | Durable routing to an owner decision point and narrow human grants | Routed request, bound policy, prior escalation context | Policy content, run/work-item stop mechanics, records storage engine | +| Capability-attestation gate | Whether autonomy may rely on a driver's proof for this action in this run context | Driver proof, run context, requested action class | Conformance-suite design, provider adapter implementation | +| 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 | ## Fixed category boundary @@ -131,6 +135,7 @@ it, and no model adjudicates edge cases at runtime. | Declared, approved, reversible, non-privileged, and not touching rule-governing surfaces | `grant` candidate | This is the only class eligible for assisted autonomy | | Touches credentials, push, merge, rule-governing files, or otherwise irreversible effects | `route` | The product boundary requires a human decision here | | Ambiguous, risky, or unproven relative to the bound policy or capability proof | `route` | Uncertainty closes the door rather than weakening the guarantee | +| Missing, stale, self-reported, or inconclusive required acceptance/review evidence | `route` or stop | A weak verdict cannot become permission to proceed | | Undeclared, unapproved, or outside bound scope | `deny` | FENCE-1 is fail-closed on requests the run was not authorized to make | This boundary is intentionally category-based, not confidence-based. A request does not become @@ -202,6 +207,9 @@ The Doorbell is the owner-facing side of routed authority decisions. the run, not a broader standing exception. - A routed request may be approved, rejected, or explicitly overridden, but any approval still stays scoped to the immediate need and is executed by the runner, not the worker. +- A routed acceptance/review gap is resolved by owner/policy decision or stops; the reviewer cannot + weaken its own acceptance requirement, and the worker cannot supply self-review as sufficient + proof. This file owns the authorization-side escalation discipline only. The work-item `started → parked` and `parked → started | rejected` transitions that consume routed decisions remain defined in @@ -265,6 +273,8 @@ matters." the parked/escalation path. - The runner remains the only component that performs privileged actions, even after a grant or owner approval. +- The verifier/reviewer remains an evidence source only: it does not authorize worker requests, + hold forge credentials, invoke Forge, or create lifecycle transitions directly. - The records system remains the durable evidence substrate for authorization and escalation outcomes; this file names the decisions that must be recorded but does not own record storage or event-shape design. @@ -312,6 +322,8 @@ These are unnumbered candidates only. They do not extend the ledger here. happens, the runner is what makes it happen. - The GUARD-2 rule itself stays outside this file; authorization owns only the enforcement leg that refuses auto-grant and routes to the owner. +- Review/verification gaps follow the same fail-closed posture: missing, stale, self-reported, or + inconclusive proof routes or stops; it never weakens the bound policy. - Deferred / extension points: the depth of capability-attestation conformance checking, and the manual-vs-assisted posture's exact tuning surface, are not specified here. diff --git a/docs/design/core/bootstrap.md b/docs/design/core/bootstrap.md index b93a896..432e893 100644 --- a/docs/design/core/bootstrap.md +++ b/docs/design/core/bootstrap.md @@ -12,7 +12,8 @@ without committing to a run identity. ## Owns - Load and validate the plan, delegating to [`plan-intake`](./plan-intake.md). -- Load and bind policy and repo-level floors, frozen at launch (GUARD-1). +- Load and bind policy, acceptance/review expectations, and repo-level floors, frozen at launch + (GUARD-1). - Resolve the track and work profile for the run. - Set up the isolated workspace (ISO-4). - Wire the provider adapters: the composition root selects which agent, host, forge, and @@ -33,6 +34,8 @@ without committing to a run identity. the one place that imports provider implementations. - Wires the Fence/Doorbell with the bound policy at launch and on resume; the classifier rules stay in [`authorization.md`](./authorization.md). +- Preserves any policy/config-selected acceptance strength as part of the launch-bound posture; + detailed runtime/config schema for richer review lanes remains follow-up. ```mermaid %%{init: { @@ -107,7 +110,7 @@ write binding record**`") | Term | Meaning | Owner | | -------------------- | ---------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------ | | Preview | The recorded-but-non-committing bootstrap path that validates and binds but does not create a run. | Bootstrap | -| Launch binding | The policy, work-profile, plan, and repo-floor references fixed for a run's lifetime. | Bootstrap | +| Launch binding | The policy, acceptance posture, work-profile, plan, and repo-floor references fixed for a run's lifetime. | Bootstrap | | Binding record | The first durable run record that ties run identity to the launch binding. | Records store, appended by Bootstrap | | Storage preflight | Bootstrap's fail-closed check that the configured records substrate can safely support start or resume. | Bootstrap | | Resume re-entry | Re-entering bootstrap for an already allocated run to re-validate binding, re-wire providers, and re-check storage before handoff. | Bootstrap | @@ -129,8 +132,8 @@ The sequence below makes each step explicit and names where sibling surfaces are Bootstrap delegates admission to [`plan-intake.md`](./plan-intake.md). Unknown, malformed, or incompatible plans stop here. No run identity exists yet. 2. **Bind launch-governing references.** - Bootstrap resolves the plan's policy, work-profile, and repo-floor references and freezes them - for the run. This is the concrete GUARD-1 binding point. + Bootstrap resolves the plan's policy, acceptance/review posture, work-profile, and repo-floor + references and freezes them for the run. This is the concrete GUARD-1 binding point. 3. **Branch by intent: preview or start.** `preview` remains non-committing. `start` continues into realization. 4. **Resolve track/work-profile realization inputs.** @@ -174,7 +177,8 @@ 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, or evidence categories locally. +Bootstrap does not reinterpret unknown format, policy content, acceptance strength, or evidence +categories locally. ### Fence and Doorbell wiring seam @@ -231,7 +235,8 @@ doing so would undercut RESUME-4's diagnosable-stop contract. Bootstrap is the concrete owner of performing the launch binding GUARD-1 requires. - The binding includes the admitted plan reference plus the policy, work-profile, and repo-floor - references the run is allowed to operate under. + references the run is allowed to operate under, including any policy/config-selected + acceptance/review posture. - Bootstrap freezes that binding before execution wiring begins. A provider implementation may receive the bound context, but it may not widen or replace it. - The binding becomes durable only when the binding record append succeeds through the configured @@ -287,7 +292,7 @@ The binding record is one such irreversible boundary. Resume reads it; it never Bootstrap preserves the original launch binding across resume: - same run identity; -- same bound plan/policy/work-profile/repo-floor references; +- same bound plan/policy/acceptance/work-profile/repo-floor references; - same authority to continue only if the resume prerequisites remain satisfied. If bootstrap cannot prove that continuity from durable evidence, it stops rather than "helpfully" @@ -385,7 +390,7 @@ freezing a record shape: | Invariant or state rule | Bootstrap implication | Source | | ------------------------------------------- | ------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------- | -| GUARD-1 launch binding is fixed for the run | bind once before execution; do not silently widen or swap on resume | [../../product/guarantees.md](../../product/guarantees.md) | +| GUARD-1 launch binding is fixed for the run | bind once before execution, including acceptance posture; do not silently widen or swap on resume | [../../product/guarantees.md](../../product/guarantees.md) | | RESUME-3 no-double-effect | resume reads prior durable effects and never replays irreversible actions just because composition restarted | [../../product/guarantees.md](../../product/guarantees.md) | | RESUME-4 fail closed and diagnosable | storage-preflight failures stop start/resume with explicit cause | [../../product/guarantees.md](../../product/guarantees.md) | | SEE-1 run identity and visibility binding | start requires durable binding record before handoff | [../../product/guarantees.md](../../product/guarantees.md) | @@ -410,6 +415,8 @@ freezing a record shape: - binding-append failure -> stop before orchestration handoff; - missing or contradictory resume evidence -> stop instead of rebinding or replaying effects; - missing required approval evidence for resume -> stop and let the authority spine govern re-entry. +- missing required acceptance/review evidence -> stop or route according to the bound policy, never + rebind to weaker criteria. ### Observability @@ -475,6 +482,8 @@ ledger. (`run.previewed`) through the SDK/operator record path — but it commits no run: no run identity is allocated and no workspace, provider, or privileged side effects occur. - Policy (plus repo-level floors) is immutable for the life of the run once bound here. +- Acceptance/review strength selected by policy/configuration is likewise launch-bound; bootstrap + preserves that posture but does not define the future schema or reviewer implementation. - Capability-attestation depth remains seam-owned by [`authorization.md`](./authorization.md) and later provider work; bootstrap only composes that spine. diff --git a/docs/design/core/orchestration.md b/docs/design/core/orchestration.md index 09e51bf..4760dd2 100644 --- a/docs/design/core/orchestration.md +++ b/docs/design/core/orchestration.md @@ -6,8 +6,9 @@ status: draft # Orchestration — the runner The runner is jig's trusted orchestrator: it drives a launched run from start to finish, owns -the run and work-item state machines, resolves what is eligible to run next, and is the sole -holder of the privileged authority needed to land work. +the run and work-item state machines, resolves what is eligible to run next, consumes policy-bound +evidence and acceptance verdicts, and is the sole holder of the privileged authority needed to land +work. ## Owns @@ -16,6 +17,10 @@ holder of the privileged authority needed to land work. (ISO-1); a blocked item halts itself and its downstream dependents while independent work keeps moving. - Driving each eligible work item to the agent port and recording its outcome. +- Invoking and consuming any implemented verifier/reviewer lane the launch-bound policy requires, + without becoming the reviewer itself. +- Evaluating policy/evidence sufficiency for lifecycle transitions, Doorbell escalation, and Forge + invocation. - Holding credentials and the sole authority to push, open a PR, and merge (FENCE-3, MERGE-2) — the thing that writes code is never the thing that ships it. - The done/landed distinction: a work item being done (evidence met) is separate from it being @@ -24,9 +29,10 @@ holder of the privileged authority needed to land work. ## Interface Consumes the `ValidatedPlan` (from plan-intake) and the bound policy; consumes fence decisions -(grant / deny / route) and modeled evidence as inputs to its state transitions. Drives the agent -port to carry out a work item. Emits every transition and decision as an event to the records -port. +(grant / deny / route), implemented verifier/reviewer verdicts, and modeled evidence as inputs to +its state transitions. Drives the agent port to carry out a work item and invokes Forge only after +policy/evidence/acceptance gates pass. Emits every transition and decision as an event to the +records port. ## Diagram @@ -108,6 +114,9 @@ checkpoint. branch to handle defensively. - Landing — the merge step from done to landed — is exclusively runner-owned; no other 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. - 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 @@ -316,7 +325,7 @@ event-type string and no new field. | Transition | Guard | Emitted event | | -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------- | | `eligible → started` | Dependency-aware eligibility resolves: every prerequisite has **landed**, so the item may begin ([`ISO-1`](../../product/guarantees.md#32-work-level-failure-isolation), INV-005 in [`../notes/runtime-design-m5a.md`](../notes/runtime-design-m5a.md)). See the eligibility entry-guard note below. | `started` | -| `started → done` | Independent evidence aligned to the policy in force is met — never the worker's self-report ([`MERGE-1`](../../product/guarantees.md#15-merge-on-evidence); sufficiency is Policy's, [`MERGE-3`](../../product/guarantees.md#15-merge-on-evidence)). Fence `grant` is the continue-condition that lets the item stay on this path; it is not itself an edge (see below). | `done` | +| `started → done` | Independent evidence aligned to the policy in force is met — never the worker's self-report ([`MERGE-1`](../../product/guarantees.md#15-merge-on-evidence); sufficiency is Policy's, [`MERGE-3`](../../product/guarantees.md#15-merge-on-evidence)). When the launch-bound policy requires an implemented verifier/reviewer lane, that lane's verdict or evidence assessment must be one of the inputs the runner consumes before judging done. Fence `grant` is the continue-condition that lets the item stay on this path; it is not itself an edge (see below). | `done` | | `started → parked` | The Fence routes the item's request to the owner: an ambiguous, risky, or unproven action escalates through the Doorbell rather than being guessed ([`authorize → route`](authorization.md), [`DOOR-1`](../../product/guarantees.md#14-the-doorbell--approval-and-escalation)); the park is durable ([`DOOR-2`](../../product/guarantees.md#14-the-doorbell--approval-and-escalation)). | `parked` | | `started → blocked` | The Fence **denies** the item's request, fail-closed — the request is outside declared, approved scope ([`authorize → deny`](authorization.md), [`FENCE-1`](../../product/guarantees.md#11-the-fence--runtime-authorization); FAIL-002 in [`../notes/runtime-design-m5a.md`](../notes/runtime-design-m5a.md)); **or** the item cannot proceed for a recorded reason (FAIL-003 in [`../notes/runtime-design-m5a.md`](../notes/runtime-design-m5a.md)) — treating an unmet evidence gate as one such non-proceeding reason is a **(modeling decision)**, see the open question below. | `blocked` | | `parked → started` | The owner resolves the escalation in favour of proceeding; the narrow grant is scoped to the need in front of the run ([`DOOR-3`](../../product/guarantees.md#14-the-doorbell--approval-and-escalation)). | `unparked` | @@ -382,16 +391,23 @@ guards, so they are recorded as properties of a state rather than forced into a ([`FENCE-3`](../../product/guarantees.md#11-the-fence--runtime-authorization), [`MERGE-2`](../../product/guarantees.md#15-merge-on-evidence)) — the existing "Owns" prose above, restated here as it governs the `done → landed` guard. +- **Review is governed evidence input, not worker self-certification.** A verifier/reviewer may be a + human, agent, or deterministic checker, but the worker does not review itself as sufficient proof; + the reviewer does not land work or move lifecycle state; and missing, stale, self-reported, or + inconclusive review evidence routes through policy to Doorbell or stop rather than lowering the + done guard. ### Two authority mechanisms across this table -The closed table exercises the two authority mechanisms this area holds, and must not collapse -them (INV-008 in [`../notes/runtime-design-m5a.md`](../notes/runtime-design-m5a.md)): (a) the -**Fence** adjudicates each worker request into `grant | deny | route`, which the table consumes -as the guard on `started`'s exits; and (b) at **landing**, the **runner-exclusive** push/PR/merge -action gates `done → landed`. These are distinct authorities — Fence adjudication governs whether -an action is allowed; runner-owned landing governs whether the merge fires — and no single row -conflates them. +The closed table exercises the authority mechanisms this area holds, and must not collapse them +(INV-008 in [`../notes/runtime-design-m5a.md`](../notes/runtime-design-m5a.md)): (a) the +**Fence** adjudicates each worker request into `grant | deny | route`, which the table consumes as +the guard on `started`'s exits; (b) the **review/verification lane**, when implemented and required +by policy, emits verdict/evidence assessment for the runner to consume; and (c) at **landing**, the +**runner-exclusive** push/PR/merge action gates `done → landed`. These are distinct authorities — +Fence adjudication governs whether an action is allowed; review/verification assesses work or +evidence without landing it; runner-owned landing governs whether the merge fires — and no single +row conflates them. **Phase 5 realization ([ADR 0021](../decisions/0021-phase-5-integrated-provider-runs.md)).** The runner-exclusive landing at `done → landed` is invoked through the `ForgePort` seam diff --git a/docs/design/core/plan-intake.md b/docs/design/core/plan-intake.md index e956c17..34295cc 100644 --- a/docs/design/core/plan-intake.md +++ b/docs/design/core/plan-intake.md @@ -11,9 +11,10 @@ intent. It is the boundary [`bootstrap`](./bootstrap.md) calls before anything e This doc is the home for the plan / policy / evidence design beneath the `PlanValidator` port: the port surface and its diagram, plus the owned domain content underneath — parse/validate/reject -mechanics, the policy model, the evidence/attestation category model, and the GUARD-2 rule -declaration. The execution-plan v0 contract remains cited and unfrozen; `authorization.md` remains -the enforcement sibling, and `orchestration.md` remains the pause-point sibling. +mechanics, the policy model, the evidence/attestation category model, acceptance/review +expectations, and the GUARD-2 rule declaration. The execution-plan v0 contract remains cited and +unfrozen; `authorization.md` remains the enforcement sibling, and `orchestration.md` remains the +pause-point sibling. ## Owns @@ -213,6 +214,8 @@ The most important contract properties for this deepened design are: than embedding a mutable override. - **Done and evidence requirements** — a plan carries evidence categories and references, while policy later judges sufficiency. +- **Acceptance / review expectations** — a plan can carry declared review needs, while + owner-controlled policy/configuration selects the required acceptance strength before launch. - **Authority and approval needs** — a plan declares expected reversible, privileged, and rule-governing touches so later authorization can fail closed. @@ -228,6 +231,9 @@ later consumes. boundary promised by `CFG-10`. - **Merge spectrum** — the evidence posture that must be satisfied before a story may move from done to landed. +- **Acceptance / review lane strength** — the review or verification posture required before + landing, selected before launch and consumed as evidence rather than chosen by the worker, + reviewer, or Forge provider mid-run. - **Concurrency ceiling** — the highest concurrency the run may derive, subject to plan and other safety constraints. - **Retry budget** — whether and how much retry behavior is allowed before a human checkpoint is @@ -244,6 +250,8 @@ later consumes. work profile tunes realization and may not lower that floor (`CFG-1`, `CFG-2`). - **Policy is fixed at launch.** A run binds to policy at launch and does not silently widen or swap it mid-run (`GUARD-1`). +- **Acceptance strength is launch-bound.** Worker, reviewer, and Forge provider cannot downgrade the + required acceptance/review lane after launch. - **The `CFG-10` category boundary is fixed.** The reversible/non-privileged/non-rule-governing versus credentials/push-merge/rule-governing/irreversible split is a product promise, not a model-adjudicated runtime judgment. @@ -257,6 +265,8 @@ later consumes. - Work-item or run pause-state mechanics; those remain in [`orchestration.md`](./orchestration.md)'s settled lifecycle territory. - Field-level plan schema; that remains with the cited v0 contract. +- Detailed acceptance-lane schema, reviewer taxonomy, or provider method signatures; those remain + future implementation/design follow-up. ## Evidence / attestation category model @@ -273,16 +283,21 @@ observes directly. Their category semantics are: - a missing or failed required check leaves the story short of done-evidence, regardless of worker confidence. -### Category 2 — review +### Category 2 — review / acceptance -Review is an approval from a human or delegated reviewer that policy requires. Its 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. +Its category semantics are: - policy decides whether review is required and for which classes of change; +- policy/configuration select the required acceptance strength before launch, not during the run; - review is durable evidence only when recorded through the runtime's owned approval / notice surfaces, not when asserted informally by the worker; - review may satisfy part of a story's evidence posture without collapsing the done-versus-landed distinction. +- the reviewer/verifier emits an assessment; it does not land work, hold forge credentials, + redefine policy, or select weaker criteria. ### Category 3 — capability proof @@ -306,6 +321,8 @@ The required sufficiency rules are: - policy may require one, two, or all three categories depending on story class and risk; - `done` and `landed` remain separate milestones even when a story's evidence is already satisfied; +- a required review/acceptance lane must be satisfied by the governed verifier/reviewer verdict or + assessment before it can contribute to `done`; - capability proof never substitutes for unrelated automated checks or required review unless the policy explicitly treats it as evidence for that capability-specific trust question. @@ -337,6 +354,8 @@ This design keeps one authority for what counts as evidence: - **The runner and its owned runtime surfaces observe evidence directly.** Evidence is never taken from the worker's self-report alone. +- **The verifier/reviewer emits governed evidence input.** Its verdict can be consumed by the + runner and policy, but it does not author lifecycle transitions or landing authority. - **The records surface persists what was observed.** This file names the category vocabulary; it does not create a second persistence channel. - **Authorization and lifecycle consume the resulting judgments.** This file does not move those @@ -389,9 +408,10 @@ then declare itself done. named reason. - Rejection is terminal for intake of that submitted instance: no run is created from it. - Contract-shape mismatch is handled as a seam-governance issue, not as local silent coercion. -- Insufficient evidence, stale capability proof, missing capability proof, or unresolved GUARD-2 - re-approval are not parse failures; they are later runtime failure/judgment conditions defined by - the policy/evidence model this file owns and consumed by sibling runtime docs. +- Insufficient evidence, stale capability proof, missing capability proof, missing or inconclusive + required acceptance/review evidence, or unresolved GUARD-2 re-approval are not parse failures; + they are later runtime failure/judgment conditions defined by the policy/evidence model this file + owns and consumed by sibling runtime docs. ## Port-boundary invariant candidates @@ -428,6 +448,8 @@ available invariant number is `INV-019`. - **Evidence is observed, never self-certified.** A worker's self-report alone cannot satisfy the evidence posture policy requires for landing. +- **Acceptance strength is owner-bound.** Required review/verification strength is selected by + policy/configuration before launch; worker, reviewer, and Forge provider cannot weaken it mid-run. - **Capability proof must be fresh for the current driver/run context.** Missing or stale proof reduces autonomy rather than weakening the guarantee. - **Touching a rule-governing surface forces pause-before-completion.** A run may not change the diff --git a/docs/design/core/records.md b/docs/design/core/records.md index 237d4fa..f8bb5e5 100644 --- a/docs/design/core/records.md +++ b/docs/design/core/records.md @@ -5,8 +5,9 @@ status: draft # Records — the event-log engine -Produces the durable, ordered, redaction-aware records that are the evidence itself. State and -summary are never authored directly — they are pure projections replayed from the log. +Produces the durable, ordered, redaction-aware records that are the evidence itself, including +governed acceptance/review verdicts when an implemented lane emits them. State and summary are +never authored directly — they are pure projections replayed from the log. ## Owns @@ -16,6 +17,8 @@ summary are never authored directly — they are pure projections replayed from - Redaction posture recorded per record. - Export: a write-once, redacted artifact a finished run produces. - The source data for notices and for "ask why" — both read from the same log, nothing parallel. +- The durable evidence posture for acceptance/review verdicts and supporting evidence, without + freezing a new record schema here. ## Interface @@ -142,7 +145,7 @@ for the projections and exports core already relies on. ### A caller or consumer implements - Emitting governed events into this port from already-settled core callers such as the runner and - cited authorization path. + cited authorization path, and governed verifier/reviewer lanes once implemented. - Reading projections, inspect/ask-why views, notices, or export outputs derived from the same log. ### Must not @@ -158,8 +161,9 @@ for the projections and exports core already relies on. This doc does not author any new state or transition. It names the already-settled emission points only: `RunStore` receives the events emitted from the cited run/work-item lifecycle flow in -[`orchestration.md`](./orchestration.md), along with cited authorization outcomes as sources. The -port boundary here is the durable append and replay surface those existing callers use. +[`orchestration.md`](./orchestration.md), along with cited authorization outcomes and implemented +acceptance/review verdicts as sources. The port boundary here is the durable append and replay +surface those existing callers use. ## Relationship to the observability-records v0 contract @@ -206,6 +210,8 @@ inspects and the runner decides from, satisfying the "records are the evidence" ## Redaction and evidence posture - Records are the evidence Jig decides from and the evidence the owner inspects afterward. +- Acceptance/review verdicts and their supporting evidence are durable evidence inputs when policy + requires them; they do not create a second narrative outside the log. - Secrets, credentials, tokens, and sensitive values are omitted or redacted before governed record persistence, not merely before later surfacing; the redaction posture is part of the governed record path, not an optional afterthought. @@ -297,11 +303,13 @@ Records remains the durable evidence substrate for both runtime decisions and la history; - export produces a write-once redacted artifact from that same history; - downstream consumers read the records/evidence surface but do not redefine it. +- 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 surface is also a downstream contract for the execution-host seam. The capability / attestation -event families already named in the cited observability-records v0 contract 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 freezing new fields here. +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 +freezing new fields here. ## Failure posture @@ -331,6 +339,8 @@ available invariant number is `INV-019`. derived from replay and do not become append authorities. - **No parallel narrative.** The explanation of what happened remains reconstructible from records rather than a separate mutable story. +- **Review verdicts are evidence inputs.** Acceptance/review results are appended through the + governed evidence path when implemented; they do not authorize landing by themselves. - **Redaction is governed at the boundary.** Surfaced records and exports preserve the safety posture of the evidence stream instead of bypassing it later. - **Unknown redaction/export posture is fail-closed.** A governed append without valid posture is @@ -357,6 +367,9 @@ available invariant number is `INV-019`. model pipelines remain out of scope until a later proof gate justifies them. - **Deferred — export encoding and downstream analytics shape.** External representation details and between-runs consumption stay downstream of this port contract. +- **Deferred — acceptance/review record detail.** If the richer acceptance/review lane needs new + event families or fields, that belongs in a future records-contract design change; this pass only + names the durable evidence posture. - **Deferred — replay-drift handling surface.** This file names replay drift as a correctness failure, but not yet whether later design work surfaces it as a stop token, notice, export denial, or another diagnosable outcome. diff --git a/docs/design/security-model.md b/docs/design/security-model.md index a5e64e8..e347958 100644 --- a/docs/design/security-model.md +++ b/docs/design/security-model.md @@ -17,14 +17,15 @@ threat-model view rather than per-seam prose. ## Trust model — who is trusted, who is not -| Party | Trust status | Why | -| ------------------------------------------- | --------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| Jig-core (runner, fence, doorbell, records) | Trusted | The runner is jig's trusted orchestrator: it holds credentials, is the sole authority to push/PR/merge, and performs irreversible actions only under policy and evidence ([`core/README.md`](./core/README.md) §B; FENCE-3, MERGE-2, SEC-3). | -| Agent / worker (Agent seam) | Untrusted | A contained coding agent: reads a work item, writes code, runs checks, reports — holds no credentials and cannot push/PR/merge or widen its own authority ([`contracts/providers.md`](./contracts/providers.md) "Agent port"; FENCE-3). | -| Execution host | Untrusted until proven | Provides isolation/containment for the worker; its isolation strength is a claim until proven, judged by `provenIsolationStrength`, not `reportedIsolationStrength` ([`core/authorization.md`](./core/authorization.md) "Phase 6 realization"; DRIVE-3, ISO-4). | -| Forge (code host) | Untrusted, runner-invoked only | Respects branch protection and merge queues as real governing constraints; only the runner invokes push/PR/merge through it ([`contracts/providers.md`](./contracts/providers.md) "Forge port"; MERGE-2, MERGE-5). | -| Work source | Untrusted, never a scheduling authority | May supply provenance/import behavior, but the validated execution plan is jig's only runtime scheduling input; the seam never bypasses `PlanValidator` ([`contracts/providers.md`](./contracts/providers.md) "Work source port"; INV-007). | -| Owner / operator | Trusted decision-maker | Authors policy and plan, and is the one party whose approval can grant a routed request or a re-approval ([`core/authorization.md`](./core/authorization.md) "Doorbell escalation"; DOOR-1..3). | +| Party | Trust status | Why | +| ------------------------------------------- | --------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Jig-core (runner, fence, doorbell, records) | Trusted | The runner is jig's trusted orchestrator: it holds credentials, is the sole authority to push/PR/merge, and performs irreversible actions only under policy and evidence ([`core/README.md`](./core/README.md) §B; FENCE-3, MERGE-2, SEC-3). | +| Agent / worker (Agent seam) | Untrusted | A contained coding agent: reads a work item, writes code, runs checks, reports — holds no credentials and cannot push/PR/merge or widen its own authority ([`contracts/providers.md`](./contracts/providers.md) "Agent port"; FENCE-3). | +| Verifier / reviewer | Governed evidence assessor | Emits an acceptance verdict or evidence assessment when launch-bound policy requires an implemented review lane; it does not land work, hold forge credentials, redefine policy, or transition lifecycle directly ([`core/orchestration.md`](./core/orchestration.md); MERGE-1, MERGE-3). | +| Execution host | Untrusted until proven | Provides isolation/containment for the worker; its isolation strength is a claim until proven, judged by `provenIsolationStrength`, not `reportedIsolationStrength` ([`core/authorization.md`](./core/authorization.md) "Phase 6 realization"; DRIVE-3, ISO-4). | +| Forge (code host) | Untrusted, runner-invoked only | Deterministic adapter for push/PR/status/comment/merge; respects branch protection and merge queues as real governing constraints; only the runner invokes it ([`contracts/providers.md`](./contracts/providers.md) "Forge port"; MERGE-2, MERGE-5). | +| Work source | Untrusted, never a scheduling authority | May supply provenance/import behavior, but the validated execution plan is jig's only runtime scheduling input; the seam never bypasses `PlanValidator` ([`contracts/providers.md`](./contracts/providers.md) "Work source port"; INV-007). | +| Owner / operator | Trusted decision-maker | Authors policy and plan, and is the one party whose approval can grant a routed request or a re-approval ([`core/authorization.md`](./core/authorization.md) "Doorbell escalation"; DOOR-1..3). | The single organizing idea: **jig-core is the only trusted party at runtime.** Every provider seam (agent, execution host, forge, work source) is an untrusted, swappable boundary that jig-core @@ -32,7 +33,8 @@ governs, never a party jig-core takes on faith ([`contracts/providers.md`](./con "Contract stance"). Landing credentials and irreversible authority stay on the trusted side of that 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. +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. ## The fence + fail-closed authorization spine @@ -43,6 +45,8 @@ boundary"; FENCE-1, FENCE-2). Its decision order is: 1. Undeclared or out-of-approved-scope → `deny` (fail-closed; FENCE-1). 2. Credentials, push/merge, rule-governing touch, irreversible effect, ambiguity, or insufficient proof → `route` to the Doorbell. + Missing, stale, self-reported, or inconclusive required acceptance/review evidence follows the + same fail-closed posture. 3. Declared, reversible, non-privileged, and not rule-governing, with sufficient proof → `grant` candidate. 4. If the classifier cannot justify `grant` from the fixed rules, `route` — uncertainty never @@ -127,6 +131,8 @@ Only the runner holds landing credentials and the sole authority to push, open P never invokes landing authority directly, and a Forge adapter cannot become a second policy or state authority for merge decisions ([`contracts/providers.md`](./contracts/providers.md) "Forge port"). +- The **Verifier/reviewer** lane never holds landing credentials and never invokes Forge directly; + it emits an assessment the runner consumes under policy. This is the same posture stated in the product guarantee: "the thing that writes code is not the thing that ships it" (MERGE-2), and "the thing writing code is never the thing holding the keys" @@ -156,6 +162,9 @@ the host or the worker ([`contracts/providers.md`](./contracts/providers.md) "Ex may ask for, attestation proves what the host actually confines ([`core/authorization.md`](./core/authorization.md) "Phase 6 realization"). +The verifier/reviewer lane does not carry SEC-2. It may assess evidence, but execution-host +confinement remains the host/core proof boundary; Forge remains the external-operation adapter. + The execution host is described in the design as "local-first today" ([`core/README.md`](./core/README.md) §C), so the honesty posture above is the guarantee that must hold as hosting substrates change, not a claim that today's default host is strongly isolated. @@ -206,17 +215,18 @@ exports (SEC-1). This is enforced at the records boundary, not left to later sur ## Threat surfaces and how they are contained -| Threat surface | Containment | -| ------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| Worker tries to widen its own authority or act outside scope | Fence denies by fixed CFG-10 category, fail-closed on anything undeclared or unapproved; the boundary is never model-adjudicated (FENCE-1, FENCE-2; [`core/authorization.md`](./core/authorization.md)). | -| Worker tries to push, open a PR, or merge directly | Structurally impossible: the Agent port has no privileged method (`INV-002`), checked by a conformance forbidden-method sweep; landing is runner-invoked only through the Forge seam (FENCE-3, MERGE-2; [`contracts/providers.md`](./contracts/providers.md)). | -| Provider over-reports capability or isolation strength | Capability attestation and execution-host proof are judged on **proven**, not reported, strength; an overstated report is recorded and unlocks nothing beyond what was proven (DRIVE-3, EARN-1/2; [`core/authorization.md`](./core/authorization.md)). | -| A run tries to change its own governing rules and call itself done | GUARD-2: a rule-governing touch pauses completion for fresh owner re-approval and evidence, enforced by the Fence/Doorbell and consumed by the run lifecycle (GUARD-2; [`core/plan-intake.md`](./core/plan-intake.md), [`core/authorization.md`](./core/authorization.md)). | -| Secrets leak into records, logs, or exports | Redaction posture is governed per record at append time; unknown/ambiguous posture is rejected, and export stays write-once and redacted-by-default (SEC-1, SEE-6; [`core/records.md`](./core/records.md)). | -| Worker attempts outbound network access ("phone home") | Execution-host confinement must be proven (exercised check), not merely reported; core judges on proven isolation strength (SEC-2, DRIVE-3; [`core/authorization.md`](./core/authorization.md), [`contracts/providers.md`](./contracts/providers.md)). | -| A conformance-green mock is mistaken for a truthful real provider | ADR 0026: `self-report-only` is a distinct, non-passing basis token; a green controlled-double suite is explicitly not proof of real-provider truth (ADR 0026). | -| Resumed run tries to widen scope on a stale or changed basis | Resume adjudicates against the **launch** attestation and policy binding; a broken integrity chain hard-refuses with no override, and a legitimate changed basis blocks pending fresh owner re-approval — never a silent rebind (GUARD-1; [`core/authorization.md`](./core/authorization.md) "Phase 9 realization"; ADR 0025). | -| Work source or forge tries to bypass validated scheduling / policy | Work source candidates cross `PlanValidator` before reaching runtime scheduling (INV-007); Forge cannot re-judge evidence sufficiency or become a second policy authority (`contracts/providers.md`). | +| Threat surface | Containment | +| ------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Worker tries to widen its own authority or act outside scope | Fence denies by fixed CFG-10 category, fail-closed on anything undeclared or unapproved; the boundary is never model-adjudicated (FENCE-1, FENCE-2; [`core/authorization.md`](./core/authorization.md)). | +| Worker tries to push, open a PR, or merge directly | Structurally impossible: the Agent port has no privileged method (`INV-002`), checked by a conformance forbidden-method sweep; landing is runner-invoked only through the Forge seam (FENCE-3, MERGE-2; [`contracts/providers.md`](./contracts/providers.md)). | +| Worker or reviewer tries to self-certify acceptance | Required acceptance/review evidence must come from the governed lane policy selected before launch, not from worker self-report or reviewer-selected weaker criteria; missing or inconclusive proof routes/stops rather than lowering policy (MERGE-1, MERGE-3; [`core/plan-intake.md`](./core/plan-intake.md), [`core/orchestration.md`](./core/orchestration.md)). | +| Provider over-reports capability or isolation strength | Capability attestation and execution-host proof are judged on **proven**, not reported, strength; an overstated report is recorded and unlocks nothing beyond what was proven (DRIVE-3, EARN-1/2; [`core/authorization.md`](./core/authorization.md)). | +| A run tries to change its own governing rules and call itself done | GUARD-2: a rule-governing touch pauses completion for fresh owner re-approval and evidence, enforced by the Fence/Doorbell and consumed by the run lifecycle (GUARD-2; [`core/plan-intake.md`](./core/plan-intake.md), [`core/authorization.md`](./core/authorization.md)). | +| Secrets leak into records, logs, or exports | Redaction posture is governed per record at append time; unknown/ambiguous posture is rejected, and export stays write-once and redacted-by-default (SEC-1, SEE-6; [`core/records.md`](./core/records.md)). | +| Worker attempts outbound network access ("phone home") | Execution-host confinement must be proven (exercised check), not merely reported; core judges on proven isolation strength (SEC-2, DRIVE-3; [`core/authorization.md`](./core/authorization.md), [`contracts/providers.md`](./contracts/providers.md)). | +| A conformance-green mock is mistaken for a truthful real provider | ADR 0026: `self-report-only` is a distinct, non-passing basis token; a green controlled-double suite is explicitly not proof of real-provider truth (ADR 0026). | +| Resumed run tries to widen scope on a stale or changed basis | Resume adjudicates against the **launch** attestation and policy binding; a broken integrity chain hard-refuses with no override, and a legitimate changed basis blocks pending fresh owner re-approval — never a silent rebind (GUARD-1; [`core/authorization.md`](./core/authorization.md) "Phase 9 realization"; ADR 0025). | +| Work source or forge tries to bypass validated scheduling / policy | Work source candidates cross `PlanValidator` before reaching runtime scheduling (INV-007); Forge cannot re-judge evidence sufficiency or become a second policy authority (`contracts/providers.md`). | ## Trust-boundary diagram @@ -258,6 +268,12 @@ governed, redacted, append-only`") fence ~~~ doorbell ~~~ runner ~~~ records end + subgraph governed["Governed lane — independent assessment"] + direction LR + review("`**Verifier / reviewer** +verdict only`") + end + subgraph untrusted["Untrusted — provider seams (governed at the boundary)"] direction LR worker("`**Agent / worker** @@ -277,6 +293,7 @@ never bypasses PlanValidator`") fence -->|route| doorbell fence -->|deny, fail-closed| deny("`**Deny**`") doorbell -->|narrow grant| runner + review -->|verdict / evidence assessment| runner runner -->|push / PR / merge| forge runner -->|contains + drives| worker worker -.->|runs inside| host @@ -290,25 +307,29 @@ runtime scheduling input`") subgraph legend[" "] direction LR - l1(" ") ~~~ lt1["trusted (jig-core)"] ~~~ l2(" ") ~~~ lt2["untrusted (provider seam)"] ~~~ l3(" ") ~~~ lt3["owner"] + l1(" ") ~~~ lt1["trusted (jig-core)"] ~~~ l2(" ") ~~~ lt2["governed lane"] ~~~ l3(" ") ~~~ lt3["untrusted (provider seam)"] ~~~ l4(" ") ~~~ lt4["owner"] end style legend fill:transparent,stroke:transparent,color:transparent classDef coreBox fill:#e3f6f0,stroke:#007a62,stroke-width:2px,color:#003f34,rx:16,ry:16; + classDef governedBox fill:#f5eefc,stroke:#6b3fa0,stroke-width:2px,color:#32194f,rx:16,ry:16; classDef seamBox fill:#fff0ea,stroke:#a43f22,stroke-width:2px,color:#4d1f12,rx:16,ry:16; classDef commonBox fill:#f6f4ed,stroke:#77736d,stroke-width:2px,color:#2b2b2b,rx:16,ry:16; classDef legendCore fill:#e3f6f0,stroke:#007a62,stroke-width:2px,color:#003f34,rx:6,ry:6; + classDef legendGoverned fill:#f5eefc,stroke:#6b3fa0,stroke-width:2px,color:#32194f,rx:6,ry:6; classDef legendSeam fill:#fff0ea,stroke:#a43f22,stroke-width:2px,color:#4d1f12,rx:6,ry:6; classDef legendOwner fill:#f6f4ed,stroke:#77736d,stroke-width:2px,color:#2b2b2b,rx:6,ry:6; classDef legendText fill:transparent,stroke:transparent,color:#666666; class fence,doorbell,runner,records,plan coreBox; + class review governedBox; class worker,host,forge,source seamBox; class owner,deny commonBox; class l1 legendCore; - class l2 legendSeam; - class l3 legendOwner; - class lt1,lt2,lt3 legendText; + class l2 legendGoverned; + class l3 legendSeam; + class l4 legendOwner; + class lt1,lt2,lt3,lt4 legendText; ``` ## Honest edge diff --git a/docs/product/README.md b/docs/product/README.md index 0cde17b..eb89892 100644 --- a/docs/product/README.md +++ b/docs/product/README.md @@ -20,7 +20,7 @@ verified (see [`docs/design/`](../design/)). | [jig.md](./jig.md) | **Canonical hub** — audience, job, problem, promise, workflow, the guarantee summary, boundaries, success signals, and open product questions. Start here. | | [guarantees.md](./guarantees.md) | **The five guarantees in detail** — the full, ID-bearing specification (FENCE, EARN, GUARD, DOOR, MERGE, SEC, CFG, RESUME, ISO, LIVE, STACK, DRIVE, SEE). | | [use-cases.md](./use-cases.md) | **Worked scenarios** — overnight delivery, the doorbell, safe resume, swapping your agent — each making one guarantee concrete. | -| [concepts.md](./concepts.md) | Cross-cutting product concepts users need: **tracks**, stories, runner/worker authority, SDK boundaries, providers, and conformance. | +| [concepts.md](./concepts.md) | Cross-cutting product concepts users need: **tracks**, stories, runner/worker/verifier authority, SDK boundaries, providers, and conformance. | ## Where Jig sits in the suite diff --git a/docs/product/concepts.md b/docs/product/concepts.md index 21b271a..126adc4 100644 --- a/docs/product/concepts.md +++ b/docs/product/concepts.md @@ -69,23 +69,31 @@ The decomposition nests cleanly: - a **story** is one landed change with its own done conditions; - **policy** and **work profile** are set per track and govern how its stories run. -## Runner and worker — the authority boundary +## Runner, worker, and verifier — the authority boundary -Two roles carry Jig's control boundary, and the difference between them is what makes delegation +Three roles carry Jig's control boundary, and the difference between them is what makes delegation safe: - The **worker** is the contained coding agent — the thing that reads a story, writes code, and - runs checks. It is the **Agent** seam, executing inside the **Execution Host** seam. The worker - is _contained_: it never holds privileged credentials and cannot push, open a PR, merge, or - widen its own authority. + runs requested checks. It is the **Agent** seam, executing inside the **Execution Host** seam. + The worker is _contained_: it never holds privileged credentials and cannot push, open a PR, + merge, choose or weaken acceptance level, decide evidence sufficiency, review itself as + sufficient proof, or widen its own authority. +- The **verifier/reviewer** is the independent acceptance lane the product model lets + owner-controlled policy and configuration select before launch. It may be a human, agent, or + deterministic checker; it assesses evidence, diff, or output and emits a verdict for Jig to + consume when that lane is implemented for the selected policy. It does not land work, hold + privileged forge credentials, redefine policy, or create lifecycle transitions directly. - The **runner** is Jig's own trusted component. It holds privileged authority — credentials, and the power to push, open PRs, and merge — and performs those irreversible actions on the worker's - behalf, only under policy and evidence gates. The runner is **Jig-core, not a seam**: the four - swappable seams (guarantee 4) are Agent, Execution Host, Forge, and Work Source; the runner is - the fixed part that governs them. + behalf, only under policy, evidence, and acceptance gates. It orchestrates lifecycle, enforces + policy, consumes evidence/verdicts, escalates through the Doorbell, records decisions, and + invokes providers. The runner is **Jig-core, not a seam**: the four swappable seams (guarantee 4) + are Agent, Execution Host, Forge, and Work Source; the runner is the fixed part that governs + them. It is not a code-review engine, forge API implementation, or worker implementation. -This split is the spine of guarantee 1 — the thing that writes code is never the thing that ships -it (FENCE-3, MERGE-2, SEC-3). +This split is the spine of guarantee 1 — the thing that writes code is not the thing that reviews +it as sufficient proof or ships it (FENCE-3, MERGE-1, MERGE-2, SEC-3). ```mermaid %%{init: { @@ -105,11 +113,14 @@ flowchart TB worker("`**Worker** — contained coding agent reads a story, writes code, runs checks no credentials; cannot push, PR, or merge`") + verifier("`**Verifier / reviewer** +independent acceptance lane +emits verdict; cannot land`") subgraph core["Jig core — fixed, trusted"] runner("`**Runner** -holds credentials; performs push / PR / merge -only under policy + evidence gates`") +orchestrates, enforces policy, +invokes providers after gates`") end subgraph seams["Four swappable seams (guarantee 4)"] @@ -121,6 +132,8 @@ only under policy + evidence gates`") end worker -->|"runs as the Agent, inside the Execution Host"| agent + runner -.->|"target acceptance lane"| verifier + verifier -->|"verdict / evidence assessment"| runner runner -->|"governs, under gates"| agent runner --> host runner --> forge @@ -132,7 +145,7 @@ only under policy + evidence gates`") class runner core; class agent,host,forge,source seam; - class worker contained; + class worker,verifier contained; ``` ## SDK, providers, and conformance @@ -150,6 +163,12 @@ needs, and proves what it can safely do before Jig grants autonomy. A bundled pr gets no privileged shortcut a future extracted or custom provider couldn't use: it earns autonomy through the same declared authority and conformance proof at the boundary. +A **Forge provider** is deterministic adapter capability behind the Forge seam. It performs external +forge operations such as push, PR/status/comment, merge, idempotency handling, and API translation +only when the Runner invokes it under the policy gate for that operation. Opening or updating a PR +may be how a configured review lane gets evidence; merge/landing remains gated on the required +acceptance verdict. Forge is not another agent and does not decide what should happen. + The **conformance surface** is the repeatable proof behind that trust. It gives Jig and provider authors a shared way to check capability, containment, declared authority, and adversarial cases. The product need is reusable proof before trust; whether the supporting surface is internal-only, @@ -233,19 +252,26 @@ resume from their last safe checkpoint"] One-line definitions of the product terms used across these pages. Each links to its fuller treatment. -| Term | Meaning | -| --------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| **Track** | One independent line of work — its own plan, policy, and work profile — running in parallel with other tracks in the same repo. See [Tracks](#tracks--parallel-independent-work). | -| **Execution plan** | Jig's one hard input: a set of stories with their dependencies and done conditions, one per track. See [the execution plan](./jig.md#the-execution-plan--jigs-one-input). | -| **Story** | The unit of work Jig runs and lands: one reviewable change with its own done conditions. Design calls it a _work item_. See [Stories](#stories--the-unit-of-work). | -| **Policy** | The per-track safety contract — gating posture, merge spectrum, required reviews, approvals, anti-gaming floor. Changing it is itself governed (guarantee 2, CFG-1). | -| **Work profile** | The per-track realization — model, effort, prompt strategy, role realization. Freely tunable; it cannot lower the safety floor (CFG-2). | -| **Repo-level floors** | A repo-scoped policy artifact setting minimums every track inherits and can tighten but not weaken (CFG-3). | -| **Runner** | Jig's fixed, trusted core: holds credentials and performs push, PR, and merge under policy and evidence gates. Not a seam. | -| **Worker** | The contained coding agent: reads a story, writes code, runs checks. Holds no credentials and cannot ship its own work. | -| **Seam** | One of four swappable integration boundaries — Agent, Execution Host, Forge, Work Source (guarantee 4, STACK-2). | -| **Provider / driver** | An implementation behind a seam. _Provider_ is the product term; the guarantee detail says _driver_ for a concrete trusted implementation. | -| **Doorbell** | The escalation point where a run parks for an owner decision — approve, reject, override, or hand off (guarantee 1, DOOR-1). | -| **Conformance** | The repeatable proof — capability, containment, declared authority, adversarial probes — a provider passes before Jig grants autonomy (DRIVE-1, DRIVE-4). | -| **SDK boundary** | Jig's stable programmatic surface for first-party consumers (CLI today, MCP later), used instead of reaching into internals. | -| **done vs landed** | _done_ = evidence met, merge pending; _landed_ = merged on evidence. Separate milestones (MERGE-4). | +| Term | Meaning | +| ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| **Track** | One independent line of work — its own plan, policy, and work profile — running in parallel with other tracks in the same repo. See [Tracks](#tracks--parallel-independent-work). | +| **Execution plan** | Jig's one hard input: a set of stories with their dependencies and done conditions, one per track. See [the execution plan](./jig.md#the-execution-plan--jigs-one-input). | +| **Story** | The unit of work Jig runs and lands: one reviewable change with its own done conditions. Design calls it a _work item_. See [Stories](#stories--the-unit-of-work). | +| **Config** | Owner-controlled run/repo wiring: provider selection, track setup, work profile, and operating posture chosen before launch. | +| **Policy** | The per-track safety contract — gating posture, merge spectrum, acceptance strength, required reviews, approvals, anti-gaming floor. Changing it is itself governed (guarantee 2, CFG-1). | +| **Work profile** | The per-track realization — model, effort, prompt strategy, role realization. Freely tunable; it cannot lower the safety floor (CFG-2). | +| **Repo-level floors** | A repo-scoped policy artifact setting minimums every track inherits and can tighten but not weaken (CFG-3). | +| **Runner** | Jig's fixed, trusted core: orchestrates lifecycle, enforces policy, consumes evidence/verdicts, records decisions, and invokes providers after gates pass. Not a seam. | +| **Worker** | The contained implementer: reads a story, writes code, runs requested checks, and reports evidence. Holds no credentials and cannot ship, self-review, or lower policy. | +| **Verifier / reviewer** | Independent acceptance lane that assesses evidence, diff, or output and emits a verdict; it cannot land work, hold forge credentials, redefine policy, or create transitions directly. | +| **Fence** | Runtime authorization: approves, denies, or routes worker requests before execution. | +| **Seam** | One of four swappable integration boundaries — Agent, Execution Host, Forge, Work Source (guarantee 4, STACK-2). | +| **Provider / driver** | An implementation behind a seam. _Provider_ is the product term; the guarantee detail says _driver_ for a concrete trusted implementation. | +| **Forge provider** | Deterministic adapter behind the Forge seam for Runner-invoked push, PR/status/comment, merge, idempotency, and API translation. | +| **Execution host** | The seam that contains the worker and proves the isolation/no-phone-home posture policy relies on. | +| **Work source** | The seam that supplies candidate work and provenance; it never bypasses plan validation. | +| **Doorbell** | The escalation point where a run parks for an owner decision — approve, reject, override, or hand off (guarantee 1, DOOR-1). | +| **Records** | Durable evidence trail for governed decisions, evidence, acceptance verdicts, stops, and outcomes. | +| **Conformance** | The repeatable proof — capability, containment, declared authority, adversarial probes — a provider passes before Jig grants autonomy (DRIVE-1, DRIVE-4). | +| **SDK boundary** | Jig's stable programmatic surface for first-party consumers (CLI today, MCP later), used instead of reaching into internals. | +| **done vs landed** | _done_ = evidence met, merge pending; _landed_ = merged on evidence. Separate milestones (MERGE-4). | diff --git a/docs/product/guarantees.md b/docs/product/guarantees.md index cb42e6b..fb4e793 100644 --- a/docs/product/guarantees.md +++ b/docs/product/guarantees.md @@ -29,9 +29,11 @@ spine, and where Jig fits in the suite, start at ## 1. Control & trust -**Intended behavior.** The agent is a contained worker. It can request work, produce code, run -checks, and report progress, but it cannot expand its own authority or land changes by -self-report. Jig is responsible for keeping the authority boundary real. +**Intended behavior.** Jig is a delivery harness, not a coding agent with shipping authority. The +agent is a contained worker. It can request work, produce code, run requested checks, and report +progress/evidence, but it cannot expand its own authority, decide evidence sufficiency, choose or +weaken acceptance level, review itself as sufficient proof, or land changes by self-report. Jig is +responsible for keeping the authority boundary real. ### 1.1 The fence — runtime authorization @@ -70,17 +72,19 @@ self-report. Jig is responsible for keeping the authority boundary real. **What counts as evidence.** At product altitude, evidence falls into three categories: (a) **automated checks** — tests, builds, linters, and gates the runner observes directly, never -taken from the worker's word; (b) **review** — an approval from a human or delegated reviewer -the policy requires; and (c) **capability proof** — fresh attestation that a driver can safely -perform what is being trusted (see [earned trust](#12-earned-trust--capability-attestation)). -Policy decides which categories, and how much of each, a story needs before it may land. +taken from the worker's word; (b) **review / acceptance** — a verdict or evidence assessment from +the independent lane policy requires, such as a mechanical evidence check, structured independent +review, real code review, owner review, or specialist/security/contracts review; and (c) +**capability proof** — fresh attestation that a driver can safely perform what is being trusted +(see [earned trust](#12-earned-trust--capability-attestation)). Policy decides which categories, +and how much of each, a story needs before it may land. - **MERGE-1.** Completing and landing work requires independent evidence aligned to the policy, never the worker's self-report alone. - **MERGE-2.** Push, PR creation, and merge are runner authority. The thing that writes code is not the thing that ships it. - **MERGE-3.** Done conditions are explicit and policy-bound. The owner decides what evidence - is required before work may land. + and acceptance strength are required before work may land. - **MERGE-4.** Done and merged are separate milestones. Jig proves a story is _done_ — its evidence is met — independently of whether its PR is _mergeable right now_. Branch protection, a merge queue, or a conflict can hold a done story without erasing that the work is done. @@ -101,7 +105,8 @@ Policy decides which categories, and how much of each, a story needs before it m **Honest edge.** Jig protects the shape of trust; the substance of each gate is still the owner's responsibility. A weak review, empty verification command, or vague plan remains weak. -Jig makes that weakness visible instead of pretending it is proof. +Jig makes that weakness visible instead of pretending it is proof; missing or inconclusive +acceptance means less autonomy or an inspectable stop, not a weaker guarantee. ## 2. Configuration ownership @@ -110,8 +115,8 @@ being handed an undifferentiated wall of knobs. Policy is the safety contract. W how the work gets done. Jig derives live behavior from those choices and the plan. - **CFG-1. Policy is the governance contract.** It expresses gating posture, merge spectrum, - concurrency ceiling, retry budget, required reviews, approvals, escalation rules, and the - anti-gaming floor. Because policy governs safety, changing it is itself governed. + concurrency ceiling, retry budget, required reviews, acceptance strength, approvals, escalation + rules, and the anti-gaming floor. Because policy governs safety, changing it is itself governed. - **CFG-2. The work profile is the realization.** It expresses cost, quality, and behavior: model, effort, prompt strategy, and role realization. It is freely tunable because it does not lower the safety floor. @@ -277,5 +282,5 @@ records. - [Jig — the execution engine](./jig.md) — product overview, spine, workflow, boundaries. - [How you use Jig](./use-cases.md) — worked scenarios that make each guarantee concrete. -- [Product concepts](./concepts.md) — tracks, stories, runner/worker authority, SDK boundaries, - providers, and conformance. +- [Product concepts](./concepts.md) — tracks, stories, runner/worker/verifier authority, SDK + boundaries, providers, and conformance. diff --git a/docs/product/jig.md b/docs/product/jig.md index 734cc7a..2947cff 100644 --- a/docs/product/jig.md +++ b/docs/product/jig.md @@ -7,9 +7,9 @@ status: draft — product overview Jig is the deterministic execution engine you run as `jig`. At product altitude, `@agentic-workflow-kit/jig` names the Jig product identity; there is no public package, export, -or stability promise today. You give Jig an approved **execution plan** and a **policy**; it turns that -plan into reviewed, landed work as far as the policy allows, or into a deliberate, inspectable -stop when the work should not continue. +or stability promise today. You give Jig an approved **execution plan** plus owner-controlled +**policy** and **configuration**; it turns those inputs into safe, evidenced delivery as far as +policy allows, or into a deliberate, inspectable stop when the work should not continue. This page is the product contract for Jig: who it serves, what job it does, what promises it makes, and where its boundaries are. It does not define low-level protocol mechanics, @@ -19,7 +19,8 @@ design and delivery planning own how those promises are implemented and verified > **The product layer, at a glance.** This page is the hub. Two companion pages carry the > detail: **[the five guarantees](./guarantees.md)** (full, ID-bearing specification) and > **[how you use Jig](./use-cases.md)** (worked scenarios). [Product concepts](./concepts.md) -> covers tracks, stories, runner/worker authority, SDK boundaries, providers, and conformance. +> covers tracks, stories, runner/worker/verifier authority, SDK boundaries, providers, and +> conformance. ## Product Spine @@ -27,7 +28,7 @@ design and delivery planning own how those promises are implemented and verified | ------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | User | An owner/operator with product and design judgment who cannot safely supervise every agent action manually. | | Also serves | Integrators and tool builders who consume Jig's programmatic surface and its structured records — driving Jig from their own agent, embedding it, or building analyzers, dashboards, and story sources around it (CFG-7, SEE-2). | -| Job | Turn an approved execution plan into reviewed, landed work while preserving human control. | +| Job | Turn an approved execution plan and owner policy/configuration into safe, evidenced delivery or an inspectable stop while preserving human control. | | Current alternative | A chain of one-off agent sessions, manual PR and review follow-up, ad hoc notes, and fragile recovery. | | Before | The owner cannot tell whether the agent stayed inside policy, what evidence justified a merge, or how to resume safely after interruption. | | After | The owner delegates execution under policy and receives evidence, escalation points, recovery, and a reconstructible outcome. | @@ -37,11 +38,15 @@ design and delivery planning own how those promises are implemented and verified Jig starts where planning ends: -1. You provide an execution plan and policy. +1. You provide an execution plan, policy, and configuration. 2. Jig runs eligible work under that policy, with the worker contained behind authorization and the runner holding privileged actions. -3. Jig asks for a human decision when policy, evidence, or capability proof requires it. -4. Jig lands work only on evidence, or stops in a named state with enough information to +3. Jig's product model treats acceptance/review before landing as a policy-selected lane; richer + runtime support for that lane remains implementation follow-up unless current design or code has + separately proven it. +4. Jig asks for a human decision when policy, evidence, implemented acceptance checks, or + capability proof requires it. +5. Jig lands work only on evidence, or stops in a named state with enough information to recover, re-plan, or reject. ```mermaid @@ -63,7 +68,8 @@ flowchart TD ``` The supporting products can help produce the product definition, design, and plan. They are -strong defaults, not prerequisites. Jig's minimum input is a valid execution plan. +strong defaults, not prerequisites. Jig's hard input boundary is a valid execution plan; the run's +safety and acceptance posture comes from owner-controlled policy and configuration. ### Driving a run @@ -131,13 +137,60 @@ see **[the five guarantees in detail](./guarantees.md)**. structured records that owners and tools can inspect. _([detail](./guarantees.md#5-full-observability))_ +### The run roles + +Jig's product promise depends on keeping these roles separate: + +| Role | Product boundary | +| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| **Config** | Owner-controlled run/repo wiring: which track, work profile, providers, and operating posture are selected before launch. | +| **Policy** | Owner-controlled safety and acceptance contract: gating posture, acceptance strength, escalation, reviews, and merge conditions. Fixed at launch for the run. | +| **Plan** | The approved execution plan and Jig's hard input boundary: stories, dependencies, and done conditions. | +| **Runner** | Jig's trusted orchestrator: owns lifecycle, policy enforcement, evidence consumption, Doorbell escalation, records append, and provider invocation. It is not a code reviewer or forge API. | +| **Worker** | The contained implementer: edits code, runs requested checks, and reports results/evidence. It does not hold forge credentials, land work, choose acceptance strength, or review itself. | +| **Verifier/reviewer** | The independent acceptance lane: human, agent, or deterministic checker that assesses evidence, diff, or output and emits a verdict for Runner/policy to consume. | +| **Fence** | Runtime authorization: approves, denies, or routes worker requests before they execute. | +| **Doorbell** | Owner escalation for ambiguous, risky, or unproven decisions; grants remain narrow and recorded. | +| **Forge provider** | Deterministic adapter capability for external forge operations such as push, PR/status/comment, merge, idempotency handling, and API translation when Runner invokes it under policy. | +| **Execution host** | The environment containing the worker and proving the isolation/no-phone-home posture policy relies on. | +| **Work source** | Supplies candidate work and provenance, but never bypasses plan validation. | +| **Records** | Durable evidence trail for governed decisions, evidence, verdicts, stops, and outcomes. | + +This is why Jig is not "an agent that codes." Jig is the harness around a worker: the worker +produces work, the verifier/reviewer assesses it, the runner enforces policy and lifecycle, the +forge provider performs deterministic external operations, and the owner owns risk decisions. + +### Acceptance before landing + +Verification before merge/landing is a configurable acceptance/review lane selected by the owner's +policy and configuration before launch. Some review modes, especially ordinary code review, may +require Runner to push a branch or open/update a PR so the review can happen or blocked work can be +surfaced safely. Those forge operations are still runner-invoked and policy-governed, but they are +not acceptance. At product altitude, the lane can be as simple or as strong as the policy requires: + +- a mechanical evidence check over recorded commands and outputs; +- structured independent review of the diff and evidence; +- real code review in the owner's normal review flow; +- explicit owner review; +- specialist review, such as security, contracts, data, or platform review. + +In the product model, the lane emits a verdict or evidence assessment. It does not land work, hold +privileged forge credentials, redefine policy, select weaker acceptance, or create lifecycle +transitions directly. Runner consumes the verdict, records it, and enforces policy when the lane is +implemented for the selected policy. If proof is missing, stale, self-reported, weak, or +inconclusive, Jig routes to the Doorbell or stops according to policy; it does not lower the bar. + +This section names the product model and target boundary. Runtime/config/policy support for richer +acceptance lanes is implementation follow-up unless current design or code has separately proven +that support. + ### Enforce vs. Guide Most of the suite guides: it gives templates, presets, product practices, and planning discipline the owner can adapt. Jig enforces only the floors that make delegation safe: authorization before action, policy that cannot be quietly weakened, runner-owned irreversible -actions, and evidence before landing work. The owner still chooses the policy posture and the -strength of the gates. +actions, implemented acceptance gates before landing when policy requires them, and evidence before +landing work. The owner still chooses the policy posture and the strength of the gates. ## How you use Jig @@ -147,10 +200,11 @@ each making one of the five guarantees concrete. ## Product Boundaries -Jig owns execution under policy: authorization, escalation, evidence, recovery, stack seams, -and run visibility. The supporting products can help produce better product definitions, -designs, and execution plans, but Jig does not require them. The learning loop is between-runs -improvement, not part of Jig's per-run hot path. +Jig owns execution under policy: orchestration, authorization, escalation, evidence consumption, +implemented acceptance verdict consumption, recovery, provider invocation, stack seams, and run +visibility. The supporting products can help produce better product definitions, designs, and +execution plans, but Jig does not require them. The learning loop is between-runs improvement, not +part of Jig's per-run hot path. Design owns the implementation details behind these promises: event schema shape, protocol mechanics, provider contracts, exact policy classifiers, setup prompts, configuration file shape, @@ -172,6 +226,11 @@ guarantees — a first-party provider gets no privileged shortcut a third-party This is a product promise about portability and owner trust, not a decision about package layout or publication. +The Forge provider is one of those replaceable providers, not another agent. It translates a +Runner-authorized external operation into deterministic forge effects and reports the result. It +does not decide whether evidence is sufficient, whether policy allows landing, or whether the work +should ship. + Provider extensibility is settled product scope. Owners and teams should be able to bring a compatible provider for a supported seam and plug it into Jig without forking Jig core. That provider earns use through declared authority and conformance proof; the exact local connection @@ -241,7 +300,7 @@ Jig is honest about its edges. These are deliberate non-goals or deferrals, not - [The five guarantees (detail)](./guarantees.md) — full ID-bearing specification. - [How you use Jig](./use-cases.md) — worked scenarios for each guarantee. -- [Product concepts](./concepts.md) — tracks, stories, runner/worker authority, SDK boundaries, - providers, and conformance. +- [Product concepts](./concepts.md) — tracks, stories, runner/worker/verifier authority, SDK + boundaries, providers, and conformance. - [Engineering design](../design/) — the implementation reference for how these product commitments are satisfied.