@rpamis/comet 0.2.4 → 0.2.6

package/assets/skills/comet/scripts/comet-yaml-validate.sh

@@ -1,138 +1,157 @@
-#!/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() {
-  grep "^${1}:" "$YAML" 2>/dev/null | sed "s/^${1}: *//" | tr -d '"' | tr -d "'" || true
-}
-
-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")
-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")
-design_doc=$(field_value "design_doc")
-plan=$(field_value "plan")
-
-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 "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"
-
-# --- 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
-
-# --- Unknown keys check ---
-KNOWN_KEYS="workflow phase design_doc plan build_mode isolation verify_mode verify_result verification_report branch_status verified_at archived"
-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
+#!/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)
+  strip_wrapping_quotes "$value"
+}
+
+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")
+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")
+
+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 "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
+
+# --- Unknown keys check ---
+KNOWN_KEYS="workflow phase design_doc plan build_mode isolation verify_mode verify_result verification_report branch_status verified_at archived direct_override build_command verify_command"
+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

package/assets/skills/comet-archive/SKILL.md

@@ -43,6 +43,9 @@ The script automatically executes:
 
 If script returns non-zero exit code, report error and stop.
 If script returns zero exit code, archive is complete.
+The summary `X/Y steps succeeded` counts real executed steps and does not double-count delta spec sync or document annotation.
+
+When a delta spec differs from an existing main spec, the script prints a unified diff before overwrite so the archive sync content is visible.
 
 Use `--dry-run` flag to preview without executing.
 

package/assets/skills/comet-build/SKILL.md

@@ -80,6 +80,11 @@ bash "$COMET_STATE" set <name> isolation <value>
 - `branch`
 - `worktree`
 
+<IMPORTANT>
+This is a script-enforced hard constraint, not a suggestion. Full workflow init may temporarily leave `isolation` as `null`, but only before this step.
+Before implementation starts, stop and ask the user, then write either `branch` or `worktree`. If it remains `null`, both the `build → verify` guard and `comet-state transition build-complete` will fail.
+</IMPORTANT>
+
 **Execute isolation**:
 
 - **branch**: Run `git checkout -b <change-name>`, subsequent work on the new branch
@@ -109,7 +114,16 @@ bash "$COMET_STATE" set <name> build_mode <value>
 
 - `subagent-driven-development`
 - `executing-plans`
-- `direct` (only for hotfix preset use)
+- `direct` (default only for hotfix/tweak preset use)
+
+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
+bash "$COMET_STATE" set <name> direct_override true
+bash "$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.
 
 Then, **immediately execute:** Use the Skill tool to load the corresponding skill. Skipping this step is prohibited.
 
@@ -151,8 +165,20 @@ Build is the longest phase and may span many tasks. To support resume after cont
 - All tasks.md checked
 - Code committed
 - 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 `bash "$COMET_GUARD" <change-name> build --apply`; after all PASS, state advances to `phase: verify`
 
