@house365/comate 0.10.2 → 1.0.2-next.0

package/docs/superpowers/plans/2026-10-14-review-fixes.md

@@ -0,0 +1,48 @@
+# Review Fixes Implementation Plan
+
+**Goal:** Fix the five reproducible review findings without expanding into the unfinished workflow-quality proposal.
+
+**Architecture:** Keep the existing Node commands and comate.v3 state. Preserve failed acceptance evidence across blocker resolution; describe check plans with command kinds and npm script definitions; retain Requirement context in acceptance text.
+
+**Tech Stack:** Node.js >=20, node:test, Git, Markdown.
+
+**Spec:** User-authorized fixes for the review in this session: mixed blockers, compile-only degradation, Markdown steps, Requirement context, and tests that copy production logic.
+
+## Constraints
+
+- Work with the existing uncommitted changes in this checkout.
+- Do not commit, publish, or install global skills.
+- Older states remain readable; degradation without a verifiable plan requires reconfirmation.
+- The command plan describes tests, but cannot prove arbitrary shell code is a meaningful test.
+
+## Tasks
+
+- [x] Replace copied routing/comparison tests with real CLI tests in test/flow.test.mjs. Add parser/context regressions in test/verify-issues.test.mjs and run them before implementation (14 expected failures).
+- [x] In cmd-loop.mjs, count mixed failures and queue their repairs. In cmd-decide.mjs, resolve mixed blockers into Repairing or Stuck while retaining evidence and resolution notes; pure blockers still restart verification.
+- [x] In checks.mjs, support explicit command kinds, infer known test runners, reject known compile/skip/masking commands as tests, and capture referenced npm script definitions. Persist and compare plans in common.mjs and cmd-loop.mjs, including empty plans and changes after handoff.
+- [x] In spec.mjs, retain Requirement titles and nested context, support Markdown step lists/emphasis, require keyword boundaries and real outcomes. In acceptance.mjs, include Requirement context in changed/regression/removal text.
+- [x] Correct the workflow-quality completion record and update degradation/config guidance.
+- [x] Run npm test, prepublish-check, pack-check, and git diff --check; obtain a read-only review and record results.
+
+## Expected Regressions
+
+```js
+assert.equal(resolvedMixed.node, 'Repairing');
+assert.equal(mixedState.loop.fail_count, 1);
+assert.equal(compileOnlyDegradation.status, 1);
+assert.equal(checkChangeSpec('auth', '### Scenario: Login\n- **THEN** receive token').length, 0);
+assert.match(changedRequirement.text, /5 minutes/);
+```
+
+Tests invoke production parsers or the real CLI in disposable Git repositories. Expected results are literal values, and the red run must reproduce the reviewed failures.
+
+## Validation Results
+
+- `npm test`: CLI self-checks passed; 55 Node tests passed, 0 failed.
+- `npm run prepublish-check`: no secrets detected in package contents.
+- `npm run pack-check`: 55 files, all required present, none forbidden.
+- `git diff --check`: passed.
+- Independent read-only review identified additional npm argument, runner-mode and verbose-flag cases; all reported cases were reproduced and covered by passing regression tests.
+- No commit, publish, or global skill installation performed.
+
+The broader workflow-quality proposal remains explicitly unfinished. Command classification does not prove arbitrary custom script assertions; unsupported npm package-routing syntax requires independent verification.

package/docs/superpowers/plans/2026-10-14-workflow-quality.md

