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

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

@@ -0,0 +1,118 @@
+/**
+ * Disk-backed active-plan resolution.
+ *
+ * `state.plan` is session-scoped: it is only populated when a plan is submitted
+ * in *this* session, restored from this session's entries, or handed off via
+ * the one-shot exec-pending file. But `.plans/<name>/tasks.jsonl` is the real
+ * source of truth, and execution routinely happens in a different session than
+ * planning. This bridges that gap: when nothing is attached in memory, resolve
+ * the plan from disk so `update_task` / `add_task` work without an interactive
+ * `/plan resume`.
+ *
+ * Attaching only loads the plan DATA into `state` (so tracking writes land in
+ * `tasks.jsonl`); it intentionally does NOT flip `executing` / tools / model —
+ * that stays the user's explicit choice via `/plan-exec` or `/plan resume`.
+ */
+
+import type { ExtensionAPI } from '@earendil-works/pi-coding-agent';
+import type { PlanModeState } from './state.js';
+import type { PlanData } from './types.js';
+import type { RunPlanIO } from './effects/runtime.js';
+import { readPlansManifest } from './storage/plans-manifest.js';
+import { readTasksJsonl } from './storage/task-storage.js';
+import { loadHandoff } from './storage/plan-storage.js';
+
+export interface ResolvedPlan {
+  /** The attached plan, when resolvable. Already written into `state`. */
+  plan?: PlanData;
+  /**
+   * In-progress plan names, surfaced when resolution was ambiguous (multiple
+   * in-progress and no usable `name` hint) or a hint missed. Lets a caller
+   * report actionable choices instead of dead-ending.
+   */
+  candidates: string[];
+}
+
+/** Normalize a plan hint (`my-plan` or `.plans/my-plan`) to a bare name. */
+function normalizeName(hint: string): string {
+  return hint
+    .replace(/^\.plans\//, '')
+    .replace(/\/+$/, '')
+    .trim();
+}
+
+/** Load `.plans/<name>` from disk into `state` (data only). Returns the plan,
+ *  or undefined when the tasks file is missing/empty. */
+async function attach(
+  state: PlanModeState,
+  pi: ExtensionAPI,
+  runPlanIO: RunPlanIO,
+  name: string,
+): Promise<PlanData | undefined> {
+  const dir = `.plans/${name}`;
+  const snapshot = await runPlanIO(readTasksJsonl(dir));
+  if (!snapshot) return undefined;
+  const plan: PlanData = {
+    title: snapshot.meta.title,
+    planName: snapshot.meta.plan_name,
+    handoff: (await runPlanIO(loadHandoff(dir))) ?? '',
+    tasks: snapshot.tasks,
+  };
+  state.plan = plan;
+  state.planDir = dir;
+  state.persist(pi);
+  return plan;
+}
+
+/**
+ * Resolve the active plan, attaching from disk when nothing is in memory.
+ *
+ * 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,
+  pi: ExtensionAPI,
+  runPlanIO: RunPlanIO,
+  opts: { name?: string } = {},
+): Promise<ResolvedPlan> {
+  // ── 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
+    // ambiguity report so the caller sees the valid choices.
+    if (match) {
+      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);
+    if (plan) return { plan, candidates: [] };
+  }
+
+  return { plan: undefined, candidates: inProgress.map((entry) => entry.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/add-task.ts

@@ -9,11 +9,13 @@
 import type { ExtensionAPI } from '@earendil-works/pi-coding-agent';
 import { Text } from '@earendil-works/pi-tui';
 import { Type } from 'typebox';
-import type { PlanData, TaskRecord } from '../types.js';
+import type { TaskRecord } from '../types.js';
+import type { ResolvedPlan } from '../resolve-plan.js';
 import { nextTaskId } from '../utils.js';
 
 export interface AddTaskCallbacks {
-  getPlan: () => PlanData | undefined;
+  /** Resolve the active plan, attaching from disk when none is in memory. */
+  resolvePlan: (opts?: { name?: string }) => Promise<ResolvedPlan>;
   onTaskAdded: (task: TaskRecord) => void | Promise<void>;
 }
 
@@ -38,11 +40,31 @@ export function registerAddTaskTool(pi: ExtensionAPI, callbacks: AddTaskCallback
         Type.String({ description: 'Optional fuller implementation notes for the follow-up' }),
       ),
       depends_on: Type.Optional(Type.Array(Type.String({ description: 'Dependency task ID' }))),
