@rpamis/comet 0.3.6 → 0.3.7

package/assets/skills/comet/SKILL.md

@@ -20,6 +20,10 @@ Superpowers handles HOW — technical design, planning, execution, closing
 
 Agents need only read this section for decision-making. Refer to the Reference Appendix as needed.
 
+### Output Language Rule
+
+Use the language of the user request that triggered this workflow as the default output language. When resuming an existing change with a clear dominant artifact language, preserve that language unless the user explicitly asks to switch.
+
 ### Automatic Phase Detection
 
 **Step 0: Active Change Discovery and Intent Detection**
@@ -53,19 +57,22 @@ Prefer reading `openspec/changes/<name>/.comet.yaml`. If not available, fall bac
 **Resume rules**:
 - On every context resume, rerun Step 0 and Step 1; do not trust conversation history for phase detection
 - If there is an active change and the worktree has uncommitted changes, handle them through `comet/reference/dirty-worktree.md`. That protocol defines checks, attribution, and prohibitions; this file does not repeat them
-- If `phase: build`, first check `build_pause`, `plan`, `build_mode`, and `isolation`:
-  - If `build_pause: plan-ready` and the plan file exists, return to the `/comet-build` plan-ready resume point, prompt the user to continue choosing isolation and execution method, and do not regenerate the plan
+- If `phase: build`, first check `build_pause`, `plan`, `build_mode`, and `isolation` (see details below):
+  - If `build_pause: plan-ready` but `isolation` and `build_mode` are already set, treat as stale pause: first output `[COMET] Detected stale pause (build_pause=plan-ready but isolation/build_mode already set), auto-clearing and continuing`, then run `"$COMET_BASH" "$COMET_STATE" set <name> build_pause null`, then read the next unchecked task from tasks.md and resume execution per `build_mode`
+  - If `build_pause: plan-ready` and the plan file exists, but `isolation` or `build_mode` is not yet set, return to the `/comet-build` plan-ready resume point, prompt the user to choose isolation and execution method, and do not regenerate the plan
   - 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 `build_mode`, `isolation`, or `tdd_mode` is unset, return to the corresponding `/comet-build` step to supplement before executing
+  - If all are set, read the next unchecked task from tasks.md and continue:
+    - If `build_mode: subagent-driven-development`, do not execute tasks directly in the main window; return to `/comet-build`'s background subagent dispatch rules, main window only coordinates
+    - Other execution modes follow `/comet-build`'s corresponding rules
 - 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: 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
+- If `phase: archive`, only invoke `/comet-archive`; `/comet-archive` must first wait for final archive confirmation. 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)
 
 1. `archived: true` or change moved to archive → Workflow complete
-2. `verify_result: pass` and `archived` is not `true` → Invoke `/comet-archive`
+2. `verify_result: pass` and `archived` is not `true` → Invoke `/comet-archive` (first perform final archive confirmation)
 3. `verify_result: fail` → Enter verification failure decision blocking point (pause and ask fix or accept deviation; only after user chooses fix, run `verify-fail` then `/comet-build`)
 4. `phase: verify` or tasks.md all checked → Invoke `/comet-verify`
 5. `phase: build` or has Design Doc but plan/execution incomplete → Route by workflow: `hotfix` → `/comet-hotfix`, `tweak` → `/comet-tweak`, `full` → `/comet-build`
@@ -89,6 +96,8 @@ If metadata conflicts with file state, use verifiable file state as source of tr
 - Cross-module coordination required
 - **5+** new test cases needed
 - Config item additions or deletions (not value changes)
+- New capability needed
+- Delta spec needed (existing spec affected)
 
 ### Error Handling Quick Reference
 
@@ -107,26 +116,30 @@ A single `/comet` invocation starts from the detected phase and advances to the
 
 Flow chain: open → design → build → verify → archive
 
