pi-goal-list-loop-audit 0.38.71 → 0.38.91

package/CHANGELOG.md

@@ -1,5 +1,106 @@
 # Changelog
 
+## 0.38.91 — Tool descriptions enumerate plan/audit/verify/add (2026-09-21)
+
+- `/goal plan`, `/goal audit`, `/goal verify`, `/list plan`, and `/list add` existed but were undiscoverable from the tool descriptions. Both descriptions now enumerate them with one-line roles; a pin keeps the enumerations (audit/POST-090-IMPROVEMENT-SWEEP-2026-09-21.md).
+
+## 0.38.90 — Monitoring visuals: standby reasons go dim (2026-09-21)
+
+- Paused-on-standby cards rendered background-agent status narration in warning yellow like errors. Standby reasons now render dim like waits and cap at 2 wrapped rows (audit/MONITORING-VISUALS-2026-09-21.md).
+
+## 0.38.89 — UI polish finale: stats usage, header prefix, status→timeline pointer (2026-09-21)
+
+- `/glla stats <typo>` now names the usage (`outcomes | challenges | premature | json | project=<path>`) instead of silently rendering the default table; the JSON path stays total for machine readers.
+- The stats table header carries the `/glla` prefix like the stats error paths (`/glla stats …`).
+- The `/goal status` card ends with a `Trail: /goal timeline` pointer to its slow twin.
+
+## 0.38.88 — Pi-shim isolation: per-file process-state reset (2026-09-21)
+
+- New `__testOnlyResetProcessState()` composite invokes all 17 latch resets, and the test preload calls it before each file — per-file isolation is now structural instead of 99 files hand-picking resets (21 picked none). Membership is pinned: a future reset that bypasses the composite fails the suite (audit/PI-SHIM-ISOLATION-2026-09-21.md).
+
+## 0.38.87 — Globals retirement slice 2: 24 ambient slots deleted (2026-09-21)
+
+- The runtime-globals registry drops 207 → 183: 11 `__testOnly*` hooks, `classifySessionHandleInvalidation`, `ownerFilePath`, `recentActions`, `COMPACT_FIRST_NUDGE_PERCENT`, three settings-UI helpers, and six pin-only constants — every consumer already imports directly, so only the ambient slots delete. Two test files switch from the globalThis path to direct imports (audit/GLOBALS-RETIREMENT-SLICE-2-2026-09-21.md).
+
+## 0.38.86 — Docs: architecture overview + promotion contract (2026-09-21)
+
+- New `docs/ARCHITECTURE.md`: GLLA in 20 minutes — entry/runtime, the three loops, the audit lifecycle, persistence, and the test suite, every claim grounded in source (stage names, handler counts, and ledger-type counts verified, not remembered).
+- New `docs/PROMOTION-CONTRACT.md`: the list item → goal → archive seam diagrammed and pinned — activate, archive, auto-advance, abort/no-advance, and the one-active-thing rule.
+- Repair: v0.38.85's `timeline` subcommand broke the no-hardcoded-guidance pin (the `/goal` tool description is an allowed surface map; its allowlist didn't know the new subcommand). The full-suite gate caught it; the pin now tracks the enumeration.
+
+## 0.38.85 — `/goal timeline`: one what-happened + next-action view (2026-09-21)
+
+- New `/goal timeline [N]` renders the goal's own trail — goal-scoped ledger events merged with auditHistory verdicts in time order, key types humanized (pauses, tiers, shields, consents), unknown types compact but never hidden — plus a footer naming the single next action from live state (decision to answer, resume time, open objections, or working). Read-only like `/glla log` (audit/TIMELINE-2026-09-21.md).
+
+## 0.38.84 — Mode check learns /loop: recurring seeds route to loops (2026-09-21)
+
+- `crossRecommendMode` now catches open-ended/recurring seeds (cadence words, monitor/watch, keep-X-under-Y) in goal and list drafting and steers the interview toward `/loop` — neither goals (end on approval) nor list items (close once) fit "keep doing it". Bounded-until phrasing ("until done/green") stays a goal, and aggregate seeds still win (audit/LOOP-INFERENCE-2026-09-21.md).
+
+## 0.38.83 — Lifecycle map: session_start stages extracted + numbered (2026-09-21)
+
+- The 800-line `session_start` callback is now navigable: three verbatim stages extracted into named nested helpers (`admitSessionStart`, `claimSessionRootOrNotify`, `retentionSweepAuditJobs`) and all 12 stages carry numbered banners. Behavior-identical — moved code is byte-identical except the early returns (audit/LIFECYCLE-MAP-2026-09-21.md).
+- Premise correction: the ×3 loop wiring this item assumed does not exist — one entry, one `registerGoalRuntime`, single registrations; the per-handler gates differ deliberately and the structure is intentionally source-pinned. Full extraction would fight load-bearing pins, so the map documents the stages instead of moving them.
+
+## 0.38.82 — Fast/slow suite split: `npm test` runs the fast set (2026-09-21)
+
+- The full serialized suite takes ~7 minutes — slow enough to skip. `npm test` now runs the fast set via `scripts/run-tests.mjs`: everything minus the 12 slowest files (evidence-timed in `tests/slow-files.mjs`, behavioral-orchestrator alone is ~90s). `npm run test:slow` runs those files, `npm run test:changed` runs git-affected files, and `npm run test:all` / `release:check` still run the whole suite — nothing escapes the gate (audit/TEST-SPLIT-2026-09-21.md).
+- Explicit paths always win: naming a slow file runs it (bun ignore patterns would otherwise beat explicit selection). `-t` filters pass through without tripping path detection.
+- Repair: `package-lock.json` had drifted to 0.38.78 behind three version bumps; re-synced (the `glla-version` sync test caught it on the first fast run).
+
+## 0.38.81 — Risk-tiered auditing: light tier, spot-checks, full-audit consent (2026-09-21)
+
+- Every audit now dispatches at a risk tier. Full tier = audit plus the falsification round (today's behavior); light tier = the same single-round audit with the same brief, shield, and tool floor, only round 2 skipped. Escalation-only: rework history, activity ceilings, high-stakes language, draft-time `fullAudit` consent, and `complete_goal requestFullAudit` can each push a claim UP to full; nothing pushes it down (audit/RISK-TIERS-2026-09-21.md).
+- Spot-checks: a sampled fraction of light audits (setting `auditSpotCheckRate`, default 0.1, 0 = off) silently runs full so under-tiering is caught statistically. Tier + spot mark record on every verdict; `/glla stats challenges` gains the light count and spot flip rate for calibration.
+- Invariants: light never means none, and the agent can demand full but never light. Tier decisions ledger as `audit_tier_decided` with reasons.
+
+## 0.38.80 — Challenge outcomes recorded; `/glla stats challenges` (2026-09-21)
+
+- The worker's falsification outcome (`confirmed` / `flipped` / `not-applicable` / `skipped:<reason>`) now threads through the parent boundary onto every recorded `AuditVerdict` (both settle sites), so audit quality becomes measurable instead of believed (audit/AUDIT-METRICS-2026-09-21.md).
+- New `/glla stats challenges` view (composes with `json`/`project=`): challenged/confirmed/flipped/skipped counts plus the flip rate over challenged runs only. Skipped challenges and legacy verdicts stay unknown, never zero-filled.
+
+## 0.38.79 — Schema covers runToDone; T6 green (2026-09-20)
+
+- `runToDone` joins `schemas/goal.schema.json`: v0.38.73 added the consent flag to the `Goal` interface but not to the published schema, and the T6 drift test caught it in the full suite (2457 pass / 1 fail). One additive boolean property, zero behavior change; full serial suite re-run green (audit/SCHEMA-RUNTO-DONE-2026-09-20.md).
+
+## 0.38.78 — Remove 6 dead exports; repair hourly-pin window (2026-09-20)
+
+- Free-only scope pass: 6 exported consts with zero references anywhere (including their own files) removed — `DEFAULT_HOURLY_RETRY_PROBE`, 3 `EXPLORE_DEFAULT_*` aliases, `MAX_AUTOMATIC_QUOTA_RETRY_SEC`, `isSubagentQuotaResult`. A first sweep wrongly dropped 49 own-file-used consts; caught by review before any release, fully restored, redone with the correct predicate (audit/FREE-SCOPE-PASS-2026-09-20.md).
+- Hourly source-pin window 28k → 30k: the v0.38.73 run-to-done consent block pushed both schedule calls to ~28.2k/28.5k. Calls unchanged and correctly placed; the pin's own comments document this maintenance.
+
+## 0.38.77 — Retire 15 single-module runtime globals (222 → 207, 2026-09-20)
+
+- First slice of the `globalThis` bridge retirement: 15 registry names used in exactly one module and nowhere else (no cross-module, test, script, or top-level consumers) lose their registration, ambient declaration, and typed entry. Owning modules keep their locals untouched — zero runtime behavior change (audit/GLOBALS-RETIREMENT-SLICE-2026-09-20.md).
+- Causality note: the `glla-status-ux` + `behavioral-orchestrator` combo shows 2 pre-existing order-dependent failures (v0.35.15 pause/resume notification counts); verified identical on the pre-retirement tree via worktree comparison.
+
+## 0.38.76 — Auditor challenge round: approvals earn a falsification pass (2026-09-20)
+
+- The detached worker now runs a second bounded RPC round in a fresh session whenever round 1 approves, with an adversarial brief (re-verify load-bearing claims; disapprove with specifics on any genuine gap). Outputs compose by final line: a challenge disapproval flips the verdict, a re-confirm preserves it. Disapprovals, impossibles, and failures stay single-round (audit/AUDITOR-CHALLENGE-2026-09-20.md).
+- Fail-open, recorded: a failed challenge truncates back to byte-identical round-1 output and records `skipped:<reason>` in `result.challenge` (`confirmed`/`flipped`/`not-applicable` otherwise). Cancellation still wins outright. New `challenging` progress phase with HUD labels.
+- Tradeoff: worst-case approval latency roughly doubles (same bounds per round); parent wall-timeout + retry machinery absorbs overruns as before.
+
+## 0.38.75 — Compaction survival suite; cost ceiling verified pre-existing (2026-09-20)
+
+- New `tests/compaction-survival.test.ts`: three genuine mid-run `session_compact` events followed by full detached-audit completion, plus a compact around an in-flight audit. Previously only projection shape, in-flight suppression, and settle probes were covered — nothing proved a goal still completes after real compacts (audit/COMPACTION-SURVIVAL-2026-09-20.md).
+- Cost-ceiling review: no build needed — per-goal token limits already pause with notice (opt-in via limit > 0) and loop token budgets already stop. Verified by inspection, not changed.
+
+## 0.38.74 — `/glla stats outcomes`: completion metrics per project (2026-09-20)
+
+- New `outcomes` view for `/glla stats` (composes with `json`/`project=`): done/aborted/open counts, completion rate, mean audit rounds to approval, mean wall-clock hours and tokens per completed goal, plus the run-to-done vs supervised completion split — so run-to-done mode can be judged on numbers, not belief (audit/STATS-OUTCOMES-2026-09-20.md).
+- Unknowns stay unknown: goals without timing/usage data are skipped from means, never zero-filled; pre-flag goals land in the supervised-or-legacy bucket.
+
+## 0.38.73 — Run-to-done mode: draft up front, carry to completion (2026-09-20)
+
+- New per-goal run-to-done consent at draft time: the interview asks supervised vs run-to-done, the Confirm dialog discloses the mode (auto session resume + immediate decision auto-default until complete or a hard stop), and consent is durable on the goal plus ledgered (`run_to_done_consented`). Single-goal drafts only in v1; batch/list drafts refuse the flag with guidance (audit/RUN-TO-DONE-2026-09-20.md).
+- Runtime: run-to-done goals auto-resume held work at session start without global autoResume (per-goal consent wins), auto-default every decision immediately (`run_to_done_auto_default`, same autoDefaultLog mechanics), and treat audit caps as hard stops (park, no TODO conversion). Blocked-on-external pauses still park; the auditor is never skipped; user abort always wins. Status line carries a `run to done` chip.
+- `docs/INDEX.md` version trail fixed (was pinned at v0.38.71).
+
+## 0.38.72 — Automatic audit-job retention sweep at session start (2026-09-20)
+
+- The proven-dead audit-job sweep now runs automatically at admitted-owner session start (previously manual `/glla audits health cleanup` only, which let 207 job dirs accumulate). Windowed by the existing `auditJobRetentionMs` setting, ledgered as `audit_jobs_retention_sweep` when it reaps, fail-silent by design (audit/AUDIT-JOB-RETENTION-SWEEP-2026-09-20.md).
+- Pre-convention finished audits (result.json on file, no worker lock ever written) now classify dead past the retention window instead of ambiguous forever; present-but-corrupt locks and unfinished lockless dirs stay ambiguous for operator inspection.
+- `paused-suspicious-close` settlement ceiling 10s to 30s: the close path legitimately takes ~9.4s unloaded, so the old ceiling flaked under any load.
+- Stale `goal-loop-shield.ts` header corrected (runner section documented as shell-free, matching helpers named as the pure subset).
+
 ## 0.38.71 — Decision cards lead with the action, plaque verbs deduped (2026-09-20)
 
 - Decision pause cards render the saved/action row before the numbered options, so Pi core tail truncation cuts late options and history instead of the resume path (UI survey finding 1, audit/UI-SURVEY-2026-09-20.md).

package/README.md

@@ -485,9 +485,13 @@ npm run check
 npm run release:check
 ```
 
-`npm run release:check` runs the serialized Bun suite, TypeScript, the jiti
-reproduction, offline auditor-extension validation, and npm pack. The test
-count changes as regressions are added; the useful result is `0 fail`.
+`npm test` runs the fast set (the full serialized suite minus the 12
+slowest files — ~4 minutes instead of ~7). `npm run test:slow` runs
+those slow files, `npm run test:changed` runs only git-affected files,
+and `npm run test:all` runs everything. `npm run release:check` runs
+the serialized Bun suite, TypeScript, the jiti reproduction, offline
+auditor-extension validation, and npm pack. The test count changes as
+regressions are added; the useful result is `0 fail`.
 
 For design rationale, see [`docs/DESIGN.md`](docs/DESIGN.md). For the shipped
 document index, see [`docs/INDEX.md`](docs/INDEX.md). For publishing, see

package/docs/ARCHITECTURE.md

@@ -0,0 +1,116 @@
+# Architecture: GLLA in 20 minutes
+
+Read top to bottom. Each section names the files that own it; the
+[promotion contract](PROMOTION-CONTRACT.md) covers the list→goal→archive
+seam in full.
+
+## 0. The one paragraph (1 min)
+
+GLLA is mission control for long-running Pi work: it drafts objectives
+with the user, runs them as audited goals, and verifies every completion
+with a detached auditor that never shares the worker's session. Three
+loops (`/goal`, `/list`, `/loop`) share one runtime, one ledger
+(`.pi-glla/active.jsonl`), and one rule: **one active thing at a time**.
+
+## 1. Entry and runtime (3 min)
+
+- Entry: `extensions/loops/goal.ts` → `registerGoalRuntime`
+  (`extensions/loops/goal-activation.ts`). All 17 Pi event
+  registrations (`session_start`, `agent_end`, `tool_result`, …) live
+  there; per-handler gates differ deliberately (worker vs subagent
+  vs foreign vs host-successor planes).
+- `session_start` is the lifecycle spine: 12 numbered stages from
+  admission → root ownership → retention sweep → rebind reset →
+  queue convergence → recovery prep → resume-consent → load barrier
+  → arbitration → held-loop resume → continuation release →
+  stored-claim release. Three closed stages are extracted helpers;
+  the rest stay inline and source-pinned on purpose (see
+  `audit/LIFECYCLE-MAP-*.md`).
+- Shared state: `extensions/goal-state.ts` (`state`, `replaceState`)
+  plus module-level runtime vars; cross-file sharing goes through
+  `goal-runtime-globals.ts` (being retired slice by slice).
+
+```
+Pi events ──▶ registerGoalRuntime ──▶ state + ledger ──▶ UI (status line, banners, /goal status)
+                                              │
+                                              ▼
+                                    detached auditor (separate process)
+```
+
+## 2. The three loops (5 min)
+
+- **Loop 1 `/goal`** — one objective, drafted (interview + Confirm) or
+  started, worked until the agent claims completion, then audited.
+  States: `active → auditing → complete|aborted`, with `paused`
+  overlays (decision, wait, error, blocked, standby).
+- **Loop 2 `/list`** — a durable queue of short items. Items activate
+  head-first into real goals (`policy: "list"`), complete → archive →
+  auto-advance; aborts archive without advancing; nothing ever
+  returns to the queue. Full contract: PROMOTION-CONTRACT.md.
+- **Loop 3 `/loop`** — metric loops (`LoopState` in
+  `goal-loop-forever.ts`: target, measure command, direction,
+  iteration/max/plateau/stall accounting). No `Goal`, no audit
+  verdicts — it ends on bounds, plateau, or `/loop stop`. Metricless
+  spec loops end on bounds only.
+
+One-active-thing: a live loop blocks list activation (loudly, with
+the way out); completion cascades hand the surface to the next item.
+
+## 3. The audit lifecycle (5 min)
+
+```
+complete_goal → claim → dispatch (tier) → worker (round 1 [+ challenge]) → shield → verdict → history → archive|park
+```
+
+- **Claim**: `complete_goal` persists a `PendingCompletion` (summaries,
+  Left-out, finding groups, gates, optional full-audit request).
+- **Dispatch** (`goal-loop-auditor-process.ts`): resolves the risk
+  tier (full = audit + falsification round; light = single round),
+  ledgers `audit_tier_decided`, spawns the worker with a hashed
+  `request.json`.
+- **Worker** (`scripts/goal-auditor-worker.mjs`): runs Pi `--no-session`
+  against the brief, parses the final-line verdict (`<approved/>` /
+  `<disapproved/>`), challenges approvals in a fresh session unless
+  the tier says light. Fail-open: a failed challenge yields
+  byte-identical round-1 output, recorded as `skipped:*`.
+- **Parent**: validates attempt/hash/revision, enforces the audit-tool
+  floor and the regression shield (contract items must be cited),
+  records the `AuditVerdict` (tier, challenge outcome, duration),
+  then archives on clean approval or parks with objections on
+  disapproval. Spot-checks (default 1-in-10 light audits) calibrate
+  the tiers; `/glla stats challenges` reports the flip rates.
+
+## 4. Persistence (3 min)
+
+- **Ledger** (`.pi-glla/active.jsonl`): append-only JSONL, ~340 event
+  types, the forensic trail. Stats, timeline, and recovery all read it.
+- **State**: snapshots persist the live goal/loop/list; `readState`
+  reconciles with the ledger at boundaries.
+- **Sidecars**: durable per-queue-item files; deleted before an item
+  leaves the queue so half-moves can't resurrect work.
+- **Archive** (`.pi-glla/archive/<id>.md`): exclusive-create,
+  intent-journaled, human + machine record. Terminal and immutable.
+- **Recovery**: crash-safe by construction — intent journals,
+  archive fences, revision-bound verdicts, stale-refusal instead of
+  silent overwrite. When in doubt it parks loudly, never proceeds
+  quietly.
+
+## 5. The test suite (3 min)
+
+- ~260 files, must run **serialized** (`--parallel=1
+  --max-concurrency=1`): parallel files trip Bun's nesting guard.
+- `npm test` = fast set (minus the 12 slowest, see
+  `tests/slow-files.mjs`); `npm run test:slow`, `test:changed`,
+  `test:all` cover the rest. `release:check` = full suite + tsc +
+  jiti repro + offline auditor-extension check + pack + smoke.
+- Two test kinds: **behavioral** (MockPi harness drives real code)
+  and **source pins** (`assert.match` on runtime source — order and
+  presence guards for load-bearing structure). Pins are curated; if
+  a refactor breaks one, the pin's *intent* decides whether the
+  refactor or the pin is wrong.
+
+## Where to go next
+
+- Operating: `README.md`, `docs/SETTINGS.md`, `/goal timeline`.
+- Deep design: `docs/DESIGN.md` (+ addenda), `docs/RELEASING.md`.
+- History of why: `audit/*.md` — every incident and decision, dated.

package/docs/DESIGN.md

@@ -673,6 +673,118 @@ shapes (details in CHANGELOG.md; each is pinned by tests):
 
 - **Primary scope is the cwd project**: `listAuditCollectTarget`, `projectAuditTarget`, and `auditTarget` now state "current project rooted at the cwd where pi was opened (treat any nested .git as a separate project boundary — do not walk into parent or sibling projects)". The TIGHT scout brief is "named directories under cwd" — external code outside cwd may be READ only to diagnose a failure that blocks the current project, and a finding about external code is valid only when it affects the current project (a typo in an unrelated sibling project is out of scope and never auto-queued). This closes the "audit the parent when you opened a subproject" leak observed when hellhunter was audited from the dracon-platform root and vice-versa.
 
+## Addendum v0.38.72 (retention policy)
+
+- **audit-jobs**: time-window retention, not count-capped. `auditJobRetentionMs`
+  (default 15m, max 7d) bounds how long finished audit transcripts stay
+  readable; the admitted owner sweeps proven-dead and pre-convention finished
+  dirs past the window at every session start (ledgered when it reaps).
+  A count cap was rejected: it could delete recent evidence, while the time
+  window already bounds growth (worst case ≈ one week of audits).
+- **ledger segments**: append-only history, no rotation. Rotation moves the
+  live ledger into segments; segments themselves are never compacted or
+  deleted. Disk cost is the audit trail's price and stays visible in
+  `.pi-glla/ledger-segments/`.
+
+## Addendum v0.38.73 (run-to-done mode)
+
+- **Draft up front, carry to the end.** A goal draft may carry run-to-done
+  consent: the interview asks supervised vs run-to-done, the Confirm
+  dialog discloses the mode in full view (the Confirm IS the consent),
+  and the flag is durable on the goal plus ledgered (`run_to_done_consented`).
+- **What the consent grants**: session-start auto-resume of held work
+  without global autoResume (specific beats general), and immediate
+  decision auto-default (`run_to_done_auto_default`, same autoDefaultLog
+  mechanics as the budget path). Waits already auto-continue; quota still
+  sleeps to reset.
+- **Hard stops still park**: audit disapproval caps (no TODO conversion —
+  repeated rejection means the approach is wrong), consecutive-error
+  ceilings, provider outage, user abort/pause. Blocked-on-external pauses
+  also still park: missing user input is a hard-stop-class dependency,
+  not friction. The auditor is never skipped.
+- **Visibility**: the status line carries a `run to done` chip — an
+  auto-running goal must never look supervised. Single-goal drafts only
+  in v1; list-queue items stay supervised.
+
+## Addendum v0.38.74 (outcome metrics)
+
+- **`/glla stats outcomes`** aggregates what the ledger already records:
+  done/aborted/open, completion rate, mean audit rounds to approval,
+  mean wall-clock hours and tokens per completed goal, and the
+  run-to-done vs supervised completion split. Unknowns stay unknown
+  (skipped from means, never zero-filled); pre-flag goals land in the
+  supervised-or-legacy bucket. The point is comparative: mode and
+  process changes get judged on numbers.
+
+## Addendum v0.38.76 (auditor challenge round)
+
+- **Approvals earn a falsification pass.** The worker runs a second bounded
+  RPC round in a fresh session (no anchoring on round-1 reasoning) with an
+  adversarial brief. Final-line verdict composition: challenge disapproval
+  flips, re-confirm preserves; the shield keeps reading round-1's evidence
+  block (first match wins). Only approvals challenge — disapprovals
+  already force rework.
+- **Fail-open, recorded.** A failed challenge truncates to byte-identical
+  round-1 output (`result.challenge: skipped:<reason>`); cancellation
+  wins outright (`ok:false`, no fallback). Worst-case approval latency
+  roughly doubles; parent timeout/retry absorbs overruns.
+
+## Addendum v0.38.80 (audit metrics)
+
+- **Challenge outcomes are recorded, then judged.** The falsification
+  outcome threads onto every `AuditVerdict`, and `/glla stats
+  challenges` reports confirmed/flipped/skipped plus the flip rate over
+  challenged runs. Same unknowns-stay-unknown rule as outcomes: skipped
+  rounds and legacy verdicts never join the denominator. The flip rate
+  is the calibration signal for risk-tiered auditing: it says whether
+  round 2 earns its latency.
+
+## Addendum v0.38.81 (risk-tiered auditing)
+
+- **Tiers differ by one round.** Full = audit plus falsification round;
+  light = the identical single-round audit (same brief, shield, tool
+  floor), round 2 skipped via `challenge: false` in the worker request.
+  Light never means none — that invariant is the design's spine.
+- **Escalation-only resolution.** The pure `resolveAuditTier` accumulates
+  full-tier reasons (draft consent, agent request, rework history,
+  activity ceilings, high-stakes vocabulary) and nothing pushes a claim
+  down. Agent-written text is read for escalation only. Computed per
+  dispatch through the shared `resolveClaimAuditTier` so both dispatch
+  paths tier identically; every decision ledgers as
+  `audit_tier_decided` with reasons.
+- **Spot-checks close the loop.** `auditSpotCheckRate` (default 0.1)
+  silently escalates sampled light audits; verdicts carry the tier and
+  spot mark, and the challenges view reports the spot flip rate — the
+  calibration signal for the v1 ceilings and vocabulary.
+
+## Addendum v0.38.82 (fast/slow suite split)
+
+- **The everyday loop is fast; the gate is whole.** `npm test` excludes
+  the 12 evidence-timed slow files via repeated bun
+  `--path-ignore-patterns` (comma-separated does not union); `test:slow`
+  runs them; `test:all` and `release:check` still run everything.
+  Explicit test paths drop the exclusion — naming a file means running
+  it. The slow list (`tests/slow-files.mjs`) carries per-file timings
+  and is validity-checked by `tests/test-split.test.ts`.
+
+## Addendum v0.38.83 (lifecycle map)
+
+- **Navigate, don't restructure.** The `session_start` callback's 12
+  stages are numbered in banners; the three closed/narrow stages
+  (admission gate, root ownership, retention sweep) moved verbatim
+  into named helpers. The per-handler gates differ on purpose and the
+  structure is intentionally source-pinned (including a char-window
+  pin) — the pins are load-bearing curation against restructures
+  that regress, so further stages stay inline and mapped.
+
+## Addendum v0.38.85 (goal timeline)
+
+- **One screen answers "what happened, what's next".** `/goal timeline`
+  merges the goal's ledger trail with its audit verdicts in time
+  order (unscoped legacy events claimed by lifetime window, unknown
+  types compact-never-hidden) and derives the single next action
+  from live state. Read-only surface like `/glla log`.
+
 ## Files
 
 - `docs/DESIGN.md` — **this file**

package/docs/INDEX.md

@@ -16,7 +16,7 @@ Policy contracts and recent changes live in the `audit/` directory of the
   failback; v0.35.9 hardened cross-version npm tarball checks; v0.35.10
   handles multi-entry npm dry-run reports; v0.35.11 accepts both npm report
   shapes; v0.35.12 supports npm 12's keyed pack reports; v0.35.13 fixes stale-API recovery loops.
-  v0.35.14–v0.38.71 continue through the supervisor freeze (`/glla pause`),
+  v0.35.14–v0.38.91 continue through the supervisor freeze (`/glla pause`),
   load hold, auditor picker parity, Windows launch fix, zombie-watchdog
   subagent carve-out, due-wait backstop, the `/glla agents` visibility panel,
   durable state-root selection, blank-until-resume auditor context, frozen
@@ -46,6 +46,8 @@ Policy contracts and recent changes live in the `audit/` directory of the
   the registry); post-release work may appear in `Unreleased` above it.
 
 ## Architecture
+- `ARCHITECTURE.md`: 20-minute newcomer overview (three loops, audit lifecycle, persistence)
+- `PROMOTION-CONTRACT.md`: the list item → goal → archive seam, diagrammed
 - `DESIGN.md`: plugin design (types, state, extension lifecycle)
 - `DESIGN-long-running-supervision.md`: v0.36.0 event/progress-driven supervision, aggressive recovery, terminal recaps, and future decision checklist
 - `GLLA-POSITIONING-AND-DECOMPOSITION-2026-08-08.md`: ecosystem

package/docs/PROMOTION-CONTRACT.md

@@ -0,0 +1,67 @@
+# The promotion contract: list item → goal → archive
+
+The one seam every GLLA user must understand. A queue item is inert
+text; a goal is a live audited objective; an archive is an immutable
+record. Promotion moves exactly one way, and every edge below is
+grounded in `activateNextListItem` (`extensions/loops/goal-list-queue.ts`)
+and `archiveCurrentGoal` (`extensions/loops/goal-orchestrator.ts`).
+
+```
+QUEUED (.pi-glla queue + sidecar)          LIVE (state.goal, policy="list")          ARCHIVED (.pi-glla/archive/<id>.md)
+───────────────────────────────          ──────────────────────────────────          ──────────────────────────────────
+inert: objective + contract               audited: turns, claims, verdicts            immutable: markdown + machine record
+  │                                                │                                            ▲
+  │  /list next · cascade · list_activate          │ complete (auditor approves)                │
+  │  ─────────────────────────────────────────▶    ├────────────────────────────────────────────┤
+  │  guards: loop must not own surface;            │ cascade: parent group closes if last       │
+  │  suspicious items get a repair card;           │ subtask done, then next item activates;    │
+  │  sidecar deleted BEFORE the item leaves        │ empty queue → "List complete"              │
+  │                                                │                                            │
+  │  activation FAILS (setGoal refused)            │ abort (/goal cancel, /list next, …)        │
+  │  ◀─────────────────────────────────────────   ├────────────────────────────────────────────┤
+  │  item + sidecar RESTORED to the queue          │ NO cascade (aborts pick their own step);   │
+  │                                                │ item NEVER returns to the queue            │
+  │  disapproval                                   │                                            │
+  │  ─ ─ ─ (queue untouched) ─ ─ ─ ▶               │ rework in place; queue waits               │
+```
+
+## The rules
+
+1. **Activation takes the item out of the queue.** `takeAt` removes
+   it from RAM and the disk sidecar is deleted first — a half-moved
+   item cannot reappear as pending work after reload. What activates
+   is a real `Goal` with `policy: "list"`, carrying the item's
+   contract, agent role, subtask binding, and repair target.
+2. **Guards refuse loudly, except the head-group skip.** A live loop,
+   a suspicious objective, or an undeletable sidecar refuses with a
+   banner and a ledger event. The one silent step is skipping a head
+   *group* to its first open child (groups are containers, not work)
+   — ledgered as `list_group_auto_skipped`, never bannered.
+3. **Completion cascades; abort does not.** An approved list goal
+   archives, closes its parent group when it was the last open
+   subtask, and auto-activates the next item. An aborted goal
+   archives as aborted and stops — auto-advancing on abort once
+   double-activated (v0.2.0), so aborts pick their own next step.
+4. **Nothing returns to the queue.** There is no requeue path: once
+   activated, the item's queue position is gone. Abort archives it
+   as aborted; to retry it, re-add it. The sole exception is a
+   *failed* activation (the prior live objective could not archive),
+   which restores item + sidecar to the queue.
+5. **Disapproval never touches the queue.** Rework happens in place
+   on the live goal; the queue waits behind it.
+6. **Standalone goals hand off, then stop.** A completed `/goal`
+   with a waiting list activates the head item; an aborted one
+   does not. The archive (`.pi-glla/archive/<id>.md`, exclusive
+   create, intent-journaled) is the durable record either way.
+
+## Where to look
+
+- Activation: `activateNextListItem` in
+  `extensions/loops/goal-list-queue.ts` (one-active-thing gate,
+  group scan, suspicious-objective repair, sidecar discipline,
+  setGoal-failure restore).
+- Terminal: `archiveCurrentGoal` + the cascade in
+  `extensions/loops/goal-orchestrator.ts` (archive fence, intent
+  journal, parent close, advance, list-complete notice).
+- The trail: `/goal timeline` narrates any live goal's journey
+  through these states.

package/docs/SETTINGS.md

@@ -30,7 +30,7 @@ copies are ignored (the recovery runtime reads the global file):
 `autoResume`, `drafterModel`, `drafterThinkingLevel`,
 `drafterModelFallbacks`, `compactorModel`, `compactorModelFallbacks`,
 `auditorModelFallbacks`, `auditorToolTimeoutMs`, `auditorStallMs`,
-`auditJobRetentionMs`, `auditorInspection`.
+`auditJobRetentionMs`, `auditSpotCheckRate`, `auditorInspection`.
 
 ## Keys
 
@@ -58,6 +58,7 @@ copies are ignored (the recovery runtime reads the global file):
 | `auditorToolTimeoutMs` | `300000` | Base budget per auditor tool call (30s–6h). Global-only. |
 | `auditorStallMs` | `600000` | Base silence budget for the detached auditor (1m–24h). Global-only. |
 | `auditJobRetentionMs` | `900000` | How long proven-dead audit job dirs are kept (0–7d, 0 = reap now). Global-only. |
+| `auditSpotCheckRate` | `0.1` | Fraction of light-tier audits silently escalated to full (0 = off, 1 = calibrate). Global-only. |
 | `auditorInspection` | `false` | Auditor runs as a persistent session you can tail/resume. Global-only. |
 | `notifyCmd` | unset | Shell command on goal complete / pause / loop stop; message is `$1`. |
 | `tokenLimit` | unset (off) | Per-goal token budget; crossing it pauses. `0` = off. |