@tech-leads-club/harness-toolkit 0.2.1 → 0.3.0

package/tools/refresh-model-prices.ts

@@ -1,35 +1,97 @@
 #!/usr/bin/env node
-import { writeFileSync } from "node:fs";
-import { dirname, join } from "node:path";
-import { fileURLToPath } from "node:url";
+import { existsSync, mkdirSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { basename, join } from "node:path";
+import { coreFacade } from "../src/core/index.ts";
+import { runtimeHome } from "../src/platform/paths.ts";
+import {
+  cataloguePath,
+  FALLBACK_PLANE,
+  loadCatalogue,
+  type ModelPriceEntry,
+  overridesPath,
+  type PriceCatalogue,
+  type PriceTable,
+  slugifyModelName,
+} from "../src/platform/pricing.ts";
 
-const HARNESS_HOME = join(dirname(fileURLToPath(import.meta.url)), "..");
-const CURSOR_DOCS_URL = "https://cursor.com/docs/models-and-pricing.md";
+/**
+ * hazard: this was `dirname(import.meta.url)/..` — the directory the script lives in. Under an npm install that is
+ * inside the package, which npm replaces wholesale on the next update, so the refresh wrote prices into a directory
+ * that would be deleted while `pricing.ts` read `runtimeHome()` and never received them. The same reason the
+ * runtime is materialised outside the package at all ([/decisions/ad-056.md](/decisions/ad-056.md),
+ * [/decisions/ad-096.md](/decisions/ad-096.md)).
+ *
+ * invariant: written where it is read. One resolution, `runtimeHome()`, used by both sides.
+ */
+const HARNESS_HOME = runtimeHome();
+
+/**
+ * The plane a provider's own rates land in. It is the provider's id, because the catalogue is keyed by who bills
+ * the call and a second provider publishing its own rates is a new plane, not a new file.
+ */
+const PROVIDER_PLANE = "cursor";
+const PROVIDER_DOCS_URL = "https://cursor.com/docs/models-and-pricing.md";
 const LITELLM_URL =
   "https://raw.githubusercontent.com/BerriAI/litellm/main/litellm/model_prices_and_context_window_backup.json";
 
-type PriceEntry = {
-  displayName?: string;
-  provider?: string;
-  promptPer1M?: number;
-  completionPer1M?: number;
-  cacheWritePer1M?: number;
-  cacheReadPer1M?: number;
-  pool?: "cursor_models" | "other_models" | "auto" | "unknown";
-  billing?: "metered" | "included" | "unknown";
-  contextWindow?: number;
-};
+/**
+ * The files this replaced. Left on disk they are stale duplicates of two planes and an alias table nothing reads,
+ * and the operator has no way to tell which one a price came from ([/decisions/ad-096.md](/decisions/ad-096.md)).
+ */
+const SUPERSEDED = [
+  `model-prices.${PROVIDER_PLANE}.json`,
+  "model-prices.litellm.json",
+  "model-aliases.json",
+] as const;
 
-function slugify(name: string): string {
-  return name
-    .trim()
-    .toLowerCase()
-    .replace(/\[([^\]]+)\]\([^)]+\)/g, "$1")
-    .replace(/\(.*?\)/g, "")
-    .replace(/[^a-z0-9.+]+/g, "-")
-    .replace(/^-+|-+$/g, "");
+/**
+ * hazard: `model-prices.json` used to be the operator's overrides table, and it is the name this now writes. An
+ * operator who had put their own rates in it would have had them replaced by the first refresh. A flat table with
+ * no `planes` key is that old file, so it is moved to where overrides are read from rather than overwritten.
+ */
+function adoptLegacyOverrides(quiet: boolean): void {
+  const path = cataloguePath();
+  if (!existsSync(path)) {
+    return;
+  }
+  const parsed = loadCatalogue();
+  const keys = Object.keys(parsed).filter((key) => key !== "_meta");
+  if (parsed.planes !== undefined || keys.length === 0) {
+    return;
+  }
+  if (existsSync(overridesPath())) {
+    console.error(
+      `refresh: ${basename(path)} holds ${keys.length} legacy entries and ${basename(overridesPath())} already exists — merge them by hand`,
+    );
+    return;
+  }
+  renameSync(path, overridesPath());
+  if (!quiet) {
+    console.log(`refresh: moved ${keys.length} local overrides → ${overridesPath()}`);
+  }
 }
 
