@getpipher/armory-todo 0.4.0 → 0.5.1

package/docs/superpowers/specs/2026-07-21-caps-release-design.md

@@ -0,0 +1,222 @@
+# v0.5.0 — Caps Release (Feature B, enforcement)
+
+**Date:** 2026-07-21
+**Status:** Approved (brainstorm 2026-07-21, all six decisions = A)
+**Issue:** #1 — Project-scope management + self-awareness caps to prevent TODO bloat (Feature B, the forcing-function half)
+**Predecessor:** v0.4.0 (project registry + `projects` overview + per-project `health` flags + advisory `maxOpen` slot + rename/merge). Published `@getpipher/armory-todo@0.4.0`.
+**Branch:** `feat/caps-release` off `main`
+**Semver:** minor (v0.5.0) — a semantic behavior change (advisory `maxOpen` → enforced) plus new enforcement.
+
+---
+
+## 1. Goal
+
+Graduate the v0.4.0 advisory `maxOpen` slot into **enforcement** and add two more caps, so the TODO store (and its auto-injected prompt block) cannot bloat silently. One coherent "caps release," all enforcement:
+
+1. **Count cap** — per-project `maxOpen` → **block-on-add** (and block on project-move into a capped project).
+2. **Notes cap** — global `maxNotesBytes` → **reject oversize notes at write time** (mirrors the title cap).
+3. **Over-cap injection truncation** — when actionable > `activeMaxOpen`, `renderOpenBlock` switches to a lean summary (counts + over-budget projects + pointer) instead of the row list.
+
+Tune defaults using v0.4.0's real per-project usage data (now visible via `projects`/`health`).
+
+## 2. Decisions (brainstorm, all A)
+
+| Q | Decision | Rationale |
+|---|---|---|
+| **Q1 enforcement mode** | Enforce explicitly-set per-project `maxOpen` only (hard block-on-add). Defaults (`activeMaxOpen`, `perProjectDefaultMax`) stay advisory. No `force` hatch. Block fires on `add` + project-`move`, **not** un-park. | v0.4.0 already ships warn-only (the flags). Enforcement must enforce *something*. Only an explicitly-set cap enforces — opt-in via setting `maxOpen`. A global hard block is too aggressive; enforcing a *default* is hostile. Un-park ≠ adding. |
+| **Q2 global cap** | No new global hard cap. `activeMaxOpen` (=15) stays advisory (`ACTIVE_LARGE`) and gains a second job: the **injection-truncation trigger**. | Global budget is a *signal*, not a *gate*. The global lever acts on the prompt (lean injection), not on `add`. |
+| **Q3 notes cap** | Global `health.maxNotesBytes`, default **8192** bytes, hard-reject at `add`/`update` (only when `notes` is written). Grandfather existing. `NOTES_OVER` health flag. Registry schema v1 unchanged. | Notes bloat is per-todo hygiene, not per-project. Active default (8KB ≈ 1–1.5k words) catches pathological agent dumps with no real downside. |
+| **Q4 injection truncation** | `renderOpenBlock` becomes cap-aware: trigger = `activeMaxOpen`. Over → lean summary (counts + `PROJECT_OVER` projects only + pointer). Under → rows up to `activeMaxOpen`. | Keeps the over-budget prompt to ~4 lines regardless of bloat — the anti-israf point. Surfaces only real breaches (explicit `maxOpen`), not soft heuristics. |
+| **Q5 migration** | Zero. Store v3 unchanged. Config gains `health.maxNotesBytes` via forward-merge (no version bump). Registry v1 unchanged. | Caps are enforcement, not data. |
+| **Q6 backwards-compat** | Oversize notes grandfathered (cap on write only). `maxOpen` advisory→enforced is a documented behavior change (minor bump). No v0.4.0 user has capped projects in the known real store, so zero real impact. | Re-setting slots silently is its own surprise. The block message tells users how to raise/clear. |
+
+## 3. Architecture
+
+Caps are an **enforcement layer on top of the existing store** — no new data, no migration. Three enforcement points:
+
+1. **`addTodo`** — title check (existing) + notes-cap check + project-cap check (new), all *before* `store.todos.push` (atomic: no partial write on breach).
+2. **`updateTodo`** — notes-cap check (only when `notes` patch present) + project-cap check on a project **move** (only when the moved todo is `open`/`in_progress`).
+3. **`renderOpenBlock`** — cap-aware truncation (summary mode when over `activeMaxOpen`).
+
+A new pure module `src/caps.ts` holds the check logic so it's unit-testable without disk. Config gains `health.maxNotesBytes`. Registry unchanged (schema v1). Zero store migration.
+
+## 4. Components
+
+### 4.1 `src/caps.ts` (new, pure — no disk I/O)
+
+```ts
+/** Throw if notes exceeds the byte cap. Byte-length (not char-length): notes
+ *  can hold Unicode ("é" = 2 bytes UTF-8). */
+export function checkNotesCap(notes: string, maxBytes: number): void
+
+/** Throw if adding one more open todo to `project` would exceed its cap.
+ *  `maxOpen === null` → no-op (uncapped). `currentOpen` is the project's
+ *  current open count, NOT counting the would-be-added todo. */
+export function checkProjectCap(opts: { project: string; currentOpen: number; maxOpen: number | null }): void
+
+/** Projects whose open count exceeds their explicit maxOpen (maxOpen non-null).
+ *  Pure; consumed by renderOpenBlock summary + health (existing PROJECT_OVER). */
+export function overBudgetProjects(liveTodos: Todo[], registry: ProjectRegistry): { name: string; open: number; maxOpen: number }[]
+```
+
+Error messages (actionable, surfaced verbatim to the agent/user via the existing `TodoError` → `Error: …` path):
+
+- `project 'X' is at maxOpen 8 (8 open) — close/park one, or raise maxOpen via the /todo panel (Projects tab → Set maxOpen), before adding`
+- `notes 9.2KB > max 8KB (maxNotesBytes 8192) — trim the detail or split into multiple todos`
+
+### 4.2 `src/config.ts` (modify)
+
+- Add `health.maxNotesBytes: number` (default `8192`).
+- Forward-compatible merge in `loadConfig` (same pattern as `perProjectDefaultMax` in v0.4.0): `{ ...DEFAULT_CONFIG.health, ...parsed.health }`.
+- Defensive: non-positive or non-number `maxNotesBytes` → default. (0 is a valid strict "no notes" choice and is respected; negative/NaN/missing → default.)
+- **No `TodoConfig.version` bump** (stays 1).
+
+### 4.3 `src/todo-store.ts` (modify)
+
+**`addTodo`:**
+- After `normalizeTitle`, load config + registry.
+- Count the target project's current `open` (todos with `status === "open"` — new todos are `open`, so `in_progress` isn't relevant for adds; count open only).
+- `checkNotesCap(notes, config.health.maxNotesBytes)` then `checkProjectCap({ project, currentOpen, maxOpen })`.
+- All checks precede `store.todos.push` → atomic (no partial write on breach).
+
+**`updateTodo`:**
+- If `patch.notes !== undefined` → `checkNotesCap(patch.notes.trim(), config.health.maxNotesBytes)`.
+- If `patch.project` is set, trimmed, and differs from `todo.project` **and** `todo.status` is `open`/`in_progress` → count the **target** project's open (excluding this todo, which is still in the source project at count time) → `checkProjectCap`.
+- Un-park (`parked→open`) is **not** re-checked — reactivation ≠ adding (intentional loophole, documented).
+
+**`renderOpenBlock(max?)`:**
+- Read `activeMaxOpen` from config; the `max` param overrides for tests.
+- If `actionable.length > activeMaxOpen` → **summary mode** (see §4.4 shape).
+- Else list up to `activeMaxOpen` rows (drops the hardcoded `max=15` default; aligns the injection budget to the configured cap).
+- The `… +N more` overflow line is removed (summary mode replaces it at the same threshold).
+
+### 4.4 `renderOpenBlock` summary shape
+
+```
+## Open TODOs (23) — ⚠ over budget (cap 15)
+23 open+in_progress across 5 projects
+over-budget: getpither 9/8, sip-protocol 6/5
+run `todo list` or `/todo` to see the full list
+```
+
+- Line 1: header with total + the breach + cap.
+- Line 2: total actionable + project span (distinct projects with any actionable).
+- Line 3: **only projects over their explicit `maxOpen`** (the `PROJECT_OVER` set). Format `name open/max`. Omitted entirely if no project is over its own cap (global over but every project within its slot).
+- Line 4: the pointer.
+
+`PROJECT_LARGE` (over `perProjectDefaultMax`, advisory) is deliberately **not** surfaced here — keep the lean summary focused on real breaches, not soft heuristics.
+
+### 4.5 `src/health.ts` (modify)
+
+- Add `"NOTES_OVER"` to `HealthFlag`.
+- Extend `NotesBytes` with `maxId: string | null` (the id of the worst-offender todo), tracked during the existing reduce over active+parked notes (cheap, no new scan).
+- Push `NOTES_OVER` when `notesBytes.max > config.health.maxNotesBytes`.
+- Suggestion: `notes: largest note <id> is 12KB > cap 8KB → trim via todo update <id> notes:…` (actionable — names the offender id).
+
+### 4.6 `src/panel-data.ts` (modify)
+
+- Add a Config row for `maxNotesBytes` (editable): label `"Notes max bytes"`, values `["2048","4096","8192","16384","32768"]`, description `"Hard reject at add/update when notes exceeds this (bytes). 0 = no notes."`.
+- Projects tab `OVER` marker unchanged — display is cap-agnostic; enforcement is backend.
+
+### 4.7 `extensions/todo.ts` (modify)
+
+- `add`/`update` actions: thrown `TodoError`s already caught + surfaced as `Error: …` — actionable messages flow through unchanged. No new code path needed.
+- `before_agent_start`'s `renderOpenBlock()` call: cap-aware now (no call-site change).
+- `promptGuidelines`:
+  - Update the `add`/`update` line: "adds are blocked if the target project is at its `maxOpen` cap; raise via the panel (Projects tab → Set maxOpen) or close/park one first. Notes are capped at `maxNotesBytes` (default 8KB)."
+  - Rewrite the `project_rename` line: remove "enforcement lands in v0.5.0" → "maxOpen caps are enforced (block-on-add)."
+- `health` action output: `NOTES_OVER` flows through the generic `flags:` line + the new suggestion line (no special rendering).
+
+### 4.8 `src/panel.ts` (minimal)
+
+No new flows. The Set-maxOpen action already exists; block-on-add surfaces via the tool/slash, not the panel (the panel has no add flow). An "OVER BUDGET" badge on the Active tab header is **YAGNI** — injection + health cover the signal. Skipped.
+
+## 5. Data flow
+
+```
+add:  loadStore → loadConfig + loadRegistry → checkNotesCap → checkProjectCap
+        → (all pass) push → save   [checks before any mutation = atomic]
+update: loadStore → find todo → [if notes patch: checkNotesCap]
+        → [if project-move + open/in_progress: checkProjectCap on target] → mutate → save
+inject: renderOpenBlock → loadConfig → actionable > activeMaxOpen ?
+          summary (counts + overBudgetProjects + pointer) : rows[:activeMaxOpen]
+```
+
+## 6. Error handling
+
+- Every cap failure is a `TodoError` thrown **before** any write — the store is never partially mutated (add: checks precede `push`; update: checks precede field mutation).
+- Corrupt/missing registry → `loadRegistry` returns empty (existing v0.4.0 behavior) → all `maxOpen` null → **cap fails open** (a bad registry never blocks adds; health flags it separately).
+- Corrupt config → `loadConfig` backs up + rewrites defaults (existing) → `maxNotesBytes` defaults to 8192.
+
+## 7. Testing
+
+### 7.1 New `test/todo-caps.test.mts` (~30 tests, temp `TODO_DIR`)
+
+**Notes cap:**
+- Oversized `add` throws with actionable message.
+- Oversized `update` (with `notes` patch) throws.
+- `update` **without** `notes` patch on a grandfathered oversize note survives (no re-check).
+- Boundary: exactly `maxBytes` ok; `maxBytes + 1` throws.
+- Byte vs char: `"é"` (2 bytes) at `maxBytes: 1` throws; at `maxBytes: 2` ok.
+- `notes: ""` always passes (the documented clear path).
+
+**Project cap:**
+- Uncapped project (`maxOpen: null`) → add always ok.
+- At-cap project (`maxOpen: 8`, open: 8) → add throws.
+- One-below (`open: 7`) → add ok (lands at 8, not over).
+- Project-move into capped target throws (when moved todo is `open`).
+- Project-move of a **parked** todo into capped target → ok (no open impact).
+- Same-project "move" (no-op) → ok.
+- Un-park (`parked→open`) into a capped project → ok (intentional, not blocked).
+- Error message includes the raise/clear hint.
+
+**`renderOpenBlock`:**
+- Under cap → row list (capped at `activeMaxOpen`).
+- Over cap → summary with over-budget line.
+- Over cap but no per-project breaches → summary without the over-budget line.
+- Custom `max` param overrides `activeMaxOpen`.
+
+### 7.2 Extend `test/todo-config.test.mts`
+
+- `maxNotesBytes` default 8192.
+- Forward-merge: old config without `maxNotesBytes` gets the default.
+- Negative/NaN/missing → default; `0` respected.
+
+### 7.3 Extend `test/todo-health.test.mts`
+
+- `NOTES_OVER` flag + suggestion when `notesBytes.max > maxNotesBytes`; suggestion names the offender `maxId`.
+- Absent when under.
+
+### 7.4 Extend `test/panel-data.test.mts`
+
+- `maxNotesBytes` config row present in `configToSettingItems`.
+
+**Total:** 331 baseline → ~361–371.
+
+## 8. Edge cases & resolved sub-questions
+
+- **`maxNotesBytes = 0`** → empty notes (0 bytes) pass, any non-empty fails. Valid strict choice; respected. Negative/non-number → default at load.
+- **Un-park into a capped project** is an intentional loophole — the cap gates *new* work, not reactivation. Documented in README + promptGuidelines.
+- **`update` that only edits `title`** on a grandfathered oversize note: no `notes` patch → no re-check → edit succeeds. (Without this gating, a cap would trap unrelated edits.)
+- **`renderOpenBlock` does 2 extra reads/turn** (config + registry). Negligible (tiny JSON files, already reads the store).
+- **Byte vs char length:** title uses char length (`.length`); notes uses byte length (`Buffer.byteLength`). Documented distinction — the field is `maxNotesBytes`.
+- **Worst-offender id in `NOTES_OVER` suggestion:** `NotesBytes` gains a `maxId: string | null` field, tracked during the existing reduce over active+parked notes (cheap, no new scan). The suggestion names the offender id so it's actionable (`todo update <id> notes:…`).
+
+## 9. Backwards-compat & upgrade notes
+
+- **Zero migration.** Store v3, config v1, registry v1 all unchanged in shape.
+- **Oversize existing notes:** grandfathered. Cap fires only when `notes` is written.
+- **`maxOpen` advisory → enforced:** semantic behavior change for any v0.4.0 user who set a slot. The known real store has none set (all `null`), so zero real impact. Documented trajectory. Block message tells the user how to raise/clear. Minor version bump (v0.5.0) is the semver signal.
+- **README upgrade note** added: a short "v0.5.0" section noting the advisory→enforced graduation + the new notes cap default.
+
+## 10. Flow (same as v0.4.0)
+
+brainstorm ✅ → spec (this doc) → RECTOR reviews → writing-plans → executing-plans (inline; pi has no subagent tool) → self-review (fresh-eyes over `git diff`) → autonomous tmux QA (temp `TODO_DIR` for write ops; real-store read-only for final verify — **do not** run rename/setmax/block-on-add against RECTOR's real store) → merge → tag `v0.5.0` → CI auto-publish npm + GitHub Release → `pi install npm:@getpipher/armory-todo@0.5.0` → memory `v0.5.0-shipped.md`.
+
+## 11. Constraints
+
+- Backwards-compatible with v0.4.0 stores (v3 store, v1 config, v1 registry).
+- Zero runtime deps (node:fs only). 2-space indent. No TODO/FIXME. No AI attribution.
+- Tests: node:test via tsx. `npm test` must stay green (331 baseline + new).
+- Commits: `feat(scope): …` per task. PR → `--merge --delete-branch`.
+- getpither UX mental model (in `~/local-dev/getpipher/AGENTS.md`): interactive first (panel) for humans, CLI-style (tool actions) for the agent. New enforcement surfaces (block-on-add error, over-cap injection summary) follow this — the error is the agent's programmatic surface; the panel needs no add flow.

package/extensions/todo.ts

@@ -133,7 +133,7 @@ export default function (pi: ExtensionAPI) {
       "Never put secrets in a TODO — the text reaches the model provider.",
     promptSnippet: "Read/update the global cross-session TODO list (active / parked / archive) + bloat health",
     promptGuidelines: [
-      "Use todo (action:'add', title, notes?, project?, tags?, priority?, source?) when the user says 'put this in our TODO'. title max 120 chars (one-line summary); put long detail in notes.",
+      "Use todo (action:'add', title, notes?, project?, tags?, priority?, source?) when the user says 'put this in our TODO'. title max 120 chars (one-line summary); put long detail in notes (capped at health.maxNotesBytes, default 8KB — oversize is rejected at write). Adds are BLOCKED if the target project is at its per-project maxOpen cap (the slot you set via the Projects tab); close/park one or raise maxOpen first.",
       "Use todo (action:'get', id) to read a todo's full notes before acting on it (the bullet marker in lists means notes exist).",
       "Use todo (action:'update', id, title?, notes?, project?, tags?, priority?, status?) to edit; notes empty string clears.",
       "Use todo (action:'list') when the user asks 'show me the TODO' / 'what's pending' (text filter searches title+notes).",
@@ -146,7 +146,7 @@ export default function (pi: ExtensionAPI) {
       "Use todo (action:'health') to check bloat across all boxes (counts + flags + suggestions). Run when the user asks about hygiene/bloat or before any hard-prune.",
       "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. getpither → getpipher). Rename onto an existing name merges (consolidates the old project into the new). Advisory maxOpen caps are NOT enforced in v0.4.0 — they only drive a health flag; enforcement lands in v0.5.0.",
+      "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. getpither → getpipher). 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.",
     ],
     parameters: Type.Object({
       action: StringEnum(ACTIONS),

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@getpipher/armory-todo",
-  "version": "0.4.0",
-  "description": "Global, cross-session TODO for pi — persists across all sessions and is auto-injected into every prompt. The disk-backed counterpart to branch-scoped pi todo extensions.",
+  "version": "0.5.1",
+  "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",
     "pi-extension",
@@ -35,7 +35,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; 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; do node test/$t.test.mts || exit 1; done"
   },
   "peerDependencies": {
     "@earendil-works/pi-ai": "*",
@@ -53,4 +53,4 @@
       "optional": true
     }
   }
-}
+}

package/src/archive.ts

@@ -12,6 +12,7 @@ import { migrateV2ToV3 } from "./migrate.ts";
 import type { Todo } from "./todo-store.ts";
 import { loadConfig } from "./config.ts";
 import { loadStore, saveStore, TodoError } from "./todo-store.ts";
+import { backupFile, snapshotOnDrop, appendAudit, countTodosInFile } from "./backup.ts";
 
 export interface ArchiveStore {
   version: 3;
@@ -61,6 +62,11 @@ export function loadArchive(): ArchiveStore {
 export function saveArchive(store: ArchiveStore): void {
   store.updatedAt = now();
   const path = getArchivePath();
+  // v0.5.1 write-audit + backup (post data-loss hardening).
+  const before = countTodosInFile(path);
+  const after = store.todos.length;
+  backupFile(path);
+  const dropSnap = snapshotOnDrop(path, before, after);
   const dir = dirname(path);
   mkdirSync(dir, { recursive: true });
   const tmp = `${path}.tmp`;
@@ -71,6 +77,7 @@ export function saveArchive(store: ArchiveStore): void {
     // some filesystems ignore mode bits
   }
   renameSync(tmp, path);
+  appendAudit("archive", before, after, dropSnap);
 }
 
 export interface PruneInput {

package/src/backup.ts

@@ -0,0 +1,83 @@
+// Write-audit + backup for armory-todo (v0.5.1 hardening, post v0.2.0 data-loss
+// incident). Every saveStore / saveArchive now:
+//   1. backs up the current file to <path>.bak (rolling previous version — the
+//      immediate recovery target);
+//   2. if the save would DROP the todo count (after < before), also snapshots
+//      the pre-write file to <path>.bak-drop-<ts> (timestamped, never
+//      overwritten — the preserved pre-wipe state, the trap);
+//   3. appends one compact line to <TODO_DIR>/todo-audit.log (counts only, no
+//      todo content — privacy-safe) flagging drops with ⚠ DROP.
+//
+// This means the v0.2.0-style "migration wiped the store" incident is now
+// recoverable: the .bak-drop-<ts> holds the pre-wipe state, and the audit log
+// names the moment + the count delta.
+//
+// Pure fs helpers (no pi imports) so they're unit-testable in isolation.
+
+import { chmodSync, copyFileSync, existsSync, mkdirSync, appendFileSync, statSync, readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { getTodoDir } from "./paths.ts";
+
+/** Copy the current file to <path>.bak (rolling previous version). No-op if the
+ *  file doesn't exist yet (first-ever save). Returns true if a backup was made. */
+export function backupFile(path: string): boolean {
+  if (!existsSync(path)) return false;
+  try {
+    copyFileSync(path, `${path}.bak`);
+    return true;
+  } catch {
+    // best-effort; a failed backup must not block the write
+    return false;
+  }
+}
+
+/** If a count drop is detected (after < before), snapshot the pre-write file to
+ *  <path>.bak-drop-<ts> (preserved — never overwritten by the rolling .bak).
+ *  Returns the snapshot path, or null if no snapshot was taken. */
+export function snapshotOnDrop(path: string, before: number, after: number): string | null {
+  if (before <= after) return null;            // no drop (growth or steady)
+  if (!existsSync(path)) return null;          // nothing to snapshot
+  const ts = new Date().toISOString().replace(/[:.]/g, "-");
+  const snap = `${path}.bak-drop-${ts}`;
+  try {
+    copyFileSync(path, snap);
+    return snap;
+  } catch {
+    return null;
+  }
+}
+
+/** Append one compact audit line. Counts only (no todo content). Flags drops.
+ *  `box` is "todo" or "archive" (which file was saved). */
+export function appendAudit(box: "todo" | "archive", before: number, after: number, dropSnap: string | null): void {
+  try {
+    const dir = getTodoDir();
+    mkdirSync(dir, { recursive: true });
+    const logPath = join(dir, "todo-audit.log");
+    const ts = new Date().toISOString();
+    const delta = after - before;
+    const flag = after < before ? " [⚠ DROP]" : "";
+    const snap = dropSnap ? ` snap=${dropSnap.split("/").pop()}` : "";
+    appendFileSync(logPath, `${ts} save ${box}.json ${before}→${after} ${delta >= 0 ? "+" : ""}${delta}${flag}${snap}\n`, { encoding: "utf8" });
+    try { chmodSync(logPath, 0o600); } catch { /* fs may ignore mode */ }
+  } catch {
+    // best-effort; audit must not block the write
+  }
+}
+
+/** Count todos in an existing store file (for the before-count). Returns 0 if the
+ *  file is missing/unreadable/not a valid store. */
+export function countTodosInFile(path: string): number {
+  try {
+    if (!existsSync(path)) return 0;
+    const raw = statSync(path).size === 0 ? null : readJson(path);
+    if (!raw || !Array.isArray(raw.todos)) return 0;
+    return raw.todos.length;
+  } catch {
+    return 0;
+  }
+}
+
+function readJson(path: string): any {
+  return JSON.parse(readFileSync(path, "utf8"));
+}

package/src/caps.ts

@@ -0,0 +1,71 @@
+// Caps enforcement primitives for armory-todo (v0.5.0). Pure — no disk I/O,
+// no config/registry loads. Callers (addTodo/updateTodo/renderOpenBlock) load
+// state and pass it in, so these are unit-testable in isolation.
+//
+// Two caps:
+//   - notes  : per-todo byte ceiling (health.maxNotesBytes), hard-reject at write.
+//   - project: per-project open-count ceiling (registry maxOpen), hard-reject
+//              on add + project-move (only for open/in_progress todos).
+// Both throw TodoError BEFORE any store mutation (callers ensure atomicity).
+//
+// Circular import note: caps.ts imports TodoError/Todo (types) from
+// todo-store.ts; todo-store.ts imports the cap functions. Safe — no module
+// touches another's exports at top level; all usage is inside functions, so
+// both are fully loaded by call-time.
+
+import { TodoError, type Todo } from "./todo-store.ts";
+import type { ProjectRegistry } from "./registry.ts";
+
+/** Human-readable byte size for error messages: 512 -> "512B", 2048 -> "2.0KB". */
+function formatBytes(n: number): string {
+  if (n < 1024) return `${n}B`;
+  if (n < 1024 * 1024) return `${(n / 1024).toFixed(1)}KB`;
+  return `${(n / (1024 * 1024)).toFixed(1)}MB`;
+}
+
+/** Throw if notes exceeds the byte cap. Byte-length (not char-length): notes
+ *  can hold Unicode ("é" = 2 bytes UTF-8). A maxBytes of 0 means "no notes
+ *  allowed" (only empty notes pass). Negative maxBytes rejects everything
+ *  (treated as a misconfig; config load clamps negative/NaN to the default). */
+export function checkNotesCap(notes: string, maxBytes: number): void {
+  const bytes = Buffer.byteLength(notes, "utf8");
+  if (bytes > maxBytes) {
+    throw new TodoError(
+      `notes ${formatBytes(bytes)} > max ${formatBytes(maxBytes)} (maxNotesBytes ${maxBytes}) — trim the detail or split into multiple todos`,
+    );
+  }
+}
+
+export interface ProjectCapInput {
+  project: string;        // target project name (already trimmed by caller)
+  currentOpen: number;     // target's current open count, NOT counting the would-be-added/moved todo
+  maxOpen: number | null;  // from the registry entry; null = uncapped
+}
+
+/** Throw if adding one more open todo to `project` would exceed its cap.
+ *  `maxOpen === null` -> no-op (uncapped). The cap is on the `open` count only
+ *  (matches the PROJECT_OVER health definition; in_progress does not count). */
+export function checkProjectCap({ project, currentOpen, maxOpen }: ProjectCapInput): void {
+  if (maxOpen === null) return;
+  if (currentOpen + 1 > maxOpen) {
+    throw new TodoError(
+      `project '${project}' is at maxOpen ${maxOpen} (${currentOpen} open) — close/park one, or raise maxOpen via the /todo panel (Projects tab -> Set maxOpen), before adding`,
+    );
+  }
+}
+
+export interface OverBudgetProject { name: string; open: number; maxOpen: number; }
+
+/** Projects whose open count exceeds their explicit maxOpen (maxOpen non-null).
+ *  Pure; consumed by renderOpenBlock's over-cap summary. `liveTodos` is the
+ *  full live store array. Open is counted here (status === "open"). Sorted by
+ *  breach depth (open - maxOpen) desc, then name asc. */
+export function overBudgetProjects(liveTodos: Todo[], registry: ProjectRegistry): OverBudgetProject[] {
+  const out: OverBudgetProject[] = [];
+  for (const entry of registry.projects) {
+    if (entry.maxOpen === null) continue;
+    const open = liveTodos.filter((t) => t.project === entry.name && t.status === "open").length;
+    if (open > entry.maxOpen) out.push({ name: entry.name, open, maxOpen: entry.maxOpen });
+  }
+  return out.sort((a, b) => (b.open - b.maxOpen) - (a.open - a.maxOpen) || a.name.localeCompare(b.name));
+}

package/src/config.ts

@@ -25,6 +25,7 @@ export interface HealthConfig {
   archiveMax: number;
   archiveOldDays: number;
   perProjectDefaultMax: number;  // v0.4.0: per-project PROJECT_LARGE threshold (advisory)
+  maxNotesBytes: number;         // v0.5.0: per-todo notes byte cap (hard-reject at add/update)
 }
 
 export interface TodoConfig {
@@ -48,6 +49,7 @@ export const DEFAULT_CONFIG: TodoConfig = {
     archiveMax: 200,
     archiveOldDays: 180,
     perProjectDefaultMax: 8,
+    maxNotesBytes: 8192,
   },
 };
 
@@ -72,6 +74,9 @@ export function loadConfig(): TodoConfig {
     // Merge with defaults so new fields get filled in on upgrade.
     const health = { ...DEFAULT_CONFIG.health, ...parsed.health };
     if (health.perProjectDefaultMax === undefined) health.perProjectDefaultMax = DEFAULT_CONFIG.health.perProjectDefaultMax;
+    if (health.maxNotesBytes === undefined || typeof health.maxNotesBytes !== "number" || Number.isNaN(health.maxNotesBytes) || health.maxNotesBytes < 0) {
+      health.maxNotesBytes = DEFAULT_CONFIG.health.maxNotesBytes;
+    }
     return {
       version: 1,
       prune: { ...DEFAULT_CONFIG.prune, ...parsed.prune },

package/src/health.ts

@@ -28,6 +28,7 @@ export interface ArchiveHealth {
 export interface NotesBytes {
   total: number;
   max: number;
+  maxId: string | null;   // v0.5.0: id of the todo with the largest notes (null if no todos)
   avg: number;
 }
 
@@ -35,6 +36,7 @@ export type HealthFlag =
   | "ACTIVE_LARGE" | "ACTIVE_STALE"
   | "PARKED_LARGE" | "PARKED_STALE"
   | "ARCHIVE_LARGE" | "ARCHIVE_OLD"
+  | "NOTES_OVER"
   | "PROJECT_OVER" | "PROJECT_TYPO" | "PROJECT_LARGE" | "PROJECT_STALE";
 
 export interface ProjectHealth {
@@ -84,12 +86,21 @@ export function healthReport(): HealthReport {
   const archiveOld = archive.todos.filter((t) => t.closedAt && daysAgo(t.closedAt) > h.archiveOldDays).length;
 
   // notes bytes across active + parked (archived excluded — sealed history).
+  // v0.5.0: track the worst-offender id so the NOTES_OVER suggestion is actionable.
   const apTodos = [...openTodos, ...ipTodos, ...parkedTodos];
-  const notesSizes = apTodos.map((t) => Buffer.byteLength(t.notes, "utf8"));
+  let maxId: string | null = null;
+  let maxSize = 0;
+  let totalBytes = 0;
+  for (const t of apTodos) {
+    const s = Buffer.byteLength(t.notes, "utf8");
+    totalBytes += s;
+    if (s > maxSize) { maxSize = s; maxId = t.id; }
+  }
   const notesBytes: NotesBytes = {
-    total: notesSizes.reduce((a, b) => a + b, 0),
-    max: notesSizes.length ? Math.max(...notesSizes) : 0,
-    avg: notesSizes.length ? Math.round(notesSizes.reduce((a, b) => a + b, 0) / notesSizes.length) : 0,
+    total: totalBytes,
+    max: maxSize,
+    maxId: apTodos.length ? maxId : null,
+    avg: apTodos.length ? Math.round(totalBytes / apTodos.length) : 0,
   };
 
   const active: ActiveHealth = {
@@ -102,6 +113,7 @@ export function healthReport(): HealthReport {
 
   const flags: HealthFlag[] = [];
   if (actionable.length > h.activeMaxOpen) flags.push("ACTIVE_LARGE");
+  if (notesBytes.max > h.maxNotesBytes) flags.push("NOTES_OVER");
   if (activeStale > 0) flags.push("ACTIVE_STALE");
   if (parkedTodos.length > h.parkedMax) flags.push("PARKED_LARGE");
   if (parkedStale > 0) flags.push("PARKED_STALE");
@@ -113,6 +125,10 @@ export function healthReport(): HealthReport {
   if (activeStale > 0) suggestions.push(`active: ${activeStale} open TODOs untouched for ${h.activeStaleDays}d → park or close them`);
   if (parkedStale > 0) suggestions.push(`parked: ${parkedStale} parked > ${h.parkedStaleDays}d → restore or hard-prune`);
   if (actionable.length > h.activeMaxOpen) suggestions.push(`active: ${actionable.length} open+in_progress (max ${h.activeMaxOpen}) → close or park some before adding more`);
+  if (notesBytes.max > h.maxNotesBytes) {
+    const id = notesBytes.maxId ?? "<id>";
+    suggestions.push(`notes: largest note ${notesBytes.max}B > cap ${h.maxNotesBytes}B (on ${id}) → trim via todo update ${id} notes:…`);
+  }
 
   // per-project flags (v0.4.0)
   const archivedDone = archive.todos.filter((t) => t.status === "done");

package/src/panel-data.ts

@@ -60,6 +60,7 @@ export function configToSettingItems(cfg: TodoConfig): SettingItem[] {
     { id: "parkedStaleDays", label: "Parked stale (days)", currentValue: String(cfg.health.parkedStaleDays), values: ["30", "60", "90"], description: "Bloat flag when parked longer than this." },
     { id: "archiveMax", label: "Archive max", currentValue: String(cfg.health.archiveMax), values: ["100", "200", "500"], description: "Bloat flag when archive exceeds this." },
     { id: "archiveOldDays", label: "Archive old (days)", currentValue: String(cfg.health.archiveOldDays), values: ["90", "180", "365"], description: "Bloat flag when archive items older than this." },
+    { id: "maxNotesBytes", label: "Notes max bytes", currentValue: String(cfg.health.maxNotesBytes), values: ["2048", "4096", "8192", "16384", "32768"], description: "Hard reject at add/update when notes exceeds this (bytes). 0 = no notes allowed." },
   ];
 }
 

package/src/panel.ts

@@ -392,6 +392,7 @@ export class TodoPanel extends Container {
       case "parkedStaleDays": return String(c.health.parkedStaleDays);
       case "archiveMax": return String(c.health.archiveMax);
       case "archiveOldDays": return String(c.health.archiveOldDays);
+      case "maxNotesBytes": return String(c.health.maxNotesBytes);
       default: return "";
     }
   }
@@ -408,6 +409,7 @@ export class TodoPanel extends Container {
       case "parkedStaleDays": this.config.health.parkedStaleDays = n; break;
       case "archiveMax": this.config.health.archiveMax = n; break;
       case "archiveOldDays": this.config.health.archiveOldDays = n; break;
+      case "maxNotesBytes": this.config.health.maxNotesBytes = n; break;
     }
     saveConfig(this.config);
     this.onNotify(`Config saved: ${id} = ${value}`, "info");