@llblab/pi-kit 0.1.0

package/node_modules/@llblab/pi-codex-usage/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "@llblab/pi-codex-usage",
+  "version": "0.9.2",
+  "private": false,
+  "description": "Minimal Pi extension that shows primary Codex ChatGPT subscription usage limits",
+  "keywords": [
+    "pi-package",
+    "pi-extension",
+    "pi",
+    "codex",
+    "usage",
+    "status"
+  ],
+  "type": "module",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/llblab/pi-codex-usage.git"
+  },
+  "homepage": "https://github.com/llblab/pi-codex-usage",
+  "bugs": {
+    "url": "https://github.com/llblab/pi-codex-usage/issues"
+  },
+  "engines": {
+    "node": ">=22.19.0"
+  },
+  "scripts": {
+    "check": "node --experimental-strip-types -e \"await import('./index.ts'); console.log('pi-codex-usage: extension import ok')\"",
+    "test": "node --experimental-strip-types --test test/*.test.ts",
+    "typecheck": "tsc --noEmit",
+    "pack:dry": "npm pack --dry-run",
+    "validate": "npm run typecheck && npm run test && npm run check && npm run pack:dry"
+  },
+  "files": [
+    "index.ts",
+    "README.md",
+    "AGENTS.md",
+    "BACKLOG.md",
+    "CHANGELOG.md",
+    "LICENSE",
+    "banner.jpg"
+  ],
+  "pi": {
+    "extensions": [
+      "./index.ts"
+    ],
+    "image": "https://github.com/llblab/pi-codex-usage/raw/main/banner.jpg"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-agent-core": "*",
+    "@earendil-works/pi-ai": "*",
+    "@earendil-works/pi-coding-agent": "*",
+    "@sinclair/typebox": "*"
+  },
+  "devDependencies": {
+    "@types/node": "latest",
+    "typescript": "latest"
+  }
+}

package/node_modules/@llblab/pi-grow-loop/AGENTS.md

