hypomnema 1.2.1 → 1.3.1

package/scripts/doctor.mjs

@@ -31,7 +31,8 @@ import {
   EXT_TYPES,
   CODEX_TYPES,
 } from './lib/extensions.mjs';
-import { sha256, readFileIfRegular } from './lib/pkg-json.mjs';
+import { sha256, readFileIfRegular, readPkgJson } from './lib/pkg-json.mjs';
+import { resolveCliOnPath, classifyInstall } from '../hooks/version-check.mjs';
 
 const HOME = homedir();
 const SCRIPT_DIR = fileURLToPath(new URL('.', import.meta.url));
@@ -221,7 +222,7 @@ function checkDirectories(hypoDir) {
     'projects',
     'sources',
     // Extensions baseline (ADR 0024). Existence only — SHA / settings /
-    // manifest integrity is E5 (#33).
+    // manifest integrity is E5 (fix #33).
     'extensions/hooks',
     'extensions/commands',
     'extensions/skills',
@@ -306,10 +307,10 @@ function checkSettingsJson() {
     fail('settings.json hook registrations', `0/${total} registered — run /hypo:init`);
   }
 
-  // fix #7: stale hypo-* entries (uninstall remnants).
+  // stale hypo-* entries (uninstall remnants).
   // hypo-ext-* commands are user-extension entries (ADR 0024) — not core hooks,
   // so they are intentionally absent from HOOK_MAP. Excluded here; their
-  // integrity (SHA + manifest + entry match) is checked separately in E5 (#33).
+  // integrity (SHA + manifest + entry match) is checked separately in E5 (fix #33).
   const isExtCommand = (cmd) => /(?:^|[/\s])hypo-ext-[^/\s]+\.mjs(?=$|["'\s])/.test(cmd);
   const expectedCmds = new Set(
     Object.entries(HOOK_MAP).flatMap(([, files]) =>
@@ -342,7 +343,7 @@ function checkSettingsJson() {
     pass('settings.json stale hypo-* entries', 'None');
   }
 
-  // fix #7: duplicate hypo-* entries per event
+  // duplicate hypo-* entries per event
   const dupes = [];
   for (const [event, groups] of Object.entries(settings.hooks || {})) {
     if (!Array.isArray(groups)) continue;
@@ -351,7 +352,7 @@ function checkSettingsJson() {
       if (!g || typeof g !== 'object') continue;
       for (const h of g.hooks || []) {
         if (typeof h.command !== 'string' || !/hypo-[^/]+\.mjs/.test(h.command)) continue;
-        if (isExtCommand(h.command)) continue; // ext duplicates are E5's concern (#33)
+        if (isExtCommand(h.command)) continue; // ext duplicates are E5's concern (fix #33)
         if (seen.has(h.command)) dupes.push(`${event}:${h.command}`);
         else seen.add(h.command);
       }
@@ -538,12 +539,12 @@ function checkSyncState(hypoDir) {
 }
 
 function checkProjectSuggestions(hypoDir) {
-  // fix #23 / ADR 0023: the auto-project skip-persistence store. Absent file is
+  // ADR 0023: the auto-project skip-persistence store. Absent file is
   // healthy (no offers declined yet). Validate the RAW JSON shape here rather
   // than via readProjectSuggestions(): that helper deliberately normalizes a
   // non-array `skips` to [] for fail-open hook reads, which would mask a
-  // malformed file and silently break permanent "N" suppression (codex review
-  // 2026-05-22). Doctor must catch the malformation the helper hides.
+  // malformed file and silently break permanent "N" suppression. Doctor must
+  // catch the malformation the helper hides.
   const path = projectSuggestionsPath(hypoDir);
   if (!existsSync(path)) {
     pass('Auto-project suggestions', 'No skip-persistence file (clean)');
@@ -1008,6 +1009,40 @@ function checkFeedbackProjection(hypoDir, claudeHome, projectId) {
   }
 }
 
+// ── stale sibling install (ADR 0038, D) ──────────────────────────────────────
+//
+// Detect a SECOND, older Hypomnema that owns the `hypomnema` bin on PATH while a
+// newer copy owns the active hooks. That sibling is a footgun: `hypomnema init` /
+// `upgrade --apply` routed through it downgrades the active hooks. This is a
+// detective backstop to the preventive init/upgrade guard — but it must NOT be
+// the only surface, since `hypomnema doctor` invoked via the stale CLI would run
+// the OLD doctor (the active-hook notifier covers that live case). fs-only.
+function checkStaleSibling() {
+  const active = readPkgJson(join(HOME, '.claude', 'hypo-pkg.json'));
+  if (!active || !active.pkgVersion) {
+    pass('PATH CLI vs active install', 'no active metadata (skipped)');
+    return;
+  }
+  const cli = resolveCliOnPath('hypomnema');
+  if (!cli) {
+    pass('PATH CLI vs active install', `no \`hypomnema\` on PATH (active v${active.pkgVersion})`);
+    return;
+  }
+  const verdict = classifyInstall(
+    { pkgRoot: cli.pkgRoot, version: cli.version },
+    { pkgRoot: active.pkgRoot, version: active.pkgVersion },
+  );
+  if (verdict === 'downgrade') {
+    warn(
+      'PATH CLI vs active install',
+      `stale sibling: \`${cli.binPath}\` is v${cli.version}, active is v${active.pkgVersion} — ` +
+        `running it would DOWNGRADE hooks. Remove with \`npm uninstall -g hypomnema\``,
+    );
+  } else {
+    pass('PATH CLI vs active install', `v${cli.version} (active v${active.pkgVersion})`);
+  }
+}
+
 // ── main ─────────────────────────────────────────────────────────────────────
 
 const args = parseArgs(process.argv);
@@ -1023,6 +1058,7 @@ if (rootOk) {
 }
 checkHooks();
 checkSettingsJson();
+checkStaleSibling();
 if (args.codex) checkCodexPaths();
 if (rootOk) checkExtensions(args.hypoDir, args.claudeHome, 'claude');
 if (rootOk && args.codex) checkExtensions(args.hypoDir, args.claudeHome, 'codex');

package/scripts/feedback-sync.mjs

@@ -205,7 +205,7 @@ function regionHasIntruders(content) {
   return span.trim().length > 0;
 }
 
-// ── projection targets (descriptor abstraction — ADR 0032 reuse) ──────────────
+// ── projection targets (descriptor abstraction) ──────────────────────────────
 
 const PUBLIC_SENSITIVITY = new Set(['public', 'sanitized']);
 
@@ -439,7 +439,7 @@ function applyTarget(target, res) {
   }
 }
 
-// ── project-id derivation (contract §5, OQ-31.3) ──────────────────────────────
+// ── project-id derivation ─────────────────────────────────────────────────────
 
 function deriveProjectId(args) {
   if (args.projectId) return { id: args.projectId, derived: false, exists: true };
@@ -602,7 +602,7 @@ function bootstrapDraftContent({ title, summary, body, date, origin }) {
     `title: ${title}`,
     'type: feedback',
     'status: draft',
-    'scope: TODO              # global | project:<slug>',
+    'scope: TODO              # global | project:<project-id>',
     'tier: TODO               # L1 (CLAUDE.md <learned_behaviors> candidate) | L2',
     'targets: [project-memory]   # + claude-learned for a global L1 rule',
     'sensitivity: public      # public | sanitized (private is forbidden)',
@@ -660,13 +660,18 @@ function existingPageSlugs(hypoDir) {
   );
 }
 
-// --bootstrap: read the two legacy projection surfaces (CLAUDE.md
-// <learned_behaviors> + MEMORY.md feedback_* index) and scaffold drafts.
-function runBootstrap(args) {
-  const draftsDir = join(args.hypoDir, 'pages', 'feedback', '_drafts');
-  const existing = existingPageSlugs(args.hypoDir);
-  const report = { mode: 'bootstrap', dryRun: args.dryRun, created: [], skipped: [] };
+// Source loader for --bootstrap (input side, symmetric with the output-side
+// target descriptors): read the two legacy projection surfaces — CLAUDE.md
+// <learned_behaviors> + the project MEMORY.md feedback_* index — and shape them
+// into ordered draft candidates. CLAUDE candidates come first (file order from
+// parseLearnedBehaviors), then MEMORY (parseMemoryIndex order); this order drives
+// duplicate handling in runBootstrap, so it must be preserved. Returns
+// { candidates, warnings, skipped } where `skipped` carries the unsafe MEMORY
+// slugs the loader could not sanitize (seeded into report.skipped before the
+// dedup loop appends its own skips).
+function loadBootstrapSources(args) {
   const warnings = [];
+  const skipped = [];
   const candidates = [];
 
   const claudeFile = join(args.claudeHome, 'CLAUDE.md');
@@ -692,7 +697,7 @@ function runBootstrap(args) {
     for (const e of parseMemoryIndex(readFileSync(memFile, 'utf-8'))) {
       const slug = safeDraftSlug(e.name.replace(/_/g, '-'));
       if (!slug) {
-        report.skipped.push({ slug: e.name, reason: 'unsafe-slug' });
+        skipped.push({ slug: e.name, reason: 'unsafe-slug' });
         continue;
       }
       candidates.push({
@@ -710,6 +715,17 @@ function runBootstrap(args) {
     );
   }
 
+  return { candidates, warnings, skipped };
+}
+
+// --bootstrap: load the two legacy projection surfaces (loadBootstrapSources)
+// and scaffold one draft per deduped candidate.
+function runBootstrap(args) {
+  const draftsDir = join(args.hypoDir, 'pages', 'feedback', '_drafts');
+  const existing = existingPageSlugs(args.hypoDir);
+  const { candidates, warnings, skipped } = loadBootstrapSources(args);
+  const report = { mode: 'bootstrap', dryRun: args.dryRun, created: [], skipped: [...skipped] };
+
   const seen = new Set();
   for (const c of candidates) {
     if (seen.has(c.slug)) {
@@ -736,20 +752,33 @@ function runBootstrap(args) {
   return { code: 0, report, warnings };
 }
 
-// --import-target-change --from=<memory|claude>: capture hand-edited (conflict)
-// managed blocks back into drafts so the human can reconcile them into the SoT.
-function runImport(args) {
+// Source loader for --import-target-change (input side): select the target
+// projection file (CLAUDE.md or the project MEMORY.md), read it, and return the
+// managed blocks whose inner content no longer matches their marker hash
+// (hand-edited = conflict). This IS the import contract — findBlocks + hash-
+// mismatch filter, NOT projection evaluation. Returns { file, conflicts } or
+// { error } for an invalid --from / missing target file.
+function loadImportConflicts(args) {
   if (args.from !== 'memory' && args.from !== 'claude') {
-    return { code: 1, error: '--import-target-change requires --from=memory|claude' };
+    return { error: '--import-target-change requires --from=memory|claude' };
   }
   const file =
     args.from === 'claude'
       ? join(args.claudeHome, 'CLAUDE.md')
       : join(args.claudeHome, 'projects', deriveProjectId(args).id, 'memory', 'MEMORY.md');
-  if (!existsSync(file)) return { code: 1, error: `target file not found: ${file}` };
+  if (!existsSync(file)) return { error: `target file not found: ${file}` };
 
   const { blocks } = findBlocks(readFileSync(file, 'utf-8'));
   const conflicts = blocks.filter((b) => b.actualHash !== b.declaredHash);
+  return { file, conflicts };
+}
+
+// --import-target-change --from=<memory|claude>: capture hand-edited (conflict)
+// managed blocks back into drafts so the human can reconcile them into the SoT.
+function runImport(args) {
+  const src = loadImportConflicts(args);
+  if (src.error) return { code: 1, error: src.error };
+  const { file, conflicts } = src;
   const report = { mode: 'import', from: args.from, dryRun: args.dryRun, imported: [] };
   const warnings = [];
   if (!conflicts.length) {

package/scripts/feedback.mjs

@@ -19,7 +19,7 @@
  *   --title=<text>          Frontmatter title (default: topic)
  *
  * Classification (lint #8 schema — required on create):
- *   --scope=<v>             global | project:<slug>           (required)
+ *   --scope=<v>             global | project:<project-id>     (required)
  *   --tier=<v>              L1 | L2                            (required)
  *   --targets=<list>        comma list of project-memory,claude-learned (default: project-memory)
  *   --sensitivity=<v>       public | sanitized                (default: public)
@@ -47,6 +47,7 @@ import { join } from 'path';
 import { spawnSync } from 'child_process';
 import { fileURLToPath } from 'url';
 import { resolveHypoRoot, expandHome } from './lib/hypo-root.mjs';
+import { FEEDBACK_SCOPE_RE } from './lib/feedback-scope.mjs';
 
 const SCRIPT_DIR = fileURLToPath(new URL('.', import.meta.url));
 
@@ -120,7 +121,6 @@ function listTopics(hypoDir) {
 
 // ── classification validation (mirrors lint #8 / ADR 0031 §6) ──────────────────
 
-const SCOPE_RE = /^(global|project:[a-z0-9][a-z0-9-]*)$/;
 const TIER_ENUM = ['L1', 'L2'];
 const SENSITIVITY_ENUM = ['public', 'sanitized']; // private is forbidden (wiki is git-public)
 const TARGET_ENUM = ['project-memory', 'claude-learned'];
@@ -135,8 +135,8 @@ function parseTargets(raw) {
 // Validate the create-mode classification. Returns an array of error strings.
 function validateClassification(args, targets) {
   const errs = [];
-  if (!args.scope) errs.push('--scope is required (global | project:<slug>)');
-  else if (!SCOPE_RE.test(args.scope)) errs.push(`--scope invalid: "${args.scope}"`);
+  if (!args.scope) errs.push('--scope is required (global | project:<project-id>)');
+  else if (!FEEDBACK_SCOPE_RE.test(args.scope)) errs.push(`--scope invalid: "${args.scope}"`);
   if (!args.tier) errs.push('--tier is required (L1 | L2)');
   else if (!TIER_ENUM.includes(args.tier)) errs.push(`--tier invalid: "${args.tier}"`);
   if (!SENSITIVITY_ENUM.includes(args.sensitivity))
@@ -222,7 +222,7 @@ function renderPage(args, targets, today) {
 // it the freshest correction, so it should sort first. Rewrite the `updated:`
 // line ONLY inside the leading frontmatter block (between the first pair of
 // `---` fences). A naive multiline replace would also rewrite any body line that
-// happens to start with "updated:" (codex review) — so we scope to the fence.
+// happens to start with "updated:" — so we scope to the fence.
 function bumpUpdated(content, today) {
   const m = content.match(/^---\n([\s\S]*?)\n---/);
   if (!m) return content; // no frontmatter → nothing to bump

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]');