py-wlcli 0.8.0__py3-none-any.whl

wl_cli/vendors/sop_doc/git-dev-sop.md

@@ -0,0 +1,220 @@
+# Git 开发 SOP —— 双主线 + AI 工具链
+
+> 本 SOP 定义一套统一的 Git 开发与发布流程，供所有经 `wl init` 生成的项目（及团队自有仓库）采用。
+> **适用范围**：默认适用——读者具备 Claude Code + `wl` + gstack（`/ship`）工具链，仓库托管在 GitLab 且采用下方 `main`+`develop` 双主线。不满足前置的仓库（无 gstack//ship、非 GitLab、或走单分支流）需先补齐前置或按自身模型裁剪本 SOP。
+> **来源与分发**：本章由 `wl-cli` 仓库维护，权威在线版见该仓库；经 `wl init` 分发到各生成项目。深层 git 细则（冲突/回滚/worktree 机制）以**外链**方式引用权威文档（各仓库本地若无，以在线版为准），本文只写日常可直接执行的部分，不重复抄细则。
+
+## 0. 分支模型与铁律
+
+```
+main(生产发布)
+   ▲
+   │  /ship（常规发布 bump 入口）      hotfix/<patch>（显式例外，admin 门禁）
+   │        │                                │
+   │        ▼                                ▼
+   │     [VERSION bump]               main ← hotfix（PATCH + tag）
+   │
+develop(集成基线, 不 bump)  ◄── feature/* 经 MR 合入
+   │                                └── hotfix 合 main 后立即回流 develop
+   └── feature/<任务>   （开发道，从 develop 建）
+```
+
+**铁律（违反 = 事故）**
+1. 不直接在 `main`/`develop` 上提交或 push。一切改动从分支走。
+2. 分支命名按意图取前缀：`feature/<任务>`（新功能）、`fix/<任务>`（缺陷修复）、`chore/<任务>`（杂项维护）、`feat/<任务>`（轻量新功能）、`research/<任务>`（调研）、`implement/<任务>`（落地既定方案）、`refactor/<任务>`（重构，不改行为）、`release/<版本>`（发布道）、`hotfix/<版本>`（紧急修复，见 §3.3）；不另设新前缀。
+3. **常规发布**的版本 bump 唯一入口是 `/ship`；**hotfix 是显式例外**（PATCH 级，走 §3.3 的受保护 main 门禁）。除此两者外，任何分支合入都不动版本。
+4. 绝不 `push --force`。需要改写历史用 `revert`，或经 `git rebase` 后 `--force-with-lease`（仅限自己独占的分支）。
+5. 凭据/密钥永不入库：任何 diff 或提交含密钥即阻断。提交前运行项目预检（`wl test` + 相关 CI 门）。
+6. `develop` 永远可以拿来开新分支；若集成基线长期落后于 `main`（含 hotfix 未回流），先修复再开新活。
+
+## 1. 开发道（日常：feature → develop）
+
+### 1.1 隔离工作区
+
+开始功能前，先确认或创建隔离工作区（按 `using-git-worktrees` 的探测与建树纪律）：
+
+- 已在独立 worktree？直接使用，**不要重复开第二个**。
+- 普通 checkout 且当前在 `develop`：征得同意后建 worktree（或按团队约定直接建）：
+
+```bash
+# 确保 develop 最新
+git checkout develop && git pull origin develop
+# 建树前确认目录会被 git 忽略，否则先入 .gitignore（防误提交整棵 worktree）
+git check-ignore -q .worktrees || echo ".worktrees/" >> .gitignore
+# 从 develop 建 feature 分支到独立 worktree
+git worktree add -b feature/<任务> .worktrees/<任务> develop
+```
+
+> `wl init` 生成的仓库 `.gitignore` 默认已含 `.worktrees/`；老仓库按上面 check-ignore 自行补。
+
+Claude Code 原生 worktree 工具（`EnterWorktree`）优先于手敲 `git worktree add`——原生工具自己管目录、建分支与清理，避免幽灵状态。
+
+### 1.2 开发循环
+
+1. **先 TDD**：写测试 → 看失败 → 实现 → 转绿。库/服务的测试与实现同 commit。
+2. 每个逻辑单元完成后跑项目质量门（`wl test` / `wl format` + ruff，`wl debug` 已废弃勿用）：
+
+```bash
+wl test        # 全量测试（覆盖率门槛看项目配置）
+wl format      # 格式化
+ruff check .   # lint
+```
+
+3. 提交用 **Conventional Commits**（`ecc:git-workflow` 规则表）：
+
+| 类型 | 用途 |
+|---|---|
+| `feat` / `fix` | 新功能 / 缺陷修复 |
+| `docs` / `style` | 文档 / 纯格式 |
+| `refactor` | 重构（不改行为） |
+| `test` / `chore` | 测试 / 维护杂项 |
+| `ci` / `perf` / `revert` | CI / 性能 / 回滚 |
+
+```
+<type>(<scope>): <subject>      # subject 祈使语气、≤50 字符
+
+[body：为什么，而不是改了什么]
+[footer：Breaking changes / Closes #issue]
+```
+
+**每 commit 一个逻辑单元**（可 `git bisect`、可被 LLM 读懂）。小改（<50 行、<4 文件）单 commit 即可。
+
+4. 一个 feature 分支内多个逻辑单元允许拆多个 commit；WIP 态用 `WIP:` 前缀，由后续吸收（见 §3.2 发布时由 /ship 收敛）。
+
+### 1.3 合入 develop（MR）
+
+开发完成、本地质检通过后：
+
+1. 与 `develop` 同步（保持分支短命、降低冲突）：
+   ```bash
+   git fetch origin && git rebase origin/develop    # 自己独占的分支用 rebase；多人共享则 merge
+   ```
+2. push 分支并开 GitLab MR → `develop`：
+   ```bash
+   git push -u origin feature/<任务>
+   glab mr create --target-branch develop           # 或经 Claude Code 交互创建
+   ```
+3. MR 描述含：What / Why / How / Testing 勾选。
+4. **Review 通过 + CI 绿 → merge**（squash/rebase 合入，保持 develop 线性）。**不 bump 版本。**
+5. 合入后立即清理（**顺序不能反**——git 拒绝删除正被另一 worktree 检出的分支；squash 合入后 feature 尖非 develop 祖先，`-d` 会报 not fully merged，须用 `-D`）：
+   ```bash
+   git worktree remove .worktrees/<任务>            # 先从任何 checkout 移除该 worktree
+   git branch -D feature/<任务>                     # 再删分支
+   ```
+
+## 2. 并行升级（需要时才并行）
+
+**默认一个人一个任务顺序做**。仅在以下判据同时成立时，才把任务拆给多个 agent 并行（`dispatching-parallel-agents`）：
+
+- 任务可拆成 **2 个及以上相互独立**的子任务；
+- 子任务之间**无共享状态**（不同文件/子系统、不会互相干扰）；
+- 每个子任务边界清晰，可独立验证。
+
+**不并行**的情形：失败同根因（可能互相牵连）、需要全局上下文、会编辑同一批文件、探索性调试。
+
+做法：
+
+1. 先定接口与边界（谁改什么、合并点在哪），再派发——**绝不并行前不定义契约**。
+2. 一个子任务一个 worktree、一个 agent、一条自包含指令（scope/goal/constraints/expected output）。
+3. 多个派发放同一条消息里 → 并行执行；各 agent 之间不共享你的会话上下文。
+4. 收齐后你逐个 review 摘要、**核对无冲突改动**、跑全量测试、再统一整合（§1.3 合入 develop）。
+
+**Orca（`orca-cli`）承担"多窗口/终端/内嵌浏览器"增强面**，当任务同时要盯多个工作区、终端或页面时用它；单一顺序任务不需要 Orca。Orca 的 worktree 是应用层追踪视图，**不等于** git worktree——裸 git worktree 管理（§1.1/§1.3）仍以 git 为准。需要更强的"监督式协调"（Run/Task/Dispatch、等 worker_done、决策门、跨 agent 消息流）时，才升到 Orca `orchestration` 面——那是另一档纪律，默认不启用。
+
+## 3. 发布道
+
+### 3.1 版本源（单一权威）
+
+- 每个 repo 维护 **`VERSION` 文件 = 三段 semver `X.Y.Z`**，是**唯一权威**版本源。
+- `pyproject.toml`、`rust/Cargo.toml` 等处声明的版本是**派生值，不独立**——发布时 **follow VERSION 同步**，保持三者一致。
+- git tag 语义化 **等于 VERSION**（`vX.Y.Z`）。
+- 版本仅在发布道变更：常规发布经 `/ship`；hotfix 经 §3.3。CI 应有校验：VERSION 与各派生文件不一致即阻断（见 §6）。
+
+### 3.2 常规发布（release → main：/ship）
+
+**常规发布唯一 bump 入口是 `/ship`**（gstack）：它把"merge 基线 → 测试 → 审 → 覆盖率 → bump VERSION+派生 → 拆提交 → push → 开 MR → 同步文档"收成一条非交互流水线。**人不手工 bump 版本、不手工写 CHANGELOG、不手工 commit/push 发布。**
+
+```bash
+# 1) 从集成基线开 release 分支（/ship 拒绝在 base 分支上跑）
+git checkout develop && git pull origin develop
+git checkout -b release/<新版本>
+# 2) 触发流水线（分支上自动 merge origin/main、跑测/审/覆盖、bump VERSION+派生、拆提交、push、开 MR→main）
+/ship
+```
+
+/ship 行为契约（务必让团队知道这些停/不停点）：
+- **不会停**：未提交改动、PATCH 版本号选择、CHANGELOG 内容、提交消息、多文件拆 commit——自动处理。
+- **会停问你**：MINOR/MAJOR 级版本 bump、复杂冲突、发布前 review 需要你判断的项、覆盖率低于门槛、计划项未完成、CI 失败。
+- 输出：MR/PR 标题带 `v<版本>` 前缀 + review + 自动同步的文档。
+- **规则**：绝不 force-push；绝不在 `main`/`develop` 上直接跑；测试不过不发版。
+- 若 /ship 的版本工具尚不能自动写某派生文件（如 `rust/Cargo.toml`），发布人负责把派生文件按 VERSION 手工同步后再提交——VERSION 权威不变。
+
+### 3.3 紧急修复（hotfix）
+
+正规做法是**双合并**：hotfix 只进 main 会让 develop 落后于生产修复（铁律 6 的红线）。流程（细则参考权威文档 §3.4，此处给可执行步骤）：
+
+```
+main ──► hotfix/vX.Y.Z ─────────► 合回 main（受保护门禁）─► tag vX.Y.Z
+   ▲                                  │
+   │                                  ├──► 立即回流 develop（ff 或 merge）
+   └──────────────────────────────────┘
+```
+
+1. 从 `main` 建 `hotfix/<patch版本>`：`git checkout -b hotfix/vX.Y.Z main`。
+2. 修复 + **PATCH bump**（VERSION 的 Z 位 + 派生文件同步）。
+3. 质量门通过 → 打包 patch → 提 MR → `main`。
+4. **受保护 main 门禁**：必须 MR + maintainer 审批 + CI 绿才合（GitLab 保护分支规则；repo 管理员是兜底执行者，不是绕过门禁的通道）。main 上直接 push 一律禁止。
+5. 合 main 后立即打 tag `vX.Y.Z` 并推送。
+6. **立即回流 develop**：develop 无并行分叉时 `git checkout develop && git merge --ff-only origin/main`；有分叉则把 hotfix merge 进 develop（消除落后基线）。
+7. 清理分支/worktree（先 remove 再 `-D`，见 §1.3.5）。
+
+### 3.4 发布后
+
+- 常规发布 MR 合到 `main` 后打 tag（等于 VERSION）并推送。
+- `develop` 收编 release 分支上仅属于发布的内容（版本 bump/CHANGELOG/发布期修正）：无分叉用 ff 到 main tip，有分叉用 merge——保证下一个 release 从完整 develop 起。
+- 清理：删 release/hotfix 分支与临时 worktree。
+
+## 4. 冲突与回滚速查
+
+冲突解决、误提交撤销、revert 的完整细则见权威文档（`docs/chapters/chapter-3-gitflow.md` §3.5，在线版为准）；速查：
+
+| 场景 | 命令 |
+|---|---|
+| 解冲突 | `git status` → 修冲突标记 → `git add` → `git commit` |
+| 撤销上一 commit（保留改动） | `git reset --soft HEAD~1` |
+| 撤销已推送提交 | `git revert HEAD`（不要 force-push） |
+| 丢了暂存/工作区 | `git stash list` / `git stash pop` |
+| 分支被误删 | `git reflog` 找回 commit → `git branch <name> <sha>` |
+
+## 5. 工具 ↔ 环节映射表
+
+| 环节 | 用什么 | 触发信号 |
+|---|---|---|
+| 建隔离 worktree | `using-git-worktrees` / Claude Code `EnterWorktree` | 开始 feature、要隔离当前分支 |
+| git 细则（模型/冲突/回滚） | 权威文档 chapter-3 §3.x（在线版） | 任何 git 机制疑问 |
+| 分支/提交规范 | `ecc:git-workflow` | 命名、commit message、rebase 纪律 |
+| 并行分解 | `dispatching-parallel-agents` | 2+ 独立子任务、无共享状态 |
+| 多窗口/终端/浏览器 | `orca-cli` | 要同时盯多工作区/页面 |
+| 监督式多 agent 协调 | Orca `orchestration` | 要等 worker_done、决策门、消息流（默认不开） |
+| 提交/合入 develop | 人：`glab mr create`（Conventional Commits） | 功能完成、CI 绿 |
+| **常规发布（bump 入口）** | **`/ship`** | 把 develop 成果发到 main |
+| 紧急修复（bump 例外） | `hotfix/<patch>` + admin/门禁合 main | 生产缺陷要立刻修 |
+
+## 6. 落地与过渡
+
+1. **单一版本源校验（CI）**：`VERSION` 与 `pyproject.toml`/`rust/Cargo.toml` 派生文件不一致 → CI 阻断。本 SOP 落地时先在 wl 自身仓库加上并修掉现存漂移。
+2. **Dogfood**：下一次 wl 自身发布按本 SOP §3.2/§3.3 走一遍，验证 /ship + 派生同步流程现实可行；走不通处回填本节或归档为工具适配任务。
+3. **分发同步**：本 SOP 经 `wl init` 按 `vendors/config/template_config.toml` 的 `[sop_templates]` 条目**逐字复制**到生成项目（`git_dev_sop` → `docs/git-dev-sop.md`），随后把正文中的包名记号改写为生成项目自己的包名。注意：与 `.wl/.templates.json` 跟踪的 **config** 模板不同，**SOP 副本不参与哈希同步**——不做漂移检测、不保留用户修改，每次 `wl init` 直接覆盖。本仓内两份副本（`vendors/sop_doc/git-dev-sop.md` 权威 + `docs/git-dev-sop.md` 部署）由 `tests/test_sop_generator.py` 断言字节相等；改本文后跑该测试即可。
+4. **团队迁移**：新 repo 默认生效；存量 repo 按其当前分支模型对照「适用范围」，缺前置的补齐后切换，并列出迁移过渡期的例外。
+
+---
+
+## 附：落地检查
+
+- [ ] 分支规范：按意图取标准前缀（`feature`/`fix`/`chore`/`feat`/`research`/`implement`/`refactor` 等）从 develop 建，MR 合 develop，无 main/develop 直推
+- [ ] 每个逻辑单元一个 Conventional Commits，WIP 有前缀
+- [ ] `.worktrees/` 已在 .gitignore；worktree 用完先 remove、分支再用 `-D` 清理
+- [ ] develop 常规不 bump；版本只经 `/ship`（常规）或 hotfix（例外）变更
+- [ ] VERSION = 三段 X.Y.Z，派生文件（pyproject/Cargo）follow VERSION 一致
+- [ ] hotfix：双合并 + tag + 立即回流 develop；main 合入走受保护门禁
+- [ ] 密钥不入库、绝不 force-push

