@hank-warren/pi-loop 0.6.0 → 0.8.0

package/CHANGELOG.md

@@ -1,5 +1,65 @@
 # @hank-warren/pi-loop
 
+## 0.8.0
+
+### Minor Changes
+
+- 2a04a46: Plan mode, a ledger write tool, and a widget that shows progress.
+
+  **Breaking: `/schedule` is removed.** It lived here because the machinery was the same
+  machinery — an idle-gated delivery path, coalescing, caps, an expiry. True, and still the
+  wrong home: a loop pursues one objective until it is done and then stops, while a schedule
+  fires forever on a clock. Persisted tasks in `~/.pi/agent/loop/schedules.json` are no longer
+  read and the `schedules.lease` lockfile is no longer taken.
+
+  **`/loop` now opens planning.** With nothing running it starts a drafting conversation
+  instead of printing "No loop in this session". The model drafts the objective as an
+  acceptance test, then calls the new `loop_propose` tool, which renders an approval card
+  showing the exact criteria the split will produce, the cadence and the caps — and starts
+  nothing. You start it, change the cadence, keep editing, or cancel. The criteria used to be
+  frozen before anyone had ever seen them; the card is the moment they can still be fixed.
+  `/loop 30m <objective>` and inline `loop:` are unchanged.
+
+  **Fixed: a wrapped bullet silently truncated its criterion.** `deriveCriteria` kept lines
+  carrying a bullet marker and discarded the rest, so a bullet longer than a terminal width
+  lost everything after its first line — while the criterion still looked well-formed. The
+  acceptance gate was quietly weakened to whatever survived, with no signal.
+
+  **New `loop_progress` tool, the only supported ledger write path.** The ledger is the one
+  thing that survives compaction, and the model was told to maintain it with no tool to do so,
+  so it reached for a shell heredoc — and one `cat > PROGRESS.md` replaced the objective line,
+  the other sections and every failed-approach note. `loop_progress` edits one section and
+  leaves every other byte alone, and marks a criterion met with the citation that justified
+  it, stored alongside it. Only `passes` ever changes, now by construction rather than by
+  prose in a skill file.
+
+  **A blocking prompt no longer deadlocks the loop invisibly.** A session waiting on a modal
+  is `busy`, which makes every continuation and every fallback tick skip; no turn completes,
+  so the cap never trips and the no-progress breaker never fires. Expiry was the only thing
+  left — up to seven days — while the widget showed a next-wake time throughout. Loops now
+  carry an autonomy posture (decide and record rather than ask, `loop_wait` as the only
+  non-deadlocking way to ask, never reshape a command to get past a permission prompt, prefer
+  the undoable), and a run left open past fifteen minutes flips the widget to an attention
+  state. The loop never answers the prompt.
+
+  **The widget was redesigned around progress.** It led with the interval — a fallback
+  heartbeat a settle-paced loop may never deliver — and reported turns against the cap, which
+  is budget burn. Criteria met over total now leads, with the turn budget, the loop's age and
+  the next wake after it. The widget and the footer render the same function: they had drifted,
+  so a loop waiting on CI showed an ordinary next-wake time above the editor while the footer
+  said it was waiting, and a paused loop dropped the cause that `/loop status` printed.
+
+## 0.7.0
+
+### Minor Changes
+
+- 2ca10d6: Companion skill, one turn cap, model-proposed criteria, and a fairer evidence gate.
+
+  - The package is now a hybrid: it ships a `pi-loop` skill (`skills/pi-loop/SKILL.md`) alongside the extension, loaded on demand via one prompt-guideline line in each of `loop_start` and `loop_complete`. It carries the judgment the engine cannot encode — writing objectives that become falsifiable criteria, what the evidence gate accepts, when to `loop_wait`, and when work belongs in no loop at all. Nothing skill-related enters any stored loop message or the system append.
+  - **Breaking:** the two caps collapse into one. `maxIterations` (delivered fallback wakes) and `automaticTurns` (loop-caused turns) become a single `maxTurns` (default 25) counting every turn the loop causes — continuations and pokes. `--max` and the `loop_start` `max` parameter now set this turn cap instead of the wake cap. Settings files and persisted in-flight loops carrying the old keys migrate automatically, adopting the tighter of the pair; the next settings save rewrites them as `maxTurns`. The poke header drops its `n/cap` denominator (wakes are still counted and shown in `/loop status`; they cap nothing).
+  - `loop_start` accepts an optional `criteria` array (at most 12 entries of at most 500 characters; a malformed list refuses the start). It replaces the deterministic grammar split when that split would misfire — context sentences becoming gate criteria, or several requirements packed into one sentence. Accepted only at start, echoed to the user, and frozen afterwards exactly like a derived set. Typed `/loop` starts are unchanged, and a restored loop now keeps the `criteria.json` it finds on disk instead of re-deriving it.
+  - `loop_complete` no longer refuses terse-but-real evidence: the twelve-character floor rejected citations like `404 → 200`. Evidence is now refused only when every word in it is a claim word ("done", "verified", "passes", …) or the value is under four characters.
+
 ## 0.6.0
 
 ### Minor Changes

package/README.md

