cclaw-cli 0.51.30 → 0.55.2

package/dist/artifact-linter/design.js

@@ -0,0 +1,323 @@
+import fs from "node:fs/promises";
+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 { extractMarkdownSectionBody, getMarkdownTableRows, meaningfulLineCount, sectionBodyByName, markdownFieldRegex } from "./shared.js";
+const DESIGN_DIAGRAM_REQUIREMENTS = {
+    lightweight: [
+        {
+            section: "Architecture Diagram",
+            markers: ["architecture"],
+            note: "Architecture diagram is required for all tiers."
+        }
+    ],
+    standard: [
+        {
+            section: "Architecture Diagram",
+            markers: ["architecture"],
+            note: "Architecture diagram is required for all tiers."
+        },
+        {
+            section: "Data-Flow Shadow Paths",
+            markers: ["data-flow-shadow-paths"],
+            note: "Standard+ requires data-flow shadow path coverage."
+        },
+        {
+            section: "Error Flow Diagram",
+            markers: ["error-flow"],
+            note: "Standard+ requires explicit error-flow rescue mapping."
+        }
+    ],
+    deep: [
+        {
+            section: "Architecture Diagram",
+            markers: ["architecture"],
+            note: "Architecture diagram is required for all tiers."
+        },
+        {
+            section: "Data-Flow Shadow Paths",
+            markers: ["data-flow-shadow-paths"],
+            note: "Standard+ requires data-flow shadow path coverage."
+        },
+        {
+            section: "Error Flow Diagram",
+            markers: ["error-flow"],
+            note: "Standard+ requires explicit error-flow rescue mapping."
+        },
+        {
+            section: "Deep Diagram Add-on",
+            markers: ["state-machine", "rollback-flowchart", "deployment-sequence"],
+            note: "Deep tier requires one add-on deep diagram (state machine, rollback flowchart, or deployment sequence)."
+        }
+    ]
+};
+function normalizeDesignDiagramTier(value) {
+    if (!value)
+        return null;
+    const normalized = value.trim().toLowerCase();
+    if (/^(?:lite|light|lightweight)$/u.test(normalized))
+        return "lightweight";
+    if (/^standard$/u.test(normalized))
+        return "standard";
+    if (/^deep$/u.test(normalized))
+        return "deep";
+    return null;
+}
+function parseApproachTierSection(sectionBody) {
+    if (!sectionBody)
+        return null;
+    for (const line of sectionBody.split(/\r?\n/u)) {
+        const cleaned = line.replace(/[*_`]/gu, "").trim();
+        const directMatch = /(?:^|\b)tier\s*:\s*(lite|lightweight|light|standard|deep)\b/iu.exec(cleaned);
+        if (directMatch) {
+            const captured = directMatch[1] ?? "";
+            const remainder = cleaned.slice(cleaned.toLowerCase().indexOf("tier") + 4);
+            const tierTokens = remainder.match(/\b(?:lite|lightweight|light|standard|deep)\b/giu) ?? [];
+            const distinct = new Set(tierTokens.map((token) => token.toLowerCase()));
+            if (distinct.size >= 2) {
+                // Multi-token line is the unfilled template placeholder
+                // (`Tier: lite | standard | deep`); treat as no decision.
+                continue;
+            }
+            return normalizeDesignDiagramTier(captured);
+        }
+    }
+    const token = /\b(lite|lightweight|light|standard|deep)\b/iu.exec(sectionBody)?.[1] ?? null;
+    return normalizeDesignDiagramTier(token);
+}
+async function resolveDesignDiagramTier(projectRoot, track, designRaw) {
+    const fromDesign = parseApproachTierSection(extractMarkdownSectionBody(designRaw, "Approach Tier"));
+    if (fromDesign) {
+        return { tier: fromDesign, source: "design-artifact:Approach Tier" };
+    }
+    try {
+        const brainstormArtifact = await resolveStageArtifactPath("brainstorm", {
+            projectRoot,
+            track,
+            intent: "read"
+        });
+        if (await exists(brainstormArtifact.absPath)) {
+            const brainstormRaw = await fs.readFile(brainstormArtifact.absPath, "utf8");
+            const fromBrainstorm = parseApproachTierSection(extractMarkdownSectionBody(brainstormRaw, "Approach Tier"));
+            if (fromBrainstorm) {
+                return { tier: fromBrainstorm, source: "brainstorm-artifact:Approach Tier" };
+            }
+        }
+    }
+    catch {
+        // Ignore read/resolve errors and fall back to default tier.
+    }
+    return { tier: "standard", source: "default:standard" };
+}
+function normalizeCodebaseInvestigationFileRef(value) {
+    const cleaned = value
+        .replace(/`/gu, "")
+        .replace(/^\s*[-*]\s*/u, "")
+        .trim();
+    if (!cleaned)
+        return null;
+    if (/^(?:file|n\/a|none|\(none\)|tbd|\?)$/iu.test(cleaned))
+        return null;
+    return cleaned;
+}
+function collectCodebaseInvestigationFiles(sectionBody) {
+    const refs = [];
+    for (const row of getMarkdownTableRows(sectionBody)) {
+        const fileCell = normalizeCodebaseInvestigationFileRef(row[0] ?? "");
+        if (fileCell)
+            refs.push(fileCell);
+    }
+    return [...new Set(refs)];
+}
+async function runStaleDiagramAudit(projectRoot, artifactPath, artifactRaw, codebaseInvestigationBody) {
+    const markerCount = (artifactRaw.match(/<!--\s*diagram:\s*[a-z0-9-]+\s*-->/giu) ?? []).length;
+    if (markerCount === 0) {
+        return {
+            ok: false,
+            details: "No diagram markers found in design artifact; stale-diagram baseline cannot be computed."
+        };
+    }
+    let artifactStat;
+    try {
+        artifactStat = await fs.stat(artifactPath);
+    }
+    catch {
+        return {
+            ok: false,
+            details: "Cannot stat design artifact to compute diagram marker baseline."
+        };
+    }
+    const refs = collectCodebaseInvestigationFiles(codebaseInvestigationBody);
+    if (refs.length === 0) {
+        return {
+            ok: false,
+            details: "Codebase Investigation must list at least one blast-radius file for stale-diagram audit."
+        };
+    }
+    const stale = [];
+    const missing = [];
+    let scanned = 0;
+    for (const ref of refs) {
+        const absPath = path.isAbsolute(ref) ? ref : path.join(projectRoot, ref);
+        if (!(await exists(absPath))) {
+            missing.push(ref);
+            continue;
+        }
+        let fileStat;
+        try {
+            fileStat = await fs.stat(absPath);
+        }
+        catch {
+            missing.push(ref);
+            continue;
+        }
+        if (!fileStat.isFile())
+            continue;
+        scanned += 1;
+        if (fileStat.mtimeMs > artifactStat.mtimeMs) {
+            stale.push(ref);
+        }
+    }
+    if (missing.length > 0) {
+        return {
+            ok: false,
+            details: `Stale Diagram Audit could not read blast-radius file(s): ${missing.join(", ")}.`
+        };
+    }
+    if (scanned === 0) {
+        return {
+            ok: false,
+            details: "Stale Diagram Audit found no readable blast-radius files in Codebase Investigation."
+        };
+    }
+    if (stale.length > 0) {
+        return {
+            ok: false,
+            details: `Stale Diagram Audit flagged stale file(s) newer than diagram baseline: ${stale.join(", ")}.`
+        };
+    }
+    return {
+        ok: true,
+        details: `Stale Diagram Audit clear: ${scanned} blast-radius file(s) are not newer than diagram baseline.`
+    };
+}
+export async function lintDesignStage(ctx) {
+    const { projectRoot, track, raw, absFile, sections, findings, parsedFrontmatter, brainstormShortCircuitBody, brainstormShortCircuitActivated, staleDiagramAuditEnabled, isTrivialOverride } = ctx;
+    const tierResolution = await resolveDesignDiagramTier(projectRoot, track, raw);
+    const diagramTier = isTrivialOverride
+        ? "lightweight"
+        : tierResolution.tier;
+    const tierSource = isTrivialOverride
+        ? `${tierResolution.source}; trivial override forced lightweight`
+        : tierResolution.source;
+    const hasDiagramMarkers = /<!--\s*diagram:\s*[a-z0-9-]+\s*-->/iu.test(raw);
+    const skipDiagramRequirements = isTrivialOverride && !hasDiagramMarkers;
+    if (skipDiagramRequirements) {
+        findings.push({
+            section: "Diagram Requirement: Architecture Diagram",
+            required: true,
+            rule: "Compact trivial-override slices may omit architecture diagram markers when they intentionally skip diagram work.",
+            found: true,
+            details: "Diagram requirement skipped: compact trivial-override slice without diagram markers."
+        });
+    }
+    else {
+        for (const requirement of DESIGN_DIAGRAM_REQUIREMENTS[diagramTier]) {
+            const sectionBody = sectionBodyByName(sections, requirement.section);
+            const hasSection = sectionBody !== null;
+            const matchedMarker = requirement.markers.find((marker) => {
+                const escapedMarker = marker.replace(/[.*+?^${}()|[\]\\]/gu, "\\$&");
+                const markerRegex = new RegExp(`<!--\\s*diagram:\\s*${escapedMarker}\\s*-->`, "iu");
+                return sectionBody !== null && markerRegex.test(sectionBody);
+            });
+            const hasMarker = matchedMarker !== undefined;
+            const hasContent = sectionBody !== null && meaningfulLineCount(sectionBody) > 0;
+            const found = hasSection && hasMarker && hasContent;
+            const markerList = requirement.markers.map((marker) => `<!-- diagram: ${marker} -->`).join(" or ");
+            findings.push({
+                section: `Diagram Requirement: ${requirement.section}`,
+                required: true,
+                rule: `Design tier "${diagramTier}" requires "${requirement.section}" with marker ${markerList}. ${requirement.note}`,
+                found,
+                details: found
+                    ? `Satisfied (${tierSource}).`
+                    : !hasSection
+                        ? `Missing section "${requirement.section}" (${tierSource}).`
+                        : !hasMarker
+                            ? `Missing marker (${markerList}) in section "${requirement.section}" (${tierSource}).`
+                            : `Section "${requirement.section}" has marker but no meaningful content (${tierSource}).`
+            });
+        }
+    }
+    if (staleDiagramAuditEnabled) {
+        if (isTrivialOverride && !hasDiagramMarkers) {
+            findings.push({
+                section: "Stale Diagram Drift Check",
+                required: true,
+                rule: "When stale-diagram audit is enabled, compact trivial-override slices may skip the drift check only if no design diagram markers are present.",
+                found: true,
+                details: "Stale Diagram Audit skipped: artifact has no diagram markers (compact trivial-override slice)."
+            });
+        }
+        else {
+            const codebaseInvestigation = sectionBodyByName(sections, "Codebase Investigation");
+            if (codebaseInvestigation === null) {
+                findings.push({
+                    section: "Stale Diagram Drift Check",
+                    required: true,
+                    rule: "When stale-diagram audit is enabled, stale diagram audit requires Codebase Investigation blast-radius files.",
+                    found: false,
+                    details: "No ## heading matching required section \"Codebase Investigation\"."
+                });
+            }
+            else {
+                const staleAudit = await runStaleDiagramAudit(projectRoot, absFile, raw, codebaseInvestigation);
+                findings.push({
+                    section: "Stale Diagram Drift Check",
+                    required: true,
+                    rule: "When stale-diagram audit is enabled, blast-radius files must not be newer than current design diagram baseline.",
+                    found: staleAudit.ok,
+                    details: staleAudit.details
+                });
+            }
+        }
+    }
+    // Universal Layer 2.3 structural checks (gstack plan-eng-review). All
+    // present-only. Validates regression iron-rule acknowledgment and
+    // confidence-calibrated finding format.
+    const regressionBody = sectionBodyByName(sections, "Regression Iron Rule");
+    if (regressionBody !== null) {
+        const ack = markdownFieldRegex("Iron rule acknowledged", "yes|true|y").test(regressionBody);
+        findings.push({
+            section: "Regression Iron Rule Acknowledgement",
+            required: true,
+            rule: "Regression Iron Rule section must affirm `Iron rule acknowledged: yes`.",
+            found: ack,
+            details: ack
+                ? "Regression iron rule acknowledged."
+                : "Regression Iron Rule is missing explicit `Iron rule acknowledged: yes`."
+        });
+    }
+    const findingsBody = sectionBodyByName(sections, "Calibrated Findings");
+    if (findingsBody !== null) {
+        const isEmpty = /(^|\n)\s*-\s*None this stage\b/iu.test(findingsBody);
+        const findingRegex = new RegExp(CONFIDENCE_FINDING_REGEX_SOURCE, "u");
+        const validRows = findingsBody
+            .split("\n")
+            .filter((line) => /^[-*]\s+\[/u.test(line.trim()))
+            .filter((line) => findingRegex.test(line));
+        const ok = isEmpty || validRows.length >= 1;
+        findings.push({
+            section: "Calibrated Finding Format",
+            required: true,
+            rule: "Calibrated Findings must either declare `None this stage` or contain at least one finding in the form `[P1|P2|P3] (confidence: <n>/10) <path>[:<line>] — <description>`.",
+            found: ok,
+            details: isEmpty
+                ? "No findings recorded for this stage."
+                : ok
+                    ? `Detected ${validRows.length} calibrated finding(s).`
+                    : "No calibrated findings detected. Use `[P1|P2|P3] (confidence: <n>/10) <repo-path>[:<line>] — <description>`."
+        });
+    }
+}

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

@@ -0,0 +1,2 @@
+import { type StageLintContext } from "./shared.js";
+export declare function lintPlanStage(ctx: StageLintContext): Promise<void>;

package/dist/artifact-linter/plan.js

@@ -0,0 +1,162 @@
+import { 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;
+    const strictPlanGuards = parsedFrontmatter.hasFrontmatter ||
+        headingPresent(sections, "Plan Quality Scan") ||
+        headingPresent(sections, "Locked Decision Coverage");
+    const taskListBody = sectionBodyByName(sections, "Task List") ?? raw;
+    const placeholderHits = collectPatternHits(taskListBody, PLACEHOLDER_PATTERNS);
+    findings.push({
+        section: "Plan Quality Scan: Placeholders",
+        required: strictPlanGuards,
+        rule: "Task List must not contain placeholders (TODO/TBD/FIXME/<fill-in>/<your-*-here>/xxx/ellipsis).",
+        found: placeholderHits.length === 0,
+        details: placeholderHits.length === 0
+            ? "No placeholder tokens detected in Task List."
+            : `Detected placeholder token(s) in Task List: ${placeholderHits.join(", ")}.`
+    });
+    const scopeArtifact = await resolveStageArtifactPath("scope", {
+        projectRoot,
+        track,
+        intent: "read"
+    });
+    const scopeRaw = (await exists(scopeArtifact.absPath))
+        ? await fs.readFile(scopeArtifact.absPath, "utf8")
+        : "";
+    const scopeDecisionIds = extractDecisionIds(scopeRaw);
+    const missingDecisionRefs = scopeDecisionIds.filter((id) => !raw.includes(id));
+    findings.push({
+        section: "Locked Decision Traceability",
+        required: strictPlanGuards && scopeDecisionIds.length > 0,
+        rule: "Every locked decision ID (D-XX) in scope must be referenced in plan.",
+        found: missingDecisionRefs.length === 0,
+        details: scopeDecisionIds.length === 0
+            ? "No D-XX IDs found in scope artifact; traceability check skipped."
+            : missingDecisionRefs.length === 0
+                ? `All ${scopeDecisionIds.length} scope decision IDs are referenced in plan.`
+                : `Missing scope decision reference(s) in plan: ${missingDecisionRefs.join(", ")}.`
+    });
+    const reductionHits = collectPatternHits(taskListBody, SCOPE_REDUCTION_PATTERNS);
+    findings.push({
+        section: "Plan Quality Scan: Scope Reduction",
+        required: strictPlanGuards && scopeDecisionIds.length > 0,
+        rule: "Task List must not include scope-reduction language when locked decisions exist.",
+        found: reductionHits.length === 0,
+        details: scopeDecisionIds.length === 0
+            ? "No locked decisions found in scope artifact; scope-reduction scan is advisory."
+            : reductionHits.length === 0
+                ? "No scope-reduction phrases detected in Task List."
+                : `Detected scope-reduction phrase(s) in Task List: ${reductionHits.join(", ")}.`
+    });
+    // Universal Layer 2.5 structural checks (superpowers writing-plans + ce-plan).
+    // Plan-wide placeholder scan (broader than Task List) using the
+    // FORBIDDEN_PLACEHOLDER_TOKENS list shared with the cross-cutting block.
+    const planHeaderBody = sectionBodyByName(sections, "Plan Header");
+    if (planHeaderBody !== null) {
+        const required = ["Goal:", "Architecture:", "Tech Stack:"];
+        const missing = required.filter((token) => !new RegExp(token.replace(":", "\\s*:"), "iu").test(planHeaderBody));
+        findings.push({
+            section: "Plan Header Coverage",
+            required: true,
+            rule: "Plan Header must include Goal, Architecture, and Tech Stack lines.",
+            found: missing.length === 0,
+            details: missing.length === 0
+                ? "Plan Header covers Goal/Architecture/Tech Stack."
+                : `Plan Header is missing field(s): ${missing.join(", ")}.`
+        });
+    }
+    const unitBlocks = raw.match(/###\s+Implementation Unit\s+U-\d+/giu) ?? [];
+    if (unitBlocks.length > 0) {
+        const requiredKeys = ["Goal:", "Files", "Approach:", "Test scenarios:", "Verification:"];
+        const blockBodies = raw.split(/(?=###\s+Implementation Unit\s+U-\d+)/iu).slice(1);
+        const validBlocks = blockBodies.filter((block) => requiredKeys.every((key) => new RegExp(key.replace(":", "\\s*:"), "iu").test(block)));
+        findings.push({
+            section: "Implementation Unit Shape",
+            required: true,
+            rule: "Each `### Implementation Unit U-<n>` must include Goal, Files, Approach, Test scenarios, Verification.",
+            found: validBlocks.length === unitBlocks.length,
+            details: validBlocks.length === unitBlocks.length
+                ? `All ${unitBlocks.length} implementation unit(s) include the required fields.`
+                : `${unitBlocks.length - validBlocks.length} implementation unit(s) are missing required fields.`
+        });
+    }
+    const allPlaceholderTokens = FORBIDDEN_PLACEHOLDER_TOKENS.map((token) => token.toLowerCase());
+    const lowerRaw = raw.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
+    // the plan deliberately references the rule by name.
+    const placeholderRuleSection = sectionBodyByName(sections, "NO PLACEHOLDERS Rule");
+    const ruleScanBody = (placeholderRuleSection ?? "").toLowerCase();
+    const ruleAcceptedHits = ruleScanBody.length > 0
+        ? allPlaceholderTokens.filter((token) => ruleScanBody.includes(token))
+        : [];
+    const filteredPlanHits = planWidePlaceholderHits.filter((token) => {
+        // If the only occurrence is in the rule section, ignore it.
+        if (!ruleAcceptedHits.includes(token))
+            return true;
+        const occurrencesElsewhere = lowerRaw.split(token).length - 1
+            - (ruleScanBody.split(token).length - 1);
+        return occurrencesElsewhere > 0;
+    });
+    findings.push({
+        section: "Plan-wide Placeholder Scan",
+        required: false,
+        rule: "Plan should not contain forbidden placeholder tokens outside the NO PLACEHOLDERS rule section.",
+        found: filteredPlanHits.length === 0,
+        details: filteredPlanHits.length === 0
+            ? "No forbidden placeholder tokens detected outside the rule section."
+            : `Detected forbidden token(s) elsewhere in plan: ${filteredPlanHits.join(", ")}.`
+    });
+    const handoffBody = sectionBodyByName(sections, "Execution Handoff");
+    if (handoffBody !== null) {
+        const ok = /(subagent-driven|inline executor)/iu.test(handoffBody);
+        findings.push({
+            section: "Execution Handoff Posture",
+            required: true,
+            rule: "Execution Handoff must declare a posture (Subagent-Driven or Inline executor).",
+            found: ok,
+            details: ok
+                ? "Execution Handoff posture declared."
+                : "Execution Handoff is missing a posture declaration (Subagent-Driven or Inline executor)."
+        });
+    }
+    const planCalibratedBody = sectionBodyByName(sections, "Calibrated Findings");
+    if (planCalibratedBody !== null) {
+        const isEmpty = /none this stage|none\b/iu.test(planCalibratedBody);
+        const findingRegex = new RegExp(CONFIDENCE_FINDING_REGEX_SOURCE, "iu");
+        const validRows = planCalibratedBody
+            .split("\n")
+            .filter((line) => /^[-*]\s+\[/u.test(line.trim()))
+            .filter((line) => findingRegex.test(line));
+        const ok = isEmpty || validRows.length >= 1;
+        findings.push({
+            section: "Plan Calibrated Finding Format",
+            required: false,
+            rule: "Calibrated Findings should either declare `None this stage` or include at least one line in `[P1|P2|P3] (confidence: <n>/10) <path>[:<line>] — <description>` format.",
+            found: ok,
+            details: isEmpty
+                ? "No calibrated findings recorded for this plan stage."
+                : ok
+                    ? `Detected ${validRows.length} calibrated plan finding(s).`
+                    : "No calibrated findings detected in canonical format."
+        });
+    }
+    const regressionIronBody = sectionBodyByName(sections, "Regression Iron Rule");
+    if (regressionIronBody !== null) {
+        const acknowledged = /iron\s+rule\s+acknowledged\s*:\s*yes\b/iu.test(regressionIronBody);
+        findings.push({
+            section: "Plan Regression Iron Rule Acknowledgement",
+            required: false,
+            rule: "Regression Iron Rule should include `Iron rule acknowledged: yes`.",
+            found: acknowledged,
+            details: acknowledged
+                ? "Regression Iron Rule is explicitly acknowledged."
+                : "Regression Iron Rule section is present but missing `Iron rule acknowledged: yes`."
+        });
+    }
+}

package/dist/artifact-linter/review-army.d.ts

@@ -0,0 +1,24 @@
+export declare function validateReviewArmy(projectRoot: string): Promise<{
+    valid: boolean;
+    errors: string[];
+}>;
+export interface ReviewVerdictConsistencyResult {
+    ok: boolean;
+    errors: string[];
+    finalVerdict: "APPROVED" | "APPROVED_WITH_CONCERNS" | "BLOCKED" | "UNKNOWN";
+    openCriticalCount: number;
+    shipBlockerCount: number;
+}
+export interface ReviewSecurityNoChangeAttestationResult {
+    ok: boolean;
+    errors: string[];
+    hasSecurityFinding: boolean;
+    hasNoChangeAttestation: boolean;
+}
+/**
+ * Ensure the narrative verdict in 07-review.md is consistent with the
+ * structured review-army reconciliation. A review cannot declare
+ * APPROVED while open Critical findings or shipBlockers remain.
+ */
+export declare function checkReviewVerdictConsistency(projectRoot: string): Promise<ReviewVerdictConsistencyResult>;
+export declare function checkReviewSecurityNoChangeAttestation(projectRoot: string): Promise<ReviewSecurityNoChangeAttestationResult>;