@rpamis/comet 0.4.0-beta.1 → 0.4.0-beta.10

package/eval/local/skills/benchmarks/039-release/comet-classic-039-open/SKILL.md

@@ -0,0 +1,220 @@
+---
+name: comet-open
+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
+
+## Prerequisites
+
+- No active change, or user wants to create a new change
+
+## Steps
+
+### 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, 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 follow the `comet/reference/decision-point.md` protocol to pause and wait for the user's choice.
+
+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 follow the `comet/reference/decision-point.md` protocol to pause and wait for the user to confirm requirements clarification is complete.
+
+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.
+
+### 1c. Change Name Confirmation (Blocking Point)
+
+Before creating the change directory (`openspec new change`), must follow the `comet/reference/decision-point.md` protocol to pause and let the user decide the change name. Must not auto-generate or silently infer the change name.
+
+OpenSpec change names must be **kebab-case English** (lowercase letters, digits, hyphens; e.g. `refine-requirements-doc`). Chinese or other non-conforming names are invalid.
+
+When pausing, present:
+- **2-3 recommended kebab-case English names** derived from the confirmed clarification summary, each with a one-line description of the scope it implies
+- An explicit option for the user to **enter their own name**
+- A note that **if the user enters Chinese (or any non-kebab-case text), it will be converted into a compliant kebab-case English name**, and the converted result must be shown back to the user for confirmation before use
+
+The decision options must include:
+- Pick one of the recommended names
+- "Enter a custom name" — accept the user's input; if it is already valid kebab-case English, use it directly; if it is Chinese or otherwise non-conforming, convert it to compliant kebab-case English and show the converted name for confirmation before continuing
+
+Must not run `openspec new change` or create `.comet.yaml` before the user confirms the final change name. If the chosen/converted name collides with an existing change, report the collision and ask the user to choose another name.
+
+### 2. Create Change Structure + Initialize State
+
+**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.
+
+If the user has already confirmed a clarification summary (Step 1b), use that summary directly to populate artifact content. If no clarification summary exists (edge case), fall back to the skill's default behavior of asking the user.
+
+After the change skeleton is created, generate `proposal`, `design`, and `tasks` one by one using the standard artifact loop:
+
+**Standard Artifact Loop** (for each `artifact-id`: `proposal` → `design` → `tasks`):
+
+1. Refresh status: `openspec status --change "<name>" --json`
+2. Fetch artifact instructions:
+
+   ```bash
+   openspec instructions proposal --change "<name>" --json
+   openspec instructions design --change "<name>" --json
+   openspec instructions tasks --change "<name>" --json
+   ```
+
+3. For the returned JSON instruction payload, you must:
+   - Read every completed dependency artifact listed in `dependencies`
+   - Use `template` as the artifact structure
+   - Follow `instruction` guidance
+   - Apply `context` and `rules` as constraints — **must not copy them into the artifact content**
+   - Write to `resolvedOutputPath`
+   - Verify the output file exists and is non-empty
+4. After creating each artifact, re-run `openspec status --change "<name>" --json` to confirm status before continuing to the next artifact
+
+**Failure handling**: If `openspec instructions` fails, returns invalid JSON, reports unmet `dependencies`, or does not provide a usable `resolvedOutputPath`, must immediately stop artifact creation and report the OpenSpec error. Must not fall back to hard-coded artifact prose because that would silently bypass project rules.
+
+**Naming and scope guard**: Change name must be the kebab-case English name confirmed by the user in Step 1c — must not auto-generate, infer, or use a non-kebab-case (e.g. Chinese) name. Change scope must match the user's description — must not expand or narrow it independently.
+
+Confirm the following artifacts have been created:
+
+```
+openspec/changes/<name>/
+├── .openspec.yaml
+├── .comet.yaml
+├── proposal.md       # Why + What: problem, goals, scope
+├── design.md         # How (high-level): architecture decisions, approach selection
+└── tasks.md          # Task checklist (checkboxes)
+```
+
+Create `.comet.yaml` state file:
+
+```bash
+COMET_ENV="${COMET_ENV:-$(find . "$HOME"/.*/skills "$HOME/.config" "$HOME/.gemini" -path '*/comet/scripts/comet-env.sh' -type f -print -quit 2>/dev/null)}"
+if [ -z "$COMET_ENV" ]; then
+  echo "ERROR: comet-env.sh not found. Ensure the comet skill is installed." >&2
+  return 1
+fi
+. "$COMET_ENV"
+
+if [ -z "$COMET_STATE" ] || [ -z "$COMET_GUARD" ]; then
+  echo "ERROR: Comet scripts not found. Ensure the comet skill is installed." >&2
+  return 1
+fi
+
+"$COMET_BASH" "$COMET_STATE" init <name> full
+```
+
+### 3. Entry State Verification
+
+Verify state machine has been correctly initialized:
+
+```bash
+"$COMET_BASH" "$COMET_STATE" check <name> open
+```
+
+Proceed to Step 4 after verification passes. The script outputs specific failure reasons when verification fails.
+
+**Idempotency**: All open phase operations can be safely re-executed. If `.comet.yaml` is already at `phase: open` and all three artifact files exist, skip completed steps and continue from the first missing step.
+
+### 4. Content Completeness Check
+
+Confirm the three documents have complete content:
+- **proposal.md**: problem background, goals, scope, non-goals
+- **design.md**: high-level architecture decisions, approach selection, data flow
+- **tasks.md**: task list, each task has a clear description
+
+**File existence verification**: Confirm all three file paths exist and are non-empty. If any file is missing or empty, must not enter Step 5 or execute phase guard — return to creation step to fill the gap.
+
+### 5. User Review and Confirmation (Blocking Point)
+
+After the three documents are created and content completeness check passes, **must follow the `comet/reference/decision-point.md` protocol to pause and wait for user confirmation**. Must not execute phase guard or auto-transition before user confirmation.
+
+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
+- **design.md**: high-level architecture decisions, approach selection
+- **tasks.md**: task count and key task descriptions
+
+**Options**:
+- "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 request confirmation again.
+
+## Exit Conditions
+
+- proposal.md, design.md, tasks.md all created with complete content
+- **User has confirmed** proposal, design, tasks content meets expectations
+- **Phase guard**: Run `"$COMET_BASH" "$COMET_GUARD" <change-name> open --apply`; after all PASS, auto-transitions to next phase
+
+Must use `--apply` before exit, otherwise `.comet.yaml` remains at `phase: open` and the next phase entry check will fail.
+
+```bash
+"$COMET_BASH" "$COMET_GUARD" <change-name> open --apply
+```
+
+Full workflow auto-transitions to `phase: design`; hotfix/tweak presets auto-transition to `phase: build`.
+
+## Automatic Handoff to Next Phase
+
+Follow `comet/reference/auto-transition.md`. Key command:
+
+```bash
+"$COMET_BASH" "$COMET_STATE" next <change-name>
+```
+
+- `NEXT: auto` → invoke the skill pointed to by `SKILL` to enter the next phase
+- `NEXT: manual` → do not invoke the next skill; prompt user to run `/<SKILL>` manually
+- `NEXT: done` → workflow is complete, no further action needed
+
+hotfix/tweak presets are controlled by their corresponding preset skill (phase goes directly to build); their `next` returns the corresponding preset skill.

