pi-goal-list-loop-audit 0.35.13 → 0.35.32

package/CHANGELOG.md

@@ -1,5 +1,371 @@
 # Changelog
 
+## 0.35.32 — hermetic settings round-trip test (2026-08-22)
+
+### Fix
+  tests/auditor-extensions.test.ts depended on the developer machine having
+  ~/.pi/agent extensions to discover: on a bare CI home the discovered list
+  was empty, the handler fell back to the input prompt, and the TUI-picker
+  branch under test never ran (publish workflow failure). The test now seeds
+  a project-scope `.pi/extensions/hermetic-ext.js` so discovery is non-empty
+  on every machine; verified green under both an empty HOME and a populated one.
+
+## 0.35.31 — user-seed trust for /goal start; loop plateau no longer false-stops on a never-moved baseline (2026-08-22)
+
+### Fix 1: explicit /goal start paused by the suspicious-objective heuristic
+  Field: Screenshot_20260822_193744 — `/goal start "…because we are logged in"`
+  was parked as "Suspicious objective detected (dangling-fragment)" with a
+  repair task queued instead of dispatching. The fragment heuristics exist
+  for AGENT-authored report garbage; an explicit `/goal start` whose
+  objective is verbatim a user seed now dispatches and ledgers
+  `faulty_objective_user_seed_trusted` (/goal tweak remains available).
+### Fix 2: loop plateau vs a degenerate zero baseline
+  Field: doomtap loop stopped "plateau — best: 0" while iterations visibly
+  fixed real findings: a min-direction metric reading 0 before work starts
+  pins best at 0, so every later productive reading scores flat and burns
+  plateau slots. Flat readings now count toward plateau only once the metric
+  has demonstrably moved (an improvement on record, or best ≠ first measured
+  reading of the run); a metric that NEVER moves gets its own loud bounded
+  stop ("metric never moved …") after 2× window, not a fake plateau.
+
+## 0.35.30 — durable last-outcome retention: the final verdict stays visible (2026-08-22)
+
+### Gap
+  Field report with screenshots (email-api-compare, 2026-08-22): "goal gets
+  closed before final audit, so auditor never approves." Forensics showed the
+  lifecycle was CORRECT — every archived goal had an approving verdict — but
+  closeArchivedSlot nulled the widget slot the moment the goal archived, so
+  after the agent's turn ended the surface went completely blank and the only
+  trace of the approval was one transient toast. Returning later, "Auditor
+  verdict pending" was the last visible text: indistinguishable from closed-
+  without-audit.
+### Ship
+  - State.lastOutcome {at, ok, title, recap}: written by closeArchivedSlot on
+    every terminal slot close (approved AND aborted), overwritten per outcome.
+  - Widget: while no goal/list/loop occupies the slot, one dim retention line
+    renders for 24h — "✓ done · auditor … approved · <recap>" or "▪ ended ·
+    <reason>" — then goes silent. A live goal always outranks it.
+  - /glla wipe clears the record (clean slate means clean).
+  - Tests: tests/last-outcome-retention.test.ts (5) — render shapes, expiry +
+    garbage-timestamp safety, live-goal precedence, source pins for both
+    write and wipe-clear sites.
+
+## 0.35.29 — /glla agents: tracked-subagent panel, transcript tail, widget segment (2026-08-22, GitHub issue #15)
+
+### Gap
+  During long fan-outs the only child visibility was the widget's 3-slot
+  recent-action ring. A child that "almost completed its final report, went
+  back to check some more, then crashed" was invisible: no live status, no
+  counters, and no post-mortem trail anyone could find (issue #15).
+  Scope agreed with the user: panel + transcript tail + widget line; a live
+  activity stream was explicitly rejected as too noisy.
+### Ship
+  - getSubagentAgentsSnapshot() (goal-heartbeat.ts): read-only view of the
+    tracked-subagent probes with hung classification mirroring the watchdog
+    scan WITHOUT its counter mutation; record-frozen vs event-only evidence
+    named; degrades gracefully when the pi-subagents manager registry is
+    absent (as on currently installed versions).
+  - /glla agents: ranked table (hung > running > ended), per-child
+    tools/output/silent clocks, liveness hint on hung rows, 20-row cap with
+    an explicit trim notice. Read-only, stale-safe.
+  - /glla agents --tail <id> [--lines N]: locates the child's session file
+    in the cwd-munged session store by needle + newest mtime and prints the
+    last N entries tolerantly ([role] text, raw fallback). LOUD when nothing
+    matches — searched dir, transcript count, needles. Never resumes or
+    attaches to a child session.
+  - Widget segment: "● N agents · <busiest> silent Xm ⚠" appended to every
+    card shape via buildWidgetLines; hidden at zero tracked children.
+  - New pure module extensions/goal-agents-panel.ts; snapshot reaches
+    goal-commands via CommandDeps injection (no heartbeat import cycle).
+
+## 0.35.28 — due-wait backstop: lapsed wait pauses actually resume; "you were recovered" notice (2026-08-22, GitHub issue #16)
+
+### Root cause (field: goal paused 30min past its scheduled auto-resume while the agent narrated "the system should have auto-resumed by now")
+  Auto-resume for pauseKind "wait" relied SOLELY on in-memory timers. An
+  exhaustive map of every wait-pause site found: agent-authored waits
+  (pause_goal kind="wait") armed NO timer at all while their own copy
+  promised automatic continuation; error-brake cooldown waits were not
+  re-armed on session_start; single-slot provider-retry timers could be
+  silently clobbered by a later schedule; and no code path anywhere compared
+  wall time against pauseResumeAt outside display rendering.
+### Fix
+  The heartbeat owns the durable invariant now: every tick, a wait whose
+  pauseResumeAt lapsed >90s is re-fired — main-model recovery waits route to
+  a provider probe, everything else clears the park and dispatches one fresh
+  continuation. supervisorPaused() still freezes it under /glla pause and
+  the load hold, one attempt per (goalId:resumeAt) key prevents storms (the
+  route re-parks with a fresh resumeAt on failure), and every fire is
+  ledgered wait_pause_overdue_resume. A stale hold persisted by a previous
+  process is released when a consenting reload arrives. Issue part 2:
+  resumed goals carry an autoResumed stamp rendered as a RECOVERY NOTICE in
+  the continuation prompt — "welcome back, YOU were recovered" — so agents
+  stop waiting for an external recovery signal that already happened.
+
+## 0.35.27 — Windows auditor launch: quote only when needed, gate always first (2026-08-22, PR #17)
+
+### Field report (PR #17, reproduced on Windows 11 + pnpm global shim)
+  The detached auditor died ~0.5s after launch and retried forever: quoting
+  EVERY argument wraps a bare executable name in quotes, which changes how
+  cmd.exe resolves it and how npm/pnpm .CMD shims compute their own
+  directory -> MODULE_NOT_FOUND -> "pi exited without an agent_settled RPC
+  event" in a 60s retry loop of flashing terminal windows.
+### Fix
+  buildAuditorPiSpawnSpec now runs the WINDOWS_UNSAFE_ARG rejection on EVERY
+  argument BEFORE the quoting decision, then quotes only when tokenization
+  requires it (whitespace / cmd metacharacters / empty). Clean bare tokens
+  reach cmd.exe untouched (shims resolve; full RPC sessions work); the
+  upstream PR's variant was not mergeable as-is because its needs-quoting
+  regex also gated the unsafe-arg check, letting %/CR/LF through bare.
+  Regression tests pin all three classes through the spec builder.
+
+## 0.35.26 — zombie watchdog recognizes pi-subagents tool names (2026-08-22, GitHub issue #13)
+
+### Gap
+  The v0.35.4 subagent-wait carve-out matched only the legacy built-in names
+  (Agent / get_subagent_result / steer_subagent). The pi-subagents extension
+  registers its foreground dispatch tool as "subagent" and a blocking wait as
+  "subagent_wait", so a parent legitimately BUSY on a healthy foreground child
+  tripped the bounded abort: field report shows a child writing Postgres
+  records productively for 30 minutes while the parent was stream-silent on
+  `subagent` — zombie_run_suspected at 20m, loop_stopped + zombie_run_aborted
+  at 30m, productive work killed mid-write.
+### Fix
+  One shared SUBAGENT_WAIT_TOOL_NAMES set + isSubagentWaitCall predicate in
+  goal-heartbeat.ts, consumed by BOTH sites (zombie stand-down and wedge-alert
+  hint) so the lists cannot drift apart again. New names: "subagent",
+  "subagent_wait". Behavioral tests drive the real heartbeat tick with a real
+  tool_call event: stand-down while in flight, clean abort once it settles,
+  no blanket amnesty.
+
+## 0.35.25 — /loop resume honors the zero-stream abort park (2026-08-22, GitHub issue #14)
+
+### Gap
+  abortZombieRun parks a loop with stopReason "stopped: automatic zero-stream
+  abort — ... (iteration N preserved; /loop resume to retry)" and its message
+  promises /loop resume — but the RESUMABLE_STOP predicate in the resume
+  handler never matched that prefix. The explicit resume answered "No held
+  loop to resume"; iteration count, best value, and preserved history were
+  unreachable without re-drafting from scratch (field report: a metricless
+  24h loop parked at iteration 210 with 200 history entries).
+### Fix
+  RESUMABLE_STOP gains the "stopped: automatic zero-stream abort" prefix.
+  The explicit resume now re-arms the loop exactly as promised: fresh stall
+  window, re-armed counters, load hold released, one new dispatch — with
+  iteration/best/history intact. Control test pins that non-resumable stops
+  (e.g. bounds) stay stopped.
+
+## 0.35.24 — auditor model picker at full selector parity: forbidden-models filtering (2026-08-22, note.md Next #1)
+
+### Gap
+  The /glla -> Auditor model row already hosted the /model-style fuzzy
+  picker and persisted to the exact key resolveAuditorModel reads — but
+  unlike every main-agent flow it did NOT apply forbidden-models policy:
+  blocked models appeared in the list and the typed escape hatch accepted
+  them, yielding pins the resolver silently skips at audit time.
+### Fix
+  promptModelRef gains an excludeRefs opt threading into buildModelPickItems
+  (list-level filter) AND validating typed entries against isForbiddenModel
+  (a policy match is refused with a warning naming the ref — never saved).
+  Both auditor slots use it: Auditor model and Auditor fallback agent.
+  A pin saved by the picker is one the resolver honors; runtime skips
+  (auditor_model_fallback reason:"forbidden") remain as belt-and-suspenders.
+
+## 0.35.23 — load without autostart: cold sessions hold automation for an explicit decision (2026-08-22, note.md Next #2)
+
+### Root cause
+  shouldAutoResumeOnSessionStart already demanded explicit `autoResume ===
+  true` (v0.28.21 tri-state, undefined default = HOLD) — but its only
+  consumer fed it the AGGRESSIVE-MODE COERCED value (unset -> true because
+  aggressiveMode defaults on), so stock installs auto-resumed everything on
+  every session load despite the documented default. Three further paths
+  bypassed the consent entirely.
+### Fixes
+  - Load consent now reads the RAW global autoResume setting; aggressive
+    mode keeps owning its caps only. Default (unset/false) = restore and
+    DISPLAY state, hold automation.
+  - New durable loadHoldAt state engages through the SAME freeze gates as
+    /glla pause (continuation dispatch, loop ticks, heartbeat refires,
+    recovery timers); released by any explicit work command (/goal resume,
+    /list resume, /list next, /loop resume|start, new goal creation),
+    each release ledgered load_hold_released. Heartbeat host-loss
+    supervision stays armed under the hold — a held plane is never an
+    unprobed idle plane.
+  - Closed consent bypasses: different-pid crash successors no longer
+    auto-resume held loops or replay journals as automation (same-process
+    /reload successors keep continuity); parked completion-audit claims no
+    longer auto-retry on a bare cold start (the main-model-recovery one-
+    shot retry keeps its pinned consent).
+
+## 0.35.22 — a queued item blocked by a live loop is loud and self-heals at loop end (2026-08-22)
+
+### suspicious-unstartable-repair-card fix (note.md Next #3)
+  Field (screenshots 20260821_114109/114210/134442/134645): /goal start of a
+  lowercase-fragment objective paused the goal and queued a repair task; the
+  card said "/list next starts the preserved repair/replan task" — but with
+  the Chrome-Bridge loop owning the surface, activateNextListItem's
+  one-active-thing guard refused activation LEDGER-ONLY: unstartable AND
+  invisibly blocked. Two fixes:
+  - the refusal now notifies with the queued objective and the way out
+    ("/loop stop … then /list next"), and the ledger names what stayed queued;
+  - when a loop ends by ANY route (/loop stop, /loop finish, plateau/bounds
+    stop), resumeQueuedListAfterLoopEnd retries list activation when no goal
+    owns the surface — the blocked entry starts instead of staying dead.
+  Also: tests/list-invisible-restart.test.ts no longer depends on co-resident
+  module state (unique owner session + explicit reset), fixing the cross-file
+  ordering failure surfaced by audit round eight.
+
+## 0.35.21 — list queue stays visible across lifecycle boundaries (2026-08-22)
+
+### list-invisible-until-restart fix (note.md Next #4)
+  Field: a stopped/interrupted /list exec left the queue surface blank —
+  active item only, no "N waiting · up next" line — until a session
+  restart. Root cause: the sidebar renders state.list from MEMORY while the
+  durable queue is the UNION of the state ledger and the per-item
+  .queue.json sidecars (v0.34.60 disk-first writes); a plugin re-init /
+  stale-handle window reset RAM to defaults and only some later path
+  re-ran the disk merge. session_start's restore now converges memory to
+  that union immediately (hydrateListQueueFromDisk after readState), so
+  the next lifecycle boundary heals the surface without a restart; the
+  hydration notifies with a truthful count ("restored N queued list
+  item(s)"). Regression tests: sidecar-only item is hydrated AND rendered;
+  convergence is idempotent (no duplicate for items in both stores).
+
+## 0.35.20 — one bounded automatic retry for transient mechanical-check deaths (2026-08-21)
+
+### Gate resilience
+  Field (sixth audit round): the pre-audit gate died MID-RUN under machine
+  load ~30 — output ends inside a passing file, no runner summary, exit 1 —
+  while the identical tree passed green twice in isolation. Resource
+  contention, not a red suite. Mechanical check commands now get exactly ONE
+  bounded automatic retry on failure: a deterministic red command stays red
+  on both attempts (final output names the retry and preserves the second
+  attempt's diagnostics); a first-attempt transient death followed by a
+  passing retry passes with an honest `recoveredRetryNote` in the result.
+  Mirrors the v0.35.17 zero-stream auto-retry philosophy at the gate level.
+
+## 0.35.19 — load-resilient budgets for the aggressive-recovery test (2026-08-21)
+
+### Flake hardening
+  At machine load ~50 (16 cores), the aggressive no-verdict recovery test's
+  wall-clock wait budgets (2x 25s inside a 60s per-test ceiling) expired
+  before two real subprocess-based auditor retry cycles completed — while
+  the canonical full-suite run stayed green in the same conditions. Raised:
+  per-test 60s→120s, retry waits 25s→45s, state-transition waits 8s→20s.
+  Budgets only; semantics untouched (same precedent as v0.35.15's 30s→60s).
+
+## 0.35.18 — mechanical checks resolve raw runners to their canonical scripts (2026-08-21)
+
+### Spurious fast-fail fix (fourth audit round)
+  A verification contract that names a RAW RUNNER in prose ("passes under
+  `bun test`") made the deterministic pre-audit execute `bun test` bare,
+  ignoring the project's own required configuration encoded in package.json
+  scripts (--parallel=1 --max-concurrency=1 --timeout; this suite shares
+  module state process-wide by design and serializes deliberately). The bare
+  invocation failed 6 tests + 5 nested-test errors while the canonical gate
+  was green twice — a spurious fast-fail of finished work. Mechanical check
+  commands that are exactly a raw runner invocation (bun test / vitest /
+  jest, no extra args) now resolve to the package script that wraps them;
+  narrower runs and non-runner programs pass through untouched. Pure resolver
+  (`resolveCanonicalRunnerCommand`) lives in goal-loop-backoff.ts with unit
+  tests; bunfig cannot express the required flags (verified empirically:
+  `[test] timeout` is not honored on bun 1.3.14).
+
+## 0.35.17 — zero-stream abort gains ONE bounded automatic retry; tag backfill (2026-08-21)
+
+### Post-accept hang self-heal (note.md Next §1)
+  Turns dispatched by accepting a Confirm dialog hung with zero provider
+  stream activity often enough that users repeatedly returned to parked
+  "action needed" sessions (field screenshot 20260821_152311). The watchdog's
+  bounded abort was correct; what was missing is self-heal. The FIRST silence
+  of a zero-stream streak now arms exactly ONE automatic retry ~90s after the
+  park — the parked goal/list item/loop auto-resumes through the durable
+  continuation machinery and one fresh dispatch goes out. A SECOND consecutive
+  silence refuses further retries (`zombie_auto_retry_refused_streak`) and
+  parks permanently for manual resume; real stream activity between aborts
+  resets the streak so an independent later hang earns its own single retry.
+  `/glla pause` freezes the retry like every other automatic side-effect;
+  the timer only clears a pause carrying exactly the watchdog's own reason
+  (a newer manual/recovery pause supersedes it); the heartbeat's one-shot
+  abort latch is released on retry dispatch so a fully-silent retry can still
+  be re-aborted. Pure streak decision lives in goal-loop-backoff.ts
+  (`zombieRetryDecision`) with unit tests; behavioral coverage drives the
+  full hang→abort/park→auto-resume→re-dispatch arc plus the double-hang and
+  pause-during-waystation paths (tests/post-accept-hang-retry.test.ts).
+
+### Version tags backfilled
+  All 41 released versions missing their `v<version>` git tag (v0.34.20 …
+  v0.35.16) were tagged at the historical commit whose package.json carried
+  that exact version and pushed to all remotes. Additive-only — no history
+  rewrite.
+
+### README currency pass
+  Documents the v0.35.15 per-phase glyphs/activity meter/silent-stretch
+  footer, `/glla pause`, and the v0.35.17 zero-stream auto-retry.
+
+## 0.35.16 — mechanical pre-audit gate no longer kills legitimate long checks (2026-08-21)
+
+### Deterministic pre-audit timeout fix
+  `runMechanicalPreAuditChecks` executed every contract command under a
+  hard 60-second `execFileSync` ceiling — but this repo's own contract
+  command (`npm run release:check`) legitimately needs ~3 minutes. Every
+  deterministic pre-audit therefore fast-failed with a truncated
+  head-of-output report showing only startup logs (two field rounds:
+  2026-08-21 14:17 and 16:01), burning two auditor cycles on a gate that
+  could never pass inside its own bound. The default bound is now 10 minutes
+  — still a hang guard, no longer an honest-slow-work guard. Failed output
+  keeps the TAIL (where failures live) instead of the head, truncation is
+  labeled, and a timeout kill is bannered as such instead of masquerading as
+  an exit-code-1 test failure.
+
+## 0.35.15 — glla status-surface UX: visual footer, /glla pause, proactive quiet notify (2026-08-21)
+
+### Visual status footer
+  The auditing footer now leads each auditor phase with a distinct glyph
+  (queued ⋯ · running ▶ · quiet ◌ · blocked ⛔ · awaiting-verdict ✓) and a
+  compact draining activity meter (▰▱) that empties as worker silence grows
+  toward the quiet threshold. A glance answers "is the audit alive?" without
+  reading the sentence.
+
+### /glla pause | resume — broad supervisor freeze
+  `/glla pause` freezes ALL automatic machinery — heartbeat re-arms, stale
+  probes, zombie cleanup, main-model recovery probes, automatic completion-
+  audit recovery, continuation dispatch, loop ticks, and the proactive quiet
+  notification — while leaving the active goal/list item/loop and any
+  detached worker untouched. The flag persists via `supervisorPausedAt`, so a
+  session restart cannot silently re-arm machinery the user explicitly
+  stopped. `/glla resume` clears it first, then resumes whatever else is
+  resumable, and never follows with a misleading "Nothing to resume". Manual
+  user commands always still work.
+
+### Proactive auditor quiet reporting
+  Entering the quiet phase (~3 min of zero worker activity) now fires exactly
+  ONE warning notify instead of only recoloring the status chip — the field
+  complaint was an 8-minute silent stretch the user only discovered after the
+  fact. Once activity resumes, the footer shows "silent Xm then resumed" for
+  10 minutes so a missed silence stays visible.
+
+### Persistence fix (latent bug)
+  `persistStateLine` never serialized `lastCompactionAt` despite v0.34.97's
+  comment claiming it did — the ⏳ compacting… chip silently lost its reload
+  survival. Both epoch fields now ride the state line with explicit nulls so
+  ledger merges clear them correctly.
+
+## 0.35.14 — full extension audit hardening (2026-08-21)
+
+### Verification and lifecycle integrity
+  Mechanical contract checks now run through a shell-free literal-argument
+  boundary, auditor verdicts require one final terminal marker, and regression
+  shield references must appear inside `<evidence>`. Invalid persisted IDs are
+  rejected at state hydration and filesystem boundaries. Child extension
+  factories no longer claim the host API or start timers before an admitted
+  `session_start`; completion approval cannot report success when terminal
+  archiving fails, and branch-mode loop resumes refuse the wrong branch.
+
+### Release contract
+  Published documentation includes the linked planning files, the workflow
+  runs the release contract on pushes and pull requests, and release tooling
+  uses pinned Node/npm versions.
+
 ## 0.35.13 — stale-API recovery loop fix (2026-08-20)
 
 ### Stale-handle recovery correctness

package/INSTALL.md

@@ -52,7 +52,7 @@ Then the other two modes:
 
 ## Install from source (developers)
 
-Prerequisites: Node 22+ and bun (the test runner — `bun test`), pi-coding-agent, TypeScript 5.9+ (for `tsc --noEmit`).
+Prerequisites: Node 22.19.0+ and bun (the test runner — `bun test`), pi-coding-agent, TypeScript 5.9+ (for `tsc --noEmit`).
 
 ```bash
 git clone https://github.com/DraconDev/pi-goal-list-loop-audit.git   # or use the local dir
@@ -111,8 +111,8 @@ a file or committed — narration alone is the narrate-but-don't-ship loop)
 Why it changed: the v0.24.0 single-signal detector (same tool + same
 result hash 3×) killed two real user loops that were shipping work with
 stable verification output — stable verification is the GOAL state of a
-metricless loop, not the stuck state. Design doc:
-`audit/STUCK-DETECTION-REWORK-2026-07-24.md`. `/loop start toolsamerepeat=0`
+metricless loop, not the stuck state. See `docs/DESIGN.md` for the shipped
+design overview. `/loop start toolsamerepeat=0`
 disables the legacy check entirely; `/loop finish [reason]` ends a loop
 cleanly with stopReason `completed: <reason>` (distinct from
 stuck/plateau/stopped-by-user).

package/LIST-PHILOSOPHY.md

@@ -0,0 +1,90 @@
+# List philosophy — the three-mode hierarchy
+
+pi-goal-list-loop-audit ships three loops. They are NOT redundant — each
+has a **distinct source of long-running-ness**:
+
+| Mode | Item size | Long-running by | Typical lifetime |
+|---|---|---|---|
+| `/goal` | ONE big multi-hour task | **Scope** | Hours |
+| `/list` | N items × short (minutes each) | **Queue depth** | Hours → days → weeks |
+| `/loop` | 1 metric × infinite polish | **Bounds** | Until plateau/stop/finish |
+
+## `/goal` — one big long task
+
+`/goal` is the multi-hour mode. Its long-running property is **scope**:
+one task that spans multiple agent runs, requires deep research, or would
+take hours end-to-end. It ends only when the isolated auditor approves
+the verification contract. If your work fits in a single agent run — a
+focused change, one audit, a small refactor — it belongs in `/list`.
+
+## `/list` — hundreds of short items
+
+`/list` items are **short tasks, not multi-hour objectives**. Each item
+should fit comfortably in a single agent run: minutes of work, a single
+focused change. The list's long-running property is **queue depth** — the
+queue can hold hundreds of items, activated one at a time, pushed over
+days or weeks. An item longer than ~30 minutes probably wants breaking
+up; much longer and it wants `/goal`.
+
+`/list depth` shows the long-running state: queue depth, oldest item age,
+and average item duration from your archived list items.
+
+## `/loop` — metric-driven infinite polish
+
+`/loop` improves ONE metric forever. Its long-running property is
+**bounds**: it ends on plateau, on bounds (max iterations / time /
+tokens), on `/loop stop`, or on `/loop finish` (graceful stop after the
+current iteration).
+
+## The wrapper-goal anti-pattern (why this doc exists)
+
+Real incidents, 2026-07-24, two projects on the same day:
+
+> "Close every weak point in `docs/per-screen-weak-points.md` (76 items,
+> one commit each)" and "land all 40 findings as a tasklist, ordered by
+> ROI" — each folded into **ONE** list item with an **aggregate**
+> verification contract ("≥ 76 commits with `CLOSED:`", "≥ 32 fix(Wn)
+> commits").
+
+The work got done; the auto-committer squashed intermediate commits; the
+literal commit count failed; the isolated auditor **correctly
+disapproved** finished work. The failure was at step 1 — task
+designation — not at the audit.
+
+The fix: **N independent short items → N `/list` items**, each closing
+exactly ONE finding with its own per-item contract ("close IMP-AUD3-68:
+`Map.svelte:1528` missing `role`"). Per-item contracts are impossible to
+squash. Any aggregate re-audit becomes the FINAL `/goal`, not the first.
+
+Since v0.25.3 the drafting flow detects this shape ("N items" + "each" +
+"one commit") and steers you to `items[]` — see the cross-recommend
+block in `prompts/goal-loop-draft.md`.
+
+Since v0.26.0 the **Reviewer** is the post-completion glue layer across
+all three modes' terminal states: it converts completion findings into
+`/list` items (bug/refactor, no Confirm), proposes architectural work as
+`/goal` (Confirm), fires a regression-scan audit on clean completions,
+and notifies + idles otherwise. See `INSTALL.md` "Reviewer".
+
+## Audit Cadence: Why Every `/list` Task is Audited
+
+Auditing occurs at the completion boundary of **every single `/list` task** (via the detached isolated auditor) before the next item in the queue can activate.
+
+While auditing every item requires rigorous verification, it prevents **queue drift**:
+- In a 50-item list, an unverified error in item #2 would otherwise silently corrupt the codebase, causing items #3 through #50 to fail or build on broken invariants.
+- Per-task auditing ensures each item represents a rock-solid, verified invariant before the next task begins.
+
+## Single-Trunk Execution Law & Parallelization
+
+### Why "Main-Only" Outperforms Branch Swarms in Autonomous Loops
+Speculative feature branching across autonomous subagents creates **stale context bubbles** and **merge collision debt**:
+1. Agent A on branch-1 and Agent B on branch-2 both read from snapshot $T_0$.
+2. Once Agent A lands a commit, Agent B is working on an obsolete codebase without knowing it.
+3. Merging parallel LLM branches frequently causes semantic regressions and broken invariants.
+
+### The Single-Trunk Operating Rule:
+* **Serial Queue on `main`**: All queue items drain sequentially on the single primary working tree. Item $N+1$ always executes with 100% truthful, up-to-date context left by item $N$.
+* **Transactional Green-or-Revert**: Every task either lands green (verified by tests and the detached auditor) and commits, or cleanly rolls back on `main` before the next backlog item is touched.
+* **Safe Subagent Parallelism**: Subagents are used for **read-only research fan-out** (e.g. concurrent `Explore` queries across subsystems in a single turn) or standalone verification, rather than speculative mutating branches.
+
+See `INSTALL.md` for the command surface.