cclaw-cli 0.12.0 → 0.14.0

package/dist/install.js

@@ -10,6 +10,15 @@ import { learnSkillMarkdown, learnCommandContract } from "./content/learnings.js
 import { nextCommandContract, nextCommandSkillMarkdown } from "./content/next-command.js";
 import { startCommandContract, startCommandSkillMarkdown } from "./content/start-command.js";
 import { statusCommandContract, statusCommandSkillMarkdown } from "./content/status-command.js";
+import { treeCommandContract, treeCommandSkillMarkdown } from "./content/tree-command.js";
+import { diffCommandContract, diffCommandSkillMarkdown } from "./content/diff-command.js";
+import { viewCommandContract, viewCommandSkillMarkdown } from "./content/view-command.js";
+import { opsCommandContract, opsCommandSkillMarkdown } from "./content/ops-command.js";
+import { featureCommandContract, featureCommandSkillMarkdown } from "./content/feature-command.js";
+import { tddLogCommandContract, tddLogCommandSkillMarkdown } from "./content/tdd-log-command.js";
+import { retroCommandContract, retroCommandSkillMarkdown } from "./content/retro-command.js";
+import { archiveCommandContract, archiveCommandSkillMarkdown } from "./content/archive-command.js";
+import { rewindAcknowledgeCommandContract, rewindCommandContract, rewindCommandSkillMarkdown } from "./content/rewind-command.js";
 import { subagentDrivenDevSkill, parallelAgentsSkill } from "./content/subagents.js";
 import { sessionHooksSkillMarkdown } from "./content/session-hooks.js";
 import { sessionStartScript, stopCheckpointScript, preCompactScript, opencodePluginJs, claudeHooksJson, cursorHooksJson, codexHooksJson } from "./content/hooks.js";
