/user-visible-output-contract

name: user-visible-output-contract
description: 用户可见输出契约 Owner — 统一入口检查、完成检查、确认、进度、结果、阻断及内部产物到用户交付的确定性投影

User Visible Output Contract Skill

职责

当任务需要输出 PC0~PC10、FC/SC/RC/T、CP/危险动作确认、长任务进度、最终结果、阻断原因或文件交付列表时，本 Skill 是用户可见语义与渲染的唯一 Owner。

本 Skill 只负责 `ArtifactDeliveryManifestV1 → ArtifactAnchorProjectionV1 / UserFacingArtifactSetV1 → PostCompletionActionSetV1 → EntryCheckModelV3 → DevCodexVisibleEnvelopeV3 → renderer`。最终结果生产者优先调用 `composeFinalArtifactDeliveryEnvelope` 串起 manifest、visible set、delivery attempts 与 envelope，禁止在最终回复中手写一套“主要产物”清单绕过该链路。它不替代 `compliance` 的检查含义、`cp-gate` 的确认状态、`report`/`memory` 的写入职责、`host-contract-verification` 的宿主 direct replay，也不判断专业内容质量。`DevCodexVisibleEnvelopeV1/V2` 只保留读取兼容，禁止新生产者继续写入。

确定性实现位于 `hooks/_runtime/visible-output-contract.cjs`，结构约束位于 `visible-output-contract.schema.json`。

触发条件

| 场景 | 是否触发 | |---|:---:| | PC0~PC10 入口检查 | 必须；且须作为用户**首次可见**块先于实质正文与产物 mutation（S07 时序；文首补 PC ≠ 先输出） | | FC/SC/RC/T 完成检查 | 必须 | | CP1/CP2/CP3、验证预算、发布或其他 DevCodex 工作流确认 | 必须；文件/命令操作权限提示由宿主自身呈现，不由 DevCodex 复制审批 | | 多批次进度、等待、阻断、恢复 | 必须 | | 最终结果与文件交付 | 必须 | | 仅内部状态写入且本轮无用户可见消息 | N/A + skipReason |

TaskPhaseProjectionGate（PF-183 · 条件）

多 active 任务、用户说「继续/刚才/当前」、或投影实施/进度时，用户可见进度/最终回复须含：

• `activeTask`（或等价任务名 + portable path）
• `phaseKind` 或 CP1～CP3 状态
• `sourceDelivery=none|started|partial|complete`
• 唯一 `nextAllowedAction`

禁止：把「04 已有 / CP3 候选」写成「已在实施」。仅 CP3 confirmed + 05 + source mutation 才可 `started`。 探针：`classifyTaskPhaseProjectionSample`（`scripts/lib/executable-absorption-gates.js`）。

单向链路

1. `ArtifactDeliveryManifestV1`：记录本任务所有持久化 mutation、恢复证据和审计证据；planned、observed、internalDelivered 必须精确对账，并在 `sourceArtifactIds.plannedArtifactIds / observedArtifactIds / internalDeliveredArtifactIds` 中保留原始规范化清单，供落盘后重新复算 manifestId 与 reconciliation。 2. `ArtifactAnchorProjectionV1`：可选上下文锚点投影，只携带 canonical path、contentDigest、projectionDigest、truthSourceKind、stalePolicy 与 evidenceRefs，不复制正文。 3. `UserFacingArtifactSetV1`：只能由 manifest 纯函数投影，禁止模型临场挑“主要产物”。 4. `PostCompletionActionSetV1`：从已验证缺口、Profile 和用户授权边界投影“当前必做 / 唯一主动作 / 最多两个条件动作”；不得把产物文件当动作。 5. `EntryCheckModelV3`：入口语义的唯一机器模型，固定承载 PC0 版本身份、PC1~PC7 既有事实、PC8 流程/方案决策、PC9 验证计划和 PC10 后续动作。 6. `DevCodexVisibleEnvelopeV3`：承载 message kind、稳定状态、checks、entry check model、decision、visible set、action set、capability 和 semantic digest。 7. renderer：按已验证能力生成 `rich-markdown / portable-markdown / plain-text`；不得改变语义集合、顺序、状态或动作。

禁止 renderer、Prompt、Hook parser 或最终回复反向补写 manifest 状态。

ArtifactDeliveryManifestGate

每个 entry 必须包含：

`artifactId / canonicalPath / previousPath / lifecycleOperation / origin / ownership / artifactClass / deliveryRequirement / visibility / displayName / purposeKey / purposeText / userAction / readingOrder / contentDigest / evidenceRefs[]`。

