pi-goal-list-loop-audit 0.28.33 → 0.29.0

package/README.md

@@ -66,6 +66,7 @@ matches `/list show`.
 /loop                              # draft the loop (agent grills; measure is test-run before you confirm)
 /loop start "keep polishing the UI"                          # infinite metricless loop (v0.23.6): no plateau, no cap — ends at time=/tokens= or /loop stop
 /loop respec                                                  # infinite metricless loop reconciling the codebase against the root SPEC.md / spec.md (v0.24.3) — 2 specs = you pick, 0 specs = drafting, 1 spec = auto-start (v0.24.4)
+/loop audit                                                    # project-audit loop (v0.29.0): each iteration audits fresh, appends findings to .pi-glla/audit-loop/findings.md, fixes the top ones — the orchestrator counts open findings and the plateau stop ends it when the well is dry
 /loop start "reduce TODOs" measure="grep -c TODO src.txt | head -1" direction=min
 /loop start "shrink the bundle" measure="..." direction=min time=4 tokens=500000   # arbitrary bounds
 /loop start "reduce TODOs" measure="..." direction=min branch=1   # scratch-branch mode
@@ -201,7 +202,7 @@ No external watchdog plugin needed.
 /glla                                # open the settings UI
 /glla model=provider/id              # auditor model override → GLOBAL
 /glla thinking=high                  # auditor thinking → GLOBAL
-/glla notify='cmd "$1"'              # push on complete/pause/stop → GLOBAL
+/glla notify='cmd "$1"'              # custom push cmd · unset = auto-detect (notify-send/osascript) · off = silent → GLOBAL
 /glla tokenlimit=10000000            # per-goal token budget (default: off) → GLOBAL
 /glla tokenlimit=0                   # explicitly no cap (the default)
 /glla wedgealert=30                  # hung-command alert minutes (default: 30, 0 = off)
@@ -233,15 +234,14 @@ activates the moment the agent proposes it, with a notification and a
 `draft_autoaccepted` ledger entry (auto-accept is never silent). The seed
 carries the intent. Pair with `autoresume=on` for fully unattended rigs.
 
-## Subagents (`@tintinweb/pi-subagents`)
+## Subagents
 
-Subagent sessions bind extensions too, so glla loads there — by design the
-**main session owns the goal/loop/list; subagents are workers** (v0.23.8):
+glla's guarantees here come from glla itself (session-handle
+discrimination), not from any specific subagent plugin — any Agent-tool
+provider gets them. Subagent sessions bind extensions too, so glla loads
+there — by design the **main session owns the goal/loop/list; subagents
+are workers** (v0.23.8):
 
-- Read-only agents (Explore, Plan) get no glla tools (pi-subagents gates
-  them); general-purpose agents see them but state-mutating calls
-  (`complete_goal`, `propose_*`, `list_add`, `pause_goal`, …) are refused
-  with "report back to the main agent".
 - A subagent session never clobbers the loop's session handle, never runs
   the restore gate, and never drives continuation — so the heartbeat,
   wedge alert, and auto-resume machinery always act on the main session.
@@ -249,6 +249,11 @@ Subagent sessions bind extensions too, so glla loads there — by design the
   is the discriminator.)
 - Subagent tool activity counts as activity for the wedge clock — a long
   subagent run is work, not a hang.
+- With `@tintinweb/pi-subagents` specifically (the one we test against):
+  read-only agents (Explore, Plan) get no glla tools; general-purpose
+  agents see them but state-mutating calls (`complete_goal`, `propose_*`,
+  `list_add`, `pause_goal`, …) are refused with "report back to the main
+  agent".
 
 ## Token guard
 
