Skip to content

Commit c18f25b

Browse files
Li-SanzeLi-Sanze
authored
Merge pull request #22 from evidentloop/plan/p15-advance-slices
Plan/p15 advance slices
2 parents 3a09a33 + 6238e9c commit c18f25b

25 files changed

Lines changed: 587 additions & 2217 deletions

‎.sopify-skills/blueprint/README.md‎

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -14,7 +14,6 @@
1414

1515
<!-- sopify:auto:focus:start -->
1616
- 当前活动 plan：暂无。
17-
- 当前焦点：P1.5 先行切片（Convention 入口 + Compliance Phase 1）与 P1.5→P2 Verifier 桥接，见 `tasks.md`。
1817
- history 归档：已可用；最近归档为 `../history/2026-05/20260504_subject_identity_binding`。
1918
<!-- sopify:auto:focus:end -->
2019

‎.sopify-skills/blueprint/tasks.md‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -68,9 +68,9 @@ ADR-017 的直系后续。不要求落地完整 ExecutionAuthorizationReceipt
6868

6969
**可先行切片（presentation-only / protocol 下界验证，不改 machine contract）：**
7070

71-
- **Convention 入口兑现（窄切片）**：README 增加 non-runtime quickstart 路径（基于 protocol.md §4 样例 A）；将 protocol.md §5 合规检查清单转化为面向外部宿主开发者的接入指南段落。不新增 CLI 面（不做 `sopify init --minimal`），用文档/模板/示例目录兑现。验收：外部宿主开发者只读 README + protocol.md 即可完成最小合规（≤3 步）
72-
- **Protocol Compliance Suite Phase 1**：在 `evals/` 或 `tests/protocol/` 建立最小合规断言套件，严格对齐 protocol.md §5（能读 blueprint、能写方案包、能归档 + receipt）。实现方式：文件结构存在性 + 必需字段断言（脚本级）。不覆盖 knowledge_sync / blueprint writeback（Convention 下界中是"推荐"不是必选）。不做 headless behavioral test（那是长期方向）。验收：一组可自动化运行的断言，输入 `.sopify-skills/` 目录，输出 pass/fail
73-
- **低风险辅助层预清理**：清理不改变 machine truth 的非核心增强模块（例如单点引用、独立测试覆盖的体验增强层）。不碰决策资产、预检契约、恢复语义、上下文骨架、gate/state/handoff 主链。具体文件清单和执行顺序由当期方案包定义。验收：删除后全量测试通过 + 无 import 断裂
71+
- ✅ **Convention 入口兑现（窄切片）**：README 增加 non-runtime quickstart 路径（基于 protocol.md §4 样例 A）；将 protocol.md §5 合规检查清单转化为面向外部宿主开发者的接入指南段落。不新增 CLI 面（不做 `sopify init --minimal`），用文档/模板/示例目录兑现。验收：外部宿主开发者只读 README + protocol.md 即可完成最小合规（≤3 步）
72+
- ✅ **Protocol Compliance Suite Phase 1**：在 `tests/protocol/` 建立最小合规断言套件，严格对齐 protocol.md §5（能读 blueprint、能写方案包、能归档 + receipt）。实现方式：文件结构存在性 + 必需字段断言（脚本级）。验收：16 项断言全部通过
73+
- ✅ **低风险辅助层预清理（~summary surface 全链路删除）**：删除 `~summary` 路由、`daily_summary` 模块、`_models/summary.py`、output/engine/router 中所有 summary 分支及相关测试。验收：全量测试通过（595 passed） + 6 组 grep 模式零残留 + 净删 2,207 行
7474

7575
**P1.5→P2 桥接切片（涉及 protocol 层契约升格，需 P1.5 授权脊柱稳定后执行）：**
7676

‎.sopify-skills/plan/20260505_p15_advance_slices/background.md‎

