etymd 0.8.0 → 0.9.1

package/dist/index.js

@@ -30,7 +30,7 @@ var init_package = __esm({
   "package.json"() {
     package_default = {
       name: "etymd",
-      version: "0.8.0",
+      version: "0.9.1",
       description: "Keep your agent instructions true \u2014 verify AGENTS.md, CLAUDE.md, rules & skills against the actual repo, with drift caught over time and a regression ledger.",
       keywords: [
         "cli",
@@ -2121,793 +2121,888 @@ init_config();
 init_facts();
 init_util();
 
-// src/lenses/instruction-truth/claims.ts
-init_detect();
+// src/lenses/state-freshness.ts
+init_config();
 init_util();
-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);
-    }
+var LENS_ID3 = "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}.`
+    );
   }
-  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}`;
+  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 };
   }
-  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);
+  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 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);
+    const key = name.toLowerCase();
+    if (seen.has(key)) continue;
+    seen.add(key);
+    fields.push(name);
   }
-  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);
-    }
+  if (fields.length === 0 && problems.length === 0) {
+    problems.push("marker declares `fields=` with no field names \u2014 no extra fields checked.");
   }
-  return counts;
+  return { fields, offset, problems };
 }
-var KNOWN_DOC_REFS = [
-  "AGENTS.md",
-  "CLAUDE.md",
-  "PROJECT_CONTEXT.md",
-  "DECISIONS.md",
-  "GEMINI.md"
-];
-function extractDocRefs(text) {
-  return KNOWN_DOC_REFS.filter((name) => text.includes(name));
+function hasField(block, name) {
+  return new RegExp(`${name.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}[\\s*]*:`).test(block);
 }
-
-// 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 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 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.",
+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_ID3}/duplicate-id:${file}:${entry.id}`,
+          lens: LENS_ID3,
+          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_ID3}/id-order:${file}:${entry.id}`,
+          lens: LENS_ID3,
+          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 out;
+  return findings;
 }
-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"
-        })
-      );
+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_ID3}/field-missing:${file}:${entry.id}:${field}`,
+        lens: LENS_ID3,
+        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_ID3}/scope-missing:${file}:${entry.id}`,
+        lens: LENS_ID3,
+        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_ID3}/revisit-due:${file}:${entry.id}`,
+        lens: LENS_ID3,
+        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 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"
-    })
-  );
+  return findings;
 }
-var instructionTruthLens = {
+var stateFreshnessLens = {
   id: LENS_ID3,
   version: "1",
-  title: "Instruction truth",
+  title: "State freshness",
   kind: "truth",
   async run(ctx) {
+    const budgets = ctx.config?.config.state ?? DEFAULT_CONFIG.state;
     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 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 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 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.`);
       }
-      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) {
+      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(
-            `${file.path}: more than ${MAX_PATH_FINDINGS_PER_FILE} missing-path claims \u2014 truncated.`
+            `${a.path} has uncommitted changes \u2014 modified since its last commit; treated fresh-now, not flagged.`
           );
-          break;
+          continue;
         }
-        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 (!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_ID3}/stale-state:${a.path}`,
+          lens: LENS_ID3,
+          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"
+        });
       }
-      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 a of stateArtifacts) {
+      const text = await readText(path.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_ID3}/state-over-budget:${a.path}`,
+          lens: LENS_ID3,
+          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 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"
-          })
+    }
+    for (const a of decisionArtifacts) {
+      const text = await readText(path.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;
       }
-    }
-    if (ctx.baseline) {
-      findings.push(
-        ...compareCommands(ctx.baseline.facts, facts),
-        ...compareArtifacts(ctx.baseline.facts, facts),
-        ...compareLayout(ctx.baseline.facts, facts)
-      );
-      if (baselineCarriesMachinePath(ctx.baseline)) {
+      const entries = parseDecisionEntries(text);
+      findings.push(...checkIdSequence(a.path, entries));
+      const format = parseDecisionsFormat(text);
+      if (!format) {
         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.`
+          `${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;
       }
-      if (ctx.baseline.packVersion !== PACK_VERSION) {
+      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(
-          `Baseline was approved under pack v${ctx.baseline.packVersion}; current pack is v${PACK_VERSION}.`
+          `${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).`
         );
       }
-    } 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` : ""}.`
-      );
+      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(
-      `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.`
+      `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_ID3,
       version: "1",
-      title: "Instruction truth",
+      title: "State freshness",
       kind: "truth",
       status: "ran",
       disclosures,
       findings,
