etymd 0.13.0 → 0.15.0

package/dist/chunk-IWG77WV3.js

@@ -0,0 +1,758 @@
+#!/usr/bin/env node
+import { expandFileGlobs } from './chunk-Y6RZRED3.js';
+import { DEFAULT_CONFIG, CONFIG_FILE } from './chunk-P6ATKV2R.js';
+import { readText, isDirectory, matchesAnyGlob, normalizeRelPath, readJson, pathExists, git } from './chunk-4VPBP6K6.js';
+import path3 from 'path';
+import { promises } from 'fs';
+
+// src/engine/finding.ts
+var TIER_ORDER = { risk: 0, gap: 1, polish: 2 };
+var EFFORT_ORDER = { S: 0, M: 1, L: 2 };
+function parseFailOnTier(value) {
+  if (value === "risk" || value === "gap" || value === "polish") return value;
+  throw new Error(`--fail-on must be risk|gap|polish, got \`${value}\``);
+}
+function meetsFailOn(findings, failOn) {
+  const threshold = TIER_ORDER[failOn];
+  return findings.some((f) => TIER_ORDER[f.tier] <= threshold);
+}
+function rankFindings(findings) {
+  return [...findings].sort(
+    (a, b) => TIER_ORDER[a.tier] - TIER_ORDER[b.tier] || EFFORT_ORDER[a.effort] - EFFORT_ORDER[b.effort]
+  );
+}
+var LENS_ID = "state-freshness";
+var DECISIONS_FORMAT_MARKER = "<!-- decisions-format: 1 -->";
+var KNOWN_FORMAT_VERSION = 1;
+var MARKER_RE = /<!--\s*decisions-format:\s*(\d+)([^>]*?)-->/;
+var FIELD_NAME_RE = /^[A-Za-z0-9 _-]+$/;
+var BUILT_IN_FIELDS = /* @__PURE__ */ new Set(["scope"]);
+var MS_PER_DAY = 864e5;
+function parseDecisionsFormat(text) {
+  const m = MARKER_RE.exec(text);
+  if (!m) return null;
+  const problems = [];
+  const fields = [];
+  const offset = m.index ?? 0;
+  const version = Number(m[1]);
+  if (version !== KNOWN_FORMAT_VERSION) {
+    problems.push(
+      `declares decisions-format version ${version}; this etymd understands version ${KNOWN_FORMAT_VERSION} \u2014 checked as version ${KNOWN_FORMAT_VERSION}.`
+    );
+  }
+  const attrs = (m[2] ?? "").trim();
+  if (!attrs) return { fields, offset, problems };
+  const declared = /^fields=(.*)$/.exec(attrs);
+  if (!declared) {
+    problems.push(`marker attribute \`${attrs}\` is not understood \u2014 ignored (only \`fields=\`).`);
+    return { fields, offset, problems };
+  }
+  const seen = new Set(BUILT_IN_FIELDS);
+  for (const raw of declared[1].split(",")) {
+    const name = raw.trim();
+    if (!name) continue;
+    if (!FIELD_NAME_RE.test(name)) {
+      problems.push(
+        `declared field \`${name}\` is not a usable field name (letters, digits, spaces, \`-\`, \`_\`) \u2014 not checked.`
+      );
+      continue;
+    }
+    const key = name.toLowerCase();
+    if (seen.has(key)) continue;
+    seen.add(key);
+    fields.push(name);
+  }
+  if (fields.length === 0 && problems.length === 0) {
+    problems.push("marker declares `fields=` with no field names \u2014 no extra fields checked.");
+  }
+  return { fields, offset, problems };
+}
+function hasField(block, name) {
+  return new RegExp(`${name.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}[\\s*]*:`).test(block);
+}
+function parseDecisionEntries(text) {
+  const headings = [...text.matchAll(/^## .*$/gm)];
+  const entries = [];
+  for (let i = 0; i < headings.length; i++) {
+    const h = headings[i];
+    const m = /^## (D-(\d+))\b/.exec(h[0]);
+    if (!m) continue;
+    const offset = h.index ?? 0;
+    const start = offset + h[0].length;
+    const end = i + 1 < headings.length ? headings[i + 1].index : void 0;
+    entries.push({ id: m[1], num: Number(m[2]), block: text.slice(start, end), offset });
+  }
+  return entries;
+}
+function checkIdSequence(file, entries) {
+  const findings = [];
+  const nextFree = Math.max(0, ...entries.map((e) => e.num)) + 1;
+  const seen = /* @__PURE__ */ new Map();
+  const duplicated = /* @__PURE__ */ new Set();
+  let prev;
+  for (const entry of entries) {
+    if (seen.has(entry.num)) {
+      if (!duplicated.has(entry.num)) {
+        duplicated.add(entry.num);
+        findings.push({
+          id: `${LENS_ID}/duplicate-id:${file}:${entry.id}`,
+          lens: LENS_ID,
+          tier: "gap",
+          claim: `${file} carries more than one ${entry.id} entry`,
+          evidence: [`${file}: ${entry.id} appears twice`],
+          why: "Two decisions under one id cannot be cited, superseded, or dismissed unambiguously \u2014 append races collide exactly here.",
+          action: `Rename the later entry to D-${String(nextFree).padStart(3, "0")} (the next free id).`,
+          effort: "S",
+          confidence: "high"
+        });
+      }
+    } else {
+      seen.set(entry.num, entry);
+      if (prev && entry.num < prev.num) {
+        findings.push({
+          id: `${LENS_ID}/id-order:${file}:${entry.id}`,
+          lens: LENS_ID,
+          tier: "gap",
+          claim: `${file} lists ${entry.id} after ${prev.id} \u2014 ids out of append order`,
+          evidence: [`${file}: ${prev.id} precedes ${entry.id}`],
+          why: "An append-only record reads in id order; out-of-order ids make the newest decision hard to find and the next id hard to pick.",
+          action: `Rename the out-of-order entry into sequence (next free id: D-${String(nextFree).padStart(3, "0")}).`,
+          effort: "S",
+          confidence: "high"
+        });
+      }
+      prev = entry;
+    }
+  }
+  return findings;
+}
+function checkFormatFields(file, entries, today, declaredFields, markerOffset) {
+  const findings = [];
+  for (const entry of entries) {
+    const bound = entry.offset >= markerOffset;
+    for (const field of bound ? declaredFields : []) {
+      if (hasField(entry.block, field)) continue;
+      findings.push({
+        id: `${LENS_ID}/field-missing:${file}:${entry.id}:${field}`,
+        lens: LENS_ID,
+        tier: "gap",
+        claim: `${file} ${entry.id} has no ${field}: field`,
+        evidence: [`${file}: ${entry.id}`, `${file} marker declares required field \`${field}\``],
+        why: "The file declares this field required on every entry after the marker; whatever reads the record for it finds nothing here.",
+        action: `Add a ${field}: line to ${entry.id}.`,
+        effort: "S",
+        confidence: "high"
+      });
+    }
+    if (bound && !/Scope[\s*]*:/.test(entry.block)) {
+      findings.push({
+        id: `${LENS_ID}/scope-missing:${file}:${entry.id}`,
+        lens: LENS_ID,
+        tier: "gap",
+        claim: `${file} ${entry.id} has no Scope: field`,
+        evidence: [`${file}: ${entry.id}`],
+        why: "A decision without a scope binds nobody \u2014 a reader cannot tell whether it covers the project they are working in.",
+        action: "Add a Scope: line naming what the decision binds.",
+        effort: "S",
+        confidence: "high"
+      });
+    }
+    const revisit = /Revisit[\s*]*:[\s*]*(\d{4}-\d{2}-\d{2})/.exec(entry.block);
+    if (revisit && revisit[1] < today) {
+      findings.push({
+        id: `${LENS_ID}/revisit-due:${file}:${entry.id}`,
+        lens: LENS_ID,
+        tier: "gap",
+        claim: `${file} ${entry.id} was due for revisit on ${revisit[1]}`,
+        evidence: [`${file}: ${entry.id} Revisit: ${revisit[1]}`],
+        why: "Review debt is due \u2014 a Revisit date is a promise to re-evaluate, and a past one silently hardens into policy.",
+        action: "Re-evaluate the decision: supersede it or move the Revisit date.",
+        effort: "S",
+        confidence: "high"
+      });
+    }
+  }
+  return findings;
+}
+var stateFreshnessLens = {
+  id: LENS_ID,
+  version: "1",
+  title: "State freshness",
+  kind: "truth",
+  async run(ctx) {
+    const budgets = ctx.config?.config.state ?? DEFAULT_CONFIG.state;
+    const findings = [];
+    const disclosures = [...ctx.config?.problems ?? []];
+    const outOfScope = [];
+    const today = (/* @__PURE__ */ new Date()).toISOString().slice(0, 10);
+    const stateArtifacts = ctx.facts.artifacts.filter((a) => a.kind === "state" && a.exists);
+    const decisionArtifacts = ctx.facts.artifacts.filter((a) => a.kind === "decisions" && a.exists);
+    if (stateArtifacts.length === 0 && decisionArtifacts.length === 0) {
+      disclosures.push("No state or decisions artifacts detected \u2014 nothing to check.");
+    }
+    const freshness = ctx.facts.freshness;
+    if (!freshness) {
+      disclosures.push("Scan carried no freshness facts \u2014 staleness unchecked.");
+    } else {
+      for (const u of freshness.unverifiable) {
+        disclosures.push(`Freshness of ${u.path} is unverifiable (${u.reason}) \u2014 not flagged.`);
+      }
+      for (const a of stateArtifacts) {
+        const fact = freshness.artifacts.find((f) => f.artifactId === a.id);
+        if (!fact || !freshness.repoLastCommit) continue;
+        if (fact.dirty) {
+          disclosures.push(
+            `${a.path} has uncommitted changes \u2014 modified since its last commit; treated fresh-now, not flagged.`
+          );
+          continue;
+        }
+        if (!fact.commitsSince) continue;
+        const gapDays = Math.floor(
+          (Date.parse(freshness.repoLastCommit) - Date.parse(fact.lastCommit)) / MS_PER_DAY
+        );
+        if (gapDays <= budgets.staleAfterDays) continue;
+        const escalated = gapDays > budgets.staleAfterDays * 3;
+        findings.push({
+          id: `${LENS_ID}/stale-state:${a.path}`,
+          lens: LENS_ID,
+          tier: escalated ? "risk" : "gap",
+          claim: `${a.path} trails the repo by ${gapDays} days of commit traffic \u2014 it says "now" but the repo moved on`,
+          evidence: [
+            `${a.path} last commit: ${fact.lastCommit}`,
+            `repo last commit: ${freshness.repoLastCommit}`
+          ],
+          why: escalated ? `Over three times the ${budgets.staleAfterDays}-day threshold while commits kept landing \u2014 every session starts from a picture of the project that is no longer true.` : `A state doc more than ${budgets.staleAfterDays} days behind continued commit traffic misleads every session that loads it.`,
+          action: "Refresh the state doc (or record why it is still current).",
+          effort: "S",
+          confidence: "high"
+        });
+      }
+    }
+    for (const a of stateArtifacts) {
+      const text = await readText(path3.join(ctx.root, a.path));
+      if (text === null) {
+        disclosures.push(`${a.path} could not be read \u2014 unexamined, not clean.`);
+        outOfScope.push(a.path);
+        continue;
+      }
+      if (text.length > budgets.maxChars) {
+        findings.push({
+          id: `${LENS_ID}/state-over-budget:${a.path}`,
+          lens: LENS_ID,
+          tier: "gap",
+          claim: `${a.path} is ${text.length} chars \u2014 over the ${budgets.maxChars}-char state budget`,
+          evidence: [`${a.path}: ${text.length} chars`],
+          why: "Session-injection hooks truncate state around 10,000 chars \u2014 an over-budget state doc gets cut mid-sentence, and every session pays its full weight before the task begins.",
+          action: "Trim to budget; move overflow into decisions/docs and keep a pointer.",
+          effort: "M",
+          confidence: "high"
+        });
+      }
+    }
+    for (const a of decisionArtifacts) {
+      const text = await readText(path3.join(ctx.root, a.path));
+      if (text === null) {
+        disclosures.push(
+          `${a.path} recognized as a decisions convention (directory) \u2014 age-exempt; per-entry format checks apply only to marker-carrying decisions files.`
+        );
+        continue;
+      }
+      const entries = parseDecisionEntries(text);
+      findings.push(...checkIdSequence(a.path, entries));
+      const format = parseDecisionsFormat(text);
+      if (!format) {
+        disclosures.push(
+          `${a.path} carries no \`${DECISIONS_FORMAT_MARKER}\` marker \u2014 format checks skipped (forward-only, never retroactive); id-sequence checks still ran.`
+        );
+        outOfScope.push(a.path);
+        continue;
+      }
+      for (const problem of format.problems) disclosures.push(`${a.path}: ${problem}`);
+      const exempt = entries.filter((e) => e.offset < format.offset);
+      if (format.fields.length > 0) {
+        disclosures.push(
+          `${a.path} declares required entry fields: ${format.fields.join(", ")} \u2014 checked on every entry at or after the marker (etymd attaches no meaning to the names).`
+        );
+      }
+      if (exempt.length > 0) {
+        disclosures.push(
+          `${a.path}: ${exempt.length} entr${exempt.length === 1 ? "y" : "ies"} precede the format marker (${exempt[0]?.id}\u2026${exempt[exempt.length - 1]?.id}) \u2014 field presence not checked there (forward-only from the marker's position).`
+        );
+      }
+      findings.push(...checkFormatFields(a.path, entries, today, format.fields, format.offset));
+    }
+    disclosures.push(
+      `Thresholds: staleAfterDays ${budgets.staleAfterDays} (3x escalates to risk), state budget ${budgets.maxChars} chars (${budgets.staleAfterDays === DEFAULT_CONFIG.state.staleAfterDays && budgets.maxChars === DEFAULT_CONFIG.state.maxChars ? `defaults \u2014 override under \`state\` in ${CONFIG_FILE}` : `set in ${CONFIG_FILE}`}). Decisions artifacts are exempt from age \u2014 old decisions are history, not defects.`
+    );
+    return {
+      lens: LENS_ID,
+      version: "1",
+      title: "State freshness",
+      kind: "truth",
+      status: "ran",
+      disclosures,
+      findings,
+      ...outOfScope.length ? { outOfScope } : {}
+    };
+  }
+};
+async function listInstructionFiles(root, facts, scope) {
+  const files = [];
+  const add = async (rel) => {
+    const text = await readText(path3.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 = path3.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(path3.join(".cursor/rules", entry));
+      }
+    } catch {
+    }
+  }
+  const skillsDir = path3.join(root, ".claude", "skills");
+  if (await isDirectory(skillsDir)) {
+    try {
+      for (const entry of await promises.readdir(skillsDir)) {
+        const skill = path3.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 };
+}
+async function listStateDocuments(root, facts) {
+  const docs = [];
+  for (const artifact of facts.artifacts) {
+    if (artifact.kind !== "state" || !artifact.exists) continue;
+    const text = await readText(path3.join(root, artifact.path));
+    if (text !== null) docs.push({ path: normalizeRelPath(artifact.path), text });
+  }
+  return docs;
+}
+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] };
+}
+var LOCAL_REF_LEADINS = new Set(
+  "decision decisions entry entries ruling rulings record records ledger id ids item items see per in of on at by to as is was are were the a an and or but not with under over from via vs than after before since between through against latest newest earliest only also still now supersedes superseded superseding amends amended extends extended cites cited citing adds added adding wrote written writes locked locks closed closes opened opens resolves resolved reopened recorded number numbers".split(" ")
+);
+function extractDecisionRefs(text) {
+  const byNum = /* @__PURE__ */ new Map();
+  for (const m of text.matchAll(/\bD-(\d{1,4})\b/g)) {
+    const index = m.index ?? 0;
+    if (index > 0 && /[-/_.]/.test(text[index - 1])) continue;
+    const before = text.slice(Math.max(0, index - 48), index);
+    const lead = /([A-Za-z][A-Za-z0-9'’-]*)[ \t]+$/.exec(before)?.[1];
+    const local = !lead || LOCAL_REF_LEADINS.has(lead.toLowerCase());
+    const num = Number(m[1]);
+    const seen = byNum.get(num);
+    if (!seen) byNum.set(num, { asWritten: m[0], local });
+    else seen.local = seen.local || local;
+  }
+  const refs = /* @__PURE__ */ new Map();
+  let qualifiedSkipped = 0;
+  for (const [num, ref] of byNum) {
+    if (ref.local) refs.set(num, ref.asWritten);
+    else qualifiedSkipped += 1;
+  }
+  return { refs, qualifiedSkipped };
+}
+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",
+  "DECISIONS.md",
+  "GEMINI.md"
+];
+var PATH_TOKEN_CHARS = /[A-Za-z0-9_.$~/-]/;
+function extractDocRefs(text) {
+  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 };
+}
+async function buildTruthEnv(root, facts) {
+  const knownScripts = new Set(Object.keys(facts.commands.raw));
+  for (const pkg of facts.packages) {
+    const pkgJson = await readJson(
+      path3.join(root, pkg.dir, "package.json")
+    );
+    for (const key of Object.keys(pkgJson?.scripts ?? {})) knownScripts.add(key);
+  }
+  const bases = [root, ...facts.packages.map((p) => path3.join(root, p.dir))];
+  const pathResolves = async (claim) => {
+    for (const base of bases) {
+      if (await pathExists(path3.join(base, claim))) return true;
+      if (await pathExists(path3.join(base, "src", claim))) return true;
+      if (await pathExists(path3.join(base, "scripts", claim))) return true;
+    }
+    return false;
+  };
+  const binResolves = async (name) => {
+    for (const base of bases) {
+      if (await pathExists(path3.join(base, "node_modules", ".bin", name))) return true;
+    }
+    return false;
+  };
+  const nodeModulesInstalled = await pathExists(path3.join(root, "node_modules"));
+  const manifestExists = await pathExists(path3.join(root, "package.json")) || facts.packages.length > 0;
+  return {
+    root,
+    facts,
+    knownScripts,
+    nodeModulesInstalled,
+    manifestExists,
+    bases,
+    pathResolves,
+    binResolves
+  };
+}
+function emptyCounters() {
+  return {
+    filteredSkipped: 0,
+    tildeSkipped: 0,
+    binaryResolved: 0,
+    unverifiableCommands: 0,
+    gitignoredSkipped: 0,
+    prospectiveSkipped: 0,
+    placeholderSkipped: 0,
+    qualifiedRefsSkipped: 0,
+    unresolvableRefs: 0
+  };
+}
+async function checkTextClaims(env, file, opts, counters) {
+  const findings = [];
+  const disclosures = [];
+  const examined = [];
+  const subject = opts.subject ?? file.path;
+  const { scripts: claimed, filteredSkipped } = extractCommandClaims(file.text);
+  counters.filteredSkipped += filteredSkipped;
+  for (const [script, raw] of claimed) {
+    if (env.knownScripts.has(script)) {
+      examined.push({ kind: "script", value: script, exists: true });
+      continue;
+    }
+    if (await env.binResolves(script)) {
+      counters.binaryResolved += 1;
+      examined.push({ kind: "script", value: script, exists: true });
+      continue;
+    }
+    if (!env.nodeModulesInstalled && env.manifestExists) {
+      counters.unverifiableCommands += 1;
+      examined.push({ kind: "script", value: script, exists: null });
+      continue;
+    }
+    examined.push({ kind: "script", value: script, exists: false });
+    findings.push({
+      lens: opts.lensId,
+      id: `${opts.lensId}/stale-command:${file.path}:${script}`,
+      tier: "risk",
+      claim: `${subject} tells agents to run \`${script}\` \u2014 no such script exists`,
+      evidence: [`${file.path}: \`${raw}\``, "package.json scripts (root + workspaces)"],
+      why: opts.whyCommand ?? "An agent following this instruction runs a command that fails \u2014 or silently skips the check it was meant to run.",
+      action: opts.actionCommand ?? "Update the instruction to the current script name (or restore the script).",
+      effort: "S",
+      confidence: "high"
+    });
+  }
+  const { paths, prospective, placeholder } = extractPathClaims(file.text);
+  counters.prospectiveSkipped += prospective.length;
+  counters.placeholderSkipped += placeholder.length;
+  const missing = [];
+  for (const claim of paths) {
+    if (await env.pathResolves(claim)) examined.push({ kind: "path", value: claim, exists: true });
+    else missing.push(claim);
+  }
+  const ignoredOut = missing.length ? await git(env.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)) {
+      counters.gitignoredSkipped += 1;
+      examined.push({ kind: "path", value: claim, exists: null });
+      continue;
+    }
+    examined.push({ kind: "path", value: claim, exists: false });
+    if (pathFindings >= opts.maxPathFindings) {
+      if (pathFindings === opts.maxPathFindings) {
+        disclosures.push(
+          `${file.path}: more than ${opts.maxPathFindings} missing-path claims \u2014 truncated.`
+        );
+        pathFindings += 1;
+      }
+      continue;
+    }
+    pathFindings += 1;
+    findings.push({
+      lens: opts.lensId,
+      id: `${opts.lensId}/stale-path:${file.path}:${claim}`,
+      tier: opts.missingPathTier,
+      claim: `${subject} references \`${claim}\` \u2014 it does not exist in the repo`,
+      evidence: [file.path, `missing: ${claim}`],
+      why: opts.whyPath ?? "Agents navigate by these references; a dead path wastes a lookup and erodes trust in the rest of the file.",
+      action: opts.actionPath ?? "Fix or remove the reference.",
+      effort: "S",
+      confidence: "medium"
+    });
+  }
+  return { findings, disclosures, examined };
+}
+async function checkDocRefs(env, file, lensId, counters, subject = file.path) {
+  const findings = [];
+  const examined = [];
+  const { refs, tildeSkipped } = extractDocRefs(file.text);
+  counters.tildeSkipped += tildeSkipped;
+  for (const ref of refs) {
+    const exists = await pathExists(path3.join(env.root, ref));
+    examined.push({ kind: "doc", value: ref, exists });
+    if (exists) continue;
+    findings.push({
+      lens: lensId,
+      id: `${lensId}/dangling-ref:${file.path}:${ref}`,
+      tier: "gap",
+      claim: `${subject} 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"
+    });
+  }
+  return { findings, examined };
+}
+async function loadDecisionLedger(root, facts) {
+  let ids = null;
+  const sources = [];
+  for (const artifact of facts.artifacts) {
+    if (artifact.kind !== "decisions" || !artifact.exists) continue;
+    const text = await readText(path3.join(root, artifact.path));
+    if (text === null) continue;
+    const entries = parseDecisionEntries(text);
+    if (!entries.length) continue;
+    ids ??= /* @__PURE__ */ new Set();
+    for (const entry of entries) ids.add(entry.num);
+    sources.push(artifact.path);
+  }
+  return { ids, sources };
+}
+function checkDecisionRefs(file, ledger, opts, counters) {
+  const findings = [];
+  const examined = [];
+  const subject = opts.subject ?? file.path;
+  const { refs, qualifiedSkipped } = extractDecisionRefs(file.text);
+  counters.qualifiedRefsSkipped += qualifiedSkipped;
+  if (!refs.size) return { findings, examined };
+  if (!ledger.ids) {
+    counters.unresolvableRefs += refs.size;
+    for (const asWritten of refs.values()) {
+      examined.push({ kind: "decision", value: asWritten, exists: null });
+    }
+    return { findings, examined };
+  }
+  for (const [num, asWritten] of refs) {
+    const exists = ledger.ids.has(num);
+    examined.push({ kind: "decision", value: asWritten, exists });
+    if (exists) continue;
+    findings.push({
+      lens: opts.lensId,
+      id: `${opts.lensId}/dead-decision-ref:${file.path}:${asWritten}`,
+      tier: "gap",
+      claim: `${subject} cites ${asWritten} \u2014 no such entry exists in ${ledger.sources.join(", ")}`,
+      evidence: [file.path, `${ledger.sources.join(", ")}: no ${asWritten} entry`],
+      why: opts.why ?? "A state doc is read as ground truth on return; a citation the decision record cannot back sends readers to a ruling that was never written.",
+      action: opts.action ?? "Fix the reference \u2014 or record the missing decision.",
+      effort: "S",
+      confidence: "medium"
+    });
+  }
+  return { findings, examined };
+}
+
+export { KNOWN_EXTENSIONS, PATH_TOKEN_RE, buildTruthEnv, checkDecisionRefs, checkDocRefs, checkTextClaims, emptyCounters, listInstructionFiles, listStateDocuments, loadDecisionLedger, meetsFailOn, packageManagerUsage, parseFailOnTier, rankFindings, stateFreshnessLens };