cclaw-cli 0.44.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.44.0
+version: 0.46.0
 flowVersion: 1.0.0
 harnesses:
   - codex

package/dist/artifact-linter.d.ts

@@ -1,4 +1,4 @@
-import type { FlowStage } from "./types.js";
+import { type FlowStage } from "./types.js";
 export interface LintFinding {
     section: string;
     required: boolean;
@@ -12,6 +12,36 @@ export interface LintResult {
     passed: boolean;
     findings: LintFinding[];
 }
+export declare function extractMarkdownSectionBody(markdown: string, section: string): string | null;
+export type LearningEntryType = "rule" | "pattern" | "lesson" | "compound";
+export type LearningConfidence = "high" | "medium" | "low";
+export type LearningUniversality = "project" | "personal" | "universal";
+export type LearningMaturity = "raw" | "lifted-to-rule" | "lifted-to-enforcement";
+export interface LearningSeedEntry {
+    type: LearningEntryType;
+    trigger: string;
+    action: string;
+    confidence: LearningConfidence;
+    domain?: string | null;
+    stage?: FlowStage | null;
+    origin_stage?: FlowStage | null;
+    origin_feature?: string | null;
+    frequency?: number;
+    universality?: LearningUniversality;
+    maturity?: LearningMaturity;
+    created?: string;
+    first_seen_ts?: string;
+    last_seen_ts?: string;
+    project?: string | null;
+}
+export interface LearningsParseResult {
+    ok: boolean;
+    none: boolean;
+    entries: LearningSeedEntry[];
+    errors: string[];
+    details: string;
+}
+export declare function parseLearningsSection(sectionBody: string): LearningsParseResult;
 export declare function lintArtifact(projectRoot: string, stage: FlowStage): Promise<LintResult>;
 export declare function lintAllArtifacts(projectRoot: string): Promise<LintResult[]>;
 export declare function validateReviewArmy(projectRoot: string): Promise<{

package/dist/artifact-linter.js

@@ -3,6 +3,7 @@ import path from "node:path";
 import { RUNTIME_ROOT } from "./constants.js";
 import { exists } from "./fs-utils.js";
 import { orderedStageSchemas, stageSchema } from "./content/stage-schema.js";
+import { FLOW_STAGES } from "./types.js";
 async function resolveArtifactPath(projectRoot, fileName) {
     const relPath = path.join(RUNTIME_ROOT, "artifacts", fileName);
     const absPath = path.join(projectRoot, relPath);
@@ -55,6 +56,9 @@ function sectionBodyByName(sections, section) {
     }
     return null;
 }
+export function extractMarkdownSectionBody(markdown, section) {
+    return sectionBodyByName(extractH2Sections(markdown), section);
+}
 function meaningfulLineCount(sectionBody) {
     return sectionBody
         .split(/\r?\n/)
@@ -179,6 +183,247 @@ 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"]);
+const LEARNING_MATURITY_SET = new Set(["raw", "lifted-to-rule", "lifted-to-enforcement"]);
+const FLOW_STAGE_SET = new Set(FLOW_STAGES);
+const LEARNING_ALLOWED_KEYS = new Set([
+    "type",
+    "trigger",
+    "action",
+    "confidence",
+    "domain",
+    "stage",
+    "origin_stage",
+    "origin_feature",
+    "frequency",
+    "universality",
+    "maturity",
+    "created",
+    "first_seen_ts",
+    "last_seen_ts",
+    "project"
+]);
+function isIsoUtcTimestamp(value) {
+    return /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}Z$/u.test(value);
+}
+function isNullableString(value) {
+    return value === null || typeof value === "string";
+}
+function isNullableStage(value) {
+    return value === null || (typeof value === "string" && FLOW_STAGE_SET.has(value));
+}
+function parseLearningSeedEntry(raw, index) {
+    if (!raw || typeof raw !== "object" || Array.isArray(raw)) {
+        return { ok: false, error: `Learnings bullet #${index} must be a JSON object.` };
+    }
+    const obj = raw;
+    for (const key of Object.keys(obj)) {
+        if (!LEARNING_ALLOWED_KEYS.has(key)) {
+            return {
+                ok: false,
+                error: `Learnings bullet #${index} includes unknown key "${key}" (allowed keys mirror knowledge JSONL fields).`
+            };
+        }
+    }
+    const type = typeof obj.type === "string" ? obj.type.toLowerCase() : "";
+    if (!LEARNING_TYPE_SET.has(type)) {
+        return {
+            ok: false,
+            error: `Learnings bullet #${index} must set type to one of: rule, pattern, lesson, compound.`
+        };
+    }
+    const trigger = typeof obj.trigger === "string" ? obj.trigger.trim() : "";
+    if (trigger.length === 0) {
+        return {
+            ok: false,
+            error: `Learnings bullet #${index} must include non-empty "trigger".`
+        };
+    }
+    const action = typeof obj.action === "string" ? obj.action.trim() : "";
+    if (action.length === 0) {
+        return {
+            ok: false,
+            error: `Learnings bullet #${index} must include non-empty "action".`
+        };
+    }
+    const confidence = typeof obj.confidence === "string" ? obj.confidence.toLowerCase() : "";
+    if (!LEARNING_CONFIDENCE_SET.has(confidence)) {
+        return {
+            ok: false,
+            error: `Learnings bullet #${index} must set confidence to high|medium|low.`
+        };
+    }
+    if (obj.domain !== undefined && !isNullableString(obj.domain)) {
+        return { ok: false, error: `Learnings bullet #${index} field "domain" must be string or null.` };
+    }
+    if (obj.stage !== undefined && !isNullableStage(obj.stage)) {
+        return {
+            ok: false,
+            error: `Learnings bullet #${index} field "stage" must be one of ${FLOW_STAGES.join(", ")} or null.`
+        };
+    }
+    if (obj.origin_stage !== undefined && !isNullableStage(obj.origin_stage)) {
+        return {
+            ok: false,
+            error: `Learnings bullet #${index} field "origin_stage" must be one of ${FLOW_STAGES.join(", ")} or null.`
+        };
+    }
+    if (obj.origin_feature !== undefined && !isNullableString(obj.origin_feature)) {
+        return { ok: false, error: `Learnings bullet #${index} field "origin_feature" must be string or null.` };
+    }
+    if (obj.project !== undefined && !isNullableString(obj.project)) {
+        return { ok: false, error: `Learnings bullet #${index} field "project" must be string or null.` };
+    }
+    if (obj.frequency !== undefined &&
+        (typeof obj.frequency !== "number" || !Number.isInteger(obj.frequency) || obj.frequency < 1)) {
+        return { ok: false, error: `Learnings bullet #${index} field "frequency" must be an integer >= 1.` };
+    }
+    if (obj.universality !== undefined &&
+        (typeof obj.universality !== "string" ||
+            !LEARNING_UNIVERSALITY_SET.has(obj.universality))) {
+        return {
+            ok: false,
+            error: `Learnings bullet #${index} field "universality" must be project|personal|universal.`
+        };
+    }
+    if (obj.maturity !== undefined &&
+        (typeof obj.maturity !== "string" || !LEARNING_MATURITY_SET.has(obj.maturity))) {
+        return {
+            ok: false,
+            error: `Learnings bullet #${index} field "maturity" must be raw|lifted-to-rule|lifted-to-enforcement.`
+        };
+    }
+    for (const timestampField of ["created", "first_seen_ts", "last_seen_ts"]) {
+        const value = obj[timestampField];
+        if (value === undefined)
+            continue;
+        if (typeof value !== "string" || !isIsoUtcTimestamp(value)) {
+            return {
+                ok: false,
+                error: `Learnings bullet #${index} field "${timestampField}" must be ISO UTC (YYYY-MM-DDTHH:MM:SSZ).`
+            };
+        }
+    }
+    return {
+        ok: true,
+        entry: {
+            ...obj,
+            type: type,
+            trigger,
+            action,
+            confidence: confidence
+        }
+    };
+}
+export function parseLearningsSection(sectionBody) {
+    const lines = sectionBody.split(/\r?\n/).map((line) => line.trim());
+    const nonEmpty = lines.filter((line) => line.length > 0);
+    const bullets = nonEmpty.filter((line) => /^-\s+\S+/u.test(line));
+    if (bullets.length === 0) {
+        return {
+            ok: false,
+            none: false,
+            entries: [],
+            errors: ["Learnings section must contain bullet entries."],
+            details: "Learnings section must contain bullet entries."
+        };
+    }
+    const nonBulletContent = nonEmpty.filter((line) => !/^-\s+\S+/u.test(line));
+    if (nonBulletContent.length > 0) {
+        return {
+            ok: false,
+            none: false,
+            entries: [],
+            errors: ["Learnings section must only contain bullet lines (one bullet per learning)."],
+            details: "Learnings section must only contain bullet lines (one bullet per learning)."
+        };
+    }
+    if (bullets.length === 1) {
+        const payload = bullets[0].replace(/^-\s+/u, "").trim();
+        if (/^none this stage\.?$/iu.test(payload)) {
+            return {
+                ok: true,
+                none: true,
+                entries: [],
+                errors: [],
+                details: "Learnings section explicitly marked as none."
+            };
+        }
+    }
+    const entries = [];
+    const errors = [];
+    for (let i = 0; i < bullets.length; i += 1) {
+        const payload = bullets[i].replace(/^-\s+/u, "").trim();
+        let parsed;
+        try {
+            parsed = JSON.parse(payload);
+        }
+        catch (err) {
+            errors.push(`Learnings bullet #${i + 1} must be valid JSON object or "None this stage.": ${err instanceof Error ? err.message : String(err)}`);
+            continue;
+        }
+        const parsedEntry = parseLearningSeedEntry(parsed, i + 1);
+        if (!parsedEntry.ok || !parsedEntry.entry) {
+            errors.push(parsedEntry.error ?? `Learnings bullet #${i + 1} is invalid.`);
+            continue;
+        }
+        entries.push(parsedEntry.entry);
+    }
+    if (errors.length > 0) {
+        return {
+            ok: false,
+            none: false,
+            entries: [],
+            errors,
+            details: errors.join(" | ")
+        };
+    }
+    return {
+        ok: true,
+        none: false,
+        entries,
+        errors: [],
+        details: `Parsed ${entries.length} learning bullet(s) as knowledge-compatible JSON entries.`
+    };
+}
 function lineContainsVagueAdjective(text) {
     const lower = text.toLowerCase();
     for (const adjective of VAGUE_AC_ADJECTIVES) {
@@ -332,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: `Rule expects keywords (${threshold}/${keywords.length} minimum): missing ${missing.join(", ")}.`
+                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: `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) {
@@ -453,6 +735,27 @@ export async function lintArtifact(projectRoot, stage) {
                 : validation.details
         });
     }
+    const learningsBody = sectionBodyByName(sections, "Learnings");
+    const requireLearnings = parsedFrontmatter.hasFrontmatter;
+    if (learningsBody === null) {
+        findings.push({
+            section: "Learnings",
+            required: requireLearnings,
+            rule: "Required for schema-v1 artifacts: include `## Learnings` with bullets of strict JSON objects compatible with knowledge.jsonl schema, or a single `- None this stage.` sentinel.",
+            found: false,
+            details: "No ## heading matching required section \"Learnings\"."
+        });
+    }
+    else {
+        const learnings = parseLearningsSection(learningsBody);
+        findings.push({
+            section: "Learnings",
+            required: requireLearnings,
+            rule: "`## Learnings` must contain either a single `- None this stage.` bullet or JSON bullets compatible with knowledge.jsonl fields (type/trigger/action/confidence required).",
+            found: learnings.ok,
+            details: learnings.details
+        });
+    }
     if (stage === "plan") {
         const strictPlanGuards = parsedFrontmatter.hasFrontmatter ||
             headingPresent(sections, "No-Placeholder Scan") ||

package/dist/content/learnings.js

@@ -49,6 +49,20 @@ Use the store to keep durable knowledge that should survive sessions:
 - **lesson**: non-obvious outcome from a failure or trade-off.
 - **compound**: post-ship insight about how to make the *next* feature faster (process accelerator, not domain rule).
 
+## Continuous capture (stage closeout path)
+
+Knowledge capture is now stage-native:
+- Each stage artifact has a \`## Learnings\` section.
+- Allowed payloads:
+  - \`- None this stage.\` (explicit no-op)
+  - JSON bullets with required keys \`type\`, \`trigger\`, \`action\`, \`confidence\` (optional keys may mirror the full JSONL schema fields).
+- During \`bash .cclaw/hooks/stage-complete.sh <stage>\`, cclaw:
+  1. validates \`## Learnings\`,
+  2. appends deduped entries to \`${KNOWLEDGE_PATH}\`,
+  3. writes a harvest marker into the artifact.
+
+\`/cc-learn\` remains the manual/query surface (search, backfill, curation).
+
 ## HARD-GATE
 
 Under \`/cc-learn\`, only modify \`${KNOWLEDGE_PATH}\`, \`${KNOWLEDGE_ARCHIVE_PATH}\`,
@@ -113,6 +127,7 @@ Rules:
 - Ask for required user-facing fields in order: \`type\`, \`trigger\`, \`action\`, \`confidence\`, \`domain\`, \`stage\`, \`universality\`, \`project\`.
 - \`confidence\` must be one of \`high\`, \`medium\`, \`low\`. Default to \`medium\` if the user declines to set it.
 - \`domain\`, \`stage\`, and \`project\` may be explicitly \`null\`.
+- Prefer stage-native \`## Learnings\` capture for new flow work; use \`add\` mainly for backfilling historical lessons or ad-hoc entries outside a stage closeout.
 - \`origin_stage\` defaults to \`stage\`; \`origin_feature\` defaults to active feature (or \`null\` if unknown).
 - \`frequency\` starts at \`1\`.
 - \`maturity\` starts at \`raw\`.
@@ -136,6 +151,11 @@ Manage the project knowledge store. One canonical file, strict JSONL:
 - \`${KNOWLEDGE_PATH}\` — append-only JSONL, one entry per line.
 - \`${KNOWLEDGE_ARCHIVE_PATH}\` — soft-archive target written only by curate.
 
+Stage-native pipeline:
+- During \`stage-complete.sh\`, cclaw harvests \`## Learnings\` from the current
+  stage artifact into \`${KNOWLEDGE_PATH}\` automatically.
+- Use \`/cc-learn\` for query, backfill, and curation workflows.
+
 ## HARD-GATE
 
 Do not edit source code from this command. Only operate on \`${KNOWLEDGE_PATH}\`,

package/dist/content/skills.js

@@ -223,9 +223,9 @@ function completionParametersBlock(schema) {
 - \`artifact\`: \`${RUNTIME_ROOT}/artifacts/${schema.artifactFile}\`
 - \`mandatory delegations\`: ${mandatory}
 - \`completion helper\`: \`bash .cclaw/hooks/stage-complete.sh ${schema.stage}\`
+- Fill \`## Learnings\` before closeout: either \`- None this stage.\` or JSON bullets with required keys \`type\`, \`trigger\`, \`action\`, \`confidence\` (knowledge-schema compatible).
 - Record mandatory delegation completion/waiver in \`${RUNTIME_ROOT}/state/delegation-log.json\` with rationale as needed.
 - Use the completion helper instead of raw \`flow-state.json\` edits (legacy direct edits trigger workflow-guard warnings or strict-mode blocks).
-
 Apply shared completion logic from:
 \`${COMPLETION_PROTOCOL_PATH}\`
 `;

package/dist/content/stage-common-guidance.js

@@ -58,8 +58,15 @@ Rollback / fallback: <if decision proves wrong>
 
 ## Self-improvement reminder
 
-Before closeout, capture 1-3 reusable insights in \`.cclaw/knowledge.jsonl\`
-whenever the stage produced non-obvious decisions, patterns, or lessons.
+Before closeout, fill the artifact \`## Learnings\` section (do not write
+\`.cclaw/knowledge.jsonl\` by hand):
+- \`- None this stage.\` when nothing reusable emerged.
+- Or 1-3 JSON bullets with required keys \`type\`, \`trigger\`, \`action\`,
+  \`confidence\` (optional fields may mirror knowledge.jsonl schema keys).
+During \`bash .cclaw/hooks/stage-complete.sh <stage>\`, cclaw validates those
+bullets, appends unique entries to \`.cclaw/knowledge.jsonl\`, and stamps a
+harvest marker in the artifact.
+
 Prefer \`type=rule|pattern|lesson\` (\`compound\` stays retro-focused).
 
 Track policy:
@@ -67,8 +74,8 @@ Track policy:
   recommended for other stages.
 - \`quick\`: recommended only.
 
-"No learning captured" is acceptable only with an explicit reason
-(for example, purely mechanical edits with no new decisions).
+\`- None this stage.\` is acceptable only when the stage produced no reusable
+insight (for example, purely mechanical edits with no new decisions).
 
 ## Progressive disclosure baseline
 

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/dist/content/templates.js

@@ -45,6 +45,9 @@ inputs_hash: sha256:pending
 ## Assumptions and Open Questions
 - **Assumptions:**
 - **Open questions (or "None"):**
+
+## Learnings
+- None this stage.
 `,
     "02-scope.md": `---
 stage: scope
@@ -148,6 +151,9 @@ inputs_hash: sha256:pending
 - Accepted scope:
 - Deferred:
 - Explicitly excluded:
+
+## Learnings
+- None this stage.
 `,
     "03-design.md": `---
 stage: design
@@ -241,6 +247,9 @@ inputs_hash: sha256:pending
 | Distribution & Delivery Review |  |  |
 
 **Decisions made:** 0 | **Unresolved:** 0
+
+## Learnings
+- None this stage.
 `,
     "04-spec.md": `---
 stage: spec
@@ -294,6 +303,9 @@ inputs_hash: sha256:pending
 ## Approval
 - Approved by:
 - Date:
+
+## Learnings
+- None this stage.
 `,
     "05-plan.md": `---
 stage: plan
@@ -370,6 +382,9 @@ Execution rule: complete and verify each batch before starting the next batch.
 ## WAIT_FOR_CONFIRM
 - Status: pending
 - Confirmed by:
+
+## Learnings
+- None this stage.
 `,
     "06-tdd.md": `---
 stage: tdd
@@ -434,6 +449,9 @@ inputs_hash: sha256:pending
 | Slice | Reproduction test | RED-without-fix evidence | GREEN-with-fix evidence | Revert-guard note |
 |---|---|---|---|---|
 | S-1 |  |  |  |  |
+
+## Learnings
+- None this stage.
 `,
     "07-review.md": `---
 stage: review
@@ -504,6 +522,9 @@ inputs_hash: sha256:pending
 
 ## Final Verdict
 - APPROVED | APPROVED_WITH_CONCERNS | BLOCKED
+
+## Learnings
+- None this stage.
 `,
     "07-review-army.json": `{
   "version": 1,
@@ -571,6 +592,9 @@ inputs_hash: sha256:pending
 - Run \`/cc-ops retro\` before archive.
 - Retro artifact path: \`.cclaw/artifacts/09-retro.md\`
 - Archive remains blocked until retro gate is complete.
+
+## Learnings
+- None this stage.
 `,
     "09-retro.md": `---
 stage: retro
@@ -611,6 +635,9 @@ inputs_hash: sha256:pending
 - RETRO_COMPLETE: yes
 - Completed at (UTC):
 - Notes:
+
+## Learnings
+- None this stage.
 `
 };
 export const RULEBOOK_MARKDOWN = `# Cclaw Rulebook

package/dist/internal/advance-stage.js

@@ -1,8 +1,13 @@
 import fs from "node:fs/promises";
+import path from "node:path";
+import { RUNTIME_ROOT } from "../constants.js";
 import { stageSchema } from "../content/stage-schema.js";
 import { appendDelegation, checkMandatoryDelegations } from "../delegation.js";
+import { readActiveFeature } from "../feature-system.js";
 import { verifyCompletedStagesGateClosure, verifyCurrentStageGateEvidence } from "../gate-evidence.js";
+import { extractMarkdownSectionBody, parseLearningsSection } from "../artifact-linter.js";
 import { isFlowTrack, nextStage } from "../flow-state.js";
+import { appendKnowledge } from "../knowledge-store.js";
 import { readFlowState, writeFlowState } from "../runs.js";
 import { FLOW_STAGES } from "../types.js";
 function unique(values) {
@@ -241,6 +246,89 @@ async function buildValidationReport(projectRoot, flowState) {
         }
     };
 }
+const LEARNINGS_HARVEST_MARKER_PREFIX = "<!-- cclaw:learnings-harvested:";
+function withLearningsHarvestMarker(artifactMarkdown, appendedEntries, skippedDuplicates) {
+    const suffix = artifactMarkdown.endsWith("\n") ? "" : "\n";
+    return `${artifactMarkdown}${suffix}${LEARNINGS_HARVEST_MARKER_PREFIX}${new Date().toISOString()} appended=${appendedEntries} skipped=${skippedDuplicates} -->\n`;
+}
+async function harvestStageLearnings(projectRoot, stage, artifactFile) {
+    const artifactPath = path.join(projectRoot, RUNTIME_ROOT, "artifacts", artifactFile);
+    let raw = "";
+    try {
+        raw = await fs.readFile(artifactPath, "utf8");
+    }
+    catch (err) {
+        return {
+            ok: false,
+            markerWritten: false,
+            parsedEntries: 0,
+            appendedEntries: 0,
+            skippedDuplicates: 0,
+            details: `Unable to read artifact for learnings harvest (${artifactPath}): ${err instanceof Error ? err.message : String(err)}`
+        };
+    }
+    if (raw.includes(LEARNINGS_HARVEST_MARKER_PREFIX)) {
+        return {
+            ok: true,
+            markerWritten: false,
+            parsedEntries: 0,
+            appendedEntries: 0,
+            skippedDuplicates: 0,
+            details: "Learnings already harvested for this artifact."
+        };
+    }
+    const learningsBody = extractMarkdownSectionBody(raw, "Learnings");
+    if (learningsBody === null) {
+        return {
+            ok: false,
+            markerWritten: false,
+            parsedEntries: 0,
+            appendedEntries: 0,
+            skippedDuplicates: 0,
+            details: 'Artifact is missing required "## Learnings" section.'
+        };
+    }
+    const parsed = parseLearningsSection(learningsBody);
+    if (!parsed.ok) {
+        return {
+            ok: false,
+            markerWritten: false,
+            parsedEntries: 0,
+            appendedEntries: 0,
+            skippedDuplicates: 0,
+            details: parsed.details
+        };
+    }
+    const activeFeature = await readActiveFeature(projectRoot).catch(() => null);
+    const appendResult = await appendKnowledge(projectRoot, parsed.entries, {
+        stage,
+        originStage: stage,
+        originFeature: activeFeature,
+        project: path.basename(projectRoot)
+    });
+    if (appendResult.invalid > 0) {
+        return {
+            ok: false,
+            markerWritten: false,
+            parsedEntries: parsed.entries.length,
+            appendedEntries: appendResult.appended,
+            skippedDuplicates: appendResult.skippedDuplicates,
+            details: `Learnings append failed schema checks: ${appendResult.errors.join(" | ")}`
+        };
+    }
+    const withMarker = withLearningsHarvestMarker(raw, appendResult.appended, appendResult.skippedDuplicates);
+    await fs.writeFile(artifactPath, withMarker, "utf8");
+    return {
+        ok: true,
+        markerWritten: true,
+        parsedEntries: parsed.entries.length,
+        appendedEntries: appendResult.appended,
+        skippedDuplicates: appendResult.skippedDuplicates,
+        details: parsed.none
+            ? "Learnings section marked none; harvest marker recorded."
+            : `Harvested ${appendResult.appended} learning entr${appendResult.appended === 1 ? "y" : "ies"} (${appendResult.skippedDuplicates} duplicate skipped).`
+    };
+}
 async function runAdvanceStage(projectRoot, args, io) {
     const flowState = await readFlowState(projectRoot);
     if (flowState.currentStage !== args.stage) {
@@ -335,6 +423,11 @@ async function runAdvanceStage(projectRoot, args, io) {
         }
         return 1;
     }
+    const learningsHarvest = await harvestStageLearnings(projectRoot, args.stage, schema.artifactFile);
+    if (!learningsHarvest.ok) {
+        io.stderr.write(`cclaw internal advance-stage: learnings harvest failed for "${schema.artifactFile}". ${learningsHarvest.details}\n`);
+        return 1;
+    }
     const successor = nextStage(args.stage, flowState.track);
     const completedStages = flowState.completedStages.includes(args.stage)
         ? [...flowState.completedStages]
@@ -352,7 +445,14 @@ async function runAdvanceStage(projectRoot, args, io) {
             stage: args.stage,
             nextStage: successor,
             currentStage: finalState.currentStage,
-            completedStages: finalState.completedStages
+            completedStages: finalState.completedStages,
+            learnings: {
+                parsed: learningsHarvest.parsedEntries,
+                appended: learningsHarvest.appendedEntries,
+                skippedDuplicates: learningsHarvest.skippedDuplicates,
+                markerWritten: learningsHarvest.markerWritten,
+                details: learningsHarvest.details
+            }
         }, null, 2)}\n`);
     }
     return 0;

