cclaw-cli 0.5.17 → 0.6.0

package/dist/cli.d.ts

@@ -1,9 +1,10 @@
 #!/usr/bin/env node
-import type { HarnessId } from "./types.js";
+import type { FlowTrack, HarnessId } from "./types.js";
 type CommandName = "init" | "sync" | "doctor" | "upgrade" | "uninstall" | "archive";
 interface ParsedArgs {
     command?: CommandName;
     harnesses?: HarnessId[];
+    track?: FlowTrack;
     reconcileGates?: boolean;
     archiveName?: string;
     showHelp?: boolean;
@@ -11,5 +12,6 @@ interface ParsedArgs {
 }
 export declare function usage(): string;
 declare function parseHarnesses(raw: string): HarnessId[];
+declare function parseTrack(raw: string): FlowTrack;
 declare function parseArgs(argv: string[]): ParsedArgs;
-export { parseArgs, parseHarnesses };
+export { parseArgs, parseHarnesses, parseTrack };

package/dist/cli.js

@@ -3,7 +3,7 @@ import { readFileSync, realpathSync } from "node:fs";
 import process from "node:process";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
-import { HARNESS_IDS } from "./types.js";
+import { FLOW_TRACKS, HARNESS_IDS } from "./types.js";
 import { doctorChecks, doctorSucceeded } from "./doctor.js";
 import { initCclaw, syncCclaw, uninstallCclaw, upgradeCclaw } from "./install.js";
 import { error, info } from "./logger.js";
@@ -20,6 +20,7 @@ Usage:
 Commands:
   init       Bootstrap .cclaw runtime, state, and harness shims in this project.
              Flags: --harnesses=<list>  Comma list of harnesses (claude,cursor,opencode,codex).
+                    --track=<id>        Flow track for new runs (standard | quick). Default: standard.
   sync       Regenerate harness shim files from the current .cclaw config (non-destructive).
   doctor     Run health checks against the local .cclaw runtime. Exit code 2 on failure.
              Flags: --reconcile-gates   Recompute current-stage gate evidence before checks.
@@ -77,6 +78,13 @@ function parseHarnesses(raw) {
     }
     return requested;
 }
