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

package/CHANGELOG.md

@@ -1,5 +1,24 @@
 # @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
+
+- Add `@plan:<slug>` plan references with autocomplete. Type `@plan:` in any message to fuzzy-search and tag a plan (all plans listed, in-progress first), and on send the referenced plan's tasks + handoff are attached as context so the agent understands the reference. Resolution is context-only — it never switches execution mode, tools, or model — and follows first-wins when multiple tokens are present.
+
 ## 0.24.1
 
 ### Patch 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__/plan-references-autocomplete.test.ts

@@ -0,0 +1,55 @@
+import { describe, expect, test } from 'bun:test';
+import { filterPlanReferences, formatPlanSuggestion } from '../references/autocomplete.js';
+import type { PlanListItem } from '../commands/list-plans.js';
+
+function item(overrides: Partial<PlanListItem> & { name: string }): PlanListItem {
+  return {
+    title: `Title ${overrides.name}`,
+    status: 'in-progress',
+    created_at: '2026-01-01T00:00:00.000Z',
+    completed_at: null,
+    totalTasks: 3,
+    doneTasks: 1,
+    pendingTasks: 2,
+    ...overrides,
+  };
+}
+
+const items: PlanListItem[] = [
+  item({ name: 'done-plan', status: 'done' }),
+  item({ name: 'active-one', status: 'in-progress' }),
+  item({ name: 'abandoned-plan', status: 'abandoned' }),
+  item({ name: 'active-two', status: 'in-progress' }),
+];
+
+describe('filterPlanReferences', () => {
+  test('empty query lists all plans, in-progress first', () => {
+    const result = filterPlanReferences(items, '');
+    expect(result.map((p) => p.name).slice(0, 2).sort()).toEqual(['active-one', 'active-two']);
+    expect(result).toHaveLength(4);
+  });
+
+  test('name-prefix matches win', () => {
+    const result = filterPlanReferences(items, 'active-t');
+    expect(result[0].name).toBe('active-two');
+  });
+
+  test('fuzzy fallback finds non-prefix matches', () => {
+    const result = filterPlanReferences(items, 'abandon');
+    expect(result.some((p) => p.name === 'abandoned-plan')).toBe(true);
+  });
+
+  test('returns empty array for no match', () => {
+    expect(filterPlanReferences(items, 'zzz-nope-nope')).toHaveLength(0);
+  });
+});
+
+describe('formatPlanSuggestion', () => {
+  test('builds a @plan: value with status + progress description', () => {
+    const suggestion = formatPlanSuggestion(item({ name: 'active-one', status: 'in-progress' }));
+    expect(suggestion.value).toBe('@plan:active-one');
+    expect(suggestion.label).toContain('Title active-one');
+    expect(suggestion.description).toContain('active-one');
+    expect(suggestion.description).toContain('1/3');
+  });
+});

package/extensions/plan-mode/__tests__/plan-references-context.test.ts

