cclaw-cli 0.12.0 → 0.14.0

package/dist/content/learnings.js

@@ -137,38 +137,9 @@ Do not edit source code from this command. Only operate on \`${KNOWLEDGE_PATH}\`
 export function selfImprovementBlock(stageName) {
     return `## Operational Self-Improvement
 
-After this stage, ask:
-- Did I discover a non-obvious reusable **rule** or **pattern**?
-- Did a failure reveal a reusable **lesson**?
-
-If yes, append one concise JSON line to the canonical knowledge store
-(\`${KNOWLEDGE_PATH}\`) using the strict 8-field schema:
-
-\`\`\`bash
-TS="$(date -u +%Y-%m-%dT%H:%M:%SZ)"
-printf '%s\\n' '{"type":"pattern","trigger":"when <situation>","action":"<concrete move>","confidence":"medium","domain":null,"stage":"${stageName}","created":"'"$TS"'","project":null}' >> ${KNOWLEDGE_PATH}
-\`\`\`
-
-Type must be exactly one of: \`rule\`, \`pattern\`, \`lesson\`, \`compound\`.
-Fields must appear in the order: \`type, trigger, action, confidence, domain, stage, created, project\`.
-Missing optional values must be emitted as \`null\`, never omitted.
-`;
-}
-export function learningsSearchPreamble(stage) {
-    return `## Prior Knowledge (load at stage start)
-
-Before stage work, stream \`${KNOWLEDGE_PATH}\` and filter for entries relevant to
-this stage (\`${stage}\`), affected domains, and key constraints. Apply matching
-entries explicitly. If the file is empty, continue normally.
-`;
-}
-export function learningsAgentsMdBlock() {
-    return `### Knowledge Store
-
-\`${KNOWLEDGE_PATH}\` — append-only JSONL memory with entry types \`rule\`, \`pattern\`, \`lesson\`, \`compound\`.
-Strict 8-field schema: \`type, trigger, action, confidence, domain, stage, created, project\`.
-At session start and stage transitions, tail the file and apply relevant entries.
-If a non-obvious reusable rule/pattern/lesson is discovered, append a new line
-through \`/cc-learn add\` (never hand-edit).
+Before closeout, capture 1-3 reusable insights in \`${KNOWLEDGE_PATH}\` whenever
+the stage produced non-obvious decisions, patterns, or lessons.
+Prefer \`type=rule|pattern|lesson\` (\`compound\` stays retro-only) and set
+\`stage: "${stageName}"\` unless the insight is explicitly cross-stage.
 `;
 }

package/dist/content/meta-skill.js

@@ -3,7 +3,7 @@ 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 /cc-learn."
+description: "Routing brain for cclaw. Decide whether to start/resume a stage, answer directly, or use utility commands like /cc-learn, /cc-view, and /cc-ops."
 ---
 
 # Using Cclaw
@@ -26,7 +26,9 @@ Task arrives
   ├─ Pure question / non-software ask? -> answer directly (no stage)
   ├─ New software work? -> /cc <idea>
   ├─ Resume existing flow? -> /cc or /cc-next
