@getpipher/armory-todo 0.6.0 → 0.7.0

package/README.md

@@ -148,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:
@@ -189,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
 ```
@@ -208,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.

package/extensions/todo.ts

@@ -40,12 +40,21 @@ import { hardPrune } from "../src/hard-prune";
 import { TodoPanel } from "../src/panel";
 import { autoPruneOnSessionStart } from "../src/auto-prune";
 import { reapStaleActive } from "../src/reap";
+import {
+  gatherCandidates,
+  executeTriage,
+  executeSafeClass,
+  renderProposalTable,
+  renderReport,
+  type TriageDecision,
+} from "../src/triage";
+import { buildTriagePrompt, TRIAGE_PROMPT_VERSION } from "../src/triage-prompt";
 import { loadConfig, type TodoConfig } from "../src/config";
 import { projectsOverview } from "../src/projects";
 import { renameProject } from "../src/registry";
 import { readAndClearWipeAlert } from "../src/backup";
 
-const ACTIONS = ["list", "add", "update", "get", "complete", "delete", "clear", "park", "prune", "restore", "health", "projects", "project_rename"] as const;
+const ACTIONS = ["list", "add", "update", "get", "complete", "delete", "clear", "park", "prune", "restore", "health", "projects", "project_rename", "triage"] as const;
 
 function fmt(t: ReturnType<typeof listTodos>[number]): string {
   const tag = t.project ? ` (${t.project})` : "";
@@ -187,6 +196,7 @@ export default function (pi: ExtensionAPI) {
       "Use todo (action:'prune', hard:true, confirm:true, box?, olderThan?) for PERMANENT deletion (the only irreversible action). ALWAYS run health first, show the user the report + the exact proposed command, and wait for an explicit yes before passing confirm:true. Never hard-prune without explicit user confirmation.",
       "Use todo (action:'projects') for a per-project scope overview (open/in_progress/parked/done counts + maxOpen + OVER/?typo markers). Run when the user asks 'which projects have open work' or to see backlog shape by project.",
       "Use todo (action:'project_rename', oldName, newName) to rename or merge a project (rewrites live + archive + registry). Use it to fix typo'd project strings (e.g. foo-bat → foo-bar). Rename onto an existing name merges (consolidates the old project into the new). Per-project maxOpen caps are ENFORCED (block-on-add); they also drive a PROJECT_OVER health flag when breached.",
+      "Use todo (action:'triage') for agent-validated pruning: phase 1 gathers candidates (stale 30d + orphans 14d + over-cap projects + agent-source debris) and returns them with the versioned rubric — NOTHING mutates. Validate each candidate with read-only probes (git log / gh / npm view), present the proposal table (verdict + evidence + confidence), get ONE batch approval from the user, then call phase 2: todo(action:'triage', approve:[{id, verdict:'close'|'park'|'keep', reason?, evidence?, confidence?, survivorId?}]). Closed items are archived (reversible) and filed as CLOSED issues in the private getpipher/todo-ledger. autoSafe:true (--yes) executes ONLY the mechanical safe class (fleet-run prompt debris) — never auto-close anything you could not verify (zero false-closes). Scope with scope:'<project>'.",
     ],
     parameters: Type.Object({
       action: StringEnum(ACTIONS),
@@ -218,6 +228,19 @@ export default function (pi: ExtensionAPI) {
       // project actions (v0.4.0)
       oldName: Type.Optional(Type.String({ description: "project_rename: current project name" })),
       newName: Type.Optional(Type.String({ description: "project_rename: new project name (merge if it already exists)" })),
+      // triage (PRD 2026-08-30) — two phases within one action:
+      //   phase 1 (no approve): gather candidates + return the versioned rubric. NOTHING mutates.
+      //   phase 2 (approve): execute exactly the approved decisions, then file closed items to the ledger.
+      scope: Type.Optional(Type.String({ description: "triage: restrict candidates to one project name (empty = all)" })),
+      autoSafe: Type.Optional(Type.Boolean({ description: "triage (--yes): auto-execute ONLY the mechanical safe class (fleet-run prompt debris). Everything else stays a proposal — never auto-closed (D2)." })),
+      approve: Type.Optional(Type.Array(Type.Object({
+        id: Type.String({ description: "Candidate todo id (td-…)" }),
+        verdict: StringEnum(["close", "park", "keep"] as const),
+        reason: Type.Optional(Type.String({ description: "close only: debris | duplicate | stale-unverified | verified-shipped" })),
+        evidence: Type.Optional(Type.String({ description: "One CHECKED line (git/gh/npm probe result). Required for verified-shipped closes." })),
+        confidence: Type.Optional(StringEnum(["high", "medium", "low"] as const)),
+        survivorId: Type.Optional(Type.String({ description: "duplicate closes: the surviving todo id" })),
+      }), { description: "triage phase 2: the user-approved decisions. Executes exactly these; nothing else." })),
     }),
     async execute(_toolCallId, params) {
       try {
@@ -391,6 +414,44 @@ export default function (pi: ExtensionAPI) {
             const r = renameProject(params.oldName, params.newName);
             return { content: [{ type: "text" as const, text: `Renamed ${params.oldName} → ${r.newName}: ${r.liveRenamed} live + ${r.archivedRenamed} archived${r.merged ? " (merged)" : ""}` }] };
           }
+          case "triage": {
+            // Phase 2: execute exactly the user-approved decisions (D2 gate).
+            if (params.approve?.length) {
+              const before = gatherCandidates(params.scope).before;
+              const report = await executeTriage(params.approve as TriageDecision[]);
+              return { content: [{ type: "text" as const, text: renderReport(report, before) }] };
+            }
+            // Phase 1: gather + propose. NOTHING mutates unless autoSafe (--yes),
+            // which executes ONLY the mechanical safe class (fleet-run debris).
+            let safeMsg = "";
+            if (params.autoSafe) {
+              const { report, remaining } = await executeSafeClass(params.scope);
+              safeMsg = report
+                ? `--yes executed the safe class ONLY (fleet-run debris). Everything else needs the batch approval.\n\n${renderReport(report)}\n`
+                : "--yes: no mechanical-safe debris found — nothing auto-closed.\n";
+              if (report && remaining === 0) {
+                return { content: [{ type: "text" as const, text: safeMsg + "No remaining candidates — triage complete." }] };
+              }
+            }
+            const g = gatherCandidates(params.scope);
+            if (g.candidates.length === 0) {
+              return { content: [{ type: "text" as const, text: `${safeMsg}${safeMsg ? "\n" : ""}Triage: no candidates (before: ${g.before.active} active / ${g.before.parked} parked / ${g.before.archive} archive${g.scope ? `, scope: ${g.scope}` : ""}). Nothing to propose, nothing mutated.` }] };
+            }
+            const lines = [
+              `## Triage — proposal (NOTHING mutated yet)`,
+              `before: ${g.before.active} active / ${g.before.parked} parked / ${g.before.archive} archive${g.scope ? ` · scope: ${g.scope}` : ""} · candidates: ${g.candidates.length} · rubric ${TRIAGE_PROMPT_VERSION}`,
+              "",
+              renderProposalTable(g),
+              "",
+              safeMsg,
+              `Validate each candidate against the rubric below (read-only probes: git log, gh, npm view — checked, not guessed). Then present the proposal table (verdict + evidence + confidence) to the user and get ONE batch approval. On approval execute all decisions in a single call:`,
+              `  todo(action:"triage", approve:[{ id, verdict:"close"|"park"|"keep", reason?, evidence?, confidence?, survivorId? }, ...])`,
+              `Safety: close needs reason (debris|duplicate|stale-unverified|verified-shipped); duplicate needs survivorId; verified-shipped needs evidence. Items you cannot verify stay proposals — zero false-closes is the metric. The safe-class column marks what --yes may close WITHOUT approval.`,
+              "",
+              buildTriagePrompt(g.candidates, g.scope),
+            ];
+            return { content: [{ type: "text" as const, text: lines.filter((l) => l !== "").join("\n") }] };
+          }
           default:
             return { content: [{ type: "text" as const, text: `Unknown action: ${params.action}` }] };
         }
