Skip to content

Commit b9e9340

Browse files
Li-SanzeLi-Sanze
committed
feat: add output contract enforcement for all skill stages
- Add output-contract.md (ZH + EN) as shared reference document defining required sections, table column rules, conditional enhancement triggers with DO/DON'T guidelines, and pre-output self-check for all output stages (analyze/design/develop/consult) - Add reference lines to 6 SKILL.md files (3 skills × 2 languages) - Add §2.6 pre-output self-check to develop-rules.md (ZH + EN) - Add 16 new test assertions: 10 template structure checks + 6 three-host inline verification tests - Update 4 golden snapshot hashes - Include plan package for traceability Release-Sync: yes Release-Version: 2026-05-28.102531 Release-Date: 2026-05-28
1 parent 1e2068e commit b9e9340

20 files changed

Lines changed: 448 additions & 12 deletions

File tree

‎.sopify-skills/plan/20260528_output_contract_enforcement/background.md‎

Lines changed: 55 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,55 @@
1+
# 变更提案: 输出契约提示层与模板结构约束
2+
3+
## 需求背景
4+
5+
Sopify 有 6 个输出模板（analyze ×2、design ×1、develop ×3），但缺少两层保障：
6+
7+
1. **无契约提示**：模板定义了验证表格、必需 section，但宿主没有显式自检规则，遵守与否全凭 LLM 自觉。
8+
2. **无条件增强指引**：analyze/design/consult 场景在复杂情况下应升级为表格/对比结构，但模板是静态的，没有"何时增强"的触发规则。
9+
3. **consult 零模板**：咨询问答是最高频场景之一，但没有任何输出指引。
10+
11+
根因：`20260527_skill_writing_quality` 修复了模板内容和 render 管线，但未补宿主侧自检规则和条件增强指引。
12+
13+
**runtime 背景**：runtime 正在逐步退场。本期不追加 gate/routing 渲染器改动、不实现 bridge validator。所有增强走 prompt/skill/template 层，对所有宿主（Copilot/Codex/Claude）统一生效。
14+
15+
评分:
16+
- 方案质量: 8/10
17+
- 落地就绪: 9/10
18+
19+
评分理由:
20+
- 优点: 纯 prompt 层改动，不侵入 runtime、不新增配置/脚本，所有宿主统一受益
21+
- 扣分: 提示层无法 100% 强制 LLM 遵守，真正的机器强制需后续 bridge/schema（列为显式债务）
22+
23+
## 变更内容
24+
25+
1. **新增输出契约参考文档**：`references/output-contract.md`，定义每类输出的 required sections、表格列约束、条件增强与表达选型（含 DO/DON'T）、输出前自检清单。通过 render 管线内联到所有宿主 prompt。
26+
2. **补 develop 自检规则**：在 `develop-rules.md` 中加输出前自检子节。
27+
3. **补 golden snapshot 结构断言**：在 `test_golden_snapshots.py` 中加模板结构验证 + 验证 output-contract.md 被内联。
28+
29+
## 影响范围
30+
31+
- 新增: `skills/{zh,en}/skills/sopify/references/output-contract.md`（ZH + EN）
32+
- 修改: `skills/{zh,en}/skills/sopify/analyze/SKILL.md`（加引用行）
33+
- 修改: `skills/{zh,en}/skills/sopify/design/SKILL.md`（加引用行）
34+
- 修改: `skills/{zh,en}/skills/sopify/develop/SKILL.md`（加引用行）
35+
- 修改: `skills/{zh,en}/skills/sopify/develop/references/develop-rules.md`（加自检子节）
36+
- 修改: `tests/test_golden_snapshots.py`（加结构断言）
37+
- 修改: `tests/golden-snapshots.json`（hash 更新）
38+
39+
## 风险评估
40+
41+
- 风险: 结构断言过严，正常模板改动频繁导致测试脆弱
42+
- 缓解: 结构断言只验必需 section 存在（如表头 `| 任务 |`、`Changes:`、`Next:`），不验具体内容；表格列允许场景化省略
43+
44+
## 明确不做
45+
46+
- 不修改 gate/routing 渲染器（runtime 正在退场，gate 输出职责不变）
47+
- 不实现 bridge validator 代码（列为后续显式债务）
48+
- 不新增 `output_contract.yaml` 配置文件
49+
- 不给 consult 创建独立 skill 目录
50+
- 不对简单问答强制表格
51+
- 不修改 `protocol.md`（输出路径职责写在 output-contract.md 即可，不需要另开一个文件）
52+
53+
## 显式后续债务
54+
55+
- bridge/schema validator：当 host bridge 落地时，可基于 output-contract.md 的 required sections 做 advisory 校验。本期只留文档化设计意图，不写代码。