-      outOfScope: excluded
+      ...outOfScope.length ? { outOfScope } : {}
     };
   }
 };
 
-// src/lenses/state-freshness.ts
-init_config();
+// src/lenses/instruction-truth/claims.ts
+init_detect();
 init_util();
-var LENS_ID4 = "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}.`
-    );
+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 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 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 };
+}
+async function listStateDocuments(root, facts) {
+  const docs = [];
+  for (const artifact of facts.artifacts) {
+    if (artifact.kind !== "state" || !artifact.exists) continue;
+    const text = await readText(path.join(root, artifact.path));
+    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}`;
   }
-  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.`
-      );
+  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 key = name.toLowerCase();
-    if (seen.has(key)) continue;
-    seen.add(key);
-    fields.push(name);
+    const prospective2 = CREATION_CONTEXT_RE.test(claimContext(text, m.index ?? 0));
+    prospectiveOnly.set(claim, (prospectiveOnly.get(claim) ?? true) && prospective2);
   }
-  if (fields.length === 0 && problems.length === 0) {
-    problems.push("marker declares `fields=` with no field names \u2014 no extra fields checked.");
+  const paths = [];
+  const prospective = [];
+  for (const [claim, only] of prospectiveOnly) {
+    if (only) prospective.push(claim);
+    else paths.push(claim);
   }
-  return { fields, offset, problems };
+  return { paths, prospective, placeholder: [...placeholder] };
 }
-function hasField(block, name) {
-  return new RegExp(`${name.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}[\\s*]*:`).test(block);
+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 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 });
+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 entries;
+  return counts;
 }
-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_ID4}/duplicate-id:${file}:${entry.id}`,
-          lens: LENS_ID4,
-          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).`,
+var KNOWN_DOC_REFS = [
+  "AGENTS.md",
+  "CLAUDE.md",
+  "PROJECT_CONTEXT.md",
+  "DECISIONS.md",
+  "GEMINI.md"
+];
+function extractDocRefs(text) {
+  return KNOWN_DOC_REFS.filter((name) => text.includes(name));
+}
+
+// src/lenses/instruction-truth/lens.ts
+var LENS_ID4 = "instruction-truth";
+var MAX_PATH_FINDINGS_PER_FILE = 15;
+function finding2(partial) {
+  return { lens: LENS_ID4, ...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_ID4}/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"
-        });
-      }
-    } else {
-      seen.set(entry.num, entry);
-      if (prev && entry.num < prev.num) {
-        findings.push({
-          id: `${LENS_ID4}/id-order:${file}:${entry.id}`,
-          lens: LENS_ID4,
+        })
+      );
+    }
+  }
+  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_ID4}/artifact-gone-${a.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")}).`,
+          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"
-        });
-      }
-      prev = entry;
+        })
+      );
     }
   }
-  return findings;
+  return out;
 }
-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_ID4}/field-missing:${file}:${entry.id}:${field}`,
-        lens: LENS_ID4,
-        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_ID4}/scope-missing:${file}:${entry.id}`,
-        lens: LENS_ID4,
-        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_ID4}/revisit-due:${file}:${entry.id}`,
-        lens: LENS_ID4,
-        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;
+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_ID4}/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 stateFreshnessLens = {
+var instructionTruthLens = {
   id: LENS_ID4,
   version: "1",
-  title: "State freshness",
+  title: "Instruction truth",
   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 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_ID4}/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 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.`);
+    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;
       }
