mewkit 1.14.0 → 1.15.0

package/dist/core/task-record.js

@@ -0,0 +1,252 @@
+// Minimal durable task state (Phase 4): the one per-task record that lets a fresh session
+// resume and audit capability use. Plans stay the human source of truth — this record JOINS
+// to a plan by path, it does not replace it. Compatibility is governed by the record's own
+// `schemaVersion` checked against the CLI's supported range (OQ6 decision): the record is
+// decoupled from the npm-CLI version line and the kit-release version line, which are recorded
+// as provenance only. Integrity: validated id, realpath containment, atomic replace under a
+// per-file lock (reuses the install-metadata writer pattern).
+import { existsSync, mkdirSync, readFileSync, readdirSync, realpathSync } from "node:fs";
+import { rename, unlink, writeFile } from "node:fs/promises";
+import { join, relative, isAbsolute, sep } from "node:path";
+import { z } from "zod";
+import { withFileLock } from "./file-lock.js";
+import { distinctRepos } from "./repo-context.js";
+/** The record schema version THIS CLI writes. Bump on any breaking record shape change. */
+export const TASK_RECORD_SCHEMA_VERSION = "1.0";
+/** Record schema versions this CLI can safely READ. A record outside this set is rejected. */
+export const SUPPORTED_TASK_RECORD_SCHEMAS = new Set(["1.0"]);
+/** Valid task id: lowercase slug, filename-safe (it becomes `<id>.json`). */
+const TASK_ID_RE = /^[a-z0-9][a-z0-9-]{0,63}$/;
+export const CapabilityDecisionSchema = z.object({
+    capabilityId: z.string(),
+    decision: z.enum(["selected", "skipped", "unavailable", "unsupported"]),
+    reason: z.string(),
+    /** References the Phase-3 availability snapshot that justified the decision. */
+    adapterSnapshotId: z.string().optional(),
+});
+export const RepoRefSchema = z.object({
+    /** Stable repository identity (remote URL, path hash, or name) — never invented. */
+    identity: z.string(),
+    /** VCS revision when available; null for non-git roots (no fabricated revision). */
+    revision: z.string().nullable(),
+});
+export const TaskRecordSchema = z.object({
+    schemaVersion: z.literal("1.0"),
+    taskId: z.string().regex(TASK_ID_RE),
+    planPath: z.string().nullable().default(null),
+    status: z.enum(["active", "blocked", "done"]),
+    currentStep: z.string().default(""),
+    repos: z.array(RepoRefSchema).default([]),
+    blockers: z.array(z.string()).default([]),
+    nextAction: z.string().default(""),
+    verificationSummaries: z.array(z.object({ ref: z.string(), result: z.string() })).default([]),
+    evidenceRefs: z.array(z.string()).default([]),
+    capabilityDecisions: z.array(CapabilityDecisionSchema).default([]),
+    /** Provenance only (never the compatibility gate): who wrote this record. */
+    writtenByCli: z.string().default(""),
+    writtenByKit: z.string().default(""),
+    updatedAt: z.string(),
+})
+    // Preserve unknown keys through a read→write round-trip. A future CLI may add an
+    // additive field WITHOUT bumping schemaVersion (per the versioning note above); an older
+    // CLI must not silently strip it when it updates the record.
+    .passthrough();
+/** Thrown when a record's schemaVersion is outside this CLI's supported range (loud, non-zero). */
+export class IncompatibleTaskRecordError extends Error {
+    detail;
+    constructor(detail) {
+        super(`Incompatible task record: ${detail}`);
+        this.detail = detail;
+        this.name = "IncompatibleTaskRecordError";
+    }
+}
+/**
+ * `<projectRoot>/tasks/active` — the durable task-record home. This is the SAME path for a
+ * flat-copy AND a plugin install: task records are the CONSUMER PROJECT's state (keyed to the
+ * project the agent is working in, `process.cwd()`), not plugin-owned state. `tasks/` is
+ * framework-internal state that keeps its path (skill-authoring Rule 2's exception), so it does
+ * NOT move to `${CLAUDE_PLUGIN_DATA}` — that root is for a plugin's OWN cross-session data, and
+ * putting consumer task records there would misplace them. Resolves P4 open decision #2.
+ */
+function activeDir(projectRoot) {
+    return join(projectRoot, "tasks", "active");
+}
+/**
+ * The current active-plan pointer, mirroring the existing hook contract
+ * (`session-state/active-plan.json` → `path` || `slug`, else legacy plain-text
+ * `session-state/active-plan`). Null when absent. This is the CHECKPOINT JOIN: the task record
+ * whose `planPath` matches the pointer is the current task (resolves P4 open decision #3).
+ */
+export function readActivePlanPointer(projectRoot) {
+    const jsonPath = join(projectRoot, "session-state", "active-plan.json");
+    if (existsSync(jsonPath)) {
+        try {
+            const d = JSON.parse(readFileSync(jsonPath, "utf-8"));
+            const p = (typeof d.path === "string" && d.path) || (typeof d.slug === "string" && d.slug) || "";
+            if (p.trim())
+                return p.trim();
+        }
+        catch {
+            /* fall through to legacy */
+        }
+    }
+    const legacy = join(projectRoot, "session-state", "active-plan");
+    if (existsSync(legacy)) {
+        const txt = readFileSync(legacy, "utf-8").trim();
+        if (txt)
+            return txt;
+    }
+    return null;
+}
+/** Resolve a task-record path and assert it stays contained under tasks/active (realpath). */
+function recordPath(projectRoot, taskId) {
+    if (!TASK_ID_RE.test(taskId))
+        throw new Error(`invalid task id: ${JSON.stringify(taskId)}`);
+    const dir = activeDir(projectRoot);
+    const abs = join(dir, `${taskId}.json`);
+    // Lexical + realpath containment: the id regex already bars separators/.., this is defense in depth.
+    const rel = relative(dir, abs);
+    if (rel === ".." || rel.startsWith(".." + sep) || isAbsolute(rel))
+        throw new Error(`task path escapes tasks/active: ${taskId}`);
+    return abs;
+}
+/** Parse + version-check a record already read from disk. Throws on schema drift. */
+function parseAndCheck(raw) {
+    const parsed = JSON.parse(raw);
+    if (typeof parsed.schemaVersion === "string" && !SUPPORTED_TASK_RECORD_SCHEMAS.has(parsed.schemaVersion)) {
+        throw new IncompatibleTaskRecordError(`record schemaVersion "${parsed.schemaVersion}" not in supported ${JSON.stringify([...SUPPORTED_TASK_RECORD_SCHEMAS])}`);
+    }
+    return TaskRecordSchema.parse(parsed);
+}
+/** Read + version-check a single task record. Throws IncompatibleTaskRecordError on schema drift. */
+export function readTaskRecord(projectRoot, taskId) {
+    const abs = recordPath(projectRoot, taskId);
+    if (!existsSync(abs))
+        return null;
+    return parseAndCheck(readFileSync(abs, "utf-8"));
+}
+/** Atomic temp+rename write of an already-validated record (NO lock — callers hold it). */
+async function atomicReplace(target, record) {
+    const serialized = JSON.stringify(record, null, 2) + "\n";
+    const tmp = `${target}.tmp-${process.pid}`;
+    try {
+        await writeFile(tmp, serialized, "utf-8");
+        await rename(tmp, target);
+    }
+    catch (err) {
+        try {
+            await unlink(tmp);
+        }
+        catch {
+            /* best-effort cleanup */
+        }
+        throw err;
+    }
+}
+/** Prepare tasks/active and assert realpath containment; returns the resolved target path. */
+function prepareTarget(projectRoot, taskId) {
+    const dir = activeDir(projectRoot);
+    mkdirSync(dir, { recursive: true });
+    // Realpath containment — reject a symlinked tasks/active escaping the project root.
+    const relDir = relative(realpathSync(projectRoot), realpathSync(dir));
+    if (relDir.startsWith("..") || isAbsolute(relDir))
+        throw new Error("tasks/active escapes the project root");
+    return recordPath(projectRoot, taskId);
+}
+/**
+ * Atomically write a task record under a per-id lock. Refuses to overwrite an on-disk record
+ * whose schemaVersion this CLI cannot read (fails closed — never clobbers an incompatible
+ * record). Prefer `updateTaskRecord` for read-modify-write; this is the low-level put.
+ */
+export async function writeTaskRecord(projectRoot, record) {
+    const validated = TaskRecordSchema.parse(record);
+    const target = prepareTarget(projectRoot, validated.taskId);
+    const lockPath = join(activeDir(projectRoot), `.${validated.taskId}.lock`);
+    await withFileLock(lockPath, async () => {
+        if (existsSync(target))
+            parseAndCheck(readFileSync(target, "utf-8")); // throws if on-disk is incompatible
+        await atomicReplace(target, validated);
+    });
+}
+/**
+ * Read → mutate → write a task record atomically under ONE lock, so concurrent updates to the
+ * same id cannot lose each other's changes (the read-modify-write cycle is serialized). The
+ * mutator receives the current record (or null if absent) and returns the next one. An
+ * incompatible on-disk record makes the read throw before any write — it is never clobbered.
+ */
+export async function updateTaskRecord(projectRoot, taskId, mutate) {
+    const target = prepareTarget(projectRoot, taskId);
+    const lockPath = join(activeDir(projectRoot), `.${taskId}.lock`);
+    return withFileLock(lockPath, async () => {
+        const existing = existsSync(target) ? parseAndCheck(readFileSync(target, "utf-8")) : null;
+        const next = TaskRecordSchema.parse(mutate(existing));
+        await atomicReplace(target, next);
+        return next;
+    });
+}
+/**
+ * Record a repo-context envelope's evidence into an EXISTING durable task record (Phase 5
+ * slice 2). Merges — never replaces — so evidence accumulates across a task's steps:
+ * - `repos`: the DISTINCT owning repos of the envelope's evidence (via `distinctRepos`), unioned
+ *   with the record's repos by identity; the newest envelope's revision wins for a repo already
+ *   present. Multi-repo context is preserved: every owning repo stays its own entry.
+ * - `evidenceRefs`: the evidence PATHS unioned with the record's, deduped. The record stays a
+ *   COMPACT resume summary — the full envelope (with content hashes) lives on disk and is
+ *   re-checked on demand via `context check`, not duplicated here.
+ *
+ * Refuses to create a record: context evidence belongs to an active durable task (task-state
+ * emission Rule 1). `now` is passed in — the pure core never reads the clock.
+ */
+export async function recordContextEvidence(projectRoot, taskId, envelope, now) {
+    return updateTaskRecord(projectRoot, taskId, (existing) => {
+        if (!existing)
+            throw new Error(`no active task record "${taskId}" — context evidence is recorded only for an existing durable task`);
+        // Union owning repos by identity (newest revision wins for a repo already recorded).
+        const revByIdentity = new Map(existing.repos.map((r) => [r.identity, r.revision]));
+        for (const r of distinctRepos(envelope.evidence))
+            revByIdentity.set(r.identity, r.revision);
+        const repos = [...revByIdentity]
+            .map(([identity, revision]) => ({ identity, revision }))
+            .sort((a, b) => (a.identity < b.identity ? -1 : a.identity > b.identity ? 1 : 0));
+        // Union evidence paths (compact resume summary — never the hashes).
+        const paths = new Set(existing.evidenceRefs);
+        for (const e of envelope.evidence)
+            paths.add(e.path);
+        return { ...existing, repos, evidenceRefs: [...paths].sort(), updatedAt: now };
+    });
+}
+/** List all active-dir task ids (record filenames), for resume reconstruction. */
+export function listTaskRecordIds(projectRoot) {
+    const dir = activeDir(projectRoot);
+    if (!existsSync(dir))
+        return [];
+    return readdirSync(dir)
+        .filter((f) => f.endsWith(".json"))
+        .map((f) => f.replace(/\.json$/, ""))
+        .filter((id) => TASK_ID_RE.test(id))
+        .sort();
+}
+export function reconstructResumeState(projectRoot) {
+    const records = [];
+    const issues = [];
+    // Listing itself is guarded so a dir-removal race can't crash the whole reconstruction.
+    let ids = [];
+    try {
+        ids = listTaskRecordIds(projectRoot);
+    }
+    catch (err) {
+        issues.push({ taskId: "(listing)", problem: err.message });
+    }
+    for (const id of ids) {
+        try {
+            const r = readTaskRecord(projectRoot, id);
+            if (r)
+                records.push(r);
+        }
+        catch (err) {
+            issues.push({ taskId: id, problem: err.message });
+        }
+    }
+    return { records, issues, activePlanPointer: readActivePlanPointer(projectRoot) };
+}
+//# sourceMappingURL=task-record.js.map

