etymd 0.12.0 → 0.14.0

package/CHANGELOG.md

@@ -1,5 +1,117 @@
 # etymd
 
+## 0.14.0
+
+Knowledge pack **v8 → v12**: every generated hook and script is regenerated by `etymd gates`.
+Versions 9, 10 and 11 were claimed by work that was reworked before release and stay retired,
+so a pack number cited in a baseline always means exactly one pack.
+
+### Minor Changes
+
+- 3056213: Three fixes to the generated gates and the onboarding flow:
+
+  - **zsh is out of the shellcheck scan.** The generated pre-push discovered shell
+    scripts by a shebang pattern that included zsh, but shellcheck cannot parse zsh — SC1071 is a
+    parser-level error no inline directive silences — so a repo whose executable surface is zsh
+    could never push. zsh shebangs are now excluded from the checked set and the hook prints the
+    exclusion (count + reason) at run time instead of going quiet about coverage.
+  - **`~/` home paths are no longer repo file references.** Prose like "global rules in
+    `~/.claude/CLAUDE.md` apply on top" made the audit demand a repo-root CLAUDE.md that was
+    never meant to exist — the sentence points at the reader's machine. Home-path mentions of
+    well-known docs are now skipped and disclosed, like absolute tokens; one ordinary mention
+    still makes the doc a live claim.
+  - **`init` no longer scaffolds AGENTS.md unasked.** `init -y` in a repo without a contract used
+    to write template prose nobody reviewed (and baseline it, making later deletion read as
+    drift). The scaffold is now opt-in via `--with-agents`; interactive runs still ask first.
+
+- aab88c5: A content gate that cannot run is now caught, and says why.
+
+  The screen doors resolve their checker at run time, from outside the repo — so whether the gate
+  will actually run is the one thing reading the hook cannot tell you. When the resolved checker
+  turns out not to be a screener, the commit door failed closed on that program's own bare error
+  and the push door, advisory by design, skipped its whole-tree pass in silence. A repo could read
+  as screened for months while nothing screened it.
+
+  Two changes, one class:
+
+  - **The hooks explain themselves.** After a failed screen — and only then, so a clean run pays
+    nothing — the hook asks the checker whether it understands `screen` at all. If it does not, it
+    prints a line naming the version floor (`screen` needs etymd 0.11+) and the override, instead of
+    leaving the checker's unexplained "unknown command" as the last word. A screener reporting a
+    real finding is left to speak for itself.
+  - **`etymd audit` and `etymd doctor` check reachability.** Gate integrity now resolves the screen
+    runner exactly as the hook would and asks it the same question, reporting a risk-tier finding
+    when a checker resolves but cannot screen. No checker installed stays the designed no-op —
+    disclosed, never a finding — and a probe that could not be carried out claims nothing.
+
+- 6536081: Generated hooks no longer guess at the content screener by path.
+
+  The emitted content-screen resolution used to include a bare `[ -x ./dist/cli.js ]` check ahead
+  of the `etymd` on PATH. That path is simply where a great many CLI projects build, so any repo
+  that builds its own binary there had the hook invoke THAT binary as the screener: it does not
+  know `screen`, so the commit door failed closed on every commit, while the push door — which
+  ignores the screen's exit status by design — skipped the whole-tree pass in silence. The trap
+  armed itself on a plain dependency install, since that runs the repo's build.
+
+  Resolution is now `CONTENT_GATE`, then whatever `etymd` is on PATH. The dev-build arm remains
+  for the repo that develops the screener itself, where gating on an unreleased build is the point,
+  but it is decided at generation time from the manifest name and emitted nowhere else.
+
+  Regenerate with `etymd gates` to pick this up; a repo needing a different runner for one
+  invocation still has `CONTENT_GATE`.
+
+- 0c0bcc6: gates: generated pre-push steps run scrubbed of git's exported GIT\_\* environment
+
+  Git exports `GIT_DIR` / `GIT_WORK_TREE` / `GIT_INDEX_FILE` / … to every hook it
+  runs, and a child `git` that inherits them ignores its cwd. A test suite that
+  builds fixture repositories by shelling out to `git` therefore operates on the
+  REAL repository — committing into it, moving its refs — while the same suite
+  outside a hook is harmless, which is exactly why the defect hides: nothing run
+  from CI ever reproduces it. This changes the generated pre-push (`etymd gates`):
+
+  - **Every gate step runs through a `run_gate()` helper** that strips every
+    exported `GIT_*` name before the command runs — each name found in the
+    environment, not a fixed list, because git adds variables over time. A step
+    that genuinely means the repository finds it again from its working
+    directory, which for a hook is the repo root.
+  - **The audit and shellcheck steps stay unscrubbed**, deliberately: audit
+    operates on the repo it is invoked in and never descends into fixtures, and
+    shellcheck's `git ls-files` must see the real repo.
+  - **The `.local` companion note documents the wrap**, so a hand-written guard
+    that runs tests can scrub the same way — the companion is where repo-owned
+    suites live.
+
+  Existing hooks pick this up on the next `etymd gates` run.
+
+### Patch Changes
+
+- 1cae71b: Context economy counts a file once when two instruction names are the same file.
+
+  `AGENTS.md` symlinked to `CLAUDE.md` is the ordinary way to serve harnesses that read different
+  names. Both names were measured separately, which doubled the reported always-loaded footprint —
+  enough to manufacture an over-budget finding out of nothing — and fired the heavy-file finding
+  twice for one file. Candidates resolving to the same inode (symlink or hardlink) are now counted
+  once and reported under every name they answer to, in `etymd audit` and `etymd context` alike,
+  with the merge stated in the lens disclosures.
+
+## 0.13.0
+
+### Minor Changes
+
+- 9b45d54: screen: the machine-path check now also skips on upstream-owned files
+
+  The upstream-ownership exemption (0.12.0) skipped vocabulary-class patterns on files
+  byte-identical to public upstream, but the absolute-home-path check still fired on
+  them. Forks of container-based projects carry upstream docs full of generic container
+  paths (the `/home/<user>/...` shape), so a sync kept blocking on paths that are
+  already public in the upstream repo and never name the local machine.
+
+  An upstream-owned file is byte-identical to a public upstream blob, so any path it
+  names is already public and cannot leak this machine. The machine-path check is now
+  skipped for upstream-owned files, exactly like vocabulary-class patterns. Secret-class
+  patterns stay absolute on every file, and the machine-path check still fires on all
+  non-upstream files (the common case) unchanged.
+
 ## 0.12.0
 
 ### Minor Changes

