mustard-claude 3.1.6 → 3.1.8

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mustard-claude",
-  "version": "3.1.6",
+  "version": "3.1.8",
   "description": "Framework-agnostic CLI for Claude Code project setup",
   "type": "module",
   "bin": {

package/templates/CLAUDE.md

@@ -87,4 +87,4 @@ RTK (Rust Token Killer) is integrated as core infrastructure. A PreToolUse hook
 - If RTK is not installed, the hook silently passes through (zero impact)
 
 ## Full Reference
-Rules, pipeline, naming: `pipeline-config.md`
+Rules, pipeline, naming: `.claude/pipeline-config.md`

package/templates/commands/mustard/approve/SKILL.md

@@ -18,7 +18,7 @@ Approves the active spec and prepares the implementation phase. Does NOT execute
 1. **Step 0: AUTO-SYNC (MANDATORY)** — Run via Bash tool BEFORE any other action:
    - `node .claude/scripts/sync-registry.js`
    - Do NOT proceed to step 2 without running this command
-2. **Read** `pipeline-config.md` — agents, model selection
+2. **Read** `.claude/pipeline-config.md` — agents, model selection
 3. Locate active spec in `.claude/spec/active/`
 4. **Spec Checkpoint — update spec header:**
    - `### Status: approved`
@@ -29,7 +29,7 @@ Approves the active spec and prepares the implementation phase. Does NOT execute
    - Parse Tasks from spec to extract tasks per agent (DB, Backend, Frontend, etc.)
    - Create `.claude/.pipeline-states/` directory if it doesn't exist
    - Write state file with `specName`, `status: "approved"`, `phaseName: "PLAN"`, `tasks` with names and agents, `model`, `updatedAt`
-6. **Model selection** — read `Model Selection` from `pipeline-config.md` and record `"model"` field in state:
+6. **Model selection** — read `Model Selection` from `.claude/pipeline-config.md` and record `"model"` field in state:
    - Count total estimated files in spec
    - Apply rule: ≤5 files/known patterns → `"model": "sonnet"`, 5+ files/new patterns → `"model": "opus"`
 7. **Task Tracking — create TaskCreate for each agent:**

package/templates/commands/mustard/bugfix/SKILL.md

@@ -87,7 +87,7 @@ Rules:
 ### EXECUTE (fix + validate)
 
 Every agent prompt dispatched in Fast Path MUST include:
-`Return format cap: ≤50 lines. Apply compact Return Format from pipeline-config.md strictly.`
+`Return format cap: ≤50 lines. Apply compact Return Format from .claude/pipeline-config.md strictly.`
 
 Dispatch bugfix agent with:
 - Root cause from ANALYZE
@@ -110,7 +110,7 @@ After the bugfix agent returns, check for an escalation status before closing:
 - `PARTIAL` — agent fixed some but not all reported issues; resume from the last incomplete fix step (max 2 retries)
 - `DEFERRED` — agent intentionally left a related issue unfixed with justification; confirm with user before closing
 
-See `pipeline-config.md` Escalation Statuses for the full status table.
+See `.claude/pipeline-config.md` Escalation Statuses for the full status table.
 
 #### Retry Compact Advisory
 If an agent fails and requires >2 retry attempts during EXECUTE:

package/templates/commands/mustard/complete/SKILL.md

@@ -11,7 +11,7 @@ Finalizes the current pipeline, either completing or canceling.
 ## Verification Gate (MANDATORY)
 
 1. **Review completed**: Check pipeline state — review agent MUST have run and returned APPROVED. If not → dispatch review first (see resume.md step 19)
-2. **Build passes**: run build command for each affected subproject (from pipeline-config.md)
+2. **Build passes**: run build command for each affected subproject (from .claude/pipeline-config.md)
 3. **Changes match spec**: each `[x]` corresponds to a real file
 4. **Zero CRITICAL issues**: review report shows zero CRITICAL violations (SOLID, design system, patterns, i18n, integration)
 5. **No regressions**: existing features still work
@@ -32,6 +32,8 @@ node .claude/scripts/verify-pipeline.js "$PROJECT_DIR"
 
 If ANY gate fails: do NOT mark complete → report what failed + suggest fix. If review wasn't run → run it now before completing.
 
+Re-reviews always dispatch with `model: "sonnet"` (see `review/SKILL.md § Model Selection`).
+
 #### Surface Accumulated Concerns
 
 Before finalizing, scan the active spec for any `## Concerns` section written during EXECUTE:
@@ -41,7 +43,7 @@ Before finalizing, scan the active spec for any `## Concerns` section written du
 - If all concerns are `CONCERN` or `DEFERRED` (non-blocking): note them and proceed
 - This step is a read-only scan — do NOT alter or dismiss concerns during CLOSE
 
-See `pipeline-config.md` Escalation Statuses for concern classification rules.
+See `.claude/pipeline-config.md` Escalation Statuses for concern classification rules.
 
 ## Action
 
@@ -54,6 +56,7 @@ See `pipeline-config.md` Escalation Statuses for concern classification rules.
    - Mark all remaining `[ ]` as `[x]`
 4. **Entity Registry — update if needed:**
    - `node .claude/scripts/sync-registry.js`
+   - **Schema-aware refresh (conditional):** If the spec's `## Files` section touched any file matching `*.schema.ts`, `*.entity.ts`, `*.prisma`, `*DbContext*.cs`, or `schema.rs`, run `rtk node .claude/scripts/sync-registry.js` to refresh `entity-registry.json`. If sync-registry fails (non-zero exit or script missing), log a warning and continue with close — this step is non-blocking.
 5. **Move spec** from `.claude/spec/active/` to `.claude/spec/completed/`
 6. **Pipeline State — cleanup:**
    - Extract `spec-name` from the spec directory (e.g. `2026-02-26-linked-services-card`)

package/templates/commands/mustard/feature/SKILL.md

@@ -53,7 +53,7 @@ Prepend the following to EVERY subagent prompt dispatched during the pipeline:
 
 If the diff file is empty or missing, skip the Git State header entirely. Never dispatch an agent without attempting interpolation.
 
-1. Read `pipeline-config.md` — agents, wave transitions, model selection
+1. Read `.claude/pipeline-config.md` — agents, wave transitions, model selection
 2. Read `entity-registry.json` via Grep for the specific entity name (e.g. `"Contract":`) — NEVER read the full JSON. Entity found? infer layers. Not found? all layers.
 3. Determine layers from signals:
 
@@ -104,6 +104,12 @@ After ANALYZE completes, if the analysis required heavy exploration (>8 file rea
 - Suggest to user: _"Analysis complete. Context is heavy — consider `/compact` before we proceed to implementation, then `/resume`."_
 - This is advisory only — proceed immediately if user declines or ignores.
 
+### End of ANALYZE — Validation
+
+Run: `rtk node .claude/scripts/analyze-validation.js --spec .claude/spec/active/{specName}/spec.md`
+If output `ok: false`, append each `issues[]` entry to the spec under `## Concerns` (non-blocking).
+Continue to PLAN regardless.
+
 ### PLAN Phase
 
 #### Full Scope
@@ -161,18 +167,70 @@ Rules:
 - Be specific: prefer exact files over broad directories when the change is known
 - Out-of-boundary edits during EXECUTE will surface a `[BOUNDARY WARNING]` from guard-verify — treat as a signal to re-evaluate, not an error to suppress
 
+### Pre-EXECUTE Existence Gate (Full scope only)
+
+**Skip conditions**: Light scope OR `## Files` section lists more than 8 files (cost-benefit inverts — Haiku 10-tool-use cap will not cover).
+
+Before dispatching implementation agents, run 1 Haiku explorer to verify the work is still needed.
+
+**Pre-check (free, zero LLM tokens)**: Before dispatching Haiku, run:
+
+```bash
+rtk git diff --stat HEAD -- <files listed in `## Files` of spec>
+```
+
+Skip rules based on pre-check output:
+- **Empty output** (no changes) → skip gate entirely, proceed to EXECUTE normally (nothing to verify)
+- **<10 total insertions/deletions** → skip gate entirely, proceed to EXECUTE normally (trivial changes, verification not worth the overhead)
+- **≥10 insertions/deletions** → proceed with Haiku dispatch below
+
+**Dispatch:**
+
+```javascript
+Task({
+  subagent_type: "Explore",
+  model: "haiku",
+  description: "Pre-EXECUTE existence check",
+  prompt: `# EXISTENCE CHECK
+Read .claude/spec/active/{specName}/spec.md sections: "## Files" and "## Checklist".
+
+For EACH checklist task (task-level, NOT file-level):
+  1. Extract 1-3 concrete identifiers from the task text — function names, component names, file path fragments, string literals.
+     Example: task "Add LogoutButton component with handleLogout handler" → identifiers: ["LogoutButton", "handleLogout"].
+  2. Identify target files for the task from "## Files" (match by extension, name hint, or task context).
+  3. Grep each target file for the identifiers.
+  4. Verdict for this task:
+     - ALL target files contain a MAJORITY of identifiers → all_present=yes
+     - SOME do, SOME do not → all_present=partial
+     - NONE do → all_present=no
+
+Return a markdown table:
+| task | target_files | all_present | evidence |
+|------|--------------|-------------|----------|
+| <task text> | <comma-sep files> | yes/partial/no | <identifier:line or "none"> |
+
+Return ≤20 lines total. Self-cap: ≤10 tool uses (the tool-use budget is the true limit, not the task count).`
+})
+```
+
+**Decision after return (orchestrator inspects the returned table):**
+
+- **All tasks `all_present=no`** → Gate is transparent. Proceed to EXECUTE normally.
+- **Mixed** (any combination that is NOT all-no AND NOT all-yes — includes all-partial, yes+no, partial+no, yes+partial, yes+partial+no) → Edit the spec: mark `[x]` on tasks where `all_present=yes`. Leave `[ ]` on `partial` and `no` (both require re-dispatch). Re-dispatch EXECUTE only for tasks still `[ ]`. Keep the original scope (Light/Full). Do NOT invent a new "PARTIAL" state.
+- **All tasks `all_present=yes`** → **MANDATORY user surface** via `AskUserQuestion`: _"Pre-EXECUTE Existence Gate detected all N tasks already implemented. Evidence: {inline table}. Choose: (a) Close as already-implemented, (b) Force EXECUTE anyway (the gate may be wrong), (c) Abort pipeline."_ Never silently skip EXECUTE.
+
 ### EXECUTE Phase (Light scope — same session)
 
 When user chooses "Approve and implement now":
 1. Update spec: `Status: implementing`, `Phase: EXECUTE`
    Every agent prompt dispatched in Light scope MUST include:
-   `Return format cap: ≤50 lines. Apply compact Return Format from pipeline-config.md strictly.`
+   `Return format cap: ≤50 lines. Apply compact Return Format from .claude/pipeline-config.md strictly.`
 2. Update pipeline state: `status: "implementing"`, `phase: 3`
-3. Read `pipeline-config.md` for agent config. For `entity-registry.json`: Grep for specific entity block only
+3. Read `.claude/pipeline-config.md` for agent config. For `entity-registry.json`: Grep for specific entity block only
 4. Match recipes by title via Grep on `{subproject}/.claude/commands/recipes.md` — do NOT read full file. Extract recipe number + pattern refs
 5. Identify relevant skills for `{recommended_skills}`: list skill names most relevant to the task (e.g., `api-endpoint-wiring, api-dto-validation`). Agents use these as hints — Claude natively decides which to load based on descriptions
-6. Dispatch agents (wave rules: DB+Backend parallel, Frontend after Backend UNLESS spec marks task as `(parallel-safe)` — see `pipeline-config.md` Parallel Rules). Agent prompt includes `{recommended_skills}` as skill hints — agents read SKILL.md of relevant skills before implementing
-7. Wave transitions between waves (from `pipeline-config.md`)
+6. Dispatch agents (wave rules: DB+Backend parallel, Frontend after Backend UNLESS spec marks task as `(parallel-safe)` — see `.claude/pipeline-config.md` Parallel Rules). Agent prompt includes `{recommended_skills}` as skill hints — agents read SKILL.md of relevant skills before implementing
+7. Wave transitions between waves (from `.claude/pipeline-config.md`)
 8. On return: validate (build/type-check), update spec `[ ]` → `[x]` (line-by-line edits, NEVER copy entire spec blocks as old_string)
 8b. **Agent Memory:** After agents return and spec is updated, write agent memory: `node .claude/scripts/memory-write.js --json '{"agent_type":"{type}","wave":{N},"pipeline":"{spec-name}","summary":"{what agent did}","details":{...}}'` — one per agent. Skip if single-wave pipeline (no downstream agents to benefit).
 
@@ -186,9 +244,11 @@ After each agent returns, check the return value for an escalation status before
 - `PARTIAL` — apply Granular Retry Protocol from the last completed step; do NOT restart from step 1
 - `DEFERRED` — note in spec with agent justification; ask user if the deferred item is load-bearing before closing
 
-If two or more agents in the same wave return `CONCERN`, surface all concerns together before starting the next wave. See `pipeline-config.md` Escalation Statuses and Diagnostic Failure Routing for the full status table.
+If two or more agents in the same wave return `CONCERN`, surface all concerns together before starting the next wave. See `.claude/pipeline-config.md` Escalation Statuses and Diagnostic Failure Routing for the full status table.
+
+9. **REVIEW** — dispatch review agent for each affected subproject (reads guards + relevant skills, runs 7-category checklist: SOLID, Design System, Patterns, i18n, Integration, Build, Elegance). REJECTED → fix + re-review (max 2 loops).
 
-9. **REVIEW** — dispatch review agent for each affected subproject (reads guards + relevant skills, runs 7-category checklist: SOLID, Design System, Patterns, i18n, Integration, Build, Elegance). REJECTED → fix + re-review (max 2 loops)
+   Re-reviews always dispatch with `model: "sonnet"` (see `review/SKILL.md § Model Selection`).
 10. All passed + APPROVED → CLOSE flow inline (sync registry, move spec, cleanup state)
 11. Failed → max 2 retries, then STOP + report
 
@@ -208,13 +268,13 @@ Progress: `[v] ANALYZE  [>] PLAN  [ ] EXECUTE  [ ] CLOSE`
 Scope tag: `[LIGHT]` or `[FULL]` after progress line.
 
 ## Rules
-- This command is self-contained — reads `pipeline-config.md` directly
+- This command is self-contained — reads `.claude/pipeline-config.md` directly
 - NEVER implement code in Full scope — only PLAN. EXECUTE via `/approve` + `/resume`
 - NEVER launch Explore agent when entity already exists in registry — read 2-3 files directly
 - NEVER read additional files after Explore agent returns — its output is final
 - NEVER exceed 5 file reads in ANALYZE phase (registry + pipeline-config are free)
 - Light scope + user chose "implement now" → proceed to EXECUTE inline
-- ALWAYS read `pipeline-config.md` for agent/wave/model info
+- ALWAYS read `.claude/pipeline-config.md` for agent/wave/model info
 - ALWAYS create pipeline state at PLAN phase
 - ALWAYS record `scope` in spec header AND pipeline state
 - ALWAYS go straight to PLAN once you understand the change — more reads ≠ better spec

package/templates/commands/mustard/knowledge/SKILL.md

@@ -103,7 +103,7 @@ Manages persistent project observations injected into agent context during pipel
 | (no argument) | — | Lists all notes files |
 | `{subproject}` | `{subproject}/.claude/commands/notes.md` | Subproject agent context |
 
-**Monorepo**: discover targets from `pipeline-config.md` Agents table or Glob `*/.claude/commands/notes.md`.
+**Monorepo**: discover targets from `.claude/pipeline-config.md` Agents table or Glob `*/.claude/commands/notes.md`.
 **Single repo**: target is root → `.claude/commands/notes.md`.
 
 ### Flow — List (`/knowledge notes`)

package/templates/commands/mustard/maint/SKILL.md

@@ -1,68 +1,68 @@
-# /maint - Maintenance Utilities
-
-> Dependencies, build validation, and registry sync.
-
-## Trigger
-
-`/maint <action>`
-
-## Actions
-
-| Action | Description |
-|--------|-------------|
-| `deps` | Install dependencies for all projects |
-| `validate` | Run build and type-check validations |
-| `sync` | Update entity-registry.json from code |
-
----
-
-## deps
-
-Installs dependencies. Monorepo: runs in all subprojects. Single repo: runs in root.
-
-### Flow
-
-1. Read `pipeline-config.md` → extract `Agents` table for subproject paths and install commands
-2. For each subproject (or root if single repo), run the restore/install command from `## Commands` in `{subproject}/CLAUDE.md`
-3. Run all in parallel
-
-**Single repo**: read root `CLAUDE.md` → `## Commands` → run the install/restore command.
-
----
-
-## validate
-
-Runs build and type-check validations.
-
-### Flow
-
-1. Read `pipeline-config.md` → extract `Agents` table for validate/build commands
-2. For each subproject (or root if single repo), run the build/type-check command from `{subproject}/CLAUDE.md` → `## Commands`
-3. Run all in parallel
-
-### Result
-
-- **Success** — project compiles and passes type-check
-- **Failure** — lists errors found
-
-**Single repo**: read root `CLAUDE.md` → `## Commands` → run the build command.
-
----
-
-## sync
-
-Scans the project and updates `.claude/entity-registry.json`.
-
-### Flow
-
-1. `node .claude/scripts/sync-registry.js`
-2. If script not found, scan manually:
-   - Search database schemas (EF Core `DbSet<T>`, Drizzle `pgTable()`, Prisma `model`, etc.)
-   - Build entity map with relationships
-   - Update `.claude/entity-registry.json`
-
-### When to Use
-
-- After creating new entity
-- After importing existing code
-- To sync after manual changes
+# /maint - Maintenance Utilities
+
+> Dependencies, build validation, and registry sync.
+
+## Trigger
+
+`/maint <action>`
+
+## Actions
+
+| Action | Description |
+|--------|-------------|
+| `deps` | Install dependencies for all projects |
+| `validate` | Run build and type-check validations |
+| `sync` | Update entity-registry.json from code |
+
+---
+
+## deps
+
+Installs dependencies. Monorepo: runs in all subprojects. Single repo: runs in root.
+
+### Flow
+
+1. Read `.claude/pipeline-config.md` → extract `Agents` table for subproject paths and install commands
+2. For each subproject (or root if single repo), run the restore/install command from `## Commands` in `{subproject}/CLAUDE.md`
+3. Run all in parallel
+
+**Single repo**: read root `CLAUDE.md` → `## Commands` → run the install/restore command.
+
+---
+
+## validate
+
+Runs build and type-check validations.
+
+### Flow
+
+1. Read `.claude/pipeline-config.md` → extract `Agents` table for validate/build commands
+2. For each subproject (or root if single repo), run the build/type-check command from `{subproject}/CLAUDE.md` → `## Commands`
+3. Run all in parallel
+
+### Result
+
+- **Success** — project compiles and passes type-check
+- **Failure** — lists errors found
+
+**Single repo**: read root `CLAUDE.md` → `## Commands` → run the build command.
+
+---
+
+## sync
+
+Scans the project and updates `.claude/entity-registry.json`.
+
+### Flow
+
+1. `node .claude/scripts/sync-registry.js`
+2. If script not found, scan manually:
+   - Search database schemas (EF Core `DbSet<T>`, Drizzle `pgTable()`, Prisma `model`, etc.)
+   - Build entity map with relationships
+   - Update `.claude/entity-registry.json`
+
+### When to Use
+
+- After creating new entity
+- After importing existing code
+- To sync after manual changes

package/templates/commands/mustard/metrics/SKILL.md

@@ -0,0 +1,33 @@
+---
+name: mustard:metrics
+description: Show enforcement metrics report — hook hit rates, budget distributions, gate activity. Metrics are recorded automatically; just run this to see them.
+---
+
+# /mustard:metrics - Show Metrics Report
+
+## Trigger
+`/mustard:metrics [--since <ISO date>] [--event <type>]`
+
+## What it does
+Runs `.claude/scripts/metrics-report.js` and shows the aggregated report.
+
+Metrics are recorded **automatically** by enforcement hooks on every Task dispatch — no activation needed. Just run this command whenever you want to see the current state.
+
+## Action
+1. Run `rtk node .claude/scripts/metrics-report.js $ARGS` (pass through any flags)
+2. Display output verbatim
+
+## Optional flags
+- `--since <ISO date>` — filter events after this date
+- `--event <type>` — filter to one event type (e.g. `budget-check`)
+
+## Examples
+- `/mustard:metrics` — full report since beginning
+- `/mustard:metrics --since 2026-04-09` — only recent events
+- `/mustard:metrics --event budget-check` — only budget-check events
+
+## Notes
+- Metrics live in `.claude/.metrics/*.jsonl` (gitignored, runtime state)
+- Logs auto-rotate at 10MB
+- To reset: delete files in `.claude/.metrics/` manually
+- Advanced: override mode via `CONTEXT_BUDGET_MODE` env var (`strict`|`warn`|`observe`). Default is `strict`.

package/templates/commands/mustard/resume/SKILL.md

@@ -87,7 +87,7 @@ Before the normal detect-and-confirm flow, scan the newest pipeline state for a
 ### Diff Context (automatic)
 Run `node .claude/scripts/diff-context.js` to capture the current git state. Include the output in the agent prompt as `{diff_context}` so agents know what has already changed.
 
-7. **Read** `pipeline-config.md`. For `entity-registry.json`: use Grep to extract ONLY the relevant entity block (e.g. `"Contract":`), NEVER read the full JSON
+7. **Read** `.claude/pipeline-config.md`. For `entity-registry.json`: use Grep to extract ONLY the relevant entity block (e.g. `"Contract":`), NEVER read the full JSON
 9. **Update spec header:** `Status: implementing`, `Phase: EXECUTE`, `Checkpoint: {ISO now}`
 10. **Update/create pipeline state:** `status: "implementing"`, `phaseName: "EXECUTE"`, `specName`
 11. **TaskCreate** — 1 per pending agent (skip completed)
@@ -97,9 +97,13 @@ Run `node .claude/scripts/diff-context.js` to capture the current git state. Inc
 **CRITICAL: Main context IS the Pipeline Runner. NEVER delegate to intermediate Task agent.**
 
 12. **Match recipe by name only:** Grep `{subproject}/.claude/commands/recipes.md` for recipe title matching the task type — do NOT read the full recipes file. Extract only: recipe number, pattern refs, reference modules
-13. **Plan waves:** `Depends on: none` → Wave 1; dependencies → later. DB+Backend parallel. Frontend after Backend UNLESS all parallel override conditions met (see `pipeline-config.md` Parallel Rules). Review agents: ALWAYS dispatch in single parallel message. Skip completed tasks.
+12b. **Pre-EXECUTE Existence Gate**: Same gate as `feature/SKILL.md § Pre-EXECUTE Existence Gate`. Invoke identically (Full scope only, `## Files` ≤ 8). On retry/resume, the gate naturally handles idempotence: tasks already `[x]` from a prior run are treated as Mixed — the Haiku confirms they stay done and the orchestrator only re-dispatches what remains `[ ]`.
+
+    **Pre-check (same as `feature/SKILL.md § Pre-EXECUTE Existence Gate`):** Before dispatching Haiku, run `rtk git diff --stat HEAD -- <files listed in spec's ## Files>`. Skip gate entirely if output is empty (no changes) or total insertions/deletions <10. Only proceed with Haiku dispatch if ≥10 lines changed.
+
+13. **Plan waves:** `Depends on: none` → Wave 1; dependencies → later. DB+Backend parallel. Frontend after Backend UNLESS all parallel override conditions met (see `.claude/pipeline-config.md` Parallel Rules). Review agents: ALWAYS dispatch in single parallel message. Skip completed tasks.
 14. **Build agent prompts using template** (`.claude/commands/mustard/templates/agent-prompt/SKILL.md`):
-    - Read template once, then fill placeholders per agent using `pipeline-config.md` data:
+    - Read template once, then fill placeholders per agent using `.claude/pipeline-config.md` data:
       - `{subproject}` → from Agents table (Subproject column)
       - `{reference_files}` → 2-3 files from matched recipe
       - `{guards_summary}` → key guards from `{subproject}/CLAUDE.md`
@@ -108,12 +112,12 @@ Run `node .claude/scripts/diff-context.js` to capture the current git state. Inc
       - `{validate_command}`, `{build_command}` → from Agents table in config
       - `{retry_context}` → empty on first dispatch (see Step 4 for retries)
       - `{task_steps}` → checkboxed steps from spec
-      - `{recommended_skills}` → from Skill Recommendations in `pipeline-config.md`:
+      - `{recommended_skills}` → from Skill Recommendations in `.claude/pipeline-config.md`:
         1. Glob `{subproject}/.claude/skills/` for generated pattern skills
         2. Add foundation skills matching the role (ui→design-craft+react-best-practices, mobile→design-craft)
         3. Format as bullet list: `- {skill-name}`
 
-16. **Wave transitions** — between waves, execute transitions from `pipeline-config.md`:
+16. **Wave transitions** — between waves, execute transitions from `.claude/pipeline-config.md`:
     - After Wave 1 (api/database/library) completes, before Wave 2 (ui):
       - Execute each command listed in the matching `Wave Transitions` section
     - Wait for transitions to complete before dispatching next wave
@@ -136,7 +140,7 @@ After each agent returns, check the return value for an escalation status before
 - `PARTIAL` — apply Granular Retry Protocol from the last completed step; do NOT restart from step 1
 - `DEFERRED` — note in spec with agent justification; ask user if the deferred item is load-bearing before closing
 
-If two or more agents in the same wave return `CONCERN`, surface all concerns together before dispatching the next wave. See `pipeline-config.md` Escalation Statuses and Diagnostic Failure Routing for the full status table.
+If two or more agents in the same wave return `CONCERN`, surface all concerns together before dispatching the next wave. See `.claude/pipeline-config.md` Escalation Statuses and Diagnostic Failure Routing for the full status table.
 
 ### Step 4: Validate, Review & Complete
 
@@ -206,6 +210,6 @@ This eliminates decision fatigue on resume. The user can always override, but th
 - Wave dispatch: ALL agents in same wave in a SINGLE message
 - Each sub-agent reads its own `{subproject}/CLAUDE.md` + auto-loads relevant skills (orchestrator does NOT read them)
 - Update pipeline state + spec checkboxes at each transition
-- ALWAYS read `pipeline-config.md` for agent/wave/model config — NEVER hardcode project-specific values
+- ALWAYS read `.claude/pipeline-config.md` for agent/wave/model config — NEVER hardcode project-specific values
 - ALWAYS use agent-prompt template — NEVER build prompts from scratch
 - ALWAYS execute wave transitions between waves