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

package/extensions/plan-mode/__tests__/list-initiatives.test.ts

@@ -0,0 +1,59 @@
+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 { upsertPlanEntry } from '../storage/plans-manifest.js';
+import { upsertInitiativeEntry } from '../storage/initiatives-manifest.js';
+import {
+  filterInitiatives,
+  formatInitiativeList,
+  loadInitiativeListItems,
+  parseFilter,
+} from '../commands/list-initiatives.js';
+
+const runPlanIO = makePlanRuntime();
+
+const originalCwd = process.cwd();
+let dir: string;
+beforeEach(async () => {
+  dir = await mkdtemp(join(tmpdir(), 'plan-mode-list-init-'));
+  chdir(dir);
+});
+afterEach(async () => {
+  chdir(originalCwd);
+  await rm(dir, { recursive: true, force: true });
+});
+
+describe('list-initiatives', () => {
+  test('parseFilter maps aliases', () => {
+    expect(parseFilter('done')).toBe('done');
+    expect(parseFilter('active')).toBe('in-progress');
+    expect(parseFilter('whatever')).toBe('all');
+  });
+
+  test('rolls up member-plan progress and readiness', async () => {
+    await runPlanIO(upsertInitiativeEntry('big', { status: 'in-progress', title: 'Big' }));
+    await runPlanIO(upsertPlanEntry('a', { status: 'done', title: 'A', initiative: 'big' }));
+    await runPlanIO(
+      upsertPlanEntry('b', { status: 'in-progress', title: 'B', initiative: 'big', depends_on: ['a'] }),
+    );
+
+    const items = await runPlanIO(loadInitiativeListItems());
+    expect(items).toHaveLength(1);
+    expect(items[0]?.totalPlans).toBe(2);
+    expect(items[0]?.donePlans).toBe(1);
+    expect(items[0]?.ready).toBe(1); // b unblocked (a done)
+
+    const text = formatInitiativeList(items, 'all');
+    expect(text).toMatch(/big — Big \[1\/2 plans, ready 1, blocked 0\]/);
+  });
+
+  test('filterInitiatives narrows by status', async () => {
+    await runPlanIO(upsertInitiativeEntry('x', { status: 'in-progress', title: 'X' }));
+    await runPlanIO(upsertInitiativeEntry('y', { status: 'done', title: 'Y' }));
+    const items = await runPlanIO(loadInitiativeListItems());
+    expect(filterInitiatives(items, 'done').map((i) => i.name)).toEqual(['y']);
+  });
+});

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

@@ -10,7 +10,13 @@ import {
   upsertPlanEntry,
   writePlansManifest,
 } from '../storage/plans-manifest.js';
-import { applyReconcile, collectPlanDrift } from '../reconcile.js';
+import { upsertInitiativeEntry, readInitiativesManifest } from '../storage/initiatives-manifest.js';
+import {
+  applyInitiativeReconcile,
+  applyReconcile,
+  collectInitiativeDrift,
+  collectPlanDrift,
+} from '../reconcile.js';
 import type { TaskMeta, TaskRecord, TaskStatus } from '../types.js';
 
 const runPlanIO = makePlanRuntime();
@@ -112,3 +118,34 @@ describe('applyReconcile', () => {
     expect(entry.status).toBe('done');
   });
 });
