| name | specpowers-archive |
| description | Use as stage 8 of specpowers-flow — verify all prior gates passed, then archive the completed change into the living specs (real openspec archive if present, else conservative guided merge). |
When to invoke
Invoke specpowers-archive after specpowers-build reports that both execute-plan and
verify-compliance have passed. The orchestrator hands off here; do not invoke this skill
directly unless resuming a workflow that has already passed all seven prior gates.
Step 1 — Enforce archive prerequisites
Read references/archive-checklist.md before doing anything else. Work through every item in
§1 of that file in order:
Gate-evidence freshness (all seven prior stages). For each stage from brainstorm through
verify-compliance, locate the evidence record at
openspec/changes/<change>/.specpowers/gates/<stage>.yaml. Confirm the record exists, its
result is passed, and every artifact digest stored in it still matches its file on disk
(recompute sha256sum for each path). If any record is absent, stale, or shows a changed
digest, that gate is invalidated — along with all gates that follow it. Stop, name the failing
gate and the changed file, and route back to that stage. Do not proceed to any later step.
Compliance implementation evidence — recompute before accepting the gate. Using the
base_ref recorded in verify-compliance.yaml (never re-resolve; use the stored value), derive
merge_base_oid = git merge-base "$base_ref" HEAD and recompute: every coverage-area file
digest, the commit range (merge_base_oid..HEAD), the HEAD tree OID
(git rev-parse HEAD^{tree}), the dirty-worktree diff hash
(git diff HEAD | sha256sum | awk '{print $1}'), and the untracked-relevant file list
(git ls-files --others --exclude-standard scoped to each Implementation-Area path). Compare
each computed value against the stored implementation block. Any divergence means the
implementation changed after compliance ran — block archive and route back to
verify-compliance. See references/stage-protocol.md §"Gate-evidence binding" for the
evidence record shape and the full base-ref resolution rules.
Block archive and surface an explicit error if either of these conditions holds:
- The computed change set is empty (no commits in the range, empty dirty diff, empty untracked
list) while at least one implementation task in
tasks.md is marked complete. An empty change
set against a complete task list signals that compliance was gathered against the wrong base or
the work was never committed.
untracked_relevant lists any file not present in the stored record. Untracked files under an
Implementation-Area path represent uncommitted work; require the user to commit or explicitly
ignore them before proceeding.
Behavioral-change spec-delta assertion. For any change that alters observable behavior —
new features, changed business rules, modified error handling, altered API contracts, or modified
side effects — at least one spec delta file must exist under
openspec/changes/<change>/specs/ and the harden-spec gate must have validated it. There is
no no-spec-delta escape for behavioral changes; that exemption is only valid for independently
reviewed, genuinely non-behavioral changes (documentation, comments, formatting, whitespace).
If the delta is missing for a behavioral change, block archive and route back to generate-spec.
User confirmation when required. Present the archive summary (Step 3 below) before
modifying any file when: the tier is full, the change touched any non-overridable escalation
surface (authentication/authorization, data migration, schema changes, destructive/irreversible
state transitions, tenant/security boundaries, billing), or any compliance finding was accepted
with a minor verdict rather than a clean approve. Wait for explicit approval before
continuing.
If any prerequisite is unmet, stop. Do not proceed to Step 2. Identify the first failing item
and route back.
Step 2 — Archive
Real openspec archive (preferred). Check with command -v openspec. If present, run
openspec archive according to the project's configuration and capture the full output. Record
the command invoked, its exit code, and its output in the archive summary.
Conservative fallback (when openspec is absent). Apply the full fallback procedure
defined in §2 of references/archive-checklist.md. The steps in order:
-
Preflight diff — for every spec delta in openspec/changes/<change>/specs/, produce a
unified diff against the corresponding living spec in openspec/specs/. Display each diff
with a clear header showing the capability name and file paths. Identify and explicitly mark
any conflict (a line in the living spec whose context diverged since the delta was written).
Do not touch any file until all diffs are displayed.
-
Timestamped backup — before writing to any openspec/specs/ file, write a backup to
openspec/specs/<capability>/.archive-backup/<YYYY-MM-DDTHH-MM-SS>-spec.md using atomic
write-and-rename (write to a .tmp file, then rename). Abort if the backup write fails.
-
Per-capability confirmation — for each capability whose living spec will change, show the
diff and wait for explicit confirmation for that specific capability. A blanket "proceed" does
not satisfy this requirement. Require the user to resolve any conflicts in the delta file
before the merge is applied; do not auto-resolve.
-
Atomic write with conflict detection — write each confirmed merge to a temp file
(spec.md.archive-tmp-<timestamp>), verify it was written completely, check that the living
spec still matches the backup (abort if it changed concurrently), then rename atomically.
Immediately verify by reading back and comparing the sha256 against the expected merged content.
Restore from backup and stop on any verification failure.
-
Idempotency marker — after each successful capability merge, write a marker at
openspec/changes/<change>/.specpowers/archive-applied/<capability> containing the sha256 of
the merged content. On any re-run, check this marker first and skip already-applied merges.
-
Move the change directory — once all merges are confirmed and verified, move
openspec/changes/<change>/ to openspec/changes/archive/<YYYY-MM-DD>-<change>/ atomically.
If the destination already exists, check idempotency marker state before deciding whether to
retry or report an inconsistency requiring human resolution.
Never emit any success message or mark the workflow complete unless every sub-step above
succeeded and was verified.
Step 3 — Emit the archive summary
Write the summary to
openspec/changes/archive/<YYYY-MM-DD>-<change>/archive-summary.md and present it to the user.
The summary must contain all five elements below. No element may be omitted or deferred:
-
Change name and identifier — the canonical change directory name, the archive date, and
the commit range (merge_base_oid..HEAD) from the compliance evidence record.
-
Final implementation summary — a coherent description of what was built: which files were
created or modified, what behavior was introduced or changed, and which spec capabilities are
now reflected in the living specs. Write this as a delivery summary, not a commit log.
-
Verification summary — how the implementation was verified: the compliance gate verdict
(passed, adversarial reviewer verdict, tier), which tests ran and their pass/fail counts, any
compliance findings and how they were resolved, and any minor findings accepted with
rationale.
-
Archive path and command result — the final location of the archived change directory. If
the real CLI was used, include the command invoked, its exit code, and its output. If the
conservative fallback was used, list each capability merged, the backup path written, and the
post-merge verification result for each.
-
Residual risks — an honest, specific assessment of anything unresolved after archive:
minor findings accepted with rationale, capabilities that required manual conflict resolution,
implementation files closely coupled to the changed behavior but outside the spec delta's scope,
known test-coverage gaps, and any explicit TODOs in the committed code. If there are no
residual risks, state "No residual risks identified." explicitly. Do not leave this field
blank.