package/dist/{approve-PP2QJQ3Y.js → approve-QDOH2E7V.js}

@@ -1,9 +1,9 @@
 #!/usr/bin/env node
-import { section, theme, print, renderBaselineDrift, glyph } from './chunk-5BVKFJWM.js';
-import { scanProject } from './chunk-MTVEJ33D.js';
-import { VERSION } from './chunk-YFNRDXUY.js';
-import { readBaseline, summarizeBaselineDrift, isDriftEmpty, writeBaseline, deriveProfile } from './chunk-JHZ2BN4U.js';
-import { PACK_VERSION } from './chunk-LSZGCKIQ.js';
+import { section, theme, print, renderBaselineDrift, glyph } from './chunk-HI7NWPRA.js';
+import { scanProject } from './chunk-HWC6PKJM.js';
+import { VERSION } from './chunk-623W6KVC.js';
+import { readBaseline, summarizeBaselineDrift, isDriftEmpty, writeBaseline, deriveProfile } from './chunk-P6ATKV2R.js';
+import { PACK_VERSION } from './chunk-YQZDYDAK.js';
 import './chunk-4VPBP6K6.js';
 
 // src/commands/approve.ts

package/dist/audit-42OHF7ON.js

@@ -0,0 +1,10 @@
+#!/usr/bin/env node
+export { run } from './chunk-PAMWS665.js';
+import './chunk-LT7JMVV3.js';
+import './chunk-3E2IPCRY.js';
+import './chunk-HI7NWPRA.js';
+import './chunk-HWC6PKJM.js';
+import './chunk-623W6KVC.js';
+import './chunk-P6ATKV2R.js';
+import './chunk-YQZDYDAK.js';
+import './chunk-4VPBP6K6.js';

package/dist/{brief-GDLJEG6X.js → brief-ZUQK3CFL.js}

