@adammcarter/use-cases 0.1.0

package/packages/cli/dist/commands/capsule.js

@@ -0,0 +1,178 @@
+import { createCliResult, errorEnvelope, loadDemoCapsules, planDemoCapsule, resolveContextOrError, runDemoCapsule } from "../runtime.js";
+import { workspaceFlags } from "./common.js";
+const capsuleFlag = {
+    key: "capsule",
+    name: "--capsule",
+    kind: "string",
+    required: true,
+    valueName: "<id>",
+    summary: "Capsule id."
+};
+// Non-writing port of the legacy writeCapsuleRunResult: build the envelope + exit
+// code instead of writing. ok unless blocked; a blocked run maps to exit 4 when a
+// command cwd-escape diagnostic is present, otherwise 1; an ok run maps to exit 1
+// when any command did not match its expected exit code, otherwise 0.
+function capsuleRunOutput(result, context) {
+    const ok = result.outcome !== "blocked";
+    const envelope = createCliResult("capsule.run", result, {
+        ok,
+        complete: result.complete,
+        diagnostics: result.diagnostics,
+        workspaceRoot: context.workspace_root,
+        dataRoot: context.data_root,
+        componentId: context.component_id
+    });
+    if (!ok) {
+        const cwdEscape = result.diagnostics.some((item) => item.code === "capsule.command_cwd_escape");
+        return { envelope, exitCode: cwdEscape ? 4 : 1 };
+    }
+    const exitCode = result.command_results.some((item) => !item.matched_expected_exit_code) ? 1 : 0;
+    return { envelope, exitCode };
+}
+export const capsuleListCommand = {
+    path: ["capsule", "list"],
+    command: "capsule.list",
+    summary: "List demo capsules.",
+    flags: workspaceFlags,
+    handler: ({ argv }) => {
+        const context = resolveContextOrError(argv, "capsule.list");
+        if (context.kind === "error") {
+            return { envelope: context.envelope, exitCode: context.exitCode };
+        }
+        const snapshot = loadDemoCapsules({ context: context.context });
+        const data = {
+            schema_version: 1,
+            complete: snapshot.complete,
+            capsules: snapshot.capsules.map((entry) => ({
+                capsule_id: entry.capsule.capsule_id,
+                title: entry.capsule.title,
+                mode: entry.capsule.mode,
+                audience: entry.capsule.audience,
+                timebox_seconds: entry.capsule.timebox_seconds,
+                item_count: entry.capsule.items.length,
+                path: entry.path,
+                semantic_hash: entry.semantic_hash
+            }))
+        };
+        return {
+            envelope: createCliResult("capsule.list", data, {
+                ok: true,
+                complete: snapshot.complete,
+                diagnostics: snapshot.diagnostics,
+                workspaceRoot: context.context.workspace_root,
+                dataRoot: context.context.data_root,
+                componentId: context.context.component_id
+            }),
+            exitCode: 0
+        };
+    }
+};
+export const capsuleValidateCommand = {
+    path: ["capsule", "validate"],
+    command: "capsule.validate",
+    summary: "Validate demo capsules.",
+    flags: workspaceFlags,
+    handler: ({ argv }) => {
+        const context = resolveContextOrError(argv, "capsule.validate");
+        if (context.kind === "error") {
+            return { envelope: context.envelope, exitCode: context.exitCode };
+        }
+        const snapshot = loadDemoCapsules({ context: context.context });
+        return {
+            envelope: createCliResult("capsule.validate", snapshot, {
+                ok: snapshot.complete,
+                complete: snapshot.complete,
+                diagnostics: snapshot.diagnostics,
+                workspaceRoot: context.context.workspace_root,
+                dataRoot: context.context.data_root,
+                componentId: context.context.component_id
+            }),
+            exitCode: snapshot.complete ? 0 : 1
+        };
+    }
+};
+export const capsulePlanCommand = {
+    path: ["capsule", "plan"],
+    command: "capsule.plan",
+    summary: "Plan a demo capsule.",
+    flags: [...workspaceFlags, capsuleFlag],
+    handler: ({ argv, flags }) => {
+        const context = resolveContextOrError(argv, "capsule.plan");
+        if (context.kind === "error") {
+            return { envelope: context.envelope, exitCode: context.exitCode };
+        }
+        const capsuleId = flags.capsule;
+        if (!capsuleId) {
+            return {
+                envelope: errorEnvelope("capsule.plan", "cli_invalid_arguments", "Missing --capsule."),
+                exitCode: 2
+            };
+        }
+        const result = planDemoCapsule({ context: context.context, capsuleId });
+        const ok = result.outcome === "generated";
+        return {
+            envelope: createCliResult("capsule.plan", result, {
+                ok,
+                complete: result.outcome === "generated" && (result.plan_result?.plan?.complete ?? false),
+                diagnostics: result.diagnostics,
+                workspaceRoot: context.context.workspace_root,
+                dataRoot: context.context.data_root,
+                componentId: context.context.component_id
+            }),
+            exitCode: result.outcome === "generated" ? 0 : result.outcome === "integrity_blocked" ? 3 : 1
+        };
+    }
+};
+export const capsuleRunCommand = {
+    path: ["capsule", "run"],
+    command: "capsule.run",
+    summary: "Run a demo capsule.",
+    flags: [
+        ...workspaceFlags,
+        capsuleFlag,
+        { key: "executeCommands", name: "--execute-commands", kind: "boolean", summary: "Actually execute the capsule commands." },
+        { key: "idempotencyKey", name: "--idempotency-key", kind: "string", valueName: "<key>", summary: "Idempotency key for the run record." },
+        { key: "recordedAt", name: "--recorded-at", kind: "string", valueName: "<timestamp>", summary: "Override the recorded-at timestamp." },
+        { key: "commandTimeoutMs", name: "--command-timeout-ms", kind: "integer", valueName: "<ms>", summary: "Per-command execution timeout in milliseconds." }
+    ],
+    handler: ({ argv, flags }) => {
+        const context = resolveContextOrError(argv, "capsule.run");
+        if (context.kind === "error") {
+            return { envelope: context.envelope, exitCode: context.exitCode };
+        }
+        const capsuleId = flags.capsule;
+        if (!capsuleId) {
+            return {
+                envelope: errorEnvelope("capsule.run", "cli_invalid_arguments", "Missing --capsule."),
+                exitCode: 2
+            };
+        }
+        try {
+            const result = runDemoCapsule({
+                context: context.context,
+                capsuleId,
+                executeCommands: flags.executeCommands,
+                actorType: "agent",
+                hostSurface: "codex.cli",
+                idempotencyKey: flags.idempotencyKey ?? undefined,
+                recordedAt: flags.recordedAt ?? undefined,
+                commandTimeoutMs: flags.commandTimeoutMs ?? undefined
+            });
+            return capsuleRunOutput(result, context.context);
+        }
+        catch (error) {
+            const code = error instanceof Error && "code" in error ? String(error.code) : "internal_error";
+            return {
+                envelope: errorEnvelope("capsule.run", code, error instanceof Error ? error.message : String(error)),
+                exitCode: 1
+            };
+        }
+    }
+};
+export const capsuleCommands = [
+    capsuleListCommand,
+    capsuleValidateCommand,
+    capsulePlanCommand,
+    capsuleRunCommand
+];
+//# sourceMappingURL=capsule.js.map

