etymd 0.16.0 → 0.19.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 = "12";
+    PACK_VERSION = "14";
   }
 });
 
@@ -30,7 +30,7 @@ var init_package = __esm({
   "package.json"() {
     package_default = {
       name: "etymd",
-      version: "0.16.0",
+      version: "0.19.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",
@@ -104,7 +104,7 @@ var init_package = __esm({
         prettier: "3.4.2",
         tsup: "8.5.1",
         typescript: "5.7.2",
-        vitest: "4.1.10"
+        vitest: "4.1.11"
       },
       publishConfig: {
         access: "public"
@@ -388,10 +388,17 @@ async function hasLintStagedConfig(root, pkg) {
   }
   return false;
 }
+function normalizeHooksPath(root, raw) {
+  const abs = path2.resolve(root, raw);
+  const rel = path2.relative(root, abs);
+  const outside = path2.isAbsolute(rel) || rel === ".." || rel.startsWith(`..${path2.sep}`);
+  return outside ? abs : normalizeRelPath(rel) || ".";
+}
 async function detectHooks(root, hooksPath, pkg) {
   const lintStaged = await hasLintStagedConfig(root, pkg);
   if (hooksPath) {
-    if (hooksPath.replace(/\/+$/, "") === ".husky/_") {
+    const dir = normalizeHooksPath(root, hooksPath);
+    if (dir === ".husky/_") {
       const base2 = path2.join(root, ".husky");
       return {
         source: "husky",
@@ -402,10 +409,10 @@ async function detectHooks(root, hooksPath, pkg) {
         lintStaged
       };
     }
-    const base = path2.join(root, hooksPath);
+    const base = path2.resolve(root, dir);
     return {
-      source: hooksPath === ".githooks" ? "githooks" : "custom",
-      dir: hooksPath,
+      source: dir === ".githooks" ? "githooks" : "custom",
+      dir,
       preCommit: await pathExists(path2.join(base, "pre-commit")),
       prePush: await pathExists(path2.join(base, "pre-push")),
       commitMsg: await pathExists(path2.join(base, "commit-msg")),
@@ -494,6 +501,64 @@ async function detectArtifacts(root) {
   });
   return artifacts;
 }
+function detectClaudeCodeVersion() {
+  const override = process.env.ETYMD_CLAUDE_VERSION;
+  if (override !== void 0) {
+    return Promise.resolve(override === "none" || override === "" ? null : override);
+  }
+  claudeVersionMemo ??= pExecFile2("claude", ["--version"], { timeout: 5e3 }).then(({ stdout }) => /(\d+\.\d+\.\d+)/.exec(stdout)?.[1] ?? null).catch(() => null);
+  return claudeVersionMemo;
+}
+function versionBefore(a, b) {
+  const pa = a.split(".").map(Number);
+  const pb = b.split(".").map(Number);
+  for (let i = 0; i < Math.max(pa.length, pb.length); i++) {
+    const x = pa[i] ?? 0;
+    const y = pb[i] ?? 0;
+    if (x !== y) return x < y;
+  }
+  return false;
+}
+async function checkClaudePointer(root, claudeVersion) {
+  const agentsAbs = path2.join(root, "AGENTS.md");
+  const claudeAbs = path2.join(root, "CLAUDE.md");
+  if (!await pathExists(agentsAbs)) return { ok: true, via: "no-agents" };
+  const statOrNone = async (p) => {
+    try {
+      return await promises.stat(p);
+    } catch {
+      return null;
+    }
+  };
+  const [agentsSt, claudeSt] = await Promise.all([statOrNone(agentsAbs), statOrNone(claudeAbs)]);
+  if (agentsSt && claudeSt && agentsSt.ino !== 0 && agentsSt.ino === claudeSt.ino && agentsSt.dev === claudeSt.dev) {
+    return { ok: true, via: "same-file" };
+  }
+  const rootClaude = await readText(claudeAbs);
+  if (rootClaude !== null && ROOT_POINTER_IMPORT_RE.test(rootClaude)) {
+    return { ok: true, via: "root-import" };
+  }
+  const dotClaude = await readText(path2.join(root, ".claude", "CLAUDE.md"));
+  if (dotClaude !== null && DOT_CLAUDE_IMPORT_RE.test(dotClaude)) {
+    return { ok: true, via: "dotclaude-import" };
+  }
+  if (rootClaude !== null || dotClaude !== null) {
+    return {
+      ok: false,
+      kind: "no-import",
+      detail: rootClaude !== null ? "AGENTS.md and CLAUDE.md both present, but CLAUDE.md does not import it" : "AGENTS.md and .claude/CLAUDE.md both present, but .claude/CLAUDE.md does not import it"
+    };
+  }
+  const version = await detectClaudeCodeVersion() ;
+  if (version !== null && versionBefore(version, CLAUDE_AGENTS_FALLBACK_VERSION)) {
+    return {
+      ok: false,
+      kind: "old-reader",
+      detail: `AGENTS.md present, no CLAUDE.md, and Claude Code ${version} predates the AGENTS.md fallback (${CLAUDE_AGENTS_FALLBACK_VERSION})`
+    };
+  }
+  return { ok: true, via: "native-fallback" };
+}
 async function walkTree(root) {
   const state = { budget: 2e4, truncated: false };
   const countFiles = async (dir) => {
@@ -539,7 +604,7 @@ async function walkTree(root) {
   dirs.sort((a, b) => b.files - a.files);
   return { dirs, truncated: state.truncated };
 }
-var IGNORED_DIRS, MEANINGFUL_DOT_DIRS, isMeta, ROLE_LADDERS, FRAMEWORK_MARKERS, ARTIFACT_SPECS, SHELL_SHEBANG, SHELL_EXT;
+var IGNORED_DIRS, MEANINGFUL_DOT_DIRS, isMeta, ROLE_LADDERS, FRAMEWORK_MARKERS, ARTIFACT_SPECS, SHELL_SHEBANG, SHELL_EXT, ROOT_POINTER_IMPORT_RE, DOT_CLAUDE_IMPORT_RE, CLAUDE_AGENTS_FALLBACK_VERSION, pExecFile2, claudeVersionMemo;
 var init_detect = __esm({
   "src/core/detect.ts"() {
     init_util();
@@ -714,6 +779,10 @@ var init_detect = __esm({
     ];
     SHELL_SHEBANG = /^#!\s*\/\S*\b(?:ba|da|z)?sh\b|^#!\s*\/usr\/bin\/env\s+(?:ba|da|z)?sh\b/;
     SHELL_EXT = /\.(?:sh|bash|zsh)$/;
+    ROOT_POINTER_IMPORT_RE = /^\s*@(\.\/)?AGENTS\.md\s*$/m;
+    DOT_CLAUDE_IMPORT_RE = /^\s*@\.\.\/AGENTS\.md\s*$/m;
+    CLAUDE_AGENTS_FALLBACK_VERSION = "2.1.277";
+    pExecFile2 = promisify(execFile);
   }
 });
 
@@ -795,11 +864,12 @@ async function scanProject(root, opts = {}) {
   const [branch, head, hooksPathRaw, authorsRaw, subjectsRaw] = isRepo ? await Promise.all([
     git(abs, ["rev-parse", "--abbrev-ref", "HEAD"]),
     git(abs, ["rev-parse", "--short", "HEAD"]),
-    git(abs, ["config", "--get", "core.hooksPath"]),
+    // `--type=path` expands a leading `~` the way git itself does when it runs the hooks.
+    git(abs, ["config", "--type=path", "--get", "core.hooksPath"]),
     git(abs, ["log", "-200", "--format=%ae"]),
     git(abs, ["log", "-50", "--format=%s"])
   ]) : [null, null, null, null, null];
-  const hooksPath = hooksPathRaw ?? void 0;
+  const hooksPath = hooksPathRaw ? normalizeHooksPath(abs, hooksPathRaw) : void 0;
   const hooks = await detectHooks(abs, hooksPath, rootPkg);
   const shell = await detectShellSurface(abs, isRepo);
   const freshness = await collectFreshness(abs, isRepo, artifacts, opts.upstreamRemote);
@@ -1132,6 +1202,19 @@ ${[
     ].filter(Boolean).join("\n") || "# add the project's key commands"}
 \`\`\`
 
+`,
+    "md"
+  );
+}
+function generateClaudePointerMd() {
+  return stampGenerated(
+    `# CLAUDE.md
+
+Single source of truth for agent instructions lives in \`AGENTS.md\`. This pointer keeps Claude
+Code aligned with every other agent \u2014 edit \`AGENTS.md\`, not this file.
+
+@AGENTS.md
+
 `,
     "md"
   );
@@ -1228,42 +1311,118 @@ ${localHookCall("commit-msg")}
 exit 0
 `);
 }
+function generateShellDiscoveryScript() {
+  return stampGenerated(`#!/usr/bin/env sh
+# etymd: shell script discovery for the pre-push shellcheck step. Arguments: the scratch
+# directory the hook created, then the tracked paths to classify (NUL-delimited on the hook's
+# side, positional here). Verdicts land in the scratch: scripts (NUL-delimited matches) and one
+# dot per decision into count / zsh-count / skip-count, tallied by the hook after the pipeline.
+#
+# A path with nothing readable behind it \u2014 a submodule entry, a dangling symlink, a file
+# deleted from the worktree while still tracked \u2014 cannot lie about its contents, so it is a
+# disclosed skip, never a block: an absent worktree file is routine dirty state. A regular file
+# that EXISTS but cannot be read is the other branch \u2014 coverage would silently shrink, so it
+# fails, naming the path.
+#
+# The two \`[ "$?" -eq 1 ]\` guards are the match/error protocol: grep reports "no match" as 1
+# and a failure as 2 or more, and only the first is a verdict. Dropping the guard would let a
+# failing matcher pass as "not a shell script" \u2014 the exact silent coverage-shrink the
+# fail-closed rules exist to prevent. The checker does not associate \`$?\` with the enclosing
+# if-condition, which is why this shape survives the pass it serves; keep it that way.
+work=$1
+shift
+for file do
+  if [ ! -f "./$file" ]; then
+    printf . >> "$work/skip-count" || exit 1
+    continue
+  fi
+  # 4096 bytes bound the read \u2014 a binary with no newline would otherwise be copied whole
+  # into the scratch on every push. The second head restores line-1-only semantics, so a
+  # shebang embedded on a LATER line of a document cannot match the patterns below.
+  head -c 4096 "./$file" > "$work/head-bytes" || {
+    echo "etymd: cannot read tracked file for shellcheck: $file" >&2
+    exit 1
+  }
+  head -n 1 "$work/head-bytes" > "$work/first-line" || exit 1
+  if grep -qE "^#!.*[/ ](ba|da)?sh( |$)" "$work/first-line"; then
+    printf "./%s\\0" "$file" >> "$work/scripts" || exit 1
+    printf . >> "$work/count" || exit 1
+  else
+    [ "$?" -eq 1 ] || exit 1
+    if grep -qE "^#!.*[/ ]zsh( |$)" "$work/first-line"; then
+      printf . >> "$work/zsh-count" || exit 1
+    else
+      [ "$?" -eq 1 ] || exit 1
+    fi
+  fi
+done
+`);
+}
 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. zsh is NOT in the checked set:
+# script added later is covered without regenerating this hook. The classifier is
+# discover-shell-scripts.sh beside this hook \u2014 tracked and shebanged like what it classifies,
+# so the scan it implements finds and checks it too. 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 same honesty splits the unreadable: a regular file that exists but cannot be read blocks
+# the push (coverage would otherwise silently shrink), while a tracked path with nothing readable
+# behind it \u2014 a submodule entry, a dangling symlink, a file deleted from the worktree while
+# still tracked \u2014 is counted and said so below as skipped, never a block.
 #
 # "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)?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 || {
-      echo "  fix, or justify inline with '# shellcheck disable=SCxxxx  # why'"
+  (
+    # POSIX pipelines report only the LAST command's status, so discovery tallies progress in
+    # files \u2014 one dot per decision, counted with wc -c after the pipeline \u2014 rather than
+    # streaming through it: a pipeline that dies halfway cannot then pass as complete coverage,
+    # and the same tallies carry the counts to the reporting below. The classifier writes the
+    # tallies; this half only reads them.
+    # NUL delimiters preserve filenames; positional arguments avoid xargs -I size limits and
+    # interpreting filenames as shell code (never -I{}). The subshell confines cleanup to
+    # this step. The classifier itself is the tracked, shebanged helper beside this hook, so
+    # the discovery it performs finds and checks it too \u2014 the gate covers its own classifier.
+    shellcheck_tmp=$(mktemp -d) || exit 1
+    trap 'rm -rf "$shellcheck_tmp"' 0
+    trap 'exit 1' 1 2 3 15
+    git ls-files -z > "$shellcheck_tmp/tracked" || {
+      echo "etymd: cannot enumerate tracked files for shellcheck" >&2
       exit 1
     }
-    # Everything below the blocking bar, shown once the push is already cleared. Never affects
-    # the exit code \u2014 advice that can fail a push is not advice.
-    advice=$(printf '%s\\n' "$scripts" | xargs shellcheck -S style -f gcc 2>/dev/null \\
-      | grep -v ': warning:\\|: error:' || true)
-    if [ -n "$advice" ]; then
-      echo "  \xB7 style/info (not blocking):"
-      printf '%s\\n' "$advice" | sed 's/^/    /'
+    : > "$shellcheck_tmp/scripts" && : > "$shellcheck_tmp/count" && : > "$shellcheck_tmp/zsh-count" && : > "$shellcheck_tmp/skip-count" || exit 1
+    xargs -0 "$(dirname "$0")/discover-shell-scripts.sh" "$shellcheck_tmp" < "$shellcheck_tmp/tracked" || {
+      echo "etymd: shell script discovery failed; shellcheck coverage is incomplete" >&2
+      exit 1
+    }
+    count=$(wc -c < "$shellcheck_tmp/count") || exit 1
+    zsh_count=$(wc -c < "$shellcheck_tmp/zsh-count") || exit 1
+    skip_count=$(wc -c < "$shellcheck_tmp/skip-count") || exit 1
+    if [ "$skip_count" -gt 0 ]; then
+      echo "\u203A shellcheck: $((skip_count)) tracked path(s) with nothing readable behind them (submodule, dangling symlink, or deleted from the worktree) \u2014 not checked, not failed"
     fi
-  fi
+    if [ "$zsh_count" -gt 0 ]; then
+      echo "\u203A shellcheck: $((zsh_count)) zsh script(s) excluded \u2014 shellcheck cannot parse zsh (SC1071); not checked, not failed"
+    fi
+    if [ "$count" -gt 0 ]; then
+      echo "\u203A shellcheck ($((count)) scripts, blocking at severity=warning)"
+      xargs -0 shellcheck -S warning -- < "$shellcheck_tmp/scripts" || {
+        echo "  fix, or justify inline with '# shellcheck disable=SCxxxx  # why'"
+        exit 1
+      }
+      # Everything below the blocking bar, shown once the push is already cleared. Never affects
+      # the exit code \u2014 advice that can fail a push is not advice.
+      advice=$(xargs -0 shellcheck -S style -f gcc -- < "$shellcheck_tmp/scripts" 2>/dev/null \\
+        | grep -v ': warning:\\|: error:' || true)
+      if [ -n "$advice" ]; then
+        echo "  \xB7 style/info (not blocking):"
+        printf '%s\\n' "$advice" | sed 's/^/    /'
+      fi
+    fi
+  ) || exit 1
 else
   echo "\u203A shellcheck skipped (not on PATH) \u2014 install it to gate this repo's shell scripts"
 fi`;
@@ -1426,6 +1585,7 @@ async function planWorkflow(root, facts, opts) {
   };
   if (opts.agents) {
     await add("AGENTS.md", generateAgentsMd(facts), "Minimal operating contract (scaffold)");
+    await add("CLAUDE.md", generateClaudePointerMd(), "Claude Code pointer to AGENTS.md");
   }
   if (opts.gates) {
     const existingPrePush = await readText(path2.join(root, ".githooks", "pre-push"));
@@ -1449,12 +1609,24 @@ async function planWorkflow(root, facts, opts) {
       commitFormat: opts.gateConfig?.commitFormat,
       allowWriting: opts.gateConfig?.allowWriting ?? []
     };
+    const tier = deriveFailOn(facts, {
+      failOn: gateConfig.failOn,
+      explicit: opts.gateFailOnPinned ?? false
+    });
     await add(
       ".githooks/pre-push",
-      generatePrePushHook(facts, gateConfig, selfBuild),
+      generatePrePushHook(facts, { ...gateConfig, failOn: tier.failOn }, selfBuild),
       "Correctness gate (pre-push)",
       true
     );
+    if (facts.shell?.scripts) {
+      await add(
+        ".githooks/discover-shell-scripts.sh",
+        generateShellDiscoveryScript(),
+        "Shell discovery (pre-push shellcheck helper)",
+        true
+      );
+    }
     if (opts.gateConfig?.publishGate ?? opts.publishGate ?? facts.publishable) {
       await add(
         "scripts/artifact-check.sh",
@@ -1889,7 +2061,7 @@ async function localHookTools(root, facts, scripts) {
   const inertCompanions = [];
   const readHook = async (name) => {
     if (!hooks.dir) return empty;
-    const text = await readText(path2.join(root, hooks.dir, name));
+    const text = await readText(path2.resolve(root, hooks.dir, name));
     if (!text) return empty;
     const tools = new Set(matchTools(text, scripts));
     const companion = await companionOf(root, hooks.dir, name, text, scripts);
@@ -2038,7 +2210,7 @@ async function buildGateInventory(root, facts) {
 
 // src/lenses/gate-integrity/screener.ts
 init_util();
-var pExecFile2 = promisify(execFile);
+var pExecFile3 = 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 ]";
@@ -2055,7 +2227,7 @@ async function probeScreener(root, facts) {
   const doors = [];
   let devBuildArm = false;
   for (const name of HOOK_FILES) {
-    const text = await readText(path2.join(root, dir, name));
+    const text = await readText(path2.resolve(root, dir, name));
     if (!text || !SCREEN_CALL_RE.test(text)) continue;
     doors.push(`${dir}/${name}`);
     if (text.includes(DEV_BUILD_ARM)) devBuildArm = true;
@@ -2075,7 +2247,7 @@ async function probeScreener(root, facts) {
     source = "path";
   }
   try {
-    await pExecFile2(runner, ["screen", "--help"], { cwd: root, timeout: 1e4 });
+    await pExecFile3(runner, ["screen", "--help"], { cwd: root, timeout: 1e4 });
     return { present: true, doors, runner, source, answersScreen: true };
   } catch (err) {
     const e = err;
@@ -2753,10 +2925,13 @@ function extractCommandClaims(text) {
   return { scripts, filteredSkipped };
 }
 var PATH_TOKEN_RE = /^[A-Za-z0-9_.-]+(\/[A-Za-z0-9_.$-]+)+\/?$/;
+var HOSTNAME_RE = /^[a-z0-9-]+(?:\.[a-z0-9-]+)*\.([a-z]{2,})$/i;
 var KNOWN_EXTENSIONS = /* @__PURE__ */ new Set([
   ..."ts tsx cts mts js jsx cjs mjs json jsonc json5 md mdx mdc yml yaml toml ini cfg conf env sh bash zsh fish ps1 bat cmd css scss sass less html htm xml svg sql prisma graphql gql proto py rb rs go java kt kts swift c h cc cpp hpp cs php vue svelte astro txt log lock csv tsv png jpg jpeg gif webp ico avif woff woff2 ttf otf wasm map pem key crt tf tfvars example sample local snap ejs hbs pug".split(" ")
 ]);
 var CREATION_CONTEXT_RE = /\b(?:creat(?:e|es|ed|ing)|generat(?:e|es|ed|ing)|scaffold(?:s|ed|ing)?|quarantin(?:e|es|ed|ing)|(?:writ(?:e|es|ten|ing)|output(?:s|ted)?|emit(?:s|ted|ting)?|sav(?:e|es|ed|ing)|mov(?:e|es|ed|ing)|copy|copi(?:es|ed))\s+(?:it\s+|them\s+)?(?:to|into)|new\s+(?:file|directory|folder)|will\s+(?:be\s+)?(?:created|generated|written)|add(?:s|ed|ing)?\s+(?:a|the)\s+new)\b/i;
+var FETCH_CONTEXT_RE = /\b(?:fetch(?:es|ed|ing)?|pull(?:s|ed|ing)?|clone(?:s|d)?|download(?:s|ed|ing)?)\b/i;
+var EXTERNAL_URL_RE = /https?:\/\/|\bwww\./i;
 var PLACEHOLDER_SEGMENTS = /* @__PURE__ */ new Set(["placeholder", "foo", "bar", "baz", "qux"]);
 var PLACEHOLDER_PREFIX_RE = /^(?:my|your)-/i;
 function isPlaceholderClaim(token) {
@@ -2790,14 +2965,21 @@ ${line}`;
 }
 function extractPathClaims(text, opts = {}) {
   const prospectiveOnly = /* @__PURE__ */ new Map();
+  const fetchedOnly = /* @__PURE__ */ new Map();
   const namespacedOnly = /* @__PURE__ */ new Map();
   const placeholder = /* @__PURE__ */ new Set();
+  const dirs = /* @__PURE__ */ new Set();
   for (const m of text.matchAll(/`([^`\n]+)`/g)) {
     const token = m[1].trim();
     if (token.includes(" ") || token.length > 120) continue;
     if (token.startsWith("/") || token.startsWith("~") || token.startsWith("@") || token.startsWith("$"))
       continue;
     if (token.includes("://") || token.startsWith("www.")) continue;
+    if (token.includes("/")) {
+      const firstSegment = token.split("/")[0] ?? token;
+      const hostSuffix = HOSTNAME_RE.exec(firstSegment)?.[1]?.toLowerCase();
+      if (hostSuffix && !KNOWN_EXTENSIONS.has(hostSuffix)) continue;
+    }
     if (/[*?{}<>|]/.test(token)) continue;
     if (token.includes("@")) continue;
     if (!PATH_TOKEN_RE.test(token)) continue;
@@ -2810,8 +2992,12 @@ function extractPathClaims(text, opts = {}) {
       placeholder.add(claim);
       continue;
     }
-    const prospective2 = CREATION_CONTEXT_RE.test(claimContext(text, m.index ?? 0));
+    if (isDirClaim) dirs.add(claim);
+    const context = claimContext(text, m.index ?? 0);
+    const prospective2 = CREATION_CONTEXT_RE.test(context);
     prospectiveOnly.set(claim, (prospectiveOnly.get(claim) ?? true) && prospective2);
+    const fetched2 = FETCH_CONTEXT_RE.test(context) && EXTERNAL_URL_RE.test(context);
+    fetchedOnly.set(claim, (fetchedOnly.get(claim) ?? true) && fetched2);
     if (opts.namespaces) {
       const nsLead = new RegExp(`(${NAMESPACE_IDENT}):[ \\t]*$`).exec(text.slice(0, m.index ?? 0));
       const prefixed = isNamespace(nsLead?.[1]);
@@ -2820,13 +3006,15 @@ function extractPathClaims(text, opts = {}) {
   }
   const paths = [];
   const prospective = [];
+  const fetched = [];
   const namespaced = [];
   for (const [claim, only] of prospectiveOnly) {
-    if (only) prospective.push(claim);
+    if (fetchedOnly.get(claim)) fetched.push(claim);
+    else if (only) prospective.push(claim);
     else if (namespacedOnly.get(claim)) namespaced.push(claim);
     else paths.push(claim);
   }
-  return { paths, prospective, namespaced, placeholder: [...placeholder] };
+  return { paths, dirs: [...dirs], prospective, fetched, namespaced, 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(" ")
@@ -2898,12 +3086,14 @@ async function buildTruthEnv(root, facts) {
     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) => {
+  const pathResolves = async (claim, fromDir) => {
     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;
     }
+    if (fromDir && fromDir !== "." && await pathExists(path2.join(root, fromDir, claim)))
+      return true;
     return false;
   };
   const binResolves = async (name) => {
@@ -2933,6 +3123,7 @@ function emptyCounters() {
     unverifiableCommands: 0,
     gitignoredSkipped: 0,
     prospectiveSkipped: 0,
+    fetchedSkipped: 0,
     placeholderSkipped: 0,
     qualifiedRefsSkipped: 0,
     unresolvableRefs: 0,
@@ -2975,19 +3166,48 @@ async function checkTextClaims(env, file, opts, counters) {
       confidence: "high"
     });
   }
-  const { paths, prospective, placeholder, namespaced } = extractPathClaims(file.text, {
-    namespaces: opts.treatNamespacedPrefixes
-  });
+  const { paths, dirs, prospective, fetched, placeholder, namespaced } = extractPathClaims(
+    file.text,
+    { namespaces: opts.treatNamespacedPrefixes }
+  );
   counters.prospectiveSkipped += prospective.length;
+  counters.fetchedSkipped += fetched.length;
   counters.placeholderSkipped += placeholder.length;
   counters.namespacedSkipped += namespaced.length;
-  const missing = [];
+  const fromDir = path2.dirname(file.path);
+  const unresolved = [];
   for (const claim of paths) {
-    if (await env.pathResolves(claim)) examined.push({ kind: "path", value: claim, exists: true });
+    if (await env.pathResolves(claim, fromDir))
+      examined.push({ kind: "path", value: claim, exists: true });
+    else unresolved.push(claim);
+  }
+  const proseBases = /* @__PURE__ */ new Set();
+  for (const dirClaim of dirs) {
+    if (await env.pathResolves(dirClaim, fromDir)) {
+      proseBases.add(dirClaim);
+      proseBases.add(path2.dirname(dirClaim));
+    }
+  }
+  const missing = [];
+  for (const claim of unresolved) {
+    let anchored = false;
+    for (const base of proseBases) {
+      if (await pathExists(path2.join(env.root, base, claim))) anchored = true;
+      else if (fromDir !== "." && await pathExists(path2.join(env.root, fromDir, base, claim)))
+        anchored = true;
+      if (anchored) break;
+    }
+    if (anchored) 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));
+  const unproven = missing.filter((claim) => !gitignored.has(claim));
+  if (unproven.length) {
+    const dirOut = await git(env.root, ["check-ignore", ...unproven.map((claim) => `${claim}/`)]);
+    for (const line of (dirOut ?? "").split("\n").filter(Boolean))
+      gitignored.add(line.replace(/\/$/, ""));
+  }
   let pathFindings = 0;
   for (const claim of missing) {
     if (opts.rootedFirstSegments && !opts.rootedFirstSegments.has(claim.split("/")[0] ?? claim)) {
@@ -3275,6 +3495,11 @@ var instructionTruthLens = {
         `${counters.prospectiveSkipped} path claim(s) sit in create-this prose (the file instructs generating them) \u2014 forward-looking, not stale; skipped, not flagged.`
       );
     }
+    if (counters.fetchedSkipped) {
+      disclosures.push(
+        `${counters.fetchedSkipped} path claim(s) sit beside the URL they are fetched from \u2014 another tree's files, unverifiable here; skipped, not flagged.`
+      );
+    }
     if (counters.placeholderSkipped) {
       disclosures.push(
         `${counters.placeholderSkipped} path claim(s) are naming stand-ins (e.g. \`my-custom-skill\`) rather than real references; skipped, not flagged.`
@@ -3312,7 +3537,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 (${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.`
+      `Checked ${files.length} instruction file(s); commands resolved against root + ${facts.packages.length} workspace manifest(s) plus installed binaries; paths matched against root, package roots, the claiming file's directory, and directories the same file names; existence judged on the working tree (gitignored-but-present is true, gitignored-and-absent unverifiable). Heuristics: workspace-filtered commands skipped (${counters.filteredSkipped}); tokens without a recognized extension treated as prose (a dir claim needs a trailing slash); schemeless hosts read as URLs; gitignored claims unverifiable; create-this, fetched-from-URL, 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,
@@ -3743,6 +3968,7 @@ async function loadFleetManifest(manifestPath) {
 
 // src/engine/fleet.ts
 init_config();
+init_detect();
 init_facts();
 init_util();
 
@@ -3871,7 +4097,7 @@ function parseMilestones(text) {
 }
 
 // src/engine/fleet.ts
-var pExecFile3 = promisify(execFile);
+var pExecFile4 = promisify(execFile);
 var FLEET_LENS = "fleet-manifest";
 var FLEET_JSON_SCHEMA = "fleet-experimental-0.2";
 var GUARDED_WALL_ARTIFACTS = ["PROJECT_CONTEXT.md", "DECISIONS.md"];
@@ -3926,7 +4152,7 @@ function stateBudgetsFor(entry) {
 async function gitGrepFiles(root, needle, mode = "fixed") {
   try {
     const matchFlag = mode === "regex" ? "-E" : "-F";
-    const { stdout } = await pExecFile3("git", ["grep", "-I", "-l", matchFlag, "-e", needle], {
+    const { stdout } = await pExecFile4("git", ["grep", "-I", "-l", matchFlag, "-e", needle], {
       cwd: root,
       timeout: 8e3
     });
@@ -4307,8 +4533,13 @@ async function checkGateDrift(manifest, findings, disclosures) {
       );
       continue;
     }
-    const { config } = await readConfig2(root);
-    const planned = (await planWorkflow2(root, facts, { agents: false, gates: true, gateConfig: config.gates })).filter((f) => f.executable);
+    const { config, explicit } = await readConfig2(root);
+    const planned = (await planWorkflow2(root, facts, {
+      agents: false,
+      gates: true,
+      gateConfig: config.gates,
+      gateFailOnPinned: explicit.gatesFailOn
+    })).filter((f) => f.executable);
     const missing = planned.filter((f) => !f.exists).map((f) => f.path);
     const differing = planned.filter((f) => f.exists && f.differs);
     const stale = differing.filter((f) => f.drift !== "edited").map((f) => f.path);
@@ -4344,6 +4575,31 @@ async function checkGateDrift(manifest, findings, disclosures) {
     }
   }
 }
+async function checkClaudePointers(manifest, findings) {
+  for (const entry of manifest.entries) {
+    const root = entry.resolvedRoot;
+    if (!root || !await isDirectory(root)) continue;
+    const check = await checkClaudePointer(root);
+    if (check.ok) continue;
+    findings.push(
+      check.kind === "no-import" ? finding3(
+        `${FLEET_LENS}/claude-pointer-missing:${entry.name}`,
+        "risk",
+        `\`${entry.name}\` has a CLAUDE.md that never imports its AGENTS.md`,
+        [`${entry.name}: ${check.detail}`],
+        "Claude Code reads CLAUDE.md when one exists and falls back to AGENTS.md only when none does. A CLAUDE.md without the import shadows AGENTS.md, so the contract looks universal from inside the repo while Claude Code never receives it.",
+        "Add a full-line `@AGENTS.md` import to that CLAUDE.md, symlink either file to the other, or delete the CLAUDE.md if AGENTS.md is the whole contract."
+      ) : finding3(
+        `${FLEET_LENS}/claude-pointer-missing:${entry.name}`,
+        "gap",
+        `\`${entry.name}\` relies on the AGENTS.md fallback, which the installed Claude Code predates`,
+        [`${entry.name}: ${check.detail}`],
+        `Claude Code reads AGENTS.md on its own only from ${CLAUDE_AGENTS_FALLBACK_VERSION}; older releases load CLAUDE.md alone, so this repo's contract is invisible to them.`,
+        "Update Claude Code, or create a CLAUDE.md beside AGENTS.md whose only import line is `@AGENTS.md`."
+      )
+    );
+  }
+}
 async function collectWallFindings(manifest) {
   const findings = [];
   const disclosures = [];
@@ -4353,6 +4609,7 @@ async function collectWallFindings(manifest) {
   await checkHygieneNeedles(manifest, findings, disclosures);
   await checkGuardedEmails(manifest, findings, disclosures);
   await checkGateDrift(manifest, findings, disclosures);
+  await checkClaudePointers(manifest, findings);
   return { findings, disclosures };
 }
 function stateAgeDays(facts) {
@@ -4699,7 +4956,6 @@ var STOP_WORDS = new Set(
 );
 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,
@@ -4887,6 +5143,11 @@ async function runPremise(opts) {
       `${counters.prospectiveSkipped} path(s) sit in create-this prose (the task says to create them) \u2014 forward-looking, not missing; skipped.`
     );
   }
+  if (counters.fetchedSkipped) {
+    disclosures.push(
+      `${counters.fetchedSkipped} path(s) are named beside the URL they are fetched from \u2014 another tree, not this repo; skipped, not flagged.`
+    );
+  }
   if (counters.placeholderSkipped) {
     disclosures.push(
       `${counters.placeholderSkipped} path(s) are naming stand-ins (e.g. \`my-feature\`) rather than real references; skipped.`