@zigrivers/scaffold 3.27.0 → 3.28.0

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

@@ -9,7 +9,7 @@ outputs: []
 conditional: null
 stateless: true
 category: pipeline
-knowledge-base: [tdd-execution-loop, task-claiming-strategy, worktree-management]
+knowledge-base: [tdd-execution-loop, task-claiming-strategy, worktree-management, multi-agent-coordination]
 reads: [coding-standards, tdd, git-workflow]
 argument-hint: "<agent-name>"
 ---
@@ -90,7 +90,7 @@ Before writing any code, verify the worktree environment:
    - If on a feature branch with changes, redirect to `/scaffold:multi-agent-resume $ARGUMENTS`
 
 3. **Beads identity** (if `.beads/` exists)
-   - `echo $BD_ACTOR` — should show `$ARGUMENTS`
+   - `echo $BEADS_ACTOR` — should show `$ARGUMENTS`
    - If not set, the worktree setup may be incomplete
 
 4. **Dependency check**
@@ -119,11 +119,13 @@ These rules are critical for multi-agent operation:
 
 **If Beads is configured** (`.beads/` exists):
 - Branch naming: `bd-<id>/<desc>`
-- Run `bd ready` to see available tasks
-- Pick the lowest-ID unblocked task
+- 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> && bd sync`
-- Repeat with `bd ready` until no tasks remain
+- After PR is merged: `bd close <id>`
+- Repeat (`bd ready --claim --json`) until no tasks remain
 
 **Without Beads:**
 - Branch naming: `<type>/<desc>` (e.g., `feat/add-auth`)
@@ -174,8 +176,28 @@ For each task:
    - Fix any findings at or above `fix_threshold` before proceeding
 
 7. **Create PR**
+   - If Beads is configured, run the PR-readiness checklist first:
+     ```bash
+     if [ -d .beads ]; then
+       bd preflight
+     fi
+     ```
+     Fix any issues `bd preflight` flags before proceeding.
+   - **For 3+ parallel agents**, acquire the project's merge slot to serialize merge-time conflicts:
+     ```bash
+     if [ -d .beads ]; then
+       bd merge-slot acquire --wait    # blocks if held; queues you in priority order
+     fi
+     ```
+     There is one merge slot per project; `--wait` blocks until you have it. Skip for single-agent or two-agent runs. See `content/knowledge/execution/multi-agent-coordination.md`.
    - Push the branch: `git push -u origin HEAD`
    - Create a pull request: `gh pr create`
+   - After the PR merges (or if you abandon the work), release the slot:
+     ```bash
+     if [ -d .beads ]; then
+       bd merge-slot release   # holder verified via $BEADS_ACTOR
+     fi
+     ```
    - Include in the PR description: what was implemented, key decisions, files changed, agent name
    - Follow the PR workflow from `docs/git-workflow.md` or CLAUDE.md
 
@@ -210,10 +232,16 @@ For each task:
 - Resolve conflicts, re-run tests, force-push the branch
 
 **Another agent claimed the same task:**
-- If Beads: `bd sync` will reveal the conflict — pick a different task
+- If Beads: A `git pull` (and `bd dolt pull` if a Dolt remote is configured) brings the local DB current; run `bd doctor --fix` if anything looks stale.
 - Without Beads: check open PRs (`gh pr list`) for overlapping work
 - Move to the next available unblocked task
 
+**A downstream task is blocked on a specific async condition (PR merge, workflow run, timer, human decision):**
+- If Beads: create a gate that blocks the downstream task. The gate has an auto-generated ID. For a PR-merge blocker: `bd gate create --type=gh:pr --blocks <task-id> --await-id=<pr-number> --reason "..."`. For a human-resolved blocker: `bd gate create --blocks <task-id> --reason "..."` (defaults to `--type=human`). Capture the gate ID via `--json | jq -r '.id'` if you need to resolve manually later.
+- The gated task disappears from `bd ready` until the gate resolves. `gh:pr` / `gh:run` / `timer` gates auto-resolve via watchers; `human` gates resolve via `bd gate resolve <gate-id>`.
+- If multiple downstream tasks share one underlying blocker, create one gate per blocked task pointing at the same `--await-id`. For dependency-style blocking ("this task can't start until that task finishes"), use `bd dep add --blocks` instead.
+- See `content/knowledge/execution/multi-agent-coordination.md` for the full pattern.
+
 **Dependency install fails after cleanup:**
 - `git clean -fd` may have removed generated files — re-run the full install sequence
 - If persistent, check if another agent's merge changed the dependency file

package/content/pipeline/build/new-enhancement.md

@@ -263,9 +263,16 @@ For each user story (or logical grouping of small stories):
 **If Beads:**
 ```bash
 bd create "US-XXX: <imperative title>" -p <priority>
