@xfey/tutti 0.1.20 → 0.1.22

package/node_modules/@tutti/shared/dist/schemas/api/project-timeline.js

@@ -1,23 +1,139 @@
 import { Type } from "@sinclair/typebox";
-import { ActivityRefSchema, IsoDateTimeStringSchema, TaskIdSchema, WorkflowInvocationRefSchema, } from "../domain/index.js";
+import { ActivityRefSchema, IsoDateTimeStringSchema, MessageIdSchema, RunResultIdSchema, TaskIdSchema, WorkflowInvocationRefSchema, } from "../domain/index.js";
 import { ProviderUsageBreakdownProjectionSchema, ProviderUsageModelSummaryProjectionSchema, ProviderUsageProjectionSchema, ProviderUsageSourceSummaryProjectionSchema, } from "./provider-usage.js";
 export const ProjectTimelineItemKindSchema = Type.Union([
-    Type.Literal("run"),
-    Type.Literal("procedure"),
-    Type.Literal("commit"),
-    Type.Literal("usage"),
-    Type.Literal("clarification"),
-    Type.Literal("checks"),
-    Type.Literal("promotion"),
-    Type.Literal("recovery"),
+    Type.Literal("task_accepted"),
+    Type.Literal("task_update"),
+    Type.Literal("checkpoint"),
 ]);
 export const ProjectTimelineItemStatusSchema = Type.Union([
-    Type.Literal("running"),
     Type.Literal("completed"),
     Type.Literal("failed"),
     Type.Literal("needs_human"),
-    Type.Literal("skipped"),
 ]);
