From 4a7d306b1c528dc750ebc57097a86d09c9d84d4d Mon Sep 17 00:00:00 2001 From: Arye Kogan Date: Fri, 3 Jul 2026 21:00:32 +0300 Subject: [PATCH] docs: add M7 Real Provider Integration milestone --- MILESTONES.md | 63 +++++++++++++++++++++++++++++++++++++++++++++++ ROADMAP.md | 18 ++++++++------ profile/README.md | 18 ++++++++------ 3 files changed, 85 insertions(+), 14 deletions(-) diff --git a/MILESTONES.md b/MILESTONES.md index e204043..0dcfc97 100644 --- a/MILESTONES.md +++ b/MILESTONES.md @@ -442,6 +442,69 @@ before any design or implementation: - Learning-loop PR or repo creation merged with checks green. - At least one sample recommendation cites the Jig record fields it used. +### M7: Real Provider Integration + +- State: ready-for-repo-planning +- Outcome: Enable an operator to turn an approved plan into real landed work — a real agent + driver doing real edits, a real execution host with proven confinement, real Forge/GitHub + landing, and real work-source intake — recorded in durable, inspectable records under + policy. This promotes Jig's M5 `named extension point` seams (agent driver, execution-host + driver, forge driver, work-source driver, resume, capability attestation) to `exercised` + behind the same contracts, with real effects replacing the reference adapters. +- Why now: The M5 slice pinned the four provider ports, the composition root, the + capability-attestation gate, and the driver conformance suite as exercised, Jig-internal + seams — proven with reference adapters that perform no real behavior. With those contracts + stable and merged (Jig Phase 5, commit `f59a479`), real drivers can slot behind them without + churning the seams. Sequence is not serialization: M5 remains `current`, but M7 consumes the + pinned, merged P5 seams, so its repo planning can proceed now. +- Primary owner: `jig` +- Participating repos: `jig`, `.github`. Learning consumes the resulting real run records. +- Owned seam or artifact: None new. M7 exercises the execution-plan and observability-records + contracts already owned by M1 and Jig, driving them through real providers rather than + reference adapters. It introduces no new org-level seam. +- Entry criteria: + - Jig Phase 5 — provider ports, composition root, capability attestation, and the driver + conformance suite — is merged to Jig `main` (commit `f59a479`). + - The outcomes are already committed by Jig's product as ID-bearing guarantees + (STACK / DRIVE / SEC / MERGE / ISO / RESUME / EARN), so no new PRD or lifecycle layer is + stood up. This is not a new-layer milestone. +- Exit criteria: + - Real drivers selected through Jig's composition root perform real effects — real agent + edits, confined real execution, real Forge/GitHub landing, real work-source intake — under + policy and against a real capability attestation, not a reference adapter. + - Those real effects are recorded in durable, inspectable records matching the M1 + observability record shape, including tamper-evidence over the record chain and an active + re-approval path when an approved plan's basis changes. + - Isolation is proven per story in parallel workspaces, and freshness is decided by a real + clock rather than a stubbed constant; secrets are scanned and redacted on the real + landing path. + - The driver conformance suite still fails closed on a broken or non-conforming adapter. + - Jig's Phase-0..4 record goldens stay byte-identical under the default (reference) wiring, + so real drivers are opt-in and do not silently alter the proven local path. +- Artifacts: + - Real driver implementations behind the existing agent, execution-host, forge, and + work-source ports. + - Real capability-attestation records and the confinement evidence they attest to. + - Driver conformance-suite results, including the fail-closed case on a broken adapter. + - Tamper-evidence and secret-redaction evidence over the real landing path. +- Repo planning handoff: + - `jig` derives its repo plan directly from this milestone, decomposing the outcome into its + own phases and stories. Org milestones carry no story list; that decomposition lives in + Jig's delivery track. + - The real run records M7 emits strengthen M6 seeding, but M6 does not block on M7 — M6's + entry is already satisfiable by M1 examples or an M5 record. +- Risks / kill assumptions: + - Fails if a real driver can escalate its substrate — argv, credentials, or egress — past + what the attestation authorized. + - Fails if attested isolation strength is declared rather than proven by an exercised check. + - Fails if real landing is not idempotent when re-run against a real effect. + - Fails if "real" expands into hosted, multi-tenant, or remote operation before the local + real path proves out. The items under `## Deferred From This Sequence` stay out of M7. +- Evidence when landed: + - Jig PR(s) merged with real drivers exercised end to end and `pnpm check` green. + - A real run record — with attestation, tamper-evidence, and redacted secrets — can be cited + by Learning-loop design. + --- ## Deferred From This Sequence diff --git a/ROADMAP.md b/ROADMAP.md index d2a6e94..63bcbe2 100644 --- a/ROADMAP.md +++ b/ROADMAP.md @@ -42,12 +42,12 @@ coupled only by a small set of **shared contracts (seams)**. Pin down each seam' and every layer can be designed in parallel against the contract, not against another layer's internals. The currently pinned seams are owned by existing layer repos. -| Seam (shared artifact) | Owner | Consumers | Status | -| ----------------------------------------------------------------- | ------------------ | ------------------------------ | ------------------------------------------------------------------------------- | -| **Execution-plan contract shape** — Jig's one hard input boundary | `jig` | Planning layer produces to it | v0 shape: `jig/docs/design/contracts/execution-plan-contract-v0.md` | -| **Observability / event records** — durable run output | `jig` | Learning loop consumes | v0 shape: `jig/docs/design/contracts/observability-records-contract-v0.md` | -| **Technical-design document format** | `technical-design` | Planning layer consumes | v0 handoff: `technical-design/docs/design/technical-design-handoff-contract.md` | -| **PRD / ID'd acceptance-criteria format** | `define-product` | Design + Planning cite the IDs | v0 contract: `define-product/docs/product/prd-contract.md` | +| Seam (shared artifact) | Owner | Consumers | Status | +| ----------------------------------------------------------------- | ------------------ | ------------------------------ | ------------------------------------------------------------------------------------------------------------- | +| **Execution-plan contract shape** — Jig's one hard input boundary | `jig` | Planning layer produces to it | v0 shape: `jig/docs/design/contracts/execution-plan-contract-v0.md`; queued for real-driver exercise under M7 | +| **Observability / event records** — durable run output | `jig` | Learning loop consumes | v0 shape: `jig/docs/design/contracts/observability-records-contract-v0.md`; real run records planned under M7 | +| **Technical-design document format** | `technical-design` | Planning layer consumes | v0 handoff: `technical-design/docs/design/technical-design-handoff-contract.md` | +| **PRD / ID'd acceptance-criteria format** | `define-product` | Design + Planning cite the IDs | v0 contract: `define-product/docs/product/prd-contract.md` | **Sequencing rule of thumb:** the highest-leverage early work is authoring Jig's two seams (execution-plan contract shape, observability records), because two downstream layers wait on their @@ -98,7 +98,11 @@ parallel. The current sequence is tracked in [`MILESTONES.md`](./MILESTONES.md). reconciling to product), and M5b Phases 0-2 delivered a TypeScript walking skeleton: a local dry-run CLI (`jig run` / `jig inspect`) with durable records and an enforced lint+typecheck+test gate. Next is the remediation phase (Phase R) and then governed local - runs (Phase 3) per jig's live delivery track (`jig/docs/delivery/m5b-local-mvp-r2/`). + runs (Phase 3) per jig's live delivery track (`jig/docs/delivery/m5b-local-mvp-r2/`). With + the Phase 5 provider ports, composition root, and capability-attestation gate now merged, + jig also derives its real-provider integration plan from + [`M7`](./MILESTONES.md) — promoting the agent, execution-host, forge, and work-source seams + from reference adapters to real drivers behind the same contracts. - **References (curated):** - Product (own, drafted): `jig/docs/product/jig.md`, `guarantees.md`, `use-cases.md`, `concepts.md`. diff --git a/profile/README.md b/profile/README.md index fca3d18..7f8e760 100644 --- a/profile/README.md +++ b/profile/README.md @@ -22,13 +22,13 @@ repo can stay focused without inventing its own vocabulary. ## Repositories -| Repo | Role | Status | -| ------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------ | -| [`define-product`](https://github.com/agentic-workflow-kit/define-product) | Product layer: PRD authoring and stable, ID'd acceptance criteria upstream of design. | Seeded; M3 contract bootstrap | -| [`technical-design`](https://github.com/agentic-workflow-kit/technical-design) | Design layer: frame, author, review-loop, enforce, and orchestrate technical designs. | Built; planning handoff contract pinned | -| [`jig`](https://github.com/agentic-workflow-kit/jig) | Delivery / execution engine: runs an approved plan under policy into reviewed, landed work, or a deliberate stop. The tool you run (`@agentic-workflow-kit/jig`). | Early; local dry-run walking skeleton (M5b Phases 0-2) | -| [`design-to-plan`](https://github.com/agentic-workflow-kit/design-to-plan) | Planning layer: decompose approved designs into the execution-plan shape Jig runs. | Seeded; M4 contract bootstrap | -| Learning loop | Capture run outcomes and feed them back into future work. | Planned | +| Repo | Role | Status | +| ------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- | +| [`define-product`](https://github.com/agentic-workflow-kit/define-product) | Product layer: PRD authoring and stable, ID'd acceptance criteria upstream of design. | Seeded; M3 contract bootstrap | +| [`technical-design`](https://github.com/agentic-workflow-kit/technical-design) | Design layer: frame, author, review-loop, enforce, and orchestrate technical designs. | Built; planning handoff contract pinned | +| [`jig`](https://github.com/agentic-workflow-kit/jig) | Delivery / execution engine: runs an approved plan under policy into reviewed, landed work, or a deliberate stop. The tool you run (`@agentic-workflow-kit/jig`). | Early; local dry-run walking skeleton (M5b Phases 0-2); M7 real-provider integration queued | +| [`design-to-plan`](https://github.com/agentic-workflow-kit/design-to-plan) | Planning layer: decompose approved designs into the execution-plan shape Jig runs. | Seeded; M4 contract bootstrap | +| Learning loop | Capture run outcomes and feed them back into future work. | Planned | ## Lifecycle @@ -58,6 +58,10 @@ The current org focus is M5: proving a narrow Jig local MVP slice now that Produ Design, and Planning contract shapes are seeded. M4 seeded `design-to-plan` so approved technical designs can become Jig-ready execution plans without re-deciding product or design scope. +With Jig's Phase 5 provider ports and capability-attestation gate now merged, M7 (Real Provider +Integration) is ready for repo planning: Jig promotes its agent, execution-host, forge, and +work-source seams from reference adapters to real drivers behind the same contracts. + Start with [`define-product`](https://github.com/agentic-workflow-kit/define-product) for product intent and acceptance-criteria IDs, [`technical-design`](https://github.com/agentic-workflow-kit/technical-design) for design-stage skills, [`design-to-plan`](https://github.com/agentic-workflow-kit/design-to-plan)