-**Continuous execution requirement**: starting from the detected phase, the agent automatically continues through all later phases. But **auto-advancing only applies at transition points without user decisions**. When encountering user decision points, **must use the AskUserQuestion tool to pause and wait for the user's explicit response**. Must not use recommendation rules, defaults, or historical preferences to substitute for user confirmation, and must not just output a text prompt and then continue executing.
+**Continuous execution requirement**: starting from the detected phase, the agent automatically continues through all later phases. But **auto-advancing only applies at transition points without user decisions**. When encountering user decision points, **must use the current platform's available user input/confirmation mechanism to pause and wait for the user's explicit response**. Must not use recommendation rules, defaults, or historical preferences to substitute for user confirmation, and must not just output a text prompt and then continue executing.
 
-**Decision points are blocking points**: whenever reaching any of the following nodes, the current `/comet` invocation must stop, **using the AskUserQuestion tool to wait for the user's choice**. Only after the user explicitly chooses can the corresponding state fields be written and operations executed, then auto-advance resumes.
+**Distinguish phase advancement vs automatic handoff**: each sub-skill runs phase guard `--apply` before exit to advance the `.comet.yaml` `phase` field. This step **always happens** and is not controlled by `auto_transition`. After that, the sub-skill runs `"$COMET_BASH" "$COMET_STATE" next <name>` to resolve the next action: when `auto_transition` is not `false`, output is `NEXT: auto` (auto-invoke next skill); when `auto_transition` is `false`, output is `NEXT: manual` (do not invoke next skill, show a manual run hint). Therefore `auto_transition` **only controls next skill invocation, not phase advancement**. Regardless of `auto_transition`, user decision points below remain blocking.
+
+**Decision points are blocking points**: whenever reaching any of the following nodes, the current `/comet` invocation must stop, **using the current platform's available user input/confirmation mechanism to wait for the user's choice**. If the current platform has no structured question tool, ask clear options in the conversation and stop the workflow, waiting for the user's reply before continuing. Only after the user explicitly chooses can the corresponding state fields be written and operations executed, then auto-advance resumes.
 
 Nodes requiring user participation (pause only at these nodes):
 1. Open phase proposal/design/tasks review and confirmation
 2. Confirm design approach during brainstorming
-3. Plan-ready pause choice during build phase, followed by workflow configuration selection (isolation + execution method)
+3. Plan-ready pause choice during build phase, followed by workflow configuration selection (isolation + execution method + TDD mode)
 4. Decide to fix or accept deviation when verify fails (including Spec drift handling)
 5. Choose branch handling method for finishing-branch
-6. Encounter upgrade conditions (hotfix/tweak → full workflow)
-7. Build phase scope expansion requiring redesign or new change split
+6. Archive phase final confirmation before running the archive script
+7. Encounter upgrade conditions (hotfix/tweak → full workflow)
+8. Build phase scope expansion requiring redesign or new change split
+9. Open phase large PRD requiring confirmation to split into multiple changes
 
-Agents should not skip these decision points; other unambiguous phase transitions must proceed automatically, must not exit midway. At decision points, **text output must NOT substitute for tool-based waiting — must explicitly obtain the user's choice via AskUserQuestion before continuing**.
+Agents should not skip these decision points; other unambiguous phase transitions must proceed automatically, must not exit midway. At decision points, **must not skip user confirmation or choose automatically — must explicitly obtain the user's choice through the current platform's available user input/confirmation mechanism before continuing**.
 
 **Red Flags** — when these thoughts appear, STOP and check:
 
 | Agent Thought | Actual Risk |
 |--------------|-------------|
-| "The user would probably agree with this approach" | Cannot decide for the user — use AskUserQuestion |
+| "The user would probably agree with this approach" | Cannot decide for the user — use the current platform's user input/confirmation mechanism |
 | "This is a small change, confirmation isn't needed" | Decision points have no size exception — blocking points must wait |
 | "The user chose A last time, so A again" | Historical preference cannot substitute for current confirmation |
 | "I explained the plan and the user didn't object" | No objection ≠ consent — must use tool to get explicit choice |
