@aibyzero/byz 0.0.0 → 0.1.2

package/workflows/cm/scripts/validate-test-cases.py

@@ -0,0 +1,127 @@
+#!/usr/bin/env python3
+"""Validate a CM test-cases.json without external dependencies."""
+
+from __future__ import annotations
+
+import json
+import re
+import sys
+from pathlib import Path
+
+
+CASE_ID = re.compile(r"^TC-(\d{3,})$")
+FEATURE = re.compile(r"^[a-z0-9]+(?:-[a-z0-9]+)*$")
+REF_IDS = {
+    "acIds": re.compile(r"^AC-\d{3,}$"),
+    "taskIds": re.compile(r"^T-\d{3,}$"),
+}
+CASE_FIELDS = {
+    "id",
+    "origin",
+    "kind",
+    "blocking",
+    "acIds",
+    "taskIds",
+    "title",
+    "preconditions",
+    "steps",
+    "expected",
+    "cleanup",
+}
+STRING_LISTS = ("acIds", "taskIds", "preconditions", "steps", "expected", "cleanup")
+
+
+def fail(message: str, failures: list[str]) -> None:
+    failures.append(message)
+
+
+def validate_string_list(
+    case: dict[str, object],
+    field: str,
+    index: int,
+    failures: list[str],
+) -> None:
+    value = case.get(field)
+    if not isinstance(value, list) or any(not isinstance(item, str) for item in value):
+        fail(f"cases[{index}].{field} must be an array of strings", failures)
+        return
+    if field in {"steps", "expected"} and not value:
+        fail(f"cases[{index}].{field} must not be empty", failures)
+    pattern = REF_IDS.get(field)
+    if pattern is not None:
+        for item in value:
+            if not pattern.fullmatch(item):
+                fail(f"cases[{index}].{field} has invalid id: {item!r}", failures)
+
+
+def validate(path: Path) -> list[str]:
+    failures: list[str] = []
+    try:
+        data = json.loads(path.read_text(encoding="utf-8"))
+    except (OSError, UnicodeError, json.JSONDecodeError) as error:
+        return [f"cannot parse JSON: {error}"]
+
+    if not isinstance(data, dict):
+        return ["root must be an object"]
+    if data.get("schemaVersion") != "1.0":
+        fail('schemaVersion must equal "1.0"', failures)
+    feature = data.get("feature")
+    if not isinstance(feature, str) or FEATURE.fullmatch(feature) is None:
+        fail("feature must be a non-empty kebab-case string", failures)
+    cases = data.get("cases")
+    if not isinstance(cases, list) or not cases:
+        fail("cases must be a non-empty array", failures)
+        return failures
+
+    seen: set[str] = set()
+    for index, item in enumerate(cases):
+        if not isinstance(item, dict):
+            fail(f"cases[{index}] must be an object", failures)
+            continue
+        missing = sorted(CASE_FIELDS - item.keys())
+        if missing:
+            fail(f"cases[{index}] missing fields: {', '.join(missing)}", failures)
+
+        case_id = item.get("id")
+        match = CASE_ID.fullmatch(case_id) if isinstance(case_id, str) else None
+        if match is None:
+            fail(f"cases[{index}].id must match TC-001", failures)
+        else:
+            expected = index + 1
+            if int(match.group(1)) != expected:
+                fail(f"cases[{index}].id must be TC-{expected:03d}", failures)
+            if case_id in seen:
+                fail(f"duplicate case id: {case_id}", failures)
+            seen.add(case_id)
+
+        if item.get("origin") not in {"user", "generated", "inferred"}:
+            fail(f"cases[{index}].origin is invalid", failures)
+        if item.get("kind") not in {"logic", "browser"}:
+            fail(f"cases[{index}].kind is invalid", failures)
+        if type(item.get("blocking")) is not bool:
+            fail(f"cases[{index}].blocking must be boolean", failures)
+        title = item.get("title")
+        if not isinstance(title, str) or not title.strip():
+            fail(f"cases[{index}].title must be a non-empty string", failures)
+        for field in STRING_LISTS:
+            validate_string_list(item, field, index, failures)
+    return failures
+
+
+def main() -> int:
+    if len(sys.argv) != 2:
+        print(f"Usage: {Path(sys.argv[0]).name} TEST_CASES_JSON", file=sys.stderr)
+        return 2
+    path = Path(sys.argv[1])
+    failures = validate(path)
+    if failures:
+        for message in failures:
+            print(f"FAIL: {message}", file=sys.stderr)
+        print(f"test-cases validation: FAILED ({len(failures)})", file=sys.stderr)
+        return 1
+    print(f"test-cases validation: PASSED ({path})")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

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

