feat(cache): add rebuild and provenance safeguards

Assistant: codex
Assistant-Model: gpt-5.6-sol
Assistant-Session: 01a023c0-a0a3-7c03-b395-5a0d2757214d

docs/cache-rebuild_v1.md

@@ -0,0 +1,62 @@
+---
+id: RMGR-RUNBOOK-CACHE-0001
+type: runbook
+title: "Repository projection cache rebuild"
+version: "1"
+status: active
+created: "2026-08-21"
+updated: "2026-08-21"
+workplan_task: RMGR-WP-0005-T07
+---
+
+# Repository projection cache rebuild v1
+
+Repo Manager's local index is advisory. Repository files and Git history are
+authoritative; deleting `.repo-manager/index.json` cannot delete work.
+
+## Inspect and rebuild
+
+```bash
+rmgr cache status --path /path/to/repository
+rmgr cache rebuild --path /path/to/repository --slug repository-slug
+```
+
+Status always reports `advisory`, `observed_at`, `age_seconds`, the indexed and
+current source fingerprints, and explicit staleness reasons. Legacy indexes
+without a fingerprint are stale. A source file changing after observation is
+stale. Rebuild parses the files afresh and atomically replaces only the local
+JSON projection.
+
+The fingerprint covers workplans, intake/decision record locations, registers,
+classification, and the repository intent/goal file. It hashes relative paths
+and bytes so uncommitted authoritative changes are visible even when Git HEAD
+has not moved.
+
+## State Hub cache replacement gate
+
+Before replacing a legacy State Hub database, export the closed unbound
+workplan provenance:
+
+```bash
+rmgr cache export-closed \
+  --api-base http://127.0.0.1:8000 \
+  --output closed-workplan-provenance.json
+```
+
+The export is minimized to identity, repository, title, lifecycle, owner, and
+creation/update timestamps. It includes a canonical UTC generation timestamp
+and SHA-256 over canonical row JSON. The command refuses to overwrite an
+existing export unless `--force` is supplied.
+
+A database replacement is not authorized by this command. Before replacement:
+
+1. verify the export count and `rows_sha256`;
+2. prove that no live unbound file-derived records remain;
+3. prove that hub-native records have reached their one authoritative central
+   owner, or retain the old database;
+4. rebuild file-derived records into an isolated database and compare counts,
+   identifiers, statuses, and source provenance;
+5. switch the local cache only after the comparison passes.
+
+The old database remains a recoverable source until those gates pass. Repo
+Manager does not merge database-local file-derived state back into repositories.