cclaw-cli 6.5.0 → 6.7.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/findings-dedup.d.ts

@@ -0,0 +1,56 @@
+import type { FlowStage } from "../types.js";
+import type { LintFinding } from "./shared.js";
+export declare const FINDINGS_CACHE_SCHEMA_VERSION = 1;
+export type FindingStatus = {
+    kind: "new";
+} | {
+    kind: "repeat";
+    count: number;
+} | {
+    kind: "resolved";
+};
+export interface ClassifiedFinding {
+    finding: LintFinding;
+    fingerprint: string;
+    status: FindingStatus;
+}
+export interface ResolvedFinding {
+    fingerprint: string;
+    rule: string;
+    lastSeenAt: string;
+}
+export interface FindingsDedupSummary {
+    newCount: number;
+    repeatCount: number;
+    resolvedCount: number;
+    resolved: ResolvedFinding[];
+}
+export interface LintRunDedupResult {
+    classified: ClassifiedFinding[];
+    summary: FindingsDedupSummary;
+    header: string;
+}
+/**
+ * Normalize a finding detail string so volatile tokens (run IDs,
+ * timestamps, counts, hex hashes, temp paths) don't cause a finding
+ * to appear "new" on every invocation.
+ */
+export declare function normalizeFindingDetail(detail: string): string;
+export declare function fingerprintFinding(stage: FlowStage, finding: LintFinding): string;
+/**
+ * Classify each emitted finding as `new`, `repeat:N`, or `resolved`
+ * relative to the cached sidecar for this stage. Persists the updated
+ * fingerprint set under a directory lock so concurrent lint runs for
+ * the same project don't clobber each other.
+ *
+ * The returned `header` is a short human string intended for inclusion
+ * above the linter output; it's stable across runs when findings
+ * repeat. Empty string when there is nothing meaningful to report
+ * (no findings and no carry-over state).
+ */
+export declare function classifyAndPersistFindings(projectRoot: string, stage: FlowStage, findings: LintFinding[], options?: {
+    now?: Date;
+}): Promise<LintRunDedupResult>;
+export declare function buildDedupHeader(stage: FlowStage, summary: FindingsDedupSummary): string;
+export declare function formatFindingStatusTag(status: FindingStatus): string;
+export declare function findingsDedupCachePathFor(projectRoot: string): string;

package/dist/artifact-linter/findings-dedup.js