-  └─ Knowledge operation? -> /cc-learn
+  ├─ Knowledge operation? -> /cc-learn
+  ├─ Read-only workspace view? -> /cc-view [status|tree|diff]
+  └─ Workspace operation? -> /cc-ops [feature|tdd-log|retro|archive|rewind|rewind-ack]
 \`\`\`
 
 ## Task classification

package/dist/content/next-command.js

@@ -33,17 +33,18 @@ This is the only progression command the user needs to drive the entire flow. St
 
 - **Do not** invent gate completion: use only \`${flowPath}\` plus observable evidence in repo artifacts.
 - **Do not** skip stages: advance only from \`currentStage\` to its configured successor.
-- If the flow is at the terminal stage with all ship gates satisfied, **report completion**.
+- If the flow reaches terminal ship completion, route closeout in order: **/cc-retro -> /cc-archive**.
 
 ## Algorithm (mandatory)
 
 1. Read **\`${flowPath}\`**. If missing → **BLOCKED** (state missing).
 2. Parse JSON. Capture \`currentStage\` and \`stageGateCatalog[currentStage]\`.
-3. Let \`G\` = \`requiredGates\` for **\`currentStage\`** from the stage schema.
-4. Let \`catalog\` = \`stageGateCatalog[currentStage]\` from flow state.
-5. **Satisfied** for gate id \`g\`: \`g\` in \`catalog.passed\` and \`g\` not in \`catalog.blocked\`.
-6. Let \`M\` = \`mandatoryDelegations\` for \`currentStage\`.
-7. If \`M\` is non-empty, inspect **\`${delegationPath}\`**. Treat as satisfied only if the agent is **completed** or **waived**.
+3. If \`staleStages[currentStage]\` exists, do not advance automatically. Re-run the stage artifact work, then clear the marker with \`/cc-rewind-ack <currentStage>\`.
+4. Let \`G\` = \`requiredGates\` for **\`currentStage\`** from the stage schema.
+5. Let \`catalog\` = \`stageGateCatalog[currentStage]\` from flow state.
+6. **Satisfied** for gate id \`g\`: \`g\` in \`catalog.passed\` and \`g\` not in \`catalog.blocked\`.
+7. Let \`M\` = \`mandatoryDelegations\` for \`currentStage\`.
+8. If \`M\` is non-empty, inspect **\`${delegationPath}\`**. Treat as satisfied only if the agent is **completed** or **waived**.
 
 ### Path A: Current stage is NOT complete (any gate unmet or delegation missing)
 
@@ -53,7 +54,10 @@ This is the only progression command the user needs to drive the entire flow. St
 
 ### Path B: Current stage IS complete (all gates passed, all delegations satisfied)
 
-→ If current stage's \`next\` is **\`done\`**: report **"Flow complete. All stages finished."** and stop.
+→ If current stage's \`next\` is **\`done\`**:
+  - if \`currentStage === "ship"\` and \`retro.completedAt\` is missing -> route to \`/cc-retro\`,
+  - if \`currentStage === "ship"\` and \`retro.completedAt\` is present -> route to \`/cc-archive\`,
+  - otherwise 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
@@ -120,7 +124,8 @@ Do **not** mark gates satisfied from memory alone. Cite **artifact evidence** (p
 
 1. Open **\`${flowPath}\`**.
 2. Record \`currentStage\` and \`stageGateCatalog[currentStage]\`.
-3. If the file is missing or invalid JSON → **BLOCKED** (report and stop).
+3. If \`staleStages[currentStage]\` exists, re-run the stage and clear marker via \`/cc-rewind-ack <currentStage>\` before advancing.
+4. If the file is missing or invalid JSON → **BLOCKED** (report and stop).
 
 ### Step 2: Evaluate gates
 
@@ -142,7 +147,11 @@ Execute the stage protocol. The stage skill handles interaction, STOP points, ga
 
 **Path B — stage IS complete (all gates met, all delegations done):**
 
-If \`next\` is \`done\` → report **"Flow complete. All stages finished."** and stop.
+If \`next\` is \`done\`:
+
+- If \`currentStage\` is \`ship\` and \`retro.completedAt\` is missing -> route to \`/cc-retro\`.
+- If \`currentStage\` is \`ship\` and \`retro.completedAt\` exists -> route to \`/cc-archive\`.
+- Otherwise report **"Flow complete. All stages finished."** and stop.
 
 Otherwise load the next stage's skill and command contract, begin execution.
 

package/dist/content/observe.d.ts

@@ -9,7 +9,11 @@ export interface PromptGuardOptions {
     strictMode?: boolean;
 }
 export declare function promptGuardScript(options?: PromptGuardOptions): string;
-export declare function workflowGuardScript(): string;
+export interface WorkflowGuardOptions {
+    tddEnforcementMode?: "advisory" | "strict";
+    tddTestGlobs?: string[];
+}
+export declare function workflowGuardScript(options?: WorkflowGuardOptions): string;
 export declare function observeScript(): string;
 export declare function contextMonitorScript(): string;
 export declare function summarizeObservationsRuntimeModule(): string;

package/dist/content/observe.js

@@ -153,18 +153,25 @@ fi
 exit 0
 `;
 }
