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

package/bin/tlc-cli.ts

@@ -13,7 +13,13 @@ import { homedir } from "node:os";
 import { delimiter, join } from "node:path";
 import { coreFacade } from "../src/core/index.ts";
 import { emitJson, JSON_FLAG, takeJsonFlag, unknownFlags } from "../src/platform/cli-output.ts";
-import { flagsDir, projectConfigPath, projectStateDir, runtimeHome } from "../src/platform/paths.ts";
+import {
+  flagsDir,
+  projectConfigPath,
+  projectStateDir,
+  providerConfigDirs,
+  runtimeHome,
+} from "../src/platform/paths.ts";
 import { type Row, render, type Screen, type Section } from "../src/platform/screen.ts";
 import { createStyle, PLAIN, type Style } from "../src/platform/style.ts";
 
@@ -1264,7 +1270,6 @@ function runUpdate(root: string): never {
 
   const binDir = process.env.TLC_BIN_DIR || join(homedir(), ".local", "bin");
   mkdirSync(binDir, { recursive: true });
-  mkdirSync(join(home, "..", "skills"), { recursive: true });
 
   if (process.platform === "win32") {
     const installPs1 = join(dest, "install.ps1");
@@ -1279,14 +1284,24 @@ function runUpdate(root: string): never {
   } else {
     const tlcBin = join(dest, "bin", "tlc");
     const skillSrc = join(dest, "skills", "harness-init");
-    const skillDest = join(home, "..", "skills", "harness-init");
     spawnSync("ln", ["-sfn", tlcBin, join(binDir, "tlc")], { stdio: "inherit" });
     if (!existsSync(skillSrc)) {
       console.error(`update: missing skill at ${skillSrc}`);
       process.exit(1);
     }
-    spawnSync("ln", ["-sfn", skillSrc, skillDest], { stdio: "inherit" });
-    console.log(`update: skill → ${skillDest}`);
+    // hazard: this linked to `<home>/../skills/harness-init` — a directory no provider reads, and which did not
+    // exist at all on the machine where this was found. `install.sh` had it right all along, linking into every
+    // provider config directory that exists, because each provider only reads its own. The resolution is now one
+    // function both use ([/decisions/ad-095.md](/decisions/ad-095.md)).
+    const links = coreFacade.skill.skillLinks(dest, providerConfigDirs(), existsSync);
+    if (links.length === 0) {
+      console.log("update: no provider config dir found — skill not linked");
+    }
+    for (const link of links) {
+      mkdirSync(join(link.providerDir, "skills"), { recursive: true });
+      spawnSync("ln", ["-sfn", link.source, link.target], { stdio: "inherit" });
+      console.log(`update: skill → ${link.target}`);
+    }
     const hooks = spawnSync(process.execPath, [join(dest, "bin", "write-user-hooks.mjs")], {
       stdio: "inherit",
       env: { ...process.env, TLC_HOME: home },

package/dist/compact-before.mjs

@@ -276,20 +276,27 @@ function readJson(path) {
     return null;
   }
 }
-async function withFileLock(lockPath, fn) {
+function isContention(error) {
+  return errorCode(error) === "EEXIST" || isRetryableFsError(error);
+}
+async function withFileLock(lockPath, fn, options = {}) {
+  const {
+    openLock = (path) => closeSync(openSync(path, "wx")),
+    lockSleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms)),
+    lockAttempts = 200
+  } = options;
   mkdirSync2(dirname2(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) {
@@ -304,14 +311,14 @@ async function withFileLock(lockPath, fn) {
   }
 }
 async function updateJsonAtomic(path, mutator, options) {
-  const { lockPath, afterWrite, ...atomicOptions } = options;
+  const { lockPath, afterWrite, openLock, lockSleep, lockAttempts, ...atomicOptions } = options;
   return withFileLock(lockPath, async () => {
     const current = readJson(path);
     const next = mutator(current);
     await writeJsonAtomic(path, next, atomicOptions);
     afterWrite?.(path);
     return next;
-  });
+  }, { openLock, lockSleep, lockAttempts });
 }
 
 // src/core/capability/capability.store.ts
@@ -5569,6 +5576,68 @@ function evaluateShellCommand(args) {
   return { kind: "allow" };
 }
 
+// src/core/shim/shim.precedence.ts
+var LAUNCHER = "tlc-exec";
+function invocationText(entry) {
+  return [entry.command ?? "", ...entry.args ?? []].join(" ");
+}
+function coversHandler(settings, handler) {
+  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;
+}
+function decideShim(userSettings, handler) {
+  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}` };
+}
+
+// src/core/skill/skill.link.ts
+var SKILL_NAME = "harness-init";
+function skillLinks(runtimeHome2, providerDirs, present) {
+  const source = `${runtimeHome2}/skills/${SKILL_NAME}`;
+  return providerDirs.filter((dir) => present(dir)).map((providerDir) => ({
+    providerDir,
+    source,
+    target: `${providerDir}/skills/${SKILL_NAME}`
+  }));
+}
+function linkHealth(target, runtimeHome2, probe) {
+  const resolved = probe.linkTarget(target);
+  if (resolved === null) {
+    return { state: "absent", target };
+  }
+  if (!probe.exists(resolved)) {
+    return { state: "dangling", target, resolved };
+  }
+  const home = runtimeHome2.replace(/\/+$/, "");
+  return resolved === home || resolved.startsWith(`${home}/`) ? { state: "ok", target, resolved } : { state: "outside-runtime", target, resolved };
+}
+function linkHealthMessage(health) {
+  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";
+  }
+}
+
 // src/core/stagnation/stagnation.resolution.ts
 import { existsSync as existsSync20, mkdirSync as mkdirSync11, readFileSync as readFileSync22, writeFileSync as writeFileSync10 } from "node:fs";
 import { join as join21 } from "node:path";
@@ -6696,6 +6765,15 @@ var coreFacade = {
     readHandoffFile,
     readForeignSlices
   },
+  shim: {
+    coversHandler,
+    decideShim
+  },
+  skill: {
+    linkHealth,
+    linkHealthMessage,
+    skillLinks
+  },
   lesson: {
     projectLessonsInjectable,
     recordLessonFromFailure,

package/dist/doctor.mjs

@@ -3,9 +3,9 @@ var __require = /* @__PURE__ */ createRequire(import.meta.url);
 
 // tools/doctor.ts
 import { spawnSync } from "node:child_process";
-import { existsSync as existsSync29, lstatSync as lstatSync2, readFileSync as readFileSync31, readlinkSync } from "node:fs";
+import { existsSync as existsSync29, lstatSync as lstatSync2, readFileSync as readFileSync31, readlinkSync, realpathSync as realpathSync4 } from "node:fs";
 import { homedir as homedir3, platform as osPlatform } from "node:os";
-import { dirname as dirname9, join as join30 } from "node:path";
+import { basename as basename5, dirname as dirname9, join as join30 } from "node:path";
 
 // bin/tlc-cli.ts
 import {
@@ -97,6 +97,9 @@ function cursorConfigDir() {
   const custom = process.env.CURSOR_CONFIG_DIR?.trim();
   return custom && custom.length > 0 ? custom : join(homedir(), ".cursor");
 }
+function providerConfigDirs() {
+  return [cursorConfigDir(), claudeConfigDir()];
+}
 
 // src/core/attest/attest.service.ts
 var CHAIN_ROOT = "genesis";
@@ -295,20 +298,27 @@ function readJson(path) {
     return null;
   }
 }
-async function withFileLock(lockPath, fn) {
+function isContention(error) {
+  return errorCode(error) === "EEXIST" || isRetryableFsError(error);
+}
+async function withFileLock(lockPath, fn, options = {}) {
+  const {
+    openLock = (path) => closeSync(openSync(path, "wx")),
+    lockSleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms)),
+    lockAttempts = 200
+  } = options;
   mkdirSync2(dirname2(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) {
@@ -323,14 +333,14 @@ async function withFileLock(lockPath, fn) {
   }
 }
 async function updateJsonAtomic(path, mutator, options) {
-  const { lockPath, afterWrite, ...atomicOptions } = options;
+  const { lockPath, afterWrite, openLock, lockSleep, lockAttempts, ...atomicOptions } = options;
   return withFileLock(lockPath, async () => {
     const current = readJson(path);
     const next = mutator(current);
     await writeJsonAtomic(path, next, atomicOptions);
     afterWrite?.(path);
     return next;
-  });
+  }, { openLock, lockSleep, lockAttempts });
 }
 
 // src/core/capability/capability.store.ts
@@ -5581,6 +5591,68 @@ function evaluateShellCommand(args) {
   return { kind: "allow" };
 }
 
+// src/core/shim/shim.precedence.ts
+var LAUNCHER = "tlc-exec";
+function invocationText(entry) {
+  return [entry.command ?? "", ...entry.args ?? []].join(" ");
+}
+function coversHandler(settings, handler) {
+  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;
+}
+function decideShim(userSettings, handler) {
+  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}` };
+}
+
+// src/core/skill/skill.link.ts
+var SKILL_NAME = "harness-init";
+function skillLinks(runtimeHome2, providerDirs, present) {
+  const source = `${runtimeHome2}/skills/${SKILL_NAME}`;
+  return providerDirs.filter((dir) => present(dir)).map((providerDir) => ({
+    providerDir,
+    source,
+    target: `${providerDir}/skills/${SKILL_NAME}`
+  }));
+}
+function linkHealth(target, runtimeHome2, probe) {
+  const resolved = probe.linkTarget(target);
+  if (resolved === null) {
+    return { state: "absent", target };
+  }
+  if (!probe.exists(resolved)) {
+    return { state: "dangling", target, resolved };
+  }
+  const home = runtimeHome2.replace(/\/+$/, "");
+  return resolved === home || resolved.startsWith(`${home}/`) ? { state: "ok", target, resolved } : { state: "outside-runtime", target, resolved };
+}
+function linkHealthMessage(health) {
+  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";
+  }
+}
+
 // src/core/stagnation/stagnation.resolution.ts
 import { existsSync as existsSync20, mkdirSync as mkdirSync11, readFileSync as readFileSync22, writeFileSync as writeFileSync10 } from "node:fs";
 import { join as join21 } from "node:path";