@@ -0,0 +1,232 @@
+import { createHash } from "node:crypto";
+import fs from "node:fs/promises";
+import path from "node:path";
+import { RUNTIME_ROOT } from "../constants.js";
+import { ensureDir, exists, withDirectoryLock, writeFileSafe } from "../fs-utils.js";
+/**
+ * Wave 26 (v6.7.0) linter-dedup cache. The linter persists a per-stage
+ * fingerprint of each finding between runs so authors can tell at a
+ * glance what's `new`, `repeat`, or `resolved` relative to the last run.
+ *
+ * Fingerprint = `sha256(stage | rule | normalizedDetail).slice(0, 8)`.
+ * Details are normalized to stabilize the digest: whitespace collapsed,
+ * run-ids/hashes/timestamps replaced with placeholders, and enumeration
+ * counts (e.g. "3 approach detail card(s)") replaced with `<N>`.
+ *
+ * The cache is intentionally bounded by `MAX_PER_STAGE` so a noisy stage
+ * can't grow the sidecar without bound. When the active run trims the
+ * cache we drop the oldest `firstSeenAt` entries first.
+ */
+const FINDINGS_CACHE_REL_PATH = `${RUNTIME_ROOT}/.linter-findings.json`;
+const FINDINGS_CACHE_LOCK_REL_PATH = `${RUNTIME_ROOT}/.linter-findings.json.lock`;
+export const FINDINGS_CACHE_SCHEMA_VERSION = 1;
+const MAX_PER_STAGE = 200;
+function cachePath(projectRoot) {
+    return path.join(projectRoot, FINDINGS_CACHE_REL_PATH);
+}
+function cacheLockPath(projectRoot) {
+    return path.join(projectRoot, FINDINGS_CACHE_LOCK_REL_PATH);
+}
+function emptyStageCache() {
+    return { findings: [], lastRunAt: null };
+}
+function emptyCacheFile() {
+    return { schemaVersion: FINDINGS_CACHE_SCHEMA_VERSION, stages: {} };
+}
+/**
+ * Normalize a finding detail string so volatile tokens (run IDs,
+ * timestamps, counts, hex hashes, temp paths) don't cause a finding
+ * to appear "new" on every invocation.
+ */
+export function normalizeFindingDetail(detail) {
+    if (typeof detail !== "string" || detail.length === 0)
+        return "";
+    let normalized = detail;
+    normalized = normalized.replace(/\brun-[a-z0-9-]+\b/giu, "run-<id>");
+    normalized = normalized.replace(/\b[0-9a-f]{16,}\b/giu, "<hex>");
+    normalized = normalized.replace(/\b\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?Z?\b/gu, "<ts>");
+    normalized = normalized.replace(/\b\d{10,}\b/gu, "<n>");
+    normalized = normalized.replace(/\b\d+\b/gu, "<n>");
+    normalized = normalized.replace(/[ \t]+/gu, " ");
+    normalized = normalized.replace(/\r?\n/gu, " ");
+    return normalized.trim().toLowerCase();
+}
+export function fingerprintFinding(stage, finding) {
+    const payload = `${stage}|${finding.rule.trim()}|${normalizeFindingDetail(finding.details)}`;
+    return createHash("sha256").update(payload, "utf8").digest("hex").slice(0, 8);
+}
+async function readCacheFile(projectRoot) {
+    const filePath = cachePath(projectRoot);
+    if (!(await exists(filePath)))
+        return emptyCacheFile();
+    let raw;
+    try {
+        raw = await fs.readFile(filePath, "utf8");
+    }
+    catch {
+        return emptyCacheFile();
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return emptyCacheFile();
+    }
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+        return emptyCacheFile();
+    }
+    const typed = parsed;
+    const stages = (typed.stages ?? {});
+    const next = emptyCacheFile();
+    for (const [stageKey, value] of Object.entries(stages)) {
+        if (!value || typeof value !== "object" || Array.isArray(value))
+            continue;
+        const rawStage = value;
+        const findingsRaw = Array.isArray(rawStage.findings) ? rawStage.findings : [];
+        const findings = [];
+        for (const row of findingsRaw) {
+            if (!row || typeof row !== "object" || Array.isArray(row))
+                continue;
+            const r = row;
+            const fingerprint = typeof r.fingerprint === "string" ? r.fingerprint : "";
+            const rule = typeof r.rule === "string" ? r.rule : "";
+            const section = typeof r.section === "string" ? r.section : "";
+            const firstSeenAt = typeof r.firstSeenAt === "string" ? r.firstSeenAt : "";
+            const lastSeenAt = typeof r.lastSeenAt === "string" ? r.lastSeenAt : "";
+            const runCount = typeof r.runCount === "number" && Number.isFinite(r.runCount)
+                ? Math.max(1, Math.floor(r.runCount))
+                : 1;
+            if (fingerprint.length === 0 || rule.length === 0)
+                continue;
+            findings.push({ fingerprint, rule, section, firstSeenAt, lastSeenAt, runCount });
+        }
+        next.stages[stageKey] = {
+            findings,
+            lastRunAt: typeof rawStage.lastRunAt === "string" ? rawStage.lastRunAt : null
+        };
+    }
+    return next;
+}
+async function writeCacheFile(projectRoot, cache) {
+    await ensureDir(path.dirname(cachePath(projectRoot)));
+    await writeFileSafe(cachePath(projectRoot), `${JSON.stringify(cache, null, 2)}\n`, { mode: 0o600 });
+}
+/**
+ * Classify each emitted finding as `new`, `repeat:N`, or `resolved`
+ * relative to the cached sidecar for this stage. Persists the updated
+ * fingerprint set under a directory lock so concurrent lint runs for
+ * the same project don't clobber each other.
+ *
+ * The returned `header` is a short human string intended for inclusion
+ * above the linter output; it's stable across runs when findings
+ * repeat. Empty string when there is nothing meaningful to report
+ * (no findings and no carry-over state).
+ */
+export async function classifyAndPersistFindings(projectRoot, stage, findings, options = {}) {
+    const nowIso = (options.now ?? new Date()).toISOString();
+    return withDirectoryLock(cacheLockPath(projectRoot), async () => {
+        const cache = await readCacheFile(projectRoot);
+        const previous = cache.stages[stage] ?? emptyStageCache();
+        const previousByFingerprint = new Map();
+        for (const entry of previous.findings) {
+            previousByFingerprint.set(entry.fingerprint, entry);
+        }
+        const currentFingerprints = new Set();
+        const classified = [];
+        const nextFindings = [];
+        let newCount = 0;
+        let repeatCount = 0;
+        for (const finding of findings) {
+            const fingerprint = fingerprintFinding(stage, finding);
+            currentFingerprints.add(fingerprint);
+            const prior = previousByFingerprint.get(fingerprint);
+            if (prior) {
+                const nextEntry = {
+                    fingerprint,
+                    rule: finding.rule,
+                    section: finding.section,
+                    firstSeenAt: prior.firstSeenAt || nowIso,
+                    lastSeenAt: nowIso,
+                    runCount: prior.runCount + 1
+                };
+                nextFindings.push(nextEntry);
+                repeatCount += 1;
+                classified.push({
+                    finding,
+                    fingerprint,
+                    status: { kind: "repeat", count: nextEntry.runCount }
+                });
+                continue;
+            }
+            const nextEntry = {
+                fingerprint,
+                rule: finding.rule,
+                section: finding.section,
+                firstSeenAt: nowIso,
+                lastSeenAt: nowIso,
+                runCount: 1
+            };
+            nextFindings.push(nextEntry);
+            newCount += 1;
+            classified.push({
+                finding,
+                fingerprint,
+                status: { kind: "new" }
+            });
+        }
+        const resolved = [];
+        for (const entry of previous.findings) {
+            if (currentFingerprints.has(entry.fingerprint))
+                continue;
+            resolved.push({
+                fingerprint: entry.fingerprint,
+                rule: entry.rule,
+                lastSeenAt: entry.lastSeenAt
+            });
+        }
+        nextFindings.sort((a, b) => {
+            const aTime = Date.parse(a.firstSeenAt);
+            const bTime = Date.parse(b.firstSeenAt);
+            return Number.isFinite(aTime) && Number.isFinite(bTime) ? aTime - bTime : 0;
+        });
+        const trimmed = nextFindings.length > MAX_PER_STAGE
+            ? nextFindings.slice(nextFindings.length - MAX_PER_STAGE)
+            : nextFindings;
+        cache.stages[stage] = {
+            findings: trimmed,
+            lastRunAt: nowIso
+        };
+        await writeCacheFile(projectRoot, cache);
+        const summary = {
+            newCount,
+            repeatCount,
+            resolvedCount: resolved.length,
+            resolved
+        };
+        const header = buildDedupHeader(stage, summary);
+        return { classified, summary, header };
+    });
+}
+export function buildDedupHeader(stage, summary) {
+    const parts = [];
+    if (summary.newCount > 0)
+        parts.push(`${summary.newCount} new`);
+    if (summary.repeatCount > 0)
+        parts.push(`${summary.repeatCount} repeat`);
+    if (summary.resolvedCount > 0)
+        parts.push(`${summary.resolvedCount} resolved`);
+    if (parts.length === 0)
+        return "";
+    return `linter findings (stage=${stage}): ${parts.join(", ")}.`;
+}
+export function formatFindingStatusTag(status) {
+    if (status.kind === "new")
+        return "[new]";
+    if (status.kind === "resolved")
+        return "[resolved]";
+    return `[repeat:${status.count}]`;
+}
+export function findingsDedupCachePathFor(projectRoot) {
+    return cachePath(projectRoot);
+}

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, extractAuthoredBody, 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");
@@ -85,7 +86,8 @@ export async function lintPlanStage(ctx) {
         });
     }
     const allPlaceholderTokens = FORBIDDEN_PLACEHOLDER_TOKENS.map((token) => token.toLowerCase());
