pi-plan-task 1.0.0

package/README.md

@@ -0,0 +1,100 @@
+# pi-plan-task
+
+One Pi package: `/plan`, `/build`, `/goal`, and `/tasks`. Progress lives on disk, so a new session or a Pi restart can continue from the next unfinished task.
+
+## Commands
+
+| Command | What it does |
+|---|---|
+| `/plan [file|goal]` | Read-only planning. Writes `.plan_task/plan.md` and `.plan_task/task.md`. |
+| `/build` | Execute the next unfinished task, then ask whether to continue here or in a new session. |
+| `/goal` | Execute remaining tasks until `task.md` is complete. No session prompts. |
+| `/tasks` | Show the current task list and progress. |
+
+Restarting Pi does not auto-start work. Run `/build` again.
+
+`/plan` accepts a spec file, a prompt, or a file plus extra notes:
+
+```
+/plan
+/plan Add login with OAuth
+/plan docs/auth-spec.md
+/plan docs/auth-spec.md focus on the callback flow
+/plan @docs/auth-spec.md
+```
+
+If the first argument is an existing file — or looks like a path such as `./spec.md`, `notes.txt`, or `@spec.md` — that file is the spec. Anything after it is extra planning guidance. Missing explicit paths are rejected instead of being treated as a prompt.
+
+## Planning method
+
+`/plan` uses `extensions/planning-and-task-breakdown.md` as the planning prompt.
+
+That file keeps the same section headings as `planning-and-task-breakdown.md`, so later methodology edits can be copied section-by-section from that source. Plan-task only changes output paths and the checklist form `/build` needs:
+
+- `.plan_task/plan.md` and `.plan_task/task.md`
+- checklist lines in the form `- [ ] N. Title`
+
+This package does not install or load a skill. It also does not modify Pi's system prompt.
+
+
+## Prompt injection
+
+Phase instructions are conversation messages, not system-prompt patches:
+
+- `/plan` and `/build` send a short visible user message to start the turn.
+- The planning method or current-task instructions are injected once, as a hidden message, when that phase or task starts.
+- Later turns in the same phase inject nothing unless the checklist actually changed; then a small build-status message is appended.
+- `context` keeps only the newest framing for the current phase. Stale plan/build messages are dropped from the model context. While idle, every injected message is filtered out.
+
+Session history still stores the injected messages. Filtering is non-destructive.
+
+## Ask user
+
+`ask_user_question` is available in every mode, not just `/plan`. Use it for consequential choices the repo cannot answer:
+
+- 2-4 selectable options
+- optional recommended default, shown with ★
+- free-form Other path (on by default; set `allowOther: false` to hide it)
+
+In the TUI, pick an option or choose **Other / type my answer**. Without a UI, the tool asks the agent to pose the question in chat.
+
+## Files
+
+Created in the current project:
+
+```
+.plan_task/plan.md
+.plan_task/task.md
+```
+
+`task.md` must start with numbered checklist lines:
+
+```markdown
+- [ ] 1. Add login API
+- [ ] 2. Add login UI
+```
+
+`/build` resumes from the first unchecked item.
+
+## Config
+
+Allowed `/plan` tools:
+
+- Global: `~/.pi/agent/plan_task.json`
+- Project override: `.pi/plan_task.json`
+
+```json
+{
+  "planTools": ["read", "bash", "grep", "find", "ls", "pwsh", "rg"]
+}
+```
+
+During `/plan`, `write` and `edit` stay available but can only touch the two plan files. Bash is limited to read-only commands.
+
+## Install
+
+```bash
+pi install D:/work/tools/pi-plan-task
+```
+
+Or add the path to `packages` in `~/.pi/agent/settings.json`, then restart Pi or run `/reload`.

package/extensions/ask-question.test.ts

