cclaw-cli 6.0.0 → 6.1.1

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

@@ -1,2 +1,18 @@
 import { type StageLintContext } from "./shared.js";
+export interface CodebaseInvestigationFileRef {
+    /** Filename to stat (parenthetical suffix already stripped). */
+    filename: string;
+    /** Raw cell content, useful for diagnostic messages. */
+    raw: string;
+    /** When true, the audit treats this row as a "new file, no baseline". */
+    newFile: boolean;
+    /**
+     * When true, the audit skips this row entirely (suffix `(skip)`,
+     * `(deleted)`, `(stub)`, leading `#`, or a `skip:` token in the
+     * Notes column).
+     */
+    skip: boolean;
+}
+export declare function normalizeCodebaseInvestigationFileRef(value: string, notesCell: string): CodebaseInvestigationFileRef | null;
+export declare function collectCodebaseInvestigationFiles(sectionBody: string): CodebaseInvestigationFileRef[];
 export declare function lintDesignStage(ctx: StageLintContext): Promise<void>;

package/dist/artifact-linter/design.js

@@ -110,25 +110,73 @@ async function resolveDesignDiagramTier(projectRoot, track, designRaw) {
     }
     return { tier: "standard", source: "default:standard" };
 }
-function normalizeCodebaseInvestigationFileRef(value) {
-    const cleaned = value
+/**
+ * Wave 25 (v6.1.0) — parenthetical suffixes that the audit strips
+ * from a Codebase Investigation filename cell BEFORE attempting
+ * `fs.stat`. The user's quick-tier test wrote `index.html (new)` in
+ * the table, and the linter then tried to stat the literal string
+ * `index.html (new)` (with the suffix) and failed with "could not
+ * read blast-radius file(s): index.html (new)". Authors used these
+ * markers as informational labels, not as part of the filename.
+ *
+ * Stripping happens for ANY parenthetical suffix on the same line as
+ * the filename cell so we don't have to enumerate every author
+ * convention. For new files (suffix "new"), the audit records
+ * "new file, no stale diagrams to detect" instead of trying to stat.
+ */
+const STALE_DIAGRAM_NEW_FILE_SUFFIX_PATTERN = /\(\s*new(?:[\s-]?file)?\s*\)/iu;
+const STALE_DIAGRAM_SKIP_FILE_SUFFIX_PATTERN = /\(\s*(?:n\/a|skip|skipped|deleted|removed|stub|placeholder|tbd)\s*\)/iu;
+export function normalizeCodebaseInvestigationFileRef(value, notesCell) {
+    const cleanedFull = value
         .replace(/`/gu, "")
         .replace(/^\s*[-*]\s*/u, "")
         .trim();
-    if (!cleaned)
+    if (!cleanedFull)
         return null;
-    if (/^(?:file|n\/a|none|\(none\)|tbd|\?)$/iu.test(cleaned))
+    if (/^#/u.test(cleanedFull)) {
+        return { filename: cleanedFull.replace(/^#\s*/u, ""), raw: cleanedFull, newFile: false, skip: true };
+    }
+    // Strip ANY trailing parenthetical suffix(es) so the audit operates
+    // on the raw filename. We loop because authors sometimes stack
+    // multiple suffixes (`index.html (new) (stub)`).
+    let stripped = cleanedFull;
+    let newFile = false;
+    let skip = false;
+    for (let safety = 0; safety < 4; safety += 1) {
+        const trailingParen = /\s*\([^)]*\)\s*$/u.exec(stripped);
+        if (!trailingParen)
+            break;
+        const parenText = trailingParen[0];
+        if (STALE_DIAGRAM_NEW_FILE_SUFFIX_PATTERN.test(parenText))
+            newFile = true;
+        if (STALE_DIAGRAM_SKIP_FILE_SUFFIX_PATTERN.test(parenText))
+            skip = true;
+        stripped = stripped.slice(0, trailingParen.index).trim();
+    }
+    if (!stripped)
+        return null;
+    if (/^(?:file|n\/a|none|\(none\)|tbd|\?)$/iu.test(stripped))
         return null;
-    return cleaned;
+    // Notes column may carry an explicit `skip:` marker (Wave 25).
+    if (/(?:^|\s|\|)skip\s*:/iu.test(notesCell))
+        skip = true;
+    return { filename: stripped, raw: cleanedFull, newFile, skip };
 }
-function collectCodebaseInvestigationFiles(sectionBody) {
+export function collectCodebaseInvestigationFiles(sectionBody) {
     const refs = [];
+    const seen = new Set();
     for (const row of getMarkdownTableRows(sectionBody)) {
-        const fileCell = normalizeCodebaseInvestigationFileRef(row[0] ?? "");
-        if (fileCell)
-            refs.push(fileCell);
+        const notesCell = row[row.length - 1] ?? "";
+        const fileCell = normalizeCodebaseInvestigationFileRef(row[0] ?? "", notesCell);
+        if (!fileCell)
+            continue;
+        const key = `${fileCell.filename}|${fileCell.skip}|${fileCell.newFile}`;
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        refs.push(fileCell);
     }
-    return [...new Set(refs)];
+    return refs;
 }
 async function runStaleDiagramAudit(projectRoot, artifactPath, artifactRaw, codebaseInvestigationBody) {
     const markerCount = (artifactRaw.match(/<!--\s*diagram:\s*[a-z0-9-]+\s*-->/giu) ?? []).length;
@@ -157,11 +205,21 @@ async function runStaleDiagramAudit(projectRoot, artifactPath, artifactRaw, code
     }
     const stale = [];
     const missing = [];
+    const newFiles = [];
+    const skipped = [];
     let scanned = 0;
     for (const ref of refs) {
-        const absPath = path.isAbsolute(ref) ? ref : path.join(projectRoot, ref);
+        if (ref.skip) {
+            skipped.push(ref.filename);
+            continue;
+        }
+        if (ref.newFile) {
+            newFiles.push(ref.filename);
+            continue;
+        }
+        const absPath = path.isAbsolute(ref.filename) ? ref.filename : path.join(projectRoot, ref.filename);
         if (!(await exists(absPath))) {
-            missing.push(ref);
+            missing.push(ref.filename);
             continue;
         }
         let fileStat;
@@ -169,23 +227,29 @@ async function runStaleDiagramAudit(projectRoot, artifactPath, artifactRaw, code
             fileStat = await fs.stat(absPath);
         }
         catch {
-            missing.push(ref);
+            missing.push(ref.filename);
             continue;
         }
         if (!fileStat.isFile())
             continue;
         scanned += 1;
         if (fileStat.mtimeMs > artifactStat.mtimeMs) {
-            stale.push(ref);
+            stale.push(ref.filename);
         }
     }
     if (missing.length > 0) {
         return {
             ok: false,
-            details: `Stale Diagram Audit could not read blast-radius file(s): ${missing.join(", ")}.`
+            details: `Stale Diagram Audit could not read blast-radius file(s): ${missing.join(", ")}. Strip parenthetical suffixes like \` (new)\`, \` (deleted)\`, \` (stub)\` from the filename column, mark new files as \`<path> (new)\`, or add a leading \`#\` to the filename to skip the row.`
         };
     }
-    if (scanned === 0) {
+    const noteParts = [];
+    if (skipped.length > 0)
+        noteParts.push(`${skipped.length} skipped (${skipped.join(", ")})`);
+    if (newFiles.length > 0)
+        noteParts.push(`${newFiles.length} new file(s) with no stale diagrams to detect (${newFiles.join(", ")})`);
+    const notes = noteParts.length > 0 ? `; ${noteParts.join("; ")}` : "";
+    if (scanned === 0 && newFiles.length === 0 && skipped.length === 0) {
         return {
             ok: false,
             details: "Stale Diagram Audit found no readable blast-radius files in Codebase Investigation."
@@ -194,12 +258,12 @@ async function runStaleDiagramAudit(projectRoot, artifactPath, artifactRaw, code
     if (stale.length > 0) {
         return {
             ok: false,
-            details: `Stale Diagram Audit flagged stale file(s) newer than diagram baseline: ${stale.join(", ")}.`
+            details: `Stale Diagram Audit flagged stale file(s) newer than diagram baseline: ${stale.join(", ")}${notes}.`
         };
     }
     return {
         ok: true,
-        details: `Stale Diagram Audit clear: ${scanned} blast-radius file(s) are not newer than diagram baseline.`
+        details: `Stale Diagram Audit clear: ${scanned} blast-radius file(s) are not newer than diagram baseline${notes}.`
     };
 }
 export async function lintDesignStage(ctx) {

package/dist/artifact-linter/scope.js

@@ -1,7 +1,9 @@
 import { checkCriticPredictionsContract, evaluateQaLogFloor, sectionBodyByHeadingPrefix, sectionBodyByName, extractCanonicalScopeMode, getMarkdownTableRows } from "./shared.js";
-import { readDelegationLedger } from "../delegation.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 } = ctx;
+    const { projectRoot, track, raw, absFile, sections, findings, parsedFrontmatter, brainstormShortCircuitBody, brainstormShortCircuitActivated, staleDiagramAuditEnabled, isTrivialOverride, activeStageFlags, taskClass } = ctx;
     const lockedDecisionsBody = sectionBodyByHeadingPrefix(sections, "Locked Decisions") ?? "";
     const scopeSummaryBody = sectionBodyByName(sections, "Scope Summary") ?? "";
     const selectedScopeMode = extractCanonicalScopeMode(scopeSummaryBody);
@@ -32,24 +34,61 @@ export async function lintScopeStage(ctx) {
     }
     const strategistRequired = selectedScopeMode === "SCOPE EXPANSION" || selectedScopeMode === "SELECTIVE EXPANSION";
     if (strategistRequired) {
-        const delegationLedger = await readDelegationLedger(projectRoot);
-        const discoveryRows = delegationLedger.entries.filter((entry) => entry.stage === "scope" &&
-            entry.agent === "product-discovery" &&
-            entry.runId === delegationLedger.runId &&
-            entry.status === "completed");
-        const hasCompleted = discoveryRows.length > 0;
-        const hasEvidence = discoveryRows.some((entry) => Array.isArray(entry.evidenceRefs) && entry.evidenceRefs.length > 0);
-        findings.push({
-            section: "Expansion Strategist Delegation",
-            required: true,
-            rule: "When Scope Summary selects SCOPE EXPANSION or SELECTIVE EXPANSION, a completed `product-discovery` delegation for the active run with non-empty evidenceRefs is required.",
-            found: hasCompleted && hasEvidence,
-            details: !hasCompleted
-                ? `Scope mode ${selectedScopeMode} requires a completed product-discovery delegation row for active run ${delegationLedger.runId}.`
-                : hasEvidence
-                    ? `product-discovery delegation satisfied for mode ${selectedScopeMode}.`
-                    : "product-discovery delegation exists but evidenceRefs is empty; add at least one artifact/code evidence reference."
-        });
+        // Wave 25 (v6.1.0) — for `track === "quick"` (lite-tier) or
+        // `taskClass === "software-bugfix"`, the Expansion Strategist
+        // delegation requirement is dropped entirely. The user's
+        // 3-file static landing page hit this gate without any
+        // discovery scope — pure ceremony for trivial work. Standard
+        // tracks remain unchanged.
+        const skipByTrack = shouldDemoteArtifactValidationByTrack(track, taskClass);
+        if (skipByTrack) {
+            findings.push({
+                section: "Expansion Strategist Delegation",
+                required: false,
+                rule: "When Scope Summary selects SCOPE EXPANSION or SELECTIVE EXPANSION, a completed `product-discovery` delegation for the active run with non-empty evidenceRefs is required.",
+                found: true,
+                details: `Expansion Strategist delegation requirement skipped for track="${track}"` +
+                    (taskClass ? `, taskClass="${taskClass}"` : "") +
+                    ` (Wave 25: lite-tier escape; selectedMode=${selectedScopeMode}).`
+            });
+            // Best-effort audit; we read the flow-state runId here
+            // because StageLintContext does not surface it directly.
+            try {
+                const flowState = await readFlowState(projectRoot);
+                const runId = flowState.activeRunId ?? null;
+                if (runId) {
+                    await recordExpansionStrategistSkippedByTrack(projectRoot, {
+                        track,
+                        taskClass: taskClass ?? null,
+                        runId,
+                        selectedScopeMode
+                    }).catch(() => { });
+                }
+            }
+            catch {
+                // Audit is best-effort; never block scope linting.
+            }
+        }
+        else {
+            const delegationLedger = await readDelegationLedger(projectRoot);
+            const discoveryRows = delegationLedger.entries.filter((entry) => entry.stage === "scope" &&
+                entry.agent === "product-discovery" &&
+                entry.runId === delegationLedger.runId &&
+                entry.status === "completed");
+            const hasCompleted = discoveryRows.length > 0;
+            const hasEvidence = discoveryRows.some((entry) => Array.isArray(entry.evidenceRefs) && entry.evidenceRefs.length > 0);
+            findings.push({
+                section: "Expansion Strategist Delegation",
+                required: true,
+                rule: "When Scope Summary selects SCOPE EXPANSION or SELECTIVE EXPANSION, a completed `product-discovery` delegation for the active run with non-empty evidenceRefs is required.",
+                found: hasCompleted && hasEvidence,
+                details: !hasCompleted
+                    ? `Scope mode ${selectedScopeMode} requires a completed product-discovery delegation row for active run ${delegationLedger.runId}.`
+                    : hasEvidence
+                        ? `product-discovery delegation satisfied for mode ${selectedScopeMode}.`
+                        : "product-discovery delegation exists but evidenceRefs is empty; add at least one artifact/code evidence reference."
+            });
+        }
     }
     const criticPredictions = checkCriticPredictionsContract(sections);
     if (criticPredictions !== null) {

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

@@ -236,7 +236,34 @@ export interface InteractionEdgeCaseRequirement {
     pattern: RegExp;
 }
 export declare const INTERACTION_EDGE_CASE_REQUIREMENTS: readonly InteractionEdgeCaseRequirement[];
-export declare function validateInteractionEdgeCaseMatrix(sectionBody: string): {
+/**
+ * Wave 25 (v6.1.0) — context for `validateInteractionEdgeCaseMatrix`.
+ *
+ * The user's quick-tier test of a 3-file static landing page hit
+ * "Interaction Edge Case row \"nav-away-mid-request\" must mark
+ * Handled? as yes/no" because they wrote `N/A` (no network at all).
+ * Then `unhandled must reference a deferred item id (for example
+ * D-12)`. Wave 25 introduces:
+ *
+ *   1. `N/A — <reason>` (em-dash + free-text reason) is now an
+ *      accepted Handled? value. The reason replaces the D-XX
+ *      requirement.
+ *   2. When the caller signals lite-tier and the design has no
+ *      network/external dependencies (detected via the Architecture
+ *      Diagram body or a missing Failure Mode Table), the standard
+ *      mandatory rows (`nav-away-mid-request`, `10K-result dataset`,
+ *      `background-job abandonment`, `zombie connection`) are
+ *      treated as advisory rather than required. The `double-click`
+ *      row stays mandatory because UI duplicate-action handling is
+ *      relevant even for static pages.
+ */
+export interface InteractionEdgeCaseValidationContext {
+    /** Optional H2 sections map for cross-section "no network" detection. */
+    sections?: H2SectionMap | null;
+    /** When true, network-dependent mandatory rows become advisory. */
+    liteTier?: boolean;
+}
+export declare function validateInteractionEdgeCaseMatrix(sectionBody: string, context?: InteractionEdgeCaseValidationContext): {
     ok: boolean;
     details: string;
 };
@@ -251,14 +278,76 @@ export declare function validatePreScopeSystemAudit(sectionBody: string): {
 export declare const DIAGRAM_ARROW_PATTERN: RegExp;
 export declare const DIAGRAM_FAILURE_EDGE_PATTERN: RegExp;
 export declare const DIAGRAM_GENERIC_NODE_PATTERN: RegExp;
+/**
+ * Wave 25 (v6.1.0) — external-dependency keywords that trigger the
+ * failure-edge requirement. The architecture diagram is allowed to
+ * omit failure edges only when ALL of:
+ *   - Failure Mode Table has zero rows.
+ *   - The diagram body mentions no external-dependency keyword.
+ *
+ * Static landing pages (3 HTML/CSS/JS files, no network) match this:
+ * no failure modes to map, no external systems to fail. The previous
+ * blanket "must include at least one failure-edge" rule produced
+ * ceremony-only failures that the agent worked around with fake
+ * `(timeout)` annotations, defeating the spirit of the rule.
+ */
+export declare const DIAGRAM_EXTERNAL_DEPENDENCY_PATTERN: RegExp;
 export declare const TEST_COMMAND_MARKER_PATTERN: RegExp;
 export declare const RED_FAILURE_MARKER_PATTERN: RegExp;
 export declare const GREEN_SUCCESS_MARKER_PATTERN: RegExp;
 export declare function diagramEdgeLines(sectionBody: string): string[];
 export declare function hasFailureEdgeInDiagram(sectionBody: string): boolean;
 export declare function hasLabeledDiagramArrow(lines: string[]): boolean;
+/**
+ * Wave 25 (v6.1.0) — accepted async edge patterns. Returns true when
+ * a line carries any of:
+ *
+ *   - `-.->`, `-->>`, `~~>` (mermaid dotted/messaging arrows)
+ *   - `- - ->` (loose dotted ASCII arrow with optional spaces)
+ *   - `.....>` (3-or-more dots followed by `>`)
+ *   - `\basync\b` text token (label-based)
+ *   - `[async]` bracketed label, `async:` prefix, `async:` cell content
+ *
+ * The error message printed when this fails (see
+ * `validateArchitectureDiagram`) lists every accepted pattern
+ * verbatim so the agent does not have to guess.
+ */
 export declare function hasAsyncDiagramEdge(lines: string[]): boolean;
+/**
+ * Wave 25 (v6.1.0) — accepted sync edge patterns. Returns true when a
+ * line carries any of:
+ *
+ *   - `\bsync\b` text token (label-based)
+ *   - `[sync]` bracketed label, `sync:` prefix, `sync:` cell content
+ *   - Solid `-->`, `->`, `=>`, `→`, `⟶`, `↦` arrow that is NOT a known
+ *     dotted/async variant (`-.->`, `-->>`, `~~>`)
+ *   - `===>` (3+ `=` then `>`) and `--->` (3+ `-` then `>`) heavy solid
+ *     arrows
+ */
 export declare function hasSyncDiagramEdge(lines: string[]): boolean;
+/**
+ * Wave 25 (v6.1.0) — exact accepted-pattern list shown in the error
+ * message when sync/async distinction fails. Keep in sync with
+ * `hasAsyncDiagramEdge` / `hasSyncDiagramEdge` above.
+ */
+export declare const DIAGRAM_SYNC_ASYNC_ACCEPTED_PATTERNS: readonly ["Solid arrows: `-->`, `->`, `===>`, `--->`, `=>`, `→`, `⟶`, `↦`", "Dotted/async arrows: `-.->`, `-->>`, `~~>`, `- - ->`, `.....>`", "Text labels on the same line: `sync` / `async`", "Bracket labels: `[sync]` / `[async]`", "Cell-prefix labels: `sync:` / `async:` (e.g. `A -->|sync: persist| B`)"];
+export interface ArchitectureDiagramValidationContext {
+    /** Optional H2 sections map for cross-section checks (e.g. Failure Mode Table presence). */
+    sections?: H2SectionMap | null;
+}
+export interface ArchitectureDiagramValidationResult {
+    ok: boolean;
+    details: string;
+}
+/**
+ * Wave 25 (v6.1.0) — Architecture Diagram structural check.
+ *
+ * Promoted out of `validateSectionBody` so it can take a `sections`
+ * map and conditionally enforce the failure-edge rule based on
+ * cross-section context (Failure Mode Table presence + diagram body
+ * mentioning external-dependency keywords).
+ */
+export declare function validateArchitectureDiagram(sectionBody: string, context?: ArchitectureDiagramValidationContext): ArchitectureDiagramValidationResult;
 export declare function validateTddRedEvidence(sectionBody: string): {
     ok: boolean;
     details: string;
@@ -334,7 +423,24 @@ export declare function collectPatternHits(text: string, patterns: Array<{
     label: string;
     regex: RegExp;
 }>): string[];
-export declare function validateSectionBody(sectionBody: string, rule: string, sectionName: string): {
+export interface ValidateSectionBodyContext {
+    /**
+     * Wave 25 (v6.1.0) — optional H2 sections map for cross-section
+     * checks (e.g. Architecture Diagram failure-edge enforcement gates
+     * on Failure Mode Table presence). When omitted, cross-section
+     * checks fall back to legacy blanket enforcement.
+     */
+    sections?: H2SectionMap | null;
+    /**
+     * Wave 25 (v6.1.0) — when true, lite-tier-only relaxations apply.
+     * Currently used by the Interaction Edge Case matrix to demote
+     * network-dependent mandatory rows to advisory when the design has
+     * no Failure Mode Table rows and no external-dependency keywords
+     * in the Architecture Diagram body.
+     */
+    liteTier?: boolean;
+}
+export declare function validateSectionBody(sectionBody: string, rule: string, sectionName: string, context?: ValidateSectionBodyContext): {
     ok: boolean;
     details: string;
 };
@@ -360,4 +466,14 @@ export interface StageLintContext {
      * When orchestrator cannot read flow-state, defaults to an empty array.
      */
     activeStageFlags: string[];
+    /**
+     * Wave 25 (v6.1.0) — task class for the active run, mirrored from
+     * `flow-state.json::taskClass`. `null` when not classified. Stage
+     * linters read this together with `track` via
+     * `shouldDemoteArtifactValidationByTrack` to demote advanced
+     * artifact-level checks (architecture diagram async/failure edges,
+     * interaction edge-case mandatory rows, stale-diagram drift,
+     * expansion-strategist delegation) from required → advisory.
+     */
+    taskClass: "software-standard" | "software-trivial" | "software-bugfix" | null;
 }