hypomnema 1.6.1 → 1.7.0

package/docs/ARCHITECTURE.md

@@ -53,7 +53,12 @@ hypomnema/
 │   ├── Home.md, Overview.md, hypo-automation.md, hypo-help.md
 │   ├── pages/_index.md
 │   └── projects/_template/
-├── tests/runner.mjs          ← no-dependency test runner
+├── tests/
+│   ├── harness.mjs               ← test()/testAsync()/suite(), selection, reporting
+│   ├── helpers.mjs               ← fixtures shared by more than one area file
+│   ├── runner.mjs                ← entry: imports every *.test.mjs, owns no tests
+│   ├── parallel.mjs              ← runs the entry as N processes (`npm test`)
+│   └── <area>.test.mjs           ← one file per production area (26)
 ├── docs/                     ← ARCHITECTURE.md, CONTRIBUTING.md
 ├── .claude-plugin/plugin.json← plugin manifest
 └── package.json              ← npm metadata, no runtime deps
@@ -395,19 +400,49 @@ Default patterns: `*.pdf`, `*.zip`, `*.pem`, `*.env`, `*.key`, `*.crt`, `*creden
 
 ## Testing
 
-| Layer | Coverage |
+```
+tests/
+├── harness.mjs          ← test() / testAsync() / suite(), and how a run is selected
+├── helpers.mjs          ← fixtures used by more than one area file
+├── runner.mjs           ← the entry: imports every *.test.mjs, owns no tests itself
+├── parallel.mjs         ← runs the entry as N concurrent processes (`npm test`)
+└── <area>.test.mjs      ← one file per production area (26 of them)
+```
+
+Tests live next to the thing they test: `extensions.test.mjs`, `lint.test.mjs`,
+`proposal-base.test.mjs`, and so on. Two branches adding tests to different areas never touch
+the same file, which is the point of the layout. It is not about speed.
+
+Everything uses Node built-ins only. Fixtures are built in code with scoped helpers
+(`withTmpDir`, `withWiki`, `withCleanWiki`, `gitRepo`, …), each cleaning up in a `finally`.
+
+**Selection is by suite, never by test.** `suite(label)` opens a selection unit, and
+`--shard=i/n` keeps a whole suite in one process, in order. So tests inside one suite may build
+on each other, and suites may not build on each other. `node tests/parallel.mjs --shards=237`
+runs every suite alone in a fresh process and is the proof of that invariant. Run it whenever
+you add or split a suite.
+
+| Command | What it does |
 |---|---|
-| `hypo-shared.mjs` utilities | 7 unit tests |
-| `hypo-compact-guard.mjs` contract | 8 input/output tests |
-| `hypo-personal-check.mjs` contract | 6 input/output tests |
-| `init.mjs` smoke | ~6 (idempotency, dry-run, hook merge) |
-| `doctor.mjs` smoke | ~5 |
-| `upgrade.mjs` regression | ~10 (includes migration fixture) |
-| `lint.mjs` (fix / json / session-state) | ~10 |
-| Misc (`expandHome`, `resolveHypoRoot`, …) | ~remainder |
-| **Total** | Run `npm test` for the live count |
-
-Run with `npm test`. The runner uses only Node.js built-ins; tests create scoped temp dirs and clean up after themselves. The count above is a layout sketch — exact totals shift as lanes ship, so `npm test` is the source of truth.
+| `npm test` | `parallel.mjs`, cpu-count processes, suites round-robined across them |
+| `npm run test:serial` | the whole suite in one process; verdict-identical |
+| `node tests/runner.mjs --grep=<regex>` | just the matching tests, in seconds |
+| `node tests/runner.mjs --file=lint` | one area file |
+| `node tests/parallel.mjs --by-file` | one process per area file |
+| `node tests/parallel.mjs --shards=237` | every suite alone: the order-independence proof |
+
+Round-robin is the default rather than one-process-per-file, and the reason is measured, not
+assumed: on a 2026 laptop the whole suite runs in about 70s round-robined and about 100s
+`--by-file`. The areas differ by an order of magnitude in size, and `--by-file` starts all 26
+at once, which oversubscribes the cores. The big files (`extensions`, `proposal-base`,
+`close-global`) then finish last under contention while the small ones exit in seconds and
+leave the tail of the run half idle. Reach for `--by-file` to read one area's output, not to go
+fast.
+
+`  ✓ name` and `  ✗ name` are a contract, not decoration.
+`scripts/lib/fix-status-verify.mjs` parses them to map a fix number to its verdict, and reads
+the `// @fix #N:` anchors as a union across every `tests/*.mjs`, so the file an anchor sits in
+does not matter.
 
 ---
 
