Merge pull request #7 from sopify-ai/feature/plan-b1-regression-smoke

chore: close plan B1 with smoke coverage and release-readme polishchore: close plan B1 with smoke coverage and release-readme polish

Author: Li-Sanze

.sopify-skills/plan/20260326_5-plan-20260326-phase1-2-3-plan-plan-20260326-ph/tasks.md

@@ -27,7 +27,8 @@ archive_ready: false
 
 ## 3. 后续子 plan 入口
 - [x] 3.1 先完成 `20260327_hotfix`，作为状态机一致性前置门禁
-- [ ] 3.2 在 3.1 解除状态链路阻塞后继续 `20260326_5-plan-20260326-phase1-2-3-plan-plan-20260326-ph`，作为升级版 Plan B1（global bundle + thin stub/pin + ignore + compatibility）
+- [x] 3.2 在 3.1 解除状态链路阻塞后继续 `20260326_5-plan-20260326-phase1-2-3-plan-plan-20260326-ph`，作为升级版 Plan B1（global bundle + thin stub/pin + ignore + compatibility）
+  收口记录：升级版 Plan B1 已完成 `global bundle + thin stub/pin + ignore + compatibility` 主线收口，并按“关键诊断出口可读、可定位、可给下一步，同时保留 JSON 机器契约”的口径接受 CLI 渲染层功能性完成；剩余 `workspace_hint / runtime_notes` 文本 polish 已降级为 post-B1 backlog。
 - [ ] 3.3 在 3.2 的 control-plane contract 稳定后推进 Plan A 子 plan
 - [ ] 3.4 在 Plan A 与 3.2 的对外语义都稳定后推进 Plan D 子 plan
 - [ ] 3.5 在 control-plane decoupling 稳定后，再评估是否需要推进 Plan B2
@@ -38,7 +39,8 @@ archive_ready: false
 - [ ] 4.1 为每个后续子 plan 显式写出 non-goals，避免范围滑移
 - [ ] 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 作为硬门禁
+- [x] 4.4 在升级版 Plan B1 中将 thin stub 校验、dual-host host-aware、payload index、ignore 默认值、legacy fallback reason code 作为硬门禁
+  验收记录：上述硬门禁已在 B1 子 plan 中通过实现、回归与 smoke 验证收口；program plan 与 child plan 现已同步该验收结论，后续只保留 post-B1 polish，不再回流到 B1 主线。
 - [ ] 4.5 在 Plan A 子 plan 启动前登记 carry-over recall debt 与明确 non-goals，明确挂住 2026-03-31 这轮 `A-1 / A-3 / A-4 / A-5` 追溯样本（如“还剩什么需要你确认”“为啥被网关卡住”“不要建包，只做确认项分析”“取消这个 proposal checkpoint”），避免把 Plan H correctness hotfix 与后续语义召回增强混做一轮
 - [ ] 4.6 为 Plan A 子 plan 明确启动触发条件（真实漏判样本 / 用户反馈阈值），并要求先补齐 `A-1 / A-3 / A-4 / A-5` 的正反例矩阵与状态不变量断言（`required_host_action / checkpoint_id / current_plan_proposal / current_decision / plan/` 副作用），避免长期后延或提前侵入 B1 窗口
 - [ ] 4.7 在 Plan A 中冻结 `ExecutionGate` 核心字段名与 `gate_status` 值集

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

@@ -6,6 +6,31 @@ This changelog is maintained manually (not auto-generated).
 
 ## [Unreleased]
 
+## [2026-04-02.224459] - 2026-04-02
+
+### Docs
+
+- Refined public documentation:
+  - `README.md`
+  - `README.zh-CN.md`
+
+### Scripts
+
+- Adjusted maintenance scripts:
+  - `scripts/check-install-payload-bundle-smoke.py`
+  - `scripts/release-preflight.sh`
+
+### Tests
+
+- Updated automated coverage:
+  - `tests/test_bundle_smoke.py`
+  - `tests/test_distribution.py`
+
+### Changed
+
+- Updated project files:
+  - `.sopify-skills/plan/20260326_5-plan-20260326-phase1-2-3-plan-plan-20260326-ph/tasks.md`
+
 ## [2026-04-02.162241] - 2026-04-02
 
 ### Runtime

CHANGELOG.md

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

Claude/Skills/CN/CLAUDE.md

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

Claude/Skills/EN/CLAUDE.md

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

Codex/Skills/CN/AGENTS.md

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

