@rpamis/comet 0.3.6 → 0.3.7

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

@@ -16,9 +16,13 @@ Quick bug fix workflow: open → build → verify → archive. Skip brainstormin
 
 ---
 
-## Process (preset workflow, 5 steps)
+## Process (preset workflow, 6 steps)
 
-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.
+### 0. Output Language Constraint
+
+Streamlined OpenSpec artifacts must use the language of the user request that triggered this workflow.
+
+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, and final archive confirmation after verification passes.
 
 Locate Comet scripts before starting:
 
@@ -61,9 +65,18 @@ Run phase guard to transition open → build:
 "$COMET_BASH" "$COMET_GUARD" <change-name> open --apply
 ```
 
+Check `auto_transition` to decide whether to continue:
+
+```bash
+"$COMET_BASH" "$COMET_STATE" next <name>
+```
+
+- `NEXT: auto` → continue to Step 2
+- `NEXT: manual` → pause, follow `HINT` to prompt user to run `/<SKILL>` manually
+
 ### 2. Direct Build (preset build)
 
-Use hotfix defaults: `build_mode: direct`. Skip Superpowers `brainstorming` and `writing-plans` (unless tasks > 3; if exceeds 3 tasks, transfer to `/comet-build`'s plan and execution method selection).
+Use hotfix defaults: `build_mode: direct`. Skip Superpowers `brainstorming` and `writing-plans` (unless tasks > 3; if exceeds 3 tasks, transfer to `/comet-build`'s plan and execution method selection — note this does NOT trigger full workflow upgrade, only switches execution method).
 
 Before continuing or starting changes, handle uncommitted changes through `comet/reference/dirty-worktree.md`. If attribution shows the fix scope exceeds hotfix, handle it through this file's "Upgrade Conditions".
 
@@ -82,6 +95,14 @@ Before continuing or starting changes, handle uncommitted changes through `comet
 - Create delta spec in `openspec/changes/<name>/specs/<capability>/spec.md`
 - Only include `## MODIFIED Requirements` section
 
+During hotfix execution, whenever a crash, unexpected behavior, test failure, or build failure appears while running the program, tests, build, or manual verification, must use the Skill tool to load the Superpowers `systematic-debugging` skill. Before root-cause investigation is complete, must not propose or implement source-code fixes.
+
+Handle it using the four-phase `systematic-debugging` flow:
+- First reproduce and locate the root cause, read full errors, check recent changes, and trace data flow
+- If root cause points to a source bug, first add a minimal failing test that reproduces the crash or unexpected behavior, then modify source code
+- After the fix, run that failing test, related tests, and project build/verification commands to confirm all pass
+- Keep the test, source fix, and tasks.md checkoff inside the current change; must not replace the current change verification loop by starting a separate "write test cases" change
+
 ### 3. Root Cause Elimination Check
 
 **Execute before running build guard**, ensuring the fix actually eliminates the root cause:
@@ -110,11 +131,11 @@ Reuse `/comet-verify`, with comet-verify's scale assessment deciding lightweight
 
 Small-scale hotfixes without delta spec usually meet lightweight verification conditions (≤ 3 tasks, ≤ 2 files), comet-verify's scale assessment will select lightweight verification path (5 quick checks). If hotfix created delta spec, enter full verification path according to comet-verify's scale assessment rules.
 
-After verification passes, record `.comet.yaml` `verify_result` as `pass` according to `/comet-verify` rules, must not skip this status before archiving.
+After verification passes, record `.comet.yaml` `verify_result` as `pass` according to `/comet-verify` rules, must not skip this status before archiving. After verification passes, still enter `/comet-archive`'s final archive confirmation; do not automatically run the archive script.
 
 ### 5. Archive (preset archive)
 
-Reuse `/comet-archive`. Must satisfy `verify_result: pass` in `.comet.yaml` before archiving.
+Reuse `/comet-archive`. Must satisfy `verify_result: pass` in `.comet.yaml` before archiving, and wait for `/comet-archive`'s final archive confirmation.
 
 **Immediately execute:** Use the Skill tool to load the `comet-archive` skill to archive. Skipping this step is prohibited.
 If there is delta spec, sync to main spec according to comet-archive rules, and handle associated Design Doc and Plan archiving annotations.
@@ -124,11 +145,16 @@ 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 advance through hotfix steps, without pausing to wait for user input mid-way. But the following situations must pause and wait for 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.
 
