@rpamis/comet 0.3.0 → 0.3.1

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

@@ -16,9 +16,9 @@ Quick bug fix workflow: open → build → verify → archive. Skip brainstormin
 
 ---
 
-## Process (preset workflow, 4 phases)
+## Process (preset workflow, 5 steps)
 
-Execution chain: open → build → verify → archive. Hotfix provides default decisions for each phase: streamlined open, direct build, scale-based verification, archive after verification passes.
+Execution chain: open → build → root cause check → verify → archive. Hotfix provides default decisions for each phase: streamlined open, direct build, root cause confirmation, scale-based verification, archive after verification passes.
 
 Locate Comet scripts before starting:
 
@@ -75,33 +75,34 @@ Before continuing or starting changes, handle uncommitted changes through `comet
    - Check corresponding `- [ ]` to `- [x]` in tasks.md
    - Commit code, commit message format: `fix: <brief fix description>`
 3. After all tasks complete, explicitly run relevant project tests and build commands
-4. Run phase guard to transition build → verify:
-
-```bash
-bash "$COMET_GUARD" <change-name> build --apply
-```
-
-State automatically updates to `phase: verify`, `verify_result: pending`, then enter verification.
 
 **If fix affects existing spec acceptance scenarios**:
 - Create delta spec in `openspec/changes/<name>/specs/<capability>/spec.md`
 - Only include `## MODIFIED Requirements` section
 
-### 3a. Hotfix-Exclusive Check: Root Cause Elimination
+### 3. Root Cause Elimination Check
 
-**Execute before loading comet-verify**, ensuring the fix actually eliminates the root cause:
+**Execute before running build guard**, ensuring the fix actually eliminates the root cause:
 
 1. Read bug description and root cause in proposal.md
 2. Search and verify problem code no longer exists
-3. If root cause not eliminated, return to Step 2 to continue fix
+3. If root cause not eliminated, return to Step 2 to continue fix (still in build phase, no state transition needed)
 
 **Upgrade conditions**:
-- Root cause check reveals deep architecture issues → Stop hotfix, upgrade to `/comet`
-- Fix requires additional interface changes → Stop hotfix, upgrade to `/comet`
+- Root cause check reveals deep architecture issues → Stop hotfix, handle per "Upgrade Conditions" section
+- Fix requires additional interface changes → Stop hotfix, handle per "Upgrade Conditions" section
 
-### 3b. Verification (preset verify)
+After root cause is confirmed eliminated, run phase guard to transition build → verify:
 
-After root cause elimination check passes, reuse `/comet-verify`, with comet-verify's scale assessment deciding lightweight or full verification.
+```bash
+bash "$COMET_GUARD" <change-name> build --apply
+```
+
+State automatically updates to `phase: verify`, `verify_result: pending`, then enter verification.
+
+### 4. Verification (preset verify)
+
+Reuse `/comet-verify`, with comet-verify's scale assessment deciding lightweight or full verification.
 
 **Immediately execute:** Use the Skill tool to load the `comet-verify` skill. Skipping this step is prohibited.
 
@@ -109,7 +110,7 @@ Small-scale hotfixes without delta spec usually meet lightweight verification co
 
 After verification passes, record `.comet.yaml` `verify_result` as `pass` according to `/comet-verify` rules, must not skip this status before archiving.
 
-### 4. Archive (preset archive)
+### 5. Archive (preset archive)
 
 Reuse `/comet-archive`. Must satisfy `verify_result: pass` in `.comet.yaml` before archiving.
 
@@ -121,11 +122,15 @@ If there is delta spec, sync to main spec according to comet-archive rules, and
 ## Continuous Execution Mode
 
 <IMPORTANT>
-Hotfix workflow is **one-time continuous execution**. After invoking `/comet-hotfix`, agent must automatically complete all 4 phases, without pausing to wait for user input mid-way (unless encountering upgrade conditions requiring user confirmation).
+Hotfix workflow is **one-time continuous execution**. After invoking `/comet-hotfix`, agent must automatically advance through hotfix steps, without pausing to wait for user input mid-way. But the following situations must pause and wait for user confirmation:
 
-Execution order: quick open → direct build → verification → archive → complete
+1. Encountering upgrade conditions (see "Upgrade Conditions" section)
+2. When tasks exceed 3 and transfer to `/comet-build` for workspace isolation and execution method selection
+3. Verification phase (comet-verify) verification failure decision and branch handling decision
 
-After each phase completes, immediately enter next phase, no need for user input again. Within each phase, must still call corresponding Comet/OpenSpec/Superpowers skill according to above requirements.
+Execution order: quick open → direct build → root cause check → verification → archive → complete
+
+After each step completes, immediately enter next step. Within each phase, must still call corresponding Comet/OpenSpec/Superpowers skill according to above requirements; if the called skill has its own user decision points, follow that skill's rules.
 </IMPORTANT>
 
 ---