• `lifecycleOperation=create|update|rename|move|delete|unchanged-evidence`；rename/move/delete 必须保留 previousPath，delete 使用 tombstone 语义。
• `visibility=decision-required|result|evidence|optional-detail|internal-only`。
• `deliveryRequirement=required|supporting|internal`；required 不得隐藏，internal 必须为 internal-only。
• `reconciliation` 必须满足 planned=observed=entries=internalDelivered；missing/unexpected/conflicting 任一非空即 BLOCK。
• `sourceArtifactIds` 必须保留规范化后的 planned / observed / internalDelivered 三组清单；完整性校验不得从 `entries` 自我重建三组清单来冒充原始输入已复证。
• 同一 artifactId 或 canonicalPath 重复、`file://`、非语义 displayName、缺 digest/evidence 均为非法。
• 根 manifest 的序列化容器不登记为自身 entry，避免 self-hash 无限递归；其 storage path 与文件 SHA256 必须由上级 ECR/validation receipt 记录。其他批次 manifest 或 raw manifest 作为普通输入时仍属于 `raw-manifest/internal-only`，不得借此例外漏记。
• 任务目录级 `TaskArtifactDeliveryManifestV2` 不直接替代最终用户可见 manifest；需要进入最终回复或 ECR 时，必须通过 `createVisibleManifestFromTaskDeliveryManifest` 投影为 `ArtifactDeliveryManifestV1`，再继续 `UserFacingArtifactSetV1` 与 envelope 链路。

ArtifactAnchorProjectionGate

当任务需要后续上下文续接、短投影或跨报告锚点时，必须从已验证的 `ArtifactDeliveryManifestV1` 纯函数生成 `ArtifactAnchorProjectionV1`，禁止手写锚点列表。

• `ArtifactAnchorV1` 必须包含 `artifactId / artifactKind / truthSourceKind / canonicalPath / contentDigest / projectionDigest / generatedAt / owner / status / stalePolicy / evidenceRefs[] / summaryLine / classification / anchorDigest`。
• `truthSourceKind=json-canonical|markdown-canonical|projection|external`，由 `classifyArtifactTruthSource` 按 artifactKind 决定；调用方显式覆盖时也必须落入枚举。
• JSON canonical 产物优先用于机器校验；Markdown canonical 产物可生成短 MD 投影，但短投影只能作为 `projectionDigest` 与 `summaryLine`，不能替代 canonical contentDigest。
• manifest 未对账、缺 contentDigest、非绝对 canonicalPath、`file://`、非法 status 或证据列表无效时，anchor projection 必须 invalid/BLOCK。

UserFacingArtifactProjectionGate

默认用户面只包含：

• `decision-required`；
• `result`；
• `deliveryRequirement=required` 的 evidence。

session、daily、Agent/全局 SUMMARY、task state、checkpoint/runtime state、raw receipt、raw manifest、raw ledger 默认 `internal-only`，但仍必须写入、验证、进入 manifest 并参与 ECR。只有用户明确要求、resume/handoff、状态冲突、写入失败、治理调查、审计取证或文件本身就是审查对象时，才升级为可见。

投影 scope：

| scope | 行为 | |---|---| | `default` | 最小必要用户交付 | | `all-deliverable` | 所有非 internal-only 项；用于用户要求完整交付清单 | | `internal-audit` | 包含 internal-only；仅审计、治理调查或用户明确要求内部留痕时 |

每次投影必须满足 `listed + remaining = total`，并按 `decision-required → result → evidence → optional-detail`、readingOrder、artifactId 稳定排序。

SemanticArtifactNameGate

• 用户面名称必须是“内容与用途”，不能只是路径、文件名、CP 编号、版本或状态。
• 每项必须同时给出 `displayName + purposeText + userAction`。
• 动作标题仅允许：`需要你确认的文件 / 本批交付文件 / 完成交付文件 / 阻断证据`。
• 禁止当前消费者输出“主要产物”或“本次会话全部产物”；历史版本文档不回填。

ArtifactPathColumnGate（PF-175 / PI-155）

用户面交付表、CP 确认清单与 Envelope renderer **必须**为每项提供可定位路径，且与语义名分离：

| 规则 | 要求 | |------|------| | 默认列 | 自由文本表：`语义名称 \| 用途 \| 路径 \| 操作`（操作可并入用途列，但**路径列不可省**） | | list 行 | 至少含 `displayName` + `purposeText` + `路径：…` + `操作：…` | | 路径默认值 | **workspace-relative portable**（`path.relative(workspaceRoot)` 风格，正斜杠） | | 绝对路径 | 仅当：用户明确要求、链接失败、`targetRelation=outside-workspace`、路径歧义、或 `absolutePathFallback` | | Rich 并存 | Rich clickable 允许 **语义链接 href=绝对路径（便于打开）** + **路径列=portable**；**禁止**再追加冗余 `绝对路径：…` 行（除非 fallback 激活） | | 禁止 | legacy「主要产物 / 核心文件 / 路