hypomnema 1.2.1 → 1.3.1

package/scripts/lib/pre-commit-format.mjs

@@ -0,0 +1,251 @@
+/**
+ * lib/pre-commit-format.mjs — pure logic for the auto-format-on-commit hook.
+ *
+ * Rule source: CLAUDE.md <formatting> directive. Pre-commit hook auto-runs the
+ * project formatter on STAGED files only. Formatter failure is non-blocking;
+ * only `git add` failure on restage is a true commit block.
+ *
+ * Why pure: lets tests construct synthetic staged sets without touching real
+ * git or invoking prettier. The CLI shim in scripts/pre-commit-format.mjs
+ * handles env resolution / repo-identity guards / process exit codes.
+ *
+ * Env discipline: every `git` spawn here MUST receive a caller-supplied `env`.
+ * The lib never reads `process.env` for git operations — that defence is what
+ * blocks GIT_DIR / GIT_WORK_TREE override attacks (see CONTRIBUTING.md).
+ */
+
+import { spawnSync } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+
+const STATUS_FILTER = 'ACMR';
+
+/**
+ * Parse the NUL-token stream emitted by `git diff --cached --name-status -z`.
+ *
+ * Token shape (verified live against git 2.50): records are NUL-separated.
+ *   A\0path\0          (added)
+ *   M\0path\0          (modified)
+ *   D\0path\0          (deleted — filtered out by --diff-filter)
+ *   T\0path\0          (type change — filtered out)
+ *   R<score>\0old\0new\0   (rename)
+ *   C<score>\0old\0new\0   (copy)
+ *
+ * Paths containing TAB are valid — TAB is not a separator here (it appears in
+ * the non-`-z` output, never in `-z`). Only NUL separates records.
+ *
+ * @param {string} buf  Raw stdout from `git diff --cached --name-status -z`.
+ * @returns {Array<{path: string, status: string}>}
+ */
+export function parseNameStatus(buf) {
+  const tokens = buf.split('\0');
+  // Trailing NUL leaves an empty token; drop it (and any stray empties).
+  while (tokens.length && tokens[tokens.length - 1] === '') tokens.pop();
+  const out = [];
+  for (let i = 0; i < tokens.length; ) {
+    const status = tokens[i++];
+    if (!status) continue;
+    const head = status[0];
+    if (head === 'R' || head === 'C') {
+      // Two-path record. Old is irrelevant for formatting — only the new path
+      // exists in the staged tree.
+      i++; // consume old
+      const next = tokens[i++];
+      if (next) out.push({ path: next, status: head });
+    } else if (head === 'A' || head === 'M') {
+      const p = tokens[i++];
+      if (p) out.push({ path: p, status: head });
+    } else {
+      // D, T, U, X — consume one path, drop. --diff-filter should exclude
+      // these but we defensively skip.
+      i++;
+    }
+  }
+  return out;
+}
+
+/**
+ * Parse `git ls-files --stage -z` output to map paths → file mode strings.
+ * Output shape: `<mode> <hash> <stage>\t<path>\0`
+ */
+export function parseLsFilesStage(buf) {
+  const map = new Map();
+  const records = buf.split('\0');
+  for (const rec of records) {
+    if (!rec) continue;
+    const tabIdx = rec.indexOf('\t');
+    if (tabIdx < 0) continue;
+    const meta = rec.slice(0, tabIdx);
+    const path = rec.slice(tabIdx + 1);
+    const mode = meta.split(' ')[0];
+    map.set(path, mode);
+  }
+  return map;
+}
+
+/**
+ * Drop symlinks (120000) and gitlinks/submodules (160000). Regular file modes
+ * (100644, 100755) are kept.
+ */
+export function filterRegularFiles(entries, modeMap) {
+  return entries.filter((e) => {
+    const m = modeMap.get(e.path);
+    if (!m) return false; // not in index — defensively skip
+    return m !== '120000' && m !== '160000';
+  });
+}
+
+/**
+ * Partition staged paths into safe vs partial (also has unstaged hunks).
+ * Partial files are skipped to avoid swallowing unstaged work.
+ */
+export function partitionStagedFiles(entries, unstagedDirty) {
+  const safe = [];
+  const partial = [];
+  for (const e of entries) {
+    if (unstagedDirty.has(e.path)) partial.push(e);
+    else safe.push(e);
+  }
+  return { safe, partial };
+}
+
+/**
+ * Formatter dispatch table. Other entries (eslint, black, gofmt, cargo fmt)
+ * are placeholders — the table is data, not a branch tree. Activate by
+ * filling in an entry similar to `prettier`.
+ *
+ * Critically: NEVER use `npx` here. `npx prettier` may try a network install
+ * on a cold machine; we want a local-only binary or no-op.
+ */
+export function selectFormatter(repoRoot) {
+  const prettierBin = join(repoRoot, 'node_modules', '.bin', 'prettier');
+  if (existsSync(prettierBin)) {
+    return {
+      name: 'prettier',
+      bin: prettierBin,
+      buildArgs: (files) => ['--write', '--', ...files],
+    };
+  }
+  return null;
+}
+
+/**
+ * Run the formatter once with all safe files. Captures exit status; never
+ * throws.
+ */
+export function formatFiles(safe, formatter, { env, cwd } = {}) {
+  if (!safe.length || !formatter) {
+    return { ran: false, formatterFailed: false, reason: 'noop' };
+  }
+  const paths = safe.map((e) => e.path);
+  const res = spawnSync(formatter.bin, formatter.buildArgs(paths), {
+    cwd,
+    env,
+    encoding: 'utf-8',
+    stdio: ['ignore', 'pipe', 'pipe'],
+  });
+  return {
+    ran: true,
+    formatterFailed: res.status !== 0,
+    exitCode: res.status,
+    stdout: res.stdout || '',
+    stderr: res.stderr || '',
+  };
+}
+
+/**
+ * Re-stage the formatted files. Returns `{gitAddFailed: bool, stderr}`.
+ * Prettier `--write` only writes on actual content change, so re-adding
+ * unchanged files is a cheap no-op. Doing it unconditionally avoids a
+ * before/after hash comparison.
+ */
+export function restageFormatted(files, { env, cwd } = {}) {
+  if (!files.length) return { gitAddFailed: false };
+  const res = spawnSync('git', ['add', '--', ...files], {
+    cwd,
+    env,
+    encoding: 'utf-8',
+    stdio: ['ignore', 'pipe', 'pipe'],
+  });
+  return {
+    gitAddFailed: res.status !== 0,
+    stderr: res.stderr || '',
+  };
+}
+
+/**
+ * Top-level orchestrator used by the CLI shim. The caller supplies `cwd`
+ * (the Hypomnema toplevel) and a sanitized `env` (no inherited `GIT_*`
+ * except optionally a validated `GIT_INDEX_FILE`).
+ *
+ * @returns {{gitAddFailed: boolean, summary: string}}
+ */
+export async function runPreCommitFormat({ cwd, env }) {
+  const summary = [];
+  const stagedRes = spawnSync(
+    'git',
+    ['diff', '--cached', '--name-status', '-z', `--diff-filter=${STATUS_FILTER}`, '--'],
+    { cwd, env, encoding: 'utf-8' },
+  );
+  if (stagedRes.status !== 0) {
+    return { gitAddFailed: false, summary: 'git diff --cached failed; skipping' };
+  }
+  const staged = parseNameStatus(stagedRes.stdout || '');
+  if (!staged.length) return { gitAddFailed: false, summary: 'no staged files' };
+
+  // Filter out symlinks / submodules.
+  const lsRes = spawnSync(
+    'git',
+    ['ls-files', '--stage', '-z', '--', ...staged.map((e) => e.path)],
+    { cwd, env, encoding: 'utf-8' },
+  );
+  let regular = staged;
+  if (lsRes.status === 0) {
+    const modeMap = parseLsFilesStage(lsRes.stdout || '');
+    regular = filterRegularFiles(staged, modeMap);
+  }
+  if (!regular.length) return { gitAddFailed: false, summary: 'no regular staged files' };
+
+  // Unstaged-dirty set for partition.
+  const unstRes = spawnSync('git', ['diff', '--name-only', '-z', '--'], {
+    cwd,
+    env,
+    encoding: 'utf-8',
+  });
+  const unstaged = new Set();
+  if (unstRes.status === 0) {
+    for (const p of (unstRes.stdout || '').split('\0')) {
+      if (p) unstaged.add(p);
+    }
+  }
+  const { safe, partial } = partitionStagedFiles(regular, unstaged);
+  if (partial.length) {
+    summary.push(`skipped ${partial.length} partially-staged file(s)`);
+  }
+  if (!safe.length) return { gitAddFailed: false, summary: summary.join('; ') || 'no safe files' };
+
+  const formatter = selectFormatter(cwd);
+  if (!formatter) {
+    return {
+      gitAddFailed: false,
+      summary: [...summary, 'no formatter (node_modules/.bin/prettier missing)'].join('; '),
+    };
+  }
+  const fmt = formatFiles(safe, formatter, { env, cwd });
+  if (fmt.formatterFailed) {
+    summary.push(`${formatter.name} exit ${fmt.exitCode} (non-blocking)`);
+    return { gitAddFailed: false, summary: summary.join('; ') };
+  }
+  const restage = restageFormatted(
+    safe.map((e) => e.path),
+    { env, cwd },
+  );
+  if (restage.gitAddFailed) {
+    return {
+      gitAddFailed: true,
+      summary: `git add failed: ${restage.stderr.trim()}`,
+    };
+  }
+  summary.push(`formatted ${safe.length} file(s) via ${formatter.name}`);
+  return { gitAddFailed: false, summary: summary.join('; ') };
+}

