hypomnema 1.8.2 → 1.8.4

package/README.md

@@ -265,7 +265,7 @@ Nine commands cover the full capture → retrieval → consolidation cycle.
 
 Both PostToolUse hooks are registered without a matcher and filter on `tool_name` themselves.
 
-All hooks resolve the wiki root via `HYPO_DIR` env → `hypo-config.md` scan → `~/hypomnema` default, and share `hypo-shared.mjs` (declared via `hooks.json`'s `shared` field).
+All hooks resolve the wiki root via `HYPO_DIR` env → `hypo-config.md` scan → `~/hypomnema` default, and share `hypo-shared.mjs` (declared in `hooks/shared.json`, a JSON array of `.mjs` basenames).
 
 When the Stop hook's pull hits a merge conflict it aborts the merge, skips the push, and records the failure. Your local commits are safe, but the machines stop converging until you act: `git -C <your wiki> pull --no-rebase`, fix the conflicts, commit, push. `/hypo:doctor` surfaces a stuck sync.
 
@@ -386,7 +386,7 @@ Place a `hypo-config.md` at the wiki root to make it portable across machines wi
 
 `.hypoignore` controls which paths the hooks ignore (default: `*.pdf`, `*.zip`, `*.pem`, `.env*`, `*credentials*`, `*secret*`, `*token*`, `*password*`, `*passwd*`, …). Edit it directly; there is no privacy mode flag. One file, one source of truth.
 
-> `init` also installs a pre-commit hook into the wiki repo at `<wiki>/.git/hooks/pre-commit`, marked `# hypo-managed:pre-commit:*`. It refuses any commit that stages a path matching `.hypoignore`; unstage the file, or override with `git commit --no-verify`. The hook embeds the absolute path of the installed package, so if you move or reinstall Hypomnema, this path goes stale and every wiki commit fails. `hypomnema upgrade --apply` (or `/hypo:upgrade`, confirming the apply step, on a plugin install) repoints it in most cases, since a plugin-channel version bump is exactly the case it is built to detect; re-run `hypomnema init` when `upgrade --apply` cannot, which happens for a manual/npm install running alongside an enabled plugin whose active root it cannot positively resolve, or when the vault itself (not just the package) has moved, since `upgrade` only ever corrects the embedded root, never the embedded `--hypo-dir`. `uninstall --apply` removes this hook, resolving the vault the same way `init` does (`--hypo-dir=<path>` to override); it only removes a hook that still carries the marker and no content outside it, so a hook you have since edited by hand is left in place. Pass `--keep-wiki-hook` to skip this wiki hook cleanup (the rest of the uninstall still runs).
+> `init` also installs a pre-commit hook into the wiki repo at `<wiki>/.git/hooks/pre-commit`, marked `# hypo-managed:pre-commit:*`. It refuses any commit that stages a path matching `.hypoignore`; unstage the file, or override with `git commit --no-verify`. The hook does not bake in an install path: it resolves the active Hypomnema install itself, at commit time, from `~/.claude/hypo-pkg.json`'s `pkgRoot` and, failing that, the plugin registry (`~/.claude/plugins/installed_plugins.json`, both the `hypo@hypomnema` and the legacy `hypomnema@hypomnema` entries, user-scope first). A candidate only counts when it is an absolute path whose `package.json` names `hypomnema` and carries a version, and whose script is actually there — anything looser and a `pkgRoot` you did not write could run in your vault. When nothing resolves, it refuses the commit and prints what it checked and how to fix it, rather than silently skip the `.hypoignore` guard. Resolving this way costs a second Node start per step, about 80ms, so a `--lint-strict` vault pays roughly 165ms per commit. A hook an older release wrote may still carry the version-pinned form (an absolute install path baked in at `init` time, which goes stale on every move or reinstall); `hypomnema upgrade --apply` (or `/hypo:upgrade`, confirming the apply step, on a plugin install) migrates it onto the self-resolving form, even when the baked-in path no longer exists on disk. A hook whose body cannot be recognized at all (hand-edited, corrupted) is different: `doctor` and `upgrade` both warn about it instead of touching it, and the fix is `hypomnema init --force-commands` (or the plugin's `/hypo:init --force-commands`) to reinstall the guard, not `upgrade --apply`. Moving the vault itself, not just the package, still needs a fresh `hypomnema init`: `upgrade` only ever fixes the install-root resolution, never a `--hypo-dir` a `--lint-strict` hook already baked in. `uninstall --apply` removes this hook, resolving the vault the same way `init` does (`--hypo-dir=<path>` to override); it only removes a hook that still carries the marker and no content outside it, so a hook you have since edited by hand is left in place. Pass `--keep-wiki-hook` to skip this wiki hook cleanup (the rest of the uninstall still runs).
 
 > The credential-style patterns above are substring globs, so an ordinary page such as `pages/oauth-token-refresh.md` is matched too: it is never injected by any hook, and the wiki pre-commit hook refuses to commit it. If you write about these topics, narrow the patterns or rename the page.
 

package/commands/crystallize.md

@@ -61,7 +61,9 @@ Field rules:
 
 Notes:
 
