@hank-warren/pi-loop 1.1.0 → 1.2.0

package/CHANGELOG.md

@@ -1,5 +1,33 @@
 # @hank-warren/pi-loop
 
+## 1.2.0
+
+### Minor Changes
+
+- 1035138: Ship the craft documents by injected path instead of as skills.
+
+  The `pi-loop` and `pi-plan-mode` skills are gone. Their bodies now ship as
+  `docs/loop-craft.md` and `docs/plan-craft.md`, and the mode prompts inject the
+  file's absolute path (resolved from the installed package) at the moments the
+  guidance matters: while a loop is being drafted or completed, and while Plan
+  Mode is active. A skill's description line sits in every system prompt of every
+  session with the package loaded; across ~220 sessions after these two shipped,
+  every read of either file was triggered by the mode's own prompt and never by
+  the description, so the line was a tax on the ~95% of sessions that never
+  entered the mode. Same document, read at the same moments, at zero cost outside
+  them. Hosts that referenced the skills by name in settings should drop those
+  entries.
+
+- 1035138: Deprecated in favour of `@hank-warren/pi-orchestrator`.
+
+  pi-loop is a pacemaker for one session that cannot be trusted to pace itself. The
+  `pi-orchestrator` skill is a supervising pi session watching real pi sessions in
+  Herdr panes — reading their state, answering their prompts within policy,
+  steering, and verifying their claims — which does by judgment what the loop
+  engine did by pacing and gates. This package stays published and continues to
+  work; it is no longer loaded by the git install of the `pi-extensions`
+  repository and receives no new features. The README opens with the notice.
+
 ## 1.1.0
 
 ### Minor Changes

package/README.md

@@ -1,5 +1,7 @@
 # pi-loop — long-running work for the Pi coding agent
 
+> **Deprecated.** pi-loop is no longer loaded by the git install of this repository and receives no new features. Its role — keeping autonomous work moving and gating completion on evidence — has moved to the [`pi-orchestrator`](../pi-orchestrator) skill package: a supervising pi session watching real pi sessions in Herdr panes, reading their state, answering their prompts within policy, steering them, and verifying their claims. A loop is a pacemaker for one session that cannot be trusted to pace itself; a supervisor with fresh context does that by judgment, and can see, attach to, and redirect each child. The package stays on npm and continues to install with `pi install npm:@hank-warren/pi-loop` for anyone who prefers it.
+
 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** that owns its own work: it carries an objective, completion criteria and ground rules, and ends when the model calls `loop_complete` with cited evidence, its expiry arrives, a cap you set is reached, or you stop it. Every loop is planned with you and started from an approval card. **No other extension is required.**
@@ -205,13 +207,13 @@ 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 loop-craft doc
 
-The package is a hybrid: it ships the extension **and** a `pi-loop` skill (`skills/pi-loop/SKILL.md`), which carries the judgment the engine cannot encode — how an objective becomes falsifiable criteria, what the evidence gate accepts as a citation, when to declare a `loop_wait` instead of polling, what `PROGRESS.md` is worth, and when the work belongs in no loop at all.
+The engine cannot encode the judgment that decides whether a loop is worth running — how an objective becomes falsifiable criteria, what the evidence gate accepts as a citation, when to declare a `loop_wait` instead of polling, what `PROGRESS.md` is worth, and when the work belongs in no loop at all. That lives in [`docs/loop-craft.md`](docs/loop-craft.md), which ships with the package.
 
-It is **loaded on demand**: the planning hint and `loop_complete`'s prompt guidelines point 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.
+It is **loaded on demand**: the planning hint and `loop_complete`'s prompt guidelines name it by absolute path (resolved from the installed package, so it works under any install layout) and the model reads it when it reaches those moments. 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 it.
 
-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.
+It used to be a skill. A skill's description line is in every system prompt, which buys exactly one thing an injected pointer cannot: the model proposing a loop unprompted. Across ~220 sessions after it shipped, every read of the file was triggered by the planning hint or the completion tool, never by the description, and the model never suggested `/loop` on its own — so the line was a tax on every session that never ran a loop (about 95% of them) that bought nothing. A hard path injected only while a loop is being drafted or completed is the same document at zero cost outside those moments.
 
 ## Install
 
@@ -221,6 +223,10 @@ pi install npm:@hank-warren/pi-loop
 
 **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.
 
+## Changelog
+
+See [CHANGELOG.md](CHANGELOG.md) for release history.
+
 ## License
 
 MIT

package/{skills/pi-loop/SKILL.md → docs/loop-craft.md}

