@aibyzero/byz 0.0.0 → 0.1.1

package/workflows/cm/skills/cm-ai/references/N5-mark-done.md

@@ -0,0 +1,107 @@
+# N5: 标记完成
+
+**强制，不可跳过。** 遗漏会导致断点恢复时重复执行任务。
+
+## 步骤
+
+0. **审查结论与标记原子卡点（必须真跑命令不许目测或手改）**：执行下列命令并保留 JSON 输出：
+
+   ```bash
+   python3 {CM_WORKFLOW_ROOT}/scripts/cm-task-gate.py mark-done \
+     --handoff {SPECS_DIR}/.reviews/{feature}-{任务号}-a{attempt}-handoff.json \
+     --reviews-dir {SPECS_DIR}/.reviews \
+     --feature {FEATURE_SLUG} \
+     --task {T-xxx} \
+     --tasks {SPECS_DIR}/{FEATURE_DIR}/tasks.md \
+     --project-root {CODE_PROJECT}
+   ```
+
+   非零退出或当前 Review 不是 `verdict: approved` = **不许标记**；成功 JSON 必须是
+   当前 attempt 且 `outcome` 为 `marked_done` 或幂等恢复时的 `already_done`，并且
+   `content_bound: true`。
+   `changes_requested` 回 N3；第 2 轮 `blocked` 停止等人工。门禁在同一进程重新校验
+   证据并原子替换当前 feature 自己的 `tasks.md`，只改精确匹配的任务 checkbox；
+   specs 根目录或其他 feature 的同名任务文件会被拒绝。不得先跑 `check-n5`
+   再手工勾选，也不得只执行 `ls`。
+1. **立即验证**：命令成功后重新读取 tasks.md，确认该任务确实已标记为 `[x]`
+
+```diff
+- - [ ] T-007: 安装依赖 ~5min
++ - [x] T-007: 安装依赖 ~5min
+```
+
+## 关键约束
+
+- 每完成一个 task **立即标记**，不批量、不延后
+- 文件编辑失败则重试，不得在未落盘时继续
+- 进入 N7 从磁盘重载上下文前，必须确认标记已写入
+
+## Git 提交（每任务一次）
+
+标记验证通过后按 N1 保存的 `DELIVERY_MODE` 分支：
+
+- `branch` / `draft-mr`：提交本任务全部变更（代码 + tasks.md 标记）。
+- `diff`：不 stage、不 commit，METRICS 备注 `delivery-diff`，回读行写
+  `commit 跳过(diff)`；所有任务保持串行，避免未提交 diff 相互覆盖。
+
+```bash
+git -C {CODE_PROJECT} add -- {该仓库内本任务新增/修改且开工前干净的相对路径}
+git -C {CODE_PROJECT} diff --cached --check
+git -C {CODE_PROJECT} commit -m "T-{编号} {feature名}: {任务标题}
+
+审查: 自审通过 | 独立审查({channel}) {N}轮 采纳{N}条 忽略{N}条({一句话理由})"
+```
+
+- **禁止 `git add -A` / `git add .`**：必须使用 N3 开工前记录的 dirty 清单与本任务文件集显式 stage，并用 `git diff --cached --name-only` 回读。不得把用户的先存改动带入任务提交
+- specs 与代码项目可以是不同目录/仓库：每个代码仓库只 stage 自己根目录下的任务文件；
+  feature `tasks.md`、`.reviews/`、METRICS 在代码仓库外时不得传给该仓库的 `git add`。
+  specs 自身另有 Git 仓库时可用单独审计提交，否则由 specs 落盘物保持审计，不能因
+  跨仓库路径导致代码提交失败（实跑结构：`$cm-ai {specs} {code}` 默认就是两条路径）。
+- 本任务必须修改一个开工前已 dirty 的文件时，不得按整文件 stage。只有能构造并回读「本任务新增 hunks」时才提交；否则跳过自动提交，METRICS 备注 `dirty-overlap`，保留用户工作区
+- **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——审计链"每任务一提交"不留空洞
+- **项目上下文的版本控制字段 = `none`**（或 N1 兜底设定 NO_GIT）→ 仅 delivery=diff 可继续并跳过本步，METRICS 行备注 `no-git`，进度输出的 🔁 回读行中提交项写 `跳过(none)`
+
+每个代码仓库提交成功并回读 SHA 后，按 `../../../runtime/logging.md` 分别写
+`delivery/commit`，只记录 project、task、branch、commit SHA 和证据路径；提交失败或
+跳过时不得伪造 delivery 事件。
+
+## 度量落盘（METRICS.md）
+
+标记完成后，向 `{SPECS_DIR}/METRICS.md` 追加本任务一行（文件不存在则先创建表头）：
+
+```markdown
+| 任务 | Feature | 开始 | 结束 | 审查轮次 | 独立审查拦截 | QA | 人工介入(次:原因) |
+| T-003 | 1.user-auth | 10:02 | 10:41 | 2 | 1 | — | 1:业务歧义 |
+```
+
+- 审查轮次 / 独立审查拦截数来自 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}/{总数} — {标题}
+🔍 主执行者自审: {结果} | 🤖 独立审查({channel}): {结果}
+🔁 回读: tasks.md T-{编号}[x]已确认 | commit {短sha}含T-{编号} | METRICS 行已写 | 门禁 {mark-done JSON 输出中的 review}
+📊 Feature {done}/{total} | 总体 {done_f}/{total_f}
+```
+
+**🔁 回读行是强制字段**——四项分别重新读取文件/执行命令确认后才能输出；本行缺失即视为 N5 未完成，不得进入 N6。不可见的纪律等于没有纪律（实跑事故教训：静默失败只有回读能发现）。

package/workflows/cm/skills/cm-ai/references/N6-qa-eval.md

@@ -0,0 +1,102 @@
+# N6: QA 评估
+
+AI 动态决策是否触发 `cm-qa-engineer`，不按固定间隔。
+
+QA 开始前解析 `tester` 角色并记录 `decision`/`phase: route`；浏览器走查另外解析
+`browser_qa`。路由元数据只说明请求的工具/模型别名，正式命令、逻辑核验和浏览器
+证据仍必须由本地 QA 合同实际产生。
+
+同时读取有效配置的 workflow profile 与 `policies.tests`：`java-backend` 优先
+commands/logic 及 API、数据库回归；`web-frontend` 优先 commands/browser；
+`cm-default` 按 logic→commands→browser。`policies.tests` 只关闭未被规格要求的可选
+类型；`test-cases.json` 中 blocking case 即使类型未列出也必须执行，环境不可用则
+`BLOCKED`，不得把配置当作跳过已审批验收的许可。
+
+## 评分（1-5 分，总分 ≥ 8 触发）
+
+| 维度     | 1 分                 | 5 分                  |
+| -------- | -------------------- | --------------------- |
+| 变更范围 | 单文件小改动         | 跨多模块/多项目       |
+| 风险等级 | 纯 UI 文案           | 数据库/支付/认证      |
+| 累积变更 | 上次 QA 后 1 个 task | 上次 QA 后 5+ 个 task |
+| 功能边界 | 模块内部实现         | 完整用户可感知功能    |
+
+## 必须触发（无需打分）
+
+- 当前 feature 所有 task 完成
+- API 接口变更（**收尾合并豁免**：下一个任务就是本 feature 最后一个任务时，可合并至 feature 级 QA 一次执行——避免背靠背双跑全量；合并决策记运行日志 `decision` 事件。实跑教训：后端 feature 几乎每任务都改 API,逐任务触发 QA 成本失衡）
+- 数据库 migration
+- 认证/授权/支付逻辑
+- 连续 5 个 task 未触发过 QA
+
+## 跳过
+
+- 纯文档/注释/配置格式
+- 仅新增类型定义（未实现）
+- 上一个 task 刚触发过 QA 且当前变更极小
+
+**跳过也必须留痕**：无论触发还是跳过，每个任务的 N6 结论都写一条 `qa` 事件进运行日志（`触发:原因` / `跳过:评分{N}` / `合并至feature级`）——cm:ai 必记事件本就含 qa，此处重申是因为实跑失守：json-keeper 7 个任务 0 条 qa 事件，N6 被整场静默绕过，连"连续 5 个 task 未触发"的必触发条款命中了都无人知晓。**不可见的跳过等于没有 N6**
+
+## 触发格式
+
+```text
+🧪 触发 QA — 原因: {理由}
+   累积变更: {N} 个 task | 风险评估: {总分}
+```
+
+QA 通过 → 继续。发现问题时，**不得在 N6 直接修改**已由 N4 绑定并在 N5 提交的
+代码或测试；先保存失败报告，再按有效配置的 `policies.auto_fix` 走唯一分支：
+
+- auto_fix: `never` → 写 `BLOCKED` 并报告，不修改。
+- auto_fix: `explicit` → 展示缺陷摘要，取得本次修复授权后调用 `$cm-fix`。
+- auto_fix: `auto` → 直接调用 `$cm-fix`，不额外停车。
+
+`$cm-fix` 必须生成自己的结构化 handoff、通过独立审查门禁并按 delivery 策略落盘；
+QA 新增或修正测试也属于该 fix diff，不能在旁路写入。修复闭环后重新 QA，总计最多
+3 轮；仍失败则 `BLOCKED`。这样原 task 的审批 SHA 不被事后覆盖，QA 修复拥有独立
+审查、提交与日志证据。
+
+实际触发 QA 时按 `../../../runtime/logging.md` 写 `test_run/start` 与
+`test_run/complete`，只记录模式、用例/通过/失败/阻塞数量、结论和报告路径；
+测试输出、截图和浏览器日志仍留在 `.reviews/`。
+
+feature 存在 `test-cases.json` 时按 `runtime/test-contract.md` 消费：正式项目命令
+仍照常执行；browser cases 由 `cm-qa-engineer` 逐条模拟并保存截图/日志；
+N4 中的 `INSUFFICIENT_EVIDENCE` 必须在本节点补运行时证据或保持 `BLOCKED`。
+任一 blocking case 为 `FAIL`/`BLOCKED` 时不得宣称 QA 通过。
+
+交付形态为微信小程序时读取
+`../../cm-miniprogram-engineer/references/release-checklist.md`，按 feature 实际能力补
+开发者工具模拟器与真机专项。Web/H5 截图不计小程序证据；授权、设备差异或平台 API
+缺真机证据时保持 `BLOCKED`/待人工，不能用静态核验或模拟器推断通过。
+
+**QA 新补的测试须变异自证**(机械,非审查轮):种 1-2 处行为变异必须变红,不红的测试修到红再入库——QA 测试是未来所有回归的安全网,安慰剂 QA 测试 = 永久性假安心(实跑先例:dogfood 中 QA agent 自发做过「5 个变异全被抓」,本条把自觉变成规则)。
+
+触发 QA 后，回填 METRICS.md 中对应任务行的 QA 列：`通过(覆盖率{x}%)` / `{N}轮通过(覆盖率{x}%)` / `失败上报`——覆盖率随列落盘，不留在会话里。
+
+## 形态确认卡点（仅 0.bootstrap 完成时，一次性）
+
+`0.bootstrap` 完成触发的 QA 中，**必须**执行形态确认：启动 dev server / 模拟器 / 开发者工具，截取首屏发给用户——
+
+```text
+📸 形态确认：这是项目当前的形态（{Web 页面 / App 模拟器 / 小程序}），与你要的交付形态一致吗？
+```
+
+**截图来源按 CLAUDE.md 交付形态写死**（防"替代形态截图糊弄卡点"）：
+
+- Web → 浏览器访问 dev server
+- **App → iOS/Android 模拟器或 Expo Go 真机截图；react-native-web / `expo start --web` 的浏览器截图不作数**——浏览器里渲染出"长得像 App 的网页"恰恰是本卡点要拦的形态错配
+- 小程序 → 微信开发者工具模拟器
+
+模拟器环境不可用 → 如实上报，请用户在本机/真机启动确认；**不得用替代形态的截图过卡点**。
+
+**用户确认后才进入业务 feature**。成本是一张截图 + 3 秒确认；收益是架构错配的发现时点从"任务过半"提前到"零行业务代码"（历史事故：要 App 画成了 HTML，跑到一半才发现）。
+
+## 业务验收走查（feature 完成时）
+
+触发原因为「当前 feature 所有 task 完成」且 QA 通过后，调用 `cm-product-manager` skill 做**业务验收走查**（用户视角流程闭环 + AC 逐条对照，非技术测试）：
+
+- 小偏差 → 记录进走查报告，继续
+- 涉及需求本意的偏差 → 暂停问人，不自行认定"也可以"
+
+金融/营销类 feature 的走查协同 `cm-finance-expert` 追加金融视角（数字口径抽查 + 营销红线扫描）；**涉合规的偏差一律上报，不适用"小偏差放行"**。

package/workflows/cm/skills/cm-ai/references/N7-context.md

@@ -0,0 +1,23 @@
+# N7: 上下文管理
+
+## task 完成后
+
+**重读落盘文件即是"重载",不需要清上下文,更不需要停车**:
+
+- 当前 feature 的 specs(requirements.md、design.md、tasks.md)
+- `{SPECS_DIR}/LESSONS.md`
+- `runtime/project-context.md` 解析出的 `AGENTS.md` 指令链与 `.claude/` 兼容规则
+
+重读完成后**直接继续下一个 task,不停车、不等用户、不以问句收尾**。
+
+> 以磁盘为准重读 specs 才是防漂移的有效动作；不依赖 Claude 的 `/clear` 或 Codex 的会话压缩细节。压缩摘要可能丢数字，落盘文件不会。
+
+## task 执行中
+
+察觉上下文被自动压缩过(前文变成摘要)→ 继续当前 task 前,重读本 feature 的 specs 与当前任务相关的 design 章节,以落盘文件校准记忆,不信摘要里的细节数字。
+
+## feature 完成后
+
+同上重读,直接进入下一个 feature。
+
+全程自动继续。**唯一合法停车点**：$cm-ai 全局规则的灾难级清单 + 各节点显式卡点（入口闸/高风险审查降级/形态确认/涉合规走查）。

package/workflows/cm/skills/cm-ai/references/N8-finish.md

@@ -0,0 +1,97 @@
+# N8: 完成
+
+所有 feature 的所有任务完成后：
+
+## 1. 调用 cm-doc-syncer
+
+调用 `cm-doc-syncer` skill 完成文档同步：
+
+- README 精炼更新（架构 + 业务 + 快速开始）
+- `AGENTS.md` 与 `.claude/CLAUDE.md` / rules 兼容文档同步
+- specs CHANGELOG 按日期生成
+- 文档一致性验证
+
+## 1.5 代码库参考文档回写（存在时强制）
+
+`{项目根}/docs/codebase-context/` 存在时（skill 未安装但文档在 → 按 skill 文内的回写映射表手动执行，映射表就在文档同目录项目里；两者都无 → 跳过本步），按 `codebase-context` skill dev 模式步骤 3 的「变更类型 → 需更新文档」映射表，把本次全部 feature 的变更回写进参考文档（09-changelog 类型标 `dev回写`）——**地图必须跟着代码走，否则下次二开按过期地图改**。
+
+## 1.7 最终工作树与交付策略
+
+对每个代码项目分别回读有效 `DELIVERY_MODE`，执行 `git diff --check` 并核对 N8 新变更：doc-syncer 只能
+产生文档/specs 元数据；若出现源码、配置或依赖变更，说明有修改绕过任务审查，立即
+`BLOCKED`。然后按唯一分支收口：
+
+- `diff`：不 commit、不 push、不创建 MR；输出基线 SHA、`git diff --stat` 和完整
+  diff 位置。工作树 dirty 是预期交付，但不得含开工前用户改动之外的范围外文件。
+- `branch`：显式 stage N8 生成的文档/specs 文件，`git diff --cached --check` 后补一条
+  `docs: sync CM workflow artifacts` 提交；确认工作树只剩开工前用户改动。停在本地分支。
+- `draft-mr`：先完成 branch 收口，再逐仓库展示 remote、branch、目标分支和将执行的 push/MR
+  命令，**取得本次明确授权**后才执行。GitHub 使用 `gh pr create --draft`，GitLab 使用
+  `glab mr create --draft`；CLI/remote/权限缺失则 `BLOCKED` 并保留本地分支。push 与
+  MR 各自成功后才写 `delivery/push`、`delivery/pull_request`，不得以配置代替授权或
+  伪造远端结果。
+
+branch/draft-mr 在写 `run_done` 前必须确认每个代码仓库的 CM 变更已全部进入可回溯
+commit；diff 模式则逐仓库确认没有新 commit。specs 位于代码仓库外时单独报告其落盘
+路径，不尝试从代码仓库 stage 跨仓库文件。该门禁防止 doc-syncer 在“全部完成”之后
+留下未交付变更。
+
+## 2. 生产发布待决清单
+
+**前置**：项目存在部署或平台发布形态才执行本步。信号包括 Dockerfile / CI 配置 /
+部署脚本、`{SPECS_DIR}/RELEASES.md`，以及已确认的 App/微信小程序交付形态（小程序可
+由 `project.config.json` + `app.json` 或跨端微信构建目标识别）。**纯本地工具、库等
+无发布形态的项目 → 跳过**，总结中输出一行 `🚀 发布清单: 跳过(无发布形态)`。
+
+调用 `cm-devops-engineer` skill **编制**（只编制，不执行生产发布）。**staging 验证状态的数据源是 `{SPECS_DIR}/RELEASES.md`**，不凭记忆：
+
+- 已通过 staging 验证的 feature 清单及版本（读 RELEASES.md）
+- 生产迁移清单与执行顺序（含备份点）
+- 新增环境变量清单（值由人在生产环境配置）
+- 回滚预案位置
+
+微信小程序另外读取 `../../cm-miniprogram-engineer/references/release-checklist.md`：
+即使尚未上传体验版，也要编制主体/类目、隐私权限、域名环境、L1–L3 证据和提审材料
+待决项；`RELEASES.md` 不存在时明确写“体验版未上传”，不得把 N6 模拟器结果伪装成
+staging/体验版验证。
+
+**生产发布由人决策触发**，不属于本流程的自动动作。
+
+## 3. 度量汇总
+
+读取 `{SPECS_DIR}/METRICS.md`，**只统计本次执行涉及的 feature 的行**（按 Feature 列过滤——防止历史批次数据混入本次门槛对照），全量历史另起一行标注"累计"。输出：
+
+```text
+📊 度量汇总
+任务: {N} 个 | 人工介入均值: {x} 次/任务 | 一次通过率(复审仅1轮): {x}%
+独立审查拦截: 共 {N} 条 | QA: 触发 {N} 次/通过 {N} | 总耗时: {x}
+💰 成本: 从当前运行时的 usage/成本面板取得；不可用则记「未采集」
+```
+
+**审查凭证对账**：tasks.md 全部 `[x]` 任务 ↔ `{SPECS_DIR}/.reviews/` 凭证一一对账，缺失项列入度量汇总（`⚠ 审查凭证缺失: T-xxx,...`，全齐则 `审查凭证: {N}/{N} 齐`）——中途漏网的审查，收尾必须暴露，不许无声混过。
+
+**临时资源对账**：读取当前 run 的项目权威日志，按 `resource_id` 对账
+`resource/acquired`、`resource/released` 与 `resource/cleanup_failed`。只有同一
+资源最后状态为 `released` 才算闭环；存在未释放或清理失败资源时输出清单、将状态
+改为 BLOCKED，并且**不得写 `run_done`**。没有 resource 事件的历史运行保持兼容。
+
+**运行日志收口**：按 `../../../runtime/logging.md` 写 `run_done` 终态事件，使项目日志与
+全局索引同时收口；然后报告 `运行日志.jsonl`、全局 run 文件路径与项目日志行数。
+提醒用户反馈问题时连同 METRICS.md 一起带回，只报告，不清理不截断。
+
+**成本落盘（灰度门槛「单任务成本 < 人工工时」的数据源）**：如果当前 Codex/Claude 界面提供 usage 或会话费用，将总费用与总耗时写入 `{SPECS_DIR}/度量汇总.md`（`成本: ${x} / {N} 任务 ≈ ${x/N} 每任务`）；无法获得就标注 `成本: 未采集`，不许编造。
+
+## 4. 输出总结
+
+```text
+🎉 全部完成
+
+📂 Features: {完成数}/{总数}
+📋 总任务: {完成数}/{总数}
+📝 文档同步: 已完成
+🚀 生产发布待决清单: 已编制，等待人工决策
+
+各 Feature 摘要:
+- 1.{name}: {N} 个任务 ✅ (发布验证: {staging/体验版已验证 | 未执行/待人工 | 不适用})
+- 2.{name}: {N} 个任务 ✅ (发布验证: {staging/体验版已验证 | 未执行/待人工 | 不适用})
+```

package/workflows/cm/skills/cm-backend-engineer/SKILL.md

@@ -0,0 +1,100 @@
+---
+name: cm-backend-engineer
+description: 后端 API 工程师 Skill，执行服务端 API 层开发（路由、业务逻辑、鉴权中间件、缓存、队列），自动适配语言和框架
+---
+
+# cm-backend-engineer — 后端 API 工程师
+
+执行服务端 API 层开发任务。自动识别语言和框架。
+
+## 职责边界
+
+- **管**：路由/控制器、业务逻辑、鉴权与权限中间件、缓存策略、消息队列、对外接口说明
+- **不管**：数据库 schema 与 migration（→ cm-database-engineer）、测试补全与 E2E（→ cm-qa-engineer）
+
+## 触发条件
+
+由 `/cm-ai` 自动调用，当 task 涉及后端 API 开发时触发。
+
+## 工作流程
+
+### 1. 识别技术栈
+
+自动检测，不做硬编码假设：
+
+- **语言/运行时**：Node.js / Python / Go / Java / Rust
+- **框架**：Express / Fastify / Hono / NestJS / FastAPI / Django / Gin / Spring 等
+- **鉴权方案**：JWT / Session / OAuth2 / BetterAuth 等（读现有中间件与依赖判断）
+- **接口风格**：REST / GraphQL / tRPC / gRPC（读路由与已有接口定义判断）
+
+### 2. 读取上下文
+
+- `.claude/rules/backend-api.md`、`.claude/rules/security.md`（如存在）
+- design.md 中的**接口契约**——本 skill 的最高约束
+- 现有路由组织、错误处理约定、中间件链
+
+### 3. 契约纪律（本 skill 核心）
+
+design.md 的接口契约是前后端并行的生命线，执行**三级协议**：
+
+1. **执行者只报不改**：实现中发现契约不合理或不完整 → **不得静默偏离、不得直接修改 design.md**，将偏差和理由写入完成汇报的「契约相关」栏
+2. **主流程小改留痕**：字段增补等小偏差由主流程更新 design.md 并标注版本（对齐 `[CHANGED]` 惯例）
+3. **大改必须问人**：偏差影响**已完成任务**所依赖的契约（会引发返工）→ 强制暂停人工确认
+
+实现完成后逐条核对：路径、方法、请求/响应字段、错误码与契约一致。
+
+### 4. 开发
+
+**接口实现：**
+
+- 遵循项目已有的路由组织和分层（controller/service/repository 等按项目实际）
+- 错误处理统一：错误码、错误体结构跟随项目约定，无约定则建立一处并全局复用
+- 输入验证在边界层完成，校验库跟随项目已有选择
+- 幂等性：写操作考虑重复提交（幂等键/去重），支付类接口强制
+
+**鉴权与权限：**
+
+- 复用项目已有的鉴权中间件，不另起炉灶
+- 权限检查靠近资源（handler 层），不散落各处
+- 敏感操作留审计日志
+
+**性能与可靠性**（以下为默认值，`.claude/rules/` 有规定时**以 rules 为准**）：
+
+- 外部调用必须有超时，默认 5s
+- 列表接口必须分页，默认页大小 20
+- 高频读考虑缓存、写路径考虑队列削峰——是否引入新基础设施以 design.md 为准，不擅自添加
+
+### 5. 安全检查
+
+- 密钥/连接串一律环境变量，绝不硬编码
+- 注入防护：参数化查询、模板转义（与 database skill 双保险）
+- 鉴权绕过自查：逐条核对本次新增路由是否漏挂鉴权中间件
+- 日志不输出密码、token、证件号等敏感字段
+
+### 6. 验证
+
+```bash
+# 根据项目实际命令执行
+npm run lint && npm run typecheck
+npm run build
+```
+
+启动服务，对本 task 涉及的接口逐个实测（curl/httpie）：正常流 + 至少一个异常流（4xx）。
+
+## 常见坑
+
+| 问题 | 处理 |
+| ---- | ---- |
+| 新路由漏挂鉴权中间件 | 按路由分组统一挂载，逐条核对本次新增路由 |
+| 外部调用无超时导致雪崩 | 统一封装 HTTP client，强制超时与重试上限 |
+| 错误体结构不一致，前端难处理 | 全局错误处理器统一出口，禁止 handler 内裸造错误体 |
+| 时间/时区序列化不一致 | 统一 UTC + ISO 8601 出参，入参解析集中处理 |
+| 阻塞事件循环（大 JSON / 同步加密） | 大计算移 worker 或队列，序列化分页 |
+| 分页游标与排序不稳定 | 排序键唯一化（时间戳+id），游标编码含排序上下文 |
+
+## 输出
+
+- 创建/修改的文件列表
+- 验证结果（lint / build / 接口实测）
+- **契约实现情况**：逐条列出实现的接口，标注与 design.md 的偏差（无偏差则写"完全一致"）
+- 需要其他工种配合的事项（如前端可替换 mock 的接口清单、需要数据库配合的字段）

package/workflows/cm/skills/cm-check/SKILL.md

@@ -0,0 +1,60 @@
+---
+name: cm-check
+description: 用户说“检查工作流是否安装正确”“为什么找不到 cm 命令”时使用。检查 CM 的 Codex 插件、核心 Skills、Claude 兼容包装、版本与模板引用；不测试业务功能、不自动修复。
+---
+
+# cm-check — 双运行时一致性自检
+
+执行前读取 `../../runtime/project-context.md` 与 `../../runtime/logging.md`。Codex 入口为 `$cm-check`；Claude Code 跨平台入口为 `/cm-check`，macOS/Linux 另有历史别名 `/cm:check`。
+
+从当前 Skill 路径解析 `{CM_WORKFLOW_ROOT}`。macOS、Linux、WSL 或 Git Bash
+先运行：
+
+```bash
+{CM_WORKFLOW_ROOT}/scripts/cm-check-runtime.sh --project "$PWD" --print-effective
+```
+
+Windows PowerShell 先运行：
+
+```powershell
+& "{CM_WORKFLOW_ROOT}\scripts\cm-check-runtime.ps1" --project (Get-Location).Path --print-effective
+```
+
+如果配置文件不在项目根目录，可额外传 `--config {CONFIG_PATH}`；不传时会读取项目根
+目录的 `.cm-workflow.yml` / `.yaml` / `.json`。
+
+PowerShell 入口会优先使用 `CLAUDE_CODE_GIT_BASH_PATH` 或 Git for Windows 的
+Bash 执行同一份检查；未找到时必须报告安装 Git for Windows 或改在 WSL
+运行，不能跳过机械检查。
+
+机械检查失败时，原样报告失败项并停止；通过后再做以下语义检查。
+
+## 语义检查
+
+1. **Codex 入口**：`.codex-plugin/plugin.json` 的 `skills` 指向 `./skills/`；`cm-idea/cm-init/cm-prd/cm-ai/cm-test/cm-fix/cm-refactor/cm-check` 八个核心 Skill 与独立 `external-expert` Skill 均有合法 frontmatter。
+2. **共享真相**：八个核心 Skill 引用 `runtime/` 合同；`external-expert` 引用共享外部专家合同；`compat/claude-commands/cm-*.md` 只是 macOS/Linux 旧入口薄包装，不再复制业务规则。
+3. **流程链路**：`cm-ai` 的 N1–N8 引用全部存在；`cm-prd` 的 greenfield/brownfield/change-mode 全部存在；`cm-idea` 引用 `idea-to-prd`；`cm-prd/cm-ai/cm-test/cm-qa-engineer` 共用 `runtime/test-contract.md`；`cm-prd/cm-ai/cm-test/cm-fix/cm-refactor/external-expert` 共用 `runtime/logging.md` 与统一 writer；`cm-test --generate-cases` 生成校验后的 inferred 草稿并硬停止。
+4. **角色链路**：N3 引用的 `cm-*-engineer/manager/expert` Skill 存在；Claude `agents/` 中每个兼容角色能找到对应工种 Skill。Codex 不依赖这些 `.md` agent 文件。
+5. **状态与审查**：`.cm-specs-status`、`.cm-status.json`、`.cm-run.json`、`tasks.md`、可选 `test-cases.json`、`METRICS.md`、`LESSONS.md`、`运行日志.jsonl` 及 `.reviews/` 的生成方与消费方配对；项目日志保持权威，全局日志只是私有可重建镜像；N4 凭证头包含 reviewer/independent/task/round/at/scope；`cm-fix` 收口前机械检查修后审查凭证；`.external/` 不得冒充 N4/N5 凭证。
+6. **模板路径**：所有 `{CM_WORKFLOW_ROOT}/templates/...` 引用都对应真实文件，重点核对 `templates/rules/`、`templates/ui-lens/`、`templates/hooks/`、`templates/refactor/`。
+7. **版本**：根 `VERSION` 与 plugin manifest 一致；README 不得宣称不存在的入口或安装路径。
+8. **私有调用清零**：Codex 核心 Skill 不得残留 `TaskCreate`、`TodoWrite`、`codex:review`、`~/.claude/commands`；兼容包装中出现 `/cm:*` 是合法的 macOS/Linux 旧入口。
+
+外部能力只做降级提示，不应导致插件自检失败：状态条、自动更新器、子代理、隔离 CLI
+审查通道与 external-expert 浏览器 transport 都是可选增强。浏览器不可用时必须能输出
+手工 handoff packet，不能把可选通道缺失报成核心运行时失败。
+
+## 输出
+
+```text
+🔍 cm-check  (plugin v{X.Y.Z})
+Codex 入口: {通过/失败}
+Claude 兼容: {通过/失败}
+流程与角色: {通过/断链清单}
+状态与审查: {通过/断链清单}
+模板与版本: {通过/不一致清单}
+可选增强: {已配置/降级项}
+结论: PASSED / FAILED ({N} 处)
+```
+
+只报告可复现的断链，不自动改文件。

package/workflows/cm/skills/cm-contract-engineer/SKILL.md

@@ -0,0 +1,136 @@
+---
+name: cm-contract-engineer
+description: 智能合约工程师 Skill，执行合约开发、测试、部署，自动适配 EVM/Solana/Move 等链和开发框架
+---
+
+# cm-contract-engineer — 智能合约工程师
+
+执行智能合约开发任务。自动识别链类型和开发框架。
+
+## 触发条件
+
+由 `/cm-ai` 自动调用，当 task 涉及智能合约开发时触发。
+
+## 工作流程
+
+### 1. 识别技术栈
+
+自动检测，不做硬编码假设：
+
+- **链/VM**：EVM（Ethereum/Base/Arbitrum/BSC...）/ Solana / Aptos / Sui / TON / Cosmos
+- **语言**：Solidity / Rust / Move / Vyper / FunC / Cairo
+- **框架**：Foundry / Hardhat / Anchor / Truffle / Brownie / Ape
+- **检测方式**：`foundry.toml` / `hardhat.config.*` / `Anchor.toml` / `truffle-config.js` / `Move.toml` / `contracts/` 目录
+
+### 2. 读取上下文
+
+- `.claude/rules/smart-contract.md`、`.claude/rules/security.md`（如存在）
+- design.md 中的合约接口设计
+- 现有合约代码和部署配置
+- 已有的测试文件和部署脚本
+
+### 3. 开发
+
+**合约编写：**
+
+- 遵循项目已有的合约组织方式（单文件/模块化/Diamond 模式等）
+- 接口（interface）先行，实现后补
+- 使用成熟的库（OpenZeppelin / Solmate / SPL 等）而非手写基础功能
+- NatSpec / Rust doc 注释覆盖所有 public 函数
+
+**安全优先（EVM/Solidity 重点）：**
+
+- 重入防护：使用 ReentrancyGuard 或 checks-effects-interactions 模式
+- 整数溢出：Solidity ≥0.8 内置检查，低版本用 SafeMath
+- 权限控制：Ownable / AccessControl / 多签，避免单点控制
+- 外部调用：不信任外部合约返回值，限制 gas 转发
+- 闪电贷攻击：价格预言机用 TWAP 而非即时价格
+- 前端运行（MEV）：commit-reveal 或时间锁机制
+
+**安全优先（Solana/Anchor 重点）：**
+
+- 账户验证：每个 instruction 都要验证 account owner 和 signer
+- PDA 派生：种子要唯一，避免碰撞
+- CPI 调用：验证目标 program_id
+- 整数溢出：用 checked_add / checked_mul
+
+**Gas/资源优化：**
+
+- 存储变量打包（EVM slot packing）
+- 减少 SSTORE/SLOAD 操作
+- 批量操作代替循环中的单次调用
+- Solana: 减少账户数量，合理使用 zero-copy
+
+### 4. 测试
+
+```bash
+# Foundry
+forge test -vvv
+forge coverage
+
+# Hardhat
+npx hardhat test
+npx hardhat coverage
+
+# Anchor
+anchor test
+
+# Move
+aptos move test
+```
+
+**测试要求：**
+
+- 正常流程覆盖所有 public 函数
+- 边界值测试（零值、最大值、空地址）
+- 权限测试（非授权调用应 revert）
+- 攻击测试（重入、闪电贷等关键场景）
+- Fuzz 测试（Foundry `forge test --fuzz-runs 1000`）
+
+### 5. 部署准备
+
+- 部署脚本使用项目约定的方式（Foundry script / Hardhat deploy / Anchor deploy）
+- 环境变量管理私钥和 RPC URL，绝不硬编码
+- 区分 testnet / mainnet 配置
+- 合约验证脚本（Etherscan / Sourcify）
+
+**部署前检查清单：**
+
+- [ ] 所有测试通过
+- [ ] 覆盖率 > 90%
+- [ ] 权限模型正确（owner/admin/multisig）
+- [ ] 升级机制明确（如使用代理模式）
+- [ ] 紧急暂停功能（如需要）
+- [ ] 事件覆盖所有状态变更
+
+## 常见坑
+
+| 问题 | 处理 |
+| ---- | ---- |
+| Solidity 版本不一致导致编译失败 | 检查 foundry.toml / hardhat.config 中的 solc 版本，与 pragma 一致 |
+| OpenZeppelin 版本升级 API 变化 | 锁定依赖版本，升级前检查 changelog |
+| Anchor IDL 生成失败 | 确保 `#[program]` 和 account struct 上的宏正确 |
+| 合约大小超过 24KB（EVM） | 拆分合约、使用 library、Diamond 模式 |
+| Gas estimation 失败 | 检查是否有 require 条件未满足，mock 依赖合约 |
+| Solana 交易大小超限 | 拆分 instruction，使用 lookup table |
+
+## 审计准备
+
+合约开发完成后，生成审计辅助文档：
+
+```markdown
+## 合约审计信息
+
+- 合约列表: {合约名及用途}
+- 依赖: {使用的库及版本}
+- 权限模型: {谁能做什么}
+- 资金流向: {token/ETH 的流入流出路径}
+- 已知风险: {设计上的取舍及原因}
+```
+
+## 输出
+
+- 合约代码和接口
+- 测试结果和覆盖率
+- 部署脚本
+- 需要其他工种配合的事项（如前端需要的 ABI 和合约地址）