Merge pull request #65 from evidentloop/codex/feat-entry-preflight

feat: add intent-first entry preflight

Author: Li-Sanze

.sopify/blueprint/README.md

@@ -1,6 +1,6 @@
 # 项目蓝图索引
 
-状态: L2 active
+状态: L3 history-ready
 维护方式: Sopify 托管自动区块；本页只保留状态、当前目标、当前焦点与阅读入口。
 
 ## 当前目标
@@ -13,9 +13,9 @@
 ## 当前焦点
 
 <!-- sopify:auto:focus:start -->
-- 当前无活动 plan；MCP tool plane pilot 已完成 Codex-first 最小注册验证，其他宿主注册保留为证据型待办。
+- 当前无活动 plan；MCP tool plane 已完成 Codex-first 持久注册验证和 Claude 会话级只读调用验证，Qoder / Claude / Copilot 的后续持久注册仍按证据推进。
 - P8 Protocol Kernel & Runtime Retirement 已归档至 `../history/2026-06/20260605_p8_protocol_kernel_runtime_retirement`。
-- history 归档：已可用；最近归档：`../history/2026-07/20260626_mcp_tool_plane_pilot`。
+- history 归档：已可用；最近归档：`../history/2026-07/20260717_sopify_entry_preflight`。
 <!-- sopify:auto:focus:end -->
 
 ## 深入阅读入口
@@ -28,5 +28,5 @@
 - [Sopify 宿主接入规范 (Protocol v0)](./protocol.md)
 - [Skill 标准对齐蓝图](./skill-standards-refactor.md)
 - [变更历史](../history/index.md)
-- 最近归档：`../history/2026-07/20260626_mcp_tool_plane_pilot`
+- 最近归档：`../history/2026-07/20260717_sopify_entry_preflight`
 <!-- sopify:auto:read-next:end -->

.sopify/blueprint/design.md

