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

package/CHANGELOG.md

@@ -1,5 +1,20 @@
 # @dreki-gg/pi-plan-mode
 
+## 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
+
+- Fix lost-update race on the plan/initiative registries and stop reconcile from regressing finished plans.
+
+  - **Serialized registry writes:** concurrent tool calls in one block (e.g. several `submit_initiative` / `submit_plan` / `revise_plan` at once) previously ran an unguarded read-modify-write against `plans.jsonl` / `initiatives.jsonl`, so only the last write survived. A process-wide per-file lock (`withFileLock`) now serializes the read→modify→write of both registries and per-plan `tasks.jsonl`, eliminating the lost updates. Atomic writes already guarded against torn files; this closes the in-process concurrency gap.
+  - **No wrong-direction reconcile:** `reconcile_plans --apply` now only records completion (`in-progress → done`) and never auto-downgrades a `done` plan back to `in-progress`. A done plan with incomplete tasks (work merged but tasks never marked done) is surfaced as `needs-tasks-done` for a human to resolve by marking the tasks done, instead of being silently regressed.
+
 ## 0.24.0
 
 ### Minor Changes

package/extensions/plan-mode/__tests__/concurrent-writes.test.ts

@@ -0,0 +1,85 @@
+/**
+ * Regression: concurrent read-modify-write on the registries must not lose
+ * updates. Each `Effect.runPromise` mimics a separate tool execute running in
+ * the same block (e.g. three `submit_initiative` calls). Before the file-lock
+ * fix, their reads all saw the same starting file and the last write clobbered
+ * the rest — only one entry survived.
+ */
+
+import { afterEach, beforeEach, describe, expect, test } from 'bun:test';
+import { Effect } from 'effect';
+import { chdir } from 'node:process';
+import { mkdtemp, rm } from 'node:fs/promises';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+import { FileSystem, nodeFileSystemService } from '../effects/filesystem.js';
+import { readPlansManifest, upsertPlanEntry } from '../storage/plans-manifest.js';
+import {
+  readInitiativesManifest,
+  upsertInitiativeEntry,
+} from '../storage/initiatives-manifest.js';
+import { writeTasksJsonl, readTasksJsonl, updateTask } from '../storage/task-storage.js';
+import type { TaskMeta, TaskRecord } from '../types.js';
+
+// Each call gets its OWN runPromise so the writes are genuinely concurrent —
+// the same shape as independent tool executes sharing one Node process.
+const run = <A, E>(program: Effect.Effect<A, E, FileSystem>): Promise<A> =>
+  Effect.runPromise(program.pipe(Effect.provideService(FileSystem, nodeFileSystemService)));
+
+const originalCwd = process.cwd();
+let dir: string;
+
+beforeEach(async () => {
+  dir = await mkdtemp(join(tmpdir(), 'plan-mode-concurrent-'));
+  chdir(dir);
+});
+afterEach(async () => {
+  chdir(originalCwd);
+  await rm(dir, { recursive: true, force: true });
+});
+
+describe('concurrent registry writes', () => {
+  test('5 concurrent plan upserts all persist (no lost updates)', async () => {
+    const names = ['a', 'b', 'c', 'd', 'e'];
+    await Promise.all(
+      names.map((n) => run(upsertPlanEntry(n, { status: 'in-progress', title: n.toUpperCase() }))),
+    );
+    const entries = await run(readPlansManifest());
+    expect(entries.map((e) => e.name).sort()).toEqual(names);
+  });
+
+  test('3 concurrent initiative upserts all persist (no lost updates)', async () => {
+    const names = ['one', 'two', 'three'];
+    await Promise.all(
+      names.map((n) => run(upsertInitiativeEntry(n, { status: 'in-progress', title: n }))),
+    );
+    const entries = await run(readInitiativesManifest());
+    expect(entries.map((e) => e.name).sort()).toEqual([...names].sort());
+  });
+
+  test('concurrent task updates to the same plan all persist', async () => {
+    const planDir = join('.plans', 'p');
+    const meta: TaskMeta = {
+      _type: 'meta',
+      plan_name: 'p',
+      title: 'P',
+      created_at: 'now',
+    };
+    const tasks: TaskRecord[] = ['t-001', 't-002', 't-003'].map((id) => ({
+      _type: 'task',
+      id,
+      description: id,
+      status: 'pending',
+      created_at: 'now',
+      updated_at: 'now',
+    }));
+    await run(writeTasksJsonl(planDir, meta, tasks));
+
+    await Promise.all(
+      tasks.map((t) => run(updateTask(planDir, t.id, { status: 'done' }))),
+    );
+
+    const snapshot = await run(readTasksJsonl(planDir));
+    expect(snapshot?.tasks.every((t) => t.status === 'done')).toBe(true);
+  });
+});

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

