cclaw-cli 0.45.0 → 0.46.0

package/README.md

@@ -140,7 +140,7 @@ Plus harness-specific shims:
 `cclaw init` writes five keys, on purpose:
 
 ```yaml
-version: 0.45.0
+version: 0.46.0
 flowVersion: 1.0.0
 harnesses:
   - codex

package/dist/artifact-linter.js

@@ -183,6 +183,42 @@ function getMarkdownTableRows(sectionBody) {
     }
     return rows;
 }
+const DIAGRAM_ARROW_PATTERN = /(?:<--?>|<?==?>|--?>|->>|=>|-\.->|→|⟶|↦)/u;
+const DIAGRAM_FAILURE_EDGE_PATTERN = /\b(fail(?:ed|ure)?|error|timeout|fallback|degrad(?:e|ed|ation)|retry|backoff|circuit|unavailable|recover(?:y)?|rescue|mitigat(?:e|ion)|rollback|exception|abort|dead[\s-]?letter|dlq)\b/iu;
+const DIAGRAM_GENERIC_NODE_PATTERN = /\b(service|component|module|system)\s*(?:[A-Z0-9])?\b/iu;
+function diagramEdgeLines(sectionBody) {
+    return sectionBody
+        .split(/\r?\n/)
+        .map((line) => line.trim())
+        .filter((line) => line.length > 0)
+        .filter((line) => !line.startsWith("```"))
+        .filter((line) => !line.startsWith("%%"))
+        .filter((line) => DIAGRAM_ARROW_PATTERN.test(line));
+}
+function hasFailureEdgeInDiagram(sectionBody) {
+    const lines = diagramEdgeLines(sectionBody);
+    for (const line of lines) {
+        if (DIAGRAM_ARROW_PATTERN.test(line) && DIAGRAM_FAILURE_EDGE_PATTERN.test(line)) {
+            return true;
+        }
+    }
+    return false;
+}
+function hasLabeledDiagramArrow(lines) {
+    return lines.some((line) => /\|[^|]+\|/u.test(line) || /:\s*[A-Za-z]/u.test(line));
+}
+function hasAsyncDiagramEdge(lines) {
+    return lines.some((line) => /-\.->|-->>|~~>|\basync\b/iu.test(line));
+}
+function hasSyncDiagramEdge(lines) {
+    return lines.some((line) => {
+        if (/\bsync\b/iu.test(line))
+            return true;
+        if (!/(-->|->|=>|→|⟶|↦)/u.test(line))
+            return false;
+        return !/-\.->|-->>|~~>/u.test(line);
+    });
+}
 const LEARNING_TYPE_SET = new Set(["rule", "pattern", "lesson", "compound"]);
 const LEARNING_CONFIDENCE_SET = new Set(["high", "medium", "low"]);
 const LEARNING_UNIVERSALITY_SET = new Set(["project", "personal", "universal"]);
@@ -541,20 +577,57 @@ function validateSectionBody(sectionBody, rule, sectionName) {
             };
         }
     }
