@wnlen/agent-execution-template 0.8.18 → 0.8.19

package/README.md

@@ -161,7 +161,8 @@ The user can still give a natural-language goal, for example:
 Build the settings page with profile editing, notification toggles, and export entrypoint
 ```
 
-Before execution, the AI decomposes L1 tasks:
+Before execution, the AI decomposes L1 tasks. Each L1 must be an independently
+acceptable vertical slice, not a mechanical step checklist:
 
 ```text
 - [ ] L1-1 Profile editing Green
@@ -171,12 +172,19 @@ Before execution, the AI decomposes L1 tasks:
 
 Because there are two or more L1 tasks, the protocol automatically uses bounded
 continuous execution. Before each L1, the AI plans naturally derived L2/L3 work.
-After completing an L1, it checks and strikes the item, then writes status back
-to `execution_policy.task_tree` in `ai/project/task.md`.
+After completing an L1, it checks and strikes the item. `task_tree` is written
+back only at L1 start/done, Red/blocked, scope changes, or final wrap-up, so tiny
+steps do not churn files.
 
 Only Red risk stops for confirmation. Green continues automatically, and Yellow
-continues after local low-risk correction. Every checkpoint must include
-evidence: changed files, commands run, and verification results.
+only permits local low-risk correction inside the current L1/L2; it must not
+change public interfaces, data models, permissions, security, architecture
+direction, or acceptance. By default, users see L1, risk conclusions, evidence,
+Red confirmations, and final results; internal protocol details are not shown.
+
+If the AI just created or rewrote `ai/project/task.md` in the current run, it
+must stop for confirmation. Execution is allowed only when an existing task is
+explicitly `ready_to_execute`.
 
 ## Installed Layout
 

package/README.zh-CN.md

@@ -171,7 +171,7 @@ npx -y @wnlen/agent-execution-template strategy
 实现设置页，包括资料编辑、通知开关和导出入口
 ```
 
-AI 会在执行前先拆 L1 任务：
+AI 会在执行前先拆 L1 任务。L1 必须是可独立验收的垂直切片，不是机械步骤清单：
 
 ```text
 - [ ] L1-1 资料编辑 Green
@@ -180,11 +180,15 @@ AI 会在执行前先拆 L1 任务：
 ```
 
 因为 L1 有两个以上，协议会自动使用边界内连续执行。执行每个 L1 前，AI 再规划
-自然衍生的 L2/L3；完成一个 L1 后，在清单中打勾并划掉，同时把状态写回
-`ai/project/task.md` 的 `execution_policy.task_tree`。
+自然衍生的 L2/L3；完成一个 L1 后，在清单中打勾并划掉。`task_tree` 只在
+L1 开始/完成、Red/blocked、范围变化或最终收尾时写回，避免为微小步骤反复改文件。
 
-只有 Red 风险会停下来让你确认。Green 自动继续，Yellow 只做局部低风险修正后继续。
-每个 Checkpoint 都必须带证据：改了哪些文件、跑了哪些命令、验证结果是什么。
+只有 Red 风险会停下来让你确认。Green 自动继续，Yellow 只允许当前 L1/L2 内的
+局部低风险修正，不能改变公共接口、数据模型、权限、安全、架构方向或验收标准。
+用户默认只看 L1、风险结论、证据、Red 确认和最终结果；内部协议细节不默认展示。
+
+如果 AI 本轮刚新建或重写了 `ai/project/task.md`，必须先停下来交接确认；
+只有已有任务明确处于 `ready_to_execute` 时，才允许进入执行。
 
 ## 安装后的结构
 

package/docs/SPEC.md

@@ -22,7 +22,7 @@ npx 安装协议 -> AI 整理项目上下文 -> 人类确认 -> AI 生成任务
 
 ```text
 Protocol: v0.8
-Package: @wnlen/agent-execution-template@0.8.18
+Package: @wnlen/agent-execution-template@0.8.19
 中文安装: npx -y @wnlen/agent-execution-template init
 英文安装: npx -y @wnlen/agent-execution-template init --lang en
 ```
@@ -392,7 +392,7 @@ npx -y @wnlen/agent-execution-template doctor
 ```text
 Agent Execution Template 检查
 
-模板版本: 0.8.18
+模板版本: 0.8.19
 模板语言: zh
 
 [通过] ai/template/LANG
@@ -664,7 +664,10 @@ ai/template/execution-policy.md
 执行前规划：
 
 - AI 根据用户目标、项目上下文和仓库事实推断目标、范围、验收、权限和验证方式；
+- 只有 `ai/project/task.md.readiness = ready_to_execute` 时才进入执行；本轮新建或重写
+  `task.md` 时必须停在确认交接；
 - 先列 L1 任务清单，并给每个 L1 标注 Green / Yellow / Red；
+- L1 必须是可独立验收的垂直切片，不是机械步骤清单；
 - L1 少于 2 个时使用 `normal`；
 - L1 为 2 个或更多时自动使用 `bounded_continuous`；
 - 任一 L1 为 Red 时停止等待人类确认；Green 和 Yellow 不阻塞启动。
@@ -675,16 +678,20 @@ ai/template/execution-policy.md
 - 默认最多 3 层，只有当 L3 仍过大、不可验证或不可回退时才动态增加 L4；
 - 每个任务节点必须有风险评级、预期改动范围、验收方式和证据要求；
 - L1 清单必须用待办列表展示，每完成一个 L1 就打勾并划掉；
