---
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.