package/packages/cli/dist/commands/capsule.js.map

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

package/packages/cli/dist/commands/common.d.ts

@@ -0,0 +1,7 @@
+import type { FlagSpec } from "../command/types.js";
+export declare const repoFlag: FlagSpec;
+export declare const dataRootFlag: FlagSpec;
+export declare const componentFlag: FlagSpec;
+export declare const jsonFlag: FlagSpec;
+export declare const workspaceFlags: readonly FlagSpec[];
+//# sourceMappingURL=common.d.ts.map

package/packages/cli/dist/commands/common.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"common.d.ts","sourceRoot":"","sources":["../../src/commands/common.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,qBAAqB,CAAC;AAIpD,eAAO,MAAM,QAAQ,EAAE,QAMtB,CAAC;AAEF,eAAO,MAAM,YAAY,EAAE,QAM1B,CAAC;AAEF,eAAO,MAAM,aAAa,EAAE,QAM3B,CAAC;AAEF,eAAO,MAAM,QAAQ,EAAE,QAKtB,CAAC;AAGF,eAAO,MAAM,cAAc,EAAE,SAAS,QAAQ,EAAsD,CAAC"}

package/packages/cli/dist/commands/common.js

@@ -0,0 +1,32 @@
+// Flags shared across most commands, defined once so help and parsing never
+// drift between groups. Summaries match the legacy USAGE table verbatim.
+export const repoFlag = {
+    key: "repo",
+    name: "--repo",
+    kind: "string",
+    valueName: "<path>",
+    summary: "Workspace root (defaults to the current directory)."
+};
+export const dataRootFlag = {
+    key: "dataRoot",
+    name: "--data-root",
+    kind: "string",
+    valueName: "<path>",
+    summary: "Override the data root (must stay inside --repo)."
+};
+export const componentFlag = {
+    key: "component",
+    name: "--component",
+    kind: "string",
+    valueName: "<id>",
+    summary: "Select a component within the workspace."
+};
+export const jsonFlag = {
+    key: "json",
+    name: "--json",
+    kind: "boolean",
+    summary: "Emit the machine-readable JSON result envelope (default output is human-readable)."
+};
+// The workspace-context trio + --json, the COMMON_FLAGS of the legacy USAGE table.
+export const workspaceFlags = [repoFlag, dataRootFlag, componentFlag, jsonFlag];
+//# sourceMappingURL=common.js.map

