coulomb/state-hub
4
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

docs: residual handoff in hub docs, AGENTS, and templates
Some checks failed
CI Smoke / host-smoke (push) Successful in 1s
Details
CI Smoke / container-smoke (push) Has been cancelled
Details

Browse source 
Align agent close/workplan finish with fleet residual convention
(live work records, origin residual + origin_ref). Reference pages for
work-records and intakes; session and workplan templates updated.
This commit is contained in:
tegwick 2026-07-22 18:15:45 +02:00
parent b5747d1104
commit f8bd74e27e
10 changed files with 480 additions and 30 deletions
Download patch file Download diff file Expand all files Collapse all files

13
scripts/project_rules/agents-codex.template
View file

@ -97,8 +97,12 @@ curl -s -X PATCH "http://127.0.0.1:8000/tasks/<task_id>" \
**Close:**
1. Update workplan file task statuses to reflect progress
2. Log: `POST /progress/` with a summary of what changed
3. After workplan file changes, run:
2. If finishing a workplan: hand off **residuals** as live work records first
(intake with `origin: residual` + `origin_ref: <WP-id>`, or a next workplan /
decision / engagement). Do not park leftovers only in prose or `SCOPE.md`.
Canon: `the-custodian/canon/standards/work-record-types_v0.1.md` § Residuals.
3. Log: `POST /progress/` with a summary of what changed (name handoff ids)
4. After workplan file changes, run:
```bash
statehub fix-consistency
```
@ -174,6 +178,11 @@ Task description text.
Status progression: `todo` → `progress` → `done`; use `wait` for waiting/blocked work and `cancel` for stopped work.
**Residuals when finishing:** actionable leftovers become live work records
before `status: finished` — usually an intake (`origin: residual`,
`origin_ref: {WP_PREFIX}-NNNN`) or a spawned workplan. Residual is a *role*,
not a kind. Fleet list lives on State Hub, not in `SCOPE.md`.
To create a new workplan:
1. Write the file following the format above
2. Run `statehub fix-consistency` locally; ask the operator only if the CLI or

8
scripts/project_rules/session-protocol.template
View file

@ -66,6 +66,14 @@ If no workplans: follow First Session Protocol (`first-session.md`).
> see `workplan-convention.md` (compatibility footnote).
**Session close:**
1. Update workplan/task statuses in repo files.
2. If marking a workplan **finished**: hand off residuals as **live work
records** first (intake with `origin: residual` + `origin_ref: <WP-id>`, or
a child workplan / decision / engagement). Do not leave actionable leftovers
only as prose or in `SCOPE.md`. See work-record-types § Residuals.
3. Log progress (below).
4. `statehub fix-consistency` when workplan/queue files changed.
With MCP tools:
```
add_progress_event(summary="...", topic_id="{TOPIC_ID}", workplan_id="<uuid>")

16
scripts/project_rules/workplan-convention.template
View file

@ -38,6 +38,22 @@ state_hub_task_id: "<uuid>" # written by fix-consistency — do not edit
Status progression is `todo` → `progress` → `done`; use `wait` for waiting or
blocked work and `cancel` for stopped work.
### Residuals (role, not kind)
When finishing a workplan, **actionable leftovers must become live work
records** before `status: finished`. Residual is not a registered kind and
must not be parked only in `SCOPE.md` or finished-file prose.
| Shape | Capture as | Links |
| --- | --- | --- |
| Small Green/Blue parkable | intake (queue YAML / `*-IN-*`) | `origin: residual`, `origin_ref: {WP_PREFIX}-NNNN` |
| Multi-step | next workplan | name parent WP; optional promote from residual intake |
| Founder gate / time | decision / engagement | same origin fields when from residual intake |
Fleet listing of residuals is a State Hub concern (`list_intakes` + origin
filters; planned `statehub residuals`). Canon:
`the-custodian/canon/standards/work-record-types_v0.1.md` § Residuals.
Workplan frontmatter carries `state_hub_workstream_id` — a legacy field name
kept for compatibility; it holds the hub workplan UUID and is written by
fix-consistency. Do not edit or rename it.