etymd 0.1.0

package/dist/index.js

@@ -0,0 +1,2095 @@
+import path from 'node:path';
+import { promises } from 'node:fs';
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import YAML from 'yaml';
+
+// src/core/scan.ts
+
+// src/pack/version.ts
+var PACK_VERSION = "2";
+
+// package.json
+var package_default = {
+  name: "etymd",
+  version: "0.1.0"};
+
+// src/version.ts
+var VERSION = package_default.version;
+var NAME = package_default.name;
+var pExecFile = promisify(execFile);
+async function pathExists(p) {
+  try {
+    await promises.access(p);
+    return true;
+  } catch {
+    return false;
+  }
+}
+async function readJson(p) {
+  try {
+    const raw = await promises.readFile(p, "utf8");
+    return JSON.parse(raw);
+  } catch {
+    return null;
+  }
+}
+async function readText(p) {
+  try {
+    return await promises.readFile(p, "utf8");
+  } catch {
+    return null;
+  }
+}
+async function isDirectory(p) {
+  try {
+    return (await promises.stat(p)).isDirectory();
+  } catch {
+    return false;
+  }
+}
+async function git(root, args) {
+  try {
+    const { stdout } = await pExecFile("git", args, { cwd: root, timeout: 4e3 });
+    return stdout.trim();
+  } catch {
+    return null;
+  }
+}
+function wordCount(text) {
+  const m = text.trim().match(/\S+/g);
+  return m ? m.length : 0;
+}
+function approxTokens(words) {
+  return Math.round(words / 0.75);
+}
+var CI_ENV_VARS = [
+  "CI",
+  "GITHUB_ACTIONS",
+  "GITLAB_CI",
+  "BUILDKITE",
+  "CIRCLECI",
+  "JENKINS_URL",
+  "TF_BUILD"
+];
+function isCiEnvironment() {
+  return CI_ENV_VARS.some((v) => Boolean(process.env[v]));
+}
+function normalizeRelPath(p) {
+  return p.replace(/\\/g, "/").replace(/^\.\//, "").replace(/\/+$/, "");
+}
+function globToRegExp(glob) {
+  let re = "";
+  for (let i = 0; i < glob.length; i++) {
+    const c = glob[i];
+    if (c === "*") {
+      if (glob[i + 1] === "*") {
+        i += 1;
+        if (glob[i + 1] === "/") {
+          i += 1;
+          re += "(?:.*/)?";
+        } else {
+          re += ".*";
+        }
+      } else {
+        re += "[^/]*";
+      }
+    } else if (c === "?") {
+      re += "[^/]";
+    } else {
+      re += c.replace(/[.+^${}()|[\]\\]/g, "\\$&");
+    }
+  }
+  return new RegExp(`^${re}$`);
+}
+function matchesGlob(p, glob) {
+  const target = normalizeRelPath(p);
+  const pattern = normalizeRelPath(glob);
+  if (!pattern) return false;
+  if (!/[*?]/.test(pattern)) return target === pattern || target.startsWith(pattern + "/");
+  return globToRegExp(pattern).test(target);
+}
+function matchesAnyGlob(p, globs) {
+  return globs.some((g) => matchesGlob(p, g));
+}
+
+// src/core/detect.ts
+var IGNORED_DIRS = /* @__PURE__ */ new Set([
+  "node_modules",
+  ".git",
+  "dist",
+  "build",
+  "coverage",
+  ".next",
+  ".turbo",
+  ".cache",
+  ".pnpm",
+  "out"
+]);
+var MEANINGFUL_DOT_DIRS = /* @__PURE__ */ new Set([
+  ".github",
+  ".gitlab",
+  ".claude",
+  ".cursor",
+  ".githooks",
+  ".husky",
+  ".changeset",
+  ".vscode",
+  ".storybook"
+]);
+async function detectPackageManager(root, pkg) {
+  if (pkg?.packageManager) {
+    const name = pkg.packageManager.split("@")[0];
+    if (name === "pnpm" || name === "yarn" || name === "npm" || name === "bun") return name;
+  }
+  const lock = [
+    ["pnpm-lock.yaml", "pnpm"],
+    ["yarn.lock", "yarn"],
+    ["package-lock.json", "npm"],
+    ["bun.lockb", "bun"]
+  ];
+  for (const [file, pm] of lock) {
+    if (await pathExists(path.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 (pnpmWs) {
+    const globs = pnpmWs.split("\n").map((l) => l.match(/^\s*-\s*["']?([^"'#]+)["']?/)?.[1]?.trim()).filter((g) => Boolean(g));
+    return { kind: "pnpm", packageGlobs: globs };
+  }
+  if (pkg?.workspaces) {
+    const globs = Array.isArray(pkg.workspaces) ? pkg.workspaces : pkg.workspaces.packages ?? [];
+    return {
+      kind: pkg.packageManager?.startsWith("yarn") ? "yarn" : "npm",
+      packageGlobs: globs
+    };
+  }
+  return { kind: "none", packageGlobs: [] };
+}
+async function listWorkspacePackages(root, globs) {
+  const found = [];
+  const seen = /* @__PURE__ */ new Set();
+  const addFromDir = async (dir) => {
+    const pkgPath = path.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) || ".",
+      private: Boolean(pkg.private),
+      version: pkg.version
+    });
+  };
+  for (const glob of globs) {
+    const base = glob.replace(/\/\*\*?$/, "");
+    const parent = path.join(root, base);
+    if (!await isDirectory(parent)) continue;
+    let entries;
+    try {
+      entries = await promises.readdir(parent);
+    } catch {
+      continue;
+    }
+    for (const entry of entries) {
+      if (IGNORED_DIRS.has(entry) || entry.startsWith(".")) continue;
+      const child = path.join(parent, entry);
+      if (await isDirectory(child)) await addFromDir(child);
+    }
+  }
+  return found.sort((a, b) => a.dir.localeCompare(b.dir));
+}
+async function expandFileGlobs(root, globs, cap = 500) {
+  if (!globs.length) return [];
+  const out = /* @__PURE__ */ new Set();
+  const walk = async (rel) => {
+    if (out.size >= cap) return;
+    let entries;
+    try {
+      entries = await promises.readdir(path.join(root, rel), { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const entry of entries) {
+      if (out.size >= cap) return;
+      if (IGNORED_DIRS.has(entry.name)) continue;
+      const child = rel ? `${rel}/${entry.name}` : entry.name;
+      if (entry.isDirectory()) await walk(child);
+      else if (entry.isFile() && matchesAnyGlob(child, globs)) out.add(child);
+    }
+  };
+  const roots = /* @__PURE__ */ new Set();
+  for (const glob of globs) {
+    const segments = normalizeRelPath(glob).split("/");
+    const literal = [];
+    for (const seg of segments) {
+      if (/[*?]/.test(seg)) break;
+      literal.push(seg);
+    }
+    if (literal.length === segments.length) literal.pop();
+    roots.add(literal.join("/"));
+  }
+  const minimal = [...roots].filter(
+    (r) => ![...roots].some((other) => other !== r && (other === "" || r.startsWith(other + "/")))
+  );
+  for (const r of minimal) {
+    if (r && !await isDirectory(path.join(root, r))) continue;
+    await walk(r);
+  }
+  return [...out].sort();
+}
+var isMeta = (value) => /npm-run-all|run-s\b|run-p\b|concurrently|&&/.test(value);
+var ROLE_LADDERS = [
+  {
+    role: "formatCheck",
+    ladder: [
+      (k) => /^format:check$/.test(k),
+      (k) => /^test:format(:local)?$/.test(k),
+      (k) => /^(prettier:check|check:format|format:ci)$/.test(k),
+      (_k, v) => /prettier(\s|.*\s)(-l\b|--check)/.test(v)
+    ]
+  },
+  {
+    role: "typecheck",
+    exclude: /generate|codegen|build|emit|watch/,
+    ladder: [
+      (k) => /^(typecheck|type-check)$/.test(k),
+      (k) => /^test:types(:local)?$/.test(k),
+      (k) => /^(types|check:types|types:check)$/.test(k),
+      (_k, v) => /tsc\b.*--noemit/i.test(v)
+    ]
+  },
+  {
+    role: "test",
+    exclude: /watch|coverage|snapshot|e2e|integration|debug|notsilent|mdx/,
+    ladder: [
+      (k) => /^test:unit(:local|:ci)?$/.test(k),
+      (k) => /^test:jest$/.test(k),
+      (k, v) => /^test$/.test(k) && !isMeta(v),
+      (k) => /^test$/.test(k)
+    ]
+  },
+  {
+    role: "lint",
+    exclude: /fix|format|staged|watch|style/,
+    ladder: [
+      (k) => /^lint$/.test(k),
+      (k) => /^test:lint(:local)?$/.test(k),
+      (k) => /^lint:/.test(k),
+      (_k, v) => /eslint\b/.test(v) && !/--fix/.test(v)
+    ]
+  },
+  {
+    role: "format",
+    exclude: /check|:ci$/,
+    ladder: [
+      (k) => /^format$/.test(k),
+      (k) => /^(format:write|format:prettier|format:fix|prettier)$/.test(k),
+      (_k, v) => /prettier\b.*--write/.test(v)
+    ]
+  },
+  {
+    role: "build",
+    exclude: /watch|storybook/,
+    ladder: [(k) => /^build$/.test(k), (k) => /^build:/.test(k)]
+  },
+  {
+    role: "dev",
+    ladder: [(k) => /^dev$/.test(k), (k) => /^start$/.test(k), (k) => /^dev:/.test(k)]
+  }
+];
+function classifyCommands(scripts = {}) {
+  const out = { raw: scripts };
+  const entries = Object.entries(scripts);
+  for (const { role, exclude, ladder } of ROLE_LADDERS) {
+    for (const pattern of ladder) {
+      const hit = entries.find(([k, v]) => !exclude?.test(k) && pattern(k, v));
+      if (hit) {
+        out[role] = hit[0];
+        break;
+      }
+    }
+  }
+  return out;
+}
+var FRAMEWORK_MARKERS = [
+  ["next", "Next.js"],
+  ["@tanstack/react-start", "TanStack Start"],
+  ["@tanstack/start", "TanStack Start"],
+  ["@tanstack/react-router", "TanStack Router"],
+  ["react", "React"],
+  ["vue", "Vue"],
+  ["svelte", "Svelte"],
+  ["@angular/core", "Angular"],
+  ["express", "Express"],
+  ["fastify", "Fastify"],
+  ["@nestjs/core", "NestJS"],
+  ["@trpc/server", "tRPC"],
+  ["vite", "Vite"],
+  ["react-scripts", "CRA"],
+  ["@apollo/client", "Apollo"],
+  ["drizzle-orm", "Drizzle"],
+  ["prisma", "Prisma"],
+  ["@sanity/client", "Sanity"],
+  ["nx", "Nx"]
+];
+function detectFrameworks(pkg) {
+  if (!pkg) return [];
+  const deps = { ...pkg.dependencies, ...pkg.devDependencies };
+  const out = [];
+  for (const [marker, label] of FRAMEWORK_MARKERS) {
+    if (deps[marker] && !out.includes(label)) out.push(label);
+  }
+  return out;
+}
+async function detectCi(root) {
+  if (await pathExists(path.join(root, ".gitlab-ci.yml"))) {
+    return { system: "gitlab", files: [".gitlab-ci.yml"] };
+  }
+  const workflows = path.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));
+      if (files.length) return { system: "github", files };
+    } catch {
+    }
+  }
+  return { system: "none", files: [] };
+}
+async function hasLintStagedConfig(root, pkg) {
+  if (pkg && pkg["lint-staged"]) return true;
+  for (const f of [
+    ".lintstagedrc",
+    ".lintstagedrc.json",
+    ".lintstagedrc.js",
+    "lint-staged.config.js"
+  ]) {
+    if (await pathExists(path.join(root, f))) return true;
+  }
+  return false;
+}
+async function detectHooks(root, hooksPath, pkg) {
+  const lintStaged = await hasLintStagedConfig(root, pkg);
+  if (hooksPath) {
+    if (hooksPath.replace(/\/+$/, "") === ".husky/_") {
+      const base2 = path.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")),
+        lintStaged
+      };
+    }
+    const base = path.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")),
+      lintStaged
+    };
+  }
+  if (await isDirectory(path.join(root, ".githooks"))) {
+    const base = path.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")),
+      lintStaged
+    };
+  }
+  if (await isDirectory(path.join(root, ".husky"))) {
+    const base = path.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")),
+      lintStaged
+    };
+  }
+  const legacyHooks = pkg?.husky?.hooks;
+  const configText = legacyHooks ? null : await readText(path.join(root, "husky.config.js"));
+  if (legacyHooks || configText) {
+    const hookNamed = (name) => legacyHooks ? Boolean(legacyHooks[name]) : Boolean(configText && configText.includes(name));
+    return {
+      source: "husky-legacy",
+      preCommit: hookNamed("pre-commit"),
+      prePush: hookNamed("pre-push"),
+      commitMsg: hookNamed("commit-msg"),
+      lintStaged
+    };
+  }
+  return { source: "none", preCommit: false, prePush: false, commitMsg: false, lintStaged };
+}
+var ARTIFACT_SPECS = [
+  { id: "agents", label: "AGENTS.md (operating contract)", path: "AGENTS.md", kind: "contract" },
+  {
+    id: "project-context",
+    label: "PROJECT_CONTEXT.md (ground-truth state)",
+    path: "PROJECT_CONTEXT.md",
+    kind: "state"
+  },
+  { id: "claude", label: "CLAUDE.md (Claude Code pointer)", path: "CLAUDE.md", kind: "adapter" },
+  {
+    id: "copilot",
+    label: "Copilot instructions",
+    path: ".github/copilot-instructions.md",
+    kind: "adapter"
+  },
+  {
+    id: "cursorrules",
+    label: ".cursorrules (legacy Cursor)",
+    path: ".cursorrules",
+    kind: "adapter"
+  },
+  { id: "cursor-rules", label: ".cursor/rules", path: ".cursor/rules", kind: "adapter" },
+  { id: "gemini", label: "GEMINI.md", path: "GEMINI.md", kind: "adapter" },
+  { id: "cline", label: ".clinerules", path: ".clinerules", kind: "adapter" },
+  { id: "windsurf", label: ".windsurfrules", path: ".windsurfrules", kind: "adapter" },
+  { id: "skills", label: "Agent skills (.claude/skills)", path: ".claude/skills", kind: "skill" },
+  {
+    id: "failure-modes-skill",
+    label: "Failure-modes register (skill)",
+    path: ".claude/skills/failure-modes",
+    kind: "skill"
+  },
+  {
+    id: "failure-modes-doc",
+    label: "Failure-modes register (doc)",
+    path: "docs/failure-modes.md",
+    kind: "other"
+  },
+  {
+    id: "sessions",
+    label: "Session archive (docs/sessions)",
+    path: "docs/sessions",
+    kind: "sessions"
+  },
+  { id: "githooks", label: "Tracked git hooks (.githooks)", path: ".githooks", kind: "gate" },
+  {
+    id: "inventory",
+    label: "Reuse inventory (docs/INVENTORY.md)",
+    path: "docs/INVENTORY.md",
+    kind: "map"
+  }
+];
+async function detectArtifacts(root) {
+  return Promise.all(
+    ARTIFACT_SPECS.map(async (spec) => ({
+      ...spec,
+      exists: await pathExists(path.join(root, spec.path))
+    }))
+  );
+}
+async function walkTree(root) {
+  const state = { budget: 2e4, truncated: false };
+  const countFiles = async (dir) => {
+    if (state.budget <= 0) {
+      state.truncated = true;
+      return 0;
+    }
+    let total = 0;
+    let entries;
+    try {
+      entries = await promises.readdir(dir, { withFileTypes: true });
+    } catch {
+      return 0;
+    }
+    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));
+      } else if (entry.isFile()) {
+        total += 1;
+        state.budget -= 1;
+        if (state.budget <= 0) {
+          state.truncated = true;
+          break;
+        }
+      }
+    }
+    return total;
+  };
+  let top;
+  try {
+    top = await promises.readdir(root, { withFileTypes: true });
+  } catch {
+    return { dirs: [], truncated: false };
+  }
+  const dirs = [];
+  for (const entry of top) {
+    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.sort((a, b) => b.files - a.files);
+  return { dirs, truncated: state.truncated };
+}
+
+// src/core/scan.ts
+function inferTicketKey(subjects) {
+  const counts = /* @__PURE__ */ new Map();
+  for (const m of subjects.matchAll(/\b([A-Z][A-Z0-9]{1,9})-\d+\b/g)) {
+    const key = m[1];
+    counts.set(key, (counts.get(key) ?? 0) + 1);
+  }
+  let best;
+  let bestCount = 0;
+  for (const [key, count] of counts) {
+    if (count > bestCount) {
+      best = key;
+      bestCount = count;
+    }
+  }
+  return bestCount >= 3 ? best : void 0;
+}
+async function scanProject(root) {
+  const abs = path.resolve(root);
+  const rootPkg = await readJson(path.join(abs, "package.json"));
+  const [packageManager, workspace, ci, artifacts, tree, isRepo] = await Promise.all([
+    detectPackageManager(abs, rootPkg),
+    detectWorkspace(abs, rootPkg),
+    detectCi(abs),
+    detectArtifacts(abs),
+    walkTree(abs),
+    git(abs, ["rev-parse", "--is-inside-work-tree"]).then((r) => r === "true")
+  ]);
+  const [branch, head, hooksPathRaw, authorsRaw, subjectsRaw] = isRepo ? await Promise.all([
+    git(abs, ["rev-parse", "--abbrev-ref", "HEAD"]),
+    git(abs, ["rev-parse", "--short", "HEAD"]),
+    git(abs, ["config", "--get", "core.hooksPath"]),
+    git(abs, ["log", "-200", "--format=%ae"]),
+    git(abs, ["log", "-50", "--format=%s"])
+  ]) : [null, null, null, null, null];
+  const hooksPath = hooksPathRaw ?? void 0;
+  const hooks = await detectHooks(abs, hooksPath, rootPkg);
+  const packages = workspace.packageGlobs.length ? await listWorkspacePackages(abs, workspace.packageGlobs) : [];
+  const recentAuthors = authorsRaw ? new Set(authorsRaw.split("\n").filter(Boolean)).size : void 0;
+  return {
+    etymdVersion: VERSION,
+    packVersion: PACK_VERSION,
+    generatedAt: (/* @__PURE__ */ new Date()).toISOString(),
+    root: abs,
+    name: rootPkg?.name ?? path.basename(abs),
+    git: {
+      isRepo,
+      branch: branch ?? void 0,
+      head: head ?? void 0,
+      hooksPath,
+      husky: hooks.source === "husky" || hooks.source === "husky-legacy",
+      recentAuthors,
+      ticketKey: subjectsRaw ? inferTicketKey(subjectsRaw) : void 0
+    },
+    packageManager,
+    node: rootPkg?.engines?.node,
+    workspace: { kind: workspace.kind, packageGlobs: workspace.packageGlobs },
+    packages,
+    frameworks: detectFrameworks(rootPkg),
+    commands: classifyCommands(rootPkg?.scripts),
+    ci,
+    hooks,
+    artifacts,
+    tree
+  };
+}
+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);
+}
+async function readCachedFacts(root) {
+  return readJson(cacheFactsPath(root));
+}
+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";
+}
+
+// src/core/config.ts
+var CONFIG_FILE = path.join(ETYMD_DIR, "config.json");
+var DEFAULT_CONFIG = {
+  instructions: { include: [], exclude: [] },
+  context: { perFileWords: 4e3, totalWords: 8e3 }
+};
+function configPath(root) {
+  return path.join(root, CONFIG_FILE);
+}
+function readGlobList(value, key, problems) {
+  if (value === void 0) return void 0;
+  if (!Array.isArray(value) || value.some((v) => typeof v !== "string")) {
+    problems.push(`${CONFIG_FILE}: \`${key}\` must be an array of glob strings \u2014 ignored.`);
+    return void 0;
+  }
+  return value.map((g) => g.trim()).filter(Boolean);
+}
+function readBudget(value, key, problems) {
+  if (value === void 0) return void 0;
+  if (typeof value !== "number" || !Number.isFinite(value) || value <= 0) {
+    problems.push(`${CONFIG_FILE}: \`${key}\` must be a positive number \u2014 ignored.`);
+    return void 0;
+  }
+  return value;
+}
+async function readConfig(root) {
+  const target = configPath(root);
+  const problems = [];
+  if (!await pathExists(target)) {
+    return { config: DEFAULT_CONFIG, present: false, problems };
+  }
+  const raw = await readText(target);
+  let parsed;
+  try {
+    parsed = JSON.parse(raw ?? "");
+  } catch (err) {
+    problems.push(
+      `${CONFIG_FILE} exists but is not valid JSON (${err instanceof Error ? err.message : String(err)}) \u2014 defaults used.`
+    );
+    return { config: DEFAULT_CONFIG, present: true, problems };
+  }
+  if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+    problems.push(`${CONFIG_FILE} must contain a JSON object \u2014 defaults used.`);
+    return { config: DEFAULT_CONFIG, present: true, problems };
+  }
+  const obj = parsed;
+  const instructions = obj.instructions ?? {};
+  const context = obj.context ?? {};
+  return {
+    present: true,
+    problems,
+    config: {
+      instructions: {
+        include: readGlobList(instructions.include, "instructions.include", problems) ?? DEFAULT_CONFIG.instructions.include,
+        exclude: readGlobList(instructions.exclude, "instructions.exclude", problems) ?? DEFAULT_CONFIG.instructions.exclude
+      },
+      context: {
+        perFileWords: readBudget(context.perFileWords, "context.perFileWords", problems) ?? DEFAULT_CONFIG.context.perFileWords,
+        totalWords: readBudget(context.totalWords, "context.totalWords", problems) ?? DEFAULT_CONFIG.context.totalWords
+      }
+    }
+  };
+}
+
+// src/core/context.ts
+var ALWAYS_LOADED = [
+  { path: "AGENTS.md", role: "operating contract" },
+  { 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 measureContext(root, perFileWords = EXTRACTION_THRESHOLD) {
+  const files = [];
+  for (const spec of ALWAYS_LOADED) {
+    const abs = path.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");
+  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;
+        const words = wordCount(text);
+        files.push({
+          path: `.cursor/rules/${entry}`,
+          role: "Cursor rule (always applied)",
+          words,
+          approxTokens: approxTokens(words)
+        });
+      }
+    } 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)
+  };
+}
+
+// src/pack/templates.ts
+function runPrefix(pm) {
+  switch (pm) {
+    case "pnpm":
+      return "pnpm";
+    case "yarn":
+      return "yarn";
+    case "bun":
+      return "bun run";
+    case "npm":
+    case "unknown":
+    default:
+      return "npm run";
+  }
+}
+function isSafeGateCommand(value) {
+  if (!value) return false;
+  return !/--write|--fix|\bcodegen\b|\bgenerate\b|-w\s|--watch/.test(value);
+}
+function mapVerifyCommand(facts) {
+  switch (facts.workspace.kind) {
+    case "nx":
+      return `${facts.packageManager === "yarn" ? "yarn" : "npx"} nx show projects`;
+    case "pnpm":
+      return "pnpm -r ls --depth -1";
+    case "yarn":
+      return "yarn workspaces info";
+    case "npm":
+      return "npm ls --workspaces --depth=0";
+    case "turbo":
+    case "lerna":
+      return "git ls-files '*/package.json'";
+    default:
+      return "git ls-files | head -50";
+  }
+}
+function doneDefinition(facts) {
+  const run = runPrefix(facts.packageManager);
+  const parts = [];
+  const c = facts.commands;
+  const formatCmd = c.formatCheck ?? (isSafeGateCommand(c.format ? c.raw[c.format] : void 0) ? c.format : void 0);
+  if (formatCmd) parts.push(`\`${run} ${formatCmd}\``);
+  if (c.typecheck) parts.push(`\`${run} ${c.typecheck}\``);
+  if (c.lint) parts.push(`\`${run} ${c.lint}\``);
+  if (c.test) parts.push(`\`${run} ${c.test}\``);
+  return parts;
+}
+function generateAgentsMd(facts) {
+  const run = runPrefix(facts.packageManager);
+  const done = doneDefinition(facts);
+  const frameworks = facts.frameworks.length ? facts.frameworks.join(", ") : "none detected";
+  const workspace = facts.workspace.kind === "none" ? "single package" : `${facts.workspace.kind} workspace`;
+  const topDirs = facts.tree.dirs.slice(0, 14);
+  return `# AGENTS.md
+
+Operating contract for AI agents working in **${facts.name}**. One source of truth \u2014 most agents
+(Claude Code, Codex, Cursor, Copilot, Gemini, \u2026) read this file natively. Kept true by
+[etymd](https://www.npmjs.com/package/etymd): the commands, paths, and claims below are audited
+against the actual repo \u2014 update this file when the repo changes, or \`etymd audit\` will tell you.
+
+## What this project is
+
+<!-- One paragraph: what this does and who it is for. Run \`etymd brief\` to have your agent
+draft it from the reckoning; refine by hand. -->
+
+## Stack
+
+- **Shape:** ${workspace}${facts.packages.length ? ` (${facts.packages.length} packages)` : ""}, package manager **${facts.packageManager}**${facts.node ? `, Node ${facts.node}` : ""}.
+- **Frameworks:** ${frameworks}.
+- **CI:** ${facts.ci.system === "none" ? "none detected" : facts.ci.system}.
+
+## Working rules
+
+- **Reuse-first.** Before writing any new helper/component/type: check the map below and the
+  surrounding code \u2014 a "new" thing usually exists.
+- **Minimal diffs.** Never touch files outside the task's scope.
+<!-- Add your project's own rules: commit/branch conventions, what the agent may and may not do,
+org tooling constraints. Keep every rule TRUE \u2014 stale rules erode trust in the rest. -->
+
+## Repo map
+
+> **Advisory, not authoritative** \u2014 re-verify with \`${mapVerifyCommand(facts)}\` before
+> structure-sensitive changes, and update this section in the same change that moves files.
+
+${topDirs.length ? topDirs.map((d) => `- \`${d.name}/\` \u2014 ${d.files} files`).join("\n") : "- (single package; list the key files here)"}
+
+## Done =
+
+${done.length ? `A change is done when these are green:
+
+${done.map((d) => `- ${d}`).join("\n")}` : `Define the check commands that gate a change (test / lint / typecheck / format).`}
+
+## Commands
+
+\`\`\`bash
+${[
+    facts.commands.dev && `${run} ${facts.commands.dev}`,
+    facts.commands.build && `${run} ${facts.commands.build}`,
+    facts.commands.test && `${run} ${facts.commands.test}`,
+    facts.commands.lint && `${run} ${facts.commands.lint}`,
+    facts.commands.typecheck && `${run} ${facts.commands.typecheck}`
+  ].filter(Boolean).join("\n") || "# add the project's key commands"}
+\`\`\`
+
+<!-- etymd pack v${PACK_VERSION} -->
+`;
+}
+function generatePreCommitHook() {
+  return `#!/usr/bin/env sh
+# etymd: process gate. Cheap, locally-knowable checks belong here (fast, blocks the commit).
+exit 0
+`;
+}
+function generatePrePushHook(facts) {
+  const run = runPrefix(facts.packageManager);
+  const c = facts.commands;
+  const candidates = [c.formatCheck, c.typecheck, c.lint];
+  const steps = candidates.filter((key) => Boolean(key) && isSafeGateCommand(c.raw[key])).map((key) => `${run} ${key}`);
+  const body = steps.length ? steps.map((s) => `echo "\u203A ${s}"
+${s} || exit 1`).join("\n") : 'echo "etymd: no correctness commands detected \u2014 add format:check / typecheck / lint"';
+  return `#!/usr/bin/env sh
+# etymd: correctness gate. Mirrors CI cheapest-first; blocks the push on any failure.
+${body}
+`;
+}
+
+// src/core/generate.ts
+async function planWorkflow(root, facts, opts) {
+  const out = [];
+  const add = async (rel, contents, label, executable = false) => {
+    const abs = path.join(root, rel);
+    const exists = await pathExists(abs);
+    const existing = exists ? await readText(abs) : null;
+    out.push({
+      path: rel,
+      contents,
+      exists,
+      differs: exists ? existing !== contents : void 0,
+      executable,
+      label
+    });
+  };
+  if (opts.agents) {
+    await add("AGENTS.md", generateAgentsMd(facts), "Minimal operating contract (scaffold)");
+  }
+  if (opts.gates) {
+    await add(".githooks/pre-commit", generatePreCommitHook(), "Process gate (pre-commit)", true);
+    await add(".githooks/pre-push", generatePrePushHook(facts), "Correctness gate (pre-push)", true);
+  }
+  return out;
+}
+async function applyFiles(root, files, overwrite = /* @__PURE__ */ new Set()) {
+  const written = [];
+  const skipped = [];
+  for (const file of files) {
+    if (file.exists && !overwrite.has(file.path)) {
+      skipped.push(file.path);
+      continue;
+    }
+    const abs = path.join(root, file.path);
+    await promises.mkdir(path.dirname(abs), { recursive: true });
+    await promises.writeFile(abs, file.contents, "utf8");
+    if (file.executable) await promises.chmod(abs, 493);
+    written.push(file.path);
+  }
+  return { written, skipped };
+}
+
+// src/lenses/context-economy.ts
+var LENS_ID = "context-economy";
+var TOTAL_BUDGET_WORDS = DEFAULT_CONFIG.context.totalWords;
+var contextEconomyLens = {
+  id: LENS_ID,
+  version: "1",
+  title: "Context economy",
+  kind: "improvement",
+  async run(ctx) {
+    const budgets = ctx.config?.config.context ?? DEFAULT_CONFIG.context;
+    const budget = await measureContext(ctx.root, budgets.perFileWords);
+    const findings = [];
+    for (const f of budget.extractionCandidates) {
+      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`],
+        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",
+        confidence: "high"
+      });
+    }
+    if (budget.totalWords >= budgets.totalWords) {
+      findings.push({
+        id: `${LENS_ID}/total-over-budget`,
+        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`),
+        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",
+        confidence: "high"
+      });
+    }
+    return {
+      lens: LENS_ID,
+      version: "1",
+      title: "Context economy",
+      kind: "improvement",
+      status: "ran",
+      disclosures: [
+        ...ctx.config?.problems ?? [],
+        `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
+    };
+  }
+};
+var TOOL_MATCHERS = [
+  ["sonar", /sonar-scanner|sonarqube|\bsonar\b/i],
+  ["codecov", /codecov/i],
+  ["commitlint", /commitlint/],
+  ["chromatic", /chromatic/],
+  ["size", /size-limit|bundlesize/],
+  ["e2e", /\bcypress\b|\bplaywright\b/],
+  ["coverage", /--coverage|\bnyc\b|\bc8\b/],
+  ["format-check", /prettier[^&|;]*(\s-l\b|\s--check)|format:check/],
+  ["format-write", /prettier[^&|;]*--write|--fix\b/],
+  ["typecheck", /\btsc\b(?![^&|;]*--watch)/],
+  ["lint", /\beslint\b/],
+  ["test", /\bjest\b|\bvitest\b|react-scripts test|\bnx\b[^&|;]*\btest\b/]
+];
+function expandScriptRefs(command, scripts, depth = 2) {
+  if (depth <= 0) return command;
+  let expanded = command;
+  for (const m of command.matchAll(
+    /(?:yarn|pnpm|npm run|bun run|npx run-s|npx run-p)\s+([A-Za-z0-9:._-]+)/g
+  )) {
+    const name = m[1];
+    const body = scripts[name];
+    if (body) expanded += `
+${expandScriptRefs(body, scripts, depth - 1)}`;
+  }
+  if (/npm-run-all|run-s|run-p/.test(command)) {
+    for (const token of command.split(/\s+/)) {
+      const clean = token.replace(/["']/g, "");
+      const body = scripts[clean];
+      if (body) expanded += `
+${expandScriptRefs(body, scripts, depth - 1)}`;
+    }
+  }
+  return expanded;
+}
+function matchTools(command, scripts) {
+  const expanded = expandScriptRefs(command, scripts);
+  const tools = /* @__PURE__ */ new Set();
+  for (const [tool, re] of TOOL_MATCHERS) {
+    if (re.test(expanded)) tools.add(tool);
+  }
+  return [...tools];
+}
+var GITLAB_TAGS = [
+  { tag: "!reference", collection: "seq", resolve: () => [] }
+];
+var GITLAB_RESERVED = /* @__PURE__ */ new Set([
+  "stages",
+  "variables",
+  "include",
+  "default",
+  "workflow",
+  "image",
+  "services",
+  "before_script",
+  "after_script",
+  "cache",
+  "types"
+]);
+function looksLikeJob(job) {
+  return job.script !== void 0 || job.before_script !== void 0 || job.extends !== void 0 || job.stage !== void 0 || job.image !== void 0 || job.trigger !== void 0 || job.rules !== void 0 || job.needs !== void 0 || job.allow_failure !== void 0;
+}
+function inferToolsFromShape(name, job) {
+  const tools = /* @__PURE__ */ new Set();
+  if (/sonar/i.test(name)) tools.add("sonar");
+  if (/chromatic/i.test(name)) tools.add("chromatic");
+  if (job.variables && typeof job.variables === "object") {
+    for (const key of Object.keys(job.variables)) {
+      if (key.startsWith("SONAR_")) tools.add("sonar");
+    }
+  }
+  return [...tools];
+}
+function asLines(value) {
+  if (typeof value === "string") return [value];
+  if (Array.isArray(value)) return value.filter((v) => typeof v === "string");
+  return [];
+}
+function parseGitlabCi(text, file, scripts) {
+  const parseErrors = [];
+  let doc;
+  try {
+    doc = YAML.parse(text, { customTags: GITLAB_TAGS, logLevel: "silent" });
+  } catch (err) {
+    parseErrors.push(
+      `${file}: ${err instanceof Error ? err.message.split("\n")[0] : "unparseable YAML"}`
+    );
+    return { jobs: [], inheritedIncludes: [], parseErrors };
+  }
+  if (!doc || typeof doc !== "object") return { jobs: [], inheritedIncludes: [], parseErrors };
+  const inheritedIncludes = [];
+  const include = doc.include;
+  const includeEntries = Array.isArray(include) ? include : include ? [include] : [];
+  for (const entry of includeEntries) {
+    if (typeof entry === "string") inheritedIncludes.push(entry);
+    else if (entry && typeof entry === "object") {
+      const e = entry;
+      if (typeof e.local === "string") inheritedIncludes.push(`local: ${e.local}`);
+      else if (typeof e.project === "string") inheritedIncludes.push(`project: ${e.project}`);
+      else if (typeof e.template === "string") inheritedIncludes.push(`template: ${e.template}`);
+      else if (typeof e.remote === "string") inheritedIncludes.push(`remote: ${e.remote}`);
+    }
+  }
+  const jobs = [];
+  const resolveScript = (job, seen = /* @__PURE__ */ new Set()) => {
+    const lines = [...asLines(job.before_script), ...asLines(job.script)];
+    const bases = asLines(job.extends).length ? asLines(job.extends) : typeof job.extends === "string" ? [job.extends] : [];
+    for (const base of bases) {
+      if (seen.has(base)) continue;
+      seen.add(base);
+      const tpl = doc[base];
+      if (tpl && typeof tpl === "object") lines.push(...resolveScript(tpl, seen));
+    }
+    return lines;
+  };
+  for (const [key, value] of Object.entries(doc)) {
+    if (GITLAB_RESERVED.has(key) || key.startsWith(".")) continue;
+    if (!value || typeof value !== "object" || Array.isArray(value)) continue;
+    const job = value;
+    if (!looksLikeJob(job)) continue;
+    const lines = resolveScript(job);
+    const tools = new Set(inferToolsFromShape(key, job));
+    for (const line of lines) for (const t of matchTools(line, scripts)) tools.add(t);
+    if (!lines.length && !tools.size) continue;
+    jobs.push({
+      job: key,
+      file,
+      tools: [...tools],
+      advisory: job.allow_failure === true || typeof job.allow_failure === "object" && job.allow_failure !== null,
+      branchScoped: Boolean(job.rules ?? job.only ?? job.except),
+      scriptVisible: lines.length > 0
+    });
+  }
+  return { jobs, inheritedIncludes, parseErrors };
+}
+function parseGithubWorkflow(text, file, scripts) {
+  const parseErrors = [];
+  let doc;
+  try {
+    doc = YAML.parse(text, { logLevel: "silent" });
+  } catch (err) {
+    parseErrors.push(
+      `${file}: ${err instanceof Error ? err.message.split("\n")[0] : "unparseable YAML"}`
+    );
+    return { jobs: [], parseErrors };
+  }
+  const jobs = [];
+  const jobsObj = doc?.jobs ?? {};
+  for (const [key, value] of Object.entries(jobsObj)) {
+    if (!value || typeof value !== "object") continue;
+    const job = value;
+    const steps = Array.isArray(job.steps) ? job.steps : [];
+    const tools = /* @__PURE__ */ new Set();
+    for (const step of steps) {
+      const run = step?.run;
+      if (typeof run === "string") for (const t of matchTools(run, scripts)) tools.add(t);
+    }
+    if (!tools.size) continue;
+    jobs.push({
+      job: key,
+      file,
+      tools: [...tools],
+      advisory: job["continue-on-error"] === true,
+      branchScoped: false,
+      scriptVisible: true
+    });
+  }
+  return { jobs, parseErrors };
+}
+async function localHookTools(root, facts, scripts) {
+  const hooks = facts.hooks;
+  const empty = [];
+  const readHook = async (name) => {
+    if (!hooks.dir) return empty;
+    const text = await readText(path.join(root, hooks.dir, name));
+    return text ? matchTools(text, scripts) : empty;
+  };
+  let preCommit = [];
+  let prePush = [];
+  let commitMsg = [];
+  if (hooks.dir) {
+    [preCommit, prePush, commitMsg] = await Promise.all([
+      readHook("pre-commit"),
+      readHook("pre-push"),
+      readHook("commit-msg")
+    ]);
+  } else if (hooks.source === "husky-legacy") {
+    const pkg = await readJson(
+      path.join(root, "package.json")
+    );
+    const legacy = pkg?.husky?.hooks ?? {};
+    const configText = await readText(path.join(root, "husky.config.js"));
+    const forHook = (name) => {
+      const cmd = legacy[name] ?? (configText?.includes(name) ? configText : void 0);
+      return cmd ? matchTools(cmd, scripts) : [];
+    };
+    preCommit = forHook("pre-commit");
+    prePush = forHook("pre-push");
+    commitMsg = forHook("commit-msg");
+  }
+  let lintStaged = [];
+  if (hooks.lintStaged) {
+    const pkg = await readJson(path.join(root, "package.json"));
+    const config = pkg?.["lint-staged"];
+    const commands = [];
+    const collect = (v) => {
+      if (typeof v === "string") commands.push(v);
+      else if (Array.isArray(v)) v.forEach(collect);
+      else if (v && typeof v === "object") Object.values(v).forEach(collect);
+    };
+    collect(config);
+    const tools = /* @__PURE__ */ new Set();
+    for (const cmd of commands) for (const t of matchTools(cmd, scripts)) tools.add(t);
+    lintStaged = [...tools];
+    if ((hooks.preCommit || hooks.source === "husky" || hooks.source === "husky-legacy") && lintStaged.length) {
+      preCommit = [.../* @__PURE__ */ new Set([...preCommit, ...lintStaged])];
+    }
+  }
+  const wired = hooks.source === "custom" || hooks.source === "husky" || hooks.source === "husky-legacy" ? true : hooks.source === "githooks" ? facts.git.hooksPath === hooks.dir : false;
+  return { source: hooks.source, wired, preCommit, prePush, commitMsg, lintStaged };
+}
+async function detectThresholds(root, scripts, ciJobs) {
+  const sonarConfigured = await pathExists(path.join(root, "sonar-project.properties")) || ciJobs.some((j) => j.tools.includes("sonar"));
+  let coverageThresholdLocal = false;
+  for (const f of [
+    "jest.config.js",
+    "jest.config.ts",
+    "jest.config.cjs",
+    "jest.config.mjs",
+    "jest.config.json",
+    "vitest.config.ts",
+    "vitest.config.js",
+    "vitest.config.mts"
+  ]) {
+    const text = await readText(path.join(root, f));
+    if (text && /coverageThreshold|thresholds\s*:/.test(text)) {
+      coverageThresholdLocal = true;
+      break;
+    }
+  }
+  if (!coverageThresholdLocal) {
+    const pkg = await readJson(
+      path.join(root, "package.json")
+    );
+    coverageThresholdLocal = Boolean(pkg?.jest?.coverageThreshold);
+  }
+  const coverageCollected = Object.values(scripts).some((v) => /--coverage|\bnyc\b|\bc8\b/.test(v)) || ciJobs.some((j) => j.tools.includes("coverage") || j.tools.includes("sonar"));
+  return { sonarConfigured, coverageThresholdLocal, coverageCollected };
+}
+async function buildGateInventory(root, facts) {
+  const scripts = facts.commands.raw;
+  const jobs = [];
+  const inheritedIncludes = [];
+  const parseErrors = [];
+  if (facts.ci.system === "gitlab") {
+    const text = await readText(path.join(root, ".gitlab-ci.yml"));
+    if (text) {
+      const parsed = parseGitlabCi(text, ".gitlab-ci.yml", scripts);
+      jobs.push(...parsed.jobs);
+      parseErrors.push(...parsed.parseErrors);
+      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));
+          if (subText) {
+            const sub = parseGitlabCi(subText, rel, scripts);
+            jobs.push(...sub.jobs);
+            parseErrors.push(...sub.parseErrors);
+            inheritedIncludes.push(...sub.inheritedIncludes);
+          } else {
+            inheritedIncludes.push(inc);
+          }
+        } else {
+          inheritedIncludes.push(inc);
+        }
+      }
+    }
+  } else if (facts.ci.system === "github") {
+    for (const file of facts.ci.files) {
+      const text = await readText(path.join(root, file));
+      if (!text) continue;
+      const parsed = parseGithubWorkflow(text, file, scripts);
+      jobs.push(...parsed.jobs);
+      parseErrors.push(...parsed.parseErrors);
+    }
+  }
+  const [local, thresholds] = await Promise.all([
+    localHookTools(root, facts, scripts),
+    detectThresholds(root, scripts, jobs)
+  ]);
+  const pkg = await readJson(path.join(root, "package.json"));
+  const deps = { ...pkg?.dependencies, ...pkg?.devDependencies };
+  const commitlintDep = Boolean(deps["@commitlint/cli"] ?? deps["commitlint"]);
+  return {
+    local,
+    ci: { system: facts.ci.system, jobs, inheritedIncludes, parseErrors },
+    thresholds,
+    commitlintDep
+  };
+}
+
+// src/lenses/gate-integrity/lens.ts
+var LENS_ID2 = "gate-integrity";
+var CORRECTNESS_TOOLS = ["typecheck", "lint", "format-check", "test"];
+var TOOL_LABEL = {
+  typecheck: "type checking",
+  lint: "linting",
+  "format-check": "format checking",
+  "format-write": "format writing",
+  test: "unit tests",
+  coverage: "coverage",
+  e2e: "e2e tests",
+  sonar: "SonarQube analysis",
+  codecov: "Codecov upload",
+  commitlint: "commit-message linting",
+  size: "bundle-size check",
+  chromatic: "visual review"
+};
+function finding(partial) {
+  return { lens: LENS_ID2, ...partial };
+}
+function deriveGateFindings(inv, disclosures = []) {
+  const findings = [];
+  const localTools = /* @__PURE__ */ new Set([
+    ...inv.local.preCommit,
+    ...inv.local.prePush,
+    ...inv.local.commitMsg
+  ]);
+  const enforcedCiJobs = inv.ci.jobs.filter((j) => !j.advisory);
+  const enforcedCiTools = new Set(enforcedCiJobs.flatMap((j) => j.tools));
+  const anyCiTools = new Set(inv.ci.jobs.flatMap((j) => j.tools));
+  if (inv.local.source === "githooks" && !inv.local.wired) {
+    if (isCiEnvironment()) {
+      disclosures.push(
+        "Running in CI: git hook wiring (core.hooksPath) is a developer-machine fact and cannot be judged from an ephemeral checkout \u2014 not flagged here. Run `etymd audit` locally to check it."
+      );
+    } else {
+      findings.push(
+        finding({
+          id: `${LENS_ID2}/hooks-not-wired`,
+          tier: "risk",
+          claim: "Tracked .githooks/ exist but git core.hooksPath is unset \u2014 the hooks never run",
+          evidence: [".githooks/"],
+          why: "Every check in those hooks is silently skipped on this clone.",
+          action: "Run `git config core.hooksPath .githooks` (etymd gates does this).",
+          effort: "S",
+          confidence: "high"
+        })
+      );
+    }
+  }
+  for (const tool of CORRECTNESS_TOOLS) {
+    if (!enforcedCiTools.has(tool) || localTools.has(tool)) continue;
+    const jobs = enforcedCiJobs.filter((j) => j.tools.includes(tool));
+    const branchNote = jobs.every((j) => j.branchScoped) ? " (rule-scoped \u2014 blocking-ness may vary per branch)" : "";
+    findings.push(
+      finding({
+        id: `${LENS_ID2}/ci-only-${tool}`,
+        tier: "gap",
+        claim: `${TOOL_LABEL[tool]} is enforced only in CI \u2014 no local hook runs it`,
+        evidence: jobs.map((j) => `${j.file} job \`${j.job}\`${branchNote}`),
+        why: "A failure is invisible until the pipeline runs \u2014 the slowest possible feedback loop.",
+        action: "Wire it into a pre-push hook \u2014 `etymd gates` generates one from your own scripts.",
+        effort: "S",
+        confidence: "high"
+      })
+    );
+  }
+  if (inv.ci.system !== "none" && inv.ci.jobs.length) {
+    for (const tool of CORRECTNESS_TOOLS) {
+      if (!localTools.has(tool) || anyCiTools.has(tool)) continue;
+      if (inv.ci.inheritedIncludes.length) continue;
+      findings.push(
+        finding({
+          id: `${LENS_ID2}/local-only-${tool}`,
+          tier: "gap",
+          claim: `${TOOL_LABEL[tool]} runs only in local hooks \u2014 CI never re-checks it`,
+          evidence: [`local hooks (${inv.local.source})`],
+          why: "Hooks are skippable (`--no-verify`, fresh clones without hook setup) \u2014 CI is the backstop.",
+          action: "Add the same check to the CI pipeline.",
+          effort: "M",
+          confidence: "medium"
+        })
+      );
+    }
+  }
+  if (inv.thresholds.coverageCollected && !inv.thresholds.coverageThresholdLocal) {
+    const sonarJobs = inv.ci.jobs.filter((j) => j.tools.includes("sonar"));
+    const advisoryNote = sonarJobs.length && sonarJobs.every((j) => j.advisory) ? " (the job is allow_failure \u2014 advisory on this pipeline)" : "";
+    findings.push(
+      finding({
+        id: `${LENS_ID2}/coverage-no-local-threshold`,
+        tier: inv.thresholds.sonarConfigured ? "gap" : "polish",
+        claim: inv.thresholds.sonarConfigured ? `A coverage gate exists only server-side (SonarQube)${advisoryNote} \u2014 its threshold is not visible in this repo and nothing local mirrors it` : "Coverage is collected but no threshold gates it anywhere",
+        evidence: [
+          ...sonarJobs.map((j) => `${j.file} job \`${j.job}\``),
+          "no coverageThreshold in jest/vitest config"
+        ],
+        why: "A coverage regression is invisible until the server-side gate fails the pipeline \u2014 after push, sometimes after review.",
+        action: "Add a local coverageThreshold mirroring the server gate (or document the server value beside the config) so a regression warns before push.",
+        effort: "M",
+        confidence: inv.thresholds.sonarConfigured ? "high" : "medium"
+      })
+    );
+  }
+  if (inv.commitlintDep && !inv.local.commitMsg.includes("commitlint") && !localToolInHook(inv, "commitlint")) {
+    findings.push(
+      finding({
+        id: `${LENS_ID2}/commitlint-unwired`,
+        tier: "polish",
+        claim: "commitlint is a dependency but no commit-msg hook runs it",
+        evidence: ["package.json (@commitlint/cli)", "no commit-msg hook"],
+        why: "The commit convention the tooling promises is not actually enforced.",
+        action: "Wire commitlint into a commit-msg hook, or remove the dependency.",
+        effort: "S",
+        confidence: "high"
+      })
+    );
+  }
+  return findings;
+}
+function localToolInHook(inv, tool) {
+  return inv.local.preCommit.includes(tool) || inv.local.prePush.includes(tool) || inv.local.commitMsg.includes(tool);
+}
+var gateIntegrityLens = {
+  id: LENS_ID2,
+  version: "1",
+  title: "Gate integrity (CI \u2194 local)",
+  kind: "improvement",
+  async run(ctx) {
+    const inv = await buildGateInventory(ctx.root, ctx.facts);
+    const disclosures = [];
+    if (inv.ci.inheritedIncludes.length) {
+      disclosures.push(
+        `${inv.ci.inheritedIncludes.length} CI include(s) reference pipeline definitions outside this repo \u2014 the CI inventory is incomplete: ${inv.ci.inheritedIncludes.slice(0, 3).join("; ")}${inv.ci.inheritedIncludes.length > 3 ? " \u2026" : ""}`
+      );
+    }
+    const advisory = inv.ci.jobs.filter((j) => j.advisory);
+    if (advisory.length) {
+      disclosures.push(
+        `${advisory.length} CI job(s) are allow_failure/continue-on-error \u2014 advisory, not counted as enforced gates: ${advisory.map((j) => j.job).join(", ")}`
+      );
+    }
+    const inheritedScripts = inv.ci.jobs.filter((j) => !j.scriptVisible);
+    if (inheritedScripts.length) {
+      disclosures.push(
+        `${inheritedScripts.length} CI job(s) define their script in an inherited template \u2014 tools inferred from name/variables only: ${inheritedScripts.map((j) => j.job).join(", ")}`
+      );
+    }
+    if (inv.ci.parseErrors.length)
+      disclosures.push(...inv.ci.parseErrors.map((e) => `CI parse: ${e}`));
+    if (inv.ci.system === "none")
+      disclosures.push("No CI configuration found \u2014 CI\u2194local comparisons skipped.");
+    const findings = deriveGateFindings(inv, disclosures);
+    return {
+      lens: LENS_ID2,
+      version: "1",
+      title: "Gate integrity (CI \u2194 local)",
+      kind: "improvement",
+      status: "ran",
+      disclosures,
+      findings
+    };
+  }
+};
+async function listInstructionFiles(root, facts, scope) {
+  const files = [];
+  const add = async (rel) => {
+    const text = await readText(path.join(root, rel));
+    if (text !== null) files.push({ path: normalizeRelPath(rel), text });
+  };
+  const singleFileArtifacts = [
+    "agents",
+    "claude",
+    "gemini",
+    "copilot",
+    "cursorrules",
+    "cline",
+    "windsurf"
+  ];
+  for (const id of singleFileArtifacts) {
+    const artifact = facts.artifacts.find((a) => a.id === id);
+    if (artifact?.exists) await add(artifact.path);
+  }
+  const rulesDir = path.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));
+      }
+    } catch {
+    }
+  }
+  const skillsDir = path.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");
+        await add(skill);
+      }
+    } catch {
+    }
+  }
+  const detected = new Set(files.map((f) => f.path));
+  const included = [];
+  for (const rel of await expandFileGlobs(root, scope?.include ?? [])) {
+    if (detected.has(rel)) continue;
+    const before = files.length;
+    await add(rel);
+    if (files.length > before) included.push(rel);
+  }
+  const exclude = scope?.exclude ?? [];
+  if (!exclude.length) return { files, excluded: [], included };
+  const kept = [];
+  const excluded = [];
+  for (const file of files) {
+    if (matchesAnyGlob(file.path, exclude)) excluded.push(file.path);
+    else kept.push(file);
+  }
+  return { files: kept, excluded, included };
+}
+function extractCodeTokens(text) {
+  const tokens = [];
+  for (const m of text.matchAll(/`([^`\n]+)`/g)) tokens.push(m[1].trim());
+  for (const block of text.matchAll(/```[a-z]*\n([\s\S]*?)```/g)) {
+    for (const line of block[1].split("\n")) {
+      const trimmed = line.trim();
+      if (trimmed && !trimmed.startsWith("#")) tokens.push(trimmed);
+    }
+  }
+  return tokens;
+}
+var PM_BUILTINS = /* @__PURE__ */ new Set([
+  "install",
+  "i",
+  "add",
+  "remove",
+  "rm",
+  "up",
+  "update",
+  "upgrade",
+  "dlx",
+  "exec",
+  "create",
+  "init",
+  "link",
+  "unlink",
+  "publish",
+  "pack",
+  "audit",
+  "outdated",
+  "why",
+  "list",
+  "ls",
+  "view",
+  "info",
+  "config",
+  "store",
+  "import",
+  "rebuild",
+  "prune",
+  "setup",
+  "env",
+  "bin",
+  "root",
+  "licenses",
+  "patch",
+  "approve-builds",
+  "workspaces",
+  "workspace",
+  "cache",
+  "version",
+  "help"
+]);
+function extractCommandClaims(text) {
+  const scripts = /* @__PURE__ */ new Map();
+  let filteredSkipped = 0;
+  for (const token of extractCodeTokens(text)) {
+    for (const m of token.matchAll(
+      /(?:^|&&\s*|\|\|\s*|;\s*|\|\s*|\$\s+|\(\s*)(pnpm|yarn|npm|bun)\s+(?:(run)\s+)?(-{0,2}[A-Za-z0-9:._@/[\]-]+)/g
+    )) {
+      const pm = m[1];
+      const ranExplicit = Boolean(m[2]);
+      const arg = m[3];
+      if (arg.startsWith("-")) {
+        filteredSkipped += 1;
+        continue;
+      }
+      if (pm === "npm" && !ranExplicit && arg !== "test" && arg !== "start") continue;
+      if ((pm === "bun" || pm === "yarn" || pm === "pnpm") && !ranExplicit && PM_BUILTINS.has(arg))
+        continue;
+      if (ranExplicit && PM_BUILTINS.has(arg)) continue;
+      scripts.set(arg, token);
+    }
+  }
+  return { scripts, filteredSkipped };
+}
+var PATH_TOKEN_RE = /^[A-Za-z0-9_.-]+(\/[A-Za-z0-9_.$-]+)+\/?$/;
+var KNOWN_EXTENSIONS = /* @__PURE__ */ new Set([
+  ..."ts tsx cts mts js jsx cjs mjs json jsonc json5 md mdx mdc yml yaml toml ini cfg conf env sh bash zsh fish ps1 bat cmd css scss sass less html htm xml svg sql prisma graphql gql proto py rb rs go java kt kts swift c h cc cpp hpp cs php vue svelte astro txt log lock csv tsv png jpg jpeg gif webp ico avif woff woff2 ttf otf wasm map pem key crt tf tfvars example sample local snap ejs hbs pug".split(" ")
+]);
+var CREATION_CONTEXT_RE = /\b(?:creat(?:e|es|ed|ing)|generat(?:e|es|ed|ing)|scaffold(?:s|ed|ing)?|quarantin(?:e|es|ed|ing)|(?:writ(?:e|es|ten|ing)|output(?:s|ted)?|emit(?:s|ted|ting)?|sav(?:e|es|ed|ing)|mov(?:e|es|ed|ing)|copy|copi(?:es|ed))\s+(?:it\s+|them\s+)?(?:to|into)|new\s+(?:file|directory|folder)|will\s+(?:be\s+)?(?:created|generated|written)|add(?:s|ed|ing)?\s+(?:a|the)\s+new)\b/i;
+var PLACEHOLDER_SEGMENTS = /* @__PURE__ */ new Set(["placeholder", "foo", "bar", "baz", "qux"]);
+var PLACEHOLDER_PREFIX_RE = /^(?:my|your)-/i;
+function isPlaceholderClaim(token) {
+  return token.split("/").some((seg) => PLACEHOLDER_PREFIX_RE.test(seg) || PLACEHOLDER_SEGMENTS.has(seg.toLowerCase()));
+}
+function claimContext(text, index) {
+  const start = text.lastIndexOf("\n", index) + 1;
+  const endRaw = text.indexOf("\n", index);
+  const end = endRaw === -1 ? text.length : endRaw;
+  const line = text.slice(start, end);
+  if (!/^\s*(?:[-*+]|\d+[.)]|\|)/.test(line)) return line;
+  let cursor = start;
+  while (cursor > 0) {
+    const prevEnd = cursor - 1;
+    const prevStart = text.lastIndexOf("\n", prevEnd - 1) + 1;
+    const prev = text.slice(prevStart, prevEnd);
+    cursor = prevStart;
+    if (!prev.trim()) continue;
+    if (/^\s*(?:[-*+]|\d+[.)]|\|)/.test(prev)) continue;
+    return `${prev}
+${line}`;
+  }
+  return line;
+}
+function extractPathClaims(text) {
+  const prospectiveOnly = /* @__PURE__ */ new Map();
+  const placeholder = /* @__PURE__ */ new Set();
+  for (const m of text.matchAll(/`([^`\n]+)`/g)) {
+    const token = m[1].trim();
+    if (token.includes(" ") || token.length > 120) continue;
+    if (token.startsWith("/") || token.startsWith("~") || token.startsWith("@") || token.startsWith("$"))
+      continue;
+    if (token.includes("://") || token.startsWith("www.")) continue;
+    if (/[*?{}<>|]/.test(token)) continue;
+    if (token.includes("@")) continue;
+    if (!PATH_TOKEN_RE.test(token)) continue;
+    if (token.split("/").some((seg) => seg.startsWith("$"))) continue;
+    const isDirClaim = token.endsWith("/");
+    const ext = token.toLowerCase().match(/\.([a-z0-9]{1,8})$/)?.[1];
+    if (!isDirClaim && !(ext && KNOWN_EXTENSIONS.has(ext))) continue;
+    const claim = token.replace(/\/$/, "");
+    if (isPlaceholderClaim(claim)) {
+      placeholder.add(claim);
+      continue;
+    }
+    const prospective2 = CREATION_CONTEXT_RE.test(claimContext(text, m.index ?? 0));
+    prospectiveOnly.set(claim, (prospectiveOnly.get(claim) ?? true) && prospective2);
+  }
+  const paths = [];
+  const prospective = [];
+  for (const [claim, only] of prospectiveOnly) {
+    if (only) prospective.push(claim);
+    else paths.push(claim);
+  }
+  return { paths, prospective, placeholder: [...placeholder] };
+}
+function packageManagerUsage(text) {
+  const counts = /* @__PURE__ */ new Map();
+  for (const token of extractCodeTokens(text)) {
+    for (const m of token.matchAll(/\b(pnpm|yarn|npm|bun)\s+(?:run\s+)?[A-Za-z-]/g)) {
+      const pm = m[1];
+      counts.set(pm, (counts.get(pm) ?? 0) + 1);
+    }
+  }
+  return counts;
+}
+var KNOWN_DOC_REFS = ["AGENTS.md", "CLAUDE.md", "PROJECT_CONTEXT.md", "GEMINI.md"];
+function extractDocRefs(text) {
+  return KNOWN_DOC_REFS.filter((name) => text.includes(name));
+}
+
+// src/lenses/instruction-truth/lens.ts
+var LENS_ID3 = "instruction-truth";
+var MAX_PATH_FINDINGS_PER_FILE = 15;
+function finding2(partial) {
+  return { lens: LENS_ID3, ...partial };
+}
+function compareCommands(baseline, fresh) {
+  const out = [];
+  for (const role of ["test", "lint", "typecheck", "format", "formatCheck", "build"]) {
+    const before = baseline.commands[role];
+    if (before && !(before in fresh.commands.raw)) {
+      out.push(
+        finding2({
+          id: `${LENS_ID3}/command-gone-${role}`,
+          tier: "risk",
+          claim: `Documented ${role} command \`${before}\` no longer exists in package.json`,
+          evidence: ["package.json"],
+          why: "Every doc, hook, and agent instruction naming it now fails or silently skips a check.",
+          action: "Re-point the contract/hooks at the renamed script, then refresh the baseline.",
+          effort: "S",
+          confidence: "high"
+        })
+      );
+    }
+  }
+  return out;
+}
+function compareArtifacts(baseline, fresh) {
+  const out = [];
+  const freshById = new Map(fresh.artifacts.map((a) => [a.id, a]));
+  for (const a of baseline.artifacts) {
+    const now = freshById.get(a.id);
+    if (a.exists && now && !now.exists) {
+      out.push(
+        finding2({
+          id: `${LENS_ID3}/artifact-gone-${a.id}`,
+          tier: "gap",
+          claim: `${a.label} was present at baseline but is now missing`,
+          evidence: [a.path],
+          why: "Agents and docs still assume it exists; instructions referring to it now mislead.",
+          action: "Restore it or update the contract and refresh the baseline.",
+          effort: "S",
+          confidence: "high"
+        })
+      );
+    }
+  }
+  return out;
+}
+function compareLayout(baseline, fresh) {
+  const now = new Set(fresh.tree.dirs.map((d) => d.name));
+  return baseline.tree.dirs.filter((d) => !now.has(d.name)).map(
+    (d) => finding2({
+      id: `${LENS_ID3}/dir-gone-${d.name}`,
+      tier: "gap",
+      claim: `Top-level \`${d.name}/\` from the baseline no longer exists \u2014 the repo map may be stale`,
+      evidence: [`${d.name}/`],
+      why: "A stale map sends agents (and people) to paths that are gone.",
+      action: "Update the repo map and refresh the baseline.",
+      effort: "S",
+      confidence: "medium"
+    })
+  );
+}
+var instructionTruthLens = {
+  id: LENS_ID3,
+  version: "1",
+  title: "Instruction truth",
+  kind: "truth",
+  async run(ctx) {
+    const findings = [];
+    const disclosures = [];
+    const { facts, root } = ctx;
+    const config = ctx.config?.config ?? DEFAULT_CONFIG;
+    disclosures.push(...ctx.config?.problems ?? []);
+    const {
+      files,
+      excluded,
+      included: includedExtra
+    } = await listInstructionFiles(root, facts, config.instructions);
+    if (!files.length) {
+      findings.push(
+        finding2({
+          id: `${LENS_ID3}/no-contract`,
+          tier: "gap",
+          claim: "No agent instruction files exist (AGENTS.md or equivalents)",
+          evidence: ["AGENTS.md (missing)"],
+          why: "Every agent in this repo works from generic priors instead of the project's rules.",
+          action: "Run `etymd init` to scaffold one.",
+          effort: "M",
+          confidence: "high"
+        })
+      );
+    }
+    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")
+      );
+      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))];
+      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;
+      }
+      return false;
+    };
+    const binResolves = async (name) => {
+      const bases = [root, ...facts.packages.map((p) => path.join(root, p.dir))];
+      for (const base of bases) {
+        if (await pathExists(path.join(base, "node_modules", ".bin", name))) return true;
+      }
+      return false;
+    };
+    const nodeModulesInstalled = await pathExists(path.join(root, "node_modules"));
+    let totalFilteredSkipped = 0;
+    let binaryResolved = 0;
+    let unverifiableCommands = 0;
+    let gitignoredSkipped = 0;
+    let prospectiveSkipped = 0;
+    let placeholderSkipped = 0;
+    for (const file of files) {
+      const { scripts: claimed, filteredSkipped } = extractCommandClaims(file.text);
+      totalFilteredSkipped += filteredSkipped;
+      for (const [script, raw] of claimed) {
+        if (knownScripts.has(script)) continue;
+        if (await binResolves(script)) {
+          binaryResolved += 1;
+          continue;
+        }
+        if (!nodeModulesInstalled) {
+          unverifiableCommands += 1;
+          continue;
+        }
+        findings.push(
+          finding2({
+            id: `${LENS_ID3}/stale-command:${file.path}:${script}`,
+            tier: "risk",
+            claim: `${file.path} tells agents to run \`${script}\` \u2014 no such script exists`,
+            evidence: [`${file.path}: \`${raw}\``, "package.json scripts (root + workspaces)"],
+            why: "An agent following this instruction runs a command that fails \u2014 or silently skips the check it was meant to run.",
+            action: "Update the instruction to the current script name (or restore the script).",
+            effort: "S",
+            confidence: "high"
+          })
+        );
+      }
+      const { paths, prospective, placeholder } = extractPathClaims(file.text);
+      prospectiveSkipped += prospective.length;
+      placeholderSkipped += placeholder.length;
+      const missing = [];
+      for (const claim of paths) {
+        if (!await pathResolves(claim)) missing.push(claim);
+      }
+      const ignoredOut = missing.length ? await git(root, ["check-ignore", ...missing]) : null;
+      const gitignored = new Set((ignoredOut ?? "").split("\n").filter(Boolean));
+      let pathFindings = 0;
+      for (const claim of missing) {
+        if (gitignored.has(claim)) {
+          gitignoredSkipped += 1;
+          continue;
+        }
+        if (pathFindings >= MAX_PATH_FINDINGS_PER_FILE) {
+          disclosures.push(
+            `${file.path}: more than ${MAX_PATH_FINDINGS_PER_FILE} missing-path claims \u2014 truncated.`
+          );
+          break;
+        }
+        pathFindings += 1;
+        findings.push(
+          finding2({
+            id: `${LENS_ID3}/stale-path:${file.path}:${claim}`,
+            tier: "gap",
+            claim: `${file.path} references \`${claim}\` \u2014 it does not exist in the repo`,
+            evidence: [file.path, `missing: ${claim}`],
+            why: "Agents navigate by these references; a dead path wastes a lookup and erodes trust in the rest of the file.",
+            action: "Fix or remove the reference.",
+            effort: "S",
+            confidence: "medium"
+          })
+        );
+      }
+      if (facts.packageManager !== "unknown") {
+        const usage = packageManagerUsage(file.text);
+        const own = usage.get(facts.packageManager) ?? 0;
+        for (const [pm, count] of usage) {
+          if (pm === facts.packageManager || count < 2 || count <= own) continue;
+          findings.push(
+            finding2({
+              id: `${LENS_ID3}/pm-conflict:${file.path}`,
+              tier: "gap",
+              claim: `${file.path} instructs \`${pm}\` (${count}\xD7) but the repo uses ${facts.packageManager}`,
+              evidence: [file.path, `lockfile \u2192 ${facts.packageManager}`],
+              why: "Mixed package-manager instructions produce divergent lockfiles and broken installs.",
+              action: `Rewrite the commands for ${facts.packageManager}.`,
+              effort: "S",
+              confidence: "medium"
+            })
+          );
+          break;
+        }
+      }
+      for (const ref of extractDocRefs(file.text)) {
+        if (await pathExists(path.join(root, ref))) continue;
+        findings.push(
+          finding2({
+            id: `${LENS_ID3}/dangling-ref:${file.path}:${ref}`,
+            tier: "gap",
+            claim: `${file.path} references ${ref} \u2014 no such file exists`,
+            evidence: [file.path, `missing: ${ref}`],
+            why: "The pointer chain agents follow breaks at a file they can never read.",
+            action: `Create ${ref} or remove the reference.`,
+            effort: "S",
+            confidence: "high"
+          })
+        );
+      }
+    }
+    if (ctx.baseline) {
+      findings.push(
+        ...compareCommands(ctx.baseline.facts, facts),
+        ...compareArtifacts(ctx.baseline.facts, facts),
+        ...compareLayout(ctx.baseline.facts, facts)
+      );
+      if (baselineCarriesMachinePath(ctx.baseline)) {
+        disclosures.push(
+          `${BASELINE_FILE} records an absolute machine path as its scan root (written by an older etymd). It is committed, so that path is published with your repo \u2014 run \`etymd approve\` to rewrite it.`
+        );
+      }
+      if (ctx.baseline.packVersion !== PACK_VERSION) {
+        disclosures.push(
+          `Baseline was approved under pack v${ctx.baseline.packVersion}; current pack is v${PACK_VERSION}.`
+        );
+      }
+    } else {
+      disclosures.push(
+        "No committed baseline (.etymd/baseline.json) \u2014 drift over time is not measurable; run `etymd init` to approve one."
+      );
+    }
+    if (binaryResolved) {
+      disclosures.push(
+        `${binaryResolved} command claim(s) are installed binaries (node_modules/.bin), not package scripts \u2014 treated as true.`
+      );
+    }
+    if (unverifiableCommands) {
+      disclosures.push(
+        `node_modules is not installed \u2014 ${unverifiableCommands} command claim(s) matching no package script could not be checked against installed binaries; skipped, not flagged.`
+      );
+    }
+    if (gitignoredSkipped) {
+      disclosures.push(
+        `${gitignoredSkipped} missing path claim(s) are gitignored (machine-local, e.g. .env) \u2014 existence is not verifiable from the repo; skipped, not flagged.`
+      );
+    }
+    if (prospectiveSkipped) {
+      disclosures.push(
+        `${prospectiveSkipped} path claim(s) sit in create-this prose (the file instructs generating them) \u2014 forward-looking, not stale; skipped, not flagged.`
+      );
+    }
+    if (placeholderSkipped) {
+      disclosures.push(
+        `${placeholderSkipped} path claim(s) are naming stand-ins (e.g. \`my-custom-skill\`) rather than real references; skipped, not flagged.`
+      );
+    }
+    if (excluded.length) {
+      const shown = excluded.slice(0, 5).join(", ");
+      disclosures.push(
+        `${excluded.length} instruction file(s) excluded by ${CONFIG_FILE} and NOT audited: ${shown}${excluded.length > 5 ? `, +${excluded.length - 5} more` : ""}.`
+      );
+    }
+    if (includedExtra.length) {
+      disclosures.push(
+        `${includedExtra.length} extra instruction file(s) audited via ${CONFIG_FILE} \`instructions.include\`: ${includedExtra.slice(0, 5).join(", ")}${includedExtra.length > 5 ? `, +${includedExtra.length - 5} more` : ""}.`
+      );
+    }
+    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.`
+    );
+    return {
+      lens: LENS_ID3,
+      version: "1",
+      title: "Instruction truth",
+      kind: "truth",
+      status: "ran",
+      disclosures,
+      findings,
+      outOfScope: excluded
+    };
+  }
+};
+
+// src/engine/finding.ts
+var TIER_ORDER = { risk: 0, gap: 1, polish: 2 };
+var EFFORT_ORDER = { S: 0, M: 1, L: 2 };
+function rankFindings(findings) {
+  return [...findings].sort(
+    (a, b) => TIER_ORDER[a.tier] - TIER_ORDER[b.tier] || EFFORT_ORDER[a.effort] - EFFORT_ORDER[b.effort]
+  );
+}
+function ledgerPath(root) {
+  return path.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.writeFile(target, JSON.stringify(ledger, null, 2) + "\n", "utf8");
+}
+function belongsToAny(id, paths) {
+  return paths.some((p) => id.includes(`:${p}`));
+}
+function reconcileLedger(ledger, findings, now = (/* @__PURE__ */ new Date()).toISOString(), outOfScope = []) {
+  const byId = new Map(ledger.entries.map((e) => [e.id, e]));
+  const seen = /* @__PURE__ */ new Set();
+  const diff = {
+    new: [],
+    stillOpen: [],
+    regressed: [],
+    resolved: [],
+    dismissed: [],
+    accepted: [],
+    outOfScope: []
+  };
+  const entries = [];
+  for (const f of findings) {
+    seen.add(f.id);
+    const prev = byId.get(f.id);
+    if (!prev) {
+      diff.new.push(f);
+      entries.push({
+        id: f.id,
+        status: "open",
+        tier: f.tier,
+        claim: f.claim,
+        firstSeen: now,
+        lastSeen: now
+      });
+      continue;
+    }
+    if (prev.status === "dismissed") {
+      diff.dismissed.push(f);
+      entries.push({ ...prev, lastSeen: now });
+      continue;
+    }
+    if (prev.status === "accepted") {
+      diff.accepted.push(f);
+      entries.push({ ...prev, tier: f.tier, claim: f.claim, lastSeen: now });
+      continue;
+    }
+    if (prev.status === "done") {
+      diff.regressed.push(f);
+      entries.push({ ...prev, status: "regressed", tier: f.tier, claim: f.claim, lastSeen: now });
+      continue;
+    }
+    diff.stillOpen.push(f);
+    entries.push({ ...prev, tier: f.tier, claim: f.claim, lastSeen: now });
+  }
+  for (const prev of ledger.entries) {
+    if (seen.has(prev.id)) continue;
+    if (outOfScope.length && belongsToAny(prev.id, outOfScope)) {
+      diff.outOfScope.push(prev);
+      entries.push(prev);
+      continue;
+    }
+    if (prev.status === "open" || prev.status === "accepted" || prev.status === "regressed") {
+      diff.resolved.push(prev);
+      entries.push({ ...prev, status: "done", lastSeen: now });
+    } else {
+      entries.push(prev);
+    }
+  }
+  return { ledger: { version: 1, entries }, diff };
+}
+function visibleFindings(findings, ledger) {
+  const quieted = new Set(
+    ledger.entries.filter((e) => e.status === "dismissed" || e.status === "accepted").map((e) => e.id)
+  );
+  return findings.filter((f) => !quieted.has(f.id));
+}
+
+// src/engine/run.ts
+var LENSES = [instructionTruthLens, gateIntegrityLens, contextEconomyLens];
+async function runAudit(root, opts = {}) {
+  const facts = await scanProject(root);
+  if ((opts.persistLedger ?? true) || await pathExists(path.join(root, ETYMD_DIR))) {
+    await writeCachedFacts(root, facts);
+  }
+  const baseline = await readBaseline(root);
+  const config = await readConfig(root);
+  const profile = baseline?.profile ?? deriveProfile(facts);
+  const selected = LENSES.filter(
+    (lens) => (!opts.kind || lens.kind === opts.kind) && (!opts.lensIds || opts.lensIds.includes(lens.id))
+  );
+  const reports = [];
+  for (const lens of selected) {
+    try {
+      reports.push(await lens.run({ root, facts, profile, baseline, config }));
+    } catch (err) {
+      reports.push({
+        lens: lens.id,
+        version: lens.version,
+        title: lens.title,
+        kind: lens.kind,
+        status: "skipped",
+        reason: err instanceof Error ? err.message : String(err),
+        disclosures: [],
+        findings: []
+      });
+    }
+  }
+  const all = reports.flatMap((r) => r.findings);
+  const previous = await readLedger(root);
+  const outOfScope = reports.flatMap((r) => r.outOfScope ?? []);
+  const { ledger, diff } = reconcileLedger(previous, all, void 0, outOfScope);
+  const fullRun = selected.length === LENSES.length;
+  if ((opts.persistLedger ?? true) && fullRun) {
+    await writeLedger(root, ledger);
+  }
+  return {
+    facts,
+    profile,
+    baseline,
+    config,
+    reports,
+    findings: rankFindings(visibleFindings(all, previous)),
+    ledger,
+    diff
+  };
+}
+
+export { CONFIG_FILE, DEFAULT_CONFIG, EXTRACTION_THRESHOLD, LENSES, NAME, PACK_VERSION, TOTAL_BUDGET_WORDS, VERSION, applyFiles, baselineCarriesMachinePath, baselinePath, buildGateInventory, cacheFactsPath, configPath, contextEconomyLens, deriveProfile, extractCommandClaims, extractPathClaims, gateIntegrityLens, instructionTruthLens, isAlwaysAppliedCursorRule, listInstructionFiles, measureContext, planWorkflow, rankFindings, readBaseline, readCachedFacts, readConfig, readLedger, reconcileLedger, runAudit, scanProject, withoutMachinePath, writeBaseline, writeCachedFacts, writeLedger };