repo-manager/workplans/RMGR-WP-0004-repository-standards-conformance.md

id	type	title	domain	repo	status	owner	topic_slug	created	updated	parent_project	parent_workplan	related
RMGR-WP-0004	workplan	Repository standards conformance and governed scaffolding	infotech	repo-manager	proposed	codex	infotech	2026-08-16	2026-08-16	prj-state-hub-retirement	SHR-WP-0001	STATE-WP-0080 STATE-WP-0079 RMGR-WP-0001 CFED-WP-0001

Repository standards conformance and governed scaffolding

Goal

Establish Repo Manager as the owner of the standards repositories must comply with — flavor, required files, naming conventions, classification, and conformance checking — and of the governed scaffolding that creates conformant repositories.

Hubs are registers. They index and project repository-owned records; they do not scaffold, template, or rewrite repository files. This workplan moves that capability to its correct owner.

Decision basis

prj-state-hub-retirement decision 747011c6 (2026-08-16, Bernd Worsch):

Hubs are registers: they index and project repository-owned records. They do not scaffold, template, or rewrite repository files. Repo Manager owns repository representation and governed mutation, and therefore owns the standards repositories must comply with.

This extends ADR-001 (hub is a read model) from data to behaviour. A hub that writes INTENT.md, AGENTS.md, .custodian-brief.md, and bootstrap workplans into repositories is already outside its own boundary — the register path is repo mutation wearing hub clothing.

It is a placement correction rather than a scope expansion: SCOPE.md already claims "repository registration, identity, classification, and lifecycle" and "controlled repository mutation through explicit commands and policy checks".

Model repository standards explicitly

id: RMGR-WP-0004-T01
status: todo
priority: high

Give Repo Manager a first-class representation of the standards a repository is expected to satisfy, rather than encoding them implicitly in a scaffolding script. At minimum:

• flavor — product, tooling, research, business, experimental, project (prj-), and how it is determined (.repo-classification.yaml category, GOAL.md repo_flavor, slug prefix, in that precedence);
• required files per flavor, with the purpose document differing by flavor (INTENT.md for durable repos, GOAL.md for prj-);
• naming conventions — repo slug, workplan prefix derivation;
• anti-patterns that are violations rather than gaps (shipping both INTENT.md and GOAL.md; a flavor-derived workplan prefix).

Source standards: project-repository-flavor_v0.1.md and repo-classification-standard_v1.0.md in the Custodian canon. Canon stays authoritative; Repo Manager implements against it and must not fork the rules into a second definition.

Implement conformance checking

id: RMGR-WP-0004-T02
status: wait
priority: high

Check a repository against its flavor's standard and report violations with enough detail to fix them. Distinguish missing (a required file absent) from contradictory (an anti-pattern present) — the second is the more valuable signal and the one that went undetected twice.

Expose it as a command and as a contract other components can call, so the consistency lane and agent sessions get the same answer.

Known first findings, both live today:

• prj-canon-federation and prj-state-hub-retirement were each scaffolded with a forbidden INTENT.md that had to be deleted by hand;
• every prj- repo would collide on workplan prefix PRJ-WP-, because the prefix is derived from the flavor marker rather than from the project.

Own governed scaffolding

id: RMGR-WP-0004-T03
status: wait
priority: high

Take ownership of creating conformant repository files, replacing the templating currently embedded in state-hub/statehub_register.py (872 lines, with no reference to .repo-classification.yaml, category, or repo_flavor anywhere — the root cause of both failures).

Requirements:

• flavor-correct purpose document: GOAL.md for prj- repos with the four sections the standard requires (Outcome, Invariants, Success gates, Project retirement), INTENT.md for durable repos, never both;
• workplan prefix derived from the project, not the flavor marker; prompt or require explicit input rather than emitting a colliding default;
• no generic bootstrap workplan for project repos, which compete with the foundation workplan the project actually needs;
• scaffolding is a command in the Repo Manager sense — requested action distinct from confirmed repository state, with the resulting revision and a normalized event recorded (SCOPE.md § API boundary).

Behaviour for durable product repos must be preserved exactly; this workplan changes where the capability lives and how project repos are treated, not what ordinary repos receive.

Regenerate agent instructions per flavor

id: RMGR-WP-0004-T04
status: wait
priority: medium

make update-agent-instructions regenerates AGENTS.md, CLAUDE.md, .claude/rules/, and .custodian-brief.md from templates that assume every repo has an INTENT.md. Bring regeneration under the same flavor model so running it on a prj- repo produces the standard's session order — GOAL.md → SCOPE.md → history → active workplans — rather than reintroducing INTENT.md references on every run.

This matters beyond first registration: regeneration runs fleet-wide, so a flavor-blind template silently re-breaks conformant repos.

Accept the handoff from state-hub

id: RMGR-WP-0004-T05
status: wait
priority: medium

Coordinate the transfer with STATE-WP-0080, which is retargeted to a thin guard plus handoff rather than a parallel implementation:

• agree the cutover point at which statehub register delegates or refuses;
• confirm the register path's disposition in prj-state-hub-retirement/inventory/ reads move to repo-manager, not keep;
• keep SHR-WP-0001 as the coordination point; link by ID, do not duplicate its task list.

Follow the dual-run strangler pattern already proven in RMGR-WP-0002 and RMGR-WP-0003 rather than a flag-day switch.

Add compatibility and regression tests

id: RMGR-WP-0004-T06
status: wait
priority: medium

Per SCOPE.md § Initial extraction source, extraction must preserve behaviour with compatibility tests. Cover:

• a prj- repo scaffolds GOAL.md, no INTENT.md, no flavor-derived prefix;
• a durable repo's scaffolded output is byte-identical to the state-hub path (regression guard against changing ordinary-repo behaviour);
• conformance checking flags both known live findings from T02;
• flavor signals that disagree warn rather than silently resolving;
• re-running scaffolding on a conformant repo is idempotent.

Confirm the canon boundary

id: RMGR-WP-0004-T07
status: wait
priority: low

Repo Manager implements repository standards; it does not author them. Confirm with the Custodian that canon remains the authoritative source and record where the seam sits, so conformance rules do not drift into a second definition inside this repo.

If the ownership shift warrants it, the Custodian may want an ADR recording that repository-standards enforcement is a Repo Manager responsibility — that is a Custodian decision, raised from here, not made here.