Skip to content

docs: reconcile M5 with jig's delivery reality and fix stale seam pointers #14

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 1 commit into from
Jul 2, 2026
Merged

docs: reconcile M5 with jig's delivery reality and fix stale seam pointers #14

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
31 changes: 26 additions & 5 deletions MILESTONES.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -309,10 +309,10 @@ before any design or implementation:
- Owned seam or artifact:
- Local runner behavior behind the execution-plan and run-record contracts
- Policy and approval behavior for the first supported local mode
- Approach: `jig/docs/design/` currently names only the two seam contracts (execution-plan
v0, observability-records v0); nothing yet names runner behavior, the execution host, or
the policy posture, so entry criterion 3 below is unmet. M5 splits into a design slice
before an implementation slice so that gap closes before code commits around it:
- Approach: at M5's start, `jig/docs/design/` named only the two seam contracts
(execution-plan v0, observability-records v0), so entry criterion 3 below was unmet. M5
split into a design slice before an implementation slice so that gap closed before code
committed around it (M5a has since landed and closed it):
- M5a — a jig-local design slice that names the full local-runtime architecture at high
altitude: plan validation, preview, eligibility/DAG, the runner/worker authority
boundary, the authorization/fence, the state machine, the record store, policy, and the
Expand Down Expand Up @@ -344,12 +344,19 @@ before any design or implementation:
posture are themselves exercised seams: M5a must name them concretely enough for M5b to
build the minimal local case, even though richer hosts and policies stay extension points.

Posture here is the M5 exit target, not a status claim. M5b re-sequenced its delivery into
client-usable phases (jig's delivery track), which moved when each seam gets exercised; the
criterion-to-phase mapping below and jig's track README
(`jig/docs/delivery/m5b-local-mvp-r2/`) are the binding reconciliation. The post-Phase-2
repository review (`jig/docs/reviews/2026-07-02-post-phase-2-repo-review.md`) is the
routed-back finding that prompted this amendment, per Deriving Repo Plans above.

- Entry criteria:
- M1 is done.
- M4 has produced a sample execution plan shape fixture (the shape, not a ready-to-parse
instance — see Artifacts).
- Jig design has named the first local execution host and the minimum policy posture.
Unmet as of this milestone's current state; M5a closes it.
Met: M5a landed (`jig/docs/design/` plus its archived M5a runtime-design note).
- Exit criteria:
- Jig validates and previews one minimal, machine-readable execution-plan instance.
- Jig executes that plan as a dry-run under policy: no privileged action (push, PR
Expand All @@ -361,6 +368,20 @@ before any design or implementation:
- The run ends in named, inspectable states.
- Tests appropriate to the exercised surface. This is jig's first real package: `pnpm check`
grows from prettier-only to include lint, typecheck, and test, with TDD coverage at 90%+.
- Exit-criteria delivery status (amended 2026-07-02, from jig's delivery track r2):

| Exit criterion | Status |
| ------------------------------------------------------- | -------------------------------------------------------------------- |
| Validates and previews a plan | Validation delivered; preview lands in jig Phase 3 |
| Dry-run executes without privileged action | Delivered (M5b Phases 1-2) |
| Fence emits requested -> authorized/denied/runner-owned | Lands in jig Phase 3 (boolean gate recorded as ADR 0018 scaffolding) |
| Records match the M1 shape | Partial; convergence lands in jig Phase R (ADR 0017) |
| Named, inspectable states | Delivered (M5b Phase 2) |
| `check` grows to lint+typecheck+test, 90%+ coverage | Delivered (TypeScript engine-archetype migration) |

M5 is not exit-complete until jig's Phase R and Phase 3 land; the phases and their
ID-bearing acceptance criteria live in `jig/docs/delivery/m5b-local-mvp-r2/phases.md`.

- Artifacts:
- Minimal CLI or runnable entry point
- Plan fixture — the machine-readable execution-plan instance is M5's own artifact; M4
Expand Down
14 changes: 8 additions & 6 deletions ROADMAP.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -44,8 +44,8 @@ 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/execution-plan-contract-v0.md` |
| **Observability / event records** — durable run output | `jig` | Learning loop consumes | v0 shape: `jig/docs/design/observability-records-contract-v0.md` |
| **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` |

Expand Down Expand Up @@ -85,7 +85,7 @@ parallel. The current sequence is tracked in [`MILESTONES.md`](./MILESTONES.md).
(profile contract, formats, lessons ledger); legacy `docs/product/supporting-products/product-to-design.md`;
v0.7 skill `agentic-workflow-kit:design-technical-solution`.

### jig — Delivery / execution engine `[early; product drafted]`
### jig — Delivery / execution engine `[early; walking skeleton running]`

- **Role:** run an approved execution plan under policy into reviewed, landed work — or a
deliberate, inspectable stop.
Expand All @@ -94,9 +94,11 @@ parallel. The current sequence is tracked in [`MILESTONES.md`](./MILESTONES.md).
deliberately.
- **Depends on:** a valid execution plan (its one hard input boundary). Upstream layers are
optional strong defaults, not prerequisites.
- **Next step:** author `docs/design/` **fresh** (reconciling to the drafted product layer),
then implement. The package decomposition is design-owned and intentionally empty until
then.
- **Next step:** the design layer is live (both seam contracts, state tables, and an ADR log
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/`).
Comment on lines +97 to +101

@chatgpt-codex-connector chatgpt-codex-connector Bot Jul 2, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge Update the stale Jig parallel-start guidance

With this change ROADMAP says the Jig design layer is already live and the next work is Phase R/Phase 3, but the unchanged “What can start in parallel now” entry in the same file still tells owners to author docs/design/ and the two seams from scratch. In the current-roadmap context, readers deriving repo plans will get the wrong next action; update that list to the Phase R/Phase 3 work or mark the design-seam item as historical.

Useful? React with 👍 / 👎.

- **References (curated):**
- Product (own, drafted): `jig/docs/product/jig.md`, `guarantees.md`, `use-cases.md`,
`concepts.md`.
Expand Down
14 changes: 7 additions & 7 deletions profile/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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; product and contract design seeded |
| [`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) |
| [`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

Expand Down