+function parseTrack(raw) {
+    const trimmed = raw.trim();
+    if (!FLOW_TRACKS.includes(trimmed)) {
+        throw new Error(`Unknown track: ${trimmed}. Supported: ${FLOW_TRACKS.join(", ")}`);
+    }
+    return trimmed;
+}
 function parseArgs(argv) {
     const parsed = {};
     const helpFlag = argv.find((arg) => arg === "--help" || arg === "-h");
@@ -96,6 +104,10 @@ function parseArgs(argv) {
             parsed.harnesses = parseHarnesses(flag.replace("--harnesses=", ""));
             continue;
         }
+        if (flag.startsWith("--track=")) {
+            parsed.track = parseTrack(flag.replace("--track=", ""));
+            continue;
+        }
         if (flag === "--reconcile-gates") {
             parsed.reconcileGates = true;
             continue;
@@ -123,9 +135,11 @@ async function runCommand(parsed, ctx) {
     if (command === "init") {
         await initCclaw({
             projectRoot: ctx.cwd,
-            harnesses: parsed.harnesses
+            harnesses: parsed.harnesses,
+            track: parsed.track
         });
-        info(ctx, "Initialized .cclaw runtime and generated harness shims");
+        const trackNote = parsed.track ? ` (track: ${parsed.track})` : "";
+        info(ctx, `Initialized .cclaw runtime and generated harness shims${trackNote}`);
         return 0;
     }
     if (command === "sync") {
@@ -190,4 +204,4 @@ function isDirectExecution() {
 if (isDirectExecution()) {
     void main();
 }
-export { parseArgs, parseHarnesses };
+export { parseArgs, parseHarnesses, parseTrack };

package/dist/config.d.ts

@@ -1,5 +1,5 @@
-import type { HarnessId, VibyConfig } from "./types.js";
+import type { FlowTrack, HarnessId, VibyConfig } from "./types.js";
 export declare function configPath(projectRoot: string): string;
-export declare function createDefaultConfig(harnesses?: HarnessId[]): VibyConfig;
+export declare function createDefaultConfig(harnesses?: HarnessId[], defaultTrack?: FlowTrack): VibyConfig;
 export declare function readConfig(projectRoot: string): Promise<VibyConfig>;
 export declare function writeConfig(projectRoot: string, config: VibyConfig): Promise<void>;

package/dist/config.js

@@ -3,17 +3,20 @@ import path from "node:path";
 import { parse, stringify } from "yaml";
 import { CCLAW_VERSION, DEFAULT_HARNESSES, FLOW_VERSION, RUNTIME_ROOT } from "./constants.js";
 import { exists, writeFileSafe } from "./fs-utils.js";
-import { HARNESS_IDS } from "./types.js";
+import { FLOW_TRACKS, HARNESS_IDS } from "./types.js";
 const CONFIG_PATH = `${RUNTIME_ROOT}/config.yaml`;
 const HARNESS_ID_SET = new Set(HARNESS_IDS);
+const FLOW_TRACK_SET = new Set(FLOW_TRACKS);
 const SUPPORTED_HARNESSES_TEXT = HARNESS_IDS.join(", ");
+const SUPPORTED_TRACKS_TEXT = FLOW_TRACKS.join(", ");
 const ALLOWED_CONFIG_KEYS = new Set([
     "version",
     "flowVersion",
     "harnesses",
     "autoAdvance",
     "promptGuardMode",
-    "gitHookGuards"
+    "gitHookGuards",
+    "defaultTrack"
 ]);
 function configFixExample() {
     return `harnesses:
@@ -23,20 +26,22 @@ function configFixExample() {
 function configValidationError(configFilePath, reason) {
     return new Error(`Invalid cclaw config at ${configFilePath}: ${reason}\n` +
         `Supported harnesses: ${SUPPORTED_HARNESSES_TEXT}\n` +
+        `Supported tracks: ${SUPPORTED_TRACKS_TEXT}\n` +
         `Example config:\n${configFixExample()}\n` +
         `After fixing, run: cclaw sync`);
 }
 export function configPath(projectRoot) {
     return path.join(projectRoot, CONFIG_PATH);
 }
-export function createDefaultConfig(harnesses = DEFAULT_HARNESSES) {
+export function createDefaultConfig(harnesses = DEFAULT_HARNESSES, defaultTrack = "standard") {
     return {
         version: CCLAW_VERSION,
         flowVersion: FLOW_VERSION,
         harnesses,
         autoAdvance: false,
         promptGuardMode: "advisory",
-        gitHookGuards: false
+        gitHookGuards: false,
+        defaultTrack
     };
 }
 export async function readConfig(projectRoot) {
@@ -89,13 +94,22 @@ export async function readConfig(projectRoot) {
         throw configValidationError(fullPath, `"gitHookGuards" must be a boolean`);
     }
     const gitHookGuards = typeof gitHookGuardsRaw === "boolean" ? gitHookGuardsRaw : false;
+    const defaultTrackRaw = parsed.defaultTrack;
+    if (Object.prototype.hasOwnProperty.call(parsed, "defaultTrack") &&
+        (typeof defaultTrackRaw !== "string" || !FLOW_TRACK_SET.has(defaultTrackRaw))) {
+        throw configValidationError(fullPath, `"defaultTrack" must be one of: ${SUPPORTED_TRACKS_TEXT}`);
+    }
+    const defaultTrack = typeof defaultTrackRaw === "string" && FLOW_TRACK_SET.has(defaultTrackRaw)
+        ? defaultTrackRaw
+        : "standard";
     return {
         version: parsed.version ?? CCLAW_VERSION,
         flowVersion: parsed.flowVersion ?? FLOW_VERSION,
         harnesses,
         autoAdvance,
         promptGuardMode,
-        gitHookGuards
+        gitHookGuards,
+        defaultTrack
     };
 }
 export async function writeConfig(projectRoot, config) {

package/dist/constants.d.ts

@@ -4,9 +4,9 @@ export declare const RUNTIME_ROOT = ".cclaw";
 export declare const CCLAW_VERSION = "0.1.1";
 export declare const FLOW_VERSION = "1.0.0";
 export declare const DEFAULT_HARNESSES: HarnessId[];
-export declare const REQUIRED_DIRS: readonly [".cclaw", ".cclaw/commands", ".cclaw/skills", ".cclaw/contexts", ".cclaw/templates", ".cclaw/artifacts", ".cclaw/state", ".cclaw/runs", ".cclaw/rules", ".cclaw/adapters", ".cclaw/agents", ".cclaw/hooks"];
+export declare const REQUIRED_DIRS: readonly [".cclaw", ".cclaw/commands", ".cclaw/skills", ".cclaw/contexts", ".cclaw/templates", ".cclaw/artifacts", ".cclaw/state", ".cclaw/runs", ".cclaw/rules", ".cclaw/adapters", ".cclaw/agents", ".cclaw/hooks", ".cclaw/custom-skills"];
 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", ".codex/commands/cc-*.md", ".codex/commands/cc.md", ".claude/hooks/hooks.json", ".cursor/hooks.json", ".codex/hooks.json", ".opencode/plugins/cclaw-plugin.mjs", ".cursor/rules/cclaw-workflow.mdc"];
 export declare const COMMAND_FILE_ORDER: FlowStage[];
-export declare const UTILITY_COMMANDS: readonly ["learn", "next"];
+export declare const UTILITY_COMMANDS: readonly ["learn", "next", "status"];
 export declare const SUBAGENT_SKILL_FOLDERS: readonly ["subagent-dev", "parallel-dispatch"];
 export type UtilityCommand = (typeof UTILITY_COMMANDS)[number];

package/dist/constants.js

@@ -20,7 +20,8 @@ export const REQUIRED_DIRS = [
     `${RUNTIME_ROOT}/rules`,
     `${RUNTIME_ROOT}/adapters`,
     `${RUNTIME_ROOT}/agents`,
-    `${RUNTIME_ROOT}/hooks`
+    `${RUNTIME_ROOT}/hooks`,
+    `${RUNTIME_ROOT}/custom-skills`
 ];
 export const REQUIRED_GITIGNORE_PATTERNS = [
     "# cclaw generated artifacts",
@@ -49,7 +50,7 @@ export const COMMAND_FILE_ORDER = [
     "review",
     "ship"
 ];
-export const UTILITY_COMMANDS = ["learn", "next"];
+export const UTILITY_COMMANDS = ["learn", "next", "status"];
 export const SUBAGENT_SKILL_FOLDERS = [
     "subagent-dev",
     "parallel-dispatch"

package/dist/content/hooks.d.ts

@@ -11,6 +11,7 @@ export interface HookRuntimeOptions {
 export declare const RUNTIME_SHELL_DETECT_ROOT = "HARNESS=\"codex\"\nif [ -n \"${CLAUDE_PROJECT_DIR:-}\" ]; then\n  HARNESS=\"claude\"\nelif [ -n \"${CURSOR_PROJECT_DIR:-}\" ] || [ -n \"${CURSOR_PROJECT_ROOT:-}\" ]; then\n  HARNESS=\"cursor\"\nelif [ -n \"${OPENCODE_PROJECT_DIR:-}\" ] || [ -n \"${OPENCODE_PROJECT_ROOT:-}\" ]; then\n  HARNESS=\"opencode\"\nfi\n\nROOT=\"\"\nfor candidate in \"${CCLAW_PROJECT_ROOT:-}\" \"${CLAUDE_PROJECT_DIR:-}\" \"${CURSOR_PROJECT_DIR:-}\" \"${CURSOR_PROJECT_ROOT:-}\" \"${OPENCODE_PROJECT_DIR:-}\" \"${OPENCODE_PROJECT_ROOT:-}\" \"${PWD:-}\"; do\n  if [ -n \"$candidate\" ] && [ -d \"$candidate/.cclaw\" ]; then\n    ROOT=\"$candidate\"\n    break\n  fi\ndone\nif [ -z \"$ROOT\" ]; then\n  ROOT=\"${CCLAW_PROJECT_ROOT:-${CLAUDE_PROJECT_DIR:-${CURSOR_PROJECT_DIR:-${CURSOR_PROJECT_ROOT:-${OPENCODE_PROJECT_DIR:-${OPENCODE_PROJECT_ROOT:-${PWD}}}}}}}\"\nfi";
 export declare function sessionStartScript(_options?: HookRuntimeOptions): string;
 export declare function stopCheckpointScript(): string;
+export declare function preCompactScript(): string;
 export { claudeHooksJsonWithObservation as claudeHooksJson } from "./observe.js";
 export { cursorHooksJsonWithObservation as cursorHooksJson } from "./observe.js";
 export { codexHooksJsonWithObservation as codexHooksJson } from "./observe.js";

package/dist/content/hooks.js

@@ -616,6 +616,151 @@ case "$HARNESS" in
 esac
 `;
 }
+export function preCompactScript() {
+    return `#!/usr/bin/env bash
+# cclaw pre-compact hook — generated by cclaw sync
+# Persists a session digest before the harness compacts/clears context, so the
+# next session-start hook can restore the most important state without the agent
+# having to re-derive it from scratch.
+set -uo pipefail
+
+${DETECT_ROOT}
+
+INPUT=$(cat 2>/dev/null || echo '{}')
+
+STATE_DIR="$ROOT/${RUNTIME_ROOT}/state"
+STATE_FILE="$STATE_DIR/flow-state.json"
+DELEGATION_FILE="$STATE_DIR/delegation-log.json"
+KNOWLEDGE_FILE="$ROOT/${RUNTIME_ROOT}/knowledge.md"
+DIGEST_FILE="$STATE_DIR/session-digest.md"
+DIGEST_TMP="$STATE_DIR/session-digest.md.tmp.$$"
+
+mkdir -p "$STATE_DIR" 2>/dev/null || true
+
+cleanup_digest_tmp() {
+  rm -f "$DIGEST_TMP" 2>/dev/null || true
+}
+trap cleanup_digest_tmp EXIT INT TERM
+
+STAGE="none"
+TRACK="standard"
+COMPLETED="0"
+SKIPPED=""
+ACTIVE_RUN="none"
+PASSED_GATES=""
+BLOCKED_GATES=""
+
+if [ -f "$STATE_FILE" ]; then
+  if command -v jq >/dev/null 2>&1; then
+    STAGE=$(jq -r '.currentStage // "none"' "$STATE_FILE" 2>/dev/null || echo "none")
+    TRACK=$(jq -r '.track // "standard"' "$STATE_FILE" 2>/dev/null || echo "standard")
+    COMPLETED=$(jq -r '(.completedStages // []) | length' "$STATE_FILE" 2>/dev/null || echo "0")
+    SKIPPED=$(jq -r '(.skippedStages // []) | join(",")' "$STATE_FILE" 2>/dev/null || echo "")
+    ACTIVE_RUN=$(jq -r '.activeRunId // "none"' "$STATE_FILE" 2>/dev/null || echo "none")
+    PASSED_GATES=$(jq -r --arg stage "$STAGE" '(.stageGates[$stage].passed // []) | join(",")' "$STATE_FILE" 2>/dev/null || echo "")
+    BLOCKED_GATES=$(jq -r --arg stage "$STAGE" '(.stageGates[$stage].blocked // []) | join(",")' "$STATE_FILE" 2>/dev/null || echo "")
+  elif command -v python3 >/dev/null 2>&1; then
+    OUTPUT=$(python3 - "$STATE_FILE" <<'PY'
+import json, sys
+try:
+    with open(sys.argv[1], "r", encoding="utf-8") as fh:
+        data = json.load(fh)
+except Exception:
+    data = {}
+stage = data.get("currentStage") or "none"
+track = data.get("track") or "standard"
+completed = data.get("completedStages") or []
+skipped = data.get("skippedStages") or []
+run = data.get("activeRunId") or "none"
+gates = (data.get("stageGates") or {}).get(stage) or {}
+passed = gates.get("passed") or []
+blocked = gates.get("blocked") or []
+print(stage)
+print(track)
+print(len(completed) if isinstance(completed, list) else 0)
+print(",".join(skipped) if isinstance(skipped, list) else "")
+print(run)
+print(",".join(passed) if isinstance(passed, list) else "")
+print(",".join(blocked) if isinstance(blocked, list) else "")
+PY
+)
+    {
+      IFS= read -r STAGE
+      IFS= read -r TRACK
+      IFS= read -r COMPLETED
+      IFS= read -r SKIPPED
+      IFS= read -r ACTIVE_RUN
+      IFS= read -r PASSED_GATES
+      IFS= read -r BLOCKED_GATES
+    } <<EOF
+$OUTPUT
+EOF
+  fi
+fi
+
+DELEGATION_PENDING=""
+if [ -f "$DELEGATION_FILE" ] && command -v jq >/dev/null 2>&1; then
+  DELEGATION_PENDING=$(jq -r --arg stage "$STAGE" '
+    (.entries // [])
+    | map(select((.stage // "") == $stage and (.status // "") != "completed" and (.status // "") != "waived"))
+    | map(.agent // "unknown")
+    | unique
+    | join(",")
+  ' "$DELEGATION_FILE" 2>/dev/null || echo "")
+fi
+
+KNOWLEDGE_TAIL=""
+if [ -f "$KNOWLEDGE_FILE" ] && [ -s "$KNOWLEDGE_FILE" ]; then
+  KNOWLEDGE_TAIL=$(tail -n 12 "$KNOWLEDGE_FILE" 2>/dev/null || echo "")
+fi
+
+GIT_HEAD=""
+GIT_BRANCH=""
+GIT_DIRTY="unknown"
+if command -v git >/dev/null 2>&1 && git -C "$ROOT" rev-parse --is-inside-work-tree >/dev/null 2>&1; then
+  GIT_HEAD=$(git -C "$ROOT" rev-parse --short HEAD 2>/dev/null || echo "")
+  GIT_BRANCH=$(git -C "$ROOT" rev-parse --abbrev-ref HEAD 2>/dev/null || echo "")
+  if [ -n "$(git -C "$ROOT" status --porcelain 2>/dev/null)" ]; then
+    GIT_DIRTY="dirty"
+  else
+    GIT_DIRTY="clean"
+  fi
+fi
+
+TS=$(date -u +"%Y-%m-%dT%H:%M:%SZ" 2>/dev/null || echo "")
+
+{
+  printf '# Session Digest\n'
+  printf '_Generated by pre-compact hook at %s_\n\n' "$TS"
+  printf '## Flow snapshot\n'
+  printf '- track: %s\n' "$TRACK"
+  printf '- current stage: %s\n' "$STAGE"
+  printf '- completed: %s stages\n' "$COMPLETED"
+  printf '- skipped: %s\n' "\${SKIPPED:-(none)}"
+  printf '- run: %s\n\n' "$ACTIVE_RUN"
+  printf '## Gates (current stage)\n'
+  printf '- passed: %s\n' "\${PASSED_GATES:-(none)}"
+  printf '- blocked: %s\n\n' "\${BLOCKED_GATES:-(none)}"
+  printf '## Outstanding delegations\n'
+  printf '- pending: %s\n\n' "\${DELEGATION_PENDING:-(none)}"
+  printf '## Git\n'
+  printf '- branch: %s\n' "\${GIT_BRANCH:-(unknown)}"
+  printf '- head: %s\n' "\${GIT_HEAD:-(unknown)}"
+  printf '- worktree: %s\n\n' "$GIT_DIRTY"
+  if [ -n "$KNOWLEDGE_TAIL" ]; then
+    printf '## Knowledge tail\n'
+    printf '%s\n' "$KNOWLEDGE_TAIL"
+  fi
+} > "$DIGEST_TMP" 2>/dev/null || true
+
+if [ -s "$DIGEST_TMP" ]; then
+  mv "$DIGEST_TMP" "$DIGEST_FILE" 2>/dev/null || rm -f "$DIGEST_TMP" 2>/dev/null || true
+fi
+
+trap - EXIT INT TERM
+exit 0
+`;
+}
 // ---------------------------------------------------------------------------
 // hooks.json generators are defined in observe.ts (shared across harnesses).
 // ---------------------------------------------------------------------------

package/dist/content/learnings.js

@@ -20,6 +20,7 @@ Use it 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)
 
 ## HARD-GATE
 
@@ -33,12 +34,25 @@ Under \`/cc-learn\`, only modify the knowledge store (\`${KNOWLEDGE_PATH}\`) or
 - Context: one short line
 - Insight: one short line
 - Reuse: one short line
+- Confidence: high | medium | low      (optional)
+- Domain: api | infra | ui | testing | …  (optional)
+- Project: <repo or scope name>        (optional)
 \`\`\`
 
 Rules:
-- Type must be exactly one of \`rule\`, \`pattern\`, \`lesson\` (lowercase).
-- Never rewrite history silently; append a newer correction entry instead.
+- Type must be exactly one of \`rule\`, \`pattern\`, \`lesson\`, \`compound\` (lowercase).
+- Never rewrite history silently; append a newer correction entry instead. To replace, prefix the new entry with \`Supersedes: <old-title>\`.
 - Keep entries concise and actionable.
+- Optional fields (\`Confidence\`, \`Domain\`, \`Project\`) are forward-compatible and used by the **knowledge-curation** skill — fill them when known.
+
+## Curation policy (target: ≤ 50 active entries)
+
+The knowledge file is append-only, but entries can be **superseded** rather than deleted:
+
+- When you discover a more correct rule, append a new entry with \`Supersedes: <old-title>\`.
+- During \`/cc-learn curate\`, the assistant surfaces candidates for soft-archive (move to \`.cclaw/knowledge.archive.md\`) when the active file exceeds 50 entries or contains stale/duplicate entries.
+
+See the **knowledge-curation** utility skill for the full curation protocol.
 
 ## Subcommands
 
@@ -52,8 +66,13 @@ Rules:
 
 ### \`/cc-learn add\`
 - Ask for: \`type\`, \`short title\`, \`context\`, \`insight\`, \`reuse\`.
+- Optionally ask for: \`confidence\`, \`domain\`, \`project\`.
 - Append one entry using current UTC timestamp.
 - Re-read the file tail and confirm the entry was written.
+
+### \`/cc-learn curate\`
+- Hand off to the **knowledge-curation** skill (read-only audit + soft-archive plan).
+- Never deletes from \`${KNOWLEDGE_PATH}\` without an explicit user-approved archive plan.
 `;
 }
 export function learnCommandContract() {
@@ -73,7 +92,8 @@ Do not edit source code from this command. Only operate on \`${KNOWLEDGE_PATH}\`
 |---|---|---|
 | (default) | — | Show recent knowledge entries (tail view). |
 | \`search\` | \`<query>\` | Search knowledge text for relevant prior rules/patterns/lessons. |
-| \`add\` | — | Append a new entry with type \`rule\` / \`pattern\` / \`lesson\`. |
+| \`add\` | — | Append a new entry with type \`rule\` / \`pattern\` / \`lesson\` / \`compound\`. |
+| \`curate\` | — | Hand off to the **knowledge-curation** skill: read-only audit + soft-archive plan when the active file exceeds the curation threshold. |
 `;
 }
 export function selfImprovementBlock(stageName) {
@@ -96,7 +116,7 @@ cat >> ${KNOWLEDGE_PATH} <<EOF
 EOF
 \`\`\`
 
-Type must be exactly one of: \`rule\`, \`pattern\`, \`lesson\`.
+Type must be exactly one of: \`rule\`, \`pattern\`, \`lesson\`, \`compound\`.
 `;
 }
 export function learningsSearchPreamble(stage) {
@@ -110,7 +130,7 @@ If the file is empty, continue normally.
 export function learningsAgentsMdBlock() {
     return `### Knowledge Store
 
-\`${KNOWLEDGE_PATH}\` — append-only markdown memory with entry types \`rule\`, \`pattern\`, \`lesson\`.
+\`${KNOWLEDGE_PATH}\` — append-only markdown memory with entry types \`rule\`, \`pattern\`, \`lesson\`, \`compound\`.
 At session start and stage transitions, load recent entries and apply relevant ones.
 If a non-obvious reusable rule/pattern/lesson is discovered, append a new entry.
 `;

package/dist/content/meta-skill.js

@@ -89,6 +89,18 @@ These skills live in \`.cclaw/skills/\` but have no slash commands. They activat
 
 **Activation rule:** When a contextual skill applies, read its SKILL.md and follow it as a supplementary lens alongside the current stage. Do not skip the stage workflow — the contextual skill adds depth, not a detour.
 
+## Custom Skills (project-owned, sync-safe)
+
+\`.cclaw/custom-skills/\` is a sync-safe directory. \`cclaw sync\` and \`cclaw upgrade\` **never overwrite** files there.
+
+Use it to add **project-specific** skills that complement the managed library:
+
+- Each skill: \`.cclaw/custom-skills/<folder>/SKILL.md\` with the same frontmatter format as managed skills (\`name\` + \`description\` triggering routing).
+- Activate by mentioning the skill name explicitly, or rely on semantic routing from the description.
+- See \`.cclaw/custom-skills/README.md\` for the full convention and a starter template under \`.cclaw/custom-skills/example/\`.
+
+If a custom skill turns out to generalize (e.g. another project would want the same lens), promote it to a managed skill via a contribution to the cclaw repo — managed skills get versioning and maintenance.
+
 ## Progressive Disclosure (Depth / See Also)
 
 Use this loading order to keep context lean while preserving depth:

package/dist/content/next-command.js

@@ -56,6 +56,14 @@ This is the only progression command the user needs to drive the entire flow. St
 → If current stage's \`next\` is **\`done\`**: report **"Flow complete. All stages finished."** and stop.
 → Otherwise: load **\`${RUNTIME_ROOT}/skills/<skillFolder>/SKILL.md\`** and **\`${RUNTIME_ROOT}/commands/<nextStage>.md\`** for the successor stage. Execute that stage's protocol.
 
+### Track-aware successor resolution
+
+\`flow-state.json\` carries a \`track\` field (\`"quick"\` or \`"standard"\`) and a \`skippedStages\` array.
+
+- If \`track === "quick"\`, the critical path is **spec → tdd → review → ship**. When advancing, skip any stage listed in \`skippedStages\` — i.e. after the current stage completes, pick the next stage that is NOT in \`skippedStages\`.
+- If \`track === "standard"\`, advance through all 8 stages in their natural order.
+- Never reintroduce a skipped stage mid-run. If the user wants upstream scoping work, they must archive the run and start a new one with \`track: "standard"\`.
+
 ## Resume Semantics
 
 \`/cc-next\` in a **new session** = resume from where you left off:

package/dist/content/observe.js

@@ -1613,6 +1613,14 @@ export function claudeHooksJsonWithObservation() {
                             command: `bash ${RUNTIME_ROOT}/hooks/stop-checkpoint.sh`,
                             timeout: 10
                         }]
+                }],
+            PreCompact: [{
+                    matcher: "manual|auto",
+                    hooks: [{
+                            type: "command",
+                            command: `bash ${RUNTIME_ROOT}/hooks/pre-compact.sh`,
+                            timeout: 10
+                        }]
                 }]
         }
     }, null, 2);
@@ -1632,6 +1640,8 @@ export function cursorHooksJsonWithObservation() {
                     command: `bash ${RUNTIME_ROOT}/hooks/session-start.sh`
                 }],
             sessionCompact: [{
+                    command: `bash ${RUNTIME_ROOT}/hooks/pre-compact.sh`
+                }, {
                     command: `bash ${RUNTIME_ROOT}/hooks/session-start.sh`
                 }],
             preToolUse: [{
@@ -1684,6 +1694,14 @@ export function codexHooksJsonWithObservation() {
                             command: `bash ${RUNTIME_ROOT}/hooks/stop-checkpoint.sh`,
                             timeout: 10
                         }]
+                }],
+            PreCompact: [{
+                    matcher: "manual|auto",
+                    hooks: [{
+                            type: "command",
+                            command: `bash ${RUNTIME_ROOT}/hooks/pre-compact.sh`,
+                            timeout: 10
+                        }]
                 }]
         }
     }, null, 2);

package/dist/content/session-hooks.js

@@ -34,7 +34,7 @@ When a new session begins in any harness:
 ### What to show the user at session start
 
 \`\`\`
-Cclaw flow state: [current stage] ([N] of 9 stages completed)
+Cclaw flow state: [current stage] ([N] of 8 stages completed)
 Knowledge highlights: [rule/pattern 1], [rule/pattern 2], [rule/pattern 3]
 Next action: /cc-[stage] to continue, or describe what you'd like to do.
 \`\`\`

package/dist/content/stage-schema.js

@@ -1147,7 +1147,8 @@ const REVIEW = {
         { id: "review_layer2_architecture", description: "Architecture fit review completed." },
         { id: "review_severity_classified", description: "All findings are severity-tagged." },
         { id: "review_criticals_resolved", description: "No unresolved critical blockers remain." },
-        { id: "review_army_json_valid", description: "07-review-army.json passes schema validation (validateReviewArmy)." }
+        { id: "review_army_json_valid", description: "07-review-army.json passes schema validation (validateReviewArmy)." },
+        { id: "review_completeness_scored", description: "Completeness score is computed and recorded (AC coverage, task coverage, slice coverage, adversarial pass)." }
     ],
     requiredEvidence: [
         "Artifact written to `.cclaw/artifacts/07-review.md`.",
@@ -1289,6 +1290,7 @@ const REVIEW = {
         { section: "Layer 2 Findings", required: true, validationRule: "Each finding has severity, description, and resolution status." },
         { section: "Review Army Contract", required: true, validationRule: "Structured findings include id/severity/confidence/fingerprint/reportedBy/status with dedup reconciliation summary." },
         { section: "Review Readiness Dashboard", required: true, validationRule: "At least 4 readiness checklist lines including blocker and recommendation status." },
+        { section: "Completeness Score", required: true, validationRule: "Records AC coverage, task coverage, test-slice coverage, and adversarial-review pass status as numeric or boolean values. At minimum, a line like 'AC coverage: N/M' or 'AC coverage: 100%'." },
         { section: "Severity Summary", required: true, validationRule: "Per-severity count lines for critical, important, and suggestion buckets." },
         { section: "Final Verdict", required: true, validationRule: "Exactly one of: APPROVED, APPROVED_WITH_CONCERNS, BLOCKED." }
     ],
@@ -1450,7 +1452,8 @@ const SHIP = {
         { section: "Rollback Plan", required: true, validationRule: "Trigger conditions, rollback steps (exact commands), verification steps." },
         { section: "Monitoring", required: false, validationRule: "If applicable: what metrics/logs to watch post-deploy. Risk note if no monitoring." },
         { section: "Finalization", required: true, validationRule: "Exactly one finalization enum token selected. Execution result documented. Worktree cleaned if applicable." },
-        { section: "Completion Status", required: false, validationRule: "If present: exactly one of SHIPPED, SHIPPED_WITH_EXCEPTIONS, BLOCKED. Exceptions documented when applicable." }
+        { section: "Completion Status", required: false, validationRule: "If present: exactly one of SHIPPED, SHIPPED_WITH_EXCEPTIONS, BLOCKED. Exceptions documented when applicable." },
+        { section: "Compound Step", required: false, validationRule: "Optional retrospective: at least one bullet of the form 'Insight: ... | Action: append [compound] entry to .cclaw/knowledge.md', or an explicit 'No compound insight this run.' line." }
     ],
     namedAntiPattern: {
         title: "Green CI Means Safe to Merge",
@@ -1512,6 +1515,13 @@ const STAGE_AUTO_SUBAGENT_DISPATCH = {
             when: "When acceptance criteria are unclear or constraints conflict.",
             purpose: "Normalize measurable criteria and testability mapping.",
             requiresUserGate: false
+        },
+        {
+            agent: "spec-reviewer",
+            mode: "proactive",
+            when: "When acceptance criteria and edge cases are drafted and need independent validation before plan stage.",
+            purpose: "Independent review of spec against measurability, testability, and completeness before locking the contract for plan.",
+            requiresUserGate: false
         }
     ],
     plan: [

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

@@ -0,0 +1,9 @@
+/**
+ * Command contract for /cc-status — a read-only snapshot command.
+ * Does not mutate state. Always safe to run.
+ */
+export declare function statusCommandContract(): string;
+/**
+ * Skill body for /cc-status — read-only status snapshot.
+ */
+export declare function statusCommandSkillMarkdown(): string;