@@ -0,0 +1,120 @@
+---
+name: cm-ai
+description: 用户明确说“规格已确认，开始实现”或要求按已审批 CM specs 开发时使用。按 N1-N8 完成开发、独立审查、QA 与文档同步；模糊点子、未审规格和单独一句“继续”不能触发编码批准。
+---
+
+# cm-ai — 自动开发
+
+执行前读取 `../../runtime/project-context.md`、`../../runtime/orchestration.md`、
+`../../runtime/task-gates.md`、`../../runtime/review.md` 与
+`../../runtime/model-efficiency.md`、`../../runtime/logging.md`。Codex 入口为
+`$cm-ai`；Claude Code 跨平台入口为 `/cm-ai`，macOS/Linux 另有历史别名 `/cm:ai`。
+
+用户明确要求外部专家，或为本次开发任务开启 AUTO 时，按
+`../../runtime/external-expert.md` 执行 `../external-expert/SKILL.md` 的任务路由。
+编码、命令、测试执行、页面 QA、Git 与 N4 永远 LOCAL；AUTO 只能把可分离的复杂
+研究、测试设计或方案批判路由到 CONSULT/VERIFY。外部建议由本地应用、测试与裁决，
+其 `.external/` 证据不得满足 N4/N5。
+
+`用户本轮输入` — specs 文件夹路径 + 代码项目路径。
+
+```bash
+$cm-ai specs在~/projects/my-app-specs，代码在~/code/my-app
+$cm-ai ~/projects/specs 前端~/code/fe 后端~/code/api
+```
+
+## 流程图
+
+按此流程执行，到达每个节点时读取 `references/` 下对应的节点文件获取详细规则。
+
+```text
+START
+  │
+  ▼
+[N1: 初始化] ── 解析输入、扫描 features、加载上下文
+  │
+  ▼
+┌─► [N2: 进入 Feature] ── 读取 specs、分析依赖、输出执行计划
+│     │
+│     ▼
+│   ┌─► [N3: 执行 Task] ── 检查 skill → 开发
+│   │     │
+│   │     ▼
+│   │   [N4: Review] ── 主执行者自审 → 独立审查
+│   │     │
+│   │     ▼
+│   │   [N5: 标记完成] ── tasks.md 标 [x]、写 LESSONS.md
+│   │     │
+│   │     ▼
+│   │   [N6: QA 评估] ── 评分决定是否触发 cm-qa-engineer
+│   │     │
+│   │     ▼
+│   │   [N7: 上下文管理] ── 从磁盘重读 specs 与项目约束
+│   │     │
+│   │     ▼
+│   │   还有未完成 task? ──YES──┘
+│   │     │
+│   │    NO
+│   │     │
+│   │     ▼
+│   └── Feature 完成 → 重建下一 Feature 的上下文
+│         │
+│         ▼
+│       还有下一个 Feature? ──YES──┘
+│         │
+│        NO
+│         │
+│         ▼
+      [N8: 完成] ── 调用 cm-doc-syncer → 输出总结
+        │
+        ▼
+       END
+```
+
+## 全局规则
+
+**暂停（仅灾难级）：** 不可逆破坏（删数据、动线上、不可回滚迁移）、资金/密钥/合规风险、交付形态级架构错向、环境阻塞到无法继续。
+**不暂停（多方案自主决策）：** 执行中出现多个可选方案时——技术选型、实现路径、库/工具选择、审查意见分歧——**自己分析利弊选最优解直接执行，不询问**。代价是留痕义务：把「选了什么 / 为什么 / 放弃了什么」写进任务汇报，方向性取舍追记 LESSONS.md——人可以事后翻案，但流程不为选择题停车。业务逻辑歧义按需求文档最合理解释执行并显式记录所做假设，仅当触及灾难级清单才暂停。
+**节点间不停车：** 除上述灾难级与各节点显式卡点（入口闸/降级知情/形态确认/涉合规走查）外，任何节点完成后**直接进入下一节点**——不得以"我将要…是否继续?"、"完成了 X,需要我继续吗?"这类问句收尾等待。阶段性汇报写在输出里照常可见,但回合不能停在等确认上（实跑反馈:执行器习惯性在节点末尾问一句,用户被迫每阶段点头,自动化名存实亡）。
+**度量：** 每次暂停问人，恢复后在当前任务的 METRICS.md 记录里人工介入计 1 次并注明原因（见 N5）。
+**状态落盘（供状态条/看板实时点亮节点）：** 每进入一个节点（N1–N8），覆盖写入 `{SPECS_DIR}/.cm-status.json` 单行 JSON：
+`{"node":"N4","feature":"1.xxx","task":"T-005","detail":"一句话当前动作","state":"running","at":"HH:MM:SS"}`
+——**detail 必须写大白话**，标准是"路过的非工程师扫一眼能懂"：写"正在开发数据接口"不写"cm-backend-engineer 执行 T-004"；写"第2轮代码审查"不写"对抗式子agent复审"；写"确认一下：原型里有3个按钮点了没反应,要做吗?"不写"原型死区待确认"。节点号/任务号由状态条自动放在行尾角标，detail 里不要再写。
+——暂停等人时 `state` 改为 `paused_for_human`（detail 写等什么），全部完成时 N8 写 `run_done`。N1 时可将 specs 绝对路径同步到当前运行时的状态镜像（Claude 兼容运行时为 `~/.claude/cm-current-specs`，Codex/OMX 为对应 session 状态），但 `{SPECS_DIR}/.cm-status.json` 始终是跨运行时真相。每节点至少写入一次；长步骤可在同一节点更新真实检查点，不得跳过。
+**运行日志（事后复盘与工作流优化的原始证据）：** 按
+`runtime/logging.md` 调用统一写入器；它先追加 `{SPECS_DIR}/运行日志.jsonl`，再把
+同一 `event_id` 镜像到 `~/.cm-workflow/logs/`。`at` 一律 ISO 8601 带时区偏移，
+detail 用一句大白话；不直接拼 JSON，避免跨会话格式漂移。
+**必记事件（event 取值固定）**：`run_start`、`node_enter`、`task_start` /
+`task_done`、`review`、`degrade`、`pause` / `resume`、`decision`、`warning`、
+`error`、`progress`、`resource`、`qa`、`test_run`、`external_expert`、
+`spec_lifecycle`、`delivery`、`run_done`。写日志与状态落盘同节奏，不得跳过；详细
+测试/审查/外部回答只写专项凭证，不灌主日志。长步骤和临时资源严格按
+`runtime/logging.md` 配对，禁止用后台心跳制造虚假活跃。
+
+**角色路由投影：** N1 用代码项目根读取有效配置；N3 每个实现任务解析 `coder`，N3
+任务检查解析 `tester`，N4 解析 `reviewer`，并在 N6 QA 解析 `tester`。使用：
+
+```bash
+python3 {CM_WORKFLOW_ROOT}/scripts/cm_workflow_config.py \
+  --project {CODE_PROJECT} --role coder --runtime {codex|claude} --print-role
+```
+
+把返回的 `adapter`、`model`、`source`、`route_state` 注入当前角色提示和任务摘要，
+并按 `runtime/workflow-routing.md` 写 `decision`/`phase: route`。每次 N7 恢复或进入
+新角色边界都从磁盘重读；配置缺失使用默认路由。`declared-adapter` 只表示项目请求了
+当前运行时未观察到的适配器，必须写 `warning`/`degrade`，不能声称该模型已执行；它
+也不能绕过本地编码、测试、Git 或 N4 独立审查。
+`managed-adapter` 只通过 `runtime/model-efficiency.md` 的内置调用边界返回文本角色结果；
+主执行者仍负责本地改码、命令与证据，适配器回答本身不得满足 N4。版本 1 因此拒绝
+`reviewer.adapter: openai-compatible`，N4 只使用 `runtime/review.md` 列出的本地审查通道。
+
+每个角色调用按 `runtime/model-efficiency.md` 重建当前任务的最小包：N3 coder 只接收
+当前 task/AC/相关设计与文件，tester 只接收测试合同和必要失败证据，N4 reviewer
+接收 task-only handoff/diff 与验证摘要。稳定规则前缀不混入动态 diff/日志；角色只返回
+既有 handoff、测试或 findings-first 结构，不复述输入。上下文缩小不得删减 N4 包的
+强制证据，也不得减少测试、审查轮次或人工门禁。
+
+**任务状态镜像：** `tasks.md` 是唯一权威任务源。运行时支持任务面板时，可将未完成任务镜像到 Codex/OMX 计划或 Claude 任务清单；N3/N5 同步状态。断点恢复必须由磁盘重建镜像：`[x]` 跳过或标为 completed，`[DROPPED]` 不镜像，不得重复创建条目。
+
+**执行策略：** 遵守 `runtime/orchestration.md`；串行默认，只有无依赖、文件边界不重叠、契约已稳定且环境确实支持时才可并行。

