cclaw-cli 0.11.0 → 0.13.0

package/dist/install.js

@@ -10,6 +10,12 @@ 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 { 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 { 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";
@@ -21,11 +27,15 @@ import { TDD_WAVE_WALKTHROUGH_MARKDOWN, stageSkillFolder, stageSkillMarkdown } f
 import { stageCommonGuidanceMarkdown } from "./content/stage-common-guidance.js";
 import { STAGE_EXAMPLES_REFERENCE_DIR, stageExamplesReferenceMarkdown } from "./content/examples.js";
 import { LANGUAGE_RULE_PACK_DIR, LANGUAGE_RULE_PACK_FILES, LANGUAGE_RULE_PACK_GENERATORS, LEGACY_LANGUAGE_RULE_PACK_FOLDERS, UTILITY_SKILL_FOLDERS, UTILITY_SKILL_MAP } from "./content/utility-skills.js";
+import { RESEARCH_PLAYBOOKS } from "./content/research-playbooks.js";
 import { HARNESS_TOOL_REFS_DIR, HARNESS_TOOL_REFS_INDEX_MD, harnessToolRefMarkdown } from "./content/harness-tool-refs.js";
+import { DOCTOR_REFERENCE_MARKDOWN } from "./content/doctor-references.js";
+import { harnessIntegrationDocMarkdown } from "./content/harnesses-doc.js";
+import { HOOK_EVENTS_BY_HARNESS, HOOK_SEMANTIC_EVENTS } from "./content/hook-events.js";
 import { createInitialFlowState } from "./flow-state.js";
 import { ensureDir, exists, writeFileSafe } from "./fs-utils.js";
 import { ensureGitignore, removeGitignorePatterns } from "./gitignore.js";
-import { HARNESS_ADAPTERS, syncHarnessShims, removeCclawFromAgentsMd } from "./harness-adapters.js";
+import { HARNESS_ADAPTERS, harnessTier, syncHarnessShims, removeCclawFromAgentsMd } from "./harness-adapters.js";
 import { validateHookDocument } from "./hook-schema.js";
 import { ensureRunSystem, readFlowState } from "./runs.js";
 const OPENCODE_PLUGIN_REL_PATH = ".opencode/plugins/cclaw-plugin.mjs";
@@ -193,6 +203,12 @@ async function writeSkills(projectRoot, config) {
     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-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", "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", "subagent-dev", "SKILL.md"), subagentDrivenDevSkill());
     await writeFileSafe(runtimePath(projectRoot, "skills", "parallel-dispatch", "SKILL.md"), parallelAgentsSkill());
     await writeFileSafe(runtimePath(projectRoot, "skills", "session", "SKILL.md"), sessionHooksSkillMarkdown());
@@ -204,6 +220,10 @@ async function writeSkills(projectRoot, config) {
         const generator = UTILITY_SKILL_MAP[folder];
         await writeFileSafe(runtimePath(projectRoot, "skills", folder, "SKILL.md"), generator());
     }
+    // In-thread research procedures (no YAML frontmatter, not delegated personas).
+    for (const [fileName, markdown] of Object.entries(RESEARCH_PLAYBOOKS)) {
+        await writeFileSafe(runtimePath(projectRoot, "skills", "research", fileName), markdown);
+    }
     // Language rule packs live under .cclaw/rules/lang/<pack>.md. They are opt-in:
     // only the packs listed in config.languageRulePacks are materialised. Any
     // legacy per-language skill folders from v0.7.0 (.cclaw/skills/language-*)
@@ -231,12 +251,24 @@ async function writeSkills(projectRoot, config) {
     for (const harness of harnessIds) {
         await writeFileSafe(runtimePath(projectRoot, ...harnessRefsDir, `${harness}.md`), harnessToolRefMarkdown(harness));
     }
+    const doctorRefsDir = ["references", "doctor"];
+    for (const [fileName, markdown] of Object.entries(DOCTOR_REFERENCE_MARKDOWN)) {
+        await writeFileSafe(runtimePath(projectRoot, ...doctorRefsDir, fileName), markdown);
+    }
+    await writeFileSafe(runtimePath(projectRoot, "references", "harnesses.md"), harnessIntegrationDocMarkdown());
 }
 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", "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", "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", "rewind.md"), rewindCommandContract());
+    await writeFileSafe(runtimePath(projectRoot, "commands", "rewind-ack.md"), rewindAcknowledgeCommandContract());
 }
 function toObject(value) {
     if (!value || typeof value !== "object" || Array.isArray(value)) {
@@ -537,7 +569,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);
@@ -747,13 +782,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,
@@ -783,6 +818,21 @@ async function ensureSessionStateFiles(projectRoot) {
     if (!(await exists(knowledgeDigestPath))) {
         await writeFileSafe(knowledgeDigestPath, "# Knowledge digest (auto-generated)\n\n(no entries yet)\n");
     }
+    const preambleLogPath = path.join(stateDir, "preamble-log.jsonl");
+    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);
@@ -846,6 +896,33 @@ async function writeAdapterManifest(projectRoot, harnesses) {
     };
     await writeFileSafe(runtimePath(projectRoot, "adapters", "manifest.json"), `${JSON.stringify(manifest, null, 2)}\n`);
 }
+async function writeHarnessGapsState(projectRoot, harnesses) {
+    const report = harnesses.map((harness) => {
+        const capabilities = HARNESS_ADAPTERS[harness].capabilities;
+        const hookMap = HOOK_EVENTS_BY_HARNESS[harness];
+        const missingHookEvents = HOOK_SEMANTIC_EVENTS.filter((eventName) => !hookMap[eventName]);
+        const missingCapabilities = [];
+        if (capabilities.nativeSubagentDispatch !== "full") {
+            missingCapabilities.push(`nativeSubagentDispatch:${capabilities.nativeSubagentDispatch}`);
+        }
+        if (capabilities.hookSurface !== "full") {
+            missingCapabilities.push(`hookSurface:${capabilities.hookSurface}`);
+        }
+        if (capabilities.structuredAsk === "plain-text") {
+            missingCapabilities.push("structuredAsk:none");
+        }
+        return {
+            harness,
+            tier: harnessTier(harness),
+            missingCapabilities,
+            missingHookEvents
+        };
+    });
+    await writeFileSafe(runtimePath(projectRoot, "state", "harness-gaps.json"), `${JSON.stringify({
+        generatedAt: new Date().toISOString(),
+        harnesses: report
+    }, null, 2)}\n`);
+}
 async function cleanLegacyArtifacts(projectRoot) {
     // Remove deprecated utility skill folders from older releases.
     for (const legacyFolder of [
@@ -878,6 +955,23 @@ async function cleanLegacyArtifacts(projectRoot) {
     catch {
         // best-effort cleanup
     }
+    // Core-5 migration: remove deprecated generated agent personas.
+    for (const legacyAgentFile of [
+        "spec-reviewer.md",
+        "code-reviewer.md",
+        "repo-research-analyst.md",
+        "learnings-researcher.md",
+        "framework-docs-researcher.md",
+        "best-practices-researcher.md",
+        "git-history-analyzer.md"
+    ]) {
+        try {
+            await fs.rm(runtimePath(projectRoot, "agents", legacyAgentFile), { force: true });
+        }
+        catch {
+            // best-effort cleanup
+        }
+    }
     for (const legacyPlugin of [
         path.join(projectRoot, ".opencode/plugins/viby-plugin.mjs"),
         path.join(projectRoot, ".opencode/plugins/opencode-plugin.mjs"),
@@ -950,6 +1044,7 @@ async function materializeRuntime(projectRoot, config, forceStateReset) {
     await ensureRunSystem(projectRoot, { createIfMissing: false });
     await ensureSessionStateFiles(projectRoot);
     await writeAdapterManifest(projectRoot, harnesses);
+    await writeHarnessGapsState(projectRoot, harnesses);
     await ensureKnowledgeStore(projectRoot);
     await ensureCustomSkillsScaffold(projectRoot);
     await writeHooks(projectRoot, config);

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" },
@@ -98,6 +119,11 @@ export async function policyChecks(projectRoot, options = {}) {
         { file: runtimeFile("skills/parallel-dispatch/SKILL.md"), needle: "Review Army", name: "utility_skill:parallel:review_army" },
         { file: runtimeFile("skills/parallel-dispatch/SKILL.md"), needle: "Reconciliation", name: "utility_skill:parallel:reconciliation" },
         { file: runtimeFile("skills/parallel-dispatch/SKILL.md"), needle: "## Model & Harness Routing Notes", name: "utility_skill:parallel:routing_notes" },
+        { file: runtimeFile("skills/research/repo-scan.md"), needle: "# Repo Scan Playbook", name: "utility_skill:research:repo_scan" },
+        { file: runtimeFile("skills/research/learnings-lookup.md"), needle: "# Learnings Lookup Playbook", name: "utility_skill:research:learnings_lookup" },
+        { file: runtimeFile("skills/research/framework-docs-lookup.md"), needle: "# Framework Docs Lookup Playbook", name: "utility_skill:research:framework_docs_lookup" },
+        { file: runtimeFile("skills/research/best-practices-lookup.md"), needle: "# Best Practices Lookup Playbook", name: "utility_skill:research:best_practices_lookup" },
+        { file: runtimeFile("skills/research/git-history.md"), needle: "# Git History Playbook", name: "utility_skill:research:git_history" },
         { file: runtimeFile("skills/session/SKILL.md"), needle: "## HARD-GATE", name: "utility_skill:session:hard_gate" },
         { file: runtimeFile("skills/session/SKILL.md"), needle: "## Session Start Protocol", name: "utility_skill:session:start" },
         { file: runtimeFile("skills/session/SKILL.md"), needle: "## Session Stop Protocol", name: "utility_skill:session:stop" },
@@ -153,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