feat(waypoint): project-navigator 工单细节与实际不符时按实际修正, 不再受阻

plugins/waypoint/CHANGELOG.md

@@ -6,6 +6,11 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 
 ## [Unreleased]
 
+### Changed
+
+- `project-navigator`: a work order now has two layers. The goal, the decisions needed, what is out of scope, and the scope are hard constraints; every other detail (data formats, paths, specific instances, implementation routes) is a working assumption. When an assumption does not match reality, the executor follows reality and records the correction in the new "事实修正" (fact corrections) table of the receipt instead of ending as blocked. The reviewer checks each correction for evidence and for overstepping under the new "修正核对" (correction check) item, and the review report lists them. Before, a mismatched detail was a specification problem, so exploratory work such as reverse engineering sent the same order back and forth.
+- `project-navigator`: the order section "前提假设" is renamed "工作假设" (working assumptions) and the receipt section "前提核对" is renamed "假设核对"; the blocked type "前提不符" becomes "目标不可达" (goal unreachable). Orders and receipts already written keep working.
+
 ## [1.4.0] - 2026-11-12
 
 ### Added

plugins/waypoint/agents/navigator-executor.md

@@ -8,7 +8,8 @@ description: project-navigator 的执行子代理, 只由编排会话按 exec-br
 ## 立场
 
 - 委派提示词中的规则与交回格式是硬性要求; 细节以执行手册 (`project-navigator ref executor`) 与工单为准.
-- 只做工单 "工作范围" 中要做的事. 范围之外的改动, 规格歧义, 需要用户提供的账号或操作, 都写进回执, 以受阻结束, 不自行变通.
+- 只做工单 "工作范围" 中要做的事. 范围之外的改动, 任务目标达不成, 需要用户决定的事, 都写进回执, 以受阻结束, 不自行变通.
+- 工单中的细节 (数据格式, 路径, 具体实例, 实现途径) 与实际不符时, 取得证据后以实际为准继续做, 在回执 "事实修正" 中逐条记录, 不算受阻. 任务目标与工作范围不能借修正改动.
 - 不提交, 不推送, 不运行改变编排状态的插件命令. 守卫拒绝的写入按拒绝理由调整, 不换写法重试.
 
 ## 交回

plugins/waypoint/docs/project-navigator-maintaining.en.md

@@ -64,6 +64,7 @@ Each entry states the decision, the reason, and what happens if it is changed.
 
 - **A work order needs two user decisions: publish it in "工单审阅" (order review), and accept and commit it in "验收报告" (review report).** The review card lists only the "审阅要点" (review points: goal, decisions needed, out of scope, sizing reason) and the order file path, prefilled by `reply approve` from the order file. Approval is still bound to the digest of the order file (the hook records the digest when the review reply ends and the choice when the user answers), so a shorter display does not weaken the binding. 0.x quoted five sections of the order verbatim; users could not read it in a few seconds, and most details were beyond their judgment anyway. If changed: the review becomes a formality, or users read every order in full.
 - **A checker subagent checks each work order once before the review.** The orchestrator writes orders from the records it already has; when a concrete fact in one (a file path, an id in the data, the release form or license of an external resource) does not hold, the executor finds out halfway through. In the same project all 5 blocked rounds of implementation orders were of this kind, and the orchestrator had read almost no project files before writing those orders. `precheck-brief` generates the prompt; `waypoint:navigator-checker` checks read-only and returns the items that do not hold or cannot be checked; the orchestrator fixes the order and runs `order precheck`. Without that mark, `reply approve` and `order set issued` refuse a drafting order. The mark records only that the check ran once and is not bound to the order content: changes made from the findings, or after a block, need no second check, otherwise every edit costs another subagent run. The findings are not stored in a file of their own; they end up in the corrected order. If changed: mistakes in an order surface during execution again, one round trip per mistake.
