@zigrivers/scaffold 3.32.1 → 3.33.0

package/content/methodology/deep.yml

@@ -42,6 +42,7 @@ steps:
   database-schema: { enabled: true, conditional: "if-needed" }
   review-database: { enabled: true, conditional: "if-needed" }
   api-contracts: { enabled: true, conditional: "if-needed" }
+  mcp-tool-resource-contract: { enabled: false }
   review-api: { enabled: true, conditional: "if-needed" }
   ux-spec: { enabled: true, conditional: "if-needed" }
   review-ux: { enabled: true, conditional: "if-needed" }
@@ -73,6 +74,7 @@ steps:
   apply-fixes-and-freeze: { enabled: true }
   developer-onboarding-guide: { enabled: true }
   implementation-playbook: { enabled: true }
+  materialize-plan-to-beads: { enabled: true, conditional: "if-needed" }
   # Phase 15 — Build (build) — stateless, on-demand execution steps
   single-agent-start: { enabled: true }
   single-agent-resume: { enabled: true }

package/content/methodology/mcp-server-overlay.yml

@@ -0,0 +1,88 @@
+# methodology/mcp-server-overlay.yml
+name: mcp-server
+description: >
+  MCP Server overlay — an MCP server has no UI, so the design-system and UX
+  steps are disabled. database-schema/review-database stay available
+  (if-needed) for servers that persist resources/state. The
+  mcp-tool-resource-contract step is enabled (if-needed) for specifying MCP
+  tool/resource/prompt schemas. MCP domain knowledge (protocol, SDK, transport,
+  tool/resource design, auth, testing, deployment, observability, versioning)
+  is injected into the relevant pipeline steps.
+project-type: mcp-server
+
+step-overrides:
+  # No UI surface — disable design/UX steps entirely.
+  design-system: { enabled: false }
+  ux-spec: { enabled: false }
+  review-ux: { enabled: false }
+  # Stateful servers may persist resources; keep available but skippable.
+  database-schema: { enabled: true, conditional: "if-needed" }
+  review-database: { enabled: true, conditional: "if-needed" }
+  # MCP-specific spec step — enabled for mcp-server projects.
+  mcp-tool-resource-contract: { enabled: true, conditional: "if-needed" }
+
+# ---------------------------------------------------------------------------
+# knowledge-overrides
+# ---------------------------------------------------------------------------
+# Inject MCP domain expertise into existing pipeline steps so that MCP
+# protocol, SDK, transport, tool/resource design, auth, testing, deployment,
+# observability, and versioning knowledge is available during prompt assembly.
+knowledge-overrides:
+  # Foundation
+  tech-stack:
+    append: [mcp-protocol-fundamentals, mcp-sdk-selection, mcp-transport-patterns]
+  tdd:
+    append: [mcp-testing-strategies]
+
+  # Architecture & Decisions
+  system-architecture:
+    append: [mcp-protocol-fundamentals, mcp-transport-patterns, mcp-tool-design, mcp-resource-design]
+  adrs:
+    append: [mcp-sdk-selection, mcp-transport-patterns]
+
+  # Specifications
+  api-contracts:
+    append: [mcp-tool-design, mcp-resource-design, mcp-error-handling]
+  # mcp-tool-resource-contract knowledge is already declared in the step's own
+  # frontmatter knowledge-base ([mcp-tool-design, mcp-resource-design,
+  # mcp-prompt-primitives, mcp-error-handling]); no overlay override needed.
+  database-schema:
+    append: [mcp-resource-design]
+
+  # Testing
+  add-e2e-testing:
+    append: [mcp-testing-strategies]
+
+  # Quality Gates
+  security:
+    append: [mcp-authentication]
+  review-security:
+    append: [mcp-authentication]
+  operations:
+    append: [mcp-deployment-patterns, mcp-observability, mcp-versioning]
+  review-operations:
+    append: [mcp-deployment-patterns, mcp-observability, mcp-versioning]
+
+  # Reviews
+  review-architecture:
+    append: [mcp-transport-patterns, mcp-tool-design, mcp-resource-design]
+
+# ---------------------------------------------------------------------------
+# reads-overrides
+# ---------------------------------------------------------------------------
+# Wire docs/mcp-contract.md (output of mcp-tool-resource-contract) into
+# downstream steps that need MCP auth/validation/error contracts.
+# Uses append-only so non-MCP steps are unaffected when the overlay is absent.
+reads-overrides:
+  # Security review: MCP auth/error contracts are security-relevant
+  security:
+    append: [mcp-tool-resource-contract]
+  review-security:
+    append: [mcp-tool-resource-contract]
+  # Test generation: test the tools/resources against the contract
+  create-evals:
+    append: [mcp-tool-resource-contract]
+  story-tests:
+    append: [mcp-tool-resource-contract]
+  tdd:
+    append: [mcp-tool-resource-contract]

