@iowarp/clio-coder 0.4.0 → 0.4.2

package/dist/doctor-QOA5FNY5.js

@@ -1,313 +0,0 @@
-import { createRequire as __clioCreateRequire } from "node:module"; const require = __clioCreateRequire(import.meta.url);
-import {
-  MUX_METHOD_MIN_PROTOCOL,
-  describeYaziProfile,
-  detectMux,
-  inspectCurrentYaziProfile,
-  resolveSocketCandidates,
-  userYaziConfigDir,
-  yaziProfileDir
-} from "./chunk-HZHHCK24.js";
-import "./chunk-VO67MWHC.js";
-import {
-  formatDoctorReport,
-  isUninitializedHome,
-  runDoctor,
-  runDoctorFleetChecks,
-  runDoctorInteropChecks,
-  runDoctorModelChecks,
-  runDoctorRuntimeChecks
-} from "./chunk-W5VSYASO.js";
-import "./chunk-BKFM6EJV.js";
-import "./chunk-LCGCVYZ4.js";
-import "./chunk-3DPEIQKN.js";
-import {
-  runEventJournalRoot
-} from "./chunk-IQ7KR472.js";
-import "./chunk-VYMXRQI6.js";
-import "./chunk-FEFIFZTL.js";
-import "./chunk-SUW5DORT.js";
-import {
-  describeResolution,
-  toolStatus,
-  toolStatuses
-} from "./chunk-QSNYB6ZV.js";
-import {
-  findPinnedTool
-} from "./chunk-QDC3K2U3.js";
-import "./chunk-RAPCMZL4.js";
-import "./chunk-K6BSR66V.js";
-import "./chunk-XPLRXC72.js";
-import "./chunk-NEKRRTYW.js";
-import "./chunk-SP2RXXYO.js";
-import "./chunk-2OQE55CK.js";
-import "./chunk-2ANTL7MR.js";
-import {
-  printError
-} from "./chunk-VPKWYKEY.js";
-import "./chunk-5TSRNF4G.js";
-import "./chunk-P3FOHJT4.js";
-import "./chunk-76ONBSIA.js";
-import "./chunk-R346GLFC.js";
-import "./chunk-IHXBNWMM.js";
-import {
-  readSettings
-} from "./chunk-VFA6GDY5.js";
-import "./chunk-BBVJUZHB.js";
-import "./chunk-FQ4SKYE4.js";
-import "./chunk-6EJMN2Y3.js";
-import "./chunk-IWHMRKLL.js";
-import "./chunk-GXNLGKAB.js";
-import "./chunk-LL4KHSZI.js";
-import "./chunk-4ZG3XFUR.js";
-import "./chunk-BBVYXMFO.js";
-import "./chunk-SST6Z5JA.js";
-import "./chunk-IKCO5N3L.js";
-import "./chunk-3I7MS7N2.js";
-import "./chunk-APJ265NV.js";
-import {
-  resolveClioDirs
-} from "./chunk-BYP5D4HI.js";
-import "./chunk-WEPFGWHJ.js";
-import "./chunk-NUGM5KR6.js";
-import "./chunk-YXLYO42X.js";
-import {
-  init_esm_shims
-} from "./chunk-3R73A4XB.js";
-
-// src/cli/doctor.ts
-init_esm_shims();
-
-// src/cli/doctor-panes.ts
-init_esm_shims();
-import { accessSync, constants, mkdirSync } from "node:fs";
-var PANE_HOST_TOOL_ID = "herdr";
-var REQUIRED_PROTOCOL = Math.max(...Object.values(MUX_METHOD_MIN_PROTOCOL));
-function journalWritabilityFinding(root = runEventJournalRoot()) {
-  try {
-    mkdirSync(root, { recursive: true });
-    accessSync(root, constants.W_OK);
-    return { ok: true, name: "panes journal dir", detail: `${root} is writable` };
-  } catch (error) {
-    return {
-      ok: true,
-      level: "warn",
-      name: "panes journal dir",
-      detail: `${root} is not writable (${error instanceof Error ? error.message : String(error)}); \`clio-coder fleet view\` will have no transcript to follow`
-    };
-  }
-}
-async function panesFindings(env = process.env) {
-  let enabled = "off";
-  try {
-    enabled = readSettings().panes.enabled;
-  } catch {
-  }
-  if (enabled === "off") {
-    return [
-      {
-        ok: true,
-        name: "panes mode",
-        detail: "off by choice (panes.enabled=off); start `clio-coder --with-panes` for one session, or set panes.enabled=auto"
-      },
-      journalWritabilityFinding()
-    ];
-  }
-  const { detection, client } = await detectMux({ enabled, env });
-  await client?.close().catch(() => void 0);
-  const candidates = detection.candidates.length > 0 ? detection.candidates : resolveSocketCandidates(env);
-  const findings = [
-    {
-      ok: true,
-      level: detection.mode === "none" ? "warn" : "ok",
-      name: "panes mode",
-      detail: `${detection.mode} (panes.enabled=${enabled}); ${detection.reason}`
-    },
-    {
-      ok: true,
-      level: detection.socketPath === null ? "warn" : "ok",
-      name: "panes socket",
-      detail: detection.socketPath === null ? `no socket answered; tried ${candidates.length > 0 ? candidates.join(", ") : "no candidates"}` : `${detection.socketPath} answered a ping`
-    }
-  ];
-  const server = detection.server;
-  findings.push({
-    ok: true,
-    level: server === null || server.protocol < REQUIRED_PROTOCOL ? "warn" : "ok",
-    name: "panes protocol",
-    detail: server === null ? `unknown; Clio's optional methods need protocol ${REQUIRED_PROTOCOL} or newer` : `server ${server.version}, protocol ${server.protocol}; Clio's optional methods need ${REQUIRED_PROTOCOL} (${server.protocol >= REQUIRED_PROTOCOL ? "satisfied" : "toasts and agent focus fall back"})`
-  });
-  const entry = findPinnedTool(PANE_HOST_TOOL_ID);
-  findings.push(
-    entry === null ? {
-      ok: true,
-      level: "warn",
-      name: "panes binary",
-      detail: `${PANE_HOST_TOOL_ID} is not in the pinned tool registry`
-    } : {
-      ok: true,
-      level: toolStatus(entry).resolution.source === "none" ? "warn" : "ok",
-      name: "panes binary",
-      detail: describeResolution(toolStatus(entry))
-    }
-  );
-  findings.push(journalWritabilityFinding());
-  return findings;
-}
-
-// src/cli/doctor-state-size.ts
-init_esm_shims();
-import { lstatSync, readdirSync } from "node:fs";
-import { join } from "node:path";
-function stateStorageFinding(stateDir = resolveClioDirs().state) {
-  let names;
-  try {
-    names = readdirSync(stateDir);
-  } catch (error) {
-    return {
-      ok: false,
-      name: "state storage",
-      detail: `${stateDir} could not be measured: ${error instanceof Error ? error.message : String(error)}`
-    };
-  }
-  let total = 0;
-  let largest = null;
-  for (const name of names.sort()) {
-    const measured = measureEntry(join(stateDir, name));
-    if (measured.error !== null) {
-      return { ok: false, name: "state storage", detail: measured.error };
-    }
-    total += measured.bytes;
-    if (largest === null || measured.bytes > largest.bytes) largest = { name, bytes: measured.bytes };
-  }
-  return {
-    ok: true,
-    name: "state storage",
-    detail: largest === null ? `${formatBytes(total)} (${total.toLocaleString("en-US")} bytes); largest contributor none` : `${formatBytes(total)} (${total.toLocaleString("en-US")} bytes); largest contributor ${largest.name} at ${formatBytes(largest.bytes)} (${largest.bytes.toLocaleString("en-US")} bytes)`
-  };
-}
-function measureEntry(path) {
-  let stats;
-  try {
-    stats = lstatSync(path);
-  } catch (error) {
-    return {
-      bytes: 0,
-      error: `${path} could not be inspected: ${error instanceof Error ? error.message : String(error)}`
-    };
-  }
-  if (!stats.isDirectory() || stats.isSymbolicLink()) return { bytes: stats.size, error: null };
-  let names;
-  try {
-    names = readdirSync(path);
-  } catch (error) {
-    return { bytes: 0, error: `${path} could not be listed: ${error instanceof Error ? error.message : String(error)}` };
-  }
-  let bytes = 0;
-  for (const name of names) {
-    const child = measureEntry(join(path, name));
-    if (child.error !== null) return child;
-    bytes += child.bytes;
-  }
-  return { bytes, error: null };
-}
-function formatBytes(bytes) {
-  if (bytes < 1024) return `${bytes} B`;
-  const units = ["KiB", "MiB", "GiB", "TiB"];
-  let value = bytes;
-  let unit = -1;
-  do {
-    value /= 1024;
-    unit += 1;
-  } while (value >= 1024 && unit < units.length - 1);
-  return `${value.toFixed(value >= 10 ? 1 : 2)} ${units[unit]}`;
-}
-
-// src/cli/doctor-toolchain.ts
-init_esm_shims();
-function yaziProfileFinding() {
-  try {
-    const profile = inspectCurrentYaziProfile();
-    return {
-      ok: true,
-      name: "yazi managed profile",
-      detail: describeYaziProfile(profile),
-      level: profile.state === "current" ? "ok" : "warn"
-    };
-  } catch (error) {
-    return {
-      ok: true,
-      name: "yazi managed profile",
-      level: "warn",
-      detail: `${yaziProfileDir()} could not be inspected (${error instanceof Error ? error.message : String(error)}); user config ${userYaziConfigDir()} is separate and untouched`
-    };
-  }
-}
-function toolchainFindings() {
-  const tools = toolStatuses().map((status) => ({
-    ok: true,
-    name: `external tool ${status.id}`,
-    // The rejection and the remedy both live inside the shared resolution
-    // sentence, so this row and `clio-coder tools status` cannot describe the
-    // same machine differently.
-    detail: describeResolution(status),
-    level: status.resolution.source === "none" ? "warn" : "ok"
-  }));
-  return [...tools, yaziProfileFinding()];
-}
-
-// src/cli/doctor.ts
-var HELP = `clio-coder doctor [--fix] [--json]
-
-Diagnose Clio Coder state without creating files. On a home Clio has never
-written to, doctor says so in one row and exits 0. Use --fix to repair structure:
-missing directories, missing template files, and credential permissions.
-Settings are validated directly against the current schema.
-Pass --json to emit a machine-readable report on stdout.
-`;
-async function runDoctorCommand(args = []) {
-  if (args.includes("--help") || args.includes("-h")) {
-    process.stdout.write(HELP);
-    return 0;
-  }
-  const fix = args.includes("--fix");
-  const json = args.includes("--json");
-  const unknown = args.find((arg) => arg !== "--fix" && arg !== "--json");
-  if (unknown) {
-    printError(`unknown flag: ${unknown}`);
-    process.stderr.write(HELP);
-    return 2;
-  }
-  const untouched = !fix && isUninitializedHome();
-  const findings = runDoctor({ fix });
-  const storageChecks = untouched ? [] : [stateStorageFinding()];
-  const runtimeChecks = await runDoctorRuntimeChecks();
-  const modelChecks = await runDoctorModelChecks();
-  const interopChecks = untouched ? [] : await runDoctorInteropChecks();
-  const fleetChecks = untouched ? [] : await runDoctorFleetChecks();
-  const toolChecks = untouched ? [] : toolchainFindings();
-  const paneChecks = untouched ? [] : await panesFindings();
-  const all = [
-    ...findings,
-    ...storageChecks,
-    ...runtimeChecks,
-    ...modelChecks,
-    ...interopChecks,
-    ...fleetChecks,
-    ...toolChecks,
-    ...paneChecks
-  ];
-  const ok = all.every((f) => f.ok);
-  if (json) {
-    process.stdout.write(`${JSON.stringify({ ok, fix, findings: all }, null, 2)}
-`);
-  } else {
-    process.stdout.write(`${formatDoctorReport(all)}
-`);
-  }
-  return ok ? 0 : 1;
-}
-export {
-  runDoctorCommand
-};
-//# sourceMappingURL=doctor-QOA5FNY5.js.map

