cclaw-cli 6.5.0 → 6.7.0

package/dist/artifact-linter/shared.js

@@ -384,6 +384,41 @@ export function duplicateH2Headings(markdown) {
         .filter(([, count]) => count > 1)
         .map(([key]) => displayHeading.get(key) ?? key);
 }
+/**
+ * Return the author-authored prose of an artifact, stripping linter meta
+ * regions so free-text scans (placeholder tokens, scope-reduction phrases,
+ * investigation trigger words) don't self-cannibalize by matching the
+ * linter's own templated meta-phrases.
+ *
+ * Stripping rules (in order):
+ *   1. `<!-- linter-meta --> ... <!-- /linter-meta -->` paired blocks.
+ *      Both markers must appear on their own line; unterminated openings
+ *      are left as-is so a malformed artifact cannot hide arbitrary
+ *      content by omitting the closing marker.
+ *   2. Every other HTML comment (`<!-- ... -->`, possibly multi-line).
+ *   3. Fenced code blocks that are tagged `linter-rule` (e.g.
+ *      ```` ```linter-rule ````). Plain fenced code blocks are preserved
+ *      because many stages quote code samples that the linter should
+ *      still see.
+ *
+ * The function guarantees the returned string is a strict subset of the
+ * original: no characters are synthesized, and line offsets are
+ * preserved for any surviving line (blank lines stand in for stripped
+ * regions). This keeps regex-based linter checks stable when authors
+ * add or remove linter-meta blocks between runs.
+ */
+export function extractAuthoredBody(rawArtifact) {
+    if (typeof rawArtifact !== "string" || rawArtifact.length === 0) {
+        return "";
+    }
+    const linterMetaBlock = /^[ \t]*<!--\s*linter-meta\s*-->[\s\S]*?^[ \t]*<!--\s*\/linter-meta\s*-->[ \t]*$/gmu;
+    let body = rawArtifact.replace(linterMetaBlock, (match) => match.replace(/[^\n]/gu, ""));
+    const htmlComment = /<!--[\s\S]*?-->/gu;
+    body = body.replace(htmlComment, (match) => match.replace(/[^\n]/gu, ""));
+    const linterRuleFence = /^([ \t]*)(`{3,}|~{3,})\s*linter-rule\b[^\n]*\n[\s\S]*?\n\1\2[ \t]*$/gmu;
+    body = body.replace(linterRuleFence, (match) => match.replace(/[^\n]/gu, ""));
+    return body;
+}
 export function headingPresent(sections, section) {
     const want = normalizeHeadingTitle(section).toLowerCase();
     for (const h of sections.keys()) {
@@ -1715,6 +1750,148 @@ export function parseLearningsSection(sectionBody) {
         details: `Parsed ${entries.length} learning bullet(s) as knowledge-compatible JSON entries.`
     };
 }
+/**
+ * Round 5 (v6.6.0) — file-path / reference detector for the
+ * `investigation_path_first_missing` advisory rule.
+ *
+ * The detector is intentionally permissive: it only needs to recognize
+ * "the author wrote down a path or ref" — the linter does NOT validate
+ * the path resolves on disk. Patterns matched (any one is enough):
+ *   - TS/JS/MD/JSON/YAML path with extension
+ *     (`src/foo/bar.ts`, `tests/spec.test.ts`, `docs/quality-gates.md`).
+ *   - Slash-bearing path under a known repo root prefix
+ *     (`src/...`, `tests/...`, `docs/...`, `scripts/...`,
+ *     `.cclaw/...`, `.cursor/...`, `node_modules/...`,
+ *     `examples/...`, `e2e/...`).
+ *   - GitHub-style ref (`owner/repo#123`, `org/repo@sha`,
+ *     `path:line`, `path:line-line`).
+ *   - Explicit `path:` / `paths:` / `ref:` / `refs:` marker.
+ *   - Stable cclaw IDs (`R1`, `D-12`, `AC-3`, `T-4`, `S-2`, `DD-5`,
+ *     `ADR-1`, `R-1`, `F-1`, `CR-1`, `I-1`, `QS-1`).
+ *   - Backticked path-like token containing a slash.
+ *
+ * Exposed for unit tests (`tests/unit/investigation-trace-evaluator.test.ts`).
+ */
+export const INVESTIGATION_TRACE_PATH_PATTERNS = [
+    /(?:^|[\s`(\[])(?:[A-Za-z0-9_.-]+\/)+[A-Za-z0-9_.-]+\.(?:ts|tsx|js|jsx|mjs|cjs|md|mdx|json|yaml|yml|toml|sh|py|rs|go|java|kt|swift|rb|css|scss|html)\b/iu,
+    /(?:^|[\s`(\[])(?:src|tests?|docs?|scripts?|e2e|examples?|packages?|apps?|cmd|internal|pkg|lib|app|server|client|backend|frontend|\.cclaw|\.cursor|\.github|node_modules)\/[A-Za-z0-9_./-]+/iu,
+    /\b[A-Za-z0-9_./-]+(?:\.[A-Za-z0-9]+)?:\d+(?:[-:]\d+)?\b/u,
+    /\b[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+(?:#\d+|@[0-9a-f]{6,40})\b/iu,
+    /(?:^|\s)(?:paths?|refs?|file|files|cite|citation)\s*:\s*\S/iu,
+    /\b(?:R|D|AC|T|S|DD|ADR|F|CR|I|QS)-?\d+\b/u,
+    /`[^`]*\/[^`]+`/u
+];
+const INVESTIGATION_TRACE_PLACEHOLDER_PATTERN = /^(?:none|none\.|n\/a|tbd|todo|fixme|placeholder|optional|fill[\s-]?in)\b/u;
+const INVESTIGATION_TRACE_ID_ONLY_CELL = /^[A-Z]{1,4}-?\d+$/u;
+function isInvestigationTracePlaceholderCell(cell) {
+    const stripped = cell.replace(/[`*_>#]/gu, "").trim();
+    if (stripped.length === 0)
+        return true;
+    if (INVESTIGATION_TRACE_PLACEHOLDER_PATTERN.test(stripped.toLowerCase()))
+        return true;
+    return false;
+}
+function isInvestigationTracePlaceholderProseLine(line) {
+    const stripped = line.replace(/[`*_>#-]/gu, "").trim();
+    if (stripped.length === 0)
+        return true;
+    const lower = stripped.toLowerCase();
+    if (INVESTIGATION_TRACE_PLACEHOLDER_PATTERN.test(lower))
+        return true;
+    if (/^\(\s*(?:none|n\/a|tbd|todo|fixme|placeholder|optional|fill[\s-]?in)\b/u.test(lower)) {
+        return true;
+    }
+    return false;
+}
+/**
+ * Internal core that does NOT depend on `StageLintContext`. Returned
+ * shape is consumed by `evaluateInvestigationTrace` (which pushes a
+ * finding into the context) and by unit tests that exercise the
+ * detector directly.
+ *
+ * Returns `null` for sections that are missing, empty, or contain only
+ * template scaffolding (table headers, separators, placeholder rows
+ * with empty cells, lone `- None.` lines). Callers treat `null` as
+ * silent — no finding is emitted.
+ */
+export function checkInvestigationTrace(sectionBody) {
+    if (sectionBody === null)
+        return null;
+    const lines = sectionBody.split(/\r?\n/u);
+    const candidates = [];
+    for (let index = 0; index < lines.length; index += 1) {
+        const raw = lines[index] ?? "";
+        const trimmed = raw.trim();
+        if (trimmed.length === 0)
+            continue;
+        if (trimmed.startsWith("<!--"))
+            continue;
+        const isTableLine = /^\|.*\|$/u.test(trimmed);
+        if (isTableLine) {
+            if (/^\|[-:| ]+\|$/u.test(trimmed))
+                continue; // separator row
+            const next = (lines[index + 1] ?? "").trim();
+            if (/^\|[-:| ]+\|$/u.test(next))
+                continue; // header row (followed by separator)
+            const cells = trimmed
+                .split("|")
+                .slice(1, -1)
+                .map((cell) => cell.trim());
+            const substantive = cells.filter((cell) => !isInvestigationTracePlaceholderCell(cell));
+            if (substantive.length === 0)
+                continue;
+            if (substantive.length === 1 && INVESTIGATION_TRACE_ID_ONLY_CELL.test(substantive[0])) {
+                continue;
+            }
+            candidates.push(substantive.join(" "));
+            continue;
+        }
+        if (isInvestigationTracePlaceholderProseLine(trimmed))
+            continue;
+        candidates.push(trimmed);
+    }
+    if (candidates.length === 0)
+        return null;
+    const sample = candidates.slice(0, Math.min(5, candidates.length));
+    const detectorMatched = sample.some((line) => INVESTIGATION_TRACE_PATH_PATTERNS.some((pattern) => pattern.test(line)));
+    if (detectorMatched) {
+        return {
+            ok: true,
+            details: "Investigation trace cites file paths or refs in the first non-empty row(s)."
+        };
+    }
+    return {
+        ok: false,
+        details: "Investigation trace has prose-only content in its first row(s). Pass paths and refs, not pasted file contents (e.g. `src/foo/bar.ts:42`, `D-12`, `AC-3`)."
+    };
+}
+/**
+ * Round 5 (v6.6.0) — advisory rule wired into the brainstorm / scope /
+ * design / tdd / plan / review linters.
+ *
+ * Behavior contract:
+ * - Section missing or empty / placeholder-only: silent (no finding).
+ * - Section has substantive content with a recognizable file path /
+ *   ref / explicit `path:`-style marker in the first non-empty rows:
+ *   advisory pass (no finding).
+ * - Section has substantive content but no path/ref signal: advisory
+ *   FAIL finding with ruleId `investigation_path_first_missing`.
+ *
+ * The rule is `required: false` so it never blocks `stage-complete`.
+ */
+export function evaluateInvestigationTrace(ctx, sectionName) {
+    const body = sectionBodyByName(ctx.sections, sectionName);
+    const result = checkInvestigationTrace(body);
+    if (result === null)
+        return;
+    ctx.findings.push({
+        section: "investigation_path_first_missing",
+        required: false,
+        rule: `[P3] investigation_path_first_missing — \`## ${sectionName}\` should cite paths and refs in the first non-empty row(s); pass paths and refs, not content.`,
+        found: result.ok,
+        details: result.details
+    });
+}
 export function lineContainsVagueAdjective(text) {
     const lower = text.toLowerCase();
     for (const adjective of VAGUE_AC_ADJECTIVES) {

package/dist/artifact-linter/tdd.js

@@ -1,9 +1,10 @@
 import fs from "node:fs/promises";
 import path from "node:path";
 import { readDelegationLedger } from "../delegation.js";
-import { sectionBodyByName } from "./shared.js";
+import { evaluateInvestigationTrace, sectionBodyByName } from "./shared.js";
 export async function lintTddStage(ctx) {
     const { projectRoot, track, raw, absFile, sections, findings, parsedFrontmatter, brainstormShortCircuitBody, brainstormShortCircuitActivated, staleDiagramAuditEnabled, isTrivialOverride } = ctx;
+    evaluateInvestigationTrace(ctx, "Watched-RED Proof");
     // Universal Layer 2.6 structural checks (superpowers TDD + evanflow vertical slices).
     const ironLawBody = sectionBodyByName(sections, "Iron Law Acknowledgement");
     if (ironLawBody === null) {

package/dist/artifact-linter.d.ts

@@ -1,7 +1,7 @@
 import type { FlowStage, FlowTrack } from "./types.js";
 import { type LintResult } from "./artifact-linter/shared.js";
 export { validateReviewArmy, checkReviewVerdictConsistency, checkReviewSecurityNoChangeAttestation, checkReviewTddNoCrossArtifactDuplication, type ReviewVerdictConsistencyResult, type ReviewSecurityNoChangeAttestationResult, type ReviewTddDuplicationConflict, type ReviewTddDuplicationResult } from "./artifact-linter/review-army.js";
-export { type LintFinding, type LintResult, type LearningEntryType, type LearningConfidence, type LearningSeverity, type LearningSource, type LearningSeedEntry, type LearningsParseResult, formatLearningsErrorsBullets, learningsParseFailureHumanSummary, extractMarkdownSectionBody, parseLearningsSection } from "./artifact-linter/shared.js";
+export { type LintFinding, type LintResult, type LearningEntryType, type LearningConfidence, type LearningSeverity, type LearningSource, type LearningSeedEntry, type LearningsParseResult, extractAuthoredBody, formatLearningsErrorsBullets, learningsParseFailureHumanSummary, extractMarkdownSectionBody, parseLearningsSection } from "./artifact-linter/shared.js";
 export interface LintArtifactOptions {
     /**
      * Stage-level flags supplied by the caller (typically `advance-stage`)

package/dist/artifact-linter.js

@@ -5,7 +5,8 @@ import { stageSchema } from "./content/stage-schema.js";
 import { readFlowState } from "./run-persistence.js";
 import { duplicateH2Headings, extractH2Sections, extractRequirementIdsFromMarkdown, isShortCircuitActivated, normalizeHeadingTitle, parseFrontmatter, parseLearningsSection, sectionBodyByAnyName, sectionBodyByHeadingPrefix, sectionBodyByName, validateSectionBody, formatLearningsErrorsBullets } from "./artifact-linter/shared.js";
 import { shouldDemoteArtifactValidationByTrack } from "./content/stage-schema.js";
-import { recordArtifactValidationDemotedByTrack } from "./delegation.js";
+import { readDelegationLedger, recordArtifactValidationDemotedByTrack } from "./delegation.js";
+import { classifyAndPersistFindings } from "./artifact-linter/findings-dedup.js";
 import { lintBrainstormStage } from "./artifact-linter/brainstorm.js";
 import { lintDesignStage } from "./artifact-linter/design.js";
 import { lintPlanStage } from "./artifact-linter/plan.js";
@@ -15,7 +16,7 @@ import { lintTddStage } from "./artifact-linter/tdd.js";
 import { lintReviewStage } from "./artifact-linter/review.js";
 import { lintShipStage } from "./artifact-linter/ship.js";
 export { validateReviewArmy, checkReviewVerdictConsistency, checkReviewSecurityNoChangeAttestation, checkReviewTddNoCrossArtifactDuplication } from "./artifact-linter/review-army.js";
-export { formatLearningsErrorsBullets, learningsParseFailureHumanSummary, extractMarkdownSectionBody, parseLearningsSection } from "./artifact-linter/shared.js";
+export { extractAuthoredBody, formatLearningsErrorsBullets, learningsParseFailureHumanSummary, extractMarkdownSectionBody, parseLearningsSection } from "./artifact-linter/shared.js";
 const FRONTMATTER_REQUIRED_KEYS = [
     "stage",
     "schema_version",
@@ -328,6 +329,30 @@ export async function lintArtifact(projectRoot, stage, track = "standard", optio
             });
         }
     }
+    try {
+        const delegationLedger = await readDelegationLedger(projectRoot);
+        const legacyWaivers = delegationLedger.entries.filter((entry) => entry.status === "waived" &&
+            entry.mode === "proactive" &&
+            entry.stage === stage &&
+            (typeof entry.approvalToken !== "string" || entry.approvalToken.trim().length === 0));
+        if (legacyWaivers.length > 0) {
+            const descriptors = legacyWaivers
+                .map((entry) => [entry.agent, entry.spanId].filter((value) => typeof value === "string").join("@"))
+                .filter((value) => value.length > 0);
+            findings.push({
+                section: "waiver_legacy_provenance",
+                required: false,
+                rule: "waiver_legacy_provenance — proactive waiver(s) without approvalToken. Issue new waivers via `cclaw-cli internal waiver-grant --stage <stage> --reason <slug>` so the provenance trail is signed. Legacy waivers remain valid (advisory).",
+                found: false,
+                details: `Found ${legacyWaivers.length} proactive waiver(s) on stage="${stage}" without approvalToken` +
+                    (descriptors.length > 0 ? ` (${descriptors.join(", ")})` : "") +
+                    ". Next waiver should be issued with `cclaw-cli internal waiver-grant` and consumed via `--accept-proactive-waiver=<token>`."
+            });
+        }
+    }
+    catch {
+        // Ledger absent or unreadable: no advisory to emit.
+    }
     const demote = shouldDemoteArtifactValidationByTrack(track, taskClass);
     const demotedSections = [];
     if (demote) {
@@ -356,7 +381,24 @@ export async function lintArtifact(projectRoot, stage, track = "standard", optio
         }
     }
     const passed = findings.every((f) => !f.required || f.found);
-    return { stage, file: relFile, passed, findings };
+    let dedup;
+    try {
+        const dedupResult = await classifyAndPersistFindings(projectRoot, stage, findings);
+        const statusByFingerprint = new Map(dedupResult.classified.map(({ fingerprint, status }) => [fingerprint, status]));
+        const statuses = dedupResult.classified.map(({ status }) => status);
+        void statusByFingerprint;
+        dedup = {
+            newCount: dedupResult.summary.newCount,
+            repeatCount: dedupResult.summary.repeatCount,
+            resolvedCount: dedupResult.summary.resolvedCount,
+            header: dedupResult.header,
+            statuses
+        };
+    }
+    catch {
+        dedup = undefined;
+    }
+    return { stage, file: relFile, passed, findings, ...(dedup ? { dedup } : {}) };
 }
 /**
  * Wave 25 (v6.1.0) — section names whose required-finding outcome is

package/dist/content/examples.d.ts

@@ -1,4 +1,36 @@
 import type { FlowStage } from "../types.js";
+/**
+ * Round 5 (v6.6.0) — short bad → good behavior anchor per stage.
+ *
+ * Each entry is rendered exactly once in the corresponding stage skill md
+ * (via `behaviorAnchorBlock` in `skills.ts`) and exactly once in the stage's
+ * artifact template (via `renderBehaviorAnchorTemplateLine`). Anchors are
+ * deliberately attached to a real artifact section name so the cross-check
+ * test in `tests/unit/behavior-anchors.test.ts` can verify the section
+ * exists in the stage's schema.
+ *
+ * Constraints enforced by the unit test:
+ * - Exactly one entry per FlowStage (8 total).
+ * - `bad` and `good` must be distinct across stages and ≤ 40 words each.
+ * - `section` must match a section name present in
+ *   `stageSchema(stage).artifactRules.artifactValidation`.
+ */
+export interface BehaviorAnchor {
+    stage: FlowStage;
+    section: string;
+    bad: string;
+    good: string;
+    ruleHint?: string;
+}
+export declare const BEHAVIOR_ANCHORS: ReadonlyArray<BehaviorAnchor>;
+export declare function behaviorAnchorFor(stage: FlowStage): BehaviorAnchor | null;
+/**
+ * Render the one-line "Behavior anchor (bad → good)" pointer used at the top
+ * of each artifact template (01..08). Templates carry the anchor inline so
+ * agents see it before they start filling sections; the prose itself lives
+ * only in `BEHAVIOR_ANCHORS` to avoid duplication.
+ */
+export declare function renderBehaviorAnchorTemplateLine(stage: FlowStage): string;
 export declare function stageGoodBadExamples(stage: FlowStage): string;
 /**
  * Returns the full example artifact body for tests and internal quality checks.

package/dist/content/examples.js

@@ -1,3 +1,77 @@
+export const BEHAVIOR_ANCHORS = [
+    {
+        stage: "brainstorm",
+        section: "Problem Decision Record",
+        bad: "Frame the problem broadly and quietly add a second outcome (\"and while we're at it, refresh the dashboard\") that no Q&A row sanctioned.",
+        good: "Name one affected user, one current failure mode, and one observable outcome; record any extra outcome as a separate row in `## Not Doing`.",
+        ruleHint: "Scope creep starts in framing — keep the Problem Decision Record single-target."
+    },
+    {
+        stage: "scope",
+        section: "Scope Contract",
+        bad: "Invent a contract from a hunch: \"I'll let the user choose 3 templates\" with no Q&A row, no user feedback citation, no upstream decision.",
+        good: "Cite the Q&A row or upstream decision (`brainstorm > Selected Direction`) that produced each in/out boundary; refuse to lock without that citation.",
+        ruleHint: "Every scope contract row must trace to a recorded user signal or carried-forward decision."
+    },
+    {
+        stage: "design",
+        section: "Codebase Investigation",
+        bad: "Open with \"Use a queue + worker pool\" before reading any file; the architecture choice precedes the trace and the diagram has no concrete node.",
+        good: "List 1-3 blast-radius files in `Codebase Investigation` with current responsibility and reuse candidate first; only then propose architecture in `ADR`.",
+        ruleHint: "Trace before lock — no architecture decision lands without a codebase citation."
+    },
+    {
+        stage: "spec",
+        section: "Acceptance Criteria",
+        bad: "AC: \"System should be fast and reliable\" — no measurable predicate, no verification approach, no design-decision ref.",
+        good: "AC: \"GET /feed returns ≤ 50 items in < 200 ms p95; verified via integration test `tests/feed.spec.ts` against scope `R-2`.\"",
+        ruleHint: "Every AC carries an observable predicate plus the exact evidence command or path that proves it."
+    },
+    {
+        stage: "plan",
+        section: "Execution Posture",
+        bad: "Posture: \"parallel-safe\" with three units that all edit the same `src/api/router.ts`; no shared interface contract, no boundary map.",
+        good: "Posture: \"parallel-safe\" only when each Implementation Unit owns disjoint files and the shared types live in one cited interface contract entry.",
+        ruleHint: "Parallelization needs disjoint units AND a single shared interface contract — claim otherwise and the next batch deadlocks."
+    },
+    {
+        stage: "tdd",
+        section: "RED Evidence",
+        bad: "RED: `expect(true).toBe(true)` then \"failing test observed\" — the assertion can never have caught the bug it claims to prove.",
+        good: "RED: `expect(api.fetchFeed()).rejects.toThrow(AuthError)`; the failure output names the missing guard and ties to AC-3.",
+        ruleHint: "Mental mutation test: name a plausible bug that would still pass the assertion. If you can, the assertion is too coarse."
+    },
+    {
+        stage: "review",
+        section: "Layer 2 Findings",
+        bad: "Slip in a rename of `userSvc` → `userService` and a folder reorg under \"Layer 2: cleanup\"; no acceptance criterion or finding ID demanded the change.",
+        good: "Findings name observed defects with `file:line`; refactors land as a separate slice with their own RED/GREEN, not bundled into the review pass.",
+        ruleHint: "Review surfaces findings; it does not refactor. Drive-by edits go back through TDD."
+    },
+    {
+        stage: "ship",
+        section: "Preflight Results",
+        bad: "Preflight: \"Looks good, tests passed last night\"; no fresh command output, no commit SHA, no exit code.",
+        good: "Preflight: paste the command, the exit code, and the commit SHA from this turn; if the suite was not re-run after the last edit, mark BLOCKED.",
+        ruleHint: "Victory-by-confidence is not a preflight. Re-run, capture, cite SHA — or stay BLOCKED."
+    }
+];
+const BEHAVIOR_ANCHOR_BY_STAGE = new Map(BEHAVIOR_ANCHORS.map((entry) => [entry.stage, entry]));
+export function behaviorAnchorFor(stage) {
+    return BEHAVIOR_ANCHOR_BY_STAGE.get(stage) ?? null;
+}
+/**
+ * Render the one-line "Behavior anchor (bad → good)" pointer used at the top
+ * of each artifact template (01..08). Templates carry the anchor inline so
+ * agents see it before they start filling sections; the prose itself lives
+ * only in `BEHAVIOR_ANCHORS` to avoid duplication.
+ */
+export function renderBehaviorAnchorTemplateLine(stage) {
+    const anchor = behaviorAnchorFor(stage);
+    if (!anchor)
+        return "";
+    return `> Behavior anchor (bad -> good) — ${anchor.section}: bad: ${anchor.bad} good: ${anchor.good}`;
+}
 const STAGE_EXAMPLES = {
     brainstorm: `## Context
 

package/dist/content/hooks.js

@@ -191,7 +191,7 @@ export function cancelRunScript() {
     return internalHelperScript("cancel-run", "cancel-run", "Usage: node " + RUNTIME_ROOT + "/hooks/cancel-run.mjs --reason=<text> [--disposition=<cancelled|abandoned>] [--name=<slug>]");
 }
 export function stageCompleteScript() {
-    return internalHelperScript("stage-complete", "advance-stage", "Usage: node " + RUNTIME_ROOT + "/hooks/stage-complete.mjs <stage> [--passed=...] [--evidence-json=...] [--waive-delegation=...] [--waiver-reason=...] [--accept-proactive-waiver] [--accept-proactive-waiver-reason=\"<why safe>\"] [--skip-questions] [--json]", {
+    return internalHelperScript("stage-complete", "advance-stage", "Usage: node " + RUNTIME_ROOT + "/hooks/stage-complete.mjs <stage> [--passed=...] [--evidence-json=...] [--waive-delegation=...] [--waiver-reason=...] [--accept-proactive-waiver=<token>] [--accept-proactive-waiver-reason=\"<why safe>\"] [--skip-questions] [--json]", {
         positionalArgName: "stage",
         positionalArgRequired: true,
         defaultQuietEnvVar: "CCLAW_STAGE_COMPLETE_QUIET"
@@ -199,6 +199,7 @@ export function stageCompleteScript() {
 }
 export function delegationRecordScript() {
     return `#!/usr/bin/env node
+import { createHash } from "node:crypto";
 import fs from "node:fs/promises";
 import path from "node:path";
 import process from "node:process";
@@ -210,6 +211,37 @@ const VALID_DISPATCH_SURFACES = ${JSON.stringify([...DELEGATION_DISPATCH_SURFACE
 const VALID_DISPATCH_SURFACES_SET = new Set(VALID_DISPATCH_SURFACES);
 const SURFACE_PATH_PREFIXES = ${JSON.stringify(DELEGATION_DISPATCH_SURFACE_PATH_PREFIXES)};
 const LEDGER_SCHEMA_VERSION = 3;
+const FLOW_STATE_GUARD_REL_PATH = RUNTIME_ROOT + "/.flow-state.guard.json";
+
+async function verifyFlowStateGuardInline(root) {
+  const statePath = path.join(root, RUNTIME_ROOT, "state", "flow-state.json");
+  const guardPath = path.join(root, FLOW_STATE_GUARD_REL_PATH);
+  let raw;
+  try {
+    raw = await fs.readFile(statePath, "utf8");
+  } catch {
+    return;
+  }
+  let guard;
+  try {
+    const guardRaw = await fs.readFile(guardPath, "utf8");
+    guard = JSON.parse(guardRaw);
+  } catch {
+    return;
+  }
+  if (!guard || typeof guard !== "object" || typeof guard.sha256 !== "string") return;
+  const actual = createHash("sha256").update(raw, "utf8").digest("hex");
+  if (actual === guard.sha256) return;
+  process.stderr.write(
+    "[cclaw] delegation-record: flow-state guard mismatch: " + (guard.runId || "unknown-run") + "\\n" +
+      "expected sha: " + guard.sha256 + "\\n" +
+      "actual sha:   " + actual + "\\n" +
+      "last writer:  " + (guard.writerSubsystem || "unknown") + "@" + (guard.writtenAt || "unknown") + "\\n" +
+      "do not edit flow-state.json by hand. To recover, run:\\n" +
+      "  cclaw-cli internal flow-state-repair --reason \\"manual_edit_recovery\\"\\n"
+  );
+  process.exit(2);
+}
 
 function parseArgs(argv) {
   const args = {};
@@ -693,6 +725,9 @@ async function main() {
   const args = parseArgs(process.argv.slice(2));
   const json = args.json !== undefined;
 
+  const guardRoot = await detectRoot();
+  await verifyFlowStateGuardInline(guardRoot);
+
   if (args.repair) {
     await runRepair(args, json);
     return;

package/dist/content/node-hooks.js

@@ -49,12 +49,14 @@ export function nodeHookRuntimeScript(options = {}) {
     const defaultDisabledHooks = [];
     const cliRuntime = resolveCliRuntimeForGeneratedHook();
     return `#!/usr/bin/env node
+import { createHash } from "node:crypto";
 import fs from "node:fs/promises";
 import path from "node:path";
 import process from "node:process";
 import { spawn } from "node:child_process";
 
 const RUNTIME_ROOT = ${JSON.stringify(RUNTIME_ROOT)};
+const FLOW_STATE_GUARD_REL_PATH = RUNTIME_ROOT + "/.flow-state.guard.json";
 // Single strictness default, derived from config.strictness at install time.
 // \`CCLAW_STRICTNESS\` env var overrides for the current process. All guards
 // (prompt, workflow, TDD, iron-laws) route through \`resolveStrictness()\`.
@@ -1017,6 +1019,40 @@ function extractCodePathsFromText(value) {
   return out;
 }
 
+async function verifyFlowStateGuardInline(root, hookName) {
+  const statePath = path.join(root, RUNTIME_ROOT, "state", "flow-state.json");
+  const guardPath = path.join(root, FLOW_STATE_GUARD_REL_PATH);
+  let raw;
+  try {
+    raw = await fs.readFile(statePath, "utf8");
+  } catch {
+    return true;
+  }
+  let guard;
+  try {
+    const guardRaw = await fs.readFile(guardPath, "utf8");
+    guard = JSON.parse(guardRaw);
+  } catch {
+    return true;
+  }
+  if (!guard || typeof guard !== "object" || typeof guard.sha256 !== "string") {
+    return true;
+  }
+  const actual = createHash("sha256").update(raw, "utf8").digest("hex");
+  if (actual === guard.sha256) return true;
+  const hookLabel = typeof hookName === "string" && hookName.length > 0 ? hookName : "hook";
+  process.stderr.write(
+    "[cclaw] " + hookLabel + ": flow-state guard mismatch: " + (guard.runId || "unknown-run") + "\\n" +
+      "expected sha: " + guard.sha256 + "\\n" +
+      "actual sha:   " + actual + "\\n" +
+      "last writer:  " + (guard.writerSubsystem || "unknown") + "@" + (guard.writtenAt || "unknown") + "\\n" +
+      "do not edit flow-state.json by hand. To recover, run:\\n" +
+      "  cclaw-cli internal flow-state-repair --reason \\"manual_edit_recovery\\"\\n"
+  );
+  await recordHookError(root, hookLabel, "flow-state guard mismatch actual=" + actual + " expected=" + guard.sha256).catch(() => undefined);
+  return false;
+}
+
 async function readFlowState(root) {
   const statePath = path.join(root, RUNTIME_ROOT, "state", "flow-state.json");
   // Loud-on-corrupt: if flow-state.json exists but fails JSON.parse, log
@@ -2110,6 +2146,13 @@ async function main() {
   };
 
   try {
+    if (hookName === "session-start" || hookName === "stop-handoff") {
+      const guardOk = await verifyFlowStateGuardInline(runtime.root, hookName);
+      if (!guardOk) {
+        process.exitCode = 2;
+        return;
+      }
+    }
     if (hookName === "session-start") {
       process.exitCode = await handleSessionStart(runtime);
       return;

package/dist/content/skills-elicitation.js

@@ -29,7 +29,7 @@ Pinned anchor: "Don't tell it what to do, give it success criteria and watch it
 These behaviors are the exact reason this skill exists. The linter will block your stage-complete if you do them.
 
 - **Bad**: User asks for a "simple web app" -> agent asks 1 question about stack -> 1 question about auth -> drafts the brainstorm artifact and asks for approval.
-- **Good**: User asks for a "simple web app" -> agent asks Q1 (what pain) -> Q2 (direct path) -> Q3 (do-nothing cost) -> Q4 (first operator/user) -> Q5 (no-go boundaries) -> self-eval: clear -> drafts the brainstorm artifact.
+- **Good**: User asks for a "simple web app" -> agent asks Q1 (what pain) -> Q2 (direct path) -> Q3 (first operator/user) -> Q4 (no-go boundaries) -> self-eval: clear -> drafts the brainstorm artifact.
 
 - **Bad**: Agent immediately dispatches a subagent (\`product-discovery\`, \`critic\`, \`planner\`) at the start of brainstorm/scope/design to "gather context" before any user dialogue.
 - **Good**: Agent walks the Q&A loop with the user first; subagent dispatch happens only after the user approves the elicitation outcome.
@@ -121,7 +121,7 @@ Default mapping note: \`lean\` maps to a lightweight specialist tier on early st
 
 ### Topic tagging (MANDATORY for forcing-question rows)
 
-Each forcing question has a stable topic id (kebab-case ASCII, e.g. \`pain\`, \`do-nothing\`, \`data-flow\`). Tag the matching Q&A Log row's \`Decision impact\` cell with \`[topic:<id>]\` so the linter can verify coverage in any natural language. This is a **HARD requirement** in Wave 24 (v6.0.0): the linter no longer keyword-matches English question prose, so an un-tagged row does NOT count toward coverage even if the answer fully addresses the topic.
+Each forcing question has a stable topic id (kebab-case ASCII, e.g. \`pain\`, \`direct-path\`, \`data-flow\`). Tag the matching Q&A Log row's \`Decision impact\` cell with \`[topic:<id>]\` so the linter can verify coverage in any natural language. This is a **HARD requirement** in Wave 24 (v6.0.0): the linter no longer keyword-matches English question prose, so an un-tagged row does NOT count toward coverage even if the answer fully addresses the topic.
 
 RU example (after asking \`pain\` in Russian):
 
@@ -131,21 +131,18 @@ RU example (after asking \`pain\` in Russian):
 | 1 | Какую боль мы решаем? | Регистрация занимает 30 минут. | scope-shaping [topic:pain] |
 \`\`\`
 
-Multiple tags in one row are allowed when one answer covers several topics: \`[topic:pain] [topic:do-nothing]\`. Stop-signal rows do NOT need a tag.
+Multiple tags in one row are allowed when one answer covers several topics: \`[topic:pain] [topic:direct-path]\`. Stop-signal rows do NOT need a tag.
 
 Stage forcing question lists (id → topic):
 
 - **Brainstorm**:
   - \`pain\` — What pain are we solving?
   - \`direct-path\` — What is the most direct path?
-  - \`do-nothing\` — What happens if we do nothing?
   - \`operator\` — Who is the operator/user impacted first?
   - \`no-go\` — What are non-negotiable no-go boundaries?
 - **Scope**:
   - \`in-out\` — What is definitely in and definitely out?
   - \`locked-upstream\` — Which decisions are already locked upstream?
-  - \`rollback\` — What is the rollback path if this fails?
-  - \`failure-modes\` — What are the top failure modes we must design for?
 - **Design**:
   - \`data-flow\` — What is the data flow end-to-end?
   - \`seams\` — Where are the seams/interfaces and ownership boundaries?

package/dist/content/skills.d.ts

@@ -8,6 +8,16 @@ export declare function outsideVoiceSlotBlock(): string;
 export declare function antiSycophancyBlock(): string;
 export declare function noPlaceholdersBlock(): string;
 export declare function watchedFailProofBlock(): string;
+/**
+ * Stages that perform real investigation work. The shared
+ * `INVESTIGATION_DISCIPLINE_BLOCK` is rendered once per stage skill in this
+ * set so the search → graph → narrow-read → draft ladder appears verbatim
+ * across the elicitation/spec/plan/tdd/review pipeline. `ship` is excluded:
+ * it consumes the upstream trace rather than producing one.
+ */
+export declare const INVESTIGATION_DISCIPLINE_STAGES: ReadonlySet<FlowStage>;
+export declare function investigationDisciplineBlock(): string;
+export declare function behaviorAnchorBlock(stage: FlowStage): string;
 export declare function stageSkillFolder(stage: FlowStage): string;
 export declare function stageSkillMarkdown(stage: FlowStage, track?: FlowTrack): string;
 export declare function executingWavesSkillMarkdown(): string;