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 <noreply@anthropic.com>
This commit is contained in:
parent
73072e5058
commit
30a4133809
1 changed files with 101 additions and 111 deletions
|
|
@ -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.
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue