cclaw-cli 7.1.0 → 7.2.0

package/dist/artifact-linter/plan.js

@@ -8,6 +8,14 @@ import { PLAN_SPLIT_SMALL_PLAN_THRESHOLD, parseImplementationUnits, parseImpleme
 const PARALLEL_EXEC_MANAGED_START = "<!-- parallel-exec-managed-start -->";
 const PARALLEL_EXEC_MANAGED_END = "<!-- parallel-exec-managed-end -->";
 const TASK_ID_PATTERN = /\bT-\d{3}[a-z]?(?:\.\d{1,3})?\b/giu;
+const PLAN_LANE_WHITELIST = new Set([
+    "production",
+    "test",
+    "docs",
+    "infra",
+    "scaffold",
+    "migration"
+]);
 /**
  * Extract every distinct T-NNN[a-z]?(.NNN)? id from a markdown body.
  *
@@ -36,6 +44,102 @@ function extractParallelExecManagedBody(planMarkdown) {
     }
     return planMarkdown.slice(startIdx + PARALLEL_EXEC_MANAGED_START.length, endIdx);
 }
+function normalizePathToken(raw) {
+    return raw.trim().replace(/^`|`$/gu, "").replace(/^\.\/+/u, "");
+}
+function parsePipeRow(trimmedLine) {
+    const inner = trimmedLine.replace(/^\|/u, "").replace(/\|\s*$/u, "");
+    return inner.split("|").map((cell) => cell.trim());
+}
+function headerIndexByName(cells) {
+    const map = new Map();
+    for (let i = 0; i < cells.length; i += 1) {
+        const key = cells[i].toLowerCase().replace(/[^a-z0-9]/gu, "");
+        if (key.length > 0 && !map.has(key)) {
+            map.set(key, i);
+        }
+    }
+    return map;
+}
+function parseParallelWaveTableMetadata(planMarkdown) {
+    const body = extractParallelExecManagedBody(planMarkdown);
+    if (body.trim().length === 0)
+        return [];
+    const lines = body.split(/\r?\n/u);
+    const out = [];
+    let current = null;
+    let headerIdx = null;
+    const flush = () => {
+        if (current)
+            out.push(current);
+    };
+    for (const rawLine of lines) {
+        const trimmed = rawLine.trim();
+        const waveMatch = /^###\s+Wave\s+(?:W-)?(\d+)\b/iu.exec(trimmed);
+        if (waveMatch) {
+            flush();
+            current = {
+                waveId: `W-${waveMatch[1].padStart(2, "0")}`,
+                rows: [],
+                notes: []
+            };
+            headerIdx = null;
+            continue;
+        }
+        if (!current)
+            continue;
+        current.notes.push(trimmed);
+        if (!trimmed.startsWith("|"))
+            continue;
+        const cells = parsePipeRow(trimmed);
+        if (cells.length === 0)
+            continue;
+        const first = cells[0].toLowerCase();
+        const isHeader = first === "sliceid" || first === "slice id";
+        if (isHeader) {
+            headerIdx = headerIndexByName(cells);
+            continue;
+        }
+        if (cells.every((cell) => /^:?-{3,}:?$/u.test(cell))) {
+            continue;
+        }
+        const sliceCell = cells[0];
+        if (!/^S-\d+$/iu.test(sliceCell))
+            continue;
+        const idx = headerIdx ?? new Map();
+        const unitIdx = idx.get("unit") ?? idx.get("taskid") ?? 1;
+        const pathsIdx = idx.get("claimedpaths");
+        const parallelizableIdx = idx.get("parallelizable");
+        const laneIdx = idx.get("lane");
+        const rawPaths = pathsIdx !== undefined ? (cells[pathsIdx] ?? "") : "";
+        const claimedPaths = rawPaths.length === 0
+            ? []
+            : rawPaths
+                .split(",")
+                .map((p) => normalizePathToken(p))
+                .filter((p) => p.length > 0);
+        const rawParallel = parallelizableIdx !== undefined ? (cells[parallelizableIdx] ?? "").toLowerCase() : "";
+        let parallelizable = null;
+        if (rawParallel === "true" || rawParallel === "yes")
+            parallelizable = true;
+        if (rawParallel === "false" || rawParallel === "no")
+            parallelizable = false;
+        const laneRaw = laneIdx !== undefined ? (cells[laneIdx] ?? "").trim().toLowerCase() : "";
+        current.rows.push({
+            sliceId: sliceCell.toUpperCase(),
+            unit: (cells[unitIdx] ?? "").trim(),
+            claimedPaths,
+            parallelizable,
+            lane: laneRaw.length > 0 ? laneRaw : null
+        });
+    }
+    flush();
+    return out;
+}
+function waveHasSequentialModeHint(wave) {
+    const noteText = wave.notes.join("\n").toLowerCase();
+    return /mode\s*:\s*sequential/iu.test(noteText) || /\bsequential\b/iu.test(noteText) || /\bserial\b/iu.test(noteText);
+}
 export async function lintPlanStage(ctx) {
     const { projectRoot, track, raw, absFile, sections, findings, parsedFrontmatter, brainstormShortCircuitBody, brainstormShortCircuitActivated, staleDiagramAuditEnabled, isTrivialOverride } = ctx;
     evaluateInvestigationTrace(ctx, "Implementation Units");
@@ -308,7 +412,8 @@ export async function lintPlanStage(ctx) {
                 : "Parallel-ready units detected or plan is single-unit."
         });
     }
-    // plan_parallel_exec_full_coverage: every T-NNN task listed in the
+    // plan_parallel_exec_full_coverage + atomic wave metadata checks.
+    // Every T-NNN task listed in the
     // plan's Task List must be assigned to a slice inside the
     // <!-- parallel-exec-managed-start --> block. Without this, TDD
     // cannot fan out work the plan never authored as waves; the previous
@@ -355,5 +460,86 @@ export async function lintPlanStage(ctx) {
                         ? `Parallel Execution Plan covers all ${authoredTaskIds.size} authored task id(s); ${deferredIds.size} task id(s) are explicitly deferred.`
                         : `Uncovered task id(s) — author waves for: ${uncovered.slice(0, 25).join(", ")}${uncovered.length > 25 ? `, … (${uncovered.length - 25} more)` : ""}. Either add slices for them inside <!-- parallel-exec-managed-start --> or move them under \`## Deferred Tasks\` with a reason.`
         });
+        const waveMeta = parseParallelWaveTableMetadata(raw);
+        const pathConflicts = [];
+        for (const wave of waveMeta) {
+            const rows = wave.rows;
+            for (let i = 0; i < rows.length; i += 1) {
+                for (let j = i + 1; j < rows.length; j += 1) {
+                    const left = rows[i];
+                    const right = rows[j];
+                    const rightPathSet = new Set(right.claimedPaths);
+                    const overlap = left.claimedPaths.filter((p) => rightPathSet.has(p));
+                    if (overlap.length === 0)
+                        continue;
+                    pathConflicts.push(`${wave.waveId} ${left.sliceId}<->${right.sliceId} overlap: ${overlap.join(", ")}`);
+                }
+            }
+        }
+        findings.push({
+            section: "plan_wave_paths_disjoint",
+            required: taskListPresent,
+            rule: "Slices within the same wave must keep `claimedPaths` disjoint so TDD can safely fan out parallel slice-builders.",
+            found: taskListPresent && blockPresent && pathConflicts.length === 0,
+            details: !taskListPresent
+                ? "Task List section is empty or missing T-NNN ids; disjoint-path wave check skipped."
+                : !blockPresent
+                    ? "`<!-- parallel-exec-managed-start -->` block is missing or empty; cannot validate wave path disjointness."
+                    : pathConflicts.length === 0
+                        ? "All parsed same-wave slice rows have disjoint claimedPaths."
+                        : `Overlapping claimedPaths detected: ${pathConflicts.slice(0, 12).join(" | ")}${pathConflicts.length > 12 ? ` | … (${pathConflicts.length - 12} more)` : ""}.`
+        });
+        const invalidLanes = [];
+        for (const wave of waveMeta) {
+            for (const row of wave.rows) {
+                if (!row.lane)
+                    continue;
+                if (!PLAN_LANE_WHITELIST.has(row.lane)) {
+                    invalidLanes.push(`${wave.waveId}/${row.sliceId}:${row.lane}`);
+                }
+            }
+        }
+        findings.push({
+            section: "plan_lane_meaningful",
+            required: false,
+            rule: "When a lane is declared, it must be one of: production, test, docs, infra, scaffold, migration.",
+            found: invalidLanes.length === 0,
+            details: invalidLanes.length === 0
+                ? "All declared lane values are either omitted or in the approved lane whitelist."
+                : `Invalid lane value(s): ${invalidLanes.join(", ")}. Remove lane or use a whitelisted value.`
+        });
+        const inconsistentParallelizable = [];
+        for (const wave of waveMeta) {
+            const hasSerialSlice = wave.rows.some((row) => row.parallelizable === false);
+            if (!hasSerialSlice)
+                continue;
+            if (!waveHasSequentialModeHint(wave)) {
+                const serialSlices = wave.rows
+                    .filter((row) => row.parallelizable === false)
+                    .map((row) => row.sliceId)
+                    .join(", ");
+                inconsistentParallelizable.push(`${wave.waveId} [${serialSlices}]`);
+            }
+        }
+        findings.push({
+            section: "plan_parallelizable_consistency",
+            required: false,
+            rule: "Waves containing `parallelizable: false` slices should be explicitly marked sequential in wave notes/mode.",
+            found: inconsistentParallelizable.length === 0,
+            details: inconsistentParallelizable.length === 0
+                ? "No serial slices were found outside a sequentially-labeled wave context."
+                : `Serial slice(s) found without sequential wave mode hints in: ${inconsistentParallelizable.join(", ")}. Add a wave mode/note indicating sequential execution.`
+        });
+        const mermaidBlocks = raw.match(/```mermaid[\s\S]*?```/giu) ?? [];
+        const hasParallelExecMermaid = mermaidBlocks.some((block) => /(flowchart|gantt)/iu.test(block) && /\bW-\d+\b/iu.test(block) && /\bS-\d+\b/iu.test(block));
+        findings.push({
+            section: "plan_parallel_exec_mermaid_present",
+            required: false,
+            rule: "Plan should include a mermaid flowchart/gantt for parallel waves and slice dependencies to make fanout shape visually reviewable.",
+            found: hasParallelExecMermaid,
+            details: hasParallelExecMermaid
+                ? "Mermaid visualization for parallel execution waves is present."
+                : "No mermaid parallel-execution visualization found (advisory). Add a ` ```mermaid ` flowchart or gantt with W-* and S-* nodes."
+        });
     }
 }

package/dist/cli.d.ts

@@ -9,6 +9,7 @@ interface ParsedArgs {
     track?: FlowTrack;
     dryRun?: boolean;
     interactive?: boolean;
+    syncCheck?: boolean;
     archiveName?: string;
     archiveSkipRetro?: boolean;
     archiveSkipRetroReason?: string;

package/dist/cli.js

@@ -40,6 +40,7 @@ Commands:
   sync       Reconcile generated runtime files with the current config.
              Flags: --harnesses=<list>  Update configured harnesses before syncing.
                     --interactive      Pick harnesses from a numbered TTY menu.
+                    --check            Verify managed hook files are byte-identical to canonical generators.
   upgrade    Refresh generated files in .cclaw. Preserves your config.yaml.
   archive    Archive the active run and reset flow state for the next run.
              Flags: --name=<slug>        Override archive folder suffix.
@@ -57,6 +58,7 @@ Examples:
   npx cclaw-cli
   npx cclaw-cli init --harnesses=claude,cursor --no-interactive
   npx cclaw-cli sync --interactive
+  npx cclaw-cli sync --check
   npx cclaw-cli archive --name=my-run
   npx cclaw-cli archive --disposition=cancelled --reason="deprioritized"
   npx cclaw-cli upgrade
@@ -334,6 +336,7 @@ function parseArgs(argv) {
             return flag.startsWith("--harnesses=") ||
                 (parsed.command === "init" && flag.startsWith("--track=")) ||
                 (parsed.command === "init" && flag.startsWith("--profile=")) ||
+                (parsed.command === "sync" && flag === "--check") ||
                 flag === "--interactive" ||
                 flag === "--no-interactive" ||
                 (parsed.command === "init" && flag === "--dry-run");
@@ -374,6 +377,10 @@ function parseArgs(argv) {
             parsed.dryRun = true;
             continue;
         }
+        if (flag === "--check") {
+            parsed.syncCheck = true;
+            continue;
+        }
         if (flag.startsWith("--name=")) {
             parsed.archiveName = flag.replace("--name=", "").trim();
             continue;
@@ -446,6 +453,11 @@ async function runCommand(parsed, ctx) {
         return 0;
     }
     if (command === "sync") {
+        if (parsed.syncCheck === true) {
+            await syncCclaw(ctx.cwd, { check: true });
+            info(ctx, "Managed hook drift check passed (no sync required).");
+            return 0;
+        }
         const resolved = await resolveSyncInputs(parsed, ctx);
         await syncCclaw(ctx.cwd, { harnesses: resolved.harnesses });
         const harnessNote = resolved.harnesses ? ` (${resolved.harnesses.join(", ")})` : "";

package/dist/content/core-agents.js

@@ -97,7 +97,7 @@ node .cclaw/hooks/delegation-record.mjs \\
   --json
 \`\`\`
 
-Reuse the same \`<spanId>\` and \`<dispatchId>\` across both rows. **GREEN evidence freshness** (slice-builder): the FIRST \`--evidence-ref\` MUST (1) reference the same test the matching \`phase=red\` row cited (basename/stem substring; reject \`green_evidence_red_test_mismatch\`), (2) include a recognized passing-runner line such as \`=> N passed; 0 failed\`, \`N passed in 0.42s\`, or \`ok pkg 0.12s\` (reject \`green_evidence_passing_assertion_missing\`), AND (3) be captured AFTER \`ackTs\` of this span — \`completedTs - ackTs\` must be ≥ \`flow-state.json::tddGreenMinElapsedMs\` (default 4000ms; reject \`green_evidence_too_fresh\`). Escape clause for legitimate observational GREEN: pass BOTH \`--allow-fast-green --green-mode=observational\`. \`--ack-ts\` and \`--completed-ts\` must be monotonic on the span (\`startTs ≤ launchedTs ≤ ackTs ≤ completedTs\`); the helper rejects out-of-order writes with \`delegation_timestamp_non_monotonic\`. If the helper rejects with \`dispatch_active_span_collision\` against a stale span, surface the conflicting \`spanId\` to the parent — do NOT silently retry with \`--allow-parallel\`.`;
+Reuse the same \`<spanId>\` and \`<dispatchId>\` across both rows. **GREEN evidence freshness** (slice-builder): the FIRST \`--evidence-ref\` MUST (1) reference the same test the matching \`phase=red\` row cited (basename/stem substring; reject \`green_evidence_red_test_mismatch\`), (2) include a recognized passing-runner line such as \`=> N passed; 0 failed\`, \`N passed in 0.42s\`, or \`ok pkg 0.12s\` (reject \`green_evidence_passing_assertion_missing\`), AND (3) be captured AFTER \`ackTs\` of this span — \`completedTs - ackTs\` must be ≥ \`flow-state.json::tddGreenMinElapsedMs\` (default 4000ms; reject \`green_evidence_too_fresh\`). Escape clause for legitimate observational GREEN: pass \`--green-mode=observational\`. \`--ack-ts\` and \`--completed-ts\` must be monotonic on the span (\`startTs ≤ launchedTs ≤ ackTs ≤ completedTs\`); the helper rejects out-of-order writes with \`delegation_timestamp_non_monotonic\`. If the helper rejects with \`dispatch_active_span_collision\` against a stale span, surface the conflicting \`spanId\` to the parent — do NOT silently retry with \`--allow-parallel\`.`;
 }
 function formatReturnSchema(schema) {
     const lines = [

package/dist/content/hooks.js

@@ -334,19 +334,20 @@ function extractRedTestNameInline(redEvidenceRef) {
   return trimmed;
 }
 
-// Match canonical runner pass lines:
-//   cargo: "test result: ok. N passed; 0 failed"
-//   pytest: "===== N passed in 0.42s ====="
-//   go test: "ok   pkg   0.123s"
-//   npm/jest/vitest: "Tests:  N passed"
-// We accept a generic shape: "=> N passed; 0 failed" plus four
-// runner-specific patterns.
+// Match canonical runner pass lines using language-agnostic examples:
+//   Node/TS   (vitest/jest): "=> N passed; 0 failed" or "Tests: N passed"
+//   Python    (pytest): "===== N passed in 0.42s ====="
+//   Go        (go test): "ok   pkg   0.123s"
+//   Rust      (cargo test): "test result: ok. N passed; 0 failed"
+//   Java/JVM  (maven/surefire): "Tests run: N, Failures: 0, Errors: 0"
+// We accept a generic "passed/failed" shape plus runner-specific patterns.
 const GREEN_PASS_PATTERNS = [
   /=>\\s*\\d+\\s+passed/iu,
   /\\b\\d+\\s+passed[;,]\\s*0\\s+failed\\b/iu,
   /\\btest\\s+result:\\s*ok\\b/iu,
   /\\b\\d+\\s+passed\\s+in\\s+\\d+(?:\\.\\d+)?\\s*s\\b/iu,
-  /^ok\\s+\\S+\\s+\\d+(?:\\.\\d+)?s\\b/imu
+  /^ok\\s+\\S+\\s+\\d+(?:\\.\\d+)?s\\b/imu,
+  /tests\\s+run\\s*:\\s*\\d+\\s*,\\s*failures\\s*:\\s*0\\s*,\\s*errors\\s*:\\s*0/iu
 ];
 
 function matchesPassingAssertionInline(value) {
@@ -373,6 +374,16 @@ async function readDelegationEvents(root) {
   }
 }
 
+async function appendAuditEventInline(root, payload) {
+  const stateDir = path.join(root, RUNTIME_ROOT, "state");
+  await fs.mkdir(stateDir, { recursive: true });
+  await fs.appendFile(
+    path.join(stateDir, "delegation-events.jsonl"),
+    JSON.stringify(payload) + "\\n",
+    { encoding: "utf8", mode: 0o600 }
+  );
+}
+
 function hasPriorAck(events, args, runId) {
   return events.some((event) =>
     event.runId === runId &&
@@ -388,7 +399,7 @@ function hasPriorAck(events, args, runId) {
 function usage() {
   process.stderr.write([
     "Usage:",
-    "  node .cclaw/hooks/delegation-record.mjs --stage=<stage> --agent=<agent> --mode=<mandatory|proactive> --status=<scheduled|launched|acknowledged|completed|failed|waived|stale> --span-id=<id> [--dispatch-id=<id>] [--worker-run-id=<id>] [--dispatch-surface=<surface>] [--agent-definition-path=<path>] [--ack-ts=<iso>] [--launched-ts=<iso>] [--completed-ts=<iso>] [--evidence-ref=<ref>] [--waiver-reason=<text>] [--supersede=<prevSpanId>] [--allow-parallel] [--paths=<comma-separated>] [--override-cap=<int>] [--json]",
+    "  node .cclaw/hooks/delegation-record.mjs --stage=<stage> --agent=<agent> --mode=<mandatory|proactive> --status=<scheduled|launched|acknowledged|completed|failed|waived|stale> --span-id=<id> [--dispatch-id=<id>] [--worker-run-id=<id>] [--dispatch-surface=<surface>] [--agent-definition-path=<path>] [--ack-ts=<iso>] [--launched-ts=<iso>] [--completed-ts=<iso>] [--evidence-ref=<ref>] [--waiver-reason=<text>] [--supersede=<prevSpanId>] [--allow-parallel] [--paths=<comma-separated>] [--override-cap=<int>] [--reason=<slug>] [--json]",
     "  node .cclaw/hooks/delegation-record.mjs --rerecord --span-id=<id> --dispatch-id=<id> --dispatch-surface=<surface> --agent-definition-path=<path> [--ack-ts=<iso>] [--completed-ts=<iso>] [--evidence-ref=<ref>] [--json]",
     "  node .cclaw/hooks/delegation-record.mjs --repair --span-id=<id> --repair-reason=\\\"<why>\\\" [--json]",
     "  node .cclaw/hooks/delegation-record.mjs --audit-kind=cclaw_integration_overseer_skipped [--audit-reason=\\\"<comma-separated reasons>\\\"] [--slice-ids=\\\"S-1,S-2\\\"] [--json]    # non-delegation audit row",
@@ -406,11 +417,12 @@ function usage() {
     "TDD parallel scheduler:",
     "  --paths=<a,b,c>           repo-relative paths the slice-builder will edit; disjoint sets auto-promote to allowParallel, overlap throws DispatchOverlapError",
     "  --override-cap=<int>      raise the slice worker fan-out cap once for this dispatch (default cap " + String(5) + ", env CCLAW_MAX_PARALLEL_SLICE_BUILDERS overrides globally)",
+    "  --reason=<slug>           required with --override-cap so cap bypasses are auditable (e.g. red-checkpoint-retry)",
     "",
     "TDD slice phase tagging:",
     "  --slice=<id>              TDD slice identifier (e.g. S-1) used by the linter to auto-derive the Watched-RED + Vertical Slice Cycle tables.",
     "  --phase=<phase>           one of " + VALID_DELEGATION_PHASES.join(", ") + ". Pair with --slice to record a TDD slice phase event.",
-    "  --refactor-rationale=<t>  required when --phase=refactor-deferred unless --evidence-ref carries the rationale text; also paired with --refactor-outcome on phase=green.",
+    "  --refactor-rationale=<t>  required for deferred refactor paths; must be >=80 chars and mention slice + task context (e.g. S-12 / T-103).",
     "  --refactor-outcome=<m>   one of inline|deferred. Folds REFACTOR into the phase=green event so a single row can close RED→GREEN→REFACTOR. Pair --refactor-outcome=deferred with --refactor-rationale.",
     "  --risk-tier=<t>          one of low|medium|high. high triggers integration-overseer in conditional mode.",
     ""
@@ -505,6 +517,28 @@ function normalizeEvidenceRefs(args) {
   return [];
 }
 
+function validateDeferredRationaleInline(rationaleRaw, args) {
+  const rationale = typeof rationaleRaw === "string" ? rationaleRaw.trim() : "";
+  if (rationale.length === 0) {
+    return "missing";
+  }
+  if (rationale.length < 80) {
+    return "too-short";
+  }
+  const lower = rationale.toLowerCase();
+  const sliceRaw = typeof args.slice === "string" ? args.slice.trim().toLowerCase() : "";
+  const hasSliceMention =
+    (sliceRaw.length > 0 && lower.includes(sliceRaw)) ||
+    /\\bs-\\d+\\b/iu.test(rationale);
+  const hasTaskMention =
+    /\\bt-\\d{3}[a-z]?(?:\\.\\d{1,3})?\\b/iu.test(rationale) ||
+    /\\btask\\b/iu.test(rationale);
+  if (!hasSliceMention || !hasTaskMention) {
+    return "missing-context";
+  }
+  return "ok";
+}
+
 function buildRow(args, status, runId, now, options) {
   const fulfillmentMode = args["dispatch-surface"] === "role-switch"
     ? "role-switch"
@@ -911,7 +945,8 @@ async function findLegacyEntry(root, spanId) {
 // the helper. Keep in sync with NON_DELEGATION_AUDIT_EVENTS in
 // src/delegation.ts.
 const VALID_AUDIT_KINDS = new Set([
-  "cclaw_integration_overseer_skipped"
+  "cclaw_integration_overseer_skipped",
+  "cclaw_allow_parallel_auto_flip"
 ]);
 
 async function runAuditEmit(args, json) {
@@ -1347,15 +1382,15 @@ async function main() {
     return;
   }
   if (args.phase === "refactor-deferred") {
-    const rationaleProvided =
-      typeof args["refactor-rationale"] === "string" && args["refactor-rationale"].trim().length > 0;
-    const evidenceProvided =
-      (typeof args["evidence-ref"] === "string" && args["evidence-ref"].trim().length > 0) ||
-      (Array.isArray(args["evidence-refs"]) && args["evidence-refs"].some(
-        (ref) => typeof ref === "string" && ref.trim().length > 0
-      ));
-    if (!rationaleProvided && !evidenceProvided) {
-      problems.push("--phase=refactor-deferred requires --refactor-rationale=<text> or --evidence-ref=<text>");
+    const rationaleQuality = validateDeferredRationaleInline(args["refactor-rationale"], args);
+    if (rationaleQuality !== "ok") {
+      if (rationaleQuality === "missing") {
+        problems.push("--phase=refactor-deferred requires --refactor-rationale=<text>");
+      } else if (rationaleQuality === "too-short") {
+        problems.push("--refactor-rationale for deferred refactor must be at least 80 characters");
+      } else {
+        problems.push("--refactor-rationale for deferred refactor must mention slice/task context (e.g. S-12 and T-103)");
+      }
       emitProblems(problems, json, 2);
       return;
     }
@@ -1375,15 +1410,15 @@ async function main() {
     return;
   }
   if (args["refactor-outcome"] === "deferred") {
-    const rationaleProvided =
-      typeof args["refactor-rationale"] === "string" && args["refactor-rationale"].trim().length > 0;
-    const evidenceProvided =
-      (typeof args["evidence-ref"] === "string" && args["evidence-ref"].trim().length > 0) ||
-      (Array.isArray(args["evidence-refs"]) && args["evidence-refs"].some(
-        (ref) => typeof ref === "string" && ref.trim().length > 0
-      ));
-    if (!rationaleProvided && !evidenceProvided) {
-      problems.push("--refactor-outcome=deferred requires --refactor-rationale=<text> or --evidence-ref=<text>");
+    const rationaleQuality = validateDeferredRationaleInline(args["refactor-rationale"], args);
+    if (rationaleQuality !== "ok") {
+      if (rationaleQuality === "missing") {
+        problems.push("--refactor-outcome=deferred requires --refactor-rationale=<text>");
+      } else if (rationaleQuality === "too-short") {
+        problems.push("--refactor-rationale for deferred refactor must be at least 80 characters");
+      } else {
+        problems.push("--refactor-rationale for deferred refactor must mention slice/task context (e.g. S-12 and T-103)");
+      }
       emitProblems(problems, json, 2);
       return;
     }
@@ -1398,6 +1433,21 @@ async function main() {
     emitProblems(problems, json, 2);
     return;
   }
+  if (args["override-cap"] !== undefined) {
+    const overrideRaw = String(args["override-cap"]).trim();
+    const overrideNum = Number(overrideRaw);
+    if (!Number.isInteger(overrideNum) || overrideNum < 1) {
+      problems.push("--override-cap must be an integer >= 1");
+      emitProblems(problems, json, 2);
+      return;
+    }
+    const reasonRaw = typeof args.reason === "string" ? args.reason.trim() : "";
+    if (reasonRaw.length === 0) {
+      problems.push("--override-cap requires --reason=<slug>");
+      emitProblems(problems, json, 2);
+      return;
+    }
+  }
 
   if (args.status === "completed" && args["dispatch-surface"] !== "role-switch") {
     for (const key of ["dispatch-id", "dispatch-surface", "agent-definition-path"]) {
@@ -1479,6 +1529,7 @@ async function main() {
   const row = buildRow(args, status, runId, now, { spanStartTs });
   const clean = Object.fromEntries(Object.entries(row).filter(([, value]) => value !== undefined));
   const event = { ...clean, event: status, eventTs: now };
+  let autoParallelAuditEvent = null;
 
   const violation = validateMonotonicTimestampsInline(clean, priorLedger);
   if (violation) {
@@ -1487,8 +1538,8 @@ async function main() {
   }
 
   // File-overlap scheduler + fan-out cap. Run before the dispatch
-  // dedup so disjoint claimedPaths can auto-promote to allowParallel and
-  // bypass the duplicate guard.
+  // dedup so disjoint claimedPaths can auto-promote to allowParallel,
+  // emit an audit event for the flip, and bypass the duplicate guard.
   if (status === "scheduled") {
     const sameRunPrior = priorLedger.filter((entry) => entry.runId === runId);
     const activeForRun = computeActiveSubagentsInline(sameRunPrior);
@@ -1501,6 +1552,18 @@ async function main() {
       clean.allowParallel = true;
       args["allow-parallel"] = true;
       event.allowParallel = true;
+      autoParallelAuditEvent = {
+        event: "cclaw_allow_parallel_auto_flip",
+        runId,
+        ts: now,
+        eventTs: now,
+        stage: clean.stage,
+        agent: clean.agent,
+        spanId: clean.spanId,
+        sliceId: clean.sliceId,
+        reason: "disjoint-claimed-paths-auto-flip",
+        claimedPaths: Array.isArray(clean.claimedPaths) ? clean.claimedPaths : []
+      };
     }
     const overrideRaw = typeof args["override-cap"] === "string" ? args["override-cap"] : null;
     const override = overrideRaw !== null ? Number(overrideRaw) : null;
@@ -1548,8 +1611,7 @@ async function main() {
   //   3. green_evidence_too_fresh — completedTs minus ackTs must be
   //      >= flow-state.json::tddGreenMinElapsedMs (default 4000ms).
   // Escape hatch for legitimate observational GREENs (cross-slice
-  // handoff, no-op verification): pair --allow-fast-green with
-  // --green-mode=observational. Both flags are required.
+  // handoff, no-op verification): --green-mode=observational.
   if (
     clean.stage === "tdd" &&
     clean.agent === "slice-builder" &&
@@ -1559,7 +1621,6 @@ async function main() {
     const isObservational =
       typeof args["green-mode"] === "string" &&
       args["green-mode"].trim().toLowerCase() === "observational";
-    const allowFastGreen = args["allow-fast-green"] === true;
     const greenEvidenceFirst =
       Array.isArray(clean.evidenceRefs) && clean.evidenceRefs.length > 0
         ? String(clean.evidenceRefs[0])
@@ -1586,10 +1647,9 @@ async function main() {
     // nothing to verify GREEN against (legacy ledger imports, RED
     // happened outside cclaw harness, or test fixtures that bypass
     // RED). Once a RED row is present, the contract becomes
-    // mandatory unless explicitly waived via --allow-fast-green
-    // --green-mode=observational.
+    // mandatory unless explicitly waived via --green-mode=observational.
     const hasRedContext = redEvidenceRef !== null;
-    const escapeFastGreen = allowFastGreen && isObservational;
+    const escapeFastGreen = isObservational;
 
     if (hasRedContext && !escapeFastGreen) {
       // Check 1: RED test name match.
@@ -1618,7 +1678,7 @@ async function main() {
             sliceId: clean.sliceId,
             greenEvidenceFirst,
             remediation:
-              "evidenceRefs[0] on the GREEN row must contain a passing-assertion line such as \\"=> N passed; 0 failed\\" (cargo/jest/vitest), \\"N passed in 0.42s\\" (pytest), \\"ok pkg 0.12s\\" (go test), or equivalent runner output. Re-run the test and paste a fresh runner line."
+              "evidenceRefs[0] on the GREEN row must contain a passing-assertion line (language-agnostic examples: Node/Vitest \\"=> N passed; 0 failed\\", Python/Pytest \\"N passed in 0.42s\\", Go \\"ok pkg 0.12s\\", Rust \\"test result: ok\\", Java/Maven \\"Tests run: N, Failures: 0, Errors: 0\\"). Re-run the test and paste a fresh runner line."
           },
           json
         );
@@ -1657,7 +1717,7 @@ async function main() {
                   elapsedMs: elapsed,
                   minMs,
                   remediation:
-                    "GREEN completedTs - ackTs is below the freshness floor. Either run the verification test for real and re-record, or pass --allow-fast-green --green-mode=observational for legitimate no-op verification spans."
+                    "GREEN completedTs - ackTs is below the freshness floor. Either run the verification test for real and re-record, or pass --green-mode=observational for legitimate no-op verification spans."
                 },
                 json
               );
@@ -1687,6 +1747,9 @@ async function main() {
   }
 
   await persistEntry(root, runId, clean, event);
+  if (autoParallelAuditEvent) {
+    await appendAuditEventInline(root, autoParallelAuditEvent);
+  }
 
   process.stdout.write(JSON.stringify({ ok: true, event }, null, 2) + "\\n");
 }

package/dist/content/skills.js

@@ -188,14 +188,14 @@ export function tddTopOfSkillBlock(stage) {
 **Step 1 — Wave status (always first):**
 \`node .cclaw/cli.mjs internal wave-status --json\`
 
-The output names: \`waves[]\` (closed/open), \`nextDispatch.waveId\`, \`nextDispatch.mode\` (\`wave-fanout\` or \`single-slice\`), \`nextDispatch.readyToDispatch\` (slice ids), and \`nextDispatch.pathConflicts\` (overlapping \`claimedPaths\` between members).
+The output names: \`waves[]\` (closed/open), \`nextDispatch.waveId\`, \`nextDispatch.mode\` (\`wave-fanout\`, \`single-slice\`, or \`blocked\`), \`nextDispatch.readyToDispatch\` (slice ids), and \`nextDispatch.pathConflicts\` (overlapping \`claimedPaths\` between members).
 
 **Step 2 — Decide automatically (no user question when paths disjoint):**
 
 | \`mode\`         | \`pathConflicts\` | Action                                                                                                                                  |
 |------------------|-------------------|-----------------------------------------------------------------------------------------------------------------------------------------|
 | \`wave-fanout\`  | \`[]\`            | **Fan out the entire wave in one tool batch.** Emit one \`Task\` per ready slice in a single controller message. Do NOT ask the user.   |
-| \`wave-fanout\`  | non-empty         | Issue exactly one AskQuestion (resolve the overlap, drop the conflicting slice, or downgrade to single-slice for the disputed member).  |
+| \`blocked\`      | non-empty         | Issue exactly one AskQuestion (resolve overlap, split/serialize, or adjust claimedPaths), then re-run \`wave-status\`.                    |
 | \`single-slice\` | —                 | One \`Task\` for the next ready slice.                                                                                                  |
 
 **Step 3 — Dispatch protocol per slice:** in the SAME controller message that issues the \`Task\` call:

package/dist/content/stage-schema.js

@@ -4,6 +4,7 @@ import { BRAINSTORM, SCOPE, DESIGN, SPEC, PLAN, TDD, REVIEW, SHIP } from "./stag
 import { stagePolicyNeedlesFromMetadata } from "./stages/_lint-metadata/index.js";
 import { tddStageForTrack } from "./stages/tdd.js";
 import { trackRenderContext } from "./track-render-context.js";
+import { STACK_REVIEW_ROUTE_PROFILES } from "../stack-detection.js";
 // ---------------------------------------------------------------------------
 // NOTE: The former QUESTION_FORMAT_SPEC / ERROR_BUDGET_SPEC exports were
 // hoisted into `src/content/meta-skill.ts` (Shared Decision + Tool-Use
@@ -31,38 +32,12 @@ const COMPLEXITY_TIER_ORDER = {
     standard: 1,
     deep: 2
 };
-const REVIEW_STACK_AWARE_ROUTES = [
-    {
-        stack: "TypeScript/JavaScript",
-        agent: "reviewer",
-        signals: ["package.json", "tsconfig.json"],
-        focus: "type safety, package scripts, build/test config, dependency boundaries"
-    },
-    {
-        stack: "Python",
-        agent: "reviewer",
-        signals: ["pyproject.toml", "requirements.txt"],
-        focus: "packaging, virtualenv assumptions, typing, pytest or unittest evidence"
-    },
-    {
-        stack: "Ruby/Rails",
-        agent: "reviewer",
-        signals: ["Gemfile", "config/"],
-        focus: "Rails conventions, migrations, routes/controllers, RSpec or Minitest evidence"
-    },
-    {
-        stack: "Go",
-        agent: "reviewer",
-        signals: ["go.mod"],
-        focus: "interfaces, concurrency, error handling, go test coverage"
-    },
-    {
-        stack: "Rust",
-        agent: "reviewer",
-        signals: ["Cargo.toml"],
-        focus: "ownership, error/result handling, feature flags, cargo test coverage"
-    }
-];
+const REVIEW_STACK_AWARE_ROUTES = STACK_REVIEW_ROUTE_PROFILES.map((profile) => ({
+    stack: profile.stack,
+    agent: "reviewer",
+    signals: [...profile.reviewSignals],
+    focus: profile.focus
+}));
 function stackAwareRoutesForStage(stage) {
     return stage === "review" ? reviewStackAwareRoutes() : [];
 }
@@ -295,6 +270,7 @@ const REQUIRED_GATE_IDS = {
         "plan_acceptance_mapped",
         "plan_execution_posture_recorded",
         "plan_parallel_exec_full_coverage",
+        "plan_wave_paths_disjoint",
         "plan_wait_for_confirm"
     ],
     tdd: (track) => [

package/dist/content/stages/plan.js

@@ -52,6 +52,7 @@ export const PLAN = {
             "Define validation points — mark where progress must be checked before continuing, with concrete command and expected evidence.",
             "Define execution posture — record whether execution should be sequential, dependency-batched, parallel-safe, or blocked; include risk triggers and RED/GREEN/REFACTOR checkpoint/commit expectations when the repo workflow supports them. This fulfills the `plan_execution_posture_recorded` gate.",
             "**Author the FULL Parallel Execution Plan.** Inside the `<!-- parallel-exec-managed-start -->` block, enumerate ALL waves W-02..W-N covering EVERY T-NNN task in `## Task List` — no `we'll author waves later`, `next batch only`, or open-ended Backlog handwave is acceptable. Each task gets a slice with `sliceId | taskId | dependsOn | claimedPaths | parallelizable | riskTier | lane`. Spike rows (`S-N`) and tasks marked `deferred` in an explicit `Deferred:` column may be omitted, but every other T-NNN must be claimed. This fulfills the `plan_parallel_exec_full_coverage` gate. The TDD stage downstream is a pure consumer of these waves — if the plan does not author them, TDD cannot fan out that work.",
+            "After authoring/refreshing the managed parallel-exec block, render a Mermaid `flowchart` or `gantt` covering waves (`W-*`) and slice dependencies (`S-*`) so parallelism and fan-in boundaries are visually auditable.",
             "WAIT_FOR_CONFIRM — write plan artifact and explicitly pause. **STOP.** Do NOT proceed until user confirms. Then close the stage with `node .cclaw/hooks/stage-complete.mjs plan` and tell user to run `/cc`."
         ],
         interactionProtocol: [
@@ -59,6 +60,7 @@ export const PLAN = {
             "Split work into small vertical slices (target 2-5 minute tasks).",
             "Publish explicit dependency batches with entry and exit checks for each batch.",
             "Expose execution posture: sequential vs batch/parallel, stop conditions, and checkpoint cadence for the TDD handoff.",
+            "Keep same-wave `claimedPaths` disjoint; if overlap exists, split waves or serialize explicitly before handoff.",
             "Attach exact verification command/manual step and expected evidence to every task.",
             "Preserve locked scope boundaries: no silent scope reduction language in task rows.",
             "Enforce WAIT_FOR_CONFIRM: present the plan summary with options (A) Approve / (B) Revise / (C) Reject.",
@@ -82,6 +84,7 @@ export const PLAN = {
             { id: "plan_acceptance_mapped", description: "Each task maps to a spec acceptance criterion." },
             { id: "plan_execution_posture_recorded", description: "Execution posture is recorded before implementation handoff." },
             { id: "plan_parallel_exec_full_coverage", description: "Every T-NNN task in `## Task List` (other than spikes/explicitly-deferred) is assigned to at least one slice inside the `<!-- parallel-exec-managed-start -->` block; TDD cannot fan out work that the plan never authored as waves." },
+            { id: "plan_wave_paths_disjoint", description: "Within each authored wave, slice `claimedPaths` remain disjoint so `wave-fanout` can dispatch safely without overlap conflicts." },
             { id: "plan_wait_for_confirm", description: "Execution blocked until explicit user confirmation." }
         ],
         requiredEvidence: [

package/dist/content/start-command.js

@@ -119,7 +119,7 @@ If during any stage the agent discovers evidence that contradicts the initial Ph
 
    **The controller never edits production code in TDD.** When \`mode: wave-fanout\` and \`pathConflicts: []\`, fan out the entire wave in a SINGLE controller message: one harness \`Task(subagent_type=…, description="slice-builder S-<id>", prompt=<full slice context>)\` call per ready slice, **side by side in the same tool batch**. Each \`slice-builder\` span owns the full RED → GREEN → REFACTOR → DOC cycle for its slice and emits its own \`delegation-record --phase=red|green|refactor|refactor-deferred|doc\` rows. RED-before-GREEN is enforced per-slice by the linter.
 
-   When \`mode: wave-fanout\` reports \`pathConflicts\`, surface exactly one AskQuestion that lets the user resolve the overlap (drop / split / serialize). When \`mode: single-slice\`, dispatch one \`Task\` for the next ready slice.
+   When \`mode: blocked\` with \`pathConflicts\`, surface exactly one AskQuestion that lets the user resolve the overlap (drop / split / serialize). When \`mode: single-slice\`, dispatch one \`Task\` for the next ready slice.
 
 6. **Auto-advance after stage-complete:** when \`stage-complete\` returns \`ok\` with a new \`currentStage\`, immediately load the next stage skill and continue without waiting for the user to retype \`/cc\`. Announce \`Stage <prev> complete → entering <next>. Continuing.\` and proceed.
 
@@ -214,7 +214,7 @@ Progress the tracked flow only when one exists:
 2. If missing, guide the user to run \`npx cclaw-cli init\` and stop.
 3. If it is only a fresh init placeholder (\`completedStages: []\`, no passed gates, and no \`${RUNTIME_ROOT}/artifacts/00-idea.md\`), stop and ask for \`/cc <prompt>\` to start a tracked run. Do not silently create a brainstorm run.
 4. Check gates for \`currentStage\`.
-5. **TDD:** When \`currentStage\` is \`tdd\`, run \`wave-status --json\`, then reconcile the managed **Parallel Execution Plan** in \`05-plan.md\` with \`wave-plans/wave-NN.md\`. **The controller never edits production code in TDD.** When \`mode: wave-fanout\` and \`pathConflicts: []\`, fan out the wave in a SINGLE controller message — one \`Task\` per ready slice, side by side. Each \`slice-builder\` span owns its full RED → GREEN → REFACTOR → DOC cycle. Mirror plan \`dependsOn\` ordering between waves.
+5. **TDD:** When \`currentStage\` is \`tdd\`, run \`wave-status --json\`, then reconcile the managed **Parallel Execution Plan** in \`05-plan.md\` with \`wave-plans/wave-NN.md\`. **The controller never edits production code in TDD.** When \`mode: wave-fanout\` and \`pathConflicts: []\`, fan out the wave in a SINGLE controller message — one \`Task\` per ready slice, side by side. If \`mode: blocked\`, resolve overlaps first. Each \`slice-builder\` span owns its full RED → GREEN → REFACTOR → DOC cycle. Mirror plan \`dependsOn\` ordering between waves.
 6. **Wave resume:** Parallelize unfinished members; never restart completed lanes. Integration-overseer follows \`integrationCheckRequired\`; when skipped, emit \`cclaw_integration_overseer_skipped\` per the hook contract.
 7. If incomplete → load current stage skill and execute.
 8. If complete → advance to next stage and execute. **Auto-advance:** when \`stage-complete\` returns \`ok\`, immediately load the next stage skill and continue without waiting for the user to retype \`/cc\`.

package/dist/delegation.js

@@ -375,6 +375,7 @@ const NON_DELEGATION_AUDIT_EVENTS = new Set([
     "cclaw_fanin_resolved",
     "cclaw_fanin_abandoned",
     "cclaw_integration_overseer_skipped",
+    "cclaw_allow_parallel_auto_flip",
     "slice-completed"
 ]);
 function isAuditEventLine(parsed) {

package/dist/flow-state.d.ts

@@ -124,7 +124,7 @@ export interface FlowState {
      * Minimum elapsed milliseconds between `acknowledged` and `completed`
      * for a `slice-builder --phase green` row. The hook helper rejects
      * fast-greens (`completedTs - ackTs < this`) with `green_evidence_too_fresh`
-     * unless the dispatch carries `--allow-fast-green --green-mode=observational`.
+     * unless the dispatch carries `--green-mode=observational`.
      *
      * Default 4000ms when omitted (see `effectiveTddGreenMinElapsedMs`).
      * Operators tuning the floor for very fast suites may set it lower

package/dist/install.d.ts

@@ -6,6 +6,7 @@ export interface InitOptions {
 }
 export interface SyncOptions {
     harnesses?: HarnessId[];
+    check?: boolean;
 }
 export declare function initCclaw(options: InitOptions): Promise<void>;
 export declare function syncCclaw(projectRoot: string, options?: SyncOptions): Promise<void>;

package/dist/install.js

@@ -750,6 +750,49 @@ async function writeHooks(projectRoot, config) {
         // OpenCode registration is auto-managed via opencode.json/opencode.jsonc.
     }
 }
+async function canonicalHookScripts() {
+    const hookRuntimeOptions = {};
+    const bundledHookRuntime = await readBundledRunHookRuntimeScript(hookRuntimeOptions);
+    return {
+        "stage-complete.mjs": stageCompleteScript(),
+        "start-flow.mjs": startFlowScript(),
+        "cancel-run.mjs": cancelRunScript(),
+        "run-hook.mjs": bundledHookRuntime ?? nodeHookRuntimeScript(hookRuntimeOptions),
+        "run-hook.cmd": runHookCmdScript(),
+        "delegation-record.mjs": delegationRecordScript(),
+        "slice-commit.mjs": sliceCommitScript(),
+        "opencode-plugin.mjs": opencodePluginJs()
+    };
+}
+async function checkManagedHookDrift(projectRoot) {
+    const hooksDir = runtimePath(projectRoot, "hooks");
+    const canonical = await canonicalHookScripts();
+    const findings = [];
+    for (const [fileName, expectedSource] of Object.entries(canonical)) {
+        const targetPath = path.join(hooksDir, fileName);
+        let actual;
+        try {
+            actual = await fs.readFile(targetPath);
+        }
+        catch {
+            findings.push({ file: fileName, reason: "missing" });
+            continue;
+        }
+        const expected = Buffer.from(expectedSource, "utf8");
+        if (!actual.equals(expected)) {
+            findings.push({ file: fileName, reason: "content_mismatch" });
+        }
+    }
+    return findings;
+}
+function formatManagedHookDriftError(findings) {
+    const details = findings
+        .map((finding) => `- .cclaw/hooks/${finding.file}: ${finding.reason === "missing" ? "missing" : "content differs from canonical renderer"}`)
+        .join("\n");
+    return ("[sync --check] Managed hook drift detected.\n" +
+        `${details}\n` +
+        "Re-run `npx cclaw-cli sync` to rewrite managed hooks.");
+}
 async function ensureKnowledgeStore(projectRoot) {
     const storePath = runtimePath(projectRoot, "knowledge.jsonl");
     if (!(await exists(storePath))) {
@@ -1064,6 +1107,13 @@ export async function syncCclaw(projectRoot, options = {}) {
     if (options.harnesses !== undefined && options.harnesses.length === 0) {
         throw new Error("Select at least one harness.");
     }
+    if (options.check === true) {
+        const drift = await checkManagedHookDrift(projectRoot);
+        if (drift.length > 0) {
+            throw new Error(formatManagedHookDriftError(drift));
+        }
+        return;
+    }
     const configExists = await exists(configPath(projectRoot));
     let config = await readConfig(projectRoot);
     if (!configExists) {

package/dist/internal/advance-stage/start-flow.js

@@ -4,6 +4,7 @@ import { RUNTIME_ROOT } from "../../constants.js";
 import { createInitialFlowState } from "../../flow-state.js";
 import { readFlowState, writeFlowState } from "../../runs.js";
 import { listExistingFiles, listFilesUnder, pathExists } from "./helpers.js";
+import { STACK_DISCOVERY_DIR_MARKERS, STACK_DISCOVERY_MARKERS } from "../../stack-detection.js";
 import { TRACK_STAGES } from "../../types.js";
 import { buildValidationReport } from "./advance.js";
 import { carriedCompletedStageCatalog, completedStageClosureEvidenceIssues, firstIncompleteStageForTrack } from "./verify.js";
@@ -91,24 +92,11 @@ export async function discoverStartFlowContext(projectRoot) {
     lines.push(originFiles.length > 0
         ? `- Origin docs scanned: found ${originFiles.join(", ")}.`
         : "- Origin docs scanned: no PRD/RFC/ADR/design/spec files found in configured locations.");
-    const stackMarkers = await listExistingFiles(projectRoot, [
-        "package.json",
-        "pyproject.toml",
-        "requirements.txt",
-        "requirements-dev.txt",
-        ".python-version",
-        "go.mod",
-        "Cargo.toml",
-        "pom.xml",
-        "build.gradle",
-        "build.gradle.kts",
-        "Dockerfile",
-        "docker-compose.yml",
-        "docker-compose.yaml",
-        ".gitlab-ci.yml"
-    ]);
-    if (await pathExists(projectRoot, ".github/workflows")) {
-        stackMarkers.push(".github/workflows/");
+    const stackMarkers = await listExistingFiles(projectRoot, [...STACK_DISCOVERY_MARKERS]);
+    for (const markerDir of STACK_DISCOVERY_DIR_MARKERS) {
+        if (await pathExists(projectRoot, markerDir)) {
+            stackMarkers.push(`${markerDir}/`);
+        }
     }
     lines.push(stackMarkers.length > 0
         ? `- Stack markers scanned: found ${stackMarkers.join(", ")}.`

package/dist/internal/advance-stage/verify.js

@@ -3,6 +3,7 @@ import { RUNTIME_ROOT } from "../../constants.js";
 import { stageSchema } from "../../content/stage-schema.js";
 import { readFlowState } from "../../runs.js";
 import { TRACK_STAGES } from "../../types.js";
+import { STACK_DISCOVERY_DIR_MARKERS, STACK_DISCOVERY_MARKERS } from "../../stack-detection.js";
 import { coerceCandidateFlowState } from "./flow-state-coercion.js";
 import { buildValidationReport } from "./advance.js";
 import fs from "node:fs/promises";
@@ -171,24 +172,11 @@ export async function discoverStartFlowContext(projectRoot) {
     lines.push(originFiles.length > 0
         ? `- Origin docs scanned: found ${originFiles.join(", ")}.`
         : "- Origin docs scanned: no PRD/RFC/ADR/design/spec files found in configured locations.");
-    const stackMarkers = await listExistingFiles(projectRoot, [
-        "package.json",
-        "pyproject.toml",
-        "requirements.txt",
-        "requirements-dev.txt",
-        ".python-version",
-        "go.mod",
-        "Cargo.toml",
-        "pom.xml",
-        "build.gradle",
-        "build.gradle.kts",
-        "Dockerfile",
-        "docker-compose.yml",
-        "docker-compose.yaml",
-        ".gitlab-ci.yml"
-    ]);
-    if (await pathExists(projectRoot, ".github/workflows")) {
-        stackMarkers.push(".github/workflows/");
+    const stackMarkers = await listExistingFiles(projectRoot, [...STACK_DISCOVERY_MARKERS]);
+    for (const markerDir of STACK_DISCOVERY_DIR_MARKERS) {
+        if (await pathExists(projectRoot, markerDir)) {
+            stackMarkers.push(`${markerDir}/`);
+        }
     }
     lines.push(stackMarkers.length > 0
         ? `- Stack markers scanned: found ${stackMarkers.join(", ")}.`

package/dist/internal/wave-status.d.ts

@@ -16,7 +16,7 @@ export interface WaveStatusNextDispatch {
     waveId: string | null;
     readyToDispatch: string[];
     pathConflicts: string[];
-    mode: "single-slice" | "wave-fanout" | "none";
+    mode: "single-slice" | "wave-fanout" | "blocked" | "none";
 }
 export interface WaveStatusReport {
     activeRunId: string;

package/dist/internal/wave-status.js

@@ -4,6 +4,8 @@ import { RUNTIME_ROOT } from "../constants.js";
 import { readDelegationEvents, readDelegationLedger } from "../delegation.js";
 import { readFlowState } from "../runs.js";
 import { mergeParallelWaveDefinitions, parseParallelExecutionPlanWaves, parseWavePlanDirectory } from "./plan-split-waves.js";
+const PARALLEL_EXEC_MANAGED_START = "<!-- parallel-exec-managed-start -->";
+const PARALLEL_EXEC_MANAGED_END = "<!-- parallel-exec-managed-end -->";
 function parseArgs(tokens) {
     const args = { format: "json" };
     for (const token of tokens) {
@@ -33,6 +35,92 @@ function classifyWaveStatus(total, closedCount) {
         return "closed";
     return "partial";
 }
+function parsePipeRow(trimmedLine) {
+    const inner = trimmedLine.replace(/^\|/u, "").replace(/\|\s*$/u, "");
+    return inner.split("|").map((cell) => cell.trim());
+}
+function normalizePathToken(raw) {
+    return raw.trim().replace(/^`|`$/gu, "").replace(/^\.\/+/u, "");
+}
+function parseManagedWaveClaimedPaths(planMarkdown) {
+    const out = new Map();
+    const startIdx = planMarkdown.indexOf(PARALLEL_EXEC_MANAGED_START);
+    const endIdx = planMarkdown.indexOf(PARALLEL_EXEC_MANAGED_END);
+    if (startIdx < 0 || endIdx <= startIdx)
+        return out;
+    const body = planMarkdown.slice(startIdx + PARALLEL_EXEC_MANAGED_START.length, endIdx);
+    const lines = body.split(/\r?\n/u);
+    let currentWaveId = null;
+    let headerIdx = new Map();
+    for (const rawLine of lines) {
+        const trimmed = rawLine.trim();
+        const waveMatch = /^###\s+Wave\s+(?:W-)?(\d+)\b/iu.exec(trimmed);
+        if (waveMatch) {
+            currentWaveId = `W-${waveMatch[1].padStart(2, "0")}`;
+            if (!out.has(currentWaveId)) {
+                out.set(currentWaveId, new Map());
+            }
+            headerIdx = new Map();
+            continue;
+        }
+        if (!currentWaveId || !trimmed.startsWith("|"))
+            continue;
+        const cells = parsePipeRow(trimmed);
+        if (cells.length === 0)
+            continue;
+        const first = cells[0].toLowerCase();
+        if (first === "sliceid" || first === "slice id") {
+            headerIdx = new Map();
+            for (let i = 0; i < cells.length; i += 1) {
+                const key = cells[i].toLowerCase().replace(/[^a-z0-9]/gu, "");
+                if (key.length > 0 && !headerIdx.has(key)) {
+                    headerIdx.set(key, i);
+                }
+            }
+            continue;
+        }
+        if (cells.every((cell) => /^:?-{3,}:?$/u.test(cell))) {
+            continue;
+        }
+        const sliceId = cells[0].trim().toUpperCase();
+        if (!/^S-\d+$/u.test(sliceId))
+            continue;
+        const pathsIdx = headerIdx.get("claimedpaths");
+        const rawPaths = pathsIdx !== undefined ? (cells[pathsIdx] ?? "") : "";
+        const claimedPaths = rawPaths.length === 0
+            ? []
+            : rawPaths
+                .split(",")
+                .map((p) => normalizePathToken(p))
+                .filter((p) => p.length > 0);
+        out.get(currentWaveId).set(sliceId, claimedPaths);
+    }
+    return out;
+}
+function detectPathConflicts(readySlices, bySlice) {
+    const conflicts = new Set();
+    const ordered = [...readySlices].sort();
+    for (let i = 0; i < ordered.length; i += 1) {
+        const leftSlice = ordered[i];
+        const leftPaths = bySlice.get(leftSlice) ?? [];
+        if (leftPaths.length === 0)
+            continue;
+        const leftSet = new Set(leftPaths);
+        for (let j = i + 1; j < ordered.length; j += 1) {
+            const rightSlice = ordered[j];
+            const rightPaths = bySlice.get(rightSlice) ?? [];
+            if (rightPaths.length === 0)
+                continue;
+            for (const pathToken of rightPaths) {
+                if (!leftSet.has(pathToken))
+                    continue;
+                conflicts.add(`${leftSlice}:${pathToken}`);
+                conflicts.add(`${rightSlice}:${pathToken}`);
+            }
+        }
+    }
+    return [...conflicts].sort();
+}
 const TERMINAL_PHASES = new Set([
     "refactor",
     "refactor-deferred",
@@ -202,11 +290,20 @@ export async function runWaveStatus(projectRoot, options = {}) {
     }
     else {
         const readyToDispatch = [...firstOpenWave.readyMembers].sort();
+        const claimedPathsByWave = parseManagedWaveClaimedPaths(planRaw);
+        const conflicts = detectPathConflicts(readyToDispatch, claimedPathsByWave.get(firstOpenWave.waveId) ?? new Map());
+        const mode = conflicts.length > 0
+            ? "blocked"
+            : readyToDispatch.length > 1
+                ? "wave-fanout"
+                : readyToDispatch.length === 1
+                    ? "single-slice"
+                    : "none";
         nextDispatch = {
             waveId: firstOpenWave.waveId,
             readyToDispatch,
-            pathConflicts: [],
-            mode: readyToDispatch.length > 1 ? "wave-fanout" : "single-slice"
+            pathConflicts: conflicts,
+            mode
         };
     }
     return {

package/dist/stack-detection.d.ts

@@ -0,0 +1,22 @@
+export interface StackReviewRouteProfile {
+    stack: string;
+    /**
+     * Signals shown in review routing documentation/skills.
+     * These are human-facing pointers, not strict parsers.
+     */
+    reviewSignals: string[];
+    /** Root-level markers used by start-flow context discovery. */
+    discoveryMarkers: string[];
+    focus: string;
+}
+export declare const STACK_REVIEW_ROUTE_PROFILES: readonly StackReviewRouteProfile[];
+/**
+ * Unified root-marker list used by start-flow context discovery.
+ * Keep this in one place so stage skill routing and start-flow scanning
+ * evolve together.
+ */
+export declare const STACK_DISCOVERY_MARKERS: readonly string[];
+/**
+ * Directory markers (checked with pathExists) for stack discovery.
+ */
+export declare const STACK_DISCOVERY_DIR_MARKERS: readonly string[];

