etymd 0.16.0 → 0.19.0

package/dist/{chunk-OKJ3RGJB.js → chunk-HSRHOVII.js}

@@ -1,8 +1,5 @@
 #!/usr/bin/env node
-import { DEFAULT_CONFIG } from './chunk-P6ATKV2R.js';
-import { PACK_VERSION } from './chunk-YQZDYDAK.js';
-import { readText, pathExists } from './chunk-4VPBP6K6.js';
-import path from 'path';
+import { PACK_VERSION } from './chunk-U7BCBJIH.js';
 import { createHash } from 'crypto';
 
 var GENERATION_MARKER_RE = /^(?:# |<!-- )etymd:generated pack-v\S+ ([0-9a-f]{16})(?: -->)?$/;
@@ -128,6 +125,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"
   );
@@ -239,42 +249,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`;
@@ -359,94 +445,4 @@ exit 0
 `);
 }
 
-// src/core/generate.ts
-function derivedCommands(facts, existingHook) {
-  const c = facts.commands;
-  const base = [c.formatCheck, c.typecheck, c.lint].filter(
-    (k) => Boolean(k) && isSafeGateCommand(c.raw[k])
-  );
-  if (c.test && existingHook && new RegExp(`\\b${c.test}\\b`).test(existingHook)) {
-    base.push(c.test);
-  }
-  return base;
-}
-function riskReachability(facts) {
-  const reasons = [];
-  if (facts.publishRoute !== "none") {
-    reasons.push("an instruction file can name a package script that no longer exists");
-  }
-  if (facts.artifacts.some((a) => a.kind === "state" && a.exists)) {
-    reasons.push("a state doc can fall far enough behind the repo to escalate");
-  }
-  return reasons;
-}
-function deriveFailOn(facts, recorded) {
-  const reachable = riskReachability(facts);
-  if (recorded.explicit) return { failOn: recorded.failOn, source: "config", reachable };
-  if (recorded.failOn === "risk" && reachable.length === 0) {
-    return { failOn: "gap", source: "derived", reachable };
-  }
-  return { failOn: recorded.failOn, source: "default", reachable };
-}
-async function planWorkflow(root, facts, opts) {
-  const out = [];
-  const add = async (rel, contents, label, executable = false) => {
-    const abs = path.join(root, rel);
-    const exists = await pathExists(abs);
-    const existing = exists ? await readText(abs) : null;
-    const differs = exists ? existing !== contents : void 0;
-    const origin = differs && existing !== null ? fileOrigin(existing) : void 0;
-    out.push({
-      path: rel,
-      contents,
-      exists,
-      differs,
-      drift: origin === "pack" ? "stale" : origin,
-      executable,
-      label
-    });
-  };
-  if (opts.agents) {
-    await add("AGENTS.md", generateAgentsMd(facts), "Minimal operating contract (scaffold)");
-  }
-  if (opts.gates) {
-    const existingPrePush = await readText(path.join(root, ".githooks", "pre-push"));
-    const selfBuild = isSelfBuildRepo(facts);
-    await add(
-      ".githooks/pre-commit",
-      generatePreCommitHook(selfBuild),
-      "Process gate (pre-commit)",
-      true
-    );
-    await add(
-      ".githooks/commit-msg",
-      generateCommitMsgHook(opts.gateConfig),
-      "Message gate (content screen, format)",
-      true
-    );
-    const gateConfig = opts.gateConfig?.commands?.length ? opts.gateConfig : {
-      commands: derivedCommands(facts, existingPrePush ?? void 0),
-      failOn: opts.gateConfig?.failOn ?? DEFAULT_CONFIG.gates.failOn,
-      publishGate: opts.gateConfig?.publishGate,
-      commitFormat: opts.gateConfig?.commitFormat,
-      allowWriting: opts.gateConfig?.allowWriting ?? []
-    };
-    await add(
-      ".githooks/pre-push",
-      generatePrePushHook(facts, gateConfig, selfBuild),
-      "Correctness gate (pre-push)",
-      true
-    );
-    if (opts.gateConfig?.publishGate ?? opts.publishGate ?? facts.publishable) {
-      await add(
-        "scripts/artifact-check.sh",
-        generateArtifactCheckScript(selfBuild),
-        "Content screen (published artifact)",
-        true
-      );
-    }
-  }
-  return out;
-}
-
-export { deriveFailOn, derivedCommands, isSafeGateCommand, planWorkflow, riskReachability, runPrefix };
+export { fileOrigin, generateAgentsMd, generateArtifactCheckScript, generateClaudePointerMd, generateCommitMsgHook, generatePreCommitHook, generatePrePushHook, generateShellDiscoveryScript, isSafeGateCommand, isSelfBuildRepo, runPrefix };