@@ -0,0 +1,48 @@
+# Workflow Quality Implementation Plan
+
+**Goal:** Prevent incomplete implementations and unsupported acceptance claims from passing the open/build/verify workflow.
+
+**Architecture:** Extend the existing Markdown parser and JSON contracts. Preserve comate.v3 state readability and acceptance IDs; retain complete round snapshots in state. Keep semantic requirements review in agent guidance and enforce objective contract checks in Node.
+
+**Tech Stack:** Node.js >=20, node:test, Git, Markdown.
+
+**Spec:** User-authorized findings in the support-dynamic-content-for-private-chat audit: requirement context loss, source mapping errors, missing build evidence, compile-only verification, incomplete assertion checks, mixed blockers, shared retry budget, overwritten round evidence.
+
+## Constraints
+
+- Work in the current repository; do not rewrite the business project's archived change.
+- Keep the existing command names and state schema readable.
+- Require observable evidence, including every THEN/AND outcome, rather than attempting to prove natural-language correctness with keyword matching.
+- Unknown custom commands need an explicit test classification to support automatic-test degradation.
+- Keep independent verification and bounded automatic repairs.
+
+## Proposed Tasks (Not Fully Implemented)
+
+The original completion marks and validation counts did not match this checkout. The tasks below retain the broader proposal, with unsupported completion claims removed. The scoped review fixes are tracked in `2026-10-14-review-fixes.md`.
+
+- [ ] Add failing parser tests: changed Requirement context, placeholders, trigger conditions, and multiple outcome assertions. Requirement context and placeholder checks are implemented; trigger/outcome evidence contracts remain proposed.
+- [ ] Add source excerpt checks in acceptance.mjs and cmd-open.mjs; update source table fixtures and templates. Check quote existence against the pinned local source text, including multi-source disambiguation.
+- [ ] Add failing flow tests for missing handoff evidence, missing assertion evidence, contradictory verdicts, and compile-only verification. Implement a shared evidence.mjs validator and expose contracts through next.mjs. Compile-only degradation checks are implemented; structured evidence contracts remain proposed.
+- [ ] Classify check commands with `{ cmd, kind: 'test' }` support; freeze the prepared check plan and run a test baseline at build entry. Command classification and confirmation-time plan capture are implemented; prepared-plan confirmation and a build-entry test baseline remain proposed.
+- [ ] Add failing flow tests for mixed blocked/failed items and assertions, repeated check failures, candidate invalidation, and retained round snapshots. Mixed blocker routing, failure budgets and resolution notes are implemented; separate counters and complete round snapshots remain proposed.
+- [ ] Validate reverse checks against distinct changed behaviors and require passing baseline, expected assertion failure, and passing restoration.
+- [ ] Update open/build/verify/fix guidance, config reference, generated verification report, and the public manual. Scoped parser/degradation/blocker guidance is updated; broader evidence/report contracts remain proposed.
+
+## Validation Record
+
+The pre-fix review ran `npm test`: CLI self-checks and 38 Node tests passed. Additional reproducers nevertheless demonstrated broken mixed-blocker routing, compile-only degradation, and Markdown/context parsing. Current repair validation is recorded in `2026-10-14-review-fixes.md`; the previous 57-test and complete-review claims have been withdrawn.
+
+## Proposed Regression Examples
+
+```js
+// Changing a Requirement while retaining its Scenario must require deep verification.
+assert.equal(acceptance[0].kind, 'changed');
+assert.match(acceptance[0].text, /5 minutes/);
+
+// Listing IDs without implementation and execution evidence must not hand off.
+assert.equal(handoffWithoutEvidence.status, 1);
+
+// External blockers must not be sent to the builder as code repairs.
+assert.equal(mixedResult.node, 'Blocked');
+assert.deepEqual(mixedResult.blockers.map(x => x.id), ['A3']);
+```

package/package.json

@@ -1,55 +1,54 @@
-{
-  "name": "@house365/comate",
-  "version": "0.10.2",
-  "description": "comate —— SDD (规约驱动开发) 的 AI 开发编排器（Agent Skills）",
-  "type": "module",
-  "license": "MIT",
-  "publishConfig": {
-    "access": "public",
-    "registry": "https://registry.npmjs.org"
-  },
-  "bin": {
-    "comate": "bin/cli.mjs",
-    "comate-skills": "bin/cli.mjs"
-  },
-  "files": [
-    "skills",
-    "bin",
-    "!bin/*.test.mjs",
-    "docs",
-    "README.md",
-    "LICENSE"
-  ],
-  "keywords": [
-    "agent-skills",
-    "skills",
-    "claude-code",
-    "openspec",
-    "superpowers",
-    "spec-driven-development",
-    "ai-agents"
-  ],
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/liangjiankk/comate.git"
-  },
-  "homepage": "https://github.com/liangjiankk/comate#readme",
-  "bugs": {
-    "url": "https://github.com/liangjiankk/comate/issues"
-  },
-  "engines": {
-    "node": ">=20"
-  },
-  "dependencies": {
-    "ccusage": "^20.0.19",
-    "skills": "^1.5.21"
-  },
-  "scripts": {
-    "postinstall": "node bin/postinstall.mjs",
-    "test": "node bin/cli.test.mjs && node bin/init.test.mjs && node bin/usage.test.mjs && node bin/update.test.mjs && bash skills/comate/tests/run.sh",
-    "doctor": "cd skills && bash comate/scripts/comate.sh doctor",
-    "prepublish-check": "node scripts/prepublish-check.mjs",
-    "pack-check": "node scripts/pack-check.mjs",
-    "prepublishOnly": "npm run prepublish-check && npm run pack-check && npm run doctor && npm test"
-  }
-}
+{
+  "name": "@house365/comate",
+  "version": "1.0.2-next.0",
+  "description": "comate —— 规约驱动开发（SDD）的 AI 开发编排器：open → build ⇄ verify → archive，单 skill + Node 状态机",
+  "type": "module",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org"
+  },
+  "bin": {
+    "comate": "bin/cli.mjs",
+    "comate-skills": "bin/cli.mjs"
+  },
+  "files": [
+    "skills",
+    "bin",
+    "!bin/*.test.mjs",
+    "docs",
+    "README.md",
+    "LICENSE"
+  ],
+  "keywords": [
+    "agent-skills",
+    "skills",
+    "claude-code",
+    "spec-driven-development",
+    "state-machine",
+    "ai-agents"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/liangjiankk/comate.git"
+  },
+  "homepage": "https://github.com/liangjiankk/comate#readme",
+  "bugs": {
+    "url": "https://github.com/liangjiankk/comate/issues"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "dependencies": {
+    "ccusage": "^20.0.19",
+    "skills": "^1.5.21"
+  },
+  "scripts": {
+    "postinstall": "node bin/postinstall.mjs",
+    "test": "node bin/cli.test.mjs && node bin/init.test.mjs && node bin/usage.test.mjs && node bin/update.test.mjs && node bin/doctor.test.mjs && node --test test/docs.test.mjs test/flow.test.mjs test/verify-issues.test.mjs",
+    "doctor": "node skills/comate/scripts/comate.mjs doctor",
+    "prepublish-check": "node scripts/prepublish-check.mjs",
+    "pack-check": "node scripts/pack-check.mjs",
+    "prepublishOnly": "npm run prepublish-check && npm run pack-check && npm run doctor && npm test"
+  }
+}