-- `sessionState` / `projectHot` / `rootHot` / `openQuestions` are **overwrite** (full-file content). `sessionLog` / `log` are **append** (entry-level idempotency — exact-entry dedup, safe to re-run).
+- `sessionState` / `projectHot` / `rootHot` / `openQuestions` are **overwrite** (full-file content); `sessionLog` / `log` are **append** (entry-level idempotency, exact-entry dedup, safe to re-run).
+- **Overwrite means overwrite: whatever you did not carry into the payload is gone.** A single session's close can legitimately touch only one thread of a file that tracks several (a project running two or three tracks in parallel is normal). Before composing an overwrite field, read the CURRENT on-disk file and carry forward every `##` section this session did not touch, verbatim; do not reconstruct a section from memory or drop it because this session had nothing new to add to it. This session's own edits go on top of that, not in place of it.
+- Apply enforces the same rule mechanically: if an overwrite field's payload drops 2 or more of the file's existing `##` sections, apply withholds that field (parks it exactly like a base conflict, as a proposal artifact a human reviews and can force through) rather than writing it. If you are deliberately consolidating or retiring sections on purpose (the user asked for it, or the sections genuinely no longer apply), add `"restructure": true` next to that field's `"content"` to say so explicitly; it only waives the check for that one field, not the whole payload. A waiver that actually waived something, not just a `true` set on a field that never dropped anything, shows up in the result's `restructureWaivers[]` (see Step 4's close-result reporting).
 - Frontmatter `updated:` is NOT auto-fixed. If your payload's `updated:` is stale, the post-apply verification gate will fail with `stage='post-apply-verification'` and you must fix the payload and retry.
 - Write the payload to a **session-scoped** temp path, e.g. `/tmp/hypo-session-close-<session-id>.json`, using the same `<session-id>` you pass below. A date-based path (`<YYYY-MM-DD>`) collides when two sessions close on the same day: the second write silently overwrites the first, and the wrong payload gets applied. The `sessionId` field above is the second line of defense if a path is ever reused anyway.
 
@@ -163,6 +165,9 @@ The result JSON includes a `stage` field when `ok: false`. Branch on it:
 | `post-apply-verification` | A mandatory file's `updated:` frontmatter is stale (≠ today) after apply. | Edit the payload's stale `content` (or supply correct `date`), then re-run. Writes are idempotent — re-applying a corrected payload is safe. |
 | `post-apply-lint` | The payload introduced an error-level lint blocker in a payload file (malformed body / bad frontmatter), or lint crashed. | Fix the offending content in the payload, then re-run. (Broken wikilinks are W4 warnings — not gated.) |
 | `post-apply-verification+lint` | Both above. | Fix both; re-run. |
+| `proposal-pending` (overwrite park) | At least one overwrite field drifted from this session's observed base, or its payload dropped 2 or more of an existing file's `##` sections without `restructure: true`. Each withheld field appears in `conflicts[]` with a `reason` code and a `why` (a ready-to-read sentence naming the cause, reuse it verbatim, don't reword it), and is parked as a `.cache/proposals/<id>.json` artifact; `proposals[]` lists the id, target, and path for every one. The target on disk is untouched. Other, non-conflicting fields in the same payload may already be on disk but uncommitted (`partialConflict: true`, `appliedUncommitted`). | Do not touch the parked file yourself, and do not tell the user to run `hypomnema proposal apply <id>`: that command reads from a TTY and is refused outright in this environment (no terminal attached). Use the transcript-approved path instead. Run `node ${CLAUDE_PLUGIN_ROOT}/scripts/proposal.mjs challenge --session-id=<current-session-id> --ids=<comma-separated ids from proposals[]>`. It prints a diff per target and mints a nonce; tell the user the exact line it prints (`apply-proposals <nonce>`, read the nonce off that output, never invent or reuse one), and once they have typed it back in the conversation, run `node ${CLAUDE_PLUGIN_ROOT}/scripts/proposal.mjs resolve --session-id=<current-session-id>` to apply the approved batch. `node ${CLAUDE_PLUGIN_ROOT}/scripts/proposal.mjs list` and `... discard <id>` (drop a proposal without applying it) both work with no TTY. Once resolved, re-run the same close; it is idempotent. |
+| `proposal-pending` (append lock timeout) | An append field (`sessionLog` or `log`) could not take its file lock within the timeout (default 5s), usually a concurrent close holding the same target. Nothing is parked for it: it carries `kind: 'append'` in `conflicts[]` and never appears in `proposals[]`. | This is transient, not a review case. Do not run any `proposal` subcommand for it, there is nothing there to challenge or apply. Just re-run the same close; the next attempt normally clears once the other close releases the lock. |
+| `proposal-store-failed` | A conflict was correctly withheld from disk, but writing its `.cache/proposals/` artifact also failed (see `proposalStoreFailures[]` and the loud stderr). The payload bytes for that field are on neither disk nor a proposal artifact right now. | Fix whatever is blocking `.cache/proposals/` (permissions, a file sitting where the directory should be, disk space), then re-run the exact same payload. Nothing was lost: the payload still holds the bytes, only the parking step failed. |
 
 Once `ok: true`, report from the result JSON's `applied` and `skipped` arrays together, not `applied` alone. `applied` lists only the fields this run actually wrote bytes for; `skipped` lists the fields that already matched what was on disk (a re-run of an already-applied payload). An idempotent re-run legitimately reports `applied: []`, and that is success, not a failure to report on: check `skipped` for the same 4-6 entries instead. Read `committed` the same way: `true` covers both a real commit and the case where nothing needed staging (a full no-op re-run); `false` means the commit itself ran and failed (see `markerSkipReason`); `null` means apply never reached the commit step at all, because `ok` was already false (an authority refusal before any write, or a verification/lint failure, or a withheld conflict, per `stage`). `null` does NOT mean nothing was written: `applied` can be non-empty (bytes landed on disk) while `committed` stays `null`, because those bytes were never staged into git.
 
@@ -172,6 +177,7 @@ Once `ok: true`, report from the result JSON's `applied` and `skipped` arrays to
 - ✓ open-questions applied (or skipped if unchanged)
 - ✓ log.md entry appended (or already present)
 - ✓ post-apply lint clean
+- **`restructureWaivers[]`** (report it if non-empty): an overwrite field carried `"restructure": true`, and that flag actually waived a real section-loss trip (the payload dropped `##` sections the guard would otherwise have parked). Report each entry verbatim: the target file and the section names the waiver let through. The waiver is set by the same party (a model composing the payload) the section-loss guard exists to check, so it must never pass silently.
 - **marker written?** (required check): if `markerWritten: true`, report "session-close marker written"; if `markerWritten: false`, report "session-close marker NOT written (reason: `<markerSkipReason>`)" and do NOT declare the session "closed" or "complete". A missing marker means the Stop-chain is still open; recover per the `markerSkipReason` branch below.
 
 If `markerWritten: true`: ask: "Session closed. Would you like to also run knowledge synthesis now, or stop here?"
@@ -182,12 +188,17 @@ If `markerWritten: true`: ask: "Session closed. Would you like to also run knowl
 - `transcript-unresolved`: the id resolved no transcript, so it is almost certainly not the main conversation's (a background-task or Agent-thread uuid, most often). Get the right one and re-run.
 - `no-user-close-signal`: the transcript is this session's, but no close authority is in force. **Branch on `gateReason` before doing anything.** The three cases need three different responses, and treating them alike is what made this refusal look like it had a new cause every time it appeared.
   - `no-open`: the user genuinely never asked to close in wording the gate recognizes (e.g. "세션 마무리까지 진행해줘" falls outside the close-signal set). Re-running the same id changes nothing, because the transcript is unchanged. Confirm intent once with `AskUserQuestion`, header "세션", a single option labelled **세션 마무리** (설명: "이 세션을 마무리하고 close 마커를 기록"). If the user picks it, that answer lands in the transcript as a recognized close signal, so re-running the exact same command now applies **everything**: the writes, the commit, and the marker. If the user declines, the session stays open and nothing is written.
-  - `no-new-open-since-resolution`: the user DID ask, and that request was already resolved by an earlier close. Asking again makes them answer a question they have already answered. Report that this session is already closed and stop; do not re-prompt.
+  - `no-new-open-since-resolution`: the user DID ask, and that request was already resolved by an earlier close. Asking again makes them answer a question they have already answered. Report that this session is already closed and stop; do not re-prompt. On the apply path, a resolution is recorded only once the session-close marker itself lands, so this reason cannot appear for a session whose apply was never marked closed. `/clear` is the one exception: it ends the session as surely as a close apply does, so `hypo-session-end.mjs` records the same resolution on a `/clear` directly, with no marker involved at all. So a session that never ran an apply, but was ended with `/clear`, can still carry a recorded resolution.
   - `transcript-rewrite-detected`: the transcript changed underneath the gate, so the earlier signal can no longer be attested. This is not a statement about what the user wants. Say what happened rather than asking them to repeat themselves, and let a human decide.
 
   In all three: do NOT touch the close-signal matcher itself, and do not hand-write the files to work around the refusal.
 
-If the apply succeeded but `markerWritten: false`, do NOT say "session closed." Branch on `markerSkipReason` (`compact-gate-not-ok`, `commit-failed: …`, `marker-did-not-land`): surface the reason verbatim and address it (resolve the compact blocker, fix the git / disk issue) before re-running.
+If the apply succeeded but `markerWritten: false`, do NOT say "session closed." Branch on `markerSkipReason`, which carries one of five values:
+
+- `compact-gate-not-ok`, `commit-failed: …`, `marker-did-not-land`: surface the reason verbatim and address it (resolve the compact blocker, fix the git / disk issue) before re-running. **The re-run needs no fresh close phrase from the user for these three.** The resolution that spends a close signal is written only once the marker lands, so a run denied its marker at this stage leaves that signal unspent and the retry is authorized by the same one.
+  **A `commit-failed:` retry can need a hand first.** The payload writes land before the commit does, so after a failed commit those files already match what the retry would write. The retry skips them as already current, which leaves them out of the commit it makes, and they stay uncommitted and keep blocking the marker. If a retry reports `commit-failed:` or `compact-gate-not-ok` a second time on the same close, stop retrying and look at `git status` in the vault: stage and commit the close files yourself, or ask the user to, then run the close again.
+- `transcript-unresolved`: the marker writer could not resolve any transcript for this `--session-id` at all, so it never got as far as checking for a close signal. Passing the exact same id again changes nothing; get the main conversation's real session id (not a background-task or Agent-thread uuid) and re-run.
+- `no-user-close-signal`: a transcript was found, but it carries no close signal the gate recognizes. This is the one branch where the re-run DOES need a fresh signal: confirm intent once with `AskUserQuestion` (the same 세션 마무리 flow described under Step 3's `no-user-close-signal` table above), then re-run only after the user confirms.
 
 If the user says stop, end here. Otherwise continue to Step 5.
 

package/docs/ARCHITECTURE.md

@@ -143,8 +143,7 @@ Hooks run automatically at Claude Code lifecycle events. They are deployed to `~
 
 Hooks run in an isolated environment at `~/.claude/hooks/`. They **cannot import from relative paths** outside their own directory. Therefore:
 
-- All shared hook logic lives in `hypo-shared.mjs`.
-- `hypo-shared.mjs` is declared via the `shared` field in `hooks.json` and copied alongside hooks at deploy time.
+- Shared hook logic lives in the modules `hooks/shared.json` declares, not only in `hypo-shared.mjs`. That file (a plain JSON array of `.mjs` basenames) is the source of truth for the list and is copied alongside hooks at deploy time. It used to be a `shared` field inside `hooks.json` itself; it moved to this sibling file because the harness started warning on that unknown top-level key once it began validating `hooks.json` against its own hook-registration schema.
 - Hook utilities use **only Node.js built-ins** — no relative imports, no npm dependencies.
 
 Scripts in `scripts/` are not deployed — they run from the package install path — so they can import from `scripts/lib/`.
@@ -246,6 +245,8 @@ Hooks inline this logic in `hypo-shared.mjs`. Scripts use `scripts/lib/hypo-root
 4. Detects drift (e.g., `pkgRoot` no longer exists) and refreshes the pointer.
 5. `--json` output emits `{ schema, hooks, settings, applied }`. `--dry-run` previews; `--apply` commits changes.
 
+The SessionStart hook (`hooks/hypo-session-start.mjs`) is a third writer of this file, outside init/upgrade entirely. `hooks/hypo-shared.mjs`'s `pkgRootDriftStatus` detects drift by comparing the canonicalized `pkgRoot` alone, not `pkgVersion`, so a file whose `pkgRoot` already matches self-location reads as `match` even when its `pkgVersion` is stale. Only a `pkgRoot` mismatch triggers the rewrite (temp file, then rename), and `pkgVersion` is carried along in that same write rather than checked or fixed on its own. The rewrite is guarded by a lockfile, so two sessions self-locating to different install roots at once cannot race each other's write, and it writes nothing on a downgrade (self-location resolves to an older version than the file already records), an incoming version that fails to parse as semver, a lock it could not acquire, or an opted-out session.
+
 ### `/hypo:uninstall`
 
 Removes hypo-prefixed hooks from `~/.claude/hooks/` and matching entries from `~/.claude/settings.json`. **Non-hypo hooks are preserved**. `--apply` also reaches past `~/.claude/`: it strips the marked `claude()` block from the shell rc file(s) init wrote to, and removes the marked pre-commit hook from the wiki's own git repo. Both removals are marker-gated the same way the hooks-dir cleanup is, so a hand-edited block or hook is left in place rather than guessed at.
@@ -501,7 +502,7 @@ Requires `NPM_TOKEN` secret.
 
 ## Plugin manifest
 
-`.claude-plugin/plugin.json` declares the plugin to Claude Code. `hooks/hooks.json` follows the standard plugin hooks schema:
+`.claude-plugin/plugin.json` declares the plugin to Claude Code. `hooks/hooks.json` follows the standard plugin hooks schema, and carries only what that schema knows about: an event-to-hook map, nothing else.
 
 ```json
 {
@@ -517,11 +518,18 @@ Requires `NPM_TOKEN` secret.
         ]
       }
     ]
-  },
-  "shared": ["hypo-shared.mjs"]
+  }
 }
 ```
 
+The shared-file list (helpers a registered hook imports, such as `hypo-shared.mjs`) is Hypomnema's own convention, not something the harness's schema recognizes, so it lives in a sibling file instead: `hooks/shared.json`, a plain JSON array of `.mjs` basenames.
+
+```json
+["hypo-shared.mjs", "version-check.mjs", "..."]
+```
+
+`hooks/hooks.json` is still the source of truth for the event-to-hook map; `hooks/shared.json` is the source of truth for the shared-file list. A hook registered in the former, or a helper listed in the latter, is what init/upgrade deploy. Anything left off either file never reaches an installed copy.
+
 `claude plugin validate .` is run as part of CI's plugin-snapshot checks.
 
 ---

package/docs/CONTRIBUTING.md

@@ -62,8 +62,7 @@ See [ARCHITECTURE.md](ARCHITECTURE.md) for the full breakdown. Short version:
 
 **Hooks run in `~/.claude/hooks/` in isolation. They cannot import from relative paths.**
 
-- All shared logic must live in `hooks/hypo-shared.mjs`.
-- `hypo-shared.mjs` is declared via the `shared` field in `hooks/hooks.json` and copied alongside each hook at deploy time.
+- Shared logic must live in one of the modules `hooks/shared.json` declares, not only in `hypo-shared.mjs`. That file (a plain JSON array of `.mjs` basenames) is the source of truth for the list and is copied alongside each hook at deploy time. It used to be a `shared` field inside `hooks.json` itself; that moved to this sibling file once the harness started warning on that unknown top-level key.
 - Hook utilities may use **only** Node.js built-ins (`fs`, `path`, `os`, `child_process`, `crypto`).
 - No relative imports, no npm dependencies.
 
@@ -85,7 +84,7 @@ Scripts under `scripts/` are not deployed and may freely import from `scripts/li
 
 1. Edit the hook file in `hooks/`.
 2. If it's new, register it in `hooks/hooks.json` under the correct event key.
-3. Shared utilities go in `hooks/hypo-shared.mjs`.
+3. Shared utilities go in a module listed in `hooks/shared.json`, usually `hypo-shared.mjs`.
 4. Add a contract test in the hook's area file, e.g. `tests/session-hooks.test.mjs` (input → expected `additionalContext` shape).
 5. After your change, run `/hypo:upgrade` in a real Claude Code session and verify the hook fires.
 
@@ -256,7 +255,7 @@ After both blocks, language-neutral:
 
 - **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-`, `fix #N`) may appear in your local notes and in `tests/` (where they aid test-to-issue traceability and never reach an installed user), but not in shipped code or workflow comments, and 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 tracker identifier that ships in those is the PR number `#N`; the lone exception is the ADR carve-out noted below. `check-tracker-ids` gates the file, message, and tag surfaces (`--all`/`--staged` for files, `--commit-msg` for messages, `--tag` for the tag body), and `check-pr-surface` gates the PR title and body; the migration keeps the CHANGELOG body clean. `ADR NNNN` / `decisions/NNNN` are exempt on the changelog surfaces (the CHANGELOG body, the tag body, and the PR `## Changelog` block), where a release line legitimately cites the decision behind it.
+- Internal tracker ids (`FEAT-`, `IMPR-`, `ISSUE-`, `PRAC-`, `fix #N`, `ADR NNNN`, `decisions/NNNN`) may appear in your local notes and in `tests/` (where they aid test-to-issue traceability and never reach an installed user), but not in shipped code or workflow comments, and 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`. `ADR NNNN` / `decisions/NNNN` used to be exempt on the changelog surfaces, on the theory that a release line legitimately cites the decision behind it; that exemption is gone, because this repo ships no `decisions/` directory for anyone outside the maintainer's private wiki to open — an external reader hits the same dead end on `decisions/NNNN` as on `ISSUE-N`, so the exemption was blocking nothing but its own contradiction. `check-tracker-ids` gates the file, message, and tag surfaces (`--all`/`--staged` for files, `--commit-msg` for messages, `--tag` for the tag body), and `check-pr-surface` gates the PR title and body; the migration keeps the CHANGELOG body clean.
 
 ### The `## Changelog` block
 
@@ -372,6 +371,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
 
+# 1c. If this release also bumps templates/SCHEMA.md's `version:` frontmatter,
+#     add a matching line to SCHEMA_VERSION_DELTAS in
+#     scripts/lib/template-schema-version.mjs, naming what that version added.
+#     Skipping this is silent: upgrade.mjs's notice just falls back to "review
+#     manually" for that version, with no test failing at bump time except
+#     the one in tests/upgrade.test.mjs that pins the SHIPPED version has an
+#     entry.
+
 # 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,
@@ -406,8 +413,10 @@ git commit -m "chore: release v<version>"
 #    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 `FEAT-`/`IMPR-`/`ISSUE-`/`PRAC-`/`fix #N` tracker
-#    ids (check-tracker-ids --tag gates it). Like the CHANGELOG, the tag body MAY cite
-#    `ADR NNNN` / `decisions/NNNN` for the decision behind a release.
+#    ids (check-tracker-ids --tag gates it), and no `ADR NNNN` / `decisions/NNNN`
+#    either: this repo ships no `decisions/` directory, so a reader outside the
+#    maintainer's private wiki cannot open either one. Say what changed in
+#    plain prose, or cite the PR number.
 git tag -a v<version> -m "$(cat <<'EOF'
 Hypomnema v<version>: <one-line English summary>
 
@@ -421,7 +430,12 @@ Hypomnema v<version>: <한 줄 한글 요약>
 EOF
 )"
 
-# 6. Rehearse the release locally (same checks CI runs against the tag)
+# 6. Rehearse the release locally (same checks CI runs against the tag).
+#    This is the ONLY gate that runs before the tag object is public. The
+#    release workflow re-runs these, but it starts when the push in step 7
+#    lands, so by then the annotated tag body is already on GitHub: CI can
+#    stop the npm publish and the Release, not the tag. Skip these three and
+#    nothing catches a leaked id until a reader finds it.
 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

package/hooks/close-journal.mjs

@@ -0,0 +1,128 @@
+// hooks/close-journal.mjs — the close journal: which relative paths THIS
+// session's close actually wrote, and the hash it wrote each one as.
+//
+// Lives in hooks/ for the same reason close-gate-store.mjs does: scripts/
+// imports hooks/, never the reverse, and a hook copied standalone into
+// ~/.claude/hooks/ cannot resolve a scripts/ import. Node built-ins only.
+//
+// Why this exists: applySessionClose treats a payload field as "already
+// current" (an overwrite whose disk bytes already match the payload, or an
+// append whose entry is already present) and skips writing it — the whole
+// point of that skip is to make a same-payload retry cheap. But a close that
+// partially failed (one field conflicted, the commit itself failed, the
+// process was killed between write and commit) can leave EARLIER fields
+// already written to disk and still uncommitted. The retry's skip then drops
+// those paths out of the commit scope entirely, because "already current"
+// and "already committed" look identical from the skip branch alone — and
+// nothing ever re-adds them, so the close gate blocks on the same dirty
+// files forever. The journal is what tells the retry apart: a path recorded
+// here, whose disk hash still matches what was recorded, is this session's
+// own uncommitted work and safe to restage. A path with no record, or one
+// whose disk hash has since moved, is not — somebody else's bytes are
+// sitting there, and the gate should keep blocking on them, not silently
+// fold them into this close's commit.
+//
+// Mirrors close-gate-store.mjs's shape: same `.cache/<name>/<sessionId>.json`
+// path convention, same atomic tmp+rename write, same "unreadable or corrupt
+// reads as empty" polarity. A journal this module cannot trust must only ever
+// NARROW what a retry is allowed to restage, never widen it — the same
+// direction close-gate-store's NO_CONSTRAINT keeps for its own file.
+
+import { existsSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+
+/** `<hypoDir>/.cache/close-journal/<sessionId>.json`. */
+export function closeJournalPath(hypoDir, sessionId) {
+  return join(hypoDir, '.cache', 'close-journal', `${sessionId}.json`);
+}
+
+/** Atomic overwrite via tmp+rename, mirroring close-gate-store's atomicWrite. */
+function atomicWrite(path, content) {
+  mkdirSync(dirname(path), { recursive: true });
+  const tmp = `${path}.${process.pid}.${Math.random().toString(36).slice(2, 10)}.tmp`;
+  writeFileSync(tmp, content);
+  renameSync(tmp, path);
+}
+
+/**
+ * Read this session's journal. Absent, corrupt, or wrong-shaped reads as
+ * `{}` — never partially trusted. A caller that widened a retry off a
+ * malformed record here would be exactly the failure mode this file exists
+ * to avoid, so any doubt about the shape falls back to "nothing recorded".
+ * @param {string} hypoDir
+ * @param {string|null|undefined} sessionId
+ * @returns {Record<string, string>} relPath -> the hash this session wrote it as
+ */
+export function readJournal(hypoDir, sessionId) {
+  if (!sessionId) return {};
+  const path = closeJournalPath(hypoDir, sessionId);
+  if (!existsSync(path)) return {};
+  try {
+    const parsed = JSON.parse(readFileSync(path, 'utf-8'));
+    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) return {};
+    if (parsed.v !== 1 || !parsed.paths || typeof parsed.paths !== 'object') return {};
+    const out = {};
+    for (const [relPath, hash] of Object.entries(parsed.paths)) {
+      if (typeof hash === 'string') out[relPath] = hash;
+    }
+    return out;
+  } catch {
+    return {};
+  }
+}
+
+/**
+ * Record that this session wrote `relPath` as `hash`. Callers must call this
+ * AFTER the byte write it describes, never before: the journal is read to
+ * decide whether a write already landed, and a record ahead of the write it
+ * names would let a crash between the two claim credit for bytes that were
+ * never actually put down.
+ *
+ * Read-modify-write, not append-only: one close touches several paths across
+ * several call sites in one process, and each call needs the earlier ones'
+ * entries still present when it re-saves the file. Best-effort like every
+ * other write in this store — a journal write failure must never fail a close
+ * over bytes that already landed; it only costs that one path its fast
+ * restage on a future retry, which falls back to the ordinary gate block, the
+ * safe direction to fail toward.
+ *
+ * @param {string} hypoDir
+ * @param {string|null|undefined} sessionId
+ * @param {string} relPath vault-relative path, exactly as it appears in
+ *   `appliedPaths` / `commitWikiChanges`
+ * @param {string} hash sha256 hex of the bytes just written (hashContent)
+ */
+export function recordJournalEntry(hypoDir, sessionId, relPath, hash) {
+  if (!sessionId) return;
+  try {
+    const paths = readJournal(hypoDir, sessionId);
+    paths[relPath] = hash;
+    atomicWrite(
+      closeJournalPath(hypoDir, sessionId),
+      JSON.stringify({ v: 1, sessionId: String(sessionId), paths }, null, 2),
+    );
+  } catch {
+    // best-effort — see doc comment above
+  }
+}
+
+/**
+ * Clear this session's journal once its close has actually committed. A
+ * journal entry that outlives a successful commit would keep offering to
+ * restage bytes for a path this SAME session might legitimately touch again
+ * later in an unrelated close — the hash comparison alone cannot tell "still
+ * my uncommitted work" from "coincidentally the same bytes, much later" once
+ * the first close is done. Best-effort: a leftover file after a successful
+ * close is at worst a future no-op restore attempt (the hash still has to
+ * match), never a data-loss risk on its own.
+ * @param {string} hypoDir
+ * @param {string|null|undefined} sessionId
+ */
+export function clearJournal(hypoDir, sessionId) {
+  if (!sessionId) return;
+  try {
+    rmSync(closeJournalPath(hypoDir, sessionId), { force: true });
+  } catch {
+    // best-effort — see doc comment above
+  }
+}

package/hooks/hooks.json

@@ -153,13 +153,5 @@
         ]
       }
     ]
