cclaw-cli 0.51.12 → 0.51.14

package/dist/artifact-linter.js

@@ -1,4 +1,5 @@
 import fs from "node:fs/promises";
+import { createHash } from "node:crypto";
 import path from "node:path";
 import { resolveArtifactPath as resolveStageArtifactPath } from "./artifact-paths.js";
 import { readConfig } from "./config.js";
@@ -94,6 +95,15 @@ function sectionBodyByAnyName(sections, sectionNames) {
         return null;
     return bodies.join("\n");
 }
+function sectionBodyByHeadingPrefix(sections, prefix) {
+    const want = normalizeHeadingTitle(prefix).toLowerCase();
+    for (const [heading, body] of sections.entries()) {
+        if (heading.toLowerCase().startsWith(want)) {
+            return body;
+        }
+    }
+    return null;
+}
 export function extractMarkdownSectionBody(markdown, section) {
     return sectionBodyByName(extractH2Sections(markdown), section);
 }
@@ -675,6 +685,52 @@ function validateRequirementsTaxonomy(sectionBody) {
         details: "Requirements table uses canonical Priority values."
     };
 }
+function validateLockedDecisionAnchors(sectionBody) {
+    const rows = getMarkdownTableRows(sectionBody);
+    const lines = sectionBody
+        .split(/\r?\n/u)
+        .map((line) => line.trim())
+        .filter((line) => /^[-*]\s+\S/u.test(line));
+    const anchors = [];
+    const issues = [];
+    for (const [index, row] of rows.entries()) {
+        const anchor = (row[0] ?? "").trim().toLowerCase();
+        const decisionText = (row[1] ?? "").trim();
+        if (!/^ld#[0-9a-f]{8}$/u.test(anchor)) {
+            issues.push(`row ${index + 1} has invalid anchor "${row[0] ?? ""}"`);
+            continue;
+        }
+        anchors.push(anchor);
+        if (decisionText.length > 0) {
+            const expected = lockedDecisionHash(decisionText).toLowerCase();
+            if (anchor !== expected) {
+                issues.push(`row ${index + 1} anchor should be ${expected} for its Decision text`);
+            }
+        }
+    }
+    for (const [index, line] of lines.entries()) {
+        const anchor = /\bLD#[0-9a-f]{8}\b/iu.exec(line)?.[0]?.toLowerCase();
+        if (!anchor) {
+            issues.push(`bullet ${index + 1} is missing an LD#<sha8> anchor`);
+            continue;
+        }
+        anchors.push(anchor);
+    }
+    const duplicateAnchors = [...new Set(anchors.filter((anchor, index) => anchors.indexOf(anchor) !== index))];
+    if (duplicateAnchors.length > 0) {
+        issues.push(`duplicate anchors: ${duplicateAnchors.join(", ")}`);
+    }
+    if (anchors.length === 0 && (rows.length > 0 || lines.length > 0)) {
+        issues.push("no LD#<sha8> anchors found");
+    }
+    return {
+        ok: issues.length === 0,
+        anchors: [...new Set(anchors)],
+        details: issues.length === 0
+            ? `${anchors.length} LD#hash anchor(s) recorded with no duplicates.`
+            : issues.join("; ")
+    };
+}
 const INTERACTION_EDGE_CASE_REQUIREMENTS = [
     { label: "double-click", pattern: /\bdouble[\s-]?click\b/iu },
     {
@@ -1286,6 +1342,18 @@ function extractDecisionIds(text) {
     const ids = text.match(/\bD-\d+\b/gu) ?? [];
     return [...new Set(ids)];
 }
+function extractRequirementIdsFromMarkdown(text) {
+    const ids = text.match(/\bR\d+\b/gu) ?? [];
+    return [...new Set(ids)];
+}
+function extractLockedDecisionAnchors(text) {
+    const ids = text.match(/\bLD#[0-9a-f]{8}\b/giu) ?? [];
+    return [...new Set(ids.map((id) => id.replace(/^LD#/iu, "LD#").toLowerCase()))];
+}
+function lockedDecisionHash(value) {
+    const normalized = value.replace(/\s+/gu, " ").trim().toLowerCase();
+    return `LD#${createHash("sha256").update(normalized).digest("hex").slice(0, 8)}`;
+}
 function collectPatternHits(text, patterns) {
     const hits = [];
     for (const pattern of patterns) {
@@ -1401,7 +1469,7 @@ function validateSectionBody(sectionBody, rule, sectionName) {
     if (sectionNameNormalized === "premise challenge") {
         return validatePremiseChallenge(sectionBody);
     }
-    if (sectionNameNormalized === "requirements") {
+    if (sectionNameNormalized.startsWith("requirements")) {
         return validateRequirementsTaxonomy(sectionBody);
     }
     if (sectionNameNormalized === "data flow") {
@@ -1823,9 +1891,9 @@ export async function lintArtifact(projectRoot, stage, track = "standard") {
         });
     }
     if (stage === "scope") {
-        const lockedDecisionsBody = sectionBodyByName(sections, "Locked Decisions (D-XX)") ?? "";
+        const lockedDecisionsBody = sectionBodyByHeadingPrefix(sections, "Locked Decisions") ?? "";
         const strictScopeGuards = parsedFrontmatter.hasFrontmatter ||
-            headingPresent(sections, "Locked Decisions (D-XX)");
+            sectionBodyByHeadingPrefix(sections, "Locked Decisions") !== null;
         const scopeSections = [
             sectionBodyByAnyName(sections, ["In Scope / Out of Scope", "In Scope", "Out of Scope"]) ?? "",
             sectionBodyByName(sections, "Scope Summary") ?? "",
@@ -1841,12 +1909,18 @@ export async function lintArtifact(projectRoot, stage, track = "standard") {
                 ? "No scope-reduction phrases detected in scope boundary sections."
                 : `Detected scope-reduction phrase(s): ${reductionHits.join(", ")}.`
         });
-        // When the Locked Decisions section is present we must enforce the
-        // D-XX ID contract at runtime (previously this was prose-only in the
-        // artifactValidation rule). Empty body, missing IDs, and duplicate
-        // IDs all fail the lint; absence of the section remains advisory so
-        // scope stays optional for small/quick tracks.
-        if (headingPresent(sections, "Locked Decisions (D-XX)")) {
+        if (sectionBodyByHeadingPrefix(sections, "Locked Decisions") !== null) {
+            const anchorValidation = validateLockedDecisionAnchors(lockedDecisionsBody);
+            findings.push({
+                section: "Locked Decisions Hash Integrity",
+                required: true,
+                rule: "Locked Decisions section must list unique LD#<sha8> content-derived anchors.",
+                found: anchorValidation.ok,
+                details: anchorValidation.details
+            });
+            // Legacy D-XX rows remain advisory for older artifacts, but new templates
+            // use LD#hash anchors. This check keeps D-XX duplicates visible without
+            // making old artifacts the primary contract.
             const listDecisionLines = lockedDecisionsBody
                 .split(/\r?\n/u)
                 .map((line) => line.trim())
@@ -1881,7 +1955,7 @@ export async function lintArtifact(projectRoot, stage, track = "standard") {
             }
             findings.push({
                 section: "Locked Decisions ID Integrity",
-                required: true,
+                required: false,
                 rule: "Locked Decisions section must list each decision with a unique stable D-XX ID.",
                 found: issues.length === 0,
                 details: issues.length === 0
@@ -1890,6 +1964,46 @@ export async function lintArtifact(projectRoot, stage, track = "standard") {
             });
         }
     }
+    if (["design", "spec", "plan", "review"].includes(stage)) {
+        const scopeArtifact = await resolveStageArtifactPath("scope", {
+            projectRoot,
+            track,
+            intent: "read"
+        });
+        if (await exists(scopeArtifact.absPath)) {
+            const scopeRaw = await fs.readFile(scopeArtifact.absPath, "utf8");
+            const scopeSections = extractH2Sections(scopeRaw);
+            const requirementsBody = sectionBodyByHeadingPrefix(scopeSections, "Requirements") ?? "";
+            const lockedDecisionsBody = sectionBodyByHeadingPrefix(scopeSections, "Locked Decisions") ?? "";
+            const requirementIds = extractRequirementIdsFromMarkdown(requirementsBody);
+            const lockedDecisionAnchors = extractLockedDecisionAnchors(lockedDecisionsBody);
+            const missingRequirementRefs = requirementIds.filter((id) => !raw.includes(id));
+            const normalizedCurrentRaw = raw.toLowerCase();
+            const missingDecisionRefs = lockedDecisionAnchors.filter((id) => !normalizedCurrentRaw.includes(id));
+            findings.push({
+                section: "Scope Requirement Reference Integrity",
+                required: requirementIds.length > 0,
+                rule: "Every R# requirement ID from scope must be referenced by downstream artifacts.",
+                found: missingRequirementRefs.length === 0,
+                details: requirementIds.length === 0
+                    ? "No R# requirement IDs found in scope artifact; reference check skipped."
+                    : missingRequirementRefs.length === 0
+                        ? `All ${requirementIds.length} scope requirement ID(s) are referenced.`
+                        : `Missing scope requirement reference(s): ${missingRequirementRefs.join(", ")}.`
+            });
+            findings.push({
+                section: "Locked Decision Hash Reference Integrity",
+                required: lockedDecisionAnchors.length > 0,
+                rule: "Every LD#hash locked decision anchor from scope must be referenced by downstream artifacts.",
+                found: missingDecisionRefs.length === 0,
+                details: lockedDecisionAnchors.length === 0
+                    ? "No LD#hash anchors found in scope artifact; reference check skipped."
+                    : missingDecisionRefs.length === 0
+                        ? `All ${lockedDecisionAnchors.length} locked decision anchor(s) are referenced.`
+                        : `Missing locked decision reference(s): ${missingDecisionRefs.join(", ")}.`
+            });
+        }
+    }
     const passed = findings.every((f) => !f.required || f.found);
     return { stage, file: relFile, passed, findings };
 }

package/dist/constants.d.ts

@@ -10,7 +10,7 @@ export declare const FLOW_VERSION = "1.0.0";
 export declare const SHIP_FINALIZATION_MODES: readonly ["FINALIZE_MERGE_LOCAL", "FINALIZE_OPEN_PR", "FINALIZE_KEEP_BRANCH", "FINALIZE_DISCARD_BRANCH", "FINALIZE_NO_VCS"];
 export type ShipFinalizationMode = (typeof SHIP_FINALIZATION_MODES)[number];
 export declare const DEFAULT_HARNESSES: HarnessId[];
-export declare const REQUIRED_DIRS: readonly [".cclaw", ".cclaw/commands", ".cclaw/skills", ".cclaw/templates", ".cclaw/artifacts", ".cclaw/state", ".cclaw/runs", ".cclaw/rules", ".cclaw/agents", ".cclaw/hooks"];
+export declare const REQUIRED_DIRS: readonly [".cclaw", ".cclaw/commands", ".cclaw/skills", ".cclaw/templates", ".cclaw/templates/state-contracts", ".cclaw/artifacts", ".cclaw/state", ".cclaw/runs", ".cclaw/rules", ".cclaw/agents", ".cclaw/hooks", ".cclaw/skills/review-prompts"];
 export declare const REQUIRED_GITIGNORE_PATTERNS: readonly ["# cclaw generated artifacts", ".cclaw/", ".claude/commands/cc-*.md", ".claude/commands/cc.md", ".cursor/commands/cc-*.md", ".cursor/commands/cc.md", ".opencode/commands/cc-*.md", ".opencode/commands/cc.md", ".agents/skills/cc/SKILL.md", ".agents/skills/cc-*/SKILL.md", ".claude/hooks/hooks.json", ".cursor/hooks.json", ".codex/hooks.json", ".opencode/plugins/cclaw-plugin.mjs", ".cursor/rules/cclaw-workflow.mdc"];
 /**
  * Canonical stage -> skill folder mapping.

package/dist/constants.js

@@ -57,12 +57,14 @@ export const REQUIRED_DIRS = [
     `${RUNTIME_ROOT}/commands`,
     `${RUNTIME_ROOT}/skills`,
     `${RUNTIME_ROOT}/templates`,
+    `${RUNTIME_ROOT}/templates/state-contracts`,
     `${RUNTIME_ROOT}/artifacts`,
     `${RUNTIME_ROOT}/state`,
     `${RUNTIME_ROOT}/runs`,
     `${RUNTIME_ROOT}/rules`,
     `${RUNTIME_ROOT}/agents`,
-    `${RUNTIME_ROOT}/hooks`
+    `${RUNTIME_ROOT}/hooks`,
+    `${RUNTIME_ROOT}/skills/review-prompts`
 ];
 export const REQUIRED_GITIGNORE_PATTERNS = [
     "# cclaw generated artifacts",

package/dist/content/review-prompts.d.ts

@@ -0,0 +1 @@
+export declare const REVIEW_PROMPTS: Record<string, string>;

package/dist/content/review-prompts.js

@@ -0,0 +1,104 @@
+export const REVIEW_PROMPTS = {
+    "brainstorm-self-review.md": `# Brainstorm Self-Review Prompt
+
+Use this before asking the user to approve the brainstorm artifact.
+
+## Calibration
+
+Only flag issues that would cause a real downstream scope/design mistake:
+wrong problem, no real alternative, hidden scope growth, missing user reaction,
+or a recommendation that does not trace to the user's answer.
+
+Do not flag prose style, wording preferences, section length, or missing detail
+that would not change the scope/design decision.
+
+## Checks
+
+| Category | What to check |
+|---|---|
+| Premise | Is this the right problem and the direct path? |
+| Alternatives | Are there 2-3 meaningfully different options, including exactly one challenger with high/higher upside? |
+| User reaction | Does the selected direction trace to the user's reaction/concerns? |
+| Scope protection | Does the Not Doing list prevent silent enlargement? |
+| Handoff | Is the next-stage handoff explicit and track-aware? |
+
+## Output
+
+Write the result into \`## Self-Review Notes\`:
+
+\`\`\`markdown
+- Status: Approved | Issues Found
+- Patches applied:
+  - <specific patch or None>
+- Remaining concerns:
+  - <concern or None>
+\`\`\`
+`,
+    "scope-ceo-review.md": `# Scope CEO Review Prompt
+
+Use this after drafting scope boundaries and before user approval.
+
+## Calibration
+
+Think like a founder reviewing whether this is the right product slice. Flag
+only issues that would materially change scope, sequencing, leverage, or user
+value. Do not nitpick wording.
+
+## Checks
+
+| Category | What to check |
+|---|---|
+| Premise | Are we solving the right problem now? |
+| Leverage | Are we using existing code, constraints, and platform strengths? |
+| 10-star delta | Is there a better high-leverage scope move worth cherry-picking? |
+| Boundary | Are accepted, deferred, and excluded items unambiguous? |
+| Mode fit | Does the selected mode match the evidence: SCOPE EXPANSION, SELECTIVE EXPANSION, HOLD SCOPE, or SCOPE REDUCTION? |
+| Downstream refs | Are R-IDs and LD#hash anchors ready for design/spec/plan? |
+
+## Output
+
+Record in \`## Outside Voice Findings\` or \`## Spec Review Loop\`:
+
+\`\`\`markdown
+| ID | Dimension | Finding | Disposition | Rationale |
+|---|---|---|---|---|
+| CEO-1 | <dimension> | <issue> | accept/reject/defer | <why> |
+\`\`\`
+`,
+    "design-eng-review.md": `# Design Engineering Review Prompt
+
+Use this after drafting design and before handing to spec.
+
+## Calibration
+
+Think like a senior engineer reviewing whether implementation can proceed
+without hidden architecture risk. Flag only issues that would cause wrong code,
+rework, missing failure behavior, or unverifiable acceptance criteria.
+
+## Checks
+
+| Category | What to check |
+|---|---|
+| Architecture | Are component boundaries concrete and aligned with scope? |
+| Data flow | Are inputs, outputs, persistence, and async/sync edges explicit? |
+| Failure modes | Does every meaningful failure have detection, rescue, and user-visible behavior? |
+| Traceability | Do design decisions reference relevant R-IDs and LD#hash anchors? |
+| Verification | Is each risky choice testable by spec/plan/TDD? |
+| Overbuild | Is any architecture stronger than the locked scope actually needs? |
+
+## Output
+
+Record findings in the design artifact's review section:
+
+\`\`\`markdown
+## Engineering Review
+**Status:** Approved | Issues Found
+
+**Issues:**
+- [R#/LD#hash]: <specific issue> — <why it matters>
+
+**Recommendations:**
+- <advisory item or None>
+\`\`\`
+`
+};

package/dist/content/skills.js

@@ -30,16 +30,20 @@ Before execution:
 2. Load active artifacts from \`.cclaw/artifacts/\`.
 3. Load upstream artifacts required by this stage:
 ${readLines}
-4. Extract upstream decisions, constraints, and open questions into the current
+4. Read the state contract for this stage from \`.cclaw/templates/state-contracts/<stage>.json\`.
+   Treat it as the machine-readable skeleton: required top-level fields,
+   closed taxonomies, and the derived markdown path. Do not validate natural-language
+   prose by regex; put semantic quality checks in the review prompts.
+5. Extract upstream decisions, constraints, and open questions into the current
    artifact's \`Upstream Handoff\` section when that section exists.
-5. Before doing stage work, give a compact user-facing drift preamble: "Carrying forward: <1-3 bullets>. Drift since upstream: None / <specific drift>. Recommendation: continue / re-scope."
-6. If you change an upstream decision, record an explicit drift reason in the
+6. Before doing stage work, give a compact user-facing drift preamble: "Carrying forward: <1-3 bullets>. Drift since upstream: None / <specific drift>. Recommendation: continue / re-scope."
+7. If you change an upstream decision, record an explicit drift reason in the
    current artifact before continuing.
-7. Confirm stage inputs:
+8. Confirm stage inputs:
 ${inputs}
-8. Confirm required context:
+9. Confirm required context:
 ${requiredContext}
-9. Use the injected knowledge digest from session-start; only fall back to full
+10. Use the injected knowledge digest from session-start; only fall back to full
    \`.cclaw/knowledge.jsonl\` when the digest is insufficient.
 `;
 }

package/dist/content/stages/plan.js

@@ -46,7 +46,7 @@ export const PLAN = {
             "Slice into vertical tasks — each task targets 2-5 minutes, produces one testable outcome, and touches one coherent area.",
             "Task Contract — every task has one coherent outcome, AC mapping, exact verification command/manual step, and expected evidence snippet or pass condition. Avoid vague `run tests` wording.",
             "Annotate slice-review metadata — if `.cclaw/config.yaml::sliceReview.enabled` is true, every task row additionally carries `touchCount` (rough number of files expected to change) and `touchPaths` (glob hints, e.g. `migrations/**`, `src/auth/**`). A task may set `highRisk: true` to force a review pass regardless of thresholds. These fields feed the TDD stage's Per-Slice Review point; when `sliceReview` is disabled they are optional.",
-            "Map scope Locked Decisions — every D-XX from scope is referenced by at least one plan task (or explicitly marked deferred with reason).",
+            "Map scope Locked Decisions — every LD#hash anchor from scope is referenced by at least one plan task (or explicitly marked deferred with reason).",
             "Run anti-placeholder + anti-scope-reduction scans — block `TODO/TBD/...` and phrasing like `v1`, `for now`, `later` for locked boundaries.",
             "Define validation points — mark where progress must be checked before continuing, with concrete command and expected evidence.",
             "Define execution posture — record whether execution should be sequential, dependency-batched, parallel-safe, or blocked; include risk triggers and RED/GREEN/REFACTOR checkpoint/commit expectations when the repo workflow supports them.",

package/dist/content/stages/scope.js

@@ -87,7 +87,7 @@ export const SCOPE = {
             "In-scope and out-of-scope lists are explicit.",
             "Discretion areas are explicit (or marked as `None`).",
             "Selected mode and rationale are documented.",
-            "Locked Decisions section lists stable D-XX IDs for non-negotiable boundaries.",
+            "Locked Decisions section lists stable LD#hash anchors for non-negotiable boundaries.",
             "Premise challenge findings documented.",
             "Outside Voice findings and dispositions are recorded (accept/reject/defer with rationale) before final approval.",
             `Spec review loop summary includes a table with columns Iteration, Quality Score, Findings, plus Stop reason, Target score, and Max iterations. This is outside-voice evidence only; it does not satisfy user approval. ${reviewLoopPolicySummary("scope")}`,
@@ -143,7 +143,7 @@ export const SCOPE = {
             { section: "Landscape Check", required: false, validationRule: "When mode is EXPAND/SELECTIVE, include at least one external reference insight and its impact on scope." },
             { section: "Taste Calibration", required: false, validationRule: "Must reference 2-3 strong in-repo modules/files that define the quality bar or explicitly justify omission." },
             { 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: "Locked Decisions (LD#hash)", required: false, validationRule: "List of stable locked decisions with unique `LD#<sha8>` anchors. Each anchor is derived from the normalized Decision cell and is referenced downstream for cross-stage traceability." },
             { 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: false, validationRule: "Deep/complex scope only: document the analysis matching the selected mode. Default path may record a concise mode rationale instead." },

package/dist/content/state-contracts.d.ts

@@ -0,0 +1 @@
+export declare const STATE_CONTRACTS: Record<string, string>;

package/dist/content/state-contracts.js

@@ -0,0 +1,63 @@
+import { CCLAW_VERSION, RUNTIME_ROOT, SHIP_FINALIZATION_MODES } from "../constants.js";
+import { FLOW_STAGES } from "../types.js";
+const REQUIRED_TOP_LEVEL_FIELDS = {
+    brainstorm: ["stage", "selectedDirection", "approachTier", "approaches", "approval", "nextStageHandoff"],
+    scope: ["stage", "scopeMode", "requirements", "lockedDecisions", "scopeSummary", "nextStageHandoff"],
+    design: ["stage", "architecture", "dataFlow", "failureModes", "requirementRefs", "decisionRefs"],
+    spec: ["stage", "acceptanceCriteria", "requirementRefs", "designDecisionRefs"],
+    plan: ["stage", "tasks", "acceptanceCriteriaRefs", "requirementRefs", "decisionRefs", "verificationCommands"],
+    tdd: ["stage", "redEvidence", "greenEvidence", "acceptanceCriteriaRefs", "verificationCommands"],
+    review: ["stage", "finalVerdict", "findings", "acceptanceCriteriaRefs", "requirementRefs", "verificationCommands"],
+    ship: ["stage", "finalizationMode", "verificationSummary", "releaseNotesDraft"]
+};
+const STAGE_TAXONOMIES = {
+    brainstorm: {
+        approachTier: ["Lightweight", "Standard", "Deep"],
+        approachRole: ["baseline", "challenger", "wild-card"],
+        approachUpside: ["low", "modest", "high", "higher"]
+    },
+    scope: {
+        scopeMode: ["SCOPE EXPANSION", "SELECTIVE EXPANSION", "HOLD SCOPE", "SCOPE REDUCTION"],
+        priority: ["P0", "P1", "P2", "P3", "DROPPED"]
+    },
+    design: {
+        diagramTier: ["lightweight", "standard", "deep"],
+        edgeKind: ["sync", "async", "failure", "degraded"]
+    },
+    spec: {
+        priority: ["P0", "P1", "P2", "P3", "DROPPED"]
+    },
+    plan: {
+        taskStatus: ["pending", "in_progress", "blocked", "done", "dropped"]
+    },
+    tdd: {
+        cycleState: ["RED", "GREEN", "REFACTOR", "BLOCKED"]
+    },
+    review: {
+        finalVerdict: ["APPROVED", "APPROVED_WITH_CONCERNS", "BLOCKED"],
+        findingSeverity: ["Critical", "High", "Medium", "Low", "Info"]
+    },
+    ship: {
+        finalizationMode: [...SHIP_FINALIZATION_MODES]
+    }
+};
+function stateContract(stage) {
+    const stageIndex = FLOW_STAGES.indexOf(stage) + 1;
+    const stageNumber = String(stageIndex).padStart(2, "0");
+    return {
+        schemaVersion: 1,
+        contractId: `cclaw-${stage}-state`,
+        stage,
+        derivedMarkdownPath: `${RUNTIME_ROOT}/artifacts/${stageNumber}-${stage}.md`,
+        requiredTopLevelFields: REQUIRED_TOP_LEVEL_FIELDS[stage],
+        taxonomies: STAGE_TAXONOMIES[stage]
+    };
+}
+export const STATE_CONTRACTS = Object.fromEntries(FLOW_STAGES.map((stage) => [
+    `${stage}.json`,
+    `${JSON.stringify({
+        ...stateContract(stage),
+        generatedBy: "cclaw",
+        cclawVersion: CCLAW_VERSION
+    }, null, 2)}\n`
+]));

package/dist/content/templates.js

@@ -183,10 +183,14 @@ ${SEED_SHELF_SECTION}
 > is later dropped, keep the row and mark Priority \`DROPPED\`; if a new one is
 > added mid-flow, append with the next free R-number — do NOT reuse numbers.
 
-## Locked Decisions (D-XX)
-| Decision ID | Decision | Why locked now | Downstream impact |
+## Locked Decisions (LD#hash)
+| Decision Anchor | Decision | Why locked now | Downstream impact |
 |---|---|---|---|
-| D-01 |  |  |  |
+| LD#<sha8> |  |  |  |
+
+> Decision Anchor is \`LD#\` + the first 8 lowercase hex chars of SHA-256 over
+> the normalized \`Decision\` cell (trim, collapse whitespace, lowercase). Downstream
+> design/spec/plan/review artifacts reference these anchors verbatim.
 
 ## In Scope / Out of Scope
 
@@ -308,9 +312,9 @@ ${SEED_SHELF_SECTION}
 | pitfalls-researcher |  |  |  |
 
 ## Architecture Boundaries
-| Component | Responsibility | Owner |
-|---|---|---|
-|  |  |  |
+| Component | Responsibility | Requirement Refs (R#) | Decision Refs (LD#hash) | Owner |
+|---|---|---|---|---|
+|  |  |  |  |  |
 
 ## Architecture Diagram
 
@@ -377,11 +381,11 @@ ${MARKDOWN_CODE_FENCE}
 ### Interaction Edge Case Matrix
 | Edge case | Handled? | Design response | Deferred item (if not handled) |
 |---|---|---|---|
-| double-click | yes/no |  | None / D-XX |
-| nav-away-mid-request | yes/no |  | None / D-XX |
-| 10K-result dataset | yes/no |  | None / D-XX |
-| background-job abandonment | yes/no |  | None / D-XX |
-| zombie connection | yes/no |  | None / D-XX |
+| double-click | yes/no |  | None / LD#hash |
+| nav-away-mid-request | yes/no |  | None / LD#hash |
+| 10K-result dataset | yes/no |  | None / LD#hash |
+| background-job abandonment | yes/no |  | None / LD#hash |
+| zombie connection | yes/no |  | None / LD#hash |
 
 ## Security & Threat Model
 | Boundary | Threat | Mitigation | Owner |
@@ -480,7 +484,7 @@ ${SEED_SHELF_SECTION}
 - Drift from upstream (or \`None\`):
 
 ## Acceptance Criteria
-| ID | Requirement Ref (R#) | Criterion (observable/measurable/falsifiable) | Design Decision Ref |
+| ID | Requirement Ref (R#) | Criterion (observable/measurable/falsifiable) | Design Decision Ref (LD#hash) |
 |---|---|---|---|
 | AC-1 | R1 |  |  |
 
@@ -585,9 +589,9 @@ Execution rule: complete and verify each batch before starting the next batch.
 - TDD checkpoint plan: RED commit/checkpoint -> GREEN commit/checkpoint -> REFACTOR commit/checkpoint (or deferred because: )
 
 ## Locked Decision Coverage
-| Decision ID | Source section | Plan tasks implementing decision | Status |
+| Decision Ref (LD#hash) | Source section | Plan tasks implementing decision | Status |
 |---|---|---|---|
-| D-01 | 02-scope.md > Locked Decisions | T-1 | covered |
+| LD#<sha8> | 02-scope.md > Locked Decisions | T-1 | covered |
 
 ## Risk Assessment
 | Task/Batch | Risk | Likelihood | Impact | Mitigation |
@@ -605,7 +609,7 @@ Execution rule: complete and verify each batch before starting the next batch.
 
 ## No Scope Reduction Language Scan
 - Scanned phrases: \`v1\`, \`for now\`, \`later\`, \`temporary\`, \`placeholder\`, \`mock for now\`, \`hardcoded for now\`, \`will improve later\`.
-- Hits: 0 (required when Locked Decisions section is non-empty).
+- Hits: 0 (required when Locked Decisions section is non-empty; use LD#hash anchors).
 
 ## WAIT_FOR_CONFIRM
 - Status: pending

package/dist/harness-adapters.js

@@ -210,6 +210,8 @@ When in doubt, prefer **non-trivial** — the quick track is opt-in and only saf
 
 Knowledge capture and curation run automatically as part of stage completion
 protocols via the internal \`learnings\` skill — no user-facing command.
+Reusable entries land in \`.cclaw/knowledge.jsonl\` as strict JSONL with
+\`type\`, \`trigger\`, \`action\`, and \`origin_run\` metadata.
 
 **Stage order:** brainstorm > scope > design > spec > plan > tdd > review > ship, then closeout: retro > compound > archive.
 \`/cc-next\` loads the right stage skill automatically and also drives post-ship closeout. Gates must pass before handoff.

package/dist/install.js

@@ -16,6 +16,8 @@ import { stageCompleteScript, startFlowScript, runHookCmdScript, opencodePluginJ
 import { nodeHookRuntimeScript } from "./content/node-hooks.js";
 import { META_SKILL_NAME, usingCclawSkillMarkdown } from "./content/meta-skill.js";
 import { ARTIFACT_TEMPLATES, CURSOR_WORKFLOW_RULE_MDC, RULEBOOK_MARKDOWN, buildRulesJson } from "./content/templates.js";
+import { STATE_CONTRACTS } from "./content/state-contracts.js";
+import { REVIEW_PROMPTS } from "./content/review-prompts.js";
 import { stageSkillFolder, stageSkillMarkdown } from "./content/skills.js";
 import { LANGUAGE_RULE_PACK_DIR, LANGUAGE_RULE_PACK_FILES, LANGUAGE_RULE_PACK_GENERATORS, LEGACY_LANGUAGE_RULE_PACK_FOLDERS } from "./content/utility-skills.js";
 import { RESEARCH_PLAYBOOKS } from "./content/research-playbooks.js";
@@ -357,6 +359,9 @@ async function writeArtifactTemplates(projectRoot) {
     await Promise.all(Object.entries(ARTIFACT_TEMPLATES).map(async ([fileName, content]) => {
         await writeFileSafe(runtimePath(projectRoot, "templates", fileName), content);
     }));
+    await Promise.all(Object.entries(STATE_CONTRACTS).map(async ([fileName, content]) => {
+        await writeFileSafe(runtimePath(projectRoot, "templates", "state-contracts", fileName), content);
+    }));
 }
 async function writeSkills(projectRoot, config) {
     const skillTrack = config?.defaultTrack ?? "standard";
@@ -379,6 +384,9 @@ async function writeSkills(projectRoot, config) {
     for (const [fileName, markdown] of Object.entries(RESEARCH_PLAYBOOKS)) {
         await writeFileSafe(runtimePath(projectRoot, "skills", "research", fileName), markdown);
     }
+    for (const [fileName, markdown] of Object.entries(REVIEW_PROMPTS)) {
+        await writeFileSafe(runtimePath(projectRoot, "skills", "review-prompts", fileName), markdown);
+    }
     // Language rule packs live under .cclaw/rules/lang/<pack>.md. They are opt-in:
     // only the packs listed in config.languageRulePacks are materialised. Any
     // legacy per-language skill folders from v0.7.0 (.cclaw/skills/language-*)

package/package.json

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