@rpamis/comet 0.4.0-beta.7 → 0.4.0-beta.9

package/assets/skills/comet-archive/SKILL.md

@@ -30,28 +30,30 @@ Proceed to Step 1 after verification passes. The script outputs specific failure
 
 If the `select` / `check` output is `BLOCKED` because `bound_branch` does not match the current branch, immediately pause under `comet/reference/decision-point.md` and let the user choose one option: switch back to the bound branch and rerun entry verification, or run `comet state rebind <change-name>` after the user explicitly confirms the current branch should take over this change, then rerun entry verification. Do not switch branches or rebind on your own.
 
-### 1. Final Archive Confirmation (Blocking Point)
+### 1. Final Archive and Delivery Confirmation (Blocking Point)
 
-After entry verification passes, **must follow the `comet/reference/decision-point.md` protocol to pause and wait for the user to confirm whether to archive immediately**. Must not run `comet archive "<change-name>"` before user confirmation.
+After entry verification passes, first read `comet state get <change-name> isolation`, then **follow the `comet/reference/decision-point.md` protocol to pause and wait for the user to confirm whether to archive and deliver remotely now**. Must not run `comet state transition <change-name> archive-confirm` or `comet archive "<change-name>"` before user confirmation.
 
 Before confirmation, show the user a brief summary:
 - Change name
 - Verification report path and result
 - Current branch/workspace and attribution summary for pre-existing dirty changes
 - Irreversible actions this archive will perform: merge main specs with OpenSpec delta semantics, annotate design doc / plan, and move the change to the archive directory
+- Remote delivery to perform after archive: push the current bound branch only, or push and then create a PR
 
 The user confirmation question must be presented as a single-select question with these options:
-- "Confirm archive" — record the final confirmation state, then run the archive script to complete spec merge and change movement
+- "Confirm archive and push now" — complete archive, create the only archive commit, and push the current bound branch
+- "Confirm archive, push now, and create a PR" — complete archive, create the only archive commit, push the current bound branch, and create a PR
 - "Needs adjustment or re-verification" — do not archive; run `comet state transition <change-name> archive-reopen` to return to `phase: verify`, then invoke `/comet-verify`. If verification confirms fixes are needed, follow `/comet-verify`'s verification-failure decision flow back to `/comet-build`
-- "Do not archive yet" — do not archive; keep the current `phase: archive` state and wait for the user to invoke `/comet-archive` again later
+- "Do not archive yet" — do not run `archive-confirm` or the archive command; keep the active change, `phase: archive`, and `branch_status: pending`, then wait for the user to invoke `/comet-archive` again later
 
-After the user selects "Confirm archive", immediately run:
+Only after the user selects one of the first two immediate-delivery choices, record that choice and immediately run:
 
 ```bash
 comet state transition <change-name> archive-confirm
 ```
 
-If the transition returns a non-zero exit code, report the error and stop. Only after the transition succeeds may Step 2 continue. After the user selects "Needs adjustment or re-verification", must first run the `archive-reopen` state transition; do not edit `.comet.yaml` manually.
+If the transition returns a non-zero exit code, report the error and stop. Only after the transition succeeds may Step 2 continue. After the user selects "Needs adjustment or re-verification", must first run the `archive-reopen` state transition; do not edit `.comet.yaml` manually. After the user selects "Do not archive yet", stop immediately; do not archive, commit, push, or set `branch_status` to `handled`.
 
 ### 2. Execute Archive
 
@@ -92,7 +94,16 @@ The archive script only moves files and merges the spec; it does not commit. Aft
 - The main spec content merged via delta semantics
 - Archive metadata annotations on the design doc / plan
 