+
+describe('initiative drift', () => {
+  test('flags an initiative whose members are all closed but registry is in-progress', async () => {
+    await runPlanIO(upsertInitiativeEntry('big', { status: 'in-progress', title: 'Big' }));
+    await runPlanIO(upsertPlanEntry('a', { status: 'done', title: 'A', initiative: 'big' }));
+    await runPlanIO(upsertPlanEntry('b', { status: 'done', title: 'B', initiative: 'big' }));
+
+    const rows = await runPlanIO(collectInitiativeDrift());
+    const big = rows.find((r) => r.name === 'big')!;
+    expect(big.drift).toBe('status');
+    expect(big.derivedStatus).toBe('done');
+    expect(big.members).toBe(2);
+  });
+
+  test('applyInitiativeReconcile repairs initiative status drift', async () => {
+    await runPlanIO(upsertInitiativeEntry('big', { status: 'in-progress', title: 'Big' }));
+    await runPlanIO(upsertPlanEntry('a', { status: 'done', title: 'A', initiative: 'big' }));
+
+    const repaired = await runPlanIO(applyInitiativeReconcile(await runPlanIO(collectInitiativeDrift())));
+    expect(repaired.map((r) => r.name)).toEqual(['big']);
+    const [entry] = await runPlanIO(readInitiativesManifest());
+    expect(entry.status).toBe('done');
+  });
+
+  test('never flags a manually-closed (abandoned) initiative as drift', async () => {
+    await runPlanIO(upsertInitiativeEntry('big', { status: 'abandoned', title: 'Big', reason: 'x' }));
+    await runPlanIO(upsertPlanEntry('a', { status: 'done', title: 'A', initiative: 'big' }));
+    const rows = await runPlanIO(collectInitiativeDrift());
+    expect(rows.find((r) => r.name === 'big')!.drift).toBeUndefined();
+  });
+});

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

@@ -26,6 +26,8 @@ interface CapturedTool {
         details?: string;
         depends_on?: string[];
       }>;
+      initiative?: string;
+      depends_on_plans?: string[];
     },
   ) => Promise<{ content?: Array<{ text: string }>; details?: unknown }>;
 }
@@ -168,4 +170,40 @@ describe('revise_plan tool', () => {
     const result = await tool.execute('c', { plan: 'ghost', title: 'x' });
     expect((result.details as { error?: string }).error).toBe('not_found');
   });
+
+  test('re-links the plan to an initiative and persists plan-level deps', async () => {
+    const plan: PlanData = {
+      title: 'P',
+      planName: 'p',
+      handoff: 'h',
+      tasks: [task('t-001')],
+    };
+    await seed(plan);
+    await runPlanIO(upsertPlanEntry('p', { status: 'in-progress', title: 'P' }));
+
+    const { tool } = setup(plan);
+    await tool.execute('c', {
+      plan: 'p',
+      initiative: 'Auth Overhaul',
+      depends_on_plans: ['Schema First'],
+    });
+
+    const [entry] = await runPlanIO(readPlansManifest());
+    expect(entry.initiative).toBe('auth-overhaul');
+    expect(entry.depends_on).toEqual(['schema-first']);
+  });
+
+  test('preserves existing initiative link when not passed', async () => {
+    const plan: PlanData = { title: 'P', planName: 'p', handoff: 'h', tasks: [task('t-001')] };
+    await seed(plan);
+    await runPlanIO(
+      upsertPlanEntry('p', { status: 'in-progress', title: 'P', initiative: 'big' }),
+    );
+
+    const { tool } = setup(plan);
+    await tool.execute('c', { plan: 'p', title: 'P2' });
+
+    const [entry] = await runPlanIO(readPlansManifest());
+    expect(entry.initiative).toBe('big');
+  });
 });

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

@@ -2,6 +2,7 @@ import { describe, expect, test } from 'bun:test';
 import { Either } from 'effect';
 import {
   decodeExecPendingConfig,
+  decodeInitiativeManifestEntry,
   decodePlanManifestEntry,
   decodeTaskMeta,
   decodeTaskRecord,
@@ -211,6 +212,93 @@ describe('plan manifest entry schema', () => {
       ),
     ).toBe(false);
   });