+Guard reads project command configuration first:
+
+```yaml
+build_command: <build command>
+verify_command: <verify command>
+```
+
+Configuration can live in the change `.comet.yaml`, or in repo-root `.comet.yaml` / `comet.yaml` / `.comet.yml` / `comet.yml`.
+Only when no command is configured does guard fall back to `npm run build`, Maven, or Cargo auto-detection. When a command fails, guard prints the command output as evidence for debugging.
+
 Before exit, run guard to auto-transition:
 
 ```bash

package/assets/skills-zh/comet/SKILL.md

@@ -171,7 +171,7 @@ archived: false
 | `design_doc` | 关联的 Superpowers Design Doc 路径，可为空 |
 | `plan` | 关联的 Superpowers Plan 路径，可为空 |
 | `build_mode` | 已选择的执行方式，可为空 |
-| `isolation` | `branch` 或 `worktree`，工作区隔离方式，默认 `branch` |
+| `isolation` | `branch` 或 `worktree`，工作区隔离方式。full 初始化可为 `null`，但只允许持续到 `/comet-build` Step 3 前；hotfix/tweak 默认 `branch` |
 | `verify_mode` | `light` 或 `full`，可为空 |
 | `verify_result` | `pending`、`pass` 或 `fail` |
 | `verification_report` | 验证报告文件路径，verify 通过前必须指向已存在文件 |
@@ -179,6 +179,20 @@ archived: false
 | `verified_at` | 验证通过时间，可为空 |
 | `archived` | change 是否已归档 |
 
+可选字段：
+
+| 字段 | 含义 |
+|------|------|
+| `direct_override` | `true`/`false`。full workflow 如需使用 `build_mode: direct`，必须显式设为 `true` |
+| `build_command` | 项目构建命令。guard 优先运行该命令，失败时打印命令输出 |
+| `verify_command` | 项目验证命令。verify guard 优先运行该命令，未配置时回退到构建命令 |
+
+状态机硬约束：
+- `build → verify` 前，`isolation` 必须是 `branch` 或 `worktree`
+- `build → verify` 前，`build_mode` 必须已选择
+- `build_mode: direct` 默认只允许 `hotfix` / `tweak`；full workflow 需要 `direct_override: true`
+- 这些约束同时存在于 `comet-guard.sh build --apply` 和 `comet-state.sh transition <name> build-complete`
+
 ### 脚本定位
 
 Comet 脚本随 skill 包分发在 `comet/scripts/` 下。**不硬编码路径** — 定位一次，缓存到环境变量：

package/assets/skills-zh/comet-archive/SKILL.md

@@ -43,6 +43,9 @@ bash "$COMET_ARCHIVE" "<change-name>"
 
 如脚本返回非零退出码，报告错误并停止。
 如脚本返回零退出码，归档完成。
+脚本摘要中的 `X/Y steps succeeded` 以真实执行步骤计数，不会因 delta spec 同步或文档标注重复累计。
+
+当待同步的 delta spec 与已有主 spec 不一致时，脚本会在覆盖前打印 unified diff 预览，帮助确认归档同步内容。
 
 如需预览而不实际执行，使用 `--dry-run` 参数。
 

package/assets/skills-zh/comet-build/SKILL.md

@@ -80,6 +80,11 @@ bash "$COMET_STATE" set <name> isolation <value>
 - `branch`
 - `worktree`
 
+<IMPORTANT>
+这是脚本级硬约束，不是建议。full workflow 初始化时 `isolation` 可以暂时为 `null`，但只允许存在到本步骤之前。
+进入实现前必须停下来询问用户并写入 `branch` 或 `worktree`。若保持 `null`，`build → verify` 的 guard 和 `comet-state transition build-complete` 都会失败。
+</IMPORTANT>
+
 **执行隔离**：
 
 - **branch**：执行 `git checkout -b <change-name>`，后续工作在新分支上进行
@@ -109,7 +114,16 @@ bash "$COMET_STATE" set <name> build_mode <value>
 
 - `subagent-driven-development`
 - `executing-plans`
-- `direct`（仅 hotfix preset 使用）
+- `direct`（默认仅 hotfix/tweak preset 使用）
+
+full workflow 不得默认使用 `direct`。只有用户明确要求跳过计划执行技能，且你已记录显式 override 时，才允许：
+
+```bash
+bash "$COMET_STATE" set <name> direct_override true
+bash "$COMET_STATE" set <name> build_mode direct
+```
+
+没有 `direct_override: true` 时，full workflow 的 `build_mode=direct` 会被 guard 和状态转换同时拦截。
 
 然后，**立即执行：** 使用 Skill 工具加载对应技能。禁止跳过此步骤。
 
@@ -151,8 +165,20 @@ Build 是最长阶段，可能跨越大量任务。为支持上下文压缩后
 - tasks.md 全部勾选
 - 代码已提交
 - 已显式运行项目对应的构建/测试命令并通过（不要只依赖 guard 自动猜测）
+- `isolation` 已写为 `branch` 或 `worktree`
+- `build_mode` 已写为 `subagent-driven-development`、`executing-plans` 或带显式 override 的 `direct`
 - **阶段守卫**：运行 `bash "$COMET_GUARD" <change-name> build --apply`，全部 PASS 后自动流转到 `phase: verify`
 
+Guard 会优先读取项目配置中的命令：
+
+```yaml
+build_command: <build command>
+verify_command: <verify command>
+```
+
+配置位置可为 change 的 `.comet.yaml`，也可为仓库根目录的 `.comet.yaml` / `comet.yaml` / `.comet.yml` / `comet.yml`。
+未配置时才回退到 `npm run build`、Maven 或 Cargo 的默认探测。构建失败时 guard 会打印失败命令输出，作为排查证据。
+
 退出前运行 guard 自动流转：
 
 ```bash

