cclaw-cli 0.45.0 → 0.46.1

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.d.ts

@@ -17,6 +17,7 @@ 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 type LearningSource = "stage" | "retro" | "compound" | "ideate" | "manual";
 export interface LearningSeedEntry {
     type: LearningEntryType;
     trigger: string;
@@ -33,6 +34,7 @@ export interface LearningSeedEntry {
     first_seen_ts?: string;
     last_seen_ts?: string;
     project?: string | null;
+    source?: LearningSource | null;
 }
 export interface LearningsParseResult {
     ok: boolean;
@@ -43,7 +45,6 @@ export interface LearningsParseResult {
 }
 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<{
     valid: boolean;
     errors: string[];

package/dist/artifact-linter.js

@@ -2,7 +2,7 @@ import fs from "node:fs/promises";
 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 { 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);
@@ -183,10 +183,53 @@ 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 LEARNING_SOURCE_SET = new Set([
+    "stage",
+    "retro",
+    "compound",
+    "ideate",
+    "manual"
+]);
 const FLOW_STAGE_SET = new Set(FLOW_STAGES);
 const LEARNING_ALLOWED_KEYS = new Set([
     "type",
@@ -203,7 +246,8 @@ const LEARNING_ALLOWED_KEYS = new Set([
     "created",
     "first_seen_ts",
     "last_seen_ts",
-    "project"
+    "project",
+    "source"
 ]);
 function isIsoUtcTimestamp(value) {
     return /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}Z$/u.test(value);
@@ -276,6 +320,14 @@ function parseLearningSeedEntry(raw, index) {
     if (obj.project !== undefined && !isNullableString(obj.project)) {
         return { ok: false, error: `Learnings bullet #${index} field "project" must be string or null.` };
     }
+    if (obj.source !== undefined &&
+        obj.source !== null &&
+        (typeof obj.source !== "string" || !LEARNING_SOURCE_SET.has(obj.source))) {
+        return {
+            ok: false,
+            error: `Learnings bullet #${index} field "source" must be stage|retro|compound|ideate|manual 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.` };
@@ -541,20 +593,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: `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: `Rule expects keywords (${threshold}/${keywords.length} minimum): missing ${missing.join(", ")}.`
+                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 (normalizeHeadingTitle(sectionName).toLowerCase() === "acceptance criteria" &&
+    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 (sectionNameNormalized === "acceptance criteria" &&
         /observable[\s,]*measurable[\s,]+(and )?falsifiable/iu.test(rule)) {
         const rows = getMarkdownTableRows(sectionBody);
         for (const row of rows) {
@@ -749,13 +838,6 @@ export async function lintArtifact(projectRoot, stage) {
     const passed = findings.every((f) => !f.required || f.found);
     return { stage, file: relFile, passed, findings };
 }
-export async function lintAllArtifacts(projectRoot) {
-    const out = [];
-    for (const schema of orderedStageSchemas()) {
-        out.push(await lintArtifact(projectRoot, schema.stage));
-    }
-    return out;
-}
 function isNonEmptyString(v) {
     return typeof v === "string" && v.length > 0;
 }

package/dist/content/harnesses-doc.js

@@ -18,7 +18,7 @@ function tierDescription(tier) {
         return "full native automation";
     if (tier === "tier2")
         return "partial automation with waivers";
-    return "manual fallback only";
+    return "compatibility shim";
 }
 export function harnessIntegrationDocMarkdown() {
     const harnesses = Object.keys(HARNESS_ADAPTERS);
@@ -67,7 +67,6 @@ ${hookRows}
 
 - \`tier1\`: full native delegation + structured asks + full hook surface.
 - \`tier2\`: usable flow with capability gaps; mandatory delegation can require waivers.
-- \`tier3\`: manual-only fallback; no native automation guarantees.
 - Codex-specific ceiling: \`PreToolUse\` can only intercept \`Bash\`. Direct
   \`Write\`/\`Edit\` to \`.cclaw/state/flow-state.json\` cannot be hard-blocked
   at hook level, so the canonical path is
@@ -82,7 +81,6 @@ All harnesses receive the same utility commands:
 - \`/cc-next\` - stage progression
 - \`/cc-ideate\` - discovery mode for ranked repo-improvement backlog
 - \`/cc-view\` - read-only router for status/tree/diff
-- \`/cc-learn\` - knowledge capture/lookup
 - \`/cc-ops\` - operations router for feature/tdd-log/retro/compound/archive/rewind
 
 Read-only subcommands:

package/dist/content/ideate-command.d.ts

@@ -1,9 +1,2 @@
 export declare function ideateCommandContract(): string;
 export declare function ideateCommandSkillMarkdown(): string;
-/**
- * Exposed for tests and docs that need to mention the artifact convention
- * without hard-coding the path string in two places.
- */
-export declare const IDEATION_ARTIFACT_PATH_PATTERN = ".cclaw/artifacts/ideation-<YYYY-MM-DD-slug>.md";
-export declare const IDEATION_ARTIFACT_GLOB_PATTERN = ".cclaw/artifacts/ideation-*.md";
-export declare const IDEATION_RESUME_WINDOW = 30;

package/dist/content/ideate-command.js

@@ -208,10 +208,3 @@ lettered list with the same four labels. Do not invent extra options.
   option in the handoff prompt must reference a concrete command.
 `;
 }
-/**
- * Exposed for tests and docs that need to mention the artifact convention
- * without hard-coding the path string in two places.
- */
-export const IDEATION_ARTIFACT_PATH_PATTERN = IDEATION_ARTIFACT_PATTERN;
-export const IDEATION_ARTIFACT_GLOB_PATTERN = IDEATION_ARTIFACT_GLOB;
-export const IDEATION_RESUME_WINDOW = IDEATION_RESUME_WINDOW_DAYS;

package/dist/content/learnings.d.ts

@@ -1,6 +1,7 @@
 /**
- * Canonical JSONL field order (matches the reference spec).
- * Exported for tests and any programmatic writer that wants the exact shape.
+ * Canonical required JSONL field order (matches strict validator keys).
+ * Optional keys (for now: `source`) may be appended after these required fields.
+ * Exported for tests and any programmatic writer that wants a stable base shape.
  */
 export declare const KNOWLEDGE_JSONL_FIELDS: readonly ["type", "trigger", "action", "confidence", "domain", "stage", "origin_stage", "origin_feature", "frequency", "universality", "maturity", "created", "first_seen_ts", "last_seen_ts", "project"];
 export declare function learnSkillMarkdown(): string;

package/dist/content/learnings.js

@@ -10,8 +10,9 @@ const KNOWLEDGE_ARCHIVE_PATH = ".cclaw/knowledge.archive.jsonl";
 const LEARN_SKILL_NAME = "learnings";
 const LEARN_SKILL_DESCRIPTION = "Project-scoped knowledge store: append and query rule/pattern/lesson/compound entries in the canonical JSONL file at .cclaw/knowledge.jsonl. Strict schema, append-only, machine-queryable.";
 /**
- * Canonical JSONL field order (matches the reference spec).
- * Exported for tests and any programmatic writer that wants the exact shape.
+ * Canonical required JSONL field order (matches strict validator keys).
+ * Optional keys (for now: `source`) may be appended after these required fields.
+ * Exported for tests and any programmatic writer that wants a stable base shape.
  */
 export const KNOWLEDGE_JSONL_FIELDS = [
     "type",
@@ -71,8 +72,9 @@ Do not invent alternate stores (no markdown mirror, no SQLite, no per-stage file
 
 ## Entry format — strict JSONL schema
 
-Exactly one JSON object per line. Fields must appear in the order:
+Exactly one JSON object per line. Required fields must appear in the order:
 \`type, trigger, action, confidence, domain, stage, origin_stage, origin_feature, frequency, universality, maturity, created, first_seen_ts, last_seen_ts, project\`.
+Optional field \`source\` may be appended after \`project\`.
 
 \`\`\`json
 {"type":"pattern","trigger":"when reviewing external payloads","action":"parse through zod before touching service layer","confidence":"high","domain":"api","stage":"review","origin_stage":"review","origin_feature":"payload-hardening","frequency":1,"universality":"project","maturity":"raw","created":"2026-04-14T12:00:00Z","first_seen_ts":"2026-04-14T12:00:00Z","last_seen_ts":"2026-04-14T12:00:00Z","project":"cclaw"}
@@ -95,9 +97,10 @@ Exactly one JSON object per line. Fields must appear in the order:
 | \`first_seen_ts\` | ISO 8601 UTC string | yes | First observed timestamp (usually equals \`created\`). |
 | \`last_seen_ts\` | ISO 8601 UTC string | yes | Last re-confirmed timestamp. |
 | \`project\` | string \\| null | yes | Repo or scope name. Use \`null\` when the entry crosses projects. |
+| \`source\` | \`"stage" \\| "retro" \\| "compound" \\| "ideate" \\| "manual" \\| null\` | no | Origin channel for the entry when known. |
 
 Rules:
-- No other fields. Extra keys are forbidden and MUST be rejected by any writer.
+- No other fields beyond the table above. Extra keys are forbidden and MUST be rejected by any writer.
 - Every required-null field must be emitted explicitly as \`null\` (not omitted). This keeps the file grep-friendly.
 - Append-only: never rewrite or delete a historical line. Corrections are new
   entries whose \`trigger\` clearly supersedes the earlier one.
@@ -167,7 +170,7 @@ Do not edit source code from this command. Only operate on \`${KNOWLEDGE_PATH}\`
 |---|---|---|
 | (default) | — | Show recent knowledge entries (tail of JSONL, pretty-printed). |
 | \`search\` | \`<query>\` | Stream-filter the JSONL for matching \`trigger\`, \`action\`, \`domain\`, \`project\`. |
-| \`add\` | — | Append one JSON line (\`rule\` / \`pattern\` / \`lesson\` / \`compound\`) with the strict 15-field schema. |
+| \`add\` | — | Append one JSON line (\`rule\` / \`pattern\` / \`lesson\` / \`compound\`) with the strict JSONL schema (15 required fields + optional \`source\`). |
 | \`curate\` | — | Hand off to the **knowledge-curation** skill: read-only audit + soft-archive plan when the file exceeds the curation threshold. |
 `;
 }

package/dist/content/retro-command.js

@@ -58,7 +58,7 @@ in the structured ask; there is no \`--skip\` flag.
    - \`skip\` — record \`retroSkipped: true\` + one-line reason, no compound entry required.
 6. On **accept**:
    - append >=1 strict-schema JSONL line to \`${knowledgePath()}\` with
-     \`type: "compound"\` and \`stage: "retro"\`,
+     \`type: "compound"\`, \`source: "retro"\`, and \`stage: null\`,
    - set \`retro.required = true\`, \`retro.completedAt = <ISO>\`,
      \`retro.compoundEntries = <count>\`,
    - set \`closeout.retroAcceptedAt = <ISO>\`,
@@ -121,7 +121,7 @@ Do not silently skip. Do not finalize without updating \`flow-state.json\`.
    > - **skip** — no retro this run (requires one-line reason).
 
 4. Apply the state transition for the chosen option:
-   - \`accept\` → append \`{ "type": "compound", "stage": "retro", ... }\` line
+   - \`accept\` → append \`{ "type": "compound", "source": "retro", "stage": null, ... }\` line
      to \`${knowledgePath()}\`; set \`retro.completedAt\`, \`retro.compoundEntries\`,
      \`closeout.retroAcceptedAt\`; set \`closeout.shipSubstate = "compound_review"\`.
    - \`edit\` → leave \`shipSubstate = "retro_review"\`; announce resume path.

package/dist/content/stages/brainstorm.js

@@ -54,8 +54,6 @@ export const BRAINSTORM = {
         "Handoff to scope only after approval is explicit."
     ],
     requiredGates: [
-        { id: "brainstorm_context_explored", description: "Project context (files, docs, existing patterns) was checked before asking questions." },
-        { id: "brainstorm_idea_understood", description: "Agent and user share the same understanding of the problem, constraints, and success criteria." },
         { id: "brainstorm_approaches_compared", description: "2-3 architecturally distinct approaches were compared with real trade-offs and a recommendation." },
         { id: "brainstorm_direction_approved", description: "User approved a concrete direction and what exactly was approved is stated." },
         { id: "brainstorm_artifact_reviewed", description: "User reviewed the written brainstorm artifact and confirmed readiness." }
@@ -123,10 +121,10 @@ export const BRAINSTORM = {
     artifactValidation: [
         { section: "Context", required: true, validationRule: "Must reference project state and relevant existing code or patterns." },
         { section: "Problem", required: true, validationRule: "Must define what we're solving, success criteria, and constraints." },
-        { section: "Clarifying Questions", required: true, validationRule: "Must capture question, answer, and decision impact for each clarifying question." },
+        { section: "Clarifying Questions", required: false, validationRule: "Must capture question, answer, and decision impact for each clarifying question." },
         { section: "Approaches", required: true, validationRule: "Must compare 2-3 architecturally distinct options with real trade-offs and recommendation." },
         { section: "Selected Direction", required: true, validationRule: "Must include the selected approach, rationale, and explicit approval marker." },
-        { section: "Design", required: true, validationRule: "Must cover architecture, key components, and data flow scaled to complexity." },
-        { section: "Assumptions and Open Questions", required: true, validationRule: "Must capture unresolved assumptions/open questions, or explicitly state none." }
+        { section: "Design", required: false, validationRule: "Must cover architecture, key components, and data flow scaled to complexity." },
+        { section: "Assumptions and Open Questions", required: false, validationRule: "Must capture unresolved assumptions/open questions, or explicitly state none." }
     ]
 };

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?",
@@ -62,8 +62,6 @@ export const DESIGN = {
         "Write design lock artifact for downstream spec/plan."
     ],
     requiredGates: [
-        { id: "design_codebase_investigated", description: "Blast-radius files read and current patterns catalogued." },
-        { id: "design_scope_challenge_done", description: "Step 0 scope challenge completed with existing-code mapping." },
         { id: "design_architecture_locked", description: "Architecture boundaries are explicit and approved." },
         { id: "design_data_flow_mapped", description: "Data/state flow includes edge-case paths." },
         { id: "design_failure_modes_mapped", description: "Failure modes and mitigations are documented." },
@@ -193,16 +191,16 @@ export const DESIGN = {
         traceabilityRule: "Every architecture decision must trace to a scope boundary. Every downstream spec requirement must trace to a design decision."
     },
     artifactValidation: [
-        { 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: "Codebase Investigation", required: false, validationRule: "Must list blast-radius files with current responsibilities and discovered patterns." },
+        { section: "Search Before Building", required: false, 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: "Data Flow", required: true, validationRule: "Must include happy path, nil input, empty input, upstream error paths." },
+        { 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: false, 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." },
-        { section: "Performance Budget", required: true, validationRule: "For each critical path: metric name, target threshold, and measurement method." },
-        { section: "What Already Exists", required: true, validationRule: "For each sub-problem: existing code/library found (Layer 1-3/EUREKA label), reuse decision, and adaptation needed." },
-        { section: "NOT in scope", required: true, validationRule: "Work considered and explicitly deferred with one-line rationale." },
+        { section: "Test Strategy", required: false, validationRule: "Must define unit/integration/e2e expectations with coverage targets." },
+        { section: "Performance Budget", required: false, validationRule: "For each critical path: metric name, target threshold, and measurement method." },
+        { section: "What Already Exists", required: false, validationRule: "For each sub-problem: existing code/library found (Layer 1-3/EUREKA label), reuse decision, and adaptation needed." },
+        { section: "NOT in scope", required: false, validationRule: "Work considered and explicitly deferred with one-line rationale." },
         { section: "Parallelization Strategy", required: false, validationRule: "If multi-module: dependency table, parallel lanes, conflict flags." },
         { section: "Unresolved Decisions", required: false, validationRule: "If any: what info is missing, who provides it, default if unanswered." },
         { section: "Interface Contracts", required: false, validationRule: "If present: for each module boundary list produces (outputs) and consumes (inputs) with data types." },

package/dist/content/stages/plan.js

@@ -51,9 +51,7 @@ export const PLAN = {
     ],
     requiredGates: [
         { id: "plan_tasks_sliced_2_5_min", description: "Tasks are small, executable slices." },
-        { id: "plan_dependency_graph_written", description: "Dependency graph and order are explicit." },
         { id: "plan_dependency_batches_defined", description: "Tasks are grouped into executable batches with gate checks." },
-        { id: "plan_verification_steps_defined", description: "Each task has verification guidance." },
         { id: "plan_acceptance_mapped", description: "Each task maps to a spec acceptance criterion." },
         { id: "plan_wait_for_confirm", description: "Execution blocked until explicit user confirmation." }
     ],
@@ -143,7 +141,7 @@ export const PLAN = {
         traceabilityRule: "Every task must trace to a spec acceptance criterion. Every locked scope decision (D-XX) must trace to at least one plan task or explicit defer rationale. Every downstream RED test must trace to a plan task."
     },
     artifactValidation: [
-        { section: "Dependency Graph", required: true, validationRule: "Ordering and parallel opportunities explicit. No circular dependencies." },
+        { section: "Dependency Graph", required: false, validationRule: "Ordering and parallel opportunities explicit. No circular dependencies." },
         { section: "Dependency Batches", required: true, validationRule: "Every task belongs to a batch. Each batch has an exit gate and dependency statement." },
         { section: "Task List", required: true, validationRule: "Each task row includes ID, description, acceptance criterion, verification command, and effort estimate (S/M/L). Every task must also carry a minutes estimate within the 2-5 minute budget. When the sliceReview feature is enabled in the cclaw config, each task row additionally declares touchCount, touchPaths, and an optional highRisk flag so the TDD stage can decide whether a Per-Slice Review pass is required." },
         { section: "Acceptance Mapping", required: true, validationRule: "Every spec criterion is covered by at least one task." },

package/dist/content/stages/review.js

@@ -56,15 +56,9 @@ export const REVIEW = {
     ],
     requiredGates: [
         { id: "review_layer1_spec_compliance", description: "Spec compliance check completed with per-criterion verdict." },
-        { id: "review_layer2_correctness", description: "Correctness review completed." },
         { id: "review_layer2_security", description: "Security review completed." },
-        { id: "review_layer2_performance", description: "Performance review completed." },
-        { id: "review_layer2_architecture", description: "Architecture fit review completed." },
-        { id: "review_severity_classified", description: "All findings are severity-tagged." },
         { id: "review_criticals_resolved", description: "No unresolved critical blockers remain." },
-        { id: "review_army_json_valid", description: "07-review-army.json passes schema validation (validateReviewArmy)." },
-        { id: "review_completeness_scored", description: "Completeness score is computed and recorded (AC coverage, task coverage, slice coverage, adversarial pass)." },
-        { id: "review_security_audit_swept", description: "The security-audit utility skill was run against the diff scope and the modules it touches. Finding count (0 if clean) recorded in the review army with file:line evidence for every Critical." }
+        { id: "review_army_json_valid", description: "07-review-army.json passes schema validation (validateReviewArmy)." }
     ],
     requiredEvidence: [
         "Artifact written to `.cclaw/artifacts/07-review.md`.",
@@ -205,10 +199,10 @@ export const REVIEW = {
     },
     artifactValidation: [
         { section: "Layer 1 Verdict", required: true, validationRule: "Per-criterion pass/fail with references." },
-        { section: "Layer 2 Findings", required: true, validationRule: "Each finding has severity, description, and resolution status." },
+        { section: "Layer 2 Findings", required: false, validationRule: "Each finding has severity, description, and resolution status." },
         { section: "Review Army Contract", required: true, validationRule: "Structured findings include id/severity/confidence/fingerprint/reportedBy/status with dedup reconciliation summary." },
-        { section: "Review Readiness Dashboard", required: true, validationRule: "Includes a per-pass table (Layer 1 / Layer 2 / Adversarial / Schema) with a 'Completed at' column, a Delegation log snapshot block (path .cclaw/state/delegation-log.json with required/completed/waived/pending), a Staleness signal block (commit at last review pass and current commit), and a Headline with open critical blockers + ship recommendation. At minimum, the section text must contain the substrings 'Completed at', 'delegation-log.json', 'commit at last review pass', and 'Ship recommendation'." },
-        { section: "Completeness Score", required: true, validationRule: "Records AC coverage, task coverage, test-slice coverage, and adversarial-review pass status as numeric or boolean values. At minimum, a line like 'AC coverage: N/M' or 'AC coverage: 100%'." },
+        { section: "Review Readiness Dashboard", required: false, validationRule: "Includes a per-pass table (Layer 1 / Layer 2 / Adversarial / Schema) with a 'Completed at' column, a Delegation log snapshot block (path .cclaw/state/delegation-log.json with required/completed/waived/pending), a Staleness signal block (commit at last review pass and current commit), and a Headline with open critical blockers + ship recommendation. At minimum, the section text must contain the substrings 'Completed at', 'delegation-log.json', 'commit at last review pass', and 'Ship recommendation'." },
+        { section: "Completeness Score", required: false, validationRule: "Records AC coverage, task coverage, test-slice coverage, and adversarial-review pass status as numeric or boolean values. At minimum, a line like 'AC coverage: N/M' or 'AC coverage: 100%'." },
         { section: "Severity Summary", required: true, validationRule: "Per-severity count lines for critical, important, and suggestion buckets." },
         { section: "Final Verdict", required: true, validationRule: "Exactly one of: APPROVED, APPROVED_WITH_CONCERNS, BLOCKED." }
     ]

package/dist/content/stages/scope.js

@@ -55,11 +55,8 @@ export const SCOPE = {
         "Produce scope summary plus completion dashboard (checklist findings, number of resolved decisions, unresolved items or `None`)."
     ],
     requiredGates: [
-        { id: "scope_premise_challenged", description: "Problem framing and assumptions were challenged." },
-        { id: "scope_alternatives_produced", description: "At least 2 implementation alternatives were evaluated with explicit effort/risk and reuse fields." },
         { id: "scope_mode_selected", description: "One scope mode was explicitly selected." },
         { id: "scope_contract_written", description: "In-scope/out-of-scope contract is documented." },
-        { id: "scope_discretion_documented", description: "Discretion areas are documented (or explicitly marked as none)." },
         { id: "scope_user_approved", description: "User approved the final scope direction." }
     ],
     requiredEvidence: [
@@ -172,17 +169,17 @@ export const SCOPE = {
         traceabilityRule: "Every scope boundary must be traceable to a brainstorm decision. Every downstream design choice must stay within the scope contract."
     },
     artifactValidation: [
-        { section: "Prime Directives", required: true, validationRule: "For each scoped capability: named failure modes, explicit error surface, four data-flow paths, interaction edge cases, observability expectations, and deferred-item handling." },
-        { section: "Premise Challenge", required: true, validationRule: "Must contain explicit answers to: right problem? direct path? what if nothing?" },
-        { section: "Requirements", required: true, validationRule: "Table of stable requirement IDs (R1, R2, R3…) one per row with observable outcome, priority, and source. IDs are assigned once and never renumbered across scope/design/spec/plan/review; dropped requirements stay with Priority `DROPPED`." },
+        { section: "Prime Directives", required: false, validationRule: "For each scoped capability: named failure modes, explicit error surface, four data-flow paths, interaction edge cases, observability expectations, and deferred-item handling." },
+        { section: "Premise Challenge", required: false, validationRule: "Must contain explicit answers to: right problem? direct path? what if nothing?" },
+        { section: "Requirements", required: false, validationRule: "Table of stable requirement IDs (R1, R2, R3…) one per row with observable outcome, priority, and source. IDs are assigned once and never renumbered across scope/design/spec/plan/review; dropped requirements stay with Priority `DROPPED`." },
         { section: "Locked Decisions (D-XX)", required: false, validationRule: "List of stable locked decisions with IDs D-01, D-02... Each ID appears once, includes rationale, and is intended for downstream cross-stage traceability." },
-        { section: "Implementation Alternatives", required: true, validationRule: "2-3 options with Name, Summary, Effort, Risk, Pros, Cons, and Reuses. Must include minimal viable and ideal architecture options." },
+        { section: "Implementation Alternatives", required: false, validationRule: "2-3 options with Name, Summary, Effort, Risk, Pros, Cons, and Reuses. Must include minimal viable and ideal architecture options." },
         { section: "Scope Mode", required: true, validationRule: "Must state selected mode and rationale with default heuristic justification." },
-        { section: "Mode-Specific Analysis", required: true, validationRule: "Must document the analysis matching the selected scope mode: EXPAND (10x and delight opportunities), SELECTIVE (hold-scope baseline then cherry-picked expansions), HOLD (minimum-change-set hardening), REDUCE (ruthless cuts and follow-up split)." },
+        { section: "Mode-Specific Analysis", required: false, validationRule: "Must document the analysis matching the selected scope mode: EXPAND (10x and delight opportunities), SELECTIVE (hold-scope baseline then cherry-picked expansions), HOLD (minimum-change-set hardening), REDUCE (ruthless cuts and follow-up split)." },
         { section: "In Scope / Out of Scope", required: true, validationRule: "Two separate explicit lists. Out-of-scope must not be empty." },
-        { section: "Discretion Areas", required: true, validationRule: "Explicit list of implementer decision zones, or 'None' if scope is fully locked." },
-        { section: "Deferred Items", required: true, validationRule: "Each item has one-line rationale. If empty, state 'None' explicitly." },
-        { section: "Error & Rescue Registry", required: true, validationRule: "Each scoped capability has: failure mode, detection method, fallback decision." },
+        { section: "Discretion Areas", required: false, validationRule: "Explicit list of implementer decision zones, or 'None' if scope is fully locked." },
+        { section: "Deferred Items", required: false, validationRule: "Each item has one-line rationale. If empty, state 'None' explicitly." },
+        { section: "Error & Rescue Registry", required: false, validationRule: "Each scoped capability has: failure mode, detection method, fallback decision." },
         { section: "Completion Dashboard", required: true, validationRule: "Lists checklist findings, count of resolved decisions, and unresolved decisions (or 'None')." },
         { section: "Scope Summary", required: true, validationRule: "Clean summary: mode, strongest challenges, recommended path, accepted scope, deferred, excluded." },
         { section: "Dream State Mapping", required: false, validationRule: "If present (complex projects): CURRENT STATE, THIS PLAN, 12-MONTH IDEAL, and alignment verdict." },

package/dist/content/stages/ship.js

@@ -50,11 +50,8 @@ export const SHIP = {
     requiredGates: [
         { id: "ship_review_verdict_valid", description: "Review verdict is APPROVED or APPROVED_WITH_CONCERNS." },
         { id: "ship_preflight_passed", description: "Preflight checks passed or exceptions documented and approved." },
-        { id: "ship_release_notes_written", description: "Release notes are complete and accurate." },
         { id: "ship_rollback_plan_ready", description: "Rollback trigger, steps, and verification are documented." },
-        { id: "ship_finalization_mode_selected", description: "Exactly one finalization action is selected." },
-        { id: "ship_finalization_executed", description: "Selected finalization action was executed and verified." },
-        { id: "ship_post_merge_tests", description: "Full test suite re-run on the merged result (not just the branch). Post-merge failures caught before release." }
+        { id: "ship_finalization_executed", description: "Selected finalization action was executed and verified." }
     ],
     requiredEvidence: [
         "Artifact written to `.cclaw/artifacts/08-ship.md`.",

package/dist/content/stages/spec.js

@@ -46,8 +46,6 @@ export const SPEC = {
     ],
     requiredGates: [
         { id: "spec_acceptance_measurable", description: "Acceptance criteria are measurable and observable." },
-        { id: "spec_edge_cases_documented", description: "Boundary and error conditions are defined for each criterion." },
-        { id: "spec_constraints_documented", description: "Constraints and assumptions are explicit." },
         { id: "spec_testability_confirmed", description: "Each criterion has a described test method." },
         { id: "spec_user_approved", description: "User approved the final written spec." }
     ],
@@ -125,7 +123,7 @@ export const SPEC = {
     artifactValidation: [
         { section: "Acceptance Criteria", required: true, validationRule: "Each criterion is observable, measurable, and falsifiable. Table must include a Requirement Ref column linking to R# IDs in 02-scope.md and a Design Decision Ref column tracing back to design artifact. AC IDs (AC-1, AC-2…) are stable across revisions — dropped ACs stay with Priority `DROPPED`." },
         { section: "Edge Cases", required: true, validationRule: "At least one boundary and one error condition per criterion." },
-        { section: "Constraints and Assumptions", required: true, validationRule: "All implicit assumptions surfaced. Constraints have sources." },
+        { section: "Constraints and Assumptions", required: false, validationRule: "All implicit assumptions surfaced. Constraints have sources." },
         { section: "Testability Map", required: true, validationRule: "Each criterion maps to a concrete test description with verification approach (unit, integration, e2e, manual) and command or manual steps." },
         { section: "Vague to Fixed", required: false, validationRule: "If present: table with original vague wording and rewritten observable/testable version for each ambiguous requirement." },
         { section: "Non-Functional Requirements", required: false, validationRule: "If present: performance thresholds, security constraints, scalability limits, reliability targets with measurable values." },

package/dist/content/stages/tdd.js

@@ -57,12 +57,8 @@ export const TDD = {
     ],
     requiredGates: [
         { id: "tdd_red_test_written", description: "Failing tests exist before implementation changes." },
-        { id: "tdd_red_failure_captured", description: "Failure output is captured as evidence." },
-        { id: "tdd_trace_to_acceptance", description: "RED tests trace to explicit acceptance criteria." },
-        { id: "tdd_red_failure_reason_verified", description: "Failure is for the expected reason, not an unrelated error." },
         { id: "tdd_green_full_suite", description: "Full relevant suite passes in GREEN state." },
         { id: "tdd_refactor_completed", description: "Refactor pass completed with behavior preservation verified." },
-        { id: "tdd_refactor_notes_written", description: "Refactor decisions and outcomes are documented." },
         { id: "tdd_traceable_to_plan", description: "Change traceability to plan slice is explicit." }
     ],
     requiredEvidence: [
@@ -173,8 +169,8 @@ export const TDD = {
     },
     artifactValidation: [
         { section: "RED Evidence", required: true, validationRule: "Failing test output captured per slice." },
-        { section: "Acceptance Mapping", required: true, validationRule: "Each RED test links to a plan task and spec criterion." },
-        { section: "Failure Analysis", required: true, validationRule: "Failure reason matches expected missing behavior." },
+        { section: "Acceptance Mapping", required: false, validationRule: "Each RED test links to a plan task and spec criterion." },
+        { section: "Failure Analysis", required: false, validationRule: "Failure reason matches expected missing behavior." },
         { section: "GREEN Evidence", required: true, validationRule: "Full suite pass output captured." },
         { section: "REFACTOR Notes", required: true, validationRule: "What changed, why, behavior preservation confirmed." },
         { section: "Traceability", required: true, validationRule: "Plan task ID and spec criterion linked." },

package/dist/content/start-command.js

@@ -19,7 +19,7 @@ export function startCommandContract() {
 **The unified entry point for the cclaw flow.**
 
 - \`/cc\` (no arguments) → behaves exactly like \`/cc-next\`: reads flow state and resumes the current stage, or starts brainstorm if the flow is fresh.
-- \`/cc <prompt>\` (with an idea/description) → saves the prompt as brainstorm context and begins the brainstorm stage, regardless of current flow state.
+- \`/cc <prompt>\` (with an idea/description) → saves the prompt as idea context and starts the first stage of the resolved track.
 
 This is the **recommended way to start** working with cclaw. Use \`/cc-next\` for subsequent stage progression.
 
@@ -63,7 +63,7 @@ This is the **recommended way to start** working with cclaw. Use \`/cc-next\` fo
    Skip detection quietly if no markers are found — do NOT invent a stack.
 
 4. Read \`${flowPath}\`.
-5. If flow already has completed stages beyond brainstorm, warn the user that starting a new brainstorm will reset progress. Ask for confirmation before proceeding.
+5. If flow already has completed stages, warn the user that starting a new tracked flow will reset progress. Ask for confirmation before proceeding.
 6. **Track heuristic** — classify the idea text and **recommend** a track (the user can override before any state mutation):
    - First, load \`${RUNTIME_ROOT}/config.yaml\`. If \`trackHeuristics\` is defined, apply those per-track vocabulary hints (\`fallback\`, \`tracks.<id>.{triggers,veto}\`) on top of the built-in defaults. Evaluation order is always \`standard -> medium -> quick\` (narrow-to-broad).
    - **quick** (\`spec → tdd → review → ship\`) — single-purpose work where the spec is essentially already known.
@@ -137,7 +137,7 @@ Do **not** silently discard an existing flow when the user provides a prompt. If
 3. **Stack detection (Phase 2).** Inspect \`package.json\` engines, \`pyproject.toml\`, \`go.mod\`, \`Cargo.toml\`, \`pom.xml\`, \`build.gradle*\`, \`Dockerfile\`, \`docker-compose*.yml\`, and CI configs. Record stack + versions on the \`Stack:\` line. Do not invent stack details.
 4. Read \`${flowPath}\`.
 5. If \`completedStages\` is non-empty:
-   - Inform: "You have an active flow at stage **{currentStage}** with {N} completed stages. Starting a new brainstorm will reset progress."
+   - Inform: "You have an active flow at stage **{currentStage}** with {N} completed stages. Starting a new tracked flow will reset progress."
    - Ask: "Continue with reset? (A) Yes, start fresh (B) No, resume current flow"
    - If (B) → switch to Path B behavior.
 6. **Classify the idea** using the heuristic below and present a single track recommendation. Wait for explicit confirmation or override before mutating any state.
@@ -149,7 +149,7 @@ Do **not** silently discard an existing flow when the user provides a prompt. If
    |---|---|---|
    | \`quick\` | \`bug\`, \`bugfix\`, \`fix\`, \`hotfix\`, \`patch\`, \`typo\`, \`regression\`, \`rename\`, \`bump\`, \`upgrade dep\`, \`docs only\`, \`comment\`, \`lint\`, \`format\`, \`small\`, \`tiny\`, \`one-liner\`, \`revert\`, \`copy change\` | Single-purpose, spec is essentially known, low blast radius |
    | \`medium\` | \`add endpoint\`, \`add field\`, \`extend existing\`, \`wire integration\`, \`small migration\`, \`new screen following existing pattern\` | Additive work with existing architecture |
-   | \`standard\` | \`new feature\`, \`build\`, \`design\`, \`refactor\`, \`migration\`, \`platform\`, \`architecture\`, \`schema\`, \`api\`, \`integrate\`, \`workflow\`, \`onboarding\` (or no confident quick/medium match) | New or uncertain multi-module work |
+   | \`standard\` | \`new feature\`, \`refactor\`, \`migration\`, \`platform\`, \`architecture\`, \`schema\`, \`integrate\`, \`workflow\`, \`onboarding\` (or no confident quick/medium match) | New or uncertain multi-module work |
 
    - On conflict, prefer \`standard\` over \`medium\`, and \`medium\` over \`quick\`.
    - Always state the recommendation as a one-line reason citing matched triggers.
@@ -180,6 +180,6 @@ Delegate entirely to \`/cc-next\` behavior:
 | Progressing after completing a stage | \`/cc-next\` |
 | Starting with a specific idea | \`/cc <idea>\` |
 
-Both commands read the same \`flow-state.json\`. The difference is that \`/cc <prompt>\` always targets brainstorm, while \`/cc\` and \`/cc-next\` follow the state.
+Both commands read the same \`flow-state.json\`. The difference is that \`/cc <prompt>\` resolves class + track and starts that track's first stage, while \`/cc\` and \`/cc-next\` follow the current state.
 `;
 }

package/dist/internal/advance-stage.js

@@ -380,15 +380,24 @@ async function runAdvanceStage(projectRoot, args, io) {
         ...nextPassed.filter((gateId) => conditional.has(gateId)),
         ...nextBlocked.filter((gateId) => conditional.has(gateId))
     ]);
+    const missingGuardEvidence = nextPassed.filter((gateId) => {
+        const existing = flowState.guardEvidence[gateId];
+        if (typeof existing === "string" && existing.trim().length > 0) {
+            return false;
+        }
+        const provided = args.evidenceByGate[gateId];
+        return !(typeof provided === "string" && provided.trim().length > 0);
+    });
+    if (missingGuardEvidence.length > 0) {
+        io.stderr.write(`cclaw internal advance-stage: missing --evidence-json entries for passed gates: ${missingGuardEvidence.join(", ")}.\n`);
+        return 1;
+    }
     const nextGuardEvidence = { ...flowState.guardEvidence };
     for (const gateId of nextPassed) {
-        const existing = nextGuardEvidence[gateId];
-        if (typeof existing === "string" && existing.trim().length > 0)
-            continue;
         const provided = args.evidenceByGate[gateId];
-        nextGuardEvidence[gateId] = provided && provided.trim().length > 0
-            ? provided.trim()
-            : `stage-complete helper auto-evidence for ${gateId} @ ${new Date().toISOString()} (${schema.artifactFile})`;
+        if (typeof provided === "string" && provided.trim().length > 0) {
+            nextGuardEvidence[gateId] = provided.trim();
+        }
     }
     const nextStageCatalog = {
         required: [...catalog.required],

package/dist/knowledge-store.d.ts

@@ -3,6 +3,7 @@ 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 type KnowledgeEntrySource = "stage" | "retro" | "compound" | "ideate" | "manual";
 export interface KnowledgeEntry {
     type: KnowledgeEntryType;
     trigger: string;
@@ -19,6 +20,7 @@ export interface KnowledgeEntry {
     first_seen_ts: string;
     last_seen_ts: string;
     project: string | null;
+    source?: KnowledgeEntrySource | null;
 }
 export interface KnowledgeSeedEntry {
     type: KnowledgeEntryType;
@@ -36,12 +38,14 @@ export interface KnowledgeSeedEntry {
     first_seen_ts?: string;
     last_seen_ts?: string;
     project?: string | null;
+    source?: KnowledgeEntrySource | null;
 }
 export interface AppendKnowledgeDefaults {
     stage?: FlowStage | null;
     originStage?: FlowStage | null;
     originFeature?: string | null;
     project?: string | null;
+    source?: KnowledgeEntrySource | null;
     nowIso?: string;
 }
 export interface AppendKnowledgeResult {

package/dist/knowledge-store.js

@@ -7,6 +7,13 @@ 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 KNOWLEDGE_SOURCE_SET = new Set([
+    "stage",
+    "retro",
+    "compound",
+    "ideate",
+    "manual"
+]);
 const FLOW_STAGE_SET = new Set(FLOW_STAGES);
 const KNOWLEDGE_REQUIRED_KEYS = [
     "type",
@@ -26,6 +33,7 @@ const KNOWLEDGE_REQUIRED_KEYS = [
     "project"
 ];
 const KNOWLEDGE_ALLOWED_KEYS = new Set(KNOWLEDGE_REQUIRED_KEYS);
+KNOWLEDGE_ALLOWED_KEYS.add("source");
 function knowledgePath(projectRoot) {
     return path.join(projectRoot, RUNTIME_ROOT, "knowledge.jsonl");
 }
@@ -51,7 +59,8 @@ function dedupeKey(entry) {
         entry.origin_stage ?? "null",
         entry.origin_feature === null ? "null" : normalizeText(entry.origin_feature),
         entry.universality,
-        entry.project === null ? "null" : normalizeText(entry.project)
+        entry.project === null ? "null" : normalizeText(entry.project),
+        entry.source === undefined || entry.source === null ? "null" : entry.source
     ].join("|");
 }
 function isIsoUtcTimestamp(value) {
@@ -123,13 +132,19 @@ export function validateKnowledgeEntry(entry) {
     if (!isNullableString(obj.project)) {
         errors.push("project must be string or null.");
     }
+    if (obj.source !== undefined &&
+        obj.source !== null &&
+        (typeof obj.source !== "string" || !KNOWLEDGE_SOURCE_SET.has(obj.source))) {
+        errors.push("source must be one of: stage, retro, compound, ideate, manual, 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 {
+    const source = seed.source ?? defaults.source ?? null;
+    const entry = {
         type: seed.type,
         trigger: seed.trigger.trim(),
         action: seed.action.trim(),
@@ -146,6 +161,10 @@ export function materializeKnowledgeEntry(seed, defaults = {}) {
         last_seen_ts: normalizeUtcIso(seed.last_seen_ts ?? now),
         project: seed.project ?? defaults.project ?? null
     };
+    if (source !== null) {
+        entry.source = source;
+    }
+    return entry;
 }
 async function readExistingKnowledgeKeys(filePath) {
     const keys = new Set();

package/dist/runs.js

@@ -398,7 +398,14 @@ async function evaluateRetroGate(projectRoot, state) {
                     continue;
                 try {
                     const parsed = JSON.parse(trimmed);
-                    if (parsed.type === "compound") {
+                    if (parsed.type !== "compound") {
+                        continue;
+                    }
+                    const source = typeof parsed.source === "string"
+                        ? parsed.source.trim().toLowerCase()
+                        : null;
+                    const legacyRetroStage = parsed.stage === "retro";
+                    if (source === "retro" || legacyRetroStage) {
                         compoundEntries += 1;
                     }
                 }
@@ -563,6 +570,7 @@ export async function archiveRun(projectRoot, featureName, options = {}) {
     const archiveArtifactsPath = path.join(archivePath, "artifacts");
     let sourceState = await readFlowState(projectRoot);
     const retroGate = await evaluateRetroGate(projectRoot, sourceState);
+    const shipCompleted = sourceState.completedStages.includes("ship");
     const skipRetro = options.skipRetro === true;
     const skipRetroReason = options.skipRetroReason?.trim();
     if (skipRetro && (!skipRetroReason || skipRetroReason.length === 0)) {
@@ -571,6 +579,12 @@ export async function archiveRun(projectRoot, featureName, options = {}) {
     const retroSkippedInCloseout = sourceState.closeout.retroSkipped === true &&
         typeof sourceState.closeout.retroSkipReason === "string" &&
         sourceState.closeout.retroSkipReason.trim().length > 0;
+    const readyForArchive = sourceState.closeout.shipSubstate === "ready_to_archive";
+    if (shipCompleted && !readyForArchive && !skipRetro && !retroSkippedInCloseout) {
+        throw new Error("Archive blocked: closeout is not ready_to_archive. " +
+            "Resume /cc-next until closeout reaches ready_to_archive, " +
+            "or run `cclaw archive --skip-retro --retro-reason=<text>` for CLI-only flows.");
+    }
     if (retroGate.required && !retroGate.completed && !skipRetro && !retroSkippedInCloseout) {
         throw new Error("Archive blocked: retro gate is required after ship completion. " +
             "Run /cc-next (auto-runs retro) or, for CLI-only flows, re-run `cclaw archive --skip-retro --retro-reason=<text>`.");
@@ -590,8 +604,12 @@ export async function archiveRun(projectRoot, featureName, options = {}) {
     const retroSummary = {
         required: retroGate.required,
         completed: retroGate.completed,
-        skipped: skipRetro,
-        skipReason: skipRetro ? skipRetroReason : undefined,
+        skipped: skipRetro || retroSkippedInCloseout,
+        skipReason: skipRetro
+            ? skipRetroReason
+            : retroSkippedInCloseout
+                ? sourceState.closeout.retroSkipReason
+                : undefined,
         compoundEntries: retroGate.compoundEntries
     };
     await ensureDir(archivePath);

package/dist/tdd-cycle.js

@@ -48,6 +48,14 @@ export function validateTddCycleOrder(entries, options = {}) {
         let state = "need_red";
         for (const entry of sliceEntries) {
             if (entry.phase === "red") {
+                if (entry.exitCode === undefined) {
+                    issues.push(`slice ${slice}: red entry must record a non-zero exitCode`);
+                    continue;
+                }
+                if (entry.exitCode === 0) {
+                    issues.push(`slice ${slice}: red entry exitCode must be non-zero`);
+                    continue;
+                }
                 if (state === "red_open") {
                     issues.push(`slice ${slice}: duplicate red before green`);
                     continue;
@@ -56,6 +64,14 @@ export function validateTddCycleOrder(entries, options = {}) {
                 continue;
             }
             if (entry.phase === "green") {
+                if (entry.exitCode === undefined) {
+                    issues.push(`slice ${slice}: green entry must record exitCode 0`);
+                    continue;
+                }
+                if (entry.exitCode !== 0) {
+                    issues.push(`slice ${slice}: green entry exitCode must be 0`);
+                    continue;
+                }
                 if (state !== "red_open") {
                     issues.push(`slice ${slice}: green logged before red`);
                     continue;

package/package.json

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