diff --git a/activity-definitions/daily-statehub-wsjf-triage.md b/activity-definitions/daily-statehub-wsjf-triage.md new file mode 100644 index 0000000..f7b9370 --- /dev/null +++ b/activity-definitions/daily-statehub-wsjf-triage.md @@ -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`. diff --git a/runtime/README.md b/runtime/README.md index ccf924c..df6c9f4 100644 --- a/runtime/README.md +++ b/runtime/README.md @@ -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 diff --git a/runtime/prompts/daily_statehub_wsgi_triage.md b/runtime/prompts/daily_statehub_wsgi_triage.md new file mode 100644 index 0000000..3fba7f8 --- /dev/null +++ b/runtime/prompts/daily_statehub_wsgi_triage.md @@ -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=` for a top-ranked workstream +- `GET /progress/?workstream_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: +- Workstreams: active, blocked, finished +- Tasks: todo, in progress, blocked +- Decisions: open, escalated +- Inbox: unread hub messages +- Input health: + +## Top Recommendations + +| Rank | Action | Candidate | WSJF | Confidence | Why now | +|------|--------|-----------|------|------------|---------| +| 1 | work-next | | 0.0 | high | | + +## Loose Ends + +| Action | Candidate | Signal | Suggested follow-up | +|--------|-----------|--------|---------------------| +| revisit | | | | + +## Human Or Cross-Agent Attention + +- `needs-human`: - +- `needs-cross-agent`: - + +## Next Custodian Session + +1. +2. +3. + +## Progress Event Summary + + +``` + +## 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. diff --git a/workplans/CUST-WP-0044-daily-statehub-wsjf-triage.md b/workplans/CUST-WP-0044-daily-statehub-wsjf-triage.md index 847e44d..56e87a7 100644 --- a/workplans/CUST-WP-0044-daily-statehub-wsjf-triage.md +++ b/workplans/CUST-WP-0044-daily-statehub-wsjf-triage.md @@ -121,7 +121,7 @@ Tiebreakers: ```task id: CUST-WP-0044-T01 -status: todo +status: done priority: high state_hub_task_id: "cb450d56-b606-4c89-9e6e-64e139d6ac6b" ``` @@ -145,7 +145,7 @@ guessing what to inspect or how to structure the result. ```task id: CUST-WP-0044-T02 -status: todo +status: done priority: high depends_on: [CUST-WP-0044-T01] 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 id: CUST-WP-0044-T03 -status: todo +status: done priority: high depends_on: [CUST-WP-0044-T01] 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 id: CUST-WP-0044-T04 -status: todo +status: done priority: high state_hub_task_id: "14b3be2c-fe9e-464e-8db5-ec1b293f5829" ``` @@ -220,7 +220,7 @@ each candidate needs attention. ```task id: CUST-WP-0044-T05 -status: todo +status: done priority: medium depends_on: [CUST-WP-0044-T03, CUST-WP-0044-T04] 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. - No canonical workplan or canon changes happen without the appropriate review 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.