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

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # @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

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__/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/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/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/package.json

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

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