@@ -476,4 +511,4 @@ Requires `NPM_TOKEN` secret.
 
 Hypomnema follows semver. The release tooling (`scripts/bump-version.mjs`, `CHANGELOG.md`, `release.yml`) is documented in [CONTRIBUTING.md](CONTRIBUTING.md#release-process).
 
-Breaking schema or hook-format changes require a major bump and a corresponding `upgrade.mjs` migration fixture in `tests/runner.mjs`.
+Breaking schema or hook-format changes require a major bump and a corresponding `upgrade.mjs` migration fixture in `tests/upgrade.test.mjs`.

package/docs/CONTRIBUTING.md

@@ -52,7 +52,7 @@ See [ARCHITECTURE.md](ARCHITECTURE.md) for the full breakdown. Short version:
 | `hooks/hypo-shared.mjs` | Shared hook utilities — read the deployment constraint below |
 | `skills/<name>/SKILL.md` | Agent Skills (auto-trigger via description match) |
 | `templates/` | Files copied into new wiki vaults on init |
-| `tests/runner.mjs` | Test runner (no external deps) |
+| `tests/` | Test suite (no external deps): `harness.mjs`, `helpers.mjs`, `runner.mjs` (entry), and one `<area>.test.mjs` per production area |
 | `docs/` | ARCHITECTURE, CONTRIBUTING |
 | `.claude-plugin/plugin.json` | Plugin manifest |
 
@@ -79,14 +79,14 @@ Scripts under `scripts/` are not deployed and may freely import from `scripts/li
 2. Edit `scripts/<name>.mjs` — the Node.js logic.
 3. If the command is new and synthesis-heavy, add `skills/<name>/SKILL.md`.
 4. Update the command table in `README.md` and `README.ko.md`.
-5. Add coverage to `tests/runner.mjs`.
+5. Add coverage to the matching `tests/<area>.test.mjs` (a new command usually means a new area file).
 
 ### Adding or modifying a hook
 
 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`.
-4. Add a contract test in `tests/runner.mjs` (input → expected `additionalContext` shape).
+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.
 
 ### Modifying `hypo-shared.mjs`
@@ -105,7 +105,7 @@ If you need to share new logic, prefer extending an existing helper over adding
 1. Drop the file under `templates/`.
 2. Update `scripts/init.mjs` so `init` copies it.
 3. Update the templates section of [ARCHITECTURE.md](ARCHITECTURE.md#package-layout).
-4. Add a test in `tests/runner.mjs` that asserts the file lands in a freshly initialized vault.
+4. Add a test in `tests/init.test.mjs` that asserts the file lands in a freshly initialized vault.
 
 ### Adding an Agent Skill
 
@@ -119,13 +119,14 @@ If you need to share new logic, prefer extending an existing helper over adding
 ## Testing
 
 ```bash
-npm test           # tests/runner.mjs — unit + smoke + contract tests
+npm test           # tests/*.test.mjs, sharded across processes — unit + smoke + contract
 npm run lint       # scripts/lint.mjs — frontmatter + wikilink validation + W8 (design-history stale vs session-log)
 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 in
-                   # tests/runner.mjs. Maintainer dogfood; needs a local wiki at
+                   # a wiki spec against `// @fix #N: <test-name>` anchors, read as a
+                   # union across every tests/*.mjs. Maintainer dogfood; needs a wiki at
                    # $HYPO_DIR or ~/hypomnema (source checkout only; not shipped in
-                   # the npm package). Does NOT grep ADR core decision lines.
+                   # the npm package). Phase 2 also greps each manifest adrKeyLine
+                   # against the production corpus.
 ```
 
 > **`fix:verify` needs an explicit `--spec`.** The default path
@@ -243,7 +244,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-`) may appear in your local notes and in `tests/` / `qa-runs/` (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`. `check-tracker-ids` gates every surface (`--all`/`--staged` for files, `--commit-msg` for messages, `--tag` for the tag body); the migration keeps the CHANGELOG body clean.
+- Internal tracker ids (`FEAT-`, `IMPR-`, `ISSUE-`, `PRAC-`, `fix #N`) may appear in your local notes and in `tests/` / `qa-runs/` (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.
 
 ### The `## Changelog` block
 
@@ -323,10 +324,13 @@ command.
 Every Hypomnema release must carry Korean alongside the English body
 in **both** the CHANGELOG section AND the git tag annotation. The release
 workflow enforces this with `scripts/check-bilingual.mjs`; a lightweight tag, or
-a gated CHANGELOG section missing its `#### 한국어` sub-block, will block `npm publish`. It also requires the
-release version to appear in **both** `README.md` and `README.ko.md`
-(`scripts/check-readme-version.mjs`) — the floor that stops the README reconcile
-from being dropped.
+a gated CHANGELOG section missing its `#### 한국어` sub-block, will block `npm publish`.
+
+The READMEs are not part of a release. They describe what Hypomnema does now, not
+what each version added, so cutting a release never edits them. Version history
+lives in `CHANGELOG.md` alone. (A gate used to require the release version to
+appear in both READMEs, back when they carried a rolling version narrative. That
+narrative is gone, and the gate with it.)
 
 Prerequisite: the changelog collector in step 2 reads merged-PR data through the GitHub CLI, so have `gh` installed and authenticated (`gh auth status`) before you start. It is a maintainer-only release script and is not shipped to npm.
 
@@ -360,32 +364,31 @@ node scripts/collect-changelog.mjs --strict   # maintainer-only; not shipped to
 #    "#### English" and a "#### 한국어" sub-block; check:bilingual enforces it.
 $EDITOR CHANGELOG.md
 
-# 3. Reconcile BOTH READMEs — add a v<version> sentence to the rolling version
-#    narrative in README.md AND README.ko.md, and update the first-viewport
-#    "current release" pointer. (Dropped 3x historically; check:readme is the floor.)
-$EDITOR README.md README.ko.md
+#    The READMEs need no edit here. They describe current behavior, so a release
+#    only touches them when the behavior itself changed.
 
-# 4. Verify locally before tagging (the full gate set CI + prepublishOnly run)
+# 3. Verify locally before tagging (the full gate set CI + prepublishOnly run)
 npm test                   # unit suite
 npm run lint               # vault linter
 npm run check:versions     # all version-carrying files (incl. package-lock) agree
 npm run check:bilingual    # each gated CHANGELOG section has #### English + #### 한국어
-npm run check:readme       # v<version> present in BOTH READMEs
 npm run smoke:plugin       # plugin manifest + hooks/commands/skills load-valid
 npm run smoke-pack         # packed tarball installs and resolves
 npm run check:tracker-ids  # no private-tracker pointers leaked into shipped files
 
-# 5. Commit — include EVERY file the bump touched, the READMEs, and the lockfile.
+# 4. Commit every file the bump touched, plus the lockfile.
 git add package.json package-lock.json .claude-plugin/ templates/hypo-config.md \
-        CHANGELOG.md README.md README.ko.md
+        CHANGELOG.md
 git commit -m "chore: release v<version>"
 #    Then open the release PR, pass review + green CI, and squash-merge to main.
 
-# 6. Tag the merge commit with an ANNOTATED tag, never a lightweight tag.
+# 5. Tag the merge commit with an ANNOTATED tag, never a lightweight tag.
 #    Annotation body shape: English summary, then "---" on its own line,
 #    then a Korean summary block. The GitHub Release republishes this body
 #    verbatim, so keep it on the same public surface as the CHANGELOG: PR
-#    numbers (#N) only, no internal tracker ids (check-tracker-ids --tag gates it).
+#    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.
 git tag -a v<version> -m "$(cat <<'EOF'
 Hypomnema v<version>: <one-line English summary>
 
@@ -399,17 +402,17 @@ Hypomnema v<version>: <한 줄 한글 요약>
 EOF
 )"
 
-# 7. Rehearse the release locally (same checks CI runs against the tag)
+# 6. Rehearse the release locally (same checks CI runs against the tag)
 node scripts/check-bilingual.mjs --tag v<version>
 node scripts/check-versions.mjs --tag v<version>
 node scripts/check-tracker-ids.mjs --tag v<version>   # no tracker ids leak into the tag body
 npm publish --dry-run --access public   # packs + prepublishOnly, NO registry PUT
 
-# 8. Push the SPECIFIC tag alone — NOT --tags (that would push stale local tags
+# 7. Push the SPECIFIC tag alone — NOT --tags (that would push stale local tags
 #    and could trigger releases for versions you did not intend).
 git push origin v<version>
 
-# 9. (minor+ releases only) After the release workflow succeeds, close the spec
+# 8. (minor+ releases only) After the release workflow succeeds, close the spec
 #    lifecycle IN PLACE (no path move): set status: archived and
 #    archived_date: <release date> in the same spec, run the wiki lint, then
 #    commit and push the vault. Do this only after the release is green, never at
@@ -425,8 +428,7 @@ The `release.yml` workflow then:
 2. Smokes the plugin channel — manifest, `hooks/hooks.json` targets, and
    command/skill component files (`scripts/smoke-plugin.mjs`).
 3. Validates the CHANGELOG section AND the tag annotation are bilingual
-   (`scripts/check-bilingual.mjs`), and that the version is present in both
-   READMEs (`scripts/check-readme-version.mjs`).
+   (`scripts/check-bilingual.mjs`).
 4. Runs `npm test` and `npm run lint`.
 5. Publishes to npm with `npm publish --access public --provenance` and creates
    the GitHub Release from the tag body.
@@ -446,7 +448,7 @@ token authenticates without publishing anything.
 | New `init` template file | minor |
 | Bug fix, doc-only change, internal refactor | patch |
 
-Major bumps must include an `upgrade.mjs` migration fixture in `tests/runner.mjs`.
+Major bumps must include an `upgrade.mjs` migration fixture in `tests/upgrade.test.mjs`.
 
 ---
 

package/hooks/base-store.mjs

@@ -0,0 +1,265 @@
+// base-store.mjs: per-session observed-base hash snapshot
+//
+// Lives in hooks/ rather than scripts/lib/ because hypo-session-start.mjs must
+// stay self-contained within this directory (an npm consumer may vendor hooks/
+// alone). scripts/ already imports from hooks/, never the reverse.
+//
+// The write=proposal gate needs to know what a session OBSERVED on disk when it
+// started, so crystallize can tell "nobody touched this page" from "someone else
+// wrote it while this session was alive". crystallize runs as a separate process
+// from the session, so the observation has to be parked somewhere both can read:
+// `<hypoDir>/.cache/sessions/<sessionId>/base.json` (gitignored, never synced).
+//
+// SessionStart writes it, crystallize reads it. Two invariants carry the design:
+//
+//   1. Existence-check, not overwrite. SessionStart fires again on resume and on
+//      compact with the SAME session_id (verified by spike). Re-snapshotting
+//      there would advance the base to whatever another session had just written,
+//      so close would compare base-to-itself, see no drift, and clobber the other
+//      session's edits. Single-session tests pass either way, which is exactly
+//      why this is pinned by a regression test and not left to reviewer memory.
+//      `/clear` mints a NEW session_id, so it gets a fresh snapshot, which is right:
+//      a cleared session restarts its observation from disk.
+//
+//   2. Advance after a successful direct write. Once crystallize legitimately
+//      overwrites a target, that content IS the new observed base. Without this,
+//      a second close in the same session would diff against the stale original
+//      and raise a false-positive proposal against its own first write.
+//
+// Everything here is best-effort: a hook must never fail a session start because
+// a cache write did not land. Read failures degrade to "base unknown", which the
+// caller treats as fail-safe (proposal), never as "no conflict".
+
+import { createHash } from 'node:crypto';
+import {
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  writeFileSync,
+  renameSync,
+  closeSync,
+  openSync,
+  writeSync,
+} from 'node:fs';
+import { join, dirname } from 'node:path';
+
+/** sha256 of a UTF-8 string, hex. */
+export function hashContent(content) {
+  return createHash('sha256').update(content, 'utf-8').digest('hex');
+}
+
+/**
+ * Hash of a file's bytes. Absent and unreadable are different answers: an absent
+ * file was genuinely observed as absent, while an unreadable one was not observed
+ * at all, and only the first makes "create it at close" safe.
+ * @returns {string|null|undefined} hex hash, `null` if absent, `undefined` if unreadable
+ */
+export function hashFile(path) {
+  if (!existsSync(path)) return null;
+  try {
+    return hashContent(readFileSync(path, 'utf-8'));
+  } catch {
+    return undefined;
+  }
+}
+
+/** `<hypoDir>/.cache/sessions/<sessionId>/base.json`. */
+export function basePath(hypoDir, sessionId) {
+  return join(hypoDir, '.cache', 'sessions', String(sessionId), 'base.json');
+}
+
+/** Atomic overwrite via tmp+rename, mirroring crystallize'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 and parse base.json. Returns null when absent, unreadable, or malformed. */
+function readBaseFile(hypoDir, sessionId) {
+  const path = basePath(hypoDir, sessionId);
+  if (!existsSync(path)) return null;
+  try {
+    const parsed = JSON.parse(readFileSync(path, 'utf-8'));
+    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) return null;
+    if (!parsed.targets || typeof parsed.targets !== 'object') return null;
+    return parsed;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Snapshot the observed base hashes for `relPaths`, ONCE per session.
+ *
+ * Existence-check (invariant 1): when base.json already exists for this session,
+ * this is a no-op: resume and compact must not move the base.
+ *
+ * A target that does not exist on disk is recorded as `null` (observed-absent),
+ * which is distinct from having no entry at all (observed-nothing). Close treats
+ * the first as "I saw no file, creating it is safe" and the second as fail-safe.
+ *
+ * @param {string} hypoDir
+ * @param {string} sessionId
+ * @param {string[]} relPaths vault-relative target paths
+ * @returns {{created: boolean, reason?: string}}
+ */
+export function snapshotBase(hypoDir, sessionId, relPaths) {
+  if (!sessionId) return { created: false, reason: 'no-session-id' };
+  const path = basePath(hypoDir, sessionId);
+  if (existsSync(path)) return { created: false, reason: 'already-snapshotted' };
+
+  const targets = {};
+  for (const rel of relPaths) {
+    if (!rel) continue;
+    const h = hashFile(join(hypoDir, rel));
+    // `undefined` (unreadable) is left OUT of the map on purpose: no entry means
+    // "unknown", and close fails safe into a proposal rather than assuming a
+    // file it could not read was unchanged.
+    if (h !== undefined) targets[rel] = h;
+  }
+
+  const body = JSON.stringify(
+    { session_id: String(sessionId), created_at: new Date().toISOString(), targets },
+    null,
+    2,
+  );
+
+  try {
+    mkdirSync(dirname(path), { recursive: true });
+    // Exclusive create IS the existence-check, closing the gap between the
+    // existsSync above and the write below when two hooks race on one session.
+    const fd = openSync(path, 'wx');
+    try {
+      writeSync(fd, body);
+    } finally {
+      closeSync(fd);
+    }
+    return { created: true };
+  } catch (e) {
+    if (e && e.code === 'EEXIST') return { created: false, reason: 'already-snapshotted' };
+    // best-effort: a hook must never break a session start over a cache write
+    return { created: false, reason: `write-failed: ${e && e.message}` };
+  }
+}
+
+/**
+ * Look up one target's observed base, as a discriminated state.
+ *
+ *   'hash'     this session observed content; `hash` holds it
+ *   'absent'   this session observed the file missing, so creating it is safe
+ *   'unknown'  this session never observed it: no snapshot, wrong session,
+ *              unreadable at snapshot time, or a target set that shifted
+ *              mid-session because cwd moved
+ *
+ * `state` is the discriminator on purpose. An earlier shape returned
+ * `{known, hash}` where BOTH 'absent' and 'unknown' carried `hash: null`, so a
+ * consumer branching on `if (!entry.hash)` would read never-observed as
+ * safe-to-write and quietly defeat the guard. Branch on `state`, never on the
+ * truthiness of `hash`.
+ *
+ * @returns {{state: 'hash'|'absent'|'unknown', hash: string|null}}
+ */
+export function readBaseEntry(hypoDir, sessionId, relPath) {
+  const unknown = { state: 'unknown', hash: null };
+  if (!sessionId) return unknown;
+  const parsed = readBaseFile(hypoDir, sessionId);
+  if (!parsed) return unknown;
+  if (!Object.prototype.hasOwnProperty.call(parsed.targets, relPath)) return unknown;
+  const hash = parsed.targets[relPath];
+  if (hash === null) return { state: 'absent', hash: null };
+  if (typeof hash !== 'string' || hash === '') return unknown;
+  return { state: 'hash', hash };
+}
+
+/**
+ * Move one target's base to `hash` after this session legitimately wrote it
+ * (invariant 2). No-op when the session has no snapshot: with no base there is
+ * no guard to keep honest.
+ *
+ * @returns {boolean} true when the base file was updated
+ */
+export function advanceBase(hypoDir, sessionId, relPath, hash) {
+  if (!sessionId) return false;
+  const parsed = readBaseFile(hypoDir, sessionId);
+  if (!parsed) return false;
+  parsed.targets[relPath] = hash;
+  try {
+    atomicWrite(basePath(hypoDir, sessionId), JSON.stringify(parsed, null, 2));
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Advance a target's base to its current on-disk bytes after the session edited
+ * it DIRECTLY (Write/Edit tool), not through crystallize. Invariant 2 covers
+ * crystallize's own overwrites; this covers the other way a session legitimately
+ * changes a guarded target.
+ *
+ * Without it, a direct edit looks — at close time — exactly like a DIFFERENT
+ * session having written the page: base != disk, so the guard fails safe into a
+ * false proposal against the session's own work. `open-questions.md` is the most
+ * exposed target, because `/hypo:crystallize` tells the model to fold same-session
+ * edits into the close payload. A PostToolUse hook calls this after each wiki
+ * write to give the session's own edits provenance.
+ *
+ * Scoped by tracked-ness, NOT by a target list: `relPath` advances only when the
+ * session already has a base entry for it (one of the four overwrite targets
+ * snapshotted at start, for the active project). A write to any other wiki file
+ * is a no-op, so this never mints a new base key and cannot widen the guard's
+ * surface. The file is hashed only once the target is confirmed tracked, so an
+ * unrelated write costs one small base.json read and no content hash.
+ *
+ * An absent or unreadable post-write file leaves the base untouched (returns
+ * false) rather than advancing it to null: a target that vanished is a real
+ * divergence the close should still fail safe on, not a provenance claim.
+ *
+ * `knownHash`: when the caller already has the exact bytes the tool wrote (the
+ * Write tool carries its full `content`), pass their hash. The base then advances
+ * to what the SESSION wrote, not to a fresh disk read — race-safe: if another
+ * session overwrote the target in the window between the tool and this call,
+ * base = my-bytes ≠ disk, so the close still sees drift and preserves the other
+ * write. Callers without the full bytes (Edit/MultiEdit) pass null and take a
+ * post-write disk read, which carries a narrow tool→hook race (documented
+ * residual in the spec's 보증 범위).
+ *
+ * This does not weaken the base contract's "no read-just-before-write as base"
+ * rule (spec line 40): only the session's OWN writes advance, so a concurrent
+ * writer's change to the same target is still observed as drift.
+ *
+ * @returns {boolean} true when the base file was updated
+ */
+export function advanceBaseForWrite(hypoDir, sessionId, relPath, absPath, knownHash = null) {
+  if (!sessionId) return false;
+  const parsed = readBaseFile(hypoDir, sessionId);
+  if (!parsed) return false;
+  // Only a tracked target advances. hasOwnProperty, not truthiness: an
+  // observed-absent entry is `null` but still a legitimate key to advance from.
+  if (!Object.prototype.hasOwnProperty.call(parsed.targets, relPath)) return false;
+  const hash = typeof knownHash === 'string' ? knownHash : hashFile(absPath);
+  if (typeof hash !== 'string') return false; // absent/unreadable → leave base as-is
+  parsed.targets[relPath] = hash;
+  try {
+    atomicWrite(basePath(hypoDir, sessionId), JSON.stringify(parsed, null, 2));
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * The four overwrite targets crystallize replaces wholesale. `project` may be
+ * null when cwd resolves to no project; the two project-scoped paths are then
+ * omitted and close falls back to proposal for them.
+ */
+export function overwriteTargets(project) {
+  const targets = ['hot.md', join('pages', 'open-questions.md')];
+  if (project) {
+    targets.unshift(join('projects', project, 'session-state.md'));
+    targets.unshift(join('projects', project, 'hot.md'));
+  }
+  return targets;
+}

package/hooks/hooks.json

@@ -143,5 +143,11 @@
       }
     ]
   },
-  "shared": ["hypo-shared.mjs", "version-check.mjs", "version-check-fetch.mjs"]
+  "shared": [
+    "hypo-shared.mjs",
+    "version-check.mjs",
+    "version-check-fetch.mjs",
+    "base-store.mjs",
+    "proposal-store.mjs"
+  ]
 }