From eeac7a023b8ea6033b2606f7fd7d412881e7c398 Mon Sep 17 00:00:00 2001
From: zheng <forggy0113@gmail.com>
Date: Sat, 6 Jun 2026 01:38:33 +0800
Subject: [PATCH 1/7] refactor bash script to js script

refactor bash script to js script, and make some tweaks to skills
---
 .github/PULL_REQUEST_TEMPLATE.md              |   5 +-
 .github/workflows/ci.yml                      |  48 +-
 AGENTS.md                                     |  25 +-
 CHANGELOG.md                                  |   9 +-
 CLAUDE.md                                     |  25 +-
 CONTRIBUTING.md                               |   1 -
 README-zh.md                                  |  38 +-
 README.md                                     |  38 +-
 assets/manifest.json                          |  13 +-
 assets/skills-zh/comet-archive/SKILL.md       |  16 +-
 assets/skills-zh/comet-build/SKILL.md         |  34 +-
 assets/skills-zh/comet-design/SKILL.md        |  28 +-
 assets/skills-zh/comet-hotfix/SKILL.md        |  22 +-
 assets/skills-zh/comet-open/SKILL.md          |  18 +-
 assets/skills-zh/comet-tweak/SKILL.md         |  22 +-
 assets/skills-zh/comet-verify/SKILL.md        |  40 +-
 assets/skills-zh/comet/SKILL.md               |  38 +-
 assets/skills/comet-archive/SKILL.md          |  16 +-
 assets/skills/comet-build/SKILL.md            |  34 +-
 assets/skills/comet-design/SKILL.md           |  28 +-
 assets/skills/comet-hotfix/SKILL.md           |  22 +-
 assets/skills/comet-open/SKILL.md             |  18 +-
 assets/skills/comet-tweak/SKILL.md            |  22 +-
 assets/skills/comet-verify/SKILL.md           |  40 +-
 assets/skills/comet/SKILL.md                  |  38 +-
 assets/skills/comet/scripts/comet-archive.js  | 106 ++
 assets/skills/comet/scripts/comet-archive.sh  | 295 ------
 assets/skills/comet/scripts/comet-env.js      |  21 +
 assets/skills/comet/scripts/comet-env.sh      | 110 ---
 assets/skills/comet/scripts/comet-guard.js    | 281 ++++++
 assets/skills/comet/scripts/comet-guard.sh    | 596 ------------
 assets/skills/comet/scripts/comet-handoff.js  | 109 +++
 assets/skills/comet/scripts/comet-handoff.sh  | 263 -----
 assets/skills/comet/scripts/comet-lib.js      | 212 ++++
 assets/skills/comet/scripts/comet-state.js    | 384 ++++++++
 assets/skills/comet/scripts/comet-state.sh    | 908 ------------------
 .../comet/scripts/comet-yaml-validate.js      |  68 ++
 .../comet/scripts/comet-yaml-validate.sh      | 200 ----
 package.json                                  |   4 +-
 pnpm-lock.yaml                                |  27 +-
 scripts/run-bats.js                           | 189 ----
 test/shell/comet-state.bats                   | 214 -----
 test/ts/comet-scripts.test.ts                 | 399 +++-----
 test/ts/run-bats.test.ts                      |  38 -
 test/ts/skills.test.ts                        |  25 +-
 45 files changed, 1684 insertions(+), 3403 deletions(-)
 create mode 100644 assets/skills/comet/scripts/comet-archive.js
 delete mode 100644 assets/skills/comet/scripts/comet-archive.sh
 create mode 100644 assets/skills/comet/scripts/comet-env.js
 delete mode 100644 assets/skills/comet/scripts/comet-env.sh
 create mode 100644 assets/skills/comet/scripts/comet-guard.js
 delete mode 100644 assets/skills/comet/scripts/comet-guard.sh
 create mode 100644 assets/skills/comet/scripts/comet-handoff.js
 delete mode 100644 assets/skills/comet/scripts/comet-handoff.sh
 create mode 100644 assets/skills/comet/scripts/comet-lib.js
 create mode 100644 assets/skills/comet/scripts/comet-state.js
 delete mode 100644 assets/skills/comet/scripts/comet-state.sh
 create mode 100644 assets/skills/comet/scripts/comet-yaml-validate.js
 delete mode 100644 assets/skills/comet/scripts/comet-yaml-validate.sh
 delete mode 100644 scripts/run-bats.js
 delete mode 100644 test/shell/comet-state.bats
 delete mode 100644 test/ts/run-bats.test.ts

diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md
index b2be4a74..74fe9ae4 100644
--- a/.github/PULL_REQUEST_TEMPLATE.md
+++ b/.github/PULL_REQUEST_TEMPLATE.md
@@ -9,7 +9,7 @@
 - [ ] CLI commands (`init`, `status`, `doctor`, `update`)
 - [ ] Core installer / platform detection
 - [ ] Comet skills (`assets/skills/`, `assets/skills-zh/`)
-- [ ] Comet shell scripts (`assets/skills/comet/scripts/`)
+- [ ] Comet Node scripts (`assets/skills/comet/scripts/`)
 - [ ] Tests / CI
 - [ ] Documentation / changelog
 - [ ] Other:
@@ -23,7 +23,6 @@
 - [ ] `pnpm format:check`
 - [ ] `pnpm test`
 - [ ] `pnpm test -- test/ts/comet-scripts.test.ts`
-- [ ] `pnpm test:shell`
 - [ ] Not run:
 
 ## ✅ Checklist
@@ -33,7 +32,7 @@
 - [ ] `CHANGELOG.md` is updated when behavior changes
 - [ ] Skill changes were made in Chinese first when applicable, then synced to English
 - [ ] New scripts are included in `assets/manifest.json` and relevant tests
-- [ ] Shell scripts remain portable across macOS, Linux, and Windows Git Bash
+- [ ] Comet Node scripts remain portable across macOS, Linux, and Windows
 - [ ] No unrelated generated files or local artifacts are included
 
 ## 👀 Notes for Reviewers
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 03e5cc51..49f7b2d9 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -34,27 +34,6 @@ jobs:
 
       - run: pnpm test:coverage
 
-  shellcheck:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v4
-
-      - name: Run shellcheck
-        uses: ludeeus/action-shellcheck@2.0.0
-        with:
-          scandir: ./assets/skills/comet/scripts
-
-  bats-tests:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v4
-
-      - name: Install bats
-        run: sudo apt-get install -y bats
-
-      - name: Run shell tests
-        run: bats test/shell/*.bats
-
   script-smoke:
     runs-on: ${{ matrix.os }}
     strategy:
@@ -77,9 +56,6 @@ jobs:
       - name: Run Comet script smoke tests
         run: pnpm test -- test/ts/comet-scripts.test.ts
 
-      - name: Run portable shell tests
-        run: pnpm test:shell
-
   init-e2e:
     runs-on: ${{ matrix.os }}
     strategy:
@@ -132,11 +108,13 @@ jobs:
                     .iflow/skills .pi/skills .qoder/skills .agents/skills \
                     .bob/skills .forge/skills .trae/skills .github/skills; do
             check_file "$PROJ/$sd/comet/SKILL.md"
-            check_file "$PROJ/$sd/comet/scripts/comet-guard.sh"
-            check_file "$PROJ/$sd/comet/scripts/comet-state.sh"
-            check_file "$PROJ/$sd/comet/scripts/comet-handoff.sh"
-            check_file "$PROJ/$sd/comet/scripts/comet-yaml-validate.sh"
-            check_file "$PROJ/$sd/comet/scripts/comet-archive.sh"
+            check_file "$PROJ/$sd/comet/scripts/comet-guard.js"
+            check_file "$PROJ/$sd/comet/scripts/comet-state.js"
+            check_file "$PROJ/$sd/comet/scripts/comet-handoff.js"
+            check_file "$PROJ/$sd/comet/scripts/comet-yaml-validate.js"
+            check_file "$PROJ/$sd/comet/scripts/comet-archive.js"
+            check_file "$PROJ/$sd/comet/scripts/comet-env.js"
+            check_file "$PROJ/$sd/comet/scripts/comet-lib.js"
           done
           echo "All 28 platforms project Comet skills: OK"
         shell: bash
@@ -220,11 +198,13 @@ jobs:
                     .iflow/skills .pi/skills .qoder/skills .gemini/antigravity/skills \
                     .bob/skills .forge/skills .trae/skills .github/skills; do
             check_file "$HOME_DIR/$sd/comet/SKILL.md"
-            check_file "$HOME_DIR/$sd/comet/scripts/comet-guard.sh"
-            check_file "$HOME_DIR/$sd/comet/scripts/comet-state.sh"
-            check_file "$HOME_DIR/$sd/comet/scripts/comet-handoff.sh"
-            check_file "$HOME_DIR/$sd/comet/scripts/comet-yaml-validate.sh"
-            check_file "$HOME_DIR/$sd/comet/scripts/comet-archive.sh"
+            check_file "$HOME_DIR/$sd/comet/scripts/comet-guard.js"
+            check_file "$HOME_DIR/$sd/comet/scripts/comet-state.js"
+            check_file "$HOME_DIR/$sd/comet/scripts/comet-handoff.js"
+            check_file "$HOME_DIR/$sd/comet/scripts/comet-yaml-validate.js"
+            check_file "$HOME_DIR/$sd/comet/scripts/comet-archive.js"
+            check_file "$HOME_DIR/$sd/comet/scripts/comet-env.js"
+            check_file "$HOME_DIR/$sd/comet/scripts/comet-lib.js"
           done
           echo "All 28 platforms global Comet skills: OK"
         shell: bash
diff --git a/AGENTS.md b/AGENTS.md
index 4bdd6754..fed2e4a0 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -1,34 +1,35 @@
 ## 测试
 
 ```bash
-npx vitest run test/ts/comet-scripts.test.ts   # shell 脚本测试
+npx vitest run test/ts/comet-scripts.test.ts   # Comet Node 脚本测试
 npx vitest run                                   # 全量测试
 ```
 
-## Shell 脚本规范
+## Comet Node 脚本规范
 
-脚本位于 `assets/skills/comet/scripts/`，必须跨平台兼容（macOS / Linux / Windows Git Bash）：
+脚本位于 `assets/skills/comet/scripts/`，必须跨平台兼容（macOS / Linux / Windows）：
 
-- **禁止** `sed -i`（GNU/BSD 不兼容），用 `awk` 做字段替换
-- 必须兼容 `sha256sum`（GNU）和 `shasum -a 256`（BSD/macOS）
-- 所有可选 grep 结果加 `|| true` 防止 `pipefail` 误杀
+- 使用 Node.js 实现，不新增 `.sh` wrapper
+- 脚本间调用使用 `node <script>.js` 或共享 `runNode`
+- 用户配置的 `build_command` / `verify_command` 允许交给平台 shell 执行
 - 新增脚本必须加入 `beforeEach` 的拷贝列表和 manifest.json
 
 ## 脚本依赖关系
 
 ```
-comet-state.sh ← comet-guard.sh, comet-handoff.sh, comet-archive.sh
-comet-yaml-validate.sh ← comet-guard.sh (preflight 阶段)
-comet-handoff.sh ← comet-state.sh (写入 handoff_context/handoff_hash)
+comet-lib.js ← comet-state.js, comet-guard.js, comet-handoff.js, comet-archive.js, comet-yaml-validate.js, comet-env.js
+comet-state.js ← comet-guard.js, comet-handoff.js, comet-archive.js
+comet-yaml-validate.js ← comet-guard.js (preflight 阶段)
+comet-handoff.js ← comet-state.js (写入 handoff_context/handoff_hash)
 ```
 
-新增共享工具函数时（如 hash、yaml 解析），如果两个脚本都需要，允许在各自脚本中独立实现，不强制抽共享文件。
+新增共享工具函数时优先放入 `comet-lib.js`，避免各脚本行为分叉。
 
 ## .comet.yaml 状态机
 
 每个 change 的状态文件，字段变更需要同步三处：
-1. `comet-state.sh` — `cmd_set` 白名单 + enum 验证
-2. `comet-yaml-validate.sh` — schema 校验 + KNOWN_KEYS
+1. `comet-state.js` — 可写字段白名单 + enum 验证
+2. `comet-yaml-validate.js` — schema 校验 + KNOWN_KEYS
 3. `test/ts/comet-scripts.test.ts` — 测试中的 yaml 字符串
 
 ## 双语言 Skill
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 6768c9ae..eb67a220 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -6,26 +6,27 @@ All notable changes to @rpamis/comet will be documented in this file.
 
 ### Added
 
+- **Cross-platform Comet Node scripts**: Added Node.js implementations for Comet state, guard, handoff, archive, YAML validation, environment discovery, and shared script utilities so bundled automation runs without Bash-specific script files.
 - **Plan-ready build pause state**: Added `build_pause` as a dedicated build-phase pause marker so Comet can stop after plan generation without confusing the pause with the actual execution method.
 - **Plan-ready pause design**: Added a design record for the model-switching pause workflow, covering recovery behavior, stale pause handling, and plan-missing remediation.
 
 ### Changed
 
 - **Build recovery routing**: `/comet` and `/comet-build` now recognize `build_pause: plan-ready`, reuse the existing plan, and resume at workspace isolation and execution-method selection instead of regenerating the plan.
+- **Comet script invocation**: Skills, manifest entries, docs, and CI now invoke Comet automation through `node comet-*.js` instead of Bash script entrypoints for simpler Windows compatibility.
 - **Bilingual workflow documentation**: Chinese and English Comet skills now describe the plan-ready pause point, clarify that `build_pause` is not `build_mode`, and document the same state field in both README files.
 
 ### Fixed
 
 - **GitHub Copilot Superpowers skill names**: Comet skills now invoke the bare Superpowers skill names installed by the GitHub Copilot skills path, avoiding blocked workflows caused by unresolved `superpowers:*` aliases.
-- **Windows bash resolution**: Comet now resolves a usable bash executable through `COMET_BASH`, rejects the Windows WSL launcher path, and uses the resolved executable for nested script calls so guard, handoff, and archive flows do not fall back to a broken PATH `bash`.
-- **Shell test runner bash resolution**: `run-bats.js` now resolves a usable bash through `COMET_TEST_BASH`, `COMET_BASH`, PATH, or Git Bash defaults, avoiding the broken Windows WSL launcher when running shell tests from Node.
+- **Windows script execution**: Comet guard, handoff, archive, state, and validation flows now use Node for internal script calls, avoiding failures caused by unavailable or incompatible Bash executables on Windows.
 - **Schema validation fatal output**: Guard validation now preserves the final fatal schema-validation message after printing validator diagnostics, making invalid `.comet.yaml` failures easier to recognize.
 
 ### Tests
 
 - **Superpowers skill invocation regression**: Added coverage that shipped Comet skill prose does not reference plugin-prefixed Superpowers aliases.
-- **Comet bash execution regression**: Added coverage for nested script calls, shipped command examples, and the shell test runner so Comet uses resolved bash paths instead of raw PATH `bash`.
-- **Plan-ready pause regression**: Added shell-script coverage for `build_pause` initialization, schema validation, state updates, and build recovery output.
+- **Comet Node script regression**: Added coverage for nested script calls, shipped command examples, manifest entries, and environment discovery so Comet uses Node script entrypoints instead of Bash wrappers.
+- **Plan-ready pause regression**: Added Comet script coverage for `build_pause` initialization, schema validation, state updates, and build recovery output.
 - **README state-field regression**: Added README coverage to ensure `build_pause` appears in examples and field descriptions for both English and Chinese documentation.
 
 ## What's Changed [0.3.5] - 2026-05-29
diff --git a/CLAUDE.md b/CLAUDE.md
index 4bdd6754..fed2e4a0 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -1,34 +1,35 @@
 ## 测试
 
 ```bash
-npx vitest run test/ts/comet-scripts.test.ts   # shell 脚本测试
+npx vitest run test/ts/comet-scripts.test.ts   # Comet Node 脚本测试
 npx vitest run                                   # 全量测试
 ```
 
-## Shell 脚本规范
+## Comet Node 脚本规范
 
-脚本位于 `assets/skills/comet/scripts/`，必须跨平台兼容（macOS / Linux / Windows Git Bash）：
+脚本位于 `assets/skills/comet/scripts/`，必须跨平台兼容（macOS / Linux / Windows）：
 
-- **禁止** `sed -i`（GNU/BSD 不兼容），用 `awk` 做字段替换
-- 必须兼容 `sha256sum`（GNU）和 `shasum -a 256`（BSD/macOS）
-- 所有可选 grep 结果加 `|| true` 防止 `pipefail` 误杀
+- 使用 Node.js 实现，不新增 `.sh` wrapper
+- 脚本间调用使用 `node <script>.js` 或共享 `runNode`
+- 用户配置的 `build_command` / `verify_command` 允许交给平台 shell 执行
 - 新增脚本必须加入 `beforeEach` 的拷贝列表和 manifest.json
 
 ## 脚本依赖关系
 
 ```
-comet-state.sh ← comet-guard.sh, comet-handoff.sh, comet-archive.sh
-comet-yaml-validate.sh ← comet-guard.sh (preflight 阶段)
-comet-handoff.sh ← comet-state.sh (写入 handoff_context/handoff_hash)
+comet-lib.js ← comet-state.js, comet-guard.js, comet-handoff.js, comet-archive.js, comet-yaml-validate.js, comet-env.js
+comet-state.js ← comet-guard.js, comet-handoff.js, comet-archive.js
+comet-yaml-validate.js ← comet-guard.js (preflight 阶段)
+comet-handoff.js ← comet-state.js (写入 handoff_context/handoff_hash)
 ```
 
-新增共享工具函数时（如 hash、yaml 解析），如果两个脚本都需要，允许在各自脚本中独立实现，不强制抽共享文件。
+新增共享工具函数时优先放入 `comet-lib.js`，避免各脚本行为分叉。
 
 ## .comet.yaml 状态机
 
 每个 change 的状态文件，字段变更需要同步三处：
-1. `comet-state.sh` — `cmd_set` 白名单 + enum 验证
-2. `comet-yaml-validate.sh` — schema 校验 + KNOWN_KEYS
+1. `comet-state.js` — 可写字段白名单 + enum 验证
+2. `comet-yaml-validate.js` — schema 校验 + KNOWN_KEYS
 3. `test/ts/comet-scripts.test.ts` — 测试中的 yaml 字符串
 
 ## 双语言 Skill
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 4d72b160..51fb3d60 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -17,7 +17,6 @@ pnpm build
 | `pnpm build` | Compile TypeScript |
 | `pnpm test` | Run unit tests |
 | `pnpm test:coverage` | Run tests with coverage |
-| `pnpm test:shell` | Run shell script tests (requires bats) |
 | `pnpm lint` | Run ESLint |
 | `pnpm format` | Run Prettier |
 
diff --git a/README-zh.md b/README-zh.md
index edfeb84d..d774e837 100644
--- a/README-zh.md
+++ b/README-zh.md
@@ -64,7 +64,7 @@ Superpowers 在头脑风暴后会产出 Spec 文档，但这个文档通常没
 
 - **如何把文档同步从“用户提醒”变成自动化** — Comet 将 handoff、状态更新、校验和归档同步放进脚本化流程，减少“记得更新 design doc”“记得同步 spec”“记得归档 change”这类反复提示。
 
-- **如何设计 Agent 可执行的守护条件** — Comet 的阶段退出不是简单相信 Agent 说“完成了”，而是通过 `comet-guard.sh`、`comet-yaml-validate.sh`、`comet-state.sh` 等脚本检查任务、状态字段、验证证据和归档条件，满足条件后才允许推进。
+- **如何设计 Agent 可执行的守护条件** — Comet 的阶段退出不是简单相信 Agent 说“完成了”，而是通过 `comet-guard.js`、`comet-yaml-validate.js`、`comet-state.js` 等 Node 脚本检查任务、状态字段、验证证据和归档条件，满足条件后才允许推进。
 
 - **如何做跨平台 Skill 分发和安装** — Comet 支持多种 AI 编码平台、项目级/全局安装、中文/英文 Skill 选择，以及平台差异化目录（例如 Antigravity 的项目级和全局路径不同），可以作为 CLI 安装器和 Skill 打包结构的参考。
 
@@ -238,12 +238,12 @@ npx skills add rpamis/comet
 
 | 脚本 | 用途 |
 |--------|---------|
-| `comet-env.sh` | 脚本发现助手 — 导出 `COMET_GUARD`、`COMET_STATE`、`COMET_HANDOFF`、`COMET_ARCHIVE` 等内置脚本路径 |
-| `comet-guard.sh` | 阶段转换守护 — 验证退出条件，`--apply` 自动更新 `.comet.yaml` |
-| `comet-handoff.sh` | 设计交接 — 从 OpenSpec 制品生成带 SHA256 追踪的确定性上下文包 |
-| `comet-archive.sh` | 一键归档 — 验证状态、同步 specs、移至归档、更新状态 |
-| `comet-yaml-validate.sh` | 模式校验器 — 校验 `.comet.yaml` 结构和字段值 |
-| `comet-state.sh` | 统一状态管理 — init/set/get/check/scale，agent 的专属 YAML 接口 |
+| `comet-env.js` | 脚本发现助手 — 以 JSON 输出 `COMET_GUARD`、`COMET_STATE`、`COMET_HANDOFF`、`COMET_ARCHIVE` 等内置脚本路径 |
+| `comet-guard.js` | 阶段转换守护 — 验证退出条件，`--apply` 自动更新 `.comet.yaml` |
+| `comet-handoff.js` | 设计交接 — 从 OpenSpec 制品生成带 SHA256 追踪的确定性上下文包 |
+| `comet-archive.js` | 一键归档 — 验证状态、同步 specs、移至归档、更新状态 |
+| `comet-yaml-validate.js` | 模式校验器 — 校验 `.comet.yaml` 结构和字段值 |
+| `comet-state.js` | 统一状态管理 — init/set/get/check/scale，agent 的专属 YAML 接口 |
 
 </details>
 
@@ -325,7 +325,7 @@ handoff_context: openspec/changes/<name>/.comet/handoff/design-context.json
 handoff_hash: <sha256>
 ```
 
-full workflow 初始化时 `build_mode`、`build_pause`、`isolation` 和 `verify_mode` 可以暂时为 `null`；进入 `build → verify` 前必须完成 `build_mode` 与 `isolation` 决策并写入合法值。`build_pause` 记录 build 阶段内部暂停点：`null` 表示无暂停，`plan-ready` 表示 plan 已生成，用户在选择隔离方式和执行方式前暂停。它不是执行方式，不得写入 `build_mode`。`verification_report` 在验证报告生成前保持 `null`，`verify-pass` 要求该报告文件存在且 `branch_status: handled`。示例中 `archived` 之后的字段是可选字段或脚本派生字段：`direct_override` 只在 full workflow 直接构建时需要，项目命令未配置时可以不存在，`handoff_context` 和 `handoff_hash` 由 `comet-handoff.sh` 在离开 design 阶段前写入。项目可在 change 或仓库根配置中设置 `build_command` / `verify_command`，guard 会优先运行并打印失败输出。
+full workflow 初始化时 `build_mode`、`build_pause`、`isolation` 和 `verify_mode` 可以暂时为 `null`；进入 `build → verify` 前必须完成 `build_mode` 与 `isolation` 决策并写入合法值。`build_pause` 记录 build 阶段内部暂停点：`null` 表示无暂停，`plan-ready` 表示 plan 已生成，用户在选择隔离方式和执行方式前暂停。它不是执行方式，不得写入 `build_mode`。`verification_report` 在验证报告生成前保持 `null`，`verify-pass` 要求该报告文件存在且 `branch_status: handled`。示例中 `archived` 之后的字段是可选字段或脚本派生字段：`direct_override` 只在 full workflow 直接构建时需要，项目命令未配置时可以不存在，`handoff_context` 和 `handoff_hash` 由 `comet-handoff.js` 在离开 design 阶段前写入。项目可在 change 或仓库根配置中设置 `build_command` / `verify_command`，guard 会优先运行并打印失败输出。
 
 </details>
 
@@ -340,13 +340,13 @@ Comet 通过自动化状态转换确保 agent 执行可靠性：
    - 检查文件存在、状态一致性、阶段转换
    - 验证失败时输出 `[HARD STOP]` 及可操作建议
 
-2. **自动化状态转换** — `comet-guard.sh --apply` 自动更新 `.comet.yaml`
+2. **自动化状态转换** — `comet-guard.js --apply` 自动更新 `.comet.yaml`
    - 所有阶段转换（open → design/build → verify → archive）使用 `guard --apply`
    - 无需手动状态编辑 — 消除写入验证错误
-   - `comet-state.sh` 是 agent 对状态操作的专属接口
-   - Guard 和 archive 脚本内部使用 `comet-state.sh` 进行状态管理
+   - `comet-state.js` 是 agent 对状态操作的专属接口
+   - Guard 和 archive 脚本内部使用 `comet-state.js` 进行状态管理
 
-3. **模式校验** — `comet-yaml-validate.sh` 确保数据完整性
+3. **模式校验** — `comet-yaml-validate.js` 确保数据完整性
    - 校验必填字段和可选字段
    - 校验枚举值（包括 `direct_override`）
    - 校验 `design_doc`、`plan`、`handoff_context` 路径存在，并校验 `handoff_hash` 格式
@@ -364,7 +364,7 @@ Comet 通过自动化状态转换确保 agent 执行可靠性：
    - Guard 检查 `verification_report exists` 和 `branch_status=handled` 作为硬性前提
    - 防止验证或分支处理被跳过时产生虚假的阶段推进
 
-6. **归档自动化** — `comet-archive.sh` 一键处理完整归档流程
+6. **归档自动化** — `comet-archive.js` 一键处理完整归档流程
    - 验证入口状态、同步 delta specs 到 main specs
    - 标注设计文档和计划文档的 frontmatter
    - 将变更移至归档目录并更新 `archived: true`
@@ -379,12 +379,12 @@ your-project/
 ├── .claude/skills/              # 平台技能目录（Comet + OpenSpec + Superpowers）
 │   ├── comet/SKILL.md
 │   │   └── scripts/
-│   │       ├── comet-guard.sh       # 阶段转换守护（--apply 自动更新状态）
-│   │       ├── comet-env.sh         # 脚本发现助手
-│   │       ├── comet-handoff.sh     # 设计交接（OpenSpec → Superpowers 上下文追踪）
-│   │       ├── comet-archive.sh     # 一键归档自动化
-│   │       ├── comet-yaml-validate.sh # 模式校验器
-│   │       └── comet-state.sh       # 统一状态管理（init/set/get/check/scale）
+│   │       ├── comet-guard.js       # 阶段转换守护（--apply 自动更新状态）
+│   │       ├── comet-env.js         # 脚本发现助手
+│   │       ├── comet-handoff.js     # 设计交接（OpenSpec → Superpowers 上下文追踪）
+│   │       ├── comet-archive.js     # 一键归档自动化
+│   │       ├── comet-yaml-validate.js # 模式校验器
+│   │       └── comet-state.js       # 统一状态管理（init/set/get/check/scale）
 │   ├── comet-*/SKILL.md
 │   ├── openspec-*/SKILL.md
 │   └── brainstorming/SKILL.md
diff --git a/README.md b/README.md
index a27f0db4..429e8833 100644
--- a/README.md
+++ b/README.md
@@ -64,7 +64,7 @@ Long-term Skill users know these capabilities can be freely combined, but exactl
 
 - **How to turn document synchronization from "user reminders" into automation** — Comet puts handoff, state updates, validation, and archive sync into scripted flows, reducing repeated prompts like "remember to update the design doc", "remember to sync the spec", and "remember to archive the change".
 
-- **How to design guard conditions that Agents can execute** — Comet does not simply trust the Agent saying "done" at phase exits. Scripts such as `comet-guard.sh`, `comet-yaml-validate.sh`, and `comet-state.sh` check tasks, state fields, verification evidence, and archive conditions before allowing the workflow to advance.
+- **How to design guard conditions that Agents can execute** — Comet does not simply trust the Agent saying "done" at phase exits. Node scripts such as `comet-guard.js`, `comet-yaml-validate.js`, and `comet-state.js` check tasks, state fields, verification evidence, and archive conditions before allowing the workflow to advance.
 
 - **How to distribute and install Skills across platforms** — Comet supports multiple AI coding platforms, project/global installation, Chinese/English Skill choices, and platform-specific directory differences such as Antigravity using different project-level and global paths. It can be a reference for CLI installers and Skill package structure.
 
@@ -239,12 +239,12 @@ After `comet init`, three groups of skills are installed to the selected platfor
 
 | Script                   | Purpose                                                                                               |
 | ------------------------ | ----------------------------------------------------------------------------------------------------- |
-| `comet-env.sh`           | Script discovery helper — exports bundled script paths such as `COMET_GUARD`, `COMET_STATE`, `COMET_HANDOFF`, and `COMET_ARCHIVE` |
-| `comet-guard.sh`         | Phase transition guard — validates exit conditions, `--apply` auto-updates `.comet.yaml`              |
-| `comet-handoff.sh`       | Design handoff — generates deterministic context packages from OpenSpec artifacts with SHA256 tracing |
-| `comet-archive.sh`       | One-command archive — validates state, syncs specs, moves to archive, updates status                  |
-| `comet-yaml-validate.sh` | Schema validator — validates `.comet.yaml` structure and field values                                 |
-| `comet-state.sh`         | Unified state management — init/set/get/check/scale, agents' exclusive YAML interface                 |
+| `comet-env.js`           | Script discovery helper — prints bundled script paths such as `COMET_GUARD`, `COMET_STATE`, `COMET_HANDOFF`, and `COMET_ARCHIVE` as JSON |
+| `comet-guard.js`         | Phase transition guard — validates exit conditions, `--apply` auto-updates `.comet.yaml`              |
+| `comet-handoff.js`       | Design handoff — generates deterministic context packages from OpenSpec artifacts with SHA256 tracing |
+| `comet-archive.js`       | One-command archive — validates state, syncs specs, moves to archive, updates status                  |
+| `comet-yaml-validate.js` | Schema validator — validates `.comet.yaml` structure and field values                                 |
+| `comet-state.js`         | Unified state management — init/set/get/check/scale, agents' exclusive YAML interface                 |
 
 </details>
 
@@ -326,7 +326,7 @@ handoff_context: openspec/changes/<name>/.comet/handoff/design-context.json
 handoff_hash: <sha256>
 ```
 
-In full workflow, `build_mode`, `build_pause`, `isolation`, and `verify_mode` may temporarily be `null`; `build_mode` and `isolation` must be resolved before `build → verify`. `build_pause` records an internal build-phase pause point: `null` means no pause, while `plan-ready` means the plan has been generated and the user paused before choosing isolation and execution mode. It is not an execution mode and must not be written into `build_mode`. `verification_report` stays `null` until verification writes a report, and `verify-pass` requires that report to exist plus `branch_status: handled`. Fields after `archived` in the example are optional or script-derived: `direct_override` is only needed for full-workflow direct builds, project commands may be absent unless configured, and `handoff_context` / `handoff_hash` are recorded by `comet-handoff.sh` before leaving design. Projects can configure `build_command` / `verify_command` in the change or repo root, and guard will run those commands first and print failure output.
+In full workflow, `build_mode`, `build_pause`, `isolation`, and `verify_mode` may temporarily be `null`; `build_mode` and `isolation` must be resolved before `build → verify`. `build_pause` records an internal build-phase pause point: `null` means no pause, while `plan-ready` means the plan has been generated and the user paused before choosing isolation and execution mode. It is not an execution mode and must not be written into `build_mode`. `verification_report` stays `null` until verification writes a report, and `verify-pass` requires that report to exist plus `branch_status: handled`. Fields after `archived` in the example are optional or script-derived: `direct_override` is only needed for full-workflow direct builds, project commands may be absent unless configured, and `handoff_context` / `handoff_hash` are recorded by `comet-handoff.js` before leaving design. Projects can configure `build_command` / `verify_command` in the change or repo root, and guard will run those commands first and print failure output.
 
 </details>
 
@@ -341,13 +341,13 @@ Comet ensures agent execution reliability through automated state transitions:
    - Checks file existence, state consistency, and phase transitions
    - Outputs `[HARD STOP]` with actionable suggestions if validation fails
 
-2. **Automated State Transitions** — `comet-guard.sh --apply` updates `.comet.yaml` automatically
+2. **Automated State Transitions** — `comet-guard.js --apply` updates `.comet.yaml` automatically
    - All phase transitions (open → design/build → verify → archive) use `guard --apply`
    - No manual state editing required — eliminates write-verification errors
-   - `comet-state.sh` is the agents' exclusive interface for state operations
-   - Guard and archive scripts use `comet-state.sh` internally for state management
+   - `comet-state.js` is the agents' exclusive interface for state operations
+   - Guard and archive scripts use `comet-state.js` internally for state management
 
-3. **Schema Validation** — `comet-yaml-validate.sh` ensures data integrity
+3. **Schema Validation** — `comet-yaml-validate.js` ensures data integrity
    - Validates required and optional fields
    - Validates enum values, including `direct_override`
    - Validates `design_doc`, `plan`, and `handoff_context` paths exist, plus `handoff_hash` format
@@ -365,7 +365,7 @@ Comet ensures agent execution reliability through automated state transitions:
    - Guard checks `verification_report exists` and `branch_status=handled` as hard prerequisites
    - Prevents false phase advances when verification or branch handling was skipped
 
-6. **Archive Automation** — `comet-archive.sh` handles the full archive flow in one command
+6. **Archive Automation** — `comet-archive.js` handles the full archive flow in one command
    - Validates entry state, syncs delta specs to main specs
    - Annotates design doc and plan frontmatter
    - Moves change to archive directory and updates `archived: true`
@@ -380,12 +380,12 @@ your-project/
 ├── .claude/skills/              # Platform skills dir (Comet + OpenSpec + Superpowers)
 │   ├── comet/SKILL.md
 │   │   └── scripts/
-│   │       ├── comet-guard.sh       # Phase transition guard (--apply auto-updates state)
-│   │       ├── comet-env.sh         # Script discovery helper
-│   │       ├── comet-handoff.sh     # Design handoff (OpenSpec → Superpowers context tracing)
-│   │       ├── comet-archive.sh     # One-command archive automation
-│   │       ├── comet-yaml-validate.sh # Schema validator
-│   │       └── comet-state.sh       # Unified state management (init/set/get/check/scale)
+│   │       ├── comet-guard.js       # Phase transition guard (--apply auto-updates state)
+│   │       ├── comet-env.js         # Script discovery helper
+│   │       ├── comet-handoff.js     # Design handoff (OpenSpec → Superpowers context tracing)
+│   │       ├── comet-archive.js     # One-command archive automation
+│   │       ├── comet-yaml-validate.js # Schema validator
+│   │       └── comet-state.js       # Unified state management (init/set/get/check/scale)
 │   ├── comet-*/SKILL.md
 │   ├── openspec-*/SKILL.md
 │   └── brainstorming/SKILL.md
diff --git a/assets/manifest.json b/assets/manifest.json
index a606af72..6a8def66 100644
--- a/assets/manifest.json
+++ b/assets/manifest.json
@@ -3,12 +3,13 @@
   "skills": [
     "comet/SKILL.md",
     "comet/reference/dirty-worktree.md",
-    "comet/scripts/comet-env.sh",
-    "comet/scripts/comet-guard.sh",
-    "comet/scripts/comet-state.sh",
-    "comet/scripts/comet-handoff.sh",
-    "comet/scripts/comet-archive.sh",
-    "comet/scripts/comet-yaml-validate.sh",
+    "comet/scripts/comet-lib.js",
+    "comet/scripts/comet-env.js",
+    "comet/scripts/comet-guard.js",
+    "comet/scripts/comet-state.js",
+    "comet/scripts/comet-handoff.js",
+    "comet/scripts/comet-archive.js",
+    "comet/scripts/comet-yaml-validate.js",
     "comet-open/SKILL.md",
     "comet-design/SKILL.md",
     "comet-build/SKILL.md",
diff --git a/assets/skills-zh/comet-archive/SKILL.md b/assets/skills-zh/comet-archive/SKILL.md
index 6c1c5b59..7ee553d0 100644
--- a/assets/skills-zh/comet-archive/SKILL.md
+++ b/assets/skills-zh/comet-archive/SKILL.md
@@ -18,13 +18,17 @@ description: "Comet 阶段 5：归档。用 /comet-archive 调用。同步 delta
 执行入口验证：
 
 ```bash
-COMET_ENV="${COMET_ENV:-$(find . "$HOME"/.*/skills "$HOME/.config" "$HOME/.gemini" -path '*/comet/scripts/comet-env.sh' -type f -print -quit 2>/dev/null)}"
+COMET_ENV="${COMET_ENV:-$(find . "$HOME"/.*/skills "$HOME/.config" "$HOME/.gemini" -path '*/comet/scripts/comet-env.js' -type f -print -quit 2>/dev/null)}"
 if [ -z "$COMET_ENV" ]; then
-  echo "ERROR: comet-env.sh not found. Ensure the comet skill is installed." >&2
+  echo "ERROR: comet-env.js not found. Ensure the comet skill is installed." >&2
   return 1
 fi
-. "$COMET_ENV"
-"$COMET_BASH" "$COMET_STATE" check <name> archive
+COMET_ENV_JSON="$(node "$COMET_ENV")"
+COMET_STATE="$(printf '%s' "$COMET_ENV_JSON" | node -e "let s='';process.stdin.on('data',d=>s+=d).on('end',()=>console.log(JSON.parse(s).COMET_STATE))")"
+COMET_GUARD="$(printf '%s' "$COMET_ENV_JSON" | node -e "let s='';process.stdin.on('data',d=>s+=d).on('end',()=>console.log(JSON.parse(s).COMET_GUARD))")"
+COMET_HANDOFF="$(printf '%s' "$COMET_ENV_JSON" | node -e "let s='';process.stdin.on('data',d=>s+=d).on('end',()=>console.log(JSON.parse(s).COMET_HANDOFF))")"
+COMET_ARCHIVE="$(printf '%s' "$COMET_ENV_JSON" | node -e "let s='';process.stdin.on('data',d=>s+=d).on('end',()=>console.log(JSON.parse(s).COMET_ARCHIVE))")"
+node "$COMET_STATE" check <name> archive
 ```
 
 验证通过后继续 Step 1。验证失败时脚本会输出具体失败原因。
@@ -38,7 +42,7 @@ fi
 运行归档脚本，自动完成以下全部步骤：
 
 ```bash
-"$COMET_BASH" "$COMET_ARCHIVE" "<change-name>"
+node "$COMET_ARCHIVE" "<change-name>"
 ```
 
 脚本自动执行：
@@ -70,7 +74,7 @@ brainstorming → delta spec → 实施 → 验证 → 主 spec 覆盖 → desig
 - 归档目录 `openspec/changes/archive/YYYY-MM-DD-<change-name>/` 存在
 - 归档后的 `.comet.yaml` 中 `archived: true`
 
-归档脚本会把 `openspec/changes/<name>/` 移动到 `openspec/changes/archive/YYYY-MM-DD-<name>/`。归档成功后**不要再对原 change 名运行** `"$COMET_BASH" "$COMET_GUARD" <change-name> archive`，因为原活跃目录已经不存在。归档完整性以脚本退出码和归档目录状态为准。
+归档脚本会把 `openspec/changes/<name>/` 移动到 `openspec/changes/archive/YYYY-MM-DD-<name>/`。归档成功后**不要再对原 change 名运行** `node "$COMET_GUARD" <change-name> archive`，因为原活跃目录已经不存在。归档完整性以脚本退出码和归档目录状态为准。
 
 ## 完成
 
diff --git a/assets/skills-zh/comet-build/SKILL.md b/assets/skills-zh/comet-build/SKILL.md
index ae4772cf..ed41318f 100644
--- a/assets/skills-zh/comet-build/SKILL.md
+++ b/assets/skills-zh/comet-build/SKILL.md
@@ -17,13 +17,17 @@ description: "Comet 阶段 3：计划与构建。用 /comet-build 调用。制
 执行入口验证：
 
 ```bash
-COMET_ENV="${COMET_ENV:-$(find . "$HOME"/.*/skills "$HOME/.config" "$HOME/.gemini" -path '*/comet/scripts/comet-env.sh' -type f -print -quit 2>/dev/null)}"
+COMET_ENV="${COMET_ENV:-$(find . "$HOME"/.*/skills "$HOME/.config" "$HOME/.gemini" -path '*/comet/scripts/comet-env.js' -type f -print -quit 2>/dev/null)}"
 if [ -z "$COMET_ENV" ]; then
-  echo "ERROR: comet-env.sh not found. Ensure the comet skill is installed." >&2
+  echo "ERROR: comet-env.js not found. Ensure the comet skill is installed." >&2
   return 1
 fi
-. "$COMET_ENV"
-"$COMET_BASH" "$COMET_STATE" check <name> build
+COMET_ENV_JSON="$(node "$COMET_ENV")"
+COMET_STATE="$(printf '%s' "$COMET_ENV_JSON" | node -e "let s='';process.stdin.on('data',d=>s+=d).on('end',()=>console.log(JSON.parse(s).COMET_STATE))")"
+COMET_GUARD="$(printf '%s' "$COMET_ENV_JSON" | node -e "let s='';process.stdin.on('data',d=>s+=d).on('end',()=>console.log(JSON.parse(s).COMET_GUARD))")"
+COMET_HANDOFF="$(printf '%s' "$COMET_ENV_JSON" | node -e "let s='';process.stdin.on('data',d=>s+=d).on('end',()=>console.log(JSON.parse(s).COMET_HANDOFF))")"
+COMET_ARCHIVE="$(printf '%s' "$COMET_ENV_JSON" | node -e "let s='';process.stdin.on('data',d=>s+=d).on('end',()=>console.log(JSON.parse(s).COMET_ARCHIVE))")"
+node "$COMET_STATE" check <name> build
 ```
 
 验证通过后继续 Step 1。验证失败时脚本会输出具体失败原因。
@@ -64,7 +68,7 @@ git rev-parse HEAD
 先记录 plan 路径：
 
 ```bash
-"$COMET_BASH" "$COMET_STATE" set <name> plan docs/superpowers/plans/YYYY-MM-DD-feature.md
+node "$COMET_STATE" set <name> plan docs/superpowers/plans/YYYY-MM-DD-feature.md
 ```
 
 无需手动更新 phase，guard 会在退出条件满足后自动流转。
@@ -81,13 +85,13 @@ git rev-parse HEAD
 用户选择继续时：
 
 ```bash
-"$COMET_BASH" "$COMET_STATE" set <name> build_pause null
+node "$COMET_STATE" set <name> build_pause null
 ```
 
 用户选择暂停时：
 
 ```bash
-"$COMET_BASH" "$COMET_STATE" set <name> build_pause plan-ready
+node "$COMET_STATE" set <name> build_pause plan-ready
 ```
 
 设置 `build_pause: plan-ready` 后，当前调用停止。不要选择 `isolation` 或 `build_mode`，不要加载执行技能。
@@ -97,7 +101,7 @@ git rev-parse HEAD
 如果恢复时检测到 `build_pause: plan-ready` 且 `plan` 文件存在，不要重新运行 `writing-plans`。先告知用户当前停在 plan-ready 暂停点；用户确认继续后，设置：
 
 ```bash
-"$COMET_BASH" "$COMET_STATE" set <name> build_pause null
+node "$COMET_STATE" set <name> build_pause null
 ```
 
 然后继续本步骤选择工作区隔离和执行方式。
@@ -132,8 +136,8 @@ git rev-parse HEAD
 用户选择后，更新 `isolation` 和 `build_mode` 字段：
 
 ```bash
-"$COMET_BASH" "$COMET_STATE" set <name> isolation <branch|worktree>
-"$COMET_BASH" "$COMET_STATE" set <name> build_mode <subagent-driven-development|executing-plans|direct>
+node "$COMET_STATE" set <name> isolation <branch|worktree>
+node "$COMET_STATE" set <name> build_mode <subagent-driven-development|executing-plans|direct>
 ```
 
 `isolation` 是脚本级硬约束。full workflow 初始化时可以为 `null`，但只允许存在到本步骤之前。若保持 `null`，`build → verify` 的 guard 和 `comet-state transition build-complete` 都会失败。
@@ -141,8 +145,8 @@ git rev-parse HEAD
 `build_mode` 默认仅 hotfix/tweak preset 使用 `direct`。full workflow 不得默认使用 `direct`。只有用户明确要求跳过计划执行技能，且你已记录显式 override 时，才允许：
 
 ```bash
-"$COMET_BASH" "$COMET_STATE" set <name> direct_override true
-"$COMET_BASH" "$COMET_STATE" set <name> build_mode direct
+node "$COMET_STATE" set <name> direct_override true
+node "$COMET_STATE" set <name> build_mode direct
 ```
 
 没有 `direct_override: true` 时，full workflow 的 `build_mode=direct` 会被 guard 和状态转换同时拦截。
@@ -196,7 +200,7 @@ Language: 使用触发本次工作流的用户请求语言输出。
 Build 是最长阶段，可能跨越大量任务。为支持上下文压缩后断点恢复：
 
 - **每完成一个 task**：立即勾选 tasks.md 并提交代码，确保 `.comet.yaml` 和文件状态持久化
-- **上下文压缩后恢复**：先运行 `"$COMET_BASH" "$COMET_STATE" check <change-name> build --recover`，脚本输出结构化恢复上下文（isolation/build_mode 状态、plan 路径、任务完成进度、恢复动作）。根据 Recovery action 决定下一步。
+- **上下文压缩后恢复**：先运行 `node "$COMET_STATE" check <change-name> build --recover`，脚本输出结构化恢复上下文（isolation/build_mode 状态、plan 路径、任务完成进度、恢复动作）。根据 Recovery action 决定下一步。
 - **用户手动修改恢复**：按 `comet/reference/dirty-worktree.md` 协议处理未提交改动。该协议定义了检查步骤、归因分类和禁令。build 阶段的特殊处理：
   1. 归因后，若 diff 暗示计划或 spec 已变化，按 Step 4「Spec 增量更新」分级处理
 - **长任务拆分**：单任务超过 200 行代码变更时，考虑拆分为多个子任务分别提交
@@ -208,7 +212,7 @@ Build 是最长阶段，可能跨越大量任务。为支持上下文压缩后
 - 已显式运行项目对应的构建/测试命令并通过（不要只依赖 guard 自动猜测）
 - `isolation` 已写为 `branch` 或 `worktree`
 - `build_mode` 已写为 `subagent-driven-development`、`executing-plans` 或带显式 override 的 `direct`
-- **阶段守卫**：运行 `"$COMET_BASH" "$COMET_GUARD" <change-name> build --apply`，全部 PASS 后自动流转到 `phase: verify`
+- **阶段守卫**：运行 `node "$COMET_GUARD" <change-name> build --apply`，全部 PASS 后自动流转到 `phase: verify`
 
 Guard 会优先读取项目配置中的命令：
 
@@ -223,7 +227,7 @@ verify_command: <verify command>
 退出前运行 guard 自动流转：
 
 ```bash
-"$COMET_BASH" "$COMET_GUARD" <change-name> build --apply
+node "$COMET_GUARD" <change-name> build --apply
 ```
 
 状态文件自动更新为 `phase: verify`、`verify_result: pending`。
diff --git a/assets/skills-zh/comet-design/SKILL.md b/assets/skills-zh/comet-design/SKILL.md
index 587ab32b..2e7f55cd 100644
--- a/assets/skills-zh/comet-design/SKILL.md
+++ b/assets/skills-zh/comet-design/SKILL.md
@@ -17,13 +17,17 @@ description: "Comet 阶段 2：深度设计。用 /comet-design 调用。通过
 执行入口验证：
 
 ```bash
-COMET_ENV="${COMET_ENV:-$(find . "$HOME"/.*/skills "$HOME/.config" "$HOME/.gemini" -path '*/comet/scripts/comet-env.sh' -type f -print -quit 2>/dev/null)}"
+COMET_ENV="${COMET_ENV:-$(find . "$HOME"/.*/skills "$HOME/.config" "$HOME/.gemini" -path '*/comet/scripts/comet-env.js' -type f -print -quit 2>/dev/null)}"
 if [ -z "$COMET_ENV" ]; then
-  echo "ERROR: comet-env.sh not found. Ensure the comet skill is installed." >&2
+  echo "ERROR: comet-env.js not found. Ensure the comet skill is installed." >&2
   return 1
 fi
-. "$COMET_ENV"
-"$COMET_BASH" "$COMET_STATE" check <name> design
+COMET_ENV_JSON="$(node "$COMET_ENV")"
+COMET_STATE="$(printf '%s' "$COMET_ENV_JSON" | node -e "let s='';process.stdin.on('data',d=>s+=d).on('end',()=>console.log(JSON.parse(s).COMET_STATE))")"
+COMET_GUARD="$(printf '%s' "$COMET_ENV_JSON" | node -e "let s='';process.stdin.on('data',d=>s+=d).on('end',()=>console.log(JSON.parse(s).COMET_GUARD))")"
+COMET_HANDOFF="$(printf '%s' "$COMET_ENV_JSON" | node -e "let s='';process.stdin.on('data',d=>s+=d).on('end',()=>console.log(JSON.parse(s).COMET_HANDOFF))")"
+COMET_ARCHIVE="$(printf '%s' "$COMET_ENV_JSON" | node -e "let s='';process.stdin.on('data',d=>s+=d).on('end',()=>console.log(JSON.parse(s).COMET_ARCHIVE))")"
+node "$COMET_STATE" check <name> design
 ```
 
 验证通过后继续 Step 1。验证失败时脚本会输出具体失败原因。
@@ -35,7 +39,7 @@ fi
 **必须由脚本生成，不允许 agent 临场手写 summary 代替。**
 
 ```bash
-"$COMET_BASH" "$COMET_HANDOFF" <change-name> design --write
+node "$COMET_HANDOFF" <change-name> design --write
 ```
 
 脚本会生成并记录：
@@ -60,7 +64,7 @@ handoff_hash: <sha256>
 如确实需要全文上下文，可显式运行：
 
 ```bash
-"$COMET_BASH" "$COMET_HANDOFF" <change-name> design --write --full
+node "$COMET_HANDOFF" <change-name> design --write --full
 ```
 
 交接包来源来自 OpenSpec open 阶段产物：
@@ -122,13 +126,13 @@ brainstorming 产出设计方案后，**必须使用 AskUserQuestion 工具暂
 
 ```bash
 # 记录 design_doc 路径
-"$COMET_BASH" "$COMET_STATE" set <name> design_doc docs/superpowers/specs/YYYY-MM-DD-topic-design.md
+node "$COMET_STATE" set <name> design_doc docs/superpowers/specs/YYYY-MM-DD-topic-design.md
 
 # 如有 delta spec 变更，重新生成 handoff（更新 hash）
-"$COMET_BASH" "$COMET_HANDOFF" <change-name> design --write
+node "$COMET_HANDOFF" <change-name> design --write
 
 # 自动流转到下一阶段
-"$COMET_BASH" "$COMET_GUARD" <change-name> design --apply
+node "$COMET_GUARD" <change-name> design --apply
 ```
 
 如果没有 delta spec 变更，跳过 handoff 重新生成步骤。状态文件自动更新，无需手动编辑其他字段。
@@ -142,12 +146,12 @@ brainstorming 产出设计方案后，**必须使用 AskUserQuestion 工具暂
 - `design-context.md` 必须是脚本生成，且包含 source path、mode、sha256 等可追溯标记（由 guard 强制校验）
 - 如有新能力或补充验收场景，OpenSpec delta spec 已创建/更新
 - `design_doc` 已写入 `.comet.yaml`
-- **阶段守卫**：运行 `"$COMET_BASH" "$COMET_GUARD" <change-name> design --apply`，全部 PASS 后自动流转到 `phase: build`
+- **阶段守卫**：运行 `node "$COMET_GUARD" <change-name> design --apply`，全部 PASS 后自动流转到 `phase: build`
 
 退出前必须使用 `--apply`：
 
 ```bash
-"$COMET_BASH" "$COMET_GUARD" <change-name> design --apply
+node "$COMET_GUARD" <change-name> design --apply
 ```
 
 ## 上下文压缩恢复
@@ -155,7 +159,7 @@ brainstorming 产出设计方案后，**必须使用 AskUserQuestion 工具暂
 design 阶段在 brainstorming 过程中可能触发上下文压缩。恢复时先运行：
 
 ```bash
-"$COMET_BASH" "$COMET_STATE" check <change-name> design --recover
+node "$COMET_STATE" check <change-name> design --recover
 ```
 
 脚本输出结构化恢复上下文（阶段、已完成字段、待完成字段、恢复动作）。按 Recovery action 判断下一步。
diff --git a/assets/skills-zh/comet-hotfix/SKILL.md b/assets/skills-zh/comet-hotfix/SKILL.md
index 43235755..51c6678b 100644
--- a/assets/skills-zh/comet-hotfix/SKILL.md
+++ b/assets/skills-zh/comet-hotfix/SKILL.md
@@ -23,12 +23,16 @@ description: "Comet 预设路径：Bug fix / 热修复。跳过 brainstorming，
 开始前先定位 Comet 脚本：
 
 ```bash
-COMET_ENV="${COMET_ENV:-$(find . "$HOME"/.*/skills "$HOME/.config" "$HOME/.gemini" -path '*/comet/scripts/comet-env.sh' -type f -print -quit 2>/dev/null)}"
+COMET_ENV="${COMET_ENV:-$(find . "$HOME"/.*/skills "$HOME/.config" "$HOME/.gemini" -path '*/comet/scripts/comet-env.js' -type f -print -quit 2>/dev/null)}"
 if [ -z "$COMET_ENV" ]; then
-  echo "ERROR: comet-env.sh not found. Ensure the comet skill is installed." >&2
+  echo "ERROR: comet-env.js not found. Ensure the comet skill is installed." >&2
   return 1
 fi
-. "$COMET_ENV"
+COMET_ENV_JSON="$(node "$COMET_ENV")"
+COMET_STATE="$(printf '%s' "$COMET_ENV_JSON" | node -e "let s='';process.stdin.on('data',d=>s+=d).on('end',()=>console.log(JSON.parse(s).COMET_STATE))")"
+COMET_GUARD="$(printf '%s' "$COMET_ENV_JSON" | node -e "let s='';process.stdin.on('data',d=>s+=d).on('end',()=>console.log(JSON.parse(s).COMET_GUARD))")"
+COMET_HANDOFF="$(printf '%s' "$COMET_ENV_JSON" | node -e "let s='';process.stdin.on('data',d=>s+=d).on('end',()=>console.log(JSON.parse(s).COMET_HANDOFF))")"
+COMET_ARCHIVE="$(printf '%s' "$COMET_ENV_JSON" | node -e "let s='';process.stdin.on('data',d=>s+=d).on('end',()=>console.log(JSON.parse(s).COMET_ARCHIVE))")"
 ```
 
 ### 1. 快速开启（preset open）
@@ -54,19 +58,19 @@ Language: 使用触发本次工作流的用户请求语言输出。
 初始化 Comet 状态文件：
 
 ```bash
-"$COMET_BASH" "$COMET_STATE" init <name> hotfix
+node "$COMET_STATE" init <name> hotfix
 ```
 
 初始化后验证状态：
 
 ```bash
-"$COMET_BASH" "$COMET_STATE" check <name> open
+node "$COMET_STATE" check <name> open
 ```
 
 阶段守卫完成 open → build 过渡：
 
 ```bash
-"$COMET_BASH" "$COMET_GUARD" <change-name> open --apply
+node "$COMET_GUARD" <change-name> open --apply
 ```
 
 ### 2. 直接构建（preset build）
@@ -105,7 +109,7 @@ Language: 使用触发本次工作流的用户请求语言输出。
 根因确认消除后，运行阶段守卫完成 build → verify 过渡：
 
 ```bash
-"$COMET_BASH" "$COMET_GUARD" <change-name> build --apply
+node "$COMET_GUARD" <change-name> build --apply
 ```
 
 状态文件自动更新为 `phase: verify`、`verify_result: pending`，然后进入验证。
@@ -162,7 +166,7 @@ Hotfix 流程为 **一次性连续执行**。调用 `/comet-hotfix` 后，agent
 用户确认升级后，**必须先更新 workflow 字段**再进入完整流程：
 
 ```bash
-"$COMET_BASH" "$COMET_STATE" set <name> workflow full
+node "$COMET_STATE" set <name> workflow full
 ```
 
 然后在当前 change 基础上补充 Design Doc：**立即使用 Skill 工具加载 `comet-design` skill**，后续正常走完整流程。若用户不确认升级，停止 hotfix 并报告当前变更已超出 hotfix 适用范围。
@@ -174,4 +178,4 @@ Hotfix 流程为 **一次性连续执行**。调用 `/comet-hotfix` 后，agent
 - Bug 已修复，测试通过
 - change 已归档
 - 如有 spec 变更，已同步到 main spec
-- **阶段守卫**：build → verify 前运行 `"$COMET_BASH" "$COMET_GUARD" <change-name> build --apply`，verify → archive 前按 `/comet-verify` 规则运行 `"$COMET_BASH" "$COMET_GUARD" <change-name> verify --apply`
+- **阶段守卫**：build → verify 前运行 `node "$COMET_GUARD" <change-name> build --apply`，verify → archive 前按 `/comet-verify` 规则运行 `node "$COMET_GUARD" <change-name> verify --apply`
diff --git a/assets/skills-zh/comet-open/SKILL.md b/assets/skills-zh/comet-open/SKILL.md
index d09fbd6b..2f1ad9f3 100644
--- a/assets/skills-zh/comet-open/SKILL.md
+++ b/assets/skills-zh/comet-open/SKILL.md
@@ -53,19 +53,23 @@ openspec/changes/<name>/
 创建 `.comet.yaml` 状态文件：
 
 ```bash
-COMET_ENV="${COMET_ENV:-$(find . "$HOME"/.*/skills "$HOME/.config" "$HOME/.gemini" -path '*/comet/scripts/comet-env.sh' -type f -print -quit 2>/dev/null)}"
+COMET_ENV="${COMET_ENV:-$(find . "$HOME"/.*/skills "$HOME/.config" "$HOME/.gemini" -path '*/comet/scripts/comet-env.js' -type f -print -quit 2>/dev/null)}"
 if [ -z "$COMET_ENV" ]; then
-  echo "ERROR: comet-env.sh not found. Ensure the comet skill is installed." >&2
+  echo "ERROR: comet-env.js not found. Ensure the comet skill is installed." >&2
   return 1
 fi
-. "$COMET_ENV"
+COMET_ENV_JSON="$(node "$COMET_ENV")"
+COMET_STATE="$(printf '%s' "$COMET_ENV_JSON" | node -e "let s='';process.stdin.on('data',d=>s+=d).on('end',()=>console.log(JSON.parse(s).COMET_STATE))")"
+COMET_GUARD="$(printf '%s' "$COMET_ENV_JSON" | node -e "let s='';process.stdin.on('data',d=>s+=d).on('end',()=>console.log(JSON.parse(s).COMET_GUARD))")"
+COMET_HANDOFF="$(printf '%s' "$COMET_ENV_JSON" | node -e "let s='';process.stdin.on('data',d=>s+=d).on('end',()=>console.log(JSON.parse(s).COMET_HANDOFF))")"
+COMET_ARCHIVE="$(printf '%s' "$COMET_ENV_JSON" | node -e "let s='';process.stdin.on('data',d=>s+=d).on('end',()=>console.log(JSON.parse(s).COMET_ARCHIVE))")"
 
 if [ -z "$COMET_STATE" ] || [ -z "$COMET_GUARD" ]; then
   echo "ERROR: Comet scripts not found. Ensure the comet skill is installed." >&2
   return 1
 fi
 
-"$COMET_BASH" "$COMET_STATE" init <name> full
+node "$COMET_STATE" init <name> full
 ```
 
 ### 3. 入口状态验证
@@ -73,7 +77,7 @@ fi
 验证状态机已正确初始化：
 
 ```bash
-"$COMET_BASH" "$COMET_STATE" check <name> open
+node "$COMET_STATE" check <name> open
 ```
 
 验证通过后继续 Step 4。验证失败时脚本会输出具体失败原因。
@@ -110,12 +114,12 @@ AskUserQuestion 必须以单选题形式呈现，包含以下摘要和选项：
 
 - proposal.md、design.md、tasks.md 均已创建且内容完整
 - **用户已确认** proposal、design、tasks 内容符合预期
-- **阶段守卫**：运行 `"$COMET_BASH" "$COMET_GUARD" <change-name> open --apply`，全部 PASS 后自动流转到下一阶段
+- **阶段守卫**：运行 `node "$COMET_GUARD" <change-name> open --apply`，全部 PASS 后自动流转到下一阶段
 
 退出前必须使用 `--apply`，否则 `.comet.yaml` 仍停留在 `phase: open`，下一阶段入口检查会失败。
 
 ```bash
-"$COMET_BASH" "$COMET_GUARD" <change-name> open --apply
+node "$COMET_GUARD" <change-name> open --apply
 ```
 
 完整流程会自动更新为 `phase: design`；hotfix/tweak preset 会自动更新为 `phase: build`。
diff --git a/assets/skills-zh/comet-tweak/SKILL.md b/assets/skills-zh/comet-tweak/SKILL.md
index dd5593b0..15ebbd9a 100644
--- a/assets/skills-zh/comet-tweak/SKILL.md
+++ b/assets/skills-zh/comet-tweak/SKILL.md
@@ -26,12 +26,16 @@ Tweak 是 Comet 五阶段能力的预设工作流，不是独立的平行流程
 开始前先定位 Comet 脚本：
 
 ```bash
-COMET_ENV="${COMET_ENV:-$(find . "$HOME"/.*/skills "$HOME/.config" "$HOME/.gemini" -path '*/comet/scripts/comet-env.sh' -type f -print -quit 2>/dev/null)}"
+COMET_ENV="${COMET_ENV:-$(find . "$HOME"/.*/skills "$HOME/.config" "$HOME/.gemini" -path '*/comet/scripts/comet-env.js' -type f -print -quit 2>/dev/null)}"
 if [ -z "$COMET_ENV" ]; then
-  echo "ERROR: comet-env.sh not found. Ensure the comet skill is installed." >&2
+  echo "ERROR: comet-env.js not found. Ensure the comet skill is installed." >&2
   return 1
 fi
-. "$COMET_ENV"
+COMET_ENV_JSON="$(node "$COMET_ENV")"
+COMET_STATE="$(printf '%s' "$COMET_ENV_JSON" | node -e "let s='';process.stdin.on('data',d=>s+=d).on('end',()=>console.log(JSON.parse(s).COMET_STATE))")"
+COMET_GUARD="$(printf '%s' "$COMET_ENV_JSON" | node -e "let s='';process.stdin.on('data',d=>s+=d).on('end',()=>console.log(JSON.parse(s).COMET_GUARD))")"
+COMET_HANDOFF="$(printf '%s' "$COMET_ENV_JSON" | node -e "let s='';process.stdin.on('data',d=>s+=d).on('end',()=>console.log(JSON.parse(s).COMET_HANDOFF))")"
+COMET_ARCHIVE="$(printf '%s' "$COMET_ENV_JSON" | node -e "let s='';process.stdin.on('data',d=>s+=d).on('end',()=>console.log(JSON.parse(s).COMET_ARCHIVE))")"
 ```
 
 ### 1. 快速开启（preset open）
@@ -57,19 +61,19 @@ Language: 使用触发本次工作流的用户请求语言输出。
 初始化 Comet 状态文件：
 
 ```bash
-"$COMET_BASH" "$COMET_STATE" init <name> tweak
+node "$COMET_STATE" init <name> tweak
 ```
 
 初始化后验证状态：
 
 ```bash
-"$COMET_BASH" "$COMET_STATE" check <name> open
+node "$COMET_STATE" check <name> open
 ```
 
 阶段守卫完成 open → build 过渡：
 
 ```bash
-"$COMET_BASH" "$COMET_GUARD" <change-name> open --apply
+node "$COMET_GUARD" <change-name> open --apply
 ```
 
 ### 2. 轻量构建（preset build）
@@ -91,7 +95,7 @@ Language: 使用触发本次工作流的用户请求语言输出。
 4. 运行阶段守卫完成 build → verify 过渡：
 
 ```bash
-"$COMET_BASH" "$COMET_GUARD" <change-name> build --apply
+node "$COMET_GUARD" <change-name> build --apply
 ```
 
 状态文件自动更新为 `phase: verify`、`verify_result: pending`，然后进入验证。
@@ -147,7 +151,7 @@ Tweak 流程为 **一次性连续执行**。调用 `/comet-tweak` 后，agent 
 用户确认升级后，**必须先更新 workflow 字段**再进入完整流程：
 
 ```bash
-"$COMET_BASH" "$COMET_STATE" set <name> workflow full
+node "$COMET_STATE" set <name> workflow full
 ```
 
 然后在当前 change 基础上补充 Design Doc：**立即使用 Skill 工具加载 `comet-design` skill**，后续正常走完整流程。若用户不确认升级，停止 tweak 并报告当前变更已超出 tweak 适用范围。
@@ -159,4 +163,4 @@ Tweak 流程为 **一次性连续执行**。调用 `/comet-tweak` 后，agent 
 - 小改动已完成，测试通过
 - change 已归档
 - 未新增 capability、架构调整或接口变化
-- **阶段守卫**：build → verify 前运行 `"$COMET_BASH" "$COMET_GUARD" <change-name> build --apply`，verify → archive 前按 `/comet-verify` 规则运行 `"$COMET_BASH" "$COMET_GUARD" <change-name> verify --apply`
+- **阶段守卫**：build → verify 前运行 `node "$COMET_GUARD" <change-name> build --apply`，verify → archive 前按 `/comet-verify` 规则运行 `node "$COMET_GUARD" <change-name> verify --apply`
diff --git a/assets/skills-zh/comet-verify/SKILL.md b/assets/skills-zh/comet-verify/SKILL.md
index 06b54fee..504d03bd 100644
--- a/assets/skills-zh/comet-verify/SKILL.md
+++ b/assets/skills-zh/comet-verify/SKILL.md
@@ -17,13 +17,17 @@ description: "Comet 阶段 4：验证与收尾。用 /comet-verify 调用。验
 执行入口验证：
 
 ```bash
-COMET_ENV="${COMET_ENV:-$(find . "$HOME"/.*/skills "$HOME/.config" "$HOME/.gemini" -path '*/comet/scripts/comet-env.sh' -type f -print -quit 2>/dev/null)}"
+COMET_ENV="${COMET_ENV:-$(find . "$HOME"/.*/skills "$HOME/.config" "$HOME/.gemini" -path '*/comet/scripts/comet-env.js' -type f -print -quit 2>/dev/null)}"
 if [ -z "$COMET_ENV" ]; then
-  echo "ERROR: comet-env.sh not found. Ensure the comet skill is installed." >&2
+  echo "ERROR: comet-env.js not found. Ensure the comet skill is installed." >&2
   return 1
 fi
-. "$COMET_ENV"
-"$COMET_BASH" "$COMET_STATE" check <change-name> verify
+COMET_ENV_JSON="$(node "$COMET_ENV")"
+COMET_STATE="$(printf '%s' "$COMET_ENV_JSON" | node -e "let s='';process.stdin.on('data',d=>s+=d).on('end',()=>console.log(JSON.parse(s).COMET_STATE))")"
+COMET_GUARD="$(printf '%s' "$COMET_ENV_JSON" | node -e "let s='';process.stdin.on('data',d=>s+=d).on('end',()=>console.log(JSON.parse(s).COMET_GUARD))")"
+COMET_HANDOFF="$(printf '%s' "$COMET_ENV_JSON" | node -e "let s='';process.stdin.on('data',d=>s+=d).on('end',()=>console.log(JSON.parse(s).COMET_HANDOFF))")"
+COMET_ARCHIVE="$(printf '%s' "$COMET_ENV_JSON" | node -e "let s='';process.stdin.on('data',d=>s+=d).on('end',()=>console.log(JSON.parse(s).COMET_ARCHIVE))")"
+node "$COMET_STATE" check <change-name> verify
 ```
 
 验证通过后继续 Step 1。验证失败时脚本会输出具体失败原因。
@@ -39,7 +43,7 @@ fi
 执行规模评估：
 
 ```bash
-"$COMET_BASH" "$COMET_STATE" scale <change-name>
+node "$COMET_STATE" scale <change-name>
 ```
 
 脚本自动统计任务数、增量规格数、变更文件数，判断使用 light 或 full 验证模式，并设置 verify_mode 字段。
@@ -54,13 +58,13 @@ fi
 
 ```bash
 # 仅在用户确认修复后执行
-"$COMET_BASH" "$COMET_STATE" transition <change-name> verify-fail
+node "$COMET_STATE" transition <change-name> verify-fail
 ```
 
 注意：如果 build 阶段每个任务都已提交，脚本基于工作区 diff 的文件数可能低估改动规模。此时必须读取 plan 文件头的 `base-ref` 并用提交区间复核：
 
 ```bash
-PLAN=$("$COMET_BASH" "$COMET_STATE" get <change-name> plan)
+PLAN=$(node "$COMET_STATE" get <change-name> plan)
 BASE_REF=$(grep '^base-ref:' "$PLAN" 2>/dev/null | head -1 | sed 's/^base-ref: *//')
 git diff --stat "$BASE_REF"...HEAD
 ```
@@ -68,12 +72,12 @@ git diff --stat "$BASE_REF"...HEAD
 若提交区间显示改动超过轻量阈值（> 4 个文件、跨模块协调、或 delta spec 超过 1 个 capability），手动设置为完整验证：
 
 ```bash
-"$COMET_BASH" "$COMET_STATE" set <change-name> verify_mode full
+node "$COMET_STATE" set <change-name> verify_mode full
 ```
 
 ### 1b. 验证失败决策（阻塞点）
 
-验证不通过时**必须使用 AskUserQuestion 工具暂停并等待用户决定修复或接受偏差**。不得自动运行 `"$COMET_BASH" "$COMET_STATE" transition <change-name> verify-fail`，也不得自动调用 `/comet-build`。禁止仅输出文字提示后继续执行。
+验证不通过时**必须使用 AskUserQuestion 工具暂停并等待用户决定修复或接受偏差**。不得自动运行 `node "$COMET_STATE" transition <change-name> verify-fail`，也不得自动调用 `/comet-build`。禁止仅输出文字提示后继续执行。
 
 暂停时必须列出：
 - 失败项
@@ -83,7 +87,7 @@ git diff --stat "$BASE_REF"...HEAD
 **不确定性原则**：无法确定严重程度时，降级处理（SUGGESTION > WARNING > CRITICAL）。仅对构建失败、测试失败、安全问题使用 CRITICAL；模糊或不确定的问题标为 WARNING 或 SUGGESTION。
 
 用户选择后按以下方式继续：
-- **全部修复**：运行 `"$COMET_BASH" "$COMET_STATE" transition <change-name> verify-fail`，然后调用 `/comet-build` 修复
+- **全部修复**：运行 `node "$COMET_STATE" transition <change-name> verify-fail`，然后调用 `/comet-build` 修复
 - **逐项处理**：CRITICAL 失败项必须修复；非 CRITICAL 失败项可选择接受偏差，但必须在验证报告中记录接受原因和影响范围。若存在任何 CRITICAL 失败项，不允许跳过修复直接全部接受
 
 ### 2a. 轻量验证（小改动）
@@ -102,7 +106,7 @@ git diff --stat "$BASE_REF"...HEAD
 
 ```bash
 # 仅在用户确认修复后执行
-"$COMET_BASH" "$COMET_STATE" transition <change-name> verify-fail
+node "$COMET_STATE" transition <change-name> verify-fail
 ```
 
 **报告格式**：简表列出 5 项检查结果 + PASS/FAIL。
@@ -132,13 +136,13 @@ git diff --stat "$BASE_REF"...HEAD
 
 ```bash
 # 仅在用户确认修复后执行
-"$COMET_BASH" "$COMET_STATE" transition <change-name> verify-fail
+node "$COMET_STATE" transition <change-name> verify-fail
 ```
 
 **Spec 漂移处理**（用户决策点）：
 - 若检查项 6 发现矛盾（delta spec 有内容但 design doc 未体现），**必须使用 AskUserQuestion 工具以单选题形式暂停并等待用户选择处理方式**，不得自动选择。选项：
   - 选项 A：在 design doc 追加 "Implementation Divergence" 节记录偏差原因。选项 A 属于 verify 阶段允许产物；写入后不得因该 design doc 变更再次触发 Step 1b dirty-worktree 决策
-  - 选项 B：用户选择 B 后，运行 `"$COMET_BASH" "$COMET_STATE" transition <change-name> verify-fail`，然后调用 `/comet-build`；由 `/comet-build` 的 Spec 增量更新规则加载 Superpowers `brainstorming` 更新 Design Doc + delta spec
+  - 选项 B：用户选择 B 后，运行 `node "$COMET_STATE" transition <change-name> verify-fail`，然后调用 `/comet-build`；由 `/comet-build` 的 Spec 增量更新规则加载 Superpowers `brainstorming` 更新 Design Doc + delta spec
   - 选项 C：确认偏差可接受，继续验证（归档时 design doc 将标记为 `superseded-by-main-spec`）
 
 ### 3. 收尾（Superpowers）
@@ -168,8 +172,8 @@ mkdir -p docs/superpowers/reports
 # 将本次验证结论写入报告文件，例如：
 # docs/superpowers/reports/YYYY-MM-DD-<change-name>-verify.md
 
-"$COMET_BASH" "$COMET_STATE" set <change-name> verification_report docs/superpowers/reports/YYYY-MM-DD-<change-name>-verify.md
-"$COMET_BASH" "$COMET_STATE" set <change-name> branch_status handled
+node "$COMET_STATE" set <change-name> verification_report docs/superpowers/reports/YYYY-MM-DD-<change-name>-verify.md
+node "$COMET_STATE" set <change-name> branch_status handled
 ```
 
 ## 退出条件
@@ -178,12 +182,12 @@ mkdir -p docs/superpowers/reports
 - 分支已处理
 - `.comet.yaml` 中 `verification_report` 指向已存在的验证报告文件
 - `.comet.yaml` 中 `branch_status: handled`
-- **阶段守卫**：运行 `"$COMET_BASH" "$COMET_GUARD" <change-name> verify --apply`，全部 PASS 后通过 `comet-state transition verify-pass` 自动流转到 `phase: archive`
+- **阶段守卫**：运行 `node "$COMET_GUARD" <change-name> verify --apply`，全部 PASS 后通过 `comet-state transition verify-pass` 自动流转到 `phase: archive`
 
 验证和分支处理均完成后，运行 guard 自动流转：
 
 ```bash
-"$COMET_BASH" "$COMET_GUARD" <change-name> verify --apply
+node "$COMET_GUARD" <change-name> verify --apply
 ```
 
 状态文件自动更新为 `phase: archive`、`verify_result: pass`、`verified_at: YYYY-MM-DD`。
@@ -193,7 +197,7 @@ mkdir -p docs/superpowers/reports
 Verify 阶段可能触发上下文压缩。恢复时先运行：
 
 ```bash
-"$COMET_BASH" "$COMET_STATE" check <change-name> verify --recover
+node "$COMET_STATE" check <change-name> verify --recover
 ```
 
 脚本输出结构化恢复上下文（phase、验证状态、分支状态、恢复动作），根据输出的 Recovery action 决定下一步。
diff --git a/assets/skills-zh/comet/SKILL.md b/assets/skills-zh/comet/SKILL.md
index b8008b06..34cc777a 100644
--- a/assets/skills-zh/comet/SKILL.md
+++ b/assets/skills-zh/comet/SKILL.md
@@ -67,8 +67,8 @@ agent 做决策只需读本节，参考附录按需查阅。
   - 若 `build_pause: plan-ready` 但 plan 文件缺失，回到 `/comet-build` 处理状态损坏或重新生成 plan
   - 若 `build_mode` 或 `isolation` 未设置，回到 `/comet-build` 对应步骤补充后再执行
   - 若均已设置，读取 tasks.md 的下一个未勾选任务继续
-- 若 `phase: verify` 且 `verify_result: fail`，进入验证失败决策阻塞点：暂停并询问用户修复或接受偏差；用户选择修复后才运行 `"$COMET_BASH" "$COMET_STATE" transition <name> verify-fail` 并调用 `/comet-build`
-- 若 `phase: open` 但 proposal/design/tasks 已完整，先运行 `"$COMET_BASH" "$COMET_GUARD" <change-name> open --apply` 修正状态，再继续判定
+- 若 `phase: verify` 且 `verify_result: fail`，进入验证失败决策阻塞点：暂停并询问用户修复或接受偏差；用户选择修复后才运行 `node "$COMET_STATE" transition <name> verify-fail` 并调用 `/comet-build`
+- 若 `phase: open` 但 proposal/design/tasks 已完整，先运行 `node "$COMET_GUARD" <change-name> open --apply` 修正状态，再继续判定
 - 若 `phase: archive`，只允许调用 `/comet-archive`；归档成功后 change 会移动到 archive 目录，不再对原活跃目录运行 guard
 
 **Step 2: 阶段判定**（按顺序，命中即停）
@@ -105,7 +105,7 @@ agent 做决策只需读本节，参考附录按需查阅。
 |------|---------|
 | `openspec list --json` 失败 | 检查 openspec 是否已安装，提示 `openspec init` |
 | 子 skill 不可用 | 停止流程，提示安装或启用对应 skill |
-| `.comet.yaml` 格式异常或缺失 | 以文件状态为准，用 `"$COMET_BASH" "$COMET_STATE" set` 修正后继续 |
+| `.comet.yaml` 格式异常或缺失 | 以文件状态为准，用 `node "$COMET_STATE" set` 修正后继续 |
 | 构建/测试失败 | 返回 build 阶段修复，不进入 verify |
 | change 目录结构不完整 | 按 `comet-open` 产物要求补齐 |
 
@@ -226,24 +226,28 @@ archived: false
 - `build → verify` 前，`build_mode` 必须已选择
 - `build_mode: direct` 默认只允许 `hotfix` / `tweak`；full workflow 需要 `direct_override: true`
 - `build_pause` 不是执行方式，不得写入 `build_mode`
-- 这些约束同时存在于 `comet-guard.sh build --apply` 和 `comet-state.sh transition <name> build-complete`
+- 这些约束同时存在于 `comet-guard.js build --apply` 和 `comet-state.js transition <name> build-complete`
 
 ### 脚本定位
 
 Comet 脚本随 skill 包分发在 `comet/scripts/` 下。**不硬编码路径** — 定位一次，缓存到环境变量：
 
 ```bash
-COMET_ENV="${COMET_ENV:-$(find . "$HOME"/.*/skills "$HOME/.config" "$HOME/.gemini" -path '*/comet/scripts/comet-env.sh' -type f -print -quit 2>/dev/null)}"
+COMET_ENV="${COMET_ENV:-$(find . "$HOME"/.*/skills "$HOME/.config" "$HOME/.gemini" -path '*/comet/scripts/comet-env.js' -type f -print -quit 2>/dev/null)}"
 if [ -z "$COMET_ENV" ]; then
-  echo "ERROR: comet-env.sh not found. Ensure the comet skill is installed." >&2
+  echo "ERROR: comet-env.js not found. Ensure the comet skill is installed." >&2
   return 1
 fi
-. "$COMET_ENV"
+COMET_ENV_JSON="$(node "$COMET_ENV")"
+COMET_STATE="$(printf '%s' "$COMET_ENV_JSON" | node -e "let s='';process.stdin.on('data',d=>s+=d).on('end',()=>console.log(JSON.parse(s).COMET_STATE))")"
+COMET_GUARD="$(printf '%s' "$COMET_ENV_JSON" | node -e "let s='';process.stdin.on('data',d=>s+=d).on('end',()=>console.log(JSON.parse(s).COMET_GUARD))")"
+COMET_HANDOFF="$(printf '%s' "$COMET_ENV_JSON" | node -e "let s='';process.stdin.on('data',d=>s+=d).on('end',()=>console.log(JSON.parse(s).COMET_HANDOFF))")"
+COMET_ARCHIVE="$(printf '%s' "$COMET_ENV_JSON" | node -e "let s='';process.stdin.on('data',d=>s+=d).on('end',()=>console.log(JSON.parse(s).COMET_ARCHIVE))")"
 
 # 脚本定位失败时停止流程
 if [ -z "$COMET_GUARD" ] || [ -z "$COMET_STATE" ] || [ -z "$COMET_HANDOFF" ] || [ -z "$COMET_ARCHIVE" ]; then
   echo "ERROR: Comet scripts not found. Ensure the comet skill is installed." >&2
-  echo "Expected path pattern: */comet/scripts/comet-*.sh under project or platform skill directories" >&2
+  echo "Expected path pattern: */comet/scripts/comet-*.js under project or platform skill directories" >&2
   return 1
 fi
 ```
@@ -251,24 +255,24 @@ fi
 **自动状态更新**：guard 支持 `--apply` 参数，验证通过后自动更新 `.comet.yaml` 状态字段：
 
 ```bash
-"$COMET_BASH" "$COMET_GUARD" <change-name> <phase> --apply
+node "$COMET_GUARD" <change-name> <phase> --apply
 ```
 
 `--apply` 内部委托给 `comet-state transition`。需要直接表达状态事件时使用：
 
 ```bash
-"$COMET_BASH" "$COMET_STATE" transition <change-name> open-complete
-"$COMET_BASH" "$COMET_STATE" transition <change-name> design-complete
-"$COMET_BASH" "$COMET_STATE" transition <change-name> build-complete
-"$COMET_BASH" "$COMET_STATE" transition <change-name> verify-pass
-"$COMET_BASH" "$COMET_STATE" transition <change-name> verify-fail
-"$COMET_BASH" "$COMET_STATE" transition <archive-name> archived
+node "$COMET_STATE" transition <change-name> open-complete
+node "$COMET_STATE" transition <change-name> design-complete
+node "$COMET_STATE" transition <change-name> build-complete
+node "$COMET_STATE" transition <change-name> verify-pass
+node "$COMET_STATE" transition <change-name> verify-fail
+node "$COMET_STATE" transition <archive-name> archived
 ```
 
 **归档脚本**：一键完成归档全部步骤：
 
 ```bash
-"$COMET_BASH" "$COMET_ARCHIVE" <change-name>
+node "$COMET_ARCHIVE" <change-name>
 ```
 
 加载 comet 后，agent 应执行以上变量赋值一次，后续全程复用 `$COMET_GUARD`、`$COMET_STATE`、`$COMET_HANDOFF`、`$COMET_ARCHIVE`。
@@ -299,7 +303,7 @@ docs/superpowers/                      # Superpowers — HOW
 
 1. **brainstorming 不可跳过** — 每次变更必须经过深度设计（hotfix 和 tweak 除外）
 2. **delta spec 是活文档** — 阶段 3 期间可自由修改，归档时同步
-3. **交接包由脚本生成** — OpenSpec → Superpowers 的上下文必须通过 `comet-handoff.sh` 生成 compact 可追溯摘录（必要时 `--full`），并由 guard 校验 source/hash/mode
+3. **交接包由脚本生成** — OpenSpec → Superpowers 的上下文必须通过 `comet-handoff.js` 生成 compact 可追溯摘录（必要时 `--full`），并由 guard 校验 source/hash/mode
 4. **保持 tasks.md 同步** — 完成一个勾一个
 5. **频繁提交** — 每个任务一次提交，message 体现设计意图
 6. **先验证再归档** — `/comet-verify` 通过后才执行 `/comet-archive`
diff --git a/assets/skills/comet-archive/SKILL.md b/assets/skills/comet-archive/SKILL.md
index eb96e2b6..45f26560 100644
--- a/assets/skills/comet-archive/SKILL.md
+++ b/assets/skills/comet-archive/SKILL.md
@@ -18,13 +18,17 @@ description: "Comet Phase 5: Archive. Invoke with /comet-archive. Sync delta spe
 Execute entry verification:
 
 ```bash
-COMET_ENV="${COMET_ENV:-$(find . "$HOME"/.*/skills "$HOME/.config" "$HOME/.gemini" -path '*/comet/scripts/comet-env.sh' -type f -print -quit 2>/dev/null)}"
+COMET_ENV="${COMET_ENV:-$(find . "$HOME"/.*/skills "$HOME/.config" "$HOME/.gemini" -path '*/comet/scripts/comet-env.js' -type f -print -quit 2>/dev/null)}"
 if [ -z "$COMET_ENV" ]; then
-  echo "ERROR: comet-env.sh not found. Ensure the comet skill is installed." >&2
+  echo "ERROR: comet-env.js not found. Ensure the comet skill is installed." >&2
   return 1
 fi
-. "$COMET_ENV"
-"$COMET_BASH" "$COMET_STATE" check <name> archive
+COMET_ENV_JSON="$(node "$COMET_ENV")"
+COMET_STATE="$(printf '%s' "$COMET_ENV_JSON" | node -e "let s='';process.stdin.on('data',d=>s+=d).on('end',()=>console.log(JSON.parse(s).COMET_STATE))")"
+COMET_GUARD="$(printf '%s' "$COMET_ENV_JSON" | node -e "let s='';process.stdin.on('data',d=>s+=d).on('end',()=>console.log(JSON.parse(s).COMET_GUARD))")"
+COMET_HANDOFF="$(printf '%s' "$COMET_ENV_JSON" | node -e "let s='';process.stdin.on('data',d=>s+=d).on('end',()=>console.log(JSON.parse(s).COMET_HANDOFF))")"
+COMET_ARCHIVE="$(printf '%s' "$COMET_ENV_JSON" | node -e "let s='';process.stdin.on('data',d=>s+=d).on('end',()=>console.log(JSON.parse(s).COMET_ARCHIVE))")"
+node "$COMET_STATE" check <name> archive
 ```
 
 Proceed to Step 1 after verification passes. The script outputs specific failure reasons when verification fails.
@@ -38,7 +42,7 @@ Archive summaries and lifecycle closure notes must use the language of the user
 Run the archive script to automatically complete all steps:
 
 ```bash
-"$COMET_BASH" "$COMET_ARCHIVE" "<change-name>"
+node "$COMET_ARCHIVE" "<change-name>"
 ```
 
 The script automatically executes:
@@ -70,7 +74,7 @@ brainstorming → delta spec → implementation → verification → main spec o
 - Archive directory `openspec/changes/archive/YYYY-MM-DD-<change-name>/` exists
 - Archived `.comet.yaml` contains `archived: true`
 
-The archive script moves `openspec/changes/<name>/` to `openspec/changes/archive/YYYY-MM-DD-<name>/`. After successful archive, **do not run** `"$COMET_BASH" "$COMET_GUARD" <change-name> archive` against the old active change name; the active directory no longer exists. Archive completeness is determined by script exit code and archived directory state.
+The archive script moves `openspec/changes/<name>/` to `openspec/changes/archive/YYYY-MM-DD-<name>/`. After successful archive, **do not run** `node "$COMET_GUARD" <change-name> archive` against the old active change name; the active directory no longer exists. Archive completeness is determined by script exit code and archived directory state.
 
 ## Complete
 
diff --git a/assets/skills/comet-build/SKILL.md b/assets/skills/comet-build/SKILL.md
index 81160708..3e7c2418 100644
--- a/assets/skills/comet-build/SKILL.md
+++ b/assets/skills/comet-build/SKILL.md
@@ -17,13 +17,17 @@ description: "Comet Phase 3: Plan and Build. Invoke with /comet-build. Create pl
 Execute entry verification:
 
 ```bash
-COMET_ENV="${COMET_ENV:-$(find . "$HOME"/.*/skills "$HOME/.config" "$HOME/.gemini" -path '*/comet/scripts/comet-env.sh' -type f -print -quit 2>/dev/null)}"
+COMET_ENV="${COMET_ENV:-$(find . "$HOME"/.*/skills "$HOME/.config" "$HOME/.gemini" -path '*/comet/scripts/comet-env.js' -type f -print -quit 2>/dev/null)}"
 if [ -z "$COMET_ENV" ]; then
-  echo "ERROR: comet-env.sh not found. Ensure the comet skill is installed." >&2
+  echo "ERROR: comet-env.js not found. Ensure the comet skill is installed." >&2
   return 1
 fi
-. "$COMET_ENV"
-"$COMET_BASH" "$COMET_STATE" check <name> build
+COMET_ENV_JSON="$(node "$COMET_ENV")"
+COMET_STATE="$(printf '%s' "$COMET_ENV_JSON" | node -e "let s='';process.stdin.on('data',d=>s+=d).on('end',()=>console.log(JSON.parse(s).COMET_STATE))")"
+COMET_GUARD="$(printf '%s' "$COMET_ENV_JSON" | node -e "let s='';process.stdin.on('data',d=>s+=d).on('end',()=>console.log(JSON.parse(s).COMET_GUARD))")"
+COMET_HANDOFF="$(printf '%s' "$COMET_ENV_JSON" | node -e "let s='';process.stdin.on('data',d=>s+=d).on('end',()=>console.log(JSON.parse(s).COMET_HANDOFF))")"
+COMET_ARCHIVE="$(printf '%s' "$COMET_ENV_JSON" | node -e "let s='';process.stdin.on('data',d=>s+=d).on('end',()=>console.log(JSON.parse(s).COMET_ARCHIVE))")"
+node "$COMET_STATE" check <name> build
 ```
 
 Proceed to Step 1 after verification passes. The script outputs specific failure reasons when verification fails.
@@ -64,7 +68,7 @@ git rev-parse HEAD
 Record plan path:
 
 ```bash
-"$COMET_BASH" "$COMET_STATE" set <name> plan docs/superpowers/plans/YYYY-MM-DD-feature.md
+node "$COMET_STATE" set <name> plan docs/superpowers/plans/YYYY-MM-DD-feature.md
 ```
 
 No manual phase update needed — guard auto-transitions when exit conditions are met.
@@ -81,13 +85,13 @@ This is a user decision point. **Must use the AskUserQuestion tool to pause and
 When the user chooses to continue:
 
 ```bash
-"$COMET_BASH" "$COMET_STATE" set <name> build_pause null
+node "$COMET_STATE" set <name> build_pause null
 ```
 
 When the user chooses to pause:
 
 ```bash
-"$COMET_BASH" "$COMET_STATE" set <name> build_pause plan-ready
+node "$COMET_STATE" set <name> build_pause plan-ready
 ```
 
 After setting `build_pause: plan-ready`, stop the current invocation. Do not choose `isolation` or `build_mode`, and do not load an execution skill.
@@ -97,7 +101,7 @@ After setting `build_pause: plan-ready`, stop the current invocation. Do not cho
 If resuming with `build_pause: plan-ready` and the `plan` file exists, do not rerun `writing-plans`. First tell the user the workflow is stopped at the plan-ready pause point; after the user confirms continuing, set:
 
 ```bash
-"$COMET_BASH" "$COMET_STATE" set <name> build_pause null
+node "$COMET_STATE" set <name> build_pause null
 ```
 
 Then continue this step to choose workspace isolation and execution method.
@@ -132,8 +136,8 @@ This is a user decision point. **Must use the AskUserQuestion tool to pause and
 After user selection, update `isolation` and `build_mode` fields:
 
 ```bash
-"$COMET_BASH" "$COMET_STATE" set <name> isolation <branch|worktree>
-"$COMET_BASH" "$COMET_STATE" set <name> build_mode <subagent-driven-development|executing-plans|direct>
+node "$COMET_STATE" set <name> isolation <branch|worktree>
+node "$COMET_STATE" set <name> build_mode <subagent-driven-development|executing-plans|direct>
 ```
 
 `isolation` is a script-enforced hard constraint. Full workflow init may temporarily leave it as `null`, but only before this step. If it remains `null`, both the `build → verify` guard and `comet-state transition build-complete` will fail.
@@ -141,8 +145,8 @@ After user selection, update `isolation` and `build_mode` fields:
 `build_mode` defaults to `direct` only for hotfix/tweak presets. Full workflow must not default to `direct`. Use it only when the user explicitly asks to bypass the plan execution skills and you record an explicit override:
 
 ```bash
-"$COMET_BASH" "$COMET_STATE" set <name> direct_override true
-"$COMET_BASH" "$COMET_STATE" set <name> build_mode direct
+node "$COMET_STATE" set <name> direct_override true
+node "$COMET_STATE" set <name> build_mode direct
 ```
 
 Without `direct_override: true`, `build_mode=direct` in full workflow is blocked by both guard and state transition.
@@ -196,7 +200,7 @@ When creating an independent change, must invoke `/comet-open`, not `/opsx:new`
 Build is the longest phase and may span many tasks. To support resume after context compaction:
 
 - **After each task**: immediately check off tasks.md and commit code so `.comet.yaml` and file state are durable
-- **After context compaction**: first run `"$COMET_BASH" "$COMET_STATE" check <change-name> build --recover` — the script outputs structured recovery context (isolation/build_mode status, plan path, task progress, recovery action). Follow the Recovery action to determine next step.
+- **After context compaction**: first run `node "$COMET_STATE" check <change-name> build --recover` — the script outputs structured recovery context (isolation/build_mode status, plan path, task progress, recovery action). Follow the Recovery action to determine next step.
 - **User manual-change resume**: handle uncommitted changes through `comet/reference/dirty-worktree.md`. That protocol defines checks, attribution, and prohibitions. Build-specific handling:
   1. After attribution, if the diff implies plan or spec changes, handle it through Step 4 "Spec Incremental Updates"
 - **Long task split**: if a single task exceeds 200 lines of code changes, consider splitting it into multiple subtasks and commits
@@ -208,7 +212,7 @@ Build is the longest phase and may span many tasks. To support resume after cont
 - Project-specific build/tests explicitly run and pass; do not rely only on guard auto-detection
 - `isolation` has been written as `branch` or `worktree`
 - `build_mode` has been written as `subagent-driven-development`, `executing-plans`, or `direct` with explicit override
-- **Phase guard**: Run `"$COMET_BASH" "$COMET_GUARD" <change-name> build --apply`; after all PASS, state advances to `phase: verify`
+- **Phase guard**: Run `node "$COMET_GUARD" <change-name> build --apply`; after all PASS, state advances to `phase: verify`
 
 Guard reads project command configuration first:
 
@@ -223,7 +227,7 @@ Only when no command is configured does guard fall back to `npm run build`, Mave
 Before exit, run guard to auto-transition:
 
 ```bash
-"$COMET_BASH" "$COMET_GUARD" <change-name> build --apply
+node "$COMET_GUARD" <change-name> build --apply
 ```
 
 State file is automatically updated to `phase: verify`, `verify_result: pending`.
diff --git a/assets/skills/comet-design/SKILL.md b/assets/skills/comet-design/SKILL.md
index ff802f4a..5e2c1678 100644
--- a/assets/skills/comet-design/SKILL.md
+++ b/assets/skills/comet-design/SKILL.md
@@ -17,13 +17,17 @@ description: "Comet Phase 2: Deep Design. Invoke with /comet-design. Produce Des
 Execute entry verification:
 
 ```bash
-COMET_ENV="${COMET_ENV:-$(find . "$HOME"/.*/skills "$HOME/.config" "$HOME/.gemini" -path '*/comet/scripts/comet-env.sh' -type f -print -quit 2>/dev/null)}"
+COMET_ENV="${COMET_ENV:-$(find . "$HOME"/.*/skills "$HOME/.config" "$HOME/.gemini" -path '*/comet/scripts/comet-env.js' -type f -print -quit 2>/dev/null)}"
 if [ -z "$COMET_ENV" ]; then
-  echo "ERROR: comet-env.sh not found. Ensure the comet skill is installed." >&2
+  echo "ERROR: comet-env.js not found. Ensure the comet skill is installed." >&2
   return 1
 fi
-. "$COMET_ENV"
-"$COMET_BASH" "$COMET_STATE" check <name> design
+COMET_ENV_JSON="$(node "$COMET_ENV")"
+COMET_STATE="$(printf '%s' "$COMET_ENV_JSON" | node -e "let s='';process.stdin.on('data',d=>s+=d).on('end',()=>console.log(JSON.parse(s).COMET_STATE))")"
+COMET_GUARD="$(printf '%s' "$COMET_ENV_JSON" | node -e "let s='';process.stdin.on('data',d=>s+=d).on('end',()=>console.log(JSON.parse(s).COMET_GUARD))")"
+COMET_HANDOFF="$(printf '%s' "$COMET_ENV_JSON" | node -e "let s='';process.stdin.on('data',d=>s+=d).on('end',()=>console.log(JSON.parse(s).COMET_HANDOFF))")"
+COMET_ARCHIVE="$(printf '%s' "$COMET_ENV_JSON" | node -e "let s='';process.stdin.on('data',d=>s+=d).on('end',()=>console.log(JSON.parse(s).COMET_ARCHIVE))")"
+node "$COMET_STATE" check <name> design
 ```
 
 Proceed to Step 1 after verification passes. The script outputs specific failure reasons when verification fails.
@@ -35,7 +39,7 @@ Proceed to Step 1 after verification passes. The script outputs specific failure
 **Must be generated by script. Agent writing summaries on the fly is not allowed.**
 
 ```bash
-"$COMET_BASH" "$COMET_HANDOFF" <change-name> design --write
+node "$COMET_HANDOFF" <change-name> design --write
 ```
 
 The script generates and records:
@@ -60,7 +64,7 @@ The default handoff package is a **compact traceable excerpt**, not an agent sum
 If full context is genuinely needed, explicitly run:
 
 ```bash
-"$COMET_BASH" "$COMET_HANDOFF" <change-name> design --write --full
+node "$COMET_HANDOFF" <change-name> design --write --full
 ```
 
 Handoff package sources come from OpenSpec open phase artifacts:
@@ -122,13 +126,13 @@ First record the design_doc path. If Step 1c wrote back delta spec (added or mod
 
 ```bash
 # Record design_doc path
-"$COMET_BASH" "$COMET_STATE" set <name> design_doc docs/superpowers/specs/YYYY-MM-DD-topic-design.md
+node "$COMET_STATE" set <name> design_doc docs/superpowers/specs/YYYY-MM-DD-topic-design.md
 
 # If delta spec changes exist, regenerate handoff (update hash)
-"$COMET_BASH" "$COMET_HANDOFF" <change-name> design --write
+node "$COMET_HANDOFF" <change-name> design --write
 
 # Auto-transition to next phase
-"$COMET_BASH" "$COMET_GUARD" <change-name> design --apply
+node "$COMET_GUARD" <change-name> design --apply
 ```
 
 If there are no delta spec changes, skip the handoff regeneration step. The state file updates automatically; no manual editing of other fields needed.
@@ -142,12 +146,12 @@ If there are no delta spec changes, skip the handoff regeneration step. The stat
 - `design-context.md` must be script-generated and contain source path, mode, sha256 traceability markers (enforced by guard)
 - If new capabilities or supplementary acceptance scenarios exist, OpenSpec delta spec has been created/updated
 - `design_doc` written to `.comet.yaml`
-- **Phase guard**: Run `"$COMET_BASH" "$COMET_GUARD" <change-name> design --apply`; after all PASS, auto-transitions to `phase: build`
+- **Phase guard**: Run `node "$COMET_GUARD" <change-name> design --apply`; after all PASS, auto-transitions to `phase: build`
 
 Must use `--apply` before exit:
 
 ```bash
-"$COMET_BASH" "$COMET_GUARD" <change-name> design --apply
+node "$COMET_GUARD" <change-name> design --apply
 ```
 
 ## Context Compaction Recovery
@@ -155,7 +159,7 @@ Must use `--apply` before exit:
 The design phase may trigger context compaction during brainstorming. To recover, first run:
 
 ```bash
-"$COMET_BASH" "$COMET_STATE" check <change-name> design --recover
+node "$COMET_STATE" check <change-name> design --recover
 ```
 
 The script outputs structured recovery context (phase, completed fields, pending fields, recovery action). Follow the Recovery action to determine next step.
diff --git a/assets/skills/comet-hotfix/SKILL.md b/assets/skills/comet-hotfix/SKILL.md
index 9bc4ea9e..50d0c814 100644
--- a/assets/skills/comet-hotfix/SKILL.md
+++ b/assets/skills/comet-hotfix/SKILL.md
@@ -23,12 +23,16 @@ Execution chain: open → build → root cause check → verify → archive. Hot
 Locate Comet scripts before starting:
 
 ```bash
-COMET_ENV="${COMET_ENV:-$(find . "$HOME"/.*/skills "$HOME/.config" "$HOME/.gemini" -path '*/comet/scripts/comet-env.sh' -type f -print -quit 2>/dev/null)}"
+COMET_ENV="${COMET_ENV:-$(find . "$HOME"/.*/skills "$HOME/.config" "$HOME/.gemini" -path '*/comet/scripts/comet-env.js' -type f -print -quit 2>/dev/null)}"
 if [ -z "$COMET_ENV" ]; then
-  echo "ERROR: comet-env.sh not found. Ensure the comet skill is installed." >&2
+  echo "ERROR: comet-env.js not found. Ensure the comet skill is installed." >&2
   return 1
 fi
-. "$COMET_ENV"
+COMET_ENV_JSON="$(node "$COMET_ENV")"
+COMET_STATE="$(printf '%s' "$COMET_ENV_JSON" | node -e "let s='';process.stdin.on('data',d=>s+=d).on('end',()=>console.log(JSON.parse(s).COMET_STATE))")"
+COMET_GUARD="$(printf '%s' "$COMET_ENV_JSON" | node -e "let s='';process.stdin.on('data',d=>s+=d).on('end',()=>console.log(JSON.parse(s).COMET_GUARD))")"
+COMET_HANDOFF="$(printf '%s' "$COMET_ENV_JSON" | node -e "let s='';process.stdin.on('data',d=>s+=d).on('end',()=>console.log(JSON.parse(s).COMET_HANDOFF))")"
+COMET_ARCHIVE="$(printf '%s' "$COMET_ENV_JSON" | node -e "let s='';process.stdin.on('data',d=>s+=d).on('end',()=>console.log(JSON.parse(s).COMET_ARCHIVE))")"
 ```
 
 ### 1. Quick Open (preset open)
@@ -54,19 +58,19 @@ Streamlined OpenSpec artifacts must use the language of the user request that tr
 Initialize Comet state file:
 
 ```bash
-"$COMET_BASH" "$COMET_STATE" init <name> hotfix
+node "$COMET_STATE" init <name> hotfix
 ```
 
 Verify initialized state:
 
 ```bash
-"$COMET_BASH" "$COMET_STATE" check <name> open
+node "$COMET_STATE" check <name> open
 ```
 
 Run phase guard to transition open → build:
 
 ```bash
-"$COMET_BASH" "$COMET_GUARD" <change-name> open --apply
+node "$COMET_GUARD" <change-name> open --apply
 ```
 
 ### 2. Direct Build (preset build)
@@ -105,7 +109,7 @@ Before continuing or starting changes, handle uncommitted changes through `comet
 After root cause is confirmed eliminated, run phase guard to transition build → verify:
 
 ```bash
-"$COMET_BASH" "$COMET_GUARD" <change-name> build --apply
+node "$COMET_GUARD" <change-name> build --apply
 ```
 
 State automatically updates to `phase: verify`, `verify_result: pending`, then enter verification.
@@ -162,7 +166,7 @@ When upgrade conditions are met, **must use the AskUserQuestion tool to pause an
 After user confirms upgrade, **must first update the workflow field** before entering full flow:
 
 ```bash
-"$COMET_BASH" "$COMET_STATE" set <name> workflow full
+node "$COMET_STATE" set <name> workflow full
 ```
 
 Then on current change basis, supplement Design Doc: **Immediately use the Skill tool to load the `comet-design` skill**, proceed normally with full workflow. If user does not confirm upgrade, stop hotfix and report that current change has exceeded hotfix scope.
@@ -174,4 +178,4 @@ Then on current change basis, supplement Design Doc: **Immediately use the Skill
 - Bug fixed, tests pass
 - Change archived
 - If spec changes, synced to main spec
-- **Phase guard**: Before build → verify run `"$COMET_BASH" "$COMET_GUARD" <change-name> build --apply`; before verify → archive follow `/comet-verify` and run `"$COMET_BASH" "$COMET_GUARD" <change-name> verify --apply`
+- **Phase guard**: Before build → verify run `node "$COMET_GUARD" <change-name> build --apply`; before verify → archive follow `/comet-verify` and run `node "$COMET_GUARD" <change-name> verify --apply`
diff --git a/assets/skills/comet-open/SKILL.md b/assets/skills/comet-open/SKILL.md
index e182bbcb..e34c95e7 100644
--- a/assets/skills/comet-open/SKILL.md
+++ b/assets/skills/comet-open/SKILL.md
@@ -53,19 +53,23 @@ openspec/changes/<name>/
 Create `.comet.yaml` state file:
 
 ```bash
-COMET_ENV="${COMET_ENV:-$(find . "$HOME"/.*/skills "$HOME/.config" "$HOME/.gemini" -path '*/comet/scripts/comet-env.sh' -type f -print -quit 2>/dev/null)}"
+COMET_ENV="${COMET_ENV:-$(find . "$HOME"/.*/skills "$HOME/.config" "$HOME/.gemini" -path '*/comet/scripts/comet-env.js' -type f -print -quit 2>/dev/null)}"
 if [ -z "$COMET_ENV" ]; then
-  echo "ERROR: comet-env.sh not found. Ensure the comet skill is installed." >&2
+  echo "ERROR: comet-env.js not found. Ensure the comet skill is installed." >&2
   return 1
 fi
-. "$COMET_ENV"
+COMET_ENV_JSON="$(node "$COMET_ENV")"
+COMET_STATE="$(printf '%s' "$COMET_ENV_JSON" | node -e "let s='';process.stdin.on('data',d=>s+=d).on('end',()=>console.log(JSON.parse(s).COMET_STATE))")"
+COMET_GUARD="$(printf '%s' "$COMET_ENV_JSON" | node -e "let s='';process.stdin.on('data',d=>s+=d).on('end',()=>console.log(JSON.parse(s).COMET_GUARD))")"
+COMET_HANDOFF="$(printf '%s' "$COMET_ENV_JSON" | node -e "let s='';process.stdin.on('data',d=>s+=d).on('end',()=>console.log(JSON.parse(s).COMET_HANDOFF))")"
+COMET_ARCHIVE="$(printf '%s' "$COMET_ENV_JSON" | node -e "let s='';process.stdin.on('data',d=>s+=d).on('end',()=>console.log(JSON.parse(s).COMET_ARCHIVE))")"
 
 if [ -z "$COMET_STATE" ] || [ -z "$COMET_GUARD" ]; then
   echo "ERROR: Comet scripts not found. Ensure the comet skill is installed." >&2
   return 1
 fi
 
-"$COMET_BASH" "$COMET_STATE" init <name> full
+node "$COMET_STATE" init <name> full
 ```
 
 ### 3. Entry State Verification
@@ -73,7 +77,7 @@ fi
 Verify state machine has been correctly initialized:
 
 ```bash
-"$COMET_BASH" "$COMET_STATE" check <name> open
+node "$COMET_STATE" check <name> open
 ```
 
 Proceed to Step 4 after verification passes. The script outputs specific failure reasons when verification fails.
@@ -110,12 +114,12 @@ After user selects "Confirm", proceed to exit conditions. When user selects "Nee
 
 - proposal.md, design.md, tasks.md all created with complete content
 - **User has confirmed** proposal, design, tasks content meets expectations
-- **Phase guard**: Run `"$COMET_BASH" "$COMET_GUARD" <change-name> open --apply`; after all PASS, auto-transitions to next phase
+- **Phase guard**: Run `node "$COMET_GUARD" <change-name> open --apply`; after all PASS, auto-transitions to next phase
 
 Must use `--apply` before exit, otherwise `.comet.yaml` remains at `phase: open` and the next phase entry check will fail.
 
 ```bash
-"$COMET_BASH" "$COMET_GUARD" <change-name> open --apply
+node "$COMET_GUARD" <change-name> open --apply
 ```
 
 Full workflow auto-transitions to `phase: design`; hotfix/tweak presets auto-transition to `phase: build`.
diff --git a/assets/skills/comet-tweak/SKILL.md b/assets/skills/comet-tweak/SKILL.md
index 31325925..be25daba 100644
--- a/assets/skills/comet-tweak/SKILL.md
+++ b/assets/skills/comet-tweak/SKILL.md
@@ -26,12 +26,16 @@ Execution chain: open → lightweight build → light verify → archive. Tweak
 Locate Comet scripts before starting:
 
 ```bash
-COMET_ENV="${COMET_ENV:-$(find . "$HOME"/.*/skills "$HOME/.config" "$HOME/.gemini" -path '*/comet/scripts/comet-env.sh' -type f -print -quit 2>/dev/null)}"
+COMET_ENV="${COMET_ENV:-$(find . "$HOME"/.*/skills "$HOME/.config" "$HOME/.gemini" -path '*/comet/scripts/comet-env.js' -type f -print -quit 2>/dev/null)}"
 if [ -z "$COMET_ENV" ]; then
-  echo "ERROR: comet-env.sh not found. Ensure the comet skill is installed." >&2
+  echo "ERROR: comet-env.js not found. Ensure the comet skill is installed." >&2
   return 1
 fi
-. "$COMET_ENV"
+COMET_ENV_JSON="$(node "$COMET_ENV")"
+COMET_STATE="$(printf '%s' "$COMET_ENV_JSON" | node -e "let s='';process.stdin.on('data',d=>s+=d).on('end',()=>console.log(JSON.parse(s).COMET_STATE))")"
+COMET_GUARD="$(printf '%s' "$COMET_ENV_JSON" | node -e "let s='';process.stdin.on('data',d=>s+=d).on('end',()=>console.log(JSON.parse(s).COMET_GUARD))")"
+COMET_HANDOFF="$(printf '%s' "$COMET_ENV_JSON" | node -e "let s='';process.stdin.on('data',d=>s+=d).on('end',()=>console.log(JSON.parse(s).COMET_HANDOFF))")"
+COMET_ARCHIVE="$(printf '%s' "$COMET_ENV_JSON" | node -e "let s='';process.stdin.on('data',d=>s+=d).on('end',()=>console.log(JSON.parse(s).COMET_ARCHIVE))")"
 ```
 
 ### 1. Quick Open (preset open)
@@ -57,19 +61,19 @@ Streamlined OpenSpec artifacts must use the language of the user request that tr
 Initialize Comet state file:
 
 ```bash
-"$COMET_BASH" "$COMET_STATE" init <name> tweak
+node "$COMET_STATE" init <name> tweak
 ```
 
 Verify initialized state:
 
 ```bash
-"$COMET_BASH" "$COMET_STATE" check <name> open
+node "$COMET_STATE" check <name> open
 ```
 
 Run phase guard to transition open → build:
 
 ```bash
-"$COMET_BASH" "$COMET_GUARD" <change-name> open --apply
+node "$COMET_GUARD" <change-name> open --apply
 ```
 
 ### 2. Lightweight Build (preset build)
@@ -91,7 +95,7 @@ Before continuing or starting changes, handle uncommitted changes through `comet
 4. Run phase guard to transition build → verify:
 
 ```bash
-"$COMET_BASH" "$COMET_GUARD" <change-name> build --apply
+node "$COMET_GUARD" <change-name> build --apply
 ```
 
 State automatically updates to `phase: verify`, `verify_result: pending`, then enter verification.
@@ -147,7 +151,7 @@ When upgrade conditions are met, **must use the AskUserQuestion tool to pause an
 After user confirms upgrade, **must first update the workflow field** before entering full flow:
 
 ```bash
-"$COMET_BASH" "$COMET_STATE" set <name> workflow full
+node "$COMET_STATE" set <name> workflow full
 ```
 
 Then on current change basis, supplement Design Doc: **Immediately use the Skill tool to load the `comet-design` skill**, proceed normally with full workflow. If user does not confirm upgrade, stop tweak and report that current change has exceeded tweak scope.
@@ -159,4 +163,4 @@ Then on current change basis, supplement Design Doc: **Immediately use the Skill
 - Small change completed, tests pass
 - Change archived
 - No new capability, architecture adjustments or interface changes
-- **Phase guard**: Before build → verify run `"$COMET_BASH" "$COMET_GUARD" <change-name> build --apply`; before verify → archive follow `/comet-verify` and run `"$COMET_BASH" "$COMET_GUARD" <change-name> verify --apply`
+- **Phase guard**: Before build → verify run `node "$COMET_GUARD" <change-name> build --apply`; before verify → archive follow `/comet-verify` and run `node "$COMET_GUARD" <change-name> verify --apply`
diff --git a/assets/skills/comet-verify/SKILL.md b/assets/skills/comet-verify/SKILL.md
index 8f38eb00..1260528e 100644
--- a/assets/skills/comet-verify/SKILL.md
+++ b/assets/skills/comet-verify/SKILL.md
@@ -17,13 +17,17 @@ description: "Comet Phase 4: Verify and Close. Invoke with /comet-verify. Verify
 Execute entry verification:
 
 ```bash
-COMET_ENV="${COMET_ENV:-$(find . "$HOME"/.*/skills "$HOME/.config" "$HOME/.gemini" -path '*/comet/scripts/comet-env.sh' -type f -print -quit 2>/dev/null)}"
+COMET_ENV="${COMET_ENV:-$(find . "$HOME"/.*/skills "$HOME/.config" "$HOME/.gemini" -path '*/comet/scripts/comet-env.js' -type f -print -quit 2>/dev/null)}"
 if [ -z "$COMET_ENV" ]; then
-  echo "ERROR: comet-env.sh not found. Ensure the comet skill is installed." >&2
+  echo "ERROR: comet-env.js not found. Ensure the comet skill is installed." >&2
   return 1
 fi
-. "$COMET_ENV"
-"$COMET_BASH" "$COMET_STATE" check <change-name> verify
+COMET_ENV_JSON="$(node "$COMET_ENV")"
+COMET_STATE="$(printf '%s' "$COMET_ENV_JSON" | node -e "let s='';process.stdin.on('data',d=>s+=d).on('end',()=>console.log(JSON.parse(s).COMET_STATE))")"
+COMET_GUARD="$(printf '%s' "$COMET_ENV_JSON" | node -e "let s='';process.stdin.on('data',d=>s+=d).on('end',()=>console.log(JSON.parse(s).COMET_GUARD))")"
+COMET_HANDOFF="$(printf '%s' "$COMET_ENV_JSON" | node -e "let s='';process.stdin.on('data',d=>s+=d).on('end',()=>console.log(JSON.parse(s).COMET_HANDOFF))")"
+COMET_ARCHIVE="$(printf '%s' "$COMET_ENV_JSON" | node -e "let s='';process.stdin.on('data',d=>s+=d).on('end',()=>console.log(JSON.parse(s).COMET_ARCHIVE))")"
+node "$COMET_STATE" check <change-name> verify
 ```
 
 Proceed to Step 1 after verification passes. The script outputs specific failure reasons when verification fails.
@@ -39,7 +43,7 @@ Verification reports and branch-handling notes must use the language of the user
 Execute scale assessment:
 
 ```bash
-"$COMET_BASH" "$COMET_STATE" scale <change-name>
+node "$COMET_STATE" scale <change-name>
 ```
 
 The script automatically counts tasks, delta spec count, changed file count, determines light or full verification mode, and sets the verify_mode field.
@@ -54,13 +58,13 @@ Only after user chooses fix, allow rollback to build phase:
 
 ```bash
 # Execute only after user confirms fix
-"$COMET_BASH" "$COMET_STATE" transition <change-name> verify-fail
+node "$COMET_STATE" transition <change-name> verify-fail
 ```
 
 Note: If every task in build phase was committed, the script's file count based on working tree diff may underestimate change scale. In this case, must read plan file header `base-ref` and verify with commit range:
 
 ```bash
-PLAN=$("$COMET_BASH" "$COMET_STATE" get <change-name> plan)
+PLAN=$(node "$COMET_STATE" get <change-name> plan)
 BASE_REF=$(grep '^base-ref:' "$PLAN" 2>/dev/null | head -1 | sed 's/^base-ref: *//')
 git diff --stat "$BASE_REF"...HEAD
 ```
@@ -68,12 +72,12 @@ git diff --stat "$BASE_REF"...HEAD
 If commit range shows changes exceed lightweight threshold (> 4 files, cross-module coordination, or delta spec spans more than 1 capability), manually set to full verification:
 
 ```bash
-"$COMET_BASH" "$COMET_STATE" set <change-name> verify_mode full
+node "$COMET_STATE" set <change-name> verify_mode full
 ```
 
 ### 1b. Verification Failure Decision (Blocking Point)
 
-When verification does not pass, **must use the AskUserQuestion tool to pause and wait for the user to decide fix or accept deviation**. Must not automatically run `"$COMET_BASH" "$COMET_STATE" transition <change-name> verify-fail`, nor automatically invoke `/comet-build`. Must not just output a text prompt and then continue executing.
+When verification does not pass, **must use the AskUserQuestion tool to pause and wait for the user to decide fix or accept deviation**. Must not automatically run `node "$COMET_STATE" transition <change-name> verify-fail`, nor automatically invoke `/comet-build`. Must not just output a text prompt and then continue executing.
 
 When pausing, must list:
 - Failed items
@@ -83,7 +87,7 @@ When pausing, must list:
 **Uncertainty principle**: When severity is unclear, downgrade (SUGGESTION > WARNING > CRITICAL). Only use CRITICAL for build failures, test failures, and security issues; ambiguous or uncertain issues should be WARNING or SUGGESTION.
 
 After user selection, continue as follows:
-- **Fix all**: Run `"$COMET_BASH" "$COMET_STATE" transition <change-name> verify-fail`, then invoke `/comet-build` to fix
+- **Fix all**: Run `node "$COMET_STATE" transition <change-name> verify-fail`, then invoke `/comet-build` to fix
 - **Handle item by item**: CRITICAL failures must be fixed; non-CRITICAL failures may choose to accept deviation, but must record acceptance reason and impact scope in verification report. If any CRITICAL failure exists, skipping fix to accept all is not allowed
 
 ### 2a. Lightweight Verification (Small Changes)
@@ -102,7 +106,7 @@ When scale assessment result is "small", skip `openspec-verify-change` and direc
 
 ```bash
 # Execute only after user confirms fix
-"$COMET_BASH" "$COMET_STATE" transition <change-name> verify-fail
+node "$COMET_STATE" transition <change-name> verify-fail
 ```
 
 **Report format**: Brief table listing 5 check results + PASS/FAIL.
@@ -132,13 +136,13 @@ When verification does not pass: report missing items, enter Step 1b verificatio
 
 ```bash
 # Execute only after user confirms fix
-"$COMET_BASH" "$COMET_STATE" transition <change-name> verify-fail
+node "$COMET_STATE" transition <change-name> verify-fail
 ```
 
 **Spec Drift Handling** (user decision point):
 - If check item 6 finds contradictions (delta spec has content but design doc does not reflect it), **must use the AskUserQuestion tool as a single-select question to pause and wait for user to choose handling method**; must not select automatically. Options:
   - Option A: Append "Implementation Divergence" section to design doc recording deviation reason. Option A is a verify phase allowed artifact; after writing, must not re-trigger Step 1b dirty-worktree decision due to that design doc change
-  - Option B: After user selects B, run `"$COMET_BASH" "$COMET_STATE" transition <change-name> verify-fail`, then invoke `/comet-build`; `/comet-build`'s Spec Incremental Update rules will load the Superpowers `brainstorming` skill to update Design Doc + delta spec
+  - Option B: After user selects B, run `node "$COMET_STATE" transition <change-name> verify-fail`, then invoke `/comet-build`; `/comet-build`'s Spec Incremental Update rules will load the Superpowers `brainstorming` skill to update Design Doc + delta spec
   - Option C: Confirm deviation is acceptable, continue verification (design doc will be marked as `superseded-by-main-spec` during archiving)
 
 ### 3. Finishing (Superpowers)
@@ -168,8 +172,8 @@ mkdir -p docs/superpowers/reports
 # Write verification conclusions to report file, e.g.:
 # docs/superpowers/reports/YYYY-MM-DD-<change-name>-verify.md
 
-"$COMET_BASH" "$COMET_STATE" set <change-name> verification_report docs/superpowers/reports/YYYY-MM-DD-<change-name>-verify.md
-"$COMET_BASH" "$COMET_STATE" set <change-name> branch_status handled
+node "$COMET_STATE" set <change-name> verification_report docs/superpowers/reports/YYYY-MM-DD-<change-name>-verify.md
+node "$COMET_STATE" set <change-name> branch_status handled
 ```
 
 ## Exit Conditions
@@ -178,12 +182,12 @@ mkdir -p docs/superpowers/reports
 - Branch handled
 - `verification_report` in `.comet.yaml` points to an existing verification report file
 - `branch_status: handled` in `.comet.yaml`
-- **Phase guard**: Run `"$COMET_BASH" "$COMET_GUARD" <change-name> verify --apply`; after all PASS, auto-transitions to `phase: archive` through `comet-state transition verify-pass`
+- **Phase guard**: Run `node "$COMET_GUARD" <change-name> verify --apply`; after all PASS, auto-transitions to `phase: archive` through `comet-state transition verify-pass`
 
 After both verification and branch handling are complete, run guard for auto-transition:
 
 ```bash
-"$COMET_BASH" "$COMET_GUARD" <change-name> verify --apply
+node "$COMET_GUARD" <change-name> verify --apply
 ```
 
 State file auto-updates to `phase: archive`, `verify_result: pass`, `verified_at: YYYY-MM-DD`.
@@ -199,7 +203,7 @@ After exit conditions are met (including user selecting branch handling method),
 The verify phase may trigger context compaction. To recover, first run:
 
 ```bash
-"$COMET_BASH" "$COMET_STATE" check <change-name> verify --recover
+node "$COMET_STATE" check <change-name> verify --recover
 ```
 
 The script outputs structured recovery context (phase, verification status, branch status, recovery action). Follow the Recovery action to determine next step.
diff --git a/assets/skills/comet/SKILL.md b/assets/skills/comet/SKILL.md
index c8b38629..fb9a421a 100644
--- a/assets/skills/comet/SKILL.md
+++ b/assets/skills/comet/SKILL.md
@@ -67,8 +67,8 @@ Prefer reading `openspec/changes/<name>/.comet.yaml`. If not available, fall bac
   - If `build_pause: plan-ready` but the plan file is missing, return to `/comet-build` to handle corrupted state or regenerate the plan
   - If `build_mode` or `isolation` is unset, return to the corresponding `/comet-build` step to supplement before executing
   - If both are set, read the next unchecked task from tasks.md and continue
-- If `phase: verify` and `verify_result: fail`, enter the verification failure decision blocking point: pause and ask the user to fix or accept deviation; only after the user chooses fix, run `"$COMET_BASH" "$COMET_STATE" transition <name> verify-fail` and invoke `/comet-build`
-- If `phase: open` but proposal/design/tasks are complete, first run `"$COMET_BASH" "$COMET_GUARD" <change-name> open --apply` to repair state, then continue detection
+- If `phase: verify` and `verify_result: fail`, enter the verification failure decision blocking point: pause and ask the user to fix or accept deviation; only after the user chooses fix, run `node "$COMET_STATE" transition <name> verify-fail` and invoke `/comet-build`
+- If `phase: open` but proposal/design/tasks are complete, first run `node "$COMET_GUARD" <change-name> open --apply` to repair state, then continue detection
 - If `phase: archive`, only invoke `/comet-archive`; after archive succeeds, the change moves to the archive directory, so do not run guard against the old active directory
 
 **Step 2: Phase Determination** (check in order, first match wins)
@@ -105,7 +105,7 @@ If metadata conflicts with file state, use verifiable file state as source of tr
 |----------|----------|
 | `openspec list --json` fails | Check if openspec is installed, prompt user to run `openspec init` |
 | Sub-skill unavailable | Stop workflow, prompt to install or enable the corresponding skill |
-| `.comet.yaml` malformed or missing | Use file state as source of truth, correct with `"$COMET_BASH" "$COMET_STATE" set` then continue |
+| `.comet.yaml` malformed or missing | Use file state as source of truth, correct with `node "$COMET_STATE" set` then continue |
 | Build/test fails | Return to build phase for fixes, do not enter verify |
 | Incomplete change directory structure | Fill missing files according to `comet-open` artifact requirements |
 
@@ -226,24 +226,28 @@ State-machine hard constraints:
 - Before `build → verify`, `build_mode` must be selected
 - `build_mode: direct` is allowed by default only for `hotfix` / `tweak`; full workflow requires `direct_override: true`
 - `build_pause` is not an execution method and must not be written to `build_mode`
-- These constraints are enforced by both `comet-guard.sh build --apply` and `comet-state.sh transition <name> build-complete`
+- These constraints are enforced by both `comet-guard.js build --apply` and `comet-state.js transition <name> build-complete`
 
 ### Script Location
 
 Comet scripts are distributed in `comet/scripts/`. **Do not hardcode paths** — locate once, cache in env vars:
 
 ```bash
-COMET_ENV="${COMET_ENV:-$(find . "$HOME"/.*/skills "$HOME/.config" "$HOME/.gemini" -path '*/comet/scripts/comet-env.sh' -type f -print -quit 2>/dev/null)}"
+COMET_ENV="${COMET_ENV:-$(find . "$HOME"/.*/skills "$HOME/.config" "$HOME/.gemini" -path '*/comet/scripts/comet-env.js' -type f -print -quit 2>/dev/null)}"
 if [ -z "$COMET_ENV" ]; then
-  echo "ERROR: comet-env.sh not found. Ensure the comet skill is installed." >&2
+  echo "ERROR: comet-env.js not found. Ensure the comet skill is installed." >&2
   return 1
 fi
-. "$COMET_ENV"
+COMET_ENV_JSON="$(node "$COMET_ENV")"
+COMET_STATE="$(printf '%s' "$COMET_ENV_JSON" | node -e "let s='';process.stdin.on('data',d=>s+=d).on('end',()=>console.log(JSON.parse(s).COMET_STATE))")"
+COMET_GUARD="$(printf '%s' "$COMET_ENV_JSON" | node -e "let s='';process.stdin.on('data',d=>s+=d).on('end',()=>console.log(JSON.parse(s).COMET_GUARD))")"
+COMET_HANDOFF="$(printf '%s' "$COMET_ENV_JSON" | node -e "let s='';process.stdin.on('data',d=>s+=d).on('end',()=>console.log(JSON.parse(s).COMET_HANDOFF))")"
+COMET_ARCHIVE="$(printf '%s' "$COMET_ENV_JSON" | node -e "let s='';process.stdin.on('data',d=>s+=d).on('end',()=>console.log(JSON.parse(s).COMET_ARCHIVE))")"
 
 # Stop workflow when script location fails
 if [ -z "$COMET_GUARD" ] || [ -z "$COMET_STATE" ] || [ -z "$COMET_HANDOFF" ] || [ -z "$COMET_ARCHIVE" ]; then
   echo "ERROR: Comet scripts not found. Ensure the comet skill is installed." >&2
-  echo "Expected path pattern: */comet/scripts/comet-*.sh under project or platform skill directories" >&2
+  echo "Expected path pattern: */comet/scripts/comet-*.js under project or platform skill directories" >&2
   return 1
 fi
 ```
@@ -251,24 +255,24 @@ fi
 **Auto state update**: Guard supports `--apply` flag, automatically updating `.comet.yaml` state fields after checks pass:
 
 ```bash
-"$COMET_BASH" "$COMET_GUARD" <change-name> <phase> --apply
+node "$COMET_GUARD" <change-name> <phase> --apply
 ```
 
 `--apply` delegates to `comet-state transition`. Use these semantic events when state changes need to be expressed directly:
 
 ```bash
-"$COMET_BASH" "$COMET_STATE" transition <change-name> open-complete
-"$COMET_BASH" "$COMET_STATE" transition <change-name> design-complete
-"$COMET_BASH" "$COMET_STATE" transition <change-name> build-complete
-"$COMET_BASH" "$COMET_STATE" transition <change-name> verify-pass
-"$COMET_BASH" "$COMET_STATE" transition <change-name> verify-fail
-"$COMET_BASH" "$COMET_STATE" transition <archive-name> archived
+node "$COMET_STATE" transition <change-name> open-complete
+node "$COMET_STATE" transition <change-name> design-complete
+node "$COMET_STATE" transition <change-name> build-complete
+node "$COMET_STATE" transition <change-name> verify-pass
+node "$COMET_STATE" transition <change-name> verify-fail
+node "$COMET_STATE" transition <archive-name> archived
 ```
 
 **Archive script**: Complete all archive steps in one command:
 
 ```bash
-"$COMET_BASH" "$COMET_ARCHIVE" <change-name>
+node "$COMET_ARCHIVE" <change-name>
 ```
 
 After loading comet, agents should run the variable assignments above once, then reuse `$COMET_GUARD`, `$COMET_STATE`, `$COMET_HANDOFF`, `$COMET_ARCHIVE` throughout the session.
@@ -299,7 +303,7 @@ docs/superpowers/                      # Superpowers — HOW
 
 1. **brainstorming cannot be skipped** — Every change must undergo deep design (except hotfix and tweak)
 2. **delta spec is a living document** — Freely modify during phase 3, sync at archive
-3. **Handoff packages are generated by scripts** — OpenSpec → Superpowers context must be generated through `comet-handoff.sh` as compact traceable excerpts (use `--full` when needed), and validated by guard for source/hash/mode
+3. **Handoff packages are generated by scripts** — OpenSpec → Superpowers context must be generated through `comet-handoff.js` as compact traceable excerpts (use `--full` when needed), and validated by guard for source/hash/mode
 4. **Keep tasks.md in sync** — Check off each completed task
 5. **Commit frequently** — One commit per task, message reflects design intent
 6. **Verify before archive** — Execute `/comet-archive` only after `/comet-verify` passes
diff --git a/assets/skills/comet/scripts/comet-archive.js b/assets/skills/comet/scripts/comet-archive.js
new file mode 100644
index 00000000..c44ab4c9
--- /dev/null
+++ b/assets/skills/comet/scripts/comet-archive.js
@@ -0,0 +1,106 @@
+#!/usr/bin/env node
+import { copyFileSync, existsSync, mkdirSync, readdirSync, readFileSync, renameSync, statSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fieldValue, green, red, runNode, scriptDir, today, validateChangeName, yellow } from './comet-lib.js';
+
+const [change, flag] = process.argv.slice(2);
+const dryRun = flag === '--dry-run';
+validateChangeName(change, 'FATAL');
+const changeDir = join('openspec', 'changes', change);
+const yaml = join(changeDir, '.comet.yaml');
+const archiveName = `${today()}-${change}`;
+const archiveDir = join('openspec', 'changes', 'archive', archiveName);
+let stepsOk = 0;
+let stepsTotal = 0;
+
+function fatal(message) {
+  red(`FATAL: ${message}`);
+  process.exit(1);
+}
+
+function stepOk(message) { green(`  [OK] ${message}`); stepsOk += 1; stepsTotal += 1; }
+function stepFail(message) { red(`  [FAIL] ${message}`); stepsTotal += 1; }
+function stepDry(message) { yellow(`  [DRY-RUN] ${message}`); stepsOk += 1; stepsTotal += 1; }
+function y(field) { return fieldValue(yaml, field); }
+
+console.error(`=== Comet Archive: ${change} ===`);
+if (!existsSync(yaml)) fatal(`.comet.yaml not found in ${changeDir}/`);
+const designDoc = y('design_doc');
+const planPath = y('plan');
+if (y('phase') !== 'archive') fatal(`phase is '${y('phase')}', expected 'archive'`);
+if (y('verify_result') !== 'pass') fatal(`verify_result is '${y('verify_result')}', expected 'pass'. Run comet-verify first.`);
+if (y('archived') === 'true') fatal('change already archived');
+stepOk('Entry state verified');
+if (existsSync(archiveDir)) fatal(`archive target already exists: ${archiveDir}`);
+stepOk('Archive target available');
+
+function syncDeltaSpecs() {
+  const deltaRoot = join(changeDir, 'specs');
+  if (!existsSync(deltaRoot)) return;
+  for (const capability of readdirSync(deltaRoot)) {
+    const deltaSpecDir = join(deltaRoot, capability);
+    if (!statSync(deltaSpecDir).isDirectory()) continue;
+    const deltaSpec = join(deltaSpecDir, 'spec.md');
+    const mainSpec = join('openspec', 'specs', capability, 'spec.md');
+    if (!existsSync(deltaSpec)) continue;
+    if (dryRun) {
+      stepDry(`Would sync: ${capability} → ${mainSpec}`);
+      continue;
+    }
+    mkdirSync(dirname(mainSpec), { recursive: true });
+    copyFileSync(deltaSpec, mainSpec);
+    stepOk(`Delta spec synced: ${capability} → openspec/specs/${capability}/spec.md`);
+  }
+}
+
+function annotateFrontmatter(file, extraFields) {
+  if (!existsSync(file)) return;
+  if (dryRun) {
+    stepDry(`Would annotate: ${file}`);
+    return;
+  }
+  const text = readFileSync(file, 'utf8');
+  let next;
+  if (text.startsWith('---')) {
+    const lines = text.split(/\r?\n/);
+    const out = [];
+    let inserted = false;
+    for (let i = 0; i < lines.length; i += 1) {
+      const line = lines[i];
+      if (/^archived-with:/.test(line)) continue;
+      if (i > 0 && line === '---' && !inserted) {
+        out.push(`archived-with: ${archiveName}`);
+        if (extraFields) out.push(extraFields);
+        inserted = true;
+      }
+      out.push(line);
+    }
+    next = out.join('\n');
+  } else {
+    next = `---\narchived-with: ${archiveName}\n${extraFields ? `${extraFields}\n` : ''}status: final\n---\n${text}`;
+  }
+  writeFileSync(file, next);
+  stepOk(`Annotated: ${file}`);
+}
+
+syncDeltaSpecs();
+if (designDoc && designDoc !== 'null') annotateFrontmatter(designDoc, 'status: final');
+if (planPath && planPath !== 'null') annotateFrontmatter(planPath, '');
+if (dryRun) stepDry(`Would move: ${changeDir} → ${archiveDir}`);
+else {
+  mkdirSync(join('openspec', 'changes', 'archive'), { recursive: true });
+  renameSync(changeDir, archiveDir);
+  stepOk(`Moved to: ${archiveDir}`);
+}
+const archiveYaml = join(archiveDir, '.comet.yaml');
+if (dryRun) stepDry(`Would set archived: true in ${archiveYaml}`);
+else if (existsSync(archiveYaml)) {
+  const state = join(scriptDir, 'comet-state.js');
+  const result = runNode(state, ['transition', archiveName, 'archived']);
+  if (result.status === 0) stepOk('archived: true');
+  else stepFail('archived: true');
+} else stepFail('archived: true (.comet.yaml not found after move)');
+console.error('');
+if (dryRun) yellow(`Dry run complete. ${stepsOk}/${stepsTotal} steps would succeed.`);
+else green(`Archive complete. ${stepsOk}/${stepsTotal} steps succeeded.`);
+if (stepsOk < stepsTotal) process.exit(1);
diff --git a/assets/skills/comet/scripts/comet-archive.sh b/assets/skills/comet/scripts/comet-archive.sh
deleted file mode 100644
index 746f6138..00000000
--- a/assets/skills/comet/scripts/comet-archive.sh
+++ /dev/null
@@ -1,295 +0,0 @@
-#!/bin/bash
-# Comet Archive — automates the archive phase in one command
-# Usage: comet-archive.sh <change-name> [--dry-run]
-# Exit 0 = archive complete, exit 1 = fatal error
-
-set -euo pipefail
-
-COMET_BASH="${COMET_BASH:-${BASH:-bash}}"
-
-red() { echo -e "\033[31m$1\033[0m" >&2; }
-green() { echo -e "\033[32m$1\033[0m" >&2; }
-yellow() { echo -e "\033[33m$1\033[0m" >&2; }
-
-DRY_RUN=0
-if [[ "${2:-}" == "--dry-run" ]]; then
-  DRY_RUN=1
-fi
-
-# Input validation
-validate_change_name() {
-  local name="$1"
-  if [ -z "$name" ]; then
-    red "FATAL: Change name cannot be empty"
-    exit 1
-  fi
-  if [[ ! "$name" =~ ^[a-zA-Z0-9_-]+$ ]]; then
-    red "FATAL: Invalid change name: '$name'"
-    red "Valid characters: a-z, A-Z, 0-9, -, _"
-    exit 1
-  fi
-  if [[ "$name" =~ \.\. ]]; then
-    red "FATAL: Change name cannot contain '..'"
-    exit 1
-  fi
-}
-
-CHANGE="$1"
-validate_change_name "$CHANGE"
-
-CHANGE_DIR="openspec/changes/$CHANGE"
-YAML="$CHANGE_DIR/.comet.yaml"
-SCRIPT_DIR="$(cd "$(dirname "$(readlink -f "$0" 2>/dev/null || echo "$0")" 2>/dev/null || dirname "$0")" && pwd)"
-STATE_SH="$SCRIPT_DIR/comet-state.sh"
-TODAY=$(date +%Y-%m-%d)
-ARCHIVE_NAME="${TODAY}-${CHANGE}"
-ARCHIVE_DIR="openspec/changes/archive/${ARCHIVE_NAME}"
-
-STEPS_OK=0
-STEPS_TOTAL=0
-
-step_ok() {
-  green "  [OK] $1"
-  STEPS_OK=$((STEPS_OK + 1))
-  STEPS_TOTAL=$((STEPS_TOTAL + 1))
-}
-
-step_fail() {
-  red "  [FAIL] $1"
-  STEPS_TOTAL=$((STEPS_TOTAL + 1))
-}
-
-step_dry_run() {
-  yellow "  [DRY-RUN] $1"
-  STEPS_OK=$((STEPS_OK + 1))
-  STEPS_TOTAL=$((STEPS_TOTAL + 1))
-}
-
-echo "=== Comet Archive: $CHANGE ===" >&2
-
-# --- Step 1: Read .comet.yaml, extract paths ---
-
-yaml_field() {
-  local field="$1"
-  if [ -f "$STATE_SH" ]; then
-    "$COMET_BASH" "$STATE_SH" get "$CHANGE" "$field" 2>/dev/null
-  else
-    if [ -f "$YAML" ]; then
-      local value
-      value=$(grep "^${field}:" "$YAML" 2>/dev/null | sed "s/^${field}: *//" || true)
-      value=$(strip_inline_comment "$value")
-      strip_wrapping_quotes "$value"
-    fi
-  fi
-}
-
-strip_inline_comment() {
-  local value="$1"
-  printf '%s\n' "$value" | awk -v squote="'" '
-    {
-      out = ""
-      quote = ""
-      for (i = 1; i <= length($0); i++) {
-        c = substr($0, i, 1)
-        if (quote == "") {
-          if (c == "\"" || c == squote) {
-            quote = c
-          } else if (c == "#" && (i == 1 || substr($0, i - 1, 1) ~ /[[:space:]]/)) {
-            sub(/[[:space:]]+$/, "", out)
-            print out
-            next
-          }
-        } else if (c == quote) {
-          quote = ""
-        }
-        out = out c
-      }
-      print out
-    }
-  '
-}
-
-strip_wrapping_quotes() {
-  local value="$1"
-  case "$value" in
-    \"*\") printf '%s\n' "${value:1:${#value}-2}" ;;
-    \'*\') printf '%s\n' "${value:1:${#value}-2}" ;;
-    *) printf '%s\n' "$value" ;;
-  esac
-}
-
-if [ ! -f "$YAML" ]; then
-  red "FATAL: .comet.yaml not found in $CHANGE_DIR/"
-  exit 1
-fi
-
-DESIGN_DOC=$(yaml_field "design_doc")
-PLAN_PATH=$(yaml_field "plan")
-
-# --- Step 2: Validate entry state ---
-
-PHASE_VAL=$(yaml_field "phase")
-VERIFY_VAL=$(yaml_field "verify_result")
-ARCHIVED_VAL=$(yaml_field "archived")
-
-if [ "$PHASE_VAL" != "archive" ]; then
-  red "FATAL: phase is '$PHASE_VAL', expected 'archive'"
-  exit 1
-fi
-
-if [ "$VERIFY_VAL" != "pass" ]; then
-  red "FATAL: verify_result is '$VERIFY_VAL', expected 'pass'. Run comet-verify first."
-  exit 1
-fi
-
-if [ "$ARCHIVED_VAL" = "true" ]; then
-  red "FATAL: change already archived"
-  exit 1
-fi
-
-step_ok "Entry state verified"
-
-# --- Step 3: Check archive target ---
-
-if [ -d "$ARCHIVE_DIR" ]; then
-  red "FATAL: archive target already exists: $ARCHIVE_DIR"
-  exit 1
-fi
-
-step_ok "Archive target available"
-
-# --- Step 4: Sync delta specs → main specs ---
-
-sync_delta_specs() {
-  local delta_root="$CHANGE_DIR/specs"
-  if [ ! -d "$delta_root" ]; then
-    return 0
-  fi
-
-  for delta_spec_dir in "$delta_root"/*/; do
-    [ -d "$delta_spec_dir" ] || continue
-    local capability
-    capability=$(basename "$delta_spec_dir")
-    local delta_spec="$delta_spec_dir/spec.md"
-    local main_spec="openspec/specs/$capability/spec.md"
-
-    if [ ! -f "$delta_spec" ]; then
-      continue
-    fi
-
-    if [ "$DRY_RUN" -eq 1 ]; then
-      step_dry_run "Would sync: $capability → $main_spec"
-      continue
-    fi
-
-    if [ ! -f "$main_spec" ]; then
-      mkdir -p "openspec/specs/$capability"
-    elif ! cmp -s "$main_spec" "$delta_spec"; then
-      yellow "  [DIFF] Delta spec differs from main spec before sync: $capability"
-      diff -u "$main_spec" "$delta_spec" >&2 || true
-    fi
-    cp "$delta_spec" "$main_spec"
-
-    step_ok "Delta spec synced: $capability → openspec/specs/$capability/spec.md"
-  done
-}
-
-sync_delta_specs
-
-# --- Step 5: Annotate design doc frontmatter ---
-
-annotate_frontmatter() {
-  local file="$1"
-  local extra_fields="$2"
-
-  if [ ! -f "$file" ]; then
-    return 0
-  fi
-
-  if [ "$DRY_RUN" -eq 1 ]; then
-    step_dry_run "Would annotate: $file"
-    return 0
-  fi
-
-  if head -1 "$file" | grep -q '^---'; then
-    local tmp_file
-    tmp_file=$(mktemp)
-    awk -v archive="$ARCHIVE_NAME" -v extra="$extra_fields" '
-      /^archived-with:/ { next }
-      NR==1 && /^---/ { print; next }
-      /^---/ && NR>1 {
-        print "archived-with: " archive
-        if (extra != "") print extra
-        print; next
-      }
-      { print }
-    ' "$file" > "$tmp_file"
-    mv "$tmp_file" "$file"
-  else
-    local tmp_file
-    tmp_file=$(mktemp)
-    {
-      echo "---"
-      echo "archived-with: $ARCHIVE_NAME"
-      if [ -n "$extra_fields" ]; then
-        echo "$extra_fields"
-      fi
-      echo "status: final"
-      echo "---"
-      cat "$file"
-    } > "$tmp_file"
-    mv "$tmp_file" "$file"
-  fi
-
-  step_ok "Annotated: $file"
-}
-
-if [ -n "$DESIGN_DOC" ] && [ "$DESIGN_DOC" != "null" ]; then
-  annotate_frontmatter "$DESIGN_DOC" "status: final"
-fi
-
-# --- Step 6: Annotate plan frontmatter ---
-
-if [ -n "$PLAN_PATH" ] && [ "$PLAN_PATH" != "null" ]; then
-  annotate_frontmatter "$PLAN_PATH" ""
-fi
-
-# --- Step 7: Move change to archive ---
-
-if [ "$DRY_RUN" -eq 1 ]; then
-  step_dry_run "Would move: $CHANGE_DIR → $ARCHIVE_DIR"
-else
-  mkdir -p "openspec/changes/archive"
-  mv "$CHANGE_DIR" "$ARCHIVE_DIR"
-  step_ok "Moved to: $ARCHIVE_DIR"
-fi
-
-# --- Step 8: Mark archived via comet-state transition ---
-
-ARCHIVE_YAML="$ARCHIVE_DIR/.comet.yaml"
-
-if [ "$DRY_RUN" -eq 1 ]; then
-  step_dry_run "Would set archived: true in $ARCHIVE_YAML"
-else
-  if [ -f "$ARCHIVE_YAML" ]; then
-    "$COMET_BASH" "$STATE_SH" transition "$ARCHIVE_NAME" archived >/dev/null
-    step_ok "archived: true"
-  else
-    step_fail "archived: true (.comet.yaml not found after move)"
-  fi
-fi
-
-# --- Step 9: Print summary ---
-
-echo "" >&2
-if [ "$DRY_RUN" -eq 1 ]; then
-  yellow "Dry run complete. $STEPS_OK/$STEPS_TOTAL steps would succeed."
-else
-  green "Archive complete. $STEPS_OK/$STEPS_TOTAL steps succeeded."
-fi
-
-if [ "$STEPS_OK" -lt "$STEPS_TOTAL" ]; then
-  exit 1
-fi
-
-exit 0
diff --git a/assets/skills/comet/scripts/comet-env.js b/assets/skills/comet/scripts/comet-env.js
new file mode 100644
index 00000000..83103746
--- /dev/null
+++ b/assets/skills/comet/scripts/comet-env.js
@@ -0,0 +1,21 @@
+#!/usr/bin/env node
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { scriptDir } from './comet-lib.js';
+
+const env = {
+  COMET_STATE: join(scriptDir, 'comet-state.js'),
+  COMET_GUARD: join(scriptDir, 'comet-guard.js'),
+  COMET_HANDOFF: join(scriptDir, 'comet-handoff.js'),
+  COMET_ARCHIVE: join(scriptDir, 'comet-archive.js'),
+  COMET_YAML_VALIDATE: join(scriptDir, 'comet-yaml-validate.js'),
+};
+
+const missing = Object.values(env).filter((file) => !existsSync(file));
+if (missing.length > 0) {
+  console.error('ERROR: Comet scripts not found. Ensure the comet skill is installed completely.');
+  console.error('Expected path pattern: */comet/scripts/comet-*.js under project or platform skill directories');
+  process.exit(1);
+}
+
+console.log(JSON.stringify(env, null, 2));
diff --git a/assets/skills/comet/scripts/comet-env.sh b/assets/skills/comet/scripts/comet-env.sh
deleted file mode 100644
index d480f10d..00000000
--- a/assets/skills/comet/scripts/comet-env.sh
+++ /dev/null
@@ -1,110 +0,0 @@
-#!/bin/bash
-# Comet script locator — source this file to export paths to bundled scripts.
-#
-# Usage:
-#   . /path/to/comet/scripts/comet-env.sh
-#
-# This file is sourced by workflow snippets. Do not set global shell options here.
-
-_comet_env_source="${BASH_SOURCE[0]:-$0}"
-_comet_script_dir="$(cd "$(dirname "$_comet_env_source")" && pwd -P)"
-_comet_env_sourced=0
-(return 0 2>/dev/null) && _comet_env_sourced=1
-
-export COMET_GUARD="${COMET_GUARD:-${_comet_script_dir}/comet-guard.sh}"
-export COMET_STATE="${COMET_STATE:-${_comet_script_dir}/comet-state.sh}"
-export COMET_HANDOFF="${COMET_HANDOFF:-${_comet_script_dir}/comet-handoff.sh}"
-export COMET_ARCHIVE="${COMET_ARCHIVE:-${_comet_script_dir}/comet-archive.sh}"
-export COMET_YAML_VALIDATE="${COMET_YAML_VALIDATE:-${_comet_script_dir}/comet-yaml-validate.sh}"
-
-_comet_bash_is_usable() {
-  local _comet_bash_candidate="$1"
-  if [ -z "$_comet_bash_candidate" ]; then
-    return 1
-  fi
-  case "$_comet_bash_candidate" in
-    */Windows/System32/bash.exe|*/windows/system32/bash.exe|*\\Windows\\System32\\bash.exe|*\\windows\\system32\\bash.exe)
-      return 1
-      ;;
-  esac
-  "$_comet_bash_candidate" -lc 'printf comet-bash-ok' >/dev/null 2>&1
-}
-
-_comet_resolve_bash() {
-  local _comet_bash_candidate
-
-  if _comet_bash_is_usable "${COMET_BASH:-}"; then
-    printf '%s\n' "$COMET_BASH"
-    return 0
-  fi
-
-  if _comet_bash_is_usable "${BASH:-}"; then
-    printf '%s\n' "$BASH"
-    return 0
-  fi
-
-  _comet_bash_candidate="$(command -v sh 2>/dev/null | awk '{ sub(/\/sh(\.exe)?$/, "/bash.exe"); print }')"
-  if _comet_bash_is_usable "$_comet_bash_candidate"; then
-    printf '%s\n' "$_comet_bash_candidate"
-    return 0
-  fi
-
-  _comet_bash_candidate="$(command -v bash 2>/dev/null || true)"
-  if _comet_bash_is_usable "$_comet_bash_candidate"; then
-    printf '%s\n' "$_comet_bash_candidate"
-    return 0
-  fi
-
-  return 1
-}
-
-COMET_BASH="$(_comet_resolve_bash || true)"
-export COMET_BASH
-
-_comet_env_fail() {
-  echo "ERROR: Comet scripts not found. Ensure the comet skill is installed completely." >&2
-  echo "Expected path pattern: */comet/scripts/comet-*.sh under project or platform skill directories" >&2
-}
-
-_comet_bash_fail() {
-  echo "ERROR: usable bash not found. Install Git Bash or set COMET_BASH to a working bash executable." >&2
-  echo "Windows WSL launcher bash.exe is not supported for Comet scripts." >&2
-}
-
-_comet_env_abort() {
-  local _comet_env_was_sourced="$_comet_env_sourced"
-  unset _comet_env_source _comet_script_dir _comet_script _comet_env_missing _comet_env_sourced
-  unset _comet_bash_candidate
-  unset -f _comet_env_fail _comet_bash_fail _comet_bash_is_usable _comet_resolve_bash
-  if [ "$_comet_env_was_sourced" -eq 1 ]; then
-    unset -f _comet_env_abort
-    return 1
-  fi
-  exit 1
-}
-
-_comet_env_missing=0
-if [ -z "$COMET_BASH" ]; then
-  _comet_bash_fail
-  _comet_env_missing=1
-fi
-for _comet_script in \
-  "$COMET_GUARD" \
-  "$COMET_STATE" \
-  "$COMET_HANDOFF" \
-  "$COMET_ARCHIVE" \
-  "$COMET_YAML_VALIDATE"; do
-  if [ ! -f "$_comet_script" ]; then
-    _comet_env_fail
-    _comet_env_missing=1
-    break
-  fi
-done
-
-if [ "$_comet_env_missing" -ne 0 ]; then
-  _comet_env_abort
-else
-  unset _comet_env_source _comet_script_dir _comet_script _comet_env_missing _comet_env_sourced
-  unset _comet_bash_candidate
-  unset -f _comet_env_fail _comet_bash_fail _comet_bash_is_usable _comet_resolve_bash _comet_env_abort
-fi
diff --git a/assets/skills/comet/scripts/comet-guard.js b/assets/skills/comet/scripts/comet-guard.js
new file mode 100644
index 00000000..21fe38b8
--- /dev/null
+++ b/assets/skills/comet/scripts/comet-guard.js
@@ -0,0 +1,281 @@
+#!/usr/bin/env node
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import {
+  changeDirFor,
+  fieldValue,
+  fileNonempty,
+  green,
+  hashFile,
+  red,
+  runCommand,
+  runCommandString,
+  runNode,
+  scriptDir,
+  sha256,
+  slash,
+  validateChangeName,
+  yellow,
+} from './comet-lib.js';
+
+const [change, phase, applyFlag] = process.argv.slice(2);
+validateChangeName(change);
+const apply = applyFlag === '--apply';
+let changeDir = join('openspec', 'changes', change);
+if (phase === 'archive' && !existsSync(changeDir) && existsSync(join('openspec', 'changes', 'archive', change))) {
+  changeDir = join('openspec', 'changes', 'archive', change);
+}
+const yaml = join(changeDir, '.comet.yaml');
+let block = false;
+
+function check(desc, fn) {
+  try {
+    const result = fn();
+    if (result === true || result === undefined) green(`  [PASS] ${desc}`);
+    else throw new Error(String(result));
+  } catch (error) {
+    red(`  [FAIL] ${desc}`);
+    const message = error instanceof Error ? error.message : String(error);
+    if (message) for (const line of message.split(/\r?\n/)) red(`    ${line}`);
+    block = true;
+  }
+}
+
+function y(field) {
+  return fieldValue(yaml, field);
+}
+
+function preflight() {
+  if (!existsSync(changeDir)) {
+    red(`FATAL: change directory not found: ${changeDir}`);
+    process.exit(1);
+  }
+  if (!existsSync(yaml)) {
+    red(`FATAL: .comet.yaml not found in ${changeDir}`);
+    process.exit(1);
+  }
+  const validateScript = join(scriptDir, 'comet-yaml-validate.js');
+  if (existsSync(validateScript)) {
+    const result = runNode(validateScript, [change]);
+    if (result.status !== 0) {
+      process.stderr.write(result.stderr || '');
+      red('FATAL: .comet.yaml schema validation failed');
+      process.exit(1);
+    }
+  }
+}
+
+function tasksAllDone() {
+  const tasks = join(changeDir, 'tasks.md');
+  if (!existsSync(tasks)) throw new Error(`tasks.md is missing at ${tasks}\nNext: restore or create tasks.md for this change before leaving build.`);
+  const text = readFileSync(tasks, 'utf8');
+  if (!/- \[x\]/.test(text)) throw new Error("tasks.md has no completed tasks.\nNext: complete implementation tasks and mark them with '- [x]'.");
+  const unfinished = text.split(/\r?\n/).map((line, index) => ({ line, index: index + 1 })).filter(({ line }) => /- \[ \]/.test(line));
+  if (unfinished.length > 0) {
+    throw new Error(`Unfinished tasks:\n${unfinished.map(({ line, index }) => `${index}:${line}`).join('\n')}\nNext: complete or explicitly remove unfinished tasks, then mark tasks.md with '- [x]'.`);
+  }
+}
+
+function tasksHasAny() {
+  return existsSync(join(changeDir, 'tasks.md')) && /- \[/.test(readFileSync(join(changeDir, 'tasks.md'), 'utf8'));
+}
+
+function projectConfigValue(field) {
+  const local = y(field);
+  if (local && local !== 'null') return local;
+  for (const config of ['.comet.yaml', 'comet.yaml', '.comet.yml', 'comet.yml']) {
+    if (existsSync(config)) {
+      const value = fieldValue(config, field);
+      if (value && value !== 'null') return value;
+    }
+  }
+  return '';
+}
+
+function buildPasses() {
+  if (process.env.COMET_SKIP_BUILD === '1') return;
+  const configured = projectConfigValue('build_command');
+  if (configured) {
+    const result = runCommandString(configured);
+    if (result.status !== 0) throw new Error(`command failed: ${configured}`);
+    return;
+  }
+  if (existsSync('package.json') && /"build"/.test(readFileSync('package.json', 'utf8'))) {
+    const result = runCommand(['npm', 'run', 'build']);
+    if (result.status !== 0) throw new Error('npm run build failed');
+    return;
+  }
+  if (existsSync('pom.xml')) {
+    const result = existsSync('./mvnw') ? runCommand(['./mvnw', 'compile', '-q']) : runCommand(['mvn', 'compile', '-q']);
+    if (result.status !== 0) throw new Error('maven build failed');
+    return;
+  }
+  if (existsSync('Cargo.toml')) {
+    const result = runCommand(['cargo', 'build']);
+    if (result.status !== 0) throw new Error('cargo build failed');
+    return;
+  }
+  throw new Error('no build command found');
+}
+
+function verificationCommandPasses() {
+  if (process.env.COMET_SKIP_BUILD === '1') return;
+  const configured = projectConfigValue('verify_command');
+  if (configured) {
+    const result = runCommandString(configured);
+    if (result.status !== 0) throw new Error(`command failed: ${configured}`);
+    return;
+  }
+  buildPasses();
+}
+
+function sourceFiles() {
+  const files = [join(changeDir, 'proposal.md'), join(changeDir, 'design.md'), join(changeDir, 'tasks.md')];
+  const specsRoot = join(changeDir, 'specs');
+  if (existsSync(specsRoot)) {
+    const { readdirSync, statSync } = awaitFs;
+    function walk(dir) {
+      for (const entry of readdirSync(dir)) {
+        const p = join(dir, entry);
+        const stat = statSync(p);
+        if (stat.isDirectory()) walk(p);
+        else if (entry === 'spec.md') files.push(p);
+      }
+    }
+    walk(specsRoot);
+  }
+  return files;
+}
+import * as awaitFs from 'node:fs';
+
+function computeHandoffHash() {
+  let content = '';
+  for (const file of sourceFiles()) if (existsSync(file)) content += `path:${slash(file)}\nsha256:${hashFile(file)}\n`;
+  return sha256(content);
+}
+
+function designHandoffContextValid() {
+  const context = y('handoff_context');
+  const recordedHash = y('handoff_hash');
+  if (!context || context === 'null') throw new Error('handoff_context is missing from .comet.yaml\nNext: run node "$COMET_HANDOFF" <change> design --write before invoking Superpowers.');
+  if (!fileNonempty(context)) throw new Error(`handoff_context does not point to a non-empty file: ${context}\nNext: regenerate the design handoff with comet-handoff.js.`);
+  if (!/^[a-f0-9]{64}$/.test(recordedHash)) throw new Error(`handoff_hash is missing or invalid: ${recordedHash || 'null'}\nNext: regenerate the design handoff with comet-handoff.js.`);
+  const actualHash = computeHandoffHash();
+  if (actualHash !== recordedHash) throw new Error(`OpenSpec artifacts changed after handoff was generated.\nExpected handoff_hash: ${recordedHash}\nActual handoff_hash:   ${actualHash}\nNext: rerun comet-handoff.js so Superpowers receives the current OpenSpec context.`);
+  const markdown = context.replace(/\.json$/, '.md');
+  if (!fileNonempty(markdown)) throw new Error(`design handoff markdown is missing or empty: ${markdown}\nNext: regenerate the design handoff with comet-handoff.js.`);
+}
+
+function designHandoffMarkdownTraceable() {
+  const context = y('handoff_context');
+  if (!context || context === 'null') throw new Error('handoff_context is missing from .comet.yaml');
+  const markdown = context.replace(/\.json$/, '.md');
+  if (!fileNonempty(markdown)) throw new Error(`design handoff markdown is missing or empty: ${markdown}`);
+  const text = readFileSync(markdown, 'utf8');
+  const missing = [];
+  if (!/^Generated-by: comet-handoff\.js$/m.test(text)) missing.push('handoff markdown is missing Generated-by marker');
+  if (!/^- Mode: (compact|full)$/m.test(text)) missing.push('handoff markdown is missing Mode marker');
+  for (const file of sourceFiles()) {
+    if (!existsSync(file)) continue;
+    if (!text.includes(`- Source: ${slash(file)}`)) missing.push(`handoff markdown is missing source reference: ${slash(file)}`);
+    if (!text.includes(`- SHA256: ${hashFile(file)}`)) missing.push(`handoff markdown is missing current sha256 for: ${file}`);
+  }
+  if (missing.length) throw new Error(missing.join('\n'));
+}
+
+function frontmatterHas(file, field, expected) {
+  const text = readFileSync(file, 'utf8').replace(/^\uFEFF/, '');
+  const match = text.match(/^\s*---\r?\n([\s\S]*?)\r?\n---/);
+  if (!match) return false;
+  return new RegExp(`^${field}: ['\"]?${expected}['\"]?\\s*$`, 'm').test(match[1]);
+}
+
+function guardOpen() {
+  console.error('=== Guard: open → next ===');
+  check('proposal.md exists and non-empty', () => fileNonempty(join(changeDir, 'proposal.md')));
+  check('design.md exists and non-empty', () => fileNonempty(join(changeDir, 'design.md')));
+  check('tasks.md exists and non-empty', () => fileNonempty(join(changeDir, 'tasks.md')));
+  check('tasks.md has at least one task', tasksHasAny);
+}
+
+function guardDesign() {
+  console.error('=== Guard: design → build ===');
+  const designDoc = y('design_doc');
+  check('proposal.md exists', () => fileNonempty(join(changeDir, 'proposal.md')));
+  check('design.md exists', () => fileNonempty(join(changeDir, 'design.md')));
+  check('tasks.md exists', () => fileNonempty(join(changeDir, 'tasks.md')));
+  check('design handoff context exists', designHandoffContextValid);
+  check('design handoff markdown is traceable', designHandoffMarkdownTraceable);
+  if (designDoc && designDoc !== 'null') {
+    check(`Design Doc (${designDoc}) exists`, () => fileNonempty(designDoc));
+    check('Design Doc frontmatter links current change', () => frontmatterHas(designDoc, 'comet_change', change));
+    check('Design Doc declares technical design role', () => frontmatterHas(designDoc, 'role', 'technical-design'));
+    check('Design Doc declares OpenSpec as canonical spec', () => frontmatterHas(designDoc, 'canonical_spec', 'openspec'));
+  } else yellow('  [WARN] No design_doc recorded in .comet.yaml');
+}
+
+function guardBuild() {
+  console.error('=== Guard: build → verify ===');
+  check('isolation selected', () => ['branch', 'worktree'].includes(y('isolation')) || `isolation must be branch or worktree, got '${y('isolation') || 'null'}'\nNext: ask the user to choose branch or worktree, create the chosen isolation, then run:\n  node "$COMET_STATE" set ${change} isolation <branch|worktree>`);
+  check('build_mode selected', () => ['subagent-driven-development', 'executing-plans', 'direct'].includes(y('build_mode')) || `build_mode must be selected before leaving build, got '${y('build_mode') || 'null'}'\nNext: ask the user to choose an execution mode, then run:\n  node "$COMET_STATE" set ${change} build_mode <subagent-driven-development|executing-plans>`);
+  check('build_mode allowed for workflow', () => y('build_mode') !== 'direct' || ['hotfix', 'tweak'].includes(y('workflow')) || y('direct_override') === 'true' || 'build_mode=direct is only allowed for hotfix/tweak unless direct_override: true is recorded\nNext: choose executing-plans or subagent-driven-development, or stop and ask the user for an explicit direct override.');
+  check('tasks.md all tasks checked', tasksAllDone);
+  check('proposal.md exists', () => fileNonempty(join(changeDir, 'proposal.md')));
+  check('Build passes', buildPasses);
+}
+
+function guardVerify() {
+  console.error('=== Guard: verify → archive ===');
+  check('tasks.md all tasks checked', tasksAllDone);
+  check('Build passes', verificationCommandPasses);
+  check('verification_report exists', () => y('verification_report') && y('verification_report') !== 'null' && existsSync(y('verification_report')));
+  check('branch_status=handled', () => y('branch_status') === 'handled');
+}
+
+function guardArchive() {
+  console.error('=== Guard: archive completeness ===');
+  check('archived is true', () => y('archived') === 'true');
+  check('proposal.md exists', () => fileNonempty(join(changeDir, 'proposal.md')));
+  check('tasks.md all tasks checked', tasksAllDone);
+}
+
+function applyStateUpdate() {
+  const state = join(scriptDir, 'comet-state.js');
+  if (!existsSync(state)) {
+    red('FATAL: comet-state.js not found; cannot apply state transition');
+    process.exit(1);
+  }
+  const event = { open: 'open-complete', design: 'design-complete', build: 'build-complete', verify: 'verify-pass' }[phase];
+  if (event) {
+    const result = runNode(state, ['transition', change, event]);
+    if (result.status !== 0) {
+      process.stderr.write(result.stderr || '');
+      process.exit(result.status ?? 1);
+    }
+  }
+}
+
+if (!['open', 'design', 'build', 'verify', 'archive'].includes(phase)) {
+  red(`Unknown phase: ${phase}`);
+  console.error('Valid phases: open, design, build, verify, archive');
+  process.exit(1);
+}
+preflight();
+({ open: guardOpen, design: guardDesign, build: guardBuild, verify: guardVerify, archive: guardArchive }[phase])();
+if (block) {
+  console.error('');
+  red('BLOCKED — fix failing checks before proceeding to next phase');
+  process.exit(1);
+}
+console.error('');
+green('ALL CHECKS PASSED — ready for next phase');
+if (apply) {
+  applyStateUpdate();
+  const messages = {
+    open: `  [APPLY] .comet.yaml updated: phase=${y('phase')}`,
+    design: '  [APPLY] .comet.yaml updated: phase=build',
+    build: '  [APPLY] .comet.yaml updated: phase=verify, verify_result=pending',
+    verify: '  [APPLY] .comet.yaml updated: phase=archive, verify_result=pass',
+  };
+  if (messages[phase]) green(messages[phase]);
+}
diff --git a/assets/skills/comet/scripts/comet-guard.sh b/assets/skills/comet/scripts/comet-guard.sh
deleted file mode 100644
index 5e66873b..00000000
--- a/assets/skills/comet/scripts/comet-guard.sh
+++ /dev/null
@@ -1,596 +0,0 @@
-#!/bin/bash
-# Comet Phase Guard — validates exit conditions before phase transitions
-# Usage: comet-guard.sh <change-name> <current-phase> [--apply]
-# Phases: open, design, build, verify, archive
-# Exit 0 = all checks pass, exit 1 = blocked (reasons printed to stderr)
-# shellcheck disable=SC2329  # Functions called indirectly via check() dispatch
-
-set -euo pipefail
-
-COMET_BASH="${COMET_BASH:-${BASH:-bash}}"
-
-red() { echo -e "\033[31m$1\033[0m" >&2; }
-green() { echo -e "\033[32m$1\033[0m" >&2; }
-warn() { echo -e "\033[33m$1\033[0m" >&2; }
-
-# Input validation - prevent path traversal
-validate_change_name() {
-  local name="$1"
-  # Reject empty names
-  if [ -z "$name" ]; then
-    red "ERROR: Change name cannot be empty" >&2
-    exit 1
-  fi
-  # Only allow alphanumeric, hyphens, and underscores
-  if [[ ! "$name" =~ ^[a-zA-Z0-9_-]+$ ]]; then
-    red "ERROR: Invalid change name: '$name'" >&2
-    red "Valid characters: a-z, A-Z, 0-9, -, _" >&2
-    exit 1
-  fi
-  # Reject path traversal attempts
-  if [[ "$name" =~ \.\. ]]; then
-    red "ERROR: Change name cannot contain '..' (path traversal not allowed)" >&2
-    exit 1
-  fi
-}
-
-validate_change_name "$1"
-
-CHANGE="$1"
-PHASE="$2"
-APPLY=0
-SCRIPT_DIR="$(dirname "$(readlink -f "$0" 2>/dev/null || echo "$0")" 2>/dev/null || dirname "$0")"
-if [[ "${3:-}" == "--apply" ]]; then
-  APPLY=1
-fi
-CHANGE_DIR="openspec/changes/$CHANGE"
-if [ "$PHASE" = "archive" ] && [ ! -d "$CHANGE_DIR" ] && [ -d "openspec/changes/archive/$CHANGE" ]; then
-  CHANGE_DIR="openspec/changes/archive/$CHANGE"
-fi
-
-BLOCK=0
-check() {
-  local desc="$1"
-  shift
-  local output
-  if output=$("$@" 2>&1); then
-    green "  [PASS] $desc"
-  else
-    red "  [FAIL] $desc"
-    if [ -n "$output" ]; then
-      while IFS= read -r line; do
-        red "    $line"
-      done <<< "$output"
-    fi
-    BLOCK=1
-  fi
-}
-
-# --- Helper functions ---
-
-tasks_all_done() {
-  local tasks="$CHANGE_DIR/tasks.md"
-  if [ ! -f "$tasks" ]; then
-    echo "tasks.md is missing at $tasks" >&2
-    echo "Next: restore or create tasks.md for this change before leaving build." >&2
-    return 1
-  fi
-  if ! grep -q '\- \[x\]' "$tasks"; then
-    echo "tasks.md has no completed tasks." >&2
-    echo "Next: complete implementation tasks and mark them with '- [x]'." >&2
-    return 1
-  fi
-  if grep -q '\- \[ \]' "$tasks"; then
-    echo "Unfinished tasks:" >&2
-    grep -n '\- \[ \]' "$tasks" >&2 || true
-    echo "Next: complete or explicitly remove unfinished tasks, then mark tasks.md with '- [x]'." >&2
-    return 1
-  fi
-  return 0
-}
-
-tasks_has_any() {
-  local tasks="$CHANGE_DIR/tasks.md"
-  [ -f "$tasks" ] && grep -q '\- \[' "$tasks"
-}
-
-yaml_field_value() {
-  local field="$1"
-  local yaml="$CHANGE_DIR/.comet.yaml"
-  if [ -f "$yaml" ]; then
-    local value
-    value=$(grep "^${field}:" "$yaml" 2>/dev/null | sed "s/^${field}: *//" || true)
-    value=$(strip_inline_comment "$value")
-    strip_wrapping_quotes "$value"
-  fi
-}
-
-strip_inline_comment() {
-  local value="$1"
-  printf '%s\n' "$value" | awk -v squote="'" '
-    {
-      out = ""
-      quote = ""
-      for (i = 1; i <= length($0); i++) {
-        c = substr($0, i, 1)
-        if (quote == "") {
-          if (c == "\"" || c == squote) {
-            quote = c
-          } else if (c == "#" && (i == 1 || substr($0, i - 1, 1) ~ /[[:space:]]/)) {
-            sub(/[[:space:]]+$/, "", out)
-            print out
-            next
-          }
-        } else if (c == quote) {
-          quote = ""
-        }
-        out = out c
-      }
-      print out
-    }
-  '
-}
-
-strip_wrapping_quotes() {
-  local value="$1"
-  case "$value" in
-    \"*\")
-      printf '%s\n' "${value:1:${#value}-2}"
-      ;;
-    \'*\')
-      printf '%s\n' "${value:1:${#value}-2}"
-      ;;
-    *)
-      printf '%s\n' "$value"
-      ;;
-  esac
-}
-
-project_config_value() {
-  local field="$1"
-  local value
-
-  value=$(yaml_field_value "$field" 2>/dev/null || true)
-  if [ -n "$value" ] && [ "$value" != "null" ]; then
-    echo "$value"
-    return 0
-  fi
-
-  for config in ".comet.yaml" "comet.yaml" ".comet.yml" "comet.yml"; do
-    if [ -f "$config" ]; then
-      value=$(grep "^${field}:" "$config" 2>/dev/null | sed "s/^${field}: *//" || true)
-      value=$(strip_inline_comment "$value")
-      value=$(strip_wrapping_quotes "$value")
-      if [ -n "$value" ] && [ "$value" != "null" ]; then
-        echo "$value"
-        return 0
-      fi
-    fi
-  done
-}
-
-file_nonempty() {
-  [ -f "$1" ] && [ -s "$1" ]
-}
-
-is_windows_bash() {
-  case "$(uname -s 2>/dev/null || true)" in
-    MINGW*|MSYS*|CYGWIN*) return 0 ;;
-    *) return 1 ;;
-  esac
-}
-
-run_command_string() {
-  local command="$1"
-  echo "+ $command" >&2
-  "$COMET_BASH" -lc "$command"
-}
-
-hash_stream() {
-  if command -v sha256sum >/dev/null 2>&1; then
-    sha256sum | awk '{print $1}'
-  elif command -v shasum >/dev/null 2>&1; then
-    shasum -a 256 | awk '{print $1}'
-  else
-    echo "sha256sum or shasum is required" >&2
-    return 1
-  fi
-}
-
-hash_file() {
-  local file="$1"
-  if command -v sha256sum >/dev/null 2>&1; then
-    sha256sum "$file" | awk '{print $1}'
-  elif command -v shasum >/dev/null 2>&1; then
-    shasum -a 256 "$file" | awk '{print $1}'
-  else
-    echo "sha256sum or shasum is required" >&2
-    return 1
-  fi
-}
-
-handoff_source_files() {
-  printf '%s\n' "$CHANGE_DIR/proposal.md"
-  printf '%s\n' "$CHANGE_DIR/design.md"
-  printf '%s\n' "$CHANGE_DIR/tasks.md"
-  if [ -d "$CHANGE_DIR/specs" ]; then
-    find "$CHANGE_DIR/specs" -path '*/spec.md' -type f 2>/dev/null | sort
-  fi
-}
-
-compute_handoff_hash() {
-  handoff_source_files | while IFS= read -r file; do
-    if [ -f "$file" ]; then
-      printf 'path:%s\n' "$file"
-      printf 'sha256:%s\n' "$(hash_file "$file")"
-    fi
-  done | hash_stream
-}
-
-preflight() {
-
-  if [ ! -d "$CHANGE_DIR" ]; then
-    red "FATAL: change directory not found: $CHANGE_DIR"
-    exit 1
-  fi
-  if [ ! -f "$CHANGE_DIR/.comet.yaml" ]; then
-    red "FATAL: .comet.yaml not found in $CHANGE_DIR"
-    exit 1
-  fi
-
-  # Schema validation
-  local validate_script
-  validate_script="$SCRIPT_DIR/comet-yaml-validate.sh"
-  if [ -f "$validate_script" ]; then
-    if ! "$COMET_BASH" "$validate_script" "$CHANGE" 2>/dev/null; then
-      "$COMET_BASH" "$validate_script" "$CHANGE" || true
-      red "FATAL: .comet.yaml schema validation failed"
-      exit 1
-    fi
-  fi
-}
-
-build_passes() {
-  if [ "${COMET_SKIP_BUILD:-0}" = "1" ]; then
-    return 0
-  fi
-  local configured_build
-  configured_build=$(project_config_value "build_command" 2>/dev/null || true)
-  if [ -n "$configured_build" ]; then
-    run_command_string "$configured_build"
-    return $?
-  fi
-  if [ -f "package.json" ] && grep -q '"build"' "package.json"; then
-    npm run build
-    return $?
-  fi
-  if [ -f "pom.xml" ]; then
-    if [ -x "./mvnw" ]; then
-      ./mvnw compile -q
-    elif is_windows_bash && command -v mvn.cmd >/dev/null 2>&1; then
-      mvn.cmd compile -q
-    else
-      mvn compile -q
-    fi
-    return $?
-  fi
-  if [ -f "Cargo.toml" ]; then
-    cargo build
-    return $?
-  fi
-  return 1
-}
-
-verification_command_passes() {
-  if [ "${COMET_SKIP_BUILD:-0}" = "1" ]; then
-    return 0
-  fi
-  local configured_verify
-  configured_verify=$(project_config_value "verify_command" 2>/dev/null || true)
-  if [ -n "$configured_verify" ]; then
-    run_command_string "$configured_verify"
-    return $?
-  fi
-  build_passes
-}
-
-isolation_selected() {
-  local isolation
-  isolation=$(yaml_field_value "isolation" 2>/dev/null || true)
-  case "$isolation" in
-    branch|worktree) return 0 ;;
-    *)
-      echo "isolation must be branch or worktree, got '${isolation:-null}'" >&2
-      echo "Next: ask the user to choose branch or worktree, create the chosen isolation, then run:" >&2
-      echo "  \"\$COMET_BASH\" \"\$COMET_STATE\" set $CHANGE isolation <branch|worktree>" >&2
-      return 1
-      ;;
-  esac
-}
-
-build_mode_selected() {
-  local build_mode
-  build_mode=$(yaml_field_value "build_mode" 2>/dev/null || true)
-  case "$build_mode" in
-    subagent-driven-development|executing-plans|direct) return 0 ;;
-    *)
-      echo "build_mode must be selected before leaving build, got '${build_mode:-null}'" >&2
-      echo "Next: ask the user to choose an execution mode, then run:" >&2
-      echo "  \"\$COMET_BASH\" \"\$COMET_STATE\" set $CHANGE build_mode <subagent-driven-development|executing-plans>" >&2
-      return 1
-      ;;
-  esac
-}
-
-build_mode_allowed_for_workflow() {
-  local workflow build_mode direct_override
-  workflow=$(yaml_field_value "workflow" 2>/dev/null || true)
-  build_mode=$(yaml_field_value "build_mode" 2>/dev/null || true)
-  direct_override=$(yaml_field_value "direct_override" 2>/dev/null || true)
-
-  if [ "$build_mode" != "direct" ]; then
-    return 0
-  fi
-  case "$workflow" in
-    hotfix|tweak) return 0 ;;
-    *)
-      if [ "$direct_override" = "true" ]; then
-        return 0
-      fi
-      echo "build_mode=direct is only allowed for hotfix/tweak unless direct_override: true is recorded" >&2
-      echo "Next: choose executing-plans or subagent-driven-development, or stop and ask the user for an explicit direct override." >&2
-      return 1
-      ;;
-  esac
-}
-
-verify_result_is_pass() {
-  local result
-  result=$(yaml_field_value "verify_result" 2>/dev/null || true)
-  [ "$result" = "pass" ]
-}
-
-verification_report_exists() {
-  local report
-  report=$(yaml_field_value "verification_report" 2>/dev/null || true)
-  [ -n "$report" ] && [ "$report" != "null" ] && [ -f "$report" ]
-}
-
-branch_status_handled() {
-  local status
-  status=$(yaml_field_value "branch_status" 2>/dev/null || true)
-  [ "$status" = "handled" ]
-}
-
-design_handoff_context_valid() {
-  local context recorded_hash actual_hash markdown
-  context=$(yaml_field_value "handoff_context" 2>/dev/null || true)
-  recorded_hash=$(yaml_field_value "handoff_hash" 2>/dev/null || true)
-
-  if [ -z "$context" ] || [ "$context" = "null" ]; then
-    echo "handoff_context is missing from .comet.yaml" >&2
-    echo "Next: run \"\$COMET_BASH\" \"\$COMET_HANDOFF\" $CHANGE design --write before invoking Superpowers." >&2
-    return 1
-  fi
-  if [ ! -s "$context" ]; then
-    echo "handoff_context does not point to a non-empty file: $context" >&2
-    echo "Next: regenerate the design handoff with comet-handoff.sh." >&2
-    return 1
-  fi
-  if [[ ! "$recorded_hash" =~ ^[a-f0-9]{64}$ ]]; then
-    echo "handoff_hash is missing or invalid: ${recorded_hash:-null}" >&2
-    echo "Next: regenerate the design handoff with comet-handoff.sh." >&2
-    return 1
-  fi
-
-  actual_hash=$(compute_handoff_hash)
-  if [ "$actual_hash" != "$recorded_hash" ]; then
-    echo "OpenSpec artifacts changed after handoff was generated." >&2
-    echo "Expected handoff_hash: $recorded_hash" >&2
-    echo "Actual handoff_hash:   $actual_hash" >&2
-    echo "Next: rerun comet-handoff.sh so Superpowers receives the current OpenSpec context." >&2
-    return 1
-  fi
-
-  markdown="${context%.json}.md"
-  if [ ! -s "$markdown" ]; then
-    echo "design handoff markdown is missing or empty: $markdown" >&2
-    echo "Next: regenerate the design handoff with comet-handoff.sh." >&2
-    return 1
-  fi
-}
-
-design_handoff_markdown_traceable() {
-  local context markdown missing=0
-  context=$(yaml_field_value "handoff_context" 2>/dev/null || true)
-  if [ -z "$context" ] || [ "$context" = "null" ]; then
-    echo "handoff_context is missing from .comet.yaml" >&2
-    return 1
-  fi
-  markdown="${context%.json}.md"
-  if [ ! -s "$markdown" ]; then
-    echo "design handoff markdown is missing or empty: $markdown" >&2
-    return 1
-  fi
-  grep -q '^Generated-by: comet-handoff\.sh$' "$markdown" || {
-    echo "handoff markdown is missing Generated-by marker" >&2
-    missing=1
-  }
-  grep -Eq '^- Mode: (compact|full)$' "$markdown" || {
-    echo "handoff markdown is missing Mode marker" >&2
-    missing=1
-  }
-  handoff_source_files | while IFS= read -r file; do
-    [ -f "$file" ] || continue
-    if ! grep -q "^- Source: $file$" "$markdown"; then
-      echo "handoff markdown is missing source reference: $file" >&2
-      exit 2
-    fi
-    if ! grep -q "^- SHA256: $(hash_file "$file")$" "$markdown"; then
-      echo "handoff markdown is missing current sha256 for: $file" >&2
-      exit 2
-    fi
-  done || missing=1
-
-  [ "$missing" -eq 0 ]
-}
-
-design_doc_frontmatter_has() {
-  local design_doc="$1"
-  local field="$2"
-  local expected="$3"
-  awk '
-    {
-      line = $0
-      sub(/^\357\273\277/, "", line)
-    }
-    !in_fm && line == "---" { in_fm = 1; next }
-    in_fm && line == "---" { exit }
-    in_fm { print line }
-  ' "$design_doc" | grep -Eq "^${field}: ['\"]?${expected}['\"]?[[:space:]]*$"
-}
-
-design_doc_links_current_change() {
-  local design_doc
-  design_doc=$(yaml_field_value "design_doc" 2>/dev/null || true)
-  if [ -z "$design_doc" ] || [ "$design_doc" = "null" ] || [ ! -s "$design_doc" ]; then
-    echo "design_doc must point to an existing Superpowers Design Doc before leaving design." >&2
-    return 1
-  fi
-  design_doc_frontmatter_has "$design_doc" "comet_change" "$CHANGE"
-}
-
-design_doc_declares_technical_role() {
-  local design_doc
-  design_doc=$(yaml_field_value "design_doc" 2>/dev/null || true)
-  [ -n "$design_doc" ] && [ "$design_doc" != "null" ] && [ -s "$design_doc" ] &&
-    design_doc_frontmatter_has "$design_doc" "role" "technical-design"
-}
-
-design_doc_declares_canonical_spec() {
-  local design_doc
-  design_doc=$(yaml_field_value "design_doc" 2>/dev/null || true)
-  [ -n "$design_doc" ] && [ "$design_doc" != "null" ] && [ -s "$design_doc" ] &&
-    design_doc_frontmatter_has "$design_doc" "canonical_spec" "openspec"
-}
-
-archived_is_true() {
-  local val
-  val=$(yaml_field_value "archived" 2>/dev/null || true)
-  [ "$val" = "true" ]
-}
-
-# --- Phase-specific checks ---
-
-guard_open() {
-  echo "=== Guard: open → next ===" >&2
-
-  check "proposal.md exists and non-empty" file_nonempty "$CHANGE_DIR/proposal.md"
-  check "design.md exists and non-empty" file_nonempty "$CHANGE_DIR/design.md"
-  check "tasks.md exists and non-empty" file_nonempty "$CHANGE_DIR/tasks.md"
-  check "tasks.md has at least one task" tasks_has_any
-}
-
-guard_design() {
-  echo "=== Guard: design → build ===" >&2
-
-  local design_doc
-  design_doc=$(yaml_field_value "design_doc" 2>/dev/null || true)
-
-  check "proposal.md exists" file_nonempty "$CHANGE_DIR/proposal.md"
-  check "design.md exists" file_nonempty "$CHANGE_DIR/design.md"
-  check "tasks.md exists" file_nonempty "$CHANGE_DIR/tasks.md"
-  check "design handoff context exists" design_handoff_context_valid
-  check "design handoff markdown is traceable" design_handoff_markdown_traceable
-
-  if [ -n "$design_doc" ] && [ "$design_doc" != "null" ]; then
-    check "Design Doc ($design_doc) exists" file_nonempty "$design_doc"
-    check "Design Doc frontmatter links current change" design_doc_links_current_change
-    check "Design Doc declares technical design role" design_doc_declares_technical_role
-    check "Design Doc declares OpenSpec as canonical spec" design_doc_declares_canonical_spec
-  else
-    warn "  [WARN] No design_doc recorded in .comet.yaml"
-  fi
-}
-
-guard_build() {
-  echo "=== Guard: build → verify ===" >&2
-
-  check "isolation selected" isolation_selected
-  check "build_mode selected" build_mode_selected
-  check "build_mode allowed for workflow" build_mode_allowed_for_workflow
-  check "tasks.md all tasks checked" tasks_all_done
-  check "proposal.md exists" file_nonempty "$CHANGE_DIR/proposal.md"
-  check "Build passes" build_passes
-}
-
-guard_verify() {
-  echo "=== Guard: verify → archive ===" >&2
-
-  check "tasks.md all tasks checked" tasks_all_done
-  check "Build passes" verification_command_passes
-  check "verification_report exists" verification_report_exists
-  check "branch_status=handled" branch_status_handled
-}
-
-guard_archive() {
-  echo "=== Guard: archive completeness ===" >&2
-
-  check "archived is true" archived_is_true
-  check "proposal.md exists" file_nonempty "$CHANGE_DIR/proposal.md"
-  check "tasks.md all tasks checked" tasks_all_done
-}
-
-apply_state_update() {
-  local state_sh="$SCRIPT_DIR/comet-state.sh"
-  local p="$1"
-
-  if [ -f "$state_sh" ]; then
-    case "$p" in
-      open)   "$COMET_BASH" "$state_sh" transition "$CHANGE" open-complete ;;
-      design) "$COMET_BASH" "$state_sh" transition "$CHANGE" design-complete ;;
-      build)  "$COMET_BASH" "$state_sh" transition "$CHANGE" build-complete ;;
-      verify) "$COMET_BASH" "$state_sh" transition "$CHANGE" verify-pass ;;
-    esac
-  else
-    red "FATAL: comet-state.sh not found; cannot apply state transition"
-    exit 1
-  fi
-}
-
-# --- Main ---
-
-case "$PHASE" in
-  open)     preflight ; guard_open ;;
-  design)   preflight ; guard_design ;;
-  build)    preflight ; guard_build ;;
-  verify)   preflight ; guard_verify ;;
-  archive)  preflight ; guard_archive ;;
-  *)
-    red "Unknown phase: $PHASE"
-    echo "Valid phases: open, design, build, verify, archive" >&2
-    exit 1
-    ;;
-esac
-
-if [ "$BLOCK" -eq 1 ]; then
-  echo "" >&2
-  red "BLOCKED — fix failing checks before proceeding to next phase"
-  exit 1
-else
-  echo "" >&2
-  green "ALL CHECKS PASSED — ready for next phase"
-  if [ "$APPLY" -eq 1 ]; then
-    apply_state_update "$PHASE"
-    case "$PHASE" in
-      open)
-        new_phase=$(yaml_field_value "phase")
-        green "  [APPLY] .comet.yaml updated: phase=$new_phase"
-        ;;
-      design) green "  [APPLY] .comet.yaml updated: phase=build" ;;
-      build)  green "  [APPLY] .comet.yaml updated: phase=verify, verify_result=pending" ;;
-      verify) green "  [APPLY] .comet.yaml updated: phase=archive, verify_result=pass" ;;
-    esac
-  fi
-  exit 0
-fi
diff --git a/assets/skills/comet/scripts/comet-handoff.js b/assets/skills/comet/scripts/comet-handoff.js
new file mode 100644
index 00000000..49a6514a
--- /dev/null
+++ b/assets/skills/comet/scripts/comet-handoff.js
@@ -0,0 +1,109 @@
+#!/usr/bin/env node
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { ensureDir, fieldValue, fileNonempty, green, hashFile, runNode, scriptDir, sha256, slash, validateChangeName } from './comet-lib.js';
+
+function error(message) {
+  console.error(`\u001b[31m${message}\u001b[0m`);
+  process.exit(1);
+}
+
+function walkSpecFiles(dir) {
+  if (!existsSync(dir)) return [];
+  const { readdirSync, statSync } = awaitFs;
+  const out = [];
+  function walk(current) {
+    for (const entry of readdirSync(current)) {
+      const p = join(current, entry);
+      const stat = statSync(p);
+      if (stat.isDirectory()) walk(p);
+      else if (entry === 'spec.md') out.push(p);
+    }
+  }
+  walk(dir);
+  return out.sort();
+}
+
+import * as awaitFs from 'node:fs';
+
+function sourceFiles(changeDir) {
+  return [join(changeDir, 'proposal.md'), join(changeDir, 'design.md'), join(changeDir, 'tasks.md'), ...walkSpecFiles(join(changeDir, 'specs'))];
+}
+
+function computeContextHash(files) {
+  let content = '';
+  for (const file of files) {
+    if (!existsSync(file)) continue;
+    content += `path:${slash(file)}\nsha256:${hashFile(file)}\n`;
+  }
+  return sha256(content);
+}
+
+function writeMarkdown(output, files, change, mode, contextHash) {
+  const chunks = [
+    '# Comet Design Handoff',
+    '',
+    `- Change: ${change}`,
+    '- Phase: design',
+    `- Mode: ${mode}`,
+    `- Context hash: ${contextHash}`,
+    '',
+    'Generated-by: comet-handoff.js',
+    '',
+    'OpenSpec remains the canonical capability spec. This handoff is a deterministic, source-traceable context pack, not an agent-authored summary.',
+    '',
+  ];
+  for (const file of files) {
+    if (!existsSync(file)) continue;
+    const text = readFileSync(file, 'utf8');
+    const lines = text.split(/\r?\n/);
+    chunks.push(`## ${slash(file)}`, '', `- Source: ${slash(file)}`, `- Lines: 1-${lines.length}`, `- SHA256: ${hashFile(file)}`, '');
+    if (mode === 'full' || lines.length <= 80) chunks.push('```md', text.replace(/\s*$/, ''), '```');
+    else chunks.push('[TRUNCATED]', '', '```md', lines.slice(0, 80).join('\n'), '```', '', `Full source: ${slash(file)}`);
+    chunks.push('');
+  }
+  writeFileSync(output, `${chunks.join('\n')}\n`);
+}
+
+function writeJson(output, files, change, mode, contextHash) {
+  const body = {
+    change,
+    phase: 'design',
+    mode,
+    canonical_spec: 'openspec',
+    generated_by: 'comet-handoff.js',
+    context_hash: contextHash,
+    files: files.filter((file) => existsSync(file)).map((file) => ({ path: slash(file), sha256: hashFile(file) })),
+  };
+  writeFileSync(output, `${JSON.stringify(body, null, 2)}\n`);
+}
+
+const [change, phase, modeArg, fullFlag] = process.argv.slice(2);
+validateChangeName(change);
+if (phase !== 'design' || modeArg !== '--write' || (fullFlag && fullFlag !== '--full')) error('Usage: comet-handoff.js <change-name> design --write [--full]');
+const handoffMode = fullFlag === '--full' ? 'full' : 'compact';
+const changeDir = join('openspec', 'changes', change);
+const yaml = join(changeDir, '.comet.yaml');
+if (!existsSync(changeDir)) error(`ERROR: change directory not found: ${changeDir}`);
+if (!existsSync(yaml)) error(`ERROR: .comet.yaml not found at ${yaml}`);
+if (fieldValue(yaml, 'phase') !== 'design') error('ERROR: design handoff requires phase: design');
+for (const required of ['proposal.md', 'design.md', 'tasks.md']) {
+  if (!fileNonempty(join(changeDir, required))) error(`ERROR: required OpenSpec artifact missing or empty: ${join(changeDir, required)}`);
+}
+const handoffDir = join(changeDir, '.comet', 'handoff');
+const contextJson = slash(join(handoffDir, 'design-context.json'));
+const contextMd = slash(join(handoffDir, 'design-context.md'));
+ensureDir(handoffDir);
+const files = sourceFiles(changeDir);
+const contextHash = computeContextHash(files);
+writeMarkdown(contextMd, files, change, handoffMode, contextHash);
+writeJson(contextJson, files, change, handoffMode, contextHash);
+const stateScript = join(scriptDir, 'comet-state.js');
+if (!existsSync(stateScript)) error('ERROR: comet-state.js not found; cannot record handoff fields');
+let result = runNode(stateScript, ['set', change, 'handoff_context', contextJson]);
+if (result.status !== 0) process.exit(result.status ?? 1);
+result = runNode(stateScript, ['set', change, 'handoff_hash', contextHash]);
+if (result.status !== 0) process.exit(result.status ?? 1);
+green(`[HANDOFF] wrote ${contextJson}`);
+green(`[HANDOFF] wrote ${contextMd}`);
+green(`[HANDOFF] handoff_hash=${contextHash}`);
diff --git a/assets/skills/comet/scripts/comet-handoff.sh b/assets/skills/comet/scripts/comet-handoff.sh
deleted file mode 100644
index b2ee6739..00000000
--- a/assets/skills/comet/scripts/comet-handoff.sh
+++ /dev/null
@@ -1,263 +0,0 @@
-#!/bin/bash
-# Comet Handoff — creates machine-owned context packages between phases
-# Usage: comet-handoff.sh <change-name> design --write [--full]
-
-set -euo pipefail
-
-COMET_BASH="${COMET_BASH:-${BASH:-bash}}"
-
-red() { echo -e "\033[31m$1\033[0m" >&2; }
-green() { echo -e "\033[32m$1\033[0m" >&2; }
-
-validate_change_name() {
-  local name="$1"
-  if [ -z "$name" ]; then
-    red "ERROR: Change name cannot be empty"
-    exit 1
-  fi
-  if [[ ! "$name" =~ ^[a-zA-Z0-9_-]+$ ]]; then
-    red "ERROR: Invalid change name: '$name'"
-    red "Valid characters: a-z, A-Z, 0-9, -, _"
-    exit 1
-  fi
-  if [[ "$name" =~ \.\. ]]; then
-    red "ERROR: Change name cannot contain '..' (path traversal not allowed)"
-    exit 1
-  fi
-}
-
-strip_wrapping_quotes() {
-  local value="$1"
-  case "$value" in
-    \"*\") printf '%s\n' "${value:1:${#value}-2}" ;;
-    \'*\') printf '%s\n' "${value:1:${#value}-2}" ;;
-    *) printf '%s\n' "$value" ;;
-  esac
-}
-
-strip_inline_comment() {
-  local value="$1"
-  printf '%s\n' "$value" | awk -v squote="'" '
-    {
-      out = ""
-      quote = ""
-      for (i = 1; i <= length($0); i++) {
-        c = substr($0, i, 1)
-        if (quote == "") {
-          if (c == "\"" || c == squote) {
-            quote = c
-          } else if (c == "#" && (i == 1 || substr($0, i - 1, 1) ~ /[[:space:]]/)) {
-            sub(/[[:space:]]+$/, "", out)
-            print out
-            next
-          }
-        } else if (c == quote) {
-          quote = ""
-        }
-        out = out c
-      }
-      print out
-    }
-  '
-}
-
-yaml_field_value() {
-  local field="$1"
-  local yaml="$CHANGE_DIR/.comet.yaml"
-  local value
-  value=$(grep "^${field}:" "$yaml" 2>/dev/null | sed "s/^${field}: *//" || true)
-  value=$(strip_inline_comment "$value")
-  strip_wrapping_quotes "$value"
-}
-
-hash_stream() {
-  if command -v sha256sum >/dev/null 2>&1; then
-    sha256sum | awk '{print $1}'
-  elif command -v shasum >/dev/null 2>&1; then
-    shasum -a 256 | awk '{print $1}'
-  else
-    red "ERROR: sha256sum or shasum is required"
-    exit 1
-  fi
-}
-
-hash_file() {
-  local file="$1"
-  if command -v sha256sum >/dev/null 2>&1; then
-    sha256sum "$file" | awk '{print $1}'
-  elif command -v shasum >/dev/null 2>&1; then
-    shasum -a 256 "$file" | awk '{print $1}'
-  else
-    red "ERROR: sha256sum or shasum is required"
-    exit 1
-  fi
-}
-
-source_files() {
-  printf '%s\n' "$CHANGE_DIR/proposal.md"
-  printf '%s\n' "$CHANGE_DIR/design.md"
-  printf '%s\n' "$CHANGE_DIR/tasks.md"
-  if [ -d "$CHANGE_DIR/specs" ]; then
-    find "$CHANGE_DIR/specs" -path '*/spec.md' -type f 2>/dev/null | sort
-  fi
-}
-
-compute_context_hash() {
-  source_files | while IFS= read -r file; do
-    if [ -f "$file" ]; then
-      printf 'path:%s\n' "$file"
-      printf 'sha256:%s\n' "$(hash_file "$file")"
-    fi
-  done | hash_stream
-}
-
-json_escape() {
-  printf '%s' "$1" | sed 's/\\/\\\\/g; s/"/\\"/g'
-}
-
-file_line_count() {
-  local file="$1"
-  wc -l < "$file" | tr -d ' '
-}
-
-write_file_excerpt() {
-  local file="$1"
-  local max_lines="$2"
-  local total_lines
-  total_lines=$(file_line_count "$file")
-
-  echo "## $file"
-  echo ""
-  echo "- Source: $file"
-  echo "- Lines: 1-$total_lines"
-  echo "- SHA256: $(hash_file "$file")"
-  echo ""
-
-  if [ "$HANDOFF_MODE" = "full" ] || [ "$total_lines" -le "$max_lines" ]; then
-    echo '```md'
-    cat "$file"
-    echo '```'
-  else
-    echo "[TRUNCATED]"
-    echo ""
-    echo '```md'
-    sed -n "1,${max_lines}p" "$file"
-    echo '```'
-    echo ""
-    echo "Full source: $file"
-  fi
-  echo ""
-}
-
-write_markdown_context() {
-  local output="$1"
-  {
-    echo "# Comet Design Handoff"
-    echo ""
-    echo "- Change: $CHANGE"
-    echo "- Phase: design"
-    echo "- Mode: $HANDOFF_MODE"
-    echo "- Context hash: $CONTEXT_HASH"
-    echo ""
-    echo "Generated-by: comet-handoff.sh"
-    echo ""
-    echo "OpenSpec remains the canonical capability spec. This handoff is a deterministic, source-traceable context pack, not an agent-authored summary."
-    echo ""
-    source_files | while IFS= read -r file; do
-      [ -f "$file" ] || continue
-      write_file_excerpt "$file" 80
-    done
-  } > "$output"
-}
-
-write_json_context() {
-  local output="$1"
-  {
-    echo "{"
-    echo "  \"change\": \"$(json_escape "$CHANGE")\","
-    echo "  \"phase\": \"design\","
-    echo "  \"mode\": \"$HANDOFF_MODE\","
-    echo "  \"canonical_spec\": \"openspec\","
-    echo "  \"generated_by\": \"comet-handoff.sh\","
-    echo "  \"context_hash\": \"$CONTEXT_HASH\","
-    echo "  \"files\": ["
-    local first=1
-    while IFS= read -r file; do
-      [ -f "$file" ] || continue
-      if [ "$first" -eq 0 ]; then
-        echo ","
-      fi
-      first=0
-      printf '    { "path": "%s", "sha256": "%s" }' "$(json_escape "$file")" "$(hash_file "$file")"
-    done < <(source_files)
-    echo ""
-    echo "  ]"
-    echo "}"
-  } > "$output"
-}
-
-CHANGE="${1:-}"
-PHASE="${2:-}"
-MODE="${3:-}"
-FULL_FLAG="${4:-}"
-
-validate_change_name "$CHANGE"
-
-if [ "$PHASE" != "design" ] || [ "$MODE" != "--write" ]; then
-  red "Usage: comet-handoff.sh <change-name> design --write [--full]"
-  exit 1
-fi
-case "$FULL_FLAG" in
-  "") HANDOFF_MODE="compact" ;;
-  --full) HANDOFF_MODE="full" ;;
-  *)
-    red "Usage: comet-handoff.sh <change-name> design --write [--full]"
-    exit 1
-    ;;
-esac
-
-CHANGE_DIR="openspec/changes/$CHANGE"
-YAML="$CHANGE_DIR/.comet.yaml"
-SCRIPT_DIR="$(dirname "$(readlink -f "$0" 2>/dev/null || echo "$0")" 2>/dev/null || dirname "$0")"
-STATE_SH="$SCRIPT_DIR/comet-state.sh"
-
-if [ ! -d "$CHANGE_DIR" ]; then
-  red "ERROR: change directory not found: $CHANGE_DIR"
-  exit 1
-fi
-if [ ! -f "$YAML" ]; then
-  red "ERROR: .comet.yaml not found at $YAML"
-  exit 1
-fi
-if [ "$(yaml_field_value phase)" != "design" ]; then
-  red "ERROR: design handoff requires phase: design"
-  exit 1
-fi
-
-for required in proposal.md design.md tasks.md; do
-  if [ ! -s "$CHANGE_DIR/$required" ]; then
-    red "ERROR: required OpenSpec artifact missing or empty: $CHANGE_DIR/$required"
-    exit 1
-  fi
-done
-
-HANDOFF_DIR="$CHANGE_DIR/.comet/handoff"
-CONTEXT_JSON="$HANDOFF_DIR/design-context.json"
-CONTEXT_MD="$HANDOFF_DIR/design-context.md"
-mkdir -p "$HANDOFF_DIR"
-
-CONTEXT_HASH="$(compute_context_hash)"
-write_markdown_context "$CONTEXT_MD"
-write_json_context "$CONTEXT_JSON"
-
-if [ -x "$STATE_SH" ] || [ -f "$STATE_SH" ]; then
-  "$COMET_BASH" "$STATE_SH" set "$CHANGE" handoff_context "$CONTEXT_JSON" >/dev/null
-  "$COMET_BASH" "$STATE_SH" set "$CHANGE" handoff_hash "$CONTEXT_HASH" >/dev/null
-else
-  red "ERROR: comet-state.sh not found; cannot record handoff fields"
-  exit 1
-fi
-
-green "[HANDOFF] wrote $CONTEXT_JSON"
-green "[HANDOFF] wrote $CONTEXT_MD"
-green "[HANDOFF] handoff_hash=$CONTEXT_HASH"
diff --git a/assets/skills/comet/scripts/comet-lib.js b/assets/skills/comet/scripts/comet-lib.js
new file mode 100644
index 00000000..f2267e5d
--- /dev/null
+++ b/assets/skills/comet/scripts/comet-lib.js
@@ -0,0 +1,212 @@
+#!/usr/bin/env node
+import { createHash } from 'node:crypto';
+import { existsSync, mkdirSync, readFileSync, statSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { spawnSync } from 'node:child_process';
+
+export const scriptDir = dirname(fileURLToPath(import.meta.url));
+
+export const FIELD_ORDER = [
+  'workflow',
+  'phase',
+  'build_mode',
+  'build_pause',
+  'isolation',
+  'verify_mode',
+  'base_ref',
+  'design_doc',
+  'plan',
+  'verify_result',
+  'verification_report',
+  'branch_status',
+  'created_at',
+  'verified_at',
+  'archived',
+  'direct_override',
+  'build_command',
+  'verify_command',
+  'handoff_context',
+  'handoff_hash',
+];
+
+export const KNOWN_KEYS = new Set(FIELD_ORDER);
+
+export function color(code, message) {
+  return `\u001b[${code}m${message}\u001b[0m`;
+}
+
+export function red(message) {
+  console.error(color(31, message));
+}
+
+export function green(message) {
+  console.error(color(32, message));
+}
+
+export function yellow(message) {
+  console.error(color(33, message));
+}
+
+export function fail(message, prefix = 'ERROR') {
+  red(`${prefix}: ${message}`);
+  process.exit(1);
+}
+
+export function validateChangeName(name, prefix = 'ERROR') {
+  if (!name) fail('Change name cannot be empty', prefix);
+  if (!/^[a-zA-Z0-9_-]+$/.test(name)) {
+    red(`${prefix}: Invalid change name: '${name}'`);
+    red('Valid characters: a-z, A-Z, 0-9, -, _');
+    process.exit(1);
+  }
+  if (name.includes('..')) fail("Change name cannot contain '..' (path traversal not allowed)", prefix);
+}
+
+export function validateEnum(value, validValues) {
+  if (validValues.includes(value)) return;
+  red(`ERROR: Invalid value: '${value}'`);
+  red(`Valid values: ${validValues.join(' ')}`);
+  process.exit(1);
+}
+
+export function stripInlineComment(value) {
+  let out = '';
+  let quote = '';
+  for (let i = 0; i < value.length; i += 1) {
+    const c = value[i];
+    if (!quote) {
+      if (c === '"' || c === "'") quote = c;
+      else if (c === '#' && (i === 0 || /\s/.test(value[i - 1]))) return out.trimEnd();
+    } else if (c === quote) {
+      quote = '';
+    }
+    out += c;
+  }
+  return out;
+}
+
+export function stripWrappingQuotes(value) {
+  if (value.length >= 2) {
+    const first = value[0];
+    const last = value[value.length - 1];
+    if (first === '"' && last === '"') {
+      try {
+        return JSON.parse(value);
+      } catch {
+        return value.slice(1, -1);
+      }
+    }
+    if (first === "'" && last === "'") return value.slice(1, -1);
+  }
+  return value;
+}
+
+export function parseYamlLines(file) {
+  const text = readFileSync(file, 'utf8');
+  const data = {};
+  const keys = [];
+  for (const line of text.split(/\r?\n/)) {
+    const match = line.match(/^([^\s:#][^:]*):\s*(.*)$/);
+    if (!match) continue;
+    const key = match[1].trim();
+    const value = stripWrappingQuotes(stripInlineComment(match[2] ?? ''));
+    data[key] = value;
+    keys.push(key);
+  }
+  return { data, keys, text };
+}
+
+export function fieldValue(file, field) {
+  if (!existsSync(file)) return '';
+  return parseYamlLines(file).data[field] ?? '';
+}
+
+function formatYamlValue(value) {
+  const stringValue = String(value);
+  if (stringValue === '') return '';
+  if (/^[A-Za-z0-9_./:@\\-]+$/.test(stringValue)) return stringValue;
+  return JSON.stringify(stringValue);
+}
+
+export function writeYamlData(file, data) {
+  const lines = [];
+  for (const key of FIELD_ORDER) {
+    if (Object.prototype.hasOwnProperty.call(data, key)) lines.push(`${key}: ${formatYamlValue(data[key])}`);
+  }
+  for (const key of Object.keys(data)) {
+    if (!FIELD_ORDER.includes(key)) lines.push(`${key}: ${formatYamlValue(data[key])}`);
+  }
+  writeFileSync(file, `${lines.join('\n')}\n`);
+}
+
+export function setYamlField(file, field, value) {
+  const { data } = parseYamlLines(file);
+  data[field] = String(value);
+  writeYamlData(file, data);
+}
+
+export function fileNonempty(file) {
+  try {
+    return statSync(file).isFile() && statSync(file).size > 0;
+  } catch {
+    return false;
+  }
+}
+
+export function changeDirFor(changeName) {
+  const active = join('openspec', 'changes', changeName);
+  const archived = join('openspec', 'changes', 'archive', changeName);
+  if (existsSync(active)) return active;
+  if (existsSync(archived)) return archived;
+  return active;
+}
+
+export function yamlFileFor(changeName) {
+  return join(changeDirFor(changeName), '.comet.yaml');
+}
+
+export function today() {
+  return new Date().toISOString().slice(0, 10);
+}
+
+export function git(args) {
+  return spawnSync('git', args, { encoding: 'utf8' });
+}
+
+export function currentHeadOrNull() {
+  const verify = git(['rev-parse', '--verify', 'HEAD']);
+  if (verify.status !== 0) return 'null';
+  const head = git(['rev-parse', 'HEAD']);
+  return head.status === 0 ? head.stdout.trim() : 'null';
+}
+
+export function sha256(content) {
+  return createHash('sha256').update(content).digest('hex');
+}
+
+export function hashFile(file) {
+  return sha256(readFileSync(file));
+}
+
+export function ensureDir(dir) {
+  mkdirSync(dir, { recursive: true });
+}
+
+export function runNode(script, args, options = {}) {
+  return spawnSync(process.execPath, [script, ...args], { encoding: 'utf8', stdio: 'pipe', ...options });
+}
+
+export function runCommandString(command, options = {}) {
+  console.error(`+ ${command}`);
+  return spawnSync(command, { encoding: 'utf8', stdio: 'inherit', shell: true, ...options });
+}
+
+export function runCommand(argv, options = {}) {
+  const [command, ...args] = argv;
+  return spawnSync(command, args, { encoding: 'utf8', stdio: 'inherit', shell: process.platform === 'win32', ...options });
+}
+
+export function slash(file) {
+  return file.replace(/\\/g, '/');
+}
diff --git a/assets/skills/comet/scripts/comet-state.js b/assets/skills/comet/scripts/comet-state.js
new file mode 100644
index 00000000..e23d410d
--- /dev/null
+++ b/assets/skills/comet/scripts/comet-state.js
@@ -0,0 +1,384 @@
+#!/usr/bin/env node
+import { existsSync, mkdirSync, readdirSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import {
+  changeDirFor,
+  currentHeadOrNull,
+  fail,
+  fieldValue,
+  fileNonempty,
+  git,
+  green,
+  red,
+  setYamlField,
+  today,
+  validateChangeName,
+  validateEnum,
+  writeYamlData,
+  yamlFileFor,
+  yellow,
+} from './comet-lib.js';
+
+const ENUMS = {
+  workflow: ['full', 'hotfix', 'tweak'],
+  phase: ['open', 'design', 'build', 'verify', 'archive'],
+  build_mode: ['subagent-driven-development', 'executing-plans', 'direct'],
+  build_pause: ['null', 'plan-ready'],
+  isolation: ['branch', 'worktree'],
+  verify_mode: ['light', 'full'],
+  verify_result: ['pending', 'pass', 'fail'],
+  branch_status: ['pending', 'handled'],
+  archived: ['true', 'false'],
+  direct_override: ['true', 'false'],
+};
+
+const SET_FIELDS = new Set([
+  'workflow',
+  'phase',
+  'build_mode',
+  'build_pause',
+  'isolation',
+  'verify_mode',
+  'verify_result',
+  'verification_report',
+  'branch_status',
+  'archived',
+  'design_doc',
+  'plan',
+  'verified_at',
+  'created_at',
+  'direct_override',
+  'build_command',
+  'verify_command',
+  'handoff_context',
+  'handoff_hash',
+  'base_ref',
+]);
+
+function get(change, field) {
+  validateChangeName(change);
+  const yaml = yamlFileFor(change);
+  if (!existsSync(yaml)) fail(`.comet.yaml not found at ${yaml}`);
+  console.log(fieldValue(yaml, field));
+}
+
+function getValue(change, field) {
+  const yaml = yamlFileFor(change);
+  return fieldValue(yaml, field);
+}
+
+function set(change, field, value, quiet = false) {
+  validateChangeName(change);
+  const yaml = yamlFileFor(change);
+  if (!existsSync(yaml)) fail(`.comet.yaml not found at ${yaml}`);
+  if (field === 'phase') {
+    yellow("WARNING: Setting 'phase' directly bypasses state machine constraints.");
+    yellow('  Consider using: comet-state.js transition <change-name> <event>');
+  } else if (!SET_FIELDS.has(field)) {
+    red(`ERROR: Unknown field: '${field}'`);
+    red('Valid fields:');
+    red('  workflow, phase, design_doc, plan, build_mode, build_pause, isolation,');
+    red('  verify_mode, verify_result, verification_report, branch_status,');
+    red('  verified_at, created_at, archived, base_ref, direct_override,');
+    red('  build_command, verify_command, handoff_context, handoff_hash');
+    process.exit(1);
+  }
+  if (ENUMS[field]) validateEnum(value, ENUMS[field]);
+  setYamlField(yaml, field, value);
+  if (!quiet) green(`[SET] ${field}=${value}`);
+}
+
+function init(change, workflow) {
+  validateChangeName(change);
+  validateEnum(workflow, ENUMS.workflow);
+  const changeDir = changeDirFor(change);
+  const yaml = yamlFileFor(change);
+  if (existsSync(yaml)) fail(`.comet.yaml already exists at ${yaml}`);
+  mkdirSync(changeDir, { recursive: true });
+  const preset = workflow === 'full' ? ['null', 'null', 'null'] : ['direct', 'branch', 'light'];
+  writeYamlData(yaml, {
+    workflow,
+    phase: 'open',
+    build_mode: preset[0],
+    build_pause: 'null',
+    isolation: preset[1],
+    verify_mode: preset[2],
+    base_ref: currentHeadOrNull(),
+    design_doc: 'null',
+    plan: 'null',
+    verify_result: 'pending',
+    verification_report: 'null',
+    branch_status: 'pending',
+    created_at: today(),
+    verified_at: 'null',
+    archived: 'false',
+  });
+  green(`Initialized: ${yaml} (workflow=${workflow})`);
+}
+
+function requirePhase(change, expected) {
+  const actual = getValue(change, 'phase');
+  if (actual !== expected) fail(`Cannot transition '${change}': expected phase ${expected}, got ${actual}`);
+}
+
+function requireVerificationEvidence(change) {
+  const report = getValue(change, 'verification_report');
+  const branchStatus = getValue(change, 'branch_status');
+  if (!report || report === 'null' || !existsSync(report)) {
+    fail(`Cannot transition '${change}': verification_report must point to an existing report file`);
+  }
+  if (branchStatus !== 'handled') fail(`Cannot transition '${change}': branch_status must be handled`);
+}
+
+function requireBuildDecisions(change) {
+  const workflow = getValue(change, 'workflow');
+  const buildMode = getValue(change, 'build_mode');
+  const isolation = getValue(change, 'isolation');
+  const directOverride = getValue(change, 'direct_override');
+  if (!['branch', 'worktree'].includes(isolation)) {
+    fail(`Cannot transition '${change}': isolation must be branch or worktree, got '${isolation || 'null'}'`);
+  }
+  if (!ENUMS.build_mode.includes(buildMode)) {
+    fail(`Cannot transition '${change}': build_mode must be selected before leaving build, got '${buildMode || 'null'}'`);
+  }
+  if (buildMode === 'direct' && !['hotfix', 'tweak'].includes(workflow) && directOverride !== 'true') {
+    fail(`Cannot transition '${change}': build_mode=direct is only allowed for hotfix/tweak unless direct_override=true`);
+  }
+}
+
+function transition(change, event) {
+  validateChangeName(change);
+  validateEnum(event, ['open-complete', 'design-complete', 'build-complete', 'verify-pass', 'verify-fail', 'archived']);
+  if (event === 'open-complete') {
+    requirePhase(change, 'open');
+    set(change, 'phase', getValue(change, 'workflow') === 'full' ? 'design' : 'build', true);
+  } else if (event === 'design-complete') {
+    requirePhase(change, 'design');
+    set(change, 'phase', 'build', true);
+  } else if (event === 'build-complete') {
+    requirePhase(change, 'build');
+    requireBuildDecisions(change);
+    set(change, 'phase', 'verify', true);
+    set(change, 'verify_result', 'pending', true);
+    set(change, 'verification_report', 'null', true);
+    set(change, 'branch_status', 'pending', true);
+  } else if (event === 'verify-pass') {
+    requirePhase(change, 'verify');
+    requireVerificationEvidence(change);
+    set(change, 'verify_result', 'pass', true);
+    set(change, 'phase', 'archive', true);
+    set(change, 'verified_at', today(), true);
+  } else if (event === 'verify-fail') {
+    requirePhase(change, 'verify');
+    set(change, 'verify_result', 'fail', true);
+    set(change, 'phase', 'build', true);
+    set(change, 'branch_status', 'pending', true);
+  } else if (event === 'archived') {
+    requirePhase(change, 'archive');
+    set(change, 'archived', 'true', true);
+  }
+  green(`[TRANSITION] ${event}`);
+}
+
+let checkBlock = false;
+function pass(msg) { console.log(`  \u001b[32m[PASS]\u001b[0m ${msg}`); }
+function block(msg) { console.log(`  \u001b[31m[FAIL]\u001b[0m ${msg}`); checkBlock = true; }
+function checkNonempty(desc, file) { fileNonempty(file) ? pass(`${desc} non-empty`) : block(`${desc} missing or empty`); }
+function checkYamlIs(field, expected, change) {
+  const actual = getValue(change, field);
+  actual === expected ? pass(`${field}=${actual} (expected: ${expected})`) : block(`${field}=${actual} (expected: ${expected})`);
+}
+function checkYamlEmpty(field, change) {
+  const value = getValue(change, field);
+  !value || value === 'null' ? pass(`${field} is empty/null`) : block(`${field}=${value} (expected: empty/null)`);
+}
+
+function check(change, phase) {
+  validateChangeName(change);
+  validateEnum(phase, ['open', 'design', 'build', 'verify', 'archive']);
+  checkBlock = false;
+  const changeDir = join('openspec', 'changes', change);
+  const yaml = join(changeDir, '.comet.yaml');
+  console.log(`=== Entry Check: comet-${phase} ===`);
+  if (!existsSync(yaml)) fail(`.comet.yaml not found at ${yaml}`);
+  if (phase === 'open') {
+    pass('.comet.yaml exists');
+    checkYamlIs('phase', 'open', change);
+  } else if (phase === 'design') {
+    pass('.comet.yaml exists');
+    checkYamlIs('phase', 'design', change);
+    checkYamlIs('workflow', 'full', change);
+    checkYamlEmpty('design_doc', change);
+    checkNonempty('proposal.md', join(changeDir, 'proposal.md'));
+    checkNonempty('design.md', join(changeDir, 'design.md'));
+    checkNonempty('tasks.md', join(changeDir, 'tasks.md'));
+  } else if (phase === 'build') {
+    pass('.comet.yaml exists');
+    checkYamlIs('phase', 'build', change);
+    const workflow = getValue(change, 'workflow');
+    if (workflow === 'full') {
+      const designDoc = getValue(change, 'design_doc');
+      designDoc && designDoc !== 'null' && existsSync(designDoc)
+        ? pass(`design_doc=${designDoc} (file exists)`)
+        : block(`design_doc=${designDoc} (expected: non-null and file exists)`);
+    } else {
+      pass(`workflow=${workflow} (design_doc not required)`);
+    }
+    checkNonempty('proposal.md', join(changeDir, 'proposal.md'));
+    checkNonempty('tasks.md', join(changeDir, 'tasks.md'));
+  } else if (phase === 'verify') {
+    pass('.comet.yaml exists');
+    checkYamlIs('phase', 'verify', change);
+    const result = getValue(change, 'verify_result');
+    result === 'pending' || !result || result === 'null'
+      ? pass(`verify_result=${result} (expected: pending or null)`)
+      : block(`verify_result=${result} (expected: pending or null)`);
+  } else if (phase === 'archive') {
+    pass('.comet.yaml exists');
+    checkYamlIs('phase', 'archive', change);
+    checkYamlIs('verify_result', 'pass', change);
+    const archived = getValue(change, 'archived');
+    archived !== 'true' ? pass(`archived=${archived} (expected: not true)`) : block(`archived=${archived} (expected: not true)`);
+  }
+  console.log('');
+  if (checkBlock) {
+    red('BLOCKED — fix failing checks before proceeding');
+    process.exit(1);
+  }
+  green('ALL CHECKS PASSED — ready to proceed');
+}
+
+function fieldStatus(field, value, file = '') {
+  if (!value || value === 'null') console.log(`  - ${field}: PENDING`);
+  else if (file && !existsSync(file)) console.log(`  - ${field}: BROKEN (path ${value} does not exist)`);
+  else console.log(`  - ${field}: DONE (${value})`);
+}
+
+function recover(change) {
+  validateChangeName(change);
+  const changeDir = join('openspec', 'changes', change);
+  const yaml = join(changeDir, '.comet.yaml');
+  if (!existsSync(yaml)) fail(`.comet.yaml not found at ${yaml}`);
+  const phase = getValue(change, 'phase');
+  const workflow = getValue(change, 'workflow');
+  console.log(`=== Recovery Context: ${change} ===`);
+  console.log(`Phase: ${phase}`);
+  console.log(`Workflow: ${workflow}`);
+  console.log('');
+  const values = Object.fromEntries(['design_doc', 'plan', 'verify_result', 'verify_mode', 'verification_report', 'branch_status', 'handoff_context', 'handoff_hash', 'isolation', 'build_mode', 'build_pause', 'direct_override', 'archived'].map((f) => [f, getValue(change, f)]));
+  console.log('State fields:');
+  if (phase === 'open') {
+    console.log('  Artifacts:');
+    for (const f of ['proposal.md', 'design.md', 'tasks.md']) console.log(`  - ${f}: ${fileNonempty(join(changeDir, f)) ? 'DONE' : 'PENDING'}`);
+    console.log('\nRecovery action: Create or complete missing artifacts, then use AskUserQuestion for user confirmation.');
+  } else if (phase === 'design') {
+    console.log('  Artifacts:');
+    for (const f of ['proposal.md', 'design.md', 'tasks.md']) console.log(`  - ${f}: ${fileNonempty(join(changeDir, f)) ? 'DONE' : 'MISSING (unexpected in design phase)'}`);
+    console.log('\n  Design progress:');
+    fieldStatus('handoff_context', values.handoff_context, values.handoff_context);
+    fieldStatus('handoff_hash', values.handoff_hash);
+    fieldStatus('design_doc', values.design_doc, values.design_doc);
+    console.log('');
+    if (values.design_doc && values.design_doc !== 'null' && existsSync(values.design_doc)) console.log('Recovery action: Design Doc already created and linked. Run guard to transition to build.');
+    else if (values.handoff_context && values.handoff_context !== 'null' && existsSync(values.handoff_context)) console.log('Recovery action: Handoff generated but Design Doc not yet created. Resume from brainstorming confirmation (Step 1c).');
+    else console.log('Recovery action: No handoff generated yet. Start from Step 1a (generate handoff package).');
+  } else if (phase === 'build') {
+    console.log('  Build decisions:');
+    fieldStatus('isolation', values.isolation);
+    fieldStatus('build_mode', values.build_mode);
+    fieldStatus('build_pause', values.build_pause);
+    if (values.build_mode === 'direct' && !['hotfix', 'tweak'].includes(workflow)) fieldStatus('direct_override', values.direct_override);
+    console.log('\n  Plan:');
+    fieldStatus('plan', values.plan, values.plan);
+    const tasksFile = join(changeDir, 'tasks.md');
+    let total = 0;
+    let done = 0;
+    if (existsSync(tasksFile)) {
+      const text = readFileSync(tasksFile, 'utf8');
+      total = (text.match(/^- \[/gm) ?? []).length;
+      done = (text.match(/^- \[x\]/gm) ?? []).length;
+      console.log(`\n  Tasks: ${done}/${total} done, ${total - done} pending`);
+    } else console.log('\n  Tasks: tasks.md MISSING');
+    console.log('');
+    if (values.build_pause === 'plan-ready' && values.plan && values.plan !== 'null' && existsSync(values.plan) && (!values.isolation || values.isolation === 'null' || !values.build_mode || values.build_mode === 'null')) console.log('Recovery action: Plan-ready pause detected. Ask the user whether to continue, then choose isolation and build mode without regenerating the plan.');
+    else if (values.build_pause === 'plan-ready' && (!values.plan || values.plan === 'null' || !existsSync(values.plan))) console.log('Recovery action: Plan-ready pause is recorded, but the plan file is missing. Restore the plan file or rerun writing-plans before choosing execution.');
+    else if (values.build_pause === 'plan-ready') console.log('Recovery action: Plan-ready pause is stale because build decisions are already selected. Clear build_pause to null, then continue from the first unchecked task.');
+    else if (!values.isolation || values.isolation === 'null') console.log('Recovery action: Isolation not selected. Use AskUserQuestion to ask user for branch/worktree choice.');
+    else if (!values.build_mode || values.build_mode === 'null') console.log('Recovery action: Build mode not selected. Use AskUserQuestion to ask user for execution method.');
+    else if (!existsSync(tasksFile)) console.log('Recovery action: tasks.md missing. Verify change directory integrity.');
+    else if (total - done > 0) console.log('Recovery action: Read tasks.md and continue from first unchecked task.');
+    else console.log('Recovery action: All tasks done. Run guard to transition to verify.');
+  } else if (phase === 'verify') {
+    console.log('  Verification:');
+    fieldStatus('verify_result', values.verify_result);
+    fieldStatus('verify_mode', values.verify_mode);
+    fieldStatus('verification_report', values.verification_report, values.verification_report);
+    fieldStatus('branch_status', values.branch_status);
+    console.log('');
+    if (values.verify_result === 'pass' && values.branch_status === 'handled') console.log('Recovery action: Verification complete. Run guard to transition to archive.');
+    else if (values.verify_result === 'pass') console.log('Recovery action: Verification passed but branch not yet handled. Complete branch handling and set branch_status to handled.');
+    else if (values.verify_result === 'fail') console.log('Recovery action: Verification failed and rolled back to build. Resume from /comet-build.');
+    else console.log('Recovery action: Verification not yet started or in progress. Run scale assessment then verify.');
+  } else if (phase === 'archive') {
+    console.log('  Archive:');
+    fieldStatus('verify_result', values.verify_result);
+    fieldStatus('archived', values.archived);
+    console.log('\nRecovery action: Run /comet-archive to complete archiving.');
+  }
+  console.log('\n=== End Recovery Context ===');
+}
+
+function countSpecFiles(dir) {
+  if (!existsSync(dir)) return 0;
+  let count = 0;
+  for (const entry of readdirSync(dir, { withFileTypes: true })) {
+    const p = join(dir, entry.name);
+    if (entry.isDirectory()) count += countSpecFiles(p);
+    else if (entry.isFile() && entry.name === 'spec.md') count += 1;
+  }
+  return count;
+}
+
+function scale(change) {
+  validateChangeName(change);
+  const changeDir = join('openspec', 'changes', change);
+  const yaml = join(changeDir, '.comet.yaml');
+  if (!existsSync(yaml)) fail(`.comet.yaml not found at ${yaml}`);
+  const tasksFile = join(changeDir, 'tasks.md');
+  const taskCount = existsSync(tasksFile) ? (readFileSync(tasksFile, 'utf8').match(/^- \[/gm) ?? []).length : 0;
+  const deltaSpecCount = countSpecFiles(join(changeDir, 'specs'));
+  let changedFiles = 0;
+  if (git(['rev-parse', '--git-dir']).status === 0) {
+    let baseRef = '';
+    const plan = getValue(change, 'plan');
+    if (plan && plan !== 'null' && existsSync(plan)) {
+      baseRef = readFileSync(plan, 'utf8').match(/^base-ref:\s*(.*)$/m)?.[1]?.trim() ?? '';
+    }
+    if (!baseRef || baseRef === 'null') baseRef = getValue(change, 'base_ref');
+    const diff = baseRef && baseRef !== 'null' && git(['rev-parse', '--verify', baseRef]).status === 0
+      ? git(['diff', '--name-only', `${baseRef}...HEAD`])
+      : git(['diff', '--name-only', 'HEAD']);
+    changedFiles = diff.status === 0 ? diff.stdout.split(/\r?\n/).filter(Boolean).length : 0;
+  }
+  const result = taskCount > 3 || deltaSpecCount > 1 || changedFiles > 4 ? 'full' : 'light';
+  console.error(`=== Scale Assessment: ${change} ===`);
+  console.error(`  Tasks: ${taskCount} (threshold: 3)`);
+  console.error(`  Delta specs: ${deltaSpecCount} capabilities (threshold: 1)`);
+  console.error(`  Changed files: ${changedFiles} (threshold: 4)`);
+  console.error(`  → Result: ${result}`);
+  setYamlField(yaml, 'verify_mode', result);
+  green(`[SCALE] verify_mode=${result}`);
+}
+
+const [subcommand, ...args] = process.argv.slice(2);
+if (subcommand === 'init' && args.length >= 2) init(args[0], args[1]);
+else if (subcommand === 'get' && args.length >= 2) get(args[0], args[1]);
+else if (subcommand === 'set' && args.length >= 3) set(args[0], args[1], args.slice(2).join(' '));
+else if (subcommand === 'transition' && args.length >= 2) transition(args[0], args[1]);
+else if (subcommand === 'check' && args.length >= 2) args[2] === '--recover' ? recover(args[0]) : check(args[0], args[1]);
+else if (subcommand === 'scale' && args.length >= 1) scale(args[0]);
+else {
+  red(`Unknown subcommand: ${subcommand ?? ''}`);
+  console.error('\nUsage: comet-state.js <subcommand> <change-name> [args...]');
+  process.exit(1);
+}
diff --git a/assets/skills/comet/scripts/comet-state.sh b/assets/skills/comet/scripts/comet-state.sh
deleted file mode 100644
index a997f9ac..00000000
--- a/assets/skills/comet/scripts/comet-state.sh
+++ /dev/null
@@ -1,908 +0,0 @@
-#!/bin/bash
-# Comet State — unified interface for .comet.yaml state management
-# Usage: comet-state.sh <subcommand> <change-name> [args...]
-#
-# Subcommands:
-#   init <change-name> <workflow>  — Initialize .comet.yaml with workflow defaults
-#   get <change-name> <field>       — Read a field value from .comet.yaml
-#   set <change-name> <field> <val> — Update a field value
-#   transition <change-name> <event> — Apply a validated state transition
-#   check <change-name> <phase>    — Verify entry requirements for a phase
-#   check <change-name> <phase> --recover — Output structured recovery context for compaction resume
-#   scale <change-name>             — Assess and set verification mode based on metrics
-#
-# Workflows: full, hotfix, tweak
-# Phases for check: open, design, build, verify, archive
-
-set -euo pipefail
-
-# --- Color output helpers ---
-
-red() { echo -e "\033[31m$1\033[0m" >&2; }
-green() { echo -e "\033[32m$1\033[0m" >&2; }
-yellow() { echo -e "\033[33m$1\033[0m" >&2; }
-
-# --- Script location ---
-
-# shellcheck disable=SC2034
-SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
-
-# --- Input validation ---
-
-validate_change_name() {
-  local name="$1"
-  # Reject empty names
-  if [ -z "$name" ]; then
-    red "ERROR: Change name cannot be empty" >&2
-    exit 1
-  fi
-  # Only allow alphanumeric, hyphens, and underscores
-  if [[ ! "$name" =~ ^[a-zA-Z0-9_-]+$ ]]; then
-    red "ERROR: Invalid change name: '$name'" >&2
-    red "Valid characters: a-z, A-Z, 0-9, -, _" >&2
-    exit 1
-  fi
-  # Reject path traversal attempts
-  if [[ "$name" =~ \.\. ]]; then
-    red "ERROR: Change name cannot contain '..' (path traversal not allowed)" >&2
-    exit 1
-  fi
-}
-
-validate_enum() {
-  local value="$1"
-  shift
-  local valid_values=("$@")
-
-  for valid in "${valid_values[@]}"; do
-    if [ "$value" = "$valid" ]; then
-      return 0
-    fi
-  done
-
-  red "ERROR: Invalid value: '$value'" >&2
-  red "Valid values: ${valid_values[*]}" >&2
-  exit 1
-}
-
-# --- Helper functions ---
-
-yaml_field() {
-  local field="$1"
-  local yaml_file="$2"
-  if [ -f "$yaml_file" ]; then
-    local value
-    value=$(grep "^${field}:" "$yaml_file" 2>/dev/null | sed "s/^${field}: *//" || true)
-    value=$(strip_inline_comment "$value")
-    strip_wrapping_quotes "$value"
-  fi
-}
-
-strip_inline_comment() {
-  local value="$1"
-  printf '%s\n' "$value" | awk -v squote="'" '
-    {
-      out = ""
-      quote = ""
-      for (i = 1; i <= length($0); i++) {
-        c = substr($0, i, 1)
-        if (quote == "") {
-          if (c == "\"" || c == squote) {
-            quote = c
-          } else if (c == "#" && (i == 1 || substr($0, i - 1, 1) ~ /[[:space:]]/)) {
-            sub(/[[:space:]]+$/, "", out)
-            print out
-            next
-          }
-        } else if (c == quote) {
-          quote = ""
-        }
-        out = out c
-      }
-      print out
-    }
-  '
-}
-
-strip_wrapping_quotes() {
-  local value="$1"
-  case "$value" in
-    \"*\")
-      printf '%s\n' "${value:1:${#value}-2}"
-      ;;
-    \'*\')
-      printf '%s\n' "${value:1:${#value}-2}"
-      ;;
-    *)
-      printf '%s\n' "$value"
-      ;;
-  esac
-}
-
-replace_yaml_field() {
-  local yaml_file="$1"
-  local field="$2"
-  local value="$3"
-  local tmp_file
-
-  tmp_file=$(mktemp)
-  awk -v field="$field" -v value="$value" '
-    index($0, field ":") == 1 { print field ": " value; next }
-    { print }
-  ' "$yaml_file" > "$tmp_file"
-  mv "$tmp_file" "$yaml_file"
-}
-
-file_nonempty() {
-  [ -f "$1" ] && [ -s "$1" ]
-}
-
-change_dir_for() {
-  local change_name="$1"
-  if [ -d "openspec/changes/$change_name" ]; then
-    echo "openspec/changes/$change_name"
-  elif [ -d "openspec/changes/archive/$change_name" ]; then
-    echo "openspec/changes/archive/$change_name"
-  else
-    echo "openspec/changes/$change_name"
-  fi
-}
-
-yaml_file_for() {
-  local change_name="$1"
-  local change_dir
-  change_dir=$(change_dir_for "$change_name")
-  echo "$change_dir/.comet.yaml"
-}
-
-# --- Subcommands ---
-
-cmd_init() {
-  local change_name="$1"
-  local workflow="$2"
-
-  validate_change_name "$change_name"
-  validate_enum "$workflow" "full" "hotfix" "tweak"
-
-  local change_dir yaml_file
-  change_dir=$(change_dir_for "$change_name")
-  yaml_file=$(yaml_file_for "$change_name")
-
-  # Check if .comet.yaml already exists
-  if [ -f "$yaml_file" ]; then
-    red "ERROR: .comet.yaml already exists at $yaml_file"
-    exit 1
-  fi
-
-  # Create change directory if it doesn't exist
-  mkdir -p "$change_dir"
-
-  # Set workflow-appropriate defaults
-  local phase build_mode isolation verify_mode
-  phase="open"
-
-  case "$workflow" in
-    full)
-      build_mode="null"
-      isolation="null"
-      verify_mode="null"
-      ;;
-    hotfix|tweak)
-      build_mode="direct"
-      isolation="branch"
-      verify_mode="light"
-      ;;
-  esac
-
-  # Write .comet.yaml
-  # Record current HEAD as base_ref for scale assessment fallback
-  local base_ref="null"
-  if git rev-parse --verify HEAD >/dev/null 2>&1; then
-    base_ref=$(git rev-parse HEAD 2>/dev/null || echo "null")
-  fi
-
-  cat > "$yaml_file" <<EOF
-workflow: $workflow
-phase: $phase
-build_mode: $build_mode
-build_pause: null
-isolation: $isolation
-verify_mode: $verify_mode
-base_ref: $base_ref
-design_doc: null
-plan: null
-verify_result: pending
-verification_report: null
-branch_status: pending
-created_at: $(date +%Y-%m-%d)
-verified_at: null
-archived: false
-EOF
-
-  green "Initialized: $yaml_file (workflow=$workflow)"
-}
-
-cmd_get() {
-  local change_name="$1"
-  local field="$2"
-
-  validate_change_name "$change_name"
-
-  local yaml_file
-  yaml_file=$(yaml_file_for "$change_name")
-
-  # Check if .comet.yaml exists
-  if [ ! -f "$yaml_file" ]; then
-    red "ERROR: .comet.yaml not found at $yaml_file"
-    exit 1
-  fi
-
-  # Read and output the field value
-  local value
-  value=$(yaml_field "$field" "$yaml_file")
-  echo "${value:-}"
-}
-
-cmd_set() {
-  local change_name="$1"
-  local field="$2"
-  local value="$3"
-
-  validate_change_name "$change_name"
-
-  local yaml_file
-  yaml_file=$(yaml_file_for "$change_name")
-
-  # Check if .comet.yaml exists
-  if [ ! -f "$yaml_file" ]; then
-    red "ERROR: .comet.yaml not found at $yaml_file"
-    exit 1
-  fi
-
-  # Validate field name
-  case "$field" in
-    phase)
-      yellow "WARNING: Setting 'phase' directly bypasses state machine constraints." >&2
-      yellow "  Consider using: comet-state.sh transition <change-name> <event>" >&2
-      ;;
-    workflow|build_mode|build_pause|isolation|verify_mode|verify_result|verification_report|branch_status|archived|design_doc|plan|verified_at|created_at|direct_override|build_command|verify_command|handoff_context|handoff_hash|base_ref)
-      # Valid field
-      ;;
-    *)
-      red "ERROR: Unknown field: '$field'" >&2
-      red "Valid fields:" >&2
-      red "  workflow, phase, design_doc, plan, build_mode, build_pause, isolation," >&2
-      red "  verify_mode, verify_result, verification_report, branch_status," >&2
-      red "  verified_at, created_at, archived, base_ref, direct_override," >&2
-      red "  build_command, verify_command, handoff_context, handoff_hash" >&2
-      exit 1
-      ;;
-  esac
-
-  # Validate enum values
-  case "$field" in
-    workflow)
-      validate_enum "$value" "full" "hotfix" "tweak"
-      ;;
-    phase)
-      validate_enum "$value" "open" "design" "build" "verify" "archive"
-      ;;
-    build_mode)
-      validate_enum "$value" "subagent-driven-development" "executing-plans" "direct"
-      ;;
-    build_pause)
-      validate_enum "$value" "null" "plan-ready"
-      ;;
-    isolation)
-      validate_enum "$value" "branch" "worktree"
-      ;;
-    verify_mode)
-      validate_enum "$value" "light" "full"
-      ;;
-    verify_result)
-      validate_enum "$value" "pending" "pass" "fail"
-      ;;
-    branch_status)
-      validate_enum "$value" "pending" "handled"
-      ;;
-    archived)
-      validate_enum "$value" "true" "false"
-      ;;
-    direct_override)
-      validate_enum "$value" "true" "false"
-      ;;
-    design_doc|plan|verification_report|verified_at|created_at|build_command|verify_command|handoff_context|handoff_hash)
-      # No validation for path fields, date fields, or project command strings
-      ;;
-  esac
-
-  # Write or update the field
-  if grep -q "^${field}:" "$yaml_file"; then
-    replace_yaml_field "$yaml_file" "$field" "$value"
-  else
-    # Field doesn't exist, append it
-    echo "${field}: ${value}" >> "$yaml_file"
-  fi
-
-  green "[SET] ${field}=${value}"
-}
-
-require_phase() {
-  local change_name="$1"
-  local expected="$2"
-  local actual
-  actual=$(cmd_get "$change_name" "phase")
-  if [ "$actual" != "$expected" ]; then
-    red "ERROR: Cannot transition '$change_name': expected phase ${expected}, got ${actual}" >&2
-    exit 1
-  fi
-}
-
-require_verification_evidence() {
-  local change_name="$1"
-  local report branch_status
-  report=$(cmd_get "$change_name" "verification_report")
-  branch_status=$(cmd_get "$change_name" "branch_status")
-
-  if [ -z "$report" ] || [ "$report" = "null" ] || [ ! -f "$report" ]; then
-    red "ERROR: Cannot transition '$change_name': verification_report must point to an existing report file" >&2
-    exit 1
-  fi
-
-  if [ "$branch_status" != "handled" ]; then
-    red "ERROR: Cannot transition '$change_name': branch_status must be handled" >&2
-    exit 1
-  fi
-}
-
-require_build_decisions() {
-  local change_name="$1"
-  local workflow build_mode isolation direct_override
-  workflow=$(cmd_get "$change_name" "workflow")
-  build_mode=$(cmd_get "$change_name" "build_mode")
-  isolation=$(cmd_get "$change_name" "isolation")
-  direct_override=$(cmd_get "$change_name" "direct_override" 2>/dev/null || true)
-
-  case "$isolation" in
-    branch|worktree) ;;
-    *)
-      red "ERROR: Cannot transition '$change_name': isolation must be branch or worktree, got '${isolation:-null}'" >&2
-      exit 1
-      ;;
-  esac
-
-  case "$build_mode" in
-    subagent-driven-development|executing-plans|direct) ;;
-    *)
-      red "ERROR: Cannot transition '$change_name': build_mode must be selected before leaving build, got '${build_mode:-null}'" >&2
-      exit 1
-      ;;
-  esac
-
-  if [ "$build_mode" = "direct" ] && [ "$workflow" != "hotfix" ] && [ "$workflow" != "tweak" ] && [ "$direct_override" != "true" ]; then
-    red "ERROR: Cannot transition '$change_name': build_mode=direct is only allowed for hotfix/tweak unless direct_override=true" >&2
-    exit 1
-  fi
-}
-
-cmd_transition() {
-  local change_name="$1"
-  local event="$2"
-
-  validate_change_name "$change_name"
-  validate_enum "$event" "open-complete" "design-complete" "build-complete" "verify-pass" "verify-fail" "archived"
-
-  case "$event" in
-    open-complete)
-      require_phase "$change_name" "open"
-      local workflow
-      workflow=$(cmd_get "$change_name" "workflow")
-      if [ "$workflow" = "full" ]; then
-        cmd_set "$change_name" phase design
-      else
-        cmd_set "$change_name" phase build
-      fi
-      ;;
-    design-complete)
-      require_phase "$change_name" "design"
-      cmd_set "$change_name" phase build
-      ;;
-    build-complete)
-      require_phase "$change_name" "build"
-      require_build_decisions "$change_name"
-      cmd_set "$change_name" phase verify
-      cmd_set "$change_name" verify_result pending
-      cmd_set "$change_name" verification_report null
-      cmd_set "$change_name" branch_status pending
-      ;;
-    verify-pass)
-      require_phase "$change_name" "verify"
-      require_verification_evidence "$change_name"
-      cmd_set "$change_name" verify_result pass
-      cmd_set "$change_name" phase archive
-      cmd_set "$change_name" verified_at "$(date +%Y-%m-%d)"
-      ;;
-    verify-fail)
-      require_phase "$change_name" "verify"
-      cmd_set "$change_name" verify_result fail
-      cmd_set "$change_name" phase build
-      cmd_set "$change_name" branch_status pending
-      ;;
-    archived)
-      require_phase "$change_name" "archive"
-      cmd_set "$change_name" archived true
-      ;;
-  esac
-
-  green "[TRANSITION] ${event}"
-}
-
-# --- Check helpers for entry verification ---
-
-CHECK_BLOCK=0
-
-check_pass() {
-  local msg="$1"
-  echo "  $(green "[PASS]") $msg"
-}
-
-check_fail() {
-  local msg="$1"
-  echo "  $(red "[FAIL]") $msg"
-  CHECK_BLOCK=1
-}
-
-check_nonempty() {
-  local desc="$1"
-  local path="$2"
-  if file_nonempty "$path"; then
-    check_pass "$desc non-empty"
-  else
-    check_fail "$desc missing or empty"
-  fi
-}
-
-check_yaml_is() {
-  local field="$1"
-  local expected="$2"
-  local change_name="$3"
-  local actual
-  actual=$(cmd_get "$change_name" "$field")
-  if [ "$actual" = "$expected" ]; then
-    check_pass "${field}=${actual} (expected: ${expected})"
-  else
-    check_fail "${field}=${actual} (expected: ${expected})"
-  fi
-}
-
-check_yaml_empty() {
-  local field="$1"
-  local change_name="$2"
-  local value
-  value=$(cmd_get "$change_name" "$field")
-  if [ -z "$value" ] || [ "$value" = "null" ]; then
-    check_pass "${field} is empty/null"
-  else
-    check_fail "${field}=${value} (expected: empty/null)"
-  fi
-}
-
-check_file_not_exists() {
-  local desc="$1"
-  local path="$2"
-  if [ ! -f "$path" ]; then
-    check_pass "$desc does not exist"
-  else
-    check_fail "$desc exists (should not exist)"
-  fi
-}
-
-cmd_check() {
-  local change_name="$1"
-  local phase="$2"
-
-  validate_change_name "$change_name"
-  validate_enum "$phase" "open" "design" "build" "verify" "archive"
-
-  local change_dir="openspec/changes/$change_name"
-  local yaml_file="$change_dir/.comet.yaml"
-  local proposal_file="$change_dir/proposal.md"
-  local design_file="$change_dir/design.md"
-  local tasks_file="$change_dir/tasks.md"
-
-  echo "=== Entry Check: comet-${phase} ==="
-
-  # .comet.yaml must exist for all phases (state machine core)
-  if [ ! -f "$yaml_file" ]; then
-    red "ERROR: .comet.yaml not found at $yaml_file"
-    exit 1
-  fi
-
-  # Phase-specific checks
-  case "$phase" in
-    open)
-      check_pass ".comet.yaml exists"
-      check_yaml_is "phase" "open" "$change_name"
-      ;;
-    design)
-      check_pass ".comet.yaml exists"
-      check_yaml_is "phase" "design" "$change_name"
-      check_yaml_is "workflow" "full" "$change_name"
-      check_yaml_empty "design_doc" "$change_name"
-      check_nonempty "proposal.md" "$proposal_file"
-      check_nonempty "design.md" "$design_file"
-      check_nonempty "tasks.md" "$tasks_file"
-      ;;
-    build)
-      check_pass ".comet.yaml exists"
-      check_yaml_is "phase" "build" "$change_name"
-      # design_doc required for full workflow only
-      local workflow
-      workflow=$(cmd_get "$change_name" "workflow")
-      if [ "$workflow" = "full" ]; then
-        local design_doc
-        design_doc=$(cmd_get "$change_name" "design_doc")
-        if [ -n "$design_doc" ] && [ "$design_doc" != "null" ] && [ -f "$design_doc" ]; then
-          check_pass "design_doc=${design_doc} (file exists)"
-        else
-          check_fail "design_doc=${design_doc} (expected: non-null and file exists)"
-        fi
-      else
-        check_pass "workflow=${workflow} (design_doc not required)"
-      fi
-      check_nonempty "proposal.md" "$proposal_file"
-      check_nonempty "tasks.md" "$tasks_file"
-      ;;
-    verify)
-      check_pass ".comet.yaml exists"
-      check_yaml_is "phase" "verify" "$change_name"
-      # Check verify_result is pending or null
-      local verify_result
-      verify_result=$(cmd_get "$change_name" "verify_result")
-      if [ "$verify_result" = "pending" ] || [ -z "$verify_result" ] || [ "$verify_result" = "null" ]; then
-        check_pass "verify_result=${verify_result} (expected: pending or null)"
-      else
-        check_fail "verify_result=${verify_result} (expected: pending or null)"
-      fi
-      ;;
-    archive)
-      check_pass ".comet.yaml exists"
-      check_yaml_is "phase" "archive" "$change_name"
-      check_yaml_is "verify_result" "pass" "$change_name"
-      # Check archived is NOT true
-      local archived
-      archived=$(cmd_get "$change_name" "archived")
-      if [ "$archived" != "true" ]; then
-        check_pass "archived=${archived} (expected: not true)"
-      else
-        check_fail "archived=${archived} (expected: not true)"
-      fi
-      ;;
-    *)
-      red "ERROR: Unknown phase for check: $phase"
-      exit 1
-      ;;
-  esac
-
-  echo ""
-  if [ "$CHECK_BLOCK" -eq 1 ]; then
-    red "BLOCKED — fix failing checks before proceeding"
-    exit 1
-  else
-    green "ALL CHECKS PASSED — ready to proceed"
-    exit 0
-  fi
-}
-
-# --- Recovery context for compaction resume ---
-
-field_status() {
-  # Args: field_name value [file_path]
-  # Prints: "field_name: DONE (value)" or "field_name: PENDING"
-  local field="$1"
-  local value="$2"
-  local file_path="${3:-}"
-
-  if [ -z "$value" ] || [ "$value" = "null" ]; then
-    echo "  - ${field}: PENDING"
-  elif [ -n "$file_path" ] && [ ! -f "$file_path" ]; then
-    echo "  - ${field}: BROKEN (path ${value} does not exist)"
-  else
-    echo "  - ${field}: DONE (${value})"
-  fi
-}
-
-cmd_recover() {
-  local change_name="$1"
-
-  validate_change_name "$change_name"
-
-  local change_dir="openspec/changes/$change_name"
-  local yaml_file="$change_dir/.comet.yaml"
-
-  if [ ! -f "$yaml_file" ]; then
-    red "ERROR: .comet.yaml not found at $yaml_file"
-    exit 1
-  fi
-
-  local phase workflow
-  phase=$(cmd_get "$change_name" "phase")
-  workflow=$(cmd_get "$change_name" "workflow")
-
-  echo "=== Recovery Context: ${change_name} ==="
-  echo "Phase: ${phase}"
-  echo "Workflow: ${workflow}"
-  echo ""
-
-  # Read all relevant fields
-  local design_doc plan verify_result verify_mode verification_report
-  local branch_status handoff_context handoff_hash isolation build_mode build_pause direct_override
-  design_doc=$(cmd_get "$change_name" "design_doc")
-  plan=$(cmd_get "$change_name" "plan")
-  verify_result=$(cmd_get "$change_name" "verify_result")
-  verify_mode=$(cmd_get "$change_name" "verify_mode")
-  verification_report=$(cmd_get "$change_name" "verification_report")
-  branch_status=$(cmd_get "$change_name" "branch_status")
-  handoff_context=$(cmd_get "$change_name" "handoff_context")
-  handoff_hash=$(cmd_get "$change_name" "handoff_hash")
-  isolation=$(cmd_get "$change_name" "isolation")
-  build_mode=$(cmd_get "$change_name" "build_mode")
-  build_pause=$(cmd_get "$change_name" "build_pause" 2>/dev/null || true)
-  direct_override=$(cmd_get "$change_name" "direct_override" 2>/dev/null || true)
-
-  echo "State fields:"
-
-  # Phase-specific field reporting
-  case "$phase" in
-    open)
-      echo "  Artifacts:"
-      for f in proposal.md design.md tasks.md; do
-        if file_nonempty "$change_dir/$f"; then
-          echo "  - ${f}: DONE"
-        else
-          echo "  - ${f}: PENDING"
-        fi
-      done
-      echo ""
-      echo "Recovery action: Create or complete missing artifacts, then use AskUserQuestion for user confirmation."
-      ;;
-    design)
-      echo "  Artifacts:"
-      for f in proposal.md design.md tasks.md; do
-        if file_nonempty "$change_dir/$f"; then
-          echo "  - ${f}: DONE"
-        else
-          echo "  - ${f}: MISSING (unexpected in design phase)"
-        fi
-      done
-      echo ""
-      echo "  Design progress:"
-      field_status "handoff_context" "$handoff_context" "$handoff_context"
-      field_status "handoff_hash" "$handoff_hash"
-      field_status "design_doc" "$design_doc" "$design_doc"
-      echo ""
-      if [ -n "$design_doc" ] && [ "$design_doc" != "null" ] && [ -f "$design_doc" ]; then
-        echo "Recovery action: Design Doc already created and linked. Run guard to transition to build."
-      elif [ -n "$handoff_context" ] && [ "$handoff_context" != "null" ] && [ -f "$handoff_context" ]; then
-        echo "Recovery action: Handoff generated but Design Doc not yet created. Resume from brainstorming confirmation (Step 1c)."
-      else
-        echo "Recovery action: No handoff generated yet. Start from Step 1a (generate handoff package)."
-      fi
-      ;;
-    build)
-      echo "  Build decisions:"
-      field_status "isolation" "$isolation"
-      field_status "build_mode" "$build_mode"
-      field_status "build_pause" "$build_pause"
-      if [ "$build_mode" = "direct" ] && [ "$workflow" != "hotfix" ] && [ "$workflow" != "tweak" ]; then
-        field_status "direct_override" "$direct_override"
-      fi
-      echo ""
-      echo "  Plan:"
-      field_status "plan" "$plan" "$plan"
-      echo ""
-      # Count completed vs pending tasks
-      local tasks_file="$change_dir/tasks.md"
-      local total=0 done=0 pending=0
-      if [ -f "$tasks_file" ]; then
-        total=$(grep -c '^\- \[' "$tasks_file" 2>/dev/null || echo "0")
-        done=$(grep -c '^\- \[x\]' "$tasks_file" 2>/dev/null || echo "0")
-        pending=$((total - done))
-        echo "  Tasks: ${done}/${total} done, ${pending} pending"
-      else
-        echo "  Tasks: tasks.md MISSING"
-      fi
-      echo ""
-      if [ "$build_pause" = "plan-ready" ] && [ -n "$plan" ] && [ "$plan" != "null" ] && [ -f "$plan" ] && { [ "$isolation" = "null" ] || [ -z "$isolation" ] || [ "$build_mode" = "null" ] || [ -z "$build_mode" ]; }; then
-        echo "Recovery action: Plan-ready pause detected. Ask the user whether to continue, then choose isolation and build mode without regenerating the plan."
-      elif [ "$build_pause" = "plan-ready" ] && { [ -z "$plan" ] || [ "$plan" = "null" ] || [ ! -f "$plan" ]; }; then
-        echo "Recovery action: Plan-ready pause is recorded, but the plan file is missing. Restore the plan file or rerun writing-plans before choosing execution."
-      elif [ "$build_pause" = "plan-ready" ]; then
-        echo "Recovery action: Plan-ready pause is stale because build decisions are already selected. Clear build_pause to null, then continue from the first unchecked task."
-      elif [ "$isolation" = "null" ] || [ -z "$isolation" ]; then
-        echo "Recovery action: Isolation not selected. Use AskUserQuestion to ask user for branch/worktree choice."
-      elif [ "$build_mode" = "null" ] || [ -z "$build_mode" ]; then
-        echo "Recovery action: Build mode not selected. Use AskUserQuestion to ask user for execution method."
-      elif [ ! -f "$tasks_file" ]; then
-        echo "Recovery action: tasks.md missing. Verify change directory integrity."
-      elif [ "$pending" -gt 0 ]; then
-        echo "Recovery action: Read tasks.md and continue from first unchecked task."
-      else
-        echo "Recovery action: All tasks done. Run guard to transition to verify."
-      fi
-      ;;
-    verify)
-      echo "  Verification:"
-      field_status "verify_result" "$verify_result"
-      field_status "verify_mode" "$verify_mode"
-      field_status "verification_report" "$verification_report" "$verification_report"
-      field_status "branch_status" "$branch_status"
-      echo ""
-      if [ "$verify_result" = "pass" ] && [ "$branch_status" = "handled" ]; then
-        echo "Recovery action: Verification complete. Run guard to transition to archive."
-      elif [ "$verify_result" = "pass" ]; then
-        echo "Recovery action: Verification passed but branch not yet handled. Complete branch handling and set branch_status to handled."
-      elif [ "$verify_result" = "fail" ]; then
-        echo "Recovery action: Verification failed and rolled back to build. Resume from /comet-build."
-      else
-        echo "Recovery action: Verification not yet started or in progress. Run scale assessment then verify."
-      fi
-      ;;
-    archive)
-      echo "  Archive:"
-      field_status "verify_result" "$verify_result"
-      field_status "archived" "$(cmd_get "$change_name" "archived")"
-      echo ""
-      echo "Recovery action: Run /comet-archive to complete archiving."
-      ;;
-    *)
-      red "ERROR: Unknown phase: $phase"
-      exit 1
-      ;;
-  esac
-
-  echo ""
-  echo "=== End Recovery Context ==="
-}
-
-cmd_scale() {
-  local change_name="$1"
-
-  validate_change_name "$change_name"
-
-  local change_dir="openspec/changes/$change_name"
-  local yaml_file="$change_dir/.comet.yaml"
-
-  # Verify .comet.yaml exists
-  if [ ! -f "$yaml_file" ]; then
-    red "ERROR: .comet.yaml not found at $yaml_file"
-    exit 1
-  fi
-
-  # Read metrics
-  # 1. Task count: count lines matching `- [` in tasks.md
-  local tasks_file="$change_dir/tasks.md"
-  local task_count=0
-  if [ -f "$tasks_file" ]; then
-    task_count=$(grep -c '^\- \[' "$tasks_file" 2>/dev/null || echo "0")
-  fi
-
-  # 2. Delta spec count: count files named spec.md under specs/*/spec.md
-  local delta_spec_count=0
-  if [ -d "$change_dir/specs" ]; then
-    delta_spec_count=$(find "$change_dir/specs" -name "spec.md" -type f 2>/dev/null | wc -l | tr -d ' ')
-  fi
-
-  # 3. Changed files: prefer plan base-ref, then .comet.yaml base_ref, fall back to worktree diff
-  local changed_files=0
-  if git rev-parse --git-dir > /dev/null 2>&1; then
-    local plan_file base_ref=""
-    plan_file=$(cmd_get "$change_name" "plan" 2>/dev/null || true)
-    if [ -n "$plan_file" ] && [ "$plan_file" != "null" ] && [ -f "$plan_file" ]; then
-      base_ref=$(grep '^base-ref:' "$plan_file" 2>/dev/null | head -1 | sed 's/^base-ref: *//')
-    fi
-    # Fallback to base_ref stored in .comet.yaml (set during init)
-    if [ -z "$base_ref" ] || [ "$base_ref" = "null" ]; then
-      base_ref=$(cmd_get "$change_name" "base_ref" 2>/dev/null || true)
-    fi
-
-    if [ -n "${base_ref:-}" ] && [ "$base_ref" != "null" ] && git rev-parse --verify "$base_ref" >/dev/null 2>&1; then
-      changed_files=$(git diff --name-only "$base_ref"...HEAD 2>/dev/null | wc -l | tr -d ' ')
-    else
-      changed_files=$(git diff --name-only HEAD 2>/dev/null | wc -l | tr -d ' ')
-    fi
-  fi
-
-  # Decision rules
-  local result="light"
-  if [ "$task_count" -gt 3 ] || [ "$delta_spec_count" -gt 1 ] || [ "$changed_files" -gt 4 ]; then
-    result="full"
-  fi
-
-  # Output assessment to stderr
-  echo "=== Scale Assessment: $change_name ===" >&2
-  echo "  Tasks: $task_count (threshold: 3)" >&2
-  echo "  Delta specs: $delta_spec_count capabilities (threshold: 1)" >&2
-  echo "  Changed files: $changed_files (threshold: 4)" >&2
-  echo "  → Result: $result" >&2
-
-  # Update verify_mode in .comet.yaml
-  replace_yaml_field "$yaml_file" "verify_mode" "$result"
-
-  green "[SCALE] verify_mode=$result"
-}
-
-# --- Main ---
-
-SUBCOMMAND="${1:-}"
-shift || true
-
-case "$SUBCOMMAND" in
-  init)
-    if [ $# -lt 2 ]; then
-      red "Usage: comet-state.sh init <change-name> <workflow>" >&2
-      red "Workflows: full, hotfix, tweak" >&2
-      exit 1
-    fi
-    cmd_init "$@"
-    ;;
-  get)
-    if [ $# -lt 2 ]; then
-      red "Usage: comet-state.sh get <change-name> <field>" >&2
-      exit 1
-    fi
-    cmd_get "$@"
-    ;;
-  set)
-    if [ $# -lt 3 ]; then
-      red "Usage: comet-state.sh set <change-name> <field> <value>" >&2
-      exit 1
-    fi
-    cmd_set "$@"
-    ;;
-  transition)
-    if [ $# -lt 2 ]; then
-      red "Usage: comet-state.sh transition <change-name> <event>" >&2
-      red "Events: open-complete, design-complete, build-complete, verify-pass, verify-fail, archived" >&2
-      exit 1
-    fi
-    cmd_transition "$@"
-    ;;
-  check)
-    if [ $# -lt 2 ]; then
-      red "Usage: comet-state.sh check <change-name> <phase> [--recover]" >&2
-      red "Phases: open, design, build, verify, archive" >&2
-      exit 1
-    fi
-    # Detect --recover flag (3rd argument)
-    if [ "${3:-}" = "--recover" ]; then
-      cmd_recover "$1"
-    else
-      cmd_check "$@"
-    fi
-    ;;
-  scale)
-    if [ $# -lt 1 ]; then
-      red "Usage: comet-state.sh scale <change-name>" >&2
-      exit 1
-    fi
-    cmd_scale "$@"
-    ;;
-  *)
-    red "Unknown subcommand: $SUBCOMMAND" >&2
-    echo "" >&2
-    echo "Usage: comet-state.sh <subcommand> <change-name> [args...]" >&2
-    echo "" >&2
-    echo "Subcommands:" >&2
-    echo "  init <change-name> <workflow>  — Initialize .comet.yaml with workflow defaults" >&2
-    echo "  get <change-name> <field>       — Read a field value from .comet.yaml" >&2
-    echo "  set <change-name> <field> <val> — Update a field value in .comet.yaml" >&2
-    echo "  transition <change-name> <event> — Apply a validated state transition" >&2
-    echo "  check <change-name> <phase>    — Verify entry requirements for a phase" >&2
-    echo "  scale <change-name>             — Assess and set verification mode based on metrics" >&2
-    echo "" >&2
-    echo "Workflows: full, hotfix, tweak" >&2
-    echo "Phases for check: open, design, build, verify, archive" >&2
-    exit 1
-    ;;
-esac
diff --git a/assets/skills/comet/scripts/comet-yaml-validate.js b/assets/skills/comet/scripts/comet-yaml-validate.js
new file mode 100644
index 00000000..6f8e6b62
--- /dev/null
+++ b/assets/skills/comet/scripts/comet-yaml-validate.js
@@ -0,0 +1,68 @@
+#!/usr/bin/env node
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { changeDirFor, fieldValue, KNOWN_KEYS, parseYamlLines, red, green, validateChangeName, yellow } from './comet-lib.js';
+
+const change = process.argv[2];
+validateChangeName(change);
+const changeDir = changeDirFor(change);
+const yaml = join(changeDir, '.comet.yaml');
+let errors = 0;
+let warnings = 0;
+
+function fail(message) {
+  red(`  FAIL: ${message}`);
+  errors += 1;
+}
+
+function warn(message) {
+  yellow(`  WARN: ${message}`);
+  warnings += 1;
+}
+
+function validateEnum(field, value, valid) {
+  if (!value || value === 'null') return;
+  if (!valid.includes(value)) fail(`${field}='${value}' is not valid. Expected: ${valid.join(' ')}`);
+}
+
+console.error(`[VALIDATE] ${yaml}`);
+
+if (!existsSync(yaml)) {
+  fail(`.comet.yaml not found at ${yaml}`);
+} else {
+  const parsed = parseYamlLines(yaml);
+  const required = ['workflow', 'phase', 'design_doc', 'plan', 'build_mode', 'isolation', 'verify_mode', 'verify_result', 'verified_at', 'archived'];
+  for (const field of required) {
+    if (!parsed.keys.includes(field)) fail(`missing required field '${field}'`);
+  }
+
+  validateEnum('workflow', fieldValue(yaml, 'workflow'), ['full', 'hotfix', 'tweak']);
+  validateEnum('phase', fieldValue(yaml, 'phase'), ['open', 'design', 'build', 'verify', 'archive']);
+  validateEnum('build_mode', fieldValue(yaml, 'build_mode'), ['subagent-driven-development', 'executing-plans', 'direct']);
+  validateEnum('build_pause', fieldValue(yaml, 'build_pause'), ['null', 'plan-ready']);
+  validateEnum('isolation', fieldValue(yaml, 'isolation'), ['branch', 'worktree']);
+  validateEnum('verify_mode', fieldValue(yaml, 'verify_mode'), ['light', 'full']);
+  validateEnum('verify_result', fieldValue(yaml, 'verify_result'), ['pending', 'pass', 'fail']);
+  validateEnum('branch_status', fieldValue(yaml, 'branch_status'), ['pending', 'handled']);
+  validateEnum('archived', fieldValue(yaml, 'archived'), ['true', 'false']);
+  validateEnum('direct_override', fieldValue(yaml, 'direct_override'), ['true', 'false']);
+
+  for (const field of ['design_doc', 'plan', 'handoff_context']) {
+    const value = fieldValue(yaml, field);
+    if (value && value !== 'null' && !existsSync(value)) fail(`${field}='${value}' does not exist on disk`);
+  }
+  const handoffHash = fieldValue(yaml, 'handoff_hash');
+  if (handoffHash && handoffHash !== 'null' && !/^[a-f0-9]{64}$/.test(handoffHash)) {
+    fail(`handoff_hash='${handoffHash}' is not a sha256 hex digest`);
+  }
+  for (const key of parsed.keys) {
+    if (!KNOWN_KEYS.has(key)) warn(`unknown field '${key}' found`);
+  }
+}
+
+console.error('');
+if (errors > 0) {
+  red(`${errors} error(s), ${warnings} warning(s) — validation FAILED`);
+  process.exit(1);
+}
+green(`0 errors, ${warnings} warning(s) — validation PASSED`);
diff --git a/assets/skills/comet/scripts/comet-yaml-validate.sh b/assets/skills/comet/scripts/comet-yaml-validate.sh
deleted file mode 100644
index 1d8676f1..00000000
--- a/assets/skills/comet/scripts/comet-yaml-validate.sh
+++ /dev/null
@@ -1,200 +0,0 @@
-#!/bin/bash
-# Comet YAML Schema Validator — validates .comet.yaml structure
-# Usage: comet-yaml-validate.sh <change-name>
-# Exit 0 = valid, exit 1 = errors found (printed to stderr)
-
-set -euo pipefail
-
-red()   { echo -e "\033[31m$1\033[0m" >&2; }
-green() { echo -e "\033[32m$1\033[0m" >&2; }
-warn()  { echo -e "\033[33m$1\033[0m" >&2; }
-
-# Input validation - prevent path traversal
-validate_change_name() {
-  local name="$1"
-  # Reject empty names
-  if [ -z "$name" ]; then
-    red "ERROR: Change name cannot be empty" >&2
-    exit 1
-  fi
-  # Only allow alphanumeric, hyphens, and underscores
-  if [[ ! "$name" =~ ^[a-zA-Z0-9_-]+$ ]]; then
-    red "ERROR: Invalid change name: '$name'" >&2
-    red "Valid characters: a-z, A-Z, 0-9, -, _" >&2
-    exit 1
-  fi
-  # Reject path traversal attempts
-  if [[ "$name" =~ \.\. ]]; then
-    red "ERROR: Change name cannot contain '..' (path traversal not allowed)" >&2
-    exit 1
-  fi
-}
-
-validate_change_name "$1"
-
-CHANGE="$1"
-CHANGE_DIR="openspec/changes/$CHANGE"
-if [ ! -d "$CHANGE_DIR" ] && [ -d "openspec/changes/archive/$CHANGE" ]; then
-  CHANGE_DIR="openspec/changes/archive/$CHANGE"
-fi
-YAML="$CHANGE_DIR/.comet.yaml"
-
-ERRORS=0
-WARNINGS=0
-
-# Helper: get value of a top-level field (handles null, empty, quoted)
-field_value() {
-  local value
-  value=$(grep "^${1}:" "$YAML" 2>/dev/null | sed "s/^${1}: *//" || true)
-  value=$(strip_inline_comment "$value")
-  strip_wrapping_quotes "$value"
-}
-
-strip_inline_comment() {
-  local value="$1"
-  printf '%s\n' "$value" | awk -v squote="'" '
-    {
-      out = ""
-      quote = ""
-      for (i = 1; i <= length($0); i++) {
-        c = substr($0, i, 1)
-        if (quote == "") {
-          if (c == "\"" || c == squote) {
-            quote = c
-          } else if (c == "#" && (i == 1 || substr($0, i - 1, 1) ~ /[[:space:]]/)) {
-            sub(/[[:space:]]+$/, "", out)
-            print out
-            next
-          }
-        } else if (c == quote) {
-          quote = ""
-        }
-        out = out c
-      }
-      print out
-    }
-  '
-}
-
-strip_wrapping_quotes() {
-  local value="$1"
-  case "$value" in
-    \"*\")
-      printf '%s\n' "${value:1:${#value}-2}"
-      ;;
-    \'*\')
-      printf '%s\n' "${value:1:${#value}-2}"
-      ;;
-    *)
-      printf '%s\n' "$value"
-      ;;
-  esac
-}
-
-fail()  { red "  FAIL: $1"; ERRORS=$((ERRORS + 1)); }
-warn_msg() { warn "  WARN: $1"; WARNINGS=$((WARNINGS + 1)); }
-
-echo "[VALIDATE] $YAML" >&2
-
-# --- Required fields ---
-REQUIRED_FIELDS="workflow phase design_doc plan build_mode isolation verify_mode verify_result verified_at archived"
-for field in $REQUIRED_FIELDS; do
-  if ! grep -q "^${field}:" "$YAML" 2>/dev/null; then
-    fail "missing required field '$field'"
-  fi
-done
-
-# --- Enum validation ---
-validate_enum() {
-  local field="$1" value="$2"
-  shift 2
-  local valid_values="$*"
-
-  # null or empty is always acceptable
-  if [ -z "$value" ] || [ "$value" = "null" ]; then
-    return 0
-  fi
-
-  for v in $valid_values; do
-    if [ "$value" = "$v" ]; then
-      return 0
-    fi
-  done
-  fail "$field='$value' is not valid. Expected: $valid_values"
-}
-
-workflow=$(field_value "workflow")
-phase=$(field_value "phase")
-build_mode=$(field_value "build_mode")
-build_pause=$(field_value "build_pause")
-isolation=$(field_value "isolation")
-verify_mode=$(field_value "verify_mode")
-verify_result=$(field_value "verify_result")
-branch_status=$(field_value "branch_status")
-archived=$(field_value "archived")
-direct_override=$(field_value "direct_override")
-design_doc=$(field_value "design_doc")
-plan=$(field_value "plan")
-handoff_context=$(field_value "handoff_context")
-handoff_hash=$(field_value "handoff_hash")
-
-validate_enum "workflow"      "$workflow"      "full hotfix tweak"
-validate_enum "phase"         "$phase"          "open design build verify archive"
-validate_enum "build_mode"    "$build_mode"     "subagent-driven-development executing-plans direct"
-validate_enum "build_pause"   "$build_pause"     "null plan-ready"
-validate_enum "isolation"     "$isolation"      "branch worktree"
-validate_enum "verify_mode"   "$verify_mode"    "light full"
-validate_enum "verify_result" "$verify_result"  "pending pass fail"
-validate_enum "branch_status" "$branch_status"  "pending handled"
-validate_enum "archived"      "$archived"       "true false"
-validate_enum "direct_override" "$direct_override" "true false"
-
-# --- Path validation ---
-
-if [ -n "$design_doc" ] && [ "$design_doc" != "null" ]; then
-  if [ ! -f "$design_doc" ]; then
-    fail "design_doc='$design_doc' does not exist on disk"
-  fi
-fi
-
-if [ -n "$plan" ] && [ "$plan" != "null" ]; then
-  if [ ! -f "$plan" ]; then
-    fail "plan='$plan' does not exist on disk"
-  fi
-fi
-
-if [ -n "$handoff_context" ] && [ "$handoff_context" != "null" ]; then
-  if [ ! -f "$handoff_context" ]; then
-    fail "handoff_context='$handoff_context' does not exist on disk"
-  fi
-fi
-
-if [ -n "$handoff_hash" ] && [ "$handoff_hash" != "null" ]; then
-  if [[ ! "$handoff_hash" =~ ^[a-f0-9]{64}$ ]]; then
-    fail "handoff_hash='$handoff_hash' is not a sha256 hex digest"
-  fi
-fi
-
-# --- Unknown keys check ---
-KNOWN_KEYS="workflow phase design_doc plan build_mode build_pause isolation verify_mode verify_result verification_report branch_status verified_at created_at archived direct_override build_command verify_command handoff_context handoff_hash base_ref"
-while IFS=: read -r key _; do
-  key="${key// /}"
-  [ -z "$key" ] && continue
-  found=0
-  for known in $KNOWN_KEYS; do
-    [ "$key" = "$known" ] && found=1 && break
-  done
-  if [ "$found" -eq 0 ]; then
-    warn_msg "unknown field '$key' found"
-  fi
-done < "$YAML"
-
-# --- Summary ---
-echo "" >&2
-if [ "$ERRORS" -gt 0 ]; then
-  red "$ERRORS error(s), $WARNINGS warning(s) — validation FAILED"
-  exit 1
-else
-  green "0 errors, $WARNINGS warning(s) — validation PASSED"
-  exit 0
-fi
diff --git a/package.json b/package.json
index ba7acf75..d89ae1ae 100644
--- a/package.json
+++ b/package.json
@@ -36,7 +36,6 @@
     "lint:fix": "eslint src/ --fix",
     "format": "prettier --write src/",
     "format:check": "prettier --check src/",
-    "test:shell": "node scripts/run-bats.js test/shell/*.bats",
     "prepare": "pnpm run build",
     "prepublishOnly": "node scripts/prepublish-check.js && pnpm run build",
     "postinstall": "node scripts/postinstall.js"
@@ -57,6 +56,7 @@
   },
   "dependencies": {
     "@inquirer/prompts": "^8.4.3",
-    "commander": "^14.0.0"
+    "commander": "^14.0.0",
+    "yaml": "^2.9.0"
   }
 }
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index 0900ecc3..0eb4c9dd 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -14,6 +14,9 @@ importers:
       commander:
         specifier: ^14.0.0
         version: 14.0.3
+      yaml:
+        specifier: ^2.9.0
+        version: 2.9.0
     devDependencies:
       '@eslint/js':
         specifier: ^10.0.1
@@ -38,7 +41,7 @@ importers:
         version: 8.59.3(eslint@10.4.0)(typescript@5.9.3)
       vitest:
         specifier: ^4.1.6
-        version: 4.1.6(@types/node@24.12.4)(@vitest/coverage-v8@4.1.6)(vite@7.3.3(@types/node@24.12.4))
+        version: 4.1.6(@types/node@24.12.4)(@vitest/coverage-v8@4.1.6)(vite@7.3.3(@types/node@24.12.4)(yaml@2.9.0))
 
 packages:
 
@@ -1170,6 +1173,11 @@ packages:
     resolution: {integrity: sha512-BN22B5eaMMI9UMtjrGd5g5eCYPpCPDUy0FJXbYsaT5zYxjFOckS53SQDE3pWkVoWpHXVb3BrYcEN4Twa55B5cA==}
     engines: {node: '>=0.10.0'}
 
+  yaml@2.9.0:
+    resolution: {integrity: sha512-2AvhNX3mb8zd6Zy7INTtSpl1F15HW6Wnqj0srWlkKLcpYl/gMIMJiyuGq2KeI2YFxUPjdlB+3Lc10seMLtL4cA==}
+    engines: {node: '>= 14.6'}
+    hasBin: true
+
   yocto-queue@0.1.0:
     resolution: {integrity: sha512-rVksvsnNCdJ/ohGc6xgPwyN8eheCxsiLM8mxuE/t/mOVqJewPuO1miLpTHQiRgTKCLexL4MeAFVagts7HmNZ2Q==}
     engines: {node: '>=10'}
@@ -1646,7 +1654,7 @@ snapshots:
       obug: 2.1.1
       std-env: 4.1.0
       tinyrainbow: 3.1.0
-      vitest: 4.1.6(@types/node@24.12.4)(@vitest/coverage-v8@4.1.6)(vite@7.3.3(@types/node@24.12.4))
+      vitest: 4.1.6(@types/node@24.12.4)(@vitest/coverage-v8@4.1.6)(vite@7.3.3(@types/node@24.12.4)(yaml@2.9.0))
 
   '@vitest/expect@4.1.6':
     dependencies:
@@ -1657,13 +1665,13 @@ snapshots:
       chai: 6.2.2
       tinyrainbow: 3.1.0
 
-  '@vitest/mocker@4.1.6(vite@7.3.3(@types/node@24.12.4))':
+  '@vitest/mocker@4.1.6(vite@7.3.3(@types/node@24.12.4)(yaml@2.9.0))':
     dependencies:
       '@vitest/spy': 4.1.6
       estree-walker: 3.0.3
       magic-string: 0.30.21
     optionalDependencies:
-      vite: 7.3.3(@types/node@24.12.4)
+      vite: 7.3.3(@types/node@24.12.4)(yaml@2.9.0)
 
   '@vitest/pretty-format@4.1.6':
     dependencies:
@@ -2100,7 +2108,7 @@ snapshots:
     dependencies:
       punycode: 2.3.1
 
-  vite@7.3.3(@types/node@24.12.4):
+  vite@7.3.3(@types/node@24.12.4)(yaml@2.9.0):
     dependencies:
       esbuild: 0.27.7
       fdir: 6.5.0(picomatch@4.0.4)
@@ -2111,11 +2119,12 @@ snapshots:
     optionalDependencies:
       '@types/node': 24.12.4
       fsevents: 2.3.3
+      yaml: 2.9.0
 
-  vitest@4.1.6(@types/node@24.12.4)(@vitest/coverage-v8@4.1.6)(vite@7.3.3(@types/node@24.12.4)):
+  vitest@4.1.6(@types/node@24.12.4)(@vitest/coverage-v8@4.1.6)(vite@7.3.3(@types/node@24.12.4)(yaml@2.9.0)):
     dependencies:
       '@vitest/expect': 4.1.6
-      '@vitest/mocker': 4.1.6(vite@7.3.3(@types/node@24.12.4))
+      '@vitest/mocker': 4.1.6(vite@7.3.3(@types/node@24.12.4)(yaml@2.9.0))
       '@vitest/pretty-format': 4.1.6
       '@vitest/runner': 4.1.6
       '@vitest/snapshot': 4.1.6
@@ -2132,7 +2141,7 @@ snapshots:
       tinyexec: 1.1.2
       tinyglobby: 0.2.16
       tinyrainbow: 3.1.0
-      vite: 7.3.3(@types/node@24.12.4)
+      vite: 7.3.3(@types/node@24.12.4)(yaml@2.9.0)
       why-is-node-running: 2.3.0
     optionalDependencies:
       '@types/node': 24.12.4
@@ -2151,4 +2160,6 @@ snapshots:
 
   word-wrap@1.2.5: {}
 
+  yaml@2.9.0: {}
+
   yocto-queue@0.1.0: {}
diff --git a/scripts/run-bats.js b/scripts/run-bats.js
deleted file mode 100644
index 48ed9ead..00000000
--- a/scripts/run-bats.js
+++ /dev/null
@@ -1,189 +0,0 @@
-#!/usr/bin/env node
-import { spawnSync } from 'node:child_process';
-import { mkdtempSync, readFileSync, readdirSync, rmSync, writeFileSync } from 'node:fs';
-import { tmpdir } from 'node:os';
-import path from 'node:path';
-
-function escapeRegExp(value) {
-  return value.replace(/[.+?^${}()|[\]\\]/g, '\\$&');
-}
-
-function findUsableBash() {
-  const candidates = [
-    process.env.COMET_TEST_BASH,
-    process.env.COMET_BASH,
-    'bash',
-    ...(process.platform === 'win32'
-      ? [
-          'C:\\Program Files\\Git\\bin\\bash.exe',
-          'C:\\Program Files\\Git\\usr\\bin\\bash.exe',
-          'C:\\Program Files (x86)\\Git\\bin\\bash.exe',
-        ]
-      : []),
-  ].filter(Boolean);
-
-  for (const candidate of [...new Set(candidates)]) {
-    const probe = spawnSync(candidate, ['-lc', 'uname -s'], { encoding: 'utf8' });
-    if (probe.status === 0 && probe.stdout.trim()) {
-      if (process.platform === 'win32' && /linux/i.test(probe.stdout)) continue;
-      return candidate;
-    }
-  }
-  return null;
-}
-
-const bashCommand = findUsableBash();
-const bashUname = bashCommand
-  ? (spawnSync(bashCommand, ['-lc', 'uname -s'], { encoding: 'utf8' }).stdout || '').trim()
-  : '';
-const isGitBash = /^(MINGW|MSYS|CYGWIN)/.test(bashUname);
-
-function toBashPath(filePath) {
-  const resolved = path.resolve(filePath).replace(/\\/g, '/');
-  const driveMatch = resolved.match(/^([A-Za-z]):\/(.*)$/);
-  if (!driveMatch) return resolved;
-  if (process.platform === 'win32' && isGitBash) {
-    return `/${driveMatch[1].toLowerCase()}/${driveMatch[2]}`;
-  }
-  return `/mnt/${driveMatch[1].toLowerCase()}/${driveMatch[2]}`;
-}
-
-function shellQuote(value) {
-  return `'${value.replace(/'/g, `'\\''`)}'`;
-}
-
-function expandArgs(args) {
-  const files = [];
-  for (const arg of args) {
-    if (!arg.includes('*')) {
-      files.push(arg);
-      continue;
-    }
-
-    const dir = path.dirname(arg);
-    const base = path.basename(arg);
-    const pattern = new RegExp(`^${base.split('*').map(escapeRegExp).join('.*')}$`);
-    for (const entry of readdirSync(dir)) {
-      if (pattern.test(entry)) files.push(path.join(dir, entry));
-    }
-  }
-  return files.sort();
-}
-
-function parseBats(content) {
-  const lines = content.replace(/\r\n/g, '\n').split('\n');
-  const prelude = [];
-  const tests = [];
-  let current = null;
-
-  for (const line of lines) {
-    const testMatch = line.match(/^@test "(.+)" \{\s*$/);
-    if (testMatch) {
-      current = { name: testMatch[1], body: [] };
-      continue;
-    }
-
-    if (current) {
-      if (/^\}\s*$/.test(line)) {
-        tests.push(current);
-        current = null;
-      } else {
-        current.body.push(line);
-      }
-      continue;
-    }
-
-    prelude.push(line);
-  }
-
-  if (current) {
-    throw new Error(`Unclosed @test block: ${current.name}`);
-  }
-
-  return { prelude, tests };
-}
-
-function compileBats(file) {
-  const content = readFileSync(file, 'utf8');
-  const { prelude, tests } = parseBats(content);
-  const testDir = toBashPath(path.dirname(file));
-  const chunks = [
-    '#!/usr/bin/env bash',
-    'set +e',
-    `export BATS_TEST_DIRNAME=${shellQuote(testDir)}`,
-    'status=0',
-    'output=""',
-    'run() {',
-    '  output="$("$@" 2>&1)"',
-    '  status=$?',
-    '  return 0',
-    '}',
-    ...prelude,
-  ];
-
-  tests.forEach((test, index) => {
-    chunks.push(`__bats_test_${index + 1}() {`);
-    chunks.push('  set -e');
-    chunks.push(...test.body.map((line) => `  ${line}`));
-    chunks.push('}');
-  });
-
-  chunks.push('failures=0');
-  tests.forEach((test, index) => {
-    const fn = `__bats_test_${index + 1}`;
-    chunks.push(`__bats_output="$(mktemp)"`);
-    chunks.push(`if ( trap teardown EXIT; setup; ${fn} ) >"$__bats_output" 2>&1; then`);
-    chunks.push(`  echo "ok ${index + 1} - ${test.name}"`);
-    chunks.push('else');
-    chunks.push(`  echo "not ok ${index + 1} - ${test.name}"`);
-    chunks.push('  cat "$__bats_output" >&2');
-    chunks.push('  failures=$((failures + 1))');
-    chunks.push('fi');
-    chunks.push('rm -f "$__bats_output"');
-  });
-  chunks.push('exit "$failures"');
-
-  return chunks.join('\n');
-}
-
-const args = process.argv.slice(2);
-if (args.length === 0) {
-  console.error('Usage: run-bats.js <file.bats> [...]');
-  process.exit(1);
-}
-
-const files = expandArgs(args);
-if (files.length === 0) {
-  console.error(`No .bats files matched: ${args.join(' ')}`);
-  process.exit(1);
-}
-
-if (!bashCommand) {
-  console.error('ERROR: usable bash not found. Install Git Bash or set COMET_TEST_BASH/COMET_BASH to a working bash executable.');
-  console.error('Windows WSL launcher bash.exe is not supported for Comet shell tests.');
-  process.exit(1);
-}
-
-let failures = 0;
-for (const file of files) {
-  const tests = parseBats(readFileSync(file, 'utf8')).tests;
-  console.log(`# ${file}`);
-  console.log(`1..${tests.length}`);
-
-  const tempDir = mkdtempSync(path.join(tmpdir(), 'comet-bats-'));
-  const compiled = path.join(tempDir, 'compiled.bash');
-  writeFileSync(compiled, compileBats(file), 'utf8');
-
-  const result = spawnSync(bashCommand, [toBashPath(compiled)], {
-    cwd: process.cwd(),
-    encoding: 'utf8',
-  });
-
-  if (result.stdout) process.stdout.write(result.stdout);
-  if (result.stderr) process.stderr.write(result.stderr);
-  if (result.status !== 0) failures += result.status ?? 1;
-
-  rmSync(tempDir, { recursive: true, force: true });
-}
-
-process.exit(failures === 0 ? 0 : 1);
diff --git a/test/shell/comet-state.bats b/test/shell/comet-state.bats
deleted file mode 100644
index 6999aa07..00000000
--- a/test/shell/comet-state.bats
+++ /dev/null
@@ -1,214 +0,0 @@
-#!/usr/bin/env bats
-
-setup() {
-  export TEST_TMPDIR="$(mktemp -d)"
-  export SCRIPT_SOURCE="$BATS_TEST_DIRNAME/../../assets/skills/comet/scripts/comet-state.sh"
-  export SCRIPT_PATH="$TEST_TMPDIR/comet-state.sh"
-  cd "$TEST_TMPDIR"
-  tr -d '\r' < "$SCRIPT_SOURCE" > "$SCRIPT_PATH"
-  mkdir -p openspec/changes
-}
-
-teardown() {
-  rm -rf "$TEST_TMPDIR"
-}
-
-# --- init subcommand ---
-
-@test "init creates .comet.yaml with full workflow defaults" {
-  run bash "$SCRIPT_PATH" init my-change full
-  [ "$status" -eq 0 ]
-  [ -f "openspec/changes/my-change/.comet.yaml" ]
-  grep -q "phase: open" "openspec/changes/my-change/.comet.yaml"
-  grep -q "verify_mode: null" "openspec/changes/my-change/.comet.yaml"
-  grep -q "verification_report: null" "openspec/changes/my-change/.comet.yaml"
-  grep -q "branch_status: pending" "openspec/changes/my-change/.comet.yaml"
-}
-
-@test "init creates .comet.yaml with hotfix workflow defaults" {
-  run bash "$SCRIPT_PATH" init hotfix-123 hotfix
-  [ "$status" -eq 0 ]
-  grep -q "phase: open" "openspec/changes/hotfix-123/.comet.yaml"
-  grep -q "build_mode: direct" "openspec/changes/hotfix-123/.comet.yaml"
-}
-
-@test "init creates .comet.yaml with tweak workflow defaults" {
-  run bash "$SCRIPT_PATH" init tweak-abc tweak
-  [ "$status" -eq 0 ]
-  grep -q "phase: open" "openspec/changes/tweak-abc/.comet.yaml"
-  grep -q "isolation: branch" "openspec/changes/tweak-abc/.comet.yaml"
-}
-
-@test "init rejects duplicate .comet.yaml" {
-  bash "$SCRIPT_PATH" init my-change full
-  run bash "$SCRIPT_PATH" init my-change full
-  [ "$status" -ne 0 ]
-}
-
-@test "init rejects invalid workflow" {
-  run bash "$SCRIPT_PATH" init my-change invalid
-  [ "$status" -ne 0 ]
-}
-
-@test "init rejects empty change name" {
-  run bash "$SCRIPT_PATH" init "" full
-  [ "$status" -ne 0 ]
-}
-
-@test "init rejects change name with special characters" {
-  run bash "$SCRIPT_PATH" init "my change" full
-  [ "$status" -ne 0 ]
-}
-
-@test "init rejects path traversal" {
-  run bash "$SCRIPT_PATH" init ".." full
-  [ "$status" -ne 0 ]
-}
-
-# --- get subcommand ---
-
-@test "get retrieves field value" {
-  bash "$SCRIPT_PATH" init my-change full
-  run bash "$SCRIPT_PATH" get my-change phase
-  [ "$status" -eq 0 ]
-  [ "$output" = "open" ]
-}
-
-@test "get fails for missing change" {
-  run bash "$SCRIPT_PATH" get nonexistent phase
-  [ "$status" -ne 0 ]
-}
-
-# --- set subcommand ---
-
-@test "set updates a field value" {
-  bash "$SCRIPT_PATH" init my-change full
-  run bash "$SCRIPT_PATH" set my-change phase build
-  [ "$status" -eq 0 ]
-
-  run bash "$SCRIPT_PATH" get my-change phase
-  [ "$output" = "build" ]
-}
-
-@test "set rejects unknown field" {
-  bash "$SCRIPT_PATH" init my-change full
-  run bash "$SCRIPT_PATH" set my-change invalid_field value
-  [ "$status" -ne 0 ]
-}
-
-@test "set validates phase enum" {
-  bash "$SCRIPT_PATH" init my-change full
-  run bash "$SCRIPT_PATH" set my-change phase invalid
-  [ "$status" -ne 0 ]
-}
-
-@test "set validates verify_mode enum" {
-  bash "$SCRIPT_PATH" init my-change full
-  run bash "$SCRIPT_PATH" set my-change verify_mode invalid
-  [ "$status" -ne 0 ]
-}
-
-@test "set validates archived enum" {
-  bash "$SCRIPT_PATH" init my-change full
-  run bash "$SCRIPT_PATH" set my-change archived maybe
-  [ "$status" -ne 0 ]
-}
-
-@test "set validates branch_status enum" {
-  bash "$SCRIPT_PATH" init my-change full
-  run bash "$SCRIPT_PATH" set my-change branch_status maybe
-  [ "$status" -ne 0 ]
-}
-
-@test "set allows free-form design_doc value" {
-  bash "$SCRIPT_PATH" init my-change full
-  run bash "$SCRIPT_PATH" set my-change design_doc "docs/design.md"
-  [ "$status" -eq 0 ]
-}
-
-# --- check subcommand ---
-
-@test "check open passes with initialized state" {
-  bash "$SCRIPT_PATH" init my-change full
-  run bash "$SCRIPT_PATH" check my-change open
-  [ "$status" -eq 0 ]
-}
-
-@test "check open fails without .comet.yaml" {
-  mkdir -p openspec/changes/my-change
-  run bash "$SCRIPT_PATH" check my-change open
-  [ "$status" -ne 0 ]
-}
-
-@test "check open fails if phase is not open" {
-  bash "$SCRIPT_PATH" init my-change full
-  bash "$SCRIPT_PATH" set my-change phase design
-  run bash "$SCRIPT_PATH" check my-change open
-  [ "$status" -ne 0 ]
-}
-
-@test "check design passes with correct state" {
-  bash "$SCRIPT_PATH" init my-change full
-  bash "$SCRIPT_PATH" set my-change phase design
-  echo "content" > openspec/changes/my-change/proposal.md
-  echo "content" > openspec/changes/my-change/design.md
-  echo "content" > openspec/changes/my-change/tasks.md
-  run bash "$SCRIPT_PATH" check my-change design
-  [ "$status" -eq 0 ]
-}
-
-@test "check design fails if design_doc is set (not empty)" {
-  bash "$SCRIPT_PATH" init my-change full
-  bash "$SCRIPT_PATH" set my-change phase design
-  bash "$SCRIPT_PATH" set my-change design_doc "some-doc.md"
-  echo "content" > openspec/changes/my-change/proposal.md
-  echo "content" > openspec/changes/my-change/design.md
-  echo "content" > openspec/changes/my-change/tasks.md
-  run bash "$SCRIPT_PATH" check my-change design
-  [ "$status" -ne 0 ]
-}
-
-# --- scale subcommand ---
-
-@test "scale defaults to light for small changes" {
-  bash "$SCRIPT_PATH" init my-change full
-  mkdir -p openspec/changes/my-change
-  echo "- [ ] task 1" > openspec/changes/my-change/tasks.md
-  run bash "$SCRIPT_PATH" scale my-change
-  [ "$status" -eq 0 ]
-
-  run bash "$SCRIPT_PATH" get my-change verify_mode
-  [ "$output" = "light" ]
-}
-
-# --- usage errors ---
-
-@test "unknown subcommand exits with error" {
-  run bash "$SCRIPT_PATH" unknown-cmd
-  [ "$status" -ne 0 ]
-}
-
-@test "init missing args shows usage" {
-  run bash "$SCRIPT_PATH" init my-change
-  [ "$status" -ne 0 ]
-}
-
-@test "get missing args shows usage" {
-  run bash "$SCRIPT_PATH" get my-change
-  [ "$status" -ne 0 ]
-}
-
-@test "set missing args shows usage" {
-  run bash "$SCRIPT_PATH" set my-change phase
-  [ "$status" -ne 0 ]
-}
-
-@test "check missing args shows usage" {
-  run bash "$SCRIPT_PATH" check my-change
-  [ "$status" -ne 0 ]
-}
-
-@test "scale missing args shows usage" {
-  run bash "$SCRIPT_PATH" scale
-  [ "$status" -ne 0 ]
-}
diff --git a/test/ts/comet-scripts.test.ts b/test/ts/comet-scripts.test.ts
index 5863099e..3ac23ca5 100644
--- a/test/ts/comet-scripts.test.ts
+++ b/test/ts/comet-scripts.test.ts
@@ -6,53 +6,11 @@ import path from 'path';
 
 const scriptsDir = path.resolve('assets', 'skills', 'comet', 'scripts');
 
-function findUsableBash(): string | null {
-  const candidates = [
-    process.env.COMET_TEST_BASH,
-    'bash',
-    ...(process.platform === 'win32'
-      ? [
-          'C:\\Program Files\\Git\\bin\\bash.exe',
-          'C:\\Program Files\\Git\\usr\\bin\\bash.exe',
-          'C:\\Program Files (x86)\\Git\\bin\\bash.exe',
-        ]
-      : []),
-  ].filter((candidate): candidate is string => Boolean(candidate));
-
-  for (const candidate of [...new Set(candidates)]) {
-    const probe = spawnSync(candidate, ['-lc', 'uname -s'], { encoding: 'utf-8' });
-    if (probe.status === 0 && probe.stdout.trim()) {
-      if (process.platform === 'win32' && /linux/i.test(probe.stdout)) continue;
-      return candidate;
-    }
-  }
-  return null;
-}
-
-const bashCommand = findUsableBash();
-const bashUname = bashCommand
-  ? (spawnSync(bashCommand, ['-lc', 'uname -s'], { encoding: 'utf-8' }).stdout || '').trim()
-  : '';
-const isGitBash = /^(MINGW|MSYS|CYGWIN)/.test(bashUname);
-
-function toBashPath(filePath: string): string {
-  const resolved = path.resolve(filePath).replace(/\\/g, '/');
-  const driveMatch = resolved.match(/^([A-Za-z]):\/(.*)$/);
-  if (!driveMatch) return resolved;
-  if (process.platform === 'win32' && isGitBash) {
-    return `/${driveMatch[1].toLowerCase()}/${driveMatch[2]}`;
-  }
-  return `/mnt/${driveMatch[1].toLowerCase()}/${driveMatch[2]}`;
-}
-
-function runBash(cwd: string, script: string, args: string[] = [], env: NodeJS.ProcessEnv = {}) {
-  if (!bashCommand) {
-    throw new Error('comet shell script tests require Bash or Git Bash');
-  }
-  return spawnSync(bashCommand, [toBashPath(script), ...args], {
+function runNode(cwd: string, script: string, args: string[] = [], env: NodeJS.ProcessEnv = {}) {
+  return spawnSync(process.execPath, [script, ...args], {
     cwd,
     encoding: 'utf-8',
-    env: { ...process.env, ...env },
+    env: { ...process.env, NODE_NO_WARNINGS: '1', ...env },
   });
 }
 
@@ -71,9 +29,7 @@ async function createChange(tmpDir: string, name: string, yaml: string, tasks =
   return changeDir;
 }
 
-const describeShell = bashCommand ? describe : describe.skip;
-
-describeShell('comet shell scripts', () => {
+describe('comet node scripts', () => {
   let tmpDir: string;
   let guardScript: string;
   let stateScript: string;
@@ -84,21 +40,23 @@ describeShell('comet shell scripts', () => {
       `comet-scripts-${Date.now()}-${Math.random().toString(36).slice(2)}`,
     );
     await fs.mkdir(tmpDir, { recursive: true });
+    await fs.writeFile(path.join(tmpDir, 'package.json'), JSON.stringify({ type: 'module' }));
     const tmpScriptsDir = path.join(tmpDir, 'scripts');
     await fs.mkdir(tmpScriptsDir, { recursive: true });
     for (const name of [
-      'comet-env.sh',
-      'comet-archive.sh',
-      'comet-guard.sh',
-      'comet-handoff.sh',
-      'comet-state.sh',
-      'comet-yaml-validate.sh',
+      'comet-lib.js',
+      'comet-env.js',
+      'comet-archive.js',
+      'comet-guard.js',
+      'comet-handoff.js',
+      'comet-state.js',
+      'comet-yaml-validate.js',
     ]) {
       const content = await fs.readFile(path.join(scriptsDir, name), 'utf-8');
-      await fs.writeFile(path.join(tmpScriptsDir, name), content.replace(/\r\n/g, '\n'));
+      await fs.writeFile(path.join(tmpScriptsDir, name), content);
     }
-    guardScript = path.join(tmpScriptsDir, 'comet-guard.sh');
-    stateScript = path.join(tmpScriptsDir, 'comet-state.sh');
+    guardScript = path.join(tmpScriptsDir, 'comet-guard.js');
+    stateScript = path.join(tmpScriptsDir, 'comet-state.js');
   });
 
   afterEach(async () => {
@@ -106,7 +64,7 @@ describeShell('comet shell scripts', () => {
   });
 
   it('initializes a new change directory with workflow defaults', async () => {
-    const result = runBash(tmpDir, stateScript, ['init', 'new-full-change', 'full']);
+    const result = runNode(tmpDir, stateScript, ['init', 'new-full-change', 'full']);
     const yaml = await fs.readFile(
       path.join(tmpDir, 'openspec', 'changes', 'new-full-change', '.comet.yaml'),
       'utf-8',
@@ -120,7 +78,7 @@ describeShell('comet shell scripts', () => {
   }, 20_000);
 
   it('initializes build_pause as null for new changes', async () => {
-    const result = runBash(tmpDir, stateScript, ['init', 'pause-defaults', 'full']);
+    const result = runNode(tmpDir, stateScript, ['init', 'pause-defaults', 'full']);
     const yaml = await fs.readFile(
       path.join(tmpDir, 'openspec', 'changes', 'pause-defaults', '.comet.yaml'),
       'utf-8',
@@ -130,80 +88,26 @@ describeShell('comet shell scripts', () => {
     expect(yaml).toContain('build_pause: null');
   }, 20_000);
 
-  it('comet-env.sh exports bundled script paths from its own directory', async () => {
-    const envScript = path.join(tmpDir, 'scripts', 'comet-env.sh');
-    const checkScript = path.join(tmpDir, 'check-env.sh');
-    await writeFile(
-      checkScript,
-      [
-        '#!/bin/bash',
-        `. "${toBashPath(envScript)}"`,
-        'printf "%s\\n%s\\n%s\\n%s\\n%s\\n" "$COMET_STATE" "$COMET_GUARD" "$COMET_HANDOFF" "$COMET_ARCHIVE" "$COMET_BASH"',
-        '',
-      ].join('\n'),
-    );
-    const result = runBash(tmpDir, checkScript);
+  it('comet-env.js outputs bundled script paths from its own directory', async () => {
+    const envScript = path.join(tmpDir, 'scripts', 'comet-env.js');
+    const result = runNode(tmpDir, envScript);
+    const env = JSON.parse(result.stdout);
 
     expect(result.status).toBe(0);
     expect(result.stderr).toBe('');
-    expect(result.stdout).toContain('comet-state.sh');
-    expect(result.stdout).toContain('comet-guard.sh');
-    expect(result.stdout).toContain('comet-handoff.sh');
-    expect(result.stdout).toContain('comet-archive.sh');
-    expect(result.stdout).toContain('bash');
+    expect(env.COMET_STATE).toContain('comet-state.js');
+    expect(env.COMET_GUARD).toContain('comet-guard.js');
+    expect(env.COMET_HANDOFF).toContain('comet-handoff.js');
+    expect(env.COMET_ARCHIVE).toContain('comet-archive.js');
   }, 20_000);
 
-  it('comet-env.sh returns failure when a bundled script is missing', async () => {
-    const envScript = path.join(tmpDir, 'scripts', 'comet-env.sh');
-    await fs.rm(path.join(tmpDir, 'scripts', 'comet-guard.sh'));
-    const checkScript = path.join(tmpDir, 'check-env-missing.sh');
-    await writeFile(
-      checkScript,
-      [
-        '#!/bin/bash',
-        `. "${toBashPath(envScript)}"`,
-        'status=$?',
-        'echo "source-status=$status"',
-        'exit "$status"',
-        '',
-      ].join('\n'),
-    );
-
-    const result = runBash(tmpDir, checkScript);
+  it('comet-env.js returns failure when a bundled script is missing', async () => {
+    const envScript = path.join(tmpDir, 'scripts', 'comet-env.js');
+    await fs.rm(path.join(tmpDir, 'scripts', 'comet-guard.js'));
+    const result = runNode(tmpDir, envScript);
 
     expect(result.status).toBe(1);
     expect(result.stderr).toContain('ERROR: Comet scripts not found');
-    expect(result.stdout).toContain('source-status=1');
-  }, 20_000);
-
-  it('comet-env.sh does not change caller shell options when sourced', async () => {
-    const envScript = path.join(tmpDir, 'scripts', 'comet-env.sh');
-    const checkScript = path.join(tmpDir, 'check-env-options.sh');
-    await writeFile(
-      checkScript,
-      [
-        '#!/bin/bash',
-        'set +e',
-        'set +u',
-        'set +o pipefail',
-        `. "${toBashPath(envScript)}"`,
-        'case "$-" in *e*) echo errexit-on ;; *) echo errexit-off ;; esac',
-        'case "$-" in *u*) echo nounset-on ;; *) echo nounset-off ;; esac',
-        "if set -o | grep -E '^pipefail[[:space:]]+on' >/dev/null; then",
-        '  echo pipefail-on',
-        'else',
-        '  echo pipefail-off',
-        'fi',
-        '',
-      ].join('\n'),
-    );
-
-    const result = runBash(tmpDir, checkScript);
-
-    expect(result.status).toBe(0);
-    expect(result.stdout).toContain('errexit-off');
-    expect(result.stdout).toContain('nounset-off');
-    expect(result.stdout).toContain('pipefail-off');
   }, 20_000);
 
   it('blocks build phase when the project build command fails', async () => {
@@ -230,14 +134,14 @@ describeShell('comet shell scripts', () => {
       JSON.stringify({ scripts: { build: 'node -e "process.exit(1)"' } }),
     );
 
-    const result = runBash(tmpDir, guardScript, ['broken-build', 'build']);
+    const result = runNode(tmpDir, guardScript, ['broken-build', 'build']);
 
     expect(result.status).not.toBe(0);
     expect(result.stderr).toContain('[FAIL] Build passes');
   }, 20_000);
 
   it('generates a design handoff and requires minimal design doc linkage before leaving design', async () => {
-    const handoffScript = path.join(tmpDir, 'scripts', 'comet-handoff.sh');
+    const handoffScript = path.join(tmpDir, 'scripts', 'comet-handoff.js');
     await createChange(
       tmpDir,
       'handoff-change',
@@ -262,13 +166,13 @@ describeShell('comet shell scripts', () => {
       'delta spec\n',
     );
 
-    const handoff = runBash(tmpDir, handoffScript, ['handoff-change', 'design', '--write']);
-    const contextPath = runBash(tmpDir, stateScript, [
+    const handoff = runNode(tmpDir, handoffScript, ['handoff-change', 'design', '--write']);
+    const contextPath = runNode(tmpDir, stateScript, [
       'get',
       'handoff-change',
       'handoff_context',
     ]).stdout.trim();
-    const contextHash = runBash(tmpDir, stateScript, [
+    const contextHash = runNode(tmpDir, stateScript, [
       'get',
       'handoff-change',
       'handoff_hash',
@@ -305,14 +209,14 @@ describeShell('comet shell scripts', () => {
         '',
       ].join('\n'),
     );
-    runBash(tmpDir, stateScript, [
+    runNode(tmpDir, stateScript, [
       'set',
       'handoff-change',
       'design_doc',
       'docs/superpowers/specs/handoff-design.md',
     ]);
 
-    const result = runBash(tmpDir, guardScript, ['handoff-change', 'design']);
+    const result = runNode(tmpDir, guardScript, ['handoff-change', 'design']);
 
     expect(result.status).toBe(0);
     expect(result.stderr).toContain('[PASS] design handoff context exists');
@@ -322,8 +226,8 @@ describeShell('comet shell scripts', () => {
   }, 20_000);
 
   it('reads comet yaml fields without including trailing comments', async () => {
-    const handoffScript = path.join(tmpDir, 'scripts', 'comet-handoff.sh');
-    const validateScript = path.join(tmpDir, 'scripts', 'comet-yaml-validate.sh');
+    const handoffScript = path.join(tmpDir, 'scripts', 'comet-handoff.js');
+    const validateScript = path.join(tmpDir, 'scripts', 'comet-yaml-validate.js');
     await createChange(
       tmpDir,
       'commented-yaml',
@@ -343,9 +247,9 @@ describeShell('comet shell scripts', () => {
       ].join('\n'),
     );
 
-    const phase = runBash(tmpDir, stateScript, ['get', 'commented-yaml', 'phase']);
-    const validate = runBash(tmpDir, validateScript, ['commented-yaml']);
-    const handoff = runBash(tmpDir, handoffScript, ['commented-yaml', 'design', '--write']);
+    const phase = runNode(tmpDir, stateScript, ['get', 'commented-yaml', 'phase']);
+    const validate = runNode(tmpDir, validateScript, ['commented-yaml']);
+    const handoff = runNode(tmpDir, handoffScript, ['commented-yaml', 'design', '--write']);
 
     expect(phase.status).toBe(0);
     expect(phase.stdout.trim()).toBe('design');
@@ -354,7 +258,7 @@ describeShell('comet shell scripts', () => {
   }, 20_000);
 
   it('accepts design doc frontmatter after a BOM and leading blank lines', async () => {
-    const handoffScript = path.join(tmpDir, 'scripts', 'comet-handoff.sh');
+    const handoffScript = path.join(tmpDir, 'scripts', 'comet-handoff.js');
     await createChange(
       tmpDir,
       'frontmatter-prefix',
@@ -373,7 +277,7 @@ describeShell('comet shell scripts', () => {
         '',
       ].join('\n'),
     );
-    runBash(tmpDir, handoffScript, ['frontmatter-prefix', 'design', '--write']);
+    runNode(tmpDir, handoffScript, ['frontmatter-prefix', 'design', '--write']);
     await writeFile(
       path.join(tmpDir, 'docs', 'superpowers', 'specs', 'frontmatter-prefix-design.md'),
       [
@@ -387,14 +291,14 @@ describeShell('comet shell scripts', () => {
         '',
       ].join('\n'),
     );
-    runBash(tmpDir, stateScript, [
+    runNode(tmpDir, stateScript, [
       'set',
       'frontmatter-prefix',
       'design_doc',
       'docs/superpowers/specs/frontmatter-prefix-design.md',
     ]);
 
-    const result = runBash(tmpDir, guardScript, ['frontmatter-prefix', 'design']);
+    const result = runNode(tmpDir, guardScript, ['frontmatter-prefix', 'design']);
 
     expect(result.status).toBe(0);
     expect(result.stderr).toContain('[PASS] Design Doc frontmatter links current change');
@@ -402,7 +306,7 @@ describeShell('comet shell scripts', () => {
   }, 20_000);
 
   it('generates a full-mode design handoff when --full is passed', async () => {
-    const handoffScript = path.join(tmpDir, 'scripts', 'comet-handoff.sh');
+    const handoffScript = path.join(tmpDir, 'scripts', 'comet-handoff.js');
     await createChange(
       tmpDir,
       'full-handoff',
@@ -422,7 +326,7 @@ describeShell('comet shell scripts', () => {
       ].join('\n'),
     );
 
-    const handoff = runBash(tmpDir, handoffScript, ['full-handoff', 'design', '--write', '--full']);
+    const handoff = runNode(tmpDir, handoffScript, ['full-handoff', 'design', '--write', '--full']);
 
     expect(handoff.status).toBe(0);
     const contextMarkdown = await fs.readFile(
@@ -442,7 +346,7 @@ describeShell('comet shell scripts', () => {
   }, 20_000);
 
   it('rejects handoff generation when required OpenSpec artifacts are missing', async () => {
-    const handoffScript = path.join(tmpDir, 'scripts', 'comet-handoff.sh');
+    const handoffScript = path.join(tmpDir, 'scripts', 'comet-handoff.js');
     const changeDir = path.join(tmpDir, 'openspec', 'changes', 'missing-artifacts');
     await fs.mkdir(changeDir, { recursive: true });
     await writeFile(
@@ -465,14 +369,14 @@ describeShell('comet shell scripts', () => {
     await writeFile(path.join(changeDir, 'proposal.md'), 'proposal\n');
     // design.md and tasks.md intentionally omitted
 
-    const result = runBash(tmpDir, handoffScript, ['missing-artifacts', 'design', '--write']);
+    const result = runNode(tmpDir, handoffScript, ['missing-artifacts', 'design', '--write']);
 
     expect(result.status).not.toBe(0);
     expect(result.stderr).toContain('required OpenSpec artifact missing or empty');
   }, 20_000);
 
   it('detects OpenSpec artifacts changed after handoff was generated', async () => {
-    const handoffScript = path.join(tmpDir, 'scripts', 'comet-handoff.sh');
+    const handoffScript = path.join(tmpDir, 'scripts', 'comet-handoff.js');
     await createChange(
       tmpDir,
       'stale-handoff',
@@ -492,7 +396,7 @@ describeShell('comet shell scripts', () => {
       ].join('\n'),
     );
 
-    runBash(tmpDir, handoffScript, ['stale-handoff', 'design', '--write']);
+    runNode(tmpDir, handoffScript, ['stale-handoff', 'design', '--write']);
 
     // Mutate proposal.md after handoff was generated
     await writeFile(
@@ -500,7 +404,7 @@ describeShell('comet shell scripts', () => {
       'mutated proposal\n',
     );
 
-    const result = runBash(tmpDir, guardScript, ['stale-handoff', 'design']);
+    const result = runNode(tmpDir, guardScript, ['stale-handoff', 'design']);
 
     expect(result.status).not.toBe(0);
     expect(result.stderr).toContain('[FAIL] design handoff context exists');
@@ -508,7 +412,7 @@ describeShell('comet shell scripts', () => {
   }, 20_000);
 
   it('blocks design exit when design doc frontmatter is missing required fields', async () => {
-    const handoffScript = path.join(tmpDir, 'scripts', 'comet-handoff.sh');
+    const handoffScript = path.join(tmpDir, 'scripts', 'comet-handoff.js');
     await createChange(
       tmpDir,
       'bad-frontmatter',
@@ -528,7 +432,7 @@ describeShell('comet shell scripts', () => {
       ].join('\n'),
     );
 
-    runBash(tmpDir, handoffScript, ['bad-frontmatter', 'design', '--write']);
+    runNode(tmpDir, handoffScript, ['bad-frontmatter', 'design', '--write']);
 
     // Design doc with wrong comet_change
     await writeFile(
@@ -542,14 +446,14 @@ describeShell('comet shell scripts', () => {
         '',
       ].join('\n'),
     );
-    runBash(tmpDir, stateScript, [
+    runNode(tmpDir, stateScript, [
       'set',
       'bad-frontmatter',
       'design_doc',
       'docs/superpowers/specs/bad-design.md',
     ]);
 
-    const result = runBash(tmpDir, guardScript, ['bad-frontmatter', 'design']);
+    const result = runNode(tmpDir, guardScript, ['bad-frontmatter', 'design']);
 
     expect(result.status).not.toBe(0);
     expect(result.stderr).toContain('[FAIL] Design Doc frontmatter links current change');
@@ -579,8 +483,8 @@ describeShell('comet shell scripts', () => {
       JSON.stringify({ scripts: { build: 'node -e "process.exit(0)"' } }),
     );
 
-    const guard = runBash(tmpDir, guardScript, ['missing-build-decisions', 'build']);
-    const transition = runBash(tmpDir, stateScript, [
+    const guard = runNode(tmpDir, guardScript, ['missing-build-decisions', 'build']);
+    const transition = runNode(tmpDir, stateScript, [
       'transition',
       'missing-build-decisions',
       'build-complete',
@@ -615,15 +519,15 @@ describeShell('comet shell scripts', () => {
       ].join('\n'),
     );
 
-    const setPlanReady = runBash(tmpDir, stateScript, [
+    const setPlanReady = runNode(tmpDir, stateScript, [
       'set',
       'pause-set',
       'build_pause',
       'plan-ready',
     ]);
-    const planReady = runBash(tmpDir, stateScript, ['get', 'pause-set', 'build_pause']);
-    const setNull = runBash(tmpDir, stateScript, ['set', 'pause-set', 'build_pause', 'null']);
-    const pausedNull = runBash(tmpDir, stateScript, ['get', 'pause-set', 'build_pause']);
+    const planReady = runNode(tmpDir, stateScript, ['get', 'pause-set', 'build_pause']);
+    const setNull = runNode(tmpDir, stateScript, ['set', 'pause-set', 'build_pause', 'null']);
+    const pausedNull = runNode(tmpDir, stateScript, ['get', 'pause-set', 'build_pause']);
 
     expect(setPlanReady.status).toBe(0);
     expect(planReady.stdout.trim()).toBe('plan-ready');
@@ -651,7 +555,7 @@ describeShell('comet shell scripts', () => {
       ].join('\n'),
     );
 
-    const result = runBash(tmpDir, guardScript, ['invalid-build-pause', 'build']);
+    const result = runNode(tmpDir, guardScript, ['invalid-build-pause', 'build']);
 
     expect(result.status).not.toBe(0);
     expect(result.stderr).toContain("build_pause='paused' is not valid");
@@ -682,7 +586,7 @@ describeShell('comet shell scripts', () => {
       JSON.stringify({ scripts: { build: 'node -e "process.exit(0)"' } }),
     );
 
-    const result = runBash(tmpDir, guardScript, ['direct-full', 'build']);
+    const result = runNode(tmpDir, guardScript, ['direct-full', 'build']);
 
     expect(result.status).not.toBe(0);
     expect(result.stderr).toContain('[FAIL] build_mode allowed for workflow');
@@ -715,7 +619,7 @@ describeShell('comet shell scripts', () => {
       JSON.stringify({ scripts: { build: 'node -e "process.exit(0)"' } }),
     );
 
-    const result = runBash(tmpDir, guardScript, ['unfinished-tasks', 'build']);
+    const result = runNode(tmpDir, guardScript, ['unfinished-tasks', 'build']);
 
     expect(result.status).not.toBe(0);
     expect(result.stderr).toContain('[FAIL] tasks.md all tasks checked');
@@ -744,7 +648,7 @@ describeShell('comet shell scripts', () => {
       ].join('\n'),
     );
 
-    const result = runBash(tmpDir, stateScript, [
+    const result = runNode(tmpDir, stateScript, [
       'transition',
       'direct-full-transition',
       'build-complete',
@@ -779,7 +683,7 @@ describeShell('comet shell scripts', () => {
       JSON.stringify({ scripts: { build: 'node -e "process.exit(0)"' } }),
     );
 
-    const result = runBash(tmpDir, guardScript, ['direct-full-override', 'build']);
+    const result = runNode(tmpDir, guardScript, ['direct-full-override', 'build']);
 
     expect(result.status).toBe(0);
     expect(result.stderr).toContain('[PASS] build_mode allowed for workflow');
@@ -814,7 +718,7 @@ describeShell('comet shell scripts', () => {
       JSON.stringify({ scripts: { build: 'node -e "process.exit(0)"' } }),
     );
 
-    const result = runBash(tmpDir, guardScript, ['configured-build', 'build']);
+    const result = runNode(tmpDir, guardScript, ['configured-build', 'build']);
 
     expect(result.status).not.toBe(0);
     expect(result.stderr).toContain('configured failure');
@@ -841,26 +745,26 @@ describeShell('comet shell scripts', () => {
       ].join('\n'),
     );
 
-    const set = runBash(tmpDir, stateScript, [
+    const set = runNode(tmpDir, stateScript, [
       'set',
       'command-metacharacters',
       'build_command',
       command,
     ]);
-    const get = runBash(tmpDir, stateScript, ['get', 'command-metacharacters', 'build_command']);
+    const get = runNode(tmpDir, stateScript, ['get', 'command-metacharacters', 'build_command']);
 
     expect(set.status).toBe(0);
     expect(get.stdout.trim()).toBe(command);
   });
 
-  it('keeps shell scripts portable across GNU and BSD sed', async () => {
+  it('keeps node scripts portable across GNU and BSD sed', async () => {
     for (const name of [
-      'comet-env.sh',
-      'comet-state.sh',
-      'comet-archive.sh',
-      'comet-guard.sh',
-      'comet-handoff.sh',
-      'comet-yaml-validate.sh',
+      'comet-env.js',
+      'comet-state.js',
+      'comet-archive.js',
+      'comet-guard.js',
+      'comet-handoff.js',
+      'comet-yaml-validate.js',
     ]) {
       const content = await fs.readFile(path.join(tmpDir, 'scripts', name), 'utf-8');
 
@@ -868,44 +772,10 @@ describeShell('comet shell scripts', () => {
     }
   });
 
-  it('keeps optional YAML field reads safe under pipefail', async () => {
-    for (const name of ['comet-state.sh', 'comet-guard.sh']) {
-      const content = await fs.readFile(path.join(tmpDir, 'scripts', name), 'utf-8');
-
-      expect(content).toMatch(/grep "\^\$\{field\}:" "\$[a-z_]+".*\|\| true\)/);
-    }
-  });
-
-  it('guards bash uname detection when bash cannot be spawned', async () => {
-    const files = [
-      path.resolve('scripts', 'run-bats.js'),
-      path.resolve('test', 'ts', 'comet-scripts.test.ts'),
-    ];
-
-    for (const file of files) {
-      const content = await fs.readFile(file, 'utf-8');
-
-      expect(content).toContain(".stdout || ''");
-    }
-  });
-
-  it('uses COMET_BASH for nested script calls when PATH bash is unusable', async () => {
-    const fakeBin = path.join(tmpDir, 'fake-bin');
-    await fs.mkdir(fakeBin, { recursive: true });
-    const fakeBash = path.join(fakeBin, 'bash');
-    await writeFile(
-      fakeBash,
-      [
-        '#!/bin/sh',
-        'echo "bad WSL bash" >&2',
-        'exit 127',
-        '',
-      ].join('\n'),
-    );
-    await fs.chmod(fakeBash, 0o755);
+  it('keeps optional YAML field reads independent from shell pipefail behavior', async () => {
     await createChange(
       tmpDir,
-      'nested-bash',
+      'optional-fields',
       [
         'workflow: full',
         'phase: open',
@@ -922,35 +792,18 @@ describeShell('comet shell scripts', () => {
       ].join('\n'),
     );
 
-    const result = spawnSync('bash', [
-      '-lc',
-      [
-        'COMET_BASH="/bin/bash"',
-        `PATH="${toBashPath(fakeBin)}:$PATH"`,
-        'export COMET_BASH PATH',
-        `/bin/bash "${toBashPath(guardScript)}" nested-bash open --apply`,
-      ].join('; '),
-    ], {
-      cwd: tmpDir,
-      encoding: 'utf-8',
-    });
-    const yaml = await fs.readFile(
-      path.join(tmpDir, 'openspec', 'changes', 'nested-bash', '.comet.yaml'),
-      'utf-8',
-    );
+    const result = runNode(tmpDir, stateScript, ['get', 'optional-fields', 'direct_override']);
 
-    expect(result.status, result.stderr).toBe(0);
-    expect(result.stderr).not.toContain('bad WSL bash');
-    expect(yaml).toContain('phase: design');
+    expect(result.status).toBe(0);
+    expect(result.stdout).toBe('\n');
   }, 20_000);
 
-  it('does not use PATH bash for nested Comet script calls', async () => {
-    for (const name of ['comet-archive.sh', 'comet-guard.sh', 'comet-handoff.sh']) {
+  it('uses node executable for nested Comet script calls', async () => {
+    for (const name of ['comet-archive.js', 'comet-guard.js', 'comet-handoff.js']) {
       const content = await fs.readFile(path.join(tmpDir, 'scripts', name), 'utf-8');
 
-      expect(content, `${name} should use COMET_BASH for nested scripts`).not.toMatch(
-        /\bbash\s+"?\$(?:STATE_SH|state_sh|validate_script)/,
-      );
+      expect(content, `${name} should invoke nested scripts through runNode`).toContain('runNode');
+      expect(content, `${name} should not shell out to bash for nested scripts`).not.toMatch(/\bbash\b/);
     }
   });
 
@@ -983,7 +836,7 @@ describeShell('comet shell scripts', () => {
       JSON.stringify({ scripts: { build: 'node -e "process.exit(0)"' } }),
     );
 
-    const result = runBash(tmpDir, guardScript, ['root-configured-build', 'build']);
+    const result = runNode(tmpDir, guardScript, ['root-configured-build', 'build']);
 
     expect(result.status).not.toBe(0);
     expect(result.stderr).toContain('root configured failure');
@@ -1024,7 +877,7 @@ describeShell('comet shell scripts', () => {
       JSON.stringify({ scripts: { build: 'node -e "process.exit(0)"' } }),
     );
 
-    const result = runBash(tmpDir, guardScript, ['configured-verify', 'verify']);
+    const result = runNode(tmpDir, guardScript, ['configured-verify', 'verify']);
 
     expect(result.status).not.toBe(0);
     expect(result.stderr).toContain('verify configured failure');
@@ -1050,14 +903,14 @@ describeShell('comet shell scripts', () => {
       ].join('\n'),
     );
 
-    const result = runBash(tmpDir, guardScript, ['2026-05-21-done-change', 'archive']);
+    const result = runNode(tmpDir, guardScript, ['2026-05-21-done-change', 'archive']);
 
     expect(result.status).toBe(0);
     expect(result.stderr).toContain('ALL CHECKS PASSED');
   });
 
   it('reports accurate archive step counts when syncing and annotating', async () => {
-    const archiveScript = path.join(tmpDir, 'scripts', 'comet-archive.sh');
+    const archiveScript = path.join(tmpDir, 'scripts', 'comet-archive.js');
     await createChange(
       tmpDir,
       'ready-to-archive',
@@ -1097,7 +950,7 @@ describeShell('comet shell scripts', () => {
       'delta spec\n',
     );
 
-    const result = runBash(tmpDir, archiveScript, ['ready-to-archive']);
+    const result = runNode(tmpDir, archiveScript, ['ready-to-archive']);
 
     expect(result.status).toBe(0);
     expect(result.stderr).toContain('Archive complete. 7/7 steps succeeded.');
@@ -1144,8 +997,8 @@ describeShell('comet shell scripts', () => {
     execFileSync('git', ['add', '.'], { cwd: tmpDir });
     execFileSync('git', ['commit', '-m', 'large change'], { cwd: tmpDir, stdio: 'ignore' });
 
-    const result = runBash(tmpDir, stateScript, ['scale', 'large-change']);
-    const mode = runBash(tmpDir, stateScript, ['get', 'large-change', 'verify_mode']);
+    const result = runNode(tmpDir, stateScript, ['scale', 'large-change']);
+    const mode = runNode(tmpDir, stateScript, ['get', 'large-change', 'verify_mode']);
 
     expect(result.status).toBe(0);
     expect(mode.stdout.trim()).toBe('full');
@@ -1171,8 +1024,8 @@ describeShell('comet shell scripts', () => {
       ].join('\n'),
     );
 
-    const result = runBash(tmpDir, stateScript, ['transition', 'full-change', 'open-complete']);
-    const phase = runBash(tmpDir, stateScript, ['get', 'full-change', 'phase']);
+    const result = runNode(tmpDir, stateScript, ['transition', 'full-change', 'open-complete']);
+    const phase = runNode(tmpDir, stateScript, ['get', 'full-change', 'phase']);
 
     expect(result.status).toBe(0);
     expect(phase.stdout.trim()).toBe('design');
@@ -1198,8 +1051,8 @@ describeShell('comet shell scripts', () => {
       ].join('\n'),
     );
 
-    const result = runBash(tmpDir, stateScript, ['transition', 'tweak-change', 'open-complete']);
-    const phase = runBash(tmpDir, stateScript, ['get', 'tweak-change', 'phase']);
+    const result = runNode(tmpDir, stateScript, ['transition', 'tweak-change', 'open-complete']);
+    const phase = runNode(tmpDir, stateScript, ['get', 'tweak-change', 'phase']);
 
     expect(result.status).toBe(0);
     expect(phase.stdout.trim()).toBe('build');
@@ -1227,10 +1080,10 @@ describeShell('comet shell scripts', () => {
       ].join('\n'),
     );
 
-    const fail = runBash(tmpDir, stateScript, ['transition', 'verify-change', 'verify-fail']);
-    const failedPhase = runBash(tmpDir, stateScript, ['get', 'verify-change', 'phase']);
-    const failedResult = runBash(tmpDir, stateScript, ['get', 'verify-change', 'verify_result']);
-    const failedBranchStatus = runBash(tmpDir, stateScript, [
+    const fail = runNode(tmpDir, stateScript, ['transition', 'verify-change', 'verify-fail']);
+    const failedPhase = runNode(tmpDir, stateScript, ['get', 'verify-change', 'phase']);
+    const failedResult = runNode(tmpDir, stateScript, ['get', 'verify-change', 'verify_result']);
+    const failedBranchStatus = runNode(tmpDir, stateScript, [
       'get',
       'verify-change',
       'branch_status',
@@ -1241,24 +1094,24 @@ describeShell('comet shell scripts', () => {
     expect(failedResult.stdout.trim()).toBe('fail');
     expect(failedBranchStatus.stdout.trim()).toBe('pending');
 
-    runBash(tmpDir, stateScript, ['set', 'verify-change', 'phase', 'verify']);
-    runBash(tmpDir, stateScript, ['set', 'verify-change', 'verify_result', 'pending']);
+    runNode(tmpDir, stateScript, ['set', 'verify-change', 'phase', 'verify']);
+    runNode(tmpDir, stateScript, ['set', 'verify-change', 'verify_result', 'pending']);
     await writeFile(
       path.join(tmpDir, 'docs', 'superpowers', 'reports', 'verify-change.md'),
       'PASS\n',
     );
-    runBash(tmpDir, stateScript, [
+    runNode(tmpDir, stateScript, [
       'set',
       'verify-change',
       'verification_report',
       'docs/superpowers/reports/verify-change.md',
     ]);
-    runBash(tmpDir, stateScript, ['set', 'verify-change', 'branch_status', 'handled']);
+    runNode(tmpDir, stateScript, ['set', 'verify-change', 'branch_status', 'handled']);
 
-    const pass = runBash(tmpDir, stateScript, ['transition', 'verify-change', 'verify-pass']);
-    const passedPhase = runBash(tmpDir, stateScript, ['get', 'verify-change', 'phase']);
-    const passedResult = runBash(tmpDir, stateScript, ['get', 'verify-change', 'verify_result']);
-    const verifiedAt = runBash(tmpDir, stateScript, ['get', 'verify-change', 'verified_at']);
+    const pass = runNode(tmpDir, stateScript, ['transition', 'verify-change', 'verify-pass']);
+    const passedPhase = runNode(tmpDir, stateScript, ['get', 'verify-change', 'phase']);
+    const passedResult = runNode(tmpDir, stateScript, ['get', 'verify-change', 'verify_result']);
+    const verifiedAt = runNode(tmpDir, stateScript, ['get', 'verify-change', 'verified_at']);
 
     expect(pass.status).toBe(0);
     expect(passedPhase.stdout.trim()).toBe('archive');
@@ -1292,8 +1145,8 @@ describeShell('comet shell scripts', () => {
       JSON.stringify({ scripts: { build: 'node -e "process.exit(0)"' } }),
     );
 
-    const result = runBash(tmpDir, guardScript, ['guard-verify', 'verify', '--apply']);
-    const phase = runBash(tmpDir, stateScript, ['get', 'guard-verify', 'phase']);
+    const result = runNode(tmpDir, guardScript, ['guard-verify', 'verify', '--apply']);
+    const phase = runNode(tmpDir, stateScript, ['get', 'guard-verify', 'phase']);
 
     expect(result.status).not.toBe(0);
     expect(result.stderr).toContain('[FAIL] verification_report exists');
@@ -1331,9 +1184,9 @@ describeShell('comet shell scripts', () => {
       JSON.stringify({ scripts: { build: 'node -e "process.exit(0)"' } }),
     );
 
-    const result = runBash(tmpDir, guardScript, ['guard-verify', 'verify', '--apply']);
-    const phase = runBash(tmpDir, stateScript, ['get', 'guard-verify', 'phase']);
-    const verifyResult = runBash(tmpDir, stateScript, ['get', 'guard-verify', 'verify_result']);
+    const result = runNode(tmpDir, guardScript, ['guard-verify', 'verify', '--apply']);
+    const phase = runNode(tmpDir, stateScript, ['get', 'guard-verify', 'phase']);
+    const verifyResult = runNode(tmpDir, stateScript, ['get', 'guard-verify', 'verify_result']);
 
     expect(result.status).toBe(0);
     expect(phase.stdout.trim()).toBe('archive');
@@ -1360,7 +1213,7 @@ describeShell('comet shell scripts', () => {
       ].join('\n'),
     );
 
-    const result = runBash(tmpDir, stateScript, ['transition', 'wrong-phase', 'build-complete']);
+    const result = runNode(tmpDir, stateScript, ['transition', 'wrong-phase', 'build-complete']);
 
     expect(result.status).not.toBe(0);
     expect(result.stderr).toContain('expected phase build');
@@ -1386,12 +1239,12 @@ describeShell('comet shell scripts', () => {
       ].join('\n'),
     );
 
-    const result = runBash(tmpDir, stateScript, [
+    const result = runNode(tmpDir, stateScript, [
       'transition',
       '2026-05-21-done-change',
       'archived',
     ]);
-    const archived = runBash(tmpDir, stateScript, ['get', '2026-05-21-done-change', 'archived']);
+    const archived = runNode(tmpDir, stateScript, ['get', '2026-05-21-done-change', 'archived']);
 
     expect(result.status).toBe(0);
     expect(archived.stdout.trim()).toBe('true');
@@ -1417,7 +1270,7 @@ describeShell('comet shell scripts', () => {
         ].join('\n'),
       );
 
-      const result = runBash(tmpDir, stateScript, ['check', 'recover-open', 'open', '--recover']);
+      const result = runNode(tmpDir, stateScript, ['check', 'recover-open', 'open', '--recover']);
 
       expect(result.status).toBe(0);
       expect(result.stdout).toContain('Recovery Context: recover-open');
@@ -1449,7 +1302,7 @@ describeShell('comet shell scripts', () => {
         ['- [x] done task', '- [ ] pending task'].join('\n'),
       );
 
-      const result = runBash(tmpDir, stateScript, ['check', 'recover-build', 'build', '--recover']);
+      const result = runNode(tmpDir, stateScript, ['check', 'recover-build', 'build', '--recover']);
 
       expect(result.status).toBe(0);
       expect(result.stdout).toContain('Phase: build');
@@ -1482,7 +1335,7 @@ describeShell('comet shell scripts', () => {
         ].join('\n'),
       );
 
-      const result = runBash(tmpDir, stateScript, [
+      const result = runNode(tmpDir, stateScript, [
         'check',
         'recover-plan-ready',
         'build',
@@ -1521,7 +1374,7 @@ describeShell('comet shell scripts', () => {
         ].join('\n'),
       );
 
-      const result = runBash(tmpDir, stateScript, [
+      const result = runNode(tmpDir, stateScript, [
         'check',
         'recover-verify',
         'verify',
@@ -1568,7 +1421,7 @@ describeShell('comet shell scripts', () => {
         '{}',
       );
 
-      const result = runBash(tmpDir, stateScript, [
+      const result = runNode(tmpDir, stateScript, [
         'check',
         'recover-design',
         'design',
@@ -1602,7 +1455,7 @@ describeShell('comet shell scripts', () => {
         ].join('\n'),
       );
 
-      const result = runBash(tmpDir, stateScript, [
+      const result = runNode(tmpDir, stateScript, [
         'check',
         'recover-no-tasks',
         'build',
@@ -1636,7 +1489,7 @@ describeShell('comet shell scripts', () => {
         ['- [x] task 1', '- [x] task 2'].join('\n'),
       );
 
-      const result = runBash(tmpDir, stateScript, [
+      const result = runNode(tmpDir, stateScript, [
         'check',
         'recover-build-done',
         'build',
@@ -1671,7 +1524,7 @@ describeShell('comet shell scripts', () => {
         ].join('\n'),
       );
 
-      const result = runBash(tmpDir, stateScript, [
+      const result = runNode(tmpDir, stateScript, [
         'check',
         'recover-archive',
         'archive',
@@ -1705,7 +1558,7 @@ describeShell('comet shell scripts', () => {
         ].join('\n'),
       );
 
-      const result = runBash(tmpDir, stateScript, ['check', 'recover-normal', 'open']);
+      const result = runNode(tmpDir, stateScript, ['check', 'recover-normal', 'open']);
 
       expect(result.status).toBe(0);
       expect(result.stdout).toContain('Entry Check');
diff --git a/test/ts/run-bats.test.ts b/test/ts/run-bats.test.ts
deleted file mode 100644
index 706b897a..00000000
--- a/test/ts/run-bats.test.ts
+++ /dev/null
@@ -1,38 +0,0 @@
-import { describe, expect, it } from 'vitest';
-import { promises as fs } from 'fs';
-import path from 'path';
-
-describe('run-bats shell runner', () => {
-  it('resolves a usable bash instead of directly invoking PATH bash', async () => {
-    const content = await fs.readFile(path.resolve('scripts', 'run-bats.js'), 'utf-8');
-
-    expect(content).toContain('function findUsableBash');
-    expect(content).toContain('process.env.COMET_TEST_BASH');
-    expect(content).toContain('process.env.COMET_BASH');
-    expect(content).not.toContain("spawnSync('bash'");
-  });
-
-  it('rejects WSL bash when resolving bash on Windows', async () => {
-    const runner = await fs.readFile(path.resolve('scripts', 'run-bats.js'), 'utf-8');
-    const shellTests = await fs.readFile(path.resolve('test', 'ts', 'comet-scripts.test.ts'), 'utf-8');
-
-    expect(runner).toContain("process.platform === 'win32' && /linux/i.test(probe.stdout)");
-    expect(shellTests).toContain("process.platform === 'win32' && /linux/i.test(probe.stdout)");
-  });
-
-  it('checks explicit Comet bash paths before shelling out to discover fallbacks', async () => {
-    const content = await fs.readFile(
-      path.resolve('assets', 'skills', 'comet', 'scripts', 'comet-env.sh'),
-      'utf-8',
-    );
-
-    const cometBashCheck = content.indexOf('if _comet_bash_is_usable "${COMET_BASH:-}"');
-    const currentBashCheck = content.indexOf('if _comet_bash_is_usable "${BASH:-}"');
-    const shellFallback = content.indexOf('command -v sh');
-
-    expect(cometBashCheck).toBeGreaterThan(-1);
-    expect(currentBashCheck).toBeGreaterThan(cometBashCheck);
-    expect(shellFallback).toBeGreaterThan(currentBashCheck);
-    expect(content).not.toContain('for _comet_bash_candidate in \\');
-  });
-});
diff --git a/test/ts/skills.test.ts b/test/ts/skills.test.ts
index e14646ba..14fb3435 100644
--- a/test/ts/skills.test.ts
+++ b/test/ts/skills.test.ts
@@ -132,7 +132,7 @@ describe('skills', () => {
       expect(command).toContain('$ARGUMENTS');
       expect(command).toContain('# Comet Phase 1: Open');
       expect(command).toContain('## Steps');
-      expect(command).toContain('"$COMET_BASH" "$COMET_STATE" init <name> full');
+      expect(command).toContain('node "$COMET_STATE" init <name> full');
       expect(command).not.toContain('Immediately load the `comet-open` skill with the skill tool');
       expect(path.basename(commandPath)).toBe('comet-open.md');
     });
@@ -223,7 +223,7 @@ describe('skills', () => {
       expect(zhTweak).toContain('不得直接进入 `/comet-design`');
       expect(zhComet).toContain('`verify_result: fail` → 进入验证失败决策阻塞点');
       expect(zhComet).not.toContain(
-        '`verify_result: fail` → `"$COMET_BASH" "$COMET_STATE" transition <name> verify-fail` 后 `/comet-build`',
+        '`verify_result: fail` → `node "$COMET_STATE" transition <name> verify-fail` 后 `/comet-build`',
       );
       expect(zhHotfix).toContain('按升级条件阻塞确认处理');
       expect(zhHotfix).not.toContain('停止 hotfix，升级为 `/comet`');
@@ -281,7 +281,7 @@ describe('skills', () => {
       expect(zhBuild).toContain('必须使用 Skill 工具加载 Superpowers `brainstorming`');
       expect(zhHotfix).toContain('立即使用 Skill 工具加载 `comet-design` skill');
       expect(zhTweak).toContain('立即使用 Skill 工具加载 `comet-design` skill');
-      expect(zhVerify).toContain('用户选择 B 后，运行 `"$COMET_BASH" "$COMET_STATE" transition <change-name> verify-fail`，然后调用 `/comet-build`');
+      expect(zhVerify).toContain('用户选择 B 后，运行 `node "$COMET_STATE" transition <change-name> verify-fail`，然后调用 `/comet-build`');
     });
   });
 
@@ -325,7 +325,7 @@ describe('skills', () => {
       expect(enTweak).toContain('Do not directly enter `/comet-design`');
       expect(enComet).toContain('`verify_result: fail` → Enter verification failure decision blocking point');
       expect(enComet).not.toContain(
-        '`verify_result: fail` → `"$COMET_BASH" "$COMET_STATE" transition <name> verify-fail` then `/comet-build`',
+        '`verify_result: fail` → `node "$COMET_STATE" transition <name> verify-fail` then `/comet-build`',
       );
 
       expect(enHotfix).toContain('handle per "Upgrade Conditions" section');
@@ -354,7 +354,7 @@ describe('skills', () => {
       expect(enBuild).toContain('must use Skill tool to load the Superpowers `brainstorming` skill');
       expect(enHotfix).toContain('Immediately use the Skill tool to load the `comet-design` skill');
       expect(enTweak).toContain('Immediately use the Skill tool to load the `comet-design` skill');
-      expect(enVerify).toContain('After user selects B, run `"$COMET_BASH" "$COMET_STATE" transition <change-name> verify-fail`, then invoke `/comet-build`');
+      expect(enVerify).toContain('After user selects B, run `node "$COMET_STATE" transition <change-name> verify-fail`, then invoke `/comet-build`');
     });
   });
 
@@ -454,7 +454,7 @@ describe('skills', () => {
   describe('Comet script discovery helper', () => {
     it('ships a shared script locator helper', async () => {
       const manifest = await readManifest();
-      expect(manifest.skills).toContain('comet/scripts/comet-env.sh');
+      expect(manifest.skills).toContain('comet/scripts/comet-env.js');
     });
 
     it('keeps platform search roots out of English and Chinese skill prose', async () => {
@@ -473,11 +473,11 @@ describe('skills', () => {
           );
           if (!content.includes('COMET_STATE') && !content.includes('COMET_GUARD')) continue;
 
-          expect(content, `${languageDir}/${skillPath} should use comet-env.sh`).toContain(
-            'comet-env.sh',
+          expect(content, `${languageDir}/${skillPath} should use comet-env.js`).toContain(
+            'comet-env.js',
           );
-          expect(content, `${languageDir}/${skillPath} should source COMET_ENV`).toContain(
-            '. "$COMET_ENV"',
+          expect(content, `${languageDir}/${skillPath} should read COMET_ENV JSON`).toContain(
+            'COMET_ENV_JSON="$(node "$COMET_ENV")"',
           );
           expect(content, `${languageDir}/${skillPath} should allow HOME skill glob expansion`).toContain(
             '"$HOME"/.*/skills',
@@ -492,7 +492,7 @@ describe('skills', () => {
       }
     });
 
-    it('uses COMET_BASH in shipped Comet command examples', async () => {
+    it('uses node in shipped Comet command examples', async () => {
       const manifest = await readManifest();
       const skillPaths = manifest.skills.filter(
         (skillPath) =>
@@ -510,6 +510,9 @@ describe('skills', () => {
           expect(content, `${languageDir}/${skillPath} should avoid raw bash for Comet scripts`).not.toMatch(
             /(^|[` \t])bash[ \t]+"?\$COMET_/m,
           );
+          expect(content, `${languageDir}/${skillPath} should avoid COMET_BASH`).not.toContain(
+            'COMET_BASH',
+          );
         }
       }
     });

From 4950710952161ac4f65010c2e29aa243f24b1b5d Mon Sep 17 00:00:00 2001
From: zheng <forggy0113@gmail.com>
Date: Sat, 6 Jun 2026 01:38:33 +0800
Subject: [PATCH 2/7] refactor bash script to js script

refactor bash script to js script, and make some tweaks to skills
---
 .github/PULL_REQUEST_TEMPLATE.md              |   5 +-
 .github/workflows/ci.yml                      |  48 +-
 AGENTS.md                                     |  25 +-
 CHANGELOG.md                                  |   9 +-
 CLAUDE.md                                     |  25 +-
 CONTRIBUTING.md                               |   1 -
 README-zh.md                                  |  38 +-
 README.md                                     |  38 +-
 assets/manifest.json                          |  13 +-
 assets/skills-zh/comet-archive/SKILL.md       |  16 +-
 assets/skills-zh/comet-build/SKILL.md         |  34 +-
 assets/skills-zh/comet-design/SKILL.md        |  28 +-
 assets/skills-zh/comet-hotfix/SKILL.md        |  22 +-
 assets/skills-zh/comet-open/SKILL.md          |  18 +-
 assets/skills-zh/comet-tweak/SKILL.md         |  22 +-
 assets/skills-zh/comet-verify/SKILL.md        |  40 +-
 assets/skills-zh/comet/SKILL.md               |  38 +-
 assets/skills/comet-archive/SKILL.md          |  16 +-
 assets/skills/comet-build/SKILL.md            |  34 +-
 assets/skills/comet-design/SKILL.md           |  28 +-
 assets/skills/comet-hotfix/SKILL.md           |  22 +-
 assets/skills/comet-open/SKILL.md             |  18 +-
 assets/skills/comet-tweak/SKILL.md            |  22 +-
 assets/skills/comet-verify/SKILL.md           |  40 +-
 assets/skills/comet/SKILL.md                  |  38 +-
 assets/skills/comet/scripts/comet-archive.js  | 106 ++
 assets/skills/comet/scripts/comet-archive.sh  | 295 ------
 assets/skills/comet/scripts/comet-env.js      |  21 +
 assets/skills/comet/scripts/comet-env.sh      | 110 ---
 assets/skills/comet/scripts/comet-guard.js    | 281 ++++++
 assets/skills/comet/scripts/comet-guard.sh    | 596 ------------
 assets/skills/comet/scripts/comet-handoff.js  | 109 +++
 assets/skills/comet/scripts/comet-handoff.sh  | 263 -----
 assets/skills/comet/scripts/comet-lib.js      | 212 ++++
 assets/skills/comet/scripts/comet-state.js    | 384 ++++++++
 assets/skills/comet/scripts/comet-state.sh    | 908 ------------------
 .../comet/scripts/comet-yaml-validate.js      |  68 ++
 .../comet/scripts/comet-yaml-validate.sh      | 200 ----
 package.json                                  |   4 +-
 pnpm-lock.yaml                                |  27 +-
 scripts/run-bats.js                           | 189 ----
 test/shell/comet-state.bats                   | 214 -----
 test/ts/comet-scripts.test.ts                 | 399 +++-----
 test/ts/run-bats.test.ts                      |  38 -
 test/ts/skills.test.ts                        |  25 +-
 45 files changed, 1684 insertions(+), 3403 deletions(-)
 create mode 100644 assets/skills/comet/scripts/comet-archive.js
 delete mode 100644 assets/skills/comet/scripts/comet-archive.sh
 create mode 100644 assets/skills/comet/scripts/comet-env.js
 delete mode 100644 assets/skills/comet/scripts/comet-env.sh
 create mode 100644 assets/skills/comet/scripts/comet-guard.js
 delete mode 100644 assets/skills/comet/scripts/comet-guard.sh
 create mode 100644 assets/skills/comet/scripts/comet-handoff.js
 delete mode 100644 assets/skills/comet/scripts/comet-handoff.sh
 create mode 100644 assets/skills/comet/scripts/comet-lib.js
 create mode 100644 assets/skills/comet/scripts/comet-state.js
 delete mode 100644 assets/skills/comet/scripts/comet-state.sh
 create mode 100644 assets/skills/comet/scripts/comet-yaml-validate.js
 delete mode 100644 assets/skills/comet/scripts/comet-yaml-validate.sh
 delete mode 100644 scripts/run-bats.js
 delete mode 100644 test/shell/comet-state.bats
 delete mode 100644 test/ts/run-bats.test.ts

diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md
index b2be4a74..74fe9ae4 100644
--- a/.github/PULL_REQUEST_TEMPLATE.md
+++ b/.github/PULL_REQUEST_TEMPLATE.md
@@ -9,7 +9,7 @@
 - [ ] CLI commands (`init`, `status`, `doctor`, `update`)
 - [ ] Core installer / platform detection
 - [ ] Comet skills (`assets/skills/`, `assets/skills-zh/`)
-- [ ] Comet shell scripts (`assets/skills/comet/scripts/`)
+- [ ] Comet Node scripts (`assets/skills/comet/scripts/`)
 - [ ] Tests / CI
 - [ ] Documentation / changelog
 - [ ] Other:
@@ -23,7 +23,6 @@
 - [ ] `pnpm format:check`
 - [ ] `pnpm test`
 - [ ] `pnpm test -- test/ts/comet-scripts.test.ts`
-- [ ] `pnpm test:shell`
 - [ ] Not run:
 
 ## ✅ Checklist
@@ -33,7 +32,7 @@
 - [ ] `CHANGELOG.md` is updated when behavior changes
 - [ ] Skill changes were made in Chinese first when applicable, then synced to English
 - [ ] New scripts are included in `assets/manifest.json` and relevant tests
-- [ ] Shell scripts remain portable across macOS, Linux, and Windows Git Bash
+- [ ] Comet Node scripts remain portable across macOS, Linux, and Windows
 - [ ] No unrelated generated files or local artifacts are included
 
 ## 👀 Notes for Reviewers
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 03e5cc51..49f7b2d9 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -34,27 +34,6 @@ jobs:
 
       - run: pnpm test:coverage
 
-  shellcheck:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v4
-
-      - name: Run shellcheck
-        uses: ludeeus/action-shellcheck@2.0.0
-        with:
-          scandir: ./assets/skills/comet/scripts
-
-  bats-tests:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v4
-
-      - name: Install bats
-        run: sudo apt-get install -y bats
-
-      - name: Run shell tests
-        run: bats test/shell/*.bats
-
   script-smoke:
     runs-on: ${{ matrix.os }}
     strategy:
@@ -77,9 +56,6 @@ jobs:
       - name: Run Comet script smoke tests
         run: pnpm test -- test/ts/comet-scripts.test.ts
 
-      - name: Run portable shell tests
-        run: pnpm test:shell
-
   init-e2e:
     runs-on: ${{ matrix.os }}
     strategy:
@@ -132,11 +108,13 @@ jobs:
                     .iflow/skills .pi/skills .qoder/skills .agents/skills \
                     .bob/skills .forge/skills .trae/skills .github/skills; do
             check_file "$PROJ/$sd/comet/SKILL.md"
-            check_file "$PROJ/$sd/comet/scripts/comet-guard.sh"
-            check_file "$PROJ/$sd/comet/scripts/comet-state.sh"
-            check_file "$PROJ/$sd/comet/scripts/comet-handoff.sh"
-            check_file "$PROJ/$sd/comet/scripts/comet-yaml-validate.sh"
-            check_file "$PROJ/$sd/comet/scripts/comet-archive.sh"
+            check_file "$PROJ/$sd/comet/scripts/comet-guard.js"
+            check_file "$PROJ/$sd/comet/scripts/comet-state.js"
+            check_file "$PROJ/$sd/comet/scripts/comet-handoff.js"
+            check_file "$PROJ/$sd/comet/scripts/comet-yaml-validate.js"
+            check_file "$PROJ/$sd/comet/scripts/comet-archive.js"
+            check_file "$PROJ/$sd/comet/scripts/comet-env.js"
+            check_file "$PROJ/$sd/comet/scripts/comet-lib.js"
           done
           echo "All 28 platforms project Comet skills: OK"
         shell: bash
@@ -220,11 +198,13 @@ jobs:
                     .iflow/skills .pi/skills .qoder/skills .gemini/antigravity/skills \
                     .bob/skills .forge/skills .trae/skills .github/skills; do
             check_file "$HOME_DIR/$sd/comet/SKILL.md"
-            check_file "$HOME_DIR/$sd/comet/scripts/comet-guard.sh"
-            check_file "$HOME_DIR/$sd/comet/scripts/comet-state.sh"
-            check_file "$HOME_DIR/$sd/comet/scripts/comet-handoff.sh"
-            check_file "$HOME_DIR/$sd/comet/scripts/comet-yaml-validate.sh"
-            check_file "$HOME_DIR/$sd/comet/scripts/comet-archive.sh"
+            check_file "$HOME_DIR/$sd/comet/scripts/comet-guard.js"
+            check_file "$HOME_DIR/$sd/comet/scripts/comet-state.js"
+            check_file "$HOME_DIR/$sd/comet/scripts/comet-handoff.js"
+            check_file "$HOME_DIR/$sd/comet/scripts/comet-yaml-validate.js"
+            check_file "$HOME_DIR/$sd/comet/scripts/comet-archive.js"
+            check_file "$HOME_DIR/$sd/comet/scripts/comet-env.js"
+            check_file "$HOME_DIR/$sd/comet/scripts/comet-lib.js"
           done
           echo "All 28 platforms global Comet skills: OK"
         shell: bash
diff --git a/AGENTS.md b/AGENTS.md
index 4bdd6754..fed2e4a0 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -1,34 +1,35 @@
 ## 测试
 
 ```bash
-npx vitest run test/ts/comet-scripts.test.ts   # shell 脚本测试
+npx vitest run test/ts/comet-scripts.test.ts   # Comet Node 脚本测试
 npx vitest run                                   # 全量测试
 ```
 
-## Shell 脚本规范
+## Comet Node 脚本规范
 
-脚本位于 `assets/skills/comet/scripts/`，必须跨平台兼容（macOS / Linux / Windows Git Bash）：
+脚本位于 `assets/skills/comet/scripts/`，必须跨平台兼容（macOS / Linux / Windows）：
 
-- **禁止** `sed -i`（GNU/BSD 不兼容），用 `awk` 做字段替换
-- 必须兼容 `sha256sum`（GNU）和 `shasum -a 256`（BSD/macOS）
-- 所有可选 grep 结果加 `|| true` 防止 `pipefail` 误杀
+- 使用 Node.js 实现，不新增 `.sh` wrapper
+- 脚本间调用使用 `node <script>.js` 或共享 `runNode`
+- 用户配置的 `build_command` / `verify_command` 允许交给平台 shell 执行
 - 新增脚本必须加入 `beforeEach` 的拷贝列表和 manifest.json
 
 ## 脚本依赖关系
 
 ```
-comet-state.sh ← comet-guard.sh, comet-handoff.sh, comet-archive.sh
-comet-yaml-validate.sh ← comet-guard.sh (preflight 阶段)
-comet-handoff.sh ← comet-state.sh (写入 handoff_context/handoff_hash)
+comet-lib.js ← comet-state.js, comet-guard.js, comet-handoff.js, comet-archive.js, comet-yaml-validate.js, comet-env.js
+comet-state.js ← comet-guard.js, comet-handoff.js, comet-archive.js
+comet-yaml-validate.js ← comet-guard.js (preflight 阶段)
+comet-handoff.js ← comet-state.js (写入 handoff_context/handoff_hash)
 ```
 
-新增共享工具函数时（如 hash、yaml 解析），如果两个脚本都需要，允许在各自脚本中独立实现，不强制抽共享文件。
+新增共享工具函数时优先放入 `comet-lib.js`，避免各脚本行为分叉。
 
 ## .comet.yaml 状态机
 
 每个 change 的状态文件，字段变更需要同步三处：
-1. `comet-state.sh` — `cmd_set` 白名单 + enum 验证
-2. `comet-yaml-validate.sh` — schema 校验 + KNOWN_KEYS
+1. `comet-state.js` — 可写字段白名单 + enum 验证
+2. `comet-yaml-validate.js` — schema 校验 + KNOWN_KEYS
 3. `test/ts/comet-scripts.test.ts` — 测试中的 yaml 字符串
 
 ## 双语言 Skill
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 6768c9ae..eb67a220 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -6,26 +6,27 @@ All notable changes to @rpamis/comet will be documented in this file.
 
 ### Added
 
+- **Cross-platform Comet Node scripts**: Added Node.js implementations for Comet state, guard, handoff, archive, YAML validation, environment discovery, and shared script utilities so bundled automation runs without Bash-specific script files.
 - **Plan-ready build pause state**: Added `build_pause` as a dedicated build-phase pause marker so Comet can stop after plan generation without confusing the pause with the actual execution method.
 - **Plan-ready pause design**: Added a design record for the model-switching pause workflow, covering recovery behavior, stale pause handling, and plan-missing remediation.
 
 ### Changed
 
 - **Build recovery routing**: `/comet` and `/comet-build` now recognize `build_pause: plan-ready`, reuse the existing plan, and resume at workspace isolation and execution-method selection instead of regenerating the plan.
+- **Comet script invocation**: Skills, manifest entries, docs, and CI now invoke Comet automation through `node comet-*.js` instead of Bash script entrypoints for simpler Windows compatibility.
 - **Bilingual workflow documentation**: Chinese and English Comet skills now describe the plan-ready pause point, clarify that `build_pause` is not `build_mode`, and document the same state field in both README files.
 
 ### Fixed
 
 - **GitHub Copilot Superpowers skill names**: Comet skills now invoke the bare Superpowers skill names installed by the GitHub Copilot skills path, avoiding blocked workflows caused by unresolved `superpowers:*` aliases.
-- **Windows bash resolution**: Comet now resolves a usable bash executable through `COMET_BASH`, rejects the Windows WSL launcher path, and uses the resolved executable for nested script calls so guard, handoff, and archive flows do not fall back to a broken PATH `bash`.
-- **Shell test runner bash resolution**: `run-bats.js` now resolves a usable bash through `COMET_TEST_BASH`, `COMET_BASH`, PATH, or Git Bash defaults, avoiding the broken Windows WSL launcher when running shell tests from Node.
+- **Windows script execution**: Comet guard, handoff, archive, state, and validation flows now use Node for internal script calls, avoiding failures caused by unavailable or incompatible Bash executables on Windows.
 - **Schema validation fatal output**: Guard validation now preserves the final fatal schema-validation message after printing validator diagnostics, making invalid `.comet.yaml` failures easier to recognize.
 
 ### Tests
 
 - **Superpowers skill invocation regression**: Added coverage that shipped Comet skill prose does not reference plugin-prefixed Superpowers aliases.
-- **Comet bash execution regression**: Added coverage for nested script calls, shipped command examples, and the shell test runner so Comet uses resolved bash paths instead of raw PATH `bash`.
-- **Plan-ready pause regression**: Added shell-script coverage for `build_pause` initialization, schema validation, state updates, and build recovery output.
+- **Comet Node script regression**: Added coverage for nested script calls, shipped command examples, manifest entries, and environment discovery so Comet uses Node script entrypoints instead of Bash wrappers.
+- **Plan-ready pause regression**: Added Comet script coverage for `build_pause` initialization, schema validation, state updates, and build recovery output.
 - **README state-field regression**: Added README coverage to ensure `build_pause` appears in examples and field descriptions for both English and Chinese documentation.
 
 ## What's Changed [0.3.5] - 2026-05-29
diff --git a/CLAUDE.md b/CLAUDE.md
index 4bdd6754..fed2e4a0 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -1,34 +1,35 @@
 ## 测试
 
 ```bash
-npx vitest run test/ts/comet-scripts.test.ts   # shell 脚本测试
+npx vitest run test/ts/comet-scripts.test.ts   # Comet Node 脚本测试
 npx vitest run                                   # 全量测试
 ```
 
-## Shell 脚本规范
+## Comet Node 脚本规范
 
-脚本位于 `assets/skills/comet/scripts/`，必须跨平台兼容（macOS / Linux / Windows Git Bash）：
+脚本位于 `assets/skills/comet/scripts/`，必须跨平台兼容（macOS / Linux / Windows）：
 
-- **禁止** `sed -i`（GNU/BSD 不兼容），用 `awk` 做字段替换
-- 必须兼容 `sha256sum`（GNU）和 `shasum -a 256`（BSD/macOS）
-- 所有可选 grep 结果加 `|| true` 防止 `pipefail` 误杀
+- 使用 Node.js 实现，不新增 `.sh` wrapper
+- 脚本间调用使用 `node <script>.js` 或共享 `runNode`
+- 用户配置的 `build_command` / `verify_command` 允许交给平台 shell 执行
 - 新增脚本必须加入 `beforeEach` 的拷贝列表和 manifest.json
 
 ## 脚本依赖关系
 
 ```
-comet-state.sh ← comet-guard.sh, comet-handoff.sh, comet-archive.sh
-comet-yaml-validate.sh ← comet-guard.sh (preflight 阶段)
-comet-handoff.sh ← comet-state.sh (写入 handoff_context/handoff_hash)
+comet-lib.js ← comet-state.js, comet-guard.js, comet-handoff.js, comet-archive.js, comet-yaml-validate.js, comet-env.js
+comet-state.js ← comet-guard.js, comet-handoff.js, comet-archive.js
+comet-yaml-validate.js ← comet-guard.js (preflight 阶段)
+comet-handoff.js ← comet-state.js (写入 handoff_context/handoff_hash)
 ```
 
-新增共享工具函数时（如 hash、yaml 解析），如果两个脚本都需要，允许在各自脚本中独立实现，不强制抽共享文件。
+新增共享工具函数时优先放入 `comet-lib.js`，避免各脚本行为分叉。
 
 ## .comet.yaml 状态机
 
 每个 change 的状态文件，字段变更需要同步三处：
-1. `comet-state.sh` — `cmd_set` 白名单 + enum 验证
-2. `comet-yaml-validate.sh` — schema 校验 + KNOWN_KEYS
+1. `comet-state.js` — 可写字段白名单 + enum 验证
+2. `comet-yaml-validate.js` — schema 校验 + KNOWN_KEYS
 3. `test/ts/comet-scripts.test.ts` — 测试中的 yaml 字符串
 
 ## 双语言 Skill
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 4d72b160..51fb3d60 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -17,7 +17,6 @@ pnpm build
 | `pnpm build` | Compile TypeScript |
 | `pnpm test` | Run unit tests |
 | `pnpm test:coverage` | Run tests with coverage |
-| `pnpm test:shell` | Run shell script tests (requires bats) |
 | `pnpm lint` | Run ESLint |
 | `pnpm format` | Run Prettier |
 
diff --git a/README-zh.md b/README-zh.md
index edfeb84d..d774e837 100644
--- a/README-zh.md
+++ b/README-zh.md
@@ -64,7 +64,7 @@ Superpowers 在头脑风暴后会产出 Spec 文档，但这个文档通常没
 
 - **如何把文档同步从“用户提醒”变成自动化** — Comet 将 handoff、状态更新、校验和归档同步放进脚本化流程，减少“记得更新 design doc”“记得同步 spec”“记得归档 change”这类反复提示。
 
-- **如何设计 Agent 可执行的守护条件** — Comet 的阶段退出不是简单相信 Agent 说“完成了”，而是通过 `comet-guard.sh`、`comet-yaml-validate.sh`、`comet-state.sh` 等脚本检查任务、状态字段、验证证据和归档条件，满足条件后才允许推进。
+- **如何设计 Agent 可执行的守护条件** — Comet 的阶段退出不是简单相信 Agent 说“完成了”，而是通过 `comet-guard.js`、`comet-yaml-validate.js`、`comet-state.js` 等 Node 脚本检查任务、状态字段、验证证据和归档条件，满足条件后才允许推进。
 
 - **如何做跨平台 Skill 分发和安装** — Comet 支持多种 AI 编码平台、项目级/全局安装、中文/英文 Skill 选择，以及平台差异化目录（例如 Antigravity 的项目级和全局路径不同），可以作为 CLI 安装器和 Skill 打包结构的参考。
 
@@ -238,12 +238,12 @@ npx skills add rpamis/comet
 
 | 脚本 | 用途 |
 |--------|---------|
-| `comet-env.sh` | 脚本发现助手 — 导出 `COMET_GUARD`、`COMET_STATE`、`COMET_HANDOFF`、`COMET_ARCHIVE` 等内置脚本路径 |
-| `comet-guard.sh` | 阶段转换守护 — 验证退出条件，`--apply` 自动更新 `.comet.yaml` |
-| `comet-handoff.sh` | 设计交接 — 从 OpenSpec 制品生成带 SHA256 追踪的确定性上下文包 |
-| `comet-archive.sh` | 一键归档 — 验证状态、同步 specs、移至归档、更新状态 |
-| `comet-yaml-validate.sh` | 模式校验器 — 校验 `.comet.yaml` 结构和字段值 |
-| `comet-state.sh` | 统一状态管理 — init/set/get/check/scale，agent 的专属 YAML 接口 |
+| `comet-env.js` | 脚本发现助手 — 以 JSON 输出 `COMET_GUARD`、`COMET_STATE`、`COMET_HANDOFF`、`COMET_ARCHIVE` 等内置脚本路径 |
+| `comet-guard.js` | 阶段转换守护 — 验证退出条件，`--apply` 自动更新 `.comet.yaml` |
+| `comet-handoff.js` | 设计交接 — 从 OpenSpec 制品生成带 SHA256 追踪的确定性上下文包 |
+| `comet-archive.js` | 一键归档 — 验证状态、同步 specs、移至归档、更新状态 |
+| `comet-yaml-validate.js` | 模式校验器 — 校验 `.comet.yaml` 结构和字段值 |
+| `comet-state.js` | 统一状态管理 — init/set/get/check/scale，agent 的专属 YAML 接口 |
 
 </details>
 
@@ -325,7 +325,7 @@ handoff_context: openspec/changes/<name>/.comet/handoff/design-context.json
 handoff_hash: <sha256>
 ```
 
-full workflow 初始化时 `build_mode`、`build_pause`、`isolation` 和 `verify_mode` 可以暂时为 `null`；进入 `build → verify` 前必须完成 `build_mode` 与 `isolation` 决策并写入合法值。`build_pause` 记录 build 阶段内部暂停点：`null` 表示无暂停，`plan-ready` 表示 plan 已生成，用户在选择隔离方式和执行方式前暂停。它不是执行方式，不得写入 `build_mode`。`verification_report` 在验证报告生成前保持 `null`，`verify-pass` 要求该报告文件存在且 `branch_status: handled`。示例中 `archived` 之后的字段是可选字段或脚本派生字段：`direct_override` 只在 full workflow 直接构建时需要，项目命令未配置时可以不存在，`handoff_context` 和 `handoff_hash` 由 `comet-handoff.sh` 在离开 design 阶段前写入。项目可在 change 或仓库根配置中设置 `build_command` / `verify_command`，guard 会优先运行并打印失败输出。
+full workflow 初始化时 `build_mode`、`build_pause`、`isolation` 和 `verify_mode` 可以暂时为 `null`；进入 `build → verify` 前必须完成 `build_mode` 与 `isolation` 决策并写入合法值。`build_pause` 记录 build 阶段内部暂停点：`null` 表示无暂停，`plan-ready` 表示 plan 已生成，用户在选择隔离方式和执行方式前暂停。它不是执行方式，不得写入 `build_mode`。`verification_report` 在验证报告生成前保持 `null`，`verify-pass` 要求该报告文件存在且 `branch_status: handled`。示例中 `archived` 之后的字段是可选字段或脚本派生字段：`direct_override` 只在 full workflow 直接构建时需要，项目命令未配置时可以不存在，`handoff_context` 和 `handoff_hash` 由 `comet-handoff.js` 在离开 design 阶段前写入。项目可在 change 或仓库根配置中设置 `build_command` / `verify_command`，guard 会优先运行并打印失败输出。
 
 </details>
 
@@ -340,13 +340,13 @@ Comet 通过自动化状态转换确保 agent 执行可靠性：
    - 检查文件存在、状态一致性、阶段转换
    - 验证失败时输出 `[HARD STOP]` 及可操作建议
 
-2. **自动化状态转换** — `comet-guard.sh --apply` 自动更新 `.comet.yaml`
+2. **自动化状态转换** — `comet-guard.js --apply` 自动更新 `.comet.yaml`
    - 所有阶段转换（open → design/build → verify → archive）使用 `guard --apply`
    - 无需手动状态编辑 — 消除写入验证错误
-   - `comet-state.sh` 是 agent 对状态操作的专属接口
-   - Guard 和 archive 脚本内部使用 `comet-state.sh` 进行状态管理
+   - `comet-state.js` 是 agent 对状态操作的专属接口
+   - Guard 和 archive 脚本内部使用 `comet-state.js` 进行状态管理
 
-3. **模式校验** — `comet-yaml-validate.sh` 确保数据完整性
+3. **模式校验** — `comet-yaml-validate.js` 确保数据完整性
    - 校验必填字段和可选字段
    - 校验枚举值（包括 `direct_override`）
    - 校验 `design_doc`、`plan`、`handoff_context` 路径存在，并校验 `handoff_hash` 格式
@@ -364,7 +364,7 @@ Comet 通过自动化状态转换确保 agent 执行可靠性：
    - Guard 检查 `verification_report exists` 和 `branch_status=handled` 作为硬性前提
    - 防止验证或分支处理被跳过时产生虚假的阶段推进
 
-6. **归档自动化** — `comet-archive.sh` 一键处理完整归档流程
+6. **归档自动化** — `comet-archive.js` 一键处理完整归档流程
    - 验证入口状态、同步 delta specs 到 main specs
    - 标注设计文档和计划文档的 frontmatter
    - 将变更移至归档目录并更新 `archived: true`
@@ -379,12 +379,12 @@ your-project/
 ├── .claude/skills/              # 平台技能目录（Comet + OpenSpec + Superpowers）
 │   ├── comet/SKILL.md
 │   │   └── scripts/
-│   │       ├── comet-guard.sh       # 阶段转换守护（--apply 自动更新状态）
-│   │       ├── comet-env.sh         # 脚本发现助手
-│   │       ├── comet-handoff.sh     # 设计交接（OpenSpec → Superpowers 上下文追踪）
-│   │       ├── comet-archive.sh     # 一键归档自动化
-│   │       ├── comet-yaml-validate.sh # 模式校验器
-│   │       └── comet-state.sh       # 统一状态管理（init/set/get/check/scale）
+│   │       ├── comet-guard.js       # 阶段转换守护（--apply 自动更新状态）
+│   │       ├── comet-env.js         # 脚本发现助手
+│   │       ├── comet-handoff.js     # 设计交接（OpenSpec → Superpowers 上下文追踪）
+│   │       ├── comet-archive.js     # 一键归档自动化
+│   │       ├── comet-yaml-validate.js # 模式校验器
+│   │       └── comet-state.js       # 统一状态管理（init/set/get/check/scale）
 │   ├── comet-*/SKILL.md
 │   ├── openspec-*/SKILL.md
 │   └── brainstorming/SKILL.md
diff --git a/README.md b/README.md
index a27f0db4..429e8833 100644
--- a/README.md
+++ b/README.md
@@ -64,7 +64,7 @@ Long-term Skill users know these capabilities can be freely combined, but exactl
 
 - **How to turn document synchronization from "user reminders" into automation** — Comet puts handoff, state updates, validation, and archive sync into scripted flows, reducing repeated prompts like "remember to update the design doc", "remember to sync the spec", and "remember to archive the change".
 
-- **How to design guard conditions that Agents can execute** — Comet does not simply trust the Agent saying "done" at phase exits. Scripts such as `comet-guard.sh`, `comet-yaml-validate.sh`, and `comet-state.sh` check tasks, state fields, verification evidence, and archive conditions before allowing the workflow to advance.
+- **How to design guard conditions that Agents can execute** — Comet does not simply trust the Agent saying "done" at phase exits. Node scripts such as `comet-guard.js`, `comet-yaml-validate.js`, and `comet-state.js` check tasks, state fields, verification evidence, and archive conditions before allowing the workflow to advance.
 
 - **How to distribute and install Skills across platforms** — Comet supports multiple AI coding platforms, project/global installation, Chinese/English Skill choices, and platform-specific directory differences such as Antigravity using different project-level and global paths. It can be a reference for CLI installers and Skill package structure.
 
@@ -239,12 +239,12 @@ After `comet init`, three groups of skills are installed to the selected platfor
 
 | Script                   | Purpose                                                                                               |
 | ------------------------ | ----------------------------------------------------------------------------------------------------- |
-| `comet-env.sh`           | Script discovery helper — exports bundled script paths such as `COMET_GUARD`, `COMET_STATE`, `COMET_HANDOFF`, and `COMET_ARCHIVE` |
-| `comet-guard.sh`         | Phase transition guard — validates exit conditions, `--apply` auto-updates `.comet.yaml`              |
-| `comet-handoff.sh`       | Design handoff — generates deterministic context packages from OpenSpec artifacts with SHA256 tracing |
-| `comet-archive.sh`       | One-command archive — validates state, syncs specs, moves to archive, updates status                  |
-| `comet-yaml-validate.sh` | Schema validator — validates `.comet.yaml` structure and field values                                 |
-| `comet-state.sh`         | Unified state management — init/set/get/check/scale, agents' exclusive YAML interface                 |
+| `comet-env.js`           | Script discovery helper — prints bundled script paths such as `COMET_GUARD`, `COMET_STATE`, `COMET_HANDOFF`, and `COMET_ARCHIVE` as JSON |
+| `comet-guard.js`         | Phase transition guard — validates exit conditions, `--apply` auto-updates `.comet.yaml`              |
+| `comet-handoff.js`       | Design handoff — generates deterministic context packages from OpenSpec artifacts with SHA256 tracing |
+| `comet-archive.js`       | One-command archive — validates state, syncs specs, moves to archive, updates status                  |
+| `comet-yaml-validate.js` | Schema validator — validates `.comet.yaml` structure and field values                                 |
+| `comet-state.js`         | Unified state management — init/set/get/check/scale, agents' exclusive YAML interface                 |
 
 </details>
 
@@ -326,7 +326,7 @@ handoff_context: openspec/changes/<name>/.comet/handoff/design-context.json
 handoff_hash: <sha256>
 ```
 
-In full workflow, `build_mode`, `build_pause`, `isolation`, and `verify_mode` may temporarily be `null`; `build_mode` and `isolation` must be resolved before `build → verify`. `build_pause` records an internal build-phase pause point: `null` means no pause, while `plan-ready` means the plan has been generated and the user paused before choosing isolation and execution mode. It is not an execution mode and must not be written into `build_mode`. `verification_report` stays `null` until verification writes a report, and `verify-pass` requires that report to exist plus `branch_status: handled`. Fields after `archived` in the example are optional or script-derived: `direct_override` is only needed for full-workflow direct builds, project commands may be absent unless configured, and `handoff_context` / `handoff_hash` are recorded by `comet-handoff.sh` before leaving design. Projects can configure `build_command` / `verify_command` in the change or repo root, and guard will run those commands first and print failure output.
+In full workflow, `build_mode`, `build_pause`, `isolation`, and `verify_mode` may temporarily be `null`; `build_mode` and `isolation` must be resolved before `build → verify`. `build_pause` records an internal build-phase pause point: `null` means no pause, while `plan-ready` means the plan has been generated and the user paused before choosing isolation and execution mode. It is not an execution mode and must not be written into `build_mode`. `verification_report` stays `null` until verification writes a report, and `verify-pass` requires that report to exist plus `branch_status: handled`. Fields after `archived` in the example are optional or script-derived: `direct_override` is only needed for full-workflow direct builds, project commands may be absent unless configured, and `handoff_context` / `handoff_hash` are recorded by `comet-handoff.js` before leaving design. Projects can configure `build_command` / `verify_command` in the change or repo root, and guard will run those commands first and print failure output.
 
 </details>
 
@@ -341,13 +341,13 @@ Comet ensures agent execution reliability through automated state transitions:
    - Checks file existence, state consistency, and phase transitions
    - Outputs `[HARD STOP]` with actionable suggestions if validation fails
 
-2. **Automated State Transitions** — `comet-guard.sh --apply` updates `.comet.yaml` automatically
+2. **Automated State Transitions** — `comet-guard.js --apply` updates `.comet.yaml` automatically
    - All phase transitions (open → design/build → verify → archive) use `guard --apply`
    - No manual state editing required — eliminates write-verification errors
-   - `comet-state.sh` is the agents' exclusive interface for state operations
-   - Guard and archive scripts use `comet-state.sh` internally for state management
+   - `comet-state.js` is the agents' exclusive interface for state operations
+   - Guard and archive scripts use `comet-state.js` internally for state management
 
-3. **Schema Validation** — `comet-yaml-validate.sh` ensures data integrity
+3. **Schema Validation** — `comet-yaml-validate.js` ensures data integrity
    - Validates required and optional fields
    - Validates enum values, including `direct_override`
    - Validates `design_doc`, `plan`, and `handoff_context` paths exist, plus `handoff_hash` format
@@ -365,7 +365,7 @@ Comet ensures agent execution reliability through automated state transitions:
    - Guard checks `verification_report exists` and `branch_status=handled` as hard prerequisites
    - Prevents false phase advances when verification or branch handling was skipped
 
-6. **Archive Automation** — `comet-archive.sh` handles the full archive flow in one command
+6. **Archive Automation** — `comet-archive.js` handles the full archive flow in one command
    - Validates entry state, syncs delta specs to main specs
    - Annotates design doc and plan frontmatter
    - Moves change to archive directory and updates `archived: true`
@@ -380,12 +380,12 @@ your-project/
 ├── .claude/skills/              # Platform skills dir (Comet + OpenSpec + Superpowers)
 │   ├── comet/SKILL.md
 │   │   └── scripts/
-│   │       ├── comet-guard.sh       # Phase transition guard (--apply auto-updates state)
-│   │       ├── comet-env.sh         # Script discovery helper
-│   │       ├── comet-handoff.sh     # Design handoff (OpenSpec → Superpowers context tracing)
-│   │       ├── comet-archive.sh     # One-command archive automation
-│   │       ├── comet-yaml-validate.sh # Schema validator
-│   │       └── comet-state.sh       # Unified state management (init/set/get/check/scale)
+│   │       ├── comet-guard.js       # Phase transition guard (--apply auto-updates state)
+│   │       ├── comet-env.js         # Script discovery helper
+│   │       ├── comet-handoff.js     # Design handoff (OpenSpec → Superpowers context tracing)
+│   │       ├── comet-archive.js     # One-command archive automation
+│   │       ├── comet-yaml-validate.js # Schema validator
+│   │       └── comet-state.js       # Unified state management (init/set/get/check/scale)
 │   ├── comet-*/SKILL.md
 │   ├── openspec-*/SKILL.md
 │   └── brainstorming/SKILL.md
diff --git a/assets/manifest.json b/assets/manifest.json
index a606af72..6a8def66 100644
--- a/assets/manifest.json
+++ b/assets/manifest.json
@@ -3,12 +3,13 @@
   "skills": [
     "comet/SKILL.md",
     "comet/reference/dirty-worktree.md",
-    "comet/scripts/comet-env.sh",
-    "comet/scripts/comet-guard.sh",
-    "comet/scripts/comet-state.sh",
-    "comet/scripts/comet-handoff.sh",
-    "comet/scripts/comet-archive.sh",
-    "comet/scripts/comet-yaml-validate.sh",
+    "comet/scripts/comet-lib.js",
+    "comet/scripts/comet-env.js",
+    "comet/scripts/comet-guard.js",
+    "comet/scripts/comet-state.js",
+    "comet/scripts/comet-handoff.js",
+    "comet/scripts/comet-archive.js",
+    "comet/scripts/comet-yaml-validate.js",
     "comet-open/SKILL.md",
     "comet-design/SKILL.md",
     "comet-build/SKILL.md",
diff --git a/assets/skills-zh/comet-archive/SKILL.md b/assets/skills-zh/comet-archive/SKILL.md
index 6c1c5b59..7ee553d0 100644
--- a/assets/skills-zh/comet-archive/SKILL.md
+++ b/assets/skills-zh/comet-archive/SKILL.md
@@ -18,13 +18,17 @@ description: "Comet 阶段 5：归档。用 /comet-archive 调用。同步 delta
 执行入口验证：
 
 ```bash
-COMET_ENV="${COMET_ENV:-$(find . "$HOME"/.*/skills "$HOME/.config" "$HOME/.gemini" -path '*/comet/scripts/comet-env.sh' -type f -print -quit 2>/dev/null)}"
+COMET_ENV="${COMET_ENV:-$(find . "$HOME"/.*/skills "$HOME/.config" "$HOME/.gemini" -path '*/comet/scripts/comet-env.js' -type f -print -quit 2>/dev/null)}"
 if [ -z "$COMET_ENV" ]; then
-  echo "ERROR: comet-env.sh not found. Ensure the comet skill is installed." >&2
+  echo "ERROR: comet-env.js not found. Ensure the comet skill is installed." >&2
   return 1
 fi
-. "$COMET_ENV"
-"$COMET_BASH" "$COMET_STATE" check <name> archive
+COMET_ENV_JSON="$(node "$COMET_ENV")"
+COMET_STATE="$(printf '%s' "$COMET_ENV_JSON" | node -e "let s='';process.stdin.on('data',d=>s+=d).on('end',()=>console.log(JSON.parse(s).COMET_STATE))")"
+COMET_GUARD="$(printf '%s' "$COMET_ENV_JSON" | node -e "let s='';process.stdin.on('data',d=>s+=d).on('end',()=>console.log(JSON.parse(s).COMET_GUARD))")"
+COMET_HANDOFF="$(printf '%s' "$COMET_ENV_JSON" | node -e "let s='';process.stdin.on('data',d=>s+=d).on('end',()=>console.log(JSON.parse(s).COMET_HANDOFF))")"
+COMET_ARCHIVE="$(printf '%s' "$COMET_ENV_JSON" | node -e "let s='';process.stdin.on('data',d=>s+=d).on('end',()=>console.log(JSON.parse(s).COMET_ARCHIVE))")"
+node "$COMET_STATE" check <name> archive
 ```
 
 验证通过后继续 Step 1。验证失败时脚本会输出具体失败原因。
@@ -38,7 +42,7 @@ fi
 运行归档脚本，自动完成以下全部步骤：
 
 ```bash
-"$COMET_BASH" "$COMET_ARCHIVE" "<change-name>"
+node "$COMET_ARCHIVE" "<change-name>"
 ```
 
 脚本自动执行：
@@ -70,7 +74,7 @@ brainstorming → delta spec → 实施 → 验证 → 主 spec 覆盖 → desig
 - 归档目录 `openspec/changes/archive/YYYY-MM-DD-<change-name>/` 存在
 - 归档后的 `.comet.yaml` 中 `archived: true`
 
-归档脚本会把 `openspec/changes/<name>/` 移动到 `openspec/changes/archive/YYYY-MM-DD-<name>/`。归档成功后**不要再对原 change 名运行** `"$COMET_BASH" "$COMET_GUARD" <change-name> archive`，因为原活跃目录已经不存在。归档完整性以脚本退出码和归档目录状态为准。
+归档脚本会把 `openspec/changes/<name>/` 移动到 `openspec/changes/archive/YYYY-MM-DD-<name>/`。归档成功后**不要再对原 change 名运行** `node "$COMET_GUARD" <change-name> archive`，因为原活跃目录已经不存在。归档完整性以脚本退出码和归档目录状态为准。
 
 ## 完成
 
diff --git a/assets/skills-zh/comet-build/SKILL.md b/assets/skills-zh/comet-build/SKILL.md
index ae4772cf..ed41318f 100644
--- a/assets/skills-zh/comet-build/SKILL.md
+++ b/assets/skills-zh/comet-build/SKILL.md
@@ -17,13 +17,17 @@ description: "Comet 阶段 3：计划与构建。用 /comet-build 调用。制
 执行入口验证：
 
 ```bash
-COMET_ENV="${COMET_ENV:-$(find . "$HOME"/.*/skills "$HOME/.config" "$HOME/.gemini" -path '*/comet/scripts/comet-env.sh' -type f -print -quit 2>/dev/null)}"
+COMET_ENV="${COMET_ENV:-$(find . "$HOME"/.*/skills "$HOME/.config" "$HOME/.gemini" -path '*/comet/scripts/comet-env.js' -type f -print -quit 2>/dev/null)}"
 if [ -z "$COMET_ENV" ]; then
-  echo "ERROR: comet-env.sh not found. Ensure the comet skill is installed." >&2
+  echo "ERROR: comet-env.js not found. Ensure the comet skill is installed." >&2
   return 1
 fi
-. "$COMET_ENV"
-"$COMET_BASH" "$COMET_STATE" check <name> build
+COMET_ENV_JSON="$(node "$COMET_ENV")"
+COMET_STATE="$(printf '%s' "$COMET_ENV_JSON" | node -e "let s='';process.stdin.on('data',d=>s+=d).on('end',()=>console.log(JSON.parse(s).COMET_STATE))")"
+COMET_GUARD="$(printf '%s' "$COMET_ENV_JSON" | node -e "let s='';process.stdin.on('data',d=>s+=d).on('end',()=>console.log(JSON.parse(s).COMET_GUARD))")"
+COMET_HANDOFF="$(printf '%s' "$COMET_ENV_JSON" | node -e "let s='';process.stdin.on('data',d=>s+=d).on('end',()=>console.log(JSON.parse(s).COMET_HANDOFF))")"
+COMET_ARCHIVE="$(printf '%s' "$COMET_ENV_JSON" | node -e "let s='';process.stdin.on('data',d=>s+=d).on('end',()=>console.log(JSON.parse(s).COMET_ARCHIVE))")"
+node "$COMET_STATE" check <name> build
 ```
 
 验证通过后继续 Step 1。验证失败时脚本会输出具体失败原因。
@@ -64,7 +68,7 @@ git rev-parse HEAD
 先记录 plan 路径：
 
 ```bash
-"$COMET_BASH" "$COMET_STATE" set <name> plan docs/superpowers/plans/YYYY-MM-DD-feature.md
+node "$COMET_STATE" set <name> plan docs/superpowers/plans/YYYY-MM-DD-feature.md
 ```
 
 无需手动更新 phase，guard 会在退出条件满足后自动流转。
@@ -81,13 +85,13 @@ git rev-parse HEAD
 用户选择继续时：
 
 ```bash
-"$COMET_BASH" "$COMET_STATE" set <name> build_pause null
+node "$COMET_STATE" set <name> build_pause null
 ```
 
 用户选择暂停时：
 
 ```bash
-"$COMET_BASH" "$COMET_STATE" set <name> build_pause plan-ready
+node "$COMET_STATE" set <name> build_pause plan-ready
 ```
 
 设置 `build_pause: plan-ready` 后，当前调用停止。不要选择 `isolation` 或 `build_mode`，不要加载执行技能。
@@ -97,7 +101,7 @@ git rev-parse HEAD
 如果恢复时检测到 `build_pause: plan-ready` 且 `plan` 文件存在，不要重新运行 `writing-plans`。先告知用户当前停在 plan-ready 暂停点；用户确认继续后，设置：
 
 ```bash
-"$COMET_BASH" "$COMET_STATE" set <name> build_pause null
+node "$COMET_STATE" set <name> build_pause null
 ```
 
 然后继续本步骤选择工作区隔离和执行方式。
@@ -132,8 +136,8 @@ git rev-parse HEAD
 用户选择后，更新 `isolation` 和 `build_mode` 字段：
 
 ```bash
-"$COMET_BASH" "$COMET_STATE" set <name> isolation <branch|worktree>
-"$COMET_BASH" "$COMET_STATE" set <name> build_mode <subagent-driven-development|executing-plans|direct>
+node "$COMET_STATE" set <name> isolation <branch|worktree>
+node "$COMET_STATE" set <name> build_mode <subagent-driven-development|executing-plans|direct>
 ```
 
 `isolation` 是脚本级硬约束。full workflow 初始化时可以为 `null`，但只允许存在到本步骤之前。若保持 `null`，`build → verify` 的 guard 和 `comet-state transition build-complete` 都会失败。
@@ -141,8 +145,8 @@ git rev-parse HEAD
 `build_mode` 默认仅 hotfix/tweak preset 使用 `direct`。full workflow 不得默认使用 `direct`。只有用户明确要求跳过计划执行技能，且你已记录显式 override 时，才允许：
 
 ```bash
-"$COMET_BASH" "$COMET_STATE" set <name> direct_override true
-"$COMET_BASH" "$COMET_STATE" set <name> build_mode direct
+node "$COMET_STATE" set <name> direct_override true
+node "$COMET_STATE" set <name> build_mode direct
 ```
 
 没有 `direct_override: true` 时，full workflow 的 `build_mode=direct` 会被 guard 和状态转换同时拦截。
@@ -196,7 +200,7 @@ Language: 使用触发本次工作流的用户请求语言输出。
 Build 是最长阶段，可能跨越大量任务。为支持上下文压缩后断点恢复：
 
 - **每完成一个 task**：立即勾选 tasks.md 并提交代码，确保 `.comet.yaml` 和文件状态持久化
-- **上下文压缩后恢复**：先运行 `"$COMET_BASH" "$COMET_STATE" check <change-name> build --recover`，脚本输出结构化恢复上下文（isolation/build_mode 状态、plan 路径、任务完成进度、恢复动作）。根据 Recovery action 决定下一步。
+- **上下文压缩后恢复**：先运行 `node "$COMET_STATE" check <change-name> build --recover`，脚本输出结构化恢复上下文（isolation/build_mode 状态、plan 路径、任务完成进度、恢复动作）。根据 Recovery action 决定下一步。
 - **用户手动修改恢复**：按 `comet/reference/dirty-worktree.md` 协议处理未提交改动。该协议定义了检查步骤、归因分类和禁令。build 阶段的特殊处理：
   1. 归因后，若 diff 暗示计划或 spec 已变化，按 Step 4「Spec 增量更新」分级处理
 - **长任务拆分**：单任务超过 200 行代码变更时，考虑拆分为多个子任务分别提交
@@ -208,7 +212,7 @@ Build 是最长阶段，可能跨越大量任务。为支持上下文压缩后
 - 已显式运行项目对应的构建/测试命令并通过（不要只依赖 guard 自动猜测）
 - `isolation` 已写为 `branch` 或 `worktree`
 - `build_mode` 已写为 `subagent-driven-development`、`executing-plans` 或带显式 override 的 `direct`
-- **阶段守卫**：运行 `"$COMET_BASH" "$COMET_GUARD" <change-name> build --apply`，全部 PASS 后自动流转到 `phase: verify`
+- **阶段守卫**：运行 `node "$COMET_GUARD" <change-name> build --apply`，全部 PASS 后自动流转到 `phase: verify`
 
 Guard 会优先读取项目配置中的命令：
 
@@ -223,7 +227,7 @@ verify_command: <verify command>
 退出前运行 guard 自动流转：
 
 ```bash
-"$COMET_BASH" "$COMET_GUARD" <change-name> build --apply
+node "$COMET_GUARD" <change-name> build --apply
 ```
 
 状态文件自动更新为 `phase: verify`、`verify_result: pending`。
diff --git a/assets/skills-zh/comet-design/SKILL.md b/assets/skills-zh/comet-design/SKILL.md
index 587ab32b..2e7f55cd 100644
--- a/assets/skills-zh/comet-design/SKILL.md
+++ b/assets/skills-zh/comet-design/SKILL.md
@@ -17,13 +17,17 @@ description: "Comet 阶段 2：深度设计。用 /comet-design 调用。通过
 执行入口验证：
 
 ```bash
-COMET_ENV="${COMET_ENV:-$(find . "$HOME"/.*/skills "$HOME/.config" "$HOME/.gemini" -path '*/comet/scripts/comet-env.sh' -type f -print -quit 2>/dev/null)}"
+COMET_ENV="${COMET_ENV:-$(find . "$HOME"/.*/skills "$HOME/.config" "$HOME/.gemini" -path '*/comet/scripts/comet-env.js' -type f -print -quit 2>/dev/null)}"
 if [ -z "$COMET_ENV" ]; then
-  echo "ERROR: comet-env.sh not found. Ensure the comet skill is installed." >&2
+  echo "ERROR: comet-env.js not found. Ensure the comet skill is installed." >&2
   return 1
 fi
-. "$COMET_ENV"
-"$COMET_BASH" "$COMET_STATE" check <name> design
+COMET_ENV_JSON="$(node "$COMET_ENV")"
+COMET_STATE="$(printf '%s' "$COMET_ENV_JSON" | node -e "let s='';process.stdin.on('data',d=>s+=d).on('end',()=>console.log(JSON.parse(s).COMET_STATE))")"
+COMET_GUARD="$(printf '%s' "$COMET_ENV_JSON" | node -e "let s='';process.stdin.on('data',d=>s+=d).on('end',()=>console.log(JSON.parse(s).COMET_GUARD))")"
+COMET_HANDOFF="$(printf '%s' "$COMET_ENV_JSON" | node -e "let s='';process.stdin.on('data',d=>s+=d).on('end',()=>console.log(JSON.parse(s).COMET_HANDOFF))")"
+COMET_ARCHIVE="$(printf '%s' "$COMET_ENV_JSON" | node -e "let s='';process.stdin.on('data',d=>s+=d).on('end',()=>console.log(JSON.parse(s).COMET_ARCHIVE))")"
+node "$COMET_STATE" check <name> design
 ```
 
 验证通过后继续 Step 1。验证失败时脚本会输出具体失败原因。
@@ -35,7 +39,7 @@ fi
 **必须由脚本生成，不允许 agent 临场手写 summary 代替。**
 
 ```bash
-"$COMET_BASH" "$COMET_HANDOFF" <change-name> design --write
+node "$COMET_HANDOFF" <change-name> design --write
 ```
 
 脚本会生成并记录：
@@ -60,7 +64,7 @@ handoff_hash: <sha256>
 如确实需要全文上下文，可显式运行：
 
 ```bash
-"$COMET_BASH" "$COMET_HANDOFF" <change-name> design --write --full
+node "$COMET_HANDOFF" <change-name> design --write --full
 ```
 
 交接包来源来自 OpenSpec open 阶段产物：
@@ -122,13 +126,13 @@ brainstorming 产出设计方案后，**必须使用 AskUserQuestion 工具暂
 
 ```bash
 # 记录 design_doc 路径
-"$COMET_BASH" "$COMET_STATE" set <name> design_doc docs/superpowers/specs/YYYY-MM-DD-topic-design.md
+node "$COMET_STATE" set <name> design_doc docs/superpowers/specs/YYYY-MM-DD-topic-design.md
 
 # 如有 delta spec 变更，重新生成 handoff（更新 hash）
-"$COMET_BASH" "$COMET_HANDOFF" <change-name> design --write
+node "$COMET_HANDOFF" <change-name> design --write
 
 # 自动流转到下一阶段
-"$COMET_BASH" "$COMET_GUARD" <change-name> design --apply
+node "$COMET_GUARD" <change-name> design --apply
 ```
 
 如果没有 delta spec 变更，跳过 handoff 重新生成步骤。状态文件自动更新，无需手动编辑其他字段。
@@ -142,12 +146,12 @@ brainstorming 产出设计方案后，**必须使用 AskUserQuestion 工具暂
 - `design-context.md` 必须是脚本生成，且包含 source path、mode、sha256 等可追溯标记（由 guard 强制校验）
 - 如有新能力或补充验收场景，OpenSpec delta spec 已创建/更新
 - `design_doc` 已写入 `.comet.yaml`
-- **阶段守卫**：运行 `"$COMET_BASH" "$COMET_GUARD" <change-name> design --apply`，全部 PASS 后自动流转到 `phase: build`
+- **阶段守卫**：运行 `node "$COMET_GUARD" <change-name> design --apply`，全部 PASS 后自动流转到 `phase: build`
 
 退出前必须使用 `--apply`：
 
 ```bash
-"$COMET_BASH" "$COMET_GUARD" <change-name> design --apply
+node "$COMET_GUARD" <change-name> design --apply
 ```
 
 ## 上下文压缩恢复
@@ -155,7 +159,7 @@ brainstorming 产出设计方案后，**必须使用 AskUserQuestion 工具暂
 design 阶段在 brainstorming 过程中可能触发上下文压缩。恢复时先运行：
 
 ```bash
-"$COMET_BASH" "$COMET_STATE" check <change-name> design --recover
+node "$COMET_STATE" check <change-name> design --recover
 ```
 
 脚本输出结构化恢复上下文（阶段、已完成字段、待完成字段、恢复动作）。按 Recovery action 判断下一步。
diff --git a/assets/skills-zh/comet-hotfix/SKILL.md b/assets/skills-zh/comet-hotfix/SKILL.md
index 43235755..51c6678b 100644
--- a/assets/skills-zh/comet-hotfix/SKILL.md
+++ b/assets/skills-zh/comet-hotfix/SKILL.md
@@ -23,12 +23,16 @@ description: "Comet 预设路径：Bug fix / 热修复。跳过 brainstorming，
 开始前先定位 Comet 脚本：
 
 ```bash
-COMET_ENV="${COMET_ENV:-$(find . "$HOME"/.*/skills "$HOME/.config" "$HOME/.gemini" -path '*/comet/scripts/comet-env.sh' -type f -print -quit 2>/dev/null)}"
+COMET_ENV="${COMET_ENV:-$(find . "$HOME"/.*/skills "$HOME/.config" "$HOME/.gemini" -path '*/comet/scripts/comet-env.js' -type f -print -quit 2>/dev/null)}"
 if [ -z "$COMET_ENV" ]; then
-  echo "ERROR: comet-env.sh not found. Ensure the comet skill is installed." >&2
+  echo "ERROR: comet-env.js not found. Ensure the comet skill is installed." >&2
   return 1
 fi
-. "$COMET_ENV"
+COMET_ENV_JSON="$(node "$COMET_ENV")"
+COMET_STATE="$(printf '%s' "$COMET_ENV_JSON" | node -e "let s='';process.stdin.on('data',d=>s+=d).on('end',()=>console.log(JSON.parse(s).COMET_STATE))")"
+COMET_GUARD="$(printf '%s' "$COMET_ENV_JSON" | node -e "let s='';process.stdin.on('data',d=>s+=d).on('end',()=>console.log(JSON.parse(s).COMET_GUARD))")"
+COMET_HANDOFF="$(printf '%s' "$COMET_ENV_JSON" | node -e "let s='';process.stdin.on('data',d=>s+=d).on('end',()=>console.log(JSON.parse(s).COMET_HANDOFF))")"
+COMET_ARCHIVE="$(printf '%s' "$COMET_ENV_JSON" | node -e "let s='';process.stdin.on('data',d=>s+=d).on('end',()=>console.log(JSON.parse(s).COMET_ARCHIVE))")"
 ```
 
 ### 1. 快速开启（preset open）
@@ -54,19 +58,19 @@ Language: 使用触发本次工作流的用户请求语言输出。
 初始化 Comet 状态文件：
 
 ```bash
-"$COMET_BASH" "$COMET_STATE" init <name> hotfix
+node "$COMET_STATE" init <name> hotfix
 ```
 
 初始化后验证状态：
 
 ```bash
-"$COMET_BASH" "$COMET_STATE" check <name> open
+node "$COMET_STATE" check <name> open
 ```
 
 阶段守卫完成 open → build 过渡：
 
 ```bash
-"$COMET_BASH" "$COMET_GUARD" <change-name> open --apply
+node "$COMET_GUARD" <change-name> open --apply
 ```
 
 ### 2. 直接构建（preset build）
@@ -105,7 +109,7 @@ Language: 使用触发本次工作流的用户请求语言输出。
 根因确认消除后，运行阶段守卫完成 build → verify 过渡：
 
 ```bash
-"$COMET_BASH" "$COMET_GUARD" <change-name> build --apply
+node "$COMET_GUARD" <change-name> build --apply
 ```
 
 状态文件自动更新为 `phase: verify`、`verify_result: pending`，然后进入验证。
@@ -162,7 +166,7 @@ Hotfix 流程为 **一次性连续执行**。调用 `/comet-hotfix` 后，agent
 用户确认升级后，**必须先更新 workflow 字段**再进入完整流程：
 
 ```bash
-"$COMET_BASH" "$COMET_STATE" set <name> workflow full
+node "$COMET_STATE" set <name> workflow full
 ```
 
 然后在当前 change 基础上补充 Design Doc：**立即使用 Skill 工具加载 `comet-design` skill**，后续正常走完整流程。若用户不确认升级，停止 hotfix 并报告当前变更已超出 hotfix 适用范围。
@@ -174,4 +178,4 @@ Hotfix 流程为 **一次性连续执行**。调用 `/comet-hotfix` 后，agent
 - Bug 已修复，测试通过
 - change 已归档
 - 如有 spec 变更，已同步到 main spec
-- **阶段守卫**：build → verify 前运行 `"$COMET_BASH" "$COMET_GUARD" <change-name> build --apply`，verify → archive 前按 `/comet-verify` 规则运行 `"$COMET_BASH" "$COMET_GUARD" <change-name> verify --apply`
+- **阶段守卫**：build → verify 前运行 `node "$COMET_GUARD" <change-name> build --apply`，verify → archive 前按 `/comet-verify` 规则运行 `node "$COMET_GUARD" <change-name> verify --apply`
diff --git a/assets/skills-zh/comet-open/SKILL.md b/assets/skills-zh/comet-open/SKILL.md
index d09fbd6b..2f1ad9f3 100644
--- a/assets/skills-zh/comet-open/SKILL.md
+++ b/assets/skills-zh/comet-open/SKILL.md
@@ -53,19 +53,23 @@ openspec/changes/<name>/
 创建 `.comet.yaml` 状态文件：
 
 ```bash
-COMET_ENV="${COMET_ENV:-$(find . "$HOME"/.*/skills "$HOME/.config" "$HOME/.gemini" -path '*/comet/scripts/comet-env.sh' -type f -print -quit 2>/dev/null)}"
+COMET_ENV="${COMET_ENV:-$(find . "$HOME"/.*/skills "$HOME/.config" "$HOME/.gemini" -path '*/comet/scripts/comet-env.js' -type f -print -quit 2>/dev/null)}"
 if [ -z "$COMET_ENV" ]; then
-  echo "ERROR: comet-env.sh not found. Ensure the comet skill is installed." >&2
+  echo "ERROR: comet-env.js not found. Ensure the comet skill is installed." >&2
   return 1
 fi
-. "$COMET_ENV"
+COMET_ENV_JSON="$(node "$COMET_ENV")"
+COMET_STATE="$(printf '%s' "$COMET_ENV_JSON" | node -e "let s='';process.stdin.on('data',d=>s+=d).on('end',()=>console.log(JSON.parse(s).COMET_STATE))")"
+COMET_GUARD="$(printf '%s' "$COMET_ENV_JSON" | node -e "let s='';process.stdin.on('data',d=>s+=d).on('end',()=>console.log(JSON.parse(s).COMET_GUARD))")"
+COMET_HANDOFF="$(printf '%s' "$COMET_ENV_JSON" | node -e "let s='';process.stdin.on('data',d=>s+=d).on('end',()=>console.log(JSON.parse(s).COMET_HANDOFF))")"
+COMET_ARCHIVE="$(printf '%s' "$COMET_ENV_JSON" | node -e "let s='';process.stdin.on('data',d=>s+=d).on('end',()=>console.log(JSON.parse(s).COMET_ARCHIVE))")"
 
 if [ -z "$COMET_STATE" ] || [ -z "$COMET_GUARD" ]; then
   echo "ERROR: Comet scripts not found. Ensure the comet skill is installed." >&2
   return 1
 fi
 
-"$COMET_BASH" "$COMET_STATE" init <name> full
+node "$COMET_STATE" init <name> full
 ```
 
 ### 3. 入口状态验证
@@ -73,7 +77,7 @@ fi
 验证状态机已正确初始化：
 
 ```bash
-"$COMET_BASH" "$COMET_STATE" check <name> open
+node "$COMET_STATE" check <name> open
 ```
 
 验证通过后继续 Step 4。验证失败时脚本会输出具体失败原因。
@@ -110,12 +114,12 @@ AskUserQuestion 必须以单选题形式呈现，包含以下摘要和选项：
 
 - proposal.md、design.md、tasks.md 均已创建且内容完整
 - **用户已确认** proposal、design、tasks 内容符合预期
-- **阶段守卫**：运行 `"$COMET_BASH" "$COMET_GUARD" <change-name> open --apply`，全部 PASS 后自动流转到下一阶段
+- **阶段守卫**：运行 `node "$COMET_GUARD" <change-name> open --apply`，全部 PASS 后自动流转到下一阶段
 
 退出前必须使用 `--apply`，否则 `.comet.yaml` 仍停留在 `phase: open`，下一阶段入口检查会失败。
 
 ```bash
-"$COMET_BASH" "$COMET_GUARD" <change-name> open --apply
+node "$COMET_GUARD" <change-name> open --apply
 ```
 
 完整流程会自动更新为 `phase: design`；hotfix/tweak preset 会自动更新为 `phase: build`。
diff --git a/assets/skills-zh/comet-tweak/SKILL.md b/assets/skills-zh/comet-tweak/SKILL.md
index dd5593b0..15ebbd9a 100644
--- a/assets/skills-zh/comet-tweak/SKILL.md
+++ b/assets/skills-zh/comet-tweak/SKILL.md
@@ -26,12 +26,16 @@ Tweak 是 Comet 五阶段能力的预设工作流，不是独立的平行流程
 开始前先定位 Comet 脚本：
 
 ```bash
-COMET_ENV="${COMET_ENV:-$(find . "$HOME"/.*/skills "$HOME/.config" "$HOME/.gemini" -path '*/comet/scripts/comet-env.sh' -type f -print -quit 2>/dev/null)}"
+COMET_ENV="${COMET_ENV:-$(find . "$HOME"/.*/skills "$HOME/.config" "$HOME/.gemini" -path '*/comet/scripts/comet-env.js' -type f -print -quit 2>/dev/null)}"
 if [ -z "$COMET_ENV" ]; then
-  echo "ERROR: comet-env.sh not found. Ensure the comet skill is installed." >&2
+  echo "ERROR: comet-env.js not found. Ensure the comet skill is installed." >&2
   return 1
 fi
-. "$COMET_ENV"
+COMET_ENV_JSON="$(node "$COMET_ENV")"
+COMET_STATE="$(printf '%s' "$COMET_ENV_JSON" | node -e "let s='';process.stdin.on('data',d=>s+=d).on('end',()=>console.log(JSON.parse(s).COMET_STATE))")"
+COMET_GUARD="$(printf '%s' "$COMET_ENV_JSON" | node -e "let s='';process.stdin.on('data',d=>s+=d).on('end',()=>console.log(JSON.parse(s).COMET_GUARD))")"
+COMET_HANDOFF="$(printf '%s' "$COMET_ENV_JSON" | node -e "let s='';process.stdin.on('data',d=>s+=d).on('end',()=>console.log(JSON.parse(s).COMET_HANDOFF))")"
+COMET_ARCHIVE="$(printf '%s' "$COMET_ENV_JSON" | node -e "let s='';process.stdin.on('data',d=>s+=d).on('end',()=>console.log(JSON.parse(s).COMET_ARCHIVE))")"
 ```
 
 ### 1. 快速开启（preset open）
@@ -57,19 +61,19 @@ Language: 使用触发本次工作流的用户请求语言输出。
 初始化 Comet 状态文件：
 
 ```bash
-"$COMET_BASH" "$COMET_STATE" init <name> tweak
+node "$COMET_STATE" init <name> tweak
 ```
 
 初始化后验证状态：
 
 ```bash
-"$COMET_BASH" "$COMET_STATE" check <name> open
+node "$COMET_STATE" check <name> open
 ```
 
 阶段守卫完成 open → build 过渡：
 
 ```bash
-"$COMET_BASH" "$COMET_GUARD" <change-name> open --apply
+node "$COMET_GUARD" <change-name> open --apply
 ```
 
 ### 2. 轻量构建（preset build）
@@ -91,7 +95,7 @@ Language: 使用触发本次工作流的用户请求语言输出。
 4. 运行阶段守卫完成 build → verify 过渡：
 
 ```bash
-"$COMET_BASH" "$COMET_GUARD" <change-name> build --apply
+node "$COMET_GUARD" <change-name> build --apply
 ```
 
 状态文件自动更新为 `phase: verify`、`verify_result: pending`，然后进入验证。
@@ -147,7 +151,7 @@ Tweak 流程为 **一次性连续执行**。调用 `/comet-tweak` 后，agent 
 用户确认升级后，**必须先更新 workflow 字段**再进入完整流程：
 
 ```bash
-"$COMET_BASH" "$COMET_STATE" set <name> workflow full
+node "$COMET_STATE" set <name> workflow full
 ```
 
 然后在当前 change 基础上补充 Design Doc：**立即使用 Skill 工具加载 `comet-design` skill**，后续正常走完整流程。若用户不确认升级，停止 tweak 并报告当前变更已超出 tweak 适用范围。
@@ -159,4 +163,4 @@ Tweak 流程为 **一次性连续执行**。调用 `/comet-tweak` 后，agent 
 - 小改动已完成，测试通过
 - change 已归档
 - 未新增 capability、架构调整或接口变化
-- **阶段守卫**：build → verify 前运行 `"$COMET_BASH" "$COMET_GUARD" <change-name> build --apply`，verify → archive 前按 `/comet-verify` 规则运行 `"$COMET_BASH" "$COMET_GUARD" <change-name> verify --apply`
+- **阶段守卫**：build → verify 前运行 `node "$COMET_GUARD" <change-name> build --apply`，verify → archive 前按 `/comet-verify` 规则运行 `node "$COMET_GUARD" <change-name> verify --apply`
diff --git a/assets/skills-zh/comet-verify/SKILL.md b/assets/skills-zh/comet-verify/SKILL.md
index 06b54fee..504d03bd 100644
--- a/assets/skills-zh/comet-verify/SKILL.md
+++ b/assets/skills-zh/comet-verify/SKILL.md
@@ -17,13 +17,17 @@ description: "Comet 阶段 4：验证与收尾。用 /comet-verify 调用。验
 执行入口验证：
 
 ```bash
-COMET_ENV="${COMET_ENV:-$(find . "$HOME"/.*/skills "$HOME/.config" "$HOME/.gemini" -path '*/comet/scripts/comet-env.sh' -type f -print -quit 2>/dev/null)}"
+COMET_ENV="${COMET_ENV:-$(find . "$HOME"/.*/skills "$HOME/.config" "$HOME/.gemini" -path '*/comet/scripts/comet-env.js' -type f -print -quit 2>/dev/null)}"
 if [ -z "$COMET_ENV" ]; then
-  echo "ERROR: comet-env.sh not found. Ensure the comet skill is installed." >&2
+  echo "ERROR: comet-env.js not found. Ensure the comet skill is installed." >&2
   return 1
 fi
-. "$COMET_ENV"
-"$COMET_BASH" "$COMET_STATE" check <change-name> verify
+COMET_ENV_JSON="$(node "$COMET_ENV")"
+COMET_STATE="$(printf '%s' "$COMET_ENV_JSON" | node -e "let s='';process.stdin.on('data',d=>s+=d).on('end',()=>console.log(JSON.parse(s).COMET_STATE))")"
+COMET_GUARD="$(printf '%s' "$COMET_ENV_JSON" | node -e "let s='';process.stdin.on('data',d=>s+=d).on('end',()=>console.log(JSON.parse(s).COMET_GUARD))")"
+COMET_HANDOFF="$(printf '%s' "$COMET_ENV_JSON" | node -e "let s='';process.stdin.on('data',d=>s+=d).on('end',()=>console.log(JSON.parse(s).COMET_HANDOFF))")"
+COMET_ARCHIVE="$(printf '%s' "$COMET_ENV_JSON" | node -e "let s='';process.stdin.on('data',d=>s+=d).on('end',()=>console.log(JSON.parse(s).COMET_ARCHIVE))")"
+node "$COMET_STATE" check <change-name> verify
 ```
 
 验证通过后继续 Step 1。验证失败时脚本会输出具体失败原因。
@@ -39,7 +43,7 @@ fi
 执行规模评估：
 
 ```bash
-"$COMET_BASH" "$COMET_STATE" scale <change-name>
+node "$COMET_STATE" scale <change-name>
 ```
 
 脚本自动统计任务数、增量规格数、变更文件数，判断使用 light 或 full 验证模式，并设置 verify_mode 字段。
@@ -54,13 +58,13 @@ fi
 
 ```bash
 # 仅在用户确认修复后执行
-"$COMET_BASH" "$COMET_STATE" transition <change-name> verify-fail
+node "$COMET_STATE" transition <change-name> verify-fail
 ```
 
 注意：如果 build 阶段每个任务都已提交，脚本基于工作区 diff 的文件数可能低估改动规模。此时必须读取 plan 文件头的 `base-ref` 并用提交区间复核：
 
 ```bash
-PLAN=$("$COMET_BASH" "$COMET_STATE" get <change-name> plan)
+PLAN=$(node "$COMET_STATE" get <change-name> plan)
 BASE_REF=$(grep '^base-ref:' "$PLAN" 2>/dev/null | head -1 | sed 's/^base-ref: *//')
 git diff --stat "$BASE_REF"...HEAD
 ```
@@ -68,12 +72,12 @@ git diff --stat "$BASE_REF"...HEAD
 若提交区间显示改动超过轻量阈值（> 4 个文件、跨模块协调、或 delta spec 超过 1 个 capability），手动设置为完整验证：
 
 ```bash
-"$COMET_BASH" "$COMET_STATE" set <change-name> verify_mode full
+node "$COMET_STATE" set <change-name> verify_mode full
 ```
 
 ### 1b. 验证失败决策（阻塞点）
 
-验证不通过时**必须使用 AskUserQuestion 工具暂停并等待用户决定修复或接受偏差**。不得自动运行 `"$COMET_BASH" "$COMET_STATE" transition <change-name> verify-fail`，也不得自动调用 `/comet-build`。禁止仅输出文字提示后继续执行。
+验证不通过时**必须使用 AskUserQuestion 工具暂停并等待用户决定修复或接受偏差**。不得自动运行 `node "$COMET_STATE" transition <change-name> verify-fail`，也不得自动调用 `/comet-build`。禁止仅输出文字提示后继续执行。
 
 暂停时必须列出：
 - 失败项
@@ -83,7 +87,7 @@ git diff --stat "$BASE_REF"...HEAD
 **不确定性原则**：无法确定严重程度时，降级处理（SUGGESTION > WARNING > CRITICAL）。仅对构建失败、测试失败、安全问题使用 CRITICAL；模糊或不确定的问题标为 WARNING 或 SUGGESTION。
 
 用户选择后按以下方式继续：
-- **全部修复**：运行 `"$COMET_BASH" "$COMET_STATE" transition <change-name> verify-fail`，然后调用 `/comet-build` 修复
+- **全部修复**：运行 `node "$COMET_STATE" transition <change-name> verify-fail`，然后调用 `/comet-build` 修复
 - **逐项处理**：CRITICAL 失败项必须修复；非 CRITICAL 失败项可选择接受偏差，但必须在验证报告中记录接受原因和影响范围。若存在任何 CRITICAL 失败项，不允许跳过修复直接全部接受
 
 ### 2a. 轻量验证（小改动）
@@ -102,7 +106,7 @@ git diff --stat "$BASE_REF"...HEAD
 
 ```bash
 # 仅在用户确认修复后执行
-"$COMET_BASH" "$COMET_STATE" transition <change-name> verify-fail
+node "$COMET_STATE" transition <change-name> verify-fail
 ```
 
 **报告格式**：简表列出 5 项检查结果 + PASS/FAIL。
@@ -132,13 +136,13 @@ git diff --stat "$BASE_REF"...HEAD
 
 ```bash
 # 仅在用户确认修复后执行
-"$COMET_BASH" "$COMET_STATE" transition <change-name> verify-fail
+node "$COMET_STATE" transition <change-name> verify-fail
 ```
 
 **Spec 漂移处理**（用户决策点）：
 - 若检查项 6 发现矛盾（delta spec 有内容但 design doc 未体现），**必须使用 AskUserQuestion 工具以单选题形式暂停并等待用户选择处理方式**，不得自动选择。选项：
   - 选项 A：在 design doc 追加 "Implementation Divergence" 节记录偏差原因。选项 A 属于 verify 阶段允许产物；写入后不得因该 design doc 变更再次触发 Step 1b dirty-worktree 决策
-  - 选项 B：用户选择 B 后，运行 `"$COMET_BASH" "$COMET_STATE" transition <change-name> verify-fail`，然后调用 `/comet-build`；由 `/comet-build` 的 Spec 增量更新规则加载 Superpowers `brainstorming` 更新 Design Doc + delta spec
+  - 选项 B：用户选择 B 后，运行 `node "$COMET_STATE" transition <change-name> verify-fail`，然后调用 `/comet-build`；由 `/comet-build` 的 Spec 增量更新规则加载 Superpowers `brainstorming` 更新 Design Doc + delta spec
   - 选项 C：确认偏差可接受，继续验证（归档时 design doc 将标记为 `superseded-by-main-spec`）
 
 ### 3. 收尾（Superpowers）
@@ -168,8 +172,8 @@ mkdir -p docs/superpowers/reports
 # 将本次验证结论写入报告文件，例如：
 # docs/superpowers/reports/YYYY-MM-DD-<change-name>-verify.md
 
-"$COMET_BASH" "$COMET_STATE" set <change-name> verification_report docs/superpowers/reports/YYYY-MM-DD-<change-name>-verify.md
-"$COMET_BASH" "$COMET_STATE" set <change-name> branch_status handled
+node "$COMET_STATE" set <change-name> verification_report docs/superpowers/reports/YYYY-MM-DD-<change-name>-verify.md
+node "$COMET_STATE" set <change-name> branch_status handled
 ```
 
 ## 退出条件
@@ -178,12 +182,12 @@ mkdir -p docs/superpowers/reports
 - 分支已处理
 - `.comet.yaml` 中 `verification_report` 指向已存在的验证报告文件
 - `.comet.yaml` 中 `branch_status: handled`
-- **阶段守卫**：运行 `"$COMET_BASH" "$COMET_GUARD" <change-name> verify --apply`，全部 PASS 后通过 `comet-state transition verify-pass` 自动流转到 `phase: archive`
+- **阶段守卫**：运行 `node "$COMET_GUARD" <change-name> verify --apply`，全部 PASS 后通过 `comet-state transition verify-pass` 自动流转到 `phase: archive`
 
 验证和分支处理均完成后，运行 guard 自动流转：
 
 ```bash
-"$COMET_BASH" "$COMET_GUARD" <change-name> verify --apply
+node "$COMET_GUARD" <change-name> verify --apply
 ```
 
 状态文件自动更新为 `phase: archive`、`verify_result: pass`、`verified_at: YYYY-MM-DD`。
@@ -193,7 +197,7 @@ mkdir -p docs/superpowers/reports
 Verify 阶段可能触发上下文压缩。恢复时先运行：
 
 ```bash
-"$COMET_BASH" "$COMET_STATE" check <change-name> verify --recover
+node "$COMET_STATE" check <change-name> verify --recover
 ```
 
 脚本输出结构化恢复上下文（phase、验证状态、分支状态、恢复动作），根据输出的 Recovery action 决定下一步。
diff --git a/assets/skills-zh/comet/SKILL.md b/assets/skills-zh/comet/SKILL.md
index b8008b06..34cc777a 100644
--- a/assets/skills-zh/comet/SKILL.md
+++ b/assets/skills-zh/comet/SKILL.md
@@ -67,8 +67,8 @@ agent 做决策只需读本节，参考附录按需查阅。
   - 若 `build_pause: plan-ready` 但 plan 文件缺失，回到 `/comet-build` 处理状态损坏或重新生成 plan
   - 若 `build_mode` 或 `isolation` 未设置，回到 `/comet-build` 对应步骤补充后再执行
   - 若均已设置，读取 tasks.md 的下一个未勾选任务继续
-- 若 `phase: verify` 且 `verify_result: fail`，进入验证失败决策阻塞点：暂停并询问用户修复或接受偏差；用户选择修复后才运行 `"$COMET_BASH" "$COMET_STATE" transition <name> verify-fail` 并调用 `/comet-build`
-- 若 `phase: open` 但 proposal/design/tasks 已完整，先运行 `"$COMET_BASH" "$COMET_GUARD" <change-name> open --apply` 修正状态，再继续判定
+- 若 `phase: verify` 且 `verify_result: fail`，进入验证失败决策阻塞点：暂停并询问用户修复或接受偏差；用户选择修复后才运行 `node "$COMET_STATE" transition <name> verify-fail` 并调用 `/comet-build`
+- 若 `phase: open` 但 proposal/design/tasks 已完整，先运行 `node "$COMET_GUARD" <change-name> open --apply` 修正状态，再继续判定
 - 若 `phase: archive`，只允许调用 `/comet-archive`；归档成功后 change 会移动到 archive 目录，不再对原活跃目录运行 guard
 
 **Step 2: 阶段判定**（按顺序，命中即停）
@@ -105,7 +105,7 @@ agent 做决策只需读本节，参考附录按需查阅。
 |------|---------|
 | `openspec list --json` 失败 | 检查 openspec 是否已安装，提示 `openspec init` |
 | 子 skill 不可用 | 停止流程，提示安装或启用对应 skill |
-| `.comet.yaml` 格式异常或缺失 | 以文件状态为准，用 `"$COMET_BASH" "$COMET_STATE" set` 修正后继续 |
+| `.comet.yaml` 格式异常或缺失 | 以文件状态为准，用 `node "$COMET_STATE" set` 修正后继续 |
 | 构建/测试失败 | 返回 build 阶段修复，不进入 verify |
 | change 目录结构不完整 | 按 `comet-open` 产物要求补齐 |
 
@@ -226,24 +226,28 @@ archived: false
 - `build → verify` 前，`build_mode` 必须已选择
 - `build_mode: direct` 默认只允许 `hotfix` / `tweak`；full workflow 需要 `direct_override: true`
 - `build_pause` 不是执行方式，不得写入 `build_mode`
-- 这些约束同时存在于 `comet-guard.sh build --apply` 和 `comet-state.sh transition <name> build-complete`
+- 这些约束同时存在于 `comet-guard.js build --apply` 和 `comet-state.js transition <name> build-complete`
 
 ### 脚本定位
 
 Comet 脚本随 skill 包分发在 `comet/scripts/` 下。**不硬编码路径** — 定位一次，缓存到环境变量：
 
 ```bash
-COMET_ENV="${COMET_ENV:-$(find . "$HOME"/.*/skills "$HOME/.config" "$HOME/.gemini" -path '*/comet/scripts/comet-env.sh' -type f -print -quit 2>/dev/null)}"
+COMET_ENV="${COMET_ENV:-$(find . "$HOME"/.*/skills "$HOME/.config" "$HOME/.gemini" -path '*/comet/scripts/comet-env.js' -type f -print -quit 2>/dev/null)}"
 if [ -z "$COMET_ENV" ]; then
-  echo "ERROR: comet-env.sh not found. Ensure the comet skill is installed." >&2
+  echo "ERROR: comet-env.js not found. Ensure the comet skill is installed." >&2
   return 1
 fi
-. "$COMET_ENV"
+COMET_ENV_JSON="$(node "$COMET_ENV")"
+COMET_STATE="$(printf '%s' "$COMET_ENV_JSON" | node -e "let s='';process.stdin.on('data',d=>s+=d).on('end',()=>console.log(JSON.parse(s).COMET_STATE))")"
+COMET_GUARD="$(printf '%s' "$COMET_ENV_JSON" | node -e "let s='';process.stdin.on('data',d=>s+=d).on('end',()=>console.log(JSON.parse(s).COMET_GUARD))")"
+COMET_HANDOFF="$(printf '%s' "$COMET_ENV_JSON" | node -e "let s='';process.stdin.on('data',d=>s+=d).on('end',()=>console.log(JSON.parse(s).COMET_HANDOFF))")"
+COMET_ARCHIVE="$(printf '%s' "$COMET_ENV_JSON" | node -e "let s='';process.stdin.on('data',d=>s+=d).on('end',()=>console.log(JSON.parse(s).COMET_ARCHIVE))")"
 
 # 脚本定位失败时停止流程
 if [ -z "$COMET_GUARD" ] || [ -z "$COMET_STATE" ] || [ -z "$COMET_HANDOFF" ] || [ -z "$COMET_ARCHIVE" ]; then
   echo "ERROR: Comet scripts not found. Ensure the comet skill is installed." >&2
-  echo "Expected path pattern: */comet/scripts/comet-*.sh under project or platform skill directories" >&2
+  echo "Expected path pattern: */comet/scripts/comet-*.js under project or platform skill directories" >&2
   return 1
 fi
 ```
@@ -251,24 +255,24 @@ fi
 **自动状态更新**：guard 支持 `--apply` 参数，验证通过后自动更新 `.comet.yaml` 状态字段：
 
 ```bash
-"$COMET_BASH" "$COMET_GUARD" <change-name> <phase> --apply
+node "$COMET_GUARD" <change-name> <phase> --apply
 ```
 
 `--apply` 内部委托给 `comet-state transition`。需要直接表达状态事件时使用：
 
 ```bash
-"$COMET_BASH" "$COMET_STATE" transition <change-name> open-complete
-"$COMET_BASH" "$COMET_STATE" transition <change-name> design-complete
-"$COMET_BASH" "$COMET_STATE" transition <change-name> build-complete
-"$COMET_BASH" "$COMET_STATE" transition <change-name> verify-pass
-"$COMET_BASH" "$COMET_STATE" transition <change-name> verify-fail
-"$COMET_BASH" "$COMET_STATE" transition <archive-name> archived
+node "$COMET_STATE" transition <change-name> open-complete
+node "$COMET_STATE" transition <change-name> design-complete
+node "$COMET_STATE" transition <change-name> build-complete
+node "$COMET_STATE" transition <change-name> verify-pass
+node "$COMET_STATE" transition <change-name> verify-fail
+node "$COMET_STATE" transition <archive-name> archived
 ```
 
 **归档脚本**：一键完成归档全部步骤：
 
 ```bash
-"$COMET_BASH" "$COMET_ARCHIVE" <change-name>
+node "$COMET_ARCHIVE" <change-name>
 ```
 
 加载 comet 后，agent 应执行以上变量赋值一次，后续全程复用 `$COMET_GUARD`、`$COMET_STATE`、`$COMET_HANDOFF`、`$COMET_ARCHIVE`。
@@ -299,7 +303,7 @@ docs/superpowers/                      # Superpowers — HOW
 
 1. **brainstorming 不可跳过** — 每次变更必须经过深度设计（hotfix 和 tweak 除外）
 2. **delta spec 是活文档** — 阶段 3 期间可自由修改，归档时同步
-3. **交接包由脚本生成** — OpenSpec → Superpowers 的上下文必须通过 `comet-handoff.sh` 生成 compact 可追溯摘录（必要时 `--full`），并由 guard 校验 source/hash/mode
+3. **交接包由脚本生成** — OpenSpec → Superpowers 的上下文必须通过 `comet-handoff.js` 生成 compact 可追溯摘录（必要时 `--full`），并由 guard 校验 source/hash/mode
 4. **保持 tasks.md 同步** — 完成一个勾一个
 5. **频繁提交** — 每个任务一次提交，message 体现设计意图
 6. **先验证再归档** — `/comet-verify` 通过后才执行 `/comet-archive`
diff --git a/assets/skills/comet-archive/SKILL.md b/assets/skills/comet-archive/SKILL.md
index eb96e2b6..45f26560 100644
--- a/assets/skills/comet-archive/SKILL.md
+++ b/assets/skills/comet-archive/SKILL.md
@@ -18,13 +18,17 @@ description: "Comet Phase 5: Archive. Invoke with /comet-archive. Sync delta spe
 Execute entry verification:
 
 ```bash
-COMET_ENV="${COMET_ENV:-$(find . "$HOME"/.*/skills "$HOME/.config" "$HOME/.gemini" -path '*/comet/scripts/comet-env.sh' -type f -print -quit 2>/dev/null)}"
+COMET_ENV="${COMET_ENV:-$(find . "$HOME"/.*/skills "$HOME/.config" "$HOME/.gemini" -path '*/comet/scripts/comet-env.js' -type f -print -quit 2>/dev/null)}"
 if [ -z "$COMET_ENV" ]; then
-  echo "ERROR: comet-env.sh not found. Ensure the comet skill is installed." >&2
+  echo "ERROR: comet-env.js not found. Ensure the comet skill is installed." >&2
   return 1
 fi
-. "$COMET_ENV"
-"$COMET_BASH" "$COMET_STATE" check <name> archive
+COMET_ENV_JSON="$(node "$COMET_ENV")"
+COMET_STATE="$(printf '%s' "$COMET_ENV_JSON" | node -e "let s='';process.stdin.on('data',d=>s+=d).on('end',()=>console.log(JSON.parse(s).COMET_STATE))")"
+COMET_GUARD="$(printf '%s' "$COMET_ENV_JSON" | node -e "let s='';process.stdin.on('data',d=>s+=d).on('end',()=>console.log(JSON.parse(s).COMET_GUARD))")"
+COMET_HANDOFF="$(printf '%s' "$COMET_ENV_JSON" | node -e "let s='';process.stdin.on('data',d=>s+=d).on('end',()=>console.log(JSON.parse(s).COMET_HANDOFF))")"
+COMET_ARCHIVE="$(printf '%s' "$COMET_ENV_JSON" | node -e "let s='';process.stdin.on('data',d=>s+=d).on('end',()=>console.log(JSON.parse(s).COMET_ARCHIVE))")"
+node "$COMET_STATE" check <name> archive
 ```
 
 Proceed to Step 1 after verification passes. The script outputs specific failure reasons when verification fails.
@@ -38,7 +42,7 @@ Archive summaries and lifecycle closure notes must use the language of the user
 Run the archive script to automatically complete all steps:
 
 ```bash
-"$COMET_BASH" "$COMET_ARCHIVE" "<change-name>"
+node "$COMET_ARCHIVE" "<change-name>"
 ```
 
 The script automatically executes:
@@ -70,7 +74,7 @@ brainstorming → delta spec → implementation → verification → main spec o
 - Archive directory `openspec/changes/archive/YYYY-MM-DD-<change-name>/` exists
 - Archived `.comet.yaml` contains `archived: true`
 
-The archive script moves `openspec/changes/<name>/` to `openspec/changes/archive/YYYY-MM-DD-<name>/`. After successful archive, **do not run** `"$COMET_BASH" "$COMET_GUARD" <change-name> archive` against the old active change name; the active directory no longer exists. Archive completeness is determined by script exit code and archived directory state.
+The archive script moves `openspec/changes/<name>/` to `openspec/changes/archive/YYYY-MM-DD-<name>/`. After successful archive, **do not run** `node "$COMET_GUARD" <change-name> archive` against the old active change name; the active directory no longer exists. Archive completeness is determined by script exit code and archived directory state.
 
 ## Complete
 
diff --git a/assets/skills/comet-build/SKILL.md b/assets/skills/comet-build/SKILL.md
index 81160708..3e7c2418 100644
--- a/assets/skills/comet-build/SKILL.md
+++ b/assets/skills/comet-build/SKILL.md
@@ -17,13 +17,17 @@ description: "Comet Phase 3: Plan and Build. Invoke with /comet-build. Create pl
 Execute entry verification:
 
 ```bash
-COMET_ENV="${COMET_ENV:-$(find . "$HOME"/.*/skills "$HOME/.config" "$HOME/.gemini" -path '*/comet/scripts/comet-env.sh' -type f -print -quit 2>/dev/null)}"
+COMET_ENV="${COMET_ENV:-$(find . "$HOME"/.*/skills "$HOME/.config" "$HOME/.gemini" -path '*/comet/scripts/comet-env.js' -type f -print -quit 2>/dev/null)}"
 if [ -z "$COMET_ENV" ]; then
-  echo "ERROR: comet-env.sh not found. Ensure the comet skill is installed." >&2
+  echo "ERROR: comet-env.js not found. Ensure the comet skill is installed." >&2
   return 1
 fi
-. "$COMET_ENV"
-"$COMET_BASH" "$COMET_STATE" check <name> build
+COMET_ENV_JSON="$(node "$COMET_ENV")"
+COMET_STATE="$(printf '%s' "$COMET_ENV_JSON" | node -e "let s='';process.stdin.on('data',d=>s+=d).on('end',()=>console.log(JSON.parse(s).COMET_STATE))")"
+COMET_GUARD="$(printf '%s' "$COMET_ENV_JSON" | node -e "let s='';process.stdin.on('data',d=>s+=d).on('end',()=>console.log(JSON.parse(s).COMET_GUARD))")"
+COMET_HANDOFF="$(printf '%s' "$COMET_ENV_JSON" | node -e "let s='';process.stdin.on('data',d=>s+=d).on('end',()=>console.log(JSON.parse(s).COMET_HANDOFF))")"
+COMET_ARCHIVE="$(printf '%s' "$COMET_ENV_JSON" | node -e "let s='';process.stdin.on('data',d=>s+=d).on('end',()=>console.log(JSON.parse(s).COMET_ARCHIVE))")"
+node "$COMET_STATE" check <name> build
 ```
 
 Proceed to Step 1 after verification passes. The script outputs specific failure reasons when verification fails.
@@ -64,7 +68,7 @@ git rev-parse HEAD
 Record plan path:
 
 ```bash
-"$COMET_BASH" "$COMET_STATE" set <name> plan docs/superpowers/plans/YYYY-MM-DD-feature.md
+node "$COMET_STATE" set <name> plan docs/superpowers/plans/YYYY-MM-DD-feature.md
 ```
 
 No manual phase update needed — guard auto-transitions when exit conditions are met.
@@ -81,13 +85,13 @@ This is a user decision point. **Must use the AskUserQuestion tool to pause and
 When the user chooses to continue:
 
 ```bash
-"$COMET_BASH" "$COMET_STATE" set <name> build_pause null
+node "$COMET_STATE" set <name> build_pause null
 ```
 
 When the user chooses to pause:
 
 ```bash
-"$COMET_BASH" "$COMET_STATE" set <name> build_pause plan-ready
+node "$COMET_STATE" set <name> build_pause plan-ready
 ```
 
 After setting `build_pause: plan-ready`, stop the current invocation. Do not choose `isolation` or `build_mode`, and do not load an execution skill.
@@ -97,7 +101,7 @@ After setting `build_pause: plan-ready`, stop the current invocation. Do not cho
 If resuming with `build_pause: plan-ready` and the `plan` file exists, do not rerun `writing-plans`. First tell the user the workflow is stopped at the plan-ready pause point; after the user confirms continuing, set:
 
 ```bash
-"$COMET_BASH" "$COMET_STATE" set <name> build_pause null
+node "$COMET_STATE" set <name> build_pause null
 ```
 
 Then continue this step to choose workspace isolation and execution method.
@@ -132,8 +136,8 @@ This is a user decision point. **Must use the AskUserQuestion tool to pause and
 After user selection, update `isolation` and `build_mode` fields:
 
 ```bash
-"$COMET_BASH" "$COMET_STATE" set <name> isolation <branch|worktree>
-"$COMET_BASH" "$COMET_STATE" set <name> build_mode <subagent-driven-development|executing-plans|direct>
+node "$COMET_STATE" set <name> isolation <branch|worktree>
+node "$COMET_STATE" set <name> build_mode <subagent-driven-development|executing-plans|direct>
 ```
 
 `isolation` is a script-enforced hard constraint. Full workflow init may temporarily leave it as `null`, but only before this step. If it remains `null`, both the `build → verify` guard and `comet-state transition build-complete` will fail.
@@ -141,8 +145,8 @@ After user selection, update `isolation` and `build_mode` fields:
 `build_mode` defaults to `direct` only for hotfix/tweak presets. Full workflow must not default to `direct`. Use it only when the user explicitly asks to bypass the plan execution skills and you record an explicit override:
 
 ```bash
-"$COMET_BASH" "$COMET_STATE" set <name> direct_override true
-"$COMET_BASH" "$COMET_STATE" set <name> build_mode direct
+node "$COMET_STATE" set <name> direct_override true
+node "$COMET_STATE" set <name> build_mode direct
 ```
 
 Without `direct_override: true`, `build_mode=direct` in full workflow is blocked by both guard and state transition.
@@ -196,7 +200,7 @@ When creating an independent change, must invoke `/comet-open`, not `/opsx:new`
 Build is the longest phase and may span many tasks. To support resume after context compaction:
 
 - **After each task**: immediately check off tasks.md and commit code so `.comet.yaml` and file state are durable
-- **After context compaction**: first run `"$COMET_BASH" "$COMET_STATE" check <change-name> build --recover` — the script outputs structured recovery context (isolation/build_mode status, plan path, task progress, recovery action). Follow the Recovery action to determine next step.
+- **After context compaction**: first run `node "$COMET_STATE" check <change-name> build --recover` — the script outputs structured recovery context (isolation/build_mode status, plan path, task progress, recovery action). Follow the Recovery action to determine next step.
 - **User manual-change resume**: handle uncommitted changes through `comet/reference/dirty-worktree.md`. That protocol defines checks, attribution, and prohibitions. Build-specific handling:
   1. After attribution, if the diff implies plan or spec changes, handle it through Step 4 "Spec Incremental Updates"
 - **Long task split**: if a single task exceeds 200 lines of code changes, consider splitting it into multiple subtasks and commits
@@ -208,7 +212,7 @@ Build is the longest phase and may span many tasks. To support resume after cont
 - Project-specific build/tests explicitly run and pass; do not rely only on guard auto-detection
 - `isolation` has been written as `branch` or `worktree`
 - `build_mode` has been written as `subagent-driven-development`, `executing-plans`, or `direct` with explicit override
-- **Phase guard**: Run `"$COMET_BASH" "$COMET_GUARD" <change-name> build --apply`; after all PASS, state advances to `phase: verify`
+- **Phase guard**: Run `node "$COMET_GUARD" <change-name> build --apply`; after all PASS, state advances to `phase: verify`
 
 Guard reads project command configuration first:
 
@@ -223,7 +227,7 @@ Only when no command is configured does guard fall back to `npm run build`, Mave
 Before exit, run guard to auto-transition:
 
 ```bash
-"$COMET_BASH" "$COMET_GUARD" <change-name> build --apply
+node "$COMET_GUARD" <change-name> build --apply
 ```
 
 State file is automatically updated to `phase: verify`, `verify_result: pending`.
diff --git a/assets/skills/comet-design/SKILL.md b/assets/skills/comet-design/SKILL.md
index ff802f4a..5e2c1678 100644
--- a/assets/skills/comet-design/SKILL.md
+++ b/assets/skills/comet-design/SKILL.md
@@ -17,13 +17,17 @@ description: "Comet Phase 2: Deep Design. Invoke with /comet-design. Produce Des
 Execute entry verification:
 
 ```bash
-COMET_ENV="${COMET_ENV:-$(find . "$HOME"/.*/skills "$HOME/.config" "$HOME/.gemini" -path '*/comet/scripts/comet-env.sh' -type f -print -quit 2>/dev/null)}"
+COMET_ENV="${COMET_ENV:-$(find . "$HOME"/.*/skills "$HOME/.config" "$HOME/.gemini" -path '*/comet/scripts/comet-env.js' -type f -print -quit 2>/dev/null)}"
 if [ -z "$COMET_ENV" ]; then
-  echo "ERROR: comet-env.sh not found. Ensure the comet skill is installed." >&2
+  echo "ERROR: comet-env.js not found. Ensure the comet skill is installed." >&2
   return 1
 fi
-. "$COMET_ENV"
-"$COMET_BASH" "$COMET_STATE" check <name> design
+COMET_ENV_JSON="$(node "$COMET_ENV")"
+COMET_STATE="$(printf '%s' "$COMET_ENV_JSON" | node -e "let s='';process.stdin.on('data',d=>s+=d).on('end',()=>console.log(JSON.parse(s).COMET_STATE))")"
+COMET_GUARD="$(printf '%s' "$COMET_ENV_JSON" | node -e "let s='';process.stdin.on('data',d=>s+=d).on('end',()=>console.log(JSON.parse(s).COMET_GUARD))")"
+COMET_HANDOFF="$(printf '%s' "$COMET_ENV_JSON" | node -e "let s='';process.stdin.on('data',d=>s+=d).on('end',()=>console.log(JSON.parse(s).COMET_HANDOFF))")"
+COMET_ARCHIVE="$(printf '%s' "$COMET_ENV_JSON" | node -e "let s='';process.stdin.on('data',d=>s+=d).on('end',()=>console.log(JSON.parse(s).COMET_ARCHIVE))")"
+node "$COMET_STATE" check <name> design
 ```
 
 Proceed to Step 1 after verification passes. The script outputs specific failure reasons when verification fails.
@@ -35,7 +39,7 @@ Proceed to Step 1 after verification passes. The script outputs specific failure
 **Must be generated by script. Agent writing summaries on the fly is not allowed.**
 
 ```bash
-"$COMET_BASH" "$COMET_HANDOFF" <change-name> design --write
+node "$COMET_HANDOFF" <change-name> design --write
 ```
 
 The script generates and records:
@@ -60,7 +64,7 @@ The default handoff package is a **compact traceable excerpt**, not an agent sum
 If full context is genuinely needed, explicitly run:
 
 ```bash
-"$COMET_BASH" "$COMET_HANDOFF" <change-name> design --write --full
+node "$COMET_HANDOFF" <change-name> design --write --full
 ```
 
 Handoff package sources come from OpenSpec open phase artifacts:
@@ -122,13 +126,13 @@ First record the design_doc path. If Step 1c wrote back delta spec (added or mod
 
 ```bash
 # Record design_doc path
-"$COMET_BASH" "$COMET_STATE" set <name> design_doc docs/superpowers/specs/YYYY-MM-DD-topic-design.md
+node "$COMET_STATE" set <name> design_doc docs/superpowers/specs/YYYY-MM-DD-topic-design.md
 
 # If delta spec changes exist, regenerate handoff (update hash)
-"$COMET_BASH" "$COMET_HANDOFF" <change-name> design --write
+node "$COMET_HANDOFF" <change-name> design --write
 
 # Auto-transition to next phase
-"$COMET_BASH" "$COMET_GUARD" <change-name> design --apply
+node "$COMET_GUARD" <change-name> design --apply
 ```
 
 If there are no delta spec changes, skip the handoff regeneration step. The state file updates automatically; no manual editing of other fields needed.
@@ -142,12 +146,12 @@ If there are no delta spec changes, skip the handoff regeneration step. The stat
 - `design-context.md` must be script-generated and contain source path, mode, sha256 traceability markers (enforced by guard)
 - If new capabilities or supplementary acceptance scenarios exist, OpenSpec delta spec has been created/updated
 - `design_doc` written to `.comet.yaml`
-- **Phase guard**: Run `"$COMET_BASH" "$COMET_GUARD" <change-name> design --apply`; after all PASS, auto-transitions to `phase: build`
+- **Phase guard**: Run `node "$COMET_GUARD" <change-name> design --apply`; after all PASS, auto-transitions to `phase: build`
 
 Must use `--apply` before exit:
 
 ```bash
-"$COMET_BASH" "$COMET_GUARD" <change-name> design --apply
+node "$COMET_GUARD" <change-name> design --apply
 ```
 
 ## Context Compaction Recovery
@@ -155,7 +159,7 @@ Must use `--apply` before exit:
 The design phase may trigger context compaction during brainstorming. To recover, first run:
 
 ```bash
-"$COMET_BASH" "$COMET_STATE" check <change-name> design --recover
+node "$COMET_STATE" check <change-name> design --recover
 ```
 
 The script outputs structured recovery context (phase, completed fields, pending fields, recovery action). Follow the Recovery action to determine next step.
diff --git a/assets/skills/comet-hotfix/SKILL.md b/assets/skills/comet-hotfix/SKILL.md
index 9bc4ea9e..50d0c814 100644
--- a/assets/skills/comet-hotfix/SKILL.md
+++ b/assets/skills/comet-hotfix/SKILL.md
@@ -23,12 +23,16 @@ Execution chain: open → build → root cause check → verify → archive. Hot
 Locate Comet scripts before starting:
 
 ```bash
-COMET_ENV="${COMET_ENV:-$(find . "$HOME"/.*/skills "$HOME/.config" "$HOME/.gemini" -path '*/comet/scripts/comet-env.sh' -type f -print -quit 2>/dev/null)}"
+COMET_ENV="${COMET_ENV:-$(find . "$HOME"/.*/skills "$HOME/.config" "$HOME/.gemini" -path '*/comet/scripts/comet-env.js' -type f -print -quit 2>/dev/null)}"
 if [ -z "$COMET_ENV" ]; then
-  echo "ERROR: comet-env.sh not found. Ensure the comet skill is installed." >&2
+  echo "ERROR: comet-env.js not found. Ensure the comet skill is installed." >&2
   return 1
 fi
-. "$COMET_ENV"
+COMET_ENV_JSON="$(node "$COMET_ENV")"
+COMET_STATE="$(printf '%s' "$COMET_ENV_JSON" | node -e "let s='';process.stdin.on('data',d=>s+=d).on('end',()=>console.log(JSON.parse(s).COMET_STATE))")"
+COMET_GUARD="$(printf '%s' "$COMET_ENV_JSON" | node -e "let s='';process.stdin.on('data',d=>s+=d).on('end',()=>console.log(JSON.parse(s).COMET_GUARD))")"
+COMET_HANDOFF="$(printf '%s' "$COMET_ENV_JSON" | node -e "let s='';process.stdin.on('data',d=>s+=d).on('end',()=>console.log(JSON.parse(s).COMET_HANDOFF))")"
+COMET_ARCHIVE="$(printf '%s' "$COMET_ENV_JSON" | node -e "let s='';process.stdin.on('data',d=>s+=d).on('end',()=>console.log(JSON.parse(s).COMET_ARCHIVE))")"
 ```
 
 ### 1. Quick Open (preset open)
@@ -54,19 +58,19 @@ Streamlined OpenSpec artifacts must use the language of the user request that tr
 Initialize Comet state file:
 
 ```bash
-"$COMET_BASH" "$COMET_STATE" init <name> hotfix
+node "$COMET_STATE" init <name> hotfix
 ```
 
 Verify initialized state:
 
 ```bash
-"$COMET_BASH" "$COMET_STATE" check <name> open
+node "$COMET_STATE" check <name> open
 ```
 
 Run phase guard to transition open → build:
 
 ```bash
-"$COMET_BASH" "$COMET_GUARD" <change-name> open --apply
+node "$COMET_GUARD" <change-name> open --apply
 ```
 
 ### 2. Direct Build (preset build)
@@ -105,7 +109,7 @@ Before continuing or starting changes, handle uncommitted changes through `comet
 After root cause is confirmed eliminated, run phase guard to transition build → verify:
 
 ```bash
-"$COMET_BASH" "$COMET_GUARD" <change-name> build --apply
+node "$COMET_GUARD" <change-name> build --apply
 ```
 
 State automatically updates to `phase: verify`, `verify_result: pending`, then enter verification.
@@ -162,7 +166,7 @@ When upgrade conditions are met, **must use the AskUserQuestion tool to pause an
 After user confirms upgrade, **must first update the workflow field** before entering full flow:
 
 ```bash
-"$COMET_BASH" "$COMET_STATE" set <name> workflow full
+node "$COMET_STATE" set <name> workflow full
 ```
 
 Then on current change basis, supplement Design Doc: **Immediately use the Skill tool to load the `comet-design` skill**, proceed normally with full workflow. If user does not confirm upgrade, stop hotfix and report that current change has exceeded hotfix scope.
@@ -174,4 +178,4 @@ Then on current change basis, supplement Design Doc: **Immediately use the Skill
 - Bug fixed, tests pass
 - Change archived
 - If spec changes, synced to main spec
-- **Phase guard**: Before build → verify run `"$COMET_BASH" "$COMET_GUARD" <change-name> build --apply`; before verify → archive follow `/comet-verify` and run `"$COMET_BASH" "$COMET_GUARD" <change-name> verify --apply`
+- **Phase guard**: Before build → verify run `node "$COMET_GUARD" <change-name> build --apply`; before verify → archive follow `/comet-verify` and run `node "$COMET_GUARD" <change-name> verify --apply`
diff --git a/assets/skills/comet-open/SKILL.md b/assets/skills/comet-open/SKILL.md
index e182bbcb..e34c95e7 100644
--- a/assets/skills/comet-open/SKILL.md
+++ b/assets/skills/comet-open/SKILL.md
@@ -53,19 +53,23 @@ openspec/changes/<name>/
 Create `.comet.yaml` state file:
 
 ```bash
-COMET_ENV="${COMET_ENV:-$(find . "$HOME"/.*/skills "$HOME/.config" "$HOME/.gemini" -path '*/comet/scripts/comet-env.sh' -type f -print -quit 2>/dev/null)}"
+COMET_ENV="${COMET_ENV:-$(find . "$HOME"/.*/skills "$HOME/.config" "$HOME/.gemini" -path '*/comet/scripts/comet-env.js' -type f -print -quit 2>/dev/null)}"
 if [ -z "$COMET_ENV" ]; then
-  echo "ERROR: comet-env.sh not found. Ensure the comet skill is installed." >&2
+  echo "ERROR: comet-env.js not found. Ensure the comet skill is installed." >&2
   return 1
 fi
-. "$COMET_ENV"
+COMET_ENV_JSON="$(node "$COMET_ENV")"
+COMET_STATE="$(printf '%s' "$COMET_ENV_JSON" | node -e "let s='';process.stdin.on('data',d=>s+=d).on('end',()=>console.log(JSON.parse(s).COMET_STATE))")"
+COMET_GUARD="$(printf '%s' "$COMET_ENV_JSON" | node -e "let s='';process.stdin.on('data',d=>s+=d).on('end',()=>console.log(JSON.parse(s).COMET_GUARD))")"
+COMET_HANDOFF="$(printf '%s' "$COMET_ENV_JSON" | node -e "let s='';process.stdin.on('data',d=>s+=d).on('end',()=>console.log(JSON.parse(s).COMET_HANDOFF))")"
+COMET_ARCHIVE="$(printf '%s' "$COMET_ENV_JSON" | node -e "let s='';process.stdin.on('data',d=>s+=d).on('end',()=>console.log(JSON.parse(s).COMET_ARCHIVE))")"
 
 if [ -z "$COMET_STATE" ] || [ -z "$COMET_GUARD" ]; then
   echo "ERROR: Comet scripts not found. Ensure the comet skill is installed." >&2
   return 1
 fi
 
-"$COMET_BASH" "$COMET_STATE" init <name> full
+node "$COMET_STATE" init <name> full
 ```
 
 ### 3. Entry State Verification
@@ -73,7 +77,7 @@ fi
 Verify state machine has been correctly initialized:
 
 ```bash
-"$COMET_BASH" "$COMET_STATE" check <name> open
+node "$COMET_STATE" check <name> open
 ```
 
 Proceed to Step 4 after verification passes. The script outputs specific failure reasons when verification fails.
@@ -110,12 +114,12 @@ After user selects "Confirm", proceed to exit conditions. When user selects "Nee
 
 - proposal.md, design.md, tasks.md all created with complete content
 - **User has confirmed** proposal, design, tasks content meets expectations
-- **Phase guard**: Run `"$COMET_BASH" "$COMET_GUARD" <change-name> open --apply`; after all PASS, auto-transitions to next phase
+- **Phase guard**: Run `node "$COMET_GUARD" <change-name> open --apply`; after all PASS, auto-transitions to next phase
 
 Must use `--apply` before exit, otherwise `.comet.yaml` remains at `phase: open` and the next phase entry check will fail.
 
 ```bash
-"$COMET_BASH" "$COMET_GUARD" <change-name> open --apply
+node "$COMET_GUARD" <change-name> open --apply
 ```
 
 Full workflow auto-transitions to `phase: design`; hotfix/tweak presets auto-transition to `phase: build`.
diff --git a/assets/skills/comet-tweak/SKILL.md b/assets/skills/comet-tweak/SKILL.md
index 31325925..be25daba 100644
--- a/assets/skills/comet-tweak/SKILL.md
+++ b/assets/skills/comet-tweak/SKILL.md
@@ -26,12 +26,16 @@ Execution chain: open → lightweight build → light verify → archive. Tweak
 Locate Comet scripts before starting:
 
 ```bash
-COMET_ENV="${COMET_ENV:-$(find . "$HOME"/.*/skills "$HOME/.config" "$HOME/.gemini" -path '*/comet/scripts/comet-env.sh' -type f -print -quit 2>/dev/null)}"
+COMET_ENV="${COMET_ENV:-$(find . "$HOME"/.*/skills "$HOME/.config" "$HOME/.gemini" -path '*/comet/scripts/comet-env.js' -type f -print -quit 2>/dev/null)}"
 if [ -z "$COMET_ENV" ]; then
-  echo "ERROR: comet-env.sh not found. Ensure the comet skill is installed." >&2
+  echo "ERROR: comet-env.js not found. Ensure the comet skill is installed." >&2
   return 1
 fi
-. "$COMET_ENV"
+COMET_ENV_JSON="$(node "$COMET_ENV")"
+COMET_STATE="$(printf '%s' "$COMET_ENV_JSON" | node -e "let s='';process.stdin.on('data',d=>s+=d).on('end',()=>console.log(JSON.parse(s).COMET_STATE))")"
+COMET_GUARD="$(printf '%s' "$COMET_ENV_JSON" | node -e "let s='';process.stdin.on('data',d=>s+=d).on('end',()=>console.log(JSON.parse(s).COMET_GUARD))")"
+COMET_HANDOFF="$(printf '%s' "$COMET_ENV_JSON" | node -e "let s='';process.stdin.on('data',d=>s+=d).on('end',()=>console.log(JSON.parse(s).COMET_HANDOFF))")"
+COMET_ARCHIVE="$(printf '%s' "$COMET_ENV_JSON" | node -e "let s='';process.stdin.on('data',d=>s+=d).on('end',()=>console.log(JSON.parse(s).COMET_ARCHIVE))")"
 ```
 
 ### 1. Quick Open (preset open)
@@ -57,19 +61,19 @@ Streamlined OpenSpec artifacts must use the language of the user request that tr
 Initialize Comet state file:
 
 ```bash
-"$COMET_BASH" "$COMET_STATE" init <name> tweak
+node "$COMET_STATE" init <name> tweak
 ```
 
 Verify initialized state:
 
 ```bash
-"$COMET_BASH" "$COMET_STATE" check <name> open
+node "$COMET_STATE" check <name> open
 ```
 
 Run phase guard to transition open → build:
 
 ```bash
-"$COMET_BASH" "$COMET_GUARD" <change-name> open --apply
+node "$COMET_GUARD" <change-name> open --apply
 ```
 
 ### 2. Lightweight Build (preset build)
@@ -91,7 +95,7 @@ Before continuing or starting changes, handle uncommitted changes through `comet
 4. Run phase guard to transition build → verify:
 
 ```bash
-"$COMET_BASH" "$COMET_GUARD" <change-name> build --apply
+node "$COMET_GUARD" <change-name> build --apply
 ```
 
 State automatically updates to `phase: verify`, `verify_result: pending`, then enter verification.
@@ -147,7 +151,7 @@ When upgrade conditions are met, **must use the AskUserQuestion tool to pause an
 After user confirms upgrade, **must first update the workflow field** before entering full flow:
 
 ```bash
-"$COMET_BASH" "$COMET_STATE" set <name> workflow full
+node "$COMET_STATE" set <name> workflow full
 ```
 
 Then on current change basis, supplement Design Doc: **Immediately use the Skill tool to load the `comet-design` skill**, proceed normally with full workflow. If user does not confirm upgrade, stop tweak and report that current change has exceeded tweak scope.
@@ -159,4 +163,4 @@ Then on current change basis, supplement Design Doc: **Immediately use the Skill
 - Small change completed, tests pass
 - Change archived
 - No new capability, architecture adjustments or interface changes
-- **Phase guard**: Before build → verify run `"$COMET_BASH" "$COMET_GUARD" <change-name> build --apply`; before verify → archive follow `/comet-verify` and run `"$COMET_BASH" "$COMET_GUARD" <change-name> verify --apply`
+- **Phase guard**: Before build → verify run `node "$COMET_GUARD" <change-name> build --apply`; before verify → archive follow `/comet-verify` and run `node "$COMET_GUARD" <change-name> verify --apply`
diff --git a/assets/skills/comet-verify/SKILL.md b/assets/skills/comet-verify/SKILL.md
index 8f38eb00..1260528e 100644
--- a/assets/skills/comet-verify/SKILL.md
+++ b/assets/skills/comet-verify/SKILL.md
@@ -17,13 +17,17 @@ description: "Comet Phase 4: Verify and Close. Invoke with /comet-verify. Verify
 Execute entry verification:
 
 ```bash
-COMET_ENV="${COMET_ENV:-$(find . "$HOME"/.*/skills "$HOME/.config" "$HOME/.gemini" -path '*/comet/scripts/comet-env.sh' -type f -print -quit 2>/dev/null)}"
+COMET_ENV="${COMET_ENV:-$(find . "$HOME"/.*/skills "$HOME/.config" "$HOME/.gemini" -path '*/comet/scripts/comet-env.js' -type f -print -quit 2>/dev/null)}"
 if [ -z "$COMET_ENV" ]; then
-  echo "ERROR: comet-env.sh not found. Ensure the comet skill is installed." >&2
+  echo "ERROR: comet-env.js not found. Ensure the comet skill is installed." >&2
   return 1
 fi
-. "$COMET_ENV"
-"$COMET_BASH" "$COMET_STATE" check <change-name> verify
+COMET_ENV_JSON="$(node "$COMET_ENV")"
+COMET_STATE="$(printf '%s' "$COMET_ENV_JSON" | node -e "let s='';process.stdin.on('data',d=>s+=d).on('end',()=>console.log(JSON.parse(s).COMET_STATE))")"
+COMET_GUARD="$(printf '%s' "$COMET_ENV_JSON" | node -e "let s='';process.stdin.on('data',d=>s+=d).on('end',()=>console.log(JSON.parse(s).COMET_GUARD))")"
+COMET_HANDOFF="$(printf '%s' "$COMET_ENV_JSON" | node -e "let s='';process.stdin.on('data',d=>s+=d).on('end',()=>console.log(JSON.parse(s).COMET_HANDOFF))")"
+COMET_ARCHIVE="$(printf '%s' "$COMET_ENV_JSON" | node -e "let s='';process.stdin.on('data',d=>s+=d).on('end',()=>console.log(JSON.parse(s).COMET_ARCHIVE))")"
+node "$COMET_STATE" check <change-name> verify
 ```
 
 Proceed to Step 1 after verification passes. The script outputs specific failure reasons when verification fails.
@@ -39,7 +43,7 @@ Verification reports and branch-handling notes must use the language of the user
 Execute scale assessment:
 
 ```bash
-"$COMET_BASH" "$COMET_STATE" scale <change-name>
+node "$COMET_STATE" scale <change-name>
 ```
 
 The script automatically counts tasks, delta spec count, changed file count, determines light or full verification mode, and sets the verify_mode field.
@@ -54,13 +58,13 @@ Only after user chooses fix, allow rollback to build phase:
 
 ```bash
 # Execute only after user confirms fix
-"$COMET_BASH" "$COMET_STATE" transition <change-name> verify-fail
+node "$COMET_STATE" transition <change-name> verify-fail
 ```
 
 Note: If every task in build phase was committed, the script's file count based on working tree diff may underestimate change scale. In this case, must read plan file header `base-ref` and verify with commit range:
 
 ```bash
-PLAN=$("$COMET_BASH" "$COMET_STATE" get <change-name> plan)
+PLAN=$(node "$COMET_STATE" get <change-name> plan)
 BASE_REF=$(grep '^base-ref:' "$PLAN" 2>/dev/null | head -1 | sed 's/^base-ref: *//')
 git diff --stat "$BASE_REF"...HEAD
 ```
@@ -68,12 +72,12 @@ git diff --stat "$BASE_REF"...HEAD
 If commit range shows changes exceed lightweight threshold (> 4 files, cross-module coordination, or delta spec spans more than 1 capability), manually set to full verification:
 
 ```bash
-"$COMET_BASH" "$COMET_STATE" set <change-name> verify_mode full
+node "$COMET_STATE" set <change-name> verify_mode full
 ```
 
 ### 1b. Verification Failure Decision (Blocking Point)
 
-When verification does not pass, **must use the AskUserQuestion tool to pause and wait for the user to decide fix or accept deviation**. Must not automatically run `"$COMET_BASH" "$COMET_STATE" transition <change-name> verify-fail`, nor automatically invoke `/comet-build`. Must not just output a text prompt and then continue executing.
+When verification does not pass, **must use the AskUserQuestion tool to pause and wait for the user to decide fix or accept deviation**. Must not automatically run `node "$COMET_STATE" transition <change-name> verify-fail`, nor automatically invoke `/comet-build`. Must not just output a text prompt and then continue executing.
 
 When pausing, must list:
 - Failed items
@@ -83,7 +87,7 @@ When pausing, must list:
 **Uncertainty principle**: When severity is unclear, downgrade (SUGGESTION > WARNING > CRITICAL). Only use CRITICAL for build failures, test failures, and security issues; ambiguous or uncertain issues should be WARNING or SUGGESTION.
 
 After user selection, continue as follows:
-- **Fix all**: Run `"$COMET_BASH" "$COMET_STATE" transition <change-name> verify-fail`, then invoke `/comet-build` to fix
+- **Fix all**: Run `node "$COMET_STATE" transition <change-name> verify-fail`, then invoke `/comet-build` to fix
 - **Handle item by item**: CRITICAL failures must be fixed; non-CRITICAL failures may choose to accept deviation, but must record acceptance reason and impact scope in verification report. If any CRITICAL failure exists, skipping fix to accept all is not allowed
 
 ### 2a. Lightweight Verification (Small Changes)
@@ -102,7 +106,7 @@ When scale assessment result is "small", skip `openspec-verify-change` and direc
 
 ```bash
 # Execute only after user confirms fix
-"$COMET_BASH" "$COMET_STATE" transition <change-name> verify-fail
+node "$COMET_STATE" transition <change-name> verify-fail
 ```
 
 **Report format**: Brief table listing 5 check results + PASS/FAIL.
@@ -132,13 +136,13 @@ When verification does not pass: report missing items, enter Step 1b verificatio
 
 ```bash
 # Execute only after user confirms fix
-"$COMET_BASH" "$COMET_STATE" transition <change-name> verify-fail
+node "$COMET_STATE" transition <change-name> verify-fail
 ```
 
 **Spec Drift Handling** (user decision point):
 - If check item 6 finds contradictions (delta spec has content but design doc does not reflect it), **must use the AskUserQuestion tool as a single-select question to pause and wait for user to choose handling method**; must not select automatically. Options:
   - Option A: Append "Implementation Divergence" section to design doc recording deviation reason. Option A is a verify phase allowed artifact; after writing, must not re-trigger Step 1b dirty-worktree decision due to that design doc change
-  - Option B: After user selects B, run `"$COMET_BASH" "$COMET_STATE" transition <change-name> verify-fail`, then invoke `/comet-build`; `/comet-build`'s Spec Incremental Update rules will load the Superpowers `brainstorming` skill to update Design Doc + delta spec
+  - Option B: After user selects B, run `node "$COMET_STATE" transition <change-name> verify-fail`, then invoke `/comet-build`; `/comet-build`'s Spec Incremental Update rules will load the Superpowers `brainstorming` skill to update Design Doc + delta spec
   - Option C: Confirm deviation is acceptable, continue verification (design doc will be marked as `superseded-by-main-spec` during archiving)
 
 ### 3. Finishing (Superpowers)
@@ -168,8 +172,8 @@ mkdir -p docs/superpowers/reports
 # Write verification conclusions to report file, e.g.:
 # docs/superpowers/reports/YYYY-MM-DD-<change-name>-verify.md
 
-"$COMET_BASH" "$COMET_STATE" set <change-name> verification_report docs/superpowers/reports/YYYY-MM-DD-<change-name>-verify.md
-"$COMET_BASH" "$COMET_STATE" set <change-name> branch_status handled
+node "$COMET_STATE" set <change-name> verification_report docs/superpowers/reports/YYYY-MM-DD-<change-name>-verify.md
+node "$COMET_STATE" set <change-name> branch_status handled
 ```
 
 ## Exit Conditions
@@ -178,12 +182,12 @@ mkdir -p docs/superpowers/reports
 - Branch handled
 - `verification_report` in `.comet.yaml` points to an existing verification report file
 - `branch_status: handled` in `.comet.yaml`
-- **Phase guard**: Run `"$COMET_BASH" "$COMET_GUARD" <change-name> verify --apply`; after all PASS, auto-transitions to `phase: archive` through `comet-state transition verify-pass`
+- **Phase guard**: Run `node "$COMET_GUARD" <change-name> verify --apply`; after all PASS, auto-transitions to `phase: archive` through `comet-state transition verify-pass`
 
 After both verification and branch handling are complete, run guard for auto-transition:
 
 ```bash
-"$COMET_BASH" "$COMET_GUARD" <change-name> verify --apply
+node "$COMET_GUARD" <change-name> verify --apply
 ```
 
 State file auto-updates to `phase: archive`, `verify_result: pass`, `verified_at: YYYY-MM-DD`.
@@ -199,7 +203,7 @@ After exit conditions are met (including user selecting branch handling method),
 The verify phase may trigger context compaction. To recover, first run:
 
 ```bash
-"$COMET_BASH" "$COMET_STATE" check <change-name> verify --recover
+node "$COMET_STATE" check <change-name> verify --recover
 ```
 
 The script outputs structured recovery context (phase, verification status, branch status, recovery action). Follow the Recovery action to determine next step.
diff --git a/assets/skills/comet/SKILL.md b/assets/skills/comet/SKILL.md
index c8b38629..fb9a421a 100644
--- a/assets/skills/comet/SKILL.md
+++ b/assets/skills/comet/SKILL.md
@@ -67,8 +67,8 @@ Prefer reading `openspec/changes/<name>/.comet.yaml`. If not available, fall bac
   - If `build_pause: plan-ready` but the plan file is missing, return to `/comet-build` to handle corrupted state or regenerate the plan
   - If `build_mode` or `isolation` is unset, return to the corresponding `/comet-build` step to supplement before executing
   - If both are set, read the next unchecked task from tasks.md and continue
-- If `phase: verify` and `verify_result: fail`, enter the verification failure decision blocking point: pause and ask the user to fix or accept deviation; only after the user chooses fix, run `"$COMET_BASH" "$COMET_STATE" transition <name> verify-fail` and invoke `/comet-build`
-- If `phase: open` but proposal/design/tasks are complete, first run `"$COMET_BASH" "$COMET_GUARD" <change-name> open --apply` to repair state, then continue detection
+- If `phase: verify` and `verify_result: fail`, enter the verification failure decision blocking point: pause and ask the user to fix or accept deviation; only after the user chooses fix, run `node "$COMET_STATE" transition <name> verify-fail` and invoke `/comet-build`
+- If `phase: open` but proposal/design/tasks are complete, first run `node "$COMET_GUARD" <change-name> open --apply` to repair state, then continue detection
 - If `phase: archive`, only invoke `/comet-archive`; after archive succeeds, the change moves to the archive directory, so do not run guard against the old active directory
 
 **Step 2: Phase Determination** (check in order, first match wins)
@@ -105,7 +105,7 @@ If metadata conflicts with file state, use verifiable file state as source of tr
 |----------|----------|
 | `openspec list --json` fails | Check if openspec is installed, prompt user to run `openspec init` |
 | Sub-skill unavailable | Stop workflow, prompt to install or enable the corresponding skill |
-| `.comet.yaml` malformed or missing | Use file state as source of truth, correct with `"$COMET_BASH" "$COMET_STATE" set` then continue |
+| `.comet.yaml` malformed or missing | Use file state as source of truth, correct with `node "$COMET_STATE" set` then continue |
 | Build/test fails | Return to build phase for fixes, do not enter verify |
 | Incomplete change directory structure | Fill missing files according to `comet-open` artifact requirements |
 
@@ -226,24 +226,28 @@ State-machine hard constraints:
 - Before `build → verify`, `build_mode` must be selected
 - `build_mode: direct` is allowed by default only for `hotfix` / `tweak`; full workflow requires `direct_override: true`
 - `build_pause` is not an execution method and must not be written to `build_mode`
-- These constraints are enforced by both `comet-guard.sh build --apply` and `comet-state.sh transition <name> build-complete`
+- These constraints are enforced by both `comet-guard.js build --apply` and `comet-state.js transition <name> build-complete`
 
 ### Script Location
 
 Comet scripts are distributed in `comet/scripts/`. **Do not hardcode paths** — locate once, cache in env vars:
 
 ```bash
-COMET_ENV="${COMET_ENV:-$(find . "$HOME"/.*/skills "$HOME/.config" "$HOME/.gemini" -path '*/comet/scripts/comet-env.sh' -type f -print -quit 2>/dev/null)}"
+COMET_ENV="${COMET_ENV:-$(find . "$HOME"/.*/skills "$HOME/.config" "$HOME/.gemini" -path '*/comet/scripts/comet-env.js' -type f -print -quit 2>/dev/null)}"
 if [ -z "$COMET_ENV" ]; then
-  echo "ERROR: comet-env.sh not found. Ensure the comet skill is installed." >&2
+  echo "ERROR: comet-env.js not found. Ensure the comet skill is installed." >&2
   return 1
 fi
-. "$COMET_ENV"
+COMET_ENV_JSON="$(node "$COMET_ENV")"
+COMET_STATE="$(printf '%s' "$COMET_ENV_JSON" | node -e "let s='';process.stdin.on('data',d=>s+=d).on('end',()=>console.log(JSON.parse(s).COMET_STATE))")"
+COMET_GUARD="$(printf '%s' "$COMET_ENV_JSON" | node -e "let s='';process.stdin.on('data',d=>s+=d).on('end',()=>console.log(JSON.parse(s).COMET_GUARD))")"
+COMET_HANDOFF="$(printf '%s' "$COMET_ENV_JSON" | node -e "let s='';process.stdin.on('data',d=>s+=d).on('end',()=>console.log(JSON.parse(s).COMET_HANDOFF))")"
+COMET_ARCHIVE="$(printf '%s' "$COMET_ENV_JSON" | node -e "let s='';process.stdin.on('data',d=>s+=d).on('end',()=>console.log(JSON.parse(s).COMET_ARCHIVE))")"
 
 # Stop workflow when script location fails
 if [ -z "$COMET_GUARD" ] || [ -z "$COMET_STATE" ] || [ -z "$COMET_HANDOFF" ] || [ -z "$COMET_ARCHIVE" ]; then
   echo "ERROR: Comet scripts not found. Ensure the comet skill is installed." >&2
-  echo "Expected path pattern: */comet/scripts/comet-*.sh under project or platform skill directories" >&2
+  echo "Expected path pattern: */comet/scripts/comet-*.js under project or platform skill directories" >&2
   return 1
 fi
 ```
@@ -251,24 +255,24 @@ fi
 **Auto state update**: Guard supports `--apply` flag, automatically updating `.comet.yaml` state fields after checks pass:
 
 ```bash
-"$COMET_BASH" "$COMET_GUARD" <change-name> <phase> --apply
+node "$COMET_GUARD" <change-name> <phase> --apply
 ```
 
 `--apply` delegates to `comet-state transition`. Use these semantic events when state changes need to be expressed directly:
 
 ```bash
-"$COMET_BASH" "$COMET_STATE" transition <change-name> open-complete
-"$COMET_BASH" "$COMET_STATE" transition <change-name> design-complete
-"$COMET_BASH" "$COMET_STATE" transition <change-name> build-complete
-"$COMET_BASH" "$COMET_STATE" transition <change-name> verify-pass
-"$COMET_BASH" "$COMET_STATE" transition <change-name> verify-fail
-"$COMET_BASH" "$COMET_STATE" transition <archive-name> archived
+node "$COMET_STATE" transition <change-name> open-complete
+node "$COMET_STATE" transition <change-name> design-complete
+node "$COMET_STATE" transition <change-name> build-complete
+node "$COMET_STATE" transition <change-name> verify-pass
+node "$COMET_STATE" transition <change-name> verify-fail
+node "$COMET_STATE" transition <archive-name> archived
 ```
 
 **Archive script**: Complete all archive steps in one command:
 
 ```bash
-"$COMET_BASH" "$COMET_ARCHIVE" <change-name>
+node "$COMET_ARCHIVE" <change-name>
 ```
 
 After loading comet, agents should run the variable assignments above once, then reuse `$COMET_GUARD`, `$COMET_STATE`, `$COMET_HANDOFF`, `$COMET_ARCHIVE` throughout the session.
@@ -299,7 +303,7 @@ docs/superpowers/                      # Superpowers — HOW
 
 1. **brainstorming cannot be skipped** — Every change must undergo deep design (except hotfix and tweak)
 2. **delta spec is a living document** — Freely modify during phase 3, sync at archive
-3. **Handoff packages are generated by scripts** — OpenSpec → Superpowers context must be generated through `comet-handoff.sh` as compact traceable excerpts (use `--full` when needed), and validated by guard for source/hash/mode
+3. **Handoff packages are generated by scripts** — OpenSpec → Superpowers context must be generated through `comet-handoff.js` as compact traceable excerpts (use `--full` when needed), and validated by guard for source/hash/mode
 4. **Keep tasks.md in sync** — Check off each completed task
 5. **Commit frequently** — One commit per task, message reflects design intent
 6. **Verify before archive** — Execute `/comet-archive` only after `/comet-verify` passes
diff --git a/assets/skills/comet/scripts/comet-archive.js b/assets/skills/comet/scripts/comet-archive.js
new file mode 100644
index 00000000..c44ab4c9
--- /dev/null
+++ b/assets/skills/comet/scripts/comet-archive.js
@@ -0,0 +1,106 @@
+#!/usr/bin/env node
+import { copyFileSync, existsSync, mkdirSync, readdirSync, readFileSync, renameSync, statSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fieldValue, green, red, runNode, scriptDir, today, validateChangeName, yellow } from './comet-lib.js';
+
+const [change, flag] = process.argv.slice(2);
+const dryRun = flag === '--dry-run';
+validateChangeName(change, 'FATAL');
+const changeDir = join('openspec', 'changes', change);
+const yaml = join(changeDir, '.comet.yaml');
+const archiveName = `${today()}-${change}`;
+const archiveDir = join('openspec', 'changes', 'archive', archiveName);
+let stepsOk = 0;
+let stepsTotal = 0;
+
+function fatal(message) {
+  red(`FATAL: ${message}`);
+  process.exit(1);
+}
+
+function stepOk(message) { green(`  [OK] ${message}`); stepsOk += 1; stepsTotal += 1; }
+function stepFail(message) { red(`  [FAIL] ${message}`); stepsTotal += 1; }
+function stepDry(message) { yellow(`  [DRY-RUN] ${message}`); stepsOk += 1; stepsTotal += 1; }
+function y(field) { return fieldValue(yaml, field); }
+
+console.error(`=== Comet Archive: ${change} ===`);
+if (!existsSync(yaml)) fatal(`.comet.yaml not found in ${changeDir}/`);
+const designDoc = y('design_doc');
+const planPath = y('plan');
+if (y('phase') !== 'archive') fatal(`phase is '${y('phase')}', expected 'archive'`);
+if (y('verify_result') !== 'pass') fatal(`verify_result is '${y('verify_result')}', expected 'pass'. Run comet-verify first.`);
+if (y('archived') === 'true') fatal('change already archived');
+stepOk('Entry state verified');
+if (existsSync(archiveDir)) fatal(`archive target already exists: ${archiveDir}`);
+stepOk('Archive target available');
+
+function syncDeltaSpecs() {
+  const deltaRoot = join(changeDir, 'specs');
+  if (!existsSync(deltaRoot)) return;
+  for (const capability of readdirSync(deltaRoot)) {
+    const deltaSpecDir = join(deltaRoot, capability);
+    if (!statSync(deltaSpecDir).isDirectory()) continue;
+    const deltaSpec = join(deltaSpecDir, 'spec.md');
+    const mainSpec = join('openspec', 'specs', capability, 'spec.md');
+    if (!existsSync(deltaSpec)) continue;
+    if (dryRun) {
+      stepDry(`Would sync: ${capability} → ${mainSpec}`);
+      continue;
+    }
+    mkdirSync(dirname(mainSpec), { recursive: true });
+    copyFileSync(deltaSpec, mainSpec);
+    stepOk(`Delta spec synced: ${capability} → openspec/specs/${capability}/spec.md`);
+  }
+}
+
+function annotateFrontmatter(file, extraFields) {
+  if (!existsSync(file)) return;
+  if (dryRun) {
+    stepDry(`Would annotate: ${file}`);
+    return;
+  }
+  const text = readFileSync(file, 'utf8');
+  let next;
+  if (text.startsWith('---')) {
+    const lines = text.split(/\r?\n/);
+    const out = [];
+    let inserted = false;
+    for (let i = 0; i < lines.length; i += 1) {
+      const line = lines[i];
+      if (/^archived-with:/.test(line)) continue;
+      if (i > 0 && line === '---' && !inserted) {
+        out.push(`archived-with: ${archiveName}`);
+        if (extraFields) out.push(extraFields);
+        inserted = true;
+      }
+      out.push(line);
+    }
+    next = out.join('\n');
+  } else {
+    next = `---\narchived-with: ${archiveName}\n${extraFields ? `${extraFields}\n` : ''}status: final\n---\n${text}`;
+  }
+  writeFileSync(file, next);
+  stepOk(`Annotated: ${file}`);
+}
+
+syncDeltaSpecs();
+if (designDoc && designDoc !== 'null') annotateFrontmatter(designDoc, 'status: final');
+if (planPath && planPath !== 'null') annotateFrontmatter(planPath, '');
+if (dryRun) stepDry(`Would move: ${changeDir} → ${archiveDir}`);
+else {
+  mkdirSync(join('openspec', 'changes', 'archive'), { recursive: true });
+  renameSync(changeDir, archiveDir);
+  stepOk(`Moved to: ${archiveDir}`);
+}
+const archiveYaml = join(archiveDir, '.comet.yaml');
+if (dryRun) stepDry(`Would set archived: true in ${archiveYaml}`);
+else if (existsSync(archiveYaml)) {
+  const state = join(scriptDir, 'comet-state.js');
+  const result = runNode(state, ['transition', archiveName, 'archived']);
+  if (result.status === 0) stepOk('archived: true');
+  else stepFail('archived: true');
+} else stepFail('archived: true (.comet.yaml not found after move)');
+console.error('');
+if (dryRun) yellow(`Dry run complete. ${stepsOk}/${stepsTotal} steps would succeed.`);
+else green(`Archive complete. ${stepsOk}/${stepsTotal} steps succeeded.`);
+if (stepsOk < stepsTotal) process.exit(1);
diff --git a/assets/skills/comet/scripts/comet-archive.sh b/assets/skills/comet/scripts/comet-archive.sh
deleted file mode 100644
index 746f6138..00000000
--- a/assets/skills/comet/scripts/comet-archive.sh
+++ /dev/null
@@ -1,295 +0,0 @@
-#!/bin/bash
-# Comet Archive — automates the archive phase in one command
-# Usage: comet-archive.sh <change-name> [--dry-run]
-# Exit 0 = archive complete, exit 1 = fatal error
-
-set -euo pipefail
-
-COMET_BASH="${COMET_BASH:-${BASH:-bash}}"
-
-red() { echo -e "\033[31m$1\033[0m" >&2; }
-green() { echo -e "\033[32m$1\033[0m" >&2; }
-yellow() { echo -e "\033[33m$1\033[0m" >&2; }
-
-DRY_RUN=0
-if [[ "${2:-}" == "--dry-run" ]]; then
-  DRY_RUN=1
-fi
-
-# Input validation
-validate_change_name() {
-  local name="$1"
-  if [ -z "$name" ]; then
-    red "FATAL: Change name cannot be empty"
-    exit 1
-  fi
-  if [[ ! "$name" =~ ^[a-zA-Z0-9_-]+$ ]]; then
-    red "FATAL: Invalid change name: '$name'"
-    red "Valid characters: a-z, A-Z, 0-9, -, _"
-    exit 1
-  fi
-  if [[ "$name" =~ \.\. ]]; then
-    red "FATAL: Change name cannot contain '..'"
-    exit 1
-  fi
-}
-
-CHANGE="$1"
-validate_change_name "$CHANGE"
-
-CHANGE_DIR="openspec/changes/$CHANGE"
-YAML="$CHANGE_DIR/.comet.yaml"
-SCRIPT_DIR="$(cd "$(dirname "$(readlink -f "$0" 2>/dev/null || echo "$0")" 2>/dev/null || dirname "$0")" && pwd)"
-STATE_SH="$SCRIPT_DIR/comet-state.sh"
-TODAY=$(date +%Y-%m-%d)
-ARCHIVE_NAME="${TODAY}-${CHANGE}"
-ARCHIVE_DIR="openspec/changes/archive/${ARCHIVE_NAME}"
-
-STEPS_OK=0
-STEPS_TOTAL=0
-
-step_ok() {
-  green "  [OK] $1"
-  STEPS_OK=$((STEPS_OK + 1))
-  STEPS_TOTAL=$((STEPS_TOTAL + 1))
-}
-
-step_fail() {
-  red "  [FAIL] $1"
-  STEPS_TOTAL=$((STEPS_TOTAL + 1))
-}
-
-step_dry_run() {
-  yellow "  [DRY-RUN] $1"
-  STEPS_OK=$((STEPS_OK + 1))
-  STEPS_TOTAL=$((STEPS_TOTAL + 1))
-}
-
-echo "=== Comet Archive: $CHANGE ===" >&2
-
-# --- Step 1: Read .comet.yaml, extract paths ---
-
-yaml_field() {
-  local field="$1"
-  if [ -f "$STATE_SH" ]; then
-    "$COMET_BASH" "$STATE_SH" get "$CHANGE" "$field" 2>/dev/null
-  else
-    if [ -f "$YAML" ]; then
-      local value
-      value=$(grep "^${field}:" "$YAML" 2>/dev/null | sed "s/^${field}: *//" || true)
-      value=$(strip_inline_comment "$value")
-      strip_wrapping_quotes "$value"
-    fi
-  fi
-}
-
-strip_inline_comment() {
-  local value="$1"
-  printf '%s\n' "$value" | awk -v squote="'" '
-    {
-      out = ""
-      quote = ""
-      for (i = 1; i <= length($0); i++) {
-        c = substr($0, i, 1)
-        if (quote == "") {
-          if (c == "\"" || c == squote) {
-            quote = c
-          } else if (c == "#" && (i == 1 || substr($0, i - 1, 1) ~ /[[:space:]]/)) {
-            sub(/[[:space:]]+$/, "", out)
-            print out
-            next
-          }
-        } else if (c == quote) {
-          quote = ""
-        }
-        out = out c
-      }
-      print out
-    }
-  '
-}
-
-strip_wrapping_quotes() {
-  local value="$1"
-  case "$value" in
-    \"*\") printf '%s\n' "${value:1:${#value}-2}" ;;
-    \'*\') printf '%s\n' "${value:1:${#value}-2}" ;;
-    *) printf '%s\n' "$value" ;;
-  esac
-}
-
-if [ ! -f "$YAML" ]; then
-  red "FATAL: .comet.yaml not found in $CHANGE_DIR/"
-  exit 1
-fi
-
-DESIGN_DOC=$(yaml_field "design_doc")
-PLAN_PATH=$(yaml_field "plan")
-
-# --- Step 2: Validate entry state ---
-
-PHASE_VAL=$(yaml_field "phase")
-VERIFY_VAL=$(yaml_field "verify_result")
-ARCHIVED_VAL=$(yaml_field "archived")
-
-if [ "$PHASE_VAL" != "archive" ]; then
-  red "FATAL: phase is '$PHASE_VAL', expected 'archive'"
-  exit 1
-fi
-
-if [ "$VERIFY_VAL" != "pass" ]; then
-  red "FATAL: verify_result is '$VERIFY_VAL', expected 'pass'. Run comet-verify first."
-  exit 1
-fi
-
-if [ "$ARCHIVED_VAL" = "true" ]; then
-  red "FATAL: change already archived"
-  exit 1
-fi
-
-step_ok "Entry state verified"
-
-# --- Step 3: Check archive target ---
-
-if [ -d "$ARCHIVE_DIR" ]; then
-  red "FATAL: archive target already exists: $ARCHIVE_DIR"
-  exit 1
-fi
-
-step_ok "Archive target available"
-
-# --- Step 4: Sync delta specs → main specs ---
-
-sync_delta_specs() {
-  local delta_root="$CHANGE_DIR/specs"
-  if [ ! -d "$delta_root" ]; then
-    return 0
-  fi
-
-  for delta_spec_dir in "$delta_root"/*/; do
-    [ -d "$delta_spec_dir" ] || continue
-    local capability
-    capability=$(basename "$delta_spec_dir")
-    local delta_spec="$delta_spec_dir/spec.md"
-    local main_spec="openspec/specs/$capability/spec.md"
-
-    if [ ! -f "$delta_spec" ]; then
-      continue
-    fi
-
-    if [ "$DRY_RUN" -eq 1 ]; then
-      step_dry_run "Would sync: $capability → $main_spec"
-      continue
-    fi
-
-    if [ ! -f "$main_spec" ]; then
-      mkdir -p "openspec/specs/$capability"
-    elif ! cmp -s "$main_spec" "$delta_spec"; then
-      yellow "  [DIFF] Delta spec differs from main spec before sync: $capability"
-      diff -u "$main_spec" "$delta_spec" >&2 || true
-    fi
-    cp "$delta_spec" "$main_spec"
-
-    step_ok "Delta spec synced: $capability → openspec/specs/$capability/spec.md"
-  done
-}
-
-sync_delta_specs
-
-# --- Step 5: Annotate design doc frontmatter ---
-
-annotate_frontmatter() {
-  local file="$1"
-  local extra_fields="$2"
-
-  if [ ! -f "$file" ]; then
-    return 0
-  fi
-
-  if [ "$DRY_RUN" -eq 1 ]; then
-    step_dry_run "Would annotate: $file"
-    return 0
-  fi
-
-  if head -1 "$file" | grep -q '^---'; then
-    local tmp_file
-    tmp_file=$(mktemp)
-    awk -v archive="$ARCHIVE_NAME" -v extra="$extra_fields" '
-      /^archived-with:/ { next }
-      NR==1 && /^---/ { print; next }
-      /^---/ && NR>1 {
-        print "archived-with: " archive
-        if (extra != "") print extra
-        print; next
-      }
-      { print }
-    ' "$file" > "$tmp_file"
-    mv "$tmp_file" "$file"
-  else
-    local tmp_file
-    tmp_file=$(mktemp)
-    {
-      echo "---"
-      echo "archived-with: $ARCHIVE_NAME"
-      if [ -n "$extra_fields" ]; then
-        echo "$extra_fields"
-      fi
-      echo "status: final"
-      echo "---"
-      cat "$file"
-    } > "$tmp_file"
-    mv "$tmp_file" "$file"
-  fi
-
-  step_ok "Annotated: $file"
-}
-
-if [ -n "$DESIGN_DOC" ] && [ "$DESIGN_DOC" != "null" ]; then
-  annotate_frontmatter "$DESIGN_DOC" "status: final"
-fi
-
-# --- Step 6: Annotate plan frontmatter ---
-
-if [ -n "$PLAN_PATH" ] && [ "$PLAN_PATH" != "null" ]; then
-  annotate_frontmatter "$PLAN_PATH" ""
-fi
-
-# --- Step 7: Move change to archive ---
-
-if [ "$DRY_RUN" -eq 1 ]; then
-  step_dry_run "Would move: $CHANGE_DIR → $ARCHIVE_DIR"
-else
-  mkdir -p "openspec/changes/archive"
-  mv "$CHANGE_DIR" "$ARCHIVE_DIR"
-  step_ok "Moved to: $ARCHIVE_DIR"
-fi
-
-# --- Step 8: Mark archived via comet-state transition ---
-
-ARCHIVE_YAML="$ARCHIVE_DIR/.comet.yaml"
-
-if [ "$DRY_RUN" -eq 1 ]; then
-  step_dry_run "Would set archived: true in $ARCHIVE_YAML"
-else
-  if [ -f "$ARCHIVE_YAML" ]; then
-    "$COMET_BASH" "$STATE_SH" transition "$ARCHIVE_NAME" archived >/dev/null
-    step_ok "archived: true"
-  else
-    step_fail "archived: true (.comet.yaml not found after move)"
-  fi
-fi
-
-# --- Step 9: Print summary ---
-
-echo "" >&2
-if [ "$DRY_RUN" -eq 1 ]; then
-  yellow "Dry run complete. $STEPS_OK/$STEPS_TOTAL steps would succeed."
-else
-  green "Archive complete. $STEPS_OK/$STEPS_TOTAL steps succeeded."
-fi
-
-if [ "$STEPS_OK" -lt "$STEPS_TOTAL" ]; then
-  exit 1
-fi
-
-exit 0
diff --git a/assets/skills/comet/scripts/comet-env.js b/assets/skills/comet/scripts/comet-env.js
new file mode 100644
index 00000000..83103746
--- /dev/null
+++ b/assets/skills/comet/scripts/comet-env.js
@@ -0,0 +1,21 @@
+#!/usr/bin/env node
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { scriptDir } from './comet-lib.js';
+
+const env = {
+  COMET_STATE: join(scriptDir, 'comet-state.js'),
+  COMET_GUARD: join(scriptDir, 'comet-guard.js'),
+  COMET_HANDOFF: join(scriptDir, 'comet-handoff.js'),
+  COMET_ARCHIVE: join(scriptDir, 'comet-archive.js'),
+  COMET_YAML_VALIDATE: join(scriptDir, 'comet-yaml-validate.js'),
+};
+
+const missing = Object.values(env).filter((file) => !existsSync(file));
+if (missing.length > 0) {
+  console.error('ERROR: Comet scripts not found. Ensure the comet skill is installed completely.');
+  console.error('Expected path pattern: */comet/scripts/comet-*.js under project or platform skill directories');
+  process.exit(1);
+}
+
+console.log(JSON.stringify(env, null, 2));
diff --git a/assets/skills/comet/scripts/comet-env.sh b/assets/skills/comet/scripts/comet-env.sh
deleted file mode 100644
index d480f10d..00000000
--- a/assets/skills/comet/scripts/comet-env.sh
+++ /dev/null
@@ -1,110 +0,0 @@
-#!/bin/bash
-# Comet script locator — source this file to export paths to bundled scripts.
-#
-# Usage:
-#   . /path/to/comet/scripts/comet-env.sh
-#
-# This file is sourced by workflow snippets. Do not set global shell options here.
-
-_comet_env_source="${BASH_SOURCE[0]:-$0}"
-_comet_script_dir="$(cd "$(dirname "$_comet_env_source")" && pwd -P)"
-_comet_env_sourced=0
-(return 0 2>/dev/null) && _comet_env_sourced=1
-
-export COMET_GUARD="${COMET_GUARD:-${_comet_script_dir}/comet-guard.sh}"
-export COMET_STATE="${COMET_STATE:-${_comet_script_dir}/comet-state.sh}"
-export COMET_HANDOFF="${COMET_HANDOFF:-${_comet_script_dir}/comet-handoff.sh}"
-export COMET_ARCHIVE="${COMET_ARCHIVE:-${_comet_script_dir}/comet-archive.sh}"
-export COMET_YAML_VALIDATE="${COMET_YAML_VALIDATE:-${_comet_script_dir}/comet-yaml-validate.sh}"
-
-_comet_bash_is_usable() {
-  local _comet_bash_candidate="$1"
-  if [ -z "$_comet_bash_candidate" ]; then
-    return 1
-  fi
-  case "$_comet_bash_candidate" in
-    */Windows/System32/bash.exe|*/windows/system32/bash.exe|*\\Windows\\System32\\bash.exe|*\\windows\\system32\\bash.exe)
-      return 1
-      ;;
-  esac
-  "$_comet_bash_candidate" -lc 'printf comet-bash-ok' >/dev/null 2>&1
-}
-
-_comet_resolve_bash() {
-  local _comet_bash_candidate
-
-  if _comet_bash_is_usable "${COMET_BASH:-}"; then
-    printf '%s\n' "$COMET_BASH"
-    return 0
-  fi
-
-  if _comet_bash_is_usable "${BASH:-}"; then
-    printf '%s\n' "$BASH"
-    return 0
-  fi
-
-  _comet_bash_candidate="$(command -v sh 2>/dev/null | awk '{ sub(/\/sh(\.exe)?$/, "/bash.exe"); print }')"
-  if _comet_bash_is_usable "$_comet_bash_candidate"; then
-    printf '%s\n' "$_comet_bash_candidate"
-    return 0
-  fi
-
-  _comet_bash_candidate="$(command -v bash 2>/dev/null || true)"
-  if _comet_bash_is_usable "$_comet_bash_candidate"; then
-    printf '%s\n' "$_comet_bash_candidate"
-    return 0
-  fi
-
-  return 1
-}
-
-COMET_BASH="$(_comet_resolve_bash || true)"
-export COMET_BASH
-
-_comet_env_fail() {
-  echo "ERROR: Comet scripts not found. Ensure the comet skill is installed completely." >&2
-  echo "Expected path pattern: */comet/scripts/comet-*.sh under project or platform skill directories" >&2
-}
-
-_comet_bash_fail() {
-  echo "ERROR: usable bash not found. Install Git Bash or set COMET_BASH to a working bash executable." >&2
-  echo "Windows WSL launcher bash.exe is not supported for Comet scripts." >&2
-}
-
-_comet_env_abort() {
-  local _comet_env_was_sourced="$_comet_env_sourced"
-  unset _comet_env_source _comet_script_dir _comet_script _comet_env_missing _comet_env_sourced
-  unset _comet_bash_candidate
-  unset -f _comet_env_fail _comet_bash_fail _comet_bash_is_usable _comet_resolve_bash
-  if [ "$_comet_env_was_sourced" -eq 1 ]; then
-    unset -f _comet_env_abort
-    return 1
-  fi
-  exit 1
-}
-
-_comet_env_missing=0
-if [ -z "$COMET_BASH" ]; then
-  _comet_bash_fail
-  _comet_env_missing=1
-fi
-for _comet_script in \
-  "$COMET_GUARD" \
-  "$COMET_STATE" \
-  "$COMET_HANDOFF" \
-  "$COMET_ARCHIVE" \
-  "$COMET_YAML_VALIDATE"; do
-  if [ ! -f "$_comet_script" ]; then
-    _comet_env_fail
-    _comet_env_missing=1
-    break
-  fi
-done
-
-if [ "$_comet_env_missing" -ne 0 ]; then
-  _comet_env_abort
-else
-  unset _comet_env_source _comet_script_dir _comet_script _comet_env_missing _comet_env_sourced
-  unset _comet_bash_candidate
-  unset -f _comet_env_fail _comet_bash_fail _comet_bash_is_usable _comet_resolve_bash _comet_env_abort
-fi
diff --git a/assets/skills/comet/scripts/comet-guard.js b/assets/skills/comet/scripts/comet-guard.js
new file mode 100644
index 00000000..21fe38b8
--- /dev/null
+++ b/assets/skills/comet/scripts/comet-guard.js
@@ -0,0 +1,281 @@
+#!/usr/bin/env node
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import {
+  changeDirFor,
+  fieldValue,
+  fileNonempty,
+  green,
+  hashFile,
+  red,
+  runCommand,
+  runCommandString,
+  runNode,
+  scriptDir,
+  sha256,
+  slash,
+  validateChangeName,
+  yellow,
+} from './comet-lib.js';
+
+const [change, phase, applyFlag] = process.argv.slice(2);
+validateChangeName(change);
+const apply = applyFlag === '--apply';
+let changeDir = join('openspec', 'changes', change);
+if (phase === 'archive' && !existsSync(changeDir) && existsSync(join('openspec', 'changes', 'archive', change))) {
+  changeDir = join('openspec', 'changes', 'archive', change);
+}
+const yaml = join(changeDir, '.comet.yaml');
+let block = false;
+
+function check(desc, fn) {
+  try {
+    const result = fn();
+    if (result === true || result === undefined) green(`  [PASS] ${desc}`);
+    else throw new Error(String(result));
+  } catch (error) {
+    red(`  [FAIL] ${desc}`);
+    const message = error instanceof Error ? error.message : String(error);
+    if (message) for (const line of message.split(/\r?\n/)) red(`    ${line}`);
+    block = true;
+  }
+}
+
+function y(field) {
+  return fieldValue(yaml, field);
+}
+
+function preflight() {
+  if (!existsSync(changeDir)) {
+    red(`FATAL: change directory not found: ${changeDir}`);
+    process.exit(1);
+  }
+  if (!existsSync(yaml)) {
+    red(`FATAL: .comet.yaml not found in ${changeDir}`);
+    process.exit(1);
+  }
+  const validateScript = join(scriptDir, 'comet-yaml-validate.js');
+  if (existsSync(validateScript)) {
+    const result = runNode(validateScript, [change]);
+    if (result.status !== 0) {
+      process.stderr.write(result.stderr || '');
+      red('FATAL: .comet.yaml schema validation failed');
+      process.exit(1);
+    }
+  }
+}
+
+function tasksAllDone() {
+  const tasks = join(changeDir, 'tasks.md');
+  if (!existsSync(tasks)) throw new Error(`tasks.md is missing at ${tasks}\nNext: restore or create tasks.md for this change before leaving build.`);
+  const text = readFileSync(tasks, 'utf8');
+  if (!/- \[x\]/.test(text)) throw new Error("tasks.md has no completed tasks.\nNext: complete implementation tasks and mark them with '- [x]'.");
+  const unfinished = text.split(/\r?\n/).map((line, index) => ({ line, index: index + 1 })).filter(({ line }) => /- \[ \]/.test(line));
+  if (unfinished.length > 0) {
+    throw new Error(`Unfinished tasks:\n${unfinished.map(({ line, index }) => `${index}:${line}`).join('\n')}\nNext: complete or explicitly remove unfinished tasks, then mark tasks.md with '- [x]'.`);
+  }
+}
+
+function tasksHasAny() {
+  return existsSync(join(changeDir, 'tasks.md')) && /- \[/.test(readFileSync(join(changeDir, 'tasks.md'), 'utf8'));
+}
+
+function projectConfigValue(field) {
+  const local = y(field);
+  if (local && local !== 'null') return local;
+  for (const config of ['.comet.yaml', 'comet.yaml', '.comet.yml', 'comet.yml']) {
+    if (existsSync(config)) {
+      const value = fieldValue(config, field);
+      if (value && value !== 'null') return value;
+    }
+  }
+  return '';
+}
+
+function buildPasses() {
+  if (process.env.COMET_SKIP_BUILD === '1') return;
+  const configured = projectConfigValue('build_command');
+  if (configured) {
+    const result = runCommandString(configured);
+    if (result.status !== 0) throw new Error(`command failed: ${configured}`);
+    return;
+  }
+  if (existsSync('package.json') && /"build"/.test(readFileSync('package.json', 'utf8'))) {
+    const result = runCommand(['npm', 'run', 'build']);
+    if (result.status !== 0) throw new Error('npm run build failed');
+    return;
+  }
+  if (existsSync('pom.xml')) {
+    const result = existsSync('./mvnw') ? runCommand(['./mvnw', 'compile', '-q']) : runCommand(['mvn', 'compile', '-q']);
+    if (result.status !== 0) throw new Error('maven build failed');
+    return;
+  }
+  if (existsSync('Cargo.toml')) {
+    const result = runCommand(['cargo', 'build']);
+    if (result.status !== 0) throw new Error('cargo build failed');
+    return;
+  }
+  throw new Error('no build command found');
+}
+
+function verificationCommandPasses() {
+  if (process.env.COMET_SKIP_BUILD === '1') return;
+  const configured = projectConfigValue('verify_command');
+  if (configured) {
+    const result = runCommandString(configured);
+    if (result.status !== 0) throw new Error(`command failed: ${configured}`);
+    return;
+  }
+  buildPasses();
+}
+
+function sourceFiles() {
+  const files = [join(changeDir, 'proposal.md'), join(changeDir, 'design.md'), join(changeDir, 'tasks.md')];
+  const specsRoot = join(changeDir, 'specs');
+  if (existsSync(specsRoot)) {
+    const { readdirSync, statSync } = awaitFs;
+    function walk(dir) {
+      for (const entry of readdirSync(dir)) {
+        const p = join(dir, entry);
+        const stat = statSync(p);
+        if (stat.isDirectory()) walk(p);
+        else if (entry === 'spec.md') files.push(p);
+      }
+    }
+    walk(specsRoot);
+  }
+  return files;
+}
+import * as awaitFs from 'node:fs';
+
+function computeHandoffHash() {
+  let content = '';
+  for (const file of sourceFiles()) if (existsSync(file)) content += `path:${slash(file)}\nsha256:${hashFile(file)}\n`;
+  return sha256(content);
+}
+
+function designHandoffContextValid() {
+  const context = y('handoff_context');
+  const recordedHash = y('handoff_hash');
+  if (!context || context === 'null') throw new Error('handoff_context is missing from .comet.yaml\nNext: run node "$COMET_HANDOFF" <change> design --write before invoking Superpowers.');
+  if (!fileNonempty(context)) throw new Error(`handoff_context does not point to a non-empty file: ${context}\nNext: regenerate the design handoff with comet-handoff.js.`);
+  if (!/^[a-f0-9]{64}$/.test(recordedHash)) throw new Error(`handoff_hash is missing or invalid: ${recordedHash || 'null'}\nNext: regenerate the design handoff with comet-handoff.js.`);
+  const actualHash = computeHandoffHash();
+  if (actualHash !== recordedHash) throw new Error(`OpenSpec artifacts changed after handoff was generated.\nExpected handoff_hash: ${recordedHash}\nActual handoff_hash:   ${actualHash}\nNext: rerun comet-handoff.js so Superpowers receives the current OpenSpec context.`);
+  const markdown = context.replace(/\.json$/, '.md');
+  if (!fileNonempty(markdown)) throw new Error(`design handoff markdown is missing or empty: ${markdown}\nNext: regenerate the design handoff with comet-handoff.js.`);
+}
+
+function designHandoffMarkdownTraceable() {
+  const context = y('handoff_context');
+  if (!context || context === 'null') throw new Error('handoff_context is missing from .comet.yaml');
+  const markdown = context.replace(/\.json$/, '.md');
+  if (!fileNonempty(markdown)) throw new Error(`design handoff markdown is missing or empty: ${markdown}`);
+  const text = readFileSync(markdown, 'utf8');
+  const missing = [];
+  if (!/^Generated-by: comet-handoff\.js$/m.test(text)) missing.push('handoff markdown is missing Generated-by marker');
+  if (!/^- Mode: (compact|full)$/m.test(text)) missing.push('handoff markdown is missing Mode marker');
+  for (const file of sourceFiles()) {
+    if (!existsSync(file)) continue;
+    if (!text.includes(`- Source: ${slash(file)}`)) missing.push(`handoff markdown is missing source reference: ${slash(file)}`);
+    if (!text.includes(`- SHA256: ${hashFile(file)}`)) missing.push(`handoff markdown is missing current sha256 for: ${file}`);
+  }
+  if (missing.length) throw new Error(missing.join('\n'));
+}
+
+function frontmatterHas(file, field, expected) {
+  const text = readFileSync(file, 'utf8').replace(/^\uFEFF/, '');
+  const match = text.match(/^\s*---\r?\n([\s\S]*?)\r?\n---/);
+  if (!match) return false;
+  return new RegExp(`^${field}: ['\"]?${expected}['\"]?\\s*$`, 'm').test(match[1]);
+}
+
+function guardOpen() {
+  console.error('=== Guard: open → next ===');
+  check('proposal.md exists and non-empty', () => fileNonempty(join(changeDir, 'proposal.md')));
+  check('design.md exists and non-empty', () => fileNonempty(join(changeDir, 'design.md')));
+  check('tasks.md exists and non-empty', () => fileNonempty(join(changeDir, 'tasks.md')));
+  check('tasks.md has at least one task', tasksHasAny);
+}
+
+function guardDesign() {
+  console.error('=== Guard: design → build ===');
+  const designDoc = y('design_doc');
+  check('proposal.md exists', () => fileNonempty(join(changeDir, 'proposal.md')));
+  check('design.md exists', () => fileNonempty(join(changeDir, 'design.md')));
+  check('tasks.md exists', () => fileNonempty(join(changeDir, 'tasks.md')));
+  check('design handoff context exists', designHandoffContextValid);
+  check('design handoff markdown is traceable', designHandoffMarkdownTraceable);
+  if (designDoc && designDoc !== 'null') {
+    check(`Design Doc (${designDoc}) exists`, () => fileNonempty(designDoc));
+    check('Design Doc frontmatter links current change', () => frontmatterHas(designDoc, 'comet_change', change));
+    check('Design Doc declares technical design role', () => frontmatterHas(designDoc, 'role', 'technical-design'));
+    check('Design Doc declares OpenSpec as canonical spec', () => frontmatterHas(designDoc, 'canonical_spec', 'openspec'));
+  } else yellow('  [WARN] No design_doc recorded in .comet.yaml');
+}
+
+function guardBuild() {
+  console.error('=== Guard: build → verify ===');
+  check('isolation selected', () => ['branch', 'worktree'].includes(y('isolation')) || `isolation must be branch or worktree, got '${y('isolation') || 'null'}'\nNext: ask the user to choose branch or worktree, create the chosen isolation, then run:\n  node "$COMET_STATE" set ${change} isolation <branch|worktree>`);
+  check('build_mode selected', () => ['subagent-driven-development', 'executing-plans', 'direct'].includes(y('build_mode')) || `build_mode must be selected before leaving build, got '${y('build_mode') || 'null'}'\nNext: ask the user to choose an execution mode, then run:\n  node "$COMET_STATE" set ${change} build_mode <subagent-driven-development|executing-plans>`);
+  check('build_mode allowed for workflow', () => y('build_mode') !== 'direct' || ['hotfix', 'tweak'].includes(y('workflow')) || y('direct_override') === 'true' || 'build_mode=direct is only allowed for hotfix/tweak unless direct_override: true is recorded\nNext: choose executing-plans or subagent-driven-development, or stop and ask the user for an explicit direct override.');
+  check('tasks.md all tasks checked', tasksAllDone);
+  check('proposal.md exists', () => fileNonempty(join(changeDir, 'proposal.md')));
+  check('Build passes', buildPasses);
+}
+
+function guardVerify() {
+  console.error('=== Guard: verify → archive ===');
+  check('tasks.md all tasks checked', tasksAllDone);
+  check('Build passes', verificationCommandPasses);
+  check('verification_report exists', () => y('verification_report') && y('verification_report') !== 'null' && existsSync(y('verification_report')));
+  check('branch_status=handled', () => y('branch_status') === 'handled');
+}
+
+function guardArchive() {
+  console.error('=== Guard: archive completeness ===');
+  check('archived is true', () => y('archived') === 'true');
+  check('proposal.md exists', () => fileNonempty(join(changeDir, 'proposal.md')));
+  check('tasks.md all tasks checked', tasksAllDone);
+}
+
+function applyStateUpdate() {
+  const state = join(scriptDir, 'comet-state.js');
+  if (!existsSync(state)) {
+    red('FATAL: comet-state.js not found; cannot apply state transition');
+    process.exit(1);
+  }
+  const event = { open: 'open-complete', design: 'design-complete', build: 'build-complete', verify: 'verify-pass' }[phase];
+  if (event) {
+    const result = runNode(state, ['transition', change, event]);
+    if (result.status !== 0) {
+      process.stderr.write(result.stderr || '');
+      process.exit(result.status ?? 1);
+    }
+  }
+}
+
+if (!['open', 'design', 'build', 'verify', 'archive'].includes(phase)) {
+  red(`Unknown phase: ${phase}`);
+  console.error('Valid phases: open, design, build, verify, archive');
+  process.exit(1);
+}
+preflight();
+({ open: guardOpen, design: guardDesign, build: guardBuild, verify: guardVerify, archive: guardArchive }[phase])();
+if (block) {
+  console.error('');
+  red('BLOCKED — fix failing checks before proceeding to next phase');
+  process.exit(1);
+}
+console.error('');
+green('ALL CHECKS PASSED — ready for next phase');
+if (apply) {
+  applyStateUpdate();
+  const messages = {
+    open: `  [APPLY] .comet.yaml updated: phase=${y('phase')}`,
+    design: '  [APPLY] .comet.yaml updated: phase=build',
+    build: '  [APPLY] .comet.yaml updated: phase=verify, verify_result=pending',
+    verify: '  [APPLY] .comet.yaml updated: phase=archive, verify_result=pass',
+  };
+  if (messages[phase]) green(messages[phase]);
+}
diff --git a/assets/skills/comet/scripts/comet-guard.sh b/assets/skills/comet/scripts/comet-guard.sh
deleted file mode 100644
index 5e66873b..00000000
--- a/assets/skills/comet/scripts/comet-guard.sh
+++ /dev/null
@@ -1,596 +0,0 @@
-#!/bin/bash
-# Comet Phase Guard — validates exit conditions before phase transitions
-# Usage: comet-guard.sh <change-name> <current-phase> [--apply]
-# Phases: open, design, build, verify, archive
-# Exit 0 = all checks pass, exit 1 = blocked (reasons printed to stderr)
-# shellcheck disable=SC2329  # Functions called indirectly via check() dispatch
-
-set -euo pipefail
-
-COMET_BASH="${COMET_BASH:-${BASH:-bash}}"
-
-red() { echo -e "\033[31m$1\033[0m" >&2; }
-green() { echo -e "\033[32m$1\033[0m" >&2; }
-warn() { echo -e "\033[33m$1\033[0m" >&2; }
-
-# Input validation - prevent path traversal
-validate_change_name() {
-  local name="$1"
-  # Reject empty names
-  if [ -z "$name" ]; then
-    red "ERROR: Change name cannot be empty" >&2
-    exit 1
-  fi
-  # Only allow alphanumeric, hyphens, and underscores
-  if [[ ! "$name" =~ ^[a-zA-Z0-9_-]+$ ]]; then
-    red "ERROR: Invalid change name: '$name'" >&2
-    red "Valid characters: a-z, A-Z, 0-9, -, _" >&2
-    exit 1
-  fi
-  # Reject path traversal attempts
-  if [[ "$name" =~ \.\. ]]; then
-    red "ERROR: Change name cannot contain '..' (path traversal not allowed)" >&2
-    exit 1
-  fi
-}
-
-validate_change_name "$1"
-
-CHANGE="$1"
-PHASE="$2"
-APPLY=0
-SCRIPT_DIR="$(dirname "$(readlink -f "$0" 2>/dev/null || echo "$0")" 2>/dev/null || dirname "$0")"
-if [[ "${3:-}" == "--apply" ]]; then
-  APPLY=1
-fi
-CHANGE_DIR="openspec/changes/$CHANGE"
-if [ "$PHASE" = "archive" ] && [ ! -d "$CHANGE_DIR" ] && [ -d "openspec/changes/archive/$CHANGE" ]; then
-  CHANGE_DIR="openspec/changes/archive/$CHANGE"
-fi
-
-BLOCK=0
-check() {
-  local desc="$1"
-  shift
-  local output
-  if output=$("$@" 2>&1); then
-    green "  [PASS] $desc"
-  else
-    red "  [FAIL] $desc"
-    if [ -n "$output" ]; then
-      while IFS= read -r line; do
-        red "    $line"
-      done <<< "$output"
-    fi
-    BLOCK=1
-  fi
-}
-
-# --- Helper functions ---
-
-tasks_all_done() {
-  local tasks="$CHANGE_DIR/tasks.md"
-  if [ ! -f "$tasks" ]; then
-    echo "tasks.md is missing at $tasks" >&2
-    echo "Next: restore or create tasks.md for this change before leaving build." >&2
-    return 1
-  fi
-  if ! grep -q '\- \[x\]' "$tasks"; then
-    echo "tasks.md has no completed tasks." >&2
-    echo "Next: complete implementation tasks and mark them with '- [x]'." >&2
-    return 1
-  fi
-  if grep -q '\- \[ \]' "$tasks"; then
-    echo "Unfinished tasks:" >&2
-    grep -n '\- \[ \]' "$tasks" >&2 || true
-    echo "Next: complete or explicitly remove unfinished tasks, then mark tasks.md with '- [x]'." >&2
-    return 1
-  fi
-  return 0
-}
-
-tasks_has_any() {
-  local tasks="$CHANGE_DIR/tasks.md"
-  [ -f "$tasks" ] && grep -q '\- \[' "$tasks"
-}
-
-yaml_field_value() {
-  local field="$1"
-  local yaml="$CHANGE_DIR/.comet.yaml"
-  if [ -f "$yaml" ]; then
-    local value
-    value=$(grep "^${field}:" "$yaml" 2>/dev/null | sed "s/^${field}: *//" || true)
-    value=$(strip_inline_comment "$value")
-    strip_wrapping_quotes "$value"
-  fi
-}
-
-strip_inline_comment() {
-  local value="$1"
-  printf '%s\n' "$value" | awk -v squote="'" '
-    {
-      out = ""
-      quote = ""
-      for (i = 1; i <= length($0); i++) {
-        c = substr($0, i, 1)
-        if (quote == "") {
-          if (c == "\"" || c == squote) {
-            quote = c
-          } else if (c == "#" && (i == 1 || substr($0, i - 1, 1) ~ /[[:space:]]/)) {
-            sub(/[[:space:]]+$/, "", out)
-            print out
-            next
-          }
-        } else if (c == quote) {
-          quote = ""
-        }
-        out = out c
-      }
-      print out
-    }
-  '
-}
-
-strip_wrapping_quotes() {
-  local value="$1"
-  case "$value" in
-    \"*\")
-      printf '%s\n' "${value:1:${#value}-2}"
-      ;;
-    \'*\')
-      printf '%s\n' "${value:1:${#value}-2}"
-      ;;
-    *)
-      printf '%s\n' "$value"
-      ;;
-  esac
-}
-
-project_config_value() {
-  local field="$1"
-  local value
-
-  value=$(yaml_field_value "$field" 2>/dev/null || true)
-  if [ -n "$value" ] && [ "$value" != "null" ]; then
-    echo "$value"
-    return 0
-  fi
-
-  for config in ".comet.yaml" "comet.yaml" ".comet.yml" "comet.yml"; do
-    if [ -f "$config" ]; then
-      value=$(grep "^${field}:" "$config" 2>/dev/null | sed "s/^${field}: *//" || true)
-      value=$(strip_inline_comment "$value")
-      value=$(strip_wrapping_quotes "$value")
-      if [ -n "$value" ] && [ "$value" != "null" ]; then
-        echo "$value"
-        return 0
-      fi
-    fi
-  done
-}
-
-file_nonempty() {
-  [ -f "$1" ] && [ -s "$1" ]
-}
-
-is_windows_bash() {
-  case "$(uname -s 2>/dev/null || true)" in
-    MINGW*|MSYS*|CYGWIN*) return 0 ;;
-    *) return 1 ;;
-  esac
-}
-
-run_command_string() {
-  local command="$1"
-  echo "+ $command" >&2
-  "$COMET_BASH" -lc "$command"
-}
-
-hash_stream() {
-  if command -v sha256sum >/dev/null 2>&1; then
-    sha256sum | awk '{print $1}'
-  elif command -v shasum >/dev/null 2>&1; then
-    shasum -a 256 | awk '{print $1}'
-  else
-    echo "sha256sum or shasum is required" >&2
-    return 1
-  fi
-}
-
-hash_file() {
-  local file="$1"
-  if command -v sha256sum >/dev/null 2>&1; then
-    sha256sum "$file" | awk '{print $1}'
-  elif command -v shasum >/dev/null 2>&1; then
-    shasum -a 256 "$file" | awk '{print $1}'
-  else
-    echo "sha256sum or shasum is required" >&2
-    return 1
-  fi
-}
-
-handoff_source_files() {
-  printf '%s\n' "$CHANGE_DIR/proposal.md"
-  printf '%s\n' "$CHANGE_DIR/design.md"
-  printf '%s\n' "$CHANGE_DIR/tasks.md"
-  if [ -d "$CHANGE_DIR/specs" ]; then
-    find "$CHANGE_DIR/specs" -path '*/spec.md' -type f 2>/dev/null | sort
-  fi
-}
-
-compute_handoff_hash() {
-  handoff_source_files | while IFS= read -r file; do
-    if [ -f "$file" ]; then
-      printf 'path:%s\n' "$file"
-      printf 'sha256:%s\n' "$(hash_file "$file")"
-    fi
-  done | hash_stream
-}
-
-preflight() {
-
-  if [ ! -d "$CHANGE_DIR" ]; then
-    red "FATAL: change directory not found: $CHANGE_DIR"
-    exit 1
-  fi
-  if [ ! -f "$CHANGE_DIR/.comet.yaml" ]; then
-    red "FATAL: .comet.yaml not found in $CHANGE_DIR"
-    exit 1
-  fi
-
-  # Schema validation
-  local validate_script
-  validate_script="$SCRIPT_DIR/comet-yaml-validate.sh"
-  if [ -f "$validate_script" ]; then
-    if ! "$COMET_BASH" "$validate_script" "$CHANGE" 2>/dev/null; then
-      "$COMET_BASH" "$validate_script" "$CHANGE" || true
-      red "FATAL: .comet.yaml schema validation failed"
-      exit 1
-    fi
-  fi
-}
-
-build_passes() {
-  if [ "${COMET_SKIP_BUILD:-0}" = "1" ]; then
-    return 0
-  fi
-  local configured_build
-  configured_build=$(project_config_value "build_command" 2>/dev/null || true)
-  if [ -n "$configured_build" ]; then
-    run_command_string "$configured_build"
-    return $?
-  fi
-  if [ -f "package.json" ] && grep -q '"build"' "package.json"; then
-    npm run build
-    return $?
-  fi
-  if [ -f "pom.xml" ]; then
-    if [ -x "./mvnw" ]; then
-      ./mvnw compile -q
-    elif is_windows_bash && command -v mvn.cmd >/dev/null 2>&1; then
-      mvn.cmd compile -q
-    else
-      mvn compile -q
-    fi
-    return $?
-  fi
-  if [ -f "Cargo.toml" ]; then
-    cargo build
-    return $?
-  fi
-  return 1
-}
-
-verification_command_passes() {
-  if [ "${COMET_SKIP_BUILD:-0}" = "1" ]; then
-    return 0
-  fi
-  local configured_verify
-  configured_verify=$(project_config_value "verify_command" 2>/dev/null || true)
-  if [ -n "$configured_verify" ]; then
-    run_command_string "$configured_verify"
-    return $?
-  fi
-  build_passes
-}
-
-isolation_selected() {
-  local isolation
-  isolation=$(yaml_field_value "isolation" 2>/dev/null || true)
-  case "$isolation" in
-    branch|worktree) return 0 ;;
-    *)
-      echo "isolation must be branch or worktree, got '${isolation:-null}'" >&2
-      echo "Next: ask the user to choose branch or worktree, create the chosen isolation, then run:" >&2
-      echo "  \"\$COMET_BASH\" \"\$COMET_STATE\" set $CHANGE isolation <branch|worktree>" >&2
-      return 1
-      ;;
-  esac
-}
-
-build_mode_selected() {
-  local build_mode
-  build_mode=$(yaml_field_value "build_mode" 2>/dev/null || true)
-  case "$build_mode" in
-    subagent-driven-development|executing-plans|direct) return 0 ;;
-    *)
-      echo "build_mode must be selected before leaving build, got '${build_mode:-null}'" >&2
-      echo "Next: ask the user to choose an execution mode, then run:" >&2
-      echo "  \"\$COMET_BASH\" \"\$COMET_STATE\" set $CHANGE build_mode <subagent-driven-development|executing-plans>" >&2
-      return 1
-      ;;
-  esac
-}
-
-build_mode_allowed_for_workflow() {
-  local workflow build_mode direct_override
-  workflow=$(yaml_field_value "workflow" 2>/dev/null || true)
-  build_mode=$(yaml_field_value "build_mode" 2>/dev/null || true)
-  direct_override=$(yaml_field_value "direct_override" 2>/dev/null || true)
-
-  if [ "$build_mode" != "direct" ]; then
-    return 0
-  fi
-  case "$workflow" in
-    hotfix|tweak) return 0 ;;
-    *)
-      if [ "$direct_override" = "true" ]; then
-        return 0
-      fi
-      echo "build_mode=direct is only allowed for hotfix/tweak unless direct_override: true is recorded" >&2
-      echo "Next: choose executing-plans or subagent-driven-development, or stop and ask the user for an explicit direct override." >&2
-      return 1
-      ;;
-  esac
-}
-
-verify_result_is_pass() {
-  local result
-  result=$(yaml_field_value "verify_result" 2>/dev/null || true)
-  [ "$result" = "pass" ]
-}
-
-verification_report_exists() {
-  local report
-  report=$(yaml_field_value "verification_report" 2>/dev/null || true)
-  [ -n "$report" ] && [ "$report" != "null" ] && [ -f "$report" ]
-}
-
-branch_status_handled() {
-  local status
-  status=$(yaml_field_value "branch_status" 2>/dev/null || true)
-  [ "$status" = "handled" ]
-}
-
-design_handoff_context_valid() {
-  local context recorded_hash actual_hash markdown
-  context=$(yaml_field_value "handoff_context" 2>/dev/null || true)
-  recorded_hash=$(yaml_field_value "handoff_hash" 2>/dev/null || true)
-
-  if [ -z "$context" ] || [ "$context" = "null" ]; then
-    echo "handoff_context is missing from .comet.yaml" >&2
-    echo "Next: run \"\$COMET_BASH\" \"\$COMET_HANDOFF\" $CHANGE design --write before invoking Superpowers." >&2
-    return 1
-  fi
-  if [ ! -s "$context" ]; then
-    echo "handoff_context does not point to a non-empty file: $context" >&2
-    echo "Next: regenerate the design handoff with comet-handoff.sh." >&2
-    return 1
-  fi
-  if [[ ! "$recorded_hash" =~ ^[a-f0-9]{64}$ ]]; then
-    echo "handoff_hash is missing or invalid: ${recorded_hash:-null}" >&2
-    echo "Next: regenerate the design handoff with comet-handoff.sh." >&2
-    return 1
-  fi
-
-  actual_hash=$(compute_handoff_hash)
-  if [ "$actual_hash" != "$recorded_hash" ]; then
-    echo "OpenSpec artifacts changed after handoff was generated." >&2
-    echo "Expected handoff_hash: $recorded_hash" >&2
-    echo "Actual handoff_hash:   $actual_hash" >&2
-    echo "Next: rerun comet-handoff.sh so Superpowers receives the current OpenSpec context." >&2
-    return 1
-  fi
-
-  markdown="${context%.json}.md"
-  if [ ! -s "$markdown" ]; then
-    echo "design handoff markdown is missing or empty: $markdown" >&2
-    echo "Next: regenerate the design handoff with comet-handoff.sh." >&2
-    return 1
-  fi
-}
-
-design_handoff_markdown_traceable() {
-  local context markdown missing=0
-  context=$(yaml_field_value "handoff_context" 2>/dev/null || true)
-  if [ -z "$context" ] || [ "$context" = "null" ]; then
-    echo "handoff_context is missing from .comet.yaml" >&2
-    return 1
-  fi
-  markdown="${context%.json}.md"
-  if [ ! -s "$markdown" ]; then
-    echo "design handoff markdown is missing or empty: $markdown" >&2
-    return 1
-  fi
-  grep -q '^Generated-by: comet-handoff\.sh$' "$markdown" || {
-    echo "handoff markdown is missing Generated-by marker" >&2
-    missing=1
-  }
-  grep -Eq '^- Mode: (compact|full)$' "$markdown" || {
-    echo "handoff markdown is missing Mode marker" >&2
-    missing=1
-  }
-  handoff_source_files | while IFS= read -r file; do
-    [ -f "$file" ] || continue
-    if ! grep -q "^- Source: $file$" "$markdown"; then
-      echo "handoff markdown is missing source reference: $file" >&2
-      exit 2
-    fi
-    if ! grep -q "^- SHA256: $(hash_file "$file")$" "$markdown"; then
-      echo "handoff markdown is missing current sha256 for: $file" >&2
-      exit 2
-    fi
-  done || missing=1
-
-  [ "$missing" -eq 0 ]
-}
-
-design_doc_frontmatter_has() {
-  local design_doc="$1"
-  local field="$2"
-  local expected="$3"
-  awk '
-    {
-      line = $0
-      sub(/^\357\273\277/, "", line)
-    }
-    !in_fm && line == "---" { in_fm = 1; next }
-    in_fm && line == "---" { exit }
-    in_fm { print line }
-  ' "$design_doc" | grep -Eq "^${field}: ['\"]?${expected}['\"]?[[:space:]]*$"
-}
-
-design_doc_links_current_change() {
-  local design_doc
-  design_doc=$(yaml_field_value "design_doc" 2>/dev/null || true)
-  if [ -z "$design_doc" ] || [ "$design_doc" = "null" ] || [ ! -s "$design_doc" ]; then
-    echo "design_doc must point to an existing Superpowers Design Doc before leaving design." >&2
-    return 1
-  fi
-  design_doc_frontmatter_has "$design_doc" "comet_change" "$CHANGE"
-}
-
-design_doc_declares_technical_role() {
-  local design_doc
-  design_doc=$(yaml_field_value "design_doc" 2>/dev/null || true)
-  [ -n "$design_doc" ] && [ "$design_doc" != "null" ] && [ -s "$design_doc" ] &&
-    design_doc_frontmatter_has "$design_doc" "role" "technical-design"
-}
-
-design_doc_declares_canonical_spec() {
-  local design_doc
-  design_doc=$(yaml_field_value "design_doc" 2>/dev/null || true)
-  [ -n "$design_doc" ] && [ "$design_doc" != "null" ] && [ -s "$design_doc" ] &&
-    design_doc_frontmatter_has "$design_doc" "canonical_spec" "openspec"
-}
-
-archived_is_true() {
-  local val
-  val=$(yaml_field_value "archived" 2>/dev/null || true)
-  [ "$val" = "true" ]
-}
-
-# --- Phase-specific checks ---
-
-guard_open() {
-  echo "=== Guard: open → next ===" >&2
-
-  check "proposal.md exists and non-empty" file_nonempty "$CHANGE_DIR/proposal.md"
-  check "design.md exists and non-empty" file_nonempty "$CHANGE_DIR/design.md"
-  check "tasks.md exists and non-empty" file_nonempty "$CHANGE_DIR/tasks.md"
-  check "tasks.md has at least one task" tasks_has_any
-}
-
-guard_design() {
-  echo "=== Guard: design → build ===" >&2
-
-  local design_doc
-  design_doc=$(yaml_field_value "design_doc" 2>/dev/null || true)
-
-  check "proposal.md exists" file_nonempty "$CHANGE_DIR/proposal.md"
-  check "design.md exists" file_nonempty "$CHANGE_DIR/design.md"
-  check "tasks.md exists" file_nonempty "$CHANGE_DIR/tasks.md"
-  check "design handoff context exists" design_handoff_context_valid
-  check "design handoff markdown is traceable" design_handoff_markdown_traceable
-
-  if [ -n "$design_doc" ] && [ "$design_doc" != "null" ]; then
-    check "Design Doc ($design_doc) exists" file_nonempty "$design_doc"
-    check "Design Doc frontmatter links current change" design_doc_links_current_change
-    check "Design Doc declares technical design role" design_doc_declares_technical_role
-    check "Design Doc declares OpenSpec as canonical spec" design_doc_declares_canonical_spec
-  else
-    warn "  [WARN] No design_doc recorded in .comet.yaml"
-  fi
-}
-
-guard_build() {
-  echo "=== Guard: build → verify ===" >&2
-
-  check "isolation selected" isolation_selected
-  check "build_mode selected" build_mode_selected
-  check "build_mode allowed for workflow" build_mode_allowed_for_workflow
-  check "tasks.md all tasks checked" tasks_all_done
-  check "proposal.md exists" file_nonempty "$CHANGE_DIR/proposal.md"
-  check "Build passes" build_passes
-}
-
-guard_verify() {
-  echo "=== Guard: verify → archive ===" >&2
-
-  check "tasks.md all tasks checked" tasks_all_done
-  check "Build passes" verification_command_passes
-  check "verification_report exists" verification_report_exists
-  check "branch_status=handled" branch_status_handled
-}
-
-guard_archive() {
-  echo "=== Guard: archive completeness ===" >&2
-
-  check "archived is true" archived_is_true
-  check "proposal.md exists" file_nonempty "$CHANGE_DIR/proposal.md"
-  check "tasks.md all tasks checked" tasks_all_done
-}
-
-apply_state_update() {
-  local state_sh="$SCRIPT_DIR/comet-state.sh"
-  local p="$1"
-
-  if [ -f "$state_sh" ]; then
-    case "$p" in
-      open)   "$COMET_BASH" "$state_sh" transition "$CHANGE" open-complete ;;
-      design) "$COMET_BASH" "$state_sh" transition "$CHANGE" design-complete ;;
-      build)  "$COMET_BASH" "$state_sh" transition "$CHANGE" build-complete ;;
-      verify) "$COMET_BASH" "$state_sh" transition "$CHANGE" verify-pass ;;
-    esac
-  else
-    red "FATAL: comet-state.sh not found; cannot apply state transition"
-    exit 1
-  fi
-}
-
-# --- Main ---
-
-case "$PHASE" in
-  open)     preflight ; guard_open ;;
-  design)   preflight ; guard_design ;;
-  build)    preflight ; guard_build ;;
-  verify)   preflight ; guard_verify ;;
-  archive)  preflight ; guard_archive ;;
-  *)
-    red "Unknown phase: $PHASE"
-    echo "Valid phases: open, design, build, verify, archive" >&2
-    exit 1
-    ;;
-esac
-
-if [ "$BLOCK" -eq 1 ]; then
-  echo "" >&2
-  red "BLOCKED — fix failing checks before proceeding to next phase"
-  exit 1
-else
-  echo "" >&2
-  green "ALL CHECKS PASSED — ready for next phase"
-  if [ "$APPLY" -eq 1 ]; then
-    apply_state_update "$PHASE"
-    case "$PHASE" in
-      open)
-        new_phase=$(yaml_field_value "phase")
-        green "  [APPLY] .comet.yaml updated: phase=$new_phase"
-        ;;
-      design) green "  [APPLY] .comet.yaml updated: phase=build" ;;
-      build)  green "  [APPLY] .comet.yaml updated: phase=verify, verify_result=pending" ;;
-      verify) green "  [APPLY] .comet.yaml updated: phase=archive, verify_result=pass" ;;
-    esac
-  fi
-  exit 0
-fi
diff --git a/assets/skills/comet/scripts/comet-handoff.js b/assets/skills/comet/scripts/comet-handoff.js
new file mode 100644
index 00000000..49a6514a
--- /dev/null
+++ b/assets/skills/comet/scripts/comet-handoff.js
@@ -0,0 +1,109 @@
+#!/usr/bin/env node
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { ensureDir, fieldValue, fileNonempty, green, hashFile, runNode, scriptDir, sha256, slash, validateChangeName } from './comet-lib.js';
+
+function error(message) {
+  console.error(`\u001b[31m${message}\u001b[0m`);
+  process.exit(1);
+}
+
+function walkSpecFiles(dir) {
+  if (!existsSync(dir)) return [];
+  const { readdirSync, statSync } = awaitFs;
+  const out = [];
+  function walk(current) {
+    for (const entry of readdirSync(current)) {
+      const p = join(current, entry);
+      const stat = statSync(p);
+      if (stat.isDirectory()) walk(p);
+      else if (entry === 'spec.md') out.push(p);
+    }
+  }
+  walk(dir);
+  return out.sort();
+}
+
+import * as awaitFs from 'node:fs';
+
+function sourceFiles(changeDir) {
+  return [join(changeDir, 'proposal.md'), join(changeDir, 'design.md'), join(changeDir, 'tasks.md'), ...walkSpecFiles(join(changeDir, 'specs'))];
+}
+
+function computeContextHash(files) {
+  let content = '';
+  for (const file of files) {
+    if (!existsSync(file)) continue;
+    content += `path:${slash(file)}\nsha256:${hashFile(file)}\n`;
+  }
+  return sha256(content);
+}
+
+function writeMarkdown(output, files, change, mode, contextHash) {
+  const chunks = [
+    '# Comet Design Handoff',
+    '',
+    `- Change: ${change}`,
+    '- Phase: design',
+    `- Mode: ${mode}`,
+    `- Context hash: ${contextHash}`,
+    '',
+    'Generated-by: comet-handoff.js',
+    '',
+    'OpenSpec remains the canonical capability spec. This handoff is a deterministic, source-traceable context pack, not an agent-authored summary.',
+    '',
+  ];
+  for (const file of files) {
+    if (!existsSync(file)) continue;
+    const text = readFileSync(file, 'utf8');
+    const lines = text.split(/\r?\n/);
+    chunks.push(`## ${slash(file)}`, '', `- Source: ${slash(file)}`, `- Lines: 1-${lines.length}`, `- SHA256: ${hashFile(file)}`, '');
+    if (mode === 'full' || lines.length <= 80) chunks.push('```md', text.replace(/\s*$/, ''), '```');
+    else chunks.push('[TRUNCATED]', '', '```md', lines.slice(0, 80).join('\n'), '```', '', `Full source: ${slash(file)}`);
+    chunks.push('');
+  }
+  writeFileSync(output, `${chunks.join('\n')}\n`);
+}
+
+function writeJson(output, files, change, mode, contextHash) {
+  const body = {
+    change,
+    phase: 'design',
+    mode,
+    canonical_spec: 'openspec',
+    generated_by: 'comet-handoff.js',
+    context_hash: contextHash,
+    files: files.filter((file) => existsSync(file)).map((file) => ({ path: slash(file), sha256: hashFile(file) })),
+  };
+  writeFileSync(output, `${JSON.stringify(body, null, 2)}\n`);
+}
+
+const [change, phase, modeArg, fullFlag] = process.argv.slice(2);
+validateChangeName(change);
+if (phase !== 'design' || modeArg !== '--write' || (fullFlag && fullFlag !== '--full')) error('Usage: comet-handoff.js <change-name> design --write [--full]');
+const handoffMode = fullFlag === '--full' ? 'full' : 'compact';
+const changeDir = join('openspec', 'changes', change);
+const yaml = join(changeDir, '.comet.yaml');
+if (!existsSync(changeDir)) error(`ERROR: change directory not found: ${changeDir}`);
+if (!existsSync(yaml)) error(`ERROR: .comet.yaml not found at ${yaml}`);
+if (fieldValue(yaml, 'phase') !== 'design') error('ERROR: design handoff requires phase: design');
+for (const required of ['proposal.md', 'design.md', 'tasks.md']) {
+  if (!fileNonempty(join(changeDir, required))) error(`ERROR: required OpenSpec artifact missing or empty: ${join(changeDir, required)}`);
+}
+const handoffDir = join(changeDir, '.comet', 'handoff');
+const contextJson = slash(join(handoffDir, 'design-context.json'));
+const contextMd = slash(join(handoffDir, 'design-context.md'));
+ensureDir(handoffDir);
+const files = sourceFiles(changeDir);
+const contextHash = computeContextHash(files);
+writeMarkdown(contextMd, files, change, handoffMode, contextHash);
+writeJson(contextJson, files, change, handoffMode, contextHash);
+const stateScript = join(scriptDir, 'comet-state.js');
+if (!existsSync(stateScript)) error('ERROR: comet-state.js not found; cannot record handoff fields');
+let result = runNode(stateScript, ['set', change, 'handoff_context', contextJson]);
+if (result.status !== 0) process.exit(result.status ?? 1);
+result = runNode(stateScript, ['set', change, 'handoff_hash', contextHash]);
+if (result.status !== 0) process.exit(result.status ?? 1);
+green(`[HANDOFF] wrote ${contextJson}`);
+green(`[HANDOFF] wrote ${contextMd}`);
+green(`[HANDOFF] handoff_hash=${contextHash}`);
diff --git a/assets/skills/comet/scripts/comet-handoff.sh b/assets/skills/comet/scripts/comet-handoff.sh
deleted file mode 100644
index b2ee6739..00000000
--- a/assets/skills/comet/scripts/comet-handoff.sh
+++ /dev/null
@@ -1,263 +0,0 @@
-#!/bin/bash
-# Comet Handoff — creates machine-owned context packages between phases
-# Usage: comet-handoff.sh <change-name> design --write [--full]
-
-set -euo pipefail
-
-COMET_BASH="${COMET_BASH:-${BASH:-bash}}"
-
-red() { echo -e "\033[31m$1\033[0m" >&2; }
-green() { echo -e "\033[32m$1\033[0m" >&2; }
-
-validate_change_name() {
-  local name="$1"
-  if [ -z "$name" ]; then
-    red "ERROR: Change name cannot be empty"
-    exit 1
-  fi
-  if [[ ! "$name" =~ ^[a-zA-Z0-9_-]+$ ]]; then
-    red "ERROR: Invalid change name: '$name'"
-    red "Valid characters: a-z, A-Z, 0-9, -, _"
-    exit 1
-  fi
-  if [[ "$name" =~ \.\. ]]; then
-    red "ERROR: Change name cannot contain '..' (path traversal not allowed)"
-    exit 1
-  fi
-}
-
-strip_wrapping_quotes() {
-  local value="$1"
-  case "$value" in
-    \"*\") printf '%s\n' "${value:1:${#value}-2}" ;;
-    \'*\') printf '%s\n' "${value:1:${#value}-2}" ;;
-    *) printf '%s\n' "$value" ;;
-  esac
-}
-
-strip_inline_comment() {
-  local value="$1"
-  printf '%s\n' "$value" | awk -v squote="'" '
-    {
-      out = ""
-      quote = ""
-      for (i = 1; i <= length($0); i++) {
-        c = substr($0, i, 1)
-        if (quote == "") {
-          if (c == "\"" || c == squote) {
-            quote = c
-          } else if (c == "#" && (i == 1 || substr($0, i - 1, 1) ~ /[[:space:]]/)) {
-            sub(/[[:space:]]+$/, "", out)
-            print out
-            next
-          }
-        } else if (c == quote) {
-          quote = ""
-        }
-        out = out c
-      }
-      print out
-    }
-  '
-}
-
-yaml_field_value() {
-  local field="$1"
-  local yaml="$CHANGE_DIR/.comet.yaml"
-  local value
-  value=$(grep "^${field}:" "$yaml" 2>/dev/null | sed "s/^${field}: *//" || true)
-  value=$(strip_inline_comment "$value")
-  strip_wrapping_quotes "$value"
-}
-
-hash_stream() {
-  if command -v sha256sum >/dev/null 2>&1; then
-    sha256sum | awk '{print $1}'
-  elif command -v shasum >/dev/null 2>&1; then
-    shasum -a 256 | awk '{print $1}'
-  else
-    red "ERROR: sha256sum or shasum is required"
-    exit 1
-  fi
-}
-
-hash_file() {
-  local file="$1"
-  if command -v sha256sum >/dev/null 2>&1; then
-    sha256sum "$file" | awk '{print $1}'
-  elif command -v shasum >/dev/null 2>&1; then
-    shasum -a 256 "$file" | awk '{print $1}'
-  else
-    red "ERROR: sha256sum or shasum is required"
-    exit 1
-  fi
-}
-
-source_files() {
-  printf '%s\n' "$CHANGE_DIR/proposal.md"
-  printf '%s\n' "$CHANGE_DIR/design.md"
-  printf '%s\n' "$CHANGE_DIR/tasks.md"
-  if [ -d "$CHANGE_DIR/specs" ]; then
-    find "$CHANGE_DIR/specs" -path '*/spec.md' -type f 2>/dev/null | sort
-  fi
-}
-
-compute_context_hash() {
-  source_files | while IFS= read -r file; do
-    if [ -f "$file" ]; then
-      printf 'path:%s\n' "$file"
-      printf 'sha256:%s\n' "$(hash_file "$file")"
-    fi
-  done | hash_stream
-}
-
-json_escape() {
-  printf '%s' "$1" | sed 's/\\/\\\\/g; s/"/\\"/g'
-}
-
-file_line_count() {
-  local file="$1"
-  wc -l < "$file" | tr -d ' '
-}
-
-write_file_excerpt() {
-  local file="$1"
-  local max_lines="$2"
-  local total_lines
-  total_lines=$(file_line_count "$file")
-
-  echo "## $file"
-  echo ""
-  echo "- Source: $file"
-  echo "- Lines: 1-$total_lines"
-  echo "- SHA256: $(hash_file "$file")"
-  echo ""
-
-  if [ "$HANDOFF_MODE" = "full" ] || [ "$total_lines" -le "$max_lines" ]; then
-    echo '```md'
-    cat "$file"
-    echo '```'
-  else
-    echo "[TRUNCATED]"
-    echo ""
-    echo '```md'
-    sed -n "1,${max_lines}p" "$file"
-    echo '```'
-    echo ""
-    echo "Full source: $file"
-  fi
-  echo ""
-}
-
-write_markdown_context() {
-  local output="$1"
-  {
-    echo "# Comet Design Handoff"
-    echo ""
-    echo "- Change: $CHANGE"
-    echo "- Phase: design"
-    echo "- Mode: $HANDOFF_MODE"
-    echo "- Context hash: $CONTEXT_HASH"
-    echo ""
-    echo "Generated-by: comet-handoff.sh"
-    echo ""
-    echo "OpenSpec remains the canonical capability spec. This handoff is a deterministic, source-traceable context pack, not an agent-authored summary."
-    echo ""
-    source_files | while IFS= read -r file; do
-      [ -f "$file" ] || continue
-      write_file_excerpt "$file" 80
-    done
-  } > "$output"
-}
-
-write_json_context() {
-  local output="$1"
-  {
-    echo "{"
-    echo "  \"change\": \"$(json_escape "$CHANGE")\","
-    echo "  \"phase\": \"design\","
-    echo "  \"mode\": \"$HANDOFF_MODE\","
-    echo "  \"canonical_spec\": \"openspec\","
-    echo "  \"generated_by\": \"comet-handoff.sh\","
-    echo "  \"context_hash\": \"$CONTEXT_HASH\","
-    echo "  \"files\": ["
-    local first=1
-    while IFS= read -r file; do
-      [ -f "$file" ] || continue
-      if [ "$first" -eq 0 ]; then
-        echo ","
-      fi
-      first=0
-      printf '    { "path": "%s", "sha256": "%s" }' "$(json_escape "$file")" "$(hash_file "$file")"
-    done < <(source_files)
-    echo ""
-    echo "  ]"
-    echo "}"
-  } > "$output"
-}
-
-CHANGE="${1:-}"
-PHASE="${2:-}"
-MODE="${3:-}"
-FULL_FLAG="${4:-}"
-
-validate_change_name "$CHANGE"
-
-if [ "$PHASE" != "design" ] || [ "$MODE" != "--write" ]; then
-  red "Usage: comet-handoff.sh <change-name> design --write [--full]"
-  exit 1
-fi
-case "$FULL_FLAG" in
-  "") HANDOFF_MODE="compact" ;;
-  --full) HANDOFF_MODE="full" ;;
-  *)
-    red "Usage: comet-handoff.sh <change-name> design --write [--full]"
-    exit 1
-    ;;
-esac
-
-CHANGE_DIR="openspec/changes/$CHANGE"
-YAML="$CHANGE_DIR/.comet.yaml"
-SCRIPT_DIR="$(dirname "$(readlink -f "$0" 2>/dev/null || echo "$0")" 2>/dev/null || dirname "$0")"
-STATE_SH="$SCRIPT_DIR/comet-state.sh"
-
-if [ ! -d "$CHANGE_DIR" ]; then
-  red "ERROR: change directory not found: $CHANGE_DIR"
-  exit 1
-fi
-if [ ! -f "$YAML" ]; then
-  red "ERROR: .comet.yaml not found at $YAML"
-  exit 1
-fi
-if [ "$(yaml_field_value phase)" != "design" ]; then
-  red "ERROR: design handoff requires phase: design"
-  exit 1
-fi
-
-for required in proposal.md design.md tasks.md; do
-  if [ ! -s "$CHANGE_DIR/$required" ]; then
-    red "ERROR: required OpenSpec artifact missing or empty: $CHANGE_DIR/$required"
-    exit 1
-  fi
-done
-
-HANDOFF_DIR="$CHANGE_DIR/.comet/handoff"
-CONTEXT_JSON="$HANDOFF_DIR/design-context.json"
-CONTEXT_MD="$HANDOFF_DIR/design-context.md"
-mkdir -p "$HANDOFF_DIR"
-
-CONTEXT_HASH="$(compute_context_hash)"
-write_markdown_context "$CONTEXT_MD"
-write_json_context "$CONTEXT_JSON"
-
-if [ -x "$STATE_SH" ] || [ -f "$STATE_SH" ]; then
-  "$COMET_BASH" "$STATE_SH" set "$CHANGE" handoff_context "$CONTEXT_JSON" >/dev/null
-  "$COMET_BASH" "$STATE_SH" set "$CHANGE" handoff_hash "$CONTEXT_HASH" >/dev/null
-else
-  red "ERROR: comet-state.sh not found; cannot record handoff fields"
-  exit 1
-fi
-
-green "[HANDOFF] wrote $CONTEXT_JSON"
-green "[HANDOFF] wrote $CONTEXT_MD"
-green "[HANDOFF] handoff_hash=$CONTEXT_HASH"
diff --git a/assets/skills/comet/scripts/comet-lib.js b/assets/skills/comet/scripts/comet-lib.js
new file mode 100644
index 00000000..f2267e5d
--- /dev/null
+++ b/assets/skills/comet/scripts/comet-lib.js
@@ -0,0 +1,212 @@
+#!/usr/bin/env node
+import { createHash } from 'node:crypto';
+import { existsSync, mkdirSync, readFileSync, statSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { spawnSync } from 'node:child_process';
+
+export const scriptDir = dirname(fileURLToPath(import.meta.url));
+
+export const FIELD_ORDER = [
+  'workflow',
+  'phase',
+  'build_mode',
+  'build_pause',
+  'isolation',
+  'verify_mode',
+  'base_ref',
+  'design_doc',
+  'plan',
+  'verify_result',
+  'verification_report',
+  'branch_status',
+  'created_at',
+  'verified_at',
+  'archived',
+  'direct_override',
+  'build_command',
+  'verify_command',
+  'handoff_context',
+  'handoff_hash',
+];
+
+export const KNOWN_KEYS = new Set(FIELD_ORDER);
+
+export function color(code, message) {
+  return `\u001b[${code}m${message}\u001b[0m`;
+}
+
+export function red(message) {
+  console.error(color(31, message));
+}
+
+export function green(message) {
+  console.error(color(32, message));
+}
+
+export function yellow(message) {
+  console.error(color(33, message));
+}
+
+export function fail(message, prefix = 'ERROR') {
+  red(`${prefix}: ${message}`);
+  process.exit(1);
+}
+
+export function validateChangeName(name, prefix = 'ERROR') {
+  if (!name) fail('Change name cannot be empty', prefix);
+  if (!/^[a-zA-Z0-9_-]+$/.test(name)) {
+    red(`${prefix}: Invalid change name: '${name}'`);
+    red('Valid characters: a-z, A-Z, 0-9, -, _');
+    process.exit(1);
+  }
+  if (name.includes('..')) fail("Change name cannot contain '..' (path traversal not allowed)", prefix);
+}
+
+export function validateEnum(value, validValues) {
+  if (validValues.includes(value)) return;
+  red(`ERROR: Invalid value: '${value}'`);
+  red(`Valid values: ${validValues.join(' ')}`);
+  process.exit(1);
+}
+
+export function stripInlineComment(value) {
+  let out = '';
+  let quote = '';
+  for (let i = 0; i < value.length; i += 1) {
+    const c = value[i];
+    if (!quote) {
+      if (c === '"' || c === "'") quote = c;
+      else if (c === '#' && (i === 0 || /\s/.test(value[i - 1]))) return out.trimEnd();
+    } else if (c === quote) {
+      quote = '';
+    }
+    out += c;
+  }
+  return out;
+}
+
+export function stripWrappingQuotes(value) {
+  if (value.length >= 2) {
+    const first = value[0];
+    const last = value[value.length - 1];
+    if (first === '"' && last === '"') {
+      try {
+        return JSON.parse(value);
+      } catch {
+        return value.slice(1, -1);
+      }
+    }
+    if (first === "'" && last === "'") return value.slice(1, -1);
+  }
+  return value;
+}
+
+export function parseYamlLines(file) {
+  const text = readFileSync(file, 'utf8');
+  const data = {};
+  const keys = [];
+  for (const line of text.split(/\r?\n/)) {
+    const match = line.match(/^([^\s:#][^:]*):\s*(.*)$/);
+    if (!match) continue;
+    const key = match[1].trim();
+    const value = stripWrappingQuotes(stripInlineComment(match[2] ?? ''));
+    data[key] = value;
+    keys.push(key);
+  }
+  return { data, keys, text };
+}
+
+export function fieldValue(file, field) {
+  if (!existsSync(file)) return '';
+  return parseYamlLines(file).data[field] ?? '';
+}
+
+function formatYamlValue(value) {
+  const stringValue = String(value);
+  if (stringValue === '') return '';
+  if (/^[A-Za-z0-9_./:@\\-]+$/.test(stringValue)) return stringValue;
+  return JSON.stringify(stringValue);
+}
+
+export function writeYamlData(file, data) {
+  const lines = [];
+  for (const key of FIELD_ORDER) {
+    if (Object.prototype.hasOwnProperty.call(data, key)) lines.push(`${key}: ${formatYamlValue(data[key])}`);
+  }
+  for (const key of Object.keys(data)) {
+    if (!FIELD_ORDER.includes(key)) lines.push(`${key}: ${formatYamlValue(data[key])}`);
+  }
+  writeFileSync(file, `${lines.join('\n')}\n`);
+}
+
+export function setYamlField(file, field, value) {
+  const { data } = parseYamlLines(file);
+  data[field] = String(value);
+  writeYamlData(file, data);
+}
+
+export function fileNonempty(file) {
+  try {
+    return statSync(file).isFile() && statSync(file).size > 0;
+  } catch {
+    return false;
+  }
+}
+
+export function changeDirFor(changeName) {
+  const active = join('openspec', 'changes', changeName);
+  const archived = join('openspec', 'changes', 'archive', changeName);
+  if (existsSync(active)) return active;
+  if (existsSync(archived)) return archived;
+  return active;
+}
+
+export function yamlFileFor(changeName) {
+  return join(changeDirFor(changeName), '.comet.yaml');
+}
+
+export function today() {
+  return new Date().toISOString().slice(0, 10);
+}
+
+export function git(args) {
+  return spawnSync('git', args, { encoding: 'utf8' });
+}
+
+export function currentHeadOrNull() {
+  const verify = git(['rev-parse', '--verify', 'HEAD']);
+  if (verify.status !== 0) return 'null';
+  const head = git(['rev-parse', 'HEAD']);
+  return head.status === 0 ? head.stdout.trim() : 'null';
+}
+
+export function sha256(content) {
+  return createHash('sha256').update(content).digest('hex');
+}
+
+export function hashFile(file) {
+  return sha256(readFileSync(file));
+}
+
+export function ensureDir(dir) {
+  mkdirSync(dir, { recursive: true });
+}
+
+export function runNode(script, args, options = {}) {
+  return spawnSync(process.execPath, [script, ...args], { encoding: 'utf8', stdio: 'pipe', ...options });
+}
+
+export function runCommandString(command, options = {}) {
+  console.error(`+ ${command}`);
+  return spawnSync(command, { encoding: 'utf8', stdio: 'inherit', shell: true, ...options });
+}
+
+export function runCommand(argv, options = {}) {
+  const [command, ...args] = argv;
+  return spawnSync(command, args, { encoding: 'utf8', stdio: 'inherit', shell: process.platform === 'win32', ...options });
+}
+
+export function slash(file) {
+  return file.replace(/\\/g, '/');
+}
diff --git a/assets/skills/comet/scripts/comet-state.js b/assets/skills/comet/scripts/comet-state.js
new file mode 100644
index 00000000..e23d410d
--- /dev/null
+++ b/assets/skills/comet/scripts/comet-state.js
@@ -0,0 +1,384 @@
+#!/usr/bin/env node
+import { existsSync, mkdirSync, readdirSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import {
+  changeDirFor,
+  currentHeadOrNull,
+  fail,
+  fieldValue,
+  fileNonempty,
+  git,
+  green,
+  red,
+  setYamlField,
+  today,
+  validateChangeName,
+  validateEnum,
+  writeYamlData,
+  yamlFileFor,
+  yellow,
+} from './comet-lib.js';
+
+const ENUMS = {
+  workflow: ['full', 'hotfix', 'tweak'],
+  phase: ['open', 'design', 'build', 'verify', 'archive'],
+  build_mode: ['subagent-driven-development', 'executing-plans', 'direct'],
+  build_pause: ['null', 'plan-ready'],
+  isolation: ['branch', 'worktree'],
+  verify_mode: ['light', 'full'],
+  verify_result: ['pending', 'pass', 'fail'],
+  branch_status: ['pending', 'handled'],
+  archived: ['true', 'false'],
+  direct_override: ['true', 'false'],
+};
+
+const SET_FIELDS = new Set([
+  'workflow',
+  'phase',
+  'build_mode',
+  'build_pause',
+  'isolation',
+  'verify_mode',
+  'verify_result',
+  'verification_report',
+  'branch_status',
+  'archived',
+  'design_doc',
+  'plan',
+  'verified_at',
+  'created_at',
+  'direct_override',
+  'build_command',
+  'verify_command',
+  'handoff_context',
+  'handoff_hash',
+  'base_ref',
+]);
+
+function get(change, field) {
+  validateChangeName(change);
+  const yaml = yamlFileFor(change);
+  if (!existsSync(yaml)) fail(`.comet.yaml not found at ${yaml}`);
+  console.log(fieldValue(yaml, field));
+}
+
+function getValue(change, field) {
+  const yaml = yamlFileFor(change);
+  return fieldValue(yaml, field);
+}
+
+function set(change, field, value, quiet = false) {
+  validateChangeName(change);
+  const yaml = yamlFileFor(change);
+  if (!existsSync(yaml)) fail(`.comet.yaml not found at ${yaml}`);
+  if (field === 'phase') {
+    yellow("WARNING: Setting 'phase' directly bypasses state machine constraints.");
+    yellow('  Consider using: comet-state.js transition <change-name> <event>');
+  } else if (!SET_FIELDS.has(field)) {
+    red(`ERROR: Unknown field: '${field}'`);
+    red('Valid fields:');
+    red('  workflow, phase, design_doc, plan, build_mode, build_pause, isolation,');
+    red('  verify_mode, verify_result, verification_report, branch_status,');
+    red('  verified_at, created_at, archived, base_ref, direct_override,');
+    red('  build_command, verify_command, handoff_context, handoff_hash');
+    process.exit(1);
+  }
+  if (ENUMS[field]) validateEnum(value, ENUMS[field]);
+  setYamlField(yaml, field, value);
+  if (!quiet) green(`[SET] ${field}=${value}`);
+}
+
+function init(change, workflow) {
+  validateChangeName(change);
+  validateEnum(workflow, ENUMS.workflow);
+  const changeDir = changeDirFor(change);
+  const yaml = yamlFileFor(change);
+  if (existsSync(yaml)) fail(`.comet.yaml already exists at ${yaml}`);
+  mkdirSync(changeDir, { recursive: true });
+  const preset = workflow === 'full' ? ['null', 'null', 'null'] : ['direct', 'branch', 'light'];
+  writeYamlData(yaml, {
+    workflow,
+    phase: 'open',
+    build_mode: preset[0],
+    build_pause: 'null',
+    isolation: preset[1],
+    verify_mode: preset[2],
+    base_ref: currentHeadOrNull(),
+    design_doc: 'null',
+    plan: 'null',
+    verify_result: 'pending',
+    verification_report: 'null',
+    branch_status: 'pending',
+    created_at: today(),
+    verified_at: 'null',
+    archived: 'false',
+  });
+  green(`Initialized: ${yaml} (workflow=${workflow})`);
+}
+
+function requirePhase(change, expected) {
+  const actual = getValue(change, 'phase');
+  if (actual !== expected) fail(`Cannot transition '${change}': expected phase ${expected}, got ${actual}`);
+}
+
+function requireVerificationEvidence(change) {
+  const report = getValue(change, 'verification_report');
+  const branchStatus = getValue(change, 'branch_status');
+  if (!report || report === 'null' || !existsSync(report)) {
+    fail(`Cannot transition '${change}': verification_report must point to an existing report file`);
+  }
+  if (branchStatus !== 'handled') fail(`Cannot transition '${change}': branch_status must be handled`);
+}
+
+function requireBuildDecisions(change) {
+  const workflow = getValue(change, 'workflow');
+  const buildMode = getValue(change, 'build_mode');
+  const isolation = getValue(change, 'isolation');
+  const directOverride = getValue(change, 'direct_override');
+  if (!['branch', 'worktree'].includes(isolation)) {
+    fail(`Cannot transition '${change}': isolation must be branch or worktree, got '${isolation || 'null'}'`);
+  }
+  if (!ENUMS.build_mode.includes(buildMode)) {
+    fail(`Cannot transition '${change}': build_mode must be selected before leaving build, got '${buildMode || 'null'}'`);
+  }
+  if (buildMode === 'direct' && !['hotfix', 'tweak'].includes(workflow) && directOverride !== 'true') {
+    fail(`Cannot transition '${change}': build_mode=direct is only allowed for hotfix/tweak unless direct_override=true`);
+  }
+}
+
+function transition(change, event) {
+  validateChangeName(change);
+  validateEnum(event, ['open-complete', 'design-complete', 'build-complete', 'verify-pass', 'verify-fail', 'archived']);
+  if (event === 'open-complete') {
+    requirePhase(change, 'open');
+    set(change, 'phase', getValue(change, 'workflow') === 'full' ? 'design' : 'build', true);
+  } else if (event === 'design-complete') {
+    requirePhase(change, 'design');
+    set(change, 'phase', 'build', true);
+  } else if (event === 'build-complete') {
+    requirePhase(change, 'build');
+    requireBuildDecisions(change);
+    set(change, 'phase', 'verify', true);
+    set(change, 'verify_result', 'pending', true);
+    set(change, 'verification_report', 'null', true);
+    set(change, 'branch_status', 'pending', true);
+  } else if (event === 'verify-pass') {
+    requirePhase(change, 'verify');
+    requireVerificationEvidence(change);
+    set(change, 'verify_result', 'pass', true);
+    set(change, 'phase', 'archive', true);
+    set(change, 'verified_at', today(), true);
+  } else if (event === 'verify-fail') {
+    requirePhase(change, 'verify');
+    set(change, 'verify_result', 'fail', true);
+    set(change, 'phase', 'build', true);
+    set(change, 'branch_status', 'pending', true);
+  } else if (event === 'archived') {
+    requirePhase(change, 'archive');
+    set(change, 'archived', 'true', true);
+  }
+  green(`[TRANSITION] ${event}`);
+}
+
+let checkBlock = false;
+function pass(msg) { console.log(`  \u001b[32m[PASS]\u001b[0m ${msg}`); }
+function block(msg) { console.log(`  \u001b[31m[FAIL]\u001b[0m ${msg}`); checkBlock = true; }
+function checkNonempty(desc, file) { fileNonempty(file) ? pass(`${desc} non-empty`) : block(`${desc} missing or empty`); }
+function checkYamlIs(field, expected, change) {
+  const actual = getValue(change, field);
+  actual === expected ? pass(`${field}=${actual} (expected: ${expected})`) : block(`${field}=${actual} (expected: ${expected})`);
+}
+function checkYamlEmpty(field, change) {
+  const value = getValue(change, field);
+  !value || value === 'null' ? pass(`${field} is empty/null`) : block(`${field}=${value} (expected: empty/null)`);
+}
+
+function check(change, phase) {
+  validateChangeName(change);
+  validateEnum(phase, ['open', 'design', 'build', 'verify', 'archive']);
+  checkBlock = false;
+  const changeDir = join('openspec', 'changes', change);
+  const yaml = join(changeDir, '.comet.yaml');
+  console.log(`=== Entry Check: comet-${phase} ===`);
+  if (!existsSync(yaml)) fail(`.comet.yaml not found at ${yaml}`);
+  if (phase === 'open') {
+    pass('.comet.yaml exists');
+    checkYamlIs('phase', 'open', change);
+  } else if (phase === 'design') {
+    pass('.comet.yaml exists');
+    checkYamlIs('phase', 'design', change);
+    checkYamlIs('workflow', 'full', change);
+    checkYamlEmpty('design_doc', change);
+    checkNonempty('proposal.md', join(changeDir, 'proposal.md'));
+    checkNonempty('design.md', join(changeDir, 'design.md'));
+    checkNonempty('tasks.md', join(changeDir, 'tasks.md'));
+  } else if (phase === 'build') {
+    pass('.comet.yaml exists');
+    checkYamlIs('phase', 'build', change);
+    const workflow = getValue(change, 'workflow');
+    if (workflow === 'full') {
+      const designDoc = getValue(change, 'design_doc');
+      designDoc && designDoc !== 'null' && existsSync(designDoc)
+        ? pass(`design_doc=${designDoc} (file exists)`)
+        : block(`design_doc=${designDoc} (expected: non-null and file exists)`);
+    } else {
+      pass(`workflow=${workflow} (design_doc not required)`);
+    }
+    checkNonempty('proposal.md', join(changeDir, 'proposal.md'));
+    checkNonempty('tasks.md', join(changeDir, 'tasks.md'));
+  } else if (phase === 'verify') {
+    pass('.comet.yaml exists');
+    checkYamlIs('phase', 'verify', change);
+    const result = getValue(change, 'verify_result');
+    result === 'pending' || !result || result === 'null'
+      ? pass(`verify_result=${result} (expected: pending or null)`)
+      : block(`verify_result=${result} (expected: pending or null)`);
+  } else if (phase === 'archive') {
+    pass('.comet.yaml exists');
+    checkYamlIs('phase', 'archive', change);
+    checkYamlIs('verify_result', 'pass', change);
+    const archived = getValue(change, 'archived');
+    archived !== 'true' ? pass(`archived=${archived} (expected: not true)`) : block(`archived=${archived} (expected: not true)`);
+  }
+  console.log('');
+  if (checkBlock) {
+    red('BLOCKED — fix failing checks before proceeding');
+    process.exit(1);
+  }
+  green('ALL CHECKS PASSED — ready to proceed');
+}
+
+function fieldStatus(field, value, file = '') {
+  if (!value || value === 'null') console.log(`  - ${field}: PENDING`);
+  else if (file && !existsSync(file)) console.log(`  - ${field}: BROKEN (path ${value} does not exist)`);
+  else console.log(`  - ${field}: DONE (${value})`);
+}
+
+function recover(change) {
+  validateChangeName(change);
+  const changeDir = join('openspec', 'changes', change);
+  const yaml = join(changeDir, '.comet.yaml');
+  if (!existsSync(yaml)) fail(`.comet.yaml not found at ${yaml}`);
+  const phase = getValue(change, 'phase');
+  const workflow = getValue(change, 'workflow');
+  console.log(`=== Recovery Context: ${change} ===`);
+  console.log(`Phase: ${phase}`);
+  console.log(`Workflow: ${workflow}`);
+  console.log('');
+  const values = Object.fromEntries(['design_doc', 'plan', 'verify_result', 'verify_mode', 'verification_report', 'branch_status', 'handoff_context', 'handoff_hash', 'isolation', 'build_mode', 'build_pause', 'direct_override', 'archived'].map((f) => [f, getValue(change, f)]));
+  console.log('State fields:');
+  if (phase === 'open') {
+    console.log('  Artifacts:');
+    for (const f of ['proposal.md', 'design.md', 'tasks.md']) console.log(`  - ${f}: ${fileNonempty(join(changeDir, f)) ? 'DONE' : 'PENDING'}`);
+    console.log('\nRecovery action: Create or complete missing artifacts, then use AskUserQuestion for user confirmation.');
+  } else if (phase === 'design') {
+    console.log('  Artifacts:');
+    for (const f of ['proposal.md', 'design.md', 'tasks.md']) console.log(`  - ${f}: ${fileNonempty(join(changeDir, f)) ? 'DONE' : 'MISSING (unexpected in design phase)'}`);
+    console.log('\n  Design progress:');
+    fieldStatus('handoff_context', values.handoff_context, values.handoff_context);
+    fieldStatus('handoff_hash', values.handoff_hash);
+    fieldStatus('design_doc', values.design_doc, values.design_doc);
+    console.log('');
+    if (values.design_doc && values.design_doc !== 'null' && existsSync(values.design_doc)) console.log('Recovery action: Design Doc already created and linked. Run guard to transition to build.');
+    else if (values.handoff_context && values.handoff_context !== 'null' && existsSync(values.handoff_context)) console.log('Recovery action: Handoff generated but Design Doc not yet created. Resume from brainstorming confirmation (Step 1c).');
+    else console.log('Recovery action: No handoff generated yet. Start from Step 1a (generate handoff package).');
+  } else if (phase === 'build') {
+    console.log('  Build decisions:');
+    fieldStatus('isolation', values.isolation);
+    fieldStatus('build_mode', values.build_mode);
+    fieldStatus('build_pause', values.build_pause);
+    if (values.build_mode === 'direct' && !['hotfix', 'tweak'].includes(workflow)) fieldStatus('direct_override', values.direct_override);
+    console.log('\n  Plan:');
+    fieldStatus('plan', values.plan, values.plan);
+    const tasksFile = join(changeDir, 'tasks.md');
+    let total = 0;
+    let done = 0;
+    if (existsSync(tasksFile)) {
+      const text = readFileSync(tasksFile, 'utf8');
+      total = (text.match(/^- \[/gm) ?? []).length;
+      done = (text.match(/^- \[x\]/gm) ?? []).length;
+      console.log(`\n  Tasks: ${done}/${total} done, ${total - done} pending`);
+    } else console.log('\n  Tasks: tasks.md MISSING');
+    console.log('');
+    if (values.build_pause === 'plan-ready' && values.plan && values.plan !== 'null' && existsSync(values.plan) && (!values.isolation || values.isolation === 'null' || !values.build_mode || values.build_mode === 'null')) console.log('Recovery action: Plan-ready pause detected. Ask the user whether to continue, then choose isolation and build mode without regenerating the plan.');
+    else if (values.build_pause === 'plan-ready' && (!values.plan || values.plan === 'null' || !existsSync(values.plan))) console.log('Recovery action: Plan-ready pause is recorded, but the plan file is missing. Restore the plan file or rerun writing-plans before choosing execution.');
+    else if (values.build_pause === 'plan-ready') console.log('Recovery action: Plan-ready pause is stale because build decisions are already selected. Clear build_pause to null, then continue from the first unchecked task.');
+    else if (!values.isolation || values.isolation === 'null') console.log('Recovery action: Isolation not selected. Use AskUserQuestion to ask user for branch/worktree choice.');
+    else if (!values.build_mode || values.build_mode === 'null') console.log('Recovery action: Build mode not selected. Use AskUserQuestion to ask user for execution method.');
+    else if (!existsSync(tasksFile)) console.log('Recovery action: tasks.md missing. Verify change directory integrity.');
+    else if (total - done > 0) console.log('Recovery action: Read tasks.md and continue from first unchecked task.');
+    else console.log('Recovery action: All tasks done. Run guard to transition to verify.');
+  } else if (phase === 'verify') {
+    console.log('  Verification:');
+    fieldStatus('verify_result', values.verify_result);
+    fieldStatus('verify_mode', values.verify_mode);
+    fieldStatus('verification_report', values.verification_report, values.verification_report);
+    fieldStatus('branch_status', values.branch_status);
+    console.log('');
+    if (values.verify_result === 'pass' && values.branch_status === 'handled') console.log('Recovery action: Verification complete. Run guard to transition to archive.');
+    else if (values.verify_result === 'pass') console.log('Recovery action: Verification passed but branch not yet handled. Complete branch handling and set branch_status to handled.');
+    else if (values.verify_result === 'fail') console.log('Recovery action: Verification failed and rolled back to build. Resume from /comet-build.');
+    else console.log('Recovery action: Verification not yet started or in progress. Run scale assessment then verify.');
+  } else if (phase === 'archive') {
+    console.log('  Archive:');
+    fieldStatus('verify_result', values.verify_result);
+    fieldStatus('archived', values.archived);
+    console.log('\nRecovery action: Run /comet-archive to complete archiving.');
+  }
+  console.log('\n=== End Recovery Context ===');
+}
+
+function countSpecFiles(dir) {
+  if (!existsSync(dir)) return 0;
+  let count = 0;
+  for (const entry of readdirSync(dir, { withFileTypes: true })) {
+    const p = join(dir, entry.name);
+    if (entry.isDirectory()) count += countSpecFiles(p);
+    else if (entry.isFile() && entry.name === 'spec.md') count += 1;
+  }
+  return count;
+}
+
+function scale(change) {
+  validateChangeName(change);
+  const changeDir = join('openspec', 'changes', change);
+  const yaml = join(changeDir, '.comet.yaml');
+  if (!existsSync(yaml)) fail(`.comet.yaml not found at ${yaml}`);
+  const tasksFile = join(changeDir, 'tasks.md');
+  const taskCount = existsSync(tasksFile) ? (readFileSync(tasksFile, 'utf8').match(/^- \[/gm) ?? []).length : 0;
+  const deltaSpecCount = countSpecFiles(join(changeDir, 'specs'));
+  let changedFiles = 0;
+  if (git(['rev-parse', '--git-dir']).status === 0) {
+    let baseRef = '';
+    const plan = getValue(change, 'plan');
+    if (plan && plan !== 'null' && existsSync(plan)) {
+      baseRef = readFileSync(plan, 'utf8').match(/^base-ref:\s*(.*)$/m)?.[1]?.trim() ?? '';
+    }
+    if (!baseRef || baseRef === 'null') baseRef = getValue(change, 'base_ref');
+    const diff = baseRef && baseRef !== 'null' && git(['rev-parse', '--verify', baseRef]).status === 0
+      ? git(['diff', '--name-only', `${baseRef}...HEAD`])
+      : git(['diff', '--name-only', 'HEAD']);
+    changedFiles = diff.status === 0 ? diff.stdout.split(/\r?\n/).filter(Boolean).length : 0;
+  }
+  const result = taskCount > 3 || deltaSpecCount > 1 || changedFiles > 4 ? 'full' : 'light';
+  console.error(`=== Scale Assessment: ${change} ===`);
+  console.error(`  Tasks: ${taskCount} (threshold: 3)`);
+  console.error(`  Delta specs: ${deltaSpecCount} capabilities (threshold: 1)`);
+  console.error(`  Changed files: ${changedFiles} (threshold: 4)`);
+  console.error(`  → Result: ${result}`);
+  setYamlField(yaml, 'verify_mode', result);
+  green(`[SCALE] verify_mode=${result}`);
+}
+
+const [subcommand, ...args] = process.argv.slice(2);
+if (subcommand === 'init' && args.length >= 2) init(args[0], args[1]);
+else if (subcommand === 'get' && args.length >= 2) get(args[0], args[1]);
+else if (subcommand === 'set' && args.length >= 3) set(args[0], args[1], args.slice(2).join(' '));
+else if (subcommand === 'transition' && args.length >= 2) transition(args[0], args[1]);
+else if (subcommand === 'check' && args.length >= 2) args[2] === '--recover' ? recover(args[0]) : check(args[0], args[1]);
+else if (subcommand === 'scale' && args.length >= 1) scale(args[0]);
+else {
+  red(`Unknown subcommand: ${subcommand ?? ''}`);
+  console.error('\nUsage: comet-state.js <subcommand> <change-name> [args...]');
+  process.exit(1);
+}
diff --git a/assets/skills/comet/scripts/comet-state.sh b/assets/skills/comet/scripts/comet-state.sh
deleted file mode 100644
index a997f9ac..00000000
--- a/assets/skills/comet/scripts/comet-state.sh
+++ /dev/null
@@ -1,908 +0,0 @@
-#!/bin/bash
-# Comet State — unified interface for .comet.yaml state management
-# Usage: comet-state.sh <subcommand> <change-name> [args...]
-#
-# Subcommands:
-#   init <change-name> <workflow>  — Initialize .comet.yaml with workflow defaults
-#   get <change-name> <field>       — Read a field value from .comet.yaml
-#   set <change-name> <field> <val> — Update a field value
-#   transition <change-name> <event> — Apply a validated state transition
-#   check <change-name> <phase>    — Verify entry requirements for a phase
-#   check <change-name> <phase> --recover — Output structured recovery context for compaction resume
-#   scale <change-name>             — Assess and set verification mode based on metrics
-#
-# Workflows: full, hotfix, tweak
-# Phases for check: open, design, build, verify, archive
-
-set -euo pipefail
-
-# --- Color output helpers ---
-
-red() { echo -e "\033[31m$1\033[0m" >&2; }
-green() { echo -e "\033[32m$1\033[0m" >&2; }
-yellow() { echo -e "\033[33m$1\033[0m" >&2; }
-
-# --- Script location ---
-
-# shellcheck disable=SC2034
-SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
-
-# --- Input validation ---
-
-validate_change_name() {
-  local name="$1"
-  # Reject empty names
-  if [ -z "$name" ]; then
-    red "ERROR: Change name cannot be empty" >&2
-    exit 1
-  fi
-  # Only allow alphanumeric, hyphens, and underscores
-  if [[ ! "$name" =~ ^[a-zA-Z0-9_-]+$ ]]; then
-    red "ERROR: Invalid change name: '$name'" >&2
-    red "Valid characters: a-z, A-Z, 0-9, -, _" >&2
-    exit 1
-  fi
-  # Reject path traversal attempts
-  if [[ "$name" =~ \.\. ]]; then
-    red "ERROR: Change name cannot contain '..' (path traversal not allowed)" >&2
-    exit 1
-  fi
-}
-
-validate_enum() {
-  local value="$1"
-  shift
-  local valid_values=("$@")
-
-  for valid in "${valid_values[@]}"; do
-    if [ "$value" = "$valid" ]; then
-      return 0
-    fi
-  done
-
-  red "ERROR: Invalid value: '$value'" >&2
-  red "Valid values: ${valid_values[*]}" >&2
-  exit 1
-}
-
-# --- Helper functions ---
-
-yaml_field() {
-  local field="$1"
-  local yaml_file="$2"
-  if [ -f "$yaml_file" ]; then
-    local value
-    value=$(grep "^${field}:" "$yaml_file" 2>/dev/null | sed "s/^${field}: *//" || true)
-    value=$(strip_inline_comment "$value")
-    strip_wrapping_quotes "$value"
-  fi
-}
-
-strip_inline_comment() {
-  local value="$1"
-  printf '%s\n' "$value" | awk -v squote="'" '
-    {
-      out = ""
-      quote = ""
-      for (i = 1; i <= length($0); i++) {
-        c = substr($0, i, 1)
-        if (quote == "") {
-          if (c == "\"" || c == squote) {
-            quote = c
-          } else if (c == "#" && (i == 1 || substr($0, i - 1, 1) ~ /[[:space:]]/)) {
-            sub(/[[:space:]]+$/, "", out)
-            print out
-            next
-          }
-        } else if (c == quote) {
-          quote = ""
-        }
-        out = out c
-      }
-      print out
-    }
-  '
-}
-
-strip_wrapping_quotes() {
-  local value="$1"
-  case "$value" in
-    \"*\")
-      printf '%s\n' "${value:1:${#value}-2}"
-      ;;
-    \'*\')
-      printf '%s\n' "${value:1:${#value}-2}"
-      ;;
-    *)
-      printf '%s\n' "$value"
-      ;;
-  esac
-}
-
-replace_yaml_field() {
-  local yaml_file="$1"
-  local field="$2"
-  local value="$3"
-  local tmp_file
-
-  tmp_file=$(mktemp)
-  awk -v field="$field" -v value="$value" '
-    index($0, field ":") == 1 { print field ": " value; next }
-    { print }
-  ' "$yaml_file" > "$tmp_file"
-  mv "$tmp_file" "$yaml_file"
-}
-
-file_nonempty() {
-  [ -f "$1" ] && [ -s "$1" ]
-}
-
-change_dir_for() {
-  local change_name="$1"
-  if [ -d "openspec/changes/$change_name" ]; then
-    echo "openspec/changes/$change_name"
-  elif [ -d "openspec/changes/archive/$change_name" ]; then
-    echo "openspec/changes/archive/$change_name"
-  else
-    echo "openspec/changes/$change_name"
-  fi
-}
-
-yaml_file_for() {
-  local change_name="$1"
-  local change_dir
-  change_dir=$(change_dir_for "$change_name")
-  echo "$change_dir/.comet.yaml"
-}
-
-# --- Subcommands ---
-
-cmd_init() {
-  local change_name="$1"
-  local workflow="$2"
-
-  validate_change_name "$change_name"
-  validate_enum "$workflow" "full" "hotfix" "tweak"
-
-  local change_dir yaml_file
-  change_dir=$(change_dir_for "$change_name")
-  yaml_file=$(yaml_file_for "$change_name")
-
-  # Check if .comet.yaml already exists
-  if [ -f "$yaml_file" ]; then
-    red "ERROR: .comet.yaml already exists at $yaml_file"
-    exit 1
-  fi
-
-  # Create change directory if it doesn't exist
-  mkdir -p "$change_dir"
-
-  # Set workflow-appropriate defaults
-  local phase build_mode isolation verify_mode
-  phase="open"
-
-  case "$workflow" in
-    full)
-      build_mode="null"
-      isolation="null"
-      verify_mode="null"
-      ;;
-    hotfix|tweak)
-      build_mode="direct"
-      isolation="branch"
-      verify_mode="light"
-      ;;
-  esac
-
-  # Write .comet.yaml
-  # Record current HEAD as base_ref for scale assessment fallback
-  local base_ref="null"
-  if git rev-parse --verify HEAD >/dev/null 2>&1; then
-    base_ref=$(git rev-parse HEAD 2>/dev/null || echo "null")
-  fi
-
-  cat > "$yaml_file" <<EOF
-workflow: $workflow
-phase: $phase
-build_mode: $build_mode
-build_pause: null
-isolation: $isolation
-verify_mode: $verify_mode
-base_ref: $base_ref
-design_doc: null
-plan: null
-verify_result: pending
-verification_report: null
-branch_status: pending
-created_at: $(date +%Y-%m-%d)
-verified_at: null
-archived: false
-EOF
-
-  green "Initialized: $yaml_file (workflow=$workflow)"
-}
-
-cmd_get() {
-  local change_name="$1"
-  local field="$2"
-
-  validate_change_name "$change_name"
-
-  local yaml_file
-  yaml_file=$(yaml_file_for "$change_name")
-
-  # Check if .comet.yaml exists
-  if [ ! -f "$yaml_file" ]; then
-    red "ERROR: .comet.yaml not found at $yaml_file"
-    exit 1
-  fi
-
-  # Read and output the field value
-  local value
-  value=$(yaml_field "$field" "$yaml_file")
-  echo "${value:-}"
-}
-
-cmd_set() {
-  local change_name="$1"
-  local field="$2"
-  local value="$3"
-
-  validate_change_name "$change_name"
-
-  local yaml_file
-  yaml_file=$(yaml_file_for "$change_name")
-
-  # Check if .comet.yaml exists
-  if [ ! -f "$yaml_file" ]; then
-    red "ERROR: .comet.yaml not found at $yaml_file"
-    exit 1
-  fi
-
-  # Validate field name
-  case "$field" in
-    phase)
-      yellow "WARNING: Setting 'phase' directly bypasses state machine constraints." >&2
-      yellow "  Consider using: comet-state.sh transition <change-name> <event>" >&2
-      ;;
-    workflow|build_mode|build_pause|isolation|verify_mode|verify_result|verification_report|branch_status|archived|design_doc|plan|verified_at|created_at|direct_override|build_command|verify_command|handoff_context|handoff_hash|base_ref)
-      # Valid field
-      ;;
-    *)
-      red "ERROR: Unknown field: '$field'" >&2
-      red "Valid fields:" >&2
-      red "  workflow, phase, design_doc, plan, build_mode, build_pause, isolation," >&2
-      red "  verify_mode, verify_result, verification_report, branch_status," >&2
-      red "  verified_at, created_at, archived, base_ref, direct_override," >&2
-      red "  build_command, verify_command, handoff_context, handoff_hash" >&2
-      exit 1
-      ;;
-  esac
-
-  # Validate enum values
-  case "$field" in
-    workflow)
-      validate_enum "$value" "full" "hotfix" "tweak"
-      ;;
-    phase)
-      validate_enum "$value" "open" "design" "build" "verify" "archive"
-      ;;
-    build_mode)
-      validate_enum "$value" "subagent-driven-development" "executing-plans" "direct"
-      ;;
-    build_pause)
-      validate_enum "$value" "null" "plan-ready"
-      ;;
-    isolation)
-      validate_enum "$value" "branch" "worktree"
-      ;;
-    verify_mode)
-      validate_enum "$value" "light" "full"
-      ;;
-    verify_result)
-      validate_enum "$value" "pending" "pass" "fail"
-      ;;
-    branch_status)
-      validate_enum "$value" "pending" "handled"
-      ;;
-    archived)
-      validate_enum "$value" "true" "false"
-      ;;
-    direct_override)
-      validate_enum "$value" "true" "false"
-      ;;
-    design_doc|plan|verification_report|verified_at|created_at|build_command|verify_command|handoff_context|handoff_hash)
-      # No validation for path fields, date fields, or project command strings
-      ;;
-  esac
-
-  # Write or update the field
-  if grep -q "^${field}:" "$yaml_file"; then
-    replace_yaml_field "$yaml_file" "$field" "$value"
-  else
-    # Field doesn't exist, append it
-    echo "${field}: ${value}" >> "$yaml_file"
-  fi
-
-  green "[SET] ${field}=${value}"
-}
-
-require_phase() {
-  local change_name="$1"
-  local expected="$2"
-  local actual
-  actual=$(cmd_get "$change_name" "phase")
-  if [ "$actual" != "$expected" ]; then
-    red "ERROR: Cannot transition '$change_name': expected phase ${expected}, got ${actual}" >&2
-    exit 1
-  fi
-}
-
-require_verification_evidence() {
-  local change_name="$1"
-  local report branch_status
-  report=$(cmd_get "$change_name" "verification_report")
-  branch_status=$(cmd_get "$change_name" "branch_status")
-
-  if [ -z "$report" ] || [ "$report" = "null" ] || [ ! -f "$report" ]; then
-    red "ERROR: Cannot transition '$change_name': verification_report must point to an existing report file" >&2
-    exit 1
-  fi
-
-  if [ "$branch_status" != "handled" ]; then
-    red "ERROR: Cannot transition '$change_name': branch_status must be handled" >&2
-    exit 1
-  fi
-}
-
-require_build_decisions() {
-  local change_name="$1"
-  local workflow build_mode isolation direct_override
-  workflow=$(cmd_get "$change_name" "workflow")
-  build_mode=$(cmd_get "$change_name" "build_mode")
-  isolation=$(cmd_get "$change_name" "isolation")
-  direct_override=$(cmd_get "$change_name" "direct_override" 2>/dev/null || true)
-
-  case "$isolation" in
-    branch|worktree) ;;
-    *)
-      red "ERROR: Cannot transition '$change_name': isolation must be branch or worktree, got '${isolation:-null}'" >&2
-      exit 1
-      ;;
-  esac
-
-  case "$build_mode" in
-    subagent-driven-development|executing-plans|direct) ;;
-    *)
-      red "ERROR: Cannot transition '$change_name': build_mode must be selected before leaving build, got '${build_mode:-null}'" >&2
-      exit 1
-      ;;
-  esac
-
-  if [ "$build_mode" = "direct" ] && [ "$workflow" != "hotfix" ] && [ "$workflow" != "tweak" ] && [ "$direct_override" != "true" ]; then
-    red "ERROR: Cannot transition '$change_name': build_mode=direct is only allowed for hotfix/tweak unless direct_override=true" >&2
-    exit 1
-  fi
-}
-
-cmd_transition() {
-  local change_name="$1"
-  local event="$2"
-
-  validate_change_name "$change_name"
-  validate_enum "$event" "open-complete" "design-complete" "build-complete" "verify-pass" "verify-fail" "archived"
-
-  case "$event" in
-    open-complete)
-      require_phase "$change_name" "open"
-      local workflow
-      workflow=$(cmd_get "$change_name" "workflow")
-      if [ "$workflow" = "full" ]; then
-        cmd_set "$change_name" phase design
-      else
-        cmd_set "$change_name" phase build
-      fi
-      ;;
-    design-complete)
-      require_phase "$change_name" "design"
-      cmd_set "$change_name" phase build
-      ;;
-    build-complete)
-      require_phase "$change_name" "build"
-      require_build_decisions "$change_name"
-      cmd_set "$change_name" phase verify
-      cmd_set "$change_name" verify_result pending
-      cmd_set "$change_name" verification_report null
-      cmd_set "$change_name" branch_status pending
-      ;;
-    verify-pass)
-      require_phase "$change_name" "verify"
-      require_verification_evidence "$change_name"
-      cmd_set "$change_name" verify_result pass
-      cmd_set "$change_name" phase archive
-      cmd_set "$change_name" verified_at "$(date +%Y-%m-%d)"
-      ;;
-    verify-fail)
-      require_phase "$change_name" "verify"
-      cmd_set "$change_name" verify_result fail
-      cmd_set "$change_name" phase build
-      cmd_set "$change_name" branch_status pending
-      ;;
-    archived)
-      require_phase "$change_name" "archive"
-      cmd_set "$change_name" archived true
-      ;;
-  esac
-
-  green "[TRANSITION] ${event}"
-}
-
-# --- Check helpers for entry verification ---
-
-CHECK_BLOCK=0
-
-check_pass() {
-  local msg="$1"
-  echo "  $(green "[PASS]") $msg"
-}
-
-check_fail() {
-  local msg="$1"
-  echo "  $(red "[FAIL]") $msg"
-  CHECK_BLOCK=1
-}
-
-check_nonempty() {
-  local desc="$1"
-  local path="$2"
-  if file_nonempty "$path"; then
-    check_pass "$desc non-empty"
-  else
-    check_fail "$desc missing or empty"
-  fi
-}
-
-check_yaml_is() {
-  local field="$1"
-  local expected="$2"
-  local change_name="$3"
-  local actual
-  actual=$(cmd_get "$change_name" "$field")
-  if [ "$actual" = "$expected" ]; then
-    check_pass "${field}=${actual} (expected: ${expected})"
-  else
-    check_fail "${field}=${actual} (expected: ${expected})"
-  fi
-}
-
-check_yaml_empty() {
-  local field="$1"
-  local change_name="$2"
-  local value
-  value=$(cmd_get "$change_name" "$field")
-  if [ -z "$value" ] || [ "$value" = "null" ]; then
-    check_pass "${field} is empty/null"
-  else
-    check_fail "${field}=${value} (expected: empty/null)"
-  fi
-}
-
-check_file_not_exists() {
-  local desc="$1"
-  local path="$2"
-  if [ ! -f "$path" ]; then
-    check_pass "$desc does not exist"
-  else
-    check_fail "$desc exists (should not exist)"
-  fi
-}
-
-cmd_check() {
-  local change_name="$1"
-  local phase="$2"
-
-  validate_change_name "$change_name"
-  validate_enum "$phase" "open" "design" "build" "verify" "archive"
-
-  local change_dir="openspec/changes/$change_name"
-  local yaml_file="$change_dir/.comet.yaml"
-  local proposal_file="$change_dir/proposal.md"
-  local design_file="$change_dir/design.md"
-  local tasks_file="$change_dir/tasks.md"
-
-  echo "=== Entry Check: comet-${phase} ==="
-
-  # .comet.yaml must exist for all phases (state machine core)
-  if [ ! -f "$yaml_file" ]; then
-    red "ERROR: .comet.yaml not found at $yaml_file"
-    exit 1
-  fi
-
-  # Phase-specific checks
-  case "$phase" in
-    open)
-      check_pass ".comet.yaml exists"
-      check_yaml_is "phase" "open" "$change_name"
-      ;;
-    design)
-      check_pass ".comet.yaml exists"
-      check_yaml_is "phase" "design" "$change_name"
-      check_yaml_is "workflow" "full" "$change_name"
-      check_yaml_empty "design_doc" "$change_name"
-      check_nonempty "proposal.md" "$proposal_file"
-      check_nonempty "design.md" "$design_file"
-      check_nonempty "tasks.md" "$tasks_file"
-      ;;
-    build)
-      check_pass ".comet.yaml exists"
-      check_yaml_is "phase" "build" "$change_name"
-      # design_doc required for full workflow only
-      local workflow
-      workflow=$(cmd_get "$change_name" "workflow")
-      if [ "$workflow" = "full" ]; then
-        local design_doc
-        design_doc=$(cmd_get "$change_name" "design_doc")
-        if [ -n "$design_doc" ] && [ "$design_doc" != "null" ] && [ -f "$design_doc" ]; then
-          check_pass "design_doc=${design_doc} (file exists)"
-        else
-          check_fail "design_doc=${design_doc} (expected: non-null and file exists)"
-        fi
-      else
-        check_pass "workflow=${workflow} (design_doc not required)"
-      fi
-      check_nonempty "proposal.md" "$proposal_file"
-      check_nonempty "tasks.md" "$tasks_file"
-      ;;
-    verify)
-      check_pass ".comet.yaml exists"
-      check_yaml_is "phase" "verify" "$change_name"
-      # Check verify_result is pending or null
-      local verify_result
-      verify_result=$(cmd_get "$change_name" "verify_result")
-      if [ "$verify_result" = "pending" ] || [ -z "$verify_result" ] || [ "$verify_result" = "null" ]; then
-        check_pass "verify_result=${verify_result} (expected: pending or null)"
-      else
-        check_fail "verify_result=${verify_result} (expected: pending or null)"
-      fi
-      ;;
-    archive)
-      check_pass ".comet.yaml exists"
-      check_yaml_is "phase" "archive" "$change_name"
-      check_yaml_is "verify_result" "pass" "$change_name"
-      # Check archived is NOT true
-      local archived
-      archived=$(cmd_get "$change_name" "archived")
-      if [ "$archived" != "true" ]; then
-        check_pass "archived=${archived} (expected: not true)"
-      else
-        check_fail "archived=${archived} (expected: not true)"
-      fi
-      ;;
-    *)
-      red "ERROR: Unknown phase for check: $phase"
-      exit 1
-      ;;
-  esac
-
-  echo ""
-  if [ "$CHECK_BLOCK" -eq 1 ]; then
-    red "BLOCKED — fix failing checks before proceeding"
-    exit 1
-  else
-    green "ALL CHECKS PASSED — ready to proceed"
-    exit 0
-  fi
-}
-
-# --- Recovery context for compaction resume ---
-
-field_status() {
-  # Args: field_name value [file_path]
-  # Prints: "field_name: DONE (value)" or "field_name: PENDING"
-  local field="$1"
-  local value="$2"
-  local file_path="${3:-}"
-
-  if [ -z "$value" ] || [ "$value" = "null" ]; then
-    echo "  - ${field}: PENDING"
-  elif [ -n "$file_path" ] && [ ! -f "$file_path" ]; then
-    echo "  - ${field}: BROKEN (path ${value} does not exist)"
-  else
-    echo "  - ${field}: DONE (${value})"
-  fi
-}
-
-cmd_recover() {
-  local change_name="$1"
-
-  validate_change_name "$change_name"
-
-  local change_dir="openspec/changes/$change_name"
-  local yaml_file="$change_dir/.comet.yaml"
-
-  if [ ! -f "$yaml_file" ]; then
-    red "ERROR: .comet.yaml not found at $yaml_file"
-    exit 1
-  fi
-
-  local phase workflow
-  phase=$(cmd_get "$change_name" "phase")
-  workflow=$(cmd_get "$change_name" "workflow")
-
-  echo "=== Recovery Context: ${change_name} ==="
-  echo "Phase: ${phase}"
-  echo "Workflow: ${workflow}"
-  echo ""
-
-  # Read all relevant fields
-  local design_doc plan verify_result verify_mode verification_report
-  local branch_status handoff_context handoff_hash isolation build_mode build_pause direct_override
-  design_doc=$(cmd_get "$change_name" "design_doc")
-  plan=$(cmd_get "$change_name" "plan")
-  verify_result=$(cmd_get "$change_name" "verify_result")
-  verify_mode=$(cmd_get "$change_name" "verify_mode")
-  verification_report=$(cmd_get "$change_name" "verification_report")
-  branch_status=$(cmd_get "$change_name" "branch_status")
-  handoff_context=$(cmd_get "$change_name" "handoff_context")
-  handoff_hash=$(cmd_get "$change_name" "handoff_hash")
-  isolation=$(cmd_get "$change_name" "isolation")
-  build_mode=$(cmd_get "$change_name" "build_mode")
-  build_pause=$(cmd_get "$change_name" "build_pause" 2>/dev/null || true)
-  direct_override=$(cmd_get "$change_name" "direct_override" 2>/dev/null || true)
-
-  echo "State fields:"
-
-  # Phase-specific field reporting
-  case "$phase" in
-    open)
-      echo "  Artifacts:"
-      for f in proposal.md design.md tasks.md; do
-        if file_nonempty "$change_dir/$f"; then
-          echo "  - ${f}: DONE"
-        else
-          echo "  - ${f}: PENDING"
-        fi
-      done
-      echo ""
-      echo "Recovery action: Create or complete missing artifacts, then use AskUserQuestion for user confirmation."
-      ;;
-    design)
-      echo "  Artifacts:"
-      for f in proposal.md design.md tasks.md; do
-        if file_nonempty "$change_dir/$f"; then
-          echo "  - ${f}: DONE"
-        else
-          echo "  - ${f}: MISSING (unexpected in design phase)"
-        fi
-      done
-      echo ""
-      echo "  Design progress:"
-      field_status "handoff_context" "$handoff_context" "$handoff_context"
-      field_status "handoff_hash" "$handoff_hash"
-      field_status "design_doc" "$design_doc" "$design_doc"
-      echo ""
-      if [ -n "$design_doc" ] && [ "$design_doc" != "null" ] && [ -f "$design_doc" ]; then
-        echo "Recovery action: Design Doc already created and linked. Run guard to transition to build."
-      elif [ -n "$handoff_context" ] && [ "$handoff_context" != "null" ] && [ -f "$handoff_context" ]; then
-        echo "Recovery action: Handoff generated but Design Doc not yet created. Resume from brainstorming confirmation (Step 1c)."
-      else
-        echo "Recovery action: No handoff generated yet. Start from Step 1a (generate handoff package)."
-      fi
-      ;;
-    build)
-      echo "  Build decisions:"
-      field_status "isolation" "$isolation"
-      field_status "build_mode" "$build_mode"
-      field_status "build_pause" "$build_pause"
-      if [ "$build_mode" = "direct" ] && [ "$workflow" != "hotfix" ] && [ "$workflow" != "tweak" ]; then
-        field_status "direct_override" "$direct_override"
-      fi
-      echo ""
-      echo "  Plan:"
-      field_status "plan" "$plan" "$plan"
-      echo ""
-      # Count completed vs pending tasks
-      local tasks_file="$change_dir/tasks.md"
-      local total=0 done=0 pending=0
-      if [ -f "$tasks_file" ]; then
-        total=$(grep -c '^\- \[' "$tasks_file" 2>/dev/null || echo "0")
-        done=$(grep -c '^\- \[x\]' "$tasks_file" 2>/dev/null || echo "0")
-        pending=$((total - done))
-        echo "  Tasks: ${done}/${total} done, ${pending} pending"
-      else
-        echo "  Tasks: tasks.md MISSING"
-      fi
-      echo ""
-      if [ "$build_pause" = "plan-ready" ] && [ -n "$plan" ] && [ "$plan" != "null" ] && [ -f "$plan" ] && { [ "$isolation" = "null" ] || [ -z "$isolation" ] || [ "$build_mode" = "null" ] || [ -z "$build_mode" ]; }; then
-        echo "Recovery action: Plan-ready pause detected. Ask the user whether to continue, then choose isolation and build mode without regenerating the plan."
-      elif [ "$build_pause" = "plan-ready" ] && { [ -z "$plan" ] || [ "$plan" = "null" ] || [ ! -f "$plan" ]; }; then
-        echo "Recovery action: Plan-ready pause is recorded, but the plan file is missing. Restore the plan file or rerun writing-plans before choosing execution."
-      elif [ "$build_pause" = "plan-ready" ]; then
-        echo "Recovery action: Plan-ready pause is stale because build decisions are already selected. Clear build_pause to null, then continue from the first unchecked task."
-      elif [ "$isolation" = "null" ] || [ -z "$isolation" ]; then
-        echo "Recovery action: Isolation not selected. Use AskUserQuestion to ask user for branch/worktree choice."
-      elif [ "$build_mode" = "null" ] || [ -z "$build_mode" ]; then
-        echo "Recovery action: Build mode not selected. Use AskUserQuestion to ask user for execution method."
-      elif [ ! -f "$tasks_file" ]; then
-        echo "Recovery action: tasks.md missing. Verify change directory integrity."
-      elif [ "$pending" -gt 0 ]; then
-        echo "Recovery action: Read tasks.md and continue from first unchecked task."
-      else
-        echo "Recovery action: All tasks done. Run guard to transition to verify."
-      fi
-      ;;
-    verify)
-      echo "  Verification:"
-      field_status "verify_result" "$verify_result"
-      field_status "verify_mode" "$verify_mode"
-      field_status "verification_report" "$verification_report" "$verification_report"
-      field_status "branch_status" "$branch_status"
-      echo ""
-      if [ "$verify_result" = "pass" ] && [ "$branch_status" = "handled" ]; then
-        echo "Recovery action: Verification complete. Run guard to transition to archive."
-      elif [ "$verify_result" = "pass" ]; then
-        echo "Recovery action: Verification passed but branch not yet handled. Complete branch handling and set branch_status to handled."
-      elif [ "$verify_result" = "fail" ]; then
-        echo "Recovery action: Verification failed and rolled back to build. Resume from /comet-build."
-      else
-        echo "Recovery action: Verification not yet started or in progress. Run scale assessment then verify."
-      fi
-      ;;
-    archive)
-      echo "  Archive:"
-      field_status "verify_result" "$verify_result"
-      field_status "archived" "$(cmd_get "$change_name" "archived")"
-      echo ""
-      echo "Recovery action: Run /comet-archive to complete archiving."
-      ;;
-    *)
-      red "ERROR: Unknown phase: $phase"
-      exit 1
-      ;;
-  esac
-
-  echo ""
-  echo "=== End Recovery Context ==="
-}
-
-cmd_scale() {
-  local change_name="$1"
-
-  validate_change_name "$change_name"
-
-  local change_dir="openspec/changes/$change_name"
-  local yaml_file="$change_dir/.comet.yaml"
-
-  # Verify .comet.yaml exists
-  if [ ! -f "$yaml_file" ]; then
-    red "ERROR: .comet.yaml not found at $yaml_file"
-    exit 1
-  fi
-
-  # Read metrics
-  # 1. Task count: count lines matching `- [` in tasks.md
-  local tasks_file="$change_dir/tasks.md"
-  local task_count=0
-  if [ -f "$tasks_file" ]; then
-    task_count=$(grep -c '^\- \[' "$tasks_file" 2>/dev/null || echo "0")
-  fi
-
-  # 2. Delta spec count: count files named spec.md under specs/*/spec.md
-  local delta_spec_count=0
-  if [ -d "$change_dir/specs" ]; then
-    delta_spec_count=$(find "$change_dir/specs" -name "spec.md" -type f 2>/dev/null | wc -l | tr -d ' ')
-  fi
-
-  # 3. Changed files: prefer plan base-ref, then .comet.yaml base_ref, fall back to worktree diff
-  local changed_files=0
-  if git rev-parse --git-dir > /dev/null 2>&1; then
-    local plan_file base_ref=""
-    plan_file=$(cmd_get "$change_name" "plan" 2>/dev/null || true)
-    if [ -n "$plan_file" ] && [ "$plan_file" != "null" ] && [ -f "$plan_file" ]; then
-      base_ref=$(grep '^base-ref:' "$plan_file" 2>/dev/null | head -1 | sed 's/^base-ref: *//')
-    fi
-    # Fallback to base_ref stored in .comet.yaml (set during init)
-    if [ -z "$base_ref" ] || [ "$base_ref" = "null" ]; then
-      base_ref=$(cmd_get "$change_name" "base_ref" 2>/dev/null || true)
-    fi
-
-    if [ -n "${base_ref:-}" ] && [ "$base_ref" != "null" ] && git rev-parse --verify "$base_ref" >/dev/null 2>&1; then
-      changed_files=$(git diff --name-only "$base_ref"...HEAD 2>/dev/null | wc -l | tr -d ' ')
-    else
-      changed_files=$(git diff --name-only HEAD 2>/dev/null | wc -l | tr -d ' ')
-    fi
-  fi
-
-  # Decision rules
-  local result="light"
-  if [ "$task_count" -gt 3 ] || [ "$delta_spec_count" -gt 1 ] || [ "$changed_files" -gt 4 ]; then
-    result="full"
-  fi
-
-  # Output assessment to stderr
-  echo "=== Scale Assessment: $change_name ===" >&2
-  echo "  Tasks: $task_count (threshold: 3)" >&2
-  echo "  Delta specs: $delta_spec_count capabilities (threshold: 1)" >&2
-  echo "  Changed files: $changed_files (threshold: 4)" >&2
-  echo "  → Result: $result" >&2
-
-  # Update verify_mode in .comet.yaml
-  replace_yaml_field "$yaml_file" "verify_mode" "$result"
-
-  green "[SCALE] verify_mode=$result"
-}
-
-# --- Main ---
-
-SUBCOMMAND="${1:-}"
-shift || true
-
-case "$SUBCOMMAND" in
-  init)
-    if [ $# -lt 2 ]; then
-      red "Usage: comet-state.sh init <change-name> <workflow>" >&2
-      red "Workflows: full, hotfix, tweak" >&2
-      exit 1
-    fi
-    cmd_init "$@"
-    ;;
-  get)
-    if [ $# -lt 2 ]; then
-      red "Usage: comet-state.sh get <change-name> <field>" >&2
-      exit 1
-    fi
-    cmd_get "$@"
-    ;;
-  set)
-    if [ $# -lt 3 ]; then
-      red "Usage: comet-state.sh set <change-name> <field> <value>" >&2
-      exit 1
-    fi
-    cmd_set "$@"
-    ;;
-  transition)
-    if [ $# -lt 2 ]; then
-      red "Usage: comet-state.sh transition <change-name> <event>" >&2
-      red "Events: open-complete, design-complete, build-complete, verify-pass, verify-fail, archived" >&2
-      exit 1
-    fi
-    cmd_transition "$@"
-    ;;
-  check)
-    if [ $# -lt 2 ]; then
-      red "Usage: comet-state.sh check <change-name> <phase> [--recover]" >&2
-      red "Phases: open, design, build, verify, archive" >&2
-      exit 1
-    fi
-    # Detect --recover flag (3rd argument)
-    if [ "${3:-}" = "--recover" ]; then
-      cmd_recover "$1"
-    else
-      cmd_check "$@"
-    fi
-    ;;
-  scale)
-    if [ $# -lt 1 ]; then
-      red "Usage: comet-state.sh scale <change-name>" >&2
-      exit 1
-    fi
-    cmd_scale "$@"
-    ;;
-  *)
-    red "Unknown subcommand: $SUBCOMMAND" >&2
-    echo "" >&2
-    echo "Usage: comet-state.sh <subcommand> <change-name> [args...]" >&2
-    echo "" >&2
-    echo "Subcommands:" >&2
-    echo "  init <change-name> <workflow>  — Initialize .comet.yaml with workflow defaults" >&2
-    echo "  get <change-name> <field>       — Read a field value from .comet.yaml" >&2
-    echo "  set <change-name> <field> <val> — Update a field value in .comet.yaml" >&2
-    echo "  transition <change-name> <event> — Apply a validated state transition" >&2
-    echo "  check <change-name> <phase>    — Verify entry requirements for a phase" >&2
-    echo "  scale <change-name>             — Assess and set verification mode based on metrics" >&2
-    echo "" >&2
-    echo "Workflows: full, hotfix, tweak" >&2
-    echo "Phases for check: open, design, build, verify, archive" >&2
-    exit 1
-    ;;
-esac
diff --git a/assets/skills/comet/scripts/comet-yaml-validate.js b/assets/skills/comet/scripts/comet-yaml-validate.js
new file mode 100644
index 00000000..6f8e6b62
--- /dev/null
+++ b/assets/skills/comet/scripts/comet-yaml-validate.js
@@ -0,0 +1,68 @@
+#!/usr/bin/env node
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { changeDirFor, fieldValue, KNOWN_KEYS, parseYamlLines, red, green, validateChangeName, yellow } from './comet-lib.js';
+
+const change = process.argv[2];
+validateChangeName(change);
+const changeDir = changeDirFor(change);
+const yaml = join(changeDir, '.comet.yaml');
+let errors = 0;
+let warnings = 0;
+
+function fail(message) {
+  red(`  FAIL: ${message}`);
+  errors += 1;
+}
+
+function warn(message) {
+  yellow(`  WARN: ${message}`);
+  warnings += 1;
+}
+
+function validateEnum(field, value, valid) {
+  if (!value || value === 'null') return;
+  if (!valid.includes(value)) fail(`${field}='${value}' is not valid. Expected: ${valid.join(' ')}`);
+}
+
+console.error(`[VALIDATE] ${yaml}`);
+
+if (!existsSync(yaml)) {
+  fail(`.comet.yaml not found at ${yaml}`);
+} else {
+  const parsed = parseYamlLines(yaml);
+  const required = ['workflow', 'phase', 'design_doc', 'plan', 'build_mode', 'isolation', 'verify_mode', 'verify_result', 'verified_at', 'archived'];
+  for (const field of required) {
+    if (!parsed.keys.includes(field)) fail(`missing required field '${field}'`);
+  }
+
+  validateEnum('workflow', fieldValue(yaml, 'workflow'), ['full', 'hotfix', 'tweak']);
+  validateEnum('phase', fieldValue(yaml, 'phase'), ['open', 'design', 'build', 'verify', 'archive']);
+  validateEnum('build_mode', fieldValue(yaml, 'build_mode'), ['subagent-driven-development', 'executing-plans', 'direct']);
+  validateEnum('build_pause', fieldValue(yaml, 'build_pause'), ['null', 'plan-ready']);
+  validateEnum('isolation', fieldValue(yaml, 'isolation'), ['branch', 'worktree']);
+  validateEnum('verify_mode', fieldValue(yaml, 'verify_mode'), ['light', 'full']);
+  validateEnum('verify_result', fieldValue(yaml, 'verify_result'), ['pending', 'pass', 'fail']);
+  validateEnum('branch_status', fieldValue(yaml, 'branch_status'), ['pending', 'handled']);
+  validateEnum('archived', fieldValue(yaml, 'archived'), ['true', 'false']);
+  validateEnum('direct_override', fieldValue(yaml, 'direct_override'), ['true', 'false']);
+
+  for (const field of ['design_doc', 'plan', 'handoff_context']) {
+    const value = fieldValue(yaml, field);
+    if (value && value !== 'null' && !existsSync(value)) fail(`${field}='${value}' does not exist on disk`);
+  }
+  const handoffHash = fieldValue(yaml, 'handoff_hash');
+  if (handoffHash && handoffHash !== 'null' && !/^[a-f0-9]{64}$/.test(handoffHash)) {
+    fail(`handoff_hash='${handoffHash}' is not a sha256 hex digest`);
+  }
+  for (const key of parsed.keys) {
+    if (!KNOWN_KEYS.has(key)) warn(`unknown field '${key}' found`);
+  }
+}
+
+console.error('');
+if (errors > 0) {
+  red(`${errors} error(s), ${warnings} warning(s) — validation FAILED`);
+  process.exit(1);
+}
+green(`0 errors, ${warnings} warning(s) — validation PASSED`);
diff --git a/assets/skills/comet/scripts/comet-yaml-validate.sh b/assets/skills/comet/scripts/comet-yaml-validate.sh
deleted file mode 100644
index 1d8676f1..00000000
--- a/assets/skills/comet/scripts/comet-yaml-validate.sh
+++ /dev/null
@@ -1,200 +0,0 @@
-#!/bin/bash
-# Comet YAML Schema Validator — validates .comet.yaml structure
-# Usage: comet-yaml-validate.sh <change-name>
-# Exit 0 = valid, exit 1 = errors found (printed to stderr)
-
-set -euo pipefail
-
-red()   { echo -e "\033[31m$1\033[0m" >&2; }
-green() { echo -e "\033[32m$1\033[0m" >&2; }
-warn()  { echo -e "\033[33m$1\033[0m" >&2; }
-
-# Input validation - prevent path traversal
-validate_change_name() {
-  local name="$1"
-  # Reject empty names
-  if [ -z "$name" ]; then
-    red "ERROR: Change name cannot be empty" >&2
-    exit 1
-  fi
-  # Only allow alphanumeric, hyphens, and underscores
-  if [[ ! "$name" =~ ^[a-zA-Z0-9_-]+$ ]]; then
-    red "ERROR: Invalid change name: '$name'" >&2
-    red "Valid characters: a-z, A-Z, 0-9, -, _" >&2
-    exit 1
-  fi
-  # Reject path traversal attempts
-  if [[ "$name" =~ \.\. ]]; then
-    red "ERROR: Change name cannot contain '..' (path traversal not allowed)" >&2
-    exit 1
-  fi
-}
-
-validate_change_name "$1"
-
-CHANGE="$1"
-CHANGE_DIR="openspec/changes/$CHANGE"
-if [ ! -d "$CHANGE_DIR" ] && [ -d "openspec/changes/archive/$CHANGE" ]; then
-  CHANGE_DIR="openspec/changes/archive/$CHANGE"
-fi
-YAML="$CHANGE_DIR/.comet.yaml"
-
-ERRORS=0
-WARNINGS=0
-
-# Helper: get value of a top-level field (handles null, empty, quoted)
-field_value() {
-  local value
-  value=$(grep "^${1}:" "$YAML" 2>/dev/null | sed "s/^${1}: *//" || true)
-  value=$(strip_inline_comment "$value")
-  strip_wrapping_quotes "$value"
-}
-
-strip_inline_comment() {
-  local value="$1"
-  printf '%s\n' "$value" | awk -v squote="'" '
-    {
-      out = ""
-      quote = ""
-      for (i = 1; i <= length($0); i++) {
-        c = substr($0, i, 1)
-        if (quote == "") {
-          if (c == "\"" || c == squote) {
-            quote = c
-          } else if (c == "#" && (i == 1 || substr($0, i - 1, 1) ~ /[[:space:]]/)) {
-            sub(/[[:space:]]+$/, "", out)
-            print out
-            next
-          }
-        } else if (c == quote) {
-          quote = ""
-        }
-        out = out c
-      }
-      print out
-    }
-  '
-}
-
-strip_wrapping_quotes() {
-  local value="$1"
-  case "$value" in
-    \"*\")
-      printf '%s\n' "${value:1:${#value}-2}"
-      ;;
-    \'*\')
-      printf '%s\n' "${value:1:${#value}-2}"
-      ;;
-    *)
-      printf '%s\n' "$value"
-      ;;
-  esac
-}
-
-fail()  { red "  FAIL: $1"; ERRORS=$((ERRORS + 1)); }
-warn_msg() { warn "  WARN: $1"; WARNINGS=$((WARNINGS + 1)); }
-
-echo "[VALIDATE] $YAML" >&2
-
-# --- Required fields ---
-REQUIRED_FIELDS="workflow phase design_doc plan build_mode isolation verify_mode verify_result verified_at archived"
-for field in $REQUIRED_FIELDS; do
-  if ! grep -q "^${field}:" "$YAML" 2>/dev/null; then
-    fail "missing required field '$field'"
-  fi
-done
-
-# --- Enum validation ---
-validate_enum() {
-  local field="$1" value="$2"
-  shift 2
-  local valid_values="$*"
-
-  # null or empty is always acceptable
-  if [ -z "$value" ] || [ "$value" = "null" ]; then
-    return 0
-  fi
-
-  for v in $valid_values; do
-    if [ "$value" = "$v" ]; then
-      return 0
-    fi
-  done
-  fail "$field='$value' is not valid. Expected: $valid_values"
-}
-
-workflow=$(field_value "workflow")
-phase=$(field_value "phase")
-build_mode=$(field_value "build_mode")
-build_pause=$(field_value "build_pause")
-isolation=$(field_value "isolation")
-verify_mode=$(field_value "verify_mode")
-verify_result=$(field_value "verify_result")
-branch_status=$(field_value "branch_status")
-archived=$(field_value "archived")
-direct_override=$(field_value "direct_override")
-design_doc=$(field_value "design_doc")
-plan=$(field_value "plan")
-handoff_context=$(field_value "handoff_context")
-handoff_hash=$(field_value "handoff_hash")
-
-validate_enum "workflow"      "$workflow"      "full hotfix tweak"
-validate_enum "phase"         "$phase"          "open design build verify archive"
-validate_enum "build_mode"    "$build_mode"     "subagent-driven-development executing-plans direct"
-validate_enum "build_pause"   "$build_pause"     "null plan-ready"
-validate_enum "isolation"     "$isolation"      "branch worktree"
-validate_enum "verify_mode"   "$verify_mode"    "light full"
-validate_enum "verify_result" "$verify_result"  "pending pass fail"
-validate_enum "branch_status" "$branch_status"  "pending handled"
-validate_enum "archived"      "$archived"       "true false"
-validate_enum "direct_override" "$direct_override" "true false"
-
-# --- Path validation ---
-
-if [ -n "$design_doc" ] && [ "$design_doc" != "null" ]; then
-  if [ ! -f "$design_doc" ]; then
-    fail "design_doc='$design_doc' does not exist on disk"
-  fi
-fi
-
-if [ -n "$plan" ] && [ "$plan" != "null" ]; then
-  if [ ! -f "$plan" ]; then
-    fail "plan='$plan' does not exist on disk"
-  fi
-fi
-
-if [ -n "$handoff_context" ] && [ "$handoff_context" != "null" ]; then
-  if [ ! -f "$handoff_context" ]; then
-    fail "handoff_context='$handoff_context' does not exist on disk"
-  fi
-fi
-
-if [ -n "$handoff_hash" ] && [ "$handoff_hash" != "null" ]; then
-  if [[ ! "$handoff_hash" =~ ^[a-f0-9]{64}$ ]]; then
-    fail "handoff_hash='$handoff_hash' is not a sha256 hex digest"
-  fi
-fi
-
-# --- Unknown keys check ---
-KNOWN_KEYS="workflow phase design_doc plan build_mode build_pause isolation verify_mode verify_result verification_report branch_status verified_at created_at archived direct_override build_command verify_command handoff_context handoff_hash base_ref"
-while IFS=: read -r key _; do
-  key="${key// /}"
-  [ -z "$key" ] && continue
-  found=0
-  for known in $KNOWN_KEYS; do
-    [ "$key" = "$known" ] && found=1 && break
-  done
-  if [ "$found" -eq 0 ]; then
-    warn_msg "unknown field '$key' found"
-  fi
-done < "$YAML"
-
-# --- Summary ---
-echo "" >&2
-if [ "$ERRORS" -gt 0 ]; then
-  red "$ERRORS error(s), $WARNINGS warning(s) — validation FAILED"
-  exit 1
-else
-  green "0 errors, $WARNINGS warning(s) — validation PASSED"
-  exit 0
-fi
diff --git a/package.json b/package.json
index ba7acf75..d89ae1ae 100644
--- a/package.json
+++ b/package.json
@@ -36,7 +36,6 @@
     "lint:fix": "eslint src/ --fix",
     "format": "prettier --write src/",
     "format:check": "prettier --check src/",
-    "test:shell": "node scripts/run-bats.js test/shell/*.bats",
     "prepare": "pnpm run build",
     "prepublishOnly": "node scripts/prepublish-check.js && pnpm run build",
     "postinstall": "node scripts/postinstall.js"
@@ -57,6 +56,7 @@
   },
   "dependencies": {
     "@inquirer/prompts": "^8.4.3",
-    "commander": "^14.0.0"
+    "commander": "^14.0.0",
+    "yaml": "^2.9.0"
   }
 }
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index 0900ecc3..0eb4c9dd 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -14,6 +14,9 @@ importers:
       commander:
         specifier: ^14.0.0
         version: 14.0.3
+      yaml:
+        specifier: ^2.9.0
+        version: 2.9.0
     devDependencies:
       '@eslint/js':
         specifier: ^10.0.1
@@ -38,7 +41,7 @@ importers:
         version: 8.59.3(eslint@10.4.0)(typescript@5.9.3)
       vitest:
         specifier: ^4.1.6
-        version: 4.1.6(@types/node@24.12.4)(@vitest/coverage-v8@4.1.6)(vite@7.3.3(@types/node@24.12.4))
+        version: 4.1.6(@types/node@24.12.4)(@vitest/coverage-v8@4.1.6)(vite@7.3.3(@types/node@24.12.4)(yaml@2.9.0))
 
 packages:
 
@@ -1170,6 +1173,11 @@ packages:
     resolution: {integrity: sha512-BN22B5eaMMI9UMtjrGd5g5eCYPpCPDUy0FJXbYsaT5zYxjFOckS53SQDE3pWkVoWpHXVb3BrYcEN4Twa55B5cA==}
     engines: {node: '>=0.10.0'}
 
+  yaml@2.9.0:
+    resolution: {integrity: sha512-2AvhNX3mb8zd6Zy7INTtSpl1F15HW6Wnqj0srWlkKLcpYl/gMIMJiyuGq2KeI2YFxUPjdlB+3Lc10seMLtL4cA==}
+    engines: {node: '>= 14.6'}
+    hasBin: true
+
   yocto-queue@0.1.0:
     resolution: {integrity: sha512-rVksvsnNCdJ/ohGc6xgPwyN8eheCxsiLM8mxuE/t/mOVqJewPuO1miLpTHQiRgTKCLexL4MeAFVagts7HmNZ2Q==}
     engines: {node: '>=10'}
@@ -1646,7 +1654,7 @@ snapshots:
       obug: 2.1.1
       std-env: 4.1.0
       tinyrainbow: 3.1.0
-      vitest: 4.1.6(@types/node@24.12.4)(@vitest/coverage-v8@4.1.6)(vite@7.3.3(@types/node@24.12.4))
+      vitest: 4.1.6(@types/node@24.12.4)(@vitest/coverage-v8@4.1.6)(vite@7.3.3(@types/node@24.12.4)(yaml@2.9.0))
 
   '@vitest/expect@4.1.6':
     dependencies:
@@ -1657,13 +1665,13 @@ snapshots:
       chai: 6.2.2
       tinyrainbow: 3.1.0
 
-  '@vitest/mocker@4.1.6(vite@7.3.3(@types/node@24.12.4))':
+  '@vitest/mocker@4.1.6(vite@7.3.3(@types/node@24.12.4)(yaml@2.9.0))':
     dependencies:
       '@vitest/spy': 4.1.6
       estree-walker: 3.0.3
       magic-string: 0.30.21
     optionalDependencies:
-      vite: 7.3.3(@types/node@24.12.4)
+      vite: 7.3.3(@types/node@24.12.4)(yaml@2.9.0)
 
   '@vitest/pretty-format@4.1.6':
     dependencies:
@@ -2100,7 +2108,7 @@ snapshots:
     dependencies:
       punycode: 2.3.1
 
-  vite@7.3.3(@types/node@24.12.4):
+  vite@7.3.3(@types/node@24.12.4)(yaml@2.9.0):
     dependencies:
       esbuild: 0.27.7
       fdir: 6.5.0(picomatch@4.0.4)
@@ -2111,11 +2119,12 @@ snapshots:
     optionalDependencies:
       '@types/node': 24.12.4
       fsevents: 2.3.3
+      yaml: 2.9.0
 
-  vitest@4.1.6(@types/node@24.12.4)(@vitest/coverage-v8@4.1.6)(vite@7.3.3(@types/node@24.12.4)):
+  vitest@4.1.6(@types/node@24.12.4)(@vitest/coverage-v8@4.1.6)(vite@7.3.3(@types/node@24.12.4)(yaml@2.9.0)):
     dependencies:
       '@vitest/expect': 4.1.6
-      '@vitest/mocker': 4.1.6(vite@7.3.3(@types/node@24.12.4))
+      '@vitest/mocker': 4.1.6(vite@7.3.3(@types/node@24.12.4)(yaml@2.9.0))
       '@vitest/pretty-format': 4.1.6
       '@vitest/runner': 4.1.6
       '@vitest/snapshot': 4.1.6
@@ -2132,7 +2141,7 @@ snapshots:
       tinyexec: 1.1.2
       tinyglobby: 0.2.16
       tinyrainbow: 3.1.0
-      vite: 7.3.3(@types/node@24.12.4)
+      vite: 7.3.3(@types/node@24.12.4)(yaml@2.9.0)
       why-is-node-running: 2.3.0
     optionalDependencies:
       '@types/node': 24.12.4
@@ -2151,4 +2160,6 @@ snapshots:
 
   word-wrap@1.2.5: {}
 
+  yaml@2.9.0: {}
+
   yocto-queue@0.1.0: {}
diff --git a/scripts/run-bats.js b/scripts/run-bats.js
deleted file mode 100644
index 48ed9ead..00000000
--- a/scripts/run-bats.js
+++ /dev/null
@@ -1,189 +0,0 @@
-#!/usr/bin/env node
-import { spawnSync } from 'node:child_process';
-import { mkdtempSync, readFileSync, readdirSync, rmSync, writeFileSync } from 'node:fs';
-import { tmpdir } from 'node:os';
-import path from 'node:path';
-
-function escapeRegExp(value) {
-  return value.replace(/[.+?^${}()|[\]\\]/g, '\\$&');
-}
-
-function findUsableBash() {
-  const candidates = [
-    process.env.COMET_TEST_BASH,
-    process.env.COMET_BASH,
-    'bash',
-    ...(process.platform === 'win32'
-      ? [
-          'C:\\Program Files\\Git\\bin\\bash.exe',
-          'C:\\Program Files\\Git\\usr\\bin\\bash.exe',
-          'C:\\Program Files (x86)\\Git\\bin\\bash.exe',
-        ]
-      : []),
-  ].filter(Boolean);
-
-  for (const candidate of [...new Set(candidates)]) {
-    const probe = spawnSync(candidate, ['-lc', 'uname -s'], { encoding: 'utf8' });
-    if (probe.status === 0 && probe.stdout.trim()) {
-      if (process.platform === 'win32' && /linux/i.test(probe.stdout)) continue;
-      return candidate;
-    }
-  }
-  return null;
-}
-
-const bashCommand = findUsableBash();
-const bashUname = bashCommand
-  ? (spawnSync(bashCommand, ['-lc', 'uname -s'], { encoding: 'utf8' }).stdout || '').trim()
-  : '';
-const isGitBash = /^(MINGW|MSYS|CYGWIN)/.test(bashUname);
-
-function toBashPath(filePath) {
-  const resolved = path.resolve(filePath).replace(/\\/g, '/');
-  const driveMatch = resolved.match(/^([A-Za-z]):\/(.*)$/);
-  if (!driveMatch) return resolved;
-  if (process.platform === 'win32' && isGitBash) {
-    return `/${driveMatch[1].toLowerCase()}/${driveMatch[2]}`;
-  }
-  return `/mnt/${driveMatch[1].toLowerCase()}/${driveMatch[2]}`;
-}
-
-function shellQuote(value) {
-  return `'${value.replace(/'/g, `'\\''`)}'`;
-}
-
-function expandArgs(args) {
-  const files = [];
-  for (const arg of args) {
-    if (!arg.includes('*')) {
-      files.push(arg);
-      continue;
-    }
-
-    const dir = path.dirname(arg);
-    const base = path.basename(arg);
-    const pattern = new RegExp(`^${base.split('*').map(escapeRegExp).join('.*')}$`);
-    for (const entry of readdirSync(dir)) {
-      if (pattern.test(entry)) files.push(path.join(dir, entry));
-    }
-  }
-  return files.sort();
-}
-
-function parseBats(content) {
-  const lines = content.replace(/\r\n/g, '\n').split('\n');
-  const prelude = [];
-  const tests = [];
-  let current = null;
-
-  for (const line of lines) {
-    const testMatch = line.match(/^@test "(.+)" \{\s*$/);
-    if (testMatch) {
-      current = { name: testMatch[1], body: [] };
-      continue;
-    }
-
-    if (current) {
-      if (/^\}\s*$/.test(line)) {
-        tests.push(current);
-        current = null;
-      } else {
-        current.body.push(line);
-      }
-      continue;
-    }
-
-    prelude.push(line);
-  }
-
-  if (current) {
-    throw new Error(`Unclosed @test block: ${current.name}`);
-  }
-
-  return { prelude, tests };
-}
-
-function compileBats(file) {
-  const content = readFileSync(file, 'utf8');
-  const { prelude, tests } = parseBats(content);
-  const testDir = toBashPath(path.dirname(file));
-  const chunks = [
-    '#!/usr/bin/env bash',
-    'set +e',
-    `export BATS_TEST_DIRNAME=${shellQuote(testDir)}`,
-    'status=0',
-    'output=""',
-    'run() {',
-    '  output="$("$@" 2>&1)"',
-    '  status=$?',
-    '  return 0',
-    '}',
-    ...prelude,
-  ];
-
-  tests.forEach((test, index) => {
-    chunks.push(`__bats_test_${index + 1}() {`);
-    chunks.push('  set -e');
-    chunks.push(...test.body.map((line) => `  ${line}`));
-    chunks.push('}');
-  });
-
-  chunks.push('failures=0');
-  tests.forEach((test, index) => {
-    const fn = `__bats_test_${index + 1}`;
-    chunks.push(`__bats_output="$(mktemp)"`);
-    chunks.push(`if ( trap teardown EXIT; setup; ${fn} ) >"$__bats_output" 2>&1; then`);
-    chunks.push(`  echo "ok ${index + 1} - ${test.name}"`);
-    chunks.push('else');
-    chunks.push(`  echo "not ok ${index + 1} - ${test.name}"`);
-    chunks.push('  cat "$__bats_output" >&2');
-    chunks.push('  failures=$((failures + 1))');
-    chunks.push('fi');
-    chunks.push('rm -f "$__bats_output"');
-  });
-  chunks.push('exit "$failures"');
-
-  return chunks.join('\n');
-}
-
-const args = process.argv.slice(2);
-if (args.length === 0) {
-  console.error('Usage: run-bats.js <file.bats> [...]');
-  process.exit(1);
-}
-
-const files = expandArgs(args);
-if (files.length === 0) {
-  console.error(`No .bats files matched: ${args.join(' ')}`);
-  process.exit(1);
-}
-
-if (!bashCommand) {
-  console.error('ERROR: usable bash not found. Install Git Bash or set COMET_TEST_BASH/COMET_BASH to a working bash executable.');
-  console.error('Windows WSL launcher bash.exe is not supported for Comet shell tests.');
-  process.exit(1);
-}
-
-let failures = 0;
-for (const file of files) {
-  const tests = parseBats(readFileSync(file, 'utf8')).tests;
-  console.log(`# ${file}`);
-  console.log(`1..${tests.length}`);
-
-  const tempDir = mkdtempSync(path.join(tmpdir(), 'comet-bats-'));
-  const compiled = path.join(tempDir, 'compiled.bash');
-  writeFileSync(compiled, compileBats(file), 'utf8');
-
-  const result = spawnSync(bashCommand, [toBashPath(compiled)], {
-    cwd: process.cwd(),
-    encoding: 'utf8',
-  });
-
-  if (result.stdout) process.stdout.write(result.stdout);
-  if (result.stderr) process.stderr.write(result.stderr);
-  if (result.status !== 0) failures += result.status ?? 1;
-
-  rmSync(tempDir, { recursive: true, force: true });
-}
-
-process.exit(failures === 0 ? 0 : 1);
diff --git a/test/shell/comet-state.bats b/test/shell/comet-state.bats
deleted file mode 100644
index 6999aa07..00000000
--- a/test/shell/comet-state.bats
+++ /dev/null
@@ -1,214 +0,0 @@
-#!/usr/bin/env bats
-
-setup() {
-  export TEST_TMPDIR="$(mktemp -d)"
-  export SCRIPT_SOURCE="$BATS_TEST_DIRNAME/../../assets/skills/comet/scripts/comet-state.sh"
-  export SCRIPT_PATH="$TEST_TMPDIR/comet-state.sh"
-  cd "$TEST_TMPDIR"
-  tr -d '\r' < "$SCRIPT_SOURCE" > "$SCRIPT_PATH"
-  mkdir -p openspec/changes
-}
-
-teardown() {
-  rm -rf "$TEST_TMPDIR"
-}
-
-# --- init subcommand ---
-
-@test "init creates .comet.yaml with full workflow defaults" {
-  run bash "$SCRIPT_PATH" init my-change full
-  [ "$status" -eq 0 ]
-  [ -f "openspec/changes/my-change/.comet.yaml" ]
-  grep -q "phase: open" "openspec/changes/my-change/.comet.yaml"
-  grep -q "verify_mode: null" "openspec/changes/my-change/.comet.yaml"
-  grep -q "verification_report: null" "openspec/changes/my-change/.comet.yaml"
-  grep -q "branch_status: pending" "openspec/changes/my-change/.comet.yaml"
-}
-
-@test "init creates .comet.yaml with hotfix workflow defaults" {
-  run bash "$SCRIPT_PATH" init hotfix-123 hotfix
-  [ "$status" -eq 0 ]
-  grep -q "phase: open" "openspec/changes/hotfix-123/.comet.yaml"
-  grep -q "build_mode: direct" "openspec/changes/hotfix-123/.comet.yaml"
-}
-
-@test "init creates .comet.yaml with tweak workflow defaults" {
-  run bash "$SCRIPT_PATH" init tweak-abc tweak
-  [ "$status" -eq 0 ]
-  grep -q "phase: open" "openspec/changes/tweak-abc/.comet.yaml"
-  grep -q "isolation: branch" "openspec/changes/tweak-abc/.comet.yaml"
-}
-
-@test "init rejects duplicate .comet.yaml" {
-  bash "$SCRIPT_PATH" init my-change full
-  run bash "$SCRIPT_PATH" init my-change full
-  [ "$status" -ne 0 ]
-}
-
-@test "init rejects invalid workflow" {
-  run bash "$SCRIPT_PATH" init my-change invalid
-  [ "$status" -ne 0 ]
-}
-
-@test "init rejects empty change name" {
-  run bash "$SCRIPT_PATH" init "" full
-  [ "$status" -ne 0 ]
-}
-
-@test "init rejects change name with special characters" {
-  run bash "$SCRIPT_PATH" init "my change" full
-  [ "$status" -ne 0 ]
-}
-
-@test "init rejects path traversal" {
-  run bash "$SCRIPT_PATH" init ".." full
-  [ "$status" -ne 0 ]
-}
-
-# --- get subcommand ---
-
-@test "get retrieves field value" {
-  bash "$SCRIPT_PATH" init my-change full
-  run bash "$SCRIPT_PATH" get my-change phase
-  [ "$status" -eq 0 ]
-  [ "$output" = "open" ]
-}
-
-@test "get fails for missing change" {
-  run bash "$SCRIPT_PATH" get nonexistent phase
-  [ "$status" -ne 0 ]
-}
-
-# --- set subcommand ---
-
-@test "set updates a field value" {
-  bash "$SCRIPT_PATH" init my-change full
-  run bash "$SCRIPT_PATH" set my-change phase build
-  [ "$status" -eq 0 ]
-
-  run bash "$SCRIPT_PATH" get my-change phase
-  [ "$output" = "build" ]
-}
-
-@test "set rejects unknown field" {
-  bash "$SCRIPT_PATH" init my-change full
-  run bash "$SCRIPT_PATH" set my-change invalid_field value
-  [ "$status" -ne 0 ]
-}
-
-@test "set validates phase enum" {
-  bash "$SCRIPT_PATH" init my-change full
-  run bash "$SCRIPT_PATH" set my-change phase invalid
-  [ "$status" -ne 0 ]
-}
-
-@test "set validates verify_mode enum" {
-  bash "$SCRIPT_PATH" init my-change full
-  run bash "$SCRIPT_PATH" set my-change verify_mode invalid
-  [ "$status" -ne 0 ]
-}
-
-@test "set validates archived enum" {
-  bash "$SCRIPT_PATH" init my-change full
-  run bash "$SCRIPT_PATH" set my-change archived maybe
-  [ "$status" -ne 0 ]
-}
-
-@test "set validates branch_status enum" {
-  bash "$SCRIPT_PATH" init my-change full
-  run bash "$SCRIPT_PATH" set my-change branch_status maybe
-  [ "$status" -ne 0 ]
-}
-
-@test "set allows free-form design_doc value" {
-  bash "$SCRIPT_PATH" init my-change full
-  run bash "$SCRIPT_PATH" set my-change design_doc "docs/design.md"
-  [ "$status" -eq 0 ]
-}
-
-# --- check subcommand ---
-
-@test "check open passes with initialized state" {
-  bash "$SCRIPT_PATH" init my-change full
-  run bash "$SCRIPT_PATH" check my-change open
-  [ "$status" -eq 0 ]
-}
-
-@test "check open fails without .comet.yaml" {
-  mkdir -p openspec/changes/my-change
-  run bash "$SCRIPT_PATH" check my-change open
-  [ "$status" -ne 0 ]
-}
-
-@test "check open fails if phase is not open" {
-  bash "$SCRIPT_PATH" init my-change full
-  bash "$SCRIPT_PATH" set my-change phase design
-  run bash "$SCRIPT_PATH" check my-change open
-  [ "$status" -ne 0 ]
-}
-
-@test "check design passes with correct state" {
-  bash "$SCRIPT_PATH" init my-change full
-  bash "$SCRIPT_PATH" set my-change phase design
-  echo "content" > openspec/changes/my-change/proposal.md
-  echo "content" > openspec/changes/my-change/design.md
-  echo "content" > openspec/changes/my-change/tasks.md
-  run bash "$SCRIPT_PATH" check my-change design
-  [ "$status" -eq 0 ]
-}
-
-@test "check design fails if design_doc is set (not empty)" {
-  bash "$SCRIPT_PATH" init my-change full
-  bash "$SCRIPT_PATH" set my-change phase design
-  bash "$SCRIPT_PATH" set my-change design_doc "some-doc.md"
-  echo "content" > openspec/changes/my-change/proposal.md
-  echo "content" > openspec/changes/my-change/design.md
-  echo "content" > openspec/changes/my-change/tasks.md
-  run bash "$SCRIPT_PATH" check my-change design
-  [ "$status" -ne 0 ]
-}
-
-# --- scale subcommand ---
-
-@test "scale defaults to light for small changes" {
-  bash "$SCRIPT_PATH" init my-change full
-  mkdir -p openspec/changes/my-change
-  echo "- [ ] task 1" > openspec/changes/my-change/tasks.md
-  run bash "$SCRIPT_PATH" scale my-change
-  [ "$status" -eq 0 ]
-
-  run bash "$SCRIPT_PATH" get my-change verify_mode
-  [ "$output" = "light" ]
-}
-
-# --- usage errors ---
-
-@test "unknown subcommand exits with error" {
-  run bash "$SCRIPT_PATH" unknown-cmd
-  [ "$status" -ne 0 ]
-}
-
-@test "init missing args shows usage" {
-  run bash "$SCRIPT_PATH" init my-change
-  [ "$status" -ne 0 ]
-}
-
-@test "get missing args shows usage" {
-  run bash "$SCRIPT_PATH" get my-change
-  [ "$status" -ne 0 ]
-}
-
-@test "set missing args shows usage" {
-  run bash "$SCRIPT_PATH" set my-change phase
-  [ "$status" -ne 0 ]
-}
-
-@test "check missing args shows usage" {
-  run bash "$SCRIPT_PATH" check my-change
-  [ "$status" -ne 0 ]
-}
-
-@test "scale missing args shows usage" {
-  run bash "$SCRIPT_PATH" scale
-  [ "$status" -ne 0 ]
-}
diff --git a/test/ts/comet-scripts.test.ts b/test/ts/comet-scripts.test.ts
index 5863099e..3ac23ca5 100644
--- a/test/ts/comet-scripts.test.ts
+++ b/test/ts/comet-scripts.test.ts
@@ -6,53 +6,11 @@ import path from 'path';
 
 const scriptsDir = path.resolve('assets', 'skills', 'comet', 'scripts');
 
-function findUsableBash(): string | null {
-  const candidates = [
-    process.env.COMET_TEST_BASH,
-    'bash',
-    ...(process.platform === 'win32'
-      ? [
-          'C:\\Program Files\\Git\\bin\\bash.exe',
-          'C:\\Program Files\\Git\\usr\\bin\\bash.exe',
-          'C:\\Program Files (x86)\\Git\\bin\\bash.exe',
-        ]
-      : []),
-  ].filter((candidate): candidate is string => Boolean(candidate));
-
-  for (const candidate of [...new Set(candidates)]) {
-    const probe = spawnSync(candidate, ['-lc', 'uname -s'], { encoding: 'utf-8' });
-    if (probe.status === 0 && probe.stdout.trim()) {
-      if (process.platform === 'win32' && /linux/i.test(probe.stdout)) continue;
-      return candidate;
-    }
-  }
-  return null;
-}
-
-const bashCommand = findUsableBash();
-const bashUname = bashCommand
-  ? (spawnSync(bashCommand, ['-lc', 'uname -s'], { encoding: 'utf-8' }).stdout || '').trim()
-  : '';
-const isGitBash = /^(MINGW|MSYS|CYGWIN)/.test(bashUname);
-
-function toBashPath(filePath: string): string {
-  const resolved = path.resolve(filePath).replace(/\\/g, '/');
-  const driveMatch = resolved.match(/^([A-Za-z]):\/(.*)$/);
-  if (!driveMatch) return resolved;
-  if (process.platform === 'win32' && isGitBash) {
-    return `/${driveMatch[1].toLowerCase()}/${driveMatch[2]}`;
-  }
-  return `/mnt/${driveMatch[1].toLowerCase()}/${driveMatch[2]}`;
-}
-
-function runBash(cwd: string, script: string, args: string[] = [], env: NodeJS.ProcessEnv = {}) {
-  if (!bashCommand) {
-    throw new Error('comet shell script tests require Bash or Git Bash');
-  }
-  return spawnSync(bashCommand, [toBashPath(script), ...args], {
+function runNode(cwd: string, script: string, args: string[] = [], env: NodeJS.ProcessEnv = {}) {
+  return spawnSync(process.execPath, [script, ...args], {
     cwd,
     encoding: 'utf-8',
-    env: { ...process.env, ...env },
+    env: { ...process.env, NODE_NO_WARNINGS: '1', ...env },
   });
 }
 
@@ -71,9 +29,7 @@ async function createChange(tmpDir: string, name: string, yaml: string, tasks =
   return changeDir;
 }
 
-const describeShell = bashCommand ? describe : describe.skip;
-
-describeShell('comet shell scripts', () => {
+describe('comet node scripts', () => {
   let tmpDir: string;
   let guardScript: string;
   let stateScript: string;
@@ -84,21 +40,23 @@ describeShell('comet shell scripts', () => {
       `comet-scripts-${Date.now()}-${Math.random().toString(36).slice(2)}`,
     );
     await fs.mkdir(tmpDir, { recursive: true });
+    await fs.writeFile(path.join(tmpDir, 'package.json'), JSON.stringify({ type: 'module' }));
     const tmpScriptsDir = path.join(tmpDir, 'scripts');
     await fs.mkdir(tmpScriptsDir, { recursive: true });
     for (const name of [
-      'comet-env.sh',
-      'comet-archive.sh',
-      'comet-guard.sh',
-      'comet-handoff.sh',
-      'comet-state.sh',
-      'comet-yaml-validate.sh',
+      'comet-lib.js',
+      'comet-env.js',
+      'comet-archive.js',
+      'comet-guard.js',
+      'comet-handoff.js',
+      'comet-state.js',
+      'comet-yaml-validate.js',
     ]) {
       const content = await fs.readFile(path.join(scriptsDir, name), 'utf-8');
-      await fs.writeFile(path.join(tmpScriptsDir, name), content.replace(/\r\n/g, '\n'));
+      await fs.writeFile(path.join(tmpScriptsDir, name), content);
     }
-    guardScript = path.join(tmpScriptsDir, 'comet-guard.sh');
-    stateScript = path.join(tmpScriptsDir, 'comet-state.sh');
+    guardScript = path.join(tmpScriptsDir, 'comet-guard.js');
+    stateScript = path.join(tmpScriptsDir, 'comet-state.js');
   });
 
   afterEach(async () => {
@@ -106,7 +64,7 @@ describeShell('comet shell scripts', () => {
   });
 
   it('initializes a new change directory with workflow defaults', async () => {
-    const result = runBash(tmpDir, stateScript, ['init', 'new-full-change', 'full']);
+    const result = runNode(tmpDir, stateScript, ['init', 'new-full-change', 'full']);
     const yaml = await fs.readFile(
       path.join(tmpDir, 'openspec', 'changes', 'new-full-change', '.comet.yaml'),
       'utf-8',
@@ -120,7 +78,7 @@ describeShell('comet shell scripts', () => {
   }, 20_000);
 
   it('initializes build_pause as null for new changes', async () => {
-    const result = runBash(tmpDir, stateScript, ['init', 'pause-defaults', 'full']);
+    const result = runNode(tmpDir, stateScript, ['init', 'pause-defaults', 'full']);
     const yaml = await fs.readFile(
       path.join(tmpDir, 'openspec', 'changes', 'pause-defaults', '.comet.yaml'),
       'utf-8',
@@ -130,80 +88,26 @@ describeShell('comet shell scripts', () => {
     expect(yaml).toContain('build_pause: null');
   }, 20_000);
 
-  it('comet-env.sh exports bundled script paths from its own directory', async () => {
-    const envScript = path.join(tmpDir, 'scripts', 'comet-env.sh');
-    const checkScript = path.join(tmpDir, 'check-env.sh');
-    await writeFile(
-      checkScript,
-      [
-        '#!/bin/bash',
-        `. "${toBashPath(envScript)}"`,
-        'printf "%s\\n%s\\n%s\\n%s\\n%s\\n" "$COMET_STATE" "$COMET_GUARD" "$COMET_HANDOFF" "$COMET_ARCHIVE" "$COMET_BASH"',
-        '',
-      ].join('\n'),
-    );
-    const result = runBash(tmpDir, checkScript);
+  it('comet-env.js outputs bundled script paths from its own directory', async () => {
+    const envScript = path.join(tmpDir, 'scripts', 'comet-env.js');
+    const result = runNode(tmpDir, envScript);
+    const env = JSON.parse(result.stdout);
 
     expect(result.status).toBe(0);
     expect(result.stderr).toBe('');
-    expect(result.stdout).toContain('comet-state.sh');
-    expect(result.stdout).toContain('comet-guard.sh');
-    expect(result.stdout).toContain('comet-handoff.sh');
-    expect(result.stdout).toContain('comet-archive.sh');
-    expect(result.stdout).toContain('bash');
+    expect(env.COMET_STATE).toContain('comet-state.js');
+    expect(env.COMET_GUARD).toContain('comet-guard.js');
+    expect(env.COMET_HANDOFF).toContain('comet-handoff.js');
+    expect(env.COMET_ARCHIVE).toContain('comet-archive.js');
   }, 20_000);
 
-  it('comet-env.sh returns failure when a bundled script is missing', async () => {
-    const envScript = path.join(tmpDir, 'scripts', 'comet-env.sh');
-    await fs.rm(path.join(tmpDir, 'scripts', 'comet-guard.sh'));
-    const checkScript = path.join(tmpDir, 'check-env-missing.sh');
-    await writeFile(
-      checkScript,
-      [
-        '#!/bin/bash',
-        `. "${toBashPath(envScript)}"`,
-        'status=$?',
-        'echo "source-status=$status"',
-        'exit "$status"',
-        '',
-      ].join('\n'),
-    );
-
-    const result = runBash(tmpDir, checkScript);
+  it('comet-env.js returns failure when a bundled script is missing', async () => {
+    const envScript = path.join(tmpDir, 'scripts', 'comet-env.js');
+    await fs.rm(path.join(tmpDir, 'scripts', 'comet-guard.js'));
+    const result = runNode(tmpDir, envScript);
 
     expect(result.status).toBe(1);
     expect(result.stderr).toContain('ERROR: Comet scripts not found');
-    expect(result.stdout).toContain('source-status=1');
-  }, 20_000);
-
-  it('comet-env.sh does not change caller shell options when sourced', async () => {
-    const envScript = path.join(tmpDir, 'scripts', 'comet-env.sh');
-    const checkScript = path.join(tmpDir, 'check-env-options.sh');
-    await writeFile(
-      checkScript,
-      [
-        '#!/bin/bash',
-        'set +e',
-        'set +u',
-        'set +o pipefail',
-        `. "${toBashPath(envScript)}"`,
-        'case "$-" in *e*) echo errexit-on ;; *) echo errexit-off ;; esac',
-        'case "$-" in *u*) echo nounset-on ;; *) echo nounset-off ;; esac',
-        "if set -o | grep -E '^pipefail[[:space:]]+on' >/dev/null; then",
-        '  echo pipefail-on',
-        'else',
-        '  echo pipefail-off',
-        'fi',
-        '',
-      ].join('\n'),
-    );
-
-    const result = runBash(tmpDir, checkScript);
-
-    expect(result.status).toBe(0);
-    expect(result.stdout).toContain('errexit-off');
-    expect(result.stdout).toContain('nounset-off');
-    expect(result.stdout).toContain('pipefail-off');
   }, 20_000);
 
   it('blocks build phase when the project build command fails', async () => {
@@ -230,14 +134,14 @@ describeShell('comet shell scripts', () => {
       JSON.stringify({ scripts: { build: 'node -e "process.exit(1)"' } }),
     );
 
-    const result = runBash(tmpDir, guardScript, ['broken-build', 'build']);
+    const result = runNode(tmpDir, guardScript, ['broken-build', 'build']);
 
     expect(result.status).not.toBe(0);
     expect(result.stderr).toContain('[FAIL] Build passes');
   }, 20_000);
 
   it('generates a design handoff and requires minimal design doc linkage before leaving design', async () => {
-    const handoffScript = path.join(tmpDir, 'scripts', 'comet-handoff.sh');
+    const handoffScript = path.join(tmpDir, 'scripts', 'comet-handoff.js');
     await createChange(
       tmpDir,
       'handoff-change',
@@ -262,13 +166,13 @@ describeShell('comet shell scripts', () => {
       'delta spec\n',
     );
 
-    const handoff = runBash(tmpDir, handoffScript, ['handoff-change', 'design', '--write']);
-    const contextPath = runBash(tmpDir, stateScript, [
+    const handoff = runNode(tmpDir, handoffScript, ['handoff-change', 'design', '--write']);
+    const contextPath = runNode(tmpDir, stateScript, [
       'get',
       'handoff-change',
       'handoff_context',
     ]).stdout.trim();
-    const contextHash = runBash(tmpDir, stateScript, [
+    const contextHash = runNode(tmpDir, stateScript, [
       'get',
       'handoff-change',
       'handoff_hash',
@@ -305,14 +209,14 @@ describeShell('comet shell scripts', () => {
         '',
       ].join('\n'),
     );
-    runBash(tmpDir, stateScript, [
+    runNode(tmpDir, stateScript, [
       'set',
       'handoff-change',
       'design_doc',
       'docs/superpowers/specs/handoff-design.md',
     ]);
 
-    const result = runBash(tmpDir, guardScript, ['handoff-change', 'design']);
+    const result = runNode(tmpDir, guardScript, ['handoff-change', 'design']);
 
     expect(result.status).toBe(0);
     expect(result.stderr).toContain('[PASS] design handoff context exists');
@@ -322,8 +226,8 @@ describeShell('comet shell scripts', () => {
   }, 20_000);
 
   it('reads comet yaml fields without including trailing comments', async () => {
-    const handoffScript = path.join(tmpDir, 'scripts', 'comet-handoff.sh');
-    const validateScript = path.join(tmpDir, 'scripts', 'comet-yaml-validate.sh');
+    const handoffScript = path.join(tmpDir, 'scripts', 'comet-handoff.js');
+    const validateScript = path.join(tmpDir, 'scripts', 'comet-yaml-validate.js');
     await createChange(
       tmpDir,
       'commented-yaml',
@@ -343,9 +247,9 @@ describeShell('comet shell scripts', () => {
       ].join('\n'),
     );
 
-    const phase = runBash(tmpDir, stateScript, ['get', 'commented-yaml', 'phase']);
-    const validate = runBash(tmpDir, validateScript, ['commented-yaml']);
-    const handoff = runBash(tmpDir, handoffScript, ['commented-yaml', 'design', '--write']);
+    const phase = runNode(tmpDir, stateScript, ['get', 'commented-yaml', 'phase']);
+    const validate = runNode(tmpDir, validateScript, ['commented-yaml']);
+    const handoff = runNode(tmpDir, handoffScript, ['commented-yaml', 'design', '--write']);
 
     expect(phase.status).toBe(0);
     expect(phase.stdout.trim()).toBe('design');
@@ -354,7 +258,7 @@ describeShell('comet shell scripts', () => {
   }, 20_000);
 
   it('accepts design doc frontmatter after a BOM and leading blank lines', async () => {
-    const handoffScript = path.join(tmpDir, 'scripts', 'comet-handoff.sh');
+    const handoffScript = path.join(tmpDir, 'scripts', 'comet-handoff.js');
     await createChange(
       tmpDir,
       'frontmatter-prefix',
@@ -373,7 +277,7 @@ describeShell('comet shell scripts', () => {
         '',
       ].join('\n'),
     );
-    runBash(tmpDir, handoffScript, ['frontmatter-prefix', 'design', '--write']);
+    runNode(tmpDir, handoffScript, ['frontmatter-prefix', 'design', '--write']);
     await writeFile(
       path.join(tmpDir, 'docs', 'superpowers', 'specs', 'frontmatter-prefix-design.md'),
       [
@@ -387,14 +291,14 @@ describeShell('comet shell scripts', () => {
         '',
       ].join('\n'),
     );
-    runBash(tmpDir, stateScript, [
+    runNode(tmpDir, stateScript, [
       'set',
       'frontmatter-prefix',
       'design_doc',
       'docs/superpowers/specs/frontmatter-prefix-design.md',
     ]);
 
-    const result = runBash(tmpDir, guardScript, ['frontmatter-prefix', 'design']);
+    const result = runNode(tmpDir, guardScript, ['frontmatter-prefix', 'design']);
 
     expect(result.status).toBe(0);
     expect(result.stderr).toContain('[PASS] Design Doc frontmatter links current change');
@@ -402,7 +306,7 @@ describeShell('comet shell scripts', () => {
   }, 20_000);
 
   it('generates a full-mode design handoff when --full is passed', async () => {
-    const handoffScript = path.join(tmpDir, 'scripts', 'comet-handoff.sh');
+    const handoffScript = path.join(tmpDir, 'scripts', 'comet-handoff.js');
     await createChange(
       tmpDir,
       'full-handoff',
@@ -422,7 +326,7 @@ describeShell('comet shell scripts', () => {
       ].join('\n'),
     );
 
-    const handoff = runBash(tmpDir, handoffScript, ['full-handoff', 'design', '--write', '--full']);
+    const handoff = runNode(tmpDir, handoffScript, ['full-handoff', 'design', '--write', '--full']);
 
     expect(handoff.status).toBe(0);
     const contextMarkdown = await fs.readFile(
@@ -442,7 +346,7 @@ describeShell('comet shell scripts', () => {
   }, 20_000);
 
   it('rejects handoff generation when required OpenSpec artifacts are missing', async () => {
-    const handoffScript = path.join(tmpDir, 'scripts', 'comet-handoff.sh');
+    const handoffScript = path.join(tmpDir, 'scripts', 'comet-handoff.js');
     const changeDir = path.join(tmpDir, 'openspec', 'changes', 'missing-artifacts');
     await fs.mkdir(changeDir, { recursive: true });
     await writeFile(
@@ -465,14 +369,14 @@ describeShell('comet shell scripts', () => {
     await writeFile(path.join(changeDir, 'proposal.md'), 'proposal\n');
     // design.md and tasks.md intentionally omitted
 
-    const result = runBash(tmpDir, handoffScript, ['missing-artifacts', 'design', '--write']);
+    const result = runNode(tmpDir, handoffScript, ['missing-artifacts', 'design', '--write']);
 
     expect(result.status).not.toBe(0);
     expect(result.stderr).toContain('required OpenSpec artifact missing or empty');
   }, 20_000);
 
   it('detects OpenSpec artifacts changed after handoff was generated', async () => {
-    const handoffScript = path.join(tmpDir, 'scripts', 'comet-handoff.sh');
+    const handoffScript = path.join(tmpDir, 'scripts', 'comet-handoff.js');
     await createChange(
       tmpDir,
       'stale-handoff',
@@ -492,7 +396,7 @@ describeShell('comet shell scripts', () => {
       ].join('\n'),
     );
 
-    runBash(tmpDir, handoffScript, ['stale-handoff', 'design', '--write']);
+    runNode(tmpDir, handoffScript, ['stale-handoff', 'design', '--write']);
 
     // Mutate proposal.md after handoff was generated
     await writeFile(
@@ -500,7 +404,7 @@ describeShell('comet shell scripts', () => {
       'mutated proposal\n',
     );
 
-    const result = runBash(tmpDir, guardScript, ['stale-handoff', 'design']);
+    const result = runNode(tmpDir, guardScript, ['stale-handoff', 'design']);
 
     expect(result.status).not.toBe(0);
     expect(result.stderr).toContain('[FAIL] design handoff context exists');
@@ -508,7 +412,7 @@ describeShell('comet shell scripts', () => {
   }, 20_000);
 
   it('blocks design exit when design doc frontmatter is missing required fields', async () => {
-    const handoffScript = path.join(tmpDir, 'scripts', 'comet-handoff.sh');
+    const handoffScript = path.join(tmpDir, 'scripts', 'comet-handoff.js');
     await createChange(
       tmpDir,
       'bad-frontmatter',
@@ -528,7 +432,7 @@ describeShell('comet shell scripts', () => {
       ].join('\n'),
     );
 
-    runBash(tmpDir, handoffScript, ['bad-frontmatter', 'design', '--write']);
+    runNode(tmpDir, handoffScript, ['bad-frontmatter', 'design', '--write']);
 
     // Design doc with wrong comet_change
     await writeFile(
@@ -542,14 +446,14 @@ describeShell('comet shell scripts', () => {
         '',
       ].join('\n'),
     );
-    runBash(tmpDir, stateScript, [
+    runNode(tmpDir, stateScript, [
       'set',
       'bad-frontmatter',
       'design_doc',
       'docs/superpowers/specs/bad-design.md',
     ]);
 
-    const result = runBash(tmpDir, guardScript, ['bad-frontmatter', 'design']);
+    const result = runNode(tmpDir, guardScript, ['bad-frontmatter', 'design']);
 
     expect(result.status).not.toBe(0);
     expect(result.stderr).toContain('[FAIL] Design Doc frontmatter links current change');
@@ -579,8 +483,8 @@ describeShell('comet shell scripts', () => {
       JSON.stringify({ scripts: { build: 'node -e "process.exit(0)"' } }),
     );
 
-    const guard = runBash(tmpDir, guardScript, ['missing-build-decisions', 'build']);
-    const transition = runBash(tmpDir, stateScript, [
+    const guard = runNode(tmpDir, guardScript, ['missing-build-decisions', 'build']);
+    const transition = runNode(tmpDir, stateScript, [
       'transition',
       'missing-build-decisions',
       'build-complete',
@@ -615,15 +519,15 @@ describeShell('comet shell scripts', () => {
       ].join('\n'),
     );
 
-    const setPlanReady = runBash(tmpDir, stateScript, [
+    const setPlanReady = runNode(tmpDir, stateScript, [
       'set',
       'pause-set',
       'build_pause',
       'plan-ready',
     ]);
-    const planReady = runBash(tmpDir, stateScript, ['get', 'pause-set', 'build_pause']);
-    const setNull = runBash(tmpDir, stateScript, ['set', 'pause-set', 'build_pause', 'null']);
-    const pausedNull = runBash(tmpDir, stateScript, ['get', 'pause-set', 'build_pause']);
+    const planReady = runNode(tmpDir, stateScript, ['get', 'pause-set', 'build_pause']);
+    const setNull = runNode(tmpDir, stateScript, ['set', 'pause-set', 'build_pause', 'null']);
+    const pausedNull = runNode(tmpDir, stateScript, ['get', 'pause-set', 'build_pause']);
 
     expect(setPlanReady.status).toBe(0);
     expect(planReady.stdout.trim()).toBe('plan-ready');
@@ -651,7 +555,7 @@ describeShell('comet shell scripts', () => {
       ].join('\n'),
     );
 
-    const result = runBash(tmpDir, guardScript, ['invalid-build-pause', 'build']);
+    const result = runNode(tmpDir, guardScript, ['invalid-build-pause', 'build']);
 
     expect(result.status).not.toBe(0);
     expect(result.stderr).toContain("build_pause='paused' is not valid");
@@ -682,7 +586,7 @@ describeShell('comet shell scripts', () => {
       JSON.stringify({ scripts: { build: 'node -e "process.exit(0)"' } }),
     );
 
-    const result = runBash(tmpDir, guardScript, ['direct-full', 'build']);
+    const result = runNode(tmpDir, guardScript, ['direct-full', 'build']);
 
     expect(result.status).not.toBe(0);
     expect(result.stderr).toContain('[FAIL] build_mode allowed for workflow');
@@ -715,7 +619,7 @@ describeShell('comet shell scripts', () => {
       JSON.stringify({ scripts: { build: 'node -e "process.exit(0)"' } }),
     );
 
-    const result = runBash(tmpDir, guardScript, ['unfinished-tasks', 'build']);
+    const result = runNode(tmpDir, guardScript, ['unfinished-tasks', 'build']);
 
     expect(result.status).not.toBe(0);
     expect(result.stderr).toContain('[FAIL] tasks.md all tasks checked');
@@ -744,7 +648,7 @@ describeShell('comet shell scripts', () => {
       ].join('\n'),
     );
 
-    const result = runBash(tmpDir, stateScript, [
+    const result = runNode(tmpDir, stateScript, [
       'transition',
       'direct-full-transition',
       'build-complete',
@@ -779,7 +683,7 @@ describeShell('comet shell scripts', () => {
       JSON.stringify({ scripts: { build: 'node -e "process.exit(0)"' } }),
     );
 
-    const result = runBash(tmpDir, guardScript, ['direct-full-override', 'build']);
+    const result = runNode(tmpDir, guardScript, ['direct-full-override', 'build']);
 
     expect(result.status).toBe(0);
     expect(result.stderr).toContain('[PASS] build_mode allowed for workflow');
@@ -814,7 +718,7 @@ describeShell('comet shell scripts', () => {
       JSON.stringify({ scripts: { build: 'node -e "process.exit(0)"' } }),
     );
 
-    const result = runBash(tmpDir, guardScript, ['configured-build', 'build']);
+    const result = runNode(tmpDir, guardScript, ['configured-build', 'build']);
 
     expect(result.status).not.toBe(0);
     expect(result.stderr).toContain('configured failure');
@@ -841,26 +745,26 @@ describeShell('comet shell scripts', () => {
       ].join('\n'),
     );
 
-    const set = runBash(tmpDir, stateScript, [
+    const set = runNode(tmpDir, stateScript, [
       'set',
       'command-metacharacters',
       'build_command',
       command,
     ]);
-    const get = runBash(tmpDir, stateScript, ['get', 'command-metacharacters', 'build_command']);
+    const get = runNode(tmpDir, stateScript, ['get', 'command-metacharacters', 'build_command']);
 
     expect(set.status).toBe(0);
     expect(get.stdout.trim()).toBe(command);
   });
 
-  it('keeps shell scripts portable across GNU and BSD sed', async () => {
+  it('keeps node scripts portable across GNU and BSD sed', async () => {
     for (const name of [
-      'comet-env.sh',
-      'comet-state.sh',
-      'comet-archive.sh',
-      'comet-guard.sh',
-      'comet-handoff.sh',
-      'comet-yaml-validate.sh',
+      'comet-env.js',
+      'comet-state.js',
+      'comet-archive.js',
+      'comet-guard.js',
+      'comet-handoff.js',
+      'comet-yaml-validate.js',
     ]) {
       const content = await fs.readFile(path.join(tmpDir, 'scripts', name), 'utf-8');
 
@@ -868,44 +772,10 @@ describeShell('comet shell scripts', () => {
     }
   });
 
-  it('keeps optional YAML field reads safe under pipefail', async () => {
-    for (const name of ['comet-state.sh', 'comet-guard.sh']) {
-      const content = await fs.readFile(path.join(tmpDir, 'scripts', name), 'utf-8');
-
-      expect(content).toMatch(/grep "\^\$\{field\}:" "\$[a-z_]+".*\|\| true\)/);
-    }
-  });
-
-  it('guards bash uname detection when bash cannot be spawned', async () => {
-    const files = [
-      path.resolve('scripts', 'run-bats.js'),
-      path.resolve('test', 'ts', 'comet-scripts.test.ts'),
-    ];
-
-    for (const file of files) {
-      const content = await fs.readFile(file, 'utf-8');
-
-      expect(content).toContain(".stdout || ''");
-    }
-  });
-
-  it('uses COMET_BASH for nested script calls when PATH bash is unusable', async () => {
-    const fakeBin = path.join(tmpDir, 'fake-bin');
-    await fs.mkdir(fakeBin, { recursive: true });
-    const fakeBash = path.join(fakeBin, 'bash');
-    await writeFile(
-      fakeBash,
-      [
-        '#!/bin/sh',
-        'echo "bad WSL bash" >&2',
-        'exit 127',
-        '',
-      ].join('\n'),
-    );
-    await fs.chmod(fakeBash, 0o755);
+  it('keeps optional YAML field reads independent from shell pipefail behavior', async () => {
     await createChange(
       tmpDir,
-      'nested-bash',
+      'optional-fields',
       [
         'workflow: full',
         'phase: open',
@@ -922,35 +792,18 @@ describeShell('comet shell scripts', () => {
       ].join('\n'),
     );
 
-    const result = spawnSync('bash', [
-      '-lc',
-      [
-        'COMET_BASH="/bin/bash"',
-        `PATH="${toBashPath(fakeBin)}:$PATH"`,
-        'export COMET_BASH PATH',
-        `/bin/bash "${toBashPath(guardScript)}" nested-bash open --apply`,
-      ].join('; '),
-    ], {
-      cwd: tmpDir,
-      encoding: 'utf-8',
-    });
-    const yaml = await fs.readFile(
-      path.join(tmpDir, 'openspec', 'changes', 'nested-bash', '.comet.yaml'),
-      'utf-8',
-    );
+    const result = runNode(tmpDir, stateScript, ['get', 'optional-fields', 'direct_override']);
 
-    expect(result.status, result.stderr).toBe(0);
-    expect(result.stderr).not.toContain('bad WSL bash');
-    expect(yaml).toContain('phase: design');
+    expect(result.status).toBe(0);
+    expect(result.stdout).toBe('\n');
   }, 20_000);
 
-  it('does not use PATH bash for nested Comet script calls', async () => {
-    for (const name of ['comet-archive.sh', 'comet-guard.sh', 'comet-handoff.sh']) {
+  it('uses node executable for nested Comet script calls', async () => {
+    for (const name of ['comet-archive.js', 'comet-guard.js', 'comet-handoff.js']) {
       const content = await fs.readFile(path.join(tmpDir, 'scripts', name), 'utf-8');
 
-      expect(content, `${name} should use COMET_BASH for nested scripts`).not.toMatch(
-        /\bbash\s+"?\$(?:STATE_SH|state_sh|validate_script)/,
-      );
+      expect(content, `${name} should invoke nested scripts through runNode`).toContain('runNode');
+      expect(content, `${name} should not shell out to bash for nested scripts`).not.toMatch(/\bbash\b/);
     }
   });
 
@@ -983,7 +836,7 @@ describeShell('comet shell scripts', () => {
       JSON.stringify({ scripts: { build: 'node -e "process.exit(0)"' } }),
     );
 
-    const result = runBash(tmpDir, guardScript, ['root-configured-build', 'build']);
+    const result = runNode(tmpDir, guardScript, ['root-configured-build', 'build']);
 
     expect(result.status).not.toBe(0);
     expect(result.stderr).toContain('root configured failure');
@@ -1024,7 +877,7 @@ describeShell('comet shell scripts', () => {
       JSON.stringify({ scripts: { build: 'node -e "process.exit(0)"' } }),
     );
 
-    const result = runBash(tmpDir, guardScript, ['configured-verify', 'verify']);
+    const result = runNode(tmpDir, guardScript, ['configured-verify', 'verify']);
 
     expect(result.status).not.toBe(0);
     expect(result.stderr).toContain('verify configured failure');
@@ -1050,14 +903,14 @@ describeShell('comet shell scripts', () => {
       ].join('\n'),
     );
 
-    const result = runBash(tmpDir, guardScript, ['2026-05-21-done-change', 'archive']);
+    const result = runNode(tmpDir, guardScript, ['2026-05-21-done-change', 'archive']);
 
     expect(result.status).toBe(0);
     expect(result.stderr).toContain('ALL CHECKS PASSED');
   });
 
   it('reports accurate archive step counts when syncing and annotating', async () => {
-    const archiveScript = path.join(tmpDir, 'scripts', 'comet-archive.sh');
+    const archiveScript = path.join(tmpDir, 'scripts', 'comet-archive.js');
     await createChange(
       tmpDir,
       'ready-to-archive',
@@ -1097,7 +950,7 @@ describeShell('comet shell scripts', () => {
       'delta spec\n',
     );
 
-    const result = runBash(tmpDir, archiveScript, ['ready-to-archive']);
+    const result = runNode(tmpDir, archiveScript, ['ready-to-archive']);
 
     expect(result.status).toBe(0);
     expect(result.stderr).toContain('Archive complete. 7/7 steps succeeded.');
@@ -1144,8 +997,8 @@ describeShell('comet shell scripts', () => {
     execFileSync('git', ['add', '.'], { cwd: tmpDir });
     execFileSync('git', ['commit', '-m', 'large change'], { cwd: tmpDir, stdio: 'ignore' });
 
-    const result = runBash(tmpDir, stateScript, ['scale', 'large-change']);
-    const mode = runBash(tmpDir, stateScript, ['get', 'large-change', 'verify_mode']);
+    const result = runNode(tmpDir, stateScript, ['scale', 'large-change']);
+    const mode = runNode(tmpDir, stateScript, ['get', 'large-change', 'verify_mode']);
 
     expect(result.status).toBe(0);
     expect(mode.stdout.trim()).toBe('full');
@@ -1171,8 +1024,8 @@ describeShell('comet shell scripts', () => {
       ].join('\n'),
     );
 
-    const result = runBash(tmpDir, stateScript, ['transition', 'full-change', 'open-complete']);
-    const phase = runBash(tmpDir, stateScript, ['get', 'full-change', 'phase']);
+    const result = runNode(tmpDir, stateScript, ['transition', 'full-change', 'open-complete']);
+    const phase = runNode(tmpDir, stateScript, ['get', 'full-change', 'phase']);
 
     expect(result.status).toBe(0);
     expect(phase.stdout.trim()).toBe('design');
@@ -1198,8 +1051,8 @@ describeShell('comet shell scripts', () => {
       ].join('\n'),
     );
 
-    const result = runBash(tmpDir, stateScript, ['transition', 'tweak-change', 'open-complete']);
-    const phase = runBash(tmpDir, stateScript, ['get', 'tweak-change', 'phase']);
+    const result = runNode(tmpDir, stateScript, ['transition', 'tweak-change', 'open-complete']);
+    const phase = runNode(tmpDir, stateScript, ['get', 'tweak-change', 'phase']);
 
     expect(result.status).toBe(0);
     expect(phase.stdout.trim()).toBe('build');
@@ -1227,10 +1080,10 @@ describeShell('comet shell scripts', () => {
       ].join('\n'),
     );
 
-    const fail = runBash(tmpDir, stateScript, ['transition', 'verify-change', 'verify-fail']);
-    const failedPhase = runBash(tmpDir, stateScript, ['get', 'verify-change', 'phase']);
-    const failedResult = runBash(tmpDir, stateScript, ['get', 'verify-change', 'verify_result']);
-    const failedBranchStatus = runBash(tmpDir, stateScript, [
+    const fail = runNode(tmpDir, stateScript, ['transition', 'verify-change', 'verify-fail']);
+    const failedPhase = runNode(tmpDir, stateScript, ['get', 'verify-change', 'phase']);
+    const failedResult = runNode(tmpDir, stateScript, ['get', 'verify-change', 'verify_result']);
+    const failedBranchStatus = runNode(tmpDir, stateScript, [
       'get',
       'verify-change',
       'branch_status',
@@ -1241,24 +1094,24 @@ describeShell('comet shell scripts', () => {
     expect(failedResult.stdout.trim()).toBe('fail');
     expect(failedBranchStatus.stdout.trim()).toBe('pending');
 
-    runBash(tmpDir, stateScript, ['set', 'verify-change', 'phase', 'verify']);
-    runBash(tmpDir, stateScript, ['set', 'verify-change', 'verify_result', 'pending']);
+    runNode(tmpDir, stateScript, ['set', 'verify-change', 'phase', 'verify']);
+    runNode(tmpDir, stateScript, ['set', 'verify-change', 'verify_result', 'pending']);
     await writeFile(
       path.join(tmpDir, 'docs', 'superpowers', 'reports', 'verify-change.md'),
       'PASS\n',
     );
-    runBash(tmpDir, stateScript, [
+    runNode(tmpDir, stateScript, [
       'set',
       'verify-change',
       'verification_report',
       'docs/superpowers/reports/verify-change.md',
     ]);
-    runBash(tmpDir, stateScript, ['set', 'verify-change', 'branch_status', 'handled']);
+    runNode(tmpDir, stateScript, ['set', 'verify-change', 'branch_status', 'handled']);
 
-    const pass = runBash(tmpDir, stateScript, ['transition', 'verify-change', 'verify-pass']);
-    const passedPhase = runBash(tmpDir, stateScript, ['get', 'verify-change', 'phase']);
-    const passedResult = runBash(tmpDir, stateScript, ['get', 'verify-change', 'verify_result']);
-    const verifiedAt = runBash(tmpDir, stateScript, ['get', 'verify-change', 'verified_at']);
+    const pass = runNode(tmpDir, stateScript, ['transition', 'verify-change', 'verify-pass']);
+    const passedPhase = runNode(tmpDir, stateScript, ['get', 'verify-change', 'phase']);
+    const passedResult = runNode(tmpDir, stateScript, ['get', 'verify-change', 'verify_result']);
+    const verifiedAt = runNode(tmpDir, stateScript, ['get', 'verify-change', 'verified_at']);
 
     expect(pass.status).toBe(0);
     expect(passedPhase.stdout.trim()).toBe('archive');
@@ -1292,8 +1145,8 @@ describeShell('comet shell scripts', () => {
       JSON.stringify({ scripts: { build: 'node -e "process.exit(0)"' } }),
     );
 
-    const result = runBash(tmpDir, guardScript, ['guard-verify', 'verify', '--apply']);
-    const phase = runBash(tmpDir, stateScript, ['get', 'guard-verify', 'phase']);
+    const result = runNode(tmpDir, guardScript, ['guard-verify', 'verify', '--apply']);
+    const phase = runNode(tmpDir, stateScript, ['get', 'guard-verify', 'phase']);
 
     expect(result.status).not.toBe(0);
     expect(result.stderr).toContain('[FAIL] verification_report exists');
@@ -1331,9 +1184,9 @@ describeShell('comet shell scripts', () => {
       JSON.stringify({ scripts: { build: 'node -e "process.exit(0)"' } }),
     );
 
-    const result = runBash(tmpDir, guardScript, ['guard-verify', 'verify', '--apply']);
-    const phase = runBash(tmpDir, stateScript, ['get', 'guard-verify', 'phase']);
-    const verifyResult = runBash(tmpDir, stateScript, ['get', 'guard-verify', 'verify_result']);
+    const result = runNode(tmpDir, guardScript, ['guard-verify', 'verify', '--apply']);
+    const phase = runNode(tmpDir, stateScript, ['get', 'guard-verify', 'phase']);
+    const verifyResult = runNode(tmpDir, stateScript, ['get', 'guard-verify', 'verify_result']);
 
     expect(result.status).toBe(0);
     expect(phase.stdout.trim()).toBe('archive');
@@ -1360,7 +1213,7 @@ describeShell('comet shell scripts', () => {
       ].join('\n'),
     );
 
-    const result = runBash(tmpDir, stateScript, ['transition', 'wrong-phase', 'build-complete']);
+    const result = runNode(tmpDir, stateScript, ['transition', 'wrong-phase', 'build-complete']);
 
     expect(result.status).not.toBe(0);
     expect(result.stderr).toContain('expected phase build');
@@ -1386,12 +1239,12 @@ describeShell('comet shell scripts', () => {
       ].join('\n'),
     );
 
-    const result = runBash(tmpDir, stateScript, [
+    const result = runNode(tmpDir, stateScript, [
       'transition',
       '2026-05-21-done-change',
       'archived',
     ]);
-    const archived = runBash(tmpDir, stateScript, ['get', '2026-05-21-done-change', 'archived']);
+    const archived = runNode(tmpDir, stateScript, ['get', '2026-05-21-done-change', 'archived']);
 
     expect(result.status).toBe(0);
     expect(archived.stdout.trim()).toBe('true');
@@ -1417,7 +1270,7 @@ describeShell('comet shell scripts', () => {
         ].join('\n'),
       );
 
-      const result = runBash(tmpDir, stateScript, ['check', 'recover-open', 'open', '--recover']);
+      const result = runNode(tmpDir, stateScript, ['check', 'recover-open', 'open', '--recover']);
 
       expect(result.status).toBe(0);
       expect(result.stdout).toContain('Recovery Context: recover-open');
@@ -1449,7 +1302,7 @@ describeShell('comet shell scripts', () => {
         ['- [x] done task', '- [ ] pending task'].join('\n'),
       );
 
-      const result = runBash(tmpDir, stateScript, ['check', 'recover-build', 'build', '--recover']);
+      const result = runNode(tmpDir, stateScript, ['check', 'recover-build', 'build', '--recover']);
 
       expect(result.status).toBe(0);
       expect(result.stdout).toContain('Phase: build');
@@ -1482,7 +1335,7 @@ describeShell('comet shell scripts', () => {
         ].join('\n'),
       );
 
-      const result = runBash(tmpDir, stateScript, [
+      const result = runNode(tmpDir, stateScript, [
         'check',
         'recover-plan-ready',
         'build',
@@ -1521,7 +1374,7 @@ describeShell('comet shell scripts', () => {
         ].join('\n'),
       );
 
-      const result = runBash(tmpDir, stateScript, [
+      const result = runNode(tmpDir, stateScript, [
         'check',
         'recover-verify',
         'verify',
@@ -1568,7 +1421,7 @@ describeShell('comet shell scripts', () => {
         '{}',
       );
 
-      const result = runBash(tmpDir, stateScript, [
+      const result = runNode(tmpDir, stateScript, [
         'check',
         'recover-design',
         'design',
@@ -1602,7 +1455,7 @@ describeShell('comet shell scripts', () => {
         ].join('\n'),
       );
 
-      const result = runBash(tmpDir, stateScript, [
+      const result = runNode(tmpDir, stateScript, [
         'check',
         'recover-no-tasks',
         'build',
@@ -1636,7 +1489,7 @@ describeShell('comet shell scripts', () => {
         ['- [x] task 1', '- [x] task 2'].join('\n'),
       );
 
-      const result = runBash(tmpDir, stateScript, [
+      const result = runNode(tmpDir, stateScript, [
         'check',
         'recover-build-done',
         'build',
@@ -1671,7 +1524,7 @@ describeShell('comet shell scripts', () => {
         ].join('\n'),
       );
 
-      const result = runBash(tmpDir, stateScript, [
+      const result = runNode(tmpDir, stateScript, [
         'check',
         'recover-archive',
         'archive',
@@ -1705,7 +1558,7 @@ describeShell('comet shell scripts', () => {
         ].join('\n'),
       );
 
-      const result = runBash(tmpDir, stateScript, ['check', 'recover-normal', 'open']);
+      const result = runNode(tmpDir, stateScript, ['check', 'recover-normal', 'open']);
 
       expect(result.status).toBe(0);
       expect(result.stdout).toContain('Entry Check');
diff --git a/test/ts/run-bats.test.ts b/test/ts/run-bats.test.ts
deleted file mode 100644
index 706b897a..00000000
--- a/test/ts/run-bats.test.ts
+++ /dev/null
@@ -1,38 +0,0 @@
-import { describe, expect, it } from 'vitest';
-import { promises as fs } from 'fs';
-import path from 'path';
-
-describe('run-bats shell runner', () => {
-  it('resolves a usable bash instead of directly invoking PATH bash', async () => {
-    const content = await fs.readFile(path.resolve('scripts', 'run-bats.js'), 'utf-8');
-
-    expect(content).toContain('function findUsableBash');
-    expect(content).toContain('process.env.COMET_TEST_BASH');
-    expect(content).toContain('process.env.COMET_BASH');
-    expect(content).not.toContain("spawnSync('bash'");
-  });
-
-  it('rejects WSL bash when resolving bash on Windows', async () => {
-    const runner = await fs.readFile(path.resolve('scripts', 'run-bats.js'), 'utf-8');
-    const shellTests = await fs.readFile(path.resolve('test', 'ts', 'comet-scripts.test.ts'), 'utf-8');
-
-    expect(runner).toContain("process.platform === 'win32' && /linux/i.test(probe.stdout)");
-    expect(shellTests).toContain("process.platform === 'win32' && /linux/i.test(probe.stdout)");
-  });
-
-  it('checks explicit Comet bash paths before shelling out to discover fallbacks', async () => {
-    const content = await fs.readFile(
-      path.resolve('assets', 'skills', 'comet', 'scripts', 'comet-env.sh'),
-      'utf-8',
-    );
-
-    const cometBashCheck = content.indexOf('if _comet_bash_is_usable "${COMET_BASH:-}"');
-    const currentBashCheck = content.indexOf('if _comet_bash_is_usable "${BASH:-}"');
-    const shellFallback = content.indexOf('command -v sh');
-
-    expect(cometBashCheck).toBeGreaterThan(-1);
-    expect(currentBashCheck).toBeGreaterThan(cometBashCheck);
-    expect(shellFallback).toBeGreaterThan(currentBashCheck);
-    expect(content).not.toContain('for _comet_bash_candidate in \\');
-  });
-});
diff --git a/test/ts/skills.test.ts b/test/ts/skills.test.ts
index e14646ba..14fb3435 100644
--- a/test/ts/skills.test.ts
+++ b/test/ts/skills.test.ts
@@ -132,7 +132,7 @@ describe('skills', () => {
       expect(command).toContain('$ARGUMENTS');
       expect(command).toContain('# Comet Phase 1: Open');
       expect(command).toContain('## Steps');
-      expect(command).toContain('"$COMET_BASH" "$COMET_STATE" init <name> full');
+      expect(command).toContain('node "$COMET_STATE" init <name> full');
       expect(command).not.toContain('Immediately load the `comet-open` skill with the skill tool');
       expect(path.basename(commandPath)).toBe('comet-open.md');
     });
@@ -223,7 +223,7 @@ describe('skills', () => {
       expect(zhTweak).toContain('不得直接进入 `/comet-design`');
       expect(zhComet).toContain('`verify_result: fail` → 进入验证失败决策阻塞点');
       expect(zhComet).not.toContain(
-        '`verify_result: fail` → `"$COMET_BASH" "$COMET_STATE" transition <name> verify-fail` 后 `/comet-build`',
+        '`verify_result: fail` → `node "$COMET_STATE" transition <name> verify-fail` 后 `/comet-build`',
       );
       expect(zhHotfix).toContain('按升级条件阻塞确认处理');
       expect(zhHotfix).not.toContain('停止 hotfix，升级为 `/comet`');
@@ -281,7 +281,7 @@ describe('skills', () => {
       expect(zhBuild).toContain('必须使用 Skill 工具加载 Superpowers `brainstorming`');
       expect(zhHotfix).toContain('立即使用 Skill 工具加载 `comet-design` skill');
       expect(zhTweak).toContain('立即使用 Skill 工具加载 `comet-design` skill');
-      expect(zhVerify).toContain('用户选择 B 后，运行 `"$COMET_BASH" "$COMET_STATE" transition <change-name> verify-fail`，然后调用 `/comet-build`');
+      expect(zhVerify).toContain('用户选择 B 后，运行 `node "$COMET_STATE" transition <change-name> verify-fail`，然后调用 `/comet-build`');
     });
   });
 
@@ -325,7 +325,7 @@ describe('skills', () => {
       expect(enTweak).toContain('Do not directly enter `/comet-design`');
       expect(enComet).toContain('`verify_result: fail` → Enter verification failure decision blocking point');
       expect(enComet).not.toContain(
-        '`verify_result: fail` → `"$COMET_BASH" "$COMET_STATE" transition <name> verify-fail` then `/comet-build`',
+        '`verify_result: fail` → `node "$COMET_STATE" transition <name> verify-fail` then `/comet-build`',
       );
 
       expect(enHotfix).toContain('handle per "Upgrade Conditions" section');
@@ -354,7 +354,7 @@ describe('skills', () => {
       expect(enBuild).toContain('must use Skill tool to load the Superpowers `brainstorming` skill');
       expect(enHotfix).toContain('Immediately use the Skill tool to load the `comet-design` skill');
       expect(enTweak).toContain('Immediately use the Skill tool to load the `comet-design` skill');
-      expect(enVerify).toContain('After user selects B, run `"$COMET_BASH" "$COMET_STATE" transition <change-name> verify-fail`, then invoke `/comet-build`');
+      expect(enVerify).toContain('After user selects B, run `node "$COMET_STATE" transition <change-name> verify-fail`, then invoke `/comet-build`');
     });
   });
 
@@ -454,7 +454,7 @@ describe('skills', () => {
   describe('Comet script discovery helper', () => {
     it('ships a shared script locator helper', async () => {
       const manifest = await readManifest();
-      expect(manifest.skills).toContain('comet/scripts/comet-env.sh');
+      expect(manifest.skills).toContain('comet/scripts/comet-env.js');
     });
 
     it('keeps platform search roots out of English and Chinese skill prose', async () => {
@@ -473,11 +473,11 @@ describe('skills', () => {
           );
           if (!content.includes('COMET_STATE') && !content.includes('COMET_GUARD')) continue;
 
-          expect(content, `${languageDir}/${skillPath} should use comet-env.sh`).toContain(
-            'comet-env.sh',
+          expect(content, `${languageDir}/${skillPath} should use comet-env.js`).toContain(
+            'comet-env.js',
           );
-          expect(content, `${languageDir}/${skillPath} should source COMET_ENV`).toContain(
-            '. "$COMET_ENV"',
+          expect(content, `${languageDir}/${skillPath} should read COMET_ENV JSON`).toContain(
+            'COMET_ENV_JSON="$(node "$COMET_ENV")"',
           );
           expect(content, `${languageDir}/${skillPath} should allow HOME skill glob expansion`).toContain(
             '"$HOME"/.*/skills',
@@ -492,7 +492,7 @@ describe('skills', () => {
       }
     });
 
-    it('uses COMET_BASH in shipped Comet command examples', async () => {
+    it('uses node in shipped Comet command examples', async () => {
       const manifest = await readManifest();
       const skillPaths = manifest.skills.filter(
         (skillPath) =>
@@ -510,6 +510,9 @@ describe('skills', () => {
           expect(content, `${languageDir}/${skillPath} should avoid raw bash for Comet scripts`).not.toMatch(
             /(^|[` \t])bash[ \t]+"?\$COMET_/m,
           );
+          expect(content, `${languageDir}/${skillPath} should avoid COMET_BASH`).not.toContain(
+            'COMET_BASH',
+          );
         }
       }
     });

From 8072f4b5c420f013207e583946e872d2084094e1 Mon Sep 17 00:00:00 2001
From: zheng <forggy0113@gmail.com>
Date: Sat, 6 Jun 2026 03:44:21 +0800
Subject: [PATCH 3/7] refactor: move script source to src/scripts/

---
 AGENTS.md                                     |  56 --
 CHANGELOG.md                                  |   2 +-
 CLAUDE.md                                     |  12 +-
 CONTRIBUTING.md                               |   8 +
 assets/skills/comet/scripts/comet-archive.js  | 181 +++--
 assets/skills/comet/scripts/comet-env.js      |  19 +-
 assets/skills/comet/scripts/comet-guard.js    | 472 ++++++-----
 assets/skills/comet/scripts/comet-handoff.js  | 158 ++--
 assets/skills/comet/scripts/comet-lib.js      | 293 ++++---
 assets/skills/comet/scripts/comet-state.js    | 767 ++++++++++--------
 .../comet/scripts/comet-yaml-validate.js      | 110 +--
 build.js                                      |  40 +-
 src/scripts/comet-archive.ts                  | 138 ++++
 src/scripts/comet-env.ts                      |  23 +
 src/scripts/comet-guard.ts                    | 368 +++++++++
 src/scripts/comet-handoff.ts                  | 156 ++++
 src/scripts/comet-lib.ts                      | 233 ++++++
 src/scripts/comet-state.ts                    | 500 ++++++++++++
 src/scripts/comet-yaml-validate.ts            | 100 +++
 src/scripts/tsconfig.json                     |  16 +
 test/ts/detect.test.ts                        |  22 +-
 test/ts/init-e2e.test.ts                      |  11 +-
 22 files changed, 2696 insertions(+), 989 deletions(-)
 delete mode 100644 AGENTS.md
 create mode 100644 src/scripts/comet-archive.ts
 create mode 100644 src/scripts/comet-env.ts
 create mode 100644 src/scripts/comet-guard.ts
 create mode 100644 src/scripts/comet-handoff.ts
 create mode 100644 src/scripts/comet-lib.ts
 create mode 100644 src/scripts/comet-state.ts
 create mode 100644 src/scripts/comet-yaml-validate.ts
 create mode 100644 src/scripts/tsconfig.json

diff --git a/AGENTS.md b/AGENTS.md
deleted file mode 100644
index fed2e4a0..00000000
--- a/AGENTS.md
+++ /dev/null
@@ -1,56 +0,0 @@
-## 测试
-
-```bash
-npx vitest run test/ts/comet-scripts.test.ts   # Comet Node 脚本测试
-npx vitest run                                   # 全量测试
-```
-
-## Comet Node 脚本规范
-
-脚本位于 `assets/skills/comet/scripts/`，必须跨平台兼容（macOS / Linux / Windows）：
-
-- 使用 Node.js 实现，不新增 `.sh` wrapper
-- 脚本间调用使用 `node <script>.js` 或共享 `runNode`
-- 用户配置的 `build_command` / `verify_command` 允许交给平台 shell 执行
-- 新增脚本必须加入 `beforeEach` 的拷贝列表和 manifest.json
-
-## 脚本依赖关系
-
-```
-comet-lib.js ← comet-state.js, comet-guard.js, comet-handoff.js, comet-archive.js, comet-yaml-validate.js, comet-env.js
-comet-state.js ← comet-guard.js, comet-handoff.js, comet-archive.js
-comet-yaml-validate.js ← comet-guard.js (preflight 阶段)
-comet-handoff.js ← comet-state.js (写入 handoff_context/handoff_hash)
-```
-
-新增共享工具函数时优先放入 `comet-lib.js`，避免各脚本行为分叉。
-
-## .comet.yaml 状态机
-
-每个 change 的状态文件，字段变更需要同步三处：
-1. `comet-state.js` — 可写字段白名单 + enum 验证
-2. `comet-yaml-validate.js` — schema 校验 + KNOWN_KEYS
-3. `test/ts/comet-scripts.test.ts` — 测试中的 yaml 字符串
-
-## 双语言 Skill
-
-skill 优化时先写中文版本（`assets/skills-zh/`），用户确认后再修改英文版本（`assets/skills/`）。
-
-## Changelog 规范
-
-文件：`CHANGELOG.md`，新版本条目置顶。
-
-```
-## What's Changed [x.y.z] - YYYY-MM-DD
-
-### Added / Changed / Fixed / Tests / Removed / Security
-
-- **功能名**: 描述做了什么以及为什么
-```
-
-要点：
-- 版本号与 `package.json` 的 `version` 字段一致
-- 每条以 `- **粗体关键词**: ` 开头，后接具体变更内容
-- 按类型分组：Added → Changed → Fixed → Tests → Removed → Security
-- 描述侧重 **行为变更**（what + why），不是实现细节
-- `### Tests` 条目汇总新增测试覆盖的场景，不逐条列出测试用例
diff --git a/CHANGELOG.md b/CHANGELOG.md
index eb67a220..8223fab5 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -6,7 +6,7 @@ All notable changes to @rpamis/comet will be documented in this file.
 
 ### Added
 
-- **Cross-platform Comet Node scripts**: Added Node.js implementations for Comet state, guard, handoff, archive, YAML validation, environment discovery, and shared script utilities so bundled automation runs without Bash-specific script files.
+- **TypeScript Comet scripts**: Converted script source to TypeScript (`src/scripts/`) with strict type annotations; `build.js` compiles them to JavaScript in `assets/skills/comet/scripts/` for distribution.
 - **Plan-ready build pause state**: Added `build_pause` as a dedicated build-phase pause marker so Comet can stop after plan generation without confusing the pause with the actual execution method.
 - **Plan-ready pause design**: Added a design record for the model-switching pause workflow, covering recovery behavior, stale pause handling, and plan-missing remediation.
 
diff --git a/CLAUDE.md b/CLAUDE.md
index fed2e4a0..76472328 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -7,9 +7,9 @@ npx vitest run                                   # 全量测试
 
 ## Comet Node 脚本规范
 
-脚本位于 `assets/skills/comet/scripts/`，必须跨平台兼容（macOS / Linux / Windows）：
+脚本源码位于 `src/scripts/`（TypeScript），经 `build.js` 编译输出到 `assets/skills/comet/scripts/`（JavaScript），必须跨平台兼容（macOS / Linux / Windows）：
 
-- 使用 Node.js 实现，不新增 `.sh` wrapper
+- 使用 TypeScript 实现（`src/scripts/*.ts`），构建时编译为 `.js`
 - 脚本间调用使用 `node <script>.js` 或共享 `runNode`
 - 用户配置的 `build_command` / `verify_command` 允许交给平台 shell 执行
 - 新增脚本必须加入 `beforeEach` 的拷贝列表和 manifest.json
@@ -17,10 +17,10 @@ npx vitest run                                   # 全量测试
 ## 脚本依赖关系
 
 ```
-comet-lib.js ← comet-state.js, comet-guard.js, comet-handoff.js, comet-archive.js, comet-yaml-validate.js, comet-env.js
-comet-state.js ← comet-guard.js, comet-handoff.js, comet-archive.js
-comet-yaml-validate.js ← comet-guard.js (preflight 阶段)
-comet-handoff.js ← comet-state.js (写入 handoff_context/handoff_hash)
+comet-lib.ts ← comet-state.ts, comet-guard.ts, comet-handoff.ts, comet-archive.ts, comet-yaml-validate.ts, comet-env.ts
+comet-state.ts ← comet-guard.ts, comet-handoff.ts, comet-archive.ts
+comet-yaml-validate.ts ← comet-guard.ts (preflight 阶段)
+comet-handoff.ts ← comet-state.ts (写入 handoff_context/handoff_hash)
 ```
 
 新增共享工具函数时优先放入 `comet-lib.js`，避免各脚本行为分叉。
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 51fb3d60..7678a340 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -53,6 +53,14 @@ src/
 │   ├── skills.ts      # Skill file operations
 │   ├── openspec.ts    # OpenSpec installation
 │   └── superpowers.ts # Superpowers installation
+├── scripts/           # Comet Node.js scripts (phase guards, state, archive)
+│   ├── comet-lib.ts   # Shared utilities
+│   ├── comet-state.ts # State machine (.comet.yaml)
+│   ├── comet-guard.ts # Phase guard checks
+│   ├── comet-handoff.ts # Design handoff
+│   ├── comet-archive.ts # Change archive
+│   ├── comet-env.ts   # Environment discovery
+│   └── comet-yaml-validate.ts # YAML validation
 └── utils/
     └── file-system.ts # File I/O utilities
 ```
diff --git a/assets/skills/comet/scripts/comet-archive.js b/assets/skills/comet/scripts/comet-archive.js
index c44ab4c9..86e2182e 100644
--- a/assets/skills/comet/scripts/comet-archive.js
+++ b/assets/skills/comet/scripts/comet-archive.js
@@ -1,8 +1,7 @@
 #!/usr/bin/env node
-import { copyFileSync, existsSync, mkdirSync, readdirSync, readFileSync, renameSync, statSync, writeFileSync } from 'node:fs';
+import { copyFileSync, existsSync, mkdirSync, readdirSync, readFileSync, renameSync, statSync, writeFileSync, } from 'node:fs';
 import { dirname, join } from 'node:path';
-import { fieldValue, green, red, runNode, scriptDir, today, validateChangeName, yellow } from './comet-lib.js';
-
+import { fieldValue, green, red, runNode, scriptDir, today, validateChangeName, yellow, } from './comet-lib.js';
 const [change, flag] = process.argv.slice(2);
 const dryRun = flag === '--dry-run';
 validateChangeName(change, 'FATAL');
@@ -12,95 +11,125 @@ const archiveName = `${today()}-${change}`;
 const archiveDir = join('openspec', 'changes', 'archive', archiveName);
 let stepsOk = 0;
 let stepsTotal = 0;
-
 function fatal(message) {
-  red(`FATAL: ${message}`);
-  process.exit(1);
+    red(`FATAL: ${message}`);
+    process.exit(1);
+}
+function stepOk(message) {
+    green(`  [OK] ${message}`);
+    stepsOk += 1;
+    stepsTotal += 1;
+}
+function stepFail(message) {
+    red(`  [FAIL] ${message}`);
+    stepsTotal += 1;
+}
+function stepDry(message) {
+    yellow(`  [DRY-RUN] ${message}`);
+    stepsOk += 1;
+    stepsTotal += 1;
+}
+function y(field) {
+    return fieldValue(yaml, field);
 }
-
-function stepOk(message) { green(`  [OK] ${message}`); stepsOk += 1; stepsTotal += 1; }
-function stepFail(message) { red(`  [FAIL] ${message}`); stepsTotal += 1; }
-function stepDry(message) { yellow(`  [DRY-RUN] ${message}`); stepsOk += 1; stepsTotal += 1; }
-function y(field) { return fieldValue(yaml, field); }
-
 console.error(`=== Comet Archive: ${change} ===`);
-if (!existsSync(yaml)) fatal(`.comet.yaml not found in ${changeDir}/`);
+if (!existsSync(yaml))
+    fatal(`.comet.yaml not found in ${changeDir}/`);
 const designDoc = y('design_doc');
 const planPath = y('plan');
-if (y('phase') !== 'archive') fatal(`phase is '${y('phase')}', expected 'archive'`);
-if (y('verify_result') !== 'pass') fatal(`verify_result is '${y('verify_result')}', expected 'pass'. Run comet-verify first.`);
-if (y('archived') === 'true') fatal('change already archived');
+if (y('phase') !== 'archive')
+    fatal(`phase is '${y('phase')}', expected 'archive'`);
+if (y('verify_result') !== 'pass')
+    fatal(`verify_result is '${y('verify_result')}', expected 'pass'. Run comet-verify first.`);
+if (y('archived') === 'true')
+    fatal('change already archived');
 stepOk('Entry state verified');
-if (existsSync(archiveDir)) fatal(`archive target already exists: ${archiveDir}`);
+if (existsSync(archiveDir))
+    fatal(`archive target already exists: ${archiveDir}`);
 stepOk('Archive target available');
-
 function syncDeltaSpecs() {
-  const deltaRoot = join(changeDir, 'specs');
-  if (!existsSync(deltaRoot)) return;
-  for (const capability of readdirSync(deltaRoot)) {
-    const deltaSpecDir = join(deltaRoot, capability);
-    if (!statSync(deltaSpecDir).isDirectory()) continue;
-    const deltaSpec = join(deltaSpecDir, 'spec.md');
-    const mainSpec = join('openspec', 'specs', capability, 'spec.md');
-    if (!existsSync(deltaSpec)) continue;
-    if (dryRun) {
-      stepDry(`Would sync: ${capability} → ${mainSpec}`);
-      continue;
+    const deltaRoot = join(changeDir, 'specs');
+    if (!existsSync(deltaRoot))
+        return;
+    for (const capability of readdirSync(deltaRoot)) {
+        const deltaSpecDir = join(deltaRoot, capability);
+        if (!statSync(deltaSpecDir).isDirectory())
+            continue;
+        const deltaSpec = join(deltaSpecDir, 'spec.md');
+        const mainSpec = join('openspec', 'specs', capability, 'spec.md');
+        if (!existsSync(deltaSpec))
+            continue;
+        if (dryRun) {
+            stepDry(`Would sync: ${capability} → ${mainSpec}`);
+            continue;
+        }
+        mkdirSync(dirname(mainSpec), { recursive: true });
+        copyFileSync(deltaSpec, mainSpec);
+        stepOk(`Delta spec synced: ${capability} → openspec/specs/${capability}/spec.md`);
     }
-    mkdirSync(dirname(mainSpec), { recursive: true });
-    copyFileSync(deltaSpec, mainSpec);
-    stepOk(`Delta spec synced: ${capability} → openspec/specs/${capability}/spec.md`);
-  }
 }
-
 function annotateFrontmatter(file, extraFields) {
-  if (!existsSync(file)) return;
-  if (dryRun) {
-    stepDry(`Would annotate: ${file}`);
-    return;
-  }
-  const text = readFileSync(file, 'utf8');
-  let next;
-  if (text.startsWith('---')) {
-    const lines = text.split(/\r?\n/);
-    const out = [];
-    let inserted = false;
-    for (let i = 0; i < lines.length; i += 1) {
-      const line = lines[i];
-      if (/^archived-with:/.test(line)) continue;
-      if (i > 0 && line === '---' && !inserted) {
-        out.push(`archived-with: ${archiveName}`);
-        if (extraFields) out.push(extraFields);
-        inserted = true;
-      }
-      out.push(line);
+    if (!existsSync(file))
+        return;
+    if (dryRun) {
+        stepDry(`Would annotate: ${file}`);
+        return;
+    }
+    const text = readFileSync(file, 'utf8');
+    let next;
+    if (text.startsWith('---')) {
+        const lines = text.split(/\r?\n/);
+        const out = [];
+        let inserted = false;
+        for (let i = 0; i < lines.length; i += 1) {
+            const line = lines[i];
+            if (/^archived-with:/.test(line))
+                continue;
+            if (i > 0 && line === '---' && !inserted) {
+                out.push(`archived-with: ${archiveName}`);
+                if (extraFields)
+                    out.push(extraFields);
+                inserted = true;
+            }
+            out.push(line);
+        }
+        next = out.join('\n');
     }
-    next = out.join('\n');
-  } else {
-    next = `---\narchived-with: ${archiveName}\n${extraFields ? `${extraFields}\n` : ''}status: final\n---\n${text}`;
-  }
-  writeFileSync(file, next);
-  stepOk(`Annotated: ${file}`);
+    else {
+        next = `---\narchived-with: ${archiveName}\n${extraFields ? `${extraFields}\n` : ''}status: final\n---\n${text}`;
+    }
+    writeFileSync(file, next);
+    stepOk(`Annotated: ${file}`);
 }
-
 syncDeltaSpecs();
-if (designDoc && designDoc !== 'null') annotateFrontmatter(designDoc, 'status: final');
-if (planPath && planPath !== 'null') annotateFrontmatter(planPath, '');
-if (dryRun) stepDry(`Would move: ${changeDir} → ${archiveDir}`);
+if (designDoc && designDoc !== 'null')
+    annotateFrontmatter(designDoc, 'status: final');
+if (planPath && planPath !== 'null')
+    annotateFrontmatter(planPath, '');
+if (dryRun)
+    stepDry(`Would move: ${changeDir} → ${archiveDir}`);
 else {
-  mkdirSync(join('openspec', 'changes', 'archive'), { recursive: true });
-  renameSync(changeDir, archiveDir);
-  stepOk(`Moved to: ${archiveDir}`);
+    mkdirSync(join('openspec', 'changes', 'archive'), { recursive: true });
+    renameSync(changeDir, archiveDir);
+    stepOk(`Moved to: ${archiveDir}`);
 }
 const archiveYaml = join(archiveDir, '.comet.yaml');
-if (dryRun) stepDry(`Would set archived: true in ${archiveYaml}`);
+if (dryRun)
+    stepDry(`Would set archived: true in ${archiveYaml}`);
 else if (existsSync(archiveYaml)) {
-  const state = join(scriptDir, 'comet-state.js');
-  const result = runNode(state, ['transition', archiveName, 'archived']);
-  if (result.status === 0) stepOk('archived: true');
-  else stepFail('archived: true');
-} else stepFail('archived: true (.comet.yaml not found after move)');
+    const state = join(scriptDir, 'comet-state.js');
+    const result = runNode(state, ['transition', archiveName, 'archived']);
+    if (result.status === 0)
+        stepOk('archived: true');
+    else
+        stepFail('archived: true');
+}
+else
+    stepFail('archived: true (.comet.yaml not found after move)');
 console.error('');
-if (dryRun) yellow(`Dry run complete. ${stepsOk}/${stepsTotal} steps would succeed.`);
-else green(`Archive complete. ${stepsOk}/${stepsTotal} steps succeeded.`);
-if (stepsOk < stepsTotal) process.exit(1);
+if (dryRun)
+    yellow(`Dry run complete. ${stepsOk}/${stepsTotal} steps would succeed.`);
+else
+    green(`Archive complete. ${stepsOk}/${stepsTotal} steps succeeded.`);
+if (stepsOk < stepsTotal)
+    process.exit(1);
diff --git a/assets/skills/comet/scripts/comet-env.js b/assets/skills/comet/scripts/comet-env.js
index 83103746..abbfc3bf 100644
--- a/assets/skills/comet/scripts/comet-env.js
+++ b/assets/skills/comet/scripts/comet-env.js
@@ -2,20 +2,17 @@
 import { existsSync } from 'node:fs';
 import { join } from 'node:path';
 import { scriptDir } from './comet-lib.js';
-
 const env = {
-  COMET_STATE: join(scriptDir, 'comet-state.js'),
-  COMET_GUARD: join(scriptDir, 'comet-guard.js'),
-  COMET_HANDOFF: join(scriptDir, 'comet-handoff.js'),
-  COMET_ARCHIVE: join(scriptDir, 'comet-archive.js'),
-  COMET_YAML_VALIDATE: join(scriptDir, 'comet-yaml-validate.js'),
+    COMET_STATE: join(scriptDir, 'comet-state.js'),
+    COMET_GUARD: join(scriptDir, 'comet-guard.js'),
+    COMET_HANDOFF: join(scriptDir, 'comet-handoff.js'),
+    COMET_ARCHIVE: join(scriptDir, 'comet-archive.js'),
+    COMET_YAML_VALIDATE: join(scriptDir, 'comet-yaml-validate.js'),
 };
-
 const missing = Object.values(env).filter((file) => !existsSync(file));
 if (missing.length > 0) {
-  console.error('ERROR: Comet scripts not found. Ensure the comet skill is installed completely.');
-  console.error('Expected path pattern: */comet/scripts/comet-*.js under project or platform skill directories');
-  process.exit(1);
+    console.error('ERROR: Comet scripts not found. Ensure the comet skill is installed completely.');
+    console.error('Expected path pattern: */comet/scripts/comet-*.js under project or platform skill directories');
+    process.exit(1);
 }
-
 console.log(JSON.stringify(env, null, 2));
diff --git a/assets/skills/comet/scripts/comet-guard.js b/assets/skills/comet/scripts/comet-guard.js
index 21fe38b8..e889a4a7 100644
--- a/assets/skills/comet/scripts/comet-guard.js
+++ b/assets/skills/comet/scripts/comet-guard.js
@@ -1,281 +1,311 @@
 #!/usr/bin/env node
-import { existsSync, readFileSync } from 'node:fs';
+import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
 import { join } from 'node:path';
-import {
-  changeDirFor,
-  fieldValue,
-  fileNonempty,
-  green,
-  hashFile,
-  red,
-  runCommand,
-  runCommandString,
-  runNode,
-  scriptDir,
-  sha256,
-  slash,
-  validateChangeName,
-  yellow,
-} from './comet-lib.js';
-
+import { fieldValue, fileNonempty, green, hashFile, red, runCommand, runCommandString, runNode, scriptDir, sha256, slash, validateChangeName, yellow, } from './comet-lib.js';
 const [change, phase, applyFlag] = process.argv.slice(2);
 validateChangeName(change);
 const apply = applyFlag === '--apply';
 let changeDir = join('openspec', 'changes', change);
-if (phase === 'archive' && !existsSync(changeDir) && existsSync(join('openspec', 'changes', 'archive', change))) {
-  changeDir = join('openspec', 'changes', 'archive', change);
+if (phase === 'archive' &&
+    !existsSync(changeDir) &&
+    existsSync(join('openspec', 'changes', 'archive', change))) {
+    changeDir = join('openspec', 'changes', 'archive', change);
 }
 const yaml = join(changeDir, '.comet.yaml');
 let block = false;
-
 function check(desc, fn) {
-  try {
-    const result = fn();
-    if (result === true || result === undefined) green(`  [PASS] ${desc}`);
-    else throw new Error(String(result));
-  } catch (error) {
-    red(`  [FAIL] ${desc}`);
-    const message = error instanceof Error ? error.message : String(error);
-    if (message) for (const line of message.split(/\r?\n/)) red(`    ${line}`);
-    block = true;
-  }
+    try {
+        const result = fn();
+        if (result === true || result === undefined)
+            green(`  [PASS] ${desc}`);
+        else
+            throw new Error(String(result));
+    }
+    catch (error) {
+        red(`  [FAIL] ${desc}`);
+        const message = error instanceof Error ? error.message : String(error);
+        if (message)
+            for (const line of message.split(/\r?\n/))
+                red(`    ${line}`);
+        block = true;
+    }
 }
-
 function y(field) {
-  return fieldValue(yaml, field);
+    return fieldValue(yaml, field);
 }
-
 function preflight() {
-  if (!existsSync(changeDir)) {
-    red(`FATAL: change directory not found: ${changeDir}`);
-    process.exit(1);
-  }
-  if (!existsSync(yaml)) {
-    red(`FATAL: .comet.yaml not found in ${changeDir}`);
-    process.exit(1);
-  }
-  const validateScript = join(scriptDir, 'comet-yaml-validate.js');
-  if (existsSync(validateScript)) {
-    const result = runNode(validateScript, [change]);
-    if (result.status !== 0) {
-      process.stderr.write(result.stderr || '');
-      red('FATAL: .comet.yaml schema validation failed');
-      process.exit(1);
+    if (!existsSync(changeDir)) {
+        red(`FATAL: change directory not found: ${changeDir}`);
+        process.exit(1);
+    }
+    if (!existsSync(yaml)) {
+        red(`FATAL: .comet.yaml not found in ${changeDir}`);
+        process.exit(1);
+    }
+    const validateScript = join(scriptDir, 'comet-yaml-validate.js');
+    if (existsSync(validateScript)) {
+        const result = runNode(validateScript, [change]);
+        if (result.status !== 0) {
+            process.stderr.write(result.stderr || '');
+            red('FATAL: .comet.yaml schema validation failed');
+            process.exit(1);
+        }
     }
-  }
 }
-
 function tasksAllDone() {
-  const tasks = join(changeDir, 'tasks.md');
-  if (!existsSync(tasks)) throw new Error(`tasks.md is missing at ${tasks}\nNext: restore or create tasks.md for this change before leaving build.`);
-  const text = readFileSync(tasks, 'utf8');
-  if (!/- \[x\]/.test(text)) throw new Error("tasks.md has no completed tasks.\nNext: complete implementation tasks and mark them with '- [x]'.");
-  const unfinished = text.split(/\r?\n/).map((line, index) => ({ line, index: index + 1 })).filter(({ line }) => /- \[ \]/.test(line));
-  if (unfinished.length > 0) {
-    throw new Error(`Unfinished tasks:\n${unfinished.map(({ line, index }) => `${index}:${line}`).join('\n')}\nNext: complete or explicitly remove unfinished tasks, then mark tasks.md with '- [x]'.`);
-  }
+    const tasks = join(changeDir, 'tasks.md');
+    if (!existsSync(tasks))
+        throw new Error(`tasks.md is missing at ${tasks}\nNext: restore or create tasks.md for this change before leaving build.`);
+    const text = readFileSync(tasks, 'utf8');
+    if (!/- \[x\]/.test(text))
+        throw new Error("tasks.md has no completed tasks.\nNext: complete implementation tasks and mark them with '- [x]'.");
+    const unfinished = text
+        .split(/\r?\n/)
+        .map((line, index) => ({ line, index: index + 1 }))
+        .filter(({ line }) => /- \[ \]/.test(line));
+    if (unfinished.length > 0) {
+        throw new Error(`Unfinished tasks:\n${unfinished.map(({ line, index }) => `${index}:${line}`).join('\n')}\nNext: complete or explicitly remove unfinished tasks, then mark tasks.md with '- [x]'.`);
+    }
 }
-
 function tasksHasAny() {
-  return existsSync(join(changeDir, 'tasks.md')) && /- \[/.test(readFileSync(join(changeDir, 'tasks.md'), 'utf8'));
+    return (existsSync(join(changeDir, 'tasks.md')) &&
+        /- \[/.test(readFileSync(join(changeDir, 'tasks.md'), 'utf8')));
 }
-
 function projectConfigValue(field) {
-  const local = y(field);
-  if (local && local !== 'null') return local;
-  for (const config of ['.comet.yaml', 'comet.yaml', '.comet.yml', 'comet.yml']) {
-    if (existsSync(config)) {
-      const value = fieldValue(config, field);
-      if (value && value !== 'null') return value;
+    const local = y(field);
+    if (local && local !== 'null')
+        return local;
+    for (const config of ['.comet.yaml', 'comet.yaml', '.comet.yml', 'comet.yml']) {
+        if (existsSync(config)) {
+            const value = fieldValue(config, field);
+            if (value && value !== 'null')
+                return value;
+        }
     }
-  }
-  return '';
+    return '';
 }
-
 function buildPasses() {
-  if (process.env.COMET_SKIP_BUILD === '1') return;
-  const configured = projectConfigValue('build_command');
-  if (configured) {
-    const result = runCommandString(configured);
-    if (result.status !== 0) throw new Error(`command failed: ${configured}`);
-    return;
-  }
-  if (existsSync('package.json') && /"build"/.test(readFileSync('package.json', 'utf8'))) {
-    const result = runCommand(['npm', 'run', 'build']);
-    if (result.status !== 0) throw new Error('npm run build failed');
-    return;
-  }
-  if (existsSync('pom.xml')) {
-    const result = existsSync('./mvnw') ? runCommand(['./mvnw', 'compile', '-q']) : runCommand(['mvn', 'compile', '-q']);
-    if (result.status !== 0) throw new Error('maven build failed');
-    return;
-  }
-  if (existsSync('Cargo.toml')) {
-    const result = runCommand(['cargo', 'build']);
-    if (result.status !== 0) throw new Error('cargo build failed');
-    return;
-  }
-  throw new Error('no build command found');
+    if (process.env.COMET_SKIP_BUILD === '1')
+        return;
+    const configured = projectConfigValue('build_command');
+    if (configured) {
+        const result = runCommandString(configured);
+        if (result.status !== 0)
+            throw new Error(`command failed: ${configured}`);
+        return;
+    }
+    if (existsSync('package.json') && /"build"/.test(readFileSync('package.json', 'utf8'))) {
+        const result = runCommand(['npm', 'run', 'build']);
+        if (result.status !== 0)
+            throw new Error('npm run build failed');
+        return;
+    }
+    if (existsSync('pom.xml')) {
+        const result = existsSync('./mvnw')
+            ? runCommand(['./mvnw', 'compile', '-q'])
+            : runCommand(['mvn', 'compile', '-q']);
+        if (result.status !== 0)
+            throw new Error('maven build failed');
+        return;
+    }
+    if (existsSync('Cargo.toml')) {
+        const result = runCommand(['cargo', 'build']);
+        if (result.status !== 0)
+            throw new Error('cargo build failed');
+        return;
+    }
+    throw new Error('no build command found');
 }
-
 function verificationCommandPasses() {
-  if (process.env.COMET_SKIP_BUILD === '1') return;
-  const configured = projectConfigValue('verify_command');
-  if (configured) {
-    const result = runCommandString(configured);
-    if (result.status !== 0) throw new Error(`command failed: ${configured}`);
-    return;
-  }
-  buildPasses();
+    if (process.env.COMET_SKIP_BUILD === '1')
+        return;
+    const configured = projectConfigValue('verify_command');
+    if (configured) {
+        const result = runCommandString(configured);
+        if (result.status !== 0)
+            throw new Error(`command failed: ${configured}`);
+        return;
+    }
+    buildPasses();
 }
-
 function sourceFiles() {
-  const files = [join(changeDir, 'proposal.md'), join(changeDir, 'design.md'), join(changeDir, 'tasks.md')];
-  const specsRoot = join(changeDir, 'specs');
-  if (existsSync(specsRoot)) {
-    const { readdirSync, statSync } = awaitFs;
-    function walk(dir) {
-      for (const entry of readdirSync(dir)) {
-        const p = join(dir, entry);
-        const stat = statSync(p);
-        if (stat.isDirectory()) walk(p);
-        else if (entry === 'spec.md') files.push(p);
-      }
+    const files = [
+        join(changeDir, 'proposal.md'),
+        join(changeDir, 'design.md'),
+        join(changeDir, 'tasks.md'),
+    ];
+    const specsRoot = join(changeDir, 'specs');
+    if (existsSync(specsRoot)) {
+        function walk(dir) {
+            for (const entry of readdirSync(dir)) {
+                const p = join(dir, entry);
+                const stat = statSync(p);
+                if (stat.isDirectory())
+                    walk(p);
+                else if (entry === 'spec.md')
+                    files.push(p);
+            }
+        }
+        walk(specsRoot);
     }
-    walk(specsRoot);
-  }
-  return files;
+    return files;
 }
-import * as awaitFs from 'node:fs';
-
 function computeHandoffHash() {
-  let content = '';
-  for (const file of sourceFiles()) if (existsSync(file)) content += `path:${slash(file)}\nsha256:${hashFile(file)}\n`;
-  return sha256(content);
+    let content = '';
+    for (const file of sourceFiles())
+        if (existsSync(file))
+            content += `path:${slash(file)}\nsha256:${hashFile(file)}\n`;
+    return sha256(content);
 }
-
 function designHandoffContextValid() {
-  const context = y('handoff_context');
-  const recordedHash = y('handoff_hash');
-  if (!context || context === 'null') throw new Error('handoff_context is missing from .comet.yaml\nNext: run node "$COMET_HANDOFF" <change> design --write before invoking Superpowers.');
-  if (!fileNonempty(context)) throw new Error(`handoff_context does not point to a non-empty file: ${context}\nNext: regenerate the design handoff with comet-handoff.js.`);
-  if (!/^[a-f0-9]{64}$/.test(recordedHash)) throw new Error(`handoff_hash is missing or invalid: ${recordedHash || 'null'}\nNext: regenerate the design handoff with comet-handoff.js.`);
-  const actualHash = computeHandoffHash();
-  if (actualHash !== recordedHash) throw new Error(`OpenSpec artifacts changed after handoff was generated.\nExpected handoff_hash: ${recordedHash}\nActual handoff_hash:   ${actualHash}\nNext: rerun comet-handoff.js so Superpowers receives the current OpenSpec context.`);
-  const markdown = context.replace(/\.json$/, '.md');
-  if (!fileNonempty(markdown)) throw new Error(`design handoff markdown is missing or empty: ${markdown}\nNext: regenerate the design handoff with comet-handoff.js.`);
+    const context = y('handoff_context');
+    const recordedHash = y('handoff_hash');
+    if (!context || context === 'null')
+        throw new Error('handoff_context is missing from .comet.yaml\nNext: run node "$COMET_HANDOFF" <change> design --write before invoking Superpowers.');
+    if (!fileNonempty(context))
+        throw new Error(`handoff_context does not point to a non-empty file: ${context}\nNext: regenerate the design handoff with comet-handoff.js.`);
+    if (!/^[a-f0-9]{64}$/.test(recordedHash))
+        throw new Error(`handoff_hash is missing or invalid: ${recordedHash || 'null'}\nNext: regenerate the design handoff with comet-handoff.js.`);
+    const actualHash = computeHandoffHash();
+    if (actualHash !== recordedHash)
+        throw new Error(`OpenSpec artifacts changed after handoff was generated.\nExpected handoff_hash: ${recordedHash}\nActual handoff_hash:   ${actualHash}\nNext: rerun comet-handoff.js so Superpowers receives the current OpenSpec context.`);
+    const markdown = context.replace(/\.json$/, '.md');
+    if (!fileNonempty(markdown))
+        throw new Error(`design handoff markdown is missing or empty: ${markdown}\nNext: regenerate the design handoff with comet-handoff.js.`);
 }
-
 function designHandoffMarkdownTraceable() {
-  const context = y('handoff_context');
-  if (!context || context === 'null') throw new Error('handoff_context is missing from .comet.yaml');
-  const markdown = context.replace(/\.json$/, '.md');
-  if (!fileNonempty(markdown)) throw new Error(`design handoff markdown is missing or empty: ${markdown}`);
-  const text = readFileSync(markdown, 'utf8');
-  const missing = [];
-  if (!/^Generated-by: comet-handoff\.js$/m.test(text)) missing.push('handoff markdown is missing Generated-by marker');
-  if (!/^- Mode: (compact|full)$/m.test(text)) missing.push('handoff markdown is missing Mode marker');
-  for (const file of sourceFiles()) {
-    if (!existsSync(file)) continue;
-    if (!text.includes(`- Source: ${slash(file)}`)) missing.push(`handoff markdown is missing source reference: ${slash(file)}`);
-    if (!text.includes(`- SHA256: ${hashFile(file)}`)) missing.push(`handoff markdown is missing current sha256 for: ${file}`);
-  }
-  if (missing.length) throw new Error(missing.join('\n'));
+    const context = y('handoff_context');
+    if (!context || context === 'null')
+        throw new Error('handoff_context is missing from .comet.yaml');
+    const markdown = context.replace(/\.json$/, '.md');
+    if (!fileNonempty(markdown))
+        throw new Error(`design handoff markdown is missing or empty: ${markdown}`);
+    const text = readFileSync(markdown, 'utf8');
+    const missing = [];
+    if (!/^Generated-by: comet-handoff\.js$/m.test(text))
+        missing.push('handoff markdown is missing Generated-by marker');
+    if (!/^- Mode: (compact|full)$/m.test(text))
+        missing.push('handoff markdown is missing Mode marker');
+    for (const file of sourceFiles()) {
+        if (!existsSync(file))
+            continue;
+        if (!text.includes(`- Source: ${slash(file)}`))
+            missing.push(`handoff markdown is missing source reference: ${slash(file)}`);
+        if (!text.includes(`- SHA256: ${hashFile(file)}`))
+            missing.push(`handoff markdown is missing current sha256 for: ${file}`);
+    }
+    if (missing.length)
+        throw new Error(missing.join('\n'));
 }
-
 function frontmatterHas(file, field, expected) {
-  const text = readFileSync(file, 'utf8').replace(/^\uFEFF/, '');
-  const match = text.match(/^\s*---\r?\n([\s\S]*?)\r?\n---/);
-  if (!match) return false;
-  return new RegExp(`^${field}: ['\"]?${expected}['\"]?\\s*$`, 'm').test(match[1]);
+    const text = readFileSync(file, 'utf8').replace(/^\uFEFF/, '');
+    const match = text.match(/^\s*---\r?\n([\s\S]*?)\r?\n---/);
+    if (!match)
+        return false;
+    return new RegExp(`^${field}: ['"]?${expected}['"]?\\s*$`, 'm').test(match[1]);
 }
-
 function guardOpen() {
-  console.error('=== Guard: open → next ===');
-  check('proposal.md exists and non-empty', () => fileNonempty(join(changeDir, 'proposal.md')));
-  check('design.md exists and non-empty', () => fileNonempty(join(changeDir, 'design.md')));
-  check('tasks.md exists and non-empty', () => fileNonempty(join(changeDir, 'tasks.md')));
-  check('tasks.md has at least one task', tasksHasAny);
+    console.error('=== Guard: open → next ===');
+    check('proposal.md exists and non-empty', () => fileNonempty(join(changeDir, 'proposal.md')));
+    check('design.md exists and non-empty', () => fileNonempty(join(changeDir, 'design.md')));
+    check('tasks.md exists and non-empty', () => fileNonempty(join(changeDir, 'tasks.md')));
+    check('tasks.md has at least one task', tasksHasAny);
 }
-
 function guardDesign() {
-  console.error('=== Guard: design → build ===');
-  const designDoc = y('design_doc');
-  check('proposal.md exists', () => fileNonempty(join(changeDir, 'proposal.md')));
-  check('design.md exists', () => fileNonempty(join(changeDir, 'design.md')));
-  check('tasks.md exists', () => fileNonempty(join(changeDir, 'tasks.md')));
-  check('design handoff context exists', designHandoffContextValid);
-  check('design handoff markdown is traceable', designHandoffMarkdownTraceable);
-  if (designDoc && designDoc !== 'null') {
-    check(`Design Doc (${designDoc}) exists`, () => fileNonempty(designDoc));
-    check('Design Doc frontmatter links current change', () => frontmatterHas(designDoc, 'comet_change', change));
-    check('Design Doc declares technical design role', () => frontmatterHas(designDoc, 'role', 'technical-design'));
-    check('Design Doc declares OpenSpec as canonical spec', () => frontmatterHas(designDoc, 'canonical_spec', 'openspec'));
-  } else yellow('  [WARN] No design_doc recorded in .comet.yaml');
+    console.error('=== Guard: design → build ===');
+    const designDoc = y('design_doc');
+    check('proposal.md exists', () => fileNonempty(join(changeDir, 'proposal.md')));
+    check('design.md exists', () => fileNonempty(join(changeDir, 'design.md')));
+    check('tasks.md exists', () => fileNonempty(join(changeDir, 'tasks.md')));
+    check('design handoff context exists', designHandoffContextValid);
+    check('design handoff markdown is traceable', designHandoffMarkdownTraceable);
+    if (designDoc && designDoc !== 'null') {
+        check(`Design Doc (${designDoc}) exists`, () => fileNonempty(designDoc));
+        check('Design Doc frontmatter links current change', () => frontmatterHas(designDoc, 'comet_change', change));
+        check('Design Doc declares technical design role', () => frontmatterHas(designDoc, 'role', 'technical-design'));
+        check('Design Doc declares OpenSpec as canonical spec', () => frontmatterHas(designDoc, 'canonical_spec', 'openspec'));
+    }
+    else
+        yellow('  [WARN] No design_doc recorded in .comet.yaml');
 }
-
 function guardBuild() {
-  console.error('=== Guard: build → verify ===');
-  check('isolation selected', () => ['branch', 'worktree'].includes(y('isolation')) || `isolation must be branch or worktree, got '${y('isolation') || 'null'}'\nNext: ask the user to choose branch or worktree, create the chosen isolation, then run:\n  node "$COMET_STATE" set ${change} isolation <branch|worktree>`);
-  check('build_mode selected', () => ['subagent-driven-development', 'executing-plans', 'direct'].includes(y('build_mode')) || `build_mode must be selected before leaving build, got '${y('build_mode') || 'null'}'\nNext: ask the user to choose an execution mode, then run:\n  node "$COMET_STATE" set ${change} build_mode <subagent-driven-development|executing-plans>`);
-  check('build_mode allowed for workflow', () => y('build_mode') !== 'direct' || ['hotfix', 'tweak'].includes(y('workflow')) || y('direct_override') === 'true' || 'build_mode=direct is only allowed for hotfix/tweak unless direct_override: true is recorded\nNext: choose executing-plans or subagent-driven-development, or stop and ask the user for an explicit direct override.');
-  check('tasks.md all tasks checked', tasksAllDone);
-  check('proposal.md exists', () => fileNonempty(join(changeDir, 'proposal.md')));
-  check('Build passes', buildPasses);
+    console.error('=== Guard: build → verify ===');
+    check('isolation selected', () => ['branch', 'worktree'].includes(y('isolation')) ||
+        `isolation must be branch or worktree, got '${y('isolation') || 'null'}'\nNext: ask the user to choose branch or worktree, create the chosen isolation, then run:\n  node "$COMET_STATE" set ${change} isolation <branch|worktree>`);
+    check('build_mode selected', () => ['subagent-driven-development', 'executing-plans', 'direct'].includes(y('build_mode')) ||
+        `build_mode must be selected before leaving build, got '${y('build_mode') || 'null'}'\nNext: ask the user to choose an execution mode, then run:\n  node "$COMET_STATE" set ${change} build_mode <subagent-driven-development|executing-plans>`);
+    check('build_mode allowed for workflow', () => y('build_mode') !== 'direct' ||
+        ['hotfix', 'tweak'].includes(y('workflow')) ||
+        y('direct_override') === 'true' ||
+        'build_mode=direct is only allowed for hotfix/tweak unless direct_override: true is recorded\nNext: choose executing-plans or subagent-driven-development, or stop and ask the user for an explicit direct override.');
+    check('tasks.md all tasks checked', tasksAllDone);
+    check('proposal.md exists', () => fileNonempty(join(changeDir, 'proposal.md')));
+    check('Build passes', buildPasses);
 }
-
 function guardVerify() {
-  console.error('=== Guard: verify → archive ===');
-  check('tasks.md all tasks checked', tasksAllDone);
-  check('Build passes', verificationCommandPasses);
-  check('verification_report exists', () => y('verification_report') && y('verification_report') !== 'null' && existsSync(y('verification_report')));
-  check('branch_status=handled', () => y('branch_status') === 'handled');
+    console.error('=== Guard: verify → archive ===');
+    check('tasks.md all tasks checked', tasksAllDone);
+    check('Build passes', verificationCommandPasses);
+    check('verification_report exists', () => y('verification_report') &&
+        y('verification_report') !== 'null' &&
+        existsSync(y('verification_report')));
+    check('branch_status=handled', () => y('branch_status') === 'handled');
 }
-
 function guardArchive() {
-  console.error('=== Guard: archive completeness ===');
-  check('archived is true', () => y('archived') === 'true');
-  check('proposal.md exists', () => fileNonempty(join(changeDir, 'proposal.md')));
-  check('tasks.md all tasks checked', tasksAllDone);
+    console.error('=== Guard: archive completeness ===');
+    check('archived is true', () => y('archived') === 'true');
+    check('proposal.md exists', () => fileNonempty(join(changeDir, 'proposal.md')));
+    check('tasks.md all tasks checked', tasksAllDone);
 }
-
 function applyStateUpdate() {
-  const state = join(scriptDir, 'comet-state.js');
-  if (!existsSync(state)) {
-    red('FATAL: comet-state.js not found; cannot apply state transition');
-    process.exit(1);
-  }
-  const event = { open: 'open-complete', design: 'design-complete', build: 'build-complete', verify: 'verify-pass' }[phase];
-  if (event) {
-    const result = runNode(state, ['transition', change, event]);
-    if (result.status !== 0) {
-      process.stderr.write(result.stderr || '');
-      process.exit(result.status ?? 1);
+    const state = join(scriptDir, 'comet-state.js');
+    if (!existsSync(state)) {
+        red('FATAL: comet-state.js not found; cannot apply state transition');
+        process.exit(1);
+    }
+    const eventMap = {
+        open: 'open-complete',
+        design: 'design-complete',
+        build: 'build-complete',
+        verify: 'verify-pass',
+    };
+    const event = eventMap[phase];
+    if (event) {
+        const result = runNode(state, ['transition', change, event]);
+        if (result.status !== 0) {
+            process.stderr.write(result.stderr || '');
+            process.exit(result.status ?? 1);
+        }
     }
-  }
 }
-
 if (!['open', 'design', 'build', 'verify', 'archive'].includes(phase)) {
-  red(`Unknown phase: ${phase}`);
-  console.error('Valid phases: open, design, build, verify, archive');
-  process.exit(1);
+    red(`Unknown phase: ${phase}`);
+    console.error('Valid phases: open, design, build, verify, archive');
+    process.exit(1);
 }
 preflight();
-({ open: guardOpen, design: guardDesign, build: guardBuild, verify: guardVerify, archive: guardArchive }[phase])();
+({
+    open: guardOpen,
+    design: guardDesign,
+    build: guardBuild,
+    verify: guardVerify,
+    archive: guardArchive,
+})[phase]();
 if (block) {
-  console.error('');
-  red('BLOCKED — fix failing checks before proceeding to next phase');
-  process.exit(1);
+    console.error('');
+    red('BLOCKED — fix failing checks before proceeding to next phase');
+    process.exit(1);
 }
 console.error('');
 green('ALL CHECKS PASSED — ready for next phase');
 if (apply) {
-  applyStateUpdate();
-  const messages = {
-    open: `  [APPLY] .comet.yaml updated: phase=${y('phase')}`,
-    design: '  [APPLY] .comet.yaml updated: phase=build',
-    build: '  [APPLY] .comet.yaml updated: phase=verify, verify_result=pending',
-    verify: '  [APPLY] .comet.yaml updated: phase=archive, verify_result=pass',
-  };
-  if (messages[phase]) green(messages[phase]);
+    applyStateUpdate();
+    const messages = {
+        open: `  [APPLY] .comet.yaml updated: phase=${y('phase')}`,
+        design: '  [APPLY] .comet.yaml updated: phase=build',
+        build: '  [APPLY] .comet.yaml updated: phase=verify, verify_result=pending',
+        verify: '  [APPLY] .comet.yaml updated: phase=archive, verify_result=pass',
+    };
+    if (messages[phase])
+        green(messages[phase]);
 }
diff --git a/assets/skills/comet/scripts/comet-handoff.js b/assets/skills/comet/scripts/comet-handoff.js
index 49a6514a..65fdbf4f 100644
--- a/assets/skills/comet/scripts/comet-handoff.js
+++ b/assets/skills/comet/scripts/comet-handoff.js
@@ -1,94 +1,103 @@
 #!/usr/bin/env node
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { existsSync, readFileSync, readdirSync, statSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
-import { ensureDir, fieldValue, fileNonempty, green, hashFile, runNode, scriptDir, sha256, slash, validateChangeName } from './comet-lib.js';
-
+import { ensureDir, fieldValue, fileNonempty, green, hashFile, runNode, scriptDir, sha256, slash, validateChangeName, } from './comet-lib.js';
 function error(message) {
-  console.error(`\u001b[31m${message}\u001b[0m`);
-  process.exit(1);
+    console.error(`\u001b[31m${message}\u001b[0m`);
+    process.exit(1);
 }
-
 function walkSpecFiles(dir) {
-  if (!existsSync(dir)) return [];
-  const { readdirSync, statSync } = awaitFs;
-  const out = [];
-  function walk(current) {
-    for (const entry of readdirSync(current)) {
-      const p = join(current, entry);
-      const stat = statSync(p);
-      if (stat.isDirectory()) walk(p);
-      else if (entry === 'spec.md') out.push(p);
+    if (!existsSync(dir))
+        return [];
+    const out = [];
+    function walk(current) {
+        for (const entry of readdirSync(current)) {
+            const p = join(current, entry);
+            const stat = statSync(p);
+            if (stat.isDirectory())
+                walk(p);
+            else if (entry === 'spec.md')
+                out.push(p);
+        }
     }
-  }
-  walk(dir);
-  return out.sort();
+    walk(dir);
+    return out.sort();
 }
-
-import * as awaitFs from 'node:fs';
-
 function sourceFiles(changeDir) {
-  return [join(changeDir, 'proposal.md'), join(changeDir, 'design.md'), join(changeDir, 'tasks.md'), ...walkSpecFiles(join(changeDir, 'specs'))];
+    return [
+        join(changeDir, 'proposal.md'),
+        join(changeDir, 'design.md'),
+        join(changeDir, 'tasks.md'),
+        ...walkSpecFiles(join(changeDir, 'specs')),
+    ];
 }
-
 function computeContextHash(files) {
-  let content = '';
-  for (const file of files) {
-    if (!existsSync(file)) continue;
-    content += `path:${slash(file)}\nsha256:${hashFile(file)}\n`;
-  }
-  return sha256(content);
+    let content = '';
+    for (const file of files) {
+        if (!existsSync(file))
+            continue;
+        content += `path:${slash(file)}\nsha256:${hashFile(file)}\n`;
+    }
+    return sha256(content);
 }
-
 function writeMarkdown(output, files, change, mode, contextHash) {
-  const chunks = [
-    '# Comet Design Handoff',
-    '',
-    `- Change: ${change}`,
-    '- Phase: design',
-    `- Mode: ${mode}`,
-    `- Context hash: ${contextHash}`,
-    '',
-    'Generated-by: comet-handoff.js',
-    '',
-    'OpenSpec remains the canonical capability spec. This handoff is a deterministic, source-traceable context pack, not an agent-authored summary.',
-    '',
-  ];
-  for (const file of files) {
-    if (!existsSync(file)) continue;
-    const text = readFileSync(file, 'utf8');
-    const lines = text.split(/\r?\n/);
-    chunks.push(`## ${slash(file)}`, '', `- Source: ${slash(file)}`, `- Lines: 1-${lines.length}`, `- SHA256: ${hashFile(file)}`, '');
-    if (mode === 'full' || lines.length <= 80) chunks.push('```md', text.replace(/\s*$/, ''), '```');
-    else chunks.push('[TRUNCATED]', '', '```md', lines.slice(0, 80).join('\n'), '```', '', `Full source: ${slash(file)}`);
-    chunks.push('');
-  }
-  writeFileSync(output, `${chunks.join('\n')}\n`);
+    const chunks = [
+        '# Comet Design Handoff',
+        '',
+        `- Change: ${change}`,
+        '- Phase: design',
+        `- Mode: ${mode}`,
+        `- Context hash: ${contextHash}`,
+        '',
+        'Generated-by: comet-handoff.js',
+        '',
+        'OpenSpec remains the canonical capability spec. This handoff is a deterministic, source-traceable context pack, not an agent-authored summary.',
+        '',
+    ];
+    for (const file of files) {
+        if (!existsSync(file))
+            continue;
+        const text = readFileSync(file, 'utf8');
+        const lines = text.split(/\r?\n/);
+        chunks.push(`## ${slash(file)}`, '', `- Source: ${slash(file)}`, `- Lines: 1-${lines.length}`, `- SHA256: ${hashFile(file)}`, '');
+        if (mode === 'full' || lines.length <= 80)
+            chunks.push('```md', text.replace(/\s*$/, ''), '```');
+        else
+            chunks.push('[TRUNCATED]', '', '```md', lines.slice(0, 80).join('\n'), '```', '', `Full source: ${slash(file)}`);
+        chunks.push('');
+    }
+    writeFileSync(output, `${chunks.join('\n')}\n`);
 }
-
 function writeJson(output, files, change, mode, contextHash) {
-  const body = {
-    change,
-    phase: 'design',
-    mode,
-    canonical_spec: 'openspec',
-    generated_by: 'comet-handoff.js',
-    context_hash: contextHash,
-    files: files.filter((file) => existsSync(file)).map((file) => ({ path: slash(file), sha256: hashFile(file) })),
-  };
-  writeFileSync(output, `${JSON.stringify(body, null, 2)}\n`);
+    const body = {
+        change,
+        phase: 'design',
+        mode,
+        canonical_spec: 'openspec',
+        generated_by: 'comet-handoff.js',
+        context_hash: contextHash,
+        files: files
+            .filter((file) => existsSync(file))
+            .map((file) => ({ path: slash(file), sha256: hashFile(file) })),
+    };
+    writeFileSync(output, `${JSON.stringify(body, null, 2)}\n`);
 }
-
 const [change, phase, modeArg, fullFlag] = process.argv.slice(2);
 validateChangeName(change);
-if (phase !== 'design' || modeArg !== '--write' || (fullFlag && fullFlag !== '--full')) error('Usage: comet-handoff.js <change-name> design --write [--full]');
+if (phase !== 'design' || modeArg !== '--write' || (fullFlag && fullFlag !== '--full'))
+    error('Usage: comet-handoff.js <change-name> design --write [--full]');
 const handoffMode = fullFlag === '--full' ? 'full' : 'compact';
 const changeDir = join('openspec', 'changes', change);
 const yaml = join(changeDir, '.comet.yaml');
-if (!existsSync(changeDir)) error(`ERROR: change directory not found: ${changeDir}`);
-if (!existsSync(yaml)) error(`ERROR: .comet.yaml not found at ${yaml}`);
-if (fieldValue(yaml, 'phase') !== 'design') error('ERROR: design handoff requires phase: design');
+if (!existsSync(changeDir))
+    error(`ERROR: change directory not found: ${changeDir}`);
+if (!existsSync(yaml))
+    error(`ERROR: .comet.yaml not found at ${yaml}`);
+if (fieldValue(yaml, 'phase') !== 'design')
+    error('ERROR: design handoff requires phase: design');
 for (const required of ['proposal.md', 'design.md', 'tasks.md']) {
-  if (!fileNonempty(join(changeDir, required))) error(`ERROR: required OpenSpec artifact missing or empty: ${join(changeDir, required)}`);
+    if (!fileNonempty(join(changeDir, required)))
+        error(`ERROR: required OpenSpec artifact missing or empty: ${join(changeDir, required)}`);
 }
 const handoffDir = join(changeDir, '.comet', 'handoff');
 const contextJson = slash(join(handoffDir, 'design-context.json'));
@@ -99,11 +108,14 @@ const contextHash = computeContextHash(files);
 writeMarkdown(contextMd, files, change, handoffMode, contextHash);
 writeJson(contextJson, files, change, handoffMode, contextHash);
 const stateScript = join(scriptDir, 'comet-state.js');
-if (!existsSync(stateScript)) error('ERROR: comet-state.js not found; cannot record handoff fields');
+if (!existsSync(stateScript))
+    error('ERROR: comet-state.js not found; cannot record handoff fields');
 let result = runNode(stateScript, ['set', change, 'handoff_context', contextJson]);
-if (result.status !== 0) process.exit(result.status ?? 1);
+if (result.status !== 0)
+    process.exit(result.status ?? 1);
 result = runNode(stateScript, ['set', change, 'handoff_hash', contextHash]);
-if (result.status !== 0) process.exit(result.status ?? 1);
+if (result.status !== 0)
+    process.exit(result.status ?? 1);
 green(`[HANDOFF] wrote ${contextJson}`);
 green(`[HANDOFF] wrote ${contextMd}`);
 green(`[HANDOFF] handoff_hash=${contextHash}`);
diff --git a/assets/skills/comet/scripts/comet-lib.js b/assets/skills/comet/scripts/comet-lib.js
index f2267e5d..0da1638f 100644
--- a/assets/skills/comet/scripts/comet-lib.js
+++ b/assets/skills/comet/scripts/comet-lib.js
@@ -4,209 +4,206 @@ import { existsSync, mkdirSync, readFileSync, statSync, writeFileSync } from 'no
 import { dirname, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { spawnSync } from 'node:child_process';
-
 export const scriptDir = dirname(fileURLToPath(import.meta.url));
-
 export const FIELD_ORDER = [
-  'workflow',
-  'phase',
-  'build_mode',
-  'build_pause',
-  'isolation',
-  'verify_mode',
-  'base_ref',
-  'design_doc',
-  'plan',
-  'verify_result',
-  'verification_report',
-  'branch_status',
-  'created_at',
-  'verified_at',
-  'archived',
-  'direct_override',
-  'build_command',
-  'verify_command',
-  'handoff_context',
-  'handoff_hash',
+    'workflow',
+    'phase',
+    'build_mode',
+    'build_pause',
+    'isolation',
+    'verify_mode',
+    'base_ref',
+    'design_doc',
+    'plan',
+    'verify_result',
+    'verification_report',
+    'branch_status',
+    'created_at',
+    'verified_at',
+    'archived',
+    'direct_override',
+    'build_command',
+    'verify_command',
+    'handoff_context',
+    'handoff_hash',
 ];
-
 export const KNOWN_KEYS = new Set(FIELD_ORDER);
-
 export function color(code, message) {
-  return `\u001b[${code}m${message}\u001b[0m`;
+    return `\u001b[${code}m${message}\u001b[0m`;
 }
-
 export function red(message) {
-  console.error(color(31, message));
+    console.error(color(31, message));
 }
-
 export function green(message) {
-  console.error(color(32, message));
+    console.error(color(32, message));
 }
-
 export function yellow(message) {
-  console.error(color(33, message));
+    console.error(color(33, message));
 }
-
 export function fail(message, prefix = 'ERROR') {
-  red(`${prefix}: ${message}`);
-  process.exit(1);
+    red(`${prefix}: ${message}`);
+    process.exit(1);
 }
-
 export function validateChangeName(name, prefix = 'ERROR') {
-  if (!name) fail('Change name cannot be empty', prefix);
-  if (!/^[a-zA-Z0-9_-]+$/.test(name)) {
-    red(`${prefix}: Invalid change name: '${name}'`);
-    red('Valid characters: a-z, A-Z, 0-9, -, _');
-    process.exit(1);
-  }
-  if (name.includes('..')) fail("Change name cannot contain '..' (path traversal not allowed)", prefix);
+    if (!name)
+        fail('Change name cannot be empty', prefix);
+    if (!/^[a-zA-Z0-9_-]+$/.test(name)) {
+        red(`${prefix}: Invalid change name: '${name}'`);
+        red('Valid characters: a-z, A-Z, 0-9, -, _');
+        process.exit(1);
+    }
+    if (name.includes('..'))
+        fail("Change name cannot contain '..' (path traversal not allowed)", prefix);
 }
-
 export function validateEnum(value, validValues) {
-  if (validValues.includes(value)) return;
-  red(`ERROR: Invalid value: '${value}'`);
-  red(`Valid values: ${validValues.join(' ')}`);
-  process.exit(1);
+    if (validValues.includes(value))
+        return;
+    red(`ERROR: Invalid value: '${value}'`);
+    red(`Valid values: ${validValues.join(' ')}`);
+    process.exit(1);
 }
-
 export function stripInlineComment(value) {
-  let out = '';
-  let quote = '';
-  for (let i = 0; i < value.length; i += 1) {
-    const c = value[i];
-    if (!quote) {
-      if (c === '"' || c === "'") quote = c;
-      else if (c === '#' && (i === 0 || /\s/.test(value[i - 1]))) return out.trimEnd();
-    } else if (c === quote) {
-      quote = '';
+    let out = '';
+    let quote = '';
+    for (let i = 0; i < value.length; i += 1) {
+        const c = value[i];
+        if (!quote) {
+            if (c === '"' || c === "'")
+                quote = c;
+            else if (c === '#' && (i === 0 || /\s/.test(value[i - 1])))
+                return out.trimEnd();
+        }
+        else if (c === quote) {
+            quote = '';
+        }
+        out += c;
     }
-    out += c;
-  }
-  return out;
+    return out;
 }
-
 export function stripWrappingQuotes(value) {
-  if (value.length >= 2) {
-    const first = value[0];
-    const last = value[value.length - 1];
-    if (first === '"' && last === '"') {
-      try {
-        return JSON.parse(value);
-      } catch {
-        return value.slice(1, -1);
-      }
+    if (value.length >= 2) {
+        const first = value[0];
+        const last = value[value.length - 1];
+        if (first === '"' && last === '"') {
+            try {
+                return JSON.parse(value);
+            }
+            catch {
+                return value.slice(1, -1);
+            }
+        }
+        if (first === "'" && last === "'")
+            return value.slice(1, -1);
     }
-    if (first === "'" && last === "'") return value.slice(1, -1);
-  }
-  return value;
+    return value;
 }
-
 export function parseYamlLines(file) {
-  const text = readFileSync(file, 'utf8');
-  const data = {};
-  const keys = [];
-  for (const line of text.split(/\r?\n/)) {
-    const match = line.match(/^([^\s:#][^:]*):\s*(.*)$/);
-    if (!match) continue;
-    const key = match[1].trim();
-    const value = stripWrappingQuotes(stripInlineComment(match[2] ?? ''));
-    data[key] = value;
-    keys.push(key);
-  }
-  return { data, keys, text };
-}
-
+    const text = readFileSync(file, 'utf8');
+    const data = {};
+    const keys = [];
+    for (const line of text.split(/\r?\n/)) {
+        const match = line.match(/^([^\s:#][^:]*):\s*(.*)$/);
+        if (!match)
+            continue;
+        const key = match[1].trim();
+        const value = stripWrappingQuotes(stripInlineComment(match[2] ?? ''));
+        data[key] = value;
+        keys.push(key);
+    }
+    return { data, keys, text };
+}
 export function fieldValue(file, field) {
-  if (!existsSync(file)) return '';
-  return parseYamlLines(file).data[field] ?? '';
+    if (!existsSync(file))
+        return '';
+    return parseYamlLines(file).data[field] ?? '';
 }
-
 function formatYamlValue(value) {
-  const stringValue = String(value);
-  if (stringValue === '') return '';
-  if (/^[A-Za-z0-9_./:@\\-]+$/.test(stringValue)) return stringValue;
-  return JSON.stringify(stringValue);
+    const stringValue = String(value);
+    if (stringValue === '')
+        return '';
+    if (/^[A-Za-z0-9_./:@\\-]+$/.test(stringValue))
+        return stringValue;
+    return JSON.stringify(stringValue);
 }
-
 export function writeYamlData(file, data) {
-  const lines = [];
-  for (const key of FIELD_ORDER) {
-    if (Object.prototype.hasOwnProperty.call(data, key)) lines.push(`${key}: ${formatYamlValue(data[key])}`);
-  }
-  for (const key of Object.keys(data)) {
-    if (!FIELD_ORDER.includes(key)) lines.push(`${key}: ${formatYamlValue(data[key])}`);
-  }
-  writeFileSync(file, `${lines.join('\n')}\n`);
-}
-
+    const lines = [];
+    for (const key of FIELD_ORDER) {
+        if (Object.prototype.hasOwnProperty.call(data, key))
+            lines.push(`${key}: ${formatYamlValue(data[key])}`);
+    }
+    for (const key of Object.keys(data)) {
+        if (!FIELD_ORDER.includes(key))
+            lines.push(`${key}: ${formatYamlValue(data[key])}`);
+    }
+    writeFileSync(file, `${lines.join('\n')}\n`);
+}
 export function setYamlField(file, field, value) {
-  const { data } = parseYamlLines(file);
-  data[field] = String(value);
-  writeYamlData(file, data);
+    const { data } = parseYamlLines(file);
+    data[field] = String(value);
+    writeYamlData(file, data);
 }
-
 export function fileNonempty(file) {
-  try {
-    return statSync(file).isFile() && statSync(file).size > 0;
-  } catch {
-    return false;
-  }
+    try {
+        return statSync(file).isFile() && statSync(file).size > 0;
+    }
+    catch {
+        return false;
+    }
 }
-
 export function changeDirFor(changeName) {
-  const active = join('openspec', 'changes', changeName);
-  const archived = join('openspec', 'changes', 'archive', changeName);
-  if (existsSync(active)) return active;
-  if (existsSync(archived)) return archived;
-  return active;
+    const active = join('openspec', 'changes', changeName);
+    const archived = join('openspec', 'changes', 'archive', changeName);
+    if (existsSync(active))
+        return active;
+    if (existsSync(archived))
+        return archived;
+    return active;
 }
-
 export function yamlFileFor(changeName) {
-  return join(changeDirFor(changeName), '.comet.yaml');
+    return join(changeDirFor(changeName), '.comet.yaml');
 }
-
 export function today() {
-  return new Date().toISOString().slice(0, 10);
+    return new Date().toISOString().slice(0, 10);
 }
-
 export function git(args) {
-  return spawnSync('git', args, { encoding: 'utf8' });
+    return spawnSync('git', args, { encoding: 'utf8' });
 }
-
 export function currentHeadOrNull() {
-  const verify = git(['rev-parse', '--verify', 'HEAD']);
-  if (verify.status !== 0) return 'null';
-  const head = git(['rev-parse', 'HEAD']);
-  return head.status === 0 ? head.stdout.trim() : 'null';
+    const verify = git(['rev-parse', '--verify', 'HEAD']);
+    if (verify.status !== 0)
+        return 'null';
+    const head = git(['rev-parse', 'HEAD']);
+    return head.status === 0 ? head.stdout.trim() : 'null';
 }
-
 export function sha256(content) {
-  return createHash('sha256').update(content).digest('hex');
+    return createHash('sha256').update(content).digest('hex');
 }
-
 export function hashFile(file) {
-  return sha256(readFileSync(file));
+    return sha256(readFileSync(file));
 }
-
 export function ensureDir(dir) {
-  mkdirSync(dir, { recursive: true });
+    mkdirSync(dir, { recursive: true });
 }
-
 export function runNode(script, args, options = {}) {
-  return spawnSync(process.execPath, [script, ...args], { encoding: 'utf8', stdio: 'pipe', ...options });
+    return spawnSync(process.execPath, [script, ...args], {
+        encoding: 'utf8',
+        stdio: 'pipe',
+        ...options,
+    });
 }
-
 export function runCommandString(command, options = {}) {
-  console.error(`+ ${command}`);
-  return spawnSync(command, { encoding: 'utf8', stdio: 'inherit', shell: true, ...options });
+    console.error(`+ ${command}`);
+    return spawnSync(command, { encoding: 'utf8', stdio: 'inherit', shell: true, ...options });
 }
-
 export function runCommand(argv, options = {}) {
-  const [command, ...args] = argv;
-  return spawnSync(command, args, { encoding: 'utf8', stdio: 'inherit', shell: process.platform === 'win32', ...options });
+    const [command, ...args] = argv;
+    return spawnSync(command, args, {
+        encoding: 'utf8',
+        stdio: 'inherit',
+        shell: process.platform === 'win32',
+        ...options,
+    });
 }
-
 export function slash(file) {
-  return file.replace(/\\/g, '/');
+    return file.replace(/\\/g, '/');
 }
diff --git a/assets/skills/comet/scripts/comet-state.js b/assets/skills/comet/scripts/comet-state.js
index e23d410d..8eaab2bd 100644
--- a/assets/skills/comet/scripts/comet-state.js
+++ b/assets/skills/comet/scripts/comet-state.js
@@ -1,384 +1,471 @@
 #!/usr/bin/env node
 import { existsSync, mkdirSync, readdirSync, readFileSync } from 'node:fs';
 import { join } from 'node:path';
-import {
-  changeDirFor,
-  currentHeadOrNull,
-  fail,
-  fieldValue,
-  fileNonempty,
-  git,
-  green,
-  red,
-  setYamlField,
-  today,
-  validateChangeName,
-  validateEnum,
-  writeYamlData,
-  yamlFileFor,
-  yellow,
-} from './comet-lib.js';
-
+import { changeDirFor, currentHeadOrNull, fail, fieldValue, fileNonempty, git, green, red, setYamlField, today, validateChangeName, validateEnum, writeYamlData, yamlFileFor, yellow, } from './comet-lib.js';
 const ENUMS = {
-  workflow: ['full', 'hotfix', 'tweak'],
-  phase: ['open', 'design', 'build', 'verify', 'archive'],
-  build_mode: ['subagent-driven-development', 'executing-plans', 'direct'],
-  build_pause: ['null', 'plan-ready'],
-  isolation: ['branch', 'worktree'],
-  verify_mode: ['light', 'full'],
-  verify_result: ['pending', 'pass', 'fail'],
-  branch_status: ['pending', 'handled'],
-  archived: ['true', 'false'],
-  direct_override: ['true', 'false'],
+    workflow: ['full', 'hotfix', 'tweak'],
+    phase: ['open', 'design', 'build', 'verify', 'archive'],
+    build_mode: ['subagent-driven-development', 'executing-plans', 'direct'],
+    build_pause: ['null', 'plan-ready'],
+    isolation: ['branch', 'worktree'],
+    verify_mode: ['light', 'full'],
+    verify_result: ['pending', 'pass', 'fail'],
+    branch_status: ['pending', 'handled'],
+    archived: ['true', 'false'],
+    direct_override: ['true', 'false'],
 };
-
 const SET_FIELDS = new Set([
-  'workflow',
-  'phase',
-  'build_mode',
-  'build_pause',
-  'isolation',
-  'verify_mode',
-  'verify_result',
-  'verification_report',
-  'branch_status',
-  'archived',
-  'design_doc',
-  'plan',
-  'verified_at',
-  'created_at',
-  'direct_override',
-  'build_command',
-  'verify_command',
-  'handoff_context',
-  'handoff_hash',
-  'base_ref',
+    'workflow',
+    'phase',
+    'build_mode',
+    'build_pause',
+    'isolation',
+    'verify_mode',
+    'verify_result',
+    'verification_report',
+    'branch_status',
+    'archived',
+    'design_doc',
+    'plan',
+    'verified_at',
+    'created_at',
+    'direct_override',
+    'build_command',
+    'verify_command',
+    'handoff_context',
+    'handoff_hash',
+    'base_ref',
 ]);
-
 function get(change, field) {
-  validateChangeName(change);
-  const yaml = yamlFileFor(change);
-  if (!existsSync(yaml)) fail(`.comet.yaml not found at ${yaml}`);
-  console.log(fieldValue(yaml, field));
+    validateChangeName(change);
+    const yaml = yamlFileFor(change);
+    if (!existsSync(yaml))
+        fail(`.comet.yaml not found at ${yaml}`);
+    console.log(fieldValue(yaml, field));
 }
-
 function getValue(change, field) {
-  const yaml = yamlFileFor(change);
-  return fieldValue(yaml, field);
+    const yaml = yamlFileFor(change);
+    return fieldValue(yaml, field);
 }
-
 function set(change, field, value, quiet = false) {
-  validateChangeName(change);
-  const yaml = yamlFileFor(change);
-  if (!existsSync(yaml)) fail(`.comet.yaml not found at ${yaml}`);
-  if (field === 'phase') {
-    yellow("WARNING: Setting 'phase' directly bypasses state machine constraints.");
-    yellow('  Consider using: comet-state.js transition <change-name> <event>');
-  } else if (!SET_FIELDS.has(field)) {
-    red(`ERROR: Unknown field: '${field}'`);
-    red('Valid fields:');
-    red('  workflow, phase, design_doc, plan, build_mode, build_pause, isolation,');
-    red('  verify_mode, verify_result, verification_report, branch_status,');
-    red('  verified_at, created_at, archived, base_ref, direct_override,');
-    red('  build_command, verify_command, handoff_context, handoff_hash');
-    process.exit(1);
-  }
-  if (ENUMS[field]) validateEnum(value, ENUMS[field]);
-  setYamlField(yaml, field, value);
-  if (!quiet) green(`[SET] ${field}=${value}`);
+    validateChangeName(change);
+    const yaml = yamlFileFor(change);
+    if (!existsSync(yaml))
+        fail(`.comet.yaml not found at ${yaml}`);
+    if (field === 'phase') {
+        yellow("WARNING: Setting 'phase' directly bypasses state machine constraints.");
+        yellow('  Consider using: comet-state.js transition <change-name> <event>');
+    }
+    else if (!SET_FIELDS.has(field)) {
+        red(`ERROR: Unknown field: '${field}'`);
+        red('Valid fields:');
+        red('  workflow, phase, design_doc, plan, build_mode, build_pause, isolation,');
+        red('  verify_mode, verify_result, verification_report, branch_status,');
+        red('  verified_at, created_at, archived, base_ref, direct_override,');
+        red('  build_command, verify_command, handoff_context, handoff_hash');
+        process.exit(1);
+    }
+    if (ENUMS[field])
+        validateEnum(value, ENUMS[field]);
+    setYamlField(yaml, field, value);
+    if (!quiet)
+        green(`[SET] ${field}=${value}`);
 }
-
 function init(change, workflow) {
-  validateChangeName(change);
-  validateEnum(workflow, ENUMS.workflow);
-  const changeDir = changeDirFor(change);
-  const yaml = yamlFileFor(change);
-  if (existsSync(yaml)) fail(`.comet.yaml already exists at ${yaml}`);
-  mkdirSync(changeDir, { recursive: true });
-  const preset = workflow === 'full' ? ['null', 'null', 'null'] : ['direct', 'branch', 'light'];
-  writeYamlData(yaml, {
-    workflow,
-    phase: 'open',
-    build_mode: preset[0],
-    build_pause: 'null',
-    isolation: preset[1],
-    verify_mode: preset[2],
-    base_ref: currentHeadOrNull(),
-    design_doc: 'null',
-    plan: 'null',
-    verify_result: 'pending',
-    verification_report: 'null',
-    branch_status: 'pending',
-    created_at: today(),
-    verified_at: 'null',
-    archived: 'false',
-  });
-  green(`Initialized: ${yaml} (workflow=${workflow})`);
+    validateChangeName(change);
+    validateEnum(workflow, ENUMS.workflow);
+    const changeDir = changeDirFor(change);
+    const yaml = yamlFileFor(change);
+    if (existsSync(yaml))
+        fail(`.comet.yaml already exists at ${yaml}`);
+    mkdirSync(changeDir, { recursive: true });
+    const preset = workflow === 'full' ? ['null', 'null', 'null'] : ['direct', 'branch', 'light'];
+    writeYamlData(yaml, {
+        workflow,
+        phase: 'open',
+        build_mode: preset[0],
+        build_pause: 'null',
+        isolation: preset[1],
+        verify_mode: preset[2],
+        base_ref: currentHeadOrNull(),
+        design_doc: 'null',
+        plan: 'null',
+        verify_result: 'pending',
+        verification_report: 'null',
+        branch_status: 'pending',
+        created_at: today(),
+        verified_at: 'null',
+        archived: 'false',
+    });
+    green(`Initialized: ${yaml} (workflow=${workflow})`);
 }
-
 function requirePhase(change, expected) {
-  const actual = getValue(change, 'phase');
-  if (actual !== expected) fail(`Cannot transition '${change}': expected phase ${expected}, got ${actual}`);
+    const actual = getValue(change, 'phase');
+    if (actual !== expected)
+        fail(`Cannot transition '${change}': expected phase ${expected}, got ${actual}`);
 }
-
 function requireVerificationEvidence(change) {
-  const report = getValue(change, 'verification_report');
-  const branchStatus = getValue(change, 'branch_status');
-  if (!report || report === 'null' || !existsSync(report)) {
-    fail(`Cannot transition '${change}': verification_report must point to an existing report file`);
-  }
-  if (branchStatus !== 'handled') fail(`Cannot transition '${change}': branch_status must be handled`);
+    const report = getValue(change, 'verification_report');
+    const branchStatus = getValue(change, 'branch_status');
+    if (!report || report === 'null' || !existsSync(report)) {
+        fail(`Cannot transition '${change}': verification_report must point to an existing report file`);
+    }
+    if (branchStatus !== 'handled')
+        fail(`Cannot transition '${change}': branch_status must be handled`);
 }
-
 function requireBuildDecisions(change) {
-  const workflow = getValue(change, 'workflow');
-  const buildMode = getValue(change, 'build_mode');
-  const isolation = getValue(change, 'isolation');
-  const directOverride = getValue(change, 'direct_override');
-  if (!['branch', 'worktree'].includes(isolation)) {
-    fail(`Cannot transition '${change}': isolation must be branch or worktree, got '${isolation || 'null'}'`);
-  }
-  if (!ENUMS.build_mode.includes(buildMode)) {
-    fail(`Cannot transition '${change}': build_mode must be selected before leaving build, got '${buildMode || 'null'}'`);
-  }
-  if (buildMode === 'direct' && !['hotfix', 'tweak'].includes(workflow) && directOverride !== 'true') {
-    fail(`Cannot transition '${change}': build_mode=direct is only allowed for hotfix/tweak unless direct_override=true`);
-  }
+    const workflow = getValue(change, 'workflow');
+    const buildMode = getValue(change, 'build_mode');
+    const isolation = getValue(change, 'isolation');
+    const directOverride = getValue(change, 'direct_override');
+    if (!['branch', 'worktree'].includes(isolation)) {
+        fail(`Cannot transition '${change}': isolation must be branch or worktree, got '${isolation || 'null'}'`);
+    }
+    if (!ENUMS.build_mode.includes(buildMode)) {
+        fail(`Cannot transition '${change}': build_mode must be selected before leaving build, got '${buildMode || 'null'}'`);
+    }
+    if (buildMode === 'direct' &&
+        !['hotfix', 'tweak'].includes(workflow) &&
+        directOverride !== 'true') {
+        fail(`Cannot transition '${change}': build_mode=direct is only allowed for hotfix/tweak unless direct_override=true`);
+    }
 }
-
 function transition(change, event) {
-  validateChangeName(change);
-  validateEnum(event, ['open-complete', 'design-complete', 'build-complete', 'verify-pass', 'verify-fail', 'archived']);
-  if (event === 'open-complete') {
-    requirePhase(change, 'open');
-    set(change, 'phase', getValue(change, 'workflow') === 'full' ? 'design' : 'build', true);
-  } else if (event === 'design-complete') {
-    requirePhase(change, 'design');
-    set(change, 'phase', 'build', true);
-  } else if (event === 'build-complete') {
-    requirePhase(change, 'build');
-    requireBuildDecisions(change);
-    set(change, 'phase', 'verify', true);
-    set(change, 'verify_result', 'pending', true);
-    set(change, 'verification_report', 'null', true);
-    set(change, 'branch_status', 'pending', true);
-  } else if (event === 'verify-pass') {
-    requirePhase(change, 'verify');
-    requireVerificationEvidence(change);
-    set(change, 'verify_result', 'pass', true);
-    set(change, 'phase', 'archive', true);
-    set(change, 'verified_at', today(), true);
-  } else if (event === 'verify-fail') {
-    requirePhase(change, 'verify');
-    set(change, 'verify_result', 'fail', true);
-    set(change, 'phase', 'build', true);
-    set(change, 'branch_status', 'pending', true);
-  } else if (event === 'archived') {
-    requirePhase(change, 'archive');
-    set(change, 'archived', 'true', true);
-  }
-  green(`[TRANSITION] ${event}`);
+    validateChangeName(change);
+    validateEnum(event, [
+        'open-complete',
+        'design-complete',
+        'build-complete',
+        'verify-pass',
+        'verify-fail',
+        'archived',
+    ]);
+    if (event === 'open-complete') {
+        requirePhase(change, 'open');
+        set(change, 'phase', getValue(change, 'workflow') === 'full' ? 'design' : 'build', true);
+    }
+    else if (event === 'design-complete') {
+        requirePhase(change, 'design');
+        set(change, 'phase', 'build', true);
+    }
+    else if (event === 'build-complete') {
+        requirePhase(change, 'build');
+        requireBuildDecisions(change);
+        set(change, 'phase', 'verify', true);
+        set(change, 'verify_result', 'pending', true);
+        set(change, 'verification_report', 'null', true);
+        set(change, 'branch_status', 'pending', true);
+    }
+    else if (event === 'verify-pass') {
+        requirePhase(change, 'verify');
+        requireVerificationEvidence(change);
+        set(change, 'verify_result', 'pass', true);
+        set(change, 'phase', 'archive', true);
+        set(change, 'verified_at', today(), true);
+    }
+    else if (event === 'verify-fail') {
+        requirePhase(change, 'verify');
+        set(change, 'verify_result', 'fail', true);
+        set(change, 'phase', 'build', true);
+        set(change, 'branch_status', 'pending', true);
+    }
+    else if (event === 'archived') {
+        requirePhase(change, 'archive');
+        set(change, 'archived', 'true', true);
+    }
+    green(`[TRANSITION] ${event}`);
 }
-
 let checkBlock = false;
-function pass(msg) { console.log(`  \u001b[32m[PASS]\u001b[0m ${msg}`); }
-function block(msg) { console.log(`  \u001b[31m[FAIL]\u001b[0m ${msg}`); checkBlock = true; }
-function checkNonempty(desc, file) { fileNonempty(file) ? pass(`${desc} non-empty`) : block(`${desc} missing or empty`); }
+function pass(msg) {
+    console.log(`  \u001b[32m[PASS]\u001b[0m ${msg}`);
+}
+function block(msg) {
+    console.log(`  \u001b[31m[FAIL]\u001b[0m ${msg}`);
+    checkBlock = true;
+}
+function checkNonempty(desc, file) {
+    if (fileNonempty(file))
+        pass(`${desc} non-empty`);
+    else
+        block(`${desc} missing or empty`);
+}
 function checkYamlIs(field, expected, change) {
-  const actual = getValue(change, field);
-  actual === expected ? pass(`${field}=${actual} (expected: ${expected})`) : block(`${field}=${actual} (expected: ${expected})`);
+    const actual = getValue(change, field);
+    if (actual === expected)
+        pass(`${field}=${actual} (expected: ${expected})`);
+    else
+        block(`${field}=${actual} (expected: ${expected})`);
 }
 function checkYamlEmpty(field, change) {
-  const value = getValue(change, field);
-  !value || value === 'null' ? pass(`${field} is empty/null`) : block(`${field}=${value} (expected: empty/null)`);
+    const value = getValue(change, field);
+    if (!value || value === 'null')
+        pass(`${field} is empty/null`);
+    else
+        block(`${field}=${value} (expected: empty/null)`);
 }
-
 function check(change, phase) {
-  validateChangeName(change);
-  validateEnum(phase, ['open', 'design', 'build', 'verify', 'archive']);
-  checkBlock = false;
-  const changeDir = join('openspec', 'changes', change);
-  const yaml = join(changeDir, '.comet.yaml');
-  console.log(`=== Entry Check: comet-${phase} ===`);
-  if (!existsSync(yaml)) fail(`.comet.yaml not found at ${yaml}`);
-  if (phase === 'open') {
-    pass('.comet.yaml exists');
-    checkYamlIs('phase', 'open', change);
-  } else if (phase === 'design') {
-    pass('.comet.yaml exists');
-    checkYamlIs('phase', 'design', change);
-    checkYamlIs('workflow', 'full', change);
-    checkYamlEmpty('design_doc', change);
-    checkNonempty('proposal.md', join(changeDir, 'proposal.md'));
-    checkNonempty('design.md', join(changeDir, 'design.md'));
-    checkNonempty('tasks.md', join(changeDir, 'tasks.md'));
-  } else if (phase === 'build') {
-    pass('.comet.yaml exists');
-    checkYamlIs('phase', 'build', change);
-    const workflow = getValue(change, 'workflow');
-    if (workflow === 'full') {
-      const designDoc = getValue(change, 'design_doc');
-      designDoc && designDoc !== 'null' && existsSync(designDoc)
-        ? pass(`design_doc=${designDoc} (file exists)`)
-        : block(`design_doc=${designDoc} (expected: non-null and file exists)`);
-    } else {
-      pass(`workflow=${workflow} (design_doc not required)`);
+    validateChangeName(change);
+    validateEnum(phase, ['open', 'design', 'build', 'verify', 'archive']);
+    checkBlock = false;
+    const changeDir = join('openspec', 'changes', change);
+    const yaml = join(changeDir, '.comet.yaml');
+    console.log(`=== Entry Check: comet-${phase} ===`);
+    if (!existsSync(yaml))
+        fail(`.comet.yaml not found at ${yaml}`);
+    if (phase === 'open') {
+        pass('.comet.yaml exists');
+        checkYamlIs('phase', 'open', change);
     }
-    checkNonempty('proposal.md', join(changeDir, 'proposal.md'));
-    checkNonempty('tasks.md', join(changeDir, 'tasks.md'));
-  } else if (phase === 'verify') {
-    pass('.comet.yaml exists');
-    checkYamlIs('phase', 'verify', change);
-    const result = getValue(change, 'verify_result');
-    result === 'pending' || !result || result === 'null'
-      ? pass(`verify_result=${result} (expected: pending or null)`)
-      : block(`verify_result=${result} (expected: pending or null)`);
-  } else if (phase === 'archive') {
-    pass('.comet.yaml exists');
-    checkYamlIs('phase', 'archive', change);
-    checkYamlIs('verify_result', 'pass', change);
-    const archived = getValue(change, 'archived');
-    archived !== 'true' ? pass(`archived=${archived} (expected: not true)`) : block(`archived=${archived} (expected: not true)`);
-  }
-  console.log('');
-  if (checkBlock) {
-    red('BLOCKED — fix failing checks before proceeding');
-    process.exit(1);
-  }
-  green('ALL CHECKS PASSED — ready to proceed');
+    else if (phase === 'design') {
+        pass('.comet.yaml exists');
+        checkYamlIs('phase', 'design', change);
+        checkYamlIs('workflow', 'full', change);
+        checkYamlEmpty('design_doc', change);
+        checkNonempty('proposal.md', join(changeDir, 'proposal.md'));
+        checkNonempty('design.md', join(changeDir, 'design.md'));
+        checkNonempty('tasks.md', join(changeDir, 'tasks.md'));
+    }
+    else if (phase === 'build') {
+        pass('.comet.yaml exists');
+        checkYamlIs('phase', 'build', change);
+        const workflow = getValue(change, 'workflow');
+        if (workflow === 'full') {
+            const designDoc = getValue(change, 'design_doc');
+            if (designDoc && designDoc !== 'null' && existsSync(designDoc))
+                pass(`design_doc=${designDoc} (file exists)`);
+            else
+                block(`design_doc=${designDoc} (expected: non-null and file exists)`);
+        }
+        else {
+            pass(`workflow=${workflow} (design_doc not required)`);
+        }
+        checkNonempty('proposal.md', join(changeDir, 'proposal.md'));
+        checkNonempty('tasks.md', join(changeDir, 'tasks.md'));
+    }
+    else if (phase === 'verify') {
+        pass('.comet.yaml exists');
+        checkYamlIs('phase', 'verify', change);
+        const result = getValue(change, 'verify_result');
+        if (result === 'pending' || !result || result === 'null')
+            pass(`verify_result=${result} (expected: pending or null)`);
+        else
+            block(`verify_result=${result} (expected: pending or null)`);
+    }
+    else if (phase === 'archive') {
+        pass('.comet.yaml exists');
+        checkYamlIs('phase', 'archive', change);
+        checkYamlIs('verify_result', 'pass', change);
+        const archived = getValue(change, 'archived');
+        if (archived !== 'true')
+            pass(`archived=${archived} (expected: not true)`);
+        else
+            block(`archived=${archived} (expected: not true)`);
+    }
+    console.log('');
+    if (checkBlock) {
+        red('BLOCKED — fix failing checks before proceeding');
+        process.exit(1);
+    }
+    green('ALL CHECKS PASSED — ready to proceed');
 }
-
 function fieldStatus(field, value, file = '') {
-  if (!value || value === 'null') console.log(`  - ${field}: PENDING`);
-  else if (file && !existsSync(file)) console.log(`  - ${field}: BROKEN (path ${value} does not exist)`);
-  else console.log(`  - ${field}: DONE (${value})`);
+    if (!value || value === 'null')
+        console.log(`  - ${field}: PENDING`);
+    else if (file && !existsSync(file))
+        console.log(`  - ${field}: BROKEN (path ${value} does not exist)`);
+    else
+        console.log(`  - ${field}: DONE (${value})`);
 }
-
 function recover(change) {
-  validateChangeName(change);
-  const changeDir = join('openspec', 'changes', change);
-  const yaml = join(changeDir, '.comet.yaml');
-  if (!existsSync(yaml)) fail(`.comet.yaml not found at ${yaml}`);
-  const phase = getValue(change, 'phase');
-  const workflow = getValue(change, 'workflow');
-  console.log(`=== Recovery Context: ${change} ===`);
-  console.log(`Phase: ${phase}`);
-  console.log(`Workflow: ${workflow}`);
-  console.log('');
-  const values = Object.fromEntries(['design_doc', 'plan', 'verify_result', 'verify_mode', 'verification_report', 'branch_status', 'handoff_context', 'handoff_hash', 'isolation', 'build_mode', 'build_pause', 'direct_override', 'archived'].map((f) => [f, getValue(change, f)]));
-  console.log('State fields:');
-  if (phase === 'open') {
-    console.log('  Artifacts:');
-    for (const f of ['proposal.md', 'design.md', 'tasks.md']) console.log(`  - ${f}: ${fileNonempty(join(changeDir, f)) ? 'DONE' : 'PENDING'}`);
-    console.log('\nRecovery action: Create or complete missing artifacts, then use AskUserQuestion for user confirmation.');
-  } else if (phase === 'design') {
-    console.log('  Artifacts:');
-    for (const f of ['proposal.md', 'design.md', 'tasks.md']) console.log(`  - ${f}: ${fileNonempty(join(changeDir, f)) ? 'DONE' : 'MISSING (unexpected in design phase)'}`);
-    console.log('\n  Design progress:');
-    fieldStatus('handoff_context', values.handoff_context, values.handoff_context);
-    fieldStatus('handoff_hash', values.handoff_hash);
-    fieldStatus('design_doc', values.design_doc, values.design_doc);
-    console.log('');
-    if (values.design_doc && values.design_doc !== 'null' && existsSync(values.design_doc)) console.log('Recovery action: Design Doc already created and linked. Run guard to transition to build.');
-    else if (values.handoff_context && values.handoff_context !== 'null' && existsSync(values.handoff_context)) console.log('Recovery action: Handoff generated but Design Doc not yet created. Resume from brainstorming confirmation (Step 1c).');
-    else console.log('Recovery action: No handoff generated yet. Start from Step 1a (generate handoff package).');
-  } else if (phase === 'build') {
-    console.log('  Build decisions:');
-    fieldStatus('isolation', values.isolation);
-    fieldStatus('build_mode', values.build_mode);
-    fieldStatus('build_pause', values.build_pause);
-    if (values.build_mode === 'direct' && !['hotfix', 'tweak'].includes(workflow)) fieldStatus('direct_override', values.direct_override);
-    console.log('\n  Plan:');
-    fieldStatus('plan', values.plan, values.plan);
-    const tasksFile = join(changeDir, 'tasks.md');
-    let total = 0;
-    let done = 0;
-    if (existsSync(tasksFile)) {
-      const text = readFileSync(tasksFile, 'utf8');
-      total = (text.match(/^- \[/gm) ?? []).length;
-      done = (text.match(/^- \[x\]/gm) ?? []).length;
-      console.log(`\n  Tasks: ${done}/${total} done, ${total - done} pending`);
-    } else console.log('\n  Tasks: tasks.md MISSING');
-    console.log('');
-    if (values.build_pause === 'plan-ready' && values.plan && values.plan !== 'null' && existsSync(values.plan) && (!values.isolation || values.isolation === 'null' || !values.build_mode || values.build_mode === 'null')) console.log('Recovery action: Plan-ready pause detected. Ask the user whether to continue, then choose isolation and build mode without regenerating the plan.');
-    else if (values.build_pause === 'plan-ready' && (!values.plan || values.plan === 'null' || !existsSync(values.plan))) console.log('Recovery action: Plan-ready pause is recorded, but the plan file is missing. Restore the plan file or rerun writing-plans before choosing execution.');
-    else if (values.build_pause === 'plan-ready') console.log('Recovery action: Plan-ready pause is stale because build decisions are already selected. Clear build_pause to null, then continue from the first unchecked task.');
-    else if (!values.isolation || values.isolation === 'null') console.log('Recovery action: Isolation not selected. Use AskUserQuestion to ask user for branch/worktree choice.');
-    else if (!values.build_mode || values.build_mode === 'null') console.log('Recovery action: Build mode not selected. Use AskUserQuestion to ask user for execution method.');
-    else if (!existsSync(tasksFile)) console.log('Recovery action: tasks.md missing. Verify change directory integrity.');
-    else if (total - done > 0) console.log('Recovery action: Read tasks.md and continue from first unchecked task.');
-    else console.log('Recovery action: All tasks done. Run guard to transition to verify.');
-  } else if (phase === 'verify') {
-    console.log('  Verification:');
-    fieldStatus('verify_result', values.verify_result);
-    fieldStatus('verify_mode', values.verify_mode);
-    fieldStatus('verification_report', values.verification_report, values.verification_report);
-    fieldStatus('branch_status', values.branch_status);
+    validateChangeName(change);
+    const changeDir = join('openspec', 'changes', change);
+    const yaml = join(changeDir, '.comet.yaml');
+    if (!existsSync(yaml))
+        fail(`.comet.yaml not found at ${yaml}`);
+    const phase = getValue(change, 'phase');
+    const workflow = getValue(change, 'workflow');
+    console.log(`=== Recovery Context: ${change} ===`);
+    console.log(`Phase: ${phase}`);
+    console.log(`Workflow: ${workflow}`);
     console.log('');
-    if (values.verify_result === 'pass' && values.branch_status === 'handled') console.log('Recovery action: Verification complete. Run guard to transition to archive.');
-    else if (values.verify_result === 'pass') console.log('Recovery action: Verification passed but branch not yet handled. Complete branch handling and set branch_status to handled.');
-    else if (values.verify_result === 'fail') console.log('Recovery action: Verification failed and rolled back to build. Resume from /comet-build.');
-    else console.log('Recovery action: Verification not yet started or in progress. Run scale assessment then verify.');
-  } else if (phase === 'archive') {
-    console.log('  Archive:');
-    fieldStatus('verify_result', values.verify_result);
-    fieldStatus('archived', values.archived);
-    console.log('\nRecovery action: Run /comet-archive to complete archiving.');
-  }
-  console.log('\n=== End Recovery Context ===');
+    const values = Object.fromEntries([
+        'design_doc',
+        'plan',
+        'verify_result',
+        'verify_mode',
+        'verification_report',
+        'branch_status',
+        'handoff_context',
+        'handoff_hash',
+        'isolation',
+        'build_mode',
+        'build_pause',
+        'direct_override',
+        'archived',
+    ].map((f) => [f, getValue(change, f)]));
+    console.log('State fields:');
+    if (phase === 'open') {
+        console.log('  Artifacts:');
+        for (const f of ['proposal.md', 'design.md', 'tasks.md'])
+            console.log(`  - ${f}: ${fileNonempty(join(changeDir, f)) ? 'DONE' : 'PENDING'}`);
+        console.log('\nRecovery action: Create or complete missing artifacts, then use AskUserQuestion for user confirmation.');
+    }
+    else if (phase === 'design') {
+        console.log('  Artifacts:');
+        for (const f of ['proposal.md', 'design.md', 'tasks.md'])
+            console.log(`  - ${f}: ${fileNonempty(join(changeDir, f)) ? 'DONE' : 'MISSING (unexpected in design phase)'}`);
+        console.log('\n  Design progress:');
+        fieldStatus('handoff_context', values.handoff_context, values.handoff_context);
+        fieldStatus('handoff_hash', values.handoff_hash);
+        fieldStatus('design_doc', values.design_doc, values.design_doc);
+        console.log('');
+        if (values.design_doc && values.design_doc !== 'null' && existsSync(values.design_doc))
+            console.log('Recovery action: Design Doc already created and linked. Run guard to transition to build.');
+        else if (values.handoff_context &&
+            values.handoff_context !== 'null' &&
+            existsSync(values.handoff_context))
+            console.log('Recovery action: Handoff generated but Design Doc not yet created. Resume from brainstorming confirmation (Step 1c).');
+        else
+            console.log('Recovery action: No handoff generated yet. Start from Step 1a (generate handoff package).');
+    }
+    else if (phase === 'build') {
+        console.log('  Build decisions:');
+        fieldStatus('isolation', values.isolation);
+        fieldStatus('build_mode', values.build_mode);
+        fieldStatus('build_pause', values.build_pause);
+        if (values.build_mode === 'direct' && !['hotfix', 'tweak'].includes(workflow))
+            fieldStatus('direct_override', values.direct_override);
+        console.log('\n  Plan:');
+        fieldStatus('plan', values.plan, values.plan);
+        const tasksFile = join(changeDir, 'tasks.md');
+        let total = 0;
+        let done = 0;
+        if (existsSync(tasksFile)) {
+            const text = readFileSync(tasksFile, 'utf8');
+            total = (text.match(/^- \[/gm) ?? []).length;
+            done = (text.match(/^- \[x\]/gm) ?? []).length;
+            console.log(`\n  Tasks: ${done}/${total} done, ${total - done} pending`);
+        }
+        else
+            console.log('\n  Tasks: tasks.md MISSING');
+        console.log('');
+        if (values.build_pause === 'plan-ready' &&
+            values.plan &&
+            values.plan !== 'null' &&
+            existsSync(values.plan) &&
+            (!values.isolation ||
+                values.isolation === 'null' ||
+                !values.build_mode ||
+                values.build_mode === 'null'))
+            console.log('Recovery action: Plan-ready pause detected. Ask the user whether to continue, then choose isolation and build mode without regenerating the plan.');
+        else if (values.build_pause === 'plan-ready' &&
+            (!values.plan || values.plan === 'null' || !existsSync(values.plan)))
+            console.log('Recovery action: Plan-ready pause is recorded, but the plan file is missing. Restore the plan file or rerun writing-plans before choosing execution.');
+        else if (values.build_pause === 'plan-ready')
+            console.log('Recovery action: Plan-ready pause is stale because build decisions are already selected. Clear build_pause to null, then continue from the first unchecked task.');
+        else if (!values.isolation || values.isolation === 'null')
+            console.log('Recovery action: Isolation not selected. Use AskUserQuestion to ask user for branch/worktree choice.');
+        else if (!values.build_mode || values.build_mode === 'null')
+            console.log('Recovery action: Build mode not selected. Use AskUserQuestion to ask user for execution method.');
+        else if (!existsSync(tasksFile))
+            console.log('Recovery action: tasks.md missing. Verify change directory integrity.');
+        else if (total - done > 0)
+            console.log('Recovery action: Read tasks.md and continue from first unchecked task.');
+        else
+            console.log('Recovery action: All tasks done. Run guard to transition to verify.');
+    }
+    else if (phase === 'verify') {
+        console.log('  Verification:');
+        fieldStatus('verify_result', values.verify_result);
+        fieldStatus('verify_mode', values.verify_mode);
+        fieldStatus('verification_report', values.verification_report, values.verification_report);
+        fieldStatus('branch_status', values.branch_status);
+        console.log('');
+        if (values.verify_result === 'pass' && values.branch_status === 'handled')
+            console.log('Recovery action: Verification complete. Run guard to transition to archive.');
+        else if (values.verify_result === 'pass')
+            console.log('Recovery action: Verification passed but branch not yet handled. Complete branch handling and set branch_status to handled.');
+        else if (values.verify_result === 'fail')
+            console.log('Recovery action: Verification failed and rolled back to build. Resume from /comet-build.');
+        else
+            console.log('Recovery action: Verification not yet started or in progress. Run scale assessment then verify.');
+    }
+    else if (phase === 'archive') {
+        console.log('  Archive:');
+        fieldStatus('verify_result', values.verify_result);
+        fieldStatus('archived', values.archived);
+        console.log('\nRecovery action: Run /comet-archive to complete archiving.');
+    }
+    console.log('\n=== End Recovery Context ===');
 }
-
 function countSpecFiles(dir) {
-  if (!existsSync(dir)) return 0;
-  let count = 0;
-  for (const entry of readdirSync(dir, { withFileTypes: true })) {
-    const p = join(dir, entry.name);
-    if (entry.isDirectory()) count += countSpecFiles(p);
-    else if (entry.isFile() && entry.name === 'spec.md') count += 1;
-  }
-  return count;
+    if (!existsSync(dir))
+        return 0;
+    let count = 0;
+    for (const entry of readdirSync(dir, { withFileTypes: true })) {
+        const p = join(dir, entry.name);
+        if (entry.isDirectory())
+            count += countSpecFiles(p);
+        else if (entry.isFile() && entry.name === 'spec.md')
+            count += 1;
+    }
+    return count;
 }
-
 function scale(change) {
-  validateChangeName(change);
-  const changeDir = join('openspec', 'changes', change);
-  const yaml = join(changeDir, '.comet.yaml');
-  if (!existsSync(yaml)) fail(`.comet.yaml not found at ${yaml}`);
-  const tasksFile = join(changeDir, 'tasks.md');
-  const taskCount = existsSync(tasksFile) ? (readFileSync(tasksFile, 'utf8').match(/^- \[/gm) ?? []).length : 0;
-  const deltaSpecCount = countSpecFiles(join(changeDir, 'specs'));
-  let changedFiles = 0;
-  if (git(['rev-parse', '--git-dir']).status === 0) {
-    let baseRef = '';
-    const plan = getValue(change, 'plan');
-    if (plan && plan !== 'null' && existsSync(plan)) {
-      baseRef = readFileSync(plan, 'utf8').match(/^base-ref:\s*(.*)$/m)?.[1]?.trim() ?? '';
+    validateChangeName(change);
+    const changeDir = join('openspec', 'changes', change);
+    const yaml = join(changeDir, '.comet.yaml');
+    if (!existsSync(yaml))
+        fail(`.comet.yaml not found at ${yaml}`);
+    const tasksFile = join(changeDir, 'tasks.md');
+    const taskCount = existsSync(tasksFile)
+        ? (readFileSync(tasksFile, 'utf8').match(/^- \[/gm) ?? []).length
+        : 0;
+    const deltaSpecCount = countSpecFiles(join(changeDir, 'specs'));
+    let changedFiles = 0;
+    if (git(['rev-parse', '--git-dir']).status === 0) {
+        let baseRef = '';
+        const plan = getValue(change, 'plan');
+        if (plan && plan !== 'null' && existsSync(plan)) {
+            baseRef =
+                readFileSync(plan, 'utf8')
+                    .match(/^base-ref:\s*(.*)$/m)?.[1]
+                    ?.trim() ?? '';
+        }
+        if (!baseRef || baseRef === 'null')
+            baseRef = getValue(change, 'base_ref');
+        const diff = baseRef && baseRef !== 'null' && git(['rev-parse', '--verify', baseRef]).status === 0
+            ? git(['diff', '--name-only', `${baseRef}...HEAD`])
+            : git(['diff', '--name-only', 'HEAD']);
+        changedFiles = diff.status === 0 ? diff.stdout.split(/\r?\n/).filter(Boolean).length : 0;
     }
-    if (!baseRef || baseRef === 'null') baseRef = getValue(change, 'base_ref');
-    const diff = baseRef && baseRef !== 'null' && git(['rev-parse', '--verify', baseRef]).status === 0
-      ? git(['diff', '--name-only', `${baseRef}...HEAD`])
-      : git(['diff', '--name-only', 'HEAD']);
-    changedFiles = diff.status === 0 ? diff.stdout.split(/\r?\n/).filter(Boolean).length : 0;
-  }
-  const result = taskCount > 3 || deltaSpecCount > 1 || changedFiles > 4 ? 'full' : 'light';
-  console.error(`=== Scale Assessment: ${change} ===`);
-  console.error(`  Tasks: ${taskCount} (threshold: 3)`);
-  console.error(`  Delta specs: ${deltaSpecCount} capabilities (threshold: 1)`);
-  console.error(`  Changed files: ${changedFiles} (threshold: 4)`);
-  console.error(`  → Result: ${result}`);
-  setYamlField(yaml, 'verify_mode', result);
-  green(`[SCALE] verify_mode=${result}`);
+    const result = taskCount > 3 || deltaSpecCount > 1 || changedFiles > 4 ? 'full' : 'light';
+    console.error(`=== Scale Assessment: ${change} ===`);
+    console.error(`  Tasks: ${taskCount} (threshold: 3)`);
+    console.error(`  Delta specs: ${deltaSpecCount} capabilities (threshold: 1)`);
+    console.error(`  Changed files: ${changedFiles} (threshold: 4)`);
+    console.error(`  → Result: ${result}`);
+    setYamlField(yaml, 'verify_mode', result);
+    green(`[SCALE] verify_mode=${result}`);
 }
-
 const [subcommand, ...args] = process.argv.slice(2);
-if (subcommand === 'init' && args.length >= 2) init(args[0], args[1]);
-else if (subcommand === 'get' && args.length >= 2) get(args[0], args[1]);
-else if (subcommand === 'set' && args.length >= 3) set(args[0], args[1], args.slice(2).join(' '));
-else if (subcommand === 'transition' && args.length >= 2) transition(args[0], args[1]);
-else if (subcommand === 'check' && args.length >= 2) args[2] === '--recover' ? recover(args[0]) : check(args[0], args[1]);
-else if (subcommand === 'scale' && args.length >= 1) scale(args[0]);
+if (subcommand === 'init' && args.length >= 2)
+    init(args[0], args[1]);
+else if (subcommand === 'get' && args.length >= 2)
+    get(args[0], args[1]);
+else if (subcommand === 'set' && args.length >= 3)
+    set(args[0], args[1], args.slice(2).join(' '));
+else if (subcommand === 'transition' && args.length >= 2)
+    transition(args[0], args[1]);
+else if (subcommand === 'check' && args.length >= 2)
+    if (args[2] === '--recover')
+        recover(args[0]);
+    else
+        check(args[0], args[1]);
+else if (subcommand === 'scale' && args.length >= 1)
+    scale(args[0]);
 else {
-  red(`Unknown subcommand: ${subcommand ?? ''}`);
-  console.error('\nUsage: comet-state.js <subcommand> <change-name> [args...]');
-  process.exit(1);
+    red(`Unknown subcommand: ${subcommand ?? ''}`);
+    console.error('\nUsage: comet-state.js <subcommand> <change-name> [args...]');
+    process.exit(1);
 }
diff --git a/assets/skills/comet/scripts/comet-yaml-validate.js b/assets/skills/comet/scripts/comet-yaml-validate.js
index 6f8e6b62..8d772015 100644
--- a/assets/skills/comet/scripts/comet-yaml-validate.js
+++ b/assets/skills/comet/scripts/comet-yaml-validate.js
@@ -1,68 +1,86 @@
 #!/usr/bin/env node
 import { existsSync } from 'node:fs';
 import { join } from 'node:path';
-import { changeDirFor, fieldValue, KNOWN_KEYS, parseYamlLines, red, green, validateChangeName, yellow } from './comet-lib.js';
-
+import { changeDirFor, fieldValue, green, KNOWN_KEYS, parseYamlLines, red, validateChangeName, yellow, } from './comet-lib.js';
 const change = process.argv[2];
 validateChangeName(change);
 const changeDir = changeDirFor(change);
 const yaml = join(changeDir, '.comet.yaml');
 let errors = 0;
 let warnings = 0;
-
 function fail(message) {
-  red(`  FAIL: ${message}`);
-  errors += 1;
+    red(`  FAIL: ${message}`);
+    errors += 1;
 }
-
 function warn(message) {
-  yellow(`  WARN: ${message}`);
-  warnings += 1;
+    yellow(`  WARN: ${message}`);
+    warnings += 1;
 }
-
 function validateEnum(field, value, valid) {
-  if (!value || value === 'null') return;
-  if (!valid.includes(value)) fail(`${field}='${value}' is not valid. Expected: ${valid.join(' ')}`);
+    if (!value || value === 'null')
+        return;
+    if (!valid.includes(value))
+        fail(`${field}='${value}' is not valid. Expected: ${valid.join(' ')}`);
 }
-
 console.error(`[VALIDATE] ${yaml}`);
-
 if (!existsSync(yaml)) {
-  fail(`.comet.yaml not found at ${yaml}`);
-} else {
-  const parsed = parseYamlLines(yaml);
-  const required = ['workflow', 'phase', 'design_doc', 'plan', 'build_mode', 'isolation', 'verify_mode', 'verify_result', 'verified_at', 'archived'];
-  for (const field of required) {
-    if (!parsed.keys.includes(field)) fail(`missing required field '${field}'`);
-  }
-
-  validateEnum('workflow', fieldValue(yaml, 'workflow'), ['full', 'hotfix', 'tweak']);
-  validateEnum('phase', fieldValue(yaml, 'phase'), ['open', 'design', 'build', 'verify', 'archive']);
-  validateEnum('build_mode', fieldValue(yaml, 'build_mode'), ['subagent-driven-development', 'executing-plans', 'direct']);
-  validateEnum('build_pause', fieldValue(yaml, 'build_pause'), ['null', 'plan-ready']);
-  validateEnum('isolation', fieldValue(yaml, 'isolation'), ['branch', 'worktree']);
-  validateEnum('verify_mode', fieldValue(yaml, 'verify_mode'), ['light', 'full']);
-  validateEnum('verify_result', fieldValue(yaml, 'verify_result'), ['pending', 'pass', 'fail']);
-  validateEnum('branch_status', fieldValue(yaml, 'branch_status'), ['pending', 'handled']);
-  validateEnum('archived', fieldValue(yaml, 'archived'), ['true', 'false']);
-  validateEnum('direct_override', fieldValue(yaml, 'direct_override'), ['true', 'false']);
-
-  for (const field of ['design_doc', 'plan', 'handoff_context']) {
-    const value = fieldValue(yaml, field);
-    if (value && value !== 'null' && !existsSync(value)) fail(`${field}='${value}' does not exist on disk`);
-  }
-  const handoffHash = fieldValue(yaml, 'handoff_hash');
-  if (handoffHash && handoffHash !== 'null' && !/^[a-f0-9]{64}$/.test(handoffHash)) {
-    fail(`handoff_hash='${handoffHash}' is not a sha256 hex digest`);
-  }
-  for (const key of parsed.keys) {
-    if (!KNOWN_KEYS.has(key)) warn(`unknown field '${key}' found`);
-  }
+    fail(`.comet.yaml not found at ${yaml}`);
+}
+else {
+    const parsed = parseYamlLines(yaml);
+    const required = [
+        'workflow',
+        'phase',
+        'design_doc',
+        'plan',
+        'build_mode',
+        'isolation',
+        'verify_mode',
+        'verify_result',
+        'verified_at',
+        'archived',
+    ];
+    for (const field of required) {
+        if (!parsed.keys.includes(field))
+            fail(`missing required field '${field}'`);
+    }
+    validateEnum('workflow', fieldValue(yaml, 'workflow'), ['full', 'hotfix', 'tweak']);
+    validateEnum('phase', fieldValue(yaml, 'phase'), [
+        'open',
+        'design',
+        'build',
+        'verify',
+        'archive',
+    ]);
+    validateEnum('build_mode', fieldValue(yaml, 'build_mode'), [
+        'subagent-driven-development',
+        'executing-plans',
+        'direct',
+    ]);
+    validateEnum('build_pause', fieldValue(yaml, 'build_pause'), ['null', 'plan-ready']);
+    validateEnum('isolation', fieldValue(yaml, 'isolation'), ['branch', 'worktree']);
+    validateEnum('verify_mode', fieldValue(yaml, 'verify_mode'), ['light', 'full']);
+    validateEnum('verify_result', fieldValue(yaml, 'verify_result'), ['pending', 'pass', 'fail']);
+    validateEnum('branch_status', fieldValue(yaml, 'branch_status'), ['pending', 'handled']);
+    validateEnum('archived', fieldValue(yaml, 'archived'), ['true', 'false']);
+    validateEnum('direct_override', fieldValue(yaml, 'direct_override'), ['true', 'false']);
+    for (const field of ['design_doc', 'plan', 'handoff_context']) {
+        const value = fieldValue(yaml, field);
+        if (value && value !== 'null' && !existsSync(value))
+            fail(`${field}='${value}' does not exist on disk`);
+    }
+    const handoffHash = fieldValue(yaml, 'handoff_hash');
+    if (handoffHash && handoffHash !== 'null' && !/^[a-f0-9]{64}$/.test(handoffHash)) {
+        fail(`handoff_hash='${handoffHash}' is not a sha256 hex digest`);
+    }
+    for (const key of parsed.keys) {
+        if (!KNOWN_KEYS.has(key))
+            warn(`unknown field '${key}' found`);
+    }
 }
-
 console.error('');
 if (errors > 0) {
-  red(`${errors} error(s), ${warnings} warning(s) — validation FAILED`);
-  process.exit(1);
+    red(`${errors} error(s), ${warnings} warning(s) — validation FAILED`);
+    process.exit(1);
 }
 green(`0 errors, ${warnings} warning(s) — validation PASSED`);
diff --git a/build.js b/build.js
index 6b864405..ed9e6c11 100644
--- a/build.js
+++ b/build.js
@@ -6,9 +6,9 @@ import { createRequire } from 'module';
 
 const require = createRequire(import.meta.url);
 
-const runTsc = (args = []) => {
+const runTsc = (project, args = []) => {
   const tscPath = require.resolve('typescript/bin/tsc');
-  execFileSync(process.execPath, [tscPath, ...args], { stdio: 'inherit' });
+  execFileSync(process.execPath, [tscPath, '--project', project, ...args], { stdio: 'inherit' });
 };
 
 console.log('Building Comet...\n');
@@ -18,12 +18,38 @@ if (existsSync('dist')) {
   rmSync('dist', { recursive: true, force: true });
 }
 
-console.log('Compiling TypeScript...');
+console.log('Compiling src/ TypeScript...');
 try {
-  runTsc(['--version']);
-  runTsc();
-  console.log('\nBuild completed successfully!');
-} catch (error) {
+  runTsc('tsconfig.json', ['--version']);
+  runTsc('tsconfig.json');
+} catch {
   console.error('\nBuild failed!');
   process.exit(1);
 }
+
+console.log('\nCleaning script output directory...');
+if (existsSync('assets/skills/comet/scripts')) {
+  const scriptFiles = [
+    'comet-lib.js',
+    'comet-env.js',
+    'comet-guard.js',
+    'comet-handoff.js',
+    'comet-archive.js',
+    'comet-yaml-validate.js',
+    'comet-state.js',
+  ];
+  for (const f of scriptFiles) {
+    const p = `assets/skills/comet/scripts/${f}`;
+    if (existsSync(p)) rmSync(p, { force: true });
+  }
+}
+
+console.log('Compiling scripts/ TypeScript...');
+try {
+  runTsc('src/scripts/tsconfig.json');
+} catch {
+  console.error('\nScript compilation failed!');
+  process.exit(1);
+}
+
+console.log('\nBuild completed successfully!');
diff --git a/src/scripts/comet-archive.ts b/src/scripts/comet-archive.ts
new file mode 100644
index 00000000..742f90e0
--- /dev/null
+++ b/src/scripts/comet-archive.ts
@@ -0,0 +1,138 @@
+#!/usr/bin/env node
+import {
+  copyFileSync,
+  existsSync,
+  mkdirSync,
+  readdirSync,
+  readFileSync,
+  renameSync,
+  statSync,
+  writeFileSync,
+} from 'node:fs';
+import { dirname, join } from 'node:path';
+import {
+  fieldValue,
+  green,
+  red,
+  runNode,
+  scriptDir,
+  today,
+  validateChangeName,
+  yellow,
+} from './comet-lib.js';
+
+const [change, flag] = process.argv.slice(2);
+const dryRun = flag === '--dry-run';
+validateChangeName(change, 'FATAL');
+const changeDir = join('openspec', 'changes', change);
+const yaml = join(changeDir, '.comet.yaml');
+const archiveName = `${today()}-${change}`;
+const archiveDir = join('openspec', 'changes', 'archive', archiveName);
+let stepsOk = 0;
+let stepsTotal = 0;
+
+function fatal(message: string): never {
+  red(`FATAL: ${message}`);
+  process.exit(1);
+}
+
+function stepOk(message: string): void {
+  green(`  [OK] ${message}`);
+  stepsOk += 1;
+  stepsTotal += 1;
+}
+function stepFail(message: string): void {
+  red(`  [FAIL] ${message}`);
+  stepsTotal += 1;
+}
+function stepDry(message: string): void {
+  yellow(`  [DRY-RUN] ${message}`);
+  stepsOk += 1;
+  stepsTotal += 1;
+}
+function y(field: string): string {
+  return fieldValue(yaml, field);
+}
+
+console.error(`=== Comet Archive: ${change} ===`);
+if (!existsSync(yaml)) fatal(`.comet.yaml not found in ${changeDir}/`);
+const designDoc = y('design_doc');
+const planPath = y('plan');
+if (y('phase') !== 'archive') fatal(`phase is '${y('phase')}', expected 'archive'`);
+if (y('verify_result') !== 'pass')
+  fatal(`verify_result is '${y('verify_result')}', expected 'pass'. Run comet-verify first.`);
+if (y('archived') === 'true') fatal('change already archived');
+stepOk('Entry state verified');
+if (existsSync(archiveDir)) fatal(`archive target already exists: ${archiveDir}`);
+stepOk('Archive target available');
+
+function syncDeltaSpecs(): void {
+  const deltaRoot = join(changeDir, 'specs');
+  if (!existsSync(deltaRoot)) return;
+  for (const capability of readdirSync(deltaRoot)) {
+    const deltaSpecDir = join(deltaRoot, capability);
+    if (!statSync(deltaSpecDir).isDirectory()) continue;
+    const deltaSpec = join(deltaSpecDir, 'spec.md');
+    const mainSpec = join('openspec', 'specs', capability, 'spec.md');
+    if (!existsSync(deltaSpec)) continue;
+    if (dryRun) {
+      stepDry(`Would sync: ${capability} → ${mainSpec}`);
+      continue;
+    }
+    mkdirSync(dirname(mainSpec), { recursive: true });
+    copyFileSync(deltaSpec, mainSpec);
+    stepOk(`Delta spec synced: ${capability} → openspec/specs/${capability}/spec.md`);
+  }
+}
+
+function annotateFrontmatter(file: string, extraFields: string): void {
+  if (!existsSync(file)) return;
+  if (dryRun) {
+    stepDry(`Would annotate: ${file}`);
+    return;
+  }
+  const text = readFileSync(file, 'utf8');
+  let next: string;
+  if (text.startsWith('---')) {
+    const lines = text.split(/\r?\n/);
+    const out: string[] = [];
+    let inserted = false;
+    for (let i = 0; i < lines.length; i += 1) {
+      const line = lines[i];
+      if (/^archived-with:/.test(line)) continue;
+      if (i > 0 && line === '---' && !inserted) {
+        out.push(`archived-with: ${archiveName}`);
+        if (extraFields) out.push(extraFields);
+        inserted = true;
+      }
+      out.push(line);
+    }
+    next = out.join('\n');
+  } else {
+    next = `---\narchived-with: ${archiveName}\n${extraFields ? `${extraFields}\n` : ''}status: final\n---\n${text}`;
+  }
+  writeFileSync(file, next);
+  stepOk(`Annotated: ${file}`);
+}
+
+syncDeltaSpecs();
+if (designDoc && designDoc !== 'null') annotateFrontmatter(designDoc, 'status: final');
+if (planPath && planPath !== 'null') annotateFrontmatter(planPath, '');
+if (dryRun) stepDry(`Would move: ${changeDir} → ${archiveDir}`);
+else {
+  mkdirSync(join('openspec', 'changes', 'archive'), { recursive: true });
+  renameSync(changeDir, archiveDir);
+  stepOk(`Moved to: ${archiveDir}`);
+}
+const archiveYaml = join(archiveDir, '.comet.yaml');
+if (dryRun) stepDry(`Would set archived: true in ${archiveYaml}`);
+else if (existsSync(archiveYaml)) {
+  const state = join(scriptDir, 'comet-state.js');
+  const result = runNode(state, ['transition', archiveName, 'archived']);
+  if (result.status === 0) stepOk('archived: true');
+  else stepFail('archived: true');
+} else stepFail('archived: true (.comet.yaml not found after move)');
+console.error('');
+if (dryRun) yellow(`Dry run complete. ${stepsOk}/${stepsTotal} steps would succeed.`);
+else green(`Archive complete. ${stepsOk}/${stepsTotal} steps succeeded.`);
+if (stepsOk < stepsTotal) process.exit(1);
diff --git a/src/scripts/comet-env.ts b/src/scripts/comet-env.ts
new file mode 100644
index 00000000..71fdccea
--- /dev/null
+++ b/src/scripts/comet-env.ts
@@ -0,0 +1,23 @@
+#!/usr/bin/env node
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { scriptDir } from './comet-lib.js';
+
+const env: Record<string, string> = {
+  COMET_STATE: join(scriptDir, 'comet-state.js'),
+  COMET_GUARD: join(scriptDir, 'comet-guard.js'),
+  COMET_HANDOFF: join(scriptDir, 'comet-handoff.js'),
+  COMET_ARCHIVE: join(scriptDir, 'comet-archive.js'),
+  COMET_YAML_VALIDATE: join(scriptDir, 'comet-yaml-validate.js'),
+};
+
+const missing = Object.values(env).filter((file) => !existsSync(file));
+if (missing.length > 0) {
+  console.error('ERROR: Comet scripts not found. Ensure the comet skill is installed completely.');
+  console.error(
+    'Expected path pattern: */comet/scripts/comet-*.js under project or platform skill directories',
+  );
+  process.exit(1);
+}
+
+console.log(JSON.stringify(env, null, 2));
diff --git a/src/scripts/comet-guard.ts b/src/scripts/comet-guard.ts
new file mode 100644
index 00000000..1c4deb1e
--- /dev/null
+++ b/src/scripts/comet-guard.ts
@@ -0,0 +1,368 @@
+#!/usr/bin/env node
+import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+import {
+  fieldValue,
+  fileNonempty,
+  green,
+  hashFile,
+  red,
+  runCommand,
+  runCommandString,
+  runNode,
+  scriptDir,
+  sha256,
+  slash,
+  validateChangeName,
+  yellow,
+} from './comet-lib.js';
+
+const [change, phase, applyFlag] = process.argv.slice(2);
+validateChangeName(change);
+const apply = applyFlag === '--apply';
+let changeDir = join('openspec', 'changes', change);
+if (
+  phase === 'archive' &&
+  !existsSync(changeDir) &&
+  existsSync(join('openspec', 'changes', 'archive', change))
+) {
+  changeDir = join('openspec', 'changes', 'archive', change);
+}
+const yaml = join(changeDir, '.comet.yaml');
+let block = false;
+
+function check(desc: string, fn: () => unknown): void {
+  try {
+    const result = fn();
+    if (result === true || result === undefined) green(`  [PASS] ${desc}`);
+    else throw new Error(String(result));
+  } catch (error) {
+    red(`  [FAIL] ${desc}`);
+    const message = error instanceof Error ? error.message : String(error);
+    if (message) for (const line of message.split(/\r?\n/)) red(`    ${line}`);
+    block = true;
+  }
+}
+
+function y(field: string): string {
+  return fieldValue(yaml, field);
+}
+
+function preflight(): void {
+  if (!existsSync(changeDir)) {
+    red(`FATAL: change directory not found: ${changeDir}`);
+    process.exit(1);
+  }
+  if (!existsSync(yaml)) {
+    red(`FATAL: .comet.yaml not found in ${changeDir}`);
+    process.exit(1);
+  }
+  const validateScript = join(scriptDir, 'comet-yaml-validate.js');
+  if (existsSync(validateScript)) {
+    const result = runNode(validateScript, [change]);
+    if (result.status !== 0) {
+      process.stderr.write(result.stderr || '');
+      red('FATAL: .comet.yaml schema validation failed');
+      process.exit(1);
+    }
+  }
+}
+
+function tasksAllDone(): void {
+  const tasks = join(changeDir, 'tasks.md');
+  if (!existsSync(tasks))
+    throw new Error(
+      `tasks.md is missing at ${tasks}\nNext: restore or create tasks.md for this change before leaving build.`,
+    );
+  const text = readFileSync(tasks, 'utf8');
+  if (!/- \[x\]/.test(text))
+    throw new Error(
+      "tasks.md has no completed tasks.\nNext: complete implementation tasks and mark them with '- [x]'.",
+    );
+  const unfinished = text
+    .split(/\r?\n/)
+    .map((line, index) => ({ line, index: index + 1 }))
+    .filter(({ line }) => /- \[ \]/.test(line));
+  if (unfinished.length > 0) {
+    throw new Error(
+      `Unfinished tasks:\n${unfinished.map(({ line, index }) => `${index}:${line}`).join('\n')}\nNext: complete or explicitly remove unfinished tasks, then mark tasks.md with '- [x]'.`,
+    );
+  }
+}
+
+function tasksHasAny(): boolean {
+  return (
+    existsSync(join(changeDir, 'tasks.md')) &&
+    /- \[/.test(readFileSync(join(changeDir, 'tasks.md'), 'utf8'))
+  );
+}
+
+function projectConfigValue(field: string): string {
+  const local = y(field);
+  if (local && local !== 'null') return local;
+  for (const config of ['.comet.yaml', 'comet.yaml', '.comet.yml', 'comet.yml']) {
+    if (existsSync(config)) {
+      const value = fieldValue(config, field);
+      if (value && value !== 'null') return value;
+    }
+  }
+  return '';
+}
+
+function buildPasses(): void {
+  if (process.env.COMET_SKIP_BUILD === '1') return;
+  const configured = projectConfigValue('build_command');
+  if (configured) {
+    const result = runCommandString(configured);
+    if (result.status !== 0) throw new Error(`command failed: ${configured}`);
+    return;
+  }
+  if (existsSync('package.json') && /"build"/.test(readFileSync('package.json', 'utf8'))) {
+    const result = runCommand(['npm', 'run', 'build']);
+    if (result.status !== 0) throw new Error('npm run build failed');
+    return;
+  }
+  if (existsSync('pom.xml')) {
+    const result = existsSync('./mvnw')
+      ? runCommand(['./mvnw', 'compile', '-q'])
+      : runCommand(['mvn', 'compile', '-q']);
+    if (result.status !== 0) throw new Error('maven build failed');
+    return;
+  }
+  if (existsSync('Cargo.toml')) {
+    const result = runCommand(['cargo', 'build']);
+    if (result.status !== 0) throw new Error('cargo build failed');
+    return;
+  }
+  throw new Error('no build command found');
+}
+
+function verificationCommandPasses(): void {
+  if (process.env.COMET_SKIP_BUILD === '1') return;
+  const configured = projectConfigValue('verify_command');
+  if (configured) {
+    const result = runCommandString(configured);
+    if (result.status !== 0) throw new Error(`command failed: ${configured}`);
+    return;
+  }
+  buildPasses();
+}
+
+function sourceFiles(): string[] {
+  const files = [
+    join(changeDir, 'proposal.md'),
+    join(changeDir, 'design.md'),
+    join(changeDir, 'tasks.md'),
+  ];
+  const specsRoot = join(changeDir, 'specs');
+  if (existsSync(specsRoot)) {
+    function walk(dir: string): void {
+      for (const entry of readdirSync(dir)) {
+        const p = join(dir, entry);
+        const stat = statSync(p);
+        if (stat.isDirectory()) walk(p);
+        else if (entry === 'spec.md') files.push(p);
+      }
+    }
+    walk(specsRoot);
+  }
+  return files;
+}
+
+function computeHandoffHash(): string {
+  let content = '';
+  for (const file of sourceFiles())
+    if (existsSync(file)) content += `path:${slash(file)}\nsha256:${hashFile(file)}\n`;
+  return sha256(content);
+}
+
+function designHandoffContextValid(): void {
+  const context = y('handoff_context');
+  const recordedHash = y('handoff_hash');
+  if (!context || context === 'null')
+    throw new Error(
+      'handoff_context is missing from .comet.yaml\nNext: run node "$COMET_HANDOFF" <change> design --write before invoking Superpowers.',
+    );
+  if (!fileNonempty(context))
+    throw new Error(
+      `handoff_context does not point to a non-empty file: ${context}\nNext: regenerate the design handoff with comet-handoff.js.`,
+    );
+  if (!/^[a-f0-9]{64}$/.test(recordedHash))
+    throw new Error(
+      `handoff_hash is missing or invalid: ${recordedHash || 'null'}\nNext: regenerate the design handoff with comet-handoff.js.`,
+    );
+  const actualHash = computeHandoffHash();
+  if (actualHash !== recordedHash)
+    throw new Error(
+      `OpenSpec artifacts changed after handoff was generated.\nExpected handoff_hash: ${recordedHash}\nActual handoff_hash:   ${actualHash}\nNext: rerun comet-handoff.js so Superpowers receives the current OpenSpec context.`,
+    );
+  const markdown = context.replace(/\.json$/, '.md');
+  if (!fileNonempty(markdown))
+    throw new Error(
+      `design handoff markdown is missing or empty: ${markdown}\nNext: regenerate the design handoff with comet-handoff.js.`,
+    );
+}
+
+function designHandoffMarkdownTraceable(): void {
+  const context = y('handoff_context');
+  if (!context || context === 'null')
+    throw new Error('handoff_context is missing from .comet.yaml');
+  const markdown = context.replace(/\.json$/, '.md');
+  if (!fileNonempty(markdown))
+    throw new Error(`design handoff markdown is missing or empty: ${markdown}`);
+  const text = readFileSync(markdown, 'utf8');
+  const missing: string[] = [];
+  if (!/^Generated-by: comet-handoff\.js$/m.test(text))
+    missing.push('handoff markdown is missing Generated-by marker');
+  if (!/^- Mode: (compact|full)$/m.test(text))
+    missing.push('handoff markdown is missing Mode marker');
+  for (const file of sourceFiles()) {
+    if (!existsSync(file)) continue;
+    if (!text.includes(`- Source: ${slash(file)}`))
+      missing.push(`handoff markdown is missing source reference: ${slash(file)}`);
+    if (!text.includes(`- SHA256: ${hashFile(file)}`))
+      missing.push(`handoff markdown is missing current sha256 for: ${file}`);
+  }
+  if (missing.length) throw new Error(missing.join('\n'));
+}
+
+function frontmatterHas(file: string, field: string, expected: string): boolean {
+  const text = readFileSync(file, 'utf8').replace(/^\uFEFF/, '');
+  const match = text.match(/^\s*---\r?\n([\s\S]*?)\r?\n---/);
+  if (!match) return false;
+  return new RegExp(`^${field}: ['"]?${expected}['"]?\\s*$`, 'm').test(match[1]);
+}
+
+function guardOpen(): void {
+  console.error('=== Guard: open → next ===');
+  check('proposal.md exists and non-empty', () => fileNonempty(join(changeDir, 'proposal.md')));
+  check('design.md exists and non-empty', () => fileNonempty(join(changeDir, 'design.md')));
+  check('tasks.md exists and non-empty', () => fileNonempty(join(changeDir, 'tasks.md')));
+  check('tasks.md has at least one task', tasksHasAny);
+}
+
+function guardDesign(): void {
+  console.error('=== Guard: design → build ===');
+  const designDoc = y('design_doc');
+  check('proposal.md exists', () => fileNonempty(join(changeDir, 'proposal.md')));
+  check('design.md exists', () => fileNonempty(join(changeDir, 'design.md')));
+  check('tasks.md exists', () => fileNonempty(join(changeDir, 'tasks.md')));
+  check('design handoff context exists', designHandoffContextValid);
+  check('design handoff markdown is traceable', designHandoffMarkdownTraceable);
+  if (designDoc && designDoc !== 'null') {
+    check(`Design Doc (${designDoc}) exists`, () => fileNonempty(designDoc));
+    check('Design Doc frontmatter links current change', () =>
+      frontmatterHas(designDoc, 'comet_change', change),
+    );
+    check('Design Doc declares technical design role', () =>
+      frontmatterHas(designDoc, 'role', 'technical-design'),
+    );
+    check('Design Doc declares OpenSpec as canonical spec', () =>
+      frontmatterHas(designDoc, 'canonical_spec', 'openspec'),
+    );
+  } else yellow('  [WARN] No design_doc recorded in .comet.yaml');
+}
+
+function guardBuild(): void {
+  console.error('=== Guard: build → verify ===');
+  check(
+    'isolation selected',
+    () =>
+      ['branch', 'worktree'].includes(y('isolation')) ||
+      `isolation must be branch or worktree, got '${y('isolation') || 'null'}'\nNext: ask the user to choose branch or worktree, create the chosen isolation, then run:\n  node "$COMET_STATE" set ${change} isolation <branch|worktree>`,
+  );
+  check(
+    'build_mode selected',
+    () =>
+      ['subagent-driven-development', 'executing-plans', 'direct'].includes(y('build_mode')) ||
+      `build_mode must be selected before leaving build, got '${y('build_mode') || 'null'}'\nNext: ask the user to choose an execution mode, then run:\n  node "$COMET_STATE" set ${change} build_mode <subagent-driven-development|executing-plans>`,
+  );
+  check(
+    'build_mode allowed for workflow',
+    () =>
+      y('build_mode') !== 'direct' ||
+      ['hotfix', 'tweak'].includes(y('workflow')) ||
+      y('direct_override') === 'true' ||
+      'build_mode=direct is only allowed for hotfix/tweak unless direct_override: true is recorded\nNext: choose executing-plans or subagent-driven-development, or stop and ask the user for an explicit direct override.',
+  );
+  check('tasks.md all tasks checked', tasksAllDone);
+  check('proposal.md exists', () => fileNonempty(join(changeDir, 'proposal.md')));
+  check('Build passes', buildPasses);
+}
+
+function guardVerify(): void {
+  console.error('=== Guard: verify → archive ===');
+  check('tasks.md all tasks checked', tasksAllDone);
+  check('Build passes', verificationCommandPasses);
+  check(
+    'verification_report exists',
+    () =>
+      y('verification_report') &&
+      y('verification_report') !== 'null' &&
+      existsSync(y('verification_report')),
+  );
+  check('branch_status=handled', () => y('branch_status') === 'handled');
+}
+
+function guardArchive(): void {
+  console.error('=== Guard: archive completeness ===');
+  check('archived is true', () => y('archived') === 'true');
+  check('proposal.md exists', () => fileNonempty(join(changeDir, 'proposal.md')));
+  check('tasks.md all tasks checked', tasksAllDone);
+}
+
+function applyStateUpdate(): void {
+  const state = join(scriptDir, 'comet-state.js');
+  if (!existsSync(state)) {
+    red('FATAL: comet-state.js not found; cannot apply state transition');
+    process.exit(1);
+  }
+  const eventMap: Record<string, string> = {
+    open: 'open-complete',
+    design: 'design-complete',
+    build: 'build-complete',
+    verify: 'verify-pass',
+  };
+  const event = eventMap[phase];
+  if (event) {
+    const result = runNode(state, ['transition', change, event]);
+    if (result.status !== 0) {
+      process.stderr.write(result.stderr || '');
+      process.exit(result.status ?? 1);
+    }
+  }
+}
+
+if (!['open', 'design', 'build', 'verify', 'archive'].includes(phase)) {
+  red(`Unknown phase: ${phase}`);
+  console.error('Valid phases: open, design, build, verify, archive');
+  process.exit(1);
+}
+preflight();
+type VoidFn = () => void;
+(
+  ({
+    open: guardOpen,
+    design: guardDesign,
+    build: guardBuild,
+    verify: guardVerify,
+    archive: guardArchive,
+  }) as Record<string, VoidFn>
+)[phase]();
+if (block) {
+  console.error('');
+  red('BLOCKED — fix failing checks before proceeding to next phase');
+  process.exit(1);
+}
+console.error('');
+green('ALL CHECKS PASSED — ready for next phase');
+if (apply) {
+  applyStateUpdate();
+  const messages: Record<string, string> = {
+    open: `  [APPLY] .comet.yaml updated: phase=${y('phase')}`,
+    design: '  [APPLY] .comet.yaml updated: phase=build',
+    build: '  [APPLY] .comet.yaml updated: phase=verify, verify_result=pending',
+    verify: '  [APPLY] .comet.yaml updated: phase=archive, verify_result=pass',
+  };
+  if (messages[phase]) green(messages[phase]);
+}
diff --git a/src/scripts/comet-handoff.ts b/src/scripts/comet-handoff.ts
new file mode 100644
index 00000000..38f3f2f5
--- /dev/null
+++ b/src/scripts/comet-handoff.ts
@@ -0,0 +1,156 @@
+#!/usr/bin/env node
+import { existsSync, readFileSync, readdirSync, statSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import {
+  ensureDir,
+  fieldValue,
+  fileNonempty,
+  green,
+  hashFile,
+  runNode,
+  scriptDir,
+  sha256,
+  slash,
+  validateChangeName,
+} from './comet-lib.js';
+
+function error(message: string): never {
+  console.error(`\u001b[31m${message}\u001b[0m`);
+  process.exit(1);
+}
+
+function walkSpecFiles(dir: string): string[] {
+  if (!existsSync(dir)) return [];
+  const out: string[] = [];
+  function walk(current: string): void {
+    for (const entry of readdirSync(current)) {
+      const p = join(current, entry);
+      const stat = statSync(p);
+      if (stat.isDirectory()) walk(p);
+      else if (entry === 'spec.md') out.push(p);
+    }
+  }
+  walk(dir);
+  return out.sort();
+}
+
+function sourceFiles(changeDir: string): string[] {
+  return [
+    join(changeDir, 'proposal.md'),
+    join(changeDir, 'design.md'),
+    join(changeDir, 'tasks.md'),
+    ...walkSpecFiles(join(changeDir, 'specs')),
+  ];
+}
+
+function computeContextHash(files: string[]): string {
+  let content = '';
+  for (const file of files) {
+    if (!existsSync(file)) continue;
+    content += `path:${slash(file)}\nsha256:${hashFile(file)}\n`;
+  }
+  return sha256(content);
+}
+
+function writeMarkdown(
+  output: string,
+  files: string[],
+  change: string,
+  mode: string,
+  contextHash: string,
+): void {
+  const chunks = [
+    '# Comet Design Handoff',
+    '',
+    `- Change: ${change}`,
+    '- Phase: design',
+    `- Mode: ${mode}`,
+    `- Context hash: ${contextHash}`,
+    '',
+    'Generated-by: comet-handoff.js',
+    '',
+    'OpenSpec remains the canonical capability spec. This handoff is a deterministic, source-traceable context pack, not an agent-authored summary.',
+    '',
+  ];
+  for (const file of files) {
+    if (!existsSync(file)) continue;
+    const text = readFileSync(file, 'utf8');
+    const lines = text.split(/\r?\n/);
+    chunks.push(
+      `## ${slash(file)}`,
+      '',
+      `- Source: ${slash(file)}`,
+      `- Lines: 1-${lines.length}`,
+      `- SHA256: ${hashFile(file)}`,
+      '',
+    );
+    if (mode === 'full' || lines.length <= 80)
+      chunks.push('```md', text.replace(/\s*$/, ''), '```');
+    else
+      chunks.push(
+        '[TRUNCATED]',
+        '',
+        '```md',
+        lines.slice(0, 80).join('\n'),
+        '```',
+        '',
+        `Full source: ${slash(file)}`,
+      );
+    chunks.push('');
+  }
+  writeFileSync(output, `${chunks.join('\n')}\n`);
+}
+
+function writeJson(
+  output: string,
+  files: string[],
+  change: string,
+  mode: string,
+  contextHash: string,
+): void {
+  const body = {
+    change,
+    phase: 'design',
+    mode,
+    canonical_spec: 'openspec',
+    generated_by: 'comet-handoff.js',
+    context_hash: contextHash,
+    files: files
+      .filter((file) => existsSync(file))
+      .map((file) => ({ path: slash(file), sha256: hashFile(file) })),
+  };
+  writeFileSync(output, `${JSON.stringify(body, null, 2)}\n`);
+}
+
+const [change, phase, modeArg, fullFlag] = process.argv.slice(2);
+validateChangeName(change);
+if (phase !== 'design' || modeArg !== '--write' || (fullFlag && fullFlag !== '--full'))
+  error('Usage: comet-handoff.js <change-name> design --write [--full]');
+const handoffMode = fullFlag === '--full' ? 'full' : 'compact';
+const changeDir = join('openspec', 'changes', change);
+const yaml = join(changeDir, '.comet.yaml');
+if (!existsSync(changeDir)) error(`ERROR: change directory not found: ${changeDir}`);
+if (!existsSync(yaml)) error(`ERROR: .comet.yaml not found at ${yaml}`);
+if (fieldValue(yaml, 'phase') !== 'design') error('ERROR: design handoff requires phase: design');
+for (const required of ['proposal.md', 'design.md', 'tasks.md']) {
+  if (!fileNonempty(join(changeDir, required)))
+    error(`ERROR: required OpenSpec artifact missing or empty: ${join(changeDir, required)}`);
+}
+const handoffDir = join(changeDir, '.comet', 'handoff');
+const contextJson = slash(join(handoffDir, 'design-context.json'));
+const contextMd = slash(join(handoffDir, 'design-context.md'));
+ensureDir(handoffDir);
+const files = sourceFiles(changeDir);
+const contextHash = computeContextHash(files);
+writeMarkdown(contextMd, files, change, handoffMode, contextHash);
+writeJson(contextJson, files, change, handoffMode, contextHash);
+const stateScript = join(scriptDir, 'comet-state.js');
+if (!existsSync(stateScript))
+  error('ERROR: comet-state.js not found; cannot record handoff fields');
+let result = runNode(stateScript, ['set', change, 'handoff_context', contextJson]);
+if (result.status !== 0) process.exit(result.status ?? 1);
+result = runNode(stateScript, ['set', change, 'handoff_hash', contextHash]);
+if (result.status !== 0) process.exit(result.status ?? 1);
+green(`[HANDOFF] wrote ${contextJson}`);
+green(`[HANDOFF] wrote ${contextMd}`);
+green(`[HANDOFF] handoff_hash=${contextHash}`);
diff --git a/src/scripts/comet-lib.ts b/src/scripts/comet-lib.ts
new file mode 100644
index 00000000..29da5d57
--- /dev/null
+++ b/src/scripts/comet-lib.ts
@@ -0,0 +1,233 @@
+#!/usr/bin/env node
+import { createHash } from 'node:crypto';
+import { existsSync, mkdirSync, readFileSync, statSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { spawnSync, type SpawnSyncOptions, type SpawnSyncReturns } from 'node:child_process';
+
+export const scriptDir: string = dirname(fileURLToPath(import.meta.url));
+
+export const FIELD_ORDER: string[] = [
+  'workflow',
+  'phase',
+  'build_mode',
+  'build_pause',
+  'isolation',
+  'verify_mode',
+  'base_ref',
+  'design_doc',
+  'plan',
+  'verify_result',
+  'verification_report',
+  'branch_status',
+  'created_at',
+  'verified_at',
+  'archived',
+  'direct_override',
+  'build_command',
+  'verify_command',
+  'handoff_context',
+  'handoff_hash',
+];
+
+export const KNOWN_KEYS: Set<string> = new Set(FIELD_ORDER);
+
+export function color(code: number, message: string): string {
+  return `\u001b[${code}m${message}\u001b[0m`;
+}
+
+export function red(message: string): void {
+  console.error(color(31, message));
+}
+
+export function green(message: string): void {
+  console.error(color(32, message));
+}
+
+export function yellow(message: string): void {
+  console.error(color(33, message));
+}
+
+export function fail(message: string, prefix: string = 'ERROR'): never {
+  red(`${prefix}: ${message}`);
+  process.exit(1);
+}
+
+export function validateChangeName(name: string, prefix: string = 'ERROR'): void {
+  if (!name) fail('Change name cannot be empty', prefix);
+  if (!/^[a-zA-Z0-9_-]+$/.test(name)) {
+    red(`${prefix}: Invalid change name: '${name}'`);
+    red('Valid characters: a-z, A-Z, 0-9, -, _');
+    process.exit(1);
+  }
+  if (name.includes('..'))
+    fail("Change name cannot contain '..' (path traversal not allowed)", prefix);
+}
+
+export function validateEnum(value: string, validValues: string[]): void {
+  if (validValues.includes(value)) return;
+  red(`ERROR: Invalid value: '${value}'`);
+  red(`Valid values: ${validValues.join(' ')}`);
+  process.exit(1);
+}
+
+export function stripInlineComment(value: string): string {
+  let out = '';
+  let quote = '';
+  for (let i = 0; i < value.length; i += 1) {
+    const c = value[i];
+    if (!quote) {
+      if (c === '"' || c === "'") quote = c;
+      else if (c === '#' && (i === 0 || /\s/.test(value[i - 1]))) return out.trimEnd();
+    } else if (c === quote) {
+      quote = '';
+    }
+    out += c;
+  }
+  return out;
+}
+
+export function stripWrappingQuotes(value: string): string {
+  if (value.length >= 2) {
+    const first = value[0];
+    const last = value[value.length - 1];
+    if (first === '"' && last === '"') {
+      try {
+        return JSON.parse(value) as string;
+      } catch {
+        return value.slice(1, -1);
+      }
+    }
+    if (first === "'" && last === "'") return value.slice(1, -1);
+  }
+  return value;
+}
+
+interface YamlData {
+  [key: string]: string;
+}
+
+interface ParsedYaml {
+  data: YamlData;
+  keys: string[];
+  text: string;
+}
+
+export function parseYamlLines(file: string): ParsedYaml {
+  const text = readFileSync(file, 'utf8');
+  const data: YamlData = {};
+  const keys: string[] = [];
+  for (const line of text.split(/\r?\n/)) {
+    const match = line.match(/^([^\s:#][^:]*):\s*(.*)$/);
+    if (!match) continue;
+    const key = match[1].trim();
+    const value = stripWrappingQuotes(stripInlineComment(match[2] ?? ''));
+    data[key] = value;
+    keys.push(key);
+  }
+  return { data, keys, text };
+}
+
+export function fieldValue(file: string, field: string): string {
+  if (!existsSync(file)) return '';
+  return parseYamlLines(file).data[field] ?? '';
+}
+
+function formatYamlValue(value: string): string {
+  const stringValue = String(value);
+  if (stringValue === '') return '';
+  if (/^[A-Za-z0-9_./:@\\-]+$/.test(stringValue)) return stringValue;
+  return JSON.stringify(stringValue);
+}
+
+export function writeYamlData(file: string, data: Record<string, string>): void {
+  const lines: string[] = [];
+  for (const key of FIELD_ORDER) {
+    if (Object.prototype.hasOwnProperty.call(data, key))
+      lines.push(`${key}: ${formatYamlValue(data[key])}`);
+  }
+  for (const key of Object.keys(data)) {
+    if (!FIELD_ORDER.includes(key)) lines.push(`${key}: ${formatYamlValue(data[key])}`);
+  }
+  writeFileSync(file, `${lines.join('\n')}\n`);
+}
+
+export function setYamlField(file: string, field: string, value: string): void {
+  const { data } = parseYamlLines(file);
+  data[field] = String(value);
+  writeYamlData(file, data);
+}
+
+export function fileNonempty(file: string): boolean {
+  try {
+    return statSync(file).isFile() && statSync(file).size > 0;
+  } catch {
+    return false;
+  }
+}
+
+export function changeDirFor(changeName: string): string {
+  const active = join('openspec', 'changes', changeName);
+  const archived = join('openspec', 'changes', 'archive', changeName);
+  if (existsSync(active)) return active;
+  if (existsSync(archived)) return archived;
+  return active;
+}
+
+export function yamlFileFor(changeName: string): string {
+  return join(changeDirFor(changeName), '.comet.yaml');
+}
+
+export function today(): string {
+  return new Date().toISOString().slice(0, 10);
+}
+
+export function git(args: string[]): SpawnSyncReturns<string> {
+  return spawnSync('git', args, { encoding: 'utf8' });
+}
+
+export function currentHeadOrNull(): string {
+  const verify = git(['rev-parse', '--verify', 'HEAD']);
+  if (verify.status !== 0) return 'null';
+  const head = git(['rev-parse', 'HEAD']);
+  return head.status === 0 ? head.stdout.trim() : 'null';
+}
+
+export function sha256(content: string | Buffer): string {
+  return createHash('sha256').update(content).digest('hex');
+}
+
+export function hashFile(file: string): string {
+  return sha256(readFileSync(file));
+}
+
+export function ensureDir(dir: string): void {
+  mkdirSync(dir, { recursive: true });
+}
+
+export function runNode(script: string, args: string[], options: SpawnSyncOptions = {}) {
+  return spawnSync(process.execPath, [script, ...args], {
+    encoding: 'utf8',
+    stdio: 'pipe',
+    ...options,
+  });
+}
+
+export function runCommandString(command: string, options: SpawnSyncOptions = {}) {
+  console.error(`+ ${command}`);
+  return spawnSync(command, { encoding: 'utf8', stdio: 'inherit', shell: true, ...options });
+}
+
+export function runCommand(argv: string[], options: SpawnSyncOptions = {}) {
+  const [command, ...args] = argv;
+  return spawnSync(command, args, {
+    encoding: 'utf8',
+    stdio: 'inherit',
+    shell: process.platform === 'win32',
+    ...options,
+  });
+}
+
+export function slash(file: string): string {
+  return file.replace(/\\/g, '/');
+}
diff --git a/src/scripts/comet-state.ts b/src/scripts/comet-state.ts
new file mode 100644
index 00000000..2b18ab7f
--- /dev/null
+++ b/src/scripts/comet-state.ts
@@ -0,0 +1,500 @@
+#!/usr/bin/env node
+import { existsSync, mkdirSync, readdirSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import {
+  changeDirFor,
+  currentHeadOrNull,
+  fail,
+  fieldValue,
+  fileNonempty,
+  git,
+  green,
+  red,
+  setYamlField,
+  today,
+  validateChangeName,
+  validateEnum,
+  writeYamlData,
+  yamlFileFor,
+  yellow,
+} from './comet-lib.js';
+
+const ENUMS: Record<string, string[]> = {
+  workflow: ['full', 'hotfix', 'tweak'],
+  phase: ['open', 'design', 'build', 'verify', 'archive'],
+  build_mode: ['subagent-driven-development', 'executing-plans', 'direct'],
+  build_pause: ['null', 'plan-ready'],
+  isolation: ['branch', 'worktree'],
+  verify_mode: ['light', 'full'],
+  verify_result: ['pending', 'pass', 'fail'],
+  branch_status: ['pending', 'handled'],
+  archived: ['true', 'false'],
+  direct_override: ['true', 'false'],
+};
+
+const SET_FIELDS = new Set([
+  'workflow',
+  'phase',
+  'build_mode',
+  'build_pause',
+  'isolation',
+  'verify_mode',
+  'verify_result',
+  'verification_report',
+  'branch_status',
+  'archived',
+  'design_doc',
+  'plan',
+  'verified_at',
+  'created_at',
+  'direct_override',
+  'build_command',
+  'verify_command',
+  'handoff_context',
+  'handoff_hash',
+  'base_ref',
+]);
+
+function get(change: string, field: string): void {
+  validateChangeName(change);
+  const yaml = yamlFileFor(change);
+  if (!existsSync(yaml)) fail(`.comet.yaml not found at ${yaml}`);
+  console.log(fieldValue(yaml, field));
+}
+
+function getValue(change: string, field: string): string {
+  const yaml = yamlFileFor(change);
+  return fieldValue(yaml, field);
+}
+
+function set(change: string, field: string, value: string, quiet: boolean = false): void {
+  validateChangeName(change);
+  const yaml = yamlFileFor(change);
+  if (!existsSync(yaml)) fail(`.comet.yaml not found at ${yaml}`);
+  if (field === 'phase') {
+    yellow("WARNING: Setting 'phase' directly bypasses state machine constraints.");
+    yellow('  Consider using: comet-state.js transition <change-name> <event>');
+  } else if (!SET_FIELDS.has(field)) {
+    red(`ERROR: Unknown field: '${field}'`);
+    red('Valid fields:');
+    red('  workflow, phase, design_doc, plan, build_mode, build_pause, isolation,');
+    red('  verify_mode, verify_result, verification_report, branch_status,');
+    red('  verified_at, created_at, archived, base_ref, direct_override,');
+    red('  build_command, verify_command, handoff_context, handoff_hash');
+    process.exit(1);
+  }
+  if (ENUMS[field]) validateEnum(value, ENUMS[field]);
+  setYamlField(yaml, field, value);
+  if (!quiet) green(`[SET] ${field}=${value}`);
+}
+
+function init(change: string, workflow: string): void {
+  validateChangeName(change);
+  validateEnum(workflow, ENUMS.workflow);
+  const changeDir = changeDirFor(change);
+  const yaml = yamlFileFor(change);
+  if (existsSync(yaml)) fail(`.comet.yaml already exists at ${yaml}`);
+  mkdirSync(changeDir, { recursive: true });
+  const preset = workflow === 'full' ? ['null', 'null', 'null'] : ['direct', 'branch', 'light'];
+  writeYamlData(yaml, {
+    workflow,
+    phase: 'open',
+    build_mode: preset[0],
+    build_pause: 'null',
+    isolation: preset[1],
+    verify_mode: preset[2],
+    base_ref: currentHeadOrNull(),
+    design_doc: 'null',
+    plan: 'null',
+    verify_result: 'pending',
+    verification_report: 'null',
+    branch_status: 'pending',
+    created_at: today(),
+    verified_at: 'null',
+    archived: 'false',
+  });
+  green(`Initialized: ${yaml} (workflow=${workflow})`);
+}
+
+function requirePhase(change: string, expected: string): void {
+  const actual = getValue(change, 'phase');
+  if (actual !== expected)
+    fail(`Cannot transition '${change}': expected phase ${expected}, got ${actual}`);
+}
+
+function requireVerificationEvidence(change: string): void {
+  const report = getValue(change, 'verification_report');
+  const branchStatus = getValue(change, 'branch_status');
+  if (!report || report === 'null' || !existsSync(report)) {
+    fail(
+      `Cannot transition '${change}': verification_report must point to an existing report file`,
+    );
+  }
+  if (branchStatus !== 'handled')
+    fail(`Cannot transition '${change}': branch_status must be handled`);
+}
+
+function requireBuildDecisions(change: string): void {
+  const workflow = getValue(change, 'workflow');
+  const buildMode = getValue(change, 'build_mode');
+  const isolation = getValue(change, 'isolation');
+  const directOverride = getValue(change, 'direct_override');
+  if (!['branch', 'worktree'].includes(isolation)) {
+    fail(
+      `Cannot transition '${change}': isolation must be branch or worktree, got '${isolation || 'null'}'`,
+    );
+  }
+  if (!ENUMS.build_mode.includes(buildMode)) {
+    fail(
+      `Cannot transition '${change}': build_mode must be selected before leaving build, got '${buildMode || 'null'}'`,
+    );
+  }
+  if (
+    buildMode === 'direct' &&
+    !['hotfix', 'tweak'].includes(workflow) &&
+    directOverride !== 'true'
+  ) {
+    fail(
+      `Cannot transition '${change}': build_mode=direct is only allowed for hotfix/tweak unless direct_override=true`,
+    );
+  }
+}
+
+function transition(change: string, event: string): void {
+  validateChangeName(change);
+  validateEnum(event, [
+    'open-complete',
+    'design-complete',
+    'build-complete',
+    'verify-pass',
+    'verify-fail',
+    'archived',
+  ]);
+  if (event === 'open-complete') {
+    requirePhase(change, 'open');
+    set(change, 'phase', getValue(change, 'workflow') === 'full' ? 'design' : 'build', true);
+  } else if (event === 'design-complete') {
+    requirePhase(change, 'design');
+    set(change, 'phase', 'build', true);
+  } else if (event === 'build-complete') {
+    requirePhase(change, 'build');
+    requireBuildDecisions(change);
+    set(change, 'phase', 'verify', true);
+    set(change, 'verify_result', 'pending', true);
+    set(change, 'verification_report', 'null', true);
+    set(change, 'branch_status', 'pending', true);
+  } else if (event === 'verify-pass') {
+    requirePhase(change, 'verify');
+    requireVerificationEvidence(change);
+    set(change, 'verify_result', 'pass', true);
+    set(change, 'phase', 'archive', true);
+    set(change, 'verified_at', today(), true);
+  } else if (event === 'verify-fail') {
+    requirePhase(change, 'verify');
+    set(change, 'verify_result', 'fail', true);
+    set(change, 'phase', 'build', true);
+    set(change, 'branch_status', 'pending', true);
+  } else if (event === 'archived') {
+    requirePhase(change, 'archive');
+    set(change, 'archived', 'true', true);
+  }
+  green(`[TRANSITION] ${event}`);
+}
+
+let checkBlock = false;
+function pass(msg: string): void {
+  console.log(`  \u001b[32m[PASS]\u001b[0m ${msg}`);
+}
+function block(msg: string): void {
+  console.log(`  \u001b[31m[FAIL]\u001b[0m ${msg}`);
+  checkBlock = true;
+}
+function checkNonempty(desc: string, file: string): void {
+  if (fileNonempty(file)) pass(`${desc} non-empty`);
+  else block(`${desc} missing or empty`);
+}
+function checkYamlIs(field: string, expected: string, change: string): void {
+  const actual = getValue(change, field);
+  if (actual === expected) pass(`${field}=${actual} (expected: ${expected})`);
+  else block(`${field}=${actual} (expected: ${expected})`);
+}
+function checkYamlEmpty(field: string, change: string): void {
+  const value = getValue(change, field);
+  if (!value || value === 'null') pass(`${field} is empty/null`);
+  else block(`${field}=${value} (expected: empty/null)`);
+}
+
+function check(change: string, phase: string): void {
+  validateChangeName(change);
+  validateEnum(phase, ['open', 'design', 'build', 'verify', 'archive']);
+  checkBlock = false;
+  const changeDir = join('openspec', 'changes', change);
+  const yaml = join(changeDir, '.comet.yaml');
+  console.log(`=== Entry Check: comet-${phase} ===`);
+  if (!existsSync(yaml)) fail(`.comet.yaml not found at ${yaml}`);
+  if (phase === 'open') {
+    pass('.comet.yaml exists');
+    checkYamlIs('phase', 'open', change);
+  } else if (phase === 'design') {
+    pass('.comet.yaml exists');
+    checkYamlIs('phase', 'design', change);
+    checkYamlIs('workflow', 'full', change);
+    checkYamlEmpty('design_doc', change);
+    checkNonempty('proposal.md', join(changeDir, 'proposal.md'));
+    checkNonempty('design.md', join(changeDir, 'design.md'));
+    checkNonempty('tasks.md', join(changeDir, 'tasks.md'));
+  } else if (phase === 'build') {
+    pass('.comet.yaml exists');
+    checkYamlIs('phase', 'build', change);
+    const workflow = getValue(change, 'workflow');
+    if (workflow === 'full') {
+      const designDoc = getValue(change, 'design_doc');
+      if (designDoc && designDoc !== 'null' && existsSync(designDoc))
+        pass(`design_doc=${designDoc} (file exists)`);
+      else block(`design_doc=${designDoc} (expected: non-null and file exists)`);
+    } else {
+      pass(`workflow=${workflow} (design_doc not required)`);
+    }
+    checkNonempty('proposal.md', join(changeDir, 'proposal.md'));
+    checkNonempty('tasks.md', join(changeDir, 'tasks.md'));
+  } else if (phase === 'verify') {
+    pass('.comet.yaml exists');
+    checkYamlIs('phase', 'verify', change);
+    const result = getValue(change, 'verify_result');
+    if (result === 'pending' || !result || result === 'null')
+      pass(`verify_result=${result} (expected: pending or null)`);
+    else block(`verify_result=${result} (expected: pending or null)`);
+  } else if (phase === 'archive') {
+    pass('.comet.yaml exists');
+    checkYamlIs('phase', 'archive', change);
+    checkYamlIs('verify_result', 'pass', change);
+    const archived = getValue(change, 'archived');
+    if (archived !== 'true') pass(`archived=${archived} (expected: not true)`);
+    else block(`archived=${archived} (expected: not true)`);
+  }
+  console.log('');
+  if (checkBlock) {
+    red('BLOCKED — fix failing checks before proceeding');
+    process.exit(1);
+  }
+  green('ALL CHECKS PASSED — ready to proceed');
+}
+
+function fieldStatus(field: string, value: string, file: string = ''): void {
+  if (!value || value === 'null') console.log(`  - ${field}: PENDING`);
+  else if (file && !existsSync(file))
+    console.log(`  - ${field}: BROKEN (path ${value} does not exist)`);
+  else console.log(`  - ${field}: DONE (${value})`);
+}
+
+function recover(change: string): void {
+  validateChangeName(change);
+  const changeDir = join('openspec', 'changes', change);
+  const yaml = join(changeDir, '.comet.yaml');
+  if (!existsSync(yaml)) fail(`.comet.yaml not found at ${yaml}`);
+  const phase = getValue(change, 'phase');
+  const workflow = getValue(change, 'workflow');
+  console.log(`=== Recovery Context: ${change} ===`);
+  console.log(`Phase: ${phase}`);
+  console.log(`Workflow: ${workflow}`);
+  console.log('');
+  const values = Object.fromEntries(
+    [
+      'design_doc',
+      'plan',
+      'verify_result',
+      'verify_mode',
+      'verification_report',
+      'branch_status',
+      'handoff_context',
+      'handoff_hash',
+      'isolation',
+      'build_mode',
+      'build_pause',
+      'direct_override',
+      'archived',
+    ].map((f) => [f, getValue(change, f)]),
+  );
+  console.log('State fields:');
+  if (phase === 'open') {
+    console.log('  Artifacts:');
+    for (const f of ['proposal.md', 'design.md', 'tasks.md'])
+      console.log(`  - ${f}: ${fileNonempty(join(changeDir, f)) ? 'DONE' : 'PENDING'}`);
+    console.log(
+      '\nRecovery action: Create or complete missing artifacts, then use AskUserQuestion for user confirmation.',
+    );
+  } else if (phase === 'design') {
+    console.log('  Artifacts:');
+    for (const f of ['proposal.md', 'design.md', 'tasks.md'])
+      console.log(
+        `  - ${f}: ${fileNonempty(join(changeDir, f)) ? 'DONE' : 'MISSING (unexpected in design phase)'}`,
+      );
+    console.log('\n  Design progress:');
+    fieldStatus('handoff_context', values.handoff_context, values.handoff_context);
+    fieldStatus('handoff_hash', values.handoff_hash);
+    fieldStatus('design_doc', values.design_doc, values.design_doc);
+    console.log('');
+    if (values.design_doc && values.design_doc !== 'null' && existsSync(values.design_doc))
+      console.log(
+        'Recovery action: Design Doc already created and linked. Run guard to transition to build.',
+      );
+    else if (
+      values.handoff_context &&
+      values.handoff_context !== 'null' &&
+      existsSync(values.handoff_context)
+    )
+      console.log(
+        'Recovery action: Handoff generated but Design Doc not yet created. Resume from brainstorming confirmation (Step 1c).',
+      );
+    else
+      console.log(
+        'Recovery action: No handoff generated yet. Start from Step 1a (generate handoff package).',
+      );
+  } else if (phase === 'build') {
+    console.log('  Build decisions:');
+    fieldStatus('isolation', values.isolation);
+    fieldStatus('build_mode', values.build_mode);
+    fieldStatus('build_pause', values.build_pause);
+    if (values.build_mode === 'direct' && !['hotfix', 'tweak'].includes(workflow))
+      fieldStatus('direct_override', values.direct_override);
+    console.log('\n  Plan:');
+    fieldStatus('plan', values.plan, values.plan);
+    const tasksFile = join(changeDir, 'tasks.md');
+    let total = 0;
+    let done = 0;
+    if (existsSync(tasksFile)) {
+      const text = readFileSync(tasksFile, 'utf8');
+      total = (text.match(/^- \[/gm) ?? []).length;
+      done = (text.match(/^- \[x\]/gm) ?? []).length;
+      console.log(`\n  Tasks: ${done}/${total} done, ${total - done} pending`);
+    } else console.log('\n  Tasks: tasks.md MISSING');
+    console.log('');
+    if (
+      values.build_pause === 'plan-ready' &&
+      values.plan &&
+      values.plan !== 'null' &&
+      existsSync(values.plan) &&
+      (!values.isolation ||
+        values.isolation === 'null' ||
+        !values.build_mode ||
+        values.build_mode === 'null')
+    )
+      console.log(
+        'Recovery action: Plan-ready pause detected. Ask the user whether to continue, then choose isolation and build mode without regenerating the plan.',
+      );
+    else if (
+      values.build_pause === 'plan-ready' &&
+      (!values.plan || values.plan === 'null' || !existsSync(values.plan))
+    )
+      console.log(
+        'Recovery action: Plan-ready pause is recorded, but the plan file is missing. Restore the plan file or rerun writing-plans before choosing execution.',
+      );
+    else if (values.build_pause === 'plan-ready')
+      console.log(
+        'Recovery action: Plan-ready pause is stale because build decisions are already selected. Clear build_pause to null, then continue from the first unchecked task.',
+      );
+    else if (!values.isolation || values.isolation === 'null')
+      console.log(
+        'Recovery action: Isolation not selected. Use AskUserQuestion to ask user for branch/worktree choice.',
+      );
+    else if (!values.build_mode || values.build_mode === 'null')
+      console.log(
+        'Recovery action: Build mode not selected. Use AskUserQuestion to ask user for execution method.',
+      );
+    else if (!existsSync(tasksFile))
+      console.log('Recovery action: tasks.md missing. Verify change directory integrity.');
+    else if (total - done > 0)
+      console.log('Recovery action: Read tasks.md and continue from first unchecked task.');
+    else console.log('Recovery action: All tasks done. Run guard to transition to verify.');
+  } else if (phase === 'verify') {
+    console.log('  Verification:');
+    fieldStatus('verify_result', values.verify_result);
+    fieldStatus('verify_mode', values.verify_mode);
+    fieldStatus('verification_report', values.verification_report, values.verification_report);
+    fieldStatus('branch_status', values.branch_status);
+    console.log('');
+    if (values.verify_result === 'pass' && values.branch_status === 'handled')
+      console.log('Recovery action: Verification complete. Run guard to transition to archive.');
+    else if (values.verify_result === 'pass')
+      console.log(
+        'Recovery action: Verification passed but branch not yet handled. Complete branch handling and set branch_status to handled.',
+      );
+    else if (values.verify_result === 'fail')
+      console.log(
+        'Recovery action: Verification failed and rolled back to build. Resume from /comet-build.',
+      );
+    else
+      console.log(
+        'Recovery action: Verification not yet started or in progress. Run scale assessment then verify.',
+      );
+  } else if (phase === 'archive') {
+    console.log('  Archive:');
+    fieldStatus('verify_result', values.verify_result);
+    fieldStatus('archived', values.archived);
+    console.log('\nRecovery action: Run /comet-archive to complete archiving.');
+  }
+  console.log('\n=== End Recovery Context ===');
+}
+
+function countSpecFiles(dir: string): number {
+  if (!existsSync(dir)) return 0;
+  let count = 0;
+  for (const entry of readdirSync(dir, { withFileTypes: true })) {
+    const p = join(dir, entry.name);
+    if (entry.isDirectory()) count += countSpecFiles(p);
+    else if (entry.isFile() && entry.name === 'spec.md') count += 1;
+  }
+  return count;
+}
+
+function scale(change: string): void {
+  validateChangeName(change);
+  const changeDir = join('openspec', 'changes', change);
+  const yaml = join(changeDir, '.comet.yaml');
+  if (!existsSync(yaml)) fail(`.comet.yaml not found at ${yaml}`);
+  const tasksFile = join(changeDir, 'tasks.md');
+  const taskCount = existsSync(tasksFile)
+    ? (readFileSync(tasksFile, 'utf8').match(/^- \[/gm) ?? []).length
+    : 0;
+  const deltaSpecCount = countSpecFiles(join(changeDir, 'specs'));
+  let changedFiles = 0;
+  if (git(['rev-parse', '--git-dir']).status === 0) {
+    let baseRef = '';
+    const plan = getValue(change, 'plan');
+    if (plan && plan !== 'null' && existsSync(plan)) {
+      baseRef =
+        readFileSync(plan, 'utf8')
+          .match(/^base-ref:\s*(.*)$/m)?.[1]
+          ?.trim() ?? '';
+    }
+    if (!baseRef || baseRef === 'null') baseRef = getValue(change, 'base_ref');
+    const diff =
+      baseRef && baseRef !== 'null' && git(['rev-parse', '--verify', baseRef]).status === 0
+        ? git(['diff', '--name-only', `${baseRef}...HEAD`])
+        : git(['diff', '--name-only', 'HEAD']);
+    changedFiles = diff.status === 0 ? diff.stdout.split(/\r?\n/).filter(Boolean).length : 0;
+  }
+  const result = taskCount > 3 || deltaSpecCount > 1 || changedFiles > 4 ? 'full' : 'light';
+  console.error(`=== Scale Assessment: ${change} ===`);
+  console.error(`  Tasks: ${taskCount} (threshold: 3)`);
+  console.error(`  Delta specs: ${deltaSpecCount} capabilities (threshold: 1)`);
+  console.error(`  Changed files: ${changedFiles} (threshold: 4)`);
+  console.error(`  → Result: ${result}`);
+  setYamlField(yaml, 'verify_mode', result);
+  green(`[SCALE] verify_mode=${result}`);
+}
+
+const [subcommand, ...args] = process.argv.slice(2);
+if (subcommand === 'init' && args.length >= 2) init(args[0], args[1]);
+else if (subcommand === 'get' && args.length >= 2) get(args[0], args[1]);
+else if (subcommand === 'set' && args.length >= 3) set(args[0], args[1], args.slice(2).join(' '));
+else if (subcommand === 'transition' && args.length >= 2) transition(args[0], args[1]);
+else if (subcommand === 'check' && args.length >= 2)
+  if (args[2] === '--recover') recover(args[0]);
+  else check(args[0], args[1]);
+else if (subcommand === 'scale' && args.length >= 1) scale(args[0]);
+else {
+  red(`Unknown subcommand: ${subcommand ?? ''}`);
+  console.error('\nUsage: comet-state.js <subcommand> <change-name> [args...]');
+  process.exit(1);
+}
diff --git a/src/scripts/comet-yaml-validate.ts b/src/scripts/comet-yaml-validate.ts
new file mode 100644
index 00000000..0f6fea73
--- /dev/null
+++ b/src/scripts/comet-yaml-validate.ts
@@ -0,0 +1,100 @@
+#!/usr/bin/env node
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import {
+  changeDirFor,
+  fieldValue,
+  green,
+  KNOWN_KEYS,
+  parseYamlLines,
+  red,
+  validateChangeName,
+  yellow,
+} from './comet-lib.js';
+
+const change = process.argv[2];
+validateChangeName(change);
+const changeDir = changeDirFor(change);
+const yaml = join(changeDir, '.comet.yaml');
+let errors = 0;
+let warnings = 0;
+
+function fail(message: string): void {
+  red(`  FAIL: ${message}`);
+  errors += 1;
+}
+
+function warn(message: string): void {
+  yellow(`  WARN: ${message}`);
+  warnings += 1;
+}
+
+function validateEnum(field: string, value: string, valid: string[]): void {
+  if (!value || value === 'null') return;
+  if (!valid.includes(value))
+    fail(`${field}='${value}' is not valid. Expected: ${valid.join(' ')}`);
+}
+
+console.error(`[VALIDATE] ${yaml}`);
+
+if (!existsSync(yaml)) {
+  fail(`.comet.yaml not found at ${yaml}`);
+} else {
+  const parsed = parseYamlLines(yaml);
+  const required = [
+    'workflow',
+    'phase',
+    'design_doc',
+    'plan',
+    'build_mode',
+    'isolation',
+    'verify_mode',
+    'verify_result',
+    'verified_at',
+    'archived',
+  ];
+  for (const field of required) {
+    if (!parsed.keys.includes(field)) fail(`missing required field '${field}'`);
+  }
+
+  validateEnum('workflow', fieldValue(yaml, 'workflow'), ['full', 'hotfix', 'tweak']);
+  validateEnum('phase', fieldValue(yaml, 'phase'), [
+    'open',
+    'design',
+    'build',
+    'verify',
+    'archive',
+  ]);
+  validateEnum('build_mode', fieldValue(yaml, 'build_mode'), [
+    'subagent-driven-development',
+    'executing-plans',
+    'direct',
+  ]);
+  validateEnum('build_pause', fieldValue(yaml, 'build_pause'), ['null', 'plan-ready']);
+  validateEnum('isolation', fieldValue(yaml, 'isolation'), ['branch', 'worktree']);
+  validateEnum('verify_mode', fieldValue(yaml, 'verify_mode'), ['light', 'full']);
+  validateEnum('verify_result', fieldValue(yaml, 'verify_result'), ['pending', 'pass', 'fail']);
+  validateEnum('branch_status', fieldValue(yaml, 'branch_status'), ['pending', 'handled']);
+  validateEnum('archived', fieldValue(yaml, 'archived'), ['true', 'false']);
+  validateEnum('direct_override', fieldValue(yaml, 'direct_override'), ['true', 'false']);
+
+  for (const field of ['design_doc', 'plan', 'handoff_context']) {
+    const value = fieldValue(yaml, field);
+    if (value && value !== 'null' && !existsSync(value))
+      fail(`${field}='${value}' does not exist on disk`);
+  }
+  const handoffHash = fieldValue(yaml, 'handoff_hash');
+  if (handoffHash && handoffHash !== 'null' && !/^[a-f0-9]{64}$/.test(handoffHash)) {
+    fail(`handoff_hash='${handoffHash}' is not a sha256 hex digest`);
+  }
+  for (const key of parsed.keys) {
+    if (!KNOWN_KEYS.has(key)) warn(`unknown field '${key}' found`);
+  }
+}
+
+console.error('');
+if (errors > 0) {
+  red(`${errors} error(s), ${warnings} warning(s) — validation FAILED`);
+  process.exit(1);
+}
+green(`0 errors, ${warnings} warning(s) — validation PASSED`);
diff --git a/src/scripts/tsconfig.json b/src/scripts/tsconfig.json
new file mode 100644
index 00000000..aefa0f6f
--- /dev/null
+++ b/src/scripts/tsconfig.json
@@ -0,0 +1,16 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "rootDir": ".",
+    "outDir": "../../assets/skills/comet/scripts",
+    "strict": true,
+    "esModuleInterop": true,
+    "forceConsistentCasingInFileNames": true,
+    "skipLibCheck": true,
+    "declaration": false,
+    "sourceMap": false
+  },
+  "include": ["./**/*.ts"]
+}
diff --git a/test/ts/detect.test.ts b/test/ts/detect.test.ts
index 09a56bcc..ef92addd 100644
--- a/test/ts/detect.test.ts
+++ b/test/ts/detect.test.ts
@@ -1,4 +1,4 @@
-import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
 import { promises as fs } from 'fs';
 import path from 'path';
 import os from 'os';
@@ -124,10 +124,18 @@ describe('detect', () => {
       expect(opencode).toBeDefined();
       if (!opencode) return;
 
+      const origHomedir = os.homedir;
+      vi.spyOn(os, 'homedir').mockReturnValue(tmpDir);
+
       await fs.mkdir(path.join(tmpDir, '.opencode', 'skills', 'comet'), { recursive: true });
       await fs.mkdir(path.join(tmpDir, '.opencode', 'skills', 'comet-open'), { recursive: true });
 
-      expect(await hasSkills(tmpDir, opencode, 'comet')).toBe(false);
+      try {
+        expect(await hasSkills(tmpDir, opencode, 'comet')).toBe(false);
+      } finally {
+        vi.mocked(os.homedir).mockRestore();
+        os.homedir = origHomedir;
+      }
     });
 
     it('detects OpenCode Comet skills when matching slash commands exist', async () => {
@@ -135,13 +143,21 @@ describe('detect', () => {
       expect(opencode).toBeDefined();
       if (!opencode) return;
 
+      const origHomedir = os.homedir;
+      vi.spyOn(os, 'homedir').mockReturnValue(tmpDir);
+
       await fs.mkdir(path.join(tmpDir, '.opencode', 'skills', 'comet'), { recursive: true });
       await fs.mkdir(path.join(tmpDir, '.opencode', 'skills', 'comet-open'), { recursive: true });
       await fs.mkdir(path.join(tmpDir, '.opencode', 'commands'), { recursive: true });
       await fs.writeFile(path.join(tmpDir, '.opencode', 'commands', 'comet.md'), '');
       await fs.writeFile(path.join(tmpDir, '.opencode', 'commands', 'comet-open.md'), '');
 
-      expect(await hasSkills(tmpDir, opencode, 'comet')).toBe(true);
+      try {
+        expect(await hasSkills(tmpDir, opencode, 'comet')).toBe(true);
+      } finally {
+        vi.mocked(os.homedir).mockRestore();
+        os.homedir = origHomedir;
+      }
     });
 
     it('detects Antigravity global skills in the Gemini Antigravity directory', async () => {
diff --git a/test/ts/init-e2e.test.ts b/test/ts/init-e2e.test.ts
index 785ceb24..ed3382ea 100644
--- a/test/ts/init-e2e.test.ts
+++ b/test/ts/init-e2e.test.ts
@@ -1,6 +1,7 @@
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
 import { execFileSync } from 'child_process';
 import { promises as fs } from 'fs';
+import { mkdirSync } from 'fs';
 import os from 'os';
 import path from 'path';
 
@@ -22,9 +23,10 @@ async function readManifest() {
 }
 
 function mockExternalSuccess() {
-  mockedExecFileSync.mockImplementation((command: unknown, args?: unknown) => {
+  mockedExecFileSync.mockImplementation((command: unknown, args?: unknown, options?: unknown) => {
     const cmd = String(command);
     const cmdArgs = Array.isArray(args) ? args.map((arg) => String(arg)) : [];
+    const opts = options as { cwd?: string } | undefined;
     if ((cmd === 'which' || cmd === 'where') && cmdArgs[0] === 'openspec') {
       return Buffer.from('/usr/bin/openspec');
     }
@@ -32,6 +34,12 @@ function mockExternalSuccess() {
       return Buffer.from('ok');
     }
     if ((cmd === 'npx' || cmd === 'npx.cmd') && cmdArgs[0] === 'skills') {
+      if (opts?.cwd && opts.cwd.includes('comet-lingma-superpowers-')) {
+        const skillsDir = path.join(opts.cwd, '.claude', 'skills');
+        mkdirSync(skillsDir, { recursive: true });
+        mkdirSync(path.join(skillsDir, 'brainstorming'), { recursive: true });
+        mkdirSync(path.join(skillsDir, 'using-superpowers'), { recursive: true });
+      }
       return Buffer.from('installed');
     }
     return Buffer.from('');
@@ -167,6 +175,7 @@ describe('comet init E2E', () => {
 
   it('installs all platforms from clean directory with --yes', async () => {
     mockExternalSuccess();
+    vi.spyOn(os, 'homedir').mockReturnValue(tmpDir);
 
     const { initCommand } = await import('../../src/commands/init.js');
     const result = await captureJsonOutput(() => initCommand(tmpDir, { yes: true, json: true }));

From 4891e295a57886134c1bd15b062802dda7543727 Mon Sep 17 00:00:00 2001
From: zheng <forggy0113@gmail.com>
Date: Sat, 6 Jun 2026 03:55:41 +0800
Subject: [PATCH 4/7] refactor: move script source to src/scripts/

---
 assets/skills/comet/scripts/comet-archive.js  | 102 -----
 assets/skills/comet/scripts/comet-env.js      |  19 -
 assets/skills/comet/scripts/comet-guard.js    | 280 -------------
 assets/skills/comet/scripts/comet-handoff.js  | 101 -----
 assets/skills/comet/scripts/comet-lib.js      | 208 ----------
 assets/skills/comet/scripts/comet-state.js    | 383 ------------------
 .../comet/scripts/comet-yaml-validate.js      |  63 ---
 7 files changed, 1156 deletions(-)

diff --git a/assets/skills/comet/scripts/comet-archive.js b/assets/skills/comet/scripts/comet-archive.js
index f9ea4333..86e2182e 100644
--- a/assets/skills/comet/scripts/comet-archive.js
+++ b/assets/skills/comet/scripts/comet-archive.js
@@ -1,14 +1,7 @@
 #!/usr/bin/env node
-<<<<<<< HEAD
 import { copyFileSync, existsSync, mkdirSync, readdirSync, readFileSync, renameSync, statSync, writeFileSync, } from 'node:fs';
 import { dirname, join } from 'node:path';
 import { fieldValue, green, red, runNode, scriptDir, today, validateChangeName, yellow, } from './comet-lib.js';
-=======
-import { copyFileSync, existsSync, mkdirSync, readdirSync, readFileSync, renameSync, statSync, writeFileSync } from 'node:fs';
-import { dirname, join } from 'node:path';
-import { fieldValue, green, red, runNode, scriptDir, today, validateChangeName, yellow } from './comet-lib.js';
-
->>>>>>> eeac7a023b8ea6033b2606f7fd7d412881e7c398
 const [change, flag] = process.argv.slice(2);
 const dryRun = flag === '--dry-run';
 validateChangeName(change, 'FATAL');
@@ -18,7 +11,6 @@ const archiveName = `${today()}-${change}`;
 const archiveDir = join('openspec', 'changes', 'archive', archiveName);
 let stepsOk = 0;
 let stepsTotal = 0;
-<<<<<<< HEAD
 function fatal(message) {
     red(`FATAL: ${message}`);
     process.exit(1);
@@ -141,97 +133,3 @@ else
     green(`Archive complete. ${stepsOk}/${stepsTotal} steps succeeded.`);
 if (stepsOk < stepsTotal)
     process.exit(1);
-=======
-
-function fatal(message) {
-  red(`FATAL: ${message}`);
-  process.exit(1);
-}
-
-function stepOk(message) { green(`  [OK] ${message}`); stepsOk += 1; stepsTotal += 1; }
-function stepFail(message) { red(`  [FAIL] ${message}`); stepsTotal += 1; }
-function stepDry(message) { yellow(`  [DRY-RUN] ${message}`); stepsOk += 1; stepsTotal += 1; }
-function y(field) { return fieldValue(yaml, field); }
-
-console.error(`=== Comet Archive: ${change} ===`);
-if (!existsSync(yaml)) fatal(`.comet.yaml not found in ${changeDir}/`);
-const designDoc = y('design_doc');
-const planPath = y('plan');
-if (y('phase') !== 'archive') fatal(`phase is '${y('phase')}', expected 'archive'`);
-if (y('verify_result') !== 'pass') fatal(`verify_result is '${y('verify_result')}', expected 'pass'. Run comet-verify first.`);
-if (y('archived') === 'true') fatal('change already archived');
-stepOk('Entry state verified');
-if (existsSync(archiveDir)) fatal(`archive target already exists: ${archiveDir}`);
-stepOk('Archive target available');
-
-function syncDeltaSpecs() {
-  const deltaRoot = join(changeDir, 'specs');
-  if (!existsSync(deltaRoot)) return;
-  for (const capability of readdirSync(deltaRoot)) {
-    const deltaSpecDir = join(deltaRoot, capability);
-    if (!statSync(deltaSpecDir).isDirectory()) continue;
-    const deltaSpec = join(deltaSpecDir, 'spec.md');
-    const mainSpec = join('openspec', 'specs', capability, 'spec.md');
-    if (!existsSync(deltaSpec)) continue;
-    if (dryRun) {
-      stepDry(`Would sync: ${capability} → ${mainSpec}`);
-      continue;
-    }
-    mkdirSync(dirname(mainSpec), { recursive: true });
-    copyFileSync(deltaSpec, mainSpec);
-    stepOk(`Delta spec synced: ${capability} → openspec/specs/${capability}/spec.md`);
-  }
-}
-
-function annotateFrontmatter(file, extraFields) {
-  if (!existsSync(file)) return;
-  if (dryRun) {
-    stepDry(`Would annotate: ${file}`);
-    return;
-  }
-  const text = readFileSync(file, 'utf8');
-  let next;
-  if (text.startsWith('---')) {
-    const lines = text.split(/\r?\n/);
-    const out = [];
-    let inserted = false;
-    for (let i = 0; i < lines.length; i += 1) {
-      const line = lines[i];
-      if (/^archived-with:/.test(line)) continue;
-      if (i > 0 && line === '---' && !inserted) {
-        out.push(`archived-with: ${archiveName}`);
-        if (extraFields) out.push(extraFields);
-        inserted = true;
-      }
-      out.push(line);
-    }
-    next = out.join('\n');
-  } else {
-    next = `---\narchived-with: ${archiveName}\n${extraFields ? `${extraFields}\n` : ''}status: final\n---\n${text}`;
-  }
-  writeFileSync(file, next);
-  stepOk(`Annotated: ${file}`);
-}
-
-syncDeltaSpecs();
-if (designDoc && designDoc !== 'null') annotateFrontmatter(designDoc, 'status: final');
-if (planPath && planPath !== 'null') annotateFrontmatter(planPath, '');
-if (dryRun) stepDry(`Would move: ${changeDir} → ${archiveDir}`);
-else {
-  mkdirSync(join('openspec', 'changes', 'archive'), { recursive: true });
-  renameSync(changeDir, archiveDir);
-  stepOk(`Moved to: ${archiveDir}`);
-}
-const archiveYaml = join(archiveDir, '.comet.yaml');
-if (dryRun) stepDry(`Would set archived: true in ${archiveYaml}`);
-else if (existsSync(archiveYaml)) {
-  const state = join(scriptDir, 'comet-state.js');
-  const result = runNode(state, ['transition', archiveName, 'archived']);
-  if (result.status === 0) stepOk('archived: true');
-  else stepFail('archived: true');
-} else stepFail('archived: true (.comet.yaml not found after move)');
-console.error('');
-if (dryRun) yellow(`Dry run complete. ${stepsOk}/${stepsTotal} steps would succeed.`);
-else green(`Archive complete. ${stepsOk}/${stepsTotal} steps succeeded.`);
-if (stepsOk < stepsTotal) process.exit(1);
->>>>>>> eeac7a023b8ea6033b2606f7fd7d412881e7c398
diff --git a/assets/skills/comet/scripts/comet-env.js b/assets/skills/comet/scripts/comet-env.js
index 7f0b169a..abbfc3bf 100644
--- a/assets/skills/comet/scripts/comet-env.js
+++ b/assets/skills/comet/scripts/comet-env.js
@@ -2,7 +2,6 @@
 import { existsSync } from 'node:fs';
 import { join } from 'node:path';
 import { scriptDir } from './comet-lib.js';
-<<<<<<< HEAD
 const env = {
     COMET_STATE: join(scriptDir, 'comet-state.js'),
     COMET_GUARD: join(scriptDir, 'comet-guard.js'),
@@ -16,22 +15,4 @@ if (missing.length > 0) {
     console.error('Expected path pattern: */comet/scripts/comet-*.js under project or platform skill directories');
     process.exit(1);
 }
-=======
-
-const env = {
-  COMET_STATE: join(scriptDir, 'comet-state.js'),
-  COMET_GUARD: join(scriptDir, 'comet-guard.js'),
-  COMET_HANDOFF: join(scriptDir, 'comet-handoff.js'),
-  COMET_ARCHIVE: join(scriptDir, 'comet-archive.js'),
-  COMET_YAML_VALIDATE: join(scriptDir, 'comet-yaml-validate.js'),
-};
-
-const missing = Object.values(env).filter((file) => !existsSync(file));
-if (missing.length > 0) {
-  console.error('ERROR: Comet scripts not found. Ensure the comet skill is installed completely.');
-  console.error('Expected path pattern: */comet/scripts/comet-*.js under project or platform skill directories');
-  process.exit(1);
-}
-
->>>>>>> eeac7a023b8ea6033b2606f7fd7d412881e7c398
 console.log(JSON.stringify(env, null, 2));
diff --git a/assets/skills/comet/scripts/comet-guard.js b/assets/skills/comet/scripts/comet-guard.js
index cb27de21..e889a4a7 100644
--- a/assets/skills/comet/scripts/comet-guard.js
+++ b/assets/skills/comet/scripts/comet-guard.js
@@ -1,34 +1,11 @@
 #!/usr/bin/env node
-<<<<<<< HEAD
 import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
 import { join } from 'node:path';
 import { fieldValue, fileNonempty, green, hashFile, red, runCommand, runCommandString, runNode, scriptDir, sha256, slash, validateChangeName, yellow, } from './comet-lib.js';
-=======
-import { existsSync, readFileSync } from 'node:fs';
-import { join } from 'node:path';
-import {
-  changeDirFor,
-  fieldValue,
-  fileNonempty,
-  green,
-  hashFile,
-  red,
-  runCommand,
-  runCommandString,
-  runNode,
-  scriptDir,
-  sha256,
-  slash,
-  validateChangeName,
-  yellow,
-} from './comet-lib.js';
-
->>>>>>> eeac7a023b8ea6033b2606f7fd7d412881e7c398
 const [change, phase, applyFlag] = process.argv.slice(2);
 validateChangeName(change);
 const apply = applyFlag === '--apply';
 let changeDir = join('openspec', 'changes', change);
-<<<<<<< HEAD
 if (phase === 'archive' &&
     !existsSync(changeDir) &&
     existsSync(join('openspec', 'changes', 'archive', change))) {
@@ -318,257 +295,10 @@ if (block) {
     console.error('');
     red('BLOCKED — fix failing checks before proceeding to next phase');
     process.exit(1);
-=======
-if (phase === 'archive' && !existsSync(changeDir) && existsSync(join('openspec', 'changes', 'archive', change))) {
-  changeDir = join('openspec', 'changes', 'archive', change);
-}
-const yaml = join(changeDir, '.comet.yaml');
-let block = false;
-
-function check(desc, fn) {
-  try {
-    const result = fn();
-    if (result === true || result === undefined) green(`  [PASS] ${desc}`);
-    else throw new Error(String(result));
-  } catch (error) {
-    red(`  [FAIL] ${desc}`);
-    const message = error instanceof Error ? error.message : String(error);
-    if (message) for (const line of message.split(/\r?\n/)) red(`    ${line}`);
-    block = true;
-  }
-}
-
-function y(field) {
-  return fieldValue(yaml, field);
-}
-
-function preflight() {
-  if (!existsSync(changeDir)) {
-    red(`FATAL: change directory not found: ${changeDir}`);
-    process.exit(1);
-  }
-  if (!existsSync(yaml)) {
-    red(`FATAL: .comet.yaml not found in ${changeDir}`);
-    process.exit(1);
-  }
-  const validateScript = join(scriptDir, 'comet-yaml-validate.js');
-  if (existsSync(validateScript)) {
-    const result = runNode(validateScript, [change]);
-    if (result.status !== 0) {
-      process.stderr.write(result.stderr || '');
-      red('FATAL: .comet.yaml schema validation failed');
-      process.exit(1);
-    }
-  }
-}
-
-function tasksAllDone() {
-  const tasks = join(changeDir, 'tasks.md');
-  if (!existsSync(tasks)) throw new Error(`tasks.md is missing at ${tasks}\nNext: restore or create tasks.md for this change before leaving build.`);
-  const text = readFileSync(tasks, 'utf8');
-  if (!/- \[x\]/.test(text)) throw new Error("tasks.md has no completed tasks.\nNext: complete implementation tasks and mark them with '- [x]'.");
-  const unfinished = text.split(/\r?\n/).map((line, index) => ({ line, index: index + 1 })).filter(({ line }) => /- \[ \]/.test(line));
-  if (unfinished.length > 0) {
-    throw new Error(`Unfinished tasks:\n${unfinished.map(({ line, index }) => `${index}:${line}`).join('\n')}\nNext: complete or explicitly remove unfinished tasks, then mark tasks.md with '- [x]'.`);
-  }
-}
-
-function tasksHasAny() {
-  return existsSync(join(changeDir, 'tasks.md')) && /- \[/.test(readFileSync(join(changeDir, 'tasks.md'), 'utf8'));
-}
-
-function projectConfigValue(field) {
-  const local = y(field);
-  if (local && local !== 'null') return local;
-  for (const config of ['.comet.yaml', 'comet.yaml', '.comet.yml', 'comet.yml']) {
-    if (existsSync(config)) {
-      const value = fieldValue(config, field);
-      if (value && value !== 'null') return value;
-    }
-  }
-  return '';
-}
-
-function buildPasses() {
-  if (process.env.COMET_SKIP_BUILD === '1') return;
-  const configured = projectConfigValue('build_command');
-  if (configured) {
-    const result = runCommandString(configured);
-    if (result.status !== 0) throw new Error(`command failed: ${configured}`);
-    return;
-  }
-  if (existsSync('package.json') && /"build"/.test(readFileSync('package.json', 'utf8'))) {
-    const result = runCommand(['npm', 'run', 'build']);
-    if (result.status !== 0) throw new Error('npm run build failed');
-    return;
-  }
-  if (existsSync('pom.xml')) {
-    const result = existsSync('./mvnw') ? runCommand(['./mvnw', 'compile', '-q']) : runCommand(['mvn', 'compile', '-q']);
-    if (result.status !== 0) throw new Error('maven build failed');
-    return;
-  }
-  if (existsSync('Cargo.toml')) {
-    const result = runCommand(['cargo', 'build']);
-    if (result.status !== 0) throw new Error('cargo build failed');
-    return;
-  }
-  throw new Error('no build command found');
-}
-
-function verificationCommandPasses() {
-  if (process.env.COMET_SKIP_BUILD === '1') return;
-  const configured = projectConfigValue('verify_command');
-  if (configured) {
-    const result = runCommandString(configured);
-    if (result.status !== 0) throw new Error(`command failed: ${configured}`);
-    return;
-  }
-  buildPasses();
-}
-
-function sourceFiles() {
-  const files = [join(changeDir, 'proposal.md'), join(changeDir, 'design.md'), join(changeDir, 'tasks.md')];
-  const specsRoot = join(changeDir, 'specs');
-  if (existsSync(specsRoot)) {
-    const { readdirSync, statSync } = awaitFs;
-    function walk(dir) {
-      for (const entry of readdirSync(dir)) {
-        const p = join(dir, entry);
-        const stat = statSync(p);
-        if (stat.isDirectory()) walk(p);
-        else if (entry === 'spec.md') files.push(p);
-      }
-    }
-    walk(specsRoot);
-  }
-  return files;
-}
-import * as awaitFs from 'node:fs';
-
-function computeHandoffHash() {
-  let content = '';
-  for (const file of sourceFiles()) if (existsSync(file)) content += `path:${slash(file)}\nsha256:${hashFile(file)}\n`;
-  return sha256(content);
-}
-
-function designHandoffContextValid() {
-  const context = y('handoff_context');
-  const recordedHash = y('handoff_hash');
-  if (!context || context === 'null') throw new Error('handoff_context is missing from .comet.yaml\nNext: run node "$COMET_HANDOFF" <change> design --write before invoking Superpowers.');
-  if (!fileNonempty(context)) throw new Error(`handoff_context does not point to a non-empty file: ${context}\nNext: regenerate the design handoff with comet-handoff.js.`);
-  if (!/^[a-f0-9]{64}$/.test(recordedHash)) throw new Error(`handoff_hash is missing or invalid: ${recordedHash || 'null'}\nNext: regenerate the design handoff with comet-handoff.js.`);
-  const actualHash = computeHandoffHash();
-  if (actualHash !== recordedHash) throw new Error(`OpenSpec artifacts changed after handoff was generated.\nExpected handoff_hash: ${recordedHash}\nActual handoff_hash:   ${actualHash}\nNext: rerun comet-handoff.js so Superpowers receives the current OpenSpec context.`);
-  const markdown = context.replace(/\.json$/, '.md');
-  if (!fileNonempty(markdown)) throw new Error(`design handoff markdown is missing or empty: ${markdown}\nNext: regenerate the design handoff with comet-handoff.js.`);
-}
-
-function designHandoffMarkdownTraceable() {
-  const context = y('handoff_context');
-  if (!context || context === 'null') throw new Error('handoff_context is missing from .comet.yaml');
-  const markdown = context.replace(/\.json$/, '.md');
-  if (!fileNonempty(markdown)) throw new Error(`design handoff markdown is missing or empty: ${markdown}`);
-  const text = readFileSync(markdown, 'utf8');
-  const missing = [];
-  if (!/^Generated-by: comet-handoff\.js$/m.test(text)) missing.push('handoff markdown is missing Generated-by marker');
-  if (!/^- Mode: (compact|full)$/m.test(text)) missing.push('handoff markdown is missing Mode marker');
-  for (const file of sourceFiles()) {
-    if (!existsSync(file)) continue;
-    if (!text.includes(`- Source: ${slash(file)}`)) missing.push(`handoff markdown is missing source reference: ${slash(file)}`);
-    if (!text.includes(`- SHA256: ${hashFile(file)}`)) missing.push(`handoff markdown is missing current sha256 for: ${file}`);
-  }
-  if (missing.length) throw new Error(missing.join('\n'));
-}
-
-function frontmatterHas(file, field, expected) {
-  const text = readFileSync(file, 'utf8').replace(/^\uFEFF/, '');
-  const match = text.match(/^\s*---\r?\n([\s\S]*?)\r?\n---/);
-  if (!match) return false;
-  return new RegExp(`^${field}: ['\"]?${expected}['\"]?\\s*$`, 'm').test(match[1]);
-}
-
-function guardOpen() {
-  console.error('=== Guard: open → next ===');
-  check('proposal.md exists and non-empty', () => fileNonempty(join(changeDir, 'proposal.md')));
-  check('design.md exists and non-empty', () => fileNonempty(join(changeDir, 'design.md')));
-  check('tasks.md exists and non-empty', () => fileNonempty(join(changeDir, 'tasks.md')));
-  check('tasks.md has at least one task', tasksHasAny);
-}
-
-function guardDesign() {
-  console.error('=== Guard: design → build ===');
-  const designDoc = y('design_doc');
-  check('proposal.md exists', () => fileNonempty(join(changeDir, 'proposal.md')));
-  check('design.md exists', () => fileNonempty(join(changeDir, 'design.md')));
-  check('tasks.md exists', () => fileNonempty(join(changeDir, 'tasks.md')));
-  check('design handoff context exists', designHandoffContextValid);
-  check('design handoff markdown is traceable', designHandoffMarkdownTraceable);
-  if (designDoc && designDoc !== 'null') {
-    check(`Design Doc (${designDoc}) exists`, () => fileNonempty(designDoc));
-    check('Design Doc frontmatter links current change', () => frontmatterHas(designDoc, 'comet_change', change));
-    check('Design Doc declares technical design role', () => frontmatterHas(designDoc, 'role', 'technical-design'));
-    check('Design Doc declares OpenSpec as canonical spec', () => frontmatterHas(designDoc, 'canonical_spec', 'openspec'));
-  } else yellow('  [WARN] No design_doc recorded in .comet.yaml');
-}
-
-function guardBuild() {
-  console.error('=== Guard: build → verify ===');
-  check('isolation selected', () => ['branch', 'worktree'].includes(y('isolation')) || `isolation must be branch or worktree, got '${y('isolation') || 'null'}'\nNext: ask the user to choose branch or worktree, create the chosen isolation, then run:\n  node "$COMET_STATE" set ${change} isolation <branch|worktree>`);
-  check('build_mode selected', () => ['subagent-driven-development', 'executing-plans', 'direct'].includes(y('build_mode')) || `build_mode must be selected before leaving build, got '${y('build_mode') || 'null'}'\nNext: ask the user to choose an execution mode, then run:\n  node "$COMET_STATE" set ${change} build_mode <subagent-driven-development|executing-plans>`);
-  check('build_mode allowed for workflow', () => y('build_mode') !== 'direct' || ['hotfix', 'tweak'].includes(y('workflow')) || y('direct_override') === 'true' || 'build_mode=direct is only allowed for hotfix/tweak unless direct_override: true is recorded\nNext: choose executing-plans or subagent-driven-development, or stop and ask the user for an explicit direct override.');
-  check('tasks.md all tasks checked', tasksAllDone);
-  check('proposal.md exists', () => fileNonempty(join(changeDir, 'proposal.md')));
-  check('Build passes', buildPasses);
-}
-
-function guardVerify() {
-  console.error('=== Guard: verify → archive ===');
-  check('tasks.md all tasks checked', tasksAllDone);
-  check('Build passes', verificationCommandPasses);
-  check('verification_report exists', () => y('verification_report') && y('verification_report') !== 'null' && existsSync(y('verification_report')));
-  check('branch_status=handled', () => y('branch_status') === 'handled');
-}
-
-function guardArchive() {
-  console.error('=== Guard: archive completeness ===');
-  check('archived is true', () => y('archived') === 'true');
-  check('proposal.md exists', () => fileNonempty(join(changeDir, 'proposal.md')));
-  check('tasks.md all tasks checked', tasksAllDone);
-}
-
-function applyStateUpdate() {
-  const state = join(scriptDir, 'comet-state.js');
-  if (!existsSync(state)) {
-    red('FATAL: comet-state.js not found; cannot apply state transition');
-    process.exit(1);
-  }
-  const event = { open: 'open-complete', design: 'design-complete', build: 'build-complete', verify: 'verify-pass' }[phase];
-  if (event) {
-    const result = runNode(state, ['transition', change, event]);
-    if (result.status !== 0) {
-      process.stderr.write(result.stderr || '');
-      process.exit(result.status ?? 1);
-    }
-  }
-}
-
-if (!['open', 'design', 'build', 'verify', 'archive'].includes(phase)) {
-  red(`Unknown phase: ${phase}`);
-  console.error('Valid phases: open, design, build, verify, archive');
-  process.exit(1);
-}
-preflight();
-({ open: guardOpen, design: guardDesign, build: guardBuild, verify: guardVerify, archive: guardArchive }[phase])();
-if (block) {
-  console.error('');
-  red('BLOCKED — fix failing checks before proceeding to next phase');
-  process.exit(1);
->>>>>>> eeac7a023b8ea6033b2606f7fd7d412881e7c398
 }
 console.error('');
 green('ALL CHECKS PASSED — ready for next phase');
 if (apply) {
-<<<<<<< HEAD
     applyStateUpdate();
     const messages = {
         open: `  [APPLY] .comet.yaml updated: phase=${y('phase')}`,
@@ -578,14 +308,4 @@ if (apply) {
     };
     if (messages[phase])
         green(messages[phase]);
-=======
-  applyStateUpdate();
-  const messages = {
-    open: `  [APPLY] .comet.yaml updated: phase=${y('phase')}`,
-    design: '  [APPLY] .comet.yaml updated: phase=build',
-    build: '  [APPLY] .comet.yaml updated: phase=verify, verify_result=pending',
-    verify: '  [APPLY] .comet.yaml updated: phase=archive, verify_result=pass',
-  };
-  if (messages[phase]) green(messages[phase]);
->>>>>>> eeac7a023b8ea6033b2606f7fd7d412881e7c398
 }
diff --git a/assets/skills/comet/scripts/comet-handoff.js b/assets/skills/comet/scripts/comet-handoff.js
index 0d42a909..65fdbf4f 100644
--- a/assets/skills/comet/scripts/comet-handoff.js
+++ b/assets/skills/comet/scripts/comet-handoff.js
@@ -1,5 +1,4 @@
 #!/usr/bin/env node
-<<<<<<< HEAD
 import { existsSync, readFileSync, readdirSync, statSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { ensureDir, fieldValue, fileNonempty, green, hashFile, runNode, scriptDir, sha256, slash, validateChangeName, } from './comet-lib.js';
@@ -99,98 +98,6 @@ if (fieldValue(yaml, 'phase') !== 'design')
 for (const required of ['proposal.md', 'design.md', 'tasks.md']) {
     if (!fileNonempty(join(changeDir, required)))
         error(`ERROR: required OpenSpec artifact missing or empty: ${join(changeDir, required)}`);
-=======
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
-import { join } from 'node:path';
-import { ensureDir, fieldValue, fileNonempty, green, hashFile, runNode, scriptDir, sha256, slash, validateChangeName } from './comet-lib.js';
-
-function error(message) {
-  console.error(`\u001b[31m${message}\u001b[0m`);
-  process.exit(1);
-}
-
-function walkSpecFiles(dir) {
-  if (!existsSync(dir)) return [];
-  const { readdirSync, statSync } = awaitFs;
-  const out = [];
-  function walk(current) {
-    for (const entry of readdirSync(current)) {
-      const p = join(current, entry);
-      const stat = statSync(p);
-      if (stat.isDirectory()) walk(p);
-      else if (entry === 'spec.md') out.push(p);
-    }
-  }
-  walk(dir);
-  return out.sort();
-}
-
-import * as awaitFs from 'node:fs';
-
-function sourceFiles(changeDir) {
-  return [join(changeDir, 'proposal.md'), join(changeDir, 'design.md'), join(changeDir, 'tasks.md'), ...walkSpecFiles(join(changeDir, 'specs'))];
-}
-
-function computeContextHash(files) {
-  let content = '';
-  for (const file of files) {
-    if (!existsSync(file)) continue;
-    content += `path:${slash(file)}\nsha256:${hashFile(file)}\n`;
-  }
-  return sha256(content);
-}
-
-function writeMarkdown(output, files, change, mode, contextHash) {
-  const chunks = [
-    '# Comet Design Handoff',
-    '',
-    `- Change: ${change}`,
-    '- Phase: design',
-    `- Mode: ${mode}`,
-    `- Context hash: ${contextHash}`,
-    '',
-    'Generated-by: comet-handoff.js',
-    '',
-    'OpenSpec remains the canonical capability spec. This handoff is a deterministic, source-traceable context pack, not an agent-authored summary.',
-    '',
-  ];
-  for (const file of files) {
-    if (!existsSync(file)) continue;
-    const text = readFileSync(file, 'utf8');
-    const lines = text.split(/\r?\n/);
-    chunks.push(`## ${slash(file)}`, '', `- Source: ${slash(file)}`, `- Lines: 1-${lines.length}`, `- SHA256: ${hashFile(file)}`, '');
-    if (mode === 'full' || lines.length <= 80) chunks.push('```md', text.replace(/\s*$/, ''), '```');
-    else chunks.push('[TRUNCATED]', '', '```md', lines.slice(0, 80).join('\n'), '```', '', `Full source: ${slash(file)}`);
-    chunks.push('');
-  }
-  writeFileSync(output, `${chunks.join('\n')}\n`);
-}
-
-function writeJson(output, files, change, mode, contextHash) {
-  const body = {
-    change,
-    phase: 'design',
-    mode,
-    canonical_spec: 'openspec',
-    generated_by: 'comet-handoff.js',
-    context_hash: contextHash,
-    files: files.filter((file) => existsSync(file)).map((file) => ({ path: slash(file), sha256: hashFile(file) })),
-  };
-  writeFileSync(output, `${JSON.stringify(body, null, 2)}\n`);
-}
-
-const [change, phase, modeArg, fullFlag] = process.argv.slice(2);
-validateChangeName(change);
-if (phase !== 'design' || modeArg !== '--write' || (fullFlag && fullFlag !== '--full')) error('Usage: comet-handoff.js <change-name> design --write [--full]');
-const handoffMode = fullFlag === '--full' ? 'full' : 'compact';
-const changeDir = join('openspec', 'changes', change);
-const yaml = join(changeDir, '.comet.yaml');
-if (!existsSync(changeDir)) error(`ERROR: change directory not found: ${changeDir}`);
-if (!existsSync(yaml)) error(`ERROR: .comet.yaml not found at ${yaml}`);
-if (fieldValue(yaml, 'phase') !== 'design') error('ERROR: design handoff requires phase: design');
-for (const required of ['proposal.md', 'design.md', 'tasks.md']) {
-  if (!fileNonempty(join(changeDir, required))) error(`ERROR: required OpenSpec artifact missing or empty: ${join(changeDir, required)}`);
->>>>>>> eeac7a023b8ea6033b2606f7fd7d412881e7c398
 }
 const handoffDir = join(changeDir, '.comet', 'handoff');
 const contextJson = slash(join(handoffDir, 'design-context.json'));
@@ -201,7 +108,6 @@ const contextHash = computeContextHash(files);
 writeMarkdown(contextMd, files, change, handoffMode, contextHash);
 writeJson(contextJson, files, change, handoffMode, contextHash);
 const stateScript = join(scriptDir, 'comet-state.js');
-<<<<<<< HEAD
 if (!existsSync(stateScript))
     error('ERROR: comet-state.js not found; cannot record handoff fields');
 let result = runNode(stateScript, ['set', change, 'handoff_context', contextJson]);
@@ -210,13 +116,6 @@ if (result.status !== 0)
 result = runNode(stateScript, ['set', change, 'handoff_hash', contextHash]);
 if (result.status !== 0)
     process.exit(result.status ?? 1);
-=======
-if (!existsSync(stateScript)) error('ERROR: comet-state.js not found; cannot record handoff fields');
-let result = runNode(stateScript, ['set', change, 'handoff_context', contextJson]);
-if (result.status !== 0) process.exit(result.status ?? 1);
-result = runNode(stateScript, ['set', change, 'handoff_hash', contextHash]);
-if (result.status !== 0) process.exit(result.status ?? 1);
->>>>>>> eeac7a023b8ea6033b2606f7fd7d412881e7c398
 green(`[HANDOFF] wrote ${contextJson}`);
 green(`[HANDOFF] wrote ${contextMd}`);
 green(`[HANDOFF] handoff_hash=${contextHash}`);
diff --git a/assets/skills/comet/scripts/comet-lib.js b/assets/skills/comet/scripts/comet-lib.js
index dbe818f0..0da1638f 100644
--- a/assets/skills/comet/scripts/comet-lib.js
+++ b/assets/skills/comet/scripts/comet-lib.js
@@ -4,7 +4,6 @@ import { existsSync, mkdirSync, readFileSync, statSync, writeFileSync } from 'no
 import { dirname, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { spawnSync } from 'node:child_process';
-<<<<<<< HEAD
 export const scriptDir = dirname(fileURLToPath(import.meta.url));
 export const FIELD_ORDER = [
     'workflow',
@@ -207,211 +206,4 @@ export function runCommand(argv, options = {}) {
 }
 export function slash(file) {
     return file.replace(/\\/g, '/');
-=======
-
-export const scriptDir = dirname(fileURLToPath(import.meta.url));
-
-export const FIELD_ORDER = [
-  'workflow',
-  'phase',
-  'build_mode',
-  'build_pause',
-  'isolation',
-  'verify_mode',
-  'base_ref',
-  'design_doc',
-  'plan',
-  'verify_result',
-  'verification_report',
-  'branch_status',
-  'created_at',
-  'verified_at',
-  'archived',
-  'direct_override',
-  'build_command',
-  'verify_command',
-  'handoff_context',
-  'handoff_hash',
-];
-
-export const KNOWN_KEYS = new Set(FIELD_ORDER);
-
-export function color(code, message) {
-  return `\u001b[${code}m${message}\u001b[0m`;
-}
-
-export function red(message) {
-  console.error(color(31, message));
-}
-
-export function green(message) {
-  console.error(color(32, message));
-}
-
-export function yellow(message) {
-  console.error(color(33, message));
-}
-
-export function fail(message, prefix = 'ERROR') {
-  red(`${prefix}: ${message}`);
-  process.exit(1);
-}
-
-export function validateChangeName(name, prefix = 'ERROR') {
-  if (!name) fail('Change name cannot be empty', prefix);
-  if (!/^[a-zA-Z0-9_-]+$/.test(name)) {
-    red(`${prefix}: Invalid change name: '${name}'`);
-    red('Valid characters: a-z, A-Z, 0-9, -, _');
-    process.exit(1);
-  }
-  if (name.includes('..')) fail("Change name cannot contain '..' (path traversal not allowed)", prefix);
-}
-
-export function validateEnum(value, validValues) {
-  if (validValues.includes(value)) return;
-  red(`ERROR: Invalid value: '${value}'`);
-  red(`Valid values: ${validValues.join(' ')}`);
-  process.exit(1);
-}
-
-export function stripInlineComment(value) {
-  let out = '';
-  let quote = '';
-  for (let i = 0; i < value.length; i += 1) {
-    const c = value[i];
-    if (!quote) {
-      if (c === '"' || c === "'") quote = c;
-      else if (c === '#' && (i === 0 || /\s/.test(value[i - 1]))) return out.trimEnd();
-    } else if (c === quote) {
-      quote = '';
-    }
-    out += c;
-  }
-  return out;
-}
-
-export function stripWrappingQuotes(value) {
-  if (value.length >= 2) {
-    const first = value[0];
-    const last = value[value.length - 1];
-    if (first === '"' && last === '"') {
-      try {
-        return JSON.parse(value);
-      } catch {
-        return value.slice(1, -1);
-      }
-    }
-    if (first === "'" && last === "'") return value.slice(1, -1);
-  }
-  return value;
-}
-
-export function parseYamlLines(file) {
-  const text = readFileSync(file, 'utf8');
-  const data = {};
-  const keys = [];
-  for (const line of text.split(/\r?\n/)) {
-    const match = line.match(/^([^\s:#][^:]*):\s*(.*)$/);
-    if (!match) continue;
-    const key = match[1].trim();
-    const value = stripWrappingQuotes(stripInlineComment(match[2] ?? ''));
-    data[key] = value;
-    keys.push(key);
-  }
-  return { data, keys, text };
-}
-
-export function fieldValue(file, field) {
-  if (!existsSync(file)) return '';
-  return parseYamlLines(file).data[field] ?? '';
-}
-
-function formatYamlValue(value) {
-  const stringValue = String(value);
-  if (stringValue === '') return '';
-  if (/^[A-Za-z0-9_./:@\\-]+$/.test(stringValue)) return stringValue;
-  return JSON.stringify(stringValue);
-}
-
-export function writeYamlData(file, data) {
-  const lines = [];
-  for (const key of FIELD_ORDER) {
-    if (Object.prototype.hasOwnProperty.call(data, key)) lines.push(`${key}: ${formatYamlValue(data[key])}`);
-  }
-  for (const key of Object.keys(data)) {
-    if (!FIELD_ORDER.includes(key)) lines.push(`${key}: ${formatYamlValue(data[key])}`);
-  }
-  writeFileSync(file, `${lines.join('\n')}\n`);
-}
-
-export function setYamlField(file, field, value) {
-  const { data } = parseYamlLines(file);
-  data[field] = String(value);
-  writeYamlData(file, data);
-}
-
-export function fileNonempty(file) {
-  try {
-    return statSync(file).isFile() && statSync(file).size > 0;
-  } catch {
-    return false;
-  }
-}
-
-export function changeDirFor(changeName) {
-  const active = join('openspec', 'changes', changeName);
-  const archived = join('openspec', 'changes', 'archive', changeName);
-  if (existsSync(active)) return active;
-  if (existsSync(archived)) return archived;
-  return active;
-}
-
-export function yamlFileFor(changeName) {
-  return join(changeDirFor(changeName), '.comet.yaml');
-}
-
-export function today() {
-  return new Date().toISOString().slice(0, 10);
-}
-
-export function git(args) {
-  return spawnSync('git', args, { encoding: 'utf8' });
-}
-
-export function currentHeadOrNull() {
-  const verify = git(['rev-parse', '--verify', 'HEAD']);
-  if (verify.status !== 0) return 'null';
-  const head = git(['rev-parse', 'HEAD']);
-  return head.status === 0 ? head.stdout.trim() : 'null';
-}
-
-export function sha256(content) {
-  return createHash('sha256').update(content).digest('hex');
-}
-
-export function hashFile(file) {
-  return sha256(readFileSync(file));
-}
-
-export function ensureDir(dir) {
-  mkdirSync(dir, { recursive: true });
-}
-
-export function runNode(script, args, options = {}) {
-  return spawnSync(process.execPath, [script, ...args], { encoding: 'utf8', stdio: 'pipe', ...options });
-}
-
-export function runCommandString(command, options = {}) {
-  console.error(`+ ${command}`);
-  return spawnSync(command, { encoding: 'utf8', stdio: 'inherit', shell: true, ...options });
-}
-
-export function runCommand(argv, options = {}) {
-  const [command, ...args] = argv;
-  return spawnSync(command, args, { encoding: 'utf8', stdio: 'inherit', shell: process.platform === 'win32', ...options });
-}
-
-export function slash(file) {
-  return file.replace(/\\/g, '/');
->>>>>>> eeac7a023b8ea6033b2606f7fd7d412881e7c398
 }
diff --git a/assets/skills/comet/scripts/comet-state.js b/assets/skills/comet/scripts/comet-state.js
index 6d6c289b..8eaab2bd 100644
--- a/assets/skills/comet/scripts/comet-state.js
+++ b/assets/skills/comet/scripts/comet-state.js
@@ -1,7 +1,6 @@
 #!/usr/bin/env node
 import { existsSync, mkdirSync, readdirSync, readFileSync } from 'node:fs';
 import { join } from 'node:path';
-<<<<<<< HEAD
 import { changeDirFor, currentHeadOrNull, fail, fieldValue, fileNonempty, git, green, red, setYamlField, today, validateChangeName, validateEnum, writeYamlData, yamlFileFor, yellow, } from './comet-lib.js';
 const ENUMS = {
     workflow: ['full', 'hotfix', 'tweak'],
@@ -469,386 +468,4 @@ else {
     red(`Unknown subcommand: ${subcommand ?? ''}`);
     console.error('\nUsage: comet-state.js <subcommand> <change-name> [args...]');
     process.exit(1);
-=======
-import {
-  changeDirFor,
-  currentHeadOrNull,
-  fail,
-  fieldValue,
-  fileNonempty,
-  git,
-  green,
-  red,
-  setYamlField,
-  today,
-  validateChangeName,
-  validateEnum,
-  writeYamlData,
-  yamlFileFor,
-  yellow,
-} from './comet-lib.js';
-
-const ENUMS = {
-  workflow: ['full', 'hotfix', 'tweak'],
-  phase: ['open', 'design', 'build', 'verify', 'archive'],
-  build_mode: ['subagent-driven-development', 'executing-plans', 'direct'],
-  build_pause: ['null', 'plan-ready'],
-  isolation: ['branch', 'worktree'],
-  verify_mode: ['light', 'full'],
-  verify_result: ['pending', 'pass', 'fail'],
-  branch_status: ['pending', 'handled'],
-  archived: ['true', 'false'],
-  direct_override: ['true', 'false'],
-};
-
-const SET_FIELDS = new Set([
-  'workflow',
-  'phase',
-  'build_mode',
-  'build_pause',
-  'isolation',
-  'verify_mode',
-  'verify_result',
-  'verification_report',
-  'branch_status',
-  'archived',
-  'design_doc',
-  'plan',
-  'verified_at',
-  'created_at',
-  'direct_override',
-  'build_command',
-  'verify_command',
-  'handoff_context',
-  'handoff_hash',
-  'base_ref',
-]);
-
-function get(change, field) {
-  validateChangeName(change);
-  const yaml = yamlFileFor(change);
-  if (!existsSync(yaml)) fail(`.comet.yaml not found at ${yaml}`);
-  console.log(fieldValue(yaml, field));
-}
-
-function getValue(change, field) {
-  const yaml = yamlFileFor(change);
-  return fieldValue(yaml, field);
-}
-
-function set(change, field, value, quiet = false) {
-  validateChangeName(change);
-  const yaml = yamlFileFor(change);
-  if (!existsSync(yaml)) fail(`.comet.yaml not found at ${yaml}`);
-  if (field === 'phase') {
-    yellow("WARNING: Setting 'phase' directly bypasses state machine constraints.");
-    yellow('  Consider using: comet-state.js transition <change-name> <event>');
-  } else if (!SET_FIELDS.has(field)) {
-    red(`ERROR: Unknown field: '${field}'`);
-    red('Valid fields:');
-    red('  workflow, phase, design_doc, plan, build_mode, build_pause, isolation,');
-    red('  verify_mode, verify_result, verification_report, branch_status,');
-    red('  verified_at, created_at, archived, base_ref, direct_override,');
-    red('  build_command, verify_command, handoff_context, handoff_hash');
-    process.exit(1);
-  }
-  if (ENUMS[field]) validateEnum(value, ENUMS[field]);
-  setYamlField(yaml, field, value);
-  if (!quiet) green(`[SET] ${field}=${value}`);
-}
-
-function init(change, workflow) {
-  validateChangeName(change);
-  validateEnum(workflow, ENUMS.workflow);
-  const changeDir = changeDirFor(change);
-  const yaml = yamlFileFor(change);
-  if (existsSync(yaml)) fail(`.comet.yaml already exists at ${yaml}`);
-  mkdirSync(changeDir, { recursive: true });
-  const preset = workflow === 'full' ? ['null', 'null', 'null'] : ['direct', 'branch', 'light'];
-  writeYamlData(yaml, {
-    workflow,
-    phase: 'open',
-    build_mode: preset[0],
-    build_pause: 'null',
-    isolation: preset[1],
-    verify_mode: preset[2],
-    base_ref: currentHeadOrNull(),
-    design_doc: 'null',
-    plan: 'null',
-    verify_result: 'pending',
-    verification_report: 'null',
-    branch_status: 'pending',
-    created_at: today(),
-    verified_at: 'null',
-    archived: 'false',
-  });
-  green(`Initialized: ${yaml} (workflow=${workflow})`);
-}
-
-function requirePhase(change, expected) {
-  const actual = getValue(change, 'phase');
-  if (actual !== expected) fail(`Cannot transition '${change}': expected phase ${expected}, got ${actual}`);
-}
-
-function requireVerificationEvidence(change) {
-  const report = getValue(change, 'verification_report');
-  const branchStatus = getValue(change, 'branch_status');
-  if (!report || report === 'null' || !existsSync(report)) {
-    fail(`Cannot transition '${change}': verification_report must point to an existing report file`);
-  }
-  if (branchStatus !== 'handled') fail(`Cannot transition '${change}': branch_status must be handled`);
-}
-
-function requireBuildDecisions(change) {
-  const workflow = getValue(change, 'workflow');
-  const buildMode = getValue(change, 'build_mode');
-  const isolation = getValue(change, 'isolation');
-  const directOverride = getValue(change, 'direct_override');
-  if (!['branch', 'worktree'].includes(isolation)) {
-    fail(`Cannot transition '${change}': isolation must be branch or worktree, got '${isolation || 'null'}'`);
-  }
-  if (!ENUMS.build_mode.includes(buildMode)) {
-    fail(`Cannot transition '${change}': build_mode must be selected before leaving build, got '${buildMode || 'null'}'`);
-  }
-  if (buildMode === 'direct' && !['hotfix', 'tweak'].includes(workflow) && directOverride !== 'true') {
-    fail(`Cannot transition '${change}': build_mode=direct is only allowed for hotfix/tweak unless direct_override=true`);
-  }
-}
-
-function transition(change, event) {
-  validateChangeName(change);
-  validateEnum(event, ['open-complete', 'design-complete', 'build-complete', 'verify-pass', 'verify-fail', 'archived']);
-  if (event === 'open-complete') {
-    requirePhase(change, 'open');
-    set(change, 'phase', getValue(change, 'workflow') === 'full' ? 'design' : 'build', true);
-  } else if (event === 'design-complete') {
-    requirePhase(change, 'design');
-    set(change, 'phase', 'build', true);
-  } else if (event === 'build-complete') {
-    requirePhase(change, 'build');
-    requireBuildDecisions(change);
-    set(change, 'phase', 'verify', true);
-    set(change, 'verify_result', 'pending', true);
-    set(change, 'verification_report', 'null', true);
-    set(change, 'branch_status', 'pending', true);
-  } else if (event === 'verify-pass') {
-    requirePhase(change, 'verify');
-    requireVerificationEvidence(change);
-    set(change, 'verify_result', 'pass', true);
-    set(change, 'phase', 'archive', true);
-    set(change, 'verified_at', today(), true);
-  } else if (event === 'verify-fail') {
-    requirePhase(change, 'verify');
-    set(change, 'verify_result', 'fail', true);
-    set(change, 'phase', 'build', true);
-    set(change, 'branch_status', 'pending', true);
-  } else if (event === 'archived') {
-    requirePhase(change, 'archive');
-    set(change, 'archived', 'true', true);
-  }
-  green(`[TRANSITION] ${event}`);
-}
-
-let checkBlock = false;
-function pass(msg) { console.log(`  \u001b[32m[PASS]\u001b[0m ${msg}`); }
-function block(msg) { console.log(`  \u001b[31m[FAIL]\u001b[0m ${msg}`); checkBlock = true; }
-function checkNonempty(desc, file) { fileNonempty(file) ? pass(`${desc} non-empty`) : block(`${desc} missing or empty`); }
-function checkYamlIs(field, expected, change) {
-  const actual = getValue(change, field);
-  actual === expected ? pass(`${field}=${actual} (expected: ${expected})`) : block(`${field}=${actual} (expected: ${expected})`);
-}
-function checkYamlEmpty(field, change) {
-  const value = getValue(change, field);
-  !value || value === 'null' ? pass(`${field} is empty/null`) : block(`${field}=${value} (expected: empty/null)`);
-}
-
-function check(change, phase) {
-  validateChangeName(change);
-  validateEnum(phase, ['open', 'design', 'build', 'verify', 'archive']);
-  checkBlock = false;
-  const changeDir = join('openspec', 'changes', change);
-  const yaml = join(changeDir, '.comet.yaml');
-  console.log(`=== Entry Check: comet-${phase} ===`);
-  if (!existsSync(yaml)) fail(`.comet.yaml not found at ${yaml}`);
-  if (phase === 'open') {
-    pass('.comet.yaml exists');
-    checkYamlIs('phase', 'open', change);
-  } else if (phase === 'design') {
-    pass('.comet.yaml exists');
-    checkYamlIs('phase', 'design', change);
-    checkYamlIs('workflow', 'full', change);
-    checkYamlEmpty('design_doc', change);
-    checkNonempty('proposal.md', join(changeDir, 'proposal.md'));
-    checkNonempty('design.md', join(changeDir, 'design.md'));
-    checkNonempty('tasks.md', join(changeDir, 'tasks.md'));
-  } else if (phase === 'build') {
-    pass('.comet.yaml exists');
-    checkYamlIs('phase', 'build', change);
-    const workflow = getValue(change, 'workflow');
-    if (workflow === 'full') {
-      const designDoc = getValue(change, 'design_doc');
-      designDoc && designDoc !== 'null' && existsSync(designDoc)
-        ? pass(`design_doc=${designDoc} (file exists)`)
-        : block(`design_doc=${designDoc} (expected: non-null and file exists)`);
-    } else {
-      pass(`workflow=${workflow} (design_doc not required)`);
-    }
-    checkNonempty('proposal.md', join(changeDir, 'proposal.md'));
-    checkNonempty('tasks.md', join(changeDir, 'tasks.md'));
-  } else if (phase === 'verify') {
-    pass('.comet.yaml exists');
-    checkYamlIs('phase', 'verify', change);
-    const result = getValue(change, 'verify_result');
-    result === 'pending' || !result || result === 'null'
-      ? pass(`verify_result=${result} (expected: pending or null)`)
-      : block(`verify_result=${result} (expected: pending or null)`);
-  } else if (phase === 'archive') {
-    pass('.comet.yaml exists');
-    checkYamlIs('phase', 'archive', change);
-    checkYamlIs('verify_result', 'pass', change);
-    const archived = getValue(change, 'archived');
-    archived !== 'true' ? pass(`archived=${archived} (expected: not true)`) : block(`archived=${archived} (expected: not true)`);
-  }
-  console.log('');
-  if (checkBlock) {
-    red('BLOCKED — fix failing checks before proceeding');
-    process.exit(1);
-  }
-  green('ALL CHECKS PASSED — ready to proceed');
-}
-
-function fieldStatus(field, value, file = '') {
-  if (!value || value === 'null') console.log(`  - ${field}: PENDING`);
-  else if (file && !existsSync(file)) console.log(`  - ${field}: BROKEN (path ${value} does not exist)`);
-  else console.log(`  - ${field}: DONE (${value})`);
-}
-
-function recover(change) {
-  validateChangeName(change);
-  const changeDir = join('openspec', 'changes', change);
-  const yaml = join(changeDir, '.comet.yaml');
-  if (!existsSync(yaml)) fail(`.comet.yaml not found at ${yaml}`);
-  const phase = getValue(change, 'phase');
-  const workflow = getValue(change, 'workflow');
-  console.log(`=== Recovery Context: ${change} ===`);
-  console.log(`Phase: ${phase}`);
-  console.log(`Workflow: ${workflow}`);
-  console.log('');
-  const values = Object.fromEntries(['design_doc', 'plan', 'verify_result', 'verify_mode', 'verification_report', 'branch_status', 'handoff_context', 'handoff_hash', 'isolation', 'build_mode', 'build_pause', 'direct_override', 'archived'].map((f) => [f, getValue(change, f)]));
-  console.log('State fields:');
-  if (phase === 'open') {
-    console.log('  Artifacts:');
-    for (const f of ['proposal.md', 'design.md', 'tasks.md']) console.log(`  - ${f}: ${fileNonempty(join(changeDir, f)) ? 'DONE' : 'PENDING'}`);
-    console.log('\nRecovery action: Create or complete missing artifacts, then use AskUserQuestion for user confirmation.');
-  } else if (phase === 'design') {
-    console.log('  Artifacts:');
-    for (const f of ['proposal.md', 'design.md', 'tasks.md']) console.log(`  - ${f}: ${fileNonempty(join(changeDir, f)) ? 'DONE' : 'MISSING (unexpected in design phase)'}`);
-    console.log('\n  Design progress:');
-    fieldStatus('handoff_context', values.handoff_context, values.handoff_context);
-    fieldStatus('handoff_hash', values.handoff_hash);
-    fieldStatus('design_doc', values.design_doc, values.design_doc);
-    console.log('');
-    if (values.design_doc && values.design_doc !== 'null' && existsSync(values.design_doc)) console.log('Recovery action: Design Doc already created and linked. Run guard to transition to build.');
-    else if (values.handoff_context && values.handoff_context !== 'null' && existsSync(values.handoff_context)) console.log('Recovery action: Handoff generated but Design Doc not yet created. Resume from brainstorming confirmation (Step 1c).');
-    else console.log('Recovery action: No handoff generated yet. Start from Step 1a (generate handoff package).');
-  } else if (phase === 'build') {
-    console.log('  Build decisions:');
-    fieldStatus('isolation', values.isolation);
-    fieldStatus('build_mode', values.build_mode);
-    fieldStatus('build_pause', values.build_pause);
-    if (values.build_mode === 'direct' && !['hotfix', 'tweak'].includes(workflow)) fieldStatus('direct_override', values.direct_override);
-    console.log('\n  Plan:');
-    fieldStatus('plan', values.plan, values.plan);
-    const tasksFile = join(changeDir, 'tasks.md');
-    let total = 0;
-    let done = 0;
-    if (existsSync(tasksFile)) {
-      const text = readFileSync(tasksFile, 'utf8');
-      total = (text.match(/^- \[/gm) ?? []).length;
-      done = (text.match(/^- \[x\]/gm) ?? []).length;
-      console.log(`\n  Tasks: ${done}/${total} done, ${total - done} pending`);
-    } else console.log('\n  Tasks: tasks.md MISSING');
-    console.log('');
-    if (values.build_pause === 'plan-ready' && values.plan && values.plan !== 'null' && existsSync(values.plan) && (!values.isolation || values.isolation === 'null' || !values.build_mode || values.build_mode === 'null')) console.log('Recovery action: Plan-ready pause detected. Ask the user whether to continue, then choose isolation and build mode without regenerating the plan.');
-    else if (values.build_pause === 'plan-ready' && (!values.plan || values.plan === 'null' || !existsSync(values.plan))) console.log('Recovery action: Plan-ready pause is recorded, but the plan file is missing. Restore the plan file or rerun writing-plans before choosing execution.');
-    else if (values.build_pause === 'plan-ready') console.log('Recovery action: Plan-ready pause is stale because build decisions are already selected. Clear build_pause to null, then continue from the first unchecked task.');
-    else if (!values.isolation || values.isolation === 'null') console.log('Recovery action: Isolation not selected. Use AskUserQuestion to ask user for branch/worktree choice.');
-    else if (!values.build_mode || values.build_mode === 'null') console.log('Recovery action: Build mode not selected. Use AskUserQuestion to ask user for execution method.');
-    else if (!existsSync(tasksFile)) console.log('Recovery action: tasks.md missing. Verify change directory integrity.');
-    else if (total - done > 0) console.log('Recovery action: Read tasks.md and continue from first unchecked task.');
-    else console.log('Recovery action: All tasks done. Run guard to transition to verify.');
-  } else if (phase === 'verify') {
-    console.log('  Verification:');
-    fieldStatus('verify_result', values.verify_result);
-    fieldStatus('verify_mode', values.verify_mode);
-    fieldStatus('verification_report', values.verification_report, values.verification_report);
-    fieldStatus('branch_status', values.branch_status);
-    console.log('');
-    if (values.verify_result === 'pass' && values.branch_status === 'handled') console.log('Recovery action: Verification complete. Run guard to transition to archive.');
-    else if (values.verify_result === 'pass') console.log('Recovery action: Verification passed but branch not yet handled. Complete branch handling and set branch_status to handled.');
-    else if (values.verify_result === 'fail') console.log('Recovery action: Verification failed and rolled back to build. Resume from /comet-build.');
-    else console.log('Recovery action: Verification not yet started or in progress. Run scale assessment then verify.');
-  } else if (phase === 'archive') {
-    console.log('  Archive:');
-    fieldStatus('verify_result', values.verify_result);
-    fieldStatus('archived', values.archived);
-    console.log('\nRecovery action: Run /comet-archive to complete archiving.');
-  }
-  console.log('\n=== End Recovery Context ===');
-}
-
-function countSpecFiles(dir) {
-  if (!existsSync(dir)) return 0;
-  let count = 0;
-  for (const entry of readdirSync(dir, { withFileTypes: true })) {
-    const p = join(dir, entry.name);
-    if (entry.isDirectory()) count += countSpecFiles(p);
-    else if (entry.isFile() && entry.name === 'spec.md') count += 1;
-  }
-  return count;
-}
-
-function scale(change) {
-  validateChangeName(change);
-  const changeDir = join('openspec', 'changes', change);
-  const yaml = join(changeDir, '.comet.yaml');
-  if (!existsSync(yaml)) fail(`.comet.yaml not found at ${yaml}`);
-  const tasksFile = join(changeDir, 'tasks.md');
-  const taskCount = existsSync(tasksFile) ? (readFileSync(tasksFile, 'utf8').match(/^- \[/gm) ?? []).length : 0;
-  const deltaSpecCount = countSpecFiles(join(changeDir, 'specs'));
-  let changedFiles = 0;
-  if (git(['rev-parse', '--git-dir']).status === 0) {
-    let baseRef = '';
-    const plan = getValue(change, 'plan');
-    if (plan && plan !== 'null' && existsSync(plan)) {
-      baseRef = readFileSync(plan, 'utf8').match(/^base-ref:\s*(.*)$/m)?.[1]?.trim() ?? '';
-    }
-    if (!baseRef || baseRef === 'null') baseRef = getValue(change, 'base_ref');
-    const diff = baseRef && baseRef !== 'null' && git(['rev-parse', '--verify', baseRef]).status === 0
-      ? git(['diff', '--name-only', `${baseRef}...HEAD`])
-      : git(['diff', '--name-only', 'HEAD']);
-    changedFiles = diff.status === 0 ? diff.stdout.split(/\r?\n/).filter(Boolean).length : 0;
-  }
-  const result = taskCount > 3 || deltaSpecCount > 1 || changedFiles > 4 ? 'full' : 'light';
-  console.error(`=== Scale Assessment: ${change} ===`);
-  console.error(`  Tasks: ${taskCount} (threshold: 3)`);
-  console.error(`  Delta specs: ${deltaSpecCount} capabilities (threshold: 1)`);
-  console.error(`  Changed files: ${changedFiles} (threshold: 4)`);
-  console.error(`  → Result: ${result}`);
-  setYamlField(yaml, 'verify_mode', result);
-  green(`[SCALE] verify_mode=${result}`);
-}
-
-const [subcommand, ...args] = process.argv.slice(2);
-if (subcommand === 'init' && args.length >= 2) init(args[0], args[1]);
-else if (subcommand === 'get' && args.length >= 2) get(args[0], args[1]);
-else if (subcommand === 'set' && args.length >= 3) set(args[0], args[1], args.slice(2).join(' '));
-else if (subcommand === 'transition' && args.length >= 2) transition(args[0], args[1]);
-else if (subcommand === 'check' && args.length >= 2) args[2] === '--recover' ? recover(args[0]) : check(args[0], args[1]);
-else if (subcommand === 'scale' && args.length >= 1) scale(args[0]);
-else {
-  red(`Unknown subcommand: ${subcommand ?? ''}`);
-  console.error('\nUsage: comet-state.js <subcommand> <change-name> [args...]');
-  process.exit(1);
->>>>>>> eeac7a023b8ea6033b2606f7fd7d412881e7c398
 }
diff --git a/assets/skills/comet/scripts/comet-yaml-validate.js b/assets/skills/comet/scripts/comet-yaml-validate.js
index 34b3a3ed..8d772015 100644
--- a/assets/skills/comet/scripts/comet-yaml-validate.js
+++ b/assets/skills/comet/scripts/comet-yaml-validate.js
@@ -1,19 +1,13 @@
 #!/usr/bin/env node
 import { existsSync } from 'node:fs';
 import { join } from 'node:path';
-<<<<<<< HEAD
 import { changeDirFor, fieldValue, green, KNOWN_KEYS, parseYamlLines, red, validateChangeName, yellow, } from './comet-lib.js';
-=======
-import { changeDirFor, fieldValue, KNOWN_KEYS, parseYamlLines, red, green, validateChangeName, yellow } from './comet-lib.js';
-
->>>>>>> eeac7a023b8ea6033b2606f7fd7d412881e7c398
 const change = process.argv[2];
 validateChangeName(change);
 const changeDir = changeDirFor(change);
 const yaml = join(changeDir, '.comet.yaml');
 let errors = 0;
 let warnings = 0;
-<<<<<<< HEAD
 function fail(message) {
     red(`  FAIL: ${message}`);
     errors += 1;
@@ -88,62 +82,5 @@ console.error('');
 if (errors > 0) {
     red(`${errors} error(s), ${warnings} warning(s) — validation FAILED`);
     process.exit(1);
-=======
-
-function fail(message) {
-  red(`  FAIL: ${message}`);
-  errors += 1;
-}
-
-function warn(message) {
-  yellow(`  WARN: ${message}`);
-  warnings += 1;
-}
-
-function validateEnum(field, value, valid) {
-  if (!value || value === 'null') return;
-  if (!valid.includes(value)) fail(`${field}='${value}' is not valid. Expected: ${valid.join(' ')}`);
-}
-
-console.error(`[VALIDATE] ${yaml}`);
-
-if (!existsSync(yaml)) {
-  fail(`.comet.yaml not found at ${yaml}`);
-} else {
-  const parsed = parseYamlLines(yaml);
-  const required = ['workflow', 'phase', 'design_doc', 'plan', 'build_mode', 'isolation', 'verify_mode', 'verify_result', 'verified_at', 'archived'];
-  for (const field of required) {
-    if (!parsed.keys.includes(field)) fail(`missing required field '${field}'`);
-  }
-
-  validateEnum('workflow', fieldValue(yaml, 'workflow'), ['full', 'hotfix', 'tweak']);
-  validateEnum('phase', fieldValue(yaml, 'phase'), ['open', 'design', 'build', 'verify', 'archive']);
-  validateEnum('build_mode', fieldValue(yaml, 'build_mode'), ['subagent-driven-development', 'executing-plans', 'direct']);
-  validateEnum('build_pause', fieldValue(yaml, 'build_pause'), ['null', 'plan-ready']);
-  validateEnum('isolation', fieldValue(yaml, 'isolation'), ['branch', 'worktree']);
-  validateEnum('verify_mode', fieldValue(yaml, 'verify_mode'), ['light', 'full']);
-  validateEnum('verify_result', fieldValue(yaml, 'verify_result'), ['pending', 'pass', 'fail']);
-  validateEnum('branch_status', fieldValue(yaml, 'branch_status'), ['pending', 'handled']);
-  validateEnum('archived', fieldValue(yaml, 'archived'), ['true', 'false']);
-  validateEnum('direct_override', fieldValue(yaml, 'direct_override'), ['true', 'false']);
-
-  for (const field of ['design_doc', 'plan', 'handoff_context']) {
-    const value = fieldValue(yaml, field);
-    if (value && value !== 'null' && !existsSync(value)) fail(`${field}='${value}' does not exist on disk`);
-  }
-  const handoffHash = fieldValue(yaml, 'handoff_hash');
-  if (handoffHash && handoffHash !== 'null' && !/^[a-f0-9]{64}$/.test(handoffHash)) {
-    fail(`handoff_hash='${handoffHash}' is not a sha256 hex digest`);
-  }
-  for (const key of parsed.keys) {
-    if (!KNOWN_KEYS.has(key)) warn(`unknown field '${key}' found`);
-  }
-}
-
-console.error('');
-if (errors > 0) {
-  red(`${errors} error(s), ${warnings} warning(s) — validation FAILED`);
-  process.exit(1);
->>>>>>> eeac7a023b8ea6033b2606f7fd7d412881e7c398
 }
 green(`0 errors, ${warnings} warning(s) — validation PASSED`);

From 21625ea0fdcf678ec78483c62aced78d0f24fc7d Mon Sep 17 00:00:00 2001
From: zheng <forggy0113@gmail.com>
Date: Sat, 6 Jun 2026 04:03:23 +0800
Subject: [PATCH 5/7] fix: use env vars for os.homedir mocking in tests

---
 test/ts/detect.test.ts   | 20 ++++++++++++--------
 test/ts/init-e2e.test.ts |  8 +++++++-
 2 files changed, 19 insertions(+), 9 deletions(-)

diff --git a/test/ts/detect.test.ts b/test/ts/detect.test.ts
index ef92addd..b3a7efcf 100644
--- a/test/ts/detect.test.ts
+++ b/test/ts/detect.test.ts
@@ -124,8 +124,10 @@ describe('detect', () => {
       expect(opencode).toBeDefined();
       if (!opencode) return;
 
-      const origHomedir = os.homedir;
-      vi.spyOn(os, 'homedir').mockReturnValue(tmpDir);
+      const origHome = process.env.HOME;
+      const origUserProfile = process.env.USERPROFILE;
+      process.env.HOME = tmpDir;
+      process.env.USERPROFILE = tmpDir;
 
       await fs.mkdir(path.join(tmpDir, '.opencode', 'skills', 'comet'), { recursive: true });
       await fs.mkdir(path.join(tmpDir, '.opencode', 'skills', 'comet-open'), { recursive: true });
@@ -133,8 +135,8 @@ describe('detect', () => {
       try {
         expect(await hasSkills(tmpDir, opencode, 'comet')).toBe(false);
       } finally {
-        vi.mocked(os.homedir).mockRestore();
-        os.homedir = origHomedir;
+        process.env.HOME = origHome;
+        process.env.USERPROFILE = origUserProfile;
       }
     });
 
@@ -143,8 +145,10 @@ describe('detect', () => {
       expect(opencode).toBeDefined();
       if (!opencode) return;
 
-      const origHomedir = os.homedir;
-      vi.spyOn(os, 'homedir').mockReturnValue(tmpDir);
+      const origHome = process.env.HOME;
+      const origUserProfile = process.env.USERPROFILE;
+      process.env.HOME = tmpDir;
+      process.env.USERPROFILE = tmpDir;
 
       await fs.mkdir(path.join(tmpDir, '.opencode', 'skills', 'comet'), { recursive: true });
       await fs.mkdir(path.join(tmpDir, '.opencode', 'skills', 'comet-open'), { recursive: true });
@@ -155,8 +159,8 @@ describe('detect', () => {
       try {
         expect(await hasSkills(tmpDir, opencode, 'comet')).toBe(true);
       } finally {
-        vi.mocked(os.homedir).mockRestore();
-        os.homedir = origHomedir;
+        process.env.HOME = origHome;
+        process.env.USERPROFILE = origUserProfile;
       }
     });
 
diff --git a/test/ts/init-e2e.test.ts b/test/ts/init-e2e.test.ts
index ed3382ea..370b673d 100644
--- a/test/ts/init-e2e.test.ts
+++ b/test/ts/init-e2e.test.ts
@@ -175,7 +175,10 @@ describe('comet init E2E', () => {
 
   it('installs all platforms from clean directory with --yes', async () => {
     mockExternalSuccess();
-    vi.spyOn(os, 'homedir').mockReturnValue(tmpDir);
+    const origHome = process.env.HOME;
+    const origUserProfile = process.env.USERPROFILE;
+    process.env.HOME = tmpDir;
+    process.env.USERPROFILE = tmpDir;
 
     const { initCommand } = await import('../../src/commands/init.js');
     const result = await captureJsonOutput(() => initCommand(tmpDir, { yes: true, json: true }));
@@ -223,6 +226,9 @@ describe('comet init E2E', () => {
     await expect(
       fs.access(path.join(tmpDir, '.opencode', 'commands', 'comet-open.md')),
     ).resolves.toBeUndefined();
+
+    process.env.HOME = origHome;
+    process.env.USERPROFILE = origUserProfile;
   }, 20_000);
 
   it('installs Antigravity Comet skills to the Gemini global skills directory', async () => {

From 9340ae1f07166c92a750574ccadeda4b2f0da51e Mon Sep 17 00:00:00 2001
From: zheng <forggy0113@gmail.com>
Date: Sat, 6 Jun 2026 06:39:33 +0800
Subject: [PATCH 6/7] fix: resolve merge conflicts, tighten validation, and fix
 archive/state behavior

---
 CHANGELOG.md                                  |   6 +-
 CLAUDE.md                                     |  15 +-
 assets/skills/comet/scripts/comet-archive.js  |   2 +-
 assets/skills/comet/scripts/comet-state.js    |   2 +-
 .../comet/scripts/comet-yaml-validate.js      |   9 +-
 src/scripts/comet-archive.ts                  |   2 +-
 src/scripts/comet-state.ts                    |   2 +-
 src/scripts/comet-yaml-validate.ts            |   9 +-
 test/ts/comet-scripts.test.ts                 | 172 +++++++++++++++++-
 9 files changed, 183 insertions(+), 36 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 62a110ba..f10375c8 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -6,11 +6,7 @@ All notable changes to @rpamis/comet will be documented in this file.
 
 ### Added
 
-<<<<<<< HEAD
-- **TypeScript Comet scripts**: Converted script source to TypeScript (`src/scripts/`) with strict type annotations; `build.js` compiles them to JavaScript in `assets/skills/comet/scripts/` for distribution.
-=======
-- **Cross-platform Comet Node scripts**: Added Node.js implementations for Comet state, guard, handoff, archive, YAML validation, environment discovery, and shared script utilities so bundled automation runs without Bash-specific script files.
->>>>>>> eeac7a023b8ea6033b2606f7fd7d412881e7c398
+- **Cross-platform Comet scripts**: Converted script source to TypeScript (`src/scripts/`) with strict type annotations; `build.js` compiles them to JavaScript in `assets/skills/comet/scripts/` so bundled automation runs without Bash-specific script files on macOS, Linux, and Windows.
 - **Plan-ready build pause state**: Added `build_pause` as a dedicated build-phase pause marker so Comet can stop after plan generation without confusing the pause with the actual execution method.
 - **Plan-ready pause design**: Added a design record for the model-switching pause workflow, covering recovery behavior, stale pause handling, and plan-missing remediation.
 
diff --git a/CLAUDE.md b/CLAUDE.md
index 4c512366..4d9b9f86 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -7,33 +7,20 @@ npx vitest run                                   # 全量测试
 
 ## Comet Node 脚本规范
 
-<<<<<<< HEAD
 脚本源码位于 `src/scripts/`（TypeScript），经 `build.js` 编译输出到 `assets/skills/comet/scripts/`（JavaScript），必须跨平台兼容（macOS / Linux / Windows）：
 
 - 使用 TypeScript 实现（`src/scripts/*.ts`），构建时编译为 `.js`
-=======
-脚本位于 `assets/skills/comet/scripts/`，必须跨平台兼容（macOS / Linux / Windows）：
-
-- 使用 Node.js 实现，不新增 `.sh` wrapper
->>>>>>> eeac7a023b8ea6033b2606f7fd7d412881e7c398
 - 脚本间调用使用 `node <script>.js` 或共享 `runNode`
 - 用户配置的 `build_command` / `verify_command` 允许交给平台 shell 执行
 - 新增脚本必须加入 `beforeEach` 的拷贝列表和 manifest.json
 
 ## 脚本依赖关系
 
-```
-<<<<<<< HEAD
+```text
 comet-lib.ts ← comet-state.ts, comet-guard.ts, comet-handoff.ts, comet-archive.ts, comet-yaml-validate.ts, comet-env.ts
 comet-state.ts ← comet-guard.ts, comet-handoff.ts, comet-archive.ts
 comet-yaml-validate.ts ← comet-guard.ts (preflight 阶段)
 comet-handoff.ts ← comet-state.ts (写入 handoff_context/handoff_hash)
-=======
-comet-lib.js ← comet-state.js, comet-guard.js, comet-handoff.js, comet-archive.js, comet-yaml-validate.js, comet-env.js
-comet-state.js ← comet-guard.js, comet-handoff.js, comet-archive.js
-comet-yaml-validate.js ← comet-guard.js (preflight 阶段)
-comet-handoff.js ← comet-state.js (写入 handoff_context/handoff_hash)
->>>>>>> eeac7a023b8ea6033b2606f7fd7d412881e7c398
 ```
 
 新增共享工具函数时优先放入 `comet-lib.js`，避免各脚本行为分叉。
diff --git a/assets/skills/comet/scripts/comet-archive.js b/assets/skills/comet/scripts/comet-archive.js
index 86e2182e..6da37dde 100644
--- a/assets/skills/comet/scripts/comet-archive.js
+++ b/assets/skills/comet/scripts/comet-archive.js
@@ -96,7 +96,7 @@ function annotateFrontmatter(file, extraFields) {
         next = out.join('\n');
     }
     else {
-        next = `---\narchived-with: ${archiveName}\n${extraFields ? `${extraFields}\n` : ''}status: final\n---\n${text}`;
+        next = `---\narchived-with: ${archiveName}\n${extraFields ? `${extraFields}\n` : ''}---\n${text}`;
     }
     writeFileSync(file, next);
     stepOk(`Annotated: ${file}`);
diff --git a/assets/skills/comet/scripts/comet-state.js b/assets/skills/comet/scripts/comet-state.js
index 8eaab2bd..05c6a160 100644
--- a/assets/skills/comet/scripts/comet-state.js
+++ b/assets/skills/comet/scripts/comet-state.js
@@ -52,7 +52,7 @@ function set(change, field, value, quiet = false) {
     const yaml = yamlFileFor(change);
     if (!existsSync(yaml))
         fail(`.comet.yaml not found at ${yaml}`);
-    if (field === 'phase') {
+    if (field === 'phase' && !quiet) {
         yellow("WARNING: Setting 'phase' directly bypasses state machine constraints.");
         yellow('  Consider using: comet-state.js transition <change-name> <event>');
     }
diff --git a/assets/skills/comet/scripts/comet-yaml-validate.js b/assets/skills/comet/scripts/comet-yaml-validate.js
index 8d772015..e7757bb9 100644
--- a/assets/skills/comet/scripts/comet-yaml-validate.js
+++ b/assets/skills/comet/scripts/comet-yaml-validate.js
@@ -31,13 +31,18 @@ else {
     const required = [
         'workflow',
         'phase',
-        'design_doc',
-        'plan',
         'build_mode',
+        'build_pause',
         'isolation',
         'verify_mode',
+        'design_doc',
+        'plan',
         'verify_result',
+        'verification_report',
+        'branch_status',
         'verified_at',
+        'created_at',
+        'base_ref',
         'archived',
     ];
     for (const field of required) {
diff --git a/src/scripts/comet-archive.ts b/src/scripts/comet-archive.ts
index 742f90e0..24d28fd8 100644
--- a/src/scripts/comet-archive.ts
+++ b/src/scripts/comet-archive.ts
@@ -109,7 +109,7 @@ function annotateFrontmatter(file: string, extraFields: string): void {
     }
     next = out.join('\n');
   } else {
-    next = `---\narchived-with: ${archiveName}\n${extraFields ? `${extraFields}\n` : ''}status: final\n---\n${text}`;
+    next = `---\narchived-with: ${archiveName}\n${extraFields ? `${extraFields}\n` : ''}---\n${text}`;
   }
   writeFileSync(file, next);
   stepOk(`Annotated: ${file}`);
diff --git a/src/scripts/comet-state.ts b/src/scripts/comet-state.ts
index 2b18ab7f..f0a6c526 100644
--- a/src/scripts/comet-state.ts
+++ b/src/scripts/comet-state.ts
@@ -71,7 +71,7 @@ function set(change: string, field: string, value: string, quiet: boolean = fals
   validateChangeName(change);
   const yaml = yamlFileFor(change);
   if (!existsSync(yaml)) fail(`.comet.yaml not found at ${yaml}`);
-  if (field === 'phase') {
+  if (field === 'phase' && !quiet) {
     yellow("WARNING: Setting 'phase' directly bypasses state machine constraints.");
     yellow('  Consider using: comet-state.js transition <change-name> <event>');
   } else if (!SET_FIELDS.has(field)) {
diff --git a/src/scripts/comet-yaml-validate.ts b/src/scripts/comet-yaml-validate.ts
index 0f6fea73..d42ed289 100644
--- a/src/scripts/comet-yaml-validate.ts
+++ b/src/scripts/comet-yaml-validate.ts
@@ -44,13 +44,18 @@ if (!existsSync(yaml)) {
   const required = [
     'workflow',
     'phase',
-    'design_doc',
-    'plan',
     'build_mode',
+    'build_pause',
     'isolation',
     'verify_mode',
+    'design_doc',
+    'plan',
     'verify_result',
+    'verification_report',
+    'branch_status',
     'verified_at',
+    'created_at',
+    'base_ref',
     'archived',
   ];
   for (const field of required) {
diff --git a/test/ts/comet-scripts.test.ts b/test/ts/comet-scripts.test.ts
index 3ac23ca5..98df9952 100644
--- a/test/ts/comet-scripts.test.ts
+++ b/test/ts/comet-scripts.test.ts
@@ -119,12 +119,16 @@ describe('comet node scripts', () => {
         'phase: build',
         'build_mode: executing-plans',
         'build_pause: null',
+        'verification_report: null',
+        'branch_status: pending',
         'isolation: branch',
         'verify_mode: null',
         'design_doc: null',
         'plan: null',
         'verify_result: pending',
         'verified_at: null',
+        'created_at: 2026-01-01',
+        'base_ref: null',
         'archived: false',
         '',
       ].join('\n'),
@@ -150,12 +154,16 @@ describe('comet node scripts', () => {
         'phase: design',
         'build_mode: null',
         'build_pause: null',
+        'verification_report: null',
+        'branch_status: pending',
         'isolation: null',
         'verify_mode: null',
         'design_doc: null',
         'plan: null',
         'verify_result: pending',
         'verified_at: null',
+        'created_at: 2026-01-01',
+        'base_ref: null',
         'archived: false',
         '',
       ].join('\n'),
@@ -236,12 +244,16 @@ describe('comet node scripts', () => {
         'phase: design # ready for handoff',
         'build_mode: null',
         'build_pause: null',
+        'verification_report: null',
+        'branch_status: pending',
         'isolation: null',
         'verify_mode: null',
         'design_doc: null',
         'plan: null',
         'verify_result: pending # not verified yet',
         'verified_at: null',
+        'created_at: 2026-01-01',
+        'base_ref: null',
         'archived: false # active',
         '',
       ].join('\n'),
@@ -267,12 +279,16 @@ describe('comet node scripts', () => {
         'phase: design',
         'build_mode: null',
         'build_pause: null',
+        'verification_report: null',
+        'branch_status: pending',
         'isolation: null',
         'verify_mode: null',
         'design_doc: null',
         'plan: null',
         'verify_result: pending',
         'verified_at: null',
+        'created_at: 2026-01-01',
+        'base_ref: null',
         'archived: false',
         '',
       ].join('\n'),
@@ -315,12 +331,16 @@ describe('comet node scripts', () => {
         'phase: design',
         'build_mode: null',
         'build_pause: null',
+        'verification_report: null',
+        'branch_status: pending',
         'isolation: null',
         'verify_mode: null',
         'design_doc: null',
         'plan: null',
         'verify_result: pending',
         'verified_at: null',
+        'created_at: 2026-01-01',
+        'base_ref: null',
         'archived: false',
         '',
       ].join('\n'),
@@ -356,12 +376,16 @@ describe('comet node scripts', () => {
         'phase: design',
         'build_mode: null',
         'build_pause: null',
+        'verification_report: null',
+        'branch_status: pending',
         'isolation: null',
         'verify_mode: null',
         'design_doc: null',
         'plan: null',
         'verify_result: pending',
         'verified_at: null',
+        'created_at: 2026-01-01',
+        'base_ref: null',
         'archived: false',
         '',
       ].join('\n'),
@@ -385,12 +409,16 @@ describe('comet node scripts', () => {
         'phase: design',
         'build_mode: null',
         'build_pause: null',
+        'verification_report: null',
+        'branch_status: pending',
         'isolation: null',
         'verify_mode: null',
         'design_doc: null',
         'plan: null',
         'verify_result: pending',
         'verified_at: null',
+        'created_at: 2026-01-01',
+        'base_ref: null',
         'archived: false',
         '',
       ].join('\n'),
@@ -421,12 +449,16 @@ describe('comet node scripts', () => {
         'phase: design',
         'build_mode: null',
         'build_pause: null',
+        'verification_report: null',
+        'branch_status: pending',
         'isolation: null',
         'verify_mode: null',
         'design_doc: null',
         'plan: null',
         'verify_result: pending',
         'verified_at: null',
+        'created_at: 2026-01-01',
+        'base_ref: null',
         'archived: false',
         '',
       ].join('\n'),
@@ -468,12 +500,16 @@ describe('comet node scripts', () => {
         'phase: build',
         'build_mode: null',
         'build_pause: null',
+        'verification_report: null',
+        'branch_status: pending',
         'isolation: null',
         'verify_mode: null',
         'design_doc: null',
         'plan: null',
         'verify_result: pending',
         'verified_at: null',
+        'created_at: 2026-01-01',
+        'base_ref: null',
         'archived: false',
         '',
       ].join('\n'),
@@ -508,12 +544,16 @@ describe('comet node scripts', () => {
         'phase: build',
         'build_mode: null',
         'build_pause: null',
+        'verification_report: null',
+        'branch_status: pending',
         'isolation: null',
         'verify_mode: null',
         'design_doc: null',
         'plan: null',
         'verify_result: pending',
         'verified_at: null',
+        'created_at: 2026-01-01',
+        'base_ref: null',
         'archived: false',
         '',
       ].join('\n'),
@@ -550,6 +590,8 @@ describe('comet node scripts', () => {
         'plan: null',
         'verify_result: pending',
         'verified_at: null',
+        'created_at: 2026-01-01',
+        'base_ref: null',
         'archived: false',
         '',
       ].join('\n'),
@@ -571,12 +613,16 @@ describe('comet node scripts', () => {
         'phase: build',
         'build_mode: direct',
         'build_pause: null',
+        'verification_report: null',
+        'branch_status: pending',
         'isolation: branch',
         'verify_mode: null',
         'design_doc: null',
         'plan: null',
         'verify_result: pending',
         'verified_at: null',
+        'created_at: 2026-01-01',
+        'base_ref: null',
         'archived: false',
         '',
       ].join('\n'),
@@ -603,12 +649,16 @@ describe('comet node scripts', () => {
         'phase: build',
         'build_mode: executing-plans',
         'build_pause: null',
+        'verification_report: null',
+        'branch_status: pending',
         'isolation: branch',
         'verify_mode: null',
         'design_doc: null',
         'plan: null',
         'verify_result: pending',
         'verified_at: null',
+        'created_at: 2026-01-01',
+        'base_ref: null',
         'archived: false',
         '',
       ].join('\n'),
@@ -637,12 +687,16 @@ describe('comet node scripts', () => {
         'phase: build',
         'build_mode: direct',
         'build_pause: null',
+        'verification_report: null',
+        'branch_status: pending',
         'isolation: branch',
         'verify_mode: null',
         'design_doc: null',
         'plan: null',
         'verify_result: pending',
         'verified_at: null',
+        'created_at: 2026-01-01',
+        'base_ref: null',
         'archived: false',
         '',
       ].join('\n'),
@@ -667,6 +721,8 @@ describe('comet node scripts', () => {
         'phase: build',
         'build_mode: direct',
         'build_pause: null',
+        'verification_report: null',
+        'branch_status: pending',
         'direct_override: true',
         'isolation: branch',
         'verify_mode: null',
@@ -674,6 +730,8 @@ describe('comet node scripts', () => {
         'plan: null',
         'verify_result: pending',
         'verified_at: null',
+        'created_at: 2026-01-01',
+        'base_ref: null',
         'archived: false',
         '',
       ].join('\n'),
@@ -698,6 +756,8 @@ describe('comet node scripts', () => {
         'phase: build',
         'build_mode: executing-plans',
         'build_pause: null',
+        'verification_report: null',
+        'branch_status: pending',
         'isolation: branch',
         'verify_mode: null',
         'build_command: node build-check.js',
@@ -705,6 +765,8 @@ describe('comet node scripts', () => {
         'plan: null',
         'verify_result: pending',
         'verified_at: null',
+        'created_at: 2026-01-01',
+        'base_ref: null',
         'archived: false',
         '',
       ].join('\n'),
@@ -734,12 +796,16 @@ describe('comet node scripts', () => {
         'phase: build',
         'build_mode: executing-plans',
         'build_pause: null',
+        'verification_report: null',
+        'branch_status: pending',
         'isolation: branch',
         'verify_mode: null',
         'design_doc: null',
         'plan: null',
         'verify_result: pending',
         'verified_at: null',
+        'created_at: 2026-01-01',
+        'base_ref: null',
         'archived: false',
         '',
       ].join('\n'),
@@ -781,12 +847,16 @@ describe('comet node scripts', () => {
         'phase: open',
         'build_mode: null',
         'build_pause: null',
+        'verification_report: null',
+        'branch_status: pending',
         'isolation: null',
         'verify_mode: null',
         'design_doc: null',
         'plan: null',
         'verify_result: pending',
         'verified_at: null',
+        'created_at: 2026-01-01',
+        'base_ref: null',
         'archived: false',
         '',
       ].join('\n'),
@@ -816,12 +886,16 @@ describe('comet node scripts', () => {
         'phase: build',
         'build_mode: executing-plans',
         'build_pause: null',
+        'verification_report: null',
+        'branch_status: pending',
         'isolation: branch',
         'verify_mode: null',
         'design_doc: null',
         'plan: null',
         'verify_result: pending',
         'verified_at: null',
+        'created_at: 2026-01-01',
+        'base_ref: null',
         'archived: false',
         '',
       ].join('\n'),
@@ -851,6 +925,8 @@ describe('comet node scripts', () => {
         'phase: verify',
         'build_mode: executing-plans',
         'build_pause: null',
+        'verification_report: null',
+        'branch_status: pending',
         'isolation: branch',
         'verify_mode: full',
         'verify_command: node verify-check.js',
@@ -860,6 +936,8 @@ describe('comet node scripts', () => {
         'verification_report: docs/superpowers/reports/configured-verify.md',
         'branch_status: handled',
         'verified_at: null',
+        'created_at: 2026-01-01',
+        'base_ref: null',
         'archived: false',
         '',
       ].join('\n'),
@@ -892,12 +970,16 @@ describe('comet node scripts', () => {
         'phase: archive',
         'build_mode: executing-plans',
         'build_pause: null',
+        'verification_report: null',
+        'branch_status: pending',
         'isolation: branch',
         'verify_mode: light',
         'design_doc: null',
         'plan: null',
         'verify_result: pass',
         'verified_at: 2026-05-21',
+        'created_at: 2026-01-01',
+        'base_ref: null',
         'archived: true',
         '',
       ].join('\n'),
@@ -919,6 +1001,8 @@ describe('comet node scripts', () => {
         'phase: archive',
         'build_mode: executing-plans',
         'build_pause: null',
+        'verification_report: null',
+        'branch_status: pending',
         'isolation: branch',
         'verify_mode: full',
         'design_doc: docs/superpowers/specs/ready-design.md',
@@ -927,6 +1011,8 @@ describe('comet node scripts', () => {
         'verification_report: docs/superpowers/reports/ready.md',
         'branch_status: handled',
         'verified_at: 2026-05-21',
+        'created_at: 2026-01-01',
+        'base_ref: null',
         'archived: false',
         '',
       ].join('\n'),
@@ -976,12 +1062,16 @@ describe('comet node scripts', () => {
         'phase: verify',
         'build_mode: executing-plans',
         'build_pause: null',
+        'verification_report: null',
+        'branch_status: pending',
         'isolation: branch',
         'verify_mode: null',
         'design_doc: null',
         'plan: docs/superpowers/plans/large-change.md',
         'verify_result: pending',
         'verified_at: null',
+        'created_at: 2026-01-01',
+        'base_ref: null',
         'archived: false',
         '',
       ].join('\n'),
@@ -1013,12 +1103,16 @@ describe('comet node scripts', () => {
         'phase: open',
         'build_mode: null',
         'build_pause: null',
+        'verification_report: null',
+        'branch_status: pending',
         'isolation: null',
         'verify_mode: null',
         'design_doc: null',
         'plan: null',
         'verify_result: pending',
         'verified_at: null',
+        'created_at: 2026-01-01',
+        'base_ref: null',
         'archived: false',
         '',
       ].join('\n'),
@@ -1040,12 +1134,16 @@ describe('comet node scripts', () => {
         'phase: open',
         'build_mode: direct',
         'build_pause: null',
+        'verification_report: null',
+        'branch_status: pending',
         'isolation: branch',
         'verify_mode: light',
         'design_doc: null',
         'plan: null',
         'verify_result: pending',
         'verified_at: null',
+        'created_at: 2026-01-01',
+        'base_ref: null',
         'archived: false',
         '',
       ].join('\n'),
@@ -1067,6 +1165,8 @@ describe('comet node scripts', () => {
         'phase: verify',
         'build_mode: executing-plans',
         'build_pause: null',
+        'verification_report: null',
+        'branch_status: pending',
         'isolation: branch',
         'verify_mode: full',
         'design_doc: null',
@@ -1075,6 +1175,8 @@ describe('comet node scripts', () => {
         'verification_report: null',
         'branch_status: pending',
         'verified_at: null',
+        'created_at: 2026-01-01',
+        'base_ref: null',
         'archived: false',
         '',
       ].join('\n'),
@@ -1128,6 +1230,8 @@ describe('comet node scripts', () => {
         'phase: verify',
         'build_mode: executing-plans',
         'build_pause: null',
+        'verification_report: null',
+        'branch_status: pending',
         'isolation: branch',
         'verify_mode: light',
         'design_doc: null',
@@ -1136,6 +1240,8 @@ describe('comet node scripts', () => {
         'verification_report: null',
         'branch_status: pending',
         'verified_at: null',
+        'created_at: 2026-01-01',
+        'base_ref: null',
         'archived: false',
         '',
       ].join('\n'),
@@ -1163,6 +1269,8 @@ describe('comet node scripts', () => {
         'phase: verify',
         'build_mode: executing-plans',
         'build_pause: null',
+        'verification_report: null',
+        'branch_status: pending',
         'isolation: branch',
         'verify_mode: light',
         'design_doc: null',
@@ -1171,6 +1279,8 @@ describe('comet node scripts', () => {
         'verification_report: docs/superpowers/reports/guard-verify.md',
         'branch_status: handled',
         'verified_at: null',
+        'created_at: 2026-01-01',
+        'base_ref: null',
         'archived: false',
         '',
       ].join('\n'),
@@ -1202,12 +1312,16 @@ describe('comet node scripts', () => {
         'phase: open',
         'build_mode: null',
         'build_pause: null',
+        'verification_report: null',
+        'branch_status: pending',
         'isolation: null',
         'verify_mode: null',
         'design_doc: null',
         'plan: null',
         'verify_result: pending',
         'verified_at: null',
+        'created_at: 2026-01-01',
+        'base_ref: null',
         'archived: false',
         '',
       ].join('\n'),
@@ -1228,12 +1342,16 @@ describe('comet node scripts', () => {
         'phase: archive',
         'build_mode: executing-plans',
         'build_pause: null',
+        'verification_report: null',
+        'branch_status: pending',
         'isolation: branch',
         'verify_mode: full',
         'design_doc: null',
         'plan: null',
         'verify_result: pass',
         'verified_at: 2026-05-21',
+        'created_at: 2026-01-01',
+        'base_ref: null',
         'archived: false',
         '',
       ].join('\n'),
@@ -1260,12 +1378,16 @@ describe('comet node scripts', () => {
           'phase: open',
           'build_mode: null',
           'build_pause: null',
+        'verification_report: null',
+        'branch_status: pending',
           'isolation: null',
           'verify_mode: null',
           'design_doc: null',
           'plan: null',
           'verify_result: pending',
-          'archived: false',
+          'created_at: 2026-01-01',
+        'base_ref: null',
+        'archived: false',
           '',
         ].join('\n'),
       );
@@ -1291,12 +1413,16 @@ describe('comet node scripts', () => {
           'phase: build',
           'build_mode: null',
           'build_pause: null',
+        'verification_report: null',
+        'branch_status: pending',
           'isolation: null',
           'verify_mode: null',
           'design_doc: null',
           'plan: null',
           'verify_result: pending',
-          'archived: false',
+          'created_at: 2026-01-01',
+        'base_ref: null',
+        'archived: false',
           '',
         ].join('\n'),
         ['- [x] done task', '- [ ] pending task'].join('\n'),
@@ -1325,12 +1451,16 @@ describe('comet node scripts', () => {
           'phase: build',
           'build_mode: null',
           'build_pause: plan-ready',
+          'verification_report: null',
+          'branch_status: pending',
           'isolation: null',
           'verify_mode: null',
           'design_doc: null',
           'plan: docs/superpowers/plans/pause-plan.md',
           'verify_result: pending',
-          'archived: false',
+          'created_at: 2026-01-01',
+        'base_ref: null',
+        'archived: false',
           '',
         ].join('\n'),
       );
@@ -1361,6 +1491,8 @@ describe('comet node scripts', () => {
           'phase: verify',
           'build_mode: executing-plans',
           'build_pause: null',
+        'verification_report: null',
+        'branch_status: pending',
           'isolation: branch',
           'verify_mode: full',
           'design_doc: null',
@@ -1369,7 +1501,9 @@ describe('comet node scripts', () => {
           'verification_report: docs/superpowers/reports/recover-verify.md',
           'branch_status: handled',
           'verified_at: null',
-          'archived: false',
+          'created_at: 2026-01-01',
+        'base_ref: null',
+        'archived: false',
           '',
         ].join('\n'),
       );
@@ -1397,6 +1531,8 @@ describe('comet node scripts', () => {
           'phase: design',
           'build_mode: null',
           'build_pause: null',
+        'verification_report: null',
+        'branch_status: pending',
           'isolation: null',
           'verify_mode: null',
           'design_doc: null',
@@ -1404,7 +1540,9 @@ describe('comet node scripts', () => {
           'verify_result: pending',
           'handoff_context: openspec/changes/recover-design/.comet/handoff/design-context.json',
           'handoff_hash: abc123def456',
-          'archived: false',
+          'created_at: 2026-01-01',
+        'base_ref: null',
+        'archived: false',
           '',
         ].join('\n'),
       );
@@ -1445,12 +1583,16 @@ describe('comet node scripts', () => {
           'phase: build',
           'build_mode: executing-plans',
           'build_pause: null',
+        'verification_report: null',
+        'branch_status: pending',
           'isolation: branch',
           'verify_mode: null',
           'design_doc: null',
           'plan: null',
           'verify_result: pending',
-          'archived: false',
+          'created_at: 2026-01-01',
+        'base_ref: null',
+        'archived: false',
           '',
         ].join('\n'),
       );
@@ -1478,12 +1620,16 @@ describe('comet node scripts', () => {
           'phase: build',
           'build_mode: executing-plans',
           'build_pause: null',
+        'verification_report: null',
+        'branch_status: pending',
           'isolation: branch',
           'verify_mode: null',
           'design_doc: null',
           'plan: null',
           'verify_result: pending',
-          'archived: false',
+          'created_at: 2026-01-01',
+        'base_ref: null',
+        'archived: false',
           '',
         ].join('\n'),
         ['- [x] task 1', '- [x] task 2'].join('\n'),
@@ -1512,6 +1658,8 @@ describe('comet node scripts', () => {
           'phase: archive',
           'build_mode: executing-plans',
           'build_pause: null',
+        'verification_report: null',
+        'branch_status: pending',
           'isolation: branch',
           'verify_mode: full',
           'design_doc: null',
@@ -1519,7 +1667,9 @@ describe('comet node scripts', () => {
           'verify_result: pass',
           'branch_status: handled',
           'verified_at: 2026-05-29',
-          'archived: false',
+          'created_at: 2026-01-01',
+        'base_ref: null',
+        'archived: false',
           '',
         ].join('\n'),
       );
@@ -1548,12 +1698,16 @@ describe('comet node scripts', () => {
           'phase: open',
           'build_mode: null',
           'build_pause: null',
+        'verification_report: null',
+        'branch_status: pending',
           'isolation: null',
           'verify_mode: null',
           'design_doc: null',
           'plan: null',
           'verify_result: pending',
-          'archived: false',
+          'created_at: 2026-01-01',
+        'base_ref: null',
+        'archived: false',
           '',
         ].join('\n'),
       );

From d99c21cd813ae266a175bde0dcedb410142d1c3d Mon Sep 17 00:00:00 2001
From: zheng <forggy0113@gmail.com>
Date: Sat, 6 Jun 2026 06:51:38 +0800
Subject: [PATCH 7/7] fix: restore test environment safely

---
 test/ts/detect.test.ts   |  12 +++--
 test/ts/init-e2e.test.ts | 102 +++++++++++++++++++--------------------
 2 files changed, 58 insertions(+), 56 deletions(-)

diff --git a/test/ts/detect.test.ts b/test/ts/detect.test.ts
index b3a7efcf..0d4cb78b 100644
--- a/test/ts/detect.test.ts
+++ b/test/ts/detect.test.ts
@@ -135,8 +135,10 @@ describe('detect', () => {
       try {
         expect(await hasSkills(tmpDir, opencode, 'comet')).toBe(false);
       } finally {
-        process.env.HOME = origHome;
-        process.env.USERPROFILE = origUserProfile;
+        if (origHome === undefined) delete process.env.HOME;
+        else process.env.HOME = origHome;
+        if (origUserProfile === undefined) delete process.env.USERPROFILE;
+        else process.env.USERPROFILE = origUserProfile;
       }
     });
 
@@ -159,8 +161,10 @@ describe('detect', () => {
       try {
         expect(await hasSkills(tmpDir, opencode, 'comet')).toBe(true);
       } finally {
-        process.env.HOME = origHome;
-        process.env.USERPROFILE = origUserProfile;
+        if (origHome === undefined) delete process.env.HOME;
+        else process.env.HOME = origHome;
+        if (origUserProfile === undefined) delete process.env.USERPROFILE;
+        else process.env.USERPROFILE = origUserProfile;
       }
     });
 
diff --git a/test/ts/init-e2e.test.ts b/test/ts/init-e2e.test.ts
index 370b673d..a3ff4605 100644
--- a/test/ts/init-e2e.test.ts
+++ b/test/ts/init-e2e.test.ts
@@ -175,60 +175,58 @@ describe('comet init E2E', () => {
 
   it('installs all platforms from clean directory with --yes', async () => {
     mockExternalSuccess();
-    const origHome = process.env.HOME;
-    const origUserProfile = process.env.USERPROFILE;
-    process.env.HOME = tmpDir;
-    process.env.USERPROFILE = tmpDir;
-
-    const { initCommand } = await import('../../src/commands/init.js');
-    const result = await captureJsonOutput(() => initCommand(tmpDir, { yes: true, json: true }));
-
-    expect((result.results as unknown[]).length).toBeGreaterThanOrEqual(28);
-
-    const manifest = await readManifest();
-    const platformDirs = [
-      '.claude',
-      '.cursor',
-      '.codex',
-      '.opencode',
-      '.windsurf',
-      '.cline',
-      '.roo',
-      '.continue',
-      '.gemini',
-      '.amazonq',
-      '.qwen',
-      '.kilocode',
-      '.augment',
-      '.kiro',
-      '.lingma',
-      '.junie',
-      '.codebuddy',
-      '.cospec',
-      '.crush',
-      '.factory',
-      '.iflow',
-      '.pi',
-      '.qoder',
-      '.agents',
-      '.bob',
-      '.forge',
-      '.trae',
-      '.github',
-    ];
-    for (const platform of platformDirs) {
-      for (const skillPath of manifest.skills) {
-        const dest = path.join(tmpDir, platform, 'skills', skillPath);
-        await expect(fs.access(dest)).resolves.toBeUndefined();
+    const homedirSpy = vi.spyOn(os, 'homedir').mockReturnValue(tmpDir);
+
+    try {
+      const { initCommand } = await import('../../src/commands/init.js');
+      const result = await captureJsonOutput(() => initCommand(tmpDir, { yes: true, json: true }));
+
+      expect((result.results as unknown[]).length).toBeGreaterThanOrEqual(28);
+
+      const manifest = await readManifest();
+      const platformDirs = [
+        '.claude',
+        '.cursor',
+        '.codex',
+        '.opencode',
+        '.windsurf',
+        '.cline',
+        '.roo',
+        '.continue',
+        '.gemini',
+        '.amazonq',
+        '.qwen',
+        '.kilocode',
+        '.augment',
+        '.kiro',
+        '.lingma',
+        '.junie',
+        '.codebuddy',
+        '.cospec',
+        '.crush',
+        '.factory',
+        '.iflow',
+        '.pi',
+        '.qoder',
+        '.agents',
+        '.bob',
+        '.forge',
+        '.trae',
+        '.github',
+      ];
+      for (const platform of platformDirs) {
+        for (const skillPath of manifest.skills) {
+          const dest = path.join(tmpDir, platform, 'skills', skillPath);
+          await expect(fs.access(dest)).resolves.toBeUndefined();
+        }
       }
-    }
 
-    await expect(
-      fs.access(path.join(tmpDir, '.opencode', 'commands', 'comet-open.md')),
-    ).resolves.toBeUndefined();
-
-    process.env.HOME = origHome;
-    process.env.USERPROFILE = origUserProfile;
+      await expect(
+        fs.access(path.join(tmpDir, '.opencode', 'commands', 'comet-open.md')),
+      ).resolves.toBeUndefined();
+    } finally {
+      homedirSpy.mockRestore();
+    }
   }, 20_000);
 
   it('installs Antigravity Comet skills to the Gemini global skills directory', async () => {