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

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

prefix-uniqueness is detection only. It does not rename files. Registry: 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:

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:

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:

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:

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.