@@ -117,6 +117,43 @@ describe('applyReconcile', () => {
     const [entry] = await runPlanIO(readPlansManifest());
     expect(entry.status).toBe('done');
   });
+
+  test('classifies an upgrade (in-progress registry, done tasks) as direction:upgrade', async () => {
+    await runPlanIO(writeTasksJsonl('.plans/up', meta('up'), [task('t-001', 'done')]));
+    await runPlanIO(upsertPlanEntry('up', { status: 'in-progress', title: 'Up' }));
+    const rows = await runPlanIO(collectPlanDrift());
+    expect(rows.find((r) => r.name === 'up')!.direction).toBe('upgrade');
+  });
+
+  test('a done plan with incomplete tasks is flagged downgrade and NOT auto-repaired', async () => {
+    // Work merged but tasks never marked done: registry done, tasks in-progress.
+    await runPlanIO(
+      writeTasksJsonl('.plans/merged', meta('merged'), [task('t-001', 'pending')]),
+    );
+    await runPlanIO(
+      writePlansManifest([
+        {
+          _type: 'plan',
+          name: 'merged',
+          status: 'done',
+          title: 'Merged',
+          created_at: now,
+          completed_at: now,
+        },
+      ]),
+    );
+
+    const rows = await runPlanIO(collectPlanDrift());
+    const merged = rows.find((r) => r.name === 'merged')!;
+    expect(merged.drift).toBe('status');
+    expect(merged.direction).toBe('downgrade');
+
+    // --apply must NOT regress it back to in-progress.
+    const repaired = await runPlanIO(applyReconcile(rows));
+    expect(repaired.map((r) => r.name)).not.toContain('merged');
+    const [entry] = await runPlanIO(readPlansManifest());
+    expect(entry.status).toBe('done');
+  });
 });
 
 describe('initiative drift', () => {

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) {

package/extensions/plan-mode/initiative.ts

@@ -18,8 +18,8 @@ import { FileSystem } from './effects/filesystem.js';
 import type { JsonlParseError, JsonlValidationError, PlanWriteError } from './errors.js';
 import { readPlansManifest, type PlanManifestEntry } from './storage/plans-manifest.js';
 import {
-  readInitiativesManifest,
-  upsertInitiativeEntry,
+  applyInitiativeUpsert,
+  mutateInitiativesManifest,
 } from './storage/initiatives-manifest.js';
 import type { PlanStatus } from './types.js';
 
@@ -139,16 +139,20 @@ type ReconcileError = JsonlParseError | JsonlValidationError | PlanWriteError;
 export function reconcileInitiativeStatus(
   name: string,
 ): Effect.Effect<void, ReconcileError, FileSystem> {
-  return Effect.gen(function* () {
-    const initiatives = yield* readInitiativesManifest();
-    const existing = initiatives.find((entry) => entry.name === name);
-    if (!existing) return;
-    if (existing.status === 'superseded' || existing.status === 'abandoned') return;
-    const plans = yield* readPlansManifest();
-    const status: PlanStatus = isInitiativeFinalizable(name, plans) ? 'done' : 'in-progress';
-    if (existing.status === status) return;
-    yield* upsertInitiativeEntry(name, { status, title: existing.title });
-  });
+  // The whole read-decide-write runs under the initiatives lock so a concurrent
+  // writer cannot slip a status change between our read and our write.
+  return mutateInitiativesManifest((initiatives) =>
+    Effect.gen(function* () {
+      const existing = initiatives.find((entry) => entry.name === name);
+      if (!existing) return false;
+      if (existing.status === 'superseded' || existing.status === 'abandoned') return false;
+      const plans = yield* readPlansManifest();
+      const status: PlanStatus = isInitiativeFinalizable(name, plans) ? 'done' : 'in-progress';
+      if (existing.status === status) return false;
+      applyInitiativeUpsert(initiatives, name, { status, title: existing.title });
+      return true;
+    }),
+  );
 }
 
 /**

package/extensions/plan-mode/reconcile.ts

@@ -55,6 +55,18 @@ export interface PlanDriftRow {
    *   - undefined       : in sync
    */
   drift?: 'status' | 'registry-only' | 'orphan';
+  /**
+   * For `status` drift, the direction the registry would move if projected from
+   * tasks:
+   *   - 'upgrade'   : registry `in-progress` → tasks `done` (safe; auto-repaired)
+   *   - 'downgrade' : registry `done` → tasks `in-progress` (NOT auto-repaired)
+   *
+   * A downgrade almost always means "work merged but tasks were never marked
+   * done" — auto-projecting tasks→registry there would REGRESS a finished plan
+   * back to in-progress (the wrong direction). We surface it for a human to
+   * resolve by marking the tasks done instead.
+   */
+  direction?: 'upgrade' | 'downgrade';
 }
 
 type CollectError = JsonlParseError | JsonlValidationError | MissingMetaRecord;
@@ -92,6 +104,12 @@ export function collectPlanDrift(): Effect.Effect<PlanDriftRow[], CollectError,
       // Terminal statuses (superseded/abandoned) are intentional — never drift.
       const isTerminalManual = entry.status === 'superseded' || entry.status === 'abandoned';
       const drift = !isTerminalManual && entry.status !== derivedStatus ? 'status' : undefined;
+      const direction =
+        drift === 'status'
+          ? derivedStatus === 'done'
+            ? ('upgrade' as const)
+            : ('downgrade' as const)
+          : undefined;
       rows.push({
         name: entry.name,
         registryStatus: entry.status,
@@ -101,6 +119,7 @@ export function collectPlanDrift(): Effect.Effect<PlanDriftRow[], CollectError,
         total,
         hasTasks: true,
         drift,
+        direction,
       });
     }
 
