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>

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.

Prerequisites (invoke before proceeding)

Superpower	When	Priority
finishing-a-development-branch	After archive is complete	MUST

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

Rationalization Prevention

Thought	Reality
"The change is already archived, finishing-a-development-branch is optional cleanup"	Archive without branch guidance leaves orphan branches and uncommitted work. The skill ensures nothing is forgotten.
"I'll just tell the user to create a PR manually"	finishing-a-development-branch offers structured options (merge, PR, cleanup) tailored to the current state. Manual advice misses context.
"Skipping sync is fine, the user can run it later"	There is no separate sync skill. Archive is the only place features get synced. Skipping means features are lost from living documentation.
"The .orig backups can be cleaned up later"	Orphaned .orig files hide scenarios from BDD runners permanently. Cleanup is part of archive, not a separate step.
"Glossary terms can be added later, it's just docs"	Once the features sync into beat/features/, the undefined terms become user-facing living documentation. Future readers can't tell which terms are canonical vs. ad hoc. The scan-and-prompt is two minutes — do it before sync.
"We didn't write any ADRs but the design.md captures everything"	design.md gets archived with the change. Cross-change decisions need to live in docs/adr/. The last-mile sweep is one prompt; if nothing qualifies, it costs nothing.
"Verify probably ran at some point, no need to check"	status.yaml records it. If the verification field is absent, verify never ran — archiving unverified work silently is exactly the gap the check exists to close. One confirmation prompt, never a block.

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

2. 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

3. 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 ." Use AskUserQuestion tool to confirm.
• status: passed: proceed silently.

Inform and confirm — never block.

4. 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 '' 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

   Source (change)	Target (beat/features/)	Behavior
   features/*.feature	beat/features/<capability>/	Add or update feature files
   proposal.md	beat/features/<capability>/proposal.md	Copy to capability
   design.md	beat/features/<capability>/design.md	Copy to capability

   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.

5. 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>
   

6. 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")
   

7. 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