Cleanup of documentation

AGENTS.md

@@ -100,6 +100,11 @@ Every Codex session in this repository must follow this ritual:
    ```
    Requires postgres running (`make db`) and `custodian_test` database to exist.
    Create it once with: `psql -U custodian -c "CREATE DATABASE custodian_test"`
+   Lifecycle movement is now flow-aware: use `get_flow_state()` to inspect
+   reachable workstations and `advance_workstation()` to move workstreams,
+   tasks, contributions, or capability requests when the target workstation's
+   requisite assertions are satisfied. Direct status updates remain available
+   for bootstrap, compatibility, and file-backed consistency syncs.
 5. If any workplan files were written or modified this session, first ensure the
    local copy is up to date, then run the consistency sync:
    ```bash

CLAUDE.md

@@ -100,6 +100,11 @@ Every Claude Code session in this repository must follow this ritual:
    ```
    Requires postgres running (`make db`) and `custodian_test` database to exist.
    Create it once with: `psql -U custodian -c "CREATE DATABASE custodian_test"`
+   Lifecycle movement is now flow-aware: use `get_flow_state()` to inspect
+   reachable workstations and `advance_workstation()` to move workstreams,
+   tasks, contributions, or capability requests when the target workstation's
+   requisite assertions are satisfied. Direct status updates remain available
+   for bootstrap, compatibility, and file-backed consistency syncs.
 5. If any workplan files were written or modified this session, first ensure the
    local copy is up to date, then run the consistency sync:
    ```bash

agents/agent-scope-analyst.md

@@ -14,6 +14,9 @@ This agent is now primarily a routing shim:
 
 - inspect the target repository enough to decide whether a new SCOPE.md is
   needed or an existing one should be refreshed;
+- when tied to a State Hub workstream or task, prefer `get_flow_state()` for
+  lifecycle orientation and `advance_workstation()` for flow-aware movement
+  after requisite assertions are satisfied;
 - prefer `scope.generate` when no SCOPE.md exists or the file is only a stub;
 - prefer `scope.update` when a SCOPE.md exists but State Hub reports missing
   sections, invalid capability blocks, or stale boundaries;

memory/working/260224-wishlist-custodian.md

@@ -221,5 +221,27 @@ EPs need to be surfaced in `get_state_summary()`.
 | W2 | `register_project.sh` script + `make register-project` | 1 hr | 25K / registration | Before next project |
 | W5 | `TOOLS.md` reference card | 30 min | 2,500 / session | Next custodian session |
 | W4 | Topic IDs in canon charters | 20 min | 200 / registration | Low urgency |
-| W7 | SessionStart hook for API health | 30 min | Indirect | After W2 |
+| W7 | SessionStart hook for API health | 30 min | Indirect | After W2 |
-| W8 | First-class EP entity in state hub (EP-CUST-001) | 2–4 hr | Indirect | When EP count warrants it |
+| W8 | First-class EP entity in state hub (EP-CUST-001) | 2–4 hr | Indirect | When EP count warrants it |
+
+---
+
+## 2026-05-02 Update — Task-Flow Engine Lifecycle Model
+
+CUST-WP-0035 replaced the old assumption that State Hub lifecycle movement is
+only a fixed set of status enums and hardcoded transition tables.
+
+Current model:
+
+- Information objects expose a stored workstation label, still surfaced as
+  `status` for API compatibility.
+- `get_flow_state(entity_type, entity_id)` reports reachable workstations,
+  unreachable workstations, and blocking assertions.
+- `advance_workstation(entity_type, entity_id, target_workstation)` is the
+  preferred lifecycle movement tool when a flow definition exists.
+- Direct status update tools remain useful for bootstrap, legacy workflows, and
+  file-backed consistency sync, but they are no longer the conceptual center of
+  lifecycle management.
+
+Reference spec:
+`state-hub/docs/task-flow-engine-spec.md`

state-hub/dashboard/src/docs/capabilities.md

@@ -96,7 +96,7 @@ This means the requester never needs to know which domain owns a capability.
 
 ---
 
-## Request lifecycle
+## Request flow
 
 ```
 requested → accepted → in_progress → ready_for_review → completed
@@ -105,7 +105,7 @@ requested → accepted → in_progress → ready_for_review → completed
               withdrawn
 ```
 
