hypomnema 1.4.2 → 1.5.1

package/scripts/doctor.mjs

@@ -221,7 +221,7 @@ function checkDirectories(hypoDir) {
     'pages',
     'projects',
     'sources',
-    // Extensions baseline (ADR 0024). Existence only — SHA / settings /
+    // Extensions baseline. Existence only — SHA / settings /
     // manifest integrity is E5.
     'extensions/hooks',
     'extensions/commands',
@@ -308,7 +308,7 @@ function checkSettingsJson() {
   }
 
   // stale hypo-* entries (uninstall remnants).
-  // hypo-ext-* commands are user-extension entries (ADR 0024) — not core hooks,
+  // hypo-ext-* commands are user-extension entries — not core hooks,
   // so they are intentionally absent from HOOK_MAP. Excluded here; their
   // integrity (SHA + manifest + entry match) is checked separately in E5.
   const isExtCommand = (cmd) => /(?:^|[/\s])hypo-ext-[^/\s]+\.mjs(?=$|["'\s])/.test(cmd);
@@ -545,7 +545,7 @@ function checkSyncState(hypoDir) {
 }
 
 function checkProjectSuggestions(hypoDir) {
-  // ADR 0023: the auto-project skip-persistence store. Absent file is
+  // Auto-project skip-persistence store. Absent file is
   // healthy (no offers declined yet). Validate the RAW JSON shape here rather
   // than via readProjectSuggestions(): that helper deliberately normalizes a
   // non-array `skips` to [] for fail-open hook reads, which would mask a
@@ -665,7 +665,7 @@ function checkCodexPaths() {
   }
 }
 
-// ── extensions integrity (ADR 0024, E5) ───────────────────────────
+// ── extensions integrity (E5) ─────────────────────────────────────
 
 // Detect drift between the user's `~/hypomnema/extensions/` source, the recorded
 // per-target SHA map (`hypo-pkg.json`), and the installed copies + settings.json
@@ -685,7 +685,7 @@ function checkCodexPaths() {
 //
 // E5 is doctor SURFACE for extensions integrity. The mixed-group surgical
 // *write* (preserve sibling-plugin hooks, swap only ours) used to be deferred
-// here; ADR 0024 amendment 2026-05-23 lifted that deferral —
+// here; amendment 2026-05-23 lifted that deferral:
 // registerSettings (extensions.mjs:478 docstring) now does occurrence-first +
 // 8-rank canonical write, and the (b) loop below mirrors that read-path via
 // collectOurOccurrences so a valid mixed-group occurrence is no longer warned
@@ -926,7 +926,7 @@ function checkExtensions(hypoDir, claudeHome, target = 'claude') {
   else warn(label, `${sample}${extra}`);
 }
 
-// ── feedback projection (ADR 0031) ──────────────────────────────
+// ── feedback projection ──────────────────────────────────────────
 
 // Spawn feedback-sync.mjs --check --json and map its drift report onto doctor's
 // pass/warn/fail. Integrity violations (exit-3 class: conflict / unpaired marker
@@ -1015,7 +1015,7 @@ function checkFeedbackProjection(hypoDir, claudeHome, projectId) {
   }
 }
 
-// ── stale sibling install (ADR 0038, D) ──────────────────────────────────────
+// ── stale sibling install (D) ────────────────────────────────────────────────
 //
 // Detect a SECOND, older Hypomnema that owns the `hypomnema` bin on PATH while a
 // newer copy owns the active hooks. That sibling is a footgun: `hypomnema init` /

package/scripts/feedback-sync.mjs

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 /**
- * feedback-sync.mjs — project wiki feedback as SoT, external memory as projection (ADR 0031)
+ * feedback-sync.mjs — project wiki feedback as SoT, external memory as projection
  *
  * Wiki `pages/feedback/<slug>.md` is the single source of truth for
  * learning/correction knowledge. Two Claude Code memory surfaces are derived
@@ -506,7 +506,7 @@ async function resolveProjectId(args, { prompt = defaultPrompt, isTTY } = {}) {
 //
 // Both modes are *reverse* one-time helpers that scaffold wiki DRAFTS under
 // pages/feedback/_drafts/ — they NEVER write pages/feedback/<slug>.md directly
-// (the single-direction invariant, ADR 0031 §6). A human reviews each draft,
+// (the single-direction invariant). A human reviews each draft,
 // fills the decision fields (scope/tier/targets/promote_to_global), and moves
 // it into pages/feedback/. _drafts/ is excluded from sync candidates
 // (loadFeedbackPages) and from lint (collectPages skips `_`-dirs), so an
@@ -856,7 +856,7 @@ function run(args, resolvedPid = null) {
   // not actionable drift — contract §5 step 4 promises this never hard-fails,
   // so it must stay OUT of strictWarnings or the PreCompact gate (#3, which
   // runs `--check --strict`) would block every first-run user. A private-
-  // sensitivity page IS a real SoT violation (ADR 0031 §7; lint #8 blocks it
+  // sensitivity page IS a real SoT violation (lint #8 blocks it
   // at the source) so it stays strict-escalatable as defense-in-depth.
   const warnings = [];
   const strictWarnings = [];
@@ -875,8 +875,8 @@ function run(args, resolvedPid = null) {
 
   // pass 1: preflight every target before touching disk — validates the write
   // plan (container/anchor, markers) and computes next content. A conflict /
-  // over-cap / build error in ANY target blocks writes to ALL (atomicity — ADR
-  // 0031 Decision §6 "no auto-merge"; avoids a partial write where one target
+  // over-cap / build error in ANY target blocks writes to ALL (atomicity:
+  // "no auto-merge"; avoids a partial write where one target
   // lands and another refuses).
   const evals = targets.map((target) => ({ target, res: evaluateTarget(pages, target) }));
   for (const { target, res } of evals) {

package/scripts/feedback.mjs

@@ -3,8 +3,8 @@
  * Hypomnema feedback script
  *
  * Creates or appends to pages/feedback/<topic>.md with a behaviour-correction
- * entry. The wiki feedback page is the single source of truth (ADR 0031 / fix
- * #37); MEMORY.md and CLAUDE.md <learned_behaviors> are one-way *projections*
+ * entry. The wiki feedback page is the single source of truth; MEMORY.md and
+ * CLAUDE.md <learned_behaviors> are one-way *projections*
  * derived from it. Never hand-edit those targets — this script writes the page
  * and then runs `feedback-sync --write` to refresh the projection automatically.
  *
@@ -123,7 +123,7 @@ function listTopics(hypoDir) {
   for (const f of files) console.log(`  ${f.replace(/\.md$/, '')}`);
 }
 
-// ── classification validation (mirrors lint #8 / ADR 0031 §6) ──────────────────
+// ── classification validation (mirrors lint #8) ─────────────────────────────────
 
 const TIER_ENUM = ['L1', 'L2'];
 const SENSITIVITY_ENUM = ['public', 'sanitized']; // private is forbidden (wiki is git-public)
@@ -136,7 +136,7 @@ function parseTargets(raw) {
     .filter(Boolean);
 }
 
-// FEAT-1: `failure_type` is OPTIONAL — an unset value is always fine. A set value
+// `failure_type` is OPTIONAL: an unset value is always fine. A set value
 // must be one of the eight enum members (same vocabulary lint enforces). Returns
 // an error string or null. Shared by create (validateClassification) and append.
 function failureTypeError(value) {
@@ -168,7 +168,7 @@ function validateClassification(args, targets) {
   const ftErr = failureTypeError(args.failureType);
   if (ftErr) errs.push(ftErr);
 
-  // CLAUDE.md projection candidates must be global + L1 (ADR 0031 §6 filter), and
+  // CLAUDE.md projection candidates must be global + L1 (SoT filter), and
   // carry the two conditional fields (lint #8). Enforce here so we never write a
   // claude-learned page that lint rejects or that silently never projects.
   if (targets.includes('claude-learned')) {
@@ -176,9 +176,8 @@ function validateClassification(args, targets) {
       errs.push('--global-summary is required when --targets includes claude-learned');
     if (!args.promoteToGlobal)
       errs.push('--promote-to-global is required when --targets includes claude-learned');
-    if (args.scope !== 'global')
-      errs.push('claude-learned projection requires --scope=global (ADR 0031 §6)');
-    if (args.tier !== 'L1') errs.push('claude-learned projection requires --tier=L1 (ADR 0031 §6)');
+    if (args.scope !== 'global') errs.push('claude-learned projection requires --scope=global');
+    if (args.tier !== 'L1') errs.push('claude-learned projection requires --tier=L1');
   }
   return errs;
 }
@@ -279,7 +278,7 @@ function writeFeedback(args, today) {
     // Append a dated entry; preserve existing frontmatter classification.
     mode = 'append';
     const existing = readFileSync(filePath, 'utf-8');
-    // FEAT-1: failure_type is a per-page classification property. On append,
+    // failure_type is a per-page classification property. On append,
     // set it if the page has none, error if it conflicts with an existing value,
     // no-op if it matches. Without the flag, append is byte-for-byte unchanged.
     const existingFt = (parseFrontmatter(existing) || {}).failure_type || null;
@@ -348,7 +347,7 @@ function writeFeedback(args, today) {
   return { wrote: true };
 }
 
-// ── projection post-step (ADR 0031) ────────────────────────────────────────────
+// ── projection post-step ────────────────────────────────────────────────────────
 
 // Refresh the MEMORY.md / CLAUDE.md projection from the just-written page. This
 // is best-effort and NON-blocking: a projection failure (over-cap, conflict,

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/page-usage.mjs

@@ -0,0 +1,141 @@
+// page-usage.mjs: read-only aggregation over .cache/page-usage.jsonl (B3)
+//
+// The lookup hook appends one JSONL record per injected page slug (see
+// hooks/hypo-shared.mjs recordLookupUsage). This lib reads that log and derives
+// "lookup-cold candidates": pages that have inbound wikilinks (so the graph
+// treats them as live) but have not been injected by lookup within a recency
+// window. It writes nothing and is only invoked from scripts (crystallize), so
+// it never touches the per-prompt hook hot path.
+
+import { readFileSync, existsSync } from 'fs';
+import { join } from 'path';
+import { collectPagesCrystallize, extractWikilinks, slugForms } from './wikilink.mjs';
+import { parseFrontmatter } from './frontmatter.mjs';
+
+const PAGE_USAGE_REL = '.cache/page-usage.jsonl';
+const DAY_MS = 86400000;
+
+// The distinct link forms a slug may appear as in a [[wikilink]] or in the log:
+// its full path, its basename, and (when nested) the path minus its first
+// segment. Matching by form-set intersection bridges the gap between the log's
+// index-matched slug form and the reverse index's [[wikilink]] form.
+function formSet(slug) {
+  const f = slugForms(slug);
+  const s = new Set([f.full, f.bare]);
+  if (f.dirRel) s.add(f.dirRel);
+  return s;
+}
+
+function intersects(a, b) {
+  for (const x of a) if (b.has(x)) return true;
+  return false;
+}
+
+// Read every record from the usage log, skipping malformed lines. Returns [] if
+// the log is absent or unreadable (fail-soft: aggregation is advisory).
+export function readPageUsage(hypoDir) {
+  const path = join(hypoDir, PAGE_USAGE_REL);
+  if (!existsSync(path)) return [];
+  let text;
+  try {
+    text = readFileSync(path, 'utf-8');
+  } catch {
+    return [];
+  }
+  const records = [];
+  for (const line of text.split('\n')) {
+    const trimmed = line.trim();
+    if (!trimmed) continue;
+    try {
+      const parsed = JSON.parse(trimmed);
+      // Only keep plain objects. A bare `null`, number, string, or array is
+      // valid JSON but not a record; keeping it would crash the field access in
+      // aggregateColdCandidates (and crystallize calls that outside a try).
+      if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {
+        records.push(parsed);
+      }
+    } catch {
+      // malformed line → skip (log is append-only and may be partially written)
+    }
+  }
+  return records;
+}
+
+// Derive lookup-cold candidates. Guards against cold-start: if there are no
+// records, or the observed log span is shorter than minLogSpanDays, returns
+// { status: 'insufficient-data' } so a fresh log doesn't flag the whole vault.
+// Otherwise returns { status: 'ok', candidates: [{ slug, title }] } for pages
+// that have >= 1 inbound wikilink from another page yet have not been logged
+// within the last thresholdDays.
+export function aggregateColdCandidates(
+  hypoDir,
+  { thresholdDays = 90, minLogSpanDays = 14, now = Date.now(), ignorePatterns = [] } = {},
+) {
+  const records = readPageUsage(hypoDir);
+  if (records.length === 0) return { status: 'insufficient-data', reason: 'no-records' };
+
+  const times = records.map((r) => Date.parse(r.ts)).filter((t) => Number.isFinite(t));
+  if (times.length === 0) return { status: 'insufficient-data', reason: 'no-timestamps' };
+  const span = Math.max(...times) - Math.min(...times);
+  if (span < minLogSpanDays * DAY_MS) {
+    return { status: 'insufficient-data', reason: 'span-too-short' };
+  }
+
+  // Forms of every slug logged within the recency window.
+  const recentCutoff = now - thresholdDays * DAY_MS;
+  const recentForms = new Set();
+  for (const r of records) {
+    const t = Date.parse(r.ts);
+    if (!Number.isFinite(t) || t < recentCutoff) continue;
+    if (typeof r.slug !== 'string' || !r.slug) continue;
+    for (const form of formSet(r.slug)) recentForms.add(form);
+  }
+
+  // Build the page list with slug, title, forms, and outbound links.
+  const pagesDir = join(hypoDir, 'pages');
+  const pageList = [];
+  for (const { path, rel } of collectPagesCrystallize(pagesDir, hypoDir, ignorePatterns)) {
+    let content;
+    try {
+      content = readFileSync(path, 'utf-8');
+    } catch {
+      continue;
+    }
+    const fm = parseFrontmatter(content);
+    if (!fm) continue;
+    const slug = rel.replace(/\.md$/, '');
+    const body = content.replace(/^---[\s\S]*?---/, '');
+    pageList.push({
+      slug,
+      title: fm.title || slug,
+      forms: formSet(slug),
+      links: extractWikilinks(body),
+    });
+  }
+
+  // Reverse index: which page slugs receive >= 1 inbound link from another page.
+  const formOwners = new Map(); // form → Set<page slug>
+  for (const p of pageList) {
+    for (const form of p.forms) {
+      if (!formOwners.has(form)) formOwners.set(form, new Set());
+      formOwners.get(form).add(p.slug);
+    }
+  }
+  const hasInbound = new Set();
+  for (const p of pageList) {
+    for (const link of p.links) {
+      const targets = new Set();
+      for (const form of formSet(link)) {
+        const owners = formOwners.get(form);
+        if (owners) for (const o of owners) targets.add(o);
+      }
+      for (const t of targets) if (t !== p.slug) hasInbound.add(t);
+    }
+  }
+
+  const candidates = pageList
+    .filter((p) => hasInbound.has(p.slug) && !intersects(p.forms, recentForms))
+    .map((p) => ({ slug: p.slug, title: p.title }));
+
+  return { status: 'ok', candidates };
+}

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) {