@dreki-gg/pi-plan-mode 0.16.0 → 0.17.0

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # @dreki-gg/pi-plan-mode
 
+## 0.17.0
+
+### Minor Changes
+
+- Refactor storage/domain layer to Effect (tagged errors, Schema-based JSONL validation, a FileSystem service + runtime layer) and add beads-style discovered follow-up tasks.
+
+  During execution the agent can now call `add_task` to capture worthwhile out-of-plan work as a `deferred` follow-up (with a reason), without implementing it. Discovered follow-ups are surfaced at checkpoints (blocked pause and when planned work finishes), keep the plan in-progress, and are picked up when you choose "Continue execution" via `/plan resume`.
+
 ## 0.16.0
 
 ### Minor Changes

package/extensions/plan-mode/__tests__/add-task.test.ts

@@ -0,0 +1,75 @@
+import { describe, expect, test } from 'bun:test';
+import { registerAddTaskTool } from '../tools/add-task.js';
+import type { PlanData, TaskRecord } from '../types.js';
+
+const now = '2026-05-27T12:00:00.000Z';
+
+interface CapturedTool {
+  execute: (
+    id: string,
+    params: { description: string; reason: string; details?: string; depends_on?: string[] },
+  ) => Promise<{ details?: unknown }>;
+}
+
+function setup(plan: PlanData | undefined) {
+  let tool: CapturedTool | undefined;
+  const added: TaskRecord[] = [];
+  const pi = {
+    registerTool: (config: CapturedTool) => {
+      tool = config;
+    },
+  } as unknown as Parameters<typeof registerAddTaskTool>[0];
+
+  registerAddTaskTool(pi, {
+    getPlan: () => plan,
+    onTaskAdded: (task) => {
+      added.push(task);
+    },
+  });
+
+  return { tool: tool!, added };
+}
+
+const basePlan = (tasks: TaskRecord[]): PlanData => ({
+  title: 'Plan',
+  planName: 'plan',
+  handoff: '',
+  tasks,
+});
+
+const planTask = (id: string): TaskRecord => ({
+  _type: 'task',
+  id,
+  description: 'planned',
+  status: 'done',
+  origin: 'plan',
+  created_at: now,
+  updated_at: now,
+});
+
+describe('add_task tool', () => {
+  test('captures a deferred discovered task with a generated id and reason as notes', async () => {
+    const plan = basePlan([planTask('t-001'), planTask('t-002')]);
+    const { tool, added } = setup(plan);
+
+    await tool.execute('call-1', {
+      description: 'Extract shared helper',
+      reason: 'noticed duplication while editing',
+    });
+
+    expect(added).toHaveLength(1);
+    const task = added[0];
+    expect(task.id).toBe('t-003');
+    expect(task.status).toBe('deferred');
+    expect(task.origin).toBe('discovered');
+    expect(task.notes).toBe('noticed duplication while editing');
+    expect(task.description).toBe('Extract shared helper');
+  });
+
+  test('throws when there is no active plan', async () => {
+    const { tool } = setup(undefined);
+    await expect(tool.execute('call-1', { description: 'x', reason: 'y' })).rejects.toThrow(
+      /No active plan/,
+    );
+  });
+});

package/extensions/plan-mode/__tests__/atomic-write.test.ts

@@ -1,4 +1,5 @@
 import { afterEach, beforeEach, describe, expect, test } from 'bun:test';
+import { Effect, Exit } from 'effect';
 import { mkdtemp, readFile, rm, writeFile } from 'node:fs/promises';
 import { join } from 'node:path';
 import { tmpdir } from 'node:os';
