hypomnema 1.4.2 → 1.5.0

package/scripts/init.mjs

@@ -123,7 +123,7 @@ Commands:
   doctor                  Health check: directories, files, hooks, settings.json, git
   uninstall               Remove hooks and registrations (dry-run by default; pass --apply)
   feedback-sync           Project feedback (SoT) → MEMORY.md / CLAUDE.md learned-behaviors
-                          projection (--check default, --write to apply; ADR 0031)
+                          projection (--check default, --write to apply)
 
   Running \`hypomnema\` with no command is equivalent to \`hypomnema init\`.
 
@@ -200,7 +200,7 @@ const HYPO_DIRS = [
   'journal/weekly',
   'journal/monthly',
   'pages/observability',
-  // User extensions companion (ADR 0024). init creates the baseline
+  // User extensions companion. init creates the baseline
   // dirs; #29 (E2) adds the hard-copy / manifest / settings sync into them.
   'extensions/hooks',
   'extensions/commands',
@@ -451,7 +451,7 @@ function pkgJsonPath() {
 }
 
 /**
- * ADR 0038 (P): abort when this package would DOWNGRADE a newer active install.
+ * Abort when this package would DOWNGRADE a newer active install.
  * Exit 2 (distinct from the generic exit-1 error class) on refusal so callers and
  * tests can tell "refused downgrade" apart from "init failed". No-ops on a fresh
  * install (no metadata), unparseable versions, the same package re-running itself,
@@ -829,7 +829,7 @@ const args = parseArgs(process.argv);
 // Validate hooks.json before any file writes so a bad package leaves no partial state
 const HOOK_MAP = args.hooks || args.codex ? loadHookMap() : null;
 
-// Downgrade guard (ADR 0038, P): refuse to overwrite a NEWER active install with
+// Downgrade guard: refuse to overwrite a NEWER active install with
 // an older package. The footgun: a stale `npm i -g hypomnema` owns the `hypomnema`
 // bin on PATH, so `hypomnema init` runs the OLD package and silently downgrades
 // the newer install (dropping features like the update-notifier). Runs
@@ -854,7 +854,7 @@ if (args.fromRemote) {
   for (const d of HYPO_DIRS) ensureDir(join(args.hypoDir, d), args.dryRun);
 
   // 1b. extensions baseline: drop a .gitkeep into each so the empty dirs are
-  // git-trackable in the user's wiki repo (ADR 0024).
+  // git-trackable in the user's wiki repo.
   for (const t of ['hooks', 'commands', 'skills', 'agents']) {
     copyTemplate(
       join('extensions', t, '.gitkeep'),
@@ -929,12 +929,12 @@ if (args.hooks) {
 // Always record the active install identity (pkgRoot + pkgVersion), even for a
 // --no-hooks --no-commands scaffold. That flow still installs the wiki pre-commit
 // hook (and, with --codex, ~/.codex hooks); without a recorded pkgVersion baseline
-// the ADR 0038 downgrade guard has nothing to compare against, so a later stale
+// the downgrade guard has nothing to compare against, so a later stale
 // sibling could repoint those surfaces unguarded. writePkgJson merges (...existing),
 // so this never clobbers a commands/extensions map written elsewhere.
 writePkgJson(args.dryRun, commandSHAs ? { commands: commandSHAs } : {});
 
-// 4b. user extensions companion sync (ADR 0024). Runs after
+// 4b. user extensions companion sync. Runs after
 // writePkgJson so the per-target SHA map is merged into the same hypo-pkg.json
 // (preserving the commands map) rather than racing it.
 if (args.hooks) {

package/scripts/lib/check-tracker-ids.mjs

@@ -10,15 +10,25 @@
  * This module is PURE (no fs, no git, no process) so it is unit-testable; the
  * CLI wrapper (scripts/check-tracker-ids.mjs) does the file/git/commit-msg I/O.
  *
- * Blocked (examples use an `N` placeholder, NOT a real digit, so this file
- * itself scans clean and is NOT exempted from --all):
+ * Blocked everywhere in scope (examples use an `N` placeholder, NOT a real
+ * digit, so this file itself scans clean and is NOT exempted from --all):
  *   - /\bISSUE-\d+\b/i      → the wiki issue tracker, any case (e.g. ISSUE-N)
  *   - /\bfix[ \t ]+#\d+\b/i → the wiki fix tracker, any case (e.g. fix #N)
+ *   - /\bFEAT-\d+\b/i       → the wiki feature tracker, any case (e.g. FEAT-N)
+ *   - /\bIMPR-\d+\b/i       → the wiki improvement tracker, any case (e.g. IMPR-N)
+ *   - /\bPRAC-\d+\b/i       → the wiki practice tracker, any case (e.g. PRAC-N)
  *
- * User-facing docs ONLY (README.md, README.ko.md, docs/) additionally block
- * `ADR NNNN` / `decisions/NNNN` (USER_FACING_PATTERNS) — dangling pointers into the
- * maintainer's private wiki ADR set. The CLI scope-gates these so shipped code
- * comments and CHANGELOG history keep their ADR anchors.
+ * FEAT-/IMPR-/PRAC- were once exempt inside shipped code comments; that exemption
+ * shipped dangling pointers into the maintainer's private wiki to OSS users, so it
+ * was removed. They now block everywhere in scope; the maintainer keeps them only
+ * in tests/, qa-runs/, and local notes. The verifier subsystem that legitimately
+ * carries `decisions/NNNN` runtime data is excluded from the scan instead (see the
+ * CLI's EXCLUDED_FILES).
+ *
+ * `ADR NNNN` / `ADR-NNNN` / `decisions/NNNN` (DECISION_PATTERNS) are dangling
+ * pointers into the maintainer's private wiki ADR set. They block everywhere in
+ * scope EXCEPT CHANGELOG.md, whose version history legitimately cites the decision
+ * behind a release line. The CLI applies these per-file via patternsFor().
  *
  * Accepted edge cases (documented, not bugs):
  *   - FALSE POSITIVE: `FOO-ISSUE-N` matches (the `-` gives a word boundary
@@ -28,21 +38,22 @@
  *     safe — none start the word `fix` right before the `#`.
  */
 
