cclaw-cli 0.49.0 → 0.51.0

package/dist/constants.d.ts

@@ -10,17 +10,8 @@ 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[];
-/**
- * Evals subtree. Scaffolds the directory layout and a default config.yaml; the
- * structural verifier, rule verifiers, and LLM wiring layer on incrementally.
- * Keeping this separate from the main REQUIRED_DIRS list makes it explicit that
- * the evals runtime is additive and does not affect non-eval cclaw behavior.
- */
-export declare const EVALS_ROOT = ".cclaw/evals";
-export declare const EVALS_CONFIG_PATH = ".cclaw/evals/config.yaml";
-export declare const EVALS_DIRS: readonly [".cclaw/evals", ".cclaw/evals/corpus", ".cclaw/evals/rubrics", ".cclaw/evals/baselines", ".cclaw/evals/reports"];
-export declare const REQUIRED_DIRS: readonly [".cclaw", ".cclaw/commands", ".cclaw/skills", ".cclaw/contexts", ".cclaw/templates", ".cclaw/artifacts", ".cclaw/state", ".cclaw/runs", ".cclaw/rules", ".cclaw/agents", ".cclaw/hooks", ".cclaw/evals", ".cclaw/evals/corpus", ".cclaw/evals/rubrics", ".cclaw/evals/baselines", ".cclaw/evals/reports"];
-export declare const REQUIRED_GITIGNORE_PATTERNS: readonly ["# cclaw generated artifacts", ".cclaw/", "# cclaw evals: user-owned, track in git", "!.cclaw/evals/", "!.cclaw/evals/config.yaml", "!.cclaw/evals/corpus/", "!.cclaw/evals/corpus/**", "!.cclaw/evals/rubrics/", "!.cclaw/evals/rubrics/**", "!.cclaw/evals/baselines/", "!.cclaw/evals/baselines/**", ".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"];
+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_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.
  *
