hypomnema 1.4.1 → 1.5.0

package/scripts/lib/schema-vocab.mjs

@@ -1,4 +1,4 @@
-import { existsSync, readFileSync } from 'fs';
+import { existsSync, readFileSync, writeFileSync } from 'fs';
 import { join } from 'path';
 
 const VOCAB_HEADER_RE = /^##\s+(?:\d+\.\s+)?Tag\s+(?:Vocabulary|Taxonomy)\s*$/m;
@@ -66,6 +66,110 @@ export function parseSchemaVocab(hypoDir) {
   return vocab;
 }
 
+// Prose seeded into a freshly-created `### Pending` block. It carries NO
+// backtick tokens, so parseSchemaVocab's vocabLineTokens never mistakes it for a
+// vocabulary line — only the `**Pending**:` data line below it contributes tags.
+const PENDING_HEADING = '### Pending (auto-registered)';
+const PENDING_PROSE =
+  'Tags auto-registered by a crystallize close because they were not yet in the ' +
+  'vocabulary above. Review periodically: promote each into a category and delete ' +
+  'it here, or drop the tag from the page.';
+const PENDING_HEADING_RE = /^###[ \t]+Pending\b.*$/im; // prefix/word match
+const PENDING_DATA_RE = /^\*\*Pending[^*]*\*\*:.*$/im;
+const NEXT_H3_RE = /^###[ \t]+/m;
+const FORBIDDEN_HEADING_RE = /^###[ \t]+Forbidden\b/im;
+
+function backtickList(tags) {
+  return tags.map((t) => `\`${t}\``).join(', ');
+}
+
+// Auto-register unknown (non-forbidden) tags into the vault SCHEMA.md `### Pending`
+// section so a close never stalls on a vocabulary gap and the next lint sees them
+// as known (B-4). Pending lives INSIDE the "## Tag Vocabulary" H2 section because
+// parseSchemaVocab is H2-bounded — placing it elsewhere would not widen the vocab.
+// No-ops (returns []) when SCHEMA.md or the Tag Vocabulary header is absent, when
+// every tag is already in the vocabulary, or when a tag is forbidden — registering
+// a forbidden pattern is pointless (lint errors on it before the vocab check) and
+// would only pollute Pending. Idempotent: re-running with the same tags writes
+// nothing (they are already in the parsed vocabulary on the second call).
+export function appendPendingTags(hypoDir, tags) {
+  const path = join(hypoDir, 'SCHEMA.md');
+  if (!existsSync(path)) return [];
+  const content = readFileSync(path, 'utf-8');
+
+  const headerMatch = VOCAB_HEADER_RE.exec(content);
+  if (!headerMatch) return [];
+
+  const current = parseSchemaVocab(hypoDir);
+  const seen = new Set();
+  const newTags = [];
+  for (const raw of tags || []) {
+    const t = typeof raw === 'string' ? raw.trim() : '';
+    // A literal backtick cannot be serialized inside the backtick-delimited
+    // `**Pending**:` line — it would close the token early and make
+    // parseSchemaVocab mis-tokenize (or blank) the whole line, taking valid
+    // sibling tags down with it (codex stage-2 CONCERN). Skip it: the tag stays a
+    // non-blocking unknown-tag warn the author can rename. (A `"` is safe — it
+    // round-trips between backticks — so only the backtick is rejected.)
+    if (!t || t.includes('`') || seen.has(t) || current.has(t) || checkForbidden(t)) continue;
+    seen.add(t);
+    newTags.push(t);
+  }
+  if (newTags.length === 0) return [];
+
+  const sectionStart = headerMatch.index + headerMatch[0].length;
+  const rest = content.slice(sectionStart);
+  const nextH2 = NEXT_H2_RE.exec(rest);
+  const sectionEnd = nextH2 ? sectionStart + nextH2.index : content.length;
+  const section = content.slice(sectionStart, sectionEnd);
+
+  let newSection;
+  const heading = PENDING_HEADING_RE.exec(section);
+  if (heading) {
+    // Pending subsection exists — bound it (heading → next H3 or section end) and
+    // either extend its `**Pending**:` data line or seed one if the block is empty
+    // (the template ships heading + prose with no tags yet).
+    const subStart = heading.index;
+    const after = section.slice(heading.index + heading[0].length);
+    const nextH3 = NEXT_H3_RE.exec(after);
+    const subEnd = nextH3 ? heading.index + heading[0].length + nextH3.index : section.length;
+    const sub = section.slice(subStart, subEnd);
+
+    const dataMatch = PENDING_DATA_RE.exec(sub);
+    let newSub;
+    if (dataMatch) {
+      const existing = [];
+      for (const m of dataMatch[0].matchAll(BACKTICK_TOKEN_RE)) {
+        const t = m[1].trim();
+        if (t && !t.includes(' ')) existing.push(t);
+      }
+      const merged = [...existing, ...newTags];
+      const dataLine = `**Pending**: ${backtickList(merged)}`;
+      newSub =
+        sub.slice(0, dataMatch.index) + dataLine + sub.slice(dataMatch.index + dataMatch[0].length);
+    } else {
+      const dataLine = `**Pending**: ${backtickList(newTags)}`;
+      newSub = `${sub.replace(/\s*$/, '')}\n\n${dataLine}\n`;
+    }
+    newSection = section.slice(0, subStart) + newSub + section.slice(subEnd);
+  } else {
+    // No Pending block yet — build one and place it before "### Forbidden patterns"
+    // if present (Pending is vocabulary; Forbidden is a separate concern), else at
+    // the end of the Tag Vocabulary section.
+    const block = `${PENDING_HEADING}\n\n${PENDING_PROSE}\n\n**Pending**: ${backtickList(newTags)}\n`;
+    const forbidden = FORBIDDEN_HEADING_RE.exec(section);
+    if (forbidden) {
+      newSection =
+        section.slice(0, forbidden.index) + `${block}\n` + section.slice(forbidden.index);
+    } else {
+      newSection = `${section.replace(/\s*$/, '')}\n\n${block}\n`;
+    }
+  }
+
+  writeFileSync(path, content.slice(0, sectionStart) + newSection + content.slice(sectionEnd));
+  return newTags;
+}
+
 // Derive the set of valid immediate subdirectories under pages/ from the
 // SCHEMA "Page Type Taxonomy" table (e.g. learnings, feedback, people). Single
 // source of truth — adding a type+dir row to SCHEMA automatically widens the

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)) {
@@ -426,7 +426,15 @@ function lintPage({ path, rel }, slugMap, tagVocab, pageDirs, validTypes) {
         continue;
       }
       if (!tagVocab.has(tag)) {
-        issue('error', rel, `Unknown tag: "${tag}" (not in SCHEMA.md Tag Vocabulary)`);
+        // W10 (B-4): an unknown but non-forbidden tag is a WARNING, not a hard
+        // error — a session close must never stall on a vocabulary gap. The
+        // crystallize apply path parses these warns (by this exact message
+        // string — load-bearing, see scripts/crystallize.mjs auto-register block)
+        // and registers them into SCHEMA.md's `### Pending` section, so the next
+        // lint sees them as known. W10 is intentionally NOT in STRICT_PROMOTE_IDS:
+        // an unregistered tag is a vocabulary lag, not a content defect, so even
+        // `--strict` keeps it a warning (it only surfaces the id in --json output).
+        issue('warn', rel, `Unknown tag: "${tag}" (not in SCHEMA.md Tag Vocabulary)`, null, 'W10');
       }
     }
   }

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

