cclaw-cli 0.51.12 → 0.51.13

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/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/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.13",
   "description": "Installer-first flow toolkit for coding agents",
   "type": "module",
   "bin": {