etymd 0.9.1 → 0.11.0

package/dist/index.js

@@ -1,10 +1,10 @@
-import { execFile } from 'node:child_process';
-import { promises } from 'node:fs';
-import { promisify } from 'node:util';
-import path from 'node:path';
-import { createHash } from 'node:crypto';
+import { execFile } from 'child_process';
+import { promises } from 'fs';
+import path2 from 'path';
+import { promisify } from 'util';
+import { createHash } from 'crypto';
 import YAML from 'yaml';
-import os from 'node:os';
+import os from 'os';
 
 var __defProp = Object.defineProperty;
 var __getOwnPropNames = Object.getOwnPropertyNames;
@@ -20,7 +20,7 @@ var __export = (target, all) => {
 var PACK_VERSION;
 var init_version = __esm({
   "src/pack/version.ts"() {
-    PACK_VERSION = "6";
+    PACK_VERSION = "8";
   }
 });
 
@@ -30,7 +30,7 @@ var init_package = __esm({
   "package.json"() {
     package_default = {
       name: "etymd",
-      version: "0.9.1",
+      version: "0.11.0",
       description: "Keep your agent instructions true \u2014 verify AGENTS.md, CLAUDE.md, rules & skills against the actual repo, with drift caught over time and a regression ledger.",
       keywords: [
         "cli",
@@ -99,12 +99,12 @@ var init_package = __esm({
         yaml: "2.9.0"
       },
       devDependencies: {
-        "@changesets/cli": "2.27.11",
+        "@changesets/cli": "2.31.1",
         "@types/node": "22.10.2",
         prettier: "3.4.2",
-        tsup: "8.3.5",
+        tsup: "8.5.1",
         typescript: "5.7.2",
-        vitest: "2.1.8"
+        vitest: "4.1.10"
       },
       publishConfig: {
         access: "public"
@@ -244,15 +244,15 @@ async function detectPackageManager(root, pkg) {
     ["bun.lockb", "bun"]
   ];
   for (const [file, pm] of lock) {
-    if (await pathExists(path.join(root, file))) return pm;
+    if (await pathExists(path2.join(root, file))) return pm;
   }
   return "unknown";
 }
 async function detectWorkspace(root, pkg) {
-  if (await pathExists(path.join(root, "nx.json"))) return { kind: "nx", packageGlobs: [] };
-  if (await pathExists(path.join(root, "turbo.json"))) return { kind: "turbo", packageGlobs: [] };
-  if (await pathExists(path.join(root, "lerna.json"))) return { kind: "lerna", packageGlobs: [] };
-  const pnpmWs = await readText(path.join(root, "pnpm-workspace.yaml"));
+  if (await pathExists(path2.join(root, "nx.json"))) return { kind: "nx", packageGlobs: [] };
+  if (await pathExists(path2.join(root, "turbo.json"))) return { kind: "turbo", packageGlobs: [] };
+  if (await pathExists(path2.join(root, "lerna.json"))) return { kind: "lerna", packageGlobs: [] };
+  const pnpmWs = await readText(path2.join(root, "pnpm-workspace.yaml"));
   if (pnpmWs) {
     const globs = pnpmWs.split("\n").map((l) => l.match(/^\s*-\s*["']?([^"'#]+)["']?/)?.[1]?.trim()).filter((g) => Boolean(g));
     return { kind: "pnpm", packageGlobs: globs };
@@ -270,21 +270,21 @@ async function listWorkspacePackages(root, globs) {
   const found = [];
   const seen = /* @__PURE__ */ new Set();
   const addFromDir = async (dir) => {
-    const pkgPath = path.join(dir, "package.json");
+    const pkgPath = path2.join(dir, "package.json");
     if (seen.has(pkgPath)) return;
     const pkg = await readJson(pkgPath);
     if (!pkg?.name) return;
     seen.add(pkgPath);
     found.push({
       name: pkg.name,
-      dir: path.relative(root, dir) || ".",
+      dir: path2.relative(root, dir) || ".",
       private: Boolean(pkg.private),
       version: pkg.version
     });
   };
   for (const glob of globs) {
     const base = glob.replace(/\/\*\*?$/, "");
-    const parent = path.join(root, base);
+    const parent = path2.join(root, base);
     if (!await isDirectory(parent)) continue;
     let entries;
     try {
@@ -294,7 +294,7 @@ async function listWorkspacePackages(root, globs) {
     }
     for (const entry of entries) {
       if (IGNORED_DIRS.has(entry) || entry.startsWith(".")) continue;
-      const child = path.join(parent, entry);
+      const child = path2.join(parent, entry);
       if (await isDirectory(child)) await addFromDir(child);
     }
   }
@@ -307,7 +307,7 @@ async function expandFileGlobs(root, globs, cap = 500) {
     if (out.size >= cap) return;
     let entries;
     try {
-      entries = await promises.readdir(path.join(root, rel), { withFileTypes: true });
+      entries = await promises.readdir(path2.join(root, rel), { withFileTypes: true });
     } catch {
       return;
     }
@@ -334,7 +334,7 @@ async function expandFileGlobs(root, globs, cap = 500) {
     (r) => ![...roots].some((other) => other !== r && (other === "" || r.startsWith(other + "/")))
   );
   for (const r of minimal) {
-    if (r && !await isDirectory(path.join(root, r))) continue;
+    if (r && !await isDirectory(path2.join(root, r))) continue;
     await walk(r);
   }
   return [...out].sort();
@@ -363,13 +363,13 @@ function detectFrameworks(pkg) {
   return out;
 }
 async function detectCi(root) {
-  if (await pathExists(path.join(root, ".gitlab-ci.yml"))) {
+  if (await pathExists(path2.join(root, ".gitlab-ci.yml"))) {
     return { system: "gitlab", files: [".gitlab-ci.yml"] };
   }
-  const workflows = path.join(root, ".github", "workflows");
+  const workflows = path2.join(root, ".github", "workflows");
   if (await isDirectory(workflows)) {
     try {
-      const files = (await promises.readdir(workflows)).filter((f) => f.endsWith(".yml") || f.endsWith(".yaml")).map((f) => path.join(".github/workflows", f));
+      const files = (await promises.readdir(workflows)).filter((f) => f.endsWith(".yml") || f.endsWith(".yaml")).map((f) => path2.join(".github/workflows", f));
       if (files.length) return { system: "github", files };
     } catch {
     }
@@ -384,7 +384,7 @@ async function hasLintStagedConfig(root, pkg) {
     ".lintstagedrc.js",
     "lint-staged.config.js"
   ]) {
-    if (await pathExists(path.join(root, f))) return true;
+    if (await pathExists(path2.join(root, f))) return true;
   }
   return false;
 }
@@ -392,50 +392,50 @@ async function detectHooks(root, hooksPath, pkg) {
   const lintStaged = await hasLintStagedConfig(root, pkg);
   if (hooksPath) {
     if (hooksPath.replace(/\/+$/, "") === ".husky/_") {
-      const base2 = path.join(root, ".husky");
+      const base2 = path2.join(root, ".husky");
       return {
         source: "husky",
         dir: ".husky",
-        preCommit: await pathExists(path.join(base2, "pre-commit")),
-        prePush: await pathExists(path.join(base2, "pre-push")),
-        commitMsg: await pathExists(path.join(base2, "commit-msg")),
+        preCommit: await pathExists(path2.join(base2, "pre-commit")),
+        prePush: await pathExists(path2.join(base2, "pre-push")),
+        commitMsg: await pathExists(path2.join(base2, "commit-msg")),
         lintStaged
       };
     }
-    const base = path.join(root, hooksPath);
+    const base = path2.join(root, hooksPath);
     return {
       source: hooksPath === ".githooks" ? "githooks" : "custom",
       dir: hooksPath,
-      preCommit: await pathExists(path.join(base, "pre-commit")),
-      prePush: await pathExists(path.join(base, "pre-push")),
-      commitMsg: await pathExists(path.join(base, "commit-msg")),
+      preCommit: await pathExists(path2.join(base, "pre-commit")),
+      prePush: await pathExists(path2.join(base, "pre-push")),
+      commitMsg: await pathExists(path2.join(base, "commit-msg")),
       lintStaged
     };
   }
-  if (await isDirectory(path.join(root, ".githooks"))) {
-    const base = path.join(root, ".githooks");
+  if (await isDirectory(path2.join(root, ".githooks"))) {
+    const base = path2.join(root, ".githooks");
     return {
       source: "githooks",
       dir: ".githooks",
-      preCommit: await pathExists(path.join(base, "pre-commit")),
-      prePush: await pathExists(path.join(base, "pre-push")),
-      commitMsg: await pathExists(path.join(base, "commit-msg")),
+      preCommit: await pathExists(path2.join(base, "pre-commit")),
+      prePush: await pathExists(path2.join(base, "pre-push")),
+      commitMsg: await pathExists(path2.join(base, "commit-msg")),
       lintStaged
     };
   }
-  if (await isDirectory(path.join(root, ".husky"))) {
-    const base = path.join(root, ".husky");
+  if (await isDirectory(path2.join(root, ".husky"))) {
+    const base = path2.join(root, ".husky");
     return {
       source: "husky",
       dir: ".husky",
-      preCommit: await pathExists(path.join(base, "pre-commit")),
-      prePush: await pathExists(path.join(base, "pre-push")),
-      commitMsg: await pathExists(path.join(base, "commit-msg")),
+      preCommit: await pathExists(path2.join(base, "pre-commit")),
+      prePush: await pathExists(path2.join(base, "pre-push")),
+      commitMsg: await pathExists(path2.join(base, "commit-msg")),
       lintStaged
     };
   }
   const legacyHooks = pkg?.husky?.hooks;
-  const configText = legacyHooks ? null : await readText(path.join(root, "husky.config.js"));
+  const configText = legacyHooks ? null : await readText(path2.join(root, "husky.config.js"));
   if (legacyHooks || configText) {
     const hookNamed = (name) => legacyHooks ? Boolean(legacyHooks[name]) : Boolean(configText && configText.includes(name));
     return {
@@ -466,10 +466,10 @@ async function detectShellSurface(root, isRepo) {
   if (!listed) return { scripts: 0 };
   const files = listed.split("\0").filter(Boolean);
   const byExtension = files.filter((f) => SHELL_EXT.test(f));
-  const candidates = files.filter((f) => !path.basename(f).includes("."));
+  const candidates = files.filter((f) => !path2.basename(f).includes("."));
   const SHEBANG_PROBE_CAP = 400;
   const probed = await Promise.all(
-    candidates.slice(0, SHEBANG_PROBE_CAP).map(async (f) => SHELL_SHEBANG.test(await firstLine(path.join(root, f))))
+    candidates.slice(0, SHEBANG_PROBE_CAP).map(async (f) => SHELL_SHEBANG.test(await firstLine(path2.join(root, f))))
   );
   return { scripts: byExtension.length + probed.filter(Boolean).length };
 }
@@ -477,12 +477,12 @@ async function detectArtifacts(root) {
   const artifacts = await Promise.all(
     ARTIFACT_SPECS.map(async (spec) => ({
       ...spec,
-      exists: await pathExists(path.join(root, spec.path))
+      exists: await pathExists(path2.join(root, spec.path))
     }))
   );
   let adrFiles = false;
   try {
-    adrFiles = (await promises.readdir(path.join(root, "docs"))).some((f) => /^\d{4}-.+\.md$/.test(f));
+    adrFiles = (await promises.readdir(path2.join(root, "docs"))).some((f) => /^\d{4}-.+\.md$/.test(f));
   } catch {
   }
   artifacts.push({
@@ -511,7 +511,7 @@ async function walkTree(root) {
     for (const entry of entries) {
       if (entry.name.startsWith(".") || IGNORED_DIRS.has(entry.name)) continue;
       if (entry.isDirectory()) {
-        total += await countFiles(path.join(dir, entry.name));
+        total += await countFiles(path2.join(dir, entry.name));
       } else if (entry.isFile()) {
         total += 1;
         state.budget -= 1;
@@ -534,7 +534,7 @@ async function walkTree(root) {
     if (!entry.isDirectory()) continue;
     if (IGNORED_DIRS.has(entry.name)) continue;
     if (entry.name.startsWith(".") && !MEANINGFUL_DOT_DIRS.has(entry.name)) continue;
-    dirs.push({ name: entry.name, files: await countFiles(path.join(root, entry.name)) });
+    dirs.push({ name: entry.name, files: await countFiles(path2.join(root, entry.name)) });
   }
   dirs.sort((a, b) => b.files - a.files);
   return { dirs, truncated: state.truncated };
@@ -782,8 +782,8 @@ async function collectFreshness(abs, isRepo, artifacts, upstreamRemote) {
   return facts;
 }
 async function scanProject(root, opts = {}) {
-  const abs = path.resolve(root);
-  const rootPkg = await readJson(path.join(abs, "package.json"));
+  const abs = path2.resolve(root);
+  const rootPkg = await readJson(path2.join(abs, "package.json"));
   const [packageManager, workspace, ci, artifacts, tree, isRepo] = await Promise.all([
     detectPackageManager(abs, rootPkg),
     detectWorkspace(abs, rootPkg),
@@ -810,7 +810,7 @@ async function scanProject(root, opts = {}) {
     packVersion: PACK_VERSION,
     generatedAt: (/* @__PURE__ */ new Date()).toISOString(),
     root: abs,
-    name: rootPkg?.name ?? path.basename(abs),
+    name: rootPkg?.name ?? path2.basename(abs),
     git: {
       isRepo,
       branch: branch ?? void 0,
@@ -847,13 +847,13 @@ var init_scan = __esm({
   }
 });
 function cacheFactsPath(root) {
-  return path.join(root, CACHE_FACTS_FILE);
+  return path2.join(root, CACHE_FACTS_FILE);
 }
 function baselinePath(root) {
-  return path.join(root, BASELINE_FILE);
+  return path2.join(root, BASELINE_FILE);
 }
 async function writeJsonFile(target, data) {
-  await promises.mkdir(path.dirname(target), { recursive: true });
+  await promises.mkdir(path2.dirname(target), { recursive: true });
   await promises.writeFile(target, JSON.stringify(data, null, 2) + "\n", "utf8");
   return target;
 }
@@ -887,9 +887,9 @@ var init_facts = __esm({
   "src/core/facts.ts"() {
     init_util();
     ETYMD_DIR = ".etymd";
-    CACHE_DIR = path.join(ETYMD_DIR, "cache");
-    CACHE_FACTS_FILE = path.join(CACHE_DIR, "facts.json");
-    BASELINE_FILE = path.join(ETYMD_DIR, "baseline.json");
+    CACHE_DIR = path2.join(ETYMD_DIR, "cache");
+    CACHE_FACTS_FILE = path2.join(CACHE_DIR, "facts.json");
+    BASELINE_FILE = path2.join(ETYMD_DIR, "baseline.json");
   }
 });
 
@@ -902,7 +902,7 @@ __export(config_exports, {
   readConfig: () => readConfig
 });
 function configPath(root) {
-  return path.join(root, CONFIG_FILE);
+  return path2.join(root, CONFIG_FILE);
 }
 function readGlobList(value, key, problems) {
   if (value === void 0) return void 0;
@@ -961,6 +961,14 @@ async function readConfig(root) {
     }
     return gates.publishGate;
   })();
+  const commitFormat = (() => {
+    if (gates.commitFormat === void 0) return void 0;
+    if (typeof gates.commitFormat !== "boolean") {
+      problems.push(`${CONFIG_FILE}: \`gates.commitFormat\` must be true or false \u2014 ignored.`);
+      return void 0;
+    }
+    return gates.commitFormat;
+  })();
   return {
     present: true,
     problems,
@@ -982,6 +990,7 @@ async function readConfig(root) {
         commands: readGlobList(gates.commands, "gates.commands", problems) ?? DEFAULT_CONFIG.gates.commands,
         failOn: failOn ?? DEFAULT_CONFIG.gates.failOn,
         publishGate,
+        commitFormat,
         allowWriting: readGlobList(gates.allowWriting, "gates.allowWriting", problems) ?? DEFAULT_CONFIG.gates.allowWriting
       }
     }
@@ -992,7 +1001,7 @@ var init_config = __esm({
   "src/core/config.ts"() {
     init_facts();
     init_util();
-    CONFIG_FILE = path.join(ETYMD_DIR, "config.json");
+    CONFIG_FILE = path2.join(ETYMD_DIR, "config.json");
     DEFAULT_CONFIG = {
       instructions: { include: [], exclude: [] },
       context: { perFileWords: 4e3, totalWords: 8e3 },
@@ -1155,9 +1164,34 @@ fi
 exit 0
 `);
 }
-function generateCommitMsgHook() {
+function commitFormatStep() {
+  const types = COMMIT_TYPES.join("|");
+  return `
+# Message format \u2014 <type>[(scope)][!]: <summary>. Needs nothing installed, so it always runs.
+subject=$(sed -e '/^#/d' -e '/^[[:space:]]*$/d' "$1" | head -1)
+case "$subject" in
+  "Merge "*|"Revert "*|fixup!*|squash!*|amend!*) ;;
+  *)
+    if ! printf '%s' "$subject" | grep -qE '^(${types})(\\([a-z0-9._/-]+\\))?!?: .+'; then
+      echo "\u2717 commit message: expected '<type>[(scope)][!]: <summary>'"
+      echo "  got:   $subject"
+      echo "  types: ${COMMIT_TYPES.join(" ")}"
+      echo "  a '!' after the type or scope marks a breaking change"
+      exit 1
+    fi
+    # Length is advice, not a block: the format is what tooling reads, the length is what a
+    # person reads, and only one of the two can break anything.
+    if [ "\${#subject}" -gt ${SUBJECT_ADVISORY_LENGTH} ]; then
+      echo "\u203A note: subject is \${#subject} characters; ${SUBJECT_ADVISORY_LENGTH} or fewer reads better in git log"
+    fi
+    ;;
+esac`;
+}
+function generateCommitMsgHook(gates) {
+  const format = gates?.commitFormat === true ? `${commitFormatStep()}
+` : "";
   return stampGenerated(`#!/usr/bin/env sh
-# etymd: content screen \u2014 the commit message itself.
+# etymd: the commit message itself \u2014 content screen, then format.
 #
 # The staged-content gate reads file bytes and never sees the message, yet a message is as
 # permanently published as any file. No-op where no checker is installed.
@@ -1167,7 +1201,7 @@ GATE="\${COMMIT_MSG_GATE:-$(command -v etymd || true)}"
 if [ -x "$GATE" ]; then
   "$GATE" screen --message "$1" || exit 1
 fi
-
+${format}
 ${localHookCall("commit-msg")}
 
 exit 0
@@ -1235,7 +1269,7 @@ ${auditStep}
 # with --no-verify and anything a rebase or merge brought in from elsewhere. Advisory here (it
 # never blocks the push): the blocking decision belongs at commit time, where the fix is cheap.
 ${CONTENT_GATE_RESOLUTION}
-if [ -x "$GATE" ] && [ "\${CONTENT_GATE_PREPUSH:-1}" = "1" ]; then
+if [ -x "$GATE" ]; then
   "$GATE" screen --tree --advisory || true
 fi
 
@@ -1249,14 +1283,10 @@ function generateArtifactCheckScript() {
 # Wire it into the irreversible moment:
 #   package.json \u2192 "prepublishOnly": "./scripts/artifact-check.sh"
 #
-# No-op where no checker is installed. Bypass is deliberate and loud: ARTIFACT_CHECK_SKIP=1.
+# The artifact gate is the one check that sees what actually SHIPS \u2014 bypass with
+# .etymd-screen-allow entries (with provenance) if you must exempt a string.
 set -eu
 
-if [ "\${ARTIFACT_CHECK_SKIP:-0}" = "1" ]; then
-  echo "\u203A artifact-check: SKIPPED by ARTIFACT_CHECK_SKIP=1"
-  exit 0
-fi
-
 ${CONTENT_GATE_RESOLUTION}
 [ -x "$GATE" ] || { echo "\u203A artifact-check: no checker installed \u2014 skipping."; exit 0; }
 
@@ -1274,12 +1304,26 @@ fi
 exit 0
 `);
 }
-var GENERATION_MARKER_RE, CONTENT_GATE_RESOLUTION;
+var GENERATION_MARKER_RE, CONTENT_GATE_RESOLUTION, COMMIT_TYPES, SUBJECT_ADVISORY_LENGTH;
 var init_templates = __esm({
   "src/pack/templates.ts"() {
     init_version();
     GENERATION_MARKER_RE = /^(?:# |<!-- )etymd:generated pack-v\S+ ([0-9a-f]{16})(?: -->)?$/;
-    CONTENT_GATE_RESOLUTION = `GATE="\${CONTENT_GATE:-$(command -v etymd || true)}"`;
+    CONTENT_GATE_RESOLUTION = `GATE="\${CONTENT_GATE:-$(if [ -x ./dist/cli.js ]; then echo ./dist/cli.js; else command -v etymd || true; fi)}"`;
+    COMMIT_TYPES = [
+      "feat",
+      "fix",
+      "docs",
+      "style",
+      "refactor",
+      "perf",
+      "test",
+      "build",
+      "ci",
+      "chore",
+      "revert"
+    ];
+    SUBJECT_ADVISORY_LENGTH = 72;
   }
 });
 
@@ -1322,7 +1366,7 @@ function deriveFailOn(facts, recorded) {
 async function planWorkflow(root, facts, opts) {
   const out = [];
   const add = async (rel, contents, label, executable = false) => {
-    const abs = path.join(root, rel);
+    const abs = path2.join(root, rel);
     const exists = await pathExists(abs);
     const existing = exists ? await readText(abs) : null;
     const differs = exists ? existing !== contents : void 0;
@@ -1341,18 +1385,19 @@ async function planWorkflow(root, facts, opts) {
     await add("AGENTS.md", generateAgentsMd(facts), "Minimal operating contract (scaffold)");
   }
   if (opts.gates) {
-    const existingPrePush = await readText(path.join(root, ".githooks", "pre-push"));
+    const existingPrePush = await readText(path2.join(root, ".githooks", "pre-push"));
     await add(".githooks/pre-commit", generatePreCommitHook(), "Process gate (pre-commit)", true);
     await add(
       ".githooks/commit-msg",
-      generateCommitMsgHook(),
-      "Content screen (commit message)",
+      generateCommitMsgHook(opts.gateConfig),
+      "Message gate (content screen, format)",
       true
     );
     const gateConfig = opts.gateConfig?.commands?.length ? opts.gateConfig : {
       commands: derivedCommands(facts, existingPrePush ?? void 0),
       failOn: opts.gateConfig?.failOn ?? DEFAULT_CONFIG.gates.failOn,
       publishGate: opts.gateConfig?.publishGate,
+      commitFormat: opts.gateConfig?.commitFormat,
       allowWriting: opts.gateConfig?.allowWriting ?? []
     };
     await add(
@@ -1404,18 +1449,18 @@ function isAlwaysAppliedCursorRule(text) {
 async function measureContext(root, perFileWords = EXTRACTION_THRESHOLD) {
   const files = [];
   for (const spec of ALWAYS_LOADED) {
-    const abs = path.join(root, spec.path);
+    const abs = path2.join(root, spec.path);
     const text = await readText(abs);
     if (text === null) continue;
     const words = wordCount(text);
     files.push({ path: spec.path, role: spec.role, words, approxTokens: approxTokens(words) });
   }
-  const rulesDir = path.join(root, ".cursor", "rules");
+  const rulesDir = path2.join(root, ".cursor", "rules");
   if (await pathExists(rulesDir)) {
     try {
       for (const entry of await promises.readdir(rulesDir)) {
         if (!entry.endsWith(".mdc") && !entry.endsWith(".md")) continue;
-        const text = await readText(path.join(rulesDir, entry));
+        const text = await readText(path2.join(rulesDir, entry));
         if (text === null || !isAlwaysAppliedCursorRule(text)) continue;
         const words = wordCount(text);
         files.push({
@@ -1448,8 +1493,8 @@ async function applyFiles(root, files, overwrite = /* @__PURE__ */ new Set()) {
       skipped.push(file.path);
       continue;
     }
-    const abs = path.join(root, file.path);
-    await promises.mkdir(path.dirname(abs), { recursive: true });
+    const abs = path2.join(root, file.path);
+    await promises.mkdir(path2.dirname(abs), { recursive: true });
     await promises.writeFile(abs, file.contents, "utf8");
     if (file.executable) await promises.chmod(abs, 493);
     written.push(file.path);
@@ -1750,14 +1795,14 @@ function parseGithubWorkflow(text, file, scripts) {
   return { jobs, parseErrors };
 }
 async function companionOf(root, hooksDir, hook, hookText, scripts) {
-  const rel = path.posix.join(hooksDir.split(path.sep).join("/"), `${hook}.local`);
+  const rel = path2.posix.join(hooksDir.split(path2.sep).join("/"), `${hook}.local`);
   if (!hookText.includes(`${hook}.local`)) return null;
-  const abs = path.join(root, hooksDir, `${hook}.local`);
+  const abs = path2.join(root, hooksDir, `${hook}.local`);
   const text = await readText(abs);
   if (text === null) return null;
   const [executable, hookExecutable] = await Promise.all([
     isExecutable(abs),
-    isExecutable(path.join(root, hooksDir, hook))
+    isExecutable(path2.join(root, hooksDir, hook))
   ]);
   if (executable === false && hookExecutable === true) return { rel, tools: [], state: "inert" };
   return {
@@ -1774,7 +1819,7 @@ async function localHookTools(root, facts, scripts) {
   const inertCompanions = [];
   const readHook = async (name) => {
     if (!hooks.dir) return empty;
-    const text = await readText(path.join(root, hooks.dir, name));
+    const text = await readText(path2.join(root, hooks.dir, name));
     if (!text) return empty;
     const tools = new Set(matchTools(text, scripts));
     const companion = await companionOf(root, hooks.dir, name, text, scripts);
@@ -1798,10 +1843,10 @@ async function localHookTools(root, facts, scripts) {
     ]);
   } else if (hooks.source === "husky-legacy") {
     const pkg = await readJson(
-      path.join(root, "package.json")
+      path2.join(root, "package.json")
     );
     const legacy = pkg?.husky?.hooks ?? {};
-    const configText = await readText(path.join(root, "husky.config.js"));
+    const configText = await readText(path2.join(root, "husky.config.js"));
     const forHook = (name) => {
       const cmd = legacy[name] ?? (configText?.includes(name) ? configText : void 0);
       return cmd ? matchTools(cmd, scripts) : [];
@@ -1812,7 +1857,7 @@ async function localHookTools(root, facts, scripts) {
   }
   let lintStaged = [];
   if (hooks.lintStaged) {
-    const pkg = await readJson(path.join(root, "package.json"));
+    const pkg = await readJson(path2.join(root, "package.json"));
     const config = pkg?.["lint-staged"];
     const commands = [];
     const collect = (v) => {
@@ -1842,7 +1887,7 @@ async function localHookTools(root, facts, scripts) {
   };
 }
 async function detectThresholds(root, scripts, ciJobs) {
-  const sonarConfigured = await pathExists(path.join(root, "sonar-project.properties")) || ciJobs.some((j) => j.tools.includes("sonar"));
+  const sonarConfigured = await pathExists(path2.join(root, "sonar-project.properties")) || ciJobs.some((j) => j.tools.includes("sonar"));
   let coverageThresholdLocal = false;
   for (const f of [
     "jest.config.js",
@@ -1854,7 +1899,7 @@ async function detectThresholds(root, scripts, ciJobs) {
     "vitest.config.js",
     "vitest.config.mts"
   ]) {
-    const text = await readText(path.join(root, f));
+    const text = await readText(path2.join(root, f));
     if (text && /coverageThreshold|thresholds\s*:/.test(text)) {
       coverageThresholdLocal = true;
       break;
@@ -1862,7 +1907,7 @@ async function detectThresholds(root, scripts, ciJobs) {
   }
   if (!coverageThresholdLocal) {
     const pkg = await readJson(
-      path.join(root, "package.json")
+      path2.join(root, "package.json")
     );
     coverageThresholdLocal = Boolean(pkg?.jest?.coverageThreshold);
   }
@@ -1875,7 +1920,7 @@ async function buildGateInventory(root, facts) {
   const inheritedIncludes = [];
   const parseErrors = [];
   if (facts.ci.system === "gitlab") {
-    const text = await readText(path.join(root, ".gitlab-ci.yml"));
+    const text = await readText(path2.join(root, ".gitlab-ci.yml"));
     if (text) {
       const parsed = parseGitlabCi(text, ".gitlab-ci.yml", scripts);
       jobs.push(...parsed.jobs);
@@ -1883,7 +1928,7 @@ async function buildGateInventory(root, facts) {
       for (const inc of parsed.inheritedIncludes) {
         if (inc.startsWith("local: ")) {
           const rel = inc.slice("local: ".length).replace(/^\//, "");
-          const subText = await readText(path.join(root, rel));
+          const subText = await readText(path2.join(root, rel));
           if (subText) {
             const sub = parseGitlabCi(subText, rel, scripts);
             jobs.push(...sub.jobs);
@@ -1899,7 +1944,7 @@ async function buildGateInventory(root, facts) {
     }
   } else if (facts.ci.system === "github") {
     for (const file of facts.ci.files) {
-      const text = await readText(path.join(root, file));
+      const text = await readText(path2.join(root, file));
       if (!text) continue;
       const parsed = parseGithubWorkflow(text, file, scripts);
       jobs.push(...parsed.jobs);
@@ -1910,7 +1955,7 @@ async function buildGateInventory(root, facts) {
     localHookTools(root, facts, scripts),
     detectThresholds(root, scripts, jobs)
   ]);
-  const pkg = await readJson(path.join(root, "package.json"));
+  const pkg = await readJson(path2.join(root, "package.json"));
   const deps = { ...pkg?.dependencies, ...pkg?.devDependencies };
   const commitlintDep = Boolean(deps["@commitlint/cli"] ?? deps["commitlint"]);
   return {
@@ -2332,7 +2377,7 @@ var stateFreshnessLens = {
       }
     }
     for (const a of stateArtifacts) {
-      const text = await readText(path.join(ctx.root, a.path));
+      const text = await readText(path2.join(ctx.root, a.path));
       if (text === null) {
         disclosures.push(`${a.path} could not be read \u2014 unexamined, not clean.`);
         outOfScope.push(a.path);
@@ -2353,7 +2398,7 @@ var stateFreshnessLens = {
       }
     }
     for (const a of decisionArtifacts) {
-      const text = await readText(path.join(ctx.root, a.path));
+      const text = await readText(path2.join(ctx.root, a.path));
       if (text === null) {
         disclosures.push(
           `${a.path} recognized as a decisions convention (directory) \u2014 age-exempt; per-entry format checks apply only to marker-carrying decisions files.`
@@ -2406,7 +2451,7 @@ init_util();
 async function listInstructionFiles(root, facts, scope) {
   const files = [];
   const add = async (rel) => {
-    const text = await readText(path.join(root, rel));
+    const text = await readText(path2.join(root, rel));
     if (text !== null) files.push({ path: normalizeRelPath(rel), text });
   };
   const singleFileArtifacts = [
@@ -2422,21 +2467,21 @@ async function listInstructionFiles(root, facts, scope) {
     const artifact = facts.artifacts.find((a) => a.id === id);
     if (artifact?.exists) await add(artifact.path);
   }
-  const rulesDir = path.join(root, ".cursor", "rules");
+  const rulesDir = path2.join(root, ".cursor", "rules");
   if (await isDirectory(rulesDir)) {
     try {
       for (const entry of await promises.readdir(rulesDir)) {
         if (entry.endsWith(".md") || entry.endsWith(".mdc"))
-          await add(path.join(".cursor/rules", entry));
+          await add(path2.join(".cursor/rules", entry));
       }
     } catch {
     }
   }
-  const skillsDir = path.join(root, ".claude", "skills");
+  const skillsDir = path2.join(root, ".claude", "skills");
   if (await isDirectory(skillsDir)) {
     try {
       for (const entry of await promises.readdir(skillsDir)) {
-        const skill = path.join(".claude/skills", entry, "SKILL.md");
+        const skill = path2.join(".claude/skills", entry, "SKILL.md");
         await add(skill);
       }
     } catch {
@@ -2464,7 +2509,7 @@ async function listStateDocuments(root, facts) {
   const docs = [];
   for (const artifact of facts.artifacts) {
     if (artifact.kind !== "state" || !artifact.exists) continue;
-    const text = await readText(path.join(root, artifact.path));
+    const text = await readText(path2.join(root, artifact.path));
     if (text !== null) docs.push({ path: normalizeRelPath(artifact.path), text });
   }
   return docs;
@@ -2748,28 +2793,28 @@ var instructionTruthLens = {
     const knownScripts = new Set(Object.keys(facts.commands.raw));
     for (const pkg of facts.packages) {
       const pkgJson = await readJson(
-        path.join(root, pkg.dir, "package.json")
+        path2.join(root, pkg.dir, "package.json")
       );
       for (const key of Object.keys(pkgJson?.scripts ?? {})) knownScripts.add(key);
     }
     const pathResolves = async (claim) => {
-      const bases = [root, ...facts.packages.map((p) => path.join(root, p.dir))];
+      const bases = [root, ...facts.packages.map((p) => path2.join(root, p.dir))];
       for (const base of bases) {
-        if (await pathExists(path.join(base, claim))) return true;
-        if (await pathExists(path.join(base, "src", claim))) return true;
-        if (await pathExists(path.join(base, "scripts", claim))) return true;
+        if (await pathExists(path2.join(base, claim))) return true;
+        if (await pathExists(path2.join(base, "src", claim))) return true;
+        if (await pathExists(path2.join(base, "scripts", claim))) return true;
       }
       return false;
     };
     const binResolves = async (name) => {
-      const bases = [root, ...facts.packages.map((p) => path.join(root, p.dir))];
+      const bases = [root, ...facts.packages.map((p) => path2.join(root, p.dir))];
       for (const base of bases) {
-        if (await pathExists(path.join(base, "node_modules", ".bin", name))) return true;
+        if (await pathExists(path2.join(base, "node_modules", ".bin", name))) return true;
       }
       return false;
     };
-    const nodeModulesInstalled = await pathExists(path.join(root, "node_modules"));
-    const manifestExists = await pathExists(path.join(root, "package.json")) || facts.packages.length > 0;
+    const nodeModulesInstalled = await pathExists(path2.join(root, "node_modules"));
+    const manifestExists = await pathExists(path2.join(root, "package.json")) || facts.packages.length > 0;
     let totalFilteredSkipped = 0;
     let binaryResolved = 0;
     let unverifiableCommands = 0;
@@ -2861,7 +2906,7 @@ var instructionTruthLens = {
         }
       }
       for (const ref of extractDocRefs(file.text)) {
-        if (await pathExists(path.join(root, ref))) continue;
+        if (await pathExists(path2.join(root, ref))) continue;
         findings.push(
           finding2({
             id: `${LENS_ID4}/dangling-ref:${file.path}:${ref}`,
@@ -2885,7 +2930,7 @@ var instructionTruthLens = {
     if (stateDocs.length) {
       for (const artifact of facts.artifacts) {
         if (artifact.kind !== "decisions" || !artifact.exists) continue;
-        const text = await readText(path.join(root, artifact.path));
+        const text = await readText(path2.join(root, artifact.path));
         if (text === null) continue;
         const entries = parseDecisionEntries(text);
         if (!entries.length) continue;
@@ -3019,14 +3064,14 @@ function rankFindings(findings) {
 // src/engine/ledger.ts
 init_util();
 function ledgerPath(root) {
-  return path.join(root, ".etymd", "ledger.json");
+  return path2.join(root, ".etymd", "ledger.json");
 }
 async function readLedger(root) {
   return await readJson(ledgerPath(root)) ?? { version: 1, entries: [] };
 }
 async function writeLedger(root, ledger) {
   const target = ledgerPath(root);
-  await promises.mkdir(path.dirname(target), { recursive: true });
+  await promises.mkdir(path2.dirname(target), { recursive: true });
   await promises.writeFile(target, JSON.stringify(ledger, null, 2) + "\n", "utf8");
 }
 function belongsToAny(id, paths) {
@@ -3111,7 +3156,7 @@ var LENSES = [
 async function runAudit(root, opts = {}) {
   const facts = await scanProject(root, { upstreamRemote: opts.upstreamRemote });
   const ledgerRoot = opts.ledgerRoot ?? root;
-  if (!opts.readOnlyRoot && ((opts.persistLedger ?? true) || await pathExists(path.join(root, ETYMD_DIR)))) {
+  if (!opts.readOnlyRoot && ((opts.persistLedger ?? true) || await pathExists(path2.join(root, ETYMD_DIR)))) {
     await writeCachedFacts(root, facts);
   }
   const baseline = await readBaseline(root);
@@ -3171,7 +3216,7 @@ function isFleetTrust(value) {
 }
 function expandTilde(p) {
   if (p === "~") return os.homedir();
-  if (p.startsWith("~/")) return path.join(os.homedir(), p.slice(2));
+  if (p.startsWith("~/")) return path2.join(os.homedir(), p.slice(2));
   return p;
 }
 var REBUILD_RECIPE = 'rebuild it beside the manifest: {"machineProfile":"corp","dirs":{"<name>":"~/path/to/worktree"}}';
@@ -3206,7 +3251,7 @@ async function readLocal(localPath, problems) {
     if (!parsed) {
       problems.push({
         kind: "parse-error",
-        file: path.basename(localPath),
+        file: path2.basename(localPath),
         detail: "must contain a JSON object \u2014 local mappings unusable"
       });
       return { present: true, data: {} };
@@ -3215,7 +3260,7 @@ async function readLocal(localPath, problems) {
   } catch (err) {
     problems.push({
       kind: "parse-error",
-      file: path.basename(localPath),
+      file: path2.basename(localPath),
       detail: `not valid JSON (${err instanceof Error ? err.message : String(err)}) \u2014 local mappings unusable`
     });
     return { present: true, data: {} };
@@ -3283,13 +3328,13 @@ function loadRegistryEntries(projects, manifest, manifestFile) {
       } else {
         const dir = manifest.localDirs[name];
         if (!dir) {
-          entry.unresolved = `no \`dirs\` mapping for \`${name}\` in ${path.basename(manifest.localPath)}`;
+          entry.unresolved = `no \`dirs\` mapping for \`${name}\` in ${path2.basename(manifest.localPath)}`;
         } else {
-          entry.resolvedRoot = path.resolve(manifest.dir, expandTilde(dir));
+          entry.resolvedRoot = path2.resolve(manifest.dir, expandTilde(dir));
         }
       }
     } else if (entry.path) {
-      entry.resolvedRoot = path.resolve(manifest.root ?? manifest.dir, expandTilde(entry.path));
+      entry.resolvedRoot = path2.resolve(manifest.root ?? manifest.dir, expandTilde(entry.path));
     } else {
       entry.unresolved = "personal entry declares no `path` \u2014 nothing to resolve";
     }
@@ -3298,7 +3343,7 @@ function loadRegistryEntries(projects, manifest, manifestFile) {
   if (corpNames.length && !manifest.localPresent) {
     manifest.problems.push({
       kind: "local-missing",
-      file: path.basename(manifest.localPath),
+      file: path2.basename(manifest.localPath),
       detail: `${corpNames.length} corp/private entr${corpNames.length === 1 ? "y" : "ies"} (${corpNames.join(", ")}) cannot resolve without it \u2014 ${REBUILD_RECIPE}`
     });
   }
@@ -3327,19 +3372,19 @@ function loadCorpusEntries(sources, manifest, manifestFile) {
     };
     const localDir = manifest.localDirs[name];
     if (localDir) {
-      entry.resolvedRoot = path.resolve(manifest.dir, "..", expandTilde(localDir));
+      entry.resolvedRoot = path2.resolve(manifest.dir, "..", expandTilde(localDir));
     } else if (entry.path) {
-      entry.resolvedRoot = path.resolve(manifest.dir, expandTilde(entry.path));
+      entry.resolvedRoot = path2.resolve(manifest.dir, expandTilde(entry.path));
     } else {
-      entry.resolvedRoot = path.resolve(manifest.dir, "..", name);
+      entry.resolvedRoot = path2.resolve(manifest.dir, "..", name);
     }
     manifest.entries.push(entry);
   }
 }
 async function loadFleetManifest(manifestPath) {
-  const abs = path.resolve(manifestPath);
-  const dir = path.dirname(abs);
-  const manifestFile = path.basename(abs);
+  const abs = path2.resolve(manifestPath);
+  const dir = path2.dirname(abs);
+  const manifestFile = path2.basename(abs);
   const raw = await readText(abs);
   if (raw === null) {
     throw new Error(`cannot read fleet manifest \`${abs}\``);
@@ -3351,7 +3396,7 @@ async function loadFleetManifest(manifestPath) {
     corpHosts: [],
     labels: {},
     localDirs: {},
-    localPath: path.join(dir, "registry.local.json"),
+    localPath: path2.join(dir, "registry.local.json"),
     localPresent: false,
     entries: [],
     problems: []
@@ -3384,7 +3429,7 @@ async function loadFleetManifest(manifestPath) {
     manifest.corpHosts = Array.isArray(local.data.corpHosts) ? local.data.corpHosts.filter((h) => typeof h === "string") : [];
     manifest.machineProfile = local.data.machineProfile === "corp" || local.data.machineProfile === "personal" ? local.data.machineProfile : void 0;
     const rootRaw = asString(local.data.root) ?? asString(parsed.root);
-    if (rootRaw) manifest.root = path.resolve(dir, expandTilde(rootRaw));
+    if (rootRaw) manifest.root = path2.resolve(dir, expandTilde(rootRaw));
     const orientationRec = asRecord(parsed.orientation);
     if (orientationRec) {
       const orientationRoot = asString(orientationRec.root);
@@ -3406,7 +3451,7 @@ async function loadFleetManifest(manifestPath) {
     loadRegistryEntries(parsed.projects, manifest, manifestFile);
   } else if (Array.isArray(parsed.sources)) {
     manifest.shape = "corpus";
-    manifest.localPath = path.join(dir, "sources.local.json");
+    manifest.localPath = path2.join(dir, "sources.local.json");
     const local = await readLocal(manifest.localPath, manifest.problems);
     manifest.localPresent = local.present;
     manifest.localDirs = asStringMap(local.data.dirs);
@@ -3462,9 +3507,9 @@ function finding3(id, tier, claim, evidence, why, action) {
   };
 }
 function corpPersistenceRoot(manifest, name) {
-  const corpDir = path.join(manifest.dir, "corp");
-  const root = path.resolve(corpDir, name);
-  if (path.dirname(root) !== corpDir || root === corpDir) {
+  const corpDir = path2.join(manifest.dir, "corp");
+  const root = path2.resolve(corpDir, name);
+  if (path2.dirname(root) !== corpDir || root === corpDir) {
     throw new Error(
       `entry name ${JSON.stringify(name)} escapes the corp persistence zone \u2014 refusing to resolve a ledger root for it`
     );
@@ -3496,7 +3541,7 @@ async function realpathOr(p) {
   try {
     return await promises.realpath(p);
   } catch {
-    return path.resolve(p);
+    return path2.resolve(p);
   }
 }
 function emailMatchesCorpHosts(email, hosts) {
@@ -3519,8 +3564,8 @@ var PROBLEM_TIER = {
 async function checkManifest(manifest) {
   const findings = [];
   const disclosures = [];
-  const manifestFile = path.basename(manifest.manifestPath);
-  const localFile = path.basename(manifest.localPath);
+  const manifestFile = path2.basename(manifest.manifestPath);
+  const localFile = path2.basename(manifest.localPath);
   for (const p of manifest.problems) {
     findings.push(
       finding3(
@@ -3672,7 +3717,7 @@ async function checkCorpWallArtifacts(entries, findings) {
   for (const entry of entries) {
     if (entry.profile !== "corp" || !entry.resolvedRoot) continue;
     for (const artifact of CORP_WALL_ARTIFACTS) {
-      if (await pathExists(path.join(entry.resolvedRoot, artifact))) {
+      if (await pathExists(path2.join(entry.resolvedRoot, artifact))) {
         findings.push(
           finding3(
             `${FLEET_LENS}/corp-artifact-in-repo:${entry.name}:${artifact}`,
@@ -3706,9 +3751,9 @@ async function checkCoverage(manifest, findings, disclosures) {
   const dirents = await promises.readdir(manifest.root, { withFileTypes: true });
   for (const d of dirents) {
     if (!d.isDirectory() || d.name.startsWith(".")) continue;
-    const dir = path.join(manifest.root, d.name);
+    const dir = path2.join(manifest.root, d.name);
     if (registered.has(await realpathOr(dir))) continue;
-    if (!await pathExists(path.join(dir, ".git"))) continue;
+    if (!await pathExists(path2.join(dir, ".git"))) continue;
     const remotes = await git(dir, ["config", "--get-regexp", "^remote\\..*\\.url"]);
     if (!remotes) continue;
     const corpRemote = manifest.corpHosts.find((h) => remotes.includes(h));
@@ -3767,7 +3812,7 @@ async function checkHygieneNeedles(manifest, findings, disclosures) {
     ...new Set(
       [
         ...Object.values(manifest.labels),
-        ...Object.values(manifest.localDirs).map((d) => path.basename(expandNeedleDir(d))),
+        ...Object.values(manifest.localDirs).map((d) => path2.basename(expandNeedleDir(d))),
         ...manifest.corpHosts
       ].filter((n) => n.length >= 3)
     )
@@ -3970,7 +4015,7 @@ async function sweepEntry(manifest, entry, opts) {
     }
   }
   const corp = entry.profile === "corp";
-  const optedIn = !corp && await pathExists(path.join(root, ETYMD_DIR));
+  const optedIn = !corp && await pathExists(path2.join(root, ETYMD_DIR));
   const result = await runAudit(root, {
     kind: opts.kind,
     persistLedger: !corp && opts.persistLedgers === true && optedIn,
@@ -3988,7 +4033,7 @@ async function sweepEntry(manifest, entry, opts) {
   project.staleAfterDays = result.config.config.state.staleAfterDays;
   for (const [key, value] of Object.entries(entry.contract)) {
     if (key === "placement" || !value) continue;
-    const exists = await pathExists(path.join(root, value.replace(/#.*$/, "")));
+    const exists = await pathExists(path2.join(root, value.replace(/#.*$/, "")));
     project.disclosures.push(
       `contract override \`${key}: ${value}\` \u2014 registered, existence-checked only (${exists ? "present" : "MISSING"})`
     );