hypomnema 1.8.2 → 1.9.0

package/docs/ARCHITECTURE.md

@@ -119,7 +119,7 @@ Hooks run automatically at Claude Code lifecycle events. They are deployed to `~
 | `UserPromptSubmit` | `hypo-first-prompt.mjs` → `hypo-lookup.mjs` → `hypo-compact-guard.mjs` |
 | `PreCompact` | `hypo-personal-check.mjs` |
 | `PostToolUse` (Write/Edit) | `hypo-auto-stage.mjs` |
-| `Stop` | `hypo-hot-rebuild.mjs` → `hypo-session-record.mjs` → `hypo-auto-commit.mjs` |
+| `Stop` | `hypo-stop.mjs` (runs `hypo-hot-rebuild.mjs` → `hypo-session-record.mjs` → `hypo-auto-commit.mjs` → `hypo-auto-minimal-crystallize.mjs` as ordered stages, not separate registrations) |
 | `CwdChanged` | `hypo-cwd-change.mjs` |
 | `FileChanged` | `hypo-file-watch.mjs` |
 
@@ -127,24 +127,23 @@ Hooks run automatically at Claude Code lifecycle events. They are deployed to `~
 
 | Hook | Responsibility |
 |---|---|
-| `hypo-session-start` | Inject `index.md`, root `hot.md`, project `hot.md`/`session-state.md`. Run `git pull --ff-only` (silent fail on missing remote) |
+| `hypo-session-start` | Run `git pull --ff-only` (silent fail on missing remote), rebuild the root `hot.md` projection, inject `index.md`, root `hot.md`, project `hot.md`/`session-state.md` |
 | `hypo-first-prompt` | Reads the marker left by `hypo-session-start` or `hypo-cwd-change` and forces a one-line resume on the first user prompt (10-min TTL). It does not re-read or re-inject `hot.md` |
 | `hypo-lookup` | BM25 search over the wiki on every prompt. **HIT** → inject top-3 page snippets (≤2000 chars each; a page whose `verify_by_date` is overdue gets a `[STALE verify_by_date=…]` marker prepended). **MISS** → emit closest-slug signal that prompts Claude to research + `/hypo:ingest` |
 | `hypo-compact-guard` | Detect `/compact` or `/clear` typed in chat and, if session close is incomplete, tell Claude so. It never blocks `/compact` |
 | `hypo-personal-check` | PreCompact detection: lint blockers, uncommitted changes, missing session-log entries surface as a `systemMessage`; `/compact` is never blocked here |
 | `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-hot-rebuild` | At session stop, regenerate the root `hot.md` projection (the same generator `hypo-session-start` also calls); emit growth metrics + cache for next SessionStart. A scan failure (not just an empty `projects/`) skips the write and leaves a health notice for the next `SessionStart` to surface |
 | `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 build `additionalContext` with its `hot.md`; `CwdChanged` has no field Claude Code forwards to the model, so this does not currently reach Claude |
-| `hypo-file-watch` | Build `additionalContext` for a changed wiki file. Two things keep this inert: nothing in this package returns `watchPaths`, so the event has no registered trigger, and `FileChanged` output does not reach the model. The event also fires regardless of who changed the file, so it is not an external-edit signal |
+| `hypo-cwd-change` | When working directory changes, re-resolve the active project and build a notice carrying its `hot.md`. The hook reference documents `watchPaths` and `systemMessage` as `CwdChanged`'s output fields and says only that "it shows the `systemMessage` as a brief terminal notification" and "the message doesn't reach the SDK message stream"; it does not say whether `systemMessage` reaches the model on this event either way. As of Claude Code 2.1.276 (checked 2026-09-18) and reconfirmed on 2.1.283, tracing the installed binary shows the only consumer of that `systemMessage` is the terminal notification queue, a low-priority toast that a same-keyed message replaces and that disappears after five seconds, with no branch that forwards it to the model; outside the interactive REPL the injecting function is null. No live-session observation of this path exists either way. Until the documentation says otherwise, this event is treated as not reaching the model |
+| `hypo-file-watch` | Build a `systemMessage` notice for a changed wiki file, over the same field as `hypo-cwd-change` whose reach to the model the reference leaves undocumented; as of Claude Code 2.1.276 (checked 2026-09-18) and reconfirmed on 2.1.283 it is likewise treated as not reaching the model, for the same shared-consumer reason (see the `hypo-cwd-change` row). On a stock install the event still has no registered trigger: its matcher key is omitted (not blank), which the reference says matches every watched file while adding nothing to the watch list, and nothing in this package returns `watchPaths` to seed that list. The watch list is session-global, not scoped to this plugin, so another hook or plugin that does seed it would make this matcher-less group fire on every watched file; the hook still returns immediately for any path that does not start with `HYPO_DIR` (a string-prefix check, not a symlink-resolving one). That check only screens the path string: a symlink living inside the wiki still starts with `HYPO_DIR` and passes it, and the hook's `readFileSync` follows the link, so such a symlink can still surface content from wherever it points. The event also fires regardless of who changed the file, so it is not an external-edit signal |
 
 ### Deployment constraint
 
 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.
@@ -292,6 +293,7 @@ SessionStart
   │
   ├─► hypo-session-start.mjs
   │     ├─► git pull --ff-only (if remote)
+  │     ├─► rebuild root hot.md (projection of projects/*/hot.md)
   │     ├─► inject index.md / hot.md / project session-state.md
   │     └─► (Claude resumes work)
   │
@@ -307,14 +309,36 @@ SessionStart
   │     └─► hypo-personal-check.mjs (lint + session-close gate)
   │
   ├─► CwdChanged
-  │     └─► hypo-cwd-change.mjs (builds hot.md context; does not currently reach Claude)
+  │     └─► hypo-cwd-change.mjs (builds a hot.md notice on systemMessage; the reference documents the terminal notification, tracing the installed binary as of Claude Code 2.1.276, checked 2026-09-18 and reconfirmed on 2.1.283, shows it does not reach the model, and no live-session observation exists either way; see the hook table above)
   │
   └─► Stop
-        ├─► hypo-hot-rebuild.mjs (regenerate root hot.md + growth cache)
-        ├─► hypo-session-record.mjs (append .cache/sessions/index.jsonl)
-        └─► hypo-auto-commit.mjs (.hypoignore-filtered stage + commit + pull + push)
+        └─► hypo-stop.mjs, running four stages in order:
+              ├─► hypo-hot-rebuild.mjs (regenerate root hot.md projection + growth cache; SessionStart also calls this generator)
+              ├─► hypo-session-record.mjs (append .cache/sessions/index.jsonl)
+              ├─► hypo-auto-commit.mjs (.hypoignore-filtered stage + commit + pull + push)
+              └─► hypo-auto-minimal-crystallize.mjs (blocks Stop if session close never ran)
 ```
 
+Root hot.md's frontmatter `updated:` is the max of every `projects/*/hot.md` row date, not the
+date the projection itself was last rewritten. A vault whose newest project row is a week old
+keeps that same week-old date across every SessionStart and Stop until a project's own `hot.md`
+moves forward, even though the root file's bytes get recomputed and checked far more often.
+
+Before overwriting content it does not recognize as its own, the projection backs it up next to
+`hot.md` as `hot.md.pre-projection-backup.md` (or a numbered variant, `-2.md`, `-3.md`, ...). These
+backups are never cleaned up automatically. Delete the ones you no longer need by hand.
+
+The write itself goes through `writeRootHotProjection` in `hooks/hypo-shared.mjs`, which holds
+the vault commit lock (`vaultCommitLockTarget`, the same lock `hypo-auto-commit.mjs` and
+`crystallize.mjs`'s apply take around stage and commit) across the whole projection write: the
+first read of `hot.md`, the ownership check, the backup, and the replacing rename. `hypo-session-start.mjs`'s
+own `git pull` takes and releases the same lock before calling into the projection, so the two
+never overlap; they still serialize against each other and against a concurrent `auto-commit` or
+`crystallize` apply. The lock is not reentrant: nothing inside the projection's write path may
+take it a second time, and a caller that already holds it has to call the unlocked form instead.
+When the lock cannot be acquired within its timeout, the write is skipped rather than blocked on
+indefinitely, and the caller is told the pointer table was left as-is.
+
 ---
 
 ## Feedback → Behavior pipeline
@@ -501,7 +525,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 +541,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.
 
@@ -130,7 +129,11 @@ npm test           # tests/*.test.mjs, sharded across processes — unit + smoke
 npm run lint       # scripts/lint.mjs — frontmatter + wikilink validation + W8 (design-history stale
                    # vs session-log) + W14 (design-history missing but session-log implies one)
                    # + W15 (synthesis older than the newest page in its sources_consulted)
-                   # + W16 (sources_consulted names W15 could not resolve)
+                   # + W16 (sources_consulted content problems: a source name W15 could not
+                   #   resolve, a source or the synthesis's own updated that fails a strict
+                   #   YYYY-MM-DD parse, or sources_consulted written as a YAML block list
+                   #   instead of the required flow list; a single page can carry more than one
+                   #   W16 at once)
 npm run fix:verify # Phase 1 of learned_behavior #6 — verifies fix #N status claims in
                    # a wiki spec against `// @fix #N: <test-name>` anchors, read as a
                    # union across every tests/*.mjs. Maintainer dogfood; needs a wiki at
@@ -256,7 +259,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 +375,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 +417,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 +434,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/atomic-write.mjs

@@ -0,0 +1,44 @@
+// The one temp+rename writer. Six byte-identical copies of this function used to
+// live in hooks/ and scripts/lib/, and a fix landed in two of them (#296) while
+// the other four kept the bug. That is the whole reason this file exists: a
+// defense that lives in six places is a defense you can only half-apply.
+//
+// Hooks are copied standalone into ~/.claude/hooks/, so this has to live in
+// hooks/ and be listed in hooks/shared.json. scripts/ may import it; the reverse
+// direction is what breaks for every installed copy.
+//
+// Node built-ins only, per the hooks rule.
+import { mkdirSync, renameSync, rmSync, writeFileSync } from 'node:fs';
+import { dirname } from 'node:path';
+
+/**
+ * Commit `content` to `path` via a temp file and a rename, so a partial or
+ * failed write lands on a throwaway name and the target is never torn.
+ *
+ * The temp name carries this pid and a fresh random rather than a shared
+ * `<path>.tmp` slot, so concurrent writers never fight over it. That is also
+ * why a leaked temp is permanent: nothing ever picks the same name again, so
+ * the file sits in the vault forever, close after close. Both failure points
+ * leak one: the rename (the target stays untouched, which is the point) and
+ * the write itself (ENOSPC or EDQUOT partway through). Clean up on either, and
+ * never let the cleanup hide the error that got us here.
+ *
+ * Rename atomicity swaps the directory entry. It is NOT power-loss durable.
+ * there is no fsync, same as everything else in the vault.
+ *
+ * @param {string} path absolute path to write
+ * @param {string|Buffer} content bytes to commit
+ */
+export function atomicWrite(path, content) {
+  mkdirSync(dirname(path), { recursive: true });
+  const tmp = `${path}.${process.pid}.${Math.random().toString(36).slice(2, 10)}.tmp`;
+  try {
+    writeFileSync(tmp, content);
+    renameSync(tmp, path);
+  } catch (err) {
+    try {
+      rmSync(tmp, { force: true });
+    } catch {}
+    throw err;
+  }
+}