@@ -31,6 +22,4 @@ export declare const REQUIRED_GITIGNORE_PATTERNS: readonly ["# cclaw generated a
  * Keep this map as the single source of truth for generated skill paths.
  */
 export declare const STAGE_TO_SKILL_FOLDER: Record<FlowStage, string>;
-export declare const UTILITY_COMMANDS: readonly ["learn", "next", "ideate", "view", "status", "tree", "diff", "ops", "feature", "tdd-log", "retro", "compound", "archive", "rewind"];
 export declare const SUBAGENT_SKILL_FOLDERS: readonly ["subagent-dev", "parallel-dispatch"];
-export type UtilityCommand = (typeof UTILITY_COMMANDS)[number];

package/dist/constants.js

@@ -52,47 +52,21 @@ export const DEFAULT_HARNESSES = [
     "opencode",
     "codex"
 ];
-/**
- * Evals subtree. Scaffolds the directory layout and a default config.yaml; the
- * structural verifier, rule verifiers, and LLM wiring layer on incrementally.
- * Keeping this separate from the main REQUIRED_DIRS list makes it explicit that
- * the evals runtime is additive and does not affect non-eval cclaw behavior.
- */
-export const EVALS_ROOT = `${RUNTIME_ROOT}/evals`;
-export const EVALS_CONFIG_PATH = `${EVALS_ROOT}/config.yaml`;
-export const EVALS_DIRS = [
-    EVALS_ROOT,
-    `${EVALS_ROOT}/corpus`,
-    `${EVALS_ROOT}/rubrics`,
-    `${EVALS_ROOT}/baselines`,
-    `${EVALS_ROOT}/reports`
-];
 export const REQUIRED_DIRS = [
     RUNTIME_ROOT,
     `${RUNTIME_ROOT}/commands`,
     `${RUNTIME_ROOT}/skills`,
-    `${RUNTIME_ROOT}/contexts`,
     `${RUNTIME_ROOT}/templates`,
     `${RUNTIME_ROOT}/artifacts`,
     `${RUNTIME_ROOT}/state`,
     `${RUNTIME_ROOT}/runs`,
     `${RUNTIME_ROOT}/rules`,
     `${RUNTIME_ROOT}/agents`,
-    `${RUNTIME_ROOT}/hooks`,
-    ...EVALS_DIRS
+    `${RUNTIME_ROOT}/hooks`
 ];
 export const REQUIRED_GITIGNORE_PATTERNS = [
     "# cclaw generated artifacts",
     `${RUNTIME_ROOT}/`,
-    "# cclaw evals: user-owned, track in git",
-    `!${EVALS_ROOT}/`,
-    `!${EVALS_ROOT}/config.yaml`,
-    `!${EVALS_ROOT}/corpus/`,
-    `!${EVALS_ROOT}/corpus/**`,
-    `!${EVALS_ROOT}/rubrics/`,
-    `!${EVALS_ROOT}/rubrics/**`,
-    `!${EVALS_ROOT}/baselines/`,
-    `!${EVALS_ROOT}/baselines/**`,
     ".claude/commands/cc-*.md",
     ".claude/commands/cc.md",
     ".cursor/commands/cc-*.md",
@@ -130,22 +104,6 @@ export const STAGE_TO_SKILL_FOLDER = {
     review: "two-layer-review",
     ship: "shipping-and-handoff"
 };
-export const UTILITY_COMMANDS = [
-    "learn",
-    "next",
-    "ideate",
-    "view",
-    "status",
-    "tree",
-    "diff",
-    "ops",
-    "feature",
-    "tdd-log",
-    "retro",
-    "compound",
-    "archive",
-    "rewind"
-];
 export const SUBAGENT_SKILL_FOLDERS = [
     "subagent-dev",
     "parallel-dispatch"

package/dist/content/closeout-guidance.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Shared post-ship closeout wording.
+ *
+ * Keep closeout chain and ship substate language in one place across command
+ * contracts, skills, and stage/docs surfaces.
+ */
+export declare const CLOSEOUT_CHAIN = "retro -> compound -> archive";
+export declare const CLOSEOUT_SUBSTATE_KEY = "closeout.shipSubstate";
+export declare function closeoutChainInline(): string;
+export declare function closeoutSubstateInline(): string;
+export declare function closeoutNextCommandGuidance(): string;
+export declare function closeoutSubstateProtocolBullets(): string;
+export declare function closeoutFlowMapSentence(): string;
+export declare function closeoutProtocolBehaviorSentence(): string;

package/dist/content/closeout-guidance.js

@@ -0,0 +1,42 @@
+/**
+ * Shared post-ship closeout wording.
+ *
+ * Keep closeout chain and ship substate language in one place across command
+ * contracts, skills, and stage/docs surfaces.
+ */
+export const CLOSEOUT_CHAIN = "retro -> compound -> archive";
+export const CLOSEOUT_SUBSTATE_KEY = "closeout.shipSubstate";
+export function closeoutChainInline() {
+    return `\`${CLOSEOUT_CHAIN}\``;
+}
+export function closeoutSubstateInline() {
+    return `\`${CLOSEOUT_SUBSTATE_KEY}\``;
+}
+export function closeoutNextCommandGuidance() {
+    return `After ship completes, the closeout chain ${closeoutChainInline()} runs automatically, driven by ${closeoutSubstateInline()}. Continue through \`/cc-next\`; do not branch into \`ce:compound\`, a separate operations router, or a one-off closeout command. Ralph Loop may be mentioned only as tdd carry-forward context when it explains the next \`/cc-next\` move; it is not part of compound/archive routing.`;
+}
+export function closeoutSubstateProtocolBullets() {
+    return `When \`currentStage === "ship"\`, route by **${closeoutSubstateInline()}**:
+  - \`"idle"\` or missing -> set ${closeoutSubstateInline()} = \`"retro_review"\`, then
+    execute the in-stage retro protocol (draft + one structured accept/edit/skip ask).
+  - \`"retro_review"\` -> continue the retro protocol (re-ask the structured
+    question; the draft already exists — do not regenerate it).
+  - \`"compound_review"\` -> execute the in-stage compound closeout scan (not \`ce:compound\`):
+    read \`.cclaw/state/compound-readiness.json\` plus the relevant tail of
+    \`.cclaw/knowledge.jsonl\`, assess overlap before adding duplicate knowledge,
+    separate bug-track learnings (turn into rules/tests/remediation) from
+    knowledge-track learnings (durable project/process guidance), and use
+    lightweight \`supersedes\` / \`superseded_by\` fields when refreshing stale or
+    partially replaced entries. Optionally ask whether to scan Cursor/Claude/Codex
+    session transcripts for matching historical learnings; only do it after opt-in.
+    Ask **one** structured question (apply / skip) per candidate cluster or a
+    single accept-all / skip choice, then advance substate.
+  - \`"ready_to_archive"\` -> run \`cclaw archive\` (or \`cclaw archive --name=<slug>\`) and reset state.
+  - \`"archived"\` (transient) -> report "run archived" and stop.`;
+}
+export function closeoutFlowMapSentence() {
+    return `The first stage names are the critical path. \`retro\`, \`compound\`, and \`archive\` are post-ship closeout substates under ${closeoutSubstateInline()}, not separate stage schemas or commands. Continue them with \`/cc-next\`; do not route compound closeout through \`ce:compound\`.`;
+}
+export function closeoutProtocolBehaviorSentence() {
+    return `Keep decision, completion, and preamble discipline inline: ask only decision-changing questions, verify gates before advancing, and keep context compact. After \`ship\`, keep using \`/cc-next\` through ${closeoutChainInline()}; do not route normal closeout through \`ce:compound\` or a separate operations command. In compound closeout, assess overlap before appending knowledge: refresh recurring bug-track learnings as actionable rules/tests, keep knowledge-track learnings as durable process/project guidance, and mark outdated entries with lightweight \`supersedes\` / \`superseded_by\` fields instead of building a new doc system.`;
+}

package/dist/content/core-agents.js

@@ -13,6 +13,38 @@ function yamlScalarString(value) {
 function yamlFlowSequence(values) {
     return JSON.stringify(values);
 }
+function formattedAgentsForStages(stages) {
+    const summary = stageDelegationSummary("standard");
+    const merged = [];
+    for (const stage of stages) {
+        const row = summary.find((item) => item.stage === stage);
+        if (!row)
+            continue;
+        for (const agent of row.primaryAgents) {
+            if (!merged.includes(agent)) {
+                merged.push(agent);
+            }
+        }
+    }
+    return merged.length > 0 ? merged.join(", ") : "none";
+}
+function activationModeSummary() {
+    const summary = stageDelegationSummary("standard");
+    const mandatory = new Set();
+    const proactive = new Set();
+    for (const row of summary) {
+        for (const agent of row.mandatoryAgents) {
+            mandatory.add(agent);
+        }
+        for (const agent of row.proactiveAgents) {
+            proactive.add(agent);
+        }
+    }
+    return {
+        mandatory: [...mandatory].join(", "),
+        proactive: [...proactive].join(", ")
+    };
+}
 /**
  * Canonical specialist roster (core-5) materialized under `.cclaw/agents/`.
  *
@@ -135,6 +167,7 @@ export const CCLAW_AGENTS = [
         ].join("\n")
     }
 ];
+import { stageDelegationSummary } from "./stage-schema.js";
 import { enhancedAgentBody } from "./subagents.js";
 /**
  * Render a complete cclaw agent markdown file (YAML frontmatter + body).
@@ -175,14 +208,20 @@ ${taskDelegation}
  * Markdown table mapping cclaw stage entry points to specialist agents.
  */
 export function agentRoutingTable() {
+    const brainstormPrimary = formattedAgentsForStages(["brainstorm"]);
+    const scopeDesignPlanPrimary = formattedAgentsForStages(["scope", "design", "plan"]);
+    const specPrimary = formattedAgentsForStages(["spec"]);
+    const tddPrimary = formattedAgentsForStages(["tdd"]);
+    const reviewPrimary = formattedAgentsForStages(["review"]);
+    const shipPrimary = formattedAgentsForStages(["ship"]);
     return `| Stage Entry | Primary Agent(s) | Supporting guidance |
 |---|---|---|
-| Brainstorm (start with \`/cc <idea>\`) | planner | Run in-thread research playbooks: \`research/repo-scan.md\`, \`research/learnings-lookup.md\` |
-| Scope / Design / Plan (via \`/cc-next\`) | planner | Use \`research/git-history.md\` (scope) and \`research/framework-docs-lookup.md\` + \`research/best-practices-lookup.md\` (design) as needed |
-| Spec (via \`/cc-next\`) | reviewer | planner (if ambiguity or conflicts remain) |
-| TDD (via \`/cc-next\`) | test-author | doc-updater on public behavior/config changes |
-| Review (via \`/cc-next\`) | reviewer, security-reviewer | conditional second reviewer for high blast-radius diffs |
-| Ship (via \`/cc-next\`) | doc-updater | security-reviewer when release risk is elevated |
+| Brainstorm (start with \`/cc <idea>\`) | ${brainstormPrimary} | Run in-thread research playbooks: \`research/repo-scan.md\`, \`research/learnings-lookup.md\` |
+| Scope / Design / Plan (via \`/cc-next\`) | ${scopeDesignPlanPrimary} | Use \`research/git-history.md\` (scope) and \`research/framework-docs-lookup.md\` + \`research/best-practices-lookup.md\` (design) as needed |
+| Spec (via \`/cc-next\`) | ${specPrimary} | planner (if ambiguity or conflicts remain) |
+| TDD (via \`/cc-next\`) | ${tddPrimary} | doc-updater on public behavior/config changes |
+| Review (via \`/cc-next\`) | ${reviewPrimary} | conditional second reviewer for high blast-radius diffs |
+| Ship (via \`/cc-next\`) | ${shipPrimary} | security-reviewer when release risk is elevated |
 `;
 }
 /**
@@ -218,9 +257,12 @@ Research work is no longer modeled as standalone personas. Use in-thread playboo
 
 ### Activation modes
 
-- **Mandatory:** planner (scope/design/plan), reviewer + security-reviewer (review), test-author (tdd), doc-updater (ship).
-- **Proactive:** planner on ambiguity, security-reviewer on trust-boundary movement outside review, doc-updater on behavior/config drift.
-- **On-demand:** none in the core-5 roster; research playbooks are in-thread procedures.
+${(() => {
+        const mode = activationModeSummary();
+        return `- **Mandatory:** ${mode.mandatory}.
+- **Proactive:** ${mode.proactive}.
+- **On-demand:** none in the core-5 roster; research playbooks are in-thread procedures.`;
+    })()}
 
 ### Cost-aware routing
 

package/dist/content/decision-protocol.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Shared wording blocks for Decision Protocol + structured ask fallback.
+ *
+ * Keep stage/utility prompt surfaces consistent and reduce wording drift.
+ */
+export declare const STRUCTURED_ASK_TOOL_LIST_GENERIC = "`AskUserQuestion` / `AskQuestion` / `question` / `request_user_input`";
+export declare const STRUCTURED_ASK_TOOL_LIST_REVIEW = "`AskUserQuestion` on Claude, `AskQuestion` on Cursor, `question` on OpenCode with `permission.question: \"allow\"`, `request_user_input` on Codex in Plan/Collaboration mode";
+export declare const STRUCTURED_ASK_TOOL_LIST_IDEATE = "`AskUserQuestion` on Claude, `AskQuestion` on Cursor, `question` on OpenCode when `permission.question: \"allow\"` is set, `request_user_input` on Codex in Plan / Collaboration mode";
+export declare function structuredAskFallbackSentence(toolList?: string): string;
+export declare function decisionProtocolInstruction(subject: string, optionsClause: string, recommendationClause: string, toolList?: string): string;
+export declare function structuredAskSingleChoiceInstruction(subject: string, choicesClause: string, toolList?: string): string;
+export declare function ideateStructuredAskToolsWithFallback(): string;

package/dist/content/decision-protocol.js

@@ -0,0 +1,20 @@
+/**
+ * Shared wording blocks for Decision Protocol + structured ask fallback.
+ *
+ * Keep stage/utility prompt surfaces consistent and reduce wording drift.
+ */
+export const STRUCTURED_ASK_TOOL_LIST_GENERIC = "\`AskUserQuestion\` / \`AskQuestion\` / \`question\` / \`request_user_input\`";
+export const STRUCTURED_ASK_TOOL_LIST_REVIEW = "\`AskUserQuestion\` on Claude, \`AskQuestion\` on Cursor, \`question\` on OpenCode with \`permission.question: \"allow\"\`, \`request_user_input\` on Codex in Plan/Collaboration mode";
+export const STRUCTURED_ASK_TOOL_LIST_IDEATE = "\`AskUserQuestion\` on Claude, \`AskQuestion\` on Cursor, \`question\` on OpenCode when \`permission.question: \"allow\"\` is set, \`request_user_input\` on Codex in Plan / Collaboration mode";
+export function structuredAskFallbackSentence(toolList = STRUCTURED_ASK_TOOL_LIST_GENERIC) {
+    return `If the harness's native structured-ask tool is available (${toolList}), send exactly ONE question per call, validate fields against the runtime schema, and on schema error immediately fall back to a plain-text lettered list instead of retrying guessed payloads.`;
+}
+export function decisionProtocolInstruction(subject, optionsClause, recommendationClause, toolList = STRUCTURED_ASK_TOOL_LIST_GENERIC) {
+    return `For ${subject}: use the Decision Protocol — ${optionsClause}. Do NOT use a numeric Completeness rubric; ${recommendationClause}. ${structuredAskFallbackSentence(toolList)}`;
+}
+export function structuredAskSingleChoiceInstruction(subject, choicesClause, toolList = STRUCTURED_ASK_TOOL_LIST_GENERIC) {
+    return `For ${subject}: use the native structured-ask tool (${toolList}) only if runtime schema is confirmed; otherwise collect ${choicesClause} with a plain-text single-choice prompt.`;
+}
+export function ideateStructuredAskToolsWithFallback() {
+    return `${STRUCTURED_ASK_TOOL_LIST_IDEATE}; fall back to a plain-text lettered list when the tool is hidden or errors`;
+}

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

@@ -1,2 +1 @@
-export declare function diffCommandContract(): string;
-export declare function diffCommandSkillMarkdown(): string;
+export declare function diffSubcommandMarkdown(): string;

package/dist/content/diff-command.js

@@ -1,126 +1,40 @@
 import { RUNTIME_ROOT } from "../constants.js";
-const DIFF_SKILL_FOLDER = "flow-diff";
-const DIFF_SKILL_NAME = "flow-diff";
 function flowStatePath() {
     return `${RUNTIME_ROOT}/state/flow-state.json`;
 }
-function snapshotPath() {
-    return `${RUNTIME_ROOT}/state/flow-state.snapshot.json`;
-}
 function delegationLogPath() {
     return `${RUNTIME_ROOT}/state/delegation-log.json`;
 }
 function retroArtifactPath() {
     return `${RUNTIME_ROOT}/artifacts/09-retro.md`;
 }
-export function diffCommandContract() {
+export function diffSubcommandMarkdown() {
     return `# /cc-view diff
 
-## Purpose
-
-Show a visual before/after diff map for flow-state progression. Covers the core
-stage/gate transitions plus:
-
-- ship **closeout substate** transitions (\`retro_review\` → \`compound_review\` → \`ready_to_archive\`),
-- delegation **fulfillmentMode** transitions per mandatory agent,
-- appearance or removal of the retro artifact \`09-retro.md\`.
-
-## HARD-GATE
-
-- Compare against \`${snapshotPath()}\` first; do not overwrite baseline before rendering.
-- If no snapshot exists, initialize baseline and report "baseline created" explicitly.
-
-## Algorithm
-
-1. Read current state from \`${flowStatePath()}\` (including \`closeout\`).
-2. Read current delegation log from \`${delegationLogPath()}\` (if missing treat as empty).
-3. Read baseline from \`${snapshotPath()}\` (if missing -> create baseline from
-   current state **plus** a copy of the current delegation log; report
-   \`flow diff baseline created\` and stop).
-4. Compute deltas:
-   - stage transition (\`from -> to\`),
-   - completed stage additions/removals,
-   - skipped stage additions/removals,
-   - stale stage additions/removals,
-   - current-stage gate \`passed\` and \`blocked\` changes,
-   - \`closeout.shipSubstate\` transition (\`from -> to\`),
-   - \`closeout.retroDraftedAt\` / \`retroAcceptedAt\` / \`retroSkipped\` flips,
-   - \`closeout.compoundPromoted\` / \`compoundSkipped\` flips,
-   - per-agent \`fulfillmentMode\` transitions from the baseline delegation log,
-   - appearance (\`+\`) or disappearance (\`-\`) of \`${retroArtifactPath()}\`.
-5. Render a compact diff map (added \`+\`, removed \`-\`, changed \`->\`).
-6. Persist current state back to \`${snapshotPath()}\` as new baseline with
-   \`capturedAt\` and an embedded \`delegations\` projection
-   (\`{ agent, status, fulfillmentMode }[]\`) so fulfillmentMode transitions are
-   computable on the next run.
-
-## Diff Map Format
-
-\`\`\`
-cclaw flow diff
-  stage: design -> spec
-  completed: +design
-  stale: -design
-  gates(spec): +spec_contract_complete  -spec_open_questions_closed
-  blocked(spec): +spec_trace_matrix_missing
-  closeout: idle -> retro_review
-  retro: +drafted (09-retro.md appeared)
-  delegations:
-    - reviewer: scheduled -> completed (mode=generic-dispatch)
-    - test-author: mode=? -> role-switch (evidenceRefs=2)
-\`\`\`
-
-- The \`closeout:\` line is omitted when \`shipSubstate\` is unchanged.
-- The \`delegations:\` block is omitted when no agent changed status or mode.
-- The \`retro:\` line is emitted only on artifact appearance/removal or on a
-  \`retroAcceptedAt\` / \`retroSkipped\` flip.
-
-## Primary skill
-
-**${RUNTIME_ROOT}/skills/${DIFF_SKILL_FOLDER}/SKILL.md**
-`;
-}
-export function diffCommandSkillMarkdown() {
-    return `---
-name: ${DIFF_SKILL_NAME}
-description: "Compare current flow-state against saved snapshot and render gate/stage/closeout/delegation deltas."
----
-
-# /cc-view diff
-
 ## HARD-GATE
 
-Never lose baseline visibility: render deltas before writing a new snapshot.
+Never mutate state from \`/cc-view diff\`. It is a read-only inspection command.
 
 ## Protocol
 
 1. Read \`${flowStatePath()}\`.
 2. Read \`${delegationLogPath()}\` (missing → treat as empty list).
-3. Read \`${snapshotPath()}\`.
-4. If snapshot missing:
-   - write baseline snapshot from current state **plus** a
-     \`delegations\` projection (\`{ agent, status, fulfillmentMode }[]\`),
-   - print \`flow diff baseline created\`,
-   - stop.
-5. Build deltas for:
+3. Inspect git diff for \`${flowStatePath()}\`, \`${delegationLogPath()}\`, and \`${retroArtifactPath()}\`.
+4. Build deltas for:
    - stage, completed/skipped/stale sets,
    - current-stage gate arrays (\`passed\`, \`blocked\`),
    - \`closeout.shipSubstate\` transitions (\`from -> to\`),
    - \`closeout.retroDraftedAt\` / \`retroAcceptedAt\` / \`retroSkipped\` flips,
    - \`closeout.compoundPromoted\` / \`compoundSkipped\` / \`compoundCompletedAt\` flips,
-   - per-agent \`fulfillmentMode\` transitions by matching baseline delegations
-     against current delegations on \`agent\` + latest entry,
+   - per-agent \`fulfillmentMode\` changes visible in delegation diffs,
    - appearance or removal of \`${retroArtifactPath()}\` on disk.
+5. If git has no baseline for these files, print \`baseline: unavailable (read-only mode)\`.
 6. Print a compact diff map with explicit \`+\`, \`-\`, and \`->\` markers.
-7. Write updated snapshot with:
-   - \`capturedAt\` (ISO),
-   - \`state\` (full current flow-state object),
-   - \`delegations\` projection from the current log.
 
 ## Validation
 
-- Diff output must be deterministic for identical states ("no changes").
-- Snapshot file stays valid JSON after every run.
+- Diff output must be deterministic for identical states ("no visible changes").
+- The command must not create or update any \`.cclaw/state/*.snapshot*\` file.
 - Do not suppress removed values; removals are first-class evidence.
 - Closeout diff lines must use the same \`shipSubstate\` vocabulary as the
   state machine (\`idle\` / \`retro_review\` / \`compound_review\` /

package/dist/content/examples.d.ts

@@ -1,18 +1,12 @@
 import type { FlowStage } from "../types.js";
 export declare function stageGoodBadExamples(stage: FlowStage): string;
-export declare const STAGE_EXAMPLES_REFERENCE_DIR = "references/stages";
-export declare function stageExamplesReferencePath(stage: FlowStage): string;
 /**
- * Returns the full example artifact body as a standalone reference markdown
- * file. Materialized under .cclaw/references/stages/<stage>-examples.md so
- * the always-rendered skill body can link instead of inlining.
+ * Returns the full example artifact body for tests and internal quality checks.
+ * Generated user projects keep only short inline shape cues.
  */
-export declare function stageExamplesReferenceMarkdown(stage: FlowStage): string | null;
+export declare function stageFullArtifactExampleMarkdown(stage: FlowStage): string | null;
 /**
- * Returns the short inline pointer rendered directly inside the stage skill.
- * Replaces the previous always-inline ~50-100 line fenced block and
- * delivers true progressive disclosure: the full example lives in a
- * reference file loaded on demand.
+ * Returns short inline shape cues rendered directly inside the stage skill.
  */
 export declare function stageExamples(stage: FlowStage): string;
 export type ExampleDomain = "web" | "cli" | "library" | "data-pipeline";

package/dist/content/examples.js

@@ -393,16 +393,16 @@ Execution rule: complete and verify each batch before starting the next batch.
 | R-2 | Important | performance | \`feedStore.merge()\` does full-array scan on every SSE event; O(n) per event where n is feed length. | open |
 | R-3 | Suggestion | architecture | SSE reconnect logic duplicated across \`useNotifications\` and \`usePresence\`; extract shared hook. | open |
 
-## Review Army Contract
+## Review Findings Contract
 
 - See \`07-review-army.json\`
 - Reconciliation summary: 1 duplicate collapsed (R-1 reported by reviewer and security-reviewer), 0 conflicts
 
-## Review Readiness Dashboard
+## Review Readiness Snapshot
 
 - Layer 1 complete: yes (3/3 criteria)
 - Layer 2 complete: yes (5 sections reviewed)
-- Review army schema valid: yes
+- Review findings schema valid: yes
 - Open critical blockers: 1 (R-1)
 - Ship recommendation: BLOCKED until R-1 resolved
 
@@ -613,16 +613,11 @@ export function stageGoodBadExamples(stage) {
     });
     return blocks.join("\n");
 }
-export const STAGE_EXAMPLES_REFERENCE_DIR = "references/stages";
-export function stageExamplesReferencePath(stage) {
-    return `.cclaw/${STAGE_EXAMPLES_REFERENCE_DIR}/${stage}-examples.md`;
-}
 /**
- * Returns the full example artifact body as a standalone reference markdown
- * file. Materialized under .cclaw/references/stages/<stage>-examples.md so
- * the always-rendered skill body can link instead of inlining.
+ * Returns the full example artifact body for tests and internal quality checks.
+ * Generated user projects keep only short inline shape cues.
  */
-export function stageExamplesReferenceMarkdown(stage) {
+export function stageFullArtifactExampleMarkdown(stage) {
     const examples = STAGE_EXAMPLES[stage];
     if (!examples)
         return null;
@@ -630,12 +625,12 @@ export function stageExamplesReferenceMarkdown(stage) {
         `---`,
         `stage: ${stage}`,
         `name: ${stage}-stage-examples`,
-        `description: "Full sample artifact for the ${stage} stage. Loaded only when an agent explicitly needs a complete example; the stage skill links here rather than inlining."`,
+        `description: "Full sample artifact for the ${stage} stage."`,
         `---`,
         "",
         `# ${stage} stage — full artifact sample`,
         "",
-        `This file is linked from \`.cclaw/skills/<${stage}-stage>/SKILL.md\` under **Examples → See also**. The sample uses H2 headings that mirror the artifact a cclaw session must produce, so the markdown is wrapped in a fence to avoid collapsing into the outline.`,
+        `The sample uses H2 headings that mirror the artifact a cclaw session must produce, so the markdown is wrapped in a fence to avoid collapsing into the outline.`,
         "",
         "```markdown",
         examples,
@@ -644,10 +639,7 @@ export function stageExamplesReferenceMarkdown(stage) {
     ].join("\n");
 }
 /**
- * Returns the short inline pointer rendered directly inside the stage skill.
- * Replaces the previous always-inline ~50-100 line fenced block and
- * delivers true progressive disclosure: the full example lives in a
- * reference file loaded on demand.
+ * Returns short inline shape cues rendered directly inside the stage skill.
  */
 export function stageExamples(stage) {
     const examples = STAGE_EXAMPLES[stage];
@@ -656,9 +648,7 @@ export function stageExamples(stage) {
     return [
         "## Examples",
         "",
-        `Full artifact sample for this stage lives at \`${stageExamplesReferencePath(stage)}\`. Open it when you need a complete reference; do NOT paste the example into the artifact verbatim — it is a shape guide, not a template.`,
-        "",
-        "Summary of what the reference covers:",
+        "Shape cues to follow; do not paste these headings verbatim unless they match the work:",
         ...exampleSummaryBullets(stage),
         ""
     ].join("\n");

package/dist/content/hook-events.js

@@ -14,8 +14,8 @@ const OPENCODE_SEMANTIC_COVERAGE = {
     pre_tool_prompt_guard: "plugin tool.execute.before -> prompt-guard",
     pre_tool_workflow_guard: "plugin tool.execute.before -> workflow-guard",
     post_tool_context_monitor: "plugin tool.execute.after -> context-monitor",
-    stop_checkpoint: "plugin session.idle -> stop-checkpoint",
-    precompact_digest: "plugin session.compacted -> pre-compact"
+    stop_handoff: "plugin session.idle -> stop-handoff",
+    precompact_compat: "plugin session.compacted -> pre-compact"
 };
 /**
  * Public semantic coverage map derived from `HOOK_MANIFEST` for

package/dist/content/hook-inline-snippets.d.ts

@@ -45,8 +45,11 @@
  * - `countArchivedRunsInline` counts immediate subdirectories of
  *   `<root>/.cclaw/runs/` so both the hook and the CLI see the same
  *   `archivedRunsCount` for the small-project relaxation.
+ * - `formatCompoundReadinessLineInline` mirrors the one-line summary shape
+ *   used by `src/internal/compound-readiness.ts::formatCompoundReadinessLine`
+ *   so session-start and internal CLI command stay wording-compatible.
  */
-export declare const HOOK_INLINE_SHARED_HELPERS = "\nfunction normalizeCompoundLastUpdatedAt(date) {\n  return date.toISOString().replace(/\\.\\d{3}Z$/u, \"Z\");\n}\n\n// Count archived runs as sub-directories under `.cclaw/runs/`. Missing\n// dir returns 0; unexpected errors return undefined so the caller can\n// skip the small-project relaxation rather than guess.\nasync function countArchivedRunsInline(root) {\n  const dir = path.join(root, RUNTIME_ROOT, \"runs\");\n  try {\n    const entries = await fs.readdir(dir, { withFileTypes: true });\n    return entries.filter((entry) => entry.isDirectory()).length;\n  } catch (error) {\n    const code = error && typeof error === \"object\" && \"code\" in error ? error.code : null;\n    if (code === \"ENOENT\") return 0;\n    return undefined;\n  }\n}\n";
+export declare const HOOK_INLINE_SHARED_HELPERS = "\nfunction normalizeCompoundLastUpdatedAt(date) {\n  return date.toISOString().replace(/\\.\\d{3}Z$/u, \"Z\");\n}\n\n// Count archived runs as sub-directories under `.cclaw/runs/`. Missing\n// dir returns 0; unexpected errors return undefined so the caller can\n// skip the small-project relaxation rather than guess.\nasync function countArchivedRunsInline(root) {\n  const dir = path.join(root, RUNTIME_ROOT, \"runs\");\n  try {\n    const entries = await fs.readdir(dir, { withFileTypes: true });\n    return entries.filter((entry) => entry.isDirectory()).length;\n  } catch (error) {\n    const code = error && typeof error === \"object\" && \"code\" in error ? error.code : null;\n    if (code === \"ENOENT\") return 0;\n    return undefined;\n  }\n}\n\nfunction formatCompoundReadinessLineInline(readiness) {\n  if (!readiness || typeof readiness !== \"object\") {\n    return \"\";\n  }\n  const ready = Array.isArray(readiness.ready) ? readiness.ready : [];\n  const readyCount =\n    typeof readiness.readyCount === \"number\" && Number.isFinite(readiness.readyCount)\n      ? Math.trunc(readiness.readyCount)\n      : ready.length;\n  const clusterCount =\n    typeof readiness.clusterCount === \"number\" && Number.isFinite(readiness.clusterCount)\n      ? Math.trunc(readiness.clusterCount)\n      : 0;\n  const threshold =\n    typeof readiness.threshold === \"number\" && Number.isFinite(readiness.threshold)\n      ? Math.trunc(readiness.threshold)\n      : COMPOUND_RECURRENCE_THRESHOLD;\n  if (readyCount === 0) {\n    return \"Compound readiness: no candidates (clusters=\" +\n      String(clusterCount) + \", threshold=\" + String(threshold) + \")\";\n  }\n  const critical = ready.filter(\n    (entry) => entry && typeof entry === \"object\" && entry.severity === \"critical\"\n  ).length;\n  const criticalSuffix = critical > 0 ? \" (critical=\" + String(critical) + \")\" : \"\";\n  return \"Compound readiness: clusters=\" + String(clusterCount) +\n    \", ready=\" + String(readyCount) + criticalSuffix;\n}\n";
 /**
  * Inline mirror of `src/knowledge-store.ts::computeCompoundReadiness`.
  *
@@ -67,7 +70,7 @@ export declare const HOOK_INLINE_SHARED_HELPERS = "\nfunction normalizeCompoundL
  * `SMALL_PROJECT_RECURRENCE_THRESHOLD`, `COMPOUND_RECURRENCE_THRESHOLD`,
  * and `HOOK_INLINE_SHARED_HELPERS` being in the same runtime scope.
  */
-export declare const COMPOUND_READINESS_INLINE_SOURCE = "\nasync function computeCompoundReadinessInline(root, options) {\n  const filePath = path.join(root, RUNTIME_ROOT, \"knowledge.jsonl\");\n  // Caller may supply pre-read raw to avoid double-reading knowledge.jsonl.\n  const raw = typeof (options && options.prereadRaw) === \"string\"\n    ? options.prereadRaw\n    : await readTextFile(filePath, \"\");\n  const baseThresholdRaw = options && options.threshold;\n  const baseThreshold = Number.isInteger(baseThresholdRaw) && baseThresholdRaw >= 1\n    ? baseThresholdRaw\n    : COMPOUND_RECURRENCE_THRESHOLD;\n  const archivedRunsCount =\n    typeof (options && options.archivedRunsCount) === \"number\" &&\n    Number.isFinite(options.archivedRunsCount) &&\n    options.archivedRunsCount >= 0\n      ? Math.floor(options.archivedRunsCount)\n      : undefined;\n  const smallProjectRelaxationApplied =\n    archivedRunsCount !== undefined &&\n    archivedRunsCount < SMALL_PROJECT_ARCHIVE_RUNS_THRESHOLD &&\n    baseThreshold > SMALL_PROJECT_RECURRENCE_THRESHOLD;\n  const threshold = smallProjectRelaxationApplied\n    ? SMALL_PROJECT_RECURRENCE_THRESHOLD\n    : baseThreshold;\n  const maxReady = Number.isInteger(options && options.maxReady) && options.maxReady >= 1\n    ? options.maxReady\n    : 10;\n  const normalize = (value) => String(value == null ? \"\" : value).trim().replace(/\\s+/gu, \" \").toLowerCase();\n  const severityWeight = (sev) => {\n    if (sev === \"critical\") return 3;\n    if (sev === \"important\") return 2;\n    if (sev === \"suggestion\") return 1;\n    return 0;\n  };\n  const buckets = new Map();\n  for (const rawLine of raw.split(/\\r?\\n/gu)) {\n    const line = rawLine.trim();\n    if (line.length === 0) continue;\n    let row;\n    try { row = JSON.parse(line); } catch { continue; }\n    if (!row || typeof row !== \"object\" || Array.isArray(row)) continue;\n    if (row.maturity === \"lifted-to-enforcement\") continue;\n    const type = typeof row.type === \"string\" ? row.type : \"\";\n    const trigger = typeof row.trigger === \"string\" ? row.trigger : \"\";\n    const action = typeof row.action === \"string\" ? row.action : \"\";\n    if (type.length === 0 || trigger.length === 0 || action.length === 0) continue;\n    const key = type + \"||\" + normalize(trigger) + \"||\" + normalize(action);\n    const frequency = Number.isInteger(row.frequency) && row.frequency > 0 ? Math.floor(row.frequency) : 1;\n    const lastSeen = typeof row.last_seen_ts === \"string\" ? row.last_seen_ts : \"\";\n    let bucket = buckets.get(key);\n    if (!bucket) {\n      bucket = {\n        trigger,\n        action,\n        recurrence: frequency,\n        entryCount: 1,\n        severity: typeof row.severity === \"string\" ? row.severity : undefined,\n        lastSeenTs: lastSeen,\n        types: new Set([type]),\n        maturity: new Set([typeof row.maturity === \"string\" ? row.maturity : \"raw\"])\n      };\n      buckets.set(key, bucket);\n      continue;\n    }\n    bucket.recurrence += frequency;\n    bucket.entryCount += 1;\n    bucket.types.add(type);\n    bucket.maturity.add(typeof row.maturity === \"string\" ? row.maturity : \"raw\");\n    if (row.severity === \"critical\") {\n      bucket.severity = \"critical\";\n    } else if (row.severity === \"important\" && bucket.severity !== \"critical\") {\n      bucket.severity = \"important\";\n    }\n    if (lastSeen && Date.parse(lastSeen) > Date.parse(bucket.lastSeenTs || \"0\")) {\n      bucket.lastSeenTs = lastSeen;\n    }\n  }\n  const ready = [];\n  for (const bucket of buckets.values()) {\n    const criticalOverride = bucket.severity === \"critical\";\n    const meetsRecurrence = bucket.recurrence >= threshold;\n    if (!criticalOverride && !meetsRecurrence) continue;\n    ready.push({\n      trigger: bucket.trigger,\n      action: bucket.action,\n      recurrence: bucket.recurrence,\n      entryCount: bucket.entryCount,\n      qualification: criticalOverride && !meetsRecurrence ? \"critical_override\" : \"recurrence\",\n      ...(bucket.severity ? { severity: bucket.severity } : {}),\n      lastSeenTs: bucket.lastSeenTs,\n      types: Array.from(bucket.types).sort(),\n      maturity: Array.from(bucket.maturity).sort()\n    });\n  }\n  ready.sort((a, b) => {\n    const sevDiff = severityWeight(b.severity) - severityWeight(a.severity);\n    if (sevDiff !== 0) return sevDiff;\n    if (b.recurrence !== a.recurrence) return b.recurrence - a.recurrence;\n    const recencyDiff = Date.parse(b.lastSeenTs || \"0\") - Date.parse(a.lastSeenTs || \"0\");\n    if (!Number.isNaN(recencyDiff) && recencyDiff !== 0) return recencyDiff;\n    return String(a.trigger).localeCompare(String(b.trigger));\n  });\n  return {\n    schemaVersion: 2,\n    threshold,\n    baseThreshold,\n    ...(archivedRunsCount !== undefined ? { archivedRunsCount } : {}),\n    smallProjectRelaxationApplied,\n    clusterCount: buckets.size,\n    readyCount: ready.length,\n    ready: ready.slice(0, maxReady),\n    lastUpdatedAt: normalizeCompoundLastUpdatedAt(new Date())\n  };\n}\n";
+export declare const COMPOUND_READINESS_INLINE_SOURCE = "\nasync function computeCompoundReadinessInline(root, options) {\n  const filePath = path.join(root, RUNTIME_ROOT, \"knowledge.jsonl\");\n  // Caller may supply pre-read raw to avoid double-reading knowledge.jsonl.\n  const raw = typeof (options && options.prereadRaw) === \"string\"\n    ? options.prereadRaw\n    : await readTextFile(filePath, \"\");\n  const baseThresholdRaw = options && options.threshold;\n  const baseThreshold = Number.isInteger(baseThresholdRaw) && baseThresholdRaw >= 1\n    ? baseThresholdRaw\n    : COMPOUND_RECURRENCE_THRESHOLD;\n  const archivedRunsCount =\n    typeof (options && options.archivedRunsCount) === \"number\" &&\n    Number.isFinite(options.archivedRunsCount) &&\n    options.archivedRunsCount >= 0\n      ? Math.floor(options.archivedRunsCount)\n      : undefined;\n  const smallProjectRelaxationApplied =\n    archivedRunsCount !== undefined &&\n    archivedRunsCount < SMALL_PROJECT_ARCHIVE_RUNS_THRESHOLD &&\n    baseThreshold > SMALL_PROJECT_RECURRENCE_THRESHOLD;\n  const threshold = smallProjectRelaxationApplied\n    ? SMALL_PROJECT_RECURRENCE_THRESHOLD\n    : baseThreshold;\n  const maxReady = Number.isInteger(options && options.maxReady) && options.maxReady >= 1\n    ? options.maxReady\n    : 10;\n  const normalize = (value) => String(value == null ? \"\" : value).trim().replace(/\\s+/gu, \" \").toLowerCase();\n  const severityWeight = (sev) => {\n    if (sev === \"critical\") return 3;\n    if (sev === \"important\") return 2;\n    if (sev === \"suggestion\") return 1;\n    return 0;\n  };\n  const buckets = new Map();\n  for (const rawLine of raw.split(/\\r?\\n/gu)) {\n    const line = rawLine.trim();\n    if (line.length === 0) continue;\n    let row;\n    try { row = JSON.parse(line); } catch { continue; }\n    if (!row || typeof row !== \"object\" || Array.isArray(row)) continue;\n    if (row.maturity === \"lifted-to-enforcement\" || typeof row.superseded_by === \"string\") continue;\n    const type = typeof row.type === \"string\" ? row.type : \"\";\n    const trigger = typeof row.trigger === \"string\" ? row.trigger : \"\";\n    const action = typeof row.action === \"string\" ? row.action : \"\";\n    if (type.length === 0 || trigger.length === 0 || action.length === 0) continue;\n    const key = type + \"||\" + normalize(trigger) + \"||\" + normalize(action);\n    const frequency = Number.isInteger(row.frequency) && row.frequency > 0 ? Math.floor(row.frequency) : 1;\n    const lastSeen = typeof row.last_seen_ts === \"string\" ? row.last_seen_ts : \"\";\n    let bucket = buckets.get(key);\n    if (!bucket) {\n      bucket = {\n        trigger,\n        action,\n        recurrence: frequency,\n        entryCount: 1,\n        severity: typeof row.severity === \"string\" ? row.severity : undefined,\n        lastSeenTs: lastSeen,\n        types: new Set([type]),\n        maturity: new Set([typeof row.maturity === \"string\" ? row.maturity : \"raw\"])\n      };\n      buckets.set(key, bucket);\n      continue;\n    }\n    bucket.recurrence += frequency;\n    bucket.entryCount += 1;\n    bucket.types.add(type);\n    bucket.maturity.add(typeof row.maturity === \"string\" ? row.maturity : \"raw\");\n    if (row.severity === \"critical\") {\n      bucket.severity = \"critical\";\n    } else if (row.severity === \"important\" && bucket.severity !== \"critical\") {\n      bucket.severity = \"important\";\n    }\n    if (lastSeen && Date.parse(lastSeen) > Date.parse(bucket.lastSeenTs || \"0\")) {\n      bucket.lastSeenTs = lastSeen;\n    }\n  }\n  const ready = [];\n  for (const bucket of buckets.values()) {\n    const criticalOverride = bucket.severity === \"critical\";\n    const meetsRecurrence = bucket.recurrence >= threshold;\n    if (!criticalOverride && !meetsRecurrence) continue;\n    ready.push({\n      trigger: bucket.trigger,\n      action: bucket.action,\n      recurrence: bucket.recurrence,\n      entryCount: bucket.entryCount,\n      qualification: criticalOverride && !meetsRecurrence ? \"critical_override\" : \"recurrence\",\n      ...(bucket.severity ? { severity: bucket.severity } : {}),\n      lastSeenTs: bucket.lastSeenTs,\n      types: Array.from(bucket.types).sort(),\n      maturity: Array.from(bucket.maturity).sort()\n    });\n  }\n  ready.sort((a, b) => {\n    const sevDiff = severityWeight(b.severity) - severityWeight(a.severity);\n    if (sevDiff !== 0) return sevDiff;\n    if (b.recurrence !== a.recurrence) return b.recurrence - a.recurrence;\n    const recencyDiff = Date.parse(b.lastSeenTs || \"0\") - Date.parse(a.lastSeenTs || \"0\");\n    if (!Number.isNaN(recencyDiff) && recencyDiff !== 0) return recencyDiff;\n    return String(a.trigger).localeCompare(String(b.trigger));\n  });\n  return {\n    schemaVersion: 2,\n    threshold,\n    baseThreshold,\n    ...(archivedRunsCount !== undefined ? { archivedRunsCount } : {}),\n    smallProjectRelaxationApplied,\n    clusterCount: buckets.size,\n    readyCount: ready.length,\n    ready: ready.slice(0, maxReady),\n    lastUpdatedAt: normalizeCompoundLastUpdatedAt(new Date())\n  };\n}\n";
 /**
  * Inline mirror of `src/tdd-cycle.ts::computeRalphLoopStatus`.
  *