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

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

# 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

```task
id: RMGR-WP-0004-T01
status: todo
priority: high
state_hub_task_id: "dd2db30f-c48f-404d-a1b4-bd75b41d42f4"
```

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

```task
id: RMGR-WP-0004-T02
status: wait
priority: high
state_hub_task_id: "2c9b0cb1-f0f0-40f7-83ef-1828298338d3"
```

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

```task
id: RMGR-WP-0004-T03
status: wait
priority: high
state_hub_task_id: "8e6fa8d7-f169-44f5-bdc9-29376bb2ef64"
```

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

```task
id: RMGR-WP-0004-T04
status: wait
priority: medium
state_hub_task_id: "8cd3ba11-b16b-4910-8bf6-651a24d47b8c"
```

`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

```task
id: RMGR-WP-0004-T05
status: wait
priority: medium
state_hub_task_id: "8402b8b6-2a1e-4236-b27d-d50b6161a176"
```

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

```task
id: RMGR-WP-0004-T06
status: wait
priority: medium
state_hub_task_id: "faaeb016-3ba8-493a-bbdf-9227de24f720"
```

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.

## Enforce workplan identifier uniqueness

```task
id: RMGR-WP-0004-T08
status: wait
priority: high
```

Implement `ADR-007` decision 1 as a repository standard: `PREFIX-WP-NNNN` names
exactly one workplan fleet-wide, for all time.

- **Prefix ownership registry** — one prefix, one repository. New machinery: no
  such registry exists today. `C-26` checks prefix conformance *within* a repo
  against a canonical prefix, but nothing checks across repos.
- **Forward-only numbering** — a running number is never reused within a prefix,
  including after cancel, archive, or delete.
- **Prefixes derive from project or repository identity**, never from a flavor
  marker or category. This is what makes `PRJ-WP-` invalid by construction and
  connects back to T03.

Live violations to detect (fleet scan, 2026-08-16 — 955 hub workplans, 525
parseable identifiers):

```text
prefixes shared across repos:
  CUST-WP-      state-hub, the-custodian
  RAIL-BS-WP-   railiance-bootstrap, railiance-cluster
  RAILIANCE-WP- railiance-apps, railiance-forge, railiance-platform, railiance-telemetry

identifiers reused:
  CUST-WP-0000 / 0010 / 0045   the-custodian ×2 each
  RAILIANCE-WP-0015            railiance-platform, railiance-apps
  RAILIANCE-WP-0016            railiance-platform ×2, railiance-apps
```

Detection only. Remediating the existing collisions is an open ruling in
`ADR-007` § Migration and is not authorized by this task.

**This task gates `RMGR-WP-0005`.** Deterministic identifier derivation from a
non-unique identifier would manufacture UUID collisions rather than remove them.

## Confirm the canon boundary

```task
id: RMGR-WP-0004-T07
status: wait
priority: low
state_hub_task_id: "7fdd54fe-fba7-4713-9814-d4534ff19706"
```

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.