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

Implement daily State Hub WSJF triage

Browse Source
This commit is contained in:
Bernd Worsch
2026-05-17 23:10:57 +02:00
parent c0a3fb6543
commit 45d296b236
4 changed files with 390 additions and 6 deletions
Download Patch File Download Diff File Expand all files Collapse all files

119
activity-definitions/daily-statehub-wsjf-triage.md Normal file
View File

@@ -0,0 +1,119 @@
---
id: "6fca51fa-387a-4fd0-bc4e-d62c29eb859a"
name: "Daily State Hub WSJF Triage"
type: activity-definition
version: "1.0"
enabled: false
owner: custodian
governance: custodian
status: draft
created: "2026-05-17"
trigger:
type: cron
cron_expression: "20 7 * * *"
timezone: Europe/Berlin
misfire_policy: skip
context_sources:
- type: static
bind_to: context.prompt_path
config:
value: /home/worsch/the-custodian/runtime/prompts/daily_statehub_wsgi_triage.md
- type: state-hub
query: state_summary
bind_to: context.state_summary
- type: state-hub
query: next_steps
bind_to: context.next_steps
- type: state-hub
query: workplan_index
params:
refresh: false
bind_to: context.workplan_index
- type: state-hub
query: hub_inbox
params:
to_agent: hub
unread_only: true
bind_to: context.hub_inbox
---
# ActivityDefinition: Daily State Hub WSJF Triage
## Purpose
This definition is the activity-core handoff point for
`CUST-WP-0044 - Daily State Hub WSJF Triage`.
The daily triage loop reviews State Hub, scores open workplans and next tasks
with the WSJF rubric, and leaves a short recommendation report plus a State Hub
progress event. It should reduce loose ends and open work without automatically
editing canonical workplans.
## Runner Status
This definition is intentionally `enabled: false`.
Current active runner:
- Codex app automation: `daily-state-hub-wsjf-triage`
- Prompt source:
`/home/worsch/the-custodian/runtime/prompts/daily_statehub_wsgi_triage.md`
Durable target runner:
- activity-core Temporal schedule using this ActivityDefinition
Enable this definition only after activity-core has a reviewed action path for
running a Custodian agent/report instruction and writing the resulting working
memory note/progress event. Until then, activity-core is the target substrate
and the Codex automation is the active runner. Do not run both at the same time.
## Trigger
Daily at 07:20 Europe/Berlin, with `misfire_policy: skip`.
This mirrors the current Codex automation schedule and avoids catch-up bursts
after downtime.
## Context Sources
The definition reuses State Hub read-model endpoints instead of introducing a
parallel priority database:
- `state_summary`: headline counts, open workstreams, blockers, progress,
derived next steps, and domain summaries
- `next_steps`: State Hub's existing derived next-action hints
- `workplan_index`: file-backed workplan mapping and needs-review labels
- `hub_inbox`: unread hub coordination messages
- `prompt_path`: the canonical triage prompt in the Custodian runtime
The State Hub context resolver in activity-core may need to expose these query
names before this definition is enabled. That resolver is the right integration
point; do not add bespoke HTTP fetch logic to this repo's workplan files.
## Output Contract
The run should produce:
- a dated working-memory note under
`/home/worsch/the-custodian/memory/working/`
- a State Hub progress event with `event_type: daily_triage`
- no direct workplan/canon edits
- no task status changes unless a later human request explicitly asks for an
apply step
## Review Gates
Daily triage may recommend but must not execute:
- external publication
- money or legal commitments
- secret or credential changes
- security posture changes without an explicit approval path
- canon promotion
## Notes
This file lives in `the-custodian/activity-definitions/` because the
automation policy belongs to the Custodian domain. activity-core can ingest
domain-owned definition directories through `ACTIVITY_DEFINITION_DIRS`.

8
runtime/README.md
View File