@@ -19,6 +19,7 @@ pi-plan-mode's `plan-mode-state` is read fail-open — the only sibling state le
 ```
 
 - **Intervals** are `<number><unit>` with unit `s`/`m`/`h`/`d`, parsed by the extension (never the model), minimum 1 minute (smaller values clamp, and the effective value is echoed).
+- **`--max`** caps the turns the loop causes — continuations and pokes alike (see [One cap](#one-cap)); `--max unlimited` opts out.
 - Loops are **user-driven only**: the model may start one *you* invoked inline (below), and never on its own initiative.
 
 ### Inline invocation
@@ -60,14 +61,13 @@ A reply that starts or ends with `LOOP_OK` and carries at most **300 characters*
 
 The chip is **display-only**. The stored message keeps its exact bytes, because rewriting them would break the prompt cache this whole design is built around.
 
-### Two counters
+### One cap
 
-One wake now yields many turns, so a single counter cannot bound a loop:
+`maxTurns` (default 25, `--max`, settings) counts **every turn the loop caused** — settle continuations plus fallback pokes — and stops the loop when it is reached. `null` means unlimited.
 
-- `maxIterations` (default 25, `--max`, settings) counts **delivered wakes** — fallback pokes only.
-- `automaticTurns` (default 25, settings) counts **turns the loop caused** — continuations plus pokes. This is the cap that actually bounds a settle-paced loop, which can run its whole life without a single wake.
+There used to be two caps: this one, and a `maxIterations` counter of **delivered wakes**. The wake cap bounded nothing the turn cap did not, because a settle-paced loop can run its whole life without delivering a single wake — so in practice the turn cap was always the one that tripped, and the second cap cost a settings field, a decision branch, a state field, and a paragraph of documentation to say so. Wakes are still counted and shown (`/loop status`); they just cap nothing.
 
-Either cap trips independently and stops the loop; `null` on either means unlimited.
+A settings file or an in-flight loop still carrying the old pair keeps the **tighter** of the two: that is the bound it was already running under, and nobody has to rewrite settings to keep a cap they already chose.
 
 ## What a wakeup does
 
@@ -77,17 +77,17 @@ Each tick — fallback heartbeat or settled boundary — evaluates, in order:
 2. **Plan mode active?** Skip quietly; never inject prompts into a planning conversation.
 3. **Agent busy?** Never interrupt: coalesce into a single pending wake delivered at the next fully-settled idle boundary. N missed ticks collapse into one poke.
 4. **A declared wait?** A `loop_wait` whose deadline has not passed holds both drivers: the loop is not stalled, it is waiting on the world.
-5. **Caps** (see [Two counters](#two-counters)): stop.
+5. **The turn cap** (see [One cap](#one-cap)): stop.
 6. **Settled boundary:** dispatch the recorded continuation — a pointer-sized message (`⟳ loop continue #6`) that points at the system prompt for the objective, exactly as the pokes do.
 7. **Fallback heartbeat: poke.** The wake header, why it fired (stalled, or a wait that has elapsed), and the loop focus when set. Every poke carries a marker (`<!-- pi-loop-poke:<id>:<n> -->`) so a wakeup is identifiable as loop-injected rather than user-typed. The marker is **provenance only** — pi-loop coalesces wakes in its own state and never reads the marker back to drop a delivery.
 
 **A poke never restates the objective.** The objective reaches the model through a byte-stable system append on the same turn, and duplicating it in the message would store another copy on every wake. That works because pokes are delivered as ordinary user messages, which pass through `before_agent_start`; a delivery path that bypassed it (for example `pi.sendMessage({triggerTurn})`, which calls the agent directly) would arrive with no append and would have to carry the objective again. The token-lean contract is pinned in `test/messages.test.ts`.
 
-In the transcript, a poke renders as a one-line chip (`⏰ loop wake 4/25 · stalled`) via a markdown transformer. That hook is display-only by Pi's contract — the stored message and the model's context are untouched.
+In the transcript, a poke renders as a one-line chip (`⏰ loop wake 4 · stalled`) via a markdown transformer. That hook is display-only by Pi's contract — the stored message and the model's context are untouched.
 
-Expiry and the caps are evaluated whenever the session settles, so a loop ends as soon as the work does rather than at the next scheduled tick. Only the fallback heartbeat pokes; a settle continues.
+Expiry and the cap are evaluated whenever the session settles, so a loop ends as soon as the work does rather than at the next scheduled tick. Only the fallback heartbeat pokes; a settle continues.
 
-The footer status shows `loop 5m · 3/25 · next 14:32`, and a widget above the editor shows the same state with the loop focus beneath it; `/loop status` shows the full card including the last tick's decision and reason.
+The footer status shows `loop 5m · 5/25 · next 14:32` (loop turns against the cap), and a widget above the editor shows the same state with the loop focus beneath it; `/loop status` shows the full card including the last tick's decision and reason.
 
 ## Objective, injection, and `loop_complete`
 
@@ -106,7 +106,7 @@ So completion is gated on the loop's own `criteria.json`. The tool takes a requi
 
 - a criterion has no entry (the refusal names each one, and marks those `criteria.json` still records as unmet);
 - an entry cites an id that is not in the file (inventing ids does not satisfy the gate);