package/dist/core/task-record.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"task-record.js","sourceRoot":"","sources":["../../src/core/task-record.ts"],"names":[],"mappings":"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"}

package/dist/core/validate-capabilities.d.ts

@@ -0,0 +1,12 @@
+import { type InventoryEntry } from "./build-inventory.js";
+import { type CapabilityEntry } from "./capability.js";
+export interface CapabilityIssue {
+    level: "error" | "warn";
+    capabilityId: string | null;
+    message: string;
+}
+/** Validate the manifest built from `claudeDir`. Returns all issues (empty ⇒ clean). */
+export declare function validateCapabilities(claudeDir: string): CapabilityIssue[];
+/** Pure validation over a built manifest + inventory. Injectable for testing. */
+export declare function validateCapabilityEntries(entries: CapabilityEntry[], inventoryEntries: InventoryEntry[]): CapabilityIssue[];
+//# sourceMappingURL=validate-capabilities.d.ts.map

package/dist/core/validate-capabilities.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate-capabilities.d.ts","sourceRoot":"","sources":["../../src/core/validate-capabilities.ts"],"names":[],"mappings":"AAMA,OAAO,EAAkB,KAAK,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAE3E,OAAO,EAAwB,KAAK,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAE7E,MAAM,WAAW,eAAe;IAC/B,KAAK,EAAE,OAAO,GAAG,MAAM,CAAC;IACxB,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,OAAO,EAAE,MAAM,CAAC;CAChB;AAoCD,wFAAwF;AACxF,wBAAgB,oBAAoB,CAAC,SAAS,EAAE,MAAM,GAAG,eAAe,EAAE,CAEzE;AAED,iFAAiF;AACjF,wBAAgB,yBAAyB,CAAC,OAAO,EAAE,eAAe,EAAE,EAAE,gBAAgB,EAAE,cAAc,EAAE,GAAG,eAAe,EAAE,CA+F3H"}