package/bin/comet.js

@@ -1,3 +1,3 @@
-#!/usr/bin/env node
-
-import '../dist/cli/index.js';
+#!/usr/bin/env node
+
+import '../dist/cli/index.js';

package/dist/cli/index.js

@@ -1,4 +1,4 @@
-import { Command } from 'commander';
+import { Command, Option } from 'commander';
 import { createRequire } from 'module';
 import { initCommand } from '../commands/init.js';
 import { statusCommand } from '../commands/status.js';
@@ -41,6 +41,11 @@ program
     .command('doctor [path]')
     .description('Diagnose Comet installation health')
     .option('--json', 'Output as JSON')
+    .addOption(new Option('--scope <scope>', 'Install scope to diagnose').choices([
+    'auto',
+    'global',
+    'project',
+]))
     .action(async (targetPath = '.', options) => {
     await doctorCommand(targetPath, options);
 });
@@ -48,8 +53,9 @@ program
     .command('update [path]')
     .description('Update comet skill files to latest version')
     .option('--json', 'Output as JSON')
-    .option('--language <lang>', 'Language for skills (en, zh)')
-    .option('--scope <scope>', 'Install scope (global, project)')
+    .addOption(new Option('--language <lang>', 'Language for skills').choices(['en', 'zh']))
+    .addOption(new Option('--scope <scope>', 'Install scope').choices(['global', 'project']))
+    .addOption(new Option('--skip-npm', 'Skip npm package self-update').hideHelp())
     .action(async (targetPath = '.', options) => {
     await updateCommand(targetPath, options);
 });

