@zigrivers/scaffold 3.27.0 → 3.29.0

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/knowledge-audit-entry.md

@@ -0,0 +1,79 @@
+---
+name: knowledge-audit-entry
+description: Audit one knowledge entry against its declared sources via grounded web retrieval
+category: tool
+stateless: true
+---
+
+# Knowledge Audit (Single Entry)
+
+You are auditing a single Scaffold knowledge entry against its declared authoritative sources. Your output is consumed by an automated pipeline — emit **only** the JSON object specified at the end.
+
+## Inputs
+
+- `{{entry_path}}` — absolute path to the knowledge entry being audited.
+- `{{entry_frontmatter}}` — parsed frontmatter object including `name`, `volatility`, `last-reviewed`, `version-pin`, `sources`.
+- `{{entry_body}}` — full body of the entry.
+- `{{prefetched_sources}}` — JSON array of `{url, body, hash, truncated}` objects. The Node-side audit runner has already fetched each declared source through an SSRF / DNS / redirect / timeout guard and embedded the response bodies here. **You have no web-fetch tool available — read these bodies instead.** A `truncated: true` flag means the body was capped at 96 KiB; do not infer anything is missing solely from that flag, but mention it in `preserve_warnings` if it materially limits your audit.
+
+## Procedure
+
+1. Read each entry in `{{prefetched_sources}}`. Each `body` is the current content of the corresponding source URL as of dispatch time. Treat these bodies as authoritative — they are what's live, regardless of what your training data says.
+2. Read the retrieved content carefully. Pay particular attention to:
+   - The current edition / version of any taxonomy or standard (compare against `version-pin`).
+   - Any normative statements in the entry body ("must", "should", "never") that the retrieved source contradicts or supersedes.
+   - New categories, sections, or recommendations in the source that the entry does not mention.
+3. Determine a verdict:
+   - `current` — sources confirm the entry, no findings.
+   - `minor-drift` — wording or examples slightly outdated; no substantive claims wrong.
+   - `major-drift` — substantive claims now inaccurate; structural revision needed.
+   - `superseded` — the source has shipped a new edition/version that changes the taxonomy; `version-pin` no longer applies.
+
+## CRITICAL: Grounding Rules
+
+- Where the prefetched source body contradicts the entry, **trust the prefetched body**.
+- Where the prefetched body contradicts your own prior knowledge, **trust the prefetched body**.
+- When you cannot verify a claim against any prefetched body, mark it `preserve_warnings` — do NOT mark it as drift, and do NOT invent corroboration.
+- Do not propose changes that introduce new normative claims unless those claims are verbatim or near-verbatim derivable from a prefetched body. Cite the source URL (from `{{prefetched_sources}}`) for every new normative claim.
+- Preserve the `## Summary` and `## Deep Guidance` headings exactly — the assembly engine depends on them.
+- You have NO tools available. Do not attempt to call WebFetch, Bash, Read, or any other tool. All evidence must come from `{{prefetched_sources}}` and the entry body.
+
+## Output (JSON only — no prose)
+
+```json
+{
+  "entry_name": "<from frontmatter>",
+  "audit_date": "<today's ISO date>",
+  "model": "<your model identifier>",
+  "verdict": "current | minor-drift | major-drift | superseded",
+  "sources_checked": [
+    {
+      "url": "<exact url from {{prefetched_sources}}>",
+      "retrieved_at": "<today's ISO date>",
+      "content_hash": "<exact hash from the matching {{prefetched_sources}} entry — do not recompute or invent>",
+      "summary": "<one sentence summary of what the source currently says>"
+    }
+  ],
+  "findings": [
+    {
+      "claim_in_entry": "<quoted snippet or paraphrase>",
+      "evidence_url": "<url>",
+      "evidence_date": "<ISO date>",
+      "source_excerpt": "<verbatim excerpt from retrieved source>",
+      "severity": "P0 | P1 | P2 | P3",
+      "drift_kind": "edition-upgrade | wording | new-category | obsolete-recommendation | factual-error"
+    }
+  ],
+  "proposed_changes": [
+    {
+      "location": "<exact existing top-level \"## \" heading line, e.g. \"## Deep Guidance\" or \"## OWASP Top 10\" — MUST be a verbatim H2 heading currently present in the entry. Phase 1 does not support targeting H3 or deeper subsections; if a change needs to land inside a subsection, replace or update the enclosing H2 section instead.>",
+      "kind": "replace | insert | delete",
+      "rationale": "<one sentence pointing at the finding(s) this resolves>",
+      "new_text": "<the proposed replacement or insertion text, with markdown link citations to retrieved sources. For `replace`, the new section's heading line (the same \"## \" heading) must be included as the first line. Omit this field for `delete`.>"
+    }
+  ],
+  "preserve_warnings": [
+    "<any claim you could not verify but should not change>"
+  ]
+}
+```

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`.
 
 ---