@rpamis/comet 0.3.9 → 0.4.0-beta.10

package/assets/manifest.json

@@ -1,22 +1,49 @@
 {
-  "version": "0.3.8",
+  "version": "0.4.0-beta.10",
   "skills": [
     "comet/SKILL.md",
+    "comet-classic/SKILL.md",
     "comet/reference/auto-transition.md",
+    "comet/reference/classic-layout.md",
     "comet/reference/comet-yaml-fields.md",
     "comet/reference/context-recovery.md",
     "comet/reference/debug-gate.md",
     "comet/reference/decision-point.md",
     "comet/reference/dirty-worktree.md",
     "comet/reference/file-structure.md",
+    "comet/reference/intent-frame.md",
+    "comet/reference/scripts.md",
     "comet/reference/subagent-dispatch.md",
-    "comet/scripts/comet-env.sh",
-    "comet/scripts/comet-guard.sh",
-    "comet/scripts/comet-state.sh",
-    "comet/scripts/comet-handoff.sh",
-    "comet/scripts/comet-archive.sh",
-    "comet/scripts/comet-yaml-validate.sh",
-    "comet/scripts/comet-hook-guard.sh",
+    "comet-any/SKILL.md",
+    "comet-any/reference/authoring-subagents.md",
+    "comet-any/reference/authored-zone-example.md",
+    "comet-any/reference/bundle-authoring.md",
+    "comet-any/reference/eval-provider.md",
+    "comet-any/reference/subagents/script-author.md",
+    "comet-any/reference/subagents/reference-author.md",
+    "comet-any/reference/subagents/workflow-entry-author.md",
+    "comet-any/reference/subagents/skill-core-author.md",
+    "comet-any/reference/subagents/pause-points-author.md",
+    "comet-any/reference/subagents/skill-reviewer.md",
+    "comet/scripts/comet-runtime.mjs",
+    "comet/scripts/comet-env.mjs",
+    "comet/scripts/comet-guard.mjs",
+    "comet/scripts/comet-state.mjs",
+    "comet/scripts/comet-handoff.mjs",
+    "comet/scripts/comet-archive.mjs",
+    "comet/scripts/comet-yaml-validate.mjs",
+    "comet/scripts/comet-hook-guard.mjs",
+    "comet/scripts/comet-intent.mjs",
+    "comet/scripts/comet-resume-probe.mjs",
+    "comet/scripts/comet-entry-runtime.mjs",
+    "comet/scripts/comet-hook-router.mjs",
+    "comet-native/SKILL.md",
+    "comet-native/reference/artifacts.md",
+    "comet-native/reference/clarification.md",
+    "comet-native/reference/commands.md",
+    "comet-native/reference/recovery.md",
+    "comet-native/scripts/comet-native-runtime.mjs",
+    "comet-native/scripts/comet-native-hook-guard.mjs",
     "comet-open/SKILL.md",
     "comet-design/SKILL.md",
     "comet-build/SKILL.md",
@@ -25,17 +52,23 @@
     "comet-hotfix/SKILL.md",
     "comet-tweak/SKILL.md"
   ],
+  "internalSkills": [
+    "comet/runtime/classic/skill.yaml",
+    "comet/runtime/classic/guardrails.yaml",
+    "comet/runtime/classic/checks.yaml"
+  ],
   "rules": [
-    "comet/rules/comet-phase-guard.md"
+    "comet/rules/comet-workflow-guard.md",
+    "comet/rules/comet-workflow-guard.en.md"
   ],
   "hooks": {
-    "comet/scripts/comet-hook-guard.sh": {
+    "comet/scripts/comet-hook-router.mjs": {
       "matcher": "Write|Edit",
-      "description": "Block code writes in wrong Comet phase (open/design/archive)"
+      "description": "Route each write to the selected Comet Native or Classic phase guard"
     }
   },
   "languages": [
-    { "id": "en", "name": "English", "skillsDir": "skills" },
-    { "id": "zh", "name": "中文", "skillsDir": "skills-zh" }
+    { "id": "en", "name": "English", "skillsDir": "skills", "artifactLanguage": "en" },
+    { "id": "zh", "name": "中文", "skillsDir": "skills-zh", "artifactLanguage": "zh-CN" }
   ]
 }

package/assets/skills/comet/SKILL.md

@@ -1,282 +1,28 @@
 ---
 name: comet
-description: "Comet — OpenSpec + Superpowers dual-star development workflow. Start with /comet for automatic phase detection and dispatch to subcommands. Five phases: open → design → build → verify → archive."
+description: "Route /comet requests or an active Comet change to the permanent Comet Native or Comet Classic entry selected by project configuration."
 ---
 
-# Comet — OpenSpec + Superpowers Dual-Star Development Workflow
+# Comet Entry
 
-OpenSpec and Superpowers orbit the same goal like a binary star system.
+`/comet` only selects an entry. It does not contain either workflow's execution method.
 
-```
-OpenSpec handles WHAT  — outline, proposal, spec lifecycle, archive
-Superpowers handles HOW — technical design, planning, execution, closing
-```
+1. First try the Comet CLI installed on PATH in the current project:
 
-**Core principle: brainstorming cannot be skipped. Every change must undergo deep design (except hotfix and tweak presets).**
+   ```text
+   comet workflow resolve . --json
+   ```
 
----
-
-## Decision Core
-
-Agents need only read this section for decision-making. Refer to the Reference Appendix as needed.
-
-### Output Language Rule
-
-Use the language of the user request that triggered this workflow as the default output language. When resuming an existing change with a clear dominant artifact language, preserve that language unless the user explicitly asks to switch.
-
-### Automatic Phase Detection
-
-**Step 0: Active Change Discovery and Intent Detection**
-
-1. Detect presets first; if hotfix/tweak matches, invoke the corresponding preset skill directly and do not enter the normal open branch
-2. When no preset matches, run `openspec list --json` to get all active changes
-
-**Preset detection has highest priority**:
-- User explicitly describes a bug fix / hotfix + meets hotfix conditions → directly invoke `/comet-hotfix`
-- User explicitly describes copy/config/docs/prompt small adjustment + meets tweak conditions → directly invoke `/comet-tweak`
-- No preset match → follow the table below
-
-| Active changes | User input | Behavior |
-|----------------|------------|----------|
-| None | non-preset input | → Invoke `/comet-open` |
-| Exactly 1 | `/comet <description>` | → **Ask**: continue this change or create a new change |
-| Multiple | `/comet <description>` | → **Ask**: continue existing or create new; if continuing, list changes for selection |
-| Exactly 1 | `/comet` with no description | → Auto-select, enter Step 1 |
-| Multiple | `/comet` with no description | → List changes for user selection |
-
-<IMPORTANT>
-When the user chooses "create a new change", **must invoke `/comet-open`**. Do not call `/opsx:new` directly.
-`/comet-open` performs dual initialization: OpenSpec artifacts (created by internal `/opsx:new`) plus `.comet.yaml` state file.
-Calling `/opsx:new` directly leaves `.comet.yaml` missing and breaks later phase detection.
-</IMPORTANT>
-
-**Step 1: Read `.comet.yaml` state metadata**
-
-Prefer reading `openspec/changes/<name>/.comet.yaml`. If not available, fall back to `openspec status --change "<name>" --json`, `tasks.md`, and `docs/superpowers/` file checks.
-
-**Resume rules**:
-- On every context resume, rerun Step 0 and Step 1; do not trust conversation history for phase detection
-- If there is an active change and the worktree has uncommitted changes, handle them through `comet/reference/dirty-worktree.md`. That protocol defines checks, attribution, and prohibitions; this file does not repeat them
-- If `phase: build`, first check `build_pause`, `plan`, `build_mode`, and `isolation` (see details below):
-  - If `build_pause: plan-ready` but `isolation` and `build_mode` are already set, treat as stale pause: first output `[COMET] Detected stale pause (build_pause=plan-ready but isolation/build_mode already set), auto-clearing and continuing`, then run `"$COMET_BASH" "$COMET_STATE" set <name> build_pause null`, then read the next unchecked task from tasks.md and resume execution per `build_mode`
-  - If `build_pause: plan-ready` and the plan file exists, but `isolation` or `build_mode` is not yet set, return to the `/comet-build` plan-ready resume point, prompt the user to choose isolation and execution method, and do not regenerate the plan
-  - If `build_pause: plan-ready` but the plan file is missing, return to `/comet-build` to handle corrupted state or regenerate the plan
-  - If `build_mode`, `isolation`, or `tdd_mode` is unset, return to the corresponding `/comet-build` step to supplement before executing
-  - If all are set, read the next unchecked task from tasks.md and continue:
-    - If `build_mode: subagent-driven-development`, do not execute tasks directly in the main window; return to `/comet-build`'s background subagent dispatch rules, main window only coordinates
-    - Other execution modes follow `/comet-build`'s corresponding rules
-- If `phase: verify` and `verify_result: fail`, enter the verification failure decision blocking point: pause and ask the user to fix or accept deviation; only after the user chooses fix, run `"$COMET_BASH" "$COMET_STATE" transition <name> verify-fail` and invoke `/comet-build`
-- If `phase: open` but proposal/design/tasks are complete, first run `"$COMET_BASH" "$COMET_GUARD" <change-name> open --apply` to repair state, then continue detection
-- If `phase: archive`, only invoke `/comet-archive`; `/comet-archive` must first wait for final archive confirmation. After archive succeeds, the change moves to the archive directory, so do not run guard against the old active directory
-
-**Step 2: Phase Determination** (check in order, first match wins)
-
-1. `archived: true` or change moved to archive → Workflow complete
-2. `verify_result: pass` and `archived` is not `true` → Invoke `/comet-archive` (first perform final archive confirmation)
-3. `verify_result: fail` → Enter verification failure decision blocking point (pause and ask fix or accept deviation; only after user chooses fix, run `verify-fail` then `/comet-build`)
-4. `phase: verify` or tasks.md all checked → Invoke `/comet-verify`
-5. `phase: build` or has Design Doc but plan/execution incomplete → Route by workflow: `hotfix` → `/comet-hotfix`, `tweak` → `/comet-tweak`, `full` → `/comet-build`
-6. `phase: design` or has change but no Design Doc → Invoke `/comet-design`
-7. `phase: open` or active change exists but `.comet.yaml` is missing → Invoke `/comet-open`
-8. No active change → Invoke `/comet-open`
-
-If metadata conflicts with file state, use verifiable file state as source of truth and correct `.comet.yaml` before continuing.
-
-### Preset Upgrade Criteria
-
-**hotfix → full** (upgrade if any condition met):
-- Change involves **3+ files**
-- Architecture changes (new modules, new interfaces, new dependencies)
-- Database schema changes
-- Fix introduces new public API
-- Fix scope exceeds a single function/module
-
-**tweak → full** (upgrade if any condition met):
-- Change involves **5+ files**
-- Cross-module coordination required
-- **5+** new test cases needed
-- Config item additions or deletions (not value changes)
-- New capability needed
-- Delta spec needed (existing spec affected)
-
-### Error Handling Quick Reference
-
-| Scenario | Handling |
-|----------|----------|
-| `openspec list --json` fails | Check if openspec is installed, prompt user to run `openspec init` |
-| Sub-skill unavailable | Stop workflow, prompt to install or enable the corresponding skill |
-| `.comet.yaml` malformed or missing | Use file state as source of truth, correct with `"$COMET_BASH" "$COMET_STATE" set` then continue |
-| Build/test fails | Return to build phase for fixes, do not enter verify |
-| Incomplete change directory structure | Fill missing files according to `comet-open` artifact requirements |
-
-### Phase Transitions
-
-<IMPORTANT>
-A single `/comet` invocation starts from the detected phase and advances to the next phase when exit conditions are met.
-
-Flow chain: open → design → build → verify → archive
-
-**Continuous execution requirement**: starting from the detected phase, the agent automatically continues through all later phases. But **auto-advancing only applies at transition points without user decisions**. When encountering user decision points, **must use the current platform's available user input/confirmation mechanism to pause and wait for the user's explicit response**. Must not use recommendation rules, defaults, or historical preferences to substitute for user confirmation, and must not just output a text prompt and then continue executing.
-
-**Distinguish phase advancement vs automatic handoff**: each sub-skill runs phase guard `--apply` before exit to advance the `.comet.yaml` `phase` field. This step **always happens** and is not controlled by `auto_transition`. After that, the sub-skill runs `"$COMET_BASH" "$COMET_STATE" next <name>` to resolve the next action: when `auto_transition` is not `false`, output is `NEXT: auto` (auto-invoke next skill); when `auto_transition` is `false`, output is `NEXT: manual` (do not invoke next skill, show a manual run hint). Therefore `auto_transition` **only controls next skill invocation, not phase advancement**. Regardless of `auto_transition`, user decision points below remain blocking.
-
-**Decision points are blocking points**: whenever reaching any of the following nodes, the current `/comet` invocation must stop, and follow the `comet/reference/decision-point.md` protocol to obtain the user's explicit choice. Only after the user explicitly chooses can the corresponding state fields be written and operations executed, then auto-advance resumes.
-
-Nodes requiring user participation (pause only at these nodes):
-1. Open phase proposal/design/tasks review and confirmation
-2. Confirm design approach during brainstorming
-3. Plan-ready pause choice during build phase, followed by workflow configuration selection (isolation + execution method + TDD mode)
-4. Decide to fix or accept deviation when verify fails (including Spec drift handling)
-5. Choose branch handling method for finishing-branch
-6. Archive phase final confirmation before running the archive script
-7. Encounter upgrade conditions (hotfix/tweak → full workflow)
-8. Build phase scope expansion requiring redesign or new change split
-9. Open phase large PRD requiring confirmation to split into multiple changes
-
-Agents should not skip these decision points; other unambiguous phase transitions must proceed automatically, must not exit midway. At decision points, **must not skip user confirmation or choose automatically — must explicitly obtain the user's choice through the current platform's available user input/confirmation mechanism before continuing**.
-
-**Red Flags** — when these thoughts appear, STOP and check:
-
-| Agent Thought | Actual Risk |
-|--------------|-------------|
-| "The user would probably agree with this approach" | Cannot decide for the user — use the current platform's user input/confirmation mechanism |
-| "This is a small change, confirmation isn't needed" | Decision points have no size exception — blocking points must wait |
-| "The user chose A last time, so A again" | Historical preference cannot substitute for current confirmation |
-| "I explained the plan and the user didn't object" | No objection ≠ consent — must use tool to get explicit choice |
-| "The flow has reached this point, should be fine" | Verification not passed ≠ passed — check verify_result |
-</IMPORTANT>
-
----
-
-## Subcommand Quick Reference
-
-| Command | Phase | Owner | Artifacts |
-|---------|-------|-------|-----------|
-| `/comet-open` | 1. Open | OpenSpec | proposal.md, design.md, tasks.md |
-| `/comet-design` | 2. Deep Design | Superpowers | Design Doc, delta spec |
-| `/comet-build` | 3. Plan and Build | Superpowers | Implementation plan, code commits |
-| `/comet-verify` | 4. Verify and Close | Both | Verification report, branch handling |
-| `/comet-archive` | 5. Archive | OpenSpec | delta→main spec sync, design doc markup, archive |
-| `/comet-hotfix` | Preset path | Both | Quick fix (skip brainstorming) |
-| `/comet-tweak` | Preset path | Both | Small change (skip brainstorming and full plan) |
-
-```
-/comet
-  ↓ Auto-detect
-/comet-open ──→ /comet-design ──→ /comet-build ──→ /comet-verify ──→ /comet-archive
-  (OpenSpec)      (Superpowers)     (Superpowers)     (Both)          (OpenSpec)
-
-/comet-hotfix (preset, skip brainstorming)
-  open ──→ build ──→ verify ──→ archive
-    ↑ If upgrade triggered → block for confirmation → supplement Design Doc → return to full workflow
-
-/comet-tweak (preset, skip brainstorming and full plan)
-  open ──→ lightweight build ──→ light verify ──→ archive
-    ↑ If upgrade triggered → block for confirmation → supplement Design Doc → return to full workflow
-```
-
----
-
-## Reference Appendix
-
-### State Machine Hard Constraints
-
-- Before `build → verify`, `isolation` must be `branch` or `worktree`
-- Before `build → verify`, `build_mode` must be selected
-- `build_mode: subagent-driven-development` must also have `subagent_dispatch: confirmed`
-- Before full workflow leaves build phase, `tdd_mode` must be selected as `tdd` or `direct`
-- `build_mode: direct` is allowed by default only for `hotfix` / `tweak`; full workflow requires `direct_override: true`
-- `build_pause` is not an execution method and must not be written to `build_mode`
-- These constraints are enforced by both `comet-guard.sh build --apply` and `comet-state.sh transition <name> build-complete`
-
-### .comet.yaml Field Reference
-
-See `comet/reference/comet-yaml-fields.md` for complete field reference with examples and descriptions.
-
-### File Structure
-
-See `comet/reference/file-structure.md` for the complete directory layout and artifact organization.
-
-### Auto-Transition Protocol
-
-See `comet/reference/auto-transition.md` for the complete automatic handoff workflow.
-
-### Context Recovery
-
-See `comet/reference/context-recovery.md` for structured recovery after context compression.
-
-### Decision Point Protocol
-
-See `comet/reference/decision-point.md` for the complete user decision point protocol.
-
-### Debug Gate Protocol
-
-See `comet/reference/debug-gate.md` for the complete debug gate protocol.
-
-### Script Location
-
-Comet scripts are distributed in `comet/scripts/`. **Do not hardcode paths** — locate once, cache in env vars. This block is a standard boilerplate repeated in every sub-skill for independent loadability; changes must be kept in sync across all files (boilerplate version: `v2`, update this version when changing to help locate files needing sync):
-
-```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"
-
-# Stop workflow when script location fails
-if [ -z "$COMET_GUARD" ] || [ -z "$COMET_STATE" ] || [ -z "$COMET_HANDOFF" ] || [ -z "$COMET_ARCHIVE" ]; then
-  echo "ERROR: Comet scripts not found. Ensure the comet skill is installed." >&2
-  echo "Expected path pattern: */comet/scripts/comet-*.sh under project or platform skill directories" >&2
-  return 1
-fi
-```
-
-**Auto state update**: Guard supports `--apply` flag, automatically updating `.comet.yaml` state fields after checks pass:
-
-```bash
-"$COMET_BASH" "$COMET_GUARD" <change-name> <phase> --apply
-```
-
-`--apply` delegates to `comet-state transition`. Use these semantic events when state changes need to be expressed directly:
-
-```bash
-"$COMET_BASH" "$COMET_STATE" transition <change-name> open-complete
-"$COMET_BASH" "$COMET_STATE" transition <change-name> design-complete
-"$COMET_BASH" "$COMET_STATE" transition <change-name> build-complete
-"$COMET_BASH" "$COMET_STATE" transition <change-name> verify-pass
-"$COMET_BASH" "$COMET_STATE" transition <change-name> verify-fail
-"$COMET_BASH" "$COMET_STATE" transition <archive-name> archived
-```
-
-**Resolve next action**: after guard-based phase advancement, use the `next` subcommand to determine whether to auto-invoke the next skill:
-
-```bash
-"$COMET_BASH" "$COMET_STATE" next <change-name>
-```
-
-Output format: `NEXT: auto|manual|done` + `SKILL: <skill-name>` (omitted for `done`) + `HINT` (for `manual` only). With `auto_transition: false`, output is `manual`, which pauses only the next skill invocation and does not block phase updates.
-
-**Archive script**: Complete all archive steps in one command:
-
-```bash
-"$COMET_BASH" "$COMET_ARCHIVE" <change-name>
-```
-
-After loading comet, agents should run the variable assignments above once, then reuse `$COMET_GUARD`, `$COMET_STATE`, `$COMET_HANDOFF`, `$COMET_ARCHIVE` throughout the session.
+2. **Only** when the host explicitly reports `command not found`, `executable not found`, or `ENOENT`, proving that `comet` is absent from PATH, locate `<comet-skill-root>` from this `SKILL.md` and run the bundled entry runtime:
 
+   ```text
+   node <comet-skill-root>/scripts/comet-entry-runtime.mjs . --json
+   ```
 
-### Best Practices
+   If the CLI starts but exits nonzero, configuration parsing fails, output is not JSON, or a required field is invalid, do not retry through the bundled runtime. Stop and report the original error without falling back or guessing.
+3. Parse the JSON. Only accept `schema: comet.workflow-resolution.v1` and a `skill` value listed below.
+4. Invoke exactly one entry based only on the returned `skill`, passing the user's original request through unchanged:
+   - `comet-native` → `/comet-native`
+   - `comet-classic` → `/comet-classic`
 
-1. **brainstorming cannot be skipped** — Every change must undergo deep design (except hotfix and tweak)
-2. **delta spec is a living document** — Freely modify during phase 3, sync at archive
-3. **Handoff packages are generated by scripts** — OpenSpec → Superpowers context must be generated through `comet-handoff.sh` as compact traceable excerpts (use `--full` when needed), and validated by guard for source/hash/mode
-4. **Keep tasks.md in sync** — Check off each completed task
-5. **Commit frequently** — One commit per task, message reflects design intent
-6. **Verify before archive confirmation** — Enter `/comet-archive` only after `/comet-verify` passes, but wait for final user confirmation before running the archive script
-7. **Classify incremental updates** — Small edits, medium brainstorming, large new changes
-8. **Plan must associate with change** — File header contains `change:` and `design-doc:` metadata
-9. **Archive closure** — design doc and plan must mark `archived-with` status
-10. **Modifying existing features** — Just open a new change
-11. **Preset has limits** — Switch to full workflow promptly when hotfix/tweak meet upgrade conditions
+Do not switch workflows based on task size, file count, active changes, or model judgment. Native and Classic changes, states, and artifacts always remain independent.

package/assets/skills/comet/reference/auto-transition.md

@@ -13,7 +13,7 @@ This protocol is shared by all comet sub-skills. It defines the automatic handof
 After exit conditions are met and the phase guard has advanced phase, run:
 
 ```bash
-"$COMET_BASH" "$COMET_STATE" next <change-name>
+comet state next <change-name>
 ```
 
 The script outputs a deterministic next step based on `phase`, `workflow`, and `auto_transition`:

package/assets/skills/comet/reference/classic-layout.md

@@ -0,0 +1,34 @@
+# Classic Artifact Layout Protocol
+
+At the start or recovery of every Classic phase, run this from the project root:
+
+```bash
+comet classic root show
+```
+
+Accept only `schema: comet.classic-layout.v1`. Bind the returned `openSpecRoot`, `changesRoot`, `archiveRoot`, `specsRoot`, and `superpowersRoot` as `<classic-open-spec-root>`, `<classic-changes-root>`, `<classic-archive-root>`, `<classic-specs-root>`, and `<classic-superpowers-root>`, respectively, then define `<classic-change-dir>` as `<classic-changes-root>/<name>`. These logical roots are the source of truth for this turn. Resolve them again after recovery or context compaction.
+
+## Command rules
+
+- This and every other Comet-owned Classic Skill must call the official OpenSpec CLI directly through:
+
+  ```bash
+  comet classic openspec -- <args...>
+  ```
+
+- The adapter runs the official CLI from the configured OpenSpec base and preserves stdout, stderr, and the exit code. Do not register or query an OpenSpec store for a root inside the same repository.
+- Run `openspec` directly only when the user explicitly operates from the resolved OpenSpec base.
+
+## Path rules
+
+- Express change, tasks, delta spec, handoff, and archive paths with the `<classic-*>` logical roots bound above; for example, use `<classic-change-dir>/tasks.md`. Do not wrap one physical layout in a logical-path convention and keep using it as filesystem guidance.
+- Resolve Superpowers files through `<classic-superpowers-root>/...`; do not derive them from the OpenSpec root or current cwd.
+- `comet state`, `comet guard`, `comet handoff`, and `comet archive` resolve the layout internally. Never persist a physical root in `.comet/current-change.json`.
+- If root show or a write command reports conflicting legacy/docs roots, invalid config, or an incomplete migration, stop. Use `comet doctor` for read-only inspection; do not scan both roots, guess change ownership, or dual-write.
+
+## New, existing, and migrated projects
+
+- New Classic projects default to `docs/openspec/`.
+- Existing projects without `classic.artifact_layout` continue to use `openspec/`.
+- Normal init/update never moves existing artifacts. Run `comet classic root move docs --dry-run` first and retain its plan ID; use `comet classic root move docs --apply --plan <id>` only with explicit user authorization.
+- The first migration version rejects every active or unmanaged OpenSpec change.

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

@@ -2,12 +2,14 @@
 
 Canonical path: `comet/reference/comet-yaml-fields.md`
 
-This file is the field reference for the `.comet.yaml` state file. Consult on demand; not loaded inline with skills.
+This file is the field reference for each change-level `.comet.yaml` state file under `<classic-change-dir>/`. `<classic-change-dir>` comes from the resolver binding in `comet/reference/classic-layout.md`.
+Consult on demand; not loaded inline with skills. Project defaults live in `.comet/config.yaml`, global defaults live in `~/.comet/config.yaml`, and project values take precedence.
 
 ## Example
 
 ```yaml
 workflow: full
+language: en
 phase: build
 design_doc: docs/superpowers/specs/YYYY-MM-DD-topic-design.md
 plan: docs/superpowers/plans/YYYY-MM-DD-feature.md
@@ -16,13 +18,18 @@ build_mode: subagent-driven-development
 build_pause: null
 subagent_dispatch: confirmed
 tdd_mode: tdd
+review_mode: standard
+auto_transition: true
 isolation: branch
+bound_branch: null
 verify_mode: light
 verify_result: pending
+verify_failures: 0
 verification_report: null
 branch_status: pending
 created_at: 2026-05-26
 verified_at: null
+archive_confirmation: null
 archived: false
 ```
 
@@ -31,22 +38,27 @@ archived: false
 | Field | Meaning |
 |-------|---------|
 | `workflow` | `full`, `hotfix`, or `tweak` |
+| `language` | Artifact language, `en` or `zh-CN`. Written to `classic.language` in the project or global `.comet/config.yaml` according to install scope, snapshotted into `.comet.yaml` with project-over-global precedence when a change is created, and used as the main-language constraint for OpenSpec / Superpowers artifacts |
 | `phase` | Current phase: `open`, `design`, `build`, `verify`, `archive` (init sets `open`; guard handles transitions) |
 | `design_doc` | Associated Superpowers Design Doc path; may be empty |
 | `plan` | Associated Superpowers Plan path; may be empty |
 | `base_ref` | Git commit SHA recorded at init for scale assessment. Used as baseline for changed-file counting when no plan exists |
-| `build_mode` | Selected execution mode; may be empty |
+| `build_mode` | Selected execution mode; may be empty. Values: `subagent-driven-development` (isolated background subagents implement and review each task), `executing-plans` (main session executes sequentially by plan), `direct` (main session codes directly; allowed by default only for hotfix/tweak, full workflow requires `direct_override: true`) |
 | `build_pause` | Build phase internal pause point. `null` = no pause, `plan-ready` = plan generated, paused for user model switch |
 | `subagent_dispatch` | `null` or `confirmed`. Only when the platform's real background subagent/Task/multi-agent dispatch capability is confirmed may `build_mode: subagent-driven-development` be written and used to leave the build phase |
-| `tdd_mode` | `tdd` or `direct`. Full workflow must select before leaving build. `tdd` forces write-failing-test-first per task; `direct` skips TDD enforcement. hotfix/tweak default to `direct` |
-| `isolation` | `branch` or `worktree`, workspace isolation mode. Full init may be `null` but only until `/comet-build` Step 3; hotfix/tweak default to `branch` |
+| `tdd_mode` | `tdd` or `direct`. Full workflow must select before leaving build. `tdd` forces write-failing-test-first per task; `direct` skips per-task TDD but still requires relevant tests and bug-regression evidence. hotfix/tweak default to `direct` |
+| `review_mode` | `off`, `standard`, or `thorough`. Full workflow must select before leaving build; hotfix/tweak default to `off` |
+| `isolation` | `current`, `branch`, or `worktree`. Full init may be `null`, but before leaving build the user must explicitly select `current`, create/select a real `branch`, or create/select a real `worktree`; hotfix/tweak may also truthfully use all three modes after the entry user decision point, and must not claim branch isolation before creating one |
+| `bound_branch` | Workspace branch binding record; may be empty. `isolation: current` / `branch` / `worktree` records the current Git branch of the directory the command runs in on first setting or entry check (for worktree mode, run set/check/guard inside that worktree, or the wrong branch gets bound/compared); switching `isolation` between workspace modes re-binds to the current branch, while repeating the same mode keeps the existing binding. Later `comet state select` / `comet state check` must confirm the bound branch still matches the current branch. On drift, `select` refuses and checks return `BLOCKED`; follow the decision-point protocol so the user chooses whether to switch back to the bound branch or explicitly confirm and run `comet state rebind <change-name>`. Clearing `isolation` clears this field |
 | `verify_mode` | `light` or `full`; may be empty |
 | `auto_transition` | `true` or `false`. Only controls whether to automatically invoke the next skill after phase guard advances phase; `false` outputs `manual` from `comet-state next`, pausing next-skill invocation but not blocking phase field updates |
 | `verify_result` | `pending`, `pass`, or `fail` |
+| `verify_failures` | Machine-owned consecutive verification failure count. `verify-fail` increments it; `verify-pass` or `archive-reopen` resets it to `0`. At `3`, the next failure requires the retry-limit strategy decision |
 | `verification_report` | Verification report file path; must point to an existing file before verify passes |
-| `branch_status` | `pending` or `handled`; set to `handled` after branch handling completes |
+| `branch_status` | `pending` or `handled`; keep `pending` through verify. After the user confirms immediate remote delivery before archive, set `handled` when archive finishes and include it in the only archive commit. `handled` means only that the delivery method is confirmed, not that push or PR creation succeeded; clear current selection and report workflow completion only after remote operations succeed |
 | `created_at` | Change creation date (auto-written at init), format `YYYY-MM-DD` |
 | `verified_at` | Verification pass timestamp; may be empty |
+| `archive_confirmation` | `null`, `pending`, or `confirmed`. `verify-pass` writes `pending` when entering the archive phase; after the user selects either "confirm archive and deliver remotely now" choice in `/comet-archive`, the `archive-confirm` transition writes `confirmed`; `archive-reopen` clears the field so an earlier confirmation cannot be reused |
 | `archived` | Whether the change has been archived |
 
 ## Optional Fields
@@ -54,15 +66,16 @@ archived: false
 | Field | Meaning |
 |-------|---------|
 | `direct_override` | `true`/`false`. Full workflow must explicitly set to `true` to use `build_mode: direct` |
-| `build_command` | Project build command. Guard runs this first; prints command output on failure |
-| `verify_command` | Project verify command. Verify guard runs this first; falls back to build command when unset |
 
 ## State Machine Hard Constraints
 
-- Before `build → verify`, `isolation` must be `branch` or `worktree`
+- Before `build → verify`, `isolation` must be `current`, `branch`, or `worktree`
 - Before `build → verify`, `build_mode` must be selected
 - `build_mode: subagent-driven-development` requires `subagent_dispatch: confirmed`
 - Full workflow must select `tdd_mode` as `tdd` or `direct` before leaving build
+- Full workflow must select `review_mode` as `off`, `standard`, or `thorough` before leaving build
 - `build_mode: direct` defaults to `hotfix`/`tweak` only; full workflow requires `direct_override: true`
 - `build_pause` is not an execution mode; must not be written to `build_mode`
-- These constraints exist in both `comet-guard.sh build --apply` and `comet-state.sh transition <name> build-complete`
+- These constraints exist in both `comet-guard.mjs build --apply` and `comet-state.mjs transition <name> build-complete`
+- `archive_confirmation` is machine-owned and can only be updated by the `verify-pass`, `archive-confirm`, and `archive-reopen` transitions; it cannot be forged with `set`, and both the `archived` transition and the mutating archive command require `confirmed`
+- `preset-escalate` event: only allows `hotfix`/`tweak` workflow at `phase: build`; atomically sets `workflow`/`classic_profile` to `full`, rewinds `phase` to `design`, and clears `design_doc` (satisfying the comet-design entry requirement). This is the only legal channel for a preset → full upgrade — direct `set phase design` is hard-blocked by the state machine, and `set classic_profile` is a machine-owned field that cannot be set manually

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

@@ -4,10 +4,30 @@ Canonical path: `comet/reference/context-recovery.md`
 
 This protocol is shared by all comet sub-skills that may trigger context compression. When the agent suspects context compression has occurred (previous conversation summarized, cannot find previously discussed content), follow this protocol to recover.
 
+## Any-Entry Recovery Principle
+
+The user may resume the workflow directly from `/comet-open`, `/comet-design`, `/comet-build`, `/comet-verify`, `/comet-archive`, `/comet-hotfix`, or `/comet-tweak`. On entry to any sub-skill, first locate scripts via `comet/reference/scripts.md`, then run the entry check or recovery check for that sub-skill's phase. Do not infer phase from conversation history.
+
+```bash
+comet state check <change-name> <phase> --recover
+```
+
+If the check shows the actual phase, workflow, or evidence belongs to another skill, switch according to script output and `/comet-classic` routing rules; do not keep writing state in the wrong phase. If the worktree has uncommitted changes, attribute them first via `comet/reference/dirty-worktree.md`.
+
+## Recovery Without Explicit `/comet-classic`
+
+If the user did not mention `/comet-classic`, but this repository may have an active change, run the Ambient Resume probe before starting work that may need code changes or investigation. First locate scripts via `comet/reference/scripts.md` and ensure `$COMET_RESUME_PROBE` is available, then pass the current user request on stdin:
+
+```bash
+node "$COMET_RESUME_PROBE" probe --stdin
+```
+
+Only `auto_resume` should resume automatically; `ask_user` must ask one short question; `out_of_scope` and `none` do not enter the workflow.
+
 ## Recovery Steps
 
 ```bash
-"$COMET_BASH" "$COMET_STATE" check <change-name> <phase> --recover
+comet state check <change-name> <phase> --recover
 ```
 
 The script outputs structured recovery context (phase, completed fields, pending fields, recovery action). Follow the **Recovery action** output for next steps.
@@ -18,10 +38,10 @@ If the recovery script outputs `build_mode: subagent-driven-development`:
 
 1. Use the Skill tool to reload the Superpowers `subagent-driven-development` skill
 2. Re-read `comet/reference/subagent-dispatch.md` for Comet-specific extensions
-3. Read `openspec/changes/<name>/.comet/subagent-progress.md` to recover the current task or final review, implementation commit, RED/GREEN evidence, passed reviews, unresolved feedback, and review-fix round
+3. Read `<classic-change-dir>/.comet/subagent-progress.md` to recover the current task or final review, implementation commit, RED/GREEN evidence, passed reviews, unresolved feedback, and review-fix round
 4. Do not execute tasks directly in the main session
 5. Resume from the checkpoint's exact stage; begin implementer dispatch for the first unchecked task only when the checkpoint is missing or mismatched
-6. After dual review and targeted checkoff verification pass, immediately continue to the next task without summarizing or asking whether to continue
+6. After `review_mode` validation and targeted checkoff verification pass, immediately continue to the next task without summarizing or asking whether to continue
 
 ## Design Phase Special Recovery
 

package/assets/skills/comet/reference/debug-gate.md

@@ -14,4 +14,20 @@ This protocol is shared by comet sub-skills that directly modify code, including
 1. Reproduce and locate the root cause first by reading the full error, checking recent changes, and tracing data flow
 2. If the root cause is a source bug, first add a minimal failing test that reproduces the crash or unexpected behavior, then modify the source
 3. After the fix, run that failing test, related tests, and the project's build or verification commands until all pass
-4. Keep the test, the source fix, and the tasks.md checkoff in the current change; do not replace the current change verification loop by starting a separate “write test cases” change
+4. Keep the test, the source fix, and the tasks.md checkoff in the current change; do not replace the current change verification loop by starting a separate “write test cases” change
+
+## Parallel Investigation of Multiple Failures
+
+Before entering the four-stage flow, run a failure-independence assessment to decide serial vs. parallel investigation:
+
+- **No parallelism (keep existing serial `systematic-debugging`)**: ≤ 2 failures; failures are related (fixing one might fix others); shared state; would touch the same set of files; failure independence not yet established
+- **Parallel (load the Superpowers `dispatching-parallel-agents` skill)**: ≥ 3 failures from distinct problem domains (different test files with different root causes, different subsystems broken independently), mutually independent and non-interfering
+
+When parallel conditions are met:
+
+1. Immediately use the Skill tool to load the Superpowers `dispatching-parallel-agents` skill
+2. Dispatch one background investigation agent per independent failure, grouped by problem domain, with all dispatches in a single response for concurrent execution. Each agent prompt must be self-contained (specific failure, error messages, allowed investigation scope, prohibition on touching other problem domains' code)
+3. All agents remain bound by this protocol's "no source changes before the root cause is identified" constraint; they only locate the root cause and return findings — **they do not submit fixes directly**
+4. Once all investigations return, the main session serially consolidates findings and performs fixes; fixes still go through the current `review_mode` verification and review loop
+
+> Parallelism applies only to **investigation**. Fixes are always serial, avoiding conflicts from multiple agents editing the same set of files at once — consistent with the `subagent-driven-development` red flag of "never dispatch multiple implementation subagents in parallel."