@@ -196,7 +205,16 @@ async function writeSkills(projectRoot, config) {
     await writeFileSafe(runtimePath(projectRoot, "skills", "learnings", "SKILL.md"), learnSkillMarkdown());
     await writeFileSafe(runtimePath(projectRoot, "skills", "flow-next-step", "SKILL.md"), nextCommandSkillMarkdown());
     await writeFileSafe(runtimePath(projectRoot, "skills", "flow-start", "SKILL.md"), startCommandSkillMarkdown());
+    await writeFileSafe(runtimePath(projectRoot, "skills", "flow-view", "SKILL.md"), viewCommandSkillMarkdown());
     await writeFileSafe(runtimePath(projectRoot, "skills", "flow-status", "SKILL.md"), statusCommandSkillMarkdown());
+    await writeFileSafe(runtimePath(projectRoot, "skills", "flow-tree", "SKILL.md"), treeCommandSkillMarkdown());
+    await writeFileSafe(runtimePath(projectRoot, "skills", "flow-diff", "SKILL.md"), diffCommandSkillMarkdown());
+    await writeFileSafe(runtimePath(projectRoot, "skills", "flow-ops", "SKILL.md"), opsCommandSkillMarkdown());
+    await writeFileSafe(runtimePath(projectRoot, "skills", "feature-workspaces", "SKILL.md"), featureCommandSkillMarkdown());
+    await writeFileSafe(runtimePath(projectRoot, "skills", "tdd-cycle-log", "SKILL.md"), tddLogCommandSkillMarkdown());
+    await writeFileSafe(runtimePath(projectRoot, "skills", "flow-retro", "SKILL.md"), retroCommandSkillMarkdown());
+    await writeFileSafe(runtimePath(projectRoot, "skills", "flow-rewind", "SKILL.md"), rewindCommandSkillMarkdown());
+    await writeFileSafe(runtimePath(projectRoot, "skills", "flow-archive", "SKILL.md"), archiveCommandSkillMarkdown());
     await writeFileSafe(runtimePath(projectRoot, "skills", "subagent-dev", "SKILL.md"), subagentDrivenDevSkill());
     await writeFileSafe(runtimePath(projectRoot, "skills", "parallel-dispatch", "SKILL.md"), parallelAgentsSkill());
     await writeFileSafe(runtimePath(projectRoot, "skills", "session", "SKILL.md"), sessionHooksSkillMarkdown());
@@ -248,8 +266,18 @@ async function writeSkills(projectRoot, config) {
 async function writeUtilityCommands(projectRoot) {
     await writeFileSafe(runtimePath(projectRoot, "commands", "learn.md"), learnCommandContract());
     await writeFileSafe(runtimePath(projectRoot, "commands", "next.md"), nextCommandContract());
+    await writeFileSafe(runtimePath(projectRoot, "commands", "view.md"), viewCommandContract());
     await writeFileSafe(runtimePath(projectRoot, "commands", "start.md"), startCommandContract());
     await writeFileSafe(runtimePath(projectRoot, "commands", "status.md"), statusCommandContract());
+    await writeFileSafe(runtimePath(projectRoot, "commands", "tree.md"), treeCommandContract());
+    await writeFileSafe(runtimePath(projectRoot, "commands", "diff.md"), diffCommandContract());
+    await writeFileSafe(runtimePath(projectRoot, "commands", "ops.md"), opsCommandContract());
+    await writeFileSafe(runtimePath(projectRoot, "commands", "feature.md"), featureCommandContract());
+    await writeFileSafe(runtimePath(projectRoot, "commands", "tdd-log.md"), tddLogCommandContract());
+    await writeFileSafe(runtimePath(projectRoot, "commands", "retro.md"), retroCommandContract());
+    await writeFileSafe(runtimePath(projectRoot, "commands", "archive.md"), archiveCommandContract());
+    await writeFileSafe(runtimePath(projectRoot, "commands", "rewind.md"), rewindCommandContract());
+    await writeFileSafe(runtimePath(projectRoot, "commands", "rewind-ack.md"), rewindAcknowledgeCommandContract());
 }
 function toObject(value) {
     if (!value || typeof value !== "object" || Array.isArray(value)) {
@@ -550,7 +578,10 @@ async function writeHooks(projectRoot, config) {
     await writeFileSafe(path.join(hooksDir, "prompt-guard.sh"), promptGuardScript({
         strictMode: config.promptGuardMode === "strict"
     }));
-    await writeFileSafe(path.join(hooksDir, "workflow-guard.sh"), workflowGuardScript());
+    await writeFileSafe(path.join(hooksDir, "workflow-guard.sh"), workflowGuardScript({
+        tddEnforcementMode: config.tddEnforcement ?? "advisory",
+        tddTestGlobs: config.tddTestGlobs
+    }));
     await writeFileSafe(path.join(hooksDir, "context-monitor.sh"), contextMonitorScript());
     const opencodePluginSource = opencodePluginJs();
     await writeFileSafe(path.join(hooksDir, "opencode-plugin.mjs"), opencodePluginSource);
@@ -760,13 +791,13 @@ Drop this section if no hard rule applies. Keep it crisp:
 async function ensureSessionStateFiles(projectRoot) {
     const stateDir = runtimePath(projectRoot, "state");
     await ensureDir(stateDir);
+    const flow = await readFlowState(projectRoot);
     const activityPath = path.join(stateDir, "stage-activity.jsonl");
     if (!(await exists(activityPath))) {
         await writeFileSafe(activityPath, "");
     }
     const checkpointPath = path.join(stateDir, "checkpoint.json");
     if (!(await exists(checkpointPath))) {
-        const flow = await readFlowState(projectRoot);
         const initialCheckpoint = {
             stage: flow.currentStage,
             runId: flow.activeRunId,
@@ -800,6 +831,17 @@ async function ensureSessionStateFiles(projectRoot) {
     if (!(await exists(preambleLogPath))) {
         await writeFileSafe(preambleLogPath, "");
     }
+    const tddCycleLogPath = path.join(stateDir, "tdd-cycle-log.jsonl");
+    if (!(await exists(tddCycleLogPath))) {
+        await writeFileSafe(tddCycleLogPath, "");
+    }
+    const flowSnapshotPath = path.join(stateDir, "flow-state.snapshot.json");
+    if (!(await exists(flowSnapshotPath))) {
+        await writeFileSafe(flowSnapshotPath, `${JSON.stringify({
+            capturedAt: new Date().toISOString(),
+            state: flow
+        }, null, 2)}\n`);
+    }
 }
 async function writeRulebook(projectRoot) {
     await writeFileSafe(runtimePath(projectRoot, "rules", "RULES.md"), RULEBOOK_MARKDOWN);

package/dist/policy.js

@@ -90,6 +90,27 @@ export async function policyChecks(projectRoot, options = {}) {
         { file: runtimeFile("skills/learnings/SKILL.md"), needle: "## Subcommands", name: "utility_skill:learnings:subcommands" },
         { file: runtimeFile("skills/learnings/SKILL.md"), needle: "## HARD-GATE", name: "utility_skill:learnings:hard_gate" },
         { file: runtimeFile("commands/learn.md"), needle: "## Subcommands", name: "utility_command:learn:subcommands" },
+        { file: runtimeFile("commands/status.md"), needle: "bar:", name: "utility_command:status:visual_bar" },
+        { file: runtimeFile("commands/status.md"), needle: "/cc-tree · /cc-diff", name: "utility_command:status:tree_diff_link" },
+        { file: runtimeFile("commands/tree.md"), needle: "## Algorithm", name: "utility_command:tree:algorithm" },
+        { file: runtimeFile("skills/flow-tree/SKILL.md"), needle: "## Protocol", name: "utility_skill:tree:protocol" },
+        { file: runtimeFile("skills/flow-tree/SKILL.md"), needle: "## HARD-GATE", name: "utility_skill:tree:hard_gate" },
+        { file: runtimeFile("commands/diff.md"), needle: "## Algorithm", name: "utility_command:diff:algorithm" },
+        { file: runtimeFile("skills/flow-diff/SKILL.md"), needle: "## Protocol", name: "utility_skill:diff:protocol" },
+        { file: runtimeFile("skills/flow-diff/SKILL.md"), needle: "## HARD-GATE", name: "utility_skill:diff:hard_gate" },
+        { file: runtimeFile("commands/feature.md"), needle: "## Subcommands", name: "utility_command:feature:subcommands" },
+        { file: runtimeFile("skills/feature-workspaces/SKILL.md"), needle: "## Protocol", name: "utility_skill:feature:protocol" },
+        { file: runtimeFile("skills/feature-workspaces/SKILL.md"), needle: "## HARD-GATE", name: "utility_skill:feature:hard_gate" },
+        { file: runtimeFile("commands/tdd-log.md"), needle: "## Subcommands", name: "utility_command:tdd_log:subcommands" },
+        { file: runtimeFile("skills/tdd-cycle-log/SKILL.md"), needle: "## Protocol", name: "utility_skill:tdd_log:protocol" },
+        { file: runtimeFile("skills/tdd-cycle-log/SKILL.md"), needle: "## HARD-GATE", name: "utility_skill:tdd_log:hard_gate" },
+        { file: runtimeFile("commands/retro.md"), needle: "## Algorithm", name: "utility_command:retro:algorithm" },
+        { file: runtimeFile("skills/flow-retro/SKILL.md"), needle: "## Protocol", name: "utility_skill:retro:protocol" },
+        { file: runtimeFile("skills/flow-retro/SKILL.md"), needle: "## HARD-GATE", name: "utility_skill:retro:hard_gate" },
+        { file: runtimeFile("commands/rewind.md"), needle: "## Algorithm", name: "utility_command:rewind:algorithm" },
+        { file: runtimeFile("commands/rewind-ack.md"), needle: "## Algorithm", name: "utility_command:rewind_ack:algorithm" },
+        { file: runtimeFile("skills/flow-rewind/SKILL.md"), needle: "## Protocol", name: "utility_skill:rewind:protocol" },
+        { file: runtimeFile("skills/flow-rewind/SKILL.md"), needle: "## HARD-GATE", name: "utility_skill:rewind:hard_gate" },
         { file: runtimeFile("skills/subagent-dev/SKILL.md"), needle: "## HARD-GATE", name: "utility_skill:sdd:hard_gate" },
         { file: runtimeFile("skills/subagent-dev/SKILL.md"), needle: "## Status Contract", name: "utility_skill:sdd:status_contract" },
         { file: runtimeFile("skills/subagent-dev/SKILL.md"), needle: "Implementer", name: "utility_skill:sdd:implementer_template" },
@@ -158,6 +179,7 @@ export async function policyChecks(projectRoot, options = {}) {
         { file: runtimeFile("hooks/prompt-guard.sh"), needle: "write_to_cclaw_runtime", name: "hooks:guard:risky_write_advisory" },
         { file: runtimeFile("hooks/workflow-guard.sh"), needle: "stage_invocation_without_recent_flow_read", name: "hooks:workflow_guard:flow_read_reason" },
         { file: runtimeFile("hooks/workflow-guard.sh"), needle: "stage_jump_", name: "hooks:workflow_guard:stage_jump_reason" },
+        { file: runtimeFile("hooks/workflow-guard.sh"), needle: "tdd_write_without_open_red", name: "hooks:workflow_guard:tdd_red_first" },
         { file: runtimeFile("hooks/context-monitor.sh"), needle: "remaining is", name: "hooks:context:threshold_warning" },
         { file: runtimeFile("hooks/opencode-plugin.mjs"), needle: "activeRunId", name: "hooks:opencode:active_run" },
         { file: runtimeFile("hooks/session-start.sh"), needle: "Knowledge digest", name: "hooks:session_start:knowledge_digest" },

package/dist/runs.d.ts

@@ -22,6 +22,7 @@ export interface ArchiveRunResult {
     archivePath: string;
     archivedAt: string;
     featureName: string;
+    activeFeature: string;
     resetState: FlowState;
     snapshottedStateFiles: string[];
     /** Knowledge curation hint: total active entries + soft threshold (50). */
@@ -31,20 +32,46 @@ export interface ArchiveRunResult {
         overThreshold: boolean;
         knowledgePath: string;
     };
+    retro: {
+        required: boolean;
+        completed: boolean;
+        skipped: boolean;
+        skipReason?: string;
+        compoundEntries: number;
+    };
 }
 export interface ArchiveManifest {
     version: 1;
     archiveId: string;
     archivedAt: string;
     featureName: string;
+    activeFeature: string;
     sourceRunId: string;
     sourceCurrentStage: FlowStage;
     sourceCompletedStages: FlowStage[];
     snapshottedStateFiles: string[];
+    retro: ArchiveRunResult["retro"];
+}
+export interface RewindRunOptions {
+    to: FlowStage;
+    reason?: string;
+}
+export interface RewindRunResult {
+    rewindId: string;
+    from: FlowStage;
+    to: FlowStage;
+    invalidatedStages: FlowStage[];
+    staleArtifacts: string[];
+    archivePath: string;
+    nextState: FlowState;
 }
 interface EnsureRunSystemOptions {
     createIfMissing?: boolean;
 }
+export interface ArchiveRunOptions {
+    skipRetro?: boolean;
+    skipRetroReason?: string;
+}
 export declare class CorruptFlowStateError extends Error {
     readonly statePath: string;
     readonly quarantinedPath: string;
@@ -54,7 +81,12 @@ export declare function readFlowState(projectRoot: string): Promise<FlowState>;
 export declare function writeFlowState(projectRoot: string, state: FlowState, options?: WriteFlowStateOptions): Promise<void>;
 export declare function ensureRunSystem(projectRoot: string, _options?: EnsureRunSystemOptions): Promise<FlowState>;
 export declare function listRuns(projectRoot: string): Promise<CclawRunMeta[]>;
-export declare function archiveRun(projectRoot: string, featureName?: string): Promise<ArchiveRunResult>;
+export declare function archiveRun(projectRoot: string, featureName?: string, options?: ArchiveRunOptions): Promise<ArchiveRunResult>;
+export declare function rewindRun(projectRoot: string, options: RewindRunOptions): Promise<RewindRunResult>;
+export declare function acknowledgeStaleStage(projectRoot: string, stage: FlowStage): Promise<{
+    acknowledged: boolean;
+    remaining: FlowStage[];
+}>;
 /**
  * Counts entries in the canonical JSONL knowledge store. An "active" entry is one
  * non-empty line that parses as JSON with the required `type` field belonging to the

package/dist/runs.js

@@ -1,8 +1,10 @@
 import fs from "node:fs/promises";
 import path from "node:path";
 import { COMMAND_FILE_ORDER, RUNTIME_ROOT } from "./constants.js";
-import { canTransition, createInitialFlowState, isFlowTrack, skippedStagesForTrack } from "./flow-state.js";
+import { canTransition, createInitialFlowState, isFlowTrack, skippedStagesForTrack, trackStages } from "./flow-state.js";
+import { ensureFeatureSystem, readActiveFeature, syncActiveFeatureSnapshot } from "./feature-system.js";
 import { ensureDir, exists, withDirectoryLock, writeFileSafe } from "./fs-utils.js";
+import { stageSchema } from "./content/stage-schema.js";
 export class InvalidStageTransitionError extends Error {
     from;
     to;
@@ -34,6 +36,8 @@ const FLOW_STATE_REL_PATH = `${RUNTIME_ROOT}/state/flow-state.json`;
 const RUNS_DIR_REL_PATH = `${RUNTIME_ROOT}/runs`;
 const ACTIVE_ARTIFACTS_REL_PATH = `${RUNTIME_ROOT}/artifacts`;
 const STATE_DIR_REL_PATH = `${RUNTIME_ROOT}/state`;
+const REWIND_LOG_REL_PATH = `${RUNTIME_ROOT}/state/rewind-log.jsonl`;
+const REWIND_ARCHIVE_DIR_NAME = "_rewind-archive";
 const FLOW_STAGE_SET = new Set(COMMAND_FILE_ORDER);
 /** State filenames explicitly excluded from the archive snapshot. */
 const STATE_SNAPSHOT_EXCLUDE = new Set([
@@ -55,6 +59,12 @@ function activeArtifactsPath(projectRoot) {
 function stateDirPath(projectRoot) {
     return path.join(projectRoot, STATE_DIR_REL_PATH);
 }
+function rewindLogPath(projectRoot) {
+    return path.join(projectRoot, REWIND_LOG_REL_PATH);
+}
+function rewindArchivePath(projectRoot, rewindId) {
+    return path.join(activeArtifactsPath(projectRoot), REWIND_ARCHIVE_DIR_NAME, rewindId);
+}
 async function snapshotStateDirectory(projectRoot, destinationRoot) {
     const sourceDir = stateDirPath(projectRoot);
     if (!(await exists(sourceDir))) {
@@ -191,6 +201,86 @@ function sanitizeSkippedStages(value, track) {
     }
     return out.length > 0 ? out : trackDefault;
 }
+function sanitizeStaleStages(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        return {};
+    }
+    const out = {};
+    for (const [stage, raw] of Object.entries(value)) {
+        if (!isFlowStage(stage))
+            continue;
+        if (!raw || typeof raw !== "object" || Array.isArray(raw))
+            continue;
+        const typed = raw;
+        const rewindId = typeof typed.rewindId === "string" ? typed.rewindId : "";
+        const reason = typeof typed.reason === "string" ? typed.reason : "";
+        const markedAt = typeof typed.markedAt === "string" ? typed.markedAt : "";
+        const acknowledgedAt = typeof typed.acknowledgedAt === "string" ? typed.acknowledgedAt : undefined;
+        if (!rewindId || !reason || !markedAt) {
+            continue;
+        }
+        out[stage] = {
+            rewindId,
+            reason,
+            markedAt,
+            acknowledgedAt
+        };
+    }
+    return out;
+}
+function sanitizeRewinds(value) {
+    if (!Array.isArray(value)) {
+        return [];
+    }
+    const out = [];
+    for (const raw of value) {
+        if (!raw || typeof raw !== "object" || Array.isArray(raw)) {
+            continue;
+        }
+        const typed = raw;
+        if (typeof typed.id !== "string" ||
+            !isFlowStage(typed.fromStage) ||
+            !isFlowStage(typed.toStage) ||
+            typeof typed.reason !== "string" ||
+            typeof typed.timestamp !== "string") {
+            continue;
+        }
+        const invalidatedStages = Array.isArray(typed.invalidatedStages)
+            ? typed.invalidatedStages.filter((stage) => isFlowStage(stage))
+            : [];
+        out.push({
+            id: typed.id,
+            fromStage: typed.fromStage,
+            toStage: typed.toStage,
+            reason: typed.reason,
+            timestamp: typed.timestamp,
+            invalidatedStages
+        });
+    }
+    return out;
+}
+function sanitizeRetroState(value) {
+    const fallback = {
+        required: false,
+        completedAt: undefined,
+        compoundEntries: 0
+    };
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        return fallback;
+    }
+    const typed = value;
+    const required = typeof typed.required === "boolean" ? typed.required : false;
+    const completedAt = typeof typed.completedAt === "string" ? typed.completedAt : undefined;
+    const compoundEntriesRaw = typed.compoundEntries;
+    const compoundEntries = typeof compoundEntriesRaw === "number" && Number.isFinite(compoundEntriesRaw) && compoundEntriesRaw >= 0
+        ? Math.floor(compoundEntriesRaw)
+        : 0;
+    return {
+        required,
+        completedAt,
+        compoundEntries
+    };
+}
 function coerceFlowState(parsed) {
     const track = coerceTrack(parsed.track);
     const next = createInitialFlowState("active", track);
@@ -205,7 +295,10 @@ function coerceFlowState(parsed) {
         guardEvidence: sanitizeGuardEvidence(parsed.guardEvidence),
         stageGateCatalog: sanitizeStageGateCatalog(parsed.stageGateCatalog, next.stageGateCatalog),
         track,
-        skippedStages: sanitizeSkippedStages(parsed.skippedStages, track)
+        skippedStages: sanitizeSkippedStages(parsed.skippedStages, track),
+        staleStages: sanitizeStaleStages(parsed.staleStages),
+        rewinds: sanitizeRewinds(parsed.rewinds),
+        retro: sanitizeRetroState(parsed.retro)
     };
 }
 function toArchiveDate(date = new Date()) {
@@ -255,6 +348,71 @@ async function uniqueArchiveId(projectRoot, baseId) {
     }
     return candidate;
 }
+function rewindTimestampId(date = new Date()) {
+    return date
+        .toISOString()
+        .replace(/[-:]/gu, "")
+        .replace(/\.\d{3}Z$/u, "Z");
+}
+function staleArtifactFileName(fileName) {
+    const ext = path.extname(fileName);
+    if (!ext) {
+        return `${fileName}.stale`;
+    }
+    const base = fileName.slice(0, -ext.length);
+    return `${base}.stale${ext}`;
+}
+function stageIndexMapForTrack(track) {
+    return new Map(trackStages(track).map((stage, index) => [stage, index]));
+}
+function retroArtifactPath(projectRoot) {
+    return path.join(activeArtifactsPath(projectRoot), "09-retro.md");
+}
+async function evaluateRetroGate(projectRoot, state) {
+    const required = state.completedStages.includes("ship");
+    const artifactFile = retroArtifactPath(projectRoot);
+    let hasRetroArtifact = false;
+    if (await exists(artifactFile)) {
+        try {
+            const raw = await fs.readFile(artifactFile, "utf8");
+            hasRetroArtifact = raw.trim().length > 0;
+        }
+        catch {
+            hasRetroArtifact = false;
+        }
+    }
+    const knowledgeFile = path.join(projectRoot, RUNTIME_ROOT, "knowledge.jsonl");
+    let compoundEntries = 0;
+    if (await exists(knowledgeFile)) {
+        try {
+            const raw = await fs.readFile(knowledgeFile, "utf8");
+            for (const line of raw.split(/\r?\n/)) {
+                const trimmed = line.trim();
+                if (!trimmed)
+                    continue;
+                try {
+                    const parsed = JSON.parse(trimmed);
+                    if (parsed.type === "compound") {
+                        compoundEntries += 1;
+                    }
+                }
+                catch {
+                    // ignore malformed lines for retro gate calculation
+                }
+            }
+        }
+        catch {
+            compoundEntries = 0;
+        }
+    }
+    const completed = required ? (hasRetroArtifact && compoundEntries > 0) : true;
+    return {
+        required,
+        completed,
+        compoundEntries,
+        hasRetroArtifact
+    };
+}
 export class CorruptFlowStateError extends Error {
     statePath;
     quarantinedPath;
@@ -293,6 +451,7 @@ async function quarantineCorruptState(statePath, cause) {
     throw new CorruptFlowStateError(statePath, quarantinedPath, cause);
 }
 export async function readFlowState(projectRoot) {
+    await ensureFeatureSystem(projectRoot);
     const statePath = flowStatePath(projectRoot);
     if (!(await exists(statePath))) {
         return createInitialFlowState();
@@ -317,6 +476,7 @@ export async function readFlowState(projectRoot) {
     return coerceFlowState(parsed);
 }
 export async function writeFlowState(projectRoot, state, options = {}) {
+    await ensureFeatureSystem(projectRoot);
     await withDirectoryLock(flowStateLockPath(projectRoot), async () => {
         const statePath = flowStatePath(projectRoot);
         if (!options.allowReset && (await exists(statePath))) {
@@ -339,8 +499,10 @@ export async function writeFlowState(projectRoot, state, options = {}) {
         const safe = coerceFlowState({ ...state });
         await writeFileSafe(statePath, `${JSON.stringify(safe, null, 2)}\n`);
     });
+    await syncActiveFeatureSnapshot(projectRoot);
 }
 export async function ensureRunSystem(projectRoot, _options = {}) {
+    await ensureFeatureSystem(projectRoot);
     await ensureDir(runsRoot(projectRoot));
     await ensureDir(activeArtifactsPath(projectRoot));
     const statePath = flowStatePath(projectRoot);
@@ -348,6 +510,7 @@ export async function ensureRunSystem(projectRoot, _options = {}) {
     if (!(await exists(statePath))) {
         await writeFlowState(projectRoot, state, { allowReset: true });
     }
+    await syncActiveFeatureSnapshot(projectRoot);
     return state;
 }
 export async function listRuns(projectRoot) {
@@ -378,8 +541,9 @@ export async function listRuns(projectRoot) {
     }
     return runs.sort((a, b) => a.createdAt.localeCompare(b.createdAt));
 }
-export async function archiveRun(projectRoot, featureName) {
+export async function archiveRun(projectRoot, featureName, options = {}) {
     await ensureRunSystem(projectRoot);
+    const activeFeature = await readActiveFeature(projectRoot);
     const artifactsDir = activeArtifactsPath(projectRoot);
     const runsDir = runsRoot(projectRoot);
     await ensureDir(runsDir);
@@ -391,7 +555,36 @@ export async function archiveRun(projectRoot, featureName) {
     const archiveId = await uniqueArchiveId(projectRoot, archiveBaseId);
     const archivePath = path.join(runsDir, archiveId);
     const archiveArtifactsPath = path.join(archivePath, "artifacts");
-    const sourceState = await readFlowState(projectRoot);
+    let sourceState = await readFlowState(projectRoot);
+    const retroGate = await evaluateRetroGate(projectRoot, sourceState);
+    const skipRetro = options.skipRetro === true;
+    const skipRetroReason = options.skipRetroReason?.trim();
+    if (skipRetro && (!skipRetroReason || skipRetroReason.length === 0)) {
+        throw new Error("archive --skip-retro requires --retro-reason=<text>.");
+    }
+    if (retroGate.required && !retroGate.completed && !skipRetro) {
+        throw new Error("Archive blocked: retro gate is required after ship completion. " +
+            "Run /cc-retro and append at least one compound knowledge entry, or re-run archive with --skip-retro and --retro-reason.");
+    }
+    if (retroGate.completed) {
+        const completedAt = sourceState.retro.completedAt ?? new Date().toISOString();
+        sourceState = {
+            ...sourceState,
+            retro: {
+                required: retroGate.required,
+                completedAt,
+                compoundEntries: retroGate.compoundEntries
+            }
+        };
+        await writeFlowState(projectRoot, sourceState, { allowReset: true });
+    }
+    const retroSummary = {
+        required: retroGate.required,
+        completed: retroGate.completed,
+        skipped: skipRetro,
+        skipReason: skipRetro ? skipRetroReason : undefined,
+        compoundEntries: retroGate.compoundEntries
+    };
     await ensureDir(archivePath);
     await fs.rename(artifactsDir, archiveArtifactsPath);
     await ensureDir(artifactsDir);
@@ -405,21 +598,187 @@ export async function archiveRun(projectRoot, featureName) {
         archiveId,
         archivedAt,
         featureName: feature,
+        activeFeature,
         sourceRunId: sourceState.activeRunId,
         sourceCurrentStage: sourceState.currentStage,
         sourceCompletedStages: sourceState.completedStages,
-        snapshottedStateFiles
+        snapshottedStateFiles,
+        retro: retroSummary
     };
     await writeFileSafe(path.join(archivePath, "archive-manifest.json"), `${JSON.stringify(manifest, null, 2)}\n`);
     const knowledgeStats = await readKnowledgeStats(projectRoot);
+    await syncActiveFeatureSnapshot(projectRoot);
     return {
         archiveId,
         archivePath,
         archivedAt,
         featureName: feature,
+        activeFeature,
         resetState,
         snapshottedStateFiles,
-        knowledge: knowledgeStats
+        knowledge: knowledgeStats,
+        retro: retroSummary
+    };
+}
+export async function rewindRun(projectRoot, options) {
+    await ensureRunSystem(projectRoot);
+    const state = await readFlowState(projectRoot);
+    const track = state.track ?? "standard";
+    const ordered = trackStages(track);
+    const stageToIndex = stageIndexMapForTrack(track);
+    const toIndex = stageToIndex.get(options.to);
+    const currentIndex = stageToIndex.get(state.currentStage);
+    if (toIndex === undefined) {
+        throw new Error(`Cannot rewind to "${options.to}" because it is outside track "${track}".`);
+    }
+    if (currentIndex === undefined) {
+        throw new Error(`Current stage "${state.currentStage}" is not part of track "${track}".`);
+    }
+    if (toIndex > currentIndex) {
+        throw new Error(`Cannot rewind forward from "${state.currentStage}" to "${options.to}".`);
+    }
+    const reason = options.reason?.trim() && options.reason.trim().length > 0
+        ? options.reason.trim()
+        : "manual_rewind";
+    const nowIso = new Date().toISOString();
+    const rewindId = `rewind-${rewindTimestampId()}`;
+    const invalidatedStages = ordered.filter((stage) => {
+        const idx = stageToIndex.get(stage);
+        if (idx === undefined || idx <= toIndex) {
+            return false;
+        }
+        return state.completedStages.includes(stage) || stage === state.currentStage;
+    });
+    const nextCompletedStages = state.completedStages.filter((stage) => {
+        const idx = stageToIndex.get(stage);
+        return typeof idx === "number" && idx < toIndex;
+    });
+    const freshCatalog = createInitialFlowState({ activeRunId: state.activeRunId, track }).stageGateCatalog;
+    const nextCatalog = { ...state.stageGateCatalog };
+    for (const stage of ordered) {
+        const idx = stageToIndex.get(stage);
+        if (idx === undefined)
+            continue;
+        if (idx >= toIndex) {
+            nextCatalog[stage] = {
+                ...freshCatalog[stage],
+                required: [...freshCatalog[stage].required],
+                recommended: [...freshCatalog[stage].recommended],
+                conditional: [...freshCatalog[stage].conditional],
+                triggered: [],
+                passed: [],
+                blocked: []
+            };
+        }
+    }
+    const nextGuardEvidence = { ...state.guardEvidence };
+    for (const stage of ordered) {
+        const idx = stageToIndex.get(stage);
+        if (idx === undefined || idx < toIndex)
+            continue;
+        const catalog = state.stageGateCatalog[stage];
+        const gateIds = new Set([
+            ...catalog.required,
+            ...catalog.recommended,
+            ...catalog.conditional,
+            ...catalog.triggered,
+            ...catalog.passed,
+            ...catalog.blocked
+        ]);
+        for (const gateId of gateIds) {
+            delete nextGuardEvidence[gateId];
+        }
+    }
+    const nextStale = {};
+    for (const [stage, marker] of Object.entries(state.staleStages)) {
+        if (!marker)
+            continue;
+        const idx = stageToIndex.get(stage);
+        if (idx === undefined || idx <= toIndex) {
+            continue;
+        }
+        nextStale[stage] = marker;
+    }
+    for (const stage of invalidatedStages) {
+        nextStale[stage] = {
+            rewindId,
+            reason,
+            markedAt: nowIso
+        };
+    }
+    const archivePath = rewindArchivePath(projectRoot, rewindId);
+    const staleArtifacts = [];
+    for (const stage of invalidatedStages) {
+        const artifactFile = stageSchema(stage).artifactFile;
+        const artifactPath = path.join(activeArtifactsPath(projectRoot), artifactFile);
+        if (!(await exists(artifactPath))) {
+            continue;
+        }
+        await ensureDir(archivePath);
+        await ensureDir(path.join(archivePath, path.dirname(artifactFile)));
+        await fs.copyFile(artifactPath, path.join(archivePath, artifactFile));
+        const staleName = staleArtifactFileName(artifactFile);
+        const stalePath = path.join(activeArtifactsPath(projectRoot), staleName);
+        await fs.rm(stalePath, { force: true });
+        await fs.rename(artifactPath, stalePath);
+        staleArtifacts.push(staleName);
+    }
+    const rewindRecord = {
+        id: rewindId,
+        fromStage: state.currentStage,
+        toStage: options.to,
+        reason,
+        timestamp: nowIso,
+        invalidatedStages
+    };
+    const nextState = {
+        ...state,
+        currentStage: options.to,
+        completedStages: nextCompletedStages,
+        guardEvidence: nextGuardEvidence,
+        stageGateCatalog: nextCatalog,
+        staleStages: nextStale,
+        rewinds: [...state.rewinds, rewindRecord]
+    };
+    await writeFlowState(projectRoot, nextState, { allowReset: true });
+    const rewindLogEntry = {
+        ...rewindRecord,
+        track,
+        runId: state.activeRunId,
+        staleArtifacts
+    };
+    await ensureDir(path.dirname(rewindLogPath(projectRoot)));
+    await fs.appendFile(rewindLogPath(projectRoot), `${JSON.stringify(rewindLogEntry)}\n`, "utf8");
+    return {
+        rewindId,
+        from: state.currentStage,
+        to: options.to,
+        invalidatedStages,
+        staleArtifacts,
+        archivePath,
+        nextState
+    };
+}
+export async function acknowledgeStaleStage(projectRoot, stage) {
+    await ensureRunSystem(projectRoot);
+    const state = await readFlowState(projectRoot);
+    const marker = state.staleStages[stage];
+    if (!marker) {
+        return {
+            acknowledged: false,
+            remaining: Object.keys(state.staleStages).filter((value) => isFlowStage(value))
+        };
+    }
+    const nextStale = { ...state.staleStages };
+    delete nextStale[stage];
+    const nextState = {
+        ...state,
+        staleStages: nextStale
+    };
+    await writeFlowState(projectRoot, nextState, { allowReset: true });
+    return {
+        acknowledged: true,
+        remaining: Object.keys(nextStale).filter((value) => isFlowStage(value))
     };
 }
 const KNOWLEDGE_SOFT_THRESHOLD = 50;