> ## Documentation Index
> Fetch the complete documentation index at: https://docs.comet.rpamis.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Changelog
> Comet release notes.
Comet release notes are grouped on one Mintlify Update timeline so each version can be maintained in one changelog page.
Beta 14 fixes configuration compatibility and scope handling in project updates, setup, and uninstall so existing projects are easier to maintain safely.
### Fixed
* **Incomplete project configuration**: `comet update` and Classic root commands now fill missing Native defaults instead of rejecting projects whose remaining configuration is usable.
* **Update scope**: Selecting the current project now refreshes only that project. When no indexed project is available, `comet update` explains that state instead of changing global installations.
* **Classic initialization compatibility**: Adding Classic to an existing Native project retains a root-level `openspec/` layout when present, and initialization works on filesystems such as exFAT that do not support hard links.
* **Codex OpenSpec Skills**: Project initialization now installs OpenSpec Skills generated for Codex into its canonical `.agents/skills/` directory.
* **Uninstall selection and completion**: Project uninstall uses the same batch platform selection as setup and retains unselected platforms. Selected Superpowers companion Skills are removed, preserving user working-directory content no longer reports an incomplete uninstall, and real cleanup failures show their reason in the selected language.
Beta 13 makes everyday workflow operations faster and makes uninstalling and reading Dashboard status easier.
### Added
* **Native receipt refresh**: New `comet native receipt refresh [--apply]` checks stale verification receipts and reissues eligible manual receipts. Automated checks that need a real rerun remain clearly identified instead of being marked as passed.
### Changed
* **Selective workflow removal**: Interactive `comet uninstall` now lets you remove Native, Classic, or both from each installed target. Removing one retains the other workflow and shared configuration; when removing Classic, OpenSpec and Superpowers Skills are optional and remain selected off by default.
* **Everyday responsiveness**: CLI startup, Classic and Native workflow commands, write checks, and Native snapshot updates are faster. Native reuses results for unchanged files while continuing to inspect real changes.
* **Fast public workflow commands**: High-frequency Native, Classic, and workflow-resolution commands keep the stable `comet` CLI interface while dispatching internally to package-owned runtime bundles, reducing cold-start overhead without relying on host-specific Skill paths.
* **Dashboard workspace**: Dashboard offers clearer project switching, search, and change-detail views, discovers projects launched from nested directories, and presents Classic changes from legacy and docs layouts alongside the separate read-only Native workspace.
### Fixed
* **Classic configuration compatibility**: Setup and update retain an existing Classic project’s directory choice and more reliably recognize a usable directory when an older project configuration is incomplete.
* **Portable workflow execution**: Native and Classic Skills now call the public `comet` CLI instead of searching platform-specific Skill directories or invoking internal bundles. Missing CLI installations stop with a clear error, while workflow routing still immediately loads the selected Skill through the Skill tool.
* **Classic execution choices**: Classic now presents every workflow-supported isolation and execution choice, then runs the user’s selection and reports any error instead of pre-screening options.
* **Dashboard status feedback**: Classic change verification uses green, red, amber, and neutral status colors for pass, fail, pending, and unknown states; invalid Dashboard ports now fail with a clear error before startup.
### Security
* **Classic phase protection**: Host configuration directories and worktrees no longer bypass Classic phase restrictions, preventing source writes hidden under paths such as `.claude/` during non-Build phases.
* **Dashboard build dependency**: Updated the Dashboard CSS build dependency to prevent untrusted source-map references from reading unintended reachable map files.
Beta 12 simplifies Classic root migration and Dashboard discovery while narrowing Native verification evidence, repair interactions, and recovery guidance.
### Changed
* **Classic root migration**: `comet classic root move docs --dry-run` reports current state, conflicts, and blockers directly instead of issuing a plan ID. `--apply` migrates the complete `openspec/` tree, including active and incompletely archived changes, without a plan ID. Output follows `classic.language`, and projects already using `docs/openspec/` receive an explicit no-op result.
* **Native workflow guidance**: Native identifies the current change and phase before loading the corresponding reference, and always completes Shape classification, silent-assumption checks, and shared-understanding confirmation before implementation. When a new user decision appears in Build, Native pauses implementation, clarifies and confirms the updated requirement, then continues. Project and change commands are organized by task to reduce unrelated guidance.
* **Native verification and repair**: Passing Verify automatically runs and binds the built-in required check. Acceptance evidence can come from manual observations or project commands executed by the Runtime, with Windows shim support and credential-like output redaction. Runtime derives repair gaps from failed evidence; the Agent must supply a concrete new repair hypothesis while one override remains, and only an exhausted override or verification budget returns one explicit user decision.
### Fixed
* **Classic Dashboard discovery**: Dashboard now locates the repository root when launched from a nested directory and reads Classic changes according to `classic.artifact_layout`. Collection failures are shown as errors instead of an empty workspace.
* **Explicit Comet Skill routing**: `/comet` enters only when you explicitly invoke it or ask to use Comet without choosing Native or Classic. The entry follows project configuration into Native or Classic and preserves the original request instead of reassessing relevance or selecting a workflow by task size.
* **Stale current-change selection**: When the current selection points to a missing or archived change, Comet checks active changes again: with no candidate, ordinary work can continue; one candidate is available for read-only recovery; and multiple candidates still require an explicit selection.
* **Native baseline recovery guidance**: Incomplete-baseline diagnostics now identify `native.snapshot.max_files` alongside total-byte and duration budgets, so file-count limits point to the relevant configuration.
### Removed
* **Native cryptographic review**: Removed controller trust, signing identities, implementation attestations, independent-review and waiver receipts, and their CLI and Eval handoff paths. Native now depends on complete acceptance evidence and the built-in required check bound to the current revision, contract, scope, snapshot, and artifacts.
* **Redundant Native CLI inputs**: Removed the `comet native list` alias; manual-receipt `--responsible` and `--confirmed` options; and caller-supplied `next --receipt`, `--evidence-receipt`, `--failure-category`, and `--failed-check` inputs. Use `status` without a change name for discovery and reference acceptance receipts in `verification.md`; active changes that still hold v2 receipts must record fresh schema-v3 evidence.
Beta 11 simplifies Native change creation and completes project configuration defaults during setup and updates.
### Changed
* **Project configuration defaults**: New Classic configurations default to `classic.artifact_layout: docs`. `comet update` fills missing managed Native and Classic fields, retaining `legacy` only when an existing root-level `openspec/` project must be preserved.
* **Risk-based Native review**: Independent review is driven by the actual implementation scope and risk instead of a creation-time signing mode. Ordinary changes can start immediately, while high-risk verification remains fail-closed.
### Removed
* **Native creation authorization**: `comet native new` no longer requires `--creation-authorization`; the `signed-v2` creation protocol and `comet native trust authorize` have been removed.
Beta 10 introduces Native Loop, gives Classic a configurable and migratable documentation layout, and repairs the local workflow Eval and Creator Bundle compatibility path.
### Added
* **Targeted platform setup**: `comet init` and `comet update` now accept `--platform `, so you can install or refresh one supported or project-defined platform without changing other platforms. Omitting the option preserves automatic detection and fallback behavior.
* **CodeGraph index lifecycle**: Non-interactive project setup can explicitly choose `comet init --codegraph init|skip`. `comet doctor` distinguishes a missing CLI, missing index, incomplete index, stale index, and ready index; only authorized `comet doctor --repair --yes` runs initialization, rebuild, or sync actions ([#245](https://github.com/rpamis/comet/issues/245)).
* **Classic configurable artifact layout**: Projects can select `classic.artifact_layout: legacy|docs` for `openspec/` or `docs/openspec/`. `comet classic root show` reports the active layout, while `comet classic root move docs --dry-run` and `--apply` safely migrate existing artifacts and configuration ([#173](https://github.com/rpamis/comet/issues/173)).
* **Native evidence-backed verification**: Every mandatory acceptance item must be supported by current evidence bound to the active snapshot and scope. Native records automated checks, manual observations, implementation attestations, independent review, and approved structured waivers. Failed, skipped, blocked, stale, or incomplete evidence cannot produce a pass, and high-risk changes require independent review ([#240](https://github.com/rpamis/comet/issues/240)).
### Changed
* **Classic documentation layout**: New Classic and dual-workflow projects store OpenSpec artifacts in `docs/openspec/` beside `docs/comet/` and `docs/superpowers/`. Existing projects keep root-level `openspec/` until explicitly migrated, and all Classic commands follow the selected layout ([#173](https://github.com/rpamis/comet/issues/173)).
* **Native Loop**: Failed or missing acceptance items and failed checks return to Build as explicit repair input. Only fewer gaps, passing checks, or restored evidence count as progress; implementation churn alone does not reset stagnation or the failure budget. Native continues Build ↔ Verify until the contract is satisfied or a stop condition returns control to the user ([#209](https://github.com/rpamis/comet/issues/209), [#242](https://github.com/rpamis/comet/issues/242)).
* **Native archive confirmation**: Set `native.archive_confirmation: required` to request one explicit decision for the final Archive candidate, or keep automatic archiving. Intermediate repair iterations never request archive confirmation, and choosing not to archive preserves the active change ([#238](https://github.com/rpamis/comet/issues/238)).
* **Native progressive guidance**: Native entry instructions keep the active phase, acceptance gaps, and next action prominent, loading detailed clarification, command, artifact, and recovery guidance only when needed.
### Fixed
* **Classic archive references**: Archive rewrites change-local handoff and related artifact references to the dated archive location, verifies them before reporting success, and preserves the handoff hash. Archived changes no longer require manual `.comet.yaml` repair ([#244](https://github.com/rpamis/comet/issues/244)).
* **Secondary worktree diagnostics**: `comet doctor` distinguishes current-worktree assets, primary-worktree-only assets, and an available global fallback. Intentionally absent ignored assets in a secondary worktree are no longer reported as project corruption ([#246](https://github.com/rpamis/comet/issues/246)).
* **Local Eval execution environment**: Local task images include the required Claude Code runner and run as a non-root user, allowing quick and full Eval to identify the execution environment and start the runner reliably ([#229](https://github.com/rpamis/comet/issues/229)).
* **Local Eval validators**: Copied lightweight validators can reliably load their bundled scaffold runtime. Workflow Eval uses tasks that match the workflow contract, while no-Skill CONTROL results remain observational data instead of incorrectly blocking a valid Dynamic Skill result ([#229](https://github.com/rpamis/comet/issues/229)).
* **Creator Bundle portability**: Creator-generated workflow Bundles persist project-relative evidence paths and use platform-neutral authoring guidance. A Claude-specific custom Agent is no longer treated as a required Codex runtime capability, and successful local Eval results are recorded as evidence for the current Bundle ([#229](https://github.com/rpamis/comet/issues/229)).
### Security
* **Native approval isolation**: Signed Native workflows keep approval credentials outside the project and implementation Agent, preventing a project change from granting itself approval authority ([#240](https://github.com/rpamis/comet/issues/240)).
### Added
* **Sequential clarification evaluation**: Adds a repeatable multi-turn Native evaluation that checks whether Sequential investigates repository facts, resolves dependent user-owned decisions one at a time, records each answer, confirms a complete shared understanding before Build, and finishes verified implementation. Task-defined reply sequences keep decision paths reproducible instead of allowing the simulated user to invent additional choices.
* **`comet native evidence format`**: New command that serializes acceptance evidence entries into the exact canonical Markdown block `verification.md` requires, so evidence blocks no longer need to be hand-formatted to match byte-for-byte and no longer trigger spurious "canonical serialization" rejections during Verify.
### Changed
* **Native clarification modes**: Sequential now recalculates remaining user-visible decisions after each answer and asks exactly one most-upstream decision with a recommendation and impact per round. Batch maintains a prerequisite-aware decision tree, asks the entire ready frontier each round, and keeps environment-fact investigations from delaying other ready questions when parallel work is available. Both modes require every behavior in the final shared-understanding summary to be traceable, and Runtime enforces explicit confirmation before Build; older `implicit` changes must also confirm before leaving Build.
### Fixed
* **Native baselines for large repositories**: Native content snapshots now support baseline-bound include/exclude policies and configurable file-count, total-byte, and duration budgets in `.comet/config.yaml`, with a 256 MiB default total budget and no separate 5 MiB per-file cap. Runtime continues to hash actual working-tree content with streaming SHA-256, records the effective policy and limits for audit, and reports actionable configuration fixes when a complete baseline cannot be captured ([#226](https://github.com/rpamis/comet/issues/226)).
* **Global workflow selection**: `comet init` now offers Native, Classic, or both for global installs and accepts `--scope global --workflow native|classic|both`, so global Skill installation exposes the same workflow choices as project scope while preserving Classic as the non-interactive default when no workflow is specified ([#234](https://github.com/rpamis/comet/issues/234)).
* **Explicit Comet Skill invocation**: Ambient Resume project instructions now give host-recognized manual Comet Skill invocations precedence over recovery probing, preventing `none` or `out_of_scope` results from skipping `/comet` when no active change exists ([#235](https://github.com/rpamis/comet/issues/235)).
* **Classic archive final state**: Classic now confirms immediate remote delivery before irreversible archiving, writes `branch_status: handled` before the one archive commit, and pushes that complete commit only once. A successful archive no longer leaves an uncommitted `.comet.yaml` or a remote archive stuck at `pending` ([#237](https://github.com/rpamis/comet/issues/237)).
* **Plugin marketplace superpowers detection**: `comet init` no longer crashes with an `ENOTDIR` error when `~/.claude/plugins/cache/` (or the Codex equivalent) contains a stray file where a marketplace directory was expected.
### Security
* **Race-safe file reads**: Reading `.comet/current-change.json` (used on every Hook Router call, `comet doctor`, and `comet resume-probe`), Native lock files, and `comet native evidence format --entries` input could previously be tricked mid-read: swapping the file for a symlink between the check and the read leaked the link target's content, and a FIFO at the lock path hung the process. These reads now reject non-regular files before opening and verify the file is still the same one after opening and after reading, so a swapped file fails the read instead of being silently accepted. Windows, which lacks `O_NOFOLLOW`, gets the same protection through the identity checks.
Beta 8 is a bug-fix and security-hardening release. It does not add commands, configuration, or workflow behavior.
### Fixed
* **Windows Native file validation**: When Windows path metadata and file-handle metadata expose different availability for device or inode identifiers, `comet status`, `comet doctor`, and other Native reads no longer report stable files as `changed while opening`. Replacement and in-flight mutation checks remain enforced.
### Security
* **Development dependency hardening**: npm and pnpm resolutions now pin `brace-expansion` to the patched 5.0.7 release, preventing malicious brace patterns from causing exponential CPU consumption in the development toolchain.
* **Classic handoff validation**: The runtime now validates recorded handoff source paths with exact line matching instead of treating project-controlled spec directory names as regular expressions, preventing malformed names from crashing or stalling the Classic design guard.
If you are upgrading from Beta 6, the most visible change is the addition of Comet Native. It is designed for strong models that can handle complex coding work but still need structured clarification, state, verification, and archive evidence. Native does not replace Classic. You can keep using Classic or install both workflows in the same project.
### Added
* **Comet Native workflow**: Adds an independent `/comet-native` workflow with no dependency on OpenSpec, Superpowers, or another external Skill. It uses Shape, Build, Verify, and Archive phases, with recoverable checkpoints, complete target specifications, and separate change state. Clarification defaults to `sequential`, which asks one upstream question per round. You can switch to `batch` to answer all currently independent questions together. See [Native workflow](https://docs.comet.rpamis.com/en/concepts/native-workflow) and [Native quickstart](https://docs.comet.rpamis.com/en/native/quickstart).
* **Native versus Classic real-world evaluation**: Both workflows ran the same **16 business tasks** three times each, for **96 runs total**. Native reached **95.83% strict pass\@1** versus **89.58%** for Classic. Both reached **100% pass\@3**, while Native reached **87.5% pass^3** versus **75%** for Classic. Native's **corrected mean model duration was 47.8% lower**. Across the **41 paired samples** where both passed strictly, Native used **76.8% fewer total tokens** and **cost 75.1% less**. The duration results come from different runtime windows, so treat them as directional evidence. See the [full comparison report](https://docs.comet.rpamis.com/en/eval/comet-native-vs-040-experiment).
* **Native clarification-mode evaluation**: Batch and Sequential each ran **10 times** on the same task. Batch reduced mean outer interactions from **4.5 to 2.7, a 40% decrease**, and reduced mean cumulative model duration from **712 seconds to 617 seconds, a 13.3% decrease**. However, Batch reached **60% strict pass\@1** versus **70%** for Sequential. This is a small, single-task sample. It shows an efficiency-reliability tradeoff and does not establish Batch as more reliable. See the [clarification-mode evaluation](https://docs.comet.rpamis.com/en/eval/comet-native-clarification-experiment).
* **Selectable Eval suites**: `comet eval --suite local|langsmith` selects local or LangSmith evaluation. Local remains the default. LangSmith uses the same tasks and scoring logic, while Comet selects the tracing runner, report directory, and Claude Code tracing plugin.
### Changed
* **Project workflow selection**: Project-level `comet init` now offers Native, Classic, or Both. New projects default `/comet` to Native, and Native artifacts default to `docs/comet/`. Both installs two independent workflows without mixing their changes, state, or artifacts.
* **Separate entries, status, and recovery**: `/comet-native` and `/comet-classic` are stable entries, while `/comet` selects one from project configuration. `comet status`, `comet resume-probe`, and Dashboard display and recover Native, Classic, and unmanaged OpenSpec changes separately. Projects with both workflows no longer block the same write twice.
* **Native execution and recovery boundaries**: Native records a complete project baseline before editing and binds implementation scope, acceptance criteria, and verification reports to the change. Incomplete snapshots do not infer file deletions. Verification stops retrying after repeated failures without genuine code progress. Interrupted work can recover state, archives, and artifact-root moves.
* **Node.js runtime requirement**: Beta 7 requires Node.js 22 or newer. Check local, CI, and Docker runtimes before upgrading.
* **Updates no longer change the npm package implicitly**: Running `comet update` in the current project refreshes only Comet-managed project assets. Use `comet update --self-update` to update the CLI as well. Updates validate the full prerelease version, refuse downgrades, and attempt to restore the previous version after installation failure. Classic settings migrate into the `classic:` block in `.comet/config.yaml`, while existing explicit values remain unchanged.
### Fixed
* **Init and update results**: `comet init` and `comet update` return non-zero exits when work is incomplete and preserve npm diagnostics. Batch updates distinguish failed projects from unattempted projects. Component failures no longer end with a success banner.
* **OpenSpec version diagnostics**: If the installed OpenSpec CLI is too old and you decline the optional upgrade, setup reports the version requirement instead of saying the CLI is unavailable.
* **Windows and parallel Eval runs**: Windows Docker interactive evaluations prefer Git Bash, preserve prompt paths inside containers, and count actual driver turns. Parallel workers wait for the shared Docker build lock instead of reporting normal concurrency as a resource deadlock.
### Added
* **`comet state rebind`**: After the user explicitly confirms that the current branch should take over a change, the new command rebinds the working branch and records an audit event. It refuses to run before an initial binding exists or while HEAD is detached.
### Changed
* **Workspace branch binding**: All three isolation modes — `current`, `branch`, and `worktree` — record the Git branch on which they were established. Later branch switches are blocked by build, verify, and archive entry checks and by the source-write guard; selecting a drifted change fails instead of silently replacing the binding. Legacy changes bind on their next select or check, and non-Git worktrees are unaffected.
* **Workspace isolation choice**: Full, hotfix, and tweak workflows now ask users to explicitly keep the current branch, create a branch, or create a worktree instead of choosing silently. Full workflows now also support `isolation: current` ([#190](https://github.com/rpamis/comet/issues/190)).
* **Status and archive guidance**: `comet status` text and JSON output show the isolation mode and bound branch. Archiving `current` isolation asks only whether to push the current branch or keep it local instead of showing feature-branch merge/PR choices.
### Fixed
* **Skill discovery resilience**: Malformed YAML frontmatter in an unrelated local Skill no longer interrupts Bundle Factory guidance or candidate discovery; Comet skips the broken description and continues scanning.
### Changed
* **Skill trigger and decision authoring**: Built-in phase Skills and Creator-generated internal Node Skills declare clear entry and Runtime boundaries. Creator separates automatic handling, stop conditions, and manual handoffs before generating pauses, reducing unnecessary internal Skill calls and user prompts.
* **Workflow checkpoints**: Clear requests skip redundant naming confirmation, Build preflights executable capabilities and combines adjacent configuration decisions, and large PRDs use recoverable batch manifests so resume does not depend on unwritten chat state.
* **Verification repair and archive ownership**: The first three actionable verification failures return automatically to Build with counts preserved across resume. Verify records evidence, while Archive commits only attributed paths before branch handling so the final branch contains specifications and archive metadata.
* **Preset execution semantics**: Hotfix and Tweak record truthful current-workspace isolation, retain regression tests in direct mode, and clear lightweight execution settings after upgrading to the full workflow.
* **Dashboard artifact preview**: Markdown preview supports tables, quotes, task lists, syntax highlighting, and Mermaid. Fullscreen TOC, duplicate-heading anchors, long-path copy, and structured YAML/JSON tables are handled consistently.
### Fixed
* **OpenSpec compatibility**: Requires OpenSpec 1.5+, drives `/comet-open` from the live schema, validates project-relative paths and concrete outputs, and resumes split batches without recreating completed changes.
* **Codex hook configuration**: Project and global Codex installs write supported `.codex/hooks.json` and safely migrate older Comet-managed configuration ([#199](https://github.com/rpamis/comet/issues/199)).
* **Standard Superpowers artifacts**: Classic write guards accept first-time design, plan, and verification artifacts in standard directories while preserving phase, selection, and duplicate-slot checks.
* **Skill lifecycle integrity**: Init, update, Doctor, and uninstall report Skill, Rule, and Hook failures consistently, preserve damaged user Hook configuration, and avoid registering partial installs as successful.
### Security
* **Dashboard preview XSS hardening**: Markdown/YAML/JSON preview uses DOMPurify, blocks dangerous URLs and attribute injection, and runs Mermaid in strict security mode so untrusted artifacts cannot execute scripts.
### Added
* **Ambient resume probing**: Adds a low-noise resume probe and managed project guidance so agents can decide whether a natural-language request should resume an active workflow even when the user does not explicitly invoke `/comet`. Ambiguous changes, dirty worktrees, and decision points still pause for confirmation.
* **Project installation registry**: Project-scope installs are recorded in a user-level registry. Interactive `comet update` and `comet uninstall` can target the current project or all indexed projects; `--json` and explicit `--current-project` stay local, `comet uninstall --force` also stays local, and cross-project operations require `--all-projects`.
* **Stable Classic commands**: Adds top-level `comet state`, `comet guard`, `comet handoff`, and `comet archive` commands so agents and automation no longer depend on internal installed script paths ([#186](https://github.com/rpamis/comet/issues/186)).
* **Custom project command evidence**: Projects without an inferred npm, Maven, or Cargo command can record the real build or verification command and exit result as auditable evidence instead of relying on an undocumented skip path ([#192](https://github.com/rpamis/comet/issues/192)).
* **CodeBuddy hook support**: Project-level and global CodeBuddy Code installs non-destructively merge the Comet PreToolUse hook into `.codebuddy/settings.json`, preserving existing plugins, settings, and hooks. Invalid configuration is reported explicitly and left byte-for-byte unchanged ([#193](https://github.com/rpamis/comet/issues/193)).
### Changed
* **Mixed change status**: `comet status` now distinguishes Comet-managed changes from plain OpenSpec changes and recommends the appropriate archive command only for ready entries ([#187](https://github.com/rpamis/comet/issues/187)).
### Fixed
* **Parallel active-change guards**: Source-write hooks bind work on a branch or worktree to the explicitly selected current change. Legal build work is no longer blocked by another change in open, design, or archive, while ambiguous selection fails with an actionable prompt ([#196](https://github.com/rpamis/comet/issues/196)).
* **Codex CLI Skill discovery**: Codex project and global installs place Comet Skills in `.agents/skills` while Codex-specific config remains under `.codex`. Update and uninstall migrate Comet-managed legacy `.codex/skills` content without removing unrelated Skills.
* **Generated Eval manifests**: `comet eval` resolves a Skill Factory `draftHash` placeholder into a temporary manifest bound to the current Bundle draft, so `/comet-any` output can be evaluated without rewriting generated Bundle files ([#183](https://github.com/rpamis/comet/issues/183)).
* **Eval harness lookup**: npm-installed `comet eval` uses the version-matched bundled harness by default and reports a missing harness separately from a missing `uv` executable.
* **Indexed project updates**: `comet update --all-projects` records npm update failures against the affected project and fails explicitly when the project registry cannot be read.
* **Responsive Dashboard workspace**: `comet dashboard` keeps the change workspace within the viewport, preserves scroll position around artifact previews, and shows archived changes as complete instead of recommending verify again ([#170](https://github.com/rpamis/comet/issues/170)).
* **Symlink installs with existing Skills**: `comet init` and `comet update --install-mode symlink` preserve an existing platform `skills/` directory and add links only for Comet Skills, so local and third-party Skills do not make installation fail ([#171](https://github.com/rpamis/comet/issues/171)).
* **OpenSpec CLI install scope**: `comet init` installs or upgrades OpenSpec CLI as a global tool even during project-scope setup, avoiding a project `node_modules/` directory for that dependency ([#175](https://github.com/rpamis/comet/issues/175)).
* **Archived Dashboard artifacts**: The Dashboard resolves archived `docs/superpowers/` pointers from the project root, so Design Docs, Plans, and verification reports remain available after archive ([#176](https://github.com/rpamis/comet/issues/176)).
* **Final archive confirmation**: `/comet-archive` records final user approval in machine-owned Classic state, and a mutating archive refuses to run until that transition succeeds.
* **Archive annotation formatting**: Classic archive annotations remain idempotent and preserve a clean Markdown EOF, preventing `git diff --check` failures ([#185](https://github.com/rpamis/comet/issues/185)).
* **Global artifact language**: Global `comet init` and `comet update` persist the selected artifact language in `~/.comet/config.yaml`. Classic workflows prefer project config and then fall back to the global default, while projects can still override it ([#174](https://github.com/rpamis/comet/issues/174)).
### Fixed
* **Doctor scope diagnostics**: `comet doctor` now reports auto-scope behavior, Node/platform environment details, and a non-alarming project-scope note when a global Comet install is available but the current project has no local Skill copy, so users can distinguish an optional project install from a broken setup.
* **PowerShell Classic initialization**: `comet-state.mjs init` now writes its successful initialization message to stdout instead of stderr, so Windows PowerShell no longer reports a successful `.comet.yaml` creation as a `NativeCommandError` ([#167](https://github.com/rpamis/comet/issues/167)).
* **Version flag alias**: `comet -v` now works as a short alias for `comet --version`, matching common CLI expectations on Windows and other shells ([#167](https://github.com/rpamis/comet/issues/167)).
* **Classic runtime fallback**: Classic phase scripts now keep an embedded runtime package fallback, so `comet-guard.mjs`, handoff, and archive flows continue to run even when a platform installation is missing the internal `runtime/classic` asset files ([#168](https://github.com/rpamis/comet/issues/168)).
* **Project config lookup**: Classic guards now resolve project defaults only from `.comet/config.yaml`, while workflow state remains in each change's `.comet.yaml`. Repository-root `.comet.yaml` and `comet.yaml` files no longer participate in config or state resolution ([#158](https://github.com/rpamis/comet/issues/158)).
### Removed
* **Custom guard command fields**: Classic workflow state no longer accepts `build_command` or `verify_command`; guards use the built-in project build detection path instead, and old fields are rejected as unknown.
### Fixed
* **Single-language rule install**: `comet init` and `comet update` now install only the Comet phase-guard rule file matching the selected/detected Skill language (e.g. `.claude/rules/comet-phase-guard.md`), instead of always installing both the Chinese and English rule variants side by side regardless of language choice.
* **Symlink install safety**: `comet init` and `comet update` now refuse to replace an existing platform `skills/` directory with a symlink when it contains files outside Comet's managed manifest, preserving local or third-party Skills instead of deleting them during symlink-mode installs ([#159](https://github.com/rpamis/comet/issues/159)).
* **Parallel change artifact writes**: Classic phase guards now route `docs/superpowers/` writes to the matching design/build/verify change instead of letting an unrelated earlier active change block shared Design Doc and planning artifacts ([#160](https://github.com/rpamis/comet/issues/160)).
This is the first beta of the 0.4.0 line. Relative to 0.3.9, Comet becomes a cross-platform Node runtime and expands from a `/comet` workflow bundle into a workflow, Skill creation, eval, and dashboard platform. The notes below describe the final user-visible release shape, not the branch work history.
### Highlights
* All Comet scripts now run through Node.js on macOS, Linux, and Windows without requiring Bash, Git Bash, or WSL.
* `/comet-any` Skill Creator now generates stable composable Skill bundles with reviewable authoring evidence, publish gates, and platform-native files.
* `comet eval` can measure arbitrary local Skills and Comet workflows with pass\@k/pass^k reliability metrics and HTML reports.
* `comet init` now records project-level artifact language, and OpenSpec/Superpowers artifacts follow that configured language.
* `comet dashboard` adds a local read-only browser view for phases, artifacts, tasks, and risks.
* `/comet` uses structured routing context so risk signals take precedence over loose conversational flow.
### Added
* **Cross-platform Classic runtime**: Bundled `/comet` workflow scripts now run through Node `.mjs` launchers backed by the TypeScript Classic runtime, so the same workflow works on Windows, macOS, and Linux without requiring Git Bash, WSL, or shell-compatible scripts.
* **`comet dashboard`**: Adds a local read-only browser dashboard for active and archived changes, including phase progress, artifact groups, task progress, verify status, next-action guidance, risk signals, Git context, artifact previews with metadata, and a light/dark UI. `--json`, `--port`, `--no-open`, and `GET /api/dashboard` expose the same snapshot for scripts and CI.
* **`/comet-any` Skill Creator**: Adds the primary flow for creating or upgrading reusable Skills. The flow covers candidate discovery, confirmable proposals, generated Skill bundles, authored decision/guidance zones, authoring lanes, current-draft eval readiness, review approval, publish, distribution, and platform-native files such as Claude Code custom agents.
* **Skill Creator CLI**: Adds `comet creator` for ordinary creation/resume guidance and `comet publish` for review, approval, publish, and distribution previews, keeping backend Bundle commands available only as advanced tooling.
* **Local Skill tooling**: Adds `comet skill add|show|run|continue|check` for installing, inspecting, running, resuming, and deterministically checking local Skill packages with snapshots.
* **`comet eval` harness**: Adds repository-local evaluation for Comet workflows and arbitrary local Skills, with task profiles, generated manifests, HTML reports, token/cost attribution, pass\@k/pass^k reliability metrics, workflow-specific scoring, Skill invocation evidence checks, configurable simulator prompts, Anthropic-compatible proxy auth, Windows/WSL-friendly execution, UTF-8 logs, and regression gates.
* **Comet workflow eval tasks**: Expands the bundled Comet workflow benchmark to 20 tasks, adding dependency-confusion, layered streaming, persistence, approval, noise-resistance, cross-file refactor, observability config, graph execution review, agent memory routing, and framework selection scenarios for stronger CONTROL vs 0.3.9 vs 0.4.0 comparisons.
* **Hotfix/tweak scope decisions**: Adds qualitative upgrade signals for hotfix and tweak workflows, while file-count thresholds now pause for user confirmation instead of forcing an automatic full-workflow escalation ([#121](https://github.com/rpamis/comet/issues/121)).
* **Supported platforms**: Adds ZCode, MimoCode, Trae CN, and Antigravity 2.0 support. Antigravity 2.0 global installs use `~/.gemini/config/skills/`; ZCode and MimoCode use OpenCode-compatible layouts; Trae CN uses `.trae-cn/skills`.
* **Symlink install mode**: `comet init` and `comet update` can now install skills by copy or by symlink/junction from a shared `.comet/skills/` store.
* **Project Skill preferences**: Adds `.comet/skill-preferences.yaml` so projects can guide preferred Skills, ordering, and Skill Creator proposals without hand-editing bundle files.
* **Configured artifact language**: `comet init` now records a project-wide artifact language (`en` or `zh-CN`) in `.comet/config.yaml`, and each new change snapshots that language into its `.comet.yaml`. OpenSpec and Superpowers artifacts follow this configured language instead of the language of whichever request happened to trigger the workflow. Comet guard checks reject workflow artifacts that are clearly written in the wrong dominant language, fail closed on an invalid `language`, and ignore fenced code blocks so pasted commands, paths, or hashes do not skew the check.
### Changed
* **Comet product model**: README, CLI help, and Skill guidance now present Comet as a workflow and Skill platform: run guided workflows, create Skills, evaluate them, publish them, and diagnose stuck changes.
* **Comet Skill language instructions**: English and Chinese Comet Skills now read the configured artifact language (`en` or `zh-CN` only, no aliases) for OpenSpec prompts, Superpowers arguments, subagent dispatch, verification reports, and archive notes, instead of deriving it from the triggering user request.
* **Eval judge provider**: LLM-as-judge now requires an explicit `BENCH_JUDGE_MODEL` and uses the independent `BENCH_JUDGE_*` provider settings, including direct Anthropic-compatible HTTP when a judge endpoint and credential are configured. Judge runs no longer silently share the subject model, endpoint, or credentials and report a skipped status when judge configuration is incomplete.
* **LangSmith eval configuration**: LangSmith eval runs now derive Claude Code tracing plugin settings from the primary `LANGSMITH_*` configuration, keep Claude Code traces in the configured base project, preserve hook logs in saved artifacts, and auto-build the official Claude Code tracing plugin into the eval cache when needed.
* **Eval comparison reporting**: Eval reports now separate raw, analysis-set, flagged, and excluded runs; treat CONTROL as a business-only baseline; split overall, business, and workflow pass\@k/pass^k views; and render paper-style Markdown/HTML reports with metric explanations, rubric-dimension explanations, source evidence, failure attribution, centered tables, a Chinese/English toggle, Python-first charts, and inline SVG fallback.
* **README eval evidence**: README now highlights paper-style baseline figures for pass\@5/pass^5 and core rubric/judge metrics, making the no-Comet, 0.3.9, and 0.4.0 comparison visible without opening the full eval report.
* **Classic workflow state**: Machine-owned run checkpoints moved from `.comet.yaml` to `.comet/run-state.json`, while user-editable workflow fields remain YAML-readable. Classic phase transitions now also write `.comet/state-events.jsonl` for an auditable state history.
* **Classic runtime packaging**: Classic control metadata now lives under `comet/runtime/classic`, and command launchers are split into independent Node bundles (`comet-state.mjs`, `comet-guard.mjs`, `comet-archive.mjs`, and peers) while preserving the existing `/comet*` command behavior.
* **Workflow diagnostics**: `comet status` and `comet doctor` now share the same runtime evidence path and report current step, runtime mode, malformed state, missing evidence, and recommended recovery action.
* **Workflow routing**: `/comet` now uses an explicit intent-frame route model for full, hotfix, tweak, resume, and ambiguous requests. `/comet-tweak` is now a tweak-only OpenSpec action path, while full `/comet` remains on the Superpowers design/plan/build path.
* **Review workflow**: `review_mode` now defaults to `standard` for full workflows. `off`, `standard`, and `thorough` form a clearer review gradient, and Comet owns review dispatch policy so users do not pay for overlapping Superpowers and Comet review loops.
* **Interactive decision points**: Comet decision points prefer Claude Code's structured question UI when available, with a text fallback for other platforms.
* **Debug workflow**: The Debug Gate can investigate independent failure groups in parallel before fixes are applied serially through the configured review flow.
* **Repository layout**: Source code moved into `app/`, `domains/`, `platform/`, and `scripts/`, with tests moved to matching `test/app/`, `test/domains/`, `test/platform/`, `test/scripts/`, and `test/repository/` roots for clearer contributor ownership.
* **README formatting policy**: Root README files are excluded from Prettier checks so user-facing prose and exact documentation phrases are not rewritten by formatter line wrapping.
### Fixed
* **Windows path handling**: Fixes OpenSpec init/update path quoting for directories with spaces on Windows, so `comet init` no longer fails when the project path contains spaces.
* **Git submodule script lookup**: Comet hook and runtime script resolution now uses the containing project root when an agent works inside a Git submodule, so submodule edits no longer fail because `.claude/skills/comet/scripts/*` is only present at the parent project level ([#136](https://github.com/rpamis/comet/issues/136)).
* **Superpowers workspace writes**: Comet phase write guards now allow Superpowers to write its `.superpowers/` workspace during protected workflow phases, so Superpowers progress files are no longer mistaken for blocked source edits ([#154](https://github.com/rpamis/comet/issues/154)).
* **Doctor diagnostics**: `comet doctor` now gives clearer version, project/global scope, malformed state, missing evidence, and recovery guidance, so users can distinguish a real missing project install from a valid global install and understand current `.comet.yaml` state problems ([#135](https://github.com/rpamis/comet/issues/135)).
* **Review mode consistency**: English, Chinese, shared rule, and recovery guidance now agree on `review_mode`, so installed Skills no longer describe an old dual-review flow that conflicts with the runtime guard/state checks ([#126](https://github.com/rpamis/comet/issues/126)).
* **Project config merge on init/update**: `comet init` and `comet update` now perform field-level merge on `.comet/config.yaml` instead of skipping when the file exists. Existing user values are preserved, missing managed fields are filled with defaults, comments are refreshed, and extra user fields are kept. Damaged YAML files gracefully fall back to all defaults.
* **Init result summaries**: `comet init` now keeps partially failed platforms out of the `Installed` list and names the failed component, so platforms such as OpenCode no longer appear installed and failed at the same time ([#128](https://github.com/rpamis/comet/issues/128)).
* **`.husky/pre-commit` executable bit**: The pre-commit hook file was committed non-executable, so git silently skipped it on every clone/checkout regardless of platform, disabling the `format:check`/lint-staged automation described in this file for all contributors since it was first introduced. It is now shipped with the executable bit set.
### Removed
* **Bash-first Classic scripts**: Removes the requirement that bundled Classic workflow scripts run through Bash-compatible shell scripts.
### Security
* **Dependabot dependency alerts**: Pins test tooling to patched Vite and esbuild versions across npm and pnpm lockfiles, clearing open Vite path traversal, launch-editor, and esbuild dev-server advisories without changing Comet runtime dependencies.
### Added
* **CLI i18n shared module**: Extracted the init-time translation table to `src/commands/i18n.ts` so init, update, and future commands can share English/Chinese strings consistently instead of duplicating tables per command.
* **Optional npm dependency prompts in init/update**: `comet init` and `comet update` now present a multi-select for OpenSpec CLI, Superpowers (via `npx skills add`), and CodeGraph CLI instead of force-installing them. Items not yet detected on the system default to checked; already-installed items default to unchecked so users can opt into upgrades without being forced. The Superpowers entry also surfaces a recommendation to install v6.0.0+ (≈2× faster, ≈50% fewer tokens).
* **`--language` option for `comet init`**: New CLI flag (`en`/`zh`) that selects skill language non-interactively, mirroring the existing `comet update --language` option ([#109](https://github.com/rpamis/comet/pull/109)).
* **`review_mode` field for code review control**: Added `.comet.yaml` field `review_mode` (`off` / `standard` / `thorough`) controlling automatic code review during build and verify phases. `comet-build` requires user selection before execution; `comet-verify` and subagent dispatch adapt behavior per mode; `comet-hotfix` defaults to `off`. Validated by `comet-state.sh`, `comet-guard.sh`, and `comet-yaml-validate.sh`.
* **Project-level review mode defaults**: `.comet/config.yaml` can now set `review_mode: off|standard|thorough`, which is snapshotted into new full workflow changes so teams can choose a project-wide automatic review default while preserving existing per-change state behavior. Newly generated config files include enum comments for `context_compression`, `review_mode`, and `auto_transition` so users can adjust supported values without searching the docs.
* **Uninstall by platform selection**: `comet uninstall` now shows a checkbox prompt when multiple platforms are detected, allowing users to selectively uninstall specific platforms instead of removing all at once. Single-target scenarios use a simple yes/no confirmation. `--force` and `--json` flags retain the existing all-at-once behavior.
* **Codex plugin-installed Superpowers detection**: `comet init` now detects Superpowers already installed via the Codex plugin cache (`~/.codex/plugins/cache/...`), preventing duplicate re-installation — parallel to the existing Claude Code and OpenCode plugin detection ([#115](https://github.com/rpamis/comet/pull/115)).
### Changed
* **Tagline rebrand**: Changed the Comet tagline in the `comet init` banner and the `package.json` / CLI `--description` from "OpenSpec + Superpowers dual-star development workflow" to "Agent Skill Harness Phase-Guarded Automation From Idea To Archive", positioning Comet by its core value (a phase-guarded agent skill harness) rather than by its underlying OpenSpec + Superpowers dependencies.
* **Change name confirmation as a blocking decision point**: `comet-open` SKILL.md (Chinese and English) now adds a dedicated Step 1c that pauses before `openspec new change` to confirm the change name. The agent must recommend 2-3 kebab-case English candidate names derived from the clarification summary, always offer a custom-input option, and warn that Chinese (or any non-kebab-case) input will be converted into a compliant kebab-case English name and shown back for confirmation — preventing agents from auto-generating non-compliant Chinese change names.
* **Non-ASCII change name prevention**: Added explicit ASCII validation rules to `comet-open` SKILL.md (both Chinese and English) to prevent agents from auto-generating non-compliant change names containing Chinese, Japanese, Korean characters, spaces, or special characters. The agent must now ask the user for an ASCII-compliant name.
* **Chinese gate-term normalization**: Updated Chinese Comet wording to avoid translating `gate` literally as "门": Design Step 1e now uses "主动式上下文压缩", the shared debugging guidance now uses "异常调试协议", and `CLAUDE.md` / `AGENTS.md` now define this as the standard Chinese translation rule for future skill edits.
* **Full i18n coverage for CLI prompts**: Extended translation coverage from `init`-only to also cover `update` (banner, npm update progress, skills copy progress, summary, codegraph prompt). All user-facing strings now have English and Chinese variants ([#109](https://github.com/rpamis/comet/pull/109)).
### Fixed
* **Phase-skip enforcement across all guard layers**: Fixed agents jumping from `open` to `build` (skipping `design`) undetected. `comet-state.sh` now enforces evidence on every forward transition; direct `set phase` is blocked (with `COMET_FORCE_PHASE=1` escape hatch); `comet-hook-guard.sh` blocks source writes when `design_doc` is null; `comet-phase-guard` rule adds a phase-entry self-consistency check requiring prerequisite artifacts before writing source.
* **Hook guard cross-change false positives**: Fixed `comet-hook-guard.sh` letting one change's phase wrongly block writes to a different change. Writes targeting `openspec/changes//` are now governed by that change's own `.comet.yaml` phase instead of the first active change found in the directory. This covers two cases that previously blocked a brand-new change's artifact writes: (1) an old change marked `archived: true` but not yet physically moved to the `archive/` subdirectory, and (2) an old change stalled in the `archive` phase with `archived: false` (not yet run through the archive script). Additionally, a new change directory whose `.comet.yaml` does not exist yet (artifacts are written before the state file during `/comet-open`) is treated as `open`, so `proposal/design/tasks/specs` writes are allowed.
* **CodeGraph setup detection**: Fixed `comet init` and `comet update` prompting for CodeGraph setup even when the project already has a `.codegraph/` index. Existing project indexes now skip the optional CodeGraph prompt and install step, and CodeGraph CLI resolution can use a pnpm global binary before falling back to npm global installation.
* **Phase guard auto-transition handoff**: Fixed the injected Comet phase guard rule hardcoding the next skill after `guard --apply`, which could bypass `auto_transition: false`. The rule now delegates post-guard handoff to `comet-state next ` and follows `NEXT: auto|manual|done` so manual phase boundaries are respected.
* **Executable permission loss on macOS after update**: `bin/comet.js` and all shell scripts under `assets/skills/comet/scripts/` were committed with git mode `100644` (non-executable). After an npm update, macOS users lost execute permissions on the `comet` CLI entry point. Changed all 8 files to `100755` in git so npm installs always preserve the executable bit.
### Tests
* **Phase-skip enforcement coverage**: Added shell-script tests covering the hardened guard layers — `open-complete` blocked when an open artifact is missing, `design-complete` blocked/allowed by `design_doc` presence, `archived` blocked until `verify_result: pass`, direct `set phase` blocked while the `COMET_FORCE_PHASE` escape hatch is allowed, and hook-guard blocking full-workflow `build` source writes when `design_doc` is null while still allowing preset workflows and full workflows with a valid `design_doc`.
* **Project review mode default coverage**: Added regression coverage for `.comet/config.yaml` `review_mode` snapshotting into full workflow changes, invalid project review mode rejection, and enum comments in generated project config files.
* **CodeGraph setup coverage**: Added regression tests for existing `.codegraph/` index detection, skipping redundant CodeGraph installation, pnpm global CLI resolution, and suppressing the update-time CodeGraph prompt when a project index already exists.
* **Phase guard handoff coverage**: Added skill-rule regression coverage ensuring the phase guard delegates to `comet-state next` and no longer embeds a fixed next-skill mapping that can ignore `auto_transition`.
* **`review_mode` integration coverage**: Added regression tests verifying `review_mode` is wired through state, guard, and validation scripts, with correct mode-specific behavior in `comet-build`/`comet-verify`/`comet-hotfix`.
* **Uninstall platform selection coverage**: Added tests for single-target auto-select, multi-target checkbox selection, user cancellation, `--force` skip, `--json` output, and no-targets-found handling.
### Added
* **Kimi Code CLI support**: Added Kimi Code as the 29th supported platform, including project/global skill installation under `.kimi-code/`, OpenSpec `kimi` tool integration, Superpowers `kimi-code-cli` mapping, detection, documentation, and cross-platform regression coverage ([#90](https://github.com/rpamis/comet/pull/90)).
* **Version info and update check**: `comet init` and `comet update` now display the current installed Comet version at the start of command output and check the npm registry for newer versions. If an update is available, users see a prompt to upgrade; if already on the latest version, a confirmation message is shown; if the registry is unreachable, the check is skipped silently without error ([#99](https://github.com/rpamis/comet/issues/99)).
* **Official registry enforcement for update**: `comet update` now passes `--registry https://registry.npmjs.org` to npm when updating the `@rpamis/comet` package, ensuring it always fetches from the official npm registry regardless of the user's local `.npmrc` or mirror configuration. Other packages continue using the user's normal registry settings. If the official registry is unreachable, a clear error message indicates the registry issue ([#100](https://github.com/rpamis/comet/issues/100)).
* **Subagent dispatch Comet extensions**: Rewrote the inline subagent dispatch protocol from `comet-build/SKILL.md` into `comet/reference/subagent-dispatch.md` (Chinese and English) as Comet-specific extensions layered on top of the Superpowers `subagent-driven-development` skill. The skill provides the core dispatch loop; the Comet extensions add real background dispatch, durable per-task checkpoints (`subagent-progress.md`), coordinator-only source execution, TDD ownership by background agents, bounded review-fix rounds (3 max), continuous task execution without pauses, and precise context recovery from checkpoint stages.
* **`task-checkoff` subcommand**: Added `comet-state task-checkoff ` to verify a specific task is uniquely checked in a markdown file. Used by the subagent dispatch protocol for targeted completion verification after dual review passes. Includes path traversal prevention, CRLF handling, and exact-match validation.
* **`comet uninstall` command**: Added `comet uninstall [path]` CLI command to safely remove Comet-distributed skills, rules, and hooks across all 29 supported AI coding platforms. Supports `--scope` (project/global), `--force` (skip confirmation), and `--json` output. Auto-detects installed targets, removes only Comet-managed artifacts while preserving user-defined hooks and non-Comet configuration, cleans up empty directories and working directories (`.comet/`, `docs/superpowers/`), and handles all 7 hook formats (Claude Code, Qwen, Qoder, Gemini, Windsurf, GitHub Copilot, Kiro) and all 3 rule formats (md, mdc, copilot instructions) ([#95](https://github.com/rpamis/comet/issues/95)).
* **Progressive loading reference docs**: Extracted four reference documents from inline skill content to enable on-demand loading and reduce per-invocation token cost (both Chinese and English): `auto-transition.md` (auto-transition protocol, replacing 7 × \~10 lines of repeated content across sub-skills), `context-recovery.md` (context compression recovery, replacing 4 × \~8 lines), `comet-yaml-fields.md` (`.comet.yaml` field table, \~40 lines), and `file-structure.md` (directory structure, \~20 lines). Main `comet/SKILL.md` retains critical state machine hard constraints inline while pointing to reference docs for detailed field descriptions. Estimated per-invocation savings: 600–1,500 tokens depending on skill; cumulative \~4,100 tokens across a full workflow.
* **Pre-commit formatting hook**: Added a `husky` + `lint-staged` pre-commit hook that automatically runs `prettier --write` on staged source files under `src/` at every `git commit` (scope aligned with CI `format:check`). Editor-agnostic — enforced for all contributors regardless of IDE or agent — preventing Prettier formatting issues from reaching CI. The `prepare` script installs the hook on `pnpm install`, and `.husky/` is excluded from the published package via the `files` whitelist.
### Changed
* **Skills progressive loading refactor**: All 7 sub-skills (`comet-open`, `comet-design`, `comet-build`, `comet-verify`, `comet-archive`, `comet-hotfix`, `comet-tweak`) in both Chinese and English now reference shared protocol documents for auto-transition and context recovery instead of embedding full content inline, while retaining critical inline commands (`next` command and output interpretation) for safe standalone loading.
* **Phase guard recovery with durable checkpoints**: Updated recovery steps in `comet-phase-guard.md` (Chinese and English) to reload the Superpowers `subagent-driven-development` skill, read `subagent-progress.md` for exact stage recovery (implementation commit, RED/GREEN evidence, passed reviews, unresolved feedback, review-fix round), and resume from the checkpoint's precise phase instead of always starting from the first unchecked task. Both `.claude/rules/` and `assets/skills/comet/rules/` copies include consistent references with bilingual identifiers for cross-language test compatibility.
* **Decision point protocol extraction**: Extracted inline user-decision-point text from all 7 sub-skills (`comet-open`, `comet-design`, `comet-build`, `comet-verify`, `comet-archive`, `comet-hotfix`, `comet-tweak`) and main `comet/SKILL.md` into shared `comet/reference/decision-point.md` (both Chinese and English). Sub-skills now reference the protocol by path instead of repeating the full blocking-point rules, reducing per-invocation token cost and ensuring consistency across skills.
* **Debug gate protocol extraction**: Extracted the inline systematic-debugging four-stage flow from `comet-build`, `comet-hotfix`, and `comet-tweak` into shared `comet/reference/debug-gate.md` (both Chinese and English). Sub-skills now reference the debug gate protocol by path, centralizing the investigation, minimal failing test, fix verification, and verification-loop rules.
* **Lightweight verification review**: Lightweight verification now requires a scoped Superpowers `requesting-code-review` review focused on correctness, security, and edge cases, adding review coverage without running full spec or design drift checks ([#86](https://github.com/rpamis/comet/pull/86)).
### Fixed
* **Pi slash command discovery**: `comet init` and `comet update` now generate a Pi extension that registers all shipped `/comet*` workflows as native slash commands forwarding to `/skill:*`. Pi settings are merged non-destructively with skill commands enabled, global resources now use Pi's documented `~/.pi/agent/` directory, legacy `~/.pi/skills/` installs are detected for update and cleanup, and `comet uninstall` removes only Comet-managed assets while preserving shared settings and unrelated extensions ([#89](https://github.com/rpamis/comet/issues/89)).
* **OpenCode plugin-installed Superpowers detection**: `comet init` now correctly detects Superpowers already installed via the OpenCode plugin system (configured in `opencode.json`), preventing duplicate re-installation. Previously, only skills placed directly under `~/.config/opencode/skills/` were detected, missing the plugin source directory at `~/.config/opencode/superpowers/skills/` and the `plugin` array in `opencode.json`. Added `hasOpenCodePluginSuperpowers()` fallback detection similar to the existing Claude Code plugin cache check ([#105](https://github.com/rpamis/comet/issues/105)).
* **Lightweight verification consistency**: Hotfix documentation now describes the 6-item lightweight verification path, and verification failure handling treats CRITICAL and IMPORTANT findings as blocking so review pass criteria and failure decisions remain consistent.
* **Hook configuration merging during init and update**: Shared hook configuration files for Claude Code, Codex, Amazon Q, Qwen, Qoder, Gemini, and Windsurf now preserve user-defined hooks when Comet installs or updates a hook for the same matcher or event. Existing Comet commands are identified by their manifest script path and replaced in place, preventing stale install paths, duplicate matcher groups, and repeated hook accumulation while leaving unrelated settings untouched.
* **Subagent-driven task isolation and continuity**: `comet-build` now loads the mature Superpowers `subagent-driven-development` loop and applies a stricter Comet extension that requires one fresh background implementer per task, fresh background reviewers and fix agents, coordinator-only source execution, and automatic continuation between tasks without progress summaries or "continue?" prompts. TDD mode requires each implementer/fix agent to load the TDD skill and return auditable RED/GREEN evidence before review. A durable per-task checkpoint preserves implementation commits, review stages, feedback, and the three-round retry budget across context compression; task checkoff remains blocked until both reviews pass ([#94](https://github.com/rpamis/comet/issues/94), [#96](https://github.com/rpamis/comet/issues/96), [#97](https://github.com/rpamis/comet/issues/97)).
* **npm shebang line ending issue on macOS**: When npm packed the project on Windows, `bin/comet.js` shebang line got CRLF line endings, causing macOS to interpret `#!/usr/bin/env node\r` instead of `#!/usr/bin/env node`, resulting in "command not found" after `npm install -g @rpamis/comet`. Added explicit `eol=lf` rules for all text file extensions (`.js`, `.mjs`, `.ts`, `.json`, `.md`, `.yaml`, `.yml`) and binary markers for image files in `.gitattributes` ([#82](https://github.com/rpamis/comet/issues/82)).
* **CodeGraph Codex CLI skip on project scope**: `comet init` with project scope passed `--target` and `--location=local` to `codegraph install`, which caused Codex CLI (no project-local config) to be skipped with a confusing message. Simplified to `codegraph install --yes` without `--target` or `--location` flags, letting CodeGraph auto-detect and configure all installed agents. Removed `filterSupportedPlatforms` and `CODEGRAPH_SUPPORTED_TARGETS` ([#98](https://github.com/rpamis/comet/issues/98)).
* **OpenSpec CLI upgrade and --profile fallback**: `ensureOpenSpecCli` now always installs/upgrades openspec to the latest version, even if an older version is already present, ensuring users get `--profile` support and other improvements. Added fallback logic: if `openspec init` fails with "unknown option --profile" in stderr, retries without the flag for edge cases where the upgrade fails but an older openspec remains ([#84](https://github.com/rpamis/comet/issues/84)).
* **Symlink resolution for skill file copies**: When skill directories are symlinks (e.g. `~/.claude/skills/comet -> ~/.agents/skills/comet`), `copyFile` and `ensureDir` wrote to the literal path instead of following the symlink target. Broken symlinks caused silent copy failures. Added `resolveSymlinkPath()` to `file-system.ts` that walks up the path tree and follows `readlink` targets for broken symlinks. Applied to `ensureDir`, `copyFile`, and `writeFile` ([#85](https://github.com/rpamis/comet/issues/85)).
* **comet-tweak missing debug handling**: `comet-tweak/SKILL.md` was missing the systematic-debugging requirement that `comet-hotfix` already had — when tests or builds fail during tweak execution, the skill now explicitly requires loading the `systematic-debugging` skill before proposing source fixes, matching hotfix behavior.
* **OpenSpec per-artifact instructions compliance**: Chinese and English `comet-open` now apply OpenSpec per-artifact instructions (`openspec instructions proposal/design/tasks --change "" --json`) for each standard artifact, loading `context`, `rules`, `template`, `instruction`, `resolvedOutputPath`, and `dependencies` from the JSON payload instead of hard-coded artifact prose. Stops artifact generation on instruction failure rather than silently bypassing project rules ([#66](https://github.com/rpamis/comet/issues/66)).
* **CI Windows path escaping in skill verification**: The `init-e2e` workflow's Pi settings verification step interpolated a Windows `$RUNNER_TEMP` path (containing backslashes) directly into a `node -e "require('...')"` JS string literal, where `\a`/`\_` were parsed as escape characters and mangled the path (`D:\a\_temp` → `D:a_temp`), failing the `init-e2e (windows-latest)` runners on Node 20 and 22. The path is now passed via an environment variable (`process.env`) so it never enters a JS string literal; Linux/macOS were unaffected.
* **OpenSpec source formatting**: Re-formatted `src/core/openspec.ts` (long-line wrapping) to satisfy `prettier --check`, unblocking the `format:check` CI step.
* **Symlink-safe removal during uninstall**: `removeFile`/`removeDir` no longer resolve symlinks before deleting. A symlinked skill, rules, or hooks directory previously had its *resolved target* recursively deleted by `comet uninstall`; symlinked directories are now unlinked directly. `isDirEmpty` also no longer reports unreadable directories as empty, so cleanup never deletes a directory it could not inspect.
* **`comet update --json` output corruption**: npm's inherited stdio previously interleaved into the JSON document; npm stdout/stderr are now discarded in JSON mode so machine-readable output stays parseable.
* **`comet update --json` no-targets shape**: the early-return JSON emitted when no installed targets exist now includes `codegraph: 'skipped'`, matching the normal output shape so consumers need not special-case the empty path.
* **JSON-mode version-check latency**: `comet init` and `comet update` now skip the npm-registry version check in JSON mode, emitting output without a network round-trip.
* **Malformed hook settings resilience**: hand-edited settings files storing a hook group as a non-array value no longer throw during init/update hook merging; malformed groups are coerced to empty.
* **Markdown code-fence language tags**: added `text` language tags to fenced code blocks in `file-structure.md` and `subagent-dispatch.md` (Chinese and English) to satisfy MD040 linting, consistent with the existing OpenSpec formatting CI fix.
* **Skills manifest version drift**: bumped `assets/manifest.json` version `0.3.3` → `0.3.8` to match `package.json`.
### Tests
* **Kimi Code platform coverage**: Added detection, project/global installation, OpenSpec tool mapping, Superpowers agent mapping, CI platform-count, and documentation regression coverage for Kimi Code.
* **Lightweight verification review regression**: Added bilingual workflow safeguards for the lightweight code-review requirement, blocking severities, scoped review criteria, and hotfix documentation consistency.
* **Pi command extension lifecycle coverage**: Added project/global init, manifest-driven command generation, argument forwarding, settings preservation, invalid-settings protection, deterministic overwrite, and selective uninstall regression coverage, plus CI assertions for Pi's project and global extension locations.
* **Hook merge regression coverage**: Added real-file tests for Claude-style, Qwen/Qoder, Gemini, and Windsurf hook formats covering same-matcher user hook preservation, stale Comet command replacement, unrelated configuration retention, and idempotent repeated installation.
* **Subagent dispatch contract coverage**: Added Chinese and English skill-content regression coverage for Superpowers/Comet composition, coordinator-only source execution with tracking-file exceptions, one fresh background agent per task and role, prompt/status/reviewer evidence contracts, durable recovery checkpoints, TDD ownership, dual-review checkoff, bounded stop conditions, continuous task execution, Comet-specific final handoff, and the absence of a Stop hook.
* **Reference doc assertions**: Added assertions verifying all skill files that reference `decision-point.md` and `debug-gate.md` include the correct protocol path, and that the shipped reference docs contain the expected core rules and fallback behavior.
* **OpenSpec artifact contract coverage**: Added bilingual contract assertions verifying `comet-open` skills contain explicit JSON instruction commands for `proposal`, `design`, and `tasks`; require applying `context`, `rules`, `template`, `instruction`, `resolvedOutputPath`, and `dependencies`; prohibit copying context/rules into artifacts; refresh status between artifacts; and stop instead of falling back when OpenSpec instructions fail.
### Added
* **Auto-transition config**: Added `auto_transition` (`true`|`false`) to `.comet.yaml` and the `.comet/config.yaml` project default so teams can choose whether Comet automatically advances to the next phase skill or pauses for a manual transition. When `auto_transition: false`, build/design/open/verify skills stop after meeting exit conditions and print the next manual step instead of invoking the next skill. Includes state-machine whitelist, enum validation, and schema (`comet-yaml-validate.sh`) coverage ([#74](https://github.com/rpamis/comet/pull/74)).
* **Deterministic next-step resolver**: Added `comet-state next ` to resolve post-guard routing from `.comet.yaml` (`phase`, `workflow`, `auto_transition`) with structured output: `NEXT: auto|manual|done`, `SKILL: `, and `HINT` (manual mode). This centralizes next-skill routing logic in scripts instead of duplicating it across skill prose.
* **Workflow output language**: Comet workflows now propagate the triggering user request language into OpenSpec and Superpowers steps via an explicit Output Language Rule, keeping generated proposals, designs, plans, verification reports, and archive notes readable in the user's language. Resuming an existing change preserves the dominant artifact language unless the user explicitly asks to switch ([#53](https://github.com/rpamis/comet/pull/53), [#37](https://github.com/rpamis/comet/issues/37)).
* **Execution benchmark (Claude Code)**: Added `benchmark:execution`, a benchmark harness with three test phases: L1 (design doc generation from handoff context), L2 (build a note-board module from handoff context + run tests), and L3 (full workflow — implement a dictionary module from spec, run 10 vitest tests). Invokes Claude Code (`claude -p`) and measures actual test pass rate, token usage, retry count, duration, and cost. Compares `off` vs `beta` context compression modes across small/medium/large tiers. Supports `--phase l1|l2|l3|both|all` and `--dry-run` for deterministic verification. Extracted shared utilities (`spawnCapture`, `parseClaudeJson`, `buildClaudeArgs`, etc.) to `scripts/benchmark-utils.mjs`.
* **Token optimization: TDD skill single load**: Build skill now loads `test-driven-development` skill once before the first task (instead of per-task), reducing \~44K tokens per 10-task workflow. Includes compaction recovery guidance to reload once on resume.
* **Token optimization: brainstorming checkpoint**: Design skill now writes `brainstorm-summary.md` after user confirms design approach, providing a compaction recovery point that preserves confirmed decisions across context window compression.
* **Token optimization: incremental brainstorming checkpoint**: Design skill now incrementally updates `brainstorm-summary.md` during brainstorming, preserving confirmed facts, candidate decisions, risks, testing notes, and pending questions before platform-driven context compaction can occur.
* **Token optimization: active compaction gate**: Design skill now requires an active context compaction gate after `brainstorm-summary.md` is finalized and before creating the Design Doc, using the host platform's native compaction mechanism when available and falling back to a manual user prompt when it is not.
* **Token optimization: plan creation subagent offload**: Build skill offloads `writing-plans` execution to a subagent, freeing main session context. Subagent reads Design Doc + tasks.md from files and returns the plan file path. Falls back to inline execution on subagent failure.
* **Token optimization: verification skill dedup**: Verify skill loads `verification-before-completion` once before the light/full branch point instead of in each branch, eliminating redundant skill content.
* **Token optimization: tasks.md incremental scan**: Build skill uses `grep` to find unchecked tasks instead of re-reading the entire `tasks.md` file after each task completion.
* **Token optimization: hash on-demand read in verify**: Verify skill checks `handoff_hash` before re-reading OpenSpec artifacts. When hash matches, only `tasks.md` is skipped (proposal.md and design.md are still read for comparison checks). Uses new `comet-handoff.sh --hash-only` flag.
* **`--hash-only` flag for comet-handoff.sh**: New backward-compatible flag outputs the context hash without generating handoff files, used by verify phase for hash comparison. Validates required files exist before computing hash.
* **CodeGraph integration in comet init**: `comet init` now offers an optional step to install and configure CodeGraph (`@colbymchenry/codegraph`) for semantic code intelligence. It auto-detects supported platforms (Claude Code, Cursor, Codex, OpenCode, Gemini, Kiro, Antigravity), installs the CLI if missing, runs `codegraph install` for agent wiring, and initializes the project index. Skips gracefully under `--json` mode.
* **Stale PR automation**: Added a scheduled and manually runnable GitHub Actions workflow that marks inactive pull requests stale after 90 days and closes them after another 30 days, helping keep long-idle review queues manageable.
* **TDD mode field**: Added `tdd_mode` (`tdd`|`direct`) to `.comet.yaml` state machine so users choose whether to enforce TDD during build. When `tdd_mode: tdd`, subagent dispatches inject an explicit TDD hard constraint, bypassing implementer-prompt.md's conditional trigger. Addresses [#67](https://github.com/rpamis/comet/issues/67).
* **subagent\_dispatch field**: Added `subagent_dispatch` (`null`|`confirmed`) to `.comet.yaml` state machine, ensuring `build_mode: subagent-driven-development` can only leave the build phase after the platform's real background dispatch capability is confirmed.
* **Verify retry limit**: Verify skill now enforces a mandatory user decision after 3 consecutive verify-fail cycles, preventing indefinite automated retry loops.
* **Manual verify\_mode override**: Users can override automatic verification scale assessment via `comet-state set verify_mode ` when the auto-detected mode doesn't fit.
* **Local context compression benchmark**: Added `benchmark:context`, a local Codex benchmark harness that creates matched `context_compression: off` and `beta` Comet fixtures, runs `codex exec` against each mode, and reports token savings, spec drift rate, task completion rate, parse success, and timing. Use `--dry-run` for deterministic non-Codex verification.
* **Beta-gated context compression switch**: Project installs now create `.comet/config.yaml` with `context_compression: off`, allowing teams to opt new changes into beta spec projection by setting `context_compression: beta`. This switch controls only the OpenSpec handoff projection path (`spec-context.*`); the workflow token optimizations above are default-on and do not require beta mode.
* **Beta spec projection handoff**: `/comet-design` can now use beta context compression to generate `spec-context.json` and `spec-context.md`, preserving OpenSpec requirement and scenario headings with source hashes so compact design handoffs reduce token load without weakening acceptance coverage.
### Changed
* **executing-plans review gate**: When `build_mode` is `executing-plans`, the build phase now requires loading the Superpowers `requesting-code-review` skill and requesting code review at least once before the build→verify phase guard. CRITICAL findings must be fixed before verify; accepted non-CRITICAL findings must record acceptance rationale in a durable artifact. The build-exit checklist enforces this gate ([#76](https://github.com/rpamis/comet/pull/76), [#41](https://github.com/rpamis/comet/issues/41)).
* **Phase advancement vs handoff wording**: Chinese and English Comet skills now consistently distinguish guard-driven phase advancement (`--apply`, always updates `phase`) from next-skill invocation control (`auto_transition`). Open/design/build/verify/hotfix/tweak guidance now routes through `comet-state next` for auto/manual handoff.
* **Preset continuity wording**: Hotfix and tweak guidance now explicitly documents the `auto_transition: false` exception in continuous execution mode, removing contradictory wording around "always continue" behavior.
* **Verify hash-skip scoped to tasks.md only**: Full verification always reads `proposal.md` and `design.md` even when hash matches, ensuring goal-satisfaction and design-consistency checks have complete context.
* **Design Doc creation stays in main session**: Design Doc is created inline (not offloaded to subagent) to preserve full brainstorming conversation context and prevent information loss for complex requirements.
* **Subagent failure fallback**: Plan creation subagent offload includes explicit degraded fallback — if the subagent fails, the main session loads `writing-plans` inline.
* **Beta spec verbatim projection**: Beta context compression now projects entire spec files verbatim (`cat`) instead of filtering by English keywords (GIVEN/WHEN/THEN/AND/BUT). This eliminates language-dependent matching, ensures zero acceptance-criteria drift for Chinese or non-English specs, and removes the fragile AWK filter entirely.
* **JSON structural validation**: `comet-guard.sh` now validates `spec-context.json` structure (required fields: `change`, `phase`, `mode`, `files`, `context_hash`) and source file reference coverage, replacing the previous English-heading-based markdown check. Guard catches corrupted or incomplete JSON before phase transition.
* **JSON file roles**: `spec-context.json` `files` array now includes a `role` field (`spec` for spec files, `supporting` for proposal/design/tasks), removing the language-dependent `projection` array entirely.
* **--full warning in beta mode**: Running `comet-handoff.sh` with `--full` in beta mode now emits an explicit warning instead of silently ignoring the flag.
* **CodeGraph step in comet update**: `comet update` now prompts to install/update CodeGraph alongside skill file updates, using the same platform detection and CLI installation flow.
* **Rules and hooks distribution in comet update**: `comet update` now distributes anti-drift phase guard rules and hooks to all installed platforms alongside skill files, keeping rules and hooks in sync after a Comet upgrade.
* **Archive confirmation gate**: Chinese `/comet-archive` now pauses for explicit user confirmation before running the archive script, giving users a final chance to adjust or re-run verification before main spec merge and change archival.
* **English archive confirmation parity**: English Comet skills now match the confirmed Chinese archive-confirmation workflow, including `/comet-archive`, `/comet-verify`, `/comet`, hotfix, and tweak guidance.
* **Archive reopen transition**: Added `comet-state transition archive-reopen` so users who decline final archive confirmation can return from `phase: archive` to `phase: verify` for adjustment or re-verification without manually editing `.comet.yaml`.
* **OpenSpec clarification gate**: Chinese and English `/comet-open` now require a confirmed requirements clarification summary before proposal, design, or tasks artifacts are created, preventing one Q\&A turn from immediately generating a full OpenSpec change.
* **PRD split preflight**: Chinese and English `/comet-open` now triage large PRDs before creating OpenSpec artifacts, allowing users to split independent capabilities into multiple Comet changes while keeping each accepted split on the `/comet-open` state-machine path. Addresses [#62](https://github.com/rpamis/comet/issues/62).
* **Skill invocation wording guidance**: Added repository guidance in `CLAUDE.md` requiring new skill-trigger descriptions to use the existing "use the Skill tool to load..." wording and place context details after the skill loads.
* **Anti-drift phase guard rule**: Added `.claude/rules/comet-phase-guard.md` that re-injects Comet phase awareness, skill invocation requirements, script execution requirements, user confirmation gates, and context compaction recovery instructions every conversation turn, preventing long-context attention drift from breaking the 5-phase workflow. Works on all platforms as a soft reminder.
* **Anti-drift phase guard hook**: Added `comet-hook-guard.sh` PreToolUse hook (configured in `.claude/settings.local.json`) that hard-blocks file writes when the active Comet change is in `open`, `design`, or `archive` phase, providing a platform-specific hard enforcement layer that the model cannot bypass. Whitelists `openspec/*`, `docs/superpowers/*`, `.claude/*`, and `.comet/*` paths.
* **Platform rules/hooks distribution in comet init**: `comet init` now distributes the anti-drift phase guard rule and hook-guard script to all supported platforms during initialization. Platform definitions were corrected: Cline uses `.clinerules/` at project root (not `.cline/rules/`), GitHub Copilot uses `.github/instructions/*.instructions.md` with `applyTo` frontmatter, Kiro uses `.kiro/steering/`, and Gemini CLI has no rules directory (uses GEMINI.md files). Added `rulesDir`/`rulesFormat` to 8 platforms that were missing it, and `supportsHooks`/`hookFormat` to 7 platforms. Hook installation supports 7 format variants: Claude Code, Gemini, Windsurf, Copilot, Qwen, Kiro, and Qoder.
* **Systematic debugging gate**: Chinese and English build and hotfix skills now require loading Superpowers `systematic-debugging` when implementation-time crashes, unexpected behavior, test failures, or build failures appear, ensuring root-cause investigation and in-change regression tests happen before source fixes.
* **Verification-before-completion gate**: Chinese and English `/comet-verify` now require loading Superpowers `verification-before-completion` before executing lightweight or full verification checks, enforcing evidence-based confirmation before any completion claims.
* **Platform-neutral confirmation gates**: Chinese and English Comet skills and recovery messages now refer to the current platform's user input/confirmation mechanism instead of hard-coding `AskUserQuestion`, preventing Codex users from being directed to a tool that may not exist while preserving blocking user decisions.
* **Preset upgrade path**: Hotfix and tweak skills now include `set phase design` step when upgrading to full workflow, preventing comet-design entry check failure after workflow switch.
* **Build-complete conditional field reset**: `build-complete` transition preserves `verification_report` and `branch_status` when the previous verify\_result was `fail`, enabling verify-fail→build→build-complete re-verify cycles without data loss.
* **Open phase recovery granularity**: Open phase recovery now distinguishes three states (all artifacts done / none done / partial) with specific recovery actions per state.
* **50% scope threshold option**: Build skill now offers "continue in current change" as a third option when changes exceed 50% scope, avoiding forced change splitting.
* **Worktree plan commit**: Build skill now explicitly instructs committing plan files before creating a worktree when using worktree isolation.
### Removed
* **openspec/config.yaml**: Removed unused example OpenSpec config file containing only placeholder comments.
### Fixed
* **Subagent task persistence**: `/comet-build` now requires every subagent dispatch prompt to persist completed task checks in the Superpowers plan and, when mapped, the corresponding OpenSpec `tasks.md` item before committing. Build guard blocks unchecked Superpowers plan tasks, and build recovery reports both OpenSpec and plan progress before inspecting recent git history/diff or dispatching more work, preventing resume after interruption or context compression from re-running already completed subagent work ([#79](https://github.com/rpamis/comet/issues/79)).
* **skip-all skipping uninstalled components**: `comet init` no longer treats a previously skipped component as already installed. Choosing skip-all now only skips components that are actually present, so uninstalled OpenSpec, Superpowers, Comet, or CodeGraph components are still offered for installation instead of being silently bypassed ([#73](https://github.com/rpamis/comet/pull/73)).
* **Update JSON output for rules/hooks**: `comet update --json` now includes rules and hooks distribution results alongside skill update results, with per-target error isolation so a single platform failure doesn't break the entire update output.
* **Duplicate YAML fields**: `replace_yaml_field` in `comet-state.sh` now deduplicates all fields after replacement, keeping only the last occurrence of each key. Previously, multiple `cmd_set` calls for the same field (e.g., during verify-fail → re-verify cycles) could leave duplicate lines in `.comet.yaml`, confusing downstream parsers. Fixes [#77](https://github.com/rpamis/comet/issues/77).
* **Hook config format**: `installClaudeCodeHooks` and `.claude/settings.local.json` now use the correct `matcher` + `hooks: [{ type, command }]` array format instead of the flat `{ matcher, command, description }` format, fixing the `/doctor` schema validation error.
* **Archive delta merge**: `comet-archive.sh` now delegates archive spec updates to OpenSpec's delta merge semantics instead of copying change specs over main specs, preventing `ADDED/MODIFIED/REMOVED/RENAMED` section headings from leaking into stable specs. Addresses [#69](https://github.com/rpamis/comet/issues/69).
* **Brainstorming depth**: Chinese and English `/comet-design` no longer tell Superpowers `brainstorming` to skip context exploration, so unclear goals, scope, non-goals, acceptance scenarios, or constraints must be clarified before a Design Doc is created.
* **Command injection prevention**: `run_command_string()` in `comet-guard.sh` now rejects build/verify commands containing shell metacharacters (`;`, `|`, `&`, `$`, backtick), preventing command injection through `.comet.yaml` command fields.
* **Path traversal prevention**: `comet-state.sh cmd_set` now validates path fields (design\_doc, plan, verification\_report, handoff\_context, handoff\_hash) for `..` traversal sequences before writing.
* **Design guard enforcement**: Design guard now requires `design_doc` for full workflow (FAIL instead of WARN), preventing phase advance without a design document.
* **branch\_status preservation on verify-fail**: `verify-fail` transition no longer resets `branch_status`, keeping branch handling state across re-verify cycles.
* **UTC date consistency**: All scripts now use `date -u +%Y-%m-%d` for `created_at`, `verified_at`, and archive naming, eliminating local/UTC date mismatches.
* **macOS SCRIPT\_DIR resolution**: All scripts use portable `$(cd "$(dirname "$0")" && pwd -P)` instead of `readlink -f` for cross-platform compatibility.
* **Archive directory resolution fallback**: `comet-archive.sh resolve_archive_dir()` now searches by `*-$CHANGE` pattern when the exact UTC-based path doesn't match, fixing test reliability across timezone differences.
* **Temp file permissions**: All `mktemp` calls now set `chmod 600` on temporary files before writing sensitive data.
* **Pipe hash error propagation**: Hash computation in `comet-handoff.sh` and `comet-guard.sh` captures pipe output in variables before piping to hash stream, preventing silent failures under `pipefail`.
### Tests
* **Auto-transition regression**: Added state-machine and skill coverage for `auto_transition` init defaults, enum validation, `.comet/config.yaml` project default propagation, schema validation, and the manual-transition vs auto-advance branching in build/design/open/verify skills ([#74](https://github.com/rpamis/comet/pull/74)).
* **`comet-state next` regression**: Added shell-script coverage for next-step resolution across full/hotfix/tweak workflows, manual-handoff mode, archived completion (`NEXT: done`), and missing `.comet.yaml` failure behavior.
* **Skill handoff wording regression update**: Updated skill-content assertions to validate next-driven handoff wording (`NEXT: auto|manual|done`) and synchronized Chinese/English expectation checks.
* **Output language regression**: Added skill coverage that Comet propagates the triggering user request language into OpenSpec and Superpowers steps across the open, design, build, verify, hotfix, tweak, and archive skills ([#53](https://github.com/rpamis/comet/pull/53)).
* **Review gate regression**: Added skill coverage that `executing-plans` build mode requires the `requesting-code-review` gate before the build→verify transition, plus updated init-e2e expectations ([#76](https://github.com/rpamis/comet/pull/76)).
* **skip-all regression**: Added `comet init` coverage that skip-all only skips installed components and still offers uninstalled OpenSpec/Superpowers/Comet/CodeGraph components ([#73](https://github.com/rpamis/comet/pull/73)).
* **`--hash-only` flag coverage**: New tests verify correct hash output, change-directory validation, required-file validation, and no handoff file regeneration.
* **Context benchmark runner coverage**: New tests verify benchmark token-savings math, Codex JSONL usage/verdict parsing, and dry-run report generation without invoking Codex.
* **Flaky test timeout fix**: Design guard test without design\_doc now has explicit 20s timeout to prevent Windows bash startup flakiness.
* **Chinese spec coverage**: Beta handoff test uses Chinese spec content to verify verbatim projection of all content (headings, descriptions, non-keyword steps) regardless of language.
* **JSON corruption detection**: New test verifies guard blocks design exit when `spec-context.json` is structurally invalid.
* **--full beta warning**: New test verifies the warning message and confirms beta files are still generated when `--full` is passed.
* **Doctor CodeGraph check**: `comet doctor` now reports CodeGraph CLI availability and project initialization status (`.codegraph/` presence).
* **Archive confirmation regression**: Added Chinese skill coverage that `/comet-archive` requires a final confirmation gate before executing the archive script.
* **English archive confirmation regression**: Added English skill coverage for final archive confirmation, archive reopen guidance, and hotfix/tweak preset blocking points.
* **Phase write guard hook coverage**: 10 new tests for `comet-hook-guard.sh` covering phase-based write blocking (open/design/archive block, build/verify allow), whitelist paths (openspec, docs/superpowers, .claude), archived change bypass, and no-active-change passthrough.
* **Archive reopen regression**: Added state-machine coverage for returning an unarchived change from archive confirmation back to verification and rejecting reopen attempts after `archived: true`.
* **Archive spec merge regression**: Added shell-script coverage for archiving a delta spec without copying delta-only requirement section headings into the stable main spec.
* **OpenSpec proposal regression**: Added Chinese and English skill coverage for the pre-artifact clarification gate, the default ban on one-shot `openspec-propose`, and preservation of the Superpowers brainstorming clarification flow.
* **Skill authoring regression**: Added coverage that `CLAUDE.md` documents the required skill invocation wording pattern.
* **Debug gate regression**: Added Chinese skill safeguard coverage for systematic-debugging invocation, minimal failing-test requirements, and keeping crash verification inside the current change.
* **Confirmation mechanism regression**: Added coverage that Chinese workflow decision gates no longer hard-code `AskUserQuestion` and that recovery output points agents to a platform-neutral confirmation mechanism.
* **PRD split workflow regression**: Added Chinese and English skill coverage for open-phase PRD split choices, `/comet-open` state initialization, repeated-triage prevention, split completion selection, and minimal resume guidance.
* **tdd\_mode state machine regression**: Added coverage for tdd\_mode init defaults (null for full, direct for hotfix), enum validation, build-exit guard, hotfix bypass, and schema validation rejection of invalid values.
* **Review fix regression**: Added coverage for conditional verification\_report preservation on re-verify, branch\_status preservation across verify-fail, path traversal rejection on design\_doc, command injection rejection on build\_command, and design guard enforcement for full workflow without design\_doc.
* **Context compression regression**: Added coverage for project config defaults, change-level `context_compression` snapshots, environment override during change initialization, beta spec projection generation, and guard rejection when beta projection misses requirement or scenario headings.
### Added
* **Plan-ready build pause state**: Added `build_pause` as a dedicated build-phase pause marker so Comet can stop after plan generation without confusing the pause with the actual execution method.
* **Plan-ready pause design**: Added a design record for the model-switching pause workflow, covering recovery behavior, stale pause handling, and plan-missing remediation.
### Changed
* **Build recovery routing**: `/comet` and `/comet-build` now recognize `build_pause: plan-ready`, reuse the existing plan, and resume at workspace isolation and execution-method selection instead of regenerating the plan.
* **Bilingual workflow documentation**: Chinese and English Comet skills now describe the plan-ready pause point, clarify that `build_pause` is not `build_mode`, and document the same state field in both README files.
### Fixed
* **GitHub Copilot Superpowers skill names**: Comet skills now invoke the bare Superpowers skill names installed by the GitHub Copilot skills path, avoiding blocked workflows caused by unresolved `superpowers:*` aliases.
* **Windows bash resolution**: Comet now resolves a usable bash executable through `COMET_BASH`, rejects the Windows WSL launcher path, and uses the resolved executable for nested script calls so guard, handoff, and archive flows do not fall back to a broken PATH `bash`.
* **Shell test runner bash resolution**: `run-bats.js` now resolves a usable bash through `COMET_TEST_BASH`, `COMET_BASH`, PATH, or Git Bash defaults, avoiding the broken Windows WSL launcher when running shell tests from Node.
* **Schema validation fatal output**: Guard validation now preserves the final fatal schema-validation message after printing validator diagnostics, making invalid `.comet.yaml` failures easier to recognize.
### Tests
* **Superpowers skill invocation regression**: Added coverage that shipped Comet skill prose does not reference plugin-prefixed Superpowers aliases.
* **Comet bash execution regression**: Added coverage for nested script calls, shipped command examples, and the shell test runner so Comet uses resolved bash paths instead of raw PATH `bash`.
* **Plan-ready pause regression**: Added shell-script coverage for `build_pause` initialization, schema validation, state updates, and build recovery output.
* **README state-field regression**: Added README coverage to ensure `build_pause` appears in examples and field descriptions for both English and Chinese documentation.
### Added
* **Context compaction recovery (`--recover`)**: `comet-state check --recover` outputs a structured recovery context, including phase status, field progress, task count, and recovery actions, used for agent context compression to quickly locate breakpoints and resume operations.
* **Red Flags Anti-Rationalization List**: Added 5 red flag warnings to the main scheduling skill (making decisions for the user, skipping confirmation, replacing historical preferences, agreeing without objection, and passing without verification), helping the agent identify its own overreach tendencies.
* **Uncertainty Degradation Principles**: Added SUGGESTION > WARNING > CRITICAL degradation rules to the verify skill. Only build failures, test failures, and security issues are marked CRITICAL; ambiguous issues must be downgraded.
* **Anti-Automatic Selection Guardian**: Added naming and scope anti-automatic selection rules to the open skill. Name changes must be specified by the user or AskUserQuestion. Confirmation: The scope cannot be expanded or narrowed arbitrarily.
* **File Existence Verification**: Before entering user confirmation, the open skill verifies that the proposal/design/tasks files are not empty, preventing empty files from skipping the check.
* **Idempotency Description**: Idempotency descriptions have been added to all skill stages (open/design/build/verify), clarifying which operations can be safely retried and which fields require confirmation before skipping.
### Changed
* **AskUserQuestion Tool Clarification**: All 7 decision blocking points (open confirmation, brainstorming confirmation, build workflow, verify failure decision, spec drift handling, branch handling, upgrade conditions) are uniformly required to use the AskUserQuestion tool; plain text prompts are prohibited.
* **Decision Points Expanded from 6 to 7**: The open stage proposal/design/tasks review confirmation is now the first decision point.
* **Spec Drift Single-Choice Question Format**: Spec drift handling in the verify stage has been changed to an AskUserQuestion single-choice question (A/B/C). (Choose one of three), no longer implicit default option
* **Completely synchronized Chinese and English skills**: The content, structure, and option format of the 7 Chinese skills and 7 English skills are completely aligned.
### Fixed
* **Crash due to unbound variables in `set -u`**: When `comet-state check --recover` is missing `tasks.md` during the build phase, the `pending` variable is not declared, causing the script to exit directly; this is fixed by moving the `local` declaration forward and adding an explicit branch `tasks.md MISSING` to the recovery action chain.
* **Path truncation risk**: `field_status` using `${var%% *}` on `design_doc` may truncate paths containing spaces; changed to `${var% }` to only remove trailing spaces.
* **Inconsistent reading style for optional fields**: `direct_override` uses `|| echo ""` while other optional fields use `|| true`; unified to `|| true` to be consistent with `cmd_scale`.
### Tests
* Added 8 `check --recover` and boundary test cases, covering five phases: open/build/verify/design/archive, as well as boundary scenarios such as missing tasks.md and all tasks completed.
* Total number of tests increased from 34 to 42, all passed.
### Changed
* **Command execution security**: Refactored all command execution in OpenSpec and Superpowers install paths from `spawn` with shell interpretation to `execFileSync`, eliminating shell injection surface and improving cross-platform reliability (#88bf487)
### Fixed
* **OpenSpec global install path for OpenCode**: `comet init --scope global` now migrates OpenSpec skills from the hardcoded `~/.opencode/` directory to `~/.config/opencode/` where OpenCode actually reads them, with a self-deletion guard when source and destination paths coincide (#46, @gleami)
* **Windows command execution**: Added `shell` option to `execFileSync` calls on Windows so command shims (.cmd) resolve correctly
* **Doctor `.comet.yaml` validation**: `comet doctor` now validates top-level keys instead of silently accepting unknown keys, and `readDir` errors other than ENOENT are no longer swallowed (@felamin)
* **CI JSON parsing**: CI workflow parses command output by finding the first `{` character, preventing non-JSON prefix lines from breaking JSON extraction (@yicochen)
* **CI warning output**: CI now only counts and prints warnings when a step actually fails, reducing noise in successful runs (@yicochen)
* **Spawn stdio noise**: Changed `inherit` to `ignore` for non-interactive spawn stdio so OpenSpec/Superpowers installers don't print unrelated progress to the console (@yicochen)
### Tests
* Added coverage for OpenCode global OpenSpec path migration, self-deletion guard, and homedir mocking
* Added doctor tests for `.comet.yaml` top-level key validation and non-ENOENT `readDir` error propagation
* Fixed timeout for git-based test "uses plan base-ref to scale verification"
### Docs
* Improved README setup guidance with clearer installation instructions and collapsible reference panels (both English and Chinese) (@hepeng)
* Added contributors wall to both README and README-zh (@Joechan11)
### New Contributors
* @felanny made their first contribution in #38
* @Joechan11 made their first contribution in #44
* @bevishe made their first contribution in #47
* @kathy32 made their first contribution in #39
* @gleami made their first contribution in #46
### Fixed
* **OpenSpec all-workflows installation**: `comet init` now writes the all-workflows config directly to the platform-specific default config path (`%APPDATA%\openspec\` on Windows, `$XDG_CONFIG_HOME/openspec/` on macOS/Linux when set, otherwise `~/.config/openspec/`) in addition to the isolated `XDG_CONFIG_HOME` env override, ensuring all 11 OpenSpec workflows are always installed regardless of the user's previous OpenSpec config state.
### Added
* **Script discovery helper**: New `comet-env.sh` centralizes script path resolution by sourcing sibling scripts from its own directory, replacing the scattered `COMET_SEARCH_ROOTS` find logic across all English and Chinese skills.
* **OpenCode global config directory**: OpenCode platform now supports a separate `globalSkillsDir` (`.config/opencode`) for global installs, keeping project and user-level skills distinct.
* **Command error diagnostics**: New `command-error.ts` module extracts and cleans stderr/stdout from failed shell commands, used by both OpenSpec and Superpowers install paths to surface actionable failure details.
### Changed
* **Build decision-point wording**: Strengthened the build skill's workspace-isolation and execution-method selection wording so agents cannot choose on behalf of the user based on recommendation rules.
* **Hotfix/Tweak upgrade wording**: Reworded upgrade-condition and verification-failure pause requirements in hotfix and tweak skills for clearer blocking semantics.
* **Comet user decision numbering**: Fixed out-of-sequence numbering in the Chinese comet skill's user decision point list.
### Fixed
* **OpenSpec workflow installation**: `comet init` now runs OpenSpec with `--profile custom` and a temporary config that enables all workflows (`propose`, `explore`, `new`, `continue`, `apply`, `ff`, `sync`, `archive`, `bulk-archive`, `verify`, `onboard`), ensuring Comet installs more than the default core workflow set.
* **OpenCode slash commands**: `comet init` now generates OpenCode command files (`commands/*.md`) that keep the `/comet*` command names while embedding the corresponding Comet workflow content, so OpenCode users can invoke `/comet`, `/comet-open`, etc. directly.
* **Lingma Superpowers path**: `comet init` now keeps Lingma out of the unsupported `skills --agent lingma` path and copies staged Superpowers skills into `.lingma/skills`, preventing the whole external installer batch from failing while preserving Lingma's expected directory layout.
* **Lingma global directory**: Lingma's global skills directory is explicitly `.lingma`, matching `~/.lingma/skills/{skill-name}/SKILL.md` for user-level installs and `.lingma/skills/{skill-name}/SKILL.md` for project installs.
* **Script discovery safety**: `comet-env.sh` no longer changes caller shell options when sourced, returns failure when bundled scripts are missing, and avoids ShellCheck unreachable-command diagnostics.
* **comet-state.sh field whitelist**: Added `created_at` and `base_ref` to the `cmd_set` allowed fields list, aligning validation with fields already written during `.comet.yaml` initialization.
### Tests
* **Script discovery coverage**: Added tests verifying `comet-env.sh` exports all bundled script paths and that no skill file inlines `COMET_SEARCH_ROOTS`.
* **Script discovery safety**: Added regression coverage for sourced shell option preservation and expandable `$HOME` skill-directory globs.
* **OpenCode Comet detection**: Added tests for OpenCode requiring both skill directories and matching command files before reporting Comet as installed.
* **OpenCode E2E init**: Added end-to-end tests for OpenCode project and global scope installs, including command file generation.
* **OpenCode command content**: Added tests that OpenCode command files preserve Comet command names and include full selected-language workflow content instead of a thin skill-delegation stub.
* **English workflow safeguards**: Added parity tests matching the existing Chinese workflow decision-point requirements.
* **OpenSpec profile and diagnostics**: Added tests for custom profile creation, `--profile custom` flag, and stderr/stdout detail printing on install failures.
* **Lingma Superpowers fallback**: Added regression coverage that Lingma is excluded from the unsupported skills CLI agent list and uses a staging install before copying skills to `.lingma`.
* **Lingma global install path**: Added regression coverage for `comet init --scope global` installing Lingma Comet skills under the user `.lingma/skills` directory.
### Added
* **Workflow state metadata**: `.comet.yaml` initialization now records `base_ref` and `created_at` so scale assessment and validation can reason from a stable change baseline.
### Changed
* **Comet decision points**: Clarified Chinese and English workflow skills so design confirmation, build configuration, verification failures, spec drift, branch handling, and preset upgrades pause for explicit user choice instead of relying on defaults or recommendations.
* **Build workflow selection**: Combined workspace isolation and execution-method selection into one build configuration step, reducing repeated pauses while still requiring `isolation` and `build_mode` before implementation can continue.
* **Hotfix verification flow**: Moved root-cause elimination before the build guard and requires preset upgrades to switch `workflow` to `full`, keeping failed hotfix checks in the build phase and full-flow upgrades in a consistent state.
* **Verification scale assessment**: Scale checks now fall back to `.comet.yaml` `base_ref` and use a four-file threshold for full verification, making committed build changes less likely to be undercounted.
* **English skill parity**: Synced English Comet skills with the Chinese workflow rules, including handoff generation, dirty-worktree handling, spec drift decisions, and verification failure blocking.
### Fixed
* **Windows npm update**: `comet update` now spawns npm through the shell so the package update path works reliably with Windows command shims.
* **Superpowers install diagnostics**: Failed Superpowers installs now print cleaned stderr details, making network or GitHub access failures visible instead of hiding the actionable cause.
### Tests
* **Workflow safeguard coverage**: Added regression coverage for Chinese Comet decision-point requirements and Superpowers install failure diagnostics.
### Added
* **Dirty worktree recovery protocol**: Added shared English and Chinese `comet/reference/dirty-worktree.md` references so agents consistently protect, inspect, and attribute user or mixed-source working tree changes during resume
### Changed
* **Comet resume behavior**: Updated `/comet`, build, verify, hotfix, and tweak skills so manual code edits made during interruptions are treated as code evidence, not automatic state transitions; agents must attribute dirty worktree changes before continuing or advancing guards
### Fixed
* **Reference skill installation**: Added the dirty worktree reference file to the Comet manifest so installed English and Chinese skill sets can resolve `comet/reference/dirty-worktree.md`
### Changed
* **Antigravity skill paths**: Updated platform handling so project-scope installs use `.agents/skills` while global installs use Antigravity's `.gemini/antigravity/skills` location, keeping `init`, `doctor`, and `update` aligned with Antigravity's directory model
* **README information architecture**: Reworked English and Chinese README sections so command details, platform lists, skill tables, script tables, `.comet.yaml` fields, and reliability notes are available in collapsible reference panels
* **Spec lifecycle documentation**: Expanded the README explanation of Comet's Spec lifecycle management, including OpenSpec/Superpowers artifact linking, automated handoff, state updates, validation, and archive sync
* **Security guidance location**: Moved repository maintenance security notes from README into `CONTRIBUTING.md`, keeping the README focused on user-facing Comet concepts and setup
### Fixed
* **Antigravity global installs**: Fixed `comet init --scope global` and related health checks so Antigravity no longer installs or searches global skills under the project-style `.agents` directory
* **Missing skills directories**: Added explicit existence checks before scanning project and global skills directories, keeping detection and update logic robust when platform directories exist without `skills/`
### Tests
* **Antigravity path coverage**: Added regression coverage for Antigravity project/global skill directories across detection and init E2E behavior
* **README structure coverage**: Verified the updated README command and reference structure with the existing README test suite
### Added
* **Design handoff script**: New `comet-handoff.sh` generates deterministic, source-traceable context packages (compact or full mode) from OpenSpec artifacts into `.comet/handoff/`, recording `handoff_context` and `handoff_hash` in `.comet.yaml`
* **Handoff guard checks**: Design phase guard now validates handoff context existence, hash freshness (detects post-handoff OpenSpec mutations), markdown traceability markers, and design doc frontmatter fields (`comet_change`, `role: technical-design`, `canonical_spec: openspec`)
* **`handoff_context` and `handoff_hash` fields**: New `.comet.yaml` fields for tracking script-generated handoff packages, with schema validation (path existence, sha256 hex digest format)
* **`comet init --scope`**: New `--scope ` CLI flag for non-interactive scope selection
* **CI init E2E job**: GitHub Actions now runs real `comet init` on Ubuntu, macOS, and Windows, verifying Comet skills, Superpowers, OpenSpec, and working directories land in correct filesystem locations for both project and global scope
### Changed
* **Chinese skill docs updated**: `comet-design/SKILL.md` and `comet/SKILL.md` now document the handoff flow, replacing agent-authored summaries with script-generated context packs
* **JSON generation uses process substitution**: `write_json_context` in `comet-handoff.sh` uses `< <(source_files)` instead of pipe subshell, fixing variable scoping
* **Error message formatting**: `comet-state.sh` unknown-field error message split from a single 270+ character line into multiple lines for readability
* **CLAUDE.md and AGENTS.md**: Added project-level instructions covering test commands, shell script conventions, script dependency graph, `.comet.yaml` state machine sync rules, and changelog format
### Fixed
* **YAML and frontmatter parsing**: Comet scripts now ignore unquoted trailing comments in `.comet.yaml` field values and accept Design Doc frontmatter after a UTF-8 BOM or leading blank lines, preventing false guard and handoff failures
* **Init E2E install checks**: CI now verifies Comet-owned skill artifacts in every supported platform directory and checks OpenSpec/Superpowers installer status from `comet init --json` for both project and global installs, avoiding false failures from external CLI-specific directory layouts
* **Windows global init E2E home directory**: CI now sets `USERPROFILE` alongside `HOME` for global-scope init checks on Windows, matching Node's `os.homedir()` resolution and preventing false missing-skill failures
* **README state documentation**: README examples now show accurate `.comet.yaml` build-state defaults, verification evidence timing, handoff fields, and project-only working directory creation
* **Windows Superpowers init timeout**: Superpowers external installer timeout increased to tolerate slower Windows `npx skills add` runs, reducing flaky init E2E failures
### Tests
* Added coverage for `--full` handoff mode, missing OpenSpec artifacts rejection, post-handoff hash mismatch detection, and design doc frontmatter validation
* Added `comet init` E2E tests covering project scope install, global scope install, skip-existing with `--yes`, overwrite with `--overwrite`, and multi-platform detection
* Added regression coverage for `.comet.yaml` trailing comments and Design Doc frontmatter with a UTF-8 BOM or leading blank lines
* Added CI workflow regression coverage for project and global installation checks across Comet-owned files and external OpenSpec/Superpowers installer statuses
* Added CI workflow regression coverage for Windows global init using the temporary `USERPROFILE` home directory
* Added regression coverage for the longer Superpowers installer timeout used by init
### Fixed
* **OpenSpec global init**: `comet init` global scope now passes the home directory as OpenSpec's init target instead of using the unsupported `openspec init --global` flag
* **Cross-platform path quoting**: OpenSpec init targets are shell-quoted for Windows, macOS, and Linux paths, including home directories with spaces
* **Installer argument quoting**: OpenSpec `--tools` values and Superpowers `--agent` values are now shell-quoted, and Windows OpenSpec paths preserve trailing backslashes before the closing quote
* **Superpowers multi-platform install**: Superpowers installation now passes repeated `--agent` flags instead of a comma-separated agent list, matching the `skills` CLI behavior
* **Superpowers agent mappings**: Updated Comet platform mappings to valid `skills` CLI agent IDs, with unsupported platform-specific IDs falling back to `universal`
### Tests
* Added regression coverage for OpenSpec global init command construction across Windows, macOS, and Linux
* Added regression coverage for OpenSpec Windows trailing-backslash quoting and quoted installer arguments
* Added Superpowers coverage for valid `skills` CLI agent mappings and multi-agent argument formatting
* Smoke-tested project and global initialization outputs for all 28 supported platforms in isolated temporary directories
### Added
* **Build decision enforcement**: Build guard and `comet-state.sh transition build-complete` now require `isolation` and `build_mode` before moving from build to verify
* **Direct mode override**: Full workflows must set `direct_override: true` before using `build_mode: direct`; hotfix/tweak remain allowed by default
* **Configurable guard commands**: Guard scripts now read `build_command` and `verify_command` from the change `.comet.yaml` or repo-root Comet config before falling back to auto-detected build commands
* **Archive diff preview**: Archive sync prints a unified diff before overwriting an existing main spec when it differs from the delta spec
* **Cross-platform script smoke CI**: Added Ubuntu, macOS, and Windows smoke coverage for Comet shell scripts and portable shell tests
* **Shell line-ending policy**: Added `.gitattributes` rules to keep shell and Bats scripts on LF endings
### Changed
* **Guard failure output**: Guard checks now preserve and print command failure output, plus actionable `Next:` hints for missing build decisions and unfinished tasks
* **Command handling**: Project commands run through `bash -lc`, Maven uses `mvnw` or `mvn.cmd` where appropriate, and Windows Git Bash paths are handled in shell test helpers
* **Archive step counting**: Dry-run, delta sync, annotation, move, and archive status steps now count real executed steps without double-counting repeated operations
* **English docs and skills**: Synced the English README and Comet skill text with the Chinese build-decision, command-config, and archive behavior descriptions
### Fixed
* **macOS shell script state updates**: Replaced GNU-only `sed -i` writes in `comet-state.sh` with portable temp-file updates, fixing macOS CI failures during `scale`, `transition`, and YAML field updates
* **Optional field reads under pipefail**: Guard and state scripts now tolerate missing optional YAML fields without exiting early under `set -euo pipefail`
* **Bash detection fallback**: Shell test helpers now handle failed `bash` probes without crashing on empty `spawnSync` output
* **Configured command persistence**: `comet-state.sh set` now escapes sed replacement metacharacters so command values containing `&`, `|`, or backslashes are preserved
* **Optional schema fields**: YAML validation now recognizes `direct_override`, `build_command`, and `verify_command`
* **Quoted YAML values**: State, guard, and validator scripts now strip only wrapping quotes instead of deleting all quote characters from values
### Tests
* Added coverage for missing build decisions, direct-mode override blocking and allowance, configured build/verify commands, command metacharacter preservation, unfinished-task remediation output, archive step counts, cross-platform path handling, BSD/GNU sed portability, optional YAML field reads under `pipefail`, and failed bash probe handling
### Added
* **PR title lint workflow**: Added GitHub Actions validation for semantic PR titles with Comet-specific scopes (`cli`, `commands`, `core`, `skills`, `assets`, `scripts`, `docs`, `ci`, `deps`, `release`)
* **Structured JSON output**: `comet init --json` and `comet update --json` now emit machine-readable results instead of mixed human logs
* **`doctor --scope`**: `comet doctor` can diagnose `auto`, `project`, or `global` scope, with `auto` checking both project and global installs
* **Next-step status hint**: `comet status` now reports the next workflow command (`/comet-open`, `/comet-design`, `/comet-build`, `/comet-verify`, `/comet-archive`) in text and JSON output
* **README asset guard**: Added tests and prepublish validation to keep README images on npm-friendly absolute URLs
### Changed
* **`comet update` preserves installed context**: Update now detects existing Comet skill targets across project/global scopes, preserves installed scope, detects Chinese vs English skills, and updates only platforms where Comet skills are already installed
* **`comet update` self-updates npm package**: Update now prints and runs the matching npm update command for the detected package scope before refreshing installed skills
* **Friendlier update output**: Update logs the npm command, per-target skill copy command, final npm status, updated target count, scope, and language summary
* **Init overwrite flow**: Interactive `comet init` now offers a bulk overwrite/skip choice when multiple existing components are detected on the same platform
* **CLI option validation**: `update --language`, `update --scope`, and `doctor --scope` now validate accepted values through Commander choices
* **README CLI docs**: Updated English and Chinese README command sections to document JSON output, doctor scope, update behavior, status next-step hints, and init overwrite behavior
* **CONTRIBUTING link**: Added contribution guide references to both English and Chinese README development sections
### Fixed
* **Doctor false positives**: `comet doctor` now recognizes current `.comet.yaml` fields including `verification_report` and `branch_status`
* **npm README images**: README images now use absolute GitHub URLs so package pages can render them
### Tests
* Added coverage for update language/scope detection, JSON output, friendly command display, status next-step hints, doctor current-state validation, README image URLs, init bulk overwrite selection, and PR title workflow configuration
### Added
* **Verification evidence enforcement**: `verify-pass` transition now requires `verification_report` (file must exist) and `branch_status: handled` before allowing phase advance. Guard checks these as hard prerequisites
* **`verification_report` and `branch_status` fields** in `.comet.yaml`: New state fields track verification report path and branch handling status
* **Verification evidence step** in comet-verify (zh): New Step 4 requiring report file creation and branch status recording before guard apply
* **`branch_status` enum validation**: `comet-state.sh set` validates `branch_status` as `pending` or `handled`
* **Guard verify checks**: `comet-guard.sh` now checks `verification_report exists` and `branch_status=handled` during verify phase
* **Bats test CRLF fix**: Shell tests strip `\r` from scripts before execution, fixing Windows compatibility
* **`test:shell` runner**: Replaced direct `bats` call with `node scripts/run-bats.js` for cross-platform support
### Changed
* **Hotfix root cause check reordered**: Moved root cause elimination check **before** comet-verify loading (Step 3a → 3b split), preventing it from being skipped during verify flow
* **Hotfix header description simplified**: Replaced ambiguous "not a separate parallel process" with direct "Quick bug fix workflow" for standalone invocation clarity
* **Removed non-action steps from comet-design**: Deleted Step 3 (Dual Spec Division table) and Step 4 (Document Hierarchy) — pure reference material with no agent actions
* **Removed duplicate script location blocks**: comet-open (Step 3) and comet-archive (Step 1) no longer repeat the full `COMET_SEARCH_ROOTS` find block when variables already cached
* **Removed duplicate 50% threshold in comet-build**: Single mention in threshold determination table instead of table + bullet repetition
* **Generic error handling**: Error table in comet main skill changed "Maven compile/test" → "Build/test" for language-agnostic wording
* **comet-state.sh usage help**: Fixed `check` parameter order in help text (`check `)
### Fixed
* **comet-state.sh `init` change directory resolution**: `cmd_init` now resolves `change_dir` before checking if `.comet.yaml` already exists, fixing path resolution for nested directories
* **Guard deadlock on verify**: `verify-pass` transition now resets `verification_report` and `branch_status` when rolling back via `verify-fail`, preventing stale evidence from allowing false transitions
### Tests
* **+66 lines** in `comet-scripts.test.ts`: New tests for verification evidence blocking, branch status validation, and guard verify with evidence
* **+12 lines** in `comet-state.bats`: New tests for `branch_status` enum validation, CRLF stripping, and new field presence in init output
### Added
* **"Why Comet" section**: README now explains the rationale behind Comet — how it combines OpenSpec's WHAT management with Superpowers' HOW execution into a unified 5-phase pipeline
* **"Screenshots" section**: Added three screenshots demonstrating platform selection, initialization, and skill execution in action
* **"What You'll Learn" section**: New section showcasing Comet as a reference for stable nested skill triggering and multi-phase auto-flow patterns
* **State Management YAML example**: Extended documentation with complete `.comet.yaml` field example showing all key configuration values
### Changed
* **comet-build skill description**: Clarified that execution mode (subagent vs executing-plans) is user-selectable based on task complexity, not always subagent-driven
* **Enhanced State Management docs**: Added explanation of how all states and phases are updated via scripts with completion validation before phase transitions
### Fixed
* **Ctrl+Z/Ctrl+C crash during `comet init`**: Wrapped inquirer prompts in try/catch to handle `ExitPromptError`, showing `Cancelled.` and exiting cleanly instead of printing a raw stack trace
* **Duplicate Superpowers installation**: `comet init` now detects Superpowers installed via Claude Code plugin system (`~/.claude/plugins/cache/`), skipping redundant `npx skills add` when Superpowers plugin is already present
### Fixed
* **CI pnpm version**: Added `packageManager` field for pnpm/action-setup v4
* **Shell scripts**: Fixed `SCRIPT_DIR` typo, renamed `maven_compiles` → `build_passes` (language-agnostic), fixed `check_nonempty` path bug, fixed `cmd_set` sed delimiter for path values, corrected shellcheck directive placement
* **Node version**: Bumped minimum to Node 20 (vitest v4 coverage requires `node:inspector/promises`)
Comet 0.2.0 is a comprehensive optimization release: skill reliability, CLI completeness, and engineering quality.
### Skill Reliability
* **SKILL.md two-zone structure**: All 8 skills split into "Decision Core" (phase detection, upgrade criteria, error handling) and "Reference Appendix" (field reference, scripts, best practices)
* **Quantified upgrade criteria**: Hotfix/tweak now define explicit thresholds for upgrading to full workflow (file count, cross-module coordination, architecture changes, etc.)
* **Script location caching**: All skills use `${VAR:-$(find ...)}` env-var cache pattern, avoiding repeated `find` calls
* **`manifest.json` fixed**: Added missing `comet-state.sh` and `comet-archive.sh` entries
* **`comet-state.sh init` fixed**: Now writes `workflow` field to `.comet.yaml`, fixing `check design` which always failed
### CLI Commands
* **`comet status`**: Show active changes with phase, task progress, workflow mode, design doc, and plan (`--json` supported)
* **`comet doctor`**: Diagnose installation health — OpenSpec CLI, working directories, skill completeness per platform, script presence, `.comet.yaml` validity (`--json` supported)
* **`comet update`**: Update comet skill files to latest version from npm package (`--language`, `--scope` supported)
* **`--json` on all commands**: `init`, `status`, `doctor`, `update` all accept structured output
### Engineering
* **Test suite**: 54 unit tests (5 suites) with 93.8% statement / 100% function coverage; 26 bats shell tests
* **GitHub Actions CI**: Build + lint + format + test (Node 18/20/22) + shellcheck + bats on push/PR
* **ESLint + Prettier**: Code quality tooling with `pnpm lint` / `pnpm format`
* **Code organization**: Monolithic `init.ts` (620 lines) split into 5 focused core modules + 4 command modules
* **Command injection hardening**: Platform/tool ID validation before shell command construction
* **Per-file error handling**: Copy loop continues past individual file failures
### Added
* **`comet-state.sh` script**: Unified state management with 5 subcommands — `init` (create .comet.yaml), `set` (update with enum validation), `get` (read field), `check` (entry verification), `scale` (verification mode assessment)
* **`check` subcommand**: Scripted entry verification replacing text checklists in all 8 skills
* **`scale` subcommand**: Scripted scale assessment replacing prose decision rules in comet-verify
### Changed
* **All `.comet.yaml` writes go through `comet-state.sh`**: No more raw `sed -i` — enum validation on every field write
* **All skill Step 0 checklists replaced with `check` subcommand**: Single command replaces text-based entry verification
* **`comet-guard.sh` and `comet-archive.sh` use state.sh internally**: All state mutations through unified interface
* **Removed write-verification blocks**: hotfix and tweak presets no longer have manual verification loops
### Added
* **`comet-archive.sh` script**: One-command archive automation — validates entry state, syncs delta specs to main specs (overwrite), annotates design doc and plan frontmatter, moves change to archive directory, updates `archived: true`. Supports `--dry-run` for preview
* **`--apply` mode for `comet-guard.sh`**: Opt-in flag that auto-updates `.comet.yaml` state fields after all guard checks pass. No manual state editing required during phase transitions
* **Idempotent frontmatter annotation**: `annotate_frontmatter()` skips existing `archived-with:` lines, safe to re-run
### Changed
* **Removed manual state editing**: All phase transitions (design → build → verify → archive) now use `guard --apply` instead of manual `.comet.yaml` field updates and write-verification loops
* **Removed write-verification blocks**: Eliminated all `【写入验证】` / `【Write verification】` patterns from comet-open, comet-design, comet-build, comet-verify, and comet-archive skills
* **Removed `## ADDED`/`## MODIFIED`/`## REMOVED` delta format**: Delta specs are now complete specs; archive overwrites main spec instead of merging fragments
* **Removed step 2b from comet-open**: Incremental modification of existing capabilities is just a new `/comet-open` — brainstorming reads existing specs as context naturally
* **Simplified archive skill**: Steps 1b–5 replaced with single `comet-archive.sh` call
* **Updated `comet/SKILL.md`**: Script location section now documents both `--apply` mode and archive script
### Removed
* Few-shot YAML examples for `isolation`, `build_mode`, `verify_mode` fields (redundant with agent judgment)
* `openspec-archive-change` skill dependency from comet-archive (archive script handles all steps)
### Added
* **Workspace Isolation Selection**: `comet-build` now prompts users to choose between creating a branch or a worktree before execution begins (Step 3: Workspace Isolation)
* **`isolation` field in `.comet.yaml`**: New required field (`branch` or `worktree`) to record the user's workspace isolation choice
* **`isolation` enum validation**: `comet-yaml-validate.sh` now validates `isolation` as a required field with allowed values `branch`/`worktree`
### Changed
* `comet-build` step numbering: Step 3 (Select Execution Method) → Step 4, Step 4 (Spec Incremental Updates) → Step 5
* Hotfix and tweak presets default to `isolation: branch` without prompting
* `comet-yaml-validate.sh` `REQUIRED_FIELDS` and `KNOWN_KEYS` updated to include `isolation`
### Added
* **Bilingual Comet skills**: `comet init` now prompts for language selection (English / 中文) and deploys the corresponding SKILL.md files
* **Language-aware asset structure**: English skills in `assets/skills/`, Chinese skills in `assets/skills-zh/`
* **`languages` field in manifest.json**: Maps language IDs to asset directories for future extensibility
### Changed
* All 8 Comet SKILL.md files in `assets/skills/` are now English (Chinese originals preserved in `assets/skills-zh/`)
* `copyCometSkillsForPlatform` accepts `languageSkillsDir` parameter; script files always sourced from default `skills/` directory
* `--yes` mode defaults to English language selection
### Fixed
* **Superpowers redundant project-level install**: `comet init` now checks the global directories (`~/{platform}/skills/`) of all user-selected platforms before installing Superpowers. If Superpowers is already installed globally for any selected platform, the project-level install is skipped
* **Unwanted `.agents/` directory creation**: `comet init` now passes `--agent` flag to `skills add`, targeting only the platforms the user selected. This prevents the skills CLI from auto-detecting and installing to all platforms, which previously created an unnecessary `.agents/` directory
* **OpenSpec global detection**: Same global-directory fallback logic applied to OpenSpec detection, avoiding redundant OpenSpec installs when already present globally for selected platforms
### Changed
* `hasSkills()` accepts `selectedPlatforms` parameter to scope global detection to user-chosen platforms only
* `installSuperpowersForPlatform()` replaced with `installSuperpowersForPlatforms()` that accepts platform IDs and maps them to skills CLI agent names via `SKILLS_AGENT_MAP`
### Added
* **State File Separation**: Comet workflow state now stored in independent `.comet.yaml` file instead of `.openspec.yaml` subtree
* **Three-Layer Reliability Defense**:
* Entry verification for all phases with `[HARD STOP]` diagnostics
* Write-then-verify pattern for all state mutations
* Schema validator script (`comet-yaml-validate.sh`) with field, enum, and path validation
* **Path Traversal Protection**: Input validation for change names to prevent directory traversal attacks
* **Guard Script Integration**: Automatic schema validation during phase transitions
### Changed
* Updated all 9 Comet skills to use `.comet.yaml` instead of `.openspec.yaml` comet: subtree
* Improved error messages with specific field values instead of generic placeholders
* Enhanced project structure documentation
### Security
* Fixed path traversal vulnerability through unvalidated change name inputs
* Schema validation now catches typos and invalid enum values at entry point