@@ -9,7 +9,7 @@ about it with an LLM, and executes bounded write operations.
agent.py CLI entry point + OODA orchestrator agent.py CLI entry point + OODA orchestrator
context.py Observe: fetch state-hub data + build LLM context prompt context.py Observe: fetch state-hub data + build LLM context prompt
actions.py Act: execute sanctioned write operations actions.py Act: execute sanctioned write operations
prompts/ System prompt templates (future) prompts/ System prompt templates and recurring review prompts
policies/ Agent-level policies (future) policies/ Agent-level policies (future)
tool_adapters/ Additional MCP/API tool adapters (future) tool_adapters/ Additional MCP/API tool adapters (future)
tests/ Unit tests (offline, no live API required) tests/ Unit tests (offline, no live API required)
@@ -90,6 +90,12 @@ The agent prints a trace to stdout:
The LLM's reasoning trace is saved to `memory/working/agent-session-{ts}-{scope}.md`. The LLM's reasoning trace is saved to `memory/working/agent-session-{ts}-{scope}.md`.
Recurring review prompts:
- `prompts/daily_statehub_wsgi_triage.md` - daily State Hub WSJF triage used by
the `daily-state-hub-wsjf-triage` automation and the activity-core handoff
definition in `../activity-definitions/`.
## Tests ## Tests
```bash ```bash

237
runtime/prompts/daily_statehub_wsgi_triage.md Normal file
View File

