@getpipher/armory-todo 0.5.5 → 0.7.0

package/README.md

@@ -16,7 +16,7 @@
 </p>
 
 <p align="center">
-  <strong>lifecycle boxes</strong> · <strong>title + notes</strong> · <strong>auto-prune</strong> · <strong>interactive panel</strong> · <strong>health diagnostics</strong> · <strong>hard-prune gate</strong>
+  <strong>lifecycle boxes</strong> · <strong>title + notes</strong> · <strong>auto-prune</strong> · <strong>source-aware reap safety</strong> · <strong>interactive panel</strong> · <strong>health diagnostics</strong> · <strong>hard-prune gate</strong>
 </p>
 
 ---
@@ -25,8 +25,9 @@
 
 The package `exports` entry (`./src/index.ts`) is the **stable public surface** —
 `addTodo`, `listTodos`, `updateTodo`, `getTodo`, `completeTodo`, `parkTodo`,
-`deleteTodo`, and the `Todo` / `AddInput` / `UpdateInput` / `ListFilter` /
-`Priority` / `Status` / `Store` types (plus `TodoError`). Other `src/*` paths
+`deleteTodo`, `loadStore`, `saveStore`, and the `Todo` / `AddInput` /
+`UpdateInput` / `ListFilter` / `Priority` / `Status` / `Store` /
+`SaveStoreOptions` types (plus `TodoError`). Other `src/*` paths
 are internal and may change without notice. Depend on `@getpipher/armory-todo`
 (the public entry), never deep-import `src/*`.
 
@@ -77,6 +78,17 @@ reports what moved (`auto-pruned N stale done (>7d): …` + a `restore` hint);
 it's a transient message, not a prompt injection. Reversible via `restore <id>`.
 `prune --all` (move fresh done too) and `prune --hard` (irreversible) stay manual.
 
+**Source-aware stale-active reap (v0.6.0):** producers can leave tracked todos
+`open`/`in_progress` forever when a worker dies before reporting a terminal
+status. On `session_start`, armory-todo now self-heals configured producer
+sources: stale `armory-fleet` todos (default: untouched for 2d) become
+`cancelled` and move directly to the archive, where `restore <id>` works
+immediately. Real/manual todos are never auto-mutated; non-policy active todos
+untouched for 14d get an advisory `ORPHAN` health flag and ⌛ panel marker.
+Both thresholds are editable in the Config tab. Expected live→archive drops
+keep rolling backup, drop-snapshot, and audit protection without emitting a
+false wipe alert.
+
 The only irreversible action is `prune --hard` (hard-prune) — it requires an
 explicit `confirm: true` and is always user-confirmed. See **Self-awareness**
 below.
@@ -87,7 +99,7 @@ below.
 ~/.pi/agent/todo/
   todo.json              # active + parked
   todo-archive.json      # done + cancelled (sealed history)