-# Priority: 0=blocking release, 1=must-have, 2=should-have, 3=nice-to-have
+# Priority: 0=blocking release, 1=must-have, 2=should-have, 3=nice-to-have, 4=backlog
 ```
 
+For architectural decisions (ADRs), use the built-in `decision` type:
+```bash
+bd create "Use Postgres over MySQL for X" -t decision -p 1
+```
+
+If your project enables custom types via `bd config set types.custom '["story","milestone","spike"]'`, you can also use `-t story` for user-story-sized work and `-t milestone` for releases.
+
 **Without Beads:** Document tasks as a structured list in `docs/implementation-plan.md` with title, priority, dependencies, and description.
 
 #### Task Titles and Descriptions

package/content/pipeline/build/quick-task.md

@@ -157,6 +157,7 @@ Assign priority using Beads conventions:
 - **P1** — Must-have for current milestone
 - **P2** — Should-have (default for most quick tasks)
 - **P3** — Nice-to-have, backlog
+- **P4** — Backlog / future-consideration (lowest priority; effectively deferred)
 
 #### Acceptance Criteria
 Write 2-5 testable acceptance criteria in Given/When/Then format:
@@ -202,6 +203,14 @@ bd create "type(scope): description" -p <priority>
 # Example: bd create "fix(auth): prevent duplicate session creation on rapid re-login" -p 2
 ```
 
+If this task was discovered while doing other work, link the lineage with `discovered-from`:
+```bash
+bd create "fix(parser): handle empty input edge case" \
+  --type bug -p 2 \
+  --deps discovered-from:$CURRENT_TASK_ID
+```
+The new task appears in `bd ready` normally; `discovered-from` is metadata for traceability and does NOT block readiness.
+
 **Without Beads:** Document the task inline and proceed directly to implementation.
 
 Then set the task description with the full context from Phase 2. Include all of:

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

@@ -98,10 +98,10 @@ Recover your context by checking the current state of work:
 
 **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> && bd sync`
+- 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, start fresh with `bd ready` to find the next available task
-- Continue working until `bd ready` shows no available tasks
+- 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:**
 - Read `docs/implementation-playbook.md` as the primary task reference.
@@ -148,6 +148,13 @@ Once in-progress work is complete (or if there was none):
    - Fix any findings at or above `fix_threshold` before proceeding
 
 3. **Create PR** (if not already created for in-progress work)
+   - If Beads is configured, run the PR-readiness checklist first:
+     ```bash
+     if [ -d .beads ]; then
+       bd preflight
+     fi
+     ```
+     Fix any issues `bd preflight` flags before proceeding.
    - Push the branch: `git push -u origin HEAD`
    - Create a pull request: `gh pr create`
    - Follow the PR workflow from `docs/git-workflow.md` or CLAUDE.md
@@ -187,7 +194,7 @@ Once in-progress work is complete (or if there was none):
 - Push updates and re-request review
 
 **Task was completed by another agent (multi-agent overlap):**
-- If Beads: `bd sync` will show updated task states
+- If Beads: A `git pull` (and `bd dolt pull` if a Dolt remote is configured) brings the local DB current; run `bd doctor --fix` if anything looks stale.
 - Without Beads: check the plan/playbook for recently completed tasks
 - Skip to the next available task
 

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

@@ -101,11 +101,13 @@ Before writing any code, verify the environment is ready:
 Check if `.beads/` directory exists.
 
 **If Beads is configured:**
-- Run `bd ready` to see available tasks
-- Pick the lowest-ID unblocked task
+- 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> && bd sync`
-- Repeat with `bd ready` until no tasks remain
+- After PR is merged, run `bd close <id>`
+- Repeat (`bd ready --claim --json`) until no tasks remain
 
 **Without Beads:**
 1. Read `docs/implementation-playbook.md` as the primary task execution reference.
