@dreki-gg/pi-plan-mode 0.23.0 → 0.24.0

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

@@ -0,0 +1,191 @@
+/**
+ * initiative_status tool — read-only snapshot of an initiative.
+ *
+ * The initiative sibling of plan_status. Shows each member plan with its task
+ * progress (resolved/total), lifecycle status, and ready/blocked-by readiness
+ * derived from plan-level dependencies. This is the at-a-glance view for
+ * splitting an initiative's work across sessions or subagents: "ready" plans
+ * have all dependencies satisfied and can be picked up now.
+ */
+
+import type { ExtensionAPI } from '@earendil-works/pi-coding-agent';
+import { Text } from '@earendil-works/pi-tui';
+import { Type } from 'typebox';
+import { Effect } from 'effect';
+import type { RunPlanIO } from '../effects/runtime.js';
+import { FileSystem } from '../effects/filesystem.js';
+import { readPlansManifest, type PlanManifestEntry } from '../storage/plans-manifest.js';
+import { readInitiativesManifest } from '../storage/initiatives-manifest.js';
+import { readTasksJsonl } from '../storage/task-storage.js';
+import { initiativeRollup, membersOf, type InitiativeRollup } from '../initiative.js';
+
+/** Normalize an initiative hint (`x` or `.plans/x`) to a bare name. */
+function normalizeName(hint: string): string {
+  return hint
+    .replace(/^\.plans\//, '')
+    .replace(/\/+$/, '')
+    .trim();
+}
+
+interface TaskCount {
+  resolved: number;
+  total: number;
+}
+
+/** Load member task counts for a set of plans (resolved = done + skipped). */
+function loadTaskCounts(
+  plans: readonly PlanManifestEntry[],
+): Effect.Effect<Map<string, TaskCount>, never, FileSystem> {
+  return Effect.gen(function* () {
+    const counts = new Map<string, TaskCount>();
+    for (const plan of plans) {
+      const snapshot = yield* Effect.orElseSucceed(
+        readTasksJsonl(`.plans/${plan.name}`),
+        () => undefined,
+      );
+      const total = snapshot?.tasks.length ?? 0;
+      const resolved =
+        snapshot?.tasks.filter((t) => t.status === 'done' || t.status === 'skipped').length ?? 0;
+      counts.set(plan.name, { resolved, total });
+    }
+    return counts;
+  });
+}
+
+const STATUS_GLYPH: Record<string, string> = {
+  'in-progress': '○',
+  done: '✓',
+  superseded: '🔄',
+  abandoned: '✗',
+};
+
+export function registerInitiativeStatusTool(pi: ExtensionAPI, runPlanIO: RunPlanIO): void {
+  pi.registerTool({
+    name: 'initiative_status',
+    label: 'Initiative Status',
+    description:
+      'Read-only snapshot of an initiative: member plans with task progress, status, and ready/blocked-by. Use to see what work is unblocked and can be picked up next.',
+    promptSnippet: 'Show an initiative: member plans, progress, and ready/blocked work',
+    promptGuidelines: [
+      'Call initiative_status to see which member plans are ready (dependencies satisfied) before dispatching work across sessions or subagents.',
+      'It is read-only and never mutates state.',
+    ],
+    parameters: Type.Object({
+      initiative: Type.Optional(
+        Type.String({
+          description:
+            'Initiative name (or .plans/<name>). Omit to use the sole in-progress initiative.',
+        }),
+      ),
+    }),
+
+    async execute(_toolCallId, params) {
+      const hint = params.initiative ? normalizeName(params.initiative) : undefined;
+
+      const snapshot = await runPlanIO(
+        Effect.gen(function* () {
+          const initiatives = yield* readInitiativesManifest();
+          const plans = yield* readPlansManifest();
+          return { initiatives, plans };
+        }),
+      );
+      const { initiatives, plans } = snapshot;
+
+      // Resolve the target initiative.
+      let targetName = hint;
+      if (!targetName) {
+        const inProgress = initiatives.filter((entry) => entry.status === 'in-progress');
+        if (inProgress.length === 1) targetName = inProgress[0]!.name;
+        else {
+          // Zero or many: list in-progress initiatives with rollup progress.
+          const rows = inProgress.map((entry) => {
+            const r = initiativeRollup(entry.name, plans);
+            return `  ${r.done}/${r.total} plans  ${entry.name} — ${entry.title} (ready ${r.ready}, blocked ${r.blocked})`;
+          });
+          const text = inProgress.length
+            ? `No single active initiative — ${inProgress.length} in-progress. Pass { initiative: "<name>" }.\n${rows.join('\n')}`
+            : 'No in-progress initiative found in .plans/initiatives.jsonl.';
+          return {
+            content: [{ type: 'text' as const, text }],
+            details: {
+              active: false,
+              in_progress: inProgress.map((e) => e.name),
+            } as Record<string, unknown>,
+          };
+        }
+      }
+
+      const entry = initiatives.find((e) => e.name === targetName);
+      if (!entry) {
+        const names = initiatives.map((e) => e.name).join(', ');
+        return {
+          content: [
+            {
+              type: 'text' as const,
+              text: `Initiative not found: ${targetName}. Known: ${names || '(none)'}`,
+            },
+          ],
+          details: {
+            active: false,
+            error: 'not_found',
+            initiative: targetName,
+          } as Record<string, unknown>,
+        };
+      }
+
+      const rollup: InitiativeRollup = initiativeRollup(entry.name, plans);
+      const taskCounts = await runPlanIO(loadTaskCounts(membersOf(entry.name, plans)));
+
+      const memberLines = rollup.members.map((m) => {
+        const glyph = STATUS_GLYPH[m.status] ?? '○';
+        const tc = taskCounts.get(m.name);
+        const progress = tc && tc.total > 0 ? ` ${tc.resolved}/${tc.total} tasks` : '';
+        let readiness = '';
+        if (m.status === 'in-progress') {
+          readiness = m.ready ? '  [ready]' : `  [blocked by ${m.blockedBy?.join(', ')}]`;
+        }
+        return `  ${glyph} ${m.name} [${m.status}]${progress}${readiness}`;
+      });
+
+      const text =
+        `Initiative: ${entry.title} (${entry.name}) — ${entry.status}\n` +
+        `Plans: ${rollup.done}/${rollup.total} done — in-progress ${rollup.inProgress} (ready ${rollup.ready}, blocked ${rollup.blocked})` +
+        (rollup.closed ? `, closed ${rollup.closed}` : '') +
+        '\n' +
+        (memberLines.length ? `Member plans:\n${memberLines.join('\n')}` : 'No member plans yet.');
+
+      return {
+        content: [{ type: 'text' as const, text }],
+        details: {
+          active: true,
+          initiative: entry.name,
+          status: entry.status,
+          rollup,
+          ready_plans: rollup.members.filter((m) => m.ready).map((m) => m.name),
+        } as Record<string, unknown>,
+      };
+    },
+
+    renderCall(args, theme) {
+      const name = (args as { initiative?: string }).initiative;
+      let content = theme.fg('toolTitle', theme.bold('initiative_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; initiative?: string; rollup?: InitiativeRollup }
+        | undefined;
+      if (!details?.active || !details.rollup)
+        return new Text(theme.fg('dim', 'No active initiative'), 0, 0);
+      const r = details.rollup;
+      return new Text(
+        theme.fg('toolTitle', `${details.initiative ?? 'initiative'} `) +
+          theme.fg('muted', `${r.done}/${r.total} plans — ready ${r.ready}, blocked ${r.blocked}`),
+        0,
+        0,
+      );
+    },
+  });
+}

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

@@ -11,7 +11,14 @@ 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';
+import {
+  applyInitiativeReconcile,
+  applyReconcile,
+  collectInitiativeDrift,
+  collectPlanDrift,
+  type InitiativeDriftRow,
+  type PlanDriftRow,
+} from '../reconcile.js';
 
 function describeRow(row: PlanDriftRow): string {
   const progress = row.hasTasks ? ` (${row.resolved}/${row.total})` : '';
@@ -48,23 +55,37 @@ export function registerReconcilePlansTool(pi: ExtensionAPI, runPlanIO: RunPlanI
 
     async execute(_toolCallId, params) {
       const rows = await runPlanIO(collectPlanDrift());
+      const initiativeRows = await runPlanIO(collectInitiativeDrift());
       const drifted = rows.filter((row) => row.drift);
+      const initiativeDrifted = initiativeRows.filter((row) => row.drift);
 
       let repaired: PlanDriftRow[] = [];
+      let initiativeRepaired: InitiativeDriftRow[] = [];
       if (params.apply) {
         repaired = await runPlanIO(applyReconcile(rows));
+        // Re-collect after plan repairs so initiative projection sees fresh state.
+        initiativeRepaired = await runPlanIO(
+          applyInitiativeReconcile(await runPlanIO(collectInitiativeDrift())),
+        );
       }
 
       const lines = rows.map(describeRow);
+      const initiativeLines = initiativeRows.map(
+        (row) =>
+          row.drift === 'status'
+            ? `  ✗ ${row.name} (initiative, ${row.members} plans) — registry ${row.registryStatus}, plans say ${row.derivedStatus}`
+            : `  ✓ ${row.name} (initiative, ${row.members} plans) — ${row.registryStatus} (in sync)`,
+      );
       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 totalDrift = drifted.length + initiativeDrifted.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).`;
+        ? `Reconciled ${repaired.length} plan(s) + ${initiativeRepaired.length} initiative(s).`
+        : totalDrift === 0
+          ? 'All plans and initiatives in sync.'
+          : `${totalDrift} drift issue(s) found (run with apply:true to repair status drift).`;
 
       const summary = [
         `status-drift ${statusDrift}`,
@@ -72,7 +93,10 @@ export function registerReconcilePlansTool(pi: ExtensionAPI, runPlanIO: RunPlanI
         `registry-only ${registryOnly}`,
       ].join(', ');
 
-      const text = `${header}\n${summary}\n${lines.join('\n')}`;
+      const initiativeBlock = initiativeLines.length
+        ? `\nInitiatives:\n${initiativeLines.join('\n')}`
+        : '';
+      const text = `${header}\n${summary}\n${lines.join('\n')}${initiativeBlock}`;
       return {
         content: [{ type: 'text' as const, text }],
         details: {
@@ -80,6 +104,9 @@ export function registerReconcilePlansTool(pi: ExtensionAPI, runPlanIO: RunPlanI
           repaired: repaired.map((r) => r.name),
           drift: drifted.map((r) => ({ name: r.name, kind: r.drift })),
           total: rows.length,
+          initiative_repaired: initiativeRepaired.map((r) => r.name),
+          initiative_drift: initiativeDrifted.map((r) => ({ name: r.name, kind: r.drift })),
+          initiative_total: initiativeRows.length,
         },
       };
     },

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

@@ -23,7 +23,9 @@ import {
   reconcilePlanStatus,
   upsertPlanEntry,
 } from '../storage/plans-manifest.js';
+import { reconcileInitiativeForPlan, reconcileInitiativeStatus } from '../initiative.js';
 import { isPlanFinalizable } from '../task-status.js';
+import { toKebabCase } from '../utils.js';
 import type { RunPlanIO } from '../effects/runtime.js';
 import type { PlanData, TaskMeta, TaskRecord } from '../types.js';
 
@@ -47,6 +49,7 @@ export function registerRevisePlanTool(
       'Use revise_plan instead of submit_plan when a plan with the same name already exists and the user asks for follow-up changes.',
       'All content fields are optional — pass only what changes; omitted title/handoff/tasks are left as-is.',
       'When you pass tasks, it fully replaces the task set (tasks you omit are dropped). Status and notes are preserved for any task whose id is unchanged.',
+      'Pass initiative / depends_on_plans to (re)link this plan to an initiative or change its plan-level dependencies; omit them to preserve the existing links.',
     ],
     parameters: Type.Object({
       plan: Type.String({ description: 'Plan name (or .plans/<name>) to revise' }),
@@ -69,6 +72,14 @@ export function registerRevisePlanTool(
           { minItems: 1 },
         ),
       ),
+      initiative: Type.Optional(
+        Type.String({ description: 'Parent initiative name (kebab); omit to preserve.' }),
+      ),
+      depends_on_plans: Type.Optional(
+        Type.Array(
+          Type.String({ description: 'Plan names this plan depends on (cross-initiative allowed).' }),
+        ),
+      ),
     }),
 
     async execute(_toolCallId, params) {
@@ -127,6 +138,9 @@ export function registerRevisePlanTool(
       };
       const planDir = `.plans/${plan.planName}`;
 
+      const newInitiative = params.initiative ? toKebabCase(params.initiative) : undefined;
+      const newDependsOn = params.depends_on_plans?.map(toKebabCase);
+
       await runPlanIO(
         Effect.gen(function* () {
           yield* writeTasksJsonl(planDir, meta, tasks);
@@ -135,11 +149,19 @@ export function registerRevisePlanTool(
           // re-derive in-progress ⇄ done (never clobbers superseded/abandoned).
           const manifest = yield* readPlansManifest();
           const current = manifest.find((entry) => entry.name === plan.planName);
+          const oldInitiative = current?.initiative;
           yield* upsertPlanEntry(plan.planName, {
             status: current?.status ?? 'in-progress',
             title: newTitle,
+            initiative: newInitiative,
+            depends_on: newDependsOn,
           });
           yield* reconcilePlanStatus(plan.planName, isPlanFinalizable(tasks), newTitle);
+          // Keep both the new and any vacated initiative projections in sync.
+          yield* reconcileInitiativeForPlan(plan.planName);
+          if (newInitiative && oldInitiative && oldInitiative !== newInitiative) {
+            yield* reconcileInitiativeStatus(oldInitiative);
+          }
         }),
       );
 

package/extensions/plan-mode/tools/submit-initiative.ts

@@ -0,0 +1,86 @@
+/**
+ * submit_initiative tool — create an initiative that groups multiple plans.
+ *
+ * The initiative-level sibling of submit_plan. Use it FIRST for work too large
+ * for a single coherent execution session: create the initiative, then submit
+ * each executable chunk as its own plan with `initiative` set (and
+ * `depends_on_plans` for ordering). The initiative's status is then a
+ * projection of its member plans.
+ */
+
+import type { ExtensionAPI } from '@earendil-works/pi-coding-agent';
+import { Text } from '@earendil-works/pi-tui';
+import { Type } from 'typebox';
+import { Effect } from 'effect';
+import { saveInitiative } from '../storage/plan-storage.js';
+import { upsertInitiativeEntry } from '../storage/initiatives-manifest.js';
+import type { RunPlanIO } from '../effects/runtime.js';
+import { toKebabCase } from '../utils.js';
+
+export function registerSubmitInitiativeTool(pi: ExtensionAPI, runPlanIO: RunPlanIO): void {
+  pi.registerTool({
+    name: 'submit_initiative',
+    label: 'Submit Initiative',
+    description:
+      'Create an initiative that groups multiple plans for a large body of work. Submit member plans separately with their initiative set.',
+    promptSnippet: 'Create an initiative to group multiple plans for large work',
+    promptGuidelines: [
+      'Use submit_initiative when the work does not fit one coherent execution session, or spans multiple subsystems with dependencies between chunks.',
+      'Create the initiative first, then submit each executable chunk as its own plan with `initiative` set and `depends_on_plans` capturing ordering.',
+      'For a bounded change, skip initiatives and just submit a flat plan.',
+    ],
+    parameters: Type.Object({
+      name: Type.String({
+        description: 'Short kebab-case name for the initiative (e.g. "auth-overhaul")',
+      }),
+      title: Type.String({ description: 'Human-readable initiative title' }),
+      overview: Type.String({
+        description:
+          'Markdown overview for INITIATIVE.md: the goal, the plan breakdown, ordering/dependencies, and how the chunks fit together.',
+      }),
+    }),
+
+    async execute(_toolCallId, params) {
+      const name = toKebabCase(params.name);
+      const initiativeDir = `.plans/${name}`;
+
+      await runPlanIO(
+        Effect.gen(function* () {
+          yield* saveInitiative(initiativeDir, params.overview);
+          yield* upsertInitiativeEntry(name, { status: 'in-progress', title: params.title });
+        }),
+      );
+
+      return {
+        content: [
+          {
+            type: 'text' as const,
+            text: `Initiative "${params.title}" created in ${initiativeDir}. Submit member plans with initiative: "${name}".`,
+          },
+        ],
+        details: { initiativeDir, name, title: params.title },
+      };
+    },
+
+    renderCall(args, theme) {
+      const name = (args as { name?: string }).name ?? 'initiative';
+      const title = (args as { title?: string }).title ?? '';
+      let content = theme.fg('toolTitle', theme.bold('submit_initiative '));
+      content += theme.fg('accent', name);
+      if (title) content += ' ' + theme.fg('dim', `"${title}"`);
+      return new Text(content, 0, 0);
+    },
+
+    renderResult(result, _options, theme) {
+      const details = result.details as { name?: string; title?: string } | undefined;
+      if (!details?.name) return new Text(theme.fg('success', '✓ Initiative created'), 0, 0);
+      return new Text(
+        theme.fg('success', '✓ ') +
+          theme.fg('accent', theme.bold(details.title ?? details.name)) +
+          theme.fg('dim', ` (${details.name})`),
+        0,
+        0,
+      );
+    },
+  });
+}

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

@@ -9,6 +9,8 @@ import { Effect } from 'effect';
 import { saveHandoff } from '../storage/plan-storage.js';
 import { writeTasksJsonl } from '../storage/task-storage.js';
 import { upsertPlanEntry } from '../storage/plans-manifest.js';
+import { readInitiativesManifest } from '../storage/initiatives-manifest.js';
+import { reconcileInitiativeForPlan } from '../initiative.js';
 import type { RunPlanIO } from '../effects/runtime.js';
 import { toKebabCase } from '../utils.js';
 import type { PlanData, TaskMeta, TaskRecord } from '../types.js';
@@ -34,6 +36,7 @@ export function registerSubmitPlanTool(
       'When you are planning and executing yourself (same session), use lightweight checklist-style tasks: just id + description, omit details. Put the real context in the handoff document instead.',
       'The handoff must be thorough enough that both a human reviewer and executor agent with zero prior context can understand the plan.',
       'For visual/UI work, preview a prototype with preview_prototype during planning — before submit_plan, not as part of it.',
+      'For large work split across plans, set `initiative` to the parent initiative (create it first with submit_initiative) and use `depends_on_plans` to order plans against each other — this enables ready-work tracking across sessions and agents.',
     ],
     parameters: Type.Object({
       name: Type.String({
@@ -57,11 +60,26 @@ export function registerSubmitPlanTool(
         }),
         { minItems: 1 },
       ),
+      initiative: Type.Optional(
+        Type.String({
+          description:
+            'Parent initiative name (kebab) when this plan is one chunk of a larger initiative. Create the initiative first with submit_initiative.',
+        }),
+      ),
+      depends_on_plans: Type.Optional(
+        Type.Array(
+          Type.String({
+            description: 'Names of other plans this plan depends on (cross-initiative allowed).',
+          }),
+        ),
+      ),
     }),
 
     async execute(_toolCallId, params) {
       const planName = toKebabCase(params.name);
       const planDir = `.plans/${planName}`;
+      const initiative = params.initiative ? toKebabCase(params.initiative) : undefined;
+      const dependsOnPlans = params.depends_on_plans?.map(toKebabCase);
       const now = new Date().toISOString();
       const meta: TaskMeta = {
         _type: 'meta',
@@ -81,24 +99,39 @@ export function registerSubmitPlanTool(
       }));
       const plan: PlanData = { title: params.title, planName, handoff: params.handoff, tasks };
 
-      await runPlanIO(
+      const unknownInitiative = await runPlanIO(
         Effect.gen(function* () {
           yield* writeTasksJsonl(planDir, meta, tasks);
           yield* saveHandoff(planDir, params.handoff);
-          yield* upsertPlanEntry(planName, { status: 'in-progress', title: params.title });
+          yield* upsertPlanEntry(planName, {
+            status: 'in-progress',
+            title: params.title,
+            initiative,
+            depends_on: dependsOnPlans,
+          });
+          // Keep the parent initiative's projected status in sync.
+          yield* reconcileInitiativeForPlan(planName);
+          if (!initiative) return false;
+          const initiatives = yield* readInitiativesManifest();
+          return !initiatives.some((entry) => entry.name === initiative);
         }),
       );
 
       callbacks.onPlanSubmitted(planDir, plan);
 
+      const linkSuffix = initiative
+        ? ` Linked to initiative "${initiative}"${
+            unknownInitiative ? ' (no initiatives.jsonl entry yet — create it with submit_initiative)' : ''
+          }.`
+        : '';
       return {
         content: [
           {
             type: 'text' as const,
-            text: `Plan "${params.title}" saved with ${tasks.length} tasks in ${planDir}. Execute when ready.`,
+            text: `Plan "${params.title}" saved with ${tasks.length} tasks in ${planDir}. Execute when ready.${linkSuffix}`,
           },
         ],
-        details: { planDir, plan },
+        details: { planDir, plan, initiative, depends_on_plans: dependsOnPlans },
       };
     },
 

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

@@ -0,0 +1,120 @@
+/**
+ * update_initiative tool — initiative-level lifecycle control.
+ *
+ * The initiative sibling of update_plan. An initiative's `done` status is a
+ * projection of its member plans, but `superseded` / `abandoned` (and reopen)
+ * are explicit decisions recorded here with an optional `reason`. A manually
+ * set terminal status is never auto-overridden by projection.
+ */
+
+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 { InitiativeStatus } from '../types.js';
+import type { RunPlanIO } from '../effects/runtime.js';
+import {
+  readInitiativesManifest,
+  upsertInitiativeEntry,
+} from '../storage/initiatives-manifest.js';
+
+/** Normalize an initiative hint (`x` or `.plans/x`) to a bare name. */
+function normalizeName(hint: string): string {
+  return hint
+    .replace(/^\.plans\//, '')
+    .replace(/\/+$/, '')
+    .trim();
+}
+
+export function registerUpdateInitiativeTool(pi: ExtensionAPI, runPlanIO: RunPlanIO): void {
+  pi.registerTool({
+    name: 'update_initiative',
+    label: 'Update Initiative',
+    description:
+      'Set an initiative-level status (done, superseded, abandoned, or reopen to in-progress) with an optional reason.',
+    promptSnippet: 'Close or reopen an initiative (done/superseded/abandoned/in-progress)',
+    promptGuidelines: [
+      'Use update_initiative to close an initiative that will not complete via its plans: superseded (another initiative shipped it) or abandoned (won\u2019t do).',
+      'Always pass a reason for superseded/abandoned so the registry keeps honest history.',
+      'An initiative usually reaches done automatically once every member plan is closed \u2014 prefer letting projection handle it.',
+    ],
+    parameters: Type.Object({
+      initiative: Type.String({ description: 'Initiative 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.initiative);
+      const manifest = await runPlanIO(readInitiativesManifest());
+      const existing = manifest.find((entry) => entry.name === name);
+      if (!existing) {
+        const names = manifest.map((entry) => entry.name).join(', ');
+        return {
+          content: [
+            {
+              type: 'text' as const,
+              text: `Initiative not found: ${name}. Known initiatives: ${names || '(none)'}`,
+            },
+          ],
+          details: { error: 'not_found', initiative: name } as Record<string, unknown>,
+        };
+      }
+
+      await runPlanIO(
+        upsertInitiativeEntry(name, {
+          status: params.status as InitiativeStatus,
+          title: existing.title,
+          reason: params.reason,
+        }),
+      );
+
+      const reasonSuffix = params.reason ? ` — ${params.reason}` : '';
+      return {
+        content: [
+          {
+            type: 'text' as const,
+            text: `Initiative ${name}: ${existing.status} → ${params.status}${reasonSuffix}`,
+          },
+        ],
+        details: {
+          initiative: name,
+          from: existing.status,
+          status: params.status,
+          reason: params.reason,
+        } as Record<string, unknown>,
+      };
+    },
+
+    renderCall(args, theme) {
+      const name = (args as { initiative?: string }).initiative ?? 'initiative';
+      const status = (args as { status?: string }).status ?? '';
+      let content = theme.fg('toolTitle', theme.bold('update_initiative '));
+      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
+        | { initiative?: string; from?: string; status?: string }
+        | undefined;
+      if (!details?.status) return new Text(theme.fg('dim', 'Initiative updated'), 0, 0);
+      const color =
+        details.status === 'done'
+          ? 'success'
+          : details.status === 'in-progress'
+            ? 'accent'
+            : 'warning';
+      return new Text(
+        theme.fg('muted', `${details.initiative ?? 'initiative'} `) +
+          theme.fg('dim', `${details.from ?? ''} → `) +
+          theme.fg(color, details.status),
+        0,
+        0,
+      );
+    },
+  });
+}

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

@@ -18,6 +18,7 @@ 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';
+import { reconcileInitiativeForPlan } from '../initiative.js';
 
 /** Normalize a plan hint (`my-plan` or `.plans/my-plan`) to a bare name. */
 function normalizeName(hint: string): string {
@@ -72,6 +73,8 @@ export function registerUpdatePlanTool(pi: ExtensionAPI, runPlanIO: RunPlanIO):
           reason: params.reason,
         }),
       );
+      // A plan-level status change can flip its parent initiative's projection.
+      await runPlanIO(reconcileInitiativeForPlan(name));
 
       const reasonSuffix = params.reason ? ` — ${params.reason}` : '';
       const okDetails: Record<string, unknown> = {

package/extensions/plan-mode/types.ts

@@ -13,6 +13,9 @@ export type TaskOrigin = 'plan' | 'discovered';
  */
 export type PlanStatus = 'in-progress' | 'done' | 'superseded' | 'abandoned';
 
+/** Initiative lifecycle reuses the plan lifecycle literals. */
+export type InitiativeStatus = PlanStatus;
+
 export interface TaskRecord {
   _type: 'task';
   id: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dreki-gg/pi-plan-mode",
-  "version": "0.23.0",
+  "version": "0.24.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"