Prospec Archive

---
name: prospec-archive
description: "Archive Changes - Archive completed changes, generate summary, sync requirements to feature specs, and gate archiving on Knowledge sync. Triggers: archive, spec sync, finalize change, 封存, 歸檔, 收尾, 規格同步"
---
<!-- Generated by `prospec agent sync`. Do not edit — this file is regenerated on every sync. -->

# Prospec Archive Skill

## Activation

When triggered, briefly describe:
- That you'll scan `.prospec/changes/` for completed changes
- The deterministic mutations are executed by `prospec archive <name>` (previewed with `--dry-run`); this skill keeps the judgment work — the Entry Gate, the Review & Verify summary, and REQ semantic graduation
- Knowledge sync for affected modules is folded into the verify S/A commit prompt; the Entry Gate re-confirms it (backstop) before archiving

## Language Policy

Write each generated document in the language the Constitution's Language Policy rule assigns to **its path** — change artifacts and their archived summaries in the project's artifact language, the trust zone (Knowledge base, Feature Specs, index) in English. One skill run may write both. Keep code, identifiers, technical terms, and git commit messages in English.
## CLI Prerequisite (required)

> The prospec CLI is a required file for this skill — its deterministic steps call `prospec`
> commands. Probe BEFORE any other step; there is no manual fallback.

1. Run `prospec --version` (Bash).
2. **Command not found / not executable** → STOP. Ask the user to install the prospec standalone
   executable — the one-click installer script from the project README (macOS/Linux `install.sh`,
   Windows `install.ps1`) or a release binary from GitHub Releases; prospec is NOT published to
   npm. Then re-run this skill.
3. **Version older than 2.0.0** → STOP. Report the installed vs required version
   and ask the user to upgrade, then re-run this skill.

Hand-executing a CLI-owned mutation is NEVER the fallback — that re-introduces the
nondeterministic serialization this contract exists to remove.

## Startup Loading

1. [DYNAMIC] Read `.prospec/changes/` — scan all change directories and their `metadata.yaml`

> Format references are read **per phase on demand**, NOT as Startup Loading items (keeps the stable prefix lean): [`references/archive-format.md`](references/archive-format.md) at Phase 2/3 (summary + spec archiving), [`references/feature-spec-format.md`](references/feature-spec-format.md) at Phase 3.5, [`references/product-spec-format.md`](references/product-spec-format.md) at Phase 3.6. (`references/promotion-format.md` is already read on demand at Phase 4.5.) Read each when entering its phase; do not preload them into the stable prefix.

## Entry Gate

> Blocking precondition check per archive target. If any item FAILs, stop and tell the user what is missing — do not archive that change. This gate is the **backstop** that re-confirms the knowledge sync folded into the verify S/A commit prompt (the prevention point); it still **FAILs and refuses to archive** when affected-module Knowledge is not synced (defense in depth — the sync is moved earlier, not removed).

