Document bounded continuous task handoff recovery

nextTask.md

@@ -0,0 +1,216 @@
+# Continuous Task Handoff
+
+This file is the bounded continuation entrypoint for the Blender Web execution
+queue. It is a procedure, not a second task pointer. The only authoritative
+pointer is `docs/EXECUTION_QUEUE.md` plus the parent manifest named there.
+
+## Copyable Resume Prompt
+
+Use the following prompt in a fresh request when continuous execution is
+needed. It deliberately names the bounded one-task-per-request contract so a
+long chain of tasks does not become one oversized context or remote compact
+payload:
+
+```text
+按 nextTask.md 接续执行。
+
+Treat this as an execution command, not a request for a plan or status report.
+Read docs/EXECUTION_QUEUE.md, run print-task-context, then run
+check-task-context before editing. Read only the current task card, parent
+manifest/status, and the focused files named by the task context. Do not open
+the full next-task-plan.json, all status logs, or historical project plans.
+
+Complete exactly one current task end to end: implement the scoped behavior,
+run the focused desktop/npm/direct checks, verify save/reopen and the negative
+case, write reports/status/manifest/task-context with SHA-256 values, then run
+governance checks and git diff --check. Advance the queue only after every
+exit criterion and hash check passes, using repository generators for the
+task index/catalog/card. On any failure or hash drift, keep the task
+in_progress/blocked and do not advance nextTask.
+
+Keep tool output and context bounded. Do not paste long logs or carry the
+previous task transcript into the next request. After handoff, the next
+invocation of this same prompt starts from a fresh print-task-context package.
+This request has a hard stop after this one task: do not inspect, implement, or
+start the next task in the same request, even when the current task finishes
+early. End with only a compact checkpoint summary (task, state, nextTask,
+command exit codes, and artifact paths/hashes).
+For stream-disconnect or remote-compact errors, stop the active request and
+use the recovery procedure below in a new request. Do not paste the failed
+transcript, invoke another compact operation, or blindly repeat a state-
+changing command.
+```
+
+## Resume Command
+
+When the user says:
+
+```text
+按 nextTask.md 接续执行
+```
+
+the phrase is an execution command, not a request for a plan or status report.
+Resume implementation autonomously from the repository checkpoint. Do not
+ask for confirmation, wait for a second message, or stop at a proposal while
+the queue and parent manifest are valid. A wording variant that quotes the
+same exact phrase has the same meaning; unrelated requests for explanation,
+review, or diagnosis do not activate this procedure.
+
+“连续” means:
+
+1. Start the task named by the current `docs/EXECUTION_QUEUE.md` pointer.
+2. Finish or safely checkpoint that one task.
+3. Write its manifest/status/task-context handoff and generate the next task
+   pointer through repository tools.
+4. On the next invocation of this command, start immediately from that new
+   pointer and a fresh compact context package.
+
+There is no intentional idle step between a valid handoff and the next
+invocation. This still means one task per execution turn/request: never run
+multiple numbered tasks in one request and never carry the previous task's
+full transcript, logs, or source context into the next request.
+
+## Activation Contract
+
+The phrase activates implementation only when the queue is internally
+consistent. Before editing, the agent must prove all of the following:
+
+- `print-task-context` reports the queue's current task and its parent
+  manifest.
+- `check-task-context` passes without `--write`.
+- The queue task exactly equals the parent manifest's `nextTask`.
+- The task card, production entrypoint, and focused test entrypoint exist.
+
+If any proof fails, preserve the queue and report the checkpoint blocker. Do
+not infer a task number from `nextTask.md`, historical status files, or a
+previous conversation.
+
+## Fresh-Context Boundary
+
+Handle at most one task per execution turn/request. At the end of a task, the
+machine handoff is the checkpoint; begin the next task from a fresh compact
+context package instead of carrying the previous transcript, logs, or source
+files forward. This keeps remote compact/reconnect payloads bounded while
+preserving continuous execution across turns.
+
+The handoff is durable only after the manifest, status, task-context, artifact
+hashes, and governance checks agree. A task that fails, is cancelled, exceeds
+budget, lacks its environment, or has hash drift remains `in_progress` or
+`blocked`; the next invocation resumes that same task instead of advancing.
+
+For every task, run this exact order:
+
+1. Read `docs/EXECUTION_QUEUE.md`.
+2. Run `node tools/web/print-task-context.mjs` and read only its required files,
+   task-card inputs, and named production/test entrypoints.
+3. Run `node tools/web/check-task-context.mjs` before any edit. Stop if the
+   queue task is not exactly the parent manifest's `nextTask`.
+4. Implement and verify only that task card's one behavior/evidence slice.
+5. Keep command output out of the conversation. For output that may be long,
+   write `> tests/golden/<task>/command.log 2>&1`, record the exit code, and
+   report only a short tail plus the artifact paths and SHA-256 values.
+6. Only after all exit criteria pass, run:
+
+   ```bash
+   node tools/web/check-task-context.mjs --task <task-id> --write
+   ```
+
+7. Write the report, status, manifest, and task context. A failed command,
+   missing environment, or hash drift keeps the task `in_progress`/`blocked`;
+   never advance the queue in that state.
+8. Re-run the governance checks and stop after reporting this task's checkpoint.
+   The next task is started only by a new request using this prompt and a fresh
+   context package.
+
+The normal post-handoff checks are:
+
+```bash
+node tools/web/check-blender-next-task-plan.mjs
+node tools/web/check-task-index.mjs
+npm --prefix web run test:task-context
+npm --prefix web run test:context-governance
+node tools/web/check-context-governance.mjs
+git diff --check
+```
+
+Do not manually edit `nextTask`, task-index offsets, catalog lines, or parent
+evidence. Generate them through the repository tools and update the queue only
+to the newly completed manifest pointer.
+
+## Transport/Compaction Recovery
+
+`stream disconnected`, `error decoding response body`, or a remote compact
+failure means that the request outcome is unknown. It is not evidence that the
+task failed or succeeded. Do not blindly repeat a generator, build, save, or
+queue-writing command.
+
+Recover with read-only checks first:
+
+```bash
+node tools/web/print-task-context.mjs
+node tools/web/check-task-context.mjs
+git status --short
+```
+
+Then compare the current task's manifest, status, task-context, and artifact
+hashes. Continue from the first missing handoff step; if every criterion is
+already recorded, run only the missing governance/check command. The failed
+request's outcome is unknown, so do not claim success from the error message.
+Resume the request at most once. If the resumed request disconnects again,
+leave the task `in_progress`/`blocked`, preserve all files, and report the exact
+command and checkpoint state rather than starting a retry loop.
+
+If the client supplies a session id, `codex resume <session-id>` may be used,
+but the resumed turn must still reread the queue and print a fresh context. Do
+not paste the old transcript or full logs into the new request. Without a
+session id, start a new turn with this file and the repository checkpoint.
+The user does not need to repeat the failed command: the next invocation of
+the exact resume phrase performs the read-only recovery checks first and
+continues from the first missing handoff step.
+
+The recovery request must not include the old transcript or full command logs:
+
+```text
+按 nextTask.md 接续执行。
+
+上一请求发生 stream disconnected / remote compact failure。先只读运行
+node tools/web/print-task-context.mjs、node tools/web/check-task-context.mjs
+和 git status --short；比较当前 task 的 manifest、status、task-context 与
+artifact SHA-256，只从第一个缺失的交接步骤继续。不要重复任何未知结果的
+生成、构建、保存或队列写入命令；本请求仍只完成一个 task，完成后立即停止。
+```
+
+## Current Handoff Snapshot
+
+Recorded: 2026-08-22 America/New_York
+
+| Field | Value |
+| --- | --- |
+| Current task when this file was written | `M16-GAP-00227` |
+| Current task state | `in_progress` |
+| Parent manifest | `tests/golden/M16-GAP-00226/manifest.json` |
+| Current task card | `docs/tasks/M16-GAP-00227.md` |
+| Current task-context nextTask | `M16-GAP-00228` |
+| Focused command | `npm --prefix web run test:generated-gap -- --task M16-GAP-00227` |
+
+The snapshot is informational and may become stale. On every resume, the queue,
+parent manifest, and fresh `print-task-context` output win. Never infer a task
+number from this table or from historical status files.
+
+## Non-Negotiable Boundaries
+
+- Chromium is the only permitted browser runtime; never run Firefox or WebKit.
+- Do not read full historical plans, all status logs, or the full gap plan by
+  default.
+- Keep unrelated user changes. Never use `git reset --hard` or `git checkout --`.
+- Keep long-running sessions alive and poll them to completion.
+- If the same blocker persists through three safe investigation attempts, leave
+  the task unadvanced and report the blocker, exit codes, evidence state, and
+  required user decision.
+
+## Completion Report
+
+Report completed task IDs, the current queue pointer, parent manifest, focused
+commands and exit codes, generated evidence paths, SHA-256/governance results,
+remaining uncommitted task files, and any blocker. Do not include full command
+logs or the previous conversation transcript.