cclaw-cli 0.15.0 → 0.18.0

package/dist/content/templates.js

@@ -1,7 +1,16 @@
 import { COMMAND_FILE_ORDER } from "../constants.js";
 import { orderedStageSchemas } from "./stage-schema.js";
 export const ARTIFACT_TEMPLATES = {
-    "01-brainstorm.md": `# Brainstorm Artifact
+    "01-brainstorm.md": `---
+stage: brainstorm
+schema_version: 1
+version: 0.18.0
+feature: <feature-id>
+locked_decisions: []
+inputs_hash: sha256:pending
+---
+
+# Brainstorm Artifact
 
 ## Context
 - **Project state:**
@@ -37,7 +46,16 @@ export const ARTIFACT_TEMPLATES = {
 - **Assumptions:**
 - **Open questions (or "None"):**
 `,
-    "02-scope.md": `# Scope Artifact
+    "02-scope.md": `---
+stage: scope
+schema_version: 1
+version: 0.18.0
+feature: <feature-id>
+locked_decisions: []
+inputs_hash: sha256:pending
+---
+
+# Scope Artifact
 
 ## Prime Directives
 - Zero silent failures:
@@ -94,6 +112,11 @@ export const ARTIFACT_TEMPLATES = {
 > is later dropped, keep the row and mark Priority \`DROPPED\`; if a new one is
 > added mid-flow, append with the next free R-number — do NOT reuse numbers.
 
+## Locked Decisions (D-XX)
+| Decision ID | Decision | Why locked now | Downstream impact |
+|---|---|---|---|
+| D-01 |  |  |  |
+
 ## In Scope / Out of Scope
 
 ### In Scope
@@ -126,7 +149,16 @@ export const ARTIFACT_TEMPLATES = {
 - Deferred:
 - Explicitly excluded:
 `,
-    "03-design.md": `# Design Artifact
+    "03-design.md": `---
+stage: design
+schema_version: 1
+version: 0.18.0
+feature: <feature-id>
+locked_decisions: []
+inputs_hash: sha256:pending
+---
+
+# Design Artifact
 
 ## Codebase Investigation
 | File | Current responsibility | Patterns discovered |
@@ -210,7 +242,16 @@ export const ARTIFACT_TEMPLATES = {
 
 **Decisions made:** 0 | **Unresolved:** 0
 `,
-    "04-spec.md": `# Specification Artifact
+    "04-spec.md": `---
+stage: spec
+schema_version: 1
+version: 0.18.0
+feature: <feature-id>
+locked_decisions: []
+inputs_hash: sha256:pending
+---
+
+# Specification Artifact
 
 ## Acceptance Criteria
 | ID | Requirement Ref (R#) | Criterion (observable/measurable/falsifiable) | Design Decision Ref |
@@ -254,7 +295,16 @@ export const ARTIFACT_TEMPLATES = {
 - Approved by:
 - Date:
 `,
-    "05-plan.md": `# Plan Artifact
+    "05-plan.md": `---
+stage: plan
+schema_version: 1
+version: 0.18.0
+feature: <feature-id>
+locked_decisions: []
+inputs_hash: sha256:pending
+---
+
+# Plan Artifact
 
 ## Dependency Graph
 - 
@@ -282,6 +332,7 @@ Execution rule: complete and verify each wave before starting the next wave.
 **Rules (apply before writing rows):**
 - Every task fits the **2-5 minute budget**. If \`[~Nm]\` is >5, split the task.
 - **No placeholders.** Forbidden tokens anywhere in this table: \`TODO\`, \`TBD\`, \`FIXME\`, \`<fill-in>\`, \`<your-*-here>\`, \`xxx\`, bare ellipsis. Every file path, test, and verification command must be copy-pasteable as written.
+- **No silent scope reduction.** Forbidden phrasing when locked decisions exist: \`v1\`, \`for now\`, \`later\`, \`temporary\`, \`placeholder\`, \`mock for now\`, \`hardcoded for now\`, \`will improve later\`.
 - If an estimate is genuinely uncertain (new library, unfamiliar subsystem), add a **spike task in wave 0** to de-risk — do NOT hide the uncertainty inside a large estimate.
 
 | Task ID | Description | Acceptance criterion | Verification command | Effort (S/M/L) | Minutes |
@@ -293,6 +344,11 @@ Execution rule: complete and verify each wave before starting the next wave.
 |---|---|
 | AC-1 | T-1 |
 
+## Locked Decision Coverage
+| Decision ID | Source section | Plan tasks implementing decision | Status |
+|---|---|---|---|
+| D-01 | 02-scope.md > Locked Decisions | T-1 | covered |
+
 ## Risk Assessment
 | Task/Wave | Risk | Likelihood | Impact | Mitigation |
 |---|---|---|---|---|
@@ -307,11 +363,24 @@ Execution rule: complete and verify each wave before starting the next wave.
 - Scanned tokens: \`TODO\`, \`TBD\`, \`FIXME\`, \`<fill-in>\`, \`<your-*-here>\`, \`xxx\`, bare ellipsis in task rows.
 - Hits: 0 (required for WAIT_FOR_CONFIRM to resolve).
 
+## No Scope Reduction Language Scan
+- Scanned phrases: \`v1\`, \`for now\`, \`later\`, \`temporary\`, \`placeholder\`, \`mock for now\`, \`hardcoded for now\`, \`will improve later\`.
+- Hits: 0 (required when Locked Decisions section is non-empty).
+
 ## WAIT_FOR_CONFIRM
 - Status: pending
 - Confirmed by:
 `,
-    "06-tdd.md": `# TDD Artifact
+    "06-tdd.md": `---
+stage: tdd
+schema_version: 1
+version: 0.18.0
+feature: <feature-id>
+locked_decisions: []
+inputs_hash: sha256:pending
+---
+
+# TDD Artifact
 
 ## RED Evidence
 | Slice | Test name | Command | Failure output summary |
@@ -366,7 +435,16 @@ Execution rule: complete and verify each wave before starting the next wave.
 |---|---|---|---|---|
 | S-1 |  |  |  |  |
 `,
-    "07-review.md": `# Review Artifact
+    "07-review.md": `---
+stage: review
+schema_version: 1
+version: 0.18.0
+feature: <feature-id>
+locked_decisions: []
+inputs_hash: sha256:pending
+---
+
+# Review Artifact
 
 ## Layer 1 Verdict
 | Criterion | Verdict | Evidence |
@@ -444,7 +522,16 @@ Execution rule: complete and verify each wave before starting the next wave.
   }
 }
 `,
-    "08-ship.md": `# Ship Artifact
+    "08-ship.md": `---
+stage: ship
+schema_version: 1
+version: 0.18.0
+feature: <feature-id>
+locked_decisions: []
+inputs_hash: sha256:pending
+---
+
+# Ship Artifact
 
 ## Preflight Results
 - Review verdict:
@@ -485,7 +572,16 @@ Execution rule: complete and verify each wave before starting the next wave.
 - Retro artifact path: \`.cclaw/artifacts/09-retro.md\`
 - Archive remains blocked until retro gate is complete.
 `,
-    "09-retro.md": `# Retro Artifact
+    "09-retro.md": `---
+stage: retro
+schema_version: 1
+version: 0.18.0
+feature: <feature-id>
+locked_decisions: []
+inputs_hash: sha256:pending
+---
+
+# Retro Artifact
 
 ## Run Summary
 - Flow track:

package/dist/content/utility-skills.js

@@ -1271,7 +1271,7 @@ For each lens, write either a knowledge entry **or** the explicit string
 ## Output protocol
 
 For every harvested insight, append one strict-schema JSON line to
-\`.cclaw/knowledge.jsonl\` (fields: \`type, trigger, action, confidence, domain, stage, created, project\`).
+\`.cclaw/knowledge.jsonl\` (fields: \`type, trigger, action, confidence, domain, stage, origin_stage, origin_feature, frequency, universality, maturity, created, first_seen_ts, last_seen_ts, project\`).
 See the \`learnings\` skill for the canonical shape. Choose \`type\`:
 
 - \`compound\` for process/speed accelerators.

package/dist/delegation.d.ts

@@ -1,12 +1,34 @@
 import type { FlowStage } from "./types.js";
+export type DelegationMode = "mandatory" | "proactive" | "conditional";
+export type DelegationStatus = "scheduled" | "completed" | "failed" | "waived";
+export interface DelegationTokenUsage {
+    input: number;
+    output: number;
+    model: string;
+}
 export type DelegationEntry = {
     stage: string;
     agent: string;
-    mode: "mandatory" | "proactive" | "conditional";
-    status: "scheduled" | "completed" | "failed" | "waived";
+    mode: DelegationMode;
+    status: DelegationStatus;
+    /**
+     * Span identifier for this delegation unit. Multiple status transitions for
+     * the same delegated unit should reuse the same spanId.
+     */
+    spanId?: string;
+    /** Parent span id when this delegation was spawned from another span. */
+    parentSpanId?: string;
+    /** ISO timestamp when the delegation span started. */
+    startTs?: string;
+    /** ISO timestamp when the delegation span ended (for terminal statuses). */
+    endTs?: string;
+    /**
+     * Legacy timestamp used by historical ledgers. New writers set both `ts` and
+     * `startTs` for backward compatibility.
+     */
     taskId?: string;
     waiverReason?: string;
-    ts: string;
+    ts?: string;
     /**
      * Run id the entry belongs to. Older ledgers written before 0.5.17 may omit this;
      * consumers treat missing runId as unscoped (conservatively excluded from current-run checks).
@@ -17,6 +39,14 @@ export type DelegationEntry = {
      * Recorded for audit so reviewers can see why the second pass was required.
      */
     conditionTrigger?: string;
+    /** Optional token usage captured from the delegated run. */
+    tokens?: DelegationTokenUsage;
+    /** Number of retries attempted for this span. */
+    retryCount?: number;
+    /** Optional references to evidence anchors in artifacts. */
+    evidenceRefs?: string[];
+    /** Schema version marker for span-compatible delegation logs. */
+    schemaVersion?: 1;
 };
 export type DelegationLedger = {
     runId: string;

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