@@ -406,7 +467,7 @@ export default function (pi: ExtensionAPI) {
       "Global cross-session TODO list. " +
       "/todo / /todo all / /todo add <title> / /todo done <id> / /todo rm <id> / " +
       "/todo park <id> / /todo restore <id> / /todo prune [--all|--hard --box <b> --older-than <d>] / " +
-      "/todo archive [project:X|text:Y] / /todo finished / /todo projects / /todo health / /todo clean / /todo path",
+      "/todo archive [project:X|text:Y] / /todo finished / /todo projects / /todo health / /todo triage [scope] [--yes] / /todo clean / /todo path",
     handler: async (args, ctx) => {
       const a = (args ?? "").trim();
       const [sub, ...rest] = a.split(/\s+/);
@@ -483,6 +544,33 @@ export default function (pi: ExtensionAPI) {
           }
           return;
         }
+        if (sub === "triage") {
+          // Thin mirror of todo(action:'triage') — humans get the proposal table;
+          // the validation loop runs through the agent (rubric ships in-package).
+          const yes = rest.includes("--yes");
+          const scopeArg = rest.find((r) => !r.startsWith("--"));
+          let safeMsg = "";
+          if (yes) {
+            const { report, remaining } = await executeSafeClass(scopeArg);
+            safeMsg = report ? renderReport(report) + `\nremaining candidates: ${remaining}\n` : "--yes: no mechanical-safe debris — nothing auto-closed.\n";
+          }
+          const g = gatherCandidates(scopeArg);
+          const head = `Triage (before: ${g.before.active} active / ${g.before.parked} parked / ${g.before.archive} archive${scopeArg ? `, scope: ${scopeArg}` : ""})`;
+          if (g.candidates.length === 0) {
+            if (ctx.hasUI) ctx.ui.notify(`${head}\n${safeMsg || "No candidates — nothing to propose, nothing mutated."}`, "info");
+            return;
+          }
+          const msg = [
+            head,
+            safeMsg,
+            `candidates (${g.candidates.length}) — NOTHING mutated${yes ? " beyond the safe class above" : ""}:`,
+            renderProposalTable(g),
+            "",
+            `Ask the agent to validate these against the triage rubric (${TRIAGE_PROMPT_VERSION}) using read-only probes, then approve the batch. The agent executes via todo(action:"triage", approve:[…]); closed items are filed to ${"getpipher/todo-ledger"} (private).`,
+          ].filter((l) => l !== "").join("\n");
+          if (ctx.hasUI) ctx.ui.notify(msg, "info");
+          return;
+        }
         if (sub === "health") {
           const report = healthReport();
           const projLines = report.projects.length

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@getpipher/armory-todo",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "description": "Global, cross-session TODO for pi \u2014 persists across all sessions and is auto-injected into every prompt. The disk-backed counterpart to branch-scoped pi todo extensions.",
   "keywords": [
     "pi-package",
@@ -41,7 +41,7 @@
     ]
   },
   "scripts": {
-    "test": "for t in todo-store todo-title-notes todo-archive todo-config todo-migrate todo-health todo-hard-prune todo-auto-prune registry projects panel-data todo-caps todo-backup todo-reap public-api; do node test/$t.test.mts || exit 1; done"
+    "test": "for t in todo-store todo-title-notes todo-archive todo-config todo-migrate todo-health todo-hard-prune todo-auto-prune registry projects panel-data todo-caps todo-backup todo-reap triage public-api; do node test/$t.test.mts || exit 1; done"
   },
   "peerDependencies": {
     "@earendil-works/pi-ai": "*",

package/src/triage-prompt.ts

@@ -0,0 +1,81 @@
+// The /todo triage validation rubric — a VERSIONED PROMPT CONSTANT.
+//
+// PRD ("The pipeline", stage 2): the agent prompt for the VALIDATE stage ships
+// IN the package, not improvised per session — so the rubric evolves
+// deliberately (bump TRIAGE_PROMPT_VERSION + tests when changing it) and every
+// triage run, in any session, judges against the same contract.
+//
+// The rubric is derived from PRD §D3 (which itself was distilled from the
+// 2026-08-30 manual triage). Evidence must be CHECKED (read-only git/gh/npm
+// probes), never guessed. D2 is restated here because it is load-bearing:
+// nothing mutates before the batch approval; the caller (extension) enforces
+// it mechanically — the prompt is the judgment-side half of the same gate.
+
+import type { Candidate } from "./triage.ts";
+
+export const TRIAGE_PROMPT_VERSION = "triage-rubric/v1";
+
+export const TRIAGE_RUBRIC = `## Triage rubric (${TRIAGE_PROMPT_VERSION})
+
+You are validating TODO-triage candidates. For EACH candidate, judge it against
+this rubric and produce one decision. Work top to bottom; do not skip rows.
+
+### Verdicts
+
+| Signal (checked, not guessed) | Verdict |
+|---|---|
+| source is an agent/fleet run, title is a subagent prompt, and the project work is verifiably merged/released | close (reason: debris) |
+| near-identical title/body to another LIVE todo in the same project | close (reason: duplicate) — name the surviving id |
+| done-able in <5 minutes, or explicitly deadline-bound | keep — surface it to the owner in your summary |
+| real work, low priority, no date | park |
+| stale >=30d and you could NOT verify anything | close (reason: stale-unverified) — this stays a proposal for the human |
+| fresh, in_progress, or produced by a configured auto-reap source | (never a candidate — the engine already excluded these) |
+
+### Evidence rules (D3 — checked, not guessed)
+
+- Use READ-ONLY probes only: \`git -C <repo> log --oneline -10\`,
+  \`gh run list -R <org>/<repo> --limit 3\`, \`npm view <pkg> version\`,
+  \`gh pr list -R <org>/<repo> --state merged --search <title>\`.
+- NEVER run mutating commands during validation (no push, no gh issue create,
+  no npm publish). Filing happens later, mechanically, by the tool.
+- One line of evidence per decision. If you found nothing, say what you
+  checked: "git log + npm view @x/y — no trace of the described work".
+- Confidence: high = direct proof (merged PR / published version); medium =
+  strong indirect (branch gone, issue closed by commit); low = judgment call.
+
+### Safety contract (D2 — load-bearing)
+
+- You NEVER mutate anything. Your output is proposals only.
+- The tool executes strictly what the user approves in the batch confirm.
+- A todo you cannot verify is a PROPOSAL, never an auto-close. Zero
+  false-closes is the success metric: a closed item that had to be restored
+  is a rubric bug.
+
+### Output contract
+
+Return one decision object per candidate, in order:
+
+{ "id": "<td-...>", "verdict": "close" | "park" | "keep",
+  "reason": "debris" | "duplicate" | "stale-unverified" | "verified-shipped",  // close only
+  "evidence": "<one checked line>",
+  "confidence": "high" | "medium" | "low",
+  "survivorId": "<td-...>" }   // duplicate only
+
+Then present the full proposal table (id / title / project / verdict /
+evidence / confidence) to the user and wait for ONE batch approval. On
+approval, submit all decisions in a single
+todo(action:"triage", approve:[...]) call.`;
+
+/** Compose the full agent prompt: rubric + the concrete candidate rows. */
+export function buildTriagePrompt(candidates: Candidate[], scope?: string): string {
+  const rows = candidates.map((c) => {
+    const cats = c.categories.join("+");
+    return `- [${c.todo.id}] (${c.todo.project || "no project"}, age ${c.ageDays}d, ${cats}${c.mechanicalSafe ? ", mechanical-safe" : ""}) ${c.todo.title}`;
+  });
+  return [
+    TRIAGE_RUBRIC,
+    "",
+    `## Candidates (${candidates.length}${scope ? `, scope: ${scope}` : ""})`,
+    rows.join("\n"),
+  ].join("\n");
+}

package/src/triage.ts

@@ -0,0 +1,474 @@
+// /todo triage engine (PRD: agent-validated pruning + GH ledger) — v1 thin slice.
+//
+// Pipeline: GATHER -> VALIDATE (agent, rubric in triage-prompt.ts) -> PROPOSE
+// -> APPROVE (batch) -> EXECUTE (cancel/park/keep + prune --all sweep) -> FILE
+// (private ledger repo, idempotent, non-blocking) -> REPORT.
+//
+// Composition rules (PRD "Non-goals" + repo conventions):
+//   - Staleness thresholds come from the EXISTING config: health.activeStaleDays
+//     (30d) and reap.orphanFlagAfterDays (14d). No new config knobs, no
+//     duplicated semantics.
+//   - in_progress todos are NEVER candidates (D3: fresh/in_progress/policy-source
+//     stay untouched). Policy auto-reap sources are owned by reap.ts — triage
+//     never treats them as mechanical debris.
+//   - D2: nothing mutates before a batch approval — except --yes, which executes
+//     ONLY the mechanical safe class (fleet-run prompt debris). Everything else,
+//     including verified-shipped closes, goes through `approve`.
+//   - D4: ledger filing is idempotent (search "td-<id> in:title" first, issues
+//     are created CLOSED) and NEVER blocking — a gh failure archives locally
+//     and is reported as skipped. The gh runner is dependency-injected so tests
+//     stay hermetic (no network, no live store).
+
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import { loadStore, updateTodo, type Todo } from "./todo-store.ts";
+import { loadArchive, pruneTodos } from "./archive.ts";
+import { loadConfig } from "./config.ts";
+import { loadRegistry } from "./registry.ts";
+import { overBudgetProjects } from "./caps.ts";
+
+const execFileP = promisify(execFile);
+
+const DAY = 86_400_000;
+
+/** Private ledger repo (D4 — TODO notes are sensitive; never a public repo).
+ *  Production default: getpipher/todo-ledger. TODO_LEDGER_REPO env override
+ *  exists for scratch/manual runs against a throwaway repo — resolved at call
+ *  time so a long-lived session picks it up. */
+export const TRIAGE_LEDGER_REPO_DEFAULT = "getpipher/todo-ledger";
+export function ledgerRepo(): string {
+  return process.env.TODO_LEDGER_REPO || TRIAGE_LEDGER_REPO_DEFAULT;
+}
+
+// ---------------------------------------------------------------------------
+// Types
+
+export type TriageVerdict = "close" | "park" | "keep";
+export type CloseReason = "debris" | "duplicate" | "stale-unverified" | "verified-shipped";
+export type Confidence = "high" | "medium" | "low";
+
+export type GhRunner = (args: string[]) => Promise<{ code: number; stdout: string; stderr: string }>;
+
+export interface Candidate {
+  todo: Todo;
+  /** Which gather categories matched: stale-30d / orphan-14d / agent-source / over-cap-project. */
+  categories: string[];
+  /** Age by updatedAt, whole days down. */
+  ageDays: number;
+  /** Mechanical safe class (D2 --yes): fleet-run prompt debris, closable without judgment. */
+  mechanicalSafe: boolean;
+}
+
+export interface GatherResult {
+  scope?: string;
+  before: { active: number; parked: number; archive: number };
+  candidates: Candidate[];
+  overCapProjects: { name: string; open: number; maxOpen: number }[];
+  staleDays: number;
+  orphanDays: number;
+}
+
+export interface TriageDecision {
+  id: string;
+  verdict: TriageVerdict;
+  reason?: CloseReason;
+  evidence?: string;
+  confidence?: Confidence;
+  /** duplicate closes: the todo that survives. */
+  survivorId?: string;
+}
+
+export interface LedgerFiling {
+  id: string;
+  status: "filed" | "skipped-existing" | "skipped-gh-error" | "skipped-duplicate-id";
+  url?: string;
+  error?: string;
+}
+
+export interface TriageReport {
+  closed: { id: string; title: string; project: string }[];
+  parked: { id: string; title: string; project: string }[];
+  kept: { id: string; title: string }[];
+  /** Items rejected before any mutation (bad id, not open, invalid decision). */
+  rejected: { id: string; error: string }[];
+  pruned: number;
+  filings: LedgerFiling[];
+  after: { active: number; parked: number; archive: number };
+}
+
+export interface TriageOptions {
+  /** Dependency-injected gh runner (tests). Default: real `gh` CLI. */
+  gh?: GhRunner;
+  /** Skip ledger filing entirely (hermetic runs that must not touch gh).
+  *  Also honored via TODO_TRIAGE_SKIP_FILING=1 (air-gapped / offline runs —
+  *  D4: pruning must never depend on the network). */
+  skipFiling?: boolean;
+}
+
+// ---------------------------------------------------------------------------
+// Gather (pure read — no mutation, no config writes)
+
+/** Prompt-shaped title: fleet runs auto-track subagent PROMPTS as titles
+ *  ("You are COMPLETING Task 9: ...", "[general-purpose] You are ...").
+ *  Deliberately narrow — a human-written title rarely starts this way, and
+ *  zero false-closes is the success metric. */
+export function isPromptShapedTitle(title: string): boolean {
+  return /^you (are|'re|will|r)\b/i.test(title) || /^\[[\w.-]+\]\s/.test(title);
+}
+
+/** Agent context: a source/project/tag that names an agent-run producer.
+ *  Reap-policy sources are excluded upstream — reap.ts owns those. */
+function hasAgentContext(todo: Todo): boolean {
+  const hay = [todo.source, todo.project, ...todo.tags].join(" ").toLowerCase();
+  return /\b(fleet|agent|subagent|run)\b/.test(hay);
+}
+
+/** Mechanical safe class (D2 --yes): prompt-shaped debris with agent context.
+ *  Policy auto-reap sources never qualify — reap.ts already owns them. */
+export function isMechanicalSafe(todo: Todo, policySources: Set<string>): boolean {
+  if (todo.status !== "open") return false;
+  if (policySources.has(todo.source)) return false;
+  return isPromptShapedTitle(todo.title) && hasAgentContext(todo);
+}
+
+/** GATHER: stale(30d) + orphans(14d) + over-cap projects + agent-source items.
+ *  Pure read: loads store/config/registry, mutates nothing, persists nothing. */
+export function gatherCandidates(scope?: string): GatherResult {
+  const config = loadConfig();
+  const staleDays = config.health.activeStaleDays;
+  const orphanDays = config.reap.orphanFlagAfterDays;
+  const policySources = new Set(Object.keys(config.reap.policy));
+
+  const store = loadStore();
+  const archiveCount = loadArchive().todos.length;
+  const active = store.todos.filter((t) => t.status === "open" || t.status === "in_progress");
+  const parked = store.todos.filter((t) => t.status === "parked");
+
+  // Over-cap projects (advisory registry caps — same definition as health PROJECT_OVER).
+  const registry = loadRegistry();
+  const overCap = overBudgetProjects(store.todos, registry);
+
+  const now = Date.now();
+  const candidates: Candidate[] = [];
+
+  for (const todo of store.todos) {
+    if (todo.status !== "open") continue; // D3: in_progress/parked/terminal — untouched
+    if (policySources.has(todo.source)) continue; // D3: policy-source — reap.ts owns them
+    if (scope && todo.project !== scope) continue;
+
+    const ageDays = Math.floor((now - Date.parse(todo.updatedAt)) / DAY);
+    const categories: string[] = [];
+    if (ageDays > staleDays) categories.push("stale-30d");
+    if (!policySources.has(todo.source) && ageDays >= orphanDays) categories.push("orphan-14d");
+    if (hasAgentContext(todo) && ageDays >= orphanDays) categories.push("agent-source");
+    if (overCap.some((p) => p.name === todo.project && todo.status === "open")) categories.push("over-cap-project");
+    if (categories.length === 0) continue;
+
+    candidates.push({ todo, categories, ageDays, mechanicalSafe: isMechanicalSafe(todo, policySources) });
+  }
+
+  return {
+    scope,
+    before: { active: active.length, parked: parked.length, archive: archiveCount },
+    candidates,
+    overCapProjects: overCap,
+    staleDays,
+    orphanDays,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Execute (the ONLY mutation path — behind an explicit decision list)
+
+const CLOSE_REASONS: CloseReason[] = ["debris", "duplicate", "stale-unverified", "verified-shipped"];
+
+function validateDecisions(decisions: TriageDecision[]): { id: string; error: string }[] {
+  const errors: { id: string; error: string }[] = [];
+  decisions.forEach((d, i) => {
+    const label = d.id || `decisions[${i}]`;
+    if (!d.verdict || !["close", "park", "keep"].includes(d.verdict)) {
+      errors.push({ id: label, error: `invalid verdict "${String(d.verdict)}" (close|park|keep)` });
+      return;
+    }
+    if (d.verdict === "close") {
+      if (!d.reason || !CLOSE_REASONS.includes(d.reason)) {
+        errors.push({ id: label, error: `close requires reason (${CLOSE_REASONS.join("|")})` });
+        return;
+      }
+      if (d.reason === "duplicate" && !d.survivorId) {
+        errors.push({ id: label, error: `duplicate close requires survivorId` });
+        return;
+      }
+      if (d.reason === "verified-shipped" && !d.evidence) {
+        errors.push({ id: label, error: `verified-shipped close requires evidence` });
+        return;
+      }
+    }
+  });
+  return errors;
+}
+
+/** EXECUTE + FILE + REPORT (PRD pipeline steps 5-7).
+ *
+ *  Mutates exactly the approved decisions: close -> cancelled, park -> parked,
+ *  keep -> untouched. Then one `prune --all` sweep (closed items enter the
+ *  archive — reversible), then ledger filing for the closed set (idempotent,
+ *  never blocking), then the before/after report. Snapshots are taken BEFORE
+ *  mutation so filing carries the full original note even after the sweep.
+ *
+ *  Per-item rejections (unknown id, not open, malformed decision) never abort
+ *  the batch — they land in `rejected` and the rest executes. */
+export async function executeTriage(decisions: TriageDecision[], opts: TriageOptions = {}): Promise<TriageReport> {
+  const rejected = validateDecisions(decisions);
+  const rejectedIds = new Set(rejected.map((r) => r.id));
+
+  const store = loadStore();
+  const before = {
+    active: store.todos.filter((t) => t.status === "open" || t.status === "in_progress").length,
+    parked: store.todos.filter((t) => t.status === "parked").length,
+    archive: loadArchive().todos.length,
+  };
+
+  const closed: TriageReport["closed"] = [];
+  const parked: TriageReport["parked"] = [];
+  const kept: TriageReport["kept"] = [];
+  const snapshots = new Map<string, Todo>();
+
+  for (const d of decisions) {
+    if (rejectedIds.has(d.id)) continue;
+    const todo = loadStore().todos.find((t) => t.id === d.id);
+    if (!todo) {
+      rejected.push({ id: d.id, error: `no todo with id ${d.id}` });
+      continue;
+    }
+    if (todo.status !== "open") {
+      rejected.push({ id: d.id, error: `not open (status: ${todo.status}) — triage only rules on open items` });
+      continue;
+    }
+    if (d.verdict === "keep") {
+      kept.push({ id: d.id, title: todo.title });
+      continue;
+    }
+    // Snapshot before mutation — filing needs the full original record.
+    snapshots.set(d.id, { ...todo });
+    if (d.verdict === "close") {
+      updateTodo(d.id, { status: "cancelled" });
+      closed.push({ id: d.id, title: todo.title, project: todo.project });
+    } else {
+      updateTodo(d.id, { status: "parked" });
+      parked.push({ id: d.id, title: todo.title, project: todo.project });
+    }
+  }
+
+  // Reversible sweep: everything terminal in the live store enters the archive.
+  let pruned = 0;
+  if (closed.length > 0) {
+    pruned = pruneTodos({ all: true }).moved;
+  }
+
+  // FILE — closed items only, idempotent, never blocking (D4).
+  const filings: LedgerFiling[] = [];
+  if (closed.length > 0 && !opts.skipFiling && process.env.TODO_TRIAGE_SKIP_FILING !== "1") {
+    const gh = opts.gh ?? defaultGhRunner;
+    for (const item of closed) {
+      const snapshot = snapshots.get(item.id)!;
+      const decision = decisions.find((d) => d.id === item.id)!;
+      filings.push(await fileClosedTodo(gh, snapshot, decision));
+    }
+  }
+
+  const afterStore = loadStore();
+  const after = {
+    active: afterStore.todos.filter((t) => t.status === "open" || t.status === "in_progress").length,
+    parked: afterStore.todos.filter((t) => t.status === "parked").length,
+    archive: loadArchive().todos.length,
+  };
+
+  return { closed, parked, kept, rejected, pruned, filings, after };
+}
+
+/** --yes path (D2): execute ONLY the mechanical safe class. Everything else
+ *  stays a proposal. Scope-filtered when a scope is given. Returns the report
+ *  plus the remaining (unexecuted) candidate count. */
+export async function executeSafeClass(scope?: string, opts: TriageOptions = {}): Promise<{ report: TriageReport | null; remaining: number }> {
+  const gather = gatherCandidates(scope);
+  const policySources = new Set(Object.keys(loadConfig().reap.policy));
+  const safe = gather.candidates.filter((c) => isMechanicalSafe(c.todo, policySources));
+  if (safe.length === 0) return { report: null, remaining: gather.candidates.length };
+  const decisions: TriageDecision[] = safe.map((c) => ({
+    id: c.todo.id,
+    verdict: "close",
+    reason: "debris",
+    evidence: "mechanical: fleet-run prompt debris (prompt-shaped title + agent context)",
+    confidence: "high",
+  }));
+  const report = await executeTriage(decisions, opts);
+  return { report, remaining: gather.candidates.length - safe.length };
+}
+
+// ---------------------------------------------------------------------------
+// Ledger filing (D4: private repo, idempotent, created CLOSED, never blocking)
+
+export const defaultGhRunner: GhRunner = async (args) => {
+  try {
+    const { stdout, stderr } = await execFileP("gh", args, { timeout: 20_000, maxBuffer: 4 * 1024 * 1024 });
+    return { code: 0, stdout, stderr };
+  } catch (e) {
+    const err = e as { code?: number; stdout?: string; stderr?: string; message: string };
+    return { code: err.code ?? 1, stdout: err.stdout ?? "", stderr: err.stderr ?? err.message };
+  }
+};
+
+function projectLabel(project: string): string {
+  return `project/${project.trim().replace(/\s+/g, "-").toLowerCase() || "none"}`;
+}
+
+/** Make sure the ledger repo exists (private). Returns null when usable,
+ *  or an error string when gh cannot see/create it (caller skips filing). */
+export async function ensureLedgerRepo(gh: GhRunner): Promise<string | null> {
+  const view = await gh(["repo", "view", ledgerRepo(), "--json", "name,visibility"]);
+  if (view.code === 0) return null;
+  const create = await gh(["repo", "create", ledgerRepo(), "--private"]);
+  if (create.code !== 0) {
+    return `gh cannot see or create ${ledgerRepo()}: ${(create.stderr || view.stderr).trim().slice(0, 200)}`;
+  }
+  return null;
+}
+
+/** Idempotency probe: an existing issue titled with this td-<id> short-circuits creation.
+ *  Client-side title match on a full list — deliberately NOT `--search`, which
+ *  rides GitHub's search index and LAGS fresh issues (proven in smoke: a
+ *  same-second re-file sailed past the probe and created a duplicate). */
+export async function findLedgerIssue(gh: GhRunner, id: string): Promise<string | null> {
+  const res = await gh([
+    "issue", "list", "-R", ledgerRepo(),
+    "--state", "all", "--json", "number,title,url", "--limit", "1000",
+  ]);
+  if (res.code !== 0) return null; // probe failure -> fall through to create attempt; create failing is what skips
+  try {
+    const found = (JSON.parse(res.stdout) as { title: string; url: string }[]).filter((i) => i.title.includes(id));
+    return found.length > 0 ? found[0].url : null;
+  } catch {
+    return null;
+  }
+}
+
+function ledgerBody(todo: Todo, decision: TriageDecision): string {
+  return [
+    `## Archived TODO \`${todo.id}\``,
+    "",
+    `- **project:** ${todo.project || "(none)"}`,
+    `- **closed:** ${todo.closedAt ?? "(unknown)"} as \`${todo.status}\``,
+    `- **close reason:** ${decision.reason ?? "(unspecified)"}`,
+    `- **confidence:** ${decision.confidence ?? "(unspecified)"}`,
+    `- **evidence:** ${decision.evidence || "(none recorded)"}`,
+    decision.survivorId ? `- **duplicate of:** \`${decision.survivorId}\`` : "",
+    "",
+    "### Original title",
+    "",
+    todo.title,
+    "",
+    "### Original notes",
+    "",
+    "```",
+    todo.notes || "(empty)",
+    "```",
+    "",
+    "---",
+    "Filed by `/todo triage` (@getpipher/armory-todo). This is a sealed record, not open work — the issue is intentionally closed.",
+  ].filter((l) => l !== "").join("\n");
+}
+
+/** File one closed todo as a CLOSED issue. Idempotent by title search; every
+ *  failure mode degrades to a `skipped-*` filing — never throws, never blocks
+ *  the local archive (D4). */
+export async function fileClosedTodo(gh: GhRunner, todo: Todo, decision: TriageDecision): Promise<LedgerFiling> {
+  try {
+    const existing = await findLedgerIssue(gh, todo.id);
+    if (existing) return { id: todo.id, status: "skipped-existing", url: existing };
+
+    const repoErr = await ensureLedgerRepo(gh);
+    if (repoErr) return { id: todo.id, status: "skipped-gh-error", error: repoErr };
+
+    const title = `[archive] ${todo.id} ${todo.title}`.slice(0, 220);
+    // D4 verdict labels: triage closes are cancellations (reversible via restore).
+    const labels = ["todo-archive", projectLabel(todo.project), `verdict/${decision.verdict === "close" ? "cancel" : "close"}`];
+    // NOTE: the create-issues REST endpoint has no `state` field — it silently
+    // ignores one (proven in smoke). Create, then PATCH closed.
+    const create = await gh([
+      "api", `repos/${ledgerRepo()}/issues`,
+      "-f", `title=${title}`,
+      "-f", `body=${ledgerBody(todo, decision)}`,
+      ...labels.flatMap((l) => ["-f", `labels[]=${l}`]),
+    ]);
+    if (create.code !== 0) {
+      return { id: todo.id, status: "skipped-gh-error", error: (create.stderr || "gh api failed").trim().slice(0, 200) };
+    }
+    let url = "";
+    let number = 0;
+    try {
+      const parsed = JSON.parse(create.stdout) as { html_url?: string; number?: number };
+      url = parsed.html_url ?? "";
+      number = parsed.number ?? 0;
+    } catch { /* url/number best-effort */ }
+    if (number > 0) {
+      // Records, not work: close immediately. A failed close still files the
+      // record (url below) but flags it — the issue would need a manual close.
+      const close = await gh(["api", "-X", "PATCH", `repos/${ledgerRepo()}/issues/${number}`, "-f", "state=closed"]);
+      if (close.code !== 0) {
+        return { id: todo.id, status: "filed", url: url || undefined, error: `filed but CLOSE FAILED (needs manual close): ${(close.stderr || "patch failed").trim().slice(0, 150)}` };
+      }
+    }
+    return { id: todo.id, status: "filed", url: url || undefined };
+  } catch (e) {
+    return { id: todo.id, status: "skipped-gh-error", error: (e as Error).message.slice(0, 200) };
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Rendering (shared by the tool action + the slash mirror)
+
+export function renderProposalTable(gather: GatherResult): string {
+  const rows = gather.candidates.map((c) => {
+    const proj = c.todo.project || "(none)";
+    const safe = c.mechanicalSafe ? " yes" : "";
+    return `| ${c.todo.id} | ${c.todo.title} | ${proj} | ${c.categories.join("+")} | ${c.ageDays}d |${safe} |`;
+  });
+  return [
+    `| id | title | project | categories | age | safe(--yes) |`,
+    `|---|---|---|---|---|---|`,
+    ...rows,
+  ].join("\n");
+}
+
+export function renderReport(report: TriageReport, before?: GatherResult["before"]): string {
+  const lines: string[] = ["## Triage — executed"];
+  if (before) lines.push(`before: ${before.active} active / ${before.parked} parked / ${before.archive} archive`);
+  if (report.closed.length) {
+    lines.push(`closed (${report.closed.length}):`);
+    for (const c of report.closed) {
+      const filing = report.filings.find((f) => f.id === c.id);
+      const ledger = filing?.status === "filed" ? ` · ledger: ${filing.url}`
+        : filing?.status === "skipped-existing" ? " · ledger: already filed"
+        : filing?.status === "skipped-gh-error" ? ` · ledger: SKIPPED (${filing.error})`
+        : filing?.status === "skipped-duplicate-id" ? " · ledger: skipped (duplicate)"
+        : " · ledger: not filed";
+      lines.push(`  [${c.id}] ${c.title}${c.project ? ` (${c.project})` : ""}${ledger}`);
+    }
+  } else {
+    lines.push("closed: (none)");
+  }
+  if (report.parked.length) {
+    lines.push(`parked (${report.parked.length}): ${report.parked.map((p) => `[${p.id}] ${p.title}`).join(", ")}`);
+  }
+  if (report.kept.length) {
+    lines.push(`kept (${report.kept.length}): ${report.kept.map((k) => `[${k.id}] ${k.title}`).join(", ")}`);
+  }
+  if (report.rejected.length) {
+    lines.push(`rejected (${report.rejected.length}):`);
+    for (const r of report.rejected) lines.push(`  [${r.id}] ${r.error}`);
+  }
+  if (report.closed.length) lines.push(`prune sweep: ${report.pruned} moved to archive (reversible via todo restore <id>)`);
+  lines.push(`after: ${report.after.active} active / ${report.after.parked} parked / ${report.after.archive} archive`);
+  return lines.join("\n");
+}