etymd 0.14.0 → 0.15.0

package/dist/index.js

@@ -30,8 +30,8 @@ var init_package = __esm({
   "package.json"() {
     package_default = {
       name: "etymd",
-      version: "0.14.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.",
+      version: "0.15.0",
+      description: "Keep your agent instructions true \u2014 verify AGENTS.md, CLAUDE.md, rules, skills, and the task you hand an agent against the actual repo, with drift caught over time and a regression ledger.",
       keywords: [
         "cli",
         "ai",
@@ -2324,6 +2324,8 @@ var gateIntegrityLens = {
 init_version();
 init_config();
 init_facts();
+
+// src/lenses/instruction-truth/checks.ts
 init_util();
 
 // src/lenses/state-freshness.ts
@@ -2871,6 +2873,204 @@ function extractDocRefs(text) {
   return { refs, tildeSkipped };
 }
 
+// src/lenses/instruction-truth/checks.ts
+async function buildTruthEnv(root, facts) {
+  const knownScripts = new Set(Object.keys(facts.commands.raw));
+  for (const pkg of facts.packages) {
+    const pkgJson = await readJson(
+      path2.join(root, pkg.dir, "package.json")
+    );
+    for (const key of Object.keys(pkgJson?.scripts ?? {})) knownScripts.add(key);
+  }
+  const bases = [root, ...facts.packages.map((p) => path2.join(root, p.dir))];
+  const pathResolves = async (claim) => {
+    for (const base of bases) {
+      if (await pathExists(path2.join(base, claim))) return true;
+      if (await pathExists(path2.join(base, "src", claim))) return true;
+      if (await pathExists(path2.join(base, "scripts", claim))) return true;
+    }
+    return false;
+  };
+  const binResolves = async (name) => {
+    for (const base of bases) {
+      if (await pathExists(path2.join(base, "node_modules", ".bin", name))) return true;
+    }
+    return false;
+  };
+  const nodeModulesInstalled = await pathExists(path2.join(root, "node_modules"));
+  const manifestExists = await pathExists(path2.join(root, "package.json")) || facts.packages.length > 0;
+  return {
+    root,
+    facts,
+    knownScripts,
+    nodeModulesInstalled,
+    manifestExists,
+    bases,
+    pathResolves,
+    binResolves
+  };
+}
+function emptyCounters() {
+  return {
+    filteredSkipped: 0,
+    tildeSkipped: 0,
+    binaryResolved: 0,
+    unverifiableCommands: 0,
+    gitignoredSkipped: 0,
+    prospectiveSkipped: 0,
+    placeholderSkipped: 0,
+    qualifiedRefsSkipped: 0,
+    unresolvableRefs: 0
+  };
+}
+async function checkTextClaims(env, file, opts, counters) {
+  const findings = [];
+  const disclosures = [];
+  const examined = [];
+  const subject = opts.subject ?? file.path;
+  const { scripts: claimed, filteredSkipped } = extractCommandClaims(file.text);
+  counters.filteredSkipped += filteredSkipped;
+  for (const [script, raw] of claimed) {
+    if (env.knownScripts.has(script)) {
+      examined.push({ kind: "script", value: script, exists: true });
+      continue;
+    }
+    if (await env.binResolves(script)) {
+      counters.binaryResolved += 1;
+      examined.push({ kind: "script", value: script, exists: true });
+      continue;
+    }
+    if (!env.nodeModulesInstalled && env.manifestExists) {
+      counters.unverifiableCommands += 1;
+      examined.push({ kind: "script", value: script, exists: null });
+      continue;
+    }
+    examined.push({ kind: "script", value: script, exists: false });
+    findings.push({
+      lens: opts.lensId,
+      id: `${opts.lensId}/stale-command:${file.path}:${script}`,
+      tier: "risk",
+      claim: `${subject} tells agents to run \`${script}\` \u2014 no such script exists`,
+      evidence: [`${file.path}: \`${raw}\``, "package.json scripts (root + workspaces)"],
+      why: opts.whyCommand ?? "An agent following this instruction runs a command that fails \u2014 or silently skips the check it was meant to run.",
+      action: opts.actionCommand ?? "Update the instruction to the current script name (or restore the script).",
+      effort: "S",
+      confidence: "high"
+    });
+  }
+  const { paths, prospective, placeholder } = extractPathClaims(file.text);
+  counters.prospectiveSkipped += prospective.length;
+  counters.placeholderSkipped += placeholder.length;
+  const missing = [];
+  for (const claim of paths) {
+    if (await env.pathResolves(claim)) examined.push({ kind: "path", value: claim, exists: true });
+    else missing.push(claim);
+  }
+  const ignoredOut = missing.length ? await git(env.root, ["check-ignore", ...missing]) : null;
+  const gitignored = new Set((ignoredOut ?? "").split("\n").filter(Boolean));
+  let pathFindings = 0;
+  for (const claim of missing) {
+    if (gitignored.has(claim)) {
+      counters.gitignoredSkipped += 1;
+      examined.push({ kind: "path", value: claim, exists: null });
+      continue;
+    }
+    examined.push({ kind: "path", value: claim, exists: false });
+    if (pathFindings >= opts.maxPathFindings) {
+      if (pathFindings === opts.maxPathFindings) {
+        disclosures.push(
+          `${file.path}: more than ${opts.maxPathFindings} missing-path claims \u2014 truncated.`
+        );
+        pathFindings += 1;
+      }
+      continue;
+    }
+    pathFindings += 1;
+    findings.push({
+      lens: opts.lensId,
+      id: `${opts.lensId}/stale-path:${file.path}:${claim}`,
+      tier: opts.missingPathTier,
+      claim: `${subject} references \`${claim}\` \u2014 it does not exist in the repo`,
+      evidence: [file.path, `missing: ${claim}`],
+      why: opts.whyPath ?? "Agents navigate by these references; a dead path wastes a lookup and erodes trust in the rest of the file.",
+      action: opts.actionPath ?? "Fix or remove the reference.",
+      effort: "S",
+      confidence: "medium"
+    });
+  }
+  return { findings, disclosures, examined };
+}
+async function checkDocRefs(env, file, lensId, counters, subject = file.path) {
+  const findings = [];
+  const examined = [];
+  const { refs, tildeSkipped } = extractDocRefs(file.text);
+  counters.tildeSkipped += tildeSkipped;
+  for (const ref of refs) {
+    const exists = await pathExists(path2.join(env.root, ref));
+    examined.push({ kind: "doc", value: ref, exists });
+    if (exists) continue;
+    findings.push({
+      lens: lensId,
+      id: `${lensId}/dangling-ref:${file.path}:${ref}`,
+      tier: "gap",
+      claim: `${subject} references ${ref} \u2014 no such file exists`,
+      evidence: [file.path, `missing: ${ref}`],
+      why: "The pointer chain agents follow breaks at a file they can never read.",
+      action: `Create ${ref} or remove the reference.`,
+      effort: "S",
+      confidence: "high"
+    });
+  }
+  return { findings, examined };
+}
+async function loadDecisionLedger(root, facts) {
+  let ids = null;
+  const sources = [];
+  for (const artifact of facts.artifacts) {
+    if (artifact.kind !== "decisions" || !artifact.exists) continue;
+    const text = await readText(path2.join(root, artifact.path));
+    if (text === null) continue;
+    const entries = parseDecisionEntries(text);
+    if (!entries.length) continue;
+    ids ??= /* @__PURE__ */ new Set();
+    for (const entry of entries) ids.add(entry.num);
+    sources.push(artifact.path);
+  }
+  return { ids, sources };
+}
+function checkDecisionRefs(file, ledger, opts, counters) {
+  const findings = [];
+  const examined = [];
+  const subject = opts.subject ?? file.path;
+  const { refs, qualifiedSkipped } = extractDecisionRefs(file.text);
+  counters.qualifiedRefsSkipped += qualifiedSkipped;
+  if (!refs.size) return { findings, examined };
+  if (!ledger.ids) {
+    counters.unresolvableRefs += refs.size;
+    for (const asWritten of refs.values()) {
+      examined.push({ kind: "decision", value: asWritten, exists: null });
+    }
+    return { findings, examined };
+  }
+  for (const [num, asWritten] of refs) {
+    const exists = ledger.ids.has(num);
+    examined.push({ kind: "decision", value: asWritten, exists });
+    if (exists) continue;
+    findings.push({
+      lens: opts.lensId,
+      id: `${opts.lensId}/dead-decision-ref:${file.path}:${asWritten}`,
+      tier: "gap",
+      claim: `${subject} cites ${asWritten} \u2014 no such entry exists in ${ledger.sources.join(", ")}`,
+      evidence: [file.path, `${ledger.sources.join(", ")}: no ${asWritten} entry`],
+      why: opts.why ?? "A state doc is read as ground truth on return; a citation the decision record cannot back sends readers to a ruling that was never written.",
+      action: opts.action ?? "Fix the reference \u2014 or record the missing decision.",
+      effort: "S",
+      confidence: "medium"
+    });
+  }
+  return { findings, examined };
+}
+
 // src/lenses/instruction-truth/lens.ts
 var LENS_ID4 = "instruction-truth";
 var MAX_PATH_FINDINGS_PER_FILE = 15;
@@ -2965,99 +3165,17 @@ var instructionTruthLens = {
         })
       );
     }
-    const knownScripts = new Set(Object.keys(facts.commands.raw));
-    for (const pkg of facts.packages) {
-      const pkgJson = await readJson(
-        path2.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) => path2.join(root, p.dir))];
-      for (const base of bases) {
-        if (await pathExists(path2.join(base, claim))) return true;
-        if (await pathExists(path2.join(base, "src", claim))) return true;
-        if (await pathExists(path2.join(base, "scripts", claim))) return true;
-      }
-      return false;
+    const env = await buildTruthEnv(root, facts);
+    const counters = emptyCounters();
+    const claimOpts = {
+      lensId: LENS_ID4,
+      missingPathTier: "gap",
+      maxPathFindings: MAX_PATH_FINDINGS_PER_FILE
     };
-    const binResolves = async (name) => {
-      const bases = [root, ...facts.packages.map((p) => path2.join(root, p.dir))];
-      for (const base of bases) {
-        if (await pathExists(path2.join(base, "node_modules", ".bin", name))) return true;
-      }
-      return false;
-    };
-    const nodeModulesInstalled = await pathExists(path2.join(root, "node_modules"));
-    const manifestExists = await pathExists(path2.join(root, "package.json")) || facts.packages.length > 0;
-    let totalFilteredSkipped = 0;
-    let totalTildeSkipped = 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(
-            `${file.path}: more than ${MAX_PATH_FINDINGS_PER_FILE} missing-path claims \u2014 truncated.`
-          );
-          break;
-        }
-        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"
-          })
-        );
-      }
+      const result = await checkTextClaims(env, file, claimOpts, counters);
+      findings.push(...result.findings);
+      disclosures.push(...result.disclosures);
     };
     for (const file of files) {
       await auditClaims(file);
@@ -3081,66 +3199,15 @@ var instructionTruthLens = {
           break;
         }
       }