-After archive, read `git status --short` and compare it with the pre-archive dirty-worktree attribution baseline. Stage only paths attributable to this change: the original active path, actual archive path printed by the command, main specs changed by this delta, and archive metadata on this Design Doc/Plan. Stop if any path cannot be attributed.
+First persist the confirmed delivery choice into archived state, then run the final archive guard:
+
+```bash
+comet state set <change-name> branch_status handled
+comet guard <change-name> archive
+```
+
+Here, `handled` means only that the user confirmed how to deliver this complete archive commit remotely. It does not mean that push or PR creation has succeeded. Stop without committing or performing remote operations if the state write or guard fails.
+
+After archive, read `git status --short` and compare it with the pre-archive dirty-worktree attribution baseline. Stage only paths attributable to this change: the original active path, actual archive path printed by the command, the archived `.comet.yaml` updated to `branch_status: handled`, main specs changed by this delta, and archive metadata on this Design Doc/Plan. Stop if any path cannot be attributed.
 
 Use explicit pathspecs, then inspect the staged diff. Never stage the whole repository or mix the user's pre-existing changes into the archive commit:
 
@@ -104,30 +115,28 @@ git commit -m "chore: archive <change-name>"
 
 Stop if the commit fails or the staged diff contains unrelated paths.
 
-### 5. Handle the Branch After the Archive Commit
+### 5. Deliver the Archive Commit and Complete
 
-After the archive commit succeeds, first read `comet state get <change-name> isolation` and route by isolation:
+After the archive commit succeeds, perform only the remote delivery method the user confirmed in Step 1:
 
-- `isolation !== current`: **immediately execute:** use the Skill tool to load Superpowers `finishing-a-development-branch`. This ordering ensures the final branch or PR contains the main-spec merge and archive metadata. If the skill is unavailable, stop and prompt the user to enable/install it; do not mark `branch_status` handled. After loading it, pause under `comet/reference/decision-point.md` and let the user choose: merge locally into the main branch, push and create a PR, or keep the current branch for later.
-- `isolation === current`: skip Superpowers `finishing-a-development-branch`. Pause under `comet/reference/decision-point.md` and let the user choose one option: push the current branch, or do not push yet and keep the local state.
+- "Confirm archive and push now": push the current bound branch once.
+- "Confirm archive, push now, and create a PR": push the current bound branch once, then create a PR using the current platform's available GitHub capability. The explicit Step 1 choice authorizes PR creation; do not substitute another branch disposition.
 
-Archive is already complete, so do not offer "discard work". Only after the selected operation succeeds, the user explicitly keeps the branch, or the user explicitly chooses not to push in `current` mode, run:
+If push fails, report the error and retain the current selection record; do not clear selection or report completion. Within the current task, retry only that same push. If PR creation fails, the branch already contains the complete archive commit; report the error and retain the current selection record. Within the current task, retry only PR creation. Do not automatically switch, delete, rebase, or rewrite branches after failure.
 
-```bash
-comet state set <change-name> branch_status handled
-comet guard <change-name> archive
-```
+Only after every remote delivery operation selected by the user succeeds may you run `comet state clear-selection` and report the Classic workflow complete.
 
-The archive guard must verify both archive completeness and `branch_status: handled`; a failure means the workflow is still incomplete.
+Archive no longer invokes Superpowers `finishing-a-development-branch`. Local merge, keeping a branch for later, or postponing push does not immediately produce final remote state, so the user must choose "Do not archive yet" in Step 1 rather than choosing it after archive.
 
 ## Exit Conditions
 
 - Archive script executed successfully (exit code 0)
 - Archive directory `openspec/changes/archive/YYYY-MM-DD-<change-name>/` exists
 - Archived `.comet.yaml` contains `archived: true`
-- Archive changes were committed with exact pathspecs
-- The user's branch decision completed and archived state has `branch_status: handled`
+- Archived `branch_status: handled` is included in the only archive commit
 - `comet guard <change-name> archive` passes
+- The only archive commit was pushed successfully using the delivery method confirmed before archive; if the user selected PR creation, the PR was created successfully
+- Current selection was cleared after remote delivery succeeded
 
 The archive script moves `openspec/changes/<name>/` to `openspec/changes/archive/YYYY-MM-DD-<name>/`.
 
