@house365/comate 0.1.0

package/skills/comate/tests/comate.bats

@@ -0,0 +1,449 @@
+#!/usr/bin/env bats
+# comate state-machine + library tests.
+# Run with: bats skills/comate/tests/comate.bats
+# (or: bash skills/comate/tests/run.sh  — plain-bash fallback, no bats needed)
+
+setup() {
+  COMATE_ROOT="$(cd "$BATS_TEST_DIRNAME/../.." && pwd)"
+  COMATE="$COMATE_ROOT/comate/scripts/comate.sh"
+  [ -f "$COMATE" ] || COMATE="$BATS_TEST_DIRNAME/../scripts/comate.sh"
+  export COMATE_SKIP_BUILD=1
+  WORK="$(mktemp -d)"
+  cd "$WORK"
+  git init -q
+  git config user.email t@t.t
+  git config user.name t
+  git commit -q --allow-empty -m init
+  mkdir -p openspec/changes
+}
+
+teardown() {
+  cd /
+  rm -rf "$WORK"
+}
+
+comate() { bash "$COMATE" "$@"; }
+
+seed_open() {
+  comate state demo init full >/dev/null
+  local d="openspec/changes/demo"
+  printf '# proposal\n' > "$d/proposal.md"
+  printf '# design\n' > "$d/design.md"
+  printf -- '- [ ] t1\n' > "$d/tasks.md"
+}
+
+# --- init / get / set ---
+
+@test "init writes canonical field order with schema_version" {
+  comate state demo init full
+  run comate state demo get schema_version
+  [ "$status" -eq 0 ]
+  [ "$output" = "1" ]
+  run comate state demo get phase
+  [ "$output" = "open" ]
+}
+
+@test "init full leaves build decisions null" {
+  comate state demo init full
+  [ "$(comate state demo get build_mode)" = "null" ]
+  [ "$(comate state demo get tdd_mode)" = "null" ]
+  [ "$(comate state demo get isolation)" = "null" ]
+}
+
+@test "init hotfix prefills preset defaults" {
+  comate state demo init hotfix
+  [ "$(comate state demo get build_mode)" = "direct" ]
+  [ "$(comate state demo get tdd_mode)" = "direct" ]
+  [ "$(comate state demo get isolation)" = "branch" ]
+  [ "$(comate state demo get verify_mode)" = "light" ]
+}
+
+@test "init tweak prefills tdd direct" {
+  comate state demo init tweak
+  [ "$(comate state demo get build_mode)" = "direct" ]
+  [ "$(comate state demo get tdd_mode)" = "direct" ]
+  [ "$(comate state demo get isolation)" = "branch" ]
+}
+
+@test "init records base_ref and base_branch" {
+  comate state demo init full
+  run comate state demo get base_ref
+  [ "$output" != "null" ]
+  run comate state demo get base_branch
+  [ "$output" != "null" ]
+}
+
+@test "init twice fails with usage error" {
+  comate state demo init full
+  run comate state demo init full
+  [ "$status" -eq 2 ]
+}
+
+@test "set rejects unknown field" {
+  comate state demo init full
+  run comate state demo set bogus_field x
+  [ "$status" -eq 2 ]
+}
+
+@test "set rejects bad enum value" {
+  comate state demo init full
+  run comate state demo set phase nonsense
+  [ "$status" -eq 2 ]
+}
+
+@test "set rejects bad tdd_mode value" {
+  comate state demo init full
+  run comate state demo set tdd_mode maybe
+  [ "$status" -eq 2 ]
+}
+
+@test "set is idempotent and keeps single key" {
+  comate state demo init full
+  comate state demo set verify_mode light >/dev/null
+  comate state demo set verify_mode full >/dev/null
+  local count
+  count=$(grep -c '^verify_mode:' "openspec/changes/demo/.comate.yaml")
+  [ "$count" -eq 1 ]
+  [ "$(comate state demo get verify_mode)" = "full" ]
+}
+
+# --- input validation ---
+
+@test "path traversal in change name rejected" {
+  run comate state "../evil" get phase
+  [ "$status" -eq 2 ]
+}
+
+@test "get on missing yaml returns corrupt code" {
+  run comate state nope get phase
+  [ "$status" -eq 4 ]
+}
+
+# --- flat yaml validation ---
+
+@test "validate passes on clean init" {
+  comate state demo init full
+  run comate state demo validate
+  [ "$status" -eq 0 ]
+}
+
+@test "validate rejects nested yaml with corrupt code" {
+  comate state demo init full
+  printf 'nested:\n  child: 1\n' >> "openspec/changes/demo/.comate.yaml"
+  run comate state demo validate
+  [ "$status" -eq 4 ]
+}
+
+@test "validate rejects list items" {
+  comate state demo init full
+  printf -- '- item\n' >> "openspec/changes/demo/.comate.yaml"
+  run comate state demo validate
+  [ "$status" -eq 4 ]
+}
+
+# --- state machine transitions ---
+
+@test "transition rejects wrong-phase event" {
+  comate state demo init full
+  run comate state demo transition design-complete
+  [ "$status" -eq 1 ]
+}
+
+@test "open-complete routes full to design" {
+  seed_open
+  comate state demo transition open-complete
+  [ "$(comate state demo get phase)" = "design" ]
+}
+
+@test "open-complete routes hotfix to build" {
+  comate state demo init hotfix
+  comate state demo transition open-complete
+  [ "$(comate state demo get phase)" = "build" ]
+}
+
+@test "build-complete blocked without isolation" {
+  comate state demo init hotfix
+  comate state demo transition open-complete
+  comate state demo set isolation null >/dev/null
+  run comate state demo transition build-complete
+  [ "$status" -eq 1 ]
+}
+
+@test "full direct build blocked without override" {
+  comate state demo init full
+  comate state demo set isolation branch >/dev/null
+  comate state demo set build_mode direct >/dev/null
+  comate state demo set tdd_mode direct >/dev/null
+  # force phase to build to isolate the decision check
+  comate state demo set phase build >/dev/null
+  run comate state demo transition build-complete
+  [ "$status" -eq 1 ]
+}
+
+@test "build-complete blocked without tdd_mode" {
+  comate state demo init full
+  comate state demo set isolation branch >/dev/null
+  comate state demo set build_mode executing-plans >/dev/null
+  comate state demo set phase build >/dev/null
+  run comate state demo transition build-complete
+  [ "$status" -eq 1 ]
+  [[ "$output" == *"tdd_mode"* ]]
+}
+
+@test "build-complete accepts tdd_mode tdd" {
+  comate state demo init full
+  comate state demo set isolation branch >/dev/null
+  comate state demo set build_mode executing-plans >/dev/null
+  comate state demo set tdd_mode tdd >/dev/null
+  comate state demo set phase build >/dev/null
+  run comate state demo transition build-complete
+  [ "$status" -eq 0 ]
+  [ "$(comate state demo get phase)" = "verify" ]
+}
+
+@test "verify-pass blocked without report" {
+  comate state demo init full
+  comate state demo set phase verify >/dev/null
+  run comate state demo transition verify-pass
+  [ "$status" -eq 1 ]
+}
+
+# --- guard open ---
+
+@test "guard open passes with full artifacts and applies" {
+  seed_open
+  printf -- '- [x] t1\n' > "openspec/changes/demo/tasks.md"
+  run comate guard demo open --apply
+  [ "$status" -eq 0 ]
+  [ "$(comate state demo get phase)" = "design" ]
+}
+
+@test "guard open json emits block false" {
+  seed_open
+  run comate guard demo open --json
+  [ "$status" -eq 0 ]
+  [[ "$output" == *'"block":false'* ]]
+}
+
+# --- handoff design + hash drift ---
+
+@test "design handoff writes context and hash" {
+  seed_open
+  comate guard demo open --apply >/dev/null 2>&1
+  comate handoff demo design --write
+  run comate state demo get handoff_hash
+  [[ "$output" =~ ^[a-f0-9]{64}$ ]]
+}
+
+@test "design guard blocks on handoff hash drift" {
+  seed_open
+  comate guard demo open --apply >/dev/null 2>&1
+  comate handoff demo design --write >/dev/null 2>&1
+  printf 'edited after handoff\n' >> "openspec/changes/demo/proposal.md"
+  run comate guard demo design --json
+  [ "$status" -eq 1 ]
+  [[ "$output" == *'"block":true'* ]]
+}
+
+# --- build->verify drift ---
+
+@test "verify guard blocks when tasks change after build handoff" {
+  comate state demo init hotfix
+  local d="openspec/changes/demo"
+  printf '# p\n' > "$d/proposal.md"; printf '# d\n' > "$d/design.md"; printf -- '- [x] t1\n' > "$d/tasks.md"
+  comate guard demo open --apply >/dev/null 2>&1
+  comate handoff demo build --write >/dev/null 2>&1
+  comate guard demo build --apply >/dev/null 2>&1
+  printf 'rep\n' > "$d/rep.md"
+  comate state demo set verification_report "$d/rep.md" >/dev/null
+  comate state demo set branch_status handled >/dev/null
+  # tamper tasks after build exit
+  printf -- '- [x] t1\n- [x] sneaked\n' > "$d/tasks.md"
+  run comate guard demo verify --json
+  [ "$status" -eq 1 ]
+  [[ "$output" == *'impl_hash'*'fail'* ]] || [[ "$output" == *'"block":true'* ]]
+}
+
+# --- archive ---
+
+@test "archive delegates spec merge to openspec instead of copying delta over main" {
+  comate state demo init full
+  local d="openspec/changes/demo"
+  printf '# p\n' > "$d/proposal.md"
+  printf '# d\n' > "$d/design.md"
+  printf -- '- [x] t1\n' > "$d/tasks.md"
+  mkdir -p "$d/specs/cap" openspec/specs/cap bin
+  printf '# Main Spec\n\n## Requirements\n\n### Requirement: Existing\n' > openspec/specs/cap/spec.md
+  printf '## ADDED Requirements\n\n### Requirement: Delta Only\n' > "$d/specs/cap/spec.md"
+
+  cat > bin/openspec <<'SH'
+#!/bin/bash
+set -e
+[ "$1" = "archive" ] || exit 2
+name="$2"
+mkdir -p openspec/changes/archive
+mv "openspec/changes/$name" "openspec/changes/archive/$(date +%Y-%m-%d)-$name"
+SH
+  chmod +x bin/openspec
+  export PATH="$PWD/bin:$PATH"
+
+  comate state demo set phase archive >/dev/null
+  comate state demo set verify_result pass >/dev/null
+  run comate archive demo
+  [ "$status" -eq 0 ]
+  [[ "$(cat openspec/specs/cap/spec.md)" == *"Requirement: Existing"* ]]
+  [[ "$(cat openspec/specs/cap/spec.md)" != *"Delta Only"* ]]
+  [ "$(comate state "$(date +%Y-%m-%d)-demo" get archived)" = "true" ]
+}
+
+@test "archive repoints .comate.yaml self-pointers to archive path" {
+  comate state demo init full
+  local d="openspec/changes/demo"
+  printf '# p\n' > "$d/proposal.md"; printf '# d\n' > "$d/design.md"; printf -- '- [x] t1\n' > "$d/tasks.md"
+  mkdir -p docs/knowledge-base/cb bin
+  printf '# frd\n' > docs/knowledge-base/cb/frd.md
+  comate sources demo track docs/knowledge-base/cb/frd.md >/dev/null 2>&1
+  cat > bin/openspec <<'SH'
+#!/bin/bash
+set -e
+[ "$1" = "archive" ] || exit 2
+mkdir -p openspec/changes/archive
+mv "openspec/changes/$2" "openspec/changes/archive/$(date +%Y-%m-%d)-$2"
+SH
+  chmod +x bin/openspec
+  export PATH="$PWD/bin:$PATH"
+  comate state demo set phase archive >/dev/null
+  comate state demo set verify_result pass >/dev/null
+  run comate archive demo
+  [ "$status" -eq 0 ]
+  local an="$(date +%Y-%m-%d)-demo"
+  [ "$(comate state "$an" get source_manifest)" = "openspec/changes/archive/$an/.comate/sources.manifest" ]
+  run comate sources "$an" check
+  [ "$status" -eq 0 ]
+}
+
+@test "archive rewrites design doc body references to archive path" {
+  comate state demo init full
+  local d="openspec/changes/demo"
+  printf '# p\n' > "$d/proposal.md"; printf '# d\n' > "$d/design.md"; printf -- '- [x] t1\n' > "$d/tasks.md"
+  mkdir -p docs/superpowers/specs bin
+  printf -- '---\ncomate_change: demo\nrole: technical-design\ncanonical_spec: openspec\n---\nref: openspec/changes/demo/specs/cap/spec.md\n' > docs/superpowers/specs/dd.md
+  comate state demo set design_doc docs/superpowers/specs/dd.md >/dev/null
+  cat > bin/openspec <<'SH'
+#!/bin/bash
+set -e
+[ "$1" = "archive" ] || exit 2
+mkdir -p openspec/changes/archive
+mv "openspec/changes/$2" "openspec/changes/archive/$(date +%Y-%m-%d)-$2"
+SH
+  chmod +x bin/openspec
+  export PATH="$PWD/bin:$PATH"
+  comate state demo set phase archive >/dev/null
+  comate state demo set verify_result pass >/dev/null
+  run comate archive demo
+  [ "$status" -eq 0 ]
+  local an="$(date +%Y-%m-%d)-demo"
+  [[ "$(cat docs/superpowers/specs/dd.md)" == *"openspec/changes/archive/$an/specs/cap/spec.md"* ]]
+  [[ "$(cat docs/superpowers/specs/dd.md)" == *"comate_change: demo"* ]]
+  [[ "$(cat docs/superpowers/specs/dd.md)" == *"archived-with: $an"* ]]
+}
+
+# --- scale ---
+
+@test "scale sets verify_mode full when many tasks" {
+  comate state demo init full
+  local d="openspec/changes/demo"
+  printf -- '- [ ] a\n- [ ] b\n- [ ] c\n- [ ] d\n' > "$d/tasks.md"
+  comate state demo scale
+  [ "$(comate state demo get verify_mode)" = "full" ]
+}
+
+@test "scale sets verify_mode light when few tasks" {
+  comate state demo init full
+  printf -- '- [ ] a\n' > "openspec/changes/demo/tasks.md"
+  comate state demo scale
+  [ "$(comate state demo get verify_mode)" = "light" ]
+}
+
+# --- source tracking ---
+
+@test "init defaults source_kind conversation with null manifest" {
+  comate state demo init full
+  [ "$(comate state demo get source_kind)" = "conversation" ]
+  [ "$(comate state demo get source_manifest)" = "null" ]
+}
+
+@test "sources check on conversation source is a no-op pass" {
+  comate state demo init full
+  run comate sources demo check
+  [ "$status" -eq 0 ]
+}
+
+@test "sources track records kb file and flips source_kind to file" {
+  comate state demo init full
+  mkdir -p docs/knowledge-base/cb
+  printf '# frd\n' > docs/knowledge-base/cb/frd.md
+  run comate sources demo track docs/knowledge-base/cb/frd.md --note "main entry"
+  [ "$status" -eq 0 ]
+  [ "$(comate state demo get source_kind)" = "file" ]
+  [ "$(comate state demo get source_manifest)" = "openspec/changes/demo/.comate/sources.manifest" ]
+  run comate sources demo list
+  [[ "$output" == *"path:docs/knowledge-base/cb/frd.md"* ]]
+  [[ "$output" == *"note:main entry"* ]]
+}
+
+@test "sources track rejects file outside knowledge-base" {
+  comate state demo init full
+  printf 'x\n' > docs/outside.md
+  run comate sources demo track docs/outside.md
+  [ "$(comate state demo get source_kind)" = "conversation" ]
+  [ "$(comate state demo get source_manifest)" = "null" ]
+}
+
+@test "sources check detects drift after file edited" {
+  comate state demo init full
+  mkdir -p docs/knowledge-base/cb
+  printf '# frd\n' > docs/knowledge-base/cb/frd.md
+  comate sources demo track docs/knowledge-base/cb/frd.md >/dev/null 2>&1
+  printf 'edited\n' >> docs/knowledge-base/cb/frd.md
+  run comate sources demo check
+  [ "$status" -eq 1 ]
+  [[ "$output" == *"drifted"* ]]
+}
+
+@test "sources find reverse-looks-up a tracked file" {
+  comate state demo init full
+  mkdir -p docs/knowledge-base/cb
+  printf '# frd\n' > docs/knowledge-base/cb/frd.md
+  comate sources demo track docs/knowledge-base/cb/frd.md >/dev/null 2>&1
+  run comate sources find docs/knowledge-base/cb/frd.md
+  [ "$status" -eq 0 ]
+  [[ "$output" == *"demo"* ]]
+}
+
+@test "build guard blocks when tracked source drifts" {
+  comate state demo init hotfix
+  local d="openspec/changes/demo"
+  printf '# p\n' > "$d/proposal.md"; printf '# d\n' > "$d/design.md"; printf -- '- [x] t1\n' > "$d/tasks.md"
+  mkdir -p docs/knowledge-base/cb
+  printf '# frd\n' > docs/knowledge-base/cb/frd.md
+  comate sources demo track docs/knowledge-base/cb/frd.md >/dev/null 2>&1
+  comate guard demo open --apply >/dev/null 2>&1
+  comate handoff demo build --write >/dev/null 2>&1
+  printf 'edited\n' >> docs/knowledge-base/cb/frd.md
+  run comate guard demo build --json
+  [ "$status" -eq 1 ]
+  [[ "$output" == *'"block":true'* ]]
+}
+
+# --- doctor + usage ---
+
+@test "doctor exits 0 when core tools present" {
+  run comate doctor
+  [ "$status" -eq 0 ]
+}
+
+@test "top-level usage error returns code 2" {
+  run comate frobnicate
+  [ "$status" -eq 2 ]
+}

