hypomnema 1.2.1 → 1.3.0

package/scripts/lib/fix-status-verify.mjs

@@ -0,0 +1,438 @@
+/**
+ * fix-status-verify (lib) — pure functions for verifying fix→test linkage.
+ *
+ * Phase 1 of CLAUDE.md learned_behavior #6 (2026-05-16): "merged 표기 전
+ * (1) ADR 핵심 결정 라인 grep + (2) replay/integration test green 양쪽 충족".
+ * This module automates the *test green* half. ADR core decision grep is out
+ * of scope (Phase 2 / v1.3.0 manifest PR).
+ *
+ * SoT split (after codex 3-worker review 2026-05-27):
+ *  - fix→test mapping SoT: `// @fix #N: <full test name>` anchor comments in
+ *    tests/runner.mjs (sits next to the assertion that verifies the fix).
+ *  - fix status SoT: wiki spec-v1.2.md word-boundary grep
+ *    (\bfix\s*#N\b ... \b(TRUE_MERGED|merged|resolved)\b).
+ *
+ * Word-boundary on status terms is required so STALE_MERGED / partial /
+ * retired are NOT matched as positive claims.
+ */
+
+import { parseFrontmatter } from './frontmatter.mjs';
+
+const POSITIVE_STATUSES = new Set(['merged', 'TRUE_MERGED', 'resolved']);
+
+// Words that disqualify a line as a positive claim (case-sensitive).
+// STALE_MERGED contains "MERGED" as a substring but is the opposite signal.
+const NEGATIVE_STATUS_TOKENS = ['STALE_MERGED', 'partial', 'retired'];
+
+/**
+ * Parse anchor comments out of runner.mjs source text.
+ *
+ *   // @fix #15: all type-conditional fields present → green
+ *   // @fix #15: another test name
+ *
+ * The `@fix` prefix is mandatory — distinguishes anchors from prose comments
+ * that mention "fix #N" in passing. Each anchor line maps ONE fix # to ONE
+ * test name (whole captured group is the name, no comma-splitting). Multiple
+ * anchors for the same fix # accumulate (union, order-preserving, dedupe).
+ *
+ * Sentinel: NAME = "NO_AUTO_TEST" declares the fix has no automated test by
+ * design (behavioral / prompt-driven). Verified upstream in verifyMatrix.
+ */
+export function parseAnchors(runnerText) {
+  const out = new Map();
+  const re = /^\s*\/\/\s*@fix\s*#(\d+)\s*:\s*(.+?)\s*$/gim;
+  let m;
+  while ((m = re.exec(runnerText)) !== null) {
+    const fixNum = Number(m[1]);
+    const name = m[2].trim();
+    if (!name) continue;
+    if (!out.has(fixNum)) out.set(fixNum, []);
+    const list = out.get(fixNum);
+    if (!list.includes(name)) list.push(name);
+  }
+  return out;
+}
+
+/**
+ * Detect a redirect-stub spec: a page whose frontmatter declares
+ * `type: reference`. These are placeholders left behind after an archive move
+ * (e.g. spec-v1.2.md → archive/spec-v1.2.md) and carry zero fix-status claims.
+ * Pointing the verifier at one yields a vacuous green, so verifyMatrix rejects
+ * it up front.
+ */
+export function isReferenceStub(specText) {
+  const fm = parseFrontmatter(specText);
+  return fm?.type === 'reference';
+}
+
+/**
+ * Parse fix status claims out of wiki spec-v1.2.md.
+ *
+ * Returns Map<fixNum:number, status:string>. status is the most recent
+ * positive status token in the file (last mention wins so `merged → resolved`
+ * narrative normalises to `resolved`). Fixes whose only mentions are negative
+ * (STALE_MERGED / partial / retired) are NOT added — they're considered
+ * incomplete claims and skipped by verifyMatrix.
+ */
+export function parseStatus(specText) {
+  const out = new Map();
+  // For each line, find every fix # mention and check whether a positive
+  // status token sits within a small proximity window AFTER the mention. This
+  // avoids false positives when a line mentions multiple fix #s with status
+  // tokens that only apply to some of them (e.g. "fix #38 (resolved); fix #41
+  // (v1.3.0 advisory)" — only #38 should be picked up).
+  const lines = specText.split('\n');
+  const PROXIMITY = 120; // chars after fix # to scan for status
+  for (const line of lines) {
+    // Quick reject: line must mention a positive status token at all.
+    const hasPositive =
+      /\bTRUE_MERGED\b/.test(line) ||
+      /\bresolved\b/.test(line) ||
+      /(?<![A-Z_])merged(?![A-Z_])/.test(line);
+    if (!hasPositive) continue;
+    // Two accepted fix # forms:
+    //   (a) inline prose: "fix #N" (word-boundary)
+    //   (b) table cell start: "| #N |" (§9.1.0 status correction table)
+    const matches = [];
+    let m2;
+    const inlineRe = /\bfix\s*#(\d+)\b/gi;
+    while ((m2 = inlineRe.exec(line)) !== null) {
+      matches.push({ fixNum: Number(m2[1]), end: m2.index + m2[0].length });
+    }
+    const tableRe = /\|\s*#(\d+)\s*\|/g;
+    while ((m2 = tableRe.exec(line)) !== null) {
+      matches.push({ fixNum: Number(m2[1]), end: m2.index + m2[0].length });
+    }
+    for (const { fixNum, end } of matches) {
+      const window = line.slice(end, end + PROXIMITY);
+      // Determine the strongest status in the proximity window. Priority:
+      // TRUE_MERGED > resolved > merged.
+      let status = null;
+      if (/\bTRUE_MERGED\b/.test(window)) status = 'TRUE_MERGED';
+      else if (/\bresolved\b/.test(window)) status = 'resolved';
+      else if (/(?<![A-Z_])merged(?![A-Z_])/.test(window)) status = 'merged';
+      if (status) out.set(fixNum, status); // last positive mention wins
+    }
+  }
+  return out;
+}
+
+/**
+ * Parse runner.mjs stdout to map test names → "pass" | "fail".
+ *
+ * The harness prints `  ✓ <name>` on pass and `  ✗ <name>` on fail.
+ */
+export function parseRunnerOutput(stdout) {
+  const out = new Map();
+  const lines = stdout.split('\n');
+  for (const line of lines) {
+    const passM = line.match(/^\s*✓\s+(.+?)\s*$/);
+    if (passM) {
+      // Sticky pass — only set if no prior result. A later fail must NOT be
+      // overridden, and a prior fail must not be flipped back to pass.
+      if (!out.has(passM[1])) out.set(passM[1], 'pass');
+      continue;
+    }
+    const failM = line.match(/^\s*✗\s+(.+?)\s*$/);
+    if (failM) {
+      // Fail is sticky: once a name has any failure, the verdict stays fail
+      // even if a duplicate test() with the same name passed elsewhere.
+      out.set(failM[1], 'fail');
+    }
+  }
+  return out;
+}
+
+/**
+ * Cross-check anchors × status × test results.
+ *
+ * Finding classes:
+ *   NO_ANCHOR       — fix claimed positive in spec, no anchor in runner.
+ *   MISSING_TEST    — anchor names a test, runner output does not contain it.
+ *   FAILING_TEST    — anchor names a test, runner output marks it failed.
+ *   ORPHAN_ANCHOR   — anchor exists, no positive status claim in spec (warn).
+ *   STUB_SPEC       — spec is unusable: a `type: reference` redirect stub, or
+ *                     it parses zero positive status claims while anchors exist
+ *                     (the vacuous-gate the tool exists to prevent). Error.
+ *
+ * Returns { ok, findings: [...] }. ok=false if any ERROR-level finding.
+ * ORPHAN_ANCHOR is WARN-only.
+ *
+ * STUB_SPEC is a precondition failure, so it short-circuits: when the spec is
+ * unusable there is nothing meaningful to cross-check, and the per-anchor
+ * ORPHAN noise would only bury the one decisive error.
+ */
+export function verifyMatrix({ anchors, status, testResults, specIsStub = false }) {
+  if (specIsStub) {
+    return {
+      ok: false,
+      findings: [
+        {
+          level: 'error',
+          class: 'STUB_SPEC',
+          detail:
+            'spec is a `type: reference` redirect stub (0 fix-status claims by design) — pass --spec pointing at the real spec',
+        },
+      ],
+    };
+  }
+  // Vacuous-gate invariant: anchors exist in the runner but the spec yields no
+  // positive status claim to verify them against. Greening here would defeat
+  // the tool's purpose. (No anchors + no claims is an empty/custom matrix, not
+  // a vacuous gate, so it is left to the normal path.)
+  if (status.size === 0 && anchors.size > 0) {
+    return {
+      ok: false,
+      findings: [
+        {
+          level: 'error',
+          class: 'STUB_SPEC',
+          detail: `${anchors.size} anchor(s) in runner but 0 positive status claims parsed from spec — gate would be vacuous`,
+        },
+      ],
+    };
+  }
+
+  const findings = [];
+
+  for (const [fixNum, statusValue] of status.entries()) {
+    const anchored = anchors.get(fixNum);
+    if (!anchored || anchored.length === 0) {
+      findings.push({
+        level: 'error',
+        class: 'NO_ANCHOR',
+        fixNum,
+        status: statusValue,
+        detail: `claimed ${statusValue} in spec but no // fix #${fixNum}: anchor in runner.mjs`,
+      });
+      continue;
+    }
+    // Sentinel: explicit "no automated test by design" (behavioral /
+    // prompt-driven fixes). The fix is still claimed-merged but verifying it
+    // is out of scope for an integration runner.
+    if (anchored.length === 1 && anchored[0] === 'NO_AUTO_TEST') {
+      findings.push({
+        level: 'info',
+        class: 'NO_AUTO_TEST',
+        fixNum,
+        status: statusValue,
+        detail: `fix #${fixNum} declares NO_AUTO_TEST (behavioral / prompt-driven)`,
+      });
+      continue;
+    }
+    for (const testName of anchored) {
+      const result = testResults.get(testName);
+      if (result === undefined) {
+        findings.push({
+          level: 'error',
+          class: 'MISSING_TEST',
+          fixNum,
+          status: statusValue,
+          testName,
+          detail: `anchor names "${testName}" but no such test ran`,
+        });
+      } else if (result === 'fail') {
+        findings.push({
+          level: 'error',
+          class: 'FAILING_TEST',
+          fixNum,
+          status: statusValue,
+          testName,
+          detail: `test "${testName}" failed`,
+        });
+      }
+    }
+  }
+
+  for (const [fixNum, names] of anchors.entries()) {
+    if (!status.has(fixNum)) {
+      findings.push({
+        level: 'warn',
+        class: 'ORPHAN_ANCHOR',
+        fixNum,
+        tests: names,
+        detail: `anchor exists for fix #${fixNum} but no positive status claim in spec`,
+      });
+    }
+  }
+
+  const ok = !findings.some((f) => f.level === 'error');
+  return { ok, findings };
+}
+
+// ── Phase 2 (A-sot) — manifest validation, coverage/drift, ADR-line grep ─────
+// ADR 0036: manifest is the evidence SoT (fix → test + ADR-line). status SoT
+// stays in the spec. These are pure functions; the CLI injects fs-backed
+// searchFn / adrExistsFn so the corpus walk stays out of the pure layer.
+
+import { FIX_MANIFEST, NO_ADR, NO_AUTO_TEST } from './fix-manifest.mjs';
+
+/** Order-insensitive set equality over string arrays (deduped). */
+function sameStringSet(a, b) {
+  const sa = new Set(a);
+  const sb = new Set(b);
+  if (sa.size !== sb.size) return false;
+  for (const x of sa) if (!sb.has(x)) return false;
+  return true;
+}
+
+/**
+ * Structural validation of the manifest shape (ADR 0036).
+ *
+ * Findings (all error):
+ *   MANIFEST_DUP_FIXID       — two rows share a fixId.
+ *   MANIFEST_EMPTY_TESTS     — testNames is empty.
+ *   MANIFEST_SENTINEL_MIX    — NO_AUTO_TEST mixed with real test names.
+ *   MANIFEST_EMPTY_KEYLINE   — adrKeyLine missing/blank.
+ *   MANIFEST_NO_ADR_SHAPE    — NO_ADR row with non-null adrPath, or a non-NO_ADR
+ *                              row with null adrPath.
+ */
+export function validateManifest(manifest = FIX_MANIFEST) {
+  const findings = [];
+  const seen = new Set();
+  for (const row of manifest) {
+    const fixNum = row.fixId;
+    if (seen.has(fixNum)) {
+      findings.push({
+        level: 'error',
+        class: 'MANIFEST_DUP_FIXID',
+        fixNum,
+        detail: `duplicate manifest row for fix #${fixNum}`,
+      });
+    }
+    seen.add(fixNum);
+
+    const names = Array.isArray(row.testNames) ? row.testNames : [];
+    if (names.length === 0) {
+      findings.push({
+        level: 'error',
+        class: 'MANIFEST_EMPTY_TESTS',
+        fixNum,
+        detail: `fix #${fixNum} manifest row has empty testNames`,
+      });
+    }
+    if (names.includes(NO_AUTO_TEST) && names.length > 1) {
+      findings.push({
+        level: 'error',
+        class: 'MANIFEST_SENTINEL_MIX',
+        fixNum,
+        detail: `fix #${fixNum} mixes NO_AUTO_TEST sentinel with real test names`,
+      });
+    }
+
+    const keyLine = typeof row.adrKeyLine === 'string' ? row.adrKeyLine.trim() : '';
+    if (!keyLine) {
+      findings.push({
+        level: 'error',
+        class: 'MANIFEST_EMPTY_KEYLINE',
+        fixNum,
+        detail: `fix #${fixNum} manifest row has empty adrKeyLine`,
+      });
+      continue;
+    }
+    const isNoAdr = row.adrKeyLine === NO_ADR;
+    if (isNoAdr && row.adrPath != null) {
+      findings.push({
+        level: 'error',
+        class: 'MANIFEST_NO_ADR_SHAPE',
+        fixNum,
+        detail: `fix #${fixNum} is NO_ADR but adrPath is not null`,
+      });
+    }
+    if (!isNoAdr && row.adrPath == null) {
+      findings.push({
+        level: 'error',
+        class: 'MANIFEST_NO_ADR_SHAPE',
+        fixNum,
+        detail: `fix #${fixNum} has a real adrKeyLine but null adrPath`,
+      });
+    }
+  }
+  return findings;
+}
+
+/**
+ * Coverage + drift between manifest, runner anchors, and spec status claims.
+ *
+ *   MANIFEST_MISSING_ROW  — a fix claimed-merged AND anchored has no manifest
+ *                           row (its ADR-line check would be silently skipped).
+ *                           Error: a missing row bypasses the whole gate.
+ *   MANIFEST_TEST_DRIFT   — a manifest row's testNames do not set-equal the
+ *                           runner anchors for that fix (stale evidence).
+ *
+ * Both error-level. The claimed∩anchored requirement mirrors the manifest
+ * scope (ADR 0036): rows exist to prove claims; anchors-without-claims are
+ * ORPHAN_ANCHOR (handled in verifyMatrix), not manifest gaps.
+ */
+export function checkManifestCoverage({ manifest = FIX_MANIFEST, anchors, status }) {
+  const findings = [];
+  const byFix = new Map(manifest.map((r) => [r.fixId, r]));
+
+  for (const fixNum of status.keys()) {
+    if (!anchors.has(fixNum)) continue; // claimed but unanchored → NO_ANCHOR (verifyMatrix)
+    if (!byFix.has(fixNum)) {
+      findings.push({
+        level: 'error',
+        class: 'MANIFEST_MISSING_ROW',
+        fixNum,
+        detail: `fix #${fixNum} is claimed-merged and anchored but has no manifest row`,
+      });
+    }
+  }
+
+  for (const row of manifest) {
+    const fixNum = row.fixId;
+    const anchored = anchors.get(fixNum) || [];
+    const names = Array.isArray(row.testNames) ? row.testNames : [];
+    if (!sameStringSet(names, anchored)) {
+      findings.push({
+        level: 'error',
+        class: 'MANIFEST_TEST_DRIFT',
+        fixNum,
+        detail:
+          `fix #${fixNum} manifest testNames ${JSON.stringify(names)} ` +
+          `≠ runner anchors ${JSON.stringify(anchored)}`,
+      });
+    }
+  }
+  return findings;
+}
+
+/**
+ * ADR-line grep: each non-NO_ADR manifest row must point at an existing ADR
+ * file and its adrKeyLine must exist verbatim in the production-code corpus.
+ *
+ *   ADR_PATH_MISSING   — adrPath does not resolve to a file.
+ *   ADR_LINE_MISSING   — adrKeyLine not found in the corpus (fixed-string).
+ *
+ * searchFn(literal) → boolean: true iff the literal appears in the corpus
+ * (the corpus MUST exclude scripts/lib/fix-manifest.mjs, else every line
+ * self-matches and the gate is vacuous — see the CLI corpus builder).
+ * adrExistsFn(adrPath) → boolean. NO_ADR rows are skipped (test-green only).
+ */
+export function checkAdrLines({ manifest = FIX_MANIFEST, searchFn, adrExistsFn }) {
+  const findings = [];
+  for (const row of manifest) {
+    if (row.adrKeyLine === NO_ADR) continue;
+    const fixNum = row.fixId;
+    if (row.adrPath != null && !adrExistsFn(row.adrPath)) {
+      findings.push({
+        level: 'error',
+        class: 'ADR_PATH_MISSING',
+        fixNum,
+        detail: `fix #${fixNum} adrPath does not resolve: ${row.adrPath}`,
+      });
+    }
+    if (!searchFn(row.adrKeyLine)) {
+      findings.push({
+        level: 'error',
+        class: 'ADR_LINE_MISSING',
+        fixNum,
+        detail: `fix #${fixNum} adrKeyLine not found in production corpus: "${row.adrKeyLine}"`,
+      });
+    }
+  }
+  return findings;
+}
+
+export { POSITIVE_STATUSES, NEGATIVE_STATUS_TOKENS, FIX_MANIFEST, NO_ADR, NO_AUTO_TEST };

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;