@@ -142,7 +147,15 @@ Upgrade to full `/comet` when **any** of the following conditions are met:
 | Introduces new public API | Fix creates new external interface |
 | Fix scope exceeds single function/module | Requires coordinated changes |
 
-Upgrade method: On current change basis, supplement Design Doc (execute `/comet-design`), then proceed normally with full workflow.
+When upgrade conditions are met, must pause and wait for user to explicitly confirm upgrade to full `/comet` workflow. Must not directly enter `/comet-design`, must not automatically supplement Design Doc.
+
+After user confirms upgrade, **must first update the workflow field** before entering full flow:
+
+```bash
+bash "$COMET_STATE" set <name> workflow full
+```
+
+Then on current change basis, supplement Design Doc: **immediately use Skill tool to load `comet-design` skill**, proceed normally with full workflow. If user does not confirm upgrade, stop hotfix and report that current change has exceeded hotfix scope.
 
 ---
 

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

@@ -1,40 +1,25 @@
 ---
 name: comet-open
-description: "Comet Phase 1: Open. Invoke with /comet-open. Explore ideas through OpenSpec and create change structure (proposal + design + tasks)."
+description: "Comet Phase 1: Open. Invoke with /comet-open. Explore ideas through OpenSpec, create change structure (proposal + design + tasks)."
 ---
 
 # Comet Phase 1: Open
 
 ## Prerequisites
 
-- No active change, or user wishes to create a new change
+- No active change, or user wants to create a new change
 
 ## Steps
 
-### 0. Locate Comet Scripts
-
-Locate scripts before creating state:
-
-```bash
-COMET_SEARCH_ROOTS=("." "$HOME/.claude/skills" "$HOME/.codex/skills" "$HOME/.cursor/skills")
-COMET_STATE="${COMET_STATE:-$(find "${COMET_SEARCH_ROOTS[@]}" -path '*/comet/scripts/comet-state.sh' -type f -print -quit 2>/dev/null)}"
-COMET_GUARD="${COMET_GUARD:-$(find "${COMET_SEARCH_ROOTS[@]}" -path '*/comet/scripts/comet-guard.sh' -type f -print -quit 2>/dev/null)}"
-
-if [ -z "$COMET_STATE" ] || [ -z "$COMET_GUARD" ]; then
-  echo "ERROR: Comet scripts not found. Ensure the comet skill is installed." >&2
-  return 1
-fi
-```
-
-### 1. Explore Idea
+### 1. Explore Ideas
 
 **Immediately execute:** Use the Skill tool to load the `openspec-explore` skill. Skipping this step is prohibited.
 
 After the skill loads, freely explore the problem space following its guidance.
 
-### 2. Create Change Structure
+### 2. Create Change Structure + Initialize State
 
-**Immediately execute:** Use the Skill tool to load the `openspec-new-change` skill. If user intent is unclear and needs to form a proposal first, load `openspec-propose` instead. Skipping this step is prohibited.
+**Immediately execute:** Use the Skill tool to load the `openspec-new-change` skill. If the user's intent is unclear and needs proposal formation first, load `openspec-propose` instead. Skipping this step is prohibited.
 
 Confirm the following artifacts have been created:
 
@@ -43,40 +28,59 @@ openspec/changes/<name>/
 ├── .openspec.yaml
 ├── .comet.yaml
 ├── proposal.md       # Why + What: problem, goals, scope
-├── design.md         # How (high-level): architectural decisions, solution selection
+├── design.md         # How (high-level): architecture decisions, approach selection
 └── tasks.md          # Task checklist (checkboxes)
 ```
 
-### 3. Initialize Comet State
-
-Initialize Comet state file:
+Create `.comet.yaml` state file:
 
 ```bash
