diff --git a/workplans/STATE-WP-0052-task-state-canon-adaptation.md b/workplans/STATE-WP-0052-task-state-canon-adaptation.md new file mode 100644 index 0000000..8c6f7eb --- /dev/null +++ b/workplans/STATE-WP-0052-task-state-canon-adaptation.md @@ -0,0 +1,343 @@ +--- +id: STATE-WP-0052 +type: workplan +title: "Task State Canon Adaptation" +domain: custodian +repo: state-hub +status: proposed +owner: codex +topic_slug: custodian +created: "2026-05-25" +updated: "2026-05-25" +--- + +# STATE-WP-0052 - Task State Canon Adaptation + +## Goal + +Adapt State Hub and its attached repository coordination surfaces to the updated +InfoTechCanon task lifecycle. + +The canon now recommends the seed task lifecycle: + +| Code | Stored value | Meaning | +|------|--------------|---------| +| `WAIT` | `wait` | Blocked, paused, or waiting on another actor, event, decision, input, or condition. | +| `TODO` | `todo` | Ready or planned work that is not actively being worked. | +| `PROG` | `progress` | Active work in focus. | +| `DONE` | `done` | Completed successfully. | +| `CNCL` | `cancel` | Stopped because the work is no longer relevant, wanted, or valid. | + +State Hub currently persists and documents task states as: + +```text +todo, in_progress, blocked, done, cancelled +``` + +This workplan migrates the State Hub task model to the canon values while +preserving enough legacy compatibility for existing workplan files, API clients, +MCP clients, dashboards, automations, and attached repo agents to adapt safely. + +## Source Canon + +Primary source: + +- `info-tech-canon/infospace/models/task/InfoTechCanonTaskModel.md` +- `info-tech-canon/seeds/InfoTechCanonTaskModel_RC1_seed.md` + +Important canon rules to preserve: + +- persisted seed values are lowercase: `wait`, `todo`, `progress`, `done`, + `cancel`; +- `WAIT` covers blocked, paused, and waiting conditions; +- `PROG` should be the only active-work state; +- `CNCL` is final; +- `DONE` is terminal by default and should reopen only through an explicit + profile rule. + +## State Hub Profile Decisions To Confirm + +The first implementation pass should record these as explicit decisions before +changing code: + +- State Hub stores lowercase values, not uppercase codes. +- Old State Hub values are accepted as compatibility aliases: + `blocked -> wait`, `in_progress -> progress`, `cancelled -> cancel`, and + `canceled -> cancel`. +- `blocking_reason`, `needs_human`, and `intervention_note` remain separate + fields. A `wait` task is not automatically human-blocked unless those fields + say so. +- Workstream/workplan frontmatter lifecycle states remain separate and are not + changed by this workplan. +- Compatibility aliases are time-boxed and writebacks should prefer canonical + values. + +## Propagation Strategy For Attached Repos + +Attached repos are the active repos registered in State Hub via `GET /repos/`. +They should not be edited directly from the State Hub repo session. Instead: + +1. Publish a State Hub interface-change record with `repo_slug=info-tech-canon`, + `interface_type=schema`, `change_type=breaking`, and the active registered + repo slugs in `affected_repo_slugs`. +2. Let the interface-change publisher send inbox messages to affected repo + agents. +3. For repos that need local file or code changes, create ecosystem tasks with + titles prefixed `[repo:]`. +4. Include a short migration brief in every message/task: + `blocked -> wait`, `in_progress -> progress`, `cancelled/canceled -> cancel`, + `todo` and `done` unchanged. +5. Each target repo's own agent creates or updates its local workplan and makes + local edits. + +This uses the existing repo boundary rule and avoids cross-repo writes. + +## T01 - Capture The Canon Delta And State Hub Profile + +```task +id: STATE-WP-0052-T01 +status: todo +priority: high +``` + +Write a short State Hub design note for the task-state migration. + +Requirements: + +- cite the exact InfoTechCanon Task Model paths and relevant sections; +- record the State Hub profile decisions from this workplan; +- define the compatibility alias table; +- define terminal/reopen behavior for `done` and `cancel`; +- explain how `wait` relates to `needs_human`, `blocking_reason`, and + intervention workflows; +- state explicitly that workstream/workplan lifecycle states are out of scope. + +Done when the design note can be used as the implementation source of truth. + +## T02 - Inventory State Hub Impact + +```task +id: STATE-WP-0052-T02 +status: todo +priority: high +``` + +Inventory every State Hub surface that embeds task-state values. + +Expected areas: + +- API models, schemas, routers, and migrations; +- consistency and validation scripts; +- reconciliation and lifecycle services; +- MCP server docs and tool descriptions; +- dashboard status controls, filters, colors, sorting, charts, and docs; +- generated agent instruction templates; +- cleanup, recently-on-scope, execution, repo-sync, and token hooks; +- tests and fixtures; +- README and dashboard reference pages. + +Done when the workplan has an implementation checklist with affected files, +required changes, and risk notes. + +## T03 - Implement Compatibility Constants And Normalization + +```task +id: STATE-WP-0052-T03 +status: todo +priority: high +``` + +Introduce a single State Hub source of truth for task statuses and aliases. + +Requirements: + +- canonical statuses: `wait`, `todo`, `progress`, `done`, `cancel`; +- legacy aliases: `blocked`, `in_progress`, `cancelled`, `canceled`; +- helper functions to normalize file/API/DB inputs; +- status ordering for no-regress checks: `todo < wait/progress < done/cancel`; +- open status set: `wait`, `todo`, `progress`; +- terminal status set: `done`, `cancel`; +- UI labels and colors aligned with the canon palette where practical. + +Done when scripts, API code, and dashboard code no longer maintain independent +task-status literal sets except in tests that intentionally assert them. + +## T04 - Migrate Database And API Contract + +```task +id: STATE-WP-0052-T04 +status: todo +priority: high +``` + +Update the persisted task status model and public API. + +Requirements: + +- add an Alembic migration that converts existing rows: + `blocked -> wait`, `in_progress -> progress`, `cancelled -> cancel`; +- handle PostgreSQL enum replacement safely; +- keep `todo` and `done` unchanged; +- accept legacy aliases in request payloads during the compatibility window; +- return canonical values from read endpoints after migration; +- update OpenAPI/Pydantic schemas and validation errors; +- preserve soft-delete semantics currently tied to `cancelled` by moving them + to `cancel`. + +Done when existing data migrates cleanly and API responses expose only canonical +task values. + +## T05 - Update Workplan File Sync And Repo Guidance + +```task +id: STATE-WP-0052-T05 +status: todo +priority: high +``` + +Update file-backed workplan behavior and generated repo instructions. + +Requirements: + +- accept old task statuses in existing workplan files without immediate breakage; +- write canonical task statuses when the consistency engine patches files; +- update `AGENTS.md` guidance and project-rule templates; +- update session protocol text that talks about open tasks; +- update workplan examples and validation messages; +- update close-out instructions so operators run consistency after migration. + +Done when new workplans use `wait/todo/progress/done/cancel` and old files can +still sync through a deliberate migration window. + +## T06 - Update Dashboard, MCP, And Operational UX + +```task +id: STATE-WP-0052-T06 +status: todo +priority: high +``` + +Align human-facing and agent-facing State Hub surfaces. + +Requirements: + +- dashboard task controls show `wait`, `todo`, `progress`, `done`, `cancel`; +- filters, ordering, charts, KPI cards, and status chips use the new values; +- intervention pages distinguish `wait` from `needs_human`; +- MCP tool descriptions and docs advertise canonical values and alias behavior; +- operational docs explain the migration and the reason for the vocabulary + change; +- any "blocked tasks" view is renamed or clarified as human-blocked/waiting. + +Done when dashboard, MCP, and docs no longer present the old values as canonical. + +## T07 - Update Tests And Migration Fixtures + +```task +id: STATE-WP-0052-T07 +status: todo +priority: high +``` + +Revise tests to lock down the new lifecycle. + +Requirements: + +- unit tests for normalization aliases; +- DB migration tests for old-to-new values; +- API tests for canonical responses and legacy request aliases; +- consistency tests for no-regress ordering and file writeback behavior; +- reconciliation tests for `wait` plus `needs_human`/`blocking_reason`; +- dashboard tests for status controls and stale-current-status conflicts; +- documentation validation tests for generated instructions. + +Done when the full State Hub test suite passes and failures would catch +reintroduction of old canonical literals. + +## T08 - Prepare Attached Repo Adaptation Brief + +```task +id: STATE-WP-0052-T08 +status: todo +priority: high +``` + +Create a concise adaptation brief for all attached repos. + +Brief contents: + +- canon source and date; +- new task state table and old-to-new mapping; +- request to update local `AGENTS.md`/`CLAUDE.md`, workplan examples, scripts, + docs, dashboards, and tests if they mention task statuses; +- note that `wait` is broader than old `blocked`; +- note that `cancel` replaces `cancelled`/`canceled`; +- compatibility window expectations; +- State Hub API behavior after migration; +- how the repo should report completion. + +Done when the brief is ready to embed in interface-change messages and +`[repo:]` ecosystem tasks. + +## T09 - Publish Interface Change And Route Repo Requests + +```task +id: STATE-WP-0052-T09 +status: todo +priority: high +``` + +Notify attached repos through State Hub rather than editing them directly. + +Requirements: + +- query active registered repos from `GET /repos/`; +- classify repos by likely impact: + State Hub clients, repos with workplans/agent instructions, repos with task + status code, and no-direct-impact repos; +- create and publish one `schema` / `breaking` interface-change record from + `info-tech-canon`; +- include all active registered repos that should receive the canon notice in + `affected_repo_slugs`; +- create `[repo:]` ecosystem tasks for repos that need local adaptation; +- use broadcast only for general awareness, not as the only tracking mechanism + for repos needing changes. + +Done when every attached repo has either an inbox message, a targeted ecosystem +task, or a recorded no-impact classification. + +## T10 - Roll Out, Verify, And Close Compatibility Window + +```task +id: STATE-WP-0052-T10 +status: todo +priority: medium +``` + +Complete rollout and decide when legacy aliases stop being first-class. + +Requirements: + +- run State Hub migrations and tests; +- run consistency against State Hub and a representative attached-repo sample; +- check dashboards and MCP docs after migration; +- verify interface-change notifications were delivered; +- monitor attached repo adaptation tasks; +- record a decision for when legacy aliases become warnings or errors; +- after the window closes, remove old values from examples and non-compatibility + documentation. + +Done when State Hub is canon-conformant, attached repos have been notified, and +the remaining compatibility window is explicit. + +## Acceptance Criteria + +- State Hub persists canonical task states as `wait`, `todo`, `progress`, + `done`, and `cancel`. +- Legacy task status values are normalized safely during the migration window. +- Existing DB rows and workplan files do not lose task state information. +- Dashboard, MCP, generated instructions, docs, and tests align with the new + canon. +- Attached repos receive actionable adaptation information through State Hub's + interface-change/messages/task-routing mechanisms. +- No attached repo is directly edited from the State Hub session.