@dreki-gg/pi-plan-mode 0.25.0 → 0.26.0

package/CHANGELOG.md

@@ -1,5 +1,18 @@
 # @dreki-gg/pi-plan-mode
 
+## 0.26.0
+
+### Minor Changes
+
+- Make plans more executable by zero-context executors. Plans now stamp the git
+  commit they were written against (`base_commit`), and the execution prompt runs
+  a drift check — if HEAD has moved, the executor is told to diff, re-read the
+  affected files, and proceed with caution. Planning guidance also now asks
+  delegation tasks to end their details with a verification gate (a concrete
+  command + expected output) and STOP conditions, so success is machine-checkable.
+  Fully backward-compatible: older plans without `base_commit` simply skip the
+  drift check.
+
 ## 0.25.0
 
 ### Minor Changes

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

@@ -0,0 +1,17 @@
+import { describe, expect, test } from 'bun:test';
+import { tmpdir } from 'node:os';
+import { readHeadCommit } from '../git.js';
+
+describe('readHeadCommit', () => {
+  test('returns the HEAD sha inside a git repo', async () => {
+    // This monorepo is a git repo, so cwd resolves a real commit.
+    const sha = await readHeadCommit(process.cwd());
+    expect(sha).toMatch(/^[0-9a-f]{40}$/);
+  });
+
+  test('returns undefined outside a git repo (never throws)', async () => {
+    // tmpdir is not a git repo; the helper must swallow the error.
+    const sha = await readHeadCommit(tmpdir());
+    expect(sha).toBeUndefined();
+  });
+});

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

@@ -23,6 +23,11 @@ describe('buildPlanModePrompt', () => {
     expect(prompt).toContain('technical-options');
   });
 