+COMET_SEARCH_ROOTS=("." "$HOME/.claude/skills" "$HOME/.codex/skills" "$HOME/.cursor/skills")
+COMET_STATE="${COMET_STATE:-$(find "${COMET_SEARCH_ROOTS[@]}" -path '*/comet/scripts/comet-state.sh' -type f -print -quit 2>/dev/null)}"
+COMET_GUARD="${COMET_GUARD:-$(find "${COMET_SEARCH_ROOTS[@]}" -path '*/comet/scripts/comet-guard.sh' -type f -print -quit 2>/dev/null)}"
+
+if [ -z "$COMET_STATE" ] || [ -z "$COMET_GUARD" ]; then
+  echo "ERROR: Comet scripts not found. Ensure the comet skill is installed." >&2
+  return 1
+fi
+
 bash "$COMET_STATE" init <name> full
 ```
 
+### 3. Entry State Verification
+
+Verify state machine has been correctly initialized:
+
+```bash
+bash "$COMET_STATE" check <name> open
+```
+
+Proceed to Step 4 after verification passes. The script outputs specific failure reasons when verification fails.
+
 ### 4. Content Completeness Check
 
 Confirm the three documents have complete content:
 - **proposal.md**: problem background, goals, scope, non-goals
-- **design.md**: high-level architectural decisions, solution selection, data flow
+- **design.md**: high-level architecture decisions, approach selection, data flow
 - **tasks.md**: task list, each task has a clear description
 
 ## Exit Conditions
 
-- proposal.md, design.md, and tasks.md are all created with complete content
-- **Phase guard**: Run `bash "$COMET_GUARD" <change-name> open --apply`; after all PASS, state automatically advances to the next phase
+- proposal.md, design.md, tasks.md all created with complete content
+- **Phase guard**: Run `bash "$COMET_GUARD" <change-name> open --apply`; after all PASS, auto-transitions to next phase
 
-You must use `--apply` before exiting. Otherwise `.comet.yaml` stays at `phase: open`, and the next phase entry check will fail.
+Must use `--apply` before exit, otherwise `.comet.yaml` remains at `phase: open` and the next phase entry check will fail.
 
 ```bash
 bash "$COMET_GUARD" <change-name> open --apply
 ```
 
-Full workflow advances to `phase: design`; hotfix/tweak presets advance to `phase: build`.
+Full workflow auto-transitions to `phase: design`; hotfix/tweak presets auto-transition to `phase: build`.
 
 ## Automatic Transition
 
 After exit conditions are met, **proceed immediately to the next phase without waiting for user input**:
 
-> **REQUIRED NEXT SKILL:** Invoke `comet-design` skill to enter the deep design phase.
+> **REQUIRED NEXT SKILL (full workflow):** Invoke `comet-design` skill to enter the deep design phase.
+>
+> Hotfix/tweak presets are controlled by their corresponding preset skill for subsequent transitions (phase goes directly to build), and do not go through this section.

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

@@ -5,17 +5,17 @@ description: "Comet preset path: Non-bug small changes (tweak). Skip brainstormi
 
 # Comet Preset Path: Tweak
 
-Tweak is a preset workflow of Comet's five-phase capabilities, not a separate parallel process. It reuses open, build, verify, archive capabilities, only skipping brainstorming and full plan.
+Tweak is a preset workflow of Comet's five-phase capabilities, not an independent parallel process. It reuses open, build, verify, archive capabilities, only skipping brainstorming and full plan.
 
-Applicable for small-scale non-bug changes, such as copy adjustments, configuration adjustments, documentation or prompt local optimization.
+Applicable for non-bug small scope changes, such as copy adjustment, configuration adjustment, documentation or prompt local optimization.
 
 **Applicable conditions** (all must be met):
 1. No new capability
 2. No architecture changes
-3. No interface changes involved
-4. Usually not exceeding 3 tasks, 4 files
+3. No interface changes
+4. Typically no more than 3 tasks, 4 files
 
-**Not applicable**: If change process discovers need for capability, architecture, or interface adjustments, should upgrade to full `/comet` workflow.
+**Not applicable**: If change process discovers need for capability, architecture or interface adjustments, should upgrade to full `/comet` workflow.
 
 ---
 
@@ -41,8 +41,8 @@ Reuse Comet open capability to create change, but use tweak defaults: do not exe
 After the skill loads, follow its guidance to create streamlined artifacts:
   - `proposal.md` — change motivation + goals + scope
   - `design.md` — brief implementation description (no solution comparison needed)
-  - `tasks.md` — not exceeding 3 tasks
-- **No delta spec needed** (unless change changes existing spec acceptance scenarios; once delta spec needed, upgrade to full `/comet`)
+  - `tasks.md` — no more than 3 tasks
+- **No delta spec needed** (unless change modifies existing spec acceptance scenarios; once delta spec is needed, upgrade to full `/comet`)
 
 Initialize Comet state file:
 
@@ -66,13 +66,13 @@ bash "$COMET_GUARD" <change-name> open --apply
 
 Use tweak defaults: `build_mode: direct`. Skip `superpowers:brainstorming` and `superpowers:writing-plans`.
 
-Before continuing or starting changes, handle uncommitted changes through `comet/reference/dirty-worktree.md`. If attribution shows the scope exceeds tweak, handle it through this file's "Upgrade Conditions".
+Before continuing or starting changes, handle uncommitted changes through `comet/reference/dirty-worktree.md`. If attribution shows scope exceeds tweak, handle it through this file's "Upgrade Conditions".
 
 **Immediately execute:** Execute tasks one by one according to tasks.md:
 
 1. Read `openspec/changes/<name>/tasks.md`, get incomplete task list
 2. For each incomplete task:
-   - Modify target file according to task description
+   - Modify target files according to task description
    - Run project formatter (e.g., `mvn spotless:apply`, `npm run format`)
    - Run related tests to confirm pass
    - Check corresponding `- [ ]` to `- [x]` in tasks.md
@@ -92,7 +92,7 @@ Reuse `/comet-verify`. Tweak must maintain lightweight verification conditions:
 
 **Immediately execute:** Use the Skill tool to load the `comet-verify` skill. Skipping this step is prohibited.
 
-If scale assessment enters full verification path, stop tweak, upgrade to full `/comet`.
+If scale assessment enters full verification path, stop tweak, handle per upgrade conditions blocking confirmation.
 
 After verification passes, record `.comet.yaml` `verify_result` as `pass` according to `/comet-verify` rules, must not skip this status before archiving.
 
@@ -107,11 +107,14 @@ Reuse `/comet-archive`. Must satisfy `verify_result: pass` in `.comet.yaml` befo
 ## Continuous Execution Mode
 
 <IMPORTANT>
-Tweak workflow is **one-time continuous execution**. After invoking `/comet-tweak`, agent must automatically complete all 4 phases, without pausing to wait for user input mid-way (unless encountering upgrade conditions requiring user confirmation).
+Tweak workflow is **one-time continuous execution**. After invoking `/comet-tweak`, agent must automatically advance through tweak steps, without pausing to wait for user input mid-way. But the following situations must pause and wait for user confirmation:
+
+1. Encountering upgrade conditions (see "Upgrade Conditions" section)
+2. Verification phase (comet-verify) verification failure decision and branch handling decision
 
 Execution order: quick open → lightweight build → lightweight verification → archive → complete
 
-After each phase completes, immediately enter next phase, no need for user input again. Within each phase, must still call corresponding Comet/OpenSpec/Superpowers skill according to above requirements.
+After each phase completes, immediately enter next phase. Within each phase, must still call corresponding Comet/OpenSpec/Superpowers skill according to above requirements; if the called skill has its own user decision points, follow that skill's rules.
 </IMPORTANT>
 
 ---
@@ -123,13 +126,21 @@ Upgrade to full `/comet` when **any** of the following conditions are met:
 | Condition | Explanation |
 |-----------|-------------|
 | Change involves **5+ files** | Exceeds small change scope |
-| Cross-module coordination required | Needs coordination across components |
-| **5+** new test cases needed | Change complexity increasing |
-| Config item additions or deletions | Non-value config changes |
+| Cross-module coordination required | Requires cross-component coordination |
+| **5+** new test cases needed | Change complexity rising |
+| Config item additions or deletions | Config changes beyond value modifications |
 | New capability needed | Exceeds local optimization |
-| Delta spec needed | Affects existing specifications |
+| Delta spec needed | Affects existing specs |
+
+When upgrade conditions are met, must pause and wait for user to explicitly confirm upgrade to full `/comet` workflow. Must not directly enter `/comet-design`, must not automatically supplement Design Doc.
+
+After user confirms upgrade, **must first update the workflow field** before entering full flow:
+
+```bash
+bash "$COMET_STATE" set <name> workflow full
+```
 
-Upgrade method: On current change basis, supplement Design Doc (execute `/comet-design`), then proceed normally with full workflow.
+Then on current change basis, supplement Design Doc: **immediately use Skill tool to load `comet-design` skill**, proceed normally with full workflow. If user does not confirm upgrade, stop tweak and report that current change has exceeded tweak scope.
 
 ---
 
@@ -137,5 +148,5 @@ Upgrade method: On current change basis, supplement Design Doc (execute `/comet-
 
 - Small change completed, tests pass
 - Change archived