package/dist/core/validate-capabilities.js

@@ -0,0 +1,138 @@
+// Validate a capability manifest against the design invariants (Phase 2 §1/§5). Pure over
+// the built manifest + inventory, so it is testable without a live install. Severity:
+// ERROR = a broken contract (cross-ref, containment, uniqueness, unknown invocation ID,
+// dependency cycle); WARN = a coverage/authoring smell (uncovered artifact, duplicate
+// intent across capabilities). No check ever executes a script or trusts a command string.
+import { buildCapabilities } from "./build-capabilities.js";
+import { buildInventory } from "./build-inventory.js";
+import { AUTHORED_CONTEXT_REQUIREMENTS, AUTHORED_INTENTS } from "./capability-authored.js";
+import { KNOWN_INVOCATION_IDS } from "./capability.js";
+/** True when `rel` is a `.claude/`-relative path with no escape (no `..`, not absolute). */
+function isContained(rel) {
+    if (rel.startsWith("/") || /^[A-Za-z]:[\\/]/.test(rel))
+        return false;
+    return !rel.split(/[\\/]/).includes("..");
+}
+/** Detect a cycle in the upstream-dependency graph (DFS with a recursion stack). */
+function findCycle(entries) {
+    const upstream = new Map(entries.map((e) => [e.id, e.dependencies.upstream]));
+    const state = new Map();
+    const stack = [];
+    const visit = (id) => {
+        if (state.get(id) === "done")
+            return null;
+        if (state.get(id) === "visiting")
+            return [...stack.slice(stack.indexOf(id)), id];
+        state.set(id, "visiting");
+        stack.push(id);
+        for (const dep of upstream.get(id) ?? []) {
+            if (!upstream.has(dep))
+                continue; // dangling deps are reported by the coverage pass below
+            const cycle = visit(dep);
+            if (cycle)
+                return cycle;
+        }
+        stack.pop();
+        state.set(id, "done");
+        return null;
+    };
+    for (const e of entries) {
+        const cycle = visit(e.id);
+        if (cycle)
+            return cycle;
+    }
+    return null;
+}
+/** Validate the manifest built from `claudeDir`. Returns all issues (empty ⇒ clean). */
+export function validateCapabilities(claudeDir) {
+    return validateCapabilityEntries(buildCapabilities(claudeDir), buildInventory(claudeDir).entries);
+}
+/** Pure validation over a built manifest + inventory. Injectable for testing. */
+export function validateCapabilityEntries(entries, inventoryEntries) {
+    const issues = [];
+    const invById = new Map(inventoryEntries.map((e) => [e.id, e]));
+    const capIds = new Set();
+    const aliasOwners = new Map();
+    const intentOwners = new Map();
+    for (const c of entries) {
+        // id uniqueness
+        if (capIds.has(c.id))
+            issues.push({ level: "error", capabilityId: c.id, message: "duplicate capability id" });
+        capIds.add(c.id);
+        // path containment (disk-backed kinds only)
+        if (c.sourcePath !== null && !isContained(c.sourcePath)) {
+            issues.push({ level: "error", capabilityId: c.id, message: `sourcePath escapes .claude/: ${c.sourcePath}` });
+        }
+        // inventory cross-reference + owner agreement (disk-backed kinds only)
+        if (c.inventoryId !== null && c.sourcePath !== null) {
+            const inv = invById.get(c.inventoryId);
+            if (!inv) {
+                issues.push({ level: "error", capabilityId: c.id, message: `inventoryId has no matching inventory entry: ${c.inventoryId}` });
+            }
+            else if (inv.owner && c.owner && inv.owner !== c.owner) {
+                issues.push({ level: "error", capabilityId: c.id, message: `denormalized owner "${c.owner}" disagrees with inventory "${inv.owner}"` });
+            }
+        }
+        // invocation id must be a known logical id — hostile frontmatter cannot smuggle a command
+        if (!KNOWN_INVOCATION_IDS.has(c.invocation.id)) {
+            issues.push({ level: "error", capabilityId: c.id, message: `unknown invocation id: ${c.invocation.id}` });
+        }
+        // alias uniqueness across entries
+        for (const a of c.aliases) {
+            const prior = aliasOwners.get(a);
+            if (prior && prior !== c.id)
+                issues.push({ level: "error", capabilityId: c.id, message: `alias "${a}" also on ${prior}` });
+            aliasOwners.set(a, c.id);
+        }
+        // intent duplication tracking (WARN — inferred keywords can legitimately overlap)
+        for (const i of c.intents) {
+            intentOwners.set(i, [...(intentOwners.get(i) ?? []), c.id]);
+        }
+    }
+    for (const [intent, owners] of intentOwners) {
+        if (owners.length > 1) {
+            issues.push({ level: "warn", capabilityId: null, message: `intent "${intent}" maps to multiple capabilities: ${owners.join(", ")}` });
+        }
+    }
+    // Dangling upstream dependency: an upstream id with no matching capability (WARN —
+    // a coherence smell, not a hard break, in this pre-resolver slice).
+    for (const c of entries) {
+        for (const dep of c.dependencies.upstream) {
+            if (!capIds.has(dep)) {
+                issues.push({ level: "warn", capabilityId: c.id, message: `upstream dependency has no matching capability: ${dep}` });
+            }
+        }
+    }
+    // coverage: every enumerated invocable-kind artifact should have a capability (WARN)
+    const capInventoryIds = new Set(entries.map((e) => e.inventoryId).filter((x) => x !== null));
+    for (const inv of inventoryEntries) {
+        if (inv.type === "rule")
+            continue; // rules are inventory-only context, not capabilities
+        if (!capInventoryIds.has(inv.id)) {
+            issues.push({ level: "warn", capabilityId: null, message: `inventory artifact has no capability: ${inv.path}` });
+        }
+    }
+    // dependency cycle (ERROR)
+    const cycle = findCycle(entries);
+    if (cycle)
+        issues.push({ level: "error", capabilityId: null, message: `dependency cycle: ${cycle.join(" → ")}` });
+    // Authored-intent overlay key with no matching capability (WARN): expected on a partial
+    // consumer install that omits a flagship skill, but on a full authoring install it means
+    // a dead key (e.g. after a skill rename) silently dropping curated intents. The hard guard
+    // against a rename is the resolver test asserting every authored phrase resolves to its owner.
+    for (const key of Object.keys(AUTHORED_INTENTS)) {
+        if (!capIds.has(key)) {
+            issues.push({ level: "warn", capabilityId: key, message: `AUTHORED_INTENTS key has no matching capability (partial install or renamed skill): ${key}` });
+        }
+    }
+    // Symmetric dead-key guard for the repo-context overlay (Phase 5): an
+    // AUTHORED_CONTEXT_REQUIREMENTS key with no capability is a partial install or a rename that
+    // silently drops the context requirement from a source-grounded flow.
+    for (const key of Object.keys(AUTHORED_CONTEXT_REQUIREMENTS)) {
+        if (!capIds.has(key)) {
+            issues.push({ level: "warn", capabilityId: key, message: `AUTHORED_CONTEXT_REQUIREMENTS key has no matching capability (partial install or renamed skill): ${key}` });
+        }
+    }
+    return issues;
+}
+//# sourceMappingURL=validate-capabilities.js.map