@@ -153,6 +155,13 @@ For each task:
    - Fix any findings at or above `fix_threshold` before proceeding
 
 7. **Create PR**
+   - If Beads is configured, run the PR-readiness checklist first:
+     ```bash
+     if [ -d .beads ]; then
+       bd preflight
+     fi
+     ```
+     Fix any issues `bd preflight` flags before proceeding. (Note: do NOT use `[ -d .beads ] && bd preflight` — that returns exit-1 when `.beads/` is absent and breaks any caller running under `set -e`.)
    - Push the branch: `git push -u origin HEAD`
    - Create a pull request: `gh pr create`
    - Include in the PR description: what was implemented, key decisions, files changed

package/content/pipeline/consolidation/workflow-audit.md

@@ -37,7 +37,7 @@ inconsistent command formats. Fix all issues found.
 
 ## Quality Criteria
 - (mvp) CLAUDE.md contains complete workflow (9 steps + AI review step 4.5)
-- (mvp) Commit format is consistent everywhere (If Beads: [BD-<id>] type(scope): description. Without Beads: type(scope): description)
+- (mvp) Commit format is consistent everywhere (If Beads: [bd-<id>] type(scope): description. Without Beads: type(scope): description)
 - (mvp) Branch naming is consistent everywhere (If Beads: bd-<task-id>/<short-desc>. Without Beads: <type>/<short-desc>)
 - (mvp) PR workflow includes all 8 sub-steps with --delete-branch flag
 - (mvp) If Beads: task closure uses bd close (not bd update --status completed)

package/content/pipeline/environment/git-workflow.md

@@ -34,11 +34,11 @@ parallel agents, CI pipeline, branch protection, and conflict prevention rules.
 
 ## Quality Criteria
 - (mvp) Branch naming format is consistent (Beads: bd-<task-id>/<desc>. Non-Beads: <type>/<desc>)
-- (mvp) Commit format is consistent (Beads: [BD-<id>] type(scope): desc. Non-Beads: type(scope): desc)
+- (mvp) Commit format is consistent (Beads: [bd-<id>] type(scope): desc. Non-Beads: type(scope): desc)
 - (deep) PR workflow includes all 8 sub-steps (commit, AI review, rebase, push, create,
   auto-merge with --delete-branch, watch CI, confirm merge)
 - (deep) Worktree script creates permanent worktrees with workspace branches
-- (deep) If Beads: BD_ACTOR environment variable documented for agent identity
+- (deep) If Beads: BEADS_ACTOR environment variable documented for agent identity
 - (deep) CI workflow job name matches branch protection context
 - (mvp) Branch cleanup documented for both single-agent and worktree-agent variants
 - (deep) Agent crash recovery procedure documented

package/content/pipeline/foundation/beads.md

@@ -21,34 +21,157 @@ and autonomous behavior guidelines.
 - Existing CLAUDE.md (optional) — if present, operates in update mode
 
 ## Expected Outputs
-- .beads/ directory — initialized Beads data store with git hooks
+- .beads/ directory — initialized Beads data store with git hooks (installed/repaired via `bd doctor --fix`)
 - tasks/lessons.md — patterns and anti-patterns file for cross-session learning
-- CLAUDE.md — initial skeleton with Core Principles, Task Management (Beads),
-  Self-Improvement, and Autonomous Behavior sections
+- CLAUDE.md — marker-managed Beads integration block installed via `bd setup claude`
+  (the recipe owns the section between `<!-- BEGIN BEADS INTEGRATION ... -->` and
+  `<!-- END BEADS INTEGRATION -->`; survives re-runs). The recipe wires `bd prime
+  --hook-json` into SessionStart/PreCompact hooks so agent context is loaded
+  automatically. Scaffold adds its own Core Principles + commit convention sections
+  AROUND that block but does NOT hand-roll the Beads command reference — `bd prime`
+  is the single source of truth for agent context.
 
 ## Quality Criteria
 - (mvp) `bd ready` executes without error (Beads is initialized)
 - (mvp) .beads/ directory exists and contains Beads data files
