diff --git a/docs/agents.md b/docs/agents.md index faa4f36..7e06d99 100644 --- a/docs/agents.md +++ b/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` | diff --git a/docs/configuration.md b/docs/configuration.md index 84f1042..3d629ac 100644 --- a/docs/configuration.md +++ b/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/-/` | 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 diff --git a/docs/hq.md b/docs/hq.md index 6f310b6..1c74b6d 100644 --- a/docs/hq.md +++ b/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`) diff --git a/docs/quickstart.md b/docs/quickstart.md index 6c940bb..a566bf3 100644 --- a/docs/quickstart.md +++ b/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. diff --git a/docs/spec-and-milestones.md b/docs/spec-and-milestones.md index dc7f644..567c9d2 100644 --- a/docs/spec-and-milestones.md +++ b/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/.md`) and + run artifacts (`.ferrus/runs//`) 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//archive/specs/-/ +├─ 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 .md per task +└─ runs/ ← archived run artifacts, one / 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//archive/specs/-/` | 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