@@ -139,4 +148,4 @@ Comet Classic workflow complete. To start new Classic work, invoke `/comet-class
 
 ## Context Compression Recovery
 
-Follow `comet/reference/context-recovery.md` with phase set to `archive`. If `archived: true` and archive directory exists, archival is complete — do not re-execute archive operations.
+Follow `comet/reference/context-recovery.md` with phase set to `archive`. If `archived: true` and the archive directory exists, do not re-execute archive operations. Retry the same push or PR creation only when the current task context explicitly records the remote delivery method selected in Step 1. This Skill does not promise automatic recovery after the user leaves the flow and changes branch topology independently.

package/assets/skills/comet-native/SKILL.md

@@ -11,7 +11,7 @@ Run the entire workflow inside this Skill. Do not load phase Skills or impose fi
 
 ## Clarification Protocol
 
-Read `native.clarification_mode` from `.comet/config.yaml`. Allowed values are `sequential` and `batch`; use `sequential` when the field is absent. This setting changes only how user questions are organized. It does not change Native phases, state, Guards, safety confirmations, or caller-defined stop points.
+Read `native.clarification_mode` from `.comet/config.yaml`. Allowed values are `sequential` and `batch`; use `sequential` when the field is absent. This setting determines how user questions are organized and which confirmation contract applies before leaving Shape. It does not change Native phases, the change schema, safety confirmations, or caller-defined stop points.
 
 First identify undefined branches that would change user-visible results. Words such as “normalize,” “intuitive,” “standard,” and “expected” are not product contracts. Only the user's words, a confirmed answer, or a published contract that clearly applies to the current behavior can close such a branch.
 
@@ -34,19 +34,25 @@ Before asking, inspect the current host's tool list. When the current tool list
 
 ### Sequential mode
 
-When a user decision remains:
+Treat the current goal as a decision tree of user-visible results. Run the following loop when entering Shape, after every user answer, and whenever relevant repository facts change:
 
-1. Record one `[blocking]` question in the brief.
-2. Ask only the most upstream question.
-3. Provide “Question / Recommendation / Impact,” then end the turn.
+1. First investigate repository, tool, and runtime facts required by the current branch. Do not ask the user for facts you can establish yourself.
+2. Traverse every reasonably reachable user-visible branch from the goal, including downstream edge cases, failure results, and defaults introduced by the current answer. Do not stop after finding the first workable interpretation, and do not silently close an unconfirmed branch with the recommendation.
+3. Maintain reviewable unresolved items and only the necessary dependency summary in the formal artifacts; do not persist hidden reasoning or a complete internal exploration. If several independent decisions remain, choose the most upstream one whose prerequisites are settled and leave the others for later rounds.
+4. Record only the current `- [blocking] <question>` in the brief. Ask only the most upstream question: each round asks exactly this one user decision, without packing independent decisions into a multi-select or several parallel clauses.
+5. Provide “Question / Recommendation / Impact,” using options, examples, or counterexamples that make the difference decidable, then end the turn. State the recommendation clearly, but never choose it for the user. Every downstream or dependent question surfaced by a new answer must retain all three parts; do not merely present a candidate collection and ask the user to edit it.
 
-When no user decision remains, continue directly without adding a generic final confirmation.
+After the user answers, immediately write the confirmed content into Decisions and the complete target specifications, remove the current blocking item, and traverse the entire decision tree again from the goal. If a target specification does not exist yet, create it in the same turn that handles the answer; updating only the brief and deferring the specification until final confirmation or Build is incomplete persistence. Treat the answer as a product constraint, not as approval of an implementation algorithm: one answer closes only the input-to-output result explicitly selected by that question. Do not silently settle independent empty-input, failure, or embedded-boundary examples merely because one possible implementation would handle them as a side effect. Branches introduced by the new answer must enter later rounds; ambiguous, partial, or unanswered content stays `[blocking]`.
+
+When no unresolved user decision remains, do not enter Build directly. Perform one completeness review and actively look for omitted or silently assumed user-visible branches. Then present a shared-understanding summary covering the outcome, scope, key decisions, acceptance criteria, and explicit non-goals, and record `- [blocking] CONFIRM: <confirmation>`. This review is also a traceability check: every product behavior in the summary and acceptance examples must trace to the user's words, a confirmed answer from an earlier round, or a published contract that clearly applies. “Consistent,” “intuitive,” “usual,” and repository convention are not confirmation. If a policy appears for the first time in the summary, the clarification loop is incomplete; restore it as a user question instead of deciding it through the final confirmation. Until the user confirms explicitly, do not modify project implementation, enter Build, or call `next`. If the user adds or rejects anything, update the formal artifacts and run the loop again. After explicit confirmation, remove the blocking item, record the confirmation, and advance with `--confirmed`.
 
 ### Batch mode
 
-Organize unresolved user decisions by their prerequisite relationships. Maintain only reviewable open items, dependency summaries, and formal artifacts; do not persist hidden reasoning or a complete internal exploration.
+Treat the current goal as a decision tree of user-visible results and organize unresolved user decisions by their prerequisite relationships. Maintain only reviewable open items, dependency summaries, and formal artifacts; do not persist hidden reasoning or a complete internal exploration.
+
+For each round, compute the ready question set. Every question in the set must have all prerequisite decisions settled, all required environment facts established, and an answer that does not depend on another question in the same round. These questions form the current frontier. Defer questions that depend on an unresolved decision or a fact still under investigation.
 
-For each round, compute the ready question set. Every question in the set must have all prerequisite decisions settled, all required environment facts established, and an answer that does not depend on another question in the same round. Defer questions that depend on an unresolved decision or a fact still under investigation.
+When a candidate branch needs an environment fact, investigating it remains your responsibility. When the host supports sub-agents or other parallel work, you must start independent fact investigations in parallel. A fact under investigation defers only its downstream questions; other frontier questions must still be asked in the current round. When the host does not support parallel work, investigate directly. Parallel capability is not a workflow prerequisite, and facts available from the environment must never be delegated to the user.
 
 For the ready question set:
 
@@ -68,7 +74,7 @@ Use this format:
 
 After the user answers, write confirmed content into Decisions and the complete target specifications, then remove the corresponding `[blocking]` items. Keep unanswered or ambiguous items `[blocking]`; never fill them from the recommendation. Recompute the ready question set from the new answers and continue round by round as new branches become available.
 
-When the ready question set is empty, all relevant facts are established, and every identified user decision is resolved, perform one completeness review. Recheck that no user-visible branch remains unaddressed or silently assumed. Present a shared-understanding summary that covers the outcome, scope, key decisions, acceptance criteria, and explicit non-goals, then persist the final confirmation as `- [blocking] CONFIRM: <confirmation>` in the brief. Until the user confirms explicitly, do not enter Build or call `next`. If the user adds or rejects anything, update the affected branches and continue with another round. After explicit confirmation, remove the blocking item, record the confirmation, and follow the normal transition.
+When the ready question set is empty, all relevant facts are established, and every identified user decision is resolved, perform one completeness review. Recheck that no user-visible branch remains unaddressed or silently assumed. Present a shared-understanding summary that covers the outcome, scope, key decisions, acceptance criteria, and explicit non-goals, then persist the final confirmation as `- [blocking] CONFIRM: <confirmation>` in the brief. Until the user confirms explicitly, do not enter Build or call `next`. If the user adds or rejects anything, update the affected branches and continue with another round. After explicit confirmation, remove the blocking item, record the confirmation, and advance with `--confirmed`.
 
 For text “normalization,” for example, cover case folding, surrounding punctuation, preservation of internal punctuation or apostrophes, and use counterexamples to show how each choice changes output.
 
@@ -132,9 +138,11 @@ Rewrite important nouns or actions as distinguishing “input → output” or
 
 For text or token behavior, normally inspect case, surrounding and internal punctuation, whitespace, Unicode, empty input, duplicates, ordering, and tied results. For CLI or API behavior, inspect defaults and error results. Do not invent ambiguity merely to cover a checklist.
 
+For parsing, counting, tokenization, or boundary detection, the completeness review also uses counterexamples for empty and whitespace-only input, no delimiter, consecutive or mixed delimiters, and delimiter-like characters embedded in valid content, such as periods in abbreviations, decimal points in numbers, or escaped separators. Ask only about examples inside the stated scope; explicit non-goals close the rest. If two counterexamples can independently choose different results, they are not one user decision. A contract limited to “non-empty input” cannot justify an empty-input policy.
+
 Only user-provided information, explicit non-goals, confirmed decisions, or a clear published contract for the current capability may close a branch. When blocked, follow the Clarification Protocol to compute and ask either one question or the ready question set for the configured mode. Do not call `next` or modify project implementation before the answer.
 
-When no unresolved branch remains and the brief, complete target specifications, repository facts, and project rules are sufficient to implement and accept the work, Sequential mode continues directly. Batch mode first completes its final shared-understanding confirmation.
+When no unresolved branch remains and the brief, complete target specifications, repository facts, and project rules are sufficient to implement and accept the work, both modes first complete the final shared-understanding confirmation. Sequential still asks only one user decision per round; Batch still asks the ready question set together.
 
 ## Progression Contract
 
@@ -146,7 +154,7 @@ After `next: auto` with disposition `continue`, reread the returned phase and re
 
 For `await-user`, `blocked`, or `next: manual`, first resolve the returned disk facts and blocking findings. Ask only when the missing input is genuinely a user decision.
 
-In Batch mode, unanswered questions and the final shared-understanding confirmation remain `[blocking]`. They are normal stop points for user input. They do not change the continuation contract and cannot be bypassed by automatic progression.
+The current Sequential question and final shared-understanding confirmation, as well as unanswered Batch questions and its final shared-understanding confirmation, remain `[blocking]`. They are normal stop points for user input and cannot be bypassed by automatic progression.
 
 `workspace-root-changed` and `workspace-inspection-unavailable` are read-only advisories and do not block progress or archive by themselves. Unknown workspace findings, confirmed conflicts, stale evidence, and repair stops must be resolved.
 
@@ -168,16 +176,16 @@ Shape is complete only when the brief, complete target specifications, repositor
 When ready, run:
 
 ```text