-- (mvp) Beads git hooks are installed (data-sync hooks, not code-quality hooks)
+- (mvp) Beads git hooks are installed; `bd doctor --fix` was run after `bd init` to
+  ensure hooks/config are current (idempotent — also the canonical recovery path if
+  `bd` is upgraded later)
 - (mvp) tasks/lessons.md exists with Patterns, Anti-Patterns, and Common Gotchas sections
-- (mvp) CLAUDE.md contains Core Principles with all four tenets (Simplicity, No Laziness, TDD, Prove It)
-- (mvp) CLAUDE.md contains Beads command reference table
-- (mvp) CLAUDE.md contains commit-message convention requiring Beads task IDs
-- (mvp) Bootstrap commit uses `[BD-0]` convention
+- (mvp) `bd setup claude` was run after `bd init` to install the upstream-managed
+  Beads integration block in CLAUDE.md (marker-wrapped, hook-driven). For projects
+  also targeting Codex CLI or Gemini CLI: `bd setup codex` and/or `bd setup gemini`
+  were run. Verify with `bd setup claude --check`.
+- (mvp) CLAUDE.md contains Core Principles with all four tenets (Simplicity, No Laziness, TDD, Prove It) — scaffold-owned content, ADJACENT to the Beads-managed block
+- (mvp) CLAUDE.md contains commit-message convention requiring Beads task IDs — scaffold-owned content
+- (mvp) CLAUDE.md contains an upgrade-remediation callout: "If `bd` was upgraded since
+  last `bd init`, run `bd doctor --fix` to re-sync git hooks and project config. This
+  fixes errors like `unknown command \"hook\" for \"bd\"` from stale post-checkout /
+  post-merge hook shims."
+- (mvp) Bootstrap commit uses `[bd-<id>]` convention (lowercase hash-style IDs per Beads v1.0.0+)
+- (mvp) Auto-export to `.beads/issues.jsonl` is explicitly enabled after `bd init`:
+  `bd config set export.auto true && bd config set export.git-add true`. As of
+  Beads v1.0.4-Unreleased this is opt-in (previously default); explicit enable means
+  release/version-bump tooling can rely on `.beads/issues.jsonl` being current.
+- (mvp) Agents pick up Beads workflow context via `bd prime` (loaded automatically by
+  the hooks `bd setup claude` installs). Scaffold does NOT hand-roll a Beads command
+  reference table — that lives upstream in `bd prime` output. If a project wants
+  custom prime content, write `.beads/PRIME.md`.
+- (deep) `bd config set types.custom '["story","milestone","spike"]'` was run so
+  downstream prompts can use `-t story` and `-t milestone`. Verify with `bd config get types.custom`.
 - (deep) Cross-doc consistency verified against git-workflow.md and coding-standards.md
 
 ## Methodology Scaling
-- **deep**: Full Beads setup with all CLAUDE.md sections, detailed command reference
-  table, priority level documentation, and cross-doc consistency checks against
+- **deep**: Full Beads setup — `bd init`, then `bd doctor --fix`, then `bd setup
+  claude` (and/or `bd setup codex`, `bd setup gemini` for multi-platform projects).
+  Enable custom issue types via `bd config set types.custom '["story","milestone","spike"]'`
+  so downstream prompts can use `-t story` for user stories and `-t milestone` for
+  releases. Scaffold-owned CLAUDE.md content (Core Principles + commit convention +
+  upgrade-remediation callout) is composed ADJACENT to the recipe-managed integration
+  block. Detailed priority level documentation. Cross-doc consistency checks against
   existing git-workflow.md and coding-standards.md.
-- **mvp**: Initialize Beads, create tasks/lessons.md, add minimal CLAUDE.md
-  sections (Core Principles + Beads commands). Skip cross-doc checks.
+- **mvp**: `bd init`, `bd doctor --fix`, `bd setup claude`, create tasks/lessons.md,
+  add minimal scaffold-owned CLAUDE.md sections (Core Principles + commit convention +
+  upgrade-remediation callout). Skip cross-doc checks. Custom types stay off — only
+  built-in `bug|feature|task|epic|chore|decision` available.
 - **custom:depth(1-5)**:
