@hank-warren/pi-plan-mode 1.5.0 → 1.7.0

package/CHANGELOG.md

@@ -1,5 +1,45 @@
 # @hank-warren/pi-plan-mode
 
+## 1.7.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.
+
+### Patch Changes
+
+- 1035138: Report a waiting question to Herdr as `blocked`.
+
+  `ask_user_question` and Plan Mode's `plan_mode_question` now emit the same
+  `herdr:blocked` event pi-auto-permissions emits for an approval prompt, labelled
+  `question` / `plan question` and cleared in a `finally`, so Herdr's pi
+  integration shows a session waiting on a question as `blocked` rather than
+  `working`. A supervising agent in another pane can wait on that state and answer
+  the dialog. No-op outside Herdr.
+
+## 1.6.0
+
+### Minor Changes
+
+- d0c46a5: Drop two legacy paths that were past their delete-by date:
+
+  - The one-shot repair of a thinking level left raised by a pre-1.3.0 session, and the "thinkingLevel is no longer used" row in the settings menu. An unknown `thinkingLevel` key in `pi-plan-mode.json` is still preserved verbatim on save.
+  - The `plan-mode.json` settings fallback and its "Using legacy…" / "ignored because…" notices. Only `$PI_CODING_AGENT_DIR/pi-plan-mode.json` is read now; a host still on the old filename gets defaults and should rename the file.
+
+  Internally, the settings watcher and the menu/workflow lifecycle moved into their own modules and the state transitions share one helper; nothing else about `/plan` changed. `engines.node` now states Pi's own floor, `>=22.19.0`.
+
 ## 1.5.0
 
 ### Minor Changes

package/README.md

@@ -17,7 +17,7 @@ The plan is written to a **durable file** that survives compaction, survives res
 - Two ways to implement: continue in this conversation, or open a fresh session that reads the same file.
 - `/plan export [path]` copies the plan anywhere, never overwriting an existing target.
 - Hand-edit the plan file at any time; every command and both implementation paths read from disk.
-- A companion `pi-plan-mode` **skill**, loaded on demand, carrying the plan-crafting craft the prompt only points at.
+- A shipped **plan-craft doc** the prompt points at by path, carrying the plan-crafting craft the prompt itself only names.
 
 ## 📦 Install
 
@@ -118,11 +118,11 @@ Detection is by tool name at runtime, re-evaluated every turn — there is no de
 
 A standalone `pi-plan-mode` install loses nothing: `plan_mode_question` stays fully functional and the prompt reads exactly as it always has. It is a **legacy fallback** and is slated for removal in a future major.
 
-## 📚 The companion skill
+## 📚 The plan-craft doc
 
-The package ships a `pi-plan-mode` skill (`skills/pi-plan-mode/SKILL.md`) alongside the extension. The system prompt is the enforcement surface and stays deliberately short; the skill is the depth layer it points at — what decision-complete actually means, why exploration comes before questions, what separates a question worth asking from one the repository already answered, and what belongs in a finished plan. One line in the planning prompt names it, and the model loads the body when it judges it needs it.
+The system prompt is the enforcement surface and stays deliberately short. The depth layer it points at — what decision-complete actually means, why exploration comes before questions, what separates a question worth asking from one the repository already answered, and what belongs in a finished plan — is [`docs/plan-craft.md`](docs/plan-craft.md), shipped with the package. One line in the planning prompt names it by absolute path (resolved from the installed package, so it works under any install layout), and the model reads it when Plan Mode opens.
 
-Skill and extension version as one artifact: a skill describing a mode the installed extension does not have is a coupling failure waiting to happen.
+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 planning unprompted. Across ~220 sessions after it shipped, every read of the file happened after the Plan Mode prompt was already active, never off the description, and the model never suggested `/plan` on its own — so the line was a tax on every session that never planned (about 95% of them) that bought nothing. A hard path injected only while the mode is active is the same document at zero cost outside it.
 
 ## 📊 Statusline and widget
 
@@ -145,7 +145,7 @@ packages/pi-plan-mode/
 │   ├── plan-file.ts      # Durable plan file read/write/delete
 │   ├── interactive-ui.ts # Lazily loaded interactive menus
 │   └── *.ts              # Prompt, question, export, settings modules
-├── skills/pi-plan-mode/  # Companion plan-crafting skill
+├── docs/plan-craft.md    # Plan-crafting depth, injected by path while the mode is active
 ├── test/
 ├── README.md
 ├── NOTICE.md
