2026-08-21 17:15:21 +02:00
|
|
|
# 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.
|
2026-08-21 23:15:48 +02:00
|
|
|
|
|
|
|
|
## 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
|
|
|
|
|
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`.
|