package/dist/{chunk-UV3YIBDW.js → chunk-KIPD3N77.js}

@@ -1,10 +1,10 @@
 #!/usr/bin/env node
-import { stateFreshnessLens, rankFindings, listInstructionFiles, buildTruthEnv, emptyCounters, packageManagerUsage, checkDocRefs, listStateDocuments, loadDecisionLedger, checkDecisionRefs, checkTextClaims } from './chunk-Y4E6ERCM.js';
+import { stateFreshnessLens, rankFindings, listInstructionFiles, buildTruthEnv, emptyCounters, packageManagerUsage, checkDocRefs, listStateDocuments, loadDecisionLedger, checkDecisionRefs, checkTextClaims } from './chunk-EYUW3UJU.js';
 import { readLedger, reconcileLedger, writeLedger, visibleFindings } from './chunk-3E2IPCRY.js';
 import { measureContext, contextFileLabel } from './chunk-HI7NWPRA.js';
-import { scanProject } from './chunk-EJM47PIF.js';
+import { scanProject } from './chunk-DLHC7QON.js';
 import { DEFAULT_CONFIG, ETYMD_DIR, writeCachedFacts, readBaseline, readConfig, deriveProfile, baselineCarriesMachinePath, BASELINE_FILE, CONFIG_FILE } from './chunk-P6ATKV2R.js';
-import { PACK_VERSION } from './chunk-YQZDYDAK.js';
+import { PACK_VERSION } from './chunk-U7BCBJIH.js';
 import { pathExists, readText, readJson, isCiEnvironment, isExecutable } from './chunk-4VPBP6K6.js';
 import path from 'path';
 import YAML from 'yaml';
