Skip to content

Commit a70bd58

Browse files
committed
docs(blueprint): fix 4 review findings
1. Wire-composable: narrow continuation claim — same session precise resume, cross-session requires explicit claim/receipt 2. Convention vs Runtime Validator: clarify pre-write authorizer (Runtime) vs post-hoc acceptance/receipt (Convention) 3. Global state scope: mark execution_confirm_pending/resume_active/exec_plan as transitional, will be cleaned with ExecutionAuthorizationReceipt 4. Route families: clarify resolve_state_conflict is cross-cutting error surface, not a workflow route family 5. Tasks: schedule formal archive of 20260424 plan via archive lifecycle
1 parent 91ca987 commit a70bd58

2 files changed

Lines changed: 11 additions & 4 deletions

File tree

.sopify-skills/blueprint/design.md

Lines changed: 10 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -40,7 +40,7 @@ Sopify 是 AI 编程工作流的 **control plane**,不是通用 LLM orchestrat
4040

4141
独立 loop 通过**线**(机器契约)组合。Sopify 是串联小 loop 的线——control plane 负责串联和传递状态,不做节点内部的事。
4242

43-
线独立于 session / model / host:handoff + run state 让不同会话精确继续
43+
线独立于 session / model / host:同一逻辑 session(`session_id`)内,handoff + run state 让中断后精确继续;跨 session 接力需显式 claim/receipt,不允许静默推进旧 session 的 pending checkpoint
4444

4545
| 显隐 | 实现 | 适用 |
4646
|------|------|------|
@@ -51,6 +51,8 @@ Sopify 是 AI 编程工作流的 **control plane**,不是通用 LLM orchestrat
5151

5252
所有线共享一个知识面(blueprint / history)。知识面是跨 session/model/host 的共享工作记忆。
5353

54+
在多模型、多云、多宿主逐步解耦的环境下,Surface-shared 的目标是让项目连续性绑定到共享文件协议,而不是绑定到某个模型、云或聊天上下文。任意 host/model 只要正确消费 blueprint/history 与 handoff 暴露的机器事实,就能基于同一项目记忆继续工作;但推进 pending checkpoint 或产生副作用仍必须回到 Wire-composable 的机器接力与 Validator 授权。
55+
5456
**Sopify 的不可替代性 = 线 + 面的组合。** Protocol 定义 schema,Runtime 是可选的"加固线"。
5557

5658
## 三层定位 (ADR-016: Protocol-first / Runtime-optional)
@@ -61,8 +63,10 @@ Sopify 是 AI 编程工作流的 **control plane**,不是通用 LLM orchestrat
6163
| **Validator** | ActionProposal 校验、状态迁移校验、archive check/apply | ~2K 行 | 独立交付 |
6264
| **Runtime** | gate / router / engine / handoff 状态机 | 目标 <20K 行 | 可选增强 |
6365

64-
**Convention 模式 (下界)**: LLM 读 SKILL.md → 自行推进 → Validator 事后校验。
65-
**Runtime 模式 (上界)**: 完整 runtime 控制状态迁移。
66+
**Convention 模式 (下界)**: LLM 读 SKILL.md → 自行推进 → Validator 事后校验(protocol acceptance / receipt authority)。
67+
**Runtime 模式 (上界)**: 完整 runtime 控制状态迁移,Validator 是 pre-write authorizer。
68+
69+
"Validator 是唯一授权者"在两种模式下含义不同:Runtime 模式是写前授权;Convention 模式是事后合规校验与 receipt 签发。两者共享同一校验逻辑,但触发时机和阻断语义不同。
6670

6771
模式选择维度是**过程要求**,不是模型强弱。
6872

@@ -172,6 +176,8 @@ Sopify 是 AI 编程工作流的 **control plane**,不是通用 LLM orchestrat
172176
| `clarification` | clarification_pending, clarification_resume |
173177
| `decision` | decision_pending, decision_resume |
174178

179+
`resolve_state_conflict` 是 state-resolution error surface,不计入 workflow route family。它在任何 route 内均可触发,作为横切 error handling 存在。
180+
175181
#### Core State Files (target: 6, authoritative)
176182

177183
| File | 职责 |
@@ -255,7 +261,7 @@ knowledge_sync:
255261
### Runtime state scope
256262

257263
- Review state 默认落在 `state/sessions/<session_id>/`,覆盖 `current_plan/current_run/current_handoff/current_clarification/current_decision/last_route`
258-
- 根级 `state/` 只承载 global execution truth(`execution_confirm_pending / resume_active / exec_plan`)
264+
- 根级 `state/` 只承载 global execution truth(当前仍包含 `execution_confirm_pending / resume_active / exec_plan` 等 transitional 语义,将随 ExecutionAuthorizationReceipt 和 route 收敛逐步清理
259265
- Archive lifecycle 只在归档主体等于当前 global `current_plan` 时清理对应执行状态
260266
- `session_id` 由宿主透传或 gate 自动生成;同一条 review 续轮必须复用同一个 `session_id`
261267
- 并发 review 使用不同 `session_id`;global truth 只补 soft ownership 观测字段

.sopify-skills/blueprint/tasks.md

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -56,6 +56,7 @@
5656
- [ ] history feature_key 聚合视图
5757
- [ ] Protocol Step 1:提取最小协议文档与行为契约 case
5858
- [ ] CrossReview Phase 4a:advisory skill 接入 develop 后审查
59+
- [ ]`plan/20260424_lightweight_pluggable_architecture` 通过 archive lifecycle 正式迁移至 `history/`(当前已降级为历史证据源,但仍物理留在 `plan/` 目录)
5960

6061
## 明确延后项
6162

0 commit comments

Comments
 (0)