@xfey/tenso 0.1.130

package/prompts/prompt-flow-map.md

@@ -0,0 +1,504 @@
+# Prompt Flow Map
+
+本文记录 Tenso 协作主流程中各模型环节的 prompt、输入、输出、下游和 skill 接入状态。
+
+它用于后续逐项 prompt 改造讨论，不替代系统语义、API contract 或执行状态定义。正式流程语义仍以 `docs/system/`、`docs/api/` 与 `docs/modules/` 为准。
+
+## 当前背景
+
+跨流程语言前缀统一见 [communication-language.md](./communication-language.md)。Scratchpad／Task Compile／Follow-up 的实际 provider 输出增加外层 `{ communication_language, output }`，下文各自业务 JSON 形状位于 `output`；其他模型流程仅增加语言上下文提示。共享规则不改变冻结来源、skill selection、文档权限或历史正文，详见[系统规范](../../../docs/system/communication-language.md)。
+
+模型调用当前分成三类：
+
+- OpenAI SDK structured output：用于轻量结构化整理和判断。调用统一经过 Responses API strict JSON schema，schema 由 TypeScript 代码绑定，prompt 只能影响内容倾向，不能新增输出字段。
+- Codex app-server read-only：用于 `@tenso` 协作聊天问答、缺失 Project Docs baseline 的初始化计划、Scratchpad 任务化、文档同步计划和 Reference summary。可以附加 built-in skills 与 invocation-scoped agent context API token。
+- Codex app-server workspace-write：用于正式 task Run、`Run.needs_human` 后的 continuation，以及 Run pipeline 内部 bounded self-correction retry。所有 attempt 都在 `tutti/mainline` checkout 所在的持久 project workspace 中运行，可附加 built-in skills 和 user skills。provider transient retry 不新增 prompt 或 selection，只在 retryable app-server failure 后复用失败 attempt 的同一 prompt family 与同一目录现场。
+
+Provider validation 也使用 OpenAI Responses API，但它只是启动前 credential/model 可用性检查，不属于协作 prompt 改造主线。
+
+## Prompt 改造状态
+
+已完成对齐：
+
+- `chat_assistant`：已对齐为 Codex app-server read-only + 六个原子上下文 built-in skills；默认只用触发消息和最近小窗口，必要时才按需读取额外上下文。它可以只读查询 user skills，但不执行 user skill 指令。
+- `scratchpad_refresh`：保持 OpenAI SDK structured output；已收敛为纯主群聊周期的轻量观察者，输入为完整 current-cycle messages、精简 Worklist、可选 ready Project Brief 和可选 active Task Compile Context，不再递归使用 previous Scratchpad 或读取 clarification。
+- `project_brief_refresh`：使用 OpenAI SDK structured output；从四个 canonical Project Docs 的 bounded source 派生 host-local Project Brief，不使用 Codex app-server、不写目标 repo。
+- `project_context_bootstrap`：已对齐为 Codex app-server read-only + `read-project-docs` / `read-references` skills；只生成缺失 baseline context files 计划，写入仍归 `workspace-ops`。
+- `task_compile`：已对齐为 Codex app-server read-only + `read-project-docs` / `read-worklist` / `read-references` skills；Host 从 workflow-owned durable Task Compile Context 物化完整有序 `source_messages` 与五字段 Scratchpad，Worklist 使用最新紧凑视图，continuation 复用同一来源并追加完整有序 clarification rounds；任务化 readiness 内聚在该 workflow 中，不新增独立 gate。
+- `context_sync`：已对齐为 Codex app-server read-only + `read-project-docs` / `read-worklist` / `read-references` skills；provider-facing direct input 为空，让 app-server 只读探索 repo，并输出 `summary` 与 `updates[].path/content`。
+- `workspace_write_run`：已对齐为 workspace-write + 精简 task contract + receipt-derived `source_messages` / completed Task Compile `clarification_rounds` / `recent_references` + Project Docs / Worklist skills + user skills；存在 user skills 时通过 `skills/list.perCwdExtraUserRoots` 预热当前项目 `<TUTTI_HOME>/projects/<project_id>/skills`；Reference Files 不再通过 built-in skill 暴露，若任务或项目文档指向 `docs/reference/` 中资料，Codex 可直接读取相关 repo 文件。
+- `follow_up_run`：已对齐为 workspace-write + 同一 compile-time source context + continuation block + Project Docs / Worklist skills + user skills；存在 user skills 时同样预热当前项目 `<TUTTI_HOME>/projects/<project_id>/skills` extra root；Reference Files 不再通过 built-in skill 暴露，若任务、项目文档或 clarification answer 指向 `docs/reference/` 中资料，Codex 可直接读取相关 repo 文件。
+- `artifact_applicability`：候选缺少 manifest 且 deterministic evidence 无法明确判定时，使用 `artifacts/applicability.md` 做 transient read-only structured-output 判断；判断不写入 Task contract，失败时 fail closed。
+- `pipeline_self_correction`：已对齐为 workspace-write + 同一 compile-time source context + 必填 correction diagnostic；使用 `runs/task-retry.md` 和 `workspace_write_run` selection，在同一 active Run 记录终态前处理 Artifact gate、checks 前后无 candidate diff、checks 失败或 accepted-checkpoint failure 等可自纠 feedback，并在同一持久 project workspace 中保留前一 attempt 的 source 与 repo-local runtime state。
+- `follow_up_check`：保持 OpenAI SDK structured output；已收敛为只判断上游 `Run.needs_human` 的 task-bound answer，不接入 skill，不重查代码或协作上下文；provider-facing input 只保留精简 task contract、previous Run pause reason、原 clarification request 和 answers，provider raw output 使用 `{ result: ... }` 互斥分支，failed-task retry 从 active path 移除。
+- `reference_summary_refresh`：已对齐为 Codex app-server read-only + 单文件临时 `cwd`；workflow / activity refs、原始 path、blob、media type 和 file metadata 只留在 Control Plane 内部，不进入 prompt；provider raw output 使用 `{ result: ... }` 互斥分支，只输出 `summarized.summary` 或 `unavailable.reason`。
+
+本次改造记录：
+
+- 2026-06-10：`workspace_write_run`、follow-up workspace-write Run 与阶段性 `context_sync` 的 skill 接入、prompt 目标和文档同步分层已完成。
+- 2026-06-11：`follow_up_check` 命名、上下文精简和 failed-task retry 收紧已完成；follow-up workspace-write selection 已命名为 `follow_up_run`。
+- 2026-06-11：初次 `task-run` 改造已完成；prompt 输入精简，`changed_paths` 与 docs 状态改由 Run pipeline Git diff 派生，`workspace_write_run` selection 移除 `read-references`。
+- 2026-06-11：`task-continuation` 改造已完成；prompt 复用 initial task-run 的精简 task contract，只新增 `continuation` block 传入 previous Run pause reason、已解决 clarification rounds、人类回答原文和 `follow_up_check.resume` summary；`follow_up_run` selection 移除 `read-references`。
+- 2026-06-14：live prompt-flow smoke 后调整 app-server runtime 边界：raw stdout / stderr known-value hard-fail 改为显式 strict leak-check 诊断选项，默认只做 surfaced diagnostics redaction；read-only Procedure turn timeout 放宽到 10 分钟，workspace-write Run turn timeout 放宽到 15 分钟。
+- 2026-06-24：移除旧的独立文档检查与旧 LLM review；Run prompt 负责随实现同步相关文档，Run pipeline 负责 checks、bounded self-correction retry、result commit 和机械 promotion，阶段性文档维护交给独立 `context_sync` Procedure。
+- 2026-06-24：`task-retry` 从旧预留 hook 改为 Run pipeline self-correction retry 模板。retry 不经过 Control Plane failed-task follow-up，不复活 `Task.failed`，只在当前 active Run 写最终结果前接收 bounded pipeline feedback 并重新生成候选。
+- 2026-06-24：`task_compile` prompt 增加通用任务化 readiness 准则：只有能冻结没有重大隐藏假设的正式 task contract 时才写入 Worklist；高影响且无法从现有上下文可靠推断的缺失决策走既有 workflow-bound clarification，不新增 workflow / gate / schema。
+- 2026-06-15：OpenAI SDK structured-output runner 对缺失或空 `output_text` 做一次通用重试；异步 `Procedure.failed` 会写入主群聊 `system_notice`，避免测试 harness 或用户只观察空 projection 时误以为仍在等待。
+- 2026-06-25：Run pipeline 对 retryable Codex app-server workspace-write failure 增加一次 provider transient retry。该 retry 只清理旧 attempt workspace 并重跑同一 prompt family，不进入 `task-retry.md`，不附加新的 correction block，也不打开 clarification。
+- 2026-06-28：`scratchpad_refresh` provider raw output 改为 `{ result: ... }` nested branch schema，`ready` 只输出 `scratchpad_snapshot`，`needs_human` 只输出 `request_payload`，adapter 解包后保持下游 workflow union 不变。
+- 2026-06-28：`task_compile` provider-facing input 改为压缩后的 Scratchpad / Worklist / optional clarification request + answer messages，不再注入 `context_entry_json`、workflow refs、审计字段、排序字段、时间戳或完整 message projection；provider raw output 改为 `{ result: ... }` 互斥分支，分支由 `proposal` 或 `clarification_request_payload` 字段存在性表达，不再输出 `decision`。proposal task 只输出 `module_ref / title / goal / scope`，runner adapter 再映射为 Control Plane 内部 proposal。
+- 2026-06-28：`context_sync` provider-facing input 去掉 `context_entry_json`、workflow/activity refs、触发原因和诊断型字段；输出去掉 `decision`、`doc_key`、`reason`、`evidence_paths`、`checked_paths`、`skipped_paths` 和 `open_questions`，只保留 `summary` 与 `updates[].path/content`，Control Plane 通过 `updates.length` 判断是否写入。
+- 2026-06-29：`task-run` / `task-continuation` / `task-retry` provider-facing input 统一只保留 `title / goal / scope` 加必要的 `continuation` 或 `correction` block，不再注入 `context_entry_json`、task id、task summary 或 Run lineage；`task-retry` correction block 只保留 summary、reason code、guidance 和可选 promotion failure 摘要；provider raw output 改为 `{ result: ... }` 互斥分支，只输出 `completed.{summary,user_note_candidate}`、`completed_no_repo_changes.{summary,user_note_candidate}`、`needs_human.{title,summary,request}` 或 `failed.summary`。
+- 2026-06-29：`follow_up_check` provider-facing input 去掉 `context_entry_json`、task id/status、activity ref、result kind、Run lineage、message id、作者 identity 和时间戳，只保留 `title / goal / scope`、`previous_run.summary`、`previous_run.clarification_request_payload` 与 `answers[]`；provider raw output 改为 `{ result: ... }` 互斥分支，只输出 `resume.summary`、`needs_more_input.{title,summary,request}` 或 `requires_retasking.summary`。
+- 2026-06-29：`reference_summary_refresh` provider-facing input 清零；runner 复制目标 reference 文件到独立临时目录，并以该目录作为 app-server `cwd` 和唯一 readable path。prompt 不再接收 workflow/activity trace anchors、原始路径、file metadata、blob 或 media type；provider raw output 改为 `{ result: ... }` 互斥分支，只输出 `summarized.summary` 或自然语言 `unavailable.reason`。
+- 2026-07-02：新增 `project_brief_refresh`；在四个 canonical Project Docs 创建、同步、被成功 Run promotion 修改，或 provider 配置完成后需要 backfill 时尽力刷新 host-local Project Brief projection。provider-facing input 只包含四份 Project Docs 的 bounded source / status，输出 `product_summary / tech_summary / structure_summary / principles_summary`。
+- 2026-07-29：新增 `artifacts/applicability.md` transient judge；Run / reconcile candidate 在 checks 前执行 Artifact gate。`task-retry` correction block 增加必填 redacted / bounded diagnostic，`promotion_failure` 改为完整对象或显式 `null`。
+- 2026-08-01：Run pipeline 完成持久 project workspace cutover；本条取代上述历史记录中的 attempt workspace cleanup、fresh run workspace、result commit / fast-forward promotion 与 reconcile candidate 语义。initial、continuation、provider transient retry 和 self-correction 现在复用同一项目目录；candidate Artifact、checks 与正式 preview 共享目录身份，通过 gate 后创建 accepted commit + immutable activity tag。
+- 2026-08-10：Scratchpad / task compile 上下文边界完成重构。Scratchpad 只从当前主群聊周期完整重建，输入收敛为 `project_brief? / worklist / active_task_compile? / messages`；Submit 固定 durable Task Compile Context，bootstrap / compile / continuation 复用 pinned snapshot，continuation 使用完整 `clarification_rounds`，receipt / sources 从 context 生成，clarification 不再回写 Scratchpad。
+- 2026-08-12：Submit 在 Task Compile 前等待 pinned-cycle references 对当前 blob 形成 summary terminal；Task Compile 与对应 Run 接收 compact `recent_references`，initial / continuation / provider retry / self-correction 保留同一 source set。
+- 2026-08-18：Task Compile 与 descendant Run source context 完成贯通。Host 从 pinned / receipt refs 物化相同的有序 `source_messages`，从 workflow-owned closed clarification chain 恢复完整 Task Compile rounds；initial Run、task-bound continuation、provider transient retry 和 pipeline self-correction 均保留这些字段。Task Compile / Run 不新增 `read-main-chat` 或 `read-scratchpad` skill；active prompt 已按实际 direct input 与 server-side selection 审计，移除描述不存在读取能力的禁止文本。
+
+后续逐项讨论时，默认从尚未在本节标为已完成的环节继续推进，避免重复分析已经收口的 prompt。
+
+## Skill Selection
+
+Phase 9.1 起，Codex app-server turn 可以在主 prompt text 前接收 skill input item。Built-in skills 位于 `apps/server/prompts/skills/<skill_name>/SKILL.md`。
+
+当前 built-in skills：
+
+- `read-main-chat`：读取 bounded 主群聊上下文。
+- `read-project-docs`：列出并读取 Tenso 项目上下文文件：四个 canonical project docs。
+- `read-scratchpad`：读取当前 Scratchpad projection。
+- `read-worklist`：读取 Worklist 列表和 task detail。
+- `read-references`：列出 Reference Files、返回已有 summary metadata，并读取相关 text reference 正文。
+- `read-user-skills`：列出 user skills，并读取 bounded `SKILL.md` 文本。
+
+当前 server-side selection：
+
+| Selection                   | 使用环节                                                                            | Built-in skills                                                                                                  | User skills | Context API scopes                                                     |
+| --------------------------- | ----------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- | ----------- | ---------------------------------------------------------------------- |
+| `chat_assistant`            | `@tenso` 只读问答                                                                   | `read-main-chat`, `read-project-docs`, `read-scratchpad`, `read-worklist`, `read-references`, `read-user-skills` | disabled    | messages, project-docs, scratchpad, worklist, task, references, skills |
+| `project_context_bootstrap` | 缺失 baseline context files 创建计划                                                | `read-project-docs`, `read-references`                                                                           | disabled    | project-docs, references                                               |
+| `task_compile`              | Scratchpad -> Worklist 任务化                                                       | `read-project-docs`, `read-worklist`, `read-references`                                                          | disabled    | project-docs, worklist, task, references                               |
+| `context_sync`              | 文档同步计划                                                                        | `read-project-docs`, `read-worklist`, `read-references`                                                          | disabled    | project-docs, worklist, task, references                               |
+| `reference_summary_refresh` | Reference file summary 生成                                                         | none                                                                                                             | disabled    | none                                                                   |
+| `workspace_write_run`       | 初次 Task Run / pipeline self-correction retry / 同类 provider transient retry      | `read-project-docs`, `read-worklist`                                                                             | all enabled | project-docs, worklist, task                                           |
+| `follow_up_run`             | continuation after task-bound clarification / continuation provider transient retry | `read-project-docs`, `read-worklist`                                                                             | all enabled | project-docs, worklist, task                                           |
+
+注意：
+
+- selection 是 provider 内部静态选择表，不是用户可见配置。
+- 未被 selection 选中的 skill 不会暴露给该 app-server turn。
+- scope 只来自 server-side selection，不来自 skill 自报。
+- skill 只提供原子上下文读取说明；workflow 角色、输出 schema、状态解释和治理仍属于 prompt template 与 Control Plane。
+
+## Agent Context API
+
+Codex app-server 可以通过 host-local internal API 按需读取协作上下文：
+
+```txt
+/internal/agent-context/messages
+/internal/agent-context/project-docs
+/internal/agent-context/project-docs/file
+/internal/agent-context/scratchpad
+/internal/agent-context/worklist
+/internal/agent-context/tasks/:taskId
+/internal/agent-context/references
+/internal/agent-context/references/file
+```
+
+边界：
+
+- 只读，不提供写协作 truth、repo truth、machine-local secret 或 command 的 API。
+- 使用每次 invocation 生成的短期 scoped bearer token，默认 TTL 30 分钟。
+- 不进入 browser-facing OpenAPI，不作为 Relay / browser API。
+- response 必须 bounded、paginated、redacted。
+- project-docs 文件读取在文档缺失、不可读或含 `To be confirmed.` 占位时返回结构化状态提示，不把缺失文档当成 context API runtime failure。
+- token、host-local context API URL 和 skill absolute path 都属于 provider known sensitive values，用于 diagnostics redaction；raw output known-value hard-fail 只在显式 strict leak-check 诊断模式下启用，默认关闭。
+
+## 协作主流程
+
+用户可见主循环可以简化理解为：
+
+```txt
+launch / join
+-> 群聊讨论
+-> 可选 @tenso 只读问答
+-> Scratchpad 自动刷新
+-> Submit to Worklist
+-> 必要时准备项目上下文
+-> Project Brief 尽力刷新
+-> task_compile 生成 Worklist
+-> scheduler dispatch
+-> Codex 执行单个 Task
+-> checks
+-> 可自纠 pipeline feedback 时在当前 Run 内部 retry
+-> promotion
+-> 如果 canonical Project Docs 被 promotion 修改，Project Brief 非阻塞尽力刷新
+-> task result feedback
+-> 当前 Worklist 全部 done 后阶段性 context_sync
+-> Project Brief 尽力刷新
+-> 回写状态 / 文档 / 下一轮讨论
+```
+
+## 环节总表
+
+| 环节                             | Prompt 文件                               | 调用方式                                                                                     | Skill selection             | 输出下游                                                    |
+| -------------------------------- | ----------------------------------------- | -------------------------------------------------------------------------------------------- | --------------------------- | ----------------------------------------------------------- |
+| `@tenso` 只读问答                | `chat-assistant.md`                       | Codex app-server read-only                                                                   | `chat_assistant`            | 普通 `main_chat` 或 `clarification_round` `agent_text` 消息 |
+| Scratchpad 自动刷新              | `procedures/scratchpad-refresh.md`        | OpenAI SDK structured output                                                                 | 无                          | Scratchpad projection                                       |
+| 缺失 baseline context files 创建 | `procedures/project-context-bootstrap.md` | Codex app-server read-only plan + `workspace-ops` write；不可用时本地 deterministic fallback | `project_context_bootstrap` | 缺失 baseline context files / `task_compile`                |
+| Project Brief 刷新               | `procedures/project-brief-refresh.md`     | OpenAI SDK structured output                                                                 | 无                          | host-local Project Brief projection                         |
+| Scratchpad -> Worklist 任务化    | `procedures/task-compile.md`              | Codex app-server read-only                                                                   | `task_compile`              | Worklist proposal 或 clarification                          |
+| 文档同步计划 `context_sync`      | `procedures/context-sync.md`              | Codex app-server read-only                                                                   | `context_sync`              | `workspace-ops` 受控写 docs                                 |
+| Reference summary 刷新           | `procedures/reference-file-summary.md`    | Codex app-server read-only                                                                   | `reference_summary_refresh` | `workspace-ops` 受控写 summary 索引                         |
+| 初次 Task Run                    | `runs/task-run.md`                        | Codex app-server workspace-write                                                             | `workspace_write_run`       | Run pipeline                                                |
+| clarification 后继续             | `runs/task-continuation.md`               | Codex app-server workspace-write                                                             | `follow_up_run`             | Run pipeline                                                |
+| pipeline self-correction retry   | `runs/task-retry.md`                      | Codex app-server workspace-write                                                             | `workspace_write_run`       | Run pipeline                                                |
+| task-bound 回复判断              | `procedures/follow-up-check.md`           | OpenAI SDK structured output                                                                 | 无                          | continuation / next round / retasking closure               |
+| Codex app-server smoke           | `codex/no-write-smoke.md`                 | Codex app-server read-only smoke                                                             | 无                          | release / readiness gate                                    |
+
+## 环节详情
+
+### `@tenso` 只读问答
+
+定义：主群聊或当前 writable clarification round 中用户明确 mention `@tenso` 时触发的只读问答助手，不进入 Procedure / Run。
+
+功能：快速回答项目相关问题；必要时只读查看更多聊天、Scratchpad、Worklist、Reference 或 repo facts；不能创建任务、修改文件或声称完成执行。
+
+当前输入：
+
+- `assistant_context_json.project.display_name`：当前项目展示名。
+- `assistant_context_json.trigger`：触发本次 `@tenso` 的消息，只包含 `text` 和可选 `author_display_name`。
+- `assistant_context_json.mode = "main_chat"` 时，`recent_messages[]` 是最近 3 条主群聊消息，只包含 `text` 和可选 `author_display_name`；数组顺序表达最近上下文，不再传入 message id、时间戳、author ref、message kind 或 role。
+- `assistant_context_json.mode = "clarification_round"` 时，`round_request` 是当前 round 的 title / summary / request，`round_messages[]` 是 bounded round 内消息，包含 `role / kind / text / optional author_display_name`；`recent_main_chat_before_round[]` 是 round 卡片打开前的小段主群聊上下文，用于解析短指代。
+- 可通过 `read-main-chat`、`read-project-docs`、`read-scratchpad`、`read-worklist`、`read-references`、`read-user-skills` skills 按需读取更多上下文，包括 user skill 列表和 bounded `SKILL.md`。
+
+输出：`{ answer: string }`。
+
+下游：主群聊触发时写入普通 `main_chat agent_text`；clarification round 触发时写入同一 round 的普通 `clarification_round agent_text`。SSE 使用 `message.created` 与对应 query invalidation；不会被 Control Plane 解释。后续自动 `scratchpad_refresh` 可能把主群聊 agent message 作为普通聊天上下文读取；round 内 agent message 不默认作为 Scratchpad source，但提交后的 workflow-bound round 会把它作为 `task_compile` answer context。
+
+当前改造结论：
+
+- 默认快速简洁回答。
+- 不再直接注入 Scratchpad、Worklist、Project Docs / `repo_context` 大对象，也不再注入 context source 清单、safety JSON、message ids、时间戳或作者 ref。
+- 仅在必要时使用 `chat_assistant` selection 暴露的六个 built-in skills；其中 `read-user-skills` 只用于查询 user skill metadata / `SKILL.md`，不执行 user skill 指令。
+
+### 自动刷新 Scratchpad
+
+定义：主群聊出现新的 Scratchpad source 后，系统自动触发 `scratchpad_refresh`，从当前主群聊周期起点重建轻量观察者笔记和下一次任务化可用的唯一 Scratchpad 快照。clarification 不属于这条 source 时间线。
+
+功能：用简洁语言记录当前在讨论什么或准备做什么，重写当前快照，提炼稳定共识、少量值得留意的开放方向，以及短小 task-impacting changes；不创建正式任务。
+
+当前输入：
+
+- `workflow_input_json.project_brief`：可选 ready Project Brief，只包含四个 canonical Project Docs 派生的短 `product / tech / structure / principles` 摘要；它只是稳定项目背景，missing / stale 时不传。
+- `workflow_input_json.worklist.modules[]`：未归档正式 module 的 `name` 与全部 task 的 `title / optional summary / status`；不含 id、module summary、order、refs 或时间戳，只用于理解正式安排和避免重复。
+- `workflow_input_json.active_task_compile`：可选当前 active Task Compile Context 的完整五字段 Scratchpad snapshot；它表示刚刚提交但尚未进入 Worklist 的历史背景，不含 clarification、source refs/window 或状态字段。
+- `workflow_input_json.messages`：`cycle_start_cursor` 之后当前周期的完整、有序主群聊 source，只含 `role / optional author_display_name / text`。每条原始消息先做头尾保留的中间截断，再按连续同作者合并并保留显式边界；预算降级不得静默删除某条消息。
+
+只有 `messages` 可以形成新的 `task_changes`；背景优先级固定为 `messages > active_task_compile > worklist > project_brief`。previous Scratchpad、recent/new 增量窗口、clarification messages、receipt 和 Timeline 都不进入输入。
+
+`workflow_ref` 和 safety 边界仍由运行时用于追踪、审计和执行约束，但不进入 `scratchpad_refresh` prompt；该模板已经固定 workflow identity，模型只需要业务输入。
+
+Provider raw 输出：根对象只包含 `result`；`result` 内二选一输出 `ready + scratchpad_snapshot` 或 `needs_human + request_payload`，不会同时输出 `scratchpad_snapshot` 和 `request_payload`。
+
+下游输出：OpenAI adapter 解包 `result` 后交给 Control Plane；`ready` 写入 Scratchpad snapshot，`needs_human` 以 Tenso 身份向主群聊发温和提醒。
+
+下游：Control Plane 写入 Current Scratchpad projection 与完整 main-chat source refs。Submit 时先复制为 immutable Task Compile Context；后续 `task_compile` 只读取该 pinned snapshot。
+
+当前改造结论：
+
+- `open_questions` 可以承接群聊中真实未解决的问题，也可以承接少量非阻塞建议或开放方向；表述应模糊、柔和，避免被理解为强制 clarification。
+- `task_changes` 是 Submit 前的一两句短摘要，只承接具体、可任务化的后续增量意图；明显相关时可以点出前端、后端 / API、数据、文档、测试或资产等受影响面。未决需求、可行性假设、技术未知和缺失决策应进入 `open_questions`，不进入 `task_changes`。
+- Scratchpad 是摘要，不是完整聊天记录；但它必须保留下一次任务化、实现或验收必需的用户提供细节。需要剔除的是 secret、provider 细节、raw log 和 Tenso runtime / internal path。
+- `needs_human` 只作为 Tenso 在主群聊中的轻量主动介入：近期人类讨论存在会明显阻塞推进的关键遗漏、尚未收口的高影响决策冲突、明确的高影响选择停滞，或把仍缺少必要约束 / 后果确认的高影响决定视为已经收口时才可触发；总原则是保持沉默的预期代价明显高于短暂打断讨论的代价。普通建议、可选优化、泛化总结、重复开放问题、低影响可逆细节和已显式 `@tenso` 的消息不触发该分支；它不是正式 clarification gate。
+- Reference upload message 只证明上传事件和文件名 / path 存在；普通 Scratchpad / taskization 不因缺少 reference 正文而阻塞，也不能根据文件名猜测文件正文。Reference summary 只由独立 `reference_summary_refresh` read-only Procedure 生成。
+- `cycle_start / refreshed_through` cursor、source refs、dirty / in-flight / backoff 等调度状态只保存在后端，不进入 provider prompt。最小 Worklist/message envelope 仍超预算时明确失败，不推进 cursor 或 boundary。
+
+### 缺失 baseline context files 创建
+
+定义：Submit to Worklist 的 project context gate 发现目标项目缺少 baseline context files 时触发的内部 `project_context_bootstrap` Procedure。baseline context files 仅包含四个 canonical project docs：`product.md`、`tech.md`、`structure.md` 与 `architecture-principles.md`。
+
+功能：优先用 Codex app-server read-only 生成缺失 Project Docs 的完整文件内容计划；然后由 `workspace-ops` 校验固定路径、只写缺失文件并 commit；如果 app-server 计划不可用或失败，则回退到本地 deterministic 模板创建缺失文档。
+
+当前输入：
+
+- `workflow_input_json.project_name`：目标项目展示名。
+- `workflow_input_json.missing_docs`：Control Plane 已确认缺失且需要本轮生成的 baseline context file 清单；仅在非空时传入。
+- `workflow_input_json.scratchpad`：最终 `task_compile workflow_ref` 对应 Task Compile Context 的 pinned Scratchpad snapshot；不读取 boundary 后可能已变化的 Current Scratchpad。
+- 可通过 `read-project-docs` skill 检查现有 Project Docs 状态或读取已存在文档正文；缺失、不可读或含 `To be confirmed.` 占位时应按返回状态处理。
+- 可通过 `read-references` skill 按需读取相关 reference 正文。
+- 可使用 Codex app-server 的只读仓库探索能力理解实际代码结构、框架、命令和已实现行为。
+
+模型输出：`documents[]`；每项只包含 `doc_key` 和完整 `content`。固定目标路径由 Control Plane 根据 `doc_key` 后处理生成。
+
+下游：Control Plane 根据 `doc_key` 生成固定 baseline path，`workspace-ops.initializeProjectDocs` 只写缺失的固定 baseline paths；完成后自动继续 `task_compile`。本环节不再有用户手动项目分析入口，也不会写主群聊分析报告。
+
+Submit gate 在缺失 baseline context files 且当前主群聊周期存在尚未进入 Scratchpad 的消息时，会先运行一次 `scratchpad_refresh`；随后固定 Task Compile Context 并启动 `project_context_bootstrap`。bootstrap、后续 compile 和 clarification continuation 因此共享同一 pinned snapshot，而不直接读取群聊、Worklist 或并发可变的 Current Scratchpad。
+
+当前改造结论：
+
+- 已从旧的项目分析 / repo context 预组装形态收敛为 app-server read-only 生成缺失文档计划。
+- provider-facing 输入只保留项目名、非空 `missing_docs` 和可选刷新后的 Scratchpad；workflow/activity refs、安全元数据和完整 Project Docs summary 不进入 prompt。
+- 通过 `project_context_bootstrap` selection 只暴露 `read-project-docs` / `read-references`；不暴露 main chat、Worklist、user skills，也不允许模型直接写 repo。
+- 缺失、不可读或含 `To be confirmed.` 占位的 Project Docs 由 context API 返回结构化状态，模型应将其作为上下文状态而不是 runtime failure。
+
+### Project Brief 刷新
+
+定义：四个 canonical Project Docs 创建、同步、被成功 Run promotion 修改，或 provider 配置后需要 backfill 时触发的 host-local 派生摘要刷新。它不是独立 Procedure、不是 Worklist 任务，也不写目标项目仓库。
+
+功能：从 `product.md`、`tech.md`、`structure.md` 与 `architecture-principles.md` 的 bounded source / status 生成短 Project Brief，供后续轻量 planning flow 使用。后续 Scratchpad 可以读取 brief 获取项目锚点，而不需要把四份完整文档直接塞进 prompt。
+
+当前输入：
+
+- `workflow_input_json.docs[]`：四个 canonical Project Docs 的 `doc_key / path / status`，以及可选 `size_bytes / blob_oid / unreadable_reason / content / content_truncated`。
+- `content` 来自 committed mainline 的 viewer 读取结果，并按固定字节上限截断。
+- `missing`、`unreadable` 与 `content_truncated` 是上下文状态，模型只能总结可见事实，不能补写或推断缺失正文。
+
+输出：固定字段 `product_summary / tech_summary / structure_summary / principles_summary`。每个字段是一句短摘要，只承接对应 Project Doc 中可见且稳定的事实。
+
+下游：Control Plane 把输出写入 SQLite `project_brief` projection，并保存 source fingerprint 与可空 workflow / activity anchor。读取方可用当前 source fingerprint 判断 `ready` 或 `stale`；stale 时仍以 canonical Project Docs 为准。
+
+当前改造结论：
+
+- 固定使用 OpenAI SDK structured output，不使用 Codex app-server、skills、repo 写入或 workspace-write。
+- Project Docs 初始化、`project_context_bootstrap` 写入缺失 docs、`context_sync` 更新 canonical docs、Run promotion 修改 canonical docs，以及 provider 配置完成后的 backfill 都会尽力刷新；Run promotion 触发的刷新不阻塞 task 终态。provider 不可用、source 不可用、brief 已经 fresh 或刷新失败不阻断上游写入与后续任务执行。
+- prompt 不接收 workflow refs、activity refs、安全元数据、repo context、聊天、Scratchpad、Worklist、Reference Files、host path 或完整 docs 之外的额外事实。
+- `project_brief` 不是第五份 baseline context file，不替代 canonical Project Docs，不保存完整文档正文、prompt、provider raw response 或 credential。
+
+### Scratchpad -> Worklist 任务化
+
+定义：把 Scratchpad 编译为 append-only Worklist proposal。
+
+功能：生成模块和正式任务；必要时打开 workflow-bound clarification；不修改既有任务。
+
+运行时 owner：Submit flow 预分配最终 `task_compile workflow_ref`，在必要 refresh 后原子固定 durable Task Compile Context 与主群聊 source boundary。context 保存 captured activity、提交时间、Scratchpad snapshot / exact version、source window 和完整 main-chat refs，但这些审计字段不进入 prompt。成功时 proposal、receipt / sources、clarification successor 与 context consume 原子写入；当前流程失败 / cancellation 回滚 boundary 并标 dirty。旧开发调试数据库直接 reset / recreate，不增加 migration compatibility 或新版本启动恢复。
+
+当前输入：
+
+- `workflow_input_json.source_messages`：Task Compile Context 固定的完整、有序主群聊 source；每条只包含 `role / optional author_display_name / text`，保留正文与消息边界，不含 message id、cursor、timestamp 或 workflow ref。初次 compile 和所有 continuation 都由 Host 从同一组 pinned refs 物化。
+- `workflow_input_json.scratchpad`：当前 workflow-owned Task Compile Context 固定的五个业务字段：`topic / background_summary / current_consensus / open_questions / task_changes`。初次 compile 和所有 continuation 都读取同一 snapshot。
+- `workflow_input_json.worklist.modules[]`：当前正式 Worklist 的紧凑模块视图，仅包含模块 `id / name / optional summary / archived` 与任务 `title / summary / status`；模块名和任务标题作为短指代解析的历史锚点。
+- `workflow_input_json.recent_references`：可选当前 pinned Scratchpad cycle human uploads，按 source message 顺序稳定生成；每项只含 repo-relative `path`、最终 `name` 与对应 source blob 的 `available.text` 或 `unavailable.reason`，不含 blob oid、message id 或 workflow audit fields。
+- `workflow_input_json.clarification_rounds`：可选 workflow-bound continuation 上下文，按 round index 包含截至当前 sealed round 的全部 `request` 和 submitted answer messages；answer message 只包含 `role / optional author_display_name / text`。opening/card refs 被排除，later round 可修正 earlier round，但不得丢失较早轮次。
+- 可通过 `read-project-docs` / `read-worklist` / `read-references` skills 按需读取当前项目上下文文件正文、既有任务 contract / latest result 或相关 reference 正文，用于理解产品目标、技术栈、结构、agent 工作规则、阶段性任务背景或用户提供的参考资料。
+- Worklist 紧凑视图以直接输入为准，task detail 只在需要理解既有任务细节时读取；main chat 与 Scratchpad read skills 不属于该 selection，因为冻结消息和摘要已经是 direct input。
+
+不进入 prompt 的字段：`context_entry_json`、workflow ref、activity ref、Task Compile Context source window / refs / submitted time、Scratchpad `id/state/updated_*`、Worklist module/task order、时间戳、latest run result、created-from workflow ref、clarification message id / refs / created_at 等审计或调度字段。Host 只展开 pinned refs，因此 Current Scratchpad 与 boundary 后消息不会混入旧 workflow。
+
+Provider raw 输出：根对象只包含 `result`；`result` 内二选一输出 `proposal` 或 `clarification_request_payload`，不输出 `decision`。proposal 只包含新模块和新任务；新模块字段为 `temp_key`、`name`，任务使用 `module_ref: { kind: "new" | "existing", key }` 指向本次新模块或现有 Worklist module。任务字段只包含 `title / goal / scope`；`goal` 是一句话任务目标，`scope` 同时承接实施范围、关键约束 / 非目标 / 假设和可观察验收信号。
+
+下游输出：workflow runner 解包 `result`，把 `proposal` 分支推断为内部 `decision: "ready"`，把 `clarification_request_payload` 分支推断为内部 `decision: "needs_human"`；同时把 `module_ref` 映射成 Control Plane 内部 proposal 的 `module_temp_key` 或 `existing_module_key`，并把 provider `goal` 填入内部 task `summary` 与 `contract.goal`。Control Plane 下游仍消费内部 `TaskCompileWorkflowOutput` union。
+
+下游：Control Plane 应用 proposal 创建 module/task/detail；或打开 / 继续 workflow-bound clarification。
+
+当前改造结论：
+
+- `task_compile` selection 开放 `read-project-docs` / `read-worklist` / `read-references`，但 prompt 不预设读取顺序或人工拼装上下文；只说明在必要时可以读取。
+- 任务化 readiness 内聚在 `task_compile`：能冻结没有重大隐藏假设的正式 task contract 才生成 proposal；无法从现有上下文可靠推断的高影响缺失决策走现有 workflow-bound clarification，不新增 workflow / gate / schema。
+- task `goal / scope` 保持正式、简洁并决定执行边界；执行依赖的精确原文、列表或数值由同一 source context 传给 Run，不复制成长任务描述。
+- clarification 明确撤回 pinned submission 时，provider 可以返回 empty proposal 并正常结束当前 workflow；不得把 concurrent Current Scratchpad 中的新方向借给旧 chain。
+- clarification answers 保持原消息边界与完整正文，不跨 round 合并，也不只保留最后一轮；later explicit round 可以修正 earlier material。
+- Project Docs 缺失通常不会进入本环节，因为 Submit gate 会先通过 `project_context_bootstrap` 与 `workspace-ops.initializeProjectDocs` 补齐缺失 baseline paths。gate 检查的是固定路径存在性，不保证内容质量。
+- Project Docs unreadable / unavailable 应是少见状态，通常来自编码或二进制异常、path policy、repo snapshot / viewer、IO 或 scope 配置问题。模型应在 Scratchpad / Worklist 与其他允许证据足够时继续任务化；只有无法定义目标、范围、约束或验收时才请求 workflow-bound clarification。
+- Project Docs 中的 `To be confirmed.` 等占位是开放上下文，不是阻塞项，也不能当作已确认事实。
+- `recent_references` 的 summary 只提供定位和压缩，不证明全部正文事实；当相关 summary 不足以冻结 task contract 时，应通过 `read-references` 按 path 读取 source。
+- 当前不增加独立 reference context expansion workflow、Task reference dependency schema 或 proposal reference paths。
+
+### 文档同步计划 `context_sync`
+
+定义：根据目标项目当前实现现状和现有 docs 生成受控文档更新计划。
+
+功能：判断项目文档是否需要同步；只返回完整文件内容 update plan，不直接写 repo。
+
+当前输入：
+
+- 可通过 Codex app-server read-only repo inspection 主动探索项目实现现状。
+- 可通过 `read-project-docs` skill 检查 Project Docs 当前可读状态和读取已有项目上下文文件正文。
+- 可通过 `read-worklist` skill 读取 Worklist / task detail；只用于理解阶段性完成背景、相关任务范围和稳定结果线索。
+- 可通过 `read-references` skill 按需读取 reference 目录中的相关正文。
+
+输出：`summary` 和 `updates[]`；每个 update 只包含 repo-relative `path` 和完整 `content`。空 `updates` 表示无需同步。冲突或证据不足不触发 `needs_human`，而是保留相关文档不变，并在 `summary` 中写简短诊断。
+
+下游：Control Plane 解释输出；`workspace-ops` 校验 path policy、写 docs 并创建 commit。
+
+当前改造结论：
+
+- 已去掉 `snapshot`、`docs`、`repo_context`、`sync_reason`、`focus`、Scratchpad、聊天和完整 Worklist 大对象输入。
+- 已去掉 `context_entry_json`、workflow / activity refs、触发原因和 safety metadata provider-facing input；这些只用于运行时追踪、审计、调度和 adapter 边界。
+- 模型可按需读取 Worklist 理解阶段性完成背景，但只能把稳定结果沉淀到可维护文档里。
+- 已去掉 `needs_human` / `request_payload` 输出分支，以及 `decision`、`doc_key`、`reason`、`evidence_paths`、`checked_paths`、`skipped_paths` 和 `open_questions` 输出字段；本环节固定完整执行。
+- prompt 只说明通用文档同步目标、目标项目文档落点、canonical docs 职责、保留现有标题和章节设计，并要求输出完整目标文件内容。
+- Worklist / task result 不是长期文档的任务完成流水来源。
+
+### Reference summary 刷新
+
+定义：为单个已上传 Reference File 生成或重试简短 summary。
+
+功能：读取一个 reference 文件正文或可理解内容，返回简短 orientation summary；无法访问、解码、理解或安全总结时返回 unavailable reason。不写 repo、不创建任务、不更新 Project Docs。
+
+当前输入：
+
+- Provider-facing prompt 不接收 direct input。
+- Control Plane 内部仍保留 workflow / activity refs、原始 repo-relative path、file name、category、size、blob oid 和 optional media type，用于目标选择、审计、错误处理和写回 summary index。
+- runner 在调用 app-server 前校验目标 path 仍位于 workspace root 内，将目标文件复制到独立临时目录，并以该目录作为 app-server `cwd`。
+- app-server readable paths 只包含该临时目录加 Codex minimal read scope；不附加 built-in skills、user skills、agent context API scopes、network 或 web search。
+
+Provider raw 输出：根对象只包含 `result`；`result` 内二选一输出 `summarized.summary` 或 `unavailable.reason`。`reason` 是简短自然语言，不要求固定枚举。
+
+下游输出：workflow runner 解包 `result`，把 `summarized` 分支映射为内部 `decision: "summarized"`，把 `unavailable` 分支映射为内部 `decision: "unavailable"`；同时把原始 repo-relative path 填回内部 `read_paths`，供 `workspace-ops` 写入 `docs/reference/README.md` summary record。
+
+下游：Control Plane 调用 `workspace-ops.updateReferenceSummaries` 更新 `docs/reference/README.md` 的 `## Summaries` 派生索引，并通过 SSE invalidation 刷新 Reference Files projection。
+
+当前改造结论：
+
+- 单个协调 Procedure 以并发度 `2` 运行隔离 target turns；单文件失败有界重试并形成 terminal unavailable，同批完成后一次写 index，再重新扫描 `missing / stale` 直到 drain。
+- 活动期间的新上传通过 pending/rescan 并入同一 single-flight；Submit 可加入既有 summary activity，并在 pinned references terminal 后续接 Task Compile，不启动第二个 foreground writer。
+- 原始 path、blob、media type、workflow refs 和 activity refs 不进入 prompt，避免上下文浪费和路径泄露。
+- summary 模型只看到临时目录中的一个复制文件，不会顺手探索目标项目目录或做项目理解。
+- prompt 只说明任务、只读/no-network 边界、secret-like content 处理和输出 schema 示例。
+- 输出不再包含 `decision`、`summary`、`unavailable_reason`、`read_paths` 等内部字段；这些由 runner adapter 从 `{ result: ... }` 映射回来。
+
+### 初次 Task Run
+
+定义：围绕单个正式 task，在持久 project workspace 中实现候选改动。
+
+功能：读取任务契约和必要 repo facts，在现有项目现场上继续修改并返回结构化 task-run result。该目录可能保留此前 failed Run 的未接受 source 与 ignored dependency/runtime state。
+
+当前输入：
+
+- `run_input_json.title`：短任务标题，用于快速定位任务意图。
+- `run_input_json.goal`：正式任务目标。
+- `run_input_json.scope`：正式任务边界，同时承接关键约束、非目标、假设和可观察验收信号。
+- `run_input_json.source_messages?`：通过 `Task.created_from_workflow_ref -> receipt sources` 恢复的原提交讨论，只含有序 `role / optional author_display_name / text`。
+- `run_input_json.clarification_rounds?`：该 Task 创建前已经完成的 Task Compile clarification questions / answers，按 round 顺序保留。
+- `run_input_json.recent_references?`：由 task 的 Task Compile receipt sources 恢复的本轮 human uploads；每项只含 path、最终 name 与 available/unavailable summary，必要时 Run 仍按 path 核对原文件。
+- 不传入 `context_entry_json`、task id、task summary、workflow / activity refs、Run lineage、dispatch context 或 project workspace 绝对路径。
+- 通过 `workspace_write_run` selection 可读取 Project Docs 与 Worklist，并可加载所有 enabled user skills；存在 user skills 时，app-server `skills/list` 会先收到当前项目 `<TUTTI_HOME>/projects/<project_id>/skills` extra user root。
+- Reference Files 不通过 built-in skill 暴露；若任务契约或 Project Docs 指向 `docs/reference/` 中资料，Codex 可直接读取相关 repo 文件正文。
+- `goal / scope` 决定本次执行边界；`source_messages` 与 compile `clarification_rounds` 只提供该边界引用的精确材料，不自动扩展任务目标。
+
+输出：根对象只包含 `result`；`result` 内四选一输出 `completed.{summary,user_note_candidate}`、`completed_no_repo_changes.{summary,user_note_candidate}`、`needs_human.{title,summary,request}` 或 `failed.summary`。`user_note_candidate` 是可选最终反馈候选，字段必填但可为 `null`；生成给用户直接查看的文件应写入共享 `docs/reference/` 根目录或有意义的语义子目录，同时避开 Host-owned `README.md` 和通常由浏览器上传使用的 `files/`、`images/` 分区。`completed_no_repo_changes` 只用于任务契约不要求 repository file changes 的情况。`needs_human` payload 必须能直接作为 task-bound clarification request 使用：解释为什么 frozen contract 下无法安全继续，并提出一个具体、可回答、非 secret 的问题。
+
+下游：Run pipeline 收集真实 Git diff 作为 `changed_paths`；`needs_human` 时 Control Plane 记录 `Run.needs_human`、打开 task-bound clarification 并把 task 迁回 `pending`；有 repo candidate 的 `completed` 结果先执行 Artifact candidate gate 与 checks，再在当前 `tutti/mainline` 创建 accepted commit + immutable activity tag；空 diff 的 `completed_no_repo_changes` 结果跳过 Artifact gate、checks 与 accepted checkpoint，记录 `promotion.status = not_attempted`。
+
+provider transient retry：如果本环节的 Codex app-server workspace-write turn 在产生可用结构化输出前因 retryable provider failure 失败，Run pipeline 使用 `runs/task-run.md`、同一 `workspace_write_run` selection、同一 frozen task contract 和同一 project workspace 重跑一次。它不清理前一 attempt 现场，也不使用 `task-retry.md`。
+
+当前改造结论：
+
+- frozen task contract 是唯一正式执行范围；Worklist 上下文只用于理解顺序、相邻任务、prior result 和避免冲突。
+- Project Docs / Worklist / repo 内相关 reference 文件 / user skills 可辅助实现和文档判断，但不能覆盖 Tenso 的任务契约、command policy、workspace path policy、checks、promotion 或 redaction 规则。
+- task-run 不再自报 `docs` 或 `changed_paths`；Run result 的路径证据始终来自 Run pipeline 在 project workspace 中收集的 Git diff。
+- `blocked` 不再属于 initial task-run 输出；无法产出可用 candidate、repo/tooling 错误或普通无 coherent diff 时返回 `failed`。
+- 如果本次改动影响稳定项目事实、使用方式、公开行为、接口、setup、项目组织、维护上下文或项目工作规则，应在同一 project workspace 更新相关项目文档。
+- 文档更新应写稳定结论和当前事实；不得把 Run 过程记录、任务完成日志、临时推理、调试轨迹或过长实现叙事写进 project specs / README-style 文档。
+
+### Clarification 后继续
+
+定义：task-bound clarification 已提交且 `follow_up_check` 判断可继续时，对同一 task contract 继续执行。
+
+功能：使用 human clarification 作为同一契约下的补充上下文，继续产生候选改动。
+
+当前输入：
+
+- `run_input_json.title` / `goal` / `scope`：同初次 Task Run，是 frozen task contract 的完整 provider-facing 表达。
+- `run_input_json.source_messages?` / `clarification_rounds?`：与 initial Run 相同的 Task Compile source context。
+- `run_input_json.recent_references?`：与 initial Run 相同的 receipt-derived source set；task-bound continuation 不读取后续上传。
+- `run_input_json.continuation.previous_run`：上一 Run 的 needs-human summary 与原 clarification request payload，说明为什么暂停。
+- `run_input_json.continuation.clarification.resolved_rounds[]`：截至当前 round 的已提交 task-bound clarification rounds；每轮包含 request payload 和人类回答消息原文。
+- `run_input_json.continuation.follow_up_check`：`resume` 判断的简短 summary，用于说明为什么本次可继续，但不能替代人类回答原文。
+- 不传入 `context_entry_json`、task id、task summary、workflow / activity refs、Run lineage、dispatch context 或 project workspace 绝对路径。
+- 通过 `follow_up_run` selection 可读取 Project Docs 与 Worklist，并可加载所有 enabled user skills；存在 user skills 时，app-server `skills/list` 会先收到当前项目 `<TUTTI_HOME>/projects/<project_id>/skills` extra user root。
+- Reference Files 不通过 built-in skill 暴露；若任务契约、Project Docs 或 clarification answer 指向 `docs/reference/` 中资料，Codex 可直接读取相关 repo 文件正文。
+- compile-time source context 继续只作为 frozen contract 引用的材料；task-bound `continuation` 负责当前 Run 暂停后的补充。
+
+输出：同初次 Task Run 的 `{ result: ... }` 互斥分支 schema。continuation 不再自报 `docs` 或 `changed_paths`。
+
+下游：同初次 Task Run。Run pipeline 收集真实 Git diff；有 repo candidate 的 `completed` 重新经过 Artifact gate、checks 与 accepted checkpoint；空 diff 的 `completed_no_repo_changes` 跳过这些 gate；`needs_human` 时 Control Plane 继续打开 task-bound clarification。
+
+provider transient retry：continuation 的 retryable app-server failure 只在同一 project workspace 重跑同一个 `runs/task-continuation.md` 和 `follow_up_run` selection，不清理现场、不转换为 pipeline self-correction retry，也不改变 frozen task contract。
+
+当前改造结论：
+
+- 复用初次 Task Run 的 task contract、Project Docs / Worklist skills、user skills、输出 schema 和下游 pipeline。
+- 仅新增必要的 `continuation` block，用来承接 previous Run pause reason、已提交 clarification rounds、人类回答原文和 follow-up check summary。
+- Human clarification 只能澄清或确认 frozen contract 内的执行，不得扩展为新任务；如果回答改变 goal / scope，应该由上游 `follow_up_check` 走 `requires_retasking`，而不是进入 continuation。
+- `follow_up_check.summary` 只帮助定位 resume 判断，不能替代 human answer messages。
+- Reference Files 仍作为 repo 文件可读，不再通过 `read-references` skill 或 references context API scope 暴露给 continuation Run。
+
+### Pipeline self-correction retry
+
+定义：Run pipeline 在同一 active Run 写最终结果前，对可自纠 pipeline feedback 做的一次 bounded retry。
+
+当前状态：active pipeline-internal path。它不等于 task-bound follow-up retry；`Run.failed` / `Task.failed` 当前仍不通过 follow-up retry 复活。如果最终失败后仍需要继续，应由用户在主群聊补充上下文或调整方向，随后重新走 Scratchpad -> Worklist 创建新任务。
+
+触发条件：当前覆盖checks前后无候选diff、可自纠Artifact candidate failure、checks失败，以及accepted-checkpoint failure。
+
+当前输入：
+
+- `run_input_json.title` / `goal` / `scope`：同一 frozen task contract。
+- `run_input_json.source_messages?` / `clarification_rounds?`：与原 attempt 相同的 Task Compile source context；pipeline self-correction 与其 provider transient retry 均保留。
+- `run_input_json.recent_references?`：与原 attempt 相同的 receipt-derived source set；pipeline self-correction 与其 provider transient retry 均保留。
+- `run_input_json.correction.summary`：上一 attempt 的 bounded failure summary。
+- `run_input_json.correction.reason_code`：Run pipeline 生成的 feedback 短码，来源包括 Artifact gate、checks 前后无 candidate diff、checks 失败或 accepted-checkpoint failure。
+- `run_input_json.correction.guidance`：Run pipeline 根据 feedback reason 生成的本次 retry 直接修正目标。
+- `run_input_json.correction.diagnostic`：必填的 redacted / bounded 原始失败文本，包含 `source / text / truncated`，用于让模型看到 parser、package、preview process、probe 或 pipeline state 的直接诊断。
+- `run_input_json.correction.promotion_failure`：当前可自纠 feedback 都发生在 accepted checkpoint 前，因此显式为 `null`；对象分支仅作为 bounded schema 兼容位，不表示当前存在 promotion reconcile 路径。
+- 不传入 `context_entry_json`、task id、task summary、workflow / activity refs、Run lineage、dispatch context 或 project workspace 绝对路径。
+- 通过 `workspace_write_run` selection 可读取 Project Docs 与 Worklist，并可加载所有 enabled user skills；存在 user skills 时，app-server `skills/list` 会先收到当前项目 `<TUTTI_HOME>/projects/<project_id>/skills` extra user root。
+
+输出：同初次 Task Run 的 `{ result: ... }` 互斥分支 schema。retry 不自报 `docs` 或 `changed_paths`。
+
+下游：Run pipeline 保留上一 attempt 的 source 与 ignored runtime state，在同一 project workspace 继续执行 retry 并重新收集真实 Git diff；有 repo candidate 时重新执行 Artifact gate、checks 和 accepted checkpoint，空 diff 的 `completed_no_repo_changes` 可记录为无 repo 改动完成。若 retry 仍产生可自纠 feedback 且已到上限，Run pipeline 记录最终失败；若 retry 返回 `needs_human`，才进入正常 task-bound clarification path。
+
+provider transient retry：如果 self-correction attempt 自身遇到 retryable app-server failure，Run pipeline 仍在同一 project workspace 重跑同一个 `runs/task-retry.md` 和 correction block，不清理现场，也不创建第二个 correction context。
+
+### Task-bound 回复判断
+
+定义：判断用户对 task-bound clarification 的回复是否足以继续同一 task contract。
+
+功能：决定 `resume`、继续 `needs_more_input`，或认为 `requires_retasking`。
+
+当前输入：
+
+- `workflow_input_json.title` / `goal` / `scope`：展平后的 frozen task contract。
+- `workflow_input_json.previous_run.summary`：latest `Run.needs_human` 暂停原因。
+- `workflow_input_json.previous_run.clarification_request_payload`：上一 Run 发出的原 task-bound clarification request，包含 `title`、`summary`、`request`。
+- `workflow_input_json.answers[]`：本轮提交的人类回答正文，按消息顺序排列。
+
+Provider raw 输出：根对象只包含 `result`；`result` 内三选一输出 `resume.summary`、`needs_more_input.{title,summary,request}` 或 `requires_retasking.summary`。runner adapter 解包后交给 Control Plane 内部 outcome。
+
+下游：Control Plane 物化 continuation、下一轮 task-bound clarification，或关闭当前 task 执行链并将 task 标记为 failed。
+
+当前改造结论：
+
+- 不接入 skill，不调用 Codex app-server，不读取代码、Project Docs、Scratchpad、Worklist 或 Reference Files。
+- 本环节被触发时，上游必须已经提供充分上下文；如果 latest Run result 不是 `needs_human`，Control Plane 不调用模型，直接关闭该 follow-up path。
+- workflow refs、task id/status、activity ref、result kind、Run lineage、message id、作者 identity 和时间戳只用于运行时追踪、审计、恢复或后续 continuation，不进入 provider prompt。
+- `requires_retasking` 不 patch 当前 task，也不创建隐式新 task；用户需要回到主群聊讨论，再通过 Scratchpad -> Worklist 形成新的正式任务。
+
+### Codex App-server Smoke
+
+定义：显式 live smoke，用于验证仓库锁定的 Codex app-server 能以 read-only 模式运行。
+
+功能：验证 API-key auth、account/model list、read-only thread/turn、no-write git status、无 approval request、secret redaction。
+
+当前输入：临时 repo、README sentinel、provider config。
+
+输出：smoke pass/failure diagnostic。
+
+下游：release / readiness gate，不属于用户协作主流程。
+
+当前实现：`apps/server/src/providers/openai/app-server/smoke.ts` 通过 prompt renderer 加载 `codex.no_write_smoke`，向模板注入 README sentinel，并绑定 `{ sentinel: string }` 输出 schema。
+
+## 单项优化前检查
+
+每次优化某个 prompt 前，先确认：
+
+- 原 prompt 的定义、功能、输入和输出。
+- 调用方式是 OpenAI SDK structured output、Codex app-server read-only，还是 Codex app-server workspace-write。
+- 是否可以接入 skill；如果可以，selection 是否只暴露该环节需要的 skills。
+- 输出是否必须匹配固定 schema；如果是，prompt 不能要求 schema 之外的字段。
+- 下游由哪个环节承接，以及下游如何解释 `ready`、`needs_human`、`blocked`、`failed`、`allow`、`deny` 等 decision。
+- 是否存在 secret、路径、reference 文件正文、repo 写入、project workspace 或 baseline 文档生成边界。

