diff --git a/.sopify-skills/blueprint/tasks.md b/.sopify-skills/blueprint/tasks.md index 3d022e0..2090b63 100644 --- a/.sopify-skills/blueprint/tasks.md +++ b/.sopify-skills/blueprint/tasks.md @@ -1,113 +1,148 @@ # 蓝图路线图与待办 -本文定位: 路线图全景 + 未完成长期项与明确延后项。已完成里程碑仅保留一行摘要与归档指引。不替代当前 plan 的执行任务清单。 +本文定位: 路线图全景 + 开放项与延后项。已完成里程碑仅保留一行摘要与归档指引。不替代当前 plan 的执行任务清单。 -## 执行优先级（已确认） - -以下顺序是硬约束。前一项未稳定前，不进入后一项实现。 +## 产品方向 > **对齐原则**：Sopify 总方向是 Protocol-first / Validator-centered / Runtime-optional。主航道的每一步都是"先 formalize protocol/validator 层契约，再让 runtime 作为参考实现消费"。不以 runtime 内部治理为驱动。蓝图变更优先做能强化证据与授权层的事，优先做能让外部宿主看懂、接入、被验证的事；AI + 单人维护应串行收敛，不同时开多条线。 -> **先行切片例外**：以下两类改动不受上述顺序约束：① 已在后续里程碑描述中显式标注"可先行"的 presentation-only 切片；② 已证明不影响 protocol / validator / runtime machine contract 的纯展示层改动。除此之外，任何涉及契约面的工作必须等前置里程碑稳定。 +## 后 P4c 执行规则 -> **结构重构锚点**：跨 contract 的模块拆分与 legacy control surface 收口应与里程碑同步——P1 后优先 subject resolution / plan lookup 统一入口（✅），P1.5 后优先 authorization policy / gate-receipt 收敛（✅），P2 后优先 action contract adapter 统一（✅），P3a sunset 表最终清理（✅）。engine.py / decision_tables.py 系统拆分属于 P4b（runtime_surface_consolidation），需 P4a 外部消费面冻结后执行。不阻止与上述 contract 无关且不改变 machine truth 的低风险整理。 +P0→P4c 主航道已全部完成。后续执行遵循以下原则： -| 优先级 | 任务 | 前置条件 | 说明 | -|--------|------|---------|------| -| P0 | Blueprint rebaseline | 无 | 已完成。重写 blueprint，实体化 ADR，定义削减目标 | -| P1 | subject_identity_binding | P0 | 已完成。protocol / validator / runtime 三联动定义"操作的是谁" | -| P1.5 | execution_authorization_spine | P1 | 已完成。操作化 ADR-017 ExecutionAuthorizationReceipt，规划授权链路 | -| P2 | local_action_contracts | P1.5 | 已完成。在主体已绑定前提下收敛局部动作 contract | -| P3a | contract_aligned_cleanup | P2 | 已完成。以 protocol/validator 已稳定为前提，清理 runtime 旧 contract 面 | -| P3b | perimeter_cleanup | P3a | 已完成。外围面清理：release gate 修复、CHANGELOG 去文件列表化、tests 分类、旧概念清理 | -| P4a | external_surface_freeze | P3b | 已完成。薄切片：冻结不可删外部消费面 keep-list | -| P4b | runtime_surface_consolidation | P4a | 已完成。prove-kept-or-delete 证明 <20K 不可达，实删 15 LOC | -| P4b.5 | runtime_optionality_audit | P4b | 已完成。设计/审计型：宿主接入层级矩阵 + 消费矩阵 + blast radius + 综合裁定 | -| P4c | host_consumption_governance | P4b.5 | 已完成。宿主只消费 contract，不定义 truth | +1. **串行收敛**：未选定下一主线前，不并行开启多个会扩张 machine truth 的方向。 +2. **主线依赖链**：P4d → P5 → P6 仍按依赖链推进；在前项尚未形成足够结论前，不把后项提升为正式主线。 +3. **证据驱动升级**：证据型候选服务于主线但不占 P 编号；其产出是主线里程碑的升级证据，不是独立的主航道步骤。（关于硬约束 §8"新增项必须挂回现有 P 主航道"的释义：此约束要求新增开放项服务既有 P 主线，不能另起一条主航道；不等于每个开放项都必须拿一个 P 编号。） -### P0: Blueprint Rebaseline（已完成） +## 已完成主航道（P0→P4c） -✅ 已完成。重写 blueprint 三件套、实体化 ADR、定义削减预算表、落地 protocol.md v0。细节见 git history。 +| 编号 | 名称 | 一行摘要 | 归档 | +|------|------|---------|------| +| P0 | Blueprint Rebaseline | 蓝图三件套 + ADR 实体化 + 削减预算表 + protocol.md v0 | git history | +| P1 | Subject Identity Binding | protocol §7 normative + Validator fail-closed + execute_existing_plan subject binding | `history/2026-05/20260504_subject_identity_binding/` | +| P1.5 | Execution Authorization Spine | 4 方案包 + 3 先行切片 + 1 桥接切片，操作化 ADR-017 ExecutionAuthorizationReceipt | `history/2026-05/20260505_p15_*` ~ `20260506_p15_*` | +| P2 | Local Action Contracts | admission contract 闭合（subject binding + delta schema + action-effect pairing） | `history/2026-05/20260506_p2_local_action_contracts/` | +| P3a | Contract-Aligned Cleanup | runtime 旧 contract 面清理 + execution routing 收敛 + dead path cleanup | `history/2026-05/20260507_p3a_contract_aligned_surface_cleanup/` | +| P3b | Perimeter Cleanup | release gate 修复 + CHANGELOG 压缩 + tests 分类 + replay 下线 + 旧概念清理 | `history/2026-05/20260508_p3b_perimeter_cleanup/` | +| P4a | External Surface Freeze | 15 条 keep-list + 20 条字段分类（纯文档） | `history/2026-05/20260509_p4a_external_surface_freeze/` | +| P4b | Runtime Surface Consolidation | prove-kept-or-delete 全量扫描，24,334 LOC，15 LOC 实删 | `history/2026-05/20260509_p4b_runtime_surface_consolidation/` | +| P4b.5 | Runtime Optionality Audit | 3 级梯度 + 消费矩阵 + blast radius + 综合裁定（纯审计） | `history/2026-05/20260510_p4b5_runtime_optionality_audit/` | +| P4c | Host Consumption Governance | 契约投影 + 增强声明 + 渲染收敛 + prompt -140 行 + protocol.md §8 唯一入口 | `history/2026-05/20260510_p4c_host_consumption_governance/` | -### P1: Subject Identity & Existing Plan Binding（已完成） +## 主线里程碑 -✅ 已完成（归档：`history/2026-05/20260504_subject_identity_binding/`）。protocol §7 subject identity 升格 normative、Validator admission fail-closed、execute_existing_plan subject binding。P1 语义债（DECISION_REJECT consult 伪装）在 P1.5-A 收口。 +### P4d: New Host Pilot -### P1.5: Execution Authorization Spine（已完成） +选 1 个非 deep 宿主做试点（payload_capable + 接续增强），不接完整 runtime。验证官方最低新宿主画像是否成立、P4b.5/P4c 的分层是否真正降低接入成本。 -✅ 已完成（4 方案包 + 3 先行切片 + 1 桥接切片）。归档：`history/2026-05/20260505_p15_*` ~ `20260506_p15_*` +**Companion: Continuation Entry Convergence** -### P2: Local Action Contracts on Bound Subjects（已完成） +统一宿主级官方入口语义（Inspect Active Work / Continue Active Work / Start New Work），覆盖同宿主跨 session 与跨宿主接续。只消费现有 frozen contract，不新增 machine truth，不绑定 runtime 正则/路由实现。不规定入口语法或关键词，宿主自行选择暴露形式。有活动工作或 pending checkpoint 时 Start New Work 必须显式仲裁。当前 `~go exec` 是 Continue Active Work 的命令级实现，应被 host-level 入口语义取代。结合 P4d 非 deep 宿主试点 formalize。 -✅ 已完成。admission contract 闭合（subject binding + delta schema + action-effect pairing）。归档：`history/2026-05/20260506_p2_local_action_contracts/` +- 前置：P4c ✅ +- 状态：待启动 +- 升级判断：试点宿主走通 payload_capable + 接续增强的最小接续链路（至少 handoff 消费，常见配套为 plan binding + run state），且接续入口语义验证可行，即可声明 P4d 结论足够，评估 P5 启动 -### P3a: Contract-Aligned Surface Cleanup（已完成） +### P5: Contract Surface Shrinkage -✅ 已完成。runtime 旧 contract 面清理 + execution routing 收敛 + knowledge_sync audit trail + dead path cleanup。Runtime 结构性减重（26K→<20K）剥离为 P4b。归档：`history/2026-05/20260507_p3a_contract_aligned_surface_cleanup/` +在 P4d 验证后，按 evidence 逐项删除或降级 deep runtime 专属的 contract surface（bridge capability / manifest entry / installer bundle 项）。此时已知哪些 contract 是新宿主需要 vs 历史包袱。 -### P3b: Perimeter Cleanup（已完成） +- 前置：P4d +- 状态：待 P4d 结论 +- 升级判断：P4d 试点产出 keep / delete / downgrade 裁定表，覆盖所有 deep-only contract 面 -✅ 已完成。Release gate 修复、CHANGELOG 压缩、tests 分类标注、replay/workflow-learning 下线、README 首屏降噪、旧概念清理。归档：`history/2026-05/20260508_p3b_perimeter_cleanup/` +### P6: Runtime Sunset / Reference Runtime -### P4a: External Surface Freeze（已完成） +将 runtime 明确降级为 reference implementation 或 deep host hardening layer。新宿主默认走 Protocol/Convention 模式，runtime 不再承载新增产品能力。可能与 P5 合并。 -✅ 已完成。Frozen External Surface keep-list（15 条）+ Output Rendering Audit（20 条字段分类 + 5 个已知热点）。纯文档变更，不写运行代码。归档：`history/2026-05/20260509_p4a_external_surface_freeze/` +- 前置：P5 +- 状态：待 P5 结论 +- 升级判断：P5 裁定表执行完毕，deep-only surface 削减到可维护水位 -### P4b: Runtime Surface Consolidation（已完成） +## 证据型候选（为下一主线提供升级证据，不占 P 编号） -✅ 已完成。prove-kept-or-delete 全量扫描证明 runtime 在当前 contract 约束下已接近最小可行体积（24,334 LOC）。<20K 目标在不改 distribution/installer contract 的约束下不可达。交付物：Phase 0 test re-audit（653 hard / 31 soft gate）、Phase 1 CI/preflight 真实降载、Phase 2 全量死代码扫描（15 LOC 删除）。归档：`history/2026-05/20260509_p4b_runtime_surface_consolidation/` +> 以下项目服务于主线里程碑的推进判断，不是独立的主航道步骤。其产出（验证报告、试点数据、compliance 结论）是主线决策的输入。 -### P4b.5: Runtime Optionality & Host Onboarding Audit（已完成） +### First-Use Adoption Proof -✅ 已完成。设计/审计型，不改代码。交付物：S1 Forbidden Surface（F1-F8）、S2 消费矩阵 + opt-in 增强组合 + 官方接入画像、S3 Blast Radius 审计（15 功能区 + 语义来源→落盘→contract 映射）、S4 综合裁定 + P4c 前提声明。归档：`history/2026-05/20260510_p4b5_runtime_optionality_audit/` +验证非作者用户/宿主能安装、触发、理解、走通 Sopify 首次使用链路。覆盖 install/bootstrap 文案压缩、status/doctor 用户语言化验收、scripts 用户面与维护面分离、至少一个非作者首次采用 walkthrough。前提：P4c 已确保默认路径不暴露内部 taxonomy。边界：只做首次采用证明与用户面收口，不重开 protocol/runtime 产品定位，不回头扩 machine contract。 -### P4c: Host Consumption Governance（已完成） +- 前置：P4c ✅ +- 服务主线：P4d（提供首次采用基线数据） +- 前置条件：GitHub Release 可用——install 脚本 `curl` / `iwr` 命令实际可执行（安装链路的物理前提） +- 最小交付证据： + 1. 至少 1 个非作者用户完成首次安装→触发→理解→走通链路的记录（含卡点与解决方式） + 2. `examples/` 包含至少 1 个可独立跟随的端到端 demo（含配置、操作步骤、预期输出） + 3. README 包含至少 1 个视觉资产（截图或 GIF），展示核心工作流的用户可感知效果（架构图不计入此项） -✅ 已完成（P4c-5 Prompt Asset 结构收口显式跳过）。P4b.5 审计结论转化为可执行治理：宿主只消费稳定 contract，不再定义 machine truth。交付物：P4c-1 契约投影矩阵（deep_verified † 全部消除）、P4c-2 增强声明/检测协议、P4c-3a output/doctor/handoff 渲染收敛、P4c-3b 首接触/prompt 收敛（-140 行 route taxonomy 删除，protocol.md §8 引用替代）、P4c-4 protocol.md §8 唯一入口 + 文档披露梯度 + builtin skill 披露 + design.md 结构整理。跨切片 invariant 5/5 PASS，红线 6/6 无违反。归档：`history/2026-05/20260510_p4c_host_consumption_governance/` +### Protocol Compliance Phase 2 -## 未完成长期项 +在 Phase 1 文件断言之上，参考 Superpowers headless behavioral test 做端到端行为验证；扩展 Convention smoke 到完整最小生命周期（含 knowledge_sync / blueprint writeback）。 -### P4b 后续路线（P4c 后视评估） +- 前置：P4c ✅ +- 服务主线：P4d / P5（提供合规性证据） +- 最小交付证据：Convention smoke 覆盖 Convention 模式最小生命周期，全部 PASS（具体步骤在 Phase 2 开包时定义） -- [ ] P4d New Host Pilot：选 1 个非 deep 宿主做试点（convention_only 或 payload_capable），不接完整 runtime。验证 P4b.5/P4c 的分层是否真正降低接入成本。可与 P4c 后期并行启动。 -- [ ] Continuation Entry Convergence：统一宿主级官方入口语义（Inspect Active Work / Continue Active Work / Start New Work），覆盖同宿主跨 session 与跨宿主接续。只消费现有 frozen contract，不新增 machine truth，不绑定 runtime 正则/路由实现。不规定入口语法或关键词，宿主自行选择暴露形式（命令、按钮、菜单等）。有活动工作或 pending checkpoint 时 Start New Work 必须显式仲裁。当前 `~go exec` 是 Continue Active Work 的命令级实现，应被 host-level 入口语义取代。_触发条件：P4c 验收后，结合 P4d 非 deep 宿主试点 formalize_ -- [ ] P5 Contract Surface Shrinkage：在 P4d 验证后，按 evidence 逐项删除或降级 deep runtime 专属的 contract surface（bridge capability / manifest entry / installer bundle 项）。此时已知哪些 contract 是新宿主需要 vs 历史包袱。 -- [ ] P6 Runtime Sunset / Reference Runtime：将 runtime 明确降级为 reference implementation 或 deep host hardening layer。新宿主默认走 Protocol/Convention 模式，runtime 不再承载新增产品能力。可能与 P5 合并。 +### 第三方宿主自助接入 Convention 证明 -### 其他长期项 +不指定下一个官方深适配目标，先把 Convention quickstart + compliance check 做出来，再由外部宿主自行验证接入。 -- [ ] 补宿主级 first-hop ingress proof / diagnostics -- [ ] `~compare` shortlist facade 收敛进默认主链路 -- [-] `workflow-learning` 独立 helper 与更稳定 replay retrieval → P3b replay 能力下线后，未来如需重设计另行评估 -- [ ] blueprint 索引摘要更细粒度自动刷新 -- [ ] history feature_key 聚合视图 +- 前置：P4c ✅ +- 服务主线：P4d（提供外部接入可行性证据） +- 最小交付证据：Convention quickstart 文档 + compliance check 脚本可独立运行，至少 1 个非 deep 宿主跑通 + +## 独立产品线 + +### CrossReview + +独立审查内核，宿主中立。Phase 0 决策全部锁定（命名/边界/仓库形态/资产层/MVP artifact/集成顺序），Phase 1-4 待推进。与主航道无硬依赖，可独立推进。 -- [ ] CrossReview Phase 4a：advisory skill 接入 develop 后审查 -- [ ] Plan intake checklist（在 intake 模板/脚本落地前，后续新 plan 开包时手工回答以下问题）： - 1. 主命中哪个蓝图里程碑（P4b.5 / P4c / P4d / P5 / P6）？若不命中主线，须显式标记为"长期项"或"延后项"，不强行归类 +- Registry 状态：active + governance deferred +- 详见：`plan/20260418_cross_review_engine/` +- 相关蓝图项：CrossReview Phase 4a（advisory skill 接入 develop 后审查） + +## 流程与工具项 + +- [ ] Plan intake checklist（后续新 plan 开包时手工回答以下问题）： + 1. 主命中哪个蓝图活跃分层？主线里程碑（P4d / P5 / P6）、证据型候选（Adoption Proof / Compliance Phase 2 / Convention 证明）、独立产品线（CrossReview）？若不命中以上任一，须显式标记为"流程工具项"或"延后项"，不强行归类 2. 这次改动定义的是 contract acceptance boundary，还是 execution strategy / implementation wave？（前者进 blueprint，后者留方案包） 3. 是否新增、删除、替代 action / route / state / checkpoint / receipt 中的任一 machine truth？若是，对照 `design.md` 削减预算表 4. 若涉及 legacy surface，替代 contract 是否已在 `design.md` sunset 表中对应里程碑稳定？ 5. 若影响 Core promotion rule / hard max / ownership / validator authority，须补充 ADR impact -- [ ] Multi-host review contract 正式化（protocol.md §7 从 informative/draft 升级为 normative）— 部分由 P1 subject identity 升格推进 +- [ ] 补宿主级 first-hop ingress proof / diagnostics +- [ ] `~compare` shortlist facade 收敛进默认主链路 +- [ ] blueprint 索引摘要更细粒度自动刷新 +- [ ] history feature_key 聚合视图 +- [ ] Multi-host review contract 正式化（protocol.md §7 从 informative/draft 升级为 normative） - [ ] 方案级收敛语义操作化（risk ladder + 验证深度规则 + 多审查者冲突解决） - [ ] 轻量化产品指标与 acceptance gate（首次上手步骤数、必需文件数、默认 workflow 必需 contract 数） -- [-] Convention 入口兑现差距 → 已转入 P1.5 可先行切片，非落地完成 - [ ] 产品层 ↔ 实现层 contract matrix 正式化（ownership / admission / lifecycle responsibilities） -- [ ] Protocol Compliance Phase 2：在 Phase 1 文件断言之上，参考 Superpowers headless behavioral test 做端到端行为验证；扩展 Convention smoke 到完整最小生命周期（含 knowledge_sync / blueprint writeback）。外部启发：Superpowers headless Claude 测试，准入 T1 Adoption。_触发条件：P4c 验收通过后评估是否提升为里程碑_ -- [ ] 第三方宿主自助接入 Convention 证明：不指定下一个官方深适配目标，先把 Convention quickstart + compliance check 做出来，再由外部宿主自行验证接入。_触发条件：P4c 验收通过后评估是否提升为里程碑_ -- [-] 第三方 CLI 宿主能力边界治理（P4a→P4c bridge）：已设计，待 P4c 消费。Host Capability Ladder（3 级 canonical 梯度）、接入判定 Checklist、Convention Quickstart 最小交付面、Prompt 镜像治理原则已落地 → `blueprint/design.md` Host Capability Governance 节。_P4c 消费该结论。_ -- [ ] First-Use Adoption Proof：验证非作者用户/宿主能安装、触发、理解、走通 Sopify 首次使用链路。覆盖 install/bootstrap 文案压缩、status/doctor 用户语言化验收、scripts 用户面与维护面分离、至少一个非作者首次采用 walkthrough。前提：P4c 已确保默认路径不暴露内部 taxonomy。边界：只做首次采用证明与用户面收口，不重开 protocol/runtime 产品定位，不回头扩 machine contract，不把维护者脚本整理泛化成大规模重构。语义方向待收窄（External Adoption Proof 或 User-Facing Onboarding Convergence），编号待定。_触发条件：P4c 验收通过后评估是否提升为里程碑_ +- [ ] GitHub Release pipeline 建立（首次 release 创建 + tag 规范 + install 脚本端到端验证） +- [ ] 测试套件健康基线（pass rate ≥ 99%；当前基线 717 tests / 695 passed / 22 failed = 97%） + +## 已关闭 / 已吸收项 + +| 原项 | 处置状态 | 归因 | +|------|---------|------| +| workflow-learning 独立 helper | 终止 | P3b replay 能力下线，未来如需重设计另行评估 | +| Convention 入口兑现差距 | 已并入 | 已转入 P1.5 先行切片 | +| ~replay 更多入口 | 终止 | P3b replay 能力已下线 | +| 第三方 CLI 宿主能力边界治理（P4a→P4c bridge） | 已消费 | P4c 已消费，Host Capability Governance 已落地 design.md | ## 明确延后项 -- [-] runtime 全接管 develop orchestrator -- [-] 非 CLI 宿主图形化表单 -- [-] history 正文纳入默认长期上下文 -- [-] daily index -- [-] ~replay 更多入口 → P3b replay 能力已下线 -- [-] runtime 独立 preferences_artifact -- [-] 偏好自动归纳/提炼 -- [-] `sopify init --minimal` 等新增 CLI 面（Convention 入口优先通过文档/模板兑现） -- [-] 知识自动提炼（Hermes Agent persistent memory + curator 方向，T0 Reference；与 runtime 全接管、偏好自动归纳有直接张力） -- [-] 声明式工作流引擎（Spec-Kit YAML workflow engine 方向，T0 Reference；与 Runtime-optional 有张力） +| 项目 | 复审触发 | +|------|---------| +| runtime 全接管 develop orchestrator | Runtime-optional 方向明确转向时 | +| 非 CLI 宿主图形化表单 | 有非 CLI 宿主试点需求时 | +| history 正文纳入默认长期上下文 | 上下文窗口或 KB 机制显著变化时 | +| daily index | 用户数增长到需要每日索引时 | +| runtime 独立 preferences_artifact | 偏好管理成为产品瓶颈时 | +| 偏好自动归纳/提炼 | 与 runtime 全接管/知识自动提炼方向收敛时 | +| `sopify init --minimal` 等新增 CLI 面 | Convention 入口优先通过文档/模板兑现；P4d 试点后评估 | +| 知识自动提炼（Hermes Agent 方向） | 与 Runtime-optional 张力解决后 | +| 声明式工作流引擎（Spec-Kit 方向） | 与 Runtime-optional 张力解决后 | + +## 遴选决策记录 + +（待填写） diff --git a/CHANGELOG.md b/CHANGELOG.md index af256c6..d458383 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -6,6 +6,18 @@ Format: Summary → Changed → Plan Packages. File-level details live in `git l ## [Unreleased] +## [2026-05-13.111757] - 2026-05-13 + +### Summary + +- Changes across: Runtime, Tests, Changed. + +### Changed + +- **Runtime**: Updated runtime internals (2 files) +- **Tests**: Updated automated coverage (3 files) +- **Changed**: Updated project files (1 files) + ## [2026-05-11.202509] - 2026-05-11 ### Summary diff --git a/Claude/Skills/CN/CLAUDE.md b/Claude/Skills/CN/CLAUDE.md index 9df1b46..6540302 100644 --- a/Claude/Skills/CN/CLAUDE.md +++ b/Claude/Skills/CN/CLAUDE.md @@ -1,5 +1,5 @@ - + # Sopify - 自适应 AI 编程助手 diff --git a/Claude/Skills/EN/CLAUDE.md b/Claude/Skills/EN/CLAUDE.md index 3793878..2ef80a7 100644 --- a/Claude/Skills/EN/CLAUDE.md +++ b/Claude/Skills/EN/CLAUDE.md @@ -1,5 +1,5 @@ - + # Sopify - Adaptive AI Programming Assistant diff --git a/Codex/Skills/CN/AGENTS.md b/Codex/Skills/CN/AGENTS.md index c11b054..3a2afa0 100644 --- a/Codex/Skills/CN/AGENTS.md +++ b/Codex/Skills/CN/AGENTS.md @@ -1,5 +1,5 @@ - + # Sopify - 自适应 AI 编程助手 diff --git a/Codex/Skills/EN/AGENTS.md b/Codex/Skills/EN/AGENTS.md index bd68ff8..dcba08c 100644 --- a/Codex/Skills/EN/AGENTS.md +++ b/Codex/Skills/EN/AGENTS.md @@ -1,5 +1,5 @@ - + # Sopify - Adaptive AI Programming Assistant diff --git a/README.md b/README.md index fc0c990..7d5f71c 100644 --- 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--11.202509-orange.svg)](#version-history) +[![Version](https://img.shields.io/badge/version-2026--05--13.111757-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) @@ -50,6 +50,14 @@ Sopify uses project-level conventions to make critical steps visible. The basic | Decisions are invisible and non-auditable | Plan changes force re-confirmation — the AI cannot silently proceed | | Each session's learning is disposable | Plans, decisions, and reviews persist as reusable project assets | +## Architecture + +
+Sopify Architecture — Evidence & Authorization Layer +
+ +User input flows through a host adapter (Codex, Claude, etc.) into the Core Protocol, where every action is proposed, validated, gated, and receipted. The Validator is the sole authorizer — the host LLM is only a proposal source. Knowledge layers (blueprint, plan, history) persist across sessions and hosts. + ## Installation Two-step install (recommended for first-time review): diff --git a/README.zh-CN.md b/README.zh-CN.md index d5aa3d2..41e04b0 100644 --- 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--11.202509-orange.svg)](#版本历史) +[![版本](https://img.shields.io/badge/version-2026--05--13.111757-orange.svg)](#版本历史) [![欢迎PR](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](./CONTRIBUTING_CN.md) [English](./README.md) · 简体中文 · [快速开始](#快速开始) · [贡献者](./CONTRIBUTORS.md) @@ -50,6 +50,14 @@ Sopify 用项目级约定把关键节点变成可见流程。基础过程记录 | 决策不可见、不可审计 | 方案变更后必须重新确认 — AI 不能静默继续 | | 每个 session 的学习都是一次性的 | 方案、决策、审查结论沉淀为可复用的项目资产 | +## 架构 + +
+Sopify 架构 — 证据与授权层 +
+ +用户输入经过宿主适配器（Codex、Claude 等）进入核心协议层，每个操作都经历提议、校验、闸门、收据四步。Validator 是唯一授权者 — 宿主 LLM 只是提议来源。知识层（蓝图、方案、历史）跨 session 和宿主持久保留。 + ## 安装说明 两步安装（推荐首次使用时先审查再执行）： diff --git a/assets/sopify-architecture.png b/assets/sopify-architecture.png new file mode 100644 index 0000000..86092a6 Binary files /dev/null and b/assets/sopify-architecture.png differ diff --git a/assets/sopify-architecture.svg b/assets/sopify-architecture.svg new file mode 100644 index 0000000..1291a85 --- /dev/null +++ b/assets/sopify-architecture.svg @@ -0,0 +1,77 @@ + + + + + + + + + + + + + +Sopify — Evidence & Authorization Architecture +Cross-host AI workflow protocol · Validator is the sole authorizer + +User / Developer + + + + +Host Prompt Layers (proposal source, NOT authorizer) + +Codex Adapter + +Claude Adapter + + +Core Protocol — Evidence & Authorization Layer (Durable Core) + +ActionProposal +action_type · evidence · side_effect + +Validator +Sole authorizer · fail-closed +schema + facts + side-effects + +Execution Gate +deterministic action + +Handoff / Receipt +auditable machine facts + + + +User NL → Host maps to proposal → Validator authorizes → Gate selects action → Receipt exposed +Checkpoints (clarification · decision · plan · review · archive) pause the flow and wait for the user + + + + +Knowledge Layers (.sopify-skills/) + +Blueprint +long-term design baseline + +Plan +active working packages + +History +archived stable conclusions + +State +current execution state + +Core Invariant: Host LLM is only the proposal source — Validator is the sole authorizer (fail-closed) +Portable project state · Cross-host resume · Auditable decisions · Knowledge precipitation + +Legend: + +Core Protocol + +Knowledge + +Host Adapter +v2026-05-13 · evidentloop/sopify + \ No newline at end of file diff --git a/installer/validate.py b/installer/validate.py index 4e4a63c..4272164 100644 --- a/installer/validate.py +++ b/installer/validate.py @@ -127,6 +127,11 @@ def _build_bundle_smoke_env(*, payload_manifest_path: Path | None) -> dict[str, env = dict(os.environ) if payload_manifest_path is not None: env["SOPIFY_PAYLOAD_MANIFEST"] = str(payload_manifest_path) + # Keep bundle smoke focused on bundle/runtime assets instead of inheriting + # arbitrary user-level skills from the current machine. + isolated_home = Path(env.get("TMPDIR") or "/tmp") / "sopify-bundle-smoke-home" + isolated_home.mkdir(parents=True, exist_ok=True) + env["HOME"] = str(isolated_home) return env diff --git a/runtime/_yaml.py b/runtime/_yaml.py index 9694fc6..d28789d 100644 --- a/runtime/_yaml.py +++ b/runtime/_yaml.py @@ -97,7 +97,14 @@ def _parse_mapping(lines: Sequence[_Line], index: int, indent: int) -> Tuple[dic if line.content.startswith("- "): break key, remainder = _split_key_value(line) - if remainder == "": + if _is_block_scalar_marker(remainder): + value, index = _parse_block_scalar( + lines, + index + 1, + parent_indent=indent, + style=remainder, + ) + elif remainder == "": index += 1 if index < len(lines) and lines[index].indent > indent: value, index = _parse_block(lines, index, lines[index].indent) @@ -136,7 +143,15 @@ def _parse_list(lines: Sequence[_Line], index: int, indent: int) -> Tuple[list[A if _looks_like_mapping_entry(item_text): key, remainder = _split_key_value(_Line(indent=indent + 2, content=item_text, line_number=line.line_number)) item: dict[str, Any] = {} - if remainder == "": + if _is_block_scalar_marker(remainder): + value, index = _parse_block_scalar( + lines, + index, + parent_indent=indent, + style=remainder, + ) + item[key] = value + elif remainder == "": if has_child: value, index = _parse_block(lines, index, lines[index].indent) else: @@ -197,3 +212,53 @@ def _parse_scalar(value: str) -> Any: inner = value[1:-1] return inner.replace(r"\'", "'").replace(r'\"', '"') return value + + +def _is_block_scalar_marker(value: str) -> bool: + return value in {"|", "|-", ">", ">-"} + + +def _parse_block_scalar( + lines: Sequence[_Line], + index: int, + *, + parent_indent: int, + style: str, +) -> Tuple[str, int]: + if index >= len(lines) or lines[index].indent <= parent_indent: + return "", index + + block_indent = lines[index].indent + chunks: list[str] = [] + while index < len(lines): + line = lines[index] + if line.indent < block_indent: + break + if line.indent == parent_indent: + break + if line.indent < block_indent: + raise YamlParseError(f"Unexpected indentation at line {line.line_number}") + relative_indent = line.indent - block_indent + chunks.append((" " * relative_indent) + line.content) + index += 1 + + if style.startswith("|"): + text = "\n".join(chunks) + else: + paragraphs: list[str] = [] + current: list[str] = [] + for chunk in chunks: + if chunk == "": + if current: + paragraphs.append(" ".join(current)) + current = [] + paragraphs.append("") + else: + current.append(chunk) + if current: + paragraphs.append(" ".join(current)) + text = "\n".join(paragraphs) + + if not style.endswith("-"): + text += "\n" + return text, index diff --git a/runtime/skill_registry.py b/runtime/skill_registry.py index 85aea8b..abdd187 100644 --- a/runtime/skill_registry.py +++ b/runtime/skill_registry.py @@ -7,7 +7,7 @@ from typing import Dict, Iterable, Mapping, Optional, Sequence import re -from ._yaml import load_yaml +from ._yaml import YamlParseError, load_yaml from .builtin_catalog import load_builtin_skills from .models import RuntimeConfig, SkillMeta from .skill_schema import SkillManifestError, normalize_skill_manifest @@ -77,7 +77,7 @@ def _discover_under_root(self, root: Path, source: str) -> Iterable[SkillMeta]: def _read_skill(self, skill_file: Path, source: str) -> Optional[SkillMeta]: text = skill_file.read_text(encoding="utf-8") - front_matter = _parse_front_matter(text) + front_matter = _parse_front_matter(text, fail_closed=(source == "builtin")) skill_dir = skill_file.parent raw_manifest = _load_manifest(skill_dir / "skill.yaml") try: @@ -131,11 +131,16 @@ def _read_skill(self, skill_file: Path, source: str) -> Optional[SkillMeta]: ) -def _parse_front_matter(text: str) -> dict[str, object]: +def _parse_front_matter(text: str, *, fail_closed: bool = False) -> dict[str, object]: match = _FRONT_MATTER_RE.match(text) if not match: return {} - data = load_yaml(match.group(1)) + try: + data = load_yaml(match.group(1)) + except YamlParseError: + if fail_closed: + raise + return {} return data if isinstance(data, dict) else {} diff --git a/tests/test_installer_validate.py b/tests/test_installer_validate.py index 52dc0e1..70c933c 100644 --- a/tests/test_installer_validate.py +++ b/tests/test_installer_validate.py @@ -39,6 +39,8 @@ def test_smoke_uses_explicit_payload_manifest_env(self) -> None: self.assertEqual(output, "ok") env = mock_run.call_args.kwargs.get("env") or {} self.assertEqual(env.get("SOPIFY_PAYLOAD_MANIFEST"), str(payload_manifest)) + self.assertIn("HOME", env) + self.assertTrue(env["HOME"].endswith("sopify-bundle-smoke-home")) def test_failure_details_always_include_exit_status_and_command(self) -> None: with tempfile.TemporaryDirectory() as temp_dir: diff --git a/tests/test_runtime_config.py b/tests/test_runtime_config.py index 9dcca6f..840ab3b 100644 --- a/tests/test_runtime_config.py +++ b/tests/test_runtime_config.py @@ -51,3 +51,21 @@ class YamlLoaderTests(unittest.TestCase): def test_quoted_list_item_with_colon_is_parsed_as_string(self) -> None: payload = load_yaml('triggers:\n - "~go"\n - "status:"\n') self.assertEqual(payload["triggers"], ["~go", "status:"]) + + def test_folded_block_scalar_is_supported(self) -> None: + payload = load_yaml( + "name: sample\n" + "description: >-\n" + " first line\n" + " second line\n" + ) + self.assertEqual(payload["description"], "first line second line") + + def test_literal_block_scalar_is_supported(self) -> None: + payload = load_yaml( + "name: sample\n" + "notes: |\n" + " first line\n" + " second line\n" + ) + self.assertEqual(payload["notes"], "first line\nsecond line\n") diff --git a/tests/test_runtime_skill_registry.py b/tests/test_runtime_skill_registry.py index 6a07142..92cd023 100644 --- a/tests/test_runtime_skill_registry.py +++ b/tests/test_runtime_skill_registry.py @@ -323,3 +323,58 @@ def test_skill_registry_user_alias_precedence_prefers_public_aliases(self) -> No self.assertEqual(user_skill.source, "user") self.assertEqual(claude_skill.description, "claude-only") self.assertEqual(claude_skill.source, "user") + + def test_skill_registry_tolerates_external_front_matter_block_scalars(self) -> None: + with tempfile.TemporaryDirectory() as temp_dir: + workspace = Path(temp_dir) + user_home = workspace / "home" + skill_dir = user_home / ".claude" / "skills" / "block-scalar-skill" + skill_dir.mkdir(parents=True) + (skill_dir / "SKILL.md").write_text( + "---\n" + "name: block-scalar-skill\n" + "description: >-\n" + " first line\n" + " second line\n" + "---\n\n" + "# block-scalar-skill\n", + encoding="utf-8", + ) + (skill_dir / "skill.yaml").write_text( + "id: block-scalar-skill\nmode: advisory\n", + encoding="utf-8", + ) + + config = load_runtime_config(workspace) + skills = SkillRegistry(config, user_home=user_home).discover() + skill = next(item for item in skills if item.skill_id == "block-scalar-skill") + + self.assertEqual(skill.description, "first line second line") + self.assertEqual(skill.source, "user") + + def test_skill_registry_ignores_invalid_external_front_matter_when_manifest_is_valid(self) -> None: + with tempfile.TemporaryDirectory() as temp_dir: + workspace = Path(temp_dir) + user_home = workspace / "home" + skill_dir = user_home / ".claude" / "skills" / "invalid-front-matter" + skill_dir.mkdir(parents=True) + (skill_dir / "SKILL.md").write_text( + "---\n" + "name: invalid-front-matter\n" + "description:\n" + " broken\n" + "---\n\n" + "# invalid-front-matter\n", + encoding="utf-8", + ) + (skill_dir / "skill.yaml").write_text( + "id: invalid-front-matter\nmode: advisory\n", + encoding="utf-8", + ) + + config = load_runtime_config(workspace) + skills = SkillRegistry(config, user_home=user_home).discover() + skill = next(item for item in skills if item.skill_id == "invalid-front-matter") + + self.assertEqual(skill.name, "invalid-front-matter") + self.assertEqual(skill.description, "")