cclaw-cli 0.15.1 → 0.18.0

package/dist/delegation.js

@@ -12,6 +12,20 @@ function delegationLogPath(projectRoot) {
 function delegationLockPath(projectRoot) {
     return path.join(projectRoot, RUNTIME_ROOT, "state", ".delegation.lock");
 }
+function createSpanId() {
+    return `dspan-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 10)}`;
+}
+function isDelegationTokenUsage(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return false;
+    const o = value;
+    return (typeof o.input === "number" &&
+        Number.isFinite(o.input) &&
+        typeof o.output === "number" &&
+        Number.isFinite(o.output) &&
+        typeof o.model === "string" &&
+        o.model.trim().length > 0);
+}
 function isDelegationEntry(value) {
     if (!value || typeof value !== "object" || Array.isArray(value))
         return false;
@@ -21,15 +35,30 @@ function isDelegationEntry(value) {
         o.status === "completed" ||
         o.status === "failed" ||
         o.status === "waived";
+    const timestampOk = typeof o.ts === "string" ||
+        typeof o.startTs === "string";
+    const retryOk = o.retryCount === undefined ||
+        (typeof o.retryCount === "number" &&
+            Number.isFinite(o.retryCount) &&
+            Number.isInteger(o.retryCount) &&
+            o.retryCount >= 0);
     return (typeof o.stage === "string" &&
         typeof o.agent === "string" &&
         modeOk &&
         statusOk &&
-        typeof o.ts === "string" &&
+        timestampOk &&
+        (o.spanId === undefined || typeof o.spanId === "string") &&
+        (o.parentSpanId === undefined || typeof o.parentSpanId === "string") &&
+        (o.startTs === undefined || typeof o.startTs === "string") &&
+        (o.endTs === undefined || typeof o.endTs === "string") &&
         (o.taskId === undefined || typeof o.taskId === "string") &&
         (o.waiverReason === undefined || typeof o.waiverReason === "string") &&
         (o.runId === undefined || typeof o.runId === "string") &&
-        (o.conditionTrigger === undefined || typeof o.conditionTrigger === "string"));
+        (o.conditionTrigger === undefined || typeof o.conditionTrigger === "string") &&
+        (o.tokens === undefined || isDelegationTokenUsage(o.tokens)) &&
+        retryOk &&
+        (o.evidenceRefs === undefined || (Array.isArray(o.evidenceRefs) && o.evidenceRefs.every((item) => typeof item === "string"))) &&
+        (o.schemaVersion === undefined || o.schemaVersion === 1));
 }
 function parseLedger(raw, runId) {
     if (!raw || typeof raw !== "object" || Array.isArray(raw)) {
@@ -41,7 +70,18 @@ function parseLedger(raw, runId) {
     if (Array.isArray(entriesRaw)) {
         for (const item of entriesRaw) {
             if (isDelegationEntry(item)) {
-                entries.push(item);
+                const ts = item.startTs ?? item.ts ?? new Date().toISOString();
+                entries.push({
+                    ...item,
+                    spanId: item.spanId ?? createSpanId(),
+                    startTs: ts,
+                    ts,
+                    retryCount: typeof item.retryCount === "number" && Number.isInteger(item.retryCount) && item.retryCount >= 0
+                        ? item.retryCount
+                        : 0,
+                    evidenceRefs: Array.isArray(item.evidenceRefs) ? item.evidenceRefs : [],
+                    schemaVersion: 1
+                });
             }
         }
     }
@@ -67,7 +107,20 @@ export async function appendDelegation(projectRoot, entry) {
     await withDirectoryLock(delegationLockPath(projectRoot), async () => {
         const filePath = delegationLogPath(projectRoot);
         const prior = await readDelegationLedger(projectRoot);
+        const startTs = entry.startTs ?? entry.ts ?? new Date().toISOString();
         const stamped = { ...entry, runId: entry.runId ?? activeRunId };
+        stamped.spanId = entry.spanId ?? createSpanId();
+        stamped.startTs = startTs;
+        stamped.ts = startTs;
+        stamped.schemaVersion = 1;
+        if (stamped.retryCount === undefined ||
+            !Number.isInteger(stamped.retryCount) ||
+            stamped.retryCount < 0) {
+            stamped.retryCount = 0;
+        }
+        if (!Array.isArray(stamped.evidenceRefs)) {
+            stamped.evidenceRefs = [];
+        }
         const ledger = {
             runId: activeRunId,
             entries: [...prior.entries, stamped]

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 });
@@ -485,7 +484,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", "status", "tree", "diff", "feature", "tdd-log", "retro", "rewind"]) {
         const cmdPath = path.join(projectRoot, RUNTIME_ROOT, "commands", `${cmd}.md`);
         checks.push({
             name: `utility_command:${cmd}`,
@@ -498,7 +497,7 @@ export async function doctorChecks(projectRoot, options = {}) {
         ["learnings", "learnings"],
         ["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-rewind", "flow-rewind"],
@@ -830,6 +829,72 @@ 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;
+        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 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)`
+        });
+    }
     checks.push({
         name: "state:checkpoint_exists",
         ok: await exists(path.join(projectRoot, RUNTIME_ROOT, "state", "checkpoint.json")),
@@ -840,6 +905,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 +993,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);
@@ -1012,30 +1050,51 @@ export async function doctorChecks(projectRoot, options = {}) {
         details: `${RUNTIME_ROOT}/artifacts must exist as the active artifact root`
     });
     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 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 +1102,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>;