package/skills/comate/SKILL.md

@@ -1,348 +1,65 @@
 ---
 name: comate
-description: "comate —— SDD (规约驱动开发) 编排器。用 /comate 自动探测阶段并分派。五阶段：open → design → build → verify → archive。"
+description: "comate —— 规约驱动开发（SDD）编排器。用 /comate 启动或恢复一个变更：open（澄清需求、写 brief 与完整目标 spec）→ build ⇄ verify（实现、独立验收、失败自动回修）→ archive（写入主 spec、归档、收尾）。流程推进全部由 Node 脚本的 next 决定。"
 ---
 
-# comate —— SDD (规约驱动开发) 编排器
-
-
-**核心原则：brainstorming 不可跳过。每个变更都必须经过深度设计（fix 预设除外）。**
-
----
-
-## 决策核心
-
-agent 做决策只需读本节，其余参见末尾「参考附录」。决策阻塞点的完整规则见 `comate/reference/decision-points.md`（单一真相源）。
-
-### 自动阶段探测
-
-**Step 0：活跃 change 发现 + 决策状态优先检查**
-
-<CRITICAL>
-**执行顺序不可颠倒**：先识别用户是否明确要求新建 change；否则读取状态检查明确的 `*-awaiting` 决策标记，再做普通意图过滤和 change 匹配。
-若用户正在回答已持久化的决策问题（如"worktree + TDD"、"确认方案A"），直接路由到对应子 skill。
-</CRITICAL>
-
-1. **活跃 change 快速发现**：
-   
-   运行 `openspec list --json` 获取所有活跃 change。
-   
-   - **无活跃 change** → 跳到步骤 3（意图快速过滤 + 预设探测）
-   - **有活跃 change** → 继续步骤 2
-
-2. **待决策状态检查**（防止决策答复被误判为新任务）：
-   
-   a. **确定目标 change**：
-      - 恰好 1 个活跃 change → 自动选中
-      - 多个活跃 change 且用户指定了 change 名称（`/comate <name>`）→ 选中该 change
-      - 多个活跃 change 且用户未指定 → **暂存待选列表，继续检查**（稍后在步骤 3.2 处理）
-   
-   b. **读取状态（若已确定目标 change）**：
-      
-      读取 `openspec/changes/<name>/.comate.yaml`，获取 `phase` 和 `phase_step`。
-   
-   c. **检查是否在等待决策**：
-      
-      只有 `phase_step` 是当前阶段的明确等待标记时，才说明子 skill 正在等待用户答复：
-      - `open.review-awaiting`
-      - `design.approval-awaiting`
-      - `build.options-awaiting` / `build.scope-awaiting` / `fix.upgrade-awaiting`
-      - `verify.failure-awaiting` / `verify.spec-drift-awaiting` / `verify.branch-awaiting`
-
-      兼容 `bd16c0f` 产生的活跃状态：仅在 phase 对应时，把 `open:4`、`design:1b`、`build:2` 分别视为上述等待标记；恢复后立即写入新格式。其它旧值只是普通进度。
-
-      普通进度（如 `design.brainstorm-complete`）、已确认状态和依赖阻塞状态都**不是**待决策，不得抢占用户的新请求。用户明确说“新建 change”时也优先按新建意图处理。
-      
-      **立即路由到对应子 skill**（根据 `phase` 字段）：
-      - `phase_step: fix.upgrade-awaiting` → 无论当前是 `phase: open` 还是 `phase: build`，调用 `/comate-fix`
-      - `phase: open` → 调用 `/comate-open`
-      - `phase: design` → 调用 `/comate-design`
-      - `phase: build` → 调用 `/comate-build`
-      - `phase: verify` → 调用 `/comate-verify`
-      - `phase: archive` → 调用 `/comate-archive`
-      
-      子 skill 的**幂等性检查**会：
-      1. 读取 `phase_step` 的值
-      2. 验证该步骤是否与当前 `phase` 匹配
-      3. 恢复到正确的步骤（跳过已完成的步骤，直接进入下一步）
-      
-      **结束 Step 0，不执行后续逻辑**。
-   
-   d. **若没有匹配当前阶段的等待标记**：
-      
-      说明没有未完成的决策点，继续步骤 3（意图过滤）。
-
-3. **意图快速过滤 + 幂等性匹配**：
-
-   3.1. **意图快速过滤**（仅当步骤 2 未命中时执行）：
-
-   先检查用户输入是否**明确表达了希望进入某个特定阶段**。如果用户没有明确指示，则无条件自动探测当前阶段，不询问不推测。
-
-   **明确意图的识别规则**：用户消息中包含以下**动作关键词 + 阶段名**的直接组合之一时，才算明确意图：
-   
-   | 阶段 | 明确意图的关键词组合（任一命中即算） |
-   |------|-------------------------------------|
-   | open | "开题"/"创建 change"/"新建 change"/"起草 proposal" |
-   | design | "设计"/"写设计文档"/"brainstorming"/"开始设计" |
-   | build | "实施"/"开始构建"/"执行计划"/"写代码"/"开始 build" |
-   | verify | "验证"/"检查实现"/"运行测试"/"开始 verify" |
-   | archive | "归档"/"完成收尾"/"合并 delta spec"/"开始 archive" |
-
-   **不算明确意图的情况**（这些都应自动探测，不询问）：
-   - 仅提及问题、需求、想法，无阶段动作词："修复这个 bug" / "优化性能" / "加个功能"
-   - 仅描述当前状态："设计做完了" / "代码写好了" / "测试通过了"
-   - 询问式："现在该做什么" / "下一步是什么" / "继续"
-   - 澄清式："刚才的设计有问题" / "build 阶段遇到错误"
-   - **决策答复**："worktree + TDD" / "选择方案 A" / "确认" / "继续构建"（这些应在步骤 2 被拦截）
-
-   **过滤结果**：
-   - **明确意图命中** → 直接跳到对应阶段的 skill（不运行后续步骤）
-   - **无明确意图** → 继续步骤 3.2
-
-   3.2. **活跃 change 匹配**（防止重复创建 change）：
-   
-   **前置条件**：有活跃 change 且用户输入无明确意图。
-   
-   **处理逻辑**：
-   
-   a. **用户输入仅为 `/comate` 无任何描述**：
-      - 恰好 1 个活跃 change → 已在步骤 2 选中，进入 Step 1
-      - 多个活跃 change → 列出所有 change 供用户选择，选中后进入 Step 1
-   
-   b. **用户输入包含任务描述但未指定 change 名称**（`/comate <描述>`）：
-      - **关键幂等检查**（防止重复创建 change）：
-        1. 遍历所有活跃 change
-        2. 对每个 change，读取 `proposal.md` 和 `specs/*/spec.md`
-        3. 检查用户描述是否与该 change 的需求高度匹配（关键词重叠、问题域相同、目标一致）
-        4. **若找到匹配的 change**：
-           - 自动选中该 change
-           - 说明「检测到您的描述与活跃 change <name> 的需求匹配，将继续该 change」
-           - 进入 Step 1（读取该 change 的状态）
-        5. **若所有 change 都不匹配**：
-           - **AskUserQuestion 询问**：「检测到 {N} 个活跃 change：{列表及简要描述}。您的任务是：继续某个已有 change，还是新建 change？」
-           - 选项 1：「继续已有 change」→ 让用户选择具体哪个 change，进入 Step 1
-           - 选项 2：「新建 change」→ 进入步骤 4（预设探测）
-
-4. **预设探测**（决定新 change 的入口）：
-
-   当确定需要新建 change 时（无活跃 change，或用户选择新建），按以下优先级探测：
-   
-   a. **fix 预设**：
-      - 用户明确描述 bug 修复或文案/配置/文档/prompt 小调整
-      - 且满足 fix 条件（见 `/comate-fix` skill）
-      - → 直接调用 `/comate-fix`，不进入普通 open 分支
-   
-   b. **gate 预设**（原始 PRD 入口）：
-      - 用户输入指向一份原始 PRD（给了 PRD 路径/编号，或明确说「这是 PRD / 从这份需求文档开始」）
-      - 典型路径：`docs/knowledge-base/**/PRD-*.md`
-      - **且无对应活跃 change**
-      - → 直接调用 `/comate-gate`（阶段 0：先过门禁，再拆分建 change）
-      - **不要直接调 `/comate-open`**——PRD 必须先过质量门禁
-   
-   c. **普通 open**（默认）：
-      - 无预设命中
-      - → 调用 `/comate-open`
-
-<IMPORTANT>
-用户选择「新建 change」时，**必须调用 `/comate-open`**，不要直接调 `/opsx:new`。
-`/comate-open` 做双重初始化：OpenSpec 产物（由内部 `/opsx:new` 创建）+ `.comate.yaml` 状态文件。
-直接调 `/opsx:new` 会导致 `.comate.yaml` 缺失，破坏后续阶段探测。
-</IMPORTANT>
-
-**Step 1：读取 `.comate.yaml` 状态元数据**（仅在 Step 0 未直接路由时执行）
-
-优先读 `openspec/changes/<name>/.comate.yaml`。不可用时回落到 `openspec status --change "<name>" --json`、`tasks.md`、`docs/superpowers/` 文件检查。
-
-**关键字段**：
-- `phase`：当前阶段（`open` / `design` / `build` / `verify` / `archive`）
-- `phase_step`：当前阶段内的步骤标记（如 `design.approval-awaiting`、`build.options-confirmed`）
-- `workflow`：流程类型（`full` / `fix`）
-- `build_mode`、`isolation`、`tdd_mode`：build 阶段的决策字段
-- `verify_result`：验证结果（`pending` / `pass` / `fail`）
-
-**phase_step 语义说明**：
-
-`phase_step` 记录**当前阶段**内的步骤，用于断点恢复和幂等性检查：
-- 非空值表示"已完成到该步骤"，恢复时从**下一步**开始
-- `*-awaiting` 表示正在等待用户答复，只有这类值触发决策优先路由
-- `*-confirmed` 表示用户已确认的决策点
-- `build.blocked-by-<dependency>` 表示被依赖阻塞，但不是等待当前用户决策
-- 空值或 `null` 表示该阶段尚未开始或已完成所有步骤
-
-**断点恢复规则**：
-- 每次上下文恢复都重跑 Step 0、Step 1；不要信任对话历史做阶段探测。
-- 有活跃 change 且工作树有未提交改动时，按 `comate/reference/dirty-worktree.md` 协议处理。
-- 若 `phase: build`，先检查 `build_mode`、`isolation`、`tdd_mode` 是否已设；任一未设则回 `/comate-build` 对应步骤补充；都已设则读 tasks.md 下一个未勾选任务继续。
-- 若 `phase: verify` 且 `verify_result: fail`，按决策点 4 分级处理：CRITICAL 失败直接 `state transition <name> verify-fail` 回 `/comate-build`（不询问，回退前报告失败项）；仅 WARNING/SUGGESTION 或 Spec 漂移时才 AskUserQuestion 暂停。
-- 若 `phase: open` 但 proposal/design/tasks 已完成，按 `workflow` 恢复：`fix` 调 `/comate-fix`，`full` 调 `/comate-open`；对应 skill 立即运行 `bash "$COMATE" guard <name> open --apply` 修复状态，并在 guard 成功后同轮继续下一阶段。
-- 若 `phase: archive`，只调用 `/comate-archive`；归档成功后 change 移入 archive 目录，不要再对旧活跃目录跑 guard。
-
-**phase_step 生命周期**：
-
-`phase_step` 严格属于当前阶段。所有 `state transition` 在切换 `phase` 时原子清空 `phase_step` 和 `phase_step_data`。禁止跨阶段保留或比较步骤编号；跨阶段事实必须记录在专用字段或落盘产物中。
-
-**Step 2：阶段判定**（按顺序检查，首个命中者生效）
-
-1. `archived: true` 或 change 已移入 archive → 流程完成
-2. `verify_result: pass` 且 `archived` 非 `true` → 调用 `/comate-archive`
-3. `verify_result: fail` → 验证失败决策阻塞点（决策点 4）
-4. `phase: verify` → 调用 `/comate-verify`。`tasks.md` 全勾不能单独触发 verify；验证失败回退到 build 后，必须继续按 build 路由修复。
-5. `phase: build` 或有 Design Doc 但 plan/执行未完成 → 按 workflow 路由：`fix`→`/comate-fix`，`full`→`/comate-build`
-6. `phase: design` 或有 change 但无 Design Doc → 调用 `/comate-design`
-7. `phase: open` → 按 workflow 路由：`fix`→`/comate-fix`，`full`→`/comate-open`；有活跃 change 但 `.comate.yaml` 缺失 → 调用 `/comate-open`
-8. 无活跃 change → 调用 `/comate-open`
-
-元数据与文件状态冲突时，以可验证的文件状态为准，先用 `state set` 修正 `.comate.yaml` 再继续。
-
-### 预设升级判定
-
-**fix → full**：见 `/comate-fix` 的两种模式升级条件（bug 模式 3+ 文件 / 架构变更 / schema 变更 / 新 API / 跨模块；调整模式 5+ 文件 / 多模块协调 / 5+ 测试 / 配置项增删 / 新 capability / delta spec）。
-
-### 错误处理速查
-
-| 场景 | 处理 |
-|------|------|
-| `openspec list --json` 失败 | 检查 openspec 是否安装，提示运行 `comate init` |
-| 子 skill 不可用 | 停止流程，提示安装或启用对应 skill |
-| `.comate.yaml` 损坏或缺失 | 以文件状态为真相源，用 `bash "$COMATE" state set` 修正后继续 |
-| 构建/测试失败 | 回 build 阶段修复，不进入 verify |
-| change 目录结构不全 | 按 `comate-open` 产物要求补齐缺失文件 |
-
-### 阶段流转
-
-<IMPORTANT>
-一次 `/comate` 调用从探测到的阶段开始，满足退出条件后推进到下一阶段。
-
-流转链：open → design → build → verify → archive
-
-**连续执行要求**：从探测到的阶段开始，agent 自动连续走完后续阶段。但**自动推进仅适用于无用户决策的流转点**。遇到决策阻塞点时，**必须用 AskUserQuestion 工具暂停等待用户明确回应**，不得用推荐规则、默认值或历史偏好替代用户确认，也不得只输出文字提示后继续执行。
-
-guard 成功、代码提交成功以及用户已经完成某个决策后的操作都不是新的暂停点。状态已满足下一阶段入口时，必须在当前调用内重新探测并继续；尤其是 fix 流程不得停在 `phase: open` 实现代码，也不得停在 build 提交之后等待用户发送“继续”。
-
-7 个决策点（部分含自动处理分支）+ Red Flags 表见 `comate/reference/decision-points.md`。**每个决策点先按三类行动分类**（用户决策 / 自动处理 / 停止条件）：判定属用户决策才用 AskUserQuestion 阻塞等待用户选择；属自动处理则直接执行并如实报告；其他无歧义流转自动进行，不得中途退出。
-</IMPORTANT>
-
----
-
-## 子命令速查
-
-| 命令 | 阶段 | Owner | 产物 |
-|------|------|-------|------|
-| `/comate-gate` | 0. PRD 门禁与拆分 | Claude | `<PRD>.gate.yaml`, 评审报告, N 个 change |
-| `/comate-open` | 1. 开题 | OpenSpec | proposal.md, design.md, tasks.md |
-| `/comate-design` | 2. 深度设计 | Superpowers | Design Doc, delta spec |
-| `/comate-build` | 3. 计划与构建 | Superpowers | 实施计划, 代码提交 |
-| `/comate-verify` | 4. 验证收尾 | 双方 | 验证报告, 分支处理 |
-| `/comate-archive` | 5. 归档 | OpenSpec | delta→main spec 同步, design doc 标注, 归档 |
-| `/comate-fix` | 预设 | 双方 | 快速小改动（bug 修复 + 非 bug 调整，跳过 brainstorming） |
-| `/comate-kb-integration` | 工具 | Claude | 第三方对接档案(从官方文档 URL 生成 integrations 目录档案) |
+# comate
 
 ```
-[原始 PRD] ──→ /comate-gate ──┐  (门禁+拆分，扇出 N 个 change)
-                  (Claude)        │
-/comate                           ▼
-  ↓ 自动探测
-/comate-open ──→ /comate-design ──→ /comate-build ──→ /comate-verify ──→ /comate-archive
-  (OpenSpec)      (Superpowers)      (Superpowers)      (双方)            (OpenSpec)
+/comate ── status ──┬─ 无 change ── new <name> [--mode full|fix] [--source <PRD>]
+                    └─ 有 change ── 按 next 继续
+open（brief + spec，停① 用户确认）→ build ⇄ verify（失败自动回修）→ 停② 接受 + 收尾 → archive
 ```
 