+- **A work order has two layers, hard constraints and working assumptions, and the executor may correct the second.** The hard constraints are the goal, the decisions needed, and what is out of scope under "审阅要点" (review points), plus "工作范围" (scope). Every other detail is a working assumption: the order's "工作假设" (working assumptions) section, and the data formats, paths, specific instances, and implementation routes written in the guidelines and criteria. When an assumption does not match reality, the executor gets evidence, follows reality, and records one row per correction in the receipt's "事实修正" (fact corrections) table; this is not blocked. The "修正核对" (correction check) item of the review prompt checks each row for evidence and for overstepping: a valid correction means the criteria are judged against the corrected fact, an invalid one fails them; the review report lists every correction. Up to 1.4.0 an order was treated as a contract and a mismatched detail was a specification problem: for reverse engineering and integration with external systems, details are known only after doing the work, and one order went back and forth repeatedly. The precheck only catches mistakes that can be looked up. There is no separate order kind; this applies to all orders, because ordinary projects meet mismatched details too and another kind is another judgement to make. The line against pending criteria: if another detail that matches the facts satisfies the criterion, it is a correction; if the facts make it impossible, it is pending. If changed: every detail found in exploratory work costs another review and issue, or the executor builds something that contradicts the facts in order to match the order.
 - **When a few criteria cannot be met, the executor finishes the rest and lists them as pending.** The receipt's "偏差记录" (deviations) has a "待定判据" (pending criteria) item, and the status is still completed. The reviewer confirms the stated reason and marks those criteria unverified with evidence starting with "待定:" (pending); they go through the existing option set 3 of "验收报告", where the user accepts as is or issues a follow-up order. No new status or option set. In the same project, 3 blocked receipts said the rest of the work was already done and only one criterion was stuck. If the user's decision would change how the rest is done, the order is still blocked. If changed: the wording of one criterion costs the whole order another review and issue.
 - **Test authorization is gone.** The executor does not run tests with external effects and lists them under "外部影响" (external effects) in the receipt's test record; the reviewer runs the code checks and the receipt's other test commands, not the external ones, and judges those from the receipt's output. MCP evidence tools are no longer registered; the reviewer makes read-only queries at the places named in the receipt's evidence record, with the constraint stated in the prompt and the subagent definition. If changed: every order with an external test costs one more user choice.
 - **Unverified criteria can be accepted explicitly by the user.** The third option group of "验收报告" (only unverified, nothing failed) lets the user accept as is and commit, via `order set accepted --accept-unverified`; the unverified criteria are recorded as risks. 0.x always failed the order, so criteria that depend on external evidence were rejected over and over. Failed criteria still cannot be accepted. If changed: orders cannot converge when external conditions are missing.
@@ -297,17 +298,18 @@ In a temporary repository with `claude --plugin-dir ./plugins/waypoint`, confirm
 ### Work order round trip
 
 1. After writing an order the orchestrator first sends the checker subagent (the Agent call carries `model: "sonnet"`), and the checker is refused when it tries to write a file; put a nonexistent file into a criterion on purpose, the findings point it out, and the orchestrator fixes the order and runs `order precheck`; `reply approve` without the precheck is refused.
