etymd 0.17.0 → 0.19.0

package/CHANGELOG.md

@@ -1,5 +1,62 @@
 # etymd
 
+## 0.19.0
+
+### Minor Changes
+
+- 29c7b31: The Claude Code pointer check follows Claude Code 2.1.277, which reads `AGENTS.md` when a
+  directory has no `CLAUDE.md`. A repo with `AGENTS.md` alone now passes and `fleet add` registers
+  it; it is reported (`claude-pointer-missing`, tier gap) only when the installed Claude Code is
+  older than 2.1.277, and `fleet add` prints a note instead of refusing. A `CLAUDE.md` that exists
+  without importing `@AGENTS.md` stays a risk and a refusal, because Claude Code reads that file
+  instead on every version. The version is read from `claude --version`; `ETYMD_CLAUDE_VERSION`
+  pins it, and `none` means no Claude Code on the machine.
+
+### Patch Changes
+
+- 3dd2683: Dependency advisories cleared inside the declared ranges. `vitest` 4.1.10 → 4.1.11 closes
+  GHSA-82fw-gwwq-j7x9 (moderate: path traversal / arbitrary file read through the `@vitest/mocker`
+  redirect mock), and `js-yaml` 4.3.1 → 4.3.2 with its transitive 3.15.1 → 3.15.2 closes
+  GHSA-2883-xcg3-v3hh (high: `maxTotalMergeKeys` does not limit CPU use for empty merge sources).
+  Both are dev-only — the test runner and the changeset tooling — so the published build is
+  byte-identical; the lockfile also picks up the range-satisfying refresh those two pull in.
+
+  One advisory stays open, and deliberately: GHSA-g7r4-m6w7-qqqr (low: `esbuild` allows an arbitrary
+  file read when its development server runs on Windows) is fixed in esbuild 0.28.1, while `tsup`
+  8.5.1 — the newest release — declares `esbuild: ^0.27.0`, so no in-range version of esbuild carries
+  the fix. The only automatic fix on offer is a downgrade to esbuild 0.27.2, which gives up five
+  patch releases to dodge a dev-server path this repo never takes: the build runs tsup, never an
+  esbuild server. It clears once tsup widens its range.
+
+- 7d4e81f: `core.hooksPath` is read the way git reads it: a repo-relative path, an absolute path and a `~`
+  path can all name one directory, and the directory is the fact. An absolute path to the tracked
+  `.githooks/` now scans as `githooks` (wired) instead of `custom`, and the hooks are read from the
+  directory git actually runs — the literal-string comparison had also joined the absolute path
+  onto the repo root and looked for hooks at a path that does not exist, so a working pre-push gate
+  could read as absent. The fact is recorded repo-relative whenever the directory sits inside the
+  worktree, so a committed baseline never carries a machine path; a hooks directory outside the
+  repo stays absolute and is disclosed as `custom`.
+
+## 0.18.0
+
+### Minor Changes
+
+- 41b91f6: Generated pre-push hooks preserve long filenames, whitespace, quotes, and leading
+  hyphens during shell-script discovery and checking, and a name carrying shell metacharacters
+  reaches the scan as data, never as code. Discovery fails closed instead of reporting success
+  with incomplete coverage: failed enumeration blocks, and a tracked regular file that exists
+  but cannot be read blocks, naming the file. Tracked paths with nothing readable behind them —
+  submodule entries, dangling symlinks, files deleted from the worktree while still tracked —
+  are counted and disclosed as skipped rather than blocking, so a submodule can no longer wedge
+  every push. Shebang reads are bounded to the first 4 KiB of the first line, so a large binary
+  cannot be copied into the gate's scratch file on every push and a shebang embedded deeper in
+  a document no longer drags the whole document into the checker. Regenerate existing hooks
+  with `etymd gates --yes` to apply the correction.
+- 4a92435: The shebang classifier ships as a tracked, shebanged helper beside the hook
+  (`.githooks/discover-shell-scripts.sh`), so the scan it implements finds and checks it too —
+  the gate covers its own classifier, and the hook's most intricate code is lintable on its
+  own lines.
+
 ## 0.17.0
 
 ### Minor Changes

