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

package/CHANGELOG.md

@@ -1,5 +1,44 @@
 # @dreki-gg/pi-plan-mode
 
+## 0.28.0
+
+### Minor Changes
+
+- Add a precondition gate that stops "delete X, it's unused" plan drift. Any task
+  that deletes, removes, renames, or narrows a codebase symbol/export/file/feature
+  must now carry a re-runnable proof of its premise — a `Proof: <command>` line
+  (grep/ast-grep over every exported symbol, scoped by feature not directory) or
+  an explicit `Precondition: none — <reason>` opt-out. The rule is hoisted to the
+  top of the planner prompt and enforced deterministically: `submit_plan` refuses
+  to persist a plan whose destructive tasks lack proof, naming the offending task
+  ids so you can fix and resubmit. No LLM call, no reviewer side effect. At
+  execution time the proof is re-run, and a contradicted premise (live consumers,
+  a delete that breaks an import) blocks instead of being silently improvised
+  around.
+
+## 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__/precondition-guard.test.ts

@@ -0,0 +1,99 @@
+import { describe, expect, test } from 'bun:test';
+import {
+  detectPreconditionGaps,
+  isDestructiveTaskText,
+  hasPreconditionProof,
+  formatPreconditionRejection,
+} from '../precondition-guard.js';
+
+describe('isDestructiveTaskText', () => {
+  test('fires on destructive verb + symbol target', () => {
+    expect(isDestructiveTaskText('Remove the `AuthProvider` export')).toBe(true);
+    expect(isDestructiveTaskText('Delete the previewCandidatesOp operation')).toBe(true);
+  });
+
+  test('fires on destructive verb + file path', () => {
+    expect(isDestructiveTaskText('Delete src/auth/middleware.ts')).toBe(true);
+  });
+
+  test('does NOT fire on destructive verb with no codebase target', () => {
+    expect(isDestructiveTaskText('Remove the TODO comment')).toBe(false);
+    expect(isDestructiveTaskText('Delete the temporary value we created')).toBe(false);
+  });
+
+  test('does NOT fire on non-destructive task', () => {
+    expect(isDestructiveTaskText('Add a new export to the schema module')).toBe(false);
+  });
+});
+
+describe('hasPreconditionProof', () => {
+  test('accepts a Precondition: marker (incl. opt-out)', () => {
+    expect(hasPreconditionProof('Precondition: none — never imported anywhere')).toBe(true);
+  });
+  test('accepts a Proof: marker', () => {
+    expect(hasPreconditionProof('Proof: ran the grep, zero hits')).toBe(true);
+  });
+  test('accepts an actual search command', () => {
+    expect(hasPreconditionProof('rg "AuthProvider" -l shows no consumers')).toBe(true);
+    expect(hasPreconditionProof('ast-grep verifies no callers')).toBe(true);
+  });
+  test('rejects prose with no proof signal', () => {
+    expect(hasPreconditionProof('this is unused so delete it')).toBe(false);
+  });
+});
+
+describe('detectPreconditionGaps', () => {
+  test('flags a destructive task lacking proof', () => {
+    const gaps = detectPreconditionGaps([
+      { id: 't-005', description: 'Delete core viewer schema', details: 'it has zero consumers' },
+    ]);
+    expect(gaps.map((g) => g.id)).toEqual(['t-005']);
+  });
+
+  test('passes a destructive task WITH a proof command', () => {
+    const gaps = detectPreconditionGaps([
+      {
+        id: 't-005',
+        description: 'Delete the `ViewerConfig` export',
+        details: 'Proof: rg "ViewerConfig|Viewer3DConfig|ViewerSceneConfig" -l → no hits',
+      },
+    ]);
+    expect(gaps).toHaveLength(0);
+  });
+
+  test('passes a destructive task WITH an explicit opt-out', () => {
+    const gaps = detectPreconditionGaps([
+      {
+        id: 't-003',
+        description: 'Remove the legacy preview command',
+        details: 'Precondition: none — added this session, never wired to anything',
+      },
+    ]);
+    expect(gaps).toHaveLength(0);
+  });
+
+  test('ignores non-destructive tasks entirely', () => {
+    const gaps = detectPreconditionGaps([
+      { id: 't-001', description: 'Add auth middleware', details: 'create src/auth/mw.ts' },
+      { id: 't-002', description: 'Remove the TODO comment in README' },
+    ]);
+    expect(gaps).toHaveLength(0);
+  });
+
+  test('reports multiple gaps', () => {
+    const gaps = detectPreconditionGaps([
+      { id: 't-001', description: 'Delete src/old.ts' },
+      { id: 't-002', description: 'Rename the `Foo` interface to Bar' },
+    ]);
+    expect(gaps.map((g) => g.id)).toEqual(['t-001', 't-002']);
+  });
+});
+
+describe('formatPreconditionRejection', () => {
+  test('names offending ids and the escape hatch', () => {
+    const msg = formatPreconditionRejection([{ id: 't-005', matched: 'Delete' }]);
+    expect(msg).toContain('t-005');
+    expect(msg).toContain('Precondition: none');
+    expect(msg).toContain('submit_plan again');
+  });
+});

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

