state-hub/workplans/STATE-WP-0052-task-state-canon-adaptation.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-0052	workplan	Task State Canon Adaptation	custodian	state-hub	finished	codex	custodian	2026-05-25	2026-06-04	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:

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:<slug>].
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

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

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

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

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

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

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

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

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:<slug>] ecosystem tasks.

T09 - Publish Interface Change And Route Repo Requests

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:<slug>] 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

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.