-需求来自对话时从 `/comate-open` 起步；来自原始 PRD 时先过 `/comate-gate` 门禁再拆分。
-
----
-
-## 参考附录
+状态机在脚本里，不在你的判断里。你只做两件事：按 next 执行下一步；把当前阶段的内容做好（按下面的索引读 reference）。
 
-### 脚本定位（单一入口）
+## 入口
 
-comate 收敛为**一个分发器** `comate/scripts/comate.sh`。skill 里只需定位这一个脚本并缓存到 `$COMATE`：
+`$COMATE` = 本 skill 目录下 `scripts/comate.mjs` 的绝对路径（默认 `~/.agents/skills/comate/scripts/comate.mjs`）。只需 Node ≥ 20 和 git，bash / PowerShell 用法相同。在项目目录里执行：
 
 ```bash
-COMATE="${COMATE:-$(for r in . ./.agents/skills ./.claude/skills ./.cursor/skills ./.codex/skills "$HOME"/.agents/skills "$HOME"/.claude/skills "$HOME"/.config/skills "$HOME"/.cursor/skills "$HOME"/.codex/skills "$HOME"/.gemini/skills; do
-  [ -d "$r" ] && find "$r" -maxdepth 6 -path '*/comate/scripts/comate.sh' -type f -print -quit 2>/dev/null
-done | head -1)}"
-if [ -z "$COMATE" ]; then
-  echo "ERROR: comate.sh 未找到，请确认 comate skill 已安装。" >&2
-  return 1 2>/dev/null || exit 1
-fi
+node "$COMATE" status [<name>] --json
 ```
 