-1. Encountering upgrade conditions (see "Upgrade Conditions" section). **Must use the AskUserQuestion tool to pause and wait for the user to explicitly confirm** upgrading to full workflow
+Exception: when `.comet.yaml` has `auto_transition: false`, after each phase guard advances `phase`, do not auto-invoke the next skill. In this case, use `"$COMET_BASH" "$COMET_STATE" next <name>` output and pause for manual continuation as instructed.
+
+The following situations must also pause and wait for user confirmation:
+
+1. Encountering upgrade conditions (see "Upgrade Conditions" section). **Must use the current platform's available user input/confirmation mechanism to pause and wait for the user to explicitly confirm** upgrading to full workflow
 2. workspace isolation and execution-method selection when tasks exceed 3 and transfer to `/comet-build`
 3. verify phase (comet-verify) verification-failure and branch-handling decisions
+4. Final archive confirmation (before comet-archive runs the archive script)
 
 Execution order: quick open → direct build → root cause check → verification → archive → complete
 
@@ -149,12 +175,13 @@ 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 |
 
-When upgrade conditions are met, **must use the AskUserQuestion tool to pause and wait for the user to explicitly confirm** upgrading to the full `/comet` workflow. Do not directly enter `/comet-design`, and do not automatically supplement Design Doc. Must not just output a text prompt and then continue executing.
+When upgrade conditions are met, **must use the current platform's available user input/confirmation mechanism to pause and wait for the user to explicitly confirm** upgrading to the full `/comet` workflow. Do not directly enter `/comet-design`, and do not automatically supplement Design Doc. If the current platform has no structured question tool, ask an upgrade confirmation question in the conversation, stop the workflow, and wait for the user's reply before continuing.
 