package/scripts/resume.mjs

@@ -26,10 +26,10 @@
  *   --json                Output as JSON
  */
 
-import { existsSync, readFileSync, readdirSync, statSync } from 'fs';
+import { existsSync, readFileSync, readdirSync, statSync, realpathSync } from 'fs';
 import { join } from 'path';
-import { homedir } from 'os';
 import { resolveHypoRoot, expandHome } from './lib/hypo-root.mjs';
+import { pickProjectByCwd, collectProjectWorkingDirs } from './lib/wd-match.mjs';
 
 // ── arg parsing ──────────────────────────────────────────────────────────────
 
@@ -60,27 +60,25 @@ function parseFrontmatterField(content, key) {
     .replace(/^['"]|['"]$/g, '');
 }
 
-// Among `slugs`, return the one whose projects/<slug>/index.md `working_dir`
-// is the LONGEST prefix of cwd (so /repo/sub wins over /repo). Returns null
-// when cwd is falsy or matches none. resume gives this authority OVER recency
-// (ADR 0044): a cwd↔working_dir match wins regardless of which row is newest.
+// Return the project (among `slugs`) that owns cwd: a longest-prefix
+// working_dir match, or — when no absolute path matches because the vault was
+// synced from another machine — a cwd ancestor whose directory name is a
+// globally-unique project basename. Uniqueness is judged over EVERY project on
+// disk (not just `slugs`), so a shared dirname declines and falls back to
+// recency. resume gives this authority over recency: a cwd↔project match wins
+// regardless of which hot.md row is newest.
 function pickByCwd(hypoDir, slugs, cwd) {
   if (!cwd) return null;
-  let best = null;
-  let bestLen = -1;
-  for (const slug of slugs) {
-    const indexPath = join(hypoDir, 'projects', slug, 'index.md');
-    if (!existsSync(indexPath)) continue;
-    const wd = parseFrontmatterField(readFileSync(indexPath, 'utf-8'), 'working_dir');
-    if (!wd) continue;
-    let resolved = wd.startsWith('~/') ? join(homedir(), wd.slice(2)) : wd;
-    resolved = resolved.replace(/\/+$/, ''); // trailing-slash normalize
-    if ((cwd === resolved || cwd.startsWith(resolved + '/')) && resolved.length > bestLen) {
-      bestLen = resolved.length;
-      best = slug;
-    }
+  let realpathCwd = null;
+  try {
+    realpathCwd = realpathSync(cwd);
+  } catch {
+    realpathCwd = null;
   }
-  return best;
+  return pickProjectByCwd(collectProjectWorkingDirs(hypoDir), cwd, {
+    eligible: slugs,
+    realpathCwd,
+  });
 }
 
 // When cwd is set but no project's working_dir matches it, resume falls back to
@@ -125,11 +123,11 @@ function resolveActiveProject(hypoDir, cwd = null) {
     ),
   ].map((m) => ({ name: m[1].trim(), date: m[2] || '', slug: m[3] }));
   if (wikiRows.length > 0) {
-    // cwd-first (ADR 0044): a cwd↔working_dir match wins over recency, across
+    // cwd-first: a cwd↔working_dir match wins over recency, across
     // ALL rows (not just a same-date tie). The user is physically in that
     // project, so cwd is a stronger intent signal than "some other project was
     // touched more recently". This reverses the earlier tie-breaker-only
-    // semantics now that resume=cwd-positive (ADR 0043). Tradeoff: a stale cwd
+    // semantics now that resume=cwd-positive. Tradeoff: a stale cwd
     // match can mask a genuinely newer project; `--project` overrides. close
     // callers pass null → recency path below (resume=cwd-positive / close=no-pick).
     if (cwd) {

package/scripts/session-audit.mjs

@@ -6,7 +6,7 @@
  * (search count, ingest count, URLs mentioned, feedback count) so the
  * weekly observability report (Lane E) can compute autonomy scores.
  *
- * Transcript dual-source (ADR 0019):
+ * Transcript dual-source:
  *   1) Primary: <hypo-dir>/.cache/sessions/index.jsonl
  *      Written by hooks/hypo-session-record.mjs (Stop hook).
  *   2) Fallback: ~/.claude/projects/<encoded>/*.jsonl

package/scripts/stats.mjs

@@ -48,8 +48,8 @@ function collectMdFiles(dir, acc = [], hypoDir = '', ignorePatterns = []) {
 // Local top-level-only extractor, behavior-aligned with lib/frontmatter.mjs:
 // skip indented / list lines, first-wins, strip a trailing `# comment`. Without
 // the comment strip a `failure_type: overreach # note` would aggregate under the
-// literal "overreach # note" key (FEAT-1). Kept local (not the shared import) to
-// hold stats' dependency surface flat per the FEAT-1 scope split.
+// literal "overreach # note" key. Kept local (not the shared import) to
+// hold stats' dependency surface flat per the scope split.
 function parseFrontmatter(content) {
   const m = content.match(/^---\r?\n([\s\S]*?)\r?\n---/);
   if (!m) return null;
@@ -101,7 +101,7 @@ const sources = existsSync(join(args.hypoDir, 'sources'))
   : [];
 
 const typeCounts = {};
-const failureTypeCounts = {}; // FEAT-1: feedback pages carrying a failure_type
+const failureTypeCounts = {}; // feedback pages carrying a failure_type
 let missingFrontmatter = 0;
 
 for (const f of pageFiles) {

package/scripts/uninstall.mjs

@@ -15,7 +15,7 @@
  *   --force-extensions   Remove user-modified extension files (hypo-ext-*) instead of preserving them
  *   --hooks-dir=<path>   Override Claude hooks directory (default: ~/.claude/hooks)
  *
- * Extensions (ADR 0024): hypo-ext-* hard-copies under
+ * Extensions: hypo-ext-* hard-copies under
  * ~/.claude/{hooks,commands,skills,agents}/ and ~/.codex/{hooks,commands}/ (with
  * --codex) are removed when their on-disk SHA matches the recorded one in
  * ~/.claude/hypo-pkg.json#extensions.<target>. User-modified copies are preserved
@@ -94,7 +94,7 @@ function removeCommands(apply, force) {
   return { removed, skippedUserModified, skippedNonRegular };
 }
 
-// ── extensions removal (ADR 0024) ───────────────────────────────────
+// ── extensions removal ───────────────────────────────────
 
 // Strip per-target extension SHA records from ~/.claude/hypo-pkg.json. Surgical:
 // we only touch the entries for keys we actually removed, so a `--force-extensions`
@@ -424,7 +424,7 @@ const hookResult = removeHookFiles(claudeHooksDir, hookFiles, args.apply);
 const settingsResult = stripSettingsJson(claudeSettings, claudeHooksDir, hookMap, args.apply);
 const commandResult = removeCommands(args.apply, args.forceCommands);
 
-// Extensions (ADR 0024). Order matters: remove files first, then strip
+// Extensions. Order matters: remove files first, then strip
 // settings, then surgically clear the per-target SHA map. The SHA strip uses
 // removedKeys so a user-modified file we left in place keeps its recorded SHA
 // (doctor still has a baseline next run). Settings are path-based and run even

package/scripts/upgrade.mjs

@@ -20,7 +20,7 @@
  *                       the user-extensions companion sync (E4).
  *   --json              Output results as JSON
  *   --allow-downgrade   Override the guard that refuses to overwrite a NEWER
- *                       active install with an older package (ADR 0038)
+ *                       active install with an older package
  *   --allow-dual-install  Override the dual-install guard: register the Claude core
  *                       surface even though the Hypomnema plugin is also enabled
  *                       (knowingly accept the double-registration risk)
@@ -235,7 +235,7 @@ function checkSchemaVersion(hypoDir) {
 
 // Target-aware: the same core-hook integrity check runs against ~/.claude/hooks/
 // for the default claude target, and against ~/.codex/hooks/ when --codex is set
-// (ADR 0024). The function reads only — apply happens in applyHookFiles.
+// The function reads only (apply happens in applyHookFiles).
 function checkHookFiles(hooksDir) {
   const results = [];
 
@@ -473,15 +473,15 @@ function writeMigrationReport(hypoDir, fromVersion, toVersion, { pluginMode = fa
   // Don't overwrite an existing report
   if (existsSync(dest)) return dest;
 
-  // v1 → v2 specific guidance for the ADR 0031 feedback classification bump.
-  // Other major jumps fall back to the generic body. ADR 0034 reserves the
-  // right to keep SCHEMA.md as user-owned (Option C); auto-stub of the 9 new
-  // fields is rejected because scope/tier/targets/sensitivity/reason/source
-  // are semantic decisions whose wrong defaults would project wrong behavior.
-  // Fire for any 1.x → 2.x major crossing, not just 1.0 → 2.0 exactly: the ADR
-  // 0031 feedback-field backfill that this body explains was introduced at 2.0
+  // v1 → v2 specific guidance for the feedback classification bump. Other major
+  // jumps fall back to the generic body. The schema deliberately keeps SCHEMA.md
+  // user-owned (Option C); auto-stub of the 9 new fields is rejected because
+  // scope/tier/targets/sensitivity/reason/source are semantic decisions whose
+  // wrong defaults would project wrong behavior.
+  // Fire for any 1.x → 2.x major crossing, not just 1.0 → 2.0 exactly: the
+  // feedback-field backfill that this body explains was introduced at 2.0
   // and still applies to a user landing on any later 2.x (e.g. 2.1's additive
-  // failure_type — FEAT-1). Keying on the exact target string would silently
+  // failure_type). Keying on the exact target string would silently
   // drop this guidance the moment the template minor moves.
   const fromV = parseVersion(fromVersion);
   const toV = parseVersion(toVersion);
@@ -489,8 +489,7 @@ function writeMigrationReport(hypoDir, fromVersion, toVersion, { pluginMode = fa
   const specificBody = isV1ToV2
     ? `## What changed in SCHEMA 2.0
 
-ADR 0031 (\`projects/hypomnema/decisions/0031-feedback-as-sot-external-memory-projection.md\`)
-made \`feedback\` pages the single source of truth for behavior corrections and added
+This release made \`feedback\` pages the single source of truth for behavior corrections and added
 **9 hard-required frontmatter fields** for every \`feedback\` page:
 
 - \`status\` (active | superseded | archived)
@@ -510,8 +509,8 @@ that does not satisfy all four is rejected by both \`hypomnema lint\` and
 \`hypomnema feedback\` (see \`scripts/lint.mjs\` and \`scripts/feedback.mjs\`
 enforcement).
 
-ADR 0034 records this schema bump and the reasoning (semver-major because
-existing feedback pages without these fields now fail \`hypomnema lint\`).
+This schema bump is semver-major because existing feedback pages without these
+fields now fail \`hypomnema lint\`.
 
 ## Action items — existing wiki
 
@@ -799,7 +798,7 @@ function writePluginModeMetadata() {
 const args = parseArgs(process.argv);
 
 // Target paths. Claude is always checked; codex is checked only when --codex is set
-// (ADR 0024) so users without codex installed see no false drift.
+// so users without codex installed see no false drift.
 const claudeHooksDir = join(HOME, '.claude', 'hooks');
 const claudeSettingsPath = join(HOME, '.claude', 'settings.json');
 const codexHooksDir = join(HOME, '.codex', 'hooks');
@@ -858,7 +857,7 @@ const hooksCodex = args.codex ? checkHookFiles(codexHooksDir) : null;
 const settingsCodex = args.codex ? checkSettingsJson(codexSettingsPath, codexHooksDir) : null;
 const oldHookRefsCodex = args.codex ? checkOldHookNames(codexSettingsPath) : null;
 
-// Extensions companion (ADR 0024). Read-only check; the apply
+// Extensions companion. Read-only check; the apply
 // happens below, AFTER applyCommands, so the per-target SHA map merges into the
 // hypo-pkg.json that applyCommands writes (rather than being clobbered by it).
 const extSettingsPath = claudeSettingsPath;
@@ -935,7 +934,7 @@ let appliedExtensions = null;
 let appliedExtensionsCodex = null;
 
 if (args.apply) {
-  // Downgrade guard (ADR 0038, P): an `--apply` from an OLDER package than the
+  // Downgrade guard: an `--apply` from an OLDER package than the
   // active install would overwrite newer hooks (upgrade.mjs:287 copyFileSync) and
   // rewrite hypo-pkg.json to the older version. Refuse before the first mutation.
   // A dev workspace re-running its own --apply (incl. the post-commit sync hook)
@@ -1370,7 +1369,7 @@ if (hypoignore.status === 'no-file') {
   for (const e of hypoignore.missing) lines.push(`    + ${e.pattern}`);
 }
 
-// Extensions companion (ADR 0024; conflict/drift gating E3, #31). Shared by the
+// Extensions companion (conflict/drift gating E3, #31). Shared by the
 // claude target and, under --codex, the codex target (E4, #32) — the label keeps
 // the two blocks distinguishable in the report.
 function pushExtSummary(check, label) {