-export function workflowGuardScript() {
+export function workflowGuardScript(options = {}) {
+    const tddEnforcementMode = options.tddEnforcementMode === "strict" ? "strict" : "advisory";
+    const tddTestGlobs = options.tddTestGlobs && options.tddTestGlobs.length > 0
+        ? options.tddTestGlobs.join(",")
+        : "**/*.test.*,**/*.spec.*,**/test/**";
     return `#!/usr/bin/env bash
 # cclaw workflow guard hook — generated by cclaw sync
 # Enforces stage-aware command discipline and recent flow-state read hygiene.
 set -uo pipefail
 WORKFLOW_GUARD_MODE="\${CCLAW_WORKFLOW_GUARD_MODE:-advisory}"
 MAX_FLOW_READ_AGE_SEC="\${CCLAW_WORKFLOW_GUARD_MAX_AGE_SEC:-1800}"
+TDD_ENFORCEMENT_MODE="${tddEnforcementMode}"
+TDD_TEST_GLOBS="${tddTestGlobs}"
 
 ${RUNTIME_SHELL_DETECT_ROOT}
 
 STATE_DIR="$ROOT/${RUNTIME_ROOT}/state"
 FLOW_STATE_FILE="$STATE_DIR/flow-state.json"
+TDD_LOG_FILE="$STATE_DIR/tdd-cycle-log.jsonl"
 GUARD_STATE_FILE="$STATE_DIR/workflow-guard.json"
 GUARD_LOG="$STATE_DIR/workflow-guard.jsonl"
 mkdir -p "$STATE_DIR" 2>/dev/null || true
@@ -234,9 +241,11 @@ NOW_EPOCH=$(date +%s 2>/dev/null || echo "0")
 REASONS=""
 
 CURRENT_STAGE="none"
+CURRENT_RUN="active"
 if [ -f "$FLOW_STATE_FILE" ]; then
   if command -v jq >/dev/null 2>&1; then
     CURRENT_STAGE=$(jq -r '.currentStage // "none"' "$FLOW_STATE_FILE" 2>/dev/null || echo "none")
+    CURRENT_RUN=$(jq -r '.activeRunId // "active"' "$FLOW_STATE_FILE" 2>/dev/null || echo "active")
   elif command -v python3 >/dev/null 2>&1; then
     CURRENT_STAGE=$(python3 - "$FLOW_STATE_FILE" <<'PY'
 import json
@@ -252,6 +261,21 @@ except Exception:
     pass
 print(stage)
 PY
+)
+    CURRENT_RUN=$(python3 - "$FLOW_STATE_FILE" <<'PY'
+import json
+import sys
+run_id = "active"
+try:
+    with open(sys.argv[1], "r", encoding="utf-8") as fh:
+        parsed = json.load(fh)
+    value = parsed.get("activeRunId")
+    if isinstance(value, str) and value:
+        run_id = value
+except Exception:
+    pass
+print(run_id)
+PY
 )
   fi
 fi
@@ -325,6 +349,99 @@ is_preimplementation_stage() {
   esac
 }
 
+is_tdd_test_payload() {
+  local text="$1"
+  if printf '%s' "$text" | grep -Eq '/tests?/|\\.test\\.|\\.spec\\.'; then
+    return 0
+  fi
+  if printf '%s' "$TDD_TEST_GLOBS" | grep -Eq '.' && printf '%s' "$text" | grep -Eq '(test|spec)'; then
+    return 0
+  fi
+  return 1
+}
+
+is_tdd_runtime_write_payload() {
+  local text="$1"
+  if printf '%s' "$text" | grep -Eq '\\.cclaw/'; then
+    return 1
+  fi
+  if ! printf '%s' "$text" | grep -Eq '\\.(ts|tsx|js|jsx|mjs|cjs|py|go|rs|java|kt|rb|php|cs|swift)'; then
+    return 1
+  fi
+  if is_tdd_test_payload "$text"; then
+    return 1
+  fi
+  return 0
+}
+
+has_open_red_cycle() {
+  if [ ! -f "$TDD_LOG_FILE" ] || [ ! -s "$TDD_LOG_FILE" ]; then
+    return 1
+  fi
+  local red_count="0"
+  local green_count="0"
+  if command -v jq >/dev/null 2>&1; then
+    red_count=$(jq -r --arg run "$CURRENT_RUN" 'select((.runId // $run) == $run and .phase == "red") | .phase' "$TDD_LOG_FILE" 2>/dev/null | wc -l | tr -d ' ' || echo "0")
+    green_count=$(jq -r --arg run "$CURRENT_RUN" 'select((.runId // $run) == $run and .phase == "green") | .phase' "$TDD_LOG_FILE" 2>/dev/null | wc -l | tr -d ' ' || echo "0")
+  elif command -v python3 >/dev/null 2>&1; then
+    red_count=$(python3 - "$TDD_LOG_FILE" "$CURRENT_RUN" <<'PY'
+import json
+import sys
+count = 0
+run_id = sys.argv[2]
+with open(sys.argv[1], "r", encoding="utf-8") as fh:
+    for raw in fh:
+        raw = raw.strip()
+        if not raw:
+            continue
+        try:
+            parsed = json.loads(raw)
+        except Exception:
+            continue
+        if not isinstance(parsed, dict):
+            continue
+        if str(parsed.get("runId", run_id)) != run_id:
+            continue
+        if parsed.get("phase") == "red":
+            count += 1
+print(count)
+PY
+)
+    green_count=$(python3 - "$TDD_LOG_FILE" "$CURRENT_RUN" <<'PY'
+import json
+import sys
+count = 0
+run_id = sys.argv[2]
+with open(sys.argv[1], "r", encoding="utf-8") as fh:
+    for raw in fh:
+        raw = raw.strip()
+        if not raw:
+            continue
+        try:
+            parsed = json.loads(raw)
+        except Exception:
+            continue
+        if not isinstance(parsed, dict):
+            continue
+        if str(parsed.get("runId", run_id)) != run_id:
+            continue
+        if parsed.get("phase") == "green":
+            count += 1
+print(count)
+PY
+)
+  else
+    red_count=$(grep -ci '"phase"[[:space:]]*:[[:space:]]*"red"' "$TDD_LOG_FILE" 2>/dev/null || echo "0")
+    green_count=$(grep -ci '"phase"[[:space:]]*:[[:space:]]*"green"' "$TDD_LOG_FILE" 2>/dev/null || echo "0")
+  fi
+  [ -n "$red_count" ] || red_count="0"
+  [ -n "$green_count" ] || green_count="0"
+  if [ "$red_count" -gt "$green_count" ]; then
+    return 0
+  fi
+  return 1
+}
+
 detect_target_stage() {
   local text="$1"
   for stage in brainstorm scope design spec plan tdd review ship; do
@@ -373,6 +490,18 @@ if is_preimplementation_stage "$CURRENT_STAGE" && is_mutating_tool "$TOOL_LOWER"
   fi
 fi
 
+if [ "$CURRENT_STAGE" = "tdd" ] && is_mutating_tool "$TOOL_LOWER"; then
+  if is_tdd_runtime_write_payload "$PAYLOAD_LOWER"; then
+    if ! has_open_red_cycle; then
+      if [ -n "$REASONS" ]; then
+        REASONS="$REASONS,tdd_write_without_open_red"
+      else
+        REASONS="tdd_write_without_open_red"
+      fi
+    fi
+  fi
+fi
+
 if is_preimplementation_stage "$CURRENT_STAGE" && ! is_plan_mode_safe_tool "$TOOL_LOWER"; then
   if ! is_mutating_tool "$TOOL_LOWER"; then
     if ! printf '%s' "$PAYLOAD_LOWER" | grep -Eq '\.cclaw/' && ! is_cclaw_cli_payload "$PAYLOAD_LOWER"; then
@@ -438,7 +567,7 @@ PY
 fi
 
 if [ -n "$REASONS" ]; then
-  NOTE="Cclaw workflow guard: detected potential flow violation (\${REASONS}). Re-read ${RUNTIME_ROOT}/state/flow-state.json, avoid source edits before tdd stage, and continue from current stage ordering."
+  NOTE="Cclaw workflow guard: detected potential flow violation (\${REASONS}). Re-read ${RUNTIME_ROOT}/state/flow-state.json, avoid source edits before tdd stage, and enforce RED -> GREEN -> REFACTOR discipline inside tdd."
   if command -v jq >/dev/null 2>&1; then
     ENTRY=$(jq -n -c \
       --arg ts "$TS" \
@@ -458,6 +587,9 @@ if [ -n "$REASONS" ]; then
   if printf '%s' "$REASONS" | grep -Eq 'implementation_write_before_'; then
     SHOULD_BLOCK="true"
   fi
+  if printf '%s' "$REASONS" | grep -Eq 'tdd_write_without_open_red' && [ "$TDD_ENFORCEMENT_MODE" = "strict" ]; then
+    SHOULD_BLOCK="true"
+  fi
   if [ "$WORKFLOW_GUARD_MODE" = "strict" ] || [ "$SHOULD_BLOCK" = "true" ]; then
     printf '[cclaw] %s (blocked by workflow guard)\n' "$NOTE" >&2
     exit 1

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

@@ -0,0 +1,2 @@
+export declare function opsCommandContract(): string;
+export declare function opsCommandSkillMarkdown(): string;

package/dist/content/ops-command.js

@@ -0,0 +1,60 @@
+import { RUNTIME_ROOT } from "../constants.js";
+const OPS_SKILL_FOLDER = "flow-ops";
+const OPS_SKILL_NAME = "flow-ops";
+export function opsCommandContract() {
+    return `# /cc-ops
+
+## Purpose
+
+Unified operational command surface for non-stage flow actions.
+
+Subcommands:
+- \`feature\` -> \`/cc-feature\`
+- \`tdd-log\` -> \`/cc-tdd-log\`
+- \`retro\` -> \`/cc-retro\`
+- \`archive\` -> \`/cc-archive\`
+- \`rewind\` -> \`/cc-rewind\`
+- \`rewind-ack\` -> \`/cc-rewind-ack\`
+
+## HARD-GATE
+
+- \`/cc-ops\` is a routing wrapper; execute only one target subcommand per call.
+- Preserve target command safety contracts (retro gate, archive gate, rewind atomicity, etc.).
+
+## Routing
+
+1. Parse required subcommand token.
+2. Dispatch:
+   - \`feature\` -> \`${RUNTIME_ROOT}/commands/feature.md\`
+   - \`tdd-log\` -> \`${RUNTIME_ROOT}/commands/tdd-log.md\`
+   - \`retro\` -> \`${RUNTIME_ROOT}/commands/retro.md\`
+   - \`archive\` -> \`${RUNTIME_ROOT}/commands/archive.md\`
+   - \`rewind\` -> \`${RUNTIME_ROOT}/commands/rewind.md\`
+   - \`rewind-ack\` -> \`${RUNTIME_ROOT}/commands/rewind-ack.md\`
+3. Unknown subcommand -> print supported values and stop.
+
+## Primary skill
+
+**${RUNTIME_ROOT}/skills/${OPS_SKILL_FOLDER}/SKILL.md**
+`;
+}
+export function opsCommandSkillMarkdown() {
+    return `---
+name: ${OPS_SKILL_NAME}
+description: "Unified operational router for feature/tdd-log/retro/archive/rewind commands."
+---
+
+# /cc-ops
+
+## HARD-GATE
+
+This wrapper only dispatches. It must not apply state mutations itself.
+
+## Protocol
+
+1. Require a subcommand (\`feature|tdd-log|retro|archive|rewind|rewind-ack\`).
+2. Route to the matching command contract + skill pair.
+3. Preserve pass-through args after the subcommand (e.g. \`/cc-ops rewind design\`).
+4. Echo which subcommand was dispatched for auditability.
+`;
+}

package/dist/content/protocols.js

@@ -46,8 +46,20 @@ Shared closeout sequence applied by every stage skill.
    - update \`guardEvidence\`.
 3. Persist stage artifact under \`.cclaw/artifacts/\`.
 4. Run \`npx cclaw doctor\` and resolve failures.
-5. Notify user with stage completion and next action (\`/cc-next\`).
-6. Stop; do not auto-run the next stage unless user asks.
+5. Capture reusable learnings from this stage artifact:
+   - append 1-3 strict-schema JSONL entries when the stage produced non-obvious
+     decisions, patterns, or lessons,
+   - use \`type=rule|pattern|lesson\` (\`compound\` stays retro-focused).
+6. Notify user with stage completion and next action (\`/cc-next\`).
+7. Stop; do not auto-run the next stage unless user asks.
+
+## Automatic learning capture policy
+
+- \`standard\` / \`medium\` tracks: required for \`design\`, \`tdd\`, and \`review\`;
+  recommended for other stages.
+- \`quick\` track: recommended only (avoid overhead for tiny fixes).
+- "No learning captured" is acceptable only when explicitly justified (e.g. pure
+  mechanical change, no new trade-offs).
 
 ## Resume protocol
 

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

@@ -0,0 +1,2 @@
+export declare function retroCommandContract(): string;
+export declare function retroCommandSkillMarkdown(): string;

package/dist/content/retro-command.js

@@ -0,0 +1,77 @@
+import { RUNTIME_ROOT } from "../constants.js";
+const RETRO_SKILL_FOLDER = "flow-retro";
+const RETRO_SKILL_NAME = "flow-retro";
+function flowStatePath() {
+    return `${RUNTIME_ROOT}/state/flow-state.json`;
+}
+function retroArtifactPath() {
+    return `${RUNTIME_ROOT}/artifacts/09-retro.md`;
+}
+function knowledgePath() {
+    return `${RUNTIME_ROOT}/knowledge.jsonl`;
+}
+export function retroCommandContract() {
+    return `# /cc-retro
+
+## Purpose
+
+Mandatory retrospective gate before archive once ship is complete.
+
+## HARD-GATE
+
+- Do not mark retro complete without writing \`${retroArtifactPath()}\`.
+- Do not finish retro without appending at least one \`type=compound\` entry into \`${knowledgePath()}\`.
+
+## Algorithm
+
+1. Read \`${flowStatePath()}\`; confirm ship stage is complete for current run.
+2. Synthesize retrospective artifact \`${retroArtifactPath()}\` with:
+   - what slowed this run
+   - what accelerated this run
+   - concrete repeatable rule for next run
+3. Append >=1 strict-schema JSONL entry to \`${knowledgePath()}\` with:
+   - \`type: "compound"\`
+   - \`stage: "ship"\` or \`"retro"\`
+4. Update flow-state \`retro\` block:
+   - \`required: true\`
+   - \`completedAt: <ISO>\`
+   - \`compoundEntries: <count>\`
+5. Report completion summary and remind user that \`/cc-archive\` is now unblocked.
+
+## Primary skill
+
+**${RUNTIME_ROOT}/skills/${RETRO_SKILL_FOLDER}/SKILL.md**
+`;
+}
+export function retroCommandSkillMarkdown() {
+    return `---
+name: ${RETRO_SKILL_NAME}
+description: "Run mandatory retrospective and record compound knowledge before archive."
+---
+
+# /cc-retro
+
+## HARD-GATE
+
+Archive must remain blocked until retro artifact exists and compound knowledge was appended.
+
+## Protocol
+
+1. Confirm ship completion from \`${flowStatePath()}\`.
+2. Create/update \`${retroArtifactPath()}\` with concise retrospective sections:
+   - outcomes
+   - bottlenecks
+   - reusable acceleration patterns
+3. Append at least one \`compound\` knowledge entry into \`${knowledgePath()}\`.
+4. Update \`flow-state.json.retro\` with completion timestamp + compound count.
+5. Print explicit completion line:
+   - \`retro gate: complete\`
+   - \`compound entries added: <N>\`
+
+## Validation
+
+- \`${retroArtifactPath()}\` exists and is non-empty.
+- \`${knowledgePath()}\` contains >=1 valid \`compound\` line.
+- \`retro.completedAt\` is set in flow-state.
+`;
+}

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