@@ -316,7 +316,7 @@ async function localHookTools(root, facts, scripts) {
   const inertCompanions = [];
   const readHook = async (name) => {
     if (!hooks.dir) return empty;
-    const text = await readText(path.join(root, hooks.dir, name));
+    const text = await readText(path.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);
@@ -479,7 +479,7 @@ async function probeScreener(root, facts) {
   const doors = [];
   let devBuildArm = false;
   for (const name of HOOK_FILES) {
-    const text = await readText(path.join(root, dir, name));
+    const text = await readText(path.resolve(root, dir, name));
     if (!text || !SCREEN_CALL_RE.test(text)) continue;
     doors.push(`${dir}/${name}`);
     if (text.includes(DEV_BUILD_ARM)) devBuildArm = true;
@@ -923,6 +923,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.`
@@ -960,7 +965,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_ID3,

package/dist/{chunk-UYCGP5BS.js → chunk-L4KIIKXI.js}

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 // package.json
 var package_default = {
-  version: "0.16.0"};
+  version: "0.19.0"};
 
 // src/version.ts
 var VERSION = package_default.version;

package/dist/{chunk-YQZDYDAK.js → chunk-U7BCBJIH.js}

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
 // src/pack/version.ts
-var PACK_VERSION = "12";
+var PACK_VERSION = "14";
 
 export { PACK_VERSION };

package/dist/{chunk-ANXGT7V3.js → chunk-ZCOIZVSM.js}

@@ -1,6 +1,7 @@
 #!/usr/bin/env node
-import { runAudit } from './chunk-UV3YIBDW.js';
+import { runAudit } from './chunk-KIPD3N77.js';
 import { readLedger } from './chunk-3E2IPCRY.js';
+import { checkClaudePointer, CLAUDE_AGENTS_FALLBACK_VERSION } from './chunk-DLHC7QON.js';
 import { DEFAULT_CONFIG, ETYMD_DIR } from './chunk-P6ATKV2R.js';
 import { readText, isDirectory, git, pathExists } from './chunk-4VPBP6K6.js';
 import os from 'os';
@@ -1005,8 +1006,8 @@ async function checkGuardedEmails(manifest, findings, disclosures) {
   }
 }
 async function checkGateDrift(manifest, findings, disclosures) {
-  const { planWorkflow } = await import('./generate-YEARCSHW.js');
-  const { scanProject } = await import('./scan-64Z6SNYF.js');
+  const { planWorkflow } = await import('./generate-6IPTCLYG.js');
+  const { scanProject } = await import('./scan-V53PGAQ6.js');
   const { readConfig } = await import('./config-724Y3IOB.js');
   for (const entry of manifest.entries) {
     const root = entry.resolvedRoot;
@@ -1024,8 +1025,13 @@ async function checkGateDrift(manifest, findings, disclosures) {
       );
       continue;
     }
-    const { config } = await readConfig(root);
-    const planned = (await planWorkflow(root, facts, { agents: false, gates: true, gateConfig: config.gates })).filter((f) => f.executable);
+    const { config, explicit } = await readConfig(root);
+    const planned = (await planWorkflow(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);
@@ -1061,6 +1067,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" ? finding(
+        `${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."
+      ) : finding(
+        `${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 = [];
@@ -1070,6 +1101,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) {

package/dist/cli.js

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { VERSION } from './chunk-UYCGP5BS.js';
+import { VERSION } from './chunk-L4KIIKXI.js';
 import path from 'path';
 import { Command } from 'commander';
 import pc from 'picocolors';
@@ -31,7 +31,7 @@ program.command("audit").description("Verify every instruction claim against the
   "exit non-zero when findings at/above this tier exist (risk|gap|polish)"
 ).action(
   (opts, cmd) => action(async () => {
-    const { run } = await import('./audit-HBNXNGD6.js');
+    const { run } = await import('./audit-RONSEYFS.js');
     await run({
       cwd: resolveCwd(cmd),
       json: opts.json,
@@ -44,7 +44,7 @@ program.command("audit").description("Verify every instruction claim against the
 );
 program.command("init").description("Onboard the truth guard: approve the baseline; scaffold AGENTS.md only if asked").option("-y, --yes", "accept defaults without prompting (never overwrites)").option("--with-agents", "also scaffold a minimal AGENTS.md where none exists (off by default)").action(
   (opts, cmd) => action(async () => {
-    const { run } = await import('./init-Z5O2WVRJ.js');
+    const { run } = await import('./init-7HWVHZMF.js');
     await run({ cwd: resolveCwd(cmd), yes: opts.yes, withAgents: opts.withAgents });
   })
 );
@@ -52,19 +52,19 @@ program.command("approve").description(
   "Re-approve the committed baseline after intentional structural changes (non-interactive)"
 ).action(
   (_opts, cmd) => action(async () => {
-    const { run } = await import('./approve-K5FFTPA4.js');
+    const { run } = await import('./approve-Y36ZO6IL.js');
     await run({ cwd: resolveCwd(cmd) });
   })
 );
 program.command("scan").description("Deterministically reckon the project into a facts index").option("--json", "print the raw facts as JSON").option("--no-save", "do not write the .etymd cache").action(
   (opts, cmd) => action(async () => {
-    const { run } = await import('./scan-H3NF5IV5.js');
+    const { run } = await import('./scan-DLKYG5BB.js');
     await run({ cwd: resolveCwd(cmd), json: opts.json, save: opts.save });
   })
 );
 program.command("doctor").description('Alias for `audit --truth` \u2014 "are the recorded instructions still true?"').option("--json", "print findings as JSON").action(
   (opts, cmd) => action(async () => {
-    const { run } = await import('./doctor-X6XAGKV7.js');
+    const { run } = await import('./doctor-EHRADIUZ.js');
     await run({ cwd: resolveCwd(cmd), json: opts.json });
   })
 );
@@ -76,7 +76,7 @@ program.command("context").description("Measure the always-loaded context footpr
 );
 program.command("brief").description("Emit a grounded briefing for the in-repo agent to complete the semantic layer").option("--human", "write a human onboarding brief instead of the agent briefing").action(
   (opts, cmd) => action(async () => {
-    const { run } = await import('./brief-DOQ2DQEG.js');
+    const { run } = await import('./brief-ILB6RMSQ.js');
     await run({ cwd: resolveCwd(cmd), human: opts.human });
   })
 );
@@ -90,7 +90,7 @@ program.command("premise").argument("[task]", "the task you are about to hand an
   "exit non-zero when findings at/above this tier exist (risk|gap|polish)"
 ).action(
   (task, opts, cmd) => action(async () => {
-    const { run } = await import('./premise-4QRU7LRI.js');
+    const { run } = await import('./premise-U6JIB2QG.js');
     await run({
       cwd: resolveCwd(cmd),
       task,
@@ -132,7 +132,7 @@ var fleet = program.command("fleet").description(
   "exit non-zero when findings at/above this tier exist (risk|gap|polish)"
 ).action(
   (opts, cmd) => action(async () => {
-    const { sweep } = await import('./fleet-UEFLKIRI.js');
+    const { sweep } = await import('./fleet-KFF3N2O7.js');
     await sweep({
       cwd: resolveCwd(cmd),
       manifest: opts.manifest,
@@ -147,7 +147,7 @@ var fleet = program.command("fleet").description(
 );
 fleet.command("check").description("Validate the manifest pair only \u2014 no lenses: dangling mappings, duplicates, leaks").option("--manifest <file>", "the fleet manifest \u2014 required unless the cwd holds registry.json").option("--json", "print the findings as JSON (EXPERIMENTAL through 0.2.x)").action(
   (_opts, cmd) => action(async () => {
-    const { check } = await import('./fleet-UEFLKIRI.js');
+    const { check } = await import('./fleet-KFF3N2O7.js');
     const opts = cmd.optsWithGlobals();
     await check({ cwd: resolveCwd(cmd), manifest: opts.manifest, json: opts.json });
   })
@@ -156,7 +156,7 @@ fleet.command("board").description(
   "Render the fleet board: every project's milestones (contract key `milestones`) plus a ranked initiatives table"
 ).option("--manifest <file>", "the fleet manifest \u2014 required unless the cwd holds registry.json").option("--initiatives <file>", "the hand-edited initiatives table (rank | id | initiative | \u2026)").option("--out <file>", "write the Markdown board here instead of printing it").option("--json", "print the board as JSON (EXPERIMENTAL)").action(
   (opts, cmd) => action(async () => {
-    const { board } = await import('./fleet-UEFLKIRI.js');
+    const { board } = await import('./fleet-KFF3N2O7.js');
     const shared = cmd.optsWithGlobals();
     await board({
       cwd: resolveCwd(cmd),
@@ -172,7 +172,7 @@ fleet.command("add").argument("<dir>", "directory of the project to register").d
   "public-repo | public-bound | private \u2014 mandatory for personal entries"
 ).option("-y, --yes", "skip prompts; every mandatory value must be passed as a flag").option("--manifest <file>", "the fleet manifest \u2014 required unless the cwd holds registry.json").action(
   (dir, opts, cmd) => action(async () => {
-    const { add } = await import('./fleet-UEFLKIRI.js');
+    const { add } = await import('./fleet-KFF3N2O7.js');
     const shared = cmd.optsWithGlobals();
     await add({
       cwd: resolveCwd(cmd),
@@ -195,7 +195,7 @@ fleet.command("dismiss").argument("<name>", "the registered project name").argum
   "Dismiss a project's finding from any cwd \u2014 guarded ledgers persist beside the manifest"
 ).requiredOption("--reason <text>", "why it is dismissed \u2014 recorded so the decision survives").option("--manifest <file>", "the fleet manifest \u2014 required unless the cwd holds registry.json").action(
   (name, id, _opts, cmd) => action(async () => {
-    const { dismiss } = await import('./fleet-UEFLKIRI.js');
+    const { dismiss } = await import('./fleet-KFF3N2O7.js');
     const opts = cmd.optsWithGlobals();
     await dismiss({
       cwd: resolveCwd(cmd),
@@ -210,7 +210,7 @@ fleet.command("accept").argument("<name>", "the registered project name").argume
   "Accept a project's finding as a known trade-off \u2014 guarded ledgers persist beside the manifest"
 ).option("--reason <text>", "optional note on why the trade-off is accepted").option("--manifest <file>", "the fleet manifest \u2014 required unless the cwd holds registry.json").action(
   (name, id, _opts, cmd) => action(async () => {
-    const { accept } = await import('./fleet-UEFLKIRI.js');
+    const { accept } = await import('./fleet-KFF3N2O7.js');
     const opts = cmd.optsWithGlobals();
     await accept({ cwd: resolveCwd(cmd), manifest: opts.manifest, name, id, reason: opts.reason });
   })
@@ -225,7 +225,7 @@ program.command("propose").description(
   "the fleet manifest \u2014 runs a read-only sweep now (no delta baseline move)"
 ).option("--from <file>", "read a stored `etymd fleet --json` output instead of sweeping").option("--json", "print the proposal/1 records as JSON (EXPERIMENTAL)").action(
   (opts, cmd) => action(async () => {
-    const { run } = await import('./propose-IKE4CUIM.js');
+    const { run } = await import('./propose-NZMEPZIL.js');
     await run({
       cwd: resolveCwd(cmd),
       manifest: opts.manifest,
@@ -242,7 +242,7 @@ program.command("screen").description(
   "fork's upstream remote: files byte-identical to its refs skip vocabulary-class patterns (secret patterns stay absolute)"
 ).action(
   (opts, cmd) => action(async () => {
-    const { run } = await import('./screen-E4FC7W5N.js');
+    const { run } = await import('./screen-S736DXQ5.js');
     const scope = opts.message ? "message" : opts.dir ? "dir" : opts.tree ? "tree" : "staged";
     await run({
       cwd: resolveCwd(cmd),
@@ -256,7 +256,7 @@ program.command("screen").description(
 );
 program.command("gates").description("Install the local git-hook gates (process \u2192 pre-commit, correctness \u2192 pre-push)").option("--ci", "note about the CI review gate (ships later; local gates install now)").option("-y, --yes", "skip prompts; never overwrites a hand-edited hook").action(
   (opts, cmd) => action(async () => {
-    const { run } = await import('./gates-NVWWKMT2.js');
+    const { run } = await import('./gates-UJ23THID.js');
     await run({ cwd: resolveCwd(cmd), ci: opts.ci, yes: opts.yes });
   })
 );

package/dist/{doctor-X6XAGKV7.js → doctor-EHRADIUZ.js}

@@ -1,13 +1,13 @@
 #!/usr/bin/env node
-import { run } from './chunk-FKDT4RBP.js';
-import './chunk-UV3YIBDW.js';
-import './chunk-Y4E6ERCM.js';
+import { run } from './chunk-4IESOWHQ.js';
+import './chunk-KIPD3N77.js';
+import './chunk-EYUW3UJU.js';
 import './chunk-3E2IPCRY.js';
 import './chunk-HI7NWPRA.js';
-import './chunk-EJM47PIF.js';
-import './chunk-UYCGP5BS.js';
+import './chunk-DLHC7QON.js';
+import './chunk-L4KIIKXI.js';
 import './chunk-P6ATKV2R.js';
-import './chunk-YQZDYDAK.js';
+import './chunk-U7BCBJIH.js';
 import './chunk-4VPBP6K6.js';
 
 // src/commands/doctor.ts

package/dist/{fleet-UEFLKIRI.js → fleet-KFF3N2O7.js}

@@ -1,14 +1,15 @@
 #!/usr/bin/env node
 import { dismiss, accept } from './chunk-HOR4M6EC.js';
-import { sweepFleet, FLEET_JSON_SCHEMA, checkManifest, FLEET_TRUST_VALUES, isFleetTrust, MILESTONES_FILE, parseMilestones, parseInitiatives, BOARD_JSON_SCHEMA, renderBoard, loadFleetManifest, fleetLedgerTarget, ensureFindingRecorded } from './chunk-ANXGT7V3.js';
-import './chunk-UV3YIBDW.js';
-import { parseFailOnTier, meetsFailOn } from './chunk-Y4E6ERCM.js';
+import { sweepFleet, FLEET_JSON_SCHEMA, checkManifest, FLEET_TRUST_VALUES, isFleetTrust, MILESTONES_FILE, parseMilestones, parseInitiatives, BOARD_JSON_SCHEMA, renderBoard, loadFleetManifest, fleetLedgerTarget, ensureFindingRecorded } from './chunk-ZCOIZVSM.js';
+import './chunk-KIPD3N77.js';
+import { parseFailOnTier, meetsFailOn } from './chunk-EYUW3UJU.js';
 import './chunk-3E2IPCRY.js';
+import { generateClaudePointerMd } from './chunk-HSRHOVII.js';
 import { print, theme, section, renderFleetRows, renderFleetNotes, renderFindings, TIER_BADGE, glyph } from './chunk-HI7NWPRA.js';
-import { scanProject } from './chunk-EJM47PIF.js';
-import './chunk-UYCGP5BS.js';
+import { checkClaudePointer, scanProject } from './chunk-DLHC7QON.js';
+import './chunk-L4KIIKXI.js';
 import './chunk-P6ATKV2R.js';
-import './chunk-YQZDYDAK.js';
+import './chunk-U7BCBJIH.js';
 import { readText, pathExists, git } from './chunk-4VPBP6K6.js';
 import { promises } from 'fs';
 import os from 'os';
@@ -234,6 +235,21 @@ async function add(opts) {
   if (manifest.entries.some((e) => e.name === name)) {
     throw new Error(`\`${name}\` is already registered \u2014 resolution is keyed by name`);
   }
+  const pointer = await checkClaudePointer(absTarget);
+  if (!pointer.ok && pointer.kind === "no-import") {
+    throw new Error(
+      `\`${name}\` has a CLAUDE.md that hides its AGENTS.md from Claude Code (${pointer.detail}). Add a full-line \`@AGENTS.md\` import to it, e.g.:
+
+${generateClaudePointerMd().trimEnd().split("\n").join("\n")}
+
+\u2014 or symlink either file to the other, or delete the CLAUDE.md \u2014 then re-run \`etymd fleet add\`.`
+    );
+  }
+  if (!pointer.ok) {
+    print(
+      `  ${theme.warn("note")} ${pointer.detail}. Update Claude Code, or add a CLAUDE.md containing \`@AGENTS.md\`.`
+    );
+  }
   const facts = await scanProject(absTarget);
   const remote = facts.git.isRepo ? await git(absTarget, ["remote", "get-url", "origin"]) : null;
   section(`Fleet add ${theme.dim(`\xB7 ${name} \xB7 ${absTarget}`)}`);