-- No new capability, architecture adjustments, or interface changes
+- No new capability, architecture adjustments or interface changes
 - **Phase guard**: Before build → verify run `bash "$COMET_GUARD" <change-name> build --apply`; before verify → archive follow `/comet-verify` and run `bash "$COMET_GUARD" <change-name> verify --apply`

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

@@ -1,14 +1,14 @@
 ---
 name: comet-verify
-description: "Comet Phase 4: Verify and Complete. Invoke with /comet-verify. Verify implementation matches design, handle development branch."
+description: "Comet Phase 4: Verify and Close. Invoke with /comet-verify. Verify implementation matches design, handle development branch."
 ---
 
-# Comet Phase 4: Verify and Complete (Verify)
+# Comet Phase 4: Verify and Close (Verify)
 
 ## Prerequisites
 
-- Code has been committed (Phase 3 complete)
-- All tasks in tasks.md are complete
+- Code committed (Phase 3 complete)
+- All tasks.md tasks completed
 
 ## Steps
 
@@ -25,7 +25,7 @@ bash "$COMET_STATE" check <change-name> verify
 
 Proceed to Step 1 after verification passes. The script outputs specific failure reasons when verification fails.
 
-### 1. Change Scale Assessment
+### 1. Scale Assessment
 
 Execute scale assessment:
 
