fix: enforce final archive confirmation

CHANGELOG.md

@@ -2,7 +2,7 @@
 
 All notable changes to @rpamis/comet will be documented in this file.
 
-## What's Changed [0.4.0-beta.4] - 2026-07-09
+## What's Changed [0.4.0-beta.4] - 2026-07-10
 
 ### Added
 
@@ -14,6 +14,7 @@ All notable changes to @rpamis/comet will be documented in this file.
 - **Symlink installs with existing Skills**: `comet init` and `comet update --install-mode symlink` now preserve existing platform `skills/` directories and link Comet-managed Skills inside them, so local or third-party Skills no longer make Comet installation fail ([#171](https://github.com/rpamis/comet/issues/171)).
 - **OpenSpec CLI install scope**: `comet init` now installs or upgrades the OpenSpec CLI as a global tool even during project-scope setup, so choosing OpenSpec no longer creates a project `node_modules/` directory ([#175](https://github.com/rpamis/comet/issues/175)).
 - **Archived dashboard artifacts**: `comet dashboard` now resolves archived changes back to the project root before reading `docs/superpowers/` path pointers, so archived Superpowers plans, design docs, and verify reports remain visible ([#176](https://github.com/rpamis/comet/issues/176)).
+- **Archive confirmation enforcement**: `/comet-archive` now records the user's final approval in machine-owned Classic state and refuses mutating archive runs until that transition succeeds, preventing direct script invocation from bypassing the required confirmation.
 
 ## What's Changed [0.4.0-beta.3] - 2026-07-08
 

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

@@ -38,22 +38,28 @@ node "$COMET_STATE" check <name> archive
 - 本次归档将执行的不可逆动作：按 OpenSpec delta 语义合并主 spec、标注 design doc / plan、移动 change 到 archive 目录
 
 用户确认问题必须以单选题形式呈现，包含以下选项：
-- 「确认归档」— 立即执行归档脚本，完成 spec 合并和 change 移动
+- 「确认归档」— 写入最终确认状态后执行归档脚本，完成 spec 合并和 change 移动
 - 「需要调整或重新验证」— 不执行归档；运行 `node "$COMET_STATE" transition <change-name> archive-reopen` 回到 `phase: verify`，再调用 `/comet-verify`。若验证阶段确认需要修复，再按 `/comet-verify` 的验证失败决策回到 `/comet-build`
 - 「暂不归档」— 不执行归档，保留当前 `phase: archive` 状态，等待用户稍后再次调用 `/comet-archive`
 
-只有用户选择「确认归档」后，才允许继续 Step 2。用户选择「需要调整或重新验证」后，必须先执行 `archive-reopen` 状态回退，不得手动编辑 `.comet.yaml`。
+用户选择「确认归档」后，立即执行：
+
+```bash
+node "$COMET_STATE" transition <change-name> archive-confirm
+```
+
+如 transition 返回非零退出码，报告错误并停止。只有 transition 成功后，才允许继续 Step 2。用户选择「需要调整或重新验证」后，必须先执行 `archive-reopen` 状态回退，不得手动编辑 `.comet.yaml`。
 
 ### 2. 执行归档
 
-运行归档脚本，自动完成以下全部步骤：
+运行归档脚本：
 
 ```bash
 node "$COMET_ARCHIVE" "<change-name>"
 ```
 
 脚本自动执行：
-1. 入口状态验证（phase=archive, verify_result=pass, archived=false）
+1. 入口状态验证（phase=archive, verify_result=pass, archive_confirmation=confirmed, archived=false）
 2. Design doc 前置元数据标注（archived-with, status）
 3. Plan 前置元数据标注（archived-with）
 4. 调用 OpenSpec archive 按 delta 语义合并主 spec 并移动 change 到归档目录

assets/skills-zh/comet/reference/comet-yaml-fields.md

@@ -26,6 +26,7 @@ verification_report: null
 branch_status: pending
 created_at: 2026-05-26
 verified_at: null
+archive_confirmation: null
 archived: false
 ```
 
@@ -52,6 +53,7 @@ archived: false
 | `branch_status` | `pending` 或 `handled`，分支处理完成后设为 `handled` |
 | `created_at` | change 创建日期（init 时自动写入），格式 `YYYY-MM-DD` |
 | `verified_at` | 验证通过时间，可为空 |
+| `archive_confirmation` | `null`、`pending` 或 `confirmed`。`verify-pass` 进入 archive 阶段时写入 `pending`；用户在 `/comet-archive` 最终确认选择「确认归档」后，`archive-confirm` transition 写入 `confirmed`；`archive-reopen` 会清空该字段，防止复用旧确认 |
 | `archived` | change 是否已归档 |
 
 ## 可选字段
@@ -70,4 +72,5 @@ archived: false
 - `build_mode: direct` 默认只允许 `hotfix` / `tweak`；full workflow 需要 `direct_override: true`
 - `build_pause` 不是执行方式，不得写入 `build_mode`
 - 这些约束同时存在于 `comet-guard.mjs build --apply` 和 `comet-state.mjs transition <name> build-complete`
+- `archive_confirmation` 是 machine-owned 字段，只能由 `verify-pass`、`archive-confirm` 和 `archive-reopen` transition 更新，不能通过 `set` 直接伪造确认；`archived` transition 和真实归档命令都要求其值为 `confirmed`
 - `preset-escalate` 事件：仅允许 `hotfix`/`tweak` workflow 在 `phase: build` 时调用，原子地把 `workflow`/`classic_profile` 置为 `full`、`phase` 回退到 `design`、清空 `design_doc`（满足 comet-design 入口要求）。这是预设升级到 full 的唯一合法通道——直接 `set phase design` 会被状态机硬拦截，`set classic_profile` 属于 machine-owned 字段不可手动设置

assets/skills/comet-archive/SKILL.md

@@ -38,22 +38,28 @@ Before confirmation, show the user a brief summary:
 - Irreversible actions this archive will perform: merge main specs with OpenSpec delta semantics, annotate design doc / plan, and move the change to the archive directory
 
 The user confirmation question must be presented as a single-select question with these options:
-- "Confirm archive" — immediately run the archive script to complete spec merge and change movement
+- "Confirm archive" — record the final confirmation state, then run the archive script to complete spec merge and change movement
 - "Needs adjustment or re-verification" — do not archive; run `node "$COMET_STATE" transition <change-name> archive-reopen` to return to `phase: verify`, then invoke `/comet-verify`. If verification confirms fixes are needed, follow `/comet-verify`'s verification-failure decision flow back to `/comet-build`
 - "Do not archive yet" — do not archive; keep the current `phase: archive` state and wait for the user to invoke `/comet-archive` again later
 
-Only after the user selects "Confirm archive" may Step 2 continue. After the user selects "Needs adjustment or re-verification", must first run the `archive-reopen` state transition; do not edit `.comet.yaml` manually.
+After the user selects "Confirm archive", immediately run:
+
+```bash
+node "$COMET_STATE" transition <change-name> archive-confirm
+```
+
+If the transition returns a non-zero exit code, report the error and stop. Only after the transition succeeds may Step 2 continue. After the user selects "Needs adjustment or re-verification", must first run the `archive-reopen` state transition; do not edit `.comet.yaml` manually.
 
 ### 2. Execute Archive
 
-Run the archive script to automatically complete all steps:
+Run the archive script:
 
 ```bash
 node "$COMET_ARCHIVE" "<change-name>"
 ```
 
 The script automatically executes:
-1. Entry state validation (phase=archive, verify_result=pass, archived=false)
+1. Entry state validation (phase=archive, verify_result=pass, archive_confirmation=confirmed, archived=false)
 2. Design doc frontmatter annotation (archived-with, status)
 3. Plan frontmatter annotation (archived-with)
 4. OpenSpec archive for delta-merge semantics and moving the change to the archive directory

assets/skills/comet/reference/comet-yaml-fields.md

@@ -27,6 +27,7 @@ verification_report: null
 branch_status: pending
 created_at: 2026-05-26
 verified_at: null
+archive_confirmation: null
 archived: false
 ```
 
@@ -53,6 +54,7 @@ archived: false
 | `branch_status` | `pending` or `handled`; set to `handled` after branch handling completes |
 | `created_at` | Change creation date (auto-written at init), format `YYYY-MM-DD` |
 | `verified_at` | Verification pass timestamp; may be empty |
+| `archive_confirmation` | `null`, `pending`, or `confirmed`. `verify-pass` writes `pending` when entering the archive phase; after the user selects "Confirm archive" in `/comet-archive`, the `archive-confirm` transition writes `confirmed`; `archive-reopen` clears the field so an earlier confirmation cannot be reused |
 | `archived` | Whether the change has been archived |
 
 ## Optional Fields
@@ -71,4 +73,5 @@ archived: false
 - `build_mode: direct` defaults to `hotfix`/`tweak` only; full workflow requires `direct_override: true`
 - `build_pause` is not an execution mode; must not be written to `build_mode`
 - These constraints exist in both `comet-guard.mjs build --apply` and `comet-state.mjs transition <name> build-complete`
+- `archive_confirmation` is machine-owned and can only be updated by the `verify-pass`, `archive-confirm`, and `archive-reopen` transitions; it cannot be forged with `set`, and both the `archived` transition and the mutating archive command require `confirmed`
 - `preset-escalate` event: only allows `hotfix`/`tweak` workflow at `phase: build`; atomically sets `workflow`/`classic_profile` to `full`, rewinds `phase` to `design`, and clears `design_doc` (satisfying the comet-design entry requirement). This is the only legal channel for a preset → full upgrade — direct `set phase design` is hard-blocked by the state machine, and `set classic_profile` is a machine-owned field that cannot be set manually