--- id: STATE-WP-0052 type: workplan title: "Task State Canon Adaptation" domain: custodian repo: state-hub status: finished owner: codex topic_slug: custodian created: "2026-05-25" updated: "2026-06-04" state_hub_workstream_id: "bc54c18b-4d98-430d-b9ad-c4410010c897" --- # 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=state-hub`, `interface_type=schema`, `change_type=breaking`, and the active registered repo slugs in `affected_repo_slugs`. The change cites `info-tech-canon` as the canon source and State Hub as the schema/API publisher. 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: done priority: high state_hub_task_id: "09c4d7ef-d193-48ed-b127-611e26b70ba0" ``` 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: done priority: high state_hub_task_id: "c79ce637-7140-4a16-8d20-b89edee4b98f" ``` 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: done priority: high state_hub_task_id: "206511ae-76a8-4c47-a1b2-114b115f8c1c" ``` 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: done priority: high state_hub_task_id: "bf4c6891-64a5-49e6-9bf6-d70577d494e7" ``` 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: done priority: high state_hub_task_id: "c9e6a649-8e1c-4d3c-b51a-1814687a99be" ``` 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: done priority: high state_hub_task_id: "0aaea886-9686-4fa7-94e5-e5a6649489e8" ``` 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: done priority: high state_hub_task_id: "c884eea6-1b69-4636-86f2-475d5ec4ea9b" ``` 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: done priority: high state_hub_task_id: "b659724d-bda1-4dec-9af1-4d5e08f4db94" ``` 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: done priority: high state_hub_task_id: "6479748b-c922-41e3-ad12-15015b2f56a9" ``` 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 State Hub, citing `info-tech-canon` as the canon source; - 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: done priority: medium state_hub_task_id: "1cde226a-6287-4db4-9d2f-7fa9ed0b6c4d" ``` 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. Close-out note: attached repos were notified through interface change `649102a2-4373-4621-9848-cc257e67c262`; decision `c386f42f-a50a-41d9-9457-f384227f8f6c` keeps legacy aliases accepted during the adaptation window and leaves any future warnings/errors to a later explicit decision. ## 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.