hypomnema 1.2.1 → 1.3.0

package/scripts/fix-status-verify.mjs

@@ -0,0 +1,256 @@
+#!/usr/bin/env node
+/**
+ * fix-status-verify (CLI) — verify fix→test linkage + ADR-line evidence
+ * against wiki spec claims.
+ *
+ * Phase 1: test-green half (anchors × spec status × runner results).
+ * Phase 2 (A-sot): manifest validation + manifest↔anchor drift + ADR core
+ * decision grep against the production corpus. See scripts/lib/fix-manifest.mjs
+ * and scripts/lib/fix-status-verify.mjs headers.
+ *
+ * Usage:
+ *   node scripts/fix-status-verify.mjs [--hypo-dir <path>]
+ *                                      [--spec <path>]
+ *                                      [--runner <path>]
+ *                                      [--test-command "<cmd>"]
+ *                                      [--json]
+ *
+ * Exit 0 if no error-level findings, 1 otherwise.
+ */
+
+import { readFileSync, existsSync } from 'node:fs';
+import { join, dirname, resolve } from 'node:path';
+import { homedir } from 'node:os';
+import { spawnSync } from 'node:child_process';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import {
+  parseAnchors,
+  parseStatus,
+  parseRunnerOutput,
+  verifyMatrix,
+  isReferenceStub,
+  validateManifest,
+  checkManifestCoverage,
+  checkAdrLines,
+  FIX_MANIFEST,
+  NO_ADR,
+} from './lib/fix-status-verify.mjs';
+import { buildCorpusSearch } from './lib/adr-corpus.mjs';
+
+const REPO = resolve(dirname(fileURLToPath(import.meta.url)), '..');
+
+// Production-code corpus for the ADR-line grep (spec §A amendment 2026-06-07:
+// templates/ ships via npm `files`, so prompt-driven fixes are verifiable).
+const CORPUS_DIRS = ['scripts', 'hooks', 'commands', 'skills', 'templates'];
+// MUST exclude the manifest itself — it holds every adrKeyLine as a literal and
+// would self-match, making ADR_LINE_MISSING impossible to ever fire.
+const CORPUS_EXCLUDE = ['scripts/lib/fix-manifest.mjs'];
+
+function parseArgs(argv) {
+  const out = {
+    hypoDir: process.env.HYPO_DIR || join(homedir(), 'hypomnema'),
+    spec: null,
+    runner: join(REPO, 'tests/runner.mjs'),
+    testCommand: 'npm test',
+    json: false,
+    manifest: null,
+  };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === '--hypo-dir') out.hypoDir = argv[++i];
+    else if (a === '--spec') out.spec = argv[++i];
+    else if (a === '--runner') out.runner = argv[++i];
+    else if (a === '--test-command') out.testCommand = argv[++i];
+    else if (a === '--manifest') out.manifest = argv[++i];
+    else if (a === '--json') out.json = true;
+    else if (a === '--help' || a === '-h') {
+      printHelp();
+      process.exit(0);
+    } else {
+      console.error(`unknown arg: ${a}`);
+      process.exit(2);
+    }
+  }
+  if (!out.spec) {
+    out.spec = join(out.hypoDir, 'projects/hypomnema/spec-v1.2.md');
+  }
+  return out;
+}
+
+function printHelp() {
+  console.log(
+    [
+      'fix-status-verify — Phase 1 (test-green half) of learned_behavior #6',
+      '',
+      'Options:',
+      '  --hypo-dir <path>        Wiki root (default: $HYPO_DIR or ~/hypomnema)',
+      '  --spec <path>            Override spec-v1.2.md path',
+      '  --runner <path>          Override tests/runner.mjs path',
+      '  --test-command "<cmd>"   Test invocation (default: "npm test")',
+      '  --json                   Emit machine-readable JSON report',
+      '',
+      'Exit 0 if no error findings, 1 otherwise.',
+      '',
+      'NOTE: The default --spec is a `type: reference` redirect stub (the real',
+      'spec moved to archive/). Running without --spec fails with STUB_SPEC by',
+      'design — pass --spec <real spec> to verify against actual claims.',
+      '',
+      'Phase 2 (A-sot): also greps each manifest adrKeyLine against the',
+      'production corpus (scripts/ hooks/ commands/ skills/ templates/) and',
+      'checks manifest↔anchor drift. NO_ADR rows skip the grep (test-green only).',
+    ].join('\n'),
+  );
+}
+
+function runTests(testCommand) {
+  // Parse simple command (no shell metacharacters supported in args; this is
+  // a maintainer tool, not a security boundary).
+  const parts = testCommand.split(/\s+/).filter(Boolean);
+  const [cmd, ...args] = parts;
+  const result = spawnSync(cmd, args, {
+    cwd: REPO,
+    encoding: 'utf-8',
+    env: { ...process.env, FORCE_COLOR: '0' },
+    maxBuffer: 64 * 1024 * 1024,
+  });
+  return {
+    stdout: result.stdout || '',
+    stderr: result.stderr || '',
+    exitCode: result.status,
+  };
+}
+
+function formatFinding(f) {
+  const icon = f.level === 'error' ? '✗' : '⚠';
+  // Some findings are not tied to a specific fix # (STUB_SPEC,
+  // TEST_RUN_NONZERO_EXIT). Only render the `fix #N` segment when present so
+  // they don't print `fix #undefined`.
+  const ref = f.fixNum != null ? ` fix #${f.fixNum}` : '';
+  return `  ${icon} [${f.class}]${ref}` + (f.testName ? ` (${f.testName})` : '') + `: ${f.detail}`;
+}
+
+async function main() {
+  const opts = parseArgs(process.argv.slice(2));
+
+  // Manifest source: built-in code constant by default (ADR 0036). --manifest
+  // <path.mjs> overrides for tests, which inject a fixture manifest matching
+  // their synthetic fixes so the real manifest does not couple to fixtures.
+  let manifest = FIX_MANIFEST;
+  if (opts.manifest) {
+    if (!existsSync(opts.manifest)) {
+      console.error(`manifest not found: ${opts.manifest}`);
+      process.exit(2);
+    }
+    const mod = await import(pathToFileURL(resolve(opts.manifest)).href);
+    manifest = mod.FIX_MANIFEST;
+  }
+
+  if (!existsSync(opts.spec)) {
+    console.error(`spec not found: ${opts.spec}`);
+    console.error('hint: pass --hypo-dir <path> or set $HYPO_DIR');
+    process.exit(2);
+  }
+  if (!existsSync(opts.runner)) {
+    console.error(`runner not found: ${opts.runner}`);
+    process.exit(2);
+  }
+
+  const specText = readFileSync(opts.spec, 'utf-8');
+  const runnerText = readFileSync(opts.runner, 'utf-8');
+
+  const anchors = parseAnchors(runnerText);
+  const status = parseStatus(specText);
+  const specIsStub = isReferenceStub(specText);
+
+  if (!opts.json) {
+    console.log(`fix-status-verify (Phase 1)`);
+    console.log(`  spec:   ${opts.spec}`);
+    console.log(`  runner: ${opts.runner}`);
+    console.log(`  ${status.size} positive status claim(s), ${anchors.size} anchor(s)`);
+    console.log(`  running: ${opts.testCommand}`);
+  }
+
+  const testRun = runTests(opts.testCommand);
+  const testResults = parseRunnerOutput(testRun.stdout + '\n' + testRun.stderr);
+
+  if (!opts.json) {
+    const passes = [...testResults.values()].filter((v) => v === 'pass').length;
+    const fails = [...testResults.values()].filter((v) => v === 'fail').length;
+    console.log(`  test run: ${passes} pass, ${fails} fail (exit ${testRun.exitCode})`);
+  }
+
+  const matrixResult = verifyMatrix({ anchors, status, testResults, specIsStub });
+  const findings = [...matrixResult.findings];
+
+  // Phase 2 (A-sot): manifest validation + ADR-line grep. validateManifest and
+  // checkAdrLines are spec-independent (manifest/code health) and run always;
+  // checkManifestCoverage keys off the spec status (a no-op under STUB_SPEC,
+  // where status is empty).
+  const needsCorpus = manifest.some((r) => r.adrKeyLine !== NO_ADR);
+  const adrSearch = needsCorpus
+    ? buildCorpusSearch({ repoRoot: REPO, includeDirs: CORPUS_DIRS, excludePaths: CORPUS_EXCLUDE })
+    : () => false;
+  const adrExists = (adrPath) => existsSync(join(opts.hypoDir, 'projects/hypomnema', adrPath));
+  findings.push(...validateManifest(manifest));
+  findings.push(...checkManifestCoverage({ manifest, anchors, status }));
+  findings.push(...checkAdrLines({ manifest, searchFn: adrSearch, adrExistsFn: adrExists }));
+
+  // CLI-level error: if the test command itself exited nonzero, the test run
+  // is not green even if the anchored tests happen to all pass in the parsed
+  // output. Surface as a synthetic error finding so `ok` flips false.
+  if (testRun.exitCode !== 0) {
+    findings.push({
+      level: 'error',
+      class: 'TEST_RUN_NONZERO_EXIT',
+      detail: `test command "${opts.testCommand}" exited ${testRun.exitCode}`,
+      exitCode: testRun.exitCode,
+    });
+  }
+  const ok = !findings.some((f) => f.level === 'error') && testRun.exitCode === 0;
+
+  const MANDATORY_NOTE =
+    'test-linkage + green + ADR-line grep (Phase 2): manifest evidence checked against production corpus';
+
+  if (opts.json) {
+    console.log(
+      JSON.stringify(
+        {
+          ok,
+          spec: opts.spec,
+          runner: opts.runner,
+          statusClaims: status.size,
+          anchorCount: anchors.size,
+          testsRan: testResults.size,
+          testExitCode: testRun.exitCode,
+          findings,
+          note: MANDATORY_NOTE,
+        },
+        null,
+        2,
+      ),
+    );
+  } else {
+    const errors = findings.filter((f) => f.level === 'error');
+    const warns = findings.filter((f) => f.level === 'warn');
+    if (errors.length === 0 && warns.length === 0) {
+      console.log(`  ✓ all ${status.size} claimed-merged fix(es) verified`);
+    } else {
+      if (errors.length) {
+        console.log(`\nerrors (${errors.length}):`);
+        for (const f of errors) console.log(formatFinding(f));
+      }
+      if (warns.length) {
+        console.log(`\nwarnings (${warns.length}):`);
+        for (const f of warns) console.log(formatFinding(f));
+      }
+    }
+    console.log(`\n(${MANDATORY_NOTE})`);
+  }
+
+  process.exit(ok ? 0 : 1);
+}
+
+main().catch((e) => {
+  console.error(e);
+  process.exit(2);
+});

