generated from coulomb/repo-seed
docs(workplans): plan task state canon adaptation
This commit is contained in:
343
workplans/STATE-WP-0052-task-state-canon-adaptation.md
Normal file
343
workplans/STATE-WP-0052-task-state-canon-adaptation.md
Normal file
@@ -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:<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: 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:<slug>]` 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:<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: 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.
|
||||
Reference in New Issue
Block a user