hypomnema 1.3.4 → 1.4.1

package/commands/feedback.md

@@ -26,6 +26,7 @@ If the user did not provide them, ask. The classification fields are required so
 6. **Targets**: "Where should this project?" → `project-memory` (MEMORY.md) and/or `claude-learned` (global CLAUDE.md). Default `project-memory`.
 7. **Priority** (1–5, higher sorts first; default 3).
 8. **Sensitivity**: `public` (default) or `sanitized` (redacted secrets/paths). `private` is not allowed — the wiki is git-pushed.
+9. **Failure type** (optional): if this correction came from a real failure incident, classify it — `hallucination` | `false-completion` | `process-stall` | `over-caution` | `overreach` | `incompleteness` | `instruction-miss` | `convention-violation`. Omit it for a pure preference or a brand-new convention ("always do X"). When several fit, take the most specific (the list is in precedence order; see SCHEMA §3.1).
 
 If **claude-learned** is among the targets, the page must be `scope: global` + `tier: L1`, and you must also collect:
 - **Global summary**: a one-line summary for the CLAUDE.md learned-behaviors entry.
@@ -35,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).
@@ -50,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>" \
@@ -61,6 +64,7 @@ node <package-root>/scripts/feedback.mjs \
   --memory-summary="<one-line MEMORY.md summary>" \
   --reason="<why this rule exists>" \
   [--global-summary="<one-line CLAUDE.md summary>" --promote-to-global] \
+  [--failure-type="<enum>"] \
   [--source="session:<date>"] \
   [--hypo-dir="<path>"] \
   [--dry-run]
@@ -68,6 +72,8 @@ node <package-root>/scripts/feedback.mjs \
 
 When `--targets` includes `claude-learned`, `--global-summary` and `--promote-to-global` are required (and `--scope=global --tier=L1`).
 
+`--failure-type` is optional (one of the eight values above). On **append** to an existing topic it is set only if the page has none; if the page already carries a different `failure_type` the command errors (a page holds a single failure_type — use a separate topic for a different one). Without the flag, an append leaves the frontmatter untouched as before.
+
 > **`scope: project:<project-id>` 주의.** `<project-id>`는 `feedback-sync`가 resolve한 project-id와 정확히 일치해야 한다 (default: cwd의 `/`,`.` → `-` 치환; `--project-id=<id>` 로 override). 일치하지 않으면 그 페이지는 해당 project의 MEMORY로 projection되지 **않는다** (silent skip — lint error 아님). v1.3.0부터 scope regex(`^(global|project:[A-Za-z0-9_-]+)$`)가 cwd-derived id 형식(`-Users-...`)을 그대로 허용하므로 lint 통과를 위해 `--project-id=<slug>`를 override할 필요는 없다. 단 cwd에 공백 등 `[A-Za-z0-9_-]` 밖 문자가 있으면 그 id는 여전히 거부되니 그때만 `--project-id=<id>`로 override한다.
 
 On a real (non-dry-run) write, the script automatically runs `feedback-sync --write` to refresh MEMORY.md / CLAUDE.md. If that post-step reports drift it prints a one-line warning — the page is still saved; reconcile with `hypomnema feedback-sync --check`.

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/ARCHITECTURE.md