-| Status | Meaning |
+| Workstation | Meaning |
 |--------|---------|
 | **requested** | Need declared; routed (or broadcast) to provider |
 | **accepted** | Provider acknowledged and claimed the request |
@@ -115,14 +115,17 @@ requested → accepted → in_progress → ready_for_review → completed
 | **rejected** | Provider cannot or will not fulfil the request |
 | **withdrawn** | Requester cancelled the request |
 
-Transitions are enforced by the API — you cannot skip stages. Terminal states
+Request movement is flow-aware. The API evaluates the target workstation's
-(`completed`, `rejected`, `withdrawn`) allow no further transitions.
+entry assertions and rejects unreachable movement with machine-readable
+blocking assertions. Terminal workstations (`completed`, `rejected`,
+`withdrawn`) have no reachable outgoing path in the current flow definition.
 
 ---
 
 ## Auto-notifications
 
-Every lifecycle transition creates an **AgentMessage** atomically:
+Every request movement handled by the capability request API creates an
+**AgentMessage** atomically:
 
 | Transition | Notification to |
 |------------|----------------|
@@ -182,17 +185,17 @@ accept_capability_request(
 )
 ```
 
-Then advances through the lifecycle:
+Then advances through the flow:
 
 ```
-update_capability_request_status(request_id, "in_progress")
+advance_workstation(entity_type="capability_request", entity_id=request_id, target_workstation="in_progress")
-update_capability_request_status(request_id, "ready_for_review", note="Instance up at 10.0.1.42")
+advance_workstation(entity_type="capability_request", entity_id=request_id, target_workstation="ready_for_review")
 ```
 
 The requester reviews and completes:
 
 ```
-update_capability_request_status(request_id, "completed", note="Verified, looks good")
+advance_workstation(entity_type="capability_request", entity_id=request_id, target_workstation="completed")
 ```
 
 ---
@@ -203,7 +206,7 @@ The Capabilities page shows:
 
 - **KPI sidebar** — open count, average fulfillment time, high/critical count
 - **Summary cards** — requested, in progress, ready for review, completed
-- **Kanban board** — cards grouped by status column
+- **Kanban board** — cards grouped by workstation/status column
 - **Table** — all requests with filters by type, status, and domain
 
 Each card shows the capability type, priority, requester → provider domains,

state-hub/dashboard/src/docs/contributions.md

@@ -22,7 +22,7 @@ registered in the state hub so it is never lost.
 
 ---
 
-## Lifecycle
+## Flow workstations
 
 ```
 draft → submitted → acknowledged → accepted → merged
@@ -30,7 +30,7 @@ draft → submitted → acknowledged → accepted → merged
                rejected        withdrawn
 ```
 
-| Status | Meaning |
+| Workstation | Meaning |
 |--------|---------|
 | **draft** | Artifact written locally; not yet sent upstream |
 | **submitted** | Filed as a GitHub issue, PR, or email — awaiting upstream response |
@@ -40,9 +40,12 @@ draft → submitted → acknowledged → accepted → merged
 | **rejected** | Upstream declined; record kept for future reference |
 | **withdrawn** | We decided not to pursue it |
 
-Transitions are enforced by the API — you cannot skip stages arbitrarily.
+Contribution movement is evaluated by the task-flow engine. The API asks
-`submitted_at` is stamped automatically when status moves to `submitted`;
+whether the target workstation is reachable from the current information
-`resolved_at` is stamped when status moves to `merged`, `rejected`, or `withdrawn`.
+object; if not, it returns structured blocking assertions instead of a generic
+"transition not allowed" message. `submitted_at` is stamped automatically when
+the contribution reaches `submitted`; `resolved_at` is stamped when it reaches
+`merged`, `rejected`, or `withdrawn`.
 
 ---
 
@@ -57,7 +60,7 @@ communication taxonomy:
 | Ecosystem | State hub task with `[repo:<slug>]` prefix |
 | **Third-party** | **Contribution artifact in `contrib/` + state hub registration** |
 
-Contributions in `draft`, `submitted`, or `acknowledged` status appear as
+Contributions in `draft`, `submitted`, or `acknowledged` workstations appear as
 open Third-party todos on the [Todo](/todo) page.
 
 ---
@@ -99,7 +102,7 @@ register_contribution(
 **3. Close the loop** when you file it upstream:
 
 ```