package/dist/core/validate-capabilities.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate-capabilities.js","sourceRoot":"","sources":["../../src/core/validate-capabilities.ts"],"names":[],"mappings":"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"}

package/dist/index.js

@@ -7,6 +7,9 @@ import pc from "picocolors";
 import { init } from "./commands/init.js";
 import { upgrade } from "./commands/upgrade.js";
 import { validate } from "./commands/validate.js";
+import { capabilities } from "./commands/capabilities.js";
+import { taskState } from "./commands/task-state.js";
+import { context } from "./commands/context.js";
 import { budget, contextBudget } from "./commands/budget.js";
 import { memory } from "./commands/memory.js";
 import { verdictGate } from "./commands/verdict-gate.js";
@@ -35,15 +38,18 @@ ${pc.bold("Usage:")}
 ${pc.bold("Commands:")}
   ${pc.green("init")}       Scaffold or update MeowKit in the current project
   ${pc.green("upgrade")}    Upgrade MeowKit to the latest version
-  ${pc.green("validate")}   Validate .claude/ project structure
+  ${pc.green("validate")}   Validate .claude/ project structure (--mode authoring|flat-copy; auto-detected)
+  ${pc.green("capabilities")} Inspect/resolve the capability manifest ('capabilities list|explain <id>|resolve --intent "…"|view|bootstrap|projections' [--json])
   ${pc.green("budget")}     View token usage and cost log ('budget context' for per-profile size)
   ${pc.green("memory")}     Manage agent memory (lessons & patterns)
   ${pc.green("setup")}      Guided post-scaffold configuration
