From b60599f09f3b28a1caef70264e2c4e7178aadb28 Mon Sep 17 00:00:00 2001 From: codex Date: Wed, 22 Jul 2026 18:15:45 +0200 Subject: [PATCH] docs: residual handoff as work records (role, not kind) Canon work-record-types: residuals use intake/workplan/decision with origin residual|handoff and origin_ref parent WP. Schema origin_ref; agent close protocol aligned. --- AGENTS.md | 14 ++++++- .../schemas/work-records/intake.schema.json | 9 +++- canon/standards/work-record-types.yaml | 9 +++- canon/standards/work-record-types_v0.1.md | 41 ++++++++++++++++++- 4 files changed, 67 insertions(+), 6 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 672a9c1..37ab453 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -97,8 +97,12 @@ curl -s -X PATCH "http://127.0.0.1:8000/tasks/" \ **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: `, or a next workplan / + decision / engagement). Do not park leftovers only in prose or `SCOPE.md`. + Canon: `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 ``` @@ -219,6 +223,12 @@ 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: CUST-WP-NNNN`) or a spawned workplan. Residual is a *role*, +not a kind. Fleet list lives on State Hub, not in `SCOPE.md`. Canon: +`canon/standards/work-record-types_v0.1.md` § Residuals. + To create a new workplan: 1. Write the file following the format above 2. Notify the custodian operator to run `make fix-consistency REPO=the-custodian` diff --git a/canon/standards/schemas/work-records/intake.schema.json b/canon/standards/schemas/work-records/intake.schema.json index 8c6a3aa..99c7456 100644 --- a/canon/standards/schemas/work-records/intake.schema.json +++ b/canon/standards/schemas/work-records/intake.schema.json @@ -17,7 +17,14 @@ "priority": { "enum": ["high", "medium", "low"] }, "pulls_from": { "type": "array" }, "promoted_to": { "type": "string", "description": "Canonical id of the record this intake was promoted to." }, - "origin": { "type": "string" }, + "origin": { + "type": "string", + "description": "Where the spark came from. Residuals use residual|handoff; also e.g. legacy-suggestion:, mail-triage ids." + }, + "origin_ref": { + "type": "string", + "description": "Stable reference into the origin (parent workplan id for residuals, e.g. BINKY-WP-0006)." + }, "notes": { "type": "string" }, "state_hub_intake_id": { "$ref": "spine.schema.json#/$defs/uuid" } }, diff --git a/canon/standards/work-record-types.yaml b/canon/standards/work-record-types.yaml index 8831637..0fd19ee 100644 --- a/canon/standards/work-record-types.yaml +++ b/canon/standards/work-record-types.yaml @@ -61,4 +61,11 @@ spine_fields: lanes: [green, blue, yellow, orange, red] tags: derived: [stalled, stale, overdue-decision, budget-breached, orphaned] - policy: [automatable, needs-human, unclear-implementation, red-adjacent, compliance-relevant] + policy: [automatable, needs-human, unclear-implementation, red-adjacent, compliance-relevant, residual] +# Residual is a *role*, not a kind: capture as intake/workplan/decision/… +# with origin: residual|handoff and origin_ref: . See +# work-record-types_v0.1.md § Residuals. +origin_values_recommended: + residual: residual + handoff: handoff + legacy_suggestion_prefix: "legacy-suggestion:" diff --git a/canon/standards/work-record-types_v0.1.md b/canon/standards/work-record-types_v0.1.md index fce2ed6..28c28c0 100644 --- a/canon/standards/work-record-types_v0.1.md +++ b/canon/standards/work-record-types_v0.1.md @@ -6,7 +6,7 @@ domain: custodian status: active version: "0.1" created: "2026-07-20" -updated: "2026-07-20" +updated: "2026-07-22" scope: fleet related_workplans: - CUST-WP-0060 @@ -111,6 +111,38 @@ per-work-kind gates (e.g. compliance tasks cannot exit `progress` without an evidence link). Profiles are YAML in repos, in the same reconciliation loop. +## Residuals (role, not kind) + +A **residual** is work intentionally left after a workplan (or large task +bundle) finishes. It is **not** a registered kind — inventing a parallel +“residuals queue” or parking leftovers only in `SCOPE.md` / finished-file +prose is a process defect. Residuals must be **live work records** so the +hub can list them across repos and domains. + +| Residual shape | Capture as | Required links | +| --- | --- | --- | +| Small Green/Blue follow-up, parkable | **intake** (e.g. AWQ / `*-IN-*`) | `origin: residual`, `origin_ref: ` | +| Multi-step / dependency-bearing | **workplan** (spawn next WP) | body or frontmatter names parent WP; optional `origin`/`origin_ref` when promoted from intake | +| Needs founder choice | **decision** | same origin fields when created from residual intake | +| Needs founder time window | **engagement** | same | +| Persistent gap / risk | **register-entry** (risk, tech debt, …) | cross-link parent WP in notes | + +**Close discipline for finished workplans:** + +1. Short residual **narrative** may remain under the closing task (human + context). +2. **Before** `status: finished`, each residual that is still actionable + becomes a live record (intake and/or child workplan). Prose alone is not + the backlog. +3. Progress milestone may name the handoff ids. +4. `statehub fix-consistency` so the index (`WORK-RECORDS.md`, hub) reflects + the handoff. + +**Fleet list (future CLI):** filter open/vetted/routed intakes (and ready/ +active workplans) with `origin ∈ {residual, handoff}` and optional +`topic_id` / `repo` / `origin_ref`. Implementation home for that query is +**state-hub** (`statehub residuals` / API), not domain repos. + ## Source files, index, and views 1. **Any repo file is a potential source of work records.** Records are @@ -135,10 +167,15 @@ Two classes, both in `tags`, never in `status`: `overdue-decision`, `budget-breached`, `orphaned`. - **Policy tags** — assigned under tagging policies: `automatable`, `needs-human`, `unclear-implementation`, `red-adjacent`, - `compliance-relevant`. + `compliance-relevant`, `residual` (optional badge when origin is not used). States migrate badly; tags migrate trivially. Anything situational is a tag. +**Origin values (intake and promoted children):** use stable strings, not free +prose. For residuals prefer `origin: residual` (or `handoff`) and +`origin_ref: ` (e.g. `BINKY-WP-0006`). Other established +origins (e.g. `legacy-suggestion:`, mail-triage ids) remain valid. + ## Budgets Guardrail envelopes resolve programmatically at run start: