Add /archive-spec command to close out completed specs

docs/agents.md

@@ -89,7 +89,7 @@ to call:
 
 | `--role` | Tools |
 |---|---|
-| `supervisor` | Definition sessions: `enqueue_task`, `create_spec`; task sessions: `wait_for_review`, `review_pending`, `approve`, `reject`, `wait_for_consultation`, `respond_consult`, `ask_human`, `wait_for_answer`, `heartbeat` |
+| `supervisor` | Definition sessions: `enqueue_task`, `create_spec`, `archive_spec`; task sessions: `wait_for_review`, `review_pending`, `approve`, `reject`, `wait_for_consultation`, `respond_consult`, `ask_human`, `wait_for_answer`, `heartbeat` |
 | `executor` | `wait_for_task`, `check`, `consult`, `submit`, `wait_for_consult`, `ask_human`, `wait_for_answer`, `status`, `reset`, `heartbeat` |
 | *(omitted)* | All tools, plus compatibility aliases `create_task` and `answer` |
 

docs/configuration.md

@@ -161,6 +161,7 @@ intent and run artifacts, not a mirrored state machine.
 |---|---|
 | `project.toml` | Project id, name, workspace path, `.ferrus` path, git metadata, timestamps, schema version |
 | `ferrus.db` | SQLite source of truth for tasks, runs, events, leases, counters, and project runtime state |
+| `archive/specs/<spec-slug>-<closed-at>/` | Completed-spec archives written by `/archive-spec`: `manifest.toml`, a copy of `spec.md`, and the relocated `tasks/` and `runs/` artifacts |
 | `logs/` | Reserved for machine-local logs that should not be committed |
 
 `ferrus init` automatically adds `.ferrus/` to your `.gitignore`. On HQ

docs/hq.md

@@ -20,7 +20,8 @@ and retry/cycle counters in real time.
 | Command | Description |
 |---|---|
 | `/plan` | Free-form planning session with the supervisor (no task created). |
-| `/spec` | Draft a feature specification with the supervisor and save it as a Markdown artifact you can later feed into `/task`. |
+| `/spec` | Draft a feature specification with the supervisor and save it as a Markdown artifact you can later feed into `/task`. Offers to archive the currently selected spec first if it is already complete. |
+| `/archive-spec` | Summarize the completed selected spec's work into an `## Outcome` section and archive its linked task and run artifacts. |
 | `/milestones` | Select the current spec and milestone without creating a task. |
 | `/task` | Queue one task from the next ready milestone with the supervisor, then run the SQLite scheduler. Supports `--manual` to skip milestone resolution and define a free-form task. |
 | `/run [--limit N]` | Plan a **batch** run: queue tasks for every ready milestone in the selected spec (or up to `--limit`) and let the scheduler dispatch executors for all of them, bounded by `max_parallel_tasks`. |
@@ -94,8 +95,16 @@ touching the task state or task files. Use it when you want to work on an
 ad-hoc task with no spec context, or when the selection is stale and you
 don't need to pick a new one right away.
 
+Once every milestone in the selected spec is complete, `/archive-spec`
+closes it out: the supervisor summarizes what actually shipped into an
+`## Outcome` section on the spec, and — after you approve that text — the
+linked task and run artifacts are moved into a machine-local archive so
+`.ferrus/tasks/` and `.ferrus/runs/` stay focused on active work. `/spec`
+offers the same archival step automatically when the spec you currently
+have selected is already finished.
+
 See the [Specs & Milestones guide](/docs/spec-and-milestones) for the full
-workflow, spec file format, and auto-advance behaviour.
+workflow, spec file format, auto-advance, and spec archival behaviour.
 
 ## Consultation (`/consult`)
 

docs/quickstart.md

@@ -93,7 +93,10 @@ ferrus> /spec
 
 The supervisor walks you through a feature specification and saves it as
 Markdown under `docs/specs/`. You can then point the next `/task` at that