@@ -0,0 +1,91 @@
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+import {
+	OTHER_LABEL,
+	questionDisplayLabels,
+	validateQuestionParams,
+} from "./ask-question.ts";
+
+const options = [
+	{ label: "SQLite", description: "Local file" },
+	{ label: "Postgres", description: "Shared DB" },
+];
+
+describe("validateQuestionParams", () => {
+	it("accepts 2-4 unique labels and a matching recommended option", () => {
+		const result = validateQuestionParams({
+			question: "Which database?",
+			options,
+			recommended: "postgres",
+		});
+		assert.equal(result.recommendedIndex, 1);
+		assert.equal(result.options.length, 2);
+	});
+
+	it("rejects blank, duplicate, Other-conflicting, and unmatched recommended labels", () => {
+		assert.throws(() => validateQuestionParams({ question: "Q", options: [{ label: "A" }, { label: " " }] }), /non-blank/);
+		assert.throws(
+			() => validateQuestionParams({ question: "Q", options: [{ label: "A" }, { label: "A" }] }),
+			/unique/,
+		);
+		assert.throws(
+			() => validateQuestionParams({ question: "Q", options: [{ label: "A" }, { label: "Other path" }] }),
+			/Other/,
+		);
+		assert.throws(
+			() => validateQuestionParams({ question: "Q", options, recommended: "Redis" }),
+			/recommended/,
+		);
+	});
+});
+
+describe("questionDisplayLabels", () => {
+	it("marks the recommended option with a star", () => {
+		assert.deepEqual(questionDisplayLabels(options, 1), [
+			"SQLite — Local file",
+			"★ Postgres — Shared DB",
+		]);
+		assert.equal(OTHER_LABEL, "Other / type my answer");
+	});
+});
+
+describe("executeAskQuestion", () => {
+	it("asks in chat when no UI is available", async () => {
+		const { executeAskQuestion } = await import("./ask-question.ts");
+		const result = await executeAskQuestion(
+			{ question: "Which database?", options },
+			{ hasUI: false } as never,
+		);
+		assert.match(result.content[0]?.text ?? "", /UI is not available/);
+		assert.equal(result.details.answer, null);
+	});
+
+	it("selects the starred option and accepts a free-form Other answer", async () => {
+		const { executeAskQuestion, OTHER_LABEL } = await import("./ask-question.ts");
+		const selected = await executeAskQuestion(
+			{ question: "Which database?", options, recommended: "Postgres" },
+			{
+				hasUI: true,
+				ui: {
+					select: async (_question: string, labels: string[]) => labels.find((label) => label.startsWith("★")),
+					editor: async () => undefined,
+				},
+			} as never,
+		);
+		assert.equal(selected.details.answer, "Postgres");
+		assert.equal(selected.details.wasCustom, false);
+
+		const custom = await executeAskQuestion(
+			{ question: "Which database?", options },
+			{
+				hasUI: true,
+				ui: {
+					select: async () => OTHER_LABEL,
+					editor: async () => "  Redis  ",
+				},
+			} as never,
+		);
+		assert.equal(custom.details.answer, "Redis");
+		assert.equal(custom.details.wasCustom, true);
+	});
+});

package/extensions/ask-question.ts

