hypomnema 1.8.2 → 1.9.0

package/scripts/lib/hook-inventory.mjs

@@ -0,0 +1,180 @@
+// hook-inventory.mjs — the one grammar every hooks.json/shared.json consumer reads
+// through: smoke-plugin.mjs, init.mjs, upgrade.mjs, doctor.mjs, uninstall.mjs.
+//
+// Before this file existed, five scripts each grew their own regex for pulling a
+// .mjs basename out of a hooks.json `command` string, and the five disagreed:
+//   - smoke-plugin accepted ANY path after `${CLAUDE_PLUGIN_ROOT}/`, so a command
+//     pointing at `${CLAUDE_PLUGIN_ROOT}/scripts/foo.mjs` (the wrong directory —
+//     init only ever copies hooks/) passed smoke as long as that file happened to
+//     exist, while init/upgrade/doctor/uninstall all resolve the same command to
+//     `hooks/foo.mjs` and never look in scripts/ at all.
+//   - init/upgrade/doctor took the LAST `.mjs` path segment in the command, so a
+//     trailing argument like `--config bar.mjs` would have picked `bar.mjs` up as
+//     the hook file instead of the hook itself.
+//   - uninstall anchored on `/hooks/([^/\s]+\.mjs)$` — the command had to literally
+//     END in `.mjs`, so the same trailing-argument shape it would silently ignore
+//     instead of misreading.
+// One parser closes all three gaps by only ever accepting one shape.
+//
+// This module also folds in the existence check that used to be missing entirely:
+// loadHookInventory() only returns ok:true once every name on both lists resolves
+// to a real regular file under `<pkgRoot>/hooks/`. A caller that runs this BEFORE
+// its first write (as init.mjs now does) can never install a partial hook set from
+// a package a file was dropped out of.
+//
+// Deliberately does NOT accept the legacy bare-filename group format
+// (`"hooks.json"`: `{ "SomeEvent": ["foo.mjs"] }`) that ../core-hooks.mjs's
+// readCoreHooksConfig still tolerates for reverse-capture's basename reservation.
+// That tolerance exists so a stale or hand-edited hooks.json never lets a core
+// hook slip into a user's captured extensions; it has nothing to do with what
+// install/uninstall are willing to act on, so narrowing the grammar here does not
+// need to touch core-hooks.mjs at all.
+
+import { join } from 'node:path';
+import { readCoreHooksConfig } from './core-hooks.mjs';
+import { isRegularFile } from './pkg-json.mjs';
+
+// A plain .mjs basename: word characters, dots, and hyphens only, no path
+// separator (so a joined path can never climb out of the directory it is joined
+// onto) and no leading dot (rules out a hidden file and `..`, which does not
+// match `\w` but a bare `.` prefix like `.mjs` alone still would). Mirrors the
+// basename check smoke-plugin.mjs already applied to hooks/shared.json entries.
+const SAFE_MJS_BASENAME = /^[\w.-]+\.mjs$/;
+
+export function isSafeMjsBasename(name) {
+  return typeof name === 'string' && SAFE_MJS_BASENAME.test(name) && !name.startsWith('.');
+}
+
+// The one command shape this module accepts: `${CLAUDE_PLUGIN_ROOT}/hooks/<basename>.mjs`,
+// optionally followed by more of the command (a trailing argument, a redirect —
+// anything after whitespace or a closing quote). No sub-directory under hooks/,
+// no other top-level directory, no bare filename with no `${CLAUDE_PLUGIN_ROOT}/hooks/`
+// prefix at all.
+const PLUGIN_HOOKS_TARGET = /\$\{CLAUDE_PLUGIN_ROOT\}\/hooks\/([^\s/"'`]+)(?=$|[\s"'`])/;
+
+/**
+ * Extract the hooks/<basename>.mjs a command string targets, or null when the
+ * command does not match the one accepted shape (wrong directory, a
+ * sub-directory, a basename that fails isSafeMjsBasename, or no
+ * `${CLAUDE_PLUGIN_ROOT}/hooks/` segment at all).
+ */
+export function extractPluginHookBasename(command) {
+  if (typeof command !== 'string') return null;
+  const m = command.match(PLUGIN_HOOKS_TARGET);
+  if (!m) return null;
+  return isSafeMjsBasename(m[1]) ? m[1] : null;
+}
+
+/**
+ * Load, narrowly validate, and existence-check the hook inventory rooted at
+ * `pkgRoot`: hooks/hooks.json's per-event basenames plus hooks/shared.json's
+ * shared-module basenames. Fails closed on the FIRST problem, whether that is a
+ * read/parse failure (delegated to readCoreHooksConfig), an empty hooks map, a
+ * command that does not match the one accepted grammar, an unsafe shared.json
+ * basename, or a named file that is not actually a regular file under
+ * `<pkgRoot>/hooks/`.
+ *
+ * @param {string} pkgRoot
+ * @returns {{ ok: true, hookMap: Record<string, string[]>, shared: string[] }
+ *   | { ok: false, error: string }}
+ */
+export function loadHookInventory(pkgRoot) {
+  const res = readCoreHooksConfig(pkgRoot);
+  if (!res.ok) return { ok: false, error: res.error };
+  const cfg = res.cfg;
+
+  if (Object.keys(cfg.hooks).length === 0) {
+    return { ok: false, error: 'hooks/hooks.json "hooks" must not be empty' };
+  }
+
+  const hookMap = {};
+  for (const [event, groups] of Object.entries(cfg.hooks)) {
+    const basenames = [];
+    for (const group of groups) {
+      // readCoreHooksConfig still accepts a bare-filename group (the legacy
+      // shape reverse-capture's basename reservation tolerates on purpose — see
+      // the module header). Every real install/uninstall consumer of THIS
+      // function only ever shipped the hook-group object form, so a bare string
+      // reaching here is not something any of the five knows how to act on.
+      if (typeof group === 'string') {
+        return {
+          ok: false,
+          error: `hooks.${event}: a bare filename group ("${group}") is not accepted here — wrap it in a hook-group object with an explicit command`,
+        };
+      }
+      if (!Array.isArray(group.hooks) || group.hooks.length === 0) {
+        return {
+          ok: false,
+          error: `hooks.${event}: a hook group must have a non-empty "hooks" array`,
+        };
+      }
+      for (const hook of group.hooks) {
+        if (hook.type !== 'command') {
+          return { ok: false, error: `hooks.${event}: hook entry "type" must be "command"` };
+        }
+        const base = extractPluginHookBasename(hook.command);
+        if (!base) {
+          return {
+            ok: false,
+            error: `hooks.${event}: command does not match "\${CLAUDE_PLUGIN_ROOT}/hooks/<basename>.mjs": ${hook.command}`,
+          };
+        }
+        basenames.push(base);
+      }
+    }
+    if (basenames.length === 0) {
+      return { ok: false, error: `hooks.${event} yields no hook files` };
+    }
+    hookMap[event] = basenames;
+  }
+
+  for (const file of cfg.shared) {
+    if (!isSafeMjsBasename(file)) {
+      return { ok: false, error: `hooks/shared.json: "${file}" is not a plain .mjs basename` };
+    }
+  }
+
+  // Existence, checked last and over the UNION of both lists: a caller that
+  // reaches this point has already paid for the grammar checks above, and a
+  // missing file (dropped from `package.json`'s `files` allowlist, or from a
+  // corrupted copy) is exactly the gap major C closed — nothing may be
+  // installed, refreshed, or reported healthy on the strength of a name alone.
+  const allBasenames = new Set([...Object.values(hookMap).flat(), ...cfg.shared]);
+  for (const base of allBasenames) {
+    if (!isRegularFile(join(pkgRoot, 'hooks', base))) {
+      return { ok: false, error: `hooks/${base} is not a file` };
+    }
+  }
+
+  return { ok: true, hookMap, shared: cfg.shared, ordered: installOrder(hookMap, cfg.shared) };
+}
+
+/**
+ * The order the hook files must be written to an install, and the reverse of
+ * the order they must be removed in.
+ *
+ * Shared modules first. An entry hook copied ahead of a module it imports is
+ * live against something that may not be there yet if the run is interrupted,
+ * and the session that would have run the repair is the one that then cannot
+ * start. The reverse order leaves the harmless state instead: an updated shared
+ * module under an entry hook that has not caught up.
+ *
+ * It lives here so init, upgrade and uninstall read one list rather than each
+ * deriving its own. They did derive their own, and the three sets were not even
+ * equal: init copied every `.mjs` in the directory, which pulled in
+ * `hypo-pre-commit.mjs` (invoked from the package root, never from the install)
+ * and left a copy in every install that upgrade would not refresh, doctor would
+ * not report, and uninstall would not remove.
+ *
+ * Alphabetical order puts today's shared modules first by luck; a shared module
+ * named later in the alphabet would take that away with nothing failing.
+ */
+export function installOrder(hookMap, shared) {
+  const sharedList = Array.isArray(shared) ? shared.filter((f) => typeof f === 'string') : [];
+  const sharedSet = new Set(sharedList);
+  const entries = [];
+  for (const file of Object.values(hookMap).flat()) {
+    if (!sharedSet.has(file) && !entries.includes(file)) entries.push(file);
+  }
+  return [...sharedList, ...entries];
+}

package/scripts/lib/page-usage.mjs

@@ -11,10 +11,10 @@ import { readFileSync, existsSync } from 'fs';
 import { join } from 'path';
 import { collectPagesCrystallize, extractWikilinks, slugForms } from './wikilink.mjs';
 import { parseFrontmatter } from './frontmatter.mjs';
+import { DAY_MS } from './time.mjs';
 import { currentDevice, scopeVisible, readVisibilityScope } from '../../hooks/hypo-shared.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

package/scripts/lib/pkg-provenance.mjs

@@ -106,6 +106,14 @@ export function provenancePath(hooksDir) {
  * it is a doctor-only freshness signal, not part of the runtime contract
  * (hooks/hypo-shared.mjs never reads this field), so a sidecar the runtime
  * can verify should not be withheld just because the digest step failed.
+ *
+ * `managedFiles` (major D) is the same best-effort shape: the sorted basename
+ * list this run's own copy targeted (every hooks.json event command plus every
+ * hooks/shared.json entry, derived from `pkgRoot` the same way the digest
+ * above is). scripts/uninstall.mjs reads it back as a fallback source of truth
+ * when THIS package's own hooks.json can no longer be read at uninstall time —
+ * the sidecar was written by whatever package last actually ran the copy, so it
+ * names the truth of what is on disk even after the current package rots.
  */
 export function writeProvenanceSidecar(hooksDir, pkgRoot, pkgVersion, hooksSrcDir, dryRun) {
   let hypoSharedSha256;
@@ -115,12 +123,15 @@ export function writeProvenanceSidecar(hooksDir, pkgRoot, pkgVersion, hooksSrcDi
     return null;
   }
   const hooksDigest = computeHooksDigest(pkgRoot, hooksSrcDir);
+  const cfgRes = readCoreHooksConfig(pkgRoot);
+  const managedFiles = cfgRes.ok ? [...deriveCoreHookBasenames(cfgRes.cfg)].sort() : null;
   const dest = provenancePath(hooksDir);
   const data = {
     pkgRoot,
     pkgVersion,
     hypoSharedSha256,
     ...(hooksDigest ? { [HOOKS_DIGEST_FIELD]: hooksDigest } : {}),
+    ...(managedFiles ? { managedFiles } : {}),
     copiedAt: new Date().toISOString(),
   };
   if (!dryRun) atomicWriteJson(dest, data);
@@ -135,8 +146,14 @@ export function writeProvenanceSidecar(hooksDir, pkgRoot, pkgVersion, hooksSrcDi
 // filesystem boundary would fall back to a non-atomic copy+delete.
 function atomicWriteJson(dest, data) {
   const tmp = `${dest}.${process.pid}.${Math.random().toString(36).slice(2)}.tmp`;
-  writeFileSync(tmp, JSON.stringify(data, null, 2) + '\n');
+  // The write is inside the try as well as the rename. A write that fails
+  // partway (ENOSPC, EDQUOT) has already created the temp file, and the temp
+  // name carries this pid and a fresh random, so nothing ever picks it up
+  // again: it would sit next to the sidecar forever. Not switched to the
+  // shared hooks/atomic-write.mjs because that one mkdirSync's the parent,
+  // which this path deliberately leaves to its caller.
   try {
+    writeFileSync(tmp, JSON.stringify(data, null, 2) + '\n');
     renameSync(tmp, dest);
   } catch (err) {
     try {

package/scripts/lib/plugin-detect.mjs

@@ -98,14 +98,20 @@ function readPkgVersionAt(root) {
   }
 }
 
-// A pkgRoot is "usable" as a DURABLE install root only if it is an ABSOLUTE path to
-// a real package directory whose package.json carries a version. A relative path
-// (e.g. installPath ".") would be resolved against the caller's cwd and break the
-// vault git hook from any other directory; a version-less package.json cannot be
-// attributed a version without lying. A bare path that merely exists is a pointer
-// the runtime cannot resolve scripts through. Shared by init's registry resolution,
-// its durable-root fallback, and upgrade's dualSkip provenance correction so they
-// all agree on what is real.
+// A pkgRoot is "usable" only if it is an ABSOLUTE path to a real package directory
+// whose package.json carries a version. A relative path (e.g. installPath ".")
+// would be resolved against the caller's cwd and break the vault git hook from any
+// other directory; a version-less package.json cannot be attributed a version
+// without lying. This is the WEAK predicate: it says nothing about WHOSE package
+// sits at that path, only that a version can be read from it. That is enough for a
+// diagnostic that reads and reports (doctor.mjs's per-row leaf-drift scan, which
+// deliberately widens rather than narrows — see leafVersionDrift above), but it is
+// NOT enough for a caller that adopts the path as Hypomnema's own durable identity
+// and writes it to a sidecar (hypo-pkg.json) or a vault's pre-commit hook: nothing
+// here stops a foreign package at an absolute, version-bearing path from being
+// adopted as if it were this one. isHypomnemaInstallRoot below is the strong
+// predicate for that case; keep the two in sync; a change to one's shape
+// (absolute + version) almost certainly belongs in the other too.
 export function usablePkgRoot(pkgRoot) {
   return (
     typeof pkgRoot === 'string' &&
@@ -116,6 +122,26 @@ export function usablePkgRoot(pkgRoot) {
   );
 }
 
+// The STRONG predicate: usablePkgRoot, AND the package at that path is literally
+// named "hypomnema". A registry or hypo-pkg.json entry can carry any absolute,
+// version-bearing path — a corrupted sidecar, a hand-edited registry row, or (per
+// the commit-time resolver's own `usable()` in git-hooks-dir.mjs) an attacker's
+// project — so a caller that RECORDS a root as durable identity (init.mjs's
+// resolveDurableRoot, selectEntry below) or WRITES it back to disk (upgrade.mjs's
+// dualSkip provenance correction) must check producer identity, not just
+// "a version is readable here". A caller that only READS for display (doctor.mjs's
+// per-row leaf scan) stays on the weak usablePkgRoot: narrowing it would silence a
+// foreign registry row doctor exists to surface, per the "does NOT exclude"
+// rationale on leafVersionDrift above.
+export function isHypomnemaInstallRoot(pkgRoot) {
+  if (!usablePkgRoot(pkgRoot)) return false;
+  try {
+    return JSON.parse(readFileSync(join(pkgRoot, 'package.json'), 'utf-8')).name === 'hypomnema';
+  } catch {
+    return false;
+  }
+}
+
 // The version-shaped leaf of a plugin cache path (its last path component), or
 // null when that leaf does not look like a version. Claude Code names a plugin
 // cache directory after the release it copied in (`cache/<marketplace>/<name>/
@@ -185,10 +211,18 @@ export function leafVersionDrift(pkgRoot) {
 // #269 reimplemented this exact filter-then-prefer-scope rule at its call site,
 // in the opposite order, which silently swaps rows whenever the user row has no
 // gitCommitSha).
+// isHypomnemaInstallRoot, not the weak usablePkgRoot: this is the row
+// resolveEnabledPluginEntry hands to callers that RECORD it as durable identity
+// (init.mjs's resolveDurableRoot, upgrade.mjs's dualSkip provenance write), so a
+// registry row whose installPath merely resolves a readable version, without
+// being a real Hypomnema package, must not be selected here. codex reproduction
+// (2026-09-11): a registry row's package.json carried no `name` field at all and
+// was still adopted as the durable root under the old, name-blind check.
 function selectEntry(entries, scope) {
   return (
     entries.find(
-      (e) => e && (scope === undefined || e.scope === scope) && usablePkgRoot(e.installPath),
+      (e) =>
+        e && (scope === undefined || e.scope === scope) && isHypomnemaInstallRoot(e.installPath),
     ) ?? null
   );
 }

package/scripts/lib/project-create.mjs

@@ -10,7 +10,14 @@
  *   2. copy templates/projects/_template/*.md with token substitution
  *        <project-name> → name, <started> → date, <working_dir> → cwd,
  *        YYYY-MM-DD     → today  (frontmatter `updated:` only)
- *   3. append a row to root hot.md "Active Projects" table
+ *   3. regenerate root hot.md's "Active Projects" table via the canonical
+ *      projection (writeRootHotProjection, hooks/hypo-shared.mjs), which
+ *      picks up this project's own row from the directory scan step 2 just
+ *      wrote, never a hand-inserted row. A direct table edit here (the old
+ *      insertHotRow) left the ownership hash pointing at whatever a
+ *      session's projection write last produced, so the next SessionStart or
+ *      Stop read this edit as external and backed it up with a false "손으로
+ *      편집한 내용이 있었습니다" alarm on every normal project creation.
  *   4. append a `## [today] project-create | <name>` entry to log.md
  *
  * Idempotent: existing files/rows/entries are preserved, never overwritten or
@@ -25,6 +32,7 @@ import { readFileSync, writeFileSync, existsSync, mkdirSync, readdirSync } from
 import { join, dirname, resolve, sep } from 'path';
 import { fileURLToPath } from 'url';
 import { resolveHypoRoot, expandHome } from './hypo-root.mjs';
+import { writeRootHotProjection, rootHotBackupRecoveryNotice } from '../../hooks/hypo-shared.mjs';
 
 const SCRIPT_DIR = dirname(fileURLToPath(import.meta.url));
 const PKG_ROOT = join(SCRIPT_DIR, '..', '..');
@@ -57,35 +65,6 @@ export function substituteTokens(content, { name, started, workingDir, today })
     .join(today);
 }
 
-/**
- * Insert a project row into the root hot.md "Active Projects" table.
- * Idempotent: returns the original content unchanged if a row already links
- * to `[[projects/<name>/hot]]`. Returns null if the table cannot be located.
- * @returns {string|null} new content, or null when no table marker is found
- */
-export function insertHotRow(content, name, today) {
-  const link = `[[projects/${name}/hot]]`;
-  if (content.includes(link)) return content; // already present
-  const lines = content.split('\n');
-  // Scope the search to the "## Active Projects" section so a table appearing
-  // earlier in hot.md can't capture the row. Start looking from the heading;
-  // stop at the next H2 so we never cross sections.
-  const headingIdx = lines.findIndex((l) => /^##\s+Active Projects\s*$/.test(l));
-  if (headingIdx === -1) return null;
-  let sepIdx = -1;
-  for (let i = headingIdx + 1; i < lines.length; i++) {
-    if (/^##\s/.test(lines[i])) break; // next section — table not found in scope
-    if (/^\|\s*-{2,}\s*\|/.test(lines[i])) {
-      sepIdx = i;
-      break;
-    }
-  }
-  if (sepIdx === -1) return null;
-  const row = `| ${name} | ${today} | ${link} |`;
-  lines.splice(sepIdx + 1, 0, row);
-  return lines.join('\n');
-}
-
 /**
  * Create a project. Idempotent and best-effort per side effect: a missing root
  * hot.md / log.md is reported in `warnings` rather than thrown, so the core
@@ -162,21 +141,38 @@ export function createProject(opts) {
     created.push(`projects/${name}/${file}`);
   }
 
-  // root hot.md pointer row
-  const hotPath = join(hypoDir, 'hot.md');
-  if (existsSync(hotPath)) {
-    const orig = readFileSync(hotPath, 'utf-8');
-    const next = insertHotRow(orig, name, today);
-    if (next === null) {
-      warnings.push('root hot.md: no Active Projects table found — add row manually');
-    } else if (next !== orig) {
-      writeFileSync(hotPath, next);
-      created.push('hot.md row');
-    } else {
-      skipped.push('hot.md row');
-    }
+  // root hot.md pointer row: regenerate via the canonical projection (n2 fix,
+  // see this function's own doc comment above) rather than hand-inserting a
+  // row. The directory scan already sees this project's own hot.md, written
+  // by the TEMPLATE_FILES loop above, so the new row lands in the same pass.
+  const hotResult = writeRootHotProjection(hypoDir);
+  if (hotResult.scanError) {
+    warnings.push('root hot.md: projects/ 디렉터리를 읽지 못해 표를 갱신하지 못했습니다');
+  } else if (hotResult.lockTimeout) {
+    // Distinct from the plain "already current" skip below: the row was
+    // never even attempted this run because another session held the vault
+    // lock, not because there was nothing new to write. `warnings` already
+    // carries writeRootHotProjection's own lock-busy message; this label is
+    // what lets a caller reading only `skipped` tell "not created" apart
+    // from "could not check whether it needed creating".
+    skipped.push('hot.md row (lock timeout)');
+  } else if (hotResult.written) {
+    created.push('hot.md row');
   } else {
-    warnings.push('root hot.md missing — skipped pointer row');
+    skipped.push('hot.md row');
+  }
+  if (hotResult.warnings.length > 0) warnings.push(...hotResult.warnings);
+  // MAJOR fix (codex 3rd-tier finding 6): a hand-authored root hot.md this
+  // scaffold's own writeRootHotProjection call just backed up never reached
+  // the user at all here. `backedUp`/`backupPath` were read by
+  // SessionStart and the Stop-hook rebuild but silently dropped on this
+  // third writer, the one call site with the least excuse for it (`main`'s
+  // own CLI output prints every entry in `warnings`). Same shared sentence
+  // the other two writers use, so a person who created a project right
+  // after hand-editing root hot.md gets the SAME recovery guidance, not a
+  // silently vanished edit.
+  if (hotResult.backedUp && hotResult.backupPath) {
+    warnings.push(rootHotBackupRecoveryNotice(hotResult.backupPath));
   }
 
   // log.md entry

package/scripts/lib/schema-vocab.mjs

@@ -1,5 +1,6 @@
-import { existsSync, readFileSync, writeFileSync } from 'fs';
+import { existsSync, readFileSync } from 'fs';
 import { join } from 'path';
+import { atomicWrite } from '../../hooks/atomic-write.mjs';
 
 const VOCAB_HEADER_RE = /^##\s+(?:\d+\.\s+)?Tag\s+(?:Vocabulary|Taxonomy)\s*$/m;
 const TYPE_TAXONOMY_HEADER_RE = /^##\s+(?:\d+\.\s+)?Page\s+Type\s+Taxonomy\s*$/m;
@@ -87,18 +88,27 @@ function backtickList(tags) {
 // 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).
+// No-ops (`{ tags: [], content: null }`) 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).
+//
+// Returns `{ tags, content }`: `tags` is the same registered-tag list this
+// helper always returned, and `content` is the exact bytes just written (or
+// `null` on a no-op): a close-receipt caller needs the written version to
+// hash for its proof entry, and re-reading the file a moment later cannot
+// tell that read apart from a concurrent writer's edit landing in between.
+// Writes via `atomicWrite` (temp + rename), not a bare `writeFileSync`, so a
+// reader can never observe a half-written SCHEMA.md.
 export function appendPendingTags(hypoDir, tags) {
   const path = join(hypoDir, 'SCHEMA.md');
-  if (!existsSync(path)) return [];
+  if (!existsSync(path)) return { tags: [], content: null };
   const content = readFileSync(path, 'utf-8');
 
   const headerMatch = VOCAB_HEADER_RE.exec(content);
-  if (!headerMatch) return [];
+  if (!headerMatch) return { tags: [], content: null };
 
   const current = parseSchemaVocab(hypoDir);
   const seen = new Set();
@@ -115,7 +125,7 @@ export function appendPendingTags(hypoDir, tags) {
     seen.add(t);
     newTags.push(t);
   }
-  if (newTags.length === 0) return [];
+  if (newTags.length === 0) return { tags: [], content: null };
 
   const sectionStart = headerMatch.index + headerMatch[0].length;
   const rest = content.slice(sectionStart);
@@ -166,8 +176,9 @@ export function appendPendingTags(hypoDir, tags) {
     }
   }
 
-  writeFileSync(path, content.slice(0, sectionStart) + newSection + content.slice(sectionEnd));
-  return newTags;
+  const nextContent = content.slice(0, sectionStart) + newSection + content.slice(sectionEnd);
+  atomicWrite(path, nextContent);
+  return { tags: newTags, content: nextContent };
 }
 
 // Derive the set of valid immediate subdirectories under pages/ from the

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

@@ -19,3 +19,51 @@ export function templateSchemaVersion(pkgRoot) {
     return null;
   }
 }
+
+// One line per SCHEMA.md version bump, naming what that version added over the
+// one before it. This is upgrade.mjs's only source for "what changed" text
+// when it tells a user their installed SCHEMA.md is behind — without it, the
+// notice can only name the two version numbers, and the two SCHEMA.md copies
+// diverge (translation, local additions) far enough that a raw diff is
+// dominated by noise unrelated to the actual upstream change. Add an entry
+// here whenever templates/SCHEMA.md's `version:` frontmatter bumps; a version
+// missing from this map falls back to the plain "review manually" notice
+// (schemaVersionDeltas below returns nothing for it), so leaving one out is
+// silent, not wrong.
+// Quote any key with a trailing zero. An unquoted `2.10:` is a NUMBER literal
+// and JS normalizes it to the string "2.1", so it would silently overwrite
+// 2.1's line (or hand 2.10's text to somebody upgrading across 2.1). Verified:
+// `Object.keys({2.10: 'x'})` is `['2.1']`. Prettier will not undo the quotes
+// there — stripping them would change meaning, so it leaves "2.10" alone even
+// though it rewrites '2.2' to 2.2. What prettier cannot save you from is
+// writing 2.10 unquoted in the first place, which is why a test reads this
+// file's text and rejects that shape rather than trusting the convention.
+export const SCHEMA_VERSION_DELTAS = {
+  2.2: 'documents `sources_consulted` on `type: synthesis` pages (lint W15/W16 read it to flag a synthesis that has fallen behind the pages it condenses)',
+  2.3: 'root `hot.md` is now a generated projection of `projects/*/hot.md` that the hooks rebuild at every session start and stop: session close no longer updates it by hand, and the pointer-table section describes the generated row format',
+};
+
+function parseMinorVersion(v) {
+  const [major, minor] = String(v).split('.').map(Number);
+  return { major, minor: Number.isFinite(minor) ? minor : 0 };
+}
+
+function compareMinorVersions(a, b) {
+  return a.major - b.major || a.minor - b.minor;
+}
+
+// Returns one line per version strictly after `installed` and up to and
+// including `current`, oldest first. `deltas` defaults to the real map above;
+// tests pass their own to exercise the multi-version stepping logic without
+// depending on how many real bumps have landed.
+export function schemaVersionDeltas(installed, current, deltas = SCHEMA_VERSION_DELTAS) {
+  if (!installed || !current) return [];
+  const from = parseMinorVersion(installed);
+  const to = parseMinorVersion(current);
+  if (compareMinorVersions(to, from) <= 0) return [];
+  return Object.keys(deltas)
+    .map((v) => ({ v, mv: parseMinorVersion(v) }))
+    .filter(({ mv }) => compareMinorVersions(mv, from) > 0 && compareMinorVersions(mv, to) <= 0)
+    .sort((a, b) => compareMinorVersions(a.mv, b.mv))
+    .map(({ v }) => `${v}: ${deltas[v]}`);
+}

package/scripts/lib/time.mjs

@@ -0,0 +1,46 @@
+// time.mjs: shared time constants for scripts/. Imports nothing, so a script
+// that only needs a day length does not pull in the modules it would otherwise
+// share a file with (page-usage.mjs loads hooks/hypo-shared.mjs, for one).
+//
+// hooks/ keeps its own copies: hooks may not import scripts/ (they are copied
+// standalone into ~/.claude/hooks/).
+
+export const DAY_MS = 86400000;
+
+// The strict YYYY-MM-DD parser used by lint.mjs (W15/W16), the design-history
+// heading check, and the close-path payload.date check. `new Date(literal)`
+// accepts more than a format check implies: a calendar-overflow value like
+// `2026-02-30` silently normalizes to March 2 instead of failing, so a bare
+// regex test on the shape (`/^\d{4}-\d{2}-\d{2}$/`) lets it through looking
+// validated. Returns a comparable UTC timestamp for a literal that is exactly
+// YYYY-MM-DD and round-trips to the same calendar date through a UTC Date, or
+// null otherwise (wrong shape or calendar overflow).
+//
+// verify/doctor and the hook date checks (e.g. isOverdueDate in
+// hooks/hypo-shared.mjs) do NOT use this: doctor.mjs and hypo-shared.mjs
+// agree to read the same literal with the same characters and same meaning,
+// and hooks may not import scripts/ (they are copied standalone into
+// ~/.claude/hooks/), so those stayed on the plain format check rather than
+// pull this file's logic across that boundary.
+const STRICT_DATE_RE = /^(\d{4})-(\d{2})-(\d{2})$/;
+export function parseStrictDate(literal) {
+  if (literal == null) return null;
+  const m = STRICT_DATE_RE.exec(String(literal));
+  if (!m) return null;
+  const year = Number(m[1]);
+  const month = Number(m[2]);
+  const day = Number(m[3]);
+  // setUTCFullYear, not Date.UTC: Date.UTC maps years 0-99 onto 1900-1999,
+  // so a valid `0001-01-01` would fail the round-trip below and be rejected.
+  const check = new Date(0);
+  check.setUTCFullYear(year, month - 1, day);
+  const ts = check.getTime();
+  if (
+    check.getUTCFullYear() !== year ||
+    check.getUTCMonth() !== month - 1 ||
+    check.getUTCDate() !== day
+  ) {
+    return null; // calendar overflow, e.g. month 13 or Feb 30
+  }
+  return ts;
+}