package/scripts/init.mjs

@@ -46,6 +46,7 @@ import {
   readFileIfRegular,
 } from './lib/pkg-json.mjs';
 import { syncExtensions } from './lib/extensions.mjs';
+import { classifyInstall, downgradeGuardMessage } from '../hooks/version-check.mjs';
 
 const HOME = homedir();
 const SCRIPT_DIR = fileURLToPath(new URL('.', import.meta.url));
@@ -108,6 +109,7 @@ function parseArgs(argv) {
     fromRemote: null,
     shellSetup: true,
     shellConfig: null,
+    allowDowngrade: false,
   };
   for (const arg of argv.slice(2)) {
     if (arg === '--help' || arg === '-h') {
@@ -136,6 +138,8 @@ Init options:
   --from-remote=<url>    Clone existing Hypomnema wiki from remote and install hooks
   --no-shell             Skip shell function setup (~/.zshrc / ~/.bashrc)
   --shell-config=<path>  Shell config file path (default: auto-detect)
+  --allow-downgrade      Override the guard that refuses to overwrite NEWER active
+                         hooks with an older package (stale-PATH-CLI footgun)
   --dry-run              Show what would be done without making changes
   --help, -h             Show this help message
 
@@ -160,6 +164,7 @@ docstring at the top of scripts/<command>.mjs.`);
     } else if (arg === '--dry-run') args.dryRun = true;
     else if (arg === '--no-shell') args.shellSetup = false;
     else if (arg.startsWith('--shell-config=')) args.shellConfig = expandHome(arg.slice(15));
+    else if (arg === '--allow-downgrade') args.allowDowngrade = true;
   }
   return args;
 }
@@ -419,6 +424,27 @@ function pkgJsonPath() {
   return join(HOME, '.claude', 'hypo-pkg.json');
 }
 
+/**
+ * ADR 0038 (P): abort when this package would DOWNGRADE a newer active install.
+ * Exit 2 (distinct from the generic exit-1 error class) on refusal so callers and
+ * tests can tell "refused downgrade" apart from "init failed". No-ops on a fresh
+ * install (no metadata), unparseable versions, the same package re-running itself,
+ * --allow-downgrade, or --dry-run.
+ */
+function maybeRefuseDowngrade(op, allowDowngrade, dryRun) {
+  if (allowDowngrade || dryRun) return;
+  const active = readPkgJsonSafe(pkgJsonPath());
+  if (!active || !active.pkgVersion || !PKG_VERSION) return;
+  const verdict = classifyInstall(
+    { pkgRoot: PKG_ROOT, version: PKG_VERSION },
+    { pkgRoot: active.pkgRoot, version: active.pkgVersion },
+  );
+  if (verdict === 'downgrade') {
+    console.error(downgradeGuardMessage(PKG_VERSION, active.pkgVersion, op));
+    process.exit(2);
+  }
+}
+
 function writePkgJson(dryRun, extraFields = {}) {
   const dest = pkgJsonPath();
   const existing = readPkgJsonSafe(dest);
@@ -777,6 +803,17 @@ const args = parseArgs(process.argv);
 // Validate hooks.json before any file writes so a bad package leaves no partial state
 const HOOK_MAP = args.hooks || args.codex ? loadHookMap() : null;
 
+// Downgrade guard (ADR 0038, P): refuse to overwrite a NEWER active install with
+// an older package. The footgun: a stale `npm i -g hypomnema` owns the `hypomnema`
+// bin on PATH, so `hypomnema init` runs the OLD package and silently downgrades
+// the newer install (dropping features like the update-notifier). Runs
+// UNCONDITIONALLY before the first write — `--no-hooks --no-commands` is NOT safe:
+// init still installs the wiki pre-commit hook (repointed to the stale pkgRoot)
+// and, with `--codex`, writes ~/.codex hooks/settings. The guard no-ops on a fresh
+// install, same realpath'd pkgRoot (dev re-run / npm-link / post-commit sync),
+// --allow-downgrade, or --dry-run, so legitimate flows are unaffected.
+maybeRefuseDowngrade('init', args.allowDowngrade, args.dryRun);
+
 if (args.fromRemote) {
   // ── from-remote path: clone → read config → install hooks ──────────────────
   const cloned = cloneFromRemote(args.fromRemote, args.hypoDir, args.dryRun);
@@ -863,9 +900,13 @@ if (args.hooks) {
   mergeSettingsJson(join(HOME, '.claude', 'settings.json'), claudeHooks, args.dryRun, HOOK_MAP);
 }
 
-if (args.hooks || args.commands) {
-  writePkgJson(args.dryRun, commandSHAs ? { commands: commandSHAs } : {});
-}
+// Always record the active install identity (pkgRoot + pkgVersion), even for a
+// --no-hooks --no-commands scaffold. That flow still installs the wiki pre-commit
+// hook (and, with --codex, ~/.codex hooks); without a recorded pkgVersion baseline
+// the ADR 0038 downgrade guard has nothing to compare against, so a later stale
+// sibling could repoint those surfaces unguarded. writePkgJson merges (...existing),
+// so this never clobbers a commands/extensions map written elsewhere.
+writePkgJson(args.dryRun, commandSHAs ? { commands: commandSHAs } : {});
 
 // 4b. user extensions companion sync (ADR 0024). Runs after
 // writePkgJson so the per-target SHA map is merged into the same hypo-pkg.json
@@ -887,7 +928,7 @@ if (args.hooks) {
   }
   for (const r of extResult.registered) log('merged', `extension ${r}`);
   for (const w of extResult.warnings) log('skipped', `extension: ${w}`);
-  // E3 (#31): a hard conflict (unowned/symlinked target) blocks install — surface
+  // E3 (fix #31): a hard conflict (unowned/symlinked target) blocks install — surface
   // the recovery and force a non-zero exit. Drift is advisory (resolvable, no block).
   if (extResult.conflicts.length > 0) {
     log('errors', '[WIKI: existing file conflicts. Backup and retry, or use --force-extensions]');

package/scripts/install-git-hooks.mjs

@@ -0,0 +1,258 @@
+#!/usr/bin/env node
+/**
+ * scripts/install-git-hooks.mjs — idempotent git pre-commit hook installer.
+ *
+ * Wired into package.json as the `prepare` script so it runs after every
+ * `npm install` / `npm ci` in this checkout. The installer is FULLY fail-open:
+ * any filesystem or git error → silent exit 0. The CLAUDE.md formatter rule
+ * is best-effort; a failed install must never block contributor onboarding.
+ *
+ * Trust model:
+ *   - `expectedRoot` is derived from THIS script's filesystem location (via
+ *     `import.meta.url` → realpath), NOT from `git rev-parse`. Git probes
+ *     can be redirected by ambient GIT_DIR/GIT_WORK_TREE; the script's own
+ *     path cannot.
+ *   - All git probes use a scrubbed env (every name from `--local-env-vars`
+ *     plus GIT_NAMESPACE / GIT_CEILING_DIRECTORIES / GIT_CONFIG_*).
+ *   - Probes run with `cwd: expectedRoot` so npm `--prefix` invocations
+ *     can't redirect resolution either.
+ *   - Generated shim embeds `HYPOMNEMA_ROOT` + `HYPOMNEMA_GIT_DIR`. Runtime
+ *     shim refuses to exec unless both literals match the current values.
+ *
+ * Refusal conditions (all exit 0):
+ *   - `CI=true` env (npm ci on CI runs prepare; we must not touch hooks)
+ *   - `npm_command` in {pack, publish} or `npm_lifecycle_event=prepublishOnly`
+ *   - `.git/` absent (consumer install of the published tarball)
+ *   - linked worktree (--absolute-git-dir != --git-common-dir)
+ *   - toplevel != expectedRoot
+ *   - hooks dir / pre-commit file is a symlink
+ *   - existing non-marker pre-commit (don't clobber the user's own hook)
+ *   - any filesystem error (ENOENT, EPERM, EACCES, …)
+ *
+ * Verbose mode: set HYPOMNEMA_HOOK_VERBOSE=1 to see skip/install reasons.
+ */
+
+import { execFileSync } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
+import url from 'node:url';
+
+function exitSilent(msg) {
+  if (process.env.HYPOMNEMA_HOOK_VERBOSE === '1') {
+    process.stderr.write(`[install-git-hooks] ${msg}\n`);
+  }
+  process.exit(0);
+}
+
+// Static fallback list for `--local-env-vars`. Used when we don't yet have a
+// trusted git invocation (the installer is bootstrapping its own trust chain),
+// and also when git is too old to support `--local-env-vars`.
+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',
+    ...Object.keys(process.env).filter((k) => /^GIT_CONFIG_/.test(k)),
+  ]);
+  return Object.fromEntries(Object.entries(process.env).filter(([k]) => !scrub.has(k)));
+}
+
+function shellSingleQuote(s) {
+  // POSIX-safe: 'x' → 'x', x'y → 'x'\''y'
+  return `'` + s.replace(/'/g, `'\\''`) + `'`;
+}
+
+function shimBody(root, gitDir) {
+  return `#!/bin/sh
+# hypomnema-pre-commit-marker v1
+# Fail-open at every guard. Only the .mjs (after identity checks) can exit nonzero.
+set +e
+HYPOMNEMA_ROOT=${shellSingleQuote(root)}
+HYPOMNEMA_GIT_DIR=${shellSingleQuote(gitDir)}
+TOPLEVEL="$(git rev-parse --show-toplevel 2>/dev/null)" || exit 0
+[ -z "$TOPLEVEL" ] && exit 0
+[ "$TOPLEVEL" = "$HYPOMNEMA_ROOT" ] || exit 0
+ABSGITDIR="$(git rev-parse --absolute-git-dir 2>/dev/null)" || exit 0
+[ "$ABSGITDIR" = "$HYPOMNEMA_GIT_DIR" ] || exit 0
+SCRIPT="$HYPOMNEMA_ROOT/scripts/pre-commit-format.mjs"
+[ -f "$SCRIPT" ] || exit 0
+command -v node >/dev/null 2>&1 || exit 0
+# Sentinel: tells the .mjs it is running under our trusted shim (not direct
+# attacker invocation). The .mjs preserves inherited GIT_INDEX_FILE only when
+# this sentinel is present — direct invocation drops it and falls back to the
+# default \`.git/index\`. This closes prefix-matching attacks on the index
+# whitelist (e.g. attacker-crafted .git/next-index-attack.lock).
+HYPOMNEMA_HOOK_INVOCATION=1 exec node "$SCRIPT"
+`;
+}
+
+function writeShim(target, root, gitDir) {
+  try {
+    fs.writeFileSync(target, shimBody(root, gitDir), { mode: 0o755 });
+    try {
+      fs.chmodSync(target, 0o755);
+    } catch {}
+    return exitSilent(`installed pre-commit hook for ${root}`);
+  } catch (e) {
+    return exitSilent(`write hook failed: ${e.code || e.message}; skipping`);
+  }
+}
+
+async function main() {
+  try {
+    // (0) CI / lifecycle guards.
+    if (process.env.CI === 'true') return exitSilent('CI=true; skipping');
+    const lc = process.env.npm_command;
+    if (lc === 'pack' || lc === 'publish') {
+      return exitSilent(`npm_command=${lc}; skipping`);
+    }
+    if (process.env.npm_lifecycle_event === 'prepublishOnly') {
+      return exitSilent('prepublishOnly; skipping');
+    }
+
+    // (1) Derive expectedRoot from THIS script's location, not from git.
+    const here = path.dirname(url.fileURLToPath(import.meta.url));
+    let expectedRoot;
+    try {
+      expectedRoot = fs.realpathSync(path.resolve(here, '..'));
+    } catch {
+      return exitSilent('cannot resolve script location; skipping');
+    }
+
+    // (2) Bootstrap scrubbed env with the static fallback list, just enough to
+    //     get a trusted git probe running. Then enrich from --local-env-vars at
+    //     runtime (modern git) so the scrub list always tracks git's own truth.
+    let cleanEnv = buildScrubbedEnv(null);
+    let run = (args) =>
+      execFileSync('git', args, {
+        encoding: 'utf-8',
+        env: cleanEnv,
+        cwd: expectedRoot,
+      }).trim();
+    try {
+      const list = run(['rev-parse', '--local-env-vars']).split(/\r?\n/).filter(Boolean);
+      cleanEnv = buildScrubbedEnv(list);
+      run = (args) =>
+        execFileSync('git', args, {
+          encoding: 'utf-8',
+          env: cleanEnv,
+          cwd: expectedRoot,
+        }).trim();
+    } catch {
+      // Old git without --local-env-vars; keep static-list cleanEnv.
+    }
+
+    // (3) Probe git with sanitized env.
+    let topR, absGitDir, commonDir;
+    try {
+      topR = fs.realpathSync(run(['rev-parse', '--show-toplevel']));
+      absGitDir = fs.realpathSync(run(['rev-parse', '--absolute-git-dir']));
+      const cd = run(['rev-parse', '--git-common-dir']);
+      commonDir = fs.realpathSync(path.isAbsolute(cd) ? cd : path.join(absGitDir, '..', cd));
+    } catch {
+      return exitSilent('git probe failed; skipping');
+    }
+
+    // (4) Identity + worktree + containment.
+    if (topR !== expectedRoot) {
+      return exitSilent('toplevel != expectedRoot; skipping');
+    }
+    if (absGitDir !== commonDir) {
+      return exitSilent('linked worktree; skipping');
+    }
+    if (!absGitDir.startsWith(expectedRoot + path.sep)) {
+      return exitSilent('gitDir outside expectedRoot; skipping');
+    }
+
+    // (5) Resolve hooks dir (still under sanitized env).
+    let rawHooksDir;
+    try {
+      rawHooksDir = run(['rev-parse', '--git-path', 'hooks']);
+    } catch {
+      return exitSilent('cannot resolve hooks dir; skipping');
+    }
+    if (!path.isAbsolute(rawHooksDir)) {
+      rawHooksDir = path.resolve(expectedRoot, rawHooksDir);
+    }
+
+    if (!fs.existsSync(rawHooksDir)) {
+      // Git creates .git/hooks lazily. Only create when it would land inside
+      // absGitDir — protects against `core.hooksPath=/elsewhere`.
+      if (!rawHooksDir.startsWith(absGitDir + path.sep)) {
+        return exitSilent('hooks dir outside gitDir; skipping');
+      }
+      try {
+        fs.mkdirSync(rawHooksDir, { recursive: true });
+      } catch {
+        return exitSilent('mkdir hooks dir failed; skipping');
+      }
+    }
+
+    let absHooksDir;
+    try {
+      absHooksDir = fs.realpathSync(rawHooksDir);
+    } catch {
+      return exitSilent('realpath hooks dir failed; skipping');
+    }
+
+    // (6) Symlink rejection + containment.
+    try {
+      if (fs.lstatSync(rawHooksDir).isSymbolicLink()) {
+        return exitSilent('hooks dir is symlink; skipping');
+      }
+    } catch {
+      return exitSilent('lstat hooks dir failed; skipping');
+    }
+    const rel = path.relative(absGitDir, absHooksDir);
+    if (rel.startsWith('..') || path.isAbsolute(rel)) {
+      return exitSilent('hooks dir outside .git/; skipping');
+    }
+
+    // (7) Existing pre-commit logic.
+    const target = path.join(absHooksDir, 'pre-commit');
+    let existing;
+    try {
+      existing = fs.lstatSync(target);
+    } catch (e) {
+      if (e.code === 'ENOENT') {
+        return writeShim(target, expectedRoot, absGitDir);
+      }
+      return exitSilent(`stat target failed: ${e.code}; skipping`);
+    }
+    if (existing.isSymbolicLink()) {
+      return exitSilent('pre-commit is symlink; not overwriting');
+    }
+    let head;
+    try {
+      head = fs.readFileSync(target, 'utf-8').split('\n').slice(0, 3).join('\n');
+    } catch {
+      return exitSilent('read existing pre-commit failed; skipping');
+    }
+    if (head.includes('hypomnema-pre-commit-marker v1')) {
+      // Same marker — regenerate (refreshes embedded root if checkout moved).
+      return writeShim(target, expectedRoot, absGitDir);
+    }
+    return exitSilent('existing non-marker pre-commit; not overwriting');
+  } catch (e) {
+    return exitSilent(`unexpected: ${e.code || e.message}; skipping`);
+  }
+}
+
+main();

