docs(workplans): require task refinement after substantial progress

Assistant: codex
Assistant-Model: gpt-6-astra
Assistant-Session: 01a13eab-1e6a-7b33-9c37-372e90ada3a2

AGENTS.md

@@ -119,7 +119,8 @@ curl -s -X PATCH "http://127.0.0.1:8000/tasks/<task_id>" \
 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-<slug>.md`
 
 **Archived location:** finished workplans may move to

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.

scripts/project_rules/agents-codex.template

@@ -109,7 +109,8 @@ curl -s -X PATCH "http://127.0.0.1:8000/tasks/<task_id>" \
 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/<task_id>" \
 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-<slug>.md`
 
 **Archived location:** finished workplans may move to

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: <WP-id>`, or
    a child workplan / decision / engagement). Do not leave actionable leftovers

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.
 
 <!-- Ralph Loop rules and HEUREKA sequence: ~/.claude/CLAUDE.md — do not duplicate here -->
+
+### 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.