-update_contribution_status(contribution_id="<uuid>", status="submitted")
+advance_workstation(entity_type="contribution", entity_id="<uuid>", target_workstation="submitted")
 ```
 
 **4. Keep updating** as upstream responds — `acknowledged`, `accepted`, `merged`.

state-hub/dashboard/src/docs/inter-repo-communication.md

@@ -115,7 +115,7 @@ framework you use but do not own.
    ```
 3. When submitted upstream, close the loop:
    ```python
-   update_contribution_status(contribution_id="<uuid>", status="submitted")
+   advance_workstation(entity_type="contribution", entity_id="<uuid>", target_workstation="submitted")
    ```
 
 Templates: `~/the-custodian/canon/standards/contrib-templates/`
@@ -129,7 +129,8 @@ The session orientation protocol (every repo's CLAUDE.md) surfaces todos from
 two sources:
 
 **Internal todos** (Step 2 of orientation) — workplan files in `workplans/`
-with `status: active`, tasks with `status: todo` or `in_progress`.
+whose stored workstation/status label is `active`, with tasks in `todo` or
+`in_progress`.
 
 **Ecosystem todos targeting this repo** (Step 1 of orientation) —
 `get_state_summary()` returns all open tasks across all workstreams. The session

state-hub/dashboard/src/docs/progress-log.md

@@ -40,6 +40,7 @@ These types are used by the State Hub's built-in write operations:
 |---|---|
 | `workstream_created` | A new workstream was registered |
 | `workstream_status_changed` | Workstream moved to active / blocked / completed / archived |
+| `workstation_advanced` | Flow-aware movement via `advance_workstation()` succeeded |
 | `task_created` | A new task was added to a workstream |
 | `task_status_changed` | Task moved to todo / in_progress / blocked / done / cancelled |
 | `decision_recorded` | A decision (pending or made) was recorded |

state-hub/dashboard/src/docs/tasks.md

@@ -5,13 +5,17 @@ title: Tasks — Reference
 # Tasks — Reference
 
 The Tasks page shows all tasks across every workstream and domain, with live
-filtering, a status distribution chart, and a blocked-tasks highlight section.
+filtering, a workstation distribution chart, and a blocked-tasks highlight
+section.
 
 ---
 
-## Task statuses
+## Task workstations
 
-| Status | Meaning |
+Tasks still expose their current workstation through the `status` field for API
+compatibility.
+
+| Workstation | Meaning |
 |--------|---------|
 | **todo** | Not yet started |
 | **in_progress** | Actively being worked on |
@@ -45,10 +49,10 @@ All filters are applied client-side after each poll.
 
 ---
 
-## Status Distribution chart
+## Workstation Distribution chart
 
 A horizontal bar chart (Observable Plot) showing the count of filtered tasks
-per status, colour-coded:
+per stored workstation/status label, colour-coded:
 
 | Colour | Status |
 |--------|--------|
@@ -62,8 +66,8 @@ per status, colour-coded:
 
 ## Blocked Tasks section
 
-Shows cards for every task currently in `blocked` status within the active
+Shows cards for every task currently in the `blocked` workstation within the
-filter. Each card displays:
+active filter. Each card displays:
 
 - Priority badge and status
 - Domain and workstream context

state-hub/dashboard/src/docs/workstream-health-index.md

@@ -76,7 +76,10 @@ Detects concentration of blocking power. High SPR means one delay propagates wid
 PEP = active workstreams with all deps completed / (active + blocked)
 ```
 
-Estimates how much work can proceed right now. A workstream is eligible if its status is `active` and every workstream it depends on has reached `completed` or `archived`.
+Estimates how much work can proceed right now. A workstream is eligible if its
+stored workstation label is `active` and the flow/dependency checks report no
+unmet dependency assertion; practically, every workstream it depends on has
+reached `completed` or `archived`.
 
 | PEP | Warning |
 |---|---|

state-hub/dashboard/src/docs/workstream-lifecycle.md

@@ -4,40 +4,43 @@ title: Workstream Lifecycle — Reference
 
 # Workstream Lifecycle — Reference
 
-A workstream moves through a defined lifecycle from creation to sign-off. The
+A workstream is an information object that occupies a named workstation. The
-dashboard "Workstreams by Domain" chart exposes these states as selectable
+stored `status` field keeps the current workstation label, while the
-filters so attention can be directed to the right workstreams at the right time.
+task-flow engine derives which other workstations are reachable and which exit
+assertions are blocking movement. The dashboard "Workstreams by Domain" chart
+exposes stored and derived states as selectable filters so attention can be
+directed to the right workstreams at the right time.
 
 ---
 
-## Core lifecycle states
+## Core workstations
 
-These are the primary stages a workstream passes through in order:
+These are the primary workstations used by State Hub workstreams:
 
-| State | Source | Meaning |
+| Workstation | Source | Meaning |
 |---|---|---|
 | **active** | DB `status = active` | Work is in progress or ready to start |
 | **finished** | Derived — no open tasks | All tasks are done, but no explicit review has taken place yet |
 | **accepted** | DB `status = completed` | Custodian and human have reviewed the workstream, quality checks passed, and it is formally signed off |
 
-The normal progression is: **active → finished → accepted**.
+The normal human-facing path is: **active → finished → accepted**.
 
-`accepted` is the only state that requires an explicit action — it is set after
+`accepted` is the only state that requires an explicit action. It is reached by
-a deliberate review, not automatically. This makes it a reliable anchor:
+advancing the workstream to the `completed` workstation after deliberate
-anything in `finished` but not yet in `accepted` is work that still needs a
+review, not by task counts alone. This makes it a reliable anchor: anything in
-quality pass.
+`finished` but not yet in `accepted` is work that still needs a quality pass.
 
 ---
 
 ## Attention signals
 
-These states are orthogonal to the core lifecycle — a workstream can be
+These signals are orthogonal to the core workstation — a workstream can be
 `active` and `stalled` at the same time. They serve as health indicators
-rather than lifecycle stages.
+rather than stored lifecycle stages.
 
 | Signal | Source | Meaning |
 |---|---|---|
-| **blocked** | Derived — has ≥ 1 blocked task | At least one task is waiting on something external |
+| **blocked** | Derived — unmet exit assertion or blocked task | Work cannot currently leave its workstation; inspect `blocked_reasons` |
 | **stalled** | Derived — `updated_at` > 7 days ago, has both done and open tasks | Work started but activity has stopped; needs a nudge |
 | **oldies** | Derived — `created_at` > 7 days ago, zero done tasks | Workstream is old and nothing has been completed yet; may need re-evaluation |
 
@@ -50,14 +53,15 @@ When a workstream reaches **finished** (all tasks done), the custodian's role is
 1. Review the deliverables against the workstream's stated purpose and scope
 2. Check for missing tests, documentation, or follow-up issues
 3. Create tasks for any gaps found — this moves the workstream back to **active**
-4. Once satisfied, set `status = completed` via MCP or API — this marks it as **accepted**
+4. Once satisfied, advance to the `completed` workstation — this marks it as **accepted**
 
 This pattern ensures that "done" and "accepted" are distinct signals.
 `finished` is a fact about task counts; `accepted` is a statement of quality.
 
 ```
-# Accept a workstream via MCP
+# Inspect and accept a workstream via MCP
-update_workstream_status(workstream_id="<uuid>", status="completed")
+get_flow_state(entity_type="workstream", entity_id="<uuid>")
+advance_workstation(entity_type="workstream", entity_id="<uuid>", target_workstation="completed")
 
 # Or via REST
 curl -X PATCH http://127.0.0.1:8000/workstreams/<uuid>/ \
@@ -86,19 +90,22 @@ workstreams to distinguish notable states at a glance.
 
 ---
 
-## DB status vs. dashboard state
+## Stored Label Vs. Dashboard State
 
-The DB stores a single `status` field on each workstream. The dashboard maps
+The DB stores a single `status` field on each workstream. Treat it as the
-this alongside derived task-count data to produce the richer set of filter states:
+current workstation label. The dashboard maps this alongside flow-engine
+results, dependency assertions, and task-count data to produce the richer set
+of filter states:
 
-| Dashboard state | DB `status` | Task-count condition |
+| Dashboard state | Stored label / derived source | Condition |
 |---|---|---|
-| active | `active` | — |
+| active | `status = active` | — |
-| accepted | `completed` | — |
+| accepted | `status = completed` | — |
-| finished | any | `todo + in_progress + blocked = 0` |
+| finished | task counts | `todo + in_progress + blocked = 0` |
-| blocked | any | `blocked ≥ 1` |
+| blocked | flow result / task counts | `exit_blocked = true` or `blocked ≥ 1` |
-| stalled | any | `done ≥ 1` and `open ≥ 1` and `updated_at > 7d ago` |
+| stalled | task counts + timestamp | `done ≥ 1` and `open ≥ 1` and `updated_at > 7d ago` |
-| oldies | any | `done = 0` and `open ≥ 1` and `created_at > 7d ago` |
+| oldies | task counts + timestamp | `done = 0` and `open ≥ 1` and `created_at > 7d ago` |
 
-*Workstreams are never hard-deleted — use `update_workstream_status(..., "completed")` or
+*Workstreams are never hard-deleted — use `advance_workstation(...,
-`"archived"` to close them without losing history.*
+"completed")` or advance/patch to `"archived"` to close them without losing
+history.*

state-hub/dashboard/src/docs/workstreams.md

@@ -4,22 +4,30 @@ title: Workstreams — Reference
 
 # Workstreams — Reference
 
-A workstream is a bounded unit of work within a topic. It carries a status, an optional owner and due date, and belongs to exactly one of the six project domains. The Workstreams page gives you a filtered, visual overview of all active work and the dependency graph between workstreams.
+A workstream is a bounded unit of work within a topic. It carries a stored
+workstation label in the `status` field, an optional owner and due date, and
+belongs to exactly one project domain. The Workstreams page gives you a
+filtered, visual overview of active work, derived blocked state, and the
+dependency graph between workstreams.
 
 ---
 
-## Status Distribution chart
+## Workstation Distribution chart
 
-A horizontal bar chart showing the count of workstreams in each status for the current filter selection. Updates immediately as filters change.
+A horizontal bar chart showing the count of workstreams in each stored
+workstation/status label for the current filter selection. Updates immediately
+as filters change.
 
-| Status | Meaning |
+| Workstation | Meaning |
 |---|---|
 | **active** | Work in progress or ready to start |
-| **blocked** | Waiting on something outside the workstream — see Dependencies |
+| **blocked** | Stored blocker label; the State Hub can also derive blocked state from unmet exit assertions |
 | **completed** | Formally accepted after custodian review (shown as **accepted** in the overview chart) |
 | **archived** | Closed without completion; no longer relevant |
 
-See [Workstream Lifecycle](/docs/workstream-lifecycle) for the full state model including derived states (finished, stalled, oldies).
+See [Workstream Lifecycle](/docs/workstream-lifecycle) for the full task-flow
+model including derived states (finished, stalled, oldies) and assertion-based
+blocking.
 
 ---
 
@@ -28,7 +36,7 @@ See [Workstream Lifecycle](/docs/workstream-lifecycle) for the full state model
 | Filter | Effect |
 |---|---|
 | **Domain** | Multi-select — show only workstreams from selected domains |
-| **Status** | Multi-select — show only workstreams with selected statuses |
+| **Status** | Multi-select — show only workstreams with selected workstation labels |
 | **Owner** | Text substring match on the owner field (case-insensitive) |
 
 Leaving a filter empty means "show all". All three filters combine with AND logic. Filters persist across polls — selections are not lost when the page refreshes live data.
@@ -43,7 +51,7 @@ The six domains are: `custodian`, `railiance`, `markitect`, `coulomb_social`, `p
 |---|---|
 | Title | Workstream title |
 | Domain | Derived from the parent topic |
-| Status | Current workstream status |
+| Status | Current stored workstation/status label |
 | Owner | Assigned person (or `—` if unset) |
 | Due | Target completion date (or `—`) |
 | Updated | Last modification timestamp |
@@ -99,13 +107,18 @@ curl -X POST http://127.0.0.1:8000/workstreams/ \
 
 ---
 
-## Updating workstream status
+## Advancing a workstream
 
 ```
-update_workstream_status(workstream_id="<uuid>", status="completed")
+get_flow_state(entity_type="workstream", entity_id="<uuid>")
+advance_workstation(entity_type="workstream", entity_id="<uuid>", target_workstation="completed")
 ```
 
-Valid transitions: `active` → `blocked` / `completed` / `archived`; `blocked` → `active`; `completed` → `archived`.
+Movement is flow-aware: the task-flow engine evaluates the target
+workstation's entry assertions and returns structured blocking assertions when
+the target is not reachable. Direct status patching still exists for bootstrap
+and compatibility work, but normal lifecycle movement should prefer
+`advance_workstation()`.
 
 ---
 

state-hub/policies/repo-doi.md

@@ -16,7 +16,9 @@ These are the minimum requirements for the state-hub to be aware of a repo.
   `GET /repos/{slug}`
 
 - [ ] **Domain assigned** — repo is linked to an active domain. The domain must
-  exist in `domains` and be in `active` status.
+  exist in `domains` and be in `active` status. Domain status is still a
+  simple administrative label; workstream/task lifecycle labels are now treated
+  as task-flow workstations.
 
 - [ ] **Local path resolves** — `_resolve_repo_path()` finds an existing
   directory on the current host (either via `host_paths[hostname]` or
@@ -43,6 +45,9 @@ A repo at this tier participates in state-hub tracking and tooling.
 - [ ] **Workplan convention followed** — any workplans live under
   `workplans/<ID>-<slug>.md` with valid YAML frontmatter
   (`id`, `type`, `title`, `domain`, `status`, `state_hub_workstream_id`).
+  The frontmatter `status` is the file-backed source for the workstream's
+  stored workstation label. Derived blocked state and blocking reasons come
+  from the task-flow engine, not from the frontmatter alone.
   Verified by: `make check-consistency REPO={slug}` → PASS or WARN only
   (no FAIL).
 
@@ -118,3 +123,8 @@ A fully integrated repo contributes to cross-repo planning and capability routin
 - A repo may satisfy **Standard** without **Full** indefinitely — Full
   integration is appropriate when the repo is actively contributing to
   cross-domain work or exposing capabilities to other repos.
+- For lifecycle inspection, prefer `get_flow_state(entity_type, entity_id)` and
+  `advance_workstation(entity_type, entity_id, target_workstation)` over
+  reasoning from stored status labels alone. Stored labels remain important for
+  filtering and compatibility, but DoI health should use structured flow
+  results when blocking assertions matter.

workplans/archived/260502-CUST-WP-0037-task-flow-reference-docs-cleanup.md

@@ -4,7 +4,7 @@ type: workplan
 title: "Task-Flow Reference Documentation Cleanup"
 domain: custodian
 repo: the-custodian
-status: todo
+status: completed
 owner: custodian
 topic_slug: custodian
 created: "2026-05-01"
@@ -28,7 +28,7 @@ stabilize before broad documentation churn.
 
 ```task
 id: CUST-WP-0037-T01
-status: todo
+status: done
 priority: medium
 state_hub_task_id: "919d21cb-1cdc-448e-a722-38f1b6374ffb"
 ```
@@ -44,7 +44,7 @@ without implying that lifecycle movement is controlled by fixed enum tables.
 
 ```task
 id: CUST-WP-0037-T02
-status: todo
+status: done
 priority: medium
 state_hub_task_id: "d6485f6c-815f-4f50-a35e-3fd42046691f"
 ```
@@ -60,7 +60,7 @@ task-flow-engine model.
 
 ```task
 id: CUST-WP-0037-T03
-status: todo
+status: done
 priority: medium
 state_hub_task_id: "79251442-12a0-4a00-9e3a-fc484933259d"
 ```
@@ -75,7 +75,7 @@ flow-aware lifecycle movement is relevant.
 
 ```task
 id: CUST-WP-0037-T04
-status: todo
+status: done
 priority: medium
 state_hub_task_id: "e2a9d096-b66a-43f2-af87-ec802ba9e795"
 ```
@@ -90,7 +90,7 @@ keeping direct status tools documented for bootstrap or compatibility cases.
 
 ```task
 id: CUST-WP-0037-T05
-status: todo
+status: done
 priority: low
 state_hub_task_id: "2320cd6b-8dc6-4160-9623-4e6425b637e5"
 ```