package/dist/cli/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/cli/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpC,OAAO,EAAE,aAAa,EAAE,MAAM,QAAQ,CAAC;AACvC,OAAO,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAClD,OAAO,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AACtD,OAAO,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AACtD,OAAO,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AAEtD,MAAM,OAAO,GAAG,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AAC/C,MAAM,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC,oBAAoB,CAAC,CAAC;AAElD,MAAM,OAAO,GAAG,IAAI,OAAO,EAAE,CAAC;AAE9B,OAAO;KACJ,IAAI,CAAC,OAAO,CAAC;KACb,WAAW,CAAC,uDAAuD,CAAC;KACpE,OAAO,CAAC,OAAO,CAAC,CAAC;AAEpB,OAAO;KACJ,OAAO,CAAC,aAAa,CAAC;KACtB,WAAW,CAAC,2CAA2C,CAAC;KACxD,MAAM,CAAC,OAAO,EAAE,gDAAgD,CAAC;KACjE,MAAM,CAAC,iBAAiB,EAAE,qCAAqC,CAAC;KAChE,MAAM,CAAC,aAAa,EAAE,kCAAkC,CAAC;KACzD,MAAM,CAAC,QAAQ,EAAE,gBAAgB,CAAC;KAClC,MAAM,CAAC,KAAK,EAAE,UAAU,GAAG,GAAG,EAAE,OAAO,EAAE,EAAE;IAC1C,IAAI,CAAC;QACH,MAAM,WAAW,CAAC,UAAU,EAAE,OAAO,CAAC,CAAC;IACzC,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,IAAI,KAAK,YAAY,KAAK,IAAI,KAAK,CAAC,IAAI,KAAK,iBAAiB,EAAE,CAAC;YAC/D,OAAO,CAAC,GAAG,CAAC,kBAAkB,CAAC,CAAC;YAChC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;QAClB,CAAC;QACD,MAAM,KAAK,CAAC;IACd,CAAC;AACH,CAAC,CAAC,CAAC;AAEL,OAAO;KACJ,OAAO,CAAC,eAAe,CAAC;KACxB,WAAW,CAAC,yCAAyC,CAAC;KACtD,MAAM,CAAC,QAAQ,EAAE,gBAAgB,CAAC;KAClC,MAAM,CAAC,KAAK,EAAE,UAAU,GAAG,GAAG,EAAE,OAAO,EAAE,EAAE;IAC1C,MAAM,aAAa,CAAC,UAAU,EAAE,OAAO,CAAC,CAAC;AAC3C,CAAC,CAAC,CAAC;AAEL,OAAO;KACJ,OAAO,CAAC,eAAe,CAAC;KACxB,WAAW,CAAC,oCAAoC,CAAC;KACjD,MAAM,CAAC,QAAQ,EAAE,gBAAgB,CAAC;KAClC,MAAM,CAAC,KAAK,EAAE,UAAU,GAAG,GAAG,EAAE,OAAO,EAAE,EAAE;IAC1C,MAAM,aAAa,CAAC,UAAU,EAAE,OAAO,CAAC,CAAC;AAC3C,CAAC,CAAC,CAAC;AAEL,OAAO;KACJ,OAAO,CAAC,eAAe,CAAC;KACxB,WAAW,CAAC,4CAA4C,CAAC;KACzD,MAAM,CAAC,QAAQ,EAAE,gBAAgB,CAAC;KAClC,MAAM,CAAC,mBAAmB,EAAE,8BAA8B,CAAC;KAC3D,MAAM,CAAC,iBAAiB,EAAE,iCAAiC,CAAC;KAC5D,MAAM,CAAC,KAAK,EAAE,UAAU,GAAG,GAAG,EAAE,OAAO,EAAE,EAAE;IAC1C,MAAM,aAAa,CAAC,UAAU,EAAE,OAAO,CAAC,CAAC;AAC3C,CAAC,CAAC,CAAC;AAEL,OAAO,CAAC,KAAK,EAAE,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/cli/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,WAAW,CAAC;AAC5C,OAAO,EAAE,aAAa,EAAE,MAAM,QAAQ,CAAC;AACvC,OAAO,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAClD,OAAO,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AACtD,OAAO,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AACtD,OAAO,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AAEtD,MAAM,OAAO,GAAG,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AAC/C,MAAM,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC,oBAAoB,CAAC,CAAC;AAElD,MAAM,OAAO,GAAG,IAAI,OAAO,EAAE,CAAC;AAE9B,OAAO;KACJ,IAAI,CAAC,OAAO,CAAC;KACb,WAAW,CAAC,uDAAuD,CAAC;KACpE,OAAO,CAAC,OAAO,CAAC,CAAC;AAEpB,OAAO;KACJ,OAAO,CAAC,aAAa,CAAC;KACtB,WAAW,CAAC,2CAA2C,CAAC;KACxD,MAAM,CAAC,OAAO,EAAE,gDAAgD,CAAC;KACjE,MAAM,CAAC,iBAAiB,EAAE,qCAAqC,CAAC;KAChE,MAAM,CAAC,aAAa,EAAE,kCAAkC,CAAC;KACzD,MAAM,CAAC,QAAQ,EAAE,gBAAgB,CAAC;KAClC,MAAM,CAAC,KAAK,EAAE,UAAU,GAAG,GAAG,EAAE,OAAO,EAAE,EAAE;IAC1C,IAAI,CAAC;QACH,MAAM,WAAW,CAAC,UAAU,EAAE,OAAO,CAAC,CAAC;IACzC,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,IAAI,KAAK,YAAY,KAAK,IAAI,KAAK,CAAC,IAAI,KAAK,iBAAiB,EAAE,CAAC;YAC/D,OAAO,CAAC,GAAG,CAAC,kBAAkB,CAAC,CAAC;YAChC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;QAClB,CAAC;QACD,MAAM,KAAK,CAAC;IACd,CAAC;AACH,CAAC,CAAC,CAAC;AAEL,OAAO;KACJ,OAAO,CAAC,eAAe,CAAC;KACxB,WAAW,CAAC,yCAAyC,CAAC;KACtD,MAAM,CAAC,QAAQ,EAAE,gBAAgB,CAAC;KAClC,MAAM,CAAC,KAAK,EAAE,UAAU,GAAG,GAAG,EAAE,OAAO,EAAE,EAAE;IAC1C,MAAM,aAAa,CAAC,UAAU,EAAE,OAAO,CAAC,CAAC;AAC3C,CAAC,CAAC,CAAC;AAEL,OAAO;KACJ,OAAO,CAAC,eAAe,CAAC;KACxB,WAAW,CAAC,oCAAoC,CAAC;KACjD,MAAM,CAAC,QAAQ,EAAE,gBAAgB,CAAC;KAClC,SAAS,CACR,IAAI,MAAM,CAAC,iBAAiB,EAAE,2BAA2B,CAAC,CAAC,OAAO,CAAC;IACjE,MAAM;IACN,QAAQ;IACR,SAAS;CACV,CAAC,CACH;KACA,MAAM,CAAC,KAAK,EAAE,UAAU,GAAG,GAAG,EAAE,OAAO,EAAE,EAAE;IAC1C,MAAM,aAAa,CAAC,UAAU,EAAE,OAAO,CAAC,CAAC;AAC3C,CAAC,CAAC,CAAC;AAEL,OAAO;KACJ,OAAO,CAAC,eAAe,CAAC;KACxB,WAAW,CAAC,4CAA4C,CAAC;KACzD,MAAM,CAAC,QAAQ,EAAE,gBAAgB,CAAC;KAClC,SAAS,CAAC,IAAI,MAAM,CAAC,mBAAmB,EAAE,qBAAqB,CAAC,CAAC,OAAO,CAAC,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC,CAAC;KACvF,SAAS,CAAC,IAAI,MAAM,CAAC,iBAAiB,EAAE,eAAe,CAAC,CAAC,OAAO,CAAC,CAAC,QAAQ,EAAE,SAAS,CAAC,CAAC,CAAC;KACxF,SAAS,CAAC,IAAI,MAAM,CAAC,YAAY,EAAE,8BAA8B,CAAC,CAAC,QAAQ,EAAE,CAAC;KAC9E,MAAM,CAAC,KAAK,EAAE,UAAU,GAAG,GAAG,EAAE,OAAO,EAAE,EAAE;IAC1C,MAAM,aAAa,CAAC,UAAU,EAAE,OAAO,CAAC,CAAC;AAC3C,CAAC,CAAC,CAAC;AAEL,OAAO,CAAC,KAAK,EAAE,CAAC"}