Lines changed: 37 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,37 @@
1+
# 变更提案: P1.5 先行切片（Convention 入口 + Compliance Suite + 辅助层预清理）
2+
3+
## 需求背景
4+
5+
P1 Subject Identity Binding 已完成（92 tests green，归档于 `history/2026-05/20260504_subject_identity_binding`）。蓝图 `tasks.md` P1.5 段落登记了三项可先行切片，不受 P1.5 主体（Execution Authorization Spine）的前置约束，可立即执行。
6+
7+
三项缺口：
8+
9+
1. **Convention 入口缺失**：README 只有 runtime 安装路径（`README.md:47-145`）。外部宿主开发者无法通过 README 找到 non-runtime quickstart。protocol.md §4 已有样例、§5 已有合规清单，但 README 未串联引用。
10+
2. **Protocol 合规测试不存在**：`tests/protocol/` 目录不存在。protocol.md §5 定义了 6 条最小合规项，但没有可自动运行的断言。现有 92 个测试全部绑定 runtime 实现，不独立于 runtime 验证协议合规性。
11+
3. **daily_summary 体验增强层**：`runtime/daily_summary.py`（1,133 行）是非核心增强模块，蓝图已确认为低风险预清理首刀候选。
12+
13+
评分:
14+
- 方案质量: 8/10
15+
- 落地就绪: 8/10
16+
17+
评分理由:
18+
- 优点: 三个切片边界清晰、均不改 machine contract、有明确验收标准
19+
- 扣分: daily_summary 依赖图比最初分析更宽（涉及 output.py、_models/summary.py、test_support），清理范围需精确控制
20+
21+
## Plan Intake Checklist
22+
23+
1. **命中蓝图里程碑**：P1.5 可先行切片（主）；不进入 P1.5 主体
24+
2. **改动性质**：presentation-only + protocol 下界验证 + 非核心模块清理；均不构成 contract acceptance boundary
25+
3. **新增 machine truth**：否 — 不新增/删除/替代 action / route / state / checkpoint / receipt 中任何 machine truth
26+
4. **Legacy surface 影响**：daily_summary 不是 machine truth surface；`_render_daily_summary_output` 在 output.py 中是 daily_summary 专属渲染，删除不影响其他 route 的输出
27+
5. **Core/validator authority 影响**：无
28+
29+
## 影响范围
30+
31+
- 模块: README（文档层）、tests/protocol/（新建）、runtime/daily_summary + 关联引用（删除/清理）、blueprint/（回写）
32+
- 文件: 10+ 文件，横跨 README / tests / runtime / blueprint
33+
34+
## 风险评估
35+
36+
- 风险: daily_summary 的 `_models/summary.py`（473 行，16 个 class）可能被 daily_summary 之外的模块消费
37+
- 缓解: 清理前先验证 `_models/summary.py` 中各 class 的消费方，仅删除 daily_summary 专属 class；若有共用 class 则保留

‎.sopify-skills/plan/20260505_p15_advance_slices/design.md‎

