coulomb/the-custodian
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Task flow engine implementation

Browse Source
This commit is contained in:
Bernd Worsch
2026-05-02 00:21:14 +02:00
parent e12a26109f
commit 95bcc5c83c
19 changed files with 716 additions and 91 deletions
Download Patch File Download Diff File Expand all files Collapse all files

211
workplans/archived/260501-CUST-WP-0028-e2e-sandbox-framework.md Normal file
View File

@@ -0,0 +1,211 @@
---
id: CUST-WP-0028
type: workplan
title: "Cross-Repo E2E Sandbox Framework"
domain: railiance
repo: the-custodian
status: completed
owner: custodian
topic_slug: railiance
created: "2026-03-27"
updated: "2026-03-27"
state_hub_workstream_id: "b68de20b-e397-4f97-b1be-ad30711fc2a6"
---
# Cross-Repo E2E Sandbox Framework
## Problem
End-to-end tests that require a real running stack (Temporal, Postgres, workers)
cannot be automated in CI or run locally without significant setup friction.
Each repo has to reinvent its own e2e story. activity-core T21 is the immediate
trigger: the full RunActivityWorkflow flow can't be exercised without a live
Temporal cluster.
## Goal
A **convention + runtime** that any repo can opt into by dropping in an `e2e/`
folder. The shared framework, living in `the-custodian/e2e-framework/`, handles:
- Provisioning an isolated sandbox on a remote host (railiance01)
- `rsync` + `docker compose up` with a unique project name (no port conflicts)
- Health polling until the stack is ready
- Running the repo's test command and capturing results
- `docker compose down` (even on failure)
- Reporting structured results to the state-hub
Each repo just provides: `e2e/e2e.yml` + `e2e/compose.yml` + `e2e/tests/`.
The sandbox host defaults to `RAILIANCE01_HOST` env var (SSH alias or IP).
## Architecture
```
the-custodian/
e2e-framework/
schema.py # parse and validate e2e.yml
sandbox.py # provision/teardown remote sandbox dir via SSH
runner.py # rsync, compose up, health-wait, run tests, compose down
reporter.py # push structured result to state-hub
cli.py # entry point: python -m e2e_framework <repo-path>
Makefile # e2e target: make e2e REPO=activity-core
<repo>/
e2e/
e2e.yml # metadata: compose_file, health_checks, test_command, timeout
compose.yml # stack definition (may symlink docker-compose.dev.yml)
tests/ # test scripts (pytest, shell, etc.)
```
## e2e.yml contract
```yaml
name: <repo-slug>
compose_file: e2e/compose.yml # relative to repo root
health_checks:
- name: <label>
url: http://localhost:<port> # checked from remote machine
timeout: 120 # seconds to wait for this check
test_command: python -m pytest e2e/tests/ -v --tb=short
timeout: 300 # hard timeout for test_command
cleanup: always # always | on_success | never
```
## Tasks
### T01 — e2e-framework core: schema, sandbox, runner
```task
id: CUST-WP-0028-T01
status: done
priority: high
state_hub_task_id: "61dbb674-5933-4185-a7af-f9274bdd43c1"
```
Write `the-custodian/e2e-framework/`:
- `schema.py` — dataclasses + YAML loader for `e2e.yml`
- `sandbox.py` — SSH wrapper: `provision()` (mkdir + rsync), `run()`, `teardown()`
- `runner.py` — full lifecycle: up → health-wait → test → down
The SSH transport uses subprocess + system `ssh` (no extra deps). rsync over SSH.
Health checks curl from within the remote machine via `sandbox.run()`.
---
### T02 — reporter, CLI, Makefile target
```task
id: CUST-WP-0028-T02
status: done
priority: high
state_hub_task_id: "cd845d62-0ab7-4180-bc87-59789883258d"
```
Write:
- `reporter.py` — POST structured result to state-hub `add_progress_event`
- `cli.py` — `python -m e2e_framework <repo-path> [--host HOST] [--keep]`
- `the-custodian/Makefile` — `make e2e REPO=<slug>` target
---
### T03 — activity-core e2e contract
```task
id: CUST-WP-0028-T03
status: done
priority: high
state_hub_task_id: "2ed2b805-2245-4f7e-84d8-4345c6c5455a"
```
In `activity-core/`:
- `e2e/e2e.yml` — references `docker-compose.dev.yml`, declares Temporal UI health check
- `e2e/compose.yml` — symlink to `../docker-compose.dev.yml`
---
### T04 — activity-core test script (closes T21)
```task
id: CUST-WP-0028-T04
status: done
priority: high
state_hub_task_id: "0d92ac62-dc04-495c-85fa-13a66ffe611a"
```
Write `activity-core/e2e/tests/test_full_flow.py`:
- Seeds one ActivityDefinition
- Triggers RunActivityWorkflow via Temporal client
- Polls for workflow completion
- Asserts run log written to DB
- Clear pass/fail output per step
Updates activity-core WP-0001 T21 status to `done`.
---
### T05 — runbook + smoke test instructions
```task
id: CUST-WP-0028-T05
status: done
priority: medium
state_hub_task_id: "bbb106bd-bd89-4c11-b136-276e4d670097"
```
Write `e2e-framework/RUNBOOK.md`:
- Prerequisites (SSH access to sandbox host, Docker installed)
- First run: `export RAILIANCE01_HOST=<ip>; make e2e REPO=activity-core`
- Troubleshooting: sandbox cleanup, docker compose project list, log locations
Note: manual validation on railiance01 still needed (first live run).
---
### T06 — automated cron on railiance01 (no manual trigger)
```task
id: CUST-WP-0028-T06
status: done
priority: high
state_hub_task_id: "b878804e-a9a2-433d-8c85-cc69f669a1b2"
```
The framework is a runner — it still needs a trigger. This task wires up the
automated scheduler so tests run without any manual invocation.
**Deliverables:**
1. `activity-core/e2e/run-on-host.sh` — standalone script that runs natively
on railiance01 (no SSH from workstation):
- `git pull --ff-only`
- `docker compose up -d`
- polls Temporal UI health (up to 180s)
- `uv run python e2e/tests/test_full_flow.py`
- `docker compose down -v`
- POSTs result to state-hub via ops-bridge tunnel (`http://127.0.0.1:18000`)
2. `the-custodian/Makefile` — three new targets:
- `make e2e-cron-install REPO=activity-core` — SSHes to railiance01, installs
weekly cron (`13 3 * * 0`). Idempotent.
- `make e2e-cron-remove REPO=activity-core` — removes the entry
- `make e2e-cron-list` — shows installed e2e cron entries
3. Run `make e2e-cron-install REPO=activity-core` to install on railiance01.
Verify: `make e2e-cron-list` shows the entry.
**Why run-on-host.sh instead of the sandbox wrapper:**
The sandbox wrapper SSHes from the workstation into railiance01. For automated
runs the workstation may be off. `run-on-host.sh` runs directly on railiance01,
so the only dependency is a working ops-bridge tunnel for state-hub reporting
(which is separately monitored).
## Done Criteria
- [ ] `make e2e REPO=activity-core` runs the full stack on railiance01 on demand
- [ ] `make e2e-cron-install REPO=activity-core` installs weekly automated run
- [ ] `make e2e-cron-list` confirms the cron entry on railiance01
- [ ] Sandbox is always cleaned up (compose down) even on failure
- [ ] Results posted to state-hub as progress event
- [ ] activity-core T21 closed by the automated test script
- [ ] Any repo can opt in by adding `e2e/e2e.yml` + `e2e/run-on-host.sh`

