> ## 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 artifacts and state > Understand the roles of .comet/config.yaml, the brief, complete target specs, comet-state.yaml, evidence, and archives. 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: ```text theme={null} / .comet/ config.yaml current-change.json docs/comet/ specs/ changes/ / brief.md comet-state.yaml specs//spec.md verification.md runtime/ baseline-manifest.json run-state.json trajectory.jsonl checkpoints/ evidence/ snapshots/ scopes/ allowances/ verifications/ check-receipts/ archive/ YYYY-MM-DD-/ runtime/ ``` `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](/en/native/configuration) for the complete schema, examples, and safe update paths; the fields below directly affect Native artifacts: | Field | Purpose | | --------------------------- | ---------------------------------------------------------------------- | | `schema` | Configuration format, currently `comet.project.v1` | | `default_workflow` | Whether `/comet` enters `native` or `classic` by default | | `workflows` | Enables Native, Classic, or both | | `ambient_resume` | Allows ordinary requests to trigger the read-only Ambient Resume probe | | `native.artifact_root` | Project-relative root for Native's `comet/` artifacts | | `native.language` | Default document language for new Native changes | | `native.clarification_mode` | Ask one question per round or all currently answerable questions | 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//specs//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 `. ## 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](/en/native/safety-and-recovery), or see the matching commands in [Native CLI](/en/cli/native).