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

package/extensions/plan-mode/tools/reconcile-plans.ts

@@ -0,0 +1,118 @@
+/**
+ * reconcile_plans tool — detect & repair drift between tasks and registry.
+ *
+ * Walks every plan, compares the registry `status` against the status derived
+ * from `tasks.jsonl`, and reports the diff (FEEDBACK #6). With `apply: true` it
+ * repairs the safe `in-progress` ⇄ `done` projection; orphans and
+ * registry-only plans are surfaced for a human decision but never auto-changed.
+ */
+
+import type { ExtensionAPI } from '@earendil-works/pi-coding-agent';
+import { Text } from '@earendil-works/pi-tui';
+import { Type } from 'typebox';
+import type { RunPlanIO } from '../effects/runtime.js';
+import { applyReconcile, collectPlanDrift, type PlanDriftRow } from '../reconcile.js';
+
+function describeRow(row: PlanDriftRow): string {
+  const progress = row.hasTasks ? ` (${row.resolved}/${row.total})` : '';
+  if (row.drift === 'registry-only') {
+    return `  ⚠ ${row.name} — registry ${row.registryStatus}, no tasks.jsonl (un-trackable)`;
+  }
+  if (row.drift === 'orphan') {
+    return `  ⚠ ${row.name}${progress} — tasks.jsonl with no registry entry (orphan)`;
+  }
+  if (row.drift === 'status') {
+    return `  ✗ ${row.name}${progress} — registry ${row.registryStatus}, tasks say ${row.derivedStatus}`;
+  }
+  return `  ✓ ${row.name}${progress} — ${row.registryStatus} (in sync)`;
+}
+
+export function registerReconcilePlansTool(pi: ExtensionAPI, runPlanIO: RunPlanIO): void {
+  pi.registerTool({
+    name: 'reconcile_plans',
+    label: 'Reconcile Plans',
+    description:
+      'Walk every plan and report where the registry status disagrees with task state (drift), plus orphan task dirs and registry-only plans. Pass apply:true to repair safe in-progress↔done drift.',
+    promptSnippet: 'Detect/repair drift between tasks.jsonl and the plan registry',
+    promptGuidelines: [
+      'Use reconcile_plans to audit .plans/ when registry status looks stale (e.g. a fully-done plan still in-progress).',
+      'Run it read-only first; pass apply:true once you have reviewed the reported drift.',
+    ],
+    parameters: Type.Object({
+      apply: Type.Optional(
+        Type.Boolean({
+          description: 'Repair status-drift by projecting derived task status into the registry.',
+        }),
+      ),
+    }),
+
+    async execute(_toolCallId, params) {
+      const rows = await runPlanIO(collectPlanDrift());
+      const drifted = rows.filter((row) => row.drift);
+
+      let repaired: PlanDriftRow[] = [];
+      if (params.apply) {
+        repaired = await runPlanIO(applyReconcile(rows));
+      }
+
+      const lines = rows.map(describeRow);
+      const statusDrift = drifted.filter((r) => r.drift === 'status').length;
+      const orphans = drifted.filter((r) => r.drift === 'orphan').length;
+      const registryOnly = drifted.filter((r) => r.drift === 'registry-only').length;
+
+      const header = params.apply
+        ? `Reconciled ${repaired.length} plan(s).`
+        : drifted.length === 0
+          ? 'All plans in sync.'
+          : `${drifted.length} drift issue(s) found (run with apply:true to repair status drift).`;
+
+      const summary = [
+        `status-drift ${statusDrift}`,
+        `orphan ${orphans}`,
+        `registry-only ${registryOnly}`,
+      ].join(', ');
+
+      const text = `${header}\n${summary}\n${lines.join('\n')}`;
+      return {
+        content: [{ type: 'text' as const, text }],
+        details: {
+          applied: Boolean(params.apply),
+          repaired: repaired.map((r) => r.name),
+          drift: drifted.map((r) => ({ name: r.name, kind: r.drift })),
+          total: rows.length,
+        },
+      };
+    },
+
+    renderCall(args, theme) {
+      const apply = (args as { apply?: boolean }).apply;
+      let content = theme.fg('toolTitle', theme.bold('reconcile_plans'));
+      if (apply) content += ' ' + theme.fg('warning', 'apply');
+      return new Text(content, 0, 0);
+    },
+
+    renderResult(result, _options, theme) {
+      const details = result.details as
+        | { applied?: boolean; repaired?: string[]; drift?: unknown[]; total?: number }
+        | undefined;
+      if (!details) return new Text(theme.fg('dim', 'Reconciled'), 0, 0);
+      const driftCount = details.drift?.length ?? 0;
+      if (details.applied) {
+        return new Text(
+          theme.fg('success', `✓ repaired ${details.repaired?.length ?? 0}`) +
+            theme.fg('muted', ` / ${details.total ?? 0} plans`),
+          0,
+          0,
+        );
+      }
+      return new Text(
+        driftCount === 0
+          ? theme.fg('success', `✓ ${details.total ?? 0} plans in sync`)
+          : theme.fg('warning', `${driftCount} drift`) +
+              theme.fg('muted', ` / ${details.total ?? 0} plans`),
+        0,
+        0,
+      );
+    },
+  });
+}

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

