etymd 0.7.0 → 0.9.0

package/dist/index.js

@@ -30,7 +30,7 @@ var init_package = __esm({
   "package.json"() {
     package_default = {
       name: "etymd",
-      version: "0.7.0",
+      version: "0.9.0",
       description: "Keep your agent instructions true \u2014 verify AGENTS.md, CLAUDE.md, rules & skills against the actual repo, with drift caught over time and a regression ledger.",
       keywords: [
         "cli",
@@ -924,7 +924,7 @@ async function readConfig(root) {
   const target = configPath(root);
   const problems = [];
   if (!await pathExists(target)) {
-    return { config: DEFAULT_CONFIG, present: false, problems };
+    return { config: DEFAULT_CONFIG, present: false, problems, explicit: { gatesFailOn: false } };
   }
   const raw = await readText(target);
   let parsed;
@@ -934,11 +934,11 @@ async function readConfig(root) {
     problems.push(
       `${CONFIG_FILE} exists but is not valid JSON (${err instanceof Error ? err.message : String(err)}) \u2014 defaults used.`
     );
-    return { config: DEFAULT_CONFIG, present: true, problems };
+    return { config: DEFAULT_CONFIG, present: true, problems, explicit: { gatesFailOn: false } };
   }
   if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
     problems.push(`${CONFIG_FILE} must contain a JSON object \u2014 defaults used.`);
-    return { config: DEFAULT_CONFIG, present: true, problems };
+    return { config: DEFAULT_CONFIG, present: true, problems, explicit: { gatesFailOn: false } };
   }
   const obj = parsed;
   const instructions = obj.instructions ?? {};
@@ -964,6 +964,7 @@ async function readConfig(root) {
   return {
     present: true,
     problems,
+    explicit: { gatesFailOn: failOn !== void 0 },
     config: {
       instructions: {
         include: readGlobList(instructions.include, "instructions.include", problems) ?? DEFAULT_CONFIG.instructions.include,
@@ -1285,8 +1286,10 @@ var init_templates = __esm({
 // src/core/generate.ts
 var generate_exports = {};
 __export(generate_exports, {
+  deriveFailOn: () => deriveFailOn,
   derivedCommands: () => derivedCommands,
-  planWorkflow: () => planWorkflow
+  planWorkflow: () => planWorkflow,
+  riskReachability: () => riskReachability
 });
 function derivedCommands(facts, existingHook) {
   const c = facts.commands;
@@ -1298,6 +1301,24 @@ function derivedCommands(facts, existingHook) {
   }
   return base;
 }
+function riskReachability(facts) {
+  const reasons = [];
+  if (facts.publishRoute !== "none") {
+    reasons.push("an instruction file can name a package script that no longer exists");
+  }
+  if (facts.artifacts.some((a) => a.kind === "state" && a.exists)) {
+    reasons.push("a state doc can fall far enough behind the repo to escalate");
+  }
+  return reasons;
+}
+function deriveFailOn(facts, recorded) {
+  const reachable = riskReachability(facts);
+  if (recorded.explicit) return { failOn: recorded.failOn, source: "config", reachable };
+  if (recorded.failOn === "risk" && reachable.length === 0) {
+    return { failOn: "gap", source: "derived", reachable };
+  }
+  return { failOn: recorded.failOn, source: "default", reachable };
+}
 async function planWorkflow(root, facts, opts) {
   const out = [];
   const add = async (rel, contents, label, executable = false) => {
@@ -2100,6 +2121,285 @@ init_config();
 init_facts();
 init_util();
 
+// src/lenses/state-freshness.ts
+init_config();
+init_util();
+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}.`
+    );
+  }
+  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_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 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_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 findings;
+}
+var stateFreshnessLens = {
+  id: LENS_ID3,
+  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_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"
+        });
+      }
+    }
+    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 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;
+      }
+      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_ID3,
+      version: "1",
+      title: "State freshness",
+      kind: "truth",
+      status: "ran",
+      disclosures,
+      findings,
+      ...outOfScope.length ? { outOfScope } : {}
+    };
+  }
+};
+
 // src/lenses/instruction-truth/claims.ts
 init_detect();
 init_util();
@@ -2160,6 +2460,15 @@ async function listInstructionFiles(root, facts, scope) {
   }
   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());
@@ -2297,6 +2606,30 @@ function extractPathClaims(text) {
   }
   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)) {
@@ -2319,10 +2652,10 @@ function extractDocRefs(text) {
 }
 
 // src/lenses/instruction-truth/lens.ts
-var LENS_ID3 = "instruction-truth";
+var LENS_ID4 = "instruction-truth";
 var MAX_PATH_FINDINGS_PER_FILE = 15;
 function finding2(partial) {
-  return { lens: LENS_ID3, ...partial };
+  return { lens: LENS_ID4, ...partial };
 }
 function compareCommands(baseline, fresh) {
   const out = [];
@@ -2331,7 +2664,7 @@ function compareCommands(baseline, fresh) {
     if (before && !(before in fresh.commands.raw)) {
       out.push(
         finding2({
-          id: `${LENS_ID3}/command-gone-${role}`,
+          id: `${LENS_ID4}/command-gone-${role}`,
           tier: "risk",
           claim: `Documented ${role} command \`${before}\` no longer exists in package.json`,
           evidence: ["package.json"],
@@ -2353,7 +2686,7 @@ function compareArtifacts(baseline, fresh) {
     if (a.exists && now && !now.exists) {
       out.push(
         finding2({
-          id: `${LENS_ID3}/artifact-gone-${a.id}`,
+          id: `${LENS_ID4}/artifact-gone-${a.id}`,
           tier: "gap",
           claim: `${a.label} was present at baseline but is now missing`,
           evidence: [a.path],
@@ -2371,7 +2704,7 @@ 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}`,
+      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}/`],
@@ -2383,7 +2716,7 @@ function compareLayout(baseline, fresh) {
   );
 }
 var instructionTruthLens = {
-  id: LENS_ID3,
+  id: LENS_ID4,
   version: "1",
   title: "Instruction truth",
   kind: "truth",
@@ -2401,7 +2734,7 @@ var instructionTruthLens = {
     if (!files.length) {
       findings.push(
         finding2({
-          id: `${LENS_ID3}/no-contract`,
+          id: `${LENS_ID4}/no-contract`,
           tier: "gap",
           claim: "No agent instruction files exist (AGENTS.md or equivalents)",
           evidence: ["AGENTS.md (missing)"],
@@ -2436,13 +2769,14 @@ var instructionTruthLens = {
       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;
-    for (const file of files) {
+    const auditClaims = async (file) => {
       const { scripts: claimed, filteredSkipped } = extractCommandClaims(file.text);
       totalFilteredSkipped += filteredSkipped;
       for (const [script, raw] of claimed) {
@@ -2451,13 +2785,13 @@ var instructionTruthLens = {
           binaryResolved += 1;
           continue;
         }
-        if (!nodeModulesInstalled) {
+        if (!nodeModulesInstalled && manifestExists) {
           unverifiableCommands += 1;
           continue;
         }
         findings.push(
           finding2({
-            id: `${LENS_ID3}/stale-command:${file.path}:${script}`,
+            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)"],
@@ -2492,7 +2826,7 @@ var instructionTruthLens = {
         pathFindings += 1;
         findings.push(
           finding2({
-            id: `${LENS_ID3}/stale-path:${file.path}:${claim}`,
+            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}`],
@@ -2503,6 +2837,9 @@ var instructionTruthLens = {
           })
         );
       }
+    };
+    for (const file of files) {
+      await auditClaims(file);
       if (facts.packageManager !== "unknown") {
         const usage = packageManagerUsage(file.text);
         const own = usage.get(facts.packageManager) ?? 0;
@@ -2510,7 +2847,7 @@ var instructionTruthLens = {
           if (pm === facts.packageManager || count < 2 || count <= own) continue;
           findings.push(
             finding2({
-              id: `${LENS_ID3}/pm-conflict:${file.path}`,
+              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}`],
@@ -2527,7 +2864,7 @@ var instructionTruthLens = {
         if (await pathExists(path.join(root, ref))) continue;
         findings.push(
           finding2({
-            id: `${LENS_ID3}/dangling-ref:${file.path}:${ref}`,
+            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}`],
@@ -2539,6 +2876,49 @@ var instructionTruthLens = {
         );
       }
     }
+    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;
+      }
+      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"
+          })
+        );
+      }
+    }
     if (ctx.baseline) {
       findings.push(
         ...compareCommands(ctx.baseline.facts, facts),
@@ -2585,6 +2965,21 @@ var instructionTruthLens = {
         `${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(
@@ -2600,7 +2995,7 @@ var instructionTruthLens = {
       `Checked ${files.length} instruction file(s); commands resolved against root + ${facts.packages.length} workspace manifest(s) plus installed binaries; paths matched against root and package roots. Heuristics: workspace-filtered commands skipped (${totalFilteredSkipped}); tokens without a recognized extension treated as prose (a dir claim needs a trailing slash); gitignored claims unverifiable; create-this and stand-in path claims skipped; absolute/globbed/placeholder tokens skipped; framework-pattern staleness not checked.`
     );
     return {
-      lens: LENS_ID3,
+      lens: LENS_ID4,
       version: "1",
       title: "Instruction truth",
       kind: "truth",
@@ -2612,276 +3007,6 @@ var instructionTruthLens = {
   }
 };
 
-// src/lenses/state-freshness.ts
-init_config();
-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 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, problems };
-  const declared = /^fields=(.*)$/.exec(attrs);
-  if (!declared) {
-    problems.push(`marker attribute \`${attrs}\` is not understood \u2014 ignored (only \`fields=\`).`);
-    return { fields, 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, 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 start = (h.index ?? 0) + 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) });
-  }
-  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_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).`,
-          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,
-          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) {
-  const findings = [];
-  for (const entry of entries) {
-    for (const field of 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 (!/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;
-}
-var stateFreshnessLens = {
-  id: LENS_ID4,
-  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_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;
-      }
-      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 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;
-      }
-      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}`);
-      if (format.fields.length > 0) {
-        disclosures.push(
-          `${a.path} declares required entry fields: ${format.fields.join(", ")} \u2014 checked on every entry (etymd attaches no meaning to the names).`
-        );
-      }
-      findings.push(...checkFormatFields(a.path, entries, today, format.fields));
-    }
-    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_ID4,
-      version: "1",
-      title: "State freshness",
-      kind: "truth",
-      status: "ran",
-      disclosures,
-      findings,
-      ...outOfScope.length ? { outOfScope } : {}
-    };
-  }
-};
-
 // src/engine/finding.ts
 var TIER_ORDER = { risk: 0, gap: 1, polish: 2 };
 var EFFORT_ORDER = { S: 0, M: 1, L: 2 };