@@ -356,6 +356,8 @@ ActionProposal 的标量 `side_effect` 字段表达粗粒度权限层级（`none
 
 **P8 关键变化**：主链机器真相从 6 个 runtime state 文件收窄为 2 个协议文件（active_plan + current_handoff）。不再存在 runtime gate/router 作为消费者；宿主通过 protocol entry 4 步读顺序消费。
 
+**会话入口稳定边界**：宿主先识别意图，consult / quick fix 不因陈旧状态进入接续链；`active_plan` 保持纯 `plan_id` 指针，Wave / 任务进度来自方案文件。显式审计非 active plan 时，Verifier 只读目标，宿主校验目标 `plan.md` digest 后仅通过 `sopify_writer` 写方案级 receipt，不切换 active plan / handoff。`session_id` 只作 provenance；只有用户明确并行开发、确认另一任务仍在运行，或写入前发现非本轮状态变化时，才停止当前有副作用的开发。
+
 **P8 偏好能力退场**：`user/preferences.md` 文件保留（persistence red-line 不可删），但旧 `preferences_preload` installer/doctor capability 在 P8 退场（runtime gate 删除后无自动预加载实现承接）。未来由 protocol entry 重新定义消费方式（TBD）。
 
 ### Legacy Mapping（P8 退场）
@@ -532,6 +534,7 @@ output.py 渲染层逐字段分类。只做分类，不做改造决策（改造
 
 - MCP 只承接 active plan / handoff 读取、protocol check 与受 guard 约束的低层 receipt 写入；分析、设计、开发、checkpoint 与 finalize 决策继续由 prompt/skill 和宿主负责。
 - repo-local server 为 `scripts/sopify_mcp_server.py`。Codex-first 注册已通过官方 `codex mcp get/add`、真实 stdio tool 调用和 no-op 复验。
+- 2026-07-17 Claude 会话级消费已通过：使用临时 MCP 配置加载同一 repo-local server，成功调用 `sopify.workspace_status_lite`；该证据不等同于持久注册。
 - Codex-first 表示验证顺序，不改变 Qoder、Claude、Copilot 的能力梯度或支持声明。其他宿主自动注册须复用同一最小契约并各自补证据。
 - 当前不把 Python/MCP 依赖供给、payload 打包、doctor 检查或多宿主配置抽象升级为产品面；只有后续证据证明重复痛点时再设计。
 

.sopify/blueprint/protocol.md

@@ -233,6 +233,8 @@ Sopify 接收后由 protocol admission 做结构校验准入，不由生产器
 
 **source**：**MUST** 标识验证器来源，供 Validator 和宿主解释 evidence provenance。是否基于 source 做差异化处理不在当前 normative scope。
 
+显式审计某个 plan 时，Verifier 仍保持只读并返回 `verdict / evidence / source`。宿主以 `subject_type=plan`、方案目录 `subject_ref` 和目标 `plan.md` 的 SHA-256 `revision_digest` 重新校验主体后，只能通过 `sopify_writer` 写入该方案未占用的 `verify_NNN` receipt；不得切换 active plan、改写 handoff 或修改方案正文。本规则只明确写入责任，不定义新的 Review Wire 或 evidence attachment schema。
+
 #### Verifier Read-Only Contract（P8 升格）
 
 P8 新增 Verifier 写入边界约束：
@@ -459,6 +461,8 @@ ExecutionAuthorizationReceipt 是 execute_existing_plan 授权通过后生成的
 
 **顺序设计原则**：active_plan 定位后**先读 plan.md 建立语义真相**，再读 current_handoff 作为恢复提示——避免 handoff 反过来变成第二真相源。
 
+`workspace_status_lite` 可用时只聚合上述文件事实；不可用时宿主直接按 4 步文件协议继续。MCP 不是 managed action 的入口依赖，也不输出工作流结论。
+
 ### 8.4 读取预算红线
 
 | 资产 | 默认读取 | 何时扩展 |
@@ -490,6 +494,10 @@ host MUST NOT 默认全量扫描 receipts/ 内容。
 
 写 `state/active_plan.json`、`state/current_handoff.json`、`plan/<id>/receipts/*.json` 时 MUST 走 `sopify_writer`。Host prompt 负责 request admission 与默认 spec workflow 入口，不负责生成机器真相、不生成计划优先级、不执行验证。
 
+`sopify_writer` 写 receipt 时 MUST 拒绝覆盖同名文件。调用方选择未占用的既有 `exec_NNN / verify_NNN / final` 标识；本协议不新增编号器、锁或重试机制。
+
+session 标识只用于 provenance，不单独构成并发冲突。只有用户明确要求同时开发、宿主确认另一任务仍在运行，或从本轮最近一次已验证快照到首次有副作用开发前出现非本轮已知写入导致的目标 `plan.md` digest / 匹配 handoff 变化，宿主才停止当前写入并询问一次。用户确认其他开发已停止后，宿主重读最新方案状态再继续。
+
 ### 8.7 链路失败模式（fail-open）
 
 | 步 | 文件缺失时 host 行为 |
@@ -501,14 +509,23 @@ host MUST NOT 默认全量扫描 receipts/ 内容。
 
 ### 8.8 读后分叉
 
-| 读到的事实 | Host 行为 |
-|---|---|
-| 无 active_plan | consult / new-plan |
-| 用户请求不指向当前 active_plan | 不自动接续；按 ActionProposal 处理 |
-| active_plan 存在且 continue_plan | 按 plan.md + tasks.md 继续 |
-| required_host_action = answer_questions | 只展示问题并等待回答 |
-| required_host_action = confirm_decision | 只展示选项并等待确认 |
-| plan.md 与 handoff 冲突 | 以 plan.md 为准；提示 state conflict |
+处理优先序固定为：**本轮用户意图 → active plan 有效性与主体绑定 → 仅消费与 active plan 匹配的 handoff / checkpoint**。同一轮同一冲突只检查、询问一次。
+
+| 用户意图与状态 | Host 行为 | 用户交互 |
+|---|---|---|
+| consult / unmanaged quick_fix，任意方案状态 | 完成当前请求，不进入接续链，不展示无关状态异常 | 无 |
+| new_plan，无 active plan | 创建方案并通过 writer 设置新指针 | 无 |
+| new_plan，active plan 无效或缺 `plan.md` | 创建方案并由 writer 替换无效指针 | 不追加清理确认 |
+| new_plan，active plan 有效 | 确认切换、合并或暂停 | 一次决策 |
+| continue_plan，active plan 有效 | 按 4 步协议和方案进度继续；缺 handoff / receipts 属正常降级 | 无 |
+| continue_plan，active plan 有效但用户明确指定其他方案 | 确认切换、合并或暂停 | 一次决策 |
+| continue_plan，用户明确指定有效方案但 active plan 缺失或无效 | 通过 writer 激活所指方案并继续 | 不追加清理确认 |
+| continue_plan / finalize，active plan 无效且未指定目标 | 说明阻断原因和可选目标后停车 | 一次决策 |
+| handoff 与 active plan 失配 | 以 `plan.md` 为准，提示一次并继续；下一次正常 handoff 写入自然替换旧提示 | 不等待 |
+| 首次进入 continue_plan，匹配 handoff 含 `answer_questions / confirm_decision` | 展示 checkpoint 后停车；失配 handoff 不触发 checkpoint | 一次响应 |
+| 用户正在回答匹配 checkpoint | 先绑定当前 plan 与 checkpoint，消费回答并通过 writer 更新一次；不得重显原问题 | 无；无法唯一绑定时提示一次 |
+| 显式审计非 active plan | Verifier 只读目标；宿主校验 `plan.md` digest 后通过 writer 写 `verify_NNN` receipt | 无；active plan / handoff 不变 |
+| 同一 active plan 出现 §8.6 并行推进信号 | 当前 session 不执行有副作用的开发；可继续只读审计，或等待用户确认后重读最新状态 | 一次决策 |
 
 ### 8.9 State 文件索引（P8 post-cutover: 2 文件）
 
@@ -517,6 +534,8 @@ host MUST NOT 默认全量扫描 receipts/ 内容。
 | `state/active_plan.json` | 定位：当前 plan_id | ignored |
 | `state/current_handoff.json` | 恢复：上次停哪 + required_host_action | ignored |
 
+`active_plan.json` 只保存 `plan_id`。Wave 和任务进度属于 `plan.md / tasks.md`，不得写入 active pointer。
+
 P8 删除的 state 文件：`current_run.json`、`current_plan.json`、`current_clarification.json`、`current_decision.json`、`current_gate_receipt.json`、`current_archive_receipt.json`、`last_route.json`。
 
 `plan/_registry.yaml` [DEPRECATED by P8]：P8 显式退场。不属于协议内核，不作为 host 接续入口，不作为 active plan pointer。协议校验 MUST fail if `_registry.yaml` appears in host entry path。删除理由和未来替代方案见 P8 design.md §4.3。

.sopify/blueprint/tasks.md

@@ -133,8 +133,7 @@ P0→P4c 主航道已全部完成。后续执行遵循以下原则：
   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
-- [ ] 补宿主级 first-hop ingress proof / diagnostics
-- [ ] MCP 注册扩展证据：沿用 Codex 试点的最小契约验证 Qoder / Claude / Copilot；仅在实测出现重复需求后再决定依赖打包、doctor 和多宿主自动注册
+- [ ] MCP 持久注册扩展证据：沿用 Codex 试点的最小契约验证 Qoder / Claude / Copilot；Claude 会话级只读调用已通过，但不代替持久注册。仅在实测出现重复需求后再决定依赖打包、doctor 和多宿主自动注册
 - [ ] `~compare` shortlist facade 收敛进默认主链路
 - [ ] blueprint 索引摘要更细粒度自动刷新
 - [ ] history feature_key 聚合视图
@@ -144,7 +143,7 @@ P0→P4c 主航道已全部完成。后续执行遵循以下原则：
 - [ ] 轻量化产品指标与 acceptance gate（首次上手步骤数、必需文件数、默认 workflow 必需 contract 数）
 - [ ] 产品层 ↔ 实现层 contract matrix 正式化（ownership / admission / lifecycle responsibilities）
 - [x] GitHub Release pipeline 建立（首次 release 创建 + tag 规范 + install 脚本端到端验证）
-- [x] 测试套件健康基线（pass rate ≥ 99%；当前基线 219 tests / 219 passed = 100%，另含 30 passed subtests）
+- [x] 测试套件健康基线（pass rate ≥ 99%；当前基线 226 tests / 226 passed = 100%，另含 34 passed subtests）
 - [ ] Skill packaging / localization governance：skill 打包格式、多语言资产管理、bundle 内 i18n 分层规范
 - [ ] Stale stub 检测与错误可观测性：~~诊断信息~~（PR #49 已补 `_stale_stub_diagnostic`）；剩余：自动建议 `--target <host>` 重装或降级到已安装版本（layer 3 auto-fix，用户已明确延后为 opt-in）
 - [x] Runtime output renderer scope audit：runtime/output.py 已随 P8 W2.10 退场，develop 输出归宿主/skill 所有
@@ -158,6 +157,7 @@ P0→P4c 主航道已全部完成。后续执行遵循以下原则：
 | Convention 入口兑现差距 | 已并入 | 已转入 P1.5 先行切片 |
 | ~replay 更多入口 | 终止 | P3b replay 能力已下线 |
 | 第三方 CLI 宿主能力边界治理（P4a→P4c bridge） | 已消费 | P4c 已消费，Host Capability Governance 已落地 design.md |
+| 宿主级 first-hop ingress proof / diagnostics | 已完成 | `20260717_sopify_entry_preflight` 已落地意图优先预检、最小状态事实、静态语义断言与一次 Codex 上下文隔离回放 |
 
 ## 明确延后项