package/workflows/cm/skills/cm-ai/references/N1-init.md

@@ -0,0 +1,92 @@
+# N1: 初始化
+
+1. 从 `用户本轮输入` 提取 **specs 文件夹路径** 和 **代码项目路径**（可多个）
+2. 扫描 specs 下所有编号目录（`0.xxx/`、`1.xxx/`、`2.xxx/`），按编号排列；进入
+   每个 feature 时保存完整目录名为 `FEATURE_DIR`（如 `1.login`），仅把去掉编号的
+   名称保存为 `FEATURE_SLUG`（如 `login`）。前者只用于规格文件路径，后者用于
+   handoff/review 证据名，二者不得混用
+3. 每个 feature 目录须含 requirements.md、design.md、tasks.md
+   - `test-cases.json` 为可选 AI 测试合同；存在时读取
+     `../../../runtime/test-contract.md`，运行 `scripts/validate-test-cases.py`，
+     并核对 `acIds`/`taskIds` 引用在本 feature 三件套中真实存在
+4. 按 `runtime/project-context.md` 加载项目上下文：Codex 的 `AGENTS.md` 指令链优先，再读兼容的 `.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-prd 走 0→1 分支）"两种回答都不得跳过：clone 场景等用户，重跑场景中止
+   - **非空目录 + `0.bootstrap` 存在且其脚手架任务（T-001）未完成 → 矛盾信号，必须暂停询问**：规格期确认的是 0→1，但目录里已有项目（用户事后 clone 了？）——"继续 0→1 会在现有项目上覆盖生成脚手架。是改用现有项目？（需重跑 $cm-prd 按存量项目生成规格）还是目录内容可弃、继续 0→1？"不确认不得执行 T-001
+
+路径验证通过后立即按 `../../../runtime/logging.md` 写 `run_start`；断点恢复会复用
+`{SPECS_DIR}/.cm-run.json` 中仍为 running 的 run id，不另开重复运行记录。
+
+随后从代码项目根读取 `{CM_WORKFLOW_ROOT}/scripts/cm_workflow_config.py` 的有效配置，
+至少解析本轮会用到的角色、`route_state`、workflow profile 与 `policies`。配置缺失
+使用内置默认值；配置错误阻断本次运行并报告字段路径。这里只记录请求路由，不把模型
+别名当成已观测的后端模型。Profile 只决定测试优先级，不改变 N1–N8：
+`java-backend` 优先命令/API/数据库回归，`web-frontend` 优先构建/交互/browser，
+`cm-default` 按通用顺序。
+
+## 规格审批入口闸（先于一切预检）
+
+读取 `{SPECS_DIR}/.cm-specs-status`：
+
+- `approved` → 直接继续（断点续跑不重复问）
+- `awaiting_review` 或文件缺失（旧版 specs）→ 把规格摘要卡打给用户（specs 里没有摘要卡就现场汇总：feature 数/任务数/交付形态/风险点），**等用户明确回复"开始"**；回复后运行 `cm-spec-manifest.py`，把当前 `specFiles` 写入状态并更新为 `approved`。**泛化授权语不构成审批**（"按最优解处理""继续""你看着办"这类话授权的是执行方式，不是规格内容）——收到时必须回问一次："规格摘要卡确认开始吗？"（实跑失守：diff-lens 把"按照你分析的最优解去处理"直接视为审批通过）
+- 已是 `approved` 但缺少 `specFiles`（旧版审批位）→ 无法证明批准的是当前三件套；展示一次摘要卡并重新取得明确“开始”，随后补全 manifest。不得静默背书。
+- 启动参数含 `--yes` → 跳过此问直接基于当前文件生成 manifest 并更新为 approved（只适合刚人审完立刻开跑的场景）
+
+只有实际把状态从非 approved 改为 approved 时才写
+`spec_lifecycle/approved`；已有 approved 状态不重复伪造审批事件。
+
+批准后真跑
+`python3 {CM_WORKFLOW_ROOT}/scripts/cm-spec-manifest.py {SPECS_DIR} --status-file {SPECS_DIR}/.cm-specs-status`。
+任一 requirements/design/tasks/test-cases 新增、删除或**规格语义哈希**变化 → 将状态
+恢复为 `awaiting_review`，写 `spec_lifecycle/changed` 并要求用 `$cm-prd --change`
+说明变更。N5/N6 将明确的任务与 AC checkbox 从 `[ ]` 改为 `[x]` 属于运行状态，
+`cm-spec-manifest.py` 会规范化后比较，不得把正常进度误判成规格漂移；文案、ID、
+`[DROPPED]`/`[CHANGED]`、普通 checklist、设计和测试合同仍须完整保护。
+
+> 这是**入口授权门**（人把关方案端），不属于"暂停仅灾难级"约束的中途暂停，也不计入 METRICS 人工介入。实跑教训：没有这道闸，prd 生成完会被一句"继续"顺势带进开发，人审形同虚设。
+
+## 独立审查通道预检
+
+开工前按 `runtime/review.md` 探测能否建立**与实现者不同上下文**的审查通道，而不是检查当前进程是否叫 Codex：
+
+- 可创建 fresh Codex 子代理/独立线程 → 作为主通道
+- 子代理不可用，但可以安全启动隔离的 `codex` CLI 审查会话 → 作为备用通道
+- 两者都不可用 → 进入 `self-degraded`，在 N4 凭证与 METRICS 如实标注；只有安全/资金/数据正确性等高风险任务才需要暂停要求用户补齐独立审查通道
+
+## Git 前置检查（字段优先，询问兜底）
+
+从有效配置保存 `DELIVERY_MODE=diff|branch|draft-mr`，其分支优先于历史默认行为：
+
+- `diff` → 串行执行，不安装提交 hook，不自动 commit/push/MR；N8 交付最终 diff。
+- `branch` / `draft-mr` → 使用任务级 commit。当前在 `main`/`master` 等保护分支时，
+  基于当前 HEAD 创建 `cm/{首个feature}-{run短id}` 本地分支；已在非保护分支则沿用，
+  不覆盖或切走用户已有改动。`draft-mr` 的远端动作留到 N8 再取得明确授权。
+
+**先按项目上下文合同读「版本控制」字段**（优先 `AGENTS.md`，兼容 `.claude/CLAUDE.md`；$cm-init 或 bootstrap 已确认并落盘）：
+
+- `remote` / `local` → 按 `DELIVERY_MODE` 执行；仅 branch/draft-mr **顺手装双保险 hook**：`{CM_WORKFLOW_ROOT}/templates/hooks/pre-commit-cm-task-check` 存在且代码仓库 `.git/hooks/pre-commit` 未装 → 复制安装（默认警告模式，不阻断），输出一行 `🪝 任务标记双保险已装(警告模式)`
+- `none` → `delivery: diff` 时进入 **NO_GIT 降级模式**：N5 跳过 git、doc-syncer 用文件扫描、审计链降级为 METRICS + tasks 勾选；配置为 branch/draft-mr 时直接 `BLOCKED`，不得声称能交付分支或 MR
+
+**字段不存在时**（项目未经 init 的兜底路径）：
+
+- 有 git 仓库 → 继续，并建议补跑 $cm-init
+- 无仓库但存在 `0.bootstrap/` 且任务含脚手架/git init → 跳过询问，交给 T-001
+- 无仓库且非上述 → 问一次"git init？（推荐）/ 不使用版本控制"，**答案由主流程回写 CLAUDE.md 版本控制字段**（决策落盘，任何后续运行不再询问）
+
+## 可视化入口提示（N1 输出末尾，一次性）
+
+N1 完成、进入 N2 之前，在输出末尾打印一行可视化入口（存在 `{CM_WORKFLOW_ROOT}/templates/pixel/` 时才打印）：
+
+```text
+🎮 想看像素流水线？另开终端: {CM_WORKFLOW_ROOT}/templates/pixel/cm-pixel.sh
+   浏览器版: {CM_WORKFLOW_ROOT}/templates/pixel/serve.sh {SPECS_DIR} （地址加 ?demo 可先看演示）
+```
+
+只在 N1 打印一次，不重复——入口可发现性问题的修复（实测反馈：用户不知道要手动启动）。
+
+## 0.bootstrap 优先规则
+
+存在 `0.bootstrap/` 且其中有未完成任务 → **无条件最优先执行**，完成前不进入任何业务 feature。它落地项目骨架、`AGENTS.md` 与 `.claude/` 兼容规范；完成后 N7 从磁盘重载新上下文。

package/workflows/cm/skills/cm-ai/references/N2-enter-feature.md

@@ -0,0 +1,38 @@
+# N2: 进入 Feature
+
+1. 读取该 feature 的 requirements.md、design.md、tasks.md；存在
+   `test-cases.json` 时按 `../../../runtime/test-contract.md` 一并加载，并把
+   `taskIds` 命中当前任务的用例加入执行计划
+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） | 天然隔离 |
+
+并行执行完全遵守 `runtime/orchestration.md`。Codex 中只在运行时确实支持子代理、边界不重叠且主执行者仍保留 specs/度量/git 单写权时派发。指令必须包含：任务编号、specs 摘录、接口契约、文件范围、应用的 `cm-*-engineer` skill 及显式验证命令。任何条件不满足就串行。
+
+**分工原则**：子代理只实现指定任务，不碰界外文件、不写 specs、不提交、不自行标记。主执行者回收产出后逐个验证并走 N4 → N5；QA 与 doc-sync 保持串行。
+
+不依赖任何 Claude 实验开关或固定 agent 文件名；Codex 的具体并行能力由当前会话工具决定。
+
+输出：
+
+```text
+📂 Feature {N}/{总数} — {feature名}
+📋 执行计划：
+  串行 1: T-001 → T-002
+  并行 2: T-003 + T-004
+  串行 3: T-005 ← 依赖 T-003, T-004
+```

package/workflows/cm/skills/cm-ai/references/N3-execute-task.md

@@ -0,0 +1,99 @@
+# N3: 执行 Task
+
+## 开始标记
+
+改文件前先记录每个目标仓库的 `git status --short`、本任务预期文件集与已存 dirty 文件的 diff 指纹。这份快照供 N4 排除用户改动、N5 精确 stage；未记录就不得使用自动提交。
+
+```text
+🔨 Task {T-编号}: {任务描述} ~{预估时间}
+   Feature {F}/{总F} | 任务 {N}/{总数}
+```
+
+本节点解析 `coder` 角色的有效路由，并把 `adapter`、`model`、`source`、`route_state`
+写入任务摘要和 `decision`/`phase: route` 事件。`route_state: declared-adapter` 只表示
+请求了当前运行时未观察到的适配器；不得虚构该模型已运行，必要时写
+`warning`/`degrade`，仍由本地执行者保持代码修改和验收边界。
+
+## Skill 匹配
+
+根据任务涉及的工种，查看可用的 `cm-*` skills：
+
+- 前端 → `cm-frontend-engineer`
+- UI 还原（有 design-baseline） → `cm-ui-engineer`
+- 微信小程序 → `cm-miniprogram-engineer`
+- 后端 API → `cm-backend-engineer`
+- 数据库 → `cm-database-engineer`
+- 合约 → `cm-contract-engineer`
+- QA/测试 → `cm-qa-engineer`
+- 部署/发布 → `cm-devops-engineer`
+- 没有匹配 → AI 直接执行
+
+有匹配的 skill → 调用该 skill 执行。
+
+**串行 / 并行的执行方式**：串行任务由主执行者直接按 skill 执行；并行任务按 `runtime/orchestration.md` 为子代理注入对应工种 skill 的角色约束。两种产出都必须由主执行者回收验证，再进入 N4。
+
+并行只读任务无需 worktree；两个及以上任务并行写代码前，主执行者必须按
+`runtime/orchestration.md` 执行 `cm-task-gate.py check-parallel-write`。非零结果立即
+降级串行，不得让多个执行者共享 checkout、分支或 detached worktree。
+
+## 开发
+
+- 参考 design.md 技术设计和 `runtime/project-context.md` 解析出的项目规范
+- 技术选型自行选最优解，不暂停
+- 业务逻辑歧义按需求最合理解释执行并显式记录假设；**仅灾难级**（不可逆破坏/资金密钥合规/形态级错向）暂停——见 $cm-ai 全局规则
+- **依赖与工具链纪律**：新引入的依赖/构建工具必须**钉版本写进 manifest**（dependencies/devDependencies），禁止在脚本里临时 `npx` 拉 latest（不可复现，锁网 CI 直接挂）；工具链改动在提交信息中单独说明，不静默混入功能变更（实跑教训：防护网脚本裸 npx esbuild 被复审抓出）
+- **二开范围纪律：只改任务范围内的代码，禁止顺手重构**——顺手"优化"老代码是存量项目的事故之源；想重构的记入 LESSONS 待触发备忘，事后走 `$cm-refactor` 单独立项、单独审查，不许夹带。改老文件跟老文件风格走，新文件才按新规范写
+- **平台专属 API 首次引入必查社区已知问题**：用当前运行时的网络搜索能力查「{API 名} 已知问题/踩坑」。微信小程序、Taro、RN/Expo 这类平台 API 的不可靠组合官方文档未必覆盖；查证结论一行留在任务汇报里
+
+## 长步骤与临时资源留痕
+
+- 启动可能长时间占用的外部命令、桌面应用、浏览器用例或模型回合前，按
+  `../../../runtime/logging.md` 写 `progress/start`；只在真实观察到的启动完成、
+  Runtime Ready、页面到达或用例阶段变化时写 `progress/checkpoint`，结束写
+  `progress/complete`。**不启动后台定时心跳**。
+- 每个 blocking browser case 写 `test_run/case_start`，随后只允许一个
+  `case_complete` 或 `case_blocked`；同一步同步更新 `.cm-status.json` 的大白话
+  detail，避免进程仍运行但日志和状态长时间停住。
+- 临时 profile、进程、模型别名、worktree 或 fixture 在使用前写
+  `resource/acquired`，清理后用同一 `resource_id` 写 `resource/released`。
+  每次新获取使用新的 `resource_id`，释放后的 ID 不复用；`cleanup_failed`
+  立即把任务标为 BLOCKED，不得进入 N4。
+- 模型发生别名或路由时同时记录 `requested_model`、`effective_model`、`provider`、
+  `purpose` 与 `model_equivalent`；不得用别名冒充实际模型。
+
+## 结构化交接门禁
+
+实现和任务内验证结束后，主执行者依据真实 diff、命令输出和子代理汇报，写入：
+
+`{SPECS_DIR}/.reviews/{feature}-{任务号}-a{attempt}-handoff.json`
+
+格式严格遵守 `../../../runtime/task-handoff.schema.json` 与
+`../../../runtime/task-gates.md`。子代理只能返回候选字段；由主执行者核对并落盘，
+不得让子代理写 `.reviews/`。`ready_for_review` 必须所有 verification 都是 `passed`，
+且 blockers/scope_deviation 为空；`changed_files` 使用正斜杠分隔的项目相对路径。
+否则写 `blocked` 并停止，不进入 N4。写 handoff 前，必须以完全相同的
+`changed_files` 计算实现内容摘要：
+
+```bash
+python3 {CM_WORKFLOW_ROOT}/scripts/cm-task-gate.py hash-implementation \
+  --project-root {CODE_PROJECT} \
+  --file path/to/changed-file \
+  --file path/to/another-file
+```
+
+把 JSON 返回的 `implementation_sha256` 原样写入 handoff；不得用 handoff 文件自身的
+SHA 替代它。后续若任一已审文件内容变化，必须生成下一 attempt 并重新审查。
+
+进入 N4 前必须真跑：
+
+```bash
+python3 {CM_WORKFLOW_ROOT}/scripts/cm-task-gate.py check-n4 \
+  --handoff {HANDOFF_PATH} \
+  --reviews-dir {SPECS_DIR}/.reviews \
+  --feature {FEATURE_SLUG} \
+  --task {T-xxx} \
+  --project-root {CODE_PROJECT}
+```
+
+attempt 2 只有在第 1 轮凭证为 `changes_requested` 时才会通过。不得创建 attempt 3。
+保留命令 JSON 返回的 `handoff_sha256`，N4 写 Review 凭证时必须原样使用。

package/workflows/cm/skills/cm-ai/references/N4-review.md

@@ -0,0 +1,96 @@
+# N4: Review
+
+每个 task 完成后必须执行，按**单个 task 粒度**审查。完整通道与凭证格式见 `../../../runtime/review.md`，入口 handoff 与状态转换见 `../../../runtime/task-gates.md`。N3 的 `check-n4` 未通过时不得开始审查。
+
+进入审查前解析 `reviewer` 角色并记录 `decision`/`phase: route`；角色配置只能描述请求
+的审查适配器和模型别名，不能替代本节要求的独立上下文。若 `route_state` 是
+`declared-adapter`，如实记录未观察到适配器，仍不得把作者模型或外部专家当作独立审查。
+版本 1 不接受 `reviewer.adapter: openai-compatible`：该文本调用不能生成 N4 认可的
+独立凭证，配置校验会在调用前拒绝，避免白白消耗 API Token。
+
+开始审查前确认 N3 的 `check-n4` JSON 返回 `content_bound: true`。这表示 handoff 的
+`implementation_sha256` 已按项目根复算，审查结论不仅绑定文件名，也绑定被审文件内容。
+历史无摘要 handoff 只能在明确披露降级时用 `--allow-legacy-unbound` 恢复，不能作为新任务凭证。
+
+## 1. 主执行者自审
+
+检查本 task 变更的：
+
+- 代码质量：命名、结构、可读性、是否符合项目上下文约束
+- 逻辑正确性：边界条件、错误处理、并发安全
+- 安全性：密钥、环境文件、注入与权限绕过
+- 性能：N+1 查询、重复计算、资源泄漏
+- 测试质量：断言是否验证行为，是否存在怎么改都会通过的安慰剂测试
+
+发现问题先形成自审 finding；不要在 N4 修改实现文件。有效问题按本节第 3 步返回
+N3 生成下一次 handoff，避免已校验的证据与实际代码失配。
+
+## 2. 独立审查（强制）
+
+自审通过后，按以下顺序选择一个**新上下文**的审查者：
+
+1. `codex-subagent`：用当前运行时的 no-history/fresh-context 选项（如 `fork_turns: none`）新建独立 Codex 子代理/线程，只接收任务范围、验收标准、diff 和验证结果
+2. `codex-cli`：子代理不可用时，启动隔离的非交互 Codex CLI 审查会话；禁止它修改文件
+3. `self-degraded`：两者都不可用时，主执行者做第二遍对抗式审查并显式标记降级
+
+审查输入只包含**本 task 的 diff**，不得将整个未分类 working tree 当作任务 diff。审查者必须：
+
+- 假设这个 diff 有害，优先寻找可复现的失败场景
+- 对照 requirements/design/task 验收，检查超范围变更
+- 按严重度排序；每条必须说明「输入/状态 → 错误结果」
+- 找不到真实问题时明确写「零发现」，不凑数
+
+该 feature 存在 `test-cases.json` 时，把 `taskIds` 命中当前 task 的 logic cases
+加入 review package。逐例按 `runtime/test-contract.md` 输出
+`SUPPORTED | CONTRADICTED | INSUFFICIENT_EVIDENCE`；`SUPPORTED` 只是静态代码
+证据，**不得冒充单测或运行时 PASS**。`CONTRADICTED` 作为有效 finding 处置，
+`INSUFFICIENT_EVIDENCE` 转交 N6 的正式命令或运行时验证。
+
+核验类任务（脚手架、依赖、模板配置）也要过独立审查；输入改为关键产物、预期模板与构建/类型检查结果。
+
+## 3. 处置与轮次上限
+
+- 无阻塞发现 → 本轮写 `verdict: approved`，交给 N5 机械校验
+- 有效发现且当前为第 1 轮 → 写 `verdict: changes_requested`，返回 N3 生成 attempt 2 handoff，再用同一级别的新鲜上下文复审
+- 第 2 轮仍有阻塞发现 → 写 `verdict: blocked`，停止并进入人工处置，不得创建 attempt 3
+- 误报 → 记录理由后忽略
+- 最多 2 轮；偏好分歧若不阻塞，必须明确写 `approved` 并将双方理由写入 LESSONS.md
+- 分歧涉及安全、资金或数据正确性 → 暂停等人裁决；只涉及风格/偏好 → 保留当前实现并记录放行
+
+## 4. 审查凭证（强制）
+
+每轮原始结果立即写入：
+
+`{SPECS_DIR}/.reviews/{feature}-{task}-r{轮次}.md`
+
+文件顶部必须包含：
+
+```yaml
+---
+reviewer: codex-subagent | codex-cli | self-degraded
+independent: true | false
+task: T-xxx
+attempt: 1
+round: 1
+verdict: approved | changes_requested | blocked
+blocking_findings: 0
+handoff: {feature}-T-xxx-a1-handoff.json
+handoff_sha256: <check-n4 JSON 返回值>
+at: 2026-07-22T10:00:00+08:00
+scope:
+  - path/to/reviewed-file
+---
+```
+
+`attempt` 必须等于 `round`，`handoff` 必须指向本轮 N3 的执行证据，
+`handoff_sha256` 必须逐字使用 `check-n4` 的输出。`scope` 必须逐项覆盖 handoff
+里的全部 `changed_files`；正文必须写实际 findings 或明确的「零发现」。
+`approved` 必须写 `blocking_findings: 0`；其他 verdict 至少为 1。
+`self-degraded` 必须写 `independent: false`，并用非空 `degraded_reason` 记录前两个
+通道为何不可用。
+**无凭证文件或 verdict 不是 approved = 不得完成**，N5 必须执行 `mark-done`，
+不能只检查文件存在或先校验再手工勾选。
+
+## 5. 度量
+
+供 N5 使用的结果：审查通道、轮次、被采纳的拦截数、忽略数及一句话理由。METRICS 保持原列顺序，将原「Codex拦截」语义升级为「独立审查拦截」。