-2. The executor meets one criterion it cannot satisfy: it finishes the rest, the receipt lists the criterion as pending, and the review report uses option set 3 and describes that criterion.
-3. On an analysis order the executor needs a user action: no receipt, the handback is "执行状态: 等待操作"; the orchestrator replies "等待操作" (no option block), the same subagent continues after the user replies "操作完成", and `status` shows the order as issued throughout.
-4. After `model set executor sonnet --kind fix`, the next action of a fix order says `model 参数写 "sonnet"` while an implementation order still says not to pass it; after a resume (SendMessage) the subagent still uses its dispatch model.
-5. "工单审阅" (order review) shows only the review points and the order file path, matching the order file; after B the order is changed and reviewed again; after A it is issued, an executor is dispatched in the background, and the reply is "工单执行" (order running); changing the order file after approval makes the issue fail.
-6. While the executor works in the background, the user can keep talking to the orchestrator; when it finishes, the orchestrator runs `status` on its own and starts the review.
-7. In the default permission mode, the executor's write prompts appear in the orchestrator session; after switching to Accept edits they stop.
-8. The executor is blocked (for example it needs an account): the reply is "受阻处理" (blocked handling); after the user acts, no new review is needed and the original subagent continues through SendMessage.
-9. "工单执行" has no option block; replying "停止执行" (stop) during execution: the subagent stops, the order goes back to drafting, and it is reviewed again after changes.
-10. The reviewer returns verdicts and evidence and is denied when it tries to write files; it does not run tests the receipt lists as external effects.
-11. After a passing review, A commits and B commits and pushes; with unverified criteria the third group is used, and A accepts the order and records risks; with failures a follow-up order is issued, and for an implementation order the orchestrator first judges whether it was too large.
-12. The executor's writes to records other than its order's receipt and `artifacts/` are denied; the orchestrator's business file writes are denied.
+2. Write one wrong detail into the order's "工作假设" on purpose (for example a function name that does not exist): the executor is not blocked, finishes according to the facts, and the receipt's "事实修正" has one row; "修正核对" in the review report describes the correction. Then make a correction cross "明确不做" (out of scope): the review fails the related criterion.
+3. The executor meets one criterion it cannot satisfy: it finishes the rest, the receipt lists the criterion as pending, and the review report uses option set 3 and describes that criterion.
+4. On an analysis order the executor needs a user action: no receipt, the handback is "执行状态: 等待操作"; the orchestrator replies "等待操作" (no option block), the same subagent continues after the user replies "操作完成", and `status` shows the order as issued throughout.
+5. After `model set executor sonnet --kind fix`, the next action of a fix order says `model 参数写 "sonnet"` while an implementation order still says not to pass it; after a resume (SendMessage) the subagent still uses its dispatch model.
+6. "工单审阅" (order review) shows only the review points and the order file path, matching the order file; after B the order is changed and reviewed again; after A it is issued, an executor is dispatched in the background, and the reply is "工单执行" (order running); changing the order file after approval makes the issue fail.
+7. While the executor works in the background, the user can keep talking to the orchestrator; when it finishes, the orchestrator runs `status` on its own and starts the review.
+8. In the default permission mode, the executor's write prompts appear in the orchestrator session; after switching to Accept edits they stop.
+9. The executor is blocked (for example it needs an account): the reply is "受阻处理" (blocked handling); after the user acts, no new review is needed and the original subagent continues through SendMessage.
+10. "工单执行" has no option block; replying "停止执行" (stop) during execution: the subagent stops, the order goes back to drafting, and it is reviewed again after changes.
+11. The reviewer returns verdicts and evidence and is denied when it tries to write files; it does not run tests the receipt lists as external effects.
+12. After a passing review, A commits and B commits and pushes; with unverified criteria the third group is used, and A accepts the order and records risks; with failures a follow-up order is issued, and for an implementation order the orchestrator first judges whether it was too large.
+13. The executor's writes to records other than its order's receipt and `artifacts/` are denied; the orchestrator's business file writes are denied.
 
 ### Changes, milestone reviews, and anomalies
 
@@ -326,6 +328,7 @@ In a temporary repository with `claude --plugin-dir ./plugins/waypoint`, confirm
 - Recognizing the orchestrator depends on the marker in the transcript, whose format is internal to Claude Code; when the transcript cannot be read, rule 4 does not apply (the write is allowed).
 - The executor subagent belongs to the session that started it; closing that session interrupts its work, and a new session continues according to whether the receipt was written.
 - A background subagent's write prompt does not name the subagent; users can infer it only from the "工单执行" (order running) reply and the task list.
+- Fact corrections are kept in check by the reviewer and the user: no script can tell when corrections add up to a changed goal; that shows only in the "修正核对" item of the review report. The line between hard constraints and working assumptions is written in the rules; when the executor misjudges it, it either blocks once more than needed or oversteps and fails the review.
 - The precheck records only that it ran, not whether the orchestrator changed the order accordingly; the checker examines only the facts written in the order and cannot find unstated assumptions.
 - The subagent model is only a parameter written in the "next action"; no hook checks that the orchestrator passes it.
 - While waiting for a user action the order status does not change, and the original executor is lost with the session; a newly dispatched one can continue only from the documents under `artifacts/`.