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

package/src/core/release/release.version.ts

@@ -0,0 +1,147 @@
+/**
+ * How a release tag is spelled.
+ *
+ * hazard: the changelog generator listed tags with the glob `v*` while every tag this repository has ever created
+ * is `harness-toolkit-v…`. It matched none, put all 88 decision records under `## Unreleased`, and passed its own
+ * `--check` because the generated document and the committed one were wrong in the same way. Three releases shipped
+ * with a changelog attributing nothing to any of them ([/decisions/ad-087.md](/decisions/ad-087.md)).
+ *
+ * invariant: derived from the package name, which is the same source `release-please-config.json` writes the tag
+ * from. A prefix written down twice is a prefix that drifts once.
+ */
+export function tagPrefixFor(packageName: string): string {
+  const unscoped = packageName.includes("/") ? (packageName.split("/").pop() ?? packageName) : packageName;
+  return `${unscoped}-v`;
+}
+
+export type SemVer = { major: number; minor: number; patch: number };
+
+export function parseVersion(text: string): SemVer | null {
+  const match = /^(\d+)\.(\d+)\.(\d+)$/.exec(text.trim());
+  if (match === null) {
+    return null;
+  }
+  return { major: Number(match[1]), minor: Number(match[2]), patch: Number(match[3]) };
+}
+
+/** The version inside a tag, or null when the tag belongs to another package or another scheme. */
+export function versionInTag(packageName: string, tag: string): string | null {
+  const prefix = tagPrefixFor(packageName);
+  if (!tag.startsWith(prefix)) {
+    return null;
+  }
+  const rest = tag.slice(prefix.length);
+  return parseVersion(rest) === null ? null : rest;
+}
+
+/**
+ * The version a set of commits earns, from Conventional Commit subjects.
+ *
+ * why: the release writes to `main` directly and publishes before it tags, so nothing assembles the bump in a pull
+ * request for a human to look at. The arithmetic therefore has to be a pure function with tests rather than a step
+ * inside somebody else's action ([/decisions/ad-087.md](/decisions/ad-087.md)).
+ */
+export type Bump = "major" | "minor" | "patch" | "none";
+
+export type Commit = {
+  /** The subject line, e.g. `fix(gate): …`. */
+  subject: string;
+  /** The body, where a `BREAKING CHANGE:` footer lives. */
+  body?: string;
+};
+
+const SUBJECT = /^(?<type>[a-z]+)(?:\((?<scope>[^)]*)\))?(?<breaking>!)?:\s*(?<rest>.+)$/;
+const BREAKING_FOOTER = /^BREAKING[ -]CHANGE:/m;
+
+/**
+ * invariant: `feat` and `fix` are the only types that release. Everything else — `docs`, `chore`, `refactor`,
+ * `test`, `ci`, `build`, `perf`, `style` — lands without moving the version. That is what stops the release's own
+ * commit from earning the next version and looping, which this pipeline did six times in nine minutes.
+ */
+export const MINOR_TYPES: ReadonlySet<string> = new Set(["feat"]);
+export const PATCH_TYPES: ReadonlySet<string> = new Set(["fix"]);
+
+/**
+ * invariant: a scope on this list never releases, whatever the type. `fix(ci)` and `fix(gate)` are repository
+ * plumbing that cannot reach anyone who installed the package — three versions were published for exactly that
+ * kind of work before this existed.
+ */
+export const INERT_SCOPES: ReadonlySet<string> = new Set(["ci", "gate", "release", "docs", "deps-dev"]);
+
+export function bumpFor(commit: Commit): Bump {
+  const match = SUBJECT.exec(commit.subject.trim());
+  if (match?.groups === undefined) {
+    return "none";
+  }
+  const { type, scope, breaking } = match.groups as { type: string; scope?: string; breaking?: string };
+  if (scope !== undefined && INERT_SCOPES.has(scope)) {
+    return "none";
+  }
+  if (breaking === "!" || BREAKING_FOOTER.test(commit.body ?? "")) {
+    return "major";
+  }
+  if (MINOR_TYPES.has(type)) {
+    return "minor";
+  }
+  return PATCH_TYPES.has(type) ? "patch" : "none";
+}
+
+const RANK: Record<Bump, number> = { none: 0, patch: 1, minor: 2, major: 3 };
+
+export function highestBump(commits: readonly Commit[]): Bump {
+  return commits.reduce<Bump>((best, commit) => {
+    const bump = bumpFor(commit);
+    return RANK[bump] > RANK[best] ? bump : best;
+  }, "none");
+}
+
+/**
+ * why: below 1.0.0 a breaking change takes the minor, not the major. Reaching 1.0.0 is a claim about stability that
+ * a commit message must not be able to make on its own.
+ *
+ * hazard: a feature still takes the minor below 1.0.0. Rebasing `feat` down to a patch is a *different* convention
+ * and this repository does not use it — the history says so: 0.1.0 went to 0.2.0 on a `feat:`. Implementing both at
+ * once would silently renumber every future feature.
+ */
+export function applyBump(current: SemVer, bump: Bump): SemVer {
+  if (bump === "none") {
+    return current;
+  }
+  const effective: Exclude<Bump, "none"> = current.major === 0 && bump === "major" ? "minor" : bump;
+  switch (effective) {
+    case "major":
+      return { major: current.major + 1, minor: 0, patch: 0 };
+    case "minor":
+      return { major: current.major, minor: current.minor + 1, patch: 0 };
+    default:
+      return { major: current.major, minor: current.minor, patch: current.patch + 1 };
+  }
+}
+
+export type VersionPlan = {
+  current: string;
+  next: string;
+  bump: Bump;
+  released: boolean;
+  /** The subjects that earned the bump, for the run's log. */
+  reasons: string[];
+};
+
+export function planVersion(currentVersion: string, commits: readonly Commit[]): VersionPlan {
+  const current = parseVersion(currentVersion);
+  if (current === null) {
+    throw new Error(`release: \`${currentVersion}\` is not a version this can bump`);
+  }
+  const bump = highestBump(commits);
+  return {
+    current: formatVersion(current),
+    next: formatVersion(applyBump(current, bump)),
+    bump,
+    released: bump !== "none",
+    reasons: commits.filter((commit) => bumpFor(commit) !== "none").map((commit) => commit.subject),
+  };
+}
+
+export function formatVersion(version: SemVer): string {
+  return `${version.major}.${version.minor}.${version.patch}`;
+}

