cclaw-cli 0.49.0 → 0.51.0

package/dist/content/hook-inline-snippets.js

@@ -45,6 +45,9 @@
  * - `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 const HOOK_INLINE_SHARED_HELPERS = `
 function normalizeCompoundLastUpdatedAt(date) {
@@ -65,6 +68,35 @@ async function countArchivedRunsInline(root) {
     return undefined;
   }
 }
+
+function formatCompoundReadinessLineInline(readiness) {
+  if (!readiness || typeof readiness !== "object") {
+    return "";
+  }
+  const ready = Array.isArray(readiness.ready) ? readiness.ready : [];
+  const readyCount =
+    typeof readiness.readyCount === "number" && Number.isFinite(readiness.readyCount)
+      ? Math.trunc(readiness.readyCount)
+      : ready.length;
+  const clusterCount =
+    typeof readiness.clusterCount === "number" && Number.isFinite(readiness.clusterCount)
+      ? Math.trunc(readiness.clusterCount)
+      : 0;
+  const threshold =
+    typeof readiness.threshold === "number" && Number.isFinite(readiness.threshold)
+      ? Math.trunc(readiness.threshold)
+      : COMPOUND_RECURRENCE_THRESHOLD;
+  if (readyCount === 0) {
+    return "Compound readiness: no candidates (clusters=" +
+      String(clusterCount) + ", threshold=" + String(threshold) + ")";
+  }
+  const critical = ready.filter(
+    (entry) => entry && typeof entry === "object" && entry.severity === "critical"
+  ).length;
+  const criticalSuffix = critical > 0 ? " (critical=" + String(critical) + ")" : "";
+  return "Compound readiness: clusters=" + String(clusterCount) +
+    ", ready=" + String(readyCount) + criticalSuffix;
+}
 `;
 /**
  * Inline mirror of `src/knowledge-store.ts::computeCompoundReadiness`.
@@ -127,7 +159,7 @@ async function computeCompoundReadinessInline(root, options) {
     let row;
     try { row = JSON.parse(line); } catch { continue; }
     if (!row || typeof row !== "object" || Array.isArray(row)) continue;
-    if (row.maturity === "lifted-to-enforcement") continue;
+    if (row.maturity === "lifted-to-enforcement" || typeof row.superseded_by === "string") continue;
     const type = typeof row.type === "string" ? row.type : "";
     const trigger = typeof row.trigger === "string" ? row.trigger : "";
     const action = typeof row.action === "string" ? row.action : "";

package/dist/content/hook-manifest.d.ts

@@ -21,7 +21,7 @@
  */
 export declare const HOOK_MANIFEST_HARNESSES: readonly ["claude", "cursor", "codex"];
 export type HookManifestHarness = (typeof HOOK_MANIFEST_HARNESSES)[number];
-export declare const HOOK_HANDLERS: readonly ["session-start", "prompt-guard", "workflow-guard", "context-monitor", "stop-checkpoint", "pre-compact", "verify-current-state"];
+export declare const HOOK_HANDLERS: readonly ["session-start", "prompt-guard", "workflow-guard", "context-monitor", "stop-handoff", "pre-compact", "verify-current-state"];
 export type HookHandlerId = (typeof HOOK_HANDLERS)[number];
 export interface HookBinding {
     /**
@@ -52,7 +52,7 @@ export interface HookHandlerSpec {
     semantic: HookSemanticEvent | null;
     bindings: Partial<Record<HookManifestHarness, HookBinding[]>>;
 }
-export declare const HOOK_SEMANTIC_EVENTS: readonly ["session_rehydrate", "pre_tool_prompt_guard", "pre_tool_workflow_guard", "post_tool_context_monitor", "stop_checkpoint", "precompact_digest"];
+export declare const HOOK_SEMANTIC_EVENTS: readonly ["session_rehydrate", "pre_tool_prompt_guard", "pre_tool_workflow_guard", "post_tool_context_monitor", "stop_handoff", "precompact_compat"];
 export type HookSemanticEvent = (typeof HOOK_SEMANTIC_EVENTS)[number];
 export declare const HOOK_MANIFEST: readonly HookHandlerSpec[];
 export interface EventGroup {
@@ -76,7 +76,6 @@ export declare function groupBindingsByEvent(harness: HookManifestHarness): Even
 /** Distinct harness-native event names covered by the manifest. */
 export declare function requiredEventsFor(harness: HookManifestHarness): string[];
 /**
- * Human-readable per-harness semantic coverage used by docs and by
- * the doctor's `harness-gaps.json` synthesis.
+ * Human-readable per-harness semantic coverage used by docs and doctor output.
  */
 export declare function semanticEventCoverage(harness: HookManifestHarness): Partial<Record<HookSemanticEvent, string>>;

package/dist/content/hook-manifest.js

@@ -25,7 +25,7 @@ export const HOOK_HANDLERS = [
     "prompt-guard",
     "workflow-guard",
     "context-monitor",
-    "stop-checkpoint",
+    "stop-handoff",
     "pre-compact",
     "verify-current-state"
 ];
@@ -34,8 +34,8 @@ export const HOOK_SEMANTIC_EVENTS = [
     "pre_tool_prompt_guard",
     "pre_tool_workflow_guard",
     "post_tool_context_monitor",
-    "stop_checkpoint",
-    "precompact_digest"
+    "stop_handoff",
+    "precompact_compat"
 ];
 export const HOOK_MANIFEST = [
     {
@@ -90,9 +90,9 @@ export const HOOK_MANIFEST = [
         }
     },
     {
-        handler: "stop-checkpoint",
-        description: "Persist checkpoint with stage + run context on session stop.",
-        semantic: "stop_checkpoint",
+        handler: "stop-handoff",
+        description: "Remind about clean handoff with stage + run context on session stop.",
+        semantic: "stop_handoff",
         bindings: {
             claude: [{ event: "Stop", timeout: 10 }],
             cursor: [{ event: "stop", timeout: 10 }],
@@ -101,12 +101,12 @@ export const HOOK_MANIFEST = [
     },
     {
         handler: "pre-compact",
-        description: "Write pre-compact digest (Claude+Cursor have a native event; Codex has no PreCompact — covered by `/cc-ops retro`).",
-        semantic: "precompact_digest",
+        description: "No-op compatibility hook for harness pre-compact events; session-start rehydrates from flow-state, artifacts, and knowledge.",
+        semantic: "precompact_compat",
         bindings: {
             claude: [{ event: "PreCompact", matcher: "manual|auto", timeout: 10 }],
-            // pre-compact must capture the digest BEFORE session-start
-            // rehydrates on cursor `sessionCompact`.
+            // Keep this before session-start on cursor `sessionCompact` so the
+            // compatibility handler runs before rehydration.
             cursor: [{ event: "sessionCompact", priority: -10 }]
         }
     },
@@ -179,8 +179,7 @@ export function requiredEventsFor(harness) {
     return ordered;
 }
 /**
- * Human-readable per-harness semantic coverage used by docs and by
- * the doctor's `harness-gaps.json` synthesis.
+ * Human-readable per-harness semantic coverage used by docs and doctor output.
  */
 export function semanticEventCoverage(harness) {
     const out = {};

package/dist/content/hooks.js

@@ -134,6 +134,7 @@ set "RUNTIME=%HOOK_DIR%run-hook.mjs"
 where node >nul 2>nul
 if %ERRORLEVEL% neq 0 (
   REM Best-effort: missing node should not block harness execution loops.
+  echo [cclaw] run-hook.cmd: node not found; cclaw hook skipped. Run cclaw doctor. >&2
   exit /b 0
 )
 node "%RUNTIME%" %*
@@ -145,6 +146,7 @@ if [ "$#" -lt 1 ]; then
   exit 1
 fi
 if ! command -v node >/dev/null 2>&1; then
+  echo "[cclaw] run-hook.cmd: node not found; cclaw hook skipped. Run cclaw doctor." >&2
   exit 0
 fi
 exec node "\${SCRIPT_DIR}/run-hook.mjs" "$@"

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

@@ -1,6 +1,8 @@
 import { type IdeateFrameId } from "./ideate-frames.js";
 export interface IdeateCommandOptions {
     frameIds?: readonly IdeateFrameId[];
+    mode?: "repo-grounded" | "elsewhere-software" | "elsewhere-non-software" | "narrow";
 }
+export declare function minimumDistinctIdeateFrames(frameCount: number, mode?: IdeateCommandOptions["mode"]): number;
 export declare function ideateCommandContract(options?: IdeateCommandOptions): string;
 export declare function ideateCommandSkillMarkdown(options?: IdeateCommandOptions): string;

package/dist/content/ideate-command.js

@@ -1,5 +1,6 @@
 import { RUNTIME_ROOT } from "../constants.js";
 import { resolveIdeateFrames } from "./ideate-frames.js";
+import { ideateStructuredAskToolsWithFallback } from "./decision-protocol.js";
 const IDEATE_SKILL_FOLDER = "flow-ideate";
 const IDEATE_SKILL_NAME = "flow-ideate";
 /**
@@ -10,15 +11,13 @@ const IDEATE_SKILL_NAME = "flow-ideate";
 const IDEATE_ARTIFACT_GLOB = ".cclaw/artifacts/ideate-*.md";
 const IDEATE_ARTIFACT_PATTERN = ".cclaw/artifacts/ideate-<YYYY-MM-DD-slug>.md";
 const IDEATE_RESUME_WINDOW_DAYS = 30;
-/**
- * Structured-ask tool list reused across cclaw skills. Kept inline here (small
- * enough) to avoid cross-module coupling; larger stage skills cite the shared
- * protocol file instead.
- */
-const STRUCTURED_ASK_TOOLS = "`AskUserQuestion` on Claude, `AskQuestion` on Cursor, " +
-    "`question` on OpenCode when `permission.question: \"allow\"` is set, " +
-    "`request_user_input` on Codex in Plan / Collaboration mode; " +
-    "fall back to a plain-text lettered list when the tool is hidden or errors";
+const STRUCTURED_ASK_TOOLS = ideateStructuredAskToolsWithFallback();
+export function minimumDistinctIdeateFrames(frameCount, mode = "repo-grounded") {
+    if (frameCount <= 0)
+        return 0;
+    const cap = mode === "repo-grounded" ? 4 : 2;
+    return Math.min(cap, frameCount);
+}
 function renderFrameBullets(frameIds) {
     return resolveIdeateFrames(frameIds)
         .map((frame) => `   - ${frame.label} (\`${frame.id}\`)`)
@@ -32,7 +31,7 @@ function renderFrameNames(frameIds) {
 export function ideateCommandContract(options = {}) {
     const frames = resolveIdeateFrames(options.frameIds);
     const frameBullets = renderFrameBullets(options.frameIds);
-    const minimumDistinctFrames = Math.min(4, frames.length);
+    const minimumDistinctFrames = minimumDistinctIdeateFrames(frames.length, options.mode);
     return `# /cc-ideate
 
 ## Purpose
@@ -58,8 +57,10 @@ same session, or save/discard the backlog.
    has been modified within the last ${IDEATE_RESUME_WINDOW_DAYS} days,
    offer the user: continue that backlog, start fresh, or cancel.
 2. **Mode classification.** Explicitly classify subject:
-   \`repo-grounded\` / \`elsewhere-software\` / \`elsewhere-non-software\`.
-   Do not assume repo-grounded by default.
+   \`repo-grounded\` / \`elsewhere-software\` / \`elsewhere-non-software\` / \`narrow\`.
+   Do not assume repo-grounded by default. Repo-grounded scans keep the
+   broadest frame minimum; narrow and non-repo modes use the smaller minimum
+   shown below.
 3. **Mode-aware grounding (parallel).**
    - Repo-grounded: repo signal scan + \`${RUNTIME_ROOT}/knowledge.jsonl\`
      repetition scan.
@@ -68,7 +69,9 @@ same session, or save/discard the backlog.
 4. **Divergent ideation frames (parallel).** Generate candidates with
    configured frames (${frames.length} total):
 ${frameBullets}
-   Keep at least ${minimumDistinctFrames} distinct frame outputs in every run.
+   Keep at least ${minimumDistinctFrames} distinct frame outputs in this rendered mode.
+   Deterministic minimum: repo-grounded = 4, narrow/non-repo = 2, always capped
+   by configured frame count.
 5. **Adversarial critique pass.** For each candidate, write the strongest
    counter-argument, kill weak ideas, and keep survivors only.
 6. **Produce 5-10 survivors** with impact (High/Medium/Low),
@@ -91,7 +94,7 @@ ${frameBullets}
 For skill-to-skill invocation, emit exactly one JSON envelope:
 
 \`\`\`json
-{"version":"1","kind":"stage-output","stage":"brainstorm","payload":{"command":"/cc-ideate","artifact":".cclaw/artifacts/ideate-<date>-<slug>.md","recommendation":"I-1"},"emittedAt":"<ISO-8601>"}
+{"version":"1","kind":"stage-output","stage":"non-flow","payload":{"command":"/cc-ideate","artifact":".cclaw/artifacts/ideate-<date>-<slug>.md","recommendation":"I-1"},"emittedAt":"<ISO-8601>"}
 \`\`\`
 
 Validate envelopes with:
@@ -105,7 +108,7 @@ Validate envelopes with:
 export function ideateCommandSkillMarkdown(options = {}) {
     const frames = resolveIdeateFrames(options.frameIds);
     const frameBullets = renderFrameBullets(options.frameIds);
-    const minimumDistinctFrames = Math.min(4, frames.length);
+    const minimumDistinctFrames = minimumDistinctIdeateFrames(frames.length, options.mode);
     const frameNames = renderFrameNames(options.frameIds);
     return `---
 name: ${IDEATE_SKILL_NAME}
@@ -148,6 +151,7 @@ repository. Will persist a ranked backlog to
    - \`repo-grounded\` — explicitly tied to this repository.
    - \`elsewhere-software\` — software problem not tied to this repository.
    - \`elsewhere-non-software\` — process/business/non-software problem.
+   - \`narrow\` — a focused prompt where broad frame coverage would be performative.
 6. Record the chosen mode in the artifact.
 
 ### Phase 1 — Mode-aware grounding
@@ -161,8 +165,7 @@ Run grounding in parallel where available:
   - Module size outliers (\`wc -l\` or \`du\`) with weak direct test coverage.
   - Docs drift: check that \`README.md\` / \`docs/\` reference files that still
     exist and flags/APIs that still match \`src/\`.
-  - \`${RUNTIME_ROOT}/knowledge.jsonl\` entries with \`type: "heuristic"\`
-    or repeated \`subject:\` values.
+  - \`${RUNTIME_ROOT}/knowledge.jsonl\` entries with recurring \`type\` in \`rule | pattern | lesson | compound\` and repeated \`trigger/action\` pairs; prefer clusters that already show stable \`origin_run\` history.
 - For \`elsewhere-software\`:
   - Gather current framework/library docs first.
   - Add one comparison scan for established solutions.
@@ -177,8 +180,11 @@ Generate candidate ideas by frame, in parallel when possible:
 
 ${frameBullets}
 
-Require at least ${minimumDistinctFrames} distinct frames in every run. Avoid frame-collapse
-(same idea rewritten 6 times). Keep raw outputs for auditability.
+Require at least ${minimumDistinctFrames} distinct frames in this rendered mode. The
+runtime rule is deterministic: repo-grounded scans require 4 distinct frames;
+narrow, elsewhere-software, and elsewhere-non-software runs require 2; all modes
+are capped by the configured frame count. Avoid frame-collapse (same idea
+rewritten many times). Keep raw outputs for auditability.
 
 ### Phase 3 — Critique all, keep survivors
 
@@ -217,7 +223,7 @@ Only survivors advance to ranking.
    # Ideation — <date>
 
    **Focus:** <user-supplied focus or "open-ended scan">
-   **Mode:** <repo-grounded | elsewhere-software | elsewhere-non-software>
+   **Mode:** <repo-grounded | elsewhere-software | elsewhere-non-software | narrow>
    **Generated:** <ISO-8601 timestamp>
    **Frames used:** <comma-separated list>
    **Raw candidates:** <N>
@@ -239,15 +245,15 @@ Only survivors advance to ranking.
 
    | ID | Improvement | Impact | Effort | Confidence | Evidence |
    |---|---|---|---|---|---|
-   | I-1 | Fix feature-worktree test timeouts | High | S | High | tests/unit/feature-system.test.ts:31 |
+| I-1 | Simplify a confusing generated prompt surface | High | S | High | <path-to-generated-surface> |
    | …   | …                                  | …    | … | …    | …                                     |
 
    ## Candidate detail
 
-   ### I-1 — Fix feature-worktree test timeouts
-   - **Evidence:** \`npm test\` hangs 40s on tests/unit/feature-system.test.ts:31.
-   - **Counter-argument:** Fix may hide deeper orchestration race.
-   - **Handoff:** \`/cc Fix feature-worktree test timeouts on macOS\`
+### I-1 — Simplify a confusing generated prompt surface
+- **Evidence:** \`<path>\` contains repeated or stale guidance that a user would see.
+- **Counter-argument:** Trimming too hard can remove useful orientation for new users.
+- **Handoff:** \`/cc Simplify the confusing generated prompt surface while preserving behavior\`
 
    ### I-2 — …
    \`\`\`

package/dist/content/iron-laws.d.ts

@@ -79,8 +79,8 @@ export declare const IRON_LAWS: readonly [{
     readonly title: "Review layers are sequential";
     readonly rule: "Review stage must complete Layer 1 spec compliance before Layer 2 quality/security passes.";
     readonly rationale: "Stops premature quality discussion when acceptance criteria are not yet satisfied.";
-    readonly enforcement: "advisory";
-    readonly severity: "soft-gate";
+    readonly enforcement: "PreToolUse";
+    readonly severity: "hard-gate";
     readonly appliesTo: ["review"];
 }, {
     readonly id: "review-criticals-close-before-ship";
@@ -123,9 +123,9 @@ export declare const IRON_LAWS: readonly [{
     readonly severity: "hard-gate";
     readonly appliesTo: "all";
 }, {
-    readonly id: "stop-clean-or-checkpointed";
-    readonly title: "Stop only from clean checkpoint";
-    readonly rule: "Do not end a session with dirty state unless checkpoint explicitly records unresolved work and blockers.";
+    readonly id: "stop-clean-or-handoff";
+    readonly title: "Stop only from clean handoff";
+    readonly rule: "Do not end a session with dirty state unless the current artifact records unresolved work and blockers.";
     readonly rationale: "Protects continuity and prevents silent half-finished sessions.";
     readonly enforcement: "Stop";
     readonly severity: "hard-gate";

package/dist/content/iron-laws.js

@@ -49,8 +49,8 @@ export const IRON_LAWS = [
         title: "Review layers are sequential",
         rule: "Review stage must complete Layer 1 spec compliance before Layer 2 quality/security passes.",
         rationale: "Stops premature quality discussion when acceptance criteria are not yet satisfied.",
-        enforcement: "advisory",
-        severity: "soft-gate",
+        enforcement: "PreToolUse",
+        severity: "hard-gate",
         appliesTo: ["review"]
     },
     {
@@ -99,9 +99,9 @@ export const IRON_LAWS = [
         appliesTo: "all"
     },
     {
-        id: "stop-clean-or-checkpointed",
-        title: "Stop only from clean checkpoint",
-        rule: "Do not end a session with dirty state unless checkpoint explicitly records unresolved work and blockers.",
+        id: "stop-clean-or-handoff",
+        title: "Stop only from clean handoff",
+        rule: "Do not end a session with dirty state unless the current artifact records unresolved work and blockers.",
         rationale: "Protects continuity and prevents silent half-finished sessions.",
         enforcement: "Stop",
         severity: "hard-gate",

package/dist/content/learnings.d.ts

@@ -1,9 +1,8 @@
 /**
  * Canonical required JSONL field order (matches strict validator keys).
- * Optional keys (for now: `source`, `severity`) may be appended after these
- * required fields.
+ * Optional keys (`source`, `severity`, `supersedes`, `superseded_by`) 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 const KNOWLEDGE_JSONL_FIELDS: readonly ["type", "trigger", "action", "confidence", "domain", "stage", "origin_stage", "origin_run", "frequency", "universality", "maturity", "created", "first_seen_ts", "last_seen_ts", "project"];
 export declare function learnSkillMarkdown(): string;
-export declare function learnCommandContract(): string;

package/dist/content/learnings.js

@@ -1,5 +1,5 @@
 // ---------------------------------------------------------------------------
-// Knowledge store content for /cc-learn and stage self-improvement prompts.
+// Knowledge store content for the learnings skill and stage self-improvement prompts.
 //
 // The knowledge store is a single canonical JSONL file. Each line is one
 // self-contained JSON object matching the strict schema in this module.
@@ -11,8 +11,8 @@ 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 required JSONL field order (matches strict validator keys).
- * Optional keys (for now: `source`, `severity`) may be appended after these
- * required fields.
+ * Optional keys (`source`, `severity`, `supersedes`, `superseded_by`) 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 = [
@@ -23,7 +23,7 @@ export const KNOWLEDGE_JSONL_FIELDS = [
     "domain",
     "stage",
     "origin_stage",
-    "origin_feature",
+    "origin_run",
     "frequency",
     "universality",
     "maturity",
@@ -49,7 +49,7 @@ Use the store to keep durable knowledge that should survive sessions:
 - **rule**: hard constraint to follow every time.
 - **pattern**: repeatable way that works well in this project.
 - **lesson**: non-obvious outcome from a failure or trade-off.
-- **compound**: post-ship insight about how to make the *next* feature faster (process accelerator, not domain rule).
+- **compound**: post-ship insight about how to make the *next* run faster (process accelerator, not domain rule).
 
 ## Continuous capture (stage closeout path)
 
@@ -63,22 +63,23 @@ Knowledge capture is now stage-native:
   2. appends deduped entries to \`${KNOWLEDGE_PATH}\`,
   3. writes a harvest marker into the artifact.
 
-\`/cc-learn\` remains the manual/query surface (search, backfill, curation).
+Manual/query operations (search, backfill, curation) use this skill when the
+user asks for knowledge work.
 
 ## HARD-GATE
 
-Under \`/cc-learn\`, only modify \`${KNOWLEDGE_PATH}\`, \`${KNOWLEDGE_ARCHIVE_PATH}\`,
+During manual knowledge operations, only modify \`${KNOWLEDGE_PATH}\`, \`${KNOWLEDGE_ARCHIVE_PATH}\`,
 or an explicitly user-approved summary file. Do not modify application code here.
 Do not invent alternate stores (no markdown mirror, no SQLite, no per-stage files).
 
 ## Entry format — strict JSONL schema
 
 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\`.
+\`type, trigger, action, confidence, domain, stage, origin_stage, origin_run, frequency, universality, maturity, created, first_seen_ts, last_seen_ts, project\`.
 Optional fields \`source\` and \`severity\` 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"}
+{"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_run":"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"}
 \`\`\`
 
 | field | type | required | notes |
@@ -90,7 +91,7 @@ Optional fields \`source\` and \`severity\` may be appended after \`project\`.
 | \`domain\` | string \\| null | yes | Free-form taxonomy (\`api\`, \`infra\`, \`ui\`, \`security\`, \`testing\`, …). Use \`null\` when cross-cutting. |
 | \`stage\` | \`FlowStage\` \\| null | yes | One of brainstorm / scope / design / spec / plan / tdd / review / ship, or \`null\` when cross-stage. |
 | \`origin_stage\` | \`FlowStage\` \\| null | yes | Stage where this learning was first observed. |
-| \`origin_feature\` | string \\| null | yes | Feature/worktree label where it was observed first. |
+| \`origin_run\` | string \\| null | yes | Optional run, branch, or topic label where it was observed first. |
 | \`frequency\` | integer >= 1 | yes | Number of times this same trigger/action pair has been observed. |
 | \`universality\` | \`"project" \\| "personal" \\| "universal"\` | yes | Scope of applicability. |
 | \`maturity\` | \`"raw" \\| "lifted-to-rule" \\| "lifted-to-enforcement"\` | yes | Lifecycle state of the learning. |
@@ -99,7 +100,7 @@ Optional fields \`source\` and \`severity\` may be appended after \`project\`.
 | \`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. |
-| \`severity\` | \`"critical" \\| "important" \\| "suggestion"\` | no | Priority signal for compound lifts; \`critical\` enables single-hit override in \`/cc-ops compound\`. |
+| \`severity\` | \`"critical" \\| "important" \\| "suggestion"\` | no | Priority signal for compound lifts; \`critical\` enables single-hit override in compound readiness analysis. |
 
 Rules:
 - No other fields beyond the table above. Extra keys are forbidden and MUST be rejected by any writer.
@@ -111,68 +112,41 @@ Rules:
 ## Curation policy (target: ≤ 50 active entries)
 
 - The file is append-only — entries are never physically deleted.
-- When the canonical file exceeds 50 lines, \`/cc-learn curate\` proposes
+- When the canonical file exceeds 50 lines, a curation pass proposes
   soft-archiving: the approved lines are **moved** to \`${KNOWLEDGE_ARCHIVE_PATH}\`
   verbatim (same JSONL shape). The working file stays lean.
-- See the **knowledge-curation** utility skill for the full curation protocol.
+- Use the **Curate** action below for the full read-only audit and
+  user-approved soft-archive plan.
 
-## Subcommands
+## Manual Actions
 
-### \`/cc-learn\` (default)
+### Show recent entries
 - Read \`${KNOWLEDGE_PATH}\`. Stream the last 30 lines; pretty-print each
   line's \`type\` / \`trigger\` / \`action\` for human review.
-- If file is missing or empty, report that clearly and suggest \`/cc-learn add\`.
+- If file is missing or empty, report that clearly and suggest adding a
+  manual entry through this skill.
 
-### \`/cc-learn search <query>\`
+### Search \`<query>\`
 - Stream \`${KNOWLEDGE_PATH}\`, JSON.parse each line, filter where any of
   \`trigger\`, \`action\`, \`domain\`, \`project\` contains \`<query>\` (case-insensitive).
 - Return the matched lines pretty-printed (do not mutate the file).
 
-### \`/cc-learn add\`
+### Add
 - Ask for required user-facing fields in order: \`type\`, \`trigger\`, \`action\`, \`confidence\`, \`domain\`, \`stage\`, \`universality\`, \`project\`.
 - \`confidence\` must be one of \`high\`, \`medium\`, \`low\`. Default to \`medium\` if the user declines to set it.
 - \`domain\`, \`stage\`, and \`project\` may be explicitly \`null\`.
 - Prefer stage-native \`## Learnings\` capture for new flow work; use \`add\` mainly for backfilling historical lessons or ad-hoc entries outside a stage closeout.
-- \`origin_stage\` defaults to \`stage\`; \`origin_feature\` defaults to active feature (or \`null\` if unknown).
+- \`origin_stage\` defaults to \`stage\`; \`origin_run\` defaults to the current run, branch, or topic label (or \`null\` if unknown).
 - \`frequency\` starts at \`1\`.
 - \`maturity\` starts at \`raw\`.
 - \`created\`, \`first_seen_ts\`, and \`last_seen_ts\` are set automatically to current UTC ISO timestamp.
 - Append exactly one JSON line to \`${KNOWLEDGE_PATH}\` with the field order from the schema table above.
 - Re-read the file tail to confirm the new line is valid JSON and parses back to the same object.
 
-### \`/cc-learn curate\`
-- Hand off to the **knowledge-curation** skill (read-only audit + soft-archive plan).
+### Curate
+- Produce a read-only audit + soft-archive plan.
 - Never deletes. Soft-archive means **moving** full JSON lines from
   \`${KNOWLEDGE_PATH}\` to \`${KNOWLEDGE_ARCHIVE_PATH}\` as part of a
   user-approved curation pass.
 `;
 }
-export function learnCommandContract() {
-    return `# /cc-learn
-
-## Purpose
-
-Manage the project knowledge store. One canonical file, strict JSONL:
-- \`${KNOWLEDGE_PATH}\` — append-only JSONL, one entry per line.
-- \`${KNOWLEDGE_ARCHIVE_PATH}\` — soft-archive target written only by curate.
-
-Stage-native pipeline:
-- During \`stage-complete.mjs\`, cclaw harvests \`## Learnings\` from the current
-  stage artifact into \`${KNOWLEDGE_PATH}\` automatically.
-- Use \`/cc-learn\` for query, backfill, and curation workflows.
-
-## HARD-GATE
-
-Do not edit source code from this command. Only operate on \`${KNOWLEDGE_PATH}\`,
-\`${KNOWLEDGE_ARCHIVE_PATH}\`, or user-approved summary output.
-
-## Subcommands
-
-| subcommand | args | description |
-|---|---|---|
-| (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 JSONL schema (15 required fields + optional \`source\` / \`severity\`). |
-| \`curate\` | — | Hand off to the **knowledge-curation** skill: read-only audit + soft-archive plan when the file exceeds the curation threshold. |
-`;
-}

package/dist/content/meta-skill.js

@@ -1,10 +1,9 @@
-import { FLOW_MAP_REL_PATH } from "./flow-map.js";
-import { COMPLETION_PROTOCOL_REL_PATH, DECISION_PROTOCOL_REL_PATH, ETHOS_PROTOCOL_REL_PATH } from "./protocols.js";
+import { CLOSEOUT_CHAIN, closeoutChainInline, closeoutFlowMapSentence, closeoutProtocolBehaviorSentence } from "./closeout-guidance.js";
 export const META_SKILL_NAME = "using-cclaw";
 export function usingCclawSkillMarkdown() {
     return `---
 name: using-cclaw
-description: "Routing brain for cclaw. Decide whether to start/resume a stage, answer directly, or use utility commands like /cc-learn, /cc-ideate, /cc-view, and /cc-ops."
+description: "Routing brain for cclaw. Decide whether to start/resume a stage, answer directly, or use visible commands like /cc, /cc-next, /cc-ideate, and /cc-view."
 ---
 
 # Using Cclaw
@@ -58,9 +57,10 @@ Task arrives
   ├─ New software work? -> /cc <idea>
   ├─ Repo-improvement discovery? -> /cc-ideate
   ├─ Resume existing flow? -> /cc or /cc-next
-  ├─ Knowledge operation? -> /cc-learn
+  ├─ Knowledge operation? -> load the learnings skill
   ├─ Read-only workspace view? -> /cc-view [status|tree|diff]
-  └─ Workspace operation? -> /cc-ops [feature|tdd-log|retro|compound|archive|rewind]
+  ├─ Normal post-ship closeout? -> /cc-next drives ${closeoutChainInline()}
+  └─ Explicit early archival/reset? -> cclaw archive [--name=<slug>]
 \`\`\`
 
 ## Task classification
@@ -89,30 +89,40 @@ Before stage work:
 
 ## Stage quick map
 
-brainstorm -> scope -> design -> spec -> plan -> tdd -> review -> ship
+Use \`/cc <idea>\` for new work, \`/cc-next\` for progression and closeout, \`/cc-view\` for read-only state, and \`/cc-ideate\` for backlog discovery.
 
-Tracks may skip stages via \`flow-state.track\` + \`skippedStages\`.
-For the full surface (stages, routers, Ralph Loop, state files) load
-\`${FLOW_MAP_REL_PATH}\` — it is the single-page overview of cclaw.
+## Main vs Operator Surfaces
 
-## Contextual skill activation
+- **Main workflow:** \`/cc\`, \`/cc-next\`, \`/cc-ideate\`, \`/cc-view status\`.
+- **Operator/support:** \`cclaw doctor\`, \`cclaw sync\`, \`cclaw archive\`,
+  \`/cc-view tree\`, and \`/cc-view diff\`.
+- Use operator/support surfaces only for install/runtime diagnosis, explicit
+  archival, or deeper inspection. Do not make them part of the happy path.
 
-Load utility skills only when triggered by the current task:
+## Whole flow map
 
-- security, performance, debugging, docs, ci-cd
-- verification-before-completion before completion claims
-- finishing-a-development-branch during ship/finalization
-- document-review, receiving-code-review, and execution context skills
+standard: brainstorm -> scope -> design -> spec -> plan -> tdd -> review -> ship -> ${CLOSEOUT_CHAIN}
+medium: brainstorm -> spec -> plan -> tdd -> review -> ship -> ${CLOSEOUT_CHAIN}
+quick: spec -> tdd -> review -> ship -> ${CLOSEOUT_CHAIN}
+
+${closeoutFlowMapSentence()}
+
+Tracks may skip critical-path stages via \`flow-state.track\` + \`skippedStages\`.
+Use the current stage skill plus \`.cclaw/state/flow-state.json\` for orientation.
+
+## Contextual Skill Activation
+
+Use built-in judgment only when triggered by the current task:
+
+- security, performance, debugging, docs, and CI/CD review lenses
+- verification discipline before completion claims
+- branch-finishing discipline during ship/finalization
 - iron-laws as policy arbitration when instructions conflict
 - language rule packs from \`.cclaw/config.yaml\` when enabled
 
-## Protocol references
-
-Do not inline these protocols in stage skills; cite by path:
+## Protocol Behavior
 
-- Decision protocol: \`${DECISION_PROTOCOL_REL_PATH}\`
-- Completion/resume protocol: \`${COMPLETION_PROTOCOL_REL_PATH}\`
-- Engineering ethos + announce discipline: \`${ETHOS_PROTOCOL_REL_PATH}\`
+${closeoutProtocolBehaviorSentence()}
 
 ## Knowledge guidance