@xfey/tutti 0.1.0

package/prompts/prompt-flow-map.md

@@ -0,0 +1,478 @@
+# Prompt Flow Map
+
+本文记录 Tutti 协作主流程中各模型环节的 prompt、输入、输出、下游和 skill 接入状态。
+
+它用于后续逐项 prompt 改造讨论，不替代系统语义、API contract 或执行状态定义。正式流程语义仍以 `docs/system/`、`docs/api/` 与 `docs/modules/` 为准。
+
+## 当前背景
+
+模型调用当前分成三类：
+
+- OpenAI SDK structured output：用于轻量结构化整理和判断。调用统一经过 Responses API strict JSON schema，schema 由 TypeScript 代码绑定，prompt 只能影响内容倾向，不能新增输出字段。
+- Codex app-server read-only：用于 `@tutti` 协作聊天问答、缺失 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。运行在隔离 run 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；已收敛为聊天到任务化之间的轻量观察者，可接收 ready Project Brief 作为背景锚点，并放宽 `open_questions` 为少量非阻塞建议 / 开放方向。
+- `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；Scratchpad / Worklist 紧凑视图仍作为直接权威输入，Project Docs / Worklist detail / References 仅在必要时按需读取；任务化 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 输入 + Project Docs / Worklist skills + user skills；存在 user skills 时通过 `skills/list.perCwdExtraUserRoots` 预热 `<TUTTI_HOME>/skills`；Reference Files 不再通过 built-in skill 暴露，若任务或项目文档指向 `docs/reference/` 中资料，Codex 可直接读取相关 repo 文件。
+- `follow_up_run`：已对齐为 workspace-write + 精简 task contract 输入 + continuation block + Project Docs / Worklist skills + user skills；存在 user skills 时同样预热 `<TUTTI_HOME>/skills` extra root；Reference Files 不再通过 built-in skill 暴露，若任务、项目文档或 clarification answer 指向 `docs/reference/` 中资料，Codex 可直接读取相关 repo 文件。
+- `pipeline_self_correction`：已对齐为 workspace-write + 精简 task contract 输入 + 精简 correction block；使用 `runs/task-retry.md` 和 `workspace_write_run` selection，在同一 active Run 记录终态前处理 no candidate diff、checks 失败、checks 修改候选或 deterministic promotion reconcile 失败等可自纠 feedback。
+- `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`、`completed_no_repo_changes.summary`、`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`。
+
+后续逐项讨论时，默认从尚未在本节标为已完成的环节继续推进，避免重复分析已经收口的 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`：列出并读取 Tutti 项目上下文文件：四个 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` | `@tutti` 只读问答 | `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
+-> 群聊讨论
+-> 可选 @tutti 只读问答
+-> 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 非阻塞尽力刷新
+-> Worklist terminal feedback
+-> 当前 Worklist 全部 done 后阶段性 context_sync
+-> Project Brief 尽力刷新
+-> 回写状态 / 文档 / 下一轮讨论
+```
+
+## 环节总表
+
+| 环节 | Prompt 文件 | 调用方式 | Skill selection | 输出下游 |
+| --- | --- | --- | --- | --- |
+| `@tutti` 只读问答 | `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 |
+
+## 环节详情
+
+### `@tutti` 只读问答
+
+定义：主群聊或当前 writable clarification round 中用户明确 mention `@tutti` 时触发的只读问答助手，不进入 Procedure / Run。
+
+功能：快速回答项目相关问题；必要时只读查看更多聊天、Scratchpad、Worklist、Reference 或 repo facts；不能创建任务、修改文件或声称完成执行。
+
+当前输入：
+
+- `assistant_context_json.project.display_name`：当前项目展示名。
+- `assistant_context_json.trigger`：触发本次 `@tutti` 的消息，只包含 `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
+
+定义：主群聊或已提交的 `task_compile` clarification round 出现新的 Scratchpad source 后，系统自动触发 `scratchpad_refresh`，把近期讨论整理成轻量观察者笔记和下一次任务化可用的唯一 Scratchpad 快照。
+
+功能：用简洁语言记录当前在讨论什么或准备做什么，重写当前快照，提炼稳定共识、少量值得留意的开放方向，以及短小 task-impacting changes；不创建正式任务。
+
+当前输入：
+
+- `workflow_input_json.previous`：压缩后的旧 Scratchpad，只包含 topic / background / consensus / questions / changes。
+- `workflow_input_json.project_brief`：可选 ready Project Brief，只包含四个 canonical Project Docs 派生的短 `product / tech / structure / principles` 摘要；它只是项目背景锚点，missing / stale 时不传，不替代最新聊天。
+- `workflow_input_json.recent_messages`：压缩后的最近主群聊上下文，只包含 role / optional author_display_name / text / optional ref；它向前补足到 5 条小窗口，用于理解当前话题和短指代，首轮没有 cursor 时承接初始主群聊 source。
+- `workflow_input_json.new_messages`：压缩后的 cursor 后增量来源消息，只包含 role / optional author_display_name / text / optional ref；已提交的 `task_compile` clarification round source 也进入这里。
+
+`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` 以 Tutti 身份向主群聊发温和提醒。
+
+下游：Control Plane 写入 Scratchpad projection；后续 `task_compile` 读取。
+
+当前改造结论：
+
+- `open_questions` 可以承接群聊中真实未解决的问题，也可以承接少量非阻塞建议或开放方向；表述应模糊、柔和，避免被理解为强制 clarification。
+- `task_changes` 是 Submit 前的一两句短摘要，只承接具体、可任务化的后续增量意图；明显相关时可以点出前端、后端 / API、数据、文档、测试或资产等受影响面。未决需求、可行性假设、技术未知和缺失决策应进入 `open_questions`，不进入 `task_changes`。
+- Scratchpad 是摘要，不是完整聊天记录；但它必须保留下一次任务化、实现或验收必需的用户提供细节。需要剔除的是 secret、provider 细节、raw log 和 Tutti runtime / internal path。
+- `needs_human` 只作为 Tutti 在主群聊中的 kindly reminder，用于提示会明显阻塞后续推进的关键可行性、需求、安全或技术问题；它不是正式 clarification gate。
+- Reference upload message 只证明上传事件和文件名 / path 存在；普通 Scratchpad / taskization 不因缺少 reference 正文而阻塞，也不能根据文件名猜测文件正文。Reference summary 只由独立 `reference_summary_refresh` read-only Procedure 生成。
+- source cursor、dirty / in-flight / backoff 等调度状态只保存在后端，不进入 provider prompt。
+
+### 缺失 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`：当前 Scratchpad snapshot，仅在 Scratchpad ready 时提供。
+- 可通过 `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`；刷新完成后再启动 `project_context_bootstrap`，因此 bootstrap 输入应尽量读取最新 Scratchpad，而不直接读取群聊或 Worklist。
+
+当前改造结论：
+
+- 已从旧的项目分析 / 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；不修改既有任务。
+
+当前输入：
+
+- `workflow_input_json.scratchpad`：当前 Scratchpad 的紧凑业务字段，仅包含 `topic / background_summary / current_consensus / open_questions / task_changes`。
+- `workflow_input_json.worklist.modules[]`：当前正式 Worklist 的紧凑模块视图，仅包含模块 `id / name / optional summary / archived` 与任务 `title / summary / status`；模块名和任务标题作为短指代解析的历史锚点。
+- `workflow_input_json.clarification`：可选 workflow-bound clarification continuation 上下文，包含上一轮 `request` 和已提交 answer messages；answer message 只包含 `role / optional author_display_name / text`。
+- 可通过 `read-project-docs` / `read-worklist` / `read-references` skills 按需读取当前项目上下文文件正文、既有任务 contract / latest result 或相关 reference 正文，用于理解产品目标、技术栈、结构、agent 工作规则、阶段性任务背景或用户提供的参考资料。
+- 不通过 skill 重读 Scratchpad；Worklist 紧凑视图以直接输入为准，task detail 只在需要理解既有任务细节时读取。
+
+不进入 prompt 的字段：`context_entry_json`、workflow ref、activity ref、Scratchpad `id/state/updated_*`、Worklist module/task order、时间戳、latest run result、created-from workflow ref、clarification message id / refs / created_at 等审计或调度字段。
+
+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 `scope` 是 Run 后续执行会收到的关键边界，应保留实施和验收必需的用户提供细节，而不是要求 Run 从聊天或 Scratchpad 重新推断。
+- 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.` 等占位是开放上下文，不是阻塞项，也不能当作已确认事实。
+- Reference upload message 只证明上传事件、文件名或路径存在；不证明正文内容。若 reference 正文会影响 task contract，应通过 `read-references` 读取；否则只作为事件处理。
+- 后续可考虑单独增加 reference context expansion workflow；当前不实现，只保留为可能扩展方向。
+
+### 文档同步计划 `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。
+
+当前改造结论：
+
+- 原始 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，在隔离 run workspace 中实现候选改动。
+
+功能：读取任务契约和必要 repo facts，修改 run workspace，返回结构化 task-run result。
+
+当前输入：
+
+- `run_input_json.title`：短任务标题，用于快速定位任务意图。
+- `run_input_json.goal`：正式任务目标。
+- `run_input_json.scope`：正式任务边界，同时承接关键约束、非目标、假设和可观察验收信号。
+- 不传入 `context_entry_json`、task id、task summary、workflow / activity refs、Run lineage、dispatch context 或 run workspace 绝对路径。
+- 通过 `workspace_write_run` selection 可读取 Project Docs 与 Worklist，并可加载所有 enabled user skills；存在 user skills 时，app-server `skills/list` 会先收到 `<TUTTI_HOME>/skills` extra user root。
+- Reference Files 不通过 built-in skill 暴露；若任务契约或 Project Docs 指向 `docs/reference/` 中资料，Codex 可直接读取相关 repo 文件正文。
+- 不直接读取主群聊或 Scratchpad；这些不作为 hidden scope。
+
+输出：根对象只包含 `result`；`result` 内四选一输出 `completed.summary`、`completed_no_repo_changes.summary`、`needs_human.{title,summary,request}` 或 `failed.summary`。`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` 结果从 Git changed paths 派生 docs 状态，再执行 checks、result commit 和 mechanical promotion；空 diff 的 `completed_no_repo_changes` 结果跳过 checks / commit / promotion，记录 `promotion.status = not_attempted`。
+
+provider transient retry：如果本环节的 Codex app-server workspace-write turn 在产生可用结构化输出前因 retryable provider failure 失败，Run pipeline 可清理 attempt workspace 并使用 `runs/task-run.md`、同一 `workspace_write_run` selection 和同一 frozen task contract 重跑一次。该 retry 不使用 `task-retry.md`。
+
+当前改造结论：
+
+- frozen task contract 是唯一正式执行范围；Worklist 上下文只用于理解顺序、相邻任务、prior result 和避免冲突。
+- Project Docs / Worklist / repo 内相关 reference 文件 / user skills 可辅助实现和文档判断，但不能覆盖 Tutti 的任务契约、command policy、workspace path policy、checks、promotion 或 redaction 规则。
+- task-run 不再自报 `docs` 或 `changed_paths`；Run result 的路径证据始终来自 Run pipeline 在 candidate workspace 中收集的 Git diff。
+- `blocked` 不再属于 initial task-run 输出；无法产出可用 candidate、repo/tooling 错误或普通无 coherent diff 时返回 `failed`。
+- 如果本次改动影响稳定项目事实、使用方式、公开行为、接口、setup、项目组织、维护上下文或项目工作规则，应在同一 run 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.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 或 run workspace 绝对路径。
+- 通过 `follow_up_run` selection 可读取 Project Docs 与 Worklist，并可加载所有 enabled user skills；存在 user skills 时，app-server `skills/list` 会先收到 `<TUTTI_HOME>/skills` extra user root。
+- Reference Files 不通过 built-in skill 暴露；若任务契约、Project Docs 或 clarification answer 指向 `docs/reference/` 中资料，Codex 可直接读取相关 repo 文件正文。
+- 不直接读取主群聊或 Scratchpad；这些不作为 hidden scope。
+
+输出：同初次 Task Run 的 `{ result: ... }` 互斥分支 schema。continuation 不再自报 `docs` 或 `changed_paths`。
+
+下游：同初次 Task Run。Run pipeline 收集真实 Git diff；有 repo candidate 的 `completed` 后从 Git changed paths 派生 docs 状态并执行 checks；空 diff 的 `completed_no_repo_changes` 跳过 checks / commit / promotion；`needs_human` 时 Control Plane 继续打开 task-bound clarification。
+
+provider transient retry：continuation 的 retryable app-server failure 只重跑同一个 `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 创建新任务。
+
+触发条件：首批只覆盖无候选 diff、checks 失败、checks 修改 tracked candidate files，以及 deterministic promotion reconcile 返回未 promotion 的可自纠失败。
+
+当前输入：
+
+- `run_input_json.title` / `goal` / `scope`：同一 frozen task contract。
+- `run_input_json.correction.summary`：上一 attempt 的 bounded failure summary。
+- `run_input_json.correction.reason_code`：Run pipeline 生成的 feedback 短码，来源包括 no candidate diff、checks 失败、checks 修改候选或 promotion reconcile 失败。
+- `run_input_json.correction.guidance`：Run pipeline 根据 feedback reason 生成的本次 retry 直接修正目标。
+- `run_input_json.correction.promotion_failure?`：仅 promotion / promotion-reconcile 未能 promotion 时出现，包含机器生成 reason code 和短摘要。
+- 不传入 `context_entry_json`、task id、task summary、workflow / activity refs、Run lineage、dispatch context 或 run workspace 绝对路径。
+- 通过 `workspace_write_run` selection 可读取 Project Docs 与 Worklist，并可加载所有 enabled user skills；存在 user skills 时，app-server `skills/list` 会先收到 `<TUTTI_HOME>/skills` extra user root。
+
+输出：同初次 Task Run 的 `{ result: ... }` 互斥分支 schema。retry 不自报 `docs` 或 `changed_paths`。
+
+下游：Run pipeline 清理上一 attempt workspace 后重新创建 fresh run workspace、收集真实 Git diff；有 repo candidate 时执行 checks、创建 result commit 并 promotion，空 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 仍重跑同一个 `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 写入、run workspace 或 baseline 文档生成边界。