@@ -153,6 +153,10 @@ packages/pi-plan-mode/
 └── package.json
 ```
 
+## Changelog
+
+See [CHANGELOG.md](CHANGELOG.md) for release history.
+
 ## 📄 License
 
 MIT. See [`LICENSE`](./LICENSE).

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

@@ -1,9 +1,3 @@
----
-name: pi-plan-mode
-description: Craft decision-complete implementation plans in Plan mode — explore before asking, ask questions worth answering, and write a plan another agent can execute without guessing. Use while Plan mode is active, before calling plan_mode_complete, and when deciding whether a request needs a plan at all.
-license: MIT
----
-
 # pi-plan-mode
 
 The extension enforces the mechanics: `edit` and `write` are blocked, the plan is written to a durable file, and `plan_mode_complete` is the only way out. It cannot enforce the thing that decides whether the plan was worth making: **whether a competent implementer could execute it without asking you anything.** That is this file.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hank-warren/pi-plan-mode",
-  "version": "1.5.0",
+  "version": "1.7.0",
   "description": "Plan mode for Pi: research and design with a durable plan file that survives compaction.",
   "type": "module",
   "keywords": [
@@ -22,20 +22,17 @@
   },
   "homepage": "https://github.com/hank-warren/pi-extensions/tree/main/packages/pi-plan-mode#readme",
   "engines": {
-    "node": ">=18.0.0"
+    "node": ">=22.19.0"
   },
   "pi": {
     "extensions": [
       "./index.ts"
-    ],
-    "skills": [
-      "./skills/pi-plan-mode"
     ]
   },
   "files": [
     "index.ts",
     "src",
-    "skills",
+    "docs/plan-craft.md",
     "README.md",
     "NOTICE.md",
     "LICENSE",

package/src/command.ts

@@ -1,4 +1,4 @@
-export interface CommandArgumentCompletion {
+interface CommandArgumentCompletion {
 	value: string;
 	label: string;
 	description?: string;

package/src/completion-tool.ts

@@ -2,10 +2,10 @@ import { getMarkdownTheme } from "@earendil-works/pi-coding-agent";
 import { Markdown } from "@earendil-works/pi-tui";
 
 export const PLAN_MODE_COMPLETE_TOOL_NAME = "plan_mode_complete";
-export const PLAN_MODE_COMPLETE_VERSION = 1;
-export const PLAN_MODE_MAX_CHARS = 50_000;
+const PLAN_MODE_COMPLETE_VERSION = 1;
+const PLAN_MODE_MAX_CHARS = 50_000;
 
-export type PlanModeCompletionDetails = {
+type PlanModeCompletionDetails = {
 	version: typeof PLAN_MODE_COMPLETE_VERSION;
 	source: typeof PLAN_MODE_COMPLETE_TOOL_NAME;
 	plan: string;
@@ -43,7 +43,7 @@ export function normalizePlanModeCompletion(input: unknown): NormalizePlanModeCo
 	return { ok: true, plan };
 }
 
-export function planFromCompletionDetails(value: unknown) {
+function planFromCompletionDetails(value: unknown) {
 	if (!isRecord(value)) return undefined;
 	if (
 		value.version !== PLAN_MODE_COMPLETE_VERSION ||
@@ -78,7 +78,7 @@ type PlanModeCompletionRenderResult = {
 	details?: unknown;
 };
 
-export function planModeCompletionMarkdown(result: PlanModeCompletionRenderResult) {
+function planModeCompletionMarkdown(result: PlanModeCompletionRenderResult) {
 	const content = result.content
 		.filter((block) => block.type === "text" && typeof block.text === "string")
 		.map((block) => block.text)

package/src/extension-runtime.ts

@@ -1,5 +1,4 @@
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
-import type { LegacyThinkingCapture } from "./state.js";
 
 type AgentSettledHandler = (event: unknown, ctx: ExtensionContext) => unknown;
 
@@ -11,16 +10,6 @@ export function onAgentSettled(pi: ExtensionAPI, handler: AgentSettledHandler) {
 	).on("agent_settled", handler);
 }
 
-/**
- * Only the one-shot migration that undoes a pre-1.3.0 thinking-level change
- * still calls this. Plan mode never sets the thinking level otherwise.
- *
- * legacy: delete in 1.4.0
- */
-export function setPlanThinkingLevel(pi: ExtensionAPI, level: LegacyThinkingCapture["previous"]) {
-	(pi.setThinkingLevel as unknown as (level: string) => void)(level);
-}
-
 export function isStaleExtensionContextError(error: unknown) {
 	return (
 		error instanceof Error &&

package/src/fresh-implementation.ts

@@ -5,7 +5,7 @@ import type { PlanModeState } from "./state.js";
 type NewSessionOptions = Exclude<Parameters<ExtensionCommandContext["newSession"]>[0], undefined>;
 type ReplacementContext = Parameters<NonNullable<NewSessionOptions["withSession"]>>[0];
 
-export interface FreshImplementationRequest {
+interface FreshImplementationRequest {
 	plan: string;
 	planPath: string;
 	stateEntryType: string;
@@ -18,7 +18,7 @@ interface FreshImplementationFromStateOptions {
 	stateEntryType: string;
 }
 
-export type FreshImplementationResult =
+type FreshImplementationResult =
 	| { kind: "started" }
 	| { kind: "cancelled" }
 	| { kind: "partial" }

package/src/lifecycle.ts

@@ -0,0 +1,79 @@
+/**
+ * A scope captured when deferred work starts: the signal that work should race
+ * against, and the question "is what I was started for still the current
+ * thing?".
+ */
+export interface LifecycleScope {
+	readonly signal: AbortSignal;
+	isCurrent(): boolean;
+}
+
+/**
+ * Two nested generations decide whether deferred Plan-mode work may still act.
+ *
+ * The session generation moves when Pi replaces or shuts down the session: a
+ * menu, a settings reload, or a question left waiting from the previous session
+ * must never write to the new one. The workflow generation moves on every
+ * enter/exit/implement, so a menu opened against one plan cannot act after the
+ * user has moved on — while a settings reload, which belongs to the session
+ * rather than to a plan, is deliberately left alone by it.
+ *
+ * The abort signal is the second half of the same rule: it stops work that is
+ * already blocked on the UI, where a generation check would never be reached.
+ */
+export function createLifecycle() {
+	let sessionGeneration = 0;
+	let workflowGeneration = 0;
+	let controller = new AbortController();
+
+	const sessionScope = (): LifecycleScope => {
+		const session = sessionGeneration;
+		const active = controller;
+		return {
+			signal: active.signal,
+			isCurrent: () => session === sessionGeneration && !active.signal.aborted,
+		};
+	};
+
+	/**
+	 * Ends the current session: everything captured before this call goes stale
+	 * and everything waiting on the signal is aborted with `reason`. The aborted
+	 * signal stays in place, so anything captured *after* it is stale too —
+	 * which is what a shut-down session wants: there is no next session to be
+	 * current for, and a menu opened in that window must refuse to run.
+	 */
+	const endSession = (reason: string) => {
+		sessionGeneration += 1;
+		controller.abort(new DOMException(reason, "AbortError"));
+	};
+
+	return {
+		/** The live session signal, for composing with a caller's own. */
+		get signal() {
+			return controller.signal;
+		},
+		endSession,
+		/**
+		 * Ends the current session and opens the next one, whose scope is
+		 * returned: work started from here races against a fresh signal.
+		 */
+		nextSession(reason: string): LifecycleScope {
+			endSession(reason);
+			controller = new AbortController();
+			return sessionScope();
+		},
+		/** Supersedes menus and prompts opened against the previous plan state. */
+		nextWorkflow() {
+			workflowGeneration += 1;
+		},
+		/** The scope for menu-scale work: stale as soon as either generation moves. */
+		capture(): LifecycleScope {
+			const session = sessionScope();
+			const workflow = workflowGeneration;
+			return {
+				signal: session.signal,
+				isCurrent: () => session.isCurrent() && workflow === workflowGeneration,
+			};
+		},
+	};
+}

package/src/plan-export.ts

@@ -8,7 +8,7 @@ import type { PlanModeState } from "./state.js";
 
 export { DEFAULT_PLAN_EXPORT_PATH };
 
-export interface PlanExportResult {
+interface PlanExportResult {
 	path: string;
 }
 
@@ -17,7 +17,7 @@ export interface PlanExportDestination {
 	resolvedPath: string;
 }
 
-export interface PlanExportLifecycle {
+interface PlanExportLifecycle {
 	signal: AbortSignal;
 	isCurrent(): boolean;
 	getState?(): PlanModeState;
@@ -74,7 +74,7 @@ export async function exportStoredPlan(
 	return true;
 }
 
-export async function exportPlanToFile(
+async function exportPlanToFile(
 	plan: string,
 	requestedPath: string | undefined,
 	cwd: string,
@@ -109,7 +109,7 @@ export function planExportDestination(defaultPath: string, cwd: string): PlanExp
 	};
 }
 
-export function resolvePlanExportPath(
+function resolvePlanExportPath(
 	requestedPath: string | undefined,
 	cwd: string,
 	defaultPath = DEFAULT_PLAN_EXPORT_PATH,

package/src/plan-file.ts

@@ -4,7 +4,7 @@ import { mkdir, open, rename, rm, unlink, writeFile } from "node:fs/promises";
 import { basename, dirname, join } from "node:path";
 import { getAgentDir } from "@earendil-works/pi-coding-agent";
 
-export const PLANS_DIRECTORY = "plans";
+const PLANS_DIRECTORY = "plans";
 const MAX_PLAN_BYTES = 1024 * 1024;
 
 /**
@@ -79,7 +79,3 @@ export async function readPlanFile(path: string): Promise<string | undefined> {
 export async function deletePlanFile(path: string): Promise<void> {
 	await unlink(path).catch(() => undefined);
 }
-
-export async function planFileExists(path: string): Promise<boolean> {
-	return (await readPlanFile(path)) !== undefined;
-}

package/src/plan-launch-menu.ts

@@ -1,7 +1,7 @@
 import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { defineMenu, runMenu } from "@narumitw/pi-tui-kit";
 
-export interface PlanLaunchMenuOptions {
+interface PlanLaunchMenuOptions {
 	statusText: string;
 	signal: AbortSignal;
 	isCurrent(): boolean;