@@ -0,0 +1,123 @@
+/**
+ * update_plan tool — plan-level lifecycle control.
+ *
+ * `update_task` tracks task status; this is its plan-level counterpart
+ * (FEEDBACK #2/#3). It lets an agent or user close a plan without a full
+ * execution run or hand-editing `.plans/plans.jsonl`:
+ *   - done       — completed (work shipped)
+ *   - superseded — another plan absorbed the work
+ *   - abandoned  — won't do / rejected
+ *   - in-progress — reopen
+ * `reason` is recorded for honest history (esp. superseded/abandoned).
+ */
+
+import type { ExtensionAPI } from '@earendil-works/pi-coding-agent';
+import { StringEnum } from '@earendil-works/pi-ai';
+import { Text } from '@earendil-works/pi-tui';
+import { Type } from 'typebox';
+import type { PlanStatus } from '../types.js';
+import type { RunPlanIO } from '../effects/runtime.js';
+import { readPlansManifest, upsertPlanEntry } from '../storage/plans-manifest.js';
+
+/** 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();
+}
+
+export function registerUpdatePlanTool(pi: ExtensionAPI, runPlanIO: RunPlanIO): void {
+  pi.registerTool({
+    name: 'update_plan',
+    label: 'Update Plan',
+    description:
+      'Set a plan-level status (done, superseded, abandoned, or reopen to in-progress) with an optional reason. Use to close a plan without a full execution run instead of hand-editing the registry.',
+    promptSnippet: 'Close or reopen a plan (done/superseded/abandoned/in-progress) with a reason',
+    promptGuidelines: [
+      'Use update_plan to close a plan that will not be executed to completion: superseded (another plan shipped it) or abandoned (rejected / won\u2019t do).',
+      'Always pass a reason for superseded/abandoned so the registry keeps honest history.',
+      'Prefer update_task for per-task progress; update_plan is for the whole plan\u2019s lifecycle.',
+    ],
+    parameters: Type.Object({
+      plan: Type.String({ description: 'Plan name (or .plans/<name>) to update' }),
+      status: StringEnum(['in-progress', 'done', 'superseded', 'abandoned'] as const),
+      reason: Type.Optional(
+        Type.String({ description: 'Why — recorded in the registry (esp. superseded/abandoned)' }),
+      ),
+    }),
+
+    async execute(_toolCallId, params) {
+      const name = normalizeName(params.plan);
+      const manifest = await runPlanIO(readPlansManifest());
+      const existing = manifest.find((entry) => entry.name === name);
+      if (!existing) {
+        const names = manifest.map((entry) => entry.name).join(', ');
+        const notFound: Record<string, unknown> = { error: 'not_found', plan: name };
+        return {
+          content: [
+            {
+              type: 'text' as const,
+              text: `Plan not found: ${name}. Known plans: ${names || '(none)'}`,
+            },
+          ],
+          details: notFound,
+        };
+      }
+
+      await runPlanIO(
+        upsertPlanEntry(name, {
+          status: params.status as PlanStatus,
+          title: existing.title,
+          reason: params.reason,
+        }),
+      );
+
+      const reasonSuffix = params.reason ? ` — ${params.reason}` : '';
+      const okDetails: Record<string, unknown> = {
+        plan: name,
+        from: existing.status,
+        status: params.status,
+        reason: params.reason,
+      };
+      return {
+        content: [
+          {
+            type: 'text' as const,
+            text: `Plan ${name}: ${existing.status} → ${params.status}${reasonSuffix}`,
+          },
+        ],
+        details: okDetails,
+      };
+    },
+
+    renderCall(args, theme) {
+      const name = (args as { plan?: string }).plan ?? 'plan';
+      const status = (args as { status?: string }).status ?? '';
+      let content = theme.fg('toolTitle', theme.bold('update_plan '));
+      content += theme.fg('accent', name);
+      if (status) content += ' ' + theme.fg('muted', status);
+      return new Text(content, 0, 0);
+    },
+
+    renderResult(result, _options, theme) {
+      const details = result.details as
+        | { plan?: string; from?: string; status?: string }
+        | undefined;
+      if (!details?.status) return new Text(theme.fg('dim', 'Plan updated'), 0, 0);
+      const color =
+        details.status === 'done'
+          ? 'success'
+          : details.status === 'in-progress'
+            ? 'accent'
+            : 'warning';
+      return new Text(
+        theme.fg('muted', `${details.plan ?? 'plan'} `) +
+          theme.fg('dim', `${details.from ?? ''} → `) +
+          theme.fg(color, details.status),
+        0,
+        0,
+      );
+    },
+  });
+}

package/extensions/plan-mode/tools/update-task.ts

@@ -6,10 +6,12 @@ import type { ExtensionAPI } from '@earendil-works/pi-coding-agent';
 import { StringEnum } from '@earendil-works/pi-ai';
 import { Text } from '@earendil-works/pi-tui';
 import { Type } from 'typebox';
-import type { PlanData, TaskStatus } from '../types.js';
+import type { TaskStatus } from '../types.js';
+import type { ResolvedPlan } from '../resolve-plan.js';
 
 export interface UpdateTaskCallbacks {
-  getPlan: () => PlanData | undefined;
+  /** Resolve the active plan, attaching from disk when none is in memory. */
+  resolvePlan: (opts?: { name?: string }) => Promise<ResolvedPlan>;
   onTaskUpdated: (
     taskId: string,
     status: Exclude<TaskStatus, 'pending'>,
@@ -17,6 +19,11 @@ export interface UpdateTaskCallbacks {
   ) => void | Promise<void>;
 }
 
