@tech-leads-club/harness-toolkit 0.3.5 → 0.4.0

package/tools/doctor.ts

@@ -2,13 +2,14 @@ import { spawnSync } from "node:child_process";
 import { existsSync, lstatSync, readFileSync, readlinkSync, realpathSync } from "node:fs";
 import { homedir, platform as osPlatform } from "node:os";
 import { basename, delimiter, dirname, join } from "node:path";
-import { NPM_PACKAGE, runtimePathKind } from "../bin/tlc-cli.ts";
+import { runtimePathKind } from "../bin/tlc-cli.ts";
 import { findBunOnPath, writeRuntimeCache } from "../bin/tlc-exec.mjs";
 import { isCursorWired } from "../bin/write-user-hooks.mjs";
 import type { ProviderWiring } from "../src/contracts/index.ts";
 import { coreFacade } from "../src/core/index.ts";
 import { emitJson, takeJsonFlag } from "../src/platform/cli-output.ts";
 import {
+  launcherBinDir,
   projectConfigPath,
   projectStateDir,
   providerConfigDirs,
@@ -244,6 +245,69 @@ export function resolveOnPath(
   return null;
 }
 
+/**
+ * The operator's own rules: which apply, where each came from, and any that can never be satisfied here.
+ *
+ * why the tier is printed: two tiers apply together, so "why did this fire?" and "why did it not?" are both
+ * answered by knowing whether the rule came from this project or from the machine
+ * ([/decisions/ad-100.md](/decisions/ad-100.md)).
+ *
+ * invariant: silent when the capability is off, and silent when no rule is declared. A row about a mechanism
+ * nobody opted into is noise on every healthy install ([/decisions/ad-034.md](/decisions/ad-034.md)).
+ */
+export function checkRules(root: string): Check[] {
+  const policy = coreFacade.policy.loadPolicy(root);
+  // why the switch is not re-read here: `load` owns it, and a second copy of the same condition is a second
+  // thing to keep true ([/decisions/ad-100.md](/decisions/ad-100.md)).
+  const set = coreFacade.rules.load(root, policy.rules);
+  if (set.rules.length === 0 && set.disabled.length === 0 && set.errors.length === 0) {
+    return [];
+  }
+
+  const checks: Check[] = [];
+  if (set.rules.length > 0) {
+    checks.push({
+      level: "ok",
+      name: "operator rules",
+      detail: set.rules
+        .map((rule) => `${rule.name} (${rule.tier}) on ${rule.on.kind} → ${rule.otherwise}`)
+        .join("; "),
+    });
+  }
+
+  // why an `ok` row: switching a global off in one repository is a decision, not a fault. It is reported because
+  // an operator who forgot they did it would otherwise wonder why nothing fires.
+  if (set.disabled.length > 0) {
+    checks.push({
+      level: "ok",
+      name: "operator rules (off here)",
+      detail: set.disabled.map((rule) => rule.name).join(", "),
+    });
+  }
+
+  for (const error of set.errors) {
+    checks.push({
+      level: "fail",
+      name: `operator rule (${error.name})`,
+      detail: `${error.error} — the other rules still apply`,
+    });
+  }
+
+  /**
+   * hazard: a rule whose proof kind this project has never recorded reads as protection and enforces nothing an
+   * operator can satisfy. Saying so is factual; guessing at the host's capabilities would not be.
+   */
+  for (const entry of coreFacade.rules.unobservedKinds(set.rules, coreFacade.rules.observations(root))) {
+    checks.push({
+      level: "warn",
+      name: `operator rule (${entry.rule})`,
+      detail: `needs ${entry.kinds.join(", ")}, and no observation of that kind has been recorded in this project yet`,
+    });
+  }
+
+  return checks;
+}
+
 export function checkRuntimePaths(home: string, platform: NodeJS.Platform): Check[] {
   const launcher = join(home, "bin", "tlc-exec.mjs");
   const distSample = join(home, "dist", "stop.mjs");
@@ -262,7 +326,12 @@ export function checkRuntimePaths(home: string, platform: NodeJS.Platform): Chec
     {
       level: onPath === null ? "fail" : "ok",
       name: "CLI on PATH",
-      detail: onPath ?? `no \`tlc\` on PATH — npm i -g ${NPM_PACKAGE}, or \`npm link\` from a clone`,
+      // hazard: this said "npm i -g <package>" — advice an operator who had just done exactly that could not act
+      // on. npm's shim lives in the bin directory of whichever Node version npm ran under, and leaves PATH the
+      // moment a version manager switches ([/decisions/ad-101.md](/decisions/ad-101.md)).
+      detail:
+        onPath ??
+        `no \`tlc\` on PATH — link it: ln -s ${join(home, "bin", "tlc")} ${join(launcherBinDir(), "tlc")} (or re-run \`tlc harness install\`, which does it)`,
     },
   ];
 }