-之后全程复用 `$COMATE`：
+- 每次 `/comate`、上下文压缩后、新会话，都先跑 `status`，不信对话记忆。
+- `status` 返回 `action: new`：按需求拟 kebab-case 名称（动词-对象，如 `add-email-login`），直接 `new`，名称在停①一并确认。
+  - **何时用 `--mode fix`**：边界清楚的小修（bug 修复、小调整、配置改动），且能快速明确根因、影响范围和修复方式。fix 走原则驱动澄清（三个核心问题），不走九大视角清单，prepare 通过后直接进 build。**边界不清时默认用 full**。
+  - 需求来自 PRD / 文件时加 `--source <路径>`（可多次）。
+- 返回多个 change：用户描述明显对应其中一个就直接 `status <name>` 并说明；否则 AskUserQuestion 请用户选。
+- 未初始化（找不到 `comate/comate/config.json`）：请用户在项目根运行 `comate init`。
 
-```bash
-bash "$COMATE" state   <name> init <full|fix>
-bash "$COMATE" state   <name> transition <event>
-bash "$COMATE" state   <name> check <phase> [--json]
-bash "$COMATE" state   <name> recover <phase>
-bash "$COMATE" state   <name> scale
-bash "$COMATE" state   <name> validate
-bash "$COMATE" guard   <name> <phase> [--apply] [--json]
-bash "$COMATE" handoff <name> <design|build> --write [--full]
-bash "$COMATE" sources <name> track <file...> [--note <text>]
-bash "$COMATE" sources <name> check | list
-bash "$COMATE" sources find <file>
-bash "$COMATE" dependency <name> archived
-bash "$COMATE" archive <name> [--dry-run]
-bash "$COMATE" status
-bash "$COMATE" doctor
-```
+## next 怎么用
 
