repo-manager/docs/repository-registers_v0.1.md

Repository registers v0.1

Repository registers are ordinary, versioned YAML files under registers/. They are authoritative in the repository; Repo Manager's index is a replaceable projection.

Shared envelope

Each register uses one file named registers/<kind>.yaml:

schema: repo-manager.register.v0
kind: technical-debt
entries:
  - id: TD-001
    title: Coupled persistence
    status: open
    severity: high
    created: "2026-08-21T10:00:00+00:00"
    updated: "2026-08-21T10:00:00+00:00"
    notes: []

Entry ids are stable within their register. created is immutable; mutations advance updated. Deletion-compatible routes map to defer, preserving the entry and Git history. Notes are append-only objects with content, author, and created.

Kinds and compatibility fields

Kind	Required create data	State Hub compatibility
sbom-inventory	package_name, ecosystem	package/version/licence entries; snapshots and reports are derived
repo-goals	description	repository goal records
upstream-contributions	type	contribution type and target metadata
technical-debt	none beyond id/title	severity, debt type, location, notes
extension-points	none beyond id/title	priority, extension type, location
register-entries	register_kind	generic extension register entries

Additional kind-specific fields are retained as YAML scalars, lists, or mappings. The envelope fields id, title, status, notes, created, and updated may only be changed through their governed command parameters.

Commands

rmgr register put --kind technical-debt --entry-id TD-001 \
  --title "Coupled persistence" --data-json '{"severity":"high"}'
rmgr register list --kind technical-debt
rmgr register note --kind technical-debt --entry-id TD-001 --note "Owner assigned."
rmgr register defer --kind technical-debt --entry-id TD-001

Mutations use the same expected-HEAD, idempotency, Git commit, optional push-seal, normalized-event, reindex, and dual-run-meter mechanism as workplan and task mutations.

Derived SBOM inventory

SBOM is the exception to ordinary register mutation: recognised lockfiles and a reviewed root sbom-tools.yaml remain authoritative. Repo Manager derives a replaceable snapshot and licence/copyleft report without copying State Hub rows back into a new source-of-truth file.

rmgr sbom scan --path . --output sbom-snapshot.json
rmgr sbom licence-report --path .

Detection covers uv.lock, requirements.txt, package-lock.json, yarn.lock, Cargo.lock, go.sum, .terraform.lock.hcl, Ansible requirements under ansible/, and root sbom-tools.yaml. Each source carries a SHA-256 and the snapshot carries the Git revision and canonical UTC generation timestamp. An output file is optional evidence, never authority, and is not overwritten without --force.