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 registrar (interim)

Until UUIDv5 derivation lands (RMGR-WP-0005-T03), only the registrar instance may mint state_hub_workstream_id / state_hub_task_id into files (ADR-007 decision 2). Other hubs may read and project; they must not write new hub primary keys into git.

Signal	Registrar?
STATEHUB_REGISTRAR=1 / true / yes / on	yes
STATEHUB_REGISTRAR=0 / false / no / off	no
env unset, hostname starts with railiance	yes
env unset, any other hostname	no

Accepted cost: new workplan/task registration requires connectivity to the registrar. Disconnected work cannot register until T03. Implementation: repo_manager.registrar.is_identifier_registrar; consumed by statehub fix-consistency C-06 / C-11 / C-32.

The production fleet sweep is disabled and is not the interactive recovery path. Repo Manager provides a bounded on-demand registrar for one clean, up-to-date repository at a time:

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 grants STATEHUB_REGISTRAR=1 only to its scoped child process. Agents must not export that variable themselves. If the command is unavailable, send one deduplicated request to repo-manager; repeated fix-consistency runs cannot resolve the gate and waste execution time.

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