From ddd6a667300df960e20d76570f16af049e797ab9 Mon Sep 17 00:00:00 2001 From: tegwick Date: Sun, 16 Aug 2026 02:46:47 +0200 Subject: [PATCH] docs(workplans): STATE-WP-0080 register project-flavor awareness (proposed) Captures the SHR-WP-0001-T01 residual: statehub register scaffolds INTENT.md and a flavor-derived workplan prefix for prj- repos, both of which the project-repository-flavor standard forbids. Root cause: statehub_register.py has no reference to .repo-classification.yaml, category, or repo_flavor anywhere, so it cannot distinguish a project repo from a durable product repo. Hit twice now (prj-state-hub-retirement, prj-canon-federation). T08 carries the fix forward to repo-manager so it is not stranded in a component scheduled for retirement. Co-Authored-By: Claude Opus 5 --- ...-0080-register-project-flavor-awareness.md | 206 ++++++++++++++++++ 1 file changed, 206 insertions(+) create mode 100644 workplans/STATE-WP-0080-register-project-flavor-awareness.md diff --git a/workplans/STATE-WP-0080-register-project-flavor-awareness.md b/workplans/STATE-WP-0080-register-project-flavor-awareness.md new file mode 100644 index 0000000..7394088 --- /dev/null +++ b/workplans/STATE-WP-0080-register-project-flavor-awareness.md @@ -0,0 +1,206 @@ +--- +id: STATE-WP-0080 +type: workplan +title: "statehub register: project-repository flavor awareness" +domain: infotech +repo: state-hub +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: + - CFED-WP-0001 + - SHR-WP-0001 +--- + +# statehub register: project-repository flavor awareness + +## 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. + +This is the residual recorded in `SHR-WP-0001-T01`: + +> 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). + +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. + +## Root cause + +`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: + +- `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`. + +The governing standard is +`the-custodian/canon/standards/project-repository-flavor_v0.1.md`, which states: + +> 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. + +and names shipping both `INTENT.md` and `GOAL.md` an explicit anti-pattern. + +## Detect repository flavor + +```task +id: STATE-WP-0080-T01 +status: todo +priority: high +``` + +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. + +Treat classification as authoritative when present and disagreeing with the slug +prefix, and warn on the mismatch rather than guessing silently. + +## Scaffold GOAL.md instead of INTENT.md for project repos + +```task +id: STATE-WP-0080-T02 +status: wait +priority: high +``` + +For project-flavor repos: + +- 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. + +For all other flavors, behaviour is unchanged. + +## Fix workplan prefix inference + +```task +id: STATE-WP-0080-T03 +status: wait +priority: medium +``` + +`_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). + +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 + +```task +id: STATE-WP-0080-T04 +status: wait +priority: medium +``` + +`: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. + +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. + +## Update generated templates and briefs + +```task +id: STATE-WP-0080-T05 +status: wait +priority: medium +``` + +Make every generated artifact flavor-correct: + +- `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. + +Confirm `make update-agent-instructions` regenerates conformant files for an +existing `prj-` repo, not just at first registration. + +## Add a conformance check + +```task +id: STATE-WP-0080-T06 +status: wait +priority: low +``` + +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. + +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. + +## Cover with tests + +```task +id: STATE-WP-0080-T07 +status: wait +priority: medium +``` + +Extend `tests/test_statehub_register_cli.py`: + +- 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. + +## Carry the fix forward past State Hub retirement + +```task +id: STATE-WP-0080-T08 +status: wait +priority: medium +``` + +State Hub is being retired (`STATE-WP-0079`, `prj-state-hub-retirement`). +Repository scaffolding and representation are slated to land in `repo-manager`. + +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.