Skip to main content
After all acceptance items pass and the change reaches the Archive-ready state, you need to decide how this archive is delivered. Whether this decision is needed at all, and which options you see, depends on the workspace chosen when you created the change. Before you choose, Comet shows the current branch, the target branch, the directories, and the actual impact of each option; you can confirm right away or defer. When verification results require your explicit acceptance, Comet can show delivery options at the same time. You can reply once, such as “Accept the result and keep the workspace,” or choose a local merge, push, or PR. The Agent carries that choice into the archive command without asking again. New delivery operations or changes to the actual scope still require confirmation.

​
Run one preflight before archiving

At Archive-ready, the Runtime returns a preflight or a confirmed archive command in continuation. The chosen delivery method is included as --finish. A confirmed archive can perform preflight and transaction checks in one command; run archive --dry-run first when you need to inspect custom commit messages. The preflight checks the archive contents, current workspace, and generated files together. If it cannot continue, it lists the blockers, affected paths, and the next confirmation command. --dry-run does not archive, commit, merge, or push. Run the single confirmation command returned by the Runtime only after the preflight says it can continue.

​
Project commit conventions

Comet’s built-in Git commits run project hooks. The Agent checks repository commit-message conventions first. Use --commit-message for the archive commit and, for a local merge, --merge-message for the merge commit. Both support Unicode and multiline text. Previews show the actual messages, and confirmation and retries preserve them. See Native command overview.

​
Delivery options and workspace type

When you create a change, you can keep using the current directory or let Comet create a branch or worktree. When the change reaches Archive, the delivery method depends on that earlier choice:
  • current workspace: the change completes directly in the current branch and directory, so no delivery method needs to be chosen when archiving. Comet shows the current branch and directory and explains that archiving performs no merge, push, or PR; after you confirm, it completes the archive directly.
  • branch / worktree isolation: the change runs in its own branch and directory. After archiving, you decide whether to merge into the target branch, push to the remote, or open a PR. Comet shows the actual change branch, the target branch, and the directories, and presents the five mutually exclusive options below as a single decision.

​
The five delivery options

When you choose A–D, Comet runs the archive command with the corresponding argument (--finish keep|merge|push|pull-request); choosing E stops here. The whole decision path:

​
Git state after each option

All of A–D complete the archive and create an archive commit on the change branch. They differ in what happens after that commit:
  • A - Keep the workspace only: the change branch gains an archive commit, the target branch is unchanged, and the branch and directory stay as they are. This archive does not remove a retained worktree.
  • B - Merge locally: the archive commit is merged from the change branch into the target branch locally; the remote is unaffected.
  • C - Archive and push: the archive commit is pushed to the remote together with the change branch; the target branch is not merged and no PR is opened.
  • D - Push and create a PR: after pushing the change branch, a PR is opened against the target branch as its base, and the merge from there goes through the PR flow.
  • E - Defer the archive: neither the archive nor the delivery runs, and nothing changes on the Git side.
A worktree retained through option A is not removed by this archive. For B, C, and D, after the archive completes, Comet offers to clean up the worktree when it has no uncommitted changes, and waits for your confirmation.

​
Final confirmation before archiving

Whether archiving needs one extra explicit decision is controlled by native.archive_confirmation, which defaults to automatic:
  • automatic: after the final Verify passes, the Runtime may continue and complete the archive. Automatic archiving does not decide the delivery method for you — when you use a branch or a worktree, you still pick one of A–E.
  • required: after the final Verify passes, the Runtime stops at the final Archive candidate and waits for an explicit decision about this one archive. Intermediate repair rounds do not trigger this confirmation; choosing not to archive yet also keeps the current active change.
See Native configuration · Archive confirmation. When required is active, Comet stops at this step and waits for your explicit consent to this archive; only after you confirm does it run the real archive command with --confirmed. --dry-run only previews the archive result and does not write a confirmation. --confirmed only comes into play when the change is genuinely stopped at an Archive-ready state waiting for final confirmation; intermediate repair rounds never ask for it. If the requirements or acceptance criteria are modified while you wait, the change first returns to Shape, and the previous verification results and archive approval become invalid.

​
How to continue after deferring the archive

After you choose E, the change stays active and the workspace together with all passed results is kept. The next time you ask the Agent to continue this change, the Runtime reads back the recorded state and the next step, returns the change to Archive-ready, and presents the same decision again. If you modify the visible requirements or acceptance criteria while waiting, the change first returns to Shape, gets confirmed again, and obtains new verification results before it comes back to Archive. The old verification results and archive approval are not reused.

​
Handling archive interruptions and parallel changes

If an Archive transaction is interrupted midway, the Runtime keeps the transaction records and the executable state and continues from the steps already completed. For the specific recovery rules, see Recovery playbook. If a project hook rejects a commit or merge message, the sealed archive and unfinished Git step remain recorded separately. The Agent corrects the message for the unfinished step and resumes the same transaction, without recreating completed commits or publishing Specs again. Recovery uses the selected delivery method and asks you only when a new decision is needed. Status continues to show delivery as unfinished until recovery completes. When multiple active changes declare the same Spec, Archive first asks you to determine the archiving order before it reaches this delivery choice. For the ordering rules, see Multi-change parallelism and conflict control. Continue reading: Native products and state, Multi-change parallelism and conflict control, and Recovery playbook.
Last modified on October 3, 2026