From 30a413380997499f577070066570631cecf6049a Mon Sep 17 00:00:00 2001 From: tegwick Date: Sun, 16 Aug 2026 18:24:56 +0200 Subject: [PATCH] docs(workplans): retarget STATE-WP-0080 to handoff after decision 747011c6 Repository standards conformance and governed scaffolding move to repo-manager (RMGR-WP-0004). Hubs are registers; they do not scaffold or rewrite repo files. T01-T04 become guard, delegate, correct the inventory disposition, and remove the templating path. T05-T08 are cancelled with pointers to their RMGR-WP-0004 successors, retained so the handoff stays legible. Co-Authored-By: Claude Opus 5 --- ...-0080-register-project-flavor-awareness.md | 212 +++++++++--------- 1 file changed, 101 insertions(+), 111 deletions(-) diff --git a/workplans/STATE-WP-0080-register-project-flavor-awareness.md b/workplans/STATE-WP-0080-register-project-flavor-awareness.md index 7394088..a8d364a 100644 --- a/workplans/STATE-WP-0080-register-project-flavor-awareness.md +++ b/workplans/STATE-WP-0080-register-project-flavor-awareness.md @@ -1,7 +1,7 @@ --- id: STATE-WP-0080 type: workplan -title: "statehub register: project-repository flavor awareness" +title: "statehub register: stop repo scaffolding, hand off to repo-manager" domain: infotech repo: state-hub status: proposed @@ -12,195 +12,185 @@ updated: "2026-08-16" parent_project: prj-state-hub-retirement parent_workplan: SHR-WP-0001 related: + - RMGR-WP-0004 + - STATE-WP-0079 - CFED-WP-0001 - SHR-WP-0001 +state_hub_workstream_id: "03f38314-7d2c-42ee-bd1e-b0cc555dc06b" --- -# statehub register: project-repository flavor awareness +# statehub register: stop repo scaffolding, hand off to repo-manager ## Goal -Make `statehub register` aware of the `prj-` project-repository flavor so that -scaffolding a project repo produces conformant files instead of files the -governing standard calls an anti-pattern. +Stop `statehub register` from producing non-conformant repository files, and +hand repository scaffolding and standards conformance to `repo-manager` — where +decision `747011c6` places them. -This is the residual recorded in `SHR-WP-0001-T01`: +**This workplan does not implement flavor awareness.** That is `RMGR-WP-0004`. +The state-hub side is a guard, a delegation, and a clean exit. -> Residual tooling gap: `statehub register` still scaffolds `INTENT.md` for -> ordinary repos — capture under a state-hub child workplan when T05 maps -> implementation streams (do not invent `INTENT.md` on `prj-` repos). +## Why this changed shape -It has now been hit twice — once when founding `prj-state-hub-retirement`, and -again on 2026-08-16 founding `prj-canon-federation`, where the scaffolded -`INTENT.md` and a generic `PRJ-WP-0001-statehub-bootstrap.md` both had to be -deleted by hand before the first `fix-consistency` run. +Drafted 2026-08-16 as a full flavor-awareness implementation inside +`statehub_register.py`; retargeted the same day after decision `747011c6`: -## Root cause +> 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. -`statehub_register.py` (872 lines) contains **no reference to -`.repo-classification.yaml`, `category`, or `repo_flavor`**. It has no way to -distinguish a project repository from a durable product repository, so: +Implementing here would have built the capability twice, inside the component +being retired under `STATE-WP-0079`, and deepened exactly the boundary violation +the hub refactor exists to remove. The originating residual (`SHR-WP-0001-T01`) +is unchanged; only its owner is. -- `KEY_CONTEXT_FILES` (`:25`) lists `INTENT.md` as a primary context file; -- `:248` writes `INTENT.md` unconditionally when absent; -- `:786`–`:790` treat a missing intent as a hard error, prompting interactively - and exiting with `ERROR: Intent is required to create INTENT.md.`; -- `:269` writes `{WP_PREFIX}-0001-statehub-bootstrap.md` with a prefix defaulted - from the repo slug (`:78`, `_default_wp_prefix`), yielding `PRJ-WP-` for every - `prj-` repo rather than a project-derived prefix; -- the generated `.custodian-brief.md` (`:634`) and templates (`:461`, `:509`, - `:525`, `:569`) all instruct agents to read `INTENT.md`. +Tasks T05–T08 below are `cancel`led with pointers to their `RMGR-WP-0004` +successors. They are retained rather than deleted so the handoff is legible. -The governing standard is -`the-custodian/canon/standards/project-repository-flavor_v0.1.md`, which states: +## The defect being contained -> Tooling that scaffolds repositories (e.g. `statehub register`) MUST treat -> `GOAL.md` + `repo_flavor: project` as sufficient purpose documentation for -> `prj-` repos and MUST NOT require inventing an `INTENT.md` that pretends the -> project is a permanent product. +`statehub_register.py` has no reference to `.repo-classification.yaml`, +`category`, or `repo_flavor` in 872 lines, so it cannot distinguish a project +repository from a durable product repository. It therefore: -and names shipping both `INTENT.md` and `GOAL.md` an explicit anti-pattern. +- writes `INTENT.md` unconditionally (`:248`) and treats missing intent as a hard + error (`:786`–`:790`), though `project-repository-flavor_v0.1` calls shipping + both `INTENT.md` and `GOAL.md` an anti-pattern and forbids requiring + `INTENT.md` on `prj-` repos; +- derives the workplan prefix from the slug (`:78`, `_default_wp_prefix`), + yielding `PRJ-WP-` for every project repo, so all `prj-` repos collide; +- writes a generic `{PREFIX}-0001-statehub-bootstrap.md` (`:269`) that competes + with the project's real foundation workplan. -## Detect repository flavor +Hit twice: `prj-state-hub-retirement` and `prj-canon-federation`, both requiring +manual deletion after registration. + +## Guard against non-conformant scaffolding ```task id: STATE-WP-0080-T01 status: todo priority: high +state_hub_task_id: "65c52600-15fe-45bd-82b1-dfeff54698af" ``` -Give the register path a flavor signal. Read `.repo-classification.yaml` -`category` when present, and `GOAL.md` frontmatter `repo_flavor` as a secondary -signal; fall back to the `prj-` directory/slug prefix. Surface the result as a -single value threaded through inference and scaffolding. +Add a minimal flavor guard to the register path — detect project flavor from +`.repo-classification.yaml` `category`, `GOAL.md` `repo_flavor`, or the `prj-` +slug prefix, and on a match **refuse to scaffold**, with a message pointing at +`repo-manager`, rather than writing files the standard forbids. -Treat classification as authoritative when present and disagreeing with the slug -prefix, and warn on the mismatch rather than guessing silently. +Deliberately a refusal, not an implementation: a partial flavor-aware templating +path here would become a second source of truth competing with `RMGR-WP-0004`. -## Scaffold GOAL.md instead of INTENT.md for project repos +Durable-repo behaviour is untouched. + +## Delegate registration scaffolding ```task id: STATE-WP-0080-T02 status: wait priority: high +state_hub_task_id: "ab1e079c-b36f-4bfc-a9fd-fb43f7f93924" ``` -For project-flavor repos: +Once `RMGR-WP-0004-T03` lands, route scaffolding through Repo Manager instead of +refusing, using the dual-run strangler pattern already proven in `RMGR-WP-0002` +and `RMGR-WP-0003`. Hub-side registration keeps only what a register legitimately +does: record the repo, its identity, and its host path. -- do not write `INTENT.md`, and do not prompt for intent (`:786`–`:790`); -- accept an existing `GOAL.md` as sufficient purpose documentation; -- when `GOAL.md` is absent, scaffold one from a template carrying the four - sections the standard requires — Outcome, Invariants, Success gates, Project - retirement — plus the recommended frontmatter (`repo`, `repo_flavor`, - `project_status`, `started`, `reviewed`); -- error only if neither `GOAL.md` nor enough input to generate one exists. +Coordinate the cutover point with `RMGR-WP-0004-T05`. -For all other flavors, behaviour is unchanged. - -## Fix workplan prefix inference +## Correct the inventory disposition ```task id: STATE-WP-0080-T03 status: wait priority: medium +state_hub_task_id: "91cb1a33-7748-4d65-bfbc-bad21234e364" ``` -`_default_wp_prefix` derives `PRJ-WP-` from any `prj-`-prefixed slug, which is -wrong for every project repo: the standard requires a prefix derived from the -project, not the flavor marker (`SHR-WP-` for State Hub Retirement, `CFED-WP-` -for canon federation). +Confirm the register/scaffolding capability is dispositioned `move` → +`repo-manager` in `prj-state-hub-retirement/inventory/`, not `keep`. If it is +recorded as `keep`, correct it and cite decision `747011c6` — `SHR-INV-0001` is +the retirement lane's source of truth, and a stale disposition would resurrect +the boundary violation during cutover. -For project-flavor repos, strip the `prj-` marker before deriving, and prompt or -require `--wp-prefix` rather than emitting a flavor-derived default. A prefix -collision across two `prj-` repos is the failure this prevents. - -## Decide the bootstrap workplan for project repos +## Remove the templating path ```task id: STATE-WP-0080-T04 status: wait -priority: medium +priority: low +state_hub_task_id: "342aa5e8-96d0-4832-be60-f48815a86f71" ``` -`:269` writes a generic `statehub-bootstrap` workplan. For project repos this -competes with the foundation workplan the project actually needs — in both real -cases it was deleted immediately. +After delegation is live and `RMGR-WP-0004-T06` compatibility tests pass, delete +the templating code from `statehub_register.py` — `INTENT.md` generation, the +`AGENTS.md` / `CLAUDE.md` / `.custodian-brief.md` templates, `project_rules/`, +and bootstrap-workplan generation. -Either skip it for project flavor, or replace it with a foundation-workplan -template shaped by the standard (confirm conventions, inventory participants, -map child workplans, define gates). Prefer skipping unless T05's template work -shows the foundation shape is genuinely reusable. +Sequence behind `STATE-WP-0079`'s strangler so removal lands with the rest of the +retirement rather than as an isolated breaking change. -## Update generated templates and briefs +## Moved: generated templates and briefs ```task id: STATE-WP-0080-T05 -status: wait +status: cancel priority: medium +state_hub_task_id: "03224fa5-56f1-4e32-bc2e-40457dceb9cc" ``` -Make every generated artifact flavor-correct: +Cancelled — moved to **`RMGR-WP-0004-T04`** by decision `747011c6`. -- `KEY_CONTEXT_FILES` (`:25`) — include `GOAL.md`; -- `.custodian-brief.md` orientation line (`:634`) — `GOAL.md` for project repos; -- `AGENTS.md` / `CLAUDE.md` / `scripts/project_rules/` templates (`:461`, - `:509`, `:525`, `:569`) — session start order `GOAL.md` → `SCOPE.md` → - history → active workplans, per the standard's agent conventions; -- `_ensure_context_files` (`:431`) — do not treat missing `INTENT.md` as a gap - on project repos. +Worth carrying forward explicitly: `make update-agent-instructions` runs +fleet-wide and shares the flavor-blind templates, so it silently re-breaks +conformant `prj-` repos on every run. That is a larger blast radius than first +registration, and it must not be lost in the handoff. -Confirm `make update-agent-instructions` regenerates conformant files for an -existing `prj-` repo, not just at first registration. - -## Add a conformance check +## Moved: conformance check ```task id: STATE-WP-0080-T06 -status: wait +status: cancel priority: low +state_hub_task_id: "47adb8e3-2a03-45b9-9647-fc4e42c58cd1" ``` -The standard ships a conformance checklist that is currently only human-checked. -Add a consistency check that flags a project-flavor repo which ships `INTENT.md` -alongside `GOAL.md`, is missing a required file, or uses a flavor-derived -workplan prefix. +Cancelled — moved to **`RMGR-WP-0004-T02`** by decision `747011c6`. -Advisory severity is sufficient — this is a convention violation, not data -corruption. Follow the existing `C-NN` numbering and register it in the -consistency-check catalog. +Conformance checking is the clearest case for the new boundary: judging whether a +repository satisfies its standard is repository representation, not hub +projection. Repo Manager exposes it as a command and a contract; the hub consumes +the result rather than computing it. -## Cover with tests +## Moved: tests ```task id: STATE-WP-0080-T07 -status: wait +status: cancel priority: medium +state_hub_task_id: "c056b8fd-d91b-4cf0-973c-d74d8e718dd1" ``` -Extend `tests/test_statehub_register_cli.py`: +Cancelled — moved to **`RMGR-WP-0004-T06`** by decision `747011c6`. -- registering a `prj-` repo with `category: project` writes `GOAL.md`, no - `INTENT.md`, and no flavor-derived prefix; -- registering an ordinary product repo is byte-identical to today's output - (regression guard — this workplan must not change durable-repo behaviour); -- classification/slug mismatch warns rather than silently choosing; -- re-running register on an existing conformant `prj-` repo is idempotent. +The byte-identical-output regression guard for durable repos stays essential: +the handoff must not change what ordinary repositories receive. -## Carry the fix forward past State Hub retirement +## Superseded: carry the fix forward ```task id: STATE-WP-0080-T08 -status: wait +status: cancel priority: medium +state_hub_task_id: "15eca52e-7c3b-40a7-b2a8-38b0313f57a8" ``` -State Hub is being retired (`STATE-WP-0079`, `prj-state-hub-retirement`). -Repository scaffolding and representation are slated to land in `repo-manager`. +Cancelled — superseded by decision `747011c6`, which answered this task's open +question outright. It asked whether `repo-manager` was close enough to take the +work; the decision settled that repository standards belong there regardless of +timing, and `RMGR-WP-0004` now carries the whole implementation. -Record where this flavor logic belongs after retirement and link it to the -inventory disposition for the register path, so the fix is not stranded in a -component scheduled for removal. If `repo-manager` is close enough to take it, -prefer implementing there and leaving `statehub register` with a thin -flavor-guard rather than a full templating path. - -Coordinate through `SHR-WP-0001` rather than duplicating its task list. +Retained as the record of where the retarget originated.