-    const lowerRaw = raw.toLowerCase();
+    const authoredBody = extractAuthoredBody(raw);
+    const lowerRaw = authoredBody.toLowerCase();
     const planWidePlaceholderHits = allPlaceholderTokens.filter((token) => lowerRaw.includes(token));
     // Strip the "## NO PLACEHOLDERS Rule" section (which lists tokens) and
     // any acknowledgement text from the scan to avoid false positives where

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

@@ -123,11 +123,36 @@ export interface LintFinding {
     found: boolean;
     details: string;
 }
+export interface LintFindingDedupSummary {
+    newCount: number;
+    repeatCount: number;
+    resolvedCount: number;
+    /**
+     * Short single-line human-facing summary of the dedup outcome. Empty
+     * string when there is nothing to report.
+     */
+    header: string;
+    /**
+     * Parallel to the `findings` array on `LintResult`; each status tags
+     * the finding at the same index as `new`, `repeat`, or `resolved`.
+     * `null` slots correspond to findings that weren't classified (for
+     * example, when the dedup cache is unreadable).
+     */
+    statuses: Array<{
+        kind: "new";
+    } | {
+        kind: "repeat";
+        count: number;
+    } | {
+        kind: "resolved";
+    } | null>;
+}
 export interface LintResult {
     stage: string;
     file: string;
     passed: boolean;
     findings: LintFinding[];
+    dedup?: LintFindingDedupSummary;
 }
 export declare function normalizeHeadingTitle(title: string): string;
 export type H2SectionMap = Map<string, string>;