-  - Depth 1: Initialize Beads + create tasks/lessons.md. Minimal CLAUDE.md with Core Principles only.
-  - Depth 2: Depth 1 + add Beads command reference table to CLAUDE.md.
-  - Depth 3: Add full command table, priority level documentation, and autonomous behavior rules.
-  - Depth 4: Full setup with cross-doc consistency checks against git-workflow.md and coding-standards.md.
-  - Depth 5: Full setup + detailed autonomous behavior rules + commit-message convention enforcement.
+  - Depth 1: `bd init` + `bd doctor --fix` + `bd setup claude` + create tasks/lessons.md. Minimal scaffold CLAUDE.md content (Core Principles only).
+  - Depth 2: Depth 1 + add commit convention + upgrade-remediation callout.
+  - Depth 3: Add priority level documentation and autonomous behavior rules.
+  - Depth 4: Full setup with cross-doc consistency checks against git-workflow.md and coding-standards.md. Enable `bd config set types.custom '["story","milestone","spike"]'`.
+  - Depth 5: Full setup + detailed autonomous behavior rules + commit-message convention enforcement. Run `bd setup codex` and `bd setup gemini` if the project targets those CLIs.
+
+## Instructions
+
+Execute these steps in order. Each is idempotent — re-running this prompt on an
+existing setup updates rather than re-initializes.
+
+1. **Initialize Beads** (skip if `.beads/` already contains a Dolt DB):
+   ```bash
+   bd init
+   ```
+
+2. **Sync hooks and project config against the installed bd version** (idempotent; also
+   the canonical recovery path if `bd` is upgraded later):
+   ```bash
+   bd doctor --fix
+   ```
+
+3. **Install the upstream-managed editor integration** for whichever AI agent CLI
+   the project targets. The recipe writes a marker-managed block in CLAUDE.md /
+   AGENTS.md / GEMINI.md and installs the SessionStart hooks that load
+   `bd prime --hook-json`:
+   ```bash
+   bd setup claude     # Claude Code (always)
+   bd setup codex      # Codex CLI (multi-platform projects only)
+   bd setup gemini     # Gemini CLI (multi-platform projects only)
+   ```
+   Verify with `bd setup claude --check`.
+
+4. **Create the project merge-slot** (one-time; idempotent — re-running on an
+   existing slot is a no-op). This is required by the multi-agent flow's
+   `bd merge-slot acquire --wait` later, and creating it now means downstream
+   PR steps can rely on it being present:
+   ```bash
+   bd merge-slot create 2>/dev/null || true   # exit 0 even if slot already exists
+   ```
+
+5. **Enable JSONL auto-export** so release/version-bump tooling can rely on
+   `.beads/issues.jsonl` being current (Beads v1.0.4-Unreleased flipped these
+   to opt-in):
+   ```bash
+   bd config set export.auto true
+   bd config set export.git-add true
+   ```
+
+6. **(deep methodology only) Enable custom issue types** so downstream prompts can
+   use `-t story` for user stories and `-t milestone` for releases:
+   ```bash
+   bd config set types.custom '["story","milestone","spike"]'
+   ```
+   Verify with `bd config get types.custom`.
+
+7. **Create the lessons-learned file** for cross-session memory (skip if it already exists — never overwrite accumulated lessons):
+   ```bash
+   mkdir -p tasks
+   if [ ! -f tasks/lessons.md ]; then
+     cat > tasks/lessons.md <<'EOF'
+   # Lessons Learned
+
+   ## Patterns
+
+   (Add discovered patterns here.)
+
+   ## Anti-Patterns
+
+   (Add anti-patterns here.)
+
+   ## Common Gotchas
+
+   (Add gotchas here.)
+   EOF
+   else
+     # Append any missing section headings; existing content stays.
+     grep -q "^## Patterns" tasks/lessons.md || printf '\n## Patterns\n\n(Add discovered patterns here.)\n' >> tasks/lessons.md
+     grep -q "^## Anti-Patterns" tasks/lessons.md || printf '\n## Anti-Patterns\n\n(Add anti-patterns here.)\n' >> tasks/lessons.md
+     grep -q "^## Common Gotchas" tasks/lessons.md || printf '\n## Common Gotchas\n\n(Add gotchas here.)\n' >> tasks/lessons.md
+   fi
+   ```
+
+8. **Compose scaffold-owned CLAUDE.md sections** ADJACENT to (not replacing) the
+   recipe-managed block from step 3. The scaffold-owned content includes Core
+   Principles (Simplicity, No Laziness, TDD, Prove It), the commit-message
+   convention (`[bd-<id>]` prefix, lowercase hash IDs), the upgrade-remediation
+   callout ("If `bd` was upgraded since last `bd init`, run `bd doctor --fix`..."),
+   and (deep) autonomous behavior rules.
+
+9. **Bootstrap commit** with the lowercase hash-style ID convention:
+   ```bash
+   git add .beads tasks/lessons.md CLAUDE.md
+   git commit -m "[bd-<id>] chore: initialize Beads task tracking"
+   ```
+   The bd-<id> here references whatever bootstrap task you created via
+   `bd create "Initialize Beads"` (or the auto-generated bootstrap bead).
 
 ## Conditional Evaluation
 Enable when: project uses Beads task tracking methodology (user selects Beads during
@@ -56,11 +179,14 @@ setup), or user explicitly enables structured task management. Skip when: user p
 GitHub Issues, Linear, or another task tracker, or explicitly declines Beads setup.
 
 ## Mode Detection
