@tyroneross/build-loop 0.34.0 → 0.36.0

package/plugin-artifacts/codex/references/agent-role-taxonomy.md

@@ -86,6 +86,40 @@ Every peer host/session must:
 - Use `heartbeat --task-ref` during long-running tasks so other sessions can
   distinguish "process alive" from "still on task".
 
+## Core vs Sub-Agent — the classification rule
+
+External analyses tend to classify by model tier ("`model: fable` ⇒ core") or by
+blocking power ("core agents halt the loop"). Both are wrong as definitions:
+
+- **Core = produces a verdict some pipeline step is contingent on.** The
+  independent-auditor's `nay`, plan-verify's blocking findings, and
+  `judgment_gate`'s `fail` gate specific steps; that contingency is what makes
+  the role core. Most Frontier critics are advisory by charter
+  (synthesis-critic is WARN-only, alignment-checker never blocks) — high tier,
+  not core. "Can halt the loop" misclassifies: build-loop verdicts gate steps;
+  they never hard-halt the loop outside the defined stop conditions.
+- **Tier follows role, never the reverse.** The role's responsibility row
+  (above) plus `references/model-tier-mapping.md` selects the tier. A future
+  re-tiering (e.g., a cheaper model clearing the Frontier contract) must not
+  reclassify an agent's authority.
+
+## Delegation depth is a security property
+
+The no-sub-sub-agents rule (subagents never dispatch agents) is not just
+context hygiene: it caps the delegation chain at depth 2
+(orchestrator → worker). Enterprise NHI guidance flags 3–5-hop delegation
+chains as the silent-privilege-escalation surface; build-loop designs that
+class out structurally. Treat any proposal to let a subagent dispatch
+(including "just this once" orchestration conveniences) as a security-surface
+change → `triggers.riskSurfaceChange: true`, security-reviewer in scope.
+
+The one sanctioned agent-initiated escalation is `status: blocked` +
+`novel_decisions[]` (the C5 backstop) — build-loop's handoff *detection phase*.
+A worker that detects out-of-scope work returns it for routing; it never
+self-routes. Keep C5 healthy instead of adding peer-to-peer routing fabric;
+recovery from failed handoffs likewise stays centralized in the orchestrator's
+status-routing + stuck-cascade, never per-worker.
+
 ## When To Add A New Agent
 
 Add a new agent only when all are true:

package/plugin-artifacts/codex/references/backlog-system.md

