@rpamis/comet 0.3.8 → 0.4.0-beta.1

package/assets/skills/comet/rules/comet-phase-guard.md

@@ -1,7 +1,7 @@
 # Comet 阶段感知（防漂移规则）
 
 > 此规则每轮注入，防止长上下文时遗忘 Comet 流程状态。
-> Hook 平台额外执行 `comet-hook-guard.sh` 进行硬性拦截；
+> Hook 平台额外执行 `comet-hook-guard.mjs` 进行硬性拦截；
 > 此 Rule 是所有平台通用的软性防线。
 
 ## 全局规则
@@ -20,6 +20,24 @@
 | `verify` | 验证、branch handling | 跳过失败处理 |
 | `archive` | 确认归档、运行归档脚本 | 写源代码 |
 
+Hook 硬拦截白名单包括 `openspec/*`、`docs/superpowers/*`、`.superpowers/*`、`.claude/*` 和 `.comet/*` 等流程/平台工作区；这些路径可写不代表可以跳过当前阶段的产物和确认要求。
+
+### 阶段进入自洽性校验（写源代码前必查）
+
+仅看 `phase` 字段不够——还必须确认"是如何到达这个阶段的"。每次准备写源代码前，先用下表自检 `.comet.yaml` 是否处于**非法空跳**状态（绕过了前置阶段）。命中任一行，立即停止写源代码，按动作回到对应阶段补齐产物，不得信任 `phase` 字段直接续跑。
+
+| 检测到 | 判定 | 动作 |
+|--------|------|------|
+| `phase: build` + `workflow: full` + `design_doc` 为空/null | 绕过 design 空跳 | 停止写源代码，运行 `/comet-design` 补 Design Doc 并过 guard |
+| `phase: build` + proposal/design/tasks 任一缺失或为空 | 绕过 open 空跳 | 回 `/comet-open` 补齐三件套 |
+| `phase: archive` + `verify_result` ≠ `pass` | 绕过 verify 空跳 | 回 `/comet-verify` 完成验证 |
+
+> 说明：上表只覆盖 hook 硬门实际检测的范围（`design_doc` 空跳在 build 阶段；proposal/design/tasks 三件套完整性在 open→build 的 guard 退出时校验）。`verify` 阶段不在此写源码自洽门内——若 verify 发现产物缺失，按下方「Verify 阶段专项」的 verify-fail 回退处理。
+
+预设例外：`workflow: hotfix/tweak` 本就跳过 design，`design_doc` 为空属正常，不算非法。
+
+升级态说明：预设（hotfix/tweak）命中升级信号并经用户确认升级后，通过 `comet-state transition <name> preset-escalate` 合法地变为 `workflow: full` + `phase: design` + `design_doc: null`。此时 `phase: design` + `design_doc` 为空**属正常升级前置态**，不是非法空跳——agent 应进入 `/comet-design` 补 Design Doc。该终态不命中上表「绕过 design 空跳」行（该行仅检测 `phase: build`）。
+
 ### Skill 调用（不可用普通对话替代）
 
 以下操作必须通过 Skill 工具加载，Skill 不可用时应停止流程并提示安装：
@@ -37,6 +55,7 @@
 - **阶段退出**: `comet-guard <name> <phase> --apply`（必须看到 ALL CHECKS PASSED）
 - **压缩恢复**: `comet-state check <name> <phase> --recover`
 - **状态更新**: 关键操作后通过 `comet-state set` 更新字段，禁止手工编辑 .comet.yaml
+- **阶段推进只能经 guard/transition**: 禁止用 `comet-state set <name> phase <值>` 手动跳阶段（会绕过证据校验，脚本已硬拦截）；确需修复畸形状态时才用 `COMET_FORCE_PHASE=1` 逃生阀。预设（hotfix/tweak）升级到 full 必须用 `comet-state transition <name> preset-escalate`——这是唯一能合法回退 phase 到 design 并同步 workflow/classic_profile 的通道，直接 `set phase design` 和 `set classic_profile` 都会被硬拦截
 - **handoff 生成**: `comet-handoff <name> design --write`（禁止手写摘要）
 
 ### 用户确认（不可自动跳过）