@@ -115,7 +115,7 @@ Hooks run automatically at Claude Code lifecycle events. They are deployed to `~
 | `hypo-personal-check` | PreCompact validation: lint blockers, uncommitted changes, missing session-log entries → block compact |
 | `hypo-auto-stage` | After Write/Edit on a wiki path, run `git add` (skips paths matching `.hypoignore`) |
 | `hypo-hot-rebuild` | At session stop, regenerate root `hot.md` from recent activity; emit growth metrics + cache for next SessionStart |
-| `hypo-session-record` | At session stop, append `{session_id, transcript_path, recorded_at, cwd}` to `.cache/sessions/index.jsonl` (primary source for the observability audit) |
+| `hypo-session-record` | At session stop, append `{session_id, transcript_path, recorded_at, cwd, device}` to `.cache/sessions/index.jsonl` (primary source for the observability audit) |
 | `hypo-auto-commit` | At session stop, filter changed paths through `.hypoignore`, commit non-ignored changes, `git pull --no-rebase` + `git push` (silent fail on missing remote) |
 | `hypo-cwd-change` | When working directory changes, re-resolve the active project and inject its `hot.md` |
 | `hypo-file-watch` | Notify on external wiki edits so the in-session view stays consistent |
@@ -335,7 +335,7 @@ journal/weekly/<YYYY-Www>.md               ← committed report (heuristic v0, s
 
 `session-audit.mjs` reads transcripts from two locations, in priority order:
 
-1. **Primary:** `<hypo-root>/.cache/sessions/index.jsonl` — written by the Stop hook `hypo-session-record.mjs`. Each line: `{ session_id, transcript_path, recorded_at, cwd }`.
+1. **Primary:** `<hypo-root>/.cache/sessions/index.jsonl` — written by the Stop hook `hypo-session-record.mjs`. Each line: `{ session_id, transcript_path, recorded_at, cwd, device }`. `device` (PRAC-17) is `os.hostname()` for multi-machine audit; the index lives under `.cache/` (gitignored in a normal vault) so it is a local-only per-session record.
 2. **Fallback:** `~/.claude/projects/<encoded>/*.jsonl` — scanned when the index is missing or empty (legacy / freshly-installed wikis).
 
 ### Classification
@@ -366,6 +366,8 @@ The score is a **proxy, not ground truth**. The four-week baseline plan (capture
 
 The observability pipeline reads but never republishes raw transcripts. Weekly reports only emit `session_id` plus aggregate counts — no transcript content, no URLs, no tool inputs. Transcripts themselves live under `~/.claude/projects/` or `.cache/sessions/` which `.hypoignore` already excludes from any sync.
 
+**PRAC-17 audit fields (`device`, `session_id`).** `device` (`os.hostname()`) is recorded in two places with different sync boundaries, by design. In `.cache/sessions/index.jsonl` it is per-session-accurate but **local-only** (`.cache/` is gitignored in a normal vault). In the seeded session-log daily-shard frontmatter it is an **intentional synced field** — a creator-only stamp (the session/machine that first created the day's shard), carried across machines so the wiki itself records which machine opened each day. `session_id` (the Claude session UUID) is seeded into that same synced frontmatter, but only on the Stop-chain close path that passes `--session-id`; on manual/skill closes it is omitted. This deliberately puts a hostname (and, on the automated path, the session UUID) into git-tracked, synced content; it is acceptable for a single-user private vault where multi-machine identification is the goal. Operators who do not want a hostname synced can override `os.hostname()` at the OS level or treat the field as a pseudonymous label.
+
 ### Growth metrics (Lane B)
 
 A separate, lightweight counter — distinct from the audit pipeline — runs at every Stop / SessionStart pair:

package/docs/CONTRIBUTING.md

@@ -222,69 +222,192 @@ 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.
 
 ### Cutting a release
 
-Every Hypomnema release must carry a Korean summary alongside the English body
+The maintainer drives this checklist with a personal `/ship` command (it lives in
+`~/.claude/commands/`, alongside `qa-before-ship` — it is maintainer tooling, not
+a shipped plugin command, since an OSS user has no reason to release Hypomnema
+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 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`.
+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).
 node scripts/bump-version.mjs <new-semver>   # e.g. 1.2.2 or 1.3.0-rc.1
 
-# 2. Edit CHANGELOG.md — the new section MUST include a "### 한글 요약"
-#    sub-section with at least 10 Hangul characters of real summary text.
+# 1b. bump-version does NOT touch package-lock.json — sync it so `npm ci` and the
+#     version-consistency gate stay green (the lock carries the version twice).
+npm install --package-lock-only
+
+# 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. Verify locally before tagging (same check that runs in CI)
-node scripts/check-bilingual.mjs --changelog
-
-# 4. Commit
-git add package.json CHANGELOG.md
+# 3. Reconcile BOTH READMEs — add a v<version> sentence to the rolling version
+#    narrative in README.md AND README.ko.md, and update the first-viewport
+#    "current release" pointer. (Dropped 3x historically; check:readme is the floor.)
+$EDITOR README.md README.ko.md
+
+# 4. Verify locally before tagging (the full gate set CI + prepublishOnly run)
+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    # 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
+npm run check:tracker-ids  # no private-tracker pointers leaked into shipped files
+
+# 5. Commit — include EVERY file the bump touched, the READMEs, and the lockfile.
+git add package.json package-lock.json .claude-plugin/ templates/hypo-config.md \
+        CHANGELOG.md README.md README.ko.md
 git commit -m "chore: release v<version>"
+#    Then open the release PR, pass review + green CI, and squash-merge to main.
 
-# 5. Tag 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
 )"
 
-# 6. Verify the tag annotation locally (same check that runs in CI)
+# 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
 
-# 7. Push
-git push origin main --tags
+# 8. Push the SPECIFIC tag alone — NOT --tags (that would push stale local tags
+#    and could trigger releases for versions you did not intend).
+git push origin v<version>
 ```
 
 The `release.yml` workflow then:
 
-1. Verifies the tag matches `package.json` version.
-2. Validates the CHANGELOG section AND the tag annotation are bilingual
-   (`scripts/check-bilingual.mjs`).
-3. Runs `npm test` and `npm run lint`.
-4. Publishes to npm with `npm publish --access public --provenance`.
-
-`NPM_TOKEN` must be set as a repository secret.
+1. Verifies the tag matches the version in EVERY version-carrying file —
+   `package.json`, `package-lock.json`, `.claude-plugin/{plugin,marketplace}.json`,
+   and `templates/hypo-config.md` (`scripts/check-versions.mjs --tag`).
+2. Smokes the plugin channel — manifest, `hooks/hooks.json` targets, and
+   command/skill component files (`scripts/smoke-plugin.mjs`).
+3. Validates the CHANGELOG section AND the tag annotation are bilingual
+   (`scripts/check-bilingual.mjs`), and that the version is present in both
+   READMEs (`scripts/check-readme-version.mjs`).
+4. Runs `npm test` and `npm run lint`.
+5. Publishes to npm with `npm publish --access public --provenance` and creates
+   the GitHub Release from the tag body.
+
+`NPM_TOKEN` must be set as a repository secret. After rotating it, run the
+`release.yml` `workflow_dispatch` "publish credential pre-check" — it verifies the
+token authenticates without publishing anything.
 
 ### Versioning rules
 

package/hooks/hypo-auto-commit.mjs

@@ -6,14 +6,10 @@
  */
 
 import { spawnSync } from 'child_process';
