@zigrivers/scaffold 2.28.1 → 2.38.1

package/knowledge/validation/dependency-validation.md

@@ -8,6 +8,18 @@ topics: [validation, dependencies, graphs, cycles, ordering, parallelization]
 
 Dependency validation extracts all dependency relationships between implementation tasks, builds a graph, checks for correctness, and verifies that the ordering matches architectural constraints. A valid dependency graph ensures that tasks can be executed in an order that never requires unbuilt dependencies.
 
+## Summary
+
+- Extract dependencies from task declarations, architecture data flows, schema foreign keys, API contract prerequisites, and implicit shared resources.
+- **Cycle detection**: Use Kahn's algorithm to find tasks that can never start; resolve by splitting tasks into "define interface" and "implement interface."
+- **Completeness check**: Every referenced task ID must exist in the task list; orphaned dependencies indicate renames, removals, or typos.
+- **Ordering validation**: Dependencies should follow architectural layer ordering (infrastructure -> schema -> domain -> service -> API -> frontend -> tests).
+- **Parallel independence**: Tasks with no dependency path between them must not share mutable files, tables, or configuration.
+- **Critical path analysis**: Identify the longest sequential chain to determine minimum project duration and focus optimization efforts.
+- **Fan-in/fan-out analysis**: High fan-in tasks are blockers (prioritize and split); high fan-out tasks start late (review whether all dependencies are necessary).
+
+## Deep Guidance
+
 ## What a Dependency Graph Represents
 
 Each node in the graph is an implementation task. Each directed edge represents a "must complete before" relationship: if task A depends on task B, then B must be completed before A can start.

package/knowledge/validation/scope-management.md

@@ -8,6 +8,18 @@ topics: [validation, scope, creep, prd-alignment, gold-plating]
 
 Scope management validation compares every specification artifact against the PRD to ensure that the documented system matches what was actually requested. Features that cannot be traced to a PRD requirement are scope creep. Requirements that grew during documentation are scope inflation. Extra polish on non-critical features is gold-plating. This validation catches all three.
 
+## Summary
+
+- **Feature-to-PRD tracing**: Classify every capability as traced (maps to PRD), supporting (necessary infrastructure), or creep (no PRD justification).
+- **Scope inflation detection**: Compare each PRD requirement's original scope to its implementation scope; flag features that grew beyond what was requested.
+- **Gold-plating detection**: Over-abstraction, premature optimization, excessive error handling, and UI polish beyond requirements. Test: "If removed, would any PRD requirement be unmet?"
+- **Deferred scope leakage**: Verify explicitly deferred items (v2 features) do not appear in specifications, including partial infrastructure for deferred features.
+- **NFR scope alignment**: Implementation targets should match PRD targets, not exceed them (e.g., 99.9% uptime, not 99.99%).
+- **Decision framework**: When in doubt, defer. Scope additions are kept only if required for a PRD feature to work and do not significantly increase effort or operational complexity.
+- Run scope validation after all documentation phases and before implementation begins.
+
+## Deep Guidance
+
 ## Why Scope Grows
 
 Scope grows during the documentation pipeline for understandable reasons — but each growth increases implementation effort, risk, and timeline. Common causes:

package/knowledge/validation/traceability.md

@@ -8,6 +8,18 @@ topics: [validation, traceability, requirements, coverage]
 
 Traceability validation ensures that every requirement flows from its origin in the PRD through domain modeling, architecture decisions, system design, and into implementable tasks. A complete traceability matrix is the strongest evidence that nothing has been lost or invented during the documentation pipeline.
 
+## Summary
+
+- **Traceability matrix**: A table where each row is a requirement and columns are pipeline artifacts (domain, ADR, architecture, schema, API, UX, tasks, tests). Empty cells are gaps.
+- **Build process**: Extract all PRD requirements (functional, NFR, constraints, deferred), then trace each forward through every downstream artifact.
+- **Gap detection**: Empty cells (not N/A), orphaned artifacts tracing to no requirement, thin traces, and deferred items appearing downstream.
+- **Bidirectional tracing**: Forward (requirement -> implementation) catches gaps; backward (implementation -> requirement) catches scope creep.
+- **NFR tracing**: Performance, security, and accessibility requirements cut across components and need special tracing through architecture, schema, API, testing, and UX.
+- **Common issues**: Orphan features, assumed infrastructure, tested-but-not-specified behaviors, specified-but-not-tested requirements, and split requirements across unlinked tasks.
+- Use consistent identifiers (REQ-001, ADR-003, T-012) so traces are searchable across all artifacts.
+
+## Deep Guidance
+
 ## What a Traceability Matrix Is
 
 A traceability matrix is a table where each row represents a requirement and each column represents a pipeline artifact. A complete row means the requirement is fully traced from origin to implementation. A missing cell means a gap — either the requirement was not addressed at that phase, or it was addressed but the connection is not explicit.

