@zigrivers/scaffold 3.32.0 → 3.33.0

package/content/knowledge/mcp-server/mcp-versioning.md

@@ -0,0 +1,115 @@
+---
+name: mcp-versioning
+description: MCP protocol version negotiation, MCP-Protocol-Version HTTP header, capability-based feature detection, server versioning strategy, and backwards compatibility
+topics: [mcp, versioning, protocol-version, backwards-compatibility, capability-negotiation]
+volatility: stable
+last-reviewed: null
+version-pin: 'MCP spec 2025-11-25'
+sources:
+  - url: https://modelcontextprotocol.io/specification/2025-11-25/basic/lifecycle
+  - url: https://modelcontextprotocol.io/specification/2025-11-25/basic/transports
+---
+
+MCP uses calendar-versioned protocol strings and capability-based feature detection. Understand both mechanisms to build servers that work with current clients and remain compatible as the spec evolves.
+
+## Summary
+
+Protocol versions are date strings (e.g., `2025-11-25`). The client proposes a version in `initialize`; the server echoes it or responds with its preferred version. If versions are incompatible, the client disconnects. HTTP clients MUST include `MCP-Protocol-Version: <negotiated-version>` on all subsequent requests. Feature availability is determined by capability negotiation, not version numbers alone. For your server's own versioning, use semantic versioning; keep the `serverInfo.version` field current and stable across protocol version changes.
+
+## Deep Guidance
+
+### Protocol version strings
+
+MCP protocol versions are ISO 8601 calendar dates: `2025-11-25`, `2025-06-18`, `2025-03-26`, `2024-11-05`. Current production version is `2025-11-25`. Always send the latest version you support in the `initialize` request — the server will downgrade if needed.
+
+Version negotiation in the `initialize` handshake:
+1. Client sends `"protocolVersion": "2025-11-25"` (its latest supported version).
+2. If the server supports `2025-11-25`, it responds with `"protocolVersion": "2025-11-25"`.
+3. If the server only supports `2025-03-26`, it responds with `"protocolVersion": "2025-03-26"`.
+4. The client checks if it supports the server's response version. If not, it disconnects.
+
+This ensures both sides agree on a common protocol dialect before any other messages are exchanged.
+
+### MCP-Protocol-Version HTTP header
+
+After initialization, HTTP clients MUST send `MCP-Protocol-Version: <negotiated-version>` on every subsequent request:
+
+```
+POST /mcp HTTP/1.1
+Host: mcp.example.com
+Content-Type: application/json
+Accept: application/json, text/event-stream
+MCP-Protocol-Version: 2025-11-25
+Mcp-Session-Id: abc123
+```
+
+Servers use this header to handle requests differently based on protocol version when supporting multiple versions simultaneously. If a server receives no `MCP-Protocol-Version` header, the spec says to assume `2025-03-26` for backwards compatibility. Servers MUST return `400 Bad Request` for unsupported or invalid version header values.
+
+### Capability-based feature detection
+
+Do not version-gate features solely on protocol version numbers. Use capability negotiation instead. A server supporting `2025-11-25` may not declare the `prompts` capability — that means prompts are not available regardless of protocol version.
+
+The correct pattern for clients: check whether the server declared the capability before calling the corresponding methods. A client that calls `tools/list` without checking whether the server declared `tools` capability will receive a protocol error. The `initialize` response is the authoritative source of truth for what a server supports.
+
+For servers: declare only the capabilities you actually implement. Over-declaring capabilities (e.g., declaring `resources: { subscribe: true }` but not handling `resources/subscribe`) will cause client errors and poor UX.
+
+### Evolving your server's capabilities over versions
+
+When you add a new capability to your server (e.g., adding resource support to a tools-only server):
+- Add the capability to your `initialize` response immediately.
+- The capability declaration is backwards compatible — old clients that don't use resources will simply not call `resources/list`.
+- Do not bump your `serverInfo.version` for protocol-level changes; that field tracks your server's own software version.
+
+When you remove a capability (uncommon but possible):
+- Remove it from the `initialize` response.
+- Any client that was relying on it will receive a protocol error when they call the now-unsupported method.
+- Consider maintaining the capability with a deprecation notice in the server's `instructions` field before fully removing it.
+
+### Server software versioning
+
+The `serverInfo.version` in `initialize` is your server's semantic version (e.g., `"1.3.0"`), independent of the MCP protocol version. Follow semantic versioning:
+- **Patch** (1.0.x): bug fixes, no schema changes, no capability changes.
+- **Minor** (1.x.0): new tools/resources/prompts added, existing ones unchanged.
+- **Major** (x.0.0): removed or renamed tools/resources/prompts, breaking schema changes.
+
+Breaking changes in tool `inputSchema` or resource URI patterns are breaking changes for MCP clients that have auto-discovered and cached your server's schema. Treat them as major version bumps and communicate them in advance.
+
+### Supporting multiple protocol versions simultaneously
+
+If you need to serve both old (2024-11-05 HTTP+SSE) and new (2025-11-25 Streamable HTTP) clients:
+- Keep the old SSE GET endpoint and POST endpoint running alongside the new MCP endpoint.
+- Use the `MCP-Protocol-Version` header to route behavior within the Streamable HTTP path.
+- Set a deprecation date for old transport support and communicate it in the `serverInfo` description or via documentation.
+
+For servers that only need to support the latest spec, target `2025-11-25` and do not implement the deprecated HTTP+SSE transport. New clients target the current spec; support for the old transport is only needed if you have existing clients that have not yet migrated.
+
+### Spec evolution cadence
+
+The MCP spec has evolved on roughly a quarterly cadence: `2024-11-05` (initial), `2025-03-26` (Streamable HTTP introduction), `2025-06-18`, `2025-11-25` (current). Major changes between versions: `2024-11-05 → 2025-03-26` introduced Streamable HTTP, deprecating HTTP+SSE. `2025-03-26 → 2025-06-18` added `outputSchema` for tools, `structuredContent`, audio content type, `title` fields, and the `elicitation` client capability. `2025-06-18 → 2025-11-25` added OIDC Discovery 1.0 support; aligned OAuth Protected Resource Metadata to RFC 9728 (`WWW-Authenticate` header now optional with `.well-known` fallback); incremental scope consent and Client ID Metadata Documents for client registration; `icons` metadata on tools/resources/prompts; JSON Schema 2020-12 as the default dialect; input validation errors explicitly directed as Tool Execution Errors (`isError`) for model self-correction; Streamable HTTP servers MUST respond HTTP 403 for invalid Origin headers; stdio servers MAY use stderr for all logging; elicitation gains URL-mode, titled/untitled enums, and primitive default values; sampling gains `tools`/`toolChoice` support; experimental `tasks` feature for durable requests with polling. Watch the spec changelog (https://modelcontextprotocol.io) for new capabilities that may benefit your server.
+
+### Backwards compatibility checklist
+
+When releasing a new server version, verify these backwards compatibility invariants before shipping:
+
+1. **No renamed tools**: renaming a tool (e.g., `search_files` → `find_files`) is a breaking change. Existing clients with auto-approved tool calls will fail silently. Use the old name as an alias or bump major version with advance notice.
+2. **No removed required input fields**: removing a required field from `inputSchema` is non-breaking (callers can stop providing it); adding a new required field IS breaking (callers that don't provide it will receive validation errors).
+3. **No resource URI pattern changes**: changing `file://{path}` to `file://workspace/{path}` breaks all existing resource subscriptions and saved URIs. Treat as a major version change.
+4. **No prompt argument removals**: removing a declared prompt argument breaks clients that pass that argument.
+5. **No capability downgrades without communication**: removing `resources: { subscribe: true }` when clients have active subscriptions causes silent failures.
+
+For patch and minor releases, adding new optional tool parameters, new tools, new resources, or new prompts is always backwards compatible — existing callers ignore what they don't use.
+
+### Version signaling in serverInfo
+
+Use the `serverInfo.version` field as a machine-readable signal for clients that cache schemas:
+
+```json
+{
+  "serverInfo": {
+    "name": "my-mcp-server",
+    "version": "2.1.0"
+  }
+}
+```
+
+Clients can cache tool/resource schemas keyed by `(serverInfo.name, serverInfo.version)`. When the server bumps its version, clients re-fetch schemas rather than serving stale cached definitions. This pattern is especially important for IDE integrations and agent frameworks that pre-load tool definitions at startup.

package/content/methodology/custom-defaults.yml

@@ -43,6 +43,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" }
@@ -74,6 +75,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/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