hypomnema 1.4.1 → 1.5.0

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/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:
  *
@@ -90,13 +90,31 @@ export function insertHotRow(content, name, today) {
  * @param {{hypoDir: string, name: string, workingDir: string, started?: string, today?: string}} opts
  * @returns {{created: string[], skipped: string[], warnings: string[], projectDir: string}}
  */
+/**
+ * A project name must be a SINGLE path segment with at least one alnum. The
+ * charset alone is not enough: `.`, `..`, `...` all pass `[A-Za-z0-9._-]+` yet
+ * would resolve `projects/<name>` to the wiki root or `projects/` itself (codex
+ * review 2026-05-22, both workers) — so dot-only names are rejected and ≥1 alnum
+ * required. The leading `typeof` guard lets non-CLI callers (e.g. a JSON payload
+ * where the value could be a number) reuse this without a JS regex coercing a
+ * non-string into a "valid" name. Shared so the apply path (crystallize.mjs B-3)
+ * accepts exactly the namespace createProject can scaffold — no wider, no narrower.
+ *
+ * @param {unknown} name
+ * @returns {boolean}
+ */
+export function isValidProjectName(name) {
+  return (
+    typeof name === 'string' &&
+    /^[A-Za-z0-9._-]+$/.test(name) &&
+    !/^\.+$/.test(name) &&
+    /[A-Za-z0-9]/.test(name)
+  );
+}
+
 export function createProject(opts) {
   const { name, workingDir } = opts;
-  // Name must be a single path segment with at least one alnum. The charset
-  // alone is not enough: `.`, `..`, `...` all pass `[A-Za-z0-9._-]+` yet would
-  // resolve `projects/<name>` to the wiki root or `projects/` itself (codex
-  // review 2026-05-22, both workers). Reject dot-only names and require alnum.
-  if (!name || !/^[A-Za-z0-9._-]+$/.test(name) || /^\.+$/.test(name) || !/[A-Za-z0-9]/.test(name)) {
+  if (!isValidProjectName(name)) {
     throw new Error(
       `invalid project name: ${JSON.stringify(name)} (need a single segment with ≥1 alnum, charset A-Za-z0-9._-, not "."/"..")`,
     );