package/methodology/README.md

@@ -0,0 +1,37 @@
+# Methodology Depth Levels
+
+The scaffold pipeline supports 5 depth levels that control the thoroughness of each step's output.
+
+| Depth | Name | Description |
+|-------|------|-------------|
+| 1 | Minimal | Bare minimum viable output. Just enough to start building. |
+| 2 | Light | Slightly more detail than minimal. Still focused on speed over completeness. |
+| 3 | Balanced | Recommended for most projects. Good coverage without excessive documentation. |
+| 4 | Thorough | Comprehensive output with external model validation (Codex/Gemini) when available. |
+| 5 | Exhaustive | Maximum detail with multi-model reconciliation. Best for critical or regulated projects. |
+
+## Presets
+
+| Preset | Default Depth | Philosophy |
+|--------|---------------|------------|
+| `mvp.yml` | 1 | Ship fast. Only essential steps enabled. No review cycles beyond PRD/stories. |
+| `custom-defaults.yml` | 3 | Balanced. Most steps enabled. Innovation and automated review disabled by default. |
+| `deep.yml` | 5 | Maximum quality. All steps enabled. External model dispatch at depth 4+. |
+
+## How Depth Affects Steps
+
+Each pipeline step defines a `## Methodology Scaling` section with behavior at each depth:
+- **mvp** bullet: What the step produces at depth 1-2
+- **deep** bullet: What the step produces at depth 4-5
+- **custom:depth(1-5)** bullet: Explicit per-level breakdown
+
+Depth 3 is typically the inflection point where steps add structure, cross-references, and validation beyond the basics.
+
+## Depth Tags in Quality Criteria
+
+Quality Criteria items may be tagged:
+- `(mvp)` — applies at all depths (depth 1+)
+- `(deep)` — applies only at depth 4+
+- `(depth N+)` — applies at depth N and above
+
+Untagged criteria apply at all depths by default.

package/methodology/custom-defaults.yml

@@ -3,8 +3,12 @@ name: Custom
 description: Choose which steps to include and how deep to go
 default_depth: 3
 
-# All steps enabled by default at depth 3 — user overrides individual steps
+# Most steps enabled by default at depth 3 — innovation and automated-pr-review disabled by default, user overrides individual steps
 steps:
+  # Phase 0 — Product Vision (vision)
+  create-vision: { enabled: true }
+  review-vision: { enabled: true }
+  innovate-vision: { enabled: false }
   # Phase 1 — Product Definition (pre)
   create-prd: { enabled: true }
   review-prd: { enabled: true }
@@ -70,3 +74,10 @@ steps:
   apply-fixes-and-freeze: { enabled: true }
   developer-onboarding-guide: { enabled: true }
   implementation-playbook: { enabled: true }
+  # Phase 15 — Build (build) — stateless, on-demand execution steps
+  single-agent-start: { enabled: true }
+  single-agent-resume: { enabled: true }
+  multi-agent-start: { enabled: true }
+  multi-agent-resume: { enabled: true }
+  quick-task: { enabled: true }
+  new-enhancement: { enabled: true }

package/methodology/deep.yml

@@ -4,6 +4,10 @@ description: Comprehensive documentation for complex systems — full analysis a
 default_depth: 5
 
 steps:
+  # Phase 0 — Product Vision (vision)
+  create-vision: { enabled: true }
+  review-vision: { enabled: true }
+  innovate-vision: { enabled: true, conditional: "if-needed" }
   # Phase 1 — Product Definition (pre)
   create-prd: { enabled: true }
   review-prd: { enabled: true }