package/dist/stack-detection.js

@@ -0,0 +1,58 @@
+export const STACK_REVIEW_ROUTE_PROFILES = [
+    {
+        stack: "TypeScript/JavaScript",
+        reviewSignals: ["package.json", "tsconfig.json"],
+        discoveryMarkers: ["package.json", "tsconfig.json", "jsconfig.json"],
+        focus: "type safety, package scripts, build/test config, dependency boundaries"
+    },
+    {
+        stack: "Python",
+        reviewSignals: ["pyproject.toml", "requirements.txt"],
+        discoveryMarkers: ["pyproject.toml", "requirements.txt", "requirements-dev.txt", ".python-version"],
+        focus: "packaging, virtualenv assumptions, typing, pytest or unittest evidence"
+    },
+    {
+        stack: "Ruby/Rails",
+        reviewSignals: ["Gemfile", "config/"],
+        discoveryMarkers: ["Gemfile"],
+        focus: "Rails conventions, migrations, routes/controllers, RSpec or Minitest evidence"
+    },
+    {
+        stack: "Go",
+        reviewSignals: ["go.mod"],
+        discoveryMarkers: ["go.mod"],
+        focus: "interfaces, concurrency, error handling, go test coverage"
+    },
+    {
+        stack: "Rust",
+        reviewSignals: ["Cargo.toml"],
+        discoveryMarkers: ["Cargo.toml"],
+        focus: "ownership, error/result handling, feature flags, cargo test coverage"
+    }
+];
+const EXTRA_DISCOVERY_MARKERS = [
+    "pom.xml",
+    "build.gradle",
+    "build.gradle.kts",
+    "Dockerfile",
+    "docker-compose.yml",
+    "docker-compose.yaml",
+    ".gitlab-ci.yml"
+];
+/**
+ * Unified root-marker list used by start-flow context discovery.
+ * Keep this in one place so stage skill routing and start-flow scanning
+ * evolve together.
+ */
+export const STACK_DISCOVERY_MARKERS = [
+    ...new Set([
+        ...STACK_REVIEW_ROUTE_PROFILES.flatMap((profile) => profile.discoveryMarkers),
+        ...EXTRA_DISCOVERY_MARKERS
+    ])
+];
+/**
+ * Directory markers (checked with pathExists) for stack discovery.
+ */
+export const STACK_DISCOVERY_DIR_MARKERS = [
+    ".github/workflows"
+];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cclaw-cli",
-  "version": "7.1.0",
+  "version": "7.2.0",
   "description": "Installer-first flow toolkit for coding agents",
   "type": "module",
   "bin": {