- Archive target is `status: verified` — only `prospec-verify` at grade S/A produces `verified` (lifecycle: `prospec/ai-knowledge/_status-lifecycle.md`).
- **Metadata completeness (machine-checked)**: `prospec archive` refuses when the `metadata-completeness` check is FAIL — **do not archive**; the metadata is missing a required field (`name`/`created_at`/`status`/`scale`) or, being `verified`, records no `prospec-verify` S/A grade. Fix it (re-run `prospec-verify` if the grade is genuinely absent), then re-archive. `--allow-incomplete` exempts this check only, for a pre-schema record. (The CLI is required — the probe STOPs before this gate when the engine is missing.)
- **Review, test and delta-spec provenance (machine-checked)**: `prospec archive` refuses when the `review-provenance`, `test-provenance` or `delta-spec-provenance` check is FAIL for this change — **Any FAIL → do not archive**, and the CLI names the remedy per cause. A review/test FAIL means the code moved since the review round or test run: re-run `prospec-review` then `prospec-verify`, or — if the only movement was the verify S/A commit — re-record (`prospec check --record-review` / `--record-tests`) after committing. A `delta-spec-provenance` FAIL is different: the `**Spec:**` landing blocks about to be copied verbatim into the trust zone are stale — **Fix the block, not the code**, then re-record. `skipped` is not a FAIL. When that re-verify **does not reach S/A** the change is not archivable — `status` stays `verified` but `metadata-completeness` reads the LATEST grade, so **never archive on the strength of a `status` the latest verify did not earn**. (The CLI is required — the probe STOPs before this gate when the engine is missing.)
- Knowledge is synced for this change: `prospec archive` **refuses** when affected-module Knowledge is not synced — it derives the affected set from `metadata.related_modules`, falling back to the delta-spec ADDED/MODIFIED/REMOVED REQ ID prefixes, and refuses until each module's README reflects the change's final state (REMOVED behavior must no longer appear). Not synced → run `prospec-knowledge-update` for those modules, then re-archive. A change that touches no modules (planning/docs-only) passes this item.
  - **`metadata.scale: quick`** has no delta-spec — derive affected modules from the **actual diff file paths** mapped through `prospec/ai-knowledge/module-map.yaml` (REQ-prefix extraction over an absent delta-spec is an empty set and would silently pass). The path mapping is deterministic. This diff-path derivation is a Phase 4 **skill** step: `prospec archive`'s knowledge-sync refusal derives its set from `metadata.related_modules` only (no delta-spec to fall back to), so a quick change without `related_modules` passes the CLI check vacuously and the CLI does **not** backstop the diff-path check — sync any module the diff touches before archiving.
  - **`metadata.scale: backfill`** uses feature-first, feature-slug REQ IDs (e.g. `REQ-USER-PROFILE-001`), so REQ-prefix extraction does **not** map to modules — derive affected modules from `metadata.related_modules` plus (`**Feature:**` → `prospec/ai-knowledge/feature-map.yaml` `modules`) instead. `related_modules` is always written by `prospec-promote-backfill`, so the set is **never silently empty**; the feature may not yet be in feature-map (brand-new feature) — then `related_modules` is the source. The same FAIL rule applies.
  - **`metadata.scale: standard` / `full`** with a **feature-prefixed REQ** — a delta-spec REQ prefix that matches a `req_prefixes` entry in `prospec/ai-knowledge/feature-map.yaml` is a feature prefix, **not** a module (e.g. `REQ-USER-PROFILE-*`). Derive that REQ's affected modules from `metadata.related_modules` plus (`**Feature:**` → feature-map `modules`), exactly as backfill does — treating the prefix as a module name would target a module that does not exist (silent no-op + phantom `modules/<prefix>/` risk). Module-prefix REQ IDs (`REQ-AUTH-*` …) map to their module as before. The same FAIL rule applies.
- **Quick spec-impact check** (`metadata.scale: quick` only) — the quick-scale **substitute** for delta-spec-driven graduation, not extra ceremony: a `standard`/`full` change graduates from delta-spec REQs authored at plan time; a quick change has no delta-spec, so its spec impact is determined here from the actual diff. It cannot move earlier — no diff exists before implement. Keep it to a **single bounded judgment** (does the diff touch spec-covered behavior?), not a re-analysis. Compare the actual diff against existing `prospec/specs/features/` REQs — an LLM judgment step (do not claim determinism).
  - Diff affects spec-covered behavior → **FAIL**: require a minimal **Spec Impact** section appended to proposal.md (REQ ID + ADDED/MODIFIED per affected requirement), then re-run. Phase 3.5 graduates from that section.
  - No spec impact → pass; record the diagnostic conclusion in summary.md and skip graduation.


## Core Workflow


### Phase 1: Scan and Confirm Targets

Scan `.prospec/changes/` for changes with `status: verified` — **only `verified` changes are archivable** (status lifecycle: `prospec/ai-knowledge/_status-lifecycle.md`).
Display a table of archivable changes:

| Change Name | Status | Created | Modules |
|-------------|--------|---------|---------|

Confirm the set with the user before proceeding.

> **Phase 1 Gate** — proceed when:
> - [ ] Archivable-changes table listed only `status: verified` changes
> - [ ] User confirmed the set of changes to archive

