Skip to main content
Native persists facts that must survive across sessions. An Agent resumes from these files and the current repository rather than relying on chat memory. Users normally read the brief, specifications, and verification report; the Runtime owns state, hashes, locks, and transactions.

​
Project layout

The default layout is:
native.artifact_root can place comet/ under another project-relative directory. For example, artifact_root: docs maps to docs/comet/. Shared configuration and current selection remain under .comet/.

​
.comet/config.yaml

Native and Classic share this project configuration location. See Native configuration for the complete schema, examples, and safe update paths; the fields below directly affect Native artifacts: Classic-specific settings may remain in the same file without changing the Native state machine. Move the artifact root through comet native root move so the Runtime performs a transactional migration; do not edit YAML and move directories manually.

Xiaoyu files readable documents on an upper shelf and keeps state records and hash indexes in locked boxes below, showing recoverable responsibilities

​
User-readable artifacts

​
brief.md

The brief defines the change target and boundaries: Outcome, Scope, Non-goals, Acceptance examples, constraints, confirmed decisions, open questions, and verification expectations. [blocking] marks behavior that still requires a user decision.

​
Complete target specifications

changes/<change>/specs/<capability>/spec.md describes the complete behavior of a capability after archiving. It is not a delta patch that can only be understood beside an older document. The Runtime derives the operation from canonical-spec existence:
  • create creates a new canonical spec at archive time;
  • replace replaces the old version with the complete target, provided its base hash has not changed;
  • remove explicitly removes the capability through the CLI.
When concurrent work changes the baseline, spec rebase binds the change to the latest canonical specification and invalidates old verification.

​
verification.md

The report records actual commands, results, skip reasons, known limitations, the overall conclusion, and evidence for each Acceptance ID. The Runtime stores an immutable report snapshot and binds it to the contract, scope, and revision at that time.

​
Runtime-managed state

​
comet-state.yaml

Every active or archived Native change has its own comet-state.yaml. It records machine-owned phase, revision, approval, approved_contract_hash, verification, and specification-operation state. On entry to Build, approved_contract_hash binds approval to the brief/spec contract from that moment. Later contract drift requires fresh user confirmation. Do not edit these fields manually or confuse this file with Classic’s .comet.yaml.

​
Run state, trajectory, and checkpoint

  • Run state stores the current continuation and repair state;
  • trajectory stores bounded phase summaries, timestamps, and evidence references, not hidden reasoning;
  • checkpoint stores an in-phase summary, next action, and content-addressed artifact manifest for a new session.
A checkpoint does not replace the brief, specifications, or verification report and does not advance the phase.

​
Selection

.comet/current-change.json records which workflow and change owns current writes. This lets the shared Hook Router select one Guard when a project enables several workflows or changes. Read-only status does not change selection as a side effect; use comet native select <change-name>.

​
Bounded reads and content addressing

Native budgets change counts, specification size, findings, Acceptance IDs, output, and archive trees. Lists and details use cursors bound to the current content set; a changed input invalidates an old cursor explicitly. baseline-manifest.json is the bounded project snapshot captured when a change is created. The Git provider includes only tracked and non-ignored untracked files and represents each submodule/gitlink atomically; non-Git projects use a bounded physical-tree provider with before/after enumeration fences. Creation and a v1/v2 migration cutover require a complete baseline. A current v3 baseline cannot be rebuilt automatically from current files. Implementation scopes, specification baselines, current snapshots, verification reports, check receipts, checkpoint manifests, and archive preflights are hash-bound. An incomplete current snapshot never infers a deletion. When change details exceed the budget, scope-detail-overflow preserves a count and content hash for the remaining changes. These bindings let the Runtime determine whether evidence still matches current facts instead of trusting a statement that verification happened earlier. Git enumeration also reports git-selection-changed and git-enumeration-limit explicitly. The first requires a retry after the index settles and is never authorizable. For the second, first reduce or clean the project-owned set, or use a later product version that adjusts the budget. Baseline creation and a migration cutover require completeness and have no partial authorization. For a later current snapshot, git-enumeration-limit may use the ordinary partial protocol with the exact hash, a reason, and --confirmed only when recovery is impossible, the Runtime returns an authorizable scope bound to a count and content hash, and the user understands the unknown-tail risk. Neither condition may be bypassed through edited evidence. Physical-tree enumeration reports physical-selection-changed and physical-enumeration-limit explicitly. The first requires waiting for concurrent filesystem activity to settle; the second requires reducing the project tree or moving non-project content outside it. Neither can bind an unknown tail stably, so neither is authorizable as partial scope, including for a current snapshot. Continue with Safety and recovery, or see the matching commands in Native CLI.
Last modified on July 22, 2026