@@ -18,7 +19,7 @@ describe('writeFileAtomic', () => {
   test('writes complete content to the target path', async () => {
     const target = join(dir, 'data.txt');
 
-    await writeFileAtomic(target, 'hello world');
+    await Effect.runPromise(writeFileAtomic(target, 'hello world'));
 
     expect(await readFile(target, 'utf8')).toBe('hello world');
   });
@@ -27,17 +28,18 @@ describe('writeFileAtomic', () => {
     const target = join(dir, 'data.txt');
     await writeFile(target, 'old');
 
-    await writeFileAtomic(target, 'new');
+    await Effect.runPromise(writeFileAtomic(target, 'new'));
 
     expect(await readFile(target, 'utf8')).toBe('new');
   });
 
-  test('leaves target untouched when writing fails before rename', async () => {
+  test('fails with PlanWriteError and leaves target untouched when the write fails', async () => {
     const target = join(dir, 'data.txt');
     await writeFile(target, 'original');
 
-    await expect(writeFileAtomic(target, 'next', { mode: 0o400 })).rejects.toThrow();
+    const exit = await Effect.runPromiseExit(writeFileAtomic(target, 'next', { mode: 0o400 }));
 
+    expect(Exit.isFailure(exit)).toBe(true);
     expect(await readFile(target, 'utf8')).toBe('original');
   });
 });

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

@@ -0,0 +1,57 @@
+import { afterEach, beforeEach, describe, expect, test } from 'bun:test';
+import { Effect } from 'effect';
+import { chdir } from 'node:process';
+import { mkdtemp, rm } from 'node:fs/promises';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+import { FileSystem, nodeFileSystemService } from '../effects/filesystem.js';
+import {
+  loadHandoff,
+  readAndClearExecPending,
+  saveHandoff,
+  writeExecPending,
+} from '../storage/plan-storage.js';
+import type { ExecPendingConfig } from '../types.js';
+
+const run = <A, E>(program: Effect.Effect<A, E, FileSystem>): Promise<A> =>
+  Effect.runPromise(program.pipe(Effect.provideService(FileSystem, nodeFileSystemService)));
+
+const originalCwd = process.cwd();
+let dir: string;
+const config: ExecPendingConfig = { model: { provider: 'anthropic', id: 'opus' }, thinking: 'low' };
+
+beforeEach(async () => {
+  dir = await mkdtemp(join(tmpdir(), 'plan-mode-plan-'));
+  chdir(dir);
+});
+afterEach(async () => {
+  chdir(originalCwd);
+  await rm(dir, { recursive: true, force: true });
+});
+
+describe('handoff documents', () => {
+  test('round trips handoff content', async () => {
+    await run(saveHandoff('.plans/p', '# Handoff'));
+    await expect(run(loadHandoff('.plans/p'))).resolves.toBe('# Handoff');
+  });
+
+  test('missing handoff returns undefined', async () => {
+    await expect(run(loadHandoff('.plans/missing'))).resolves.toBeUndefined();
+  });
+});
+
+describe('exec-pending markers', () => {
+  test('writes, reads, and clears a marker', async () => {
+    await run(writeExecPending('.plans/p', config));
+    const first = await run(readAndClearExecPending());
+    expect(first?.planDir).toBe('.plans/p');
+    expect(first?.config).toEqual(config);
+
+    // Marker is cleared after reading.
+    await expect(run(readAndClearExecPending())).resolves.toBeUndefined();
+  });
+
+  test('returns undefined when .plans does not exist', async () => {
+    await expect(run(readAndClearExecPending())).resolves.toBeUndefined();
+  });
+});

package/extensions/plan-mode/__tests__/plans-manifest.test.ts

@@ -1,14 +1,19 @@
 import { afterEach, beforeEach, describe, expect, test } from 'bun:test';
+import { Effect } from 'effect';
 import { chdir } from 'node:process';
 import { mkdtemp, rm } from 'node:fs/promises';
 import { join } from 'node:path';
 import { tmpdir } from 'node:os';
+import { FileSystem, nodeFileSystemService } from '../effects/filesystem.js';
 import {
   readPlansManifest,
   upsertPlanEntry,
   writePlansManifest,
 } from '../storage/plans-manifest.js';
 
+const run = <A, E>(program: Effect.Effect<A, E, FileSystem>): Promise<A> =>
+  Effect.runPromise(program.pipe(Effect.provideService(FileSystem, nodeFileSystemService)));
+
 const originalCwd = process.cwd();
 let dir: string;
 
@@ -31,31 +36,37 @@ describe('plans.jsonl manifest', () => {
       created_at: 'now',
       completed_at: null,
     };
-    await writePlansManifest([entry]);
-    await expect(readPlansManifest()).resolves.toEqual([entry]);
+    await run(writePlansManifest([entry]));
+    await expect(run(readPlansManifest())).resolves.toEqual([entry]);
+  });
+
+  test('missing manifest returns an empty list', async () => {
+    await expect(run(readPlansManifest())).resolves.toEqual([]);
   });
 
   test('upserts new entries', async () => {
-    await upsertPlanEntry('new-plan', { status: 'in-progress', title: 'New Plan' });
-    const entries = await readPlansManifest();
+    await run(upsertPlanEntry('new-plan', { status: 'in-progress', title: 'New Plan' }));
+    const entries = await run(readPlansManifest());
     expect(entries).toHaveLength(1);
     expect(entries[0]?.name).toBe('new-plan');
     expect(entries[0]?.title).toBe('New Plan');
   });
 
   test('upserts existing entries without changing created_at', async () => {
-    await writePlansManifest([
-      {
-        _type: 'plan',
-        name: 'p',
-        status: 'in-progress',
-        title: 'Old',
-        created_at: 'created',
-        completed_at: null,
-      },
-    ]);
-    await upsertPlanEntry('p', { status: 'done', title: 'New' });
-    const [entry] = await readPlansManifest();
+    await run(
+      writePlansManifest([
+        {
+          _type: 'plan',
+          name: 'p',
+          status: 'in-progress',
+          title: 'Old',
+          created_at: 'created',
+          completed_at: null,
+        },
+      ]),
+    );
+    await run(upsertPlanEntry('p', { status: 'done', title: 'New' }));
+    const [entry] = await run(readPlansManifest());
     expect(entry.created_at).toBe('created');
     expect(entry.status).toBe('done');
     expect(entry.completed_at).toBeString();

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

@@ -0,0 +1,212 @@
+import { describe, expect, test } from 'bun:test';
+import { Either } from 'effect';
+import {
+  decodeExecPendingConfig,
+  decodePlanManifestEntry,
+  decodeTaskMeta,
+  decodeTaskRecord,
+  decodeTasksLine,
+} from '../schema.js';
+
+const now = '2026-05-27T12:00:00.000Z';
+
+const isOk = (value: unknown, decode: (v: unknown) => Either.Either<unknown, unknown>): boolean =>
+  Either.isRight(decode(value));
+
+describe('task record schema', () => {
+  test('accepts a full task record', () => {
+    expect(
+      isOk(
+        {
+          _type: 'task',
+          id: 't-001',
+          description: 'Do work',
+          details: 'Full instructions',
+          status: 'pending',
+          depends_on: ['t-000'],
+          notes: 'note',
+          created_at: now,
+          updated_at: now,
+        },
+        decodeTaskRecord,
+      ),
+    ).toBe(true);
+  });
+
+  test('accepts a lightweight task record without details', () => {
+    expect(
+      isOk(
+        {
+          _type: 'task',
+          id: 't-001',
+          description: 'Do work',
+          status: 'pending',
+          created_at: now,
+          updated_at: now,
+        },
+        decodeTaskRecord,
+      ),
+    ).toBe(true);
+  });
+
+  test('accepts a deferred discovered task', () => {
+    expect(
+      isOk(
+        {
+          _type: 'task',
+          id: 't-011',
+          description: 'Follow-up discovered mid-run',
+          status: 'deferred',
+          origin: 'discovered',
+          notes: 'noticed while implementing',
+          created_at: now,
+          updated_at: now,
+        },
+        decodeTaskRecord,
+      ),
+    ).toBe(true);
+  });
+
+  test('rejects an unknown origin', () => {
+    expect(
+      isOk(
+        {
+          _type: 'task',
+          id: 't-001',
+          description: 'Do work',
+          status: 'pending',
+          origin: 'bogus',
+          created_at: now,
+          updated_at: now,
+        },
+        decodeTaskRecord,
+      ),
+    ).toBe(false);
+  });
+
+  test('rejects missing fields and unknown status', () => {
+    expect(isOk({ _type: 'task', id: 't-001', status: 'pending' }, decodeTaskRecord)).toBe(false);
+    expect(
+      isOk(
+        {
+          _type: 'task',
+          id: 't-001',
+          description: 'Do work',
+          status: 'unknown',
+          created_at: now,
+          updated_at: now,
+        },
+        decodeTaskRecord,
+      ),
+    ).toBe(false);
+  });
+});
+
+describe('task meta schema', () => {
+  test('accepts a valid meta record', () => {
+    expect(
+      isOk(
+        { _type: 'meta', title: 'Refactor', plan_name: 'refactor', created_at: now },
+        decodeTaskMeta,
+      ),
+    ).toBe(true);
+  });
+
+  test('rejects malformed meta records', () => {
+    expect(isOk({ _type: 'meta', title: 'Refactor' }, decodeTaskMeta)).toBe(false);
+    expect(
+      isOk(
+        { _type: 'task', title: 'Refactor', plan_name: 'refactor', created_at: now },
+        decodeTaskMeta,
+      ),
+    ).toBe(false);
+  });
+});
+
+describe('tasks.jsonl line schema (meta | task union)', () => {
+  test('discriminates meta from task', () => {
+    const meta = decodeTasksLine({ _type: 'meta', title: 'T', plan_name: 'p', created_at: now });
+    const task = decodeTasksLine({
+      _type: 'task',
+      id: 't-001',
+      description: 'Do work',
+      status: 'pending',
+      created_at: now,
+      updated_at: now,
+    });
+    expect(Either.isRight(meta) && Either.getOrThrow(meta)._type).toBe('meta');
+    expect(Either.isRight(task) && Either.getOrThrow(task)._type).toBe('task');
+  });
+
+  test('round-trips a deferred discovered task', () => {
+    const decoded = decodeTasksLine({
+      _type: 'task',
+      id: 't-011',
+      description: 'Follow-up',
+      status: 'deferred',
+      origin: 'discovered',
+      created_at: now,
+      updated_at: now,
+    });
+    expect(Either.isRight(decoded)).toBe(true);
+    if (Either.isRight(decoded) && decoded.right._type === 'task') {
+      expect(decoded.right.status).toBe('deferred');
+      expect(decoded.right.origin).toBe('discovered');
+    }
+  });
+
+  test('rejects records with an unknown _type', () => {
+    expect(isOk({ _type: 'bogus' }, decodeTasksLine)).toBe(false);
+  });
+});
+
+describe('plan manifest entry schema', () => {
+  test('accepts a valid entry with null completed_at', () => {
+    expect(
+      isOk(
+        {
+          _type: 'plan',
+          name: 'plan',
+          status: 'in-progress',
+          title: 'Plan',
+          created_at: now,
+          completed_at: null,
+        },
+        decodePlanManifestEntry,
+      ),
+    ).toBe(true);
+  });
+
+  test('rejects an invalid status', () => {
+    expect(
+      isOk(
+        {
+          _type: 'plan',
+          name: 'plan',
+          status: 'paused',
+          title: 'Plan',
+          created_at: now,
+          completed_at: null,
+        },
+        decodePlanManifestEntry,
+      ),
+    ).toBe(false);
+  });
+});
+
+describe('exec pending config schema', () => {
+  test('accepts a valid config', () => {
+    expect(
+      isOk(
+        { model: { provider: 'anthropic', id: 'opus' }, thinking: 'low' },
+        decodeExecPendingConfig,
+      ),
+    ).toBe(true);
+  });
+
+  test('rejects a config missing the model id', () => {
+    expect(
+      isOk({ model: { provider: 'anthropic' }, thinking: 'low' }, decodeExecPendingConfig),
+    ).toBe(false);
+  });
+});

package/extensions/plan-mode/__tests__/task-status.test.ts

@@ -0,0 +1,74 @@
+import { describe, expect, test } from 'bun:test';
+import {
+  activeTasksResolved,
+  deferredTasks,
+  isPlanFinalizable,
+  reactivateForExecution,
+} from '../task-status.js';
+import type { TaskRecord, TaskStatus } from '../types.js';
+
+const now = '2026-05-27T12:00:00.000Z';
+let counter = 0;
+const make = (status: TaskStatus, origin?: 'plan' | 'discovered'): TaskRecord => ({
+  _type: 'task',
+  id: `t-${String(++counter).padStart(3, '0')}`,
+  description: 'task',
+  status,
+  origin,
+  created_at: now,
+  updated_at: now,
+});
+
+describe('deferredTasks', () => {
+  test('returns only deferred tasks', () => {
+    const tasks = [make('done'), make('deferred', 'discovered'), make('pending')];
+    expect(deferredTasks(tasks).map((t) => t.status)).toEqual(['deferred']);
+  });
+});
+
+describe('activeTasksResolved', () => {
+  test('true when only done/skipped/deferred remain', () => {
+    expect(
+      activeTasksResolved([make('done'), make('skipped'), make('deferred', 'discovered')]),
+    ).toBe(true);
+  });
+
+  test('false when a task is still pending', () => {
+    expect(activeTasksResolved([make('done'), make('pending')])).toBe(false);
+  });
+
+  test('false when a task is still blocked', () => {
+    expect(activeTasksResolved([make('done'), make('blocked')])).toBe(false);
+  });
+});
+
+describe('isPlanFinalizable', () => {
+  test('true when all work is done/skipped and nothing is deferred', () => {
+    expect(isPlanFinalizable([make('done'), make('skipped')])).toBe(true);
+  });
+
+  test('false when a deferred follow-up awaits the user', () => {
+    expect(isPlanFinalizable([make('done'), make('deferred', 'discovered')])).toBe(false);
+  });
+
+  test('false when active work remains', () => {
+    expect(isPlanFinalizable([make('pending')])).toBe(false);
+  });
+});
+
+describe('reactivateForExecution', () => {
+  test('flips blocked and deferred tasks to pending and stamps updated_at', () => {
+    const tasks = [make('done'), make('blocked'), make('deferred', 'discovered')];
+    const ts = '2026-06-01T00:00:00.000Z';
+    const changed = reactivateForExecution(tasks, ts);
+    expect(changed).toBe(true);
+    expect(tasks.map((t) => t.status)).toEqual(['done', 'pending', 'pending']);
+    expect(tasks[1].updated_at).toBe(ts);
+    expect(tasks[2].updated_at).toBe(ts);
+  });
+
+  test('returns false and leaves tasks untouched when nothing to reactivate', () => {
+    const tasks = [make('done'), make('pending')];
+    expect(reactivateForExecution(tasks, '2026-06-01T00:00:00.000Z')).toBe(false);
+  });
+});

package/extensions/plan-mode/__tests__/task-storage.test.ts

@@ -1,10 +1,26 @@
 import { afterEach, beforeEach, describe, expect, test } from 'bun:test';
+import { Cause, Effect, Exit, Option } from 'effect';
 import { mkdtemp, rm } from 'node:fs/promises';
 import { join } from 'node:path';
 import { tmpdir } from 'node:os';
+import { FileSystem, nodeFileSystemService } from '../effects/filesystem.js';
 import { readTasksJsonl, updateTask, writeTasksJsonl } from '../storage/task-storage.js';
 import type { TaskMeta, TaskRecord } from '../types.js';
 
+const run = <A, E>(program: Effect.Effect<A, E, FileSystem>): Promise<A> =>
+  Effect.runPromise(program.pipe(Effect.provideService(FileSystem, nodeFileSystemService)));
+
+const runExit = <A, E>(program: Effect.Effect<A, E, FileSystem>) =>
+  Effect.runPromiseExit(program.pipe(Effect.provideService(FileSystem, nodeFileSystemService)));
+
+const failureTag = <A, E>(exit: Exit.Exit<A, E>): string | undefined => {
+  if (!Exit.isFailure(exit)) return undefined;
+  const error = Option.getOrUndefined(Cause.failureOption(exit.cause)) as
+    | { _tag?: string }
+    | undefined;
+  return error?._tag;
+};
+
 let dir: string;
 const now = '2026-05-27T12:00:00.000Z';
 const meta: TaskMeta = { _type: 'meta', title: 'Plan', plan_name: 'plan', created_at: now };
@@ -27,8 +43,8 @@ afterEach(async () => {
 
 describe('tasks.jsonl storage', () => {
   test('round trips meta and tasks', async () => {
-    await writeTasksJsonl(dir, meta, [task]);
-    await expect(readTasksJsonl(dir)).resolves.toEqual({ meta, tasks: [task] });
+    await run(writeTasksJsonl(dir, meta, [task]));
+    await expect(run(readTasksJsonl(dir))).resolves.toEqual({ meta, tasks: [task] });
   });
 
   test('round trips tasks without details (lightweight checklist)', async () => {
@@ -40,32 +56,39 @@ describe('tasks.jsonl storage', () => {
       created_at: now,
       updated_at: now,
     };
-    await writeTasksJsonl(dir, meta, [lightweight]);
-    const result = await readTasksJsonl(dir);
+    await run(writeTasksJsonl(dir, meta, [lightweight]));
+    const result = await run(readTasksJsonl(dir));
     expect(result?.tasks[0]?.id).toBe('t-002');
     expect(result?.tasks[0]?.details).toBeUndefined();
   });
 
   test('missing file returns undefined', async () => {
-    await expect(readTasksJsonl(dir)).resolves.toBeUndefined();
+    await expect(run(readTasksJsonl(dir))).resolves.toBeUndefined();
   });
 
-  test('rejects corrupt lines', async () => {
+  test('rejects corrupt lines with JsonlParseError', async () => {
     await Bun.write(join(dir, 'tasks.jsonl'), `${JSON.stringify(meta)}\nnot-json\n`);
-    await expect(readTasksJsonl(dir)).rejects.toThrow(/Invalid JSONL/);
+    expect(failureTag(await runExit(readTasksJsonl(dir)))).toBe('JsonlParseError');
   });
 
-  test('rejects empty files', async () => {
+  test('rejects empty files with MissingMetaRecord', async () => {
     await Bun.write(join(dir, 'tasks.jsonl'), '');
-    await expect(readTasksJsonl(dir)).rejects.toThrow(/meta/);
+    expect(failureTag(await runExit(readTasksJsonl(dir)))).toBe('MissingMetaRecord');
   });
 
   test('updates a task by id and rewrites the snapshot', async () => {
-    await writeTasksJsonl(dir, meta, [task]);
-    const updated = await updateTask(dir, 't-001', { status: 'done', notes: 'finished' });
+    await run(writeTasksJsonl(dir, meta, [task]));
+    const updated = await run(updateTask(dir, 't-001', { status: 'done', notes: 'finished' }));
 
     expect(updated.status).toBe('done');
     expect(updated.notes).toBe('finished');
-    expect((await readTasksJsonl(dir))?.tasks[0]?.status).toBe('done');
+    expect((await run(readTasksJsonl(dir)))?.tasks[0]?.status).toBe('done');
+  });
+
+  test('fails with TaskNotFound for an unknown task id', async () => {
+    await run(writeTasksJsonl(dir, meta, [task]));
+    expect(failureTag(await runExit(updateTask(dir, 't-999', { status: 'done' })))).toBe(
+      'TaskNotFound',
+    );
   });
 });

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

@@ -1,5 +1,23 @@
 import { describe, expect, test } from 'bun:test';
-import { isSafeCommand, isPlanPath } from '../utils.js';
+import { isSafeCommand, isPlanPath, nextTaskId } from '../utils.js';
+
+describe('nextTaskId', () => {
+  test('increments the max numeric suffix', () => {
+    expect(nextTaskId(['t-001', 't-002', 't-003'])).toBe('t-004');
+  });
+
+  test('uses the max even when ids are unordered or sparse', () => {
+    expect(nextTaskId(['t-003', 't-001', 't-010'])).toBe('t-011');
+  });
+
+  test('starts at t-001 for an empty plan', () => {
+    expect(nextTaskId([])).toBe('t-001');
+  });
+
+  test('falls back to count+1 when no ids match the pattern', () => {
+    expect(nextTaskId(['setup', 'cleanup'])).toBe('t-003');
+  });
+});
 
 describe('isSafeCommand', () => {
   // ── Commands that SHOULD be allowed ──────────────────────────────────────

package/extensions/plan-mode/constants.ts

@@ -17,7 +17,7 @@ export const PLAN_TOOLS = [
   'subagent',
 ];
 
-export const EXEC_TOOLS = ['read', 'bash', 'edit', 'write', 'update_task'];
+export const EXEC_TOOLS = ['read', 'bash', 'edit', 'write', 'update_task', 'add_task'];
 
 // ── Model + thinking presets ─────────────────────────────────────────────────
 export const PLAN_MODEL = { provider: 'anthropic', id: 'claude-opus-4-6' } as const;