Merge pull request #1 from sopify-ai/hotfix-plan-h-checkpoint-cancel

fix(runtime): close checkpoint cancel hotfix loop

Author: Li-Sanze

.sopify-skills/plan/20260326_phase1-2-3-plan/design.md

@@ -64,6 +64,42 @@
 - 核心字段名 `gate_status / blocking_reason / plan_completion / next_required_action` 不改名
 - `blocking_reason` 如需扩展，必须验证未知值消费兼容性
 
+承接边界（来自 Plan H 收口后的 carry-over）:
+- Plan H 负责 checkpoint correctness hotfix：唯一 pending 收敛、cancel bridge 放行、execution-confirm 污染冲突、doctor/status 协商态解释
+- Plan A 只承接 host-facing 语义召回增强，不重开 Plan H 已收口的状态机正确性修复
+
+非目标:
+- 不扩大全局语义理解；仅允许在局部 checkpoint 语境下增强召回
+- 不在本计划中改 runtime state model / handoff contract / resolution contract
+- 不把 polite prefix、同义词、更多 tail token 的扩展伪装成 Plan H 热修
+
+启动条件:
+- 仅在 `Plan H + Plan B1` 各自收口后，才进入 Plan A 子 plan
+- 启动前必须先登记真实漏判样本或用户反馈阈值，避免长期欠债无限后延，也避免过早侵入 control-plane 迁移窗口
+
+Case（后续拆分 Plan A 子计划时必须覆盖）:
+- Case A-1 | checkpoint 中 explain-only 咨询不应二次物化
+  - 场景: 已存在 `confirm_plan_package / confirm_decision` 等 pending checkpoint 时，用户提出“只分析、不改文件”的追问。
+  - 期望: 优先按 consult 回答并保持当前 checkpoint 身份稳定；除非用户明确提交 `继续 / 取消 / 1/2/...`，不得新建或重开 plan proposal。
+  - 验收: 同一 session 连续 explain-only 问答后，不新增 proposal `checkpoint_id`，且 `plan/` 下无新建方案包目录。
+- Case A-2 | 决策编号确认携带补充文本应稳健消费
+  - 场景: 用户以 `1/2` 开头确认决策，同时附带后续动作文本（如“并把 case 补进总纲”）。
+  - 期望: 先稳定消费 decision selection，再把后续文本作为 follow-up 意图处理，避免回退到“无效选择”或重复 decision checkpoint。
+- Case A-3 | 引用受保护 plan 资产的分析请求不应默认升级阻断
+  - 场景: 用户消息包含 `.sopify-skills/plan/...` 引用，但意图是“只分析/不改文件/判断是否认可”。
+  - 期望: 优先按 consult 或非阻断路径处理；仅在命中明确执行动作（如 `继续/next/开始/选择`）时进入 checkpoint 约束。
+  - 验收: 在同一 session 下，连续分析问答不会新增 `plan_proposal_pending`；`required_host_action` 不因“只分析”从 consult 漂移到阻断 checkpoint。
+- Case A-4 | “取消 checkpoint”应幂等收口，不得派生新 pending
+  - 场景: 当前处于 `confirm_decision / confirm_plan_package` pending，用户输入“取消这个 checkpoint”。
+  - 期望: 只取消当前 pending（或返回已取消状态），并恢复到稳定可继续态；不得创建新的 proposal 或切到其他 checkpoint 类型。
+  - 验收: 取消后 `current_handoff.required_host_action` 不再是新的 pending checkpoint；不会出现“取消动作触发新 plan_proposal_pending”的链路漂移。
+  - 验收补充: 当用户输入“取消这个 checkpoint”等含取消关键词的自由文本时，必须按 `cancel` 处理，并允许 `status=cancelled/resume_action=cancel` 在无 `selected_option_id` 的情况下生效，且不得派生新的 pending checkpoint。
+- Case A-5 | 逗号混合句的局部语境歧义应单独细化
+  - 场景: 当前为保留 `"取消这个 checkpoint，不要取消全部"` 这类混合句的可执行语义，`, / ，` 仍作为 cancel 成功边界。
+  - 已知残余风险: `"取消这个 checkpoint，为什么还会回到 pending"` 这类分析/追问句仍可能误命中 cancel。
+  - 期望: 在 Plan A 中统一细化逗号后从句的局部语境，区分否定补充、解释性补充与疑问补充；该项不回流到 Plan H。
+  - 验收: 保留 `"取消这个 checkpoint，不要取消全部"` 的 cancel 语义，同时降低 `"取消这个 checkpoint，为什么..."` 类问句的误触发率。
+
 ### Plan D | 对外定位与文档
 状态: committed after Plan A scope is stable
 