-comet native next <change-name> --summary <summary>
+comet native next <change-name> --summary <summary> [--confirmed]
 ```
 
-Append `--confirmed` only when this turn recorded the user's answer to an existing blocking question; Batch mode must first obtain the final shared-understanding confirmation. The Runtime binds approval to the current brief/spec contract hash. If the contract changes during Build, obtain user confirmation for the current contract and retry with the command returned by status. Do not edit `approval` or `approved_contract_hash` manually.
+Append `--confirmed` only when this turn recorded the user's answer to an existing blocking question; both Sequential and Batch modes must first obtain the final shared-understanding confirmation. The Runtime binds approval to the current brief/spec contract hash. If the contract changes during Build, obtain user confirmation for the current contract and retry with the command returned by status. Do not edit `approval` or `approved_contract_hash` manually.
 
 ## Build
 
 Choose the simplest reliable implementation that satisfies the brief and proposed specifications. Decide implementation details, whether to save a plan, test granularity, debugging method, and review depth according to risk.
 
-Do not create extra documents merely to satisfy the workflow. If requirements or specifications drift, update the Native artifacts first. If a new user decision appears, mark it `[blocking]` and follow the configured clarification protocol. Batch mode must recompute the ready question set and obtain a final confirmation of the updated shared understanding before implementation continues.
+Do not create extra documents merely to satisfy the workflow. If requirements or specifications drift, update the Native artifacts first. If a new user decision appears, mark it `[blocking]` and follow the configured clarification protocol. Sequential mode must traverse the decision tree again, while Batch mode must recompute the ready question set; both modes must obtain final confirmation of the updated shared understanding before implementation continues.
 
 When implementation is complete, provide real project artifacts. If no code changed, provide a concrete reason. Then run:
 
@@ -205,7 +213,7 @@ Never edit snapshots or evidence, guess unenumerated paths, or present partial s
 
 Run verification appropriate to the Acceptance examples, complete target specifications, and risk. Record actual commands, results, skipped checks, specification consistency, known limitations, and the conclusion. Never record an unrun check as passed.
 
-In the fixed acceptance evidence block of `verification.md`, use every Runtime-provided `acceptance_id`. Each item must contain either project-relative evidence refs or an honest `skipped_reason`. See the artifact reference for the exact format.
+In the fixed acceptance evidence block of `verification.md`, use every Runtime-provided `acceptance_id`. Each item must contain either project-relative evidence refs or an honest `skipped_reason`. Serialize the entries with `comet native evidence format` and paste the result; never hand-format this JSON — a hand-typed block can almost never match the canonical serialization byte-for-byte. See the artifact reference for the exact format.
 
 When you need reproducible text-hygiene evidence, run the built-in read-only check:
 

package/assets/skills/comet-native/reference/artifacts.md

@@ -53,9 +53,18 @@ native:
   artifact_root: docs
   language: en
   clarification_mode: sequential
+  snapshot:
+    include:
+      - '**/*'
+    exclude: []
+    max_files: 10000
+    max_total_bytes: 268435456
+    max_duration_ms: 60000
 ```
 
