hypomnema 1.6.2 → 1.7.0

package/scripts/lib/hypo-ignore.mjs

@@ -1,5 +1,5 @@
 import { existsSync, readFileSync } from 'fs';
-import { join, relative, basename } from 'path';
+import { join, relative, basename, resolve } from 'path';
 
 export function loadHypoIgnore(hypoDir) {
   const ignorePath = join(hypoDir, '.hypoignore');
@@ -10,6 +10,46 @@ export function loadHypoIgnore(hypoDir) {
     .filter((l) => l && !l.startsWith('#'));
 }
 
+// .hyposcanignore: scan-only exclusions (lint/graph/stats/query/verify/doctor
+// catalog scans). Deliberately NOT a privacy boundary: a match here is still
+// committed and still readable by hooks. Only isScanIgnored() below reads this
+// file. loadHypoIgnore()/isIgnored() must never see it, that is the whole
+// point of the split, so do not thread it into the pre-commit gate or
+// ingest --check.
+export function loadScanIgnore(hypoDir) {
+  const ignorePath = join(resolve(hypoDir), '.hyposcanignore');
+  if (!existsSync(ignorePath)) return [];
+  return readFileSync(ignorePath, 'utf-8')
+    .split('\n')
+    .map((l) => l.trim())
+    .filter((l) => l && !l.startsWith('#'));
+}
+
+// Parsed .hyposcanignore patterns, cached per vault for the process lifetime.
+// The shared walker (wikilink.mjs) calls isScanIgnored() once per directory
+// entry, so re-reading this file on every call would turn a vault scan into
+// O(files) filesystem reads for one small file. Nothing writes
+// .hyposcanignore mid-process, so a stale cache is not a real scenario.
+//
+// Keyed on path.resolve(hypoDir), NOT the raw argument: a raw-string key lets
+// two different relative spellings of the SAME vault ('.', './') miss each
+// other (harmless, just a wasted read), but it also lets a relative key like
+// '.' collide ACROSS vaults when the caller cd's between them between calls —
+// vault B would silently reuse vault A's scan patterns. Resolving to an
+// absolute path first makes the key vault-identity-stable regardless of cwd
+// or spelling.
+const scanIgnoreCache = new Map();
+
+function cachedScanIgnore(hypoDir) {
+  const key = resolve(hypoDir);
+  let patterns = scanIgnoreCache.get(key);
+  if (patterns === undefined) {
+    patterns = loadScanIgnore(key);
+    scanIgnoreCache.set(key, patterns);
+  }
+  return patterns;
+}
+
 function globToRegex(glob) {
   return new RegExp(
     '^' +
@@ -39,12 +79,20 @@ export function isGeneratedArtifact(filePath, hypoDir) {
 }
 
 // Catalog/scan exclusion = privacy/.hypoignore patterns PLUS generated root
-// artifacts. Use this in tools that build the knowledge catalog (lint, graph,
-// stats, query, verify, crystallize, rename, doctor broken-links). Do NOT use it
-// in the pre-commit gate or ingest --check, which are privacy boundaries that
-// must stay on isIgnored()/.hypoignore alone.
+// artifacts PLUS scan-only/.hyposcanignore patterns (loaded and cached
+// internally, so callers keep passing only their privacy `patterns` array).
+// Use this in tools that build the knowledge catalog (lint, graph, stats,
+// query, verify, crystallize, rename, doctor broken-links). Do NOT use it in
+// the pre-commit gate or ingest --check, which are privacy boundaries that
+// must stay on isIgnored()/.hypoignore alone — OR-ing in .hyposcanignore here
+// only ever WIDENS what a scan skips, it can never make an .hypoignore match
+// committable, so that separation holds by construction.
 export function isScanIgnored(filePath, hypoDir, patterns) {
-  return isIgnored(filePath, hypoDir, patterns) || isGeneratedArtifact(filePath, hypoDir);
+  return (
+    isIgnored(filePath, hypoDir, patterns) ||
+    isGeneratedArtifact(filePath, hypoDir) ||
+    isIgnored(filePath, hypoDir, cachedScanIgnore(hypoDir))
+  );
 }
 
 export function isIgnored(filePath, hypoDir, patterns) {

package/scripts/lib/hypo-root.mjs

@@ -26,13 +26,20 @@ export function expandHome(p) {
 }
 
 /**
- * Resolve the Hypomnema root directory.
+ * Resolve the Hypomnema root directory, along with how it was resolved.
  * Checks HYPO_DIR env → hypo-config.md scan → ~/hypomnema default.
- * @returns {string} absolute path to Hypomnema root
+ *
+ * The `source` lets a caller tell "the user pointed us somewhere and it's
+ * empty" (an explicit misconfiguration worth failing loud on) apart from
+ * "nobody configured anything and none of the usual spots had a vault
+ * either" (a silent fallback, worth a quiet notice at most). resolveHypoRoot()
+ * itself collapses both into the same path, on purpose, for every caller that
+ * only ever wants a directory to hand to fs calls.
+ * @returns {{ root: string, source: 'env'|'marker'|'default' }}
  */
-export function resolveHypoRoot() {
+export function resolveHypoRootInfo() {
   if (process.env.HYPO_DIR) {
-    return expandHome(process.env.HYPO_DIR);
+    return { root: expandHome(process.env.HYPO_DIR), source: 'env' };
   }
 
   const candidates = [
@@ -46,8 +53,51 @@ export function resolveHypoRoot() {
   ];
 
   for (const c of candidates) {
-    if (existsSync(join(c, 'hypo-config.md'))) return c;
+    if (existsSync(join(c, 'hypo-config.md'))) return { root: c, source: 'marker' };
+  }
+
+  return { root: join(HOME, 'hypomnema'), source: 'default' };
+}
+
+/**
+ * Resolve the Hypomnema root directory.
+ * Checks HYPO_DIR env → hypo-config.md scan → ~/hypomnema default.
+ * @returns {string} absolute path to Hypomnema root
+ */
+export function resolveHypoRoot() {
+  return resolveHypoRootInfo().root;
+}
+
+/**
+ * Validate a resolved root against the hypo-config.md marker, for the
+ * read-only CLIs only (lint/stats/graph/query). Two failure classes need
+ * different loudness:
+ *   - `source === 'env'`: the caller pointed HYPO_DIR at a path with no
+ *     vault there — an explicit misconfiguration. Fail loud: stderr + exit 1.
+ *   - `source === 'default'` (or a stale `'marker'` hit): nobody configured
+ *     anything and none of the usual spots had a vault. CI (lint-runner,
+ *     release.yml) intentionally runs this way and must keep exiting 0 — but
+ *     the CLI must stop silently reporting "no issues found" / "no results"
+ *     as if it had actually scanned a wiki. Print a visible notice and tell
+ *     the caller, so it can adjust its own empty-result copy, then continue.
+ * A caller that received `hypoDir` from an explicit --hypo-dir=<path> flag
+ * (tests, other tooling) never calls this — that path is not auto-resolved
+ * and is trusted as-is, valid or not.
+ * @param {string} root
+ * @param {'env'|'marker'|'default'} source
+ * @returns {boolean} true when the vault is missing (caller should suppress
+ *   its own "nothing found" messaging in favor of this notice already
+ *   printed); false when a real vault was found and normal scanning should
+ *   proceed.
+ */
+export function checkVaultOrExit(root, source) {
+  if (existsSync(join(root, 'hypo-config.md'))) return false;
+
+  if (source === 'env') {
+    console.error(`Hypomnema vault not found at HYPO_DIR=${root} (no hypo-config.md).`);
+    process.exit(1);
   }
 
-  return join(HOME, 'hypomnema');
+  console.error('No Hypomnema vault found. Set HYPO_DIR or run inside a vault; nothing to scan.');
+  return true;
 }

package/scripts/lib/page-usage.mjs

@@ -11,6 +11,7 @@ import { readFileSync, existsSync } from 'fs';
 import { join } from 'path';
 import { collectPagesCrystallize, extractWikilinks, slugForms } from './wikilink.mjs';
 import { parseFrontmatter } from './frontmatter.mjs';
+import { currentDevice, scopeVisible, readVisibilityScope } from '../../hooks/hypo-shared.mjs';
 
 const PAGE_USAGE_REL = '.cache/page-usage.jsonl';
 const DAY_MS = 86400000;
@@ -69,7 +70,13 @@ export function readPageUsage(hypoDir) {
 // within the last thresholdDays.
 export function aggregateColdCandidates(
   hypoDir,
-  { thresholdDays = 90, minLogSpanDays = 14, now = Date.now(), ignorePatterns = [] } = {},
+  {
+    thresholdDays = 90,
+    minLogSpanDays = 14,
+    now = Date.now(),
+    ignorePatterns = [],
+    device = currentDevice(),
+  } = {},
 ) {
   const records = readPageUsage(hypoDir);
   if (records.length === 0) return { status: 'insufficient-data', reason: 'no-records' };
@@ -110,6 +117,7 @@ export function aggregateColdCandidates(
       title: fm.title || slug,
       forms: formSet(slug),
       links: extractWikilinks(body),
+      scope: readVisibilityScope(content),
     });
   }
 
@@ -134,7 +142,12 @@ export function aggregateColdCandidates(
   }
 
   const candidates = pageList
-    .filter((p) => hasInbound.has(p.slug) && !intersects(p.forms, recentForms))
+    .filter(
+      (p) =>
+        hasInbound.has(p.slug) &&
+        !intersects(p.forms, recentForms) &&
+        scopeVisible(p.scope, device),
+    )
     .map((p) => ({ slug: p.slug, title: p.title }));
 
   return { status: 'ok', candidates };

package/scripts/lib/pkg-json.mjs

@@ -75,3 +75,43 @@ export function writePkgJsonAtomic(pkgJsonPath, data) {
     throw err;
   }
 }
+
+// Non-mutating read of the version a candidate install root's own package.json
+// carries, or null. Shared by writeDualSkipProvenance (what to stamp) and
+// upgrade.mjs's read-only report (what to preview/display) so both agree.
+export function readVersionAtRoot(root) {
+  try {
+    const v = JSON.parse(readFileSync(join(root, 'package.json'), 'utf-8')).version;
+    return typeof v === 'string' && v.length > 0 ? v : null;
+  } catch {
+    return null;
+  }
+}
+
+// Dual-install self-heal: writes a NARROW provenance correction to
+// pkgJsonPath, pointing pkgRoot/pkgVersion at the plugin registry's own
+// resolved root/version, while preserving every other existing field
+// (including a prior `commands` map — that map reflects the PLUGIN's own
+// install, not the caller's own run, so unlike a full plugin-mode metadata
+// write it must NOT be dropped or touched here).
+//
+// TOCTOU guard: the caller (upgrade.mjs) resolves `registryRoot` as usable via
+// a SEPARATE earlier read (resolveEnabledPluginRoot / usablePkgRoot) — that
+// root's own package.json can vanish or corrupt between that resolution and
+// this write. Re-reads the version HERE and refuses the correction outright if
+// it cannot, rather than stamp a NEW pkgRoot with a STALE version (the old
+// recorded one, or none): a wrong root+version pairing is worse than no
+// correction. Returns false without writing anything when refused — the
+// existing metadata is left exactly as it was, and the caller must not report
+// this as "corrected".
+export function writeDualSkipProvenance(pkgJsonPath, registryRoot) {
+  const registryVersion = readVersionAtRoot(registryRoot);
+  if (!registryVersion) return false;
+  const existing = readPkgJson(pkgJsonPath);
+  writePkgJsonAtomic(pkgJsonPath, {
+    ...existing,
+    pkgRoot: registryRoot,
+    pkgVersion: registryVersion,
+  });
+  return true;
+}

package/scripts/lib/plugin-detect.mjs

@@ -15,7 +15,8 @@
 // legacy `hypomnema@<marketplace>` key in `enabledPlugins` until they reinstall
 // as `hypo@<marketplace>`, and the guard must hold across that gap.
 
-import { readFileSync } from 'node:fs';
+import { readFileSync, existsSync } from 'node:fs';
+import { isAbsolute, join } from 'node:path';
 
 /**
  * @param {string} settingsPath  path to a Claude Code settings.json (e.g. ~/.claude/settings.json)
@@ -38,11 +39,18 @@ export function isHypomnemaPluginEnabled(settingsPath) {
   }
   if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) return false;
 
-  const enabled = parsed.enabledPlugins;
+  return enabledKeyFrom(parsed.enabledPlugins) !== null;
+}
+
+// The exact enabledPlugins KEY (`hypo@<marketplace>` / legacy
+// `hypomnema@<marketplace>`) whose value is strictly true, or null. Same matching
+// rules as isHypomnemaPluginEnabled, but returns the identifier so a caller can
+// look that exact plugin up in the install registry rather than guessing among all
+// hypo-named entries.
+function enabledKeyFrom(enabled) {
   // enabledPlugins is an object map `{ "<name>@<marketplace>": true|false }`.
   // Anything else (absent, array, scalar) → not enabled.
-  if (!enabled || typeof enabled !== 'object' || Array.isArray(enabled)) return false;
-
+  if (!enabled || typeof enabled !== 'object' || Array.isArray(enabled)) return null;
   for (const [key, value] of Object.entries(enabled)) {
     if (value !== true) continue; // strictly true only — no truthy coercion
     // Require a real `name@marketplace` shape: an `@` that is neither the first
@@ -54,7 +62,89 @@ export function isHypomnemaPluginEnabled(settingsPath) {
     const name = key.slice(0, at);
     // Match the current plugin name and the legacy one (pre-rename) so the
     // guard holds across the migration window. Exact, case-sensitive.
-    if (name === 'hypo' || name === 'hypomnema') return true;
+    if (name === 'hypo' || name === 'hypomnema') return key;
+  }
+  return null;
+}
+
+/**
+ * @param {string} settingsPath  path to a Claude Code settings.json
+ * @returns {string|null} the exact `enabledPlugins` key of the enabled Hypomnema
+ *   plugin (`hypo@<marketplace>` or legacy `hypomnema@<marketplace>`), or null.
+ */
+export function enabledHypomnemaPluginKey(settingsPath) {
+  let raw;
+  try {
+    raw = readFileSync(settingsPath, 'utf-8');
+  } catch {
+    return null;
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    return null;
+  }
+  if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) return null;
+  return enabledKeyFrom(parsed.enabledPlugins);
+}
+
+function readPkgVersionAt(root) {
+  try {
+    const v = JSON.parse(readFileSync(join(root, 'package.json'), 'utf-8')).version;
+    return typeof v === 'string' && v.length > 0 ? v : null;
+  } catch {
+    return null;
+  }
+}
+
+// A pkgRoot is "usable" as a DURABLE install root only if it is an ABSOLUTE path to
+// a real package directory whose package.json carries a version. A relative path
+// (e.g. installPath ".") would be resolved against the caller's cwd and break the
+// vault git hook from any other directory; a version-less package.json cannot be
+// attributed a version without lying. A bare path that merely exists is a pointer
+// the runtime cannot resolve scripts through. Shared by init's registry resolution,
+// its durable-root fallback, and upgrade's dualSkip provenance correction so they
+// all agree on what is real.
+export function usablePkgRoot(pkgRoot) {
+  return (
+    typeof pkgRoot === 'string' &&
+    pkgRoot.length > 0 &&
+    isAbsolute(pkgRoot) &&
+    existsSync(join(pkgRoot, 'package.json')) &&
+    readPkgVersionAt(pkgRoot) !== null
+  );
+}
+
+// Resolve the enabled Hypomnema plugin's REAL install root from the plugin
+// registry (~/.claude/plugins/installed_plugins.json). POSITIVE attribution: it
+// looks up the EXACT key that settingsPath marks enabled (via
+// enabledHypomnemaPluginKey), not just any hypo-named entry — a disabled legacy or
+// other-marketplace entry must never be selected. Among that key's registry
+// entries it prefers the user-scope install (the one a plugin-enabled user runs),
+// falling back to any usable entry. Returns a usable absolute install root, or
+// null when the registry is absent/unreadable, names no entry for the enabled key,
+// or that entry is not a usable package dir. Fails open (null) on every
+// uncertainty — callers must treat null as "cannot positively resolve", never as
+// "resolved to nothing usable exists".
+export function resolveEnabledPluginRoot(settingsPath, registryPath) {
+  const key = enabledHypomnemaPluginKey(settingsPath);
+  if (!key) return null;
+  let reg;
+  try {
+    reg = JSON.parse(readFileSync(registryPath, 'utf-8'));
+  } catch {
+    return null;
   }
-  return false;
+  const plugins =
+    reg && typeof reg.plugins === 'object' && !Array.isArray(reg.plugins) ? reg.plugins : null;
+  const entries = plugins && Array.isArray(plugins[key]) ? plugins[key] : null;
+  if (!entries) return null;
+  const paths = (scope) =>
+    entries
+      .filter((e) => e && (scope === undefined || e.scope === scope))
+      .map((e) => (typeof e.installPath === 'string' ? e.installPath : null))
+      .filter((p) => usablePkgRoot(p));
+  // Prefer the user-scope install, then any usable entry for this exact key.
+  return paths('user')[0] ?? paths(undefined)[0] ?? null;
 }

package/scripts/lib/wd-match.mjs

@@ -72,7 +72,12 @@ function lastSegment(p) {
  * @returns {string|null} matched slug, or null when nothing matches.
  */
 export function pickProjectByCwd(projects, cwd, opts = {}) {
-  const { eligible = null, realpathCwd = null, caseInsensitive = isCaseInsensitiveFs() } = opts;
+  const {
+    eligible = null,
+    realpathCwd = null,
+    caseInsensitive = isCaseInsensitiveFs(),
+    rejectAmbiguous = false,
+  } = opts;
   if (!cwd && !realpathCwd) return null;
 
   const eligibleSet = eligible ? new Set(eligible) : null;
@@ -98,19 +103,32 @@ export function pickProjectByCwd(projects, cwd, opts = {}) {
   // ── Tier 1: longest absolute prefix (the original behavior) ────────────────
   // cwd === path or cwd under path/. Longest path wins so /repo/sub beats /repo.
   // The FIRST cwd variant that yields any prefix match wins (raw before realpath).
+  // With rejectAmbiguous (session-cwd close check), two DISTINCT projects sharing the same
+  // longest matching working_dir (a monorepo config) is a real tie we must not
+  // break arbitrarily — decline to null so the caller degrades to the
+  // unresolved-cwd path instead of attributing the close to the wrong project.
   for (const c of cwds) {
     const cf = casefold(c, caseInsensitive);
     let bestSlug = null;
     let bestLen = -1;
+    let bestTied = false;
     for (const e of entries) {
       if (!isEligible(e.slug)) continue;
       const pf = casefold(e.path, caseInsensitive);
-      if ((cf === pf || cf.startsWith(`${pf}/`)) && e.path.length > bestLen) {
-        bestLen = e.path.length;
-        bestSlug = e.slug;
+      if (cf === pf || cf.startsWith(`${pf}/`)) {
+        if (e.path.length > bestLen) {
+          bestLen = e.path.length;
+          bestSlug = e.slug;
+          bestTied = false;
+        } else if (e.path.length === bestLen && e.slug !== bestSlug) {
+          bestTied = true;
+        }
       }
     }
-    if (bestSlug) return bestSlug;
+    if (bestSlug) {
+      if (bestTied && rejectAmbiguous) return null;
+      return bestSlug;
+    }
   }
 
   // ── Tier 2: globally-unique basename of a cwd ancestor (cross-machine) ─────

package/scripts/lib/wikilink.mjs

@@ -8,21 +8,24 @@
 //   - scripts/crystallize.mjs (page collection, link extraction)
 //
 // Shared-resolver consolidation. Before this lib, each script carried its own copy of
-// collectPages + a slug-form deriver, drifting in subtle ways. The four
+// collectPages + a slug-form deriver, drifting in subtle ways. The five
 // collectPages variants are NOT interchangeable — they differ deliberately in
 // traversal/security/output-shape policy (codex design review, CONCERN):
 //
 //   - rename uses lstat + skips symlinks   → a vault scan can never escape via a
 //     symlinked dir/file (security boundary).
 //   - lint skips `_`-prefixed DIRECTORIES  → pages/feedback/_drafts scaffolds
-//     stay out of the lint set, while `_`-prefixed FILES (e.g. _index.md) lint.
+//     stay out of the lint SET, while `_`-prefixed FILES (e.g. _index.md) lint.
+//   - linkable is lint WITHOUT that dir skip → the same pages stay reachable as
+//     wikilink destinations. Not linting a page and not being able to link to it
+//     are separate policies; lint feeds this into its link-target catalog only.
 //   - crystallize skips ANY `.`-prefixed entry (dir AND file).
-//   - graph/lint/rename skip only `.`-prefixed FILES.
-//   - graph/crystallize emit raw `rel`/`slug`; lint keeps OS-native `rel`
-//     (its own buildSlugMap POSIX-normalizes downstream); rename/graph
+//   - graph/lint/linkable/rename skip only `.`-prefixed FILES.
+//   - graph/crystallize emit raw `rel`/`slug`; lint/linkable keep OS-native `rel`
+//     (lint's buildSlugMap POSIX-normalizes downstream); rename/graph
 //     POSIX-normalize the slug at scan time.
 //
-// So this lib exposes ONE walker core plus four NAMED PRESETS, not a pile of
+// So this lib exposes ONE walker core plus five NAMED PRESETS, not a pile of
 // boolean flags — each preset pins exactly one caller's historical behavior and
 // is fixed by a unit test. readdirSync order is preserved verbatim (NO sort):
 // graph's bare-first slug index is order-sensitive (first page wins a shared
@@ -81,6 +84,29 @@ export function collectPagesLint(dir, root, ignorePatterns = []) {
   );
 }
 
+// lint link-target catalog: collectPagesLint WITHOUT the `_`-dir skip.
+//
+// Not linting a page and not being able to link to it are different things. The
+// `_`-dir skip exists so draft/spec scaffolds don't have to satisfy the schema —
+// it was never meant to make them unreachable. Sharing one list for both jobs
+// made lint report a live file as a broken wikilink, and under --strict that is
+// an error, so a vault could not reach a green gate no matter how clean it was.
+// lint feeds this into buildSlugMap's extraTargets (verbatim full slugs, no bare
+// or dir-relative aliases): `_specs/<name>/spec.md` repeats across specs, and a
+// bare `spec` alias would swallow unrelated broken links.
+export function collectPagesLinkable(dir, root, ignorePatterns = []) {
+  return walkMarkdown(
+    dir,
+    root,
+    ignorePatterns,
+    {
+      skipDotFile: true,
+      shape: (full) => ({ path: full, rel: relative(root, full) }),
+    },
+    [],
+  );
+}
+
 // graph: POSIX slug + bare, no `rel`.
 export function collectPagesGraph(dir, root, ignorePatterns = []) {
   return walkMarkdown(

package/scripts/lint.mjs

@@ -18,7 +18,7 @@
 
 import { existsSync, readFileSync, writeFileSync, readdirSync, statSync } from 'fs';
 import { join, extname, basename } from 'path';
-import { resolveHypoRoot, expandHome } from './lib/hypo-root.mjs';
+import { resolveHypoRootInfo, checkVaultOrExit, expandHome } from './lib/hypo-root.mjs';
 import { SESSION_STATE_NEXT_HEADINGS } from '../hooks/hypo-shared.mjs';
 import { loadHypoIgnore, isScanIgnored } from './lib/hypo-ignore.mjs';
 import {
@@ -30,7 +30,7 @@ import {
 import { findDesignHistoryStale } from './lib/design-history-stale.mjs';
 import { FEEDBACK_SCOPE_RE } from './lib/feedback-scope.mjs';
 import { FAILURE_TYPE_ENUM } from './lib/failure-type.mjs';
-import { collectPagesLint, slugForms } from './lib/wikilink.mjs';
+import { collectPagesLint, collectPagesLinkable, slugForms } from './lib/wikilink.mjs';
 import { parseFrontmatter, SEQUENCE_ENTRY_RE } from './lib/frontmatter.mjs';
 
 // ── arg parsing ──────────────────────────────────────────────────────────────
@@ -43,7 +43,11 @@ function parseArgs(argv) {
     else if (arg === '--fix') args.fix = true;
     else if (arg === '--strict') args.strict = true;
   }
-  if (!args.hypoDir) args.hypoDir = resolveHypoRoot();
+  if (!args.hypoDir) {
+    const info = resolveHypoRootInfo();
+    args.hypoDir = info.root;
+    args.hypoDirSource = info.source;
+  }
   return args;
 }
 
@@ -483,12 +487,24 @@ function lintPage({ path, rel }, slugMap, tagVocab, pageDirs, validTypes) {
 // ── main ──────────────────────────────────────────────────────────────────────
 
 const args = parseArgs(process.argv);
+// Only validate the auto-resolved path (env/marker/default). An explicit
+// --hypo-dir=<path> (tests, other tooling) is trusted as-is, valid or not.
+if (args.hypoDirSource) checkVaultOrExit(args.hypoDir, args.hypoDirSource);
 
 const ignorePatterns = loadHypoIgnore(args.hypoDir);
 const scanDirs = ['pages', 'projects', 'journal'].map((d) => join(args.hypoDir, d));
 const pages = scanDirs.flatMap((d) => collectPagesLint(d, args.hypoDir, ignorePatterns));
+// Pages under `_`-prefixed dirs are deliberately not linted, but they are real
+// files and a link to one is not broken. Catalog them as link targets only, as
+// verbatim full slugs (extraTargets gets no derived aliases — a bare `spec` from
+// every `_specs/<name>/spec.md` would mask unrelated broken links).
+const lintedRels = new Set(pages.map((p) => p.rel));
+const underscoreDirTargets = scanDirs
+  .flatMap((d) => collectPagesLinkable(d, args.hypoDir, ignorePatterns))
+  .filter((p) => !lintedRels.has(p.rel))
+  .map((p) => p.rel.replace(/\.md$/, '').replace(/\\/g, '/'));
 const linkTargets = collectLinkTargets(args.hypoDir, ignorePatterns);
-const slugMap = buildSlugMap(pages, linkTargets);
+const slugMap = buildSlugMap(pages, [...linkTargets, ...underscoreDirTargets]);
 const tagVocab = parseSchemaVocab(args.hypoDir);
 const pageDirs = parseSchemaPageDirs(args.hypoDir);
 // Accepted page types = hardcoded core ∪ the vault SCHEMA's taxonomy. Union (not