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

package/CHANGELOG.md

@@ -1,5 +1,14 @@
 # @dreki-gg/pi-plan-mode
 
+## 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__/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/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/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.24.1",
   "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"