-Update mode if .beads/ contains a config.json or tasks directory (not just an
-empty directory). In update mode: never re-initialize
-.beads/ (existing task data is irreplaceable), never overwrite tasks/lessons.md
-(only add missing sections), update CLAUDE.md Beads sections in-place preserving
-project-specific customizations.
+Update mode if `.beads/` contains a populated database (look for `.beads/embeddeddolt/`
+in the default embedded-Dolt layout, `.beads/dolt/` in server mode, or any `.beads/*.db`
+file). Legacy v0.x Beads used `.beads/config.json` and a `tasks` directory — recognize
+those too for older projects. When unsure, run `bd info` from the project root: a
+populated DB returns project metadata; an uninitialized one errors. In update mode:
+never re-initialize `.beads/` (existing task data is irreplaceable), never overwrite
+`tasks/lessons.md` (only add missing sections), update CLAUDE.md Beads sections
+in-place preserving project-specific customizations.
 
 ## Update Mode Specifics
 - **Detect prior artifact**: .beads/ directory exists with data files

package/content/pipeline/foundation/coding-standards.md

@@ -33,7 +33,7 @@ self-review checklist.
 ## Quality Criteria
 - (mvp) Every standard references the specific tech stack, not generic principles
 - (deep) Includes >= 2 runnable code examples per section showing the RIGHT way for the stack
-- (mvp) Commit message format documented: if project uses Beads task tracking: [BD-<id>] type(scope): description; otherwise: type(scope): description following conventional commits
+- (mvp) Commit message format documented: if project uses Beads task tracking: [bd-<id>] type(scope): description; otherwise: type(scope): description following conventional commits
 - (mvp) AI-specific coding rules section addresses common AI mistakes (dead code,
   duplication, magic numbers, premature abstraction, unnecessary features)
 - (mvp) Linter/formatter configs created and referenced from the document

package/content/tools/post-implementation-review.md

@@ -433,9 +433,9 @@ The per-story review prompt for Codex and Gemini:
     \"findings\": [
       {
         \"severity\": \"P0|P1|P2|P3\",
+        \"category\": \"correctness|edge-case|security|acceptance-criteria|test-coverage\",
         \"acceptance_criterion\": \"Which criterion (or null if general)\",
-        \"file\": \"relative/path/to/file.ts\",
-        \"line\": 42,
+        \"location\": \"relative/path/to/file.ts:42\",
         \"description\": \"Specific description\",
         \"suggestion\": \"How to fix it\"
       }
@@ -448,7 +448,7 @@ The per-story review prompt for Codex and Gemini:
   Return ONLY valid JSON."
 
 Normalize the Superpowers code-reviewer findings to the same JSON shape as
