hypomnema 1.3.4 → 1.4.1

package/hooks/hypo-shared.mjs

@@ -846,7 +846,10 @@ function syncStatePath(hypoDir) {
  * failure-log must not break the Stop hook that calls it.
  *
  * @param {string} hypoDir
- * @param {'pull'|'push'} op
+ * @param {'pull'|'push'|'conflict'|'conflict-unresolved'} op  'conflict' = a
+ *   merge conflict was detected and aborted (the tree was left clean at the
+ *   local commit); 'conflict-unresolved' = the abort itself failed and the tree
+ *   may still be half-merged (rare). See syncRemote.
  * @param {string} error  raw stderr/stdout; first non-empty line is kept
  */
 export function appendSyncFailure(hypoDir, op, error) {
@@ -870,6 +873,70 @@ export function appendSyncFailure(hypoDir, op, error) {
   }
 }
 
+/**
+ * Pull + push the wiki against its remote, guaranteeing the working tree is
+ * never left half-merged. Called by the auto-commit Stop hook after a local
+ * commit succeeds.
+ *
+ * Failure policy (v1.4 "sync hardening", tracker FEAT-17):
+ *   - clean fast-forward / conflict-free merge → push.
+ *   - MERGE CONFLICT (`git pull --no-rebase` leaves unmerged paths): abort the
+ *     merge so the tree returns to the just-committed local state ("ours"),
+ *     record op='conflict', and do NOT push (a diverged branch cannot
+ *     fast-forward, so the push would only add a noisy second failure). No data
+ *     is lost: ours stays committed locally, "theirs" stays on the remote, and
+ *     the divergence is surfaced by session-start + doctor until the user merges
+ *     manually. Inline auto-resolution (preserving the losing version as a
+ *     `.conflict-*` sibling) is deferred — see tracker PRAC-18.
+ *   - non-conflict pull failure (network/auth: no unmerged paths) → record
+ *     op='pull', then still attempt push (a transient pull blip should not block
+ *     an otherwise-pushable commit); record op='push' if that also fails.
+ *
+ * Best-effort: never throws — a sync failure must not break the Stop hook.
+ *
+ * @param {string} hypoDir
+ * @returns {{pulled: boolean, pushed: boolean, conflict: boolean}}
+ */
+export function syncRemote(hypoDir) {
+  const git = (...args) =>
+    spawnSync('git', ['-C', hypoDir, ...args], { encoding: 'utf-8', timeout: 30000 });
+  const result = { pulled: false, pushed: false, conflict: false };
+  try {
+    const pull = git('pull', '--no-rebase', '-q');
+    if (pull.status === 0) {
+      result.pulled = true;
+    } else {
+      // A merge conflict leaves unmerged index entries; a network/auth failure
+      // leaves none. Only the former must be aborted to keep the tree clean.
+      const unmerged = git('ls-files', '-u');
+      const hasConflict = unmerged.status === 0 && (unmerged.stdout || '').trim().length > 0;
+      if (hasConflict) {
+        // Abort to return the tree to the just-committed local state. Verify the
+        // abort actually cleaned up: if it fails (filesystem/concurrent-mutation
+        // edge), the tree may still be half-merged, so record that distinctly
+        // ('conflict-unresolved') rather than masking it as a clean abort.
+        const abort = git('merge', '--abort');
+        const stillUnmerged = git('ls-files', '-u');
+        const aborted = abort.status === 0 && (stillUnmerged.stdout || '').trim().length === 0;
+        appendSyncFailure(
+          hypoDir,
+          aborted ? 'conflict' : 'conflict-unresolved',
+          pull.stderr || pull.stdout,
+        );
+        result.conflict = true;
+        return result; // do not push from a diverged branch
+      }
+      appendSyncFailure(hypoDir, 'pull', pull.stderr || pull.stdout);
+    }
+    const push = git('push');
+    if (push.status === 0) result.pushed = true;
+    else appendSyncFailure(hypoDir, 'push', push.stderr || push.stdout);
+  } catch {
+    // best-effort — never break the Stop hook
+  }
+  return result;
+}
+
 /**
  * Stage + commit every non-.hypoignore change in the wiki. Does NOT pull/push —
  * remote sync stays in the auto-commit Stop hook (commit is local + cheap; sync is

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hypomnema",
-  "version": "1.3.4",
+  "version": "1.4.1",
   "description": "LLM-native personal wiki system for Claude Code",
   "type": "module",
   "license": "MIT",
@@ -9,6 +9,11 @@
   },
   "files": [
     "scripts/",
+    "!scripts/collect-changelog.mjs",
+    "!scripts/lib/collect-changelog.mjs",
+    "!scripts/bump-version.mjs",
+    "!scripts/smoke-pack.mjs",
+    "!scripts/smoke-plugin.mjs",
     "commands/",
     "hooks/",
     "skills/",
@@ -42,12 +47,15 @@
     "fix:verify": "node scripts/fix-status-verify.mjs",
     "graph": "node scripts/graph.mjs",
     "smoke-pack": "node scripts/smoke-pack.mjs",
+    "check:versions": "node scripts/check-versions.mjs",
+    "smoke:plugin": "node scripts/smoke-plugin.mjs",
     "check:bilingual": "node scripts/check-bilingual.mjs --changelog",
+    "check:readme": "node scripts/check-readme-version.mjs",
     "check:tracker-ids": "node scripts/check-tracker-ids.mjs --all",
     "format": "prettier --write .",
     "format:check": "prettier --check .",
     "prepare": "node scripts/install-git-hooks.mjs",
-    "prepublishOnly": "npm test && npm run lint && npm run smoke-pack && npm run check:bilingual && npm run check:tracker-ids"
+    "prepublishOnly": "npm test && npm run lint && npm run check:versions && npm run smoke:plugin && npm run smoke-pack && npm run check:bilingual && npm run check:readme && npm run check:tracker-ids"
   },
   "devDependencies": {
     "prettier": "^3.8.3"

package/scripts/check-bilingual.mjs

@@ -20,7 +20,12 @@ 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';
+import {
+  validateChangelog,
+  validateTagBody,
+  listChangelogVersions,
+  meetsKoreanCutoff,
+} from './lib/check-bilingual.mjs';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const REPO_ROOT = join(__dirname, '..');
@@ -43,7 +48,11 @@ 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` +
+      `      Validate one CHANGELOG.md "## [<version>]" section (section model).\n` +
+      `      Default version: package.json.\n` +
+      `  node scripts/check-bilingual.mjs --changelog --all\n` +
+      `      Validate EVERY documented version (Korean enforced at >= 1.2.0,\n` +
+      `      English-only versions below the cutoff pass).\n` +
       `  node scripts/check-bilingual.mjs --tag <ref>\n` +
       `      Validate annotated tag body (lightweight tags are rejected).\n`,
   );
@@ -52,12 +61,44 @@ function usage(exitCode) {
 
 const args = process.argv.slice(2);
 const mode = args[0];
+const wantAll = args.includes('--all');
 
 if (mode === '--help' || mode === '-h') usage(0);
 if (!mode) usage(1);
 
 if (mode === '--changelog') {
-  let version = args[1];
+  let content;
+  try {
+    content = readFileSync(join(REPO_ROOT, 'CHANGELOG.md'), 'utf-8');
+  } catch (err) {
+    fail(`cannot read CHANGELOG.md: ${err.message}`);
+  }
+
+  if (wantAll) {
+    // Validate every documented version. Korean is enforced only at/after the
+    // cutoff; pre-cutoff versions pass on English presence (format.md §9). This
+    // is the migration gate — it must not green-pass a half-migrated file.
+    const versions = listChangelogVersions(content);
+    if (versions.length === 0) fail('no "## [<version>]" sections found in CHANGELOG.md');
+    const failures = [];
+    let enforced = 0;
+    for (const v of versions) {
+      const r = validateChangelog(content, v);
+      if (meetsKoreanCutoff(v)) enforced++;
+      if (!r.ok) failures.push(`  [${v}] ${r.reason}`);
+    }
+    if (failures.length) {
+      fail(`${failures.length}/${versions.length} version(s) failed:\n${failures.join('\n')}`);
+    }
+    ok(
+      `CHANGELOG.md --all: ${versions.length} versions conform ` +
+        `(${enforced} Korean-enforced at >= 1.2.0, ${versions.length - enforced} English-only below cutoff).`,
+    );
+  }
+
+  // single-version path (kept: prepublishOnly and release.yml call --changelog
+  // with no version, defaulting to package.json's).
+  let version = args[1] && !args[1].startsWith('--') ? args[1] : undefined;
   if (!version) {
     try {
       const pkg = JSON.parse(readFileSync(join(REPO_ROOT, 'package.json'), 'utf-8'));
@@ -68,16 +109,13 @@ if (mode === '--changelog') {
   }
   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 "### 한글 요약".`);
+  if (result.koreanExempt) {
+    ok(`CHANGELOG.md [${version}] — pre-cutoff version, English-only (Korean exempt).`);
+  } else {
+    ok(`CHANGELOG.md [${version}] — ${result.hangulCount} Hangul chars across "#### 한국어" sub-blocks.`);
+  }
 } else if (mode === '--tag') {
   const ref = args[1];
   if (!ref) fail('--tag requires a ref argument (e.g. v1.2.1)');

package/scripts/check-readme-version.mjs

@@ -0,0 +1,126 @@
+#!/usr/bin/env node
+// check-readme-version.mjs — assert the release version string is present in BOTH
+// README.md and README.ko.md. This is the machine FLOOR for the README-reconcile
+// step that was dropped three times (v1.2 / v1.3.0 / v1.3.1): a publish of vX.Y.Z
+// must not go out unless vX.Y.Z is written into both READMEs' version narrative.
+//
+// SCOPE (honest): this catches the GROSS drop — shipping a version whose sentence
+// was never added to the README at all. It does NOT verify the narrative is
+// accurate or that the first-viewport "current release" pointer was updated; that
+// stays a judgment step owned by the release checklist (docs/CONTRIBUTING.md
+// "Cutting a release"). README/CHANGELOG carry
+// prose version HISTORY (every past vX.Y.Z), so check-versions.mjs intentionally
+// excludes them — this script is their complement, not a duplicate.
+//
+// Usage:
+//   node scripts/check-readme-version.mjs                 # version from package.json
+//   node scripts/check-readme-version.mjs --version 1.4.0 # explicit version
+//   node scripts/check-readme-version.mjs --root <dir>    # point at a fixture (tests)
+//   node scripts/check-readme-version.mjs --json
+//
+// Exit 0 = both READMEs mention the version. Exit 1 = missing in one/both, or unreadable.
+
+import { readFileSync } from 'fs';
+import { join, dirname } from 'path';
+import { fileURLToPath } from 'url';
+
+function parseArgs(argv) {
+  const args = { root: null, version: null, json: false };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a.startsWith('--root=')) args.root = a.slice(7);
+    else if (a === '--root') args.root = argv[++i];
+    else if (a.startsWith('--version=')) args.version = a.slice(10);
+    else if (a === '--version') args.version = argv[++i];
+    else if (a === '--json') args.json = true;
+  }
+  return args;
+}
+
+const REPO_ROOT = join(dirname(fileURLToPath(import.meta.url)), '..');
+
+const README_FILES = ['README.md', 'README.ko.md'];
+
+// Build a boundary-aware matcher so a version does not spuriously match inside a
+// LONGER version token yet still matches at a sentence boundary. The checked
+// version must be a standalone token, NOT a prefix of another version:
+//   - "1.3.40", "v11.3.4"      → reject (digit continuation)
+//   - "1.3.4.5"                → reject (dot-then-digit continuation)
+//   - "1.3.4-rc.1", "1.3.4+b"  → reject (a stable check must NOT pass on a
+//                                 prerelease/build string — that defeats the floor)
+//   - "1.3.0-rc.1a", "1.3.0-rc.10", "1.3.0-rc.1.alpha" → a prerelease check must
+//                                 reject these continuation tokens too
+//   - "shipped v1.3.4." / "v1.3.4**" / "(v1.3.4)" → match (sentence/markup boundary)
+// Leading: no digit/dot immediately before (an optional "v" is fine — it is
+// neither). Trailing: not a semver-continuation char ([0-9A-Za-z+-]) and not a
+// dot-then-alphanumeric (".5" / ".alpha" continuation); a sentence period
+// (dot followed by space / punctuation / end) is allowed.
+function versionPresent(text, version) {
+  const escaped = version.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+  return new RegExp(`(?<![\\d.])${escaped}(?![\\dA-Za-z+-])(?!\\.[\\dA-Za-z])`).test(text);
+}
+
+function checkReadmeVersions(root, version) {
+  const results = README_FILES.map((file) => {
+    const abs = join(root, file);
+    try {
+      const text = readFileSync(abs, 'utf-8');
+      return { file, present: versionPresent(text, version) };
+    } catch (err) {
+      return { file, present: false, error: err?.message ?? String(err) };
+    }
+  });
+  const ok = results.every((r) => r.present);
+  return { ok, version, results };
+}
+
+function main() {
+  const args = parseArgs(process.argv.slice(2));
+  const root = args.root || REPO_ROOT;
+
+  let version = args.version;
+  if (!version) {
+    try {
+      version = JSON.parse(readFileSync(join(root, 'package.json'), 'utf-8')).version;
+    } catch (err) {
+      const msg = `cannot read package.json for version: ${err?.message ?? err}`;
+      if (args.json) console.log(JSON.stringify({ ok: false, error: msg }, null, 2));
+      else console.error(`✗ ${msg}`);
+      process.exit(1);
+    }
+  }
+  if (typeof version !== 'string' || !version) {
+    const msg = 'no version (—version empty and package.json has no "version" field)';
+    if (args.json) console.log(JSON.stringify({ ok: false, error: msg }, null, 2));
+    else console.error(`✗ ${msg}`);
+    process.exit(1);
+  }
+
+  const report = checkReadmeVersions(root, version);
+
+  if (args.json) {
+    console.log(JSON.stringify(report, null, 2));
+  } else {
+    for (const r of report.results) {
+      const mark = r.error ? `ERROR: ${r.error}` : r.present ? 'found' : 'MISSING';
+      console.log(`  ${r.file.padEnd(13)}  ${mark}`);
+    }
+    if (report.ok) {
+      console.log(`\n✓ both READMEs mention version ${version}`);
+    } else {
+      const missing = report.results
+        .filter((r) => !r.present)
+        .map((r) => (r.error ? `${r.file} (unreadable)` : r.file))
+        .join(', ');
+      console.error(
+        `\n✗ version ${version} missing from: ${missing}\n` +
+          `  Reconcile the version narrative in both READMEs before releasing ` +
+          `(the README reconcile step — see docs/CONTRIBUTING.md "Cutting a release").`,
+      );
+    }
+  }
+
+  process.exit(report.ok ? 0 : 1);
+}
+
+main();

package/scripts/check-tracker-ids.mjs

@@ -51,6 +51,7 @@ import {
   messageHasGitTemplate,
   BLOCKED_PATTERNS,
   USER_FACING_PATTERNS,
+  TAG_BODY_PATTERNS,
 } from './lib/check-tracker-ids.mjs';
 import {
   parseNameStatus,
@@ -297,6 +298,52 @@ function runCommitMsg(file, json) {
   process.exit(report(violations, json));
 }
 
+// Scan an annotated tag's body for ALL wiki tracker prefixes (TAG_BODY_PATTERNS:
+// ISSUE-/fix #/FEAT-/IMPR-/PRAC-). The tag body is the PUBLIC release surface —
+// `gh release create --notes-from-tag` republishes it verbatim — and it carries
+// no code, so unlike the file gate it must reject every prefix (changelog-pr-
+// guide §5 / T4). Wired into release.yml before `gh release create`. `--tag -`
+// reads the body from stdin (piping / test), `--tag <ref>` reads it from git.
+function runTag(ref, json) {
+  let body;
+  if (ref === '-') {
+    try {
+      body = readFileSync(0, 'utf-8');
+    } catch (err) {
+      process.stderr.write(`[check-tracker-ids] --tag -: cannot read stdin: ${err.message}\n`);
+      process.exit(2);
+    }
+  } else {
+    // Require an annotated tag: `<ref>^{tag}` peels only for an annotated tag
+    // object. A lightweight tag has no body to leak, but a release uses
+    // --notes-from-tag on an annotated tag, so a lightweight one here is a
+    // release misconfiguration — fail loudly rather than silently pass.
+    const tagObj = git(['rev-parse', '--verify', '--quiet', `${ref}^{tag}`]);
+    if (tagObj.status !== 0) {
+      const exists = git(['rev-parse', '--verify', '--quiet', ref]);
+      if (exists.status !== 0) {
+        process.stderr.write(`[check-tracker-ids] --tag: tag ${ref} not found\n`);
+      } else {
+        process.stderr.write(
+          `[check-tracker-ids] --tag: ${ref} is a lightweight tag (no annotation body to scan)\n`,
+        );
+      }
+      process.exit(2);
+    }
+    const tagBody = git(['tag', '-l', '--format=%(contents)', ref]);
+    if (tagBody.status !== 0) {
+      process.stderr.write(
+        `[check-tracker-ids] --tag: failed to read tag ${ref}: ${tagBody.stderr}\n`,
+      );
+      process.exit(2);
+    }
+    body = tagBody.stdout || '';
+  }
+  const file = ref === '-' ? '<stdin>' : `tag:${ref}`;
+  const violations = scanText(body, TAG_BODY_PATTERNS).map((h) => ({ file, ...h }));
+  process.exit(report(violations, json));
+}
+
 // ── arg parsing ────────────────────────────────────────────────────────────
 
 function usage(code) {
@@ -304,7 +351,10 @@ function usage(code) {
     'Usage:\n' +
       '  node scripts/check-tracker-ids.mjs [--all] [--json]\n' +
       '  node scripts/check-tracker-ids.mjs --staged [--json]\n' +
-      '  node scripts/check-tracker-ids.mjs --commit-msg <file> [--json]\n',
+      '  node scripts/check-tracker-ids.mjs --commit-msg <file> [--json]\n' +
+      '  node scripts/check-tracker-ids.mjs --tag <ref|-> [--json]\n' +
+      '      Scan an annotated tag body (or stdin via "-") for ALL tracker\n' +
+      '      prefixes; the public release surface must be tracker-ID-0.\n',
   );
   process.exit(code);
 }
@@ -321,6 +371,15 @@ if (argv.includes('--commit-msg')) {
     usage(2);
   }
   runCommitMsg(file, json);
+} else if (argv.includes('--tag')) {
+  const i = argv.indexOf('--tag');
+  const ref = argv[i + 1];
+  // `-` (stdin) is a valid ref token here; only a missing/flag value is an error.
+  if (!ref || (ref.startsWith('--') && ref !== '-')) {
+    process.stderr.write('[check-tracker-ids] --tag requires a ref argument (or "-" for stdin)\n');
+    usage(2);
+  }
+  runTag(ref, json);
 } else if (argv.includes('--staged')) {
   runStaged(json);
 } else {

package/scripts/check-versions.mjs

@@ -0,0 +1,171 @@
+#!/usr/bin/env node
+// check-versions.mjs — assert every version-carrying file in the repo agrees, and
+// (with --tag) that they all match the release tag. This makes the release pipeline
+// OWN the plugin channel: a forgotten plugin.json / marketplace.json / hypo-config /
+// lockfile bump hard-fails the release instead of publishing a split-version plugin.
+//
+// The set mirrors scripts/bump-version.mjs (package.json, .claude-plugin/plugin.json,
+// .claude-plugin/marketplace.json, templates/hypo-config.md) PLUS package-lock.json,
+// which npm — not bump-version — manages, so it can lag a bump and silently break
+// `npm ci`. README/CHANGELOG carry prose version HISTORY (every past vX.Y.Z), not a
+// single release authority, so they are intentionally excluded (covered by the
+// bilingual + README-reconcile checklist instead).
+//
+// Usage:
+//   node scripts/check-versions.mjs               # assert all files agree
+//   node scripts/check-versions.mjs --tag v1.4.0  # also assert they equal the tag
+//   node scripts/check-versions.mjs --root <dir>  # point at a fixture (tests)
+//   node scripts/check-versions.mjs --json
+//
+// Exit 0 = consistent (and, with --tag, matches). Exit 1 = drift / unreadable / mismatch.
+
+import { readFileSync } from 'fs';
+import { join, dirname } from 'path';
+import { fileURLToPath } from 'url';
+
+function parseArgs(argv) {
+  const args = { root: null, tag: null, json: false };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a.startsWith('--root=')) args.root = a.slice(7);
+    else if (a === '--root') args.root = argv[++i];
+    else if (a.startsWith('--tag=')) args.tag = a.slice(6);
+    else if (a === '--tag') args.tag = argv[++i];
+    else if (a === '--json') args.json = true;
+  }
+  return args;
+}
+
+const REPO_ROOT = join(dirname(fileURLToPath(import.meta.url)), '..');
+
+function readJson(abs) {
+  return JSON.parse(readFileSync(abs, 'utf-8'));
+}
+
+// Collect {label, version} for every authoritative location. A location that
+// cannot be read or whose field is missing becomes {label, version: null, error}.
+function collectVersions(root) {
+  const sources = [];
+  const push = (label, fn) => {
+    try {
+      const v = fn();
+      if (typeof v !== 'string' || v.length === 0) {
+        sources.push({ label, version: null, error: 'version field missing or empty' });
+      } else {
+        sources.push({ label, version: v });
+      }
+    } catch (err) {
+      sources.push({ label, version: null, error: err?.message ?? String(err) });
+    }
+  };
+
+  push('package.json', () => readJson(join(root, 'package.json')).version);
+
+  // package-lock.json carries the version in TWO top-level spots (lockfileVersion 3):
+  // the root `.version` and `.packages[""].version`. Dependency versions deeper in
+  // the tree are NOT release authorities and must not be read.
+  push('package-lock.json (root)', () => readJson(join(root, 'package-lock.json')).version);
+  push('package-lock.json (packages[""])', () => {
+    const lock = readJson(join(root, 'package-lock.json'));
+    return lock.packages && lock.packages[''] ? lock.packages[''].version : undefined;
+  });
+
+  const pluginName = (() => {
+    try {
+      return readJson(join(root, '.claude-plugin', 'plugin.json')).name;
+    } catch {
+      return null;
+    }
+  })();
+
+  push(
+    '.claude-plugin/plugin.json',
+    () => readJson(join(root, '.claude-plugin', 'plugin.json')).version,
+  );
+
+  // Select the marketplace entry BY NAME (matching plugin.json), not by position:
+  // Claude Code's runtime resolves plugins by name (hooks/version-check.mjs), and a
+  // future second marketplace entry would make plugins[0] the wrong authority.
+  push('.claude-plugin/marketplace.json (entry: ' + (pluginName ?? '?') + ')', () => {
+    const mp = readJson(join(root, '.claude-plugin', 'marketplace.json'));
+    const plugins = Array.isArray(mp.plugins) ? mp.plugins : [];
+    if (!pluginName)
+      throw new Error('plugin.json name unreadable — cannot match marketplace entry');
+    const matches = plugins.filter((p) => p && p.name === pluginName);
+    if (matches.length !== 1) {
+      throw new Error(
+        `expected exactly one marketplace entry named "${pluginName}", found ${matches.length}`,
+      );
+    }
+    return matches[0].version;
+  });
+
+  // hypo-config.md frontmatter: version: "X.Y.Z"
+  push('templates/hypo-config.md', () => {
+    const text = readFileSync(join(root, 'templates', 'hypo-config.md'), 'utf-8');
+    const m = text.match(/^version:\s*"?([^"\n]+)"?/m);
+    return m ? m[1].trim() : undefined;
+  });
+
+  return sources;
+}
+
+function main() {
+  const args = parseArgs(process.argv.slice(2));
+  const root = args.root || REPO_ROOT;
+  const sources = collectVersions(root);
+
+  const errored = sources.filter((s) => s.error);
+  const versions = [...new Set(sources.filter((s) => s.version).map((s) => s.version))];
+
+  // Normalize the tag by stripping exactly one leading `v` (release tags are vX.Y.Z,
+  // file versions are X.Y.Z). Track tag PRESENCE separately from the normalized
+  // value: a bare `v` (or any tag that normalizes to empty / non-semver) must HARD
+  // FAIL, not be mistaken for "no tag supplied" — otherwise a `git tag v` push would
+  // bypass the release gate. This preserves the old "Validate tag matches package
+  // version" guarantee while widening it to every channel.
+  const hasTag = args.tag != null;
+  const tagVersion = hasTag ? args.tag.replace(/^v/, '') : null;
+  const tagValid = hasTag && /^\d+\.\d+\.\d+(-[\w.]+)?$/.test(tagVersion);
+
+  const consistent = errored.length === 0 && versions.length === 1;
+  const tagOk = !hasTag || (tagValid && consistent && versions[0] === tagVersion);
+  const ok = consistent && tagOk;
+
+  if (args.json) {
+    console.log(
+      JSON.stringify(
+        { ok, consistent, hasTag, tagVersion, tagValid, distinctVersions: versions, sources },
+        null,
+        2,
+      ),
+    );
+  } else {
+    const width = Math.max(...sources.map((s) => s.label.length));
+    for (const s of sources) {
+      const val = s.error ? `ERROR: ${s.error}` : s.version;
+      console.log(`  ${s.label.padEnd(width)}  ${val}`);
+    }
+    if (errored.length) {
+      console.error(`\n✗ ${errored.length} version source(s) unreadable.`);
+    } else if (!consistent) {
+      console.error(
+        `\n✗ version drift — ${versions.length} distinct versions: ${versions.join(', ')}`,
+      );
+    } else if (hasTag && !tagValid) {
+      console.error(`\n✗ tag "${args.tag}" does not normalize to a valid semver version`);
+    } else if (!tagOk) {
+      console.error(
+        `\n✗ tag ${args.tag} (→ ${tagVersion}) does not match the file version ${versions[0]}`,
+      );
+    } else {
+      console.log(
+        `\n✓ all version-carrying files agree on ${versions[0]}${tagVersion ? ` (matches tag ${args.tag})` : ''}`,
+      );
+    }
+  }
+
+  process.exit(ok ? 0 : 1);
+}
+
+main();