-file so the executor implements directly from an approved design.
+file so the executor implements directly from an approved design. When every
+milestone in the spec is done, `/archive-spec` records an `## Outcome`
+summary and files the spent task/run artifacts away — see the
+[Specs & Milestones guide](/docs/spec-and-milestones#closing-out-a-spec-archive-spec).
 
 :::tip
 Press **Ctrl+C** twice within 2 seconds to exit HQ.

docs/spec-and-milestones.md

@@ -25,6 +25,7 @@ ferrus> /task              ← confirm the milestone, draft the task, run the lo
 ferrus> /task              ← confirm the next milestone, run the loop
   └─ Complete              ← next milestone auto-selected
 …
+ferrus> /archive-spec      ← all milestones done: write ## Outcome, archive artifacts
 ```
 
 When you run `/task`, ferrus shows the currently selected milestone and asks
@@ -34,6 +35,8 @@ the task is approved and moves to `Complete`, ferrus silently advances the
 selection to the next incomplete milestone — ready for the next `/task`.
 
 You never have to touch `/milestones` in a straight-line run through a spec.
+When the last milestone lands, `/archive-spec` closes the spec out — see
+[Closing out a spec](#closing-out-a-spec-archive-spec).
 
 ## Writing a spec (`/spec`)
 
@@ -140,6 +143,75 @@ milestone — as long as you haven't manually overridden the selection since the
 task started. If you used `/milestones` to point at a different milestone
 mid-flight, auto-advance is suppressed and your manual choice is respected.
 
+## Closing out a spec (`/archive-spec`)
+
+Once every milestone in a spec is complete, the spec has served its purpose as
+a plan. `/archive-spec` turns it into durable **project memory** and clears its
+working artifacts out of the way in one guided step:
+
+```
+ferrus> /archive-spec
+```
+
+It spawns a supervisor session in archive mode. The supervisor reads the spec
+and its linked task and run history, drafts a concise `## Outcome` section —
+what actually shipped, notable deviations from the plan, validation evidence,
+and any follow-up work — and presents it to you. **Nothing is written or moved
+until you approve the outcome text.** After you approve, the supervisor calls
+the `archive_spec` tool, which:
+
+1. appends (or replaces) the spec's `## Outcome` section in place;
+2. moves the spec's linked task artifacts (`.ferrus/tasks/<task-id>.md`) and
+   run artifacts (`.ferrus/runs/<task-id>/`) into a machine-local archive; and
+3. records the archive — spec path, close timestamp, task/run counts, and the
+   approved outcome — in `ferrus.db`.
+
+The spec file itself stays in your repository, now carrying its `## Outcome`
+summary; only the machine-local task/run scratch artifacts are relocated, so
+`.ferrus/tasks/` and `.ferrus/runs/` stay focused on active work.
+
+### Preconditions
+
+`/archive-spec` refuses to run — with a specific message — unless all of these
+hold, so you never archive a spec that is still in flight:
+
+| Requirement | Detail |
+|---|---|
+| A spec is selected | Run `/milestones` first if nothing is selected; the selected spec file must still exist. |
+| All milestones complete | Every milestone must be `- [x]`; any incomplete milestone is listed and blocks archival. |
+| No live tasks | Every task linked to the spec must be in a terminal state (e.g. `Complete`); non-terminal tasks block archival. |
+| Artifacts to archive | At least one linked task or run artifact must remain to move. |
+
+### Where archives go
+
+Archives live under the machine-local project directory, not in your
+repository:
+
+```text
+~/.ferrus/projects/<project-id>/archive/specs/<spec-slug>-<closed-at>/
+├─ manifest.toml   ← spec path, archive timestamp, and per-task metadata
+├─ spec.md         ← copy of the spec as archived (with its ## Outcome)
+├─ tasks/          ← archived task artifacts, one <task-id>.md per task
+└─ runs/           ← archived run artifacts, one <task-id>/ directory per run
+```
+
+The `spec_archives` row in `ferrus.db` remains the queryable source of truth,
+and `ferrus doctor` still accounts for the relocated run artifacts. See
+[Runtime files](/docs/configuration#runtime-files).
+
+### Archiving from `/spec`
+
+You don't have to run `/archive-spec` explicitly. When you start `/spec` while
+the currently selected spec is already complete, ferrus offers to archive it
+first — running the same flow — before drafting the new specification. Decline
+and the old spec is left untouched; the new one is drafted alongside it.
+
+:::tip
+Treat `## Outcome` as compact memory for future agents. When a later `/spec`
+or `/plan` session builds on finished work, the supervisor reads the outcome
+instead of re-deriving context from raw task and run artifacts.
+:::
+
 ## Manual milestone selection (`/milestones`)
 
 ```
@@ -207,6 +279,7 @@ directory = "docs/specs"  # any path inside the project; created on first write
 | File | Contents |
 |---|---|
 | `.ferrus/SPEC_TEMPLATE.md` | Read-only template the supervisor loads during `/spec` |
+| `~/.ferrus/projects/<project-id>/archive/specs/<spec-slug>-<closed-at>/` | Machine-local archive written by `/archive-spec`: `manifest.toml`, a copy of `spec.md`, and the relocated `tasks/` and `runs/` artifacts |
 
 The selected spec path and milestone ID are stored as project runtime state
 in `ferrus.db`, alongside the rest of the SQLite-backed runtime state — see