coulomb/the-custodian
4
0
Fork 0
Code Issues 1 Pull requests Projects Releases Packages Wiki Activity Actions

feat(terminology): prose sweep tool and custodian workplan cleanup (CUST-WP-0055 T04)
All checks were successful
CI Smoke / host-smoke (push) Successful in 1s
Details
CI Smoke / container-smoke (push) Successful in 6s
Details

Browse source 
Add sweep_workstream_prose.py for agent-guidance files, sweep active workplan
prose in-repo, tighten scan allowlist exclusions, and update ADR-001 closure
protocol to workplan-first terminology.
This commit is contained in:
codex 2026-07-08 16:35:37 +02:00
parent 3bdefb3c4a
commit 2e0deee2ef
42 changed files with 312 additions and 186 deletions
Download patch file Download diff file Expand all files Collapse all files

20
workplans/CUST-WP-0029-token-consumption-tracking.md
View file

@ -17,7 +17,7 @@ state_hub_workstream_id: "6f459d9f-b4d4-46d7-a5d7-d5f10721b29e"
## Goal
Record AI token consumption at task granularity and aggregate it up to
workstream, repo, commit, and release level. Makes agent work visible as a
workplan, repo, commit, and release level. Makes agent work visible as a
cost/effort metric — reviewable alongside tasks, workplans, and releases.
## Background
@ -37,14 +37,14 @@ per iteration. Commit/release tagging is optional and manual.
token_events
id UUID PK
task_id UUID FK tasks (nullable)
workstream_id UUID FK workstreams (nullable)
workstream_id UUID FK workplans (nullable)
repo_id UUID FK managed_repos (nullable)
session_id TEXT -- agent session identifier
model TEXT -- e.g. "claude-sonnet-4-6"
tokens_in INT NOT NULL
tokens_out INT NOT NULL
agent TEXT -- "custodian", "ralph", etc.
ref_type TEXT -- 'task'|'workstream'|'commit'|'release'|'session'
ref_type TEXT -- 'task'|'workplan'|'commit'|'release'|'session'
ref_id TEXT -- commit SHA, release tag, etc.
note TEXT
created_at TIMESTAMPTZ server_default=now()
@ -56,7 +56,7 @@ Aggregation endpoint rolls up by any FK axis.
## Exit Criteria
- Token events can be recorded via MCP tool
- Aggregation queries work for task / workstream / repo / commit / release
- Aggregation queries work for task / workplan / repo / commit / release
- Dashboard page shows token spend by repo, workplan, model
- `ralph-workplan` logs a token event per completed task iteration
- All tests passing; consistency check clean
@ -94,7 +94,7 @@ state_hub_task_id: "57d71132-001a-4c85-bc39-2d20155c4971"
```
Add `api/models/token_event.py` (SQLAlchemy ORM, relationships to Task,
Workstream, ManagedRepo). Add `api/schemas/token_event.py`:
Workplan, ManagedRepo). Add `api/schemas/token_event.py`:
- `TokenEventCreate` — input (task_id, workstream_id, repo_id all nullable;
tokens_in, tokens_out required; model, agent, ref_type, ref_id, note optional)
@ -125,7 +125,7 @@ Add `api/routers/token_events.py`:
- `GET /token-events/` — list with filters: `task_id`, `workstream_id`,
`repo_id`, `ref_type`, `ref_id`, `model`, `agent`; default limit 100
- `GET /token-events/summary/` — aggregation; required query param `scope`
(`task`|`workstream`|`repo`|`commit`|`release`) + `id` (the FK value or
(`task`|`workplan`|`repo`|`commit`|`release`) + `id` (the FK value or
ref_id). Returns `TokenSummary`.
Register router in `api/main.py`.
@ -149,7 +149,7 @@ Add two tools to `mcp_server/server.py`:
**`record_token_event(tokens_in, tokens_out, task_id?, workstream_id?,
repo_id?, model?, agent?, ref_type?, ref_id?, note?, session_id?)`**
- POSTs to `/token-events/`
- Returns the created event id and running total for the task/workstream
- Returns the created event id and running total for the task/workplan
**`get_token_summary(scope, id)`**
- GETs `/token-events/summary/?scope=X&id=Y`
@ -195,13 +195,13 @@ state_hub_task_id: "02cc5d8e-a9da-4fb3-9c39-fdc05812d8d0"
Add `dashboard/src/token-cost.md` Observable page:
- **By repo bar chart** — total tokens per repo (stacked in/out)
- **By workplan table** — workstream slug, title, tokens_total, event_count,
- **By workplan table** — workplan slug, title, tokens_total, event_count,
dominant model
- **By model breakdown** — pie or bar; shows model mix across all events
- **Top 10 tasks by tokens** — useful for identifying expensive tasks
Data loader: `dashboard/src/data/token-summary.json.py` — calls
`GET /token-events/summary/` for each repo and workstream.
`GET /token-events/summary/` for each repo and workplan.
Add page to `observablehq.config.js` nav under "Analytics".
@ -247,7 +247,7 @@ state_hub_task_id: "a3627144-9d98-4a3b-aa64-3079fd087448"
Add tests to `state-hub/tests/`:
- `test_token_events.py`: create event, list with filter, summary aggregation
(single task, cross-workstream rollup, by-model breakdown)
(single task, cross-workplan rollup, by-model breakdown)
- `test_token_passthrough.py`: `update_task_status` with tokens creates event
Run `make test`. Run `make fix-consistency REPO=the-custodian`.