+/** A non-terminating tool result — task tracking must never derail real work. */
+function soft(text: string, details: Record<string, unknown>) {
+  return { content: [{ type: 'text' as const, text }], details };
+}
+
 export function registerUpdateTaskTool(pi: ExtensionAPI, callbacks: UpdateTaskCallbacks): void {
   pi.registerTool({
     name: 'update_task',
@@ -35,19 +42,51 @@ export function registerUpdateTaskTool(pi: ExtensionAPI, callbacks: UpdateTaskCa
       notes: Type.Optional(
         Type.String({ description: 'What was done, why skipped, or why blocked' }),
       ),
+      plan: Type.Optional(
+        Type.String({
+          description:
+            'Plan name (or .plans/<name>) to target. Only needed to disambiguate when multiple plans are in-progress; otherwise the active / sole in-progress plan is used.',
+        }),
+      ),
     }),
 
     async execute(_toolCallId, params) {
-      const plan = callbacks.getPlan();
-      if (!plan) throw new Error('No active plan. Cannot update task.');
+      const { plan, candidates } = await callbacks.resolvePlan({ name: params.plan });
+      // No active plan is a tracking miss, not an error: return a soft result
+      // (non-terminating) so the agent keeps doing the real work.
+      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.';
+        return soft(`Skipped task tracking — no active plan.${hint}`, {
+          skipped: true,
+          candidates,
+        });
+      }
 
       const task = plan.tasks.find((candidate) => candidate.id === params.task_id);
-      if (!task) throw new Error(`Task not found: ${params.task_id}`);
-      if (task.status !== 'pending') {
-        throw new Error(
-          `Task ${params.task_id} is already "${task.status}". Only pending tasks can be updated.`,
-        );
+      if (!task) {
+        const ids = plan.tasks.map((candidate) => candidate.id).join(', ');
+        return soft(`Task not found: ${params.task_id}. Valid ids: ${ids || '(none)'}`, {
+          error: 'not_found',
+          task_id: params.task_id,
+        });
+      }
+      // Idempotent: re-marking the same status is a no-op success (safe to
+      // retry).
+      if (task.status === params.status) {
+        return soft(`Task ${params.task_id} already ${params.status} (no-op).`, {
+          task_id: params.task_id,
+          status: params.status,
+          description: task.description,
+        });
       }
+      // A different status on an already-resolved task is a CORRECTION — apply
+      // it (e.g. done→skipped, or blocked→done to unblock). The status is the
+      // edit; the plan queue recomputes from it.
+      const wasCorrection = task.status !== 'pending';
+      const priorStatus = task.status;
 
       await callbacks.onTaskUpdated(params.task_id, params.status, params.notes);
 
@@ -75,7 +114,8 @@ export function registerUpdateTaskTool(pi: ExtensionAPI, callbacks: UpdateTaskCa
       const resolved = done + skipped;
       const next = plan.tasks.find((candidate) => candidate.status === 'pending');
       const statusEmoji = params.status === 'done' ? '✓' : '⊘';
-      let text = `${statusEmoji} Task ${params.task_id} ${params.status}. Progress: ${resolved}/${plan.tasks.length}`;
+      const verb = wasCorrection ? `corrected (${priorStatus} → ${params.status})` : params.status;
+      let text = `${statusEmoji} Task ${params.task_id} ${verb}. Progress: ${resolved}/${plan.tasks.length}`;
       if (params.notes) text += ` — ${params.notes}`;
       text += next ? `\n\nNext task ${next.id}: ${next.description}` : '\n\nAll tasks resolved!';
 

package/extensions/plan-mode/types.ts

@@ -7,6 +7,12 @@ export type TaskStatus = 'pending' | 'done' | 'skipped' | 'blocked' | 'deferred'
 /** Where a task came from: the original submitted plan, or discovered during execution. */
 export type TaskOrigin = 'plan' | 'discovered';
 
+/**
+ * Plan lifecycle status. Only `in-progress` is active; `done`, `superseded`,
+ * and `abandoned` are terminal and drop out of active-plan resolution.
+ */
+export type PlanStatus = 'in-progress' | 'done' | 'superseded' | 'abandoned';
+
 export interface TaskRecord {
   _type: 'task';
   id: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dreki-gg/pi-plan-mode",
-  "version": "0.17.1",
+  "version": "0.19.0",
   "description": "Two-phase planning workflow for pi — plan with claude-opus-4-6:medium, execute with gpt-5.5:low, with .plans/ file-based handoff",
   "keywords": [
     "pi-package"