@rpamis/comet 0.4.0-beta.3 → 0.4.0-beta.4

package/README.md

@@ -14,6 +14,7 @@
   <a href="https://www.npmjs.com/package/@rpamis/comet"><img alt="npm version" src="https://img.shields.io/npm/v/@rpamis/comet?style=flat-square" /></a>
   <a href="https://www.npmjs.com/package/@rpamis/comet"><img alt="npm download count" src="https://img.shields.io/npm/dm/@rpamis/comet?style=flat-square&label=Downloads/mo" /></a>
   <a href="https://www.npmjs.com/package/@rpamis/comet"><img alt="npm weekly download count" src="https://img.shields.io/npm/dw/@rpamis/comet?style=flat-square&label=Downloads/wk" /></a>
+  <a href="https://docs.comet.rpamis.com/"><img alt="Comet Docs" src="https://img.shields.io/badge/Docs-docs.comet.rpamis.com-FFD700?style=flat-square" /></a>
   <a href="./LICENSE"><img alt="License: MIT" src="https://img.shields.io/badge/License-MIT-blue.svg?style=flat-square" /></a>
 </p>
 
@@ -210,6 +211,15 @@ and diagnostic recovery hints when a change is malformed or missing required evi
 
 </details>
 
+<details>
+<summary><code>comet resume-probe [path]</code> — Decide whether an active Comet workflow should resume</summary>
+
+Read-only probe for active changes, `.comet.yaml`, current phase, and the user request. It returns `auto_resume`,
+`ask_user`, `out_of_scope`, or `none`. `comet init/update` merges a `<comet-ambient-resume>` managed block into
+`AGENTS.md` and `CLAUDE.md` while preserving user-authored rules.
+
+</details>
+
 <details>
 <summary><code>comet dashboard [path]</code> — Launch local read-only dashboard server</summary>
 

package/assets/manifest.json