@@ -0,0 +1,145 @@
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+
+export const ASK_USER_QUESTION_TOOL = "ask_user_question";
+export const OTHER_LABEL = "Other / type my answer";
+
+export interface QuestionOption {
+	label: string;
+	description?: string;
+}
+
+export interface QuestionParams {
+	question: string;
+	options: QuestionOption[];
+	recommended?: string;
+	allowOther?: boolean;
+}
+
+export const ASK_QUESTION_GUIDELINES = [
+	"Use only when repo research leaves a consequential ambiguity.",
+	"Prefer 2-4 concrete options. Use short labels.",
+	"Don't ask what's discoverable from repo.",
+	"Respect user's stated preference.",
+	"Provide a recommended option when one choice is clearly preferable.",
+];
+
+
+export function validateQuestionParams(params: QuestionParams): {
+	options: QuestionOption[];
+	recommendedIndex: number | null;
+} {
+	const question = params.question?.trim() ?? "";
+	if (!question) throw new Error("question must be non-blank.");
+	const options = params.options ?? [];
+	if (options.length < 2 || options.length > 4) {
+		throw new Error("Provide 2-4 options.");
+	}
+	const labels = options.map((option) => option.label.trim());
+	if (labels.some((label) => !label)) {
+		throw new Error("Each option must have a non-blank label.");
+	}
+	if (new Set(labels).size !== labels.length) {
+		throw new Error("Option labels must be unique.");
+	}
+	if (labels.some((label) => label.toLowerCase() === "other" || label.toLowerCase().startsWith("other "))) {
+		throw new Error('Option labels cannot conflict with the "Other" label.');
+	}
+	let recommendedIndex: number | null = null;
+	if (params.recommended) {
+		const recommended = params.recommended.trim();
+		const matchIdx = labels.findIndex((label) => label.toLowerCase() === recommended.toLowerCase());
+		if (matchIdx === -1) {
+			throw new Error("recommended must match one of the option labels.");
+		}
+		recommendedIndex = matchIdx;
+	}
+	return { options, recommendedIndex };
+}
+
+export function questionDisplayLabels(
+	options: QuestionOption[],
+	recommendedIndex: number | null,
+): string[] {
+	return options.map((option, index) => {
+		const star = recommendedIndex !== null && index === recommendedIndex && options.length > 1 ? "★ " : "";
+		return option.description ? `${star}${option.label} — ${option.description}` : `${star}${option.label}`;
+	});
+}
+
+function textResult(
+	text: string,
+	details: Record<string, unknown>,
+): { content: [{ type: "text"; text: string }]; details: Record<string, unknown> } {
+	return { content: [{ type: "text", text }], details };
+}
+
+export async function executeAskQuestion(
+	params: unknown,
+	ctx: ExtensionContext,
+): Promise<{ content: [{ type: "text"; text: string }]; details: Record<string, unknown> }> {
+	const typed = params as QuestionParams;
+	let options: QuestionOption[];
+	let recommendedIndex: number | null;
+	try {
+		({ options, recommendedIndex } = validateQuestionParams(typed));
+	} catch (error) {
+		return textResult(error instanceof Error ? error.message : String(error), {
+			question: typed.question,
+			answer: null,
+			cancelled: false,
+			wasCustom: false,
+		});
+	}
+	if (!ctx.hasUI) {
+		return textResult("UI is not available. Ask this question directly in chat and wait for the user's answer.", {
+			question: typed.question,
+			options,
+			answer: null,
+			wasCustom: false,
+			cancelled: false,
+		});
+	}
+	const allowOther = typed.allowOther !== false;
+	const displayLabels = questionDisplayLabels(options, recommendedIndex);
+	const choice = await ctx.ui.select(typed.question, allowOther ? [...displayLabels, OTHER_LABEL] : displayLabels);
+	if (!choice) {
+		return textResult("User cancelled the question.", {
+			question: typed.question,
+			options,
+			answer: null,
+			cancelled: true,
+			wasCustom: false,
+		});
+	}
+	if (choice === OTHER_LABEL) {
+		const answer = (await ctx.ui.editor("Your answer", ""))?.trim();
+		if (!answer) {
+			return textResult("User cancelled the question.", {
+				question: typed.question,
+				options,
+				answer: null,
+				cancelled: true,
+				wasCustom: false,
+			});
+		}
+		return textResult(`User wrote: ${answer}`, {
+			question: typed.question,
+			options,
+			answer,
+			wasCustom: true,
+			cancelled: false,
+		});
+	}
+	const selectedIndex = displayLabels.indexOf(choice);
+	const selected = options[selectedIndex];
+	const answer = selected?.label ?? choice;
+	return textResult(`User selected: ${answer}`, {
+		question: typed.question,
+		options,
+		answer,
+		selectedIndex,
+		recommendedIndex,
+		wasCustom: false,
+		cancelled: false,
+	});
+}

package/extensions/bash-guard.test.ts

@@ -0,0 +1,17 @@
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+import { isSafePlanCommand } from "./bash-guard.ts";
+
+describe("isSafePlanCommand", () => {
+	it("allows read-only inspection", () => {
+		assert.equal(isSafePlanCommand("ls src"), true);
+		assert.equal(isSafePlanCommand("git status"), true);
+		assert.equal(isSafePlanCommand("rg TODO"), true);
+	});
+
+	it("blocks writes and destructive git", () => {
+		assert.equal(isSafePlanCommand("rm -rf src"), false);
+		assert.equal(isSafePlanCommand("git commit -m wip"), false);
+		assert.equal(isSafePlanCommand("echo hi > file.txt"), false);
+	});
+});

package/extensions/bash-guard.ts

