generated from coulomb/repo-seed
tegwick
166aedfa8d
Adds preferred workplan REST/event surfaces, legacy-meter telemetry and weekly review summaries, documentation/dashboard terminology updates, dashboard API loading fixes, and close-out sync for STATE-WP-0052 and STATE-WP-0054.
362 lines
12 KiB
Markdown
362 lines
12 KiB
Markdown
---
|
|
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:<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.
|