cclaw-cli 0.11.0 → 0.13.0

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) {

package/dist/harness-adapters.d.ts

@@ -4,8 +4,15 @@ export declare const CCLAW_MARKER_END = "<!-- cclaw-end -->";
 export interface HarnessAdapter {
     id: HarnessId;
     commandDir: string;
+    capabilities: {
+        nativeSubagentDispatch: "full" | "partial" | "none";
+        hookSurface: "full" | "plugin" | "limited" | "none";
+        structuredAsk: "AskUserQuestion" | "AskQuestion" | "plain-text";
+    };
 }
 export declare const HARNESS_ADAPTERS: Record<HarnessId, HarnessAdapter>;
+export type HarnessTier = "tier1" | "tier2" | "tier3";
+export declare function harnessTier(harnessId: HarnessId): HarnessTier;
 /** Removes the cclaw AGENTS.md block. */
 export declare function stripCclawBlock(content: string): string;
 export declare function removeCclawFromAgentsMd(projectRoot: string): Promise<void>;

package/dist/harness-adapters.js

@@ -1,7 +1,7 @@
 import fs from "node:fs/promises";
 import path from "node:path";
 import { RUNTIME_ROOT } from "./constants.js";
-import { CCLAW_AGENTS, agentMarkdown } from "./content/agents.js";
+import { CCLAW_AGENTS, agentMarkdown } from "./content/core-agents.js";
 import { ensureDir, exists, writeFileSafe } from "./fs-utils.js";
 export const CCLAW_MARKER_START = "<!-- cclaw-start -->";
 export const CCLAW_MARKER_END = "<!-- cclaw-end -->";
@@ -11,12 +11,120 @@ function escapeRegExp(value) {
 const RUNTIME_AGENTS_BLOCK_SOURCE = `${escapeRegExp(CCLAW_MARKER_START)}[\\s\\S]*?${escapeRegExp(CCLAW_MARKER_END)}`;
 const RUNTIME_AGENTS_BLOCK_PATTERN = new RegExp(RUNTIME_AGENTS_BLOCK_SOURCE, "u");
 const RUNTIME_AGENTS_BLOCK_GLOBAL_PATTERN = new RegExp(RUNTIME_AGENTS_BLOCK_SOURCE, "gu");
+const UTILITY_SHIMS = [
+    {
+        fileName: "cc-next.md",
+        command: "next",
+        skillFolder: "flow-next-step",
+        commandFile: "next.md"
+    },
+    {
+        fileName: "cc-learn.md",
+        command: "learn",
+        skillFolder: "learnings",
+        commandFile: "learn.md"
+    },
+    {
+        fileName: "cc-status.md",
+        command: "status",
+        skillFolder: "flow-status",
+        commandFile: "status.md"
+    },
+    {
+        fileName: "cc-tree.md",
+        command: "tree",
+        skillFolder: "flow-tree",
+        commandFile: "tree.md"
+    },
+    {
+        fileName: "cc-diff.md",
+        command: "diff",
+        skillFolder: "flow-diff",
+        commandFile: "diff.md"
+    },
+    {
+        fileName: "cc-feature.md",
+        command: "feature",
+        skillFolder: "feature-workspaces",
+        commandFile: "feature.md"
+    },
+    {
+        fileName: "cc-tdd-log.md",
+        command: "tdd-log",
+        skillFolder: "tdd-cycle-log",
+        commandFile: "tdd-log.md"
+    },
+    {
+        fileName: "cc-retro.md",
+        command: "retro",
+        skillFolder: "flow-retro",
+        commandFile: "retro.md"
+    },
+    {
+        fileName: "cc-rewind.md",
+        command: "rewind",
+        skillFolder: "flow-rewind",
+        commandFile: "rewind.md"
+    },
+    {
+        fileName: "cc-rewind-ack.md",
+        command: "rewind-ack",
+        skillFolder: "flow-rewind",
+        commandFile: "rewind-ack.md"
+    }
+];
 export const HARNESS_ADAPTERS = {
-    claude: { id: "claude", commandDir: ".claude/commands" },
-    cursor: { id: "cursor", commandDir: ".cursor/commands" },
-    opencode: { id: "opencode", commandDir: ".opencode/commands" },
-    codex: { id: "codex", commandDir: ".codex/commands" }
+    claude: {
+        id: "claude",
+        commandDir: ".claude/commands",
+        capabilities: {
+            nativeSubagentDispatch: "full",
+            hookSurface: "full",
+            structuredAsk: "AskUserQuestion"
+        }
+    },
+    cursor: {
+        id: "cursor",
+        commandDir: ".cursor/commands",
+        capabilities: {
+            nativeSubagentDispatch: "partial",
+            hookSurface: "full",
+            structuredAsk: "AskQuestion"
+        }
+    },
+    opencode: {
+        id: "opencode",
+        commandDir: ".opencode/commands",
+        capabilities: {
+            nativeSubagentDispatch: "partial",
+            hookSurface: "plugin",
+            structuredAsk: "plain-text"
+        }
+    },
+    codex: {
+        id: "codex",
+        commandDir: ".codex/commands",
+        capabilities: {
+            nativeSubagentDispatch: "none",
+            hookSurface: "full",
+            structuredAsk: "plain-text"
+        }
+    }
 };
+export function harnessTier(harnessId) {
+    const capabilities = HARNESS_ADAPTERS[harnessId].capabilities;
+    if (capabilities.nativeSubagentDispatch === "full" &&
+        capabilities.structuredAsk !== "plain-text" &&
+        capabilities.hookSurface === "full") {
+        return "tier1";
+    }
+    if (capabilities.hookSurface === "full" ||
+        capabilities.hookSurface === "plugin" ||
+        capabilities.nativeSubagentDispatch === "partial") {
+        return "tier2";
+    }
+    return "tier3";
+}
 function agentsMdBlock() {
     return `${CCLAW_MARKER_START}
 ## Cclaw — Workflow Adapter
@@ -52,21 +160,25 @@ When in doubt, prefer **non-trivial** — the quick track is opt-in and only saf
 5. Contextual utility skills.
 6. Training priors.
 
-### Commands (3 total)
+### Commands
 
 | Command | Purpose |
 |---|---|
 | \`/cc\` | **Entry point.** No args = resume current stage. With prompt = classify task and start the right flow. |
 | \`/cc-next\` | **Progression.** Advances to the next stage when current is complete. |
 | \`/cc-learn\` | **Cross-cutting.** Capture or review project knowledge (append-only JSONL). |
+| \`/cc-status\` | **Read-only.** Visual snapshot with progress bar, gate delta, and delegations. |
+| \`/cc-tree\` | **Read-only.** Deep flow tree for stages, artifacts, and stale markers. |
+| \`/cc-diff\` | **Delta map.** Compare current flow-state with saved baseline snapshot. |
+| \`/cc-feature\` | **Workspace.** Manage active feature snapshots for parallel tracks. |
+| \`/cc-tdd-log\` | **Evidence.** Record RED/GREEN/REFACTOR cycle events for enforcement. |
+| \`/cc-retro\` | **Learning gate.** Mandatory retrospective before archive after ship. |
+| \`/cc-rewind\` | **Recovery.** Rewind flow to an earlier stage and invalidate downstream work. |
+| \`/cc-rewind-ack\` | **Recovery.** Clear stale-stage markers after redo. |
 
 **Stage order:** brainstorm > scope > design > spec > plan > tdd > review > ship.
 \`/cc-next\` loads the right stage skill automatically. Gates must pass before handoff.
 
-### Invocation Preamble (non-trivial turns)
-
-Before starting substantive work, emit a one-paragraph preamble: **Stage**, **Goal**, **Plan** (next 1–3 actions), **Guardrails**. Skip for pure questions, trivial edits, and dispatched subagent invocations.
-
 ### Verification Discipline
 
 No completion claims without fresh evidence. No "Done" / "All good" / "Tests pass" without running the command in this message. Failed tool calls are diagnostic data, not instructions.
@@ -78,7 +190,9 @@ If the same approach fails three times in a row (same command, same finding, sam
 ### Detail Level
 
 - This managed AGENTS block is intentionally minimal for cross-project use.
+- Harness coverage is tiered: Tier1 (claude), Tier2 (cursor/opencode/codex), Tier3 (fallback/manual-only).
 - Detailed operating procedures live in \`.cclaw/skills/using-cclaw/SKILL.md\`.
+- Preamble budget and cooldown rules live in \`.cclaw/references/protocols/ethos.md\`.
 - Subagent orchestration patterns: \`.cclaw/skills/subagent-dev/SKILL.md\` and \`.cclaw/skills/parallel-dispatch/SKILL.md\`.
 ${CCLAW_MARKER_END}`;
 }
@@ -169,9 +283,9 @@ export async function syncHarnessShims(projectRoot, harnesses) {
         const commandDir = path.join(projectRoot, adapter.commandDir);
         await ensureDir(commandDir);
         await writeFileSafe(path.join(commandDir, "cc.md"), utilityShimContent(harness, "cc", "flow-start", "start.md"));
-        await writeFileSafe(path.join(commandDir, "cc-next.md"), utilityShimContent(harness, "next", "flow-next-step", "next.md"));
-        await writeFileSafe(path.join(commandDir, "cc-learn.md"), utilityShimContent(harness, "learn", "learnings", "learn.md"));
-        await writeFileSafe(path.join(commandDir, "cc-status.md"), utilityShimContent(harness, "status", "flow-status", "status.md"));
+        for (const shim of UTILITY_SHIMS) {
+            await writeFileSafe(path.join(commandDir, shim.fileName), utilityShimContent(harness, shim.command, shim.skillFolder, shim.commandFile));
+        }
     }
     await syncAgentFiles(projectRoot);
     await syncAgentsMd(projectRoot, harnesses);

package/dist/init-detect.d.ts

@@ -0,0 +1,2 @@
+import type { HarnessId } from "./types.js";
+export declare function detectHarnesses(projectRoot: string): Promise<HarnessId[]>;

package/dist/init-detect.js

@@ -0,0 +1,45 @@
+import path from "node:path";
+import { exists } from "./fs-utils.js";
+export async function detectHarnesses(projectRoot) {
+    const detected = [];
+    const claudeHints = [
+        path.join(projectRoot, ".claude"),
+        path.join(projectRoot, "CLAUDE.md")
+    ];
+    if (await anyExists(claudeHints)) {
+        detected.push("claude");
+    }
+    const cursorHints = [
+        path.join(projectRoot, ".cursor"),
+        path.join(projectRoot, ".cursor/rules")
+    ];
+    if (await anyExists(cursorHints)) {
+        detected.push("cursor");
+    }
+    const opencodeHints = [
+        path.join(projectRoot, ".opencode"),
+        path.join(projectRoot, "opencode.json"),
+        path.join(projectRoot, "opencode.jsonc"),
+        path.join(projectRoot, ".opencode/opencode.json"),
+        path.join(projectRoot, ".opencode/opencode.jsonc")
+    ];
+    if (await anyExists(opencodeHints)) {
+        detected.push("opencode");
+    }
+    const codexHints = [
+        path.join(projectRoot, ".codex"),
+        path.join(projectRoot, ".codex/hooks.json")
+    ];
+    if (await anyExists(codexHints)) {
+        detected.push("codex");
+    }
+    return detected;
+}
+async function anyExists(paths) {
+    for (const candidate of paths) {
+        if (await exists(candidate)) {
+            return true;
+        }
+    }
+    return false;
+}