### Phase 2: Generate Summary

For each change to archive:
1. Read `proposal.md` — extract User Story and acceptance criteria (and the Spec Impact section for a quick change that has one)
2. Read `delta-spec.md` — extract REQ IDs and affected modules (quick: absent — use the Spec Impact section and diff-derived modules from the Entry Gate)
3. Read `tasks.md` — calculate completion rate over **code tasks only** (kind schema: tasks-format reference). Unchecked code tasks → **warn and list them** before archiving; unchecked `[M]` manual tasks → reminder only, never blocking. (`scale: backfill` has no tasks.md — skip this step.)
4. Check for `design-spec.md` and `interaction-spec.md` — if present, note design artifacts in summary
5. Assemble the **Review & Verify** section from `metadata.yaml` `quality_log` (WARN/FAIL digest), `review.md` (critical/major counts + a short findings excerpt), and the verify report (grade + dimensions) — archiving is the one moment these still exist before the worktree workflow can discard them (same window as Phase 4.5 Harvest). When a source is absent, state it plainly (`Unverified`, `no review round`); **never fabricate** a grade or counts. Format: `references/archive-format.md` §6
6. Generate `summary.md` following `references/archive-format.md` specification — it MUST carry the `## Review & Verify` section from step 5

> **Phase 2 Gate** — proceed when:
> - [ ] `summary.md` generated per `references/archive-format.md` for each target change
> - [ ] `summary.md` carries the `## Review & Verify` section (grade + criticals/majors + `quality_log` digest; `Unverified`/`no review round` when a source is absent, never fabricated)
> - [ ] Code-task completion rate computed; any unchecked code tasks surfaced to the user

### Phase 3: Execute Archive

The deterministic mutations are code-executed by the CLI — do not hand-run them. For each confirmed change:
1. Preview: run `prospec archive <change-name> --dry-run` and show the planned mutations.
2. Execute: run `prospec archive <change-name>` — it moves the bundle to `.prospec/archive/{YYYY-MM-DD}-{change-name}/`, sets `status: archived` + `archived_at`, and runs the mechanical Feature Spec / product.md `## Feature Map` / feature-map.yaml syncs (detailed in Phases 3.5–3.6). A `refused`/`not found` report means the target is not archivable — resolve it, never force.
3. Overwrite the scaffold `summary.md` in the archive directory with the Phase 2 summary (the one carrying `## Review & Verify`) — the scaffold is the deterministic baseline; the Phase 2 summary is the record.
The `_archived-history` copy and the feature-spec counter reconciliation happen AFTER the judgment
work, via `prospec archive finalize` in Phase 3.7 — running them here would copy the scaffold and
count the pre-graduation spec text.

> **Phase 3 Gate** — proceed when:
> - [ ] `prospec archive` executed (dry-run previewed first) — bundle moved to `.prospec/archive/{YYYY-MM-DD}-{change-name}/` with all artifacts (originals not deleted)
> - [ ] Phase 2 `summary.md` (with `## Review & Verify`) placed in the archive directory, replacing the scaffold
> - [ ] `metadata.yaml` `status` set to `archived`

### Phase 3.5: Feature Spec Sync

