> ## 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. # Native CLI > Initialize Native, manage changes, preserve in-phase progress, advance state, bind verification evidence, and recover or archive safely. `comet native` is the deterministic Runtime entry for the Native workflow. Its state and workflow artifacts belong only to the shared `.comet/config.yaml` project configuration and configured `/comet/`; it neither reads nor converts Classic/OpenSpec changes. To build baselines and implementation scopes, the Runtime reads project-owned file content within fixed budgets. When Git metadata exists, it invokes Git only as part of building the Git-aware snapshot. It never invokes external Skills, a shell, or project commands. The built-in `comet native check` still invokes neither Git nor any external process. ## Initialize and manage the artifact root ```bash theme={null} comet native init [--root ] [--language en|zh-CN] comet native root show comet native root move ``` Examples: ```bash theme={null} # Default: /docs/comet/ comet native init --language en # Optional: /comet/ comet native init --root . --language en # Transactionally move to /artifacts/comet/ comet native root move artifacts ``` `artifact-root` must be a project-relative path and defaults to `docs`. `.` means `/comet/`, while `docs` means `/docs/comet/`. `init --language` persists the default language for future Native changes in `.comet/config.yaml`. `new --language` can override it for one change. Running `init --language` again changes only the default for future changes and never rewrites existing ones. Existing configuration rejects a conflicting `init --root`. Change directories through `root move`, never by editing configuration. Migration progresses through `copying`, `ready`, and `switched`. While `pending_root_move` exists, ordinary write commands fail closed so two trees cannot become writable at once. ## Change management ```bash theme={null} comet native new [--language en|zh-CN] comet native spec remove comet native spec rebase --summary comet native list [--cursor ] comet native show comet native status [--cursor ] comet native status [--details [--acceptance-cursor ]] comet native select ``` `change-name` and capability IDs start with a letter and use lowercase kebab-case. `new` creates default configuration and `/docs/comet/` when configuration is absent. For new or replaced durable behavior, write the complete target specification at: ```text theme={null} changes//specs//spec.md ``` The Runtime derives `create` or `replace` from canonical-spec existence and freezes `base_hash`. Use `spec remove` to remove a capability; never maintain `comet-state.yaml`'s `spec_changes` by hand. If a parallel change has modified the same canonical specification, re-read and rewrite the complete target, then use `spec rebase` to refresh the baseline, reopen Build, and clear the old verification conclusion. ### Baseline and Git-aware snapshots `new` captures a complete baseline before committing change state. A Git project includes only tracked and non-ignored untracked files. Ignored caches and contents of unregistered nested repositories are outside the project-owned set, while each submodule/gitlink is one atomic entry. Non-Git projects use the bounded physical-tree provider. Any omitted project-owned item returns structured `baseline-incomplete` and removes the unfinished change instead of deferring an unusable baseline until Build. Git selection requires one stable, bounded enumeration: * `git-selection-changed` means the Git index changed during enumeration. Wait for `git add` and other Git writes to finish, then rerun the command. Never authorize past it as partial scope. * `git-enumeration-limit` means the tracked plus non-ignored untracked project-owned set exceeds the Git enumeration safety budget. This is structural incompleteness. First reduce or clean the project-owned set, or use a later Comet version that adjusts the product budget; never bypass it directly or by default. If recovery is genuinely impossible, use the ordinary partial protocol only when the Runtime returns an authorizable scope bound to a count and content hash and the user understands the unknown-tail risk, with the exact hash, a reason, and `--confirmed`. Never edit snapshot/evidence or guess unenumerated paths. For non-Git projects, physical selection uses bounded, order-independent before/after enumeration fences: * `physical-selection-changed` means the project tree changed during capture. Wait for concurrent filesystem activity to finish, then retry. * `physical-enumeration-limit` means the node, path, byte, or cooperative execution budget was exhausted. Reduce the project tree or move non-project content outside the project-owned set, then retry. Neither physical integrity failure can bind an unknown tail to a stable scope, so neither is authorizable as partial scope, including for a current snapshot. Ordinary omissions include a reason, counts, and bounded sample paths. Baseline creation and a migration cutover require completeness; neither Git selection omission is authorizable there. For a later current snapshot, only a partial scope that the Runtime explicitly makes authorizable may proceed with its exact hash. `git-selection-changed` must still be eliminated first; `git-enumeration-limit` is available only as the last-resort path described above. ### Bounded status views `list` and `status` without a change name return the same read-only paginated projection: * At most 24 active changes per page. * At most 4096 visible changes are accepted. * Pass a non-null `nextCursor` unchanged to the next `--cursor` call. * The cursor binds the complete change-name set and fails explicitly after a change is added or removed. `status ` returns the phase, evidence freshness, finding summary, checkpoint, repair state, and structured continuation. Add `--details` for up to 50 detailed findings, recovery information, and the first `acceptancePage`. If `findingsTruncated` is `true`, never assume undisplayed items do not exist. When `acceptancePage.nextCursor` is non-null, retrieve pages with `--acceptance-cursor`. Each page contains at most 16 items, and the cursor binds both the change and current acceptance hash. `show` enforces hard budgets on specification count, per-file and cumulative reads, and final output. On overflow it rejects the request instead of pretending success by truncating requirements. ## In-phase checkpoints ```bash theme={null} comet native checkpoint \ --summary \ --next-action \ [--artifact ]... \ [--expect-revision ] ``` A checkpoint stores an in-phase summary, next action, and content-addressed artifact manifest without changing phase. `--expect-revision` uses CAS so an old session cannot overwrite newer state. Resume from the checkpoint returned by `status`, not from chat memory. ## Built-in read-only checks ```bash theme={null} comet native check ``` `check` is available only in Verify after an implementation scope exists. It runs Comet's built-in bounded read-only text policy and writes an independent content-addressed receipt. It does not: * Invoke Git, a shell, project scripts, test commands, or external Skills. * Accept arbitrary commands, environment variables, paths, or timeout arguments. * Modify source code, change phase, Run state, or trajectory. A check that finds issues or a stale scope exits with `1`, but still saves its receipt. The model should continue to run real project tests according to task risk. The built-in check is reviewable supplemental evidence, not a general test runner. ## Phase progression ```bash theme={null} comet native next --summary \ [--confirmed] \ [--artifact ]... \ [--no-code-reason ] \ [--allow-partial-scope --partial-reason --confirmed] \ [--result pass|fail] \ [--report ] \ [--receipt ] \ [--failure-category ]... \ [--failed-check ]... \ [--override-repair --override-summary ] ``` | Current phase | Runtime requirement | Result | | ------------- | --------------------------------------------------------------------------------- | -------------------------------------------------- | | Shape | Complete brief, valid target specifications, no `[blocking]` question | Enter Build | | Build | Valid brief/specs; real artifact or no-code reason; complete implementation scope | Enter Verify | | Verify | Structurally complete report bound to current acceptance, contract, and scope | pass enters Archive; fail returns to Build | | Archive | Use the separate two-step archive command | Update canonical specifications and archive change | Pass `--confirmed` in Shape or Build only when the user has just confirmed a decision that changes scope, user-visible behavior, compatibility, risk, or an irreversible result. Without a high-impact decision, the Runtime records implicit approval. No confirmation can bypass a `[blocking]` question. On entry to Build, the Runtime binds approval to that moment's `approved_contract_hash`. If the brief or complete target specifications later change, Build remains blocked and returns `re-confirm-contract`. Pass `--confirmed` again only after the user reconfirms the current contract; never reuse an old confirmation or edit the hash. When Build cannot prove complete scope, the first call returns a scope hash and unattributed items without advancing. An incomplete current snapshot never turns an unobserved path into a deletion. When change details exceed the budget, bounded details remain and `scope-detail-overflow` represents the rest with a count and content hash. Only after the user explicitly accepts a concrete risk that the Runtime permits for authorization should you retry with the exact `--allow-partial-scope`, a non-empty reason, and `--confirmed`. The allowance binds to the scope hash and cannot authorize a changed implementation. `git-selection-changed`, `physical-selection-changed`, and `physical-enumeration-limit` are never authorizable. `git-enumeration-limit` may use the same ordinary partial protocol only after recovery attempts fail, the Runtime returns an authorizable scope, and the user understands the unknown-tail risk. The Verify report must contain the Runtime-readable acceptance block and bind every current Acceptance ID. An old report or receipt, changed brief/specification, changed implementation scope, or evidence from another revision is stale. If the contract or project snapshot changes after entering Verify, status returns a controlled summary-only `next`. Run it to retreat to Build and generate a new scope. Reconfirm with the user only when the brief/spec contract hash also changed. If only the project snapshot or implementation changed, preserve the existing `approved_contract_hash` instead of creating a meaningless confirmation. Do not submit pass/fail against a stale scope. Drift in any bound Archive fact uses the same retreat protocol; never reuse the old pass. ## Autonomous repair and stop semantics A Verify failure automatically returns to Build. The model may repair autonomously, while the Runtime forms a semantic signature from failure categories, failed check IDs, contract, and implementation scope: * The third identical failure signature under the same scope changes continuation to manual stop. * A genuine scope change makes the next Build progression close the old repair episode. * With unchanged scope, the exact signature returned by `status` may be overridden once with a non-empty summary. * A repair episode records at most 12 failures; reaching the budget creates a hard stop. These limits measure real evidence progress rather than mechanical phase switches, so a long-lived change is not permanently locked by a fixed Run-iteration cap. ## Two-step Archive ```bash theme={null} comet native archive --dry-run comet native archive --expect-preflight ``` Archive cannot be replaced by `next` or committed in one step: 1. Run `--dry-run`, inspect evidence, canonical hashes, target paths, and conflicts, and obtain `preflightHash`. 2. Pass that hash unchanged to `--expect-preflight`. 3. The Runtime recomputes every fact under lock and commits only on an exact match. Archive uses bounded identity-bound reads for source trees, canonical files, and transaction journals. Directory moves enter a transaction-bound quarantine before the irreversible commit. An interruption before the final marker can continue or roll back according to the journal. After the marker, only exactly-once continue is allowed, preventing a published archive result from being reversed. ## Diagnose and recover ```bash theme={null} comet native doctor [] comet native doctor [] --repair comet native doctor [] --repair [--strategy continue|rollback] ``` Doctor is non-mutating by default. `--repair` handles only facts the Runtime can prove safe: * Stale selections and locks. * Schema and workspace-identity migrations. * Phase-transition, Archive, and root-move transaction recovery. * Derived evidence/receipts that are unreferenced and beyond the retention window. * Interrupted retention quarantines. Doctor never rewrites user briefs, specifications, verification reports, or project source. Ordinary phase transitions support only `continue`; `rollback` applies only to Archive/root-move journals that have not crossed their irreversible boundary. New changes and current-schema v3 changes must retain the complete baseline captured at creation. If a v3 baseline is missing or incomplete, doctor does not rebuild it from current files because that would erase differences accumulated since creation. Restore it from a trusted backup, or preserve the user-authored artifacts and implementation facts while creating a new change. Explicit v1/v2 schema migration is the sole cutover exception. Before any state write, `doctor --repair` captures a complete baseline at the migration timepoint. An incomplete capture leaves the old state unchanged and stops. Post-migration implementation evidence proves only changes after that cutover; pre-migration chat, an old scope, or an old pass is not current evidence. A v2 change in Verify/Archive retreats to Build to establish fresh evidence. Ordinary write commands never take over a stale lock automatically. Only explicit `doctor --repair` may do so after proving the local owner is gone, lock identity is unchanged, and no conflicting transaction exists. Active locks and locks that cannot be proven stale are preserved. Evidence retention cleans only active-change derived evidence that is at least 30 days old, outside the latest 32 files of each evidence kind, and proven unreferenced through the dependency closure. Current-state references, archived evidence, dependencies, newer files, and the latest 32 of every kind are always retained. ## Continuation and exit codes `status` and write commands return structured continuation. Common dispositions include: * `continue-same-skill`: the current Skill can perform the next action. * `await-user`: a real user decision or partial-scope authorization is required. * `repair-runtime`: run doctor/recovery first. * `stop`: completed, manually stopped, or at hard stop. `next: auto` means the caller can continue in the same Native Skill. It does not mean a background daemon will invoke the model. Every command supports `--json`. JSON mode emits exactly one object containing `command`, `exitCode`, and `data`, plus a structured `error` on failure. | Exit code | Meaning | | --------- | ------------------------------------------------------------- | | `0` | Success | | `1` | Built-in `check` completed but found issues or became stale | | `64` | Invalid arguments or usage | | `65` | Invalid configuration, state, or artifacts | | `70` | Unexpected internal failure | | `73` | Lock, transaction, concurrent hash, or artifact-root conflict | | `75` | Repair stagnation or a hard stop blocks continuation | ## Hosts that expose only Skill files If the host does not have the `comet` CLI, use the Runtime shipped with `/comet-native` directly: ```bash theme={null} node /scripts/comet-native-runtime.mjs [options] ``` It uses the same arguments, output, and exit codes as `comet native`. Runtime and Skill ship together and depend on neither OpenSpec, Superpowers, grill-me, nor any other external Skill.