@@ -0,0 +1,237 @@
---
id: daily-statehub-wsjf-triage
type: runtime-prompt
owner: custodian
status: active
created: "2026-05-17"
updated: "2026-05-17"
related_workplan: CUST-WP-0044
---
# Daily State Hub WSJF Triage Prompt
## Purpose
Run a daily Custodian review of State Hub state and produce a short,
reviewable recommendation report. The review is a focus surface, not an
execution loop: it recommends what to work next, what to revisit, what to park,
and what needs human or cross-agent attention.
Do not create a new scheduler for this loop. The current runner is the Codex
app automation `daily-state-hub-wsjf-triage`. The durable target substrate is
activity-core using the ActivityDefinition in
`/home/worsch/the-custodian/activity-definitions/daily-statehub-wsjf-triage.md`.
If the runner is moved to activity-core later, disable the Codex app automation
first so there is exactly one daily runner.
## Operating Rules
- Read first, then decide. Do not edit workplans, canon, or task status during
a daily review unless a later human request explicitly asks for an apply step.
- Prefer existing State Hub read surfaces over ad hoc scans:
`/state/summary`, `/state/next_steps`, `/workstreams/workplan-index`,
`/messages/`, and `.custodian-brief.md`.
- Use local workplan files only to enrich the State Hub snapshot with task
wording, stale frontmatter, and missing file-backed state.
- Treat scores as prioritization aids, not truth. Every WSJF row needs a
confidence label.
- Items involving money, legal status, secrets, security posture, external
publication, or external reputation must be reported as `needs-human` unless
a current explicit approval already exists.
## Inputs
Collect these inputs in order. If a live input fails, continue from the last
available fallback and say so in the report.
1. `/home/worsch/the-custodian/.custodian-brief.md`
2. `GET http://127.0.0.1:8000/state/summary`
3. `GET http://127.0.0.1:8000/messages/?to_agent=hub&unread_only=true`
4. `GET http://127.0.0.1:8000/state/next_steps`
5. `GET http://127.0.0.1:8000/workstreams/workplan-index`
6. Local workplan files for candidate workstreams that need closer inspection
7. Read-only `git status --short` for repos named in top recommendations
Optional enrichment:
- `GET /tasks/?workstream_id=<id>` for a top-ranked workstream
- `GET /progress/?workstream_id=<id>&limit=5` for staleness confidence
- State Hub domain summaries through MCP when available
## Candidate Set
Build the candidate list from:
- all open workstreams in `state_summary.open_workstreams`
- all derived `state_summary.next_steps`
- blocked tasks and blocking decisions from the summary
- high-priority file-backed workplans surfaced by `workplan-index`
- workstreams with suspicious structure, such as zero parsed tasks or stale
active plans
Keep the scored table compact. Score at most 15 candidates internally and
report the top 10.
## Loose-End Detection
Flag a candidate when one or more signals apply:
| Signal | Default threshold | Recommended action |
|--------|-------------------|--------------------|
| Active with no recent progress | no progress in 14 days, or 7 days for high-priority items | `revisit` |
| Large unstarted plan | `tasks_total >= 6`, `tasks_done == 0`, `tasks_in_progress == 0` | `split` or `revisit` |
| Near complete | `tasks_done / tasks_total >= 0.75` and `tasks_todo <= 3` | `close-out` or `work-next` |
| Zero parsed tasks | active or blocked workstream with `tasks_total == 0` | `needs-consistency-sync` |
| Blocked but dependency appears closed | blocked workstream with cleared dependency or empty blocked reason | `revisit` |
| Open decision blocks execution | blocking decision connected to workstream/task | `needs-human` |
| File-backed mismatch | missing index entry, stale `updated`, `needs_review`, or status disagreement | `needs-consistency-sync` |
| Too broad for one session | many unrelated task clusters in one workplan | `split` |
| Safety-sensitive | security, identity, secrets, legal, external reputation, money | `needs-human` |
Use these as prompts for judgment, not as automatic status changes.
## WSJF Procedure
Score every reported candidate with:
```text
WSJF = (strategic_value + time_criticality + risk_reduction + opportunity_enablement) / job_size
```
Use integer scores from 1 to 5.
### Strategic Value
Score higher when the work aligns with:
- current Custodian/State Hub operating reliability
- dependency-chain foundations: Railiance, identity, secrets, backup, HA
- explicit `planning_priority: high` or low `planning_order`
- active repo/domain goals
- closing a workstream that is already consuming coordination attention
### Time Criticality
Score higher when waiting increases:
- operational risk or data-loss risk
- number of blocked downstream plans
- context decay for partially completed work
- queue pressure from accumulating open tasks
### Risk Reduction
Score higher when the work reduces:
- security, identity, backup, restore, deployment, or consistency risk
- false dashboard state or stale State Hub records
- manual recovery burden
- ambiguity around human approvals
### Opportunity Enablement
Score higher when the work unlocks:
- multiple downstream workstreams
- agent autonomy or fewer repeated setup steps
- reliable cross-repo operation
- future daily triage quality
### Job Size
Score lower numbers for easier jobs:
| Score | Meaning |
|-------|---------|
| 1 | tiny, clear, can likely close in one focused session |
| 2 | small, local, low uncertainty |
| 3 | moderate, several files or one external dependency |
| 4 | large, multi-repo, needs coordination or testing |
| 5 | broad/uncertain, likely should be split before execution |
### Confidence
Use:
- `high` when State Hub summary, workplan file, and recent progress agree
- `medium` when the score relies on summary data plus one corroborating source
- `low` when the workplan file is missing, stale, blocked by dirty repo state,
or based mostly on inference
## Recommendation Actions
| Action | Meaning | Agent may proceed when | Human gate required when |
|--------|---------|------------------------|--------------------------|
| `work-next` | Best next executable task | scope is local, reversible, and inside an existing approved workplan | it touches money, legal, secrets, public reputation, or external commitments |
| `revisit` | Re-read and refresh before execution | the plan is stale, ambiguous, blocked, or context has moved | revisiting changes purpose, scope, owner, or approval posture |
| `split` | Break an oversized workplan into smaller plans | split is file-backed and preserves provenance | split would drop scope, change priorities, or alter commitments |
| `park` | Move out of active focus | plan is clearly not current and parking is proposed only | actually changing status to backlog/archive needs review |
| `close-out` | Finish closure review and mark done when appropriate | remaining tasks are truly done/cancelled/carry-forwarded | tasks are ambiguous, cancelled for policy reasons, or external effects are involved |
| `needs-human` | Human decision or approval needed | never auto-resolve; report the ask crisply | always |
| `needs-cross-agent` | Another repo/agent is the right owner | send/prepare a coordination message or task only when requested | when ownership or priority is uncertain |
| `needs-consistency-sync` | File/DB/index state should be reconciled | running read/check/fix consistency is already allowed by repo protocol | sync would overwrite work or local repo is behind remote |
## Report Template
Write the daily note in this shape:
```markdown
---
id: daily-statehub-triage-YYYY-MM-DD
type: working-memory
created: "YYYY-MM-DD"
related_workplan: CUST-WP-0044
source: daily-state-hub-wsjf-triage
---
# Daily State Hub WSJF Triage - YYYY-MM-DD
## Snapshot
- Generated at: <timestamp>
- Workstreams: <active> active, <blocked> blocked, <finished> finished
- Tasks: <todo> todo, <in_progress> in progress, <blocked> blocked
- Decisions: <open> open, <escalated> escalated
- Inbox: <count> unread hub messages
- Input health: <summary of API/MCP/file fallbacks>
## Top Recommendations
| Rank | Action | Candidate | WSJF | Confidence | Why now |
|------|--------|-----------|------|------------|---------|
| 1 | work-next | <workstream/task> | 0.0 | high | <short reason> |
## Loose Ends
| Action | Candidate | Signal | Suggested follow-up |
|--------|-----------|--------|---------------------|
| revisit | <workplan> | <signal> | <next check> |
## Human Or Cross-Agent Attention
- `needs-human`: <decision/task> - <specific ask>
- `needs-cross-agent`: <repo/agent> - <specific handoff>
## Next Custodian Session
1. <first recommended action>
2. <second recommended action>
3. <cleanup/sync action if relevant>
## Progress Event Summary
<One or two sentences suitable for POST /progress/.>
```
## Progress Event
When the State Hub API is reachable, append one progress event for the review:
- `topic_id`: Custodian topic id when known
- `workstream_id`: `99993845-be6a-401d-be98-f8107014abed`
- `event_type`: `daily_triage`
- `summary`: one sentence summarizing the top recommendation and loose-end count
- `detail`: include top three recommendations, input health, and any human gates
Do not mark tasks done from the daily run itself. Task status changes belong to
the implementation session that applies a recommendation.