-  todo.config.json       # prune ages + health thresholds
+  todo.config.json       # prune/health/reap thresholds + notify settings
 ```
 
 A v1 single-file store at `~/.pi/agent/todo.json` is migrated automatically on
@@ -136,6 +148,47 @@ Three caps keep the store (and its auto-injected prompt block) from bloating sil
 
 **Backwards-compat:** zero migration (store v3, config v1, registry v1 unchanged in shape). Oversize notes grandfathered. The `maxOpen` advisory→enforced graduation is a documented behavior change for any v0.4.0 user who set a slot (the block message tells them how to raise/clear).
 
+## Agent-validated triage (`/todo triage`)
+
+Rules alone can't clean a store that accretes agent-run debris, stale backlog,
+and prune hesitation. Triage adds judgment: one command that gathers
+candidates, has the agent validate each against a versioned rubric, and closes
+nothing without an explicit batch approval.
+
+```
+/todo triage [scope] [--yes]
+  1. GATHER   stale(30d) + orphans(14d) + over-cap projects + agent-source items
+  2. VALIDATE agent checks each candidate (read-only git/gh/npm probes — rubric ships in-package: src/triage-prompt.ts)
+  3. PROPOSE  table: verdict + evidence + confidence
+  4. APPROVE  one batch confirm — nothing mutates before it (the load-bearing gate)
+  5. EXECUTE  close(cancel) / park / keep → one prune --all sweep (reversible)
+  6. FILE     each closed item as a CLOSED issue in the private getpipher/todo-ledger
+  7. REPORT   before/after counts, filed links, anything deferred
+```
+
+Safety rails (the point of the feature):
+
+- **No silent close, ever.** The agent classifies; only the user's batch
+  approval mutates. `--yes` (`autoSafe:true`) executes ONLY the mechanical safe
+  class — fleet-run prompt debris (prompt-shaped title + agent context) — and
+  still reports what it closed. Unverifiable items stay proposals; zero
+  false-closes is the success metric.
+- **The ledger never blocks.** Issues are matched by client-side title search
+  (idempotent — GitHub's search index lags fresh issues), created then PATCHed
+  closed, labeled `todo-archive` + `project/<name>` + `verdict/cancel`, and
+  embed the full original note. gh down → items archive locally anyway and the
+  skip is reported; `TODO_TRIAGE_SKIP_FILING=1` forces that path (air-gapped
+  runs). `TODO_LEDGER_REPO` overrides the repo for scratch runs.
+- **The rubric is versioned** (`triage-rubric/v1`) and ships in the package —
+  judgment quality evolves deliberately, not per-session.
+- Composes with the existing machinery: thresholds come from
+  `health.activeStaleDays` / `reap.orphanFlagAfterDays`, over-cap from the
+  registry, and reap-policy sources stay owned by the v0.6.0 auto-reap.
+
+A Triage tab in the interactive panel is planned for v2; today the loop runs
+through the agent (the tool returns the candidates + rubric, the agent
+validates and proposes, you approve, one `approve:[…]` call executes + files).
+
 ## Interactive panel (SPEC-3)
 
 Run `/todo` (no arg) in a TUI session to open the interactive triage panel:
@@ -177,6 +230,7 @@ Typed subcommands (`/todo park <id>`, `/todo prune`, etc.) all still work alongs
 /todo prune --hard        permanent deletion (interactive confirm prompt)
 /todo archive [filter]   archive summary, or filtered slice (project:X / text:Y)
 /todo health              bloat report across all boxes + flags + suggestions
+/todo triage [scope] [--yes]  agent-validated prune: gather → validate → propose → approve → close/park → file to ledger
 /todo clean              clear all done (deprecated — use prune)
 /todo path               show the store file path
 ```
@@ -196,6 +250,7 @@ Typed subcommands (`/todo park <id>`, `/todo prune`, etc.) all still work alongs
 | `restore` | `id` | bring an archived TODO back as open |
 | `health` | (none) | bloat report across active/parked/archive + flags + suggestions |
 | `prune` (hard) | `hard:true`, `confirm:true`, `box?`, `olderThan?`, `project?`, `tag?` | PERMANENT deletion — the only irreversible action |
+| `triage` | `scope?`, `autoSafe?`, `approve?: [{id, verdict, reason?, evidence?, confidence?, survivorId?}]` | two-phase agent-validated prune: bare call gathers candidates + returns the versioned rubric (nothing mutates); `autoSafe` executes ONLY mechanical debris; `approve` executes the user-approved batch, sweeps the archive, and files closed items to the private ledger
 | `clear` | `status?` (default `done`) | bulk-clear a status (deprecated — use prune) |
 
 Each TODO carries `id, title (≤120 chars), notes (any length), project, tags, priority (low|med|high|critical), status (open|in_progress|parked|done|cancelled), source, createdAt, updatedAt, closedAt`. The auto-injected block + list/panel show `title` only; `notes` is read via `get` and never injected.