package/content/methodology/mvp.yml

@@ -42,6 +42,7 @@ steps:
   database-schema: { enabled: false }
   review-database: { enabled: false }
   api-contracts: { enabled: false }
+  mcp-tool-resource-contract: { enabled: false }
   review-api: { enabled: false }
   ux-spec: { enabled: false }
   review-ux: { enabled: false }
@@ -73,6 +74,7 @@ steps:
   apply-fixes-and-freeze: { enabled: false }
   developer-onboarding-guide: { enabled: false }
   implementation-playbook: { enabled: true }
+  materialize-plan-to-beads: { enabled: false }
   # Phase 15 — Build (build) — stateless, on-demand execution steps
   single-agent-start: { enabled: true }
   single-agent-resume: { enabled: true }

package/content/pipeline/build/multi-agent-resume.md

@@ -119,17 +119,113 @@ Recover your context by checking the current state of work:
 
 ### Beads Recovery
 
-**If Beads is configured** (`.beads/` exists):
-- `bd list --assignee "$ARGUMENTS"` — check for tasks with `in_progress` status owned by this agent
-- If a PR shows as merged, close the corresponding task: `bd close <id>`
-- If there is in-progress work, finish it (see "Resume In-Progress Work" below)
-- Otherwise, clean up and start fresh:
-  - `git fetch origin --prune && git clean -fd`
-  - Run the install command from CLAUDE.md Key Commands
-  - Atomically claim the next ready task: `TASK=$(bd ready --claim --json | jq -r '.id')` (sets `assignee=$BEADS_ACTOR` + `status=in_progress`; no race window between agents).
-- Continue working until `bd ready --claim --json` returns no task.
-
-**Without Beads:**
+The implementation plan is materialized into Beads issues by
+`/scaffold:materialize-plan-to-beads` before the build phase. A resumed build
+runs the **same defensive preflight** as the start prompt — it never claims
+against an empty or stale tracker. Under multi-agent concurrency,
+materialization is **orchestrator-only** and runs **once per wave under a
+merge-slot lock**; workers never materialize and must wait for a run-stamped
+completion signal before their first claim.
+
+**Step 1 — compute `beads_usable`.** `beads_usable` is true only when **all**
+hold: `.beads/` exists, `bd` is on `PATH`, `bd version` parses to **≥ 1.0.5**
+(using a macOS/BSD-safe numeric compare — split major/minor/patch and compare
+numerically, never rely on GNU `sort -V`), and `jq` is on `PATH`. Never write
+`[ -d .beads ] && bd …` as a whole command — it returns exit 1 when `.beads/` is
+absent and breaks callers under `set -e`; use an `if`.
+
+**Step 2 — route on the decision table** (this is what prevents the "empty
+tracker looks done" bug):
+
+| Condition | Action |
+|---|---|
+| `.beads/` **absent** | Non-Beads project → drive the loop from the markdown playbook/plan (see "Markdown fallback" below). Do **not** call `bd`. |
+| `.beads/` present but `beads_usable` is false (`bd`/`jq` missing or `bd` < 1.0.5) | **Fail closed.** Stop and tell the user to install/upgrade `bd` (≥ v1.0.5) and `jq`. Do **not** markdown-fall-back — Beads may already hold execution state. |
+| `beads_usable`, plan has **no** stable IDs **and** Beads holds no plan-derived issues and no non-bootstrap claimed/closed work | Genuinely legacy plan → markdown loop, emit "re-run planning to assign stable task IDs". Do **not** claim. |
+| `beads_usable`, plan has no stable IDs **but** Beads already holds plausible build work | **Fail closed** — markdown would bypass existing execution state. |
+| `beads_usable`, contract **partially present or malformed** | **Fail closed.** Do **not** markdown-fall-back. Require planning to be re-run/fixed. |
+| `beads_usable` **and a valid stable-ID contract** | **Resume your own task; orchestrator materializes once under the lock; workers wait; then claim** (see Step 3). |
+
+**Step 3 — `beads_usable` + valid contract:**
+
+**Two distinct identities.** The merge-slot needs a **per-process unique** holder
+(e.g. `agent-$$` or a UUID) so two local agents sharing one `git user.name` don't
+both think they hold the slot. The **claim/resume actor must stay stable** per
+worktree/session — resolve `BEADS_ACTOR` → `git user.name` → `$USER` (never
+empty). Use the unique value **only** for `bd merge-slot acquire/check/release`;
+keep the stable `BEADS_ACTOR` for the resume lookup and `bd ready --claim`.
+
+1. **Resume the actor's own in-flight *plan* task first.** Before claiming
+   anything new — and using the **stable** claim actor, not the per-process lock
+   identity — check for a **plan-derived** task already `in_progress` assigned to
+   you, scoped exactly like claiming:
+   `bd list --status in_progress --assignee <actor> --has-metadata-key plan_task_id --json`.
+   If one exists, continue it (see "Resume In-Progress Work" below). Scoping to
+   `plan_task_id` prevents resuming onto an unrelated manual/bootstrap issue
+   assigned to the same actor; any such non-plan in-progress work is reported
+   separately, not resumed as build work.
+2. **Reconcile merged PRs.** If a PR shows as merged, close the corresponding
+   task: `bd close <id>`.
+3. **Orchestrator-only materialization under the merge-slot lock.** Only the wave
+   orchestrator (the first agent resuming the wave) runs the materializer;
+   workers skip to step 4. The orchestrator:
+   - **Clears/overwrites any stale completion signal before acquiring the lock**,
+     so a signal left from a previous pipeline run (or a pre-update plan) can't
+     let workers race ahead of a fresh re-materialization. The **completion
+     signal must be run-stamped** — carry a `run_id` or the current plan hash
+     (e.g. a metadata flag on the project merge-slot/bootstrap bead, or a
+     workspace marker recording `run_id` / `materialized_at`).
+   - **Acquires the lock with a real acquisition loop, not a status poll** — loop
+     on `bd merge-slot acquire` itself and re-verify ownership via
+     `bd merge-slot check --json` (a released slot is `holder: null` and never
+     auto-promotes a waiter). Guard the non-zero/queued return with `|| true` and
+     release via a `trap … EXIT INT TERM`.
+   - **Once ownership is confirmed, invokes `/scaffold:materialize-plan-to-beads`**
+     (the canonical procedure — do not duplicate the four-pass logic). It is
+     idempotent and a cheap no-op when in sync. If it returns non-zero, **fail
+     closed** (do not set the signal, do not claim, do not markdown-fall-back).
+   - On success, **sets the run-stamped completion signal**, then **releases**
+     the slot.
+4. **Workers block on the run-stamped completion signal before their first
+   claim.** A released slot (`holder: null`) does **not** prove the orchestrator
+   ran — blocking on slot release alone is insufficient (a worker could
+   acquire/release before the orchestrator started). Workers wait until a signal
+   matching **this run's** `run_id`/plan-hash is present, then proceed.
+5. **Clean up and run the scoped claim loop** (using the **stable** `BEADS_ACTOR`,
+   not the per-process lock identity):
+   - `git fetch origin --prune && git clean -fd`
+   - Run the install command from CLAUDE.md Key Commands
+   - Atomically claim the next ready **plan** task:
+     `TASK=$(bd ready --claim --has-metadata-key plan_task_id --json | jq -r '.id')`
+     - Scoping to `plan_task_id` keeps the loop from ever claiming the bootstrap
+       "initialize Beads" bead or a manually-created issue.
+     - This sets `assignee=$BEADS_ACTOR` + `status=in_progress` in a single
+       round-trip — no race window between agents.
+6. Continue until the scoped claim
+   (`bd ready --claim --has-metadata-key plan_task_id --json`) returns no ready
+   task, then run the **completion check**.
+
+**Completion check (empty `bd ready` ≠ done).** An empty scoped-ready result does
+**not** mean the build is finished. On an empty result, fetch all plan-derived
+tasks (`bd list --all --limit 0 --has-metadata-key plan_task_id --json`) and
+classify the remaining non-`closed` tasks:
+
+- **All plan tasks `closed`** → genuinely **done**; exit gracefully.
+- Otherwise classify **each** remaining non-`closed` task independently — do
+  **not** short-circuit on "any task is `in_progress`". Resolve blocker statuses
+  from an **unfiltered** `bd list --all --limit 0 --json` (manual blockers carry
+  no `plan_task_id`):
+  - **advancing** — the task is itself `in_progress`, **or** a **transitive**
+    blocker (walk the chain; bound the walk, reuse `bd dep cycles`) is
+    `in_progress`.
+  - **stalled** — not `in_progress` and no transitive blocker is `in_progress`.
+- **All remaining advancing** → exit gracefully (normal multi-agent case). **Any
+  stalled** → **stop and report the stalled subset**, grouped by why (open
+  dependency, manual `blocked`, `deferred`). Unrelated global `in_progress` work
+  that blocks none of the stalled tasks does **not** suppress the report.
+
+**Markdown fallback** (only when `.beads/` is **absent**, or for a genuinely
+legacy plan per the table — never past existing Beads state):
 - Read `docs/implementation-playbook.md` as the primary task reference.
   Fall back to `docs/implementation-plan.md` when no playbook is present.
 - If a PR shows as merged, mark the corresponding task as complete in the plan/playbook

package/content/pipeline/build/multi-agent-start.md

@@ -123,17 +123,110 @@ These rules are critical for multi-agent operation:
 
 ### Beads Detection
 
-**If Beads is configured** (`.beads/` exists):
-- Branch naming: `bd-<id>/<desc>`
-- Verify `$BEADS_ACTOR` is set per agent (echo it; bail if empty).
-- Atomically claim the next ready task: `TASK=$(bd ready --claim --json | jq -r '.id')`
-  - This sets `assignee=$BEADS_ACTOR` and `status=in_progress` in a single round-trip — eliminates the race window where two agents both see the same "ready" task.
-  - If `bd ready --claim` returns no task, you're done — exit the loop.
-- Implement following the TDD workflow below
-- After PR is merged: `bd close <id>`
-- Repeat (`bd ready --claim --json`) until no tasks remain
-
-**Without Beads:**
+The implementation plan is materialized into Beads issues by
+`/scaffold:materialize-plan-to-beads` before the build phase. This block is the
+**defensive preflight** that guarantees the tracker is populated and current
+before any agent claims work — it never claims against an empty or stale tracker.
+Under multi-agent concurrency, materialization is **orchestrator-only** and runs
+**once per wave under a merge-slot lock**; workers never materialize and must
+wait for a run-stamped completion signal before their first claim.
+
+**Step 1 — compute `beads_usable`.** `beads_usable` is true only when **all**
+hold: `.beads/` exists, `bd` is on `PATH`, `bd version` parses to **≥ 1.0.5**
+(using a macOS/BSD-safe numeric compare — split major/minor/patch and compare
+numerically, never rely on GNU `sort -V`), and `jq` is on `PATH`. Never write
+`[ -d .beads ] && bd …` as a whole command — it returns exit 1 when `.beads/` is
+absent and breaks callers under `set -e`; use an `if`.
+
+**Step 2 — route on the decision table** (this is what prevents the "empty
+tracker looks done" bug):
+
+| Condition | Action |
+|---|---|
+| `.beads/` **absent** | Non-Beads project → drive the loop from the markdown playbook/plan (see "Markdown fallback" below). Do **not** call `bd`. |
+| `.beads/` present but `beads_usable` is false (`bd`/`jq` missing or `bd` < 1.0.5) | **Fail closed.** Stop and tell the user to install/upgrade `bd` (≥ v1.0.5) and `jq`. Do **not** markdown-fall-back — Beads may already hold execution state. |
+| `beads_usable`, but the plan has **no** stable task IDs **and** Beads holds no plan-derived issues and no non-bootstrap claimed/closed work | Genuinely legacy plan → markdown loop, and emit "re-run planning to assign stable task IDs". Do **not** claim. |
+| `beads_usable`, plan has no stable IDs **but** Beads already holds plausible build work (claimed/closed non-bootstrap issues) | **Fail closed** — markdown would bypass existing execution state. Require re-running planning + materialization. |
+| `beads_usable`, contract **partially present or malformed** | **Fail closed.** Do **not** markdown-fall-back (would bypass existing plan-derived issues and diverge). Require planning to be re-run/fixed. |
+| `beads_usable` **and a valid stable-ID contract** | **Orchestrator materializes once under the lock, then everyone claims** (see Step 3). |
+
+**Step 3 — `beads_usable` + valid contract → orchestrator materializes, workers wait, then claim:**
+
+Branch naming: `bd-<id>/<desc>`. Verify `$BEADS_ACTOR` is set per agent (echo it;
+bail if empty).
+
+**Two distinct identities.** The merge-slot needs a **per-process unique** holder
+(e.g. `agent-$$` or a UUID) so two local agents sharing one `git user.name` don't
+both think they hold the slot. The **claim/resume actor must stay stable** per
+worktree/session — resolve `BEADS_ACTOR` → `git user.name` → `$USER` (never
+empty). Use the unique value **only** for `bd merge-slot acquire/check/release`;
+keep the stable `BEADS_ACTOR` for `bd ready --claim`. If you must override
+`BEADS_ACTOR` for the lock, scope that override to the lock commands and restore
+the stable actor before claiming.
+
+1. **Orchestrator-only materialization under the merge-slot lock.** Only the wave
+   orchestrator (the first agent) runs the materializer; workers skip to step 2.
+   The orchestrator:
+   - **Clears/overwrites any stale completion signal before acquiring the lock**,
+     so a signal left from a previous pipeline run (or a pre-update plan) can't
+     let workers race ahead of a fresh re-materialization. The **completion
+     signal must be run-stamped** — carry a `run_id` or the current plan hash
+     (e.g. a metadata flag on the project merge-slot/bootstrap bead, or a
+     workspace marker file recording `run_id` / `materialized_at`).
+   - **Acquires the lock with a real acquisition loop, not a status poll** — loop
+     on `bd merge-slot acquire` itself and re-verify ownership via
+     `bd merge-slot check --json` (a released slot is `holder: null` and never
+     auto-promotes a waiter, so a check-only loop deadlocks). Guard the
+     non-zero/queued return with `|| true` and release via a
+     `trap … EXIT INT TERM`.
+   - **Once ownership is confirmed, invokes `/scaffold:materialize-plan-to-beads`**
+     (the canonical procedure — do not duplicate the four-pass logic). It is
+     idempotent and a cheap no-op when already in sync. If it returns non-zero,
+     **fail closed** (do not set the signal, do not claim, do not markdown-fall-back).
+   - On success, **sets the run-stamped completion signal**, then **releases**
+     the slot.
+2. **Workers block on the run-stamped completion signal before their first
+   claim.** A released slot (`holder: null`) does **not** prove the orchestrator
+   ran — a worker could acquire/release before the orchestrator even started. So
+   workers wait until a signal matching **this run's** `run_id`/plan-hash is
+   present, then proceed. The lock serializes the *write*; the run-stamped signal
+   gates the *readers*.
+3. **Run the scoped claim loop** (using the **stable** `BEADS_ACTOR`, not the
+   per-process lock identity). Atomically claim the next ready **plan** task:
+   `TASK=$(bd ready --claim --has-metadata-key plan_task_id --json | jq -r '.id')`
+   - Scoping to `plan_task_id` keeps the loop from ever claiming the bootstrap
+     "initialize Beads" bead or a manually-created issue.
+   - This sets `assignee=$BEADS_ACTOR` and `status=in_progress` in a single
+     round-trip — eliminates the race window where two agents both see the same
+     "ready" task.
+4. Implement following the TDD workflow below.
+5. After the PR is merged: `bd close <id>`.
+6. Repeat the scoped claim (`bd ready --claim --has-metadata-key plan_task_id --json`)
+   until it returns no ready task, then run the **completion check**.
+
+**Completion check (empty `bd ready` ≠ done).** An empty scoped-ready result does
+**not** mean the build is finished. On an empty result, fetch all plan-derived
+tasks (`bd list --all --limit 0 --has-metadata-key plan_task_id --json`) and
+classify the remaining non-`closed` tasks:
+
+- **All plan tasks `closed`** → genuinely **done**; exit gracefully.
+- Otherwise classify **each** remaining non-`closed` task independently — do
+  **not** short-circuit on "any task is `in_progress`". Resolve blocker statuses
+  from an **unfiltered** `bd list --all --limit 0 --json` (manual blockers carry
+  no `plan_task_id`):
+  - **advancing** — the task is itself `in_progress`, **or** at least one of its
+    **transitive** blockers (walk the chain; bound the walk, reuse
+    `bd dep cycles`) is `in_progress`.
+  - **stalled** — not `in_progress` and **no** transitive blocker is
+    `in_progress`.
+- **All remaining tasks advancing** → exit gracefully (normal multi-agent case;
+  other agents are still working).
+- **Any task stalled** → **stop and report the stalled subset**, grouped by why
+  (open dependency, manual `blocked`, `deferred`). Unrelated global `in_progress`
+  work that blocks none of the stalled tasks does **not** suppress the report.
+
+**Markdown fallback** (only when `.beads/` is **absent**, or for a genuinely
+legacy plan per the table — never past existing Beads state):
 - Branch naming: `<type>/<desc>` (e.g., `feat/add-auth`)
 1. Read `docs/implementation-playbook.md` as the primary task execution reference.
    Fall back to `docs/implementation-plan.md` when no playbook is present.

package/content/pipeline/build/single-agent-resume.md

@@ -96,14 +96,80 @@ Recover your context by checking the current state of work:
 
 ### Beads Recovery
 
-**If Beads is configured** (`.beads/` exists):
-- `bd list` — check for tasks with `in_progress` status
-- If a PR shows as merged, close the corresponding task: `bd close <id>`
-- If there is in-progress work, finish it (see "Resume In-Progress Work" below)
-- Otherwise, atomically claim the next ready task: `TASK=$(bd ready --claim --json | jq -r '.id')` (sets `assignee=$BEADS_ACTOR` + `status=in_progress`; no race window).
-- Continue working until `bd ready --claim --json` returns no task.
-
-**Without Beads:**
+The implementation plan is materialized into Beads issues by
+`/scaffold:materialize-plan-to-beads` before the build phase. A resumed build
+runs the **same defensive preflight** as the start prompt — it never claims
+against an empty or stale tracker.
+
+**Step 1 — compute `beads_usable`.** `beads_usable` is true only when **all**
+hold: `.beads/` exists, `bd` is on `PATH`, `bd version` parses to **≥ 1.0.5**
+(using a macOS/BSD-safe numeric compare — split major/minor/patch and compare
+numerically, never rely on GNU `sort -V`), and `jq` is on `PATH`. Never write
+`[ -d .beads ] && bd …` as a whole command — it returns exit 1 when `.beads/` is
+absent and breaks callers under `set -e`; use an `if`.
+
+**Step 2 — route on the decision table** (this is what prevents the "empty
+tracker looks done" bug):
+
+| Condition | Action |
+|---|---|
+| `.beads/` **absent** | Non-Beads project → drive the loop from the markdown playbook/plan (see "Markdown fallback" below). Do **not** call `bd`. |
+| `.beads/` present but `beads_usable` is false (`bd`/`jq` missing or `bd` < 1.0.5) | **Fail closed.** Stop and tell the user to install/upgrade `bd` (≥ v1.0.5) and `jq`. Do **not** markdown-fall-back — Beads may already hold execution state. |
+| `beads_usable`, plan has **no** stable IDs **and** Beads holds no plan-derived issues and no non-bootstrap claimed/closed work | Genuinely legacy plan → markdown loop, emit "re-run planning to assign stable task IDs". Do **not** claim. |
+| `beads_usable`, plan has no stable IDs **but** Beads already holds plausible build work | **Fail closed** — markdown would bypass existing execution state. |
+| `beads_usable`, contract **partially present or malformed** | **Fail closed.** Do **not** markdown-fall-back. Require planning to be re-run/fixed. |
+| `beads_usable` **and a valid stable-ID contract** | **Resume your own task, materialize, then claim** (see Step 3). |
+
+**Step 3 — `beads_usable` + valid contract:**
+
+1. **Resume the actor's own in-flight *plan* task first.** Before claiming
+   anything new — and using the **stable** claim actor (resolve `BEADS_ACTOR` →
+   `git user.name` → `$USER`, never empty) — check for a **plan-derived** task
+   already `in_progress` assigned to you, scoped exactly like claiming:
+   `bd list --status in_progress --assignee <actor> --has-metadata-key plan_task_id --json`.
+   If one exists, continue it (see "Resume In-Progress Work" below). Scoping to
+   `plan_task_id` prevents resuming onto an unrelated manual/bootstrap issue
+   assigned to the same actor; any such non-plan in-progress work is reported
+   separately, not resumed as build work.
+2. **Reconcile merged PRs.** If a PR shows as merged, close the corresponding
+   task: `bd close <id>`.
+3. **Always invoke the canonical materializer** before claiming new work:
+   `/scaffold:materialize-plan-to-beads`. Run it unconditionally — do **not**
+   gate it on a count or ID-set comparison. It is idempotent (a cheap no-op when
+   in sync) and is the single source of the four-pass reconcile logic — this
+   prompt **invokes** it, it does not duplicate it. If it returns non-zero,
+   **fail closed** — stop, surface the error, do **not** claim and do **not**
+   markdown-fall-back past existing Beads state.
+4. **Run the scoped claim loop.** Atomically claim the next ready **plan** task:
+   `TASK=$(bd ready --claim --has-metadata-key plan_task_id --json | jq -r '.id')`
+   - Scoping to `plan_task_id` keeps the loop from ever claiming the bootstrap
+     "initialize Beads" bead or a manually-created issue.
+   - This sets `assignee=$BEADS_ACTOR` + `status=in_progress` in a single
+     round-trip — no race window.
+5. Continue until the scoped claim
+   (`bd ready --claim --has-metadata-key plan_task_id --json`) returns no ready
+   task, then run the **completion check**.
+
+**Completion check (empty `bd ready` ≠ done).** An empty scoped-ready result does
+**not** mean the build is finished. On an empty result, fetch all plan-derived
+tasks (`bd list --all --limit 0 --has-metadata-key plan_task_id --json`) and
+classify the remaining non-`closed` tasks:
+
+- **All plan tasks `closed`** → genuinely **done**; exit gracefully.
+- Otherwise classify **each** remaining non-`closed` task independently — do
+  **not** short-circuit on "any task is `in_progress`". Resolve blocker statuses
+  from an **unfiltered** `bd list --all --limit 0 --json` (manual blockers carry
+  no `plan_task_id`):
+  - **advancing** — the task is itself `in_progress`, **or** a **transitive**
+    blocker (walk the chain; bound the walk, reuse `bd dep cycles`) is
+    `in_progress`.
+  - **stalled** — not `in_progress` and no transitive blocker is `in_progress`.
+- **All remaining advancing** → exit gracefully. **Any stalled** → **stop and
+  report the stalled subset**, grouped by why (open dependency, manual `blocked`,
+  `deferred`).
+
+**Markdown fallback** (only when `.beads/` is **absent**, or for a genuinely
+legacy plan per the table — never past existing Beads state):
 - Read `docs/implementation-playbook.md` as the primary task reference.
   Fall back to `docs/implementation-plan.md` when no playbook is present.
 - If a PR shows as merged, mark the corresponding task as complete in the plan/playbook

package/content/pipeline/build/single-agent-start.md

@@ -98,18 +98,75 @@ Before writing any code, verify the environment is ready:
 
 ### Beads Detection
 
-Check if `.beads/` directory exists.
-
-**If Beads is configured:**
-- Atomically claim the next ready task: `TASK=$(bd ready --claim --json | jq -r '.id')`
-  - This sets `assignee=$BEADS_ACTOR` (or your git user.name) and `status=in_progress` in a single round-trip — no race window vs other agents.
-  - If you need a specific task by ID instead, use `bd update <id> --claim`.
-  - If `bd ready --claim` returns no task, you're done — exit the loop.
-- Implement following the TDD workflow below
-- After PR is merged, run `bd close <id>`
-- Repeat (`bd ready --claim --json`) until no tasks remain
-
-**Without Beads:**
+The implementation plan is materialized into Beads issues by
+`/scaffold:materialize-plan-to-beads` before the build phase. This block is the
+**defensive preflight** that guarantees the tracker is populated and current
+before any work is claimed — it never claims against an empty or stale tracker.
+
+**Step 1 — compute `beads_usable`.** `beads_usable` is true only when **all**
+hold: `.beads/` exists, `bd` is on `PATH`, `bd version` parses to **≥ 1.0.5**
+(using a macOS/BSD-safe numeric compare — split major/minor/patch and compare
+numerically, never rely on GNU `sort -V`), and `jq` is on `PATH`. Never write
+`[ -d .beads ] && bd …` as a whole command — it returns exit 1 when `.beads/` is
+absent and breaks callers under `set -e`; use an `if`.
+
+**Step 2 — route on the decision table** (this is what prevents the "empty
+tracker looks done" bug):
+
+| Condition | Action |
+|---|---|
+| `.beads/` **absent** | Non-Beads project → drive the loop from the markdown playbook/plan (see "Markdown fallback" below). Do **not** call `bd`. |
+| `.beads/` present but `beads_usable` is false (`bd`/`jq` missing or `bd` < 1.0.5) | **Fail closed.** Stop and tell the user to install/upgrade `bd` (≥ v1.0.5) and `jq`. Do **not** markdown-fall-back — Beads may already hold execution state, and a markdown re-run would re-execute completed work. |
+| `beads_usable`, but the plan has **no** stable task IDs **and** Beads holds no plan-derived issues and no non-bootstrap claimed/closed work | Genuinely legacy plan → markdown loop, and emit "re-run planning to assign stable task IDs". Do **not** claim. |
+| `beads_usable`, plan has no stable IDs **but** Beads already holds plausible build work (claimed/closed non-bootstrap issues) | **Fail closed** — markdown would bypass existing execution state. Require re-running planning + materialization. |
+| `beads_usable`, contract **partially present or malformed** (some IDs present, or plan-derived issues already exist, but the contract doesn't fully parse) | **Fail closed.** Do **not** markdown-fall-back (would bypass existing plan-derived issues and diverge). Require planning to be re-run/fixed. |
+| `beads_usable` **and a valid stable-ID contract** | **Always materialize first, then claim** (see Step 3). |
+
+**Step 3 — `beads_usable` + valid contract → materialize, then claim:**
+
+1. **Always invoke the canonical materializer:** `/scaffold:materialize-plan-to-beads`.
+   Run it unconditionally — do **not** gate it on a count or ID-set comparison
+   (every such gate misses content-only edits, partial imports, or stale deps).
+   The materializer is idempotent and a cheap no-op when already in sync; it is
+   the single source of the four-pass reconcile logic — this prompt **invokes**
+   it, it does not duplicate it. If the materializer returns non-zero (mid-run
+   failure), **fail closed** — stop and surface the error; do **not** claim and
+   do **not** markdown-fall-back past existing Beads state.
+2. **Run the scoped claim loop.** Atomically claim the next ready **plan** task:
+   `TASK=$(bd ready --claim --has-metadata-key plan_task_id --json | jq -r '.id')`
+   - Scoping to `plan_task_id` keeps the loop from ever claiming the bootstrap
+     "initialize Beads" bead or a manually-created issue.
+   - This sets `assignee=$BEADS_ACTOR` (or your git user.name) and
+     `status=in_progress` in a single round-trip — no race window.
+   - If you need a specific task by ID instead, use `bd update <id> --claim`.
+3. Implement following the TDD workflow below.
+4. After the PR is merged, run `bd close <id>`.
+5. Repeat the scoped claim (`bd ready --claim --has-metadata-key plan_task_id --json`)
+   until it returns no ready task, then run the **completion check**.
+
+**Completion check (empty `bd ready` ≠ done).** An empty scoped-ready result does
+**not** mean the build is finished — every remaining task could be blocked. On an
+empty result, fetch all plan-derived tasks
+(`bd list --all --limit 0 --has-metadata-key plan_task_id --json`) and classify
+the remaining non-`closed` tasks:
+
+- **All plan tasks `closed`** → genuinely **done**; exit gracefully.
+- Otherwise classify **each** remaining non-`closed` task independently — do
+  **not** short-circuit on "any task is `in_progress`". Resolve blocker statuses
+  from an **unfiltered** `bd list --all --limit 0 --json` (manual blockers carry
+  no `plan_task_id`):
+  - **advancing** — the task is itself `in_progress`, **or** at least one of its
+    **transitive** blockers (walk the chain; bound the walk and reuse
+    `bd dep cycles` as a guard) is `in_progress`.
+  - **stalled** — not `in_progress` and **no** transitive blocker is
+    `in_progress` (open-but-unready behind inactive blockers, manually `blocked`,
+    or `deferred`).
+- **All remaining tasks advancing** → exit gracefully.
+- **Any task stalled** → **stop and report the stalled subset**, grouped by why
+  (open dependency, manual `blocked`, `deferred`), so the user can unblock them.
+
+**Markdown fallback** (only when `.beads/` is **absent**, or for a genuinely
+legacy plan per the table — never past existing Beads state):
 1. Read `docs/implementation-playbook.md` as the primary task execution reference.
    Fall back to `docs/implementation-plan.md` when no playbook is present.
 2. Pick the first uncompleted task that has no unfinished dependencies.