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

# Repository standards v0.1

Repo Manager **implements** Custodian canon. It does not author a second
definition. This note is an index.

| Concern | Canon |
| --- | --- |
| Categories and `.repo-classification.yaml` | `the-custodian/canon/standards/repo-classification-standard_v1.0.md` |
| `prj-` layout, `GOAL.md`, anti-pattern both purpose docs | `the-custodian/canon/standards/project-repository-flavor_v0.1.md` |
| One workplan prefix per repository | `the-custodian/canon/architecture/adr-007-workplan-identity-and-repo-worker-topology.md` |

## Flavor resolution

Precedence, then warn on disagreement (do not silently pick a winner for
operators — the first match is used only to choose the required-file set):

1. `.repo-classification.yaml` `category`
2. `GOAL.md` `repo_flavor`
3. slug prefix `prj-`

`prj-` layout (`GOAL.md`, no `INTENT.md`) applies when the slug starts
with `prj-` or `GOAL.md` declares `repo_flavor: project`. Not every
`category: project` repo is a `prj-` repo.

## Commands

```bash
rmgr conform --path .
rmgr prefix-uniqueness --root ..
```

`prefix-uniqueness` is detection only. It does not rename files.
Registry: [`config/workplan-prefix-registry.yaml`](../config/workplan-prefix-registry.yaml).

Work: `RMGR-WP-0004-T01`, `RMGR-WP-0004-T08`.

## Identifier derivation and legacy repair

UUIDv5 derivation is live fleet-wide (`RMGR-WP-0005`). Any State Hub instance
may reconcile canonical workplans, tasks, intakes, and decisions: the fleet
namespace plus canonical record id produces the same identifier and
byte-identical writeback on every instance. `STATEHUB_REGISTRAR` no longer gates
the State Hub C-06/C-11/C-32 paths. The normal path is:

```bash
rmgr sync --path . --push
```

This verifies that repository sources are committed and visible on the forge,
verifies the State Hub identity, and requests one central reconciliation of the
exact pushed commit. Disconnected work remains valid in files and receives an
explicit pending receipt rather than being written to a local cache database.

The production fleet sweep remains disabled. The compatibility command below
is retained only for sealed legacy identifier migration and repair; its name and
scoped environment preserve compatibility with older State Hub releases and do
not impose a single-writer rule on ordinary reconciliation:

```bash
uv run --project ~/repo-manager rmgr registrar-reconcile \
  --path /path/to/repo \
  --api-base http://127.0.0.1:18000 \
  --confirm-primary \
  --push
```

The command verifies the authoritative State Hub health endpoint, refuses dirty
or ahead/behind branches and retired Gitea origins, serializes local registrar
runs, and scopes its compatibility environment to the child process. Agents do
not need to export `STATEHUB_REGISTRAR`; ordinary `fix-consistency` runs derive
canonical identifiers without it.

`--confirm-primary` is an operator assertion, not endpoint discovery. Always
pass the central API explicitly; under ADR-010 the workstation service at
`127.0.0.1:8000` is a replaceable cache, while the standard central tunnel is
`127.0.0.1:18000`. The registrar verifies exactly the identifiers requested by
that invocation. Unrelated consistency failures remain visible but do not turn
a successfully verified scoped registration into a false failure.

Identity preflight follows the same scope. An invalid identifier or conflicting
UUID assignment in the requested set fails closed before State Hub runs. Legacy
identity defects elsewhere in the repository remain in the command evidence and
the consistency report, but do not block assignment of unrelated canonical
records. Empty-projection bootstrap remains a full-repository operation and
therefore still requires the complete identity set to pass.

The child consistency pass has a 15-minute ceiling. Exceeding it returns a
structured `statehub_timeout` result with output tails and the post-timeout
missing-ID scan; it must not terminate the caller with an uncaught traceback.

Work: `RMGR-WP-0005-T01`.

## Coding-assistant commit provenance

Interactive coding assistants keep the supervising human as Git author and add
standard trailers to the commit message:

```text
Assistant: codex
Assistant-Model: gpt-5
Assistant-Process: 12345@workstation
Assistant-Session: 01a023c0-a0a3-7c03-b395-5a0d2757214d
```

`Assistant` is required when the hook identifies an assistant. Model, process,
and session are emitted when known. Process identifiers include the host because
PIDs are host-local; session identifiers are opaque and must not contain
credentials. `Assistant-Model` is the canonical model attribution;
assistant-specific `Co-Authored-By` prompt conventions are deprecated because
the human remains the author and the model is not a co-owner.

The hook accepts stable, tool-neutral overrides `ASSISTANT_NAME`,
`ASSISTANT_MODEL`, `ASSISTANT_PROCESS`, and `ASSISTANT_SESSION`. It also performs
best-effort detection for Claude Code, Codex, and Grok variables. Tool-specific
variables are compatibility inputs, not this contract: launch wrappers should
set the neutral values when an exact model or stable session is required.

Install the governed hook and derive a report from repository history:

```bash
rmgr assistant-provenance install
rmgr assistant-provenance report --path .
```

The `prepare-commit-msg` hook never rejects a commit, does nothing for a human
environment, and does not duplicate existing trailer tokens. Known automation
with its own Git identity, currently `custodian-sync`, does not need assistant
trailers. History before the configured cutover commit stays unattributed; it
must not be inferred from timestamps or writing style.

Work: `RMGR-WP-0009`.