@@ -206,9 +261,11 @@ Each TODO carries `id, title (≤120 chars), notes (any length), project, tags,
 - **`todo` tool** — model CRUD + lifecycle (above).
 - **`/todo` command** — human triage (above).
 - **Auto-inject** — on every `before_agent_start`, a compact `## Open TODOs (N)` block (titles + ids, sorted by priority) is appended to the system prompt, so the agent starts every turn already aware of pending work. The block is **cap-aware** (v0.5.0): under `health.activeMaxOpen` (default 15) it lists the rows; **over** the cap it collapses to a lean summary (counts + over-budget projects + a `todo list` pointer) so the prompt stays bounded when the store bloats. Only `open` + `in_progress` are injected — `parked` and archived todos are excluded (the lifecycle-box boundary). Mutations refresh it on the next turn.
+- **Source-aware safety protocol** — on `session_start`, policy-source stale actives (default `armory-fleet` >2d) move live→archive as immediately-restorable `cancelled` records. Non-policy stale actives are flagged only; never mutated. The Archive tab reports the cumulative number of auto-reaped runs.
 - **Archive query** — `list` with `archived:true` is summary-first (counts by project + month) then filtered/paginated on demand, so a large archive never bloats a single query.
 
 Full design + decisions:
+- v0.6.0 (source-aware reap safety protocol): [`docs/superpowers/specs/2026-07-29-reap-safety-protocol-design.md`](docs/superpowers/specs/2026-07-29-reap-safety-protocol-design.md)
 - v0.4.0 (project-scope management): [`docs/superpowers/specs/2026-07-21-project-scope-management-design.md`](docs/superpowers/specs/2026-07-21-project-scope-management-design.md)
 - v0.3.1 (auto-prune + unified Done view): [`docs/superpowers/specs/2026-07-21-auto-prune-done-view-design.md`](docs/superpowers/specs/2026-07-21-auto-prune-done-view-design.md)
 - v0.3.0 (title + notes split): [`docs/superpowers/specs/2026-07-21-title-notes-split-design.md`](docs/superpowers/specs/2026-07-21-title-notes-split-design.md)
@@ -230,15 +287,25 @@ Full design + decisions:
   "health": { "activeMaxOpen": 15, "activeStaleDays": 30, "parkedMax": 10,
               "parkedStaleDays": 60, "archiveMax": 200, "archiveOldDays": 180,
               "perProjectDefaultMax": 8, "maxNotesBytes": 8192 },
-  "notify": { "sessionStartCount": true }
+  "notify": { "sessionStartCount": true },
+  "reap": {
+    "orphanFlagAfterDays": 14,
+    "policy": { "armory-fleet": { "reapAfterDays": 2, "reapTo": "cancelled" } }
+  }
 }
 ```
 
 | `notify.*` | default | purpose |
 |---|---|---|
-| `sessionStartCount` | `true` | Show the `armory-todo: N open TODOs` startup line. Set `false` to silence it — safety messages (wipe-recovery alert, auto-prune undo info) still surface. |
+| `sessionStartCount` | `true` | Show the `armory-todo: N open TODOs` startup line. Set `false` to silence it — safety messages (wipe recovery, auto-prune, reap) still surface. |
+
+| `reap.*` | default | purpose |
+|---|---:|---|
+| `orphanFlagAfterDays` | `14` | Advisory ORPHAN threshold for active todos whose source is not auto-reaped; never mutates them. |
+| `policy.armory-fleet.reapAfterDays` | `2` | Move stale fleet-tracked active todos directly to archive as cancelled. |
+| `policy.armory-fleet.reapTo` | `cancelled` | Fixed reversible terminal status; `done` is intentionally unsupported. |
 
-Run the store tests: `npm test` (315/315 across 11 suites).
+Run the store tests: `npm test` (497/497 across 15 suites).
 
 ## Known issues