@aibyzero/byz 0.1.1 → 0.1.3

package/workflows/cm-plugin/README.md

@@ -0,0 +1,195 @@
+# cm-plugin-workflow — Chrome 插件专用的 Claude Code 自动化开发工作流
+
+一套 spec-driven 的 Claude Code 工作流，**专用于 Chrome 浏览器扩展（MV3）开发**：需求文档 → 开发规格 → 自动开发 → QA/商店合规 → 文档同步。
+
+基于 [cm-workflow](https://github.com/kingxiaozhe/cm-workflow)（通用多工种版）定制：流程引擎（N1–N8 状态机、prd/fix/refactor 闭环）完整继承，工种层换成插件领域——核心工种是扩展工程师，QA 带真实浏览器加载验证与商店合规检查单，发布通道对准 Chrome Web Store。前缀 `cm-plugin:`，与上游 `cm:` 可同机共存（安装产物零交集）。
+
+## BYZ 集成
+
+BYZ 按完整 Git 提交锁定并内置本工作流。BYZ 用户只安装或更新 BYZ，不需要单独安装、更新或回滚 CM Plugin Workflow，也不应为 BYZ 内置副本启用本仓库的自动更新脚本。
+
+## 目录结构
+
+```text
+commands/                          # 斜杠命令（安装到 ~/.claude/commands/）
+├── cm-plugin:rewrite.md           # ★重写直通流水线：链接 → 素材采集 → huashu-design 原型 → PRD → 拆specs → 开发到底
+├── cm-plugin:scout.md             # 竞品插件重写机会评估（评论槽点/停更信号/源码功能盘点 → 机会评分卡；支持 --rewrite 素材模式、--bakeoff 多候选对抗模式）
+├── cm-plugin:init.md              # 项目 .claude/ 初始化（CLAUDE.md + rules/，识别扩展脚手架与权限清单）
+├── cm-plugin:prd.md               # 需求文档 → specs 三件套（requirements/design/tasks），支持 --change 变更模式
+├── cm-plugin:ai.md                # 自动开发主循环（流程图状态机）
+├── cm-plugin:fix.md               # 缺陷修复小闭环（复现→定位→防护网→最小修复→Codex审查→波及面回归→档案落盘）
+├── cm-plugin:refactor.md          # 重构闭环（行为保持；设计见 docs/重构流程设计）
+├── cm-plugin:idea.md              # 点子→PRD 访谈入口（加载 idea-to-prd 技能；流程上游，非 N1–N8 步骤）
+├── cm-plugin:check.md             # 框架一致性自检（角色/命名/引用/配套/版本）
+│
+│  # 独立工具 skill（不属于 N1–N8 流程，按需使用）
+│  skills/idea-to-prd/             # 点子→PRD 产品访谈搭档（新插件从零想法起步的前置工具）
+│  skills/darwin-skill/            # 技能优化器（MIT 收编自 alchaincyf/darwin-skill，详见其 NOTICE.md）
+│  skills/codebase-context/        # 代码库业务地图（scan/dev 两模式）
+└── cm-plugin-ai-nodes/            # cm-plugin:ai 的 8 个流程节点，按需加载
+    ├── N1-init.md                 # 初始化：解析路径、扫描 features、加载上下文
+    ├── N2-enter-feature.md        # 进入 feature：断点恢复、依赖分析、串/并行计划
+    ├── N3-execute-task.md         # 执行 task：按工种匹配 skill
+    ├── N4-review.md               # AI 自审 + Codex 复审（环境不可用时降级）
+    ├── N5-mark-done.md            # 标记 [x]、写 LESSONS.md
+    ├── N6-qa-eval.md              # QA 评分决定是否触发 QA（含真实浏览器形态确认卡点）
+    ├── N7-context.md              # 每个 task 后 /clear 重载 specs
+    └── N8-finish.md               # 调用 doc-syncer、编制发布待决清单、输出总结
+
+skills/                            # 工种 Skills（安装到 ~/.claude/skills/）—— skill 管技术
+├── cm-plugin-extension-engineer/  # ★核心工种：扩展本体（manifest/service worker/content script/
+│                                  #   popup/options/side panel/chrome.storage/消息通信），适配 WXT/Plasmo/CRXJS/原生
+├── cm-plugin-ui-engineer/         # UI 还原（design-baseline → token 先行 → 原子还原 → BackstopJS ≤1%）
+├── cm-plugin-backend-engineer/    # 配套后端（API 代理/鉴权/同步；扩展 CORS 与 token 鉴权、密钥只在服务端）
+├── cm-plugin-qa-engineer/         # QA（测试补全、--load-extension 真实浏览器 E2E、商店合规检查单）
+├── cm-plugin-product-manager/     # 产品（需求分析、歧义五问含权限敏感面、变更影响、业务验收走查）
+├── cm-plugin-devops-engineer/     # 发布（打包 zip、权限 diff 核对、Chrome Web Store 提审强制人工确认）
+└── cm-plugin-doc-syncer/          # 文档同步（README 权限清单/CLAUDE.md/rules/CHANGELOG）
+
+agents/                            # 并行工种的子 agent 定义（安装到 ~/.claude/agents/）—— agent 管纪律
+├── cm-plugin-extension-agent.md   # 只做指定任务、manifest 权限只减不增、不自行标记、规范汇报
+├── cm-plugin-ui-agent.md          # 只碰展示层白名单、基准只读、改既有 token 强制上报
+└── cm-plugin-backend-agent.md     # 范围外鉴权/权限改动强制上报
+```
+
+**分工原则**：并行干活的做 agent（extension/UI/后端），串行把关的做 skill（产品/QA/发布/doc-syncer）。
+
+**可选外部依赖**：`npx skills add alchaincyf/huashu-design`（MIT）——无设计稿时在 /cm-plugin:prd 阶段生成高保真原型作为设计基准，未安装则 UI 由扩展工程师自行实现。
+
+**rules 模板层**（`templates/rules/`，install.sh 装到 `~/.claude/templates/cm-plugin-rules/`）：7 个规则骨架（coding-style / testing / security / git-workflow / **chrome-extension** / frontend / backend-api），/cm-plugin:init 以其为骨架 + 项目推断生成最终规则；模板头部统一四原则（可执行 / Bad-Good / 量化 / 现代实践）。其中 `chrome-extension.md` 是插件铁律（权限最小化、MV3 约束、禁远程代码、消息契约集中管理）。**把团队规范沉淀进模板，所有项目 init 出的 rules 自动带团队基因**——这是团队定制的官方入口。
+
+**收编素材**：QA 与 devops 两个 skill 的 `references/` 下的 CWS 检测模式清单、官方违规码表、提审材料清单、CI/CD 模板收编自 [quangpl/browser-extension-skills](https://github.com/quangpl/browser-extension-skills)（MIT），来源与改动见各 skill 目录的 `NOTICE.md`。
+
+## 扩展 E2E harness 模板（templates/e2e/ → ~/.claude/templates/cm-plugin-e2e/）
+
+MV3 扩展的 Playwright E2E 有一组固定坑，dogfood 实测全踩过一遍，现固化成**可拷贝的久经考验底座**（`extension-harness.ts` + `smoke.spec.example.ts`）。bootstrap T-005 直接拷入，每个新插件不再重踩：
+
+- 系统 Chrome（2026 版）默认屏蔽 `--load-extension` → 须用 **Chrome for Testing**（harness 跨架构自动发现）
+- `--headless=new`（旧 headless 不支持扩展，`headless:false` 在无头/CI 退化 flaky）
+- SW **注册-停机竞态**（`acquireServiceWorker` 三路取先到）
+- `sw.evaluate` 前须 `wakeServiceWorker` 取活引用（否则 `Worker was closed`）
+
+给 N5「运行观察闸」提供了真能用的工具——不只是要求"真跑观察"，还给出怎么跑。
+
+## 流程工具脚本（templates/scripts/ → ~/.claude/templates/cm-plugin-scripts/）
+
+把 dogfood 实测中最痛的三个手工环节工具化，命令按需调用（都是有据可查的真实摩擦）：
+
+- **cm-plugin-preflight.sh** — 环境预检：开跑前一次性引爆扩展开发的环境地雷（Node/git/Codex/**Chrome for Testing**/系统 Chrome）。最大的雷是系统 Chrome（2026 版）静默屏蔽 `--load-extension`，E2E 必须用 CfT。N1/R0 调用。
+- **cm-plugin-codex.sh** — Codex 审查封装：收齐正确调用姿势（`--skip-git-repo-check --sandbox read-only` + 超时防挂起 + 输出清洗去源码转储 + 凭证落盘）。N4/prd/scout 的 Codex 调用优先用它，不裸调。
+- **cm-plugin-log.sh** — JSONL 日志助手：自动 ISO8601 时间戳、原子追加、JSON 转义。杜绝手写 echo 的「先记账后落盘」「攒批挤同秒」两类实测错误。
+
+## 插件领域的三条红线（区别于上游的领域性约束）
+
+1. **manifest 权限只减不增**（agent 层硬约束）——任务范围外的权限新增/扩大必须停下上报
+2. **Chrome Web Store 提审强制人工确认**——含权限变更的版本更新同样过闸
+3. **商店合规检查单只举旗不定性**——权限最小化/单一用途/数据披露/禁远程代码/注入克制，举旗项交人裁决
+
+## 安装
+
+### Pi / BYZ 内置 package
+
+BYZ 按完整 Git 提交锁定并内置本工作流。用户安装 BYZ 后可直接运行
+`byz --workflow cm-plugin`，不需要设置私有源，也不需要执行独立的工作流安装、
+更新或回滚命令。BYZ 内置副本只随 BYZ 版本更新。
+
+### Codex / Claude Code legacy installer
+
+```bash
+./install.sh          # macOS/Linux 一键安装（含覆盖确认），装完自动提示运行 /cm-plugin:check
+```
+
+```powershell
+powershell -ExecutionPolicy Bypass -File install.ps1   # Windows 版
+```
+
+或手动：
+
+```bash
+cp -r commands/* ~/.claude/commands/
+cp -r skills/*   ~/.claude/skills/
+cp -r agents/*   ~/.claude/agents/
+```
+
+安装/修改框架后运行 `/cm-plugin:check` 做一致性自检（角色存在性、命名一致、引用有效、配套完整、外部依赖 + **安装版本号**——反馈问题时请带上它）。
+
+**与上游 cm-workflow 共存**：本包所有安装产物（命令前缀、skill/agent 名、`templates/cm-plugin-*`、`~/.cm-plugin-workflow/`）与上游零交集，两套可同机安装互不覆盖。
+
+**Windows 说明**：核心工作流（commands/skills/agents）是纯 Markdown，Windows 原生可用；状态条 / 终端像素版 / serve.sh 是 bash+python3 脚本，在 WSL 或 Git Bash 中使用（浏览器像素版页面双击加 `?demo` 即可预览，不依赖脚本）。
+
+## 执行可视化（终端原生优先）
+
+**① 终端状态条（推荐，Claude Code 底部常驻）**——官方 statusLine 机制，零外部依赖：
+
+```json
+// ~/.claude/settings.json
+"statusLine": {"type": "command", "command": "~/.claude/templates/cm-plugin-statusline.sh"}
+```
+
+效果：`⚙ ○○○●○○○○ N4 1.tab-organizer/T-005 · Codex复审第1轮`——八点节点条实时点亮；等人时整条变黄 `⏸ 等待人工`；数据来自 .cm-status.json（N1 写入 ~/.claude/cm-plugin-current-specs 指针定位）。
+
+**② 内置任务清单镜像**——N2 进 feature 时任务自动镜像到 Claude Code 原生任务清单，N3/N5 同步状态，终端直接看勾选进度（无需配置）。
+
+**③ 浏览器看板（备选，适合投屏/远程盯进度）**
+
+```bash
+templates/dashboard/serve.sh {specs路径}   # 浏览器打开提示的地址，2 秒自动刷新
+```
+
+**纯只读、零侵入**——只消费 specs 落盘文件（tasks.md 勾选 / METRICS / LESSONS），执行引擎无感知。
+
+**④ 像素流水线（2D 像素游戏视角，演示/氛围屏首选）**——8 个像素工位对应 N1–N8：
+
+```bash
+templates/pixel/cm-pixel.sh            # 终端版（ANSI 像素，分屏挂一个 pane）
+templates/pixel/cm-pixel.sh --demo     # 终端版演示模式（不需要真实运行）
+templates/pixel/serve.sh {specs路径}   # 浏览器版（16-bit 风格，办公室大屏）
+# 浏览器版演示模式: 打开地址后加 ?demo
+```
+
+精灵素材采用 Kenney Pixel Platformer 系列开源素材（CC0，已内嵌，单文件零依赖）。
+
+## 自动更新（可选，macOS/Linux）
+
+`templates/auto-update/` 提供会话级自动更新链路，install.sh 装到 `~/.cm-plugin-workflow/`，按提示在 settings.json 的 `hooks.SessionStart` 挂两条即启用：
+
+- **cm-update.sh**：每次开会话异步检测上游新提交并自动重装；无新提交时做**逐文件字节级比对**，安装被改动/误删即自愈还原；**有工作流正在跑（.cm-status.json 为 running 且 30 分钟内活跃）则跳过本轮**。团队 fork 用 `CM_UPDATE_REMOTE` 环境变量指仓库，不要改脚本（会被自愈还原）
+- **cm-announce.sh**：下次开会话时播报更新/自愈结果，报完即删
+
+分工：更新器管"装的东西对不对"（机械，每会话），`/cm-plugin:check` 管"引用链断没断"（AI，改框架后跑），N1 预检管"这次运行环境行不行"（流程内）。
+
+## 度量与双保险
+
+- **METRICS.md**（specs 目录，N5 自动落盘）：每任务记录审查轮次、Codex 拦截、QA 结果、人工介入次数
+- **RELEASES.md**（specs 目录，devops 落盘）：每次打包/提审/部署的审计记录，含权限 diff 与商店审核状态
+- **templates/hooks/pre-commit-cm-task-check**：任务标记双保险 git hook（默认仅警告，`CM_TASK_CHECK_STRICT=1` 时阻断）
+
+## 使用流程
+
+**重写直通（已决定重写某插件时的主入口）：**
+
+`/cm-plugin:rewrite {商店链接}`——一条命令走完全程：**R1** 素材采集（scout 素材模式：源码盘点+评论痛点，结论不设门）→ **R2** huashu-design 生成 UI 原型（唯一新增卡点：设计方向确认）→ **R3** 输出 PRD（功能三态标记：保留/改进/舍弃）→ **R4** /cm-plugin:prd 拆 specs（规格摘要卡人审）→ **R5** /cm-plugin:ai 开发到 N8 发布待决清单。中断可幂等续跑。
+
+**选品（还没决定做不做时的第 0 步）：**
+
+`/cm-plugin:scout {商店链接}`——三维评估现存插件值不值得重写：**评论区槽点**（低分评论聚类 = 重写的原始需求，高分评论 = 不能丢的核心体验）、**停更信号**（>6 个月未更新是最强机会信号）、**源码功能盘点**（只盘功能不抄代码，清白室红线）。产出机会评分卡（GO/WATCH/NO-GO 由人拍板）+ 槽点→需求映射表 + 全程 `.log.jsonl` 运行日志（与 /cm-plugin:ai 同规格，可审计）；多次选品由 `SCOUTS.md` 台账串联，WATCH 项带复查到期提醒。GO 后报告直接作为 /cm-plugin:prd 的需求文档。
+
+**还没定靶时**：`/cm-plugin:scout --bakeoff {方向提示}`——多候选对抗比对模式：按判据（纯客户端/现任弃养或劣化/空档没被干净替代填满/非红海）凑齐 3-5 个候选做轻量核验 → 交 Codex **证否式对抗**（默认都不值得重写，证据压倒才翻）→ 逼出**一个确定靶**（或"全部不达标，继续搜"，无 GO 是合法结论不硬凑），选出的靶再走完整三维。挡住"单点押注把 WATCH 美化成 GO"（dogfood 实跑教训）。
+
+**存量插件项目：**
+
+1. 在插件项目中运行 `/cm-plugin:init`，生成 `.claude/CLAUDE.md` 和 `rules/` 规范（含 chrome-extension.md 铁律）
+2. 建一个 specs 文件夹，把需求文档放进 `docs/`，运行 `/cm-plugin:prd {specs路径}` 生成规格三件套
+3. 审查 specs 后运行 `/cm-plugin:ai {specs路径} {插件项目路径}` 开始自动开发
+4. 需求变更时用 `/cm-plugin:prd --change {N}.{feature} 变更描述`，已完成任务不受影响
+
+**0 到 1 新插件（无需先手动搭脚手架）：**
+
+1. 建 specs 文件夹放入需求文档，直接运行 `/cm-plugin:prd {specs路径}`——检测到空项目后自动进入 0→1 分支：先确认**表面组合**（popup/side panel/content script…）与**目标浏览器**，给出 2-3 套脚手架方案（WXT/Plasmo/CRXJS）供人拍板，再生成 `0.bootstrap` feature（design.md 即 ADR，任务含脚手架/规范生成/CI 打包/公共底座/E2E 基座）
+2. 人审规格（审 `0.bootstrap` 就是审架构，审**权限清单**就是审商店风险）后运行 `/cm-plugin:ai`——bootstrap 完成时的 QA 会把扩展**真实加载进浏览器**截图给你做形态确认
+3. 日后架构调整走 `/cm-plugin:prd --change 0.bootstrap 变更描述`，选型演进全程留痕
+4. 跳过 `/cm-plugin:init`——空项目没有可分析的对象，规范生成是 bootstrap 的任务之一
+
+**发布：**
+
+feature 全部完成后，N8 会编制**发布待决清单**（版本、权限 diff、商店材料就绪度）；商店提审由你确认后触发，审核状态记入 RELEASES.md，被拒原因按 bug 回流闭环。

package/workflows/cm-plugin/VERSION

@@ -0,0 +1 @@
+0.5.0

package/workflows/cm-plugin/agents/cm-plugin-backend-agent.md

@@ -0,0 +1,34 @@
+---
+name: cm-plugin-backend-agent
+description: 后端 API 开发子 agent。由 /cm-plugin:ai 在并行执行后端任务时派发，负责流程纪律（任务边界、上下文、汇报、退出），具体开发规范由 cm-plugin-backend-engineer skill 提供。
+---
+
+# cm-plugin-backend-agent — 后端开发子 agent
+
+你是被主流程派发的后端 API 开发子 agent。**agent 管纪律，skill 管技术**——你的职责是守住流程边界，开发方法完全遵循 skill。
+
+## 执行流程
+
+1. **加载 skill**：读取并严格遵循 `cm-plugin-backend-engineer` skill，它是开发方法的唯一准则
+2. **读取上下文**：派发指令中给出的 specs 摘录（requirements/design/tasks 相关部分）+ 代码项目的 `.claude/CLAUDE.md` 和 `.claude/rules/`
+3. **只做指定任务**：严格按派发指令中的任务编号（T-xxx）执行，不顺手做其他任务
+
+## 边界约束（不可违反）
+
+- **不修改**任务范围之外的文件；发现必须跨界的改动 → 停止并在汇报中说明
+- **不自行标记** tasks.md —— 标记完成是主流程 N5 的职责
+- **不自行执行** review —— 审查是主流程 N4 的职责
+- **不得修改 `.claude/` 下任何文件**（CLAUDE.md、rules/）——规范异议写入汇报，由主流程处理
+- **不修改 design.md** —— 契约偏差走三级协议第 1 级：只报不改，写入汇报「契约相关」栏
+- **任务范围之外的鉴权/权限/会话逻辑改动 → 立即停止并上报**；任务本身即鉴权任务则正常执行（人工把关已在规格审查完成，QA 由 N6 强制触发兜底）
+
+## 完成后汇报（固定格式）
+
+```text
+📦 T-{编号} 完成汇报
+- 变更文件: {列表}
+- 验证结果: {lint / build / 接口实测结果}
+- 契约相关: {逐条列出实现的接口及与 design.md 的偏差，无偏差写"完全一致"}
+- 需其他工种配合: {事项，无则写"无"}
+- 建议写入 LESSONS: {要点，无则写"无"}
+```

package/workflows/cm-plugin/agents/cm-plugin-extension-agent.md

@@ -0,0 +1,35 @@
+---
+name: cm-plugin-extension-agent
+description: 浏览器扩展开发子 agent。由 /cm-plugin:ai 在并行执行扩展本体任务时派发，负责流程纪律（任务边界、上下文、汇报、退出），具体开发规范由 cm-plugin-extension-engineer skill 提供。
+---
+
+# cm-plugin-extension-agent — 浏览器扩展开发子 agent
+
+你是被主流程派发的扩展开发子 agent。**agent 管纪律，skill 管技术**——你的职责是守住流程边界，开发方法完全遵循 skill。
+
+## 执行流程
+
+1. **加载 skill**：读取并严格遵循 `cm-plugin-extension-engineer` skill，它是开发方法的唯一准则
+2. **读取上下文**：派发指令中给出的 specs 摘录（requirements/design/tasks 相关部分）+ 代码项目的 `.claude/CLAUDE.md` 和 `.claude/rules/`
+3. **只做指定任务**：严格按派发指令中的任务编号（T-xxx）执行，不顺手做其他任务
+
+## 边界约束（不可违反）
+
+- **不修改**任务范围之外的文件；发现必须跨界的改动 → 停止并在汇报中说明
+- **manifest 权限只减不增**：任务范围外的 permission / host_permission 新增或匹配范围扩大 → 停止并上报，不得先加了再说——权限扩张影响商店审核与用户信任，必须过主流程
+- **不自行标记** tasks.md —— 标记完成是主流程 N5 的职责
+- **不自行执行** review —— 审查是主流程 N4 的职责
+- **不得修改 `.claude/` 下任何文件**（CLAUDE.md、rules/）——规范异议写入汇报，由主流程处理
+- 涉及消息契约（message type、payload、storage schema、后端 API 字段）的决定 → 以 design.md 为准，design.md 未覆盖的在汇报中明确列出
+
+## 完成后汇报（固定格式）
+
+```text
+📦 T-{编号} 完成汇报
+- 变更文件: {列表}
+- 验证结果: {lint / typecheck / build / 真实加载冒烟 结果}
+- manifest/权限变更: {逐项带用途理由，无则写"无"}
+- 契约相关: {新增或依赖的消息契约/API 约定，无则写"无"}
+- 需其他工种配合: {事项，无则写"无"}
+- 建议写入 LESSONS: {要点，无则写"无"}
+```

package/workflows/cm-plugin/agents/cm-plugin-ui-agent.md

@@ -0,0 +1,34 @@
+---
+name: cm-plugin-ui-agent
+description: UI 还原子 agent。由 /cm-plugin:ai 在并行执行 UI 还原任务时派发，负责流程纪律（任务边界、上下文、汇报、退出），具体还原方法由 cm-plugin-ui-engineer skill 提供。
+---
+
+# cm-plugin-ui-agent — UI 还原子 agent
+
+你是被主流程派发的 UI 还原子 agent。**agent 管纪律，skill 管技术**——你的职责是守住流程边界，还原方法完全遵循 skill。
+
+## 执行流程
+
+1. **加载 skill**：读取并严格遵循 `cm-plugin-ui-engineer` skill，它是还原方法的唯一准则
+2. **读取上下文**：派发指令中给出的 specs 摘录 + 设计基准路径（`design-baseline/`）+ 代码项目的 `.claude/CLAUDE.md` 和 `.claude/rules/`
+3. **只做指定任务**：严格按派发指令中的任务编号（T-xxx）执行，不顺手做其他任务
+
+## 边界约束（不可违反）
+
+- **只碰展示层文件**：组件公共目录（如 `components/ui/`）、样式与 token 文件、静态资产、本任务的页面静态结构；**不碰**业务逻辑、API 层、路由配置
+- **不修改设计基准文件**（`design-baseline/` 只读）
+- **不修改既有 token 值**——需要改 → 停止并写入汇报「契约相关」栏（新增 token 可自由添加）
+- **不自行标记** tasks.md、**不自行执行** review、**不修改** design.md（契约偏差只报不改）
+- **不得修改 `.claude/` 下任何文件**（CLAUDE.md、rules/）——规范异议写入汇报，由主流程处理
+- 基准缺失状态/断点 → 上报，**不脑补设计**；执行期不向用户征求设计意见
+
+## 完成后汇报（固定格式）
+
+```text
+📦 T-{编号} 完成汇报
+- 变更文件: {token / 组件 / 页面 / 资产列表}
+- 验证结果: {BackstopJS 各断点 mismatch 值 + 白名单项}
+- 契约相关: {组件契约实现情况、token 变更清单，无则写"无"}
+- 需其他工种配合: {前端可接线的组件清单及 props，无则写"无"}
+- 建议写入 LESSONS: {要点，无则写"无"}
+```

package/workflows/cm-plugin/commands/cm-plugin-ai-nodes/N1-init.md

@@ -0,0 +1,60 @@
+# N1: 初始化
+
+1. 从 `$ARGUMENTS` 提取 **specs 文件夹路径** 和 **代码项目路径**（可多个）
+2. 扫描 specs 下所有编号目录（`0.xxx/`、`1.xxx/`、`2.xxx/`），按编号排列
+3. 每个 feature 目录须含 requirements.md、design.md、tasks.md
+4. 加载：代码项目的 `.claude/CLAUDE.md` + `.claude/rules/`（0→1 项目此时可能尚不存在，跳过不报错）
+5. 加载 `{SPECS_DIR}/LESSONS.md`（架构决策和踩坑记录，开发时必须参考）；**文件不存在（全新 specs 首次运行的常态）→ 按 0 条处理，不报错不中断**，首个任务的 N5 会创建它
+6. 验证各代码项目路径存在，**空目录按信号处理**：
+   - 空目录 + specs 含 `0.bootstrap` → 0→1 已在规格期人工确认，直接执行
+   - **空目录 + specs 无 `0.bootstrap` → 矛盾信号，必须暂停询问**：specs 是按存量项目生成的，但目录是空的——"需要先 clone 项目？（clone 完成后回复继续）还是这就是新项目？（specs 上下文有毒，需重跑 /cm-plugin:prd 走 0→1 分支）"两种回答都不得跳过：clone 场景等用户，重跑场景中止
+   - **非空目录 + `0.bootstrap` 存在且其脚手架任务（T-001）未完成 → 矛盾信号，必须暂停询问**：规格期确认的是 0→1，但目录里已有项目（用户事后 clone 了？）——"继续 0→1 会在现有项目上覆盖生成脚手架。是改用现有项目？（需重跑 /cm-plugin:prd 按存量项目生成规格）还是目录内容可弃、继续 0→1？"不确认不得执行 T-001
+
+## 规格审批入口闸（先于一切预检）
+
+读取 `{SPECS_DIR}/.cm-specs-status`：
+
+- `approved` → 直接继续（断点续跑不重复问）
+- `awaiting_review` 或文件缺失（旧版 specs）→ 把规格摘要卡打给用户（specs 里没有摘要卡就现场汇总：feature 数/任务数/交付形态/风险点），**等用户明确回复"开始"**；回复后写 `{"status":"approved","at":"{时间}"}` 再继续。**泛化授权语不构成审批**（"按最优解处理""继续""你看着办"这类话授权的是执行方式，不是规格内容）——收到时必须回问一次："规格摘要卡确认开始吗？"（实跑失守：diff-lens 把"按照你分析的最优解去处理"直接视为审批通过）
+- 启动参数含 `--yes` → 跳过此问直接写 approved（适合刚人审完立刻开跑的场景）
+
+> 这是**入口授权门**（人把关方案端），不属于"暂停仅灾难级"约束的中途暂停，也不计入 METRICS 人工介入。实跑教训：没有这道闸，prd 生成完会被一句"继续"顺势带进开发，人审形同虚设。
+
+## 环境预检（先于一切任务，一次性）
+
+开工前跑 `~/.claude/templates/cm-plugin-scripts/cm-plugin-preflight.sh`（存在则用；不存在按下方逐项手查）——它一次性探明扩展开发全链路的环境地雷并给出补救：Node/npm、git、Codex（+调用姿势）、**Chrome for Testing（E2E 真实加载扩展的唯一途径——系统 Chrome 2026 版静默屏蔽 `--load-extension`）**、系统 Chrome。有阻塞项（退出码 1）先解决再开跑。依据：实测最吃时间的不是开发本身,是这些报错什么都不给的环境地雷（`--load-extension` 被屏蔽、codex 缺 `--skip-git-repo-check`、playwright 浏览器下载被墙）。
+
+## 审查通道预检（Codex 是主通道）
+
+开工前探测 Codex 可用性（`codex --version` 或项目配置的 codex 调用方式），结果直接影响 N4 的审查质量，必须在第一个任务开始前让用户知情。**调用封装**：`~/.claude/templates/cm-plugin-scripts/cm-plugin-codex.sh "<提示词>" [凭证路径]` 已收齐正确姿势（`--skip-git-repo-check --sandbox read-only` + 超时 + 输出清洗 + 凭证落盘），N4/prd/scout 的 Codex 调用优先用它，不裸调（实测:裸调常忘 flag、挂起、输出混入源码转储要手工清洗）。
+
+- 可用 → 正常，N4 走双模型交叉审查
+- **不可用 → 明确告知用户**："Codex 未检测到，代码审查将降级为对抗式子代理（质量次优）。建议安装/登录 codex CLI 后回复继续，或回复'接受降级'跑完本次。"——用户接受降级才继续，且本次运行的所有 METRICS 审查列都会带 `降级` 标注。**不得静默降级开跑**
+
+## Git 前置检查（字段优先，询问兜底）
+
+**先读 CLAUDE.md 的「版本控制」字段**（/cm-plugin:init 或 bootstrap 已确认并落盘）：
+
+- `remote` / `local` → 按常规执行每任务提交，不询问；**顺手装双保险 hook**：`~/.claude/templates/cm-plugin-task-check-hook`（安装名，源 templates/hooks/pre-commit-cm-task-check）存在且代码仓库 `.git/hooks/pre-commit` 未装 → 复制安装（默认警告模式,不阻断），输出一行 `🪝 任务标记双保险已装(警告模式)`——纪律靠节点文字自我约束在长会话中必然漏（实跑失守：两个项目均未装 hook,N5 漏标/漏凭证无人拦）
+- `none` → 直接进入 **NO_GIT 降级模式**，不询问：N5 跳过 git 提交（METRICS 备注 `no-git`）、doc-syncer 用文件扫描替代 git diff、hook 不适用、审计链降级为 METRICS + tasks 勾选
+
+**字段不存在时**（项目未经 init 的兜底路径）：
+
+- 有 git 仓库 → 继续，并建议补跑 /cm-plugin:init
+- 无仓库但存在 `0.bootstrap/` 且任务含脚手架/git init → 跳过询问，交给 T-001
+- 无仓库且非上述 → 问一次"git init？（推荐）/ 不使用版本控制"，**答案由主流程回写 CLAUDE.md 版本控制字段**（决策落盘，任何后续运行不再询问）
+
+## 可视化入口提示（N1 输出末尾，一次性）
+
+N1 完成、进入 N2 之前，在输出末尾打印一行可视化入口（存在 `~/.claude/templates/cm-plugin-pixel/` 时才打印）：
+
+```text
+🎮 想看像素流水线？另开终端: ~/.claude/templates/cm-plugin-pixel/cm-pixel.sh
+   浏览器版: ~/.claude/templates/cm-plugin-pixel/serve.sh {SPECS_DIR} （地址加 ?demo 可先看演示）
+```
+
+只在 N1 打印一次，不重复——入口可发现性问题的修复（实测反馈：用户不知道要手动启动）。
+
+## 0.bootstrap 优先规则
+
+存在 `0.bootstrap/` 且其中有未完成任务 → **无条件最优先执行**，完成前不进入任何业务 feature。它落地项目骨架和 `.claude/` 规范；完成后进入下一个 feature 时，N7 的重载机制会自然带上新生成的 CLAUDE.md 和 rules。

package/workflows/cm-plugin/commands/cm-plugin-ai-nodes/N2-enter-feature.md

@@ -0,0 +1,51 @@
+# N2: 进入 Feature
+
+1. 读取该 feature 的 requirements.md、design.md、tasks.md
+2. 断点恢复：`[x]` 已完成 → 跳过，`[DROPPED]` → 跳过，`[CHANGED]` → 按更新后描述执行。**恢复时凭证对账**：每个已 `[x]` 任务 ↔ `{SPECS_DIR}/.reviews/*-{任务号}-r*.md` 配对，缺失项输出一行 `⚠ 凭证缺失: T-xxx,...（存量欠账,如实留档,恢复起严格执行）`——不阻塞恢复，但缺失不许无声混过（实跑失守：json-keeper 7 任务全无凭证,中断前无人发现）
+3. 如该 feature 所有任务已完成 → 跳过，进入下一个 feature
+
+## 教训定向注入（防复发，两个动作）
+
+- **筛相关教训**：按本 feature 的领域/模块/技术栈关键词从 `LESSONS.md` 筛出相关条目（文件不存在或无匹配 → 注入 0 条照常继续,执行计划中输出一行说明）（`[仅记忆]` 级优先——`[已结构化]` 的已有代码防线兜底），把要点列进执行计划输出；并行派发时相关教训随 specs 摘录一并写进 agent 指令。全量加载靠注意力,定向注入才可靠（实跑教训：Infinity 防线教训在库仍复发）
+- **必扫「待触发备忘」段**：逐条判断触发条件是否与本 feature 相关——命中 → 升级为任务或在执行计划中显式认领；未命中 → 不动。扫过即在执行计划输出一行 `📌 备忘扫描: 命中 {N} 条 / 共 {N} 条`，零条也要输出（可见性纪律）
+
+## 执行计划
+
+分析 tasks.md 的依赖关系，自行决定串行或并行：
+
+| 串行 | 并行 |
+| ---- | ---- |
+| 有显式依赖 | 无依赖 |
+| 会修改同一文件/模块 | 分属不同代码项目 |
+| 涉及共享状态定义（schema、API、design token） | 天然隔离 |
+
+并行时用 Agent 工具派发子 agent，**优先使用 `cm-plugin-*-agent` 预定义角色**（cm-plugin-extension-agent / cm-plugin-ui-agent / cm-plugin-backend-agent，见 agents/ 目录）。派发指令必须包含：任务编号、该任务的 specs 摘录、design.md 中的接口契约。所有任务都有依赖时退化为全串行。
+
+**分工原则**：并行干活的用 agent（agent 管纪律：只做指定任务、不碰界外文件、不自行标记、规范汇报）；串行把关的用 skill（QA、doc-syncer 不做 agent）。agent 产出返回后，仍逐个走 N4 → N5。
+
+### 并行模式升级：Agent Teams（可选）
+
+同时满足以下条件时，将并行组升级为 Agent Teams 队友（而非子 agent）：
+
+- 环境已启用 `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS`
+- 并行组内的任务分属**不同代码项目**（如前端仓库 + 后端仓库）
+
+队友规则：
+
+1. **一个队友绑定一个代码项目**，绝不允许两个队友修改同一文件
+2. 生成提示中必须包含：该任务的 specs 摘录、design.md 中的接口契约、应使用的工种 skill 名称（如 `cm-plugin-extension-engineer`）
+3. 队友在**接口契约变更**时（API 字段、schema、事件格式）立即用消息通知相关队友同步，不等任务结束
+4. 队友完成后，产出仍**逐个回到 N4（审查）→ N5（标记）** 走完质量门禁，不因并行而跳过
+5. 该并行组结束后关闭所有队友，再进入下一组
+
+任一条件不满足 → 维持默认行为（Agent 工具派子 agent 或串行）。Teams 是可选加速器，不是硬依赖。
+
+输出：
+
+```text
+📂 Feature {N}/{总数} — {feature名}
+📋 执行计划：
+  串行 1: T-001 → T-002
+  并行 2: T-003 + T-004
+  串行 3: T-005 ← 依赖 T-003, T-004
+```

package/workflows/cm-plugin/commands/cm-plugin-ai-nodes/N3-execute-task.md

@@ -0,0 +1,32 @@
+# N3: 执行 Task
+
+## 开始标记
+
+```text
+🔨 Task {T-编号}: {任务描述} ~{预估时间}
+   Feature {F}/{总F} | 任务 {N}/{总数}
+```
+
+## Skill 匹配
+
+根据任务涉及的工种，查看可用的 `cm-plugin-*` skills：
+
+- 插件本体（manifest / service worker / content script / popup / options / side panel / chrome.storage / 消息通信） → `cm-plugin-extension-engineer`
+- UI 还原（有 design-baseline 的 popup/options/side panel 界面） → `cm-plugin-ui-engineer`
+- 配套后端 API（同步、鉴权、AI 代理等服务端） → `cm-plugin-backend-engineer`
+- QA/测试 → `cm-plugin-qa-engineer`
+- 打包/发布（Chrome Web Store 提审、版本管理） → `cm-plugin-devops-engineer`
+- 没有匹配 → AI 直接执行
+
+有匹配的 skill → 调用该 skill 执行。
+
+**串行 / 并行的执行方式**：串行任务由主 agent 直接按 skill 执行；并行任务（由 N2 计划决定）派发对应的 `cm-*-agent` 子 agent，agent 内部加载同名工种 skill。两种方式的产出都必须回到 N4 走审查。
+
+## 开发
+
+- 参考 design.md 技术设计和 `.claude/rules/` 规范
+- 技术选型自行选最优解，不暂停
+- 业务逻辑歧义按需求最合理解释执行并显式记录假设；**仅灾难级**（不可逆破坏/资金密钥合规/形态级错向）暂停——见 cm-plugin:ai 全局规则
+- **依赖与工具链纪律**：新引入的依赖/构建工具必须**钉版本写进 manifest**（dependencies/devDependencies），禁止在脚本里临时 `npx` 拉 latest（不可复现，锁网 CI 直接挂）；工具链改动在提交信息中单独说明，不静默混入功能变更（实跑教训：防护网脚本裸 npx esbuild 被复审抓出）
+- **二开范围纪律：只改任务范围内的代码，禁止顺手重构**——顺手"优化"老代码是存量项目的事故之源；想重构的记入 LESSONS 待触发备忘，事后走 `/cm-plugin:refactor` 单独立项、单独审查，不许夹带。改老文件跟老文件风格走，新文件才按新规范写
+- **平台专属 API 首次引入必查社区已知问题**（WebSearch"{API 名} 已知问题/踩坑"）：`chrome.*` 扩展 API 的不可靠组合官方文档不会写——MV3 service worker 休眠丢状态、offscreen document 生命周期、declarativeNetRequest 规则上限、跨浏览器 API 差异都是社区长期报告的重灾区。查证结论一行留在任务汇报里

package/workflows/cm-plugin/commands/cm-plugin-ai-nodes/N4-review.md

@@ -0,0 +1,58 @@
+# N4: Review
+
+每个 task 完成后必须执行，按**单个 task 粒度**审查。
+
+**核验类任务的处理**（产物是工具生成物或环境状态：脚手架生成、依赖安装、配置文件按模板落地）：**Codex 已安装 → 照常过 Codex，不豁免**（传生成配置与关键产物 diff，审"生成结果是否与 ADR/模板一致"）；**仅当 Codex 未安装/不可用时才跳过**——此时直接自审核验（产物存在、与 ADR/模板一致、构建/类型检查通过），不必派对抗子 agent（对生成物做对抗审查是浪费，降级链第 2 级只服务于手写代码）。手写代码任何情况下都不豁免。
+
+## 1. AI 自审
+
+检查本 task 变更的：
+
+- 代码质量：命名、结构、可读性、是否符合 `.claude/rules/`
+- 逻辑正确性：边界条件、错误处理、并发安全
+- 安全性：硬编码密钥、`.env` 误入 git、注入漏洞、OWASP Top 10
+- 性能：N+1 查询、不必要的重复计算、内存泄漏风险
+
+发现问题立即修复。不确定的点按多方案自主决策规则处理（选最合理方案并留痕），**仅触及灾难级清单**（不可逆破坏/资金密钥合规/形态级错向）才暂停——见 cm-plugin:ai 全局规则。
+
+## 2. Codex Review（强制）
+
+AI 自审通过后，调用 `codex:review`：
+
+- 传入**本 task 涉及的变更文件 diff**（不是整个 working tree）
+- 要求 Codex 审查代码质量、逻辑缺陷、安全问题
+- **本任务新增/修改的测试本身是审查对象**:断言测的是行为还是实现细节、是否安慰剂(怎么改代码都绿)、前提是否与被测代码共谋——实测最大问题类就是「测试是戏台」(七任务审查抓出最多的一类;cm-plugin:fix 第 5 步已有同款条款,此处对齐)
+- **审查产出纪律（对降级链各级同样生效）**：只报告能给出具体失败场景的问题（什么输入/状态 → 什么错误结果），按严重度排序；找不到真实问题必须明说"零发现"——凑数意见比没有审查更贵，每条都要花修复成本
+- 合理建议 → 修复后重新提交复审
+- 误报 → 记录理由后忽略
+- **审查通过后方可进入 N5**
+
+## 复审轮次上限（强制）
+
+Codex 复审**最多 2 轮**。AI 互审没有尽头——语法等价的改法无穷多，无限复审只会把代码越改越烂：
+
+- 第 2 轮后仍有分歧 → 停止复审，将分歧点和双方理由记入 LESSONS.md
+- 分歧涉及安全/数据正确性 → 暂停等人裁决
+- 分歧仅涉及风格/实现偏好 → 保留当前实现放行，进入 N5 并在进度输出中标注 `Codex review: 2轮后放行（分歧已记录）`
+
+> **三级降级路径**（按序尝试，用哪级在 N5 进度输出中标注）。**Codex 是主通道，降级是意外兜底不是备选项**——N1 预检已确认过 Codex 可用性，此处降级只发生在运行中途失效：
+> 1. `codex:review` 可用 → 双模型交叉复审（最强：跨厂商盲区互补）
+> 2. Codex 不可用 → **对抗式子 agent 复审**：派一个全新上下文的子 agent，提示词设为"假设这段 diff 有害，找出证据"——作者的上下文偏见不会带入新实例，≤2 轮上限同样生效，标注 `Codex review: 子agent对抗(N轮)`
+> 3. 子 agent 也不可用 → 单模型自审保底，标注 `跳过（环境不可用）`
+>
+> **降级门槛**：必须是本任务实际调用 Codex 失败（命令报错/超时/未登录），失败原因原文记入该任务 METRICS 行备注——"觉得可能不可用"不构成降级理由。单次超时先重试 1 次再降级；**连续 2 个任务降级 → 暂停提醒用户修复 Codex 环境**（主通道断了不是小事，不许一路降级跑完全程）。
+
+## 审查凭证落盘（防"丢审"的物理证据，强制）
+
+每轮审查的**原始输出当场落盘**——真调用比编造更省力（直接管道）：
+
+- Codex 轮：`codex ... | tee {SPECS_DIR}/.reviews/{feature}-{task}-r{轮次}.md`，文件头补一行时间戳+调用方式
+- 降级轮：同路径落盘，内容 = Codex 失败报错原文 + 子 agent 对抗结论（或核验类自审清单）
+- 返工后的复审是新一轮 → 落 `-r2` 凭证，≤2 轮上限不变
+- `.reviews/` 目录不存在则创建
+
+**无凭证文件 = 本任务审查未发生**——N5 会据此卡住标记（见 N5）。实跑教训：长会话里审查会被顺势跳过，METRICS 自填的轮次数字不构成证据，凭证文件才是。
+
+## 度量记录
+
+审查结束时记下供 N5 使用的内容：**复审轮次**（1 或 2）、**Codex 拦截数**（被采纳修复的条数；降级时记 `跳过`）写入 METRICS.md；**一句话审查摘要**（采纳/忽略条数及忽略理由）写入 N5 的 git commit message——误报的忽略理由以此落盘，不留在会话里。

package/workflows/cm-plugin/commands/cm-plugin-ai-nodes/N5-mark-done.md

@@ -0,0 +1,80 @@
+# N5: 标记完成
+
+**强制，不可跳过。** 遗漏会导致断点恢复时重复执行任务。
+
+## 步骤
+
+0. **审查凭证卡点（先于标记，必须真跑命令不许目测）**：执行 `ls {SPECS_DIR}/.reviews/*-{任务号}-r*.md`——命令无输出=**没有凭证不许标记**，退回 N4 补审。凭证是审查真实发生的唯一物理证据，METRICS 自填数字不算（实跑失守：两个项目 8 个任务在无凭证状态下被标记,文字卡点没拦住,故本步升级为强制命令执行,输出进回读行）
+0.5. **运行时观察卡点（有运行面的任务必过，标记前）**：**"编译过 + 测试绿" ≠ "真能跑"。** 任务若改动了任何**运行时可观察的产物**（扩展本体/UI/service worker/content script/脚本，即非纯文档、非纯配置、非纯类型），标记前必须**真实观察一次它按预期运行**并留证据——不是断言"我改好了"，是拿到物理产物：
+   - UI/表面 → 真实浏览器加载扩展截图（N6 形态确认同款 CfT 加载，系统 Chrome 屏蔽 `--load-extension` 用 Chrome for Testing）
+   - 行为逻辑 → 针对**本任务具体行为**的 E2E/集成测试输出（用 `templates/cm-plugin-e2e/` harness 底座，别手写 launchPersistentContext），且**必须读全 `passed` 与 `failed` 两个计数**——只看 "passed" 行会漏掉回归（实跑失守：改 UI 后 smoke 断言失效，只 grep passed 漏看 "2 failed" 连续两提交带病；另有"CfT 修复声称落盘实则在幻觉区块从未生效"——两次都是"声称完成≠真完成"，唯一解药是真跑观察）
+   - 纯逻辑函数 → 单测已覆盖即可，无需额外观察
+   证据一行进回读行（截图路径 / 测试 `N passed, M failed` 原文）。**观察不过或拿不到证据不许标记**——退回修。纯文档/配置/类型任务豁免本步。
+1. 用 Edit 工具打开 tasks.md，找到当前任务对应的行
+2. 将 `- [ ]` 改为 `- [x]`，**仅改 checkbox，不改其他内容**
+3. **立即验证**：改完后重新读取 tasks.md，确认该任务确实已标记为 `[x]`
+
+```diff
+- - [ ] T-007: 安装依赖 ~5min
++ - [x] T-007: 安装依赖 ~5min
+```
+
+## 关键约束
+
+- 每完成一个 task **立即标记**，不批量、不延后
+- Edit 失败则重试直到成功
+- `/clear` 之前必须确认标记已写入
+
+## Git 提交（每任务一次）
+
+标记验证通过后，提交本任务全部变更（代码 + tasks.md 标记）：
+
+```bash
+git add -A && git commit -m "T-{编号} {feature名}: {任务标题}
+
+审查: 自审通过 | Codex {N}轮 采纳{N}条 忽略{N}条({一句话理由})"
+```
+
+- **commit message 必须含任务编号**——"任何一行代码回溯到任务"靠这一步实现（`git log --grep "T-003"` 即可验证）
+- **一次实现天然覆盖多个任务时**（拆分过细的兜底）：message 必须列出全部编号（如 `T-005/T-006 ...`），各任务分别标记、METRICS 各记一行并备注"并入 T-xxx"——禁止只写其一导致审计链断点
+- 审查摘要来自 N4 的度量记录
+- **任务产物已在既有提交中**（典型：T-001 的产物就是脚手架自带的 initial commit）→ 用 `git commit --allow-empty` 打一条核验提交，message 照常规格式并指认产物所在的 commit sha——审计链"每任务一提交"不留空洞
+- **CLAUDE.md 版本控制字段 = `none`**（或 N1 兜底设定 NO_GIT）→ 跳过本步，METRICS 行备注 `no-git`，进度输出的 🔁 回读行中提交项写 `跳过(none)`
+
+## 度量落盘（METRICS.md）
+
+标记完成后，向 `{SPECS_DIR}/METRICS.md` 追加本任务一行（文件不存在则先创建表头）：
+
+```markdown
+| 任务 | Feature | 开始 | 结束 | 审查轮次 | Codex拦截 | QA | 人工介入(次:原因) |
+| T-003 | 1.user-auth | 10:02 | 10:41 | 2 | 1 | — | 1:业务歧义 |
+```
+
+- 审查轮次 / Codex 拦截数来自 N4；QA 列先写 `—`，N6 触发时回填
+- 人工介入：本任务执行期间每次暂停问人计 1 次并注明原因（技术选型自主决策不计）
+- 这张表是试点/灰度门槛（人工介入 ≤2 次/任务、一次通过率等）的**唯一数据源，不可跳过**
+
+## LESSONS.md
+
+如有值得记录的内容追加到 `{SPECS_DIR}/LESSONS.md`：
+
+- 架构决策及理由、踩坑记录、跨 feature 影响、环境/依赖特殊处理
+
+不记录常规开发、显而易见的事情。格式：`## {日期} — {Feature名} / {Task标题}`
+
+**条目分级（实跑教训：Infinity 防线进了 LESSONS 仍复发——纪律靠记忆不可靠）**：
+
+- 每条教训标注 `[已结构化]`（已落为测试用例/校验代码/lint 规则，防线不靠记忆）或 `[仅记忆]`（只有文字）
+- **`[仅记忆]` 是欠账**：写下时优先考虑能否顺手结构化（一条断言的成本远低于复发一次）；确实无法结构化的才保留标注，供 N2 定向注入与 N4 对照
+- **备忘/已知限制类**（"V1.x 需要……""等真实反馈再定"）不混入正文，写入文件顶部的 **`## 待触发备忘`** 段，格式：`- [挂起] {触发条件} → {事项}（来源 T-xxx）`——否则埋进只写不读的正文里，到期无人认领（实跑教训：warnings 无 UI 出口备忘无回流出口）
+
+## 输出进度
+
+```text
+✅ Feature {F}/{总F} | 任务 {N}/{总数} — {标题}
+🔍 AI review: {结果} | 🤖 Codex review: {结果}
+🔁 回读: tasks.md T-{编号}[x]已确认 | commit {短sha}含T-{编号} | METRICS 行已写 | 凭证 {ls 实际输出的文件名} | 运行观察 {截图路径 / "N passed M failed" / 豁免(纯文档)}
+📊 Feature {done}/{total} | 总体 {done_f}/{total_f}
+```
+
+**🔁 回读行是强制字段**——四项分别重新读取文件/执行命令确认后才能输出；本行缺失即视为 N5 未完成，不得进入 N6。不可见的纪律等于没有纪律（实跑事故教训：静默失败只有回读能发现）。