-  ${pc.green("doctor")}     Diagnose common environment issues
+  ${pc.green("doctor")}     Diagnose common environment issues ('doctor provenance --explain' for a read-only provenance report)
   ${pc.green("status")}     Print version and config summary
+  ${pc.green("task-state")} Durable task record ('task-state show [--json]' | 'task-state update <id> --status --step --next --plan')
+  ${pc.green("context")}    Repo-context evidence ('context resolve <path> [--root]' | 'context check <envelope.json>' | 'context record --task <id> <envelope.json>')
   ${pc.green("task")}       Create and list task files (new, list)
   ${pc.green("migrate")}    Export MeowKit to external coding-agent tools (cursor, codex, ...)
-  ${pc.green("providers")}  Show effective provider support matrix and enforcement levels
+  ${pc.green("providers")}  Show effective provider support matrix and enforcement levels ('providers [<p>] --lifecycle' for the capability-adapter + lifecycle matrix)
   ${pc.green("orchviz")}    Live web visualizer for the active Claude Code session
   ${pc.green("inventory")}  List harness artifacts with governance metadata
   ${pc.green("trace")}      On-demand trace recall: score | audit | propose | --friction
@@ -60,6 +66,7 @@ ${pc.bold("Options:")}
   --providers      Doctor/migrate: include provider contract diagnostics
   --state          Doctor: include state taxonomy diagnostics
   --hard-gates     Doctor: live-probe the hard gates (plan/privacy/injection block)