@@ -0,0 +1,56 @@
+# Project Context
+
+## Meta-Protocol Principles
+
+- `Constraint-Driven Evolution`: Add loop complexity only after real runs expose durable constraints.
+- `Single Source of Truth`: Keep durable rules in `AGENTS.md`, open work in `BACKLOG.md`, completed delivery in `CHANGELOG.md`, and operator-facing usage in `README.md`.
+- `Clean Backlog`: `BACKLOG.md` must contain only unresolved open work. When a task is completed, move the outcome into `CHANGELOG.md` and remove the completed item from `BACKLOG.md` instead of leaving checked-off history there.
+- `Release Heading Format`: `CHANGELOG.md` release sections use second-level headings in the form `## MAJOR.MINOR.PATCH: Release Summary`, with a compact Title Case summary such as `Initial Release`.
+- `Release-Level Changelog`: `CHANGELOG.md` records final release outcomes, not raw iteration telemetry or superseded internal steps. Keep entries linear, domain-tagged, and coherent for a release reader.
+- `Docs Directory Purpose`: Create `docs/` only when there are multiple project documentation pages that need an index. A lone extra README under `docs/` is unnecessary; the root `README.md` is the human entrypoint.
+- `Boundary Clarity`: Keep meta-loop decision, worker iteration, and runtime trigger separate.
+- `Scope-First Activation`: Grow Loop starts from a concrete user-focus task scope, not from command phrasing alone. Prefer a canonical open-work surface explicitly declared by relevant project-local delivery instructions, then project-local surfaces near the active working directory; resolve declarations relative to their owner, reject scope mismatch, and stop on unresolved competing ownership instead of selecting unrelated work.
+- `Lexical Intent Precedence`: An explicitly named protocol selects its exact behavior. Standalone `while-true` runs only the portable worker; standalone `grow-loop` selects the meta-protocol; `while true | grow loop` is reserved for runtime continuation.
+- `Structural Routing`: When no protocol is named, route by delegated execution shape and checkpoint topology, never by verbs, work categories, prompt length, apparent size, or internal step count. One coherent change with one natural validation/reporting boundary remains ordinary execution; a concrete outcome may select Grow Loop when it benefits from multiple independently useful validated slices and visible continuation checkpoints. Bootstrapping a canonical backlog from an explicit requested outcome is decomposition, not speculative work invention.
+- `Stop Honesty`: Exact proof-of-stop is better than simulated autonomous momentum.
+
+## Concept
+
+`pi-grow-loop` is a semantic loop-engineering layer for agent-owned, visible, interruptible continuation from real project state. The runtime exposes one `grow_loop` scheduling tool with an optional `after_seconds` delay; the agent retains semantic ownership of scope, evidence, priority, safety, and continuation. The `grow-loop` skill decides whether another iteration should run, and the portable `while-true` skill performs one bounded worker pass.
+
+## Boundaries
+
+- `grow-loop` skill owns continuation semantics: continue or stop.
+- Routing selects the protocol before worker execution: explicit names override inference; otherwise concrete iterative tasks may select Grow Loop when multiple validated slices and visible checkpoints are useful.
+- `while-true` skill owns only one portable worker pass: discover one canonical work surface, including neutral `Canonical open work: <path>` declarations from relevant project-local delivery instructions, assess reality, reconcile the plan, assemble one bounded validation cohort, execute independent low-coupling tasks with per-task falsification, run shared validation, and hand off. It batches by default when diagnosis remains clear and falls back to a single task for coupled, ordered, large, high-risk, or ambiguous work. A standalone invocation must not activate or call a continuation scheduler. It must not own continuation, user-stop semantics, command phrases, runtime tools, status text, or extension-specific controls; `grow-loop` plus `grow_loop` own sequential continuation only after Grow Loop was selected.
+- `grow_loop` tool only schedules the next visible iteration; its optional `after_seconds` argument accepts `3` through `3600` and defaults to `3`; the minimum preserves an operator-interrupt window before every continuation. Scheduling is idle-deferred: the tool first waits until Pi is idle and no user messages are pending, then starts the configured countdown and sends the compact trigger `while true | grow loop` only if Pi is still idle and no user messages are pending. A longer delay may serve as a continuation timer while asynchronous work finishes. The agent chooses it from evidence about expected remaining duration and reassesses after every wake; the one-hour maximum is exceptional rather than a polling default. If the runtime becomes busy during the countdown, the tool returns to deferred waiting instead of queueing a hidden follow-up. Status shows deferred scheduling as `loop ∞N` with the iteration number in warning color, countdown as `loop Ns`, and active iterations as `loop ∞N` with the iteration number dimmed; `N` is monotonic within the extension instance.
+- There is no slash-command control surface. Any ordinary user prompt exits the active runtime rhythm by clearing pending scheduling and hiding loop status; restart/continuation intent belongs to the agent and Grow Loop skill, not to a runtime latch or regex.
+- No start slash commands, budgets, cycle counts, hidden processes, or background agents.
+- Loop status is dynamic: show warning-colored `loop ∞N` only while the next iteration is deferred until idle, `loop Ns` only during the configured countdown, and dim `loop ∞N` only while a loop-scheduled turn is active. Clear active status only after Pi fully settles without an armed successor; low-level run endings may still lead to retry or compaction recovery. Any user input except the runtime's exact expected continuation prompt clears pending loop scheduling and hides loop status, including operator input injected through another extension.
+- Grow Loop does not own Escape/abort semantics; Escape remains baseline Pi behavior for active agent turns. The runtime does not block future `grow_loop` tool calls; the skill contract owns whether recent user context means continue, stop, restart, or change direction.
+
+## Topology
+
+```text
+index.ts                  optionally delayed grow_loop tool
+skills/grow-loop/SKILL.md meta-loop protocol
+skills/while-true/SKILL.md worker-loop protocol baseline
+README.md                 human entrypoint
+BACKLOG.md                open work
+CHANGELOG.md              completed delivery history
+```
+
+## Evolution Path
+
+1. Keep the MVP as one no-argument tool.
+2. Let the skills dogfood themselves on this extension.
+3. Add state only if real runs prove it is necessary.
+4. Preserve the separation: decision in skill, execution in while-true, triggering in tool.
+5. Preserve exact named entrypoints while allowing natural multi-slice tasks to bootstrap a truthful backlog and select Grow Loop automatically.
+
+## Style
+
+- Prefer small, inspectable TypeScript over framework or actor dependencies.
+- Use concise operator copy.
+- Keep prompt contracts explicit and bounded.
+- Record completed growth evidence in `CHANGELOG.md`; keep `BACKLOG.md` clean and limited to unresolved work.

package/node_modules/@llblab/pi-grow-loop/BACKLOG.md

@@ -0,0 +1,3 @@
+# Backlog
+
+No open work.

package/node_modules/@llblab/pi-grow-loop/CHANGELOG.md

