@dreki-gg/pi-plan-mode 0.27.0 → 0.27.3

package/CHANGELOG.md

@@ -1,5 +1,28 @@
 # @dreki-gg/pi-plan-mode
 
+## 0.27.3
+
+### Patch Changes
+
+- Require an explicit plan id on plan mutations so writes always target the intended plan.
+
+## 0.27.2
+
+### Patch Changes
+
+- `add_task` now rejects an empty or whitespace `plan` argument instead of
+  silently filing the follow-up onto whatever plan happens to be in-progress.
+  This prevents discovered tasks from being misfiled onto an unrelated plan
+  after a context switch — the agent is told to re-issue with an explicit plan.
+
+## 0.27.1
+
+### Patch Changes
+
+- Require an explicit `plan` argument on `add_task`, `update_task`, and `update_tasks` so writes are always scoped to the intended plan and can never be misfiled into whatever plan happened to be the active pin. Previously these tools would trust a stale in-memory active-plan pin (or silently fall back to some other in-progress plan) after the pinned plan finished, causing follow-ups to be filed against the wrong plan.
+
+  In addition, `resolveActivePlan` now drops a stale pin and reports the in-progress candidates instead of guessing when a pinned plan has completed while other plans are still in-progress. The pin is still honored when no other plan is in-progress.
+
 ## 0.27.0
 
 ### Minor Changes

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