+  --consolidation  Doctor: show the Phase-7 consolidation/deprecation ledger (status ≠ runtime availability)
   --portable       Validate: include portable provider contract checks
   --strict         Validate: treat WARN as failure (exit 1); off by default
   --workflow       Validate: run only the workflow.yaml drift-check (CI scope)
@@ -135,6 +142,7 @@ async function main() {
             "providers",
             "state",
             "hard-gates",
+            "consolidation",
             "portable",
             "all",
             "dry-run",
@@ -168,10 +176,20 @@ async function main() {
             "packs",
             "rules",
             "substrate",
+            "capabilities",
             "emit",
             "commit",
+            "explain",
+            "write",
         ],
         string: [
+            "mode",
+            "intent",
+            "provider",
+            "step",
+            "next",
+            "plan",
+            "root",
             "only",
             "type",
             "priority",
@@ -222,8 +240,14 @@ async function main() {
                 yes: args.yes,
             });
             break;
-        case "validate":
+        case "validate": {
+            const modeArg = args.mode;
+            if (modeArg !== undefined && modeArg !== "authoring" && modeArg !== "flat-copy") {
+                console.error(`Invalid --mode "${modeArg}". Expected "authoring" or "flat-copy".`);
+                process.exit(1);
+            }
             await validate({
+                mode: modeArg,
                 portable: args.portable,
                 strict: args.strict,
                 workflow: args.workflow,
@@ -232,13 +256,25 @@ async function main() {
                 packs: args.packs,
                 rules: args.rules,
                 plugin: args.plugin,
+                capabilities: args.capabilities,
             });
             break;
+        }
         case "build-plugin":
             await buildPlugin({
                 json: args.json,
             });
             break;
+        case "capabilities":
+            await capabilities({
+                subcommand: args._[1],
+                target: args._[2],
+                json: args.json,
+                intent: args.intent,
+                provider: args.provider,
+                write: args.write,
+            });
+            break;
         case "pack":
             await pack({
                 subcommand: args._[1],
@@ -253,6 +289,7 @@ async function main() {
             await providersCommand({
                 provider: args._[1],
                 json: args.json,
+                lifecycle: args.lifecycle,
             });
             break;
         case "inventory":
@@ -344,11 +381,36 @@ async function main() {
                 providers: args.providers,
                 state: args.state,
                 hardGates: args["hard-gates"],
+                // `doctor provenance [--explain]`: read-only provenance report.
+                provenance: args._[1] === "provenance" || undefined,
+                explain: args.explain,
+                consolidation: args.consolidation,
             });
             break;
         case "status":
             await printStatus();
             break;
+        case "task-state":
+            await taskState({
+                subcommand: args._[1],
+                taskId: args._[2],
+                status: args.status,
+                step: args.step,
+                next: args.next,
+                plan: args.plan,
+                json: args.json,
+                cliVersion: VERSION,
+            });
+            break;
+        case "context":
+            await context({
+                subcommand: args._[1],
+                target: args._[2],
+                root: args.root,
+                task: args.task,
+                json: args.json,
+            });
+            break;
         case "task": {
             const subcommand = args._[1];
             // positional description: everything after the subcommand that isn't a flag