-`clarification_mode` controls only how Native organizes user decisions. `sequential` asks one most-upstream question per round, while `batch` asks every question whose prerequisites are settled. The default is `sequential` when the field is absent. It does not change the change schema, lifecycle, Guards, safety confirmations, or caller-defined stop points.
+`clarification_mode` controls how Native organizes user decisions and which confirmation contract applies before leaving Shape. `sequential` asks one most-upstream question per round, while `batch` asks every question whose prerequisites are settled. The default is `sequential` when the field is absent. It does not change the change schema, lifecycle, safety confirmations, or caller-defined stop points.
+
+`snapshot` defines the explicit content-snapshot scope and bounded resource budget. `include` and `exclude` use project-relative `/` paths with `*`, `**`, and `?`; the normalized policy and its hash are persisted in each new change baseline. Later current snapshots keep using the baseline policy, so changing configuration mid-change cannot hide implementation changes. `max_files`, `max_total_bytes`, and `max_duration_ms` bound capture work and can be raised for larger repositories. File content uses streaming SHA-256, does not depend on Git object hashes, and has no separate 5 MiB per-file limit.
 
 During an artifact-root move, the runtime-managed `pending_root_move` field is present. Ordinary write commands must stop while it exists; never choose the old or new root yourself.
 
@@ -103,7 +112,7 @@ run_id: null
 
 Do not edit Runtime-managed fields directly. The Runtime owns `phase`, `revision`, `approval`, `approved_contract_hash`, `spec_changes`, operation, `base_hash`, all three evidence refs, `run_id`, and `archived`.
 
