archive

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

When it runs: after /beat:verify and before the PR or merge, on whatever branch the change lives on (normally the worktree branch /beat:design created). The archive is the last commit on that branch and ships in the same PR as the code, so main never carries an active beat/changes/<name> directory for a feature that has already landed. Archive itself hands off to the merge/PR step (step 7) — it is never something to do after the PR is merged. Archive never creates or switches branches: if the user is on the base branch, archive there and let step 7 handle branch state.

<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)
• Waiting for the PR to be merged first — archive is the last commit on the branch, before the PR, and it invokes the merge/PR step itself

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>

Prerequisites (invoke before proceeding)

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

Unattended mode

When the run carries a stage-result nonce (see references/handoff-report.md), nobody is watching: follow references/unattended-mode.md. Every AskUserQuestion in this skill becomes a default (recorded in beat/changes/<name>/decisions/assumed.md), a decision brief (references/decision-brief.md, blocked-on: decision), or an environmental stop (blocked-on: env). The per-skill table in that reference says which. For archive specifically: the confirmations in steps 2, 3 and 3b should not arise in a flow (verify precedes archive) and are env if they do; capability mapping and glossary terms take the obvious answer and are recorded; the ADR sweep is skipped; the route is archived when complete. Step 7 changes shape: no finishing-a-development-branch, the branch is pushed and a ready PR opened with a decisions section.

Rationalization Prevention

Red Flags — STOP if you catch yourself:

• Completing archive without invoking finishing-a-development-branch (interactive mode)
• 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 GLOSSARY.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
• Copying the change's design.md over an existing beat/features/<capability>/design.md
• Finishing archive while any file still references beat/changes/<name> (the pre-move path)
• Deferring archive until the PR is merged, or invoking finishing-a-development-branch with the archive result uncommitted

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];
    "Rewrite references\nto old change path" [shape=box, style=bold];
    "Route node?" [shape=diamond];
    "Derive route status,\noffer route archive" [shape=box];
    "Commit archive" [shape=box, style=bold];
    "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" -> "Rewrite references\nto old change path";
    "Rewrite references\nto old change path" -> "Route node?";
    "Route node?" -> "Derive route status,\noffer route archive" [label="yes"];
    "Route node?" -> "Commit archive" [label="no"];
    "Derive route status,\noffer route archive" -> "Commit archive";
    "Commit 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)

Run node <skill-dir>/scripts/validate-beat.mjs --pre-archive <name> (see references/lint-tools.md). It reports each of the conditions below plus unchecked tasks; use its output to decide which warning to raise. Then 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. State the open WARNING / SUGGESTION count and, when mode is incremental, that the last run re-read only the diff — one line, no question. A passing verify is converged (zero open CRITICAL); a full re-run is the user's choice, never a condition.

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 GLOSSARY.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 GLOSSARY.md: OK, continue.
   • If it doesn't: use AskUserQuestion tool:

     "Term '<term>' appears in scenarios but isn't in GLOSSARY.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, insert it into GLOSSARY.md where "Where a new entry goes" in references/context-format.md says — inside the ## <group> section it belongs to (or ## Language for a flat glossary), one-sentence definition, optional _Avoid_ aliases. Never append it to the end of the file: that lands the term under ## Flagged ambiguities. Create GLOSSARY.md lazily if it doesn't exist, writing the full skeleton first.

   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 if absent; merge if present (see below)

   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.

   Merging design.md into an existing capability design:

   The capability's design.md is a current-state document that accumulates every change that touched the capability. The change's design.md is a delta written before implementation. When beat/features/<capability>/design.md already exists, never copy over it — read both and rewrite the capability file so it describes the system as it now is:

   1. Approach — restate the capability's overall approach as it stands after this change. Fold in this change's approach where it extends the existing one; replace the parts it changed.
   2. Key Decisions — keep every existing decision still in force. Add this change's decisions. A decision this change reverses is not deleted: rewrite it as the new decision and note what it superseded (Supersedes: <old decision> — see <archived change path or ADR>). Keep existing See docs/adr/NNNN-slug.md cross-references.
   3. Components — update the component list to match the code after this change (added, removed, renamed).
   4. History — append one line under ## History (create the section if absent): - YYYY-MM-DD <change-name>: <one-line summary of what the change did>. This is the only append-only part of the file.

   The result reads as one document: each section appears once, in the capability's existing language and section order, describing the system as it is now. If the two documents genuinely conflict and the code doesn't settle it, use AskUserQuestion tool rather than guessing. The change's own design.md stays untouched in the change directory and is archived with it.

   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)

   Run node <skill-dir>/scripts/validate-beat.mjs --change <name> — it reports any .feature.orig left in beat/features/ that no active change claims. Then run node <skill-dir>/scripts/lint-features.mjs so the synced features and the README index are clean.

   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, follow "Before writing an ADR" in that reference (apply config rules.adr; use the project's docs/adr/TEMPLATE.md if it exists, otherwise Beat's front-matter template with source: beat/changes/<name> — step 5b rewrites it to the archived path) and 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>

5b. Rewrite references to the old change path

Moving the directory breaks every link that pointed at it: ADR source fields and links, See beat/changes/<name>/... cross-references in synced features and design docs, glossary or README mentions, and self-references inside the moved directory (e.g. tasks.md pointing at its own design.md).

