cclaw-cli 6.4.0 → 6.6.0

package/dist/artifact-linter/brainstorm.js

@@ -1,9 +1,10 @@
 import fs from "node:fs/promises";
 import path from "node:path";
-import { checkCriticPredictionsContract, evaluateQaLogFloor, sectionBodyByName, validateApproachesTaxonomy, headingLineIndex, meaningfulLineCount, getMarkdownTableRows, parseShortCircuitStatus, validateCalibratedSelfReview, markdownFieldRegex } from "./shared.js";
+import { checkCriticPredictionsContract, evaluateInvestigationTrace, evaluateQaLogFloor, sectionBodyByName, validateApproachesTaxonomy, headingLineIndex, meaningfulLineCount, getMarkdownTableRows, parseShortCircuitStatus, validateCalibratedSelfReview, markdownFieldRegex } from "./shared.js";
 import { readFlowState } from "../run-persistence.js";
 export async function lintBrainstormStage(ctx) {
     const { projectRoot, track, raw, absFile, sections, findings, parsedFrontmatter, brainstormShortCircuitBody, brainstormShortCircuitActivated, staleDiagramAuditEnabled, isTrivialOverride } = ctx;
+    evaluateInvestigationTrace(ctx, "Q&A Log");
     const qaLogBody = sectionBodyByName(sections, "Q&A Log");
     const qaLogRows = qaLogBody ? getMarkdownTableRows(qaLogBody) : [];
     const qaLogOk = qaLogBody !== null && qaLogRows.length > 0;

package/dist/artifact-linter/design.js

@@ -3,7 +3,7 @@ import path from "node:path";
 import { resolveArtifactPath as resolveStageArtifactPath } from "../artifact-paths.js";
 import { exists } from "../fs-utils.js";
 import { CONFIDENCE_FINDING_REGEX_SOURCE } from "../content/skills.js";
-import { checkCriticPredictionsContract, evaluateLayeredDocumentReviewStatus, evaluateQaLogFloor, extractMarkdownSectionBody, getMarkdownTableRows, meaningfulLineCount, sectionBodyByName, markdownFieldRegex } from "./shared.js";
+import { checkCriticPredictionsContract, evaluateInvestigationTrace, evaluateLayeredDocumentReviewStatus, evaluateQaLogFloor, extractMarkdownSectionBody, getMarkdownTableRows, meaningfulLineCount, sectionBodyByName, markdownFieldRegex } from "./shared.js";
 const DESIGN_DIAGRAM_REQUIREMENTS = {
     lightweight: [
         {
@@ -268,6 +268,7 @@ async function runStaleDiagramAudit(projectRoot, artifactPath, artifactRaw, code
 }
 export async function lintDesignStage(ctx) {
     const { projectRoot, track, raw, absFile, sections, findings, parsedFrontmatter, brainstormShortCircuitBody, brainstormShortCircuitActivated, staleDiagramAuditEnabled, isTrivialOverride, activeStageFlags } = ctx;
+    evaluateInvestigationTrace(ctx, "Codebase Investigation");
     const qaLogBody = sectionBodyByName(sections, "Q&A Log");
     const qaLogRows = qaLogBody ? getMarkdownTableRows(qaLogBody) : [];
     const qaLogOk = qaLogBody !== null && qaLogRows.length > 0;

package/dist/artifact-linter/plan.js

@@ -1,10 +1,11 @@
-import { evaluateLayeredDocumentReviewStatus, headingPresent, sectionBodyByName, collectPatternHits, PLACEHOLDER_PATTERNS, extractDecisionIds, SCOPE_REDUCTION_PATTERNS } from "./shared.js";
+import { evaluateInvestigationTrace, evaluateLayeredDocumentReviewStatus, headingPresent, sectionBodyByName, collectPatternHits, PLACEHOLDER_PATTERNS, extractDecisionIds, SCOPE_REDUCTION_PATTERNS } from "./shared.js";
 import { resolveArtifactPath as resolveStageArtifactPath } from "../artifact-paths.js";
 import { exists } from "../fs-utils.js";
 import { FORBIDDEN_PLACEHOLDER_TOKENS, CONFIDENCE_FINDING_REGEX_SOURCE } from "../content/skills.js";
 import fs from "node:fs/promises";
 export async function lintPlanStage(ctx) {
     const { projectRoot, track, raw, absFile, sections, findings, parsedFrontmatter, brainstormShortCircuitBody, brainstormShortCircuitActivated, staleDiagramAuditEnabled, isTrivialOverride } = ctx;
+    evaluateInvestigationTrace(ctx, "Implementation Units");
     const strictPlanGuards = parsedFrontmatter.hasFrontmatter ||
         headingPresent(sections, "Plan Quality Scan") ||
         headingPresent(sections, "Locked Decision Coverage");

package/dist/artifact-linter/review.js

@@ -1,7 +1,8 @@
-import { markdownFieldRegex, sectionBodyByName } from "./shared.js";
+import { evaluateInvestigationTrace, markdownFieldRegex, sectionBodyByName } from "./shared.js";
 import { checkReviewTddNoCrossArtifactDuplication } from "./review-army.js";
 export async function lintReviewStage(ctx) {
     const { projectRoot, track, raw, absFile, sections, findings, parsedFrontmatter, brainstormShortCircuitBody, brainstormShortCircuitActivated, staleDiagramAuditEnabled, isTrivialOverride } = ctx;
+    evaluateInvestigationTrace(ctx, "Changed-File Coverage");
     // Universal Layer 2.7 structural checks (superpowers requesting + receiving).
     const frameBody = sectionBodyByName(sections, "Pre-Critic Self-Review");
     if (frameBody !== null) {

package/dist/artifact-linter/scope.js

@@ -1,9 +1,10 @@
-import { checkCriticPredictionsContract, evaluateQaLogFloor, sectionBodyByHeadingPrefix, sectionBodyByName, extractCanonicalScopeMode, getMarkdownTableRows } from "./shared.js";
+import { checkCriticPredictionsContract, evaluateInvestigationTrace, evaluateQaLogFloor, sectionBodyByHeadingPrefix, sectionBodyByName, extractCanonicalScopeMode, getMarkdownTableRows } from "./shared.js";
 import { readDelegationLedger, recordExpansionStrategistSkippedByTrack } from "../delegation.js";
 import { shouldDemoteArtifactValidationByTrack } from "../content/stage-schema.js";
 import { readFlowState } from "../run-persistence.js";
 export async function lintScopeStage(ctx) {
     const { projectRoot, track, raw, absFile, sections, findings, parsedFrontmatter, brainstormShortCircuitBody, brainstormShortCircuitActivated, staleDiagramAuditEnabled, isTrivialOverride, activeStageFlags, taskClass } = ctx;
+    evaluateInvestigationTrace(ctx, "Q&A Log");
     const lockedDecisionsBody = sectionBodyByHeadingPrefix(sections, "Locked Decisions") ?? "";
     const scopeSummaryBody = sectionBodyByName(sections, "Scope Summary") ?? "";
     const selectedScopeMode = extractCanonicalScopeMode(scopeSummaryBody);
@@ -43,11 +44,11 @@ export async function lintScopeStage(ctx) {
         const skipByTrack = shouldDemoteArtifactValidationByTrack(track, taskClass);
         if (skipByTrack) {
             findings.push({
-                section: "Expansion Strategist Delegation",
+                section: "Product Discovery Delegation (Strategist Mode)",
                 required: false,
                 rule: "When Scope Summary selects SCOPE EXPANSION or SELECTIVE EXPANSION, a completed `product-discovery` delegation for the active run with non-empty evidenceRefs is required.",
                 found: true,
-                details: `Expansion Strategist delegation requirement skipped for track="${track}"` +
+                details: `Product-discovery delegation requirement skipped for track="${track}"` +
                     (taskClass ? `, taskClass="${taskClass}"` : "") +
                     ` (Wave 25: lite-tier escape; selectedMode=${selectedScopeMode}).`
             });
@@ -78,12 +79,12 @@ export async function lintScopeStage(ctx) {
             const hasCompleted = discoveryRows.length > 0;
             const hasEvidence = discoveryRows.some((entry) => Array.isArray(entry.evidenceRefs) && entry.evidenceRefs.length > 0);
             findings.push({
-                section: "Expansion Strategist Delegation",
+                section: "Product Discovery Delegation (Strategist Mode)",
                 required: true,
                 rule: "When Scope Summary selects SCOPE EXPANSION or SELECTIVE EXPANSION, a completed `product-discovery` delegation for the active run with non-empty evidenceRefs is required.",
                 found: hasCompleted && hasEvidence,
                 details: !hasCompleted
-                    ? `Scope mode ${selectedScopeMode} requires a completed product-discovery delegation row for active run ${delegationLedger.runId}.`
+                    ? `Scope mode ${selectedScopeMode} requires a completed product-discovery delegation row for active run ${delegationLedger.runId}. In SELECTIVE EXPANSION / SCOPE EXPANSION, run product-discovery (mode=proactive) BEFORE stage-complete.`
                     : hasEvidence
                         ? `product-discovery delegation satisfied for mode ${selectedScopeMode}.`
                         : "product-discovery delegation exists but evidenceRefs is empty; add at least one artifact/code evidence reference."

package/dist/artifact-linter/shared.d.ts

@@ -403,6 +403,60 @@ export declare function parseLearningSeedEntry(raw: unknown, index: number): {
     error?: string;
 };
 export declare function parseLearningsSection(sectionBody: string): LearningsParseResult;
+/**
+ * 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 declare const INVESTIGATION_TRACE_PATH_PATTERNS: readonly RegExp[];
+export interface InvestigationTraceFinding {
+    ok: boolean;
+    details: string;
+}
+/**
+ * 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 declare function checkInvestigationTrace(sectionBody: string | null): InvestigationTraceFinding | null;
+/**
+ * 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 declare function evaluateInvestigationTrace(ctx: StageLintContext, sectionName: string): void;
 export declare function lineContainsVagueAdjective(text: string): string | null;
 export interface ParsedFrontmatter {
     hasFrontmatter: boolean;

package/dist/artifact-linter/shared.js

@@ -1715,6 +1715,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.js

@@ -367,7 +367,7 @@ export async function lintArtifact(projectRoot, stage, track = "standard", optio
  *  - `Architecture Diagram` — sync/async + failure-edge enforcement
  *  - `Data Flow` — Interaction Edge Case mandatory rows
  *  - `Stale Diagram Drift Check` — blast-radius file mtime audit
- *  - `Expansion Strategist Delegation` — product-discovery delegation
+ *  - `Product Discovery Delegation (Strategist Mode)` — product-discovery delegation
  *
  * Findings remain in the result so the caller can surface them as
  * advisory hints; only `required` flips to `false`.
@@ -376,5 +376,5 @@ const ARTIFACT_VALIDATION_LITE_DEMOTE_SECTIONS = new Set([
     "Architecture Diagram",
     "Data Flow",
     "Stale Diagram Drift Check",
-    "Expansion Strategist Delegation"
+    "Product Discovery Delegation (Strategist Mode)"
 ]);

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

@@ -380,6 +380,47 @@ function buildRow(args, status, runId, now) {
   };
 }
 
+async function acquireDelegationLogLock(stateDir) {
+  const lockDir = path.join(stateDir, "delegation-log.json.lock");
+  const maxWaitMs = 3000;
+  const startMs = Date.now();
+  let delayMs = 25;
+  while (true) {
+    try {
+      await fs.mkdir(lockDir, { recursive: false });
+      return lockDir;
+    } catch (err) {
+      const code = err && typeof err === "object" && "code" in err ? err.code : "";
+      if (code !== "EEXIST") throw err;
+      if (Date.now() - startMs >= maxWaitMs) {
+        process.stderr.write(
+          "[cclaw] delegation-record: timeout waiting for delegation-log.json.lock (max " + maxWaitMs + "ms)\\n"
+        );
+        process.exit(2);
+      }
+      const jitter = Math.floor(Math.random() * 25);
+      await new Promise((resolve) => setTimeout(resolve, delayMs + jitter));
+      delayMs = Math.min(delayMs * 2, 200);
+    }
+  }
+}
+
+async function releaseDelegationLogLock(lockDir) {
+  try {
+    await fs.rm(lockDir, { recursive: true, force: true });
+  } catch {
+    // best-effort release
+  }
+}
+
+async function writeDelegationLedgerAtomic(ledgerPath, ledger) {
+  const dir = path.dirname(ledgerPath);
+  const tmp =
+    path.join(dir, ".delegation-log.json." + process.pid + "." + Date.now() + "." + Math.random().toString(16).slice(2) + ".tmp");
+  await fs.writeFile(tmp, JSON.stringify(ledger, null, 2) + "\\n", { encoding: "utf8", mode: 0o600 });
+  await fs.rename(tmp, ledgerPath);
+}
+
 async function persistEntry(root, runId, clean, event, options = {}) {
   const stateDir = path.join(root, RUNTIME_ROOT, "state");
   await fs.mkdir(stateDir, { recursive: true });
@@ -387,29 +428,34 @@ async function persistEntry(root, runId, clean, event, options = {}) {
 
   const ledgerPath = path.join(stateDir, "delegation-log.json");
   let ledger = { runId, entries: [], schemaVersion: LEDGER_SCHEMA_VERSION };
+  const lockDir = await acquireDelegationLogLock(stateDir);
   try {
-    ledger = JSON.parse(await fs.readFile(ledgerPath, "utf8"));
-    if (!Array.isArray(ledger.entries)) ledger.entries = [];
-  } catch {
-    ledger = { runId, entries: [], schemaVersion: LEDGER_SCHEMA_VERSION };
-  }
-
-  // Rerecord semantics: replace any pre-existing row with the same spanId
-  // (regardless of its status) so the legacy v1/v2 row is upgraded to v3
-  // shape on disk. The append path keeps the historical dedup semantics:
-  // an exact (spanId, status) duplicate is dropped to keep retried hooks
-  // idempotent.
-  if (options.replaceBySpanId) {
-    ledger.entries = ledger.entries.filter((entry) => entry.spanId !== clean.spanId);
-    ledger.entries.push(clean);
-    ledger.runId = runId;
-    ledger.schemaVersion = LEDGER_SCHEMA_VERSION;
-    await fs.writeFile(ledgerPath, JSON.stringify(ledger, null, 2) + "\\n", { encoding: "utf8", mode: 0o600 });
-  } else if (!ledger.entries.some((entry) => entry.spanId === clean.spanId && entry.status === clean.status)) {
-    ledger.entries.push(clean);
-    ledger.runId = runId;
-    ledger.schemaVersion = LEDGER_SCHEMA_VERSION;
-    await fs.writeFile(ledgerPath, JSON.stringify(ledger, null, 2) + "\\n", { encoding: "utf8", mode: 0o600 });
+    try {
+      ledger = JSON.parse(await fs.readFile(ledgerPath, "utf8"));
+      if (!Array.isArray(ledger.entries)) ledger.entries = [];
+    } catch {
+      ledger = { runId, entries: [], schemaVersion: LEDGER_SCHEMA_VERSION };
+    }
+
+    // Rerecord semantics: replace any pre-existing row with the same spanId
+    // (regardless of its status) so the legacy v1/v2 row is upgraded to v3
+    // shape on disk. The append path keeps the historical dedup semantics:
+    // an exact (spanId, status) duplicate is dropped to keep retried hooks
+    // idempotent.
+    if (options.replaceBySpanId) {
+      ledger.entries = ledger.entries.filter((entry) => entry.spanId !== clean.spanId);
+      ledger.entries.push(clean);
+      ledger.runId = runId;
+      ledger.schemaVersion = LEDGER_SCHEMA_VERSION;
+      await writeDelegationLedgerAtomic(ledgerPath, ledger);
+    } else if (!ledger.entries.some((entry) => entry.spanId === clean.spanId && entry.status === clean.status)) {
+      ledger.entries.push(clean);
+      ledger.runId = runId;
+      ledger.schemaVersion = LEDGER_SCHEMA_VERSION;
+      await writeDelegationLedgerAtomic(ledgerPath, ledger);
+    }
+  } finally {
+    await releaseDelegationLogLock(lockDir);
   }
 
   const active = ledger.entries.filter((entry) => ["scheduled", "launched", "acknowledged"].includes(entry.status));

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;

package/dist/content/skills.js

@@ -1,7 +1,8 @@
 import { RUNTIME_ROOT, STAGE_TO_SKILL_FOLDER } from "../constants.js";
 import { nextStage as nextStageForTrack } from "../flow-state.js";
 import { FLOW_STAGES } from "../types.js";
-import { stageExamples } from "./examples.js";
+import { behaviorAnchorFor, stageExamples } from "./examples.js";
+import { INVESTIGATION_DISCIPLINE_BLOCK } from "./templates.js";
 import { reviewStackAwareRoutes, reviewStackAwareRoutingSummary, stageAutoSubagentDispatch, stageSchema, stageTrackRenderContext } from "./stage-schema.js";
 import { referencePatternsForStage } from "./reference-patterns.js";
 import { harnessDelegationRecipes } from "../harness-adapters.js";
@@ -104,6 +105,40 @@ Any "the failure is real" claim (failing test, broken build, regression catch, d
 For TDD specifically, this is the watched-RED proof and is required per new test before \`stage-complete\` accepts the stage.
 `;
 }
+/**
+ * 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 const INVESTIGATION_DISCIPLINE_STAGES = new Set([
+    "brainstorm",
+    "scope",
+    "design",
+    "spec",
+    "plan",
+    "tdd",
+    "review"
+]);
+export function investigationDisciplineBlock() {
+    return INVESTIGATION_DISCIPLINE_BLOCK;
+}
+export function behaviorAnchorBlock(stage) {
+    const anchor = behaviorAnchorFor(stage);
+    if (!anchor)
+        return "";
+    const ruleHint = anchor.ruleHint && anchor.ruleHint.trim().length > 0
+        ? `\n\nRule hint: ${anchor.ruleHint.trim()}`
+        : "";
+    return `## Behavior anchor
+
+Anchored to artifact section: \`${anchor.section}\`.
+
+- Bad: ${anchor.bad}
+- Good: ${anchor.good}${ruleHint}
+`;
+}
 function crossCuttingMechanicsBlock(stage) {
     // All stages share the universal mechanics, but each stage's matching
     // linter rules decide what is mandatory vs. structural-only.
@@ -117,6 +152,13 @@ function crossCuttingMechanicsBlock(stage) {
     if (stage === "tdd" || stage === "review" || stage === "ship") {
         blocks.push(watchedFailProofBlock());
     }
+    if (INVESTIGATION_DISCIPLINE_STAGES.has(stage)) {
+        blocks.push(investigationDisciplineBlock());
+    }
+    const anchor = behaviorAnchorBlock(stage);
+    if (anchor.length > 0) {
+        blocks.push(anchor);
+    }
     return blocks.join("\n");
 }
 function whenNotToUseBlock(items) {
@@ -192,7 +234,7 @@ function autoSubagentDispatchBlock(stage, track) {
 |---|---|---|---|---|---|---|---|
 ${rows}
 Mandatory: ${mandatoryList}. Record lifecycle rows in \`${delegationLogRel}\` and append-only \`${delegationEventsRel}\` before completion.${runPhaseLegend}
-### Harness Dispatch Contract — use true harness dispatch: Claude Task, Cursor generic dispatch, OpenCode \`.opencode/agents/<agent>.md\` via Task/@agent, Codex \`.codex/agents/<agent>.toml\`. Do not collapse OpenCode or Codex to role-switch by default. Worker ACK Contract: ACK must include \`spanId\`, \`dispatchId\`, \`dispatchSurface\`, \`agentDefinitionPath\`, and \`ackTs\`; never claim \`fulfillmentMode: "isolated"\` without matching lifecycle proof. Helper: \`.cclaw/hooks/delegation-record.mjs --status=<status> --span-id=<spanId> --dispatch-id=<dispatchId> --dispatch-surface=<surface> --agent-definition-path=<path> --json\`. Exact recipe: scheduled -> launched -> acknowledged -> completed with the same span; completed isolated/generic rows require a prior ACK event for that span or \`--ack-ts=<iso>\`.
+### Harness Dispatch Contract — use true harness dispatch: Claude Task, Cursor generic dispatch, OpenCode \`.opencode/agents/<agent>.md\` via Task/@agent, Codex \`.codex/agents/<agent>.toml\`. Do not collapse OpenCode or Codex to role-switch by default. Worker ACK Contract: ACK must include \`spanId\`, \`dispatchId\`, \`dispatchSurface\`, \`agentDefinitionPath\`, and \`ackTs\`; never claim \`fulfillmentMode: "isolated"\` without matching lifecycle proof. Canonical helper (same flags as \`delegation-record.mjs --help\`): \`node .cclaw/hooks/delegation-record.mjs --stage=<stage> --agent=<agent> --mode=<mandatory|proactive> --status=<scheduled|launched|acknowledged|completed|...> --span-id=<id> --dispatch-id=<id> --dispatch-surface=<surface> --agent-definition-path=<path> [--ack-ts=<iso>] [--evidence-ref=<ref>] --json\`. Lifecycle order: \`scheduled → launched → acknowledged → completed\` on one span (reuse the same span id); completed isolated/generic rows require a prior ACK event for that span or \`--ack-ts=<iso>\`. For a partial audit trail, \`--repair --span-id=<id> --repair-reason="<why>"\` appends missing phases (see \`--help\`) instead of inventing shortcuts.
 
 ${perHarnessLifecycleRecipeBlock()}`;
 }
@@ -390,7 +432,7 @@ function completionParametersBlock(schema, track) {
 - If you edit any completed-stage artifact after it shipped (\`completedStageMeta\` timestamps exist), append a short \`## Amendments\` section with dated bullets (timestamp + reason) instead of overwriting the archived narrative silently — advisory linter rule \`stage_artifact_post_closure_mutation\` enforces visibility when this trail is missing.
 - Record mandatory delegation lifecycle in \`${RUNTIME_ROOT}/state/delegation-log.json\` and append proof events to \`${RUNTIME_ROOT}/state/delegation-events.jsonl\`; the ledger is current state, the event log is audit proof.${mandatoryAgents.length > 0 ? ` If a mandatory delegation cannot run in this harness, use \`--waive-delegation=${mandatoryAgents.join(",")} --waiver-reason="<why safe>"\` on the completion helper.` : ""} If proactive delegations were intentionally skipped, rerun only with \`--accept-proactive-waiver\` (optionally \`--accept-proactive-waiver-reason="<why safe>"\`) after explicit user approval.
 - Never edit raw \`flow-state.json\` to complete a stage, even in advisory mode; that bypasses validation, gate evidence, and Learnings harvest. If a helper fails, report a one-line human-readable failure plus fenced JSON diagnostics; never echo the invoking command line or apply a manual state workaround.
-- Stage completion claim requires \`stage-complete\` exit 0 in the current turn. Quote the success line; do not paraphrase, do not infer success from skipped retries.
+- Stage completion claim requires \`stage-complete\` exit 0 in the current turn. Quote the single-line success JSON exactly as printed to stdout (for example \`{"ok":true,"command":"stage-complete",...}\` including \`completedStages\` / \`currentStage\` / \`runId\`); do not paraphrase. Do not infer success from empty stdout or from skipped retries (quiet mode always emits one JSON line on success).
 - Completion protocol: verify required gates, update the artifact, then use the completion helper with \`--evidence-json\` and \`--passed\` for every satisfied gate.
 `;
 }
@@ -412,7 +454,7 @@ ${completionBlock}
 - **NEVER paste the \`--evidence-json\` payload into chat.** It is structured data for the helper, not for the user. The same evidence already lives in the artifact section.
 - On failure, report a compact human-readable summary based on the helper's JSON \`findings\` array — list failing section names only (one line each), include the full helper JSON in a single fenced \`json\` block. Do not echo the invoking command.
 - **NEVER run shell hash commands** (\`shasum\`, \`sha256sum\`, \`md5sum\`, \`Get-FileHash\`, \`certutil\`, etc.) for hash compute. If the linter ever asks for a hash, that is a linter bug — report failure and stop, do not auto-fix in bash.
-- The helper defaults to quiet success (\`CCLAW_STAGE_COMPLETE_QUIET=1\`); rely on the resulting JSON, not stdout chatter.
+- The helper defaults to quiet (\`CCLAW_STAGE_COMPLETE_QUIET=1\`): no pretty-printed chatter, but **stdout still prints exactly one line** of machine-readable success JSON (same contract as \`start-flow\` in quiet mode).
 `;
 }
 function quickStartBlock(stage, track) {

package/dist/content/stages/brainstorm.js

@@ -69,7 +69,9 @@ export const BRAINSTORM = {
             "For simple low-risk greenfield work, present a compact A/B choice with one recommended path and one higher-upside challenger; keep the artifact concise but structurally complete (Context, Premise, How Might We, Sharpening Questions, Approaches, Reaction, Selected Direction, Not Doing).",
             "Show approaches before the recommendation; include a higher-upside challenger and gather reaction first.",
             "Self-review before approval: re-read the artifact, fix contradictions/placeholders/weak trade-offs, then ask for approval. Do not ask for approval on a draft you have not re-read.",
-            "State exactly what is being approved, then **STOP** until the user explicitly approves the artifact."
+            "State exactly what is being approved, then **STOP** until the user explicitly approves the artifact.",
+            "Investigation discipline: follow the shared `## Investigation Discipline` block (search -> graph/impact -> narrow read of 1-3 files -> draft) before any drafting or delegation; pass repo-relative paths and refs (never file bodies) in delegations.",
+            "Behavior anchor: see the shared `## Behavior anchor` block in this skill — the bad/good pair anchors how this stage's `Problem Decision Record` must be filled."
         ],
         process: [
             "Explore project context and align work to the run's discovery mode (lean / guided / deep).",

package/dist/content/stages/design.js

@@ -71,7 +71,9 @@ export const DESIGN = {
             "Classify ambiguity before acting. Only non-critical preference/default assumptions may continue; STOP on uncertainty about scope, architecture, security, data loss, public API, migration, auth/pricing, or required user approval. Design hypotheses must name validation path, rollback trigger, and owner before they can be carried forward.",
             "Before final approval, run the critic pass, reconcile material findings, and bound retries with the review-loop policy.",
             "For baseline approval, present the full design plus exact spec handoff and **STOP** until explicit approval.",
-            "**STOP BEFORE ADVANCE.** Mandatory delegation `planner` runs **AFTER user approval of the design lock**, not before Q&A. Sequence is: Q&A loop -> draft design lock -> user approval -> `planner` delegation -> `stage-complete`. Legal fulfillment modes for `planner`: (a) **harness-native Task tool** — run the delegation, then record via `node .cclaw/hooks/delegation-record.mjs --stage=design --agent=planner --mode=mandatory --status=completed --span-id=<uuid> --dispatch-surface=cursor-task --agent-definition-path=<agent-md-path> --evidence-ref=<artifact#section>`; (b) **role-switch** — write planner output into the design artifact, then record with `--dispatch-surface=role-switch`; (c) **cclaw subagent helper** with `--dispatch-surface=isolated`. Run `node .cclaw/hooks/stage-complete.mjs design` from the tool layer (do not paste the command into chat); report only the resulting summary."
+            "**STOP BEFORE ADVANCE.** Mandatory delegation `planner` runs **AFTER user approval of the design lock**, not before Q&A. Sequence is: Q&A loop -> draft design lock -> user approval -> `planner` delegation -> `stage-complete`. Legal fulfillment modes for `planner`: (a) **harness-native Task tool** — run the delegation, then record via `node .cclaw/hooks/delegation-record.mjs --stage=design --agent=planner --mode=mandatory --status=completed --span-id=<uuid> --dispatch-surface=cursor-task --agent-definition-path=<agent-md-path> --evidence-ref=<artifact#section>`; (b) **role-switch** — write planner output into the design artifact, then record with `--dispatch-surface=role-switch`; (c) **cclaw subagent helper** with `--dispatch-surface=isolated`. Run `node .cclaw/hooks/stage-complete.mjs design` from the tool layer (do not paste the command into chat); report only the resulting summary.",
+            "Investigation discipline: follow the shared `## Investigation Discipline` block before drafting architecture — populate `Codebase Investigation` from a search/graph trace and pass paths/refs (never file bodies) to investigator/critic delegations.",
+            "Behavior anchor: see the shared `## Behavior anchor` block in this skill — the bad/good pair anchors how `Codebase Investigation` must precede any ADR commitment."
         ],
         process: [
             "Read upstream artifacts and current design docs.",

package/dist/content/stages/plan.js

@@ -61,7 +61,9 @@ export const PLAN = {
             "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.",
             "**STOP.** Do NOT proceed until user explicitly approves.",
-            "**STOP BEFORE ADVANCE.** Mandatory delegation `planner` must be marked completed or explicitly waived in `.cclaw/state/delegation-log.json`. Then close the stage via `node .cclaw/hooks/stage-complete.mjs plan` and tell the user to run `/cc`."
+            "**STOP BEFORE ADVANCE.** Mandatory delegation `planner` must be marked completed or explicitly waived in `.cclaw/state/delegation-log.json`. Then close the stage via `node .cclaw/hooks/stage-complete.mjs plan` and tell the user to run `/cc`.",
+            "Investigation discipline: follow the shared `## Investigation Discipline` block — when defining `Implementation Units`, list cited paths in the `Files` and `Patterns to follow` rows instead of pasting code into chat or delegations.",
+            "Behavior anchor: see the shared `## Behavior anchor` block in this skill — the bad/good pair anchors how `Execution Posture` may only claim parallel-safe with disjoint units and a cited interface contract."
         ],
         process: [
             "Build dependency graph and ordered slices.",

package/dist/content/stages/review.js

@@ -58,7 +58,9 @@ export const REVIEW = {
             "Resolve all critical blockers before ship. If verdict is BLOCKED, do not pass `review_criticals_resolved`; pass only the remediation route gate `review_verdict_blocked` when routing back to TDD.",
             "When verdict is BLOCKED, do not end with a passive stop: explicitly route remediation to TDD via `ROUTE_BACK_TO_TDD`, point to `npx cclaw-cli internal rewind tdd` with the blocking IDs, and tell the operator to ack the stale TDD marker only after rework is complete.",
             structuredAskSingleChoiceInstruction("final verdict", "verdict (APPROVED / APPROVED_WITH_CONCERNS / BLOCKED)"),
-            "**STOP.** Do NOT proceed to ship until the user provides an explicit verdict."
+            "**STOP.** Do NOT proceed to ship until the user provides an explicit verdict.",
+            "Investigation discipline: follow the shared `## Investigation Discipline` block — `Changed-File Coverage` and Layer 2 findings cite `path:line`; delegate `reviewer`/`security-reviewer` with paths and refs, never with pasted file contents.",
+            "Behavior anchor: see the shared `## Behavior anchor` block in this skill — the bad/good pair anchors that `Layer 2 Findings` surface defects, not drive-by refactors."
         ],
         process: [
             "Layer 1: check acceptance criteria and requirement coverage.",

package/dist/content/stages/scope.js

@@ -52,6 +52,7 @@ export const SCOPE = {
             "**Premise carry-forward (do NOT re-author)** — brainstorm OWNS the premise check (right problem / direct path / what if nothing). Cite brainstorm's `## Premise Check` section in `## Upstream Handoff > Decisions carried forward`. Add a row to `## Premise Drift` only when the scope-stage Q&A surfaced NEW evidence that materially changes the brainstorm answer (e.g. new constraint, new user signal). Otherwise mark `Premise Drift: None` — do not duplicate the brainstorm premise table.",
             "**Conditional 10-star boundary** — for deep/high-risk/product-strategy work, show what would make the product meaningfully better, then explicitly choose what ships now, what is deferred, and what is excluded without vague `later/for now` placeholders. Skip this for straightforward repair work and record `not needed: compact scope`.",
             "**Pick one operational mode with the user** — HOLD SCOPE preserves focus; SELECTIVE EXPANSION cherry-picks high-leverage reference ideas; SCOPE EXPANSION explores ambitious alternatives; SCOPE REDUCTION cuts to the essential wedge. Recommend one, state why and what signal would change it, then keep elicitation focused until the user either approves or asks to proceed with draft boundaries.",
+            "**Product-discovery is REQUIRED for SELECTIVE / SCOPE EXPANSION (hard gate)** — If the resolved scope mode is SELECTIVE EXPANSION or SCOPE EXPANSION, run \`product-discovery\` in proactive mode **after** adaptive elicitation converges and **before** \`stage-complete\`. Do not complete this stage until the delegation ledger shows \`product-discovery\` as \`completed\` with non-empty \`evidenceRefs\` pointing at this scope artifact. HOLD SCOPE and SCOPE REDUCTION do not require this row.",
             "**Run mode-specific analysis only to needed depth** — lean discovery keeps the selected-mode row compact; guided adds the standard contract rows; deep may add Landscape Check, Taste Calibration, Reference Pattern Registry, Reference Pull, Ambitious Alternatives, and Ruthless Minimum Slice evidence when mode/risk warrants it.",
             "**Decision-driver contract** — list weighted decision drivers (value, risk, reversibility, effort, timeline) and score candidate scope moves so the selected mode and boundaries are evidence-backed, not preference-led.",
             "**Architecture handoff (do NOT pick architecture tier here)** — design OWNS architecture choice (minimum-viable / product-grade / ideal). Scope only picks the SCOPE MODE (HOLD/SELECTIVE/EXPAND/REDUCE) and boundary; record in `## Scope Contract > Design handoff` what design must decide (e.g. `architecture-tier`, `framework`, `data-model`). Do NOT enumerate Implementation Alternatives in scope.",
@@ -73,7 +74,9 @@ export const SCOPE = {
             "If the user says no but cannot name the change, offer concrete moves: keep scope, add one obvious adjacent capability, reduce to wedge, or re-open stack/product direction.",
             "Before final approval, record outside-voice findings and a `## Scope Outside Voice Loop` table per the Scope Outside Voice Loop policy above.",
             "**STOP.** Wait for explicit user approval of the scope mode and scope contract before writing final approval language or advancing.",
-            "**STOP BEFORE ADVANCE.** Mandatory delegation `planner` runs **AFTER user approval of the scope contract**, not before Q&A. Sequence is: Q&A loop -> propose contract -> user approval -> `planner` delegation -> `stage-complete`. If you delegate `planner` before the Q&A loop converges, you violate the elicitation contract and the linter will block stage-complete via `qa_log_unconverged`. Legal fulfillment modes for `planner`: (a) **harness-native Task tool** — run the delegation, then record the lifecycle row via `node .cclaw/hooks/delegation-record.mjs --stage=scope --agent=planner --mode=mandatory --status=completed --span-id=<uuid> --dispatch-surface=cursor-task --agent-definition-path=<agent-md-path> --evidence-ref=<artifact#section>` (the helper sets `fulfillmentMode: \"generic-dispatch\"` automatically); (b) **role-switch** — announce `## cclaw role-switch: scope/planner (mandatory)`, write the planner output/evidence into the scope artifact, then record the row with `--dispatch-surface=role-switch --agent-definition-path=<artifact-anchor>` (helper sets `fulfillmentMode: \"role-switch\"` automatically); (c) **cclaw subagent helper** if available, with `--dispatch-surface=isolated`. Run `node .cclaw/hooks/stage-complete.mjs scope` from the tool layer (do not paste the command into chat); report only the resulting summary."
+            "**STOP BEFORE ADVANCE.** Mandatory delegation `planner` runs **AFTER user approval of the scope contract**, not before Q&A. Sequence is: Q&A loop -> propose contract -> user approval -> `planner` delegation -> `stage-complete`. If you delegate `planner` before the Q&A loop converges, you violate the elicitation contract and the linter will block stage-complete via `qa_log_unconverged`. Legal fulfillment modes for `planner`: (a) **harness-native Task tool** — run the delegation, then record the lifecycle row via `node .cclaw/hooks/delegation-record.mjs --stage=scope --agent=planner --mode=mandatory --status=completed --span-id=<uuid> --dispatch-surface=cursor-task --agent-definition-path=<agent-md-path> --evidence-ref=<artifact#section>` (the helper sets `fulfillmentMode: \"generic-dispatch\"` automatically); (b) **role-switch** — announce `## cclaw role-switch: scope/planner (mandatory)`, write the planner output/evidence into the scope artifact, then record the row with `--dispatch-surface=role-switch --agent-definition-path=<artifact-anchor>` (helper sets `fulfillmentMode: \"role-switch\"` automatically); (c) **cclaw subagent helper** if available, with `--dispatch-surface=isolated`. Run `node .cclaw/hooks/stage-complete.mjs scope` from the tool layer (do not paste the command into chat); report only the resulting summary.",
+            "Investigation discipline: follow the shared `## Investigation Discipline` block (search -> graph/impact -> narrow read of 1-3 files -> draft); pass repo-relative paths and refs to any delegated planner/critic instead of pasting upstream content.",
+            "Behavior anchor: see the shared `## Behavior anchor` block in this skill — the bad/good pair anchors how this stage's `Scope Contract` must trace each row to a recorded user signal."
         ],
         process: [
             "Run pre-scope system audit (git log/diff/stash + debt-marker scan) — scope OWNS the repo audit; design will only diff the blast radius since this scope baseline.",

package/dist/content/stages/ship.js

@@ -59,7 +59,8 @@ export const SHIP = {
             "Document release notes and rollback plan explicitly.",
             decisionProtocolInstruction("finalization mode", "present modes as labeled options (A/B/C/D/E) with consequences, and mark one as (recommended)", "recommend the mode that best addresses release blast-radius, rollback readiness, observability, and stakeholder communication — ties go to the most reversible option"),
             "Do not proceed if critical blockers remain from review.",
-            "**STOP.** Present finalization options and wait for user selection before executing any finalization action."
+            "**STOP.** Present finalization options and wait for user selection before executing any finalization action.",
+            "Behavior anchor: see the shared `## Behavior anchor` block in this skill — the bad/good pair anchors that `Preflight Results` cite fresh command output, exit codes, and the commit SHA from this turn."
         ],
         process: [
             "Validate review and test gates.",

package/dist/content/stages/spec.js

@@ -54,7 +54,9 @@ export const SPEC = {
             "**Chunk acceptance criteria for review.** When presenting the spec to the user for sign-off, deliver acceptance criteria in batches of 3-5 and **pause for explicit ACK** (via Decision Protocol) before sending the next batch. Do not dump the full criteria wall in one message — small batches surface objections earlier and keep the sign-off meaningful. Full spec writeup still lands in `04-spec.md`, but the conversation itself must be digestible.",
             "Require user confirmation on the written spec. **STOP.** Do NOT proceed to plan until user approves.",
             "For each criterion, ask: what exact evidence proves this passed? If the evidence or verification command/manual step is vague, rewrite.",
-            "When encountering ambiguity, classify it before acting: (A) ask user for missing info, (B) enumerate non-critical interpretations and pick one with justification, (C) propose hypothesis with validation path. Do NOT silently resolve ambiguity. STOP on scope, architecture, security, data loss, public API, migration, auth/pricing, or user-approval uncertainty."
+            "When encountering ambiguity, classify it before acting: (A) ask user for missing info, (B) enumerate non-critical interpretations and pick one with justification, (C) propose hypothesis with validation path. Do NOT silently resolve ambiguity. STOP on scope, architecture, security, data loss, public API, migration, auth/pricing, or user-approval uncertainty.",
+            "Investigation discipline: follow the shared `## Investigation Discipline` block — derive ACs from cited upstream paths/refs (`02-scope.md#R-2`, `03-design.md#DD-1`) instead of pasting their bodies into delegation prompts.",
+            "Behavior anchor: see the shared `## Behavior anchor` block in this skill — the bad/good pair anchors how each `Acceptance Criteria` row must carry an observable predicate plus the evidence path."
         ],
         process: [
             "Define measurable acceptance criteria.",

package/dist/content/stages/tdd.js

@@ -71,7 +71,9 @@ export const TDD = {
             "Use incremental RED/GREEN/REFACTOR commits when the repository workflow and working tree make that appropriate; otherwise record the checkpoint boundaries in the artifact.",
             "Stop if regressions appear and fix before proceeding.",
             "If a test passes unexpectedly, investigate: does the behavior already exist, or is the test wrong?",
-            "**Per-Slice Review point (conditional).** Check every slice against the triggers before declaring it DONE. Triggers: `touchCount >= filesChangedThreshold`, any `touchPaths` match a `touchTriggers` glob, or the plan row declares `highRisk: true`. On a trigger, run two passes on the slice alone — (1) Spec-Compliance: trace RED/GREEN/REFACTOR evidence back to its plan task + spec criterion, noting edge cases the tests skip; (2) Quality: diff-scan for naming, error handling, dead code, simpler alternatives. Record both under `## Per-Slice Review` in `06-tdd.md`, naming the trigger that fired. Dispatch the `reviewer` subagent natively when available (log `fulfillmentMode: \"isolated\"`); otherwise fulfil via in-session role switch (`fulfillmentMode: \"role-switch\"`). Never fabricate an isolated pass from memory."
+            "**Per-Slice Review point (conditional).** Check every slice against the triggers before declaring it DONE. Triggers: `touchCount >= filesChangedThreshold`, any `touchPaths` match a `touchTriggers` glob, or the plan row declares `highRisk: true`. On a trigger, run two passes on the slice alone — (1) Spec-Compliance: trace RED/GREEN/REFACTOR evidence back to its plan task + spec criterion, noting edge cases the tests skip; (2) Quality: diff-scan for naming, error handling, dead code, simpler alternatives. Record both under `## Per-Slice Review` in `06-tdd.md`, naming the trigger that fired. Dispatch the `reviewer` subagent natively when available (log `fulfillmentMode: \"isolated\"`); otherwise fulfil via in-session role switch (`fulfillmentMode: \"role-switch\"`). Never fabricate an isolated pass from memory.",
+            "Investigation discipline: follow the shared `## Investigation Discipline` block — `Watched-RED Proof` and `RED Evidence` rows must cite test paths and command logs, not pasted source bodies; delegate `test-author` with paths and refs only.",
+            "Behavior anchor: see the shared `## Behavior anchor` block in this skill — the bad/good pair anchors how `RED Evidence` must contain a falsifiable assertion (no tautologies)."
         ],
         process: [
             "Select one vertical slice and map it to acceptance criterion(s).",

package/dist/content/templates.d.ts

@@ -1,3 +1,12 @@
+/**
+ * Shared investigation discipline block (Round 5 / v6.6.0). Rendered once per
+ * elicitation/spec stage skill (brainstorm, scope, design, spec, plan, tdd,
+ * review). The block enforces a four-step ladder before drafting and a
+ * path-passing rule for delegations so token cost and "jumped into code"
+ * regressions stay bounded. Stop-trigger count and ladder-step count are
+ * verified by `tests/unit/investigation-discipline-block.test.ts`.
+ */
+export declare const INVESTIGATION_DISCIPLINE_BLOCK = "## Investigation Discipline\n\nUse this ladder before drafting or delegating; do not jump straight to the editor.\n\n1. **Search** \u2014 locate the surface (file path, symbol, ref) before reading. Use `rg` / glob / graph; record the query, not the chunk.\n2. **Graph / impact** \u2014 name what the change touches (callers, callees, tests, configs) and its blast radius before opening a file.\n3. **Narrow read** \u2014 read at most 1-3 files, only the sections needed; cite paths with `:line` ranges instead of pasting bodies.\n4. **Draft** \u2014 only after the trace exists; the trace is the authority, not chat history or memory.\n\n**Path-passing in delegations.** When delegating, pass repo-relative paths and refs (e.g. `src/foo/bar.ts:42`, `D-12`, `AC-3`) \u2014 never the file body. The subagent re-reads from path; pasting content fragments breaks freshness and inflates tokens.\n\n**Stop triggers** (any one means halt and re-enter the ladder):\n\n- You are about to read more than 3 files in one pass.\n- You are about to load file content into a delegation prompt instead of paths or refs.\n- You are about to start a draft before any trace (search log, graph note, narrow-read citation) exists.\n";
 export declare const ARTIFACT_TEMPLATES: Record<string, string>;
 export declare const RULEBOOK_MARKDOWN = "# Cclaw Rulebook\n\n## MUST_ALWAYS\n- Follow flow order: brainstorm -> scope -> design -> spec -> plan -> tdd -> review -> ship\n- Require explicit user confirmation after plan before TDD\n- Keep evidence artifacts in `.cclaw/artifacts/`\n- Enforce RED before GREEN in TDD\n- Run two-layer review (spec_compliance and code_quality) before ship\n- Validate all inputs before processing \u2014 never trust external data without sanitization\n- Prefer immutable data patterns and pure functions where the language supports them\n- Follow existing repo conventions, patterns, and directory structure \u2014 match the codebase\n- Verify claims with fresh evidence: \"tests pass\" requires running tests in this message\n- Use conventional commits: `type(scope): description` (feat, fix, refactor, test, docs, chore)\n\n## MUST_NEVER\n- Skip RED phase and jump directly to GREEN in TDD\n- Ship with critical review findings\n- Start implementation during /brainstorm\n- Modify generated cclaw files manually when CLI can regenerate them\n- Commit `.cclaw/` or generated shim files\n- Expose secrets, tokens, API keys, or absolute system paths in agent output\n- Duplicate existing functionality without explicit justification \u2014 search before building\n- Bypass security checks, linting hooks, or type checking to \"move faster\"\n- Claim success (\"Done,\" \"All good,\" \"Tests pass\") without running verification in this message\n- Make changes outside the blast radius of the current task without user consent\n\n## DELEGATION\nWhen a task requires specialist knowledge (security audit, performance profiling, database review),\ndelegate to a specialized agent or skill if the harness supports it. The primary agent should:\n1. Identify the specialist domain\n2. Provide focused context (relevant files, the specific concern)\n3. Evaluate the specialist output before acting on it \u2014 do not blindly apply recommendations\n";
 /**
@@ -7,5 +16,5 @@ export declare const RULEBOOK_MARKDOWN = "# Cclaw Rulebook\n\n## MUST_ALWAYS\n-
  * (premature draft, premature subagent dispatch, command-line echo to chat).
  */
 export declare const CURSOR_GUIDELINES_RULE_MDC = "---\ndescription: cclaw zero-install behavior baseline (always-on)\nglobs:\n  - \"**/*\"\nalwaysApply: true\n---\n\n<!-- cclaw-managed-cursor-guidelines-rule -->\n\n# Cclaw Baseline Guidelines\n\nThese three rules apply to every Cursor agent session in this project,\nregardless of whether stage skills loaded.\n\n## 1. Q&A floor before drafting (brainstorm/scope/design)\n\nBefore drafting any `.cclaw/artifacts/01-brainstorm-*.md`,\n`02-scope-*.md`, or `03-design-*.md`, verify that the artifact's\n`## Q&A Log` table demonstrates Ralph-Loop convergence: every\nforcing-question topic id is tagged `[topic:<id>]` on at least one row\n(see the stage's forcing-questions checklist for the id list), the last\n2 turns produce no new decision-changing impact, OR an explicit user\nstop-signal row is recorded. Walk the stage forcing questions one at a\ntime via the `AskQuestion` tool. If you find yourself proposing a\ndraft after 1-2 questions while forcing topic ids remain untagged, STOP\nand continue the loop.\n\nThe `qa_log_unconverged` linter rule will block `stage-complete` when\nconvergence has not been reached. Wave 24 (v6.0.0) made `[topic:<id>]`\ntagging mandatory; the English keyword fallback was removed because it\nmis-reported convergence on RU/UA Q&A logs.\n\n## 2. Mandatory subagents run after Q&A approval\n\nFor brainstorm / scope / design, mandatory subagents (\n`product-discovery`, `critic`, `planner`, `architect`,\n`test-author`) run **only AFTER the user approves the elicitation\noutcome**, never before the Q&A loop converges. Dispatching them early\npreempts the user dialogue and violates the elicitation contract \u2014 the\nlinter will block stage-complete.\n\nSee each stage's \"Run Phase: post-elicitation\" rows in the materialized\nAutomatic Subagent Dispatch table.\n\n## 3. Never echo cclaw command lines to chat\n\nThe user does not run cclaw helpers (`node .cclaw/hooks/...`) manually.\nNEVER paste full command lines, `--evidence-json '{...}'` payloads,\n`--waive-delegation=...`, or shell hash commands (`shasum`,\n`sha256sum`, `Get-FileHash`, `certutil`, etc.) into chat. Run the\nhelper via the tool layer and report only the resulting summary. On\nfailure, report a compact human-readable summary plus the helper JSON in\na single fenced `json` block.\n";
-export declare const CURSOR_WORKFLOW_RULE_MDC = "---\ndescription: cclaw workflow guardrails for Cursor agent sessions\nglobs:\n  - \"**/*\"\nalwaysApply: true\n---\n\n<!-- cclaw-managed-cursor-workflow-rule -->\n\n# Cclaw Workflow Guardrails\n\n## Activation Rule\n\nBefore responding to coding work:\n1. Read `.cclaw/state/flow-state.json`.\n2. Start with `/cc` or continue with `/cc`.\n3. If no software-stage flow applies, respond normally.\n\n## Stage Order\n\n`brainstorm -> scope -> design -> spec -> plan -> tdd -> review -> ship`\n\nTrack-specific skips are allowed only when `flow-state.track` + `skippedStages` explicitly say so.\n\n## Task Classification\n\n| Class | Route |\n|---|---|\n| non-trivial software work | `/cc <idea>` |\n| trivial software fix | `/cc <idea>` (quick track) |\n| bugfix with repro | `/cc <idea>` and enforce RED-first in tdd |\n| pure question / non-software | direct answer (no stage flow) |\n\n## Command Surface\n\n- `/cc` = entry and resume.\n- `/cc` = only progression path.\n- Knowledge capture and recall use the `learnings` skill when requested.\n\n## Verification Discipline\n\n- No completion claim without fresh command evidence in this turn.\n- Stage completion claim requires `stage-complete` exit 0 in the current turn. Quote the success line; do not paraphrase, do not infer success from skipped retries.\n\n## Protocol label hygiene\n\n`skip` wording means different things depending on phase: brainstorm/scope/design Q&A stop-signals may still literal **skip**/enough/move-on wording; structured ship closeout retros and compound clustering prompts should expose **no changes** (or accept-as-is language) rather than labeling the passive path as skip. Keep the verbs aligned with the harness question copy you present to the human.\n- Do not mark gates passed from memory.\n- Keep evidence in `.cclaw/artifacts/`; archive through closeout via `/cc` or cancel early via `node .cclaw/hooks/cancel-run.mjs`.\n\n## Delegation And Approvals\n\n- Machine-only checks in design/plan/tdd/review/ship should auto-dispatch when tooling supports it.\n- **For brainstorm / scope / design stages**: ask user input continuously via adaptive elicitation (one question per turn through the harness-native question tool \u2014 `AskQuestion` in Cursor). Walk the stage forcing-questions list one-by-one. **Tag each Q&A Log row's `Decision impact` cell with `[topic:<id>]`** (the id is given in the stage's forcing-questions checklist) so the linter can verify coverage in any natural language. Do NOT batch and do NOT defer to a single approval gate at the end. The `qa_log_unconverged` linter rule will block `stage-complete` when convergence is not reached (forcing topic ids untagged AND last 2 turns still produce decision-changing rows AND no stop-signal).\n- **For other stages** (spec/plan/tdd/build/review/ship): ask user input only at explicit approval gates (scope mode, plan approval, challenge resolution, ship finalization), not for routine progress updates.\n- If you find yourself proposing a draft after 1-2 questions in brainstorm/scope/design, STOP \u2014 go back to the forcing-questions list and continue.\n- Mandatory subagents in brainstorm/scope/design run only AFTER the user approves the elicitation outcome (see each stage's \"Run Phase: post-elicitation\" rows). Dispatching them before the Q&A loop converges violates the contract.\n- Never echo cclaw command lines (`node .cclaw/hooks/...`, `--evidence-json '{...}'`) to chat \u2014 the user does not run cclaw manually. Run helpers via the tool layer; report only the resulting summary.\n- If harness capabilities are partial, record waiver reasons in delegation logs.\n\n## Routing Source Of Truth\n\n- Primary router: `.cclaw/skills/using-cclaw/SKILL.md`.\n- Stage behavior: current stage skill plus `.cclaw/state/flow-state.json`.\n- Preamble budget: keep role/status announcements brief and avoid repeating\n  them unless the stage or role changes.\n";
+export declare const CURSOR_WORKFLOW_RULE_MDC = "---\ndescription: cclaw workflow guardrails for Cursor agent sessions\nglobs:\n  - \"**/*\"\nalwaysApply: true\n---\n\n<!-- cclaw-managed-cursor-workflow-rule -->\n\n# Cclaw Workflow Guardrails\n\n## Activation Rule\n\nBefore responding to coding work:\n1. Read `.cclaw/state/flow-state.json`.\n2. Start with `/cc` or continue with `/cc`.\n3. If no software-stage flow applies, respond normally.\n\n## Stage Order\n\n`brainstorm -> scope -> design -> spec -> plan -> tdd -> review -> ship`\n\nTrack-specific skips are allowed only when `flow-state.track` + `skippedStages` explicitly say so.\n\n## Task Classification\n\n| Class | Route |\n|---|---|\n| non-trivial software work | `/cc <idea>` |\n| trivial software fix | `/cc <idea>` (quick track) |\n| bugfix with repro | `/cc <idea>` and enforce RED-first in tdd |\n| pure question / non-software | direct answer (no stage flow) |\n\n## Command Surface\n\n- `/cc` = entry and resume.\n- `/cc` = only progression path.\n- Knowledge capture and recall use the `learnings` skill when requested.\n\n## Verification Discipline\n\n- No completion claim without fresh command evidence in this turn.\n- Stage completion claim requires `stage-complete` exit 0 in the current turn. Quote the single-line success JSON printed to stdout (e.g. `{\"ok\":true,\"command\":\"stage-complete\",...}`); do not paraphrase, do not infer success from empty stdout or from skipped retries.\n\n## Protocol label hygiene\n\n`skip` wording means different things depending on phase: brainstorm/scope/design Q&A stop-signals may still literal **skip**/enough/move-on wording; structured ship closeout retros and compound clustering prompts should expose **no changes** (or accept-as-is language) rather than labeling the passive path as skip. Keep the verbs aligned with the harness question copy you present to the human.\n- Do not mark gates passed from memory.\n- Keep evidence in `.cclaw/artifacts/`; archive through closeout via `/cc` or cancel early via `node .cclaw/hooks/cancel-run.mjs`.\n\n## Delegation And Approvals\n\n- Machine-only checks in design/plan/tdd/review/ship should auto-dispatch when tooling supports it.\n- **For brainstorm / scope / design stages**: ask user input continuously via adaptive elicitation (one question per turn through the harness-native question tool \u2014 `AskQuestion` in Cursor). Walk the stage forcing-questions list one-by-one. **Tag each Q&A Log row's `Decision impact` cell with `[topic:<id>]`** (the id is given in the stage's forcing-questions checklist) so the linter can verify coverage in any natural language. Do NOT batch and do NOT defer to a single approval gate at the end. The `qa_log_unconverged` linter rule will block `stage-complete` when convergence is not reached (forcing topic ids untagged AND last 2 turns still produce decision-changing rows AND no stop-signal).\n- **For other stages** (spec/plan/tdd/build/review/ship): ask user input only at explicit approval gates (scope mode, plan approval, challenge resolution, ship finalization), not for routine progress updates.\n- If you find yourself proposing a draft after 1-2 questions in brainstorm/scope/design, STOP \u2014 go back to the forcing-questions list and continue.\n- Mandatory subagents in brainstorm/scope/design run only AFTER the user approves the elicitation outcome (see each stage's \"Run Phase: post-elicitation\" rows). Dispatching them before the Q&A loop converges violates the contract.\n- Never echo cclaw command lines (`node .cclaw/hooks/...`, `--evidence-json '{...}'`) to chat \u2014 the user does not run cclaw manually. Run helpers via the tool layer; report only the resulting summary.\n- If harness capabilities are partial, record waiver reasons in delegation logs.\n\n## Routing Source Of Truth\n\n- Primary router: `.cclaw/skills/using-cclaw/SKILL.md`.\n- Stage behavior: current stage skill plus `.cclaw/state/flow-state.json`.\n- Preamble budget: keep role/status announcements brief and avoid repeating\n  them unless the stage or role changes.\n";
 export declare function buildRulesJson(): Record<string, unknown>;

package/dist/content/templates.js

@@ -1,4 +1,5 @@
 import { CCLAW_VERSION, SHIP_FINALIZATION_MODES } from "../constants.js";
+import { renderBehaviorAnchorTemplateLine } from "./examples.js";
 import { orderedStageSchemas } from "./stage-schema.js";
 import { FLOW_STAGES } from "../types.js";
 const SHIP_FINALIZATION_ENUM_LINES = SHIP_FINALIZATION_MODES.map((mode) => `  - ${mode}`).join("\n");
@@ -17,11 +18,38 @@ const SEED_SHELF_SECTION = `## Seed Shelf Candidates (optional)
 | Seed file | Trigger when | Suggested action | Status (planted/deferred/ignored) |
 |---|---|---|---|
 | .cclaw/seeds/SEED-YYYY-MM-DD-<slug>.md |  |  |  |`;
+/**
+ * Shared investigation discipline block (Round 5 / v6.6.0). Rendered once per
+ * elicitation/spec stage skill (brainstorm, scope, design, spec, plan, tdd,
+ * review). The block enforces a four-step ladder before drafting and a
+ * path-passing rule for delegations so token cost and "jumped into code"
+ * regressions stay bounded. Stop-trigger count and ladder-step count are
+ * verified by `tests/unit/investigation-discipline-block.test.ts`.
+ */
+export const INVESTIGATION_DISCIPLINE_BLOCK = `## Investigation Discipline
+
+Use this ladder before drafting or delegating; do not jump straight to the editor.
+
+1. **Search** — locate the surface (file path, symbol, ref) before reading. Use \`rg\` / glob / graph; record the query, not the chunk.
+2. **Graph / impact** — name what the change touches (callers, callees, tests, configs) and its blast radius before opening a file.
+3. **Narrow read** — read at most 1-3 files, only the sections needed; cite paths with \`:line\` ranges instead of pasting bodies.
+4. **Draft** — only after the trace exists; the trace is the authority, not chat history or memory.
+
+**Path-passing in delegations.** When delegating, pass repo-relative paths and refs (e.g. \`src/foo/bar.ts:42\`, \`D-12\`, \`AC-3\`) — never the file body. The subagent re-reads from path; pasting content fragments breaks freshness and inflates tokens.
+
+**Stop triggers** (any one means halt and re-enter the ladder):
+
+- You are about to read more than 3 files in one pass.
+- You are about to load file content into a delegation prompt instead of paths or refs.
+- You are about to start a draft before any trace (search log, graph note, narrow-read citation) exists.
+`;
 export const ARTIFACT_TEMPLATES = {
     "01-brainstorm.md": `${artifactFrontmatter("brainstorm")}
 
 # Brainstorm Artifact
 
+${renderBehaviorAnchorTemplateLine("brainstorm")}
+
 ## Mode Block
 - **Mode:** STARTUP | BUILDER | ENGINEERING | OPS | RESEARCH (pick exactly one)
 - **Why this mode:** (one line; cite a concrete signal — repo state, user prompt, ownership, risk window)
@@ -200,6 +228,8 @@ ${MARKDOWN_CODE_FENCE}
 
 # Scope Artifact
 
+${renderBehaviorAnchorTemplateLine("scope")}
+
 ## Upstream Handoff
 - Source artifacts: \`00-idea.md\`, \`01-brainstorm-<slug>.md\`
 - Decisions carried forward:
@@ -434,6 +464,8 @@ ${MARKDOWN_CODE_FENCE}
 
 # Design Artifact
 
+${renderBehaviorAnchorTemplateLine("design")}
+
 ## Compact-First Scaffold
 - Default to the compact design spine unless risk requires Standard/Deep add-ons.
 - Compact required spine: Upstream Handoff, Codebase Investigation, Engineering Lock, Architecture Boundaries, Architecture Diagram, Data Flow, Failure Mode Table, Test Strategy, Spec Handoff, and Completion Dashboard.
@@ -698,6 +730,8 @@ ${MARKDOWN_CODE_FENCE}
 
 # Specification Artifact
 
+${renderBehaviorAnchorTemplateLine("spec")}
+
 ## Upstream Handoff
 - Source artifacts: standard uses \`02-scope-<slug>.md\` + \`03-design-<slug>.md\`; medium uses \`01-brainstorm-<slug>.md\` when present; quick uses \`00-idea.md\` plus reproduction context.
 - Decisions carried forward:
@@ -797,6 +831,8 @@ ${MARKDOWN_CODE_FENCE}
 
 # Plan Artifact
 
+${renderBehaviorAnchorTemplateLine("plan")}
+
 ## Plan Header
 - **Goal:** (one sentence — what this plan delivers)
 - **Architecture:** (2-3 sentences — approach + key boundaries)
@@ -930,6 +966,8 @@ Execution rule: complete and verify each batch before starting the next batch.
 
 # TDD Artifact
 
+${renderBehaviorAnchorTemplateLine("tdd")}
+
 ## Upstream Handoff
 - Source artifacts: \`04-spec.md\` plus the active track's upstream source item (plan slice on standard/medium, spec acceptance item or bug reproduction slice on quick).
 - Decisions carried forward:
@@ -1126,6 +1164,8 @@ Execution rule: complete and verify each batch before starting the next batch.
 
 # Review Artifact
 
+${renderBehaviorAnchorTemplateLine("review")}
+
 ## Upstream Handoff
 - Source artifacts: \`04-spec.md\`, \`06-tdd.md\`, plus the active track's upstream source item when available.
 - Decisions carried forward:
@@ -1298,6 +1338,8 @@ Execution rule: complete and verify each batch before starting the next batch.
 
 # Ship Artifact
 
+${renderBehaviorAnchorTemplateLine("ship")}
+
 ## Upstream Handoff
 - Source artifacts: \`06-tdd.md\`, \`07-review.md\`
 - Decisions carried forward:
@@ -1565,7 +1607,7 @@ Track-specific skips are allowed only when \`flow-state.track\` + \`skippedStage
 ## Verification Discipline
 
 - No completion claim without fresh command evidence in this turn.
-- Stage completion claim requires \`stage-complete\` exit 0 in the current turn. Quote the success line; do not paraphrase, do not infer success from skipped retries.
+- Stage completion claim requires \`stage-complete\` exit 0 in the current turn. Quote the single-line success JSON printed to stdout (e.g. \`{"ok":true,"command":"stage-complete",...}\`); do not paraphrase, do not infer success from empty stdout or from skipped retries.
 
 ## Protocol label hygiene
 

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

@@ -601,7 +601,17 @@ export async function runAdvanceStage(projectRoot, args, io) {
         interactionHints
     };
     await writeFlowState(projectRoot, finalState);
-    if (!args.quiet) {
+    if (args.quiet) {
+        io.stdout.write(`${JSON.stringify({
+            ok: true,
+            command: "stage-complete",
+            stage: args.stage,
+            completedStages: finalState.completedStages,
+            currentStage: finalState.currentStage,
+            runId: finalState.activeRunId
+        })}\n`);
+    }
+    else {
         io.stdout.write(`${JSON.stringify({
             ok: true,
             command: "advance-stage",

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

@@ -211,19 +211,31 @@ export async function runStartFlow(projectRoot, args, io) {
     nextState = { ...nextState, repoSignals };
     await writeFlowState(projectRoot, nextState, { allowReset: true });
     await appendIdeaArtifact(projectRoot, args, current);
-    if (!args.quiet) {
+    const successPayload = {
+        ok: true,
+        command: "start-flow",
+        reclassify: args.reclassify,
+        track: nextState.track,
+        discoveryMode: nextState.discoveryMode,
+        taskClass: nextState.taskClass ?? null,
+        currentStage: nextState.currentStage,
+        skippedStages: nextState.skippedStages,
+        activeRunId: nextState.activeRunId,
+        repoSignals
+    };
+    if (args.quiet) {
         io.stdout.write(`${JSON.stringify({
             ok: true,
             command: "start-flow",
-            reclassify: args.reclassify,
-            track: nextState.track,
-            discoveryMode: nextState.discoveryMode,
-            taskClass: nextState.taskClass ?? null,
-            currentStage: nextState.currentStage,
-            skippedStages: nextState.skippedStages,
-            activeRunId: nextState.activeRunId,
-            repoSignals
-        }, null, 2)}\n`);
+            track: successPayload.track,
+            discoveryMode: successPayload.discoveryMode,
+            currentStage: successPayload.currentStage,
+            activeRunId: successPayload.activeRunId,
+            repoSignals: successPayload.repoSignals
+        })}\n`);
+    }
+    else {
+        io.stdout.write(`${JSON.stringify(successPayload, null, 2)}\n`);
     }
     return 0;
 }

package/package.json

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