# Project Context

## Meta-Protocol Principles

- `Pi Baseline`: Require Pi ≥1.0.0 in peer metadata, dependency locks and source/packaged compatibility tests; preserve settled-event scheduling and operator interruption semantics.
- `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. Skill routing, scope retention, and no-op decisions are agent instructions, not runtime-enforced guarantees.
- `Growth And Drying`: Grow useful capability and dry accidental carrying cost: complementary pressures that sharpen the project's essence. Neither feature accumulation nor fewer lines is the objective; preserve obligations and require evidenced value. Do not add automatic alternation, quotas, or a second scheduler.
- `Evidence Boundary`: Text-contract tests prove that instructions are present; loader tests prove discoverability; runtime tests prove exercised scheduling behavior. None alone proves model adherence across live skill-loop turns. Keep known implementation gaps in `BACKLOG.md`, not hidden behind normative guarantees.
- `Scope-First Activation`: Grow Loop locks the concrete user-focus scope and selected skill. While True alone resolves and validates its canonical open-work surface; other skills retain their own evidence and need no backlog merely to loop. Grow Loop consumes the result and owns continuation, not domain execution.
- `Lexical Intent Precedence`: An explicitly named protocol selects its exact behavior. A standalone skill request runs one bounded pass; `<skill> loop` selects Grow Loop with that skill. `grow loop` defaults to While True for growth; `active drying loop` and `drying loop` select Active Drying for lower carrying cost with preserved capability. `while true | grow loop` resumes the locked skill from context, never silently resetting it. Quoted examples and informational mentions do not request execution.
- `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; the selected skill performs one bounded pass. The default `while-true` worker advances project growth, while `active-drying` reduces carrying cost without weakening capability or guarantees.

## Boundaries

- `grow-loop` skill owns continuation semantics: continue or stop.
- Routing selects the protocol and skill before execution: explicit skill-loop intent overrides inference; otherwise concrete iterative tasks may select Grow Loop when multiple validated slices and visible checkpoints are useful. Preserve the selected skill across checkpoints and stop if it cannot be recovered. Growth and drying are complementary, not an automatic alternating cycle; no loop overrides a skill's permissions or human-input gates.
- `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 `grow-loop ∞N` with the iteration number in warning color, countdown as `grow-loop Ns`, and active iterations as `grow-loop ∞N` with the iteration number dimmed; `N` is monotonic within the extension instance and advances once per turn that arms a deferred iteration; repeated tool calls in that turn only replace the delay while retaining the same iteration number.
- 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 `grow-loop ∞N` only while the next iteration is deferred until idle, `grow-loop Ns` only during the configured countdown, and dim `grow-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.
- Telegram status mirror: when `pi-telegram` is installed, the optional fail-open status-line adapter mirrors the same identity (`Grow Loop: ∞N`) and hides with it. It reads the same runtime state, registers once per process lifetime, disposes on session shutdown, and a missing or unready transport changes nothing.
- 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                       source-checkout composition root
dist/pi-grow-loop/index.js     packaged compiled entrypoint
dist/skills                    packaged Skill root
skills/grow-loop/SKILL.md      meta-loop protocol
skills/while-true/SKILL.md     default growth worker
skills/active-drying/SKILL.md  portable carrying-cost refinement lens
README.md                      human entrypoint
BACKLOG.md                     open work
CHANGELOG.md                   completed delivery history
```

## Evolution Rules

1. Keep one narrow scheduling tool; optional delay does not make it a domain executor.
2. Let the skills dogfood themselves on this extension without inventing work to sustain a loop.
3. Add state only if real runs prove it is necessary.
4. Preserve the separation: continuation in Grow Loop, domain execution in the selected skill, triggering in the tool.
5. Preserve exact named entrypoints while allowing natural multi-slice tasks to bootstrap a truthful backlog and select Grow Loop automatically.

## Style

- Manifest-loaded packages expose bundled Skills only through `pi.skills`, preserving package filters and package-owned provenance. Only a checkout auto-discovered directly below a user or project Pi `extensions/` root may contribute its source Skill root through `resources_discover`; compiled-vs-source filename shape does not determine ownership.
- Keep `dist/` synchronized and committed after source changes because Pi git-package installation does not run the npm `prepack` lifecycle. Run `npm run build` to atomically replace it; validation uses `build:check` to reject drift without rewriting the working tree, while npm publication rebuilds the same tree.
- Prefer small, inspectable TypeScript over framework or actor dependencies.
- Use concise operator copy.
- Keep prompt contracts explicit and bounded.
- Record meaningful completed outcomes in `CHANGELOG.md`; keep `BACKLOG.md` clean and limited to unresolved work.