@@ -0,0 +1,126 @@
+# Changelog
+
+## 0.7.1: Banner Presentation Hotfix
+
+- [Docs] Display the packaged project banner at the top of the README through its stable repository URL so GitHub and npm readers see the release identity immediately.
+
+## 0.7.0: Configurable Continuation Delay
+
+- [Runtime] Add optional `after_seconds` scheduling from 3 through 3600 seconds, preserving the minimum operator-interrupt window while letting agents defer the next visible iteration until asynchronous work is worth checking.
+- [Agent Contract] Guide agents to choose evidence-based waits, reserve the one-hour maximum for genuinely long work, and reassess the delay after every wake instead of polling mechanically.
+- [Package] Ship the package banner and expose it through Pi package metadata alongside synchronized runtime, skill, operator-guide, and validation contracts.
+
+## 0.6.2: Version-Independent Skills
+
+- [Skills] Decouple bundled `grow-loop` and `while-true` frontmatter from npm package versions so reusable protocol identity no longer duplicates release state.
+- [Docs] Normalize emphasized resolution and validation labels so punctuation remains outside bold text without changing protocol behavior.
+- [Evidence] Align packaging assertions with version-independent skill metadata and normalized Markdown while retaining discovery, routing, and cohort contract coverage.
+
+## 0.6.0: Batched Validation Cohorts
+
+- [Worker] Make one bounded validation cohort the default `while-true` execution unit, batching independent low-coupling backlog tasks while retaining single-task execution for coupled, ordered, large, high-risk, or diagnostically ambiguous work.
+- [Efficiency] Give every cohort task a cheap focused falsifier, then share expensive type, build, integration, context, or live validation across the completed cohort without sacrificing failure attribution.
+- [Boundaries] Keep cohort assembly inside the portable worker while Grow Loop consumes the resulting handoff as one checkpoint and retains sole ownership of continuation.
+- [Interop] Preserve the runtime rhythm only for its exact expected continuation prompt; operator messages delivered through Telegram, RPC bridges, or other extensions now cancel pending scheduling and hide loop status like direct input.
+- [Compatibility] Validate the package on both the declared minimum Node.js `22.19.0` runtime and the latest Node.js release in CI.
+- [Evidence] Cover cohort contracts, bridge-injected interruption, exact own-prompt exemption, synchronized package metadata, strict type checking, extension import, and packed source shape.
+
+## 0.5.0: Scope-Locked Work Surfaces
+
+- [Discovery] Resolve relative, external, portfolio-linked, stale, missing, scope-mismatched, and competing canonical-open-work declarations without knowing which project-local method produced them.
+- [Safety] Stop on unresolved declaration ownership and refuse to harvest unrelated available work when a declared surface moves or disappears.
+- [Continuity] Preserve declared work-surface ownership across bounded iterations until user intent or verified repository reality changes it.
+- [Boundaries] Keep mature knowledge, support guidance, historical delivery text, examples, insights, and procedural prose outside task discovery unless they explicitly declare trustworthy current canonical open work; allow the same skill to declare work again when feature pressure returns.
+- [Docs] Align operator and agent contracts around deterministic feature-local work resolution and one canonical task owner.
+- [Evidence] Keep the plain-text declaration after independent composition runs showed that scope and ownership validation resolve current friction without a producer registry, lifecycle marker, or structured metadata layer.
+
+## 0.4.3: Declared Work Surfaces
+
+- [Discovery] Let relevant project-local delivery instructions declare one canonical open-work surface through the neutral `Canonical open work: <path or external reference>` contract.
+- [Worker] Give trustworthy declared surfaces precedence over filename-based plan discovery while refusing to mine procedural skill prose or unrelated skills for available work.
+- [Scope] Let Grow Loop lock a declared feature-local work surface without naming or depending on the skill or methodology that produced it.
+- [Truth] Treat portfolio pointers as indexes rather than duplicate task lists and preserve one canonical task owner per feature scope.
+- [Docs] Document independent composition between project-local delivery instructions and the portable worker protocol.
+- [Release] Synchronize package, lockfile, and bundled-skill metadata at `0.4.3`.
+
+## 0.4.2: Structural Routing
+
+- [Routing] Remove verb-, work-category-, and apparent-size-based activation language from the Grow Loop retrieval surface.
+- [Skills] Define natural routing through a concrete delegated outcome, independently useful bounded slices, separate validation evidence, and operator-visible continuation checkpoints.
+- [Docs] Align public and agent-facing contracts around execution topology while keeping concrete task references illustrative rather than normative.
+- [Compatibility] Preserve automatic routing for natural multi-slice outcomes and ordinary one-shot execution for coherent changes without changing runtime behavior or continuation authority.
+- [Release] Synchronize package, lockfile, and bundled-skill metadata at `0.4.2`.
+
+## 0.4.1: Semantic Annealing
+
+- [Runtime] Keep active loop status visible through low-level agent endings and clear it on Pi's `agent_settled` event, preventing automatic retry or compaction recovery from appearing idle; require Pi `0.80.4` or newer for this lifecycle contract.
+- [Tests] Cover settled lifecycle cleanup, preservation of an armed successor, and package-to-skill version synchronization.
+- [Routing] Clarify that multiple internal steps may remain one-shot work; Grow Loop applies when a concrete outcome benefits from independently validated slices and visible continuation checkpoints.
+- [Skills] Align the portable worker handoff with the meta-protocol checkpoint contract and define a bounded slice as one coherent unit rather than an artificially tiny file, command, or step.
+- [Docs] Explain the project-cultivation boundary as semantic execution-shape judgment without adding keyword classification, confirmation rituals, or a narrower automatic-routing range.
+- [Release] Synchronize package, lockfile, and bundled-skill metadata at `0.4.1` while preserving the existing autonomy and operator-control envelope.
+
+## 0.4.0: Bounded Worker Meta-Protocol
+
+- [Runtime] Clear active loop status when a loop-scheduled agent run ends without arming a successor, while preserving deferred status when the ending run schedules another iteration.
+- [Skills] Consolidate `while-true` into one canonical bounded-worker protocol while preserving its named Anti-Bullshit Gate, plan bootstrap and insight classification, autonomous execution boundary, progressive-hardening safeguards, unblocker-aware priority, validation discipline, convergence controls, and visible Grow Loop continuation boundary.
+- [Skills] Consolidate `grow-loop` around scope locking, intent precedence, explicit worker-handoff consumption, checkpoint-signature comparison, gated preparation, and exactly-once continuation decisions.
+- [Docs] Strengthen the README as the human protocol contract with explicit entrypoint routing, ownership boundaries, bounded-slice semantics, worker handoff, scope continuity, operator-intent precedence, exactly-once continuation, and navigable project context.
+- [Routing] Give explicit protocol names lexical precedence: standalone `while-true` remains worker-only, explicit `grow-loop` selects the meta-protocol, the combined prompt remains runtime-internal, and unnamed multi-slice outcomes may bootstrap a backlog and route automatically into Grow Loop.
+- [Positioning] Define the project concisely as semantic loop engineering: portable bounded work plus visible, interruptible scheduling, with continuation meaning owned by the agent rather than runtime machinery.
+- [Validation] Add strict TypeScript no-emit checking for extension and test sources, isolated from transitive peer-package declaration defects.
+- [Tests] Cover terminal active-status cleanup and successor-status preservation across the `agent_end` lifecycle boundary.
+- [Release] Advance package and bundled-skill metadata to 0.4.0, reflecting the new bounded worker and explicit continuation contracts alongside lifecycle and validation hardening.
+
+## 0.3.0: Status-Only Runtime
+
+- [Runtime] Removed hidden follow-up delivery from countdown races; if Pi becomes busy before dispatch, Grow Loop returns to deferred waiting and keeps the next prompt visible/interruption-friendly.
+- [Controls] Reduced runtime interruption semantics to status-only behavior: any user prompt clears pending loop scheduling and hides loop status, while agent/skill intent handling decides whether future turns call `grow_loop` again.
+- [Controls] Removed Grow Loop-owned Escape/abort handling from runtime tests and documentation; Escape is treated as baseline Pi behavior outside this extension's control surface.
+- [Docs] Reworked README as a product-facing guide with early `/goal` comparison, clearer use cases, `while-true` as the worker protocol, compact runtime status language, and skill-owned continuation decisions.
+- [Tests] Replaced follow-up, synthetic abort, restart-regex, no-op injection, and stop/pause allowlist expectations with deferred retry and generic user-interjection coverage.
+
+## 0.2.1: Runtime Prompt Polish
+
+- [Controls] Added a conservative allowlist for polite continuation-break prompts: `please stop`, `stop please`, `please pause`, `pause please`, `cancel loop`, and `cancel grow loop`.
+- [Tests] Covered polite stop/pause/cancel latching, queued prompt no-op injection, and ordinary interjection non-latching behavior.
+
+## 0.2.0: Dogfood-Ready Runtime
+
+- [Runtime] Fixed grace-countdown timeout ownership so cancellation paths clear both the countdown interval and the already-created send timeout through the same pending iteration handle.
+- [Controls] Added explicit `pause` prompt handling as a latched stop-equivalent state with `loop paused` status and restart through existing start prompts.
+- [Docs] Aligned README and project context around the runtime control model: stop/pause latch, ordinary interjection cancels rhythm only, and Esc/abort is not a durable stop latch without contextual evidence.
+- [Docs] Added README runtime state-machine, dogfooding protocol, and compact operator transcript examples so operators can infer loop states, controls, release discipline, no-op queued stops, and stop-proof shape without reading runtime code.
+- [Skills] Restored `while-true` as the fractal work loop while making the responsibility boundary explicit: it runs from an existing backlog/plan/TODO/work surface without waiting for user opinion; no-actionability stop belongs to `while-true`; cross-turn continuation and user continuation-break intent belong to `grow-loop`/runtime.
+- [Tests] Added regressions proving all mid-countdown cancellation paths clear already-created send timeouts, including stop, pause, ordinary interjection, repeated scheduling, abort, and shutdown.
+- [Tests] Added runtime harness helpers for tool execution, input injection, shutdown, latest status, and no-prompt assertions to keep cancellation coverage easier to extend.
+- [Tests] Covered source-checkout skill discovery for present and missing co-located `skills/` directories.
+- [Release] Added GitHub Actions validation on pull requests and `main` pushes using Node 22.19.0, `npm ci`, and `npm run validate`.
+- [Release] Added a README release smoke checklist covering validation, dry pack contents, git/npm install checks, `/reload`, and skill visibility in source/package modes.
+
+## 0.1.2: Skill Discovery Hotfix
+
+- [Skills] Added runtime resource discovery for the co-located `skills/` directory and preserved `sourceSkills` metadata so source checkouts contribute the bundled `grow-loop` and `while-true` skills the same way installed packages do.
+
+## 0.1.1: Idle-Deferred Scheduling Hotfix
+
+- [Runtime] Changed `grow_loop` scheduling to wait until Pi is idle and no user messages are pending before starting the 3-second grace countdown or queueing the next `while true | grow loop` prompt. Impact: active agent work and operator interjections keep priority over the next loop iteration.
+- [UX] Added a deferred-schedule status state: `loop ∞N` uses warning color while the next iteration is armed but not yet counting down, then switches to the countdown and dim running state at the appropriate phases. Impact: operators get a quiet visible hint that a future loop prompt is pending.
+- [Controls] Made Esc/abort cancel deferred scheduling or grace-delay timers without entering stopped state, while explicit stop prompts still set stopped state and protect already queued loop prompts with no-op guidance.
+- [Docs] Updated README and project context to describe idle-deferred scheduling, deferred warning status, and the refined Esc/stop split.
+
+## 0.1.0: Initial Release
+
+- [Release] Completed live Grow Loop dogfooding against this repository: the extension selected a backlog task, executed release-readiness validation, reconciled context, and returned to a clean backlog.
+- [Release] Created the initial `pi-grow-loop` extension as a compact, visible, interruptible loop rhythm for Pi.
+- [Runtime] Added one no-argument `grow_loop` tool that schedules the next visible iteration after a fixed 3-second operator-interrupt grace countdown.
+- [Runtime] Sends the compact trigger `while true | grow loop`, pauses when user messages are pending, and uses follow-up delivery only when the session is not idle.
+- [Runtime] Added plain-English stop/restart handling, abort-aware timer cleanup, stopped-state scheduling guard, session shutdown cleanup, and queued-prompt no-op instruction injection.
+- [UX] Added dynamic status rhythm: `loop 3.0s` appears only during grace countdown, `loop ∞N` appears only while a loop-scheduled turn is active, and ordinary user interjection hides loop status without entering stopped state.
+- [Skills] Bundled the `grow-loop` meta-protocol for scope-first continuation decisions and the `while-true` worker protocol for one bounded actionable iteration.
+- [Skills] Reframed activation as scope-first rather than command-first: the agent must select a trustworthy user-focus task surface before continuing.
+- [Docs] Expanded `README.md` into the primary RhythmE entrypoint with install commands, value proposition, scope discovery, loop rhythm, stop semantics, goal-command comparison, release stance, and non-goals.
+- [Context] Added durable project rules for clean backlog state, changelog release-heading format, docs-directory purpose, scope-first activation, and context/changelog/backlog ownership.
+- [Manifest] Prepared the simple source-TS package shape: `pi.extensions` points at `./index.ts`, `pi.skills` points at `./skills`, and there is no build step or generated `dist/` tree.
+- [Manifest] Prepared npm package metadata for publication with repository, homepage, bugs, keywords, engines, `private: false`, and host-aligned peer dependencies.
+- [Tests] Added runtime and packaging regression coverage for prompt matching, delayed scheduling, pending-message pause, repeated schedule cancellation, ordinary user interjection status hiding, stop/restart, abort cleanup, shutdown cleanup, queued stop no-op injection, round-trip delivery, and bundled skills metadata.