package/scripts/lib/adr-corpus.mjs

@@ -0,0 +1,79 @@
+/**
+ * adr-corpus — fs-backed production-code corpus search for the ADR-line grep.
+ *
+ * Kept separate from the pure verifier (scripts/lib/fix-status-verify.mjs) so
+ * that layer stays IO-free and unit-testable with injected searchFns. This
+ * module is itself testable against real temp directories.
+ *
+ * CRITICAL (self-match): the manifest module (scripts/lib/fix-manifest.mjs)
+ * lives *inside* the scripts/ corpus and holds every adrKeyLine as a literal.
+ * If it were scanned, every line would self-match and ADR_LINE_MISSING could
+ * never fire — the gate would be silently vacuous. The builder therefore
+ * excludes caller-supplied paths, resolved absolute, BEFORE reading any file.
+ */
+
+import { readdirSync, readFileSync, statSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+
+const DEFAULT_EXTENSIONS = ['.mjs', '.js', '.md', '.json', '.cjs'];
+
+function* walk(dir, excludeAbs, extensions) {
+  let entries;
+  try {
+    entries = readdirSync(dir, { withFileTypes: true });
+  } catch {
+    return; // missing corpus dir is not fatal — other dirs may exist
+  }
+  for (const ent of entries) {
+    const full = join(dir, ent.name);
+    if (excludeAbs.has(resolve(full))) continue;
+    if (ent.isDirectory()) {
+      if (ent.name === 'node_modules' || ent.name === '.git') continue;
+      yield* walk(full, excludeAbs, extensions);
+    } else if (ent.isFile()) {
+      if (extensions.some((e) => ent.name.endsWith(e))) yield full;
+    }
+  }
+}
+
+/**
+ * Build a fixed-string corpus search function.
+ *
+ *   buildCorpusSearch({ repoRoot, includeDirs, excludePaths, extensions })
+ *     → (literal:string) => boolean
+ *
+ * - includeDirs / excludePaths are resolved relative to repoRoot.
+ * - excludePaths are matched by resolved absolute path (handles symlinks of the
+ *   caller-supplied path consistently with the walk's resolve()).
+ * - search is case-sensitive String.includes (fixed string, not regex).
+ *
+ * Files are read once and cached so repeated searches (one per manifest row)
+ * do not re-walk the tree.
+ */
+export function buildCorpusSearch({
+  repoRoot,
+  includeDirs,
+  excludePaths = [],
+  extensions = DEFAULT_EXTENSIONS,
+}) {
+  const excludeAbs = new Set(excludePaths.map((p) => resolve(repoRoot, p)));
+  const contents = [];
+  for (const dir of includeDirs) {
+    const abs = resolve(repoRoot, dir);
+    let isDir = false;
+    try {
+      isDir = statSync(abs).isDirectory();
+    } catch {
+      isDir = false;
+    }
+    if (!isDir) continue;
+    for (const file of walk(abs, excludeAbs, extensions)) {
+      try {
+        contents.push(readFileSync(file, 'utf-8'));
+      } catch {
+        /* unreadable file — skip */
+      }
+    }
+  }
+  return (literal) => contents.some((text) => text.includes(literal));
+}