package/dist/fleet-view-ZCON35AG.js

@@ -1,102 +0,0 @@
-import { createRequire as __clioCreateRequire } from "node:module"; const require = __clioCreateRequire(import.meta.url);
-import {
-  loadFleetRunViewModel,
-  loadRunViewModel,
-  readWatchSelection,
-  renderFleetRunView,
-  renderRunView,
-  renderWatchView,
-  resolveFleetRootId,
-  resolveRunId,
-  runFleetView
-} from "./chunk-IBEBSCYA.js";
-import "./chunk-NYS75XW5.js";
-import "./chunk-BUMFYQFY.js";
-import "./chunk-X75E3D2N.js";
-import "./chunk-B7OBL7PK.js";
-import "./chunk-QREDIESB.js";
-import "./chunk-U77AMWDL.js";
-import "./chunk-QBJA7R7N.js";
-import "./chunk-RVG5JXAL.js";
-import "./chunk-3DPEIQKN.js";
-import "./chunk-NHLBIGRH.js";
-import "./chunk-IQ7KR472.js";
-import "./chunk-T56WDKA5.js";
-import "./chunk-W6GROXXM.js";
-import "./chunk-QLFS5GO2.js";
-import "./chunk-TXOTCRLG.js";
-import "./chunk-HVDIIIQW.js";
-import "./chunk-CTJ4RNAA.js";
-import "./chunk-RKKLTLYB.js";
-import "./chunk-SUW5DORT.js";
-import "./chunk-J4W7KFM7.js";
-import "./chunk-SJ5ZKQ4S.js";
-import "./chunk-2JDWVJND.js";
-import "./chunk-GKF55TAZ.js";
-import "./chunk-32KWKNSF.js";
-import "./chunk-TVHHYFHE.js";
-import "./chunk-42FMPA75.js";
-import "./chunk-H7IXIC72.js";
-import "./chunk-5LXZXPKX.js";
-import "./chunk-OQE5J4C6.js";
-import "./chunk-RAPCMZL4.js";
-import "./chunk-CY6FY24N.js";
-import "./chunk-OZNBF4L3.js";
-import "./chunk-4BJ5BYCE.js";
-import "./chunk-6XLNIQDB.js";
-import "./chunk-CMZWFGD2.js";
-import "./chunk-PQEFIJ36.js";
-import "./chunk-HHV2GANA.js";
-import "./chunk-DYJP44XW.js";
-import "./chunk-GCSMB2KY.js";
-import "./chunk-UL3WSD3F.js";
-import "./chunk-ECH6PKUQ.js";
-import "./chunk-5B2AEOW5.js";
-import "./chunk-K6BSR66V.js";
-import "./chunk-XAKHZX5N.js";
-import "./chunk-33YXPOE3.js";
-import "./chunk-7CR24IG7.js";
-import "./chunk-XPLRXC72.js";
-import "./chunk-DQITNCXG.js";
-import "./chunk-CFGTUFWB.js";
-import "./chunk-P3FOHJT4.js";
-import "./chunk-UM7N4G5A.js";
-import "./chunk-ZGVHUX3M.js";
-import "./chunk-HLW2MRKE.js";
-import "./chunk-76ONBSIA.js";
-import "./chunk-R346GLFC.js";
-import "./chunk-IHXBNWMM.js";
-import "./chunk-VFA6GDY5.js";
-import "./chunk-BBVJUZHB.js";
-import "./chunk-FQ4SKYE4.js";
-import "./chunk-6EJMN2Y3.js";
-import "./chunk-IWHMRKLL.js";
-import "./chunk-6DB53AJS.js";
-import "./chunk-GXNLGKAB.js";
-import "./chunk-LL4KHSZI.js";
-import "./chunk-4ZG3XFUR.js";
-import "./chunk-HI63TFOG.js";
-import "./chunk-BBVYXMFO.js";
-import "./chunk-SST6Z5JA.js";
-import "./chunk-IKCO5N3L.js";
-import "./chunk-3I7MS7N2.js";
-import "./chunk-APJ265NV.js";
-import "./chunk-BYP5D4HI.js";
-import "./chunk-WEPFGWHJ.js";
-import "./chunk-NUGM5KR6.js";
-import "./chunk-VO2LKSTM.js";
-import "./chunk-UOSL25KY.js";
-import "./chunk-YXLYO42X.js";
-import "./chunk-3R73A4XB.js";
-export {
-  loadFleetRunViewModel,
-  loadRunViewModel,
-  readWatchSelection,
-  renderFleetRunView,
-  renderRunView,
-  renderWatchView,
-  resolveFleetRootId,
-  resolveRunId,
-  runFleetView
-};
-//# sourceMappingURL=fleet-view-ZCON35AG.js.map