@@ -33,21 +33,22 @@ Execute scale assessment:
 bash "$COMET_STATE" scale <change-name>
 ```
 
-Script automatically counts tasks, delta specs, and changed files to determine whether to use light or full verification mode, and sets the verify_mode field.
+The script automatically counts tasks, delta spec count, changed file count, determines light or full verification mode, and sets the verify_mode field.
 
-Before verification starts, inspect and handle uncommitted changes through `comet/reference/dirty-worktree.md`. Verify-specific handling:
+Before verification begins, handle uncommitted changes through `comet/reference/dirty-worktree.md` protocol. Verify phase special handling:
 
-1. If dirty diff belongs to the current change and involves implementation, tests, tasks, delta spec, or design doc changes, do not fix or commit directly in verify; record failure and return to build
-2. If dirty diff is only a verify-phase artifact, such as a verification report draft or branch-handling record, continue in verify and record state
-3. If dirty diff has implemented work but tasks.md is unchecked, treat it as stale build state; record failure and return to build so `/comet-build` verifies the implementation, checks off tasks, and commits
+1. If dirty diff belongs to current change and involves implementation, tests, tasks, delta spec, or design doc changes, do not fix or commit directly in verify phase; report failures and enter Step 1b verification failure decision blocking point
+2. If dirty diff is only verify phase artifacts (e.g., verification report draft, branch handling records), may continue and record state in verify phase
+3. If dirty diff shows implementation but tasks.md not checked, treat as build state lag; report failures and enter Step 1b, let user decide to roll back for fix or accept deviation
 
-Return to build:
+Only after user chooses fix, allow rollback to build phase:
 
 ```bash
+# Execute only after user confirms fix
 bash "$COMET_STATE" transition <change-name> verify-fail
 ```
 
-Note: if the build phase committed after each task, worktree diff can underestimate change size. In that case, read the plan header `base-ref` and re-check the full commit range:
+Note: If every task in build phase was committed, the script's file count based on working tree diff may underestimate change scale. In this case, must read plan file header `base-ref` and verify with commit range:
 
 ```bash
 PLAN=$(bash "$COMET_STATE" get <change-name> plan)