+  test('instructs delegation tasks to include a verification gate', () => {
+    expect(prompt).toContain('verification gate');
+    expect(prompt).toContain('STOP conditions');
+  });
+
   test('mentions handoff instead of context and risks', () => {
     expect(prompt).toContain('handoff');
     expect(prompt).not.toContain('- risks:');
@@ -72,6 +77,24 @@ describe('buildExecutionPrompt', () => {
     expect(prompt).toContain('Details: Full instructions here');
   });
 
+  test('includes a drift check when base_commit is present', () => {
+    const plan: PlanData = {
+      title: 'Test',
+      planName: 'test',
+      handoff: '# H',
+      tasks: [makeTask()],
+      base_commit: 'deadbeef',
+    };
+    const prompt = buildExecutionPrompt(plan)!;
+    expect(prompt).toContain('Drift check');
+    expect(prompt).toContain('deadbeef');
+  });
+
+  test('omits the drift check when base_commit is absent', () => {
+    const plan: PlanData = { title: 'Test', planName: 'test', handoff: '# H', tasks: [makeTask()] };
+    expect(buildExecutionPrompt(plan)!).not.toContain('Drift check');
+  });
+
   test('returns undefined when no pending tasks', () => {
     const plan: PlanData = {
       title: 'Test',

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

@@ -113,6 +113,21 @@ describe('task meta schema', () => {
     ).toBe(true);
   });
 
+  test('accepts a meta record with base_commit', () => {
+    expect(
+      isOk(
+        { _type: 'meta', title: 'Refactor', plan_name: 'refactor', created_at: now, base_commit: 'abc123' },
+        decodeTaskMeta,
+      ),
+    ).toBe(true);
+  });
+
+  test('accepts a meta record without base_commit (back-compat)', () => {
+    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(

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

@@ -47,6 +47,13 @@ describe('tasks.jsonl storage', () => {
     await expect(run(readTasksJsonl(dir))).resolves.toEqual({ meta, tasks: [task] });
   });
 
+  test('round trips base_commit on the meta record', async () => {
+    const metaWithCommit: TaskMeta = { ...meta, base_commit: 'deadbeefcafe' };
+    await run(writeTasksJsonl(dir, metaWithCommit, [task]));
+    const result = await run(readTasksJsonl(dir));
+    expect(result?.meta.base_commit).toBe('deadbeefcafe');
+  });
+
   test('round trips tasks without details (lightweight checklist)', async () => {
     const lightweight: TaskRecord = {
       _type: 'task',

package/extensions/plan-mode/git.ts

@@ -0,0 +1,21 @@
+/**
+ * Read-only git helpers. Failure-tolerant by design: plan-mode must never block
+ * or throw because git metadata is unavailable (no repo, detached HEAD, no
+ * commits yet). Runs on Node via execFile — no Bun APIs.
+ */
+
+import { execFile } from 'node:child_process';
+
+/**
+ * Resolve the current HEAD commit SHA, or undefined when it cannot be read.
+ * Never rejects — callers treat undefined as "no drift baseline".
+ */
+export function readHeadCommit(cwd: string = process.cwd()): Promise<string | undefined> {
+  return new Promise((resolve) => {
+    execFile('git', ['rev-parse', 'HEAD'], { cwd }, (error, stdout) => {
+      if (error) return resolve(undefined);
+      const sha = stdout.trim();
+      resolve(sha.length > 0 ? sha : undefined);
+    });
+  });
+}

package/extensions/plan-mode/index.ts

@@ -626,6 +626,7 @@ export default function planMode(pi: ExtensionAPI): void {
               planName: snapshot.meta.plan_name,
               handoff: (await runPlanIO(loadHandoff(pending.planDir))) ?? '',
               tasks: snapshot.tasks,
+              base_commit: snapshot.meta.base_commit,
             }
           : undefined;
       }

package/extensions/plan-mode/prompts.ts

@@ -28,7 +28,7 @@ When you are ready to finalize the plan, call submit_plan with:
 - tasks: an array of tasks with id (e.g. "t-001"), description (≤60 chars), optional details, and optional depends_on task IDs
 
 Plan weight:
-- **Delegation plans** (different agent/human executes): include full details in each task so an executor with zero context can follow them.
+- **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.
 
 submit_plan is finalization, not the starting point. It records tasks and the handoff — it does not generate HTML.
@@ -59,6 +59,10 @@ export function buildExecutionPrompt(plan: PlanData): string | undefined {
   const currentTask = remaining[0];
   const currentDetails = currentTask.details ? `\nDetails: ${currentTask.details}` : '';
 
+  const driftCheck = plan.base_commit
+    ? `\n## Drift check (do this FIRST)\nThis plan was written against git commit ${plan.base_commit}. Before editing, run \`git rev-parse HEAD\`. If it differs, the codebase has moved since the plan was written: run \`git diff ${plan.base_commit} --stat\`, re-read any files the current task touches, and proceed with caution — adjust to what the code actually looks like now. This is a warning, not a stop.\n`
+    : '';
+
   return `[EXECUTING PLAN — FOLLOW THE PLAN EXACTLY]
 
 You are executing a structured plan. Your ONLY job is to implement the plan tasks below, one at a time.
@@ -73,6 +77,7 @@ Rules:
 
 ## Current task
 ${currentTask.id}: ${currentTask.description}${currentDetails}
+${driftCheck}
 
 ## Handoff
 ${plan.handoff}

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

@@ -57,6 +57,7 @@ async function attach(
     planName: snapshot.meta.plan_name,
     handoff: (await runPlanIO(loadHandoff(dir))) ?? '',
     tasks: snapshot.tasks,
+    base_commit: snapshot.meta.base_commit,
   };
   state.plan = plan;
   state.planDir = dir;

package/extensions/plan-mode/resume.ts

@@ -82,6 +82,7 @@ export async function resumePlan(
     planName: snapshot.meta.plan_name,
     handoff: (await runPlanIO(loadHandoff(dir))) ?? '',
     tasks: snapshot.tasks,
+    base_commit: snapshot.meta.base_commit,
   };
 
   const doneCount = state.plan.tasks.filter(

package/extensions/plan-mode/schema.ts

@@ -31,6 +31,8 @@ export const TaskMetaSchema = Schema.Struct({
   title: Schema.String,
   plan_name: Schema.String,
   created_at: Schema.String,
+  /** Optional git commit the plan was written against (back-compat: absent on older plans). */
+  base_commit: Schema.optional(Schema.String),
 });
 
 /** A single tasks.jsonl line is either the meta record or a task record. */

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

@@ -129,12 +129,14 @@ export function registerRevisePlanTool(
         title: newTitle,
         plan_name: plan.planName,
         created_at: plan.tasks[0]?.created_at ?? now,
+        base_commit: plan.base_commit,
       };
       const revised: PlanData = {
         title: newTitle,
         planName: plan.planName,
         handoff: newHandoff,
         tasks,
+        base_commit: plan.base_commit,
       };
       const planDir = `.plans/${plan.planName}`;
 

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

@@ -13,6 +13,7 @@ import { readInitiativesManifest } from '../storage/initiatives-manifest.js';
 import { reconcileInitiativeForPlan } from '../initiative.js';
 import type { RunPlanIO } from '../effects/runtime.js';
 import { toKebabCase } from '../utils.js';
+import { readHeadCommit } from '../git.js';
 import type { PlanData, TaskMeta, TaskRecord } from '../types.js';
 
 export interface SubmitPlanCallbacks {
@@ -33,6 +34,7 @@ export function registerSubmitPlanTool(
       'Only call submit_plan after shared understanding has been reached with the user.',
       'Each task needs an id like t-001, a short description, and optional depends_on task IDs.',
       "When a different agent or human will execute the plan, include detailed implementation instructions in each task's details field.",
+      "For delegation tasks (those with details), end the details with a verification gate: a concrete command and its expected output, plus any STOP conditions, so a zero-context executor can prove success without judgement.",
       'When you are planning and executing yourself (same session), use lightweight checklist-style tasks: just id + description, omit details. Put the real context in the handoff document instead.',
       'The handoff must be thorough enough that both a human reviewer and executor agent with zero prior context can understand the plan.',
       'For visual/UI work, preview a prototype with preview_prototype during planning — before submit_plan, not as part of it.',
@@ -81,11 +83,13 @@ export function registerSubmitPlanTool(
       const initiative = params.initiative ? toKebabCase(params.initiative) : undefined;
       const dependsOnPlans = params.depends_on_plans?.map(toKebabCase);
       const now = new Date().toISOString();
+      const baseCommit = await readHeadCommit();
       const meta: TaskMeta = {
         _type: 'meta',
         title: params.title,
         plan_name: planName,
         created_at: now,
+        base_commit: baseCommit,
       };
       const tasks: TaskRecord[] = params.tasks.map((task) => ({
         _type: 'task',
@@ -97,7 +101,13 @@ export function registerSubmitPlanTool(
         created_at: now,
         updated_at: now,
       }));
-      const plan: PlanData = { title: params.title, planName, handoff: params.handoff, tasks };
+      const plan: PlanData = {
+        title: params.title,
+        planName,
+        handoff: params.handoff,
+        tasks,
+        base_commit: baseCommit,
+      };
 
       const unknownInitiative = await runPlanIO(
         Effect.gen(function* () {

package/extensions/plan-mode/types.ts

@@ -35,6 +35,12 @@ export interface TaskMeta {
   title: string;
   plan_name: string;
   created_at: string;
+  /**
+   * Git commit (HEAD) the plan was written against, captured at submit time.
+   * Optional for back-compat: older tasks.jsonl files predate this field, and
+   * it stays undefined when git metadata is unavailable (no repo, no commits).
+   */
+  base_commit?: string;
 }
 
 export interface PlanData {
@@ -42,6 +48,8 @@ export interface PlanData {
   planName: string;
   handoff: string;
   tasks: TaskRecord[];
+  /** Git commit the plan was written against; powers the executor drift check. */
+  base_commit?: string;
 }
 
 export type ThinkingLevel = 'off' | 'minimal' | 'low' | 'medium' | 'high' | 'xhigh';

package/package.json

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