@iowarp/clio-coder 0.4.1 → 0.4.3

package/dist/upgrade-H7TOM7YL.js

@@ -1,323 +0,0 @@
-import { createRequire as __clioCreateRequire } from "node:module"; const require = __clioCreateRequire(import.meta.url);
-import {
-  listMigrations,
-  runPending
-} from "./chunk-6HMJX2VU.js";
-import {
-  readStateInfo
-} from "./chunk-QTFGO774.js";
-import "./chunk-AP73CFDC.js";
-import "./chunk-J5LZHVIT.js";
-import "./chunk-LCGCVYZ4.js";
-import "./chunk-NDDGJUXD.js";
-import "./chunk-QSNYB6ZV.js";
-import "./chunk-QDC3K2U3.js";
-import {
-  getVersionInfo
-} from "./chunk-XPLRXC72.js";
-import {
-  initializeClioHome
-} from "./chunk-7PWAODYW.js";
-import "./chunk-ZW55JB7N.js";
-import {
-  printError,
-  printHeader,
-  printOk
-} from "./chunk-VPKWYKEY.js";
-import "./chunk-5TSRNF4G.js";
-import "./chunk-EIMVLWB3.js";
-import "./chunk-D7E7WCDF.js";
-import "./chunk-EBY63B7G.js";
-import "./chunk-IWHMRKLL.js";
-import "./chunk-BWW4HLO4.js";
-import "./chunk-LL4KHSZI.js";
-import "./chunk-NLFAQR7Z.js";
-import "./chunk-WNP7O5WZ.js";
-import "./chunk-336NSSKI.js";
-import "./chunk-IKCO5N3L.js";
-import "./chunk-3I7MS7N2.js";
-import "./chunk-APJ265NV.js";
-import {
-  clioStateDir
-} from "./chunk-BYP5D4HI.js";
-import "./chunk-WEPFGWHJ.js";
-import "./chunk-YXLYO42X.js";
-import {
-  init_esm_shims
-} from "./chunk-3R73A4XB.js";
-
-// src/cli/upgrade.ts
-init_esm_shims();
-import { spawn } from "node:child_process";
-
-// src/domains/lifecycle/install-method.ts
-init_esm_shims();
-import { existsSync, readFileSync, realpathSync } from "node:fs";
-import { join, resolve, sep } from "node:path";
-var PACKAGE_NAME = "@iowarp/clio-coder";
-var DIST_CLI_SUFFIX = join("dist", "cli", "index.js");
-function detectInstallMethod(entryPath = process.argv[1]) {
-  const root = sourceCheckoutRoot(entryPath);
-  return root === null ? "npm" : "source";
-}
-function sourceCheckoutRoot(entryPath = process.argv[1]) {
-  if (!entryPath || entryPath.trim().length === 0) return null;
-  let entry;
-  try {
-    entry = realpathSync(resolve(entryPath));
-  } catch {
-    return null;
-  }
-  const suffix = sep + DIST_CLI_SUFFIX;
-  if (!entry.endsWith(suffix)) return null;
-  if (entry.split(sep).includes("node_modules")) return null;
-  const root = entry.slice(0, entry.length - suffix.length);
-  try {
-    const pkg = JSON.parse(readFileSync(join(root, "package.json"), "utf8"));
-    if (pkg.name !== PACKAGE_NAME) return null;
-  } catch {
-    return null;
-  }
-  const hasCheckoutMarker = existsSync(join(root, ".git")) || existsSync(join(root, "src", "cli", "index.ts"));
-  return hasCheckoutMarker ? root : null;
-}
-
-// src/cli/upgrade.ts
-var CHANNELS = ["latest", "beta", "dev"];
-var HELP = `clio-coder upgrade [--dry-run] [--channel=<latest|beta|dev>] [--skip-migrations]
-
-Refresh state metadata and apply pending data-dir migrations. An npm-installed
-binary is also reinstalled via npm; a source-checkout install instead prints
-the git-based update steps and never touches the global npm prefix.
-
-Flags:
-  --dry-run             print planned actions without changing anything
-  --channel=<chan>      npm dist-tag to install (latest|beta|dev). npm installs only.
-  --skip-migrations     skip migrations after the install step
-`;
-var SOURCE_UPGRADE_STEPS = ["git pull", "npm run install:local", "hash -r"];
-function printSourceUpgradeSteps() {
-  process.stdout.write("[upgrade] source checkout install: update the code with:\n");
-  for (const step of SOURCE_UPGRADE_STEPS) process.stdout.write(`  ${step}
-`);
-}
-function parseUpgradeArgs(argv) {
-  let dryRun = false;
-  let channel = "latest";
-  let skipMigrations = false;
-  let help = false;
-  let postInstall = false;
-  for (const arg of argv) {
-    if (arg === "upgrade") continue;
-    if (arg === "--help" || arg === "-h") {
-      help = true;
-      continue;
-    }
-    if (arg === "--dry-run") {
-      dryRun = true;
-      continue;
-    }
-    if (arg === "--skip-migrations") {
-      skipMigrations = true;
-      continue;
-    }
-    if (arg === "--post-install") {
-      postInstall = true;
-      continue;
-    }
-    if (arg.startsWith("--channel=")) {
-      const value = arg.slice("--channel=".length);
-      if (!CHANNELS.includes(value)) {
-        throw new Error(`--channel must be one of ${CHANNELS.join("|")}, got '${value}'`);
-      }
-      channel = value;
-      continue;
-    }
-    throw new Error(`unknown upgrade argument: ${arg}`);
-  }
-  return { dryRun, channel, skipMigrations, help, postInstall };
-}
-function streamPrefixed(source, sink) {
-  let buffered = "";
-  source.on("data", (chunk) => {
-    buffered += typeof chunk === "string" ? chunk : chunk.toString("utf8");
-    let idx = buffered.indexOf("\n");
-    while (idx !== -1) {
-      const line = buffered.slice(0, idx);
-      buffered = buffered.slice(idx + 1);
-      sink.write(line.startsWith("[upgrade] ") ? `${line}
-` : `[upgrade] ${line}
-`);
-      idx = buffered.indexOf("\n");
-    }
-  });
-  source.on("end", () => {
-    if (buffered.length > 0) sink.write(`[upgrade] ${buffered}
-`);
-  });
-}
-async function runNpmInstall(channel) {
-  const args = ["install", "-g", `@iowarp/clio-coder@${channel}`];
-  process.stdout.write(`[upgrade] npm ${args.join(" ")}
-`);
-  await new Promise((resolve2, reject) => {
-    const child = spawn("npm", args, { stdio: ["ignore", "pipe", "pipe"] });
-    streamPrefixed(child.stdout, process.stdout);
-    streamPrefixed(child.stderr, process.stderr);
-    child.on("error", reject);
-    child.on("exit", (code) => {
-      if (code === 0) resolve2();
-      else reject(new Error(`npm exited with code ${code ?? -1}`));
-    });
-  });
-}
-async function runDoctorFixAfterInstall() {
-  const args = ["doctor", "--fix"];
-  process.stdout.write(`[upgrade] clio-coder ${args.join(" ")}
-`);
-  await new Promise((resolve2, reject) => {
-    const child = spawn("clio-coder", args, { stdio: ["ignore", "pipe", "pipe"] });
-    streamPrefixed(child.stdout, process.stdout);
-    streamPrefixed(child.stderr, process.stderr);
-    child.on("error", reject);
-    child.on("exit", (code) => {
-      if (code === 0) resolve2();
-      else reject(new Error(`clio-coder doctor --fix exited with code ${code ?? -1}`));
-    });
-  });
-}
-async function runPostInstallUpgrade(opts) {
-  const args = ["upgrade", "--post-install", `--channel=${opts.channel}`];
-  if (opts.skipMigrations) args.push("--skip-migrations");
-  process.stdout.write(`[upgrade] clio-coder ${args.join(" ")}
-`);
-  await new Promise((resolve2, reject) => {
-    const child = spawn("clio-coder", args, { stdio: ["ignore", "pipe", "pipe"] });
-    streamPrefixed(child.stdout, process.stdout);
-    streamPrefixed(child.stderr, process.stderr);
-    child.on("error", reject);
-    child.on("exit", (code) => {
-      if (code === 0) resolve2();
-      else reject(new Error(`clio-coder upgrade --post-install exited with code ${code ?? -1}`));
-    });
-  });
-}
-async function runUpgradeCommand(argv) {
-  let opts;
-  try {
-    opts = parseUpgradeArgs(argv);
-  } catch (err) {
-    printError(err instanceof Error ? err.message : String(err));
-    return 2;
-  }
-  if (opts.help) {
-    process.stdout.write(HELP);
-    return 0;
-  }
-  const before = getVersionInfo().clio;
-  const stateDir = clioStateDir();
-  const method = detectInstallMethod();
-  printHeader("Clio Coder upgrade");
-  process.stdout.write(`install     ${method === "source" ? "source checkout" : "npm"}
-`);
-  if (method === "npm") process.stdout.write(`channel     ${opts.channel}
-`);
-  process.stdout.write(`current     ${before}
-`);
-  process.stdout.write(`state dir   ${stateDir}
-`);
-  const noNetwork = Boolean(process.env.CLIO_CODER_TEST_UPGRADE_NO_NETWORK);
-  const migrations = listMigrations();
-  const migrationIds = migrations.map((m) => m.id);
-  const recorded = readStateInfo()?.version ?? null;
-  const describeRefresh = () => recorded === null ? "state metadata (none recorded)" : recorded === before ? `state metadata (already ${before})` : `state metadata ${recorded} -> ${before}`;
-  if (opts.dryRun) {
-    if (method === "source") {
-      printSourceUpgradeSteps();
-    } else {
-      process.stdout.write(`[upgrade] would run: npm install -g @iowarp/clio-coder@${opts.channel}
-`);
-    }
-    if (opts.skipMigrations) {
-      process.stdout.write("[upgrade] would skip migrations (--skip-migrations)\n");
-    } else if (migrationIds.length === 0) {
-      process.stdout.write("[upgrade] no migrations registered; the manifest would be written as is\n");
-    } else {
-      process.stdout.write(`[upgrade] would consider ${migrationIds.length} migration(s):
-`);
-      for (const id of migrationIds) process.stdout.write(`  - ${id}
-`);
-    }
-    process.stdout.write(`[upgrade] would refresh ${describeRefresh()}
-`);
-    printOk("dry run complete, no changes made");
-    return 0;
-  }
-  if (opts.postInstall) {
-    process.stdout.write("[upgrade] running post-install checks with the active clio binary\n");
-  } else if (method === "source") {
-    process.stdout.write("[upgrade] source checkout install detected; skipping npm install\n");
-  } else if (noNetwork) {
-    process.stdout.write("[upgrade] CLIO_CODER_TEST_UPGRADE_NO_NETWORK set, skipping npm install\n");
-  } else {
-    try {
-      await runNpmInstall(opts.channel);
-    } catch (err) {
-      printError(err instanceof Error ? err.message : String(err));
-      return 1;
-    }
-    try {
-      await runPostInstallUpgrade(opts);
-      printOk(`${before} -> post-install checks complete`);
-      return 0;
-    } catch (err) {
-      printError(err instanceof Error ? err.message : String(err));
-      return 1;
-    }
-  }
-  let appliedCount = 0;
-  let appliedIds = [];
-  if (opts.skipMigrations) {
-    process.stdout.write("[upgrade] skipping migrations (--skip-migrations)\n");
-  } else {
-    let result;
-    try {
-      result = await runPending(stateDir);
-    } catch (err) {
-      printError(
-        `migration failed: ${err instanceof Error ? err.message : String(err)}`,
-        "the rest of the upgrade does not depend on it; run `clio-coder upgrade --skip-migrations` to continue, then fix the cause and re-run `clio-coder upgrade`."
-      );
-      return 1;
-    }
-    appliedIds = [...result.applied];
-    appliedCount = appliedIds.length;
-    if (appliedCount === 0) {
-      process.stdout.write("[upgrade] no pending migrations\n");
-    } else {
-      for (const id of appliedIds) process.stdout.write(`[upgrade] applied migration ${id}
-`);
-    }
-  }
-  if (method === "source" || noNetwork) {
-    const refresh = describeRefresh();
-    initializeClioHome();
-    process.stdout.write(`[upgrade] refreshed ${refresh}
-`);
-  } else {
-    try {
-      await runDoctorFixAfterInstall();
-    } catch (err) {
-      printError(err instanceof Error ? err.message : String(err));
-      return 1;
-    }
-  }
-  if (method === "source") printSourceUpgradeSteps();
-  const after = getVersionInfo().clio;
-  printOk(`${recorded ?? before} -> ${after} (migrations: ${appliedCount})`);
-  return 0;
-}
-export {
-  runUpgradeCommand
-};
-//# sourceMappingURL=upgrade-H7TOM7YL.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/development-pipeline.md

