Comet Archive

Comet Phase 5: Archive

After entry returns layout, follow comet-classic/reference/classic-layout.md to bind each logical root to its directory. Do not reload the protocol if it is already in context. Use the adapter for OpenSpec CLI calls and the bound <classic-*> roots for paths; do not run an extra root show first.

Prerequisites

• Verification passed; Phase 4 is complete.
• Archive or the selected delivery action is unfinished. Recovery does not require branch_status to remain pending.
• <classic-change-dir>/.comet.yaml records verify_result: pass.

Steps

0. Set the output language

Use configuration.language from this invocation's entry result for the archive summary and completion message. Do not query the language separately.

0b. Validate entry state

Use the supported comet CLI in comet-classic/reference/scripts.md for these checks. When resuming from any entry, first follow comet-classic/reference/context-recovery.md:

comet state select <change-name>
comet state check <name> archive --json

When the previous phase's guard already returned this phase's state, continue from that state and agent.continuation without repeating select/check; run the entry checks above only when resuming, after workspace changes, or after external state changes. Continue from returned layout, configuration, nextAction, and the delivery summary. After context loss, read details according to context-recovery.md. If authorization is still valid and the delivery target is unchanged, continue only unfinished actions without asking again. Handle the specific cause on failure.

If select/check returns BLOCKED — or a branch-binding ERROR — because bound_branch differs from the current branch, pause under comet-classic/reference/decision-point.md. Offer a single choice: return to the bound branch and rerun entry checks, or, after the user explicitly confirms that the current branch should take over this change, run comet state rebind <change-name> and rerun entry checks. Do not switch or rebind branches yourself.

1. Ask the user to confirm archive and delivery

Read configuration.isolation and delivery from entry. If valid authorization is absent or the delivery target changed, pause under decision-point.md and ask the user to confirm archive and delivery. If authorization exists, let Runtime verify actual Git state and delivery progress, then follow nextAction. Do not infer archive, push, or PR authorization solely from branch_status: handled. Do not run archive-confirm or archive before authorization.

Before asking, show a short summary:

• Change name.
• Verification report path and conclusion.
• Current branch/workspace and which work owns each uncommitted change.
• The irreversible archive actions: merge delta changes into main spec, annotate the Design Doc/plan, and move the change to the archive directory.
• How the archive commit will be handled: keep it local, push the bound branch, or push and create a PR.

Present a single-choice question containing every option below. Use this table in text fallback mode. With structured questions, use “Method” as the short label and “Effect” as its description; do not shorten options until their meaning is unclear.

Only after the user chooses A, B, or C, save the choice as JSON through Runtime, then confirm archive:

comet state delivery <change-name> --file <json-path>
comet state transition <change-name> archive-confirm

JSON contains action (A=local, B=push, C=pr), targetBranch, and optional remote, commit, and prUrl. Initially record only confirmed actions and targets. Do not fabricate unknown commit/prUrl values; add them after the operations actually complete.

targetBranch is the bound branch receiving the archive commit, not the PR base branch. Use an explicit existing PR-base configuration; clarify ambiguity first. With multiple remotes, establish the destination rather than guessing. For example, after the user confirms push:

{
  "action": "push",
  "targetBranch": "<confirmed-bound-branch>",
  "remote": "<confirmed-remote>"
}

Save JSON using file tools and pass it to delivery --file. Store the input file outside the change directory (for example delivery-input.json at the repository root) and delete it after use; never place it inside the change directory, and especially never at <change-dir>/.comet/delivery.json — that is the Runtime's delivery record. Runtime recognizes case variants and filesystem aliases of the same path and reports the input collision directly. The input contains only action, targetBranch, and optional remote, commit, and prUrl; schemaVersion and other Runtime record fields must not appear in the input. Once the archive commit is confirmed, add "commit": "<actual-archive-commit-sha>" to the same complete record. For action pr, add the actual prUrl after PR creation. The commit is stored by Runtime in a Git-ignored delivery receipt, and the tracked delivery.json inside the change directory never carries a commit. After the archive commit, the change directory must stay byte-identical to that commit: do not add, modify, or delete files inside it, or the integrity check fails. Local needs only action:local and the confirmed targetBranch; remote is not required.

Plain comet state delivery <change-name> reads saved records only, and the entry summary does not access the network. Explicitly run the following when resuming remote delivery, resolving an uncertain call result, or preparing to announce completion:

comet state delivery <change-name> --verify

The result is {delivery, verification}. delivery contains saved choices and progress; verification contains Runtime's read-only checks of actual Git, remote branches, and PRs. A delivery record or successful ordinary entry check alone does not prove remote delivery. Handle the result as follows:

• Confirmed not-yet-delivered, such as no first push or a completed push with no PR: if authorization and target remain valid, perform the missing action and check again with --verify. Do not stop solely because of notVerified/needsVerification.
• unavailable, meaning network, permission, or service failures prevent determining the result, or a target conflict/uncertain outcome: keep the record and stop. Restore read-only verification first; do not blindly retry push or create duplicate PRs.

Stop if either the delivery write or transition fails. Proceed to Step 2 only after both succeed. For D, run archive-reopen; the old delivery authorization must be invalidated, and obtain new confirmation after verification. For E, stop without archiving, committing, pushing, or setting handled.

2. Run archive

comet archive "<change-name>"

The script automatically:

1. Validates entry state: phase=archive, verify_result=pass, archive_confirmation=confirmed, archived=false.
2. Updates Design Doc metadata before archive: archived-with, status.
3. Updates Plan metadata before archive: archived-with.
4. Calls OpenSpec archive to merge deltas into main spec and move the change to archive.
5. Checks that main spec has no delta-only section headings.
6. Updates archived state in the actual OpenSpec archive directory and reconciles pending recovery metadata so interrupted work can resume.

Report and stop on a nonzero exit code. A zero exit code means archive completed.

The script's X/Y steps succeeded counts actual steps, not duplicate counts for delta syncing or document annotations.

It applies OpenSpec ADDED/MODIFIED/REMOVED/RENAMED delta semantics and verifies that main spec has no remaining delta-only section headings afterwards.

Use --dry-run to preview without executing.