-      const { refs: docRefs, tildeSkipped } = extractDocRefs(file.text);
-      totalTildeSkipped += tildeSkipped;
-      for (const ref of docRefs) {
-        if (await pathExists(path2.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"
-          })
-        );
-      }
+      findings.push(...(await checkDocRefs(env, file, LENS_ID4, counters)).findings);
     }
     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(path2.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);
-      }
-    }
+    const ledger = stateDocs.length ? await loadDecisionLedger(root, facts) : { ids: null, sources: [] };
+    const ledgerSources = ledger.sources;
     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"
-          })
-        );
-      }
+      findings.push(...checkDecisionRefs(doc, ledger, { lensId: LENS_ID4 }, counters).findings);
     }
     if (ctx.baseline) {
       findings.push(
@@ -3163,34 +3230,34 @@ var instructionTruthLens = {
         "No committed baseline (.etymd/baseline.json) \u2014 drift over time is not measurable; run `etymd init` to approve one."
       );
     }
-    if (binaryResolved) {
+    if (counters.binaryResolved) {
       disclosures.push(
-        `${binaryResolved} command claim(s) are installed binaries (node_modules/.bin), not package scripts \u2014 treated as true.`
+        `${counters.binaryResolved} command claim(s) are installed binaries (node_modules/.bin), not package scripts \u2014 treated as true.`
       );
     }
-    if (unverifiableCommands) {
+    if (counters.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.`
+        `node_modules is not installed \u2014 ${counters.unverifiableCommands} command claim(s) matching no package script could not be checked against installed binaries; skipped, not flagged.`
       );
     }
-    if (gitignoredSkipped) {
+    if (counters.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.`
+        `${counters.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) {
+    if (counters.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.`
+        `${counters.prospectiveSkipped} path claim(s) sit in create-this prose (the file instructs generating them) \u2014 forward-looking, not stale; skipped, not flagged.`
       );
     }
-    if (placeholderSkipped) {
+    if (counters.placeholderSkipped) {
       disclosures.push(
-        `${placeholderSkipped} path claim(s) are naming stand-ins (e.g. \`my-custom-skill\`) rather than real references; skipped, not flagged.`
+        `${counters.placeholderSkipped} path claim(s) are naming stand-ins (e.g. \`my-custom-skill\`) rather than real references; skipped, not flagged.`
       );
     }
-    if (totalTildeSkipped) {
+    if (counters.tildeSkipped) {
       disclosures.push(
-        `${totalTildeSkipped} well-known doc mention(s) sit inside \`~/\` home paths (e.g. \`~/.claude/CLAUDE.md\`) \u2014 machine-global files, not this repo's; skipped, not flagged.`
+        `${counters.tildeSkipped} well-known doc mention(s) sit inside \`~/\` home paths (e.g. \`~/.claude/CLAUDE.md\`) \u2014 machine-global files, not this repo's; skipped, not flagged.`
       );
     }
     if (stateDocs.length) {
@@ -3198,14 +3265,14 @@ var instructionTruthLens = {
         `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) {
+    if (counters.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.`
+        `${counters.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) {
+    if (counters.unresolvableRefs) {
       disclosures.push(
-        `${unresolvableRefs} decision reference(s) could not be resolved \u2014 no decisions file with \`## D-NNN\` entries; skipped, not flagged.`
+        `${counters.unresolvableRefs} decision reference(s) could not be resolved \u2014 no decisions file with \`## D-NNN\` entries; skipped, not flagged.`
       );
     }
     if (excluded.length) {
@@ -3220,7 +3287,7 @@ var instructionTruthLens = {
       );
     }
     disclosures.push(
-      `Checked ${files.length} instruction file(s); commands resolved against root + ${facts.packages.length} workspace manifest(s) plus installed binaries; paths matched against root and package roots. Heuristics: workspace-filtered commands skipped (${totalFilteredSkipped}); tokens without a recognized extension treated as prose (a dir claim needs a trailing slash); gitignored claims unverifiable; create-this and stand-in path claims skipped; absolute/globbed/placeholder tokens skipped; doc mentions inside \`~/\` home paths skipped; framework-pattern staleness not checked.`
+      `Checked ${files.length} instruction file(s); commands resolved against root + ${facts.packages.length} workspace manifest(s) plus installed binaries; paths matched against root and package roots. Heuristics: workspace-filtered commands skipped (${counters.filteredSkipped}); tokens without a recognized extension treated as prose (a dir claim needs a trailing slash); gitignored claims unverifiable; create-this and stand-in path claims skipped; absolute/globbed/placeholder tokens skipped; doc mentions inside \`~/\` home paths skipped; framework-pattern staleness not checked.`
     );
     return {
       lens: LENS_ID4,
@@ -4258,8 +4325,273 @@ async function sweepFleet(manifest, opts = {}) {
   };
 }
 
+// src/engine/premise.ts
+init_facts();
+init_scan();
+init_util();
+var PREMISE_LENS = "premise";
+var PREMISE_BRIEF_FILE = path2.join(ETYMD_DIR, "premise-brief.md");
+var TASK_LABEL = "task";
+var MAX_PATH_FINDINGS = 15;
+var CODE_SPAN_RE = /(```[\s\S]*?```|`[^`\n]+`)/g;
+var RUN_RE = /\b(?:pnpm|yarn|npm|bun)\s+run\s+(?!-)([A-Za-z0-9:._-]+)|\bnpm\s+(?:test|start)\b/g;
+var BARE_PM_RE = /\b(?:pnpm|yarn|bun)\s+(?!run\b)(?!-)[A-Za-z0-9:._-]+/g;
+var STOP_WORDS = new Set(
+  "a an the this that these those it its them all any both each every some your our my their and or but to in on at of for with from by as is are was were be will would can could should may might must do does did not no so if then than when where which who what how also again now first once twice after before via into over only just too very".split(" ")
+);
+var WRAP_RE = /^([([{"']*)(.*?)([.,;:!?)\]}"']*)$/;
+var TRAIL_RE = /[.,;:!?)\]}"']*$/;
+var HOSTNAME_RE = /^[a-z0-9-]+(?:\.[a-z0-9-]+)*\.([a-z]{2,})$/i;
+function promoteBareTokens(text, ctx) {
+  const skips = {
+    bareInvocations: 0,
+    proseScripts: 0,
+    hostnameLike: 0,
+    unrootedDirs: 0
+  };
+  const promoted = text.split(CODE_SPAN_RE).map((segment, i) => i % 2 === 1 ? segment : promoteProse(segment, ctx, skips)).join("");
+  return { text: promoted, skips };
+}
+function promoteProse(segment, ctx, skips) {
+  skips.bareInvocations += segment.match(BARE_PM_RE)?.length ?? 0;
+  const withCommands = segment.replace(RUN_RE, (m, script) => {
+    const trail = TRAIL_RE.exec(m)?.[0] ?? "";
+    const core = trail ? m.slice(0, -trail.length) : m;
+    if (script !== void 0) {
+      const name = script.replace(TRAIL_RE, "");
+      if (name.length < 2 || STOP_WORDS.has(name.toLowerCase())) {
+        skips.proseScripts += 1;
+        return m;
+      }
+    }
+    return `\`${core}\`${trail}`;
+  });
+  return withCommands.replace(/[^\s`]+/g, (token) => {
+    const m = WRAP_RE.exec(token);
+    if (!m) return token;
+    const [, lead = "", core = "", trail = ""] = m;
+    if (!core || core.includes("://") || !PATH_TOKEN_RE.test(core)) return token;
+    const first = core.slice(0, core.indexOf("/"));
+    const hostSuffix = HOSTNAME_RE.exec(first)?.[1]?.toLowerCase();
+    if (hostSuffix && !KNOWN_EXTENSIONS.has(hostSuffix)) {
+      skips.hostnameLike += 1;
+      return token;
+    }
+    if (core.endsWith("/")) {
+      if (!ctx.rootedDirs.has(first)) {
+        skips.unrootedDirs += 1;
+        return token;
+      }
+      return `${lead}\`${core}\`${trail}`;
+    }
+    const ext = core.toLowerCase().match(/\.([a-z0-9]{1,8})$/)?.[1];
+    if (!ext || !KNOWN_EXTENSIONS.has(ext)) return token;
+    return `${lead}\`${core}\`${trail}`;
+  });
+}
+async function listRootedDirs(env) {
+  const dirs = /* @__PURE__ */ new Set();
+  for (const base of env.bases) {
+    for (const sub of ["", "src", "scripts"]) {
+      const entries = await promises.readdir(path2.join(base, sub), { withFileTypes: true }).catch(() => []);
+      for (const entry of entries) if (entry.isDirectory()) dirs.add(entry.name);
+    }
+  }
+  return dirs;
+}
+async function runPremise(opts) {
+  const root = opts.root;
+  const task = opts.task.trim();
+  const facts = await scanProject(root);
+  const env = await buildTruthEnv(root, facts);
+  const counters = emptyCounters();
+  const promoted = promoteBareTokens(task, { rootedDirs: await listRootedDirs(env) });
+  const text = { path: TASK_LABEL, text: promoted.text };
+  const findings = [];
+  const disclosures = [];
+  const entities = [];
+  const claims = await checkTextClaims(
+    env,
+    text,
+    {
+      lensId: PREMISE_LENS,
+      subject: "The task",
+      missingPathTier: "risk",
+      maxPathFindings: MAX_PATH_FINDINGS,
+      whyCommand: "The task is built on a command that does not exist \u2014 an agent will run it and fail, or quietly substitute something else and report success.",
+      actionCommand: "Fix the task before handing it over: name the real script, or restore it.",
+      whyPath: "The task is ABOUT this path. Acting on it means editing, testing, or reasoning about something that is not there \u2014 the wrong problem, solved precisely.",
+      actionPath: "Find where the behaviour actually lives and rewrite the task to name it."
+    },
+    counters
+  );
+  findings.push(...claims.findings);
+  disclosures.push(...claims.disclosures);
+  entities.push(...claims.examined);
+  const docs = await checkDocRefs(env, text, PREMISE_LENS, counters, "The task");
+  findings.push(...docs.findings);
+  entities.push(...docs.examined);
+  const ledger = await loadDecisionLedger(root, facts);
+  const decisions = checkDecisionRefs(
+    text,
+    ledger,
+    {
+      lensId: PREMISE_LENS,
+      subject: "The task",
+      why: "The task presupposes a ruling that was never recorded; an agent will act on a decision nobody made.",
+      action: "Point the task at the entry that exists \u2014 or record the missing decision first."
+    },
+    counters
+  );
+  findings.push(...decisions.findings);
+  entities.push(...decisions.examined);
+  if (!entities.length) {
+    disclosures.push(
+      "The task names no path with a directory, no package script, no well-known doc, and no decision id \u2014 nothing etymd can check by reading the repo. Everything it presupposes is in the brief."
+    );
+  }
+  disclosures.push(
+    "In prose, a path needs a directory and a recognized extension (a directory claim needs a trailing slash and a first segment that exists here), and a script needs the `run` form (`npm run X`, `pnpm run X` \u2026) or the `npm test` / `npm start` shorthands; anything backticked is read exactly as an instruction file would be. A bare file name (a lone `config.ts`) is prose."
+  );
+  const { skips } = promoted;
+  if (skips.bareInvocations) {
+    disclosures.push(
+      `${skips.bareInvocations} bare \`pnpm X\` / \`yarn X\` / \`bun X\` mention(s) in prose were not read as scripts \u2014 in a sentence that shape is a phrase as often as an invocation; write \`\u2026 run X\` or backtick it to have it checked.`
+    );
+  }
+  if (skips.proseScripts) {
+    disclosures.push(
+      `${skips.proseScripts} \`\u2026 run X\` mention(s) put a function word or a one-letter stand-in where a script name would be; read as prose, skipped.`
+    );
+  }
+  if (skips.hostnameLike) {
+    disclosures.push(
+      `${skips.hostnameLike} slash token(s) start with a host name (e.g. \`github.com/\u2026\`) \u2014 a URL, not a repo path; skipped.`
+    );
+  }
+  if (skips.unrootedDirs) {
+    disclosures.push(
+      `${skips.unrootedDirs} slash-joined phrase(s) ending in \`/\` start with no directory that exists here (e.g. \`input/output/\`) \u2014 read as prose; skipped, not flagged. Backtick one to have it checked.`
+    );
+  }
+  if (counters.unverifiableCommands) {
+    disclosures.push(
+      `node_modules is not installed \u2014 ${counters.unverifiableCommands} command(s) matching no package script could not be checked against installed binaries; skipped, not flagged.`
+    );
+  }
+  if (counters.binaryResolved) {
+    disclosures.push(
+      `${counters.binaryResolved} command(s) resolve to installed binaries (node_modules/.bin), not package scripts \u2014 treated as true.`
+    );
+  }
+  if (counters.gitignoredSkipped) {
+    disclosures.push(
+      `${counters.gitignoredSkipped} missing path(s) are gitignored (machine-local) \u2014 existence is not verifiable from the repo; skipped, not flagged.`
+    );
+  }
+  if (counters.prospectiveSkipped) {
+    disclosures.push(
+      `${counters.prospectiveSkipped} path(s) sit in create-this prose (the task says to create them) \u2014 forward-looking, not missing; skipped.`
+    );
+  }
+  if (counters.placeholderSkipped) {
+    disclosures.push(
+      `${counters.placeholderSkipped} path(s) are naming stand-ins (e.g. \`my-feature\`) rather than real references; skipped.`
+    );
+  }
+  if (counters.filteredSkipped) {
+    disclosures.push(
+      `${counters.filteredSkipped} workspace-filtered command(s) (\`--filter\`, \`-C\` \u2026) were not resolved; skipped.`
+    );
+  }
+  if (counters.tildeSkipped) {
+    disclosures.push(
+      `${counters.tildeSkipped} well-known doc mention(s) sit inside \`~/\` home paths (e.g. \`~/.claude/CLAUDE.md\`) \u2014 machine-global files, not this repo's; skipped, not flagged.`
+    );
+  }
+  if (counters.qualifiedRefsSkipped) {
+    disclosures.push(
+      `${counters.qualifiedRefsSkipped} decision reference(s) name another record \u2014 not this repo's; skipped.`
+    );
+  }
+  if (counters.unresolvableRefs) {
+    disclosures.push(
+      `${counters.unresolvableRefs} decision reference(s) could not be resolved \u2014 no decisions file with \`## D-NNN\` entries; skipped, not flagged.`
+    );
+  }
+  disclosures.push(
+    "What the task PRESUPPOSES \u2014 that the named things are the ones meant, that the mechanism it assumes actually runs, that the state it assumes holds \u2014 cannot be checked by reading files. The brief hands those to the agent."
+  );
+  disclosures.push("Task findings are not remembered between runs \u2014 no ledger is written.");
+  const ranked = rankFindings(findings);
+  const brief = renderBrief(task, ranked, entities);
+  let briefPath = null;
+  if (opts.writeBrief !== false && await pathExists(path2.join(root, ETYMD_DIR))) {
+    await promises.writeFile(path2.join(root, PREMISE_BRIEF_FILE), brief, "utf8");
+    briefPath = PREMISE_BRIEF_FILE;
+  }
+  return {
+    schema: "premise/1",
+    task,
+    source: opts.source ?? "argument",
+    name: facts.name,
+    findings: ranked,
+    disclosures,
+    entities,
+    brief,
+    briefPath
+  };
+}
+function mark(exists) {
+  return exists === null ? "?" : exists ? "\u2713" : "\u2717";
+}
+function kindLabel(kind) {
+  return kind === "script" ? "script " : kind === "decision" ? "decision " : "";
+}
+function renderBrief(task, findings, entities) {
+  const oneLine = task.replace(/\s+/g, " ").trim();
+  const title = oneLine.length > 100 ? `${oneLine.slice(0, 97)}\u2026` : oneLine;
+  const checked = entities.length ? entities.map(
+    (e) => `- ${mark(e.exists)} ${kindLabel(e.kind)}\`${e.value}\`${e.exists === null ? " \u2014 could not be checked" : e.exists ? " \u2014 exists" : " \u2014 missing (see the finding)"}`
+  ).join("\n") : "- (nothing the task names could be checked by reading the repo)";
+  const failed = findings.filter((f) => f.tier === "risk");
+  const failedLine = failed.length ? `
+**${failed.length} premise(s) already failed** \u2014 the task names things that do not exist. Resolve those before anything below.
+` : "";
+  return `# Premise brief \u2014 ${title}
+
+The task, verbatim:
+
+> ${task.replace(/\n/g, "\n> ")}
+
+etymd checked what the task names against the repo. What it could NOT check is listed under
+"only you can verify"; check those before acting, and if one fails, say so first \u2014 everything
+else is downstream of it.
+${failedLine}
+## What the task names, and whether it exists
+
+${checked}
+
+## Premises only you can verify
+
+1. **The named things are the ones MEANT.** A file that exists can still be the wrong file, and a
+   script that exists can still not be the one the task has in mind. Confirm each is where the
+   behaviour actually lives before touching it.
+2. **The mechanism the task assumes is working.** A task shaped like "make X faster / less flaky /
+   fresh after Y" assumes X and Y already do what it says. Run them once. If the assumed
+   mechanism does not run, the task is downstream of a defect it does not mention.
+3. **The state the task assumes holds.** Read it; do not trust the task's description of it.
+
+## If a premise fails
+
+Report it first, in one line: what the task presupposes, and what you found instead. Do not
+answer the original task as if the premise held \u2014 a wrong problem solved precisely is still the
+wrong problem.
+`;
+}
+
 // src/index.ts
 init_version();
 init_version2();
 