-// Applied by the CLI to user-facing docs ONLY (README.md / README.ko.md / docs/),
-// never to shipped code or CHANGELOG. A `ADR NNNN` / `decisions/NNNN` reference in
-// prose a user reads points into the maintainer's private wiki ADR set, which the
-// user does not have — a dangling pointer. The same anchor inside a code comment
-// is maintainer rationale (kept), so this set is scope-gated rather than global.
-// Examples below use `NNNN`, not real digits, so this file scans clean.
-export const USER_FACING_PATTERNS = [
+// `ADR NNNN` / `ADR-NNNN` / `decisions/NNNN` point into the maintainer's private
+// wiki ADR set, which an OSS user does not have. The CLI applies this set to every
+// in-scope file EXCEPT CHANGELOG.md (version history may cite a decision); the
+// verifier subsystem that carries decisions/ paths as runtime data is removed by
+// EXCLUDED_FILES first. The ADR matcher tolerates a space, tab, or hyphen between
+// `ADR` and the number. Examples below use `NNNN`, not real digits, so this file
+// scans clean.
+export const DECISION_PATTERNS = [
   {
     name: 'ADR NNNN',
-    label: 'wiki ADR pointer (user-facing docs)',
-    re: /\bADR[ \t]+\d{3,4}\b/gi,
+    label: 'wiki ADR pointer',
+    re: /\bADR[ \t-]+\d{3,4}\b/gi,
   },
   {
     name: 'decisions/NNNN',
-    label: 'wiki decisions path (user-facing docs)',
+    label: 'wiki decisions path',
     re: /\bdecisions\/\d{3,4}\b/gi,
   },
 ];
@@ -59,32 +70,40 @@ export const BLOCKED_PATTERNS = [
     label: 'wiki fix-tracker id',
     re: /\bfix[ \t ]+#\d+\b/gi,
   },
-];
-
-// The remaining wiki tracker prefixes (FEAT-/IMPR-/PRAC-). These are NOT in
-// BLOCKED_PATTERNS because shipped CODE COMMENTS legitimately cite them for
-// maintainer context (e.g. `// FEAT-17 hardening`), exactly like ADR anchors —
-// blocking them everywhere would flag ~20 real in-code references. They ARE
-// blocked on the PUBLIC RELEASE SURFACE that carries no code: the annotated tag
-// body (the source of the GitHub Release via --notes-from-tag). The CLI applies
-// [...BLOCKED_PATTERNS, ...SURFACE_TRACKER_PATTERNS] only in --tag mode. The
-// CHANGELOG's own surface-ID-0 is held by the section migration + a grep
-// regression test, not by widening this file-scan set (changelog-pr-guide §5).
-// Examples below use `N`, not a real digit, so this file scans clean.
-export const SURFACE_TRACKER_PATTERNS = [
+  // FEAT-/IMPR-/PRAC- were a tag-body-only set until they were promoted here so
+  // they block in shipped code comments too (the old exemption leaked dead wiki
+  // pointers to OSS users). Examples below use `N`, not a real digit, so this
+  // file scans clean and is NOT exempted from --all.
   { name: 'FEAT-N', label: 'wiki feature-tracker id', re: /\bFEAT-\d+\b/gi },
   { name: 'IMPR-N', label: 'wiki improvement-tracker id', re: /\bIMPR-\d+\b/gi },
   { name: 'PRAC-N', label: 'wiki practice-tracker id', re: /\bPRAC-\d+\b/gi },
 ];
 