package/prompts/runs/README.md

@@ -0,0 +1,16 @@
+# runs
+
+Formal Task execution uses one durable Task-scoped Codex Thread and four templates:
+
+- `task-execute.md` supplies the Task goal, scope, pinned source material, workspace rules, documentation rules, Artifact contract, and safety boundary. It runs with workspace write access and no structured output schema.
+- `task-finalize.md` is a short read-only instruction that asks Codex to describe the work already completed using `task-result-contract.md` and the current turn output schema.
+- `task-recovery.md` combines the concrete bounded failure evidence with the complete result contract. Output-only failures run read-only; candidate, Artifact, or checks failures may run with workspace write access.
+- `task-result-contract.md` is the single human-readable definition of the four mutually exclusive Task result branches and must stay aligned with `TASK_RUN_OUTPUT_SCHEMA`.
+
+Initial Execute receives compact `title / goal / scope` plus pinned `source_messages`, completed Task Compile `clarification_rounds`, and `recent_references` when present. Continuation Execute reuses the same Thread and adds only the sealed clarification outcome and resume summary. Finalize does not repeat Task context or implementation instructions.
+
+Recovery retains the previous valid Task result or bounded raw final output together with the actual parser, Artifact, candidate, or checks diagnostic. Failure evidence never replaces the complete result contract. Attempt numbers, command ids, member identity, Activity ids, session paths, and Thread lifecycle details stay outside model context.
+
+Only a schema-valid Finalize or Recovery `needs_human` result can open task-bound clarification. Execute handoff text never opens clarification by itself.
+
+Task session state is machine-local and outside the repository. Prompt templates must never include provider credentials, Host-local session paths, raw secrets, or browser capability tokens. Checks, changed paths, documentation status, and accepted checkpoint state remain Host-derived facts rather than model claims.