@@ -1,9 +1,9 @@
 #!/usr/bin/env node
-import { print, theme } from './chunk-5BVKFJWM.js';
-import { scanProject } from './chunk-MTVEJ33D.js';
-import './chunk-YFNRDXUY.js';
-import { ETYMD_DIR } from './chunk-JHZ2BN4U.js';
-import './chunk-LSZGCKIQ.js';
+import { print, theme } from './chunk-HI7NWPRA.js';
+import { scanProject } from './chunk-HWC6PKJM.js';
+import './chunk-623W6KVC.js';
+import { ETYMD_DIR } from './chunk-P6ATKV2R.js';
+import './chunk-YQZDYDAK.js';
 import './chunk-4VPBP6K6.js';
 import { promises } from 'fs';
 import path from 'path';

package/dist/{chunk-YFNRDXUY.js → chunk-623W6KVC.js}

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 // package.json
 var package_default = {
-  version: "0.12.0"};
+  version: "0.14.0"};
 
 // src/version.ts
 var VERSION = package_default.version;

package/dist/{chunk-5BVKFJWM.js → chunk-HI7NWPRA.js}

@@ -1,6 +1,77 @@
 #!/usr/bin/env node
+import { DEFAULT_CONFIG } from './chunk-P6ATKV2R.js';
+import { readText, pathExists, approxTokens, wordCount } from './chunk-4VPBP6K6.js';
+import { promises } from 'fs';
+import path from 'path';
 import pc from 'picocolors';
 