-`approved_contract_hash` binds approval to the brief/spec contract from that moment. Later contract drift requires fresh user confirmation. To change requirements, edit only the brief and `specs/<capability>/spec.md`; remove a capability with `comet native spec remove`, then let the command validate and advance state.
+`approval: confirmed` means the Runtime recorded explicit user confirmation of the current shared understanding. `implicit` exists only for compatibility with older changes and does not prove confirmation; an older `implicit` change in Build must be confirmed before Verify. `approved_contract_hash` binds approval to the brief/spec contract from that moment, and later contract drift also requires fresh user confirmation. To change requirements, edit only the brief and `specs/<capability>/spec.md`; remove a capability with `comet native spec remove`, then let the command validate and advance state.
 
 ## Brief
 
@@ -122,7 +131,7 @@ Do not edit Runtime-managed fields directly. The Runtime owns `phase`, `revision
 
 The first four sections require substantive content. Prefix unresolved implementation-blocking questions under Open questions with `- [blocking]`; ordinary notes do not block Shape.
 
-In Sequential mode, Open questions holds one most-upstream blocking question at a time. In Batch mode, persist the current ready question set as `- [blocking] Q1: <question>`, `- [blocking] Q2: <question>`, and so on. This unordered-list prefix is the fixed form recognized by the Runtime and must not be replaced with a Markdown ordered list. Unanswered items remain `[blocking]`. After the round is resolved and the completeness review passes, Batch mode persists the shared-understanding confirmation as `- [blocking] CONFIRM: <confirmation>`. Build cannot begin before explicit confirmation.
+In Sequential mode, Open questions holds one most-upstream blocking question at a time. In Batch mode, persist the current ready question set as `- [blocking] Q1: <question>`, `- [blocking] Q2: <question>`, and so on. This unordered-list prefix is the fixed form recognized by the Runtime and must not be replaced with a Markdown ordered list. Unanswered items remain `[blocking]`. After all questions for the current mode are resolved and the completeness review passes, both modes persist the shared-understanding confirmation as `- [blocking] CONFIRM: <confirmation>`. Build cannot begin before explicit confirmation.
 
 Question numbers apply only to the current clarification round. Write confirmed answers into Decisions and the complete target specifications. Do not add a decision-tree artifact or persist hidden reasoning in the brief.
 
@@ -155,7 +164,7 @@ Persist reviewable facts, not hidden reasoning. Put unrun checks under Skipped c
 
 The runtime derives at most 1024 acceptance items from the brief and proposed specifications. It rejects overflow rather than first creating an unbounded list and truncating it. Each `acceptancePage` contains at most 16 items. Text is capped at 512 UTF-8 bytes, context at four entries of at most 256 bytes each, and a full page at 32 KiB. Text or context truncation is marked explicitly, while acceptance IDs are never lost to paging or truncation. Cursors bind to the current acceptance hash and fail after the contract changes.
 
-`# Acceptance evidence` must contain exactly one fixed machine block. The runtime derives IDs from the brief/specifications and returns them through Build or `status --details`; never calculate or rewrite them yourself:
+`# Acceptance evidence` must contain exactly one fixed machine block. The runtime derives IDs from the brief/specifications and returns them through Build or `status --details`; never calculate or rewrite them yourself. Generate this block with `comet native evidence format` and paste the result; never hand-format the JSON — a hand-typed block can almost never match the canonical serialization byte-for-byte and will be rejected with a "canonical serialization" error:
 
 ```text
 <!-- comet-native:acceptance-evidence:start -->
@@ -177,6 +186,12 @@ The runtime derives at most 1024 acceptance items from the brief and proposed sp
 
 The array is sorted by `acceptance_id`, and every `evidence_refs` list is sorted. Each item chooses exactly one path: at least one project-relative evidence ref, or an empty array plus a non-empty `skipped_reason`. Never provide both evidence and a skip reason, and never reference an absolute path, a path outside Native, `.git`, or `.env*`.
 
+```text
+comet native evidence format [--entries <path>]
+```
+
+Pass the entry array above (without the markers) as JSON on stdin, or point `--entries <path>` at a JSON file. The command's output already includes the start/end markers plus the canonical order and indentation, so paste it as-is into the `# Acceptance evidence` section of verification.md.
+
 ## Content-addressed evidence
 
 - `baseline-manifest.json`: a bounded project snapshot captured when the change is created. It records only project-relative paths, sizes, hashes, the capture provider, and omission facts, never file contents. The Git provider includes tracked and non-ignored untracked files and treats each submodule/gitlink as an atomic entry; non-Git projects use a bounded physical-tree provider with before/after enumeration fences. If project-owned entries are still omitted, `new` fails and removes the unfinished change.

