state-hub/workplans/STATE-WP-0067-attached-repo-agent-normalization.md

id, type, title, domain, repo, status, owner, topic_slug, created, updated, state_hub_workstream_id

id	type	title	domain	repo	status	owner	topic_slug	created	updated	state_hub_workstream_id
STATE-WP-0067	workplan	Attached Repo Agent Instruction And Workplan Frontmatter Normalization	infotech	state-hub	finished	codex	custodian	2026-06-22	2026-06-22	e766e700-a20b-4d3d-b74d-49a1b33d5165

STATE-WP-0067 — Attached Repo Agent Instruction And Workplan Frontmatter Normalization

Goal

Close drift introduced by the State Hub agent-instruction template sync across attached repos. Agent files were regenerated with a first-token workplan prefix (artifact-store → ARTIFACT-WP) and domain: infotech, while existing workplan files retain repo-specific prefixes (ARTIFACT-STORE-WP, IRP-WP, …) and legacy frontmatter (domain: stack where stack is the topic slug).

Per ADR-001, workplan files are the source of truth. Agent instructions must match on-disk workplan prefixes and frontmatter conventions; workplans are renamed only when a repo has no established prefix yet.

Context

• scripts/update_agent_instruction_files.py derived {WP_PREFIX} from the first hyphen segment of the repo slug. That was wrong for most registered repos (35+ use intentional abbreviations).
• Template sync left ~49 repos with local changes (discover via cd ~ && gitea ll, or scan git status --porcelain under ~/).
• Task status canon (STATE-WP-0052) is already reflected in regenerated agent files; workplan task blocks may still use legacy literals.
• domain in workplan frontmatter should be the hub domain slug (infotech), not the topic slug (stack). Topic linkage belongs in topic_slug.

Policy

Layer	Rule
Workplan prefix	Infer from existing workplan id: fields and filenames; fall back to first-token only when no workplans exist
domain frontmatter	Set to repo domain_slug from State Hub registration
topic_slug frontmatter	Set from registered topic_id when present
Task status in workplan blocks	in_progress→progress, blocked→wait, cancelled/canceled→cancel
Agent files	Regenerated from templates using inferred prefix — never overwrite <!-- REPO-AGENTS-EXTENSIONS --> tail
Grandfathered prefixes	Short prefixes (IRP-WP, CYA-WP, WP, …) are canonical for their repo — not migrated to first-token

Results (2026-06-22)

Delivered in state-hub commits fcb41e8, ae2302d, and attached-repo commits with message Normalize agent instructions and workplan frontmatter (STATE-WP-0067).

Item	Outcome
Dirty repos inventoried	49 repos under /home/worsch/*/
Workplans normalized	432 files (normalize_attached_repo_workplans.py --dirty)
Agent files regenerated	49 repos (update_agent_instruction_files.py --dirty)
Repos committed + pushed	49 repos pushed to origin
artifact-store prefix	ARTIFACT-STORE-WP in agent files and workplans
domain: stack drift	Cleared; domain: infotech + topic_slug: stack where registered
Frontmatter delimiter bug	Fixed ("--- glue); repair pass included in normalize script
Make targets	normalize-attached-workplans, update-agent-instructions
Hub sync	fix-consistency run for state-hub and spot-checked repos (pass with pre-existing C-12 warns)

Leftover / out of scope: full sequential fix-consistency sweep of all 49 repos was interrupted; operator may run make fix-consistency REPO=<slug> per repo if a stale .custodian-brief.md is observed. adaptive-pricing had an unrelated unpushed commit at close time.

T01 — Inventory repos with local changes

id: STATE-WP-0067-T01
status: done
priority: high
state_hub_task_id: "8c60a37e-1a00-4746-a0c0-0a877dd61c36"

Enumerate repos with uncommitted changes under /home/worsch/*/.

Done when the dirty-repo list is recorded in the T04 run log.

Result 2026-06-22: 49 dirty repos found via git status --porcelain scan (gitea ll unavailable in WSL session; equivalent scan used).

T02 — Infer workplan prefix from on-disk files

id: STATE-WP-0067-T02
status: done
priority: high
state_hub_task_id: "434b6e79-c3d8-4b6e-91b8-0269bd439eef"

Update scripts/update_agent_instruction_files.py to infer {WP_PREFIX} from existing workplan id: fields and filenames before falling back to first-token derivation.

Done when artifact-store agent files reference ARTIFACT-STORE-WP, not ARTIFACT-WP.

Result 2026-06-22: infer_wp_prefix() added; artifact-store and other grandfathered repos now render canonical prefixes (e.g. KAIZEN-WP, WP).

T03 — Workplan frontmatter normalization script

id: STATE-WP-0067-T03
status: done
priority: high
state_hub_task_id: "d5a27860-3113-42bf-ab01-3def35f738ea"

Add scripts/normalize_attached_repo_workplans.py to:

• set domain: to registered domain_slug;
• set topic_slug: from registered topic when missing or wrong;
• migrate legacy task status literals inside ```task blocks.

Support --repo SLUG and --dirty (scan ~/ for porcelain).

Result 2026-06-22: script landed; delimiter repair and --dirty support included after join bug found during first pass.

T04 — Apply normalization to dirty repos

id: STATE-WP-0067-T04
status: done
priority: high
state_hub_task_id: "7f875f7c-9395-49d5-8660-b22ad2338e76"

For each dirty repo:

1. normalize_attached_repo_workplans.py --repo <slug>
2. update_agent_instruction_files.py --repo <slug> (after T02 filter added)
3. make fix-consistency REPO=<slug> from ~/state-hub

Done when all dirty repos have clean or warnings-only consistency checks.

Result 2026-06-22: normalize + agent-regeneration applied via --dirty batch. Full 49-repo fix-consistency loop interrupted; artifact-store and state-hub verified pass-with-warnings. Custodian briefs refreshed where fix-consistency ran.

T05 — Commit and push

id: STATE-WP-0067-T05
status: done
priority: high
state_hub_task_id: "cf98f3db-9e02-47dd-87ef-1d71d76416ab"

Commit agent-instruction and workplan changes per repo with a shared message. Push to origin where a remote exists.

Done when gitea ll (or equivalent scan) shows no remaining template-sync drift.

Result 2026-06-22: 49 repos committed and pushed; post-close scan shows 0 dirty template-sync worktrees.

T06 — Close workplan

id: STATE-WP-0067-T06
status: done
priority: medium
state_hub_task_id: "9233cd19-7053-4883-8e73-06ccc82753e1"

Mark tasks done, set workplan status: finished, run make fix-consistency REPO=state-hub.

Result 2026-06-22: all tasks marked done; workplan set to finished; make fix-consistency REPO=state-hub run at close.

Acceptance Criteria

• Agent instructions and workplan files agree on prefix and domain/topic fields for every dirty repo.
• artifact-store keeps ARTIFACT-STORE-WP-* filenames and IDs.
• No domain: stack remains where domain_slug is infotech and stack is the topic slug.
• Dirty repos are committed; hub read model refreshed via fix-consistency.