Skip to content

Clarify verification lane product and design boundaries #82

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
aryeko merged 3 commits into from
Jul 7, 2026
Merged

Clarify verification lane product and design boundaries #82

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
3c03aea
docs(product): clarify verification lane boundaries
aryeko Jul 6, 2026
ef19dfb
docs(design): align review lane with product model
aryeko Jul 6, 2026
07fddd1
docs(product): allow PR-based review flow
aryeko Jul 7, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
24 changes: 15 additions & 9 deletions docs/design/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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 |
Expand All @@ -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.
Expand Down Expand Up @@ -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

Expand Down Expand Up @@ -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

Expand All @@ -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.
35 changes: 22 additions & 13 deletions docs/design/contracts/providers.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand All @@ -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.
Expand Down Expand Up @@ -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.
Expand Down Expand Up @@ -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.
Expand Down Expand Up @@ -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.
Expand All @@ -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.
Expand All @@ -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
Expand Down Expand Up @@ -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
Expand Down
Loading