wl_cli/vendors/sop_doc/industrial-standard-sop.md

@@ -0,0 +1,145 @@
+# 按工业化标准补齐仓库 SOP（industrial-standard-sop）
+
+> 定位：repo 无关的工业化基准 + 差距审计运行手册 + 修复推进指引。可复制到任意 Python/Rust
+> （或通用）仓库执行。首次 dogfood 对象与产出实例见文末「附录 A」。
+
+## 1. 概述
+
+本 SOP 把一个仓库从「能用」推进到「工业化基线」。它做两件事：
+
+1. **给基准**：一套 repo 无关的「五支柱工业化基准」checklist，每个检查项都带达标判据（可证伪）。
+2. **给方法**：如何跑一次**只读差距审计**（既对照外部通用标准，也核对「仓库自己文档里宣称的
+   标准是否真的被强制」），把差距沉淀成分级 remediation ticket，再逐个走
+   brainstorm → spec → plan → implement 闭环。
+
+**关键视角：审计必须「双基准」。** 只看外部标准会漏掉「名实不符」——仓库文档声称有质量门/
+有 CI/有安全扫描，但代码里根本没有执行载体。自宣兑现度审计往往比外部标准审计找到更多真实缺口。
+
+**范围与红线**：审计阶段只读取证、不修改代码；remediation 一律进 ticket，不在审计阶段顺手改。
+
+## 2. 工业化五支柱基准（checklist）
+
+评级：`ok`（已达标）| `partial`（部分达标）| `missing`（缺失）。每条记录证据
+（`文件:行` / 命令输出 / 政策引用）+ 置信度（`CONFIRMED` 亲验 / `PLAUSIBLE` 待复核）。
+
+### 支柱 A：代码工程质量
+- A1 lint/format：lint 与 format 检查零错误零 diff，且**有执行载体**（本地命令 + hook + CI 至少一处强制）。
+- A2 类型检查：静态类型检查真实在跑（不是文档写了但命令不可执行 / 无人跑），错误基线**可追踪且收敛**；
+  基线配置是「诚实收紧」（无大量 `type: ignore`、无 per-module 整段 disable）。
+- A3 测试：测试有断言质量（非纯冒烟）；无 flaky/时间依赖失控；**门禁是全量**——CI/hook 不得用
+  `-k`/skip/xfail 静默豁免某条测试而无线索。
+- A4 覆盖率：覆盖率阈值声明一致（本地命令 / 配置文件 / CI 三方一致），且**口径可证实**
+  （如分支覆盖率有存档快照，不是只留一句声明）。
+- A5 dead code：有系统性清理入口，且 lint 不全局吞掉未用导入/变量（F401/F841 类不被无差别 ignore）。
+- A6 质量门真实：文档宣称的「质量门」（debug/check 命令、CI 门禁）确实串联了它声称的全部检查，
+  而非只跑子集。
+
+### 支柱 B：CI/CD 与发布
+- B1 分级 pipeline：lint/轻量先行，构建/发布按分支分层；feature 分支不被重活拖垮。
+- B2 构建可复现：锁文件入库（Python lock + Cargo.lock）；安装用锁定模式（`sync --locked`）；
+  基础镜像 pin 到 patch/digest；构建工具版本固定。
+- B3 产物可溯源：构建产物有清单/校验和（sha256 manifest），与 pipeline+commit 绑定；CI 配置文件
+  从仓库可找到（含 include 链或路径接线有据可查）。
+- B4 发布安全：生产级发布有**人工门禁**（manual/环境门禁），不是任意 tag/分支自动推生产；
+  凭据走 CI 变量、最小暴露、可轮换。
+- B5 版本纪律：单一版本源由工具 + **CI 断言**强制（多文件版本一致），changelog 按版本分节且有条目纪律。
+- B6 失败路径：有发布失败/yank/重发/回滚的 runbook，不是只有「git revert」。
+
+### 支柱 C：安全与供应链
+- C1 依赖漏洞审计：Python 与 Rust（如适用）漏洞审计有**入口**（CI job/hook：uv audit / cargo audit /
+  GitLab Dependency Scanning 等）并纳入发布门禁。
+- C2 凭据卫生：secret 扫描入口存在（gitleaks/Secret-Detection 类）；**git 历史无已提交凭据**
+  （有则先轮换再清历史）；CI 无明文密钥。
+- C3 SBOM：发布流程产出依赖 SBOM。
+- C4 license/来源合规：Rust crate/依赖有 license 与来源合规检查（cargo deny 类）；依赖来源可信、有 pin。
+- C5 CI 最小权限：pipeline 用到的 runner/credential/token 最小化，无第三方镜像 + `TRUSTED_HOST`
+  之类降低可复现/可审计性的做法而无说明。
+
+### 支柱 D：文档与工程规范
+- D1 占位符零泄漏：正式文档（README/CONTRIBUTING/安装指南）无模板占位符（`your-username`、
+  `test-project` 等）、无 stub。
+- D2 文档与代码一致：文档描述的入口（命令、模块、子系统）**真实存在**；被删除子系统的文档残留必须清理。
+- D3 架构/决策记录：架构说明（CLAUDE/README）与实际代码路径一致；有 ADR 实践并覆盖关键决策。
+- D4 贡献基座：有 MR/issue 模板；CoC 声明与文件匹配；CONTRIBUTING 的命令可执行。
+- D5 发布文档：发布/上线文档指向真实发布路径（CI 或真实命令），不指向已删命令。
+- D6 changelog/版本实时：CHANGELOG 覆盖近期版本且与提交对应；README 可运行可复现。
+
+### 支柱 E：交付/健康横切
+- E1 版本一致：当前版本在版本源/构建文件/changelog 顶部一致。
+- E2 许可证：LICENSE 存在，版权署名与包元数据作者一致。
+- E3 环境锁定：`.python-version`、锁文件在库且被 CI 使用。
+- E4 仓库卫生：`.gitignore`/体积健康、无损坏/过期构建产物入库。
+- E5 测试工程：测试可并行/可缓存；测试文件数与 src 匹配且文档数字不过期。
+- E6 可复现 onboarding：从干净 clone 按 ONBOARDING 能复现开发环境（含 hook/工具链安装、生成目录的澄清）。
+- E7 辅助脚本非死物：install/reinstall/辅助脚本指向现存入口，无缺参/指向已删模块。
+
+## 3. 审计运行手册
+
+### 3.1 提取自宣声明（兑现度审计的关键前置）
+扫 `README`、`CONTRIBUTING`、`CLAUDE.md`、维护/发布指南、`docs/`，把所有**可证伪声明**列出来，
+例如：
+- 「合并前需通过 X」 → 执行载体是什么（命令/hook/CI job）？
+- 「我们提供 Y 命令」 → `registry`/CLI 里 Y 还在吗？
+- 「CI 含 security-scan」 → pipeline 里真有该 job 吗？
+- 「基于 Contributor Code of Conduct」 → 文件在吗？
+- 「锁文件保持一致」 → 锁文件入库了吗？
+
+### 3.2 找执行载体
+每条声明去找载体：本地质量命令 → pre-commit hook → CI job。**声明而无载体 = 名实不符（必录）**；
+有载体但命令本身报错/不可执行同样必录。
+
+### 3.3 证据规则
+- 每条 finding：`claim`（一句话）+ `evidence`（文件:行/命令输出，可复核）+ `criterion`（A1…E7）+ `gap`
+  + `confidence` + `ticket_draft`（建议 remediation 一句话）+ `effort/risk`（S/M/L）。
+- CONFIRMED 必须亲验（实跑命令或逐行读文件）；拿不准标 PLAUSIBLE 交主控复核。
+- 审计**只读**：跑只读命令可以，修代码不行。
+
+### 3.4 运行方式（并行加速）
+按五支柱各派一个只读研究代理并行取证（互不共享状态），主控复核去重后综合。跨支柱重叠（如
+「文档声称已删命令」会同时命中 D 与 B）由主控归一化。
+
+### 3.5 名实不符实例警示（来自真实 dogfood，供识别同类问题）
+1. **README stub 直通打包面**：根 README 只剩 `# test-project` 一行，而包配置 `readme =` 指向它
+   → PyPI/打包展示同为 stub。判据：README 存在且非占位，或显式指向替代文档。
+2. **模板占位符泄漏**：`CONTRIBUTING`/安装指南多处 `your-username` clone URL，新人照抄会克隆失败。
+   判据：正式文档无占位符。
+3. **自宣质量门无执行载体**：文档称「类型检查全绿」但类型检查器不在 hook/CI/质量命令里，
+   且命令行本身报错（`--package` 缺 `py.typed` → 0 检查）——错误数字可无感合入。
+   判据：宣称的门禁必须能在 CI/hook 里看到它在跑。
+4. **删除子系统后文档残留**：publish 命令已删/迁 CI，但发布文档、命令参考、onboarding 仍指导用户
+   执行一个已不存在的 publish 子命令。判据：文档入口与 CLI 注册表一致。
+5. **锁文件未入库**：lockfile 在 `.gitignore` 里，CI 却用非锁定安装 + 第三方镜像。
+   判据：锁文件入库且 CI 用锁定模式，或显式声明不锁依赖。
+
+## 4. 修复期排序与推进
+
+### 4.1 P0/P1/P2 判据
+- **P0**：阻断工业化基线 / 安全与发布完整性 / 低风险高可见快赢（README、占位符、发布 manual 门禁、
+  历史凭据、mypy 空转、`-k` 豁免、锁文件缺失、依赖审计门禁）。
+- **P1**：下一里程碑补齐（文档↔CI 现实对齐、ADR/模板基座、CI 断言单一版本源、SBOM/license gate、
+  可复现 onboarding、pipeline 触发收窄）。
+- **P2**：长期卫生（模板刷新、计数刷新、flaky 评估、死代码 lint 兜底）。
+
+排序启发：`missing > partial`；安全/凭据类**先轮换再清历史**；低 effort 高收益靠前；
+每 ticket 尽量单会话可独立解决。
+
+### 4.2 每个 ticket 的推进闭环
+```
+brainstorm → spec（设计/契约） → plan（writing-plans） → implement（TDD/executing） → 质量门全绿（lint/type/测试/覆盖） → MR
+```
+- 删除类 remediation 用「彻底删除，不保留兼容层」原则。
+- 改动验收 = 仓库质量门全绿（lint/type/测试/覆盖/pre-commit）+ 有针对性测试。
+
+## 5. 落地约定
+
+- 审计产物三件套：**差距报告**（支柱×发现表 + 自宣兑现度摘要 + P0/P1/P2 列表）、**路线图**
+  （wayfinder 地图 + 分级 ticket，issue tracker canonical）、**本 SOP**（把基准与方法固化，供复用到别的库）。
+- 多库推广时：复制本 SOP 到目标库，跑 §3 手册；五支柱 checklist 保留，证据/专名替换为目标库实况。
+- issue canonical：审计先落本地 ticket 文件；有 issue 跟踪系统（如 GitLab）恢复后按报告 §5 清单批量建 issue 回填。
+
+## 附录 A：首次执行记录（dogfood）
+
+- 目标：wl_cli v0.6.11（Python+Rust CLI）
+- 产出：差距报告 + 25 张 remediation ticket（P0×10 / P1×9 / P2×6）+ 本 SOP
+- 口径样例：五支柱 78 条发现归一化为 25 ticket；名实不符集中在「已删子系统文档残留 / 宣称无载体门禁 / 占位符泄漏」三类
+- 复用注意：附录内容仅作执行样例，复制到其他仓库时删除本附录并替换为目标库的记录