@@ -287,17 +292,25 @@ contradictory turns. One driver at a time:
   fine to keep, never run a ralph loop while a goal/list/loop is active.
 
 **Goes well with it**: `@juicesharp/rpiv-ask-user-question` (drafting uses its
-structured forms), `@tintinweb/pi-subagents` (spawn research/review subagents
-inside goal work), `@tintinweb/pi-tasks` (session-wide DAGs vs our goal-scoped
-task lists — different granularity), `pi-chrome` (the research/search path for
-goals — logged-in browsing with no extra services; standalone search skills
-like `mmx-cli`/`pi-search-skill` are optional conveniences for bulk queries,
-not requirements).
+structured forms), any subagent provider — e.g. `@tintinweb/pi-subagents` —
+(spawn research/review subagents inside goal work), `pi-chrome` (the
+research/search path for goals — logged-in browsing with no extra services;
+standalone search skills like `mmx-cli`/`pi-search-skill` are optional
+conveniences for bulk queries, not requirements).
+
+**Overlaps — pick one**: `@tintinweb/pi-tasks` is a second task list next to
+`/list`, and in practice the glla list *is* the task list (queue, statuses,
+per-item audit trail) while the todos end up the weaker copy. We ran both
+and removed pi-tasks. If you truly need session-wide dependency DAGs beyond
+one ordered queue, it exists — but installing both is not the ideal combo.
 
 **Two footnotes**: (1) extension-registered providers work in the main session
 but not the auditor's extension-less session — if audits fail auth, set the
-override once with `/glla model=`. (2) `pi-notify-agent` notifies on every turn;
-`/glla notify=` fires only on goal complete/pause/loop stop.
+override once with `/glla model=`. (2) `pi-notify-agent` notifies on every
+turn; glla pushes fire only where there is something to DO (pauses, verdicts,
+storms, wedge) and work out of the box — with no `notify=` configured glla
+auto-detects `notify-send`/`osascript`; `notify=off` silences, `notify='<cmd>'`
+customizes.
 
 ## Files
 

package/extensions/goal-loop-forever.ts