-export { CONFIG_FILE, DECISIONS_FORMAT_MARKER, DEFAULT_CONFIG, EXTRACTION_THRESHOLD, FLEET_JSON_SCHEMA, FLEET_LENS, LENSES, NAME, PACK_VERSION, TOTAL_BUDGET_WORDS, VERSION, applyFiles, baselineCarriesMachinePath, baselinePath, buildGateInventory, cacheFactsPath, checkManifest, collectWallFindings, configPath, contextEconomyLens, corpPersistenceRoot, deriveProfile, expandTilde, extractCommandClaims, extractPathClaims, gateIntegrityLens, instructionTruthLens, isAlwaysAppliedCursorRule, listInstructionFiles, loadFleetManifest, measureContext, planWorkflow, rankFindings, readBaseline, readCachedFacts, readConfig, readLedger, reconcileLedger, runAudit, scanProject, stateFreshnessLens, sweepFleet, withoutMachinePath, writeBaseline, writeCachedFacts, writeLedger };
+export { CONFIG_FILE, DECISIONS_FORMAT_MARKER, DEFAULT_CONFIG, EXTRACTION_THRESHOLD, FLEET_JSON_SCHEMA, FLEET_LENS, LENSES, NAME, PACK_VERSION, PREMISE_BRIEF_FILE, PREMISE_LENS, TOTAL_BUDGET_WORDS, VERSION, applyFiles, baselineCarriesMachinePath, baselinePath, buildGateInventory, buildTruthEnv, cacheFactsPath, checkDecisionRefs, checkDocRefs, checkManifest, checkTextClaims, collectWallFindings, configPath, contextEconomyLens, corpPersistenceRoot, deriveProfile, emptyCounters, expandTilde, extractCommandClaims, extractPathClaims, gateIntegrityLens, instructionTruthLens, isAlwaysAppliedCursorRule, listInstructionFiles, loadDecisionLedger, loadFleetManifest, measureContext, planWorkflow, promoteBareTokens, rankFindings, readBaseline, readCachedFacts, readConfig, readLedger, reconcileLedger, renderBrief, runAudit, runPremise, scanProject, stateFreshnessLens, sweepFleet, withoutMachinePath, writeBaseline, writeCachedFacts, writeLedger };