package/dist/knowledge-store.d.ts

@@ -0,0 +1,59 @@
+import { type FlowStage } from "./types.js";
+export type KnowledgeEntryType = "rule" | "pattern" | "lesson" | "compound";
+export type KnowledgeEntryConfidence = "high" | "medium" | "low";
+export type KnowledgeEntryUniversality = "project" | "personal" | "universal";
+export type KnowledgeEntryMaturity = "raw" | "lifted-to-rule" | "lifted-to-enforcement";
+export interface KnowledgeEntry {
+    type: KnowledgeEntryType;
+    trigger: string;
+    action: string;
+    confidence: KnowledgeEntryConfidence;
+    domain: string | null;
+    stage: FlowStage | null;
+    origin_stage: FlowStage | null;
+    origin_feature: string | null;
+    frequency: number;
+    universality: KnowledgeEntryUniversality;
+    maturity: KnowledgeEntryMaturity;
+    created: string;
+    first_seen_ts: string;
+    last_seen_ts: string;
+    project: string | null;
+}
+export interface KnowledgeSeedEntry {
+    type: KnowledgeEntryType;
+    trigger: string;
+    action: string;
+    confidence: KnowledgeEntryConfidence;
+    domain?: string | null;
+    stage?: FlowStage | null;
+    origin_stage?: FlowStage | null;
+    origin_feature?: string | null;
+    frequency?: number;
+    universality?: KnowledgeEntryUniversality;
+    maturity?: KnowledgeEntryMaturity;
+    created?: string;
+    first_seen_ts?: string;
+    last_seen_ts?: string;
+    project?: string | null;
+}
+export interface AppendKnowledgeDefaults {
+    stage?: FlowStage | null;
+    originStage?: FlowStage | null;
+    originFeature?: string | null;
+    project?: string | null;
+    nowIso?: string;
+}
+export interface AppendKnowledgeResult {
+    appended: number;
+    skippedDuplicates: number;
+    invalid: number;
+    errors: string[];
+    appendedEntries: KnowledgeEntry[];
+}
+export declare function validateKnowledgeEntry(entry: unknown): {
+    ok: boolean;
+    errors: string[];
+};
+export declare function materializeKnowledgeEntry(seed: KnowledgeSeedEntry, defaults?: AppendKnowledgeDefaults): KnowledgeEntry;
+export declare function appendKnowledge(projectRoot: string, seeds: KnowledgeSeedEntry[], defaults?: AppendKnowledgeDefaults): Promise<AppendKnowledgeResult>;