@@ -0,0 +1,3 @@
+export declare function rewindCommandContract(): string;
+export declare function rewindAcknowledgeCommandContract(): string;
+export declare function rewindCommandSkillMarkdown(): string;

package/dist/content/rewind-command.js

@@ -0,0 +1,120 @@
+import { RUNTIME_ROOT } from "../constants.js";
+const REWIND_SKILL_FOLDER = "flow-rewind";
+const REWIND_SKILL_NAME = "flow-rewind";
+function flowStatePath() {
+    return `${RUNTIME_ROOT}/state/flow-state.json`;
+}
+function artifactsPath() {
+    return `${RUNTIME_ROOT}/artifacts`;
+}
+function rewindLogPath() {
+    return `${RUNTIME_ROOT}/state/rewind-log.jsonl`;
+}
+export function rewindCommandContract() {
+    return `# /cc-rewind
+
+## Purpose
+
+Rewind active flow to an earlier stage and atomically invalidate downstream work.
+
+## HARD-GATE
+
+- Never rewind without preserving downstream artifact history.
+- Mark downstream stages as stale; do not leave completedStages pointing to invalidated work.
+- Record a rewind reason in \`${rewindLogPath()}\`.
+
+## Inputs
+
+\`/cc-rewind <target-stage> [reason]\`
+
+## Algorithm
+
+1. Read \`${flowStatePath()}\` and current track.
+2. Validate \`target-stage\` belongs to the active track and is not ahead of current stage.
+3. Compute downstream stages to invalidate (all stages after target that were completed or current).
+4. Archive downstream artifacts into \`${artifactsPath()}/_rewind-archive/<rewind-id>/\`.
+5. Rename active downstream artifacts to \`*.stale.md\`.
+6. Update flow-state:
+   - \`currentStage = target-stage\`
+   - trim \`completedStages\` to stages before target-stage
+   - clear gate evidence/catalog for target-stage and downstream
+   - mark downstream entries in \`staleStages\`
+   - append \`rewinds[]\` record
+7. Append JSON line to \`${rewindLogPath()}\`.
+
+## Output
+
+- Rewind id
+- from -> to stage
+- Invalidated stages list
+- Number of stale artifacts
+
+## Primary skill
+
+**${RUNTIME_ROOT}/skills/${REWIND_SKILL_FOLDER}/SKILL.md**
+`;
+}
+export function rewindAcknowledgeCommandContract() {
+    return `# /cc-rewind-ack
+
+## Purpose
+
+Acknowledge and clear stale-stage markers after downstream work is intentionally redone.
+
+## Input
+
+\`/cc-rewind-ack <stage>\`
+
+## HARD-GATE
+
+- Only clear stale marker for the requested stage.
+- Never modify completedStages from this command.
+
+## Algorithm
+
+1. Read \`${flowStatePath()}\`.
+2. If \`staleStages.<stage>\` is missing, report no-op.
+3. Remove \`staleStages.<stage>\`.
+4. Write updated flow-state.
+5. Print remaining stale stages (if any).
+
+## Primary skill
+
+**${RUNTIME_ROOT}/skills/${REWIND_SKILL_FOLDER}/SKILL.md**
+`;
+}
+export function rewindCommandSkillMarkdown() {
+    return `---
+name: ${REWIND_SKILL_NAME}
+description: "Rewind active flow stage safely and acknowledge stale invalidations."
+---
+
+# /cc-rewind + /cc-rewind-ack
+
+## HARD-GATE
+
+Rewind is an atomic state transition. Never leave flow-state half-updated (for example currentStage changed but stale markers/artifact archive missing).
+
+## Protocol
+
+### rewind
+1. Validate target stage belongs to current track and is upstream.
+2. Archive downstream artifacts under \`${artifactsPath()}/_rewind-archive/<rewind-id>/\`.
+3. Mark downstream artifacts as stale (\`*.stale.md\`).
+4. Reset downstream gate catalog and guard evidence.
+5. Record \`rewinds[]\` and \`staleStages\` in flow-state.
+6. Append rewind entry into \`${rewindLogPath()}\`.
+
+### rewind-ack
+1. Load flow-state stale map.
+2. Remove exactly one stale stage marker.
+3. Report remaining stale stages.
+
+## Validation checklist
+
+- \`${flowStatePath()}\` remains valid JSON.
+- \`currentStage\` equals requested rewind target.
+- invalidated stages are absent from \`completedStages\`.
+- archived copies exist for each moved artifact.
+`;
+}

