repo-manager/docs/cache-rebuild_v1.md

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

### 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:

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