cclaw-cli 0.12.0 → 0.13.0

package/dist/content/tree-command.js

@@ -0,0 +1,91 @@
+import { RUNTIME_ROOT } from "../constants.js";
+const TREE_SKILL_FOLDER = "flow-tree";
+const TREE_SKILL_NAME = "flow-tree";
+function flowStatePath() {
+    return `${RUNTIME_ROOT}/state/flow-state.json`;
+}
+function delegationLogPath() {
+    return `${RUNTIME_ROOT}/state/delegation-log.json`;
+}
+function artifactsPath() {
+    return `${RUNTIME_ROOT}/artifacts`;
+}
+function rewindLogPath() {
+    return `${RUNTIME_ROOT}/state/rewind-log.jsonl`;
+}
+export function treeCommandContract() {
+    return `# /cc-tree
+
+## Purpose
+
+Render a visual flow tree for quick orientation across stages, gates, delegations,
+stale markers, and artifact presence.
+
+## HARD-GATE
+
+- \`/cc-tree\` is read-only. Do not mutate flow-state or artifacts.
+- Use values from \`${flowStatePath()}\` and \`${delegationLogPath()}\`; never infer missing evidence.
+
+## Algorithm
+
+1. Read \`${flowStatePath()}\`.
+2. Read \`${delegationLogPath()}\` (if missing, treat current-stage delegations as pending).
+3. Detect artifact files in \`${artifactsPath()}\`.
+4. Read rewind records from \`${rewindLogPath()}\` when present for stale-stage context.
+5. Render the tree using stage order from active track:
+   - stage node marker: passed/current/pending/skipped/stale
+   - gate summary: \`passed/required\`
+   - delegation summary for current stage
+   - artifact marker per stage (exists / stale copy / missing)
+
+## Tree Format
+
+\`\`\`
+cclaw flow tree (track=<track>, run=<runId>)
+├─ [✓] brainstorm  gates 6/6   artifact 01-brainstorm.md
+├─ [✓] scope       gates 5/5   artifact 02-scope.md
+├─ [▶] design      gates 2/7   artifact 03-design.md
+│  ├─ delegations: [✓] planner  [○] reviewer
+│  └─ stale: none
+├─ [○] spec        gates -     artifact missing
+└─ [○] plan        gates -     artifact missing
+\`\`\`
+
+Use UTF markers by default, ASCII fallback when terminal cannot render UTF.
+
+## Primary skill
+
+**${RUNTIME_ROOT}/skills/${TREE_SKILL_FOLDER}/SKILL.md**
+`;
+}
+export function treeCommandSkillMarkdown() {
+    return `---
+name: ${TREE_SKILL_NAME}
+description: "Render a visual flow tree for stages, gates, delegations, and artifacts."
+---
+
+# /cc-tree
+
+## HARD-GATE
+
+Do not modify state in this command. It is a pure read/render operation.
+
+## Protocol
+
+1. Read \`${flowStatePath()}\` as source of truth.
+2. Read \`${delegationLogPath()}\` for current-stage delegation status.
+3. Inspect \`${artifactsPath()}\` for per-stage artifact presence and stale copies.
+4. Render one compact tree:
+   - stage marker: passed/current/pending/skipped/stale
+   - gates summary
+   - artifact summary
+   - delegation branch for current stage
+5. If rewind records exist in \`${rewindLogPath()}\`, include latest rewind note in footer.
+
+## Validation
+
+- Output must mention the active \`track\` and \`currentStage\`.
+- Exactly one stage is marked current.
+- Missing files are reported explicitly; never guessed as complete.
+`;
+}

package/dist/doctor.js

@@ -14,8 +14,10 @@ import { readFlowState } from "./runs.js";
 import { skippedStagesForTrack } from "./flow-state.js";
 import { TRACK_STAGES } from "./types.js";
 import { checkMandatoryDelegations } from "./delegation.js";
+import { ensureFeatureSystem, featureRootPath, listFeatures, readActiveFeature } from "./feature-system.js";
 import { buildTraceMatrix } from "./trace-matrix.js";
 import { reconcileAndWriteCurrentStageGateCatalog, verifyCompletedStagesGateClosure, verifyCurrentStageGateEvidence } from "./gate-evidence.js";