-  },
-  "shared": [
-    "hypo-shared.mjs",
-    "version-check.mjs",
-    "version-check-fetch.mjs",
-    "base-store.mjs",
-    "proposal-store.mjs",
-    "close-gate-store.mjs"
-  ]
+  }
 }

package/hooks/hypo-session-start.mjs

@@ -7,7 +7,7 @@
  *   MISS → inject global hot.md pointer only (no fan-out to all projects)
  */
 
-import { readFileSync, writeFileSync, existsSync, realpathSync } from 'fs';
+import { readFileSync, writeFileSync, existsSync, realpathSync, renameSync } from 'fs';
 import { homedir } from 'os';
 import { join, dirname } from 'path';
 import { fileURLToPath } from 'url';
@@ -39,6 +39,7 @@ import {
   readVisibilityScope,
   pkgRootDriftStatus,
   PKG_ROOT,
+  withFileLock,
 } from './hypo-shared.mjs';
 import {
   defaultCachePath,
@@ -52,6 +53,8 @@ import {
   computeSiblingNotice,
   siblingAlreadyNotified,
   markSiblingNotified,
+  classifyInstall,
+  parseSemver,
   pkgRootDriftAlreadyNotified,
   markPkgRootDriftNotified,
   clearPkgRootDriftNotified,
@@ -237,15 +240,177 @@ function buildSiblingNotice() {
   }
 }
 
+// Full path to the file init/upgrade own writing (hypo-shared.mjs's
+// readCachedPkgRoot reads it but does not export the path). Self-heal below
+// reads and rewrites it directly rather than adding a write path into
+// hypo-shared.mjs, which currently owns only the READ side of this file.
+const HYPO_PKG_JSON_PATH = join(homedir(), '.claude', 'hypo-pkg.json');
+
+// ── self-heal lock ───────────────────────────────────────────────────────────
+// Two sessions can self-locate to two DIFFERENT install roots at once (a dual
+// install, or one upgrade mid-flight while another session already started)
+// and both hit this same homedir()-keyed hypo-pkg.json. Reading it once,
+// comparing, then writing let whichever session finished SECOND clobber
+// whatever the first had just written, even when its own incoming version
+// was itself newer than the file's ORIGINAL value (Codex 3rd-round review,
+// 2026-09-11: reproduced by running a 1.8.2 and a 1.8.1 install against the
+// same HOME; both read the pre-existing 1.0.0, both judged themselves an
+// improvement over it, and whichever wrote last won regardless of which
+// incoming version was actually higher).
+//
+// This used to hand-roll its own `wx` lockfile (write-then-fill), which a
+// Codex 3rd-round review caught publishing an empty lock before the pid was
+// written: a holder preempted inside that window is indistinguishable from a
+// pid-less legacy lock, so a second writer steals it and both run the
+// critical section, which is the exact bug a liveness check is supposed to
+// close. `withFileLock` (below, from hypo-shared.mjs) already exists in this
+// repo, and its own docstring names that same failure mode as the reason it
+// stages the pid into a private sibling first and `linkSync`s it into place
+// atomically. Reuse it instead of repeating the mistake it was written to
+// avoid. `timeoutMs: 150` keeps the bounded, best-effort wait this hook
+// always had (long enough for a sibling session's heal, a handful of sync fs
+// calls, to finish and release; short enough that SessionStart itself never
+// stalls noticeably even under contention); `staleMs: 30000` keeps the same
+// crashed-holder cutoff the old lock used.
+//
+// withFileLock throws ELOCKTIMEOUT when it cannot acquire in time, never a
+// bare Error, so selfHealPkgRoot's caller can tell "lock contention" apart
+// from "fn() itself failed". Either way this hook must fail OPEN: a
+// SessionStart hook must never block or crash a session over a lock it
+// couldn't get, so both outcomes collapse to the caller's `{ healed: false }`
+// via the try/catch already wrapping the read-compare-write below.
+//
+// Known residue in withFileLock itself, inherited here rather than
+// re-solved: a microscopic stat-then-unlink TOCTOU on the stale-steal path
+// (a fresh holder can grab the path in that gap and have its lock removed by
+// the stealer, bounded by staleMs being far above a normal close), a
+// local-filesystem-only guarantee (no network FS atomicity), and a PID-reuse
+// window where a live process happens to reuse a crashed holder's pid and
+// gets treated as the still-alive original (an availability loss, the lock
+// is never stolen from it, not a correctness bug, since two writers still
+// never enter the critical section together).
+
+/**
+ * Self-heal `pkgRoot`/`pkgVersion` in `hypo-pkg.json` in place, once a session
+ * has already detected they disagree with the code's own self-location
+ * (`status`, from pkgRootDriftStatus()). Until now the user's only remaining
+ * job was copying those two values into the file by hand; this does that copy
+ * for them.
+ *
+ * Preserves every other key untouched (`schemaVersion`, `extensions`,
+ * `commands`, ...): this file is shared with init/upgrade's own writes, so a
+ * narrower op than "read the whole object, patch two keys, write the whole
+ * object back" would silently drop state another lane depends on. Mirrors
+ * scripts/lib/pkg-json.mjs's writeDualSkipProvenance in spirit, but cannot
+ * import it — hooks never reach into scripts/.
+ *
+ * Fails closed to `{ healed: false }` on anything short of a verified,
+ * complete write: a lock that could not be acquired (timeout or a genuine
+ * fs error from `withFileLock`), an unreadable/corrupt existing file, a
+ * non-object parse result, no resolvable-and-parseable version at the new
+ * root, a DOWNGRADE (below), or the write itself throwing. The caller must
+ * fall back to the manual `/hypo:upgrade` guidance rather than claim a fix
+ * that never landed.
+ *
+ * Concurrency: the whole read-compare-write runs inside `withFileLock`
+ * (hypo-shared.mjs), which re-reads `hypo-pkg.json` AFTER acquiring the
+ * lock, not before, since a pre-lock snapshot is exactly what let two
+ * concurrent installs race. Losing the lock (ELOCKTIMEOUT, or any other
+ * throw from `withFileLock` or from `fn` itself) is caught by the outer
+ * try/catch and treated as fail-open: this session simply skips the heal,
+ * the same outcome as any other precondition miss below.
+ *
+ * The lock's reach is narrower than the sentence above about sharing this
+ * file with init/upgrade might suggest: it serializes SessionStart heals
+ * against each other, and nothing else. `writePkgJsonAtomic` (what init,
+ * upgrade and writeDualSkipProvenance go through) does not take it, so an
+ * `upgrade --apply` running while another session starts is still a lost
+ * update. The damage is bounded rather than absent: heal refuses a
+ * downgrade, so whichever write lands last leaves `pkgVersion` at the same
+ * value or higher. That bound is the whole argument for leaving it, and it
+ * dies the moment a heal path is allowed to lower the version.
+ *
+ * Downgrade guard: a dual install (e.g. a plugin-scope cache at 1.8.2 and a
+ * project-scope cache at 1.8.1, both reading the SAME `hypo-pkg.json` because
+ * that path is keyed on `homedir()`, not on scope) means a session that
+ * happens to self-locate to the OLDER sibling would otherwise overwrite this
+ * file's `pkgVersion` with a lower number — the one baseline
+ * `scripts/upgrade.mjs`'s downgrade guard and `hooks/version-check.mjs`'s
+ * `computeSiblingNotice` both compare against. `classifyInstall` is the same
+ * judgment those two already trust, but this only blocks the `'downgrade'`
+ * verdict: a comparison that resolves and comes out lower. On `'downgrade'`,
+ * this returns `{ healed: false }` before touching the file, so the normal
+ * failure fallback below fires the original manual-fix guidance instead of
+ * quietly recording the sibling's older version as truth.
+ *
+ * Direction matters for the `'unknown'` verdict (one side's semver failed to
+ * parse), which is why the INCOMING version is checked with `parseSemver`
+ * up front rather than folded into the same `'unknown'` escape hatch as an
+ * unparseable EXISTING value. An unparseable incoming version must never
+ * heal: that would overwrite a good `pkgVersion` with garbage read from a
+ * corrupt `package.json` (Codex 3rd-round review, 2026-09-11: reproduced with
+ * `package.json.version: "not-semver"` against an existing `1.8.2`, which
+ * used to heal to `"not-semver"`). An unparseable EXISTING value with a
+ * valid incoming one is the opposite case, a good value replacing a
+ * corrupted one, and is still allowed through by `classifyInstall`'s
+ * `'unknown'` verdict: there is no valid comparison to protect against
+ * there, and refusing it would leave a broken value in place forever with no
+ * path back to a good one.
+ */
+function selfHealPkgRoot(status) {
+  try {
+    return withFileLock(
+      HYPO_PKG_JSON_PATH,
+      () => {
+        const meta = JSON.parse(readFileSync(HYPO_PKG_JSON_PATH, 'utf-8'));
+        if (!meta || typeof meta !== 'object' || Array.isArray(meta)) return { healed: false };
+        const newVersion = readInstalledVersion(status.self);
+        if (!newVersion || !parseSemver(newVersion)) return { healed: false };
+        const oldVersion = typeof meta.pkgVersion === 'string' ? meta.pkgVersion : null;
+        const incoming = { pkgRoot: status.self, version: newVersion };
+        const active = { pkgRoot: meta.pkgRoot, version: oldVersion };
+
+        if (classifyInstall(incoming, active) === 'downgrade') return { healed: false };
+        const updated = { ...meta, pkgRoot: status.self, pkgVersion: newVersion };
+        // temp + rename in the SAME directory: a crash mid-write leaves only a
+        // throwaway temp file behind, never a torn hypo-pkg.json that the next
+        // session's every hook read of this file would then choke on.
+        const dir = dirname(HYPO_PKG_JSON_PATH);
+        const tmp = join(
+          dir,
+          `.hypo-pkg.json.${process.pid}.${Math.random().toString(36).slice(2, 10)}.tmp`,
+        );
+        writeFileSync(tmp, `${JSON.stringify(updated, null, 2)}\n`);
+        renameSync(tmp, HYPO_PKG_JSON_PATH);
+        return { healed: true, oldVersion, newVersion };
+      },
+      { timeoutMs: 150, staleMs: 30_000, pollMs: 20 },
+    );
+  } catch {
+    // Fail open: a lock timeout (ELOCKTIMEOUT) or any other throw from
+    // withFileLock/fn must not block or crash SessionStart. The caller
+    // treats this exactly like any other heal precondition miss.
+    return { healed: false };
+  }
+}
+
 /**
  * pkgRoot drift notice. hypo-shared.mjs's resolvePkgRoot() already
  * self-corrects PKG_ROOT in memory whenever the code's own resolved location
- * disagrees with the cached hypo-pkg.json — but silent self-correction is the
- * exact failure this closes: the user's own `upgrade` habit stops mattering
- * and nothing ever tells them hypo-pkg.json fell behind. Surfaced once per
- * (cached → self-location) pair via the same notify-once cache the sibling
- * notice above uses — a fresh drift (new self-location) re-notifies, but
- * staying on the same drifted state doesn't nag every session.
+ * disagrees with the cached hypo-pkg.json — but silent self-correction used
+ * to leave the FILE itself stale forever, with nothing but a "please copy
+ * these two values in yourself" notice to show for it. This now does that
+ * copy itself (selfHealPkgRoot above), on the spot, in the same session that
+ * detected the drift.
+ *
+ * Notify-once cache: a successful heal marks the (cached → self-location)
+ * pair notified, but next session's pkgRootDriftStatus() reads back 'match'
+ * from the now-fixed file regardless and clears it on its own — the mark here
+ * only prevents a duplicate "fixed" line within a session that re-checks
+ * drift more than once. A FAILED heal must NOT mark the pair: marking would
+ * suppress the only guidance the user has (the manual `/hypo:upgrade` line)
+ * for a drift that never actually got fixed, on every later session that
+ * hits the same stale pair.
  *
  * Tri-state (pkgRootDriftStatus): 'match' CLEARS any earlier mark (checked
  * FIRST, unconditionally — even under opt-out, so a drift that resolves while
@@ -253,8 +418,9 @@ function buildSiblingNotice() {
  * recurrence once opt-out is lifted); 'unknown' touches nothing (self-location
  * could not be resolved this session — the permanent steady state for the
  * npm/manual channel, not evidence either way); only 'drift' can produce a
- * banner, and opt-out is checked there so an opted-out session never marks a
- * pair as notified it never actually showed.
+ * banner (or attempt a heal), and opt-out is checked there so an opted-out
+ * session never writes a fix — or marks a pair notified — it never actually
+ * showed.
  */
 function buildPkgRootDriftNotice() {
   try {
@@ -269,7 +435,24 @@ function buildPkgRootDriftNotice() {
     const key = `${status.cached || '(none)'}->${status.self}`;
     const cache = readCache(cachePath);
     if (pkgRootDriftAlreadyNotified(cache, key)) return '';
-    markPkgRootDriftNotified(cachePath, key);
+
+    const heal = selfHealPkgRoot(status);
+    if (heal.healed) {
+      markPkgRootDriftNotified(cachePath, key);
+      return (
+        `[Hypomnema] Package metadata drift fixed: hypo-pkg.json pointed at ` +
+        `\`${status.cached || '(none)'}\`` +
+        `${heal.oldVersion ? ` (version ${heal.oldVersion})` : ''}, now synced to ` +
+        `\`${status.self}\` (version ${heal.newVersion}).\n` +
+        `  This was corrected automatically for this session — no action needed.`
+      );
+    }
+
+    // Heal did not land (unreadable/corrupt hypo-pkg.json, no resolvable
+    // version at the new root, or the write itself failed). Do NOT mark this
+    // pair notified here — see the docstring above — and fall back to the
+    // original manual-fix guidance.
+    //
     // status.cached is null both for a genuinely fresh install (never ran
     // /hypo:init) AND for the channel-judgment-failure guard (init/upgrade
     // positively decided to leave pkgRoot unset; see scripts/init.mjs's
@@ -287,7 +470,7 @@ function buildPkgRootDriftNotice() {
       `\`${status.cached || '(none)'}\`, but the code actually running resolves to ` +
       `\`${status.self}\`.\n` +
       `  Hooks already resolved the correct root for this session — this is a ` +
-      `heads-up, not a blocker.\n${recoveryLine}`
+      `heads-up, not a blocker (the automatic fix did not take — see below).\n${recoveryLine}`
     );
   } catch {
     return '';