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

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
context.py Observe: fetch state-hub data + build LLM context prompt
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)
tool_adapters/ Additional MCP/API tool adapters (future)
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`.
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
```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.