Codex/Skills/EN/AGENTS.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--04--02.162241-orange.svg)](#version-history)
+[![Version](https://img.shields.io/badge/version-2026--04--02.224459-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)
@@ -35,6 +35,15 @@ Sopify uses machine-readable protocols to make critical steps visible: when fact
 - Multi-stage work that keeps moving in the same repository instead of one-off edits
 - You're willing to manage progress with plan / blueprint artifacts and close out each stage
 
+## What You Get After Install
+
+- Your host is ready to run Sopify after install.
+- The first time you trigger Sopify in a project, it prepares the local `.sopify-runtime/`.
+- `status` shows the current host / workspace state.
+- `doctor` shows deeper installation and runtime diagnostics and repair guidance.
+
+This guide focuses on install visibility, verification, and stable first use; repository cleanup flows are intentionally out of scope here.
+
 ## Quick Start
 
 ### Installation
@@ -87,11 +96,20 @@ Notes:
 Installer behavior:
 
 - Installs the selected host prompt layer and the Sopify payload
-- When `--workspace` is omitted, this is still a complete install; Sopify bootstraps `.sopify-runtime/` on the first project trigger
-- Prewarms `.sopify-runtime/` when `--workspace` is provided
-- Use `python3 scripts/sopify_status.py --format text` to inspect the support matrix and current workspace state
-- Use `python3 scripts/sopify_doctor.py --format text` to inspect payload, bundle, and smoke diagnostics
-- `status` / `doctor` surface the current path directly: `payload bundle: source_kind=global_active|legacy_layout|unresolved`, `payload outcome: ...`, and `workspace outcome: stub_selected [continue]` when a workspace stub is healthy
+- A standard install makes your host ready to run Sopify; most users do not need `--workspace`
+- Sopify prepares `.sopify-runtime/` the first time you trigger it in a project workspace
+- `--workspace` is an advanced prewarm path for maintainers, CI, or explicit repository setup
+
+### Verify Your Install
+
+```bash
+python3 scripts/sopify_status.py --format text
+python3 scripts/sopify_doctor.py --format text
+```
+
+- `will bootstrap on first project trigger`: the host install is ready and the project-local runtime has not been prepared yet
+- `workspace outcome: stub_selected [continue]`: the workspace runtime entry is healthy
+- Payload or bundle corruption errors (for example `global_bundle_missing`, `global_bundle_incompatible`, or `global_index_corrupted`): repair the install and retry
 
 ### Choose an Entry by Task Size
 
@@ -103,6 +121,8 @@ Installer behavior:
 
 ### First Use
 
+After install, open Codex or Claude inside a repository and paste one of the prompts below.
+
 ```bash
 # Simple task
 "Fix the typo on line 42 in src/utils.ts"
@@ -301,14 +321,6 @@ Use `--workspace` only for maintainer validation, CI, or when you explicitly wan
 python3 scripts/install_sopify.py --target codex:en-US --workspace /path/to/project
 ```
 
-### Q: How do I migrate existing repositories?
-
-Use `python3 scripts/sopify_status.py --format text` first, then `python3 scripts/sopify_doctor.py --format text` if the workspace still looks suspicious.
-
-- New repositories: no manual migration is needed. A normal install is already complete, and Sopify bootstraps `.sopify-runtime/` on the first project trigger.
-- Already bootstrapped repositories: keep the existing `.sopify-runtime/`. A healthy thin-stub workspace should show `workspace outcome: stub_selected [continue]`.
-- Old vendored repositories: still supported, but no one-click migrator is provided in this release. If `status` / `doctor` show `legacy_fallback_selected [warn]`, refresh the local install and trigger Sopify in that repository again. If the surface instead shows `global_bundle_missing`, `global_bundle_incompatible`, or `global_index_corrupted`, repair the installed payload first and retry.
-
 ### Q: How do I reset learned preferences?
 
 Delete or clear `.sopify-skills/user/preferences.md`; keep `feedback.jsonl` only if you still want the audit trail.

README.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--04--02.162241-orange.svg)](#版本历史)
+[![版本](https://img.shields.io/badge/version-2026--04--02.224459-orange.svg)](#版本历史)
 [![欢迎PR](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](./CONTRIBUTING_CN.md)
 
 [English](./README.md) · 简体中文 · [快速开始](#快速开始) · [配置说明](#配置说明) · [贡献者](./CONTRIBUTORS.md)
@@ -35,12 +35,21 @@ Sopify 用机器可读协议把关键节点变成可见流程：缺事实时停
 - 在同一仓库中持续推进多阶段工作，而不是一次性改动
 - 愿意用 plan / blueprint 管理进展，并在阶段完成后持续做收口
 
+## 安装后你会得到什么
+
+- 安装后，你的宿主已可运行 Sopify。
+- 首次在项目仓库里触发 Sopify 时，才会准备本地 `.sopify-runtime/`。
+- `status` 用来看当前 host / workspace 状态。
+- `doctor` 用来看更深的安装与运行时诊断及修复建议。
+
+本文只聚焦安装可见性、自检与首次使用路径，不展开仓库清理流程。
+
 ## 快速开始
 
 ### 安装
 
 ```bash
-# 推荐：official stable one-liner
+# 推荐：稳定版一行安装
 curl -fsSL https://github.com/sopify-ai/sopify/releases/latest/download/install.sh | bash -s -- --target codex:zh-CN
 
 # 两步安装：先下载，确认后再执行
@@ -61,7 +70,7 @@ Get-Content sopify-install.ps1 -TotalCount 40
 
 ```bash
 bash scripts/install-sopify.sh --target codex:zh-CN
-python3 scripts/install_sopify.py --target claude:en-US --workspace /path/to/project
+python3 scripts/install_sopify.py --target claude:zh-CN --workspace /path/to/project
 ```
 
 支持的 `target`：
@@ -87,11 +96,20 @@ python3 scripts/install_sopify.py --target claude:en-US --workspace /path/to/pro
 安装后行为：
 
 - installer 会安装宿主提示层，并在宿主根目录安装 Sopify payload
-- 不传 `--workspace` 时，这仍是完整安装；后续首次在项目仓库触发 Sopify 会自动 bootstrap `.sopify-runtime/`
-- 传入 `--workspace` 时，会额外预热目标仓库的 `.sopify-runtime/`
-- 可用 `python3 scripts/sopify_status.py --format text` 查看支持矩阵与当前 workspace 状态
-- 可用 `python3 scripts/sopify_doctor.py --format text` 查看 payload / bundle / smoke 诊断结果
-- `status` / `doctor` 会直接展示当前路径：`payload bundle: source_kind=global_active|legacy_layout|unresolved`，以及 `payload outcome`、`workspace outcome: stub_selected [continue]` 这类结果行
+- 默认安装后，宿主已可运行 Sopify；大多数用户不需要 `--workspace`
+- 首次在项目仓库里触发 Sopify 时，才会准备 `.sopify-runtime/`
+- `--workspace` 适用于维护者、CI 或显式预热仓库的高级路径
+
+### 安装后怎么确认正常
+
+```bash
+python3 scripts/sopify_status.py --format text
+python3 scripts/sopify_doctor.py --format text
+```
+
+- `will bootstrap on first project trigger`：宿主安装已就绪，项目侧 runtime 还未准备，这是正常状态
+- `workspace outcome: stub_selected [continue]`：workspace runtime 入口健康
+- 如果 doctor 报出 payload 或 bundle 损坏类错误（例如 `global_bundle_missing`、`global_bundle_incompatible`、`global_index_corrupted`），先修复安装，再重试
 
 ### 根据任务规模选入口
 
@@ -103,6 +121,8 @@ python3 scripts/install_sopify.py --target claude:en-US --workspace /path/to/pro
 
 ### 首次使用
 
+安装完成后，在仓库目录中打开 Codex 或 Claude，直接粘贴下面任一条提示即可开始。
+
 ```bash
 # 简单任务
 "修复 src/utils.ts 第 42 行的 typo"
@@ -301,14 +321,6 @@ plan:
 python3 scripts/install_sopify.py --target codex:zh-CN --workspace /path/to/project
 ```
 
-### Q: 已有仓库怎么迁移？
-
-先跑 `python3 scripts/sopify_status.py --format text`，如果现场仍然可疑，再跑 `python3 scripts/sopify_doctor.py --format text`。
-
-- 新仓库：不需要手动迁移。默认安装已经完整，首次在项目里触发 Sopify 时会自动 bootstrap `.sopify-runtime/`。
-- 已经 bootstrap 过的仓库：保留现有 `.sopify-runtime/` 即可。健康的 thin stub workspace 应显示 `workspace outcome: stub_selected [continue]`。
-- 旧的 vendored 仓库：当前版本仍兼容，但不提供一键迁移器。如果 `status` / `doctor` 出现 `legacy_fallback_selected [warn]`，先刷新本地安装，再回到该仓库重新触发 Sopify；如果出现的是 `global_bundle_missing`、`global_bundle_incompatible` 或 `global_index_corrupted`，则先修复已安装 payload，再重试。
-
 ### Q: 用户偏好如何重置？
 
 删除或清空 `.sopify-skills/user/preferences.md` 即可；`feedback.jsonl` 可按需保留用于审计。