@@ -186,8 +205,15 @@ export function applyInitiativeReconcile(
 
 /**
  * Repair `status`-class drift by projecting derived status into the registry.
- * Orphans and registry-only rows are reported but not auto-fixed (they need a
- * human decision). Returns the rows that were repaired.
+ *
+ * Safety: only `upgrade` drift (registry `in-progress` → tasks `done`) is
+ * auto-repaired. A `downgrade` (registry `done` → tasks `in-progress`) is
+ * reported but NEVER auto-applied — it almost always means work merged without
+ * marking tasks done, and projecting tasks→registry there would regress a
+ * finished plan. The human resolves it by marking the tasks done instead.
+ *
+ * Orphans and registry-only rows are likewise reported but not auto-fixed.
+ * Returns the rows that were repaired.
  */
 export function applyReconcile(
   rows: PlanDriftRow[],
@@ -196,6 +222,9 @@ export function applyReconcile(
     const repaired: PlanDriftRow[] = [];
     for (const row of rows) {
       if (row.drift !== 'status' || !row.derivedStatus) continue;
+      // Guard against the wrong-direction projection: never auto-regress a
+      // `done` plan back to `in-progress`.
+      if (row.direction === 'downgrade') continue;
       yield* reconcilePlanStatus(row.name, row.derivedStatus === 'done', row.title);
       // Repairing a plan's status can flip its parent initiative's projection.
       yield* reconcileInitiativeForPlan(row.name);

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/storage/file-lock.ts

@@ -0,0 +1,49 @@
+/**
+ * Process-wide keyed mutex for serializing read-modify-write on shared files.
+ *
+ * Pi runs every tool call in a single Node process. When several tool calls run
+ * in one block (e.g. three `submit_initiative` calls, or concurrent
+ * `submit_plan` / `revise_plan`), each does an independent
+ * read → modify → write against the same registry file. Without serialization
+ * their reads all observe the same starting state and the last write clobbers
+ * the rest — a classic lost-update race.
+ *
+ * `withFileLock` wraps a read-modify-write critical section so only one runs at
+ * a time per `key` (the registry path). The semaphore is created eagerly with
+ * `unsafeMakeSemaphore` and cached per key, so its permit count lives in plain
+ * shared memory and serializes correctly even across independent
+ * `Effect.runPromise` invocations (separate tool executes).
+ *
+ * NOTE: this guards against in-process concurrency only. Atomic writes
+ * (`writeFileAtomic`) still protect against torn files from other processes,
+ * but cross-process registry coordination is out of scope.
+ */
+
+import { Effect } from 'effect';
+
+const locks = new Map<string, Effect.Semaphore>();
+
+function lockFor(key: string): Effect.Semaphore {
+  let lock = locks.get(key);
+  if (!lock) {
+    lock = Effect.unsafeMakeSemaphore(1);
+    locks.set(key, lock);
+  }
+  return lock;
+}
+
+/**
+ * Run `effect` while holding the single permit for `key`. Concurrent callers
+ * with the same key queue and run one at a time; the permit is always released,
+ * even on failure or interruption.
+ *
+ * Do NOT nest `withFileLock` for the same key inside another — the permit is
+ * not reentrant and would deadlock. Express composite read-modify-write as one
+ * locked section instead.
+ */
+export function withFileLock<A, E, R>(
+  key: string,
+  effect: Effect.Effect<A, E, R>,
+): Effect.Effect<A, E, R> {
+  return Effect.suspend(() => lockFor(key).withPermits(1)(effect));
+}

package/extensions/plan-mode/storage/initiatives-manifest.ts

@@ -18,6 +18,7 @@ import { FileSystem } from '../effects/filesystem.js';
 import { JsonlParseError, JsonlValidationError, PlanWriteError } from '../errors.js';
 import { decodeInitiativeManifestEntry } from '../schema.js';
 import type { InitiativeStatus } from '../types.js';
+import { withFileLock } from './file-lock.js';
 
 const MANIFEST_DIR = '.plans';
 const MANIFEST_PATH = '.plans/initiatives.jsonl';
@@ -86,27 +87,68 @@ export function writeInitiativesManifest(
   });
 }
 
+export interface InitiativeUpsert {
+  status: InitiativeStatus;
+  title?: string;
+  reason?: string;
+}
+
+/**
+ * Pure transform: upsert `name` into the in-memory `entries` array, preserving
+ * created_at from any existing entry. No IO — shared by the locked
+ * `upsertInitiativeEntry` and `reconcileInitiativeStatus` so both flow through
+ * one serialized read-modify-write and never nest locks.
+ */
+export function applyInitiativeUpsert(
+  entries: InitiativeManifestEntry[],
+  name: string,
+  updates: InitiativeUpsert,
+): void {
+  const now = new Date().toISOString();
+  const index = entries.findIndex((entry) => entry.name === name);
+  const existing = index === -1 ? undefined : entries[index];
+  const entry: InitiativeManifestEntry = {
+    _type: 'initiative',
+    name,
+    status: updates.status,
+    title: updates.title ?? existing?.title ?? 'Untitled initiative',
+    created_at: existing?.created_at ?? now,
+    // Terminal statuses record a completion timestamp; reopening clears it.
+    completed_at: isTerminalStatus(updates.status) ? (existing?.completed_at ?? now) : null,
+    reason: updates.reason ?? existing?.reason,
+  };
+  if (index === -1) entries.push(entry);
+  else entries[index] = entry;
+}
+
+/**
+ * Serialized read-modify-write of the initiatives registry. Holds a
+ * process-wide lock on the manifest path across the whole read → transform →
+ * write so concurrent tool calls cannot clobber each other. `transform` may run
+ * IO (e.g. read the plans manifest to project status) and mutates the entries
+ * array in place, returning `true` when it changed something.
+ */
+export function mutateInitiativesManifest<E, R>(
+  transform: (entries: InitiativeManifestEntry[]) => Effect.Effect<boolean, E, R>,
+): Effect.Effect<void, ReadError | PlanWriteError | E, FileSystem | R> {
+  return withFileLock(
+    MANIFEST_PATH,
+    Effect.gen(function* () {
+      const entries = yield* readInitiativesManifest();
+      const changed = yield* transform(entries);
+      if (changed) yield* writeInitiativesManifest(entries);
+    }),
+  );
+}
+
 export function upsertInitiativeEntry(
   name: string,
-  updates: { status: InitiativeStatus; title?: string; reason?: string },
+  updates: InitiativeUpsert,
 ): Effect.Effect<void, ReadError | PlanWriteError, FileSystem> {
-  return Effect.gen(function* () {
-    const entries = yield* readInitiativesManifest();
-    const now = new Date().toISOString();
-    const index = entries.findIndex((entry) => entry.name === name);
-    const existing = index === -1 ? undefined : entries[index];
-    const entry: InitiativeManifestEntry = {
-      _type: 'initiative',
-      name,
-      status: updates.status,
-      title: updates.title ?? existing?.title ?? 'Untitled initiative',
-      created_at: existing?.created_at ?? now,
-      // Terminal statuses record a completion timestamp; reopening clears it.
-      completed_at: isTerminalStatus(updates.status) ? (existing?.completed_at ?? now) : null,
-      reason: updates.reason ?? existing?.reason,
-    };
-    if (index === -1) entries.push(entry);
-    else entries[index] = entry;
-    yield* writeInitiativesManifest(entries);
-  });
+  return mutateInitiativesManifest((entries) =>
+    Effect.sync(() => {
+      applyInitiativeUpsert(entries, name, updates);
+      return true;
+    }),
+  );
 }

package/extensions/plan-mode/storage/plans-manifest.ts

@@ -3,6 +3,7 @@ import { FileSystem } from '../effects/filesystem.js';
 import { JsonlParseError, JsonlValidationError, PlanWriteError } from '../errors.js';
 import { decodePlanManifestEntry } from '../schema.js';
 import type { PlanStatus } from '../types.js';
+import { withFileLock } from './file-lock.js';
 
 const MANIFEST_DIR = '.plans';
 const MANIFEST_PATH = '.plans/plans.jsonl';
@@ -71,39 +72,74 @@ export function writePlansManifest(
   });
 }
 