+import { parseTddCycleLog, validateTddCycleOrder } from "./tdd-cycle.js";
 import { stageSkillFolder } from "./content/skills.js";
 import { doctorCheckMetadata } from "./doctor-registry.js";
 import { LANGUAGE_RULE_PACK_DIR, LANGUAGE_RULE_PACK_FILES, LEGACY_LANGUAGE_RULE_PACK_FOLDERS, UTILITY_SKILL_FOLDERS } from "./content/utility-skills.js";
@@ -445,7 +447,19 @@ export async function doctorChecks(projectRoot, options = {}) {
             });
             continue;
         }
-        for (const shim of ["cc.md", "cc-next.md", "cc-learn.md"]) {
+        for (const shim of [
+            "cc.md",
+            "cc-next.md",
+            "cc-learn.md",
+            "cc-status.md",
+            "cc-tree.md",
+            "cc-diff.md",
+            "cc-feature.md",
+            "cc-tdd-log.md",
+            "cc-retro.md",
+            "cc-rewind.md",
+            "cc-rewind-ack.md"
+        ]) {
             const shimPath = path.join(projectRoot, adapter.commandDir, shim);
             checks.push({
                 name: `shim:${harness}:${shim.replace(".md", "")}`,
@@ -462,10 +476,32 @@ export async function doctorChecks(projectRoot, options = {}) {
         const hasCcCommand = content.includes("/cc");
         const hasCcNext = content.includes("/cc-next");
         const hasCcLearn = content.includes("/cc-learn");
+        const hasCcStatus = content.includes("/cc-status");
+        const hasCcTree = content.includes("/cc-tree");
+        const hasCcDiff = content.includes("/cc-diff");
+        const hasCcFeature = content.includes("/cc-feature");
+        const hasCcTddLog = content.includes("/cc-tdd-log");
+        const hasCcRetro = content.includes("/cc-retro");
+        const hasCcRewind = content.includes("/cc-rewind");
+        const hasCcRewindAck = content.includes("/cc-rewind-ack");
         const hasVerification = content.includes("Verification Discipline");
         const hasMinimalMarker = content.includes("intentionally minimal for cross-project use");
         const hasMetaSkillPointer = content.includes(".cclaw/skills/using-cclaw/SKILL.md");
-        agentsBlockOk = hasMarkers && hasCcCommand && hasCcNext && hasCcLearn && hasVerification && hasMinimalMarker && hasMetaSkillPointer;
+        agentsBlockOk = hasMarkers
+            && hasCcCommand
+            && hasCcNext
+            && hasCcLearn
+            && hasCcStatus
+            && hasCcTree
+            && hasCcDiff
+            && hasCcFeature
+            && hasCcTddLog
+            && hasCcRetro
+            && hasCcRewind
+            && hasCcRewindAck
+            && hasVerification
+            && hasMinimalMarker
+            && hasMetaSkillPointer;
     }
     checks.push({
         name: "agents:cclaw_block",
@@ -473,7 +509,7 @@ export async function doctorChecks(projectRoot, options = {}) {
         details: `${agentsFile} must contain the managed cclaw marker block with routing, verification, and minimal detail pointer`
     });
     // Utility commands
-    for (const cmd of ["learn"]) {
+    for (const cmd of ["learn", "next", "status", "tree", "diff", "feature", "tdd-log", "retro", "rewind", "rewind-ack"]) {
         const cmdPath = path.join(projectRoot, RUNTIME_ROOT, "commands", `${cmd}.md`);
         checks.push({
             name: `utility_command:${cmd}`,
@@ -484,6 +520,12 @@ export async function doctorChecks(projectRoot, options = {}) {
     // Utility skills
     for (const [folder, label] of [
         ["learnings", "learnings"],
+        ["flow-tree", "flow-tree"],
+        ["flow-diff", "flow-diff"],
+        ["feature-workspaces", "feature-workspaces"],
+        ["tdd-cycle-log", "tdd-cycle-log"],
+        ["flow-retro", "flow-retro"],
+        ["flow-rewind", "flow-rewind"],
         ["subagent-dev", "sdd"],
         ["parallel-dispatch", "parallel-agents"],
         ["session", "session"],
@@ -937,6 +979,8 @@ export async function doctorChecks(projectRoot, options = {}) {
                         : "preamble log is empty; no recent preamble emissions recorded"
         });
     }
+    await ensureFeatureSystem(projectRoot);
+    const activeFeature = await readActiveFeature(projectRoot);
     let flowState = await readFlowState(projectRoot);
     if (options.reconcileCurrentStageGates === true) {
         const reconciliation = await reconcileAndWriteCurrentStageGateCatalog(projectRoot);
@@ -991,6 +1035,108 @@ export async function doctorChecks(projectRoot, options = {}) {
         ok: await exists(path.join(projectRoot, RUNTIME_ROOT, "artifacts")),
         details: `${RUNTIME_ROOT}/artifacts must exist as the active artifact root`
     });
+    const features = await listFeatures(projectRoot);
+    checks.push({
+        name: "state:active_feature_meta",
+        ok: await exists(path.join(projectRoot, RUNTIME_ROOT, "state", "active-feature.json")),
+        details: `${RUNTIME_ROOT}/state/active-feature.json must exist`
+    });
+    checks.push({
+        name: "state:active_feature_exists",
+        ok: features.includes(activeFeature),
+        details: features.includes(activeFeature)
+            ? `active feature "${activeFeature}" is present in ${RUNTIME_ROOT}/features`
+            : `active feature "${activeFeature}" is missing from ${RUNTIME_ROOT}/features`
+    });
+    checks.push({
+        name: "state:features_nonempty",
+        ok: features.length > 0,
+        details: features.length > 0
+            ? `${features.length} feature snapshot(s): ${features.join(", ")}`
+            : `no feature snapshots found under ${RUNTIME_ROOT}/features`
+    });
+    checks.push({
+        name: "state:active_feature_snapshot_dirs",
+        ok: await exists(path.join(featureRootPath(projectRoot, activeFeature), "artifacts")) &&
+            await exists(path.join(featureRootPath(projectRoot, activeFeature), "state")),
+        details: `${RUNTIME_ROOT}/features/${activeFeature}/artifacts and /state must exist`
+    });
+    const staleStages = Object.keys(flowState.staleStages).filter((value) => COMMAND_FILE_ORDER.includes(value));
+    checks.push({
+        name: "state:stale_stages_resolved",
+        ok: staleStages.length === 0,
+        details: staleStages.length === 0
+            ? "no stale stages pending acknowledgement"
+            : `stale stages must be acknowledged via /cc-rewind-ack: ${staleStages.join(", ")}`
+    });
+    const retroRequired = flowState.completedStages.includes("ship");
+    const retroComplete = !retroRequired ||
+        (typeof flowState.retro.completedAt === "string" && flowState.retro.compoundEntries > 0);
+    checks.push({
+        name: "state:retro_gate",
+        ok: retroComplete,
+        details: retroComplete
+            ? retroRequired
+                ? `retro gate complete (${flowState.retro.compoundEntries} compound entries)`
+                : "retro gate not required yet (ship not completed)"
+            : "retro gate incomplete: run /cc-retro and record at least one compound knowledge entry"
+    });
+    const flowSnapshotPath = path.join(projectRoot, RUNTIME_ROOT, "state", "flow-state.snapshot.json");
+    const flowSnapshotExists = await exists(flowSnapshotPath);
+    let flowSnapshotValid = flowSnapshotExists;
+    if (flowSnapshotExists) {
+        try {
+            JSON.parse(await fs.readFile(flowSnapshotPath, "utf8"));
+            flowSnapshotValid = true;
+        }
+        catch {
+            flowSnapshotValid = false;
+        }
+    }
+    checks.push({
+        name: "state:flow_snapshot",
+        ok: flowSnapshotExists && flowSnapshotValid,
+        details: flowSnapshotExists
+            ? flowSnapshotValid
+                ? `${RUNTIME_ROOT}/state/flow-state.snapshot.json exists and is valid JSON`
+                : `${RUNTIME_ROOT}/state/flow-state.snapshot.json exists but is invalid JSON`
+            : `${RUNTIME_ROOT}/state/flow-state.snapshot.json is missing`
+    });
+    const tddLogPath = path.join(projectRoot, RUNTIME_ROOT, "state", "tdd-cycle-log.jsonl");
+    const tddLogExists = await exists(tddLogPath);
+    checks.push({
+        name: "state:tdd_cycle_log_exists",
+        ok: tddLogExists,
+        details: `${RUNTIME_ROOT}/state/tdd-cycle-log.jsonl must exist`
+    });
+    const tddCompleted = flowState.completedStages.includes("tdd")
+        || (flowState.currentStage === "review" || flowState.currentStage === "ship");
+    if (tddLogExists) {
+        const tddLogRaw = await fs.readFile(tddLogPath, "utf8");
+        const parsedCycles = parseTddCycleLog(tddLogRaw);
+        const validation = validateTddCycleOrder(parsedCycles, { runId: activeRunId || undefined });
+        const hasCoverage = validation.sliceCount > 0;
+        checks.push({
+            name: "state:tdd_cycle_order",
+            ok: validation.ok && (!tddCompleted || hasCoverage),
+            details: validation.ok
+                ? tddCompleted && !hasCoverage
+                    ? "tdd stage complete but no RED/GREEN cycle evidence logged"
+                    : `tdd cycle log valid (${validation.sliceCount} slice(s), open_red=${validation.openRedSlices.length})`
+                : `tdd cycle order issues: ${validation.issues.join("; ")}${validation.openRedSlices.length > 0
+                    ? ` | open red slices: ${validation.openRedSlices.join(", ")}`
+                    : ""}`
+        });
+    }
+    else {
+        checks.push({
+            name: "state:tdd_cycle_order",
+            ok: !tddCompleted,
+            details: tddCompleted
+                ? "tdd stage complete but tdd-cycle-log.jsonl is missing"
+                : "tdd cycle order deferred until tdd stage evidence is generated"
+        });
+    }
     checks.push({
         name: "runs:archive_root",
         ok: await exists(path.join(projectRoot, RUNTIME_ROOT, "runs")),

package/dist/feature-system.d.ts

@@ -0,0 +1,18 @@
+export interface ActiveFeatureMeta {
+    activeFeature: string;
+    updatedAt: string;
+}
+export declare function activeFeatureMetaPath(projectRoot: string): string;
+export declare function featureRootPath(projectRoot: string, featureId: string): string;
+export declare function featureArtifactsPath(projectRoot: string, featureId: string): string;
+export declare function featureStatePath(projectRoot: string, featureId: string): string;
+export declare function readActiveFeature(projectRoot: string): Promise<string>;
+export declare function listFeatures(projectRoot: string): Promise<string[]>;
+export declare function ensureFeatureSystem(projectRoot: string): Promise<ActiveFeatureMeta>;
+export declare function syncActiveFeatureSnapshot(projectRoot: string): Promise<void>;
+export declare function switchActiveFeature(projectRoot: string, featureId: string): Promise<ActiveFeatureMeta>;
+export interface CreateFeatureOptions {
+    cloneActive?: boolean;
+    switchTo?: boolean;
+}
+export declare function createFeature(projectRoot: string, rawFeatureId: string, options?: CreateFeatureOptions): Promise<string>;

package/dist/feature-system.js

@@ -0,0 +1,247 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { RUNTIME_ROOT } from "./constants.js";
+import { ensureDir, exists, writeFileSafe } from "./fs-utils.js";
+const FEATURES_DIR_REL_PATH = `${RUNTIME_ROOT}/features`;
+const ACTIVE_FEATURE_META_REL_PATH = `${RUNTIME_ROOT}/state/active-feature.json`;
+const DEFAULT_FEATURE_ID = "default";
+const FEATURE_ID_PATTERN = /^[a-z0-9][a-z0-9-]{0,63}$/u;
+const FEATURE_STATE_EXCLUDE_FROM_SNAPSHOT = new Set([
+    "active-feature.json",
+    ".flow-state.lock",
+    ".delegation.lock"
+]);
+function featuresRoot(projectRoot) {
+    return path.join(projectRoot, FEATURES_DIR_REL_PATH);
+}
+function runtimeArtifactsRoot(projectRoot) {
+    return path.join(projectRoot, RUNTIME_ROOT, "artifacts");
+}
+function runtimeStateRoot(projectRoot) {
+    return path.join(projectRoot, RUNTIME_ROOT, "state");
+}
+export function activeFeatureMetaPath(projectRoot) {
+    return path.join(projectRoot, ACTIVE_FEATURE_META_REL_PATH);
+}
+export function featureRootPath(projectRoot, featureId) {
+    return path.join(featuresRoot(projectRoot), featureId);
+}
+export function featureArtifactsPath(projectRoot, featureId) {
+    return path.join(featureRootPath(projectRoot, featureId), "artifacts");
+}
+export function featureStatePath(projectRoot, featureId) {
+    return path.join(featureRootPath(projectRoot, featureId), "state");
+}
+function normalizedFeatureId(value) {
+    const candidate = value
+        .trim()
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/gu, "-")
+        .replace(/^-+/u, "")
+        .replace(/-+$/u, "");
+    if (!candidate) {
+        return DEFAULT_FEATURE_ID;
+    }
+    const clipped = candidate.slice(0, 64);
+    return FEATURE_ID_PATTERN.test(clipped) ? clipped : DEFAULT_FEATURE_ID;
+}
+async function clearDirectory(dirPath, preserveTargetEntries = new Set()) {
+    await ensureDir(dirPath);
+    let entries;
+    try {
+        entries = await fs.readdir(dirPath, { withFileTypes: true });
+    }
+    catch {
+        return;
+    }
+    for (const entry of entries) {
+        if (preserveTargetEntries.has(entry.name)) {
+            continue;
+        }
+        await fs.rm(path.join(dirPath, entry.name), { recursive: true, force: true });
+    }
+}
+async function copyDirectoryContents(sourceDir, targetDir, options = {}) {
+    const exclude = options.exclude ?? new Set();
+    const preserveTargetEntries = options.preserveTargetEntries ?? new Set();
+    await ensureDir(targetDir);
+    await clearDirectory(targetDir, preserveTargetEntries);
+    if (!(await exists(sourceDir))) {
+        return;
+    }
+    let entries;
+    try {
+        entries = await fs.readdir(sourceDir, { withFileTypes: true });
+    }
+    catch {
+        return;
+    }
+    for (const entry of entries) {
+        if (exclude.has(entry.name)) {
+            continue;
+        }
+        const from = path.join(sourceDir, entry.name);
+        const to = path.join(targetDir, entry.name);
+        if (entry.isDirectory()) {
+            await fs.cp(from, to, { recursive: true, force: true });
+            continue;
+        }
+        if (entry.isFile()) {
+            await fs.copyFile(from, to);
+        }
+    }
+}
+async function dirHasEntries(dirPath, exclude = new Set()) {
+    if (!(await exists(dirPath))) {
+        return false;
+    }
+    try {
+        const entries = await fs.readdir(dirPath, { withFileTypes: true });
+        return entries.some((entry) => !exclude.has(entry.name));
+    }
+    catch {
+        return false;
+    }
+}
+async function readActiveFeatureMetaInternal(projectRoot) {
+    const filePath = activeFeatureMetaPath(projectRoot);
+    if (!(await exists(filePath))) {
+        return {
+            activeFeature: DEFAULT_FEATURE_ID,
+            updatedAt: new Date().toISOString()
+        };
+    }
+    try {
+        const parsed = JSON.parse(await fs.readFile(filePath, "utf8"));
+        const activeFeatureRaw = typeof parsed.activeFeature === "string"
+            ? parsed.activeFeature
+            : DEFAULT_FEATURE_ID;
+        const updatedAtRaw = typeof parsed.updatedAt === "string"
+            ? parsed.updatedAt
+            : new Date().toISOString();
+        return {
+            activeFeature: normalizedFeatureId(activeFeatureRaw),
+            updatedAt: updatedAtRaw
+        };
+    }
+    catch {
+        return {
+            activeFeature: DEFAULT_FEATURE_ID,
+            updatedAt: new Date().toISOString()
+        };
+    }
+}
+async function writeActiveFeatureMeta(projectRoot, meta) {
+    const normalized = {
+        activeFeature: normalizedFeatureId(meta.activeFeature),
+        updatedAt: meta.updatedAt
+    };
+    await writeFileSafe(activeFeatureMetaPath(projectRoot), `${JSON.stringify(normalized, null, 2)}\n`);
+}
+async function ensureFeatureSnapshot(projectRoot, featureId) {
+    const id = normalizedFeatureId(featureId);
+    await ensureDir(featureArtifactsPath(projectRoot, id));
+    await ensureDir(featureStatePath(projectRoot, id));
+}
+export async function readActiveFeature(projectRoot) {
+    const meta = await readActiveFeatureMetaInternal(projectRoot);
+    return normalizedFeatureId(meta.activeFeature);
+}
+export async function listFeatures(projectRoot) {
+    const root = featuresRoot(projectRoot);
+    if (!(await exists(root))) {
+        return [];
+    }
+    let entries;
+    try {
+        entries = await fs.readdir(root, { withFileTypes: true });
+    }
+    catch {
+        return [];
+    }
+    return entries
+        .filter((entry) => entry.isDirectory() && FEATURE_ID_PATTERN.test(entry.name))
+        .map((entry) => entry.name)
+        .sort((a, b) => a.localeCompare(b));
+}
+export async function ensureFeatureSystem(projectRoot) {
+    await ensureDir(featuresRoot(projectRoot));
+    await ensureDir(runtimeArtifactsRoot(projectRoot));
+    await ensureDir(runtimeStateRoot(projectRoot));
+    const existing = await readActiveFeatureMetaInternal(projectRoot);
+    const activeFeature = normalizedFeatureId(existing.activeFeature);
+    await ensureFeatureSnapshot(projectRoot, activeFeature);
+    const runtimeArtifactsHasData = await dirHasEntries(runtimeArtifactsRoot(projectRoot));
+    const runtimeStateHasData = await dirHasEntries(runtimeStateRoot(projectRoot), new Set(["active-feature.json"]));
+    const featureArtifactsHasData = await dirHasEntries(featureArtifactsPath(projectRoot, activeFeature));
+    const featureStateHasData = await dirHasEntries(featureStatePath(projectRoot, activeFeature));
+    if ((runtimeArtifactsHasData || runtimeStateHasData) && !featureArtifactsHasData && !featureStateHasData) {
+        await copyDirectoryContents(runtimeArtifactsRoot(projectRoot), featureArtifactsPath(projectRoot, activeFeature));
+        await copyDirectoryContents(runtimeStateRoot(projectRoot), featureStatePath(projectRoot, activeFeature), { exclude: FEATURE_STATE_EXCLUDE_FROM_SNAPSHOT });
+    }
+    else if ((!runtimeArtifactsHasData && !runtimeStateHasData) && (featureArtifactsHasData || featureStateHasData)) {
+        await copyDirectoryContents(featureArtifactsPath(projectRoot, activeFeature), runtimeArtifactsRoot(projectRoot));
+        await copyDirectoryContents(featureStatePath(projectRoot, activeFeature), runtimeStateRoot(projectRoot), { preserveTargetEntries: new Set(["active-feature.json"]) });
+    }
+    const normalized = {
+        activeFeature,
+        updatedAt: new Date().toISOString()
+    };
+    await writeActiveFeatureMeta(projectRoot, normalized);
+    return normalized;
+}
+export async function syncActiveFeatureSnapshot(projectRoot) {
+    const activeFeature = await readActiveFeature(projectRoot);
+    await ensureFeatureSnapshot(projectRoot, activeFeature);
+    await copyDirectoryContents(runtimeArtifactsRoot(projectRoot), featureArtifactsPath(projectRoot, activeFeature));
+    await copyDirectoryContents(runtimeStateRoot(projectRoot), featureStatePath(projectRoot, activeFeature), {
+        exclude: FEATURE_STATE_EXCLUDE_FROM_SNAPSHOT
+    });
+}
+export async function switchActiveFeature(projectRoot, featureId) {
+    await ensureFeatureSystem(projectRoot);
+    const current = await readActiveFeature(projectRoot);
+    const target = normalizedFeatureId(featureId);
+    if (current === target) {
+        const unchanged = {
+            activeFeature: current,
+            updatedAt: new Date().toISOString()
+        };
+        await writeActiveFeatureMeta(projectRoot, unchanged);
+        return unchanged;
+    }
+    await syncActiveFeatureSnapshot(projectRoot);
+    await ensureFeatureSnapshot(projectRoot, target);
+    await copyDirectoryContents(featureArtifactsPath(projectRoot, target), runtimeArtifactsRoot(projectRoot));
+    await copyDirectoryContents(featureStatePath(projectRoot, target), runtimeStateRoot(projectRoot), {
+        preserveTargetEntries: new Set(["active-feature.json"])
+    });
+    const nextMeta = {
+        activeFeature: target,
+        updatedAt: new Date().toISOString()
+    };
+    await writeActiveFeatureMeta(projectRoot, nextMeta);
+    return nextMeta;
+}
+export async function createFeature(projectRoot, rawFeatureId, options = {}) {
+    await ensureFeatureSystem(projectRoot);
+    const featureId = normalizedFeatureId(rawFeatureId);
+    if (featureId === DEFAULT_FEATURE_ID && rawFeatureId.trim().length > 0 && rawFeatureId.trim().toLowerCase() !== "default") {
+        throw new Error(`Unable to create feature from "${rawFeatureId}" — use letters, numbers, and dashes.`);
+    }
+    const featureDir = featureRootPath(projectRoot, featureId);
+    if (await exists(featureDir)) {
+        throw new Error(`Feature "${featureId}" already exists.`);
+    }
+    await ensureFeatureSnapshot(projectRoot, featureId);
+    if (options.cloneActive === true) {
+        const activeFeature = await readActiveFeature(projectRoot);
+        await syncActiveFeatureSnapshot(projectRoot);
+        await copyDirectoryContents(featureArtifactsPath(projectRoot, activeFeature), featureArtifactsPath(projectRoot, featureId));
+        await copyDirectoryContents(featureStatePath(projectRoot, activeFeature), featureStatePath(projectRoot, featureId));
+    }
+    if (options.switchTo === true) {
+        await switchActiveFeature(projectRoot, featureId);
+    }
+    return featureId;
+}

package/dist/flow-state.d.ts

@@ -9,6 +9,25 @@ export interface StageGateState {
     passed: string[];
     blocked: string[];
 }
+export interface RewindRecord {
+    id: string;
+    fromStage: FlowStage;
+    toStage: FlowStage;
+    reason: string;
+    timestamp: string;
+    invalidatedStages: FlowStage[];
+}
+export interface StaleStageMarker {
+    rewindId: string;
+    reason: string;
+    markedAt: string;
+    acknowledgedAt?: string;
+}
+export interface RetroState {
+    required: boolean;
+    completedAt?: string;
+    compoundEntries: number;
+}
 export interface FlowState {
     activeRunId: string;
     currentStage: FlowStage;
@@ -19,6 +38,12 @@ export interface FlowState {
     track: FlowTrack;
     /** Stages explicitly skipped for this track (empty for standard; populated for quick). */
     skippedStages: FlowStage[];
+    /** Stages invalidated by rewind operations and awaiting explicit acknowledgement. */
+    staleStages: Partial<Record<FlowStage, StaleStageMarker>>;
+    /** Chronological rewind operations for the active run. */
+    rewinds: RewindRecord[];
+    /** Mandatory retrospective gate status before archive. */
+    retro: RetroState;
 }
 export interface InitialFlowStateOptions {
     activeRunId?: string;

package/dist/flow-state.js

@@ -41,7 +41,14 @@ export function createInitialFlowState(activeRunIdOrOptions = "active", maybeTra
         guardEvidence: {},
         stageGateCatalog,
         track,
-        skippedStages
+        skippedStages,
+        staleStages: {},
+        rewinds: [],
+        retro: {
+            required: false,
+            completedAt: undefined,
+            compoundEntries: 0
+        }
     };
 }
 export function canTransition(from, to) {