@@ -1,121 +0,0 @@
-# Development Pipeline
-
-How a change to Clio Coder moves from "we noticed something" to a published
-release. This is the process the maintainers follow and the process Clio
-herself follows when dogfooding: every stage is a marketplace skill, so any
-harness that loads the skills (Clio, Claude Code, Codex) runs the same
-pipeline. One-shot reactive prompting is the anti-pattern this page retires:
-work that is not traceable to an issue does not merge.
-
-## The lifecycle
-
-Three stages. A skill earns a stage only when it encodes repo policy a
-model cannot guess or an irreversibility gate a small model will skip
-under pressure; git mechanics alone never justify a stage.
-
-| Stage | Skill | Output |
-| --- | --- | --- |
-| 1. File | [`file-ticket`](../skills/git/file-ticket/) | A labeled GitHub issue with evidence and acceptance criteria |
-| 2. Fix | [`fix-issue`](../skills/git/fix-issue/) | An uncommitted, verified change where failing tests preceded the fix, self-reviewed against the issue's acceptance criteria |
-| 3. Ship | [`ship`](../skills/git/ship/) | An atomic conventional commit referencing the issue (`fixes #N`), a gated push, and an open PR; merge is a human decision |
-
-Releases follow [release-cut-checklist.md](release-cut-checklist.md) as a
-human-gated checklist, not a skill. Worktrees
-([`worktree-create`](../skills/git/worktree-create/),
-[`worktree-merge`](../skills/git/worktree-merge/)),
-[`resolve-merge-conflicts`](../skills/git/resolve-merge-conflicts/), and
-[`tdd`](../skills/coding/tdd/) are à-la-carte tools reached for when the
-situation calls for them, not stages every change passes through. An RCA
-written as the closing comment on the issue (`rca` label) is an artifact of
-hard bugs, not a mandatory toll booth. Batch ticket creation from a PRD
-bypasses stage 1 and uses [`backlog`](../skills/planning/backlog/)
-instead; everything downstream is identical.
-
-## Inheriting a Pi release
-
-Pi dependency upgrades use a fixed five-step review so that upstream fixes
-replace Clio copies without crossing the product boundary:
-
-1. Read the release notes or package changelogs for `pi-ai`, `pi-agent-core`,
-   and `pi-tui`.
-2. Run `npm run pi:surface-diff`. A changed or removed symbol that Clio imports
-   is an error; a new export is review input.
-3. Run `npm run ci`, then explicitly run the wire-capture fixtures and
-   `tests/smoke/tui-width-matrix.test.ts` from the
-   [Pi regression net](pi-boundary.md#pi-regression-net).
-4. Walk Pi's fixed-issue list against the
-   [Pi SDK boundary table](pi-boundary.md). For every fix in a surface Clio
-   still owns, either delete Clio's copy in favor of Pi or add a dated reason
-   for keeping the delta.
-5. Review the matching pi-coding-agent release diff for application features
-   worth a Clio ticket.
-
-After review, regenerate `docs/pi-surface.json` with
-`npm run pi:surface-snapshot`, inspect the symbol and signature changes, and
-commit the dependency pins, snapshot, boundary notes, and proving contracts
-together. `npm run lint` invokes the surface check automatically when the
-installed Pi versions differ from the checked-in snapshot.
-
-## Test lanes
-
-`npm test` runs `scripts/shard-tests.mjs`. Contract and smoke files are assigned
-deterministically to weighted parallel lanes, with timings from
-`scripts/shard-weights.json`; `--list` shows the assignment and `--shard <n>`
-reproduces one numbered lane. Tests whose assertion is itself sensitive to
-wall-clock scheduling live in the explicit serial set. The runner waits for all
-parallel lanes to drain, then runs that set alone with
-`CLIO_TEST_CONCURRENCY=1`. Reproduce it with:
-
-```bash
-node scripts/shard-tests.mjs --shard serial
-```
-
-Do not repair a timing-measurement failure by widening its product bound or by
-moving ordinary watchdog tests into the serial set. `tests/harness/load.ts`
-scales watchdogs by the parallel lane count; the serial lane is reserved for
-claims that cease to mean the same thing under contention.
-
-## Issue conventions
-
-- **Title**: conventional tag plus imperative summary (`fix: memory overlay
-  cannot scroll`), matching `.github/ISSUE_TEMPLATE/` prefixes.
-- **Body**: Problem, Reproduce, Evidence with `file:line` pointers,
-  Acceptance criteria as a verifiable checklist, Links.
-- **Labels**: exactly one type label (`bug`, `enhancement`,
-  `documentation`, `question`) plus applicable `area:*` labels.
-- **Milestone**: the open release milestone when the work is committed to
-  it; unassigned issues carry `needs-triage` until a human places them.
-
-### Label taxonomy
-
-| Kind | Labels | Meaning |
-| --- | --- | --- |
-| Type | `bug`, `enhancement`, `documentation`, `question` | What the issue is; exactly one |
-| Area | `area:tui`, `area:engine`, `area:memory`, `area:dispatch`, `area:skills`, `area:cli`, `area:api`, `area:docs` | Which subsystem; one or more |
-| Status | `needs-triage`, `rca`, `blocked` | Where in the lifecycle |
-| Community | `good first issue`, `help wanted`, `duplicate`, `invalid`, `wontfix` | GitHub defaults, unchanged |
-
-New `area:*` labels are proposed in an issue, not created ad hoc.
-
-## Milestones are releases
-
-Each open milestone is the next version (`v0.3.7`, `v0.4.0`). Triage means
-assigning an issue to a milestone or explicitly leaving it in the backlog.
-A release cut requires every issue in its milestone to be closed
-or bumped; the milestone closes when the tag is published.
-
-## Dogfooding setup
-
-The marketplace copy under `skills/git/` is the committed source of truth,
-pinned in `skills/registry.yaml` by `npm run skills:pin`. Runtime roots are
-gitignored, so each developer installs locally:
-
-```bash
-cp -r skills/git/file-ticket .clio-coder/skills/   # Clio Coder
-cp -r skills/git/file-ticket .claude/skills/       # Claude Code
-```
-
-The other pipeline skills are model-invoked from the marketplace catalog the
-same way. When a skill changes, re-run `npm run skills:pin` and re-copy;
-drift between an installed copy and the pinned hash surfaces a warning at
-activation.

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.