@@ -144,6 +169,30 @@ export type H2SectionMap = Map<string, string>;
  */
 export declare function extractH2Sections(markdown: string): H2SectionMap;
 export declare function duplicateH2Headings(markdown: string): string[];
+/**
+ * Return the author-authored prose of an artifact, stripping linter meta
+ * regions so free-text scans (placeholder tokens, scope-reduction phrases,
+ * investigation trigger words) don't self-cannibalize by matching the
+ * linter's own templated meta-phrases.
+ *
+ * Stripping rules (in order):
+ *   1. `<!-- linter-meta --> ... <!-- /linter-meta -->` paired blocks.
+ *      Both markers must appear on their own line; unterminated openings
+ *      are left as-is so a malformed artifact cannot hide arbitrary
+ *      content by omitting the closing marker.
+ *   2. Every other HTML comment (`<!-- ... -->`, possibly multi-line).
+ *   3. Fenced code blocks that are tagged `linter-rule` (e.g.
+ *      ```` ```linter-rule ````). Plain fenced code blocks are preserved
+ *      because many stages quote code samples that the linter should
+ *      still see.
+ *
+ * The function guarantees the returned string is a strict subset of the
+ * original: no characters are synthesized, and line offsets are
+ * preserved for any surviving line (blank lines stand in for stripped
+ * regions). This keeps regex-based linter checks stable when authors
+ * add or remove linter-meta blocks between runs.
+ */
+export declare function extractAuthoredBody(rawArtifact: string): string;
 export declare function headingPresent(sections: H2SectionMap, section: string): boolean;
 export declare function sectionBodyByName(sections: H2SectionMap, section: string): string | null;
 export declare function sectionBodyByAnyName(sections: H2SectionMap, sectionNames: string[]): string | null;
@@ -403,6 +452,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;