package/packages/cli/dist/commands/common.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"common.js","sourceRoot":"","sources":["../../src/commands/common.ts"],"names":[],"mappings":"AAEA,4EAA4E;AAC5E,yEAAyE;AACzE,MAAM,CAAC,MAAM,QAAQ,GAAa;IAChC,GAAG,EAAE,MAAM;IACX,IAAI,EAAE,QAAQ;IACd,IAAI,EAAE,QAAQ;IACd,SAAS,EAAE,QAAQ;IACnB,OAAO,EAAE,qDAAqD;CAC/D,CAAC;AAEF,MAAM,CAAC,MAAM,YAAY,GAAa;IACpC,GAAG,EAAE,UAAU;IACf,IAAI,EAAE,aAAa;IACnB,IAAI,EAAE,QAAQ;IACd,SAAS,EAAE,QAAQ;IACnB,OAAO,EAAE,mDAAmD;CAC7D,CAAC;AAEF,MAAM,CAAC,MAAM,aAAa,GAAa;IACrC,GAAG,EAAE,WAAW;IAChB,IAAI,EAAE,aAAa;IACnB,IAAI,EAAE,QAAQ;IACd,SAAS,EAAE,MAAM;IACjB,OAAO,EAAE,0CAA0C;CACpD,CAAC;AAEF,MAAM,CAAC,MAAM,QAAQ,GAAa;IAChC,GAAG,EAAE,MAAM;IACX,IAAI,EAAE,QAAQ;IACd,IAAI,EAAE,SAAS;IACf,OAAO,EAAE,oFAAoF;CAC9F,CAAC;AAEF,mFAAmF;AACnF,MAAM,CAAC,MAAM,cAAc,GAAwB,CAAC,QAAQ,EAAE,YAAY,EAAE,aAAa,EAAE,QAAQ,CAAC,CAAC"}

package/packages/cli/dist/commands/doctor.d.ts

@@ -0,0 +1,6 @@
+import type { CliCommand } from "../command/types.js";
+export declare const doctorSkillsCommand: CliCommand;
+export declare const doctorPackageCommand: CliCommand;
+export declare const doctorRootsCommand: CliCommand;
+export declare const doctorCommands: CliCommand[];
+//# sourceMappingURL=doctor.d.ts.map

