Task flow engine implementation

canon/projects/custodian/task_flow_engine_scope_v0.1.md

@@ -0,0 +1,92 @@
+---
+id: CUST-TFE-SCOPE-2026-000001
+type: architecture-note
+title: "Task Flow Engine Extraction Scope v0.1"
+status: draft
+owners: ["Bernd", "Custodian"]
+created: "2026-05-01"
+updated: "2026-05-01"
+scope:
+  domains: ["Custodian"]
+  sensitivity: internal
+tags: ["task-flow-engine", "architecture", "state-hub", "workflow"]
+domain: custodian
+provenance:
+  workplan: CUST-WP-0035
+  task: CUST-WP-0035-T06
+---
+
+# Task Flow Engine Extraction Scope v0.1
+
+## Purpose
+
+The task flow engine is currently co-located in `state-hub/` so it can replace
+hardcoded lifecycle logic where the need is immediate. Its core model is more
+general than State Hub, so it should become a standalone Python package once
+the API has stabilized through real use.
+
+## Standalone Package Boundary
+
+The future `task-flow-engine` package should contain only pure computation:
+
+- `models.py`: dataclasses for assertions, workstations, flows, and results
+- `evaluator.py`: target path resolution and assertion evaluation
+- `engine.py`: reachable workstation and exit-blocking derivation
+- `builtins.py`: built-in operations such as `all_eq`, `any_eq`, `none_eq`,
+  `exists`, and `count_gte`
+
+The package must not depend on State Hub, SQLAlchemy, FastAPI, MCP, Custodian
+canon files, or any specific database schema.
+
+## State Hub Integration Boundary
+
+State Hub should retain the domain-specific integration layer:
+
+- YAML flow definitions in `state-hub/flows/`
+- conversion from ORM entities into plain information-object dictionaries
+- Alembic migrations and status-column storage choices
+- API routers and MCP tools
+- custom assertion callables that query State Hub data
+- progress events, timestamps, notifications, and other side effects
+
+This keeps the reusable engine small while allowing State Hub to remain the
+place where Custodian-specific lifecycle semantics are declared and exposed.
+
+## Extraction Path
+
+1. Keep `state-hub/task_flow_engine/` in-tree until at least one non-trivial
+   flow definition runs in normal State Hub use.
+2. Stabilize the dataclass and result shapes around real consumers:
+   State Hub API, MCP tools, and repo-facing workflows.
+3. Extract the pure package into a new `task-flow-engine` repository.
+4. Publish it as an internal pip package.
+5. Replace the in-tree package with a dependency import in State Hub.
+
+The extraction should preserve the current import surface where practical:
+`FlowDef`, `WorkstationDef`, `AssertionDef`, `FlowResult`, `AssertionResult`,
+`FlowEngine`, and `resolve_target`.
+
+## Managed Repo Concept
+
+When extraction starts, register a managed repository concept:
+
+- slug: `task-flow-engine`
+- domain: `custodian`
+- purpose: reusable declarative workstation/assertion engine
+- primary capability: `workflow.evaluate`
+- secondary capabilities: `workflow.define`, `workflow.explain`
+
+## Extension Point
+
+An extension point is registered in State Hub to keep this extraction visible:
+
+- type: `architecture`
+- title: `task-flow-engine extraction as standalone package`
+- status: `open`
+- priority: `low`
+
+Description:
+
+`task_flow_engine/` is currently co-located in the State Hub. Extract it to its
+own repository and pip package once the API is stable after at least one
+non-trivial flow definition has been running in production.