-    const keywords = extractRequiredKeywords(rule);
-    if (keywords.length > 0) {
-        const bodyLower = sectionBody.toLowerCase();
-        const found = keywords.filter((kw) => bodyLower.includes(kw.toLowerCase()));
-        const threshold = Math.ceil(keywords.length * 0.5);
-        if (found.length < threshold) {
-            const missing = keywords.filter((kw) => !bodyLower.includes(kw.toLowerCase()));
+    const sectionNameNormalized = normalizeHeadingTitle(sectionName).toLowerCase();
+    if (sectionNameNormalized === "architecture diagram") {
+        const edgeLines = diagramEdgeLines(sectionBody);
+        if (edgeLines.length === 0) {
+            return {
+                ok: false,
+                details: "Architecture Diagram must include at least one directional edge line (for example `A -->|action| B`)."
+            };
+        }
+        if (!hasLabeledDiagramArrow(edgeLines)) {
+            return {
+                ok: false,
+                details: "Architecture Diagram must label each edge with an action/message (for example `A -->|sync: persist| B`)."
+            };
+        }
+        const genericLine = edgeLines.find((line) => DIAGRAM_GENERIC_NODE_PATTERN.test(line));
+        if (genericLine) {
             return {
                 ok: false,
-                details: `Rule expects keywords (${threshold}/${keywords.length} minimum): missing ${missing.join(", ")}.`
+                details: `Architecture Diagram uses a generic node label in edge "${genericLine}". Use concrete component names instead of placeholders like Service/Component.`
             };
         }
+        if (!hasAsyncDiagramEdge(edgeLines) || !hasSyncDiagramEdge(edgeLines)) {
+            return {
+                ok: false,
+                details: "Architecture Diagram must distinguish sync vs async edges (for example solid + dotted arrows, or `sync:` and `async:` labels)."
+            };
+        }
+        if (!hasFailureEdgeInDiagram(sectionBody)) {
+            return {
+                ok: false,
+                details: "Architecture Diagram must include at least one failure-edge arrow with a failure keyword (for example: timeout, error, fallback, degraded, retry)."
+            };
+        }
+    }
+    if (sectionNameNormalized !== "architecture diagram") {
+        const keywords = extractRequiredKeywords(rule);
+        if (keywords.length > 0) {
+            const bodyLower = sectionBody.toLowerCase();
+            const found = keywords.filter((kw) => bodyLower.includes(kw.toLowerCase()));
+            const threshold = Math.ceil(keywords.length * 0.5);
+            if (found.length < threshold) {
+                const missing = keywords.filter((kw) => !bodyLower.includes(kw.toLowerCase()));
+                return {
+                    ok: false,
+                    details: `Rule expects keywords (${threshold}/${keywords.length} minimum): missing ${missing.join(", ")}.`
+                };
+            }
+        }
     }
-    if (normalizeHeadingTitle(sectionName).toLowerCase() === "acceptance criteria" &&
+    if (sectionNameNormalized === "acceptance criteria" &&
         /observable[\s,]*measurable[\s,]+(and )?falsifiable/iu.test(rule)) {
         const rows = getMarkdownTableRows(sectionBody);
         for (const row of rows) {

package/dist/content/stages/design.js

@@ -25,7 +25,7 @@ export const DESIGN = {
         "Codebase Investigation — Before any design decision, read the actual code in the blast radius. List every file that will be touched, its current responsibilities, and existing patterns (error handling, naming, test style). Design must conform to discovered patterns, not impose new ones without justification.",
         "Step 0: Scope Challenge — what existing code solves sub-problems? Minimum change set? Complexity check: 8+ files or 2+ new services = complexity smell → flag for possible scope reduction.",
         "Search Before Building — For each technical choice (library, pattern, architecture), search for existing solutions. Label findings: Layer 1 (exact match), Layer 2 (partial match, needs adaptation), Layer 3 (inspiration only), EUREKA (unexpected perfect solution). Default to existing before custom.",
-        "Architecture Review — system design, component boundaries, data flow, scaling, security architecture. For each new codepath: one realistic production failure scenario. **Mandatory:** produce at least one architecture diagram (ASCII, Mermaid, or tool-generated) showing component boundaries and data flow direction. Apply the **Visual Communication rules** (see below) — an unlabeled or generic diagram is worse than no diagram, because it pretends to encode decisions it does not.",
+        "Architecture Review — system design, component boundaries, data flow, scaling, security architecture. For each new codepath: one realistic production failure scenario. **Mandatory:** produce at least one architecture diagram (ASCII, Mermaid, or tool-generated) showing component boundaries and data flow direction. Include at least one labeled failure edge, e.g. `API -->|timeout| FallbackCache -->|degraded response| User`. Apply the **Visual Communication rules** (see below) — an unlabeled or generic diagram is worse than no diagram, because it pretends to encode decisions it does not.",
         "Code Quality Review — code organization, DRY violations, error handling patterns, over/under-engineering assessment.",
         "Test Review — diagram every new flow, data path, error path. For each: what test type covers it? Does one exist? What is the gap? Produce test plan artifact.",
         "Performance Review — N+1 queries, memory concerns, caching opportunities, slow code paths. What breaks at 10x load? At 100x?",
@@ -196,7 +196,7 @@ export const DESIGN = {
         { section: "Codebase Investigation", required: true, validationRule: "Must list blast-radius files with current responsibilities and discovered patterns." },
         { section: "Search Before Building", required: true, validationRule: "For each technical choice: Layer 1 (exact match), Layer 2 (partial match), Layer 3 (inspiration), EUREKA labels with reuse-first default." },
         { section: "Architecture Boundaries", required: true, validationRule: "Must list component boundaries with ownership." },
-        { section: "Architecture Diagram", required: true, validationRule: "At least one diagram (ASCII, Mermaid, or image) showing component boundaries and data flow direction. Diagram must: (1) label every node with a concrete component name (no generic 'Service A/B'), (2) label every arrow with the action or message (no unlabeled arrows), (3) mark direction of data flow explicitly, (4) distinguish synchronous from asynchronous edges (e.g. solid vs dashed, or `sync:` / `async:` prefix), (5) show at least one failure edge or degraded-mode branch when the system has one." },
+        { section: "Architecture Diagram", required: true, validationRule: "At least one diagram (ASCII, Mermaid, or image) showing component boundaries and data flow direction. Diagram must: (1) label every node with a concrete component name (no generic 'Service A/B'), (2) label every arrow with the action or message (no unlabeled arrows), (3) mark direction of data flow explicitly, (4) distinguish synchronous from asynchronous edges (e.g. solid vs dashed, or `sync:` / `async:` prefix), (5) include at least one failure/degraded edge line that contains an arrow plus a failure keyword (`timeout`, `error`, `fallback`, `degraded`, `retry`, etc.)." },
         { section: "Data Flow", required: true, validationRule: "Must include happy path, nil input, empty input, upstream error paths." },
         { section: "Failure Mode Table", required: true, validationRule: "Each failure mode has: trigger, detection, mitigation, user impact." },
         { section: "Test Strategy", required: true, validationRule: "Must define unit/integration/e2e expectations with coverage targets." },

package/package.json

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