package/dist/panes-HMABYVO4.js

@@ -1,58 +0,0 @@
-import { createRequire as __clioCreateRequire } from "node:module"; const require = __clioCreateRequire(import.meta.url);
-import {
-  runToolsCommand
-} from "./chunk-NQQH3YT7.js";
-import "./chunk-HZHHCK24.js";
-import "./chunk-VO67MWHC.js";
-import "./chunk-BKFM6EJV.js";
-import "./chunk-LCGCVYZ4.js";
-import "./chunk-QSNYB6ZV.js";
-import "./chunk-QDC3K2U3.js";
-import "./chunk-2ANTL7MR.js";
-import {
-  printError
-} from "./chunk-VPKWYKEY.js";
-import "./chunk-5TSRNF4G.js";
-import "./chunk-IWHMRKLL.js";
-import "./chunk-BBVYXMFO.js";
-import "./chunk-SST6Z5JA.js";
-import "./chunk-IKCO5N3L.js";
-import "./chunk-3I7MS7N2.js";
-import "./chunk-APJ265NV.js";
-import "./chunk-BYP5D4HI.js";
-import "./chunk-WEPFGWHJ.js";
-import "./chunk-YXLYO42X.js";
-import {
-  init_esm_shims
-} from "./chunk-3R73A4XB.js";
-
-// src/cli/panes.ts
-init_esm_shims();
-var HELP = `clio-coder panes install [--force] [--json]
-
-Install the pane multiplexer Clio drives. This is an alias for
-\`clio-coder tools install herdr\`; the toolchain command is where every pinned
-external program is managed, and \`clio-coder tools status herdr\` explains
-which copy Clio would run.
-`;
-async function runPanesCommand(argv = []) {
-  if (argv.includes("--help") || argv.includes("-h")) {
-    process.stdout.write(HELP);
-    return 0;
-  }
-  const [subcommand, ...rest] = argv;
-  if (subcommand === void 0) {
-    process.stdout.write(HELP);
-    return 2;
-  }
-  if (subcommand !== "install") {
-    printError(`unknown panes command: ${subcommand}`);
-    process.stderr.write(HELP);
-    return 2;
-  }
-  return runToolsCommand(["install", "herdr", ...rest]);
-}
-export {
-  runPanesCommand
-};
-//# sourceMappingURL=panes-HMABYVO4.js.map