@@ -55,27 +56,41 @@ BASE_REF=$(grep '^base-ref:' "$PLAN" 2>/dev/null | head -1 | sed 's/^base-ref: *
 git diff --stat "$BASE_REF"...HEAD
 ```
 
-If the commit range exceeds lightweight thresholds (> 5 files, cross-module coordination, or more than 1 delta spec capability), manually switch to full verification:
+If commit range shows changes exceed lightweight threshold (> 4 files, cross-module coordination, or delta spec spans more than 1 capability), manually set to full verification:
 
 ```bash
 bash "$COMET_STATE" set <change-name> verify_mode full
 ```
 
+### 1b. Verification Failure Decision (Blocking Point)
+
+When verification does not pass, must pause and wait for the user to decide fix or accept deviation. Must not automatically run `bash "$COMET_STATE" transition <change-name> verify-fail`, nor automatically invoke `/comet-build`.
+
+When pausing, must list:
+- Failed items
+- Whether CRITICAL (build failure, test failure, security issues, core acceptance scenario failure)
+- Recommended handling approach
+
+After user selection, continue as follows:
+- **Fix all**: Run `bash "$COMET_STATE" transition <change-name> verify-fail`, then invoke `/comet-build` to fix
+- **Handle item by item**: CRITICAL failures must be fixed; non-CRITICAL failures may choose to accept deviation, but must record acceptance reason and impact scope in verification report. If any CRITICAL failure exists, skipping fix to accept all is not allowed
+
 ### 2a. Lightweight Verification (Small Changes)
 
-When scale assessment result is "small", skip `openspec-verify-change`, directly execute the following checks:
+When scale assessment result is "small", skip `openspec-verify-change` and directly execute these checks:
 
-1. All tasks in tasks.md completed `[x]`
-2. Changed files consistent with tasks.md description (compare `git diff --stat` / `git diff --cached --stat` / `git diff --stat <base-ref>...HEAD` against task content)
-3. Build passes (run project-appropriate build command, e.g., `npm run build`, `mvn compile`, `cargo build`)
+1. All tasks.md tasks completed `[x]`
+2. Changed files match tasks.md descriptions (`git diff --stat` / `git diff --cached --stat` / `git diff --stat <base-ref>...HEAD` compared against tasks content)
+3. Build passes (run project-specific build command, e.g., `npm run build`, `mvn compile`, `cargo build`, etc.)
 4. Related tests pass
-5. No obvious security issues (no hardcoded secrets, no new unsafe operations)
+5. No obvious security issues (no hardcoded keys, no new unsafe operations)
 
-**Pass standard**: All 5 items OK, no CRITICAL issues.
+**Pass criteria**: All 5 items OK, no CRITICAL issues.
 
-**When failing**: report failed items, record failure, move back to build, then invoke `/comet-build`.
+**When not passing**: Report failures, enter Step 1b verification failure decision blocking point. Only after user confirms fix, execute the following command to record failure and roll back to build phase, then invoke `/comet-build` to fix:
 
 ```bash
+# Execute only after user confirms fix
 bash "$COMET_STATE" transition <change-name> verify-fail
 ```
 
@@ -84,7 +99,7 @@ bash "$COMET_STATE" transition <change-name> verify-fail
 **Skipped items** (not checked in lightweight verification):
 - spec scenario coverage
 - design doc consistency deep comparison
-- code pattern consistency recommendations
+- code pattern consistency suggestions
 - delta spec and design doc drift detection
 
 ### 2b. Full Verification (Large Changes)
@@ -94,49 +109,52 @@ When scale assessment result is "large":
 **Immediately execute:** Use the Skill tool to load the `openspec-verify-change` skill. Skipping this step is prohibited.
 
 After the skill loads, follow its guidance to verify. Check items:
-1. All tasks in tasks.md completed (`[x]`)
-2. Implementation matches design.md design decisions
-3. Implementation matches brainstorming design document
-4. All capability specification scenarios pass
-5. proposal.md goals satisfied
-6. No contradiction between delta spec and design doc (if Build phase had incremental spec modifications, check if design doc has corresponding records)
-7. `docs/superpowers/specs/` associated design document can be located (file exists and relates to current change)
+1. All tasks.md tasks completed (`[x]`)
+2. Implementation matches `openspec/changes/<name>/design.md` high-level design decisions
+3. Implementation matches Design Doc (technical design documents under `docs/superpowers/specs/`)
+4. All capability spec scenarios pass
+5. proposal.md goals are satisfied
+6. No contradictions between delta spec and design doc (if Build phase had incremental spec modifications, check if design doc has corresponding records)
+7. Associated design documents under `docs/superpowers/specs/` are locatable (file exists and is related to current change)
 
-When verification fails: report missing items, record failure, move back to build, then invoke `/comet-build`.
+When verification does not pass: report missing items, enter Step 1b verification failure decision blocking point. Only after user confirms fix, execute the following command to record failure and roll back to build phase, then invoke `/comet-build` to supplement:
 
 ```bash
+# Execute only after user confirms fix
 bash "$COMET_STATE" transition <change-name> verify-fail
 ```
 
-**Spec drift handling**:
-- If check item 6 finds contradiction (delta spec has content but design doc doesn't reflect it), prompt user:
-  - Option A: Append "Implementation Divergence" section to design doc recording deviation reason
-  - Option B: Roll back to Build phase, supplement brainstorming to update design doc
-  - Option C: Confirm deviation acceptable, continue verification (design doc will be marked as `superseded-by-main-spec` during archiving)
+**Spec Drift Handling** (user decision point):
+- If check item 6 finds contradictions (delta spec has content but design doc does not reflect it), **must pause and wait for user to choose handling method**; must not select automatically. Options:
+  - Option A: Append "Implementation Divergence" section to design doc recording deviation reason. Option A is a verify phase allowed artifact; after writing, must not re-trigger Step 1b dirty-worktree decision due to that design doc change
+  - Option B: After user selects B, run `bash "$COMET_STATE" transition <change-name> verify-fail`, then invoke `/comet-build`; `/comet-build`'s Spec Incremental Update rules will load `superpowers:brainstorming` to update Design Doc + delta spec
+  - Option C: Confirm deviation is acceptable, continue verification (design doc will be marked as `superseded-by-main-spec` during archiving)
 
-### 3. Completion (Superpowers)
+### 3. Finishing (Superpowers)
 
 **Immediately execute:** Use the Skill tool to load the `superpowers:finishing-a-development-branch` skill. Skipping this step is prohibited.
 
 If `superpowers:finishing-a-development-branch` is unavailable, stop the process and prompt to install or enable Superpowers skills. Do not substitute this step with normal conversation.
 
-After the skill loads, follow its guidance to complete. Branch handling options:
-1. Local merge to main branch
+After the skill loads, follow its guidance to finish. Branch handling options:
+1. Merge to main branch locally
 2. Push and create PR
 3. Keep branch (handle later)
 4. Discard work
 
+This is a user decision point. **Must pause and wait for user to choose branch handling method**. Must not select based on recommendations, defaults, or current branch status. Only after the user completes selection and the corresponding operation finishes, may `branch_status: handled` be written.
+
 **Confirmation items**:
 - All tests pass
-- No hardcoded secrets or security issues
+- No hardcoded keys or security issues
 
 ### 4. Record Verification Evidence
 
-The verification report must be written to disk and recorded in `.comet.yaml`; branch handling must also be written to state after it completes. Do not manually set `verify_result: pass`; guard performs the transition.
+Verification report must be saved to disk and recorded in `.comet.yaml`; after branch handling completes, state fields must also be written. Do not manually set `verify_result: pass`; use guard for auto-transition.
 
 ```bash
 mkdir -p docs/superpowers/reports
-# Write this verification result to a report file, for example:
+# Write verification conclusions to report file, e.g.:
 # docs/superpowers/reports/YYYY-MM-DD-<change-name>-verify.md
 
 bash "$COMET_STATE" set <change-name> verification_report docs/superpowers/reports/YYYY-MM-DD-<change-name>-verify.md
@@ -147,20 +165,20 @@ bash "$COMET_STATE" set <change-name> branch_status handled
 
 - Verification report passed
 - Branch handled
-- `.comet.yaml` `verification_report` points to an existing verification report file
-- `.comet.yaml` has `branch_status: handled`
-- **Phase guard**: Run `bash "$COMET_GUARD" <change-name> verify --apply`; after all PASS, it uses `comet-state transition verify-pass` to advance to `phase: archive`
+- `verification_report` in `.comet.yaml` points to an existing verification report file
+- `branch_status: handled` in `.comet.yaml`
+- **Phase guard**: Run `bash "$COMET_GUARD" <change-name> verify --apply`; after all PASS, auto-transitions to `phase: archive` through `comet-state transition verify-pass`
 
-After verification and branch handling are complete, run guard to auto-transition:
+After both verification and branch handling are complete, run guard for auto-transition:
 
 ```bash
 bash "$COMET_GUARD" <change-name> verify --apply
 ```
 
-State file is automatically updated to `phase: archive`, `verify_result: pass`, `verified_at: YYYY-MM-DD`.
+State file auto-updates to `phase: archive`, `verify_result: pass`, `verified_at: YYYY-MM-DD`.
 
 ## Automatic Transition
 
 After exit conditions are met, **proceed immediately to the next phase without waiting for user input**:
 
-> **REQUIRED NEXT SKILL:** Invoke `comet-archive` skill to enter the archiving phase.
+> **REQUIRED NEXT SKILL:** Invoke `comet-archive` skill to enter the archive phase.

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

@@ -53,8 +53,8 @@ agent 做决策只需读本节，参考附录按需查阅。
 **断点恢复规则**：
 - 每次恢复上下文时，先重新执行 Step 0 和 Step 1，不依赖对话历史判断阶段
 - 只要存在 active change 且工作区有未提交改动，必须按 `comet/reference/dirty-worktree.md` 协议处理。该协议定义了检查步骤、归因分类和禁令，本文件不重复
-- 若 `phase: build`，读取 tasks.md 的下一个未勾选任务继续
-- 若 `phase: verify` 且 `verify_result: fail`，先运行 `bash "$COMET_STATE" transition <name> verify-fail`，再调用 `/comet-build`
+- 若 `phase: build`，先检查 `build_mode` 和 `isolation` 是否已设置；若有未设置的字段，回到 `/comet-build` 对应步骤补充后再执行；若均已设置，读取 tasks.md 的下一个未勾选任务继续
+- 若 `phase: verify` 且 `verify_result: fail`，进入验证失败决策阻塞点：暂停并询问用户修复或接受偏差；用户选择修复后才运行 `bash "$COMET_STATE" transition <name> verify-fail` 并调用 `/comet-build`
 - 若 `phase: open` 但 proposal/design/tasks 已完整，先运行 `bash "$COMET_GUARD" <change-name> open --apply` 修正状态，再继续判定
 - 若 `phase: archive`，只允许调用 `/comet-archive`；归档成功后 change 会移动到 archive 目录，不再对原活跃目录运行 guard
 
@@ -62,9 +62,9 @@ agent 做决策只需读本节，参考附录按需查阅。
 
 1. `archived: true` 或 change 已移入 archive → 流程已完成
 2. `verify_result: pass` 且 `archived` 不是 `true` → `/comet-archive`
-3. `verify_result: fail` → `bash "$COMET_STATE" transition <name> verify-fail` 后 `/comet-build`
+3. `verify_result: fail` → 进入验证失败决策阻塞点（暂停询问修复或接受偏差；用户选择修复后才 `verify-fail` 并 `/comet-build`）
 4. `phase: verify` 或 tasks.md 全部勾选 → `/comet-verify`
-5. `phase: build` 或已有 Design Doc 但计划/执行未完成 → `/comet-build`
+5. `phase: build` 或已有 Design Doc 但计划/执行未完成 → 优先按 workflow 路由：`hotfix` → `/comet-hotfix`，`tweak` → `/comet-tweak`，`full` → `/comet-build`
 6. `phase: design` 或有 change 但无 Design Doc → `/comet-design`
 7. `phase: open` 或有活跃 change 但 `.comet.yaml` 缺失 → `/comet-open`
 8. 无活跃 change → `/comet-open`
@@ -103,14 +103,17 @@ agent 做决策只需读本节，参考附录按需查阅。
 
 流转链：open → design → build → verify → archive
 
-**连续执行要求**：从检测到的阶段开始，agent 必须自动走完后续所有阶段，中间不停顿等待用户输入（除非遇到需要用户决策的节点）。每个阶段完成后立即进入下一阶段，无需用户再次输入。
+**连续执行要求**：从检测到的阶段开始，agent 必须自动推进后续阶段；自动推进只适用于没有用户决策的衔接点。遇到用户决策点时必须暂停并等待用户明确回复，不得用推荐规则、默认值或历史偏好代替用户确认。
+
+**决策点是阻塞点**：只要到达下列任一节点，当前 `/comet` 调用必须停住。用户明确选择后才能写入对应状态字段、执行对应操作，随后再继续自动流转。
 
 需要用户参与的节点（仅在这些节点暂停）：
 1. brainstorming 确认设计方案
-2. build 阶段选择执行方式
-3. verify 不通过时决定修复或接受偏差
+2. build 阶段选择工作方式（隔离方式 + 执行方式，一次交互完成）
+4. verify 不通过时决定修复或接受偏差（含 Spec 漂移处理方式选择）
 4. finishing-branch 选择分支处理方式
 5. 遇到升级条件（hotfix/tweak → 完整流程）
+6. build 阶段范围扩张需重新设计或拆分新 change
 
 agent 不应跳过这些决策点；其他明确无歧义的阶段衔接必须自动继续推进，不得中途退出。
 </IMPORTANT>
@@ -137,11 +140,11 @@ agent 不应跳过这些决策点；其他明确无歧义的阶段衔接必须
 
 /comet-hotfix（预设路径，跳过 brainstorming）
   open ──→ build ──→ verify ──→ archive
-    ↑ 如触发升级条件 → 补充 Design Doc → 回到完整流程
+    ↑ 如触发升级条件 → 阻塞确认升级 → 补充 Design Doc → 回到完整流程
 
 /comet-tweak（预设路径，跳过 brainstorming 和完整 plan）
   open ──→ lightweight build ──→ light verify ──→ archive
-    ↑ 如触发升级条件 → 补充 Design Doc → 回到完整流程
+    ↑ 如触发升级条件 → 阻塞确认升级 → 补充 Design Doc → 回到完整流程
 ```
 
 ---
@@ -155,12 +158,14 @@ workflow: full
 phase: build
 design_doc: docs/superpowers/specs/YYYY-MM-DD-topic-design.md
 plan: docs/superpowers/plans/YYYY-MM-DD-feature.md
+base_ref: a1b2c3d4e5f6...
 build_mode: subagent-driven-development
 isolation: branch
 verify_mode: light
 verify_result: pending
 verification_report: null
 branch_status: pending
+created_at: 2026-05-26
 verified_at: null
 archived: false
 ```
@@ -171,12 +176,14 @@ archived: false
 | `phase` | 当前阶段：`open`、`design`、`build`、`verify`、`archive`（init 统一设为 `open`，guard 负责过渡） |
 | `design_doc` | 关联的 Superpowers Design Doc 路径，可为空 |
 | `plan` | 关联的 Superpowers Plan 路径，可为空 |
+| `base_ref` | init 时记录的 git commit SHA，用于 scale 评估。无 plan 时作为改动文件数统计基准 |
 | `build_mode` | 已选择的执行方式，可为空 |
 | `isolation` | `branch` 或 `worktree`，工作区隔离方式。full 初始化可为 `null`，但只允许持续到 `/comet-build` Step 3 前；hotfix/tweak 默认 `branch` |
 | `verify_mode` | `light` 或 `full`，可为空 |
 | `verify_result` | `pending`、`pass` 或 `fail` |
 | `verification_report` | 验证报告文件路径，verify 通过前必须指向已存在文件 |
 | `branch_status` | `pending` 或 `handled`，分支处理完成后设为 `handled` |
+| `created_at` | change 创建日期（init 时自动写入），格式 `YYYY-MM-DD` |
 | `verified_at` | 验证通过时间，可为空 |
 | `archived` | change 是否已归档 |