.sopify-skills/plan/20260326_phase1-2-3-plan/tasks.md

@@ -39,9 +39,11 @@ archive_ready: false
 - [ ] 4.2 为每个后续子 plan 显式写出 acceptance gate
 - [x] 4.3 在 `20260327_hotfix` 中冻结 `snapshot-only resolver / proposal session-only / state_conflict + abort / unique handoff exit`
 - [ ] 4.4 在升级版 Plan B1 中将 thin stub 校验、dual-host host-aware、payload index、ignore 默认值、legacy fallback reason code 作为硬门禁
-- [ ] 4.5 在 Plan A 中冻结 `ExecutionGate` 核心字段名与 `gate_status` 值集
-- [ ] 4.6 在 Plan B2 中明确“不改变 plan/blueprint/history contract”
-- [ ] 4.7 在 Plan C 中明确“bounded side task，不允许自由漫游”
+- [ ] 4.5 在 Plan A 子 plan 启动前登记 carry-over recall debt 与明确 non-goals，避免把 Plan H correctness hotfix 与后续语义召回增强混做一轮
+- [ ] 4.6 为 Plan A 子 plan 明确启动触发条件（真实漏判样本 / 用户反馈阈值），避免长期后延或提前侵入 B1 窗口
+- [ ] 4.7 在 Plan A 中冻结 `ExecutionGate` 核心字段名与 `gate_status` 值集
+- [ ] 4.8 在 Plan B2 中明确“不改变 plan/blueprint/history contract”
+- [ ] 4.9 在 Plan C 中明确“bounded side task，不允许自由漫游”
 
 ## 5. 明确延后方向
 - [ ] 5.1 若未来启动 B3，单独拍板 `plan_path` 新语义

CHANGELOG.md

@@ -6,6 +6,36 @@ This changelog is maintained manually (not auto-generated).
 
 ## [Unreleased]
 
+## [2026-03-28.220226] - 2026-03-28
+
+### Docs
+
+- Refined public documentation:
+  - `docs/dev/development-guidelines.md`
+
+### Runtime
+
+- Updated runtime internals:
+  - `runtime/checkpoint_cancel.py`
+  - `runtime/context_snapshot.py`
+  - `runtime/decision.py`
+  - `runtime/decision_bridge.py`
+  - `runtime/plan_proposal.py`
+
+### Tests
+
+- Updated automated coverage:
+  - `tests/test_installer_status_doctor.py`
+  - `tests/test_runtime_decision.py`
+  - `tests/test_runtime_engine.py`
+  - `tests/test_runtime_router.py`
+  - `tests/test_runtime_state.py`
+
+### Changed
+
+- Updated project files:
+  - `installer/inspection.py`
+
 ## [2026-03-28.002645] - 2026-03-28
 
 ### Runtime

Claude/Skills/CN/CLAUDE.md

@@ -1,5 +1,5 @@
 <!-- bootstrap: lang=zh-CN; encoding=UTF-8 -->
-<!-- SOPIFY_VERSION: 2026-03-28.002645 -->
+<!-- SOPIFY_VERSION: 2026-03-28.220226 -->
 <!-- ARCHITECTURE: Adaptive Workflow + Layered Rules -->
 
 # Sopify - 自适应 AI 编程助手

Claude/Skills/EN/CLAUDE.md

@@ -1,5 +1,5 @@
 <!-- bootstrap: lang=en-US; encoding=UTF-8 -->
-<!-- SOPIFY_VERSION: 2026-03-28.002645 -->
+<!-- SOPIFY_VERSION: 2026-03-28.220226 -->
 <!-- ARCHITECTURE: Adaptive Workflow + Layered Rules -->
 
 # Sopify - Adaptive AI Programming Assistant

Codex/Skills/CN/AGENTS.md

@@ -1,5 +1,5 @@
 <!-- bootstrap: lang=zh-CN; encoding=UTF-8 -->
-<!-- SOPIFY_VERSION: 2026-03-28.002645 -->
+<!-- SOPIFY_VERSION: 2026-03-28.220226 -->
 <!-- ARCHITECTURE: Adaptive Workflow + Layered Rules -->
 
 # Sopify - 自适应 AI 编程助手

Codex/Skills/EN/AGENTS.md

