etymd 0.17.0 → 0.19.1

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 = "15";
   }
 });
 
@@ -30,7 +30,7 @@ var init_package = __esm({
   "package.json"() {
     package_default = {
       name: "etymd",
-      version: "0.17.0",
+      version: "0.19.1",
       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"
   );
@@ -1154,15 +1237,21 @@ function contentScreenCall(opts) {
     `${indent}fi`
   ].join("\n");
 }
-function localHookCall(hook) {
+function localHookCall(hook, feedRefs = false) {
+  const refsCapture = feedRefs ? `# git hands the pushed refs to pre-push ONCE, on stdin \u2014 one line per ref:
+# "<local ref> <local sha> <remote ref> <remote sha>". The shell gate below reads them too, so
+# they are captured here and fed to each.
+refs=$(cat)
+` : "";
+  const call = feedRefs ? `printf '%s\\n' "$refs" | "$LOCAL" "$@" || exit 1` : `"$LOCAL" "$@" || exit 1`;
   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
+${refsCapture}if [ -x "$LOCAL" ]; then
+  ${call}
 fi`;
 }
 function generatePreCommitHook(selfBuild = false) {
@@ -1171,10 +1260,10 @@ function generatePreCommitHook(selfBuild = false) {
 
 ${localHookCall("pre-commit")}
 
-# Content screen \u2014 staged file bytes. Refuses to commit environment, guarded-side or identity
-# detail into a repo whose history is (or could become) public. The checker and its patterns
-# are machine-local by design, so this is a NO-OP wherever no checker is installed: safe to
-# commit anywhere, active only where you opted in.
+# Content screen \u2014 staged file bytes. Refuses to commit detail about your environment, work
+# or identity into a repo whose history is (or could become) public. The checker and its
+# patterns are machine-local by design, so this is a NO-OP wherever no checker is installed:
+# safe to commit anywhere, active only where you opted in.
 #
 # Bypass, with a reason: git commit --no-verify
 ${contentGateResolution(selfBuild)}
@@ -1228,42 +1317,181 @@ ${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.
+#
+# The hook runs it from inside a commit materialised from git's object store, so paths resolve
+# against that tree, never the working tree. A path with nothing readable behind it \u2014 a
+# submodule entry, a dangling symlink \u2014 cannot lie about its contents, so it is a disclosed
+# skip, never a block. 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 commits BEING PUSHED are
+# the bytes that ship, so each one is materialised from git's object store and checked there \u2014
+# never the working tree (wrong in both directions: a fixed tree let an unfixed commit ship, and
+# a dirty tree shared by several sessions blocked an unrelated push) and never the tip alone (a
+# bad commit under a clean tip shipped while the gate read only the tip's fix). 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 \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
+    # Every commit in each pushed range, never the tip alone: pushing two commits \u2014 a bad
+    # script, then its fix \u2014 passed a tip-only read while the bad commit landed on the remote.
+    # An all-zero local sha is a delete (nothing to check). An all-zero REMOTE sha is a new
+    # branch: everything no remote already has is being pushed, so the range is the local sha
+    # minus every remote-tracking ref \u2014 commits a remote already received were gated when they
+    # landed there, and the residue is exactly this push's new commits. A remote sha this clone
+    # has never seen (the remote moved on since the last fetch) cannot bound a range, so it takes
+    # the same new-branch rule instead of refusing a push the gate could have read. Enumeration
+    # failure refuses the push: a range the gate could not list is a range it did not read.
+    # (pattern) with both parens: bash 3.2 (macOS /bin/sh) cannot parse an unbalanced )
+    # in a case pattern.
+    : > "$shellcheck_tmp/shas" || exit 1
+    printf '%s\\n' "$refs" | while read -r _lref lsha _rref rsha; do
+      case "$lsha" in
+        (*[!0]*) ;;
+        (*) continue ;;
+      esac
+      case "$rsha" in
+        (*[!0]*)
+          if git cat-file -e "\${rsha}^{commit}" 2>/dev/null; then
+            git rev-list "$rsha..$lsha"
+          else
+            git rev-list "$lsha" --not --remotes
+          fi ;;
+        (*) git rev-list "$lsha" --not --remotes ;;
+      esac >> "$shellcheck_tmp/shas" || exit 1
+    done || {
+      echo "etymd: could not enumerate the commits being pushed 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/^/    /'
-    fi
-  fi
+    shas=$(sort -u "$shellcheck_tmp/shas") || exit 1
+    [ -n "$shas" ] || echo "\u203A shellcheck: no commit in the pushed refs (deletes only, or nothing on stdin) \u2014 nothing to check"
+    # Resolved once, before any cd: the classifier runs inside each materialised tree, and a
+    # relative hook path would no longer point at it from there.
+    discover="$(cd "$(dirname "$0")" && pwd)/discover-shell-scripts.sh" || exit 1
+    for sha in $shas; do
+      # A fresh directory per commit, removed once that commit is checked so a long push does
+      # not pile up one full tree per commit; the subshell trap above still cleans the root on
+      # every early exit.
+      tree=$(mktemp -d "$shellcheck_tmp/commit.XXXXXX") || exit 1
+      # Checked out through a scratch index, never \`git archive\`: archive honours the
+      # export-ignore and export-subst attributes, so a script marked export-ignore would leave
+      # the checked set without a word. read-tree + checkout-index writes every tracked blob.
+      # Large-file pointers stay pointers \u2014 they are never shell, and a push must not need the
+      # network to be checked.
+      if ! git cat-file -e "\${sha}^{commit}" 2>/dev/null \\
+         || ! GIT_INDEX_FILE="$shellcheck_tmp/index" git read-tree "$sha" 2>/dev/null \\
+         || ! GIT_INDEX_FILE="$shellcheck_tmp/index" GIT_LFS_SKIP_SMUDGE=1 \\
+              git checkout-index -a -f --prefix="$tree/" 2>/dev/null; then
+        echo "\u2717 shellcheck: could not materialise $(git rev-parse --short "$sha" 2>/dev/null || echo "$sha") \u2014 refusing the push rather than certifying bytes this gate did not read" >&2
+        exit 1
+      fi
+      if [ -n "$(git ls-tree -r --name-only "$sha")" ] && [ -z "$(ls -A "$tree")" ]; then
+        echo "\u2717 shellcheck: $(git rev-parse --short "$sha" 2>/dev/null || echo "$sha") extracted to an empty tree \u2014 refusing the push" >&2
+        exit 1
+      fi
+      : > "$shellcheck_tmp/scripts" && : > "$shellcheck_tmp/count" && : > "$shellcheck_tmp/zsh-count" && : > "$shellcheck_tmp/skip-count" || exit 1
+      git ls-tree -r -z --name-only "$sha" > "$shellcheck_tmp/tracked" || {
+        echo "etymd: cannot enumerate the tree of $(git rev-parse --short "$sha" 2>/dev/null || echo "$sha") for shellcheck" >&2
+        exit 1
+      }
+      ( cd "$tree" && xargs -0 "$discover" "$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 or dangling symlink) \u2014 not checked, not failed"
+      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 in $(git rev-parse --short "$sha" 2>/dev/null || echo "$sha"), blocking at severity=warning)"
+        ( cd "$tree" && 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=$( ( cd "$tree" && 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
+      rm -rf "$tree" || exit 1
+    done
+  ) || exit 1
 else
   echo "\u203A shellcheck skipped (not on PATH) \u2014 install it to gate this repo's shell scripts"
 fi`;
@@ -1296,7 +1524,7 @@ fi`;
   return stampGenerated(`#!/usr/bin/env sh
 # etymd: correctness gate. Mirrors CI cheapest-first; blocks the push on any failure.
 
-${localHookCall("pre-push")}${runner}
+${localHookCall("pre-push", true)}${runner}
 ${body}${shellStep}
 ${auditStep}
 
@@ -1426,6 +1654,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"));
@@ -1459,6 +1688,14 @@ async function planWorkflow(root, facts, opts) {
       "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",
@@ -1893,7 +2130,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);
@@ -2042,7 +2279,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 ]";
@@ -2059,7 +2296,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;
@@ -2079,7 +2316,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;
@@ -2757,10 +2994,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) {
@@ -2794,14 +3034,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;
@@ -2814,8 +3061,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]);
@@ -2824,13 +3075,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(" ")
@@ -2902,12 +3155,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) => {
@@ -2937,6 +3192,7 @@ function emptyCounters() {
     unverifiableCommands: 0,
     gitignoredSkipped: 0,
     prospectiveSkipped: 0,
+    fetchedSkipped: 0,
     placeholderSkipped: 0,
     qualifiedRefsSkipped: 0,
     unresolvableRefs: 0,
@@ -2979,19 +3235,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)) {
@@ -3279,6 +3564,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.`
@@ -3316,7 +3606,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,
@@ -3747,6 +4037,7 @@ async function loadFleetManifest(manifestPath) {
 
 // src/engine/fleet.ts
 init_config();
+init_detect();
 init_facts();
 init_util();
 
@@ -3875,7 +4166,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"];
@@ -3930,7 +4221,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
     });
@@ -4353,6 +4644,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 = [];
@@ -4362,6 +4678,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) {
@@ -4708,7 +5025,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,
@@ -4896,6 +5212,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.`