etymd 0.13.0 → 0.15.0

package/dist/index.js

@@ -20,7 +20,7 @@ var __export = (target, all) => {
 var PACK_VERSION;
 var init_version = __esm({
   "src/pack/version.ts"() {
-    PACK_VERSION = "8";
+    PACK_VERSION = "12";
   }
 });
 
@@ -30,8 +30,8 @@ var init_package = __esm({
   "package.json"() {
     package_default = {
       name: "etymd",
-      version: "0.13.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",
@@ -1136,15 +1136,36 @@ ${[
     "md"
   );
 }
+function isSelfBuildRepo(facts) {
+  return facts.publishRoute !== "none" && facts.name === SELF_PACKAGE_NAME;
+}
+function contentGateResolution(selfBuild) {
+  if (!selfBuild) return `GATE="\${CONTENT_GATE:-$(command -v etymd || true)}"`;
+  return `GATE="\${CONTENT_GATE:-$(if [ -x ./dist/cli.js ]; then echo ./dist/cli.js; else command -v etymd || true; fi)}"`;
+}
+function contentScreenCall(opts) {
+  const { args, envVar, blocking, indent } = opts;
+  const hint = `etymd: this checker does not understand 'screen' (needs etymd 0.11+) \u2014 upgrade it, or set ${envVar} to a checker that does.`;
+  return [
+    `${indent}if ! "$GATE" screen ${args}; then`,
+    `${indent}  "$GATE" screen --help >/dev/null 2>&1 ||`,
+    `${indent}    echo "${hint}" >&2`,
+    ...blocking ? [`${indent}  exit 1`] : [],
+    `${indent}fi`
+  ].join("\n");
+}
 function localHookCall(hook) {
   return `# Repo-owned checks. This file is generated and will be overwritten; \`.githooks/${hook}.local\`
 # is yours \u2014 etymd never reads, writes, or regenerates it. Put project-specific guards there.
+# A guard running tests that build fixture repositories should scrub git's exported GIT_* names
+# first \u2014 a child git inherits them and ignores its cwd, so the suite would hit the real repo:
+#   env $(env | grep -o '^GIT_[A-Za-z0-9_]*' | sed 's/^/-u /') <your command>
 LOCAL="$(dirname "$0")/${hook}.local"
 if [ -x "$LOCAL" ]; then
   "$LOCAL" "$@" || exit 1
 fi`;
 }
-function generatePreCommitHook() {
+function generatePreCommitHook(selfBuild = false) {
   return stampGenerated(`#!/usr/bin/env sh
 # etymd: process gate. Cheap, locally-knowable checks belong here (fast, blocks the commit).
 
@@ -1156,9 +1177,9 @@ ${localHookCall("pre-commit")}
 # commit anywhere, active only where you opted in.
 #
 # Bypass, with a reason: git commit --no-verify
-${CONTENT_GATE_RESOLUTION}
+${contentGateResolution(selfBuild)}
 if [ -x "$GATE" ]; then
-  "$GATE" screen --staged || exit 1
+${contentScreenCall({ args: "--staged", envVar: "CONTENT_GATE", blocking: true, indent: "  " })}
 fi
 
 exit 0
@@ -1199,7 +1220,7 @@ function generateCommitMsgHook(gates) {
 # Bypass, with a reason: git commit --no-verify
 GATE="\${COMMIT_MSG_GATE:-$(command -v etymd || true)}"
 if [ -x "$GATE" ]; then
-  "$GATE" screen --message "$1" || exit 1
+${contentScreenCall({ args: '--message "$1"', envVar: "COMMIT_MSG_GATE", blocking: true, indent: "  " })}
 fi
 ${format}
 ${localHookCall("commit-msg")}
@@ -1210,11 +1231,24 @@ exit 0
 function shellcheckStep() {
   return `
 # Shell correctness. Scripts are discovered by shebang over TRACKED files at push time, so a
-# script added later is covered without regenerating this hook.
+# script added later is covered without regenerating this hook. zsh is NOT in the checked set:
+# the checker cannot parse it (SC1071 is a parser-level error no inline directive can silence),
+# so checking it would fail every push on the parser, not on the script. Excluded \u2014 and said so
+# at run time below, because a coverage hole that is silent is indistinguishable from coverage.
+#
+# "the checker", not its name, on purpose: a comment whose first word is that name is read as
+# a DIRECTIVE, and an unparseable directive is itself an error (SC1072/SC1073). A hook that
+# explains why it skips a shell dialect must not break the checker while doing it.
 if command -v shellcheck >/dev/null 2>&1; then
   scripts=$(git ls-files -z \\
-    | xargs -0 -I{} sh -c 'head -1 "{}" 2>/dev/null | grep -qE "^#!.*[/ ](ba|da|z)?sh( |$)" && echo "{}"' \\
+    | xargs -0 -I{} sh -c 'head -1 "{}" 2>/dev/null | grep -qE "^#!.*[/ ](ba|da)?sh( |$)" && echo "{}"' \\
     | sort)
+  zsh_scripts=$(git ls-files -z \\
+    | xargs -0 -I{} sh -c 'head -1 "{}" 2>/dev/null | grep -qE "^#!.*[/ ]zsh( |$)" && echo "{}"' \\
+    | sort)
+  if [ -n "$zsh_scripts" ]; then
+    echo "\u203A shellcheck: $(printf '%s\\n' "$zsh_scripts" | wc -l | tr -d ' ') zsh script(s) excluded \u2014 shellcheck cannot parse zsh (SC1071); not checked, not failed"
+  fi
   if [ -n "$scripts" ]; then
     echo "\u203A shellcheck ($(printf '%s\\n' "$scripts" | wc -l | tr -d ' ') scripts, blocking at severity=warning)"
     printf '%s\\n' "$scripts" | xargs shellcheck -S warning || {
@@ -1234,7 +1268,7 @@ else
   echo "\u203A shellcheck skipped (not on PATH) \u2014 install it to gate this repo's shell scripts"
 fi`;
 }
-function generatePrePushHook(facts, gates) {
+function generatePrePushHook(facts, gates, selfBuild = false) {
   const run = runPrefix(facts.packageManager);
   const c = facts.commands;
   const candidates = gates?.commands?.length ? gates.commands : [c.formatCheck, c.typecheck, c.lint];
@@ -1243,8 +1277,9 @@ function generatePrePushHook(facts, gates) {
     (key) => Boolean(key) && (allowed.has(key) || isSafeGateCommand(c.raw[key]))
   ).map((key) => `${run} ${key}`);
   const shellStep = facts.shell?.scripts ? shellcheckStep() : "";
+  const runner = steps.length ? SCRUBBED_RUNNER : "";
   const body = steps.length ? steps.map((s) => `echo "\u203A ${s}"
-${s} || exit 1`).join("\n") : shellStep ? (
+run_gate ${s} || exit 1`).join("\n") : shellStep ? (
     // A repo whose executable surface is shell HAS a correctness command — it just is not in
     // package.json. Claiming "none detected" beside a step that is about to run would be the
     // tool contradicting itself.
@@ -1261,22 +1296,22 @@ fi`;
   return stampGenerated(`#!/usr/bin/env sh
 # etymd: correctness gate. Mirrors CI cheapest-first; blocks the push on any failure.
 
-${localHookCall("pre-push")}
+${localHookCall("pre-push")}${runner}
 ${body}${shellStep}
 ${auditStep}
 
 # Content screen, second pass \u2014 the WHOLE TREE rather than one diff. Catches anything committed
 # with --no-verify and anything a rebase or merge brought in from elsewhere. Advisory here (it
 # never blocks the push): the blocking decision belongs at commit time, where the fix is cheap.
-${CONTENT_GATE_RESOLUTION}
+${contentGateResolution(selfBuild)}
 if [ -x "$GATE" ]; then
-  "$GATE" screen --tree --advisory || true
+${contentScreenCall({ args: "--tree --advisory", envVar: "CONTENT_GATE", blocking: false, indent: "  " })}
 fi
 
 exit 0
 `);
 }
-function generateArtifactCheckScript() {
+function generateArtifactCheckScript(selfBuild = false) {
   return stampGenerated(`#!/usr/bin/env sh
 # etymd: content screen \u2014 the published ARTIFACT, not the repository.
 #
@@ -1287,7 +1322,7 @@ function generateArtifactCheckScript() {
 # .etymd-screen-allow entries (with provenance) if you must exempt a string.
 set -eu
 
-${CONTENT_GATE_RESOLUTION}
+${contentGateResolution(selfBuild)}
 [ -x "$GATE" ] || { echo "\u203A artifact-check: no checker installed \u2014 skipping."; exit 0; }
 
 WORK=$(mktemp -d)
@@ -1300,16 +1335,16 @@ if [ -f package.json ]; then
   tar -xzf "$WORK"/*.tgz -C "$WORK" 2>/dev/null || true
 fi
 
-"$GATE" screen --dir "$WORK" || exit 1
+${contentScreenCall({ args: '--dir "$WORK"', envVar: "CONTENT_GATE", blocking: true, indent: "" })}
 exit 0
 `);
 }
-var GENERATION_MARKER_RE, CONTENT_GATE_RESOLUTION, COMMIT_TYPES, SUBJECT_ADVISORY_LENGTH;
+var GENERATION_MARKER_RE, SELF_PACKAGE_NAME, COMMIT_TYPES, SUBJECT_ADVISORY_LENGTH, SCRUBBED_RUNNER;
 var init_templates = __esm({
   "src/pack/templates.ts"() {
     init_version();
     GENERATION_MARKER_RE = /^(?:# |<!-- )etymd:generated pack-v\S+ ([0-9a-f]{16})(?: -->)?$/;
-    CONTENT_GATE_RESOLUTION = `GATE="\${CONTENT_GATE:-$(if [ -x ./dist/cli.js ]; then echo ./dist/cli.js; else command -v etymd || true; fi)}"`;
+    SELF_PACKAGE_NAME = "etymd";
     COMMIT_TYPES = [
       "feat",
       "fix",
@@ -1324,6 +1359,14 @@ var init_templates = __esm({
       "revert"
     ];
     SUBJECT_ADVISORY_LENGTH = 72;
+    SCRUBBED_RUNNER = `
+# Gate steps run scrubbed of git's exported GIT_* names: a child git that inherits them ignores
+# its cwd, so a hook-run suite building fixture repositories would operate on the real repo.
+run_gate() (
+  # shellcheck disable=SC2046  # word-splitting is the point: one -u per exported GIT_* name
+  env $(env | grep -o '^GIT_[A-Za-z0-9_]*' | sed 's/^/-u /') "$@"
+)
+`;
   }
 });
 
@@ -1386,7 +1429,13 @@ async function planWorkflow(root, facts, opts) {
   }
   if (opts.gates) {
     const existingPrePush = await readText(path2.join(root, ".githooks", "pre-push"));
-    await add(".githooks/pre-commit", generatePreCommitHook(), "Process gate (pre-commit)", true);
+    const selfBuild = isSelfBuildRepo(facts);
+    await add(
+      ".githooks/pre-commit",
+      generatePreCommitHook(selfBuild),
+      "Process gate (pre-commit)",
+      true
+    );
     await add(
       ".githooks/commit-msg",
       generateCommitMsgHook(opts.gateConfig),
@@ -1402,14 +1451,14 @@ async function planWorkflow(root, facts, opts) {
     };
     await add(
       ".githooks/pre-push",
-      generatePrePushHook(facts, gateConfig),
+      generatePrePushHook(facts, gateConfig, selfBuild),
       "Correctness gate (pre-push)",
       true
     );
     if (opts.gateConfig?.publishGate ?? opts.publishGate ?? facts.publishable) {
       await add(
         "scripts/artifact-check.sh",
-        generateArtifactCheckScript(),
+        generateArtifactCheckScript(selfBuild),
         "Content screen (published artifact)",
         true
       );
@@ -1446,14 +1495,36 @@ function isAlwaysAppliedCursorRule(text) {
   const frontmatter = fm[1] ?? "";
   return /^\s*alwaysApply\s*:\s*true\s*$/m.test(frontmatter);
 }
+async function inodeKey(abs) {
+  try {
+    const st = await promises.stat(abs);
+    return st.ino ? `${st.dev}:${st.ino}` : null;
+  } catch {
+    return null;
+  }
+}
+function contextFileLabel(file) {
+  return file.aliases?.length ? [file.path, ...file.aliases].join(" \u2192 ") : file.path;
+}
 async function measureContext(root, perFileWords = EXTRACTION_THRESHOLD) {
   const files = [];
+  const byInode = /* @__PURE__ */ new Map();
+  const record = async (rel, role, text) => {
+    const words = wordCount(text);
+    const key = await inodeKey(path2.join(root, rel));
+    const seen = key ? byInode.get(key) : void 0;
+    if (seen) {
+      seen.aliases = [...seen.aliases ?? [], rel];
+      return;
+    }
+    const file = { path: rel, role, words, approxTokens: approxTokens(words) };
+    if (key) byInode.set(key, file);
+    files.push(file);
+  };
   for (const spec of ALWAYS_LOADED) {
-    const abs = path2.join(root, spec.path);
-    const text = await readText(abs);
+    const text = await readText(path2.join(root, spec.path));
     if (text === null) continue;
-    const words = wordCount(text);
-    files.push({ path: spec.path, role: spec.role, words, approxTokens: approxTokens(words) });
+    await record(spec.path, spec.role, text);
   }
   const rulesDir = path2.join(root, ".cursor", "rules");
   if (await pathExists(rulesDir)) {
@@ -1462,13 +1533,7 @@ async function measureContext(root, perFileWords = EXTRACTION_THRESHOLD) {
         if (!entry.endsWith(".mdc") && !entry.endsWith(".md")) continue;
         const text = await readText(path2.join(rulesDir, entry));
         if (text === null || !isAlwaysAppliedCursorRule(text)) continue;
-        const words = wordCount(text);
-        files.push({
-          path: `.cursor/rules/${entry}`,
-          role: "Cursor rule (always applied)",
-          words,
-          approxTokens: approxTokens(words)
-        });
+        await record(`.cursor/rules/${entry}`, "Cursor rule (always applied)", text);
       }
     } catch {
     }
@@ -1525,13 +1590,15 @@ var contextEconomyLens = {
     const budgets = ctx.config?.config.context ?? DEFAULT_CONFIG.context;
     const budget = await measureContext(ctx.root, budgets.perFileWords);
     const findings = [];
+    const aliased = budget.files.filter((f) => f.aliases?.length);
     for (const f of budget.extractionCandidates) {
+      const label = contextFileLabel(f);
       findings.push({
         id: `${LENS_ID}/heavy-file:${f.path}`,
         lens: LENS_ID,
         tier: "gap",
-        claim: `${f.path} loads ${f.words} words (~${f.approxTokens} tokens) into every session`,
-        evidence: [`${f.path}: ${f.words} words`],
+        claim: `${label} loads ${f.words} words (~${f.approxTokens} tokens) into every session`,
+        evidence: [`${label}: ${f.words} words`],
         why: "Reference material that loads every session taxes attention and cost on tasks that never need it.",
         action: "Extract the reference bulk into an on-demand skill/doc and keep a pointer.",
         effort: "M",
@@ -1544,7 +1611,7 @@ var contextEconomyLens = {
         lens: LENS_ID,
         tier: "gap",
         claim: `The always-loaded footprint is ${budget.totalWords} words (~${budget.totalApproxTokens} tokens) \u2014 over the ${budgets.totalWords}-word budget`,
-        evidence: budget.files.slice(0, 5).map((f) => `${f.path}: ${f.words}w`),
+        evidence: budget.files.slice(0, 5).map((f) => `${contextFileLabel(f)}: ${f.words}w`),
         why: "Every session pays this before the task begins; instruction-following degrades as the resident context grows.",
         action: "Run `etymd context` for the per-file breakdown and extract the heaviest block.",
         effort: "M",
@@ -1559,6 +1626,9 @@ var contextEconomyLens = {
       status: "ran",
       disclosures: [
         ...ctx.config?.problems ?? [],
+        ...aliased.map(
+          (f) => `${contextFileLabel(f)} are one file (same inode) \u2014 counted once, at ${f.words} words.`
+        ),
         `Budgets: ${budgets.perFileWords} words/file, ${budgets.totalWords} words total (${budgets.perFileWords === DEFAULT_CONFIG.context.perFileWords && budgets.totalWords === DEFAULT_CONFIG.context.totalWords ? `defaults \u2014 override under \`context\` in ${CONFIG_FILE}` : `set in ${CONFIG_FILE}`}). Scoped Cursor rules excluded.`
       ],
       findings
@@ -1966,6 +2036,73 @@ async function buildGateInventory(root, facts) {
   };
 }
 
+// src/lenses/gate-integrity/screener.ts
+init_util();
+var pExecFile2 = promisify(execFile);
+var HOOK_FILES = ["pre-commit", "pre-push", "commit-msg"];
+var SCREEN_CALL_RE = /"\$GATE"\s+screen\b/;
+var DEV_BUILD_ARM = "[ -x ./dist/cli.js ]";
+async function probeScreener(root, facts) {
+  const absent = {
+    present: false,
+    doors: [],
+    runner: null,
+    source: null,
+    answersScreen: null
+  };
+  const dir = facts.hooks.dir;
+  if (!dir) return absent;
+  const doors = [];
+  let devBuildArm = false;
+  for (const name of HOOK_FILES) {
+    const text = await readText(path2.join(root, dir, name));
+    if (!text || !SCREEN_CALL_RE.test(text)) continue;
+    doors.push(`${dir}/${name}`);
+    if (text.includes(DEV_BUILD_ARM)) devBuildArm = true;
+  }
+  if (!doors.length) return absent;
+  let runner = null;
+  let source = null;
+  const override = process.env.CONTENT_GATE;
+  if (override) {
+    runner = override;
+    source = "CONTENT_GATE";
+  } else if (devBuildArm && await pathExists(path2.join(root, "dist", "cli.js"))) {
+    runner = path2.join(root, "dist", "cli.js");
+    source = "dev-build";
+  } else {
+    runner = "etymd";
+    source = "path";
+  }
+  try {
+    await pExecFile2(runner, ["screen", "--help"], { cwd: root, timeout: 1e4 });
+    return { present: true, doors, runner, source, answersScreen: true };
+  } catch (err) {
+    const e = err;
+    if (e.code === "ENOENT") {
+      return {
+        present: true,
+        doors,
+        runner: null,
+        source,
+        answersScreen: null,
+        skipped: `no checker named \`${runner}\` is installed \u2014 the screen doors no-op here by design, and nothing was verified.`
+      };
+    }
+    if (e.killed || e.code === "ETIMEDOUT") {
+      return {
+        present: true,
+        doors,
+        runner,
+        source,
+        answersScreen: null,
+        skipped: `\`${runner} screen --help\` did not return within 10s \u2014 the runner was not verified either way.`
+      };
+    }
+    return { present: true, doors, runner, source, answersScreen: false };
+  }
+}
+
 // src/lenses/gate-integrity/lens.ts
 var LENS_ID2 = "gate-integrity";
 var CORRECTNESS_TOOLS = ["typecheck", "lint", "format-check", "test"];
@@ -2108,6 +2245,28 @@ function deriveGateFindings(inv, disclosures = []) {
 function localToolInHook(inv, tool) {
   return inv.local.preCommit.includes(tool) || inv.local.prePush.includes(tool) || inv.local.commitMsg.includes(tool);
 }
+function deriveScreenerFindings(probe, disclosures) {
+  if (!probe.present) return [];
+  if (probe.skipped) {
+    disclosures.push(`Content screen: ${probe.skipped}`);
+    return [];
+  }
+  if (probe.answersScreen !== false) return [];
+  const via = probe.source === "CONTENT_GATE" ? "resolved from the CONTENT_GATE override" : probe.source === "dev-build" ? "resolved to this repo's own ./dist/cli.js build" : "resolved from PATH";
+  return [
+    finding({
+      id: `${LENS_ID2}/content-screen-unrunnable`,
+      tier: "risk",
+      kind: "truth",
+      claim: `The content screen resolves to \`${probe.runner}\`, which does not understand \`screen\` \u2014 the gate cannot run`,
+      evidence: [...probe.doors, `${probe.runner} screen --help \u2192 failed (${via})`],
+      why: "The commit door fails closed on an error that explains nothing, and the push door \u2014 advisory by design \u2014 skips the whole-tree pass in silence, so the repo reads as screened when nothing screened it.",
+      action: "Install or upgrade etymd (`screen` needs 0.11+), or point CONTENT_GATE at a checker that provides it, then re-run `etymd gates` to refresh the hooks.",
+      effort: "S",
+      confidence: "high"
+    })
+  ];
+}
 var gateIntegrityLens = {
   id: LENS_ID2,
   version: "1",
@@ -2148,6 +2307,7 @@ var gateIntegrityLens = {
     if (inv.ci.system === "none")
       disclosures.push("No CI configuration found \u2014 CI\u2194local comparisons skipped.");
     const findings = deriveGateFindings(inv, disclosures);
+    findings.push(...deriveScreenerFindings(await probeScreener(ctx.root, ctx.facts), disclosures));
     return {
       lens: LENS_ID2,
       version: "1",
@@ -2164,6 +2324,8 @@ var gateIntegrityLens = {
 init_version();
 init_config();
 init_facts();
+
+// src/lenses/instruction-truth/checks.ts
 init_util();
 
 // src/lenses/state-freshness.ts
@@ -2692,8 +2854,221 @@ var KNOWN_DOC_REFS = [
   "DECISIONS.md",
   "GEMINI.md"
 ];
+var PATH_TOKEN_CHARS = /[A-Za-z0-9_.$~/-]/;
 function extractDocRefs(text) {
-  return KNOWN_DOC_REFS.filter((name) => text.includes(name));
+  const refs = [];
+  let tildeSkipped = 0;
+  for (const name of KNOWN_DOC_REFS) {
+    let claimed = false;
+    let at = text.indexOf(name);
+    while (at !== -1) {
+      let head = at;
+      while (head > 0 && PATH_TOKEN_CHARS.test(text[head - 1])) head -= 1;
+      if (text[head] === "~") tildeSkipped += 1;
+      else claimed = true;
+      at = text.indexOf(name, at + name.length);
+    }
+    if (claimed) refs.push(name);
+  }
+  return { refs, tildeSkipped };
+}
+
+// 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
@@ -2790,98 +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 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 env = await buildTruthEnv(root, facts);
+    const counters = emptyCounters();
+    const claimOpts = {
+      lensId: LENS_ID4,
+      missingPathTier: "gap",
+      maxPathFindings: MAX_PATH_FINDINGS_PER_FILE
     };
-    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 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);
@@ -2905,64 +3199,15 @@ var instructionTruthLens = {
           break;
         }
       }
-      for (const ref of extractDocRefs(file.text)) {
-        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(
@@ -2985,29 +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(
+        `${counters.binaryResolved} command claim(s) are installed binaries (node_modules/.bin), not package scripts \u2014 treated as true.`
+      );
+    }
+    if (counters.unverifiableCommands) {
       disclosures.push(
-        `${binaryResolved} command claim(s) are installed binaries (node_modules/.bin), not package scripts \u2014 treated as true.`
+        `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 (unverifiableCommands) {
+    if (counters.gitignoredSkipped) {
       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.`
+        `${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 (gitignoredSkipped) {
+    if (counters.prospectiveSkipped) {
       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.prospectiveSkipped} path claim(s) sit in create-this prose (the file instructs generating them) \u2014 forward-looking, not stale; skipped, not flagged.`
       );
     }
-    if (prospectiveSkipped) {
+    if (counters.placeholderSkipped) {
       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.placeholderSkipped} path claim(s) are naming stand-ins (e.g. \`my-custom-skill\`) rather than real references; skipped, not flagged.`
       );
     }
-    if (placeholderSkipped) {
+    if (counters.tildeSkipped) {
       disclosures.push(
-        `${placeholderSkipped} path claim(s) are naming stand-ins (e.g. \`my-custom-skill\`) rather than real references; 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) {
@@ -3015,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) {
@@ -3037,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; 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,
@@ -3470,7 +3720,7 @@ async function loadFleetManifest(manifestPath) {
 init_config();
 init_facts();
 init_util();
-var pExecFile2 = promisify(execFile);
+var pExecFile3 = promisify(execFile);
 var FLEET_LENS = "fleet-manifest";
 var FLEET_JSON_SCHEMA = "fleet-experimental-0.2";
 var CORP_WALL_ARTIFACTS = ["PROJECT_CONTEXT.md", "DECISIONS.md"];
@@ -3525,7 +3775,7 @@ function stateBudgetsFor(entry) {
 async function gitGrepFiles(root, needle, mode = "fixed") {
   try {
     const matchFlag = mode === "regex" ? "-E" : "-F";
-    const { stdout } = await pExecFile2("git", ["grep", "-I", "-l", matchFlag, "-e", needle], {
+    const { stdout } = await pExecFile3("git", ["grep", "-I", "-l", matchFlag, "-e", needle], {
       cwd: root,
       timeout: 8e3
     });
@@ -4075,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 };