evidentloop · Li-Sanze · May 28, 2026 · May 28, 2026
diff --git a/.sopify-skills/history/2026-05/20260528_output_contract_enforcement/background.md b/.sopify-skills/history/2026-05/20260528_output_contract_enforcement/background.md
@@ -0,0 +1,55 @@
+# 变更提案: 输出契约提示层与模板结构约束
+
+## 需求背景
+
+Sopify 有 6 个输出模板（analyze ×2、design ×1、develop ×3），但缺少两层保障：
+
+1. **无契约提示**：模板定义了验证表格、必需 section，但宿主没有显式自检规则，遵守与否全凭 LLM 自觉。
+2. **无条件增强指引**：analyze/design/consult 场景在复杂情况下应升级为表格/对比结构，但模板是静态的，没有"何时增强"的触发规则。
+3. **consult 零模板**：咨询问答是最高频场景之一，但没有任何输出指引。
+
+根因：`20260527_skill_writing_quality` 修复了模板内容和 render 管线，但未补宿主侧自检规则和条件增强指引。
+
+**runtime 背景**：runtime 正在逐步退场。本期不追加 gate/routing 渲染器改动、不实现 bridge validator。所有增强走 prompt/skill/template 层，对所有宿主（Copilot/Codex/Claude）统一生效。
+
+评分:
+- 方案质量: 8/10
+- 落地就绪: 9/10
+
+评分理由:
+- 优点: 纯 prompt 层改动，不侵入 runtime、不新增配置/脚本，所有宿主统一受益
+- 扣分: 提示层无法 100% 强制 LLM 遵守，真正的机器强制需后续 bridge/schema（列为显式债务）
+
+## 变更内容
+
+1. **新增输出契约参考文档**：`references/output-contract.md`，定义每类输出的 required sections、表格列约束、条件增强与表达选型（含 DO/DON'T）、输出前自检清单。通过 render 管线内联到所有宿主 prompt。
+2. **补 develop 自检规则**：在 `develop-rules.md` 中加输出前自检子节。
+3. **补 golden snapshot 结构断言**：在 `test_golden_snapshots.py` 中加模板结构验证 + 验证 output-contract.md 被内联。
+
+## 影响范围
+
+- 新增: `skills/{zh,en}/skills/sopify/references/output-contract.md`（ZH + EN）
+- 修改: `skills/{zh,en}/skills/sopify/analyze/SKILL.md`（加引用行）
+- 修改: `skills/{zh,en}/skills/sopify/design/SKILL.md`（加引用行）
+- 修改: `skills/{zh,en}/skills/sopify/develop/SKILL.md`（加引用行）
+- 修改: `skills/{zh,en}/skills/sopify/develop/references/develop-rules.md`（加自检子节）
+- 修改: `tests/test_golden_snapshots.py`（加结构断言）
+- 修改: `tests/golden-snapshots.json`（hash 更新）
+
+## 风险评估
+
+- 风险: 结构断言过严，正常模板改动频繁导致测试脆弱
+- 缓解: 结构断言只验必需 section 存在（如表头 `| 任务 |`、`Changes:`、`Next:`），不验具体内容；表格列允许场景化省略
+
+## 明确不做
+
+- 不修改 gate/routing 渲染器（runtime 正在退场，gate 输出职责不变）
+- 不实现 bridge validator 代码（列为后续显式债务）
+- 不新增 `output_contract.yaml` 配置文件
+- 不给 consult 创建独立 skill 目录
+- 不对简单问答强制表格
+- 不修改 `protocol.md`（输出路径职责写在 output-contract.md 即可，不需要另开一个文件）
+
+## 显式后续债务
+
+- bridge/schema validator：当 host bridge 落地时，可基于 output-contract.md 的 required sections 做 advisory 校验。本期只留文档化设计意图，不写代码。
diff --git a/.sopify-skills/history/2026-05/20260528_output_contract_enforcement/design.md b/.sopify-skills/history/2026-05/20260528_output_contract_enforcement/design.md
@@ -0,0 +1,103 @@
+# 技术设计: 输出契约提示层与模板结构约束
+
+## 设计原则
+
+所有增强走 prompt/skill/template 层，不碰 runtime。原因：
+- runtime 正在退场，不应追加投入
+- prompt 层改动对 Copilot/Codex/Claude 统一生效
+- 提示层无法 100% 强制 LLM，但可以显著提高一致性
+
+## 输出契约参考文档
+
+### 定位
+
+一个共享参考文档（类似 `shared-writing-dna.md`），定义所有阶段输出的 required/adaptive 规则。通过 render 管线内联到所有宿主 prompt。
+
+落点：`skills/zh/skills/sopify/references/output-contract.md`
+
+render 管线已在 `20260527` 修复中支持顶层 `references/` 内联，所以新文件自动进入所有宿主的 managed block。
+
+### 内容结构（最终 4 section）
+
+```
+1. 输出路径说明（gate 摘要 ≠ 最终回复，不写死 runtime 文件名）
+2. 必需 section 契约表（per output type）+ 表格列约束
+3. Conditional Enhancement & Format Selection（合并条件触发 + 信息形状选型 + DO/DON'T）
+4. 输出前自检清单（mandatory pre-output check）
+```
+
+### 必需 section 契约
+
+| 输出类型 | 必需 section | 必需表格 | 状态符约束 |
+|---------|-------------|---------|-----------|
+| develop/success | 复审结论行、验证摘要、Changes、Next | 验证摘要表 | ✓ 仅当全部 passed |
+| develop/partial | 未完成项、验证摘要、Changes、Next | 未完成项表 + 验证摘要表 | 必须 ! |
+| develop/quick-fix | 验证摘要、Changes、Next | 验证摘要简表 | ✓ 仅当全部 passed |
+| analyze/success | 假设与前提、信息缺口、下一步理由、Changes、Next | — | — |
+| analyze/question | 问题列表、Next | — | 必须 ? |
+| design/summary | 评分行、Changes、Next | — | — |
+| consult | Changes、Next | — (adaptive) | — |
+
+表格列约束：只展示当前场景有信息量的列。success 场景下全部 `reason_code=—` 时，可省略该列。列省略只影响最终展示，不影响内部验证判断。
+
+### Conditional Enhancement & Format Selection
+
+合并条件触发与信息形状选型为单一决策表：
+
+| 触发条件 | 推荐表达 | 典型场景 |
+|---------|---------|---------|
+| 多项对比/取舍（>2 方案） | 表格 | 方案取舍、风险对比、宿主能力对比 |
+| 流程/调用/生命周期 | 编号序列 | SDK 流程、gate → route → handoff |
+| 文件/组件/模块组成 | 树状结构 | 组件拆分、模块结构、方案文件组织 |
+| 评分维度需可见化 | 评分表 | analyze 评分 |
+| 简单问答/状态确认 | 保持简洁 | 单一问题回答、状态确认 |
+
+约束：同一回复最多选一种主结构，避免表格 + 树 + 流程叠加。
+
+附 DO/DON'T 短规则（3+3 条），防止漏增强和过度增强。
+
+## develop 自检子节
+
+在 `develop-rules.md` 步骤 2.5（两阶段复审）后追加"输出前自检"：
+
+```
+### 2.6 输出前自检
+
+完成两阶段复审后，输出最终摘要前必须检查：
+
+1. 状态符是否正确：`✓` 仅当全部 `result=passed` 且 `reason_code=—`；否则必须 `!`。
+2. 必需表格是否存在：success/partial 必须有验证摘要表；partial 必须有未完成项表。
+3. 复审结论行是否存在：success 必须有 `spec_compliance` + `code_quality` 各一句依据。
+4. footer 是否完整：`Changes:` + `Next:` 必须存在。
+```
+
+## golden snapshot 结构断言
+
+在 `test_golden_snapshots.py` 中新增两组测试：
+
+**1. 模板结构断言**（验证模板文件包含 required markers）：
+
+```python
+@pytest.mark.parametrize("template_path,required_markers", [
+    ("develop/assets/output-success.md", ["| 任务 |", "| 验证来源 |", "Changes:", "Next:"]),
+    ("develop/assets/output-partial.md", ["| 任务 |", "| 阻塞原因 |", "| 验证来源 |", "Changes:", "Next:"]),
+    ("develop/assets/output-quick-fix.md", ["| 验证来源 |", "Changes:", "Next:"]),
+    ("analyze/assets/success-output.md", ["假设与前提:", "已识别信息缺口:", "Changes:", "Next:"]),
+    ("design/assets/output-summary.md", ["方案质量:", "落地就绪:", "Changes:", "Next:"]),
+])
+def test_template_required_sections(template_path, required_markers):
+    ...
+```
+
+**2. 内联断言**（验证 output-contract.md 出现在各宿主的 rendered prompt 中）：
+
+直接检查 render_single_file() 输出是否包含 `output-contract.md` 的关键标记。
+
+覆盖 ZH + EN 两个语言目录。
+
+## 不变项
+
+- 各 skill 执行流程不变
+- gate/routing 摘要渲染器不变
+- 不新增脚本、不新增配置文件
+- develop 模板内容不变（只加规则引用和自检）
diff --git a/.sopify-skills/history/2026-05/20260528_output_contract_enforcement/tasks.md b/.sopify-skills/history/2026-05/20260528_output_contract_enforcement/tasks.md
@@ -0,0 +1,24 @@
+# 任务清单: 输出契约提示层与模板结构约束
+
+目录: `.sopify-skills/plan/20260528_output_contract_enforcement/`
+
+> **范围说明**：覆盖 `skills/zh/` + `skills/en/`（ZH/EN 对称）。0 脚本、0 配置、0 runtime 改动。
+
+## 1. 输出契约参考文档
+
+- [x] 1.1 创建 `skills/zh/skills/sopify/references/output-contract.md`：必需 section 契约表 + 条件增强触发规则 + 输出前自检清单 + 输出路径说明
+- [x] 1.2 创建 `skills/en/skills/sopify/references/output-contract.md`（EN 对等）
+- [x] 1.3 在 `analyze/SKILL.md` 资源导航加引用行（ZH + EN）
+- [x] 1.4 在 `design/SKILL.md` 资源导航加引用行（ZH + EN）
+- [x] 1.5 在 `develop/SKILL.md` 资源导航加引用行（ZH + EN）
+
+## 2. develop 自检规则
+
+- [x] 2.1 在 `develop/references/develop-rules.md` 步骤 2.5 后追加 2.6 输出前自检子节（ZH + EN）
+
+## 3. 测试
+
+- [x] 3.1 在 `tests/test_golden_snapshots.py` 新增模板结构断言测试（验证 required markers 存在）
+- [x] 3.2 在 `tests/test_golden_snapshots.py` 新增内联断言（验证 output-contract.md 被 rendered prompt 包含）
+- [x] 3.3 更新 `tests/golden-snapshots.json`（hash 因 SKILL.md 加引用行而变化）
+- [x] 3.4 运行 `pytest tests/test_golden_snapshots.py` 全部通过
diff --git a/.sopify-skills/history/index.md b/.sopify-skills/history/index.md
@@ -4,6 +4,7 @@
 
 ## 索引
 