@@ -0,0 +1,94 @@
+const DESTRUCTIVE_PATTERNS = [
+	/\brm\b/i,
+	/\brmdir\b/i,
+	/\bmv\b/i,
+	/\bcp\b/i,
+	/\bmkdir\b/i,
+	/\btouch\b/i,
+	/\bchmod\b/i,
+	/\bchown\b/i,
+	/\bchgrp\b/i,
+	/\bln\b/i,
+	/\btee\b/i,
+	/\btruncate\b/i,
+	/\bdd\b/i,
+	/\bshred\b/i,
+	/(^|[^<])>(?!>)/,
+	/>>/,
+	/\bnpm\s+(install|uninstall|update|ci|link|publish)/i,
+	/\byarn\s+(add|remove|install|publish)/i,
+	/\bpnpm\s+(add|remove|install|publish)/i,
+	/\bpip\s+(install|uninstall)/i,
+	/\bapt(-get)?\s+(install|remove|purge|update|upgrade)/i,
+	/\bbrew\s+(install|uninstall|upgrade)/i,
+	/\bgit\s+(add|commit|push|pull|merge|rebase|reset|checkout|branch\s+-[dD]|stash|cherry-pick|revert|tag|init|clone)/i,
+	/\bsudo\b/i,
+	/\bsu\b/i,
+	/\bkill\b/i,
+	/\bpkill\b/i,
+	/\bkillall\b/i,
+	/\breboot\b/i,
+	/\bshutdown\b/i,
+	/\bsystemctl\s+(start|stop|restart|enable|disable)/i,
+	/\bservice\s+\S+\s+(start|stop|restart)/i,
+	/\b(vim?|nano|emacs|code|subl)\b/i,
+];
+
+const SAFE_PATTERNS = [
+	/^\s*cat\b/,
+	/^\s*head\b/,
+	/^\s*tail\b/,
+	/^\s*less\b/,
+	/^\s*more\b/,
+	/^\s*grep\b/,
+	/^\s*find\b/,
+	/^\s*ls\b/,
+	/^\s*pwd\b/,
+	/^\s*echo\b/,
+	/^\s*printf\b/,
+	/^\s*wc\b/,
+	/^\s*sort\b/,
+	/^\s*uniq\b/,
+	/^\s*diff\b/,
+	/^\s*file\b/,
+	/^\s*stat\b/,
+	/^\s*du\b/,
+	/^\s*df\b/,
+	/^\s*tree\b/,
+	/^\s*which\b/,
+	/^\s*whereis\b/,
+	/^\s*type\b/,
+	/^\s*env\b/,
+	/^\s*printenv\b/,
+	/^\s*uname\b/,
+	/^\s*whoami\b/,
+	/^\s*id\b/,
+	/^\s*date\b/,
+	/^\s*cal\b/,
+	/^\s*uptime\b/,
+	/^\s*ps\b/,
+	/^\s*top\b/,
+	/^\s*htop\b/,
+	/^\s*free\b/,
+	/^\s*git\s+(status|log|diff|show|branch|remote|config\s+--get)/i,
+	/^\s*git\s+ls-/i,
+	/^\s*npm\s+(list|ls|view|info|search|outdated|audit)/i,
+	/^\s*yarn\s+(list|info|why|audit)/i,
+	/^\s*node\s+--version/i,
+	/^\s*python\s+--version/i,
+	/^\s*curl\s/i,
+	/^\s*wget\s+-O\s*-/i,
+	/^\s*jq\b/,
+	/^\s*sed\s+-n/i,
+	/^\s*awk\b/,
+	/^\s*rg\b/,
+	/^\s*fd\b/,
+	/^\s*bat\b/,
+	/^\s*eza\b/,
+];
+
+export function isSafePlanCommand(command: string): boolean {
+	const isDestructive = DESTRUCTIVE_PATTERNS.some((pattern) => pattern.test(command));
+	const isSafe = SAFE_PATTERNS.some((pattern) => pattern.test(command));
+	return !isDestructive && isSafe;
+}

package/extensions/config.ts

