cclaw-cli 6.6.0 → 6.7.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,4 +1,4 @@
-import { evaluateInvestigationTrace, 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";
@@ -86,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/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;

package/dist/artifact-linter/shared.js

@@ -384,6 +384,41 @@ export function duplicateH2Headings(markdown) {
         .filter(([, count]) => count > 1)
         .map(([key]) => displayHeading.get(key) ?? key);
 }
+/**
+ * Return the author-authored prose of an artifact, stripping linter meta
+ * regions so free-text scans (placeholder tokens, scope-reduction phrases,
+ * investigation trigger words) don't self-cannibalize by matching the
+ * linter's own templated meta-phrases.
+ *
+ * Stripping rules (in order):
+ *   1. `<!-- linter-meta --> ... <!-- /linter-meta -->` paired blocks.
+ *      Both markers must appear on their own line; unterminated openings
+ *      are left as-is so a malformed artifact cannot hide arbitrary
+ *      content by omitting the closing marker.
+ *   2. Every other HTML comment (`<!-- ... -->`, possibly multi-line).
+ *   3. Fenced code blocks that are tagged `linter-rule` (e.g.
+ *      ```` ```linter-rule ````). Plain fenced code blocks are preserved
+ *      because many stages quote code samples that the linter should
+ *      still see.
+ *
+ * The function guarantees the returned string is a strict subset of the
+ * original: no characters are synthesized, and line offsets are
+ * preserved for any surviving line (blank lines stand in for stripped
+ * regions). This keeps regex-based linter checks stable when authors
+ * add or remove linter-meta blocks between runs.
+ */
+export function extractAuthoredBody(rawArtifact) {
+    if (typeof rawArtifact !== "string" || rawArtifact.length === 0) {
+        return "";
+    }
+    const linterMetaBlock = /^[ \t]*<!--\s*linter-meta\s*-->[\s\S]*?^[ \t]*<!--\s*\/linter-meta\s*-->[ \t]*$/gmu;
+    let body = rawArtifact.replace(linterMetaBlock, (match) => match.replace(/[^\n]/gu, ""));
+    const htmlComment = /<!--[\s\S]*?-->/gu;
+    body = body.replace(htmlComment, (match) => match.replace(/[^\n]/gu, ""));
+    const linterRuleFence = /^([ \t]*)(`{3,}|~{3,})\s*linter-rule\b[^\n]*\n[\s\S]*?\n\1\2[ \t]*$/gmu;
+    body = body.replace(linterRuleFence, (match) => match.replace(/[^\n]/gu, ""));
+    return body;
+}
 export function headingPresent(sections, section) {
     const want = normalizeHeadingTitle(section).toLowerCase();
     for (const h of sections.keys()) {

package/dist/artifact-linter.d.ts

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

package/dist/artifact-linter.js

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

package/dist/content/hooks.js

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

package/dist/content/node-hooks.js

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