mustard-claude 3.1.31 → 3.1.32

package/package.json

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

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

@@ -23,15 +23,31 @@ Approves the active spec and prepares the implementation phase.
    - Do NOT proceed to step 2 without running this command
 2. **Read** `.claude/pipeline-config.md` — agents, model selection
 3. Locate active spec in `.claude/spec/active/`
+
+### Step 3b: Wave Plan Detection
+
+Check if the located spec is a wave plan: look for `.claude/spec/active/{specName}/wave-plan.md`.
+
+**If `wave-plan.md` exists:**
+
+1. Read `.claude/.pipeline-states/{specName}.json` — expect `isWavePlan: true`, `totalWaves: N`, `currentWave: 1`, `completedWaves: []`.
+2. Read `wave-plan.md` and print its ENTIRE contents verbatim inside a fenced markdown block (```` ```markdown ... ``` ````). List each wave spec file path below the block (one line each).
+3. `AskUserQuestion`:
+   - **"Approve wave plan — start with wave 1"** → proceed to step 4 (update header + state for wave 1 dispatch)
+   - **"Reject decomposition — use single spec"** → merge all wave specs back into a single spec at `.claude/spec/active/{specName}/spec.md` (concatenate `## Files`, `## Tasks`, `## Boundaries` from each wave), delete `wave-plan.md` and `wave-N-*/` subdirectories, set `scopeOverride: "user-rejected-waves"` and `isWavePlan: false` in pipeline state, proceed to step 4 on the single spec
+   - **"Stop — re-plan with guidance"** → stop. Instruct user: `Delete .claude/spec/active/{specName}/ and re-run /feature {name} with explicit guidance (e.g., "keep wave 2 and wave 3 together").`
+4. If user approved wave plan, for step 4 and onward, operate on the **wave 1 spec** (`.claude/spec/active/{specName}/wave-1-{role}/spec.md`) — update its header, not the wave-plan.md header.
+
+**If `wave-plan.md` does NOT exist:** proceed as a single spec (original behavior below).
+
 4. **Spec Checkpoint — update spec header:**
    - `### Status: approved`
    - `### Phase: PLAN`
    - `### Checkpoint: {ISO timestamp now}`
-5. **Pipeline State — create `.claude/.pipeline-states/{spec-name}.json`:**
+5. **Pipeline State — create or update `.claude/.pipeline-states/{spec-name}.json`:**
    - Extract `spec-name` from the spec directory (e.g. basename of path → `2026-02-26-linked-services-card`)