package/prompts/runs/README.md

@@ -0,0 +1,17 @@
+# runs
+
+These templates are used by task `Run` execution.
+
+- `task-run.md` is rendered for initial task Runs.
+- `task-continuation.md` is rendered for Phase 8 continuation Runs after task-bound clarification.
+- `task-retry.md` is rendered for bounded Run pipeline self-correction retries after pipeline feedback such as no candidate diff, failed checks, checks mutating the candidate, or deterministic promotion reconcile failure. It is not a failed-task follow-up path and does not resurrect `Task.failed`.
+Templates in this directory may describe task contracts, repo evidence, check expectations, artifact declaration rules, and documentation update responsibilities. They must never include provider credentials or host-local secret material.
+
+`task-run.md` allows `needs_human` only for human requirement decisions, non-secret context, or risk confirmation. Unusable candidates, ordinary missing diffs, or repo/tooling errors that prevent implementation should be returned as `failed` so the Run does not open task-bound clarification incorrectly. If the task contract does not require repository file changes, the output can use `completed_no_repo_changes`; otherwise a completed implementation is expected to produce a candidate diff. If the candidate is complete but Codex self-validation commands are unavailable or blocked, the task-run output should still be `completed`; Tutti checks are the authoritative validation gate.
+Initial `task-run.md`, active `task-continuation.md`, and active pipeline `task-retry.md` receive only the compact task contract fields `title / goal / scope`; continuation adds the required `continuation` block, and pipeline self-correction retry adds the required `correction` block with only the previous failure summary, machine-generated reason code, correction guidance, and optional promotion failure summary. Provider-facing prompts do not receive task ids, task summaries, Run lineage, workflow anchors, changed paths, docs status, checks status, or the safety audit context entry.
+All three Run templates use a slim mutually exclusive structured output schema under `result`: exactly one of `completed.summary`, `completed_no_repo_changes.summary`, `needs_human.{title,summary,request}`, or `failed.summary`. The `summary` is a concise, human-readable result note for project members who may not inspect the code. It should describe what changed, what was found, or why the Run cannot continue; checks, docs, promotion, changed paths, and other Tutti status stay in structured fields derived by the Run pipeline. They do not ask Codex to self-report docs status or changed paths; both come from Run pipeline Git diff and derived projection.
+Initial `task-run.md`, active `task-continuation.md`, and active pipeline `task-retry.md` also instruct Codex to write or update the single active `tutti.artifact.json` manifest only when the task creates or updates a member-viewable visual artifact. The manifest must include a viewer-facing `artifact.title` and must set `artifact.network: true` when the preview loads remote browser resources. The manifest remains repo truth and is not reported through the structured output schema.
+Active task-bound follow-up still only starts continuation Runs from `Run.needs_human`. Pipeline self-correction retry happens before a terminal Run result is recorded and does not open clarification.
+Provider transient retry is separate from self-correction. If a retryable Codex app-server workspace-write failure occurs before usable structured output, Run pipeline may rerun the same prompt family once in a fresh run workspace: initial Runs stay on `task-run.md`, continuation Runs stay on `task-continuation.md`, and self-correction attempts stay on `task-retry.md`. This retry does not add `RunCorrectionContext` unless the failed attempt was already a self-correction attempt.
+Run templates are responsible for telling Codex to update related project documentation in the same candidate workspace whenever implementation changes stable project facts. Broader cleanup, fact reconciliation, and phase-level documentation maintenance belong to the independent `context_sync` Procedure.
+The Phase 8 promotion reconcile foundation currently uses deterministic workspace-ops apply and reruns checks on the reconciled merge candidate. A dedicated Codex `promotion-reconcile.md` prompt is reserved for a later fallback when deterministic apply cannot resolve the moved-mainline candidate.