@zigrivers/scaffold 2.38.1 → 2.44.2

package/pipeline/consolidation/claude-md-optimization.md

@@ -39,12 +39,12 @@ scannability.
 - (mvp) No verbatim repetition of content from other docs (reference instead)
 - (mvp) Consistent terminology throughout (task vs. ticket, etc.)
 - (mvp) Key Commands table matches actual Makefile/package.json commands
-- Critical patterns are prominent (TDD, never push to main, keep working,
+- (mvp) Critical patterns are prominent (TDD, never push to main, keep working,
   verify before commit, worktrees for parallel). If Beads: every commit needs task ID.
 - (deep) CLAUDE.md is <= 200 lines or critical patterns appear in the first 50 lines
 - (deep) Workflow scenarios cover error cases (test failures, merge conflicts, CI failures,
   crashed sessions, blocked tasks)
-- Tracking comment added: <!-- scaffold:claude-md-optimization v1 YYYY-MM-DD -->
+- (mvp) Tracking comment added: <!-- scaffold:claude-md-optimization v1 YYYY-MM-DD -->
 
 ## Methodology Scaling
 - **deep**: Full four-phase analysis (redundancy, consistency, gap, priority audits)
@@ -52,8 +52,12 @@ scannability.
   patterns verified present and prominent.
 - **mvp**: Quick pass to remove obvious duplicates and ensure workflow section is
   complete. Fix any command inconsistencies. Skip detailed audit.
-- **custom:depth(1-5)**: Depth 1-2: dedup + workflow check. Depth 3: add
-  consistency pass. Depth 4: add gap analysis. Depth 5: full four-phase audit.
+- **custom:depth(1-5)**:
+  - Depth 1: remove duplicated instructions within CLAUDE.md.
+  - Depth 2: dedup plus workflow section completeness check.
+  - Depth 3: add terminology consistency pass across all sections.
+  - Depth 4: add gap analysis (missing patterns, stale command references).
+  - Depth 5: full four-phase audit (redundancy, consistency, gap, priority).
 
 ## Mode Detection
 Always operates in update mode (CLAUDE.md always exists by this point). Check

package/pipeline/consolidation/workflow-audit.md

@@ -8,7 +8,7 @@ dependencies: [claude-md-optimization]
 outputs: [CLAUDE.md, docs/git-workflow.md]
 conditional: null
 reads: [operations]
-knowledge-base: [cross-phase-consistency]
+knowledge-base: [cross-phase-consistency, claude-md-patterns, git-workflow-patterns]
 ---
 
 ## Purpose
@@ -45,8 +45,8 @@ inconsistent command formats. Fix all issues found.
 - (deep) Worktree cleanup between tasks documented (cannot checkout main)
 - (deep) Agent crash recovery documented
 - (deep) No document contradicts the canonical workflow
-- Tracking comment matches format: `<!-- scaffold:workflow-audit v1 YYYY-MM-DD -->`
-- Tracking comment added: <!-- scaffold:workflow-audit v1 YYYY-MM-DD -->
+- (mvp) CLAUDE.md is the source of truth for workflow. All other documents must align with CLAUDE.md, not override it.
+- (mvp) Tracking comment matches format: `<!-- scaffold:workflow-audit v1 YYYY-MM-DD -->`
 
 ## Methodology Scaling
 - **deep**: Full six-phase audit (inventory, completeness check with all
@@ -54,8 +54,12 @@ inconsistent command formats. Fix all issues found.
   Every workflow step verified in every document.
 - **mvp**: Quick consistency check of commit format, branch naming, and PR
   workflow across CLAUDE.md and git-workflow.md. Fix obvious contradictions.
-- **custom:depth(1-5)**: Depth 1-2: CLAUDE.md workflow check only. Depth 3: add
-  cross-doc consistency. Depth 4: add gap analysis. Depth 5: full six-phase audit.
+- **custom:depth(1-5)**:
+  - Depth 1: CLAUDE.md workflow section completeness check only.
+  - Depth 2: CLAUDE.md workflow check plus commit format and branch naming verification.
+  - Depth 3: add cross-doc consistency (git-workflow.md, coding-standards.md alignment).
+  - Depth 4: add gap analysis (missing steps, stale references, Makefile target verification).
+  - Depth 5: full six-phase audit (inventory, completeness, consistency, gap analysis, recommendations, execution).
 
 ## Mode Detection
 Always operates in update mode (all documents exist by this point). Check for

package/pipeline/decisions/adrs.md

@@ -28,7 +28,7 @@ ADR category — tech stack decisions are documented here.
 ## Quality Criteria
 - (mvp) ADRs exist for: language, framework, database, ORM, deployment target, API style, authentication, and any decision referenced in system-architecture.md
 - (deep) Each ADR documents alternatives considered with pros/cons
-- (mvp) Decisions trace to PRD requirements or domain model constraints
+- (mvp) Decisions map to PRD requirements or domain model constraints
 - (mvp) No ADR contradicts another without explicit acknowledgment
 - (deep) Technology selections include team expertise and maintenance considerations
 - (deep) Decision dependencies documented — if ADR-002 depends on ADR-001's outcome, the dependency is explicit
@@ -39,8 +39,12 @@ ADR category — tech stack decisions are documented here.
   related ADRs. Supersession tracking.
 - **mvp**: Core technology choices only (language, framework, database, hosting).
   Brief rationale. Single-paragraph ADRs.
-- **custom:depth(1-5)**: Depth 1-2: core tech choices. Depth 3: add pattern
-  and integration decisions. Depth 4-5: full evaluation with risk assessment.
+- **custom:depth(1-5)**:
+  - Depth 1: core tech choices only (language, framework, database) with single-paragraph rationale.
+  - Depth 2: core tech choices plus hosting and ORM with brief rationale.
+  - Depth 3: add pattern and integration decisions with 2+ alternatives per decision.
+  - Depth 4: full evaluation with 3+ alternatives, risk assessment, and decision dependency tracking.
+  - Depth 5: full evaluation with cross-references between related ADRs, supersession tracking, and team expertise considerations.
 
 ## Mode Detection
 If docs/adrs/ exists, operate in update mode: review existing ADRs against

package/pipeline/decisions/review-adrs.md

@@ -32,20 +32,23 @@ independent review validation.
 
 ## Quality Criteria
 - (mvp) All ADR-specific review passes executed
-- (mvp) Every finding categorized P0-P3 with specific ADR number, section, and issue
+- (mvp) Every finding categorized P0-P3 with specific ADR number, section, and issue. Severity definitions: P0 = Breaks downstream work. P1 = Prevents quality milestone. P2 = Known tech debt. P3 = Polish.
 - (deep) Missing decisions identified and documented
 - (mvp) Contradictions resolved
 - (mvp) Downstream readiness confirmed (architecture phase can proceed)
-- (depth 4+) Multi-model findings synthesized with consensus/disagreement analysis
+- (depth 4+) Multi-model findings synthesized: Consensus (all models agree), Majority (2+ models agree), or Divergent (models disagree — present to user for decision)
 
 ## Methodology Scaling
 - **deep**: All review passes. Full findings report. Fixes applied and
   re-validated. Multi-model review dispatched to Codex and Gemini if available,
   with graceful fallback to Claude-only enhanced review.
 - **mvp**: Quick consistency check for contradictions only.
-- **custom:depth(1-5)**: Depth 1-3: scale number of review passes with depth.
-  Depth 4: full review + one external model (if CLI available). Depth 5:
-  full review + multi-model with reconciliation.
+- **custom:depth(1-5)**:
+  - Depth 1: single pass — contradiction check only.
+  - Depth 2: two passes — contradiction check + missing rationale scan.
+  - Depth 3: four passes — contradiction check, missing rationale, implied-but-unrecorded decisions, and unresolved trade-offs.
+  - Depth 4: all passes + one external model (if CLI available).
+  - Depth 5: all passes + multi-model with reconciliation.
 
 ## Mode Detection
 Re-review mode if previous review exists. Check which findings were addressed.

package/pipeline/environment/ai-memory-setup.md

@@ -50,8 +50,12 @@ to prevent API hallucination. Users choose which tiers to enable.
   Tier 3 configured with appropriate library doc server.
 - **mvp**: Tier 1 only (modular rules). Quick extraction of essential conventions
   into 2-3 rule files. Skip Tier 2 and 3. Minimal CLAUDE.md optimization.
-- **custom:depth(1-5)**: Depth 1-2: Tier 1 basics (2-3 rule files). Depth 3:
-  full Tier 1 + offer Tier 2. Depth 4-5: all tiers with comprehensive setup.
+- **custom:depth(1-5)**:
+  - Depth 1: Tier 1 basics — 2 rule files for core conventions.
+  - Depth 2: Tier 1 with 3-4 rule files covering code and workflow conventions.
+  - Depth 3: full Tier 1 extraction from all project docs + offer Tier 2 (persistent memory).
+  - Depth 4: all three tiers with MCP memory server and lifecycle hooks configured.
+  - Depth 5: all tiers with comprehensive setup, library doc server for all project dependencies, and CLAUDE.md optimization.
 
 ## Mode Detection
 Check if `.claude/rules/` directory or docs/ai-memory-setup.md exists first. If

package/pipeline/environment/automated-pr-review.md

@@ -5,7 +5,7 @@ summary: "Configures automated code review — using Codex and/or Gemini CLIs fo
 phase: "environment"
 order: 340
 dependencies: [git-workflow]
-outputs: [AGENTS.md, docs/review-standards.md]
+outputs: [AGENTS.md, docs/review-standards.md, scripts/cli-pr-review.sh, scripts/await-pr-review.sh]
 reads: [tdd]
 conditional: "if-needed"
 knowledge-base: [review-methodology, automated-review-tooling]
@@ -29,16 +29,17 @@ entire review-fix loop locally.
 - scripts/cli-pr-review.sh (local CLI mode) — dual-model review with reconciliation
 - scripts/await-pr-review.sh (external bot mode) — polling script with JSON output
 - docs/git-workflow.md updated with review loop integration
-- CLAUDE.md updated with agent-driven review workflow
+- CLAUDE.md updated with agent-driven review workflow and review-pr hook
 
 ## Quality Criteria
-- External reviewer configured and verified (AGENTS.md created)
-- Review standards document matches project coding conventions
-- Await script handles all exit conditions (approved, findings, cap, skip, timeout)
-- CLAUDE.md workflow documents the agent-driven loop
-- No GitHub Actions workflows created (zero Actions minutes)
-- No ANTHROPIC_API_KEY secret required
-- Legacy GitHub Actions workflows detected and cleanup offered
+- (mvp) External reviewer configured and verified (AGENTS.md created)
+- (mvp) Review standards document matches project coding conventions
+- (deep) Await script handles all exit conditions (approved, findings, cap, skip, timeout)
+- (mvp) CLAUDE.md workflow documents the agent-driven loop
+- (mvp) No GitHub Actions workflows created (zero Actions minutes)
+- (mvp) No ANTHROPIC_API_KEY secret required
+- (mvp) Post-PR-creation hook configured in settings to remind agents to run review-pr
+- (deep) Legacy GitHub Actions workflows detected and cleanup offered
 - (deep) Dual-model review enabled when both CLIs available
 
 ## Methodology Scaling
@@ -46,9 +47,12 @@ entire review-fix loop locally.
   review-standards.md, AGENTS.md, and comprehensive CLAUDE.md workflow.
   Falls back to external bot review if no CLIs available.
 - **mvp**: Step is disabled. Local self-review from git-workflow suffices.
-- **custom:depth(1-5)**: Depth 1-2: disabled. Depth 3: basic review-standards.md
-  + single-CLI review. Depth 4: add dual-model review. Depth 5: full suite
-  with all options and legacy cleanup.
+- **custom:depth(1-5)**:
+  - Depth 1: disabled — local self-review from git-workflow suffices.
+  - Depth 2: disabled — same as depth 1.
+  - Depth 3: basic review-standards.md + single-CLI review (whichever CLI is available).
+  - Depth 4: add dual-model review when both CLIs available, AGENTS.md with project-specific rules.
+  - Depth 5: full suite with dual-model review, legacy Actions cleanup, and comprehensive CLAUDE.md workflow integration.
 
 ## Conditional Evaluation
 Enable when: project uses GitHub for version control, team size > 1 or CI/CD is
@@ -74,3 +78,66 @@ Check if AGENTS.md exists first. If it exists, check for scaffold tracking comme
 - **Conflict resolution**: if review criteria changed in coding-standards.md,
   update AGENTS.md review rules to match; if both CLI reviewers are now
   available, offer to enable dual-model review
+
+## Instructions
+
+### Configure Review Enforcement Hook
+
+Add a Claude Code hook to the project's `.claude/settings.json` that fires after
+every `gh pr create` command. This injects a mandatory reminder into the agent's
+context at exactly the moment it needs to run reviews — preventing context decay
+from causing missed review channels.
+
+Add this to `.claude/settings.json`:
+
+```json
+{
+  "hooks": {
+    "PostToolUse": [
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "if echo \"$CC_BASH_COMMAND\" | grep -q 'gh pr create'; then echo '\\n⚠️  MANDATORY: Run all 3 code review channels before proceeding to the next task:\\n\\n  1. Codex CLI:\\n     Auth: codex login status 2>/dev/null\\n     Run:  codex exec --skip-git-repo-check -s read-only --ephemeral \"REVIEW_PROMPT\" 2>/dev/null\\n\\n  2. Gemini CLI:\\n     Auth: NO_BROWSER=true gemini -p \"respond with ok\" -o json 2>&1\\n     Run:  NO_BROWSER=true gemini -p \"REVIEW_PROMPT\" --output-format json --approval-mode yolo 2>/dev/null\\n\\n  3. Superpowers code-reviewer:\\n     Dispatch superpowers:code-reviewer subagent with BASE_SHA and HEAD_SHA\\n\\nIf auth fails: tell user to run ! codex login or ! gemini -p \"hello\"\\nFix all P0/P1/P2 findings before moving on. Do NOT skip any channel.\\nFull instructions: scaffold run review-pr'; fi"
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+**Why a hook instead of just instructions?** Agents in long implementation sessions
+suffer from context decay — instructions from hundreds of messages ago are
+effectively invisible by the time the agent creates its third PR. The hook injects
+the reminder at exactly the right moment, every time, regardless of context length.
+
+**Why inline commands instead of just a slash command reference?** The hook must work
+regardless of how scaffold is installed (plugin vs CLI vs user commands). Including
+the actual CLI invocations ensures the agent can execute reviews even if the
+`/scaffold:review-pr` slash command isn't available in the current namespace.
+
+### Add Review Workflow to CLAUDE.md
+
+Add the following to the project's CLAUDE.md in the Code Review section:
+
+```markdown
+## Code Review
+
+After creating a PR, run `/scaffold:review-pr <PR#>` to execute all three review
+channels (Codex CLI, Gemini CLI, Superpowers code-reviewer). Fix P0/P1/P2 findings
+before moving to the next task. A post-hook on `gh pr create` will remind you.
+
+| Command | Purpose |
+|---------|---------|
+| `/scaffold:review-pr <PR#>` | Run all 3 review channels on a PR |
+| `scripts/cli-pr-review.sh <PR#>` | Run dual-model CLI review only |
+```
+
+### Configure AGENTS.md, Review Standards, and CLI Scripts
+
+Follow the existing instructions for creating AGENTS.md, docs/review-standards.md,
+and review scripts based on the project's coding standards and test requirements.
+These provide the review context that `/scaffold:review-pr` uses when dispatching
+to each channel.

package/pipeline/environment/design-system.md

@@ -5,7 +5,7 @@ summary: "Creates a visual language — color palette (WCAG-compliant), typograp
 phase: "environment"
 order: 320
 dependencies: [dev-env-setup]
-outputs: [docs/design-system.md]
+outputs: [docs/design-system.md, tailwind.config.js, docs/coding-standards.md]
 reads: [create-prd]
 conditional: "if-needed"
 knowledge-base: [design-system-tokens]
@@ -35,12 +35,12 @@ professional UI without requiring design expertise from the user.
 ## Quality Criteria
 - (mvp) All colors meet WCAG AA contrast requirements
 - (mvp) Typography scale uses a consistent modular ratio; body text >= 16px; line height >= 1.5 for body text
-- (mvp) Spacing uses a consistent base unit (e.g., 4px increments)
+- (mvp) Spacing uses a consistent system with a defined base unit (e.g., 4px for custom systems, Tailwind spacing scale, or Material Design grid)
 - (deep) Component patterns cover buttons, forms, cards, feedback, navigation, data display
 - (mvp) Theme configuration files actually work (verified by running dev server)
 - (deep) Both light and dark mode token values provided (if dark mode requested)
 - (deep) Responsive breakpoints defined (mobile, tablet, desktop)
-- No arbitrary hex values or pixel values in component examples (all use tokens)
+- (mvp) No arbitrary hex values or pixel values in component examples (all use tokens)
 
 ## Methodology Scaling
 - **deep**: Full design system with all component categories, dark mode support,
@@ -48,9 +48,12 @@ professional UI without requiring design expertise from the user.
   page demonstrating all patterns. 15-20 pages.
 - **mvp**: Color palette, typography, spacing scale, and button/form/card patterns.
   No dark mode. Basic theme config. 3-5 pages.
-- **custom:depth(1-5)**: Depth 1-2: colors + typography + buttons. Depth 3: add
-  forms, cards, spacing. Depth 4: add navigation, data display, layout. Depth 5:
-  full suite with dark mode and accessibility.
+- **custom:depth(1-5)**:
+  - Depth 1: color palette and typography scale only.
+  - Depth 2: colors, typography, and button patterns.
+  - Depth 3: add forms, cards, and spacing scale.
+  - Depth 4: add navigation, data display, layout system, and responsive breakpoints.
+  - Depth 5: full suite with dark mode, accessibility audit, and animation guidelines.
 
 ## Conditional Evaluation
 Enable when: tech-stack.md includes a frontend framework (React, Vue, Angular, Svelte,

package/pipeline/environment/dev-env-setup.md

@@ -35,9 +35,9 @@ by the entire workflow.
 - (mvp) Dev server starts with a single command and supports live/hot reloading
 - (deep) Local database setup is scripted (if applicable)
 - (deep) .env.example documents all variables with comments
-- Key Commands table in CLAUDE.md matches actual Makefile/package.json commands
+- (mvp) Key Commands table in CLAUDE.md matches actual Makefile/package.json commands
 - (mvp) Lint and test commands exist and are runnable
-- Verification checklist passes (install, dev server, browser, live reload, tests, db)
+- (deep) Verification checklist passes (install, dev server, browser, live reload, tests, db)
 - (mvp) Setup process works for first-time clone (max 5 steps)
 - (mvp) Makefile/package.json includes at minimum: dev, test, lint targets
 
@@ -47,9 +47,12 @@ by the entire workflow.
   troubleshooting section. Complete Key Commands table.
 - **mvp**: Dev server with live reload, basic lint and test commands, .env.example.
   Minimal docs. Key Commands table with essentials only.
-- **custom:depth(1-5)**: Depth 1-2: dev server + test command. Depth 3: add
-  database and env vars. Depth 4: add troubleshooting. Depth 5: full docs with
-  multi-platform support.
+- **custom:depth(1-5)**:
+  - Depth 1: dev server with live reload and a single test command.
+  - Depth 2: dev server, test command, and basic lint command.
+  - Depth 3: add database setup, .env.example, and environment variable management.
+  - Depth 4: add troubleshooting section and watch mode tests.
+  - Depth 5: full docs with multi-platform support (Mac, Linux, WSL), Docker Compose, and seed data strategy.
 
 ## Mode Detection
 Update mode if docs/dev-setup.md exists. In update mode: preserve port assignments,

package/pipeline/environment/git-workflow.md

@@ -5,7 +5,7 @@ summary: "Sets up your branching strategy, commit message format, PR workflow, C
 phase: "environment"
 order: 330
 dependencies: [dev-env-setup]
-outputs: [docs/git-workflow.md]
+outputs: [docs/git-workflow.md, scripts/setup-agent-worktree.sh, .github/workflows/ci.yml, .github/pull_request_template.md]
 conditional: null
 knowledge-base: [dev-environment, git-workflow-patterns]
 ---
@@ -33,16 +33,16 @@ parallel agents, CI pipeline, branch protection, and conflict prevention rules.
   Worktree Awareness, and Code Review sections
 
 ## Quality Criteria
-- Branch naming format is consistent (Beads: bd-<task-id>/<desc>. Non-Beads: <type>/<desc>)
-- Commit format is consistent (Beads: [BD-<id>] type(scope): desc. Non-Beads: type(scope): desc)
-- PR workflow includes all 8 sub-steps (commit, AI review, rebase, push, create,
+- (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)
+- (deep) PR workflow includes all 8 sub-steps (commit, AI review, rebase, push, create,
   auto-merge with --delete-branch, watch CI, confirm merge)
-- Worktree script creates permanent worktrees with workspace branches
-- If Beads: BD_ACTOR environment variable documented for agent identity
-- CI workflow job name matches branch protection context
-- Branch cleanup documented for both single-agent and worktree-agent variants
-- Agent crash recovery procedure documented
-- Conflict prevention rule: don't parallelize tasks touching same files
+- (deep) Worktree script creates permanent worktrees with workspace branches
+- (deep) If Beads: BD_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
+- (mvp) Conflict prevention rule: don't parallelize tasks touching same files
 - (mvp) CI workflow YAML is valid and references commands from Key Commands table
 
 ## Methodology Scaling
@@ -51,9 +51,12 @@ parallel agents, CI pipeline, branch protection, and conflict prevention rules.
   cleanup, and comprehensive CLAUDE.md updates.
 - **mvp**: Branching strategy, commit format, basic PR workflow, CI config.
   Skip worktree script and crash recovery. Minimal CLAUDE.md updates.
-- **custom:depth(1-5)**: Depth 1-2: branching + commits + CI. Depth 3: add PR
-  workflow and branch protection. Depth 4: add worktrees and crash recovery.
-  Depth 5: full suite with all sections.
+- **custom:depth(1-5)**:
+  - Depth 1: branching strategy, commit format, and CI config.
+  - Depth 2: add basic PR workflow and PR template.
+  - Depth 3: add branch protection rules and full 8-step PR workflow.
+  - Depth 4: add worktree script, agent crash recovery, and conflict prevention rules.
+  - Depth 5: full suite with batch branch cleanup, multi-agent coordination, and comprehensive CLAUDE.md updates.
 
 ## Mode Detection
 Update mode if docs/git-workflow.md exists. In update mode: never rename CI jobs

package/pipeline/finalization/apply-fixes-and-freeze.md

@@ -26,16 +26,21 @@ issue is discovered during implementation.
 - Freeze marker added to each document (tracking comment)
 
 ## Quality Criteria
-- (mvp) All P0 and P1 validation findings addressed
-- (deep) P2 findings addressed or explicitly deferred with rationale
-- Fix log documents what changed and why
+- (mvp) All P0 and P1 validation findings resolved: fixed in source document or explicitly deferred with documented rationale
+- (deep) P2 findings fixed in source document or explicitly deferred with documented rationale
+- (mvp) Fix log documents what changed and why
 - (deep) Cross-phase-consistency validation re-run after fixes yields no new P0 or P1 findings
-- Every frozen document contains a tracking comment matching `<!-- scaffold:step-name vN YYYY-MM-DD -->`
+- (mvp) Every frozen document contains a tracking comment matching `<!-- scaffold:step-name vN YYYY-MM-DD -->`
 
 ## Methodology Scaling
 - **deep**: All findings addressed. Full fix log. Final consistency check.
 - **mvp**: P0 findings only. Brief fix log.
-- **custom:depth(1-5)**: Depth 1-2: address P0 findings only with brief fix log. Depth 3: address P0-P1 findings with detailed fix log and deferred rationale. Depth 4: address P0-P2 with full deferred rationale and re-validation passes. Depth 5: all findings addressed, final consistency re-check, and freeze verification audit.
+- **custom:depth(1-5)**:
+  - Depth 1: address P0 findings only with minimal fix log.
+  - Depth 2: address P0 findings with brief fix log and freeze markers on updated documents.
+  - Depth 3: address P0-P1 findings with detailed fix log and deferred rationale.
+  - Depth 4: address P0-P2 with full deferred rationale and re-validation passes.
+  - Depth 5: all findings addressed, final consistency re-check, and freeze verification audit.
 
 ## Mode Detection
 Check if `docs/validation/fix-log.md` already exists.

package/pipeline/finalization/developer-onboarding-guide.md

@@ -25,9 +25,11 @@ before their first task.
 
 ## Quality Criteria
 - (mvp) Contains sections for: project purpose, architecture overview (with component diagram reference), top 3 coding patterns with examples, and a file/doc lookup table
-- (mvp) Guide includes clone instructions, dependency install command, dev server start command, and test run command; every ADR referenced by number with one-sentence summary
+- (mvp) Guide includes: clone instructions, dependency install command, dev server start command, and test run command
+- (deep) Every ADR referenced by number with one-sentence summary
 - (deep) Key architectural decisions are summarized (with pointers to ADRs)
-- (mvp) Development workflow is clear (branch, code, test, PR)
+- (mvp) Development workflow section documents: branch creation command, commit message format, test command, and PR creation command
+- (mvp) Guide explicitly states relationship to implementation-playbook: what the guide covers vs what the playbook covers
 
 ## Methodology Scaling
 - **deep**: Comprehensive guide. Architecture walkthrough, key pattern explanations,
@@ -35,7 +37,12 @@ before their first task.
 - **mvp**: Quick-start guide with: clone command, dependency install, dev server
   start, test run command. Skip architecture overview, key patterns, and
   troubleshooting sections.
-- **custom:depth(1-5)**: Depth 1-2: quick start with setup and test commands only. Depth 3: add architecture overview, key patterns, and common tasks. Depth 4: add troubleshooting section, entry points documentation, and development workflow detail. Depth 5: full guide with architecture walkthrough, decision rationale, and team-specific onboarding paths.
+- **custom:depth(1-5)**:
+  - Depth 1: clone command and dependency install only.
+  - Depth 2: quick start with setup, dev server start, and test run commands.
+  - Depth 3: add architecture overview, key patterns, and common tasks.
+  - Depth 4: add troubleshooting section, entry points documentation, and development workflow detail.
+  - Depth 5: full guide with architecture walkthrough, decision rationale, and team-specific onboarding paths.
 
 ## Mode Detection
 Check if `docs/onboarding-guide.md` already exists.

package/pipeline/finalization/implementation-playbook.md

@@ -6,7 +6,7 @@ phase: "finalization"
 order: 1430
 dependencies: [developer-onboarding-guide]
 outputs: [docs/implementation-playbook.md]
-reads: [story-tests, create-evals, implementation-plan, database-schema, api-contracts, ux-spec, design-system, system-architecture, tdd, coding-standards, security, operations]
+reads: [story-tests, create-evals, implementation-plan, database-schema, api-contracts, ux-spec, design-system, system-architecture, tdd, coding-standards, security, operations, domain-modeling, adrs, create-prd, project-structure]
 conditional: null
 knowledge-base: [implementation-playbook]
 ---
@@ -19,7 +19,7 @@ format between agents, and success criteria.
 
 ## Inputs
 - docs/implementation-plan.md (required) — tasks to sequence
-- docs/system-architecture.md (required) — architecture context
+- docs/system-architecture.md (required at deep; optional — not available in MVP) — architecture context
 - docs/tdd-standards.md (required) — testing requirements
 - tests/acceptance/ (required if exists) — test skeletons agents implement during TDD
 - docs/story-tests-map.md (required if exists) — story-to-test mapping for progress tracking
@@ -34,6 +34,8 @@ format between agents, and success criteria.
 - docs/security-review.md (optional) — for security control task context
 - docs/operations-runbook.md (optional) — for deployment task context
 - docs/onboarding-guide.md (optional — not available in MVP) — agents should read for project context before playbook
+- docs/vision.md (optional) — strategic direction and product vision
+- docs/tech-stack.md (required) — technology choices that determine quality gate commands and build tooling
 - All other frozen artifacts
 
 ## Expected Outputs
@@ -47,7 +49,9 @@ format between agents, and success criteria.
 - (mvp) Success criteria per task (how to know it's done)
 - (deep) Handoff format between agents (what to communicate when passing work)
 - (mvp) Quality gates are defined (what must pass before a task is complete)
-- Quality gates include `make eval` (or equivalent) as a required check
+- (deep) Test skeleton discovery: playbook instructs agents to check docs/story-tests-map.md before writing new tests
+- (mvp) Dependency-failure recovery: playbook documents what to do when a task's upstream dependency is blocked
+- (deep) Quality gates include `make eval` (or equivalent) as a required check when eval tests exist
 - (deep) Agent workflow references test skeleton implementation from tests/acceptance/
 - (deep) Handoff format includes at minimum: implementation summary, assumptions made, known limitations, gotchas, and files modified
 
@@ -59,7 +63,12 @@ format between agents, and success criteria.
   reference, commit format, and quality gate commands from CLAUDE.md. Skip
   per-task context blocks, wave assignments, and inter-agent handoff format.
   Reference docs/coding-standards.md and docs/tdd-standards.md directly.
-- **custom:depth(1-5)**: Depth 1-2: task execution order, basic coding conventions reference, commit format, and quality gate commands. Depth 3: add per-task context requirements, wave assignments, and quality gates per wave. Depth 4: add inter-agent communication protocol, handoff format, and error recovery procedures. Depth 5: full playbook with rollback procedures, eval integration, and per-task minimum context blocks.
+- **custom:depth(1-5)**:
+  - Depth 1: task execution order and commit format only.
+  - Depth 2: add basic coding conventions reference and quality gate commands.
+  - Depth 3: add per-task context requirements, wave assignments, and quality gates per wave.
+  - Depth 4: add inter-agent communication protocol, handoff format, and error recovery procedures.
+  - Depth 5: full playbook with rollback procedures, eval integration, and per-task minimum context blocks.
 
 ## Mode Detection
 Check if `docs/implementation-playbook.md` already exists.

package/pipeline/foundation/beads.md

@@ -33,8 +33,8 @@ and autonomous behavior guidelines.
 - (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
-- CLAUDE.md contains commit-message convention requiring Beads task IDs
-- Bootstrap commit uses `[BD-0]` convention
+- (mvp) CLAUDE.md contains commit-message convention requiring Beads task IDs
+- (mvp) Bootstrap commit uses `[BD-0]` convention
 - (deep) Cross-doc consistency verified against git-workflow.md and coding-standards.md
 
 ## Methodology Scaling
@@ -43,9 +43,12 @@ and autonomous behavior guidelines.
   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.
-- **custom:depth(1-5)**: Depth 1-2: MVP Beads init + minimal CLAUDE.md. Depth 3:
-  add full command table and priority docs. Depth 4-5: full setup with cross-doc
-  consistency and detailed autonomous behavior rules.
+- **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.
 
 ## Conditional Evaluation
 Enable when: project uses Beads task tracking methodology (user selects Beads during

package/pipeline/foundation/coding-standards.md

@@ -31,14 +31,14 @@ self-review checklist.
   alongside the standards doc
 
 ## Quality Criteria
-- Every standard references the specific tech stack, not generic principles
-- Includes runnable code examples showing the RIGHT way for the stack
-- Commit message format is [BD-<id>] type(scope): description
-- AI-specific coding rules section addresses common AI mistakes (dead code,
+- (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) AI-specific coding rules section addresses common AI mistakes (dead code,
   duplication, magic numbers, premature abstraction, unnecessary features)
-- Linter/formatter configs created and referenced from the document
-- Every standard has a corresponding linter rule, code review checklist item, or test pattern that enforces it
-- Every code review checklist item is a binary yes/no question
+- (mvp) Linter/formatter configs created and referenced from the document
+- (mvp) Every standard has a corresponding linter rule, formatter rule, code review checklist item, or test pattern that enforces it (where applicable tools exist)
+- (deep) Every code review checklist item is a binary yes/no question
 - (mvp) Linter/formatter config files are valid (lint command runs without config errors)
 
 ## Methodology Scaling
@@ -47,9 +47,12 @@ self-review checklist.
   linter/formatter configuration with custom rules. 15-20 pages.
 - **mvp**: Core naming conventions, commit format, import ordering, error handling
   approach, and AI-specific rules. Basic linter config. 3-5 pages.
-- **custom:depth(1-5)**: Depth 1-2: MVP conventions. Depth 3: add security and
-  database patterns. Depth 4: add API design and logging. Depth 5: full suite
-  with all sections and custom linter rules.
+- **custom:depth(1-5)**:
+  - Depth 1: Core naming conventions, commit format, and import ordering. 1-2 pages.
+  - Depth 2: Depth 1 + error handling approach and AI-specific rules. Basic linter config. 3-5 pages.
+  - Depth 3: Add security and database access patterns. 5-8 pages.
+  - Depth 4: Add API design and logging conventions. 8-12 pages.
+  - Depth 5: Full suite with all sections, custom linter rules, and code review checklist. 15-20 pages.
 
 ## Mode Detection
 Update mode if docs/coding-standards.md exists. In update mode: preserve naming

package/pipeline/foundation/project-structure.md

@@ -33,17 +33,17 @@ with a Quick Reference section for file placement.
 - CLAUDE.md updated with Project Structure Quick Reference section
 
 ## Quality Criteria
-- Module organization strategy chosen and justified (feature-based, layer-based, or hybrid)
-- File placement table covers all file types (routes, services, models, types, utils, tests)
-- High-contention files identified with merge-conflict mitigation strategies
-- Shared utilities rule enforced (2+ features before promoting to shared)
-- Import conventions defined with ordering rules
-- Test file location aligns with tdd-standards.md (if it exists)
-- .gitignore covers all generated files for the tech stack
-- Structure follows the chosen framework's conventions
-- CLAUDE.md contains Project Structure Quick Reference section with file placement table
+- (mvp) Module organization strategy chosen and justified (feature-based, layer-based, or hybrid)
+- (mvp) File placement table covers all file types (routes, services, models, types, utils, tests)
+- (deep) High-contention files identified with merge-conflict mitigation strategies
+- (mvp) Shared utilities rule enforced (2+ features before promoting to shared)
+- (mvp) Import conventions defined with ordering rules
+- (mvp) Test file location aligns with tdd-standards.md (if it exists)
+- (mvp) .gitignore covers all generated files for the tech stack
+- (mvp) Structure follows the chosen framework's conventions
+- (mvp) CLAUDE.md contains Project Structure Quick Reference section with file placement table
 - (mvp) All documented directories exist on disk with .gitkeep placeholder files
-- CLAUDE.md Project Structure Quick Reference matches the directory tree in docs/project-structure.md
+- (mvp) CLAUDE.md Project Structure Quick Reference matches the directory tree in docs/project-structure.md
 
 ## Methodology Scaling
 - **deep**: Comprehensive structure with high-contention analysis, shared code
@@ -51,9 +51,12 @@ with a Quick Reference section for file placement.
   screenshots, and generated vs. committed file inventory.
 - **mvp**: Directory tree with annotations, basic file placement table, .gitignore.
   Skip shared code strategy and high-contention analysis.
-- **custom:depth(1-5)**: Depth 1-2: tree + placement table. Depth 3: add shared
-  code rules. Depth 4: add contention analysis. Depth 5: full suite with barrel
-  policy and import aliases.
+- **custom:depth(1-5)**:
+  - Depth 1: Directory tree with purpose annotations and .gitignore. Minimal.
+  - Depth 2: Depth 1 + file placement table covering all file types.
+  - Depth 3: Add shared code strategy (2+ features before promoting to shared).
+  - Depth 4: Add high-contention file analysis with merge-conflict mitigation strategies.
+  - Depth 5: Full suite with barrel file policy, import path aliases, and generated vs. committed file inventory.
 
 ## Mode Detection
 Update mode if docs/project-structure.md exists. In update mode: never delete

package/pipeline/foundation/tdd.md

@@ -30,10 +30,10 @@ actual test framework and assertion library.
 - docs/tdd-standards.md — testing approach with coverage goals and patterns
 
 ## Quality Criteria
-- (mvp) Test pyramid defined with coverage targets per layer
+- (mvp) Test pyramid (or equivalent testing model for non-layered architectures) defined with coverage targets per layer (defined per layer, e.g., 80% unit, 50% integration)
 - (mvp) Testing patterns specified for each layer (unit, integration, e2e)
-- (mvp) Quality gates defined (what must pass before merge)
-- Edge cases from domain invariants are test scenarios
+- (mvp) Quality gates defined: list of commands to run before merge, with expected pass criteria for each
+- (mvp) Edge cases from domain invariants are test scenarios
 - (deep) Performance testing approach for critical paths
 - (deep) Contract testing strategy documented for service boundaries
 
@@ -42,7 +42,12 @@ actual test framework and assertion library.
   test patterns per architecture pattern. Performance benchmarks. CI integration.
   Test data strategy. Mutation testing approach.
 - **mvp**: Test pyramid overview. Key testing patterns. What must pass before deploy.
-- **custom:depth(1-5)**: Depth 1-2: test pyramid overview with key patterns and example test for each layer. Depth 3: add per-layer test patterns, coverage targets, CI integration, and test data strategy. Depth 4: add performance benchmarks, mutation testing approach, and cross-module integration patterns. Depth 5: full suite with contract testing, visual regression strategy, and automated quality gate calibration.
+- **custom:depth(1-5)**:
+  - Depth 1: Test pyramid overview with key patterns. What must pass before deploy.
+  - Depth 2: Depth 1 + example test for each layer using the project's actual test framework.
+  - Depth 3: Add per-layer test patterns, coverage targets, CI integration, and test data strategy.
+  - Depth 4: Add performance benchmarks, mutation testing approach, and cross-module integration patterns.
+  - Depth 5: Full suite with contract testing, visual regression strategy, and automated quality gate calibration.
 
 ## Mode Detection
 Check for docs/tdd-standards.md. If it exists, operate in update mode: read