@@ -0,0 +1,49 @@
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { dirname } from "node:path";
+import { globalConfigPath, projectConfigPath } from "./paths.ts";
+import { DEFAULT_CONFIG, type PlanTaskConfig } from "./types.ts";
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function parseConfig(raw: string): Partial<PlanTaskConfig> {
+	const parsed: unknown = JSON.parse(raw);
+	if (!isRecord(parsed)) return {};
+	const next: Partial<PlanTaskConfig> = {};
+	if (Array.isArray(parsed.planTools)) {
+		next.planTools = parsed.planTools.filter(
+			(item): item is string => typeof item === "string" && item.trim().length > 0,
+		);
+	}
+	return next;
+}
+
+async function readConfigFile(path: string): Promise<Partial<PlanTaskConfig>> {
+	try {
+		return parseConfig(await readFile(path, "utf8"));
+	} catch {
+		return {};
+	}
+}
+
+export async function ensureDefaultGlobalConfig(): Promise<void> {
+	const path = globalConfigPath();
+	try {
+		await readFile(path, "utf8");
+	} catch {
+		await mkdir(dirname(path), { recursive: true });
+		await writeFile(path, `${JSON.stringify(DEFAULT_CONFIG, null, 2)}\n`, "utf8");
+	}
+}
+
+export async function loadConfig(cwd: string): Promise<PlanTaskConfig> {
+	const globalConfig = await readConfigFile(globalConfigPath());
+	const projectConfig = await readConfigFile(projectConfigPath(cwd));
+	return {
+		planTools:
+			projectConfig.planTools ??
+			globalConfig.planTools ??
+			DEFAULT_CONFIG.planTools,
+	};
+}

package/extensions/files.test.ts

@@ -0,0 +1,59 @@
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+import { markTaskDoneInMarkdown, parseTaskMarkdown } from "./parse.ts";
+
+const SAMPLE = `# Tasks
+
+- [ ] 1. Add login API
+- [ ] 2. Add login UI
+- [x] 3. Already done
+
+## Task 1: Add login API
+
+**Description:** Create the endpoint.
+**Acceptance criteria:**
+- [ ] Returns 200
+- [ ] Validates input
+
+## Task 2: Add login UI
+
+**Description:** Build the form.
+`;
+
+describe("parseTaskMarkdown", () => {
+	it("reads numbered checklist items and ignores nested boxes", () => {
+		const tasks = parseTaskMarkdown(SAMPLE);
+		assert.equal(tasks.length, 3);
+		assert.deepEqual(
+			tasks.map((task) => ({ id: task.id, title: task.title, done: task.done })),
+			[
+				{ id: 1, title: "Add login API", done: false },
+				{ id: 2, title: "Add login UI", done: false },
+				{ id: 3, title: "Already done", done: true },
+			],
+		);
+		assert.match(tasks[0]?.body ?? "", /Create the endpoint/);
+		assert.match(tasks[1]?.body ?? "", /Build the form/);
+	});
+
+	it("falls back to unnumbered checklist items", () => {
+		const tasks = parseTaskMarkdown(`# Tasks\n\n- [ ] First\n- [x] Second\n`);
+		assert.equal(tasks.length, 2);
+		assert.equal(tasks[0]?.id, 1);
+		assert.equal(tasks[0]?.title, "First");
+		assert.equal(tasks[1]?.done, true);
+	});
+});
+
+describe("markTaskDoneInMarkdown", () => {
+	it("checks the matching numbered item only", () => {
+		const next = markTaskDoneInMarkdown(SAMPLE, 2);
+		assert.match(next, /- \[x\] 2\. Add login UI/);
+		assert.match(next, /- \[ \] 1\. Add login API/);
+		assert.match(next, /- \[ \] Returns 200/);
+	});
+
+	it("is a no-op when the item is already done", () => {
+		assert.equal(markTaskDoneInMarkdown(SAMPLE, 3), SAMPLE);
+	});
+});

package/extensions/files.ts

@@ -0,0 +1,50 @@
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { planDir, planFilePath, taskFilePath } from "./paths.ts";
+import { markTaskDoneInMarkdown, parseTaskMarkdown } from "./parse.ts";
+import type { TaskFile, TaskItem } from "./types.ts";
+
+export { markTaskDoneInMarkdown, parseTaskMarkdown } from "./parse.ts";
+
+export async function ensurePlanDir(cwd: string): Promise<void> {
+	await mkdir(planDir(cwd), { recursive: true });
+}
+
+export async function readOptionalFile(path: string): Promise<string | undefined> {
+	try {
+		return await readFile(path, "utf8");
+	} catch {
+		return undefined;
+	}
+}
+
+export async function loadTaskFile(cwd: string): Promise<TaskFile | undefined> {
+	const raw = await readOptionalFile(taskFilePath(cwd));
+	if (raw === undefined) return undefined;
+	return { raw, tasks: parseTaskMarkdown(raw) };
+}
+
+export async function markTaskComplete(cwd: string, id: number): Promise<TaskFile | undefined> {
+	const current = await loadTaskFile(cwd);
+	if (!current) return undefined;
+	const nextRaw = markTaskDoneInMarkdown(current.raw, id);
+	if (nextRaw !== current.raw) {
+		await writeFile(taskFilePath(cwd), nextRaw, "utf8");
+	}
+	const planRaw = await readOptionalFile(planFilePath(cwd));
+	if (planRaw !== undefined) {
+		const nextPlan = markTaskDoneInMarkdown(planRaw, id);
+		if (nextPlan !== planRaw) {
+			await writeFile(planFilePath(cwd), nextPlan, "utf8");
+		}
+	}
+	return { raw: nextRaw, tasks: parseTaskMarkdown(nextRaw) };
+}
+
+export function nextPendingTask(tasks: TaskItem[]): TaskItem | undefined {
+	return tasks.find((task) => !task.done);
+}
+
+export function formatProgress(tasks: TaskItem[]): string {
+	const done = tasks.filter((task) => task.done).length;
+	return `${done}/${tasks.length}`;
+}