> `prospec-archive` is the **sole writer** of Feature Specs — requirements graduate into the permanent capability record here (the archive service is this station's mechanical writer; it writes nowhere else). `prospec-verify` deliberately does not gate on Feature Spec freshness (see `_status-lifecycle.md`), so this graduation step is where `specs/features/` catches up to the change.

> **PHASE 3.5 SPEC GRADUATION CONTRACT**:
> Before proceeding with Phase 3.5, **STOP immediately and read `references/spec-graduation.md`** to understand the FIVE CLI worklists, the block-replaces-whole-body rule, and graduation key by scale.

`prospec archive` (Phase 3) already performed the **mechanical** Feature Spec Sync. What remains is the **judgment** work — REQ semantic graduation:

1. **Audit CLI Worklists**: Consult the 5 worklists (`pendingConvergence`, `droppedBehavior`, `refusedRequirements`, `acknowledgedDrops`, `staleDeclarations`) per [`references/spec-graduation.md`](references/spec-graduation.md). Phase 3's mechanical sync replaced bodies only where the delta-spec carried a `**Spec:**` block — it did NOT replace bodies lacking one (having landed does not mean you lost nothing — inspect dropped behavior; a refusal for an ADDED entry with no `**Spec:**` block points at Description / Acceptance Criteria).
2. **Read Graduating REQs**: Read every requirement this change graduates from the **merged Feature Spec on disk** via `prospec spec show <feature> --req <ids>` (Bash) (the worklists above do **not** define that set — each is an EXCEPTION report; **Graduation key by scale** names that set: `quick` → the proposal's **Spec Impact** section; `standard`/`full`/`backfill` → delta-spec REQ IDs; never substitute the delta-spec).
3. **Converge wording**: Rewrite merged text into the spec's English, behavior-first voice; trim transient change narrative.
4. **Story Placement & Context**: Ensure ADDED REQs sit under their respective User Story sections and context is enriched per [`references/spec-graduation.md`](references/spec-graduation.md) and [`references/feature-spec-format.md`](references/feature-spec-format.md).
5. (Frontmatter counters are reconciled mechanically by `prospec archive finalize` in Phase 3.7 — do not recount them by hand).

**Feature Spec Sync is non-fatal** — if it fails, archiving still succeeds. Warn the user to manually update Feature Specs.

> **Phase 3.5 Gate** — proceed when:
> - [ ] Every REQ on the CLI's graduation worklist has a converged body (no REQ left with only a title, and no pre-change body left describing post-change behavior)
> - [ ] Every bullet the CLI reported as **dropped behavior** is either restored into the `**Spec:**` block or written into that entry's `**Dropped:**` block — a landing block replaces the whole body, so what it omits leaves the trust zone. Confirming deliberateness means *writing it down*, not asserting it in passing: the CLI holds the write until the declaration is there, and the declaration is what a later reader audits (an empty report satisfies this item)
> - [ ] Every REQ the CLI **refused** has had the block the refusal NAMES fixed — `**Spec:**` for a MODIFIED entry, `**Description:**`/`**Acceptance Criteria:**` for an ADDED entry that carries no `**Spec:**` block. A refusal means that block was cut short by a label the delta-spec template does not own, so the fragment was never trusted. Inline the labelled section as bullets; a `**Dropped:**` declaration does not release a refusal
> - [ ] Every **stale declaration** reported is resolved — a declared bullet that was not dropped means the delta-spec describes an older body than the spec now has, so re-read the merged file before graduating
> - [ ] Each ADDED/MODIFIED/REMOVED requirement routed into its Feature Spec under `prospec/specs/features/` (CLI-reported, spot-checked; or graduation skipped for a quick change diagnosed as no-impact)
> - [ ] Merged REQ wording converged and placed under the right Story section
> - [ ] Any sync failure logged and surfaced to the user (non-fatal)

### Phase 3.6: Product Spec Sync

`prospec archive` (Phase 3) already wrote both outputs — confirm rather than re-derive:

1. Confirm the run did **not** report a declined `product.md` sync. A decline means the Feature Map was NOT synced — the CLI names the reason (a near-miss `## Feature Map` heading, an unclosed code fence, an absent `specs/features/`) and what resolves it. Apply that fix now, and say so in the summary: this change's bundle has already moved out of `.prospec/changes/`, so the sync cannot be retried for it — the Feature Map lands on the **next archive run**, which rescans every active Feature Spec and loses nothing. Do not confirm item 2 against a file the sync never touched
2. **When the sync ran** (item 1 reported no decline), confirm `prospec/specs/product.md`: its Feature Map lists every active Feature Spec — including any spec Phase 3.5's wording pass just touched — and everything outside that section is unchanged apart from the frontmatter's `last_updated` (`## Feature Map` is the only machine-owned region; a **missing** product.md is instead bootstrapped to `references/product-spec-format.md`, TBD placeholders included). After a decline there is nothing to confirm — the file was not touched — and item 1 carries this one
3. Read the authored sections for a feature map the sync will not recognize: one under a **different name** (`## Feature Inventory`, `## 功能地圖`), or under a same-name heading the near-miss rule does not reach — that rule is lexical and narrow, and its exact reach lives in the CLI (`archive` spec-sync) and its contract test, so headings like `## Feature Map (draft) (2024)` and `## 3.1 Feature Map` fall past it and are silently appended. Either way a second map is about to be appended: reconcile it with the author instead of leaving two to drift apart
4. Confirm `prospec/ai-knowledge/feature-map.yaml` — the feature→module index, scanned alongside `product.md` from the same `specs/features/*.md`. **Bootstrap-once + no-clobber**: an existing index (and its human-curated `req_prefixes`) is never overwritten; on first creation `modules` is seeded from each feature's module-prefix REQ headings and `req_prefixes` is left empty for human curation. The archive service writes it as an idempotent, non-fatal safety net.

**Product Spec and feature-map writes are non-fatal** — if either fails, Feature Spec Sync results are still valid.

> **Phase 3.6 Gate** — proceed when:
> - [ ] the run reported no declined `product.md` sync — or, when it did, the named cause is fixed and the pending sync is recorded in the summary (the Feature Map lands on the next archive run; this change's bundle has already moved)
> - [ ] no authored section duplicates the Feature Map — under another name, or under a same-name heading past the near-miss rule's reach (defined by the CLI)
> - [ ] when the sync ran, `prospec/specs/product.md` Feature Map lists every active Feature Spec, and content outside that section is preserved apart from the `last_updated` refresh (a bootstrapped file follows `references/product-spec-format.md`); after a decline this item is carried by the first one
> - [ ] any `TBD` placeholder the bootstrap left (Vision, Target Users, Core Stories, a new feature's description) is either filled in or knowingly left for the author — the sync never fills them
> - [ ] `prospec/ai-knowledge/feature-map.yaml` present (bootstrapped on first archive; existing curated index left untouched)

### Phase 3.7: Finalize (post-judgment CLI step)

Run `prospec archive finalize <change-name>` (Bash; `--dry-run` first to preview). It executes the
two writes that MUST come after the judgment work above:

1. Copies the finalized `summary.md` (the Phase 2 record you placed in Phase 3 — the command refuses
   while the file still lacks `## Review & Verify`) to
   `prospec/specs/_archived-history/{YYYY-MM-DD}-{change-name}.md` — the **committed**
   spec-history audit trail (`.prospec/archive/` is gitignored, so this copy is the only per-change
   record in version control). It lands in `_archived-history/` (drift-excluded via
   `ARCHIVED_EXCLUDES`), never flat under `prospec/specs/`.
2. Reconciles every feature spec's frontmatter `story_count`/`req_count` against its FINAL
   (post-graduation) body — except a spec whose body would zero a counter the frontmatter declares
   above zero: that file is left byte-identical and reported as a refused reconciliation on stderr.
   A zeroed count is treated as a parse signal, not a fact, so converge that spec by hand (its
   counters keep warning under `spec-counters` until you do).

Non-fatal — a finalize failure never un-archives; fix and re-run (idempotent).

> **Phase 3.7 Gate** — proceed when:
> - [ ] `prospec archive finalize` ran after Phase 3.5's graduation
> - [ ] each refusal was read for WHICH kind it is: a *command* refusal means the Phase 3 summary overwrite is missing (fix that first); a *reconciliation* refusal names a spec whose counter would have been zeroed (converge that spec — re-running finalize will not fix it)

### Phase 4: Knowledge Sync Re-check

The Entry Gate already required Knowledge to be synced — this phase re-confirms the gate held through archiving (no prompt, no question):

1. Extract affected module names from delta-spec REQ ID prefixes (e.g., `REQ-AUTH-010` → `auth`, `REQ-API-005` → `api`); for `scale: quick`, reuse the Entry Gate's diff-derived module set (module-map.yaml path mapping); for `scale: backfill`, reuse the Entry Gate's `metadata.related_modules` + `**Feature:**`→feature-map module set (REQ-prefix extraction does not apply to feature-slug REQ IDs); for `scale: standard`/`full`, a REQ prefix matching a feature-map `req_prefixes` entry is a feature prefix — resolve it via `metadata.related_modules` + `**Feature:**`→feature-map, not as a module name
2. Confirm each affected module README still reflects the archived change; list the confirmed modules:
   ```
   Knowledge sync confirmed for this change:
   - [module-1]: [N] requirements reflected
   - [module-2]: [N] requirements reflected
   ```
3. If a gap is found (gate state regressed since the Entry Gate), STOP: run `prospec-knowledge-update` for the gap, then continue — do not fall back to an optional prompt
4. Refresh the deterministic project-structure snapshot so `prospec/ai-knowledge/raw-scan.md` reflects the just-archived code for the next `prospec-knowledge-generate`: run `prospec knowledge init --raw-scan-only` (Bash). Non-fatal — a refresh failure is noted, never blocks the archive.

> The archive service does **not** auto-trigger a knowledge update or a raw-scan refresh. Steps 3–4 above (and the Entry Gate) are the only knowledge-sync path — perform them manually; there is no service-side fallback.

> **Phase 4 Gate** — proceed when:
> - [ ] Every affected module README re-confirmed to reflect the archived change (no regression since the Entry Gate)
> - [ ] Confirmed modules listed with their reflected requirement counts; any gap resolved via `prospec-knowledge-update`
> - [ ] `raw-scan.md` refreshed via `prospec knowledge init --raw-scan-only` (or the failure noted, non-fatal)

### Phase 4.5: Auto-Harvest Recurring Lessons

Harvest this change's `quality_log` and `review.md` into the version-controlled ledger now — a fresh worktree may no longer have them.

Follow the **Harvest** definition in [`references/promotion-format.md`](references/promotion-format.md) (read it on demand; do not restate the ledger table here):

1. Scan this change's `metadata.yaml` `quality_log` (WARN/FAIL) and `review.md` (recurring criticals); cross `tasks.md` × kind markers for `[M]` manual tasks left unchecked.
2. Assign each finding its deterministic ledger key, emit the lesson JSON (`{key, description, kind, source_change, impact_modules}`) to a temp file and run `prospec learn upsert --lesson <file>` (Bash) — the **same single writer** `prospec-learn` Collect uses, so `prospec/ai-knowledge/_lessons-ledger.md` is never hand-edited from here. The CLI owns the mechanics: `source_changes` is a set and `frequency` increments once per distinct change, so re-archiving is **idempotent** (no double-count); a row whose `status` is `retired` is **refused** — counters untouched, `unchanged` reported with a warning naming the key — because its root cause is gone. Recording that occurrence in the row's `description`, or un-retiring the row, is a human act for `prospec-learn` Sweep, never something to force through here. A recurring unchecked-`[M]` pattern records a `kind: playbook` "manual task systematically skipped" lesson; a `tasks.md` without kind markers is skipped, not guessed.
3. **Regression Pin Adjudication** — inspect regression pins introduced during this change's review fix-loop. If a pin enforces a generalizable structural or security invariant across a whole family (e.g. formatter sanitize, issue-ref sink), note it for promotion to a permanent directory-enumerated contract test during `prospec-learn`.
4. This is **non-fatal** (try/catch + log, like Feature Spec Sync / knowledge update) — a harvest failure never blocks archiving.

Then point the user at `prospec-learn` for Score/Promote — auto-harvest only accumulates; nothing is promoted to `_playbook.md`/Constitution without explicit human approval.

## Output Contract

> After running, self-assess and emit a concise Output Summary. Every Success Criterion must be objectively checkable (file existence / grep / test result / count) — no subjective adjectives.

### Success Criteria
- [ ] summary.md generated
- [ ] Feature Spec sync completed
- [ ] metadata status set to archived
- [ ] knowledge sync confirmed (Entry Gate held through Phase 4 re-check)

### Failure Conditions
- archived a non-verified change without confirmation
- Feature Spec sync skipped

### Output Summary
Emit one line: `Met N/M | Unmet: <items> | Overall: PASS|WARN|FAIL | Next: <one-line>`

## NEVER

- **NEVER** archive without user confirmation — accidental archiving moves active work out of changes/; recovery requires manual file moves. The explicit change name passed to `prospec archive <name>` is that confirmation's carrier — never archive unnamed
- **NEVER** hand-execute the deterministic mutations — `prospec archive` owns the move, scaffold summary, mechanical spec sync, and the product Feature-Map/feature-map writes; `prospec archive finalize` owns the `_archived-history` copy and the counter reconciliation; hand-running any of them re-introduces the drift the CLI entry exists to prevent (preview with `--dry-run` instead)
- **NEVER** archive a change that is not `status: verified` — only `prospec-verify` at grade S/A produces `verified`; tell the user to verify to S/A first (lifecycle: `prospec/ai-knowledge/_status-lifecycle.md`)
- **NEVER** skip summary.md generation — summary is the permanent record in the archive directory; without it, the change has no audit trail
- **NEVER** emit a summary.md that lacks the `## Review & Verify` section — the review/verify evidence (grade, criticals/majors, `quality_log`) lives only in the gitignored bundle otherwise, and the `_archived-history` copy is the sole durable record; when a source is absent record `Unverified`/`no review round`, never fabricate
- **NEVER** delete original files instead of moving — deletion is irreversible; archive preserves all artifacts for future reference and debugging
- **NEVER** modify the content of artifacts during archive — artifacts are the historical record; any modification falsifies the development history
- **NEVER** bypass the Entry Gate knowledge-sync check — a failed `prospec-knowledge-update` means the gate stays FAIL; fix it and re-run, then archive. Archiving with stale Knowledge writes a permanent record that contradicts the code, and no later checkpoint will force the sync
- **NEVER** archive without reading delta-spec.md — affected modules drive both Spec Sync and Knowledge Update; skipping produces orphaned requirements (`scale: quick` is the exception: modules come from diff paths and graduation from the Spec Impact section; `scale: backfill` derives modules from `related_modules`/`**Feature:**`→feature-map, graduating via the delta-spec as usual)
- **NEVER** skip the quick spec-impact check or treat its empty REQ-prefix module set as "touches no modules" — an absent delta-spec is not evidence of no impact; the actual diff is

## Error Handling

| Scenario | Action |
|----------|--------|
| No changes found in changes/ | Inform user that there are no changes to archive |
| Entry Gate knowledge-sync FAIL | Guide user to run `prospec-knowledge-update` for the affected modules, then re-run `prospec-archive` |
| Change missing metadata.yaml | Skip that change, warn user about incomplete change directory |
| Change missing delta-spec.md | `scale: quick`: expected — run the quick spec-impact check instead. Otherwise: archive with partial summary, note missing spec in summary.md |
| `prospec archive` reports `refused` / `not found` | The named target is not archivable (wrong status) or misspelled — resolve per the report (verify to S/A, or `prospec status` to list names); never force |
| Archive directory already exists | The CLI reports it skipped (exit 1) — investigate the stale destination with the user before retrying |
| File move fails | The CLI rolls back that change's move and reports the error — surface it, continue with others |

## Next-Step Handoff

After the Output Summary, recommend the next step in the SDD workflow order
(`story → plan → tasks → implement → review → verify → knowledge-update → archive`, then periodic `learn`) — read
`metadata.yaml` status and `prospec/ai-knowledge/_status-lifecycle.md` (review and learn own no
status transition, so follow this order, not status alone). Provide the direct, actionable Skill
identity or CLI command for the next step (e.g. `prospec-plan`), allowing smooth continuation
without blocking on a separate confirmation turn. If the stage is terminal (`archived`), the linear
flow is complete — point to periodic `prospec-learn` rather than a workflow successor. If the result
does not advance (e.g. verify grade B/C/D), say so and point to the corrective step instead of
offering the next skill.