+export interface PlanUpsert {
+  status: PlanStatus;
+  title?: string;
+  reason?: string;
+  /** Parent initiative name; preserved when omitted. */
+  initiative?: string;
+  /** Plan-level dependencies (plan names); preserved when omitted. */
+  depends_on?: string[];
+}
+
+/**
+ * Pure transform: upsert `name` into the in-memory `entries` array, preserving
+ * created_at / membership / deps from any existing entry. No IO — shared by the
+ * locked `upsertPlanEntry` and `reconcilePlanStatus` so both flow through one
+ * serialized read-modify-write and never nest locks.
+ */
+export function applyPlanUpsert(
+  entries: PlanManifestEntry[],
+  name: string,
+  updates: PlanUpsert,
+): void {
+  const now = new Date().toISOString();
+  const index = entries.findIndex((entry) => entry.name === name);
+  const existing = index === -1 ? undefined : entries[index];
+  const entry: PlanManifestEntry = {
+    _type: 'plan',
+    name,
+    status: updates.status,
+    title: updates.title ?? existing?.title ?? 'Untitled plan',
+    created_at: existing?.created_at ?? now,
+    // Terminal statuses record a completion timestamp; reopening clears it.
+    completed_at: isTerminalStatus(updates.status) ? (existing?.completed_at ?? now) : null,
+    reason: updates.reason ?? existing?.reason,
+    // Membership + plan-level deps are preserved across status-only upserts.
+    initiative: updates.initiative ?? existing?.initiative,
+    depends_on: updates.depends_on ?? existing?.depends_on,
+  };
+  if (index === -1) entries.push(entry);
+  else entries[index] = entry;
+}
+
+/**
+ * Serialized read-modify-write of the plans registry. Holds a process-wide lock
+ * on the manifest path across the whole read → transform → write so concurrent
+ * tool calls cannot clobber each other (lost-update race). `transform` mutates
+ * the entries array in place and returns `true` when it changed something
+ * (return `false` to skip the rewrite).
+ */
+export function mutatePlansManifest(
+  transform: (entries: PlanManifestEntry[]) => boolean,
+): Effect.Effect<void, ReadError | PlanWriteError, FileSystem> {
+  return withFileLock(
+    MANIFEST_PATH,
+    Effect.gen(function* () {
+      const entries = yield* readPlansManifest();
+      const changed = transform(entries);
+      if (changed) yield* writePlansManifest(entries);
+    }),
+  );
+}
+
 export function upsertPlanEntry(
   name: string,
-  updates: {
-    status: PlanStatus;
-    title?: string;
-    reason?: string;
-    /** Parent initiative name; preserved when omitted. */
-    initiative?: string;
-    /** Plan-level dependencies (plan names); preserved when omitted. */
-    depends_on?: string[];
-  },
+  updates: PlanUpsert,
 ): Effect.Effect<void, ReadError | PlanWriteError, FileSystem> {
-  return Effect.gen(function* () {
-    const entries = yield* readPlansManifest();
-    const now = new Date().toISOString();
-    const index = entries.findIndex((entry) => entry.name === name);
-    const existing = index === -1 ? undefined : entries[index];
-    const entry: PlanManifestEntry = {
-      _type: 'plan',
-      name,
-      status: updates.status,
-      title: updates.title ?? existing?.title ?? 'Untitled plan',
-      created_at: existing?.created_at ?? now,
-      // Terminal statuses record a completion timestamp; reopening clears it.
-      completed_at: isTerminalStatus(updates.status) ? (existing?.completed_at ?? now) : null,
-      reason: updates.reason ?? existing?.reason,
-      // Membership + plan-level deps are preserved across status-only upserts.
-      initiative: updates.initiative ?? existing?.initiative,
-      depends_on: updates.depends_on ?? existing?.depends_on,
-    };
-    if (index === -1) entries.push(entry);
-    else entries[index] = entry;
-    yield* writePlansManifest(entries);
+  return mutatePlansManifest((entries) => {
+    applyPlanUpsert(entries, name, updates);
+    return true;
   });
 }
 
@@ -123,16 +159,16 @@ export function reconcilePlanStatus(
   finalizable: boolean,
   title?: string,
 ): Effect.Effect<void, ReadError | PlanWriteError, FileSystem> {
-  return Effect.gen(function* () {
-    const entries = yield* readPlansManifest();
+  return mutatePlansManifest((entries) => {
     const existing = entries.find((entry) => entry.name === name);
     // Reconcile only reflects task state for KNOWN plans; never conjure an
     // entry for an unregistered plan (orphans are surfaced, not auto-created).
-    if (!existing) return;
+    if (!existing) return false;
     // Do not resurrect / clobber an explicitly closed plan.
-    if (existing.status === 'superseded' || existing.status === 'abandoned') return;
+    if (existing.status === 'superseded' || existing.status === 'abandoned') return false;
     const status: PlanStatus = finalizable ? 'done' : 'in-progress';
-    if (existing.status === status) return; // no change
-    yield* upsertPlanEntry(name, { status, title });
+    if (existing.status === status) return false; // no change
+    applyPlanUpsert(entries, name, { status, title });
+    return true;
   });
 }

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

@@ -11,6 +11,7 @@ import {
 } from '../errors.js';
 import { decodeTasksLine } from '../schema.js';
 import type { TaskMeta, TaskRecord } from '../types.js';
+import { withFileLock } from './file-lock.js';
 
 const TASKS_FILE = 'tasks.jsonl';
 
@@ -86,20 +87,25 @@ export function updateTask(
   ReadError | PlanWriteError | TasksFileNotFound | TaskNotFound,
   FileSystem
 > {
-  return Effect.gen(function* () {
-    const snapshot = yield* readTasksJsonl(planDir);
-    if (!snapshot) return yield* Effect.fail(new TasksFileNotFound({ planDir }));
+  // Serialize the read-modify-write so concurrent task updates to the same plan
+  // (e.g. parallel update_task / update_tasks calls) cannot clobber each other.
+  return withFileLock(
+    join(planDir, TASKS_FILE),
+    Effect.gen(function* () {
+      const snapshot = yield* readTasksJsonl(planDir);
+      if (!snapshot) return yield* Effect.fail(new TasksFileNotFound({ planDir }));
 
-    const index = snapshot.tasks.findIndex((task) => task.id === taskId);
-    if (index === -1) return yield* Effect.fail(new TaskNotFound({ planDir, taskId }));
+      const index = snapshot.tasks.findIndex((task) => task.id === taskId);
+      if (index === -1) return yield* Effect.fail(new TaskNotFound({ planDir, taskId }));
 
-    const updated: TaskRecord = {
-      ...snapshot.tasks[index],
-      ...updates,
-      updated_at: new Date().toISOString(),
-    };
-    snapshot.tasks[index] = updated;
-    yield* writeTasksJsonl(planDir, snapshot.meta, snapshot.tasks);
-    return updated;
-  });
+      const updated: TaskRecord = {
+        ...snapshot.tasks[index],
+        ...updates,
+        updated_at: new Date().toISOString(),
+      };
+      snapshot.tasks[index] = updated;
+      yield* writeTasksJsonl(planDir, snapshot.meta, snapshot.tasks);
+      return updated;
+    }),
+  );
 }

package/extensions/plan-mode/tools/reconcile-plans.ts

@@ -29,6 +29,10 @@ function describeRow(row: PlanDriftRow): string {
     return `  ⚠ ${row.name}${progress} — tasks.jsonl with no registry entry (orphan)`;
   }
   if (row.drift === 'status') {
+    if (row.direction === 'downgrade') {
+      // Wrong-direction projection: do NOT auto-repair. Mark tasks done instead.
+      return `  ⚠ ${row.name}${progress} — registry ${row.registryStatus}, tasks say ${row.derivedStatus} (likely merged; mark tasks done — not auto-repaired)`;
+    }
     return `  ✗ ${row.name}${progress} — registry ${row.registryStatus}, tasks say ${row.derivedStatus}`;
   }
   return `  ✓ ${row.name}${progress} — ${row.registryStatus} (in sync)`;
@@ -44,6 +48,7 @@ export function registerReconcilePlansTool(pi: ExtensionAPI, runPlanIO: RunPlanI
     promptGuidelines: [
       'Use reconcile_plans to audit .plans/ when registry status looks stale (e.g. a fully-done plan still in-progress).',
       'Run it read-only first; pass apply:true once you have reviewed the reported drift.',
+      'apply:true only records completion (in-progress→done). It never regresses a done plan back to in-progress — if a done plan shows incomplete tasks (work merged but tasks not marked), mark those tasks done instead.',
     ],
     parameters: Type.Object({
       apply: Type.Optional(
@@ -76,7 +81,12 @@ export function registerReconcilePlansTool(pi: ExtensionAPI, runPlanIO: RunPlanI
             ? `  ✗ ${row.name} (initiative, ${row.members} plans) — registry ${row.registryStatus}, plans say ${row.derivedStatus}`
             : `  ✓ ${row.name} (initiative, ${row.members} plans) — ${row.registryStatus} (in sync)`,
       );
-      const statusDrift = drifted.filter((r) => r.drift === 'status').length;
+      const statusDrift = drifted.filter(
+        (r) => r.drift === 'status' && r.direction === 'upgrade',
+      ).length;
+      const downgrades = drifted.filter(
+        (r) => r.drift === 'status' && r.direction === 'downgrade',
+      ).length;
       const orphans = drifted.filter((r) => r.drift === 'orphan').length;
       const registryOnly = drifted.filter((r) => r.drift === 'registry-only').length;
 
@@ -89,6 +99,7 @@ export function registerReconcilePlansTool(pi: ExtensionAPI, runPlanIO: RunPlanI
 
       const summary = [
         `status-drift ${statusDrift}`,
+        `needs-tasks-done ${downgrades}`,
         `orphan ${orphans}`,
         `registry-only ${registryOnly}`,
       ].join(', ');
@@ -102,7 +113,7 @@ export function registerReconcilePlansTool(pi: ExtensionAPI, runPlanIO: RunPlanI
         details: {
           applied: Boolean(params.apply),
           repaired: repaired.map((r) => r.name),
-          drift: drifted.map((r) => ({ name: r.name, kind: r.drift })),
+          drift: drifted.map((r) => ({ name: r.name, kind: r.drift, direction: r.direction })),
           total: rows.length,
           initiative_repaired: initiativeRepaired.map((r) => r.name),
           initiative_drift: initiativeDrifted.map((r) => ({ name: r.name, kind: r.drift })),

package/package.json

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