@@ -0,0 +1,86 @@
+import { afterEach, beforeEach, describe, expect, test } from 'bun:test';
+import { chdir } from 'node:process';
+import { mkdtemp, rm } from 'node:fs/promises';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+import { makePlanRuntime } from '../effects/runtime.js';
+import { upsertPlanEntry } from '../storage/plans-manifest.js';
+import { writeTasksJsonl } from '../storage/task-storage.js';
+import { saveHandoff } from '../storage/plan-storage.js';
+import type { TaskMeta, TaskRecord } from '../types.js';
+import { buildPlanContextPack, resolvePlanReference } from '../references/context.js';
+
+const runPlanIO = makePlanRuntime();
+const originalCwd = process.cwd();
+let dir: string;
+
+beforeEach(async () => {
+  dir = await mkdtemp(join(tmpdir(), 'plan-mode-refctx-'));
+  chdir(dir);
+});
+
+afterEach(async () => {
+  chdir(originalCwd);
+  await rm(dir, { recursive: true, force: true });
+});
+
+const meta: TaskMeta = {
+  _type: 'meta',
+  title: 'Add Auth',
+  plan_name: 'add-auth',
+  created_at: '2026-01-01T00:00:00.000Z',
+};
+
+const tasks: TaskRecord[] = [
+  {
+    _type: 'task',
+    id: 't-001',
+    description: 'Write middleware',
+    status: 'done',
+    origin: 'plan',
+    created_at: '2026-01-01T00:00:00.000Z',
+    updated_at: '2026-01-01T00:00:00.000Z',
+  },
+  {
+    _type: 'task',
+    id: 't-002',
+    description: 'Wire routes',
+    status: 'pending',
+    origin: 'plan',
+    created_at: '2026-01-01T00:00:00.000Z',
+    updated_at: '2026-01-01T00:00:00.000Z',
+  },
+];
+
+describe('buildPlanContextPack', () => {
+  test('includes title, status, tasks, and handoff', () => {
+    const pack = buildPlanContextPack('add-auth', 'Add Auth', 'in-progress', tasks, 'Handoff body');
+    expect(pack).toContain('Add Auth');
+    expect(pack).toContain('add-auth');
+    expect(pack).toContain('in-progress');
+    expect(pack).toContain('t-001');
+    expect(pack).toContain('Write middleware');
+    expect(pack).toContain('t-002');
+    expect(pack).toContain('Handoff body');
+  });
+});
+
+describe('resolvePlanReference', () => {
+  test('resolves a real plan on disk', async () => {
+    await runPlanIO(upsertPlanEntry('add-auth', { status: 'in-progress', title: 'Add Auth' }));
+    await runPlanIO(writeTasksJsonl('.plans/add-auth', meta, tasks));
+    await runPlanIO(saveHandoff('.plans/add-auth', 'Handoff body'));
+
+    const resolved = await runPlanIO(resolvePlanReference('add-auth'));
+    expect(resolved).toBeDefined();
+    expect(resolved?.title).toBe('Add Auth');
+    expect(resolved?.status).toBe('in-progress');
+    expect(resolved?.tasks).toHaveLength(2);
+    expect(resolved?.handoff).toBe('Handoff body');
+  });
+
+  test('returns undefined for an unknown slug', async () => {
+    const resolved = await runPlanIO(resolvePlanReference('nope'));
+    expect(resolved).toBeUndefined();
+  });
+});

package/extensions/plan-mode/__tests__/plan-references-tokens.test.ts

@@ -0,0 +1,63 @@
+import { describe, expect, test } from 'bun:test';
+import {
+  PLAN_TOKEN_PREFIX,
+  buildPlanToken,
+  parsePlanSlug,
+  findActivePlanToken,
+  extractPlanReferences,
+  firstPlanReference,
+} from '../references/tokens.js';
+
+describe('buildPlanToken / parsePlanSlug', () => {
+  test('round-trips a slug', () => {
+    const token = buildPlanToken('add-auth-middleware');
+    expect(token).toBe(`${PLAN_TOKEN_PREFIX}add-auth-middleware`);
+    expect(parsePlanSlug(token)).toBe('add-auth-middleware');
+  });
+
+  test('parsePlanSlug returns undefined for non-plan tokens', () => {
+    expect(parsePlanSlug('@chat:abc')).toBeUndefined();
+    expect(parsePlanSlug('@plan:')).toBeUndefined();
+  });
+});
+
+describe('findActivePlanToken', () => {
+  test('detects a token being typed at the cursor', () => {
+    const active = findActivePlanToken('start working on @plan:add-au');
+    expect(active?.query).toBe('add-au');
+    expect(active?.token).toBe('@plan:add-au');
+  });
+
+  test('detects an empty query right after the prefix', () => {
+    const active = findActivePlanToken('do @plan:');
+    expect(active?.query).toBe('');
+  });
+
+  test('returns undefined when there is no token at the cursor', () => {
+    expect(findActivePlanToken('just some text')).toBeUndefined();
+    expect(findActivePlanToken('email me@plan-b.com')).toBeUndefined();
+  });
+
+  test('does not match when the token is not adjacent to the cursor', () => {
+    expect(findActivePlanToken('@plan:foo and more text')).toBeUndefined();
+  });
+});
+
+describe('extractPlanReferences / firstPlanReference', () => {
+  test('extracts all tokens in order', () => {
+    const tokens = extractPlanReferences('work on @plan:alpha then @plan:beta');
+    expect(tokens).toEqual(['@plan:alpha', '@plan:beta']);
+  });
+
+  test('first-wins helper returns only the first slug', () => {
+    expect(firstPlanReference('work on @plan:alpha then @plan:beta')).toBe('alpha');
+  });
+
+  test('firstPlanReference returns undefined when no token present', () => {
+    expect(firstPlanReference('nothing here')).toBeUndefined();
+  });
+
+  test('does not treat email-like text as a token', () => {
+    expect(extractPlanReferences('reach me@plan-x.dev')).toEqual([]);
+  });
+});

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

