mustard-claude 3.1.35 → 3.1.36

package/package.json

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

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

@@ -124,6 +124,7 @@ Dispatch 1 Haiku Task(Explore) to verify work is still needed. Pre-check via `rt
 ### EXECUTE Phase (Light scope — same session)
 
 When user chooses "Approve and implement now":
+0. **Pre-EXECUTE Rewave Check:** Run `node .claude/scripts/exec-rewave-check.js --spec .claude/spec/active/{spec-name}/spec.md`. Parse JSON output. If `action: "decomposed"`, the spec was just split into N waves — proceed using wave-1's spec (`wave-1-{role}/spec.md`) instead of the original. If `action: "keep-single"` or `"skip"`, continue with the original spec normally. Silent operation — no AskUserQuestion.
 1. Update spec: `Status: implementing`, `Phase: EXECUTE`. Every agent prompt MUST include: `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 `.claude/pipeline-config.md` for agent config. Grep `entity-registry.json` for specific entity block only

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

@@ -84,6 +84,8 @@ Run `node .claude/scripts/diff-context.js --subproject {subproject_path}` per su
 
 **CRITICAL: Main context IS the Pipeline Runner. NEVER delegate to intermediate Task agent.**
 
+11b. **Pre-EXECUTE Rewave Check** (skip if `pipeline-state.isWavePlan === true`): Run `node .claude/scripts/exec-rewave-check.js --spec .claude/spec/active/{specName}/spec.md`. Parse JSON output. If `action: "decomposed"`, the spec was split into N waves — update `pipeline-state.isWavePlan: true, currentWave: 1` and proceed using wave-1's spec (`wave-1-{role}/spec.md`). If `action: "keep-single"` or `"skip"`, continue with the original spec. Silent — no AskUserQuestion.
+
 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 `[ ]`.
 

package/templates/hooks/__tests__/exec-rewave-check.test.js

