hypomnema 1.2.1 → 1.3.0

package/hooks/hypo-shared.mjs

@@ -17,8 +17,8 @@ const HOME = homedir();
 // hypo-session-start / hypo-cwd-change WRITE this marker; hypo-first-prompt
 // READS + unlinks it. The session_id comes from the Claude Code runtime (a
 // UUID), but we sanitize defensively so a malformed id with path separators or
-// `..` can never escape tmpdir or collide on an empty value (codex review
-// 2026-05-21, fix #3/#13). Non-alphanumeric chars collapse to `_`.
+// `..` can never escape tmpdir or collide on an empty value. Non-alphanumeric
+// chars collapse to `_`.
 export function sessionMarkerPath(sessionId) {
   const safe = String(sessionId || 'default').replace(/[^A-Za-z0-9._-]/g, '_') || 'default';
   return join(tmpdir(), `hypo-session-marker-${safe}.json`);
@@ -207,8 +207,8 @@ export function hasSessionLogHeading(content, date) {
  * "foo-bar" (hyphen is non-word). The canonical log format always separates the
  * project slug from anything that follows by whitespace or end-of-line, so the
  * lookahead correctly rejects "session | foo-bar" when looking for "foo".
- * (Reported by codex review of fix #38 — was a pre-existing bug in
- * sessionCloseFileStatus that the helper extraction inherited.)
+ * (Was a pre-existing bug in sessionCloseFileStatus that the helper extraction
+ * inherited.)
  */
 export function hasLogEntry(content, date, project) {
   return new RegExp(
@@ -358,9 +358,9 @@ export function sessionCloseFileStatus(hypoDir) {
 
 // ── sync-state ────────────────────────────────────────────
 // `.cache/sync-state.json` is JSONL: one {timestamp, op, error, host} entry per
-// line. hypo-auto-commit (#9) appends on pull/push failure; hypo-session-start
-// (#10) surfaces open entries and clears them once sync is healthy again;
-// doctor (#11) warns while entries remain. Keep the schema defined here only.
+// line. hypo-auto-commit (fix #9) appends on pull/push failure; hypo-session-start
+// (fix #10) surfaces open entries and clears them once sync is healthy again;
+// doctor (fix #11) warns while entries remain. Keep the schema defined here only.
 
 /** @returns {string} path to the sync-state JSONL file for a wiki root. */
 function syncStatePath(hypoDir) {
@@ -527,14 +527,12 @@ export function shouldSuggestProjectCreation(cwd, hypoDir = HYPO_DIR, now = Date
  * Build the §8.11 auto-project offer line for a cwd. The display name is the
  * cwd basename, which is attacker-influenced (a directory name can contain
  * newlines/control chars on Unix). Strip control characters and length-cap it
- * so a crafted dir name cannot spoof extra instructions in additionalContext
- * (codex review 2026-05-22).
+ * so a crafted dir name cannot spoof extra instructions in additionalContext.
  */
 export function buildProjectSuggestionLine(cwd) {
   // Replace any control char (code < 0x20 or === 0x7F) with a space so a
-  // crafted dir name cannot inject newlines/instructions into additionalContext
-  // (codex review 2026-05-22). Done by codepoint to keep control bytes out of
-  // this source file.
+  // crafted dir name cannot inject newlines/instructions into additionalContext.
+  // Done by codepoint to keep control bytes out of this source file.
   const sanitized = Array.from(basename(cwd))
     .map((ch) => {
       const code = ch.codePointAt(0);
@@ -803,6 +801,133 @@ export function hasMutatingTranscriptActivity(transcriptPath) {
   return false;
 }
 
+// ── session-scoped lint classification ──────────────────────────────────────
+// Bug A/B fix: the close gate must judge a session on the files IT touched, not
+// the whole vault. Lint debt from another project/session (often in shared
+// pages/) must not block this session's close/compact. Two scope builders feed
+// one shared classifier: transcript-derived (hooks + standalone marker) and
+// close-file/payload-derived (the documented apply path writes via Bash, so its
+// files never appear as Edit/Write file_paths and must be seeded explicitly).
+
+const MUTATING_FILE_TOOLS = new Set(['Edit', 'Write', 'MultiEdit', 'NotebookEdit']);
+
+/** Pull file_path/notebook_path args from mutating tool_use blocks in one
+ *  transcript entry. Mirrors extractTranscriptToolNames' shape handling
+ *  (top-level tool_use + nested message.content[] blocks). */
+function extractTranscriptToolFilePaths(entry) {
+  const paths = [];
+  if (!entry || typeof entry !== 'object') return paths;
+  const pull = (name, input) => {
+    if (!name || !MUTATING_FILE_TOOLS.has(name) || !input || typeof input !== 'object') return;
+    const fp = input.file_path || input.notebook_path;
+    if (typeof fp === 'string' && fp) paths.push(fp);
+  };
+  if (entry.type === 'tool_use') pull(entry.name || entry.tool_name, entry.input);
+  const content = entry.message?.content ?? (Array.isArray(entry.content) ? entry.content : null);
+  if (Array.isArray(content)) {
+    for (const block of content) {
+      if (block && typeof block === 'object' && block.type === 'tool_use') {
+        pull(block.name || block.tool_name, block.input);
+      }
+    }
+  }
+  return paths;
+}
+
+/** Normalize an absolute path to a repo-relative POSIX path under hypoDir, or
+ *  null if it resolves outside the wiki. */
+function toHypoRel(absPath, hypoDir) {
+  let rel;
+  try {
+    rel = relative(hypoDir, absPath);
+  } catch {
+    return null;
+  }
+  if (!rel || rel.startsWith('..') || rel.startsWith('/')) return null;
+  return rel.split('\\').join('/');
+}
+
+/**
+ * Repo-relative POSIX paths of wiki files this session edited via direct
+ * Edit/Write/MultiEdit/NotebookEdit tool_use. Returns a Set; empty when the
+ * transcript is missing/unreadable (callers decide the fallback). A per-line
+ * JSON parse error skips that line only (transcripts occasionally truncate).
+ */
+export function extractTouchedWikiFiles(transcriptPath, hypoDir) {
+  const out = new Set();
+  if (!transcriptPath || typeof transcriptPath !== 'string' || !existsSync(transcriptPath)) {
+    return out;
+  }
+  let raw;
+  try {
+    raw = readFileSync(transcriptPath, 'utf-8');
+  } catch {
+    return out;
+  }
+  for (const line of raw.split('\n')) {
+    const t = line.trim();
+    if (!t) continue;
+    let entry;
+    try {
+      entry = JSON.parse(t);
+    } catch {
+      continue;
+    }
+    for (const fp of extractTranscriptToolFilePaths(entry)) {
+      const rel = toHypoRel(fp, hypoDir);
+      if (rel) out.add(rel);
+    }
+  }
+  return out;
+}
+
+/**
+ * The mandatory session-close files (repo-relative POSIX). The documented close
+ * path `crystallize.mjs --apply-session-close` writes these from inside a Bash
+ * call, so they never surface as Edit/Write file_paths — they must seed the
+ * scoped-lint set explicitly or a close-introduced error would escape the gate.
+ * Mirrors the file list in sessionCloseFileStatus.
+ */
+export function closeFileTargets(hypoDir) {
+  const out = new Set(['hot.md', 'log.md']);
+  const project = resolveActiveProject(hypoDir);
+  if (project) {
+    out.add(`projects/${project}/session-state.md`);
+    out.add(`projects/${project}/hot.md`);
+    const month = freshDates()[0].slice(0, 7);
+    out.add(`projects/${project}/session-log/${month}.md`);
+  }
+  return out;
+}
+
+/** Normalize a path's separators to POSIX so scope membership is OS-independent.
+ *  lint.mjs emits `file` via path.relative (back-slashes on Windows) while the
+ *  scope builders produce forward-slash paths — normalize both sides. */
+function posixPath(p) {
+  return (p || '').split('\\').join('/');
+}
+
+/**
+ * Partition lint findings into `blocking` (a file this session is accountable
+ * for) vs `notice` (pre-existing debt elsewhere — surfaced, not blocking).
+ *
+ * `scope` = iterable of repo-relative paths the session is accountable for.
+ * Membership is exact on the normalized path. Only findings passed in are
+ * classified — callers pass lint ERRORS; broken wikilinks (lint W4 warnings) are
+ * intentionally warn-only (forward references to planned pages are normal in a
+ * wiki) and are NOT promoted to blocking by this gate.
+ */
+export function partitionLintScope(findings, scope) {
+  const normScope = new Set([...scope].map(posixPath));
+  const blocking = [];
+  const notice = [];
+  for (const f of findings || []) {
+    if (normScope.has(posixPath(f.file))) blocking.push(f);
+    else notice.push(f);
+  }
+  return { blocking, notice };
+}
+
 // ── session-close checklist ────────────────────────────────────────────────
 
 /**

package/hooks/version-check.mjs

@@ -18,8 +18,8 @@
  *     than overwrites so it never erases the hook's `notifiedFor` marks.
  */
 
-import { readFileSync, writeFileSync, renameSync, mkdirSync } from 'fs';
-import { dirname, join } from 'path';
+import { readFileSync, writeFileSync, renameSync, mkdirSync, realpathSync, existsSync } from 'fs';
+import { dirname, join, delimiter } from 'path';
 import { homedir } from 'os';
 
 export const TTL_MS = 24 * 60 * 60 * 1000; // 24h
@@ -48,24 +48,72 @@ export function parseSemver(v) {
     .replace(/^v/, '')
     .match(/^(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?(?:\+[0-9A-Za-z.-]+)?$/);
   if (!m) return null;
-  return { major: +m[1], minor: +m[2], patch: +m[3], pre: m[4] || '' };
+  // Keep core identifiers as RAW DIGIT STRINGS (not +Number) so compareSemver can
+  // order them precisely — SemVer caps neither core nor prerelease numeric length,
+  // and Number() silently loses precision past 2^53.
+  return { major: m[1], minor: m[2], patch: m[3], pre: m[4] || '' };
+}
+
+/**
+ * Compare two SemVer numeric identifier strings (digits only, no leading zeros).
+ * Done WITHOUT Number() so arbitrary-length identifiers order exactly: fewer
+ * digits ⇒ smaller value; equal length ⇒ ASCII order is numeric order.
+ */
+function compareNumericId(x, y) {
+  if (x.length !== y.length) return x.length < y.length ? -1 : 1;
+  if (x !== y) return x < y ? -1 : 1;
+  return 0;
+}
+
+/**
+ * Compare two prerelease strings per the SemVer §11 precedence rules. Identifiers
+ * are dot-separated; numeric ones compare numerically and always rank LOWER than
+ * alphanumeric ones; a larger set of identifiers outranks a smaller one when all
+ * preceding identifiers are equal. Both inputs are non-empty prereleases here.
+ */
+function comparePrerelease(a, b) {
+  const ai = a.split('.');
+  const bi = b.split('.');
+  const len = Math.max(ai.length, bi.length);
+  for (let i = 0; i < len; i++) {
+    // "a larger set of pre-release fields has higher precedence" → the one that
+    // still has identifiers wins once the shorter one runs out.
+    if (i >= ai.length) return -1;
+    if (i >= bi.length) return 1;
+    const x = ai[i];
+    const y = bi[i];
+    const xn = /^\d+$/.test(x);
+    const yn = /^\d+$/.test(y);
+    if (xn && yn) {
+      const c = compareNumericId(x, y);
+      if (c !== 0) return c;
+    } else if (xn !== yn) {
+      return xn ? -1 : 1; // numeric identifiers have lower precedence
+    } else if (x !== y) {
+      return x < y ? -1 : 1; // ASCII lexical for alphanumeric
+    }
+  }
+  return 0;
 }
 
 /**
  * Compare two semver strings. Returns -1 / 0 / 1, or null if either is invalid.
- * A release outranks a prerelease of the same x.y.z (1.2.3 > 1.2.3-rc.1).
+ * A release outranks a prerelease of the same x.y.z (1.2.3 > 1.2.3-rc.1), and
+ * prereleases follow full SemVer §11 precedence (1.2.3-rc.2 < 1.2.3-rc.10) — this
+ * matters because compareSemver now gates the init/upgrade downgrade guard.
  */
 export function compareSemver(a, b) {
   const pa = parseSemver(a);
   const pb = parseSemver(b);
   if (!pa || !pb) return null;
   for (const k of ['major', 'minor', 'patch']) {
-    if (pa[k] !== pb[k]) return pa[k] < pb[k] ? -1 : 1;
+    const c = compareNumericId(pa[k], pb[k]);
+    if (c !== 0) return c;
   }
   if (pa.pre === pb.pre) return 0;
   if (!pa.pre) return 1; // release > prerelease
   if (!pb.pre) return -1;
-  return pa.pre < pb.pre ? -1 : 1; // lexicographic fallback (good enough)
+  return comparePrerelease(pa.pre, pb.pre);
 }
 
 // ── channel detection ──────────────────────────────────────────────────────
@@ -182,3 +230,153 @@ export function mergeLatest(path, latest, now = Date.now()) {
 export function isOptedOut(env = process.env) {
   return Boolean(env.HYPO_NO_UPDATE_CHECK || env.NO_UPDATE_NOTIFIER || env.CI);
 }
+
+// ── stale-sibling detection (ADR 0038) ───────────────────────────────────────
+//
+// A second, OLDER Hypomnema can sit on $PATH (e.g. a stale `npm i -g hypomnema`)
+// while a newer copy owns the active hooks. The CLI bin (`hypomnema`) then routes
+// `hypomnema init` / `upgrade --apply` through the OLD package, which silently
+// downgrades the newer registered hooks (dropping features like this notifier).
+//
+// The update-notifier above only asks "is MY install behind latest?" — it is
+// blind to a stale SIBLING. These helpers add that axis. They are fs-only and
+// offline (no `npm`, no `which` spawn) so they are safe inside the SessionStart
+// hook and `doctor`.
+
+/** realpathSync that returns null instead of throwing on a missing/broken path. */
+export function realpathSafe(p) {
+  if (typeof p !== 'string' || !p) return null;
+  try {
+    return realpathSync(p);
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Read the nearest ancestor `package.json` named `hypomnema`, starting at `start`
+ * and walking up. Returns { pkgRoot, version } or null. Used to map a resolved
+ * bin path back to the package that owns it.
+ */
+function readOwningPkg(start) {
+  let dir = start;
+  // Bounded ascent (filesystem depth is finite; cap defensively).
+  for (let i = 0; i < 64; i++) {
+    const pkgPath = join(dir, 'package.json');
+    if (existsSync(pkgPath)) {
+      try {
+        const pkg = JSON.parse(readFileSync(pkgPath, 'utf-8'));
+        if (pkg && pkg.name === 'hypomnema' && typeof pkg.version === 'string') {
+          return { pkgRoot: dir, version: pkg.version };
+        }
+      } catch {
+        /* keep ascending — a non-hypomnema package.json is not our target */
+      }
+    }
+    const parent = dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  return null;
+}
+
+/**
+ * Locate the `hypomnema` CLI on $PATH WITHOUT spawning `which`/`npm`.
+ *
+ * Splits $PATH, probes each dir for the bin (plus PATHEXT variants on Windows),
+ * resolves symlinks (npm global bins are symlinks into node_modules), then walks
+ * up to the owning package.json. Returns { binPath, pkgRoot, version } for the
+ * FIRST hit — that is the one the shell would actually run — or null.
+ *
+ * Windows note: npm installs `.cmd`/`.ps1` launcher shims (not symlinks), so the
+ * realpath→package.json walk usually fails there and we return null rather than
+ * guess. POSIX (the reported footgun) resolves cleanly.
+ */
+export function resolveCliOnPath(binName = 'hypomnema', env = process.env) {
+  const pathVar = env.PATH || env.Path || '';
+  if (!pathVar) return null;
+  const dirs = pathVar.split(delimiter).filter(Boolean);
+  const exts =
+    process.platform === 'win32'
+      ? (env.PATHEXT || '.COM;.EXE;.BAT;.CMD').split(';').filter(Boolean)
+      : [''];
+  for (const dir of dirs) {
+    for (const ext of exts) {
+      const candidate = join(dir, binName + ext.toLowerCase());
+      const real = realpathSafe(candidate);
+      if (!real) continue;
+      const owner = readOwningPkg(dirname(real));
+      if (owner) return { binPath: candidate, ...owner };
+    }
+  }
+  return null;
+}
+
+/**
+ * Classify two installs by version and identity. Returns:
+ *   'same'      — same package root (dev re-run / npm-link) → never a downgrade
+ *   'downgrade' — `incoming` is strictly OLDER than `active`
+ *   'ok'        — `incoming` >= `active`
+ *   'unknown'   — either version unparseable; cannot prove a downgrade
+ *
+ * realpath-compares the roots first so a dev workspace re-running its own
+ * init/upgrade is never mis-flagged.
+ */
+export function classifyInstall(incoming, active) {
+  const ri = realpathSafe(incoming && incoming.pkgRoot);
+  const ra = realpathSafe(active && active.pkgRoot);
+  if (ri && ra && ri === ra) return 'same';
+  const cmp = compareSemver(incoming && incoming.version, active && active.version);
+  if (cmp === null) return 'unknown';
+  return cmp < 0 ? 'downgrade' : 'ok';
+}
+
+/**
+ * Decide whether to warn about a stale sibling owning the CLI. Returns
+ * { cliVersion, line, key } or null. Warns only when the PATH CLI is a DIFFERENT,
+ * strictly OLDER package than the active install.
+ *
+ * `key` is a throttle token (cli path+version → active version) so the
+ * SessionStart hook can suppress repeats via `siblingNotifiedFor`.
+ */
+export function computeSiblingNotice(cli, active) {
+  if (!cli || !active || !active.version) return null;
+  if (classifyInstall(cli, active) !== 'downgrade') return null;
+  const key = `${cli.binPath || cli.pkgRoot}@${cli.version}->${active.version}`;
+  const line =
+    `[Hypomnema] Stale install on PATH: \`${cli.binPath || cli.pkgRoot}\` is v${cli.version}, ` +
+    `but your active install is v${active.version}.\n` +
+    `  Running \`hypomnema init\`/\`upgrade\` from PATH would DOWNGRADE your hooks.\n` +
+    `  → remove the old one:  npm uninstall -g hypomnema   (then re-check with \`hypomnema doctor\`)`;
+  return { cliVersion: cli.version, line, key };
+}
+
+/** Has this exact sibling tuple already been surfaced? */
+export function siblingAlreadyNotified(cache, key) {
+  return Boolean(cache && cache.siblingNotifiedFor === key);
+}
+
+/** Record that the sibling banner for `key` was shown (read-merge-write). */
+export function markSiblingNotified(path, key) {
+  try {
+    const cache = readCache(path) || {};
+    cache.siblingNotifiedFor = key;
+    writeCacheAtomic(path, cache);
+  } catch {
+    /* best-effort */
+  }
+}
+
+/**
+ * Shared one-line message for the init/upgrade downgrade guard (P). `op` is
+ * 'init' or 'upgrade'. Kept here so guard text stays identical across both CLIs.
+ */
+export function downgradeGuardMessage(incomingVersion, activeVersion, op) {
+  return (
+    `[Hypomnema] Refusing to ${op}: this package is v${incomingVersion}, but your ` +
+    `active install is NEWER (v${activeVersion}).\n` +
+    `  This is usually a stale global CLI on PATH — proceeding would DOWNGRADE your hooks.\n` +
+    `  → upgrade the stale copy:  npm install -g hypomnema\n` +
+    `  → or, if you really mean to downgrade:  re-run with --allow-downgrade`
+  );
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hypomnema",
-  "version": "1.2.1",
+  "version": "1.3.0",
   "description": "LLM-native personal wiki system for Claude Code",
   "type": "module",
   "license": "MIT",
@@ -39,11 +39,14 @@
   "scripts": {
     "test": "node tests/runner.mjs",
     "lint": "node scripts/lint.mjs",
+    "fix:verify": "node scripts/fix-status-verify.mjs",
     "graph": "node scripts/graph.mjs",
     "smoke-pack": "node scripts/smoke-pack.mjs",
+    "check:bilingual": "node scripts/check-bilingual.mjs --changelog",
     "format": "prettier --write .",
     "format:check": "prettier --check .",
-    "prepublishOnly": "npm test && npm run lint && npm run smoke-pack"
+    "prepare": "node scripts/install-git-hooks.mjs",
+    "prepublishOnly": "npm test && npm run lint && npm run smoke-pack && npm run check:bilingual"
   },
   "devDependencies": {
     "prettier": "^3.8.3"

package/scripts/bump-version.mjs

@@ -52,6 +52,12 @@ for (const { path, pattern } of targets) {
 }
 
 console.log(`\nNext steps:`);
-console.log(`  git add -A && git commit -m "chore(release): v${next}"`);
-console.log(`  git tag v${next}`);
-console.log(`  git push origin <branch> --tags`);
+console.log(`  1. Edit CHANGELOG.md — ensure the "## [${next}]" section has a`);
+console.log(`     "### 한글 요약" sub-section (release.yml check-bilingual gate).`);
+console.log(`  2. node scripts/check-bilingual.mjs --changelog   # local pre-check`);
+console.log(`  3. git add -A && git commit -m "chore(release): v${next}"`);
+console.log(`  4. Create an ANNOTATED tag (lightweight tags are rejected by CI):`);
+console.log(`       git tag -a v${next} -m "<English body>\\n\\n---\\n\\n<한글 요약>"`);
+console.log(`     See docs/CONTRIBUTING.md "Cutting a release" for the full template.`);
+console.log(`  5. node scripts/check-bilingual.mjs --tag v${next}   # local pre-check`);
+console.log(`  6. git push origin <branch> --tags`);

package/scripts/check-bilingual.mjs

@@ -0,0 +1,115 @@
+#!/usr/bin/env node
+/**
+ * check-bilingual.mjs — CLI gate for the bilingual release-doc rule.
+ *
+ * Modes:
+ *   --changelog [version]   Validate CHANGELOG.md section for given version.
+ *                           Defaults to package.json's "version" field.
+ *                           Wired into npm `prepublishOnly` so publishes fail
+ *                           when the Korean summary is missing.
+ *
+ *   --tag <ref>             Validate annotated tag body for given ref.
+ *                           Wired into .github/workflows/release.yml so a
+ *                           lightweight tag or a missing Korean section
+ *                           blocks the npm publish step.
+ *
+ * Exits 0 on pass, 1 on fail with a stderr diagnostic.
+ */
+
+import { readFileSync } from 'fs';
+import { spawnSync } from 'child_process';
+import { fileURLToPath } from 'url';
+import { dirname, join } from 'path';
+import { validateChangelog, validateTagBody } from './lib/check-bilingual.mjs';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const REPO_ROOT = join(__dirname, '..');
+
+const RULE_REF =
+  'Rule source: CLAUDE.md learned_behaviors (release-doc-bilingual, 2026-05-24). ' +
+  'OSS Hypomnema ships must carry English body + Korean summary in both CHANGELOG section and git tag annotation.';
+
+function fail(msg) {
+  process.stderr.write(`[check-bilingual] FAIL: ${msg}\n${RULE_REF}\n`);
+  process.exit(1);
+}
+
+function ok(msg) {
+  process.stdout.write(`[check-bilingual] OK: ${msg}\n`);
+  process.exit(0);
+}
+
+function usage(exitCode) {
+  process.stdout.write(
+    `Usage:\n` +
+      `  node scripts/check-bilingual.mjs --changelog [version]\n` +
+      `      Validate CHANGELOG.md "## [<version>]" section. Default version: package.json.\n` +
+      `  node scripts/check-bilingual.mjs --tag <ref>\n` +
+      `      Validate annotated tag body (lightweight tags are rejected).\n`,
+  );
+  process.exit(exitCode);
+}
+
+const args = process.argv.slice(2);
+const mode = args[0];
+
+if (mode === '--help' || mode === '-h') usage(0);
+if (!mode) usage(1);
+
+if (mode === '--changelog') {
+  let version = args[1];
+  if (!version) {
+    try {
+      const pkg = JSON.parse(readFileSync(join(REPO_ROOT, 'package.json'), 'utf-8'));
+      version = pkg.version;
+    } catch (err) {
+      fail(`cannot read package.json: ${err.message}`);
+    }
+  }
+  if (!version) fail('no version (arg empty, package.json has no "version" field)');
+
+  let content;
+  try {
+    content = readFileSync(join(REPO_ROOT, 'CHANGELOG.md'), 'utf-8');
+  } catch (err) {
+    fail(`cannot read CHANGELOG.md: ${err.message}`);
+  }
+
+  const result = validateChangelog(content, version);
+  if (!result.ok) fail(result.reason);
+  ok(`CHANGELOG.md [${version}] — ${result.hangulCount} Hangul chars in "### 한글 요약".`);
+} else if (mode === '--tag') {
+  const ref = args[1];
+  if (!ref) fail('--tag requires a ref argument (e.g. v1.2.1)');
+
+  // Reject lightweight tags. `git rev-parse <ref>^{tag}` succeeds ONLY for
+  // annotated tags. For lightweight tags the ^{tag} peel fails because there
+  // is no tag object — the ref points straight at a commit.
+  const tagObj = spawnSync('git', ['rev-parse', '--verify', '--quiet', `${ref}^{tag}`], {
+    encoding: 'utf-8',
+    cwd: REPO_ROOT,
+  });
+  if (tagObj.status !== 0) {
+    const exists = spawnSync('git', ['rev-parse', '--verify', '--quiet', ref], {
+      encoding: 'utf-8',
+      cwd: REPO_ROOT,
+    });
+    if (exists.status !== 0) fail(`tag ${ref} not found`);
+    fail(
+      `tag ${ref} is a lightweight tag, not annotated. ` +
+        `Re-create with: git tag -a ${ref} -m "<English body>\n\n---\n\n<Korean summary>"`,
+    );
+  }
+
+  const tagBody = spawnSync('git', ['tag', '-l', `--format=%(contents)`, ref], {
+    encoding: 'utf-8',
+    cwd: REPO_ROOT,
+  });
+  if (tagBody.status !== 0) fail(`failed to read tag ${ref}: ${tagBody.stderr}`);
+
+  const result = validateTagBody(tagBody.stdout || '');
+  if (!result.ok) fail(`tag ${ref} — ${result.reason}`);
+  ok(`tag ${ref} annotation — ${result.hangulCount} Hangul chars after last "---" separator.`);
+} else {
+  fail(`unknown mode: ${mode}. Use --changelog or --tag (see --help).`);
+}