+/** invariant: only the exact names this replaced, only inside the runtime home. Nothing else is removed. */
+function retireSupersededFiles(quiet: boolean): void {
+  for (const name of SUPERSEDED) {
+    const path = join(HARNESS_HOME, name);
+    if (!existsSync(path)) {
+      continue;
+    }
+    rmSync(path, { force: true });
+    if (!quiet) {
+      console.log(`refresh: removed superseded ${name}`);
+    }
+  }
+}
+
+/**
+ * invariant: the key a model is written under is computed by the same function the lookup uses. There were two
+ * copies of this and they disagreed about parentheses, which is what let a variant overwrite its base model and be
+ * read back at the wrong price ([/decisions/ad-096.md](/decisions/ad-096.md)).
+ */
+const slugify = slugifyModelName;
+
 function parseMoney(cell: string): number | undefined {
   const t = cell.trim();
   if (!t || t === "-" || t === "—" || t.toLowerCase() === "n/a") {
@@ -50,7 +112,7 @@ function stripCell(cell: string): string {
     .trim();
 }
 
-function inferPool(displayName: string, provider: string): PriceEntry["pool"] {
+export function inferPool(displayName: string, provider: string): ModelPriceEntry["pool"] {
   const n = displayName.toLowerCase();
   if (n === "auto cost" || n.startsWith("auto ")) {
     return "auto";
@@ -61,16 +123,24 @@ function inferPool(displayName: string, provider: string): PriceEntry["pool"] {
   return "other_models";
 }
 
-function parseCursorDocs(md: string): Record<string, PriceEntry> {
-  const out: Record<string, PriceEntry> = {};
+/**
+ * hazard: this used to `break` on the first line that is not a table row, so it read the FIRST table and stopped.
+ * The page now carries three: the provider's own models, then the rest. The parser went from 43 models to 3
+ * overnight and the only guard was `count === 0`, so a mutilated catalogue overwrote a good one and read as a
+ * successful refresh ([/decisions/ad-096.md](/decisions/ad-096.md)).
+ *
+ * invariant: every table on the page, and the header row of each resets the column expectation rather than ending
+ * the parse.
+ */
+export function parseCursorDocs(md: string): PriceTable {
+  const out: PriceTable = {};
   const lines = md.split("\n");
   let inTable = false;
 
   for (const line of lines) {
     if (!line.startsWith("|")) {
-      if (inTable) {
-        break;
-      }
+      // why: leaving a table is not the end of the document. The next one may be a few lines down.
+      inTable = false;
       continue;
     }
     const cells = line
@@ -125,15 +195,15 @@ type LiteLlmEntry = {
   litellm_provider?: string;
 };
 
-function parseLiteLlm(raw: Record<string, LiteLlmEntry>): Record<string, PriceEntry> {
-  const out: Record<string, PriceEntry> = {};
+export function parseLiteLlm(raw: Record<string, LiteLlmEntry>): PriceTable {
+  const out: PriceTable = {};
   for (const [id, entry] of Object.entries(raw)) {
     if (id === "sample_spec") {
       continue;
     }
     const contextWindow =
       typeof entry.max_input_tokens === "number" ? entry.max_input_tokens : entry.max_tokens;
-    const compact: PriceEntry = {
+    const compact: ModelPriceEntry = {
       displayName: id,
       provider: entry.litellm_provider,
       pool: "unknown",
@@ -163,48 +233,145 @@ function parseLiteLlm(raw: Record<string, LiteLlmEntry>): Record<string, PriceEn
   return out;
 }
 
-const mode = (process.argv[2] ?? "all").toLowerCase();
-
-if (mode === "all" || mode === "cursor") {
-  const res = await fetch(CURSOR_DOCS_URL);
-  if (!res.ok) {
-    console.error(`Failed to fetch Cursor docs: ${res.status}`);
-    process.exit(1);
-  }
-  const md = await res.text();
-  const cursor = parseCursorDocs(md);
-  const count = Object.keys(cursor).length;
-  if (count === 0) {
-    console.error("Parsed 0 Cursor models — docs table format may have changed");
-    process.exit(1);
-  }
-  const path = join(HARNESS_HOME, "model-prices.cursor.json");
-  writeFileSync(
-    path,
-    `${JSON.stringify({ _meta: { source: CURSOR_DOCS_URL, refreshedAt: new Date().toISOString() }, ...cursor }, null, 2)}\n`,
-  );
-  console.log(`Cursor catalog: ${count} models → ${path}`);
+/**
+ * Which planes a refresh may write, and what happens when one of them comes back mutilated.
+ *
+ * invariant: a plane is replaced only if the incoming table is not a large loss against what is already there, and
+ * a refused plane leaves the others alone. One bad fetch must not take a good catalogue down with it
+ * ([/decisions/ad-096.md](/decisions/ad-096.md)).
+ */
+export type PlaneUpdate = { plane: string; source: string; table: PriceTable };
+export type PlaneOutcome = { plane: string; accepted: boolean; reason: string; count: number };
+
+function planeCount(catalogue: PriceCatalogue, plane: string): number {
+  return Object.keys(catalogue.planes?.[plane] ?? {}).length;
+}
+
+export function applyPlanes(
+  existing: PriceCatalogue,
+  updates: readonly PlaneUpdate[],
+  now: Date,
+): { catalogue: PriceCatalogue; outcomes: PlaneOutcome[] } {
+  const planes: Record<string, PriceTable> = { ...(existing.planes ?? {}) };
+  const planeMeta = { ...(existing._meta?.planes ?? {}) };
+  const outcomes: PlaneOutcome[] = [];
+  let accepted = 0;
+
+  for (const update of updates) {
+    const count = Object.keys(update.table).length;
+    const verdict = coreFacade.pricing.mayReplace(planeCount(existing, update.plane), count);
+    outcomes.push({ plane: update.plane, accepted: verdict.replace, reason: verdict.reason, count });
+    if (!verdict.replace) {
+      continue;
+    }
+    planes[update.plane] = update.table;
+    planeMeta[update.plane] = { source: update.source, count, refreshedAt: now.toISOString() };
+    accepted += 1;
+  }
+
+  // invariant: the file's own date moves only when something in it actually changed, so a refused refresh stays
+  // visibly stale rather than looking fresh.
+  const refreshedAt = accepted > 0 ? now.toISOString() : existing._meta?.refreshedAt;
+  return {
+    catalogue: { _meta: { ...(refreshedAt ? { refreshedAt } : {}), planes: planeMeta }, planes },
+    outcomes,
+  };
+}
+
+/**
+ * hazard: this file used to run its fetches at module scope, so importing it to test the parsers would have hit the
+ * network. `parseCursorDocs` and the key function were therefore untested — and both carried a defect that reached
+ * the catalogue ([/decisions/ad-096.md](/decisions/ad-096.md)).
+ */
+async function main(): Promise<void> {
+  const mode = (process.argv[2] ?? "all").toLowerCase();
+  const ifStale = process.argv.includes("--if-stale");
+  const quiet = process.argv.includes("--quiet");
+
+  const path = cataloguePath();
+
+  /**
+   * why: `--if-stale` is what makes an automatic refresh safe to wire into `install` and `update`. Without it both
+   * would reach the network on every run; with it the common case is one file read.
+   *
+   * invariant: the freshness decision is the core's and takes the clock as a parameter, and it is per plane —
+   * the provider's page changes far more often than the vendor list.
+   */
+  function wanted(plane: string, label: string): boolean {
+    if (!ifStale) {
+      return true;
+    }
+    const meta = existing._meta?.planes?.[plane];
+    const state = coreFacade.pricing.freshness(
+      existing.planes?.[plane] === undefined ? null : (meta ?? {}),
+      new Date(),
+    );
+    if (coreFacade.pricing.shouldRefetch(state)) {
+      return true;
+    }
+    if (!quiet) {
+      console.log(`${coreFacade.pricing.freshnessMessage(state, label)} — not refetching`);
+    }
+    return false;
+  }
+
+  // why: the directory may not exist yet on a first install, and writing into a missing one is the failure this
+  // avoids rather than reports.
+  mkdirSync(HARNESS_HOME, { recursive: true });
+  // invariant: the legacy overrides move out before the catalogue is read, so nothing of the old file's shape —
+  // its entries or its date — is carried into the new one.
+  adoptLegacyOverrides(quiet);
+  const existing = loadCatalogue();
+
+  const updates: PlaneUpdate[] = [];
+
+  if ((mode === "all" || mode === PROVIDER_PLANE) && wanted(PROVIDER_PLANE, `${PROVIDER_PLANE} prices`)) {
+    const res = await fetch(PROVIDER_DOCS_URL);
+    if (!res.ok) {
+      console.error(`refresh: provider docs answered ${res.status} — keeping the catalogue as it is`);
+      process.exit(1);
+    }
+    updates.push({
+      plane: PROVIDER_PLANE,
+      source: PROVIDER_DOCS_URL,
+      table: parseCursorDocs(await res.text()),
+    });
+  }
+
+  if ((mode === "all" || mode === FALLBACK_PLANE) && wanted(FALLBACK_PLANE, `${FALLBACK_PLANE} prices`)) {
+    const res = await fetch(LITELLM_URL);
+    if (!res.ok) {
+      console.error(`refresh: ${FALLBACK_PLANE} answered ${res.status} — keeping the catalogue as it is`);
+      process.exit(1);
+    }
+    updates.push({
+      plane: FALLBACK_PLANE,
+      source: LITELLM_URL,
+      table: parseLiteLlm((await res.json()) as Record<string, LiteLlmEntry>),
+    });
+  }
+
+  if (updates.length === 0) {
+    return;
+  }
+
+  const { catalogue, outcomes } = applyPlanes(existing, updates, new Date());
+  const refused = outcomes.filter((outcome) => !outcome.accepted);
+  if (outcomes.some((outcome) => outcome.accepted)) {
+    writeFileSync(path, `${JSON.stringify(catalogue)}\n`);
+    for (const outcome of outcomes.filter((o) => o.accepted)) {
+      console.log(`${outcome.plane}: ${outcome.count} models (${outcome.reason}) → ${path}`);
+    }
+    retireSupersededFiles(quiet);
+  }
+  for (const outcome of refused) {
+    console.error(`${outcome.plane}: ${outcome.reason}`);
+  }
+  if (refused.length > 0) {
+    process.exitCode = 1;
+  }
 }
 
-if (mode === "all" || mode === "litellm") {
-  const res = await fetch(LITELLM_URL);
-  if (!res.ok) {
-    console.error(`Failed to fetch LiteLLM prices: ${res.status}`);
-    process.exit(1);
-  }
-  const raw = (await res.json()) as Record<string, LiteLlmEntry>;
-  const litellm = parseLiteLlm(raw);
-  const path = join(HARNESS_HOME, "model-prices.litellm.json");
-  writeFileSync(
-    path,
-    `${JSON.stringify({
-      _meta: {
-        source: LITELLM_URL,
-        refreshedAt: new Date().toISOString(),
-        count: Object.keys(litellm).length,
-      },
-      ...litellm,
-    })}\n`,
-  );
-  console.log(`LiteLLM catalog: ${Object.keys(litellm).length} models → ${path}`);
+if (import.meta.main) {
+  await main();
 }

package/tools/uninstall-runtime.ts

@@ -37,36 +37,38 @@ export type UninstallPlan = {
 
 export type UninstallTargets = {
   home: string;
-  binLink: string;
+  binLinks: string[];
   claudeSettings: string;
   cursorHooks: string;
   skillLinks: string[];
 };
 
 /**
- * hazard: `install.ps1` does not write the same artefacts as `install.sh`. It resolves the home from
- * `USERPROFILE`, **copies** `tlc.cmd` into the bin directory instead of linking it, and puts one skill junction
- * at `~/.tlc/skills/harness-init` rather than one inside each provider's directory. Reading the POSIX layout on
- * Windows finds none of them and reports a clean machine ([/decisions/ad-066.md](/decisions/ad-066.md)).
+ * Everything an install may have left outside the runtime directory, on any machine.
+ *
+ * hazard: this used to read one layout per platform, chosen by `process.platform` — and the two installers wrote
+ * different layouts, so reading the POSIX one on Windows found none of them and reported a clean machine
+ * ([/decisions/ad-066.md](/decisions/ad-066.md)).
+ *
+ * why every name and not a branch: an uninstall has to clean up what is *there*, which includes what an older
+ * version put there. `tlc.cmd` does not exist on Linux and the legacy `~/.tlc/skills` junction does not exist on
+ * a machine installed after it was retired — an absent path is reported as nothing, so listing them all is both
+ * simpler and more complete than deciding ([/decisions/ad-097.md](/decisions/ad-097.md)).
  */
-export function uninstallTargets(
-  env: NodeJS.ProcessEnv = process.env,
-  platform: NodeJS.Platform = process.platform,
-): UninstallTargets {
-  const windows = platform === "win32";
-  const userHome = (windows ? env.USERPROFILE : env.HOME)?.trim() || homedir();
+export function uninstallTargets(env: NodeJS.ProcessEnv = process.env): UninstallTargets {
+  const userHome = homedir();
   const binDir = env.TLC_BIN_DIR?.trim() || join(userHome, ".local", "bin");
   return {
     home: runtimeHome(env),
-    binLink: join(binDir, windows ? "tlc.cmd" : "tlc"),
+    binLinks: [join(binDir, "tlc"), join(binDir, "tlc.cmd")],
     claudeSettings: join(claudeConfigDir(), "settings.json"),
     cursorHooks: join(cursorConfigDir(), "hooks.json"),
-    skillLinks: windows
-      ? [join(userHome, ".tlc", "skills", "harness-init")]
-      : [
-          join(claudeConfigDir(), "skills", "harness-init"),
-          join(cursorConfigDir(), "skills", "harness-init"),
-        ],
+    skillLinks: [
+      join(claudeConfigDir(), "skills", "harness-init"),
+      join(cursorConfigDir(), "skills", "harness-init"),
+      // the layout the PowerShell installer wrote: one junction no provider ever read
+      join(userHome, ".tlc", "skills", "harness-init"),
+    ],
   };
 }
 
@@ -312,7 +314,9 @@ export function planUninstall(targets: UninstallTargets, options: { purge?: bool
   for (const link of targets.skillLinks) {
     planLink(items, link, targets.home, "skill link", "location");
   }
-  planLink(items, targets.binLink, targets.home, "the tlc launcher on PATH", "target");
+  for (const link of targets.binLinks) {
+    planLink(items, link, targets.home, "the tlc launcher on PATH", "target");
+  }
   const homeIsLink = planRuntime(items, targets.home, purge);
   planManual(items, targets.home);
 

package/CHANGELOG.md

@@ -1,95 +0,0 @@
-# Changelog
-
-Generated from `docs/decisions/` — do not edit by hand. Run `node tools/render-changelog.ts`.
-
-Each entry is an architectural decision record: what changed, why, what was refused, and what it costs.
-A **Needs your action** line is a change `tlc harness doctor` cannot detect for you; everything else
-doctor reports against your own configuration.
-
-## Unreleased
-
-- **AD-001** — Optional parent-Fast sticky deny for Task spawns
-- **AD-002** — Provider-neutral naming and layout
-- **AD-003** — No backward compatibility
-- **AD-004** — Ports and adapters with an anti-corruption layer per provider
-- **AD-005** — Local test runner is the gate; CI matrix runs on every push
-- **AD-006** — Windows ships in scope, with CI covering the suite and the build
-- **AD-007** — Vendor check applies to core tests; absence checks do not
-- **AD-008** — Biome + TypeScript in the gate; @types/node pinned to the declared floor
-- **AD-009** — Event kinds are provider-agnostic; capabilities are data, not flags
-- **AD-010** — Shared vocabulary moves to src/contracts/
-- **AD-011** — Vendor-specific data belongs to the provider, not to core
-- **AD-012** — Prefer Bun at runtime, keep dist/ for the Node fallback, ship no binary
-- **AD-013** — Documentation follows the Open Knowledge Format (OKF v0.1)
-- **AD-014** — Claude Code hook payload field paths, pinned
-- **AD-015** — Wiring handler names are the entrypoint filenames
-- **AD-016** — Field semantics, state writers, and the core export surface
-- **AD-017** — The docs gate delegates to the project's tool, and the catalog is the only source of capability metadata
-- **AD-018** — Three rails adopted from an external review, each off by default and declared rather than inferred
-- **AD-019** — A resource is identified by what it resolves to, and a declared capability must be read where it matters
-- **AD-020** — One resolution for the install path, one source for posture, and a config that only advertises what it reads
-- **AD-021** — A gate command that never resolved is a config fault, and a recipe runner does not receive file arguments
-- **AD-022** — The policy surface is a floor rule, detection sits behind interception, and the operator/agent line is structural
-- **AD-023** — One finding per failure, and lesson relevance is recurrence rather than exposure
-- **AD-024** — The gate tells the truth about its own environment, its own lock, and the cause of a failure
-- **AD-025** — Posture governs surfacing only, and each posture has exactly one name
-- **AD-026** — An interruption is worth what it costs: narrower asks, a deadline on questions, and a rate the operator can see
-- **AD-027** — Evidence is ordered against the code, every rail's firing is recorded, and a checker can run with its rule off
-  - **Needs your action:** Re-run your verification after the last code change before citing the verdict — the ship gate now refuses evidence written before the code it certifies, so a claim that used to pass can block. Nothing in doctor can see this one; it shows up as a blocked stop.
-- **AD-028** — A resolved failure is kept, a session attests to itself, and provider neutrality becomes a proof
-- **AD-029** — A capability the init skill cannot correctly initialise is not shipped
-- **AD-030** — Clearing a policy divergence is one operator command behind four independent locks, and a refusal never points an agent at a door the floor holds shut
-- **AD-031** — The decisions are the changelog, a breaking change carries its own instruction, and looking never changes anything
-- **AD-032** — A hook is healthy when it can run, not when a marker string is present
-- **AD-033** — The gate says what it costs, appendFiles stops promising what it cannot deliver, and a dead capability leaves
-- **AD-034** — A warning that fires on a healthy install is not a warning, and the author reads the operator's output before anyone else does
-- **AD-035** — A lesson learned by reasoning can be written down, and the harness never learns where lessons come from
-- **AD-036** — A lesson names what makes it true, and stops being injected when that is gone
-- **AD-037** — A lesson can be true for a period, and an unparseable bound withholds it
-- **AD-038** — Promotion counts distinct sessions, because one stuck session is one observation
-- **AD-039** — A lesson is graded by the gate it was injected for, and unproven is not a passing reading
-- **AD-040** — Three lesson tiers, and nothing crosses between products by itself
-- **AD-041** — A member something reads and nothing writes fails the gate
-- **AD-042** — The suite gets an empty runtime home, and one renderer renders a lesson
-- **AD-043** — A standing rule is pinned, not ranked, and the budget says what it dropped
-- **AD-044** — Only an injection a gate could grade can be unproven
-- **AD-045** — A gate verdict is reused when the content hash of its inputs did not change
-- **AD-046** — The runtime path is an artifact, and update never touches what it does not own
-- **AD-047** — An instruction is not an affordance, and a refusal names the route that works
-- **AD-048** — A broken updater cannot deliver its own fix, so the installer is the recovery route
-- **AD-049** — An empty synced file says which of four reasons made it empty
-- **AD-050** — Lesson transport is a provider capability, not an operator preference
-- **AD-051** — A warning fails the gate, and a suppression states what breaks without it
-- **AD-052** — The repository moves to the org and the runtime paths do not
-- **AD-053** — The harness ships no model allowlist, and a list that names nothing enforces nothing
-- **AD-054** — npm is the distribution, and a merged release PR is the only thing that publishes
-- **AD-055** — The changelog is rendered from the decision records, and git says which release each landed in
-- **AD-056** — The package delivers the runtime, and the runtime path stays where hooks already point
-- **AD-057** — The release PR is a mechanism, not a gate, and the bot merges it
-- **AD-058** — Gates diff against the turn's base, and language knowledge is one table
-  - **Needs your action:** If a project has the comment gate on, expect it to start firing on turns that commit and on languages it never covered. Nothing changes in your config.
-- **AD-059** — A rail never writes a field it reads, and a counter reads the plane its events land on
-- **AD-060** — The gate records the environment it ran under, and names it only once the cheap explanations are spent
-- **AD-061** — A decision that refuses names its rule, and degrading preserves it
-- **AD-062** — One command answers whether the harness did that, and says so plainly when it did not
-- **AD-063** — One palette for human output, and a checker keeping it out of everything else
-- **AD-064** — A snapshot is assigned, never accumulated, and a table does not list what it cannot count
-- **AD-065** — The obs bus has a contract, and the gate checks both sides of it
-- **AD-066** — Uninstall reads the artefact, and the plan is the confirmation
-- **AD-067** — A reserved file that cannot be retired is rendered, and the gate holds it there
-- **AD-068** — A directory decides what ships, and dist is derived from disk in both directions
-- **AD-069** — A decision record declares its shape, and cites by link so a move cannot break it
-- **AD-070** — A comment has to read for somebody who was not in the session
-- **AD-071** — The turn's added lines are checked against the code the project already has
-- **AD-072** — A record can leave the corpus, and removing is a change worth recording
-- **AD-073** — A neighbour mid-gate is not a reason to block a turn
-- **AD-074** — Code the gate cannot read is refused, and a credential is not always a file
-- **AD-075** — A dependency a turn adds outlives the turn, so two mechanical failures are worth a stop
-- **AD-076** — Goal-hijack enforcement needs the tool's output, and the host does not deliver it
-- **AD-077** — A command that appears verbatim in fetched content is put to the operator
-- **AD-078** — The two files the harness reads aloud are sealed on write and verified on injection
-- **AD-079** — The coverage claim is a generated page with its gaps in it, not a badge in the README
-- **AD-080** — Every hand-written list of our own rules is now checked, including the one that drifted while writing this
-- **AD-081** — The manifest npm publishes is checked here, because the release runner was the only thing reading it
-- **AD-082** — npm is the documented install, and the first version cannot come from CI
-- **AD-083** — Going public switched the branch ruleset on, and an unattended release needs the App to bypass it

package/bin/tlc-build

@@ -1,80 +0,0 @@
-#!/usr/bin/env bash
-# Build Node-runnable ESM bundles under dist/. Requires Bun OR esbuild on PATH for compile.
-set -euo pipefail
-
-TLC_HOME="$(cd "$(dirname "$0")/.." && pwd)"
-DIST="$TLC_HOME/dist"
-mkdir -p "$DIST"
-
-# Derived from disk, never hardcoded: a fixed list silently stops building a new
-# entrypoint, and the missing bundle only surfaces when a hook fires in production.
-collect() {
-  local dir="$1"
-  local name
-  for path in "$dir"/*.ts; do
-    [ -e "$path" ] || continue
-    name="$(basename "$path" .ts)"
-    case "$name" in *.test) continue ;; esac
-    printf '%s\n' "$name"
-  done
-}
-
-# tools/dev/ holds the checks that validate THIS repository's own architecture, docs and conventions. They must
-# not ship — a user's clone has no src/core to validate and no docs/decisions of ours to render — and the
-# directory is the whole declaration: `collect` reads one level, so nothing under tools/dev is ever a bundle.
-# The list this replaced named four while ten qualified, and the six that were added later shipped for weeks.
-
-# macOS ships bash 3.2, which has no mapfile — read into arrays the portable way instead.
-ENTRYPOINTS=()
-while IFS= read -r name; do
-  [ -n "$name" ] && ENTRYPOINTS+=("$name")
-done < <(collect "$TLC_HOME/src/entrypoints")
-
-TOOLS=()
-while IFS= read -r name; do
-  [ -n "$name" ] && TOOLS+=("$name")
-done < <(collect "$TLC_HOME/tools")
-
-build_one() {
-  local src="$1"
-  local out="$2"
-  if command -v bun >/dev/null 2>&1; then
-    bun build --target=node --format=esm --outfile="$out" "$src"
-    return
-  fi
-  if command -v esbuild >/dev/null 2>&1; then
-    esbuild --bundle --platform=node --format=esm --outfile="$out" "$src"
-    return
-  fi
-  echo "tlc-build: need Bun or esbuild to compile TypeScript → dist/" >&2
-  echo "  Install Node.js 24+ (Active LTS) or 26 Current, then either Bun or: npm i -g esbuild" >&2
-  exit 1
-}
-
-echo "tlc-build → $DIST"
-for name in "${ENTRYPOINTS[@]}"; do
-  build_one "$TLC_HOME/src/entrypoints/${name}.ts" "$DIST/${name}.mjs"
-done
-for name in "${TOOLS[@]}"; do
-  build_one "$TLC_HOME/tools/${name}.ts" "$DIST/${name}.mjs"
-done
-
-build_one "$TLC_HOME/bin/tlc-cli.ts" "$DIST/tlc-cli.mjs"
-
-chmod +x "$TLC_HOME/bin/tlc" "$TLC_HOME/bin/tlc-exec" "$TLC_HOME/bin/tlc-build"
-
-# A bundle whose source moved or was deleted is not rebuilt, so it is also never diffed — it simply stays in
-# dist/ and ships. Deriving what to remove from the same disk that decides what to build closes that.
-for bundle in "$DIST"/*.mjs; do
-  [ -e "$bundle" ] || continue
-  name="$(basename "$bundle" .mjs)"
-  if [ "$name" = "tlc-cli" ] ||
-     [ -f "$TLC_HOME/src/entrypoints/${name}.ts" ] ||
-     [ -f "$TLC_HOME/tools/${name}.ts" ]; then
-    continue
-  fi
-  echo "tlc-build: pruning $name.mjs — no source"
-  rm -f "$bundle"
-done
-
-echo "tlc-build: ok ($(ls -1 "$DIST"/*.mjs | wc -l) bundles)"

package/bin/tlc-exec

@@ -1,10 +0,0 @@
-#!/usr/bin/env bash
-set -euo pipefail
-SOURCE="${BASH_SOURCE[0]:-$0}"
-while [[ -L "$SOURCE" ]]; do
-  DIR="$(cd "$(dirname "$SOURCE")" && pwd)"
-  SOURCE="$(readlink "$SOURCE")"
-  [[ "$SOURCE" != /* ]] && SOURCE="$DIR/$SOURCE"
-done
-BIN_DIR="$(cd "$(dirname "$SOURCE")" && pwd)"
-exec node "$BIN_DIR/tlc-exec.mjs" "$@"

package/bin/tlc-exec.cmd

@@ -1,4 +0,0 @@
-@echo off
-setlocal
-node "%~dp0tlc-exec.mjs" %*
-exit /b %ERRORLEVEL%

package/docs/decisions/ad-001.md

@@ -1,32 +0,0 @@
----
-type: Decision
-title: "AD-001 — Optional parent-Fast sticky deny for Task spawns"
-description: "subagents.blockParentFast denies Task/subagent spawns while the sticky parent model is Fast, closing a gap where Cursor Fast appears on the parent but not on the Task model string."
-tags: [decision, subagents, policy, cursor]
-timestamp: "2026-07-27"
----
-
-# AD-001 — Optional parent-Fast sticky deny for Task spawns
-
-- **status**: active
-- **date**: 2026-07-27
-
-## Decision
-
-`subagents.blockParentFast` (default `false`) denies Task / `subagentStart` when sticky parent state is
-Fast; bracket/`model_params` Fast is always treated as blocked in policy helpers.
-
-## Why
-
-Cursor Fast often appears on the parent (`*-fast` / `model_params.fast=true`) while Task `model` stays
-allowlisted without `-fast`. Without this rail, a Fast parent chat can still spawn full-price subagents.
-
-## Applies to
-
-- agent-harness hooks
-- harness-init capability 6b (see [/init.md](/init.md))
-
-## See also
-
-- [/decisions/ad-011.md](/decisions/ad-011.md) — provider model catalogs and blocked patterns
-- [/decisions/ad-016.md](/decisions/ad-016.md) — item 2 fixes the missing writer for this state