‎.sopify-skills/plan/20260528_output_contract_enforcement/design.md‎

Lines changed: 103 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,103 @@
1+
# 技术设计: 输出契约提示层与模板结构约束
2+
3+
## 设计原则
4+
5+
所有增强走 prompt/skill/template 层，不碰 runtime。原因：
6+
- runtime 正在退场，不应追加投入
7+
- prompt 层改动对 Copilot/Codex/Claude 统一生效
8+
- 提示层无法 100% 强制 LLM，但可以显著提高一致性
9+
10+
## 输出契约参考文档
11+
12+
### 定位
13+
14+
一个共享参考文档（类似 `shared-writing-dna.md`），定义所有阶段输出的 required/adaptive 规则。通过 render 管线内联到所有宿主 prompt。
15+
16+
落点：`skills/zh/skills/sopify/references/output-contract.md`
17+
18+
render 管线已在 `20260527` 修复中支持顶层 `references/` 内联，所以新文件自动进入所有宿主的 managed block。
19+
20+
### 内容结构（最终 4 section）
21+
22+
```
23+
1. 输出路径说明（gate 摘要 ≠ 最终回复，不写死 runtime 文件名）
24+
2. 必需 section 契约表（per output type）+ 表格列约束
25+
3. Conditional Enhancement & Format Selection（合并条件触发 + 信息形状选型 + DO/DON'T）
26+
4. 输出前自检清单（mandatory pre-output check）
27+
```
28+
29+
### 必需 section 契约
30+
31+
| 输出类型 | 必需 section | 必需表格 | 状态符约束 |
32+
|---------|-------------|---------|-----------|
33+
| develop/success | 复审结论行、验证摘要、Changes、Next | 验证摘要表 | ✓ 仅当全部 passed |
34+
| develop/partial | 未完成项、验证摘要、Changes、Next | 未完成项表 + 验证摘要表 | 必须 ! |
35+
| develop/quick-fix | 验证摘要、Changes、Next | 验证摘要简表 | ✓ 仅当全部 passed |
36+
| analyze/success | 假设与前提、信息缺口、下一步理由、Changes、Next | — | — |
37+
| analyze/question | 问题列表、Next | — | 必须 ? |
38+
| design/summary | 评分行、Changes、Next | — | — |
39+
| consult | Changes、Next | — (adaptive) | — |
40+
41+
表格列约束：只展示当前场景有信息量的列。success 场景下全部 `reason_code=—` 时，可省略该列。列省略只影响最终展示，不影响内部验证判断。
42+
43+
### Conditional Enhancement & Format Selection
44+
45+
合并条件触发与信息形状选型为单一决策表：
46+
47+
| 触发条件 | 推荐表达 | 典型场景 |
48+
|---------|---------|---------|
49+
| 多项对比/取舍（>2 方案） | 表格 | 方案取舍、风险对比、宿主能力对比 |
50+
| 流程/调用/生命周期 | 编号序列 | SDK 流程、gate → route → handoff |
51+
| 文件/组件/模块组成 | 树状结构 | 组件拆分、模块结构、方案文件组织 |
52+
| 评分维度需可见化 | 评分表 | analyze 评分 |
53+
| 简单问答/状态确认 | 保持简洁 | 单一问题回答、状态确认 |
54+
55+
约束：同一回复最多选一种主结构，避免表格 + 树 + 流程叠加。
56+
57+
附 DO/DON'T 短规则（3+3 条），防止漏增强和过度增强。
58+
59+
## develop 自检子节
60+
61+
在 `develop-rules.md` 步骤 2.5（两阶段复审）后追加"输出前自检"：
62+
63+
```
64+
### 2.6 输出前自检
65+
66+
完成两阶段复审后，输出最终摘要前必须检查：
67+
68+
1. 状态符是否正确：`✓` 仅当全部 `result=passed` 且 `reason_code=—`；否则必须 `!`。
69+
2. 必需表格是否存在：success/partial 必须有验证摘要表；partial 必须有未完成项表。
70+
3. 复审结论行是否存在：success 必须有 `spec_compliance` + `code_quality` 各一句依据。
71+
4. footer 是否完整：`Changes:` + `Next:` 必须存在。
72+
```
73+
74+
## golden snapshot 结构断言
75+
76+
在 `test_golden_snapshots.py` 中新增两组测试：
77+
78+
**1. 模板结构断言**（验证模板文件包含 required markers）：
79+
80+
```python
81+
@pytest.mark.parametrize("template_path,required_markers", [
82+
("develop/assets/output-success.md", ["| 任务 |", "| 验证来源 |", "Changes:", "Next:"]),
83+
("develop/assets/output-partial.md", ["| 任务 |", "| 阻塞原因 |", "| 验证来源 |", "Changes:", "Next:"]),
84+
("develop/assets/output-quick-fix.md", ["| 验证来源 |", "Changes:", "Next:"]),
85+
("analyze/assets/success-output.md", ["假设与前提:", "已识别信息缺口:", "Changes:", "Next:"]),
86+
("design/assets/output-summary.md", ["方案质量:", "落地就绪:", "Changes:", "Next:"]),
87+
])
88+
def test_template_required_sections(template_path, required_markers):
89+
...
90+
```
91+
92+
**2. 内联断言**（验证 output-contract.md 出现在各宿主的 rendered prompt 中）：
93+
94+
直接检查 render_single_file() 输出是否包含 `output-contract.md` 的关键标记。
95+
96+
覆盖 ZH + EN 两个语言目录。
97+
98+
## 不变项
99+
100+
- 各 skill 执行流程不变
101+
- gate/routing 摘要渲染器不变
102+
- 不新增脚本、不新增配置文件
103+
- develop 模板内容不变（只加规则引用和自检）

