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

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).
@@ -143,6 +143,16 @@ NOT pause: the auditor's objections become a TODO list (`pendingTasks`)
 rendered into every continuation, and the goal stays ACTIVE. Every
 auto-event announces itself with a one-line notify.
 
+## Subagent stall action (v0.35.64)
+
+The subagent watchdog warns after short no-progress windows. A top-level
+tracked child that remains frozen for the longer
+`subagentHangEscalationMinutes` threshold (default `30`) receives one
+child-specific abort request; the parent goal is not aborted. Set the value to
+`0` under `/glla` for warning/telemetry only. Unreachable, nested, or
+ownership-ambiguous children remain warning-only, and partial output stays
+available for inspection.
+
 ## Subagent model inheritance (v0.24.6)
 
 If you use `@tintinweb/pi-subagents`: its default `Explore` agent pins

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.

package/PLAN.md

@@ -0,0 +1,316 @@
+# PLAN — pi-goal-list-loop-audit
+
+Living plan for the project. Update this file as decisions land or milestones close.
+New here? Start with README.md and INSTALL.md — this file is the historical
+plan, not the onboarding path.
+Last updated: v0.29.6 (header refresh). The milestones
+below cover the v0.1.0–v0.7.0 scaffold era; later decisions live in CHANGELOG.md
+(current through v0.29.6) and the current-state addendum in docs/DESIGN.md.
+
+---
+
+## 0. Product definition (frozen)
+
+- **What it is**: a pi-coding-agent extension that supervises long-running work to *verified* completion.
+- **Core mechanism**: a shared goal state machine + an `agent_end`-driven continuation loop + an **isolated auditor** (fresh pi session, no extensions, no skills, power-mode audit tools: read/grep/find/ls/bash) that must approve before a goal is marked complete.
+- **Three loops on one machine**:
+  - **goal** — one ordered goal, audited (`/goal`)
+  - **list** — a queue of goals, each audited in turn (`/list`)
+  - **loop** — a forever-polish loop around a measurable target (`/loop`)
+- **Naming is frozen**: commands are `/goal*`, `/list*`, `/loop*`. No `pi-gla-` prefix, no `oracle/sisyphus/squad/forge` metaphors anywhere (code, files, docs, keywords).
+
+### Non-goals (v0.x)
+
+- No interop with `pi-goal-x` state (`.pi/goals/`). Clean break, `.pi-gla/` only.
+- No web dashboard, no remote control, no multi-machine coordination.
+- No planner/decomposer that invents the goal for the user (drafting *clarifies*; it does not originate).
+
+---
+
+## 1. Milestones & acceptance criteria
+
+### M0 — v0.1.0-alpha.1 scaffold ✅ (done)
+
+- [x] Package layout, LICENSE, README, CHANGELOG, DESIGN, tsconfig
+- [x] `extensions/loops/goal.ts` — commands + agent tools + agent_end loop
+- [x] `extensions/goal-loop-core.ts` — types, JSONL ledger, markdown renderer
+- [x] `extensions/goal-loop-auditor.ts` — isolated auditor session
+- [x] `extensions/goal-loop-backoff.ts` — 5-min hard cap
+- [x] `prompts/goal-loop-continuation.md`, `schemas/goal.schema.json`
+- [x] 24 unit tests green (`npm test`)
+- **Exit evidence**: `npm test` → 24/24 pass (verified 2026-07-20).
+
+### M1 — v0.1.0 (first real release)
+
+Scope: make the goal loop actually work end-to-end in a live pi session. No new features.
+
+- [ ] **Type-check clean**: `npm run check` (tsc --noEmit) → 0 errors.
+  - Known risk: `ExtensionContext`, `defineTool` import path, `pi.registerCommand` arg shapes were written against memory of pi-goal-x, not verified against the installed pi 0.74 API.
+- [x] **Live smoke test** ✅ 2026-07-20 — full loop verified end-to-end in tmux: `/goal` → agent works → `complete_goal` → isolated auditor (opencode/deepseek-v4-flash-free, extension-less) approves → archived with clean 1-entry history + real auditor report.
+- [x] **Fix whatever the smoke test breaks** ✅ — 6 real fixes: (1) API imports from public entrypoint + pi-ai/pi-agent-core types; (2) `sendMessage` on `pi` API not `ctx`; (3) stale-ctx crash → `lastCtx`/`rememberCtx` pattern; (4) `details:{}` in tool results, async handlers, `tool_call` event name; (5) auditor model default → `ctx.model` + string-ref resolver; (6) audit-history pollution — record only non-empty reports, cap at 20, include `error` field.
+- [x] **Escape hatch verified** ✅ (with caveat) — Esc during audit aborts the pi turn; the auditor session may complete detached. Loop recovers cleanly via `agent_end` (verified live: 3 empty audits then approval). pi-goal-x's fancy Escape dialog is v0.2.0 scope. Abort signal is threaded into the auditor for when pi wires tool-level abort properly.
+- [x] **Backoff cap verified** ✅ (incidentally, live) — openrouter 403 storm triggered exactly "Goal paused: 5 consecutive errors" auto-pause.
+- [ ] Update CHANGELOG, tag `v0.1.0`, `npm publish`.
+
+**Live smoke script** (target: < 5 min):
+```
+pi -e /home/dracon/Dev/pi-goal-list-loop-audit
+> /goal "Create file hello.txt containing the word world. Done when: grep -q world hello.txt"
+# expect: agent writes file, calls complete_goal, auditor approves, goal archived
+> /goal status        # expect: complete, audit history shows 1 approved
+cat .pi-gla/active.jsonl | tail -3
+ls .pi-gla/archive/   # expect: one .md file
+```
+
+### M2 — v0.2.0 (list + drafting + regression_shield) ✅ (2026-07-20)
+
+- [x] **Loop 2: `/list`** — `add|show|next|remove <n>|clear`; each item is a full goal; completing/aborting one auto-activates the next; session restart resumes a non-empty queue. Live-verified: two items auto-advanced through audit to archive.
+- [x] **Drafting**: `/goal` no-args → agent grills one question at a time → `propose_goal_draft` → real Confirm dialog. Live-verified end-to-end (drafted goal completed with shield).
+- [x] **regression_shield**: auditor must quote raw output per contract item in an `<evidence>` block; orchestrator converts evidence-free `<approved/>` into disapproval. Pure logic in `goal-loop-shield.ts`; 14 unit tests + live verification (verbatim `<evidence>` in history).
+- [x] **Escape dialog**: abort → complete-without-audit / continue choice.
+- [x] **Provider warning**: one-time `session_start` notice when the session provider isn't a confirmed built-in and no auditorModel is set. Live-verified on kilocode.
+- [x] **Inline contract extraction**: one-liner `Done when:` now extracts (was silently skipped before — the shield never engaged on one-liners).
+- [x] **Live integration harness**: `scripts/smoke.sh [goal|list|draft]` — goal scenario 5/5 assertions green.
+- [x] CHANGELOG, version 0.2.0, publish.
+- [ ] `max_subtasks_per_task` cap → moved to M3 (no task-list creation tool exists yet; capping nothing is premature).
+
+### M3 — v0.3.0 (loop) ✅ (2026-07-20) — design
+
+**Loop 3 is metric-driven, not vibes-driven.** This is the anti-doorknob design:
+pi-loop-mode's failure mode was endless "improvement" churn (the DOORKNOB problem).
+Our loop only believes a number.
+
+**Model**:
+- User supplies: `target` (what to improve), `measure` (shell command that prints
+  a number), `direction` (min|max). Optional: `window` (plateau window, default 5),
+  `max` (iteration cap, default 50).
+- On `/loop start`: orchestrator runs `measure` → baseline.
+- On every `agent_end` while active: orchestrator runs `measure` → compare to best:
+  - improved (min: value < best; max: value > best) → new best, stall=0
+  - not improved / measure failed → stall++
+  - The **orchestrator** runs the measure (via `pi.exec`), never the agent —
+    the agent cannot fake the number.
+- Stop conditions: `stall >= window` (plateau), `iteration >= max`, or `/loop stop`.
+- No git-based auto-revert in v0.3.0 (too dangerous with uncommitted user work);
+  on regression the agent is instructed to undo its own last change, and the next
+  measure verifies.
+- **No auditor in loop 3**: the metric IS the verdict. Documented.
+- Mutual exclusion: a `/loop` cannot start while a goal/list is active and vice versa.
+
+**Command shape**: `/loop start "<target>" measure="<cmd>" direction=min [window=5] [max=50]`
+`/loop` (status) · `/loop stop`
+
+**Collision note**: `/loop` collides with pi-loop-mode — the M1 collision detector
+handles UX; smoke tests run under a bare `PI_CODING_AGENT_DIR` to isolate.
+
+**Also in M3**:
+- `propose_task_list` tool + `max_subtasks_per_task: 5` cap (M2 carry-over — makes
+  the existing complete_task/update_task_status tools actually usable).
+- `notify=<cmd>` setting: shell out on goal complete / goal pause / loop stop
+  (message passed as `$1`; config-gated, no deps).
+- Unit tests (metric parse, plateau logic, task cap) + `/loop` smoke scenario.
+
+**M3 verification evidence** (all live, 2026-07-20):
+- `/loop` smoke: metric 5→0 over 5 improving iterations (stall reset each time),
+  3 stall iterations at 0, plateau stop at window=3, `loop_stopped` + per-iteration
+  `loop_measured` in ledger, notify fired on stop. `scripts/smoke.sh loop` 5/5.
+- Regression check: `goal` 5/5, `list` 4/4, `draft` 3/3 — all scenarios hermetic
+  (bare agent dir + readiness wait) after two collision/REPL-race flakes.
+- 73 unit tests green; `tsc --noEmit` clean.
+- Found + fixed during M3: `/gla` whitespace split mangled quoted
+  notify commands; smoke `wait_for "plateau"` matched agent prose instead of
+  the orchestrator's stop text (assertions raced the loop).
+
+### M7 — v0.7.0 (global config tier) ✅ (2026-07-21)
+
+User directive: settings are not per-goal/loop/list — there should be ONE
+global config you set once and rarely open. Shipped: project > global >
+defaults resolution, `/gla` writes global by default (`project`
+prefix for local overrides), provenance display, 4 mergeSettings unit tests,
+live-verified both tiers + no-leak smoke. Docs updated.
+
+### M6 — v0.6.0 (draft everything) ✅ (2026-07-20)
+
+User directive: for a long-running thing, a draft up front is better. Drafting
+exists only for `/goal`; `/list add` takes raw strings, and `/loop start`
+demands a correct target+measure+direction in one blind shot — the most
+expensive place to be wrong (up to 50 iterations before plateau stops a bad
+metric). Draft all three loops; for `/loop`, validate the metric BEFORE
+confirming.
+
+1. **Unified drafting modes**: drafting target becomes `"goal" | "list" |
+   "loop"`. `/goal` (existing), `/list add` with no args (draft → confirmed
+   contract goes into the QUEUE instead of activating), `/loop` with no args
+   (draft → confirmed loop config starts the loop).
+2. **`/loop` drafting with measure test-run** (centerpiece): the agent grills
+   about target + what number represents progress, then calls
+   `propose_loop_draft(target, measureCmd, direction, window?, max?)`. The
+   **orchestrator runs the measure command once** and shows target + measure +
+   real output + parsed number + direction in the Confirm dialog:
+   "`grep -c TODO src.txt` → `42` (min). Start?" A broken measure (no number)
+   is shown as such and the agent is told to fix the proposal. User validates
+   the metric before a single iteration burns tokens.
+3. **`/goals` archive browser**: list archived goals (id, status, stop reason,
+   objective head) from `.pi-gla/archive/`. Long-running tool needs history.
+4. Gates: unit tests (draft-mode routing, loop-draft measure parsing), smoke
+   scenarios for loop-drafting and list-drafting, publish v0.6.0.
+
+**M6 evidence** (2026-07-20):
+- Loop drafting live: agent located num.txt itself, proposed `cat num.txt`;
+  Confirm dialog showed the real test-run ("Parsed number: 10, lower is
+  better"); confirmed loop ran improving iterations immediately.
+- List drafting live: confirmed contract → list_added → auto-activate →
+  audited → archived.
+- `/goals` parsing verified against real archive entries.
+- 89 unit tests, tsc clean.
+
+**Still deferred**: live footer/TUI widget (now the ONLY remaining scoreboard
+gap vs pi-loop-mode/pi-goal-x).
+
+### M5 — v0.5.0 (self-sufficiency) ✅ (2026-07-20)
+
+User directive: a goal loop that dies silently after compaction and needs an
+EXTERNAL plugin (`@badliveware/pi-compaction-continue`) to restart it is a hole
+in OUR plugin. Liveness is the loop's own job. Bake it in; cut the watchdog.
+
+1. **Heartbeat self-watchdog** (replaces pi-compaction-continue for our loops):
+   a 15s interval checks: active goal-or-loop AND session idle AND no pending
+   continuation/loop timer AND no activity for 60s → re-fire the continuation.
+   One check covers every stall cause (compaction-eaten turn, dropped message,
+   stale ctx). Stall accounting: a heartbeat-nudged turn with ZERO tool calls
+   counts as a nudge; 3 consecutive → pause (mirrors the watchdog's 3-nudge cap,
+   but scoped to real goal progress). Pure decision function unit-tested.
+   Scope note: this covers stalls while a goal/loop is active. Non-goal sessions
+   are the user's own business — they are at the keyboard.
+2. **`/goal tweak "<text>"`** — edit the active goal's objective in place
+   (Confirm dialog shows old vs new; contract re-extracted from the new text).
+   Closes the last pi-goal-x feature gap we use.
+3. **Structured drafting forms**: drafting prompt prefers `ask_user_question`
+   (rpiv-ask-user-question) when the tool is available in the session — closes
+   the structured-forms gap vs pi-goal-x without a hard dependency.
+4. **Rig cuts** (after publish): `pi-codex-goal`, `pi-loop-mode`,
+   `@badliveware/pi-compaction-continue`. AGENTS.md stack table rewritten:
+   goal plane = pi-goal-list-loop-audit.
+
+**M5 evidence** (2026-07-20):
+- Heartbeat: 8 unit tests for the stall predicate + nudge accounting; `goal`
+  smoke 5/5 with the heartbeat interval live through the full cycle.
+- `/goal tweak`: implemented with Confirm dialog + contract re-extraction.
+- Drafting prompt prefers `ask_user_question` when available.
+- 89 unit tests, tsc clean.
+
+**Deferred**: live footer/TUI widget (pi-loop-mode's dashboard is the one thing
+we genuinely lose by cutting it; v0.6.0 candidate if missed).
+
+### M4 — v0.4.0 (completion release) ✅ (2026-07-20)
+
+Everything left, in one release. Completes the 6-flaw list and makes the docs honest.
+
+1. **Auditor compaction (flaw #3 — the LAST open flaw)**. Enable pi's built-in
+   compaction in the auditor session (currently `compaction: { enabled: false }`).
+   Safety argument: regression_shield is orchestrator-side — a compaction-degraded
+   auditor produces weaker evidence → disapproval, never false approval. The risky
+   direction (silent false approval) is structurally impossible.
+2. **Schema + examples + docs sync**. `schemas/goal.schema.json` still says "oracle"
+   and "v0.1.0 loop 1 only"; `examples/example-objective.md` used `/pi-gla-set`;
+   `tests/README.md` has stale counts; `docs/DESIGN.md` needs the v0.2/v0.3 addendum.
+3. **tokensUsed wiring + limit enforcement**. `AgentEndEvent.messages` carries
+   `usage.totalTokens` per assistant message — accumulate per goal. `tokensLimit`
+   becomes a real cost guard: crossing it pauses the goal with a clear reason
+   (configurable via `/glla tokenlimit=`).
+4. **Resumption notice** on `session_start`: if a goal is active or a loop is
+   running, say so. (The "plugin vanished" self-check from D4 is impossible from
+   inside the plugin — absent code cannot run. Recorded as rejected.)
+5. **Loop 3 git-branch mode** (`branch=1` flag): at `/loop start`, create scratch
+   branch `pi-glla-loop/<id>`; commit after each improving iteration; on regression
+   `git reset --hard` to the last improving commit ON THE SCRATCH BRANCH ONLY.
+   The user's branch and uncommitted work are never touched. Requires: git repo,
+   and we refuse `branch=1` with a dirty tree (refuse to mix user work into the
+   scratch branch).
+6. **Draft reject path** in the smoke harness (Confirm → No → agent refines).
+
+After M4 the 6-flaw list is closed and the roadmap table is all-shipped.
+
+**M4 verification evidence** (all live, 2026-07-20):
+- Auditor compaction enabled; `goal` smoke 5/5 green after the change.
+- Token guard: 3 unit tests for dedup accumulation; limit-pause path wired in
+  agent_end with settings-configurable budget.
+- branch=1 live: 5 improvement commits on scratch branch, 0 for stalls, main
+  untouched, returned to main on plateau with merge instructions.
+- `draft-reject` smoke 6/6: Confirm → reject → refine → Confirm → approval.
+- Resumption notice on session_start for active goal/loop.
+- 81 unit tests, tsc clean, all 5 smoke scenarios green.
+- **6/6 pi-goal-x flaws now closed.** The D4 "plugin vanished" self-check is
+  recorded as REJECTED (absent code cannot run); replaced by the resumption
+  notice.
+
+**Deferred to v0.4.0 (with justification)**: (superseded — this release)
+
+---
+
+## 2. Open decisions (must resolve before M1 publish)
+
+### D1 — Command collision strategy ✅ RESOLVED
+
+**Verified in installed pi source** (`dist/core/extensions/runner.js:resolveRegisteredCommands`):
+- Duplicate command names **never throw** and **never clobber** — both survive.
+- First registrant keeps the bare name (`/goal`); later ones get `/goal:2`, `/goal:3`, …
+- So the failure mode is degraded UX (our command reachable as `/goal:2`), never breakage.
+
+**Decision: option 1 — plain names + detect-and-warn.** Implemented in `extensions/loops/goal.ts:warnOnCommandCollision`: at `session_start` we count registered command names via `pi.getCommands()`, and if any of ours (`goal`, `list`, `loop`, `goal-*`) appears more than once we notify the user with the degraded invocation name. Collision check is fail-silent (non-fatal by design).
+
+### D2 — Auditor model default ✅ RESOLVED (with a hard discovered constraint)
+
+**Discovered during M1 smoke (2026-07-20): the auditor session has no extensions, so it can only use BUILT-IN providers.** On this rig the main session ran kilocode (`tencent/hy3:free`) — an extension-registered provider — and every auditor spawn failed with `No API key found for kilocode`. Verified bare-session matrix: `opencode/deepseek-v4-flash-free` works extension-less; kilocode/zenmux/kimi-coding do not.
+
+**Decision**: default = session model (works when the session model is built-in); `/gla model=provider/id` overrides for rigs running extension-provided session models. The `/gla` save message now warns about the built-in-provider constraint. `resolveAuditorModel` documents it in code. v0.2.0 should add a startup check: if session model's provider is extension-registered and no auditorModel is set, warn once.
+
+### D3 — State dir name ✅ RESOLVED
+
+**Keep `.pi-gla/`.** Internal-only path; renaming costs a migration for zero user-visible gain. If we ever regret it, the rename is a one-line constant (`piGlaDir` in `goal-loop-core.ts`) plus a migrate-on-read.
+
+### D4 — Persistence across pi updates ✅ RESOLVED
+
+Known rig behavior (from earlier audits): `pi update` overwrites `~/.pi/agent/npm/node_modules/`, which can wipe npm-installed plugins. **Decision: document both install paths in INSTALL.md** — `pi install npm:pi-goal-list-loop-audit` (convenient, re-install after `pi update`) and project-local `.pi/extensions/` (permanent, survives updates). The `-e <path>` dev flow is unaffected. v0.2.0 should add a `session_start` self-check that notifies if the plugin vanished from the loaded set while `.pi-gla/active.jsonl` shows an active goal.
+
+---
+
+## 3. Verification gates (apply to every milestone)
+
+A milestone is not done until:
+
+1. `npm test` green (unit).
+2. `npm run check` clean (types).
+3. Live smoke passes (M1+).
+4. CHANGELOG entry written.
+5. No `oracle|sisyphus|squad|forge|pi-gla-` string outside `.pi-gla/` dir name (run the grep).
+
+```bash
+grep -rn "oracle\|sisyphus\|squad\|forge" \
+  tests/ extensions/ prompts/ docs/ examples/ README.md INSTALL.md CHANGELOG.md package.json \
+  | grep -v node_modules
+# expect: no output
+```
+
+---
+
+## 4. Risks
+
+| Risk | Likelihood | Mitigation |
+|---|---|---|
+| pi extension API drift (0.74 → next) | medium | pin peerDeps `*`; smoke test after every pi update |
+| Command collision (D1) | high | resolve D1 before publish |
+| Auditor cost (every complete_goal = extra session) | medium | D2 settings; document cost expectation in README |
+| User installs alongside pi-goal-x and gets two loops fighting | medium | README "conflicts" section; loud notify if `.pi/goals/` detected |
+| v0.1.0's auditor is rubber-stampable (`bash true`) until v0.2.0 regression_shield | known/accepted | documented in DESIGN + README; ship v0.2.0 fast |
+
+---
+
+## 5. Publish checklist (M1)
+
+- [ ] D1–D4 resolved and recorded in this file
+- [ ] `npm test` + `npm run check` + live smoke all green
+- [ ] Version bump `0.1.0-alpha.1` → `0.1.0`
+- [ ] git init + initial commit + GitHub repo `dracon/pi-goal-list-loop-audit`
+- [ ] `npm publish --access public`
+- [ ] Verify: `pi install npm:pi-goal-list-loop-audit` on a clean rig