-Codex/Gemini (severity, acceptance_criterion, file, line, description, suggestion)
+Codex/Gemini (severity, category, acceptance_criterion, location, description, suggestion)
 before returning. Then return all three channels' findings plus channel status:
 {
   "story": "[STORY_TITLE]",
@@ -479,8 +479,8 @@ mmr reconcile "$JOB_ID" --channel superpowers --input /tmp/agent-findings.json
 ```
 
 All findings injected via `mmr reconcile` must use MMR-compatible schema: each
-finding needs `severity` (P0-P3), `location` (file:line), and `description`
-(`suggestion` is optional). The strict validator will reject findings with
+finding needs `severity` (P0-P3), `category` (stable finding category),
+`location` (file:line), and `description` (`suggestion` is optional). The strict validator will reject findings with
 missing or invalid required fields.
 
 This step is optional — post-implementation review is a full-codebase review (not
@@ -721,7 +721,7 @@ the user they require manual attention before the project is ready to release.
 3. **Auth failures are not silent** — always surface to the user with the exact recovery command (`! codex login` or `! gemini -p "hello"`). Wait for user response before queuing a compensating pass.
 4. **Independence** — never share one channel's output with another. Each reviews independently.
 5. **Verify every fix** — run tests (or re-read the file) immediately after each fix before moving on.
-6. **3-round limit (per finding)** — never attempt to fix the *same* blocking finding more than 3 times. Each round that surfaces a *new, different, fixable* finding is healthy iteration — keep going. Stop only when the same finding recurs across 3 attempts, channels contradict each other, or the user asks to stop. Surface unresolved findings to the user.
+6. **3-round limit (per finding identity)** — never attempt to fix the *same* blocking finding more than 3 times. Mirror the wrapper hash identity used by `review-pr.md` and `review-code.md`: `location` + `category` + `description` + `suggestion`. This tool's JSON prompt templates already require `category`; it does not have wrapper-side Step 7a attempts-file bookkeeping, so track attempts in the review report/session notes. Each round that surfaces genuinely different findings with new identities is healthy iteration — keep going. Stop when an identity hits 3 attempts, when the same underlying defect recurs across 3 rounds even if reviewer wording changes, when channels contradict each other, or when the user asks to stop. Surface unresolved findings to the user.
 7. **Document everything** — the report must show which channels ran, which were compensating, which were skipped, and the root cause for any degraded channel.
 8. **No auto-merge** — this tool modifies local files only. It never pushes, merges, or creates PRs.
 9. **Dispatch pattern cross-reference** — Phase 2 parallel dispatch uses `superpowers:dispatching-parallel-agents`. Each story subagent dispatches its own `superpowers:code-reviewer` as Channel 3. This two-level nesting is intentional and supported.

package/content/tools/prompt-pipeline.md

@@ -27,7 +27,7 @@ Print the following reference directly. Do not read any files or run any command
 ### Phase 0 — Prerequisites (one-time)
 | Action | Command |
 |--------|---------|
-| Install Beads | `npm install -g @beads/bd` or `brew install beads` **(optional)** |
+| Install Beads | `curl -fsSL https://raw.githubusercontent.com/gastownhall/beads/main/scripts/install.sh \| bash` (upstream-recommended), `brew install beads`, or `npm install -g @beads/bd` **(optional)** |
 | Install Playwright MCP | `claude mcp add playwright npx @playwright/mcp@latest` **(optional — web apps only)** |
 
 ### Phase 0 — Product Vision (`vision`)

package/content/tools/release.md

@@ -227,14 +227,14 @@ Omit empty sections. Use the commit's first line (without the type prefix) as th
 
 If `.beads/` exists:
 
-1. Run `bd list --status closed` (or parse `.beads/issues.jsonl` for closed issues).
-2. Cross-reference closed tasks with the commit range (match task IDs like `BD-xxx` or `scaffold-xxx` in commit messages).
+1. Run `bd list --status closed --json` (canonical). If `bd` is unavailable in this environment, skip the autogenerated closed-tasks section — manual changelog entry expected.
+2. Cross-reference closed tasks with the commit range (match task IDs like `bd-xxxx` or `scaffold-xxx` in commit messages).
 3. If matches found, append a section:
 
 ```markdown
 ### Completed Tasks
-- [BD-xxx] Task title
-- [BD-yyy] Task title
+- [bd-<id>] Task title
+- [bd-<id2>] Task title
 ```
 
 If `.beads/` does not exist or no tasks match, silently skip this section.
@@ -286,7 +286,7 @@ git add <changed-files>
 git commit -m "chore(release): vX.Y.Z"
 ```
 
-If Beads is configured (`.beads/` exists) and a task is active, include the task ID: `[BD-xxx] chore(release): vX.Y.Z`.
+If Beads is configured (`.beads/` exists) and a task is active, include the task ID: `[bd-<id>] chore(release): vX.Y.Z`.
 
 ---