docs: row 28 (canonical YAML pipeline) + bensig approvals + MemPalace#1173 status

CLAUDE.md row 28 documents the canonical-source pipeline (5a01aec)
that landed earlier today. PR table updated to reflect bensig's
2026-04-26 approvals on four of our open PRs:

  - MemPalace#1173 (HNSW quarantine wire): approved on the original 1-commit
    shape, then force-pushed two safety commits (cold-start gate +
    integrity sniff-test) after a production cold-start incident
    destroyed three healthy 253MB segments. Now mergeable=CONFLICTING
    against develop (which moved with MemPalace#1210, MemPalace#1205, MemPalace#976) — needs
    rebase + re-review.
  - MemPalace#1177, MemPalace#1198, MemPalace#1201: approved, mergeable, awaiting merge.

YAML manifest gets a new entry for the doc pipeline itself; FORK_CHANGELOG
regenerated to match. promises.md (in claude-config, not this repo)
got a long log entry covering today's full output.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: jphein

CLAUDE.md

@@ -63,6 +63,8 @@ Ruff for linting (`ruff check`), line length 100, target Python 3.9.
 
 24. **fix: gate `quarantine_stale_hnsw` to cold-start, not every reconnect** (commit `70c4bc6`, 2026-04-25) — `ChromaBackend._quarantined_paths` set tracks which palaces have already had the proactive drift check run in this process; `make_client()` skips `quarantine_stale_hnsw` on subsequent calls. **Symptom on canonical disks daemon:** `.drift-*` directories accumulating every 10–30 min throughout 2026-04-25 despite the daemon being the only writer (palace data is **not** Syncthing-replicated — only the source code under `~/Projects/` syncs; `/mnt/raid/projects/.stignore` excludes `mempalace-data`). **Root cause:** false-positive thrash. `chroma.sqlite3` mtime bumps per write (millisecond cadence) but HNSW segments flush on chromadb's internal batch cadence. Under steady write load the gap exceeds the 300s threshold (lowered from 3600s in PR #1173 after a real cross-machine drift segfault) even when nothing is corrupt — so the proactive check renames a valid HNSW segment, chromadb rebuilds, drift recurs as soon as the next batch lands. **Real cold-start drift still caught** — that's exactly when a fresh client opens a palace. **Real runtime drift still caught** — palace-daemon's `_auto_repair` calls `quarantine_stale_hnsw` directly on observed HNSW errors, bypassing this gate. 2 new tests in `test_backends.py` verify single-fire-per-palace and per-palace independence. Conftest clears the gate between tests. Worth bringing back upstream — false-positive shape applies to any high-write-rate deployment, not just daemon-strict.
 
+28. **feat: canonical YAML manifest + renderer for fork-ahead docs** (commit `5a01aec`, 2026-04-26) — `docs/fork-changes.yaml` is now the canonical source for the fork-ahead narrative. `scripts/render-docs.py` regenerates `FORK_CHANGELOG.md` from it; the README fork-change-queue table, this file's row inventory (rows 1–28), and `scratch/promises.md` are still hand-maintained but planned for marker-based render insertion in a follow-on commit. `scripts/check-docs.sh` extended with a render-parity check (calls `render-docs.py --check`) plus the existing test-count / commit-hash / upstream-PR-state checks. Researched towncrier, scriv, git-cliff, antsibull-changelog before going custom — none do single-source → multi-target render in this shape (keep-a-changelog#230 has been asking for this since 2018). Documentation workflow now lives in the **Documentation maintenance** section above.
+
 ### Merged into upstream (post-v3.3.1)
 
 - epsilon mtime comparison (upstream PR #610, merged 2026-04-12 by Arnold Wender — their threshold is 0.001, ours was 0.01, semantically equivalent)
@@ -117,10 +119,10 @@ As of 2026-04-25: 14 merged, 8 open (including #1198 + #1201), 10 closed (added
 | #1087 | open (`MERGEABLE`, 6/6 CI green) | `mempalace purge --wing/--room` CLI — destructive drawer removal (fork-ahead Row 4) |
 | #1094 | open (`CLEAN`, 6/6 CI green) | Coerce `None` metadatas → `{}` at `ChromaCollection.query/.get` boundary (closes #1020) |
 | #1142 | open (filed 2026-04-23) | `docs/RELEASING.md` with `mempalace-mcp` pre-release grep — fulfills #1093's release-checklist proposal, accepted by @bensig 2026-04-23 via email |
-| #1173 | open (filed 2026-04-24, CI green) | Call `quarantine_stale_hnsw()` in `make_client()`; lower threshold 3600→300s (production 0.96h-drift segfault). Complementary to #1062 which covers server startup. |
-| #1177 | open (filed 2026-04-24, CI green) | `.blob_seq_ids_migrated` marker guard — skip `sqlite3.connect()` on already-migrated palaces. Closes #1090. |
-| #1198 | open (filed 2026-04-24) | `_tokenize` None-document guard — closes the gap upstream's #999 None-metadata audit left in BM25 helpers. Three regression tests in `TestBM25NoneSafety`. |
-| #1201 | open (filed 2026-04-25) | `palace_graph.build_graph` skips None metadata — daemon `/stats` was 500-ing on a single legacy drawer; same gap class as #999 / #1094 in a read path the audit didn't reach. |
+| #1173 | **bensig-approved 2026-04-26 then force-pushed 2 safety commits** — `mergeable=CONFLICTING` after develop moved | Call `quarantine_stale_hnsw()` in `make_client()`; lower threshold 3600→300s. Cold-start gate (`70c4bc6`) + integrity sniff-test (`645ba20`) cherry-picked onto the PR branch after production cold-start destroyed three healthy 253MB segments. Approval was on the original 1-commit shape; needs re-review + rebase against develop. |
+| #1177 | **bensig-approved 2026-04-26**, mergeable | `.blob_seq_ids_migrated` marker guard — skip `sqlite3.connect()` on already-migrated palaces. Closes #1090. |
+| #1198 | **bensig-approved 2026-04-26** | `_tokenize` None-document guard — closes the gap upstream's #999 None-metadata audit left in BM25 helpers. Three regression tests in `TestBM25NoneSafety`. |
+| #1201 | **bensig-approved 2026-04-26** | `palace_graph.build_graph` skips None metadata — daemon `/stats` was 500-ing on a single legacy drawer; same gap class as #999 / #1094 in a read path the audit didn't reach. |
 | #1171 | **closed** 2026-04-25 | Cross-process write lock at `ChromaCollection` adapter — superseded by [#976](https://github.com/MemPalace/mempalace/pull/976) (`mine_global_lock` at the right layer) plus this fork's daemon-strict architecture. |
 | #659 | **merged** 2026-04-23 | Diary wing parameter (`tool_diary_write` / `tool_diary_read` accept `wing`, hook derives from transcript path) |
 | #661 | **merged** 2026-04-22 | Graph cache with write-invalidation |

FORK_CHANGELOG.md

@@ -24,6 +24,23 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 ### Added
 
 
+- **Canonical YAML manifest + renderer for fork-ahead docs** ([`5a01aec`](https://github.com/jphein/mempalace/commit/5a01aec))
+  The fork-ahead narrative previously lived (and drifted) across four
+  hand-edited files: README's fork-change-queue table, CLAUDE.md's row
+  inventory, FORK_CHANGELOG.md, and the promises tracker. New
+  ``docs/fork-changes.yaml`` is now the canonical source; running
+  ``scripts/render-docs.py`` regenerates FORK_CHANGELOG.md.
+  ``scripts/check-docs.sh`` extended with a render-parity check that
+  detects YAML→FORK_CHANGELOG drift, plus the existing test-count /
+  commit-hash / upstream-PR-state checks. Researched towncrier, scriv,
+  git-cliff, antsibull-changelog — none do single-source →
+  multi-target render in this shape. README/CLAUDE/promises
+  rendering planned for follow-on commits with marker-based
+  insertion.
+
+  *Files:* `docs/fork-changes.yaml`, `scripts/render-docs.py`, `scripts/check-docs.sh`, `FORK_CHANGELOG.md`, `CLAUDE.md`
+
+
 - **Phase D migration + PreCompact recovery write** ([`42817d7`](https://github.com/jphein/mempalace/commit/42817d7))
   ``migrate_checkpoints_to_recovery(palace_path, batch_size=1000)`` walks
   the main collection in pages, filters drawers with topic in

docs/fork-changes.yaml

@@ -24,6 +24,32 @@
 
 entries:
 
+  - id: doc-canonical-source
+    date: 2026-04-26
+    bucket: Added
+    commit: 5a01aec
+    area: Docs
+    summary: "Canonical YAML manifest + renderer for fork-ahead docs"
+    body: |
+      The fork-ahead narrative previously lived (and drifted) across four
+      hand-edited files: README's fork-change-queue table, CLAUDE.md's row
+      inventory, FORK_CHANGELOG.md, and the promises tracker. New
+      ``docs/fork-changes.yaml`` is now the canonical source; running
+      ``scripts/render-docs.py`` regenerates FORK_CHANGELOG.md.
+      ``scripts/check-docs.sh`` extended with a render-parity check that
+      detects YAML→FORK_CHANGELOG drift, plus the existing test-count /
+      commit-hash / upstream-PR-state checks. Researched towncrier, scriv,
+      git-cliff, antsibull-changelog — none do single-source →
+      multi-target render in this shape. README/CLAUDE/promises
+      rendering planned for follow-on commits with marker-based
+      insertion.
+    files:
+      - docs/fork-changes.yaml
+      - scripts/render-docs.py
+      - scripts/check-docs.sh
+      - FORK_CHANGELOG.md
+      - CLAUDE.md
+
   - id: phase-d-precompact
     date: 2026-04-26
     bucket: Added