@@ -0,0 +1,203 @@
+#!/usr/bin/env node
+"use strict";
+
+/**
+ * Tests for exec-rewave-check.js
+ * Run: node --test .claude/hooks/__tests__/exec-rewave-check.test.js
+ */
+
+const { describe, it } = require("node:test");
+const assert = require("node:assert/strict");
+const fs = require("node:fs");
+const os = require("node:os");
+const path = require("node:path");
+const { spawnSync } = require("node:child_process");
+
+const SCRIPT = path.resolve(__dirname, "..", "..", "scripts", "exec-rewave-check.js");
+
+// ── helpers ────────────────────────────────────────────────────────────────────
+
+function makeTempProject() {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), "mustard-rewave-"));
+  fs.mkdirSync(path.join(dir, ".claude", ".pipeline-states"), { recursive: true });
+  fs.mkdirSync(path.join(dir, ".claude", "spec", "active"), { recursive: true });
+  return dir;
+}
+
+function makeSpec(projectDir, specName, filesSection, extra = "") {
+  const specDir = path.join(projectDir, ".claude", "spec", "active", specName);
+  fs.mkdirSync(specDir, { recursive: true });
+  const specText = `# Feature: ${specName}
+### Status: approved | Phase: PLAN | Scope: full
+
+## Summary
+Test feature.
+
+${filesSection}
+
+## Tasks
+- [ ] Implement thing
+
+## Acceptance Criteria
+- [ ] AC-1: build passes — Command: \`node -e "process.exit(0)"\`
+${extra}`;
+  fs.writeFileSync(path.join(specDir, "spec.md"), specText, "utf8");
+  return specDir;
+}
+
+function writePipelineState(projectDir, specName, state) {
+  const file = path.join(projectDir, ".claude", ".pipeline-states", `${specName}.json`);
+  fs.writeFileSync(file, JSON.stringify(state, null, 2), "utf8");
+}
+
+function run(projectDir, specRelPath) {
+  const result = spawnSync(
+    process.execPath,
+    [SCRIPT, "--spec", specRelPath],
+    {
+      cwd: projectDir,
+      encoding: "utf8",
+      timeout: 20000,
+      env: { ...process.env, MUSTARD_DISABLED_HOOKS: "all" },
+    }
+  );
+  let parsed = null;
+  try { parsed = JSON.parse(result.stdout.trim()); } catch (_) {}
+  return { code: result.status, stdout: result.stdout.trim(), parsed };
+}
+
+function cleanup(dir) {
+  try { fs.rmSync(dir, { recursive: true, force: true }); } catch (_) {}
+}
+
+// ── test 1: single-layer spec → keep-single ────────────────────────────────────
+
+describe("exec-rewave-check", () => {
+  it("single-layer (all api): keep-single with reason single-layer", (t) => {
+    const proj = makeTempProject();
+    t.after(() => cleanup(proj));
+    const specName = "2026-01-01-test-single";
+    const filesSection = `## Files
+- src/api/users.ts
+- src/api/orders.ts
+- src/api/helpers.ts`;
+    makeSpec(proj, specName, filesSection);
+    const specPath = `.claude/spec/active/${specName}/spec.md`;
+
+    const { parsed } = run(proj, specPath);
+    assert.ok(parsed, "output must be valid JSON");
+    assert.equal(parsed.action, "keep-single");
+    assert.equal(parsed.reason, "single-layer");
+  });
+
+  // ── test 2: multi-layer spec → decomposed ──────────────────────────────────
+  it("multi-layer (schema + api): decomposed into 2 waves", (t) => {
+    const proj = makeTempProject();
+    t.after(() => cleanup(proj));
+    const specName = "2026-01-02-test-multi";
+    // wave-dependency works on real files; for DAG we need actual files on disk
+    // Create the files so the DAG parser can read them (no imports → each in own wave)
+    const apiDir = path.join(proj, "src", "api");
+    const schemaDir = path.join(proj, "src", "schema");
+    fs.mkdirSync(apiDir, { recursive: true });
+    fs.mkdirSync(schemaDir, { recursive: true });
+    // schema file — no imports
+    fs.writeFileSync(path.join(schemaDir, "user.ts"), "export const users = {};\n", "utf8");
+    // api file — imports from schema
+    fs.writeFileSync(path.join(apiDir, "users.ts"), 'import { users } from "../schema/user";\n', "utf8");
+
+    const filesSection = `## Files
+- src/schema/user.ts
+- src/api/users.ts`;
+    makeSpec(proj, specName, filesSection);
+    writePipelineState(proj, specName, { specName, status: "approved", phase: 2 });
+
+    const specPath = `.claude/spec/active/${specName}/spec.md`;
+    const { parsed } = run(proj, specPath);
+    assert.ok(parsed, "output must be valid JSON");
+
+    if (parsed.action === "decomposed") {
+      assert.equal(parsed.action, "decomposed");
+      assert.ok(parsed.totalWaves >= 2, `expected >=2 waves, got ${parsed.totalWaves}`);
+
+      // wave-plan.md created
+      const specDir = path.join(proj, ".claude", "spec", "active", specName);
+      assert.ok(fs.existsSync(path.join(specDir, "wave-plan.md")), "wave-plan.md must exist");
+
+      // spec.original.md created
+      assert.ok(fs.existsSync(path.join(specDir, "spec.original.md")), "spec.original.md must exist");
+
+      // per-wave spec.md dirs created
+      for (const w of parsed.waves) {
+        const waveDir = path.join(specDir, `wave-${w.wave}-${w.role}`);
+        assert.ok(fs.existsSync(path.join(waveDir, "spec.md")), `wave-${w.wave} spec.md must exist`);
+      }
+
+      // pipeline-state updated
+      const stateFile = path.join(proj, ".claude", ".pipeline-states", `${specName}.json`);
+      const state = JSON.parse(fs.readFileSync(stateFile, "utf8"));
+      assert.equal(state.isWavePlan, true);
+      assert.ok(state.totalWaves >= 2);
+      assert.deepEqual(state.completedWaves, []);
+      assert.equal(state.rewaveSource, "exec-entry");
+    } else {
+      // DAG had no real depth (both files in same wave) → keep-single is acceptable
+      assert.equal(parsed.action, "keep-single");
+    }
+  });
+
+  // ── test 3: spec with existing wave-plan.md → skip already-decomposed ────────
+  it("already-decomposed (wave-plan.md exists): skip", (t) => {
+    const proj = makeTempProject();
+    t.after(() => cleanup(proj));
+    const specName = "2026-01-03-test-already";
+    const filesSection = `## Files
+- src/schema/thing.ts
+- src/api/thing.ts`;
+    const specDir = makeSpec(proj, specName, filesSection);
+    // Plant a wave-plan.md
+    fs.writeFileSync(path.join(specDir, "wave-plan.md"), "# Wave Plan\n", "utf8");
+
+    const { parsed } = run(proj, `.claude/spec/active/${specName}/spec.md`);
+    assert.ok(parsed);
+    assert.equal(parsed.action, "skip");
+    assert.equal(parsed.reason, "already-decomposed");
+  });
+
+  // ── test 4: pipeline-state.scopeOverride = user-rejected-waves → skip ────────
+  it("scopeOverride user-rejected-waves: skip", (t) => {
+    const proj = makeTempProject();
+    t.after(() => cleanup(proj));
+    const specName = "2026-01-04-test-rejected";
+    const filesSection = `## Files
+- src/schema/x.ts
+- src/api/x.ts`;
+    makeSpec(proj, specName, filesSection);
+    writePipelineState(proj, specName, {
+      specName,
+      status: "approved",
+      phase: 2,
+      scopeOverride: "user-rejected-waves",
+    });
+
+    const { parsed } = run(proj, `.claude/spec/active/${specName}/spec.md`);
+    assert.ok(parsed);
+    assert.equal(parsed.action, "skip");
+    assert.equal(parsed.reason, "user-rejected");
+  });
+
+  // ── test 5: spec with no ## Files section → skip error-fallback ───────────────
+  it("spec without ## Files: skip error-fallback", (t) => {
+    const proj = makeTempProject();
+    t.after(() => cleanup(proj));
+    const specName = "2026-01-05-test-nofiles";
+    const specDir = path.join(proj, ".claude", "spec", "active", specName);
+    fs.mkdirSync(specDir, { recursive: true });
+    fs.writeFileSync(path.join(specDir, "spec.md"), `# Feature\n## Summary\nSomething\n`, "utf8");
+
+    const { parsed } = run(proj, `.claude/spec/active/${specName}/spec.md`);
+    assert.ok(parsed);
+    assert.equal(parsed.action, "skip");
+    assert.equal(parsed.reason, "error-fallback");
+  });
+});

