tegwick
833fa6e746
Assistant: codex Assistant-Model: gpt-5.6-sol Assistant-Session: 01a023c0-a0a3-7c03-b395-5a0d2757214d
89 lines
3.4 KiB
Markdown
89 lines
3.4 KiB
Markdown
---
|
|
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.
|