hypomnema 1.8.2 → 1.9.0

package/scripts/verify.mjs

@@ -19,6 +19,7 @@ import { existsSync, readFileSync, readdirSync, statSync } from 'fs';
 import { join, relative, extname } from 'path';
 import { resolveHypoRoot, expandHome } from './lib/hypo-root.mjs';
 import { loadHypoIgnore, isScanIgnored } from './lib/hypo-ignore.mjs';
+import { DAY_MS } from './lib/time.mjs';
 
 // ── arg parsing ──────────────────────────────────────────────────────────────
 
@@ -130,7 +131,7 @@ for (const file of files) {
   if (!fm.verify_by) {
     missing.push(entry);
   } else if (fm.verify_by_date && /^\d{4}-\d{2}-\d{2}$/.test(fm.verify_by_date)) {
-    const daysUntil = Math.ceil((new Date(fm.verify_by_date) - new Date(today)) / 86400000);
+    const daysUntil = Math.ceil((new Date(fm.verify_by_date) - new Date(today)) / DAY_MS);
     if (fm.verify_by_date < today) {
       overdue.push({ ...entry, daysOverdue: -daysUntil });
     } else if (daysUntil <= 14) {

package/scripts/weekly-report.mjs

@@ -18,6 +18,7 @@ import { existsSync, mkdirSync, writeFileSync } from 'fs';
 import { join } from 'path';
 import { resolveHypoRoot, expandHome } from './lib/hypo-root.mjs';
 import { loadSessionEntries, auditEntries } from './session-audit.mjs';
+import { DAY_MS } from './lib/time.mjs';
 
 function parseArgs(argv) {
   const args = {
@@ -46,7 +47,7 @@ function isoWeek(date) {
   const dayNum = d.getUTCDay() || 7;
   d.setUTCDate(d.getUTCDate() + 4 - dayNum);
   const yearStart = new Date(Date.UTC(d.getUTCFullYear(), 0, 1));
-  const week = Math.ceil(((d - yearStart) / 86400000 + 1) / 7);
+  const week = Math.ceil(((d - yearStart) / DAY_MS + 1) / 7);
   return `${d.getUTCFullYear()}-W${String(week).padStart(2, '0')}`;
 }
 

package/templates/SCHEMA.md

@@ -2,7 +2,7 @@
 title: Wiki Schema
 type: schema
 updated: YYYY-MM-DD
-version: 2.2
+version: 2.3
 ---
 
 # Wiki Schema
@@ -59,18 +59,38 @@ Files responsible for session continuity — separate from the type taxonomy abo
 
 **Operations**:
 - Session start: root `hot.md` → project `hot.md` → `session-state.md`
-- Session close: update project `hot.md` (what was done) + `session-state.md` (what to do next) + root `hot.md`
+- Session close: update project `hot.md` (what was done) + `session-state.md` (what to do next)
 
-**Pointer table row format** (`hypo-hot-rebuild.mjs` parses this with a fixed regex — wrong col3 format causes the row to be silently skipped):
+Root `hot.md` is not something a session writes. It is a generated file: the
+hooks rebuild it by scanning `projects/*/hot.md` at every session start and
+stop, so a hand edit to it is overwritten by the next rebuild. This is the
+one place to look when a project does not show up in the table.
+
+**Pointer table row format** (generated by `formatRootHotProjection` in
+`hooks/hypo-shared.mjs`, fed by a directory scan in
+`scanRootHotProjectionSources` in the same file):
 
 ```
-| <Project Name> | YYYY-MM-DD | [[projects/<slug>/hot]] |
+| <slug> | YYYY-MM-DD | [[projects/<slug>/hot]] |
 ```
 
+The table holds one row per subdirectory of `projects/` that has a `hot.md`
+file. A project with no `hot.md` yet gets no row; delete or move that file to
+drop the project from the table.
+
 Column semantics:
-- col 1 (name): preserved as-is from the existing row
-- col 2 (date): **ignored on read** — rebuilt from `projects/<slug>/hot.md` frontmatter `updated:` (falls back to today if the file is absent)
-- col 3 (wikilink): must be `[[projects/<slug>/hot]]` — no trailing path, no markdown link `[text](url)`. Extra trailing columns are discarded during canonical rebuild (not dropped).
+- col 1 (name): always the slug (the directory name under `projects/`), never
+  that project's frontmatter `title`
+- col 2 (date): that project's `hot.md` frontmatter `updated:` field, left
+  blank when the file is missing, unreadable, or the value is not a
+  well-formed `YYYY-MM-DD` string. It is never defaulted to today.
+- col 3 (wikilink): always `[[projects/<slug>/hot]]`
+
+Rows sort by date descending, blank dates last, ties broken by slug
+ascending, so two machines scanning the same tree produce byte-identical
+output. The root file's own frontmatter `updated:` is the max of the row
+dates (or blank when every row is dateless), not the day the file itself was
+last rewritten.
 
 ---
 

package/templates/gitignore

@@ -12,3 +12,14 @@
 # match the staging name, and a crash between the link and its cleanup leaves one
 # behind — where `git add -A` would happily pick it up.
 *.lock.*.tmp
+
+# Migration backup of a hand-authored root hot.md, written the first time
+# writeRootHotProjection takes over a file it does not already own (see
+# hooks/hypo-shared.mjs). Never tracked: it can hold whatever a person's own
+# uncommitted notes held, and a scoped auto-commit must never pick it up.
+/hot.md.pre-projection-backup*.md
+# atomicWrite's own temp file for the backup write above
+# (`<backupPath>.<pid>.<random>.tmp`): carries the same hand-authored bytes
+# until the rename that produces the file matched above, so a kill or power
+# loss mid-write must not leave it exposed to `git add -A` either.
+/hot.md.pre-projection-backup*.tmp

package/templates/hypo-automation.md

@@ -14,12 +14,12 @@ session continuity, and git sync.
 
 ## Hook Overview
 
-All 15 hooks registered in `hooks/hooks.json` are listed below, in registration order.
+All 12 hooks registered in `hooks/hooks.json` are listed below, in registration order.
 
 | Hook | Event | Purpose |
 |------|-------|---------|
 | `hypo-close-guard.mjs` | `PreToolUse` | Blocks a direct Write/Edit/MultiEdit bypass of the session-close approval flow |
-| `hypo-session-start.mjs` | `SessionStart` | Injects `hot.md` and `session-state.md` into context on session start |
+| `hypo-session-start.mjs` | `SessionStart` | Rebuilds the root `hot.md` projection, then injects `hot.md` and `session-state.md` into context on session start |
 | `hypo-session-end.mjs` | `SessionEnd` | Records the dying session's identity so a `/clear` can be detected and recovered from on the next start |
 | `hypo-first-prompt.mjs` | `UserPromptSubmit` | Injects a one-line resume summary on the first prompt after a session start or cwd change |
 | `hypo-lookup.mjs` | `UserPromptSubmit` | Searches the wiki index for each prompt and injects matched pages as context |
@@ -27,12 +27,9 @@ All 15 hooks registered in `hooks/hooks.json` are listed below, in registration
 | `hypo-personal-check.mjs` | `PreCompact` | Detects missing session-close files, uncommitted wiki changes, or lint blockers and surfaces them as a `systemMessage`; it does not block `/compact` |
 | `hypo-auto-stage.mjs` | `PostToolUse` | Auto-stages a wiki file after it is written |
 | `hypo-web-fetch-ingest.mjs` | `PostToolUse` | Nudges Claude to ingest WebFetch/WebSearch results into `sources/` |
-| `hypo-hot-rebuild.mjs` | `Stop` | Rebuilds root `hot.md`'s pointer table and frontmatter at session end |
-| `hypo-session-record.mjs` | `Stop` | Appends the completed session to the session index |
-| `hypo-auto-commit.mjs` | `Stop` | Stages, commits, and pushes this session's touched wiki paths |
-| `hypo-auto-minimal-crystallize.mjs` | `Stop` | Blocks `Stop` when the session did substantial work, the user signalled wrap-up, and no close was recorded. A substantial session with no close signal is let through |
-| `hypo-cwd-change.mjs` | `CwdChanged` | Builds `additionalContext` with the matching project's `hot.md` when the working directory changes mid-session, but `CwdChanged` has no field Claude Code forwards to the model, so this output does not currently reach Claude |
-| `hypo-file-watch.mjs` | `FileChanged` | Builds `additionalContext` for a changed vault file once it passes the ignore and visibility filters. Nothing in this package registers watch paths, so the event has no trigger here, and `FileChanged` output does not reach Claude either way |
+| `hypo-stop.mjs` | `Stop` | Runs the session-end chain as four ordered stages, one after another, not in parallel: rebuilds the root `hot.md` projection, appends the session to the session index, stages/commits/pushes this session's touched wiki paths, then blocks `Stop` if the session did substantial work, the user signalled wrap-up, and no close was recorded |
+| `hypo-cwd-change.mjs` | `CwdChanged` | Builds a `systemMessage` with the matching project's `hot.md` when the working directory changes mid-session. `additionalContext` is not among `CwdChanged`'s documented output fields, so this never becomes `additionalContext`; the reference says only that it "shows the `systemMessage` as a brief terminal notification," without saying whether it also reaches the model. 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, with no branch that forwards it to the model; no live-session observation of this path exists either way, and this event is treated as not reaching the model until the documentation says otherwise |
+| `hypo-file-watch.mjs` | `FileChanged` | Builds a `systemMessage` for a changed vault file once it passes the ignore and visibility filters, 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 (see the row above). On a stock install the event still has no trigger here, because nothing in this package returns `watchPaths` to seed the watch list; that list is session-global, so another hook or plugin seeding it would still make this matcher-less group fire, though it returns immediately for any path that does not start with `HYPO_DIR` (a string-prefix check, not a symlink-resolving one) |
 
 This file is copied into a vault only at `init` time, and no update channel pushes a later fix here into a vault that already exists. So this copy can be older than the shipped one. `hooks/hooks.json` in the package is the source of truth for which hook runs on which event; when this table disagrees with it, the table is what went stale.
 
@@ -45,8 +42,8 @@ remove the remote if you do not want it.
 
 - `hypo-session-start.mjs` (`SessionStart`) runs `git pull --ff-only` before it reads any
   vault file. It waits for that pull, up to a 10 second timeout.
-- `hypo-auto-commit.mjs` (`Stop`) runs `git pull` and `git push` after committing this
-  session's touched paths.
+- `hypo-stop.mjs` (`Stop`) runs `git pull` and `git push`, via its `hypo-auto-commit.mjs`
+  stage, after committing this session's touched paths.
 
 **The update check.** `hypo-session-start.mjs` also spawns a background check that fetches
 two URLs:
@@ -65,15 +62,15 @@ affect the git sync above.
 
 ```
 Session start
-  └─ hypo-session-start.mjs → reads hot.md + session-state.md → injects context
+  └─ hypo-session-start.mjs → rebuilds root hot.md → reads hot.md + session-state.md → injects context
 
 During session
   └─ hypo-auto-stage.mjs → git-adds any wiki path a tool touched (not only .md edits)
   └─ hypo-web-fetch-ingest.mjs → after WebFetch/WebSearch, nudges an ingest
   └─ hypo-lookup.mjs → BM25-matches each prompt against the wiki index
 
-Session end (Stop chain, in order)
-  └─ hypo-hot-rebuild.mjs → refreshes root hot.md
+Session end (single Stop hook, hypo-stop.mjs, running four stages in order)
+  └─ hypo-hot-rebuild.mjs → refreshes root hot.md (same generator SessionStart also calls)
   └─ hypo-session-record.mjs → appends to the session index
   └─ hypo-auto-commit.mjs → git commit + push
   └─ hypo-auto-minimal-crystallize.mjs → blocks Stop if session close never ran

package/templates/hypo-config.md

@@ -1,7 +1,7 @@
 ---
 title: Hypomnema Config
 type: config
-version: "1.8.2"
+version: "1.9.0"
 created: YYYY-MM-DD
 ---
 

package/templates/hypo-guide.md

@@ -2,7 +2,7 @@
 title: Wiki Operations Guide
 type: reference
 updated: YYYY-MM-DD
-version: 1
+version: 2
 tags: [wiki, guide, operations]
 ---
 
@@ -82,36 +82,63 @@ Ask: *"이 작업이 마무리되었나요? 세션을 정리(crystallize)할까
 1. Update `projects/<name>/session-state.md` (next tasks, overwrite)
 2. Update `projects/<name>/hot.md` (what was done, ≤500 words, overwrite)
 3. Append to `projects/<name>/session-log/YYYY-MM-DD.md` (daily shard, narrative entry, append-only)
-4. Update root `hot.md` pointer table + date
+4. Root `hot.md` is regenerated by the hooks from `projects/*/hot.md`, not hand-edited: step 2 above is what actually moves it.
 5. Run `/hypo:lint` and fix errors in files **you** touched — debt in other
    projects / shared pages you did not author is reported as a non-blocking
    notice, not a gate. (The documented `/hypo:crystallize` session-close path
    runs this lint automatically, scoped to the files it writes.)
-6. Verify with `/hypo:crystallize` in its `--check-session-close` mode: a dry-run of the
+6. Check with `/hypo:crystallize` in its `--check-session-close` mode: a dry-run of the
    **full** set of checks the PreCompact hook itself runs (close files + lint + design-history + feedback
-   projection), sharing one function (`precompactGateStatus`) with that hook. Only declare the
-   session closed once it prints **"Compact-ready"**. A "close files updated"
-   check alone is not enough to earn that signal: a lint error in a close file
-   or a feedback projection over-cap keeps the check red on its own.
+   projection), sharing one function (`precompactGateStatus`) with that hook. Its
+   **"Compact-ready"** line is a diagnostic of the whole vault, not the bar for calling a
+   session closed. It goes red for anything in the vault, including an uncommitted file
+   another session wrote, so on a shared vault a normal close can finish while it is still
+   red. A "close files updated" check alone is not enough to turn it green: a lint error in
+   a close file or a feedback projection over-cap keeps it red on its own.
    The live hook can still see a different set than this check does, because of
    `HYPO_SKIP_GATE` or a transcript-scoped lint error (pass `--transcript-path`
-   to include the last). Note that neither one stops `/compact` any more: the
-   hook reports what it finds and lets the compact through, so "Compact-ready"
-   is the bar for calling a session closed, not a lock on the command.
-   Pass `--session-id=<id>` to also see `marker_present`
-   (step 7). `--project=<slug>` narrows the check to one project (a scoped
+   to include the last). Neither one stops `/compact` any more: the hook reports what it
+   finds and lets the compact through.
+   Pass `--session-id=<id>` to also see `marker_present` and `close_state` (step 7).
+   `--project=<slug>` narrows the check to one project (a scoped
    diagnostic, JSON `scope: "project"`): green there means only that slug is
    close-complete, **not** that every project in the vault is. Use the plain
-   check for the go/no-go signal.
-7. Record the session-closed marker. The Stop hook blocks until this
-   session's per-session marker exists, and a hand-edit close (writing the files
-   directly + committing) never writes it; the marker is written only by the
-   crystallize writer, never by the hook (bypass guard). Normal path:
-   close via `/hypo:crystallize` (`--apply-session-close --session-id=<id> --transcript-path=<path>`),
-   which writes the marker once the gate is green. Hand-edit recovery: after
-   committing the files, run `/hypo:crystallize` (`--mark-session-closed --session-id=<id> --transcript-path=<path>`).
-   Both writers gate the marker on the SAME `precompactGateStatus` as `/compact`,
-   so the marker only lands when step 6 would print **"Compact-ready"**.
+   check when you want to know whether the whole vault is clean.
+7. Record the close checkpoint. The Stop hook blocks until this session's close
+   checkpoint receipt (`.cache/sessions/<id>/close-receipt.json`) is valid, and a hand-edit
+   close (writing the files directly + committing) never writes one; the receipt
+   is filed only by the crystallize writer, never by the hook (bypass guard). A
+   compat marker (`.cache/session-closed-<id>.marker`) is written right after the
+   receipt, for consumers that have not been updated to read the receipt itself.
+   The receipt certifies only what it names: that the file versions this close
+   wrote are in a specific commit. It does not certify that every change this
+   session made is saved, so the Stop hook still surfaces any other uncommitted
+   vault change as a separate notice, once per close, even after the checkpoint
+   is recorded. Normal path: close via `/hypo:crystallize`
+   (`--apply-session-close --session-id=<id> --transcript-path=<path>`), which files the
+   checkpoint once the gate is green. Hand-edit recovery: after committing the
+   files, run `/hypo:crystallize` (`--mark-session-closed --session-id=<id> --transcript-path=<path>`).
+   Both writers gate the checkpoint on `precompactGateStatus`, the gate `/compact`
+   uses, with one difference: the git check is narrower. An uncommitted file
+   inside the project folder being closed (`projects/<project>/`) blocks whether
+   or not this session has a record of writing it. An uncommitted file at the
+   root or in another project's folder blocks only when this session wrote it
+   through Write or Edit since its last auto-commit, and is otherwise a notice
+   (another session's, one of unknown ownership, or one this session changed
+   through a shell command). If the record of this session's writes cannot be
+   read, the check does not block on it and adds a notice that it could not
+   determine ownership. So it can land while step 6 still shows a git blocker
+   for someone else's dirty file.
+   Every other check (close files, hot.md, lint, feedback) is the same as step 6.
+   **The session is closed once the checkpoint receipt is issued**: the writer's result
+   reports `markerWritten: true` (apply) or `ok: true` (`--mark`), and
+   `--check-session-close --session-id=<id>` then reports `close_state: closed`. Declare the
+   close on that, not on "Compact-ready". If the writer reports the marker as not written, or
+   `close_state` is anything other than `closed`, the session is still open whatever step 6 says.
+   If `close_state` is `broken` because the commit an earlier close proved was dropped from
+   history (a reset or rebase), `--mark-session-closed` refuses with
+   `prior-checkpoint-rewritten` and leaves the old receipt alone: restore that commit, or ask
+   the user to close again with a new payload.
    `--session-id` is not optional on the apply path. Before it writes anything, the
    apply reads that session's transcript for evidence the **user** asked to close, and
    refuses the whole close (exit 1, nothing on disk, nothing committed) when the id is
@@ -157,10 +184,11 @@ Skip session close for: single bug fix, single-file edit, Q&A only.
 projects/<name>/
 ├── index.md          (working_dir: /path/to/repo)
 ├── prd.md
+├── hot.md            (copy from projects/_template/hot.md, then fill in the name and `updated:`)
 └── session-state.md
 ```
 
-Add to root `hot.md` active projects table.
+`hot.md` is the file that puts the project in the root table: the table is built by scanning `projects/*/hot.md`, so a project without one never gets a row, and `/hypo:resume` cannot find it from there. Copy it from `projects/_template/hot.md` rather than starting blank. Once it exists, the next session start or stop rebuilds root `hot.md` and the row appears on its own. The auto-project offer below creates all of these files for you.
 
 #### Auto-project offer
 
@@ -173,7 +201,7 @@ ignore it:**
 1. Ask the user with `AskUserQuestion` (or a plain Y/n question) whether to
    create the project.
 2. **On Yes** — run the scaffold helper once (it substitutes tokens, creates
-   the project files, adds the root `hot.md` row, and logs the entry):
+   the project files, regenerates root `hot.md` so the new row appears, and logs the entry):
    ```
    node ${CLAUDE_PLUGIN_ROOT}/scripts/lib/project-create.mjs --name <slug> --working-dir "$(pwd)"
    ```
@@ -198,7 +226,7 @@ ignore it:**
 
 1. Write final `session-state.md` (mark as complete)
 2. Update `projects/<name>/index.md` status
-3. Remove from root `hot.md` active table (or mark archived)
+3. There is no hand path to drop the root `hot.md` row: it is regenerated from `projects/*/hot.md` on every session start and stop, so the row stays as long as that file exists. To archive the project, move or delete `projects/<name>/hot.md` (or the whole project directory) so the next rebuild no longer finds it.
 
 ---
 

package/templates/hot.md

@@ -1,24 +0,0 @@
----
-title: Hot Cache — Pointer
-type: reference
-updated: YYYY-MM-DD
-tags: [wiki, operations]
----
-
-# Hot Cache
-
-> Read at session start → navigate to the relevant project session-state.md and hot.md.
-> Update at session close: project session-state.md, project hot.md, and this file's "Active Projects" table.
-
-## Active Projects
-
-| Project | Last Session | Hot Cache |
-|---|---|---|
-<!-- Row format: | Project Name | YYYY-MM-DD | projects/<slug>/hot (wikilink) | -->
-<!-- col2 date is rebuilt from projects/<slug>/hot.md frontmatter on each session close -->
-
-## Session Start Checklist
-
-1. Check this file for the relevant project link
-2. Read `projects/<name>/session-state.md` for next tasks if it exists
-3. Read `projects/<name>/hot.md` for project background