Skip to main content
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 <artifact-root>/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

Examples:
artifact-root must be a project-relative path and defaults to docs. . means <project>/comet/, while docs means <project>/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

change-name and capability IDs start with a letter and use lowercase kebab-case. new creates default configuration and <project>/docs/comet/ when configuration is absent. For new or replaced durable behavior, write the complete target specification at:
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 <change-name> 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

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

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

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

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

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.

​
Hosts that expose only Skill files

If the host does not have the comet CLI, use the Runtime shipped with /comet-native directly:
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.
Last modified on July 22, 2026