cclaw-cli 0.15.1 → 0.21.0

package/dist/doctor.js

@@ -14,7 +14,7 @@ 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 { ensureFeatureSystem, listFeatures, readActiveFeature, readFeatureWorktreeRegistry, resolveFeatureWorkspacePath, worktreeRegistryPath } 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";
@@ -25,7 +25,6 @@ import { CONTEXT_MODES, DEFAULT_CONTEXT_MODE } from "./content/contexts.js";
 import { DOCTOR_REFERENCE_MARKDOWN } from "./content/doctor-references.js";
 import { validateHookDocument } from "./hook-schema.js";
 const execFileAsync = promisify(execFile);
-const PREAMBLE_COOLDOWN_MS = 15 * 60 * 1000;
 async function isGitRepo(projectRoot) {
     try {
         await execFileAsync("git", ["rev-parse", "--is-inside-work-tree"], { cwd: projectRoot });
@@ -35,6 +34,27 @@ async function isGitRepo(projectRoot) {
         return false;
     }
 }
+async function gitWorktreePaths(projectRoot) {
+    try {
+        const { stdout } = await execFileAsync("git", ["worktree", "list", "--porcelain"], {
+            cwd: projectRoot
+        });
+        const out = new Set();
+        for (const line of stdout.split(/\r?\n/)) {
+            const trimmed = line.trim();
+            if (!trimmed.startsWith("worktree "))
+                continue;
+            const rawPath = trimmed.slice("worktree ".length).trim();
+            if (!rawPath)
+                continue;
+            out.add(path.resolve(rawPath));
+        }
+        return out;
+    }
+    catch {
+        return new Set();
+    }
+}
 async function resolveGitHooksDir(projectRoot) {
     try {
         const { stdout } = await execFileAsync("git", ["rev-parse", "--git-path", "hooks"], { cwd: projectRoot });
@@ -463,6 +483,7 @@ export async function doctorChecks(projectRoot, options = {}) {
         const hasMarkers = content.includes(CCLAW_MARKER_START) && content.includes(CCLAW_MARKER_END);
         const hasCcCommand = content.includes("/cc");
         const hasCcNext = content.includes("/cc-next");
+        const hasCcIdeate = content.includes("/cc-ideate");
         const hasCcLearn = content.includes("/cc-learn");
         const hasCcView = content.includes("/cc-view");
         const hasCcOps = content.includes("/cc-ops");
@@ -472,6 +493,7 @@ export async function doctorChecks(projectRoot, options = {}) {
         agentsBlockOk = hasMarkers
             && hasCcCommand
             && hasCcNext
+            && hasCcIdeate
             && hasCcLearn
             && hasCcView
             && hasCcOps
@@ -485,7 +507,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", "next", "status", "tree", "diff", "feature", "tdd-log", "retro", "rewind", "rewind-ack"]) {
+    for (const cmd of ["learn", "next", "ideate", "status", "tree", "diff", "feature", "tdd-log", "retro", "compound", "rewind"]) {
         const cmdPath = path.join(projectRoot, RUNTIME_ROOT, "commands", `${cmd}.md`);
         checks.push({
             name: `utility_command:${cmd}`,
@@ -496,12 +518,16 @@ export async function doctorChecks(projectRoot, options = {}) {
     // Utility skills
     for (const [folder, label] of [
         ["learnings", "learnings"],
+        ["flow-ideate", "flow-ideate"],
         ["flow-tree", "flow-tree"],
         ["flow-diff", "flow-diff"],
-        ["feature-workspaces", "feature-workspaces"],
+        ["using-git-worktrees", "using-git-worktrees"],
         ["tdd-cycle-log", "tdd-cycle-log"],
         ["flow-retro", "flow-retro"],
+        ["flow-compound", "flow-compound"],
         ["flow-rewind", "flow-rewind"],
+        ["verification-before-completion", "verification-before-completion"],
+        ["finishing-a-development-branch", "finishing-a-development-branch"],
         ["subagent-dev", "sdd"],
         ["parallel-dispatch", "parallel-agents"],
         ["session", "session"],
@@ -830,6 +856,102 @@ export async function doctorChecks(projectRoot, options = {}) {
             ? `legacy ${RUNTIME_ROOT}/knowledge.md must be removed — cclaw is JSONL-native`
             : `no legacy markdown store present`
     });
+    const knowledgePath = path.join(projectRoot, RUNTIME_ROOT, "knowledge.jsonl");
+    if (await exists(knowledgePath)) {
+        let malformedKnowledgeLines = 0;
+        let missingSchemaV2Fields = 0;
+        let parsedKnowledgeLines = 0;
+        let lowConfidenceLines = 0;
+        const triggerActionCounts = new Map();
+        const requiredV2Fields = [
+            "type",
+            "trigger",
+            "action",
+            "confidence",
+            "domain",
+            "stage",
+            "origin_stage",
+            "origin_feature",
+            "frequency",
+            "universality",
+            "maturity",
+            "created",
+            "first_seen_ts",
+            "last_seen_ts",
+            "project"
+        ];
+        try {
+            const raw = await fs.readFile(knowledgePath, "utf8");
+            const lines = raw
+                .split("\n")
+                .map((line) => line.trim())
+                .filter((line) => line.length > 0);
+            for (const line of lines) {
+                try {
+                    const parsed = JSON.parse(line);
+                    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+                        malformedKnowledgeLines += 1;
+                        continue;
+                    }
+                    parsedKnowledgeLines += 1;
+                    const confidence = typeof parsed.confidence === "string" ? parsed.confidence.toLowerCase() : "";
+                    if (confidence === "low") {
+                        lowConfidenceLines += 1;
+                    }
+                    const trigger = typeof parsed.trigger === "string" ? parsed.trigger.trim().toLowerCase() : "";
+                    const action = typeof parsed.action === "string" ? parsed.action.trim().toLowerCase() : "";
+                    if (trigger.length > 0 && action.length > 0) {
+                        const key = `${trigger} => ${action}`;
+                        triggerActionCounts.set(key, (triggerActionCounts.get(key) ?? 0) + 1);
+                    }
+                    const missing = requiredV2Fields.some((field) => !Object.prototype.hasOwnProperty.call(parsed, field));
+                    if (missing) {
+                        missingSchemaV2Fields += 1;
+                    }
+                }
+                catch {
+                    malformedKnowledgeLines += 1;
+                }
+            }
+        }
+        catch {
+            malformedKnowledgeLines += 1;
+        }
+        checks.push({
+            name: "knowledge:jsonl_parseable",
+            ok: malformedKnowledgeLines === 0,
+            details: malformedKnowledgeLines === 0
+                ? "knowledge.jsonl lines parse as JSON objects"
+                : `knowledge.jsonl contains ${malformedKnowledgeLines} malformed line(s)`
+        });
+        checks.push({
+            name: "warning:knowledge:schema_v2_fields",
+            ok: true,
+            details: parsedKnowledgeLines === 0
+                ? "knowledge.jsonl is empty"
+                : missingSchemaV2Fields === 0
+                    ? `all ${parsedKnowledgeLines} knowledge line(s) include schema v2 fields`
+                    : `warning: ${missingSchemaV2Fields}/${parsedKnowledgeLines} knowledge line(s) miss schema v2 fields (origin/maturity/frequency metadata)`
+        });
+        const lowConfidenceRatio = parsedKnowledgeLines === 0 ? 0 : lowConfidenceLines / parsedKnowledgeLines;
+        checks.push({
+            name: "warning:knowledge:low_confidence_density",
+            ok: true,
+            details: parsedKnowledgeLines === 0
+                ? "knowledge.jsonl is empty"
+                : lowConfidenceRatio <= 0.35
+                    ? `low-confidence entries: ${lowConfidenceLines}/${parsedKnowledgeLines}`
+                    : `warning: low-confidence entries are high (${lowConfidenceLines}/${parsedKnowledgeLines}, ${(lowConfidenceRatio * 100).toFixed(1)}%). Consider /cc-learn curate before adding more.`
+        });
+        const repeatedClusters = [...triggerActionCounts.entries()].filter(([, count]) => count >= 3);
+        checks.push({
+            name: "warning:knowledge:repeat_clusters",
+            ok: true,
+            details: repeatedClusters.length === 0
+                ? "no high-frequency repeated trigger/action clusters detected"
+                : `warning: ${repeatedClusters.length} repeated learning cluster(s) detected (>=3 repeats). Consider /cc-ops compound to lift them into rules/skills.`
+        });
+    }
     checks.push({
         name: "state:checkpoint_exists",
         ok: await exists(path.join(projectRoot, RUNTIME_ROOT, "state", "checkpoint.json")),
@@ -840,6 +962,54 @@ export async function doctorChecks(projectRoot, options = {}) {
         ok: await exists(path.join(projectRoot, RUNTIME_ROOT, "state", "stage-activity.jsonl")),
         details: `${RUNTIME_ROOT}/state/stage-activity.jsonl must exist`
     });
+    const stageActivityPath = path.join(projectRoot, RUNTIME_ROOT, "state", "stage-activity.jsonl");
+    if (await exists(stageActivityPath)) {
+        let malformedActivityLines = 0;
+        let missingSchemaVersion = 0;
+        let parsedActivityLines = 0;
+        try {
+            const raw = await fs.readFile(stageActivityPath, "utf8");
+            const lines = raw
+                .split("\n")
+                .map((line) => line.trim())
+                .filter((line) => line.length > 0);
+            for (const line of lines) {
+                try {
+                    const parsed = JSON.parse(line);
+                    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+                        malformedActivityLines += 1;
+                        continue;
+                    }
+                    parsedActivityLines += 1;
+                    if (parsed.schemaVersion !== 1) {
+                        missingSchemaVersion += 1;
+                    }
+                }
+                catch {
+                    malformedActivityLines += 1;
+                }
+            }
+        }
+        catch {
+            malformedActivityLines += 1;
+        }
+        checks.push({
+            name: "state:stage_activity_jsonl_parseable",
+            ok: malformedActivityLines === 0,
+            details: malformedActivityLines === 0
+                ? "stage-activity.jsonl lines parse as JSON objects"
+                : `stage-activity.jsonl contains ${malformedActivityLines} malformed line(s)`
+        });
+        checks.push({
+            name: "warning:state:stage_activity_schema_version",
+            ok: true,
+            details: parsedActivityLines === 0
+                ? "stage-activity.jsonl is empty"
+                : missingSchemaVersion === 0
+                    ? `all ${parsedActivityLines} stage-activity line(s) include schemaVersion=1`
+                    : `warning: ${missingSchemaVersion}/${parsedActivityLines} stage-activity line(s) missing schemaVersion=1`
+        });
+    }
     checks.push({
         name: "state:suggestion_memory_exists",
         ok: await exists(path.join(projectRoot, RUNTIME_ROOT, "state", "suggestion-memory.json")),
@@ -880,81 +1050,6 @@ export async function doctorChecks(projectRoot, options = {}) {
             details: modePath
         });
     }
-    const preambleLogPath = path.join(projectRoot, RUNTIME_ROOT, "state", "preamble-log.jsonl");
-    const preambleLogExists = await exists(preambleLogPath);
-    checks.push({
-        name: "state:preamble_log_exists",
-        ok: preambleLogExists,
-        details: `${RUNTIME_ROOT}/state/preamble-log.jsonl must exist for preamble budget tracking`
-    });
-    if (preambleLogExists) {
-        let duplicateHits = 0;
-        let parsedEntries = 0;
-        let malformedEntries = 0;
-        try {
-            const now = Date.now();
-            const byKey = new Map();
-            const raw = await fs.readFile(preambleLogPath, "utf8");
-            const lines = raw
-                .split("\n")
-                .map((line) => line.trim())
-                .filter((line) => line.length > 0);
-            for (const line of lines) {
-                try {
-                    const parsed = JSON.parse(line);
-                    const tsRaw = parsed.ts;
-                    const stageRaw = parsed.stage;
-                    const triggerRaw = parsed.trigger;
-                    const hashRaw = parsed.hash;
-                    if (typeof tsRaw !== "string" ||
-                        typeof stageRaw !== "string" ||
-                        typeof triggerRaw !== "string" ||
-                        typeof hashRaw !== "string") {
-                        malformedEntries += 1;
-                        continue;
-                    }
-                    const stamp = Date.parse(tsRaw);
-                    if (!Number.isFinite(stamp)) {
-                        malformedEntries += 1;
-                        continue;
-                    }
-                    if (now - stamp > 24 * 60 * 60 * 1000) {
-                        continue;
-                    }
-                    parsedEntries += 1;
-                    const key = `${stageRaw}|${triggerRaw}|${hashRaw}`;
-                    const bucket = byKey.get(key) ?? [];
-                    bucket.push(stamp);
-                    byKey.set(key, bucket);
-                }
-                catch {
-                    malformedEntries += 1;
-                }
-            }
-            for (const stamps of byKey.values()) {
-                stamps.sort((a, b) => a - b);
-                for (let i = 1; i < stamps.length; i += 1) {
-                    if (stamps[i] - stamps[i - 1] < PREAMBLE_COOLDOWN_MS) {
-                        duplicateHits += 1;
-                    }
-                }
-            }
-        }
-        catch {
-            malformedEntries += 1;
-        }
-        checks.push({
-            name: "warning:preamble:dedup",
-            ok: true,
-            details: duplicateHits > 0
-                ? `warning: detected ${duplicateHits} repeated preamble emission(s) inside ${Math.floor(PREAMBLE_COOLDOWN_MS / 60000)}m cooldown window`
-                : parsedEntries > 0
-                    ? `preamble budget healthy (${parsedEntries} recent preamble entry/entries checked)`
-                    : malformedEntries > 0
-                        ? `warning: preamble log exists but entries are malformed (${malformedEntries} line(s) ignored)`
-                        : "preamble log is empty; no recent preamble emissions recorded"
-        });
-    }
     await ensureFeatureSystem(projectRoot);
     const activeFeature = await readActiveFeature(projectRoot);
     let flowState = await readFlowState(projectRoot);
@@ -1011,31 +1106,117 @@ 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 artifactsRoot = path.join(projectRoot, RUNTIME_ROOT, "artifacts");
+    let artifactPlaceholderHits = [];
+    if (await exists(artifactsRoot)) {
+        try {
+            const entries = await fs.readdir(artifactsRoot, { withFileTypes: true });
+            const placeholderPattern = /\b(?:TODO|TBD|FIXME)\b|<fill-in>|<your-.*-here>/giu;
+            for (const entry of entries) {
+                if (!entry.isFile() || !entry.name.endsWith(".md"))
+                    continue;
+                const filePath = path.join(artifactsRoot, entry.name);
+                const content = await fs.readFile(filePath, "utf8");
+                const matchCount = (content.match(placeholderPattern) ?? []).length;
+                if (matchCount > 0) {
+                    artifactPlaceholderHits.push(`${entry.name}:${matchCount}`);
+                }
+            }
+        }
+        catch {
+            artifactPlaceholderHits = [];
+        }
+    }
+    checks.push({
+        name: "warning:artifacts:stale_placeholders",
+        ok: true,
+        details: artifactPlaceholderHits.length === 0
+            ? "no TODO/TBD/FIXME placeholder markers found in active artifacts"
+            : `warning: placeholder markers detected in active artifacts (${artifactPlaceholderHits.join(", ")}). Clear before marking completion.`
+    });
     const features = await listFeatures(projectRoot);
+    const worktreeRegistry = await readFeatureWorktreeRegistry(projectRoot);
+    const activeFeatureEntry = worktreeRegistry.entries.find((entry) => entry.featureId === activeFeature);
+    const activeFeatureWorkspacePath = activeFeatureEntry
+        ? resolveFeatureWorkspacePath(projectRoot, activeFeatureEntry)
+        : "";
     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:worktree_registry_exists",
+        ok: await exists(worktreeRegistryPath(projectRoot)),
+        details: `${RUNTIME_ROOT}/state/worktrees.json must exist and track feature->worktree mapping`
+    });
     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`
+            ? `active feature "${activeFeature}" is present in ${RUNTIME_ROOT}/state/worktrees.json`
+            : `active feature "${activeFeature}" is missing from ${RUNTIME_ROOT}/state/worktrees.json`
     });
     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`
+            ? `${features.length} registered feature workspace(s): ${features.join(", ")}`
+            : `no feature workspaces found in ${RUNTIME_ROOT}/state/worktrees.json`
+    });
+    checks.push({
+        name: "state:active_feature_workspace_path",
+        ok: activeFeatureEntry ? await exists(activeFeatureWorkspacePath) : false,
+        details: activeFeatureEntry
+            ? `active feature "${activeFeature}" maps to workspace path ${activeFeatureEntry.path} (${activeFeatureEntry.source})`
+            : `active feature "${activeFeature}" has no worktree registry entry`
+    });
+    const missingRegistryPaths = [];
+    for (const entry of worktreeRegistry.entries) {
+        const workspacePath = resolveFeatureWorkspacePath(projectRoot, entry);
+        if (!(await exists(workspacePath))) {
+            missingRegistryPaths.push(`${entry.featureId}:${entry.path}`);
+        }
+    }
+    checks.push({
+        name: "state:worktree_registry_paths_exist",
+        ok: missingRegistryPaths.length === 0,
+        details: missingRegistryPaths.length === 0
+            ? "all worktree registry entries resolve to existing paths"
+            : `missing worktree paths for registry entries: ${missingRegistryPaths.join(", ")}`
+    });
+    const gitTrackedPaths = await gitWorktreePaths(projectRoot);
+    const registryGitPaths = worktreeRegistry.entries
+        .filter((entry) => entry.source === "git-worktree")
+        .map((entry) => resolveFeatureWorkspacePath(projectRoot, entry));
+    const missingFromGitList = registryGitPaths.filter((workspacePath) => !gitTrackedPaths.has(path.resolve(workspacePath)));
+    checks.push({
+        name: "warning:state:worktree_registry_git_drift",
+        ok: true,
+        details: missingFromGitList.length === 0
+            ? "git-worktree registry entries align with `git worktree list`"
+            : `warning: ${missingFromGitList.length} registry worktree path(s) are missing from \`git worktree list\`: ${missingFromGitList.join(", ")}`
+    });
+    const managedWorktreeRoot = path.join(projectRoot, RUNTIME_ROOT, "worktrees");
+    const unregisteredManagedWorktrees = [...gitTrackedPaths]
+        .filter((workspacePath) => workspacePath.startsWith(path.resolve(managedWorktreeRoot)))
+        .filter((workspacePath) => !registryGitPaths.some((registeredPath) => path.resolve(registeredPath) === workspacePath));
+    checks.push({
+        name: "warning:state:worktree_unregistered_paths",
+        ok: true,
+        details: unregisteredManagedWorktrees.length === 0
+            ? "no unmanaged git worktrees under .cclaw/worktrees"
+            : `warning: unregistered git worktree paths detected: ${unregisteredManagedWorktrees.map((value) => path.relative(projectRoot, value)).join(", ")}`
     });
+    const legacyWorkspaceEntries = worktreeRegistry.entries
+        .filter((entry) => entry.source === "legacy-snapshot")
+        .map((entry) => entry.featureId);
     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`
+        name: "warning:state:legacy_feature_snapshots",
+        ok: legacyWorkspaceEntries.length === 0,
+        details: legacyWorkspaceEntries.length === 0
+            ? "no legacy .cclaw/features snapshot entries remain"
+            : `legacy snapshot entries still present (read-only): ${legacyWorkspaceEntries.join(", ")}`
     });
     const staleStages = Object.keys(flowState.staleStages).filter((value) => COMMAND_FILE_ORDER.includes(value));
     checks.push({
@@ -1043,7 +1224,7 @@ export async function doctorChecks(projectRoot, options = {}) {
         ok: staleStages.length === 0,
         details: staleStages.length === 0
             ? "no stale stages pending acknowledgement"
-            : `stale stages must be acknowledged via /cc-ops rewind-ack: ${staleStages.join(", ")}`
+            : `stale stages must be acknowledged via /cc-ops rewind --ack <stage>: ${staleStages.join(", ")}`
     });
     const retroRequired = flowState.completedStages.includes("ship");
     const retroComplete = !retroRequired ||

package/dist/feature-system.d.ts

@@ -2,17 +2,34 @@ export interface ActiveFeatureMeta {
     activeFeature: string;
     updatedAt: string;
 }
+export type FeatureWorkspaceSource = "git-worktree" | "workspace" | "legacy-snapshot";
+export interface FeatureWorkspaceEntry {
+    featureId: string;
+    branch: string;
+    path: string;
+    source: FeatureWorkspaceSource;
+    createdAt: string;
+}
+export interface FeatureWorktreeRegistry {
+    schemaVersion: 1;
+    updatedAt: string;
+    entries: FeatureWorkspaceEntry[];
+}
+export interface CreateFeatureOptions {
+    cloneActive?: boolean;
+    switchTo?: boolean;
+}
 export declare function activeFeatureMetaPath(projectRoot: string): string;
+export declare function worktreeRegistryPath(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 resolveFeatureWorkspacePath(projectRoot: string, entry: FeatureWorkspaceEntry): string;
+export declare function ensureFeatureSystem(projectRoot: string): Promise<ActiveFeatureMeta>;
+export declare function readFeatureWorktreeRegistry(projectRoot: string): Promise<FeatureWorktreeRegistry>;
 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>;
+export declare function activeFeatureWorkspacePath(projectRoot: string): Promise<string>;