Ss Archive

---
name: ss-archive
description: Merges an active OpenSpec change's delta specs into the authoritative openspec/specs/ tree and moves the change directory into the dated archive. Idempotent; the ss-create-pr skill calls it automatically before opening a PR. Use it once a delta is reviewed and ready to become part of the source of truth.
---

# Archive OpenSpec Change

Merge OpenSpec delta specs from `openspec/changes/<change-id>/specs/` into
`openspec/specs/`, then move the change directory to
`openspec/changes/archive/YYYY-MM-DD-<change-id>/`.

This skill is idempotent. The `ss-create-pr` skill calls it automatically before opening a
pull request.

## Inputs

Optional: a specific `<change-id>`, and/or `--dry-run` to validate and report without
writing anything.

## Process

### Step 1: Discover the Active Change

If a `<change-id>` was given, use it. Otherwise:

1. List directories under `openspec/changes/`, excluding `archive/`.
2. If none exist, report a no-op.
3. If exactly one exists, use it.
4. If multiple exist, ask the user which one to archive.

If `openspec/changes/<change-id>/specs/` has no delta files, report a zero-spec no-op.

### Step 2: Sync With Git

Check the working tree status.

- If there are uncommitted changes: continue only if they are the intended OpenSpec
  delta/code changes for this branch. Stop if unrelated files are dirty — never stash,
  discard, or rewrite the user's work.
- Don't rebase-pull while the worktree is dirty.
- If the worktree is clean, sync first (fetch and rebase against upstream).
- If the worktree is dirty but only contains the intended change, perform the archive
  merge and commit first, then rebase-pull only if needed before pushing.

### Step 3: Validate Delta Format

For every `openspec/changes/<change-id>/specs/<cap>/spec.md`:

- section headings are only ADDED / MODIFIED / REMOVED / RENAMED Requirements
- every section heading is followed by at least one `### Requirement:` entry — remove
  empty sections entirely
- every Requirement has at least one `#### Scenario:`
- `MODIFIED` entries copy a matching source-of-truth Requirement in full
- `REMOVED` entries include a Reason and a Migration note
- `RENAMED` entries use `FROM: <old> → TO: <new>`

If validation fails, stop and list the exact files and fixes needed.

### Step 4: Merge Deltas Into Source-of-Truth Specs

This is a semantic merge, not a mechanical patch — read and understand each delta before
writing. For each capability:

1. Read the delta file.
2. Read `openspec/specs/<cap>/spec.md`; if it doesn't exist, create a new source-of-truth
   spec.
3. Apply the delta:
   - ADDED: append the new Requirements.
   - MODIFIED: replace the matching Requirement with its full modified content.
   - REMOVED: remove the Requirement, keeping the rationale in the archived delta.
   - RENAMED: rename the Requirement heading, preserving content unless the delta also
     changes it.
4. Maintain the source-of-truth header:

```markdown
# Capability: <capability>

> Source of truth - auto-generated by the `ss-archive` skill from delta merges.
> Do not hand-edit this file. Create a new delta via the `ss-plan` skill's Phase 0,
> then merge it with `ss-archive`.

**Last archived change:** <change-id> (<YYYY-MM-DD>)
**Last sync commit:** <sha>
```

If the file still carries a baseline reverse-spec header (from `ss-reverse-spec`), remove
it after the first successful delta merge.

### Step 5: Move to Archive

Unless `--dry-run` was given:

1. Create `openspec/changes/archive/` if it doesn't exist.
2. Move the change directory to `openspec/changes/archive/<YYYY-MM-DD>-<change-id>/`,
   preserving history if your version control supports move-tracking.
3. Stage and commit: `chore(spec): archive <change-id>`.

Push only if the current branch already has an upstream. If the push fails, report the
local commit and leave the retry to the user.

## Output

Report:

- the archived change path
- capabilities merged
- Requirements added / modified / removed / renamed
- the commit SHA, if committed

No-op cases must be reported explicitly and treated as success.