repo-manager/docs/cache-rebuild_v1.md

id	type	title	version	status	created	updated	workplan_task
RMGR-RUNBOOK-CACHE-0001	runbook	Repository projection cache rebuild	1	active	2026-08-21	2026-08-22	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

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:

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.

Prove a file-derived rebuild in an empty projection

Use the registrar bootstrap only against a fresh or disposable State Hub whose projection for the target repository is empty:

rmgr registrar-reconcile \
  --path /path/to/repository \
  --api-base http://127.0.0.1:58005 \
  --confirm-primary \
  --bootstrap-empty-projection

The command requires a clean checkout synchronized with Forgejo and a healthy target. It refuses multi-repository or remote scans, proves that the selected repository has zero projected workplans before mutation, scopes registrar authority to the child consistency process, and then verifies every authoritative workplan, task, intake, and decision UUID. It restores the generated .custodian-brief.md if that is the only checkout change and fails closed on any authoritative file mutation.

Run a second read-only consistency pass against the same target. A passing rebuild has no issues and has the same record identifiers, lifecycle statuses, and source bindings as the files. This operation deliberately does not copy progress events, token events, or messages; those hub-native records must pass their own central-owner gate before any legacy database is discarded.