+export const ProjectTimelineTaskUpdateStateSchema = Type.Union([
+    Type.Literal("needs_input"),
+    Type.Literal("completed"),
+    Type.Literal("failed"),
+]);
+export const ProjectTimelineTraceToneSchema = Type.Union([
+    Type.Literal("neutral"),
+    Type.Literal("success"),
+    Type.Literal("warning"),
+    Type.Literal("error"),
+]);
+export const ProjectTimelineTraceLinkSchema = Type.Object({
+    kind: Type.Union([
+        Type.Literal("worklist_task"),
+        Type.Literal("chat_message"),
+        Type.Literal("reference_file"),
+        Type.Literal("repo_path"),
+    ]),
+    label: Type.String({ minLength: 1 }),
+    task_id: Type.Optional(TaskIdSchema),
+    message_id: Type.Optional(MessageIdSchema),
+    path: Type.Optional(Type.String({ minLength: 1 })),
+}, { additionalProperties: false });
+export const ProjectTimelineSourceSnippetSchema = Type.Object({
+    message_id: MessageIdSchema,
+    author: Type.String({ minLength: 1 }),
+    body: Type.String(),
+    created_at: IsoDateTimeStringSchema,
+}, { additionalProperties: false });
+export const ProjectTimelineDecisionSummarySchema = Type.Object({
+    title: Type.Optional(Type.String({ minLength: 1 })),
+    summary: Type.String({ minLength: 1 }),
+    source: Type.Optional(Type.Union([
+        Type.Literal("scratchpad"),
+        Type.Literal("clarification"),
+        Type.Literal("contract"),
+    ])),
+}, { additionalProperties: false });
+export const ProjectTimelineClarificationTraceSchema = Type.Object({
+    title: Type.Optional(Type.String({ minLength: 1 })),
+    summary: Type.Optional(Type.String()),
+    request: Type.Optional(Type.String()),
+    status: Type.Optional(Type.Union([Type.Literal("active"), Type.Literal("resolved")])),
+    answer_count: Type.Optional(Type.Integer({ minimum: 0 })),
+    answers: Type.Optional(Type.Array(ProjectTimelineSourceSnippetSchema)),
+}, { additionalProperties: false });
+export const ProjectTimelineChangeStatusSchema = Type.Union([
+    Type.Literal("added"),
+    Type.Literal("modified"),
+    Type.Literal("deleted"),
+    Type.Literal("renamed"),
+    Type.Literal("unknown"),
+]);
+export const ProjectTimelineTraceCardSchema = Type.Object({
+    tone: ProjectTimelineTraceToneSchema,
+    summary: Type.Optional(Type.String()),
+    origin: Type.Optional(Type.Object({
+        title: Type.Optional(Type.String({ minLength: 1 })),
+        summary: Type.Optional(Type.String()),
+        snippets: Type.Optional(Type.Array(ProjectTimelineSourceSnippetSchema)),
+        source_count: Type.Optional(Type.Integer({ minimum: 0 })),
+        unavailable_reason: Type.Optional(Type.String({ minLength: 1 })),
+    }, { additionalProperties: false })),
+    decisions: Type.Optional(Type.Array(ProjectTimelineDecisionSummarySchema)),
+    clarification: Type.Optional(ProjectTimelineClarificationTraceSchema),
+    contract: Type.Optional(Type.Object({
+        goal: Type.String(),
+        scope: Type.Array(Type.String()),
+        truncated: Type.Optional(Type.Boolean()),
+    }, { additionalProperties: false })),
+    result: Type.Optional(Type.Object({
+        summary: Type.String(),
+        error_code: Type.Optional(Type.String({ minLength: 1 })),
+    }, { additionalProperties: false })),
+    changes: Type.Optional(Type.Object({
+        items: Type.Array(Type.Object({
+            status: ProjectTimelineChangeStatusSchema,
+            path: Type.String({ minLength: 1 }),
+            previous_path: Type.Optional(Type.String({ minLength: 1 })),
+        }, { additionalProperties: false })),
+        total_count: Type.Integer({ minimum: 0 }),
+        truncated: Type.Boolean(),
+    }, { additionalProperties: false })),
+    verification: Type.Optional(Type.Object({
+        checks: Type.Union([
+            Type.Literal("passed"),
+            Type.Literal("failed"),
+            Type.Literal("skipped"),
+        ]),
+        skip_reason_code: Type.Optional(Type.String({ minLength: 1 })),
+        skip_reason_summary: Type.Optional(Type.String()),
+    }, { additionalProperties: false })),
+    promotion: Type.Optional(Type.Object({
+        status: Type.Union([
+            Type.Literal("promoted"),
+            Type.Literal("not_promoted"),
+            Type.Literal("not_attempted"),
+        ]),
+        commit_oid: Type.Optional(Type.String({ minLength: 1 })),
+        commit_short_oid: Type.Optional(Type.String({ minLength: 1 })),
+        summary: Type.Optional(Type.String()),
+        reason_code: Type.Optional(Type.String({ minLength: 1 })),
+    }, { additionalProperties: false })),
+    checkpoint: Type.Optional(Type.Object({
+        counters: Type.Object({
+            completed: Type.Integer({ minimum: 0 }),
+            failed: Type.Integer({ minimum: 0 }),
+            remaining: Type.Integer({ minimum: 0 }),
+        }, { additionalProperties: false }),
+        items: Type.Array(Type.Object({
+            task_id: TaskIdSchema,
+            title: Type.String({ minLength: 1 }),
+            status: Type.Union([Type.Literal("done"), Type.Literal("failed")]),
+            summary: Type.String(),
+        }, { additionalProperties: false })),
+        generated_files: Type.Optional(Type.Array(Type.Object({
+            path: Type.String({ minLength: 1 }),
+            name: Type.String({ minLength: 1 }),
+        }, { additionalProperties: false }))),
+        truncated: Type.Optional(Type.Boolean()),
+    }, { additionalProperties: false })),
+    links: Type.Array(ProjectTimelineTraceLinkSchema),
+}, { additionalProperties: false });
 export const ProjectTimelineItemSchema = Type.Object({
     id: Type.String({ minLength: 1 }),
     kind: ProjectTimelineItemKindSchema,
@@ -28,13 +144,14 @@ export const ProjectTimelineItemSchema = Type.Object({
     task_title: Type.Optional(Type.String({ minLength: 1 })),
     activity_ref: Type.Optional(ActivityRefSchema),
     workflow_ref: Type.Optional(WorkflowInvocationRefSchema),
-    commit_oid: Type.Optional(Type.String({ minLength: 1 })),
-    commit_short_oid: Type.Optional(Type.String({ minLength: 1 })),
+    run_result_id: Type.Optional(RunResultIdSchema),
+    message_id: Type.Optional(MessageIdSchema),
     status: Type.Optional(ProjectTimelineItemStatusSchema),
+    update_state: Type.Optional(ProjectTimelineTaskUpdateStateSchema),
     token_usage: Type.Optional(ProviderUsageBreakdownProjectionSchema),
     usage_sources: Type.Optional(Type.Array(ProviderUsageSourceSummaryProjectionSchema)),
     usage_models: Type.Optional(Type.Array(ProviderUsageModelSummaryProjectionSchema)),
-    meta: Type.Optional(Type.Array(Type.String({ minLength: 1 }))),
+    trace_card: Type.Optional(ProjectTimelineTraceCardSchema),
 }, { additionalProperties: false });
 export const ProjectTimelineResponseSchema = Type.Object({
     generated_at: IsoDateTimeStringSchema,

package/node_modules/@tutti/shared/dist/schemas/api/types.d.ts

@@ -3,7 +3,7 @@ import type { IdempotencyKeySchema, IsoDateTimeStringSchema } from "../domain/in
 import type { ApiErrorCodeSchema, ApiErrorResponseSchema, CommandDispositionBaseSchema, CursorPageRequestSchema, InterruptedCommandDispositionSchema, QueryInvalidationHintSchema, RelayInvalidationHintSchema, RelaySseEventTypeSchema, SseReplayWindowPolicySchema, WorkspaceSseEventTypeSchema } from "./primitives.js";
 import type { ProviderConfigInvalidReasonCodeSchema, ProviderConfigProjectionSchema, ProviderUnavailableReasonCodeSchema } from "./provider-config.js";
 import type { ProviderUsageBreakdownProjectionSchema, ProviderUsageCategorySchema, ProviderUsageModelSummaryProjectionSchema, ProviderUsageProjectionSchema, ProviderUsageSourceSummaryProjectionSchema } from "./provider-usage.js";
-import type { ProjectTimelineItemKindSchema, ProjectTimelineItemSchema, ProjectTimelineItemStatusSchema, ProjectTimelineResponseSchema } from "./project-timeline.js";
+import type { ProjectTimelineItemKindSchema, ProjectTimelineItemSchema, ProjectTimelineItemStatusSchema, ProjectTimelineResponseSchema, ProjectTimelineTaskUpdateStateSchema, ProjectTimelineClarificationTraceSchema, ProjectTimelineTraceCardSchema, ProjectTimelineTraceLinkSchema } from "./project-timeline.js";
 import type { PresignedUploadPutSchema, RelayUploadProjectionSchema, RelayUploadPurposeSchema, Sha256DigestSchema, StagedUploadReferenceSchema, StartRelayUploadDispositionSchema, StartRelayUploadPayloadSchema, StartRelayUploadResultSchema } from "./uploads.js";
 import type { MarkReadDispositionSchema, MarkReadPayloadSchema, MarkReadResultSchema, ReadStateScopeProjectionSchema, ReadStateScopeSchema, ReadStateSummaryProjectionSchema } from "./read-state.js";
 import type { GetMessagesRequestSchema, MessageCreatedEventPayloadSchema, MessageProjectionSchema, MessageReferenceFileRefSchema, ReferenceFileCategorySchema, SendMainChatMessageCreatedDispositionSchema, SendMainChatMessageDispositionSchema, SendMainChatMessagePayloadSchema, SendMainChatMessageResultSchema, WorklistFeedbackGeneratedFileSchema, WorklistFeedbackItemSchema, WorklistFeedbackRefSchema } from "./messages.js";
@@ -63,6 +63,10 @@ export type ProviderUsageModelSummaryProjection = Static<typeof ProviderUsageMod
 export type ProviderUsageProjection = Static<typeof ProviderUsageProjectionSchema>;
 export type ProjectTimelineItemKind = Static<typeof ProjectTimelineItemKindSchema>;
 export type ProjectTimelineItemStatus = Static<typeof ProjectTimelineItemStatusSchema>;
+export type ProjectTimelineTaskUpdateState = Static<typeof ProjectTimelineTaskUpdateStateSchema>;
+export type ProjectTimelineClarificationTrace = Static<typeof ProjectTimelineClarificationTraceSchema>;
+export type ProjectTimelineTraceCard = Static<typeof ProjectTimelineTraceCardSchema>;
+export type ProjectTimelineTraceLink = Static<typeof ProjectTimelineTraceLinkSchema>;
 export type ProjectTimelineItem = Static<typeof ProjectTimelineItemSchema>;
 export type ProjectTimelineResponse = Static<typeof ProjectTimelineResponseSchema>;
 export type ApprovalRequestKind = Static<typeof ApprovalRequestKindSchema>;

package/package.json

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

package/prompts/procedures/README.md

@@ -14,7 +14,7 @@
 
 `project_context_bootstrap` 的 provider path 只让 Codex app-server read-only adapter 生成缺失文档内容；如果该计划不可用，Control Plane 会回退到本地保守模板。
 `project_context_bootstrap` 的 read-only 输入只包含项目名、非空时的 `missing_docs` 与刷新后的 Scratchpad；prompt 会要求 app-server 只读探索仓库，并可通过 `read-project-docs` / `read-references` skill 按需读取现有文档和参考文件。输出只包含 `documents[].doc_key/content`，固定 path 由 Control Plane 后处理生成。
-`task_compile` 的 read-only 输入只包含压缩后的 Scratchpad、Worklist 和可选 clarification request / answer messages；workflow ref、activity ref、Scratchpad / Worklist 审计字段、排序字段、时间戳和完整 message projection 不进入 prompt。prompt 暴露 `read-project-docs` / `read-worklist` / `read-references` skills 供 app-server 必要时读取项目上下文文件、既有任务 contract / latest result 或相关 reference 正文；Scratchpad 和 Worklist 紧凑视图仍以直接输入为准，不通过 skill 重读 Scratchpad。provider raw output 使用 `{ result: ... }` 互斥分支；proposal 分支用 `module_ref` 指向新模块或既有模块，task 只输出 `title / goal / scope`，runner adapter 再映射为 Control Plane 内部 proposal：`goal` 同时作为内部 task summary 和 contract goal，`scope` 作为内部 contract scope。该 prompt 内部承担任务化 readiness 判断：能冻结没有重大隐藏假设的正式 task contract 时返回 proposal；如果缺失决策会显著改变目标、范围、用户可见行为、视觉 / 交互方向、技术形态、数据 / 资产来源、验收、安全边界或外部副作用，且无法从现有上下文可靠推断，则返回 workflow-bound clarification。该 prompt 也要求任务字段短而具体，避免 `title / goal / scope` 互相复述；Web 任务契约区只展示目标与范围，运行账本字段仍折叠展示。
+`task_compile` 的 read-only 输入只包含压缩后的 Scratchpad、Worklist 和可选 clarification request / answer messages；workflow ref、activity ref、Scratchpad / Worklist 审计字段、排序字段、时间戳和完整 message projection 不进入 prompt。prompt 暴露 `read-project-docs` / `read-worklist` / `read-references` skills 供 app-server 必要时读取项目上下文文件、既有任务 contract / latest result 或相关 reference 正文；Scratchpad 和 Worklist 紧凑视图仍以直接输入为准，不通过 skill 重读 Scratchpad。provider raw output 使用 `{ result: ... }` 互斥分支；proposal 分支用 `module_ref` 指向新模块或既有模块，task 只输出 `title / goal / scope`，runner adapter 再映射为 Control Plane 内部 proposal：`goal` 同时作为内部 task summary 和 contract goal，`scope` 作为内部 contract scope。该 prompt 内部承担任务化 readiness 判断：能冻结没有重大隐藏假设的正式 task contract 时返回 proposal；如果缺失决策会显著改变目标、范围、用户可见行为、视觉 / 交互方向、技术形态、数据 / 资产来源、验收、安全边界或外部副作用，且无法从现有上下文可靠推断，则返回 workflow-bound clarification。当 Scratchpad 明确要求可预览页面、可交互产物、报告、规格、导出或其他直接交付物时，prompt 要求在 task `scope` 中简洁点明交付面：可视化 / 交互预览对应 active `tutti.artifact.json`，Tutti 生成的用户可见文件对应 `docs/reference/tutti/<meaningful-folder>/...`，需要完成卡片直接提示结果时可提到 `user_note_candidate`。`docs/reference/tutti/**` 是 References UI 会展示的生成文件命名空间，不是临时输出或 canonical project docs。该 prompt 也要求任务字段短而具体，避免 `title / goal / scope` 互相复述；Web 任务契约区只展示目标与范围，运行账本字段仍折叠展示。
 `context_sync` 没有 provider-facing direct input；workflow ref、activity ref、触发原因、安全元数据、checked paths、skipped paths 和 open questions 都不进入 prompt，只用于运行时追踪、调度或审计。prompt 说明通用文档同步目标、目标项目文档落点和 canonical docs 职责，由 app-server 主动探索 repo，并通过 `read-project-docs` / `read-worklist` / `read-references` skill 按需读取现有文档、正式任务上下文和参考文件。Worklist / task result 只作为阶段性完成背景和稳定结果线索，不写成长文档里的逐任务流水。
 `context_sync` prompt 只返回 `summary` 与 `updates[].path/content`；空 `updates` 表示无需同步，非空 `updates` 由 Control Plane 调用 `workspace-ops` 做 path policy、mainline clean 检查、文件写入和 Git commit。
 `project_brief_refresh` 只走 OpenAI SDK structured output，不使用 Codex app-server，不读取 repo 或 skills。它接收四个 baseline Project Docs 的 bounded source 内容与状态，输出 `product_summary / tech_summary / structure_summary / principles_summary`，由 Control Plane 写入 host-local `project_brief` projection；Project Docs 创建、同步、被成功 Run promotion 修改，或 provider setup 后需要 backfill 时可以触发。provider 不可用、source 不可用、brief 已经 fresh 或刷新失败都不影响 Project Docs 写入结果。

package/prompts/procedures/task-compile.md

@@ -28,9 +28,16 @@ You compile Tutti's Scratchpad into an append-only Worklist proposal for post-ba
 - Preserve user-provided non-secret details when they are needed to execute or accept the task. Do not generalize them into vague labels.
 - Do not use web search, credentials, provider internals, raw logs, or Tutti runtime/internal paths.
 
-# Artifacts Context
+# Delivery Surface Context
 
-Tutti can expose a user-viewable artifact, such as a static page or app preview, as a concrete deliverable for project members to inspect. When the Scratchpad asks for an artifact or preview, keep the task subject anchored to the established product, feature, design direction, or implementation target; treat "artifact" as the delivery format unless context makes it the subject.
+Tutti can expose direct user-viewable outputs through two repo-backed surfaces when a task result is meant for project members to inspect:
+
+- a single active visual artifact, declared by `tutti.artifact.json`, for previewable pages, apps, dashboards, or similar interactive outputs;
+- generated files under `docs/reference/tutti/**`, for reviewable files such as reports, notes, specs, exports, or similar outputs.
+
+Treat these as delivery surfaces, not as task subjects by themselves. Human-uploaded references still live under `docs/reference/files/` or `docs/reference/images/`, and stable project facts still belong in the relevant project docs or README-style files.
+
+When the Scratchpad clearly asks for one of these direct deliverables, include a concise task `scope` item naming the expected surface. If a completion card should call out the result or generated file name, the scope may also mention `user_note_candidate`. Do not add artifact or generated-reference outputs solely to create feedback for ordinary implementation tasks.
 
 # Readiness
 

package/prompts/runs/README.md

@@ -10,8 +10,8 @@ Templates in this directory may describe task contracts, repo evidence, check ex
 `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,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/`; Tutti-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 and rendered by References automatically.
-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.
+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 Worklist terminal feedback.
+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.
 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

@@ -57,7 +57,14 @@ Use attached skills only when they help the current task:
 
 Human-uploaded reference material is kept in the repository under `docs/reference/`. If the task contract, project docs, or clarification answer makes a reference file relevant, read the actual repo file before relying on it. Do not infer reference contents from names, upload messages, media types, or paths.
 
-`docs/reference/` is a user-visible file exchange area. Human uploads live under `docs/reference/files/` and `docs/reference/images/`. When this task produces files that project members should inspect directly, write them under `docs/reference/tutti/`. Use `docs/reference/tutti/<meaningful-folder>/...` when a folder name helps explain the output group; that folder name is shown directly in the References UI. Do not create ad hoc folders at the `docs/reference/` root. Files under `docs/reference/tutti/` are displayed automatically, so `user_note_candidate` may mention generated file names but should not include paths.
+`docs/reference/` is a user-visible file exchange area:
+
+- Human uploads live under `docs/reference/files/` and `docs/reference/images/`.
+- `docs/reference/tutti/**` is for Tutti-generated files that project members should inspect directly in the References UI.
+- Use `docs/reference/tutti/**` for reviewable deliverables such as reports, notes, specs, exports, or similar generated files.
+- Do not use `docs/reference/tutti/**` for temporary output, internal notes, logs, or canonical project documentation.
+
+When this task explicitly produces such a file deliverable, write it under `docs/reference/tutti/`. Use `docs/reference/tutti/<meaningful-folder>/...` when a folder name helps explain the output group; that folder name is shown directly in the References UI and promoted files may be listed in Worklist terminal feedback. Do not create ad hoc folders at the `docs/reference/` root. Files under `docs/reference/tutti/` are displayed automatically, so `user_note_candidate` may mention generated file names but should not include paths.
 
 # Documentation
 
@@ -73,9 +80,9 @@ 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 declaration must include a short viewer-facing `artifact.title`.
-- For a static artifact, declare `version: 1`, `artifact.title`, `artifact.kind: "static"`, a repo-relative `root`, and an HTML `entry` within that root.
-- For a server artifact, declare `artifact.title`, `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.
+- 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`.
 - Do not declare a preview that exposes secrets, credentials, private host-local pages, source maps, `.env` content, debug file browsers, or implementation-only tooling.
 

package/prompts/runs/task-retry.md

@@ -62,7 +62,14 @@ Use attached skills only when they help the current task:
 
 Human-uploaded reference material is kept in the repository under `docs/reference/`. If the task contract, project docs, or correction context makes a reference file relevant, read the actual repo file before relying on it. Do not infer reference contents from names, upload messages, media types, or paths.
 
-`docs/reference/` is a user-visible file exchange area. Human uploads live under `docs/reference/files/` and `docs/reference/images/`. When this task produces files that project members should inspect directly, write them under `docs/reference/tutti/`. Use `docs/reference/tutti/<meaningful-folder>/...` when a folder name helps explain the output group; that folder name is shown directly in the References UI. Do not create ad hoc folders at the `docs/reference/` root. Files under `docs/reference/tutti/` are displayed automatically, so `user_note_candidate` may mention generated file names but should not include paths.
+`docs/reference/` is a user-visible file exchange area:
+
+- Human uploads live under `docs/reference/files/` and `docs/reference/images/`.
+- `docs/reference/tutti/**` is for Tutti-generated files that project members should inspect directly in the References UI.
+- Use `docs/reference/tutti/**` for reviewable deliverables such as reports, notes, specs, exports, or similar generated files.
+- Do not use `docs/reference/tutti/**` for temporary output, internal notes, logs, or canonical project documentation.
+
+When this task explicitly produces such a file deliverable, write it under `docs/reference/tutti/`. Use `docs/reference/tutti/<meaningful-folder>/...` when a folder name helps explain the output group; that folder name is shown directly in the References UI and promoted files may be listed in Worklist terminal feedback. Do not create ad hoc folders at the `docs/reference/` root. Files under `docs/reference/tutti/` are displayed automatically, so `user_note_candidate` may mention generated file names but should not include paths.
 
 # Documentation
 
@@ -78,9 +85,9 @@ 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 declaration must include a short viewer-facing `artifact.title`.
-- For a static artifact, declare `version: 1`, `artifact.title`, `artifact.kind: "static"`, a repo-relative `root`, and an HTML `entry` within that root.
-- For a server artifact, declare `artifact.title`, `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.
+- 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`.
 - Do not declare a preview that exposes secrets, credentials, private host-local pages, source maps, `.env` content, debug file browsers, or implementation-only tooling.
 

package/prompts/runs/task-run.md

@@ -44,7 +44,14 @@ Use attached skills only when they help the current task:
 
 Human-uploaded reference material is kept in the repository under `docs/reference/`. If the task contract or project docs make a reference file relevant, read the actual repo file before relying on it. Do not infer reference contents from names, upload messages, media types, or paths.
 
-`docs/reference/` is a user-visible file exchange area. Human uploads live under `docs/reference/files/` and `docs/reference/images/`. When this task produces files that project members should inspect directly, write them under `docs/reference/tutti/`. Use `docs/reference/tutti/<meaningful-folder>/...` when a folder name helps explain the output group; that folder name is shown directly in the References UI. Do not create ad hoc folders at the `docs/reference/` root. Files under `docs/reference/tutti/` are displayed automatically, so `user_note_candidate` may mention generated file names but should not include paths.
+`docs/reference/` is a user-visible file exchange area:
+
+- Human uploads live under `docs/reference/files/` and `docs/reference/images/`.
+- `docs/reference/tutti/**` is for Tutti-generated files that project members should inspect directly in the References UI.
+- Use `docs/reference/tutti/**` for reviewable deliverables such as reports, notes, specs, exports, or similar generated files.
+- Do not use `docs/reference/tutti/**` for temporary output, internal notes, logs, or canonical project documentation.
+
+When this task explicitly produces such a file deliverable, write it under `docs/reference/tutti/`. Use `docs/reference/tutti/<meaningful-folder>/...` when a folder name helps explain the output group; that folder name is shown directly in the References UI and promoted files may be listed in Worklist terminal feedback. Do not create ad hoc folders at the `docs/reference/` root. Files under `docs/reference/tutti/` are displayed automatically, so `user_note_candidate` may mention generated file names but should not include paths.
 
 # Documentation
 
@@ -60,9 +67,9 @@ 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 declaration must include a short viewer-facing `artifact.title`.
-- For a static artifact, declare `version: 1`, `artifact.title`, `artifact.kind: "static"`, a repo-relative `root`, and an HTML `entry` within that root.
-- For a server artifact, declare `artifact.title`, `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.
+- 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`.
 - Do not declare a preview that exposes secrets, credentials, private host-local pages, source maps, `.env` content, debug file browsers, or implementation-only tooling.