package/skills/comate/tests/run.sh

@@ -0,0 +1,101 @@
+#!/bin/bash
+# run.sh — plain-bash runner for comate.bats when `bats` is not installed.
+#
+# It sources each @test body in a subshell with setup/teardown, providing the
+# minimal bats shims (`run`, `$status`, `$output`, `$BATS_TEST_DIRNAME`).
+# If real bats is available, prefer: bats skills/comate/tests/comate.bats
+#
+# Usage: bash skills/comate/tests/run.sh
+
+set -uo pipefail
+
+TEST_DIR="$(cd "$(dirname "$0")" && pwd)"
+BATS_FILE="$TEST_DIR/comate.bats"
+export BATS_TEST_DIRNAME="$TEST_DIR"
+
+# bats shim: run a command, capture combined output + status.
+run() {
+  local _out _rc
+  _out="$("$@" 2>&1)"
+  _rc=$?
+  output="$_out"
+  status="$_rc"
+  # shellcheck disable=SC2034
+  lines=()
+  local _l
+  while IFS= read -r _l; do lines+=("$_l"); done <<< "$_out"
+  return 0
+}
+
+# Extract test names and bodies from the .bats file.
+# A test is:  @test "name" {  ... }  with closing } at column 0.
+PASS=0
+FAIL=0
+FAILED_NAMES=()
+
+# shellcheck disable=SC1090
+source_helpers() {
+  # Pull setup(), teardown(), comate(), seed_open() definitions by sourcing
+  # a sanitized copy that strips the @test blocks.
+  local helpers
+  helpers="$(awk '
+    /^@test / { skip=1 }
+    skip==1 && /^}/ { skip=0; next }
+    skip==1 { next }
+    { print }
+  ' "$BATS_FILE")"
+  eval "$helpers"
+}
+
+run_one() {
+  local name="$1" body="$2"
+  ( # subshell isolates each test
+    set -uo pipefail
+    source_helpers
+    status=0; output=""
+    setup
+    _trap() { teardown 2>/dev/null || true; }
+    trap _trap EXIT
+    eval "$body"
+  )
+}
+
+main() {
+  local name="" body="" in_test=0
+  while IFS= read -r line; do
+    if [[ "$in_test" -eq 0 && "$line" =~ ^@test\ \"(.*)\"\ \{ ]]; then
+      name="${BASH_REMATCH[1]}"
+      body=""
+      in_test=1
+      continue
+    fi
+    if [[ "$in_test" -eq 1 && "$line" == "}" ]]; then
+      in_test=0
+      if run_one "$name" "$body" >/tmp/comate_test_out.$$ 2>&1; then
+        PASS=$((PASS+1))
+        printf '  ok   %s\n' "$name"
+      else
+        FAIL=$((FAIL+1))
+        FAILED_NAMES+=("$name")
+        printf '  FAIL %s\n' "$name"
+        sed 's/^/       /' /tmp/comate_test_out.$$
+      fi
+      continue
+    fi
+    if [[ "$in_test" -eq 1 ]]; then
+      body+="$line"$'\n'
+    fi
+  done < "$BATS_FILE"
+  rm -f /tmp/comate_test_out.$$
+
+  echo ""
+  echo "comate tests: $PASS passed, $FAIL failed"
+  if [ "$FAIL" -gt 0 ]; then
+    printf 'Failed:\n'
+    printf '  - %s\n' "${FAILED_NAMES[@]}"
+    exit 1
+  fi
+  exit 0
+}
+
+main

package/skills/comate-archive/SKILL.md

@@ -0,0 +1,63 @@
+---
+name: comate-archive
+description: "comate 阶段 5：归档。用 /comate-archive 调用。委托 OpenSpec 合并 delta spec 并归档 change。"
+---
+
+# comate 阶段 5：归档（Archive）
+
+## 前置条件
+
+- 验证已通过（阶段 4 完成），分支已处理
+- `openspec/changes/<name>/.comate.yaml` 中 `verify_result: pass`
+
+## 步骤
+
+### 0. 入口状态验证
+
+```bash
+COMATE="${COMATE:-$(for r in . ./.claude/skills "$HOME"/.claude/skills "$HOME"/.config/skills "$HOME"/.cursor/skills; do
+  [ -d "$r" ] && find "$r" -maxdepth 6 -path '*/comate/scripts/comate.sh' -type f -print -quit 2>/dev/null
+done | head -1)}"
+if [ -z "$COMATE" ]; then
+  echo "ERROR: comate.sh 未找到，请确认 comate skill 已安装。" >&2
+  return 1 2>/dev/null || exit 1
+fi
+bash "$COMATE" state <name> check archive
+```
+
+### 1. 执行归档
+
+```bash
+bash "$COMATE" archive "<name>"
+```
+
+脚本自动完成：
+1. 入口状态验证（phase=archive, verify_result=pass, archived=false）
+2. 委托 `openspec archive <name> -y` 合并 delta spec 到主 spec；无 delta spec 时使用 `--skip-specs`
+3. Design doc 前置元数据标注（archived-with, status: final），并把正文中指向 `openspec/changes/<name>/` 的引用重写为归档路径
+4. Plan 前置元数据标注（archived-with），同样重写正文 OpenSpec 路径引用
+5. 由 OpenSpec 移动 change 到 `openspec/changes/archive/YYYY-MM-DD-<name>/`
+6. 通过 `state transition <archive-name> archived` 设 `archived: true`
+7. 重写归档后 `.comate.yaml` 中随 change 移动的自指字段（`source_manifest` / `handoff_context` / `impl_context`）指向新归档路径，使 `sources <name> check/list` 等命令对归档 change 仍可用
+
+非零退出码 → 报告错误并停止。零退出码 → 归档完成。摘要 `X/Y steps succeeded` 以真实执行步骤计数。
+
+需预览不实际执行：加 `--dry-run`。
+
+### 2. 生命周期闭环
+
+```
+brainstorming → delta spec → 实施 → 验证 → OpenSpec 合并主 spec → design doc 标注 → 归档
+```
+
+## 退出条件
+
+- 归档脚本退出码 0
+- 归档目录 `openspec/changes/archive/YYYY-MM-DD-<name>/` 存在
+- 归档后 `.comate.yaml` 中 `archived: true`
+
+归档成功后**不要再对原 change 名跑 guard**，原活跃目录已不存在。
+
+## 完成
+
+comate 流程全部完成。如需开始新工作，调用 `/comate` 或 `/comate-open`。