package/assets/skills/comet-native/reference/commands.md

@@ -62,6 +62,12 @@ comet native check <change-name>
 
 `checkpoint` stores only an in-phase summary, next action, and content-addressed artifact manifest. It uses revision/CAS to prevent overwrites and does not change the phase. `check` is available only in Verify after an implementation scope exists. It runs Comet's built-in bounded, read-only text scan. It does not invoke Git, a shell, project scripts, external Skills, or any external process; it accepts no arbitrary command, path, environment, or timeout options and does not modify project files, the change, Run, or trajectory. Results, issue counts, and scope freshness are written to an independent content-addressed receipt. A check that finds issues or becomes stale exits with 1, but still writes the receipt.
 
+```text
+comet native evidence format [--entries <path>]
+```
+
+Before writing the `# Acceptance evidence` machine block in verification.md, use this command to serialize the entry array into the canonical Markdown text and paste that, rather than hand-formatting the JSON yourself. It reads entries JSON from stdin by default, or from a file with `--entries <path>`; the output already includes the start/end markers plus the fixed order and indentation, so pasting it as-is satisfies `next --result`'s canonical-serialization check.
+
 ## Phase progression
 
 ```text
@@ -81,8 +87,8 @@ comet native archive <change-name> --dry-run
 comet native archive <change-name> --expect-preflight <sha256>
 ```
 