package/scripts/lib/project-create.mjs

@@ -64,8 +64,8 @@ export function insertHotRow(content, name, today) {
   if (content.includes(link)) return content; // already present
   const lines = content.split('\n');
   // Scope the search to the "## Active Projects" section so a table appearing
-  // earlier in hot.md can't capture the row (codex review 2026-05-22). Start
-  // looking from the heading; stop at the next H2 so we never cross sections.
+  // earlier in hot.md can't capture the row. Start looking from the heading;
+  // stop at the next H2 so we never cross sections.
   const headingIdx = lines.findIndex((l) => /^##\s+Active Projects\s*$/.test(l));
   if (headingIdx === -1) return null;
   let sepIdx = -1;

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/resume.mjs

@@ -9,13 +9,22 @@
  *   node scripts/resume.mjs [options]
  *
  * Options:
- *   --hypo-dir=<path>     Hypomnema root (default: resolved via HYPO_DIR / hypo-config.md / ~/hypomnema)
+ *   --hypo-dir=<path>     Hypomnema root. When omitted, resolveHypoRoot()
+ *                         (see lib/hypo-root.mjs) resolves it in priority order:
+ *                           1. $HYPO_DIR if set — returned immediately; the
+ *                              hypo-config.md scan below is then skipped.
+ *                           2. else the first of 7 fixed candidates
+ *                              (~/{hypomnema,wiki,notes,knowledge},
+ *                              ~/Documents/{hypomnema,wiki,notes}) that contains
+ *                              a hypo-config.md marker.
+ *                           3. else the default ~/hypomnema.
  *   --project=<name>      Project name (default: most recently active from hot.md)
  *   --json                Output as JSON
  */
 
 import { existsSync, readFileSync, readdirSync, statSync } from 'fs';
 import { join } from 'path';
+import { homedir } from 'os';
 import { resolveHypoRoot, expandHome } from './lib/hypo-root.mjs';
 
 // ── arg parsing ──────────────────────────────────────────────────────────────
@@ -33,7 +42,43 @@ function parseArgs(argv) {
 
 // ── active project from hot.md ───────────────────────────────────────────────
 
-function resolveActiveProject(hypoDir) {
+// Parse a single frontmatter scalar (mirrors the hook helpers in
+// hypo-session-start.mjs / hypo-cwd-change.mjs — kept local per the hook
+// self-contained convention rather than shared, to avoid script↔hook coupling).
+function parseFrontmatterField(content, key) {
+  const m = content.match(/^---\r?\n([\s\S]*?)\r?\n---/);
+  if (!m) return null;
+  const line = m[1].split('\n').find((l) => l.startsWith(`${key}:`));
+  if (!line) return null;
+  return line
+    .slice(key.length + 1)
+    .trim()
+    .replace(/^['"]|['"]$/g, '');
+}
+
+// Among `slugs`, return the one whose projects/<slug>/index.md `working_dir`
+// is the LONGEST prefix of cwd (so /repo/sub wins over /repo). Returns null
+// when cwd is falsy or matches none. Used only as a same-date tie-breaker.
+function pickByCwd(hypoDir, slugs, cwd) {
+  if (!cwd) return null;
+  let best = null;
+  let bestLen = -1;
+  for (const slug of slugs) {
+    const indexPath = join(hypoDir, 'projects', slug, 'index.md');
+    if (!existsSync(indexPath)) continue;
+    const wd = parseFrontmatterField(readFileSync(indexPath, 'utf-8'), 'working_dir');
+    if (!wd) continue;
+    let resolved = wd.startsWith('~/') ? join(homedir(), wd.slice(2)) : wd;
+    resolved = resolved.replace(/\/+$/, ''); // trailing-slash normalize
+    if ((cwd === resolved || cwd.startsWith(resolved + '/')) && resolved.length > bestLen) {
+      bestLen = resolved.length;
+      best = slug;
+    }
+  }
+  return best;
+}
+
+function resolveActiveProject(hypoDir, cwd = null) {
   const hotPath = join(hypoDir, 'hot.md');
   if (!existsSync(hotPath)) return null;
 
@@ -49,6 +94,19 @@ function resolveActiveProject(hypoDir) {
   ].map((m) => ({ name: m[1].trim(), date: m[2] || '', slug: m[3] }));
   if (wikiRows.length > 0) {
     wikiRows.sort((a, b) => b.date.localeCompare(a.date));
+    // Same-date tie-break (ISSUE-1): when the top date is shared by >1 row,
+    // prefer the project whose working_dir contains cwd. No cwd / no match →
+    // keep the stable-sort winner (the legacy "first table row" behavior).
+    const topDate = wikiRows[0].date;
+    const tied = wikiRows.filter((r) => r.date === topDate);
+    if (cwd && tied.length > 1) {
+      const picked = pickByCwd(
+        hypoDir,
+        tied.map((r) => r.slug),
+        cwd,
+      );
+      if (picked) return picked;
+    }
     return wikiRows[0].slug;
   }
   // Legacy markdown-link rows: | [name](projects/name/...) | ...
@@ -93,7 +151,7 @@ function readHot(hypoDir, project) {
 
 const args = parseArgs(process.argv);
 
-const project = args.project || resolveActiveProject(args.hypoDir);
+const project = args.project || resolveActiveProject(args.hypoDir, process.cwd());
 
 if (!project) {
   console.error('Error: no active project found. Use --project=<name> or create a hot.md entry.');