@@ -28,6 +28,13 @@ describe('buildPlanModePrompt', () => {
     expect(prompt).toContain('STOP conditions');
   });
 
+  test('hoists the precondition gate and flags it as enforced', () => {
+    expect(prompt).toContain('PRECONDITION GATE');
+    expect(prompt).toMatch(/submit_plan will REJECT/i);
+    expect(prompt).toContain('Precondition: none');
+    expect(prompt).toMatch(/FEATURE, not directory/i);
+  });
+
   test('mentions handoff instead of context and risks', () => {
     expect(prompt).toContain('handoff');
     expect(prompt).not.toContain('- risks:');

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__/submit-plan.test.ts

@@ -17,7 +17,7 @@ interface SubmitParams {
   name: string;
   title: string;
   handoff: string;
-  tasks: Array<{ id: string; description: string }>;
+  tasks: Array<{ id: string; description: string; details?: string }>;
   initiative?: string;
   depends_on_plans?: string[];
 }
@@ -58,6 +58,47 @@ afterEach(async () => {
   await rm(dir, { recursive: true, force: true });
 });
 
+describe('submit_plan tool — precondition gate', () => {
+  test('rejects a destructive task with no proof and persists nothing', async () => {
+    const tool = setup();
+    const res = await tool.execute(
+      'c',
+      baseParams({ tasks: [{ id: 't-001', description: 'Delete the `AuthProvider` export' }] }),
+    );
+    expect(res.content?.[0]?.text).toContain('precondition gate failed');
+    expect((res.details as { rejected?: boolean }).rejected).toBe(true);
+    // Nothing written to the registry.
+    const entries = await runPlanIO(readPlansManifest());
+    expect(entries).toHaveLength(0);
+  });
+
+  test('accepts a destructive task that carries a proof command', async () => {
+    const tool = setup();
+    const res = await tool.execute(
+      'c',
+      baseParams({
+        tasks: [
+          {
+            id: 't-001',
+            description: 'Delete the `AuthProvider` export',
+            details: 'Proof: rg "AuthProvider" -l → no consumers',
+          },
+        ],
+      }),
+    );
+    expect((res.details as { rejected?: boolean }).rejected).toBeUndefined();
+    const entries = await runPlanIO(readPlansManifest());
+    expect(entries).toHaveLength(1);
+  });
+
+  test('accepts a non-destructive task untouched', async () => {
+    const tool = setup();
+    await tool.execute('c', baseParams());
+    const entries = await runPlanIO(readPlansManifest());
+    expect(entries).toHaveLength(1);
+  });
+});
+
 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' }));

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/precondition-guard.ts

@@ -0,0 +1,83 @@
+/**
+ * Deterministic precondition guard for submit_plan.
+ *
+ * Catches "destructive premise without proof" drift at plan-submission time:
+ * a task that deletes/removes/renames a codebase symbol/path but carries no
+ * re-runnable consumer-proof command (or an explicit, auditable opt-out).
+ *
+ * Pure string heuristics — NO LLM, no reviewer agent, no I/O. The trigger is
+ * intentionally narrow (destructive verb AND a codebase-scoped target) to
+ * avoid false-positive fatigue, which is the failure mode that makes guards
+ * get ignored.
+ */
+
+/** A destructive action verb applied to code. */
+const DESTRUCTIVE =
+  /\b(delete|deletes|deleting|remove|removes|removing|rename|renames|renaming|drop|drops|dropping|strip|strips|stripping|purge|purges|purging|deprecate|deprecates|deprecating|unregister|unregisters)\b|\b(rip|tear)\s+out\b/i;
+
+/**
+ * A codebase-scoped target: a backticked identifier, a file path, a known code
+ * file extension, or a code-construct noun. Generic words like "file" alone are
+ * deliberately excluded — file-ish targets must show up as a path/extension/
+ * backtick — to keep "delete the temp file" from tripping the guard.
+ */
+const CODEBASE_TARGET =
+  /`[^`]+`|\b[\w.-]+\/[\w./-]+|\.(ts|tsx|js|jsx|mjs|cjs|json|md|css|scss|html|py|go|rs|java|rb|sql|ya?ml|toml)\b|\b(export|exports|import|imports|function|class|interface|type|schema|module|component|route|endpoint|operation|command|setting|settings|config|field|enum|const|method|prop|props|symbol|package|namespace|hook|reducer|selector|migration)s?\b/i;
+
+/**
+ * Proof or auditable opt-out signal. A `Precondition:`/`Proof:` marker (the
+ * opt-out form is `Precondition: none — <reason>`), or an actual search command
+ * that establishes the consumer set.
+ */
+const PROOF = /\b(precondition|proof)\b\s*:|\b(grep|rg|ripgrep|ast-grep|ast_grep)\b/i;
+
+export interface PreconditionGap {
+  id: string;
+  /** The destructive verb phrase that triggered the check. */
+  matched: string;
+}
+
+/** Returns true when text describes a destructive change to a codebase target. */
+export function isDestructiveTaskText(text: string): boolean {
+  return DESTRUCTIVE.test(text) && CODEBASE_TARGET.test(text);
+}
+
+/** Returns true when text carries a proof command or an auditable opt-out. */
+export function hasPreconditionProof(text: string): boolean {
+  return PROOF.test(text);
+}
+
+/**
+ * Find tasks that describe a destructive codebase change but carry no proof
+ * command or opt-out. Scans description + details together.
+ */
+export function detectPreconditionGaps(
+  tasks: ReadonlyArray<{ id: string; description: string; details?: string }>,
+): PreconditionGap[] {
+  const gaps: PreconditionGap[] = [];
+  for (const task of tasks) {
+    const text = `${task.description}\n${task.details ?? ''}`;
+    if (!isDestructiveTaskText(text)) continue;
+    if (hasPreconditionProof(text)) continue;
+    const matched = DESTRUCTIVE.exec(text)?.[0] ?? 'destructive change';
+    gaps.push({ id: task.id, matched });
+  }
+  return gaps;
+}
+
+/** Human-readable rejection message for the agent to act on. */
+export function formatPreconditionRejection(gaps: PreconditionGap[]): string {
+  const list = gaps.map((g) => `  • ${g.id} ("${g.matched}")`).join('\n');
+  return (
+    `Plan NOT saved — precondition gate failed for ${gaps.length} destructive ` +
+    `task(s):\n${list}\n\n` +
+    `Each task above deletes/removes/renames a codebase target but carries no ` +
+    `precondition proof. In the task's details, add ONE of:\n` +
+    `  1. A proof command that establishes the consumer set, scoped by feature ` +
+    `not directory — e.g. \`Proof: rg "ExportedSymbol" -l\` (run it for EVERY ` +
+    `exported symbol being removed, not just the type/feature name), OR\n` +
+    `  2. An explicit, auditable opt-out: \`Precondition: none — <reason it has ` +
+    `no consumers>\`.\n\n` +
+    `Then call submit_plan again. This is deterministic input validation, not a review.`
+  );
+}