-      for (const a of stateArtifacts) {
-        const fact = freshness.artifacts.find((f) => f.artifactId === a.id);
-        if (!fact || !freshness.repoLastCommit) continue;
-        if (fact.dirty) {
+      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"));
+    const manifestExists = await pathExists(path.join(root, "package.json")) || facts.packages.length > 0;
+    let totalFilteredSkipped = 0;
+    let binaryResolved = 0;
+    let unverifiableCommands = 0;
+    let gitignoredSkipped = 0;
+    let prospectiveSkipped = 0;
+    let placeholderSkipped = 0;
+    const auditClaims = async (file) => {
+      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 && manifestExists) {
+          unverifiableCommands += 1;
+          continue;
+        }
+        findings.push(
+          finding2({
+            id: `${LENS_ID4}/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(
-            `${a.path} has uncommitted changes \u2014 modified since its last commit; treated fresh-now, not flagged.`
+            `${file.path}: more than ${MAX_PATH_FINDINGS_PER_FILE} missing-path claims \u2014 truncated.`
           );
-          continue;
+          break;
         }
-        if (!fact.commitsSince) continue;
-        const gapDays = Math.floor(
-          (Date.parse(freshness.repoLastCommit) - Date.parse(fact.lastCommit)) / MS_PER_DAY
+        pathFindings += 1;
+        findings.push(
+          finding2({
+            id: `${LENS_ID4}/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 (gapDays <= budgets.staleAfterDays) continue;
-        const escalated = gapDays > budgets.staleAfterDays * 3;
-        findings.push({
-          id: `${LENS_ID4}/stale-state:${a.path}`,
-          lens: LENS_ID4,
-          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(path.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;
+    };
+    for (const file of files) {
+      await auditClaims(file);
+      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_ID4}/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;
+        }
       }
-      if (text.length > budgets.maxChars) {
-        findings.push({
-          id: `${LENS_ID4}/state-over-budget:${a.path}`,
-          lens: LENS_ID4,
-          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 ref of extractDocRefs(file.text)) {
+        if (await pathExists(path.join(root, ref))) continue;
+        findings.push(
+          finding2({
+            id: `${LENS_ID4}/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"
+          })
+        );
       }
     }
-    for (const a of decisionArtifacts) {
-      const text = await readText(path.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.`
-        );
+    const auditedPaths = new Set(files.map((f) => f.path));
+    const stateDocs = await listStateDocuments(root, facts);
+    let qualifiedRefsSkipped = 0;
+    let unresolvableRefs = 0;
+    let ledgerIds = null;
+    const ledgerSources = [];
+    if (stateDocs.length) {
+      for (const artifact of facts.artifacts) {
+        if (artifact.kind !== "decisions" || !artifact.exists) continue;
+        const text = await readText(path.join(root, artifact.path));
+        if (text === null) continue;
+        const entries = parseDecisionEntries(text);
+        if (!entries.length) continue;
+        ledgerIds ??= /* @__PURE__ */ new Set();
+        for (const entry of entries) ledgerIds.add(entry.num);
+        ledgerSources.push(artifact.path);
+      }
+    }
+    for (const doc of stateDocs) {
+      if (!auditedPaths.has(doc.path)) await auditClaims(doc);
+      const { refs, qualifiedSkipped } = extractDecisionRefs(doc.text);
+      qualifiedRefsSkipped += qualifiedSkipped;
+      if (!refs.size) continue;
+      if (!ledgerIds) {
+        unresolvableRefs += refs.size;
         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.`
+      for (const [num, asWritten] of refs) {
+        if (ledgerIds.has(num)) continue;
+        findings.push(
+          finding2({
+            id: `${LENS_ID4}/dead-decision-ref:${doc.path}:${asWritten}`,
+            tier: "gap",
+            claim: `${doc.path} cites ${asWritten} \u2014 no such entry exists in ${ledgerSources.join(", ")}`,
+            evidence: [doc.path, `${ledgerSources.join(", ")}: no ${asWritten} entry`],
+            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: "Fix the reference \u2014 or record the missing decision.",
+            effort: "S",
+            confidence: "medium"
+          })
         );
-        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) {
+    }
+    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(
-          `${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).`
+          `${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 (exempt.length > 0) {
+      if (ctx.baseline.packVersion !== PACK_VERSION) {
         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).`
+          `Baseline was approved under pack v${ctx.baseline.packVersion}; current pack is v${PACK_VERSION}.`
         );
       }
-      findings.push(...checkFormatFields(a.path, entries, today, format.fields, format.offset));
+    } 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 (stateDocs.length) {
+      disclosures.push(
+        `Checked ${stateDocs.length} state document(s) for command, path, and decision-reference claims (same skip classes as instruction files); decision ids resolved against ${ledgerSources.length ? ledgerSources.join(", ") : "nothing \u2014 no decisions file with D-NNN entries"}.`
+      );
+    }
+    if (qualifiedRefsSkipped) {
+      disclosures.push(
+        `${qualifiedRefsSkipped} decision reference(s) name another record (e.g. a fleet-level ledger) \u2014 not claims about this repo's decisions; skipped, not flagged.`
+      );
+    }
+    if (unresolvableRefs) {
+      disclosures.push(
+        `${unresolvableRefs} decision reference(s) could not be resolved \u2014 no decisions file with \`## D-NNN\` entries; 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(
-      `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.`
+      `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_ID4,
       version: "1",
-      title: "State freshness",
+      title: "Instruction truth",
       kind: "truth",
       status: "ran",
       disclosures,
       findings,
-      ...outOfScope.length ? { outOfScope } : {}
+      outOfScope: excluded
     };
   }
 };