package/dist/knowledge-store.js

@@ -0,0 +1,220 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { RUNTIME_ROOT } from "./constants.js";
+import { withDirectoryLock } from "./fs-utils.js";
+import { FLOW_STAGES } from "./types.js";
+const KNOWLEDGE_TYPE_SET = new Set(["rule", "pattern", "lesson", "compound"]);
+const KNOWLEDGE_CONFIDENCE_SET = new Set(["high", "medium", "low"]);
+const KNOWLEDGE_UNIVERSALITY_SET = new Set(["project", "personal", "universal"]);
+const KNOWLEDGE_MATURITY_SET = new Set(["raw", "lifted-to-rule", "lifted-to-enforcement"]);
+const FLOW_STAGE_SET = new Set(FLOW_STAGES);
+const KNOWLEDGE_REQUIRED_KEYS = [
+    "type",
+    "trigger",
+    "action",
+    "confidence",
+    "domain",
+    "stage",
+    "origin_stage",
+    "origin_feature",
+    "frequency",
+    "universality",
+    "maturity",
+    "created",
+    "first_seen_ts",
+    "last_seen_ts",
+    "project"
+];
+const KNOWLEDGE_ALLOWED_KEYS = new Set(KNOWLEDGE_REQUIRED_KEYS);
+function knowledgePath(projectRoot) {
+    return path.join(projectRoot, RUNTIME_ROOT, "knowledge.jsonl");
+}
+function knowledgeLockPath(projectRoot) {
+    return path.join(projectRoot, RUNTIME_ROOT, "state", ".knowledge.lock");
+}
+function normalizeUtcIso(iso) {
+    return iso.replace(/\.\d{3}Z$/u, "Z");
+}
+function nowUtcIso() {
+    return normalizeUtcIso(new Date().toISOString());
+}
+function normalizeText(value) {
+    return value.trim().replace(/\s+/gu, " ").toLowerCase();
+}
+function dedupeKey(entry) {
+    return [
+        entry.type,
+        normalizeText(entry.trigger),
+        normalizeText(entry.action),
+        entry.domain === null ? "null" : normalizeText(entry.domain),
+        entry.stage ?? "null",
+        entry.origin_stage ?? "null",
+        entry.origin_feature === null ? "null" : normalizeText(entry.origin_feature),
+        entry.universality,
+        entry.project === null ? "null" : normalizeText(entry.project)
+    ].join("|");
+}
+function isIsoUtcTimestamp(value) {
+    return /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}Z$/u.test(value);
+}
+function isNullableString(value) {
+    return value === null || typeof value === "string";
+}
+function isNullableStage(value) {
+    return value === null || (typeof value === "string" && FLOW_STAGE_SET.has(value));
+}
+export function validateKnowledgeEntry(entry) {
+    const errors = [];
+    if (!entry || typeof entry !== "object" || Array.isArray(entry)) {
+        return { ok: false, errors: ["Knowledge entry must be a JSON object."] };
+    }
+    const obj = entry;
+    for (const key of Object.keys(obj)) {
+        if (!KNOWLEDGE_ALLOWED_KEYS.has(key)) {
+            errors.push(`Unknown key "${key}" in knowledge entry.`);
+        }
+    }
+    for (const key of KNOWLEDGE_REQUIRED_KEYS) {
+        if (!Object.prototype.hasOwnProperty.call(obj, key)) {
+            errors.push(`Missing required key "${key}".`);
+        }
+    }
+    if (!KNOWLEDGE_TYPE_SET.has(obj.type)) {
+        errors.push("type must be one of: rule, pattern, lesson, compound.");
+    }
+    if (typeof obj.trigger !== "string" || obj.trigger.trim().length === 0) {
+        errors.push("trigger must be a non-empty string.");
+    }
+    if (typeof obj.action !== "string" || obj.action.trim().length === 0) {
+        errors.push("action must be a non-empty string.");
+    }
+    if (!KNOWLEDGE_CONFIDENCE_SET.has(obj.confidence)) {
+        errors.push("confidence must be one of: high, medium, low.");
+    }
+    if (!isNullableString(obj.domain)) {
+        errors.push("domain must be string or null.");
+    }
+    if (!isNullableStage(obj.stage)) {
+        errors.push(`stage must be one of ${FLOW_STAGES.join(", ")} or null.`);
+    }
+    if (!isNullableStage(obj.origin_stage)) {
+        errors.push(`origin_stage must be one of ${FLOW_STAGES.join(", ")} or null.`);
+    }
+    if (!isNullableString(obj.origin_feature)) {
+        errors.push("origin_feature must be string or null.");
+    }
+    if (typeof obj.frequency !== "number" ||
+        !Number.isInteger(obj.frequency) ||
+        obj.frequency < 1) {
+        errors.push("frequency must be an integer >= 1.");
+    }
+    if (!KNOWLEDGE_UNIVERSALITY_SET.has(obj.universality)) {
+        errors.push("universality must be one of: project, personal, universal.");
+    }
+    if (!KNOWLEDGE_MATURITY_SET.has(obj.maturity)) {
+        errors.push("maturity must be one of: raw, lifted-to-rule, lifted-to-enforcement.");
+    }
+    for (const timestampField of ["created", "first_seen_ts", "last_seen_ts"]) {
+        const value = obj[timestampField];
+        if (typeof value !== "string" || !isIsoUtcTimestamp(value)) {
+            errors.push(`${timestampField} must be ISO UTC (YYYY-MM-DDTHH:MM:SSZ).`);
+        }
+    }
+    if (!isNullableString(obj.project)) {
+        errors.push("project must be string or null.");
+    }
+    return { ok: errors.length === 0, errors };
+}
+export function materializeKnowledgeEntry(seed, defaults = {}) {
+    const now = normalizeUtcIso(defaults.nowIso ?? nowUtcIso());
+    const stage = seed.stage ?? defaults.stage ?? null;
+    const originStage = seed.origin_stage ?? defaults.originStage ?? stage ?? null;
+    return {
+        type: seed.type,
+        trigger: seed.trigger.trim(),
+        action: seed.action.trim(),
+        confidence: seed.confidence,
+        domain: seed.domain ?? null,
+        stage,
+        origin_stage: originStage,
+        origin_feature: seed.origin_feature ?? defaults.originFeature ?? null,
+        frequency: seed.frequency ?? 1,
+        universality: seed.universality ?? "project",
+        maturity: seed.maturity ?? "raw",
+        created: normalizeUtcIso(seed.created ?? now),
+        first_seen_ts: normalizeUtcIso(seed.first_seen_ts ?? now),
+        last_seen_ts: normalizeUtcIso(seed.last_seen_ts ?? now),
+        project: seed.project ?? defaults.project ?? null
+    };
+}
+async function readExistingKnowledgeKeys(filePath) {
+    const keys = new Set();
+    try {
+        const raw = await fs.readFile(filePath, "utf8");
+        const lines = raw.split(/\r?\n/u).map((line) => line.trim()).filter((line) => line.length > 0);
+        for (const line of lines) {
+            try {
+                const parsed = JSON.parse(line);
+                const validated = validateKnowledgeEntry(parsed);
+                if (!validated.ok)
+                    continue;
+                const entry = parsed;
+                keys.add(dedupeKey(entry));
+            }
+            catch {
+                // Ignore malformed historical lines for dedupe indexing.
+            }
+        }
+    }
+    catch {
+        // Missing file is fine — treat as empty store.
+    }
+    return keys;
+}
+export async function appendKnowledge(projectRoot, seeds, defaults = {}) {
+    if (seeds.length === 0) {
+        return { appended: 0, skippedDuplicates: 0, invalid: 0, errors: [], appendedEntries: [] };
+    }
+    const filePath = knowledgePath(projectRoot);
+    const errors = [];
+    const materialized = [];
+    for (let i = 0; i < seeds.length; i += 1) {
+        const seed = seeds[i];
+        const entry = materializeKnowledgeEntry(seed, defaults);
+        const validated = validateKnowledgeEntry(entry);
+        if (!validated.ok) {
+            errors.push(`entry #${i + 1}: ${validated.errors.join(" ")}`);
+            continue;
+        }
+        materialized.push(entry);
+    }
+    let skippedDuplicates = 0;
+    const appendedEntries = [];
+    await withDirectoryLock(knowledgeLockPath(projectRoot), async () => {
+        await fs.mkdir(path.dirname(filePath), { recursive: true });
+        const existingKeys = await readExistingKnowledgeKeys(filePath);
+        const batchKeys = new Set();
+        const linesToAppend = [];
+        for (const entry of materialized) {
+            const key = dedupeKey(entry);
+            if (existingKeys.has(key) || batchKeys.has(key)) {
+                skippedDuplicates += 1;
+                continue;
+            }
+            batchKeys.add(key);
+            existingKeys.add(key);
+            appendedEntries.push(entry);
+            linesToAppend.push(JSON.stringify(entry));
+        }
+        if (linesToAppend.length > 0) {
+            await fs.appendFile(filePath, `${linesToAppend.join("\n")}\n`, "utf8");
+        }
+    });
+    return {
+        appended: appendedEntries.length,
+        skippedDuplicates,
+        invalid: errors.length,
+        errors,
+        appendedEntries
+    };
+}

package/package.json

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