@pify/plan-mode 0.2.0 → 0.4.0

package/README.md

@@ -24,6 +24,10 @@ Part of the [Pify suite](https://github.com/pifydev). Install with [`pify instal
 /plan                      # toggle plan mode
 /plan add oauth login      # enter + start planning this
 /plan off                  # leave without approval
+/plan list                 # saved plans in .pi/plans/ (v0.2)
+- **Reopen a saved plan** (v0.4): `/plan open <file>` takes a filename, a stem, or any distinctive fragment (`/plan open oauth`), hands the plan text back to the agent as a hidden message, and restarts step tracking from what the file says **now** — the file is the source of truth, not the step list it produced last time.
+/plan steps                # progress through the approved plan (v0.3)
+/plan export [file]        # standalone HTML next to the plan (v0.3)
 pi --plan                  # start a session already in plan mode
 ```
 
@@ -36,6 +40,16 @@ pi remove npm:@narumitw/pi-plan-mode
 pify install plan-mode
 ```
 
+## After approval (v0.3)
+
+An approved plan becomes a tracked step list rather than a document the agent re-reads each turn — which is how plans get quietly abandoned halfway. Steps are parsed from the markdown the agent already wrote (numbered list, or the bullets under a *Steps*-ish heading), so there is no second source of truth.
+
+- `plan_step_done(index, evidence)` — the agent ticks off one step at a time, with evidence, and gets the next one back. Completing out of order is allowed but reported: the answer names the steps still open before it.
+- The status badge follows execution — `📋 2/7 steps` — instead of disappearing at approval.
+- `/plan steps` shows the list; progress survives `/reload` and branch switches with the rest of the plan state.
+
+`/plan export` writes a self-contained HTML file next to the plan: no assets, no network, everything escaped before rendering — a plan containing HTML is shown as text, not executed.
+
 ## License
 
 MIT © [Pify maintainers](https://github.com/pifydev)

package/extensions/plan-mode.ts

@@ -26,11 +26,25 @@ import type {
 import { Type } from "typebox";
 
 import { classifyToolCall } from "../src/policy.ts";
-import { createPlanFile, listPlanFiles } from "../src/plans.ts";
+import { readFileSync, writeFileSync } from "node:fs";
+import { basename, isAbsolute, join } from "node:path";
+
+import { htmlPathFor, renderPlanHtml } from "../src/export.ts";
+import { createPlanFile, listPlanFiles, plansDir, resolvePlanFile } from "../src/plans.ts";
+import {
+  completeStep,
+  formatSteps,
+  nextStep,
+  parseSteps,
+  progressLine,
+  skippedBefore,
+  type PlanStep,
+} from "../src/steps.ts";
 import {
   ENTER_REMINDER,
   EXIT_REMINDER,
   buildHandoffMessage,
+  buildReopenMessage,
   buildImplementHereMessage,
 } from "../src/prompts.ts";
 import { PLAN_STATE, replayBranch } from "../src/state.ts";
@@ -38,6 +52,16 @@ import { INITIAL_STATE, PLAN_THINKING, type PlanState } from "../src/types.ts";
 
 const REMINDER_TYPE = "plan-mode-reminder";
 
+/** Read a file, or "" when it is missing/unreadable. */
+function readFileSafe(file: string | null): string {
+  if (!file) return "";
+  try {
+    return readFileSync(file, "utf8");
+  } catch {
+    return "";
+  }
+}
+
 type UiContext = ExtensionContext;
 
 export default function planMode(pi: ExtensionAPI) {
@@ -54,7 +78,14 @@ export default function planMode(pi: ExtensionAPI) {
 
   function updateBadge(ctx: UiContext): void {
     if (!ctx.hasUI) return;
-    ctx.ui.setStatus("plan", state.active ? "📋 plan" : undefined);
+    if (state.active) {
+      ctx.ui.setStatus("plan", "📋 plan");
+      return;
+    }
+    // After approval the badge follows execution instead of disappearing —
+    // that is exactly when a plan gets quietly abandoned halfway.
+    const open = state.steps.filter((s) => !s.done).length;
+    ctx.ui.setStatus("plan", open > 0 ? `📋 ${progressLine(state.steps)}` : undefined);
   }
 
   function notify(ctx: UiContext, message: string, level: "info" | "warning" | "error"): void {
@@ -75,6 +106,7 @@ export default function planMode(pi: ExtensionAPI) {
       planFile: null,
       buildThinking,
       enteredAt: Date.now(),
+      steps: [],
     });
     try {
       // Planning earns deeper thought (bacnh85); restored on exit.
@@ -87,10 +119,15 @@ export default function planMode(pi: ExtensionAPI) {
     return true;
   }
 
-  function leavePlanMode(ctx: UiContext): void {
+  /**
+   * Leave plan mode. `keepSteps` carries the approved plan's step list into
+   * execution — the tracker only exists after an approval, never after a
+   * discard.
+   */
+  function leavePlanMode(ctx: UiContext, keepSteps: PlanStep[] = []): void {
     if (!state.active) return;
     const restore = state.buildThinking;
-    commit(ctx, { ...INITIAL_STATE });
+    commit(ctx, { ...INITIAL_STATE, steps: keepSteps });
     approvedTools.clear();
     if (restore) {
       try {
@@ -210,6 +247,42 @@ export default function planMode(pi: ExtensionAPI) {
     },
   });
 
+  pi.registerTool({
+    name: "plan_step_done",
+    label: "Plan step done",
+    description:
+      "Mark one step of the approved plan complete and get the next one. Call it as you finish each " +
+      "step, with evidence of what you verified — not at the end for all steps at once. Only available " +
+      "after a plan was approved.",
+    parameters: Type.Object({
+      index: Type.Number({ description: "1-based step number from the plan" }),
+      evidence: Type.String({ description: "What you verified for this step (command output, file state)" }),
+    }),
+    async execute(_id, params: { index: number; evidence: string }, _signal, _onUpdate, ctx) {
+      if (state.steps.length === 0) {
+        throw new Error("No approved plan is being tracked. plan_step_done only works after exit_plan_mode approval.");
+      }
+      if (!params.evidence.trim()) {
+        throw new Error("plan_step_done requires evidence: what you verified for this step.");
+      }
+      const result = completeStep(state.steps, params.index);
+      if (result.error) throw new Error(result.error);
+
+      const skipped = skippedBefore(state.steps, params.index);
+      commit(ctx as UiContext, { ...state, steps: result.steps });
+
+      const next = nextStep(result.steps);
+      const lines = [
+        `Step #${params.index} done (${progressLine(result.steps)}).`,
+        skipped.length > 0
+          ? `Still open before it: ${skipped.map((s) => `#${s.index}`).join(", ")} — go back unless they no longer apply.`
+          : "",
+        next ? `Next: #${next.index} ${next.text}` : "All steps complete. Report the result to the user.",
+      ].filter(Boolean);
+      return { content: [{ type: "text", text: lines.join("\n") }], details: { steps: result.steps } };
+    },
+  });
+
   const APPROVE_HERE = "Approve — implement here";
   const APPROVE_FRESH = "Approve — implement in a fresh session";
   const REVISE = "Revise the plan";
@@ -309,7 +382,13 @@ export default function planMode(pi: ExtensionAPI) {
       }
 
       const planFile = state.planFile;
-      leavePlanMode(uiCtx);
+      // v0.3: the approved plan becomes a tracked step list, so execution has
+      // a cursor instead of the agent re-reading the markdown each turn.
+      const steps = planFile ? parseSteps(readFileSafe(planFile)) : [];
+      leavePlanMode(uiCtx, steps);
+      if (steps.length > 0) {
+        notify(uiCtx, `Tracking ${steps.length} steps — /plan steps to view.`, "info");
+      }
 
       if (decision === APPROVE_FRESH) {
         try {
@@ -347,9 +426,48 @@ export default function planMode(pi: ExtensionAPI) {
   // ── Command & shortcut ───────────────────────────────────────────────
 
   pi.registerCommand("plan", {
-    description: "Toggle read-only plan mode: /plan [off | list | <first planning prompt>]",
+    description: "Plan mode: /plan [off | list | open <file> | steps | export [file] | <first planning prompt>]",
     handler: async (args, ctx) => {
       const text = (args ?? "").trim();
+      if (text.toLowerCase() === "steps") {
+        notify(
+          ctx,
+          state.steps.length === 0
+            ? "No plan is being tracked. Steps appear after a plan is approved with exit_plan_mode."
+            : formatSteps(state.steps),
+          "info",
+        );
+        return;
+      }
+      if (text.toLowerCase() === "export" || text.toLowerCase().startsWith("export ")) {
+        const target = text.slice("export".length).trim() || state.planFile;
+        if (!target) {
+          notify(ctx, "Nothing to export — no current plan. Usage: /plan export [file.md]", "warning");
+          return;
+        }
+        const file = isAbsolute(target) ? target : join(plansDir(ctx.cwd), target);
+        const markdown = readFileSafe(file);
+        if (!markdown) {
+          notify(ctx, `Could not read ${file}.`, "error");
+          return;
+        }
+        const out = htmlPathFor(file);
+        try {
+          writeFileSync(
+            out,
+            renderPlanHtml(markdown, {
+              title: basename(file, ".md").replace(/^\d{4}-\d{2}-\d{2}-/, "").replace(/-/g, " "),
+              generatedAt: new Date().toISOString().replace("T", " ").slice(0, 16),
+              sourceFile: basename(file),
+              progress: state.steps.length > 0 ? progressLine(state.steps) : undefined,
+            }),
+          );
+          notify(ctx, `Exported ${out}`, "info");
+        } catch (err) {
+          notify(ctx, `Export failed: ${err instanceof Error ? err.message : String(err)}`, "error");
+        }
+        return;
+      }
       if (text.toLowerCase() === "list") {
         const plans = listPlanFiles(ctx.cwd);
         notify(
@@ -361,6 +479,37 @@ export default function planMode(pi: ExtensionAPI) {
         );
         return;
       }
+      // v0.4: reopen a saved plan — the other half of the plan library. The
+      // file is the source of truth, so tracking restarts from what it says
+      // now, not from the step list it produced when it was written.
+      if (text.toLowerCase().startsWith("open")) {
+        const wanted = text.slice("open".length).trim();
+        if (!wanted) {
+          notify(ctx, "Usage: /plan open <file>  (see /plan list)", "warning");
+          return;
+        }
+        const file = resolvePlanFile(ctx.cwd, wanted);
+        if (!file) {
+          notify(ctx, `No saved plan matches "${wanted}". /plan list shows what is there.`, "warning");
+          return;
+        }
+        const markdown = readFileSafe(file);
+        if (!markdown) {
+          notify(ctx, `Could not read ${file}.`, "error");
+          return;
+        }
+        const steps = parseSteps(markdown);
+        commit(ctx, { ...state, planFile: file, steps });
+        sendReminder(buildReopenMessage(file, markdown));
+        notify(
+          ctx,
+          steps.length > 0
+            ? `Reopened ${basename(file)} — tracking ${steps.length} steps. /plan steps to view.`
+            : `Reopened ${basename(file)}. No checklist steps were found in it.`,
+          "info",
+        );
+        return;
+      }
       if (text.toLowerCase() === "off") {
         if (!state.active) {
           notify(ctx, "Plan mode is not active.", "info");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pify/plan-mode",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "description": "Read-only planning mode for pi with an explicit approve-then-execute gate: enforced tool policy, plan files, approach options, fresh-session handoff",
   "keywords": [
     "pi-package",

package/src/export.ts

@@ -0,0 +1,153 @@
+/**
+ * Standalone HTML export of a plan (v0.3, narumiruna's plan-export). Plans
+ * get shared with people who do not have the repository — a self-contained
+ * file with no assets and no network is what actually travels.
+ *
+ * The renderer is a small markdown subset on purpose: plans are headings,
+ * lists, code, and emphasis. Everything is escaped first, so a plan
+ * containing HTML (or a prompt-injection attempt aimed at the reader) is
+ * shown as text rather than executed.
+ */
+
+export function escapeHtml(text: string): string {
+  return text
+    .replace(/&/g, "&")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;")
+    .replace(/"/g, "&quot;")
+    .replace(/'/g, "&#39;");
+}
+
+/** Inline spans, applied to already-escaped text. */
+function renderInline(escaped: string): string {
+  return escaped
+    .replace(/`([^`]+)`/g, "<code>$1</code>")
+    .replace(/\*\*([^*]+)\*\*/g, "<strong>$1</strong>")
+    .replace(/(^|[^*])\*([^*\n]+)\*/g, "$1<em>$2</em>");
+}
+
+const STYLE = [
+  ":root{color-scheme:light dark}",
+  "body{max-width:46rem;margin:2.5rem auto;padding:0 1.25rem;",
+  "font:16px/1.65 ui-sans-serif,-apple-system,Segoe UI,Roboto,sans-serif}",
+  "h1,h2,h3,h4{line-height:1.25;margin:1.8em 0 .6em}",
+  "h1{font-size:1.7rem}h2{font-size:1.3rem}h3{font-size:1.1rem}",
+  "code{background:rgba(127,127,127,.16);padding:.12em .35em;border-radius:4px;font-size:.9em}",
+  "pre{background:rgba(127,127,127,.12);padding:.9rem 1rem;border-radius:8px;overflow:auto}",
+  "pre code{background:none;padding:0}",
+  "li{margin:.3em 0}",
+  "footer{margin-top:3rem;font-size:.85rem;opacity:.65;border-top:1px solid rgba(127,127,127,.3);padding-top:.8rem}",
+  ".done{opacity:.55;text-decoration:line-through}",
+].join("");
+
+interface ListState {
+  open: "ul" | "ol" | null;
+}
+
+function closeList(state: ListState, out: string[]): void {
+  if (state.open) {
+    out.push(`</${state.open}>`);
+    state.open = null;
+  }
+}
+
+function openList(state: ListState, kind: "ul" | "ol", out: string[]): void {
+  if (state.open !== kind) {
+    closeList(state, out);
+    out.push(`<${kind}>`);
+    state.open = kind;
+  }
+}
+
+/** Render the markdown subset plans are written in. */
+export function renderMarkdown(markdown: string): string {
+  const out: string[] = [];
+  const state: ListState = { open: null };
+  let inCode = false;
+
+  for (const rawLine of (markdown ?? "").split("\n")) {
+    const line = rawLine.replace(/\r$/, "");
+
+    if (/^\s*```/.test(line)) {
+      closeList(state, out);
+      out.push(inCode ? "</code></pre>" : "<pre><code>");
+      inCode = !inCode;
+      continue;
+    }
+    if (inCode) {
+      out.push(escapeHtml(line));
+      continue;
+    }
+
+    const heading = /^(#{1,6})\s+(.*)$/.exec(line);
+    if (heading) {
+      closeList(state, out);
+      const level = Math.min(heading[1]!.length, 6);
+      out.push(`<h${level}>${renderInline(escapeHtml(heading[2]!))}</h${level}>`);
+      continue;
+    }
+
+    const ordered = /^\s*\d+[.)]\s+(.*)$/.exec(line);
+    const bullet = /^\s*[-*+]\s+(.*)$/.exec(line);
+    if (ordered || bullet) {
+      openList(state, ordered ? "ol" : "ul", out);
+      const body = (ordered ?? bullet)![1]!;
+      const checked = /^\[[xX]\]\s*/.test(body);
+      const text = renderInline(escapeHtml(body.replace(/^\[[ xX]\]\s*/, "")));
+      out.push(checked ? `<li class="done">${text}</li>` : `<li>${text}</li>`);
+      continue;
+    }
+
+    if (!line.trim()) {
+      closeList(state, out);
+      continue;
+    }
+    closeList(state, out);
+    out.push(`<p>${renderInline(escapeHtml(line))}</p>`);
+  }
+
+  if (inCode) out.push("</code></pre>");
+  closeList(state, out);
+  return out.join("\n");
+}
+
+export interface ExportOptions {
+  title: string;
+  /** Rendered into the footer; passed in so the module stays pure. */
+  generatedAt: string;
+  sourceFile?: string;
+  progress?: string;
+}
+
+export function renderPlanHtml(markdown: string, options: ExportOptions): string {
+  const title = escapeHtml(options.title);
+  const footer = [
+    options.sourceFile ? escapeHtml(options.sourceFile) : "",
+    options.progress ? escapeHtml(options.progress) : "",
+    `exported ${escapeHtml(options.generatedAt)} by @pify/plan-mode`,
+  ]
+    .filter(Boolean)
+    .join(" · ");
+
+  return [
+    "<!doctype html>",
+    '<html lang="en">',
+    "<head>",
+    '<meta charset="utf-8">',
+    '<meta name="viewport" content="width=device-width,initial-scale=1">',
+    `<title>${title}</title>`,
+    `<style>${STYLE}</style>`,
+    "</head>",
+    "<body>",
+    renderMarkdown(markdown),
+    `<footer>${footer}</footer>`,
+    "</body>",
+    "</html>",
+    "",
+  ].join("\n");
+}
+
+/** Sibling .html path for a plan file. */
+export function htmlPathFor(planFile: string): string {
+  return planFile.replace(/\.md$/i, "") + ".html";
+}

package/src/plans.ts

@@ -1,5 +1,5 @@
 import { mkdirSync, writeFileSync, existsSync, readdirSync, statSync } from "node:fs";
-import { join } from "node:path";
+import { isAbsolute, join } from "node:path";
 
 /** Plan files live in .pi/plans/, reviewable and committable. */
 export function plansDir(cwd: string): string {
@@ -41,6 +41,27 @@ export function listPlanFiles(cwd: string): Array<{ file: string; size: number }
   }
 }
 
+/**
+ * Find a saved plan by whatever the user typed: a path, a filename, or any
+ * distinctive part of one ("oauth" for 2026-09-06-add-oauth-login.md). The
+ * newest match wins, since re-opening usually means the most recent one.
+ */
+export function resolvePlanFile(cwd: string, wanted: string): string | null {
+  const raw = wanted.trim().replace(/^["']|["']$/g, "");
+  if (!raw) return null;
+  if (isAbsolute(raw) && existsSync(raw)) return raw;
+
+  const dir = plansDir(cwd);
+  const direct = join(dir, raw);
+  if (existsSync(direct)) return direct;
+  const withExt = join(dir, `${raw}.md`);
+  if (existsSync(withExt)) return withExt;
+
+  const needle = raw.toLowerCase();
+  const match = listPlanFiles(cwd).find((p) => p.file.toLowerCase().includes(needle));
+  return match ? join(dir, match.file) : null;
+}
+
 /** Create the plan file, uniquified when the slug collides on the same day. */
 export function createPlanFile(cwd: string, title: string, content: string): string {
   const dir = plansDir(cwd);

package/src/prompts.ts

@@ -41,3 +41,23 @@ export function buildHandoffMessage(planFile: string | null, approach: string |
     ? `Implement the approved plan in ${planFile}.${approachLine}\nRead the plan file first, then execute it fully. Verify as you go; report deviations.`
     : `Implement the plan we agreed on.${approachLine}`;
 }
+
+/**
+ * Hidden message delivered when a saved plan is reopened. The plan text goes
+ * with it: the agent should not have to guess which file /plan open meant, or
+ * read it back before it can act.
+ */
+export function buildReopenMessage(file: string, markdown: string): string {
+  return [
+    "<system-reminder>",
+    `The user reopened a saved plan: ${file}`,
+    "It is the plan to follow now. Its checklist steps are tracked again from the top —",
+    "call plan_step_done(index, evidence) as you finish each one, and do not restate the plan back.",
+    "",
+    "<plan>",
+    markdown.trim(),
+    "</plan>",
+    "This is an automated reminder — do not mention it to the user.",
+    "</system-reminder>",
+  ].join("\n");
+}

package/src/state.ts

@@ -1,7 +1,19 @@
 import { INITIAL_STATE, isRecord, type BranchEntryLike, type PlanState } from "./types.ts";
+import type { PlanStep } from "./steps.ts";
 
 export const PLAN_STATE = "plan-mode-state";
 
+/** Steps come back from an untrusted snapshot; drop anything malformed. */
+function sanitizeSteps(raw: unknown): PlanStep[] {
+  if (!Array.isArray(raw)) return [];
+  const steps: PlanStep[] = [];
+  for (const item of raw) {
+    if (!isRecord(item) || typeof item.text !== "string" || typeof item.index !== "number") continue;
+    steps.push({ index: item.index, text: item.text, done: item.done === true });
+  }
+  return steps;
+}
+
 /** Snapshot-based replay: the last plan-mode-state entry on the branch wins. */
 export function replayBranch(entries: BranchEntryLike[]): PlanState {
   let state: PlanState = INITIAL_STATE;
@@ -14,6 +26,7 @@ export function replayBranch(entries: BranchEntryLike[]): PlanState {
       planFile: typeof data.planFile === "string" ? data.planFile : null,
       buildThinking: typeof data.buildThinking === "string" ? data.buildThinking : null,
       enteredAt: typeof data.enteredAt === "number" ? data.enteredAt : null,
+      steps: sanitizeSteps(data.steps),
     };
   }
   return state;

package/src/steps.ts

@@ -0,0 +1,123 @@
+/**
+ * Step tracking for an approved plan (v0.3, janvitos' plan-execution). A plan
+ * is approved as a whole and then executed as a list — without a tracker the
+ * agent re-reads the markdown every turn and quietly skips steps.
+ *
+ * Steps are parsed out of the plan file the agent already wrote, so there is
+ * no second source of truth: the markdown stays the plan, this is a cursor
+ * over it.
+ */
+
+export interface PlanStep {
+  /** 1-based position in the plan. */
+  index: number;
+  text: string;
+  done: boolean;
+}
+
+const MAX_STEPS = 40;
+const MAX_STEP_CHARS = 200;
+
+/** Headings that introduce the step list; anything else is prose. */
+const STEP_HEADING = /^#{1,6}\s*(implementation\s+)?(steps|plan|tasks|todo|work)\b/i;
+const NON_STEP_HEADING = /^#{1,6}\s*(risk|verification|testing|open question|context|goal|background|note)/i;
+
+function cleanStep(raw: string): string {
+  return raw
+    .replace(/^\s*(?:\d+[.)]|[-*+]|\[[ xX]\])\s*/, "")
+    .replace(/^\[[ xX]\]\s*/, "")
+    .replace(/\s+/g, " ")
+    .trim()
+    .slice(0, MAX_STEP_CHARS);
+}
+
+/**
+ * Extract the ordered steps from a plan's markdown. Numbered lists win: a
+ * plan that numbers its steps means those and only those. Otherwise the
+ * bullets under a steps-ish heading are used, which is how most plans that
+ * are not numbered are written.
+ */
+export function parseSteps(markdown: string): PlanStep[] {
+  const lines = (markdown ?? "").split("\n");
+
+  const numbered: string[] = [];
+  const underHeading: string[] = [];
+  let inStepSection = false;
+
+  for (const line of lines) {
+    if (/^#{1,6}\s/.test(line)) {
+      inStepSection = STEP_HEADING.test(line) && !NON_STEP_HEADING.test(line);
+      continue;
+    }
+    if (/^\s*\d+[.)]\s+\S/.test(line)) {
+      // Only top-level numbers: an indented "1." is a detail of a step.
+      if (!/^\s{2,}/.test(line)) numbered.push(cleanStep(line));
+      continue;
+    }
+    if (inStepSection && /^\s*[-*+]\s+\S/.test(line) && !/^\s{2,}/.test(line)) {
+      underHeading.push(cleanStep(line));
+    }
+  }
+
+  const chosen = (numbered.length > 0 ? numbered : underHeading).filter(Boolean).slice(0, MAX_STEPS);
+  return chosen.map((text, i) => ({ index: i + 1, text, done: false }));
+}
+
+/** Merge parsed steps with what was already completed, matching on text. */
+export function mergeProgress(steps: PlanStep[], previous: PlanStep[]): PlanStep[] {
+  const doneText = new Set(previous.filter((s) => s.done).map((s) => s.text));
+  return steps.map((step) => ({ ...step, done: doneText.has(step.text) }));
+}
+
+export function nextStep(steps: PlanStep[]): PlanStep | null {
+  return steps.find((step) => !step.done) ?? null;
+}
+
+export interface CompleteResult {
+  steps: PlanStep[];
+  step: PlanStep | null;
+  error: string | null;
+}
+
+/**
+ * Mark a step done. Out-of-order completion is allowed but not silent: the
+ * caller reports which steps were skipped, since skipping is usually a
+ * mistake and occasionally the point.
+ */
+export function completeStep(steps: PlanStep[], index: number): CompleteResult {
+  const target = steps.find((step) => step.index === index);
+  if (!target) return { steps, step: null, error: `No step #${index} in the plan (it has ${steps.length}).` };
+  if (target.done) return { steps, step: target, error: `Step #${index} is already done.` };
+  return {
+    steps: steps.map((step) => (step.index === index ? { ...step, done: true } : step)),
+    step: target,
+    error: null,
+  };
+}
+
+export function skippedBefore(steps: PlanStep[], index: number): PlanStep[] {
+  return steps.filter((step) => step.index < index && !step.done);
+}
+
+export function progressLine(steps: PlanStep[]): string {
+  const done = steps.filter((s) => s.done).length;
+  return `${done}/${steps.length} steps`;
+}
+
+const MAX_WIDGET_STEPS = 8;
+
+/** Plain-text step list for a notify or a widget. */
+export function formatSteps(steps: PlanStep[], limit = MAX_WIDGET_STEPS): string {
+  if (steps.length === 0) return "No steps parsed from the plan.";
+  const current = nextStep(steps);
+  const start = current ? Math.max(0, Math.min(steps.length - limit, current.index - 1 - 2)) : 0;
+  const window = steps.slice(start, start + limit);
+  const lines = window.map((step) => {
+    const mark = step.done ? "✔" : step === current ? "▸" : "◻";
+    return `${mark} ${step.index}. ${step.text.length > 70 ? `${step.text.slice(0, 69)}…` : step.text}`;
+  });
+  if (start > 0) lines.unshift(`… +${start} above`);
+  const after = steps.length - start - window.length;
+  if (after > 0) lines.push(`… +${after} more`);
+  return [progressLine(steps), ...lines].join("\n");
+}

package/src/types.ts

@@ -3,6 +3,8 @@
  * No imports from pi packages: src/ typechecks and runs standalone.
  */
 
+import type { PlanStep } from "./steps.ts";
+
 export interface PlanState {
   active: boolean;
   /** Absolute path of the current plan file; edit/write to it is allowed. */
@@ -10,12 +12,15 @@ export interface PlanState {
   /** Thinking level to restore when leaving plan mode. */
   buildThinking: string | null;
   enteredAt: number | null;
+  /** Steps of the approved plan, tracked through execution (v0.3). */
+  steps: PlanStep[];
 }
 
 export const INITIAL_STATE: PlanState = {
   active: false,
   planFile: null,
   buildThinking: null,
+  steps: [],
   enteredAt: null,
 };