-// The full tracker-ID set for a no-code public surface (the annotated tag body).
-export const TAG_BODY_PATTERNS = [...BLOCKED_PATTERNS, ...SURFACE_TRACKER_PATTERNS];
+// The full tracker-ID set for a no-code public surface (the annotated tag body,
+// republished verbatim by `gh release create --notes-from-tag`). It equals
+// BLOCKED_PATTERNS now that FEAT-/IMPR-/PRAC- live there; ADR/decisions anchors
+// are intentionally allowed in the tag body (release notes cite decisions the way
+// CHANGELOG history does). The CHANGELOG's own surface-ID-0 is held by the section
+// migration + a grep regression test (changelog-pr-guide §5).
+export const TAG_BODY_PATTERNS = [...BLOCKED_PATTERNS];
+
+// Strip a leading comment-continuation marker (`*`, `//`, `#`) so a wrapped
+// comment line can be re-joined to its predecessor as flowing text.
+const COMMENT_CONT_RE = /^[ \t]*(?:\*|\/\/|#+)[ \t]?/;
 
 /**
  * Scan a blob of text against `patterns` (default BLOCKED_PATTERNS). Returns hits:
  *   { pattern, label, match, line, col, lineText }
  * `line`/`col` are 1-based. Empty array => clean. The CLI passes the broader
- * [...BLOCKED_PATTERNS, ...USER_FACING_PATTERNS] set only for user-facing docs.
+ * [...BLOCKED_PATTERNS, ...DECISION_PATTERNS] set for every in-scope file but the
+ * CHANGELOG.
+ *
+ * Tracker tokens also line-wrap inside comments (`... continuing (ADR\n * 0045)`).
+ * A pure per-line scan misses those, so each line is ALSO scanned joined to the
+ * next (with the next line's comment-continuation marker collapsed to a space);
+ * only matches that START on the current line and CROSS the join are kept, so a
+ * wrap is reported exactly once at its prefix line and non-wrapped tokens are
+ * never double-counted.
  */
 export function scanText(text, patterns = BLOCKED_PATTERNS) {
   if (typeof text !== 'string' || text.length === 0) return [];
@@ -107,6 +126,45 @@ export function scanText(text, patterns = BLOCKED_PATTERNS) {
         if (m.index === re.lastIndex) re.lastIndex++; // never-zero-width guard
       }
     }
+    // Wrapped-token guard: a token can line-wrap at two points — between its
+    // prefix WORD and its number (`ADR\n0045`, where the break stands in for a
+    // space) OR right at its separator (`ISSUE-\n9`, `decisions/\n0031`,
+    // `fix #\n37`, where the digit must sit flush against `-`/`/`/`#`). So scan
+    // this line joined to the next BOTH with a space (space-separated forms) and
+    // with no gap (separator-flush forms), keeping only matches that begin on this
+    // line and cross the join. A token reconstructed by both joins (e.g. the ADR
+    // hyphen form) is de-duplicated by its whitespace-collapsed text.
+    if (i + 1 < lines.length) {
+      const lt = lineText.length;
+      const tail = lines[i + 1].replace(COMMENT_CONT_RE, '');
+      const seen = new Set();
+      for (const [joined, tailAt] of [
+        [lineText + ' ' + tail, lt + 1],
+        [lineText + tail, lt],
+      ]) {
+        for (const { name, label, re } of patterns) {
+          re.lastIndex = 0;
+          let m;
+          while ((m = re.exec(joined)) !== null) {
+            if (m.index < lt && m.index + m[0].length > tailAt) {
+              const key = name + ':' + m[0].replace(/\s+/g, '');
+              if (!seen.has(key)) {
+                seen.add(key);
+                hits.push({
+                  pattern: name,
+                  label,
+                  match: m[0],
+                  line: i + 1,
+                  col: m.index + 1,
+                  lineText: joined,
+                });
+              }
+            }
+            if (m.index === re.lastIndex) re.lastIndex++;
+          }
+        }
+      }
+    }
   }
   return hits;
 }

