@zigrivers/scaffold 3.32.1 → 3.33.1

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.