@hank-warren/pi-loop 0.5.0 → 0.7.0

package/CHANGELOG.md

@@ -1,5 +1,34 @@
 # @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
+
+- b642391: Removing goal-bound loops is breaking for anyone holding one; it lands as a 0.x minor per this repo's convention.
+
+  **Start a loop from an inline `/loop` invocation.** Pi dispatches `/loop` only when it is the first thing in the message, so `quick check /loop 10m get CI green` used to arrive as prose and vanish. A new `loop_start` tool, pointed at by a one-turn `<system-reminder>`, now starts the loop and begins working in the same turn. `loop: <objective>` at line start works the same way. The message itself is never rewritten, split, re-sent, or annotated: an `input` handler only records it, and `before_agent_start` appends the hint when the starting prompt is that same message.
+
+  `loop_start` **refuses unless the inline hint armed for that turn.** A loop is self-continuing, so a spurious start does not produce one unwanted answer, it produces turns until a cap — that gate is enforcement rather than prompt guidance. It also refuses when a loop is already active, when `loop_complete` is missing from the active tool set, and on an unparsable objective, interval, or expiry.
+
+  New settings: `inlineInvocation` (default `true`) and `defaultInterval` (default `"10m"`, used when an invocation names no interval).
+
+  **Goal-bound loops are gone,** along with every `goal-state` reader, the completion-race clear-scan, and the goal outcomes in the tick and continuation decisions. A loop owns its objective, ledger, post-compaction re-anchor, and evidence-gated completion, so delegating completion to a second extension bought nothing and cost a coupling. `plan-mode-state` is now the only sibling entry pi-loop reads.
+
+  A loop persisted before this release with no objective of its own adopts its focus text as one on restore, and pauses with an explanation when there is nothing to adopt.
+
+  `@hank-warren/pi-goal` is deprecated in favour of this package. Its published versions stay installable.
+
 ## 0.5.0
 
 ### Minor Changes

package/README.md

@@ -2,30 +2,16 @@
 
 Inspired by Claude Code's `/loop`, adapted to Pi: keep work moving across many turns, and keep long loops coherent across context compaction.
 
-A loop is a **pacemaker**: it owns *when* the session works. What it works *on* comes in two modes, chosen automatically when the loop starts:
+A loop is a **pacemaker** that owns its own work: it carries an objective and completion criteria, and ends when the model calls `loop_complete` with cited evidence, a cap is reached, its expiry arrives, or you stop it. **No other extension is required.**
 
-- **Standalone** — the loop carries its own objective and completion criteria. It ends when the model calls `loop_complete`, a cap is reached, or you stop it. **No other extension required**, and this is the mode to use.
-- **Goal-bound** (**deprecated**) — an active [pi-goal](../pi-goal) goal is present, so the loop binds to it and pi-goal owns *whether the work is done*. Coupling stays read-only: fail-open reads of pi-goal's `goal-state` entries.
+Earlier versions could instead bind a loop to a [pi-goal](https://www.npmjs.com/package/@hank-warren/pi-goal) goal and let that extension own *whether the work is done*. That mode is gone as of 0.6.0, along with every `goal-state` reader: a loop now does everything the pairing did — objective, durable ledger, post-compaction re-anchor, evidence-gated completion — so the coupling bought nothing. A loop persisted before 0.6.0 that carries no objective adopts its focus text as one on restore, and pauses with an explanation when there is nothing to adopt.
 
-**An active goal still wins**, for now: start a loop while a goal is running and it binds to that goal, with any trailing text kept as a per-wake focus — with a deprecation warning. With no active goal, the trailing text becomes the loop's own objective.
-
-### Goal-bound loops are going away
-
-A standalone loop now does everything the pairing did — it owns its objective, keeps a durable ledger, re-anchors itself after compaction, and gates completion on cited evidence — so delegating "is the work done" to a second extension buys nothing and costs a coupling. [pi-goal](../pi-goal) carries the matching deprecation banner.
-
-This release keeps the goal-bound path working, warns when you start one, and **migrates a restored goal-bound loop to standalone** by adopting the goal's objective text (falling back to the loop's own focus text). The one case it deliberately does not migrate is a **still-active** goal: pi-goal is driving that session's continuations, and a standalone loop driving them too would send two messages at every settle — that loop keeps its old behaviour and gets the warning instead. If there is nothing to adopt at all, the loop pauses and says so rather than pretending.
-
-The following release removes the goal-bound branch, the `goal-state` readers, and their fixtures.
-
-pi-plan-mode's `plan-mode-state` is read the same fail-open way in both modes, so a loop never injects into a planning conversation.
+pi-plan-mode's `plan-mode-state` is read fail-open — the only sibling state left — so a loop never injects into a planning conversation.
 
 ## Usage
 
 ```
-/loop 30m until all tests pass and CI is green   # standalone: the loop owns the objective
-/goal get CI green                               # ...or bind to a goal
-/loop 30m                                        #    poke that goal every 30m if the session stalls
-/loop 10m recheck the pipeline                   #    trailing text is a per-wake focus when goal-bound
+/loop 30m until all tests pass and CI is green   # the trailing text is the objective
 /loop                                            # manager TUI (status, pause/resume, edit, settings, stop)
 /loop status | pause | resume | stop | settings
 /loop --max 20 --compact-at 60% --expires 3d 10m # per-loop overrides
@@ -33,7 +19,27 @@ pi-plan-mode's `plan-mode-state` is read the same fail-open way in both modes, s
 ```
 
 - **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).
