From 0a22992a134d8e0dedf119737064d21428affa52 Mon Sep 17 00:00:00 2001 From: mes123456 Date: Sat, 22 Aug 2026 18:45:25 -0400 Subject: [PATCH] Document bounded continuous task handoff recovery --- docs/CONTEXT_BUDGET.md | 15 +++ docs/EXECUTION_QUEUE.md | 12 ++- docs/README.md | 2 + nextTask.md | 216 ++++++++++++++++++++++++++++++++++++++++ 4 files changed, 240 insertions(+), 5 deletions(-) create mode 100644 nextTask.md diff --git a/docs/CONTEXT_BUDGET.md b/docs/CONTEXT_BUDGET.md index dfc78a0f..736be6d4 100644 --- a/docs/CONTEXT_BUDGET.md +++ b/docs/CONTEXT_BUDGET.md @@ -39,6 +39,21 @@ node tools/web/check-context-governance.mjs 推进到新任务时，若 `docs/tasks/.md` 不存在，先运行 `generate-task-card.mjs --task `；它只从 catalog 的一条记录生成一张短卡，生成后再运行 `check-task-context`。禁止为了生成一张卡读取完整 plan。 +## 连续执行与断流恢复 + +`nextTask.md` 是连续接续的操作入口，`docs/EXECUTION_QUEUE.md` 和 parent manifest +仍是唯一任务指针。用户发送“按 nextTask.md 接续执行”时，直接执行当前任务，不先输出路线图或等待确认。 +连续执行的边界是每个请求只完成一个 task；交接完成后，下一次相同请求从新的紧凑 context package 开始， +不得把上一任务的完整 transcript、长日志或源文件继续带入上下文。当前请求在写完交接并报告 +checkpoint 后必须停止，不得在同一请求中读取或启动下一个 task。 + +若出现 `stream disconnected`、`error decoding response body` 或 remote compact 失败，先运行只读的 +`print-task-context`、`check-task-context`、`git status --short`，再根据 manifest、status、task-context 和 +artifact hashes 找到第一个缺失的交接步骤。失败请求的结果未知，不得据错误消息宣称成功；不得盲目重复 +生成、构建、保存或推进队列。恢复请求最多重试一次，再次断流就保持 `in_progress`/`blocked` 并停止。 +预算接近上限时优先写入当前任务的交接证据，而不是加载更多背景文档；恢复请求不得携带旧 transcript +或完整日志。 + ## 文档分层 - 当前执行：`EXECUTION_QUEUE.md`、当前任务卡、parent `manifest.json`、parent `status`。 diff --git a/docs/EXECUTION_QUEUE.md b/docs/EXECUTION_QUEUE.md index 7c7f47d0..87283635 100644 --- a/docs/EXECUTION_QUEUE.md +++ b/docs/EXECUTION_QUEUE.md @@ -1,18 +1,20 @@ # Web Blender 短周期执行入口 -更新时间：2026-08-20（America/New_York） +更新时间：2026-08-22（America/New_York） 本页是唯一的当前任务指针，不保存历史任务表、实现日志或长期规划。领取任务前只读取本页、当前任务上下文、parent manifest 和 parent status；完整规则见 [`CONTEXT_BUDGET.md`](CONTEXT_BUDGET.md)。 +连续接续入口见 [`nextTask.md`](../nextTask.md)：用户发送“按 nextTask.md 接续执行”时，按该流程从当前指针开始；每次只完成一个任务并在新请求中用 fresh compact context 继续。 + ## 当前指针 | 字段 | 值 | | --- | --- | | 里程碑 | M16 Main、Mesh、Modifier、Sculpt | -| 当前任务 | `M16-GAP-00175` | -| parent manifest | `tests/golden/M16-GAP-00174/manifest.json` | -| 任务卡 | [`tasks/M16-GAP-00175.md`](tasks/M16-GAP-00175.md) | -| 专项验收 | `npm --prefix web run test:generated-gap -- --task M16-GAP-00175` | +| 当前任务 | `M16-GAP-00227` | +| parent manifest | `tests/golden/M16-GAP-00226/manifest.json` | +| 任务卡 | [`tasks/M16-GAP-00227.md`](tasks/M16-GAP-00227.md) | +| 专项验收 | `npm --prefix web run test:generated-gap -- --task M16-GAP-00227` | 领取前执行： diff --git a/docs/README.md b/docs/README.md index 5f2519e0..f8f78c5a 100644 --- a/docs/README.md +++ b/docs/README.md @@ -7,6 +7,8 @@ ## 领取任务 +连续接续入口见仓库根目录的 [`nextTask.md`](../nextTask.md)；它只定义有界的恢复/交接流程，当前任务仍以本页队列和 parent manifest 为准。 + 1. [EXECUTION_QUEUE.md](EXECUTION_QUEUE.md)：唯一的短周期入口和当前指针。 2. `node tools/web/print-task-context.mjs`：只输出当前任务需要的四份输入。 3. `tasks/.md`：当前任务唯一的范围、输入和验收；缺卡时先修复生成流程，不要打开完整 plan。 diff --git a/nextTask.md b/nextTask.md new file mode 100644 index 00000000..4a95c283 --- /dev/null +++ b/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//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 --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 ` 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.