+
+  test('accepts optional initiative + plan-level depends_on (forward compat)', () => {
+    expect(
+      isOk(
+        {
+          _type: 'plan',
+          name: 'auth-jwt',
+          status: 'in-progress',
+          title: 'Auth JWT',
+          created_at: now,
+          completed_at: null,
+          initiative: 'auth-overhaul',
+          depends_on: ['auth-schema'],
+        },
+        decodePlanManifestEntry,
+      ),
+    ).toBe(true);
+  });
+
+  test('still accepts a legacy entry without the new optional fields (back compat)', () => {
+    expect(
+      isOk(
+        {
+          _type: 'plan',
+          name: 'legacy',
+          status: 'done',
+          title: 'Legacy',
+          created_at: now,
+          completed_at: now,
+        },
+        decodePlanManifestEntry,
+      ),
+    ).toBe(true);
+  });
+});
+
+describe('initiative manifest entry schema', () => {
+  test('accepts a valid in-progress initiative', () => {
+    expect(
+      isOk(
+        {
+          _type: 'initiative',
+          name: 'auth-overhaul',
+          status: 'in-progress',
+          title: 'Auth Overhaul',
+          created_at: now,
+          completed_at: null,
+        },
+        decodeInitiativeManifestEntry,
+      ),
+    ).toBe(true);
+  });
+
+  test('accepts terminal statuses with a reason', () => {
+    for (const status of ['done', 'superseded', 'abandoned'] as const) {
+      expect(
+        isOk(
+          {
+            _type: 'initiative',
+            name: 'auth-overhaul',
+            status,
+            title: 'Auth Overhaul',
+            created_at: now,
+            completed_at: now,
+            reason: 'shipped',
+          },
+          decodeInitiativeManifestEntry,
+        ),
+      ).toBe(true);
+    }
+  });
+
+  test('rejects a plan _type masquerading as an initiative', () => {
+    expect(
+      isOk(
+        {
+          _type: 'plan',
+          name: 'auth-overhaul',
+          status: 'in-progress',
+          title: 'Auth Overhaul',
+          created_at: now,
+          completed_at: null,
+        },
+        decodeInitiativeManifestEntry,
+      ),
+    ).toBe(false);
+  });
 });
 
 describe('exec pending config schema', () => {

package/extensions/plan-mode/__tests__/submit-initiative.test.ts

@@ -0,0 +1,58 @@
+import { afterEach, beforeEach, describe, expect, test } from 'bun:test';
+import { chdir } from 'node:process';
+import { mkdtemp, readFile, rm } from 'node:fs/promises';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+import { makePlanRuntime } from '../effects/runtime.js';
+import { readInitiativesManifest } from '../storage/initiatives-manifest.js';
+import { registerSubmitInitiativeTool } from '../tools/submit-initiative.js';
+
+const runPlanIO = makePlanRuntime();
+
+interface CapturedTool {
+  execute: (
+    id: string,
+    params: { name: string; title: string; overview: 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 registerSubmitInitiativeTool>[0];
+  registerSubmitInitiativeTool(pi, runPlanIO);
+  return tool!;
+}
+
+const originalCwd = process.cwd();
+let dir: string;
+beforeEach(async () => {
+  dir = await mkdtemp(join(tmpdir(), 'plan-mode-submit-init-'));
+  chdir(dir);
+});
+afterEach(async () => {
+  chdir(originalCwd);
+  await rm(dir, { recursive: true, force: true });
+});
+
+describe('submit_initiative tool', () => {
+  test('creates a registry entry + INITIATIVE.md and kebab-cases the name', async () => {
+    const tool = setup();
+    const result = await tool.execute('c', {
+      name: 'Auth Overhaul',
+      title: 'Auth Overhaul',
+      overview: '# Overview\n\nBreak auth into plans.',
+    });
+
+    const [entry] = await runPlanIO(readInitiativesManifest());
+    expect(entry.name).toBe('auth-overhaul');
+    expect(entry.status).toBe('in-progress');
+
+    const md = await readFile(join(dir, '.plans/auth-overhaul/INITIATIVE.md'), 'utf-8');
+    expect(md).toMatch(/Break auth into plans/);
+    expect(result.content?.[0]?.text).toMatch(/initiative: "auth-overhaul"/);
+  });
+});

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

@@ -0,0 +1,97 @@
+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 } from '../storage/plans-manifest.js';
+import {
+  readInitiativesManifest,
+  upsertInitiativeEntry,
+} from '../storage/initiatives-manifest.js';
+import { registerSubmitPlanTool } from '../tools/submit-plan.js';
+
+const runPlanIO = makePlanRuntime();
+
+interface SubmitParams {
+  name: string;
+  title: string;
+  handoff: string;
+  tasks: Array<{ id: string; description: string }>;
+  initiative?: string;
+  depends_on_plans?: string[];
+}
+interface CapturedTool {
+  execute: (
+    id: string,
+    params: SubmitParams,
+  ) => 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 registerSubmitPlanTool>[0];
+  registerSubmitPlanTool(pi, runPlanIO, { onPlanSubmitted: () => {} });
+  return tool!;
+}
+
+const baseParams = (over: Partial<SubmitParams> = {}): SubmitParams => ({
+  name: 'auth-jwt',
+  title: 'Auth JWT',
+  handoff: '# handoff',
+  tasks: [{ id: 't-001', description: 'do it' }],
+  ...over,
+});
+
+const originalCwd = process.cwd();
+let dir: string;
+beforeEach(async () => {
+  dir = await mkdtemp(join(tmpdir(), 'plan-mode-submit-plan-'));
+  chdir(dir);
+});
+afterEach(async () => {
+  chdir(originalCwd);
+  await rm(dir, { recursive: true, force: true });
+});
+
+describe('submit_plan tool — initiative + plan deps', () => {
+  test('persists initiative + depends_on onto the plan manifest entry', async () => {
+    await runPlanIO(upsertInitiativeEntry('auth-overhaul', { status: 'in-progress', title: 'Auth' }));
+    const tool = setup();
+    await tool.execute('c', baseParams({ initiative: 'auth-overhaul', depends_on_plans: ['auth-schema'] }));
+
+    const [entry] = await runPlanIO(readPlansManifest());
+    expect(entry.initiative).toBe('auth-overhaul');
+    expect(entry.depends_on).toEqual(['auth-schema']);
+  });
+
+  test('kebab-cases the initiative name and reconciles it (member keeps it in-progress)', async () => {
+    await runPlanIO(upsertInitiativeEntry('auth-overhaul', { status: 'done', title: 'Auth' }));
+    const tool = setup();
+    await tool.execute('c', baseParams({ initiative: 'Auth Overhaul' }));
+
+    const [plan] = await runPlanIO(readPlansManifest());
+    expect(plan.initiative).toBe('auth-overhaul');
+    // A fresh in-progress member must reopen a prematurely-done initiative.
+    const [init] = await runPlanIO(readInitiativesManifest());
+    expect(init.status).toBe('in-progress');
+  });
+
+  test('warns softly when the initiative has no registry entry yet', async () => {
+    const tool = setup();
+    const result = await tool.execute('c', baseParams({ initiative: 'ghost-initiative' }));
+    expect(result.content?.[0]?.text).toMatch(/no initiatives\.jsonl entry yet/);
+  });
+
+  test('a standalone plan stores no initiative and no warning', async () => {
+    const tool = setup();
+    const result = await tool.execute('c', baseParams());
+    const [entry] = await runPlanIO(readPlansManifest());
+    expect(entry.initiative).toBeUndefined();
+    expect(result.content?.[0]?.text).not.toMatch(/initiative/i);
+  });
+});

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

@@ -0,0 +1,72 @@
+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 {
+  readInitiativesManifest,
+  upsertInitiativeEntry,
+} from '../storage/initiatives-manifest.js';
+import { registerUpdateInitiativeTool } from '../tools/update-initiative.js';
+
+const runPlanIO = makePlanRuntime();
+
+interface CapturedTool {
+  execute: (
+    id: string,
+    params: { initiative: 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 registerUpdateInitiativeTool>[0];
+  registerUpdateInitiativeTool(pi, runPlanIO);
+  return tool!;
+}
+
+const originalCwd = process.cwd();
+let dir: string;
+beforeEach(async () => {
+  dir = await mkdtemp(join(tmpdir(), 'plan-mode-update-init-'));
+  chdir(dir);
+});
+afterEach(async () => {
+  chdir(originalCwd);
+  await rm(dir, { recursive: true, force: true });
+});
+
+describe('update_initiative tool', () => {
+  test('closes an initiative as superseded with a reason', async () => {
+    await runPlanIO(upsertInitiativeEntry('big', { status: 'in-progress', title: 'Big' }));
+    const tool = setup();
+    const result = await tool.execute('c', {
+      initiative: 'big',
+      status: 'superseded',
+      reason: 'merged into mega',
+    });
+    expect(result.content?.[0]?.text).toMatch(/in-progress → superseded/);
+    const [entry] = await runPlanIO(readInitiativesManifest());
+    expect(entry.status).toBe('superseded');
+    expect(entry.reason).toBe('merged into mega');
+  });
+
+  test('accepts a .plans/<name> hint', async () => {
+    await runPlanIO(upsertInitiativeEntry('big', { status: 'in-progress', title: 'Big' }));
+    const tool = setup();
+    await tool.execute('c', { initiative: '.plans/big', status: 'abandoned', reason: 'dropped' });
+    const [entry] = await runPlanIO(readInitiativesManifest());
+    expect(entry.status).toBe('abandoned');
+  });
+
+  test('reports not_found for an unknown initiative (no throw)', async () => {
+    const tool = setup();
+    const result = await tool.execute('c', { initiative: 'ghost', status: 'done' });
+    expect((result.details as { error?: string }).error).toBe('not_found');
+  });
+});

package/extensions/plan-mode/commands/list-initiatives.ts

@@ -0,0 +1,148 @@
+/**
+ * /initiatives command — list, filter, and sort initiatives interactively.
+ *
+ * The initiative sibling of /plans. Reads the initiatives registry plus the
+ * plans manifest to roll up member-plan progress (done/total, ready/blocked).
+ */
+
+import { Effect } from 'effect';
+import type { ExtensionCommandContext } from '@earendil-works/pi-coding-agent';
+import type { RunPlanIO } from '../effects/runtime.js';
+import { FileSystem } from '../effects/filesystem.js';
+import { readPlansManifest, type PlanManifestEntry } from '../storage/plans-manifest.js';
+import {
+  readInitiativesManifest,
+  type InitiativeManifestEntry,
+} from '../storage/initiatives-manifest.js';
+import { initiativeRollup } from '../initiative.js';
+import type { InitiativeStatus } from '../types.js';
+
+export type StatusFilter = 'all' | InitiativeStatus;
+
+export interface InitiativeListItem {
+  name: string;
+  title: string;
+  status: InitiativeStatus;
+  created_at: string;
+  totalPlans: number;
+  donePlans: number;
+  ready: number;
+  blocked: number;
+}
+
+export function filterInitiatives(
+  items: InitiativeListItem[],
+  filter: StatusFilter,
+): InitiativeListItem[] {
+  if (filter === 'all') return items;
+  return items.filter((i) => i.status === filter);
+}
+
+const STATUS_ICON: Record<InitiativeStatus, string> = {
+  'in-progress': '🔵',
+  done: '✅',
+  superseded: '🔄',
+  abandoned: '❌',
+};
+
+export function formatInitiativeList(items: InitiativeListItem[], filter: StatusFilter): string {
+  if (items.length === 0) {
+    return filter === 'all'
+      ? 'No initiatives found in .plans/initiatives.jsonl'
+      : `No initiatives with status "${filter}"`;
+  }
+  const header =
+    filter === 'all'
+      ? `All initiatives (${items.length})`
+      : `Initiatives: ${filter} (${items.length})`;
+  const lines = items.map((i) => {
+    const icon = STATUS_ICON[i.status];
+    const progress =
+      i.totalPlans > 0
+        ? ` [${i.donePlans}/${i.totalPlans} plans, ready ${i.ready}, blocked ${i.blocked}]`
+        : ' [no plans]';
+    const date = i.created_at.slice(0, 10);
+    return `  ${icon} ${i.name} — ${i.title}${progress}  (${date})`;
+  });
+  return `${header}\n${lines.join('\n')}`;
+}
+
+export function loadInitiativeListItems(): Effect.Effect<InitiativeListItem[], never, FileSystem> {
+  return Effect.gen(function* () {
+    const initiatives = yield* Effect.orElseSucceed(
+      readInitiativesManifest(),
+      () => [] as InitiativeManifestEntry[],
+    );
+    const plans = yield* Effect.orElseSucceed(
+      readPlansManifest(),
+      () => [] as PlanManifestEntry[],
+    );
+    return initiatives.map((entry): InitiativeListItem => {
+      const r = initiativeRollup(entry.name, plans);
+      return {
+        name: entry.name,
+        title: entry.title,
+        status: entry.status,
+        created_at: entry.created_at,
+        totalPlans: r.total,
+        donePlans: r.done,
+        ready: r.ready,
+        blocked: r.blocked,
+      };
+    });
+  });
+}
+
+const FILTER_ALIASES: Record<string, StatusFilter> = {
+  all: 'all',
+  'in-progress': 'in-progress',
+  active: 'in-progress',
+  done: 'done',
+  completed: 'done',
+  superseded: 'superseded',
+  abandoned: 'abandoned',
+};
+
+export function parseFilter(raw: string): StatusFilter {
+  for (const token of raw.toLowerCase().split(/\s+/)) {
+    if (FILTER_ALIASES[token]) return FILTER_ALIASES[token];
+  }
+  return 'all';
+}
+
+export async function handleListInitiatives(
+  ctx: ExtensionCommandContext,
+  runPlanIO: RunPlanIO,
+  args?: string,
+): Promise<void> {
+  const items = await runPlanIO(loadInitiativeListItems());
+  if (items.length === 0) {
+    ctx.ui.notify('No initiatives found in .plans/initiatives.jsonl', 'info');
+    return;
+  }
+
+  let filter: StatusFilter = 'all';
+  if (args?.trim()) {
+    filter = parseFilter(args.trim());
+  } else {
+    const choice = await ctx.ui.select('Filter initiatives by status:', [
+      'All',
+      'In-progress',
+      'Done',
+      'Superseded',
+      'Abandoned',
+    ]);
+    if (!choice) return;
+    const map: Record<string, StatusFilter> = {
+      All: 'all',
+      'In-progress': 'in-progress',
+      Done: 'done',
+      Superseded: 'superseded',
+      Abandoned: 'abandoned',
+    };
+    filter = map[choice] ?? 'all';
+  }
+
+  const filtered = filterInitiatives(items, filter);
+  ctx.ui.notify(formatInitiativeList(filtered, filter), 'info');
+}

package/extensions/plan-mode/constants.ts

@@ -10,6 +10,7 @@ export const PLAN_TOOLS = [
   'find',
   'ls',
   'submit_plan',
+  'submit_initiative',
   'revise_plan',
   'preview_prototype',
   'write',
@@ -19,6 +20,8 @@ export const PLAN_TOOLS = [
   'plan_status',
   'set_active_plan',
   'update_plan',
+  'update_initiative',
+  'initiative_status',
   'reconcile_plans',
 ];
 
@@ -33,6 +36,8 @@ export const EXEC_TOOLS = [
   'plan_status',
   'set_active_plan',
   'update_plan',
+  'update_initiative',
+  'initiative_status',
   'reconcile_plans',
 ];