@@ -62,6 +62,7 @@ describe('add_task tool', () => {
     await tool.execute('call-1', {
       description: 'Extract shared helper',
       reason: 'noticed duplication while editing',
+      plan: 'plan',
     });
 
     expect(added).toHaveLength(1);
@@ -73,11 +74,23 @@ describe('add_task tool', () => {
     expect(task.description).toBe('Extract shared helper');
   });
 
-  test('soft-skips (does not throw) when there is no active plan', async () => {
+  test('soft-skips (does not throw) when the named plan cannot be resolved', async () => {
     const { tool, added } = setup(undefined);
-    const result = await tool.execute('call-1', { description: 'x', reason: 'y' });
+    const result = await tool.execute('call-1', { description: 'x', reason: 'y', plan: 'plan' });
     expect((result.details as { skipped?: boolean }).skipped).toBe(true);
     expect(result.content?.[0]?.text).toMatch(/no active plan/i);
     expect(added).toHaveLength(0);
   });
+
+  test('throws when { plan } is missing or whitespace', async () => {
+    const plan = basePlan([planTask('t-001')]);
+    const { tool, added } = setup(plan);
+    await expect(tool.execute('call-1', { description: 'x', reason: 'y' })).rejects.toThrow(
+      /requires an explicit \{ plan \}/,
+    );
+    await expect(
+      tool.execute('call-2', { description: 'x', reason: 'y', plan: '   ' }),
+    ).rejects.toThrow(/requires an explicit \{ plan \}/);
+    expect(added).toHaveLength(0);
+  });
 });

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

@@ -133,6 +133,36 @@ describe('resolveActivePlan', () => {
     expect(state.planDir).toBe('.plans/beta');
   });
 
+  test('refuses a stale in-memory pin when other plans are in-progress (misfile guard)', async () => {
+    // The pinned plan has completed; two unrelated plans are still in-progress.
+    await seedPlan('alpha', 'done', ['t-001']);
+    await seedPlan('beta', 'in-progress', ['t-001']);
+    await seedPlan('gamma', 'in-progress', ['t-001']);
+    const state = new PlanModeState();
+    state.plan = { title: 'alpha', planName: 'alpha', handoff: '', tasks: [task('t-001')] };
+    state.planDir = '.plans/alpha';
+    const { pi } = fakePi();
+
+    const result = await resolveActivePlan(state, pi, runPlanIO);
+
+    // Must NOT silently file into the stale pin or guess one of the others.
+    expect(result.plan).toBeUndefined();
+    expect(result.candidates.sort()).toEqual(['beta', 'gamma']);
+  });
+
+  test('keeps a stale in-memory pin when no other plan is in-progress', async () => {
+    // Pin completed, nothing else live → safe to keep using it (no ambiguity).
+    await seedPlan('alpha', 'done', ['t-001']);
+    const state = new PlanModeState();
+    state.plan = { title: 'alpha', planName: 'alpha', handoff: '', tasks: [task('t-001')] };
+    state.planDir = '.plans/alpha';
+    const { pi } = fakePi();
+
+    const result = await resolveActivePlan(state, pi, runPlanIO);
+
+    expect(result.plan?.planName).toBe('alpha');
+  });
+
   test('ignores a done plan when auto-attaching', async () => {
     await seedPlan('alpha', 'done', ['t-001']);
     const state = new PlanModeState();

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

@@ -206,4 +206,16 @@ describe('revise_plan tool', () => {
     const [entry] = await runPlanIO(readPlansManifest());
     expect(entry.initiative).toBe('big');
   });
+
+  test('throws when { plan } is empty or whitespace', async () => {
+    const plan: PlanData = { title: 'P', planName: 'p', handoff: 'h', tasks: [task('t-001')] };
+    const { tool, revised } = setup(plan);
+    await expect(tool.execute('c', { plan: '', title: 'x' })).rejects.toThrow(
+      /requires an explicit \{ plan \}/,
+    );
+    await expect(tool.execute('c', { plan: '   ', title: 'x' })).rejects.toThrow(
+      /requires an explicit \{ plan \}/,
+    );
+    expect(revised).toHaveLength(0);
+  });
 });

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

@@ -56,20 +56,25 @@ const planTask = (id: string, status: TaskStatus = 'pending'): TaskRecord => ({
 describe('update_task tool', () => {
   test('marks a pending task and reports progress', async () => {
     const { tool, updates } = setup(basePlan([planTask('t-001'), planTask('t-002')]));
-    const result = await tool.execute('c', { task_id: 't-001', status: 'done', notes: 'did it' });
+    const result = await tool.execute('c', {
+      task_id: 't-001',
+      status: 'done',
+      notes: 'did it',
+      plan: 'plan',
+    });
     expect(updates).toEqual([{ taskId: 't-001', status: 'done', notes: 'did it' }]);
     expect(result.content?.[0]?.text).toMatch(/Progress: 1\/2/);
   });
 
   test('blocked terminates the turn', async () => {
     const { tool } = setup(basePlan([planTask('t-001')]));
-    const result = await tool.execute('c', { task_id: 't-001', status: 'blocked' });
+    const result = await tool.execute('c', { task_id: 't-001', status: 'blocked', plan: 'plan' });
     expect(result.terminate).toBe(true);
   });
 
   test('soft-skips (no throw) when there is no active plan', async () => {
     const { tool, updates } = setup(undefined, ['alpha', 'beta']);
-    const result = await tool.execute('c', { task_id: 't-001', status: 'done' });
+    const result = await tool.execute('c', { task_id: 't-001', status: 'done', plan: 'plan' });
     expect((result.details as { skipped?: boolean }).skipped).toBe(true);
     expect(result.content?.[0]?.text).toMatch(/alpha, beta/);
     expect(updates).toHaveLength(0);
@@ -77,7 +82,7 @@ describe('update_task tool', () => {
 
   test('soft result (no throw) for an unknown task id', async () => {
     const { tool, updates } = setup(basePlan([planTask('t-001')]));
-    const result = await tool.execute('c', { task_id: 't-999', status: 'done' });
+    const result = await tool.execute('c', { task_id: 't-999', status: 'done', plan: 'plan' });
     expect((result.details as { error?: string }).error).toBe('not_found');
     expect(result.content?.[0]?.text).toMatch(/t-001/);
     expect(updates).toHaveLength(0);
@@ -85,22 +90,33 @@ describe('update_task tool', () => {
 
   test('idempotent: re-marking the same status is a no-op success', async () => {
     const { tool, updates } = setup(basePlan([planTask('t-001', 'done')]));
-    const result = await tool.execute('c', { task_id: 't-001', status: 'done' });
+    const result = await tool.execute('c', { task_id: 't-001', status: 'done', plan: 'plan' });
     expect(result.content?.[0]?.text).toMatch(/no-op/);
     expect(updates).toHaveLength(0);
   });
 
   test('corrects an already-resolved task (done → skipped) and reports it', async () => {
     const { tool, updates } = setup(basePlan([planTask('t-001', 'done')]));
-    const result = await tool.execute('c', { task_id: 't-001', status: 'skipped' });
+    const result = await tool.execute('c', { task_id: 't-001', status: 'skipped', plan: 'plan' });
     expect(updates).toEqual([{ taskId: 't-001', status: 'skipped', notes: undefined }]);
     expect(result.content?.[0]?.text).toMatch(/corrected \(done → skipped\)/);
   });
 
   test('unblocks a task (blocked → done) without terminating', async () => {
     const { tool, updates } = setup(basePlan([planTask('t-001', 'blocked')]));
-    const result = await tool.execute('c', { task_id: 't-001', status: 'done' });
+    const result = await tool.execute('c', { task_id: 't-001', status: 'done', plan: 'plan' });
     expect(updates).toEqual([{ taskId: 't-001', status: 'done', notes: undefined }]);
     expect(result.terminate).toBeUndefined();
   });
+
+  test('throws when { plan } is missing or whitespace', async () => {
+    const { tool, updates } = setup(basePlan([planTask('t-001')]));
+    await expect(tool.execute('c', { task_id: 't-001', status: 'done' })).rejects.toThrow(
+      /requires an explicit \{ plan \}/,
+    );
+    await expect(
+      tool.execute('c', { task_id: 't-001', status: 'done', plan: '   ' }),
+    ).rejects.toThrow(/requires an explicit \{ plan \}/);
+    expect(updates).toHaveLength(0);
+  });
 });

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

@@ -66,6 +66,7 @@ describe('update_tasks tool', () => {
         { task_id: 't-001', status: 'done', notes: 'a' },
         { task_id: 't-002', status: 'skipped', notes: 'b' },
       ],
+      plan: 'plan',
     });
     expect(updates).toEqual([
       { taskId: 't-001', status: 'done', notes: 'a' },
@@ -79,7 +80,10 @@ describe('update_tasks tool', () => {
 
   test('soft-skips (no throw) when there is no active plan', async () => {
     const { tool, updates } = setup(undefined, ['alpha', 'beta']);
-    const result = await tool.execute('c', { updates: [{ task_id: 't-001', status: 'done' }] });
+    const result = await tool.execute('c', {
+      updates: [{ task_id: 't-001', status: 'done' }],
+      plan: 'plan',
+    });
     expect((result.details as { skipped?: boolean }).skipped).toBe(true);
     expect(result.content?.[0]?.text).toMatch(/alpha, beta/);
     expect(updates).toHaveLength(0);
@@ -92,6 +96,7 @@ describe('update_tasks tool', () => {
         { task_id: 't-001', status: 'done' },
         { task_id: 't-999', status: 'done' },
       ],
+      plan: 'plan',
     });
     expect(getWriteCount()).toBe(0);
   });
@@ -103,6 +108,7 @@ describe('update_tasks tool', () => {
         { task_id: 't-001', status: 'done' },
         { task_id: 't-999', status: 'done' },
       ],
+      plan: 'plan',
     });
     expect(updates).toEqual([{ taskId: 't-001', status: 'done', notes: undefined }]);
     const details = result.details as { results?: Array<{ task_id: string; outcome: string }> };
@@ -116,6 +122,7 @@ describe('update_tasks tool', () => {
         { task_id: 't-001', status: 'done' },
         { task_id: 't-002', status: 'done' },
       ],
+      plan: 'plan',
     });
     expect(updates).toEqual([{ taskId: 't-002', status: 'done', notes: undefined }]);
     const details = result.details as { results?: Array<{ task_id: string; outcome: string }> };
@@ -124,7 +131,21 @@ describe('update_tasks tool', () => {
 
   test('corrects an already-resolved task (done → skipped)', async () => {
     const { tool, updates } = setup(basePlan([planTask('t-001', 'done')]));
-    await tool.execute('c', { updates: [{ task_id: 't-001', status: 'skipped' }] });
+    await tool.execute('c', {
+      updates: [{ task_id: 't-001', status: 'skipped' }],
+      plan: 'plan',
+    });
     expect(updates).toEqual([{ taskId: 't-001', status: 'skipped', notes: undefined }]);
   });
+
+  test('throws when { plan } is missing or whitespace', async () => {
+    const { tool, updates } = setup(basePlan([planTask('t-001')]));
+    await expect(
+      tool.execute('c', { updates: [{ task_id: 't-001', status: 'done' }] }),
+    ).rejects.toThrow(/requires an explicit \{ plan \}/);
+    await expect(
+      tool.execute('c', { updates: [{ task_id: 't-001', status: 'done' }], plan: '   ' }),
+    ).rejects.toThrow(/requires an explicit \{ plan \}/);
+    expect(updates).toHaveLength(0);
+  });
 });

package/extensions/plan-mode/resolve-plan.ts

@@ -106,10 +106,27 @@ export async function resolveActivePlan(
   }
 
   // ── No hint: in-memory plan, else the single in-progress plan on disk ─────
-  if (state.plan) return { plan: state.plan, candidates: [] };
-
+  //
+  // IMPORTANT (misfile guard): a pinned `state.plan` must NOT be trusted blindly
+  // when it no longer corresponds to an in-progress plan. After a plan completes
+  // (e.g. `set_active_plan` then 6/6 done), a stale pin would silently capture
+  // writes — or the fallback would guess a different in-progress plan. Mirror
+  // `update_task`'s strictness: when the pin is stale AND other plans are still
+  // in-progress, REFUSE and force an explicit `{ plan }` rather than guess.
   const manifest = await runPlanIO(readPlansManifest());
   const inProgress = manifest.filter((entry) => entry.status === 'in-progress');
+
+  if (state.plan) {
+    const pinName = state.plan.planName;
+    const pinInProgress = inProgress.some((entry) => entry.name === pinName);
+    const competing = inProgress.filter((entry) => entry.name !== pinName);
+    // Trust the pin only when it is still in-progress, or when there is no other
+    // in-progress plan to confuse it with (e.g. an in-memory-only plan).
+    if (pinInProgress || competing.length === 0) return { plan: state.plan, candidates: [] };
+    // Stale pin with live competitors → ambiguous: require an explicit choice.
+    return { plan: undefined, candidates: inProgress.map((entry) => entry.name) };
+  }
+
   if (inProgress.length === 1) {
     const plan = await attach(state, pi, runPlanIO, inProgress[0]!.name);
     if (plan) return { plan, candidates: [] };

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

@@ -30,6 +30,7 @@ export function registerAddTaskTool(pi: ExtensionAPI, callbacks: AddTaskCallback
       'Use add_task when you notice worthwhile work outside the current plan while implementing.',
       'Discovered tasks are deferred for the user to review — do NOT implement them now; continue with the planned tasks.',
       'Give a clear reason so the user can decide whether the follow-up is worth doing.',
+      'Always pass an explicit { plan } (it is required) so the write is scoped to the intended plan — never rely on an implicit active-plan pin, which may have completed after a context switch.',
     ],
     parameters: Type.Object({
       description: Type.String({ description: 'Short task label (≤60 chars)' }),
@@ -40,15 +41,23 @@ 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.',
-        }),
-      ),
+      plan: Type.String({
+        description:
+          'Plan name (or .plans/<name>) to target. Required — always scope the capture explicitly so it never lands in the wrong plan.',
+      }),
     }),
 
     async execute(_toolCallId, params) {
+      // Hard-require an explicit plan: the schema marks it required, but an
+      // empty/whitespace value must never fall through to candidate resolution
+      // (that silently files the follow-up onto whatever plan happens to be
+      // in-progress — e.g. after the intended plan completed on a context
+      // switch). Throw so the agent re-issues with an explicit { plan }.
+      if (!params.plan || !params.plan.trim()) {
+        throw new Error(
+          'add_task requires an explicit { plan } — pass the plan name so the follow-up is never misfiled onto an unrelated in-progress plan.',
+        );
+      }
       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.

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

@@ -83,6 +83,15 @@ export function registerRevisePlanTool(
     }),
 
     async execute(_toolCallId, params) {
+      // Hard-require an explicit plan: an empty/whitespace value must never fall
+      // through to candidate resolution (that silently rewrites whatever plan
+      // happens to be in-progress — e.g. after the intended plan completed on a
+      // context switch). Throw so the agent re-issues with an explicit { plan }.
+      if (!params.plan || !params.plan.trim()) {
+        throw new Error(
+          'revise_plan requires an explicit { plan } — pass the plan name so the rewrite is never applied to an unrelated in-progress plan.',
+        );
+      }
       const { plan, candidates } = await callbacks.resolvePlan({ name: params.plan });
       if (!plan) {
         const notFound: Record<string, unknown> = {

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

@@ -35,6 +35,7 @@ export function registerUpdateTaskTool(pi: ExtensionAPI, callbacks: UpdateTaskCa
       'Call update_task after completing each plan task before moving to the next.',
       'Always include notes summarizing what was done, why skipped, or why blocked.',
       'Use update_task with status "blocked" and explain the reason in notes if a task cannot be completed.',
+      'Always pass an explicit { plan } (it is required) so the write is scoped to the intended plan — never rely on an implicit active-plan pin, which may have completed after a context switch.',
     ],
     parameters: Type.Object({
       task_id: Type.String({ description: 'Task ID (for example, t-001)' }),
@@ -42,15 +43,22 @@ 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.',
-        }),
-      ),
+      plan: Type.String({
+        description:
+          'Plan name (or .plans/<name>) to target. Required — always scope the write explicitly so it never lands in the wrong plan.',
+      }),
     }),
 
     async execute(_toolCallId, params) {
+      // Hard-require an explicit plan: an empty/whitespace value must never fall
+      // through to candidate resolution (that silently writes to whatever plan
+      // happens to be in-progress — e.g. after the intended plan completed on a
+      // context switch). Throw so the agent re-issues with an explicit { plan }.
+      if (!params.plan || !params.plan.trim()) {
+        throw new Error(
+          'update_task requires an explicit { plan } — pass the plan name so the write is never applied to an unrelated in-progress plan.',
+        );
+      }
       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.

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

@@ -69,15 +69,22 @@ export function registerUpdateTasksTool(pi: ExtensionAPI, callbacks: UpdateTasks
         }),
         { description: 'Tasks to mark, each with its own status and notes', minItems: 1 },
       ),
-      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.',
-        }),
-      ),
+      plan: Type.String({
+        description:
+          'Plan name (or .plans/<name>) to target. Required — always scope the write explicitly so it never lands in the wrong plan.',
+      }),
     }),
 
     async execute(_toolCallId, params) {
+      // Hard-require an explicit plan: an empty/whitespace value must never fall
+      // through to candidate resolution (that silently writes to whatever plan
+      // happens to be in-progress — e.g. after the intended plan completed on a
+      // context switch). Throw so the agent re-issues with an explicit { plan }.
+      if (!params.plan || !params.plan.trim()) {
+        throw new Error(
+          'update_tasks requires an explicit { plan } — pass the plan name so the writes are never applied to an unrelated in-progress plan.',
+        );
+      }
       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.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dreki-gg/pi-plan-mode",
-  "version": "0.27.0",
+  "version": "0.27.3",
   "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"
@@ -9,12 +9,12 @@
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "https://github.com/dreki-gg/pi-extensions",
+    "url": "git+https://github.com/dreki-gg/pi-extensions.git",
     "directory": "packages/plan-mode"
   },
   "type": "module",
   "bin": {
-    "pi-plan-mode": "./bin/clean-plans.js"
+    "pi-plan-mode": "bin/clean-plans.js"
   },
   "files": [
     "extensions",