cash-archive

name	cash-archive
description	Archive a completed change
license	MIT
metadata	{"author":"cash","version":"1.0"}

Project-local Cash CLI bootstrap

執行任何 Cash artifact command 前，MUST 先從目前目錄解析並驗證 Git root，再使用該 root 下的 absolute launcher；不得依賴 PATH 或外部 runtime：

cash_root="$(git rev-parse --show-toplevel)" || exit 1
cash_cli="$cash_root/.cash-skills/bin/cash"
test -x "$cash_cli" || exit 1

同一段 workflow 後續每個 artifact command MUST 使用 "$cash_cli"。

Archive a completed change.

Input: Optionally specify a change name after $cash-archive (e.g., $cash-archive add-auth). If omitted, check if it can be inferred from conversation context. If vague or ambiguous you MUST prompt for available changes.

Prerequisites: The project-local launcher initialized above is required. If root resolution, launcher validation, or a Cash command fails, report the exact error and STOP.

Response language: All user-facing responses in this workflow MUST be written in Traditional Chinese unless the user explicitly requests another language. Keep shell commands, file paths, code identifiers, schema field names, and quoted source text verbatim.

Steps

1. If no change name provided, prompt for selection

   Run "$cash_cli" list --json to get available changes. Use the AskUserQuestion tool to let the user select.

   Show only active changes (not already archived). Include the schema used for each change if available.

   IMPORTANT: Do NOT guess or auto-select a change. Always let the user choose.

2. Check artifact completion status

   Run "$cash_cli" status --change "<name>" --json to check artifact completion.

   Parse the JSON to understand:

   • schemaName: The workflow being used
   • artifacts: List of artifacts with their status (done or other)

   If any artifacts are not done:

   • Display warning listing incomplete artifacts
   • Prompt user for confirmation to continue
   • Proceed if user confirms

3. Check task completion status

   Read the tasks file (typically tasks.md) to check for incomplete tasks.

   Count tasks marked with - [ ] (incomplete) vs - [x] (complete).

   If incomplete tasks found:

   • Display warning showing count of incomplete tasks
   • Prompt user for confirmation to continue
   • Proceed if user confirms

   If no tasks file exists: Proceed without task-related warning.

4. Choose spec sync behavior

   Check for delta specs at openspec/changes/<name>/specs/. If delta specs exist, ask whether to sync them.

   • Sync: archive without --skip-specs; the Cash CLI performs or verifies sync inside its transaction.
   • Do not sync: pass --skip-specs.
   • Cancel: stop without mutation.

   Do not invoke another skill or delete touched state directly. The Cash CLI owns touched import, sync state, legacy cleanup diagnostics, transaction flags, and cleanup.

5. Perform the archive

   Use the "$cash_cli" archive command, adding the selected flags:

   "$cash_cli" archive <name>
   "$cash_cli" archive <name> --skip-specs
   

   Optional flags:

   • --skip-specs — skip delta spec application (for tooling/doc-only changes)
   • --mark-tasks-complete — mark all incomplete tasks as complete before archiving
   • --no-validate — skip the independent change validation gate only; safety and delta identity preflight remain mandatory

   If archive fails with "already exists" error, suggest renaming existing archive.

6. Display summary

   Show archive completion summary including:

   • Change name
   • Schema that was used
   • Archive location
   • Spec sync status (synced / sync skipped / no delta specs)
   • Any legacy cleanup diagnostic returned by Cash; report it as a diagnostic only and do not re-read legacy state
   • Note about any warnings (incomplete artifacts/tasks)

Output On Success

## Archive Complete

**Change:** <change-name>
**Schema:** <schema-name>
**Archived to:** openspec/changes/archive/YYYY-MM-DD-<name>/
**Specs:** ✓ Synced to main specs

All artifacts complete. All tasks complete.

Output On Success (No Delta Specs)

## Archive Complete

**Change:** <change-name>
**Schema:** <schema-name>
**Archived to:** openspec/changes/archive/YYYY-MM-DD-<name>/
**Specs:** No delta specs

All artifacts complete. All tasks complete.

Output On Success With Warnings

## Archive Complete (with warnings)

**Change:** <change-name>
**Schema:** <schema-name>
**Archived to:** openspec/changes/archive/YYYY-MM-DD-<name>/
**Specs:** Sync skipped (user chose to skip)

**Warnings:**
- Archived with 2 incomplete artifacts
- Archived with 3 incomplete tasks
- Delta spec sync was skipped (user chose to skip)

Review the archive if this was not intentional.

Output On Error (Archive Exists)

## Archive Failed

**Change:** <change-name>
**Target:** openspec/changes/archive/YYYY-MM-DD-<name>/

Target archive directory already exists.

**Options:**
1. Rename the existing archive
2. Delete the existing archive if it's a duplicate
3. Wait until a different date to archive

Guardrails

• Preserve .openspec.yaml when moving to archive (it moves with the directory)
• Never delete touched or sync state directly; archive owns ensure, transaction, cleanup, and each legacy cleanup diagnostic
• If AskUserQuestion tool is not available, ask the same questions as plain text and wait for the user's response