Lines changed: 184 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,184 @@
1+
# 技术设计: P1.5 先行切片
2+
3+
> **定位**：P1.5 可先行切片方案包。三个窄切片串行执行，均不改 machine contract。
4+
> **前置**：P1 已完成；protocol.md §4/§5 已有 Convention 样例和合规清单。
5+
> **目标**：兑现 Convention 入口、建立 Protocol 合规断言、完成 daily_summary 预清理。
6+
7+
---
8+
9+
## 切片 1: Convention 入口兑现
10+
11+
### 现状
12+
13+
| 文件 | 当前 | 目标 |
14+
|------|------|------|
15+
| README.md | 只有 runtime 安装路径（Quick Start → install.sh） | 增加 Convention Mode 入口段落 |
16+
| README.zh-CN.md | 同上 | 中文同步 |
17+
| protocol.md §4 | 4 个生命周期样例（样例 A 是 Convention 正常流） | 不改 |
18+
| protocol.md §5 | 6 条合规检查清单 | 不改 |
19+
20+
### 设计决策
21+
22+
**D1: Convention 入口放在 Quick Start 内部，不单独建章节**
23+
24+
在现有 Quick Start 章节的 Installation 之前或之后，增加 "Convention Mode (No Runtime)" 子段落。引用 protocol.md §4 样例 A 的 3 步路径。不新建顶层章节——Convention 是 Quick Start 的一种模式，不是独立产品。
25+
26+
**D2: 不新增模板文件、不新增 CLI 面**
27+
28+
蓝图明确不做 `sopify init --minimal`。Convention 入口通过 README 文字 + protocol.md 引用兑现。如需示例目录结构，引用 protocol.md §4 而非新建 examples/ 目录。
29+
30+
**D3: 3 步路径的表述对齐 protocol.md §4 样例 A**
31+
32+
1. 读 `blueprint/` 理解项目上下文
33+
2. 在 `plan/` 下创建 plan.md（含 title/scope/approach + 内联 tasks）
34+
3. 归档到 `history/YYYY-MM/` 并生成 receipt.md
35+
36+
合规自检引用 protocol.md §5。
37+
38+
---
39+
40+
## 切片 2: Protocol Compliance Suite Phase 1
41+
42+
### 现状
43+
44+
- `tests/protocol/` 不存在
45+
- `evals/` 只有 3 个 JSON 评估文件（skill_eval_slo/baseline/report），不是协议合规断言
46+
- protocol.md §5 定义了 6 条最小合规项
47+
48+
### 设计决策
49+
50+
**D4: 断言套件放在 `tests/protocol/`，不放 `evals/`**
51+
52+
理由：evals/ 当前承载的是 skill 评估数据（JSON），和协议合规是不同层面。tests/ 下新建 protocol/ 子目录，用 pytest 驱动，与现有 runtime 测试隔离。
53+
54+
**D5: 用 pytest + tmp_path fixture 模拟 `.sopify-skills/` 结构**
55+
56+
不依赖真实项目目录、不依赖 runtime 模块。每个 test case 在 tmp_path 下构建最小 `.sopify-skills/` 目录结构，验证文件存在性 + 必需字段。
57+
58+
这保证了 Compliance Suite 的独立性——任何宿主只要能构建正确目录结构就能通过，不需要跑 Sopify runtime。
59+
60+
**D6: 6 条合规项的断言策略**
61+
62+
| 合规项 | 断言方式 | 级别 |
63+
|--------|---------|------|
64+
| 1. 读取 project.md 并识别项目名 | 文件存在 + 正则匹配 `# ` 标题行 | 必选 |
65+
| 2. 读取 blueprint/ 三件套 | 三文件存在性断言 | 必选 |
66+
| 3. 在 plan/ 下创建方案包 | tmp_path 创建 + 目录结构验证 | 必选 |
67+
| 4. plan.md 必需字段 | 正则/文本搜索 title + scope + approach + tasks 区块 | 必选 |
68+
| 5. 归档 + receipt.md | history/YYYY-MM/ 结构 + receipt.md 存在 | 必选 |
69+
| 6. blueprint 回写 | Phase 1 不断言（Convention 下界中是推荐不是必选） | 推荐 |
70+
71+
**D7: 不做字段 schema 深度解析**
72+
73+
Phase 1 只做文件存在性 + 区块存在性（正则级）。不做 YAML/JSON schema 校验、不做内容语义验证。深度验证是 Phase 2（长期方向）的范围。
74+
75+
---
76+
77+
## 切片 3: 低风险辅助层预清理（daily_summary）
78+
79+
### 依赖图分析（基于真实代码）
80+
81+
```
82+
runtime/daily_summary.py (1,133 行)
83+
├── 被 runtime/engine.py:18 import (build_daily_summary)
84+
│ └── engine.py:1009 调用
85+
├── 被 runtime/output.py:212,689 渲染 (_render_daily_summary_output)
86+
└── 被 tests/ 消费:
87+
├── tests/runtime_test_support.py:47 import (render_daily_summary_markdown)
88+
├── tests/test_runtime_summary.py (175 行, 2 个 test case)
89+
└── tests/test_runtime_engine.py:2338 mock (daily_summary.subprocess.run)
90+
91+
runtime/_models/summary.py (473 行, 16 classes)
92+
├── 被 runtime/models.py:21 re-export
93+
├── 被 runtime/daily_summary.py 消费
94+
└── 可能被其他模块通过 runtime.models 间接消费 → 需清理前验证
95+
```
96+
97+
### 设计决策
98+
99+
**D8: daily_summary.py 整文件删除**
100+
101+
1,133 行全部删除。不保留骨架——没有用户在用，不需要 stub。
102+
103+
**D9: _models/summary.py 需逐 class 验证消费方后再决定**
104+
105+
16 个 class 中，`DailySummaryArtifact` + `SummaryScope` + `SummarySourceWindow` + `SummarySourceRefs` 等 class 大概率是 daily_summary 专属。但 `runtime/models.py` 的 re-export 可能导致其他模块间接引用。
106+
107+
策略：**先 grep 全量消费方，只删仅被 daily_summary 消费的 class**。如果 _models/summary.py 全部 class 都只被 daily_summary 消费，则整文件删除；否则保留共用 class。
108+
109+
**D10: output.py 中 `_render_daily_summary_output` 函数删除**
110+
111+
不只删除 `_render_daily_summary_output`。`output.py` 中与 `summary` route 绑定的 phase label、`next_summary`、`_collect_changes`、`_next_hint`、`_status_symbol`、`_status_message` 等分支都需要同步清理，避免 route 删除后留下只读渲染残面。
112+
113+
**D11: 测试清理范围**
114+
115+
| 文件 | 处理 |
116+
|------|------|
117+
| `tests/test_runtime_summary.py` (175 行) | 整文件删除 |
118+
| `tests/runtime_test_support.py:47` | 删除 `render_daily_summary_markdown` import |
119+
| `tests/test_runtime_engine.py:2338` | 删除 mock patch 行及关联上下文 |
120+
| `tests/test_runtime_router.py:124,131-132` | 删除 `~summary` 分类断言 |
121+
| `tests/test_runtime_gate.py:1947-1959,2380-2390` | 删除 `~summary` route 集成断言 |
122+
123+
说明：`installer.outcome_contract.render_outcome_summary`、`ClarificationState.summary`、`DecisionOption.summary` 等与 `daily_summary` route 无关的引用不在本次删除范围内。
124+
125+
**D12: engine.py 调用点处理**
126+
127+
`engine.py` 不只是一处调用点。需要同步删除：
128+
129+
- `summary` route 的 `last_route` 豁免分支
130+
- `build_daily_summary` 调用分支
131+
- `summary` route 的 handoff 保留分支
132+
- `summary` route 的 phase / skill 映射分支
133+
134+
`router.py` 也需同步删除 `~summary` 命令匹配、`summary` route 支持、以及 capture/decision 相关分支。`runtime/__init__.py` 和 `runtime/models.py` 的 public export / re-export 需一起收口，保证删除后不存在公开 facade 残留。
135+
136+
---
137+
138+
## 文件变更预估
139+
140+
| 切片 | 文件 | 变更类型 | 范围 |
141+
|------|------|---------|------|
142+
| 1 | README.md | 编辑 | Convention Mode 段落 |
143+
| 1 | README.zh-CN.md | 编辑 | 中文同步 |
144+
| 2 | tests/protocol/test_convention_compliance.py | 新建 | 6 条合规断言 |
145+
| 3 | runtime/daily_summary.py | 删除 | 1,133 行 |
146+
| 3 | runtime/router.py | 编辑 | 删除 `~summary` route 入口与相关分支 |
147+
| 3 | runtime/engine.py | 编辑 | 删除 summary route 分支 |
148+
| 3 | runtime/output.py | 编辑 | 删除 summary route 全部专属分支 |
149+
| 3 | runtime/__init__.py | 编辑 | 删除 `DailySummaryArtifact` public export |
150+
| 3 | runtime/_models/summary.py | 编辑/删除 | 视消费方验证结果 |
151+
| 3 | runtime/models.py | 编辑 | 清理 re-export |
152+
| 3 | tests/test_runtime_summary.py | 删除 | 175 行 |
153+
| 3 | tests/runtime_test_support.py | 编辑 | 删除 import |
154+
| 3 | tests/test_runtime_engine.py | 编辑 | 删除 mock 行 |
155+
| 3 | tests/test_runtime_router.py | 编辑 | 删除 `~summary` 断言 |
156+
| 3 | tests/test_runtime_gate.py | 编辑 | 删除 `~summary` route 集成断言 |
157+
| 4 | .sopify-skills/blueprint/README.md | 确认 | 焦点区块由 renderer 托管，不手工覆写 |
158+
| 4 | .sopify-skills/blueprint/tasks.md | 编辑 | 状态更新 |
159+
160+
不新增 runtime 模块、不新增 CLI 面、不改 protocol.md。
161+
162+
---
163+
164+
## 验收标准
165+
166+
### 切片 1
167+
1. README.md 含 Convention Mode 段落，描述 ≤3 步最小路径
168+
2. 段落引用 protocol.md §4 样例 A 和 §5 合规清单
169+
3. README.zh-CN.md 有对应中文段落
170+
4. `test_check_readme_links.py` 通过（已有测试）
171+
172+
### 切片 2
173+
5. `pytest tests/protocol/` 可独立运行并全部通过
174+
6. 断言覆盖 protocol.md §5 前 5 条（第 6 条不纳入 Phase 1）
175+
7. 不 import 任何 `runtime.*` 模块
176+
177+
### 切片 3
178+
8. `summary` surface 相关精确 pattern 组无残留：`~summary`、`route_name.*summary`、`daily_summary`、`DailySummary`、`_render_daily_summary`、`next_summary`
179+
9. 全量 `pytest` 通过
180+
10. runtime 行数减少 ≥1,100 行
181+
182+
### 蓝图回写
183+
11. blueprint/README.md 焦点已更新
184+
12. blueprint/tasks.md 先行切片状态已标记