@@ -69,3 +73,10 @@ steps:
   apply-fixes-and-freeze: { enabled: true }
   developer-onboarding-guide: { enabled: true }
   implementation-playbook: { enabled: true }
+  # Phase 15 — Build (build) — stateless, on-demand execution steps
+  single-agent-start: { enabled: true }
+  single-agent-resume: { enabled: true }
+  multi-agent-start: { enabled: true }
+  multi-agent-resume: { enabled: true }
+  quick-task: { enabled: true }
+  new-enhancement: { enabled: true }

package/methodology/mvp.yml

@@ -4,6 +4,10 @@ description: Get to code fast with minimal ceremony
 default_depth: 1
 
 steps:
+  # Phase 0 — Product Vision (vision)
+  create-vision: { enabled: true }
+  review-vision: { enabled: true }
+  innovate-vision: { enabled: false }
   # Phase 1 — Product Definition (pre)
   create-prd: { enabled: true }
   review-prd: { enabled: true }
@@ -69,3 +73,10 @@ steps:
   apply-fixes-and-freeze: { enabled: false }
   developer-onboarding-guide: { enabled: false }
   implementation-playbook: { enabled: true }
+  # Phase 15 — Build (build) — stateless, on-demand execution steps
+  single-agent-start: { enabled: true }
+  single-agent-resume: { enabled: true }
+  multi-agent-start: { enabled: true }
+  multi-agent-resume: { enabled: true }
+  quick-task: { enabled: true }
+  new-enhancement: { enabled: true }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zigrivers/scaffold",
-  "version": "2.28.1",
+  "version": "2.38.1",
   "description": "AI-powered software project scaffolding pipeline",
   "type": "module",
   "keywords": [
@@ -41,11 +41,11 @@
     "test": "vitest run",
     "test:coverage": "vitest run --coverage",
     "test:e2e": "vitest run --config vitest.e2e.config.ts",
-    "test:bench": "vitest bench",
+    "test:perf": "vitest run tests/performance/",
     "lint": "eslint src/ tests/",
     "type-check": "tsc --noEmit",
     "check": "npm run lint && npm run type-check && npm test",
-    "prepublish": "bash scripts/prepublish.sh"
+    "prepublishOnly": "bash scripts/prepublish.sh"
   },
   "dependencies": {
     "@inquirer/prompts": "^7.4.0",

package/pipeline/architecture/review-architecture.md

@@ -1,12 +1,14 @@
 ---
 name: review-architecture
 description: Review system architecture for completeness and downstream readiness
+summary: "Verifies every domain concept lands in a component, every decision constraint is respected, no components are orphaned from data flows, and the module structure minimizes merge conflicts."
 phase: "architecture"
 order: 720
 dependencies: [system-architecture]
 outputs: [docs/reviews/review-architecture.md, docs/reviews/architecture/review-summary.md, docs/reviews/architecture/codex-review.json, docs/reviews/architecture/gemini-review.json]
+reads: [domain-modeling]
 conditional: null
-knowledge-base: [review-methodology, review-system-architecture]
+knowledge-base: [review-methodology, review-system-architecture, multi-model-review-dispatch, review-step-template]
 ---
 
 ## Purpose
@@ -32,12 +34,14 @@ independent review validation.
 - docs/reviews/architecture/gemini-review.json (depth 4+, if available) — raw Gemini findings
 
 ## Quality Criteria
-- All architecture-specific review passes executed
-- Domain model coverage verified (every model maps to a component)
-- ADR constraint compliance verified
-- Data flow completeness verified (no orphaned components)
-- Module structure validated for practical concerns
-- Downstream readiness confirmed (specification, quality, and planning steps can proceed)
+- (mvp) Domain model coverage verified (every model maps to a component)
+- (mvp) ADR constraint compliance verified
+- (deep) All architecture-specific review passes executed
+- (deep) Data flow completeness verified (no orphaned components)
+- (deep) Module structure assessed for merge conflict risk, circular dependency risk, and import depth
+- (mvp) Downstream readiness confirmed (specification, quality, and planning steps can proceed)
+- (mvp) Every finding categorized P0-P3 with specific component, section, and issue
+- (mvp) Fix plan documented for all P0/P1 findings; fixes applied to system-architecture.md and re-validated
 - (depth 4+) Multi-model findings synthesized with consensus/disagreement analysis
 
 ## Methodology Scaling
@@ -54,3 +58,10 @@ independent review validation.
 ## Mode Detection
 Re-review mode if previous review exists. If multi-model review artifacts exist
 under docs/reviews/architecture/, preserve prior findings still valid.
+
+## Update Mode Specifics
+
+- **Detect**: `docs/reviews/review-architecture.md` exists with tracking comment
+- **Preserve**: Prior findings still valid, resolution decisions, multi-model review artifacts
+- **Triggers**: Upstream artifact changed since last review (compare tracking comment dates)
+- **Conflict resolution**: Previously resolved findings reappearing = regression; flag and re-evaluate

package/pipeline/architecture/system-architecture.md

@@ -1,19 +1,22 @@
 ---
 name: system-architecture
 description: Design and document system architecture
+summary: "Designs the system blueprint — which components exist, how data flows between them, where each module lives in the directory tree, and where extension points allow custom behavior."
 phase: "architecture"
 order: 710
 dependencies: [review-adrs]
 outputs: [docs/system-architecture.md]
-reads: [create-prd]
+reads: [create-prd, domain-modeling, adrs]
 conditional: null
-knowledge-base: [system-architecture]
+knowledge-base: [system-architecture, domain-modeling]
 ---
 
 ## Purpose
 Design and document the system architecture, translating domain models and ADR
 decisions into a concrete component structure, data flows, and module
-organization. Project directory structure and module organization are defined here.
+organization. Project directory structure and module organization are defined
+here. This is the blueprint that agents reference when deciding where code
+lives and how components communicate.
 
 ## Inputs
 - docs/domain-models/ (required) — domain models from modeling phase
@@ -25,11 +28,11 @@ organization. Project directory structure and module organization are defined he
   data flows, module structure, and extension points
 
 ## Quality Criteria
-- Every domain model lands in a component or module
-- Every ADR constraint is respected in the architecture
-- All components appear in at least one data flow diagram
-- Extension points are both documented and designed (not just listed)
-- Project directory structure is defined with file-level granularity
+- (mvp) Every domain model lands in a component or module
+- (mvp) Every ADR constraint is respected in the architecture
+- (mvp) All components appear in at least one data flow diagram
+- (deep) Each extension point has interface definition, example usage scenario, and constraints on what can/cannot be extended
+- (mvp) Project directory structure is defined with file-level granularity
 
 ## Methodology Scaling
 - **deep**: Full architecture document. Component diagrams, data flow diagrams,

package/pipeline/build/multi-agent-resume.md

@@ -0,0 +1,245 @@
+---
+name: multi-agent-resume
+description: Resume multi-agent work after a break
+summary: "Verifies the worktree, syncs with main, reconciles completed tasks, and resumes the agent's TDD loop from the previous session."
+phase: "build"
+order: 1540
+dependencies: [implementation-playbook]
+outputs: []
+conditional: null
+stateless: true
+category: pipeline
+knowledge-base: [tdd-execution-loop, task-claiming-strategy, worktree-management]
+reads: [coding-standards, tdd, git-workflow]
+argument-hint: "<agent-name>"
+---
+
+## Purpose
+Resume a named agent's implementation work in its worktree after a break.
+Recovers session context by verifying the worktree environment, syncing with
+main, reconciling task status and open PRs, then continuing the TDD execution
+loop from where the agent left off.
+
+## Inputs
+- $ARGUMENTS (required) — the agent name (e.g., "alpha", "beta", "agent-1")
+- CLAUDE.md (required) — project conventions, key commands, workflow
+- docs/implementation-playbook.md (required if exists) — primary task execution reference
+- docs/implementation-plan.md (fallback) — task list when no playbook exists
+- docs/onboarding-guide.md (optional) — project context for orientation
+- docs/coding-standards.md (required) — code conventions, naming, patterns
+- docs/tdd-standards.md (required) — test categories, mocking strategy
+- docs/project-structure.md (required) — where files live
+- tests/acceptance/ (optional) — TDD test skeletons
+- tests/evals/ (optional) — project eval checks for quality gates
+- tasks/lessons.md (optional) — previous lessons learned
+- .beads/ (conditional) — Beads task tracking if configured
+
+## Expected Outputs
+- Completed in-progress work from previous session
+- Continued task implementation with passing tests
+- Pull requests for each completed task
+- Updated task status in playbook/plan or Beads
+
+## Quality Criteria
+- (mvp) Worktree environment is verified before resuming
+- (mvp) In-progress work is identified and completed before starting new tasks
+- (mvp) Merged PRs are reconciled with task status
+- (mvp) Each task follows red-green-refactor TDD cycle
+- (deep) Full sync with origin/main before resuming
+- (deep) Beads actor identity is verified and task states are reconciled
+- (deep) Between-task cleanup ensures no state leakage
+
+## Methodology Scaling
+- **deep**: Full worktree verification, Beads actor check, rebase on latest
+  main, reconcile all open PRs, review onboarding guide, consult lessons.md,
+  eval gates, detailed PR descriptions, between-task cleanup.
+- **mvp**: Verify worktree, check branch state, finish in-progress work or
+  pick next task, TDD loop, make check, create PR.
+- **custom:depth(1-5)**: Depth 1-2: check branch and continue. Depth 3: add
+  PR reconciliation, lessons.md review, sync with origin. Depth 4: add
+  rebase, eval gates, between-task cleanup. Depth 5: full state audit with
+  actor verification and branch cleanup.
+
+## Mode Detection
+This is a stateless execution command. No document is created or updated.
+- Always operates in RESUME MODE.
+- If there is no prior work for this agent (no feature branches, no task
+  progress), redirect to `/scaffold:multi-agent-start $ARGUMENTS` instead.
+
+## Update Mode Specifics
+Not applicable — this is a stateless execution command that does not produce
+a persistent document.
+
+## Instructions
+
+You are **$ARGUMENTS**.
+
+### Worktree Verification
+
+Before doing anything else, confirm the environment:
+
+1. **Worktree confirmation**
+   - `git rev-parse --git-dir` — output should contain `/worktrees/` (confirms you are in a worktree)
+   - If NOT in a worktree, stop and instruct the user to set one up or navigate to the correct directory
+
+2. **Beads identity** (if `.beads/` exists)
+   - `echo $BD_ACTOR` — should show `$ARGUMENTS`
+   - If not set, the worktree setup may be incomplete
+
+### State Recovery
+
+Recover your context by checking the current state of work:
+
+1. **Read project context**
+   - Read `CLAUDE.md` for project conventions and key commands
+   - Read `docs/onboarding-guide.md` if it exists (refresh project context)
+   - Read `tasks/lessons.md` for relevant anti-patterns
+
+2. **Git state assessment**
+   - `git branch --show-current` — determine if you are on a feature branch (in-progress work) or a workspace branch
+   - `git status` — check for uncommitted changes or staged files
+   - `git stash list` — check for stashed work
+   - `git log --oneline -5` — review recent commits for context
+
+3. **PR reconciliation**
+   - `gh pr list --author="@me"` — check for open PRs from this agent
+   - For each open PR, check if it has been merged: `gh pr view <number> --json state`
+   - If a PR was merged while you were away, reconcile the task status (see below)
+
+4. **Sync with remote**
+   - `git fetch origin --prune` — get latest remote state and clean stale references
+
+### Beads Recovery
+
+**If Beads is configured** (`.beads/` exists):
+- `bd list --actor $ARGUMENTS` — check for tasks with `in_progress` status owned by this agent
+- If a PR shows as merged, close the corresponding task: `bd close <id> && bd sync`
+- If there is in-progress work, finish it (see "Resume In-Progress Work" below)
+- Otherwise, clean up and start fresh:
+  - `git fetch origin --prune && git clean -fd`
+  - Run the install command from CLAUDE.md Key Commands
+  - `bd ready` to find the next available task
+- Continue working until `bd ready` shows no available tasks
+
+**Without Beads:**
+- Read `docs/implementation-playbook.md` as the primary task reference.
+  Fall back to `docs/implementation-plan.md` when no playbook is present.
+- If a PR shows as merged, mark the corresponding task as complete in the plan/playbook
+- If there is in-progress work on your current branch, finish it
+- Otherwise, clean up and pick the next task:
+  - `git fetch origin --prune && git clean -fd`
+  - Run the install command from CLAUDE.md Key Commands
+  - Pick the next uncompleted task with no unfinished dependencies
+
+### Resume In-Progress Work
+
+If you are on a feature branch with changes:
+
+1. **Assess the state**
+   - `git diff --stat` — what files have been changed?
+   - `git log --oneline origin/main..HEAD` — what commits exist on this branch?
+   - Read the task description to understand what was being worked on
+
+2. **Rebase on latest main**
+   - `git fetch origin && git rebase origin/main`
+   - Resolve any conflicts, re-run tests
+
+3. **Check test state**
+   - Run the project's test suite
+   - If tests pass: you may be in the refactor phase or ready for PR
+   - If tests fail: determine if these are your in-progress test cases (red phase) or regressions
+
+4. **Continue the TDD loop**
+   - Pick up where the previous session left off
+   - Follow the same Red-Green-Refactor cycle as in `/scaffold:multi-agent-start`
+
+### Continue to Next Task
+
+Once in-progress work is complete (or if there was none):
+
+1. **Quality gates**
+   - Run `make check` (or equivalent from CLAUDE.md Key Commands)
+   - If `tests/evals/` exists, run `make eval` (or equivalent eval command)
+
+2. **Create PR** (if not already created for in-progress work)
+   - Push the branch: `git push -u origin HEAD`
+   - Create a pull request: `gh pr create`
+   - Include agent name in PR description for traceability
+
+3. **Between-task cleanup**
+   - `git fetch origin --prune && git clean -fd`
+   - Run the install command from CLAUDE.md Key Commands
+
+4. **Claim next task**
+   - Branch from remote: `git fetch origin && git checkout -b <branch-name> origin/main`
+   - Pick the next task following the same process as `/scaffold:multi-agent-start`
+   - Continue the TDD execution loop
+
+### Recovery Procedures
+
+**Worktree not found or corrupted:**
+- Check `git worktree list` from the main repo to see if the worktree exists
+- If missing: `scripts/setup-agent-worktree.sh $ARGUMENTS` to recreate
+- If corrupted: `git worktree remove <path>` then recreate
+
+**Uncommitted changes on a feature branch:**
+- Review the changes: `git diff`
+- If the changes look intentional, stage and continue implementation
+- If the changes look broken or experimental, stash them: `git stash`
+
+**Stale feature branch (main has diverged significantly):**
+- `git fetch origin && git rebase origin/main`
+- If conflicts are extensive, consider starting the task fresh from origin/main
+- Re-run full test suite after rebase
+
+**PR was rejected or has requested changes:**
+- `gh pr view <number>` — read the review comments
+- Address the feedback on the existing branch
+- Push updates and re-request review
+
+**Task was completed by another agent:**
+- If Beads: `bd sync` will show updated task states
+- Without Beads: check the plan/playbook for recently completed tasks and open PRs
+- Skip to the next available task
+
+**`git checkout main` fails:**
+- This is expected in a worktree. Use `git fetch origin && git checkout -b <branch> origin/main` instead.
+
+**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
+
+### Process Rules
+
+1. **Verify worktree first** — Never resume work without confirming the worktree environment.
+2. **Recover state before new work** — Check for in-progress tasks and merged PRs first.
+3. **Branch from remote, not local** — Always use `origin/main` as the branch point.
+4. **Clean between tasks** — Run cleanup after each task to prevent state leakage.
+5. **TDD is not optional** — Continue the red-green-refactor cycle for any in-progress work.
+6. **Quality gates before PR** — Never create a PR with failing checks.
+7. **Follow CLAUDE.md** — It is the authority on project conventions and commands.
+
+---
+
+## After This Step
+
+When this step is complete (all tasks done or session ending), tell the user:
+
+---
+**Agent $ARGUMENTS resume session complete.**
+
+**Session summary:**
+- Recovered state: [in-progress task or "clean start"]
+- Tasks completed this session: [list task IDs/titles]
+- PRs created: [list PR numbers]
+- Remaining tasks: [count or "none"]
+
+**If resuming again later:** Run `/scaffold:multi-agent-resume $ARGUMENTS` again.
+
+**If all tasks are done:**
+- Review `tasks/lessons.md` and add any patterns learned during implementation.
+- Consider running `/scaffold:version-bump` for a release.
+
+**Pipeline reference:** `/scaffold:prompt-pipeline`
+
+---