@@ -1,5 +1,5 @@
 <!-- bootstrap: lang=en-US; encoding=UTF-8 -->
-<!-- SOPIFY_VERSION: 2026-03-28.002645 -->
+<!-- SOPIFY_VERSION: 2026-03-28.220226 -->
 <!-- ARCHITECTURE: Adaptive Workflow + Layered Rules -->
 
 # Sopify - Adaptive AI Programming Assistant

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--03--28.002645-orange.svg)](#version-history)
+[![Version](https://img.shields.io/badge/version-2026--03--28.220226-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) · [Configuration](#configuration) · [Contributors](./CONTRIBUTORS.md)

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--03--28.002645-orange.svg)](#版本历史)
+[![版本](https://img.shields.io/badge/version-2026--03--28.220226-orange.svg)](#版本历史)
 [![欢迎PR](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](./CONTRIBUTING_CN.md)
 
 [English](./README.md) · 简体中文 · [快速开始](#快速开始) · [配置说明](#配置说明) · [贡献者](./CONTRIBUTORS.md)

docs/dev/development-guidelines.md

@@ -0,0 +1,81 @@
+# Sopify 开发规范
+
+面向维护者与协作者。本文只约束日常开发协作边界；发布步骤、版本更新与 release smoke 仍以 `docs/dev/release-process.md` 为准。
+
+---
+
+## 1. 目的与范围
+
+- 统一日常开发、合并与发布前的最小协作约束。
+- 保持 `main` 可继续集成，并让 stable release 的来源清晰可追踪。
+- 本文不重复 release 细节，不定义独立的 release branch 流程。
+
+---
+
+## 2. 主分支与发布线
+
+- `main` 是唯一长期主分支。
+- 对外发布版本使用 `tag + GitHub Release` 表达，不使用长期维护的 `release branch`。
+- 当前默认模式是：`main + topic branches + release tags`。
+- 只有在出现并行维护多个已发布版本、需要长期 backport 修复时，才重新评估是否引入 `release branch`。
+
+---
+
+## 3. 主题分支
+
+- 日常开发使用短生命周期主题分支，通过 MR/PR 合入 `main`。
+- 分支命名采用 `<type>/<topic>`。
+- 若改动明确归属某个计划窗口，采用 `<type>/<plan>-<topic>`，其中 `plan` 只使用短标识，不带完整目录名。
+
+推荐类型：
+
+- `hotfix`
+- `feature`
+- `refactor`
+- `docs`
+
+推荐示例：
+
+- `hotfix/plan-h-checkpoint-cancel`
+- `feature/plan-a-cancel-semantics`
+- `refactor/runtime-gate-cleanup`
+- `docs/dev-guidelines`
+
+不建议：
+
+- 直接把完整 plan 目录名塞进分支名
+- 一个分支同时承载 hotfix、语义增强、文档扩写等多个主题
+
+---
+
+## 4. 合并原则
+
+- `main` 默认通过 MR/PR 合入，不把直推 `main` 作为常规流程。
+- 一个分支只承载一个可验证的闭环主题。
+- 合入前应完成与改动直接相关的最小验证与回归。
+- `main` 上的提交应保持“可继续集成、可进入下一次 release”的基本质量。
+
+---
+
+## 5. 开发取舍
+
+- Hotfix 以最小闭环为原则，只修当前错误链路，不顺手扩词表、扩状态模型或新增流程守卫。
+- 本轮不解决但已识别的问题，应记录到对应的 plan 或 backlog，避免混入当前修复窗口。
+
+---
+
+## 6. 提交与验证
+
+- 提交粒度以单一闭环为单位，避免把不同性质的改动揉进同一个提交。
+- 新增共享源码文件后，必须显式纳入版本控制，不要依赖 `git commit -am` 覆盖新增文件。
+- 若改动影响 runtime 契约、checkpoint、bridge、status/doctor 或 installer 行为，必须补对应回归测试。
+- 对于文档-only 变更，不要求额外运行代码测试，但应避免与功能改动混提。
+
+---
+
+## 7. 与发布流程的关系
+
+- stable release 从 `main` 上的已合入提交生成。
+- README 首屏安装入口面向 latest stable release，不面向 `raw/main`。
+- `raw/main` 入口仅用于开发者文档、调试或 inspect-first 场景，不进入对普通用户的主安装链路。
+- 版本号、asset 渲染、GitHub Release 创建与 post-release smoke，统一遵循 `docs/dev/release-process.md`。