package/extensions/plan-mode/prompts.ts

@@ -21,6 +21,8 @@ Your job is to reach shared understanding before formalizing a plan:
 3. Maintain a living .plans/<plan-name>/context.md as you converge — the planning-context skill covers what to capture and how.
 4. Only call submit_plan after the user and agent have converged on the approach.
 
+PRECONDITION GATE — blast-radius awareness (anti-rot). This is enforced: submit_plan will REJECT the plan if you skip it. Any task that deletes, removes, renames, or narrows a symbol, export, file, or feature must carry a re-runnable proof of its premise in the task's details. Record the exact command (grep / ast-grep over EVERY exported symbol name being removed — not just the type or feature name) that establishes the consumer set, written as a \`Proof: <command>\` line, plus the expected result. Scope by FEATURE, not directory: follow each symbol upward to its callers, operations, commands, and settings — a "delete the X dir" task that never traces X's consumers is incomplete and will rot. If you genuinely believe there are no consumers, state it as an auditable opt-out: \`Precondition: none — <reason>\`. The executor RE-RUNS this proof; if reality contradicts it, the executor blocks instead of improvising.
+
 When you are ready to finalize the plan, call submit_plan with:
 - name: a short kebab-case name (e.g. "add-auth-middleware")
 - title: a human-readable plan title
@@ -31,6 +33,8 @@ Plan weight:
 - **Delegation plans** (different agent/human executes): include full details in each task so an executor with zero context can follow them. End each task's details with a **verification gate** — a concrete command and its expected output (e.g. \`bun test\` → all pass) so the executor can prove success without judgement, plus any **STOP conditions** ("if X, stop and report" instead of improvising when reality doesn't match the plan).
 - **Self-execution plans** (you plan and execute in the same session): use lightweight checklist-style tasks — just id + description, skip details. The handoff doc carries the real context.
 
+The verification gate proves success *after* a task; the **precondition gate** (above) proves a destructive task's *premise before* acting on it. Both are required where they apply — the precondition gate is enforced by submit_plan.
+
 submit_plan is finalization, not the starting point. It records tasks and the handoff — it does not generate HTML.
 
 Sizing the work — flat plan vs initiative:
@@ -73,6 +77,7 @@ Rules:
 - Do NOT run diagnostics, linters, test suites, or skills unless a task explicitly asks for it
 - Do NOT explore the codebase beyond what the current task requires
 - Do NOT deviate from the plan — if something seems wrong, call update_task with status "blocked"
+- If a destructive task names a precondition (e.g. "X is unused", "no consumers of Y"), **re-run its proof command FIRST**. If reality contradicts the task — the symbol still has live consumers, the delete would break an import — **STOP and call update_task status "blocked"** with what you found. Do NOT rename, stub, comment out, or otherwise improvise to make the delete "work". Silently improvising around a contradicted premise is the exact failure this rule exists to stop.
 - If you notice worthwhile work OUTSIDE the current plan, call add_task to capture it as a deferred follow-up, then keep going. Do NOT implement discovered work in this run — the user reviews follow-ups later via /plan resume.
 
 ## Current task

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/submit-plan.ts

@@ -14,6 +14,7 @@ import { reconcileInitiativeForPlan } from '@dreki-gg/taskman';
 import type { RunPlanIO } from '@dreki-gg/taskman';
 import { toKebabCase } from '@dreki-gg/taskman';
 import { readHeadCommit } from '../git.js';
+import { detectPreconditionGaps, formatPreconditionRejection } from '../precondition-guard.js';
 import type { PlanData, TaskMeta, TaskRecord } from '../types.js';
 
 export interface SubmitPlanCallbacks {
@@ -78,6 +79,18 @@ export function registerSubmitPlanTool(
     }),
 
     async execute(_toolCallId, params) {
+      // Precondition gate (deterministic, no LLM): reject destructive tasks that
+      // carry no proof command or auditable opt-out. Nothing is persisted on
+      // rejection — the agent fixes the tasks and re-calls submit_plan.
+      const gaps = detectPreconditionGaps(params.tasks);
+      if (gaps.length > 0) {
+        const details: Record<string, unknown> = { rejected: true, preconditionGaps: gaps };
+        return {
+          content: [{ type: 'text' as const, text: formatPreconditionRejection(gaps) }],
+          details,
+        };
+      }
+
       const planName = toKebabCase(params.name);
       const planDir = `.plans/${planName}`;
       const initiative = params.initiative ? toKebabCase(params.initiative) : undefined;

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.28.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"
@@ -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",

package/skills/planning-context/SKILL.md

@@ -28,6 +28,7 @@ As soon as you understand the intent, write `.plans/<plan-name>/context.md` with
 - **Constraints** — technical, product, or process limits that shape the work
 - **Open questions** — anything unresolved; do not submit a plan with silent unknowns
 - **Discarded options** — approaches considered and rejected, with why. This is the highest-value section and the one most often skipped.
+- **Blast radius** (when the plan deletes/removes/renames/narrows anything) — for every symbol, export, file, or feature being removed, record the exact proof command (grep / ast-grep over *every* exported symbol name, not just the type or feature name) and its result. Scope by **feature, not directory**: trace each symbol upward to its callers, operations, commands, and settings. This evidence is what turns "delete, it's unused" from an assertion into a precondition the executor can re-run — see the precondition gate in the plan-mode prompt. A removal task without it will rot.
 
 ### 3. Style