@@ -45,7 +64,7 @@
 
 - **open**: 需求澄清完成确认、artifact 评审确认
 - **design**: brainstorming 方案确认（确认前不得创建 Design Doc）
-- **build**: plan-ready 暂停、isolation/build_mode/tdd_mode 选择、spec 大规模变更确认
+- **build**: plan-ready 暂停、`isolation` / `build_mode` / `tdd_mode` / `review_mode` 四项选择（工作区隔离、执行方式、TDD 模式、代码审查模式）、spec 大规模变更确认、预设（hotfix/tweak）升级判定二选一（命中质变信号或文件数 tripwire 时，交用户决定继续预设流程还是升级 full）
 - **verify**: 验证失败处理策略、branch handling 选择
 - **archive**: 归档前最终确认
 
@@ -60,7 +79,7 @@
 ## Build 阶段专项
 
 1. plan 创建后必须询问用户选择继续或暂停（`build_pause` 机制）
-2. 每个 task 验收后必须: tasks.md 打勾 → git commit（不得积攒）。`subagent-driven-development` 必须等 spec compliance 与 code quality 两个审查都通过，再由协调者按任务唯一文本定向勾选和验证；不得用未完成任务总表代替当前任务验证
+2. 每个 task 验收后必须: tasks.md 打勾 → git commit（不得积攒）。`subagent-driven-development` 必须按当前 `review_mode` 完成验收，再由协调者按任务唯一文本定向勾选和验证；不得用未完成任务总表代替当前任务验证
 3. 遇到失败必须加载 **systematic-debugging** skill，根因未定位前不得提出源码修复
 4. spec 变更分级: 小改直接编辑 | 中改加载 brainstorming | 大改暂停等用户确认拆分
 
@@ -69,31 +88,45 @@
 1. 第一步运行 `comet-state scale <name>` 确定验证级别
 2. 验证失败后列出失败项等用户选择，CRITICAL 必须修
 3. 连续 3 次失败后必须让用户选择接受偏差或继续修
+4. 用户选择修复时运行 `comet-state transition <name> verify-fail`：该转移会把 `phase` 回退到 `build`（不是停在 verify），随后进入 `/comet-build` 修复，修完重新过 build→verify guard
 
 ## 上下文压缩恢复
 
 如果怀疑发生上下文压缩（之前对话被摘要、找不到之前讨论的内容），立即运行：
 
 ```bash
-"$COMET_BASH" "$COMET_STATE" check <name> <phase> --recover
+node "$COMET_STATE" check <name> <phase> --recover
 ```
 
 按脚本输出的 **Recovery action** 决定下一步。
 
+恢复后必须先用「阶段进入自洽性校验」表复查一遍：若发现 `phase` 与产物不自洽（design_doc/三件套/verify_result 任一不匹配），按非法空跳处理，回对应阶段补齐，不得信任 `phase` 字段直接续跑。
+
 **特别注意 `build_mode`**：若恢复脚本输出 `build_mode: subagent-driven-development`，你是协调者，不是执行者。必须：
 1. 使用 Skill 工具重新加载 Superpowers `subagent-driven-development` 技能 (Use the Skill tool to reload the Superpowers `subagent-driven-development` skill)
 2. 读取 `comet/reference/subagent-dispatch.md` 获取 Comet 专属扩展 (re-read `comet/reference/subagent-dispatch.md` for Comet-specific extensions)
 3. 读取 `openspec/changes/<name>/.comet/subagent-progress.md` 恢复精确阶段、证据和审查-修复轮次 (Read `openspec/changes/<name>/.comet/subagent-progress.md` to recover the exact stage, evidence, and review-fix round)
 4. 禁止在主会话中直接执行 task (Do not execute the pending task directly in the main window)
 5. 按检查点恢复；缺失或不匹配时才从第一个未勾选 task 开始