package/templates/hooks/__tests__/scope-decompose.test.js

@@ -0,0 +1,99 @@
+#!/usr/bin/env node
+/**
+ * Tests for scripts/scope-decompose.js.
+ * Run with: node --test templates/hooks/__tests__/scope-decompose.test.js
+ */
+
+const { describe, it } = require('node:test');
+const assert = require('node:assert/strict');
+const { spawn } = require('node:child_process');
+const path = require('node:path');
+
+const SCRIPT = path.resolve(__dirname, '..', '..', 'scripts', 'scope-decompose.js');
+
+function runScript(input) {
+  return new Promise((resolve, reject) => {
+    const child = spawn(process.execPath, [SCRIPT], {
+      stdio: ['pipe', 'pipe', 'pipe'],
+    });
+
+    let stdout = '';
+    let stderr = '';
+
+    child.stdout.on('data', d => (stdout += d));
+    child.stderr.on('data', d => (stderr += d));
+    child.on('error', reject);
+    child.on('close', code => {
+      let parsed = null;
+      if (stdout.trim()) {
+        try { parsed = JSON.parse(stdout.trim()); } catch (_) {}
+      }
+      resolve({ code, stdout: stdout.trim(), stderr: stderr.trim(), parsed });
+    });
+
+    const payload = typeof input === 'string' ? input : JSON.stringify(input);
+    child.stdin.write(payload);
+    child.stdin.end();
+  });
+}
+
+describe('scope-decompose decision logic', () => {
+  it('single layer with few files → decompose:false reason:single-layer', async () => {
+    const r = await runScript({ fileCount: 3, layerCount: 1, newEntityCount: 0, knowledgeMatches: [] });
+    assert.equal(r.code, 0);
+    assert.equal(r.parsed.decompose, false);
+    assert.equal(r.parsed.reason, 'single-layer');
+    assert.equal(r.parsed.signals.fileCount, 3);
+    assert.equal(r.parsed.signals.layerCount, 1);
+  });
+
+  it('two layers with few files → decompose:true reason:multi-layer', async () => {
+    const r = await runScript({ fileCount: 3, layerCount: 2, newEntityCount: 1, knowledgeMatches: [] });
+    assert.equal(r.code, 0);
+    assert.equal(r.parsed.decompose, true);
+    assert.equal(r.parsed.reason, 'multi-layer');
+  });
+
+  it('three layers with few files → decompose:true reason:multi-layer', async () => {
+    const r = await runScript({ fileCount: 3, layerCount: 3, newEntityCount: 0, knowledgeMatches: [] });
+    assert.equal(r.code, 0);
+    assert.equal(r.parsed.decompose, true);
+    assert.equal(r.parsed.reason, 'multi-layer');
+  });
+
+  it('historical knowledge match → decompose:true reason:history-match', async () => {
+    const r = await runScript({
+      fileCount: 1,
+      layerCount: 1,
+      newEntityCount: 0,
+      knowledgeMatches: [{ id: 'heavy-pipeline-x', type: 'heavy-pipeline', scope: {} }],
+    });
+    assert.equal(r.code, 0);
+    assert.equal(r.parsed.decompose, true);
+    assert.match(r.parsed.reason, /^history-match:/);
+    assert.equal(r.parsed.reason, 'history-match:heavy-pipeline-x');
+    assert.equal(r.parsed.signals.historicalMatches, 1);
+  });
+
+  it('wide spec single layer with new entities → decompose:true reason:wide-and-new-entities', async () => {
+    const r = await runScript({ fileCount: 15, layerCount: 1, newEntityCount: 2, knowledgeMatches: [] });
+    assert.equal(r.code, 0);
+    assert.equal(r.parsed.decompose, true);
+    assert.equal(r.parsed.reason, 'wide-and-new-entities');
+  });
+
+  it('empty input → fail-open decompose:false', async () => {
+    const r = await runScript('');
+    assert.equal(r.code, 0);
+    assert.equal(r.parsed.decompose, false);
+    // empty signals defaults: layerCount=0 → single-layer branch
+    assert.equal(r.parsed.reason, 'single-layer');
+  });
+
+  it('invalid JSON input → error-fallback', async () => {
+    const r = await runScript('{not-json');
+    assert.equal(r.code, 0);
+    assert.equal(r.parsed.decompose, false);
+    assert.equal(r.parsed.reason, 'error-fallback');
+  });
+});