@@ -6708,6 +6780,15 @@ var coreFacade = {
     readHandoffFile,
     readForeignSlices
   },
+  shim: {
+    coversHandler,
+    decideShim
+  },
+  skill: {
+    linkHealth,
+    linkHealthMessage,
+    skillLinks
+  },
   lesson: {
     projectLessonsInjectable,
     recordLessonFromFailure,
@@ -7893,6 +7974,29 @@ function runtimeOwnershipCheck(home) {
     detail: detail[kind]
   };
 }
+function checkSkillLinks(home, providerDirs = providerConfigDirs(), probe = {
+  linkTarget: (path) => {
+    try {
+      return realpathSync4(path);
+    } catch {
+      try {
+        return readlinkSync(path);
+      } catch {
+        return null;
+      }
+    }
+  },
+  exists: existsSync29
+}) {
+  return providerDirs.filter((dir) => existsSync29(dir)).map((dir) => {
+    const health = coreFacade.skill.linkHealth(join30(dir, "skills", "harness-init"), home, probe);
+    return {
+      level: health.state === "ok" ? "ok" : "fail",
+      name: `init skill (${basename5(dir)})`,
+      detail: coreFacade.skill.linkHealthMessage(health)
+    };
+  });
+}
 function checkRuntimePaths(home, platform) {
   const launcher = join30(home, "bin", "tlc-exec.mjs");
   const distSample = join30(home, "dist", "stop.mjs");
@@ -8171,6 +8275,7 @@ function runChecks(ctx) {
   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),
@@ -8251,6 +8356,7 @@ export {
   formatReport,
   exitCodeFor,
   checkSubagentAllowlist,
+  checkSkillLinks,
   checkRuntimePaths,
   checkProviders,
   checkProjectPolicy,

package/dist/init-project.mjs

@@ -3,7 +3,7 @@ var __require = /* @__PURE__ */ createRequire(import.meta.url);
 
 // tools/init-project.ts
 import { existsSync as existsSync3, mkdirSync as mkdirSync3, readFileSync as readFileSync3, writeFileSync as writeFileSync3 } from "node:fs";
-import { dirname as dirname3, join as join4 } from "node:path";
+import { dirname as dirname3, join as join4, sep } from "node:path";
 
 // bin/write-user-hooks.mjs
 import { existsSync as existsSync2, mkdirSync as mkdirSync2, readFileSync as readFileSync2, writeFileSync as writeFileSync2 } from "node:fs";
@@ -858,19 +858,23 @@ function claudeShimEntries(launcher) {
     ...spec.loopLimit !== undefined ? { loopLimit: spec.loopLimit } : {}
   }));
 }
