From 211b81cd94bce2c698778315b716cdfba47037ba Mon Sep 17 00:00:00 2001 From: tegwick Date: Sun, 16 Aug 2026 18:24:32 +0200 Subject: [PATCH] docs(workplans): RMGR-WP-0004 repository standards conformance (proposed) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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 --- ...P-0004-repository-standards-conformance.md | 203 ++++++++++++++++++ 1 file changed, 203 insertions(+) create mode 100644 workplans/RMGR-WP-0004-repository-standards-conformance.md diff --git a/workplans/RMGR-WP-0004-repository-standards-conformance.md b/workplans/RMGR-WP-0004-repository-standards-conformance.md new file mode 100644 index 0000000..1f34c23 --- /dev/null +++ b/workplans/RMGR-WP-0004-repository-standards-conformance.md @@ -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.