+var ALWAYS_LOADED = [
+  { path: "AGENTS.md", role: "operating contract" },
+  { path: "PROJECT_CONTEXT.md", role: "ground-truth state" },
+  { path: "CLAUDE.md", role: "Claude Code pointer" },
+  { path: "GEMINI.md", role: "Gemini pointer" },
+  { path: ".github/copilot-instructions.md", role: "Copilot instructions" },
+  { path: ".cursorrules", role: "Cursor rules (legacy)" }
+];
+var EXTRACTION_THRESHOLD = DEFAULT_CONFIG.context.perFileWords;
+function isAlwaysAppliedCursorRule(text) {
+  const fm = text.match(/^---\n([\s\S]*?)\n---/);
+  if (!fm) return true;
+  const frontmatter = fm[1] ?? "";
+  return /^\s*alwaysApply\s*:\s*true\s*$/m.test(frontmatter);
+}
+async function inodeKey(abs) {
+  try {
+    const st = await promises.stat(abs);
+    return st.ino ? `${st.dev}:${st.ino}` : null;
+  } catch {
+    return null;
+  }
+}
+function contextFileLabel(file) {
+  return file.aliases?.length ? [file.path, ...file.aliases].join(" \u2192 ") : file.path;
+}
+async function measureContext(root, perFileWords = EXTRACTION_THRESHOLD) {
+  const files = [];
+  const byInode = /* @__PURE__ */ new Map();
+  const record = async (rel, role, text) => {
+    const words = wordCount(text);
+    const key = await inodeKey(path.join(root, rel));
+    const seen = key ? byInode.get(key) : void 0;
+    if (seen) {
+      seen.aliases = [...seen.aliases ?? [], rel];
+      return;
+    }
+    const file = { path: rel, role, words, approxTokens: approxTokens(words) };
+    if (key) byInode.set(key, file);
+    files.push(file);
+  };
+  for (const spec of ALWAYS_LOADED) {
+    const text = await readText(path.join(root, spec.path));
+    if (text === null) continue;
+    await record(spec.path, spec.role, text);
+  }
+  const rulesDir = path.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));
+        if (text === null || !isAlwaysAppliedCursorRule(text)) continue;
+        await record(`.cursor/rules/${entry}`, "Cursor rule (always applied)", text);
+      }
+    } catch {
+    }
+  }
+  const totalWords = files.reduce((s, f) => s + f.words, 0);
+  return {
+    files: files.sort((a, b) => b.words - a.words),
+    totalWords,
+    totalApproxTokens: approxTokens(totalWords),
+    perFileWords,
+    extractionCandidates: files.filter((f) => f.words >= perFileWords)
+  };
+}
 var theme = {
   brand: (s) => pc.magenta(pc.bold(s)),
   heading: (s) => pc.bold(s),
@@ -103,11 +174,13 @@ function renderContext(budget, threshold) {
     print(`  ${theme.dim("no always-loaded agent files found \u2014 nothing loads every session yet")}`);
     return;
   }
-  const pathWidth = maxWidth(budget.files.map((f) => f.path));
+  const pathWidth = maxWidth(budget.files.map((f) => contextFileLabel(f)));
   for (const f of budget.files) {
     const heavy = f.words >= threshold;
     const words = heavy ? theme.warn(`${f.words} w`) : `${f.words} w`;
-    print(`  ${pad(theme.info(f.path), pathWidth)}  ${pad(words, 12)} ${theme.dim(f.role)}`);
+    print(
+      `  ${pad(theme.info(contextFileLabel(f)), pathWidth)}  ${pad(words, 12)} ${theme.dim(f.role)}`
+    );
   }
   print();
   keyValues([
@@ -122,7 +195,9 @@ function renderContext(budget, threshold) {
       `  ${theme.dim("These load every session but are rarely all needed. Move to an on-demand skill:")}`
     );
     for (const f of budget.extractionCandidates) {
-      print(`  ${glyph.arrow} ${theme.info(f.path)} ${theme.dim(`(${f.words} words)`)}`);
+      print(
+        `  ${glyph.arrow} ${theme.info(contextFileLabel(f))} ${theme.dim(`(${f.words} words)`)}`
+      );
     }
   } else {
     print(`  ${glyph.ok} ${theme.dim("lean \u2014 no single file is heavy enough to extract yet")}`);
@@ -262,4 +337,4 @@ function renderLedger(ledger) {
   }
 }
 
-export { TIER_BADGE, glyph, print, renderBaselineDrift, renderContext, renderFacts, renderFindings, renderFleetNotes, renderFleetRows, renderLedger, renderLedgerDiff, renderLensCoverage, renderPlan, section, theme };
+export { TIER_BADGE, contextFileLabel, glyph, measureContext, print, renderBaselineDrift, renderContext, renderFacts, renderFindings, renderFleetNotes, renderFleetRows, renderLedger, renderLedgerDiff, renderLensCoverage, renderPlan, section, theme };

package/dist/{chunk-2VLNI3L2.js → chunk-HOR4M6EC.js}

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 import { readLedger, resolveEntry, writeLedger } from './chunk-3E2IPCRY.js';
-import { print, renderLedger, glyph, theme } from './chunk-5BVKFJWM.js';
+import { print, renderLedger, glyph, theme } from './chunk-HI7NWPRA.js';
 
 // src/commands/ledger.ts
 async function list(opts) {

package/dist/{chunk-MTVEJ33D.js → chunk-HWC6PKJM.js}

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
-import { VERSION } from './chunk-YFNRDXUY.js';
-import { PACK_VERSION } from './chunk-LSZGCKIQ.js';
+import { VERSION } from './chunk-623W6KVC.js';
+import { PACK_VERSION } from './chunk-YQZDYDAK.js';
 import { normalizeRelPath, isDirectory, readJson, git, matchesAnyGlob, pathExists, readText } from './chunk-4VPBP6K6.js';
 import path from 'path';
 import { promises } from 'fs';

package/dist/{chunk-O3PHW4OP.js → chunk-LT7JMVV3.js}

@@ -1,13 +1,14 @@
 #!/usr/bin/env node
-import { measureContext } from './chunk-F75Q43BC.js';
 import { readLedger, reconcileLedger, writeLedger, visibleFindings } from './chunk-3E2IPCRY.js';
-import { DEFAULT_CONFIG, readConfig, CONFIG_FILE } from './chunk-DWL2IKZH.js';
-import { scanProject, expandFileGlobs } from './chunk-MTVEJ33D.js';
-import { ETYMD_DIR, writeCachedFacts, readBaseline, deriveProfile, baselineCarriesMachinePath, BASELINE_FILE } from './chunk-JHZ2BN4U.js';
-import { PACK_VERSION } from './chunk-LSZGCKIQ.js';
+import { measureContext, contextFileLabel } from './chunk-HI7NWPRA.js';
+import { scanProject, expandFileGlobs } from './chunk-HWC6PKJM.js';
+import { DEFAULT_CONFIG, ETYMD_DIR, writeCachedFacts, readBaseline, readConfig, deriveProfile, baselineCarriesMachinePath, BASELINE_FILE, CONFIG_FILE } from './chunk-P6ATKV2R.js';
+import { PACK_VERSION } from './chunk-YQZDYDAK.js';
 import { pathExists, readJson, readText, isDirectory, matchesAnyGlob, git, normalizeRelPath, isCiEnvironment, isExecutable } from './chunk-4VPBP6K6.js';
 import path from 'path';
 import YAML from 'yaml';
+import { execFile } from 'child_process';
+import { promisify } from 'util';
 import { promises } from 'fs';
 
 // src/engine/finding.ts
@@ -39,13 +40,15 @@ var contextEconomyLens = {
     const budgets = ctx.config?.config.context ?? DEFAULT_CONFIG.context;
     const budget = await measureContext(ctx.root, budgets.perFileWords);
     const findings = [];
+    const aliased = budget.files.filter((f) => f.aliases?.length);
     for (const f of budget.extractionCandidates) {
+      const label = contextFileLabel(f);
       findings.push({
         id: `${LENS_ID}/heavy-file:${f.path}`,
         lens: LENS_ID,
         tier: "gap",
-        claim: `${f.path} loads ${f.words} words (~${f.approxTokens} tokens) into every session`,
-        evidence: [`${f.path}: ${f.words} words`],
+        claim: `${label} loads ${f.words} words (~${f.approxTokens} tokens) into every session`,
+        evidence: [`${label}: ${f.words} words`],
         why: "Reference material that loads every session taxes attention and cost on tasks that never need it.",
         action: "Extract the reference bulk into an on-demand skill/doc and keep a pointer.",
         effort: "M",
@@ -58,7 +61,7 @@ var contextEconomyLens = {
         lens: LENS_ID,
         tier: "gap",
         claim: `The always-loaded footprint is ${budget.totalWords} words (~${budget.totalApproxTokens} tokens) \u2014 over the ${budgets.totalWords}-word budget`,
-        evidence: budget.files.slice(0, 5).map((f) => `${f.path}: ${f.words}w`),
+        evidence: budget.files.slice(0, 5).map((f) => `${contextFileLabel(f)}: ${f.words}w`),
         why: "Every session pays this before the task begins; instruction-following degrades as the resident context grows.",
         action: "Run `etymd context` for the per-file breakdown and extract the heaviest block.",
         effort: "M",
@@ -73,6 +76,9 @@ var contextEconomyLens = {
       status: "ran",
       disclosures: [
         ...ctx.config?.problems ?? [],
+        ...aliased.map(
+          (f) => `${contextFileLabel(f)} are one file (same inode) \u2014 counted once, at ${f.words} words.`
+        ),
         `Budgets: ${budgets.perFileWords} words/file, ${budgets.totalWords} words total (${budgets.perFileWords === DEFAULT_CONFIG.context.perFileWords && budgets.totalWords === DEFAULT_CONFIG.context.totalWords ? `defaults \u2014 override under \`context\` in ${CONFIG_FILE}` : `set in ${CONFIG_FILE}`}). Scoped Cursor rules excluded.`
       ],
       findings
@@ -473,6 +479,70 @@ async function buildGateInventory(root, facts) {
     commitlintDep
   };
 }
+var pExecFile = promisify(execFile);
+var HOOK_FILES = ["pre-commit", "pre-push", "commit-msg"];
+var SCREEN_CALL_RE = /"\$GATE"\s+screen\b/;
+var DEV_BUILD_ARM = "[ -x ./dist/cli.js ]";
+async function probeScreener(root, facts) {
+  const absent = {
+    present: false,
+    doors: [],
+    runner: null,
+    source: null,
+    answersScreen: null
+  };
+  const dir = facts.hooks.dir;
+  if (!dir) return absent;
+  const doors = [];
+  let devBuildArm = false;
+  for (const name of HOOK_FILES) {
+    const text = await readText(path.join(root, dir, name));
+    if (!text || !SCREEN_CALL_RE.test(text)) continue;
+    doors.push(`${dir}/${name}`);
+    if (text.includes(DEV_BUILD_ARM)) devBuildArm = true;
+  }
+  if (!doors.length) return absent;
+  let runner = null;
+  let source = null;
+  const override = process.env.CONTENT_GATE;
+  if (override) {
+    runner = override;
+    source = "CONTENT_GATE";
+  } else if (devBuildArm && await pathExists(path.join(root, "dist", "cli.js"))) {
+    runner = path.join(root, "dist", "cli.js");
+    source = "dev-build";
+  } else {
+    runner = "etymd";
+    source = "path";
+  }
+  try {
+    await pExecFile(runner, ["screen", "--help"], { cwd: root, timeout: 1e4 });
+    return { present: true, doors, runner, source, answersScreen: true };
+  } catch (err) {
+    const e = err;
+    if (e.code === "ENOENT") {
+      return {
+        present: true,
+        doors,
+        runner: null,
+        source,
+        answersScreen: null,
+        skipped: `no checker named \`${runner}\` is installed \u2014 the screen doors no-op here by design, and nothing was verified.`
+      };
+    }
+    if (e.killed || e.code === "ETIMEDOUT") {
+      return {
+        present: true,
+        doors,
+        runner,
+        source,
+        answersScreen: null,
+        skipped: `\`${runner} screen --help\` did not return within 10s \u2014 the runner was not verified either way.`
+      };
+    }
+    return { present: true, doors, runner, source, answersScreen: false };
+  }
+}
 
 // src/lenses/gate-integrity/lens.ts
 var LENS_ID2 = "gate-integrity";
@@ -616,6 +686,28 @@ function deriveGateFindings(inv, disclosures = []) {
 function localToolInHook(inv, tool) {
   return inv.local.preCommit.includes(tool) || inv.local.prePush.includes(tool) || inv.local.commitMsg.includes(tool);
 }
+function deriveScreenerFindings(probe, disclosures) {
+  if (!probe.present) return [];
+  if (probe.skipped) {
+    disclosures.push(`Content screen: ${probe.skipped}`);
+    return [];
+  }
+  if (probe.answersScreen !== false) return [];
+  const via = probe.source === "CONTENT_GATE" ? "resolved from the CONTENT_GATE override" : probe.source === "dev-build" ? "resolved to this repo's own ./dist/cli.js build" : "resolved from PATH";
+  return [
+    finding({
+      id: `${LENS_ID2}/content-screen-unrunnable`,
+      tier: "risk",
+      kind: "truth",
+      claim: `The content screen resolves to \`${probe.runner}\`, which does not understand \`screen\` \u2014 the gate cannot run`,
+      evidence: [...probe.doors, `${probe.runner} screen --help \u2192 failed (${via})`],
+      why: "The commit door fails closed on an error that explains nothing, and the push door \u2014 advisory by design \u2014 skips the whole-tree pass in silence, so the repo reads as screened when nothing screened it.",
+      action: "Install or upgrade etymd (`screen` needs 0.11+), or point CONTENT_GATE at a checker that provides it, then re-run `etymd gates` to refresh the hooks.",
+      effort: "S",
+      confidence: "high"
+    })
+  ];
+}
 var gateIntegrityLens = {
   id: LENS_ID2,
   version: "1",
@@ -656,6 +748,7 @@ var gateIntegrityLens = {
     if (inv.ci.system === "none")
       disclosures.push("No CI configuration found \u2014 CI\u2194local comparisons skipped.");
     const findings = deriveGateFindings(inv, disclosures);
+    findings.push(...deriveScreenerFindings(await probeScreener(ctx.root, ctx.facts), disclosures));
     return {
       lens: LENS_ID2,
       version: "1",
@@ -1186,8 +1279,23 @@ var KNOWN_DOC_REFS = [
   "DECISIONS.md",
   "GEMINI.md"
 ];
+var PATH_TOKEN_CHARS = /[A-Za-z0-9_.$~/-]/;
 function extractDocRefs(text) {
-  return KNOWN_DOC_REFS.filter((name) => text.includes(name));
+  const refs = [];
+  let tildeSkipped = 0;
+  for (const name of KNOWN_DOC_REFS) {
+    let claimed = false;
+    let at = text.indexOf(name);
+    while (at !== -1) {
+      let head = at;
+      while (head > 0 && PATH_TOKEN_CHARS.test(text[head - 1])) head -= 1;
+      if (text[head] === "~") tildeSkipped += 1;
+      else claimed = true;
+      at = text.indexOf(name, at + name.length);
+    }
+    if (claimed) refs.push(name);
+  }
+  return { refs, tildeSkipped };
 }
 
 // src/lenses/instruction-truth/lens.ts
@@ -1310,6 +1418,7 @@ var instructionTruthLens = {
     const nodeModulesInstalled = await pathExists(path.join(root, "node_modules"));
     const manifestExists = await pathExists(path.join(root, "package.json")) || facts.packages.length > 0;
     let totalFilteredSkipped = 0;
+    let totalTildeSkipped = 0;
     let binaryResolved = 0;
     let unverifiableCommands = 0;
     let gitignoredSkipped = 0;
@@ -1399,7 +1508,9 @@ var instructionTruthLens = {
           break;
         }
       }
-      for (const ref of extractDocRefs(file.text)) {
+      const { refs: docRefs, tildeSkipped } = extractDocRefs(file.text);
+      totalTildeSkipped += tildeSkipped;
+      for (const ref of docRefs) {
         if (await pathExists(path.join(root, ref))) continue;
         findings.push(
           finding2({
@@ -1504,6 +1615,11 @@ var instructionTruthLens = {
         `${placeholderSkipped} path claim(s) are naming stand-ins (e.g. \`my-custom-skill\`) rather than real references; skipped, not flagged.`
       );
     }
+    if (totalTildeSkipped) {
+      disclosures.push(
+        `${totalTildeSkipped} well-known doc mention(s) sit inside \`~/\` home paths (e.g. \`~/.claude/CLAUDE.md\`) \u2014 machine-global files, not this repo's; skipped, not flagged.`
+      );
+    }
     if (stateDocs.length) {
       disclosures.push(
         `Checked ${stateDocs.length} state document(s) for command, path, and decision-reference claims (same skip classes as instruction files); decision ids resolved against ${ledgerSources.length ? ledgerSources.join(", ") : "nothing \u2014 no decisions file with D-NNN entries"}.`
@@ -1531,7 +1647,7 @@ var instructionTruthLens = {
       );
     }
     disclosures.push(
-      `Checked ${files.length} instruction file(s); commands resolved against root + ${facts.packages.length} workspace manifest(s) plus installed binaries; paths matched against root and package roots. Heuristics: workspace-filtered commands skipped (${totalFilteredSkipped}); tokens without a recognized extension treated as prose (a dir claim needs a trailing slash); gitignored claims unverifiable; create-this and stand-in path claims skipped; absolute/globbed/placeholder tokens skipped; framework-pattern staleness not checked.`
+      `Checked ${files.length} instruction file(s); commands resolved against root + ${facts.packages.length} workspace manifest(s) plus installed binaries; paths matched against root and package roots. Heuristics: workspace-filtered commands skipped (${totalFilteredSkipped}); tokens without a recognized extension treated as prose (a dir claim needs a trailing slash); gitignored claims unverifiable; create-this and stand-in path claims skipped; absolute/globbed/placeholder tokens skipped; doc mentions inside \`~/\` home paths skipped; framework-pattern staleness not checked.`
     );
     return {
       lens: LENS_ID4,

package/dist/{chunk-DWL2IKZH.js → chunk-P6ATKV2R.js}

@@ -1,8 +1,70 @@
 #!/usr/bin/env node
-import { ETYMD_DIR } from './chunk-JHZ2BN4U.js';
-import { pathExists, readText } from './chunk-4VPBP6K6.js';
+import { readJson, pathExists, readText } from './chunk-4VPBP6K6.js';
 import path from 'path';
+import { promises } from 'fs';
 
+var ETYMD_DIR = ".etymd";
+var CACHE_DIR = path.join(ETYMD_DIR, "cache");
+var CACHE_FACTS_FILE = path.join(CACHE_DIR, "facts.json");
+var BASELINE_FILE = path.join(ETYMD_DIR, "baseline.json");
+function cacheFactsPath(root) {
+  return path.join(root, CACHE_FACTS_FILE);
+}
+function baselinePath(root) {
+  return path.join(root, BASELINE_FILE);
+}
+async function writeJsonFile(target, data) {
+  await promises.mkdir(path.dirname(target), { recursive: true });
+  await promises.writeFile(target, JSON.stringify(data, null, 2) + "\n", "utf8");
+  return target;
+}
+async function writeCachedFacts(root, facts) {
+  return writeJsonFile(cacheFactsPath(root), facts);
+}
+function withoutMachinePath(facts) {
+  return { ...facts, root: "." };
+}
+function baselineCarriesMachinePath(baseline) {
+  const root = baseline.facts?.root;
+  return typeof root === "string" && root !== "." && (root.startsWith("/") || /^[A-Za-z]:[\\/]/.test(root));
+}
+async function writeBaseline(root, baseline) {
+  return writeJsonFile(baselinePath(root), {
+    ...baseline,
+    facts: withoutMachinePath(baseline.facts)
+  });
+}
+async function readBaseline(root) {
+  return readJson(baselinePath(root));
+}
+function deriveProfile(facts) {
+  return (facts.git.recentAuthors ?? 1) > 2 ? "team" : "solo";
+}
+var DRIFT_ROLES = ["test", "lint", "typecheck", "format", "formatCheck", "build", "dev"];
+function summarizeBaselineDrift(old, fresh) {
+  const commands = [];
+  for (const role of DRIFT_ROLES) {
+    const from = old.commands[role];
+    const to = fresh.commands[role];
+    if (from !== to) commands.push({ role, from, to });
+  }
+  const presentIds = (f) => new Set(f.artifacts.filter((a) => a.exists).map((a) => a.id));
+  const oldArtifacts = presentIds(old);
+  const freshArtifacts = presentIds(fresh);
+  const labelOf = (id) => fresh.artifacts.find((a) => a.id === id)?.label ?? old.artifacts.find((a) => a.id === id)?.label ?? id;
+  const artifactsAdded = [...freshArtifacts].filter((id) => !oldArtifacts.has(id)).map(labelOf);
+  const artifactsRemoved = [...oldArtifacts].filter((id) => !freshArtifacts.has(id)).map(labelOf);
+  const oldDirs = new Set(old.tree.dirs.map((d) => d.name));
+  const freshDirs = new Set(fresh.tree.dirs.map((d) => d.name));
+  const dirsAdded = [...freshDirs].filter((d) => !oldDirs.has(d));
+  const dirsRemoved = [...oldDirs].filter((d) => !freshDirs.has(d));
+  return { commands, artifactsAdded, artifactsRemoved, dirsAdded, dirsRemoved };
+}
+function isDriftEmpty(d) {
+  return d.commands.length === 0 && d.artifactsAdded.length === 0 && d.artifactsRemoved.length === 0 && d.dirsAdded.length === 0 && d.dirsRemoved.length === 0;
+}
+
+// src/core/config.ts
 var CONFIG_FILE = path.join(ETYMD_DIR, "config.json");
 var DEFAULT_CONFIG = {
   instructions: { include: [], exclude: [] },
@@ -106,4 +168,4 @@ async function readConfig(root) {
   };
 }
 
-export { CONFIG_FILE, DEFAULT_CONFIG, configPath, readConfig };
+export { BASELINE_FILE, CACHE_DIR, CONFIG_FILE, DEFAULT_CONFIG, ETYMD_DIR, baselineCarriesMachinePath, configPath, deriveProfile, isDriftEmpty, readBaseline, readConfig, summarizeBaselineDrift, writeBaseline, writeCachedFacts };

package/dist/{chunk-SWA4NQHB.js → chunk-PAMWS665.js}

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
-import { parseFailOnTier, runAudit, meetsFailOn } from './chunk-O3PHW4OP.js';
-import { print, section, theme, renderLensCoverage, renderFindings, renderLedgerDiff } from './chunk-5BVKFJWM.js';
+import { parseFailOnTier, runAudit, meetsFailOn } from './chunk-LT7JMVV3.js';
+import { print, section, theme, renderLensCoverage, renderFindings, renderLedgerDiff } from './chunk-HI7NWPRA.js';
 
 // src/commands/audit.ts
 async function run(opts) {