Skip to content

Commit 25af473

Browse files
Li-SanzeLi-Sanze
committed
docs(adr): create ADR-013, ADR-016, ADR-017 entity files
ADR-013: Product Positioning — Workflow Control Plane ADR-016: Protocol-first / Runtime-optional ADR-017: Action/Effect Boundary (includes ExecutionAuthorizationReceipt fields) Previously these ADRs were only referenced by number in plan/blueprint prose. Now they exist as standalone reviewable documents in docs/adr/.
1 parent 1d2c622 commit 25af473

3 files changed

Lines changed: 182 additions & 0 deletions

File tree

‎docs/adr/ADR-013.md‎

Lines changed: 47 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,47 @@
1+
# ADR-013: Product Positioning — Workflow Control Plane
2+
3+
状态: 已确认
4+
日期: 2026-04
5+
6+
## 背景
7+
8+
Sopify 需要明确自身在 AI 编程生态中的定位，避免与宿主（Claude Code、Codex、Cursor）、技能市场（Superpowers）或方法论产品（Spec-Kit）竞争。
9+
10+
## 决策
11+
12+
**Sopify 是 AI 编程工作流的 control plane。**
13+
14+
Core 职责：
15+
16+
1. **自适应工作流**：按任务复杂度选择快速修复 / 轻量迭代 / 完整方案
17+
2. **状态交接**：handoff 机器契约让任务跨轮、跨会话可恢复
18+
3. **质量治理**：独立验证闭环（cross-review 是参考实现，不是 core 功能）
19+
4. **资产沉淀**：blueprint / history 构建跨任务项目记忆
20+
5. **宿主无关**：`.sopify-skills/` 纯文件协议
21+
22+
不做的事：
23+
24+
| 领域 | 不做 | 归属 |
25+
|------|------|------|
26+
| 模型推理 | LLM 调用、代码生成 | 宿主 |
27+
| 技能市场 | skill 分发、安装、计费 | 独立生态 |
28+
| 方法论 | spec 写作、设计模式教学 | 独立产品 |
29+
| 代码执行 | 文件编辑、终端操作 | 宿主 |
30+
31+
## 生存性测试
32+
33+
2027 年宿主原生支持 plan/checkpoint/multi-agent 后，Sopify 仍必须保留：
34+
35+
- 项目级资产沉淀（blueprint / history）
36+
- 跨宿主连续工作
37+
- 可审计决策链
38+
- 独立质量闭环
39+
- 计划漂移治理
40+
41+
如果以上任一能力被宿主完全替代且无跨宿主可携带性需求，该能力应 sunset。
42+
43+
## 后果
44+
45+
- Core 只保留协议/状态/权限层
46+
- 具有独立用户价值的分析/推理能力设计为可外部化组件
47+
- CrossReview 是已实现的可外部化参考范本

‎docs/adr/ADR-016.md‎

Lines changed: 49 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,49 @@
1+
# ADR-016: Protocol-first / Runtime-optional
2+
3+
状态: 已确认
4+
日期: 2026-04-26
5+
6+
## 背景
7+
8+
Sopify runtime 已膨胀至 ~29K 行 Python / 66 个模块。核心价值（plan 约定、状态交接、checkpoint、history、blueprint）天然是文件协议，不必须由 Python runtime 承载。复杂 runtime 容易把"LLM 随机出错"变成"系统性卡在某状态"，后者更不可控。
9+
10+
## 决策
11+
12+
**Sopify 从 Runtime-centric 演进为 Protocol-first。**
13+
14+
三层定位：
15+
16+
| 层 | 内容 | 体量 | 可替代性 |
17+
|----|------|------|---------|
18+
| **Protocol** | `.sopify-skills/` 目录约定、plan/state/history schema、SKILL.md 编排 | 纯文档 | 不可替代 |
19+
| **Validator** | ActionProposal 校验、状态迁移校验、archive check/apply、diagnostics | ~2K 行 | 独立交付 |
20+
| **Runtime** | gate / router / engine / handoff / checkpoint 状态机 | 目标 <20K 行 | 可选增强 / 参考实现 |
21+
22+
两种操作模式：
23+
24+
- **Convention 模式（下界）**：LLM 读 SKILL.md → 自行推进 → Validator 事后校验。适用：轻量任务、新宿主接入。
25+
- **Runtime 模式（上界）**：完整 runtime 控制状态迁移。适用：确定性门控、审计、恢复、权限边界。
26+
27+
模式选择维度是**过程要求**，不是模型强弱。
28+
29+
## 战略论据
30+
31+
1. **核心价值不在 Python runtime** — plan、状态交接、checkpoint、history 天然是文件协议
32+
2. **Protocol 更抗平台替代** — Runtime 编排易被宿主替代；`.sopify-skills/` 可审计资产格式可被各宿主复用
33+
3. **Convention 是多宿主最短路径** — Protocol + SKILL.md + Validator 让新宿主先"会读会写"
34+
4. **复杂 runtime 不解决 LLM 出错** — 把随机错误变成系统性卡顿更不可控
35+
36+
## 四步演进路线
37+
38+
| 步骤 | 内容 | 前置 |
39+
|------|------|------|
40+
| Step 1 | 提取 Protocol 文档：plan/state/lifecycle/SKILL.md 规范 | 无 |
41+
| Step 2 | Protocol validator CLI (check / doctor / archive) | Step 1 |
42+
| Step 3 | SKILL.md 表单式增强 + Action Schema Boundary | Step 1 + ADR-017 |
43+
| Step 4 | Runtime 可选化：Convention 下界 + Runtime 上界 | Step 2+3 验证 |
44+
45+
## 后果
46+
47+
- 新功能优先考虑是否可以纯 Protocol 实现
48+
- Runtime 体量目标 <20K 行（从当前 ~29K 削减）
49+
- SKILL.md 必须是表单式（弱模型可机械填写），不是方法论散文