package/src/core/shim/shim.precedence.ts

@@ -0,0 +1,72 @@
+/**
+ * Whether the project-level shim should stand down because a user-level hook already covers this event.
+ *
+ * hazard: this was `if (process.env.TLC_ACTIVE === "1")`, and nothing in the repository ever set `TLC_ACTIVE`.
+ * Four documents stated that the user-level `sessionStart` hook sets it; none could, because a hook cannot export
+ * an environment variable to a later hook process — the host's own documentation says there is no field that
+ * passes state between hook invocations. So the condition was never true, the shim never stood down, and both
+ * levels ran the handler on every overlapping event. Measured on one machine: eleven hook groups registered at
+ * user level, six at project level, six events overlapping, and the host merges rather than replaces — it
+ * deduplicates only byte-identical handlers, and these differ (`… tlc-exec.mjs shim stop` against
+ * `… tlc-exec.mjs stop`) ([/decisions/ad-095.md](/decisions/ad-095.md)).
+ *
+ * invariant: the answer is derived from what is on disk, not from what a previous process might have exported.
+ * Two hooks in the same event are separate processes with no channel between them, so the only thing they can
+ * agree on is a file both can read.
+ */
+
+export type HookEntry = { command?: string; args?: readonly string[] };
+export type HookMatcher = { hooks?: readonly HookEntry[] };
+export type ProviderSettings = { hooks?: Record<string, readonly HookMatcher[]> };
+
+/**
+ * why: the launcher's file name, not its full path. The user-level hook names the runtime home
+ * (`~/.tlc/harness/bin/tlc-exec.mjs`) and the project shim names wherever init resolved the runtime from — the
+ * paths differ by construction, so comparing them would never match. What identifies the harness is the launcher
+ * it runs and the handler it runs it with.
+ */
+export const LAUNCHER = "tlc-exec";
+
+export function invocationText(entry: HookEntry): string {
+  return [entry.command ?? "", ...(entry.args ?? [])].join(" ");
+}
+
+/**
+ * Does this settings document already run the harness for this handler?
+ *
+ * invariant: `shim` is not part of the comparison. The user-level hook runs `tlc-exec <handler>` and the project
+ * shim runs `tlc-exec shim <handler>` — the same handler reached two ways. Requiring the spellings to match is
+ * what made the host's own deduplication miss them.
+ */
+export function coversHandler(settings: ProviderSettings, handler: string): boolean {
+  for (const matchers of Object.values(settings.hooks ?? {})) {
+    for (const matcher of matchers) {
+      for (const entry of matcher.hooks ?? []) {
+        const text = invocationText(entry);
+        if (text.includes(LAUNCHER) && new RegExp(`(^|\\s)${handler}(\\s|$)`).test(text)) {
+          return true;
+        }
+      }
+    }
+  }
+  return false;
+}
+
+export type ShimDecision = { run: boolean; reason: string };
+
+/**
+ * why: `null` for the user-level settings means "there is no user-level install", which is the case the project
+ * shim exists for — a cloud agent with no user-level hooks runs the real handler through it
+ * (`docs/architecture.md`). Absence must therefore mean run, and only a positive match means stand down.
+ */
+export function decideShim(userSettings: ProviderSettings | null, handler: string): ShimDecision {
+  if (userSettings === null) {
+    return { run: true, reason: "no user-level settings — this shim is the only hook for this event" };
+  }
+  return coversHandler(userSettings, handler)
+    ? {
+        run: false,
+        reason: `a user-level hook already runs ${handler} — standing down to avoid a second run`,
+      }
+    : { run: true, reason: `no user-level hook runs ${handler}` };
+}

