@dreki-gg/pi-plan-mode 0.18.0 → 0.19.0

package/extensions/plan-mode/__tests__/schema.test.ts

@@ -177,6 +177,25 @@ describe('plan manifest entry schema', () => {
     ).toBe(true);
   });
 
+  test('accepts terminal statuses (superseded / abandoned) with a reason', () => {
+    for (const status of ['done', 'superseded', 'abandoned'] as const) {
+      expect(
+        isOk(
+          {
+            _type: 'plan',
+            name: 'plan',
+            status,
+            title: 'Plan',
+            created_at: now,
+            completed_at: now,
+            reason: 'another plan shipped it',
+          },
+          decodePlanManifestEntry,
+        ),
+      ).toBe(true);
+    }
+  });
+
   test('rejects an invalid status', () => {
     expect(
       isOk(

package/extensions/plan-mode/__tests__/update-plan.test.ts

@@ -0,0 +1,69 @@
+import { afterEach, beforeEach, describe, expect, test } from 'bun:test';
+import { chdir } from 'node:process';
+import { mkdtemp, rm } from 'node:fs/promises';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+import { makePlanRuntime } from '../effects/runtime.js';
+import { readPlansManifest, upsertPlanEntry } from '../storage/plans-manifest.js';
+import { registerUpdatePlanTool } from '../tools/update-plan.js';
+
+const runPlanIO = makePlanRuntime();
+
+interface CapturedTool {
+  execute: (
+    id: string,
+    params: { plan: string; status: string; reason?: string },
+  ) => Promise<{ content?: Array<{ text: string }>; details?: unknown }>;
+}
+
+function setup(): CapturedTool {
+  let tool: CapturedTool | undefined;
+  const pi = {
+    registerTool: (config: CapturedTool) => {
+      tool = config;
+    },
+  } as unknown as Parameters<typeof registerUpdatePlanTool>[0];
+  registerUpdatePlanTool(pi, runPlanIO);
+  return tool!;
+}
+
+const originalCwd = process.cwd();
+let dir: string;
+beforeEach(async () => {
+  dir = await mkdtemp(join(tmpdir(), 'plan-mode-update-plan-'));
+  chdir(dir);
+});
+afterEach(async () => {
+  chdir(originalCwd);
+  await rm(dir, { recursive: true, force: true });
+});
+
+describe('update_plan tool', () => {
+  test('closes a plan as superseded with a reason', async () => {
+    await runPlanIO(upsertPlanEntry('p', { status: 'in-progress', title: 'P' }));
+    const tool = setup();
+    const result = await tool.execute('c', {
+      plan: 'p',
+      status: 'superseded',
+      reason: 'absorbed by q',
+    });
+    expect(result.content?.[0]?.text).toMatch(/in-progress → superseded/);
+    const [entry] = await runPlanIO(readPlansManifest());
+    expect(entry.status).toBe('superseded');
+    expect(entry.reason).toBe('absorbed by q');
+  });
+
+  test('accepts a .plans/<name> hint', async () => {
+    await runPlanIO(upsertPlanEntry('p', { status: 'in-progress', title: 'P' }));
+    const tool = setup();
+    await tool.execute('c', { plan: '.plans/p', status: 'abandoned', reason: 'rejected' });
+    const [entry] = await runPlanIO(readPlansManifest());
+    expect(entry.status).toBe('abandoned');
+  });
+
+  test('reports not_found for an unknown plan (no throw)', async () => {
+    const tool = setup();
+    const result = await tool.execute('c', { plan: 'ghost', status: 'done' });
+    expect((result.details as { error?: string }).error).toBe('not_found');
+  });
+});

package/extensions/plan-mode/constants.ts

@@ -16,6 +16,8 @@ export const PLAN_TOOLS = [
   'search_skills',
   'subagent',
   'plan_status',
+  'update_plan',
+  'reconcile_plans',
 ];
 
 export const EXEC_TOOLS = [
@@ -26,6 +28,8 @@ export const EXEC_TOOLS = [
   'update_task',
   'add_task',
   'plan_status',
+  'update_plan',
+  'reconcile_plans',
 ];
 
 // ── Model + thinking presets ─────────────────────────────────────────────────

package/extensions/plan-mode/index.ts

@@ -31,19 +31,22 @@ import { PlanModeState } from './state.js';
 import { makePlanRuntime } from './effects/runtime.js';
 import { loadHandoff, readAndClearExecPending } from './storage/plan-storage.js';
 import { readTasksJsonl, writeTasksJsonl } from './storage/task-storage.js';
-import { upsertPlanEntry } from './storage/plans-manifest.js';
+import { upsertPlanEntry, reconcilePlanStatus } from './storage/plans-manifest.js';
 import { updateUI } from './ui.js';
 import { buildPlanModePrompt, buildExecutionPrompt } from './prompts.js';
 import { filterExecutionMessages, filterStalePlanMessages } from './context-filter.js';
-import { activeTasksResolved, deferredTasks } from './task-status.js';
+import { activeTasksResolved, deferredTasks, isPlanFinalizable } from './task-status.js';
 import { enterPlanMode, exitPlanMode, switchModel } from './phase-transitions.js';
 import { resumePlan, executeInNewSession } from './resume.js';
 import { resolveActivePlan } from './resolve-plan.js';
+import { collectPlanDrift } from './reconcile.js';
 import { registerSubmitPlanTool } from './tools/submit-plan.js';
 import { registerPreviewPrototypeTool } from './tools/preview-prototype.js';
 import { registerUpdateTaskTool } from './tools/update-task.js';
 import { registerAddTaskTool } from './tools/add-task.js';
 import { registerPlanStatusTool } from './tools/plan-status.js';
+import { registerUpdatePlanTool } from './tools/update-plan.js';
+import { registerReconcilePlansTool } from './tools/reconcile-plans.js';
 import { isSafeCommand, isPlanPath } from './utils.js';
 
 export default function planMode(pi: ExtensionAPI): void {
@@ -90,14 +93,38 @@ export default function planMode(pi: ExtensionAPI): void {
           state.plan.tasks,
         ),
       );
+      // FEEDBACK #1: registry status is a projection of task state. Re-derive it
+      // on every task write so completion is decoupled from in-session execution
+      // — cross-session / disk-tracked `update_task` now closes the plan too.
+      await runPlanIO(
+        reconcilePlanStatus(
+          state.plan.planName,
+          isPlanFinalizable(state.plan.tasks),
+          state.plan.title,
+        ),
+      );
       state.persist(pi);
     },
   });
 
   registerPlanStatusTool(pi, {
     resolvePlan: (opts) => resolveActivePlan(state, pi, runPlanIO, opts),
+    listInProgress: async () => {
+      const rows = await runPlanIO(collectPlanDrift());
+      return rows
+        .filter((row) => row.registryStatus === 'in-progress')
+        .map((row) => ({
+          name: row.name,
+          title: row.title ?? row.name,
+          resolved: row.resolved ?? 0,
+          total: row.total ?? 0,
+        }));
+    },
   });
 
+  registerUpdatePlanTool(pi, runPlanIO);
+  registerReconcilePlansTool(pi, runPlanIO);
+
   registerAddTaskTool(pi, {
     resolvePlan: (opts) => resolveActivePlan(state, pi, runPlanIO, opts),
     onTaskAdded: async (task) => {
@@ -115,6 +142,15 @@ export default function planMode(pi: ExtensionAPI): void {
           state.plan.tasks,
         ),
       );
+      // A new deferred follow-up means the plan is no longer finalizable: re-open
+      // it in the registry if it had been auto-marked done.
+      await runPlanIO(
+        reconcilePlanStatus(
+          state.plan.planName,
+          isPlanFinalizable(state.plan.tasks),
+          state.plan.title,
+        ),
+      );
       state.persist(pi);
     },
   });
@@ -122,13 +158,33 @@ export default function planMode(pi: ExtensionAPI): void {
   // ── Commands ──────────────────────────────────────────────────────────────
   pi.registerCommand('plan', {
     description:
-      'Enter plan mode, optionally with a starting prompt. Use "/plan resume" to pick up an existing plan.',
+      'Enter plan mode, optionally with a starting prompt. "/plan resume" picks up an existing plan; "/plan focus <name>" pins the active plan for tracking calls.',
     handler: async (args, ctx) => {
       const trimmed = args?.trim();
       if (trimmed === 'resume') {
         await resumePlan(state, pi, ctx, runPlanIO);
         return;
       }
+      // "/plan focus <name>" — pin a plan so update_task / add_task / plan_status
+      // default to it without repeating { plan: "<name>" } on every call (#5).
+      if (trimmed?.startsWith('focus')) {
+        const name = trimmed.slice('focus'.length).trim();
+        if (!name) {
+          ctx.ui.notify('Usage: /plan focus <name>', 'info');
+          return;
+        }
+        // Clear any stale in-memory plan so the hint re-attaches from disk.
+        state.plan = undefined;
+        state.planDir = undefined;
+        const { plan, candidates } = await resolveActivePlan(state, pi, runPlanIO, { name });
+        if (plan) {
+          ctx.ui.notify(`Focused plan: ${plan.title} (${plan.planName})`, 'info');
+        } else {
+          const hint = candidates.length ? ` In-progress: ${candidates.join(', ')}.` : '';
+          ctx.ui.notify(`No plan named "${name}".${hint}`, 'error');
+        }
+        return;
+      }
       if (state.planEnabled || state.executing) {
         await exitPlanMode(state, pi, ctx);
         return;

package/extensions/plan-mode/reconcile.ts

@@ -0,0 +1,141 @@
+/**
+ * Drift detection + repair between `tasks.jsonl` reality and registry status.
+ *
+ * Drift happens in both directions (FEEDBACK #6):
+ *   - tasks all done but registry `in-progress` (completion never recorded), and
+ *   - registry `in-progress`/`done` disagreeing with task state generally.
+ *
+ * It also surfaces two un-trackable classes:
+ *   - registry-only plans (an entry with no `tasks.jsonl` directory), and
+ *   - orphan task dirs (a `tasks.jsonl` with no registry entry).
+ *
+ * `collectPlanDrift` is a pure read; `applyReconcile` repairs only the safe
+ * `in-progress` ⇄ `done` projection and never touches terminal statuses.
+ */
+
+import { Effect } from 'effect';
+import { FileSystem } from './effects/filesystem.js';
+import type {
+  JsonlParseError,
+  JsonlValidationError,
+  MissingMetaRecord,
+  PlanWriteError,
+} from './errors.js';
+import { readPlansManifest, reconcilePlanStatus } from './storage/plans-manifest.js';
+import { readTasksJsonl } from './storage/task-storage.js';
+import { isPlanFinalizable } from './task-status.js';
+import type { PlanStatus } from './types.js';
+
+const PLANS_DIR = '.plans';
+
+export interface PlanDriftRow {
+  name: string;
+  /** Registry status, or `undefined` when there is a task dir but no entry. */
+  registryStatus?: PlanStatus;
+  title?: string;
+  /** Derived from tasks: `done` when finalizable, else `in-progress`. */
+  derivedStatus?: 'in-progress' | 'done';
+  /** Resolved/total task counts when a tasks.jsonl exists. */
+  resolved?: number;
+  total?: number;
+  /** True when a `tasks.jsonl` snapshot was found for this plan. */
+  hasTasks: boolean;
+  /**
+   * Drift class:
+   *   - 'status'        : registry status disagrees with derived task status
+   *   - 'registry-only' : registry entry but no tasks.jsonl dir
+   *   - 'orphan'        : tasks.jsonl dir but no registry entry
+   *   - undefined       : in sync
+   */
+  drift?: 'status' | 'registry-only' | 'orphan';
+}
+
+type CollectError = JsonlParseError | JsonlValidationError | MissingMetaRecord;
+
+/** Walk every plan (registry + task dirs) and classify drift. Pure read. */
+export function collectPlanDrift(): Effect.Effect<PlanDriftRow[], CollectError, FileSystem> {
+  return Effect.gen(function* () {
+    const fs = yield* FileSystem;
+    const manifest = yield* readPlansManifest();
+    const dirs = yield* Effect.orElseSucceed(fs.listDirectories(PLANS_DIR), () => [] as string[]);
+    // Ignore dotfile dirs like `.archive`.
+    const taskDirs = new Set(dirs.filter((name) => !name.startsWith('.')));
+
+    const rows: PlanDriftRow[] = [];
+    const seen = new Set<string>();
+
+    for (const entry of manifest) {
+      seen.add(entry.name);
+      const snapshot = yield* readTasksJsonl(`${PLANS_DIR}/${entry.name}`);
+      if (!snapshot) {
+        rows.push({
+          name: entry.name,
+          registryStatus: entry.status,
+          title: entry.title,
+          hasTasks: false,
+          drift: 'registry-only',
+        });
+        continue;
+      }
+      const total = snapshot.tasks.length;
+      const resolved = snapshot.tasks.filter(
+        (t) => t.status === 'done' || t.status === 'skipped',
+      ).length;
+      const derivedStatus = isPlanFinalizable(snapshot.tasks) ? 'done' : 'in-progress';
+      // Terminal statuses (superseded/abandoned) are intentional — never drift.
+      const isTerminalManual = entry.status === 'superseded' || entry.status === 'abandoned';
+      const drift = !isTerminalManual && entry.status !== derivedStatus ? 'status' : undefined;
+      rows.push({
+        name: entry.name,
+        registryStatus: entry.status,
+        title: entry.title,
+        derivedStatus,
+        resolved,
+        total,
+        hasTasks: true,
+        drift,
+      });
+    }
+
+    // Orphan task dirs: have tasks.jsonl but no registry entry.
+    for (const name of taskDirs) {
+      if (seen.has(name)) continue;
+      const snapshot = yield* readTasksJsonl(`${PLANS_DIR}/${name}`);
+      if (!snapshot) continue;
+      const total = snapshot.tasks.length;
+      const resolved = snapshot.tasks.filter(
+        (t) => t.status === 'done' || t.status === 'skipped',
+      ).length;
+      rows.push({
+        name,
+        title: snapshot.meta.title,
+        derivedStatus: isPlanFinalizable(snapshot.tasks) ? 'done' : 'in-progress',
+        resolved,
+        total,
+        hasTasks: true,
+        drift: 'orphan',
+      });
+    }
+
+    return rows;
+  });
+}
+
+/**
+ * Repair `status`-class drift by projecting derived status into the registry.
+ * Orphans and registry-only rows are reported but not auto-fixed (they need a
+ * human decision). Returns the rows that were repaired.
+ */
+export function applyReconcile(
+  rows: PlanDriftRow[],
+): Effect.Effect<PlanDriftRow[], CollectError | PlanWriteError, FileSystem> {
+  return Effect.gen(function* () {
+    const repaired: PlanDriftRow[] = [];
+    for (const row of rows) {
+      if (row.drift !== 'status' || !row.derivedStatus) continue;
+      yield* reconcilePlanStatus(row.name, row.derivedStatus === 'done', row.title);
+      repaired.push(row);
+    }
+    return repaired;
+  });
+}

package/extensions/plan-mode/resolve-plan.ts

@@ -67,10 +67,17 @@ async function attach(
 /**
  * Resolve the active plan, attaching from disk when nothing is in memory.
  *
- * Order: in-memory `state.plan` → explicit `name` hint → the single
+ * Order: explicit `name` hint → in-memory `state.plan` → the single
  * in-progress plan in `.plans/plans.jsonl`. Ambiguous (multiple in-progress,
  * no hint) returns `{ plan: undefined, candidates }` so the caller can prompt
  * for a `name`.
+ *
+ * IMPORTANT (FEEDBACK #7): an explicit `name` hint ALWAYS wins over the
+ * in-memory `state.plan`. Previously `state.plan` short-circuited first, so a
+ * deliberate `{ plan: '<other>' }` was silently ignored and writes landed in
+ * whatever plan the last `submit_plan` attached — a data-corruption path. The
+ * hint is now resolved first; when it names a different plan we re-attach from
+ * disk so subsequent writes target the right `tasks.jsonl`.
  */
 export async function resolveActivePlan(
   state: PlanModeState,
@@ -78,12 +85,13 @@ export async function resolveActivePlan(
   runPlanIO: RunPlanIO,
   opts: { name?: string } = {},
 ): Promise<ResolvedPlan> {
-  if (state.plan) return { plan: state.plan, candidates: [] };
-
-  const manifest = await runPlanIO(readPlansManifest());
-
+  // ── Explicit hint wins, even over an attached in-memory plan ──────────────
   if (opts.name) {
     const hint = normalizeName(opts.name);
+    // Already the attached plan? Return the in-memory copy (freshest task state).
+    if (state.plan && state.plan.planName === hint) return { plan: state.plan, candidates: [] };
+
+    const manifest = await runPlanIO(readPlansManifest());
     const match = manifest.find((entry) => entry.name === hint);
     // A hint that names a real plan attaches regardless of status (the caller
     // asked for it explicitly); a hint that names nothing falls through to the
@@ -92,8 +100,14 @@ export async function resolveActivePlan(
       const plan = await attach(state, pi, runPlanIO, match.name);
       if (plan) return { plan, candidates: [] };
     }
+    const inProgress = manifest.filter((entry) => entry.status === 'in-progress');
+    return { plan: undefined, candidates: inProgress.map((entry) => entry.name) };
   }
 
+  // ── No hint: in-memory plan, else the single in-progress plan on disk ─────
+  if (state.plan) return { plan: state.plan, candidates: [] };
+
+  const manifest = await runPlanIO(readPlansManifest());
   const inProgress = manifest.filter((entry) => entry.status === 'in-progress');
   if (inProgress.length === 1) {
     const plan = await attach(state, pi, runPlanIO, inProgress[0]!.name);

package/extensions/plan-mode/schema.ts

@@ -36,13 +36,25 @@ export const TaskMetaSchema = Schema.Struct({
 /** A single tasks.jsonl line is either the meta record or a task record. */
 export const TasksLineSchema = Schema.Union(TaskMetaSchema, TaskRecordSchema);
 
+/**
+ * Plan lifecycle statuses.
+ *   - in-progress: active, tracked, eligible for auto-resolution
+ *   - done:        completed (all tasks resolved)
+ *   - superseded:  closed because another plan absorbed the work
+ *   - abandoned:   closed without shipping (rejected / won't do)
+ * Only `in-progress` is treated as active; the rest are terminal.
+ */
+export const PlanStatusSchema = Schema.Literal('in-progress', 'done', 'superseded', 'abandoned');
+
 export const PlanManifestEntrySchema = Schema.Struct({
   _type: Schema.Literal('plan'),
   name: Schema.String,
-  status: Schema.Literal('in-progress', 'done'),
+  status: PlanStatusSchema,
   title: Schema.String,
   created_at: Schema.String,
   completed_at: Schema.NullOr(Schema.String),
+  /** Optional human-readable reason, used for terminal statuses. */
+  reason: Schema.optional(Schema.String),
 });
 
 export const ExecPendingConfigSchema = Schema.Struct({

package/extensions/plan-mode/storage/plans-manifest.ts

@@ -2,6 +2,7 @@ import { Effect, Either, Option } from 'effect';
 import { FileSystem } from '../effects/filesystem.js';
 import { JsonlParseError, JsonlValidationError, PlanWriteError } from '../errors.js';
 import { decodePlanManifestEntry } from '../schema.js';
+import type { PlanStatus } from '../types.js';
 
 const MANIFEST_DIR = '.plans';
 const MANIFEST_PATH = '.plans/plans.jsonl';
@@ -9,10 +10,16 @@ const MANIFEST_PATH = '.plans/plans.jsonl';
 export interface PlanManifestEntry {
   _type: 'plan';
   name: string;
-  status: 'in-progress' | 'done';
+  status: PlanStatus;
   title: string;
   created_at: string;
   completed_at: string | null;
+  reason?: string;
+}
+
+/** A status is terminal (closed) when it is anything other than in-progress. */
+export function isTerminalStatus(status: PlanStatus): boolean {
+  return status !== 'in-progress';
 }
 
 type ReadError = JsonlParseError | JsonlValidationError;
@@ -62,7 +69,7 @@ export function writePlansManifest(
 
 export function upsertPlanEntry(
   name: string,
-  updates: { status: 'in-progress' | 'done'; title?: string },
+  updates: { status: PlanStatus; title?: string; reason?: string },
 ): Effect.Effect<void, ReadError | PlanWriteError, FileSystem> {
   return Effect.gen(function* () {
     const entries = yield* readPlansManifest();
@@ -75,10 +82,42 @@ export function upsertPlanEntry(
       status: updates.status,
       title: updates.title ?? existing?.title ?? 'Untitled plan',
       created_at: existing?.created_at ?? now,
-      completed_at: updates.status === 'done' ? now : null,
+      // Terminal statuses record a completion timestamp; reopening clears it.
+      completed_at: isTerminalStatus(updates.status) ? (existing?.completed_at ?? now) : null,
+      reason: updates.reason ?? existing?.reason,
     };
     if (index === -1) entries.push(entry);
     else entries[index] = entry;
     yield* writePlansManifest(entries);
   });
 }
+
+/**
+ * Reconcile a plan's registry status from its task state.
+ *
+ * The registry `status` is a PROJECTION of task state, not a parallel flag.
+ * Call this wherever tasks are written so completion is never coupled to a
+ * formal in-session execution run (see FEEDBACK #1). `finalizable` means every
+ * active task is resolved AND no deferred follow-ups remain.
+ *
+ * Guard: a manually-set terminal status (`superseded` / `abandoned`) is never
+ * auto-overridden — only `in-progress` ⇄ `done` is derived from tasks.
+ */
+export function reconcilePlanStatus(
+  name: string,
+  finalizable: boolean,
+  title?: string,
+): Effect.Effect<void, ReadError | PlanWriteError, FileSystem> {
+  return Effect.gen(function* () {
+    const entries = yield* readPlansManifest();
+    const existing = entries.find((entry) => entry.name === name);
+    // Reconcile only reflects task state for KNOWN plans; never conjure an
+    // entry for an unregistered plan (orphans are surfaced, not auto-created).
+    if (!existing) return;
+    // Do not resurrect / clobber an explicitly closed plan.
+    if (existing.status === 'superseded' || existing.status === 'abandoned') return;
+    const status: PlanStatus = finalizable ? 'done' : 'in-progress';
+    if (existing.status === status) return; // no change
+    yield* upsertPlanEntry(name, { status, title });
+  });
+}

package/extensions/plan-mode/tools/plan-status.ts

@@ -13,9 +13,22 @@ import { Type } from 'typebox';
 import type { TaskStatus } from '../types.js';
 import type { ResolvedPlan } from '../resolve-plan.js';
 
+export interface InProgressSummary {
+  name: string;
+  title: string;
+  resolved: number;
+  total: number;
+}
+
 export interface PlanStatusCallbacks {
   /** Resolve the active plan, attaching from disk when none is in memory. */
   resolvePlan: (opts?: { name?: string }) => Promise<ResolvedPlan>;
+  /**
+   * List every in-progress plan with progress counts. Used to render a
+   * progress-at-a-glance table when no single plan can be resolved
+   * (multiple in-progress) — surfaces drift (e.g. a 17/17 plan still listed).
+   */
+  listInProgress?: () => Promise<InProgressSummary[]>;
 }
 
 const STATUS_GLYPH: Record<TaskStatus, string> = {
@@ -49,6 +62,25 @@ export function registerPlanStatusTool(pi: ExtensionAPI, callbacks: PlanStatusCa
     async execute(_toolCallId, params) {
       const { plan, candidates } = await callbacks.resolvePlan({ name: params.plan });
       if (!plan) {
+        // Multiple in-progress plans: show a progress-at-a-glance table rather
+        // than a bare name list (FEEDBACK #5). The counts surface drift too —
+        // a fully-resolved plan still listed in-progress is a reconcile cue.
+        if (candidates.length > 1 && callbacks.listInProgress) {
+          const summaries = await callbacks.listInProgress();
+          const rows = summaries
+            .map((s) => {
+              const flag = s.total > 0 && s.resolved === s.total ? '  ⚠ done?' : '';
+              return `  ${s.resolved}/${s.total}  ${s.name} — ${s.title}${flag}`;
+            })
+            .join('\n');
+          const text =
+            `No single active plan — ${summaries.length} in-progress. Pass { plan: "<name>" } to target one.\n` +
+            `Progress:\n${rows}`;
+          return {
+            content: [{ type: 'text' as const, text }],
+            details: { active: false, candidates, in_progress: summaries },
+          };
+        }
         const hint =
           candidates.length > 1
             ? ` In-progress plans: ${candidates.join(', ')} — pass { plan: "<name>" }.`