package/docs/artifact-versions.md

@@ -1,67 +0,0 @@
-# Artifact Versions & Serialization Contracts
-
-This document is the canonical registry of all versioned file formats, serialized data structures, integrity digests, and migration rules across Clio Coder in `v0.4.0`.
-
----
-
-## 1. Versioned Artifacts Registry
-
-Clio Coder strictly versions every persistent or network-transported data structure. When a reader encounters an incompatible version, it either executes an automated migration or fails closed with a typed error.
-
-| Artifact / Subsystem | Current Version | Symbol / Type & Source Location | Persisted Path / Wire Location | Schema Semantics & Version Differences | Mismatch Handling |
-| :--- | :--- | :--- | :--- | :--- | :--- |
-| **Run Receipt** | `20` | `RUN_RECEIPT_INTEGRITY_VERSION = 20`<br>`src/domains/dispatch/receipt-integrity.ts:13` | `<stateDir>/receipts/<runId>.json` | Cryptographically sealed run record. Version 20 adds `pathProvenance` on dispatch intent and the resolved `pathScope`, over the v19 base of provenance fields, routing intent, quality labels, `validationGrounding`, `capabilityMismatch`, council provenance, and fleet gate provenance. | Fail-closed. A receipt below v20 is reported as retired rather than invalid, is never read as evidence, and is never migrated; a malformed or tampered v20 receipt fails verification. |
-| **Dispatch Intent** | `2` | `DISPATCH_INTENT_VERSION = 2`, `DISPATCH_INTENT_SUPPORTED_VERSIONS = [2]`<br>`src/domains/dispatch/intent-compatibility.ts` | Inside the resolved dispatch plan artifact, the `JobSpec`/`DispatchRequest`, and the sealed run receipt | Typed model- and producer-declared scope: `read_roots`, `write_roots`, `relevant_paths`, `expected_outputs`, and declared-id `verification`, plus the `pathProvenance` binding every policy-bearing path to the field that declared it. Version 2 adds `pathProvenance` over the v1 path-and-output shape. | Fail-closed, never migrated. The supported set is a membership list, not a range: any other version is refused with `intent_version_unsupported` and the caller restates the fields on a fresh dispatch call. Omitted intent is accepted through the separately tracked legacy inference path; contradictory intent is a terminal refusal. See [dispatch-typed-intent.md](dispatch-typed-intent.md). |
-| **Dispatch Path Scope Provenance** | `1` | `version: 1` in `interface DispatchPathScopeProvenance`<br>`src/domains/dispatch/path-scope.ts` | `pathScope` on the sealed run receipt | Resolved policy-bearing paths with per-field provenance (`declared`/`derived`/`inferred`), source, and confidence. Never carries the task or briefing prose an inferred path came from. | Sealed inside the receipt integrity digest; shares the receipt's fail-closed policy. |
-| **Resolved Dispatch Plan Artifact** | `3` | `version: 3` in `interface ResolvedDispatchPlanArtifact`<br>`src/tools/dispatch-plan.ts:122` | Trusted admission-time tool argument, rendered and hashed into the plan approval | Pinned agent/target/model/node per task plus the sealed `intent` and admission-resolved `resolvedVerification`. The rendered artifact carries `intent_sha256` for a declared task and the full inferred scope table for a legacy one. | Fail-closed. Any version but 3 parses as `null`, as does any task whose `intent` is not a normalized v2 intent; the call falls back to unresolved admission rather than executing a half-understood plan. |
-| **Session Ledger** | `3` | `CURRENT_SESSION_FORMAT_VERSION = 3`<br>`src/engine/session.ts:66` | `<stateDir>/sessions/<cwdHash>/<sessionId>/` (`meta.json`, `current.jsonl`, `tree.json`) | Append-only ledger format with UUIDv7 turn IDs, session header line, and tree graph linkage. | Automated migration via `src/domains/session/migrations/` on `/resume`. Earlier unmigratable versions rejected. |
-| **Worker Spec** | `3` | `WORKER_SPEC_VERSION = 3`<br>`src/worker/spec-contract.ts:22` | Subprocess `stdin` control plane JSON payload | Worker invocation parameters, tool surface profile, and execution bounds. | Fail-closed preflight rejection before worker activation. |
-| **Worker Runtime Descriptor** | `2` | `WORKER_RUNTIME_DESCRIPTOR_VERSION = 2`<br>`src/worker/spec-contract.ts:23` | Worker attestation descriptor payload | Attestation descriptor for worker runtime environment and hardware facts. | Attestation mismatch causes immediate process termination. |
-| **Worker Protected Artifact State** | `1` | `WORKER_PROTECTED_ARTIFACT_STATE_VERSION = 1`<br>`src/worker/spec-contract.ts:24` | Worker spec initialization snapshot | Snapshot of active protected artifact paths and validation commands passed to worker. | Worker fails closed before executing mutations. |
-| **Fleet Contract** | `1 \| 2 \| 3 \| 4 \| 5` (Current: `5`) | `FleetContractVersion = 1 \| 2 \| 3 \| 4 \| 5`<br>`FLEET_WRITE_BOUNDARY_VERSION = 4`<br>`FLEET_DYNAMIC_STEP_VERSION = 5`<br>`src/domains/agents/fleet-contract.ts` | `.clio-coder/fleets/<name>.yaml`, `.clio-coder/fleets/<name>.yml`, or built-in recipes | Multi-agent workflow contract. v1 is agent-only; v2 adds deterministic code steps; v3 adds bounded loops and commit steps; v4 adds declared per-step write boundaries; v5 adds plan steps, gate steps, per-step target or profile routing, and the single-writer declaration. | Reader refuses contracts whose version features it does not support. |
-| **Execution Plan** | `4` | `version: 4` in `interface ExecutionPlan`<br>`src/domains/dispatch/execution-plan.ts:98` | Statically compiled DAG representation in dispatch memory and receipts | Statically unrolled, deterministically hashed execution plan. v4 adds bounded loop nodes, verification staleness tracking, and commit nodes. | Preflight validation rejects unsupported plan versions. |
-| **Eval Artifact** | `4` | `version: 4` in `interface EvalArtifactV4`<br>`src/domains/eval/schema/artifact.ts:51-52` | `<stateDir>/evals/<evalId>.json` | Stored eval results with suite provenance, matrix parameters, and itemized metric outcomes. Note: `EVAL_ARTIFACT_VERSION = 1` in `src/domains/eval/types.ts:2` is legacy/dead code. | Incompatible eval artifacts are rejected during `clio-coder eval report` and `compare`. |
-| **Prompt Manifest** | `2` | `PROMPT_MANIFEST_VERSION = 2`<br>`src/domains/session/prompt-manifest.ts:30` | `<stateDir>/sessions/<cwdHash>/<sessionId>/prompt-manifest.jsonl` | Per-session record of the compiled system prompt: fragment ids, relative paths, content hashes, section token estimates, and the composition hash. Version 2 is the stable-prefix-first ordering with one `# Memory` header and records `contextWindowSource` beside the window the prompt states (#249). | Additive. A record without a `version` field predates the field and reads as version 1, so a 0.3.8 manifest still parses; the version explains the single `promptRecompiled` entry a resumed session's first compile writes. |
-| **Eval Verdict Envelope** | `clio.eval.verdict.v1` | `EVAL_VERDICT_SCHEMA_V1`<br>`src/domains/eval/schema/verdict.ts:1` | Inside the Eval Artifact at `<stateDir>/evals/<evalId>.json` | Fail-closed verdict identity with ledger- and receipt-sourced performance metrics, per-scenario pass and distribution aggregates, and serving-configuration provenance (#252). One pass decision: the code grader's outcome is part of `result.pass`. | Fail-closed. `eval compare` refuses serving-configuration drift unless explicitly allowed; an artifact without a parseable verdict envelope is rejected rather than read as passing. |
-| **Behavioral Scenario & Result** | `clio.eval.scenario.v1`, `clio.eval.behavior.v1` | `EVAL_BEHAVIOR_SCENARIO_SCHEMA_V1`, `EVAL_BEHAVIOR_SCHEMA_V1`<br>`src/domains/eval/schema/behavioral.ts:4-5` | Suite v2 task declarations; additive sibling inside the Eval Artifact | Versioned behavioral contract: bounded expected and forbidden rules across tool choice, exploration, delegation, safety comprehension, claim grounding, denied-tool recovery, completion behavior, and task correctness, with deterministic judge inputs canonicalized from transcript, tool, receipt, and grader facts (#156). References the unchanged `clio.eval.verdict.v1` identity. | Fail-closed. `unknown`, `unmeasured`, `behavioral_failure`, and `infrastructure_failure` stay distinct; a malformed, partial, contradictory, or cross-linked verdict cannot parse as a pass. Existing artifact readers are unaffected because the sibling is additive. |
-| **Behavioral Metrics Projection** | `clio.eval.behavior.metrics.v1` | `EVAL_BEHAVIOR_METRICS_SCHEMA_V1`<br>`src/domains/eval/schema/behavioral-metrics.ts:4` | Additive role- and target/model-bound projection inside the Eval Artifact | Ten sourced metric families (correctness, safety, label violations, tool-call efficiency, unnecessary exploration, delegation quality, unsupported claims, tokens, latency, cost, and repeat variability) with coverage, min/max, p90, population variance, and standard deviation per distribution (#161). | Unmeasured observations stay typed `null` and never become zero violations. A baseline hard metric that becomes unmeasured fails the comparison closed, and `--metric` filtering cannot hide a hard failure. |
-| **Execution Envelope** | `clio.eval.execution-envelope.v1` | `EVAL_EXECUTION_ENVELOPE_SCHEMA_V1`<br>`src/domains/eval/schema/execution-envelope.ts:1` | On every new behavioral result inside the Eval Artifact | Strictly parsed binding of prompt fragment ids, versions, and content hashes, composition hash, recipe identity and content hash, target, wire model, runtime, thinking level, tool signature, autonomy, policy hashes, project-context provenance, and corpus id and version (#164). Suites declare which matrix dimensions may vary. | Fail-closed. Comparisons mark rows incomparable on any undeclared envelope drift, refuse one-sided envelopes and within-run variance, and name every prompt- or recipe-affected corpus result. |
-| **Trace Database** | `1` | `TRACE_SCHEMA_VERSION = 1`<br>`src/domains/observability/trace-store.ts:23` | `<stateDir>/trace.sqlite` (`meta` table `schema_version`) | Schema version for the 7 SQLite trace mirror tables (`runs`, `phases`, `events`, `envelopes`, `gate_results`, `agent_sessions`, `processes`). | Log warning (`[clio:trace]`), trace writing degrades without failing the parent run. |
-| **Capacity State File** | `2` | `version: 2` in `interface CapacityStateFile`<br>`src/domains/dispatch/capacity-lease.ts:40` | `<stateDir>/dispatch-admission.json` | Active capacity leases, drain status, and cross-process lock state. | Corrupted or unparseable state file causes admission to fail closed. |
-| **Protected Artifact Journal** | `1` | `version: 1` in `interface PendingProtectedArtifactRecord`<br>`src/domains/session/protected-artifact-journal.ts:22` | `<stateDir>/protected-artifact-pending/<key>/<id>.json` | Write-ahead durability records for pending protected artifacts. | Leftover records reconciled during session initialization. |
-| **Fleet Run Record** | `1` | `version: 1` in `interface FleetRunRecord`<br>`src/domains/dispatch/fleet-run.ts` | `<stateDir>/fleet-runs/<runId>.json` | Durable record of one fleet run: contract name, plan hash, static step ids and steps, `--var` values, replayed and settled step results, and the delegation plan hash a `kind: plan` step produced. Read by `fleet run --resume`. | Resume refuses a changed plan hash with a per-step diff and refuses differing `--var` values. |
-| **Durable Assignment Store** | `1` | `version: 1` in `interface AssignmentStoreFile`<br>`DurableAssignmentRecord`<br>`src/domains/dispatch/assignment-store.ts` | `<stateDir>/assignments.json` | Machine-wide logical-dispatch records: assignment id, attempt ids, terminal run id, status, optional fleet verdict owner, and—while running—`processOwner {pid, processBirthToken, acquiredAt}`. The owner is cleared on a true terminal transition. | A live sibling owner keeps the row running; a genuinely dead or legacy ownerless row is reconciled. An unsupported or unreadable store is treated as empty, and malformed records are ignored. |
-| **Checkout Writer Lease** | `1` | `version: 1` in `interface CheckoutWriterLeaseRecord`<br>`src/domains/dispatch/checkout-writer-lease.ts` | `<stateDir>/checkout-writer-leases/<key>.json` (key derived from the canonical checkout path) | Cross-process single-writer lease: checkout path, pid, process birth token, acquisition time. | A live sibling holder is refused with `checkout_writer_lease_held`; a dead owner is reclaimed; a malformed record is treated as absent. |
-| **Out-of-turn Usage Ledger** | unversioned JSONL | `OutOfTurnUsageRow`<br>`src/domains/observability/out-of-turn-usage.ts` | `<stateDir>/usage/out-of-turn.jsonl` | One row per priced `/btw` or `/handoff` call: label, session id, repo identity, timestamp, target, attributed model, provider usage. Bounded ring of `MAX_OUT_OF_TURN_USAGE_ROWS = 1000`, rewritten atomically under the state-file lock. | Unparseable rows are skipped and counted by `usage report`; the session ledger is never affected. |
-| **Library Pins** | unversioned YAML map | `readLibraryPins`<br>`src/domains/resources/library.ts` | `<configDir>/library-pins.yaml` | Typed ref (`skill:x`, `agent:y`, `prompt:p`, `fleet:z`) to `{sha256, sourceUrl}` for every resource `library add` or the Skills Hub installed. | A non-map document reads as empty; an entry whose installed file is missing is reported as available, not installed. |
-
----
-
-## 2. Integrity Verification Contracts
-
-### Receipt Integrity (Version 20)
-
-Receipt integrity authenticates that a sealed receipt matches its ledger envelope without modification. Verification reproduces the canonical JSON serialization and computes the SHA-256 digest:
-
-```typescript
-export function computeReceiptDigest(receipt: RunReceiptV15): string {
-  const canonical = serializeCanonicalReceipt(receipt);
-  return createHash("sha256").update(canonical, "utf8").digest("hex");
-}
-```
-
-Receipt verification checks:
-1. `integrity.version === 20`. A receipt sealed at a lower version is reported as retired rather than invalid: it is intact, but is not read as evidence and is never migrated.
-2. Calculated SHA-256 matches `integrity.digest`.
-3. All optional fields present in the schema (`validationGrounding`, `capabilityMismatch`, `steering`, `gate`, `fleetGate`, `council`, `plan`, `briefing`) conform to the strict v20 specification.
-
----
-
-## 3. Migration Mechanics
-
-Session migrations execute automatically when resuming a session whose `meta.json` format version is less than `CURRENT_SESSION_FORMAT_VERSION = 3`:
-
-1. **Discovery**: `src/domains/session/migrations/index.ts:runMigrations` reads the recorded `sessionFormatVersion`.
-2. **Step Execution**: Sequentially runs migration passes (e.g. `v1 -> v2`, `v2 -> v3`), transforming `current.jsonl` entries and reconstructing `tree.json` linkages.
-3. **Atomic Commit**: Staged migrations are written to temporary files, fsync'd, and atomically renamed over the original session files.
-4. **Metadata Update**: `meta.sessionFormatVersion` is updated to `3` and committed to `meta.json`.

package/docs/documentation-coverage.md

@@ -1,46 +0,0 @@
-# Clio Coder Documentation Coverage Matrix
-
-This matrix maps every top-level directory in `src/` and every domain directory under `src/domains/` to its authoritative documentation page. It records coverage status (`documented`, `partial`, `undocumented`), missing concepts, and key source contracts for `v0.4.0`.
-
-## Coverage Matrix
-
-| Source Area | Primary Subsystems / Modules | Owning Documentation | Status | Coverage Details & Gap Analysis |
-| :--- | :--- | :--- | :--- | :--- |
-| `src/cli/` | Command line routing, subcommands, flag parsing, exit codes, machine-readable JSON streaming | [commands-and-modes.md](commands-and-modes.md), [exit-codes-and-output.md](exit-codes-and-output.md) | `documented` | Covered by CLI reference and the dedicated exit codes and machine-readable output contract guide. |
-| `src/core/` | Invariants, constants, configuration defaults, headless permissions, tool definitions, response schema contracts | [architecture.md](architecture.md), [configuration-and-targets.md](configuration-and-targets.md), [installation-and-lifecycle.md](installation-and-lifecycle.md), [safety-model.md](safety-model.md) | `documented` | Fully documented across architecture, configuration, lifecycle, and safety model pages. |
-| `src/engine/` (Core) | Engine turn loop, prompt priming, streaming message adapters, turn execution | [architecture.md](architecture.md), [context-engine.md](context-engine.md) | `documented` | Documented across architecture and context engine guides. |
-| `src/engine/acp/` | ACP protocol server, transport adapters, tool mediators, permission forwarding, error taxonomy | [acp.md](acp.md) | `documented` | Dedicated ACP specification covering server wiring, permission mediation, timeouts, error taxonomy, and security boundaries. |
-| `src/entry/` | Application bootstrapping, CLI router, interactive loop entry point | [architecture.md](architecture.md), [installation-and-lifecycle.md](installation-and-lifecycle.md) | `documented` | Documented in architecture compilation boundaries and lifecycle guides. |
-| `src/interactive/` | TUI architecture, screens, overlays, keybindings, panels, theme tokens, width matrices, prompt pre-warm rounds and their gating, expected-cold reason stamping | [tui-design.md](tui-design.md), [commands-and-modes.md](commands-and-modes.md), [context-engine.md](context-engine.md) | `documented` | Fully documented in TUI design specification and commands reference; the pre-warm and the cache-honesty surfaces `/context` renders are in the context engine reference. |
-| `src/tools/` | 20 built-in tools across 7 planes, registry, policy engine bindings, observation envelope bounds | [tool-usage.md](tool-usage.md), [prompt-envelope-and-tools.md](prompt-envelope-and-tools.md) | `documented` | Comprehensive 20-tool reference with schemas, examples, and envelope size constraints. |
-| `src/utils/` | Image manipulation, photon operations, git execution utilities | [architecture.md](architecture.md), [tool-usage.md](tool-usage.md) | `documented` | Utility helpers documented within tool usage and architectural boundaries. |
-| `src/worker/` | Worker subprocess lifecycle, NDJSON transport, heartbeat timers, control lane demuxing, spec contracts | [worker-dispatch-mechanics.md](worker-dispatch-mechanics.md) | `documented` | Complete reference for NDJSON socket protocols, watchdog timers, and exit status mapping. |
-| `src/domains/agents/` | 12 built-in recipes, agent catalog, recipe schema, fleet commands, fleet contract v4 | [built-in-agents.md](built-in-agents.md), [fleet-dispatch.md](fleet-dispatch.md) | `documented` | Documented in built-in agent recipes guide and fleet dispatch architecture. |
-| `src/domains/components/` | Component scanning, snapshots, hashing, diffing | [middleware-and-components.md](middleware-and-components.md) | `documented` | Documented in active component snapshot and middleware guide. |
-| `src/domains/config/` | Configuration contracts, file watcher, keybinding definitions, setting classifiers | [configuration-and-targets.md](configuration-and-targets.md), [commands-and-modes.md](commands-and-modes.md) | `documented` | Documented in configuration targets and command/keybinding reference. |
-| `src/domains/context/` | `CLIO-CODER.md` bootstrap, codewiki generation, prompt context assembly, project rules, non-destructive working-set eviction (`age-horizon` and `structural-v1` policies, protection predicates, path index, byte-stable markers, recall by ref) | [context-engine.md](context-engine.md), [context-working-set.md](context-working-set.md) | `documented` | Context window, token accounting, and the three compaction mechanisms in the engine reference; the working-set layer has its own guide covering the vocabulary, both ledger record kinds and format v4, the marker contract, both policies with their rule order, recall semantics, and the operator surfaces. |
-| `src/domains/dispatch/` | Fleet orchestration, assignment store, batch tracker, admission, route planner, receipt integrity v16 | [fleet-dispatch.md](fleet-dispatch.md), [dispatch-architecture-rationale.md](dispatch-architecture-rationale.md), [worker-dispatch-mechanics.md](worker-dispatch-mechanics.md) | `documented` | Multi-node fleet dispatch, admission invariants, and receipt verification fully documented. |
-| `src/domains/eval/` | Suite v2 YAML schema, eval runner, `clio.eval.verdict.v1` envelope and its Suite v2 adapter, tracked metrics and scenario aggregates, serving-configuration provenance, reporters, workspace sandboxing | [eval-runner.md](eval-runner.md), [evals-internal.md](evals-internal.md) | `documented` | Product evals are documented independently from external benchmarks. The verdict envelope, `trackedMetrics` and their sources, `--trials`, and the config-drift and estimated-versus-measured refusals are in the runner reference. |
-| `src/domains/evidence/` | Evidence bundles, findings taxonomy, provenance store, failure attribution | [evidence-and-memory.md](evidence-and-memory.md) | `documented` | Documented in evidence directory structures and memory retrieval guide. |
-| `src/domains/evolution/` | Falsifiable Change Manifest JSON templates and `clio-coder evolve` self-edit gates | [evolution.md](evolution.md) | `documented` | Documented in evolution manifest reference and mutation validation rules. |
-| `src/domains/extensions/` | Extension manifest schemas, resource roots, portable share archives | [extensions-and-sharing.md](extensions-and-sharing.md) | `documented` | Documented in extensions and sharing guide. |
-| `src/domains/lifecycle/` | Platform initialization, upgrade, reset, uninstall, migrations, doctor diagnostics | [installation-and-lifecycle.md](installation-and-lifecycle.md) | `documented` | Platform directories, permissions, initialization, and diagnostic commands documented. |
-| `src/domains/memory/` | Proactive task memory, three-tier bank, two-phase policy grammar, handoffs | [proactive-memory.md](proactive-memory.md), [evidence-and-memory.md](evidence-and-memory.md) | `documented` | Proactive task bank, intervention rules, and persistence fully documented. |
-| `src/domains/middleware/` | Middleware hooks (`turn_start`, `tool_call`, `tool_result`, `turn_end`), reminders, budgets | [middleware-and-components.md](middleware-and-components.md) | `documented` | Documented in middleware hooks and active component snapshot guide. |
-| `src/domains/observability/` | Trace store (`node:sqlite` WAL mirror), metrics, cost accounting, evidence index | [trace-store.md](trace-store.md), [observability.md](observability.md) | `documented` | Database schema, rowid cursor queries, and receipt provenance documented. |
-| `src/domains/prompts/` | Prompt compiler, fragment loaders, static cache stability, memory intervention injection | [prompt-envelope-and-tools.md](prompt-envelope-and-tools.md) | `documented` | Documented in prompt envelope and tool delivery guide. |
-| `src/domains/providers/` | Runtime adapters, capability probes, model catalog and its per-family `measuredUnder` provenance, canonical endpoint keys and per-endpoint request-slot capacity, thinking control, ALCF OAuth | [configuration-and-targets.md](configuration-and-targets.md), [model-catalog.md](model-catalog.md), [provider-adapter-cookbook.md](provider-adapter-cookbook.md), [alcf-provider.md](alcf-provider.md) | `documented` | Complete provider adapter contracts, model catalogs, and ALCF Globus targets documented. |
-| `src/domains/resources/` | Skill package discovery, marketplace index resolution, prompt resources | [skills-marketplace.md](skills-marketplace.md), [extensions-and-sharing.md](extensions-and-sharing.md) | `documented` | Skills marketplace, publishing flows, and resource managers documented. |
-| `src/domains/safety/` | Policy engine, action classifiers, damage-control rules, path policies, finish contract, audit log | [safety-model.md](safety-model.md), [scientific-validation.md](scientific-validation.md) | `documented` | Policy evaluation order, 10-step sequence, write containment, and finish contract documented. |
-| `src/domains/scheduling/` | Capacity lease acquisition, heartbeats, expiry, cross-process locks, cluster scheduling | [capacity-and-scheduling.md](capacity-and-scheduling.md), [fleet-dispatch.md](fleet-dispatch.md) | `documented` | Dedicated capacity leasing, heartbeat TTL, and cross-process lock reference. |
-| `src/domains/session/` | Session ledger format v4, tree branching (`/tree`), `/fork`, `/resume`, checkpoints, protected-artifact journal | [session-lifecycle.md](session-lifecycle.md), [context-working-set.md](context-working-set.md) | `documented` | Dedicated session lifecycle guide covering branching, journal, and recovery; the `contextEviction` and `contextRecall` records added at format v4 are specified in the working-set guide. |
-| `src/domains/share/` | Portable share archive bundles, manifest verification, import/export flows | [extensions-and-sharing.md](extensions-and-sharing.md) | `documented` | Share archives and portable bundle formats documented in extensions guide. |
-| `src/domains/webhook/` | Empty directory | None (Inert) | `inert` | Directory contains no active modules or exports in v0.4.0. |
-
-## Cross-Cutting Reference Guides
-
-In addition to source subsystem mappings, the documentation set includes cross-cutting contracts:
-
-1. [artifact-versions.md](artifact-versions.md): Canonical version registry and migration contract for all 9 serialized artifact schemas across Clio Coder.
-2. [glossary.md](glossary.md): Formal definitions of 45 core architectural concepts mapped to their TypeScript types in `src/`.
-3. [troubleshooting.md](troubleshooting.md): Comprehensive diagnostic and remediation guide keyed by exact user-facing error strings.