311
workplans/archived/260501-CUST-WP-0035-task-flow-engine.md Normal file
View File

@@ -0,0 +1,311 @@
---
id: CUST-WP-0035
type: workplan
title: "Task-Flow-Engine — Declarative Workstation and Requisite Model"
domain: custodian
repo: the-custodian
status: completed
owner: custodian
topic_slug: custodian
created: "2026-04-30"
updated: "2026-04-30"
state_hub_workstream_id: "781e519b-0dd7-451b-b63c-fad50f999c9c"
---
# CUST-WP-0035 — Task-Flow-Engine
## Goal
Build a lightweight, declarative workflow substrate that replaces the
custodian's current hardcoded status enums and `_VALID_TRANSITIONS` dicts with
a generalised model of **workstations**, **information objects**, and
**requisite assertions**.
The core idea:
- **Information objects** are any entities that move through a lifecycle:
workstreams, tasks, contributions, capability requests, interface changes.
- **Workstations** are named positions an information object can occupy. They
are not fixed lifecycle stages — they are general nodes whose semantics are
defined by their entry and exit assertions.
- **Requisite assertions** are declarative predicates on data elements or
qualities of an information object or its environment. An assertion might
say "all child tasks have status `done`", "a human approval record exists",
or "the dependency workstream `X` is at workstation `completed`". Assertions
compose: a workstation is reachable when all its entry assertions are
satisfied; it is exitable when all its exit assertions are satisfied.
- **Transitions** are derived, not enumerated. Any workstation is reachable
from any other if the entry assertions are met. There are no hardcoded valid
transition tables. Blocked state is also derived — an object is blocked at
its current workstation when one or more exit assertions are unsatisfied, and
the engine surfaces exactly which assertions are failing and why.
This design supports the loose, flexible coupling of activities needed across
the custodian ecosystem. Work items don't march through a prescribed pipeline;
they move when their world matches what the target workstation requires.
The engine is designed to eventually live in its own repository
(`task-flow-engine`) as a reusable Python package, independent of the
state-hub. This workplan builds the first version inside the custodian, then
scopes the extraction boundary.
## T01: Design specification — workstations, assertions, flow definitions
```task
id: CUST-WP-0035-T01
status: done
priority: high
state_hub_task_id: "25ad9022-987f-4d30-b1a1-a96c4a83889a"
```
Write `state-hub/docs/task-flow-engine-spec.md` capturing the full data model
before any code is written. The spec must cover:
**Information Object:** any entity with a current workstation label and a
bag of observable properties. The engine is not coupled to a specific DB
schema — it receives a plain dict of properties.
**WorkstationDef:** `{name: str, entry_assertions: list[AssertionDef],
exit_assertions: list[AssertionDef], description: str}`. A workstation with
no assertions is always reachable / always exitable (unconstrained).
**AssertionDef:** `{id: str, target: str, op: str, value: Any,
description: str}`.
- `target` is a dot-path into the information object's properties:
`"tasks.*.status"`, `"dependencies.all.workstation"`, `"metadata.approved_by"`
- `op` is a predicate: `all_eq`, `any_eq`, `none_eq`, `exists`, `count_gte`,
`custom` (for assertions that call back into the engine host)
- Assertions are pure — they do not mutate state
**FlowDef:** `{id: str, entity_type: str, workstations: list[WorkstationDef]}`.
A flow definition is a named graph. Multiple flows can exist per entity type
(e.g., a "lightweight" flow and a "governance" flow for workstreams).
**Transition:** not a first-class type. The engine derives valid next
workstations by evaluating entry assertions of all workstations in the flow
against the current object state. The caller sees: current workstation,
satisfied exit assertions, unsatisfied exit assertions (blocking reasons),
reachable workstations, unreachable workstations with the blocking assertion
for each.
**FlowResult:** `{current_workstation: str, exit_blocked: bool,
blocking_assertions: list[AssertionResult], reachable: list[str],
unreachable: list[{workstation: str, blocking: AssertionResult}]}`.
Acceptance: spec document exists; the model can express the full lifecycle of
workstreams, tasks, contributions, and capability requests without hardcoding
any domain knowledge into the engine itself.
## T02: Core Python library — pure engine, no FastAPI dependency
```task
id: CUST-WP-0035-T02
status: done
priority: high
state_hub_task_id: "df5ce1f2-a0d0-4f90-9629-c28c6021b909"
```
New package at `state-hub/task_flow_engine/`:
```
task_flow_engine/
__init__.py
models.py # AssertionDef, WorkstationDef, FlowDef, FlowResult dataclasses
evaluator.py # assertion evaluation logic
engine.py # FlowEngine.evaluate(obj: dict, flow: FlowDef) -> FlowResult
builtins.py # built-in op implementations: all_eq, any_eq, exists, count_gte, …
```
Design constraints:
- No SQLAlchemy, no FastAPI, no HTTP — this is a pure computation library
- `FlowEngine.evaluate()` takes a plain `dict` (the information object's
properties) and a `FlowDef`, returns a `FlowResult`
- `FlowDef` instances can be loaded from YAML or constructed in code; the
engine does not care
- The `custom` op accepts a callable injected by the host — keeping the engine
pure while allowing host-specific assertions (e.g., "has a linked approval
decision in the DB")
Acceptance: unit tests in `state-hub/tests/test_task_flow_engine.py` cover:
- object with all assertions satisfied → correct reachable workstations
- object with one failing exit assertion → `exit_blocked: true` with the
specific assertion identified
- custom op callable invoked correctly
- empty flow def (no assertions) → all workstations reachable
- circular reference in target path → handled without infinite loop
## T03: Flow definitions for existing custodian entities
```task
id: CUST-WP-0035-T03
status: done
priority: high
state_hub_task_id: "3d01fc77-0329-44ee-8a60-20a3de1c1d6e"
```
Write YAML flow definitions for the four entity types currently tracked in the
state-hub. Store them at `state-hub/flows/`:
**`workstream.yaml`** — replaces `WorkstreamStatus` enum:
- Workstations: `todo`, `active`, `blocked`, `completed`, `archived`
- `todo → active`: no entry assertions (planning is unconstrained)
- `active → completed`: exit assertion `tasks.all_done` = all tasks have
status `done` or `cancelled`
- `active → blocked`: exit assertion `dependencies.any_incomplete` (any
dependency workstream not yet at `completed`)
- `blocked → active`: entry assertion `dependencies.all_complete`
- `completed → archived`: no entry assertions
**`task.yaml`** — replaces the informal `todo | in_progress | blocked | done`
model:
- Workstations: `todo`, `in_progress`, `blocked`, `done`, `cancelled`
- `in_progress → blocked`: exit assertion `needs_human == false` (maps to the
existing `needs_human` flag)
- `blocked → in_progress`: entry assertion `needs_human == false`
- `in_progress → done`: no assertions beyond curator intent
**`contribution.yaml`** — replaces `_VALID_TRANSITIONS` dict in
`routers/contributions.py`:
- Workstations: `draft`, `submitted`, `acknowledged`, `accepted`, `merged`,
`rejected`, `withdrawn`
- Express the same lifecycle as the current dict but as assertion-annotated
workstation definitions, making the intent readable rather than just the
allowed edges
**`capability_request.yaml`** — replaces `_VALID_TRANSITIONS` in
`routers/capability_requests.py`
Acceptance: each YAML file loads as a valid `FlowDef`; running
`FlowEngine.evaluate()` on a representative set of existing DB entities (via
a test fixture) produces `FlowResult`s consistent with the current manual
status labels.
## T04: State-hub integration — migrate from enums to engine
```task
id: CUST-WP-0035-T04
status: done
priority: high
state_hub_task_id: "db320d4e-cbcd-4787-a42c-e7cb109737a3"
```
**4a: Migrate `WorkstreamStatus` from SA Enum to `String(20)`**
Write an Alembic migration that alters the `workstreams.status` column from
the `WorkstreamStatus` enum type to `VARCHAR(20)`. Existing values (`active`,
`blocked`, `completed`, `archived`) are valid workstation names and survive
unchanged. Drop the `WorkstreamStatus` Python enum after migration; use plain
strings throughout. Follow the pattern already established by tasks
(`String(20)` with no SA Enum).
**4b: Replace `_VALID_TRANSITIONS` guards with engine evaluation**
In `routers/contributions.py` and `routers/capability_requests.py`: replace
the `_VALID_TRANSITIONS` dict lookup with `FlowEngine.evaluate()`. The router
loads the appropriate `FlowDef` (from the YAML files in T03), calls evaluate,
and returns 409 with a structured error body listing the failing assertions
if the target workstation is unreachable. The error body replaces the current
free-text `"transition not allowed"` message with machine-readable assertion
failures.
**4c: Derive `blocked` automatically in state summary**
In `routers/state.py`: instead of filtering `Workstream.status == 'blocked'`
directly, evaluate each active workstream against its flow definition and
surface it as effectively blocked when `exit_blocked: true`. This means the
`blocked` status on a workstream can be set automatically by the engine rather
than requiring manual `update_workstream_status("blocked")` calls.
Acceptance: existing API tests pass after migration; the state summary
`blocked_workstreams` count matches what the engine derives; a workstream
with all tasks done automatically surfaces as ready to move to `completed`.
## T05: MCP tools — flow-aware session orientation
```task
id: CUST-WP-0035-T05
status: done
priority: medium
state_hub_task_id: "8ea7e49f-f1ad-4290-84f4-c1ee75c79786"
```
Three new tools in `mcp_server/server.py`:
- `get_flow_state(entity_type: str, entity_id: str)` — returns the
`FlowResult` for the given entity: current workstation, exit-blocking
assertions with human-readable reasons, and list of reachable workstations
- `advance_workstation(entity_type: str, entity_id: str,
target_workstation: str)` — attempts to move the entity to the target
workstation; returns the `FlowResult` on success, or a 409-equivalent with
the specific failing assertions if blocked
- `list_flow_definitions()` — returns the registered flow definitions with
their workstation names and assertion counts (orientation tool)
Update `get_state_summary()` and `get_domain_summary()` to include a
`blocked_reasons` field per blocked workstream so agents see not just that a
workstream is blocked but specifically which assertion is failing.
Acceptance: `get_flow_state("workstream", "<id>")` returns a readable result
for an existing workstream; `advance_workstation` refuses correctly when
assertions are unmet and accepts correctly when they are met.
## T06: Extraction boundary and future repo scope
```task
id: CUST-WP-0035-T06
status: done
priority: low
state_hub_task_id: "b9242cb4-5fb4-4e9e-9f16-9a1866cedc6a"
```
Before closing this workplan, write a brief design note at
`canon/projects/custodian/task_flow_engine_scope_v0.1.md` that captures:
- What belongs in the standalone `task-flow-engine` package:
`models.py`, `evaluator.py`, `engine.py`, `builtins.py` — pure Python,
no custodian dependency
- What stays in the state-hub integration layer:
YAML flow definitions (domain-specific), DB migration, router changes, MCP
tools, custom op callables that query the DB
- The extraction path: once the engine is stable, `state-hub/task_flow_engine/`
is published as a separate pip package and re-imported as a dependency
- Register a new managed repo concept (`task-flow-engine`) in the capabilities
domain for when extraction happens
Also register an extension point:
```
ep_type: architecture
title: task-flow-engine extraction as standalone package
description: >
task_flow_engine/ is currently co-located in the state-hub. Extract to its
own repo and pip package once the API is stable after at least one non-trivial
flow definition has been running in production.
status: open
priority: low
```
Acceptance: design note file exists; extension point registered.
---
## Closing note — reference documentation cleanup
Once this workplan is complete and the task-flow-engine model is live, the
following custodian reference materials will need to be updated to reflect the
refined terminology (workstations, information objects, requisite assertions)
and to retire language that assumed fixed lifecycle enums:
- `state-hub/dashboard/src/docs/` — any page describing workstream or task
lifecycle, status values, or contribution flows
- `state-hub/policies/repo-doi.md` — references to task/workstream status
checks that assume specific enum values
- `agents/agent-scope-analyst.md` and other kaizen agents that reference
status transitions by name
- `CLAUDE.md` (global and project) — session protocol references to
`update_workstream_status()` and `update_task_status()` should be updated
to the `advance_workstation()` pattern
- `memory/MEMORY.md` entries covering the state-hub data model
This cleanup is intentionally deferred — the new terminology should stabilise
in practice before documentation is frozen. A dedicated workplan should be
opened at the close of T05 to track this.