package/dist/commands/doctor.d.ts

@@ -1,5 +1,8 @@
+import type { InstallScope } from '../core/types.js';
+type DoctorScope = InstallScope | 'auto';
 interface DoctorOptions {
     json?: boolean;
+    scope?: DoctorScope;
 }
 export declare function doctorCommand(targetPath: string, options?: DoctorOptions): Promise<void>;
 export {};

package/dist/commands/doctor.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"doctor.d.ts","sourceRoot":"","sources":["../../src/commands/doctor.ts"],"names":[],"mappings":"AAmLA,UAAU,aAAa;IACrB,IAAI,CAAC,EAAE,OAAO,CAAC;CAChB;AAED,wBAAsB,aAAa,CACjC,UAAU,EAAE,MAAM,EAClB,OAAO,GAAE,aAAkB,GAC1B,OAAO,CAAC,IAAI,CAAC,CAgBf"}
+{"version":3,"file":"doctor.d.ts","sourceRoot":"","sources":["../../src/commands/doctor.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAQrD,KAAK,WAAW,GAAG,YAAY,GAAG,MAAM,CAAC;AAsMzC,UAAU,aAAa;IACrB,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,KAAK,CAAC,EAAE,WAAW,CAAC;CACrB;AAED,wBAAsB,aAAa,CACjC,UAAU,EAAE,MAAM,EAClB,OAAO,GAAE,aAAkB,GAC1B,OAAO,CAAC,IAAI,CAAC,CAiBf"}

package/dist/commands/doctor.js

@@ -1,4 +1,5 @@
 import path from 'path';
+import os from 'os';
 import { execSync } from 'child_process';
 import { promises as fs } from 'fs';
 import { fileExists, readDir } from '../utils/file-system.js';
@@ -14,6 +15,8 @@ const VALID_YAML_FIELDS = new Set([
     'verify_result',
     'design_doc',
     'plan',
+    'verification_report',
+    'branch_status',
     'archived',
     'verified_at',
 ]);
@@ -57,39 +60,56 @@ async function checkWorkingDirs(projectPath) {
         message: `partial (missing: ${missing.join(', ')})`,
     };
 }
