coulomb/repo-manager
4
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
repo-manager/docs/cache-rebuild_v1.md
tegwick 5dc2f3cdf6 feat(cache): add rebuild and provenance safeguards 
Assistant: codex
Assistant-Model: gpt-5.6-sol
Assistant-Session: 01a023c0-a0a3-7c03-b395-5a0d2757214d
2026-08-21 23:23:03 +02:00

2.2 KiB
Raw Blame History

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