Run node <skill-dir>/scripts/validate-beat.mjs --stale-paths <name> (see references/lint-tools.md). It lists every tracked or untracked file that still references beat/changes/<name> (excluding the archived status.yaml, which records the change by name). In each listed file replace beat/changes/<name> with beat/changes/archive/YYYY-MM-DD-<name> — only where the old path is followed by /, whitespace, punctuation or end of line, never where it continues into a longer change name. Rerun until it prints no files.

Record the number of files rewritten for the summary.

5b2. Route check (only when status.yaml has route: <route>/<node>)

Read beat/routes/<route>/status.yaml (schema: references/route-schema.md). The node's status is derived from this change's phase, so nothing is written to the node. Derive every node's status; if all are done, use AskUserQuestion tool: "Every node of route <route> is done. Archive the route to beat/routes/archive/YYYY-MM-DD-<route>/?" On Yes, mkdir -p beat/routes/archive && mv beat/routes/<route> beat/routes/archive/YYYY-MM-DD-<route> and include it in step 5c. Otherwise list the new frontier in the summary so the next /beat:explore <route> knows where to start.

5c. Commit the archive

Everything this run produced is one unit of work and must be committed on the current branch — do not create or switch branches — before step 7 hands off to merge/PR:

git add beat/changes/            # the moved directory (deletions + new archive path)
git add beat/routes/             # only if step 5b2 archived the route
git add beat/features/           # synced features, capability README/proposal/design.md
git add GLOSSARY.md          # glossary terms added in step 4
git add docs/adr/                # ADRs from the last-mile sweep, plus any ADR index
git add <files rewritten in 5b>  # references updated to the archived path
git commit -m "archive(<name>): sync features and archive change"

Stage only paths git status shows and this run wrote (a path the user modified outside this run stays unstaged). After the commit, git status must be clean apart from files unrelated to the archive — finishing-a-development-branch runs the test suite and offers merge/PR on top of this commit; it does not commit for you.

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")
   **Design doc:** merged into beat/features/<capability>/design.md (or "created" / "no design.md in change")
   **Glossary:** N terms added to GLOSSARY.md (or "no changes" / "M terms skipped")
   **ADRs:** N written to docs/adr/ (or "none recorded — last-mile sweep declined")
   **References rewritten:** N files updated from beat/changes/<name> to the archived path (or "none found")
   **Commit:** <sha> archive(<name>): sync features and archive change
   **Artifacts:** N done, M skipped
   **Tasks:** X/Y complete (or "No tasks file")
   **Route:** <route> — N/M nodes done, frontier: [...] (or "route archived" / "standalone")

   Then the handoff block from references/handoff-report.md (next: the finishing-a-development-branch step below, or /beat:explore <route> when a route still has frontier nodes).

   One line after the block, not a step: "If this change taught you something about the environment (a lint rule, a config.yaml rule, a CLAUDE.md note), /retro from mattpocock-skills turns it into one — pass it beat/changes/archive/YYYY-MM-DD-<name>/verify.md and status.yaml." Only mention it when that skill is installed.

7. Finish the development branch

   Interactive: invoke superpowers:finishing-a-development-branch (if available) to guide the user through merge, PR creation, or cleanup. The archive commit from step 5c is already on the branch, so whichever option the user picks carries it — this is the first point in the pipeline where pushing is expected. If not available, skip this step.

   Unattended (references/unattended-mode.md): do not invoke finishing-a-development-branch. Push the branch (git push -u origin <branch>) and open a ready pull request (never a draft) against the base branch. Build the body with the pr skill from mattpocock/skills when installed (it shapes the smallest visual, before/after evidence and the one-way / two-way door call), the project's PR template when there is one, and in every case one section with this exact heading that the human reads before the diff:

   ## 決定與影響
   - 已定案（來自 issue）：<each locked decision, one line; "無" if none>
   - 這次做的決定：<each Key Decision from design.md with its ADR link; each D<n> brief with its outcome>
   - assumed（採預設、沒問人）：<each line of decisions/assumed.md; "無" if the file is absent>
   - 沒處理的 verify WARNING：<open WARNING / SUGGESTION ids with one phrase each; "無">
   - sensitive：<"無", or which situation / path matched and in which phase>
   - preset 升級：<from → to and reason, or "無">

   Use the English heading ## Decisions and impact with the same bullets when the project's language is not zh-TW. The data comes from decisions/, design.md, verify.md and status.yaml in the archived directory — read them, do not recall. When status.yaml has issue (or the change otherwise came from an issue), the body ends with Closes <issue> (for example Closes #454) so the merge closes it. Report the PR URL in the summary and make the handoff next the PR URL's review step. Merge stays with the human.

   Re-entry. If an earlier unattended run stopped with env part-way, resume from what is on disk: the directory already under beat/changes/archive/ means the move is done; a commit whose message starts with archive(<name>) means step 5c is done; gh pr view showing a PR for this branch means step 7 is done. Never redo a step whose result exists.

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
• Never overwrite an existing capability design.md — merge and rewrite as current state
• After the move, no tracked file may still reference beat/changes/<name>
• Archive runs before the PR/merge and commits its result; it is never deferred until after the PR lands
• Unattended mode opens the PR itself and never merges; interactive mode hands off to finishing-a-development-branch
• Never write node status into a route — it is derived from the changes