docs(workplans): RMGR-WP-0004 repository standards conformance (proposed)
Repo Manager takes ownership of the standards repositories must comply with — flavor, required files, naming, classification, conformance checking — and of governed scaffolding, per prj-state-hub-retirement decision 747011c6. Hubs are registers; they do not scaffold or rewrite repo files. Extends ADR-001 from data to behaviour. Receives the implementation retargeted out of STATE-WP-0080. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
This commit is contained in:
parent
3dd5822d31
commit
211b81cd94
1 changed files with 203 additions and 0 deletions
203
workplans/RMGR-WP-0004-repository-standards-conformance.md
Normal file
203
workplans/RMGR-WP-0004-repository-standards-conformance.md
Normal file
|
|
@ -0,0 +1,203 @@
|
|||
---
|
||||
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
|
||||
---
|
||||
|
||||
# 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
|
||||
```
|
||||
|
||||
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
|
||||
```
|
||||
|
||||
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
|
||||
```
|
||||
|
||||
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
|
||||
```
|
||||
|
||||
`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
|
||||
```
|
||||
|
||||
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
|
||||
```
|
||||
|
||||
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
|
||||
|
||||
```task
|
||||
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.
|
||||
Loading…
Add table
Add a link
Reference in a new issue