hypomnema 1.2.1 → 1.3.0

package/scripts/lint.mjs

@@ -11,6 +11,9 @@
  *   --hypo-dir=<path>   Hypomnema root (default: resolved via HYPO_DIR / hypo-config.md / ~/hypomnema)
  *   --json              Output results as JSON
  *   --fix               Auto-add missing `updated` field (safe repairs only)
+ *   --strict            Promote selected warnings (STRICT_PROMOTE_IDS) to errors
+ *                       so they exit 1. Opt-in gate for release-checklist /
+ *                       pre-commit; default mode stays byte-identical.
  */
 
 import { existsSync, readFileSync, writeFileSync, readdirSync, statSync } from 'fs';
@@ -20,15 +23,17 @@ import { SESSION_STATE_NEXT_HEADINGS } from '../hooks/hypo-shared.mjs';
 import { loadHypoIgnore, isIgnored } from './lib/hypo-ignore.mjs';
 import { parseSchemaVocab, checkForbidden, parseSchemaPageDirs } from './lib/schema-vocab.mjs';
 import { findDesignHistoryStale } from './lib/design-history-stale.mjs';
+import { FEEDBACK_SCOPE_RE } from './lib/feedback-scope.mjs';
 
 // ── arg parsing ──────────────────────────────────────────────────────────────
 
 function parseArgs(argv) {
-  const args = { hypoDir: null, json: false, fix: false };
+  const args = { hypoDir: null, json: false, fix: false, strict: false };
   for (const arg of argv.slice(2)) {
     if (arg.startsWith('--hypo-dir=')) args.hypoDir = expandHome(arg.slice(11));
     else if (arg === '--json') args.json = true;
     else if (arg === '--fix') args.fix = true;
+    else if (arg === '--strict') args.strict = true;
   }
   if (!args.hypoDir) args.hypoDir = resolveHypoRoot();
   return args;
@@ -198,6 +203,20 @@ const VALID_TYPES = [
 
 const issues = [];
 
+// Stable warning class IDs (W1..Wn). `--strict` promotes a frozen subset to
+// errors by ID — never by brittle message-text matching. W8 (design-history
+// stale) predates this scheme; hooks/hypo-personal-check.mjs filters `w.id ===
+// 'W8'`, so it must keep that number — the W5..W7 gap is honest history, not a
+// bug. (spec-v1.3.0 Track E)
+//
+// STRICT_PROMOTE_IDS (OQ-E1, frozen as a code constant): confirmed content
+// defects only.
+//   W1 no-frontmatter / W2 unknown-type / W4 broken-wikilink → promote.
+//   W3 missing-updated  → excluded (auto-repaired by --fix).
+//   W8 design-history-stale → excluded (hypo-personal-check handles it; would
+//                             double-gate).
+const STRICT_PROMOTE_IDS = new Set(['W1', 'W2', 'W4']);
+
 function issue(severity, rel, msg, fullPath = null, id = null) {
   issues.push({ severity, file: rel, message: msg, path: fullPath, id });
 }
@@ -249,7 +268,7 @@ function lintPage({ path, rel }, slugMap, tagVocab, pageDirs) {
   }
 
   if (!content.match(/^---\r?\n/)) {
-    issue('warn', rel, 'No frontmatter found');
+    issue('warn', rel, 'No frontmatter found', null, 'W1');
     return;
   }
 
@@ -264,11 +283,11 @@ function lintPage({ path, rel }, slugMap, tagVocab, pageDirs) {
   }
 
   if (fm.type && !VALID_TYPES.includes(fm.type)) {
-    issue('warn', rel, `Unknown type: "${fm.type}"`);
+    issue('warn', rel, `Unknown type: "${fm.type}"`, null, 'W2');
   }
 
   if (!fm.updated) {
-    issue('warn', rel, 'Missing frontmatter field: updated', path);
+    issue('warn', rel, 'Missing frontmatter field: updated', path, 'W3');
   }
 
   // type-conditional required fields
@@ -296,8 +315,12 @@ function lintPage({ path, rel }, slugMap, tagVocab, pageDirs) {
   // feedback: scope vocabulary + conditional claude-learned fields (ADR 0031)
   if (fm.type === 'feedback') {
     const scope = fm.scope || '';
-    if (scope && scope !== 'global' && !/^project:[a-z0-9][a-z0-9-]*$/.test(scope)) {
-      issue('error', rel, `Invalid feedback scope: "${scope}" (allowed: global | project:<slug>)`);
+    if (scope && !FEEDBACK_SCOPE_RE.test(scope)) {
+      issue(
+        'error',
+        rel,
+        `Invalid feedback scope: "${scope}" (allowed: global | project:<project-id>)`,
+      );
     }
     const fbTargets = parseTagsField(fm.targets) || [];
     if (fbTargets.includes('claude-learned')) {
@@ -332,7 +355,7 @@ function lintPage({ path, rel }, slugMap, tagVocab, pageDirs) {
 
   for (const link of extractWikilinks(content)) {
     if (!slugMap.has(link)) {
-      issue('warn', rel, `Broken wikilink: [[${link}]]`);
+      issue('warn', rel, `Broken wikilink: [[${link}]]`, null, 'W4');
     }
   }
 }
@@ -404,12 +427,29 @@ if (args.fix) {
   }
 }
 
+// --strict: promote selected warnings (by stable ID) to errors *before* the
+// errors/warns split, so exit code, counts, plain-text icons, and --json `ok`
+// all derive from the post-promotion severities through the existing paths.
+if (args.strict) {
+  for (const iss of issues) {
+    if (iss.severity === 'warn' && iss.id && STRICT_PROMOTE_IDS.has(iss.id)) {
+      iss.severity = 'error';
+    }
+  }
+}
+
 const errors = issues.filter((i) => i.severity === 'error');
 const warns = issues.filter((i) => i.severity === 'warn');
 
 if (args.json) {
+  // Default mode is byte-identical: only W8 carries an `id` in the JSON payload
+  // (hooks/hypo-personal-check.mjs filters on it). All other IDs stay internal
+  // unless `--strict` is set, where the full ID set is exposed so promoted
+  // findings are traceable to their warning class.
   const toOut = ({ severity, file, message, id }) =>
-    id ? { severity, file, message, id } : { severity, file, message };
+    id && (id === 'W8' || args.strict)
+      ? { severity, file, message, id }
+      : { severity, file, message };
   console.log(
     JSON.stringify(
       {

package/scripts/pre-commit-format.mjs

@@ -0,0 +1,198 @@
+#!/usr/bin/env node
+/**
+ * scripts/pre-commit-format.mjs — Node-side entry for the pre-commit hook.
+ *
+ * Invoked by the shell shim installed at <git-dir>/hooks/pre-commit. The shim
+ * already verifies HYPOMNEMA_ROOT + HYPOMNEMA_GIT_DIR; this script is the
+ * second layer of identity defence and the only place that may exit nonzero
+ * (only when `git add` fails on restage).
+ *
+ * Env discipline:
+ *   - probes git twice with ambient env to learn what Git thinks the repo is
+ *   - builds `cleanEnv` by stripping every name from `git rev-parse --local-env-vars`
+ *     plus GIT_NAMESPACE / GIT_CEILING_DIRECTORIES / GIT_CONFIG_* (belt-and-suspenders)
+ *   - validates inherited GIT_INDEX_FILE: preserve if inside HYPOMNEMA_GIT_DIR
+ *     (Git exports this for commit -am / commit -- path / commit --amend);
+ *     otherwise refuse — that's a foreign-index attack vector
+ *   - lib spawns get `cleanEnv` only; lib never touches process.env directly
+ *
+ * Why dynamic import: keeping the lib import behind every guard makes the
+ * fail-open story water-tight. A static import at file head would throw at
+ * module load if the lib were missing or syntactically broken, before any
+ * identity check could exit 0.
+ *
+ * Why pathToFileURL for the import: absolute filesystem paths fed to
+ * `import()` break when the checkout path contains URL-significant characters
+ * (#, %). pathToFileURL is the canonical Node way to bridge.
+ */
+
+try {
+  const { execFileSync } = await import('node:child_process');
+  const fs = await import('node:fs');
+  const path = await import('node:path');
+  const { pathToFileURL, fileURLToPath } = await import('node:url');
+
+  const probe = (args, env) => execFileSync('git', args, { encoding: 'utf8', env }).trim();
+
+  // (0) Derive expectedRoot from THIS script's filesystem location. The shell
+  //     shim already verifies HYPOMNEMA_ROOT/HYPOMNEMA_GIT_DIR before exec'ing
+  //     us, but a direct `node scripts/pre-commit-format.mjs` invocation with
+  //     hostile GIT_DIR/GIT_WORK_TREE pointing at another repo that ALSO calls
+  //     itself "hypomnema" would bypass the package.json identity check unless
+  //     we anchor on the script's own location. import.meta.url cannot be
+  //     redirected by ambient env.
+  let expectedRoot;
+  try {
+    const here = path.dirname(fileURLToPath(import.meta.url));
+    expectedRoot = fs.realpathSync(path.resolve(here, '..'));
+  } catch {
+    process.exit(0);
+  }
+
+  // (1) Probe with ambient env to learn what Git thinks the repo is.
+  let toplevel, absGitDir, commonDir;
+  try {
+    toplevel = probe(['rev-parse', '--show-toplevel'], process.env);
+    absGitDir = probe(['rev-parse', '--absolute-git-dir'], process.env);
+    commonDir = probe(['rev-parse', '--git-common-dir'], process.env);
+  } catch {
+    process.exit(0);
+  }
+
+  // (2) Realpath-resolve for stable comparison.
+  let absGitDirR, commonDirR, toplevelR;
+  try {
+    absGitDirR = fs.realpathSync(absGitDir);
+    const cdAbs = path.isAbsolute(commonDir) ? commonDir : path.join(absGitDir, '..', commonDir);
+    commonDirR = fs.realpathSync(cdAbs);
+    toplevelR = fs.realpathSync(toplevel);
+  } catch {
+    process.exit(0);
+  }
+
+  // (3) Trust anchor — refuse to run against any toplevel other than this
+  //     script's own checkout. Closes the GIT_DIR/GIT_WORK_TREE attack where a
+  //     foreign hypomnema-named repo would otherwise pass the package.json check.
+  if (toplevelR !== expectedRoot) process.exit(0);
+
+  // (3a) Anchor the git dir to the expected location too. Without this, a
+  //      mixed-env attack — GIT_DIR=/foreign/.git + GIT_WORK_TREE=expectedRoot
+  //      + GIT_INDEX_FILE=/foreign/.git/index — would let `absGitDirR` point at
+  //      the foreign repo while `--show-toplevel` reports expectedRoot. The
+  //      subsequent GIT_INDEX_FILE check would then pass relative to the
+  //      foreign git dir, and the lib would operate on a foreign index while
+  //      mutating real files. (Live-verified by codex round 7.)
+  let expectedGitDirR;
+  try {
+    expectedGitDirR = fs.realpathSync(path.join(expectedRoot, '.git'));
+  } catch {
+    process.exit(0);
+  }
+  if (absGitDirR !== expectedGitDirR) process.exit(0);
+
+  // (4) Linked worktree → main-worktree only (documented limitation).
+  if (absGitDirR !== commonDirR) process.exit(0);
+
+  // (5) Repo identity check — package.json name must be "hypomnema" (defence in
+  //     depth alongside the expectedRoot anchor above).
+  const pkgPath = path.join(toplevelR, 'package.json');
+  if (!fs.existsSync(pkgPath)) process.exit(0);
+  let pkg;
+  try {
+    pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf8'));
+  } catch {
+    process.exit(0);
+  }
+  if (pkg?.name !== 'hypomnema') process.exit(0);
+
+  // (5) Build trusted env from --local-env-vars + GIT_CONFIG_* belt.
+  let localEnvList;
+  try {
+    localEnvList = probe(['rev-parse', '--local-env-vars'], process.env)
+      .split(/\r?\n/)
+      .filter(Boolean);
+  } catch {
+    // Static fallback (Git versions where --local-env-vars is unavailable).
+    localEnvList = [
+      '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',
+    ];
+  }
+  const scrub = new Set([
+    ...localEnvList,
+    'GIT_NAMESPACE',
+    'GIT_CEILING_DIRECTORIES',
+    ...Object.keys(process.env).filter((k) => /^GIT_CONFIG_/.test(k)),
+  ]);
+  const cleanEnv = Object.fromEntries(Object.entries(process.env).filter(([k]) => !scrub.has(k)));
+
+  // (6) GIT_INDEX_FILE preservation gated on shim invocation. Git legitimately
+  //     exports this for these commit shapes (verified live by codex round 5/9
+  //     on Git 2.50.1):
+  //       - .git/index             normal commit, commit --amend, merge commit
+  //       - .git/index.lock        commit -am, commit -p, commit --interactive
+  //       - .git/next-index-*.lock commit -- <pathspec>, rebase partial commit
+  //     The basename whitelist used in v8/v9 had a residual gap: a crafted
+  //     .git/next-index-attack.lock matches the `next-index-*` prefix even
+  //     though Git itself uses `next-index-<pid>.lock` (codex round 9 live
+  //     replay). Closing that prefix gap by tightening pattern just invites
+  //     more attacker iteration.
+  //
+  //     The cleaner defence: only honour inherited GIT_INDEX_FILE when we
+  //     were invoked from our own trusted shell shim (HYPOMNEMA_HOOK_INVOCATION
+  //     sentinel set there). Direct invocation — which is the only path an
+  //     attacker can use to plant a crafted index — drops the inherited value
+  //     and lets git fall back to the default `.git/index`, i.e. the real
+  //     staged set. The hook then either has nothing to do (no real stage) or
+  //     formats the real stage (correct behaviour). An attacker that can also
+  //     set HYPOMNEMA_HOOK_INVOCATION already has full env control and can
+  //     mutate files directly without going through the hook gadget.
+  const fromShim = process.env.HYPOMNEMA_HOOK_INVOCATION === '1';
+  if (fromShim && process.env.GIT_INDEX_FILE) {
+    // Even when trusted, sanity-check that the path lives inside our git dir.
+    // Belt-and-suspenders against shim invocation with an inherited but
+    // misdirected GIT_INDEX_FILE (e.g. by a wrapper that exec'd our shim).
+    const inherited = process.env.GIT_INDEX_FILE;
+    const lexical = path.isAbsolute(inherited) ? inherited : path.join(toplevelR, inherited);
+    let absIdx;
+    try {
+      absIdx = fs.realpathSync(lexical);
+    } catch {
+      absIdx = path.resolve(lexical);
+    }
+    if (path.dirname(absIdx) === absGitDirR) {
+      cleanEnv.GIT_INDEX_FILE = inherited;
+    }
+  }
+  // If !fromShim, GIT_INDEX_FILE stays scrubbed → lib uses default .git/index.
+
+  // (7) Dynamic-import the lib through a file:// URL so checkout paths with
+  //     URL-significant chars (#, %) don't break ESM resolution. We import
+  //     from expectedRoot, not toplevel — the script's own location is the
+  //     anchor of trust.
+  const libPath = path.join(expectedRoot, 'scripts/lib/pre-commit-format.mjs');
+  let lib;
+  try {
+    lib = await import(pathToFileURL(libPath).href);
+  } catch {
+    process.exit(0);
+  }
+
+  const result = await lib.runPreCommitFormat({ cwd: toplevelR, env: cleanEnv });
+  if (result.summary) process.stderr.write(`[pre-commit-format] ${result.summary}\n`);
+  process.exit(result.gitAddFailed ? 1 : 0);
+} catch {
+  process.exit(0);
+}

package/scripts/smoke-pack.mjs

@@ -56,6 +56,13 @@ const wikiDir = join(work, 'wiki');
 let cleanupOk = false;
 
 try {
+  // Capture pre-commit hook contents (if any) BEFORE pack so we can prove
+  // `npm pack` didn't mutate it. The `prepare` lifecycle script runs during
+  // `npm pack` and could theoretically touch .git/hooks/pre-commit; the
+  // installer's CI/lifecycle guards must prevent that.
+  const preCommitPath = join(REPO, '.git', 'hooks', 'pre-commit');
+  const preCommitBefore = existsSync(preCommitPath) ? readFileSync(preCommitPath, 'utf-8') : null;
+
   step('npm pack');
   const pack = run('npm', ['pack', '--json'], { cwd: REPO });
   const meta = JSON.parse(pack.stdout)[0];
@@ -203,6 +210,15 @@ try {
     );
   }
 
+  step('verify pre-commit hook was not mutated by npm pack');
+  const preCommitAfter = existsSync(preCommitPath) ? readFileSync(preCommitPath, 'utf-8') : null;
+  if (preCommitBefore !== preCommitAfter) {
+    throw new Error(
+      'npm pack mutated .git/hooks/pre-commit — the prepare lifecycle ' +
+        'guard (npm_command=pack) is not firing.',
+    );
+  }
+
   console.log('\n✓ smoke-pack passed');
   cleanupOk = true;
 } catch (err) {

package/scripts/upgrade.mjs

@@ -19,6 +19,8 @@
  *                       wiki-*.mjs → hypo-*.mjs rename migration (fix #48), and
  *                       the user-extensions companion sync (E4 / fix #32).
  *   --json              Output results as JSON
+ *   --allow-downgrade   Override the guard that refuses to overwrite a NEWER
+ *                       active install with an older package (ADR 0038)
  */
 
 import {
@@ -45,6 +47,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));
@@ -76,6 +79,7 @@ function parseArgs(argv) {
     forceCommands: false,
     forceExtensions: false,
     codex: false,
+    allowDowngrade: false,
   };
   for (const arg of argv.slice(2)) {
     if (arg.startsWith('--hypo-dir=')) args.hypoDir = expandHome(arg.slice(11));
@@ -84,6 +88,7 @@ function parseArgs(argv) {
     else if (arg === '--force-extensions') args.forceExtensions = true;
     else if (arg === '--codex') args.codex = true;
     else if (arg === '--json') args.json = true;
+    else if (arg === '--allow-downgrade') args.allowDowngrade = true;
   }
   if (!args.hypoDir) args.hypoDir = resolveHypoRoot();
   return args;
@@ -312,7 +317,7 @@ function applySettingsJson(settingsResults, settingsPath) {
   for (const s of settingsResults) {
     if (s.status !== 'missing') continue;
     if (!Array.isArray(settings.hooks[s.event])) settings.hooks[s.event] = [];
-    // fix #48 BLOCKER: re-check the current parsed settings before appending.
+    // re-check the current parsed settings before appending.
     // applyHookNameMigration may have rewritten a legacy wiki-*.mjs command to
     // exactly `s.cmd` between checkSettingsJson and now — appending without
     // this guard creates a duplicate registration (codex 2-worker review
@@ -521,15 +526,16 @@ checklist below is manual:
 - [ ] **Re-run \`hypomnema lint\` after backfilling — confirm 0 feedback errors
       remain (including the conditional \`claude-learned\` fields above)**
 
-## Caveat — \`scope: project:<project-id>\` and slug regex
+## Note — \`scope: project:<project-id>\` and the scope regex
 
-The lint regex \`^project:[a-z0-9][a-z0-9-]*$\` accepts only short slugs, but
-\`feedback-sync\`'s default resolved project-id is cwd-derived (e.g.
-\`-Users-you-Workspace-Project\`), which the regex rejects. To use a
-\`scope: project:*\` page in v1.2.0 you must override with
-\`--project-id=<slug>\` so the resolved id is slug-safe. The full resolved-id
-↔ wiki-slug reconciliation is deferred to v1.3.0; \`commands/feedback.md\`
-documents the interim pattern.
+As of v1.3.0 the feedback scope regex \`^(global|project:[A-Za-z0-9_-]+)\$\`
+accepts cwd-derived project-ids directly (e.g.
+\`-Users-you-Workspace-Project\`), so a \`scope: project:*\` page no longer needs
+a \`--project-id=<slug>\` override just to pass \`lint\`. The resolved id must
+still exact-match \`feedback-sync\`'s project-id for projection (default: cwd
+with \`/\` and \`.\` replaced by \`-\`). Known limit: a cwd containing spaces or
+other characters outside \`[A-Za-z0-9_-]\` still derives an id the regex
+rejects — pass \`--project-id=<id>\` for those.
 `
     : `## What changed
 
@@ -762,7 +768,7 @@ const commands = checkCommands();
 const oldHookRefs = checkOldHookNames(claudeSettingsPath);
 const hypoignore = checkHypoignore(args.hypoDir);
 
-// fix #48: when --codex is set, mirror the same core-hook checks against ~/.codex/
+// when --codex is set, mirror the same core-hook checks against ~/.codex/
 // so `hypomnema upgrade --codex` reports drift symmetrically and `--apply --codex`
 // updates both targets in one pass (matching init.mjs behaviour).
 const hooksCodex = args.codex ? checkHookFiles(codexHooksDir) : null;
@@ -784,7 +790,7 @@ const extCheck = syncExtensions({
   force: args.forceExtensions,
 });
 
-// E4 (#32): --codex mirrors the extensions sync into ~/.codex (hooks + commands
+// E4 (fix #32): --codex mirrors the extensions sync into ~/.codex (hooks + commands
 // only; skills/agents skipped with a notice). The per-target SHA map lives in the
 // same ~/.claude/hypo-pkg.json under extensions.codex, so pkgPath is unchanged.
 const extCodexSettingsPath = codexSettingsPath;
@@ -839,6 +845,32 @@ let appliedExtensions = null;
 let appliedExtensionsCodex = null;
 
 if (args.apply) {
+  // Downgrade guard (ADR 0038, P): an `--apply` from an OLDER package than the
+  // active install would overwrite newer hooks (upgrade.mjs:287 copyFileSync) and
+  // rewrite hypo-pkg.json to the older version. Refuse before the first mutation.
+  // A dev workspace re-running its own --apply (incl. the post-commit sync hook)
+  // is exempt via realpath'd pkgRoot equality. Exit 2 = refused downgrade.
+  if (!args.allowDowngrade) {
+    const _active = readPkgJsonSafe(pkgJsonPath());
+    let _incomingVersion = null;
+    try {
+      _incomingVersion = JSON.parse(readFileSync(join(PKG_ROOT, 'package.json'), 'utf-8')).version;
+    } catch {
+      /* unreadable own package.json — cannot prove a downgrade, allow */
+    }
+    if (
+      _active &&
+      _active.pkgVersion &&
+      _incomingVersion &&
+      classifyInstall(
+        { pkgRoot: PKG_ROOT, version: _incomingVersion },
+        { pkgRoot: _active.pkgRoot, version: _active.pkgVersion },
+      ) === 'downgrade'
+    ) {
+      console.error(downgradeGuardMessage(_incomingVersion, _active.pkgVersion, 'upgrade --apply'));
+      process.exit(2);
+    }
+  }
   if (oldHookRefs.length > 0) {
     appliedHookNameRenames = applyHookNameMigration(
       oldHookRefs,
@@ -855,7 +887,7 @@ if (args.apply) {
   appliedCommands = applyCommands(commands, args.forceCommands);
   appliedPkgJson = true;
   appliedHypoignore = applyHypoignoreMigration(hypoignore);
-  // fix #48: codex core hooks + settings + wiki-*→hypo-* rename mirror. Same order
+  // codex core hooks + settings + wiki-*→hypo-* rename mirror. Same order
   // as the claude side (rename first so subsequent hook copy can find renamed targets).
   if (args.codex) {
     if (oldHookRefsCodex.length > 0) {
@@ -878,7 +910,7 @@ if (args.apply) {
     apply: true,
     force: args.forceExtensions,
   });
-  // E4 (#32): codex apply runs AFTER the claude apply so it reads the freshly
+  // E4 (fix #32): codex apply runs AFTER the claude apply so it reads the freshly
   // written hypo-pkg.json and merges extensions.codex alongside extensions.claude
   // (the per-target spread in syncExtensions preserves the other target's map).
   if (args.codex) {
@@ -898,7 +930,7 @@ if (args.apply) {
 
 const extDrift = extCheck.needsWork || (extCheckCodex?.needsWork ?? false);
 
-// fix #48: codex drift only counts when --codex is set — without the flag the codex
+// codex drift only counts when --codex is set — without the flag the codex
 // target is intentionally unobserved (parity with the existing extensions pattern).
 const codexCoreDrift =
   args.codex &&
@@ -935,7 +967,7 @@ if (args.json) {
         hypoignore,
         extensions: extCheck,
         extensionsCodex: extCheckCodex,
-        // fix #48: codex core mirror (null when --codex absent).
+        // codex core mirror (null when --codex absent).
         hooksCodex,
         settingsCodex,
         oldHookRefsCodex,
@@ -1090,7 +1122,7 @@ if (commands.length === 0) {
 }
 
 // Old hook names (wiki-*.mjs → hypo-*.mjs rename migration). Target-aware so
-// fix #48 surfaces codex settings.json that still references the v1.0/v1.1 names.
+// codex settings.json entries that still reference the v1.0/v1.1 names are surfaced.
 function pushHookNameSummary(refs, label) {
   if (refs.length > 0) {
     lines.push(
@@ -1142,7 +1174,7 @@ function pushExtSummary(check, label) {
     for (const c of check.conflicts) lines.push(`    ✗ ${c.file}  [${c.action} — left untouched]`);
     for (const d of check.drifts) lines.push(`    ⚠ ${d.file}  [drift — left untouched]`);
   }
-  // E3 (#31): a hard conflict blocks install (exit 1, even under --apply); drift is
+  // E3 (fix #31): a hard conflict blocks install (exit 1, even under --apply); drift is
   // resolvable advisory. Emit the spec'd WIKI messages so the user knows the recovery.
   if (nConflicts > 0) {
     lines.push('  [WIKI: existing file conflicts. Backup and retry, or use --force-extensions]');
@@ -1200,7 +1232,7 @@ if (
     lines.push(`✓ Appended .hypoignore entries (${appliedHypoignore.length}):`);
     for (const e of appliedHypoignore) lines.push(`    → ${e}`);
   }
-  // fix #48: codex-target applied actions (mirrors claude blocks above).
+  // codex-target applied actions (mirrors claude blocks above).
   if (appliedHookNameRenamesCodex.length > 0) {
     lines.push(`✓ Renamed legacy hook references (codex) (${appliedHookNameRenamesCodex.length}):`);
     for (const r of appliedHookNameRenamesCodex) lines.push(`    → ${r}`);
@@ -1252,11 +1284,11 @@ const totalDrift =
   extCheck.actions.filter(
     (a) => a.action === 'create' || a.action === 'update' || a.action === 'force-update',
   ).length +
-  // E3 (#31): unresolved drift/conflict is pending work too — without these the
-  // summary printed "up to date" while the exit code was 1 (codex review).
+  // E3 (fix #31): unresolved drift/conflict is pending work too — without these the
+  // summary printed "up to date" while the exit code was 1.
   extCheck.conflicts.length +
   extCheck.drifts.length +
-  // E4 (#32): codex-target pending work counts identically (same message/exit
+  // E4 (fix #32): codex-target pending work counts identically (same message/exit
   // consistency the E3 review caught — a codex conflict must not read "up to date").
   (extCheckCodex
     ? extCheckCodex.actions.filter(
@@ -1265,7 +1297,7 @@ const totalDrift =
       extCheckCodex.conflicts.length +
       extCheckCodex.drifts.length
     : 0) +
-  // fix #48: codex core mirror counts the same way as the claude side.
+  // codex core mirror counts the same way as the claude side.
   staleHooksCodex.length +
   missingSettingsCodex.length +
   (invalidSettingsCodex ? 1 : 0) +
@@ -1297,7 +1329,7 @@ if (totalDrift === 0) {
 
 console.log(lines.join('\n'));
 
-// E3 (#31): a hard extension conflict blocks even under --apply (unlike ordinary
+// E3 (fix #31): a hard extension conflict blocks even under --apply (unlike ordinary
 // drift, which only fails check mode). --force-extensions clears the resolvable
 // cases; an unfollowable symlink/non-regular dest still counts and stays exit 1.
 const extBlocked = extCheck.conflicts.length > 0 || (extCheckCodex?.conflicts.length ?? 0) > 0;

package/skills/crystallize/SKILL.md

@@ -11,7 +11,7 @@ When invoked at the end of a session (or with phrases like "세션 종료", "wra
 
 ## What this does
 
-- **Close mode**: walks the 6-step checklist (session-state, project hot.md, root hot.md, session-log, open-questions(변경 시), log.md) and verifies via `crystallize.mjs --check-session-close` — same gate the PreCompact hook runs.
+- **Close mode**: walks the checklist (session-state, project hot.md, root hot.md, session-log, open-questions(변경 시), log.md) plus a lint step, then writes via `crystallize.mjs --apply-session-close --payload=<path>` — which runs the lint gate automatically, **scoped to the files it writes** (debt elsewhere is a non-blocking notice). `--check-session-close` remains a read-only probe (freshness only). The PreCompact gate runs the same scoped lint, judging the session on the files it touched.
 - **Synthesis mode**: finds tag clusters (≥ N pages), orphan pages (no outbound `[[wikilinks]]`), and draft / stub pages, then guides consolidation into `pages/syntheses/<topic>.md` with back-links and `index.md` updates.
 
 ---
@@ -43,7 +43,18 @@ Show the output verbatim.
 
 ## Step 3 — Session-close checklist (if triggered at session end)
 
-If `/hypo:crystallize` was invoked as a session-close action, run through this checklist before synthesizing. Proceed automatically without confirmation unless the user has not said "auto".
+If `/hypo:crystallize` was invoked as a session-close action, run through this checklist before synthesizing. The mechanical checklist items (1–6 below) proceed automatically without confirmation unless the user has not said "auto"; the advisory reflections that precede them (#41~#44) always surface to the user for confirmation — they are recommendations, never auto-actions.
+
+### Advisory reflections (run before the checklist below — advisory only)
+
+Surface each of these four to the user first. Every one is **advisory** (ADR 0029 identity guard): the user confirms or declines, and none performs an automatic action, writes a file on its own, or bypasses the mandatory gate.
+
+- **Trivial-session check (#44)** — Was this session trivial (a single bug fix, a single-file edit, or Q&A with no durable artifact)? If so, recommend skipping session-close: *"이 세션은 trivial해 보입니다 — session-close를 건너뛸까요?"* A trivial skip is a recommendation, **not** a bypass: it must not mark the session closed, must not run `--mark-session-closed`, and must not claim `/compact` can pass. Any real close still requires all 5 mandatory files.
+- **ADR-candidate check (#41)** — Did this session make an architectural or design decision (a new pattern, a tradeoff, a convention)? If yes, ask whether it warrants an ADR and capture that intent in the session-log entry. If nothing rose to ADR level, record `ADR 없음 — <one-line reason>` in that same session-log entry. **Never auto-write an ADR file** — the session-log note is the only action here.
+- **design-history staleness check (#42)** — If `projects/<name>/design-history.md` exists and this session changed design decisions it does not yet reflect, recommend updating it (W8 lint flags this mechanically; an active-project W8 can also block at PreCompact). If the file does not exist, skip silently — do **not** create it just for this check. Never auto-update it.
+- **Ingest check (#43)** — Did this session consume trustworthy external knowledge (a fetched URL, official docs, or code you verified directly)? If so, recommend running `/hypo:ingest` to capture it under `sources/`. Proceed only on the user's confirmation.
+
+When uncertain, surface the question rather than skip it. None of the four blocks the close or writes on its own.
 
 1. **session-state.md** — update `projects/<name>/session-state.md` with the next tasks list (what to tackle first next time).
 2. **hot.md (project)** — update `projects/<name>/hot.md` with a session snapshot: what changed and decisions made. Keep under 500 words. Do not put next-step tasks here; those belong in session-state.md.

package/templates/hypo-config.md

@@ -1,7 +1,7 @@
 ---
 title: Hypomnema Config
 type: config
-version: "1.2.1"
+version: "1.3.0"
 created: YYYY-MM-DD
 ---
 

package/templates/hypo-guide.md

@@ -80,6 +80,10 @@ Ask: *"이 작업이 마무리되었나요? 세션을 정리(crystallize)할까
 2. Update `projects/<name>/hot.md` (what was done, ≤500 words, overwrite)
 3. Append to `projects/<name>/session-log/YYYY-MM.md` (narrative entry, append-only)
 4. Update root `hot.md` pointer table + date
+5. Run `scripts/lint.mjs` and fix errors in files **you** touched — debt in other
+   projects / shared pages you did not author is reported as a non-blocking
+   notice, not a gate. (The documented `crystallize.mjs --apply-session-close`
+   path runs this lint automatically, scoped to the files it writes.)
 
 Skip session close for: single bug fix, single-file edit, Q&A only.