-- an entry asserts completion instead of citing it ("done", "verified", anything under a dozen characters).
+- an entry asserts completion instead of citing it: every word in it is a claim word ("done", "ok", "verified", "passes", "green", …), punctuation and case ignored, or the whole value is under four characters. One word the blocklist does not know — a command, a number, a filename — makes it specific, so terse citations like `404 → 200` and `tests: 0 fail` pass. (The floor used to be twelve characters, which refused both of those.)
 
 The gate is deliberately **mechanical**: it cannot judge whether evidence is *good*, only that the model was made to look at every requirement and say something specific about each. The rules that make the citation worth anything — audit requirement by requirement, authoritative state over transcript, weak or merely consistent evidence is not enough, **effort exhaustion is not completion** — live in the tool description and the system append. With no readable `criteria.json` the gate degrades to "cite at least one specific thing", because the ledger is fail-open everywhere else too.
 
@@ -124,20 +124,22 @@ Without it a loop has exactly one answer to "progress depends on something outsi
 
 A wait **holds both drivers** — no settle continuation, no fallback poke — but does **not** pause the loop and does **not** cancel the pacemaker: it supersedes the next fallback wake, so a wait whose event never arrives still ends in a wake rather than in silence. The deadline timer is generation-guarded and re-armed on session start, so a deadline that passed while the session was away is due immediately.
 
-A wake delivered for an elapsed wait **counts against `maxIterations`**, so a model that keeps re-arming a wait cannot run forever.
+The turn a wake delivers for an elapsed wait **counts against `maxTurns`** like any other, so a model that keeps re-arming a wait cannot run forever.
 
 There is deliberately **no cancel tool**. The events that legitimately cancel a wait (you typing, an earlier wake arriving) are not the model's to report — so when one of them ends a wait, its reason rides along once on the next loop message as `Previous wait (cancelled): …` and is then dropped.
 
 ## Breakers
 
 - **No progress.** The characteristic failure of an autonomous loop is not crashing, it is *restating*: the same paragraph of "here is what I would do next", turn after turn, calling no tools. pi-loop fingerprints the visible assistant text (SHA-256 over NFKC-normalised, case- and whitespace-folded text) of every tool-free loop-caused turn; `noProgressTurns` consecutive repeats (default 3, settings-tunable, `null` disables) **pause** the loop rather than stopping it — it stays configured, the widget says why, and `/loop resume` or your next message continues it with a fresh safety epoch. A turn that called **any** tool, including `loop_wait`, is progress by definition and resets the counter; counting a declared wait is the false positive that made this class of breaker infamous.
-- **Interruption classification.** A loop that answers every provider failure with "continue" retries into exhausted quotas and re-sends requests too large to succeed. So each class gets its own answer: usage/billing exhaustion **pauses** (retrying a quota window that has not reset just burns the caps), an unrecoverable auth error **pauses**, an aborted loop turn (`Esc`) **pauses**, a context overflow **compacts and then continues** regardless of what the usage gauge says — the failed request just disproved that reading — and a transient error simply continues, because the next continuation *is* the retry.
+- **Interruption classification.** A loop that answers every provider failure with "continue" retries into exhausted quotas and re-sends requests too large to succeed. So each class gets its own answer: usage/billing exhaustion **pauses** (retrying a quota window that has not reset just burns the cap), an unrecoverable auth error **pauses**, an aborted loop turn (`Esc`) **pauses**, a context overflow **compacts and then continues** regardless of what the usage gauge says — the failed request just disproved that reading — and a transient error simply continues, because the next continuation *is* the retry.
 
 ## The loop ledger
 
 A multi-day loop cannot keep its state in the conversation: compaction is lossy by construction, and a summary of a summary drifts further from what happened every time. So the conversation stays the working memory, and two files become the record — under `~/.pi/agent/loop/<loop-id>/` (keyed by **loop id**: session ids are not stably exposed to extensions, and one session can run several loops in sequence):
 
-- **`criteria.json`** — this loop's completion criteria, derived from the objective when the loop starts (bullets if you wrote a list, otherwise sentences, otherwise one implicit criterion) and echoed back to you so you can see what `loop_complete` will answer for. JSON deliberately, not Markdown: models rewrite prose they are asked to maintain far more readily than they rewrite a structured file. The model may change **only** the `passes` field, only with cited evidence, and may never add, remove, or reword an entry — a model allowed to rewrite its own acceptance criteria eventually rewrites them into something it has already achieved.
+- **`criteria.json`** — this loop's completion criteria, derived from the objective when the loop starts (bullets if you wrote a list, otherwise sentences, otherwise one implicit criterion) and echoed back to you so you can see what `loop_complete` will answer for. JSON deliberately, not Markdown: models rewrite prose they are asked to maintain far more readily than they rewrite a structured file. The model may change **only** the `passes` field, only with cited evidence, and may never add, remove, or reword an entry — a model allowed to rewrite its own acceptance criteria eventually rewrites them into something it has already achieved. A restore keeps the file it finds: re-deriving it on every session start would reset the flips the loop had earned.
+
+  **The one exception is at start.** The derivation is grammar, not comprehension, so `/loop fix CI. it has been red since Tuesday.` yields a `c2` demanding cited evidence for a piece of background. So `loop_start` takes an optional `criteria` array (≤ 12 entries, ≤ 500 characters each, no blank entries — a malformed list is refused rather than quietly ignored), and when the model passes one it replaces the split. That is the *only* place a model may write criteria: at start there is no work yet to grade, the criteria are echoed to you immediately, and the incentive to write an easy gate is at its weakest — which is exactly untrue at completion time, where they stay immutable. The typed `/loop` command never takes them; there is no model in that path.
 - **`PROGRESS.md`** — the agent-maintained ledger, created with a fixed four-section schema (current status / completed / **failed approaches and why** / next actions) so "update the ledger" means the same thing on every turn. Failed approaches matter most: nothing else remembers them once the conversation is compacted.
 
 Both are **best-effort**. An unwritable home directory, a full disk, or a file hand-edited into invalid JSON degrades the loop to "no ledger" with a single warning; it never breaks the loop. `PROGRESS.md` is created and then never overwritten, so a session restart cannot erase days of ledger.