package/templates/refs/feature/wave-decomposition.md

@@ -10,10 +10,12 @@ Before writing the single spec in Full scope, check whether the work should be d
 
 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)
+   - `layerCount` — distinct layers (use role detection derived from paths: schema/api/ui/lib). **`layerCount >= 2` is sufficient to trigger decomposition** regardless of fileCount.
    - `newEntityCount` — new entities created by this spec
    - `estimatedTouchPoints` — count of imports/refs from Grep on affected directories (optional)
 
+   Decomposition reasons emitted: `history-match:{id}`, `multi-layer`, `wide-and-new-entities`. Single-layer specs return `decompose: false` with reason `single-layer`.
+
 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:**

package/templates/scripts/exec-rewave-check.js

@@ -0,0 +1,304 @@
+#!/usr/bin/env node
+"use strict";
+
+/**
+ * exec-rewave-check.js
+ *
+ * Pre-EXECUTE re-check: silently decomposes a single-spec into waves if signals
+ * (layerCount >= 2) are found in the finalised spec's ## Files section.
+ *
+ * CLI:
+ *   node .claude/scripts/exec-rewave-check.js --spec .claude/spec/active/{name}/spec.md
+ *
+ * Output: one JSON line on stdout, always exit 0 (fail-open).
+ *   { action: "skip",        reason: "already-decomposed" | "user-rejected" | "no-spec-arg" | "error-fallback", error? }
+ *   { action: "keep-single", reason: "single-layer" | "no-dag-depth-or-error" | ..., signals? }
+ *   { action: "decomposed",  totalWaves: N, waves: [{wave, role, files: count}, ...] }
+ */
+
+const fs = require("fs");
+const path = require("path");
+const { spawnSync } = require("child_process");
+
+// ── role detection (mirrors wave-dependency.js:101-108) ──────────────────────
+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 emit(obj) {
+  process.stdout.write(JSON.stringify(obj) + "\n");
+}
+
+// ── parse ## Files section from spec text ────────────────────────────────────
+function parseFiles(specText) {
+  const lines = specText.split("\n");
+  const start = lines.findIndex((l) => /^##\s+Files/.test(l));
+  if (start === -1) return null;
+
+  const paths = [];
+  for (let i = start + 1; i < lines.length; i++) {
+    const line = lines[i].trim();
+    if (/^##\s/.test(line)) break; // next section
+    // match "- path" or "- `path`" bullets
+    const m = line.match(/^-\s+`?([^\s`]+)`?/);
+    if (m && m[1] && !m[1].startsWith("#")) {
+      paths.push(m[1]);
+    }
+  }
+  return paths;
+}
+
+// ── extract optional newEntityCount from spec ─────────────────────────────────
+function parseNewEntityCount(specText) {
+  const m = specText.match(/new\s+entities?:\s*(\d+)/i) ||
+            specText.match(/newEntityCount[:\s]+(\d+)/i);
+  return m ? parseInt(m[1], 10) : 0;
+}
+
+// ── locate pipeline state ─────────────────────────────────────────────────────
+function findPipelineState(specDir, projectRoot) {
+  const specName = path.basename(specDir);
+  const statesDir = path.join(projectRoot, ".claude", ".pipeline-states");
+  const stateFile = path.join(statesDir, `${specName}.json`);
+  try {
+    const raw = fs.readFileSync(stateFile, "utf8");
+    return { file: stateFile, state: JSON.parse(raw) };
+  } catch {
+    return { file: stateFile, state: null };
+  }
+}
+
+// ── call scope-decompose.js ───────────────────────────────────────────────────
+function runScopeDecompose(signals, scriptsDir) {
+  const scriptPath = path.join(scriptsDir, "scope-decompose.js");
+  const result = spawnSync(process.execPath, [scriptPath], {
+    input: JSON.stringify(signals),
+    encoding: "utf8",
+    timeout: 10000,
+  });
+  if (result.status !== 0 || result.error) return null;
+  try {
+    return JSON.parse(result.stdout.trim());
+  } catch {
+    return null;
+  }
+}
+
+// ── call wave-dependency.js ───────────────────────────────────────────────────
+function runWaveDependency(files, projectRoot, scriptsDir) {
+  const scriptPath = path.join(scriptsDir, "wave-dependency.js");
+  const result = spawnSync(process.execPath, [scriptPath], {
+    input: JSON.stringify({ files, projectRoot }),
+    encoding: "utf8",
+    cwd: projectRoot,
+    timeout: 15000,
+  });
+  if (result.status !== 0 || result.error) return null;
+  try {
+    return JSON.parse(result.stdout.trim());
+  } catch {
+    return null;
+  }
+}
+
+// ── generate wave-plan.md content ─────────────────────────────────────────────
+function buildWavePlanMd(specName, wavesResult, specText, decomposeReason) {
+  const now = new Date().toISOString();
+  const summaryMatch = specText.match(/^##\s+Summary\s*\n([\s\S]*?)(?=\n##\s)/m);
+  const summary = summaryMatch ? summaryMatch[1].trim() : "(see spec)";
+
+  const waveLines = wavesResult.waves.map((w) => {
+    const depends = w.dependsOn.length === 0 ? "none" : w.dependsOn.map((d) => `wave ${d}`).join(", ");
+    return `### Wave ${w.wave} — ${w.roles.join("/")}
+Depends on: ${depends}
+Files (${w.files.length}): ${w.files.join(", ")}`;
+  }).join("\n\n");
+
+  return `<!-- mustard:generated -->
+# Wave Plan: ${specName}
+### Status: draft | Phase: EXECUTE | Scope: full | Decomposed: yes
+### Checkpoint: ${now}
+### Reason: ${decomposeReason}
+### Source: exec-rewave-check (re-evaluated at EXECUTE entry)
+
+## Summary
+${summary}
+
+## Waves
+${waveLines}
+
+## Rationale
+Decomposed at EXECUTE entry by exec-rewave-check.js.
+Threshold: layerCount >= 2 (reason: ${decomposeReason}).
+`;
+}
+
+// ── generate per-wave spec.md content ─────────────────────────────────────────
+function buildWaveSpecMd(parentSpecText, waveFiles, waveNum, waveRole, wavePlanRelPath) {
+  // Extract Summary
+  const summaryMatch = parentSpecText.match(/^##\s+Summary\s*\n([\s\S]*?)(?=\n##\s)/m);
+  const summary = summaryMatch ? summaryMatch[1].trim() : "(see parent spec)";
+
+  // Extract Tasks section (copy entirely — agent will filter)
+  const tasksMatch = parentSpecText.match(/^##\s+Tasks\s*\n([\s\S]*?)(?=\n##\s|\s*$)/m);
+  const tasks = tasksMatch ? tasksMatch[1].trim() : "";
+
+  const fileList = waveFiles.map((f) => `- ${f}`).join("\n");
+
+  return `<!-- mustard:generated -->
+> Wave spec — see [../wave-plan.md](${wavePlanRelPath}) for overall plan.
+
+# Wave ${waveNum} — ${waveRole}
+
+## Summary
+${summary}
+
+## Files
+${fileList}
+
+## Tasks
+${tasks}
+`;
+}
+
+// ── main ──────────────────────────────────────────────────────────────────────
+function main() {
+  const args = process.argv.slice(2);
+  const specArgIdx = args.indexOf("--spec");
+  if (specArgIdx === -1 || !args[specArgIdx + 1]) {
+    emit({ action: "skip", reason: "no-spec-arg" });
+    return;
+  }
+
+  const specArg = args[specArgIdx + 1];
+  // Resolve spec path relative to cwd
+  const specFile = path.isAbsolute(specArg) ? specArg : path.resolve(process.cwd(), specArg);
+  const specDir = path.dirname(specFile);
+  // scriptsDir = same dir as this script
+  const scriptsDir = path.dirname(path.resolve(__filename));
+  // projectRoot = walk up until we find .claude dir (or fallback to cwd)
+  const projectRoot = findProjectRoot(specDir) || process.cwd();
+
+  try {
+    // 1. Read spec
+    let specText;
+    try {
+      specText = fs.readFileSync(specFile, "utf8");
+    } catch {
+      emit({ action: "skip", reason: "error-fallback", error: "spec-not-readable" });
+      return;
+    }
+
+    const specName = path.basename(specDir);
+
+    // 2. Skip if already decomposed (wave-plan.md exists in same dir)
+    const wavePlanPath = path.join(specDir, "wave-plan.md");
+    if (fs.existsSync(wavePlanPath)) {
+      emit({ action: "skip", reason: "already-decomposed" });
+      return;
+    }
+
+    // 3. Skip if pipeline-state says so
+    const { file: stateFile, state } = findPipelineState(specDir, projectRoot);
+    if (state) {
+      if (state.isWavePlan === true) {
+        emit({ action: "skip", reason: "already-decomposed" });
+        return;
+      }
+      if (state.scopeOverride === "user-rejected-waves") {
+        emit({ action: "skip", reason: "user-rejected" });
+        return;
+      }
+    }
+
+    // 4. Parse ## Files
+    const filePaths = parseFiles(specText);
+    if (!filePaths || filePaths.length === 0) {
+      emit({ action: "skip", reason: "error-fallback", error: "no-files-section" });
+      return;
+    }
+
+    // 5. Compute layerCount (unique roles, lib-only = 1 layer)
+    const roles = filePaths.map(detectRole);
+    const uniqueRoles = new Set(roles);
+    // If only "lib" → 1 layer; otherwise count all unique roles
+    const layerCount = (uniqueRoles.size === 1 && uniqueRoles.has("lib")) ? 1 : uniqueRoles.size;
+    const fileCount = filePaths.length;
+    const newEntityCount = parseNewEntityCount(specText);
+
+    // 6. Call scope-decompose.js
+    const signals = { fileCount, layerCount, newEntityCount, knowledgeMatches: [] };
+    const decision = runScopeDecompose(signals, scriptsDir);
+
+    if (!decision || decision.decompose === false) {
+      const reason = decision ? decision.reason : "error-fallback";
+      emit({ action: "keep-single", reason, signals });
+      return;
+    }
+
+    // 7. decompose: true — call wave-dependency.js
+    const dagResult = runWaveDependency(filePaths, projectRoot, scriptsDir);
+
+    if (!dagResult || dagResult.error || !Array.isArray(dagResult.waves) || dagResult.waves.length < 2) {
+      emit({ action: "keep-single", reason: "no-dag-depth-or-error", signals });
+      return;
+    }
+
+    // 8. Write wave structure
+    const wavePlanContent = buildWavePlanMd(specName, dagResult, specText, decision.reason);
+    fs.writeFileSync(wavePlanPath, wavePlanContent, "utf8");
+
+    const wavesMeta = [];
+    for (const w of dagResult.waves) {
+      const primaryRole = w.roles[0] || "lib";
+      const waveDir = path.join(specDir, `wave-${w.wave}-${primaryRole}`);
+      fs.mkdirSync(waveDir, { recursive: true });
+      const waveSpecPath = path.join(waveDir, "spec.md");
+      const waveSpecContent = buildWaveSpecMd(specText, w.files, w.wave, w.roles.join("/"), "../wave-plan.md");
+      fs.writeFileSync(waveSpecPath, waveSpecContent, "utf8");
+      wavesMeta.push({ wave: w.wave, role: primaryRole, files: w.files.length });
+    }
+
+    // 9. Rename original spec to spec.original.md
+    const originalBackup = path.join(specDir, "spec.original.md");
+    fs.renameSync(specFile, originalBackup);
+
+    // 10. Update pipeline state
+    const updatedState = Object.assign({}, state || { specName }, {
+      specName,
+      isWavePlan: true,
+      currentWave: 1,
+      totalWaves: dagResult.waves.length,
+      completedWaves: [],
+      failedWaves: [],
+      rewaveSource: "exec-entry",
+      updatedAt: new Date().toISOString(),
+    });
+
+    const statesDir = path.join(projectRoot, ".claude", ".pipeline-states");
+    fs.mkdirSync(statesDir, { recursive: true });
+    fs.writeFileSync(stateFile, JSON.stringify(updatedState, null, 2), "utf8");
+
+    emit({ action: "decomposed", totalWaves: dagResult.waves.length, waves: wavesMeta });
+  } catch (err) {
+    emit({ action: "skip", reason: "error-fallback", error: err.message });
+  }
+}
+
+function findProjectRoot(startDir) {
+  let dir = startDir;
+  for (let i = 0; i < 10; i++) {
+    if (fs.existsSync(path.join(dir, ".claude"))) return dir;
+    const parent = path.dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  return null;
+}
+
+main();

package/templates/scripts/scope-decompose.js

@@ -49,14 +49,6 @@ function decide(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,
@@ -65,10 +57,10 @@ function decide(signals) {
     };
   }
 
-  if (layerCount >= 3) {
+  if (layerCount >= 2) {
     return {
       decompose: true,
-      reason: "deep-layers",
+      reason: "multi-layer",
       signals: { fileCount, layerCount, newEntityCount, estimatedTouchPoints, historicalMatches: 0 },
     };
   }
@@ -83,7 +75,7 @@ function decide(signals) {
 
   return {
     decompose: false,
-    reason: "below-thresholds",
+    reason: "single-layer",
     signals: { fileCount, layerCount, newEntityCount, estimatedTouchPoints, historicalMatches: 0 },
   };
 }

package/templates/skills/commit-workflow/SKILL.md

@@ -2,8 +2,8 @@
 name: commit-workflow
 description: Git commit strategy, submodule-aware, budget ≤15 API calls.
 disable-model-invocation: true
+source: manual
 ---
-<!-- mustard:generated -->
 
 # Commit Workflow
 

package/templates/skills/karpathy-guidelines/SKILL.md

@@ -4,7 +4,6 @@ description: Behavioral guidelines to reduce common LLM coding mistakes (think b
 license: MIT
 source: manual
 ---
-<!-- mustard:generated -->
 
 # Karpathy Guidelines