@xfey/tutti 0.1.41 → 0.1.43

package/node_modules/@tutti/shared/dist/utils/redaction/index.js

@@ -11,6 +11,8 @@ export const REDACTION_FIXTURES = [
     "sk-proj-example-secret",
     "Authorization: Bearer example-token",
     "Cookie: tutti_session=example-session",
+    "Cookie: tutti_preview_session=example-preview-session",
+    "https://opaque.preview.tutti.now/__tutti_preview_bootstrap#token=example-preview-token",
     "http://127.0.0.1:4370/join/example-join-token",
     "http://127.0.0.1:4370/api/v1/join/example-join-token/accept",
     "http://127.0.0.1:4371/setup?token=example-runtime-token",
@@ -42,6 +44,18 @@ const TEXT_REDACTION_RULES = [
         pattern: /\btutti_session\s*=\s*[^;\s,]+/giu,
         replacement: `tutti_session=${REDACTION_LABELS.cookie}`,
     },
+    {
+        pattern: /\btutti_preview_session\s*=\s*[^;\s,]+/giu,
+        replacement: `tutti_preview_session=${REDACTION_LABELS.cookie}`,
+    },
+    {
+        pattern: /(https?:\/\/[^\s"'`]+\/__tutti_preview_bootstrap)#token=[A-Za-z0-9._~+/%=-]+/giu,
+        replacement: `$1#token=${REDACTION_LABELS.bearerToken}`,
+    },
+    {
+        pattern: /(^|[\s"'`])\/__tutti_preview_bootstrap#token=[A-Za-z0-9._~+/%=-]+/giu,
+        replacement: `$1/__tutti_preview_bootstrap#token=${REDACTION_LABELS.bearerToken}`,
+    },
     {
         pattern: /https?:\/\/[^\s"'`]+\/api\/v1\/join\/[A-Za-z0-9._~+/-]+\/accept/giu,
         replacement: `https://[REDACTED:host]/api/v1/join/${REDACTION_LABELS.joinToken}/accept`,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xfey/tutti",
-  "version": "0.1.41",
+  "version": "0.1.43",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",

package/prompts/README.md

@@ -14,6 +14,7 @@ Prompt / skill 改造后的 live 实验计划与记录见 [prompt-flow-experimen
 ## 结构
 
 - `procedures/`：`scratchpad_refresh`、`project_brief_refresh`、`task_compile`、`project_context_bootstrap`、`context_sync`、`reference_summary_refresh`、`follow_up_check` 等 Procedure / workflow prompt。
+- `artifacts/`：候选实现完成后的 transient Artifact applicability 判断；只接收 bounded task / diff / repo evidence，不写回 Task contract 或 repo。
 - `runs/`：正式 task `Run`、task-bound continuation 与 pipeline self-correction retry 等 Run pipeline prompt；provider transient retry 不新增 prompt，而是复用失败 attempt 的同一 prompt family；Codex 参与式 promotion reconcile prompt 后续按 fallback 需求加入。
 - `codex/`：Codex app-server smoke 等 adapter / spike prompt。
 - `skills/`：Tutti packaged built-in Codex skills；由 server-side app-server skill selection 选择，不在 Web Skills 页面展示，也不保存 user skills。

package/prompts/artifacts/README.md

@@ -0,0 +1,7 @@
+# artifacts
+
+This directory contains model-facing prompts used by the internal Artifact candidate gate.
+
+- `applicability.md` makes one read-only, non-persistent decision after a candidate diff exists and only when deterministic evidence cannot decide whether a browser-viewable Artifact is applicable.
+
+The prompt receives only the frozen task `title / goal / scope`, bounded changed paths, bounded Git diff facts, and limited repository evidence. It must not receive chat history, Scratchpad, task / activity ids, host paths, run workspace paths, credentials, provider output, or secrets. Applicability output is transient pipeline state; it is not written back to the Task contract or repository.

package/prompts/artifacts/applicability.md

@@ -0,0 +1,41 @@
+<!--
+template_key: artifacts.applicability
+owner: run-pipeline/artifact-gate
+model_path: openai.sdk.structured_output
+-->
+
+# Role
+
+Decide whether the completed repository candidate should provide a browser-viewable Artifact manifest.
+
+# Input
+
+{{applicability_input_json}}
+
+# Decision rules
+
+- Return `artifact_required` when the candidate creates or changes a page, site, Web App, SPA, dashboard, visual prototype, browser bundle, frontend entry, same-origin Web API used by an existing browser app, or other member-viewable browser result.
+- Return `not_applicable` only when the evidence clearly describes a library without a browser entry, a CLI, a migration or data script, an API-only service without a Web client, docs-only maintenance, or another task with no reasonable browser presentation surface.
+- Existing browser application evidence is relevant even if the changed path is a server entry, API handler, build configuration, or other behavior required by that application.
+- Ambiguity must resolve to `artifact_required`. Do not use a missing field, `unknown`, or a confidence score to avoid the decision.
+- Do not propose implementation changes. Do not infer hidden requirements from chat, Scratchpad, task ids, or machine-local context; none of those are inputs.
+
+# Output
+
+Return exactly one strict JSON object with both fields filled:
+
+```json
+{
+  "decision": "artifact_required",
+  "reason": "The candidate introduces a browser-viewable application entry."
+}
+```
+
+or:
+
+```json
+{
+  "decision": "not_applicable",
+  "reason": "The candidate only changes a reusable library and exposes no browser entry."
+}
+```

package/prompts/prompt-flow-map.md

@@ -26,7 +26,8 @@ Provider validation 也使用 OpenAI Responses API，但它只是启动前 crede
 - `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>/projects/<project_id>/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>/projects/<project_id>/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。
+- `artifact_applicability`：候选缺少 manifest 且 deterministic evidence 无法明确判定时，使用 `artifacts/applicability.md` 做 transient read-only structured-output 判断；判断不写入 Task contract，失败时 fail closed。
+- `pipeline_self_correction`：已对齐为 workspace-write + 精简 task contract 输入 + 必填 correction diagnostic；使用 `runs/task-retry.md` 和 `workspace_write_run` selection，在同一 active Run 记录终态前处理 Artifact gate、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`。
 
@@ -49,6 +50,7 @@ Provider validation 也使用 OpenAI Responses API，但它只是启动前 crede
 - 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`。
 
 后续逐项讨论时，默认从尚未在本节标为已完成的环节继续推进，避免重复分析已经收口的 prompt。
 
@@ -67,15 +69,15 @@ Phase 9.1 起，Codex app-server turn 可以在主 prompt text 前接收 skill i
 
 当前 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                   | 使用环节                                                                            | 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                                           |
 
 注意：
 
@@ -135,20 +137,20 @@ launch / join
 
 ## 环节总表
 
-| 环节 | 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 |
+| 环节                             | 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                                    |
 
 ## 环节详情
 
@@ -416,9 +418,10 @@ provider transient retry：continuation 的 retryable app-server failure 只重
 
 - `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.reason_code`：Run pipeline 生成的 feedback 短码，来源包括 Artifact gate、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 和短摘要。
+- `run_input_json.correction.diagnostic`：必填的 redacted / bounded 原始失败文本，包含 `source / text / truncated`，用于让模型看到 parser、package、preview process、probe 或 candidate diff 的直接诊断。
+- `run_input_json.correction.promotion_failure`：promotion / promotion-reconcile 失败时为完整的 reason code 与短摘要；未到达 promotion 时显式为 `null`。
 - 不传入 `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>/projects/<project_id>/skills` extra user root。
 

package/prompts/runs/README.md

@@ -5,13 +5,13 @@ 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.
+  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.
+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 the previous failure summary, machine-generated reason code, correction guidance, a required redacted / bounded diagnostic, and `promotion_failure` as either a complete object or explicit `null`. 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,user_note_candidate}`, `completed_no_repo_changes.{summary,user_note_candidate}`, `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. Completed branches also require `user_note_candidate`, which is either a short user-facing final-card sentence or `null`; it must not repeat `summary` or include file paths. 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.
 Run templates describe `docs/reference/` as a user-visible file exchange area. Human uploads remain under `docs/reference/files/` and `docs/reference/images/`; `docs/reference/tutti/**` is for Tutti-generated files intended for direct member review in References, not temporary output, internal notes, logs, or canonical project documentation. Generated user-visible files must be written under `docs/reference/tutti/`, with `docs/reference/tutti/<meaningful-folder>/...` used when the folder name should be shown as a References UI group. Generated files under `docs/reference/tutti/` are discovered from promoted changed paths, rendered by References automatically, and may be listed in completed task result cards.
-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 schema requires top-level `version: 1`; it 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.
+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. Each template includes the complete strict static and server JSON shapes: every behavior field is required, `network` is always an explicit boolean, and server `script / ready_path / port` fields are forbidden. A server package instead declares the fixed `artifact:preview` npm script in its own `package.json` and listens on the injected `HOST / PORT`. 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.

package/prompts/runs/task-continuation.md

@@ -80,10 +80,42 @@ If the task creates or updates a user-viewable web page, static page, single-pag
 
 - Do not modify `tutti.artifact.json` for tasks unrelated to a visual artifact.
 - If an existing artifact remains the only current preview entry, update that manifest instead of creating another declaration.
-- Every artifact manifest must include top-level `version: 1` and a short viewer-facing `artifact.title`.
-- For a static artifact, declare `artifact.kind: "static"`, a repo-relative `root`, and an HTML `entry` within that root.
-- For a server artifact, declare `artifact.kind: "server"` and provide an `artifact:preview` npm script that listens on `127.0.0.1` using the injected `HOST` and `PORT` environment variables.
-- If the preview loads external images, fonts, API data, or other remote browser resources, set `artifact.network: true`; otherwise omit it or set it to `false`.
+- The manifest is a strict contract. Fill every field shown for the selected kind, do not add other fields, and do not rely on defaults.
+- A static artifact must use this exact shape:
+
+```json
+{
+  "version": 1,
+  "artifact": {
+    "title": "Landing Page",
+    "kind": "static",
+    "root": "dist",
+    "entry": "index.html",
+    "network": false
+  }
+}
+```
+
+- A server artifact must use this exact shape:
+
+```json
+{
+  "version": 1,
+  "artifact": {
+    "title": "App Preview",
+    "kind": "server",
+    "cwd": ".",
+    "entry": "/",
+    "network": false
+  }
+}
+```
+
+- For a static artifact, `root` and `entry` are repo-relative and `entry` must be an HTML file inside `root`.
+- For a server artifact, `cwd` is the repo-relative npm package directory and `entry` is the HTTP path Tutti opens.
+- A server artifact must provide an `artifact:preview` npm script in `cwd/package.json`; it must listen on `127.0.0.1` using the injected `HOST` and `PORT` environment variables.
+- Set `network` explicitly to `true` only when the browser preview needs external HTTPS or WSS resources; otherwise set it to `false`.
+- Never add `script`, `ready_path`, `port`, or kind-specific fields from the other manifest shape.
 - Do not declare a preview that exposes secrets, credentials, private host-local pages, source maps, `.env` content, debug file browsers, or implementation-only tooling.
 
 # Safety

package/prompts/runs/task-retry.md

@@ -30,9 +30,13 @@ Fields:
 Use `correction` to understand why the previous attempt could not be promoted and what this retry must fix.
 
 - `summary`: short human-readable summary of the previous attempt failure.
-- `reason_code`: machine-generated pipeline feedback code. Current sources include no candidate diff, failed checks, checks that modified tracked candidate files, and promotion reconcile failures. This code is assigned by Tutti Run pipeline, not by the model.
+- `reason_code`: machine-generated pipeline feedback code. Current sources include Artifact candidate validation, no candidate diff, failed checks, checks that modified tracked candidate files, and promotion reconcile failures. This code is assigned by Tutti Run pipeline, not by the model.
 - `guidance`: direct retry instruction generated by Tutti Run pipeline for the feedback reason.
-- `promotion_failure`: optional details for promotion or promotion-reconcile failures only.
+- `diagnostic`: required bounded diagnostic from the failed gate.
+  - `source`: stable diagnostic source such as `manifest_parser`, `package_json`, `preview_process`, `ready_probe`, `candidate_diff`, or `pipeline`.
+  - `text`: redacted original parser, process, probe, diff, or pipeline error text. Use it to fix the concrete failure; do not copy it into user-facing output or project docs.
+  - `truncated`: whether Tutti had to bound the original diagnostic.
+- `promotion_failure`: promotion or promotion-reconcile failure details, or explicit `null` when promotion was not reached.
   - `reason_code`: machine-generated promotion failure code, taken from the promotion result when available; otherwise Tutti falls back to the failed result error code or `promotion_reconcile_failed`.
   - `summary`: short promotion failure summary.
 
@@ -85,10 +89,42 @@ If the task creates or updates a user-viewable web page, static page, single-pag
 
 - Do not modify `tutti.artifact.json` for tasks unrelated to a visual artifact.
 - If an existing artifact remains the only current preview entry, update that manifest instead of creating another declaration.
-- Every artifact manifest must include top-level `version: 1` and a short viewer-facing `artifact.title`.
-- For a static artifact, declare `artifact.kind: "static"`, a repo-relative `root`, and an HTML `entry` within that root.
-- For a server artifact, declare `artifact.kind: "server"` and provide an `artifact:preview` npm script that listens on `127.0.0.1` using the injected `HOST` and `PORT` environment variables.
-- If the preview loads external images, fonts, API data, or other remote browser resources, set `artifact.network: true`; otherwise omit it or set it to `false`.
+- The manifest is a strict contract. Fill every field shown for the selected kind, do not add other fields, and do not rely on defaults.
+- A static artifact must use this exact shape:
+
+```json
+{
+  "version": 1,
+  "artifact": {
+    "title": "Landing Page",
+    "kind": "static",
+    "root": "dist",
+    "entry": "index.html",
+    "network": false
+  }
+}
+```
+
+- A server artifact must use this exact shape:
+
+```json
+{
+  "version": 1,
+  "artifact": {
+    "title": "App Preview",
+    "kind": "server",
+    "cwd": ".",
+    "entry": "/",
+    "network": false
+  }
+}
+```
+
+- For a static artifact, `root` and `entry` are repo-relative and `entry` must be an HTML file inside `root`.
+- For a server artifact, `cwd` is the repo-relative npm package directory and `entry` is the HTTP path Tutti opens.
+- A server artifact must provide an `artifact:preview` npm script in `cwd/package.json`; it must listen on `127.0.0.1` using the injected `HOST` and `PORT` environment variables.
+- Set `network` explicitly to `true` only when the browser preview needs external HTTPS or WSS resources; otherwise set it to `false`.
+- Never add `script`, `ready_path`, `port`, or kind-specific fields from the other manifest shape.
 - Do not declare a preview that exposes secrets, credentials, private host-local pages, source maps, `.env` content, debug file browsers, or implementation-only tooling.
 
 # Safety

package/prompts/runs/task-run.md

@@ -67,10 +67,42 @@ If the task creates or updates a user-viewable web page, static page, single-pag
 
 - Do not modify `tutti.artifact.json` for tasks unrelated to a visual artifact.
 - If an existing artifact remains the only current preview entry, update that manifest instead of creating another declaration.
-- Every artifact manifest must include top-level `version: 1` and a short viewer-facing `artifact.title`.
-- For a static artifact, declare `artifact.kind: "static"`, a repo-relative `root`, and an HTML `entry` within that root.
-- For a server artifact, declare `artifact.kind: "server"` and provide an `artifact:preview` npm script that listens on `127.0.0.1` using the injected `HOST` and `PORT` environment variables.
-- If the preview loads external images, fonts, API data, or other remote browser resources, set `artifact.network: true`; otherwise omit it or set it to `false`.
+- The manifest is a strict contract. Fill every field shown for the selected kind, do not add other fields, and do not rely on defaults.
+- A static artifact must use this exact shape:
+
+```json
+{
+  "version": 1,
+  "artifact": {
+    "title": "Landing Page",
+    "kind": "static",
+    "root": "dist",
+    "entry": "index.html",
+    "network": false
+  }
+}
+```
+
+- A server artifact must use this exact shape:
+
+```json
+{
+  "version": 1,
+  "artifact": {
+    "title": "App Preview",
+    "kind": "server",
+    "cwd": ".",
+    "entry": "/",
+    "network": false
+  }
+}
+```
+
+- For a static artifact, `root` and `entry` are repo-relative and `entry` must be an HTML file inside `root`.
+- For a server artifact, `cwd` is the repo-relative npm package directory and `entry` is the HTTP path Tutti opens.
+- A server artifact must provide an `artifact:preview` npm script in `cwd/package.json`; it must listen on `127.0.0.1` using the injected `HOST` and `PORT` environment variables.
+- Set `network` explicitly to `true` only when the browser preview needs external HTTPS or WSS resources; otherwise set it to `false`.
+- Never add `script`, `ready_path`, `port`, or kind-specific fields from the other manifest shape.
 - Do not declare a preview that exposes secrets, credentials, private host-local pages, source maps, `.env` content, debug file browsers, or implementation-only tooling.
 
 # Safety