docs+tooling: doc-freshness gate, documentation-pass policy, token-hygiene

Refresh CLAUDE.md for v0.10.0 (3 CI jobs incl. disabled test-cgal,
compile-time option matrix, reviewer/pages docs, agentic + token-hygiene
workflow patterns) and condense the historical Phase-8/audit logs to
pointers.

Add the documentation-pass process so the single-source-of-truth rules
stay enforced:
  * scripts/quality/check-doc-freshness.sh — string-only drift gate
    (version/date across CITATION/CHANGELOG/CLAUDE, doc-map count), <1 s,
    registered in run-all.sh + quality README.
  * doc/release-policy.md — "Documentation passes" subsection (triggers +
    docs:sync rule); fix stale Phase-milestone mapping (v0.10.0 was
    reviewer-ready, 9c→v0.11.0) and the test-cgal CI mention.

Add shared Claude config (un-ignore the two files only):
  * .claude/settings.json — permission allowlist for safe repo commands.
  * .claude/token-hygiene.md — Tier-3 cache-discipline user guide that
    CLAUDE.md instructs Claude to remind the user about.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

doc/release-policy.md

@@ -37,8 +37,9 @@ Phase milestone → MINOR-bump mapping (historical + planned):
 | `v0.2.0`  | Phase 2 (hyper-ideal geometry)                         |
 | `v0.7.0`  | Phase 7 complete (period matrix, fundamental domain)   |
 | `v0.9.0`  | Phase 9a + 9b + 8b-Lite                                |
-| `v0.10.0` | Phase 9c (4g-polygon, genus g > 1)                     |
-| `v0.11.0` | Phase 10a (harmonic + holomorphic 1-forms)             |
+| `v0.10.0` | Reviewer-ready: 100 % Doxygen, quality-gate suite, reviewer materials, compile-time matrix (no new geometry phase) |
+| `v0.11.0` | Phase 9c (4g-polygon, genus g > 1) *(planned)*         |
+| `v0.12.0` | Phase 10a (harmonic + holomorphic 1-forms) *(planned)* |
 | `v1.0.0`  | CGAL package submission-ready                          |
 
 ### Post-1.0 phase (planned, ≥ `v1.0.0`)
@@ -104,6 +105,36 @@ overhead.  We pay the click.
 This catches the `tests.md` itself going stale even if no other doc
 hardcodes the number.
 
+### Documentation passes
+
+The single-source-of-truth rules above only work if the docs are actually
+re-synced on a predictable schedule.  A "documentation pass" is the named
+ritual that does this.  Two rules make it durable instead of forgotten:
+
+**Anchor it to a trigger, never do it mid-task.**
+
+| Trigger | What the pass covers |
+|---|---|
+| **Release tag** | `CHANGELOG.md`, `CITATION.cff` (version + date), `doc/api/tests.md`, CLAUDE.md "Release state" + "Documentation map" count. |
+| **Feature branch, just before the PR** | Land all doc edits the branch implies as a single final `docs: sync` commit — so the doc update is part of every merge, not a separate event you can skip. |
+| **Mid-code-work** | **Do not fix docs inline.** Note the drift (a TODO, a memory decision-record, or a flagged follow-up task) and fold it into the next `docs: sync`.  Inline doc edits bloat the PR's scope and — for AI-assisted sessions — bust the prompt cache (see `.claude/token-hygiene.md`). |
+
+**Make drift visible with a cheap gate.**
+
+`scripts/quality/check-doc-freshness.sh` verifies the *string-only*
+cross-file invariants in well under a second (no build):
+
+* release version agrees across `CITATION.cff`, `CHANGELOG.md` (newest
+  section), and CLAUDE.md;
+* release date agrees across `CITATION.cff` and `CHANGELOG.md`;
+* the "N documents across …" count in CLAUDE.md's Documentation map
+  equals the actual `doc/**/*.md` file count.
+
+Run it as the first step of any documentation pass.  The two
+build-dependent checks it deliberately skips — `scripts/check-test-counts.sh`
+(needs a build dir) and `scripts/gen-headers-md.py` drift (needs Doxygen
+XML) — belong to the *release* pass, not the per-branch one.
+
 ---
 
 ## 3.  Release process (checklist)
@@ -137,7 +168,9 @@ The recipe that worked for v0.9.0 (after the false-start with PR #11 /
 7. **Open one PR** with all prep commits.  Title:
    `release: vX.Y.Z (<summary>)`.  Description: copy the new
    `CHANGELOG.md` section.
-8. **Wait for CI green** — `test-fast` + `test-cgal` + `doc-build`.
+8. **Wait for CI green** — `test-fast` + `quality-gates`.  (`test-cgal`
+   is disabled since 2026-05-26 — OOM-prone on the runner; run the CGAL
+   suite locally instead, see step 3.)
 9. **Merge** with a merge commit (the merge SHA becomes the release
    target).