-- 执行前和执行中必须把任务树写回 `ai/project/task.md.execution_policy.task_tree`；
+- `task_tree` 写回应集中在执行前、L1 开始/完成、Red、blocked、范围变化和最终收尾；
 - 默认按 `vertical_slice` 推进，每轮都要产生可检查增量；
+- Checkpoint 只在风险从 Green 变 Yellow/Red、即将扩大范围或权限、完成 L1 垂直切片、
+  验证失败后准备继续或最终收尾时输出；
 - 每个 Checkpoint 必须包含证据：已改文件、已运行命令、验证结果或无法验证原因；
 - Green 可自动继续；
-- Yellow 做局部低风险修正后继续；
+- Yellow 只允许当前 L1/L2 内的局部低风险修正，不能改变公共接口、数据模型、权限、
+  安全、架构方向或验收标准；
 - Red 必须停止等待人类确认；
+- 用户可见输出默认只展示 L1、风险结论、证据、Red 确认和最终结果，不展示内部协议细节；
 - 目标、范围、验收和权限由 AI 推断，但不能越过项目规则、显式用户限制、
   `permission.modify.denied`、安全边界或破坏性操作限制；
-- 需要扩大权限、运行未允许命令、访问网络、执行破坏性操作、改变产品方向或核心架构时，
-  当前节点必须标为 Red。
+- 需要扩大权限、运行未允许命令、访问网络、执行破坏性操作、改变产品方向、核心架构、
+  公共 API、持久化数据结构、安全边界、支付、账号或权限时，当前节点必须标为 Red。
 
 它不适用于方向未定且无法推断、验收无法定义或高风险架构取舍任务；这些应直接评为 Red。
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wnlen/agent-execution-template",
-  "version": "0.8.18",
+  "version": "0.8.19",
   "description": "Low-friction AI execution protocol template for coding agents.",
   "bin": {
     "agent-execution-template": "bin/agent-execution-template.js"

package/template/en/ai/project/task.md

@@ -11,6 +11,8 @@ execution_policy:
   max_depth: 3
   allow_depth_4_when_needed: true
   progress_unit: "vertical_slice"
+  l1_granularity: "independently_acceptable_vertical_slice"
+  write_back_policy: "l1_start_done_red_blocked_scope_change_final"
   task_tree:
     - id: "L1-1"
       title: ""
@@ -86,6 +88,9 @@ permissions, and acceptance from the human goal, project context, and repository
 facts. If inference would cross permission or safety boundaries, or acceptance
 cannot be defined, set `readiness` to `blocked` or mark the relevant task node
 `Red` and wait for human confirmation.
+If this run creates or rewrites the task contract, keep
+`readiness = draft_for_confirmation` by default and stop at the handoff. Enter
+execution only when an existing task is explicitly `ready_to_execute`.
 
 ## Goal
 
@@ -143,26 +148,36 @@ fewer than 2 L1 tasks, use `normal`; if it finds 2 or more L1 tasks, use
   before execution.
 - `readiness = blocked` means the task cannot execute and must produce a
   blocked result.
+- If this run creates or rewrites `ai/project/task.md`, stop at the confirmation
+  handoff; do not execute while the task is still a draft.
 - Before execution, write the L1 checklist to `execution_policy.task_tree`.
 - Before execution, list the L1 task checklist; mark each L1 complete with a
   checked and struck-through item.
+- Each L1 must be an independently acceptable vertical slice. Do not split a
+  single mechanical step into L1 tasks, and do not merge multiple independently
+  acceptable user-visible outcomes into one L1.
 - Before executing an L1, plan the naturally derived L2 tasks; if an L2 still
   needs decomposition, plan L3 tasks.
 - Default to at most 3 levels; add L4 dynamically only when leaving it out
   would make L3 too large or unverifiable.
 - The AI assigns Green / Yellow / Red risk to every task node.
 - Only Red stops for human confirmation; Green continues automatically, and
-  Yellow continues after local low-risk correction.
+  Yellow only permits local low-risk correction inside the current L1/L2. It
+  must not change public interfaces, data models, permissions, security,
+  architecture direction, or acceptance.
 - `progress_unit` defaults to `vertical_slice`: each work loop should produce
   a reviewable increment.
 - `checkpoint_budget` is the maximum checkpoint budget, not a required count;
   do not report just to spend the budget.
-- Emit a checkpoint only when `checkpoint_triggers` fire, risk rises, or final
-  review is about to start.
+- Emit checkpoints only when risk changes from Green to Yellow/Red, scope or
+  permission is about to expand, an L1 vertical slice is complete, verification
+  failed but execution is about to continue, or final wrap-up is about to start.
 - Every checkpoint must include evidence: changed files, commands run,
   verification results, or why verification was not possible.
-- During execution, update `task_tree` node status: `pending`, `running`,
-  `done`, or `blocked`.
+- `task_tree` write-back frequency: write the L1 checklist before execution;
+  update an L1 when it starts or completes; write back immediately on Red,
+  blocked, scope change, or final wrap-up; do not write back every tiny L3
+  operation.
 - After completion, run one final review; only re-check Yellow, Red, failed
   verification, or high-impact modules.
 - Continuous execution does not change model policy; escalate through
@@ -192,7 +207,8 @@ Stop and write `ai/project/result.json`, `ai/project/result.md`, and `ai/project
 - Required command cannot be run.
 - Risk level is high without explicit authorization.
 - A Red checkpoint appears during continuous execution.
-- The task would change product direction, core architecture, data structures,
-  security boundaries, payment, accounts, or permissions.
-- The task would delete many files, rewrite a core module, or require choosing
-  between multiple high-cost options.
+- The task would change product direction, core architecture, public API,
+  persistent data structures, security boundaries, payment, accounts, or
+  permissions.
+- The task would delete files beyond the current L1's directly related files,
+  rewrite a core module, or require choosing between multiple high-cost options.

package/template/en/ai/template/VERSION

@@ -1 +1 @@
-0.8.18
+0.8.19

package/template/en/ai/template/execution-policy.md

@@ -13,7 +13,13 @@ Pre-execution planning must:
 
 - Infer goal, scope, acceptance, permissions, and verification method from the
   human goal, project context, and repository facts.
+- Enter execution only when `ai/project/task.md` already exists and
+  `readiness = ready_to_execute`. If this run creates or rewrites the task
+  contract, stop at the confirmation handoff instead of executing from a draft.
 - List the L1 task checklist and assign Green / Yellow / Red risk to each L1.
+- Each L1 must be an independently acceptable vertical slice. Do not split a
+  single mechanical step into L1 tasks, and do not merge multiple independently
+  acceptable user-visible outcomes into one L1.
 - Use `normal` if there are fewer than 2 L1 tasks.
 - Automatically use `bounded_continuous` if there are 2 or more L1 tasks.
 - Stop for human confirmation first if any L1 is Red; Green and Yellow do not
@@ -24,6 +30,10 @@ Pre-execution planning must:
 
 Execute the task tree in L1 -> L2 -> L3 order.
 
+- L1 is a work increment that can be verified, rolled back, and explained to the
+  user after completion.
+- L2 is an implementation substep needed to finish that L1.
+- L3 is a local operation step used when an L2 is still too large.
 - Before executing an L1, plan its naturally derived L2 tasks.
 - Before executing an L2, plan L3 tasks if it still needs decomposition.
 - Default to at most 3 levels. Add L4 dynamically only when L3 would otherwise
@@ -32,8 +42,11 @@ Execute the task tree in L1 -> L2 -> L3 order.
   and evidence requirements.
 - Show the L1 checklist as task items; when an L1 is complete, check it off and
   strike it through.
-- During execution, update each `task_tree` node status: `pending`, `running`,
-  `done`, or `blocked`.
+- Task tree write-back rule: write the L1 checklist before execution; update an
+  L1 when it starts or completes; write back immediately on Red, blocked, scope
+  change, or final wrap-up. Do not write back every tiny L3 operation.
+- During execution, use `pending`, `running`, `done`, or `blocked` for node
+  status.
 
 Recommended node shape:
 
@@ -65,16 +78,19 @@ Yellow:
 - Still inside current task scope;
 - local uncertainty or local verification failure exists;
 - a low-risk local correction can continue the work;
-- no permission, scope, command, or acceptance expansion is needed.
+- the correction affects only the current L1/L2 local implementation and does
+  not change public interfaces, data models, permissions, security,
+  architecture direction, or acceptance;
+- no permission, scope, command, network, or acceptance expansion is needed.
 
 Red:
 
 - Permission expansion, unallowed command, network access, or destructive action
   is needed;
-- product direction, core architecture, data structure, security boundary,
-  payment, account, or permission would change;
-- many files must be deleted, a core module must be rewritten, or multiple
-  high-cost options require judgment;
+- product direction, core architecture, public APIs, persistent data structures,
+  security boundary, payment, account, or permission would change;
+- files beyond the current L1's directly related files must be deleted, a core
+  module must be rewritten, or multiple high-cost options require judgment;
 - acceptance cannot be defined, or task goal materially conflicts with project direction.
 
 Only Red stops for human confirmation. Green continues automatically. Yellow
@@ -82,9 +98,10 @@ continues after local low-risk correction.
 
 ## Checkpoint
 
-Emit checkpoints only when risk rises, a boundary is about to change, a vertical
-slice is complete, or final review is about to start. Do not report just to
-spend checkpoint budget.
+Emit checkpoints only when risk changes from Green to Yellow/Red, scope or
+permission is about to expand, an L1 vertical slice is complete, verification
+failed but execution is about to continue, or final review is about to start.
+Do not report just to spend checkpoint budget.
 
 Every checkpoint must include:
 
@@ -102,6 +119,17 @@ Every checkpoint must include:
 Evidence must include changed files, commands run, verification results, or why
 verification was not possible. A purely subjective Green is not valid.
 
+## User-Visible Output
+
+- Show the L1 checklist by default; do not show full L2/L3/L4 by default.
+- Show risk conclusions and necessary reasons; do not output long internal reasoning.
+- Show evidence; do not show internal protocol fields, full YAML,
+  `checkpoint_budget`, or `model_policy`.
+- Say little for Green, be brief for Yellow, and stop with clear reasons and
+  options for Red.
+- Final output must include status, completed items, verification results, and
+  result files.
+
 ## Model Policy
 
 Continuous execution does not change `model_policy`. Still escalate through

package/template/en/ai/template/prompt.md

@@ -69,12 +69,12 @@ In Task Draft Mode:
    and write it to `execution_policy.task_tree`. Use `normal` if there are
    fewer than 2 L1 tasks; automatically use `bounded_continuous` if there are 2
    or more L1 tasks.
-5. If no Red preflight item exists, set `readiness` to `ready_to_execute`; if
-   human confirmation is needed, set it to `draft_for_confirmation`; if the task
-   cannot execute, set it to `blocked`.
-6. Stop for human confirmation only when a Red preflight item appears. If the
-   human asked to execute or continue, and preflight contains only Green /
-   Yellow, proceed directly to Execution Mode.
+5. If this run creates or rewrites `ai/project/task.md`, set `readiness` to
+   `draft_for_confirmation` and stop at the handoff; do not execute while the
+   task is still a draft.
+6. Enter Execution Mode only when an existing task is explicitly
+   `ready_to_execute` and no Red preflight item exists; if it cannot execute,
+   set it to `blocked`.
 7. Do not modify source or business files in Task Draft Mode.
 
 End Task Draft Mode with:
@@ -129,12 +129,17 @@ In Execution Mode, read:
 Then follow `ai/template/execution-policy.md` for pre-execution planning: list
 the L1 checklist, mark each L1 Green / Yellow / Red, and write it to
 `execution_policy.task_tree`. Automatically choose `normal` or
-`bounded_continuous` from the L1 count. Plan L2 before executing an L1, and
-plan L3 as needed before executing an L2; default to at most 3 levels, with L4
-allowed when needed. When an L1 is complete, check it off, strike it through,
-and update the `task_tree` node status. Only Red stops for human confirmation;
-Green continues automatically, and Yellow continues after local low-risk
-correction. Write results to:
+`bounded_continuous` from the L1 count. Execute only when
+`readiness = ready_to_execute`; if this run creates or rewrites the task
+contract, stop at the confirmation handoff. Each L1 must be an independently
+acceptable vertical slice. Plan L2 before executing an L1, and plan L3 as needed
+before executing an L2; default to at most 3 levels, with L4 allowed when
+needed. When an L1 is complete, check it off and strike it through; write back
+`task_tree` when an L1 starts or completes, on Red/blocked, on scope change, or
+at final wrap-up. Only Red stops for human confirmation; Green continues
+automatically, and Yellow only permits local low-risk correction inside the
+current L1/L2. User-visible output follows the "User-Visible Output" rules in
+`ai/template/execution-policy.md`. Write results to:
 
 - `ai/project/result.json`
 - `ai/project/result.md`

package/template/en/ai/template/protocol.md

@@ -54,11 +54,15 @@ Before task execution, read `ai/template/execution-policy.md`.
 The default execution policy is `auto`: the AI first decomposes L1 tasks and
 judges Green / Yellow / Red risk, then chooses `normal` or `bounded_continuous`.
 Use `normal` when there are fewer than 2 L1 tasks; automatically use
-`bounded_continuous` when there are 2 or more L1 tasks. Only Red stops for
-human confirmation.
-
-Task tree, risk rubric, checkpoint evidence, and `task_tree` status update
-rules are defined in `ai/template/execution-policy.md`.
+`bounded_continuous` when there are 2 or more L1 tasks. Each L1 must be an
+independently acceptable vertical slice. Execution is allowed only for an
+existing task with `readiness = ready_to_execute`; if this run creates or
+rewrites the task contract, stop at the confirmation handoff. Only Red stops for
+human confirmation, and Yellow only permits local low-risk correction inside the
+current L1/L2.
+
+Task tree, risk rubric, checkpoint evidence, and `task_tree` write-back rules
+are defined in `ai/template/execution-policy.md`.
 
 ## Bootstrap Mode
 

package/template/en/ai/template/rules/core.md

@@ -125,15 +125,24 @@ explicitly say "enable continuous execution".
 
 Hard gates:
 
+- Execute only when `ai/project/task.md.readiness = ready_to_execute`; if this
+  run creates or rewrites `task.md`, stop at the confirmation handoff.
+- L1 must be an independently acceptable vertical slice, not a mechanical step
+  checklist.
 - `execution_policy.task_tree` must record the L1 checklist and execution state.
 - Every task node must have Green / Yellow / Red risk.
+- Yellow only permits local low-risk correction inside the current L1/L2. It
+  must not change public interfaces, data models, permissions, security,
+  architecture direction, or acceptance.
 - Every checkpoint must include evidence; a purely subjective Green is not valid.
 - Red must stop for human confirmation.
-- Any product direction, core architecture, data structure, security, payment,
-  account, permission, large deletion, core rewrite, or high-cost option choice
-  must stop.
+- Any product direction, core architecture, public API, persistent data
+  structure, security, payment, account, permission, large deletion, core
+  rewrite, or high-cost option choice must stop.
 - Any need to expand scope, permission, commands, network access, or acceptance
   must stop.
+- `task_tree` write-back should happen at L1 start/done, Red, blocked, scope
+  change, and final wrap-up; do not write back every tiny L3 operation.
 
 The AI infers goal, scope, acceptance, and permissions, but must not cross
 project rules, explicit human limits, `permission.modify.denied`, security

package/template/zh/ai/project/task.md

@@ -11,6 +11,8 @@ execution_policy:
   max_depth: 3
   allow_depth_4_when_needed: true
   progress_unit: "vertical_slice"
+  l1_granularity: "independently_acceptable_vertical_slice"
+  write_back_policy: "l1_start_done_red_blocked_scope_change_final"
   task_tree:
     - id: "L1-1"
       title: ""
@@ -83,6 +85,8 @@ permission:
 优先使用安全假设，少问额外问题。AI 应基于用户目标、项目上下文和仓库事实推断
 范围、风险、权限和验收；如果推断会越过权限、安全边界或验收无法定义，将
 `readiness` 标为 `blocked` 或将相关任务节点标为 `Red`，等待人类确认。
+如果本轮新建或重写了任务契约，默认保持 `draft_for_confirmation` 并停下来交接；
+只有已有任务明确处于 `ready_to_execute` 时，才进入执行。
 
 ## 目标
 
@@ -132,17 +136,23 @@ permission:
 - `readiness = ready_to_execute` 表示没有 Red 预检项，可以执行。
 - `readiness = draft_for_confirmation` 表示需要人类确认后才能执行。
 - `readiness = blocked` 表示当前任务不可执行，必须写 blocked 结果。
+- 本轮如果新建或重写 `ai/project/task.md`，必须停在确认交接；不能在任务仍是草稿时执行。
 - 执行前必须把 L1 任务清单写入 `execution_policy.task_tree`。
 - 执行前必须列出 L1 任务清单；每个 L1 用待办列表表示，完成后打勾并划掉。
+- L1 必须是可独立验收的垂直切片；不要把单个机械步骤拆成 L1，也不要把多个
+  可独立验收的用户可见结果合并成一个 L1。
 - 执行某个 L1 前，AI 先规划自然衍生出的 L2；如果 L2 仍需拆分，再规划 L3。
 - 默认最多 3 层；只有当不拆 L4 会导致 L3 过大或不可验证时，才允许动态增加 L4。
 - 每个任务节点都由 AI 自己生成 Green / Yellow / Red 风险评级。
-- 只有 Red 停下来让人类确认；Green 自动继续，Yellow 先做局部低风险修正后继续。
+- 只有 Red 停下来让人类确认；Green 自动继续，Yellow 只允许当前 L1/L2 内的局部
+  低风险修正，不能改变公共接口、数据模型、权限、安全、架构方向或验收标准。
 - `progress_unit` 默认是 `vertical_slice`：每轮推进都应该产生可检查的工作增量。
 - `checkpoint_budget` 是最多可用检查点预算，不是必须用完的次数；不要为了消耗预算而汇报。
-- 只有在触发 `checkpoint_triggers`、风险升高或准备收尾时才输出 Checkpoint。
+- 只有在风险从 Green 变 Yellow/Red、即将扩大范围或权限、完成 L1 垂直切片、
+  验证失败后准备继续、准备最终收尾时才输出 Checkpoint。
 - 每个 Checkpoint 必须包含证据：已改文件、已运行命令、验证结果或无法验证的原因。
-- 执行中必须更新 `task_tree` 节点状态：`pending`、`running`、`done` 或 `blocked`。
+- `task_tree` 写回频率：执行前写入 L1 清单；开始或完成 L1 时更新该 L1 状态；
+  出现 Red、blocked、范围变化或最终收尾时立即写回；不要为每个微小 L3 操作写回。
 - 完成后只做一次总复盘；只对 Yellow、Red、失败验证或高影响模块做二次抽检。
 - 连续执行不改变模型策略；涉及判断、架构、失败复盘或验收争议时仍按 `model_policy` 升级。
 
@@ -170,5 +180,5 @@ permission:
 - 必需命令无法运行。
 - 风险等级高但没有明确授权。
 - 连续执行中出现 Red 检查点。
-- 需要改变产品方向、核心架构、数据结构、安全边界、支付、账号或权限。
-- 需要删除大量文件、重写核心模块，或在多个高成本方案之间取舍。
+- 需要改变产品方向、核心架构、公共 API、持久化数据结构、安全边界、支付、账号或权限。
+- 需要删除超过当前 L1 直接相关的文件、重写核心模块，或在多个高成本方案之间取舍。

package/template/zh/ai/template/VERSION

@@ -1 +1 @@
-0.8.18
+0.8.19

package/template/zh/ai/template/execution-policy.md

@@ -11,7 +11,11 @@
 执行前规划必须：
 
 - 根据用户目标、项目上下文和仓库事实，推断目标、范围、验收、权限和验证方式。
+- 只有 `ai/project/task.md` 已存在且 `readiness = ready_to_execute` 时才进入执行。
+  如果本轮新建或重写任务契约，必须先停在确认交接，不能边写草稿边执行。
 - 列出 L1 任务清单，并为每个 L1 生成 Green / Yellow / Red 风险评级。
+- L1 必须是可独立验收的垂直切片；不要把单个机械步骤拆成 L1，也不要把多个
+  可独立验收的用户可见结果合并成一个 L1。
 - 如果 L1 少于 2 个，使用 `normal`。
 - 如果 L1 为 2 个或更多，自动启用 `bounded_continuous`。
 - 如果任一 L1 为 Red，先停止并让人类确认；Green 和 Yellow 不阻塞启动。
@@ -21,12 +25,17 @@
 
 任务树按 L1 -> L2 -> L3 执行。
 
+- L1 表示一个完成后可验证、可回退、可向用户解释的工作增量。
+- L2 表示完成该 L1 所需的实现子步骤。
+- L3 表示 L2 仍过大时的局部操作步骤。
 - 执行某个 L1 前，先规划它自然衍生出的 L2。
 - 执行某个 L2 前，如果仍需拆分，再规划 L3。
 - 默认最多 3 层。只有当 L3 仍过大、不可验证或不可回退时，才动态增加 L4。
 - L1/L2/L3/L4 都必须有风险评级、预期改动范围、验收方式和证据要求。
 - L1 清单必须用待办列表展示；每完成一个 L1，就打勾并划掉。
-- 执行中必须更新 `task_tree` 节点状态：`pending`、`running`、`done` 或 `blocked`。
+- 任务树写回规则：执行前写入 L1 清单；开始或完成 L1 时更新该 L1 状态；
+  出现 Red、blocked、范围变化或最终收尾时立即写回。不要为每个微小 L3 操作写回。
+- 执行中使用 `pending`、`running`、`done` 或 `blocked` 表示节点状态。
 
 推荐节点结构：
 
@@ -57,20 +66,24 @@ Yellow：
 - 仍在当前任务范围内；
 - 存在局部不确定或局部验证失败；
 - 可以用低风险修正继续；
-- 不需要扩大权限、范围、命令或验收。
+- 修正只影响当前 L1/L2 的局部实现，不改变公共接口、数据模型、权限、安全、
+  架构方向或验收标准；
+- 不需要扩大权限、范围、命令、网络或验收。
 
 Red：
 
 - 需要扩大权限、运行未允许命令、访问网络或执行破坏性操作；
-- 需要改变产品方向、核心架构、数据结构、安全边界、支付、账号或权限；
-- 需要删除大量文件、重写核心模块或在多个高成本方案之间取舍；
+- 需要改变产品方向、核心架构、公共 API、持久化数据结构、安全边界、支付、
+  账号或权限；
+- 需要删除超过当前 L1 直接相关的文件、重写核心模块或在多个高成本方案之间取舍；
 - 验收不可定义，或任务目标和项目方向发生实质冲突。
 
 只有 Red 停止等待人类确认。Green 自动继续。Yellow 做局部低风险修正后继续。
 
 ## Checkpoint
 
-Checkpoint 只在风险升高、边界即将变化、完成垂直切片或准备收尾时输出。
+Checkpoint 只在以下情况输出：风险从 Green 变 Yellow/Red、即将扩大范围或权限、
+完成一个 L1 垂直切片、验证失败后准备继续、准备最终收尾。
 不要为了消耗预算而汇报。
 
 每个 Checkpoint 必须包含：
@@ -89,6 +102,14 @@ Checkpoint 只在风险升高、边界即将变化、完成垂直切片或准备
 证据必须包含已改文件、已运行命令、验证结果，或无法验证的原因。
 不接受只有主观判断的 Green。
 
+## 用户可见输出
+
+- 默认展示 L1 清单；不要默认展示完整 L2/L3/L4。
+- 展示风险结论和必要原因；不要输出长篇内部推理。
+- 展示证据；不要展示内部协议字段、完整 YAML、`checkpoint_budget` 或 `model_policy`。
+- Green 少说，Yellow 简说，Red 停下并说明原因和选项。
+- 最终必须给状态、完成项、验证结果和结果文件。
+
 ## 模型策略
 
 连续执行不改变 `model_policy`。遇到规划、架构、失败复盘或验收争议，

package/template/zh/ai/template/prompt.md

@@ -55,10 +55,10 @@
 4. 执行前列出 L1 任务清单并标注 Green / Yellow / Red，同时写入
    `execution_policy.task_tree`。L1 少于 2 个时使用 `normal`；L1 为 2 个或更多时
    自动使用 `bounded_continuous`。
-5. 如果没有 Red 预检项，将 `readiness` 设为 `ready_to_execute`；如果需要人类确认，
-   设为 `draft_for_confirmation`；如果不可执行，设为 `blocked`。
-6. 只有出现 Red 预检项时才停止等待人类确认。若用户要求的是执行或继续，且预检
-   只有 Green / Yellow，可以直接进入执行模式。
+5. 本轮如果新建或重写了 `ai/project/task.md`，将 `readiness` 设为
+   `draft_for_confirmation` 并停止交接；不要在任务仍是草稿时直接执行。
+6. 只有已有任务明确处于 `ready_to_execute`，且没有 Red 预检项时，才能进入执行模式；
+   如果不可执行，设为 `blocked`。
 7. 不要在任务草稿模式中修改源码或业务文件。
 
 任务草稿模式必须以下面结构结束：
@@ -110,10 +110,13 @@
 
 然后按 `ai/template/execution-policy.md` 做执行前规划：列出 L1 清单，给每个 L1
 标注 Green / Yellow / Red，并写入 `execution_policy.task_tree`。根据 L1 数量自动选择
-`normal` 或 `bounded_continuous`。执行 L1 前规划 L2，执行 L2 前按需规划 L3；
-默认最多 3 层，必要时允许 L4。每完成一个 L1，在清单中打勾并划掉，并更新
-`task_tree` 节点状态。只有 Red 停止等待人类确认；Green 自动继续，Yellow 做局部
-低风险修正后继续。最后把结果写入：
+`normal` 或 `bounded_continuous`。只有 `readiness = ready_to_execute` 才能执行；
+如果本轮新建或重写任务契约，先停在确认交接。L1 必须是可独立验收的垂直切片。
+执行 L1 前规划 L2，执行 L2 前按需规划 L3；默认最多 3 层，必要时允许 L4。
+每完成一个 L1，在清单中打勾并划掉；开始或完成 L1、出现 Red/blocked、范围变化
+或最终收尾时写回 `task_tree`。只有 Red 停止等待人类确认；Green 自动继续，Yellow
+只做当前 L1/L2 内的局部低风险修正。用户可见输出遵守
+`ai/template/execution-policy.md` 的“用户可见输出”规则。最后把结果写入：
 
 - `ai/project/result.json`
 - `ai/project/result.md`

package/template/zh/ai/template/protocol.md

@@ -47,9 +47,12 @@ ai/project/task.md             = 当前执行契约
 
 执行策略默认是 `auto`：AI 先拆 L1 任务并判断 Green / Yellow / Red，再决定使用
 `normal` 或 `bounded_continuous`。L1 少于 2 个使用 `normal`；L1 为 2 个或更多
-自动启用 `bounded_continuous`。只有 Red 停止等待人类确认。
+自动启用 `bounded_continuous`。L1 必须是可独立验收的垂直切片。只有
+`readiness = ready_to_execute` 的既有任务才能执行；本轮新建或重写任务契约时先
+停在确认交接。只有 Red 停止等待人类确认，Yellow 只允许当前 L1/L2 内的局部
+低风险修正。
 
-任务树、风险分级、Checkpoint 证据和 `task_tree` 状态更新规则由
+任务树、风险分级、Checkpoint 证据和 `task_tree` 写回规则由
 `ai/template/execution-policy.md` 定义。
 
 ## 引导模式

package/template/zh/ai/template/rules/core.md

@@ -108,13 +108,20 @@
 
 硬门禁：
 
+- 只有 `ai/project/task.md.readiness = ready_to_execute` 才能执行；本轮新建或重写
+  `task.md` 时必须停在确认交接。
+- L1 必须是可独立验收的垂直切片，不是机械步骤清单。
 - `execution_policy.task_tree` 必须记录 L1 清单和执行状态。
 - 每个任务节点必须有 Green / Yellow / Red 风险评级。
+- Yellow 只允许当前 L1/L2 内的局部低风险修正，不能改变公共接口、数据模型、
+  权限、安全、架构方向或验收标准。
 - 每个 Checkpoint 必须包含证据；不接受只有主观判断的 Green。
 - Red 必须停止等待人类确认。
-- 任何方向、核心架构、数据结构、安全、支付、账号、权限、大量删除、
+- 任何方向、核心架构、公共 API、持久化数据结构、安全、支付、账号、权限、大量删除、
   核心重写或高成本方案取舍，都必须停止。
 - 需要扩大范围、权限、命令、网络或验收时，必须停止。
+- `task_tree` 写回应集中在 L1 开始/完成、Red、blocked、范围变化和最终收尾，
+  不要为每个微小 L3 操作写回。
 
 目标、范围、验收和权限由 AI 推断，但不能越过项目规则、显式用户限制、
 `permission.modify.denied`、安全边界或破坏性操作限制。

package/test/selftest.js

@@ -84,13 +84,24 @@ function testInitUpdateDoctor() {
   assert(read(cwd, "ai/template/prompt.md").includes("默认也只处理 `ai/project/inbox/*.md`"), "execution prompt should narrow inbox reconciliation");
   assert(read(cwd, "ai/template/protocol.md").includes("`bounded_continuous`"), "protocol should include bounded continuous execution");
   assert(read(cwd, "ai/template/execution-policy.md").includes("垂直切片"), "protocol should require vertical-slice progress for continuous execution");
+  assert(read(cwd, "ai/template/execution-policy.md").includes("可独立验收的垂直切片"), "execution policy should define L1 granularity");
+  assert(read(cwd, "ai/template/execution-policy.md").includes("不能边写草稿边执行"), "execution policy should block execution from draft tasks");
+  assert(read(cwd, "ai/template/execution-policy.md").includes("不要为每个微小 L3 操作写回"), "execution policy should limit task tree write-back churn");
+  assert(read(cwd, "ai/template/execution-policy.md").includes("公共接口、数据模型、权限、安全"), "execution policy should constrain Yellow corrections");
+  assert(read(cwd, "ai/template/execution-policy.md").includes("用户可见输出"), "execution policy should define user-visible output rules");
+  assert(read(cwd, "ai/template/execution-policy.md").includes("不要默认展示完整 L2/L3/L4"), "execution policy should avoid exposing full subtask trees by default");
+  assert(read(cwd, "ai/template/execution-policy.md").includes("不要展示内部协议字段"), "execution policy should hide internal protocol details by default");
   assert(read(cwd, "ai/template/execution-policy.md").includes("L1 为 2 个或更多，自动启用"), "protocol should auto-enable continuous execution from L1 count");
   assert(read(cwd, "ai/template/execution-policy.md").includes("每个 Checkpoint 必须包含"), "protocol should require evidence-backed checkpoints");
   assert(read(cwd, "ai/template/rules/core.md").includes("边界内连续执行门"), "core rules should include bounded continuous execution gate");
+  assert(read(cwd, "ai/template/rules/core.md").includes("readiness = ready_to_execute"), "core rules should require ready task before execution");
+  assert(read(cwd, "ai/template/rules/core.md").includes("不是机械步骤清单"), "core rules should reject mechanical L1 task lists");
   assert(read(cwd, "ai/template/rules/core.md").includes("需要扩大范围、权限、命令、网络或验收时"), "core rules should stop continuous execution before boundary expansion");
   assert(read(cwd, "ai/project/task.md").includes("execution_policy:"), "task template should include execution policy");
   assert(read(cwd, "ai/project/task.md").includes("readiness:"), "task template should include readiness state");
   assert(read(cwd, "ai/project/task.md").includes("activation_rule: \"auto_enable_when_l1_count_gte_2\""), "task template should define automatic activation rule");
+  assert(read(cwd, "ai/project/task.md").includes("l1_granularity: \"independently_acceptable_vertical_slice\""), "task template should define L1 granularity");
+  assert(read(cwd, "ai/project/task.md").includes("write_back_policy: \"l1_start_done_red_blocked_scope_change_final\""), "task template should define task tree write-back policy");
   assert(read(cwd, "ai/project/task.md").includes("risk_gate:"), "task template should define risk gate");
   assert(read(cwd, "ai/project/task.md").includes("status: \"pending | running | done | blocked\""), "task template should define task tree node status");
   assert(read(cwd, "ai/project/task.md").includes("progress_unit: \"vertical_slice\""), "task template should define continuous progress unit");
@@ -99,6 +110,8 @@ function testInitUpdateDoctor() {
   assert(read(cwd, "ai/template/prompt.md").includes("不要重新 bootstrap"), "execution prompt should reconcile inbox material when project context already exists");
   assert(read(cwd, "ai/template/prompt.md").includes("整合 ai/project/inbox/ 里的新资料"), "execution prompt should route natural reconcile entry");
   assert(read(cwd, "ai/template/prompt.md").includes("继续推进这个项目"), "execution prompt should route natural continue entry");
+  assert(read(cwd, "ai/template/prompt.md").includes("不要在任务仍是草稿时直接执行"), "execution prompt should stop after drafting a task");
+  assert(read(cwd, "ai/template/prompt.md").includes("用户可见输出"), "execution prompt should reference user-visible output rules");
   assert(read(cwd, "ai/template/prompt.md").includes("strategy_update"), "execution prompt should route strategy updates");
   assert(read(cwd, "ai/template/reconcile.md").includes("上下文整合"), "init should install reconcile prompt");
   assert(read(cwd, "ai/template/reconcile.md").includes("整合计划"), "reconcile prompt should require a plan first");
@@ -168,13 +181,24 @@ function testEnglishInitUpdateDoctor() {
   assert(read(cwd, "ai/template/prompt.md").includes("default to only `ai/project/inbox/*.md`"), "English execution prompt should narrow inbox reconciliation");
   assert(read(cwd, "ai/template/protocol.md").includes("`bounded_continuous`"), "English protocol should include bounded continuous execution");
   assert(read(cwd, "ai/template/execution-policy.md").includes("vertical"), "English protocol should require vertical-slice progress for continuous execution");
+  assert(read(cwd, "ai/template/execution-policy.md").includes("independently acceptable vertical slice"), "English execution policy should define L1 granularity");
+  assert(read(cwd, "ai/template/execution-policy.md").includes("executing from a draft"), "English execution policy should block execution from draft tasks");
+  assert(read(cwd, "ai/template/execution-policy.md").includes("every tiny L3 operation"), "English execution policy should limit task tree write-back churn");
+  assert(read(cwd, "ai/template/execution-policy.md").includes("public interfaces, data models, permissions"), "English execution policy should constrain Yellow corrections");
+  assert(read(cwd, "ai/template/execution-policy.md").includes("User-Visible Output"), "English execution policy should define user-visible output rules");
+  assert(read(cwd, "ai/template/execution-policy.md").includes("do not show full L2/L3/L4 by default"), "English execution policy should avoid exposing full subtask trees by default");
+  assert(read(cwd, "ai/template/execution-policy.md").includes("do not show internal protocol fields"), "English execution policy should hide internal protocol details by default");
   assert(read(cwd, "ai/template/execution-policy.md").includes("Automatically use `bounded_continuous`"), "English protocol should auto-enable continuous execution from L1 count");
   assert(read(cwd, "ai/template/execution-policy.md").includes("Every checkpoint must include"), "English protocol should require evidence-backed checkpoints");
   assert(read(cwd, "ai/template/rules/core.md").includes("Bounded Continuous Execution Gate"), "English core rules should include bounded continuous execution gate");
+  assert(read(cwd, "ai/template/rules/core.md").includes("readiness = ready_to_execute"), "English core rules should require ready task before execution");
+  assert(read(cwd, "ai/template/rules/core.md").includes("not a mechanical step"), "English core rules should reject mechanical L1 task lists");
   assert(read(cwd, "ai/template/rules/core.md").includes("expand scope, permission, commands, network access, or acceptance"), "English core rules should stop continuous execution before boundary expansion");
   assert(read(cwd, "ai/project/task.md").includes("execution_policy:"), "English task template should include execution policy");
   assert(read(cwd, "ai/project/task.md").includes("readiness:"), "English task template should include readiness state");
   assert(read(cwd, "ai/project/task.md").includes("activation_rule: \"auto_enable_when_l1_count_gte_2\""), "English task template should define automatic activation rule");
+  assert(read(cwd, "ai/project/task.md").includes("l1_granularity: \"independently_acceptable_vertical_slice\""), "English task template should define L1 granularity");
+  assert(read(cwd, "ai/project/task.md").includes("write_back_policy: \"l1_start_done_red_blocked_scope_change_final\""), "English task template should define task tree write-back policy");
   assert(read(cwd, "ai/project/task.md").includes("risk_gate:"), "English task template should define risk gate");
   assert(read(cwd, "ai/project/task.md").includes("status: \"pending | running | done | blocked\""), "English task template should define task tree node status");
   assert(read(cwd, "ai/project/task.md").includes("progress_unit: \"vertical_slice\""), "English task template should define continuous progress unit");
@@ -182,6 +206,8 @@ function testEnglishInitUpdateDoctor() {
   assert(read(cwd, "ai/template/prompt.md").includes("instead of bootstrapping again"), "English execution prompt should reconcile inbox material when project context already exists");
   assert(read(cwd, "ai/template/prompt.md").includes("Reconcile the new material in ai/project/inbox/"), "English execution prompt should route natural reconcile entry");
   assert(read(cwd, "ai/template/prompt.md").includes("Continue this project"), "English execution prompt should route natural continue entry");
+  assert(read(cwd, "ai/template/prompt.md").includes("do not execute while the\n   task is still a draft"), "English execution prompt should stop after drafting a task");
+  assert(read(cwd, "ai/template/prompt.md").includes("User-Visible Output"), "English execution prompt should reference user-visible output rules");
   assert(read(cwd, "ai/template/prompt.md").includes("strategy_update"), "English execution prompt should route strategy updates");
   assert(exists(cwd, "ai/project/refs/final-shape.md"), "English init should create project North Star");
   assert(exists(cwd, "ai/project/refs/module-map.md"), "English init should create module map");