@@ -389,3 +389,36 @@ export function resolveSpecFile(cwd: string): string | null {
 export function respecTarget(specName: string): string {
   return `Reconcile the codebase against ${specName} (the project spec in the root). Read the spec critically first: if a requirement is stale, contradictory, or wrong for the current codebase, report the discrepancy and move on — never force the code to match a bad spec. Otherwise pick the next gap between spec and code and close it. Rotate: one iteration implements a missing or outdated spec item, the next audits something already "implemented" against the spec and fixes what drifted.`;
 }
+
+// ---- /loop audit (v0.29.0) ----
+
+/**
+ * The audit loop's findings file — checkbox lines, append-only. The agent
+ * appends new findings and checks off fixed ones; the ORCHESTRATOR counts
+ * open boxes every iteration. The agent never self-reports progress.
+ */
+export const AUDIT_FINDINGS_REL = ".pi-glla/audit-loop/findings.md";
+
+/**
+ * The audit-loop measure command: count open findings. Prints exactly one
+ * number in every file state (missing file / zero matches → 0). This is
+ * what respec (metricless) and the reviewer cascade (no termination) both
+ * lacked: an honest metric the plateau stop can believe — audits that stop
+ * surfacing new findings = the well is dry = the loop ends.
+ */
+export function auditMeasureCmd(): string {
+  return `c=$(grep -cE '^- \\[ \\]' ${AUDIT_FINDINGS_REL} 2>/dev/null); echo \${c:-0}`;
+}
+
+/**
+ * The audit target. User's design (2026-07-29): "the looper running audits
+ * to see where to progress and what to fix" — the thing that fires at the
+ * end of goals and lists, finds the next batch of work, and works it.
+ * Each iteration: fresh audit pass → append NEW findings → fix the top
+ * open ones → check them off with the fix commit. Honesty laws: never
+ * fabricate findings, never rewrite the file's history, never check a box
+ * without the fix commit existing.
+ */
+export function auditTarget(): string {
+  return `Audit the project for real problems and fix them, iteration by iteration. Every iteration: (1) run a FRESH audit pass over the codebase — spawn Explore subagents for breadth — hunting real issues: bugs, broken flows, regressions, drift between docs and code, dead code, security holes. Not style nits, not speculative refactors. (2) Append every NEW finding as one checkbox line "- [ ] SEVERITY: short description (file:line)" to ${AUDIT_FINDINGS_REL} (create the file on the first finding; append-only — never delete, rewrite, or reorder existing lines; never re-report a finding already listed). (3) Fix the highest-severity OPEN finding(s) — real fixes, committed — then check the box: "- [x] … — fixed in <commit>". (4) Honesty law: never fabricate findings to look busy; never mark a finding fixed without the fix commit existing. When a full audit pass surfaces nothing new AND no open findings remain, say so plainly — the orchestrator counts open findings every iteration and the plateau stop ends the loop when the well is dry.`;
+}

package/extensions/loops/goal.ts

@@ -161,6 +161,8 @@ import {
   LOOP_DEFAULTS,
   resolveSpecFiles,
   respecTarget,
+  auditMeasureCmd,
+  auditTarget,
   HELD_ON_RESTORE,
   type LoopState,
 } from "../goal-loop-forever.js";
@@ -978,7 +980,12 @@ function archiveCurrentGoal(ctx: ExtensionContext, status: Status, stopReason?:
   if (goal.policy === "list" && status === "complete") {
     const advanced = activateNextListItem(ctx);
     // v0.26.0: the queue just EMPTIED on a completion → list-complete.
-    if (!advanced) fireReviewer(ctx, { kind: "list", goalId: goal.id, objective: goal.objective, terminal: "goal-complete" });
+    if (!advanced) {
+      fireReviewer(ctx, { kind: "list", goalId: goal.id, objective: goal.objective, terminal: "goal-complete" });
+      // v0.29.0: the well ran dry — point at the project-audit loop. A
+      // suggestion, not an action: consent, never auto-start (v0.28.28).
+      ctx.ui.notify("List complete. /loop audit to sweep the project for the next batch of work.", "info");
+    }
     return;
   }
   // v0.26.0: a /goal (non-list) reached a terminal state → maybe fire.
@@ -1932,15 +1939,44 @@ function addSingleItem(ctx: ExtensionContext, raw: string): void {
 }
 
 /**
- * Config-gated push notification: if settings.notifyCmd is set, shell out
- * with the message as $1. Fire-and-forget — a broken notify command never
- * blocks the loop. /glla notify='<cmd>' to configure.
+ * Push notification, folded IN by default (v0.28.34 — user: "leaving it to
+ * the user to set up sucks, cause then they won't have it"). Resolution:
+ *   notifyCmd === "off"   → silent (explicit opt-out)
+ *   notifyCmd set         → that command, message passed as $1
+ *   notifyCmd unset       → auto-detect ONCE per session: notify-send
+ *                           (Linux) or osascript (macOS); none → silent.
+ * Pushes fire only where there is something to DO — pauses, auditor
+ * verdicts, storms, wedge, persistence degradation — never per-turn noise.
+ * Fire-and-forget: a broken notifier never blocks the loop.
  */
+let autoNotifyCmd: string | null | undefined; // undefined = not probed yet
+
+function probeAutoNotify(ctx: ExtensionContext): void {
+  if (autoNotifyCmd !== undefined || !extensionApi) return;
+  autoNotifyCmd = null; // probing sentinel — drops at most the first push
+  void extensionApi
+    .exec("bash", ["-c", "command -v notify-send || command -v osascript || true"], { cwd: ctx.cwd })
+    .then((r) => {
+      const found = String((r as { stdout?: string }).stdout ?? "").trim();
+      if (found.endsWith("notify-send")) autoNotifyCmd = `notify-send "pi-goal-list-loop-audit" "$1"`;
+      // env-var handoff: the message never touches AppleScript quoting.
+      else if (found.endsWith("osascript")) autoNotifyCmd = `GLLA_MSG="$1" osascript -e 'display notification (system attribute "GLLA_MSG") with title "pi-goal-list-loop-audit"'`;
+      else autoNotifyCmd = null;
+    })
+    .catch(() => {
+      autoNotifyCmd = null;
+    });
+}
+
 function notifyExternal(ctx: ExtensionContext, message: string): void {
   try {
     const settings = loadSettings(ctx.cwd);
-    const cmd = settings.notifyCmd;
-    if (!cmd || !extensionApi) return;
+    if (settings.notifyCmd === "off" || !extensionApi) return;
+    const cmd = settings.notifyCmd ?? autoNotifyCmd;
+    if (!cmd) {
+      if (settings.notifyCmd === undefined && autoNotifyCmd === undefined) probeAutoNotify(ctx);
+      return;
+    }
     void extensionApi.exec("bash", ["-c", cmd, "pi-goal-list-loop-audit", message], { cwd: ctx.cwd }).catch(() => {});
   } catch {
     // non-fatal by design
@@ -2481,6 +2517,34 @@ async function cmdLoop(args: string, ctx: ExtensionContext): Promise<void> {
     return;
   }
 
+  if (sub === "audit") {
+    // v0.29.0: the project-audit loop (user design: "the looper running
+    // audits to see where to progress and what to fix — the thing that
+    // fires at the end of goals and lists"). Unlike respec this is a
+    // METRIC loop: the orchestrator counts open findings every iteration,
+    // direction=min, and the plateau stop is the termination — audits that
+    // stop surfacing new findings = the well is dry. User typed the
+    // command = the act (same auto-start rule as respec).
+    if (state.goal && state.goal.status === "active") {
+      ctx.ui.notify("A goal is active — /goal cancel or /goal pause it before starting a loop.", "warning");
+      return;
+    }
+    if (isLoopActive()) {
+      ctx.ui.notify("A loop is already active. /loop stop first.", "warning");
+      return;
+    }
+    await startLoopFromConfig(ctx, {
+      target: auditTarget(),
+      measureCmd: auditMeasureCmd(),
+      direction: "min",
+      plateauWindow: LOOP_DEFAULTS.plateauWindow,
+      maxIterations: 0,
+      branch: false,
+      force: false,
+    });
+    return;
+  }
+
   if (sub === "respec") {
     // v0.24.3: reconcile the codebase against the root spec, forever.
     // Same auto-start path as /loop start (the user typed the command —
@@ -3892,7 +3956,7 @@ export async function handleSettingChoice(id: string, ctx: ExtensionContext): Pr
       // current effective subagent models. Treat as no-op.
       return;
     case "notifyCmd": {
-      const v = await ctx.ui.input("Notify command — the event message is passed as $1", "e.g. a desktop-notification or push command; empty = off");
+      const v = await ctx.ui.input("Notify command — the event message is passed as $1", "custom command · empty = auto-detect (notify-send/osascript) · 'off' = silent");
       if (v !== undefined) saveSettings("global", ctx.cwd, { notifyCmd: v.trim() || undefined });
       return;
     }
@@ -4821,6 +4885,7 @@ export default function (pi: ExtensionAPI): void {
     getArgumentCompletions: completions([
       ["start", "skip drafting: /loop start \"<target>\" measure=\"<cmd>\" direction=min|max [window=5] [max=50]"],
       ["respec", "infinite metricless loop reconciling the codebase against the root SPEC.md"],
+      ["audit", "project-audit loop: each iteration audits fresh, appends findings, fixes the top ones — plateau stops when the well is dry (v0.29.0)"],
       ["status", "show metric, iteration, best/last values, stall count"],
       ["stop", "end the loop (keeps the best state)"],
       ["cancel", "alias of /loop stop — end the loop"],

package/extensions/reviewer.ts

@@ -40,7 +40,7 @@ export const DEFAULT_REVIEWER_CONFIG: ReviewerConfig = {
   mode: "on",
   fireOn: ["goal-complete", "list-complete"],
   doNotFireOn: ["goal-aborted", "goal-paused"],
-  cascade: ["convert-findings-to-list", "queue-leftovers", "fire-audit-on-clean", "notify-and-idle"],
+  cascade: ["convert-findings-to-list", "queue-leftovers", "notify-and-idle"],
   auditCadence: "every-clean-completion",
   auditScope: "regression-scan",
   leverageMode: "fix-without-confirm",

package/extensions/settings-menu.ts

@@ -323,9 +323,9 @@ export function buildSettingsRows(
       id: "notifyCmd",
       section: "other",
       label: "Notify command",
-      valueText: show("notifyCmd", "off"),
+      valueText: show("notifyCmd", "auto"),
       sourceText: src("notifyCmd"),
-      description: "desktop push command; the event message is passed as $1",
+      description: "custom command ($1 = message) · unset = auto-detect notify-send/osascript · 'off' = silent",
     },
     {
       id: "tokenLimit",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-goal-list-loop-audit",
-  "version": "0.28.33",
+  "version": "0.29.0",
   "description": "Goal. Loop. Audit. Done. \u2014 a pi-coding-agent extension that supervises long-running work, with isolated auditor on each completion. Beat bamboozling by design: the auditor runs in a fresh session with no extensions, no skills, no editor \u2014 only the read tools needed to verify your goal.",
   "license": "MIT",
   "author": "dracon",