feat(sweep): archive closed deferred-work entries so the ledger stays proportional to open work

CHANGELOG.md

@@ -15,6 +15,16 @@ breaking changes may land in a minor release.
   compatibility contract. The probe opens non-blocking, so a planted reader-less FIFO cannot
   park the orchestrator.
 
+- **`bmad-loop sweep --archive`** moves closed (`status: done <ISO date>`) deferred-work entries to
+  a sibling `deferred-work-archive.md`, replacing each with a stub that preserves the DW- id for
+  grep and `closes_deferred` cross-references plus the load-bearing field lines (`gate:`,
+  `origin:`/`source_spec:`, reopenable-close undo markers). The live ledger then carries open
+  entries in full and archived ones as compact stubs, rather than every closed body forever.
+  Supports `--before DATE` to archive only entries closed before a cutoff, and `--dry-run` to
+  preview. Reopening an archived stub leaves an `archived-body:` line pointing at the archive
+  block that holds its body. Refuses while any engine run is live. Pure deterministic Python —
+  no LLM involvement.
+
 ### Changed
 
 - **A published run archive now lands at mode `0600`** instead of a umask-derived mode (#591).

README.md

@@ -81,7 +81,7 @@ bmad-loop tui                    # …or drive everything from the dashboard
 | `bmad-loop mux`                                          | List registered terminal-multiplexer backends — platform match, availability, version, and which one is selected (and why). `mux set <name>` persists a machine-scoped choice into `.bmad-loop/policy.toml` (`--clear` reverts to auto-select, `--force` allows a name that only registers on the target machine); the `BMAD_LOOP_MUX_BACKEND` env var outranks it.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
 | `bmad-loop adapters`                                     | List registered coding-CLI adapter **kinds** — name, builtin/external, whether the family drives a multiplexer, and which profiles select each — the CLI axis's counterpart to `mux`. Unlike `mux` there is no global choice to persist: a kind is selected per profile by its `adapter` field. A profile naming an unregistered kind, and any out-of-tree adapter/profile package that failed to load, get a `warning:` on stderr.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
 | `bmad-loop run`                                          | Drive the dev → review → verify → commit loop. `--epic N`, `--story KEY`, `--max-stories N`, `--dry-run`. `--spec <folder>` forces **stories mode** (folder+id dispatch off `<folder>/stories.yaml`), overriding `[stories].source`; `--story` then filters by story id.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
-| `bmad-loop sweep`                                        | Triage + execute open `deferred-work.md` entries. `--no-prompt`, `--decisions-only`, `--max-bundles N`, `--repeat`, `--max-cycles N`, `--dry-run`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
+| `bmad-loop sweep`                                        | Triage + execute open `deferred-work.md` entries. `--no-prompt`, `--decisions-only`, `--max-bundles N`, `--repeat`, `--max-cycles N`, `--dry-run`. `--archive [--before DATE]` instead moves closed ledger entries to `deferred-work-archive.md`, leaving id-preserving stubs.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
 | `bmad-loop resume <run-id>`                              | Continue a run paused at a gate, escalation, or interruption.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
 | `bmad-loop resolve <run-id>`                             | Resolve a CRITICAL escalation: open an interactive resolve agent to fix the frozen spec, then re-arm the story and resume. On an _intent gap_ the re-drive can resume review on the attempted change instead of re-implementing it. `--story KEY`, `--no-interactive`, `--restore-patch <path>` (intent-gap patch-restore), `--resume` / `--no-resume`, `--force` (proceed when engine liveness is unverifiable; a provably-live engine still blocks).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
 | `bmad-loop decisions`                                    | Answer deferred-work decisions earlier sweeps left unanswered (skipped by `--no-prompt`, or an abandoned interactive sweep). Recorded so the next sweep acts on them without re-asking. `--list` shows them without answering; `--json` emits them as a stable machine-readable document — id, question, context, recommendation, and every option's key/label/effect/intent/resolution/bundle-name with a derived `recommended` flag. It implies the listing and never prompts, so a script can select an option by policy instead of scraping the text.                                                                                                                                                                                                                                                                                                                                                                                                      |

docs/FEATURES.md

@@ -133,6 +133,7 @@ See [README.md](../README.md) for the narrative overview and [setup-guide.md](se
 - Auto-sweep at epic boundaries or run-end (`[sweep] auto`); a failed or paused child sweep is journaled + notified and leaves the parent running — including the `SystemExit` an unusable multiplexer or an unresolvable profile raises, which used to end the parent at exit 1 with an orphaned session (#600). A stop (`bmad-loop stop`) or a Ctrl-C delivered through the child is the deliberate exception and propagates, so a parent stays stoppable while a child sweep is mid-flight (#601).
 - A trigger is spent only once its child has actually started, so a refusal no longer consumes it (#501) — but nothing re-asks it either, since both call sites close their boundary within a few statements of the refusal. What the run keeps instead is a record: `sweeps_refused` (trigger → `not-started` / `failed` / `dirty`), surfaced by the end-of-run summary, `bmad-loop status`, `status --json` and `bmad-loop diagnose`, naming `bmad-loop sweep` (which needs a clean worktree) as the human-present follow-up.
 - Repeat mode (`--repeat` / `[sweep] repeat`): re-triages after each cycle to absorb newly generated deferred work, stopping when a cycle does nothing addressable or hits `max_cycles`.
+- Ledger archiving (`sweep --archive`, optionally `--before DATE` to bound by close date; `--dry-run` previews): moves closed (`status: done <ISO date>`) entries to sibling `deferred-work-archive.md` (body preserved, an `archived: <date>` marker appended), leaving an id-preserving stub (`status: done <date>` + `archived: <date>`) so grep and `closes_deferred` cross-references keep resolving and the live ledger stays proportional to open work rather than all history. The stub keeps load-bearing field lines — `gate:` (validate's closed-gate report keeps speaking), `origin:`/`source_spec:` (the harvest-replay dedupe stays status-agnostic), and the reopenable-close undo tail (a paused sweep's bundle rollback still works). Reopening an archived stub — what that rollback does — demotes its `archived:` stamp to `archived-body:` rather than dropping it: the entry is live work again, so the stamp would be a lie and its shape would strand the entry outside every future archive, but the body its close moved out is still in the archive file and that line is what a later triage follows to it. Deterministic, no LLM, atomic writes with crash-safe ordering (archive before ledger; a retry keyed on id + close date completes the move without duplicate bodies). Refuses while any engine run is live or its liveness is unverifiable — it is the one out-of-band ledger writer. When the ledger is tracked, the move is durable only once both files are committed; a gitignored ledger — the default shape — or an artifact dir outside the repo has nothing to commit. Unrelated to `bmad-loop archive <run-id>` (run-tarball archiving).
 - Sweeps are their own resumable runs (`bmad-loop resume <id>`). An escalated bundle resolves like a story escalation, including intent-gap patch-restore: `bmad-loop resolve <id> --restore-patch <path>` re-arms the bundle spec to `in-review` and the re-driven bundle session resumes review on the re-applied patch instead of re-implementing.
 
 ### Stories mode (folder+id dispatch)

src/bmad_loop/cli.py

@@ -482,8 +482,7 @@ def cmd_validate(args: argparse.Namespace) -> int:
         channel = (
             "the ATTENTION file in the run directory is the only alert channel left"
             if pol.notify.file
-            else "notify.file is also off, so no alert channel is configured — "
-            "enable notify.file"
+            else "notify.file is also off, so no alert channel is configured — enable notify.file"
         )
         report.warn(
             "notify.desktop-unavailable",
@@ -2212,6 +2211,28 @@ def cmd_sweep(args: argparse.Namespace) -> int:
         return rc
     project = _project(args)
     paths = bmadconfig.load_paths(project)
+
+    if args.before is not None and not args.archive:
+        print("--before requires --archive", file=sys.stderr)
+        return ExitCode.FAILURE
+
+    if args.archive:
+        if (
+            args.decisions_only
+            or args.repeat is not None
+            or args.max_bundles is not None
+            or args.max_cycles is not None
+            or args.no_prompt
+            or args.run_id is not None
+        ):
+            print(
+                "--archive cannot combine with --decisions-only, --repeat, "
+                "--max-bundles, --max-cycles, --no-prompt, or --run-id",
+                file=sys.stderr,
+            )
+            return ExitCode.FAILURE
+        return _sweep_archive(project, paths, args)
+
     pol = policy_mod.load(_policy_path(project))
 
     if args.dry_run:
@@ -2246,6 +2267,74 @@ def cmd_sweep(args: argparse.Namespace) -> int:
     )
 
 
+def _sweep_archive(project: Path, paths: bmadconfig.ProjectPaths, args: argparse.Namespace) -> int:
+    """`bmad-loop sweep --archive`: move closed deferred-work entries to a
+    sibling archive file. A self-contained sub-mode — no worktree, no
+    preflight, no LLM. Refuses while any engine run is live or unverifiably
+    so: this is the one out-of-band ledger writer, and a concurrent close or
+    harvest landing between its read and its writes would be silently
+    clobbered. An unverifiable pid is treated as live — a write op takes the
+    conservative side, unlike the cleanup guards which only warn.
+
+    Run dirs are enumerated raw (:func:`runs.all_run_dirs`) rather than through
+    the ``state.json``-gated :func:`runs.list_run_dirs`: a run whose state file
+    was removed still owns its ``engine.pid`` and still writes this ledger, and
+    the gated view would report it as no run at all. An unreadable runs root
+    answers nothing, so it refuses too — same conservative side."""
+    run_dirs = runs.all_run_dirs(project)
+    if run_dirs is None:
+        print(
+            f"cannot list runs under {project / runs.RUNS_DIR} — "
+            "refusing to archive ledger entries",
+            file=sys.stderr,
+        )
+        return ExitCode.FAILURE
+    for run_dir in run_dirs:
+        if runs.engine_liveness(run_dir) != "dead":
+            print(
+                f"run {run_dir.name} may still be live — stop it before archiving ledger entries",
+                file=sys.stderr,
+            )
+            return ExitCode.FAILURE
+    ledger = paths.deferred_work
+    # Call the primitive BEFORE reporting a missing ledger, and report the
+    # missing ledger from its empty result. `archive_closed` validates `before`
+    # ahead of its own `is_file` short-circuit precisely so a malformed date
+    # fails the same way whether or not a ledger exists; short-circuiting here
+    # first put that back, and `--before not-a-date` then exited 0 on a project
+    # that happens to have no ledger today and 1 on one that does — the same
+    # invocation graded by optional project data rather than by its own shape
+    # (#711 review). The call is safe on a missing file: it short-circuits to
+    # an empty list without writing.
+    try:
+        archived = deferredwork.archive_closed(
+            ledger,
+            before=args.before,
+            dry_run=args.dry_run,
+        )
+    except ValueError as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return ExitCode.FAILURE
+    if not ledger.is_file():
+        print(f"no deferred-work ledger at {ledger}")
+        return ExitCode.OK
+    archive_path = ledger.parent / deferredwork.ARCHIVE_REL
+    if not archived:
+        print("no closed entries to archive")
+        return ExitCode.OK
+    noun = "entry" if len(archived) == 1 else "entries"
+    if args.dry_run:
+        print(f"would archive {len(archived)} {noun}:")
+        for dw_id in archived:
+            print(f"  {dw_id}")
+        return ExitCode.OK
+    print(f"archived {len(archived)} {noun} to {archive_path}:")
+    for dw_id in archived:
+        print(f"  {dw_id}")
+    print("note: if the ledger is tracked, commit both files to make the move durable")
+    return ExitCode.OK
+
+
 def _sweep_dry_run(paths: bmadconfig.ProjectPaths, pol) -> int:
     # Before the no-ledger early return below: a broken install is worth saying so
     # about whether or not there is anything to sweep.
@@ -4222,7 +4311,23 @@ def add(name: str, func, help: str, *, aliases=()) -> argparse.ArgumentParser:
     )
     sweep_p.add_argument("--max-cycles", type=int, help="override [sweep] max_cycles")
     sweep_p.add_argument(
-        "--dry-run", action="store_true", help="list open ledger entries, spawn nothing"
+        "--dry-run",
+        action="store_true",
+        help="list open ledger entries, spawn nothing; with --archive: list the "
+        "entries that would move, write nothing",
+    )
+    sweep_p.add_argument(
+        "--archive",
+        action="store_true",
+        help="move closed (status: done <ISO date>) deferred-work entries to a "
+        "sibling deferred-work-archive.md, leaving a minimal stub in the live "
+        "ledger; use --before DATE to archive only entries closed before that "
+        "date, and --dry-run to preview",
+    )
+    sweep_p.add_argument(
+        "--before",
+        metavar="DATE",
+        help="with --archive: archive only entries closed before this ISO date",
     )
     sweep_p.add_argument("--run-id", help=argparse.SUPPRESS)  # pre-assigned id (used by the TUI)
 
@@ -4356,7 +4461,12 @@ def add(name: str, func, help: str, *, aliases=()) -> argparse.ArgumentParser:
         "--force", action="store_true", help="stop the run first if it is still live"
     )
 
-    archive_p = add("archive", cmd_archive, "compress a run into .bmad-loop/archive and remove it")
+    archive_p = add(
+        "archive",
+        cmd_archive,
+        "compress a run into .bmad-loop/archive and remove it; "
+        "for ledger archiving see `sweep --archive`",
+    )
     archive_p.add_argument("run_id")
     archive_p.add_argument(
         "--force", action="store_true", help="stop the run first if it is still live"

src/bmad_loop/data/skills/bmad-loop-sweep/SKILL.md

@@ -35,6 +35,13 @@ are `### DW-<n>:` blocks whose `status:` line is `open`. If the ledger is
 missing or unreadable, escalate `CRITICAL` (`type: missing-ledger`) per
 automation-mode.md and end your turn.
 
+An entry carrying an `archived:` line keeps only a stub here — its full body
+lives in the sibling `deferred-work-archive.md`, keyed by the same DW- id; read
+it there before classifying that entry. An `archived-body:` line says the same
+of an entry that was archived and later reopened: it is live work again, but the
+body it carried before that close is still in the archive file, in the block
+stamped with the date the line carries.
+
 If the invocation carries `--feedback <path>`, read that file FIRST — it lists
 the deterministic validation errors your previous attempt's result.json failed
 on. Fix exactly those defects in this attempt's output.