@@ -1,5 +1,5 @@
 {
-  "version": "0.4.0-beta.3",
+  "version": "0.4.0-beta.4",
   "skills": [
     "comet/SKILL.md",
     "comet/reference/auto-transition.md",
@@ -32,6 +32,7 @@
     "comet/scripts/comet-yaml-validate.mjs",
     "comet/scripts/comet-hook-guard.mjs",
     "comet/scripts/comet-intent.mjs",
+    "comet/scripts/comet-resume-probe.mjs",
     "comet-open/SKILL.md",
     "comet-design/SKILL.md",
     "comet-build/SKILL.md",

package/assets/skills/comet/SKILL.md

@@ -22,7 +22,7 @@ Agents need only read this section for decision-making. Refer to the Reference A
 
 ### Output Language Rule
 
-Use the configured Comet artifact language as the output language for every OpenSpec and Superpowers artifact. The configured value is a normalized language id, `en` or `zh-CN`. For an existing change, read `language` from `openspec/changes/<name>/.comet.yaml` using `"$COMET_BASH" "$COMET_STATE" get <name> language`. Before `.comet.yaml` exists, read `language` from `.comet/config.yaml`; if neither exists, fall back to the current user request language. Include the resolved language explicitly in every prompt or ARGUMENTS passed to external OpenSpec/Superpowers skills.
+Use the configured Comet artifact language as the output language for every OpenSpec and Superpowers artifact. The configured value is a normalized language id, `en` or `zh-CN`. For an existing change, read `language` from `openspec/changes/<name>/.comet.yaml` using `"$COMET_BASH" "$COMET_STATE" get <name> language`. Before `.comet.yaml` exists, read `language` from project `.comet/config.yaml`, then fall back to global `~/.comet/config.yaml`; if neither exists, fall back to the current user request language. Include the resolved language explicitly in every prompt or ARGUMENTS passed to external OpenSpec/Superpowers skills.
 
 ### Automatic Phase Detection
 
@@ -40,6 +40,30 @@ Use the configured Comet artifact language as the output language for every Open
    - `ask_user` → pause through `comet/reference/decision-point.md` and wait for the user's choice
    - `out_of_scope` → explain that the input is not a Comet workflow start/resume request and do not initialize a change
 
+After the runtime route, Ambient Resume, or user choice resolves one explicit change, bind the current execution context before entering its phase Skill:
+
+```bash
+comet state select <change-name>
+```
+
+When multiple active changes exist and the user has not selected one, do not bind early; keep the existing `ask_user` decision point.
+
+### Comet Ambient Resume
+
+When the user did not explicitly invoke `/comet`, but this repository may already have an active Comet change, run the read-only probe before starting work that may need code changes or investigation:
+
+```bash
+node "$COMET_RESUME_PROBE" probe --stdin
+```
+
+The probe only reads repository state. Follow the returned action:
+
+- `auto_resume`: print one line, `[COMET] Detected active change <name>; resuming via <nextCommand>.`, then enter `nextCommand`.
+- `ask_user`: ask one short question and wait.
+- `out_of_scope` or `none`: do not enter the Comet workflow.
+
+Never attach unrelated work to an active Comet change only because `.comet.yaml` exists.
+
 **Minimal CometIntentFrame Skeleton**:
 
 ```json

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

@@ -3,7 +3,7 @@
 Canonical path: `comet/reference/comet-yaml-fields.md`
 
 This file is the field reference for each change-level `.comet.yaml` state file under `openspec/changes/<name>/`.
-Consult on demand; not loaded inline with skills. Project defaults live in `.comet/config.yaml`.
+Consult on demand; not loaded inline with skills. Project defaults live in `.comet/config.yaml`, global defaults live in `~/.comet/config.yaml`, and project values take precedence.
 
 ## Example
 
@@ -27,6 +27,7 @@ verification_report: null
 branch_status: pending
 created_at: 2026-05-26
 verified_at: null
+archive_confirmation: null
 archived: false
 ```
 
@@ -35,7 +36,7 @@ archived: false
 | Field | Meaning |
 |-------|---------|
 | `workflow` | `full`, `hotfix`, or `tweak` |
-| `language` | Artifact language, `en` or `zh-CN`. Written to `.comet/config.yaml` by `comet init`, snapshotted into `.comet.yaml` when a change is created, and used as the main-language constraint for OpenSpec / Superpowers artifacts |
+| `language` | Artifact language, `en` or `zh-CN`. Written to the project or global `.comet/config.yaml` according to install scope, snapshotted into `.comet.yaml` with project-over-global precedence when a change is created, and used as the main-language constraint for OpenSpec / Superpowers artifacts |
 | `phase` | Current phase: `open`, `design`, `build`, `verify`, `archive` (init sets `open`; guard handles transitions) |
 | `design_doc` | Associated Superpowers Design Doc path; may be empty |
 | `plan` | Associated Superpowers Plan path; may be empty |
@@ -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

package/assets/skills/comet/reference/context-recovery.md

@@ -14,6 +14,16 @@ node "$COMET_STATE" check <change-name> <phase> --recover
 
 If the check shows the actual phase, workflow, or evidence belongs to another skill, switch according to script output and `/comet` routing rules; do not keep writing state in the wrong phase. If the worktree has uncommitted changes, attribute them first via `comet/reference/dirty-worktree.md`.
 
+## Recovery Without Explicit `/comet`
+
+If the user did not mention `/comet`, but this repository may have an active change, run the Ambient Resume probe before starting work that may need code changes or investigation. First locate scripts via `comet/reference/scripts.md` and ensure `$COMET_RESUME_PROBE` is available, then pass the current user request on stdin:
+
+```bash
+node "$COMET_RESUME_PROBE" probe --stdin
+```
+
+Only `auto_resume` should resume automatically; `ask_user` must ask one short question; `out_of_scope` and `none` do not enter the workflow.
+
 ## Recovery Steps
 
 ```bash

package/assets/skills/comet/reference/scripts.md

@@ -1,12 +1,30 @@
-# Script Location and Commands
+# Stable CLI and Internal Script Compatibility
 
 Canonical path: `comet/reference/scripts.md`
 
-This file is the single source of truth for locating Comet scripts and the state/guard/handoff/archive command surface. Load it once per session, then reuse the cached env vars.
+This file is the single source of truth for Comet's public CLI and internal script compatibility. Public workflows must prefer the stable command surface: `comet state`, `comet guard`, `comet handoff`, and `comet archive`.
 
-## Bootstrap (run once per session)
+## Public Workflow Contract
 
-Comet scripts are distributed in `comet/scripts/`. **Do not hardcode paths** — locate once, cache in env vars. Sub-skills may reference this section directly and only inline this block when they must be fully self-contained; this file is the single source of truth for updates:
+Normal installations and everyday workflows use the `comet` CLI directly. They do not need to locate launchers and must not expose the internal `classic` name to users:
+
+```bash
+comet state select <change-name>
+comet state current
+comet state clear-selection
+comet state check <change-name> <phase>
+comet guard <change-name> <phase> --apply
+comet handoff <change-name>
+comet archive <change-name>
+```
+
+When multiple active changes coexist, run `comet state select <change-name>` after resolving the intended change. Ordinary source writes are governed only by that selection; without one, the hook blocks and asks for a choice. A single active change retains automatic routing. Select again after switching branch/worktree or when the recorded selection becomes stale.
+
+Guard `--apply` advances state after checks pass. Use `comet state transition` when expressing a state event directly, and `comet state next` after phase advancement to determine whether to invoke the next Skill automatically.
+
+## Compatibility, Recovery, and Internal Command Bootstrap
+
+The script discovery below is only for legacy compatibility, recovery when the CLI is unavailable, and internal `/comet` entry commands. Normal public workflows must not prefer it. Comet scripts are distributed in `comet/scripts/`; recovery code must locate them once and cache environment variables instead of hardcoding paths:
 
 ```bash
 COMET_ENV="${COMET_ENV:-$(find . "$HOME"/.*/skills "$HOME/.config" "$HOME/.gemini" -path '*/comet/scripts/comet-env.mjs' -type f -print -quit 2>/dev/null)}"
@@ -20,6 +38,7 @@ COMET_GUARD="$COMET_SCRIPTS_DIR/comet-guard.mjs"
 COMET_HANDOFF="$COMET_SCRIPTS_DIR/comet-handoff.mjs"
 COMET_ARCHIVE="$COMET_SCRIPTS_DIR/comet-archive.mjs"
 COMET_INTENT="$COMET_SCRIPTS_DIR/comet-intent.mjs"
+COMET_RESUME_PROBE="$COMET_SCRIPTS_DIR/comet-resume-probe.mjs"
 
 # Stop workflow when script location fails
 if [ -z "$COMET_SCRIPTS_DIR" ]; then
@@ -28,34 +47,47 @@ if [ -z "$COMET_SCRIPTS_DIR" ]; then
 fi
 ```
 
-After loading comet, agents should run this bootstrap block once, then reuse `$COMET_GUARD`, `$COMET_STATE`, `$COMET_HANDOFF`, `$COMET_ARCHIVE`, and `$COMET_INTENT` throughout the session.
+Agents run this bootstrap only when entering one of the compatibility, recovery, or internal-command paths above. `COMET_INTENT` and `COMET_RESUME_PROBE` remain necessary for internal entry routing and must not be removed globally.
+
+| Variable | Purpose |
+|----------|---------|
+| `COMET_STATE` | `.comet.yaml` state reads/writes, phase checks, and recovery context |
+| `COMET_GUARD` | Phase exit guard and `--apply` state advancement |
+| `COMET_HANDOFF` | Design/Build handoff context pack generation |
+| `COMET_ARCHIVE` | One-command archive and main spec sync |
+| `COMET_INTENT` | `/comet` entry intent recognition and route scoring |
+| `COMET_RESUME_PROBE` | Read-only Ambient Resume probe that decides whether to resume an active Comet workflow |
 
 ## Auto state update
 
 Guard supports `--apply` flag, automatically updating `.comet.yaml` state fields after checks pass:
 
 ```bash
-node "$COMET_GUARD" <change-name> <phase> --apply
+comet guard <change-name> <phase> --apply
 ```
 
-`--apply` delegates to `comet-state transition`. Use these semantic events when state changes need to be expressed directly:
+`--apply` delegates to the state-machine transition. Use these semantic events when state changes need to be expressed directly:
 
 ```bash
-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
+comet state transition <change-name> open-complete
+comet state transition <change-name> design-complete
+comet state transition <change-name> build-complete
+comet state transition <change-name> verify-pass
+comet state transition <change-name> verify-fail
+comet state transition <change-name> archive-confirm
+comet state transition <change-name> archive-reopen
+comet state transition <change-name> archived
+comet state transition <change-name> preset-escalate
 ```
 
-Archive completion is handled by `node "$COMET_ARCHIVE" <change-name>` after OpenSpec moves the change into its date-prefixed archive directory; do not manually transition an `<archive-name>`.
+Archive completion is handled by `comet archive <change-name>` after OpenSpec moves the change into its date-prefixed archive directory. Use `archive-confirm` or `archive-reopen` for the pre-archive decision, and do not manually run the `archived` transition outside that flow.
 
 ## Resolve next action
 
 After guard-based phase advancement, use the `next` subcommand to determine whether to auto-invoke the next skill:
 
 ```bash
-node "$COMET_STATE" next <change-name>
+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 block phase updates.
@@ -65,5 +97,5 @@ Output format: `NEXT: auto|manual|done` + `SKILL: <skill-name>` (omitted for `do
 Complete all archive steps in one command:
 
 ```bash
-node "$COMET_ARCHIVE" <change-name>
+comet archive <change-name>
 ```

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

@@ -10,6 +10,14 @@
 
 When there is an active comet change (`openspec/changes/<name>/.comet.yaml` exists), **before starting any operation** you must read the `phase` field to confirm the current phase.
 
+When multiple active changes exist, resolve the current change first, then run:
+
+```bash
+comet state select <change-name>
+```
+
+Ordinary source writes are governed only by the selected change phase. With multiple active changes and no valid selection, the Hook must block and ask for a choice; it must not guess alphabetically or let an unrelated open, design, or archive change globally block a legal build. A single active change may retain automatic routing.
+
 **Phases and allowed operations:**
 
 | Phase | Allowed | Prohibited |

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

@@ -10,6 +10,14 @@
 
 有活跃 comet change 时（`openspec/changes/<name>/.comet.yaml` 存在），**每次开始执行操作前**必须读取 `phase` 字段确认当前阶段。
 
+当存在多个 active change 时，必须先明确当前 change，再运行：
+
+```bash
+comet state select <change-name>
+```
+
+普通源码写入只受已选择 change 的阶段约束。多个 active change 且没有有效选择时，Hook 必须阻塞并提示选择；不得按字母序猜测，也不得让无关 change 的 `open`、`design` 或 `archive` 阶段全局封锁合法 build。单 active change 无选择时可保持自动归属。
+
 **阶段与允许操作：**
 
 | 阶段 | 允许 | 禁止 |
@@ -32,7 +40,7 @@ Hook 硬拦截白名单包括 `openspec/*`、`docs/superpowers/*`、`.superpower
 | `phase: build` + proposal/design/tasks 任一缺失或为空 | 绕过 open 空跳 | 回 `/comet-open` 补齐三件套 |
 | `phase: archive` + `verify_result` ≠ `pass` | 绕过 verify 空跳 | 回 `/comet-verify` 完成验证 |
 
-> 说明：上表只覆盖 hook 硬门实际检测的范围（`design_doc` 空跳在 build 阶段；proposal/design/tasks 三件套完整性在 open→build 的 guard 退出时校验）。`verify` 阶段不在此写源码自洽门内——若 verify 发现产物缺失，按下方「Verify 阶段专项」的 verify-fail 回退处理。
+> 说明：上表只覆盖 hook 硬拦截实际检测的范围（`design_doc` 空跳在 build 阶段；proposal/design/tasks 三件套完整性在 open→build 的 guard 退出时校验）。`verify` 阶段不在此写源码自洽检查内——若 verify 发现产物缺失，按下方「Verify 阶段专项」的 verify-fail 回退处理。
 
 预设例外：`workflow: hotfix/tweak` 本就跳过 design，`design_doc` 为空属正常，不算非法。
 

package/assets/skills/comet/scripts/comet-resume-probe.mjs

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+import { main } from './comet-runtime.mjs';
+process.exitCode = await main(["resume-probe", ...process.argv.slice(2)]);