@@ -57,11 +57,16 @@ import { registerReconcilePlansTool } from './tools/reconcile-plans.js';
 import { isSafeCommand, isPlanPath } from './utils.js';
 import { handleListPlans } from './commands/list-plans.js';
 import { handleListInitiatives } from './commands/list-initiatives.js';
+import { createPlanReferenceIndex } from './references/plan-index.js';
+import { registerPlanReferenceAutocomplete } from './references/autocomplete.js';
+import { registerPlanReferenceContext } from './references/context.js';
 
 export default function planMode(pi: ExtensionAPI): void {
   const state = new PlanModeState();
   // Build the live Effect runtime once; all storage I/O runs through this bridge.
   const runPlanIO = makePlanRuntime();
+  // Cached plan list for `@plan:<slug>` autocomplete; refreshed at session start.
+  const planReferenceIndex = createPlanReferenceIndex(runPlanIO);
 
   // ── Flag ──────────────────────────────────────────────────────────────────
   pi.registerFlag('plan', {
@@ -200,6 +205,9 @@ export default function planMode(pi: ExtensionAPI): void {
   registerInitiativeStatusTool(pi, runPlanIO);
   registerReconcilePlansTool(pi, runPlanIO);
 
+  // Attach a referenced plan (`@plan:<slug>`) as context when present in a prompt.
+  registerPlanReferenceContext(pi, runPlanIO);
+
   registerAddTaskTool(pi, {
     resolvePlan: (opts) => resolveActivePlan(state, pi, runPlanIO, opts),
     onTaskAdded: async (task) => {
@@ -602,6 +610,10 @@ export default function planMode(pi: ExtensionAPI): void {
       ctx.sessionManager.getEntries() as Array<{ type: string; customType?: string; data?: any }>,
     );
 
+    // Register `@plan:<slug>` autocomplete and warm its cache.
+    await planReferenceIndex.refresh();
+    registerPlanReferenceAutocomplete(ctx, planReferenceIndex);
+
     // Check for exec-pending handoff from planning session
     const pending = await runPlanIO(readAndClearExecPending());
     if (pending) {
@@ -614,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/references/autocomplete.ts

@@ -0,0 +1,120 @@
+/**
+ * `@plan:` autocomplete provider — stacks on top of the built-in provider.
+ *
+ * Lists all plans, ranking in-progress first. Empty query keeps that ordering;
+ * a non-empty query prefers exact name-prefix matches and otherwise falls back
+ * to a fuzzy search over name + title.
+ */
+
+import type { ExtensionContext } from '@earendil-works/pi-coding-agent';
+import type {
+  AutocompleteItem,
+  AutocompleteProvider,
+  AutocompleteSuggestions,
+} from '@earendil-works/pi-tui';
+import { fuzzyFilter } from '@earendil-works/pi-tui';
+import type { PlanListItem } from '../commands/list-plans.js';
+import type { PlanStatus } from '../types.js';
+import { buildPlanToken, findActivePlanToken } from './tokens.js';
+import type { PlanReferenceIndex } from './plan-index.js';
+
+const MAX_SUGGESTIONS = 20;
+
+const STATUS_ICON: Record<PlanStatus, string> = {
+  'in-progress': '🔵',
+  done: '✅',
+  superseded: '🔄',
+  abandoned: '❌',
+};
+
+const STATUS_RANK: Record<PlanStatus, number> = {
+  'in-progress': 0,
+  done: 1,
+  superseded: 2,
+  abandoned: 3,
+};
+
+/** In-progress first, then newest plans within each status group. */
+function byInProgressFirst(a: PlanListItem, b: PlanListItem): number {
+  const rank = STATUS_RANK[a.status] - STATUS_RANK[b.status];
+  if (rank !== 0) return rank;
+  return b.created_at.localeCompare(a.created_at);
+}
+
+export function filterPlanReferences(items: PlanListItem[], query: string): PlanListItem[] {
+  const trimmed = query.trim().toLowerCase();
+  if (!trimmed) {
+    return [...items].sort(byInProgressFirst).slice(0, MAX_SUGGESTIONS);
+  }
+
+  const prefixMatches = items
+    .filter((item) => item.name.toLowerCase().startsWith(trimmed))
+    .sort(byInProgressFirst);
+  if (prefixMatches.length) return prefixMatches.slice(0, MAX_SUGGESTIONS);
+
+  return fuzzyFilter(items, trimmed, (item) => `${item.name} ${item.title}`).slice(
+    0,
+    MAX_SUGGESTIONS,
+  );
+}
+
+export function formatPlanSuggestion(item: PlanListItem): AutocompleteItem {
+  const progress = item.totalTasks > 0 ? `${item.doneTasks}/${item.totalTasks} tasks` : 'no tasks';
+  return {
+    value: buildPlanToken(item.name),
+    label: `${item.title}`,
+    description: `${STATUS_ICON[item.status]} ${item.name} • ${item.status} • ${progress}`,
+  };
+}
+
+export function createPlanReferenceAutocompleteProvider(
+  current: AutocompleteProvider,
+  index: PlanReferenceIndex,
+): AutocompleteProvider {
+  return {
+    async getSuggestions(
+      lines,
+      cursorLine,
+      cursorCol,
+      options,
+    ): Promise<AutocompleteSuggestions | null> {
+      const line = lines[cursorLine] ?? '';
+      const beforeCursor = line.slice(0, cursorCol);
+      const active = findActivePlanToken(beforeCursor);
+      if (!active) return current.getSuggestions(lines, cursorLine, cursorCol, options);
+
+      const items = await index.getItems();
+      if (options.signal.aborted) return null;
+
+      const matches = filterPlanReferences(items, active.query);
+      if (matches.length === 0) {
+        return current.getSuggestions(lines, cursorLine, cursorCol, options);
+      }
+
+      return {
+        prefix: active.token,
+        items: matches.map(formatPlanSuggestion),
+      };
+    },
+
+    applyCompletion(lines, cursorLine, cursorCol, item, prefix) {
+      return current.applyCompletion(lines, cursorLine, cursorCol, item, prefix);
+    },
+
+    shouldTriggerFileCompletion(lines, cursorLine, cursorCol) {
+      const line = lines[cursorLine] ?? '';
+      const beforeCursor = line.slice(0, cursorCol);
+      if (findActivePlanToken(beforeCursor)) return false;
+      return current.shouldTriggerFileCompletion?.(lines, cursorLine, cursorCol) ?? true;
+    },
+  };
+}
+
+export function registerPlanReferenceAutocomplete(
+  ctx: ExtensionContext,
+  index: PlanReferenceIndex,
+): void {
+  ctx.ui.addAutocompleteProvider((current) =>
+    createPlanReferenceAutocompleteProvider(current, index),
+  );
+}

package/extensions/plan-mode/references/context.ts

@@ -0,0 +1,140 @@
+/**
+ * `@plan:` context injection.
+ *
+ * When a submitted message references a plan with `@plan:<slug>`, attach that
+ * plan's tasks + handoff as a hidden context message so the agent understands
+ * the reference. First-wins: only the first token in the message is resolved.
+ *
+ * This is *context only* — it never switches execution mode, tools, or model.
+ */
+
+import { Effect } from 'effect';
+import type { ExtensionAPI } from '@earendil-works/pi-coding-agent';
+import type { FileSystem } from '../effects/filesystem.js';
+import type { RunPlanIO } from '../effects/runtime.js';
+import type { PlanStatus, TaskRecord, TaskStatus } from '../types.js';
+import { readPlansManifest } from '../storage/plans-manifest.js';
+import { readTasksJsonl } from '../storage/task-storage.js';
+import { loadHandoff } from '../storage/plan-storage.js';
+import { firstPlanReference } from './tokens.js';
+
+export interface ResolvedPlanReference {
+  name: string;
+  title: string;
+  status: PlanStatus;
+  tasks: TaskRecord[];
+  handoff: string;
+}
+
+const TASK_ICON: Record<TaskStatus, string> = {
+  pending: '○',
+  done: '✓',
+  skipped: '⊘',
+  blocked: '✗',
+  deferred: '⏸',
+};
+
+/** Resolve a plan slug to its registry entry + tasks + handoff (Effect-based). */
+export function resolvePlanReference(
+  slug: string,
+): Effect.Effect<ResolvedPlanReference | undefined, never, FileSystem> {
+  return Effect.gen(function* () {
+    const manifest = yield* Effect.orElseSucceed(readPlansManifest(), () => []);
+    const entry = manifest.find((candidate) => candidate.name === slug);
+    if (!entry) return undefined;
+
+    const dir = `.plans/${slug}`;
+    const snapshot = yield* Effect.orElseSucceed(readTasksJsonl(dir), () => undefined);
+    const handoff = yield* loadHandoff(dir);
+
+    return {
+      name: entry.name,
+      title: entry.title,
+      status: entry.status,
+      tasks: snapshot?.tasks ?? [],
+      handoff: handoff ?? '',
+    };
+  });
+}
+
+/** Build the markdown context pack injected for a resolved plan reference. */
+export function buildPlanContextPack(
+  name: string,
+  title: string,
+  status: PlanStatus,
+  tasks: TaskRecord[],
+  handoff: string,
+): string {
+  const done = tasks.filter((t) => t.status === 'done' || t.status === 'skipped').length;
+  const taskLines = tasks.length
+    ? tasks
+        .map((t) => {
+          const marker = t.origin === 'discovered' ? ' (discovered)' : '';
+          const notes = t.notes ? `\n   ${t.notes}` : '';
+          return `${t.id}. ${TASK_ICON[t.status]} ${t.description}${marker}${notes}`;
+        })
+        .join('\n')
+    : '_(no tasks)_';
+
+  return [
+    `# Referenced plan: ${title} (\`${name}\`)`,
+    `The user referenced this plan with \`@plan:${name}\`. Status: **${status}** — ${done}/${tasks.length} tasks done.`,
+    `Use this as context. The source of truth is \`.plans/${name}/\` (tasks.jsonl + HANDOFF.md) — inspect it with tools if you need more detail.`,
+    '',
+    '## Tasks',
+    '',
+    taskLines,
+    '',
+    '## Handoff',
+    '',
+    handoff.trim() || '_(no handoff recorded)_',
+  ].join('\n');
+}
+
+/**
+ * Register the `before_agent_start` handler that attaches a referenced plan as
+ * context. Chains alongside plan-mode's own `before_agent_start` handler.
+ */
+export function registerPlanReferenceContext(pi: ExtensionAPI, runPlanIO: RunPlanIO): void {
+  pi.on('before_agent_start', async (event, ctx) => {
+    const slug = firstPlanReference(event.prompt);
+    if (!slug) return undefined;
+
+    const resolved = await runPlanIO(resolvePlanReference(slug));
+
+    if (!resolved) {
+      if (ctx.hasUI) {
+        ctx.ui.notify(`plan-mode: no plan named "${slug}" for @plan:${slug}`, 'warning');
+      }
+      return {
+        message: {
+          customType: 'plan-reference-context',
+          content: `The prompt referenced @plan:${slug}, but no plan with that name exists in .plans/plans.jsonl.`,
+          display: true,
+          details: { slug, resolved: false },
+        },
+      };
+    }
+
+    const content = buildPlanContextPack(
+      resolved.name,
+      resolved.title,
+      resolved.status,
+      resolved.tasks,
+      resolved.handoff,
+    );
+
+    if (ctx.hasUI) {
+      ctx.ui.notify(`Attached plan reference: ${resolved.title} (${resolved.name}).`, 'info');
+    }
+
+    return {
+      message: {
+        customType: 'plan-reference-context',
+        content,
+        display: false,
+        details: { slug, name: resolved.name, status: resolved.status, resolved: true },
+      },
+    };
+  });
+}

package/extensions/plan-mode/references/plan-index.ts

@@ -0,0 +1,55 @@
+/**
+ * In-memory cache of plan list items for `@plan:` autocomplete.
+ *
+ * Autocomplete `getSuggestions` runs on every keystroke, so it must be cheap.
+ * We cache the manifest-derived `PlanListItem[]` and refresh at most once per
+ * TTL window — fresh enough to surface plans submitted mid-session without a
+ * per-keystroke disk hit.
+ */
+
+import type { RunPlanIO } from '../effects/runtime.js';
+import { loadPlanListItems, type PlanListItem } from '../commands/list-plans.js';
+
+const DEFAULT_TTL_MS = 2_000;
+
+export interface PlanReferenceIndex {
+  /** Force a reload from disk. */
+  refresh(): Promise<void>;
+  /** Cached items, reloading first when the cache is stale. */
+  getItems(): Promise<PlanListItem[]>;
+  /** Cached items without triggering IO (may be stale or empty). */
+  peek(): PlanListItem[];
+}
+
+export function createPlanReferenceIndex(
+  runPlanIO: RunPlanIO,
+  ttlMs: number = DEFAULT_TTL_MS,
+): PlanReferenceIndex {
+  let items: PlanListItem[] = [];
+  let loadedAt = 0;
+  let inflight: Promise<void> | undefined;
+
+  const load = async (): Promise<void> => {
+    items = await runPlanIO(loadPlanListItems());
+    loadedAt = Date.now();
+  };
+
+  const refresh = async (): Promise<void> => {
+    // Coalesce concurrent refreshes so rapid keystrokes share one read.
+    if (!inflight) {
+      inflight = load().finally(() => {
+        inflight = undefined;
+      });
+    }
+    await inflight;
+  };
+
+  return {
+    refresh,
+    peek: () => items,
+    async getItems() {
+      if (Date.now() - loadedAt > ttlMs) await refresh();
+      return items;
+    },
+  };
+}

package/extensions/plan-mode/references/tokens.ts

@@ -0,0 +1,76 @@
+/**
+ * `@plan:<slug>` reference tokens.
+ *
+ * Lets a user reference a plan inside a normal chat message (e.g.
+ * "start working on @plan:add-auth"). Mirrors the past-chats `@chat:` /
+ * `@session:` token model: a cursor-anchored matcher drives autocomplete, and a
+ * global matcher extracts referenced slugs from a submitted prompt.
+ *
+ * Pure module — no IO, safe to unit test.
+ */
+
+export const PLAN_TOKEN_PREFIX = '@plan:' as const;
+
+/** Plan slugs are kebab-ish identifiers. */
+const SLUG_CHARS = 'A-Za-z0-9_-';
+
+export interface ActivePlanToken {
+  /** The query typed after the prefix (may be empty). */
+  query: string;
+  /** The full token under the cursor, including the prefix. */
+  token: string;
+  /** Offset in the line where the token starts. */
+  tokenStart: number;
+}
+
+export function buildPlanToken(slug: string): string {
+  return `${PLAN_TOKEN_PREFIX}${slug}`;
+}
+
+/** Extract the slug from a `@plan:<slug>` token, or undefined when invalid. */
+export function parsePlanSlug(token: string): string | undefined {
+  if (!token.startsWith(PLAN_TOKEN_PREFIX)) return undefined;
+  const slug = token.slice(PLAN_TOKEN_PREFIX.length).trim();
+  return slug || undefined;
+}
+
+// Token must be at a word boundary: start of line or after whitespace / open
+// bracket. Prevents matching inside emails like `me@plan-x.dev`.
+const ACTIVE_RE = new RegExp(`(?:^|[\\s([{])(${PLAN_TOKEN_PREFIX}([${SLUG_CHARS}]*))$`);
+const GLOBAL_RE = new RegExp(
+  `(?:^|[\\s([{])(${PLAN_TOKEN_PREFIX}([${SLUG_CHARS}]+))`,
+  'g',
+);
+
+/** Detect a `@plan:` token being typed immediately before the cursor. */
+export function findActivePlanToken(textBeforeCursor: string): ActivePlanToken | undefined {
+  const match = textBeforeCursor.match(ACTIVE_RE);
+  if (!match) return undefined;
+  const token = match[1] ?? '';
+  return {
+    query: match[2] ?? '',
+    token,
+    tokenStart: textBeforeCursor.length - token.length,
+  };
+}
+
+/** All `@plan:<slug>` tokens in a message, in order, de-duplicated by slug. */
+export function extractPlanReferences(text: string): string[] {
+  const tokens: string[] = [];
+  const seen = new Set<string>();
+  for (const match of text.matchAll(GLOBAL_RE)) {
+    const token = match[1];
+    const slug = token ? parsePlanSlug(token) : undefined;
+    if (token && slug && !seen.has(slug)) {
+      seen.add(slug);
+      tokens.push(token);
+    }
+  }
+  return tokens;
+}
+
+/** First referenced slug in a message (first-wins), or undefined. */
+export function firstPlanReference(text: string): string | undefined {
+  const [first] = extractPlanReferences(text);
+  return first ? parsePlanSlug(first) : undefined;
+}

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.24.1",
+  "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"