hypomnema 1.4.0 → 1.4.1

package/commands/graph.md

@@ -12,9 +12,9 @@ You are running `/hypo:graph`. Generate a link dependency graph from wiki pages.
 
 ---
 
-## Step 1 — Locate package root
+## Step 1 — Run script
 
-Locate the Hypomnema package root (the directory containing this file's parent `commands/`).
+The script path below resolves via `${CLAUDE_PLUGIN_ROOT}`, which the plugin harness expands to this package's absolute path before you see it, so run it as written. If it appears unexpanded (a literal `${CLAUDE_PLUGIN_ROOT}`), read the package root from the `hypo@hypomnema` installPath in `~/.claude/plugins/installed_plugins.json` rather than guessing from the cache layout.
 
 If the user specified a Hypomnema directory, pass it as `--hypo-dir="<path>"`. Otherwise omit the flag.
 
@@ -23,7 +23,7 @@ If the user specified a Hypomnema directory, pass it as `--hypo-dir="<path>"`. O
 ## Step 2 — Run the graph script
 
 ```bash
-node <package-root>/scripts/graph.mjs \
+node ${CLAUDE_PLUGIN_ROOT}/scripts/graph.mjs \
   [--hypo-dir="<path>"] \
   [--format=json|mermaid|dot] \
   [--min-edges=<n>]

package/commands/ingest.md

@@ -27,18 +27,20 @@ Do **not** fetch the URL or read the file yet — the privacy guard in Step 2 mu
 
 ## Step 2 — Privacy guard (`.hypoignore`)
 
-Refuse to ingest secrets (`.env`, SSH keys, credentials) before they ever reach `sources/`. Locate the Hypomnema package root and run the guard for **both** the input path and the destination path:
+The script paths below resolve via `${CLAUDE_PLUGIN_ROOT}`, which the plugin harness expands to this package's absolute path before you see it, so run them as written. If one appears unexpanded (a literal `${CLAUDE_PLUGIN_ROOT}`), read the package root from the `hypo@hypomnema` installPath in `~/.claude/plugins/installed_plugins.json` rather than guessing from the cache layout.
+
+Refuse to ingest secrets (`.env`, SSH keys, credentials) before they ever reach `sources/`. Run the guard for **both** the input path and the destination path:
 
 1. **If the source is a file path**, check it (use an absolute path):
 
    ```bash
-   node <package-root>/scripts/ingest.mjs [--hypo-dir="<path>"] --check="<absolute-input-path>"
+   node ${CLAUDE_PLUGIN_ROOT}/scripts/ingest.mjs [--hypo-dir="<path>"] --check="<absolute-input-path>"
    ```
 
 2. **Always** check the destination `sources/<slug>.<ext>`:
 
    ```bash
-   node <package-root>/scripts/ingest.mjs [--hypo-dir="<path>"] --check="sources/<slug>.<ext>"
+   node ${CLAUDE_PLUGIN_ROOT}/scripts/ingest.mjs [--hypo-dir="<path>"] --check="sources/<slug>.<ext>"
    ```
 
 If either command exits non-zero, **stop**: surface the `Refused: ...` message to the user and do not fetch, read, or save the source. The slug check matters because a user could rename a `.env` to an innocuous slug — the destination must still be blocked.
@@ -50,7 +52,7 @@ If either command exits non-zero, **stop**: surface the `Refused: ...` message t
 Run the ingest helper to surface existing orphaned sources:
 
 ```bash
-node <package-root>/scripts/ingest.mjs [--hypo-dir="<path>"]
+node ${CLAUDE_PLUGIN_ROOT}/scripts/ingest.mjs [--hypo-dir="<path>"]
 ```
 
 If there are orphaned sources already in `sources/`, ask: "There are N unprocessed sources — do you want to ingest one of those instead?"

package/commands/init.md

@@ -43,10 +43,12 @@ Ask the following questions **one at a time**. Use the default if the user press
 
 ## Step 2a — From Remote (skip wizard) {#step-2a}
 
+The script path below resolves via `${CLAUDE_PLUGIN_ROOT}`, which the plugin harness expands to this package's absolute path before you see it, so run it as written. If it appears unexpanded (a literal `${CLAUDE_PLUGIN_ROOT}`), read the package root from the `hypo@hypomnema` installPath in `~/.claude/plugins/installed_plugins.json` rather than guessing from the cache layout.
+
 If the user provided `--from-remote <url>`, run:
 
 ```bash
-node <package-root>/scripts/init.mjs \
+node ${CLAUDE_PLUGIN_ROOT}/scripts/init.mjs \
   --from-remote="<url>" \
   --hypo-dir="<hypo-dir>" \
   [--no-hooks] \
@@ -62,11 +64,11 @@ node <package-root>/scripts/init.mjs \
 
 ## Step 2 — Run the init script (new wiki)
 
-Locate the Hypomnema package root (the directory containing this file's parent `commands/`).
+The script path below resolves via `${CLAUDE_PLUGIN_ROOT}`, which the plugin harness expands to this package's absolute path before you see it, so run it as written. If it appears unexpanded (a literal `${CLAUDE_PLUGIN_ROOT}`), read the package root from the `hypo@hypomnema` installPath in `~/.claude/plugins/installed_plugins.json` rather than guessing from the cache layout.
 Then run:
 
 ```bash
-node <package-root>/scripts/init.mjs \
+node ${CLAUDE_PLUGIN_ROOT}/scripts/init.mjs \
   --hypo-dir="<hypo-dir>" \
   [--no-hooks] \
   [--codex] \

package/commands/lint.md

@@ -14,9 +14,9 @@ You are running `/hypo:lint`. Validate all wiki pages for frontmatter correctnes
 
 ---
 
-## Step 1 — Locate package root
+## Step 1 — Run script
 
-Locate the Hypomnema package root (the directory containing this file's parent `commands/`).
+The script path below resolves via `${CLAUDE_PLUGIN_ROOT}`, which the plugin harness expands to this package's absolute path before you see it, so run it as written. If it appears unexpanded (a literal `${CLAUDE_PLUGIN_ROOT}`), read the package root from the `hypo@hypomnema` installPath in `~/.claude/plugins/installed_plugins.json` rather than guessing from the cache layout.
 
 If the user specified a Hypomnema directory, pass it as `--hypo-dir="<path>"`. Otherwise omit the flag and the script resolves the Hypomnema root automatically via `HYPO_DIR` → `hypo-config.md` scan → `~/hypomnema`.
 
@@ -25,7 +25,7 @@ If the user specified a Hypomnema directory, pass it as `--hypo-dir="<path>"`. O
 ## Step 2 — Run lint
 
 ```bash
-node <package-root>/scripts/lint.mjs [--hypo-dir="<path>"] [--json] [--fix]
+node ${CLAUDE_PLUGIN_ROOT}/scripts/lint.mjs [--hypo-dir="<path>"] [--json] [--fix]
 ```
 
 Options:

package/commands/query.md

@@ -18,14 +18,14 @@ Ask the user what they want to know if it was not provided in the command invoca
 
 ---
 
-## Step 2 — Locate package root and search
+## Step 2 — Search
 
-Locate the Hypomnema package root (the directory containing this file's parent `commands/`).
+The script path below resolves via `${CLAUDE_PLUGIN_ROOT}`, which the plugin harness expands to this package's absolute path before you see it, so run it as written. If it appears unexpanded (a literal `${CLAUDE_PLUGIN_ROOT}`), read the package root from the `hypo@hypomnema` installPath in `~/.claude/plugins/installed_plugins.json` rather than guessing from the cache layout.
 
 Run full-text search:
 
 ```bash
-node <package-root>/scripts/query.mjs \
+node ${CLAUDE_PLUGIN_ROOT}/scripts/query.mjs \
   --q="<query terms>" \
   [--hypo-dir="<path>"] \
   [--limit=10]

package/commands/rename.md

@@ -14,9 +14,9 @@ You are running `/hypo:rename`. Move a page or directory and content-aware rewri
 
 ---
 
-## Step 1 — Locate package root
+## Step 1 — Run script
 
-Locate the Hypomnema package root (the directory containing this file's parent `commands/`).
+The script path below resolves via `${CLAUDE_PLUGIN_ROOT}`, which the plugin harness expands to this package's absolute path before you see it, so run it as written. If it appears unexpanded (a literal `${CLAUDE_PLUGIN_ROOT}`), read the package root from the `hypo@hypomnema` installPath in `~/.claude/plugins/installed_plugins.json` rather than guessing from the cache layout.
 
 If the user specified a Hypomnema directory, pass it as `--hypo-dir="<path>"`. Otherwise omit the flag.
 
@@ -27,7 +27,7 @@ If the user specified a Hypomnema directory, pass it as `--hypo-dir="<path>"`. O
 Always run the dry-run (no `--apply`) before writing anything:
 
 ```bash
-node <package-root>/scripts/rename.mjs \
+node ${CLAUDE_PLUGIN_ROOT}/scripts/rename.mjs \
   [--hypo-dir="<path>"] \
   --from=<slug|rel|dir> \
   --to=<slug|rel|dir> \
@@ -61,7 +61,7 @@ If the result is `ok: false`:
 Once the user confirms the dry-run looks right, re-run with `--apply`:
 
 ```bash
-node <package-root>/scripts/rename.mjs \
+node ${CLAUDE_PLUGIN_ROOT}/scripts/rename.mjs \
   [--hypo-dir="<path>"] \
   --from=<slug|rel|dir> \
   --to=<slug|rel|dir> \

package/commands/resume.md

@@ -14,12 +14,14 @@ You are running `/hypo:resume`. Load the session state for an active project and
 
 ## Step 1 — Resolve project
 
-If the user named a project in the command invocation, use that. Otherwise, locate the Hypomnema package root and run:
+If the user named a project in the command invocation, use that. Otherwise, run:
 
 ```bash
-node <package-root>/scripts/resume.mjs [--hypo-dir="<path>"] [--project=<name>]
+node ${CLAUDE_PLUGIN_ROOT}/scripts/resume.mjs [--hypo-dir="<path>"] [--project=<name>]
 ```
 
+The plugin harness expands `${CLAUDE_PLUGIN_ROOT}` to this package's absolute path before you see it, so run the command as written. If it appears unexpanded (a literal `${CLAUDE_PLUGIN_ROOT}`), read the package root from the `hypo@hypomnema` installPath in `~/.claude/plugins/installed_plugins.json` rather than guessing from the cache layout.
+
 When `--project` is omitted, the script prefers the project whose `working_dir` contains the current directory (cwd-first); if nothing under the current directory matches, it falls back to the most recently active project from `hot.md`.
 
 ---

package/commands/stats.md

@@ -13,9 +13,9 @@ You are running `/hypo:stats`. Display a summary of wiki health and activity.
 
 ---
 
-## Step 1 — Locate package root
+## Step 1 — Run script
 
-Locate the Hypomnema package root (the directory containing this file's parent `commands/`).
+The script path below resolves via `${CLAUDE_PLUGIN_ROOT}`, which the plugin harness expands to this package's absolute path before you see it, so run it as written. If it appears unexpanded (a literal `${CLAUDE_PLUGIN_ROOT}`), read the package root from the `hypo@hypomnema` installPath in `~/.claude/plugins/installed_plugins.json` rather than guessing from the cache layout.
 
 If the user specified a Hypomnema directory, pass it as `--hypo-dir="<path>"`. Otherwise omit the flag.
 
@@ -24,7 +24,7 @@ If the user specified a Hypomnema directory, pass it as `--hypo-dir="<path>"`. O
 ## Step 2 — Run the stats script
 
 ```bash
-node <package-root>/scripts/stats.mjs [--hypo-dir="<path>"] [--json]
+node ${CLAUDE_PLUGIN_ROOT}/scripts/stats.mjs [--hypo-dir="<path>"] [--json]
 ```
 
 ---

package/commands/upgrade.md

@@ -12,9 +12,9 @@ You are running `/hypo:upgrade`. Check if the installed Hypomnema wiki is out of
 
 ---
 
-## Step 1 — Locate package root
+## Step 1 — Run script
 
-Locate the Hypomnema package root (the directory containing this file's parent `commands/`).
+The script path below resolves via `${CLAUDE_PLUGIN_ROOT}`, which the plugin harness expands to this package's absolute path before you see it, so run it as written. If it appears unexpanded (a literal `${CLAUDE_PLUGIN_ROOT}`), read the package root from the `hypo@hypomnema` installPath in `~/.claude/plugins/installed_plugins.json` rather than guessing from the cache layout.
 
 If the user specified a Hypomnema directory, pass it as `--hypo-dir="<path>"`. Otherwise omit the flag.
 
@@ -23,7 +23,7 @@ If the user specified a Hypomnema directory, pass it as `--hypo-dir="<path>"`. O
 ## Step 2 — Run upgrade check
 
 ```bash
-node <package-root>/scripts/upgrade.mjs [--hypo-dir="<path>"]
+node ${CLAUDE_PLUGIN_ROOT}/scripts/upgrade.mjs [--hypo-dir="<path>"]
 ```
 
 Show the output verbatim.
@@ -54,7 +54,7 @@ If there is anything to update, ask the user:
 
 - If **yes** → run with `--apply`:
   ```bash
-  node <package-root>/scripts/upgrade.mjs [--hypo-dir="<path>"] --apply
+  node ${CLAUDE_PLUGIN_ROOT}/scripts/upgrade.mjs [--hypo-dir="<path>"] --apply
   ```
 - If **no** → tell the user they can apply later by running `/hypo:upgrade` again.
 

package/commands/verify.md

@@ -11,12 +11,12 @@ You are running `/hypo:verify`. Audit wiki pages for overdue or missing `verify_
 
 ---
 
-## Step 1 — Locate package root and run
+## Step 1 — Run
 
-Locate the Hypomnema package root (the directory containing this file's parent `commands/`).
+The script path below resolves via `${CLAUDE_PLUGIN_ROOT}`, which the plugin harness expands to this package's absolute path before you see it, so run it as written. If it appears unexpanded (a literal `${CLAUDE_PLUGIN_ROOT}`), read the package root from the `hypo@hypomnema` installPath in `~/.claude/plugins/installed_plugins.json` rather than guessing from the cache layout.
 
 ```bash
-node <package-root>/scripts/verify.mjs [--hypo-dir="<path>"] [--file=<path>]
+node ${CLAUDE_PLUGIN_ROOT}/scripts/verify.mjs [--hypo-dir="<path>"] [--file=<path>]
 ```
 
 Options:

package/docs/CONTRIBUTING.md

@@ -222,10 +222,83 @@ Open the PR against `main`. Include:
 - **What changed** — short summary
 - **Why** — the user-visible motivation
 - **Manual verification steps** — anything the test suite cannot cover
+- **Changelog**: one English line plus one Korean line if the change is user-visible (see CHANGELOG conventions below)
 - **Migration notes** — if upgrading existing installs needs special handling
 
 ---
 
+## CHANGELOG conventions
+
+`CHANGELOG.md` is the source of truth for release history. It follows a fixed section model, and contributors feed it through the `## Changelog` block in the PR template rather than editing `CHANGELOG.md` directly. The release collector and the maintainer assemble the final entries at release time.
+
+### PR title vs. merge commit
+
+- **PR title**: Conventional Commits plus a scope, e.g. `feat(feedback): add failure_type enum`. The type drives the CHANGELOG section (see the classification table below).
+- **Merge commit**: the squash-merge subject carries the PR number (`#123`). That is where `#N` comes from, not the PR title. The two conventions stay separate.
+- Internal tracker ids (`FEAT-`, `IMPR-`, `ISSUE-`, `PRAC-`) may appear in your local notes and in source or workflow comments (an internal reference, like an ADR anchor), but never on the published changelog and release surface: not in the CHANGELOG body, not in the PR `## Changelog` block, not in a tag annotation, not in a GitHub Release. The only identifier that ships in those is the PR number `#N`. `check-tracker-ids --tag` gates the tag body; the migration keeps the CHANGELOG body clean.
+
+### The `## Changelog` block
+
+If a change is user-visible, fill the `## Changelog` block in the PR body with one English line and one Korean line:
+
+```
+## Changelog
+
+- EN: Feedback pages accept an optional `failure_type` so recurring mistakes are visible.
+- KO: 피드백 페이지에 선택적 `failure_type`를 달아 반복되는 실수를 집계로 볼 수 있습니다.
+```
+
+- Reference the PR by number only (`#123`). No internal tracker ids on this surface.
+- No em dashes; use a colon, comma, or parentheses.
+- Internal-only changes (a refactor with no user-visible effect, test-only, CI plumbing) write `None` and skip the lines.
+
+### Section model
+
+Each version block in `CHANGELOG.md` is ordered, top to bottom:
+
+1. Optional `> [!IMPORTANT]` migration or breaking callout.
+2. `### New Features`, `### Bug Fixes`, `### Chores`: present only when that version has a user-relevant entry of that kind. An empty section is omitted. Keep each entry to one compact line; split or trim anything that runs to multiple sentences. Describe only what a user sees: purely internal work (release tooling, contributor docs, a refactor with no user-visible effect) gets no prose entry and lives in the `### Changelog` index alone.
+3. `### Changelog`: the PR-link index plus contributors. Always present. Language-neutral. It lists every merged PR, internal ones included.
+
+At and after the v1.2.0 cutoff, each non-empty gated section (`New Features`, `Bug Fixes`, `Chores`) splits its content into `#### English` then `#### 한국어`, in that order:
+
+```
+### New Features
+#### English
+- Feedback pages accept an optional `failure_type`. (#141)
+#### 한국어
+- 피드백 페이지가 선택적 `failure_type`를 받습니다. (#141)
+```
+
+Versions below the v1.2.0 cutoff (1.0.0, 1.0.1, 1.1.0) are English-only: the English body sits directly under the section header with no `####` sub-blocks. Korean is not back-filled for those releases.
+
+The `### Changelog` index is language-neutral, one merged PR per line:
+
+```
+### Changelog
+- #141 feedback failure_type classification
+- #140 invalid-YAML lint guard
+Contributors: @handle
+```
+
+Each line is `- #N <short title>`, no em dash. The `Contributors:` line lists that version's PR authors, de-duplicated; the release collector fills the handles from the GitHub API.
+
+A `### Known Issues` or `### Notes` block, when a version has one, is a trailing note (a caveat, not a change). It is not one of the gated sections, so it carries no `####` sub-blocks even at or after the cutoff; bilingual text there is recommended, not enforced.
+
+### Classification
+
+The section is decided by change kind, with the Conventional Commit type as the default and content as the override:
+
+| Input | Section |
+|---|---|
+| `feat:` / `FEAT-` | New Features |
+| `fix:` / `ISSUE-` | Bug Fixes |
+| `chore:` / `refactor:` / `docs:` / `ci:` / `perf:` / `IMPR-` / `PRAC-` | Chores |
+
+Chores is defined by kind, not by visibility: improvements (`IMPR`), refactors, and release or internal cleanup all land in Chores even when user-visible. The external changelog highlights only New Features and Bug Fixes; everything else is a Chore.
+
+---
+
 ## Release process
 
 Hypomnema uses semver. Releases are automated via `release.yml` on `v*` tag push.
@@ -239,14 +312,16 @@ itself). The sequence below is that same checklist, and is the authoritative
 in-repo reference; follow it whether or not you have the `/ship` convenience
 command.
 
-Every Hypomnema release must carry a Korean summary alongside the English body
+Every Hypomnema release must carry Korean alongside the English body
 in **both** the CHANGELOG section AND the git tag annotation. The release
-workflow enforces this with `scripts/check-bilingual.mjs`; lightweight tags or
-a missing `### 한글 요약` section will block `npm publish`. It also requires the
+workflow enforces this with `scripts/check-bilingual.mjs`; a lightweight tag, or
+a gated CHANGELOG section missing its `#### 한국어` sub-block, will block `npm publish`. It also requires the
 release version to appear in **both** `README.md` and `README.ko.md`
 (`scripts/check-readme-version.mjs`) — the floor that stops the README reconcile
 from being dropped.
 
+Prerequisite: the changelog collector in step 2 reads merged-PR data through the GitHub CLI, so have `gh` installed and authenticated (`gh auth status`) before you start. It is a maintainer-only release script and is not shipped to npm.
+
 ```bash
 # 1. Bump the version across package.json, plugin.json, marketplace.json,
 #    and templates/hypo-config.md. Takes a concrete semver (not patch/minor/major).
@@ -256,8 +331,14 @@ node scripts/bump-version.mjs <new-semver>   # e.g. 1.2.2 or 1.3.0-rc.1
 #     version-consistency gate stay green (the lock carries the version twice).
 npm install --package-lock-only
 
-# 2. Edit CHANGELOG.md — the new section MUST include a "### 한글 요약"
-#    sub-section with at least 10 Hangul characters of real summary text.
+# 2. Draft the new CHANGELOG.md section from the merged PRs' `## Changelog`
+#    blocks (see CHANGELOG conventions above). The collector prints a draft for
+#    the range since the last tag; paste it, then finalize the wording by hand,
+#    dropping any entry that is not user-relevant. --strict fails if any PR lacks
+#    a usable block.
+node scripts/collect-changelog.mjs --strict   # maintainer-only; not shipped to npm
+#    Each gated section (New Features / Bug Fixes / Chores) MUST carry both a
+#    "#### English" and a "#### 한국어" sub-block; check:bilingual enforces it.
 $EDITOR CHANGELOG.md
 
 # 3. Reconcile BOTH READMEs — add a v<version> sentence to the rolling version
@@ -269,7 +350,7 @@ $EDITOR README.md README.ko.md
 npm test                   # unit suite
 npm run lint               # vault linter
 npm run check:versions     # all version-carrying files (incl. package-lock) agree
-npm run check:bilingual    # CHANGELOG section has a 한글 요약
+npm run check:bilingual    # each gated CHANGELOG section has #### English + #### 한국어
 npm run check:readme       # v<version> present in BOTH READMEs
 npm run smoke:plugin       # plugin manifest + hooks/commands/skills load-valid
 npm run smoke-pack         # packed tarball installs and resolves
@@ -281,17 +362,19 @@ git add package.json package-lock.json .claude-plugin/ templates/hypo-config.md
 git commit -m "chore: release v<version>"
 #    Then open the release PR, pass review + green CI, and squash-merge to main.
 
-# 6. Tag the merge commit with an ANNOTATED tag — never a lightweight tag.
+# 6. Tag the merge commit with an ANNOTATED tag, never a lightweight tag.
 #    Annotation body shape: English summary, then "---" on its own line,
-#    then a Korean summary block.
+#    then a Korean summary block. The GitHub Release republishes this body
+#    verbatim, so keep it on the same public surface as the CHANGELOG: PR
+#    numbers (#N) only, no internal tracker ids (check-tracker-ids --tag gates it).
 git tag -a v<version> -m "$(cat <<'EOF'
-Hypomnema v<version> — <one-line English summary>
+Hypomnema v<version>: <one-line English summary>
 
-<a few lines of English body — what shipped, links, etc.>
+<a few lines of English body: what shipped, links, etc.>
 
 ---
 
-Hypomnema v<version> — <한 줄 한글 요약>
+Hypomnema v<version>: <한 줄 한글 요약>
 
 <몇 줄의 한글 요약 본문.>
 EOF
@@ -300,6 +383,7 @@ EOF
 # 7. Rehearse the release locally (same checks CI runs against the tag)
 node scripts/check-bilingual.mjs --tag v<version>
 node scripts/check-versions.mjs --tag v<version>
+node scripts/check-tracker-ids.mjs --tag v<version>   # no tracker ids leak into the tag body
 npm publish --dry-run --access public   # packs + prepublishOnly, NO registry PUT
 
 # 8. Push the SPECIFIC tag alone — NOT --tags (that would push stale local tags

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hypomnema",
-  "version": "1.4.0",
+  "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/",

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-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 {