32
workplans/CUST-WP-0044-daily-statehub-wsjf-triage.md
View File

@@ -121,7 +121,7 @@ Tiebreakers:
```task ```task
id: CUST-WP-0044-T01 id: CUST-WP-0044-T01
status: todo status: done
priority: high priority: high
state_hub_task_id: "cb450d56-b606-4c89-9e6e-64e139d6ac6b" state_hub_task_id: "cb450d56-b606-4c89-9e6e-64e139d6ac6b"
``` ```
@@ -145,7 +145,7 @@ guessing what to inspect or how to structure the result.
```task ```task
id: CUST-WP-0044-T02 id: CUST-WP-0044-T02
status: todo status: done
priority: high priority: high
depends_on: [CUST-WP-0044-T01] depends_on: [CUST-WP-0044-T01]
state_hub_task_id: "078c547b-82e0-4ae9-a29c-7bab930924da" state_hub_task_id: "078c547b-82e0-4ae9-a29c-7bab930924da"
@@ -170,7 +170,7 @@ Done when a daily run can complete unattended and leave a useful report.
```task ```task
id: CUST-WP-0044-T03 id: CUST-WP-0044-T03
status: todo status: done
priority: high priority: high
depends_on: [CUST-WP-0044-T01] depends_on: [CUST-WP-0044-T01]
state_hub_task_id: "85fb98ba-3716-4524-88d2-6340a3674d0a" state_hub_task_id: "85fb98ba-3716-4524-88d2-6340a3674d0a"
@@ -196,7 +196,7 @@ without pretending the score is more precise than the evidence supports.
```task ```task
id: CUST-WP-0044-T04 id: CUST-WP-0044-T04
status: todo status: done
priority: high priority: high
state_hub_task_id: "14b3be2c-fe9e-464e-8db5-ec1b293f5829" state_hub_task_id: "14b3be2c-fe9e-464e-8db5-ec1b293f5829"
``` ```
@@ -220,7 +220,7 @@ each candidate needs attention.
```task ```task
id: CUST-WP-0044-T05 id: CUST-WP-0044-T05
status: todo status: done
priority: medium priority: medium
depends_on: [CUST-WP-0044-T03, CUST-WP-0044-T04] depends_on: [CUST-WP-0044-T03, CUST-WP-0044-T04]
state_hub_task_id: "0b2d01e4-8c64-4b2f-bb51-502f6c1af975" state_hub_task_id: "0b2d01e4-8c64-4b2f-bb51-502f6c1af975"
@@ -279,3 +279,25 @@ Custodian habit.
- Daily runs leave progress events so future sessions can see the review. - Daily runs leave progress events so future sessions can see the review.
- No canonical workplan or canon changes happen without the appropriate review - No canonical workplan or canon changes happen without the appropriate review
gate. gate.
## Implementation Notes - 2026-05-17
The daily triage loop now has two explicit layers:
- Active runner: Codex app automation `daily-state-hub-wsjf-triage`.
- Durable target substrate: activity-core ActivityDefinition draft at
`activity-definitions/daily-statehub-wsjf-triage.md`.
The reusable prompt, report template, WSJF procedure, loose-end detectors, and
recommendation gates live in
`runtime/prompts/daily_statehub_wsgi_triage.md`.
The activity-core definition is intentionally disabled while the Codex
automation is the active runner. It exists so the schedule and context contract
are reviewable in the same Markdown-as-definition style activity-core already
uses. When activity-core can run a Custodian agent/report action directly, this
definition should be enabled and the Codex app automation disabled, keeping a
single daily runner.
T06 remains open because it requires three actual daily runs and calibration
against follow-up work.