# Native artifact reference Read this file only when editing the brief or complete target specifications, or reviewing a Runtime-generated verification report. ## Editing boundaries Each active change directory contains only user-readable formal artifacts that can be synchronized through Git: ```text /comet/changes// comet-state.yaml brief.md children.yaml specs//spec.md verification.md ``` The Agent edits only the brief, complete target specifications, and a Supervisor Change's `children.yaml`. The Runtime manages `comet-state.yaml` and `verification.md`, generating the report after it first accepts a Verifier result. Local Runtime data always lives under the Git-ignored `.comet/runtime/native/`. Each active change keeps local state and logs under `changes//state.json` and `logs/`; project-level locks and short-lived transactions also live in this Runtime directory. Always let the Runtime create, migrate, and repair these machine files. ## Portable state and report `comet-state.yaml` is the only trusted workflow state for cross-device recovery. It records the current phase, status, version, acceptance Loop counters, verification result, Builder handoff, blockers, next action, check summaries, and compact history. Local processes, absolute paths, and full command output remain only in the local Runtime. The Runtime updates this file. `verification.md` is a readable report generated by the Runtime from the same YAML version. If the report is missing or behind, the Runtime rebuilds only the report; it does not rerun checks or a Verifier for that reason. Workflow progress always comes from YAML and cannot be advanced by editing the Markdown report. `.comet/config.yaml` selects the workflow and the artifact directory for changes. Synchronize this file when using a non-default artifact directory that must be resumed across devices. Keep every other `.comet/*` path local. ## Brief `brief.md` is Native's durable clarification artifact and uses these non-empty level-one headings: ```text # Outcome # Scope # Non-goals # Acceptance examples # Constraints and invariants # Decisions # Open questions # Verification expectations ``` Use these forms in Open questions only for real unresolved user questions: ```text - [blocking] - [blocking] Q1: - [blocking] CONFIRM: ``` As soon as a decision is confirmed, write it into Decisions and the complete target specifications, then remove the corresponding blocker. Formal artifacts record conclusions and reasons, not hidden model reasoning. When the user directly supplies a file, attachment, link, or local path as a requirements source, keep the only source coverage map in `brief.md` at `# Scope` under `## Source coverage`; the complete target Spec does not repeat that source table and instead fully expresses all currently active executable semantics. Acceptance criteria must be specific, observable, and non-duplicative. Use simple sequential IDs such as `A1`, `A2`, and `A3`. IDs map results only; they are not derived from content and do not identify files. On Shape confirmation, the Runtime saves the full acceptance text and its source. For every direct-source unit, the coverage map records the source location, `complete`/`partial`/`unavailable` read status, retained semantics, applicable Spec location and acceptance ID, `covered`/`needs-clarification`/`background`/`non-goal`/`superseded` coverage state, and a reason or replacement relationship. Every currently active executable unit must have both a Spec location and acceptance ID; background, non-goal, and superseded source units do not require a Spec location or acceptance ID. Acceptance criteria cover all currently active executable semantics from the original source; `partial`, `unavailable`, uncovered, or incompletely dual-mapped executable units remain blocked. A new Supervisor Change `children.yaml` uses `comet.native.children.v2`: `acceptance_index` stores the source and complete text for brief-derived parent acceptance IDs, each child still contains only `name`, `depends_on`, and `covers`, and `covers` must cover every ID in the index. Spec-derived acceptance remains in the Runtime's complete acceptance matrix; only repair phases add actual failed Spec IDs with their source and text to the index. Names must be unique, dependencies must exist and be acyclic. Historical `comet.native.children.v1` files remain accepted with their original complete acceptance coverage format; any change returns the Supervisor Change to Shape. ## Complete target specifications Each `specs//spec.md` describes the complete capability behavior after Archive, rather than only the difference from older text: - New capability: write the complete specification. - Existing capability: write the complete updated specification. - Removed capability: use CLI `spec remove`; do not only delete the file. If an archived canonical Spec changes in a way that conflicts with the current change, reread the latest Spec, rewrite the current change's complete target specification according to user intent, then execute the Runtime-provided rebase action. The Runtime continues to own Spec operation type and workflow state. ## Verification The report shows the outcome and reason for every acceptance item, redacted command previews and states for checks that actually ran, blockers, risks, and compact acceptance Loop history. Full command output remains in local logs. The Runtime generates the verification conclusion from YAML. Failed, blocked, not-run, or timed-out items retain their state. The final result is pass only when every acceptance item for the current candidate has a conclusion and every necessary check succeeds.