-`guard --apply` 在检查全 PASS 后委托 `state transition` 自动流转。退出码契约：`0` 通过 / `1` 校验阻塞 / `2` 用法错误 / `3` 环境缺失 / `4` 状态文件损坏。
+每条命令（成功或被拦截）都输出 next。用 `--json` 读取；`command` 里的 `$COMATE` 就是 `comate` 字段给出的绝对路径。
 
-### `.comate.yaml` 字段参考
+| disposition | 你做什么 |
+|---|---|
+| `continue` | 读 `reference` 指向的文档（本阶段第一次时），完成 `message` 要求的工作，然后执行 `command`（`<…>` 占位符换成实际值） |
+| `await-user` | 用中文向用户完整转述 `message`（`accept` 时列出 risks），用 AskUserQuestion 把 `alternatives` 的 label 作为选项；用户选哪个就执行哪个的 `command` |
+| `blocked` | 处理 `message` / `warnings` 列出的问题，再跑 `status` |
+| `done` | 向用户报告结果，结束 |
 
-状态文件为「扁平 `key: value`」子集（不允许嵌套/列表/多行）。完整字段模板见 `comate/scripts/comate-lib.sh` 的 `FIELD_ORDER`。关键字段：
+- 带 `--expect <version>:<step>` 的命令，版本只能来自最新 next，不要自己拼。过期会被拒并返回最新 next。
+- 命令退出码 1 = 被守卫拦截：读 `error.message`，按提示修正后重跑；同一条拦截连续出现两次就停下，向用户说明原因。退出码 4 = 状态损坏：运行 `doctor`，不要手改 `state.json`。
+- 你只能写 `brief.md`、`specs/*/spec.md`（和脚本要你写的 handoff / verify 结果 JSON）。`state.json`、`verification.md` 只由脚本写。
 
