cclaw-cli 7.1.1 → 7.2.0

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/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() : [];
 }

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/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.1",
+  "version": "7.2.0",
   "description": "Installer-first flow toolkit for coding agents",
   "type": "module",
   "bin": {