cclaw-cli 6.5.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);

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/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/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) {

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

@@ -74,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";
 /**

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:

package/package.json

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