+- `2026-05-28` [`20260528_output_contract_enforcement`](2026-05/20260528_output_contract_enforcement/) - standard - 输出契约提示层与模板结构约束: output-contract.md（ZH+EN）定义必需 section / 表格列约束 / 条件增强与表达选型（DO/DON'T）/ 输出前自检，6 SKILL.md 引用行 + develop §2.6 自检子节 + 16 项 golden snapshot 结构与内联断言
 - `2026-05-27` [`20260527_skill_writing_quality`](2026-05/20260527_skill_writing_quality/) - standard - Skill 写作质量收敛: 共享写作 DNA（6 规则 ZH+EN）+ 4 输出模板 v2 重写（验证表/reason_code/复审依据/状态符硬约束）+ 3 SKILL.md 哲学声明 + human_action_required root_cause + render 管线顶层 references/ inline 修复
 - `2026-05-27` [`20260526_pre_launch_host_and_bundle_unification`](2026-05/20260526_pre_launch_host_and_bundle_unification/) - standard - 推广前宿主分发与 Bundle 统一: 4 套宿主语言内容→2 套语言源 + 安装时 host 渲染，Copilot 纳入统一 registry，runtime_bundle→sopify_bundle 命名收口，三宿主双语言端到端验证通过（6 条安装路径 + 8 项 golden snapshot 全绿），旧宿主目录删除
 - `2026-05-26` [`20260522_runtime_slimming_kernel_extraction`](2026-05/20260522_runtime_slimming_kernel_extraction/) - standard - 任务清单: Runtime Slimming — Orchestration Kernel Extraction

diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -6,6 +6,36 @@ Format: Summary → Changed → Plan Packages. File-level details live in `git l
 
 ## [Unreleased]
 
+## [2026-05-28.102531] - 2026-05-28
+
+### Summary
+
+- Updated 1 active plan package(s); Changes across: Tests, Changed.
+
+### Changed
+
+- **Tests**: Updated automated coverage (1 files)
+- **Changed**: Updated project files (2 files)
+
+### Plan Packages
+
+- `20260528_output_contract_enforcement` (active)
+
+## [2026-05-28.101947] - 2026-05-28
+
+### Summary
+
+- Updated 1 active plan package(s); Changes across: Tests, Changed.
+
+### Changed
+
+- **Tests**: Updated automated coverage (2 files)
+- **Changed**: Updated project files (10 files)
+
+### Plan Packages
+
+- `20260528_output_contract_enforcement` (active)
+
 ## [2026-05-27.220559] - 2026-05-27
 
 ### Summary

diff --git a/README.md b/README.md
@@ -8,7 +8,7 @@
 
 [![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](./LICENSE)
 [![Docs](https://img.shields.io/badge/docs-CC%20BY%204.0-green.svg)](./LICENSE-docs)
-[![Version](https://img.shields.io/badge/version-2026--05--27.220559-orange.svg)](#version-history)
+[![Version](https://img.shields.io/badge/version-2026--05--28.102531-orange.svg)](#version-history)
 [![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](./CONTRIBUTING.md)
 
 English · [简体中文](./README.zh-CN.md) · [Quick Start](#quick-start) · [Contributors](./CONTRIBUTORS.md)

diff --git a/README.zh-CN.md b/README.zh-CN.md
@@ -8,7 +8,7 @@
 
 [![许可证](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](./LICENSE)
 [![文档](https://img.shields.io/badge/docs-CC%20BY%204.0-green.svg)](./LICENSE-docs)
-[![版本](https://img.shields.io/badge/version-2026--05--27.220559-orange.svg)](#版本历史)
+[![版本](https://img.shields.io/badge/version-2026--05--28.102531-orange.svg)](#版本历史)
 [![欢迎PR](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](./CONTRIBUTING_CN.md)
 
 [English](./README.md) · 简体中文 · [快速开始](#快速开始) · [贡献者](./CONTRIBUTORS.md)

diff --git a/skills/en/header.md.template b/skills/en/header.md.template
@@ -1,5 +1,5 @@
 <!-- bootstrap: lang=en-US; encoding=UTF-8 -->
-<!-- SOPIFY_VERSION: 2026-05-27.220559 -->
+<!-- SOPIFY_VERSION: 2026-05-28.102531 -->
 <!-- ARCHITECTURE: Adaptive Workflow + Layered Rules -->
 
 # Sopify - Adaptive AI Programming Assistant

diff --git a/skills/en/skills/sopify/analyze/SKILL.md b/skills/en/skills/sopify/analyze/SKILL.md
@@ -26,6 +26,7 @@ description: Analyze phase entry. Aggregates scoring, follow-up, and scope-check
 
 - Long rules: `references/analyze-rules.md`
 - Shared writing standards: `../references/shared-writing-dna.md` (apply to all output)
+- Output contract: `../references/output-contract.md` (required sections, conditional enhancement, self-check)
 - Follow-up template: `assets/question-output.md`
 - Success template: `assets/success-output.md`
 - Deterministic scoring script: `scripts/score_requirement.py`

diff --git a/skills/en/skills/sopify/design/SKILL.md b/skills/en/skills/sopify/design/SKILL.md
@@ -24,6 +24,7 @@ description: Design phase entry. Aggregates plan-level selection, task breakdown
 
 - Long rules: `references/design-rules.md`
 - Shared writing standards: `../references/shared-writing-dna.md` (apply to all output)
+- Output contract: `../references/output-contract.md` (required sections, conditional enhancement, self-check)
 - Templates: `assets/*.md`
 - Deterministic level selector: `scripts/select_plan_level.py`
 

diff --git a/skills/en/skills/sopify/develop/SKILL.md b/skills/en/skills/sopify/develop/SKILL.md
@@ -25,6 +25,7 @@ description: Develop phase entry; routes task execution, state updates, KB sync,
 
 - Long rules: `references/develop-rules.md`
 - Shared writing standards: `../references/shared-writing-dna.md` (apply to all output)
+- Output contract: `../references/output-contract.md` (required sections, conditional enhancement, self-check)
 - Output templates: `assets/*.md`
 - Task extraction script: `scripts/extract_pending_tasks.py`
 

diff --git a/skills/en/skills/sopify/develop/references/develop-rules.md b/skills/en/skills/sopify/develop/references/develop-rules.md
@@ -149,6 +149,15 @@ Output status symbol constraint:
 - `✓` is allowed only when every verification row has `result=passed` and `reason_code=—`
 - Otherwise `!` must be used
 
+### 2.6 Pre-output self-check
+
+After completing the two-stage review, before outputting the final summary:
+
+1. Status symbol correct: `✓` only when all `result=passed` and `reason_code=—`; otherwise `!`.
+2. Required tables present: success/partial must include a verification summary table; partial must include an incomplete items table.
+3. Review conclusion line present: success must include `spec_compliance` + `code_quality` each with one sentence of evidence.
+4. Footer complete: `Changes:` + `Next:` must be present.
+
 ## Step 3: Post-develop advisory review
 
 After all tasks pass the quality loop and two-stage review, if the workspace `.agents/skills/` contains an advisory skill whose triggers include `post_develop`, execute a single post-develop advisory review following its SKILL.md. Currently only CrossReview Phase 4a is included in this path.

diff --git a/skills/en/skills/sopify/references/output-contract.md b/skills/en/skills/sopify/references/output-contract.md
@@ -0,0 +1,56 @@
+# Sopify Output Contract
+
+All stages (analyze / design / develop / consult) must follow this contract for final replies. Each section governs one output decision dimension.
+
+## 1. Output Path Responsibilities
+
+- **Gate summary**: Routing status from the gate/routing phase. Contains phase title, status line, Context, Changes, Next. Does not contain verification tables, review conclusions, or other skill-level content.
+- **Host completion reply**: The final summary after skill execution. Must follow the corresponding template, including required sections and enhancements when triggered.
+- Gate summary ≠ final reply. The gate tells the host what to do; the host outputs results per template after completing the work.
+
+## 2. Required Sections
+
+| Output Type | Required Sections | Required Tables | Status Symbol |
+|------------|------------------|----------------|---------------|
+| develop/success | Review conclusion, verification summary, Changes, Next | Verification table | ✓ only when all passed |
+| develop/partial | Incomplete items, verification summary, Changes, Next | Incomplete table + verification table | Must use ! |
+| develop/quick-fix | Verification summary, Changes, Next | Simplified verification table | ✓ only when all passed |
+| analyze/success | Assumptions, identified gaps, next-step rationale, Changes, Next | — | — |
+| analyze/question | Question list, Next | — | Must use ? |
+| design/summary | Score lines, Changes, Next | — | — |
+| consult | Changes, Next | — (adaptive) | — |
+
+Table column rule: only show columns that carry meaningful information for the current scenario. When all `reason_code=—` in a success scenario, that column may be omitted. Column omission only affects final display, not internal verification logic.
+
+## 3. Conditional Enhancement & Format Selection
+
+Do not force structure on every scenario. Decide whether and how to enhance based on information shape and trigger conditions:
+
+| Trigger Condition | Recommended Format | Typical Scenarios |
+|------------------|-------------------|-------------------|
+| Multi-item comparison/tradeoff (>2 options) | Table | Solution tradeoffs, risk comparison, host capability comparison |
+| Flow/invocation/lifecycle | Numbered sequence | SDK flows, gate → route → handoff |
+| File/component/module composition | Tree structure | Component breakdown, module structure, plan file organization |
+| Score dimensions need visibility | Score table | analyze scoring |
+| Simple Q&A/status confirmation | Keep concise | Single question answers, status confirmations |
+
+Constraint: use at most one primary structure per reply; avoid stacking table + tree + flow.
+
+**DO:**
+- Use a comparison table when multi-option tradeoffs are present — make differences visible at a glance
+- Simplify verification summary on success when all passed — omit columns with no information
+- Keep plain text when information shape does not match any structure
+
+**DON'T:**
+- Multi-option tradeoffs without comparison structure = missed enhancement
+- Forcing tables on simple Q&A = over-enhancement
+- Mixing two or more primary structures in one reply = cognitive overload
+
+## 4. Pre-output Self-check
+
+Before outputting the final reply, verify:
+
+1. Required sections present: check §2 for the current output type.
+2. Status symbol correct: `✓` only when all `result=passed` and `reason_code=—`; otherwise `!`.
+3. Footer complete: `Changes:` + `Next:` must be present.
+4. Conditional enhancement applied: if the reply meets a §3 trigger condition, use the corresponding structured format.
diff --git a/skills/zh/header.md.template b/skills/zh/header.md.template
@@ -1,5 +1,5 @@
 <!-- bootstrap: lang=zh-CN; encoding=UTF-8 -->
-<!-- SOPIFY_VERSION: 2026-05-27.220559 -->
+<!-- SOPIFY_VERSION: 2026-05-28.102531 -->
 <!-- ARCHITECTURE: Adaptive Workflow + Layered Rules -->
 
 # Sopify - 自适应 AI 编程助手

diff --git a/skills/zh/skills/sopify/analyze/SKILL.md b/skills/zh/skills/sopify/analyze/SKILL.md
@@ -26,6 +26,7 @@ description: 需求分析阶段入口；聚合评分、追问与范围判定规
 
 - 长规则：`references/analyze-rules.md`
 - 共享写作规范：`../references/shared-writing-dna.md`（所有输出遵循）
+- 输出契约：`../references/output-contract.md`（必需 section、条件增强、自检）
 - 追问模板：`assets/question-output.md`
 - 达标输出模板：`assets/success-output.md`
 - 确定性评分脚本：`scripts/score_requirement.py`

diff --git a/skills/zh/skills/sopify/design/SKILL.md b/skills/zh/skills/sopify/design/SKILL.md
@@ -24,6 +24,7 @@ description: 方案设计阶段入口；聚合方案分级、任务拆分与方
 
 - 长规则：`references/design-rules.md`
 - 共享写作规范：`../references/shared-writing-dna.md`（所有输出遵循）
+- 输出契约：`../references/output-contract.md`（必需 section、条件增强、自检）
 - 模板：`assets/*.md`
 - 确定性分级脚本：`scripts/select_plan_level.py`