package/scripts/lib/design-history-stale.mjs

@@ -88,7 +88,7 @@ export function findDesignHistoryStale(hypoDir) {
     if (!existsSync(dhPath)) continue;
 
     // session-log can live as a flat `session-log.md` (legacy) or a directory of
-    // daily shards `session-log/YYYY-MM-DD.md` (ADR 0050 canonical; legacy
+    // daily shards `session-log/YYYY-MM-DD.md` (canonical; legacy
     // monthly `YYYY-MM.md` files still appear pre-cutover). This globs every
     // `.md` in the directory, so daily and monthly shapes are both aggregated —
     // the staleness check needs to see all of them.

package/scripts/lib/extensions.mjs

@@ -1,5 +1,5 @@
 /**
- * scripts/lib/extensions.mjs — User extensions companion sync (ADR 0024).
+ * scripts/lib/extensions.mjs — User extensions companion sync.
  *
  * `~/hypomnema/extensions/{hooks,commands,skills,agents}/` holds user-authored
  * extensions, git-tracked alongside the wiki. init/upgrade hard-copy them into
@@ -38,12 +38,12 @@ const HOME = homedir();
 // Extension types and their on-disk target subdirectory under ~/.claude or ~/.codex.
 export const EXT_TYPES = ['hooks', 'commands', 'skills', 'agents'];
 
-// Required filename prefix (ADR 0024 §2 recommends; plan §5 #9 enforces). Files
+// Required filename prefix (plan §5 #9 enforces). Files
 // without it are skipped so uninstall (which strips hypo-ext-*) can always reach
 // every file we install — and so a stray name cannot collide with core hooks.
 export const EXT_PREFIX = 'hypo-ext-';
 
-// Codex supports hooks + commands only; skills/agents are Claude-only (ADR 0024 §4).
+// Codex supports hooks + commands only; skills/agents are Claude-only.
 export const CODEX_TYPES = ['hooks', 'commands'];
 
 // Per-type expected file extension. Hooks are executable .mjs; the rest are .md.
@@ -505,7 +505,7 @@ export function syncExtensions({
  *   7. non-target event · mixed                                        (extract + append new)
  *   8. no occurrence                                                   (append new)
  *
- * Mixed-group invariant (ADR 0024 amendment 2026-05-23): foreign hooks
+ * Mixed-group invariant (amendment 2026-05-23): foreign hooks
  * sharing the matcher group are NEVER read, modified, or reordered. The hosting
  * group's matcher is also left exactly as-is once we extract — even when our
  * extraction is the reason the group becomes single-foreign. Foreign handler-
@@ -516,7 +516,7 @@ export function syncExtensions({
  * Our hook entry, however, is canonical-reset on any drift mutation (ranks 3
  * and 4): the entire prior hook object — including any handler-level fields a
  * user appended to our hypo-ext-* entry — is replaced by the manifest-derived
- * `{ type, command, timeout? }` shape. This mirrors the ADR 0024 hard-copy
+ * `{ type, command, timeout? }` shape. This mirrors the hard-copy
  * ownership semantic for hypo-ext-* file copies. Users who want extra handler
  * fields on a Hypomnema-managed extension must extend the manifest, not edit
  * settings.json directly (manifest-as-SoT). registerSettings is honest about
@@ -718,7 +718,7 @@ function registerSettings(settingsPath, expectedEntries, apply) {
       // target single-hook drift → replace the canonical group object with
       // the manifest-derived shape. Our hook entry is canonical-reset on this
       // path (any user-added handler fields are discarded — that mirrors the
-      // ADR 0024 hard-copy ownership semantic for hypo-ext-*).
+      // hard-copy ownership semantic for hypo-ext-*).
       const loc = locateGroup(settings.hooks, canonical.group);
       if (loc) settings.hooks[loc.event][loc.groupIdx] = desiredGroup;
     } else if (canonicalRank === 4) {
@@ -726,7 +726,7 @@ function registerSettings(settingsPath, expectedEntries, apply) {
       // entry (looked up by identity) with the manifest-derived shape.
       // Foreign hooks and the group-level matcher are untouched; our own
       // hook is canonical-reset (handler-level user mods on the hypo-ext-*
-      // hook are not preserved — by the same ADR 0024 ownership semantic).
+      // hook are not preserved — by the same ownership semantic).
       const hi = canonical.group.hooks.indexOf(canonical.hook);
       if (hi !== -1) canonical.group.hooks[hi] = desiredHook;
     } else {

package/scripts/lib/failure-type.mjs

@@ -4,7 +4,7 @@
 //   - scripts/lint.mjs      (lint-time enum validation of feedback frontmatter)
 //   - scripts/feedback.mjs  (create/append-time --failure-type validation)
 // Keep this the ONLY definition; both consumers import it so the two validators
-// never drift (mirrors feedback-scope.mjs / ADR 0034). stats.mjs aggregates by
+// never drift (mirrors feedback-scope.mjs). stats.mjs aggregates by
 // plain string and does not validate, so it is intentionally not a consumer.
 //
 // `failure_type` is an OPTIONAL field: it classifies feedback that came from a

package/scripts/lib/feedback-scope.mjs

@@ -4,7 +4,7 @@
 //   - scripts/lint.mjs      (lint-time validation of feedback page frontmatter)
 //   - scripts/feedback.mjs  (create-time --scope validation in /hypo:feedback)
 // Keep this the ONLY definition; both consumers import it so the two validators
-// never drift (ADR 0034 / OQ-34). feedback-sync.mjs matches scope by plain string
+// never drift. feedback-sync.mjs matches scope by plain string
 // equality (not this regex), so it is intentionally not a consumer.
 //
 // Accepts `global` or `project:<id>`. The `<id>` charset matches what

package/scripts/lib/project-create.mjs

@@ -1,8 +1,8 @@
 #!/usr/bin/env node
 /**
- * project-create.mjs — atomic auto-project scaffold (ADR 0023)
+ * project-create.mjs — atomic auto-project scaffold
  *
- * Invoked by the LLM (NOT a user-facing subcommand — ADR 0023 deprecated
+ * Invoked by the LLM (NOT a user-facing subcommand; `hypomnema project new` is deprecated
  * `hypomnema project new`) after the user answers "Y" to a SessionStart /
  * CwdChanged auto-project offer. One call materializes a whole project:
  *

package/scripts/lib/template-schema-version.mjs

@@ -6,7 +6,7 @@ import { parseFrontmatter } from './frontmatter.mjs';
 // frontmatter. init.mjs / upgrade.mjs stamp it into hypo-pkg.json metadata;
 // deriving it here (rather than hardcoding a literal at each write site) keeps
 // the stamped value from going stale on a schema bump — the failure mode that
-// FEAT-1's 2.0 → 2.1 bump would otherwise have introduced. Returns null only if
+// the 2.0 → 2.1 schema bump would otherwise have introduced. Returns null only if
 // the template is missing/unreadable (a broken package), in which case callers
 // keep their prior literal default.
 export function templateSchemaVersion(pkgRoot) {

package/scripts/lib/wd-match.mjs

@@ -0,0 +1,181 @@
+/**
+ * scripts/lib/wd-match.mjs — shared cwd ↔ working_dir project matcher.
+ *
+ * The four readers (resume.mjs, hooks/hypo-shared.mjs, hooks/hypo-session-start.mjs,
+ * hooks/hypo-cwd-change.mjs) each used to inline the same prefix-match. This
+ * module is the single source of truth they delegate the path logic to, so the
+ * cross-machine basename fallback below is implemented (and tested) once.
+ *
+ * The cross-machine problem: a git-synced vault carries one machine's absolute
+ * working_dir to every machine, so on a second machine cwd never prefix-matches
+ * and cwd-first resume silently degrades to recency. The basename tier recovers
+ * the match WITHOUT a synced map or a writer: when the absolute prefix fails, a
+ * cwd ancestor whose directory name is a GLOBALLY unique project working_dir
+ * basename identifies the project. Unique-only, so a shared repo dirname fails
+ * closed back to recency (the original prefix-only behavior).
+ *
+ * The matcher (pickProjectByCwd) is PURE — no fs. collectProjectWorkingDirs is
+ * the disk companion that builds the project universe the matcher reasons over.
+ */
+
+import { homedir } from 'os';
+import { existsSync, readFileSync, readdirSync, statSync } from 'fs';
+import { join } from 'path';
+import { parseFrontmatter } from './frontmatter.mjs';
+
+// Expand a leading `~`/`~/`, strip trailing slashes. Mirrors the inline
+// expansion the readers did, kept here so every caller normalizes identically.
+// Returns null for empty/falsy input.
+export function normalizeWorkingDir(p) {
+  if (!p) return null;
+  let s = String(p).trim();
+  if (s === '~') s = homedir();
+  else if (s.startsWith('~/')) s = `${homedir()}/${s.slice(2)}`;
+  s = s.replace(/\/+$/, '');
+  return s || null;
+}
+
+// macOS (APFS/HFS+ default) and Windows match paths case-insensitively, so a
+// case-only difference between cwd and a recorded working_dir is the SAME dir
+// there and a genuinely different dir on Linux. Fold only on those platforms:
+// on Linux folding stays off, preserving the exact original comparison.
+export function isCaseInsensitiveFs(platform = process.platform) {
+  return platform === 'darwin' || platform === 'win32';
+}
+
+function casefold(s, ci) {
+  return ci ? s.toLowerCase() : s;
+}
+
+// Trailing path segment (basename) without importing path — paths here are
+// already normalized (no trailing slash). Returns '' for a bare root.
+function lastSegment(p) {
+  const i = p.lastIndexOf('/');
+  return i < 0 ? p : p.slice(i + 1);
+}
+
+/**
+ * Resolve which project a cwd belongs to.
+ *
+ * @param {{slug:string, workingDir:string|null|undefined}[]} projects
+ *   EVERY project with an index.md (the universe). The basename-uniqueness gate
+ *   is computed over all of them, so an unrelated project sharing a dirname
+ *   correctly disqualifies the basename tier (fail closed).
+ * @param {string} cwd  process.cwd()
+ * @param {object} [opts]
+ * @param {string[]|null} [opts.eligible]  restrict the ANSWER to these slugs
+ *   (e.g. resume's hot.md rows); uniqueness is still judged over all `projects`.
+ *   null = any project is an acceptable answer.
+ * @param {string|null} [opts.realpathCwd]  realpathSync(cwd), if the caller
+ *   resolved symlinks. Tried in addition to the raw cwd.
+ * @param {boolean} [opts.caseInsensitive]  override FS case sensitivity (tests).
+ * @returns {string|null} matched slug, or null when nothing matches.
+ */
+export function pickProjectByCwd(projects, cwd, opts = {}) {
+  const { eligible = null, realpathCwd = null, caseInsensitive = isCaseInsensitiveFs() } = opts;
+  if (!cwd && !realpathCwd) return null;
+
+  const eligibleSet = eligible ? new Set(eligible) : null;
+  const isEligible = (slug) => !eligibleSet || eligibleSet.has(slug);
+
+  // Universe of normalized (slug, path) entries with a real working_dir.
+  const entries = [];
+  for (const p of projects) {
+    const path = normalizeWorkingDir(p.workingDir);
+    if (path) entries.push({ slug: p.slug, path });
+  }
+  if (entries.length === 0) return null;
+
+  // cwd variants in PRIORITY order: raw first, realpath (symlink-resolved) only
+  // as a fallback. A raw-cwd match must not be overridden by a realpath match
+  // (preserves the original single-cwd behavior; realpath only rescues misses).
+  const cwds = [];
+  for (const c of [cwd, realpathCwd]) {
+    const n = normalizeWorkingDir(c);
+    if (n && !cwds.includes(n)) cwds.push(n);
+  }
+
+  // ── 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).
+  for (const c of cwds) {
+    const cf = casefold(c, caseInsensitive);
+    let bestSlug = null;
+    let bestLen = -1;
+    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 (bestSlug) return bestSlug;
+  }
+
+  // ── Tier 2: globally-unique basename of a cwd ancestor (cross-machine) ─────
+  // Count basenames across the WHOLE universe. A basename is usable only when
+  // exactly one project carries it, so a shared dirname falls through to null.
+  const byBasename = new Map(); // folded basename -> { slug, count }
+  for (const e of entries) {
+    const b = casefold(lastSegment(e.path), caseInsensitive);
+    if (!b) continue;
+    const hit = byBasename.get(b);
+    if (hit) hit.count += 1;
+    else byBasename.set(b, { slug: e.slug, count: 1 });
+  }
+
+  // For each cwd variant (raw first), collect every ancestor whose basename is a
+  // globally-unique, eligible project basename. Use it ONLY when the whole chain
+  // points at exactly ONE project: if two different projects match along the
+  // path (e.g. cwd /x/monorepo/api with both `monorepo` and `api` registered),
+  // cwd alone can't disambiguate, so decline and let the caller fall back to
+  // recency (fail closed, no wrong-project guess).
+  for (const c of cwds) {
+    const matched = new Set();
+    let cur = c;
+    while (cur && cur.includes('/')) {
+      const b = casefold(lastSegment(cur), caseInsensitive);
+      const hit = b && byBasename.get(b);
+      if (hit && hit.count === 1 && isEligible(hit.slug)) matched.add(hit.slug);
+      cur = cur.slice(0, cur.lastIndexOf('/'));
+    }
+    if (matched.size === 1) return [...matched][0];
+  }
+  return null;
+}
+
+/**
+ * Scan projects/<slug>/index.md and return [{slug, workingDir}] for every real
+ * project. Skips `_template` and dirs without an index.md. The full set is the
+ * uniqueness universe for tier 2, so callers should pass ALL projects here even
+ * when they later restrict the answer via `opts.eligible`.
+ *
+ * @param {string} hypoDir
+ * @returns {{slug:string, workingDir:string|null}[]}
+ */
+export function collectProjectWorkingDirs(hypoDir) {
+  const projectsDir = join(hypoDir, 'projects');
+  if (!existsSync(projectsDir)) return [];
+  const out = [];
+  for (const slug of readdirSync(projectsDir)) {
+    if (slug === '_template') continue;
+    const dir = join(projectsDir, slug);
+    try {
+      if (!statSync(dir).isDirectory()) continue;
+    } catch {
+      continue;
+    }
+    const indexPath = join(dir, 'index.md');
+    if (!existsSync(indexPath)) continue;
+    let workingDir = null;
+    try {
+      const fm = parseFrontmatter(readFileSync(indexPath, 'utf-8'));
+      workingDir = fm?.working_dir ?? null;
+    } catch {
+      workingDir = null;
+    }
+    out.push({ slug, workingDir });
+  }
+  return out;
+}

package/scripts/lib/wikilink.mjs

@@ -7,7 +7,7 @@
 //   - scripts/graph.mjs       (slug index, page collection, link extraction)
 //   - scripts/crystallize.mjs (page collection, link extraction)
 //
-// IMPR-13 consolidation. Before this lib, each script carried its own copy of
+// 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 variants are NOT interchangeable — they differ deliberately in
 // traversal/security/output-shape policy (codex design review, CONCERN):

package/scripts/lint.mjs

@@ -115,7 +115,7 @@ const TYPE_CONDITIONAL_FIELDS = {
   'tool-eval': ['status'],
   postmortem: ['outcome'],
   learning: ['source'],
-  // feedback: ADR 0031 — projection SoT requires full classification
+  // feedback: projection SoT requires full classification
   feedback: [
     'status',
     'scope',
@@ -136,13 +136,13 @@ const TYPE_ENUM_FIELDS = {
   prd: { status: ['draft', 'active', 'completed', 'cancelled', 'archived'] },
   adr: { status: ['proposed', 'accepted', 'deprecated', 'superseded'] },
   'tool-eval': { status: ['adopted', 'evaluating', 'rejected'] },
-  // feedback: ADR 0031 — sensitivity:private is forbidden (wiki is a
+  // feedback: sensitivity:private is forbidden (wiki is a
   // git-pushed public surface)
   feedback: {
     status: ['active', 'superseded', 'archived'],
     tier: ['L1', 'L2'],
     sensitivity: ['public', 'sanitized'],
-    // FEAT-1: optional failure taxonomy. The enum loop guards on `if (fm[field])`,
+    // optional failure taxonomy. The enum loop guards on `if (fm[field])`,
     // so an omitted failure_type is never validated (optional, migration-safe).
     failure_type: FAILURE_TYPE_ENUM,
   },
@@ -283,7 +283,7 @@ const issues = [];
 //                             double-gate).
 // NOTE: no gate currently passes --strict (npm run lint / CI / release.yml /
 // crystallize / the close-gate all run plain lint), so promotion is
-// forward-looking — these surface as warnings today. IMPR-3's deliverable is
+// forward-looking: these surface as warnings today. The deliverable is
 // "stop silently green-passing invalid YAML"; the W9 warning satisfies that.
 const STRICT_PROMOTE_IDS = new Set(['W1', 'W2', 'W4', 'W9']);
 
@@ -392,7 +392,7 @@ function lintPage({ path, rel }, slugMap, tagVocab, pageDirs, validTypes) {
     }
   }
 
-  // feedback: scope vocabulary + conditional claude-learned fields (ADR 0031)
+  // feedback: scope vocabulary + conditional claude-learned fields
   if (fm.type === 'feedback') {
     const scope = fm.scope || '';
     if (scope && !FEEDBACK_SCOPE_RE.test(scope)) {

package/scripts/rename.mjs

@@ -234,7 +234,7 @@ function fail(args, msg) {
 //  • A directory move does NOT change basenames, only the path prefix. So bare
 //    `[[0052]]` links keep resolving to the relocated page automatically and need
 //    NO rewrite — only the FULL-slug and 1-seg DIR-RELATIVE forms encode the moved
-//    prefix and break. (Forms that drop ≥2 segments, e.g. `[[decisions/0052]]`, do
+//    prefix and break. (Forms that drop ≥2 segments, e.g. `[[decisions/NNNN]]`, do
 //    not encode the renamed prefix either: lint cannot resolve them today and they
 //    survive a move unchanged — out of scope, matching lint's buildSlugMap.)
 //  • Every moved page is BOTH a target (it relocates) and a source (its links to