hypomnema 1.7.0 → 1.7.2

package/scripts/graph.mjs

@@ -91,7 +91,7 @@ function escapeDot(s) {
 
 // ── formatters ────────────────────────────────────────────────────────────────
 
-function formatJson(pages, graph, minEdges) {
+function formatJson(pages, graph, minEdges, vaultFound) {
   const nodes = pages
     .map((p) => ({
       slug: p.slug,
@@ -107,7 +107,9 @@ function formatJson(pages, graph, minEdges) {
     return fn && tn;
   });
 
-  return JSON.stringify({ nodes, edges }, null, 2);
+  // vaultFound: same reasoning as lint.mjs/stats.mjs — an empty graph from a
+  // vault that was never found must not read the same as a real, linkless one.
+  return JSON.stringify({ nodes, edges, vaultFound }, null, 2);
 }
 
 function formatMermaid(pages, graph, minEdges) {
@@ -156,7 +158,11 @@ function formatDot(pages, graph, minEdges) {
 const args = parseArgs(process.argv);
 // Only validate the auto-resolved path (env/marker/default). An explicit
 // --hypo-dir=<path> (tests, other tooling) is trusted as-is, valid or not.
-if (args.hypoDirSource) checkVaultOrExit(args.hypoDir, args.hypoDirSource);
+// See lint.mjs's matching comment: source 'default'/stale-'marker' stays
+// exit-0 (CI-safe).
+const vaultMissing = args.hypoDirSource
+  ? checkVaultOrExit(args.hypoDir, args.hypoDirSource)
+  : false;
 
 const ignorePatterns = loadHypoIgnore(args.hypoDir);
 const scanDirs = ['pages', 'projects'].map((d) => join(args.hypoDir, d));
@@ -164,13 +170,22 @@ const pages = scanDirs.flatMap((d) => collectPagesGraph(d, args.hypoDir, ignoreP
 const slugIndex = buildSlugIndex(pages);
 const graph = buildGraph(pages, slugIndex);
 
-switch (args.format) {
-  case 'mermaid':
-    console.log(formatMermaid(pages, graph, args.minEdges));
-    break;
-  case 'dot':
-    console.log(formatDot(pages, graph, args.minEdges));
-    break;
-  default:
-    console.log(formatJson(pages, graph, args.minEdges));
+if (vaultMissing && (args.format === 'mermaid' || args.format === 'dot')) {
+  // Same reasoning as lint.mjs/stats.mjs: mermaid/dot render straight to a
+  // diagram tool with no JSON envelope to carry `vaultFound`, so a valid but
+  // linkless diagram from a real (empty) vault and "no vault was found at
+  // all" would otherwise render identically. checkVaultOrExit already put the
+  // "No Hypomnema vault found" notice on stderr; suppress the stdout diagram
+  // rather than hand the renderer an empty-but-"real"-looking graph.
+} else {
+  switch (args.format) {
+    case 'mermaid':
+      console.log(formatMermaid(pages, graph, args.minEdges));
+      break;
+    case 'dot':
+      console.log(formatDot(pages, graph, args.minEdges));
+      break;
+    default:
+      console.log(formatJson(pages, graph, args.minEdges, !vaultMissing));
+  }
 }

package/scripts/init.mjs

@@ -38,6 +38,7 @@ import { execSync, spawnSync } from 'child_process';
 import { fileURLToPath } from 'url';
 import { createHash } from 'crypto';
 import { expandHome, resolveHypoRoot } from './lib/hypo-root.mjs';
+import { hooksDirForInstall, unsafeHookTargetReason } from './lib/git-hooks-dir.mjs';
 import { readCoreHooksConfig } from './lib/core-hooks.mjs';
 import {
   readPkgJson as readPkgJsonSafe,
@@ -47,6 +48,7 @@ import {
   readFileIfRegular,
 } from './lib/pkg-json.mjs';
 import { syncExtensions } from './lib/extensions.mjs';
+import { writeProvenanceSidecar } from './lib/pkg-provenance.mjs';
 import { templateSchemaVersion } from './lib/template-schema-version.mjs';
 import { classifyInstall, downgradeGuardMessage } from '../hooks/version-check.mjs';
 import {
@@ -142,6 +144,9 @@ Commands:
   capture                 Reverse-capture ~/.claude/{commands,agents} extensions and
                           settings.json hooks into the wiki for cross-machine sync
                           (pass names or --all; --dry-run to preview)
+  proposal                Manage staged crystallize proposals: list, apply, or
+                          discard a parked write (also challenge/resolve for the
+                          no-TTY agent approval channel)
 
   Running \`hypomnema\` with no command is equivalent to \`hypomnema init\`.
 
@@ -164,11 +169,15 @@ Init options:
                          to a blocking error), sequenced after the .hypoignore
                          guard. Off by default; re-run init to add or drop it.
   --dry-run              Show what would be done without making changes
+  --version              Print the installed package version and exit
   --help, -h             Show this help message
 
 Subcommand-specific flags (upgrade/doctor/uninstall/capture) live in the
 docstring at the top of scripts/<command>.mjs; capture also accepts \`--help\`.`);
       process.exit(0);
+    } else if (arg === '--version') {
+      console.log(PKG_VERSION ?? 'unknown');
+      process.exit(0);
     } else if (arg.startsWith('--hypo-dir=')) args.hypoDir = expandHome(arg.slice(11));
     else if (arg === '--no-hooks') args.hooks = false;
     else if (arg === '--no-commands') args.commands = false;
@@ -189,6 +198,18 @@ docstring at the top of scripts/<command>.mjs; capture also accepts \`--help\`.`
     else if (arg.startsWith('--shell-config=')) args.shellConfig = expandHome(arg.slice(15));
     else if (arg === '--allow-downgrade') args.allowDowngrade = true;
     else if (arg === '--lint-strict') args.lintStrict = true;
+    else {
+      // An unrecognized argument used to fall through silently and run the
+      // default init flow (scaffold + hook install + settings.json merge) —
+      // a destructive write triggered by what looked like a query. `--version`
+      // was the concrete case that bit a user: it reads like an inspection
+      // flag, was never implemented, and its typo/mistake landed on a live
+      // wiki's pre-commit hook instead of printing anything. Fail loud and
+      // do nothing, rather than guess what the caller meant.
+      console.error(`Unknown option: ${arg}`);
+      console.error('Run `hypomnema --help` for usage.');
+      process.exit(2);
+    }
   }
   return args;
 }
@@ -438,6 +459,14 @@ function installHooks(targetDir, dryRun) {
     if (!dryRun) copyFileSync(join(HOOKS_SRC, file), dest);
     log('created', dest);
   }
+  // Refresh the provenance sidecar every run, even when every .mjs above was
+  // skipped as already-present: this is the standalone (manual/npm) channel
+  // only (the plugin channel never calls installHooks), and resolvePkgRoot()'s
+  // provenance fallback needs it to track the truth of what is actually on
+  // disk here, not just what a fresh copy left behind. See
+  // hooks/hypo-shared.mjs's readVerifiedProvenancePkgRoot() for the reader.
+  const sidecar = writeProvenanceSidecar(targetDir, PKG_ROOT, PKG_VERSION, HOOKS_SRC, dryRun);
+  if (sidecar) log('created', sidecar);
 }
 
 function mergeSettingsJson(settingsPath, hooksDir, dryRun, hookMap) {
@@ -693,10 +722,19 @@ function installCommands(targetDir, dryRun, force) {
 }
 
 function installPkgGitHook(dryRun) {
-  const gitDir = join(PKG_ROOT, '.git');
-  if (!existsSync(gitDir)) return;
-  const hooksDir = join(gitDir, 'hooks');
+  const { dir: hooksDir, skip } = hooksDirForInstall(PKG_ROOT);
+  if (!hooksDir) {
+    if (skip) log('skipped', `${PKG_ROOT} post-commit (${skip})`);
+    return;
+  }
   const hookPath = join(hooksDir, 'post-commit');
+  // Checked before existsSync: a dangling symlink reads as absent there, and
+  // writing would create its external target.
+  const unsafe = unsafeHookTargetReason(hookPath);
+  if (unsafe) {
+    log('skipped', `${hookPath} (${unsafe})`);
+    return;
+  }
   if (existsSync(hookPath)) {
     log('skipped', hookPath);
     return;
@@ -758,12 +796,23 @@ function wikiPreCommitContent(root, hypoDir, lintStrict) {
 }
 
 function installWikiPreCommitHook(hypoDir, dryRun, force, root, lintStrict) {
-  const gitDir = join(hypoDir, '.git');
-  if (!existsSync(gitDir)) return; // no git repo — silently skip
-  const hooksDir = join(gitDir, 'hooks');
+  const { dir: hooksDir, skip } = hooksDirForInstall(hypoDir);
+  if (!hooksDir) {
+    // no git repo — silently skip, as before; anything else is worth surfacing
+    if (skip) log('skipped', `${hypoDir} pre-commit (${skip})`);
+    return;
+  }
   const hookPath = join(hooksDir, 'pre-commit');
   const newContent = wikiPreCommitContent(root, hypoDir, lintStrict);
 
+  // Before every branch below, including --force: a symlink here would send the
+  // write through to an arbitrary external file.
+  const unsafe = unsafeHookTargetReason(hookPath);
+  if (unsafe) {
+    log('skipped', `${hookPath} (${unsafe})`);
+    return;
+  }
+
   if (existsSync(hookPath)) {
     const existing = readFileSync(hookPath, 'utf-8');
     if (existing.includes(WIKI_PRE_COMMIT_MARKER_START)) {
@@ -777,8 +826,18 @@ function installWikiPreCommitHook(hypoDir, dryRun, force, root, lintStrict) {
       }
       log('merged', `${hookPath} (pre-commit updated)`);
     } else if (force) {
+      // The .bak is a SECOND write to a DIFFERENT path, so the guard on
+      // hookPath above says nothing about it. Left unchecked, a pre-commit.bak
+      // symlink turns --force-commands into an overwrite of whatever it points
+      // at — deterministically, not as a race.
+      const bakPath = hookPath + '.bak';
+      const unsafeBak = unsafeHookTargetReason(bakPath);
+      if (unsafeBak) {
+        log('skipped', `${bakPath} (${unsafeBak}) — not force-overwriting without a safe backup`);
+        return;
+      }
       if (!dryRun) {
-        writeFileSync(hookPath + '.bak', existing);
+        writeFileSync(bakPath, existing);
         writeFileSync(hookPath, newContent);
         chmodSync(hookPath, 0o755);
       }

package/scripts/lib/git-hooks-dir.mjs

@@ -0,0 +1,229 @@
+/**
+ * Resolve a repository's active git hooks directory by asking git, never by
+ * assuming the on-disk layout.
+ *
+ * The layout assumption this replaces (`join(root, '.git', 'hooks')`) is wrong
+ * in two ways that both showed up in practice:
+ *
+ *   1. In a linked worktree `.git` is a regular FILE holding `gitdir: <path>`,
+ *      so `existsSync` passes and `mkdirSync` dies with ENOTDIR.
+ *   2. When `core.hooksPath` is set, git does not read `.git/hooks` at all, so
+ *      a hook written there is inert.
+ *
+ * `git rev-parse --git-path hooks` handles both: it follows the worktree's
+ * gitdir pointer AND substitutes `core.hooksPath` (verified on git 2.50.1 —
+ * `/dev/null` stays `/dev/null`, a relative value stays relative, and `~` is
+ * expanded). That makes rev-parse the single authority here; reading
+ * `core.hooksPath` out of the config ourselves would be strictly worse, since
+ * it would leave `~` unexpanded and could not tell an empty-but-set value from
+ * an unset one.
+ *
+ * Two things rev-parse does NOT give us, so we add them:
+ *
+ *   - `git -C <root>` does not neutralize ambient git environment variables.
+ *     `GIT_DIR` + `GIT_WORK_TREE` redirect the probe at a foreign repository,
+ *     and `GIT_CONFIG_COUNT`/`GIT_CONFIG_PARAMETERS` redirect it at an
+ *     arbitrary hooks path. Every probe therefore runs under a scrubbed env,
+ *     with the scrub list taken from git's own `--local-env-vars` when
+ *     available.
+ *   - `core.hooksPath` may point at a directory SHARED by many repositories
+ *     (the documented centralized-hooks pattern). Auto-installing there would
+ *     put our hook in front of unrelated repositories' commits, and our
+ *     post-commit executes `$REPO_ROOT/scripts/upgrade.mjs` dynamically. So the
+ *     result carries an `owned` flag, and callers that WRITE must refuse when
+ *     it is false. Callers that only READ (doctor) may report the path.
+ */
+
+import { execFileSync } from 'child_process';
+import { existsSync, lstatSync, realpathSync, statSync } from 'fs';
+import { basename, dirname, isAbsolute, join, resolve, sep } from 'path';
+
+// Fallback scrub list for git versions without `rev-parse --local-env-vars`.
+// Mirrors scripts/install-git-hooks.mjs, which established this trust model.
+const STATIC_LOCAL_ENV_VARS = [
+  'GIT_DIR',
+  'GIT_WORK_TREE',
+  'GIT_INDEX_FILE',
+  'GIT_OBJECT_DIRECTORY',
+  'GIT_ALTERNATE_OBJECT_DIRECTORIES',
+  'GIT_COMMON_DIR',
+  'GIT_CONFIG',
+  'GIT_CONFIG_PARAMETERS',
+  'GIT_PREFIX',
+  'GIT_IMPLICIT_WORK_TREE',
+  'GIT_GRAFT_FILE',
+  'GIT_NO_REPLACE_OBJECTS',
+  'GIT_REPLACE_REF_BASE',
+  'GIT_SHALLOW_FILE',
+];
+
+function buildScrubbedEnv(localEnvList) {
+  const scrub = new Set([
+    ...(localEnvList || STATIC_LOCAL_ENV_VARS),
+    'GIT_NAMESPACE',
+    'GIT_CEILING_DIRECTORIES',
+    // GIT_CONFIG_COUNT / GIT_CONFIG_KEY_n / GIT_CONFIG_VALUE_n inject config
+    // wholesale and are not always listed by --local-env-vars.
+    ...Object.keys(process.env).filter((k) => /^GIT_CONFIG_/.test(k)),
+  ]);
+  return Object.fromEntries(Object.entries(process.env).filter(([k]) => !scrub.has(k)));
+}
+
+// Canonicalize a path that may not exist yet: realpath the deepest existing
+// ancestor and re-append the rest. Without this, a hooks dir git will create
+// lazily could evade the containment check via an unresolved symlinked parent.
+function canonicalize(p) {
+  let cur = resolve(p);
+  const tail = [];
+  for (;;) {
+    try {
+      return join(realpathSync(cur), ...tail);
+    } catch {
+      const parent = dirname(cur);
+      if (parent === cur) return resolve(p); // hit the root; nothing to resolve
+      // basename, not a slice: when the parent IS the root it already ends in a
+      // separator, so `parent.length + 1` would eat the first real character
+      // ("/Nope/x" -> "ope/x") and could rewrite an external path into one that
+      // looks repository-owned.
+      tail.unshift(basename(cur));
+      cur = parent;
+    }
+  }
+}
+
+function isInside(child, parent) {
+  return child === parent || child.startsWith(parent + sep);
+}
+
+/**
+ * @param {string} repoRoot        working tree root to probe
+ * @param {{timeoutMs?: number}} [opts]
+ * @returns {{ok: true, path: string, owned: boolean, gitDir: string, commonDir: string}
+ *          |{ok: false, reason: string, detail?: string, path?: string}}
+ *
+ * Failure reasons are deliberately distinct so callers can react differently:
+ *   not-a-repo        no `.git` entry (also the case for a bare repo — matches
+ *                     the pre-existing behavior of every call site)
+ *   git-unavailable   git is not on PATH / not executable
+ *   probe-failed      git ran but could not resolve the repo (stale `.git`
+ *                     pointer, dubious ownership, timeout, ...)
+ *   hooks-disabled    the active hooks path is `/dev/null` or an existing
+ *                     non-directory — git's documented way to disable hooks
+ */
+export function resolveGitHooksDir(repoRoot, { timeoutMs = 5000 } = {}) {
+  if (!existsSync(join(repoRoot, '.git'))) return { ok: false, reason: 'not-a-repo' };
+
+  let env = buildScrubbedEnv(null);
+  const run = (args) =>
+    execFileSync('git', args, {
+      encoding: 'utf-8',
+      env,
+      cwd: repoRoot,
+      timeout: timeoutMs,
+      stdio: ['ignore', 'pipe', 'ignore'],
+      maxBuffer: 1024 * 1024,
+    }).trim();
+
+  try {
+    // Enrich the scrub list from git's own truth when this git supports it.
+    try {
+      env = buildScrubbedEnv(run(['rev-parse', '--local-env-vars']).split(/\r?\n/).filter(Boolean));
+    } catch {
+      // Old git without --local-env-vars; the static list already applied.
+    }
+
+    const gitDir = canonicalize(run(['rev-parse', '--absolute-git-dir']));
+    const rawCommon = run(['rev-parse', '--git-common-dir']);
+    // A relative --git-common-dir is relative to the command's cwd, which we
+    // pinned to repoRoot.
+    const commonDir = canonicalize(isAbsolute(rawCommon) ? rawCommon : join(repoRoot, rawCommon));
+    const topLevel = canonicalize(run(['rev-parse', '--show-toplevel']));
+
+    // --path-format is git 2.31+. Fall back to the plain form, whose output is
+    // relative to cwd (= repoRoot) when core.hooksPath is relative.
+    let raw;
+    try {
+      raw = run(['rev-parse', '--path-format=absolute', '--git-path', 'hooks']);
+    } catch {
+      raw = run(['rev-parse', '--git-path', 'hooks']);
+    }
+    if (!raw) return { ok: false, reason: 'probe-failed', detail: 'empty hooks path' };
+
+    const hooksPath = canonicalize(isAbsolute(raw) ? raw : join(repoRoot, raw));
+
+    // git documents core.hooksPath=/dev/null as "disable all hooks". Treat any
+    // existing non-directory the same way rather than failing on mkdir later.
+    if (existsSync(hooksPath) && !statSync(hooksPath).isDirectory()) {
+      return { ok: false, reason: 'hooks-disabled', path: hooksPath };
+    }
+
+    // Repository-owned means: inside this repo's git directory (the normal
+    // `.git/hooks`, and in a linked worktree the shared common dir) or inside
+    // the working tree itself (the `core.hooksPath=.githooks` convention).
+    // Anything else is a location we do not own and must not write into.
+    const owned =
+      isInside(hooksPath, commonDir) ||
+      isInside(hooksPath, gitDir) ||
+      isInside(hooksPath, topLevel);
+
+    return { ok: true, path: hooksPath, owned, gitDir, commonDir };
+  } catch (e) {
+    if (e && e.code === 'ENOENT') return { ok: false, reason: 'git-unavailable' };
+    return { ok: false, reason: 'probe-failed', detail: e && (e.code || e.message) };
+  }
+}
+
+/**
+ * Guard the final hook ENTRY, not just the directory it lives in.
+ *
+ * An owned hooks directory can still contain a symlink pointing anywhere, and
+ * `writeFileSync` follows symlinks. Three ways that escapes the boundary the
+ * directory check appears to establish:
+ *   - a live symlink to an external file gets its TARGET overwritten;
+ *   - if that target happens to carry our managed marker, it is rewritten even
+ *     without --force-commands;
+ *   - a DANGLING symlink reads as absent through `existsSync`, so the "not
+ *     installed yet" path creates the external target outright.
+ * So refuse to write through any symlink, and refuse anything that is not a
+ * regular file. Callers log the reason and move on.
+ *
+ * @returns {null | string} null when writing is safe, else a reason to log
+ */
+export function unsafeHookTargetReason(hookPath) {
+  let st;
+  try {
+    st = lstatSync(hookPath);
+  } catch (e) {
+    if (e && e.code === 'ENOENT') return null; // genuinely absent — safe to create
+    return `cannot stat (${e.code || e.message})`;
+  }
+  if (st.isSymbolicLink()) return 'is a symlink — refusing to write through it';
+  if (!st.isFile()) return 'exists but is not a regular file';
+  return null;
+}
+
+/**
+ * Write-side wrapper: the hooks directory only if it is safe to install into.
+ * Returns `{dir}` when installing is allowed, otherwise `{skip}` carrying a
+ * human-readable reason for the caller to log.
+ */
+export function hooksDirForInstall(repoRoot, opts) {
+  const r = resolveGitHooksDir(repoRoot, opts);
+  if (!r.ok) {
+    if (r.reason === 'not-a-repo') return { skip: null }; // silent, as before
+    if (r.reason === 'hooks-disabled') {
+      // Do not name core.hooksPath here: the same branch fires for a plain
+      // .git/hooks that happens to be a regular file, where no such setting
+      // exists and naming it would send the user hunting for a phantom config.
+      return { skip: `hooks path is not a directory, so git runs no hooks (${r.path})` };
+    }
+    if (r.reason === 'git-unavailable') return { skip: 'git not available on PATH' };
+    return { skip: `could not resolve hooks dir (${r.detail || r.reason})` };
+  }
+  if (!r.owned) {
+    return {
+      skip: `core.hooksPath points outside this repository (${r.path}) — refusing to install into a shared hooks directory`,
+    };
+  }
+  return { dir: r.path };
+}

package/scripts/lib/pkg-provenance.mjs

@@ -0,0 +1,166 @@
+/**
+ * `.hypo-provenance.json` sidecar: copy-time producer proof for the
+ * standalone (manual/npm) hooks channel.
+ *
+ * hooks/hypo-shared.mjs's resolvePkgRoot() falls back to this file, verified
+ * against its own package name + a SHA-256 of the running hypo-shared.mjs,
+ * whenever self-location can't confirm a package root — the standalone hooks
+ * copy has no package.json alongside it to walk up to, by design (hooks
+ * import only Node built-ins, nothing outside the hooks dir).
+ *
+ * This is accidental-staleness protection, not a security boundary: any
+ * process running as this OS user can edit this JSON file freely, same as it
+ * could edit hooks/hypo-shared.mjs itself. It only guards against the
+ * accidental drift init/upgrade left unguarded before this fix — a hook
+ * file skip (already-present) that still let hypo-pkg.json's cached pointer
+ * move on to a newer version, silently mismatching the code actually copied.
+ *
+ * The filename and the producer-name check ("hypomnema") here must stay
+ * byte-identical with hooks/hypo-shared.mjs's own copy of this contract —
+ * hooks can't import scripts/, so the two sides are duplicated, not shared.
+ */
+
+import { existsSync, readFileSync, writeFileSync, unlinkSync, renameSync } from 'fs';
+import { join } from 'path';
+import { sha256 } from './pkg-json.mjs';
+import { readCoreHooksConfig, deriveCoreHookBasenames } from './core-hooks.mjs';
+
+export const PROVENANCE_FILENAME = '.hypo-provenance.json';
+export const EXPECTED_PKG_NAME = 'hypomnema';
+
+// Field name for the aggregate hook-set hash (BLOCKER A). Exported so
+// scripts/doctor.mjs reads/writes the same key instead of duplicating the
+// string literal — doctor already imports this module for
+// PROVENANCE_FILENAME/EXPECTED_PKG_NAME, so importing one more constant costs
+// nothing and closes the duplication CONCERN 1 flagged for the filename/name
+// pair (those two stay duplicated only because hooks/hypo-shared.mjs can't
+// import this file at all).
+export const HOOKS_DIGEST_FIELD = 'hooksDigest';
+
+/**
+ * Deterministic aggregate hash over every hook file hooks/hooks.json wires up
+ * (every event handler's file plus every `shared` entry) — the exact set
+ * installHooks/applyHookFiles copy, derived from hooks.json itself rather
+ * than hand-listed here so this can never drift from what actually gets
+ * copied. `dir` is read for CONTENT: pass hooksSrcDir at write time (the
+ * package's own hooks/, immediately after files were copied out of it — see
+ * writeProvenanceSidecar) and the installed hooksDir at doctor-check time
+ * (mirrors how hypoSharedSha256 below is written from source but verified
+ * against the installed copy).
+ *
+ * Deliberately NOT what the runtime resolver reads: hooks/hypo-shared.mjs's
+ * readVerifiedProvenancePkgRoot() only ever compares hypoSharedSha256, one
+ * file, because hook modules load on every single hook event and hashing an
+ * entire directory on every load would tax the hot path for a check only
+ * `hypomnema doctor` needs to run once per invocation. This digest is that
+ * doctor-only, directory-wide check: it catches a hooks/ dir where some OTHER
+ * file (e.g. hypo-personal-check.mjs) went stale while hypo-shared.mjs itself
+ * stayed byte-identical, which the single-file SHA the runtime trusts cannot
+ * see at all.
+ *
+ * Sorted basenames, `<file>\n<sha256-of-file-hex>\n` per file concatenated,
+ * then SHA-256 of that string — order and content only, never mtime/size.
+ * Returns null if hooks.json can't be read/parsed or any listed file can't be
+ * read, so a caller can treat "couldn't compute" the same as "nothing to
+ * compare" rather than writing/trusting a bogus digest.
+ */
+export function computeHooksDigest(pkgRoot, dir) {
+  const cfgRes = readCoreHooksConfig(pkgRoot);
+  if (!cfgRes.ok) return null;
+  const files = [...deriveCoreHookBasenames(cfgRes.cfg)].sort();
+  try {
+    let acc = '';
+    for (const file of files) {
+      acc += `${file}\n${sha256(readFileSync(join(dir, file)))}\n`;
+    }
+    return sha256(acc);
+  } catch {
+    return null;
+  }
+}
+
+export function provenancePath(hooksDir) {
+  return join(hooksDir, PROVENANCE_FILENAME);
+}
+
+/**
+ * Write/refresh the sidecar next to a standalone hooks copy at `hooksDir`.
+ * `hooksSrcDir` is the package's own hooks/ (the source hypo-shared.mjs was
+ * just copied FROM) — its content is what gets hashed, since that hash is
+ * what the copy left at `hooksDir` will actually match.
+ *
+ * Callers must invoke this every run that touches — or even just re-verifies
+ * — the hook file set, EVEN when every individual .mjs file was skipped as
+ * already-present. A skipped hook copy that still lets hypo-pkg.json's
+ * pkgVersion move on to a newer release is exactly the bug this sidecar
+ * exists to catch; refreshing it only when files actually changed would
+ * reintroduce that gap under a new name.
+ *
+ * Returns the sidecar path written, or null if the source couldn't be
+ * hashed (leaves any pre-existing sidecar untouched rather than write a
+ * broken one).
+ *
+ * `hooksDigest` (BLOCKER A) is best-effort: computed from the same
+ * `hooksSrcDir`, over the file set hooks.json actually wires up. Unlike
+ * hypoSharedSha256 above, a failure to compute it does not abort the write —
+ * 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.
+ */
+export function writeProvenanceSidecar(hooksDir, pkgRoot, pkgVersion, hooksSrcDir, dryRun) {
+  let hypoSharedSha256;
+  try {
+    hypoSharedSha256 = sha256(readFileSync(join(hooksSrcDir, 'hypo-shared.mjs')));
+  } catch {
+    return null;
+  }
+  const hooksDigest = computeHooksDigest(pkgRoot, hooksSrcDir);
+  const dest = provenancePath(hooksDir);
+  const data = {
+    pkgRoot,
+    pkgVersion,
+    hypoSharedSha256,
+    ...(hooksDigest ? { [HOOKS_DIGEST_FIELD]: hooksDigest } : {}),
+    copiedAt: new Date().toISOString(),
+  };
+  if (!dryRun) atomicWriteJson(dest, data);
+  return dest;
+}
+
+// Tmp file in the SAME directory as `dest`, then rename over it (CONCERN 2):
+// a reader (readVerifiedProvenancePkgRoot in hooks/hypo-shared.mjs) that
+// races a plain truncate-then-write can observe a half-written file and
+// JSON.parse throws, degrading PKG_ROOT to null for that hook invocation.
+// Same directory is required for the rename to be atomic — crossing a
+// 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');
+  try {
+    renameSync(tmp, dest);
+  } catch (err) {
+    try {
+      unlinkSync(tmp);
+    } catch {
+      /* best-effort cleanup */
+    }
+    throw err;
+  }
+}
+
+/** Remove the sidecar at `hooksDir`, if present. Returns the path removed, or null. */
+export function removeProvenanceSidecar(hooksDir, apply) {
+  const dest = provenancePath(hooksDir);
+  if (!existsSync(dest)) return null;
+  if (apply) unlinkSync(dest);
+  return dest;
+}
+
+/** Non-mutating read. Returns the parsed sidecar, or null on absence/corruption. */
+export function readProvenanceSidecar(hooksDir) {
+  try {
+    return JSON.parse(readFileSync(provenancePath(hooksDir), 'utf-8'));
+  } catch {
+    return null;
+  }
+}

package/scripts/lib/project-create.mjs

@@ -28,7 +28,11 @@ import { resolveHypoRoot, expandHome } from './hypo-root.mjs';
 
 const SCRIPT_DIR = dirname(fileURLToPath(import.meta.url));
 const PKG_ROOT = join(SCRIPT_DIR, '..', '..');
-const TEMPLATE_DIR = join(PKG_ROOT, 'templates', 'projects', '_template');
+// Exported so other project-scaffolding call sites (crystallize.mjs's
+// session-close apply, which fills a MISSING index.md on a project that
+// bypassed createProject entirely) resolve the same template dir instead of
+// re-deriving the path.
+export const TEMPLATE_DIR = join(PKG_ROOT, 'templates', 'projects', '_template');
 
 const TEMPLATE_FILES = ['index.md', 'prd.md', 'hot.md', 'session-state.md'];
 

package/scripts/lib/rename-marker.mjs

@@ -0,0 +1,39 @@
+// scripts/lib/rename-marker.mjs
+//
+// The crash-recovery marker for rename.mjs --apply. Shared read-only path/parse
+// logic between the writer (rename.mjs) and the reader (doctor.mjs) so the two
+// never drift on where the marker lives or what shape it is in.
+//
+// Kept under .cache/ deliberately, matching every other runtime marker this repo
+// already writes there (sync-state.json, session-closed-*.marker, proposals/,
+// project-suggestions.json). Two things fall out of that placement for free:
+//   - it is JSON, not .md, so every vault walker (scripts/lib/wikilink.mjs) that
+//     only ever collects .md files simply never sees it — no lint/rename/graph
+//     scan needs to know this file exists.
+//   - .cache/ ships in templates/.hypoignore's default pattern list, so a scan
+//     that DOES walk directories rather than just filtering by extension
+//     (doctor's own checkBrokenLinks walker) is also covered on any vault that
+//     carries that baseline — which every vault already needs, since .cache/
+//     holds the pre-commit secret-gate's own state.
+// No .hyposcanignore entry or scan-logic change was needed to get this property;
+// it comes from where the file lives, not from a new exclusion rule.
+import { existsSync, readFileSync } from 'fs';
+import { join } from 'path';
+
+export const RENAME_MARKER_REL = '.cache/rename-in-progress.json';
+
+export function renameMarkerPath(hypoDir) {
+  return join(hypoDir, RENAME_MARKER_REL);
+}
+
+// Best-effort read: a missing or corrupt marker both mean "nothing to report" —
+// this runs inside doctor's health scan and must never throw.
+export function readRenameMarker(hypoDir) {
+  const path = renameMarkerPath(hypoDir);
+  if (!existsSync(path)) return null;
+  try {
+    return JSON.parse(readFileSync(path, 'utf-8'));
+  } catch {
+    return null;
+  }
+}