-After user confirms upgrade, **must first update the workflow field** before entering full flow:
+After user confirms upgrade, **must first update the workflow and phase fields** before entering full flow:
 
 ```bash
 "$COMET_BASH" "$COMET_STATE" set <name> workflow full
+"$COMET_BASH" "$COMET_STATE" set <name> phase design
 ```
 
 Then on current change basis, supplement Design Doc: **Immediately use the Skill tool to load the `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.
@@ -167,3 +194,18 @@ Then on current change basis, supplement Design Doc: **Immediately use the Skill
 - Change archived
 - If spec changes, synced to main spec
 - **Phase guard**: Before build → verify run `"$COMET_BASH" "$COMET_GUARD" <change-name> build --apply`; before verify → archive follow `/comet-verify` and run `"$COMET_BASH" "$COMET_GUARD" <change-name> verify --apply`
+
+## Automatic Handoff to Next Phase
+
+> **Terminology distinction**: phase guard `--apply` advances the `.comet.yaml` `phase` field. This step **always happens** and is not controlled by `auto_transition`. This section's "automatic handoff" only controls whether to automatically invoke the next skill.
+
+After each phase guard or state transition advances phase, run:
+
+```bash
+"$COMET_BASH" "$COMET_STATE" next <name>
+```
+
+The script determines the next action from `phase`, `workflow`, and `auto_transition`:
+- `NEXT: auto` -> invoke the `SKILL` target to continue the hotfix flow (`phase: build` returns `comet-hotfix`, `verify` returns `comet-verify`, `archive` returns `comet-archive`)
+- `NEXT: manual` -> do not invoke the next skill; follow `HINT` and ask the user to run `/<SKILL>` manually
+- `NEXT: done` -> workflow is complete; no further action needed

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

@@ -1,6 +1,6 @@
 ---
 name: comet-open
-description: "Comet Phase 1: Open. Invoke with /comet-open. Explore ideas through OpenSpec, create change structure (proposal + design + tasks)."
+description: "Comet Phase 1: Open. Invoke with /comet-open. Explore ideas through OpenSpec, confirm requirements clarification, then create change structure (proposal + design + tasks)."
 ---
 
 # Comet Phase 1: Open
@@ -11,17 +11,81 @@ description: "Comet Phase 1: Open. Invoke with /comet-open. Explore ideas throug
 
 ## Steps
 
-### 1. Explore Ideas
+### 0. Output Language Constraint
+
+Every prompt and artifact request passed to OpenSpec must include the output-language constraint: use the language of the user request that triggered this workflow. When resuming an existing change with a clear dominant artifact language, preserve that language unless the user explicitly asks to switch.
+
+### 1. Explore Ideas and Clarify Requirements
 
 **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.
+After the skill loads, explore the problem space following its guidance, but do not treat one Q&A turn as sufficient clarification. You must continue asking, align with the user, and form a clarification summary covering:
+- Goals: the problem the user truly wants to solve and the expected outcome
+- Non-goals: what is explicitly out of scope for this change
+- Scope boundaries: included/excluded modules, users, platforms, or data
+- Key unknowns: unresolved assumptions, risks, or dependencies
+- Draft acceptance scenarios: at least the core success scenario and important boundary scenarios
+
+The clarification summary must include: goals, non-goals, scope boundaries, key unknowns, and draft acceptance scenarios.
+
+### 1a. PRD Split Preflight (Blocking Point)
+
+When the user input is a large PRD, roadmap, complete product plan, or the clarification summary shows multiple independent capabilities, modules, user journeys, or milestones, must evaluate whether it should be split into multiple changes before creating OpenSpec artifacts.
+
+The split preflight must be based on clarified information and output a proposed split list. Each proposed split item must include:
+- Suggested change name
+- Goals and scope boundaries
+- Explicit non-goals
+- Dependencies or recommended execution order
+- Core acceptance scenarios
+
+Recommend splitting when any condition applies:
+- The PRD contains multiple capabilities that can be independently designed, built, verified, and archived
+- Multiple modules or user journeys are involved, and part of them can be delivered independently
+- Clear phased milestones exist
+- The work is expected to produce multiple delta specs or more than 3 large tasks
+- Failure or delay in one part should not block other parts from entering later phases
+
+When splitting is recommended, must use the current platform's available user input/confirmation mechanism to pause and wait for the user's choice. If the current platform has no structured question tool, ask an equivalent single-select question in the conversation, stop the workflow, and wait for the user's reply before continuing.
+
+The user choices must include:
+- "Create multiple OpenSpec changes" — create independent changes from the proposed split
+- "Keep everything as one change" — continue the single-change flow and record the reason for not splitting in proposal/design/tasks
+- "Adjust the split plan before continuing" — after the user describes the adjustment, output the revised proposed split list and ask for confirmation again
+
+Every accepted split item must be created as an independent change through `/comet-open`, not by calling `/opsx:new` directly. `/comet-open` creates both OpenSpec artifacts and `.comet.yaml`, ensuring each change enters the Comet state machine.
+
+Must not create proposal.md, design.md, or tasks.md before the user completes the PRD split choice. If the user chooses to create multiple changes, the current `/comet-open` invocation only completes split confirmation and coordination, then enters `/comet-open` for each split item in the user-confirmed order.
+
+In batch split mode, entering `/comet-open` for each split item must explicitly mark it as a "confirmed split item" and carry that split item's goals, scope, non-goals, and acceptance scenarios. Confirmed split items skip the PRD split preflight by default, unless the split item itself still clearly contains multiple independent capabilities.
+
+In batch split mode, a single split item must not auto-advance to `/comet-design` after completing the open phase. After splitting is complete, must pause and ask the user which change to start; after the user chooses, advance only that change into `/comet-design`, while other changes remain active and can be resumed later through `/comet`.
+
+Minimal resume rule: do not add a dedicated batch state file. On resume, first check already-created active changes; split items that already exist and contain `.comet.yaml` must not be created again, while uncreated split items continue through `/comet-open` according to the user-confirmed split list. If the confirmed split list cannot be recovered from the conversation, must ask the user to confirm the split list again before continuing.
+
+### 1b. Requirements Clarification Completion Confirmation (Blocking Point)
+
+Before creating OpenSpec artifacts, must use the current platform's available user input/confirmation mechanism to pause and wait for the user to confirm requirements clarification is complete. If the current platform has no structured question tool, present the clarification summary in the conversation, ask a confirmation question, stop the workflow, and wait for the user's reply before continuing.
+
+When pausing, present the clarification summary: goals, non-goals, scope boundaries, key unknowns, and draft acceptance scenarios.
+
+Must not create proposal.md, design.md, or tasks.md before the user confirms requirements clarification is complete, and must not use the Skill tool to load the `openspec-propose` skill to generate all artifacts in one pass.
 
 ### 2. Create Change Structure + Initialize State
 
-**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.
+**Immediately execute:** Use the Skill tool to load the `openspec-new-change` skill. Skipping this step is prohibited.
+
+Full `/comet` workflow must not use the Skill tool to load the `openspec-propose` skill by default; only load it when the user explicitly requests generating the proposal and artifacts in one pass.
+
+After the skill loads, follow its guidance to create the change skeleton, but override its "STOP and wait for user direction" behavior when a confirmed clarification summary from Step 1b is already available in the conversation context. Specifically:
+
+1. Run `openspec new change`, `openspec status`, and `openspec instructions` as the skill directs
+2. If the user has already confirmed a clarification summary (Step 1b), use that summary directly to draft proposal.md — do NOT ask the user to describe the change again
+3. If no clarification summary exists (edge case), fall back to the skill's default behavior of asking the user
 
-**Naming and scope guard**: Change name must use a user-specified or AskUserQuestion-confirmed name — must not auto-generate or infer. Change scope must match the user's description — must not expand or narrow it independently.
+Then fill in design.md and tasks.md one by one; every document must be based on the confirmed clarification summary.
+
+**Naming and scope guard**: Change name must use a user-specified name or a name confirmed through the current platform's available user input/confirmation mechanism — must not auto-generate or infer. Change scope must match the user's description — must not expand or narrow it independently.
 
 Confirm the following artifacts have been created:
 
@@ -75,9 +139,9 @@ Confirm the three documents have complete content:
 
 ### 5. User Review and Confirmation (Blocking Point)
 
-After the three documents are created and content completeness check passes, **must use the AskUserQuestion tool to pause and wait for user confirmation**. Must not execute phase guard or auto-transition before user confirmation.
+After the three documents are created and content completeness check passes, **must use the current platform's available user input/confirmation mechanism to pause and wait for user confirmation**. Must not execute phase guard or auto-transition before user confirmation. If the current platform has no structured question tool, ask an equivalent single-select question in the conversation, stop the workflow, and wait for the user's reply before continuing.
 
-AskUserQuestion must be presented as a single-select question with the following summary and options:
+The user confirmation question must be presented as a single-select question with the following summary and options:
 
 **Summary content**:
 - **proposal.md**: problem background, goals, scope
@@ -88,7 +152,7 @@ AskUserQuestion must be presented as a single-select question with the following
 - "Confirm, proceed to next phase" — artifacts meet expectations, execute phase guard transition
 - "Needs adjustment" — include adjustment notes, modify and re-request confirmation
 
-After user selects "Confirm", proceed to exit conditions. When user selects "Needs adjustment", modify the corresponding files per their notes, then re-use AskUserQuestion to request confirmation.
+After user selects "Confirm", proceed to exit conditions. When user selects "Needs adjustment", modify the corresponding files per their notes, then request confirmation again.
 
 ## Exit Conditions
 
@@ -104,10 +168,19 @@ Must use `--apply` before exit, otherwise `.comet.yaml` remains at `phase: open`
 
 Full workflow auto-transitions to `phase: design`; hotfix/tweak presets auto-transition to `phase: build`.
 
-## Automatic Transition
+## Automatic Handoff to Next Phase
+
+> **Terminology distinction**: the "phase advancement" above is performed by guard `--apply`, which updates the `.comet.yaml` `phase` field. This step **always happens** and is not controlled by `auto_transition`. This section's "automatic handoff" only controls whether to automatically invoke the next skill.
+
+After user confirmation and guard-based phase advancement, run:
+
+```bash
+"$COMET_BASH" "$COMET_STATE" next <change-name>
+```
 
-After user confirmation and exit conditions are met, auto-transition to next phase:
+The script determines the next action from `phase`, `workflow`, and `auto_transition`:
+- `NEXT: auto` -> invoke the `SKILL` target to continue to the next phase
+- `NEXT: manual` -> do not invoke the next skill; follow `HINT` and ask the user to run `/<SKILL>` manually
+- `NEXT: done` -> workflow is complete; no further action needed
 
-> **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.
+Hotfix/tweak presets are controlled by their preset skills (phase goes directly to build), and their `next` output points to the preset path.

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

@@ -13,7 +13,7 @@ Applicable for non-bug small scope changes, such as copy adjustment, configurati
 1. No new capability
 2. No architecture changes
 3. No interface changes
-4. Typically no more than 3 tasks, 4 files
+4. Typically no more than 3 tasks (file count constraint see upgrade conditions below)
 
 **Not applicable**: If change process discovers need for capability, architecture or interface adjustments, should upgrade to full `/comet` workflow.
 
@@ -21,7 +21,11 @@ Applicable for non-bug small scope changes, such as copy adjustment, configurati
 
 ## Process (preset workflow, 4 phases)
 
-Execution chain: open → lightweight build → light verify → archive. Tweak provides default decisions for each phase: streamlined open, lightweight build, lightweight verification, archive after verification passes.
+### 0. Output Language Constraint
+
+Streamlined OpenSpec artifacts must use the language of the user request that triggered this workflow.
+
+Execution chain: open → lightweight build → light verify → archive. Tweak provides default decisions for each phase: streamlined open, lightweight build, lightweight verification, and final archive confirmation after verification passes.
 
 Locate Comet scripts before starting:
 
@@ -96,11 +100,11 @@ Reuse `/comet-verify`. Tweak must maintain lightweight verification conditions:
 
 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.
+After verification passes, record `.comet.yaml` `verify_result` as `pass` according to `/comet-verify` rules, must not skip this status before archiving. After verification passes, still enter `/comet-archive`'s final archive confirmation; do not automatically run the archive script.
 
 ### 4. Archive (preset archive)
 
-Reuse `/comet-archive`. Must satisfy `verify_result: pass` in `.comet.yaml` before archiving.
+Reuse `/comet-archive`. Must satisfy `verify_result: pass` in `.comet.yaml` before archiving, and wait for `/comet-archive`'s final archive confirmation.
 
 **Immediately execute:** Use the Skill tool to load the `comet-archive` skill to archive. Skipping this step is prohibited.
 
@@ -109,10 +113,15 @@ 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 advance through tweak steps, without pausing to wait for user input mid-way. But the following situations must pause and wait for 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.
+
+Exception: when `.comet.yaml` has `auto_transition: false`, after each phase guard advances `phase`, do not auto-invoke the next skill. In this case, use `"$COMET_BASH" "$COMET_STATE" next <name>` output and pause for manual continuation as instructed.
 
-1. Encountering upgrade conditions (see "Upgrade Conditions" section). **Must use the AskUserQuestion tool to pause and wait for the user to explicitly confirm** upgrading to full workflow
+The following situations must pause and wait for user confirmation:
+
+1. Encountering upgrade conditions (see "Upgrade Conditions" section). **Must use the current platform's available user input/confirmation mechanism to pause and wait for the user to explicitly confirm** upgrading to full workflow
 2. verify phase (comet-verify) verification-failure and branch-handling decisions
+3. Final archive confirmation (before comet-archive runs the archive script)
 
 Execution order: quick open → lightweight build → lightweight verification → archive → complete
 
@@ -134,12 +143,13 @@ Upgrade to full `/comet` when **any** of the following conditions are met:
 | New capability needed | Exceeds local optimization |
 | Delta spec needed | Affects existing specs |
 
-When upgrade conditions are met, **must use the AskUserQuestion tool to pause and wait for the user to explicitly confirm** upgrading to the full `/comet` workflow. Do not directly enter `/comet-design`, and do not automatically supplement Design Doc. Must not just output a text prompt and then continue executing.
+When upgrade conditions are met, **must use the current platform's available user input/confirmation mechanism to pause and wait for the user to explicitly confirm** upgrading to the full `/comet` workflow. Do not directly enter `/comet-design`, and do not automatically supplement Design Doc. If the current platform has no structured question tool, ask an upgrade confirmation question in the conversation, stop the workflow, and wait for the user's reply before continuing.
 
-After user confirms upgrade, **must first update the workflow field** before entering full flow:
+After user confirms upgrade, **must first update the workflow and phase fields** before entering full flow:
 
 ```bash
 "$COMET_BASH" "$COMET_STATE" set <name> workflow full
+"$COMET_BASH" "$COMET_STATE" set <name> phase design
 ```
 
 Then on current change basis, supplement Design Doc: **Immediately use the Skill tool to load the `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.
@@ -152,3 +162,18 @@ Then on current change basis, supplement Design Doc: **Immediately use the Skill
 - Change archived
 - No new capability, architecture adjustments or interface changes
 - **Phase guard**: Before build → verify run `"$COMET_BASH" "$COMET_GUARD" <change-name> build --apply`; before verify → archive follow `/comet-verify` and run `"$COMET_BASH" "$COMET_GUARD" <change-name> verify --apply`
+
+## Automatic Handoff to Next Phase
+
+> **Terminology distinction**: phase guard `--apply` advances the `.comet.yaml` `phase` field. This step **always happens** and is not controlled by `auto_transition`. This section's "automatic handoff" only controls whether to automatically invoke the next skill.
+
+After each phase guard or state transition advances phase, run:
+
+```bash
+"$COMET_BASH" "$COMET_STATE" next <name>
+```
+
+The script determines the next action from `phase`, `workflow`, and `auto_transition`:
+- `NEXT: auto` -> invoke the `SKILL` target to continue the tweak flow (`phase: build` returns `comet-tweak`, `verify` returns `comet-verify`, `archive` returns `comet-archive`)
+- `NEXT: manual` -> do not invoke the next skill; follow `HINT` and ask the user to run `/<SKILL>` manually
+- `NEXT: done` -> workflow is complete; no further action needed

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