-   - 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`
+   - **If wave plan (from Step 3b):** state already exists. Update fields: `status: "approved"`, `currentWave: 1`, `updatedAt`. Parse tasks from **wave-1** spec only (not all waves). Preserve `isWavePlan`, `totalWaves`, `completedWaves`, `failedWaves`.
+   - **If single spec:** 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`.
 5b. **Memory Persist — record architectural decisions:**
    - For each significant decision in the spec (technology choices, design patterns, trade-offs):
      ```bash

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

@@ -58,6 +58,32 @@ If the diff file is empty or missing, skip the Git State header entirely. Never
    - Trace callers/callees via Grep in relevant directories (prefer Grep over Read)
    - Return as soon as root cause is clear — don't exhaustively scan
    - Return: root cause file(s), line(s), explanation
+
+2b. **Cache root-cause for retry reuse:**
+
+After DIAGNOSE returns, compute a cache signature so fix-loop retries can skip re-DIAGNOSE when the affected surface hasn't changed:
+
+```javascript
+// in-memory during bugfix session (also persisted to pipeline-state for Full Path)
+const affectedFiles = [...root-cause file(s) from Explore return, sorted];
+const bugDescription = {user's error description, canonical — trimmed and lowercased};
+const rootCauseHash = sha256(bugDescription + '|' + affectedFiles.join(','));
+const rootCauseSummary = {1-line root cause from Explore, ≤500 chars};
+const affectedFilesHash = sha256(concatenated contents of affectedFiles right now);
+```
+
+Write to pipeline-state if Full Path (`.claude/.pipeline-states/{specName}.json`):
+```json
+{
+  "rootCauseHash": "sha256...",
+  "rootCauseSummary": "...",
+  "affectedFilesHash": "sha256...",
+  "affectedFiles": ["path/a.ts", "path/b.ts"],
+  "cachedAt": "{ISO}"
+}
+```
+
+For Fast Path (no spec yet), keep the cache in-memory only — it lives for the duration of the bugfix session, which is sufficient for the retry loop.
 3. **ASSESS — Decision point:**
    - Explore returns clear root cause in 1-2 files → **Fast Path** (skip PLAN)
    - 3+ files, unclear impact, cross-layer → **Full Path** (brief spec via PLAN)
@@ -125,9 +151,19 @@ Before retrying a failed fix attempt, classify the failure:
 
 1. **Transient?** — Would re-running succeed without any change? (flaky test, cache, env) → Retry once immediately.
 2. **Resolvable?** — Is the fix clear and patchable in ≤3 lines without new reads? → Apply patch, retry (counts as retry 1).
-3. **Structural?** — Did the original ANALYZE misidentify the root cause? → Re-analyze: dispatch a focused Explore on the actual failure point, update root cause, re-dispatch bugfix agent. Does NOT count against the 2-retry cap.
-
-Max 2 retries for Transient + Resolvable. Structural failures trigger a targeted re-ANALYZE, not a blind retry.
+3. **Structural?** — Did the original ANALYZE misidentify the root cause? → **Before re-Exploring, consult the root-cause cache from Step 2b:**
+   - Recompute `affectedFilesHash` for the cached `affectedFiles`.
+   - **Cache hit (hash matches) AND failure signal does NOT suggest a different cause** (no keyword in the failure pointing to files outside `affectedFiles`, no REVIEW rationale explicitly naming a different root) → skip re-Explore, inject `rootCauseSummary` verbatim into the retry prompt. Log: `root-cause cached (retry {N}/2), skipping diagnose`.
+   - **Cache miss (files changed) OR failure rationale points elsewhere** → invalidate cache, run targeted Explore on the actual failure point, update root cause (including new cache entry via Step 2b), re-dispatch bugfix agent.
+   - Re-ANALYZE (with or without cache) does NOT count against the 2-retry cap.
+
+Max 2 retries for Transient + Resolvable. Structural failures trigger a targeted re-ANALYZE (cache-gated), not a blind retry.
+
+**Cache invalidation signals:**
+- Affected files changed on disk → hash mismatch invalidates
+- Review/build failure rationale mentions files outside `affectedFiles` → invalidate
+- User explicitly overrides (rare) → invalidate
+- After 2 retries exhausted, the cache is naturally flushed when the pipeline aborts or advances
 
 ### CLOSE
 

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

@@ -121,6 +121,101 @@ Continue to PLAN regardless.
 
 ### PLAN Phase
 
+#### Wave Decomposition Pre-Check (Full scope only)
+
+**Skip for Light/Extended Light** — decomposition only makes sense when scope is genuinely large.
+
+Before writing the single spec in Full scope, check whether the work should be decomposed into waves:
+
+1. **Compute signals from ANALYZE output:**
+   - `fileCount` — files that will go into `## Files`
+   - `layerCount` — distinct layers (use role detection derived from paths: schema/api/ui/lib)
+   - `newEntityCount` — new entities created by this spec
+   - `estimatedTouchPoints` — count of imports/refs from Grep on affected directories (optional)
+
+2. **Read knowledge matches:** Read `.claude/knowledge.json` (if it exists). Extract entries whose `id` starts with `heavy-pipeline` or `high-hook-retry`. Each entry's scope signals represent a historical pipeline that cost a lot.
+
+3. **Run decomposition decision:**
+   ```bash
+   echo '{"fileCount":{N},"layerCount":{L},"newEntityCount":{E},"knowledgeMatches":[...]}' | node .claude/scripts/scope-decompose.js
+   ```
+   Output JSON: `{decompose: bool, reason: string, signals: {...}}`
+
+4. **If `decompose: false`** → proceed to `#### Full Scope` below as usual (single spec).
+
+5. **If `decompose: true`** → build wave plan:
+   ```bash
+   echo '{"files":[...all paths from ANALYZE...],"projectRoot":"."}' | node .claude/scripts/wave-dependency.js
+   ```
+   Output cases:
+   - `{error: "cyclic-dependency", cycle: [...]}` → warn user about cyclic imports (pre-existing architecture issue), fall back to single spec with note in `## Concerns`. Proceed to `#### Full Scope`.
+   - `{error: ...}` → fail-open: fall back to single spec.
+   - `{waves: [...]}` with only 1 wave → no real DAG depth, fall back to single spec.
+   - `{waves: [...]}` with 2+ waves → write **Wave Plan** (step 6).
+
+6. **Write Wave Plan structure:**
+   ```
+   .claude/spec/active/{date}-{name}/
+     ├── wave-plan.md
+     ├── wave-1-{role}/spec.md
+     ├── wave-2-{role}/spec.md
+     └── wave-N-{role}/spec.md
+   ```
+
+   `wave-plan.md` contains:
+   ```markdown
+   # Wave Plan: {name}
+   ### Status: draft | Phase: PLAN | Scope: full | Decomposed: yes
+   ### Checkpoint: {ISO now}
+   ### Reason: {decompose.reason}
+
+   ## Summary
+   {1-2 lines: what + why}
+
+   ## Waves
+   ### Wave 1 — {roles of wave 1}
+   Depends on: none
+   Files ({count}): {file1}, {file2}, ...
+
+   ### Wave 2 — {roles of wave 2}
+   Depends on: wave 1
+   Files ({count}): {file3}, ...
+
+   {... for each wave ...}
+
+   ## Rationale
+   {which knowledge entry matched or which threshold triggered; signals from scope-decompose}
+   ```
+
+   Each `wave-N-{role}/spec.md` is a **complete atomic spec** scoped to just that wave's files. Use the same template as Full scope single spec (Summary, Entity Info, Files, Tasks, Dependencies, Boundaries). Reference `../wave-plan.md` at the top as context.
+
+7. **Write pipeline state for wave plan:**
+   ```json
+   {
+     "specName": "{date}-{name}",
+     "status": "draft",
+     "phase": 2,
+     "phaseName": "PLAN",
+     "scope": "full",
+     "isWavePlan": true,
+     "currentWave": 1,
+     "totalWaves": N,
+     "completedWaves": [],
+     "failedWaves": []
+   }
+   ```
+
+8. **Present wave plan to user:**
+   - Read `wave-plan.md` and print its ENTIRE contents verbatim inside a fenced markdown block.
+   - Also list each wave's spec file paths (one line each) so the user can open individual wave specs if desired.
+   - Then `AskUserQuestion`:
+     - **"Approve wave plan and implement now"** → goes to EXECUTE wave 1 inline (same rules as Light inline)
+     - **"Approve wave plan for later"** → stop, user runs `/approve` + `/resume`
+     - **"Edit decomposition (hint PLAN)"** → user provides hint (e.g., "merge waves 2 and 3"), PLAN reexecutes with the hint appended to `estimatedTouchPoints`/manual grouping. Re-decompose once.
+     - **"Reject decomposition — use single spec"** → discard wave plan files, set `scopeOverride: "user-rejected-waves"` in pipeline state, proceed to `#### Full Scope` as if `decompose: false`.
+
+9. **If user approves the wave plan**, the single-spec `#### Full Scope` flow below is **skipped** — wave-1 becomes the first thing to execute (via `/approve --resume` or `/resume`).
+
 #### Full Scope
 
 1. Create `.claude/spec/active/{date}-{name}/spec.md` with:
@@ -300,5 +395,7 @@ Scope tag: `[LIGHT]` or `[FULL]` after progress line.
 - ALWAYS go straight to PLAN once you understand the change — more reads ≠ better spec
 - Light scope inline implement follows same dispatch rules as `/resume` (template, waves, retries)
 - Context budget: Grep entity-registry (not full read), Grep recipes (not full read), line-by-line checkbox updates
+- Wave decomposition is opt-in via signals (knowledge matches, layer/file/entity counts) — never force waves on small scopes
+- If wave decomposition is approved, single-spec Full Scope flow is skipped — waves execute sequentially via `/resume`
 
 ULTRATHINK

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

@@ -29,7 +29,28 @@ Before the normal detect-and-confirm flow, scan the newest pipeline state for a
      3. After the re-dispatch returns, clear the flag: remove `lastDispatchFailure` from the state object and rewrite the pipeline-state JSON.
      4. Fall through to Step 1 (normal resume flow continues from the updated state).
    - **If ageMs > 10 * 60 * 1000** (stale): silently remove `lastDispatchFailure` from the state and rewrite the file, then continue to Step 1.
-4. If `lastDispatchFailure` is absent, skip Step 0 entirely and proceed to Step 1.
+4. If `lastDispatchFailure` is absent, skip Step 0 entirely and proceed to Step 0.5.
+
+### Step 0.5: Resume Mode (continuar vs reanalisar)
+
+Before loading heavy context (sync-registry, diff-context, Explore Gate), ask the user which mode to use. This gates roughly 2-5k tokens per resume.
+
+1. **Skip conditions** — enter `reanalyze` mode automatically without prompting:
+   - Step 0 just re-dispatched a failed agent (recovery path → always reanalyze next step)
+   - `pipeline-state.lastDispatchFailure` was present and <10min old (already handled in Step 0)
+   - Wave plan with `failedWaves.length > 0` (handled in wave failure section below — forces `reanalyze`)
+
+2. **Otherwise, AskUserQuestion:**
+   - **"Continuar de onde parou (modo leve)"** → `mode = "continued"`: skip sync-registry (Step 2 #6), skip diff-context (unless wave transition forces), skip Pre-EXECUTE Existence Gate (Step 12b). Trust pipeline-state as source of truth.
+   - **"Reanalisar contexto (modo completo)"** → `mode = "reanalyzed"`: run Step 2 fully (default behavior, relê tudo).
+
+3. **Record mode in pipeline state:** write `resumeMode: "continued" | "reanalyzed"` and `resumeModeAt: {ISO now}` so downstream steps know which path they are in.
+
+4. **Stale-context fallback (safety net):** if a dispatched agent in `continued` mode returns an error indicating stale context (e.g., references a missing file, fails boundary check, or returns `BLOCKED` with reason citing out-of-date registry), escalate automatically:
+   - Update pipeline state: `resumeMode: "escalated-to-reanalyze"`, append to `resumeEscalations` array with `{at, reason}`
+   - Re-run Step 2 in full (sync-registry + diff-context)
+   - Re-dispatch the failed agent with fresh context
+   - Fail-open: escalation never blocks, just upgrades to the heavier path
 
 ### Step 1: Detect & Confirm
 
@@ -83,10 +104,14 @@ Before the normal detect-and-confirm flow, scan the newest pipeline state for a
 ### Step 2: Bootstrap (after confirmation)
 
 6. **AUTO-SYNC:** `node .claude/scripts/sync-registry.js`
+   - **Skip if `resumeMode === "continued"`** (Step 0.5): registry is reused from prior session.
+   - Always run if `resumeMode === "reanalyzed"` or `"escalated-to-reanalyze"`.
 
 ### Diff Context (automatic)
 Run `node .claude/scripts/diff-context.js --subproject {subproject_path}` per subproject to capture the current git state scoped to each subproject. Include the subproject-specific output in the agent prompt as `{diff_context}` so agents see only changes relevant to their scope.
 
+**Skip if `resumeMode === "continued"`** unless a wave just completed (wave transitions always refresh diff). The prior diff snapshot is reused from `.claude/.pipeline-states/{specName}.diff-{subproject}.md`.
+
 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`
@@ -99,9 +124,26 @@ Run `node .claude/scripts/diff-context.js --subproject {subproject_path}` per su
 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
 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 `[ ]`.
 
+   **Skip entirely if `resumeMode === "continued"`** (Step 0.5). The `continued` mode trusts pipeline-state checkboxes as-is. If the stale-context fallback escalates to `reanalyze`, the gate runs on the re-dispatch.
+
     **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.
 
+12c. **Wave Plan Scope (conditional — only if `pipeline-state.isWavePlan === true`):**
+
+When the pipeline state indicates a wave plan, the orchestrator dispatches only the **current wave**, not the full spec:
+
+1. Read `pipeline-state.currentWave` and `pipeline-state.totalWaves`.
+2. The spec to work from for this invocation is `.claude/spec/active/{specName}/wave-{currentWave}-*/spec.md`. Replace any prior reference to `spec.md` at the root of the spec dir with the current wave's spec.
+3. **Between waves** (see Step 17 post-dispatch):
+   - On wave completion: run `/mustard:git commit` style commit with message `feat(wave-{N}/{role}): {summary}`. If `/mustard:git commit` is not appropriate for the project, fall back to `git add {files} && git commit -m "..."`.
+   - Update state: `completedWaves.push(currentWave)`, `currentWave += 1`, `updatedAt`.
+   - Force `resumeMode = "reanalyzed"` for the next wave transition so diff-context refreshes with the just-committed changes.
+   - If `currentWave > totalWaves` → skip remaining wave dispatch, go to Step 19 REVIEW + Step 20 CLOSE on the overall wave plan.
+4. **If a wave fails (REJECTED after 2 fix-loops, or BLOCKED)** — see § Wave Failure Handling below.
+
 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.
+
+**Note on wave plans:** when `isWavePlan === true`, this step plans the agent wave structure **within** the current wave's spec only — agents internal to the current wave-spec may still split across DB/Backend/Frontend sub-waves. The outer wave (1..N) is the cross-spec sequence managed by Step 12c.
 14. **Build agent prompts using template** (`.claude/commands/mustard/templates/agent-prompt/SKILL.md`):
     - Read template once, then fill placeholders per agent using `.claude/pipeline-config.md` data:
       - `{subproject}` → from Agents table (Subproject column)
@@ -183,11 +225,46 @@ When REVIEW returns REJECTED (any CRITICAL):
 8. If review still REJECTED after 2 fix-loops: STOP + report exhausted retries.
 
 20. **CLOSE:**
+    - **Wave plan gate:** if `pipeline-state.isWavePlan === true`, only CLOSE when `completedWaves.length === totalWaves`. If waves remain (`currentWave <= totalWaves` and wave N-1 just finished), **do not** run CLOSE — instead update state (`currentWave++`, `completedWaves.push`), output `═══ WAVE {N-1} COMPLETE — {role} ═══`, and stop. Next `/mustard:resume` picks up wave N.
     - `node .claude/scripts/sync-registry.js`
-    - Spec: `Status: completed`, `Phase: CLOSE`, all `[ ]` → `[x]`
-    - Move spec to `.claude/spec/completed/`
+    - Spec: `Status: completed`, `Phase: CLOSE`, all `[ ]` → `[x]`. For wave plans: mark `wave-plan.md` status `completed`, and mark each `wave-N-{role}/spec.md` completed too.
+    - Move spec to `.claude/spec/completed/` (the entire `{specName}/` directory, including wave subdirs if any)
     - **Delete** `.claude/.pipeline-states/{spec-name}.json`
-    - Output with agent colors: `═══ PIPELINE COMPLETE — {name} | Agents: {n} ok | Files: {c} created, {m} modified ═══`
+    - Output with agent colors: `═══ PIPELINE COMPLETE — {name} | Agents: {n} ok | Files: {c} created, {m} modified ═══` (for wave plans: append `| Waves: {totalWaves}`).
+
+### Wave Failure Handling
+
+Applies only when `pipeline-state.isWavePlan === true`.
+
+A wave is considered **failed** when:
+- REVIEW returns REJECTED after 2 fix-loops exhausted (see Step 19b), OR
+- An implementation agent returns `BLOCKED` and the user cannot resolve inline, OR
+- Build/type-check fails repeatedly (max 2 retries) after Granular Retry Protocol is exhausted.
+
+**On wave failure:**
+
+1. Update pipeline state:
+   - `failedWaves.push(currentWave)`
+   - `status = "failed"`
+   - `updatedAt = {ISO now}`
+2. Write failure log to `.claude/spec/active/{specName}/wave-{currentWave}-{role}/failure.md`:
+   ```markdown
+   # Wave {N} Failure — {role}
+   ## When: {ISO}
+   ## Phase: {EXECUTE | REVIEW | CLOSE}
+   ## Reason: {short cause — e.g., "REVIEW REJECTED after 2 fix-loops"}
+   ## Findings (verbatim)
+   {last review findings OR BLOCKED rationale OR build error}
+   ## Files touched
+   {list from agent memory}
+   ```
+3. **Do NOT** attempt further automatic recovery. Wave N-1 commits remain in place — they are real progress.
+4. **Prompt the user via AskUserQuestion:**
+   - **"Corrigir wave {N} manualmente e retomar"** → user fixes by hand; next `/mustard:resume` clears `failedWaves` entry and restarts wave N from EXECUTE.
+   - **"Reescrever wave {N} (re-PLAN dessa onda)"** → delete `wave-{N}-{role}/spec.md`, re-enter PLAN for wave N only (run PLAN sub-flow scoped to wave N's files). User then re-approves via `/mustard:approve` for wave N.
+   - **"Abortar pipeline"** → set `status: "aborted"`, move spec to `.claude/spec/aborted/{specName}/` (create dir if needed), keep waves 1..N-1 commits. Inform user: `Pipeline aborted. Waves 1..{N-1} commits preserved. Waves {N}..{totalWaves} discarded.`
+
+**Risco residual documentado:** wave N-1 commits podem estar incompletos semanticamente sem wave N (ex.: schema criado mas API não). O usuário foi avisado disso no `/approve` da wave plan. O log `failure.md` explicita qual superfície ficou exposta.
 
 ### Granular Retry Protocol
 

package/templates/scripts/scope-decompose.js

@@ -0,0 +1,105 @@
+#!/usr/bin/env node
+
+/**
+ * scope-decompose.js
+ *
+ * Decides whether a feature spec should be decomposed into multiple waves.
+ * Reads signals from stdin (JSON), emits decision to stdout (JSON).
+ *
+ * Input (stdin):
+ *   {
+ *     fileCount: number,          // arquivos em "## Files" do spec
+ *     layerCount: number,         // camadas distintas tocadas
+ *     newEntityCount: number,     // entidades novas
+ *     estimatedTouchPoints: number, // imports/refs cruzados (opcional)
+ *     knowledgeMatches: [         // entradas heavy-pipeline/high-hook-retry do knowledge.json
+ *       { id: string, type: string, scope: object }
+ *     ]
+ *   }
+ *
+ * Output (stdout):
+ *   { decompose: boolean, reason: string, signals: {...} }
+ *
+ * Fail-open: on any error, emits { decompose: false, reason: "error-fallback" }
+ * and exits 0.
+ */
+
+"use strict";
+
+function readStdin() {
+  return new Promise((resolve) => {
+    let data = "";
+    process.stdin.setEncoding("utf8");
+    process.stdin.on("data", (chunk) => {
+      data += chunk;
+    });
+    process.stdin.on("end", () => resolve(data));
+    process.stdin.on("error", () => resolve(""));
+  });
+}
+
+function decide(signals) {
+  const {
+    fileCount = 0,
+    layerCount = 0,
+    newEntityCount = 0,
+    estimatedTouchPoints = 0,
+    knowledgeMatches = [],
+  } = signals;
+
+  const hasHistoricalMatch = Array.isArray(knowledgeMatches) && knowledgeMatches.length > 0;
+
+  if (!hasHistoricalMatch && fileCount <= 5) {
+    return {
+      decompose: false,
+      reason: "small-scope-no-history",
+      signals: { fileCount, layerCount, newEntityCount, estimatedTouchPoints, historicalMatches: 0 },
+    };
+  }
+
+  if (hasHistoricalMatch) {
+    return {
+      decompose: true,
+      reason: `history-match:${knowledgeMatches[0].id || "unknown"}`,
+      signals: { fileCount, layerCount, newEntityCount, estimatedTouchPoints, historicalMatches: knowledgeMatches.length },
+    };
+  }
+
+  if (layerCount >= 3) {
+    return {
+      decompose: true,
+      reason: "deep-layers",
+      signals: { fileCount, layerCount, newEntityCount, estimatedTouchPoints, historicalMatches: 0 },
+    };
+  }
+
+  if (fileCount > 10 && newEntityCount >= 2) {
+    return {
+      decompose: true,
+      reason: "wide-and-new-entities",
+      signals: { fileCount, layerCount, newEntityCount, estimatedTouchPoints, historicalMatches: 0 },
+    };
+  }
+
+  return {
+    decompose: false,
+    reason: "below-thresholds",
+    signals: { fileCount, layerCount, newEntityCount, estimatedTouchPoints, historicalMatches: 0 },
+  };
+}
+
+async function main() {
+  try {
+    const raw = await readStdin();
+    let signals = {};
+    if (raw.trim()) {
+      signals = JSON.parse(raw);
+    }
+    const decision = decide(signals);
+    process.stdout.write(JSON.stringify(decision));
+  } catch (_err) {
+    process.stdout.write(JSON.stringify({ decompose: false, reason: "error-fallback" }));
+  }
+}
+
+main();

package/templates/scripts/wave-dependency.js

@@ -0,0 +1,239 @@
+#!/usr/bin/env node
+
+/**
+ * wave-dependency.js
+ *
+ * Builds a dependency DAG from a list of files (via imports/require/from parsing)
+ * and groups files into waves using topological level assignment.
+ *
+ * Input (stdin):
+ *   {
+ *     files: ["src/schema/user.ts", "src/api/users.ts", ...],
+ *     projectRoot: "."               // absolute or relative to cwd (optional, defaults to cwd)
+ *   }
+ *
+ * Output (stdout):
+ *   Success:
+ *   {
+ *     waves: [
+ *       { wave: 1, files: [...], roles: [...], dependsOn: [] },
+ *       { wave: 2, files: [...], roles: [...], dependsOn: [1] },
+ *       ...
+ *     ],
+ *     metadata: { totalWaves: N, totalFiles: M, widestWave: W }
+ *   }
+ *
+ *   Error:
+ *   { error: "cyclic-dependency" | "empty-input" | "error-fallback", cycle?: [...] }
+ *
+ * Fail-open: on unrecoverable error, emits { error: "error-fallback" } and exits 0.
+ */
+
+"use strict";
+
+const fs = require("fs");
+const path = require("path");
+
+const RESOLVABLE_EXTENSIONS = [".ts", ".tsx", ".js", ".jsx", ".mjs", ".cjs", ".vue", ".svelte", ".py", ".go", ".cs"];
+const INDEX_BASENAMES = ["index.ts", "index.tsx", "index.js", "index.jsx", "index.mjs", "__init__.py"];
+
+function readStdin() {
+  return new Promise((resolve) => {
+    let data = "";
+    process.stdin.setEncoding("utf8");
+    process.stdin.on("data", (chunk) => {
+      data += chunk;
+    });
+    process.stdin.on("end", () => resolve(data));
+    process.stdin.on("error", () => resolve(""));
+  });
+}
+
+function extractImports(content) {
+  const imports = new Set();
+  const patterns = [
+    /import\s+[\s\S]*?from\s+['"]([^'"]+)['"]/g,
+    /import\s+['"]([^'"]+)['"]/g,
+    /require\s*\(\s*['"]([^'"]+)['"]\s*\)/g,
+    /from\s+([.\w]+)\s+import\s+/g,
+  ];
+  for (const re of patterns) {
+    let m;
+    while ((m = re.exec(content)) !== null) {
+      imports.add(m[1]);
+    }
+  }
+  return [...imports];
+}
+
+function resolveImport(importPath, currentFileAbs, projectRoot, candidateSet) {
+  if (!importPath.startsWith(".") && !importPath.startsWith("/")) {
+    return null;
+  }
+  const baseDir = path.dirname(currentFileAbs);
+  const absTarget = path.resolve(baseDir, importPath);
+
+  if (candidateSet.has(absTarget)) return absTarget;
+
+  for (const ext of RESOLVABLE_EXTENSIONS) {
+    const withExt = absTarget + ext;
+    if (candidateSet.has(withExt)) return withExt;
+  }
+
+  const lastDot = absTarget.lastIndexOf(".");
+  if (lastDot > absTarget.lastIndexOf(path.sep)) {
+    const stripped = absTarget.slice(0, lastDot);
+    if (candidateSet.has(stripped)) return stripped;
+    for (const ext of RESOLVABLE_EXTENSIONS) {
+      const swapped = stripped + ext;
+      if (candidateSet.has(swapped)) return swapped;
+    }
+  }
+
+  for (const basename of INDEX_BASENAMES) {
+    const indexPath = path.join(absTarget, basename);
+    if (candidateSet.has(indexPath)) return indexPath;
+  }
+
+  return null;
+}
+
+function detectRole(filePath) {
+  const lower = filePath.toLowerCase();
+  if (/(schema|migration|entity|model|drizzle|prisma)/.test(lower)) return "schema";
+  if (/(api|controller|route|endpoint|handler|service)/.test(lower)) return "api";
+  if (/(ui|component|view|page|screen|widget)/.test(lower)) return "ui";
+  if (/(test|spec|__tests__)/.test(lower)) return "test";
+  return "lib";
+}
+
+function buildGraph(files, projectRoot) {
+  const absFiles = files.map((f) => path.isAbsolute(f) ? f : path.resolve(projectRoot, f));
+  const candidateSet = new Set(absFiles);
+  const graph = new Map();
+
+  for (const absFile of absFiles) {
+    graph.set(absFile, new Set());
+    let content;
+    try {
+      content = fs.readFileSync(absFile, "utf8");
+    } catch {
+      continue;
+    }
+    const imports = extractImports(content);
+    for (const imp of imports) {
+      const resolved = resolveImport(imp, absFile, projectRoot, candidateSet);
+      if (resolved && resolved !== absFile) {
+        graph.get(absFile).add(resolved);
+      }
+    }
+  }
+
+  return { graph, absFiles };
+}
+
+function topologicalWaves(graph) {
+  const indegree = new Map();
+  const dependents = new Map();
+
+  for (const node of graph.keys()) {
+    indegree.set(node, 0);
+    dependents.set(node, new Set());
+  }
+
+  for (const [node, deps] of graph.entries()) {
+    for (const dep of deps) {
+      if (graph.has(dep)) {
+        indegree.set(node, (indegree.get(node) || 0) + 1);
+        dependents.get(dep).add(node);
+      }
+    }
+  }
+
+  const waves = [];
+  const visited = new Set();
+  let currentWave = [...indegree.entries()].filter(([, deg]) => deg === 0).map(([node]) => node);
+
+  while (currentWave.length > 0) {
+    waves.push(currentWave);
+    for (const node of currentWave) visited.add(node);
+    const nextWave = [];
+    for (const node of currentWave) {
+      for (const dependent of dependents.get(node) || []) {
+        const newDeg = indegree.get(dependent) - 1;
+        indegree.set(dependent, newDeg);
+        if (newDeg === 0 && !visited.has(dependent)) {
+          nextWave.push(dependent);
+        }
+      }
+    }
+    currentWave = nextWave;
+  }
+
+  if (visited.size < graph.size) {
+    const stuck = [...graph.keys()].filter((n) => !visited.has(n));
+    return { error: "cyclic-dependency", cycle: stuck };
+  }
+
+  return { waves };
+}
+
+function toRelative(abs, projectRoot) {
+  try {
+    return path.relative(projectRoot, abs).replace(/\\/g, "/");
+  } catch {
+    return abs;
+  }
+}
+
+async function main() {
+  try {
+    const raw = await readStdin();
+    if (!raw.trim()) {
+      process.stdout.write(JSON.stringify({ error: "empty-input" }));
+      return;
+    }
+    const { files, projectRoot = process.cwd() } = JSON.parse(raw);
+
+    if (!Array.isArray(files) || files.length === 0) {
+      process.stdout.write(JSON.stringify({ error: "empty-input" }));
+      return;
+    }
+
+    const rootAbs = path.isAbsolute(projectRoot) ? projectRoot : path.resolve(projectRoot);
+    const { graph } = buildGraph(files, rootAbs);
+    const result = topologicalWaves(graph);
+
+    if (result.error) {
+      const cycle = (result.cycle || []).map((f) => toRelative(f, rootAbs));
+      process.stdout.write(JSON.stringify({ error: result.error, cycle }));
+      return;
+    }
+
+    const waves = result.waves.map((waveFiles, idx) => {
+      const relFiles = waveFiles.map((f) => toRelative(f, rootAbs));
+      const roles = [...new Set(relFiles.map(detectRole))];
+      return {
+        wave: idx + 1,
+        files: relFiles,
+        roles,
+        dependsOn: idx === 0 ? [] : [idx],
+      };
+    });
+
+    const widestWave = waves.reduce((max, w) => Math.max(max, w.files.length), 0);
+
+    process.stdout.write(JSON.stringify({
+      waves,
+      metadata: {
+        totalWaves: waves.length,
+        totalFiles: files.length,
+        widestWave,
+      },
+    }));
+  } catch (_err) {
+    process.stdout.write(JSON.stringify({ error: "error-fallback" }));
+  }
+}
+
+main();