package/dist/content/skills.js

@@ -1,5 +1,6 @@
 import { RUNTIME_ROOT } from "../constants.js";
 import { STAGE_EXAMPLES_REFERENCE_DIR, stageDomainExamples, stageExamples, stageGoodBadExamples } from "./examples.js";
+import { selfImprovementBlock } from "./learnings.js";
 import { STAGE_COMMON_GUIDANCE_REL_PATH } from "./stage-common-guidance.js";
 import { stageAutoSubagentDispatch, stageSchema } from "./stage-schema.js";
 const VERIFICATION_STAGES = ["tdd", "review", "ship"];
@@ -377,6 +378,7 @@ ${mergedAntiPatterns(schema)}
 ## Verification
 ${schema.exitCriteria.map((item) => `- [ ] ${item}`).join("\n")}
 
+${selfImprovementBlock(schema.stage)}
 ${completionParametersBlock(schema)}
 ## Shared Stage Guidance
 See:

package/dist/content/stage-common-guidance.js

@@ -59,7 +59,8 @@ Rollback / fallback: <if decision proves wrong>
 ## Self-improvement reminder
 
 If a reusable lesson appears during the stage, append one strict-schema JSONL
-entry via \`/cc-learn add\`. Do not keep operational lessons only in chat.
+entry (manually via \`/cc-learn add\` or directly in stage closeout protocol).
+Do not keep operational lessons only in chat.
 
 ## Progressive disclosure baseline