‎.sopify-skills/plan/20260528_output_contract_enforcement/tasks.md‎

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
# 任务清单: 输出契约提示层与模板结构约束
2+
3+
目录: `.sopify-skills/plan/20260528_output_contract_enforcement/`
4+
5+
> **范围说明**：覆盖 `skills/zh/` + `skills/en/`（ZH/EN 对称）。0 脚本、0 配置、0 runtime 改动。
6+
7+
## 1. 输出契约参考文档
8+
9+
- [x] 1.1 创建 `skills/zh/skills/sopify/references/output-contract.md`：必需 section 契约表 + 条件增强触发规则 + 输出前自检清单 + 输出路径说明
10+
- [x] 1.2 创建 `skills/en/skills/sopify/references/output-contract.md`（EN 对等）
11+
- [x] 1.3 在 `analyze/SKILL.md` 资源导航加引用行（ZH + EN）
12+
- [x] 1.4 在 `design/SKILL.md` 资源导航加引用行（ZH + EN）
13+
- [x] 1.5 在 `develop/SKILL.md` 资源导航加引用行（ZH + EN）
14+
15+
## 2. develop 自检规则
16+
17+
- [x] 2.1 在 `develop/references/develop-rules.md` 步骤 2.5 后追加 2.6 输出前自检子节（ZH + EN）
18+
19+
## 3. 测试
20+
21+
- [x] 3.1 在 `tests/test_golden_snapshots.py` 新增模板结构断言测试（验证 required markers 存在）
22+
- [x] 3.2 在 `tests/test_golden_snapshots.py` 新增内联断言（验证 output-contract.md 被 rendered prompt 包含）
23+
- [x] 3.3 更新 `tests/golden-snapshots.json`（hash 因 SKILL.md 加引用行而变化）
24+
- [x] 3.4 运行 `pytest tests/test_golden_snapshots.py` 全部通过

