archive

Archive a completed change. Checks completion, syncs features to living documentation, then moves to archive.

<decision_boundary>

Use for:

• Archiving a completed (or verified distilled) change
• Syncing features into beat/features/ living documentation
• Final living-doc sweeps (glossary terms, last-mile ADR) before archiving

NOT for:

• Verifying implementation against spec (use /beat:verify)
• Implementing remaining tasks (use /beat:apply)
• Creating or modifying spec artifacts (use /beat:design)

Trigger examples:

• "Archive the change" / "The change is done, wrap it up" / "Sync the features"
• Should NOT trigger: "verify the implementation" / "implement the change" / "design a feature"

</decision_boundary>

<HARD-GATE> After archive is complete: you MUST invoke superpowers:finishing-a-development-branch to guide merge/PR/cleanup. If unavailable (not installed), skip and show summary only — but NEVER skip because you judged the workflow complete without it. Before archiving: you MUST check the top-level verification field in status.yaml; if absent or issues-found, confirm with the user — inform and confirm, never block. When gherkin status is done: you MUST sync features before archiving. Before sync: you MUST scan the features being synced for project-specific terms that are not yet defined in beat/CONTEXT.md, and prompt the user to add them. Before moving to archive: you MUST run the last-mile ADR sweep — if zero ADRs were written for this change, prompt once before archiving. This applies whether or not features were synced. Do NOT skip any of these because the user wants speed. </HARD-GATE>

Prerequisites (invoke before proceeding)

If unavailable (skill not installed), skip and show archive summary only.

Rationalization Prevention

Red Flags — STOP if you catch yourself:

• Completing archive without invoking finishing-a-development-branch
• Skipping the sync step without checking if gherkin is done
• Moving to archive without asking user about capability mapping (when features exist)
• Completing archive while .feature.orig files remain in beat/features/
• Syncing features without first scanning for project-specific terms missing from beat/CONTEXT.md
• Archiving a change with zero ADRs without running the last-mile sweep prompt
• Archiving a change with no verification record (or status: issues-found) without confirming with the user

Process Flow

digraph archive {
    "Select change" [shape=box];
    "Check artifact completion" [shape=diamond];
    "Warn incomplete" [shape=box];
    "Check task completion" [shape=diamond];
    "Warn incomplete tasks" [shape=box];
    "Verification recorded?" [shape=diamond];
    "Warn unverified" [shape=box];
    "Gherkin done?" [shape=diamond];
    "Ask capability mapping" [shape=box];
    "Scan features for\nundefined terms" [shape=box, style=bold];
    "Sync features" [shape=box];
    "Skip sync" [shape=box];
    "Last-mile ADR sweep" [shape=box, style=bold];
    "Move to archive" [shape=box];
    "Show summary" [shape=box];
    "Invoke finishing-a-development-branch" [shape=doublecircle, style=bold];

    "Select change" -> "Check artifact completion";
    "Check artifact completion" -> "Warn incomplete" [label="pending found"];
    "Check artifact completion" -> "Check task completion" [label="all done/skipped"];
    "Warn incomplete" -> "Check task completion" [label="user confirms"];
    "Check task completion" -> "Warn incomplete tasks" [label="incomplete"];
    "Check task completion" -> "Verification recorded?" [label="all complete\nor no tasks"];
    "Warn incomplete tasks" -> "Verification recorded?" [label="user confirms"];
    "Verification recorded?" -> "Warn unverified" [label="absent or\nissues-found"];
    "Verification recorded?" -> "Gherkin done?" [label="passed"];
    "Warn unverified" -> "Gherkin done?" [label="user confirms"];
    "Gherkin done?" -> "Ask capability mapping" [label="done"];
    "Gherkin done?" -> "Skip sync" [label="skipped"];
    "Ask capability mapping" -> "Scan features for\nundefined terms";
    "Scan features for\nundefined terms" -> "Sync features";
    "Sync features" -> "Last-mile ADR sweep";
    "Skip sync" -> "Last-mile ADR sweep";
    "Last-mile ADR sweep" -> "Move to archive";
    "Move to archive" -> "Show summary";
    "Show summary" -> "Invoke finishing-a-development-branch";
}

Input: Optionally specify a change name. If omitted, infer from context or prompt.

Steps

1. Select the change

If no name provided:

• Look for beat/changes/ directories (excluding archive/)
• If only one exists, use it
• If multiple exist, use AskUserQuestion tool to let user select
• Show only active (non-archived) changes

1. Check artifact completion

Read beat/changes/<name>/status.yaml (schema: references/status-schema.md). Check which artifacts are done vs pending (not skipped).

If any non-skipped artifacts are still `pending`:

• Display warning listing incomplete artifacts
• Use AskUserQuestion tool to confirm user wants to proceed
• Proceed if user confirms

1. Check task completion (if tasks.md exists)

Read tasks.md. Count - [ ] (incomplete) vs - [x] (complete).

If incomplete tasks found:

• Display warning: "N/M tasks incomplete"
• Use AskUserQuestion tool to confirm
• Proceed if user confirms

3b. Check verification ran (schema: references/status-schema.md)