-6. 已提交但未通过双审查的 task 保持未勾选，继续审查/修复循环
-7. task 通过双审查和定向勾选验证后立即继续下一个 task，不得总结或询问是否继续
+6. 已提交但未按 `review_mode` 完成验收的 task 保持未勾选，继续对应的验证/审查/修复循环
+7. task 按 `review_mode` 完成验收并通过定向勾选验证后立即继续下一个 task，不得总结或询问是否继续
 
 ## 阶段退出后自动过渡
 
-guard `--apply` 成功后，必须调用下一阶段的 skill：
+guard `--apply` 成功后，不得在本规则中硬编码下一阶段 skill。必须先运行：
+
+```bash
+comet-state next <change-name>
+```
+
+若已通过 `comet-env.mjs` 定位脚本，等价运行：
+
+```bash
+node "$COMET_STATE" next <change-name>
+```
+
+按脚本输出决定下一步：
 
-- open → `comet-design`（full）/ `comet-build`（hotfix/tweak）
-- design → `comet-build`
-- build → `comet-verify`
-- verify → `comet-archive`
+- `NEXT: auto` → 使用 Skill 工具加载 `SKILL` 指向的 skill
+- `NEXT: manual` → 不加载下一 skill，按 `HINT` 提示用户手动继续
+- `NEXT: done` → 流程已完成，无需继续

package/assets/skills/comet/runtime/classic/checks.yaml

@@ -0,0 +1,6 @@
+runtime:
+  - id: classic-completed
+    scope: completion
+    type: state_equals
+    field: status
+    equals: completed

package/assets/skills/comet/runtime/classic/guardrails.yaml

@@ -0,0 +1,13 @@
+allowedSkills:
+  - comet-open
+  - comet-design
+  - comet-build
+  - comet-verify
+  - comet-archive
+  - comet-hotfix
+  - comet-tweak
+allowedAgents: []
+allowedTools: []
+maxIterations: 500
+maxRetriesPerAction: 3
+confirmationRequiredFor: []

package/assets/skills/comet/runtime/classic/skill.yaml