@@ -470,6 +539,94 @@ export function checkSubagentAllowlist(root: string): Check[] {
   ];
 }
 
+/**
+ * What the operator cannot otherwise find out: how many of their lessons actually reach the model.
+ *
+ * hazard: the char budget drops lessons, and the only place that said so was the injected block itself — text the
+ * model reads and the operator never sees. `lessons list` answers a different question (`not-injected` is about
+ * grading history, not about the budget), and `status` does not answer it at all. So an operator with six lessons
+ * and a 900-char budget saw six healthy lessons and had four that never left the file
+ * ([/decisions/ad-100.md](/decisions/ad-100.md)).
+ *
+ * why the real selector rather than a size sum: pinning, staleness, validity windows and the mode all bind before
+ * the budget does. Re-deriving the arithmetic here would be a second answer that drifts from the first.
+ */
+/**
+ * Which keys this project restates instead of deciding.
+ *
+ * hazard: the layers are `DEFAULTS < user < project`, and `init` writes the whole default policy when there is no
+ * config yet while the wizard writes every knob it collected. So a project config typically names dozens of values
+ * it did not choose — and each one shadows the machine-wide tier for ever. An operator who raises
+ * `maxCharsSession` once, on the machine, sees no change in any repository that restated the old number, and
+ * nothing said why ([/decisions/ad-100.md](/decisions/ad-100.md)).
+ *
+ * invariant: a warning, never a failure. Restating a value is legitimate — pinning a project to a number on
+ * purpose is a real intent. What is not legitimate is not knowing.
+ */
+export function checkShadowedPolicy(root: string): Check[] {
+  const project = coreFacade.capability.readProjectPolicyRaw(root);
+  if (!project) {
+    return [];
+  }
+  const shadowed = coreFacade.policy.shadowedKeys(project, coreFacade.policy.resolvedWithoutProjectTier());
+  if (shadowed.length === 0) {
+    return [];
+  }
+  const shown = shadowed.slice(0, 6).map((key) => key.path);
+  const rest = shadowed.length - shown.length;
+  return [
+    {
+      level: "warn",
+      name: "project policy restates lower tiers",
+      detail: `${plural(shadowed.length, "key")} in this project's config name the value ${shadowed.length === 1 ? "it" : "they"} would already have: ${shown.join(", ")}${rest > 0 ? `, and ${rest} more` : ""}. Each one stops tracking ${join(runtimeHome(), "config.json")}, so a machine-wide change will not reach this repository. Delete what this project did not decide.`,
+    },
+  ];
+}
+
+export function checkLessonBudget(root: string): Check[] {
+  const policy = coreFacade.policy.loadPolicy(root);
+  const config = policy.intelligence.lessons;
+  if (!config.enabled) {
+    return [];
+  }
+  const selected = coreFacade.lesson.previewLessonSelection({ projectDir: root, config, mode: "session" });
+  const reaching = selected.lessons.length;
+  if (selected.omitted === 0) {
+    return reaching === 0
+      ? []
+      : [
+          {
+            level: "ok",
+            name: "lesson budget",
+            detail: `every eligible lesson reaches the model at session start (${plural(reaching, "lesson")}, maxCharsSession ${config.maxCharsSession})`,
+          },
+        ];
+  }
+  const chars = selected.lessons.reduce(
+    (total, lesson) => total + coreFacade.lesson.renderLessonBlock(lesson).length,
+    0,
+  );
+  const hogs = selected.lessons
+    .filter((lesson) => lesson.pinned)
+    .map((lesson) => `${lesson.id} (pinned, ${coreFacade.lesson.renderLessonBlock(lesson).length} chars)`);
+  return [
+    {
+      level: "warn",
+      name: "lesson budget",
+      detail: [
+        // hazard: this read "4 eligible lessons never reaches". `plural` handles the noun and the verb still has to
+        // agree — the same slip the unproven row already carries a note about.
+        `${plural(selected.omitted, "eligible lesson")} ${selected.omitted === 1 ? "never reaches" : "never reach"} the model at session start:`,
+        `${reaching} of ${reaching + selected.omitted} fit in maxCharsSession ${config.maxCharsSession} (${chars} used).`,
+        hogs.length > 0 ? `Pinned lessons go first and take the room: ${hogs.join(", ")}.` : "",
+        "Raise intelligence.lessons.maxCharsSession, shorten a lesson, or unpin one. Run: tlc harness lessons list",
+      ]
+        .filter(Boolean)
+        .join(" "),
+    },
+  ];
+}
+
 export function checkLessonHealth(root: string): Check[] {
   const policy = coreFacade.policy.loadPolicy(root);
   if (!policy.intelligence.lessons.enabled) {
@@ -597,6 +754,8 @@ export function checkProjectPolicy(root: string): Check[] {
     checkPosture(root),
     ...checkObservedRails(root),
     ...checkLessonHealth(root),
+    ...checkLessonBudget(root),
+    ...checkShadowedPolicy(root),
     ...checkSubagentAllowlist(root),
     ...checkPolicyDivergence(root),
     ...checkGateScope(root),
@@ -643,6 +802,7 @@ export function runChecks(ctx: DoctorContext): Check[] {
     ...checkProjectPolicy(ctx.root),
     ...checkCapabilities(ctx.root, ctx.runtimeHome),
     ...checkPrices(),
+    ...checkRules(ctx.root),
     checkGlobalCommands(ctx.home),
   ];
 }

package/tools/help-topic.ts

@@ -5,22 +5,34 @@ import { runtimeHome } from "../src/platform/paths.ts";
 const docsDir = join(runtimeHome(), "docs");
 const topic = (process.argv[2] ?? "").toLowerCase();
 
-const TOPICS: Record<string, string> = {
-  architecture: "architecture.md",
-  concepts: "concepts.md",
-  measure: "measure.md",
-  metrics: "measure.md",
-  prices: "measure.md",
-  price: "measure.md",
-  cost: "measure.md",
-  costs: "measure.md",
-  diagnose: "diagnose.md",
-  doctor: "diagnose.md",
-  debug: "diagnose.md",
-  init: "init.md",
-  setup: "init.md",
-  lessons: "lessons.md",
-  lesson: "lessons.md",
+/**
+ * A topic is a document, or one heading inside one. `section` exists because two topics live inside a larger
+ * document and printing the whole of it would bury the answer.
+ */
+type Topic = { file: string; section?: string };
+
+const TOPICS: Record<string, Topic> = {
+  architecture: { file: "architecture.md" },
+  concepts: { file: "concepts.md" },
+  measure: { file: "measure.md" },
+  metrics: { file: "measure.md" },
+  prices: { file: "measure.md", section: "## Prices" },
+  price: { file: "measure.md", section: "## Prices" },
+  cost: { file: "measure.md", section: "## Prices" },
+  costs: { file: "measure.md", section: "## Prices" },
+  diagnose: { file: "diagnose.md" },
+  doctor: { file: "diagnose.md" },
+  debug: { file: "diagnose.md" },
+  init: { file: "init.md" },
+  setup: { file: "init.md" },
+  lessons: { file: "lessons.md" },
+  lesson: { file: "lessons.md" },
+  rules: { file: "concepts.md", section: "## operator rules" },
+  rule: { file: "concepts.md", section: "## operator rules" },
+  runtime: { file: "concepts.md", section: "## which runtime answers a hook" },
+  dev: { file: "concepts.md", section: "## which runtime answers a hook" },
+  settings: { file: "concepts.md", section: "## where a setting lives" },
+  config: { file: "concepts.md", section: "## where a setting lives" },
 };
 
 function printIndex(): void {
@@ -30,6 +42,9 @@ TOPICS
   tlc harness help architecture
   tlc harness help concepts
   tlc harness help lessons
+  tlc harness help rules
+  tlc harness help settings
+  tlc harness help runtime
   tlc harness help measure
   tlc harness help prices
   tlc harness help diagnose
@@ -49,25 +64,26 @@ if (!topic || topic === "help" || topic === "-h" || topic === "--help") {
   process.exit(0);
 }
 
-const file = TOPICS[topic];
-if (!file) {
+const entry = TOPICS[topic];
+if (!entry) {
   console.error(`unknown topic: ${topic}`);
   printIndex();
   process.exit(1);
 }
 
-const path = join(docsDir, file);
+const path = join(docsDir, entry.file);
 if (!existsSync(path)) {
   console.error(`missing doc: ${path}`);
   process.exit(1);
 }
 
 let body = readFileSync(path, "utf8");
-if (topic === "prices" || topic === "price" || topic === "cost" || topic === "costs") {
-  const marker = "## Prices";
-  const idx = body.indexOf(marker);
+if (entry.section) {
+  const idx = body.indexOf(entry.section);
+  // why the whole document when the heading is absent: an answer from the wrong version of a doc beats no answer,
+  // and the section check already runs in the gate.
   if (idx >= 0) {
-    body = `# Prices\n\n${body.slice(idx)}`;
+    body = body.slice(idx);
   }
 }
 

package/tools/init-project.ts

@@ -2,6 +2,7 @@ import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { dirname, join, sep } from "node:path";
 import { applyCursorWiring, renderCursorHooksDocument } from "../bin/write-user-hooks.mjs";
 import type { WiringEntry } from "../src/contracts/index.ts";
+import { coreFacade } from "../src/core/index.ts";
 import { DEFAULTS } from "../src/core/policy/policy.defaults.ts";
 import { claudeConfigDir, cursorConfigDir, projectConfigPath, runtimeHome } from "../src/platform/paths.ts";
 import { render, type Screen } from "../src/platform/screen.ts";
@@ -150,17 +151,37 @@ export function mergeGitignore(root: string): { text: string; changed: boolean }
   return { text: `${withoutTrailingBlank.join("\n").replace(/\n+$/, "")}\n`, changed: true };
 }
 
+/**
+ * hazard: this returned `DEFAULTS` whole, and the wizard's `--stdin-json` carried every knob it had collected. Both
+ * wrote values nobody chose, and each one shadows the machine tier for ever — raise a number there afterwards and
+ * no such project sees it. Measured on one repository: 29 keys restating the tiers below
+ * ([/decisions/ad-101.md](/decisions/ad-101.md)).
+ *
+ * invariant: pruning cannot change the effective policy, because a leaf is dropped only when the tiers below
+ * already resolve to it. An existing config is still returned untouched — rewriting an operator's file is not
+ * this command's business.
+ */
 export function resolvePolicy(root: string, flags: InitFlags, stdinText: string | null): unknown {
   if (flags.stdinJson && !flags.minimal) {
     if (!stdinText || stdinText.trim() === "") {
       throw new Error("stdin-json: empty stdin");
     }
-    return JSON.parse(stdinText);
+    return prune(JSON.parse(stdinText) as Record<string, unknown>);
   }
   if (!flags.minimal && !flags.stdinJson && existsSync(projectConfigPath(root))) {
     return JSON.parse(readFileSync(projectConfigPath(root), "utf8"));
   }
-  return DEFAULTS;
+  /**
+   * hazard: this returned `DEFAULTS`, and pruning it was not enough. Against a machine tier that enabled things,
+   * the shipped defaults *differ* — so a fresh project wrote `comments.enabled: false` and turned off, in that
+   * repository, a capability the operator had switched on for the machine. A project that has decided nothing must
+   * say nothing ([/decisions/ad-101.md](/decisions/ad-101.md)).
+   */
+  return { version: DEFAULTS.version };
+}
+
+function prune(policy: Record<string, unknown>): Record<string, unknown> {
+  return coreFacade.policy.pruneShadowed(policy, coreFacade.policy.resolvedWithoutProjectTier());
 }
 
 export type ProviderPresence = { cursor: boolean; claude: boolean };
@@ -197,10 +218,22 @@ export function buildPlan(
 
 export type ApplyOutcome = {
   configPath: string;
+  /** why reported: silence after keeping a file reads as having written it. */
+  configKept: boolean;
   cursor: { skipped: true } | { skipped: false; status: string; target: string };
   claude: { skipped: true } | { skipped: false; status: string; target: string };
 };
 
+/**
+ * why exported: the repository's convention is that text is built by a named function and printed by the caller,
+ * so what an operator reads can be asserted. Silence after keeping a file reads as having written it.
+ */
+export function configLine(outcome: ApplyOutcome): string {
+  return outcome.configKept
+    ? `kept ${outcome.configPath} — already configured; delete it to start over, or run the wizard to replace it`
+    : `wrote ${outcome.configPath}`;
+}
+
 export function applyPlan(
   root: string,
   flags: InitFlags,
@@ -209,8 +242,20 @@ export function applyPlan(
 ): ApplyOutcome {
   const policy = resolvePolicy(root, flags, stdinText);
   const configPath = projectConfigPath(root);
-  mkdirSync(dirname(configPath), { recursive: true });
-  writeFileSync(configPath, `${JSON.stringify(policy, null, 2)}\n`);
+  /**
+   * hazard: this wrote unconditionally. `init --minimal` on a configured project replaced the operator's file —
+   * with the whole default policy before, with a bare version marker after that changed. Both destroy choices
+   * nobody asked to undo, and neither said so ([/decisions/ad-101.md](/decisions/ad-101.md)).
+   *
+   * invariant: an existing config is replaced only when the operator supplied one to replace it with. That is what
+   * `--stdin-json` is — the wizard's collected answers — and it is the one route that carries consent. Everything
+   * else keeps the file. This is the rule `linkDir` already follows: a real file at the target is somebody's work.
+   */
+  const kept = existsSync(configPath) && !flags.stdinJson;
+  if (!kept) {
+    mkdirSync(dirname(configPath), { recursive: true });
+    writeFileSync(configPath, `${JSON.stringify(policy, null, 2)}\n`);
+  }
 
   const launcher = launcherPath();
 
@@ -242,7 +287,7 @@ export function applyPlan(
   const gitignore = mergeGitignore(root);
   writeFileSync(join(root, ".gitignore"), gitignore.text);
 
-  return { configPath, cursor, claude };
+  return { configPath, configKept: kept, cursor, claude };
 }
 
 async function readStdin(): Promise<string> {
@@ -270,7 +315,7 @@ export async function main(argv: string[]): Promise<void> {
   }
 
   const outcome = applyPlan(root, flags, presence, stdinText);
-  console.log(`wrote ${outcome.configPath}`);
+  console.log(configLine(outcome));
   if (outcome.cursor.skipped) {
     console.log("init: cursor not installed — skipped project hooks.json");
   } else {

package/tools/install-runtime.ts

@@ -1,5 +1,5 @@
 import { spawnSync } from "node:child_process";
-import { cpSync, existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { cpSync, existsSync, mkdirSync, readFileSync, realpathSync, rmSync, writeFileSync } from "node:fs";
 import { join, relative, resolve, sep } from "node:path";
 import { NPM_MARKER, NPM_PACKAGE, wireRuntime } from "../bin/tlc-cli.ts";
 import { linkDir } from "../src/platform/links.ts";
@@ -71,8 +71,29 @@ export function originRoot(env: NodeJS.ProcessEnv = process.env): string {
   return home && home.length > 0 ? resolve(home) : conventionalRuntimeHome();
 }
 
+/**
+ * hazard: this compared `resolve(source)` with `resolve(dest)`, and `resolve` does not follow a symlink. An
+ * operator who installed with `--link` has a runtime home that *is* a link to their checkout, so the two paths
+ * differed lexically while naming the same directory — the in-place guard missed, `rmSync` followed the link, and
+ * the first entry of the payload deleted the checkout's own `bin/` before `cpSync` failed on the source it had
+ * just removed. Measured on this repository: the gate ate its own `bin/` ([/decisions/ad-100.md](/decisions/ad-100.md)).
+ *
+ * why the fallback: a destination that does not exist yet has no real path, and a first install is exactly that
+ * case. Then the lexical answer is the only one there is, and it is correct — nothing is there to alias.
+ */
+function samePlace(a: string, b: string): boolean {
+  const real = (path: string): string => {
+    try {
+      return realpathSync(path);
+    } catch {
+      return resolve(path);
+    }
+  };
+  return real(a) === real(b);
+}
+
 export function installRuntime(source: string, dest: string): InstallReport {
-  if (resolve(source) === resolve(dest)) {
+  if (samePlace(source, dest)) {
     // why: the git route already has the code at the destination. Copying a directory onto itself is the one
     // input that turns a sync into data loss.
     return { kind: "in-place", source, dest, entries: [], missing: [] };

package/tools/lessons-cli.ts

@@ -159,7 +159,10 @@ export function listScreen(report: LessonsListReport): Screen {
         },
         { label: "notes", value: notes.join("  ") },
       ],
-      lines: ["", row.instruction.slice(0, 160)],
+      // why the whole instruction: it is the operator's own text, and a slice with no marker is how 103
+      // characters of a 263-character lesson vanished mid-word ([/decisions/ad-101.md](/decisions/ad-101.md)).
+      lines: ["", row.instruction],
+      wrap: true,
     });
   }
 

package/tools/refresh-model-prices.ts

@@ -2,7 +2,7 @@
 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 { machineHome } from "../src/platform/paths.ts";
 import {
   cataloguePath,
   FALLBACK_PLANE,
@@ -23,7 +23,7 @@ import {
  *
  * invariant: written where it is read. One resolution, `runtimeHome()`, used by both sides.
  */
-const HARNESS_HOME = runtimeHome();
+const HARNESS_HOME = machineHome();
 
 /**
  * The plane a provider's own rates land in. It is the provider's id, because the catalogue is keyed by who bills

package/tools/uninstall-runtime.ts

@@ -12,7 +12,13 @@ import {
 import { homedir } from "node:os";
 import { basename, dirname, isAbsolute, join, relative, resolve } from "node:path";
 import { NPM_MARKER, NPM_PACKAGE } from "../bin/tlc-cli.ts";
-import { claudeConfigDir, cursorConfigDir, runtimeHome } from "../src/platform/paths.ts";
+import {
+  claudeConfigDir,
+  cursorConfigDir,
+  launcherBinDir,
+  launcherNames,
+  runtimeHome,
+} from "../src/platform/paths.ts";
 import { type Row, render, type Screen } from "../src/platform/screen.ts";
 import { createStyle, PLAIN, type Style } from "../src/platform/style.ts";
 import { removeClaudeWiring, unmergeClaudeSettings } from "../src/providers/claude/claude.wiring.ts";
@@ -57,10 +63,12 @@ export type UninstallTargets = {
  */
 export function uninstallTargets(env: NodeJS.ProcessEnv = process.env): UninstallTargets {
   const userHome = homedir();
-  const binDir = env.TLC_BIN_DIR?.trim() || join(userHome, ".local", "bin");
+  // invariant: the same definition install links into, so what one creates the other removes
+  // ([/decisions/ad-101.md](/decisions/ad-101.md)).
+  const binDir = launcherBinDir(env);
   return {
     home: runtimeHome(env),
-    binLinks: [join(binDir, "tlc"), join(binDir, "tlc.cmd")],
+    binLinks: launcherNames().map((name) => join(binDir, name)),
     claudeSettings: join(claudeConfigDir(), "settings.json"),
     cursorHooks: join(cursorConfigDir(), "hooks.json"),
     skillLinks: [