-async function checkSkillCompleteness(projectPath) {
+function getScopeBases(projectPath, scope) {
+    if (scope === 'project')
+        return [{ scope, baseDir: projectPath }];
+    if (scope === 'global')
+        return [{ scope, baseDir: os.homedir() }];
+    const bases = [
+        { scope: 'project', baseDir: projectPath },
+    ];
+    if (path.resolve(projectPath) !== path.resolve(os.homedir())) {
+        bases.push({ scope: 'global', baseDir: os.homedir() });
+    }
+    return bases;
+}
+async function checkSkillCompleteness(projectPath, scope) {
     const results = [];
     const manifest = await readManifest();
     let anyPlatform = false;
-    for (const platform of PLATFORMS) {
-        const skillsDir = path.join(projectPath, platform.skillsDir, 'skills');
-        if (!(await fileExists(skillsDir)))
-            continue;
-        anyPlatform = true;
-        const missing = [];
-        for (const relPath of manifest.skills) {
-            const fullPath = path.join(projectPath, platform.skillsDir, 'skills', relPath);
-            if (!(await fileExists(fullPath))) {
-                missing.push(relPath);
+    for (const base of getScopeBases(projectPath, scope)) {
+        for (const platform of PLATFORMS) {
+            const skillsDir = path.join(base.baseDir, platform.skillsDir, 'skills');
+            if (!(await fileExists(skillsDir)))
+                continue;
+            anyPlatform = true;
+            const missing = [];
+            for (const relPath of manifest.skills) {
+                const fullPath = path.join(base.baseDir, platform.skillsDir, 'skills', relPath);
+                if (!(await fileExists(fullPath))) {
+                    missing.push(relPath);
+                }
             }
+            results.push(missing.length === 0
+                ? {
+                    check: `skills: ${platform.name} (${base.scope})`,
+                    status: 'pass',
+                    message: `complete (${manifest.skills.length} files)`,
+                }
+                : {
+                    check: `skills: ${platform.name} (${base.scope})`,
+                    status: 'warn',
+                    message: `missing ${missing.length}: ${missing.join(', ')}`,
+                });
         }
-        results.push(missing.length === 0
-            ? {
-                check: `skills: ${platform.name}`,
-                status: 'pass',
-                message: `complete (${manifest.skills.length} files)`,
-            }
-            : {
-                check: `skills: ${platform.name}`,
-                status: 'warn',
-                message: `missing ${missing.length}: ${missing.join(', ')}`,
-            });
     }
     if (!anyPlatform) {
         results.push({
             check: 'skills',
             status: 'warn',
-            message: 'no platforms detected — run comet init',
+            message: scope === 'auto'
+                ? 'no platforms detected in project or global scope — run comet init'
+                : `no platforms detected in ${scope} scope — run comet init`,
         });
     }
     return results;
@@ -136,11 +156,13 @@ async function checkCometYamlValidity(projectPath) {
     }
     return results;
 }
-async function collectResults(projectPath) {
+async function collectResults(projectPath, scope) {
     const results = [];
     results.push(await checkOpenSpecCli());
-    results.push(await checkWorkingDirs(projectPath));
-    results.push(...(await checkSkillCompleteness(projectPath)));
+    if (scope !== 'global') {
+        results.push(await checkWorkingDirs(projectPath));
+    }
+    results.push(...(await checkSkillCompleteness(projectPath, scope)));
     results.push(await checkScriptsPresent());
     results.push(...(await checkCometYamlValidity(projectPath)));
     return results;
@@ -154,12 +176,13 @@ function icon(status) {
 }
 export async function doctorCommand(targetPath, options = {}) {
     const projectPath = path.resolve(targetPath);
-    const results = await collectResults(projectPath);
+    const scope = options.scope ?? 'auto';
+    const results = await collectResults(projectPath, scope);
     if (options.json) {
-        console.log(JSON.stringify({ results }, null, 2));
+        console.log(JSON.stringify({ scope, results }, null, 2));
         return;
     }
-    console.log('Comet Doctor\n');
+    console.log(`Comet Doctor (scope: ${scope})\n`);
     for (const r of results) {
         console.log(`  ${icon(r.status)} ${r.check}: ${r.message}`);
     }