‎CHANGELOG.md‎

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,36 @@ Format: Summary → Changed → Plan Packages. File-level details live in `git l
66

77
## [Unreleased]
88

9+
## [2026-05-28.102531] - 2026-05-28
10+
11+
### Summary
12+
13+
- Updated 1 active plan package(s); Changes across: Tests, Changed.
14+
15+
### Changed
16+
17+
- **Tests**: Updated automated coverage (1 files)
18+
- **Changed**: Updated project files (2 files)
19+
20+
### Plan Packages
21+
22+
- `20260528_output_contract_enforcement` (active)
23+
24+
## [2026-05-28.101947] - 2026-05-28
25+
26+
### Summary
27+
28+
- Updated 1 active plan package(s); Changes across: Tests, Changed.
29+
30+
### Changed
31+
32+
- **Tests**: Updated automated coverage (2 files)
33+
- **Changed**: Updated project files (10 files)
34+
35+
### Plan Packages
36+
37+
- `20260528_output_contract_enforcement` (active)
38+
939
## [2026-05-27.220559] - 2026-05-27
1040

1141
### Summary

‎README.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -8,7 +8,7 @@
88

99
[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](./LICENSE)
1010
[![Docs](https://img.shields.io/badge/docs-CC%20BY%204.0-green.svg)](./LICENSE-docs)
11-
[![Version](https://img.shields.io/badge/version-2026--05--27.220559-orange.svg)](#version-history)
11+
[![Version](https://img.shields.io/badge/version-2026--05--28.102531-orange.svg)](#version-history)
1212
[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](./CONTRIBUTING.md)
1313

1414
English · [简体中文](./README.zh-CN.md) · [Quick Start](#quick-start) · [Contributors](./CONTRIBUTORS.md)

‎README.zh-CN.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -8,7 +8,7 @@
88

99
[![许可证](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](./LICENSE)
1010
[![文档](https://img.shields.io/badge/docs-CC%20BY%204.0-green.svg)](./LICENSE-docs)
11-
[![版本](https://img.shields.io/badge/version-2026--05--27.220559-orange.svg)](#版本历史)
11+
[![版本](https://img.shields.io/badge/version-2026--05--28.102531-orange.svg)](#版本历史)
1212
[![欢迎PR](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](./CONTRIBUTING_CN.md)
1313

1414
[English](./README.md) · 简体中文 · [快速开始](#快速开始) · [贡献者](./CONTRIBUTORS.md)

‎skills/en/header.md.template‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
<!-- bootstrap: lang=en-US; encoding=UTF-8 -->
2-
<!-- SOPIFY_VERSION: 2026-05-27.220559 -->
2+
<!-- SOPIFY_VERSION: 2026-05-28.102531 -->
33
<!-- ARCHITECTURE: Adaptive Workflow + Layered Rules -->
44

55
# Sopify - Adaptive AI Programming Assistant

‎skills/en/skills/sopify/analyze/SKILL.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -26,6 +26,7 @@ description: Analyze phase entry. Aggregates scoring, follow-up, and scope-check
2626

2727
- Long rules: `references/analyze-rules.md`
2828
- Shared writing standards: `../references/shared-writing-dna.md` (apply to all output)
29+
- Output contract: `../references/output-contract.md` (required sections, conditional enhancement, self-check)
2930
- Follow-up template: `assets/question-output.md`
3031
- Success template: `assets/success-output.md`
3132
- Deterministic scoring script: `scripts/score_requirement.py`

‎skills/en/skills/sopify/design/SKILL.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -24,6 +24,7 @@ description: Design phase entry. Aggregates plan-level selection, task breakdown
2424

2525
- Long rules: `references/design-rules.md`
2626
- Shared writing standards: `../references/shared-writing-dna.md` (apply to all output)
27+
- Output contract: `../references/output-contract.md` (required sections, conditional enhancement, self-check)
2728
- Templates: `assets/*.md`
2829
- Deterministic level selector: `scripts/select_plan_level.py`
2930

‎skills/en/skills/sopify/develop/SKILL.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -25,6 +25,7 @@ description: Develop phase entry; routes task execution, state updates, KB sync,
2525

2626
- Long rules: `references/develop-rules.md`
2727
- Shared writing standards: `../references/shared-writing-dna.md` (apply to all output)
28+
- Output contract: `../references/output-contract.md` (required sections, conditional enhancement, self-check)
2829
- Output templates: `assets/*.md`
2930
- Task extraction script: `scripts/extract_pending_tasks.py`
3031

0 commit comments

Comments
 (0)