@getpipher/armory-todo 0.3.0 → 0.4.0

package/docs/superpowers/specs/2026-07-21-auto-prune-done-view-design.md

@@ -0,0 +1,217 @@
+# Workstream v0.3.1 — auto-prune on session_start + unified `Done` view
+
+**Date:** 2026-07-21
+**Status:** Shipped (v0.3.1, PR #5, 2026-07-21)
+**Branch:** `feat/auto-prune-done-view` off `main`
+**Predecessor:** v0.3.0 (title + notes split), shipped 2026-07-21 (PR #4)
+**Target ship:** v0.3.1, auto-published via `release.yml` on `v0.3.1` tag (now also creates a GitHub Release)
+
+---
+
+## 1. Problem
+
+v0.3.0 split title/notes and fixed per-todo injection bloat, but two friction points remain in the *lifecycle* of finished work:
+
+1. **Prune is 100% manual.** Done/cancelled todos sit in the live `todo.json` forever until someone runs `/todo prune`. On a busy stretch they pile up; the `session_start` bloat nudge only *suggests* pruning — it never does it. The user is the prune trigger.
+2. **"Done" is split across two stores after pruning.** Recent done (<7d) lives in the live store; older done lives in `todo-archive.json`. There's no single "show me my finished work" view — you query live and archive separately. The `/todo` panel's Archive tab shows only the archive file (sealed history: done + cancelled), not recent live done.
+
+## 2. Goals
+
+- **Auto-prune:** done/cancelled todos older than `config.prune.defaultAgeDays` (default 7d) archive *themselves* on `session_start`, without the user asking. Deterministic (the extension does it, not the model remembering to) — but **silent when there's nothing stale**.
+- **Transparency:** every prune (auto or manual) reports a **rich result** (ids + titles + age + `restore` hint), so the user is never blind to what moved — especially when the agent auto-pruned without an explicit trigger.
+- **Unified `Done` view:** one command + one panel tab to see all finished work (`status: done`), spanning live (recent) + archive (old), annotated by location, filterable.
+- **Preserve the injection contract unchanged:** only `open` + `in_progress` are auto-injected into the prompt. Parked / done / archive are not injected. v0.3.1 does not alter this boundary.
+
+## 3. Non-goals (deferred)
+
+- **`cancelled`-in-live visibility** — a pre-existing gap (cancelled todos <7d are in live but shown in no panel tab). Cancelled shows in the Archive tab once pruned. Separate concern; not addressed here.
+- **`prune --all` / `prune --hard`** — unchanged (manual only; `--hard` stays the only irreversible, gated action).
+- **Auto-prune of `parked`** — parked is deferred-not-finished, not "done"; auto-prune targets `done`/`cancelled` only (same as manual `prune`).
+- **Time-based/scheduled prune outside session_start** — no cron; auto-prune runs only on the `session_start` hook (cold start / resume / fork / reload).
+
+## 4. Decisions log (from brainstorm Q&A)
+
+| # | Question | Decision |
+|---|---|---|
+| Q1 | Where does "done" live in the `/todo` panel? | **A** — new 5th box tab `Done` (status `done` only, unified live+archive). `done` (status) ≠ `archive` (location) — different axes; `Done` = workflow view, `Archive` = storage vault. |
+| Q2 | Auto-prune trigger mechanism | Deterministic on `session_start` (extension code), age-gated (>`defaultAgeDays`), **never `--all`**. Not prompt-driven (the model doesn't have to remember). |
+| Q3 | Confirm gate for auto-prune? | No gate — reversible + age-gated, not destructive. The `--hard` gate stays untouched. |
+| Q4 | Visibility when prune runs | Rich result (ids + titles + age + `restore` hint) for BOTH auto and manual prune. |
+| Q5 | Unified `done` listing | `todo list status:done` spans live+archive in one call; `/todo done` slash shortcut. |
+| Q6 | Injection contract | **Unchanged** — only `open`+`in_progress` injected. Auto-prune moves done→archive (both non-injected); zero injection impact. The Done tab is a panel view only. |
+
+## 5. Auto-prune on `session_start`
+
+### 5.1 Trigger
+
+The extension's existing `session_start` handler (in `extensions/todo.ts`) currently: loads open todos, computes `healthReport()`, and notifies `armory-todo: N open TODOs` (+ a `⚠ N bloat signals` suffix if flags). v0.3.1 inserts an **auto-prune step** before the notify:
+
+1. Load the live store.
+2. Compute the set of done/cancelled todos with `closedAt` older than `config.prune.defaultAgeDays` (default 7d) — i.e. exactly what `pruneTodos({})` (age-gated, no `--all`) would move.
+3. **If that set is non-empty → call `pruneTodos({})`** (age-gated; **never `--all`**) and capture the moved ids + todos.
+4. Notify once, with the rich format (§6).
+5. **If empty → skip** (just the normal `N open TODOs` notify; no prune noise).
+
+This runs on every `session_start` (cold start / resume / fork / `/reload`). Because it's age-gated, it's a no-op on a clean store — no churn, no prune spam. Idempotent: once pruned, the todos are in the archive; the next start sees nothing stale.
+
+### 5.2 Why deterministic (not prompt-driven)
+
+"Agent thinks" = the agent's *awareness* drives it, but relying on the model to remember to call `prune` every session is fragile. Wiring it into the `session_start` hook makes it **just happen** reliably — the extension acts on the user's behalf at session start, deterministically. The model still *sees* the result (via the notify) and can act on it (e.g. mention it, or `restore` if the user asks). This matches the user's intent ("automatically triggered") without depending on model compliance.
+
+### 5.3 Config
+
+Reuses `config.prune.defaultAgeDays` (7) — already tunable via the Config tab / `todo.config.json`. **No new config key.** A future v0.4.x could add `config.prune.autoOnSessionStart: boolean` to disable auto-prune, but v0.3.1 ships it always-on (age-gated).
+
+### 5.4 Notify format
+
+```
+armory-todo: 2 open TODOs · auto-pruned 3 stale done (>7d):
+  [td-…] done  armory-todo v0.2.0 — Workstream A shipped…
+  [td-…] done  Task 1: Store schema break…
+  [td-…] cancelled  QA smoke v0.3.0
+Undo any with: todo restore <id>
+```
+
+(When nothing was pruned, just `armory-todo: N open TODOs` — unchanged from v0.3.0, optionally + the existing `⚠ bloat` suffix if health flags fire.)
+
+The notify is a **transient `ctx.ui.notify` message**, NOT a system-prompt injection. The `## Open TODOs` prompt block is untouched.
+
+## 6. Rich prune result (auto + manual)
+
+Both the auto-prune (§5) and manual `prune` (tool + `/todo prune` slash) produce the same structured output. New helper in `src/archive.ts`:
+
+```ts
+export interface PruneDetail {
+  moved: number;
+  items: { id: string; status: "done" | "cancelled"; title: string; ageDays: number }[];
+}
+```
+
+`pruneTodos` gains an optional `detail: true` flag (default false for back-compat) that returns `items` + `ageDays` (computed from `closedAt`). When `detail` is true, the caller (extension) formats:
+
+```
+Pruned 3 todos to archive:
+  [td-…] done  <title>  (was 9d old)
+  [td-…] cancelled  <title>  (was 12d old)
+Undo any with: todo restore <id>
+```
+
+- **Manual `prune`** (tool + slash): always uses `detail: true` → rich output.
+- **Auto-prune** (session_start): uses `detail: true` → rich notify.
+- The `--all` path: same rich format (age shown as `(--all)` or the real age; minor).
+
+The existing `PruneResult { moved, ids }` shape stays (back-compat for any caller); `PruneDetail` is additive.
+
+## 7. Unified `Done` listing
+
+### 7.1 Store layer (`src/archive.ts` + `src/todo-store.ts`)
+
+New `listDoneUnified(filter?): DoneItem[]` (in `archive.ts` — it already coordinates live + archive via `loadStore`/`loadArchive`):
+
+```ts
+export interface DoneItem extends Todo {
+  location: "live" | "archive";
+  archivedAt: string | null;  // closedAt for live; closedAt for archive (the prune time ≈ closedAt)
+}
+```
+
+- Pulls done todos from the live store (`loadStore().todos.filter(status === "done")`) tagged `location: "live"`, plus done todos from the archive (`loadArchive().todos.filter(status === "done")`) tagged `location: "archive"`.
+- **Excludes `cancelled`** (Done = finished work; cancelled = abandoned → lives in the Archive tab only).
+- Sorts newest-`closedAt` first.
+- Filter: `text` (title|notes substring), `project`, `since`, `before`, `limit`, `page` (same shape as `listTodos`/`listArchived` filters).
+
+### 7.2 Tool (`extensions/todo.ts`)
+
+- **`todo list status:done`** now returns the **unified** set (live + archive) via `listDoneUnified`, formatted:
+  ```
+  - [td-…] done  <title>  [live 3d]
+  - [td-…] done  <title>  [archived 2026-07-15]
+  ```
+  (When `status:done` is set, the `archived` param is ignored — `done` is always unified. Other status values keep current behavior: `archived:true` queries the archive, default queries live.)
+
+### 7.3 Slash (`/todo done`)
+
+New slash subcommand: `/todo done` → prints the unified done list (recent first), same row format as §7.2. `/todo done project:bug-bounty` → filtered.
+
+## 8. `/todo` panel — new `Done` box tab
+
+### 8.1 Tabs
+
+`BOXES` becomes `["active", "parked", "done", "archive", "config"]` (5 tabs).
+
+### 8.2 Done tab content
+
+- Uses `listDoneUnified({ text: filter })` (the panel's filter input searches title|notes across the unified set).
+- `todoToItem` rows: `[id] (done) (project) • <title>` + a location tag suffix `[live N]` or `[archived <YYYY-MM-DD>]`. (Add a `todoDoneItem` helper in `panel-data.ts` that extends `todoToItem` with the location tag, or add an optional `location` param to `todoToItem`.)
+- Sorted newest-closed first.
+- Action submenu on Enter: **View detail** + (if location is archive) **Restore** (brings it back as open). Live done rows offer **View detail** only (no Restore — they are already in the live store; use `todo update <id> status:open` to reopen, or leave as done). No **Delete** for done rows (already finished; deletion/cancel is for open todos).
+
+### 8.3 Archive tab — unchanged
+
+Still the sealed-vault browse view: summary-first (counts by project + month across done + cancelled), drill-down with a filter. Unchanged from v0.3.0.
+
+### 8.4 Footer hint
+
+Update the panel footer to reflect 5 tabs: `↑↓ navigate • enter select/action • tab switch box • esc done`.
+
+## 9. Injection contract (unchanged — explicit)
+
+`renderOpenBlock()` still calls `listTodos()` with the default filter (`status === "open" || status === "in_progress"`). v0.3.1 does NOT touch `renderOpenBlock` or `listTodos`'s default. Therefore:
+
+- Only `open` + `in_progress` are auto-injected (title + `•`, capped 15).
+- Parked / done / archive are NOT injected — available via `list`/`get`/panel only.
+- Auto-prune moves done (not injected) → archive (not injected): **zero injection impact**.
+- The Done tab is a panel view; it does not inject.
+
+The only new thing the *agent* sees at session start is the transient `ctx.ui.notify` (§5.4), not a system-prompt change.
+
+## 10. Tests
+
+Baseline: 220 across 8 suites. Target: ~240+.
+
+### 10.1 New suite `test/todo-auto-prune.test.mts`
+- `session_start` auto-prune: stale done (>7d) → moved to archive; fresh done (<7d) → stays in live; open/in_progress/parked untouched.
+- Auto-prune never uses `--all` (fresh done <7d stays even if `--all` would move it).
+- Auto-prune is a no-op when nothing is stale (live store unchanged, no prune notify payload).
+- Idempotent: running twice (two session_starts) → second is a no-op.
+- `cancelled` also auto-pruned when stale.
+- Rich result: `PruneDetail.items` has id + status + title + ageDays.
+
+### 10.2 Extend `test/todo-archive.test.mts`
+- `pruneTodos({ detail: true })` returns `items` with `ageDays` computed from `closedAt`.
+- `listDoneUnified`: live done + archived done merged, `cancelled` excluded, sorted newest-closed first, `location` tag correct, filters (text/project/since/before/limit/page) work.
+- `listDoneUnified` empty when no done todos.
+
+### 10.3 Extend `test/panel-data.test.mts`
+- `todoDoneItem` (or `todoToItem` with location): label includes `[live N]` / `[archived <date>]`.
+
+### 10.4 Extend `test/todo-store.test.mts` (if `list status:done` routing changes)
+- `listTodos({ status: "done" })` still returns live done (back-compat) — the unification happens at the extension layer for the `todo list status:done` tool call, OR move unification into the store. **Decision:** keep `listTodos({status:"done"})` as live-only (back-compat); the unification lives in `listDoneUnified` (archive.ts), called by the extension for `todo list status:done`. So no `todo-store` change for routing — test that `listTodos({status:"done"})` is unchanged.
+
+### 10.5 Manual-gate (no unit test)
+- Extension `session_start` auto-prune + notify format.
+- `/todo` panel Done tab (rendering, filter, action submenu, restore-from-archive).
+- `/todo done` slash.
+- `todo list status:done` unified output.
+
+Verified by RECTOR in a real pi session before merge (same gate as v0.3.0).
+
+## 11. Branch + ship
+
+- Branch `feat/auto-prune-done-view` off `main`.
+- Commits: `feat(auto-prune): ...`, `feat(prune): rich result ...`, `feat(done): unified listing ...`, `feat(panel): Done tab ...`, `test: ...`, `docs: ...` — one logical change per commit.
+- PR to `main`, `--merge --delete-branch`. No GitLab mirror (getpipher).
+- **QA gate:** RECTOR tests in a real pi session: stale done auto-prunes on start (fresh done stays); the notify shows the rich result; `/todo done` + the Done tab show unified done (live + archive, tagged); `todo restore <id>` undoes an auto-prune; injection unchanged (only active injected).
+- Tag `v0.3.1` → CI auto-publish (npm) + auto-create GitHub Release (the v0.3.0-post workflow change).
+- Post-ship: bump README/AGENTS test count + add the Done tab / auto-prune to the docs; mark this spec shipped.
+
+## 12. Open question (resolve at implementation)
+
+- **`pruneTodos` `detail` flag vs always-rich:** simplest is to make the rich `items` always returned (no flag) and have callers that only need `{moved, ids}` ignore `items`. Decide during implementation — leaning toward always-return for simplicity, since the cost is computing `ageDays` (trivial) per moved todo.
+
+## 13. Out of scope (future)
+
+- **`cancelled`-in-live panel visibility** — a pre-existing gap; could add a `Cancelled` filter or fold into the Archive tab's live portion in a future workstream.
+- **`config.prune.autoOnSessionStart` toggle** — disable auto-prune (v0.4.x).
+- **Auto-prune notify dedup** — if `/reload` fires multiple times in a session, the notify repeats; acceptable for v0.3.1 (it's a transient inform).
+- **Workstream C (v0.4.0):** preventive caps-on-add (notes length cap + project registry) — still the next major milestone.

package/docs/superpowers/specs/2026-07-21-project-scope-management-design.md

@@ -0,0 +1,319 @@
+# Project-Scope Management — Design (v0.4.0, Workstream C / Feature A)
+
+**Date:** 2026-07-21
+**Workstream:** C → Feature A (issue #1's project-scope half)
+**Release:** v0.4.0
+**Predecessors:** v0.3.1 (auto-prune + unified Done view) — 255/255 tests, 9 suites
+**Successor:** v0.5.0 — Feature B (caps enforcement: count cap + notes cap + over-cap injection summary). This spec is **advisory-only**; no enforcement ships here.
+
+**Branch:** `feat/project-scope-management` off `main`
+**Commits:** `feat(scope): ...` per task. PR → `--merge --delete-branch`. RECTOR QA gate → tag `v0.4.0` → CI auto-publishes npm + GitHub Release (now automatic).
+
+---
+
+## 1. Problem (the real one, restated)
+
+The injected `## Open TODOs (N)` block is already bounded (v0.3.0 title-only injection + `renderOpenBlock(max=15)` + v0.3.1 auto-prune). What's **still unsolved**:
+
+1. **No forcing function on the *count*.** Open can grow to 30/50/100 with no pushback; the injection *hides* the rot behind `+N more`. A cap is a triage signal, not a bytes fix.
+2. **No scope overview.** `project` is free-text, un-aggregated. Working across ZeroClaw, getpipher, vision, etc., you can't see "this project owns 18 of my 22 open" — can't triage *where* to cut. The bigger daily pain than the cap.
+3. **No per-project bloat signal in `health`.** `ACTIVE_LARGE` fires globally at >15; can't say *which* project is over budget.
+4. **No curation surface.** A typo'd project string (`getpither` vs `getpipher`) silently becomes its own "project" with no way to merge.
+
+v0.4.0 is the **triage visibility** release: see the backlog by project + know when one's over budget + fix typos. **No enforcement** — that's v0.5.0's "caps release" (count + notes + injection, all block-on-add).
+
+---
+
+## 2. Scope (locked decisions)
+
+| Decision | Choice | Rationale |
+|---|---|---|
+| **Release slice** (Q1) | B — v0.4.0 = Feature A only; v0.5.0 = Feature B (caps) | Lands triage visibility (the daily pain) before the cap that needs it. v0.4.0 is zero-enforcement-risk. |
+| **Registry vs dynamic** (Q2) | C — full registry with per-project config slots | Forward-looking for armory-todo; canonical name list + rename/merge (the point of a registry over dynamic derivation). |
+| **`maxOpen` slot behavior in v0.4.0** (Q3) | A — advisory `health` flag now; enforcement (block-on-add) in v0.5.0 | Slot is never inert: graduates advisory → hard block. No lying UI. |
+| **Notes cap in v0.4.0?** (Q4) | A — defer to v0.5.0 | v0.4.0 is purely the project-scope axis; v0.5.0 is "the caps release" (count + notes + injection). |
+| **Registry storage** (Q5) | B — sibling `~/.pi/agent/todo/projects.json` | Registry is *state* (grows, auto-seeds); config is *settings*. Separation avoids a config schema bump + the risky live-store migration. |
+| **Registry entry shape** (Q6) | A — minimal `{ name, maxOpen, createdAt, updatedAt }` | Every field earns its weight; `lastSeenAt`/reserved slots re-introduce the inert-field hazard. |
+| **Registry sync** (Q7) | A — lazy sync-on-read | No writes on `add`/`update`; `projects`/`health` reconcile first. First read seeds; later reads self-heal. No cross-path risk (file lives under `TODO_DIR`). |
+| **Rename/merge** (Q8) | B — included, full consistency (live + archive + registry) | Rename is the point of a registry; half-way (archive sealed) re-splits the project in the view. |
+| **`projects` output** (Q9) | B — counts + cap signal + typo marker | One-stop triage; staleness/notesBytes stay in `health` (whole-store concerns). |
+| **`health` per-project flags** (Q10) | C — `PROJECT_OVER` + `PROJECT_TYPO` + `PROJECT_LARGE` + `PROJECT_STALE` | `PROJECT_LARGE` (global default threshold) makes the per-project signal useful on day 1, not gated behind per-project config. All advisory. |
+| **Action API + slash naming** (Q11) | A — tool `action:'projects'` + `action:'project_rename'`; slash `/todo projects` (thin mirror) | Plural=list, singular=action namespace. No `/todo project rename` slash — rename is panel-only (Q12). |
+| **Panel surface** (Q12) | A — 6th tab `projects` + per-project action submenu | Panel is the primary human surface (getpither UX mental model: interactive first, CLI-style for the agent). |
+| **UX mental model** | Documented in `~/local-dev/getpipher/AGENTS.md` (cross-cutting, all getpither extensions) | Panel-first design order; tool action + slash are secondary/derived. |
+
+**Defaults (Q13):** `health.perProjectDefaultMax = 8`; `maxOpen` per-project default `null`; `PROJECT_STALE` reuses `activeStaleDays` (30d); `PROJECT_TYPO` = exactly 1 todo in project (live + archived done); seed scope = live + archive; empty-project group = `(no project)` (excluded from typo detection, no `maxOpen`); rename is best-effort multi-file (live → archive → registry, backup-on-corrupt per file, no cross-file WAL).
+
+---
+
+## 3. Architecture
+
+### 3.1 New file: `projects.json` (registry state)
+
+`~/.pi/agent/todo/projects.json` — the project registry. Auto-seeded on first read, lazy-synced on every registry touch.
+
+```json
+{
+  "version": 1,
+  "updatedAt": "2026-07-21T12:00:00.000Z",
+  "projects": [
+    {
+      "name": "getpipher",
+      "maxOpen": 5,
+      "createdAt": "2026-07-21T12:00:00.000Z",
+      "updatedAt": "2026-07-21T12:00:00.000Z"
+    }
+  ]
+}
+```
+
+- **`version: 1`** — bump on future schema changes (e.g. v0.5.0 may add per-project `maxNotesBytes`).
+- **`maxOpen: number | null`** — advisory cap slot. `null` (default) → no `PROJECT_OVER` flag for this project. v0.4.0: drives `health` flag only. v0.5.0: enforcement (block-on-add).
+- **`name`** — canonical project string. Unique within `projects[]`. Empty string `""` is NOT a registry entry (the `(no project)` group is implicit, never registered).
+- Atomic 0600 write (tmp + rename), same pattern as `saveStore`/`saveConfig`.
+
+### 3.2 New module: `src/registry.ts`
+
+Pure, pi-independent (like the other `src/` modules). No new runtime deps.
+
+```ts
+export interface ProjectEntry { name: string; maxOpen: number | null; createdAt: string; updatedAt: string; }
+export interface ProjectRegistry { version: 1; updatedAt: string; projects: ProjectEntry[]; }
+
+export function getRegistryPath(): string;           // <TODO_DIR>/projects.json
+export function loadRegistry(): ProjectRegistry;     // corrupt → backup .bad-<ts>, fresh
+export function saveRegistry(reg: ProjectRegistry): void;  // atomic 0600
+export function reconcileRegistry(reg, liveTodos, archivedTodos): { reg, changed };  // lazy sync: append unknown project strings with maxOpen:null
+export function getProjectEntry(reg, name): ProjectEntry | undefined;
+export function setProjectMaxOpen(reg: ProjectRegistry, name: string, max: number | null): ProjectEntry;  // max=null clears; creates entry if unknown; throws if name === "" (no-project group can't be capped)
+export function renameProject(reg, oldName, newName): { reg, liveTodos, archivedTodos, liveChanged, archivedChanged };  // rewrites registry + both stores in place
+```
+
+**Lazy sync (`reconcileRegistry`):** collect distinct non-empty `project` strings across `liveTodos` + `archivedTodos`; for any not in `reg.projects`, append `{ name, maxOpen: null, createdAt: now, updatedAt: now }`. Bump `reg.updatedAt` iff changed. Caller persists iff `changed`.
+
+**Seed:** `loadRegistry()` on a missing file returns an empty registry (`{ version: 1, updatedAt: now, projects: [] }`) and does NOT seed. Seeding happens on the first `reconcileRegistry` call (inside `projectsOverview`/`healthReport`), which persists. This keeps `loadRegistry` side-effect-free (matches `loadConfig`'s "missing → write defaults" pattern is NOT used here — we seed lazily to keep load pure + avoid a write on a bare load).
+
+**No env guard:** `projects.json` always lives under `TODO_DIR` (temp dir in tests), so no cross-path migration risk (unlike v1→v2 file-move). Tests get isolated registries for free.
+
+### 3.3 New module: `src/projects.ts` (overview)
+
+Pure read + reconcile. The `projects` action's brain.
+
+```ts
+export interface ProjectOverviewRow {
+  name: string;
+  open: number;
+  in_progress: number;
+  parked: number;
+  done: number;          // live done + archived done
+  total: number;         // open + in_progress + parked + done
+  maxOpen: number | null;
+  over: boolean;         // open > maxOpen (only when maxOpen !== null)
+  typo: boolean;          // exactly 1 todo (live + archived done) in the project
+  lastUpdated: string;   // max updatedAt across the project's live todos (ISO), or "" if none live
+}
+
+export interface ProjectsOverview {
+  rows: ProjectOverviewRow[];      // sorted: open desc → total desc → name asc
+  totalTodos: number;              // sum of all rows' total
+  noProject: { count: number; open: number };  // the (no project) bucket — not a row
+}
+
+export function projectsOverview(): ProjectsOverview;
+```
+
+**Typo nearest-sibling:** `typo: true` rows are reported in `health` suggestions with a nearest-sibling guess (Levenshtein ≤ 2 among other registry names). The `projects` row carries `typo: true`; the suggestion text carries the guess. (Edit-distance helper lives in `projects.ts` or a tiny `src/levenshtein.ts` — small enough to inline.)
+
+**`(no project)` bucket:** todos with `project === ""` are aggregated into `noProject`, NOT a row (no `maxOpen`, no typo, no rename target). Surfaced in the overview summary + `health`.
+
+### 3.4 `src/health.ts` — extend with per-project flags
+
+New flags + a new config field (forward-compatible merge, no schema bump):
+
+```ts
+export type HealthFlag =
+  | "ACTIVE_LARGE" | "ACTIVE_STALE"
+  | "PARKED_LARGE" | "PARKED_STALE"
+  | "ARCHIVE_LARGE" | "ARCHIVE_OLD"
+  | "PROJECT_OVER" | "PROJECT_TYPO" | "PROJECT_LARGE" | "PROJECT_STALE";  // new
+```
+
+`HealthConfig` gains `perProjectDefaultMax: number` (default 8). `loadConfig`'s existing merge (`{ ...DEFAULT_CONFIG.health, ...parsed.health }`) fills it for old configs — no migration.
+
+`HealthReport` gains:
+
+```ts
+export interface ProjectHealth { name: string; open: number; maxOpen: number | null; over: boolean; typo: boolean; large: boolean; stale: boolean; lastUpdated: string; }
+export interface HealthReport {
+  // ...existing fields...
+  projects: ProjectHealth[];   // only projects with ≥1 flag, sorted open desc
+  noProject: { open: number };  // (no project) open count, for context
+}
+```
+
+Flag logic per project (live open count is the `open` figure):
+- `PROJECT_OVER` — `maxOpen !== null && open > maxOpen`
+- `PROJECT_LARGE` — `open > config.health.perProjectDefaultMax` (default 8; fires even when `maxOpen` is null — the day-1 signal)
+- `PROJECT_STALE` — `lastUpdated !== "" && daysAgo(lastUpdated) > config.health.activeStaleDays` (30d)
+- `PROJECT_TYPO` — total todos (live + archived done) in the project === 1 AND a near-named sibling (Levenshtein ≤ 2) exists in the registry
+
+`healthReport()` calls `reconcileRegistry` first (so the registry is current), persists iff changed, then computes. Suggestions gain per-project actionable lines, e.g.:
+- `project 'getpither' has 1 todo — possible typo of 'getpipher'? → todo project rename getpither getpipher`
+- `project 'getpipher' 12 open (maxOpen 5) → close/park some, or raise maxOpen`
+- `project 'bug-bounty' 9 open (per-project default max 8) → over budget`
+- `project 'vision' untouched 45d → stale, park or close`
+
+### 3.5 `src/todo-store.ts` — no schema change, no new writes
+
+`addTodo`/`updateTodo` are **unchanged** (no registry write — lazy sync, Q7=A). The live store stays `Store.version: 3`. `Todo.project` stays free-text. No migration.
+
+### 3.6 `extensions/todo.ts` — new tool actions + panel tab + thin slash
+
+#### Tool actions (agent surface)
+- `action: 'projects'` → returns `ProjectsOverview` (structured). No params.
+- `action: 'project_rename'` → params `oldName: string`, `newName: string`. Returns `{ liveRenamed: number, archivedRenamed: number, merged: boolean, newName: string }`. Throws `TodoError` if `oldName` not in registry. `newName` may equal an existing different project — rename-onto-existing is a **merge** (consolidates `oldName` todos into `newName`, removes the `oldName` registry entry, keeps `newName`'s entry; `merged: true`). This is the typo-cleanup path (`getpither` → `getpipher` where `getpipher` already exists). Self-rename (`newName === oldName`) is a no-op success (`{ liveRenamed: 0, archivedRenamed: 0, merged: false, newName }`).
+
+#### Panel (human surface — primary)
+New 6th tab `projects` in the `/todo` panel (existing 5: active/parked/done/archive/config → now 6). Tab label `Projects`.
+
+- **Rows:** `ProjectOverviewRow` rendered as: `name  open/in_progress/parked/done (total)  [max:N or —]  OVER?  ?typo  · lastUpdated`. Box-draw to match existing tab style.
+- **Sort:** open desc → total desc → name asc (Q9).
+- **Action submenu** (per project, via `openActionSubmenu`): `Rename` / `Set maxOpen` / `Filter active to project`.
+  - **Rename** — inline `Input` (single-line; pi-tui can't nest `ctx.ui.editor()` inside `ctx.ui.custom()`). Validates `newName` non-empty + not equal to current. Calls `renameProject`. Confirms merge if target exists. Notify on success (`Renamed getpither → getpipher (3 live + 1 archived)`).
+  - **Set maxOpen** — inline `Input`, accepts a positive integer or `clear` (→ `null`). Calls `setProjectMaxOpen`. Notify (`getpipher maxOpen = 5` or `getpipher maxOpen cleared`).
+  - **Filter active to project** — jumps to the `active` tab with a `project` filter applied (existing list filter already supports `project`).
+- **`(no project)` bucket** — shown as a non-selectable summary row at the top or footer (`(no project): N open`), no submenu.
+
+#### Slash (thin mirror only)
+- `/todo projects` — prints the `ProjectsOverview` as text (mirrors `/todo health`'s text-report style). One new sub. **No** `/todo project rename` slash — rename is panel-only (Q12=A + getpither UX mental model).
+
+### 3.7 `src/config.ts` — one new field, no schema bump
+
+`HealthConfig` gains `perProjectDefaultMax: number` (default 8). `DEFAULT_CONFIG.health.perProjectDefaultMax = 8`. `loadConfig`'s merge fills it for old configs. `TodoConfig.version` stays `1`.
+
+### 3.8 No injection change
+
+`renderOpenBlock` is **unchanged** in v0.4.0 (no caps, no over-cap summary — that's v0.5.0). The `## Open TODOs (N)` block keeps its current shape (≤15 title-only rows + `+N more`).
+
+---
+
+## 4. Data flow
+
+### 4.1 `todo projects` (tool) / `/todo projects` (slash) / Projects tab (panel)
+1. `loadStore()` (live) + `loadArchive()` (archived done).
+2. `loadRegistry()` → `reconcileRegistry(reg, live, archive)` → persist iff changed.
+3. `projectsOverview()` computes rows from live + archive + registry.
+4. Return (tool) / render (panel) / print (slash).
+
+### 4.2 `todo health`
+1. Same load + reconcile as 4.1.
+2. `healthReport()` extends: existing box diagnostics + new `projects[]` (per-project flags) + `noProject`.
+3. Render (existing text format + new `projects:` section).
+
+### 4.3 `todo project_rename` (tool) / panel Rename
+1. `loadRegistry()`, find `oldName` entry (throw if missing).
+2. `loadStore()` + `loadArchive()`.
+3. Validate `newName` (non-empty, trimmed; if equal to `oldName` → no-op success).
+4. Rewrite live todos (`project === oldName` → `newName`, bump `updatedAt`), save store iff changed.
+5. Rewrite archived todos (`project === oldName` → `newName`, bump archive `updatedAt`), save archive iff changed.
+6. Registry: remove `oldName` entry, ensure `newName` entry exists (create if merge target was absent, keep if merge), bump `updatedAt`. Save registry.
+7. Return `{ liveRenamed, archivedRenamed, merged, newName }`.
+8. **Failure semantics:** best-effort, not cross-file transactional (no WAL). Each file write uses the existing backup-on-corrupt pattern. If step N fails, prior writes stand; the result reports what happened. A later `reconcileRegistry` self-heals any drift.
+
+### 4.4 `todo update` / `todo add` with a project
+- **Unchanged.** No registry write. The new project string is picked up on the next `projects`/`health` read (lazy sync).
+
+---
+
+## 5. Edge cases
+
+- **Empty store** — `projectsOverview` returns `{ rows: [], totalTodos: 0, noProject: { count: 0, open: 0 } }`. `healthReport().projects = []`. Panel shows `(no projects)`.
+- **All-done project** — seeded from archive (live has 0 todos for it). Row: `name  0/0/0/N (N)  [max:null]  · lastUpdated:""`. Not typo (total ≥ 1 but if total === 1 and it's archived done, still typo-eligible — a single archived todo under a near-typo'd name is still a typo). Typo counts live + archived done.
+- **Rename onto self** — no-op success (`{ liveRenamed: 0, archivedRenamed: 0, merged: false, newName }`).
+- **Rename onto existing (merge)** — allowed; `merged: true`; `oldName` entry removed, `newName` entry kept.
+- **Rename to a name that only differs by case** (`getpipher` → `Getpipher`) — allowed (case-sensitive `project` is the existing contract); flags nothing special.
+- **`(no project)` rename** — not a rename target (no registry entry for `""`). `setProjectMaxOpen("")` → throws `TodoError` (no project group can't have a cap).
+- **Corrupt `projects.json`** — `loadRegistry` backs up to `projects.json.bad-<ts>` and returns a fresh empty registry; next reconcile re-seeds. No data loss (todos are the source of truth; the registry is derived + the maxOpen slots — which are the only non-derived data — are lost on corrupt, acceptable, same tradeoff as `todo.config.json`).
+- **`maxOpen = 0`** — semantically "no open todos allowed for this project." v0.4.0: `PROJECT_OVER` fires if open > 0. v0.5.0: blocks any add. Valid (edge but meaningful — "this project is closed").
+- **Two projects with the same name after a case-only rename** — can't happen (rename rewrites all todos to one casing; the registry has one entry per unique name).
+
+---
+
+## 6. Testing
+
+New suite `test/registry.test.mts` + `test/projects.test.mts`; extend `test/todo-health.test.mts` + `test/panel-data.test.mts`. Baseline 255/255 → target ~300+.
+
+### `test/registry.test.mts` (new, ~20)
+- `loadRegistry` missing → empty registry, no file write (lazy seed).
+- `loadRegistry` corrupt → backup `.bad-<ts>`, fresh empty.
+- `saveRegistry` atomic + 0600.
+- `reconcileRegistry` appends unknown (live + archive), bumps `updatedAt` iff changed, idempotent (no change on second call).
+- `reconcileRegistry` ignores empty-string project (not registered).
+- `getProjectEntry` hit/miss.
+- `setProjectMaxOpen` create-if-unknown, set number, `null` clears.
+- `renameProject` rewrites live + archive + registry, removes old, keeps/creates new, `merged` flag, no-op self-rename, throws on unknown old.
+
+### `test/projects.test.mts` (new, ~15)
+- `projectsOverview` row counts (open/in_progress/parked/done/total) from live + archive.
+- `maxOpen` carried from registry; `over` only when `maxOpen !== null && open > maxOpen`.
+- `typo` true iff total (live + archived done) === 1 AND near-sibling Levenshtein ≤ 2 exists.
+- `(no project)` bucket aggregated, not a row.
+- Sort: open desc → total desc → name asc.
+- `lastUpdated` = max live `updatedAt`, `""` when no live todos.
+- Empty store → empty overview.
+
+### `test/todo-health.test.mts` (extend, +~15)
+- `perProjectDefaultMax` default 8 + override via config.
+- `PROJECT_OVER` (maxOpen set + exceeded), `PROJECT_LARGE` (default threshold, maxOpen null), `PROJECT_STALE` (lastUpdated > activeStaleDays), `PROJECT_TYPO` (1 todo + near-sibling).
+- `healthReport().projects` only includes projects with ≥1 flag, sorted open desc.
+- `noProject` reported.
+- Reconcile runs inside health (registry seeded on first health call).
+- Suggestions actionable (rename hint for typo, maxOpen hint for over).
+
+### `test/panel-data.test.mts` (extend, +~10)
+- `projectsOverview` → panel rows rendering (markers `OVER`, `?typo`).
+- Action submenu options per project (Rename/Set maxOpen/Filter).
+- `(no project)` summary row, no submenu.
+- (Panel interactive flows — Rename via inline Input, Set maxOpen — are NOT unit-tested; covered by the autonomous tmux QA harness per v0.3.1 pattern. `panel.ts` is the only non-unit-tested component, same as v0.3.0/v0.3.1.)
+
+### Existing suites — regression
+- `todo-store` (44), `todo-title-notes` (31), `todo-archive` (55), `todo-config` (15), `todo-migrate` (26), `todo-hard-prune` (16), `todo-auto-prune` (12) — **unchanged logic**, must stay green. `todo-config` gains the new `perProjectDefaultMax` field assertion (default 8 + merge for old configs).
+
+---
+
+## 7. Implementation plan (high-level, for writing-plans)
+
+1. `src/registry.ts` + `test/registry.test.mts` — registry load/save/reconcile/setMaxOpen/rename. Pure, no pi.
+2. `src/projects.ts` + `test/projects.test.mts` — overview + Levenshtein typo helper.
+3. `src/config.ts` — add `perProjectDefaultMax` (default 8) + `DEFAULT_CONFIG` + merge test.
+4. `src/health.ts` + extend `test/todo-health.test.mts` — 4 per-project flags + `projects[]` + `noProject` + actionable suggestions; reconcile-first.
+5. `extensions/todo.ts` — tool `projects` + `project_rename` actions; `/todo projects` slash; panel `Projects` tab (rows, action submenu, inline Rename/Set maxOpen/Filter).
+6. `src/panel-data.ts` + extend `test/panel-data.test.mts` — `projectsOverview` → panel row helpers, action-submenu options, `(no project)` row.
+7. `README.md` + `AGENTS.md` — v0.4.0 section (projects view, rename, per-project health flags, `maxOpen` advisory); Known issues (no enforcement until v0.5.0).
+8. RECTOR QA gate (autonomous tmux harness per v0.3.1): panel Projects tab, Rename (incl. merge), Set maxOpen, `/todo projects`, `todo health` per-project section, `/todo project*` slash absence.
+9. Merge → tag `v0.4.0` → CI auto-publish npm + GitHub Release.
+
+---
+
+## 8. Out of scope (v0.5.0 / later)
+
+- **Enforcement** — block-on-add when open > maxOpen (v0.5.0 graduates the `PROJECT_OVER` flag → throw).
+- **Notes cap** — `maxNotesBytes` config + reject oversize notes at `add`/`update` (v0.5.0).
+- **Over-cap injection summary** — `renderOpenBlock` over-cap truncation (counts + over-budget projects instead of the 15-row list) (v0.5.0).
+- **Project merge as a distinct action** — v0.4.0 merge is a side-effect of rename-onto-existing; a dedicated `project_merge` (merge N → 1) is later if needed.
+- **Project delete/purge** — removing a registry entry without renaming (orphaned todos keep their `project` string; re-registered on next read). Later.
+- **Per-project `maxNotesBytes`** — v0.5.0 may add this to the registry entry (schema v2).
+
+---
+
+## 9. Backwards compatibility
+
+- **Store:** `Store.version: 3` unchanged. No migration. Existing `todo.json` + `todo-archive.json` load as-is.
+- **Config:** `TodoConfig.version: 1` unchanged. `perProjectDefaultMax` added via forward-compatible merge (old configs get the default 8).
+- **Registry:** new file; missing on first load → empty → seeded lazily. No user action.
+- **`project` free-text:** unchanged. Existing todos with any `project` string keep working; the registry picks them up on first read.
+- **Injection (`## Open TODOs`):** unchanged in v0.4.0.
+- **Tool API:** two new `action` values (`projects`, `project_rename`); no existing action changes.
+- **Slash:** one new sub (`/todo projects`); no existing sub changes.
+
+No breaking changes. v0.3.1 → v0.4.0 is a safe in-place upgrade.

package/docs/superpowers/specs/2026-07-21-title-notes-split-design.md

@@ -1,7 +1,7 @@
 # Workstream B — `title` + `notes` schema split (v0.3.0)
 
 **Date:** 2026-07-21
-**Status:** Design approved → pending implementation plan
+**Status:** Shipped (v0.3.0, PR #4, 2026-07-21)
 **Branch:** `feat/title-notes-split` off `main`
 **Predecessor:** v0.2.0 (Workstream A — lifecycle boxes + prune + health + TUI panel), PR #3, shipped 2026-07-21
 **Supersedes (for this scope):** `2026-07-20-lifecycle-boxes-prune-design.md` §14 (which deferred this exact split to Workstream B)