package/extensions/framing.test.ts

@@ -0,0 +1,85 @@
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+import {
+	BUILD_FRAMING_TYPE,
+	BUILD_STATUS_TYPE,
+	filterFramingMessages,
+	INITIAL_FRAMING_STATE,
+	nextInjection,
+	PLAN_FRAMING_TYPE,
+	rememberInjection,
+} from "./framing.ts";
+
+function custom(customType: string, content: string) {
+	return { role: "custom" as const, customType, content };
+}
+
+describe("filterFramingMessages", () => {
+	const messages = [
+		{ role: "user", content: "goal" },
+		custom(PLAN_FRAMING_TYPE, "plan-old"),
+		{ role: "assistant", content: "ok" },
+		custom(PLAN_FRAMING_TYPE, "plan-new"),
+		custom(BUILD_FRAMING_TYPE, "build-old"),
+		custom(BUILD_STATUS_TYPE, "status-old"),
+		custom(BUILD_FRAMING_TYPE, "build-new"),
+		custom(BUILD_STATUS_TYPE, "status-new"),
+		{ role: "user", content: "continue" },
+	];
+
+	it("drops every injected message while idle", () => {
+		assert.deepEqual(
+			filterFramingMessages(messages, "idle"),
+			[
+				{ role: "user", content: "goal" },
+				{ role: "assistant", content: "ok" },
+				{ role: "user", content: "continue" },
+			],
+		);
+	});
+
+	it("keeps only the newest plan framing", () => {
+		assert.deepEqual(
+			filterFramingMessages(messages, "plan"),
+			[
+				{ role: "user", content: "goal" },
+				{ role: "assistant", content: "ok" },
+				custom(PLAN_FRAMING_TYPE, "plan-new"),
+				{ role: "user", content: "continue" },
+			],
+		);
+	});
+
+	it("keeps only the newest build framing and status", () => {
+		assert.deepEqual(
+			filterFramingMessages(messages, "build"),
+			[
+				{ role: "user", content: "goal" },
+				{ role: "assistant", content: "ok" },
+				custom(BUILD_FRAMING_TYPE, "build-new"),
+				custom(BUILD_STATUS_TYPE, "status-new"),
+				{ role: "user", content: "continue" },
+			],
+		);
+	});
+});
+
+describe("nextInjection", () => {
+	it("injects plan framing once per phase entry", () => {
+		assert.equal(nextInjection("plan", INITIAL_FRAMING_STATE), "plan-framing");
+		const delivered = rememberInjection(INITIAL_FRAMING_STATE, "plan-framing");
+		assert.equal(nextInjection("plan", delivered), undefined);
+	});
+
+	it("injects build framing per task, then status only when the checklist changes", () => {
+		assert.equal(nextInjection("build", INITIAL_FRAMING_STATE, 1, "1:1:0"), "build-framing");
+		const framed = rememberInjection(INITIAL_FRAMING_STATE, "build-framing", 1, "1:1:0");
+		assert.equal(nextInjection("build", framed, 1, "1:1:0"), undefined);
+		assert.equal(nextInjection("build", framed, 1, "1:1:1"), "build-status");
+		assert.equal(nextInjection("build", framed, 2, "2:1:1"), "build-framing");
+	});
+
+	it("injects nothing while idle", () => {
+		assert.equal(nextInjection("idle", INITIAL_FRAMING_STATE), undefined);
+	});
+});