@@ -1,9 +1,3 @@
----
-name: pi-loop
-description: Draft loop objectives that become falsifiable criteria, set cadence and ground rules, and complete a loop with evidence the gate accepts. Use while drafting a loop in /loop planning, before calling loop_propose, 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, compaction, and the ledger. It cannot handle the three things that decide whether a loop is worth running: **what end state the objective names**, **what constraints bound the work**, and **what evidence proves it is done**. That is this file.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hank-warren/pi-loop",
-  "version": "1.1.0",
+  "version": "1.2.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,15 +29,12 @@
   "pi": {
     "extensions": [
       "./index.ts"
-    ],
-    "skills": [
-      "./skills/pi-loop"
     ]
   },
   "files": [
     "index.ts",
     "src",
-    "skills",
+    "docs/loop-craft.md",
     "README.md",
     "LICENSE",
     "CHANGELOG.md"

package/src/command.ts

@@ -17,7 +17,7 @@
  * of having exactly one way in, and the menu is one keystroke away.
  */
 
-export type LoopCommand =
+type LoopCommand =
 	/** Bare `/loop`: open whichever menu the current state calls for. */
 	| { kind: "menu" }
 	/** `/loop <text>`: enter planning and send the text as the first message. */

package/src/complete-tool.ts

@@ -24,6 +24,7 @@
 
 import { defineTool, type ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { Type } from "typebox";
+import { LOOP_CRAFT_DOC } from "./docs.js";
 import type { LoopController } from "./loop.js";
 import type { LoopCriterion } from "./ledger.js";
 
@@ -92,7 +93,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.",
+				`Before your first loop_complete this session, read ${LOOP_CRAFT_DOC}: it describes what the evidence gate accepts as a citation and what it refuses.`,
 			],
 			parameters: Type.Object({
 				loop_id: Type.String({

package/src/decide.ts

@@ -37,9 +37,9 @@ function isWaiting(loop: LoopState, now: number): boolean {
  * An expiring loop gets one last turn to write its state into the ledger
  * before it stops; a loop already spending that turn stops immediately.
  */
-export type ExpiryReason = "loop-expired" | "expiry-final-wake";
+type ExpiryReason = "loop-expired" | "expiry-final-wake";
 
-export type SkipReason =
+type SkipReason =
 	| "plan-mode-active"
 	| "agent-busy"
 	| "compaction-in-flight"

package/src/docs.ts

@@ -0,0 +1,21 @@
+import { join } from "node:path";
+
+/**
+ * The loop-craft document: the judgment the engine cannot encode — how an
+ * objective becomes falsifiable criteria, what the evidence gate accepts as a
+ * citation, when to `loop_wait`, and when work belongs in no loop at all.
+ *
+ * It used to ship as a skill. A skill buys one thing an injected pointer
+ * cannot: a description line in every system prompt, so the model could
+ * propose a loop unprompted. Across ~220 sessions after it shipped, every read
+ * of the file was triggered by the planning hint or `loop_complete`'s
+ * guidelines — never by the description — and the model never suggested
+ * `/loop` on its own. So the line was a tax on every session that never ran a
+ * loop (~95% of them) and bought nothing. An absolute path, injected only
+ * while a loop is being drafted or completed, is the same document at zero
+ * cost outside those moments, and a hard path beats "if it is available".
+ *
+ * The path is resolved from this module's own location so it survives every
+ * install layout (git, npm, workspace symlink, `npm link`).
+ */
+export const LOOP_CRAFT_DOC = join(import.meta.dirname, "..", "docs", "loop-craft.md");

package/src/errors.ts

@@ -19,7 +19,7 @@ import {
 	type Usage,
 } from "@earendil-works/pi-ai";
 
-export type LoopInterruption =
+type LoopInterruption =
 	/** The turn finished normally. */
 	| "none"
 	/** The user (or another extension) aborted the turn. */

package/src/fresh-launch.ts

@@ -27,14 +27,14 @@ import { LOOP_STATE_ENTRY_TYPE } from "./state.js";
 type NewSessionOptions = Exclude<Parameters<ExtensionCommandContext["newSession"]>[0], undefined>;
 type SessionManagerLike = Parameters<NonNullable<NewSessionOptions["setup"]>>[0];
 
-export type FreshLoopResult =
+type FreshLoopResult =
 	| { kind: "started" }
 	| { kind: "cancelled" }
 	/** The session exists and holds the loop, but it could not be kicked off. */
 	| { kind: "partial"; detail: string }
 	| { kind: "rejected"; detail: string };
 
-export interface FreshLoopRequest {
+interface FreshLoopRequest {
 	built: BuiltLoop;
 	/** Write the ledger for `built` before the handoff; returns a failure detail. */
 	prepareLedger(): string | undefined;

package/src/interval.ts

@@ -27,7 +27,7 @@ export function parseDuration(token: string): number | undefined {
 	return ms > MAX_INTERVAL_MS ? undefined : ms;
 }
 
-export interface ParsedInterval {
+interface ParsedInterval {
 	requestedMs: number;
 	/** Clamped to MIN_INTERVAL_MS; the caller must echo the effective value. */
 	effectiveMs: number;

package/src/ledger.ts

@@ -26,13 +26,13 @@ import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 import { getAgentDir } from "@earendil-works/pi-coding-agent";
 
-export const LEDGER_DIR_NAME = "loop";
+const LEDGER_DIR_NAME = "loop";
 export const CRITERIA_FILE = "criteria.json";
 export const PROGRESS_FILE = "PROGRESS.md";
 
 /** Cap on a loop's criteria: an objective is a paragraph, not a backlog. */
-export const MAX_CRITERIA = 12;
-export const MAX_DESCRIPTION_LENGTH = 500;
+const MAX_CRITERIA = 12;
+const MAX_DESCRIPTION_LENGTH = 500;
 
 export interface LoopCriterion {
 	id: string;
@@ -75,7 +75,7 @@ export const MAX_EVIDENCE_LENGTH = 4000;
 /** The template's placeholders, replaced rather than appended to on first write. */
 const PLACEHOLDERS = new Set(["not started.", "- (nothing yet)"]);
 
-export function loopLedgerDir(loopId: string, agentDir = getAgentDir()): string {
+function loopLedgerDir(loopId: string, agentDir = getAgentDir()): string {
 	return join(agentDir, LEDGER_DIR_NAME, loopId);
 }
 
@@ -234,7 +234,7 @@ export function createLedger(
 	}
 }
 
-export function progressTemplate(objective: string): string {
+function progressTemplate(objective: string): string {
 	return [
 		"# Loop progress ledger",
 		"",
@@ -320,7 +320,7 @@ function headingText(line: string | undefined): string | undefined {
 	return match ? match[1].toLowerCase() : undefined;
 }
 
-export interface MarkCriterionResult {
+interface MarkCriterionResult {
 	ok: boolean;
 	message: string;
 	criteria?: LoopCriterion[];

package/src/loop-action-menus.ts

@@ -18,7 +18,7 @@ import type { ActionsScreen } from "@narumitw/pi-tui-kit";
 import { formatDuration } from "./interval.js";
 import type { LoopProposal } from "./planning.js";
 
-export type LoopApprovalAction =
+type LoopApprovalAction =
 	| "start-here"
 	| "start-fresh"
 	| "change-cadence"
@@ -27,7 +27,7 @@ export type LoopApprovalAction =
 
 type Screen = "approval";
 
-export interface LoopApprovalMenuOptions {
+interface LoopApprovalMenuOptions {
 	proposal: LoopProposal;
 	signal?: AbortSignal;
 	isCurrent?(): boolean;

package/src/loop-env.ts

@@ -25,8 +25,8 @@
 
 import type { LoopState } from "./state.js";
 
-export const LOOP_ACTIVE_ENV = "PI_LOOP_ACTIVE";
-export const LOOP_ID_ENV = "PI_LOOP_ID";
+const LOOP_ACTIVE_ENV = "PI_LOOP_ACTIVE";
+const LOOP_ID_ENV = "PI_LOOP_ID";
 
 /**
  * Publish (or withdraw) the loop-active signal for `loop`.

package/src/loop-launch-menu.ts

@@ -15,9 +15,9 @@ import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
 import type { ActionsScreen, DetailScreen } from "@narumitw/pi-tui-kit";
 import { defineMenu, runMenu } from "@narumitw/pi-tui-kit";
 
-export type LoopLaunchScreen = "main" | "how";
-export type LoopLaunchAction = "start-planning" | "settings";
-export type LoopPlanningAction = "request-proposal" | "cancel" | "settings";
+type LoopLaunchScreen = "main" | "how";
+type LoopLaunchAction = "start-planning" | "settings";
+type LoopPlanningAction = "request-proposal" | "cancel" | "settings";
 
 /**
  * What a loop actually is, for someone who has never run one.
@@ -95,7 +95,7 @@ export function loopPlanningScreen(): ActionsScreen<LoopLaunchScreen, LoopPlanni
 	};
 }
 
-export interface LoopLaunchMenuOptions {
+interface LoopLaunchMenuOptions {
 	signal?: AbortSignal;
 	isCurrent?(): boolean;
 	startPlanning(): void;
@@ -120,7 +120,7 @@ export async function showLoopLaunchMenu(ctx: ExtensionContext, options: LoopLau
 	return runMenu(ctx, menu, { getState: () => undefined, ...lifecycle(options) });
 }
 
-export interface LoopPlanningMenuOptions {
+interface LoopPlanningMenuOptions {
 	signal?: AbortSignal;
 	isCurrent?(): boolean;
 	requestProposal(): void;

package/src/loop-manager-menu.ts

@@ -18,8 +18,8 @@ import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
 import type { ActionsScreen, DetailScreen, InputScreen } from "@narumitw/pi-tui-kit";
 import { defineMenu, runMenu } from "@narumitw/pi-tui-kit";
 
-export type LoopManagerScreen = "main" | "status" | "focus" | "cadence";
-export type LoopManagerAction =
+type LoopManagerScreen = "main" | "status" | "focus" | "cadence";
+type LoopManagerAction =
 	| "pause"
 	| "resume"
 	| "stop"
@@ -128,7 +128,7 @@ export function loopCadenceScreen(view: LoopManagerView): InputScreen<LoopManage
 	};
 }
 
-export interface LoopManagerMenuOptions {
+interface LoopManagerMenuOptions {
 	getView(): LoopManagerView | undefined;
 	signal?: AbortSignal;
 	isCurrent?(): boolean;

package/src/loop.ts

@@ -99,7 +99,7 @@ import {
 	updateLoopWidget,
 } from "./widget.js";
 
-export const LOOP_STATUS_KEY = "loop";
+const LOOP_STATUS_KEY = "loop";
 
 /** Custom message type of the kickoff anchor. */
 export const LOOP_ANCHOR_MESSAGE_TYPE = "loop-objective";
@@ -109,7 +109,7 @@ export const LOOP_ANCHOR_MESSAGE_TYPE = "loop-objective";
  * capped here. Deterministic and small: the point is to stop re-waking a loop
  * that has nothing to do, not to invent an adaptive scheduler.
  */
-export const MAX_FALLBACK_BACKOFF = 4;
+const MAX_FALLBACK_BACKOFF = 4;
 
 /**
  * How long a single run may stay open before the widget calls it blocked.
@@ -129,10 +129,10 @@ export const STALL_ATTENTION_MS = 900_000;
  * is not proof a turn will start. The ordinary dead-delivery counter cannot
  * catch this one, because after expiry there is no next delivery to count.
  */
-export const EXPIRY_TURN_GRACE_MS = 60_000;
+const EXPIRY_TURN_GRACE_MS = 60_000;
 
 /** Consecutive loop deliveries that produce no run before the loop pauses. */
-export const MAX_DEAD_DELIVERIES = 3;
+const MAX_DEAD_DELIVERIES = 3;
 
 /** Why the loop caused the run that is currently in flight. */
 type RunOrigin = "continuation" | "fallback";
@@ -145,7 +145,7 @@ type RunOrigin = "continuation" | "fallback";
  * actions share that path — one installs the loop here, the other hands it to
  * a fresh session — so the decision is returned and each caller renders it.
  */
-export type LoopStartResult = { ok: true; loop: LoopState } | { ok: false; message: string };
+type LoopStartResult = { ok: true; loop: LoopState } | { ok: false; message: string };
 
 /**
  * A loop that exists but is not running anywhere: everything `installLoop`
@@ -160,7 +160,7 @@ export interface BuiltLoop {
 	requestedMs: number;
 }
 
-export type LoopBuildResult = { ok: true; built: BuiltLoop } | { ok: false; message: string };
+type LoopBuildResult = { ok: true; built: BuiltLoop } | { ok: false; message: string };
 
 interface ContinuationIntent {
 	loopId: string;

package/src/manager.ts

@@ -160,7 +160,7 @@ function setCadence(
 	return true;
 }
 
-export async function showLoopSettings(
+async function showLoopSettings(
 	controller: LoopController,
 	ctx: ExtensionCommandContext,
 ): Promise<void> {

package/src/planning.ts

@@ -17,6 +17,7 @@
  * gone: both authored an acceptance gate in one line, unreviewed.
  */
 
+import { LOOP_CRAFT_DOC } from "./docs.js";
 import { deriveCriteria, type LoopCriterion } from "./ledger.js";
 import { formatDuration } from "./interval.js";
 
@@ -132,7 +133,7 @@ export function renderProposalCard(proposal: LoopProposal): string[] {
 export const LOOP_PLANNING_HINT = [
 	"<system-reminder>",
 	"The user opened loop planning. You are drafting a loop with them; no loop is running and none starts until they approve one on the card.",
-	"Read the pi-loop skill before drafting if it is available: it carries the objective, criteria, cadence and evidence craft in depth.",
+	`Before drafting, read ${LOOP_CRAFT_DOC}: it carries the objective, criteria, cadence and evidence craft in depth.`,
 	"Cover three things in the conversation, then call loop_propose:",
 	"- The objective, written as an acceptance test. One requirement per bullet; a conjunction inside a sentence does not split, so 'fix the flaky test and update the docs' becomes one criterion whose evidence must cover both halves. Name the check in the requirement itself ('…, verified by npm test passing'). The two questions that fix most objectives: how will we know it is done, and what command proves it?",
 	"- The cadence: how long the loop may run before it expires, and the fallback heartbeat for a session that goes quiet. The loop advances whenever the session settles, so the heartbeat only matters when it is waiting on something.",

package/src/progress-tool.ts

@@ -33,7 +33,7 @@ import {
 } from "./ledger.js";
 import type { LoopController } from "./loop.js";
 
-export const LOOP_PROGRESS_TOOL = "loop_progress";
+const LOOP_PROGRESS_TOOL = "loop_progress";
 
 export function registerLoopProgressTool(pi: ExtensionAPI, controller: LoopController) {
 	pi.registerTool(

package/src/propose-tool.ts

@@ -18,7 +18,7 @@ import { formatDuration, MAX_INTERVAL_MS, parseDuration } from "./interval.js";
 import type { LoopController } from "./loop.js";
 import { MAX_GROUND_RULE_LENGTH, MAX_GROUND_RULES } from "./planning.js";
 
-export const LOOP_PROPOSE_TOOL = "loop_propose";
+const LOOP_PROPOSE_TOOL = "loop_propose";
 
 export function registerLoopProposeTool(
 	pi: ExtensionAPI,

package/src/safety.ts

@@ -20,7 +20,7 @@
 
 import { createHash } from "node:crypto";
 
-export interface NoProgressState {
+interface NoProgressState {
 	toolFreeRepeatCount: number;
 	lastFingerprint?: string;
 }

package/src/settings.ts

@@ -11,9 +11,9 @@ import { basename, dirname, join } from "node:path";
 import { getAgentDir } from "@earendil-works/pi-coding-agent";
 import { parseDuration } from "./interval.js";
 
-export const LOOP_SETTINGS_FILE = "pi-loop.json";
+const LOOP_SETTINGS_FILE = "pi-loop.json";
 
-export interface LoopCompactionSettings {
+interface LoopCompactionSettings {
 	enabled: boolean;
 	/** Fraction of the context window that triggers a proactive compact. */
 	threshold: number;
@@ -82,7 +82,7 @@ export const DEFAULT_LOOP_SETTINGS: LoopSettings = {
 	},
 };
 
-export type LoopSettingsLoadResult =
+type LoopSettingsLoadResult =
 	| { kind: "missing"; settings: LoopSettings }
 	| { kind: "invalid"; reason: string; settings: LoopSettings }
 	| { kind: "loaded"; settings: LoopSettings };

package/src/state.ts

@@ -11,8 +11,8 @@ export const PLAN_MODE_STATE_ENTRY_TYPE = "plan-mode-state";
 
 import { type LoopWait, normalizeLoopWait } from "./wait.js";
 
-export const LOOP_STATUSES = ["active", "paused", "stopped"] as const;
-export type LoopStatus = (typeof LOOP_STATUSES)[number];
+const LOOP_STATUSES = ["active", "paused", "stopped"] as const;
+type LoopStatus = (typeof LOOP_STATUSES)[number];
 
 export interface LoopState {
 	id: string;

package/src/widget.ts

@@ -45,13 +45,13 @@ interface WidgetTheme {
 type WidgetHost = { setWidget?: unknown };
 
 /** Criteria progress, absent when the loop has no readable ledger. */
-export interface CriteriaProgress {
+interface CriteriaProgress {
 	met: number;
 	total: number;
 }
 
 /** The loop is being drafted with the user and has not started. */
-export interface LoopPlanningView {
+interface LoopPlanningView {
 	kind: "planning";
 	/** Criteria in the proposed draft, once one has been put up for approval. */
 	proposedCriteria?: number;