‎.sopify-skills/plan/20260505_p15_advance_slices/tasks.md‎

Lines changed: 70 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,70 @@
1+
# 任务清单: P1.5 先行切片
2+
3+
目录: `.sopify-skills/plan/20260505_p15_advance_slices/`
4+
5+
## 1. Convention 入口兑现
6+
7+
- [x] T1-A: 在 README.md Quick Start 章节内增加 Convention Mode 子段落
8+
- 描述 3 步最小路径（读 blueprint → 写 plan → 归档 + receipt）
9+
- 引用 protocol.md §4 样例 A 和 §5 合规检查清单
10+
- 验收: 段落存在 + 内容准确引用协议文档
11+
- [x] T1-B: 在 README.zh-CN.md 同步增加对应中文段落
12+
- 验收: 中文段落结构与英文一致
13+
- [x] T1-C: 运行 `pytest tests/test_check_readme_links.py` 验证链接完整性
14+
- 验收: 测试通过
15+
16+
## 2. Protocol Compliance Suite Phase 1
17+
18+
- [x] T2-A: 新建 `tests/protocol/test_convention_compliance.py` 骨架
19+
- 验收: `pytest tests/protocol/` 可运行（即使 0 test）
20+
- [x] T2-B: 实现断言 1-2（project.md 存在 + blueprint 三件套存在）
21+
- 使用 tmp_path fixture 构建最小 `.sopify-skills/` 目录
22+
- 验收: 正向（结构完整）和反向（缺文件）均测试
23+
- [x] T2-C: 实现断言 3-4（plan 创建 + plan.md 必需字段）
24+
- 在 tmp_path 下创建 plan/YYYYMMDD_feature/plan.md
25+
- 验证 title / scope / approach / tasks 区块存在
26+
- 验收: 正向 + 反向（缺必需字段时失败）
27+
- [x] T2-D: 实现断言 5（归档 + receipt.md）
28+
- 在 tmp_path 下创建 history/YYYY-MM/feature/receipt.md
29+
- 验证 receipt.md 存在
30+
- 验收: 正向 + 反向
31+
- [x] T2-E: 验证 `pytest tests/protocol/` 不 import 任何 `runtime.*` 模块
32+
- 验收: `grep -rn "from runtime\|import runtime" tests/protocol/` 无匹配
33+
34+
## 3. 低风险辅助层预清理（daily_summary）
35+
36+
- [x] T3-A: 验证 `_models/summary.py` 中各 class 的消费方
37+
- grep 全量引用，确认哪些 class 仅被 daily_summary 消费
38+
- 记录结论到本任务备注（共用 class 保留，专属 class 删除）
39+
- 验收: 消费方分析结果记录完毕
40+
- 结论: 全部 16 个 class 均为 daily_summary 专属，整文件删除
41+
- [x] T3-B: 删除 `runtime/daily_summary.py` + 清理 `runtime/engine.py` 中的 import 和调用点
42+
- 删除 `runtime/router.py` 中 `~summary` 命令匹配、`summary` route 支持、以及 capture/decision 相关分支
43+
- 删除 `runtime/__init__.py` 中 `DailySummaryArtifact` public export
44+
- 删除 `runtime/engine.py` 中 summary 相关 import 和 4 处分支（last_route 豁免、build_daily_summary 调用、handoff 保留分支、phase 映射）
45+
- 验收: router/engine/__init__ 不再暴露或消费 summary route
46+
- [x] T3-C: 清理 `runtime/output.py` 中全部 summary 专属分支
47+
- 删除 phase label、`next_summary` 文案、`_render_daily_summary_output`、以及 `summary` route 相关的 `_collect_changes` / `_next_hint` / `_status_symbol` / `_status_message` 分支
48+
- 验收: output.py 不再包含 summary route 的专属渲染与提示逻辑
49+
- [x] T3-D: 清理 `runtime/_models/summary.py` + `runtime/models.py` re-export
50+
- 按 T3-A 结论删除 daily_summary 专属 class
51+
- 清理 `runtime/models.py` 中对应的 re-export
52+
- 验收: 无 daily_summary 专属 class 残留
53+
- [x] T3-E: 清理测试文件
54+
- 删除 `tests/test_runtime_summary.py`（175 行）
55+
- 清理 `tests/runtime_test_support.py:47` 的 import
56+
- 清理 `tests/test_runtime_engine.py:2338` 的 mock patch
57+
- 清理 `tests/test_runtime_router.py:124,131-132` 的 `~summary` 分类断言
58+
- 清理 `tests/test_runtime_gate.py:1947-1959` 与 `2380-2390` 的 `~summary` route 断言
59+
- 验收: 测试文件不再引用 `~summary` / `daily_summary`，且不误删 `render_outcome_summary`、`ClarificationState.summary`、`DecisionOption.summary` 等无关断言
60+
- [x] T3-F: 全量 `pytest` 验证 + `grep` 残留检查
61+
- `pytest` 全量通过（595 passed）
62+
- `grep` 使用精确 pattern 组检查残留：`~summary`、`route_name.*summary`、`daily_summary`、`DailySummary`、`_render_daily_summary`、`next_summary`
63+
- 验收: 目标 surface 零残留（runtime/ + tests/ 范围） + 无 import 断裂，且不把 `render_outcome_summary` / 各类 `*.summary` 字段误判为失败
64+
65+
## 4. 蓝图回写
66+
67+
- [x] T4-A: 确认 `blueprint/README.md` 当前焦点
68+
- 焦点区块由 renderer (`runtime/kb.py`) 托管，不手工覆写
69+
- 验收: `tasks.md` 状态标记到位即可；焦点区块保持 renderer-managed 不变
70+
- [x] T4-B: 更新 `blueprint/tasks.md` P1.5 先行切片状态标记

0 commit comments

Comments
 (0)