@@ -0,0 +1,122 @@
+apiVersion: comet/v1alpha1
+kind: Skill
+metadata:
+  name: comet-classic
+  version: "1"
+  description: Internal compatibility orchestration for classic Comet full, hotfix, and tweak workflows
+goal:
+  statement: Advance or restore a classic Comet Run without changing the user command surface
+  inputs:
+    - name: classic-state
+      description: Validated ClassicState consistent with the Run projection
+      required: true
+    - name: evidence
+      description: Structured evidence produced by the Classic Evidence collector
+      required: true
+  outputs:
+    - name: run-state
+      description: Atomically synchronized Classic and Run state
+      required: true
+  success:
+    - Legacy fields and Run fields remain consistent
+    - Every step invokes only a declared public Comet Skill
+    - The completed state passes its completion eval
+orchestration:
+  mode: deterministic
+  entry: full.open
+  steps:
+    - id: full.open
+      action: { type: invoke_skill, ref: comet-open }
+      next: full.design.handoff
+    - id: full.design.handoff
+      action: { type: invoke_skill, ref: comet-design }
+      next: full.design.document
+    - id: full.design.document
+      action: { type: invoke_skill, ref: comet-design }
+      next: full.build.plan
+    - id: full.build.plan
+      action: { type: invoke_skill, ref: comet-build }
+      next: full.build.plan-ready
+    - id: full.build.plan-ready
+      action: { type: invoke_skill, ref: comet-build }
+      next: full.build.configure
+    - id: full.build.configure
+      action: { type: invoke_skill, ref: comet-build }
+      next: full.build.execute
+    - id: full.build.execute
+      action: { type: invoke_skill, ref: comet-build }
+      next: full.build.complete
+    - id: full.build.complete
+      action: { type: invoke_skill, ref: comet-build }
+      next: full.verify.run
+    - id: full.build.fix
+      action: { type: invoke_skill, ref: comet-build }
+      next: full.build.execute
+    - id: full.verify.run
+      action: { type: invoke_skill, ref: comet-verify }
+      next: full.verify.branch
+    - id: full.verify.branch
+      action: { type: invoke_skill, ref: comet-verify }
+      next: full.archive.confirm
+    - id: full.archive.confirm
+      action: { type: invoke_skill, ref: comet-archive }
+      next: full.archive.execute
+    - id: full.archive.execute
+      action: { type: invoke_skill, ref: comet-archive }
+      next: completed
+    - id: hotfix.open
+      action: { type: invoke_skill, ref: comet-hotfix }
+      next: hotfix.build.execute
+    - id: hotfix.build.execute
+      action: { type: invoke_skill, ref: comet-build }
+      next: hotfix.build.complete
+    - id: hotfix.build.complete
+      action: { type: invoke_skill, ref: comet-build }
+      next: hotfix.verify.run
+    - id: hotfix.verify.run
+      action: { type: invoke_skill, ref: comet-verify }
+      next: hotfix.verify.branch
+    - id: hotfix.verify.branch
+      action: { type: invoke_skill, ref: comet-verify }
+      next: hotfix.archive.confirm
+    - id: hotfix.archive.confirm
+      action: { type: invoke_skill, ref: comet-archive }
+      next: hotfix.archive.execute
+    - id: hotfix.archive.execute
+      action: { type: invoke_skill, ref: comet-archive }
+      next: completed
+    - id: tweak.open
+      action: { type: invoke_skill, ref: comet-tweak }
+      next: tweak.build.execute
+    - id: tweak.build.execute
+      action: { type: invoke_skill, ref: comet-build }
+      next: tweak.build.complete
+    - id: tweak.build.complete
+      action: { type: invoke_skill, ref: comet-build }
+      next: tweak.verify.run
+    - id: tweak.verify.run
+      action: { type: invoke_skill, ref: comet-verify }
+      next: tweak.verify.branch
+    - id: tweak.verify.branch
+      action: { type: invoke_skill, ref: comet-verify }
+      next: tweak.archive.confirm
+    - id: tweak.archive.confirm
+      action: { type: invoke_skill, ref: comet-archive }
+      next: tweak.archive.execute
+    - id: tweak.archive.execute
+      action: { type: invoke_skill, ref: comet-archive }
+      next: completed
+    - id: completed
+      action: { type: checkpoint }
+      completionEvals:
+        - classic-completed
+skills:
+  - id: comet-open
+  - id: comet-design
+  - id: comet-build
+  - id: comet-verify
+  - id: comet-archive
+  - id: comet-hotfix
+  - id: comet-tweak
+agents: []
+tools: []

package/assets/skills/comet/scripts/comet-archive.mjs

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+import { main } from './comet-runtime.mjs';
+process.exitCode = await main(["archive", ...process.argv.slice(2)]);

package/assets/skills/comet/scripts/comet-env.mjs

@@ -0,0 +1,15 @@
+#!/usr/bin/env node
+// Comet script locator — prints the absolute path to this scripts directory.
+//
+// Usage:
+//   COMET_SCRIPTS_DIR="$(node /path/to/comet-env.mjs)"
+//
+// The skill boilerplate runs this once to resolve the sibling command scripts
+// (comet-state.mjs, comet-guard.mjs, ...) without depending on bash.
+import { dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+// Use forward slashes so the path is safe to interpolate into any shell and
+// is accepted verbatim by Node on every platform (Windows included).
+const scriptDir = dirname(fileURLToPath(import.meta.url)).replace(/\\/gu, '/');
+process.stdout.write(`${scriptDir}\n`);

package/assets/skills/comet/scripts/comet-guard.mjs

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+import { main } from './comet-runtime.mjs';
+process.exitCode = await main(["guard", ...process.argv.slice(2)]);

package/assets/skills/comet/scripts/comet-handoff.mjs

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+import { main } from './comet-runtime.mjs';
+process.exitCode = await main(["handoff", ...process.argv.slice(2)]);

package/assets/skills/comet/scripts/comet-hook-guard.mjs

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+import { main } from './comet-runtime.mjs';
+process.exitCode = await main(["hook-guard", ...process.argv.slice(2)]);

package/assets/skills/comet/scripts/comet-intent.mjs

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+import { main } from './comet-runtime.mjs';
+process.exitCode = await main(["intent", ...process.argv.slice(2)]);