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

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

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

```bash
sbom-nexus scan . --output sbom-snapshot.json

# Deprecated compatibility aliases; both delegate to the sbom-nexus executable.
rmgr sbom scan --path . --output sbom-snapshot.json
rmgr sbom licence-report --path .
```

SBOM Nexus is the sole scanner and snapshot product owner. Repo Manager retains
these aliases only so existing repository workflows do not break; set
`SBOM_NEXUS_CLI` when `sbom-nexus` is not on `PATH`. Their JSON includes
`product_owner: sbom-nexus` and the Nexus `sbom-nexus.snapshot.v1` schema.
They also carry `repo_manager_context.mode: local-preview` with explicit false
values for authority, persistence, attempt/success advancement, and snapshot
history creation. See `docs/sbom-nexus-client-contract_v1.md` for the pinned
preview and production-service boundary.

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