diff --git a/AGENTS.md b/AGENTS.md index e90c0c1..8eb2a60 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -119,7 +119,8 @@ curl -s -X PATCH "http://127.0.0.1:8000/tasks/" \ 4. Check human-needed tasks: `GET /tasks/?needs_human=true` **During work:** -- Update task statuses in workplan files as tasks progress +- Update task statuses and refine task structure after substantial work; record + completed deliverables and split remaining scope (see Workplan Convention) - Record significant decisions via `POST /decisions/` **Close:** @@ -202,6 +203,36 @@ get wrong. Work items originate as files in this repo — not in the hub. The hub is a read/cache/index layer that rebuilds from files. +### Task refinement after substantial work (required) + +At each substantive checkpoint and before session close, compare the completed +work and new knowledge with the current task structure. If substantial work was +completed while the workplan's task granularity stayed unchanged, **add completed +task records for those evidenced outcomes and refine the remaining tasks**. +A long progress note inside the same broad open task does not satisfy this rule. + +- Give each substantial completed deliverable a task with its actual outcome, + completion date, evidence and limits. Retrospective recording is allowed; do + not invent completion dates, deliveries, native acceptance or approvals. +- Split remaining work into independently manageable deliverables with an owner, + next action, completion criteria and real dependencies. Use `todo` for work + that can start; use `wait` only with a concrete prerequisite and unblock condition. +- Preserve existing task IDs, Hub UUIDs and history. When narrowing an umbrella + task, explain the split and map moved scope to the new task IDs. Do not mark + the umbrella done unless its retained scope is complete; preserve externally + referenced acceptance gates until their dependencies are satisfied. +- Keep task counts honest: extracting completed scope must not count the same + outcome twice or imply an effort-based completion percentage. Distinguish + source/fixture proof, actual operational proof and owner acceptance. +- Record new risks and out-of-scope findings as explicit disposition/handoff + tasks or linked live work records; do not silently expand authorization. + +Make these changes in the repository source, commit/push, run the repository's +required projection sync, and verify the actual projected task counts, statuses +and dependencies. Progress events supplement the task structure; they do not +replace it. A checkpoint report must show both substantive outcomes and newly +refined remaining work when this rule is triggered. + **File location:** `workplans/STATE-WP-NNNN-.md` **Archived location:** finished workplans may move to diff --git a/docs/workplan-convention.md b/docs/workplan-convention.md index 6c763ac..f3a4a69 100644 --- a/docs/workplan-convention.md +++ b/docs/workplan-convention.md @@ -64,3 +64,33 @@ a live work record: Canon: `the-custodian/canon/standards/work-record-types_v0.1.md` § Residuals. Hub index/list: State Hub (not domain-local residual files). + +### Task refinement after substantial work (required) + +At each substantive checkpoint and before session close, compare the completed +work and new knowledge with the current task structure. If substantial work was +completed while the workplan's task granularity stayed unchanged, **add completed +task records for those evidenced outcomes and refine the remaining tasks**. +A long progress note inside the same broad open task does not satisfy this rule. + +- Give each substantial completed deliverable a task with its actual outcome, + completion date, evidence and limits. Retrospective recording is allowed; do + not invent completion dates, deliveries, native acceptance or approvals. +- Split remaining work into independently manageable deliverables with an owner, + next action, completion criteria and real dependencies. Use `todo` for work + that can start; use `wait` only with a concrete prerequisite and unblock condition. +- Preserve existing task IDs, Hub UUIDs and history. When narrowing an umbrella + task, explain the split and map moved scope to the new task IDs. Do not mark + the umbrella done unless its retained scope is complete; preserve externally + referenced acceptance gates until their dependencies are satisfied. +- Keep task counts honest: extracting completed scope must not count the same + outcome twice or imply an effort-based completion percentage. Distinguish + source/fixture proof, actual operational proof and owner acceptance. +- Record new risks and out-of-scope findings as explicit disposition/handoff + tasks or linked live work records; do not silently expand authorization. + +Make these changes in the repository source, commit/push, run the repository's +required projection sync, and verify the actual projected task counts, statuses +and dependencies. Progress events supplement the task structure; they do not +replace it. A checkpoint report must show both substantive outcomes and newly +refined remaining work when this rule is triggered. diff --git a/scripts/project_rules/agents-codex.template b/scripts/project_rules/agents-codex.template index 02dac66..7f5bd55 100644 --- a/scripts/project_rules/agents-codex.template +++ b/scripts/project_rules/agents-codex.template @@ -109,7 +109,8 @@ curl -s -X PATCH "http://127.0.0.1:8000/tasks/" \ 4. Check human-needed tasks: `GET /tasks/?needs_human=true` **During work:** -- Update task statuses in workplan files as tasks progress +- Update task statuses and refine task structure after substantial work; record + completed deliverables and split remaining scope (see Workplan Convention) - Record significant decisions via `POST /decisions/` **Close:** @@ -143,6 +144,36 @@ curl -s -X PATCH "http://127.0.0.1:8000/tasks/" \ Work items originate as files in this repo — not in the hub. The hub is a read/cache/index layer that rebuilds from files. +### Task refinement after substantial work (required) + +At each substantive checkpoint and before session close, compare the completed +work and new knowledge with the current task structure. If substantial work was +completed while the workplan's task granularity stayed unchanged, **add completed +task records for those evidenced outcomes and refine the remaining tasks**. +A long progress note inside the same broad open task does not satisfy this rule. + +- Give each substantial completed deliverable a task with its actual outcome, + completion date, evidence and limits. Retrospective recording is allowed; do + not invent completion dates, deliveries, native acceptance or approvals. +- Split remaining work into independently manageable deliverables with an owner, + next action, completion criteria and real dependencies. Use `todo` for work + that can start; use `wait` only with a concrete prerequisite and unblock condition. +- Preserve existing task IDs, Hub UUIDs and history. When narrowing an umbrella + task, explain the split and map moved scope to the new task IDs. Do not mark + the umbrella done unless its retained scope is complete; preserve externally + referenced acceptance gates until their dependencies are satisfied. +- Keep task counts honest: extracting completed scope must not count the same + outcome twice or imply an effort-based completion percentage. Distinguish + source/fixture proof, actual operational proof and owner acceptance. +- Record new risks and out-of-scope findings as explicit disposition/handoff + tasks or linked live work records; do not silently expand authorization. + +Make these changes in the repository source, commit/push, run the repository's +required projection sync, and verify the actual projected task counts, statuses +and dependencies. Progress events supplement the task structure; they do not +replace it. A checkpoint report must show both substantive outcomes and newly +refined remaining work when this rule is triggered. + **File location:** `workplans/{WP_PREFIX}-NNNN-.md` **Archived location:** finished workplans may move to diff --git a/scripts/project_rules/session-protocol.template b/scripts/project_rules/session-protocol.template index 7c9a58b..7c32368 100644 --- a/scripts/project_rules/session-protocol.template +++ b/scripts/project_rules/session-protocol.template @@ -56,6 +56,12 @@ For each file with `status: ready`, `active`, or `blocked`, note pending If no workplans: follow First Session Protocol (`first-session.md`). +**During work:** Refine task structure at substantive checkpoints. Substantial +completed work must become evidenced completed tasks; split newly understood +remaining work into owned tasks with completion criteria and real dependencies. +Keep stable IDs and map moved scope. Progress prose alone is insufficient. +See workplan-convention.md, “Task refinement after substantial work”. + **During work:** `record_decision()` · `add_progress_event()` · `resolve_decision()` > State Hub is a *read model*. **Never register workplans or tasks by hand** @@ -69,7 +75,8 @@ 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. +1. Refine task structure after substantial work and update statuses in repo files; + record completed deliverables and newly understood remaining tasks before sync. 2. If marking a workplan **finished**: hand off residuals as **live work records** first (intake with `origin: residual` + `origin_ref: `, or a child workplan / decision / engagement). Do not leave actionable leftovers diff --git a/scripts/project_rules/workplan-convention.template b/scripts/project_rules/workplan-convention.template index 81b73be..49376d4 100644 --- a/scripts/project_rules/workplan-convention.template +++ b/scripts/project_rules/workplan-convention.template @@ -80,3 +80,33 @@ identifiers as workplan IDs. Prefer `GET /workplans/` and `workplan_id` in new examples and scripts. + +### Task refinement after substantial work (required) + +At each substantive checkpoint and before session close, compare the completed +work and new knowledge with the current task structure. If substantial work was +completed while the workplan's task granularity stayed unchanged, **add completed +task records for those evidenced outcomes and refine the remaining tasks**. +A long progress note inside the same broad open task does not satisfy this rule. + +- Give each substantial completed deliverable a task with its actual outcome, + completion date, evidence and limits. Retrospective recording is allowed; do + not invent completion dates, deliveries, native acceptance or approvals. +- Split remaining work into independently manageable deliverables with an owner, + next action, completion criteria and real dependencies. Use `todo` for work + that can start; use `wait` only with a concrete prerequisite and unblock condition. +- Preserve existing task IDs, Hub UUIDs and history. When narrowing an umbrella + task, explain the split and map moved scope to the new task IDs. Do not mark + the umbrella done unless its retained scope is complete; preserve externally + referenced acceptance gates until their dependencies are satisfied. +- Keep task counts honest: extracting completed scope must not count the same + outcome twice or imply an effort-based completion percentage. Distinguish + source/fixture proof, actual operational proof and owner acceptance. +- Record new risks and out-of-scope findings as explicit disposition/handoff + tasks or linked live work records; do not silently expand authorization. + +Make these changes in the repository source, commit/push, run the repository's +required projection sync, and verify the actual projected task counts, statuses +and dependencies. Progress events supplement the task structure; they do not +replace it. A checkpoint report must show both substantive outcomes and newly +refined remaining work when this rule is triggered.