@@ -12,7 +12,11 @@ description: "Comet Phase 4: Verify and Close. Invoke with /comet-verify. Verify
 
 ## Steps
 
-### 0. Entry State Verification (Entry Check)
+### 0a. Output Language Constraint
+
+Verification reports and branch-handling notes must use the language of the user request that triggered this workflow.
+
+### 0b. Entry State Verification (Entry Check)
 
 Execute entry verification:
 
@@ -38,7 +42,7 @@ Execute scale assessment:
 "$COMET_BASH" "$COMET_STATE" scale <change-name>
 ```
 
-The script automatically counts tasks, delta spec count, changed file count, determines 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. Decision rule (any condition triggers full): tasks > 3, delta spec capabilities > 1, changed files > 4.
 
 Before verification begins, handle uncommitted changes through `comet/reference/dirty-worktree.md` protocol. Verify phase special handling:
 
@@ -53,6 +57,8 @@ Only after user chooses fix, allow rollback to build phase:
 "$COMET_BASH" "$COMET_STATE" transition <change-name> verify-fail
 ```
 
+Note: When verify-fail rolls back to build, `branch_status` is not reset. If branch handling was already completed during the first verify attempt, skip the branch handling step on re-verify and keep the existing `branch_status: handled`.
+
 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
@@ -67,9 +73,11 @@ If commit range shows changes exceed lightweight threshold (> 4 files, cross-mod
 "$COMET_BASH" "$COMET_STATE" set <change-name> verify_mode full
 ```
 
+**Override mechanism**: If the agent or user believes the automated assessment is inappropriate, override at any time with `"$COMET_BASH" "$COMET_STATE" set <change-name> verify_mode <light|full>`.
+
 ### 1b. Verification Failure Decision (Blocking Point)
 
-When verification does not pass, **must use the AskUserQuestion tool to pause and wait for the user to decide fix or accept deviation**. Must not automatically run `"$COMET_BASH" "$COMET_STATE" transition <change-name> verify-fail`, nor automatically invoke `/comet-build`. Must not just output a text prompt and then continue executing.
+When verification does not pass, **must use the current platform's available user input/confirmation mechanism to pause and wait for the user to decide whether to fix or accept the deviation**. Must not automatically run `"$COMET_BASH" "$COMET_STATE" transition <change-name> verify-fail`, nor automatically invoke `/comet-build`. If the current platform has no structured question tool, ask fix/accept-deviation options in the conversation, stop the workflow, and wait for the user's reply before continuing.
 
 When pausing, must list:
 - Failed items
@@ -82,9 +90,29 @@ After user selection, continue as follows:
 - **Fix all**: Run `"$COMET_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
 
+**Retry limit**: After 3 consecutive verify-fail cycles, on the 4th failure the agent must not automatically choose to continue fixing; **must use the current platform's available user input/confirmation mechanism to pause** with only two options: "Accept all deviations and record" or "Continue fixing", for the user to explicitly decide.
+
+### 2. Artifact Context Loading (Hash On-Demand Read)
+
+When verification needs to read OpenSpec artifacts, first check whether they have changed since the design phase:
+
+```bash
+RECORDED_HASH=$("$COMET_BASH" "$COMET_STATE" get <change-name> handoff_hash)
+CURRENT_HASH=$("$COMET_BASH" "$COMET_HANDOFF" <change-name> --hash-only 2>/dev/null || echo "")
+```
+
+- If `RECORDED_HASH` = `CURRENT_HASH` and both are non-empty and neither is `null`: OpenSpec artifacts are unchanged. **tasks.md does not need to be re-read in full** (use `grep -c '\- \[ \]' tasks.md` to confirm completion count). proposal.md, design.md, and delta specs must still be read for comparison checks.
+- If `RECORDED_HASH` is empty, is `null`, or differs from `CURRENT_HASH`: artifacts have changed or hash was never recorded. Read all required files in full normally.
+
+This optimization only skips re-reading tasks.md in full. proposal.md and design.md contain the full context needed for verification checks and must not be skipped due to hash match.
+
+**Immediately execute:** Use the Skill tool to load the Superpowers `verification-before-completion` skill. Skipping this step is prohibited.
+
+After the skill loads, follow the `verify_mode` branch:
+
 ### 2a. Lightweight Verification (Small Changes)
 
-When scale assessment result is "small", skip `openspec-verify-change` and directly execute these checks:
+Run these 5 checks:
 
 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)