package/packages/cli/dist/commands/doctor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"doctor.d.ts","sourceRoot":"","sources":["../../src/commands/doctor.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAC;AAsBtD,eAAO,MAAM,mBAAmB,EAAE,UAwBjC,CAAC;AAEF,eAAO,MAAM,oBAAoB,EAAE,UAsDlC,CAAC;AAEF,eAAO,MAAM,kBAAkB,EAAE,UA6BhC,CAAC;AAEF,eAAO,MAAM,cAAc,EAAE,UAAU,EAItC,CAAC"}

package/packages/cli/dist/commands/doctor.js

@@ -0,0 +1,133 @@
+import { accessSync, constants } from "node:fs";
+import { resolve } from "node:path";
+import { valueAfter } from "../args/parse.js";
+import { createCliResult, errorEnvelope, inspectPackageArtifact, resolveContextOrError, validateSkillAssets } from "../runtime.js";
+import { workspaceFlags } from "./common.js";
+// Local port of the legacy `canWrite`: probe a directory for write access without
+// mutating it, swallowing the EACCES/ENOENT throw into a boolean.
+function canWrite(path) {
+    try {
+        accessSync(path, constants.W_OK);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export const doctorSkillsCommand = {
+    path: ["doctor", "skills"],
+    command: "doctor.skills",
+    summary: "Validate packaged skill assets (maintainer-only; expects a plugin checkout).",
+    hidden: true,
+    flags: workspaceFlags,
+    handler: ({ argv }) => {
+        const context = resolveContextOrError(argv, "doctor.skills");
+        if (context.kind === "error") {
+            return { envelope: context.envelope, exitCode: context.exitCode };
+        }
+        const result = validateSkillAssets({ context: context.context });
+        return {
+            envelope: createCliResult("doctor.skills", result, {
+                ok: result.complete,
+                complete: result.complete,
+                diagnostics: result.diagnostics,
+                workspaceRoot: context.context.workspace_root,
+                dataRoot: context.context.data_root,
+                componentId: context.context.component_id
+            }),
+            exitCode: result.complete ? 0 : 1
+        };
+    }
+};
+export const doctorPackageCommand = {
+    path: ["doctor", "package"],
+    command: "doctor.package",
+    summary: "Inspect the packaged plugin artifact (maintainer-only; builds via pnpm).",
+    hidden: true,
+    flags: [
+        ...workspaceFlags,
+        { key: "tarball", name: "--tarball", kind: "string", valueName: "<path>", summary: "Inspect a packed tarball instead of the workspace." },
+        { key: "installedRoot", name: "--installed-root", kind: "string", valueName: "<path>", summary: "Inspect an installed plugin root instead of the workspace." }
+    ],
+    handler: ({ argv }) => {
+        const context = resolveContextOrError(argv, "doctor.package");
+        if (context.kind === "error") {
+            return { envelope: context.envelope, exitCode: context.exitCode };
+        }
+        const tarball = valueAfter(argv, "--tarball");
+        const installedRoot = valueAfter(argv, "--installed-root");
+        if (tarball && installedRoot) {
+            return {
+                envelope: errorEnvelope("doctor.package", "package.target_conflict", "Use only one of --tarball or --installed-root."),
+                exitCode: 2
+            };
+        }
+        try {
+            const data = inspectPackageArtifact({
+                target: tarball
+                    ? { kind: "tarball", path: resolve(process.cwd(), tarball) }
+                    : installedRoot
+                        ? { kind: "installed_root", path: resolve(process.cwd(), installedRoot) }
+                        : { kind: "workspace", path: context.context.workspace_root, build: true }
+            });
+            const envelope = createCliResult("doctor.package", data, {
+                ok: data.complete,
+                complete: data.complete,
+                diagnostics: data.diagnostics,
+                workspaceRoot: context.context.workspace_root,
+                dataRoot: context.context.data_root,
+                componentId: context.context.component_id
+            });
+            // Derive the exit code from the FINAL envelope's `ok`, not `data.complete`.
+            // createCliResult forces ok:false when an error-severity diagnostic is present
+            // even if data.complete is true — so keying off data.complete could ship an
+            // ok:false envelope with exit 0 (a false green). ok is the exit-code contract.
+            return {
+                envelope,
+                exitCode: envelope.ok ? 0 : 1
+            };
+        }
+        catch (error) {
+            return {
+                envelope: errorEnvelope("doctor.package", "package.inspection_failed", error instanceof Error ? error.message : String(error)),
+                exitCode: 2
+            };
+        }
+    }
+};
+export const doctorRootsCommand = {
+    path: ["doctor", "roots"],
+    command: "doctor.roots",
+    summary: "Report the resolved workspace and data roots.",
+    flags: workspaceFlags,
+    handler: ({ argv }) => {
+        const context = resolveContextOrError(argv, "doctor.roots");
+        if (context.kind === "error") {
+            return { envelope: context.envelope, exitCode: context.exitCode };
+        }
+        const writable = canWrite(context.context.data_root);
+        return {
+            envelope: createCliResult("doctor.roots", {
+                schema_version: 1,
+                workspace_root: context.context.workspace_root,
+                data_root: context.context.data_root,
+                use_cases_root: context.context.use_cases_root,
+                component_id: context.context.component_id,
+                config_path: context.context.config_path,
+                provenance: context.context.provenance,
+                writable
+            }, {
+                workspaceRoot: context.context.workspace_root,
+                dataRoot: context.context.data_root,
+                componentId: context.context.component_id
+            }),
+            exitCode: 0
+        };
+    }
+};
+export const doctorCommands = [
+    doctorSkillsCommand,
+    doctorPackageCommand,
+    doctorRootsCommand
+];
+//# sourceMappingURL=doctor.js.map

package/packages/cli/dist/commands/doctor.js.map

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

package/packages/cli/dist/commands/evidence.d.ts

@@ -0,0 +1,6 @@
+import type { CliCommand } from "../command/types.js";
+export declare const evidenceRecordCommand: CliCommand;
+export declare const evidenceStatusCommand: CliCommand;
+export declare const evidenceVoidCommand: CliCommand;
+export declare const evidenceCommands: CliCommand[];
+//# sourceMappingURL=evidence.d.ts.map

package/packages/cli/dist/commands/evidence.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"evidence.d.ts","sourceRoot":"","sources":["../../src/commands/evidence.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAC;AAgCtD,eAAO,MAAM,qBAAqB,EAAE,UA+EnC,CAAC;AAEF,eAAO,MAAM,qBAAqB,EAAE,UAuBnC,CAAC;AAEF,eAAO,MAAM,mBAAmB,EAAE,UAkEjC,CAAC;AAEF,eAAO,MAAM,gBAAgB,EAAE,UAAU,EAIxC,CAAC"}

package/packages/cli/dist/commands/evidence.js

@@ -0,0 +1,191 @@
+import { appendEvidenceEvent, appendEvidenceVoidEvent, createCliResult, errorEnvelope, isValidId, loadUseCaseMatrix, replayEvidence, resolveContextOrError, toEvidenceAppendResult, toEvidenceStatusResult } from "../runtime.js";
+import { workspaceFlags } from "./common.js";
+// Human-readable note for each derived assurance class. Ported verbatim from the
+// legacy `assuranceClassMessage` so the evidence.record info diagnostic stays
+// byte-identical.
+function assuranceClassMessage(assuranceClass) {
+    const note = assuranceClass === "reported"
+        ? " (self-reported — the weakest assurance tier)"
+        : assuranceClass === "observed"
+            ? " (observed — stronger than self-reported)"
+            : assuranceClass === "reproducible"
+                ? " (reproducible via a structured command — the strongest tier)"
+                : assuranceClass === "reference"
+                    ? " (reference link)"
+                    : "";
+    return `Evidence assurance class: ${assuranceClass}${note}.`;
+}
+export const evidenceRecordCommand = {
+    path: ["evidence", "record"],
+    command: "evidence.record",
+    summary: "Record an evidence event for a use case.",
+    flags: [
+        ...workspaceFlags,
+        { key: "useCase", name: "--use-case", kind: "string", required: true, valueName: "<id>", summary: "Use-case id to attach evidence to." },
+        { key: "kind", name: "--kind", kind: "string", valueName: "<kind>", summary: "Evidence kind (defaults to manual_observation)." },
+        { key: "result", name: "--result", kind: "string", valueName: "<result>", summary: "Evidence result (defaults to observed)." },
+        { key: "summary", name: "--summary", kind: "string", valueName: "<text>", summary: "Human summary of the evidence." },
+        { key: "idempotencyKey", name: "--idempotency-key", kind: "string", valueName: "<key>", summary: "Idempotency key (defaults to a derived cli: key)." }
+    ],
+    handler: ({ argv, flags }) => {
+        const context = resolveContextOrError(argv, "evidence.record");
+        if (context.kind === "error") {
+            return { envelope: context.envelope, exitCode: context.exitCode };
+        }
+        const useCaseId = flags.useCase;
+        if (!useCaseId) {
+            return {
+                envelope: errorEnvelope("evidence.record", "evidence.use_case.required", "Missing --use-case."),
+                exitCode: 2
+            };
+        }
+        const matrix = loadUseCaseMatrix({ context: context.context });
+        const resolved = matrix.resolveUseCase(useCaseId);
+        if (resolved.kind !== "resolved") {
+            return {
+                envelope: errorEnvelope("evidence.record", "evidence.use_case.unresolved", `Use case '${useCaseId}' is ${resolved.kind}.`),
+                exitCode: 2
+            };
+        }
+        const kind = flags.kind ?? "manual_observation";
+        const result = flags.result ?? "observed";
+        const append = appendEvidenceEvent({
+            context: context.context,
+            idempotencyKey: flags.idempotencyKey ?? `cli:${useCaseId}:${kind}:${result}`,
+            target: {
+                use_case_id: useCaseId,
+                use_case_semantic_hash: resolved.useCase.semanticHash
+            },
+            kind: kind,
+            result: result,
+            summary: flags.summary ?? `Recorded ${kind} evidence for ${useCaseId}.`,
+            actorType: "agent",
+            hostSurface: "codex.cli"
+        });
+        // Surface the derived assurance class so the agent immediately sees how strong
+        // the evidence is (e.g. a self-reported "pass" is the weakest tier). The
+        // append-result data shape is schema-locked, so this rides as an info
+        // diagnostic rather than an extra data field.
+        const snapshot = replayEvidence({ context: context.context });
+        const aggregate = snapshot.aggregates.find((item) => item.evidenceId === append.event.aggregate_id);
+        const assuranceClass = aggregate?.assurance?.class;
+        const diagnostics = assuranceClass
+            ? [
+                {
+                    code: "evidence.assurance_class",
+                    severity: "info",
+                    message: assuranceClassMessage(assuranceClass),
+                    source_path: null,
+                    json_pointer: null,
+                    entity_id: null,
+                    related_ids: []
+                }
+            ]
+            : [];
+        return {
+            envelope: createCliResult("evidence.record", toEvidenceAppendResult(append), {
+                ok: true,
+                complete: true,
+                diagnostics,
+                workspaceRoot: context.context.workspace_root,
+                dataRoot: context.context.data_root,
+                componentId: context.context.component_id
+            }),
+            exitCode: 0
+        };
+    }
+};
+export const evidenceStatusCommand = {
+    path: ["evidence", "status"],
+    command: "evidence.status",
+    summary: "Replay and report evidence-ledger completeness.",
+    flags: workspaceFlags,
+    handler: ({ argv }) => {
+        const context = resolveContextOrError(argv, "evidence.status");
+        if (context.kind === "error") {
+            return { envelope: context.envelope, exitCode: context.exitCode };
+        }
+        const snapshot = replayEvidence({ context: context.context });
+        return {
+            envelope: createCliResult("evidence.status", toEvidenceStatusResult(snapshot), {
+                ok: snapshot.complete,
+                complete: snapshot.complete,
+                diagnostics: snapshot.diagnostics,
+                workspaceRoot: context.context.workspace_root,
+                dataRoot: context.context.data_root,
+                componentId: context.context.component_id
+            }),
+            exitCode: snapshot.complete ? 0 : 1
+        };
+    }
+};
+export const evidenceVoidCommand = {
+    path: ["evidence", "void"],
+    command: "evidence.void",
+    summary: "Void an evidence aggregate at its expected head.",
+    flags: [
+        ...workspaceFlags,
+        { key: "evidence", name: "--evidence", kind: "string", required: true, valueName: "<id>", summary: "Evidence aggregate id to void." },
+        { key: "expectedHead", name: "--expected-head", kind: "string", required: true, valueName: "<event-id>", summary: "Optimistic-concurrency guard (current head event id)." },
+        { key: "reason", name: "--reason", kind: "string", required: true, valueName: "<text>", summary: "Why the evidence is being voided." },
+        { key: "idempotencyKey", name: "--idempotency-key", kind: "string", valueName: "<key>", summary: "Idempotency key (defaults to a derived cli:void: key)." }
+    ],
+    handler: ({ argv, flags }) => {
+        const context = resolveContextOrError(argv, "evidence.void");
+        if (context.kind === "error") {
+            return { envelope: context.envelope, exitCode: context.exitCode };
+        }
+        const evidenceId = flags.evidence;
+        const expectedHead = flags.expectedHead;
+        const reason = flags.reason;
+        if (!evidenceId || !expectedHead || !reason) {
+            return {
+                envelope: errorEnvelope("evidence.void", "cli_invalid_arguments", "Missing --evidence, --expected-head, or --reason."),
+                exitCode: 2
+            };
+        }
+        // SECURITY: reject a user-supplied id that is not a canonical id BEFORE it can
+        // become a ledger lookup key. Mirrors the legacy rejectUnsafeId/invalidIdExit.
+        if (!isValidId(evidenceId)) {
+            return {
+                envelope: errorEnvelope("evidence.void", "UCM_INVALID_ID", `Invalid --evidence '${evidenceId}': must be a canonical id (lowercase, no path separators, no '..').`),
+                exitCode: 2
+            };
+        }
+        try {
+            const append = appendEvidenceVoidEvent({
+                context: context.context,
+                evidenceId,
+                expectedHeadEventId: expectedHead,
+                reason,
+                idempotencyKey: flags.idempotencyKey ?? `cli:void:${evidenceId}:${expectedHead}`,
+                actorType: "agent",
+                hostSurface: "codex.cli"
+            });
+            return {
+                envelope: createCliResult("evidence.void", toEvidenceAppendResult(append), {
+                    ok: true,
+                    complete: true,
+                    workspaceRoot: context.context.workspace_root,
+                    dataRoot: context.context.data_root,
+                    componentId: context.context.component_id
+                }),
+                exitCode: 0
+            };
+        }
+        catch (error) {
+            const code = error instanceof Error && "code" in error ? String(error.code) : "internal_error";
+            const exitCode = code === "evidence_expected_head_mismatch" ? 1 : code === "evidence_ledger_damaged" ? 3 : 6;
+            return {
+                envelope: errorEnvelope("evidence.void", code, error instanceof Error ? error.message : String(error)),
+                exitCode
+            };
+        }
+    }
+};
+export const evidenceCommands = [
+    evidenceRecordCommand,
+    evidenceStatusCommand,
+    evidenceVoidCommand
+];
+//# sourceMappingURL=evidence.js.map

package/packages/cli/dist/commands/evidence.js.map

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

package/packages/cli/dist/commands/host.d.ts

@@ -0,0 +1,6 @@
+import type { CliCommand } from "../command/types.js";
+export declare const hostDoctorCommand: CliCommand;
+export declare const hostProjectCommand: CliCommand;
+export declare const hostConformanceCommand: CliCommand;
+export declare const hostCommands: CliCommand[];
+//# sourceMappingURL=host.d.ts.map

package/packages/cli/dist/commands/host.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"host.d.ts","sourceRoot":"","sources":["../../src/commands/host.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAiB,MAAM,qBAAqB,CAAC;AAoDrE,eAAO,MAAM,iBAAiB,EAAE,UA6B/B,CAAC;AAEF,eAAO,MAAM,kBAAkB,EAAE,UA6ChC,CAAC;AAEF,eAAO,MAAM,sBAAsB,EAAE,UAkCpC,CAAC;AAkDF,eAAO,MAAM,YAAY,EAAE,UAAU,EAAoE,CAAC"}