@@ -176,6 +189,8 @@ plan: docs/superpowers/plans/YYYY-MM-DD-feature.md
 base_ref: a1b2c3d4e5f6...
 build_mode: subagent-driven-development
 build_pause: null
+subagent_dispatch: confirmed
+tdd_mode: tdd
 isolation: branch
 verify_mode: light
 verify_result: pending
@@ -195,8 +210,11 @@ archived: false
 | `base_ref` | Git commit SHA recorded at init, used for scale assessment. Serves as fallback when no plan exists |
 | `build_mode` | Selected execution method, can be empty |
 | `build_pause` | Internal build-phase pause point. `null` means no pause; `plan-ready` means the plan has been generated and the user chose to pause for switching models |
+| `subagent_dispatch` | `null` or `confirmed`. Only when the current platform has confirmed real background subagent / Task / multi-agent dispatch capability can `build_mode: subagent-driven-development` be written and used to leave the build phase |
+| `tdd_mode` | `tdd` or `direct`. Must be selected before full workflow leaves build phase. `tdd` enforces writing a failing test first for each task; `direct` does not enforce TDD. hotfix/tweak default to `direct` |
 | `isolation` | `branch` or `worktree`, workspace isolation method. Full workflow init may leave this as `null`, but only until `/comet-build` Step 3; hotfix/tweak default to `branch` |
 | `verify_mode` | `light` or `full`, can be empty |
+| `auto_transition` | `true` or `false`. `false` pauses only the next skill invocation; it does not block phase updates |
 | `verify_result` | `pending`, `pass`, or `fail` |
 | `verification_report` | Verification report file path; must point to an existing file before verify can pass |
 | `branch_status` | `pending` or `handled`; set to `handled` after branch handling completes |
@@ -215,13 +233,15 @@ Optional fields:
 State-machine hard constraints:
 - Before `build → verify`, `isolation` must be `branch` or `worktree`
 - Before `build → verify`, `build_mode` must be selected
+- `build_mode: subagent-driven-development` must also have `subagent_dispatch: confirmed`
+- Before full workflow leaves build phase, `tdd_mode` must be selected as `tdd` or `direct`
 - `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`
 
 ### Script Location
 
-Comet scripts are distributed in `comet/scripts/`. **Do not hardcode paths** — locate once, cache in env vars:
+Comet scripts are distributed in `comet/scripts/`. **Do not hardcode paths** — locate once, cache in env vars. This block is a standard boilerplate repeated in every sub-skill for independent loadability; changes must be kept in sync across all files (boilerplate version: `v2`, update this version when changing to help locate files needing sync):
 
 ```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)}"
@@ -256,6 +276,14 @@ fi
 "$COMET_BASH" "$COMET_STATE" transition <archive-name> archived
 ```
 