-- Shape: advance after the brief and proposed specifications pass; add `--confirmed` only when this turn contains a decision the user just confirmed. On successful entry to Build, the Runtime binds approval to the current contract hash.
-- Build: recheck the brief and proposed specifications; provide at least one real project artifact or use `--no-code-reason`. If the contract changed after approval, status/next requires the user to reconfirm the current contract; pass `--confirmed` only after obtaining that confirmation. If complete scope cannot be proven, the first call returns a scope hash and bounded unattributed details without advancing; changes beyond the detail budget are represented by a `scope-detail-overflow` count and content hash. Retry only after the user accepts the specific risk, with the exact `--allow-partial-scope`, a reason, and `--confirmed`.
+- Shape: advance after the brief and proposed specifications pass. Both Sequential and Batch must obtain the final shared-understanding confirmation and pass `--confirmed`. On successful entry to Build, the Runtime binds confirmed approval to the current contract hash.
+- Build: recheck the brief and proposed specifications; provide at least one real project artifact or use `--no-code-reason`. An older change that still has `approval: implicit` must first confirm the current shared understanding. If the contract changed after approval, status/next requires the user to reconfirm the current contract. In either case, pass `--confirmed` only after obtaining confirmation. If complete scope cannot be proven, the first call returns a scope hash and bounded unattributed details without advancing; changes beyond the detail budget are represented by a `scope-detail-overflow` count and content hash. Retry only after the user accepts the specific risk, with the exact `--allow-partial-scope`, a reason, and `--confirmed`.
 - Verify: provide both `--result` and a complete `--report`. An optional `--receipt` must be fresh for the current change, revision, contract, and implementation scope. A failure returns to Build and may use failure categories and check IDs to form a no-progress signature; a pass enters Archive.
 - Repair: the third identical failure returns a manual stop. A genuine scope change on an ordinary Build `next` closes the old repair episode and continues. With unchanged scope, only one override is allowed, using the exact signature returned by status plus a non-empty summary. Neither a semantic repair budget nor an exhausted override can be bypassed; the generic Run iteration is only an event sequence number, not a permanent stop condition for a long-lived change.
 - Archive: only `archive` completes this phase; `next` cannot substitute for it. First run `--dry-run`, then pass the returned `preflightHash` unchanged to `--expect-preflight`. The runtime recomputes it under the mutation lock before committing.

package/assets/skills/comet-native/reference/recovery.md

@@ -19,7 +19,7 @@ When Shape or Build contains `[blocking]` items, recover the current open decisi
 
 Continue investigating facts available from the repository, tools, or runtime environment yourself. Independent facts may be investigated in parallel when the host supports it, but recovery must not depend on any optional parallel capabilities. A fact still under investigation delays only the questions that depend on it.
 
-In Batch mode, unanswered questions remain `[blocking]`. After all questions are resolved, recover or establish the final shared-understanding confirmation. Remove that blocking item and enter Build only after explicit user confirmation. This process adds no phase, change-state field, or separate decision-tree file.
+Sequential mode recovers the current most-upstream question, while Batch mode recovers every unanswered numbered question; both remain `[blocking]`. After all questions are resolved, recover or establish the final shared-understanding confirmation. Remove that blocking item and enter Build only after explicit user confirmation. This process adds no phase, change-state field, or separate decision-tree file.
 
 Before interrupting a long task within the same phase, write a checkpoint when useful: