hypomnema 1.8.4 → 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,17 +127,17 @@ 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
 
@@ -293,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)
   │
@@ -308,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

package/docs/CONTRIBUTING.md

@@ -129,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

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;
+  }
+}