Read the top-level verification field from status.yaml:

• Absent: warn "This change was never verified (/beat:verify has not run)." Use AskUserQuestion tool to confirm archiving anyway.
• `status: issues-found`: warn "Verification found N critical issue(s) on <date>." Use AskUserQuestion tool to confirm.
• `status: passed`: proceed silently.

Inform and confirm — never block.

1. Sync features to living documentation

Check status.yaml:

If gherkin status is `skipped`: Skip sync (no features to sync). Proceed to step 4b.

If gherkin status is `done`:

Read from beat/changes/<name>/:

• features/*.feature (all Gherkin files)
• proposal.md (if exists)
• design.md (if exists)

If no feature files exist: skip sync, proceed to step 4b.

Read beat/config.yaml if it exists (schema: references/config-schema.md). Use language for README content language.

Determine capability mapping:

Use AskUserQuestion tool:

"Where should each feature be synced? Existing capabilities: [list from beat/features/]. Or enter a new name."

If only one feature file and the mapping is obvious from context, suggest a default.

Scan features for undefined terms (Layer 1 living-doc enforcement):

Read beat/CONTEXT.md if it exists (schema: references/context-format.md). The glossary is lazy — it may not exist yet if this is the project's first synced change.

Scan the feature files being synced for bolded project-specific terms. For each term:

• If it exists in beat/CONTEXT.md: OK, continue.
• If it doesn't: use AskUserQuestion tool:

"Term '<term>' appears in scenarios but isn't in beat/CONTEXT.md. Add it now?" - Yes (recommended): provide a one-sentence definition; Beat appends it - Skip this term - Skip all remaining (record the count for the summary)

When the user adds a term, append it to beat/CONTEXT.md following the structure in references/context-format.md (one-sentence definition, optional _Avoid_ aliases). Create beat/CONTEXT.md lazily if it doesn't exist.

If no project-specific bolded terms appear in the scanned features, skip this sub-step silently.

Sync files:

If beat/features/ doesn't exist, create it: mkdir -p beat/features

When features map to multiple capabilities, copy proposal.md and design.md to the primary capability only (the one receiving the most feature files). On a tie, ask the user which capability owns them. Don't duplicate them across capabilities.

Handle .orig backups (when status.yaml has gherkin.modified):

For each path in gherkin.modified:

1. The modified version is in changes/<name>/features/ — sync it to beat/features/<capability>/ (same as new features, unified flow)
2. Delete the .feature.orig backup from beat/features/
3. If the project uses pytest-bdd: update @scenario decorator paths in test files (from beat/changes/.../x.feature → beat/features/<capability>/x.feature)

Verify no .feature.orig files remain in beat/features/ before proceeding.

Create beat/features/<capability>/README.md if it doesn't exist (placeholder description). Create or update beat/features/README.md with global navigation.

Update status.yaml phase to sync.

4b. Last-mile ADR sweep (Layer 2 living-doc enforcement)

Runs on every path — whether features were synced or sync was skipped.

Count ADR files written or referenced during this change:

• Check docs/adr/ for files created since this change started (git diff against the change's base commit)
• Scan design.md and tasks.md for docs/adr/NNNN- cross-references

If at least one ADR exists for this change: skip the sweep silently. Earlier triggers (in /beat:design, /beat:plan, /beat:apply) already caught the candidates.

If zero ADRs exist for this change: prompt once using AskUserQuestion tool:

"No ADRs recorded for this change. Was there any hard-to-reverse + surprising + real-trade-off decision worth recording before archiving?" - No, none qualified - Yes, let me describe it now

If user describes one, run the three-condition gate from references/adr-format.md. If all three hold, write the ADR under docs/adr/ with the next sequential number. If not all three hold, note the skip.

Either way, proceed to archive.

1. Perform the archive

Update status.yaml: set phase to archive.

   mkdir -p beat/changes/archive

Generate target name: YYYY-MM-DD-<change-name>

Check if target already exists:

• If yes: fail with error, suggest renaming
• If no: move the directory

   mv beat/changes/<name> beat/changes/archive/YYYY-MM-DD-<name>

1. Show summary

   ## Archive Complete

   **Change:** <change-name>
   **Archived to:** beat/changes/archive/YYYY-MM-DD-<name>/
   **Verification:** passed / issues-found (N critical) / never run (user confirmed)
   **Features:** Synced to beat/features/ (or "Sync skipped" or "No features to sync")
   **Glossary:** N terms added to beat/CONTEXT.md (or "no changes" / "M terms skipped")
   **ADRs:** N written to docs/adr/ (or "none recorded — last-mile sweep declined")
   **Artifacts:** N done, M skipped
   **Tasks:** X/Y complete (or "No tasks file")

1. Finish the development branch

After showing the summary, invoke superpowers:finishing-a-development-branch (if available) to guide the user through merge, PR creation, or cleanup. If not available, skip this step.

Guardrails

• Always prompt for change selection if not provided
• Don't block archive on warnings -- inform and confirm
• Sync features inline before archiving
• Show clear summary of what happened
• If archive target already exists, don't overwrite