hypomnema 1.4.0 → 1.4.2

package/commands/feedback.md

@@ -36,10 +36,12 @@ If **claude-learned** is among the targets, the page must be `scope: global` + `
 
 ## Step 2 — List existing feedback (optional)
 
-To check for an existing topic, locate the Hypomnema package root and run:
+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.
+
+To check for an existing topic, run:
 
 ```bash
-node <package-root>/scripts/feedback.mjs --list [--hypo-dir="<path>"]
+node ${CLAUDE_PLUGIN_ROOT}/scripts/feedback.mjs --list [--hypo-dir="<path>"]
 ```
 
 If a matching topic exists, appending adds a dated entry and bumps `updated:` (classification frontmatter is preserved).
@@ -51,7 +53,7 @@ If a matching topic exists, appending adds a dated entry and bumps `updated:` (c
 Run with `--dry-run` first to preview the generated page, then without it to write. Pass every collected field:
 
 ```bash
-node <package-root>/scripts/feedback.mjs \
+node ${CLAUDE_PLUGIN_ROOT}/scripts/feedback.mjs \
   --topic="<slug>" \
   --entry="<one-line rule>" \
   --scope="global|project:<project-id>" \

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

@@ -217,12 +217,92 @@ Before opening:
 4. If you changed a template or `init` flow, a fresh `init` produces the expected vault structure.
 5. README / ARCHITECTURE / docs are updated to match.
 
-Open the PR against `main`. Include:
+Open the PR against `main`. The body is **bilingual**: write the full description twice, once under a `# English` heading and once under a `# 한국어` heading, each carrying the same sections. The `## Changelog` and `## Checklist` blocks are language-neutral, so they appear once, after both language blocks. Do **not** add any tool-attribution footer (no "Generated with ..." line) to the body.
 
-- **What changed** — short summary
-- **Why** — the user-visible motivation
-- **Manual verification steps** — anything the test suite cannot cover
-- **Migration notes** — if upgrading existing installs needs special handling
+Each language block includes:
+
+- **What changed** / **변경 내용**: short summary
+- **Why** / **이유**: the user-visible motivation
+- **How** / **방법**: approach notes that aren't obvious from the diff
+- **Manual verification** / **수동 검증**: anything the test suite cannot cover
+- **Migration notes** / **마이그레이션 노트**: if upgrading existing installs needs special handling (else "None")
+
+After both blocks, language-neutral:
+
+- **Changelog**: one English line plus one Korean line if the change is user-visible (see CHANGELOG conventions below)
+- **Checklist**: the boxes from the PR template
+
+---
+
+## 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.
 
 ---
 
@@ -239,14 +319,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 +338,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 +357,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 +369,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 +390,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/hooks/hypo-auto-minimal-crystallize.mjs

@@ -59,21 +59,33 @@ function emitContinue() {
 }
 
 function emitBlock(sessionId, transcriptPath, gate = null) {
-  // One-line, skill-first. /hypo:crystallize is the documented session-close
-  // alias; passing --session-id there writes the per-session marker that clears
-  // this block. CLI fallback + bypass live in commands/crystallize.md, not here
-  // — keep the Stop reason terse so the actionable instruction stands out.
-  // Surface the transcript path so the close can pass --transcript-path=<path>,
-  // which scopes the marker's lint gate to this session's own files (Bug A
-  // coherence: a marker written without lint would only let Stop pass for
-  // /compact to immediately re-block on the same errors).
-  const transcriptHint = transcriptPath ? ` --transcript-path=${transcriptPath}` : '';
-  const markCmd = `crystallize --mark-session-closed --session-id=${sessionId}${transcriptHint}`;
+  // One-line recovery action. The gate-precise branches below name an EXACT
+  // command so "only the marker is missing" stays a one-shot fix — but that
+  // command must be a runnable `node <pkg>/scripts/crystallize.mjs` invocation,
+  // never a bare `crystallize` (a package.json `bin` that is NOT on PATH in a
+  // plugin install → `command not found`). When PKG_ROOT is
+  // unresolved we cannot build that path, so fall back to the /hypo:crystallize
+  // skill, which resolves its own package root (the same alias the generic
+  // branch uses). Passing --session-id writes the per-session marker that clears
+  // this block. Surface the transcript path so the close can pass
+  // --transcript-path=<path>, which scopes the marker's lint gate to this
+  // session's own files (Bug A coherence: a marker written without lint would
+  // only let Stop pass for /compact to immediately re-block on the same errors).
+  // Quote the paths so the printed command stays copy-paste runnable even when
+  // an install/transcript path contains spaces (display text only — never exec'd
+  // here).
+  const transcriptHint = transcriptPath ? ` --transcript-path="${transcriptPath}"` : '';
+  const cliBase = PKG_ROOT ? `node "${join(PKG_ROOT, 'scripts', 'crystallize.mjs')}"` : null;
+  const markCmd = cliBase
+    ? `${cliBase} --mark-session-closed --session-id=${sessionId}${transcriptHint}`
+    : `/hypo:crystallize (session_id=${sessionId}${transcriptHint})`;
   // The log-only escape hatch for a non-project (wiki/tooling-only)
   // session. Offered ONLY as an explicit alternative when a close blocker is
   // present — never as the default recovery, so a real project session is not
   // taught to bypass the ADR 0043 close invariant (codex design Finding 3).
-  const logOnlyCmd = `crystallize --mark-session-closed --log-only --session-id=${sessionId}${transcriptHint}`;
+  const logOnlyCmd = cliBase
+    ? `${cliBase} --mark-session-closed --log-only --session-id=${sessionId}${transcriptHint}`
+    : `/hypo:crystallize --log-only (session_id=${sessionId}${transcriptHint})`;
   // ADR 0047: refine the message with the read-only /compact gate result.
   // - gate green → the close is compact-ready and ONLY the marker is missing
   //   (the hand-edit close case: files Written + committed directly, bypassing