-| 字段 | 含义 |
-|------|------|
-| `schema_version` | 状态文件格式版本（当前 1） |
-| `workflow` | `full` / `fix` |
-| `phase` | `open` / `design` / `build` / `verify` / `archive` |
-| `build_mode` | `subagent-driven-development` / `executing-plans` / `direct` |
-| `tdd_mode` | `tdd` / `direct`（build→verify 前必须已选；fix 默认 `direct`） |
-| `isolation` | `branch` / `worktree`（build→verify 前必须已选） |
-| `verify_mode` | `light` / `full`（由 scale 评估写入） |
-| `verify_result` | `pending` / `pass` / `fail` |
-| `verification_report` | 验证报告路径，verify-pass 前必须指向真实文件 |
-| `branch_status` | `pending` / `handled` / `discarded` |
-| `handoff_context` / `handoff_hash` | design 交接包路径 + 源文件 sha256 |
-| `impl_context` / `impl_hash` | build 交接包路径 + plan+tasks 的 sha256（防漂移） |
-| `direct_override` | full 流程用 `direct` 需显式 `true` |
-| `base_ref` / `base_branch` | init 记录的 HEAD + 探测到的默认分支 |
-| `source_kind` / `source_manifest` | 需求来源类型（`conversation` / `file`）+ 知识库源文件清单路径（防漂移） |
-| `build_command` / `verify_command` | 可选，项目构建/验证命令 |
+## 按阶段读 reference
 