-- `/loop` is deliberately **user-typed only** — the model never starts or stops loops. (Inline `/goal` invocation is the [pi-goal fork](https://github.com/hank-warren/pi-extensions/tree/main/packages/pi-goal)'s `goal_start` tool.)
+- **`--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
+
+Pi dispatches `/loop` only when it is the first thing in the message, so `quick check /loop 10m get CI green` arrives as ordinary prose and nothing happens. That is the common way to lose an invocation, so pi-loop detects it:
+
+```
+quick check /loop 10m get CI green on main, verified by a passing run
+loop: get CI green on main, verified by a passing run
+```
+
+Both make the model call the `loop_start` tool with the objective and then begin working, in the same turn.
+
+**Your message is never touched** — not cut, split, re-sent, or annotated. An `input` handler only *records* the text; `before_agent_start` appends a one-turn `<system-reminder>` when the starting prompt is that same message. The hint is a per-turn system-prompt append, never a stored message, so "call loop_start now" cannot linger and fire on a later turn.
+
+Detection is deliberately narrow. A token at position 0 is ignored (that is Pi's own dispatch), as is one inside backticks or a quoted span — `` `/loop` `` and `"/loop 5m ship it"` are how people *discuss* the command — and a bare trailing `/loop` with no remainder. The `loop:` form needs to start a line, so "my loop: is unclear" is prose. Extension-sent prompts never arm, and neither does steered or queued input, whose delivery order would leave a stale arm behind.
+
+**`loop_start` refuses unless the turn was armed.** This is enforcement, not guidance. A loop is *self-continuing*: a spurious start does not produce one unwanted answer, it produces turns until a cap. So the tool checks a flag the inline hooks set for exactly one turn, and refuses outright otherwise, along with a loop already being active, a missing `loop_complete`, or an unparsable interval or expiry.
+
+An invocation that names no interval uses the `defaultInterval` setting (`10m`). In a settle-paced loop the interval is only a fallback heartbeat, so the value matters far less than it looks. Turn the whole feature off with `"inlineInvocation": false`.
 
 ## What paces a loop
 
@@ -55,43 +61,37 @@ 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.
 
-A **goal-bound** loop is unchanged: pi-goal drives its own settle continuations, so pi-loop would only double every turn, and the interval stays that loop's only driver.
+### One cap
 
-### Two counters
+`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.
 
-One wake now yields many turns, so a single counter cannot bound a loop:
+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.
 
-- `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.
-
-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
 
 Each tick — fallback heartbeat or settled boundary — evaluates, in order:
 
-1. **Expired?** Loops hard-expire after `maxLoopDuration` (default 7 days, or per loop with `--expires 3d`, echoed at start) — a forgotten loop is bounded. A standalone loop gets **one final turn** first: "write the current state into the ledger, start no new work, claim no completion", and the settle after it stops the loop. A loop that simply vanished at its deadline would leave its most recent state only in a conversation about to be closed. If that final wake cannot be delivered, the loop stops immediately rather than living past its deadline.
+1. **Expired?** Loops hard-expire after `maxLoopDuration` (default 7 days, or per loop with `--expires 3d`, echoed at start) — a forgotten loop is bounded. The loop gets **one final turn** first: "write the current state into the ledger, start no new work, claim no completion", and the settle after it stops the loop. A loop that simply vanished at its deadline would leave its most recent state only in a conversation about to be closed. If that final wake cannot be delivered, the loop stops immediately rather than living past its deadline.
 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. **Mode-specific stop criteria.** *Standalone*: none — the loop reads no goal state at all, so pi-goal being absent, complete, or paused is irrelevant to it; it ends only via `loop_complete`, a cap, or you. *Goal-bound*: a missing goal (cleared mid-loop) **pauses** the loop; completion **stops** it — including through the clear that follows it, since pi-goal persists the finished goal and *then* clears the entry, so the newest entry at completion is a clear and the loop reads back past it; a safety pause (`paused`/`blocked`/`usage_limited`/`budget_limited`, or any unknown status) **pauses** it — pi-loop never pokes past pi-goal's circuit breakers. An `active` or `goal_wait`-waiting goal in an idle session is exactly the stall this extension exists for, so it pokes toward the goal (a tick is the external wake `goal_wait` arranges).
-5. **Caps** (see [Two counters](#two-counters)): stop.
-6. **Settled boundary, standalone loop:** 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.
-
-6. **Poke**: a goal wake message — the wake header, why it fired (stalled or the external wake for a waiting goal), 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**, in either mode — the objective always 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. The two modes differ only in who provides that append: pi-goal's, on every active goal turn, for a goal-bound loop; this extension's own, for a standalone one. Both work because pokes are delivered as ordinary user messages that pass through `before_agent_start`.
+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. **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.
 
-That makes the goal-bound case a genuine **cross-extension assumption**, and the last one left: if pokes were ever delivered by a path that bypasses `before_agent_start` (for example `pi.sendMessage({triggerTurn})`, which calls the agent directly), a goal-bound poke would arrive with no objective anywhere and would have to carry it again. It disappears with the goal-bound path. The token-lean contract is pinned in `test/messages.test.ts`; the matching cache-stability contract lives in [pi-goal](https://github.com/hank-warren/pi-extensions/tree/main/packages/pi-goal#fork-feature-cache-safe-token-lean-injections), whose README records the same assumption from the other side.
+**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, completion, and pi-goal's safety states are evaluated whenever the session settles, so a loop stops as soon as its goal 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.
 
-## Standalone loops: objective, injection, and `loop_complete`
+## Objective, injection, and `loop_complete`
 
-A standalone loop has to put its objective in front of the model itself, since no pi-goal append is doing it. It uses the same cache-safe split pi-goal uses:
+A loop puts its own objective in front of the model, under a cache-safe split:
 
 - **Static per loop — the system prompt.** The objective, `loop_id`, ledger contract, and loop-mode rules are appended to the system prompt, **byte-identically on every turn of that loop**. Anthropic caches `tools → system → messages` as one prefix, so a moving value there (iteration, next wake) would invalidate the cache for the whole conversation every wake. It changes only when the loop does.
 
@@ -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.
@@ -151,7 +153,7 @@ The system append carries the objective only while the loop is *active*, and con
 Long loops die by context exhaustion, not by failing. pi-loop owns the compaction path:
 
 - **Proactive compact at a threshold** (default 70% of the context window, `--compact-at` / settings): at an idle boundary, pi-loop triggers `/compact` itself with loop-specific instructions — preserve the objective and acceptance criteria verbatim, **every failed approach and the reason it failed**, decisions and rationale, files modified, commands and unresolved errors, and the next 1-3 actions. The instructions explicitly **stop carrying prior summaries forward wholesale** and tell the next turn to re-derive status from the ledger and authoritative state instead: cumulative carry-forward grows the text while the information in it decays. Pending pokes are held until the compaction completes. Pi's reserve-token auto-compaction remains as the fault handler.
-- **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. A standalone loop no longer goes quiet until the next wake, and nothing is delegated to pi-goal. A re-anchor supersedes an ordinary continuation already queued: after a compaction, "re-read the ledger" is strictly the better instruction. (A goal-bound loop still leaves that message to pi-goal, which owns its continuations.)
+- **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
@@ -196,10 +198,11 @@ 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,
+  "defaultInterval": "10m",
   "compaction": {
     "enabled": true,
     "threshold": 0.7,
@@ -208,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.
+`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
 
@@ -218,13 +221,21 @@ 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
 pi install npm:@hank-warren/pi-loop
 ```
 
-**No other extension is required.** A standalone loop stands alone; a goal extension (`npm:@hank-warren/pi-goal` or upstream `@narumitw/pi-goal`) is only needed for the deprecated goal-bound mode, and that mode is being removed.
+**No other extension is required.** The only sibling state pi-loop reads is [pi-plan-mode](https://www.npmjs.com/package/@hank-warren/pi-plan-mode)'s, fail-open, so a loop never injects into a planning conversation — and it works fine without it.
 
 ## License
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hank-warren/pi-loop",
-  "version": "0.5.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

@@ -1,5 +1,5 @@
 /**
- * `loop_complete`: the standalone loop's terminal tool.
+ * `loop_complete`: the loop's terminal tool.
  *
  * It used to be deliberately thin, on the argument that stopping a pacemaker
  * has a small blast radius: the user just restarts it. That argument does not
@@ -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({
@@ -94,7 +120,7 @@ export function registerLoopCompleteTool(pi: ExtensionAPI, controller: LoopContr
 				if (!loop || loop.objective === undefined) {
 					return {
 						content: toolContent(
-							"No standalone /loop is active. loop_complete only applies to a loop started with its own objective; a goal-bound loop is ended through pi-goal.",
+							"No /loop with an objective is active, so there is nothing to complete. Start one with /loop <interval> <objective>.",
 						),
 						details: { loopId: params.loop_id },
 						isError: true,
@@ -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) {