package/README.md

@@ -174,7 +174,7 @@ personal and guarded repos. See [the fleet manifest](#the-fleet-manifest-experim
 | Command                          | What it does                                                                                                                                                                                                                                                        |
 | -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `etymd audit`                    | Verify every claim; ranked findings (risk → gap → polish) + ledger diff. `--lens`, `--truth`, `--json`, `--no-ledger`, `--fail-on <tier>`.                                                                                                                          |
-| `etymd init`                     | Onboard: approve the committed baseline; scaffold a minimal AGENTS.md **only if missing**. Never overwrites.                                                                                                                                                        |
+| `etymd init`                     | Onboard: approve the committed baseline; scaffold a minimal AGENTS.md **only if missing**, with its `CLAUDE.md` pointer. Never overwrites.                                                                                                                          |
 | `etymd doctor`                   | Alias for `audit --truth`.                                                                                                                                                                                                                                          |
 | `etymd context`                  | The economy view: per-file always-loaded footprint + extraction candidates.                                                                                                                                                                                         |
 | `etymd gates`                    | Install local git-hook gates (pre-commit / commit-msg / pre-push, plus a publish screen where something ships) built from your own check scripts — and from the repo's shell surface, where it has one.                                                             |
@@ -188,7 +188,7 @@ personal and guarded repos. See [the fleet manifest](#the-fleet-manifest-experim
 | `etymd accept`                   | `accept <id>` — record a finding as accepted reality; visible in the ledger, out of the report.                                                                                                                                                                     |
 | `etymd fleet`                    | Sweep every project in a fleet manifest: read-only per-repo audits + manifest/wall checks. `--manifest`, `--only`, `--profile`, `--truth`, `--persist-ledgers`, `--json`, `--fail-on`.                                                                              |
 | `etymd fleet check`              | Validate the manifest pair alone (no lenses): dangling mappings, duplicate names, privacy leaks, undeclared trust, machine paths. Non-zero exit on any finding.                                                                                                     |
-| `etymd fleet add`                | `add <dir>` — register a project: scans it, asks for what no scan can derive, and refuses to write an entry missing a mandatory field. `--name`, `--kind`, `--profile`, `--trust`, `-y`.                                                                            |
+| `etymd fleet add`                | `add <dir>` — register a project: scans it, asks for what no scan can derive, and refuses to write an entry missing a mandatory field, or a repo whose `AGENTS.md` Claude Code cannot see. `--name`, `--kind`, `--profile`, `--trust`, `-y`.                        |
 | `etymd fleet board`              | Render the fleet board: every project's `MILESTONES.md` (contract key `milestones`, shape-checked by the sweep) plus a ranked initiatives table on one page. `--initiatives <file>`, `--out <file>`, `--json`.                                                      |
 | `etymd propose`                  | Score the sweep's improvement findings + recurring classes against a fleet-authored rubric — stable `proposal/1` records, read-only, deterministic, guarded entries excluded. `--rubric <file>` (required), `--manifest <file>` or `--from <fleet.json>`, `--json`. |
 | `etymd fleet dismiss` / `accept` | `<name> <id>` — resolve a project's finding from any cwd; guarded findings persist beside the manifest, never in the guarded worktree.                                                                                                                              |
@@ -520,7 +520,11 @@ Two fields the scan can never derive, so the manifest must declare them:
 
 `etymd fleet add <dir>` is the gate that keeps both true: it scans the project, prompts for what
 no scan can derive, and **refuses to write an incomplete entry**. Non-interactive runs (`--yes`,
-CI) must pass every mandatory value as a flag — there is deliberately no default.
+CI) must pass every mandatory value as a flag — there is deliberately no default. It also refuses
+a repo whose `CLAUDE.md` hides its `AGENTS.md`: Claude Code reads `CLAUDE.md` when one exists and
+falls back to `AGENTS.md` (from 2.1.277) only when none does, so a `CLAUDE.md` must import
+`@AGENTS.md` or be a symlink to it — the refusal prints the fix. A repo with `AGENTS.md` alone
+registers; on a Claude Code older than 2.1.277 it gets a note, since that version cannot see it.
 
 How the sweep behaves:
 
@@ -543,8 +547,9 @@ How the sweep behaves:
 - **Wall checks.** Guarded contract files found inside a guarded worktree, unregistered checkouts
   under the fleet root whose remotes match `guardedHosts`, tracked `/Users/` paths in the manifest
   repo, private **needles** — the identifiers the local file holds (labels, dir names, hosts) —
-  inside `trust: "public-repo"` entries, and guarded-host commit emails on personal entries — each
-  a risk finding; each check that cannot run is disclosed.
+  inside `trust: "public-repo"` entries, guarded-host commit emails on personal entries, and
+  repos whose `AGENTS.md` no `CLAUDE.md` pointer or symlink makes visible to Claude Code
+  (`claude-pointer-missing`) — each a risk finding; each check that cannot run is disclosed.
 - **No global pointer.** `--manifest` is required unless the cwd holds `registry.json` — there
   is deliberately no env var and no home-directory pointer.
 - **Milestones and the fleet board.** A project declares its plan in one file — `MILESTONES.md`,

package/dist/{approve-VN4EDBR5.js → approve-Y36ZO6IL.js}

@@ -1,9 +1,9 @@
 #!/usr/bin/env node
 import { section, theme, print, renderBaselineDrift, glyph } from './chunk-HI7NWPRA.js';
-import { scanProject } from './chunk-446EZNAQ.js';
-import { VERSION } from './chunk-BUMOGHQA.js';
+import { scanProject } from './chunk-DLHC7QON.js';
+import { VERSION } from './chunk-L4KIIKXI.js';
 import { readBaseline, summarizeBaselineDrift, isDriftEmpty, writeBaseline, deriveProfile } from './chunk-P6ATKV2R.js';
-import { PACK_VERSION } from './chunk-YQZDYDAK.js';
+import { PACK_VERSION } from './chunk-U7BCBJIH.js';
 import './chunk-4VPBP6K6.js';
 
 // src/commands/approve.ts

package/dist/audit-RONSEYFS.js

@@ -0,0 +1,11 @@
+#!/usr/bin/env node
+export { run } from './chunk-4IESOWHQ.js';
+import './chunk-KIPD3N77.js';
+import './chunk-EYUW3UJU.js';
+import './chunk-3E2IPCRY.js';
+import './chunk-HI7NWPRA.js';
+import './chunk-DLHC7QON.js';
+import './chunk-L4KIIKXI.js';
+import './chunk-P6ATKV2R.js';
+import './chunk-U7BCBJIH.js';
+import './chunk-4VPBP6K6.js';

package/dist/{brief-7MWP35UI.js → brief-ILB6RMSQ.js}

@@ -1,9 +1,9 @@
 #!/usr/bin/env node
 import { print, theme } from './chunk-HI7NWPRA.js';
-import { scanProject } from './chunk-446EZNAQ.js';
-import './chunk-BUMOGHQA.js';
+import { scanProject } from './chunk-DLHC7QON.js';
+import './chunk-L4KIIKXI.js';
 import { ETYMD_DIR } from './chunk-P6ATKV2R.js';
-import './chunk-YQZDYDAK.js';
+import './chunk-U7BCBJIH.js';
 import './chunk-4VPBP6K6.js';
 import { promises } from 'fs';
 import path from 'path';

package/dist/{chunk-ANFNXFRI.js → chunk-4IESOWHQ.js}

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
-import { runAudit } from './chunk-WKP7M2B3.js';
-import { parseFailOnTier, meetsFailOn } from './chunk-FNA4R5KT.js';
+import { runAudit } from './chunk-KIPD3N77.js';
+import { parseFailOnTier, meetsFailOn } from './chunk-EYUW3UJU.js';
 import { print, section, theme, renderLensCoverage, renderFindings, renderLedgerDiff } from './chunk-HI7NWPRA.js';
 
 // src/commands/audit.ts

package/dist/{chunk-446EZNAQ.js → chunk-DLHC7QON.js}

@@ -1,9 +1,11 @@
 #!/usr/bin/env node
-import { VERSION } from './chunk-BUMOGHQA.js';
-import { PACK_VERSION } from './chunk-YQZDYDAK.js';
-import { normalizeRelPath, isDirectory, readJson, git, matchesAnyGlob, pathExists, readText } from './chunk-4VPBP6K6.js';
+import { VERSION } from './chunk-L4KIIKXI.js';
+import { PACK_VERSION } from './chunk-U7BCBJIH.js';
+import { normalizeRelPath, isDirectory, pathExists, readText, readJson, git, matchesAnyGlob } from './chunk-4VPBP6K6.js';
 import path from 'path';
+import { execFile } from 'child_process';
 import { promises } from 'fs';
+import { promisify } from 'util';
 
 var IGNORED_DIRS = /* @__PURE__ */ new Set([
   "node_modules",
@@ -265,10 +267,17 @@ async function hasLintStagedConfig(root, pkg) {
   }
   return false;
 }
+function normalizeHooksPath(root, raw) {
+  const abs = path.resolve(root, raw);
+  const rel = path.relative(root, abs);
+  const outside = path.isAbsolute(rel) || rel === ".." || rel.startsWith(`..${path.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 = path.join(root, ".husky");
       return {
         source: "husky",
@@ -279,10 +288,10 @@ async function detectHooks(root, hooksPath, pkg) {
         lintStaged
       };
     }
-    const base = path.join(root, hooksPath);
+    const base = path.resolve(root, dir);
     return {
-      source: hooksPath === ".githooks" ? "githooks" : "custom",
-      dir: hooksPath,
+      source: dir === ".githooks" ? "githooks" : "custom",
+      dir,
       preCommit: await pathExists(path.join(base, "pre-commit")),
       prePush: await pathExists(path.join(base, "pre-push")),
       commitMsg: await pathExists(path.join(base, "commit-msg")),
@@ -438,6 +447,69 @@ async function detectArtifacts(root) {
   });
   return artifacts;
 }
+var ROOT_POINTER_IMPORT_RE = /^\s*@(\.\/)?AGENTS\.md\s*$/m;
+var DOT_CLAUDE_IMPORT_RE = /^\s*@\.\.\/AGENTS\.md\s*$/m;
+var CLAUDE_AGENTS_FALLBACK_VERSION = "2.1.277";
+var pExecFile = promisify(execFile);
+var claudeVersionMemo;
+function detectClaudeCodeVersion() {
+  const override = process.env.ETYMD_CLAUDE_VERSION;
+  if (override !== void 0) {
+    return Promise.resolve(override === "none" || override === "" ? null : override);
+  }
+  claudeVersionMemo ??= pExecFile("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 = path.join(root, "AGENTS.md");
+  const claudeAbs = path.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(path.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 = claudeVersion === void 0 ? await detectClaudeCodeVersion() : claudeVersion;
+  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) => {
@@ -558,11 +630,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);
@@ -602,4 +675,4 @@ async function scanProject(root, opts = {}) {
   };
 }
 
-export { expandFileGlobs, scanProject };
+export { CLAUDE_AGENTS_FALLBACK_VERSION, checkClaudePointer, expandFileGlobs, scanProject };

package/dist/{chunk-FNA4R5KT.js → chunk-EYUW3UJU.js}

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { expandFileGlobs } from './chunk-446EZNAQ.js';
+import { expandFileGlobs } from './chunk-DLHC7QON.js';
 import { DEFAULT_CONFIG, CONFIG_FILE } from './chunk-P6ATKV2R.js';
 import { readText, isDirectory, matchesAnyGlob, normalizeRelPath, readJson, pathExists, git } from './chunk-4VPBP6K6.js';
 import path3 from 'path';
@@ -439,10 +439,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) {
@@ -476,14 +479,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;
@@ -496,8 +506,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]);
@@ -506,13 +520,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(" ")
@@ -582,12 +598,14 @@ async function buildTruthEnv(root, facts) {
     for (const key of Object.keys(pkgJson?.scripts ?? {})) knownScripts.add(key);
   }
   const bases = [root, ...facts.packages.map((p) => path3.join(root, p.dir))];
-  const pathResolves = async (claim) => {
+  const pathResolves = async (claim, fromDir) => {
     for (const base of bases) {
       if (await pathExists(path3.join(base, claim))) return true;
       if (await pathExists(path3.join(base, "src", claim))) return true;
       if (await pathExists(path3.join(base, "scripts", claim))) return true;
     }
+    if (fromDir && fromDir !== "." && await pathExists(path3.join(root, fromDir, claim)))
+      return true;
     return false;
   };
   const binResolves = async (name) => {
@@ -617,6 +635,7 @@ function emptyCounters() {
     unverifiableCommands: 0,
     gitignoredSkipped: 0,
     prospectiveSkipped: 0,
+    fetchedSkipped: 0,
     placeholderSkipped: 0,
     qualifiedRefsSkipped: 0,
     unresolvableRefs: 0,
@@ -659,19 +678,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 = path3.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(path3.dirname(dirClaim));
+    }
+  }
+  const missing = [];
+  for (const claim of unresolved) {
+    let anchored = false;
+    for (const base of proseBases) {
+      if (await pathExists(path3.join(env.root, base, claim))) anchored = true;
+      else if (fromDir !== "." && await pathExists(path3.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)) {
@@ -780,4 +828,4 @@ function checkDecisionRefs(file, ledger, opts, counters) {
   return { findings, examined };
 }
 
-export { KNOWN_EXTENSIONS, NAMESPACE_IDENT, NAMESPACE_STOP, PATH_TOKEN_RE, buildTruthEnv, checkDecisionRefs, checkDocRefs, checkTextClaims, emptyCounters, listInstructionFiles, listStateDocuments, loadDecisionLedger, meetsFailOn, packageManagerUsage, parseFailOnTier, rankFindings, stateFreshnessLens };
+export { HOSTNAME_RE, KNOWN_EXTENSIONS, NAMESPACE_IDENT, NAMESPACE_STOP, PATH_TOKEN_RE, buildTruthEnv, checkDecisionRefs, checkDocRefs, checkTextClaims, emptyCounters, listInstructionFiles, listStateDocuments, loadDecisionLedger, meetsFailOn, packageManagerUsage, parseFailOnTier, rankFindings, stateFreshnessLens };

package/dist/chunk-EZRK4MV3.js

@@ -0,0 +1,109 @@
+#!/usr/bin/env node
+import { isSafeGateCommand, generateAgentsMd, generateClaudePointerMd, isSelfBuildRepo, generatePreCommitHook, generateCommitMsgHook, generatePrePushHook, generateShellDiscoveryScript, generateArtifactCheckScript, fileOrigin } from './chunk-HSRHOVII.js';
+import { DEFAULT_CONFIG } from './chunk-P6ATKV2R.js';
+import { readText, pathExists } from './chunk-4VPBP6K6.js';
+import path from 'path';
+
+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)");
+    await add("CLAUDE.md", generateClaudePointerMd(), "Claude Code pointer to AGENTS.md");
+  }
+  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 ?? []
+    };
+    const tier = deriveFailOn(facts, {
+      failOn: gateConfig.failOn,
+      explicit: opts.gateFailOnPinned ?? false
+    });
+    await add(
+      ".githooks/pre-push",
+      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",
+        generateArtifactCheckScript(selfBuild),
+        "Content screen (published artifact)",
+        true
+      );
+    }
+  }
+  return out;
+}
+
+export { deriveFailOn, derivedCommands, planWorkflow, riskReachability };