‎docs/adr/ADR-017.md‎

Lines changed: 86 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,86 @@
1+
# ADR-017: Action/Effect Boundary
2+
3+
状态: P0 完成，持续扩展
4+
日期: 2026-04-28 (P0)
5+
6+
## 背景
7+
8+
在 ActionProposal 之前，Host LLM 直接驱动 runtime 路由和副作用。局部语境请求被误读为全局推进是通用问题。需要在 materialization 之前建立授权边界。
9+
10+
## 决策
11+
12+
**在 State Resolution 完成后、Router 产生副作用之前，插入 ActionProposal 解析与 Effect 授权。**
13+
14+
核心管线：
15+
16+
```
17+
用户自然语言
18+
→ Host LLM 映射为 ActionProposal（action_type + side_effect + confidence + evidence）
19+
→ Validator 基于 ActionProposal + ValidationContext 输出 ValidationDecision
20+
→ Deterministic action 执行
21+
→ Handoff / Receipt 暴露机器事实
22+
```
23+
24+
### 不变量
25+
26+
1. **Host LLM 只是 proposal source，不是 authorizer** — LLM 提交工单，不批准工单
27+
2. **Validator 是唯一授权者** — 判断当前 context 下 action/side effect 是否允许
28+
3. **Validator 不是 executor** — 不做 plan materialization、文件迁移、自动修复、状态推进
29+
4. **执行层不理解人话** — 只按结构化字段和文件事实做事
30+
5. **`fallback_router` 是临时兼容出口** — 应单调收缩，不承接新的长期能力
31+
32+
### ExecutionAuthorizationReceipt（方向）
33+
34+
execution_confirm checkpoint 重分类为机器授权事实：
35+
36+
**不变量：**
37+
- 绑定 plan identity + plan revision + execution gate result + action proposal identity + authorization source
38+
- 使用 canonical JSON + sha256 生成 fingerprint
39+
- Plan 变更后 receipt 自动失效
40+
- Fail-closed：任一字段不匹配则拒绝执行
41+
42+
**Receipt 字段定义：**
43+
44+
| 字段 | 语义 |
45+
|------|------|
46+
| `plan_id` | 目标 plan 的唯一标识 |
47+
| `plan_path` | 目标 plan 的文件路径 |
48+
| `plan_revision_digest` | plan 内容的 sha256 摘要 |
49+
| `gate_status` | execution gate 的判定结果 |
50+
| `action_proposal_id` | 触发授权的 ActionProposal 标识 |
51+
| `authorization_source` | `{ kind: "host_turn", turn_id }` 或 `{ kind: "request_hash", request_sha1 }` |
52+
| `fingerprint` | `sha256(canonical_json({plan_id, plan_path, plan_revision_digest, gate_status, action_proposal_id}))` |
53+
| `authorized_at` | ISO 8601 时间戳 |
54+
55+
Implementation plan 可补充字段，但不得删除或弱化上述字段的 fail-closed 语义。
56+
57+
### Checkpoint 重分类
58+
59+
| 旧类型 | 新定位 | 理由 |
60+
|--------|--------|------|
61+
| `clarification` | **保留为 canonical checkpoint** | 补事实是真协作分叉 |
62+
| `decision` | **保留为 canonical checkpoint** | 拍板选路是真协作分叉 |
63+
| `plan_proposal` | propose_plan pending artifact | 等 side-effect proof 稳定后降级 |
64+
| `execution_confirm` | ExecutionAuthorizationReceipt | 授权不是协作分叉 |
65+
| `develop_checkpoint` | develop callback source | 触发 clarification/decision，不是独立类型 |
66+
67+
## P0 Thin Slice（已完成）
68+
69+
- `ActionProposal` schema + `ValidationContext` + `Validator` 已实现
70+
- Gate 接收 `--action-proposal-json`
71+
- Engine pre-route interceptor 已接入
72+
- `consult_readonly` 首个受控 side-effect 已验证
73+
- `archive_plan` 已切入 ActionProposal 管线
74+
75+
## 后续扩展方向
76+
77+
- `propose_plan` + `write_plan_package` side-effect proof
78+
- `execute_existing_plan` 通过 ExecutionAuthorizationReceipt 授权
79+
- `fallback_router` 职责单调收缩
80+
81+
## 后果
82+
83+
- 所有 side-effecting action 必须先映射为 ActionProposal
84+
- `~go finalize` 等 command alias 必须映射为对应 proposal，不绕过 Validator
85+
- Checkpoint 目标压缩为 2 种 canonical type
86+
- required_host_action 目标压缩为 5 种 canonical action

0 commit comments

Comments
 (0)