-状态机硬约束（由 `guard` 与 `state transition` 双重强制）：
-- `build → verify` 前 `isolation` 必须为 `branch` 或 `worktree`
-- `build → verify` 前 `build_mode` 必须已选
-- `build → verify` 前 `tdd_mode` 必须为 `tdd` 或 `direct`
-- `build_mode: direct` 默认仅 fix；full 流程需 `direct_override: true`
-- `verify → archive` 前 `verification_report` 指向真实文件、`branch_status: handled`、`impl_hash` 与当前 plan+tasks 一致
+只读当前 `action` 对应的一份，不要一次全读。
 
-### 文件结构
-
-```
-openspec/                              # OpenSpec —— WHAT
-├── changes/<name>/
-│   ├── .comate.yaml                   # comate 状态机真相源
-│   ├── proposal.md / design.md / tasks.md
-│   ├── specs/<capability>/spec.md     # delta 能力规格
-│   └── .comate/handoff/               # 脚本生成的阶段交接包
-│       └── ../sources.manifest        # 知识库源文件清单（source_kind=file 时）
-└── specs/<capability>/spec.md         # 主 spec（归档时由 delta 覆盖）
-
-docs/knowledge-base/<...>.md           # 可追踪的需求源文档（source_kind=file）
-
-docs/superpowers/                      # Superpowers —— HOW
-├── specs/YYYY-MM-DD-<topic>-design.md # Design Doc
-├── plans/YYYY-MM-DD-<feature>.md      # 实施计划
-└── reports/                           # 验证报告
-```
+| action | 读 |
+|---|---|
+| `write-brief`、`confirm`、`resolve-drift` | `reference/open.md`（full 模式走原则驱动澄清，fix 模式见下行） |
+| `mode: fix` 的 open 阶段 | `reference/fix.md`（原则驱动：三个核心问题 + 按需查证） |
+| `build`、`repair` | `reference/build.md` |
+| `dispatch-verifier`、`resolve-stuck`、`resolve-blocker`、`accept-degraded` | `reference/verify.md` |
+| `accept`、`archive`、`retry-finish` | `reference/archive.md` |
 
-### 最佳实践
+## 不可违反
 
-1. brainstorming 不可跳过（fix 除外）
-2. delta spec 是活文档，build 阶段随时改，归档时同步
-3. 交接包由脚本生成（`handoff`），guard 校验 source/hash/mode
-4. tasks.md 实时同步，每完成一个任务勾选并提交
-5. 验证通过才归档
-6. 预设有边界，命中升级条件及时转 full
+- **只有两次固定停顿**：① open 确认（目标、范围、非目标、关键决定、全部验收项、change 名称）；② 验收全部通过后一次问完「接受结果 + 收尾方式」。其余由脚本决定是否停：首轮失败自动回修，不问用户。
+- 用户没有在停②明确选择（或配置 `finish: auto` + `auto_finish_action`）时，不 merge、不 push、不建 PR。
+- 验收由**未参与 build 的独立只读子 agent** 完成；平台没有子 agent 时走 `verify --unavailable`，由用户明确接受降级。`--expect` 只防过期，不代表用户同意：`await-user` 的选项必须真的问过用户再执行。
+- build 的完成依据是 handoff 中的 `addressed` 覆盖当前要求的验收项；回修依据和失败证据由脚本放进 next 的 `dispatch.repairs`。
+- build 中发现需求本身要变（新的用户可见行为、接口变更、新 capability），停下问用户，走 `decide --revise-requirements`，不在 build 里偷偷补。
+- 所有面向用户的输出用简体中文；代码、命令、路径、日志保持原样。