+      plan: Type.Optional(
+        Type.String({
+          description:
+            'Plan name (or .plans/<name>) to target. Only needed to disambiguate when multiple plans are in-progress.',
+        }),
+      ),
     }),
 
     async execute(_toolCallId, params) {
-      const plan = callbacks.getPlan();
-      if (!plan) throw new Error('No active plan. Cannot add a follow-up task.');
+      const { plan, candidates } = await callbacks.resolvePlan({ name: params.plan });
+      // No active plan is a tracking miss, not an error — return a soft,
+      // non-terminating result so real work continues.
+      if (!plan) {
+        const hint =
+          candidates.length > 1
+            ? ` Multiple in-progress plans (${candidates.join(', ')}) — pass { plan: "<name>" } to choose.`
+            : ' No in-progress plan found in .plans/plans.jsonl.';
+        const details: Record<string, unknown> = { skipped: true, candidates };
+        return {
+          content: [
+            { type: 'text' as const, text: `Skipped follow-up capture — no active plan.${hint}` },
+          ],
+          details,
+        };
+      }
 
       const now = new Date().toISOString();
       const task: TaskRecord = {

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

@@ -0,0 +1,155 @@
+/**
+ * plan_status tool — read-only snapshot of the active plan.
+ *
+ * Lets an agent proactively learn whether a plan is active, its progress, and
+ * the valid task ids — instead of discovering that by a failed `update_task`.
+ * Resolves disk-backed (attaches the sole in-progress plan), so it works in a
+ * fresh execution session. Pure read: never mutates plan state.
+ */
+
+import type { ExtensionAPI } from '@earendil-works/pi-coding-agent';
+import { Text } from '@earendil-works/pi-tui';
+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> = {
+  done: '✓',
+  skipped: '⊘',
+  blocked: '✗',
+  pending: '○',
+  deferred: '+',
+};
+
+export function registerPlanStatusTool(pi: ExtensionAPI, callbacks: PlanStatusCallbacks): void {
+  pi.registerTool({
+    name: 'plan_status',
+    label: 'Plan Status',
+    description:
+      'Read-only snapshot of the active plan: progress counts and every task id + status. Use to check whether a plan is active and what the valid task ids are before calling update_task.',
+    promptSnippet: 'Show the active plan: progress + task ids/statuses',
+    promptGuidelines: [
+      'Call plan_status when unsure whether a plan is active or which task ids exist — it is read-only and never mutates state.',
+      'Prefer it over guessing task ids; the returned ids are what update_task expects.',
+    ],
+    parameters: Type.Object({
+      plan: Type.Optional(
+        Type.String({
+          description:
+            'Plan name (or .plans/<name>) to inspect. Only needed to disambiguate when multiple plans are in-progress.',
+        }),
+      ),
+    }),
+
+    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>" }.`
+            : ' No in-progress plan found in .plans/plans.jsonl.';
+        const noPlanDetails: Record<string, unknown> = { active: false, candidates };
+        return {
+          content: [{ type: 'text' as const, text: `No active plan.${hint}` }],
+          details: noPlanDetails,
+        };
+      }
+
+      const counts: Record<TaskStatus, number> = {
+        done: 0,
+        skipped: 0,
+        blocked: 0,
+        pending: 0,
+        deferred: 0,
+      };
+      for (const task of plan.tasks) counts[task.status] += 1;
+      const resolved = counts.done + counts.skipped;
+
+      const parts = [
+        `done ${counts.done}`,
+        `skipped ${counts.skipped}`,
+        `pending ${counts.pending}`,
+      ];
+      if (counts.blocked) parts.push(`blocked ${counts.blocked}`);
+      if (counts.deferred) parts.push(`follow-up ${counts.deferred}`);
+
+      const lines = plan.tasks.map(
+        (task) => `  ${STATUS_GLYPH[task.status]} ${task.id} [${task.status}] ${task.description}`,
+      );
+      const text =
+        `Plan: ${plan.title} (${plan.planName})\n` +
+        `Progress: ${resolved}/${plan.tasks.length} resolved — ${parts.join(', ')}\n` +
+        `Tasks:\n${lines.join('\n')}`;
+
+      return {
+        content: [{ type: 'text' as const, text }],
+        details: {
+          active: true,
+          plan_name: plan.planName,
+          title: plan.title,
+          total: plan.tasks.length,
+          counts,
+          task_ids: plan.tasks.map((task) => task.id),
+        },
+      };
+    },
+
+    renderCall(args, theme) {
+      const name = (args as { plan?: string }).plan;
+      let content = theme.fg('toolTitle', theme.bold('plan_status'));
+      if (name) content += ' ' + theme.fg('muted', name);
+      return new Text(content, 0, 0);
+    },
+
+    renderResult(result, _options, theme) {
+      const details = result.details as
+        | { active?: boolean; plan_name?: string; total?: number; counts?: Record<string, number> }
+        | undefined;
+      if (!details?.active) return new Text(theme.fg('dim', 'No active plan'), 0, 0);
+      const resolved = (details.counts?.done ?? 0) + (details.counts?.skipped ?? 0);
+      return new Text(
+        theme.fg('toolTitle', `${details.plan_name ?? 'plan'} `) +
+          theme.fg('muted', `${resolved}/${details.total ?? 0} resolved`),
+        0,
+        0,
+      );
+    },
+  });
+}