---
id: STATE-WP-0052
type: workplan
title: "Task State Canon Adaptation"
domain: infotech
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:<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

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

```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.