@@ -0,0 +1,285 @@
+<!-- SPDX-FileCopyrightText: 2025-2026 Tyrone Ross, Jr <46267523+tyroneross@users.noreply.github.com> | SPDX-License-Identifier: Apache-2.0 -->
+
+# Backlog System — host-agnostic, multi-repo deferred-work tracker
+
+A backlog is the durable list of wanted-but-not-now work for a repo: deferred
+debt, blocked infra, known fixes, pending decisions. This system makes that list
+**host-neutral** (any coding agent — Claude, Codex, or other — reads and writes
+it the same way), **filesystem-first** (grep + frontmatter, no DB/vector/graph),
+and **aggregatable** across all of one user's repos via their personal memory.
+
+## Why it is shaped this way
+
+Five research-grounded principles drive the design (from the memory-architecture
+guide; Letta filesystem-memory benchmark; "don't over-engineer"):
+
+1. **Canonical truth vs derived index.** The items in `items/` are the truth.
+   `INDEX.md` is a *generated, rebuildable* view — never hand-edited.
+2. **Metadata-rich items.** Each item carries provenance, evidence,
+   supersession links, and a TTL (`review_by`) so it can be audited and aged.
+3. **Filesystem-first retrieval.** Reading = `cat BACKLOG.md` → `INDEX.md`, then
+   `grep` over `items/*.md` frontmatter. No index server, no embeddings.
+4. **Lifecycle ops.** Formation (`new`) → consolidation (`sync` archives
+   done/dropped, flags stale) → retrieval (`list`, grep) → forgetting
+   (archive, never delete).
+5. **Governance Level 3.** Every write is logged, timestamped, attributable —
+   git history + `created`/`updated` stamps + archive-not-delete provide it.
+
+## Two scopes (do not conflate)
+
+| Scope | Path | Lifetime | Shared? |
+|---|---|---|---|
+| **Per-repo backlog** | `<repo>/.build-loop/backlog/` | Travels with the repo; committed | Team-shareable (in the repo) |
+| **Personal memory mirror** | `build-loop-memory/projects/<slug>/backlog/` | Per-user, aggregated across ALL the user's repos | Private to the user |
+
+The sync is **one-way**: per-repo backlog → personal memory. The per-repo store
+is the source of truth; the memory mirror is a cross-repo read view for the user
+who downloaded build-loop.
+
+## Structure
+
+```
+<repo>/
+├── BACKLOG.md                      # repo-root pointer → .build-loop/backlog/INDEX.md
+└── .build-loop/backlog/
+    ├── README.md                   # what this dir is + how to use it
+    ├── .gitattributes              # INDEX.md merge=ours (resolve by regeneration)
+    ├── INDEX.md                    # DERIVED — regenerated by `sync`; do not edit
+    ├── items/<ID>.md               # CANONICAL truth — one file per item
+    └── archive/<ID>.md             # done/dropped items (never deleted)
+```
+
+`<ID>` = `<PROJSLUG>-<AREA>-<token>` — e.g. `ATOM-SEARCH-mt3k9p7q`. The prefix is
+derived from the repo basename; the **token** is a coordination-free,
+collision-resistant suffix: 8 Crockford-base32 digits of millisecond time
+(so `ls items/` still roughly sorts by creation) followed by 5 digits of
+`os.urandom` entropy (so the ID is unique across agents, machines, branches, and
+clones with **no shared counter**). Lowercase throughout.
+
+**Why not the old sequential `-NNN`?** A per-area zero-padded counter is a
+single-writer assumption. Two agents in independent worktrees/clones (Claude on
+branch A, Codex on branch B) each read their OWN highest-NNN and both minted the
+SAME `...-001/002/003` for DIFFERENT items — on `git merge` the identical
+filenames/IDs collided or silently lost an item. The token removes the shared
+counter entirely. The readability trade-off (IDs gain a ~13-char token suffix
+instead of `-001`) is paid back by `INDEX.md`, which is the human-ordered
+navigation view; the items themselves are addressed by token.
+
+**Legacy `-NNN` items still read.** Items minted before this change (and any
+hand-authored `-NNN`) remain valid: the ID-shape regex accepts BOTH a token
+suffix and a legacy `\d{3,}` suffix, and no parser assumes a numeric tail.
+Existing IDs are never rewritten — only NEW items get tokens.
+
+## Item schema (frontmatter on every `items/<ID>.md`)
+
+```yaml
+id: ATOM-SEARCH-001
+title: <one line>
+status: open            # open | in-progress | blocked | deferred | done | dropped
+priority: P2            # P0..P3
+type: debt              # feature | fix | debt | infra | decision | cleanup | research
+area: search            # free-ish tag; the grep + filter routing key
+entities: [pg_trgm, keyword-leg]
+gated: db-migration     # none | prod-deploy | db-migration | infra | product-decision
+provenance: { source: followup, ref: <path/commit/PR#/chat-date> }
+evidence: [<commit/PR/retro/followup paths>]
+supersedes: null
+superseded_by: null
+created: 2026-06-16
+updated: 2026-06-16
+review_by: 2026-07-16   # TTL — surfaced by `sync` when passed
+owner: unassigned
+```
+
+Body sections: `## Context`, `## Acceptance`, `## Notes`.
+
+Dates are caller-stamped (`--today YYYY-MM-DD` or the `BACKLOG_TODAY` env var,
+falling back to the system clock) so the tool runs in harnesses where the clock
+is not callable.
+
+## Lifecycle / sync contract
+
+`scripts/backlog.py sync --repo <path>` does three things, in order:
+
+1. **Consolidate.** Move every `status: done` / `status: dropped` item from
+   `items/` to `archive/`. Never deletes. Flags items whose `review_by` has
+   passed as stale. Warns about `.build-loop/{followup,issues,proposals}` files
+   not yet referenced by any item's `evidence`/`provenance.ref` (scattered work
+   not yet triaged into the backlog).
+2. **Regenerate INDEX.** Rebuild `INDEX.md` deterministically from the remaining
+   items' frontmatter — grouped status → area → priority, with a compact table,
+   a summary (active count, open P0/P1, stale count, gated count), and a stale
+   call-out. For a FIXED item set re-rendering is **byte-identical** (no
+   wall-clock in the body), so `sync` is safe to re-run and diff-clean. The INDEX
+   write is atomic (temp file + `os.replace`), so a concurrent `sync` by two
+   agents never leaves a torn file for a reader. **Duplicate-ID guard
+   (defense in depth):** if two items ever share an `id` (a bad merge, a
+   hand-edit), `sync` surfaces them LOUDLY in a `## ⚠ Duplicate IDs` section
+   (id, count, all titles, all paths) instead of silently rendering one — so a
+   collision that did happen is visible.
+3. **Mirror to personal memory.** Copy active item files (+ a mirror INDEX) into
+   `build-loop-memory/projects/<slug>/backlog/`. Each mirror file is written
+   atomically (temp file + `os.replace`), so a parallel session never observes a
+   half-written file; last-writer-wins (the per-repo backlog is the truth).
+   Best-effort: if the memory root is absent or unwritable, sync still succeeds
+   and reports `mirror.skipped`.
+
+### INDEX.md merge handling
+
+`INDEX.md` is fully derived, so two agents that both regenerate it WILL conflict
+on `git merge`. The scaffold (via `adopt` AND any backlog materialisation by
+`new`/`sync`) drops a `.build-loop/backlog/.gitattributes` with:
+
+```gitattributes
+INDEX.md merge=ours
+```
+
+so git resolves the conflict by keeping one side instead of inserting conflict
+markers. **On an `INDEX.md` conflict, run `backlog.py sync` — `items/` is the
+truth and the INDEX regenerates deterministically.** Item files in `items/`
+don't conflict once IDs are unique (token suffix → separate paths), so both
+branches' new items survive a merge.
+
+## How ANY agent uses it (host-neutral)
+
+**Read** (no tools required — just the filesystem):
+1. `cat <repo>/BACKLOG.md` → follow the pointer to `INDEX.md`.
+2. `cat <repo>/.build-loop/backlog/INDEX.md` for the grouped view.
+3. `grep -l 'area: search' <repo>/.build-loop/backlog/items/*.md` to find items
+   by any frontmatter field; read the matching item bodies.
+
+**Write** (via the pure-stdlib CLI — works under bare `python3`, no host SDK):
+```bash
+# create
+python3 scripts/backlog.py new --repo <path> --area search --type debt \
+    --title "pg_trgm for keyword leg" --priority P1 --gated db-migration \
+    --provenance-source followup --provenance-ref .build-loop/followup/x.md \
+    --today 2026-06-16
+# edit the item body / frontmatter by hand in items/<ID>.md
+# then regenerate + mirror
+python3 scripts/backlog.py sync --repo <path> --today 2026-06-16
+# read
+python3 scripts/backlog.py list --repo <path> --status open
+```
+
+The CLI emits structured JSON (machine-readable) on `new`/`sync`; `list` prints
+a text table (or JSON with `--json`). The host LLM reasons over the structured
+data + the convention — it never calls a vendor API.
+
+## Relationship to existing build-loop surfaces
+
+- `.build-loop/issues/` — current-run bugs (short-lived). A persistent issue is
+  triaged INTO the backlog (`new`), then the issue file is referenced as
+  `evidence`/`provenance.ref` so `sync` stops warning about it.
+- `.build-loop/followup/` — iterate-cap overflow. Same triage path.
+- `templates/backlog-item.md` + `build-loop-memory/projects/<slug>/backlog.md`
+  (the legacy single-table durable backlog) remain valid for build-loop's own
+  self-work tracking; this per-item system is the general, multi-repo surface
+  and writes its mirror to the `backlog/` *subdir* (no clobber of `backlog.md`).
+
+## Phase 1 Assess integration
+
+`scripts/context_bootstrap.py` surfaces a compact backlog line at Phase 1 Assess
+when `.build-loop/backlog/INDEX.md` exists: open P0/P1 count, past-`review_by`
+stale count, and gated count. Cheap (reads the generated INDEX summary only) and
+non-fatal when the file is absent.
+
+It also surfaces a one-time **discoverability nudge** (`backlog_discoverability`)
+when there's something to act on:
+
+- **Adoptable** — the repo has scattered work in `.build-loop/{followup,issues}`
+  but no `INDEX.md` yet → *"Backlog available — run `backlog.py adopt
+  --dry-run --repo .`"*.
+- **Won't travel** — `.build-loop/backlog/` exists but is gitignored → *"Backlog
+  won't travel — run `adopt --apply` to fix `.gitignore`"*.
+
+Both are silent when there's nothing to surface, and neither ever raises.
+
+## Download & upgrade safety
+
+This is the contract that makes the backlog safe to **download** with a fresh
+build-loop and **upgrade** in place over an existing one. The guiding rule:
+*every adoption/upgrade step is additive and reversible; nothing the user
+already had is moved, deleted, or rewritten in a lossy way.*
+
+**1. Additive / never-destructive.** Adoption never touches the existing work
+surfaces. `.build-loop/followup/`, `.build-loop/issues/`, `.build-loop/proposals/`,
+and the personal `build-loop-memory` store are read-only inputs to `adopt` — an
+imported item *links* to its source (`provenance.ref` + `evidence[]` +
+`imported_from`); the source file stays exactly where it was as the inbox /
+provenance record. `sync` likewise only ever archives (`done`/`dropped` →
+`archive/`) and regenerates the derived `INDEX.md`; it never deletes a live item.
+
+**2. Lazy / opt-in scaffolding.** A repo gets backlog dirs and pointer files
+*only* when the user runs `adopt` (or `new`). A downloaded build-loop does not
+litter every repo with an empty `backlog/` on first run — the structure
+materialises on demand. `adopt --dry-run` (the default) reports exactly what it
+*would* create without writing anything, so the user previews before opting in.
+
+**3. The `.gitignore` dependency — and how `adopt` fixes it.** `.build-loop/` is
+gitignored by default (confirmed in both `build-loop` and `sample-app`). That is
+correct for transient run state — but it means the backlog would **not commit
+and therefore would not travel** with the repo (no team-sharing, lost on a fresh
+clone). `adopt` detects this by inspecting `.gitignore` (pure text, no git call)
+and, on `--apply`, appends un-ignore rules so the durable backlog escapes the
+broad ignore:
+
+```gitignore
+# build-loop backlog (added by `backlog.py adopt` — keep so the backlog travels)
+!.build-loop/backlog/
+!.build-loop/backlog/**
+!BACKLOG.md
+```
+
+It reports this loudly (`gitignore.was_ignored: true`, `added: [...]`) and is
+idempotent — re-running never appends the block twice. If `.build-loop/` is not
+ignored, `adopt` leaves `.gitignore` untouched.
+
+**4. Idempotent, dry-run-first migration.** `adopt` defaults to a read-only
+dry-run; `--apply` executes. Re-running `--apply` is a no-op: each imported item
+records `imported_from: <source path>`, and a re-run reads that field across
+`items/` **and** `archive/` and skips any source already imported. No duplicate
+items, no churned `.gitignore`. Verified contract: `adopt --apply` twice → the
+second run's diff (items + `.gitignore`) is empty.
+
+**5. Schema-version tolerance (forward/back compatible).** Every item carries
+`schema_version` (current = `1`). The reader (`read_item`) is deliberately
+tolerant: it **defaults missing known fields** and **preserves unknown fields**.
+An item written by an *older* build-loop (no `schema_version`) reads back with
+defaults filled in; an item written by a *newer* build-loop (carrying fields
+this version doesn't know) reads back without error and with those fields intact.
+So a backlog written by one build-loop version always reads on another — neither
+a downgrade nor an upgrade corrupts or rejects it. Bump `SCHEMA_VERSION` only for
+a contract change a reader must actively know about; the tolerant reader absorbs
+purely-additive field changes without a bump.
+
+**6. `build-loop-memory` is the per-user cross-repo long-term store.** The
+per-repo backlog travels *with the repo* (committed, team-shareable). `sync`
+additionally mirrors active items one-way into
+`build-loop-memory/projects/<slug>/backlog/` — the user's private, cross-repo
+aggregate view. The mirror writes to the `backlog/` **subdir**, so it never
+collides with the legacy single-table `backlog.md`, with `lessons/`, or with
+`decisions/` in that project's memory lane. The mirror is additive: its only
+delete path is pruning orphaned item mirrors (ID-shaped stems whose source item
+was removed), and it never touches a hand-dropped note. If the memory root is
+absent or unwritable, `sync` still succeeds and reports `mirror.skipped`.
+
+**Concurrency note (multi-agent) — two distinct collision classes.**
+
+1. **Distributed (cross-worktree/clone/machine).** Independent checkouts share no
+   filesystem and no counter, so IDs must be collision-free *with zero
+   coordination*. The token suffix (time-ordered + `os.urandom`) provides exactly
+   that: two agents in separate worktrees minting in the same area produce
+   DISJOINT ID sets, so a `git merge` of their `items/` trees lands every item
+   with nothing clobbered. This is the bug the token scheme fixes — the retired
+   sequential counter collided here.
+2. **Same-filesystem concurrent processes.** N `new`/`adopt` processes on ONE
+   filesystem still race on the create. That is handled (kept from the prior fix)
+   by the `O_EXCL` atomic create: exactly one process can create a given path;
+   the rest re-mint a fresh token and retry, bounded. So 8 parallel `new` calls
+   in one area yield 8 distinct files, zero loss.
+
+Together these make the backlog safe as a shared multi-agent work surface across
+both separate checkouts AND concurrent processes — not just a single-writer file.
+The INDEX and memory-mirror writes are atomic (temp + `os.replace`) so a reader
+never sees a torn derived file.

package/plugin-artifacts/codex/references/capability-routing.md

@@ -25,6 +25,55 @@ Phase 1 runs `node ${CLAUDE_PLUGIN_ROOT}/skills/build-loop/detect-plugins.mjs` a
 | Modular systems pack | Phases 1-4 | Read `references/modular-systems-pack.md`; partition files/tasks MECE; prefer modular scalable boundaries unless an exception is documented |
 | Codex subagent adapter | Phase 3 (Execute, Codex only) | Read `references/codex-subagents.md`; use `templates/codex-worker-prompt.md` for authorized Codex workers |
 
+### Spec/Plan author router (intent-driven, ordered)
+
+This router selects the single skill that AUTHORS the plan/spec/task graph for this run. It is a recommendation that DRIVES Phase 2 — recorded into `state.json.intent.spec_router`, consumed by Phase 2 Plan, never a hard block.
+
+**Scope — author selection only.** `prd-bridge` is NOT in this router. It is mandatory in Phase 1 step 10 and only *consumes* an existing PRD (`docs/prd-*.md` → `state.json.prd`); it never authors. PRD-context is orthogonal to author selection — keep them separate.
+
+**Governing rule**: select on intent + goal + context, not on a trigger-word match. A skill's word-overlap activation is not enough to call it (this is why `prd-builder` over-fired during build-loop runs). The router is the intent-side selection; it pairs with the activation-side guard (prd-builder's negative-trigger scope, which excludes in-flight changes and active build-loop runs).
+
+Signals (all set during Phase 1 Assess):
+
+- `run_active` — is a build-loop run active? (`true` for any `/build-loop:run` or build-orchestrator dispatch.)
+- `plan_status` — `no-plan` | `plan-valid`, from the Phase 2 plan-exists gate (`.build-loop/plan.md` absent/empty + last `plan-verify` result).
+- `intent_kind` — `PRD-author` | `build-plan` | `task-graph` | `none`, the LLM's read of what this run needs authored.
+- `code_exists` — does the repo have substantive existing code? (Assess maps architecture: new/empty repo → false, existing repo → true.)
+- `goal_scope` — `new-app` | `existing-app-change` | `in-build-task-breakdown`.
+
+The rows are ORDERED — first match wins, so exactly one author is selected and no case matches two. The final default row makes the table exhaustive: every `(run_active, plan_status, intent_kind)` combination matches exactly one row, so nothing falls through.
+
+| # | Match condition (first true wins) | route_type / action | Author selected | Why |
+|---|---|---|---|---|
+| 1 | `intent_kind == none` — nothing to author (Q&A, status, trivial, read-only, or advisory-context-only) | `noop` (call nothing) | — (`skill: null`) | no plan/spec/task graph needed |
+| 2 | `run_active == false` AND greenfield PRD authoring is explicitly intended (new app with no code, OR `/start-prd` requested for a project) | `call` (or `recommend` outside an interactive session) | `prd-builder` | greenfield authoring + interactive intake; honors prd-builder's negative trigger — never fires inside an active run |
+| 3 | `run_active == true` AND `plan_status == no-plan` | `call` | `build-loop:spec-writing` | author the in-build, non-interactive, gated plan for the orchestrator |
+| 4 | `run_active == true` AND `plan_status == plan-valid` | `call` | `build-loop:writing-plans` (external) | turn the accepted plan into the task / dependency graph |
+| 5 (default) | else (no earlier row matched) — the canonical case is `run_active == false` AND `intent_kind` is `build-plan` or `task-graph`: a direct, out-of-run invocation of plan authoring on an existing repo | `recommend` | `build-loop:spec-writing` | recommend, not auto-call: there is no active run to drive, so surface the author for the lead to run if it chooses |
+
+The order is the contract: row 1 short-circuits before any author runs; row 2 is the only PRD author and is fenced off from active runs; rows 3 and 4 are mutually exclusive on `plan_status`; row 5 is the exhaustive `else` default that catches every remaining combination — its canonical case is an out-of-run `build-plan`/`task-graph` intent, but as the final row it also absorbs any residual (e.g. an out-of-run non-greenfield `PRD-author`) so no signal combination ever falls through. The table extends to any future author skill — add a row at the right precedence above the default, key it on the same signals, and the system still selects exactly one and records why.
+
+`build-loop:writing-plans` (row 4) is the **external** `writing-plans` skill from the superpowers plugin — it is not vendored in this repo (`skills/writing-plans/SKILL.md` does not exist here). When it is absent, fall back to the inline "write a structured plan directly" path in the §"Core loop skills/assets" table above.
+
+> Future refinement (do not over-build now): for monorepos, a `target_code_exists` signal (does the *target sub-path* already have code, vs the repo as a whole) would refine row 2's greenfield test. Out of scope until a monorepo case demands it.
+
+**Phase 1 record (the consumable contract)**. Phase 1 writes the matched decision into `state.json.intent.spec_router` so a Codex lead (no `Skill()` auto-activation) can consume it deterministically:
+
+```json
+{
+  "route_type": "author",
+  "action": "call" | "recommend" | "noop",
+  "skill": "build-loop:spec-writing" | "build-loop:writing-plans" | "prd-builder" | null,
+  "fallback": "<fallbacks.md section or inline guidance> | null",
+  "matched_row": 1 | 2 | 3 | 4 | 5,
+  "signals": { "run_active": true, "plan_status": "no-plan", "intent_kind": "build-plan", "code_exists": true, "goal_scope": "existing-app-change" }
+}
+```
+
+`action: "noop"` → `skill: null`, Phase 2 authors nothing from the router (terminal). `action: "recommend"` → `skill` carries the recommended author name (so the lead knows what to run if it chooses); Phase 2 surfaces the recommendation in the report and does NOT auto-call. `action: "call"` → `skill` is non-null and Phase 2 calls it. The three actions are distinct: `call` auto-invokes, `recommend` surfaces-only, `noop` skips.
+
+**Phase 2 read (the load-bearing wire)**. Phase 2 Plan READS `state.json.intent.spec_router` and acts on `action`/`skill` — it does NOT independently re-decide which author to call. See `references/phase-2-plan.md` step 0.
+
 ### Phase quick reference
 
 | # | Phase | Purpose | Sub-steps / key actions |

package/plugin-artifacts/codex/references/coordination-file-template.md

@@ -67,7 +67,7 @@ Per-run amendments: {{ANY_RUN_SPECIFIC_OPERATING_AMENDMENTS_OR_NONE}}
 
 ## MECE Ownership Packets per Piece
 
-<!-- TEMPLATE NOTE: Repeat this block once per piece. Every write-handoff requires all six. Skip ONLY for pure-read handoffs. -->
+<!-- TEMPLATE NOTE: Repeat this block once per piece. Every write-handoff requires all seven. Skip ONLY for pure-read handoffs. -->
 
 ### {{PIECE_ID}} — {{PIECE_TITLE}}
 
@@ -165,7 +165,7 @@ Before committing your filled-in coord file:
 
 1. Every `{{PLACEHOLDER}}` replaced with a real value.
 2. Every `<!-- TEMPLATE NOTE: ... -->` block deleted.
-3. Every piece has a MECE packet (all six elements: owns / does-not-own / interface-contract / integration-checkpoint / allowed-tools / denied-tools).
+3. Every piece has a MECE packet (all seven elements: owns / does-not-own / interface-contract / integration-checkpoint / allowed-tools / denied-tools / acceptance-criteria).
 4. Every piece has an acceptance-criteria sub-section.
 5. Step-status table rows match piece IDs in MECE packets.
 6. Run `python3 scripts/coordination_status.py --workdir . --session-id <id> --coordination-file <this-file> --json` — should report `status: clear` initially.