package/eval/local/skills/benchmarks/039-release/comet-classic-039-tweak/SKILL.md

@@ -0,0 +1,180 @@
+---
+name: comet-tweak
+description: "Comet preset path: Non-bug small changes (tweak). Skip brainstorming and full plan, directly open → lightweight build → light verify → archive. Applicable for copy, configuration, documentation or prompt local optimization."
+---
+
+# Comet Preset Path: Tweak
+
+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 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
+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.
+
+---
+
+## Process (preset workflow, 4 phases)
+
+### 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:
+
+```bash
+COMET_ENV="${COMET_ENV:-$(find . "$HOME"/.*/skills "$HOME/.config" "$HOME/.gemini" -path '*/comet/scripts/comet-env.sh' -type f -print -quit 2>/dev/null)}"
+if [ -z "$COMET_ENV" ]; then
+  echo "ERROR: comet-env.sh not found. Ensure the comet skill is installed." >&2
+  return 1
+fi
+. "$COMET_ENV"
+```
+
+### 1. Quick Open (preset open)
+
+Reuse Comet open capability to create change, but use tweak defaults: do not execute `openspec-explore` long exploration, directly enter streamlined change creation.
+
+**Immediately execute:** Use the Skill tool to load the `openspec-new-change` skill. Skipping this step is prohibited.
+
+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` — 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:
+
+```bash
+"$COMET_BASH" "$COMET_STATE" init <name> tweak
+```
+
+Verify initialized state:
+
+```bash
+"$COMET_BASH" "$COMET_STATE" check <name> open
+```
+
+Run phase guard to transition open → build:
+
+```bash
+"$COMET_BASH" "$COMET_GUARD" <change-name> open --apply
+```
+
+### 2. Lightweight Build (preset build)
+
+Use tweak defaults: `build_mode: direct`. Skip Superpowers `brainstorming` and `writing-plans`.
+
+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 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
+   - Commit code, commit message format: `tweak: <brief change description>`
+3. After all tasks complete, explicitly run relevant project tests and build commands
+4. Run phase guard to transition build → verify:
+
+```bash
+"$COMET_BASH" "$COMET_GUARD" <change-name> build --apply
+```
+
+State automatically updates to `phase: verify`, `verify_result: pending`, then enter verification.
+
+During tweak execution, whenever running programs, tests, builds, or manual verification results in crashes, abnormal behavior, test failures, or build failures, you must use the Skill tool to load the Superpowers `systematic-debugging` skill. Do not propose or implement source code fixes before completing root cause investigation.
+
+For specific investigation, minimal failing test, fix verification, and keeping the current change verification loop, follow `comet/reference/debug-gate.md`.
+
+### 3. Lightweight Verification (preset verify)
+
+Reuse `/comet-verify`. Tweak must maintain lightweight verification conditions: ≤ 3 tasks, ≤ 4 files, no delta spec, no new capability.
+
+**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, 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, 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, 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.
+
+---
+
+## 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.
+
+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 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
+
+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>
+
+---
+
+## Upgrade Conditions
+
+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 | 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 specs |
+
+When upgrade conditions are met, **must follow the `comet/reference/decision-point.md` protocol 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.
+
+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.
+
+---
+
+## Exit Conditions
+
+- Small change completed, tests pass
+- 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
+
+Follow `comet/reference/auto-transition.md`. Key command:
+
+```bash
+"$COMET_BASH" "$COMET_STATE" next <name>
+```
+
+- `NEXT: auto` → invoke the skill pointed to by `SKILL` to continue tweak workflow (`phase: build` returns `comet-tweak`, `verify` returns `comet-verify`, `archive` returns `comet-archive`)
+- `NEXT: manual` → do not invoke the next skill; prompt user to manually run `/<SKILL>` per `HINT`
+- `NEXT: done` → workflow is complete, no further action needed

package/eval/local/skills/benchmarks/039-release/comet-classic-039-verify/SKILL.md

@@ -0,0 +1,234 @@
+---
+name: comet-verify
+description: "Comet Phase 4: Verify and Close. Invoke with /comet-verify. Verify implementation matches design, handle development branch."
+---
+
+# Comet Phase 4: Verify and Close (Verify)
+
+## Prerequisites
+
+- Code committed (Phase 3 complete)
+- All tasks.md tasks completed
+
+## Steps
+
+### 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:
+
+```bash
+COMET_ENV="${COMET_ENV:-$(find . "$HOME"/.*/skills "$HOME/.config" "$HOME/.gemini" -path '*/comet/scripts/comet-env.sh' -type f -print -quit 2>/dev/null)}"
+if [ -z "$COMET_ENV" ]; then
+  echo "ERROR: comet-env.sh not found. Ensure the comet skill is installed." >&2
+  return 1
+fi
+. "$COMET_ENV"
+"$COMET_BASH" "$COMET_STATE" check <change-name> verify
+```
+
+Proceed to Step 1 after verification passes. The script outputs specific failure reasons when verification fails.
+
+**Idempotency**: All verify phase checks can be safely re-executed. If `verify_result` is already `pass` and `branch_status` is `handled`, verification is complete — execute guard to transition. If `verify_result` is `pending`, start verification from the beginning.
+
+### 1. Scale Assessment
+
+Execute scale assessment:
+
+```bash
+"$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. 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:
+
+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
+
+Only after user chooses fix, allow rollback to build phase:
+
+```bash
+# Execute only after user confirms fix
+"$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
+PLAN=$("$COMET_BASH" "$COMET_STATE" get <change-name> plan)
+BASE_REF=$(grep '^base-ref:' "$PLAN" 2>/dev/null | head -1 | sed 's/^base-ref: *//')
+git diff --stat "$BASE_REF"...HEAD
+```
+
+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
+"$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 follow the `comet/reference/decision-point.md` protocol 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`.
+
+When pausing, must list:
+- Failed items
+- Whether CRITICAL or IMPORTANT (build failure, test failure, security issues, core acceptance scenario failure, lightweight code review correctness/security/edge-case issue)
+- Recommended handling approach
+
+**Uncertainty principle**: When severity is unclear, downgrade (SUGGESTION > WARNING > CRITICAL). Only use CRITICAL for build failures, test failures, and security issues; ambiguous or uncertain issues should be WARNING or SUGGESTION.
+
+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 or IMPORTANT failures must be fixed; WARNING/SUGGESTION failures may choose to accept deviation, but must record acceptance reason and impact scope in verification report. If any CRITICAL or IMPORTANT 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)
+
+Run these 6 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)
+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 keys, no new unsafe operations)
+6. Lightweight code review passes: use the Skill tool to load the Superpowers `requesting-code-review` skill and request a lightweight review that checks only correctness, security, and edge cases
+
+The lightweight code review input should be limited to this change's diff, tasks.md, and necessary test results; the review scope covers implementation correctness, security risk, and edge cases only, and does not perform spec coverage, Design Doc consistency, or drift checks. If the review finds CRITICAL or IMPORTANT issues, treat verification as failed and enter Step 1b.
+
+**Pass criteria**: All 6 items OK, no CRITICAL or IMPORTANT issues.
+
+**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
+"$COMET_BASH" "$COMET_STATE" transition <change-name> verify-fail
+```
+
+**Report format**: Brief table listing 6 check results + PASS/FAIL.
+
+**Skipped items** (not checked in lightweight verification):
+- spec scenario coverage
+- design doc consistency deep comparison
+- code pattern consistency suggestions that do not affect correctness, security, or edge cases
+- delta spec and design doc drift detection
+
+### 2b. Full Verification (Large Changes)
+
+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.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 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
+"$COMET_BASH" "$COMET_STATE" transition <change-name> verify-fail
+```
+
+**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 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)
+
+### 3. Finishing (Superpowers)
+
+**Immediately execute:** Use the Skill tool to load the Superpowers `finishing-a-development-branch` skill. Skipping this step is prohibited.
+
+If the Superpowers `finishing-a-development-branch` skill 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 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 follow the `comet/reference/decision-point.md` protocol to pause and wait for the 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 keys or security issues
+
+### 4. Record Verification Evidence
+
+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 verification conclusions to report file, e.g.:
+# docs/superpowers/reports/YYYY-MM-DD-<change-name>-verify.md
+
+"$COMET_BASH" "$COMET_STATE" set <change-name> verification_report docs/superpowers/reports/YYYY-MM-DD-<change-name>-verify.md
+"$COMET_BASH" "$COMET_STATE" set <change-name> branch_status handled
+```
+
+## Exit Conditions
+
+- Verification report passed
+- Branch handled
+- `verification_report` in `.comet.yaml` points to an existing verification report file
+- `branch_status: handled` in `.comet.yaml`
+- **Phase guard**: Run `"$COMET_BASH" "$COMET_GUARD" <change-name> verify --apply`; after all PASS, auto-transitions to `phase: archive` through `comet-state transition verify-pass`
+
+After both verification and branch handling are complete, run guard for auto-transition:
+
+```bash
+"$COMET_BASH" "$COMET_GUARD" <change-name> verify --apply
+```
+
+State file auto-updates to `phase: archive`, `verify_result: pass`, `verified_at: YYYY-MM-DD`.
+
+## Automatic Handoff to Next Phase
+
+Follow `comet/reference/auto-transition.md`. Key command:
+
+```bash
+"$COMET_BASH" "$COMET_STATE" next <change-name>
+```
+
+- `NEXT: auto` → invoke the skill pointed to by `SKILL` to enter the next phase
+- `NEXT: manual` → do not invoke the next skill; prompt user to run `/<SKILL>` manually
+- `NEXT: done` → workflow is complete, no further action needed
+
+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 Compression Recovery
+
+Follow `comet/reference/context-recovery.md` with phase set to `verify`.