package/node_modules/@llblab/pi-grow-loop/README.md

@@ -0,0 +1,216 @@
+# pi-grow-loop
+
+![pi-grow-loop banner](https://raw.githubusercontent.com/llblab/pi-grow-loop/main/banner.jpg)
+
+`pi-grow-loop` is a semantic loop-engineering layer for Pi. It pairs the portable `while-true` worker protocol with a visible, interruptible scheduler to advance concrete work from project state or an explicit scoped outcome.
+
+The agent owns scope, evidence, priority, safety, and the decision to continue or stop; the runtime only schedules the next turn, while the operator retains normal conversational control. There is no hidden queue, fixed workflow, regex latch, or runtime state machine replacing agent judgment.
+
+## Quick Start
+
+Requires Pi `0.80.4` or newer for the settled-agent lifecycle event.
+
+Install from npm:
+
+```bash
+pi install npm:@llblab/pi-grow-loop
+```
+
+Or install from git:
+
+```bash
+pi install git:github.com/llblab/pi-grow-loop
+```
+
+Then focus Pi on trustworthy open work or provide a concrete multi-slice outcome and ask for continuation:
+
+```text
+grow loop
+```
+
+The agent should run one bounded `while-true` slice, report what changed or what was proven, and schedule another visible turn only if useful work remains.
+
+## When To Use It
+
+Use `pi-grow-loop` when the execution shape has all of these properties:
+
+- A concrete delegated scope or outcome.
+- A truthful canonical work surface that exists or can be bootstrapped from that outcome.
+- Multiple independently useful bounded slices with separate validation evidence.
+- Operator-visible continuation boundaries that provide useful opportunities to redirect or stop.
+- Safe actionable or preparable work remains after the current slice.
+
+The vocabulary, apparent size, and number of internal steps do not select the protocol. Decomposing an explicit requested outcome into a canonical backlog is not inventing work. Harvesting unrelated improvements merely to keep the loop alive is. If neither an existing surface nor a concrete outcome exists, the correct result is a stop proof or a request for the missing scope.
+
+## Compared With `/goal`
+
+`/goal` is the nearest mental model, but it solves a different problem. It creates a goal-shaped session around a declared outcome. `pi-grow-loop` selects an iterative execution shape and keeps its source of truth in a canonical open-work surface, whether discovered or bootstrapped from an explicit scoped outcome.
+
+| Dimension | `/goal` | `pi-grow-loop` |
+| --- | --- | --- |
+| Starting point | A declared objective | Existing project evidence or an explicit scoped outcome |
+| Planning mode | Decompose a goal-shaped session | Bootstrap or reconcile a canonical open-work surface |
+| Agent question | "How do we reach this outcome?" | "What is the next safe useful slice?" |
+| Runtime shape | Goal/session frame | Normal visible Pi turns |
+| Continuation | Driven by the goal session | Re-decided after each `while-true` checkpoint |
+| Work shape | Goal-organized initiative | Independently useful slices with visible validation boundaries |
+
+The distinction is session shape and source of truth: `/goal` owns a goal object; `pi-grow-loop` has no goal object and advances a canonical backlog one visible checkpoint at a time. An explicit outcome may seed that backlog, but only requested work belongs there.
+
+## Execution Model
+
+```text
+lock the user-focus scope
+  → checkpoint current reality
+  → reconcile the open-work surface
+  → assemble one bounded validation cohort
+  → execute tasks with focused checks
+  → validate the cohort proportionally
+  → hand off evidence and remaining state
+  → decide once: stop, or schedule one next visible turn
+```
+
+The selected scope stays stable across iterations unless the operator redirects it or verified reality proves that a different surface governs the same work. The runtime does not decide what matters; the skills do.
+
+### Declared Work Surfaces
+
+Relevant project-local delivery instructions may explicitly declare a feature's source of open work:
+
+```markdown
+Canonical open work: ./BACKLOG.md
+```
+
+Relative paths resolve from the declaring instruction. `while-true` gives a trustworthy declaration precedence over filename-based discovery without knowing which skill or methodology produced it. It does not mine procedural skill prose for tasks or scan unrelated skills merely to find available work.
+
+Resolution remains scope-locked: external references must recover precise current work, scope-mismatched declarations are ignored, root plans may index a feature-local surface without duplicating tasks, and stale or missing owners must be repaired from evidence rather than replaced with unrelated work. Competing relevant declarations stop for the smallest ownership decision when project evidence cannot select one.
+
+A project-local knowledge or support skill without a trustworthy declaration remains context, never a task source. `while-true` does not infer work from prose, examples, insights, historical delivery sections, or lifecycle language. The same skill may later declare new canonical open work when its feature evolves; discovery follows current evidence rather than producer identity.
+
+The plain-text declaration remains intentionally sufficient: real composition runs require scope and ownership validation, not a producer registry, lifecycle marker, or structured metadata layer. Additional syntax should appear only after reproducible ambiguity proves this contract insufficient.
+
+## The Three Pieces
+
+- `while-true` skill — the portable worker protocol. It assesses reality, reconciles backlog/plan state, and executes one bounded validation cohort. By default it batches several independent low-coupling tasks, falsifies each task cheaply, runs expensive shared validation once, and hands off evidence. Coupled, ordered, large, high-risk, or diagnostically ambiguous work runs as a single-task cohort. It knows nothing about Grow Loop or its runtime.
+- `grow-loop` skill — the continuation meta-protocol. It locks the relevant scope, interprets recent user intent, consumes the worker handoff, and decides exactly once whether another iteration should run.
+- `grow_loop` tool — the scheduler. It waits for an optional `after_seconds` delay (default `3`), shows status, and sends the next visible Pi prompt.
+
+Protocol selection happens before worker execution:
+
+```text
+explicit while-true → one portable worker pass → handoff to caller
+explicit grow-loop  → Grow Loop → while-true → decide → grow_loop or stop
+one coherent change → ordinary one-shot execution
+multi-slice outcome → Grow Loop → bootstrap backlog → bounded iterations
+runtime continuation prompt: while true | grow loop
+```
+
+Explicit protocol names are exact overrides: asking for `while-true` never silently expands into Grow Loop. When no protocol is named, automatic routing follows execution topology: one coherent change remains one-shot, while a concrete outcome with independently useful validated slices may select Grow Loop. Concrete tasks may illustrate either shape, but their verbs and categories never act as activation predicates.
+
+### Choosing The Execution Shape
+
+Multiple internal steps do not by themselves require Grow Loop. Use ordinary one-shot execution when those steps form one coherent change that can be validated and reported at one natural boundary. Use Grow Loop when a concrete delegated outcome benefits from multiple independently useful slices, each with its own validation evidence and a visible opportunity for the operator to redirect or stop. This is semantic judgment, not a keyword classifier or consent ceremony.
+
+## Protocol Contract
+
+Each visible iteration has one checkpoint boundary:
+
+1. `while-true` executes at most one bounded validation cohort. The cohort batches independent low-coupling tasks by default and falls back to one task when ordering, overlap, size, risk, or diagnosis requires it.
+2. Each cohort task gets a cheap focused falsifier before the next task; expensive type, build, integration, context, or live validation runs once after the retained cohort.
+3. The worker hands off the locked scope, cohort membership, plan transitions, per-task evidence, shared validation result, highest-value remaining item, actionability, blocker, and exact unblocker.
+4. `grow-loop` gives latest operator intent precedence over repository availability and compares the checkpoint with the previous iteration to reject repeated no-ops.
+5. If continuation remains safe and valuable, it calls `grow_loop` exactly once and ends the turn. Otherwise it does not call the tool and returns a stop proof.
+
+Bounded does not mean one file, command, internal step, backlog item, or tiny edit. It means one validation cohort whose task-level failures remain attributable, followed by shared validation and an operator-visible continuation boundary.
+
+A standalone `while-true` invocation ends at that handoff. Only a previously selected `grow-loop` meta-protocol may consume it as a continuation checkpoint and schedule another turn.
+
+## Runtime Behavior
+
+`grow_loop` is intentionally narrow:
+
+- Waits until Pi is idle and no user messages are pending.
+- Shows an interrupt countdown configured by the optional `after_seconds` argument from 3 through 3600, defaulting to 3 seconds. The minimum preserves a window for the operator to redirect the agent before continuation.
+- Can act as a continuation timer when the agent must wait for asynchronous work before checking again.
+- Sends the compact prompt `while true | grow loop` only if Pi is still idle.
+- If Pi becomes busy during the countdown, returns to deferred waiting instead of queueing a hidden follow-up.
+- Shows loop status only while it is actively carrying the rhythm.
+- Clears pending scheduling and hides loop status when any user prompt arrives, including prompts injected by another extension; only the scheduler's exact expected continuation prompt preserves the rhythm.
+
+For the normal interrupt window, call `grow_loop` without arguments. To check asynchronous work again after one minute, call it with `{ "after_seconds": 60 }`. The one-hour maximum keeps the tool focused on bounded asynchronous checks rather than long-term scheduling. Agents should estimate the next useful check from the expected remaining duration, reassess after every wake, and shorten later waits as completion approaches instead of repeating one interval mechanically.
+
+The tool never blocks future calls. Whether to continue belongs to the agent and skills, not to a runtime latch, regex, slash command, or hidden state machine.
+
+## Runtime Statuses
+
+- No status — no active loop rhythm, or the operator took the turn.
+- `loop ∞N` warning — the next loop prompt is armed and waiting for idle/no pending messages.
+- `loop Ns` countdown — Pi is idle and the configured delay is running.
+- `loop ∞N` dim — the compact loop prompt was sent for this iteration.
+
+`N` is monotonic within the current extension instance. Active status clears when the scheduled agent run fully settles without arming a successor, so automatic retry or compaction recovery does not produce a false idle state. There is no `loop stopped` or `loop paused` status; absence of loop status means the runtime rhythm is no longer active.
+
+## Interruption Model
+
+Any user prompt except the scheduler's exact expected continuation prompt exits the active runtime rhythm. This includes operator input delivered through Telegram, RPC bridges, or other extensions:
+
+```text
+Runtime: loop 3.0s or loop ∞2
+User: What changed?
+Runtime: hides loop status and cancels pending scheduling
+Agent: answers, stops, changes direction, or later continues based on intent and context
+```
+
+The runtime only clears the rhythm. It does not decide whether the user meant stop, answer first, change direction, or continue afterward. That interpretation belongs to `grow-loop`, and operator intent outranks remaining backlog availability.
+
+## Stop Conditions
+
+Grow Loop should stop and not call `grow_loop` when:
+
+- No high-value actionable or preparable work remains.
+- Work is complete.
+- Remaining work is gated and preparation is complete.
+- The checkpoint signature repeats.
+- The next step is unsafe, destructive, approval-gated, credential-gated, account-affecting, or externally blocked.
+- Validation regresses enough to require a strategy change.
+- Recent user intent means stop, answer, change direction, or wait.
+
+Stopping with exact evidence is progress.
+
+## What It Does Not Do
+
+- No background worker.
+- No hidden task queue.
+- No slash-command control surface.
+- No cycle budget or goal-session state.
+- No Escape/abort ownership; Escape remains baseline Pi behavior for active agent turns.
+- No replacement for approval on destructive, publishing, credential, account, or external actions.
+
+## Operator Examples
+
+Normal continuation:
+
+```text
+User: grow loop
+Agent: closes one backlog slice, validates, reports evidence, calls grow_loop
+Runtime: loop ∞1 → loop 3.0s → while true | grow loop
+```
+
+Terminal stop proof:
+
+```text
+Agent: closed release checklist, npm run validate passed, remaining npm publish is approval-gated; restart with "grow loop" after publish approval is ready.
+```
+
+## Package Shape
+
+The package uses Pi's source-extension shape: package metadata points directly at `index.ts` and the bundled `skills/` directory. There is no build step or generated `dist/` tree.
+
+Repository files:
+
+- [`index.ts`](index.ts) — optionally delayed `grow_loop` tool and status scheduler.
+- [`skills/while-true/SKILL.md`](skills/while-true/SKILL.md) — bounded worker-loop protocol with neutral project-local work-surface discovery.
+- [`skills/grow-loop/SKILL.md`](skills/grow-loop/SKILL.md) — continuation meta-protocol.
+- [`AGENTS.md`](AGENTS.md) — durable project protocol and routing invariants.
+- [`BACKLOG.md`](BACKLOG.md) — canonical open work and next growth slices.
+- [`CHANGELOG.md`](CHANGELOG.md) — completed delivery history and package-version release notes.
+- [`tsconfig.json`](tsconfig.json) — maintainer-side strict no-emit validation for extension and test sources; it is not required by the installed runtime package.