package/src/core/skill/skill.link.ts

@@ -0,0 +1,81 @@
+/**
+ * Where the init skill has to be linked, and what counts as a link that works.
+ *
+ * hazard: `install.sh` loops over every provider config directory that exists and links
+ * `<provider>/skills/harness-init`, with the comment "Each provider only reads its own skills directory".
+ * `tlc harness update` linked to `<runtime-home>/../skills/harness-init` instead — a directory no provider reads,
+ * and which did not exist at all on the machine where this was found. So an update never refreshed the skill
+ * anywhere a provider looks, and the evidence was a link left pointing into a `/tmp` recovery directory that does
+ * not survive a reboot ([/decisions/ad-095.md](/decisions/ad-095.md)).
+ *
+ * invariant: one function, used by both, so the two cannot disagree again.
+ */
+
+export const SKILL_NAME = "harness-init";
+
+export type SkillLink = { providerDir: string; source: string; target: string };
+
+/**
+ * why: the provider directories are given rather than resolved here. Both tools relocate their config directory by
+ * environment variable, and this repository is itself installed under a relocated one — so the caller resolves and
+ * this decides.
+ */
+export function skillLinks(
+  runtimeHome: string,
+  providerDirs: readonly string[],
+  present: (path: string) => boolean,
+) {
+  const source = `${runtimeHome}/skills/${SKILL_NAME}`;
+  return providerDirs
+    .filter((dir) => present(dir))
+    .map((providerDir) => ({
+      providerDir,
+      source,
+      target: `${providerDir}/skills/${SKILL_NAME}`,
+    }));
+}
+
+export type LinkHealth =
+  | { state: "ok"; target: string; resolved: string }
+  | { state: "dangling"; target: string; resolved: string }
+  | { state: "outside-runtime"; target: string; resolved: string }
+  | { state: "absent"; target: string };
+
+/**
+ * hazard: a link whose destination does not exist reads as installed to anything that only checks the link. The
+ * one found on the machine that prompted this pointed at `/tmp/tlc-recovery-…/install/skills/harness-init` — a
+ * directory from a recovery run, gone on the next boot, and invisible to every check the harness had.
+ *
+ * invariant: a link that resolves outside the runtime home is reported even when it currently exists, because
+ * a source that is not the runtime is a source that will move.
+ */
+export function linkHealth(
+  target: string,
+  runtimeHome: string,
+  probe: { linkTarget: (path: string) => string | null; exists: (path: string) => boolean },
+): LinkHealth {
+  const resolved = probe.linkTarget(target);
+  if (resolved === null) {
+    return { state: "absent", target };
+  }
+  if (!probe.exists(resolved)) {
+    return { state: "dangling", target, resolved };
+  }
+  const home = runtimeHome.replace(/\/+$/, "");
+  return resolved === home || resolved.startsWith(`${home}/`)
+    ? { state: "ok", target, resolved }
+    : { state: "outside-runtime", target, resolved };
+}
+
+export function linkHealthMessage(health: LinkHealth): string {
+  switch (health.state) {
+    case "ok":
+      return `linked → ${health.resolved}`;
+    case "dangling":
+      return `points at ${health.resolved}, which does not exist — re-run \`tlc harness install\``;
+    case "outside-runtime":
+      return `points at ${health.resolved}, outside the runtime — it will break when that path goes`;
+    default:
+      return "not linked — the provider cannot see the init skill";
+  }
+}