-var GITIGNORE_LINE = ".tlc/harness/state/";
+var PROJECT_SHIMS = [join4(".cursor", "hooks.json"), join4(".claude", "settings.json")];
+var GITIGNORE_STATE = ".tlc/harness/state/";
+function gitignoreEntries() {
+  return [GITIGNORE_STATE, ...PROJECT_SHIMS.map((path) => path.split(sep).join("/"))];
+}
 function mergeGitignore(root) {
   const path = join4(root, ".gitignore");
   const existing = existsSync3(path) ? readFileSync3(path, "utf8") : "";
   const lines = existing.split(`
 `);
-  const alreadyPresent = lines.includes(GITIGNORE_LINE);
-  if (alreadyPresent) {
+  const missing = gitignoreEntries().filter((entry) => !lines.includes(entry));
+  if (missing.length === 0) {
     return { text: existing.endsWith(`
 `) || existing === "" ? existing : `${existing}
 `, 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(`
 `).replace(/\n+$/, "")}
@@ -901,7 +905,7 @@ function buildPlan(root, flags, stdinText, presence) {
     policy,
     cursorHooksDocument: presence.cursor ? renderCursorHooksDocument(cursorShimEntries(launcher)) : null,
     claudeHooksPreview: presence.claude ? claudeShimEntries(launcher) : null,
-    gitignoreLine: GITIGNORE_LINE
+    gitignoreEntries: gitignoreEntries()
   };
 }
 function applyPlan(root, flags, presence, stdinText) {
@@ -983,11 +987,13 @@ export {
   mergeGitignore,
   main,
   launcherPath,
+  gitignoreEntries,
   detectProviders,
   cursorShimEntries,
   claudeShimEntries,
   buildPlan,
   applyPlan,
   UsageError,
-  GITIGNORE_LINE
+  PROJECT_SHIMS,
+  GITIGNORE_STATE
 };

package/dist/lessons-cli.mjs

@@ -268,20 +268,27 @@ function readJson(path) {
     return null;
   }
 }
-async function withFileLock(lockPath, fn) {
+function isContention(error) {
+  return errorCode(error) === "EEXIST" || isRetryableFsError(error);
+}
+async function withFileLock(lockPath, fn, options = {}) {
+  const {
+    openLock = (path) => closeSync(openSync(path, "wx")),
+    lockSleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms)),
+    lockAttempts = 200
+  } = options;
   mkdirSync2(dirname2(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) {
@@ -296,14 +303,14 @@ async function withFileLock(lockPath, fn) {
   }
 }
 async function updateJsonAtomic(path, mutator, options) {
-  const { lockPath, afterWrite, ...atomicOptions } = options;
+  const { lockPath, afterWrite, openLock, lockSleep, lockAttempts, ...atomicOptions } = options;
   return withFileLock(lockPath, async () => {
     const current = readJson(path);
     const next = mutator(current);
     await writeJsonAtomic(path, next, atomicOptions);
     afterWrite?.(path);
     return next;
-  });
+  }, { openLock, lockSleep, lockAttempts });
 }
 
 // src/core/capability/capability.store.ts
@@ -5554,6 +5561,68 @@ function evaluateShellCommand(args) {
   return { kind: "allow" };
 }
 
+// src/core/shim/shim.precedence.ts
+var LAUNCHER = "tlc-exec";
+function invocationText(entry) {
+  return [entry.command ?? "", ...entry.args ?? []].join(" ");
+}
+function coversHandler(settings, handler) {
+  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;
+}
+function decideShim(userSettings, handler) {
+  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}` };
+}
+
+// src/core/skill/skill.link.ts
+var SKILL_NAME = "harness-init";
+function skillLinks(runtimeHome2, providerDirs, present) {
+  const source = `${runtimeHome2}/skills/${SKILL_NAME}`;
+  return providerDirs.filter((dir) => present(dir)).map((providerDir) => ({
+    providerDir,
+    source,
+    target: `${providerDir}/skills/${SKILL_NAME}`
+  }));
+}
+function linkHealth(target, runtimeHome2, probe) {
+  const resolved = probe.linkTarget(target);
+  if (resolved === null) {
+    return { state: "absent", target };
+  }
+  if (!probe.exists(resolved)) {
+    return { state: "dangling", target, resolved };
+  }
+  const home = runtimeHome2.replace(/\/+$/, "");
+  return resolved === home || resolved.startsWith(`${home}/`) ? { state: "ok", target, resolved } : { state: "outside-runtime", target, resolved };
+}
+function linkHealthMessage(health) {
+  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";
+  }
+}
+
 // src/core/stagnation/stagnation.resolution.ts
 import { existsSync as existsSync20, mkdirSync as mkdirSync11, readFileSync as readFileSync22, writeFileSync as writeFileSync10 } from "node:fs";
 import { join as join21 } from "node:path";
@@ -6681,6 +6750,15 @@ var coreFacade = {
     readHandoffFile,
     readForeignSlices
   },
+  shim: {
+    coversHandler,
+    decideShim
+  },
+  skill: {
+    linkHealth,
+    linkHealthMessage,
+    skillLinks
+  },
   lesson: {
     projectLessonsInjectable,
     recordLessonFromFailure,