+**Resolve next action**: after guard-based phase advancement, use the `next` subcommand to determine whether to auto-invoke the next skill:
+
+```bash
+"$COMET_BASH" "$COMET_STATE" next <change-name>
+```
+
+Output format: `NEXT: auto|manual|done` + `SKILL: <skill-name>` (omitted for `done`) + `HINT` (for `manual` only). With `auto_transition: false`, output is `manual`, which pauses only the next skill invocation and does not affect the already-applied phase advancement.
+
 **Archive script**: Complete all archive steps in one command:
 
 ```bash
@@ -279,7 +307,7 @@ openspec/                              # OpenSpec — WHAT
 │   │   ├── .comet/handoff/            # Script-generated phase handoff packages
 │   │   └── tasks.md                   # Task checklist
 │   └── archive/YYYY-MM-DD-<name>/     # Archived
-└── specs/<capability>/spec.md         # Main specs (overwritten from delta at archive)
+└── specs/<capability>/spec.md         # Main specs (merged from delta semantics at archive)
 
 docs/superpowers/                      # Superpowers — HOW
 ├── specs/YYYY-MM-DD-<topic>-design.md # Design doc (technical RFC, mark status at archive)
@@ -293,7 +321,7 @@ docs/superpowers/                      # Superpowers — HOW
 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
 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
+6. **Verify before archive confirmation** — Enter `/comet-archive` only after `/comet-verify` passes, but wait for final user confirmation before running the archive script
 7. **Classify incremental updates** — Small edits, medium brainstorming, large new changes
 8. **Plan must associate with change** — File header contains `change:` and `design-doc:` metadata
 9. **Archive closure** — design doc and plan must mark `archived-with` status

package/assets/skills/comet/reference/dirty-worktree.md

@@ -20,6 +20,7 @@ When needed, inspect `git diff`, `git diff --cached`, and newly created file con
 ## 2. Core Rules
 
 - The user may not say which files they changed. If the worktree is dirty, including new files shown as `??` in Git status, assume changes may come from the user or mixed sources.
+- **Build artifact exclusion**: `??` files matching `.gitignore` patterns (e.g., `node_modules/`, `dist/`, `__pycache__/`, `*.o`, `target/`, `build/`) are automatically skipped during attribution and not treated as user changes.
 - A dirty worktree is code evidence only. It does not automatically advance `.comet.yaml` `phase` or check off `tasks.md`; Comet state may advance only after attribution, verification, required document synchronization, and the relevant phase guard.
 
 ## 3. Attribution

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

@@ -0,0 +1,90 @@
+# Comet 阶段感知（防漂移规则）
+
+> 此规则每轮注入，防止长上下文时遗忘 Comet 流程状态。
+> Hook 平台额外执行 `comet-hook-guard.sh` 进行硬性拦截；
+> 此 Rule 是所有平台通用的软性防线。
+
+## 全局规则
+
+### 阶段感知（最高优先级）
+
+有活跃 comet change 时（`openspec/changes/<name>/.comet.yaml` 存在），**每次开始执行操作前**必须读取 `phase` 字段确认当前阶段。
+
+**阶段与允许操作：**
+
+| 阶段 | 允许 | 禁止 |
+|------|------|------|
+| `open` | 创建 proposal/design/tasks, 运行 guard | 写源代码 |
+| `design` | brainstorming, 创建 Design Doc, 运行 guard | 写源代码 |
+| `build` | 写源代码、测试、执行计划 | 跳过用户确认点 |
+| `verify` | 验证、branch handling | 跳过失败处理 |
+| `archive` | 确认归档、运行归档脚本 | 写源代码 |
+
+### Skill 调用（不可用普通对话替代）
+
+以下操作必须通过 Skill 工具加载，Skill 不可用时应停止流程并提示安装：
+
+- **brainstorming** — design 阶段、build 阶段中等规模 spec 变更
+- **writing-plans** — build 阶段创建实现计划
+- **executing-plans** / **subagent-driven-development** — build 阶段执行
+- **test-driven-development** — build 阶段 `tdd_mode: tdd` 时，第一个 task 前
+- **systematic-debugging** — 遇到崩溃/测试失败/构建失败时
+- **verification-before-completion** — verify 阶段
+- **using-git-worktrees** — build 阶段选择 worktree 隔离时
+
+### 脚本执行（不可跳过）
+
+- **阶段退出**: `comet-guard <name> <phase> --apply`（必须看到 ALL CHECKS PASSED）
+- **压缩恢复**: `comet-state check <name> <phase> --recover`
+- **状态更新**: 关键操作后通过 `comet-state set` 更新字段，禁止手工编辑 .comet.yaml
+- **handoff 生成**: `comet-handoff <name> design --write`（禁止手写摘要）
+
+### 用户确认（不可自动跳过）
+
+以下决策点必须暂停等待用户明确选择，不得根据推荐规则自动填写：
+
+- **open**: 需求澄清完成确认、artifact 评审确认
+- **design**: brainstorming 方案确认（确认前不得创建 Design Doc）
+- **build**: plan-ready 暂停、isolation/build_mode/tdd_mode 选择、spec 大规模变更确认
+- **verify**: 验证失败处理策略、branch handling 选择
+- **archive**: 归档前最终确认
+
+## Design 阶段专项
+
+1. 第一个脚本操作 = `comet-handoff <name> design --write`（未生成 handoff 禁止加载 brainstorming）
+2. brainstorming in progress: incrementally update brainstorm-summary.md（每轮澄清或方案迭代后增量更新恢复检查点，未确认内容标注为待确认/候选）
+3. brainstorming 完成后下一步 = brainstorm-summary.md 定稿 → Design Doc → guard
+4. active compaction gate: brainstorm-summary.md 定稿后、创建 Design Doc 前，优先触发宿主平台原生上下文压缩；无法程序化触发时暂停提示用户手动压缩或确认继续
+5. **绝对不能直接开始写实现代码** — 必须先创建 Design Doc 并通过 guard
+
+## Build 阶段专项
+
+1. plan 创建后必须询问用户选择继续或暂停（`build_pause` 机制）
+2. 每个 task 完成后必须: tasks.md 打勾 → git commit（不得积攒）
+3. 遇到失败必须加载 **systematic-debugging** skill，根因未定位前不得提出源码修复
+4. spec 变更分级: 小改直接编辑 | 中改加载 brainstorming | 大改暂停等用户确认拆分
+
+## Verify 阶段专项
+
+1. 第一步运行 `comet-state scale <name>` 确定验证级别
+2. 验证失败后列出失败项等用户选择，CRITICAL 必须修
+3. 连续 3 次失败后必须让用户选择接受偏差或继续修
+
+## 上下文压缩恢复
+
+如果怀疑发生上下文压缩（之前对话被摘要、找不到之前讨论的内容），立即运行：
+
+```bash
+"$COMET_BASH" "$COMET_STATE" check <name> <phase> --recover
+```
+
+按脚本输出的 **Recovery action** 决定下一步。
+
+## 阶段退出后自动过渡
+
+guard `--apply` 成功后，必须调用下一阶段的 skill：
+
+- open → `comet-design`（full）/ `comet-build`（hotfix/tweak）
+- design → `comet-build`
+- build → `comet-verify`
+- verify → `comet-archive`

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

@@ -6,6 +6,7 @@
 set -euo pipefail
 
 COMET_BASH="${COMET_BASH:-${BASH:-bash}}"
+COMET_OPENSPEC="${COMET_OPENSPEC:-openspec}"
 
 red() { echo -e "\033[31m$1\033[0m" >&2; }
 green() { echo -e "\033[32m$1\033[0m" >&2; }
@@ -39,9 +40,9 @@ 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)"
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd -P)"
 STATE_SH="$SCRIPT_DIR/comet-state.sh"
-TODAY=$(date +%Y-%m-%d)
+TODAY=$(date -u +%Y-%m-%d)
 ARCHIVE_NAME="${TODAY}-${CHANGE}"
 ARCHIVE_DIR="openspec/changes/archive/${ARCHIVE_NAME}"
 
@@ -158,45 +159,7 @@ 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 ---
+# --- Step 4: Prepare document frontmatter annotation ---
 
 annotate_frontmatter() {
   local file="$1"
@@ -214,6 +177,7 @@ annotate_frontmatter() {
   if head -1 "$file" | grep -q '^---'; then
     local tmp_file
     tmp_file=$(mktemp)
+    chmod 600 "$tmp_file"
     awk -v archive="$ARCHIVE_NAME" -v extra="$extra_fields" '
       /^archived-with:/ { next }
       NR==1 && /^---/ { print; next }
@@ -228,6 +192,7 @@ annotate_frontmatter() {
   else
     local tmp_file
     tmp_file=$(mktemp)
+    chmod 600 "$tmp_file"
     {
       echo "---"
       echo "archived-with: $ARCHIVE_NAME"
@@ -244,27 +209,78 @@ annotate_frontmatter() {
   step_ok "Annotated: $file"
 }
 
-if [ -n "$DESIGN_DOC" ] && [ "$DESIGN_DOC" != "null" ]; then
-  annotate_frontmatter "$DESIGN_DOC" "status: final"
-fi
+# --- Step 5: Run OpenSpec archive for delta merge and move ---
 
-# --- Step 6: Annotate plan frontmatter ---
+verify_main_specs_clean() {
+  if [ ! -d "openspec/specs" ]; then
+    return 0
+  fi
 
-if [ -n "$PLAN_PATH" ] && [ "$PLAN_PATH" != "null" ]; then
-  annotate_frontmatter "$PLAN_PATH" ""
-fi
+  local found=0
+  local matches
+  for spec_file in openspec/specs/*/spec.md; do
+    [ -f "$spec_file" ] || continue
+    matches=$(grep -nE '^## (ADDED|MODIFIED|REMOVED|RENAMED) Requirements$' "$spec_file" 2>/dev/null || true)
+    if [ -n "$matches" ]; then
+      red "FATAL: delta-only section heading leaked into main spec: $spec_file"
+      printf '%s\n' "$matches" >&2
+      found=1
+    fi
+  done
 
-# --- Step 7: Move change to archive ---
+  if [ "$found" -ne 0 ]; then
+    return 1
+  fi
+  return 0
+}
+
+resolve_archive_dir() {
+  if [ -d "$ARCHIVE_DIR" ]; then
+    return 0
+  fi
+  # Fallback: search for any directory matching *-$CHANGE in archive
+  local found
+  found=$(find "openspec/changes/archive" -maxdepth 1 -mindepth 1 -type d -name "*-$CHANGE" 2>/dev/null | head -1 || true)
+  if [ -n "$found" ]; then
+    ARCHIVE_DIR="$found"
+    ARCHIVE_NAME=$(basename "$found")
+    return 0
+  fi
+  return 1
+}
 
 if [ "$DRY_RUN" -eq 1 ]; then
-  step_dry_run "Would move: $CHANGE_DIR → $ARCHIVE_DIR"
+  step_dry_run "Would run OpenSpec archive: $CHANGE"
 else
-  mkdir -p "openspec/changes/archive"
-  mv "$CHANGE_DIR" "$ARCHIVE_DIR"
-  step_ok "Moved to: $ARCHIVE_DIR"
+  if ! command -v "$COMET_OPENSPEC" >/dev/null 2>&1; then
+    red "FATAL: OpenSpec CLI not found: $COMET_OPENSPEC"
+    red "Install OpenSpec or set COMET_OPENSPEC to the openspec executable."
+    exit 1
+  fi
+
+  "$COMET_OPENSPEC" archive "$CHANGE" --yes >&2
+  if ! resolve_archive_dir; then
+    step_fail "OpenSpec archive output not found"
+    exit 1
+  else
+    step_ok "OpenSpec archive completed: $ARCHIVE_DIR"
+  fi
+
+  verify_main_specs_clean
+  step_ok "Main specs verified clean"
+fi
+
+# --- Step 6: Annotate design doc and plan frontmatter ---
+
+if [ -n "$DESIGN_DOC" ] && [ "$DESIGN_DOC" != "null" ]; then
+  annotate_frontmatter "$DESIGN_DOC" "status: final"
+fi
+
+if [ -n "$PLAN_PATH" ] && [ "$PLAN_PATH" != "null" ]; then
+  annotate_frontmatter "$PLAN_PATH" ""
 fi
 
-# --- Step 8: Mark archived via comet-state transition ---
+# --- Step 7: Mark archived via comet-state transition ---
 
 ARCHIVE_YAML="$ARCHIVE_DIR/.comet.yaml"
 
@@ -279,7 +295,7 @@ else
   fi
 fi
 
-# --- Step 9: Print summary ---
+# --- Step 8: Print summary ---
 
 echo "" >&2
 if [ "$DRY_RUN" -eq 1 ]; then