package/src/entrypoints/shim.ts

@@ -1,17 +1,49 @@
 import { spawn } from "node:child_process";
-import { existsSync } from "node:fs";
+import { existsSync, readFileSync } from "node:fs";
 import { join } from "node:path";
-import { runtimeHome } from "../platform/paths.ts";
+import { coreFacade, type ProviderSettings } from "../core/index.ts";
+import { runtimeHome, userSettingsPaths } from "../platform/paths.ts";
 
-const handler = process.argv[2];
-if (!handler) {
-  console.error("usage: shim <handler-name>");
-  process.exit(1);
+function requireHandler(): string {
+  const name = process.argv[2];
+  if (!name) {
+    console.error("usage: shim <handler-name>");
+    process.exit(1);
+  }
+  return name;
 }
 
-// hazard: a project-level hook and a user-level hook both fire for the same event. The user-level
-// session start sets TLC_ACTIVE, so the project shim stands down rather than double-firing.
-if (process.env.TLC_ACTIVE === "1") {
+const handler = requireHandler();
+
+/**
+ * hazard: a project-level hook and a user-level hook both fire for the same event, and the host merges the two
+ * rather than replacing one with the other. This used to read `TLC_ACTIVE`, which nothing ever set — a hook cannot
+ * export an environment variable to a later hook process, so the condition was never true and both levels ran the
+ * handler every time ([/decisions/ad-095.md](/decisions/ad-095.md)).
+ *
+ * invariant: read from disk, because two hooks in one event share no channel except the filesystem.
+ */
+// why: the first document that covers the handler wins, and a document that does not cover it must not stop the
+// next one being read — otherwise a user with only one editor installed globally would decide for both.
+function coveringSettings(): ProviderSettings | null {
+  let seen: ProviderSettings | null = null;
+  for (const path of userSettingsPaths()) {
+    let parsed: ProviderSettings;
+    try {
+      parsed = JSON.parse(readFileSync(path, "utf8")) as ProviderSettings;
+    } catch {
+      continue;
+    }
+    seen = parsed;
+    if (coreFacade.shim.coversHandler(parsed, handler)) {
+      return parsed;
+    }
+  }
+  return seen;
+}
+
+const decision = coreFacade.shim.decideShim(coveringSettings(), handler);
+if (!decision.run) {
   process.stdout.write("{}\n");
   process.exit(0);
 }

package/src/platform/fs-atomic.ts

@@ -88,20 +88,52 @@ function readJson<T>(path: string): T | null {
   }
 }
 
-async function withFileLock<T>(lockPath: string, fn: () => Promise<T>): Promise<T> {
+/**
+ * hazard: `EEXIST` is what a held lock looks like on POSIX and only sometimes on Windows. There, a concurrent
+ * `wx` open against a file another process is creating or unlinking answers `EPERM` — so the loop below threw
+ * instead of waiting, and the two-concurrent-writers test failed in Windows CI with
+ * `EPERM: operation not permitted, open '…\handoff.json.lock'`. This module already listed the codes that mean
+ * "busy, come back" for its rename; the lock, which is the one place contention is the expected case, did not
+ * consult them ([/decisions/ad-086.md](/decisions/ad-086.md)).
+ */
+function isContention(error: unknown): boolean {
+  return errorCode(error) === "EEXIST" || isRetryableFsError(error);
+}
+
+/**
+ * invariant: prefixed names. `FsAtomicOptions` already carries `attempts` and `sleep` for the rename retry, and
+ * `UpdateJsonAtomicOptions` is the intersection of both — sharing a name there would silently hand the lock's
+ * budget to the rename, or the other way round.
+ */
+export type FileLockOptions = {
+  /** Injected so the contention branch has a test that does not need a second process or Windows. */
+  openLock?: (path: string) => void;
+  lockSleep?: (ms: number) => Promise<void>;
+  lockAttempts?: number;
+};
+
+export async function withFileLock<T>(
+  lockPath: string,
+  fn: () => Promise<T>,
+  options: FileLockOptions = {},
+): Promise<T> {
+  const {
+    openLock = (path: string) => closeSync(openSync(path, "wx")),
+    lockSleep = (ms: number) => new Promise((resolve) => setTimeout(resolve, ms)),
+    lockAttempts = 200,
+  } = options;
   mkdirSync(dirname(lockPath), { recursive: true });
-  const attempts = 200;
   let acquired = false;
-  for (let attempt = 0; attempt < attempts; attempt++) {
+  for (let attempt = 0; attempt < lockAttempts; attempt++) {
     try {
-      closeSync(openSync(lockPath, "wx"));
+      openLock(lockPath);
       acquired = true;
       break;
     } catch (error) {
-      if (errorCode(error) !== "EEXIST") {
+      if (!isContention(error)) {
         throw error;
       }
-      await new Promise((resolve) => setTimeout(resolve, nextDelay({ attempt, baseMs: 10, capMs: 200 })));
+      await lockSleep(nextDelay({ attempt, baseMs: 10, capMs: 200 }));
     }
   }
   if (!acquired) {
@@ -116,27 +148,33 @@ async function withFileLock<T>(lockPath: string, fn: () => Promise<T>): Promise<
   }
 }
 
-export type UpdateJsonAtomicOptions = FsAtomicOptions & {
-  lockPath: string /**
-   * Run inside the write lock, after the file lands. The platform does not care what it does — recording a
-   * content hash is core's business, and doing it here is what makes the record and the content one write.
-   */;
-  afterWrite?: (path: string) => void;
-};
+export type UpdateJsonAtomicOptions = FsAtomicOptions &
+  FileLockOptions & {
+    lockPath: string;
+    /**
+     * Run inside the write lock, after the file lands. The platform does not care what it does — recording a
+     * content hash is core's business, and doing it here is what makes the record and the content one write.
+     */
+    afterWrite?: (path: string) => void;
+  };
 
 export async function updateJsonAtomic<T>(
   path: string,
   mutator: (current: T | null) => T,
   options: UpdateJsonAtomicOptions,
 ): Promise<T> {
-  const { lockPath, afterWrite, ...atomicOptions } = options;
-  return withFileLock(lockPath, async () => {
-    const current = readJson<T>(path);
-    const next = mutator(current);
-    await writeJsonAtomic(path, next, atomicOptions);
-    // why: inside the lock. A caller that sealed after the lock released would race the next writer, and the pair
-    // that lost would leave a record matching neither content ([/decisions/ad-078.md](/decisions/ad-078.md)).
-    afterWrite?.(path);
-    return next;
-  });
+  const { lockPath, afterWrite, openLock, lockSleep, lockAttempts, ...atomicOptions } = options;
+  return withFileLock(
+    lockPath,
+    async () => {
+      const current = readJson<T>(path);
+      const next = mutator(current);
+      await writeJsonAtomic(path, next, atomicOptions);
+      // why: inside the lock. A caller that sealed after the lock released would race the next writer, and the
+      // pair that lost would leave a record matching neither content ([/decisions/ad-078.md](/decisions/ad-078.md)).
+      afterWrite?.(path);
+      return next;
+    },
+    { openLock, lockSleep, lockAttempts },
+  );
 }

package/src/platform/paths.ts

@@ -78,3 +78,30 @@ export function cursorConfigDir(): string {
   const custom = process.env.CURSOR_CONFIG_DIR?.trim();
   return custom && custom.length > 0 ? custom : join(homedir(), ".cursor");
 }
+
+/**
+ * The user-level hook documents, in the order the shim reads them.
+ *
+ * why: the project shim is told a handler and nothing else — it does not know which provider invoked it. So it
+ * asks both: if any user-level document already runs this handler, a second run would be a duplicate. The cost of
+ * that imprecision is under-running in a setup where one editor is installed globally and the other only in the
+ * project, which is the safe direction — the alternative was running the handler twice, which is what actually
+ * happened ([/decisions/ad-095.md](/decisions/ad-095.md)).
+ *
+ * invariant: both paths are resolved, never assumed. Either tool can relocate its config directory by env, and
+ * this repository is itself installed under a relocated one.
+ */
+export function userSettingsPaths(): string[] {
+  return [join(claudeConfigDir(), "settings.json"), join(cursorConfigDir(), "hooks.json")];
+}
+
+/**
+ * The provider config directories, resolved. Each provider reads only its own skills directory, so this is the
+ * list anything linking the init skill must walk.
+ *
+ * invariant: resolved, never assumed — either tool relocates its config directory by env, and this repository is
+ * itself installed under a relocated one ([/decisions/ad-095.md](/decisions/ad-095.md)).
+ */
+export function providerConfigDirs(): string[] {
+  return [cursorConfigDir(), claudeConfigDir()];
+}

package/tools/doctor.ts

@@ -1,14 +1,19 @@
 import { spawnSync } from "node:child_process";
-import { existsSync, lstatSync, readFileSync, readlinkSync } from "node:fs";
+import { existsSync, lstatSync, readFileSync, readlinkSync, realpathSync } from "node:fs";
 import { homedir, platform as osPlatform } from "node:os";
-import { dirname, join } from "node:path";
+import { basename, dirname, join } from "node:path";
 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 { projectConfigPath, projectStateDir, runtimeHome } from "../src/platform/paths.ts";
+import {
+  projectConfigPath,
+  projectStateDir,
+  providerConfigDirs,
+  runtimeHome,
+} from "../src/platform/paths.ts";
 import { type ColorName, createStyle, PLAIN, type Style, SYMBOLS } from "../src/platform/style.ts";
 import { mergeClaudeSettings } from "../src/providers/claude/claude.wiring.ts";
 import {
@@ -126,6 +131,47 @@ export function runtimeOwnershipCheck(home: string): Check {
   };
 }
 
+/**
+ * hazard: a skill link whose destination is gone reads as installed to anything that only checks the link exists.
+ * One on the machine that prompted this pointed at `/tmp/tlc-recovery-…/install/skills/harness-init` — a directory
+ * from a recovery run, gone on the next boot — and nothing in the harness could see it. A provider whose skill link
+ * dangles simply never routes a request to the init skill, silently
+ * ([/decisions/ad-095.md](/decisions/ad-095.md)).
+ *
+ * invariant: reported per provider, because each reads only its own skills directory, and one being healthy says
+ * nothing about the other.
+ */
+export function checkSkillLinks(
+  home: string,
+  providerDirs: readonly string[] = providerConfigDirs(),
+  probe = {
+    linkTarget: (path: string) => {
+      try {
+        return realpathSync(path);
+      } catch {
+        // a dangling link cannot be realpath'd, so read the link itself before giving up
+        try {
+          return readlinkSync(path);
+        } catch {
+          return null;
+        }
+      }
+    },
+    exists: existsSync,
+  },
+): Check[] {
+  return providerDirs
+    .filter((dir) => existsSync(dir))
+    .map((dir) => {
+      const health = coreFacade.skill.linkHealth(join(dir, "skills", "harness-init"), home, probe);
+      return {
+        level: health.state === "ok" ? ("ok" as const) : ("fail" as const),
+        name: `init skill (${basename(dir)})`,
+        detail: coreFacade.skill.linkHealthMessage(health),
+      };
+    });
+}
+
 export function checkRuntimePaths(home: string, platform: NodeJS.Platform): Check[] {
   const launcher = join(home, "bin", "tlc-exec.mjs");
   const distSample = join(home, "dist", "stop.mjs");
@@ -522,6 +568,7 @@ export function runChecks(ctx: DoctorContext): Check[] {
   return [
     ...checkNodeVersion(ctx.nodeVersion, ctx.bunPath),
     ...checkRuntimePaths(ctx.runtimeHome, ctx.platform),
+    ...checkSkillLinks(ctx.runtimeHome),
     checkHookRuntime(ctx.runtimeHome, ctx.bunPath),
     ...checkProviders(ctx.registry, ctx.runtimeHome),
     ...checkProjectPolicy(ctx.root),

package/tools/init-project.ts

@@ -1,5 +1,5 @@
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
-import { dirname, join } from "node:path";
+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 { DEFAULTS } from "../src/core/policy/policy.defaults.ts";
@@ -115,17 +115,37 @@ export function claudeShimEntries(launcher: string): WiringEntry[] {
   }));
 }
 
-export const GITIGNORE_LINE = ".tlc/harness/state/";
+/**
+ * The paths `init` writes into the project that must not be committed.
+ *
+ * hazard: this was one line, `.tlc/harness/state/`, while `init` also writes two shim documents containing an
+ * absolute path to the runtime on the machine that ran it. A user committed a `settings.json` naming their own
+ * home directory, and the next developer's hook pointed at a path that does not exist. This repository has
+ * ignored both files by hand since 2026-07-30 — commit 81c5830, "keep generated shims out of git", with the
+ * comment "per-machine artifacts rather than shared configuration" — so the protection existed here and was never
+ * delivered to anyone using the product ([/decisions/ad-095.md](/decisions/ad-095.md)).
+ *
+ * invariant: derived from what `init` writes. `PROJECT_SHIMS` is the same list the wiring below writes to, so a
+ * new shim cannot be added without appearing here.
+ */
+export const PROJECT_SHIMS = [join(".cursor", "hooks.json"), join(".claude", "settings.json")] as const;
+
+export const GITIGNORE_STATE = ".tlc/harness/state/";
+
+/** why: posix separators, because a `.gitignore` is read by git and not by the platform that wrote it. */
+export function gitignoreEntries(): string[] {
+  return [GITIGNORE_STATE, ...PROJECT_SHIMS.map((path) => path.split(sep).join("/"))];
+}
 
 export function mergeGitignore(root: string): { text: string; changed: boolean } {
   const path = join(root, ".gitignore");
   const existing = existsSync(path) ? readFileSync(path, "utf8") : "";
   const lines = existing.split("\n");
-  const alreadyPresent = lines.includes(GITIGNORE_LINE);
-  if (alreadyPresent) {
+  const missing = gitignoreEntries().filter((entry) => !lines.includes(entry));
+  if (missing.length === 0) {
     return { text: existing.endsWith("\n") || existing === "" ? existing : `${existing}\n`, changed: false };
   }
-  lines.push(GITIGNORE_LINE);
+  lines.push(...missing);
   const withoutTrailingBlank = lines.filter((line, index, all) => line.length > 0 || index < all.length - 1);
   return { text: `${withoutTrailingBlank.join("\n").replace(/\n+$/, "")}\n`, changed: true };
 }
@@ -156,7 +176,7 @@ export type InitPlan = {
   policy: unknown;
   cursorHooksDocument: unknown | null;
   claudeHooksPreview: WiringEntry[] | null;
-  gitignoreLine: string;
+  gitignoreEntries: string[];
 };
 
 export function buildPlan(
@@ -171,7 +191,7 @@ export function buildPlan(
     policy,
     cursorHooksDocument: presence.cursor ? renderCursorHooksDocument(cursorShimEntries(launcher)) : null,
     claudeHooksPreview: presence.claude ? claudeShimEntries(launcher) : null,
-    gitignoreLine: GITIGNORE_LINE,
+    gitignoreEntries: gitignoreEntries(),
   };
 }