-import { HYPO_DIR, appendSyncFailure, commitWikiChanges } from './hypo-shared.mjs';
-
-function git(...args) {
-  return spawnSync('git', ['-C', HYPO_DIR, ...args], { encoding: 'utf-8', timeout: 30000 });
-}
+import { HYPO_DIR, syncRemote, commitWikiChanges } from './hypo-shared.mjs';
 
 function hasRemote() {
-  const r = git('remote');
+  const r = spawnSync('git', ['-C', HYPO_DIR, 'remote'], { encoding: 'utf-8', timeout: 30000 });
   return (r.stdout || '').trim().length > 0;
 }
 
@@ -28,12 +24,10 @@ if (!result.committed) {
 
 if (hasRemote()) {
   // pull/push failures must not stop the session, but they can no longer be
-  // swallowed silently — record each to .cache/sync-state.json so session-start
-  // and doctor can surface them next session.
-  const pull = git('pull', '--no-rebase', '-q');
-  if (pull.status !== 0) appendSyncFailure(HYPO_DIR, 'pull', pull.stderr || pull.stdout);
-  const push = git('push');
-  if (push.status !== 0) appendSyncFailure(HYPO_DIR, 'push', push.stderr || push.stdout);
+  // swallowed silently — syncRemote records each to .cache/sync-state.json and,
+  // on a merge conflict, aborts the merge so the tree is never left half-merged
+  // (FEAT-17 hardening). session-start + doctor surface the result next session.
+  syncRemote(HYPO_DIR);
 }
 
 console.log(JSON.stringify({ continue: true, suppressOutput: true }));

package/hooks/hypo-session-record.mjs

@@ -12,6 +12,7 @@
 
 import { existsSync, mkdirSync, appendFileSync } from 'fs';
 import { dirname, join } from 'path';
+import { hostname } from 'os';
 import { HYPO_DIR } from './hypo-shared.mjs';
 
 const INDEX_PATH = join(HYPO_DIR, '.cache', 'sessions', 'index.jsonl');
@@ -50,6 +51,10 @@ process.stdin.on('end', () => {
       transcript_path: transcriptPath,
       recorded_at: new Date().toISOString(),
       cwd: payload.cwd || process.cwd(),
+      // PRAC-17: machine identity for multi-machine audit. index.jsonl lives
+      // under .cache/ (gitignored in a normal vault), so this is a LOCAL-only
+      // per-session record — accurate for every session, no sync/privacy cost.
+      device: hostname() || 'unknown',
     };
     appendFileSync(INDEX_PATH, JSON.stringify(entry) + '\n');
   } catch (err) {

package/hooks/hypo-session-start.mjs

@@ -243,6 +243,13 @@ function syncStateNotice(pullOk) {
     return '';
   }
   const last = entries[entries.length - 1];
+  if (last.op === 'conflict') {
+    return (
+      `[WIKI: remote diverged — auto-merge was aborted to protect your edits ` +
+      `(your local work is committed and safe; the other machine's version is on the remote). ` +
+      `Resolve manually: \`git -C ${HYPO_DIR} pull --no-rebase\`, fix conflicts, then push.]`
+    );
+  }
   return `[WIKI: last sync failed: ${last.op || '?'} — ${last.error || 'unknown'}]`;
 }
 const GLOBAL_HOT = join(HYPO_DIR, 'hot.md');