@@ -154,50 +156,13 @@ Long loops die by context exhaustion, not by failing. pi-loop owns the compactio
 - **Loop-owned re-anchor**: when a compaction completes mid-loop, pi-loop dispatches one pointer-sized continuation at the next settle — re-read `PROGRESS.md` and `criteria.json`, continue from authoritative state, plus the next 1-3 actions lifted out of the summary that just replaced the conversation. The loop no longer goes quiet until the next wake. A re-anchor supersedes an ordinary continuation already queued: after a compaction, "re-read the ledger" is strictly the better instruction.
 - Loop state itself lives in custom session entries, which compaction never touches, and survives session restarts (the timer re-arms on resume; expired loops are dropped with a notice).
 
-## `/schedule`: recurring prompts and headless runs
-
-The same extension also schedules work, because the machinery is the same machinery: an idle-gated delivery path, coalescing, caps, and an expiry.
-
-```
-/schedule                                        manager TUI
-/schedule list
-/schedule every 30m check the release queue      in-session prompt, every 30 minutes
-/schedule at +2h remind me to cut the RC         once, two hours from now
-/schedule at 2026-01-31T09:00 monthly report     once, at an ISO timestamp
-/schedule cron "0 9 * * 1" weekly triage         Monday mornings
-/schedule every 6h --run --cwd /srv/app sync     headless `pi -p` run
-/schedule pause|resume|run|status|delete <id>
-```
-
-Flags: `--run` (headless instead of in-session), `--cwd <path>`, `--max <n|unlimited>`, `--wake always|failure|success|never`, `--name <text>`.
-
-**Two task kinds, deliberately different lifetimes:**
-
-- **`prompt`** injects a prompt into the owning session, delivered exactly like a loop wake — only at a settled idle boundary, queued while the agent is busy. It is **session-scoped**: it lives in memory and dies with the session, because a prompt with no session to arrive in is not a task, it is a leak.
-- **`run`** spawns a headless `pi -p "<prompt>"` in a working directory, tees stdout and stderr to `~/.pi/agent/loop/runs/<task-id>/<timestamp>.log`, and records the exit code. It never touches the conversation unless `wakeOn` says to report back (default: only failures). These are the only tasks persisted, in `~/.pi/agent/loop/schedules.json`.
-
-  A headless run is a **fresh `pi` invocation**, so it uses your *default* model and settings, not the model the scheduling session happens to be using. If a run needs a specific model, say so in the prompt's environment — or check the run log, which records the command, cwd, prompt, and exit code precisely so a surprise like this is one `cat` away.
-
-**One fire per occurrence, not one per open session.** Headless firing is arbitrated by a lockfile lease (`schedules.lease`) holding a pid and a heartbeat: without it, a task scheduled for 09:00 fires once in every Pi session that happens to be open. A holder that dies stops renewing and the next session takes over after 90 seconds. It is not a distributed lock — the failure it must prevent is duplicate work, and the worst it can produce is one skipped tick.
-
-**Missed occurrences coalesce into a single fire.** A laptop asleep for a weekend wakes to one catch-up, never one turn per missed interval.
-
-**Every task is bounded twice**: `maxRuns` (default 25, `--max unlimited` is an explicit opt-in) and a hard 90-day expiry.
-
-**Cron** is five numeric fields at minute granularity (`minute hour day-of-month month day-of-week`), supporting `*`, `n`, `a-b`, `a,b`, and `/step`. No names, no `@daily`, no seconds, no timezones beyond the host's local clock — each of those is a place where two implementations disagree, and a scheduler with debatable semantics is worse than one that refuses the expression. When both day fields are restricted, a day matching *either* fires, as in every crontab in the world.
-
-`/schedule` is **user-typed only**, exactly like `/loop`: the model gets no scheduling tools. A model that can schedule its own future turns can schedule its way around every limit the loop imposes.
-
-> **Never co-install [`@jl1990/pi-scheduler`](https://www.npmjs.com/package/@jl1990/pi-scheduler).** Both register `/schedule`; the commands and the concepts collide.
-
 ## Settings
 
 `~/.pi/agent/pi-loop.json` (absent file = defaults, never created implicitly; saves are atomic and preserve unknown fields), or `/loop settings`:
 
 ```json
 {
-  "maxIterations": 25,
-  "automaticTurns": 25,
+  "maxTurns": 25,
   "noProgressTurns": 3,
   "maxLoopDuration": "7d",
   "inlineInvocation": true,
@@ -210,7 +175,7 @@ Flags: `--run` (headless instead of in-session), `--cwd <path>`, `--max <n|unlim
 }
 ```
 
-`maxIterations: null` and `automaticTurns: null` mean unlimited; `noProgressTurns: null` disables the breaker. `inlineInvocation: false` turns off mid-prompt `/loop` detection; `defaultInterval` is the fallback heartbeat an inline invocation gets when it names none.
+`maxTurns: null` means unlimited; `noProgressTurns: null` disables the breaker. A file still carrying the superseded `maxIterations`/`automaticTurns` pair loads, keeping the tighter of them, and the next save rewrites it as `maxTurns`. `inlineInvocation: false` turns off mid-prompt `/loop` detection; `defaultInterval` is the fallback heartbeat an inline invocation gets when it names none.
 
 ## Deliberate omissions
 
@@ -220,6 +185,14 @@ These were considered and cut, and the reasoning is recorded so they are not sil
 - **No judge model.** Grading completion with a second model is a larger, more expensive change than the criteria/evidence gate; the gate is the rung that ships.
 - **No `loop_blocked` tool.** `loop_wait` covers a real external dependency, and the no-progress breaker covers an impasse the model does not recognise as one. A third "I give up" tool mostly gives a model a way to stop early. `compaction.instructions` overrides the built-in template.
 
+## The companion skill
+
+The package is a hybrid: it ships the extension **and** a `pi-loop` skill (`skills/pi-loop/SKILL.md`), which carries the judgment the engine cannot encode — how an objective becomes falsifiable criteria, what the evidence gate accepts as a citation, when to declare a `loop_wait` instead of polling, what `PROGRESS.md` is worth, and when the work belongs in no loop at all.
+
+It is **loaded on demand**: one line in each of `loop_start` and `loop_complete`'s prompt guidelines points at it by name, exactly as `pi-processes` does, and the model reads the body when it judges it needs it. Nothing about the guidance enters a stored loop message or the system append — those bytes are the cache prefix, and `test/bytes.test.ts` fails if any of them so much as mentions a skill.
+
+Skill and extension version as one artifact on purpose: a skill describing an engine the installed extension does not have is the coupling failure this repository already learned once.
+
 ## Install
 
 ```bash

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hank-warren/pi-loop",
-  "version": "0.6.0",
+  "version": "0.8.0",
   "description": "Long-running work for Pi: settle-paced loops with a durable ledger, adaptive waits, no-progress breakers, evidence-gated completion, and a task scheduler.",
   "type": "module",
   "keywords": [
@@ -29,11 +29,15 @@
   "pi": {
     "extensions": [
       "./index.ts"
+    ],
+    "skills": [
+      "./skills/pi-loop"
     ]
   },
   "files": [
     "index.ts",
     "src",
+    "skills",
     "README.md",
     "LICENSE",
     "CHANGELOG.md"

package/skills/pi-loop/SKILL.md

@@ -0,0 +1,155 @@
+---
+name: pi-loop
+description: Write loop objectives that become falsifiable criteria, and complete a loop with evidence the gate accepts. Use before the first loop_start of a session, before assembling loop_complete evidence, and when deciding whether work belongs in a loop at all.
+license: MIT
+---
+
+# pi-loop
+
+The engine handles pacing, wakes, the cap, compaction, and the ledger. It cannot handle the two things that decide whether a loop is worth running: **what end state the objective names**, and **what evidence proves it**. That is this file.
+
+Nothing here changes how you invoke a loop. `loop_start` still refuses unless the user's message carried an inline `/loop` or `loop:` token — that gate is enforcement, not guidance.
+
+## The objective is not a prompt, it is an acceptance test
+
+At `loop_start` the extension splits the objective into `criteria.json` by default, deterministically and without a model:
+
+- **Bullets or a numbered list** (2+) → one criterion per item.
+- Otherwise **sentences** → one criterion per sentence.
+- Otherwise **the whole objective** → one implicit criterion.
+
+Up to 12 criteria; each gets an id (`c1`, `c2`, …) and `passes: false`. `loop_complete` later demands **one cited piece of evidence per id**. So the objective's grammar decides the shape of the gate — and a conjunction *inside a sentence* does **not** split. "Fix the flaky test and update the docs" is a single criterion whose evidence must cover both halves; nothing will remind you of the second half. When the work has several requirements, write them as separate sentences or bullets on purpose — or pass the criteria yourself (below).
+
+**You pass the user's objective text verbatim** — never a cleaned-up version of it. So the criteria are only as falsifiable as what was typed, and the evidence gate cannot rescue them later: it checks that you said something specific about every criterion, not that the criterion was worth checking.
+
+What you can do is say so **at the start**, in the same turn as `loop_start`. When the objective names no observable end state, start the loop as invoked and then, in one or two lines, name the end state you will hold yourself to and the check that will prove it — and tell the user that `/loop` can edit the objective if that is not what they meant. Record the same statement in `PROGRESS.md`. Do not silently invent an easier target and discover the disagreement at completion.
+
+| Vague as typed | The end state to name back |
+| --- | --- |
+| `make the tests better` | raise `packages/foo` line coverage above 80%, proven by `npm run coverage` |
+| `fix CI` | the CI workflow green on this branch, proven by `gh pr checks` reporting all checks passed |
+| `clean up the parser` | the duplicated token table gone from `src/parse.ts`, with `npm test` still passing |
+| `investigate the memory leak` | no end state exists yet — see *When not to start a loop* |
+
+Two rules follow from the split:
+
+1. **The evidence is best named in the objective itself.** "…, verified by `npm test` passing" pre-commits the citation, so completion is a lookup instead of an argument. Where the objective names no check, the criterion's `check` field is empty and you must audit against authoritative current state. When you suggest a `/loop` invocation to the user, write it that way.
+2. **Keep each criterion checkable by one observation.** A criterion that needs three different commands to prove is three criteria — that is a reason to suggest bullets.
+
+The criteria are echoed back at start. If they came out wrong, that is visible *then*: say so, rather than discovering it at completion.
+
+### When the split would misfire: propose the criteria
+
+The split is grammar, not comprehension. `/loop fix CI. it has been red since Tuesday.` gives you a `c2` demanding cited evidence that CI has been red since Tuesday — background, not a requirement. So `loop_start` takes an optional **`criteria`** array (at most 12 entries, at most 500 characters each, no blank entries; a malformed list is refused, not ignored). When you pass one it *replaces* the split, with ids `c1`…`cN` exactly as if it had been derived.
+
+Use it only when the split would misfire:
+
+- the objective **mixes requirements with context** ("fix CI. it has been red since Tuesday." → one criterion: get CI green on main);
+- the objective **packs several requirements into one sentence** ("fix the flaky test and update the docs" → two criteria, so neither half can be forgotten).
+
+Every criterion you write must be a **faithful restatement of something the user asked for** — never fewer, never weaker, never easier than the objective as typed, and never a requirement they did not state. **When in doubt, omit the parameter** and let the deterministic split stand: an awkward criterion you must answer for is safer than a tidy one you wrote for yourself.
+
+This is the only point where you may write criteria at all. Once the loop starts they are frozen — you may flip `passes`, nothing else — and the user has already seen them echoed.
+
+## Completing: cite, do not assert
+
+`loop_complete` refuses when:
+
+- a criterion id is missing from `evidence` (the refusal names each one, and flags those `criteria.json` still records as unmet);
+- an id appears that is not in `criteria.json`;
+- an entry asserts rather than cites — *every* word in it is a claim word ("done", "ok", "verified", "passes", "green", "n/a", …), with punctuation and case ignored, so "Done." and "verified, passed" are refused too; or the whole value is under four characters.
+
+One word the blocklist does not know — a command, a number, a filename — makes the value specific, so a terse citation is fine: `404 → 200` and `tests: 0 fail` both pass. Terseness is not the problem; asserting is.
+
+Evidence is **the command and what it printed**, **the file and what it now contains**, **the URL and its state**. Previous conversation, your own plan, and a summary of a summary are context, not proof — and after a compaction they are a summary of a summary.
+
+```
+c1: "npm test → 214 passing, 0 failing (packages/pi-loop/test, full run at 14:02)"
+c2: "gh pr checks 171 → all 3 checks passed (ci/gate, ci/typecheck, ci/scan-secrets)"
+```
+
+Audit requirement by requirement before calling it, and match the verification scope to the requirement scope: a criterion about the whole suite is not proven by one test file. **Effort exhaustion is not completion** — running long, running out of ideas, or nearing a cap is never a reason to call the tool. If the criteria are not met, keep working; another continuation is coming.
+
+## A loop runs unattended, so a question is a deadlock
+
+Outside a loop, asking the user costs a few seconds of their attention. Inside one they are not
+there by construction, and the cost is not a slow answer — it is the loop's death.
+
+A session blocked on a modal prompt is **busy**, and `busy` is the third test in the decision
+prefix both drivers share:
+
+```
+loop liveness -> expiry -> plan mode -> compaction -> busy -> wait -> the turn cap -> act
+```
+
+So `agent_settled` never fires and no continuation is queued; every fallback tick returns
+`skip: agent-busy`; `automaticTurns` never increments, so the turn cap never trips; and the
+no-progress breaker needs tool-free *turns*, of which there are none. **Expiry is the only thing
+left, up to seven days later** — and the widget shows the next wake time the whole time.
+
+This is why the guidance is a posture rather than a list of forbidden tools. Your other
+extensions are unknowable and a blacklist goes stale the moment one of them ships a new prompt.
+The rule follows from the mechanics instead:
+
+1. **Decide, do not ask.** Take the reversible option, write the decision *and the reasoning*
+   into `PROGRESS.md`, and keep going. The user reads it when they return and the loop never
+   stopped. A decision recorded beats a question unanswered.
+2. **`loop_wait` is the loop-safe form of asking.** It is the one way to say "I need a human"
+   that does not deadlock: continuations stop, the reason shows in the widget and `/loop status`,
+   and any wake resumes it. Use it exactly where you would otherwise open a modal, and put the
+   options in the ledger first so the answer can be one word.
+3. **Never reshape a command to get past a permission prompt.** This is the dangerous one. An
+   agent under a turn cap has real incentive to rewrite a blocked command into something the
+   guardian waves through, and that failure *looks like progress*. A blocked command means stop
+   and ask through `loop_wait` — never find another way around it.
+4. **Prefer the undoable.** Nobody is watching to catch a bad call, so when two paths are close,
+   take the one that is cheap to reverse: a worktree over the clone, additive over destructive, a
+   draft pull request over a merge.
+5. **Ask only when proceeding is irreversible *and* the choice is load-bearing.** Then use
+   `loop_wait`, not a prompt.
+
+Autonomy is not permission to be reckless. It is the opposite: the absence of a human in the loop
+is exactly why the reversible path is the right default.
+
+## Waiting on the world
+
+When progress depends on something outside the session — a CI run, a deploy, a human reply — call `loop_wait` with a one-sentence reason. Do not spend continuations re-checking, and never sleep in a shell to pass time.
+
+- `resume_after_ms` is clamped to **[60s, 1h]** and the clamped value is echoed back. Omit it to stay quiet until something else wakes the session.
+- Avoid ~300s: that is the prompt-cache dead zone, where the cache has just expired and the next turn re-reads the whole conversation at full price. Use ≤270s only when actively polling external state nothing else reports; otherwise commit to 1200s or more.
+- The turn a wake delivers for an elapsed wait counts against the cap like any other, so re-arming a wait forever is not free.
+- Never wait for what Pi already notifies you about: background processes, subagents, and tool completions wake the session on their own.
+
+`loop_wait` is for a genuine external event, never a way to end a turn early with work outstanding.
+
+## PROGRESS.md is what a stopped loop is worth
+
+The ledger lives at `~/.pi/agent/loop/<loop-id>/`, and `PROGRESS.md` has four fixed sections: current status, completed, **failed approaches and why**, next actions. It is created from a template; **write your first real update in the turn that starts the loop**, and keep updating it as you work rather than at the end. A ledger still holding the template is a loop with no memory.
+
+The failed-approaches section carries the most value, because it is the only thing that survives compaction and the only thing that stops the next continuation — or the next engineer — from re-running an experiment that already failed. "Tried X, it failed because Y" is the whole point; "tried several things" is worth nothing.
+
+Write both files with the **`loop_progress`** tool, never with the file or shell tools. `loop_progress` edits one section and leaves every other byte alone; a whole-file write takes out the objective line, the other three sections, and however many days of failed-approach notes were in them. That is not a hypothetical — it is what a `cat > PROGRESS.md <<EOF` does on the first ledger update, and `createLedger` opens the file with `flag: "wx"` precisely so the engine can never do it.
+
+`criteria.json` sits next to it. Mark an entry met with `loop_progress`, which flips `passes` and stores the citation that justified it alongside the criterion, where `loop_complete` can be held to it later. Only `passes` ever changes: you may **never** add, remove, reword, or re-id an entry, and never hand-edit the file. A model that can rewrite its acceptance criteria eventually rewrites them into something it has already achieved.
+
+Both files are best-effort. If the ledger could not be created the loop still runs; it just has no memory outside the conversation.
+
+## What actually ends a loop
+
+- **The turn cap** (`maxTurns`, default 25, `--max`) counts every turn the loop caused — continuations *and* pokes. It is the only cap: a settle-paced loop can run its whole life without delivering a single fallback wake, so counting wakes bounded nothing. Wakes are still counted and shown in `/loop status`; they cap nothing.
+- **Expiry** (default 7 days, `--expires`) grants one final turn to write state into `PROGRESS.md` — no new work, no completion claim.
+- **The no-progress breaker** pauses the loop after 3 consecutive tool-free turns with the same visible text. Restating a plan is the characteristic failure of an autonomous loop; calling any tool, including `loop_wait`, resets it.
+
+The interval is a fallback heartbeat, not the pacemaker — the loop advances when the session settles. So an interval argument is worth much less thought than the objective.
+
+## When not to start a loop
+
+An inline invocation *permits* a loop; it does not oblige you to start one. When the work is a bad fit, say so in one line and offer the alternative instead:
+
+- **Recurring cadence** ("check the release queue every morning") → not a loop. A loop pursues one objective until it is done and then stops; it is not a timer, and an objective that is never "done" only produces turns until a cap. Use whatever scheduling your setup provides.
+- **Genuine open exploration** ("figure out why memory grows") → do the investigation in the conversation. A loop's value is the gate at the end; an investigation has no end state to gate on, so the loop only supplies unwanted turns. Once the investigation names a fix, *that* is a loop objective.
+- **Work that finishes this turn** → just do it, and say why no loop was needed.
+
+A vague-but-real objective is not in this list: start it, and name the end state back (above).
+
+A loop is self-continuing: starting one wrongly does not produce one bad answer, it produces turns until a cap.

package/src/command.ts

@@ -23,13 +23,19 @@ export interface LoopStartArguments {
 	requestedMs: number;
 	intervalMs: number;
 	clamped: boolean;
-	/** undefined = use settings default; null = unlimited. */
-	maxIterations?: number | null;
+	/** Loop-caused-turn cap: undefined = use settings default; null = unlimited. */
+	maxTurns?: number | null;
 	/** undefined = use settings default; null = disabled for this loop. */
 	compactAt?: number | null;
 	/** Per-loop lifetime in ms; undefined = use the settings default. */
 	expiresInMs?: number;
 	prompt?: string;
+	/**
+	 * Completion criteria proposed at `loop_start`, replacing the deterministic
+	 * split of the objective. Only the tool sets this: a typed `/loop` always
+	 * splits, because there is no model in that path to propose anything.
+	 */
+	criteria?: string[];
 }
 
 export type LoopCommand =
@@ -70,7 +76,7 @@ export function parseLoopCommand(args: string): LoopCommand {
 	// that quietly did not apply.
 	const afterInterval = scanFlags(tokens, beforeInterval + 1, flags);
 	if (typeof afterInterval !== "number") return afterInterval;
-	const { maxIterations, compactAt, expiresInMs } = flags;
+	const { maxTurns, compactAt, expiresInMs } = flags;
 
 	const promptToken = tokens[afterInterval];
 	const prompt = promptToken === undefined ? undefined : args.slice(promptToken.index).trim();
@@ -79,7 +85,7 @@ export function parseLoopCommand(args: string): LoopCommand {
 		requestedMs: interval.requestedMs,
 		intervalMs: interval.effectiveMs,
 		clamped: interval.clamped,
-		...(maxIterations === undefined ? {} : { maxIterations }),
+		...(maxTurns === undefined ? {} : { maxTurns }),
 		...(compactAt === undefined ? {} : { compactAt }),
 		...(expiresInMs === undefined ? {} : { expiresInMs }),
 		...(prompt ? { prompt } : {}),
@@ -87,7 +93,7 @@ export function parseLoopCommand(args: string): LoopCommand {
 }
 
 interface LoopFlags {
-	maxIterations?: number | null;
+	maxTurns?: number | null;
 	compactAt?: number | null;
 	expiresInMs?: number;
 }
@@ -109,7 +115,10 @@ function scanFlags(
 		const consumed = inlineValue !== undefined ? 1 : 2;
 		if (flag === "--max") {
 			if (value === undefined) {
-				return { kind: "error", message: "--max needs a value (a positive number, or unlimited)." };
+				return {
+					kind: "error",
+					message: "--max needs a value (a positive number of loop turns, or unlimited).",
+				};
 			}
 			const parsed = parseMax(value);
 			if (parsed === undefined) {
@@ -118,7 +127,7 @@ function scanFlags(
 					message: `Invalid --max value: ${value}. Use a positive whole number or unlimited.`,
 				};
 			}
-			flags.maxIterations = parsed;
+			flags.maxTurns = parsed;
 		} else if (flag === "--compact-at") {
 			if (value === undefined) {
 				return { kind: "error", message: "--compact-at needs a value (e.g. 60% or off)." };

package/src/complete-tool.ts

@@ -31,22 +31,47 @@ export const LOOP_COMPLETE_TOOL = "loop_complete";
 
 const MAX_SUMMARY_LENGTH = 4_000;
 const MAX_EVIDENCE_LENGTH = 4_000;
-/** Shorter than this is an assertion, not a citation. */
-const MIN_EVIDENCE_LENGTH = 12;
+/**
+ * Shorter than this cannot be a citation of anything. Deliberately tiny: the
+ * floor used to be twelve characters, which refused `404 → 200` and
+ * `tests: 0 fail` — terse, specific, and exactly the evidence the gate wants.
+ * Length was never the signal; the claim words below are.
+ */
+const MIN_EVIDENCE_LENGTH = 4;
+/**
+ * Words that assert rather than cite. A value made of nothing but these is a
+ * claim of completion, however many of them are strung together.
+ */
 const EMPTY_EVIDENCE = new Set([
-	"done",
-	"ok",
-	"okay",
-	"yes",
-	"true",
-	"passes",
-	"passed",
+	"all",
 	"complete",
 	"completed",
-	"verified",
 	"confirmed",
+	"done",
+	"everything",
+	"fine",
+	"fixed",
+	"good",
+	"green",
+	"it",
+	"is",
+	"met",
 	"n/a",
 	"none",
+	"nothing",
+	"now",
+	"okay",
+	"ok",
+	"passed",
+	"passes",
+	"passing",
+	"success",
+	"successful",
+	"true",
+	"verified",
+	"working",
+	"works",
+	"yes",
 ]);
 
 export function registerLoopCompleteTool(pi: ExtensionAPI, controller: LoopController) {
@@ -67,6 +92,7 @@ export function registerLoopCompleteTool(pi: ExtensionAPI, controller: LoopContr
 				"Pass the exact loop_id from the active /loop objective in the system prompt. A mismatched id means the loop changed and the call is refused.",
 				"loop_complete stops scheduled wakeups only. It does not mean an unrelated goal or task is complete.",
 				"If the criteria are not met, do not call it: keep working and expect another continuation.",
+				"Before your first loop_complete this session, read the pi-loop skill: it describes what the evidence gate accepts as a citation and what it refuses.",
 			],
 			parameters: Type.Object({
 				loop_id: Type.String({
@@ -192,10 +218,25 @@ export function auditEvidence(
 	return undefined;
 }
 
+/**
+ * Does this evidence value cite something, or merely assert it?
+ *
+ * Mechanical and predictable on purpose — the per-criterion-id enumeration is
+ * the real gate, and a heuristic that guesses at quality would refuse real
+ * citations. So exactly two things are refused: a value too short to say
+ * anything, and a value in which *every* word is one of the claim words, with
+ * punctuation and case ignored ("Done.", "verified, passed"). One word the
+ * blocklist does not know — a command, a number, a filename — is enough to
+ * make the value specific, which is what the gate is asking for.
+ */
 function isSubstantive(value: string): boolean {
-	const trimmed = value.trim();
-	if (trimmed.length < MIN_EVIDENCE_LENGTH) return false;
-	return !EMPTY_EVIDENCE.has(trimmed.toLowerCase().replace(/[.!]+$/u, ""));
+	const words = value
+		.trim()
+		.split(/\s+/u)
+		.map((word) => word.replace(/^[^\p{L}\p{N}]+|[^\p{L}\p{N}]+$/gu, ""))
+		.filter(Boolean);
+	if (words.length === 0 || value.trim().length < MIN_EVIDENCE_LENGTH) return false;
+	return !words.every((word) => EMPTY_EVIDENCE.has(word.toLowerCase()));
 }
 
 function toolContent(text: string) {