@hank-warren/pi-loop 0.6.0 → 0.7.0

package/CHANGELOG.md

@@ -1,5 +1,16 @@
 # @hank-warren/pi-loop
 
+## 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.
@@ -196,8 +198,7 @@ Flags: `--run` (headless instead of in-session), `--cwd <path>`, `--max <n|unlim
 
 ```json
 {
-  "maxIterations": 25,
-  "automaticTurns": 25,
+  "maxTurns": 25,
   "noProgressTurns": 3,
   "maxLoopDuration": "7d",
   "inlineInvocation": true,
@@ -210,7 +211,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 +221,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 `/schedule` or 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.7.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,112 @@
+---
+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.
+
+## 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.
+
+`criteria.json` sits next to it. You may flip an entry's `passes` field when authoritative evidence proves it, citing that evidence in `PROGRESS.md`. You may **never** add, remove, reword, or re-id an entry: 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") → `/schedule`, which owns cron, one-shots, and headless runs. A loop pursues one objective until it is done; it is not a timer.
+- **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) {

package/src/decide.ts

@@ -9,7 +9,7 @@
  *   handler for a lost continuation or an external wait, not the pacemaker.
  *
  * Both share one precedence prefix: loop liveness → expiry → plan mode →
- * compaction → busy → wait → caps → act.
+ * compaction → busy → wait → the turn cap → act.
  *
  * A loop owns its own objective and reads no other extension's state: it ends
  * only through `loop_complete`, a cap, an expiry, or the user.
@@ -49,14 +49,14 @@ export type TickDecision =
 	| { action: "none"; reason: "loop-not-active" }
 	| { action: "expire"; reason: ExpiryReason }
 	| { action: "skip"; reason: SkipReason }
-	| { action: "stop"; reason: "max-iterations" | "max-automatic-turns" }
+	| { action: "stop"; reason: "max-turns" }
 	| { action: "poke"; reason: "objective-stalled" | "wait-elapsed" };
 
 export type ContinuationDecision =
 	| { action: "none"; reason: "loop-not-active" }
 	| { action: "expire"; reason: ExpiryReason }
 	| { action: "skip"; reason: SkipReason }
-	| { action: "stop"; reason: "max-iterations" | "max-automatic-turns" }
+	| { action: "stop"; reason: "max-turns" }
 	| { action: "continue"; reason: "settled-idle" };
 
 /** Shared prefix: everything that holds or ends a loop before caps matter. */
@@ -80,17 +80,14 @@ function decideCommonPrefix(
 }
 
 /**
- * Caps are checked in a fixed order so a loop that trips both reports the
- * wake cap first — it is the one the user configured with `--max`.
+ * The one cap, counting every turn the loop caused: continuations and pokes
+ * alike. A delivered-wake cap sat next to it until it was collapsed into
+ * this one — in a settle-paced loop the wake counter can stay at zero for the
+ * loop's whole life, so it was never the ceiling that held.
  */
-function decideCaps(
-	loop: LoopState,
-): { action: "stop"; reason: "max-iterations" | "max-automatic-turns" } | undefined {
-	if (loop.maxIterations !== null && loop.iteration >= loop.maxIterations) {
-		return { action: "stop", reason: "max-iterations" };
-	}
-	if (loop.maxAutomaticTurns !== null && loop.automaticTurns >= loop.maxAutomaticTurns) {
-		return { action: "stop", reason: "max-automatic-turns" };
+function decideCap(loop: LoopState): { action: "stop"; reason: "max-turns" } | undefined {
+	if (loop.maxTurns !== null && loop.automaticTurns >= loop.maxTurns) {
+		return { action: "stop", reason: "max-turns" };
 	}
 	return undefined;
 }
@@ -103,7 +100,7 @@ function decideCaps(
 export function decideContinuation(loop: LoopState, env: TickEnvironment): ContinuationDecision {
 	const prefix = decideCommonPrefix(loop, env);
 	if (prefix) return prefix;
-	const capped = decideCaps(loop);
+	const capped = decideCap(loop);
 	if (capped) return capped;
 	return { action: "continue", reason: "settled-idle" };
 }
@@ -111,10 +108,10 @@ export function decideContinuation(loop: LoopState, env: TickEnvironment): Conti
 export function decideTick(loop: LoopState, env: TickEnvironment): TickDecision {
 	const prefix = decideCommonPrefix(loop, env);
 	if (prefix) return prefix;
-	const capped = decideCaps(loop);
+	const capped = decideCap(loop);
 	if (capped) return capped;
 	// The prefix already let a still-waiting loop skip, so a wait surviving to
 	// here is one whose deadline has come due: this wake is the wake it asked
-	// for, and it counts against the wake cap like any other.
+	// for, and the turn it starts counts against the cap like any other.
 	return { action: "poke", reason: loop.waiting ? "wait-elapsed" : "objective-stalled" };
 }

package/src/ledger.ts

@@ -30,9 +30,9 @@ export const LEDGER_DIR_NAME = "loop";
 export const CRITERIA_FILE = "criteria.json";
 export const PROGRESS_FILE = "PROGRESS.md";
 
-/** Cap on derived criteria: an objective is a paragraph, not a backlog. */
-const MAX_CRITERIA = 12;
-const MAX_DESCRIPTION_LENGTH = 500;
+/** Cap on a loop's criteria: an objective is a paragraph, not a backlog. */
+export const MAX_CRITERIA = 12;
+export const MAX_DESCRIPTION_LENGTH = 500;
 
 export interface LoopCriterion {
 	id: string;
@@ -69,7 +69,20 @@ export function deriveCriteria(objective: string): LoopCriterion[] {
 		.filter(Boolean);
 	const parts = bullets.length > 1 ? bullets : splitSentences(trimmed);
 	if (parts.length < 2) return [implicitCriterion(trimmed)];
-	return parts.slice(0, MAX_CRITERIA).map((description, index) => ({
+	return criteriaFromDescriptions(parts);
+}
+
+/**
+ * Number a list of descriptions into criteria.
+ *
+ * Shared by the deterministic split and by the criteria a model may propose
+ * at `loop_start`, so nothing downstream — the echo at start, the evidence
+ * gate, the immutability rule — can tell the two apart. The extension still
+ * writes every field but the description: ids are positional, `check` is
+ * empty (audit against authoritative state), and a criterion starts unmet.
+ */
+export function criteriaFromDescriptions(descriptions: readonly string[]): LoopCriterion[] {
+	return descriptions.slice(0, MAX_CRITERIA).map((description, index) => ({
 		id: `c${index + 1}`,
 		description: truncate(description),
 		check: "",

package/src/loop.ts

@@ -37,9 +37,11 @@ import {
 import { formatClock, formatDuration, MAX_INTERVAL_MS, parseDuration } from "./interval.js";
 import {
 	createLedger,
+	criteriaFromDescriptions,
 	deriveCriteria,
 	type LedgerPaths,
 	ledgerPaths,
+	type LoopCriterion,
 	readCriteria,
 } from "./ledger.js";
 import {
@@ -570,14 +572,21 @@ export class LoopController {
 	 * Create (or adopt) the loop's ledger. Best-effort by design: a loop with
 	 * no writable ledger still runs, it just loses the durable record, so the
 	 * failure is warned once and never repeated.
+	 *
+	 * `criteria` is passed at start: the criteria proposed at `loop_start`, or
+	 * the deterministic split of the objective. On restore it is omitted, and
+	 * the criteria already on disk are authoritative — they are the ones the
+	 * user saw echoed, and re-deriving them would both discard a proposed set
+	 * and reset whatever `passes` flips the loop has earned.
 	 */
-	private openLedger(loop: LoopState): void {
+	private openLedger(loop: LoopState, criteria?: LoopCriterion[]): void {
 		if (loop.objective === undefined) {
 			this.ledger = undefined;
 			return;
 		}
 		const paths = ledgerPaths(loop.id, this.agentDir);
-		const failure = createLedger(paths, loop.objective, deriveCriteria(loop.objective));
+		const contents = criteria ?? readCriteria(paths) ?? deriveCriteria(loop.objective);
+		const failure = createLedger(paths, loop.objective, contents);
 		if (failure) {
 			this.ledger = undefined;
 			if (!this.ledgerWarned) {
@@ -757,12 +766,7 @@ export class LoopController {
 				this.transition("stopped", "loop expired (the expiry was reached)");
 				return;
 			case "stop":
-				this.transition(
-					"stopped",
-					decision.reason === "max-automatic-turns"
-						? `the ${loop.maxAutomaticTurns}-automatic-turn cap was reached`
-						: `the ${loop.maxIterations}-iteration cap was reached`,
-				);
+				this.transition("stopped", `the ${loop.maxTurns}-turn cap was reached`);
 				return;
 		}
 	}
@@ -809,9 +813,9 @@ export class LoopController {
 
 	/**
 	 * Send first, then account. Pi can refuse the delivery (a busy or compacting
-	 * session), and an iteration persisted before the send would burn the
-	 * maxIterations cap on a poke that never arrived; on a throw the loop re-arms
-	 * on the same cadence and retries at the next wake.
+	 * session), and a turn persisted before the send would burn the cap on a
+	 * poke that never arrived; on a throw the loop re-arms on the same cadence
+	 * and retries at the next wake.
 	 */
 	private deliverPoke(now: number, reason: "objective-stalled" | "wait-elapsed"): void {
 		const loop = this.state;
@@ -961,7 +965,7 @@ export class LoopController {
 			);
 			return;
 		}
-		const cap = loop.maxIterations === null ? "∞" : `${loop.maxIterations}`;
+		const cap = loop.maxTurns === null ? "∞" : `${loop.maxTurns}`;
 		const next = this.wakePending
 			? "next on idle"
 			: this.nextWakeAt
@@ -969,7 +973,7 @@ export class LoopController {
 				: "next unscheduled";
 		ui.setStatus(
 			LOOP_STATUS_KEY,
-			`loop ${formatDuration(loop.intervalMs)} · ${loop.iteration}/${cap} · ${next}`,
+			`loop ${formatDuration(loop.intervalMs)} · ${loop.automaticTurns}/${cap} · ${next}`,
 		);
 	}
 
@@ -991,8 +995,8 @@ export class LoopController {
 				? [`Cancelled wait (reported on the next wake): ${loop.cancelledWaitReason}`]
 				: []),
 			`Interval: every ${formatDuration(loop.intervalMs)}`,
-			`Wakes: ${loop.iteration}${loop.maxIterations === null ? " (unlimited)" : ` of ${loop.maxIterations}`}`,
-			`Automatic turns: ${loop.automaticTurns}${loop.maxAutomaticTurns === null ? " (unlimited)" : ` of ${loop.maxAutomaticTurns}`}`,
+			`Loop turns: ${loop.automaticTurns}${loop.maxTurns === null ? " (unlimited)" : ` of ${loop.maxTurns}`}`,
+			`Fallback wakes delivered: ${loop.iteration}`,
 			`Started: ${new Date(loop.startedAt).toLocaleString()}`,
 			`Expires: ${new Date(loop.expiresAt).toLocaleString()}`,
 			`Proactive compaction: ${loop.compactAt === null ? "off" : `at ${Math.round(loop.compactAt * 100)}% of context`}`,
@@ -1079,9 +1083,7 @@ export class LoopController {
 			status: "active",
 			objective,
 			intervalMs: start.intervalMs,
-			maxIterations:
-				start.maxIterations !== undefined ? start.maxIterations : this.settings.maxIterations,
-			maxAutomaticTurns: this.settings.automaticTurns,
+			maxTurns: start.maxTurns !== undefined ? start.maxTurns : this.settings.maxTurns,
 			compactAt,
 			iteration: 0,
 			automaticTurns: 0,
@@ -1093,7 +1095,10 @@ export class LoopController {
 		this.continuationIntent = undefined;
 		this.noOpStreak = 0;
 		this.ledgerWarned = false;
-		this.openLedger(this.state);
+		this.openLedger(
+			this.state,
+			start.criteria ? criteriaFromDescriptions(start.criteria) : deriveCriteria(objective),
+		);
 		this.persist();
 		this.scheduleTick(start.intervalMs);
 		this.updateWidget();

package/src/manager.ts

@@ -154,8 +154,7 @@ export async function showLoopSettings(
 	for (;;) {
 		const s = controller.settings;
 		const items = [
-			`Max wakes: ${s.maxIterations === null ? "Unlimited" : s.maxIterations}`,
-			`Max automatic turns: ${s.automaticTurns === null ? "Unlimited" : s.automaticTurns}`,
+			`Max loop turns: ${s.maxTurns === null ? "Unlimited" : s.maxTurns}`,
 			`No-progress breaker: ${s.noProgressTurns === null ? "Off" : `after ${s.noProgressTurns} repeats`}`,
 			`Max loop duration: ${s.maxLoopDuration}`,
 			`Proactive compaction: ${s.compaction.enabled ? `On at ${Math.round(s.compaction.threshold * 100)}%` : "Off"}`,
@@ -167,14 +166,10 @@ export async function showLoopSettings(
 		if (index === 0) {
 			// Unlimited is a first-class choice, not a magic word typed into a free
 			// text box: it is only reachable by discovery otherwise.
-			const cap = await editCap(ctx, "Max wakes", "no wake cap", s.maxIterations);
+			const cap = await editCap(ctx, "Max loop turns", "no turn cap", s.maxTurns);
 			if (cap === undefined) continue;
-			next.maxIterations = cap === "unlimited" ? null : cap;
+			next.maxTurns = cap === "unlimited" ? null : cap;
 		} else if (index === 1) {
-			const cap = await editCap(ctx, "Max automatic turns", "no turn cap", s.automaticTurns);
-			if (cap === undefined) continue;
-			next.automaticTurns = cap === "unlimited" ? null : cap;
-		} else if (index === 2) {
 			const cap = await editCap(
 				ctx,
 				"No-progress breaker",
@@ -183,7 +178,7 @@ export async function showLoopSettings(
 			);
 			if (cap === undefined) continue;
 			next.noProgressTurns = cap === "unlimited" ? null : cap;
-		} else if (index === 3) {
+		} else if (index === 2) {
 			const value = await ctx.ui.input("Max loop duration (e.g. 7d)", s.maxLoopDuration);
 			if (value === undefined) continue;
 			if (parseDuration(value.trim()) === undefined) {
@@ -191,7 +186,7 @@ export async function showLoopSettings(
 				continue;
 			}
 			next.maxLoopDuration = value.trim();
-		} else if (index === 4) {
+		} else if (index === 3) {
 			if (s.compaction.enabled) next.compaction.enabled = false;
 			else {
 				const value = await ctx.ui.input(
@@ -216,7 +211,7 @@ export async function showLoopSettings(
 }
 
 /**
- * One cap editor for both counters. Unlimited is a first-class choice, not a
+ * One cap editor for every cap. Unlimited is a first-class choice, not a
  * magic word typed into a free text box: it is only reachable by discovery
  * otherwise. The typed word still works, so the /loop --max vocabulary and
  * muscle memory keep working.

package/src/messages.ts

@@ -15,23 +15,30 @@ import type { LoopState } from "./state.js";
 /** Why the loop is talking: the first turn, an ordinary turn, or after a compaction. */
 export type ContinuationKind = "kickoff" | "continue" | "reanchor";
 
-function formatIteration(loop: LoopState): string {
-	const cap = loop.maxIterations === null ? "unlimited" : `${loop.maxIterations}`;
-	return `${loop.iteration + 1}/${cap}`;
+/**
+ * The wake ordinal, and only the ordinal. It used to read `4/25`, the wake
+ * counter against the delivered-wake cap; that cap is gone, collapsed into
+ * the single loop-turn cap, and pairing a wake number with a turn cap would
+ * have been a number that reads as a budget and is not one. The cap is shown
+ * to the *user*, in the widget and `/loop status`, which is who it is for.
+ */
+function formatWakeOrdinal(loop: LoopState): string {
+	return `${loop.iteration + 1}`;
 }
 
 /**
  * The poke. Deliberately slim: the loop's own objective injection puts the
  * objective and loop-mode rules in the system prompt of every turn, so
  * restating them here would store a duplicate copy on every wake. Only the
- * dynamic per-wake state (iteration, reason) belongs in this tail message.
+ * dynamic per-wake state (the wake ordinal, the reason) belongs in this tail
+ * message.
  */
 export function buildObjectivePoke(
 	loop: LoopState,
 	reason: "objective-stalled" | "wait-elapsed" = "objective-stalled",
 ): string {
 	const lines = [
-		`Scheduled loop wakeup ${formatIteration(loop)} (every ${formatDuration(loop.intervalMs)}).`,
+		`Scheduled loop wakeup ${formatWakeOrdinal(loop)} (every ${formatDuration(loop.intervalMs)}).`,
 		reason === "wait-elapsed"
 			? "The wait you asked for has elapsed. Re-check the external state it depended on and continue — the objective and loop-mode rules are in the system prompt."
 			: "The session went idle but the loop objective's completion criteria are not met. Continue working it — the objective and loop-mode rules are in the system prompt.",

package/src/settings.ts

@@ -21,15 +21,22 @@ export interface LoopCompactionSettings {
 	instructions: string | null;
 }
 
+/**
+ * The cap fields this one replaced: a delivered-wake cap (`maxIterations`,
+ * `--max`) and a loop-caused-turn cap (`automaticTurns`). A settle-paced loop
+ * can run its whole life without delivering a single fallback wake, so the
+ * wake cap bounded nothing the turn cap did not already bound.
+ */
+const LEGACY_CAP_KEYS = ["maxIterations", "automaticTurns"] as const;
+
 export interface LoopSettings {
-	/** Delivered-wake cap; null means unlimited (explicit opt-in). */
-	maxIterations: number | null;
 	/**
-	 * Cap on turns the loop itself causes (settle continuations plus fallback
-	 * pokes); null means unlimited. A settle-paced loop can run many turns per
-	 * wake, so this is the bound that actually holds it.
+	 * Cap on the turns the loop itself causes (settle continuations plus
+	 * fallback pokes); null means unlimited (explicit opt-in). The only cap
+	 * there is: one wake can yield many turns, so counting turns is what
+	 * actually bounds a loop.
 	 */
-	automaticTurns: number | null;
+	maxTurns: number | null;
 	/**
 	 * Consecutive tool-free loop turns with identical output that pause the
 	 * loop; null disables the breaker.
@@ -54,8 +61,7 @@ export interface LoopSettings {
 }
 
 export const DEFAULT_LOOP_SETTINGS: LoopSettings = {
-	maxIterations: 25,
-	automaticTurns: 25,
+	maxTurns: 25,
 	noProgressTurns: 3,
 	maxLoopDuration: "7d",
 	inlineInvocation: true,
@@ -76,11 +82,8 @@ export function normalizeLoopSettings(value: unknown): LoopSettings | undefined
 	const record = ownRecord(value);
 	if (!record) return undefined;
 
-	const maxIterations = normalizeCap(record.maxIterations, DEFAULT_LOOP_SETTINGS.maxIterations);
-	if (maxIterations === false) return undefined;
-
-	const automaticTurns = normalizeCap(record.automaticTurns, DEFAULT_LOOP_SETTINGS.automaticTurns);
-	if (automaticTurns === false) return undefined;
+	const maxTurns = normalizeTurnCap(record);
+	if (maxTurns === false) return undefined;
 
 	const noProgressTurns = normalizeCap(
 		record.noProgressTurns,
@@ -134,8 +137,7 @@ export function normalizeLoopSettings(value: unknown): LoopSettings | undefined
 	}
 
 	return {
-		maxIterations,
-		automaticTurns,
+		maxTurns,
 		noProgressTurns,
 		maxLoopDuration,
 		inlineInvocation,
@@ -151,6 +153,32 @@ function normalizeCap(value: unknown, fallback: number | null): number | null |
 	return typeof value === "number" && Number.isSafeInteger(value) && value > 0 ? value : false;
 }
 
+/**
+ * The turn cap, accepting the two caps it replaced.
+ *
+ * A settings file written by an older version names no `maxTurns`, and asking
+ * users to rewrite their settings to keep a cap they already chose is not a
+ * trade worth making. So a file carrying only the legacy keys keeps the
+ * tighter of the two: that is the bound their loops were already running
+ * under. An invalid value in either key still fails the whole file closed,
+ * exactly as it did when the key was current.
+ */
+function normalizeTurnCap(record: Record<string, unknown>): number | null | false {
+	if (Object.hasOwn(record, "maxTurns")) {
+		return normalizeCap(record.maxTurns, DEFAULT_LOOP_SETTINGS.maxTurns);
+	}
+	let adopted: number | null | undefined;
+	for (const key of LEGACY_CAP_KEYS) {
+		if (!Object.hasOwn(record, key)) continue;
+		const cap = normalizeCap(record[key], DEFAULT_LOOP_SETTINGS.maxTurns);
+		if (cap === false) return false;
+		// null is unlimited, so it only wins when every legacy cap is unlimited.
+		if (adopted === undefined || adopted === null) adopted = cap;
+		else if (cap !== null) adopted = Math.min(adopted, cap);
+	}
+	return adopted === undefined ? DEFAULT_LOOP_SETTINGS.maxTurns : adopted;
+}
+
 function readBoolean(record: Record<string, unknown>, key: string, fallback: boolean): unknown {
 	return Object.hasOwn(record, key) ? record[key] : fallback;
 }
@@ -221,11 +249,14 @@ export function saveLoopSettings(settings: LoopSettings, settingsPath = loopSett
 	}
 
 	const compaction = ownRecord(raw.compaction) ?? {};
+	// Unknown fields are preserved, but the two caps `maxTurns` replaced are not
+	// unknown: leaving them next to a cap that supersedes them would show the
+	// user two numbers where only one applies.
+	for (const key of LEGACY_CAP_KEYS) delete raw[key];
 	const document = `${JSON.stringify(
 		{
 			...raw,
-			maxIterations: normalized.maxIterations,
-			automaticTurns: normalized.automaticTurns,
+			maxTurns: normalized.maxTurns,
 			noProgressTurns: normalized.noProgressTurns,
 			maxLoopDuration: normalized.maxLoopDuration,
 			inlineInvocation: normalized.inlineInvocation,

package/src/start-tool.ts

@@ -15,6 +15,14 @@
  * until a cap. So the tool refuses outright unless the inline hint armed for
  * the turn that is calling it.
  *
+ * The one thing this path may decide that the `/loop` command cannot is the
+ * loop's completion criteria. They are otherwise a deterministic split of the
+ * objective's grammar, which turns a context sentence into a gate criterion;
+ * a model that read the objective can do better. It is accepted only *here*,
+ * at start, before any work exists to grade and with the user seeing the
+ * criteria echoed back — the point where the incentive to write an easy gate
+ * is weakest. After start they are immutable, exactly as a derived set is.
+ *
  * Registered unconditionally, like the other loop tools: the tool set is part
  * of the cached request prefix, so it never changes with loop state.
  */
@@ -23,6 +31,7 @@ import { defineTool, type ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { Type } from "typebox";
 import { LOOP_COMPLETE_TOOL } from "./complete-tool.js";
 import { formatDuration, parseDuration, parseInterval } from "./interval.js";
+import { MAX_CRITERIA, MAX_DESCRIPTION_LENGTH } from "./ledger.js";
 import type { InlineInvocationState } from "./inline-invocation.js";
 import type { LoopController } from "./loop.js";
 
@@ -49,7 +58,11 @@ export function registerLoopStartTool(
 				"If the user is discussing, quoting, or documenting the /loop command rather than invoking it — asking how it works, pasting a transcript, or editing text that mentions it — do not call loop_start.",
 				"Pass the objective text that follows the token, without the token itself. A leading interval (`10m`, `2h`) and flags like `--max 5` or `--expires 3d` become the interval, max, and expires parameters, not part of the objective.",
 				"Call loop_start before doing any of the objective's work, then continue working toward it in the same turn.",
+				"Leave the criteria parameter out by default: the extension splits the objective into completion criteria on its own (bullets, else sentences, else the whole objective). Propose criteria only when that split would misfire — when the objective mixes requirements with context sentences (`fix CI. it has been red since Tuesday.`), or packs several requirements into one sentence.",
+				"Every criterion you propose must be a faithful restatement of something the user asked for: never fewer, weaker, or easier than the objective as typed, and never a requirement they did not state. They are echoed back to the user at start and frozen afterwards — you may only ever flip a criterion's passes field.",
+				"When in doubt, omit criteria and let the deterministic split stand.",
 				"Never call loop_complete in the same turn as loop_start: the starting turn has not done the work, and completion needs cited evidence per criterion.",
+				"Before your first loop_start this session, read the pi-loop skill: the objective is split into the completion criteria this loop will be gated on, so its wording is the leverage point.",
 			],
 			parameters: Type.Object({
 				objective: Type.String({
@@ -67,7 +80,8 @@ export function registerLoopStartTool(
 				max: Type.Optional(
 					Type.Integer({
 						minimum: 1,
-						description: "Wake cap from a --max flag in the invocation.",
+						description:
+							"Cap on the turns the loop causes (continuations and pokes), from a --max flag in the invocation.",
 					}),
 				),
 				expires: Type.Optional(
@@ -75,6 +89,17 @@ export function registerLoopStartTool(
 						description: "Loop lifetime from an --expires flag in the invocation, e.g. '3d'.",
 					}),
 				),
+				criteria: Type.Optional(
+					Type.Array(
+						Type.String({ minLength: 1, maxLength: MAX_DESCRIPTION_LENGTH }),
+						{
+							minItems: 1,
+							maxItems: MAX_CRITERIA,
+							description:
+								"Optional completion criteria for this loop, each one checkable requirement restated faithfully from the user's objective. Replaces the deterministic split of the objective, so omit it unless that split would misfire.",
+						},
+					),
+				),
 			}),
 			async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
 				// The gate. Everything below is ordinary validation; this is the
@@ -89,6 +114,14 @@ export function registerLoopStartTool(
 				if (!objective) {
 					return refusal("Loop not started: the objective is empty.", {});
 				}
+				const criteria = params.criteria?.map((description) => description.trim());
+				const badCriteria = criteria && describeBadCriteria(criteria);
+				if (badCriteria) {
+					return refusal(
+						`Loop not started: ${badCriteria}. Pass one short checkable requirement per entry, or omit criteria to split the objective deterministically.`,
+						{ objective },
+					);
+				}
 				const existing = controller.state;
 				if (existing && existing.status !== "stopped") {
 					return refusal(
@@ -119,8 +152,9 @@ export function registerLoopStartTool(
 					requestedMs: interval.requestedMs,
 					intervalMs: interval.effectiveMs,
 					clamped: interval.clamped,
-					...(params.max === undefined ? {} : { maxIterations: params.max }),
+					...(params.max === undefined ? {} : { maxTurns: params.max }),
 					...(expiresInMs === undefined ? {} : { expiresInMs }),
+					...(criteria === undefined ? {} : { criteria }),
 					prompt: objective,
 				});
 				if (!result.ok) return refusal(`Loop not started: ${result.message}`, { objective });
@@ -136,6 +170,26 @@ export function registerLoopStartTool(
 	);
 }
 
+/**
+ * Why a proposed criteria list cannot be used, or undefined when it can.
+ *
+ * A list that says nothing is worse than no list: it would replace the
+ * deterministic split with a gate the model wrote and can pass by saying
+ * anything. So a malformed list refuses the start rather than falling back
+ * silently, which would leave the model believing its criteria were accepted.
+ */
+function describeBadCriteria(criteria: readonly string[]): string | undefined {
+	if (criteria.length === 0) return "the criteria list is empty";
+	if (criteria.length > MAX_CRITERIA) {
+		return `a loop takes at most ${MAX_CRITERIA} criteria and ${criteria.length} were given`;
+	}
+	if (criteria.some((description) => !description)) return "one of the criteria is blank";
+	if (criteria.some((description) => description.length > MAX_DESCRIPTION_LENGTH)) {
+		return `a criterion may be at most ${MAX_DESCRIPTION_LENGTH} characters`;
+	}
+	return undefined;
+}
+
 function refusal(text: string, details: Record<string, unknown>) {
 	return { content: toolContent(text), details, isError: true };
 }

package/src/state.ts

@@ -30,19 +30,17 @@ export interface LoopState {
 	 */
 	objective?: string;
 	intervalMs: number;
-	/** Delivered-poke cap; null means unlimited. */
-	maxIterations: number | null;
-	/** Proactive-compaction threshold fraction, or null when disabled per loop. */
-	compactAt: number | null;
 	/**
-	 * Turns this loop caused; null means unlimited. Counted separately from
-	 * `maxIterations` because one wake now yields many turns: a settle-driven
-	 * continuation chain runs without any wake at all.
+	 * Cap on the turns this loop causes (continuations plus pokes); null means
+	 * unlimited. The only cap: a settle-driven continuation chain runs without
+	 * any wake at all, so a wake cap bounded nothing this one does not.
 	 */
-	maxAutomaticTurns: number | null;
-	/** Delivered wakes so far (fallback pokes only). */
+	maxTurns: number | null;
+	/** Proactive-compaction threshold fraction, or null when disabled per loop. */
+	compactAt: number | null;
+	/** Delivered wakes so far (fallback pokes only); uncapped, and displayed. */
 	iteration: number;
-	/** Loop-caused turns so far (continuations + pokes). */
+	/** Loop-caused turns so far (continuations + pokes): what `maxTurns` caps. */
 	automaticTurns: number;
 	startedAt: number;
 	expiresAt: number;
@@ -91,8 +89,8 @@ export function normalizeLoopState(value: unknown): LoopState | undefined {
 	}
 	const intervalMs = record.intervalMs;
 	if (!isPositiveSafeInteger(intervalMs)) return undefined;
-	const maxIterations = record.maxIterations;
-	if (maxIterations !== null && !isPositiveSafeInteger(maxIterations)) return undefined;
+	const maxTurns = readTurnCap(record);
+	if (maxTurns === false) return undefined;
 	const compactAt = record.compactAt;
 	if (
 		compactAt !== null &&
@@ -100,16 +98,12 @@ export function normalizeLoopState(value: unknown): LoopState | undefined {
 	) {
 		return undefined;
 	}
-	const maxAutomaticTurns = Object.hasOwn(record, "maxAutomaticTurns")
-		? record.maxAutomaticTurns
-		: null;
-	if (maxAutomaticTurns !== null && !isPositiveSafeInteger(maxAutomaticTurns)) return undefined;
 	const iteration = record.iteration;
 	if (typeof iteration !== "number" || !Number.isSafeInteger(iteration) || iteration < 0) {
 		return undefined;
 	}
-	// Loops persisted before the two-counter split carry no automaticTurns; an
-	// absent counter restores as zero rather than rejecting the whole state.
+	// A loop persisted before the turn counter existed carries no automaticTurns;
+	// an absent counter restores as zero rather than rejecting the whole state.
 	const automaticTurns = Object.hasOwn(record, "automaticTurns") ? record.automaticTurns : 0;
 	if (
 		typeof automaticTurns !== "number" ||
@@ -147,8 +141,7 @@ export function normalizeLoopState(value: unknown): LoopState | undefined {
 		...(prompt === undefined ? {} : { prompt }),
 		...(objective === undefined ? {} : { objective }),
 		intervalMs,
-		maxIterations: maxIterations as number | null,
-		maxAutomaticTurns: maxAutomaticTurns as number | null,
+		maxTurns,
 		compactAt: compactAt as number | null,
 		iteration,
 		automaticTurns,
@@ -164,6 +157,33 @@ export function normalizeLoopState(value: unknown): LoopState | undefined {
 	};
 }
 
+/**
+ * The turn cap, adopting the caps a loop persisted by an older version
+ * carries: `maxAutomaticTurns` (turns) and `maxIterations` (wakes). An
+ * in-flight loop restored mid-upgrade keeps the tighter of them rather than
+ * having its bound widened or being dropped as unparsable; its wake *counter*
+ * is kept for display but no longer caps anything. Returns the cap, or false
+ * when a present value is invalid.
+ */
+function readTurnCap(record: Record<string, unknown>): number | null | false {
+	if (Object.hasOwn(record, "maxTurns")) {
+		const value = record.maxTurns;
+		if (value === null) return null;
+		return isPositiveSafeInteger(value) ? value : false;
+	}
+	let adopted: number | null | undefined;
+	for (const key of ["maxAutomaticTurns", "maxIterations"]) {
+		if (!Object.hasOwn(record, key)) continue;
+		const value = record[key];
+		if (value !== null && !isPositiveSafeInteger(value)) return false;
+		const cap = value as number | null;
+		// null is unlimited, so it only wins when every legacy cap is unlimited.
+		if (adopted === undefined || adopted === null) adopted = cap;
+		else if (cap !== null) adopted = Math.min(adopted, cap);
+	}
+	return adopted === undefined ? null : adopted;
+}
+
 // --- session-branch entry readers ---
 
 interface SessionEntryLike {

package/src/widget.ts

@@ -1,6 +1,6 @@
 /**
  * The loop widget: a compact themed line above the editor mirroring the
- * footer status (interval · iteration/cap · next wake), with the loop focus
+ * footer status (interval · loop turns/cap · next wake), with the loop focus
  * dimmed below it when set.
  *
  * Presentation only: every entry point tolerates a host without setWidget
@@ -61,13 +61,15 @@ export function clearLoopWidget(ui: WidgetHost) {
 export function loopWidgetLine(view: LoopWidgetView) {
 	const loop = view.loop;
 	if (loop.status === "paused") return "⏸ loop paused";
-	const cap = loop.maxIterations === null ? "∞" : `${loop.maxIterations}`;
+	const cap = loop.maxTurns === null ? "∞" : `${loop.maxTurns}`;
 	const next = view.wakePending
 		? "next on idle"
 		: view.nextWakeAt !== undefined
 			? `next ${formatClock(view.nextWakeAt)}`
 			: "next unscheduled";
-	return `⟳ loop every ${formatDuration(loop.intervalMs)} · ${loop.iteration}/${cap} · ${next}`;
+	// The turn counter, not the wake counter: the cap counts turns, so a
+	// progress line against that cap has to count the same thing.
+	return `⟳ loop every ${formatDuration(loop.intervalMs)} · ${loop.automaticTurns}/${cap} · ${next}`;
 }
 
 function identity(text: string) {