@@ -132,7 +160,7 @@ When verification does not pass: report missing items, enter Step 1b verificatio
 ```
 
 **Spec Drift Handling** (user decision point):
-- If check item 6 finds contradictions (delta spec has content but design doc does not reflect it), **must use the AskUserQuestion tool as a single-select question to pause and wait for user to choose handling method**; must not select automatically. Options:
+- If check item 6 finds contradictions (delta spec has content but design doc does not reflect it), **must use the current platform's available user input/confirmation mechanism as a single-select question to pause and wait for the user to choose the 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 `"$COMET_BASH" "$COMET_STATE" transition <change-name> verify-fail`, then invoke `/comet-build`; `/comet-build`'s Spec Incremental Update rules will load the Superpowers `brainstorming` skill 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)
@@ -149,7 +177,7 @@ After the skill loads, follow its guidance to finish. Branch handling options:
 3. Keep branch (handle later)
 4. Discard work
 
-This is a user decision point. **Must use the AskUserQuestion tool to pause and wait for user to choose branch handling method**. Must not select based on recommendations, defaults, or current branch status. Must not just output a text prompt and then continue executing. Only after the user completes selection and the corresponding operation finishes, may `branch_status: handled` be written.
+This is a user decision point. **Must use the current platform's available user input/confirmation mechanism to pause and wait for the user to choose branch handling method**. Must not select based on recommendations, defaults, or current branch status. If the current platform has no structured question tool, ask branch-handling options in the conversation, stop the workflow, and wait for the user's reply before continuing. Only after the user completes selection and the corresponding operation finishes, may `branch_status: handled` be written.
 
 **Confirmation items**:
 - All tests pass
@@ -184,11 +212,22 @@ After both verification and branch handling are complete, run guard for auto-tra
 
 State file auto-updates to `phase: archive`, `verify_result: pass`, `verified_at: YYYY-MM-DD`.
 
-## Automatic Transition
+## Automatic Handoff to Next Phase
+
+> **Terminology distinction**: the "phase advancement" above is performed by guard `--apply`, which updates the `.comet.yaml` `phase` field. This step **always happens** and is not controlled by `auto_transition`. This section's "automatic handoff" only controls whether to automatically invoke the next skill.
+
+After verification and branch handling are complete, and guard-based phase advancement has completed, run:
+
+```bash
+"$COMET_BASH" "$COMET_STATE" next <change-name>
+```
 
-After exit conditions are met (including user selecting branch handling method), auto-transition to next phase:
+The script determines the next action from `phase`, `workflow`, and `auto_transition`:
+- `NEXT: auto` -> invoke the `SKILL` target to continue to the next phase
+- `NEXT: manual` -> do not invoke the next skill; follow `HINT` and ask the user to run `/<SKILL>` manually
+- `NEXT: done` -> workflow is complete; no further action needed
 
-> **REQUIRED NEXT SKILL:** Invoke `comet-archive` skill to enter the archive phase.
+Note: after `comet-archive` starts, it must first execute the final archive confirmation blocking point and wait for the user to explicitly choose "Confirm archive" before running the archive script. Must not automatically archive just because verification passed.
 
 ## Context Compaction Recovery