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

package/extensions/plan-mode/commands/list-initiatives.ts

@@ -0,0 +1,148 @@
+/**
+ * /initiatives command — list, filter, and sort initiatives interactively.
+ *
+ * The initiative sibling of /plans. Reads the initiatives registry plus the
+ * plans manifest to roll up member-plan progress (done/total, ready/blocked).
+ */
+
+import { Effect } from 'effect';
+import type { ExtensionCommandContext } from '@earendil-works/pi-coding-agent';
+import type { RunPlanIO } from '../effects/runtime.js';
+import { FileSystem } from '../effects/filesystem.js';
+import { readPlansManifest, type PlanManifestEntry } from '../storage/plans-manifest.js';
+import {
+  readInitiativesManifest,
+  type InitiativeManifestEntry,
+} from '../storage/initiatives-manifest.js';
+import { initiativeRollup } from '../initiative.js';
+import type { InitiativeStatus } from '../types.js';
+
+export type StatusFilter = 'all' | InitiativeStatus;
+
+export interface InitiativeListItem {
+  name: string;
+  title: string;
+  status: InitiativeStatus;
+  created_at: string;
+  totalPlans: number;
+  donePlans: number;
+  ready: number;
+  blocked: number;
+}
+
+export function filterInitiatives(
+  items: InitiativeListItem[],
+  filter: StatusFilter,
+): InitiativeListItem[] {
+  if (filter === 'all') return items;
+  return items.filter((i) => i.status === filter);
+}
+
+const STATUS_ICON: Record<InitiativeStatus, string> = {
+  'in-progress': '🔵',
+  done: '✅',
+  superseded: '🔄',
+  abandoned: '❌',
+};
+
+export function formatInitiativeList(items: InitiativeListItem[], filter: StatusFilter): string {
+  if (items.length === 0) {
+    return filter === 'all'
+      ? 'No initiatives found in .plans/initiatives.jsonl'
+      : `No initiatives with status "${filter}"`;
+  }
+  const header =
+    filter === 'all'
+      ? `All initiatives (${items.length})`
+      : `Initiatives: ${filter} (${items.length})`;
+  const lines = items.map((i) => {
+    const icon = STATUS_ICON[i.status];
+    const progress =
+      i.totalPlans > 0
+        ? ` [${i.donePlans}/${i.totalPlans} plans, ready ${i.ready}, blocked ${i.blocked}]`
+        : ' [no plans]';
+    const date = i.created_at.slice(0, 10);
+    return `  ${icon} ${i.name} — ${i.title}${progress}  (${date})`;
+  });
+  return `${header}\n${lines.join('\n')}`;
+}
+
+export function loadInitiativeListItems(): Effect.Effect<InitiativeListItem[], never, FileSystem> {
+  return Effect.gen(function* () {
+    const initiatives = yield* Effect.orElseSucceed(
+      readInitiativesManifest(),
+      () => [] as InitiativeManifestEntry[],
+    );
+    const plans = yield* Effect.orElseSucceed(
+      readPlansManifest(),
+      () => [] as PlanManifestEntry[],
+    );
+    return initiatives.map((entry): InitiativeListItem => {
+      const r = initiativeRollup(entry.name, plans);
+      return {
+        name: entry.name,
+        title: entry.title,
+        status: entry.status,
+        created_at: entry.created_at,
+        totalPlans: r.total,
+        donePlans: r.done,
+        ready: r.ready,
+        blocked: r.blocked,
+      };
+    });
+  });
+}
+
+const FILTER_ALIASES: Record<string, StatusFilter> = {
+  all: 'all',
+  'in-progress': 'in-progress',
+  active: 'in-progress',
+  done: 'done',
+  completed: 'done',
+  superseded: 'superseded',
+  abandoned: 'abandoned',
+};
+
+export function parseFilter(raw: string): StatusFilter {
+  for (const token of raw.toLowerCase().split(/\s+/)) {
+    if (FILTER_ALIASES[token]) return FILTER_ALIASES[token];
+  }
+  return 'all';
+}
+
+export async function handleListInitiatives(
+  ctx: ExtensionCommandContext,
+  runPlanIO: RunPlanIO,
+  args?: string,
+): Promise<void> {
+  const items = await runPlanIO(loadInitiativeListItems());
+  if (items.length === 0) {
+    ctx.ui.notify('No initiatives found in .plans/initiatives.jsonl', 'info');
+    return;
+  }
+
+  let filter: StatusFilter = 'all';
+  if (args?.trim()) {
+    filter = parseFilter(args.trim());
+  } else {
+    const choice = await ctx.ui.select('Filter initiatives by status:', [
+      'All',
+      'In-progress',
+      'Done',
+      'Superseded',
+      'Abandoned',
+    ]);
+    if (!choice) return;
+    const map: Record<string, StatusFilter> = {
+      All: 'all',
+      'In-progress': 'in-progress',
+      Done: 'done',
+      Superseded: 'superseded',
+      Abandoned: 'abandoned',
+    };
+    filter = map[choice] ?? 'all';
+  }
+
+  const filtered = filterInitiatives(items, filter);
+  ctx.ui.notify(formatInitiativeList(filtered, filter), 'info');
+}

package/extensions/plan-mode/constants.ts

@@ -10,6 +10,7 @@ export const PLAN_TOOLS = [
   'find',
   'ls',
   'submit_plan',
+  'submit_initiative',
   'revise_plan',
   'preview_prototype',
   'write',
@@ -19,6 +20,8 @@ export const PLAN_TOOLS = [
   'plan_status',
   'set_active_plan',
   'update_plan',
+  'update_initiative',
+  'initiative_status',
   'reconcile_plans',
 ];
 
@@ -33,6 +36,8 @@ export const EXEC_TOOLS = [
   'plan_status',
   'set_active_plan',
   'update_plan',
+  'update_initiative',
+  'initiative_status',
   'reconcile_plans',
 ];
 

package/extensions/plan-mode/index.ts

@@ -39,8 +39,10 @@ import { activeTasksResolved, deferredTasks, isPlanFinalizable } from './task-st
 import { enterPlanMode, exitPlanMode, switchModel } from './phase-transitions.js';
 import { resumePlan, executeInNewSession } from './resume.js';
 import { resolveActivePlan, focusActivePlan } from './resolve-plan.js';
+import { reconcileInitiativeForPlan } from './initiative.js';
 import { collectPlanDrift } from './reconcile.js';
 import { registerSubmitPlanTool } from './tools/submit-plan.js';
+import { registerSubmitInitiativeTool } from './tools/submit-initiative.js';
 import { registerRevisePlanTool } from './tools/revise-plan.js';
 import { registerPreviewPrototypeTool } from './tools/preview-prototype.js';
 import { registerUpdateTaskTool } from './tools/update-task.js';
@@ -49,9 +51,12 @@ import { registerAddTaskTool } from './tools/add-task.js';
 import { registerPlanStatusTool } from './tools/plan-status.js';
 import { registerSetActivePlanTool } from './tools/set-active-plan.js';
 import { registerUpdatePlanTool } from './tools/update-plan.js';
+import { registerUpdateInitiativeTool } from './tools/update-initiative.js';
+import { registerInitiativeStatusTool } from './tools/initiative-status.js';
 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';
 
 export default function planMode(pi: ExtensionAPI): void {
   const state = new PlanModeState();
@@ -83,6 +88,8 @@ export default function planMode(pi: ExtensionAPI): void {
     },
   });
 
+  registerSubmitInitiativeTool(pi, runPlanIO);
+
   registerPreviewPrototypeTool(pi, runPlanIO);
 
   // Shared task-write closure: mutate the in-memory task, persist tasks.jsonl,
@@ -120,6 +127,8 @@ export default function planMode(pi: ExtensionAPI): void {
         state.plan.title,
       ),
     );
+    // Project plan status up to its parent initiative (no-op when standalone).
+    await runPlanIO(reconcileInitiativeForPlan(state.plan.planName));
     state.persist(pi);
   };
 
@@ -162,6 +171,7 @@ export default function planMode(pi: ExtensionAPI): void {
           state.plan.title,
         ),
       );
+      await runPlanIO(reconcileInitiativeForPlan(state.plan.planName));
       state.persist(pi);
     },
   });
@@ -186,6 +196,8 @@ export default function planMode(pi: ExtensionAPI): void {
   });
 
   registerUpdatePlanTool(pi, runPlanIO);
+  registerUpdateInitiativeTool(pi, runPlanIO);
+  registerInitiativeStatusTool(pi, runPlanIO);
   registerReconcilePlansTool(pi, runPlanIO);
 
   registerAddTaskTool(pi, {
@@ -214,6 +226,7 @@ export default function planMode(pi: ExtensionAPI): void {
           state.plan.title,
         ),
       );
+      await runPlanIO(reconcileInitiativeForPlan(state.plan.planName));
       state.persist(pi);
     },
   });
@@ -277,6 +290,14 @@ export default function planMode(pi: ExtensionAPI): void {
     },
   });
 
+  pi.registerCommand('initiatives', {
+    description:
+      'List all initiatives with member-plan rollup. Usage: /initiatives [filter]. Filters: all, in-progress, done, superseded, abandoned.',
+    handler: async (args, ctx) => {
+      await handleListInitiatives(ctx, runPlanIO, args);
+    },
+  });
+
   pi.registerCommand('todos', {
     description: 'Show current plan progress',
     handler: async (_args, ctx) => {
@@ -513,6 +534,7 @@ export default function planMode(pi: ExtensionAPI): void {
           await runPlanIO(
             upsertPlanEntry(state.plan.planName, { status: 'done', title: state.plan.title }),
           );
+          await runPlanIO(reconcileInitiativeForPlan(state.plan.planName));
           await runPlanIO(
             writeTasksJsonl(
               state.planDir,

package/extensions/plan-mode/initiative.ts

@@ -0,0 +1,172 @@
+/**
+ * Initiative logic — ready-work computation and the initiative→plan projection.
+ *
+ * Two layers live here:
+ *   - PURE: `computePlanReadiness`, `isInitiativeFinalizable`, `initiativeRollup`
+ *     reason over a plans-manifest snapshot with no IO. They are the basis for
+ *     "what work is unblocked right now" — the foundation for phase-2 subagent
+ *     fan-out.
+ *   - IO: `reconcileInitiativeStatus` / `reconcileInitiativeForPlan` keep an
+ *     initiative's registry status a PROJECTION of its member plans, mirroring
+ *     `reconcilePlanStatus` one level up. They read the PLANS manifest, so they
+ *     live here (not in `initiatives-manifest.ts`) to keep the dependency
+ *     direction one-way: initiative.ts → {plans-manifest, initiatives-manifest}.
+ */
+
+import { Effect } from 'effect';
+import { FileSystem } from './effects/filesystem.js';
+import type { JsonlParseError, JsonlValidationError, PlanWriteError } from './errors.js';
+import { readPlansManifest, type PlanManifestEntry } from './storage/plans-manifest.js';
+import {
+  applyInitiativeUpsert,
+  mutateInitiativesManifest,
+} from './storage/initiatives-manifest.js';
+import type { PlanStatus } from './types.js';
+
+// ── Pure: readiness + projection rules ───────────────────────────────────────
+
+export interface PlanReadiness {
+  name: string;
+  /** True when every plan in `depends_on` is `done`. */
+  ready: boolean;
+  /** Dependency plan names that are not yet `done` (unknown deps count too). */
+  blockedBy: string[];
+}
+
+/**
+ * For each `in-progress` plan, whether all of its plan-level dependencies are
+ * `done`. Only a `done` dependency unblocks — a missing, in-progress, or
+ * terminally-closed (superseded/abandoned) dependency keeps a plan blocked.
+ */
+export function computePlanReadiness(plans: readonly PlanManifestEntry[]): PlanReadiness[] {
+  const statusByName = new Map(plans.map((plan) => [plan.name, plan.status]));
+  return plans
+    .filter((plan) => plan.status === 'in-progress')
+    .map((plan) => {
+      const deps = plan.depends_on ?? [];
+      const blockedBy = deps.filter((dep) => statusByName.get(dep) !== 'done');
+      return { name: plan.name, ready: blockedBy.length === 0, blockedBy };
+    });
+}
+
+/** Member plans of an initiative (linked by name in the plans manifest). */
+export function membersOf(
+  initiative: string,
+  plans: readonly PlanManifestEntry[],
+): PlanManifestEntry[] {
+  return plans.filter((plan) => plan.initiative === initiative);
+}
+
+/**
+ * An initiative is finalizable (`done`) when it has ≥1 member plan AND every
+ * member is terminal (no member is `in-progress`). Mirrors the plan-level rule
+ * one level up.
+ */
+export function isInitiativeFinalizable(
+  initiative: string,
+  plans: readonly PlanManifestEntry[],
+): boolean {
+  const members = membersOf(initiative, plans);
+  if (members.length === 0) return false;
+  return members.every((plan) => plan.status !== 'in-progress');
+}
+
+export interface InitiativeMemberRow {
+  name: string;
+  title: string;
+  status: PlanStatus;
+  /** Present for in-progress members. */
+  ready?: boolean;
+  blockedBy?: string[];
+}
+
+export interface InitiativeRollup {
+  name: string;
+  total: number;
+  done: number;
+  /** Terminal but not done (superseded / abandoned). */
+  closed: number;
+  inProgress: number;
+  ready: number;
+  blocked: number;
+  members: InitiativeMemberRow[];
+}
+
+/** Aggregate an initiative's member plans into counts + per-member readiness. */
+export function initiativeRollup(
+  initiative: string,
+  plans: readonly PlanManifestEntry[],
+): InitiativeRollup {
+  const members = membersOf(initiative, plans);
+  const readiness = new Map(computePlanReadiness(plans).map((row) => [row.name, row]));
+
+  let done = 0;
+  let closed = 0;
+  let inProgress = 0;
+  let ready = 0;
+  let blocked = 0;
+
+  const rows: InitiativeMemberRow[] = members.map((plan) => {
+    if (plan.status === 'done') done += 1;
+    else if (plan.status === 'in-progress') inProgress += 1;
+    else closed += 1; // superseded / abandoned
+
+    const row: InitiativeMemberRow = { name: plan.name, title: plan.title, status: plan.status };
+    if (plan.status === 'in-progress') {
+      const r = readiness.get(plan.name);
+      row.ready = r?.ready ?? true;
+      row.blockedBy = r?.blockedBy ?? [];
+      if (row.ready) ready += 1;
+      else blocked += 1;
+    }
+    return row;
+  });
+
+  return { name: initiative, total: members.length, done, closed, inProgress, ready, blocked, members: rows };
+}
+
+// ── IO: keep initiative registry status a projection of member plans ─────────
+
+type ReconcileError = JsonlParseError | JsonlValidationError | PlanWriteError;
+
+/**
+ * Re-derive an initiative's registry status from its member plans.
+ *
+ * Like `reconcilePlanStatus`: only reflects state for a KNOWN initiative (never
+ * conjures an entry), and never clobbers a manually-set terminal status
+ * (`superseded` / `abandoned`). Only `in-progress` ⇄ `done` is derived.
+ */
+export function reconcileInitiativeStatus(
+  name: string,
+): Effect.Effect<void, ReconcileError, FileSystem> {
+  // 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;
+    }),
+  );
+}
+
+/**
+ * Reconcile the initiative that a given plan belongs to (no-op when the plan is
+ * standalone). Call this after any plan-status write so the initiative level
+ * stays in sync without callers needing to know the parent name.
+ */
+export function reconcileInitiativeForPlan(
+  planName: string,
+): Effect.Effect<void, ReconcileError, FileSystem> {
+  return Effect.gen(function* () {
+    const plans = yield* readPlansManifest();
+    const plan = plans.find((entry) => entry.name === planName);
+    if (!plan?.initiative) return;
+    yield* reconcileInitiativeStatus(plan.initiative);
+  });
+}

package/extensions/plan-mode/prompts.ts

@@ -33,6 +33,10 @@ Plan weight:
 
 submit_plan is finalization, not the starting point. It records tasks and the handoff — it does not generate HTML.
 
+Sizing the work — flat plan vs initiative:
+- For a bounded change that fits one coherent execution session, submit a single flat plan.
+- For LARGE work that does not fit one session, or spans multiple subsystems with dependencies between chunks, create an **initiative** first with submit_initiative, then submit each executable chunk as its own plan with \`initiative\` set and \`depends_on_plans\` capturing ordering. An initiative's status is a projection of its member plans; \`initiative_status\` shows which member plans are READY (all dependencies done) so the work can be split across sessions or subagents. Use \`/initiatives\` and \`update_initiative\` to track and close initiatives.
+
 If a plan with the same name already exists and the user asks for follow-up changes (e.g. you submitted prematurely), call revise_plan instead of submit_plan. It rewrites the existing plan in place — pass only the fields that change (title, handoff, and/or tasks); status and notes are preserved for tasks whose id is unchanged.
 
 For visual/UI/layout/style work, build a prototype with preview_prototype DURING planning, before submit_plan, so the user can react to the visual before the plan hardens. You author the HTML freely — no template engine, no imposed theme — and can delegate the markup to the ux-designer subagent for real design taste. The visual-prototype skill covers when and how.

package/extensions/plan-mode/reconcile.ts

@@ -22,6 +22,13 @@ import type {
   PlanWriteError,
 } from './errors.js';
 import { readPlansManifest, reconcilePlanStatus } from './storage/plans-manifest.js';
+import { readInitiativesManifest } from './storage/initiatives-manifest.js';
+import {
+  isInitiativeFinalizable,
+  membersOf,
+  reconcileInitiativeForPlan,
+  reconcileInitiativeStatus,
+} from './initiative.js';
 import { readTasksJsonl } from './storage/task-storage.js';
 import { isPlanFinalizable } from './task-status.js';
 import type { PlanStatus } from './types.js';
@@ -48,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;
@@ -85,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,
@@ -94,6 +119,7 @@ export function collectPlanDrift(): Effect.Effect<PlanDriftRow[], CollectError,
         total,
         hasTasks: true,
         drift,
+        direction,
       });
     }
 
@@ -121,10 +147,73 @@ export function collectPlanDrift(): Effect.Effect<PlanDriftRow[], CollectError,
   });
 }
 
+// ── Initiative-level drift ───────────────────────────────────────────────────
+
+export interface InitiativeDriftRow {
+  name: string;
+  registryStatus: PlanStatus;
+  title: string;
+  /** Projected from member plans: `done` when finalizable, else `in-progress`. */
+  derivedStatus: 'in-progress' | 'done';
+  members: number;
+  /** 'status' when the registry status disagrees with the projection. */
+  drift?: 'status';
+}
+
+/** Compare each initiative's registry status against its member-plan projection. */
+export function collectInitiativeDrift(): Effect.Effect<
+  InitiativeDriftRow[],
+  CollectError,
+  FileSystem
+> {
+  return Effect.gen(function* () {
+    const initiatives = yield* readInitiativesManifest();
+    const plans = yield* readPlansManifest();
+    return initiatives.map((entry) => {
+      const derivedStatus: 'in-progress' | 'done' = isInitiativeFinalizable(entry.name, plans)
+        ? 'done'
+        : 'in-progress';
+      // Terminal statuses (superseded/abandoned) are intentional — never drift.
+      const isTerminalManual = entry.status === 'superseded' || entry.status === 'abandoned';
+      const drift = !isTerminalManual && entry.status !== derivedStatus ? ('status' as const) : undefined;
+      return {
+        name: entry.name,
+        registryStatus: entry.status,
+        title: entry.title,
+        derivedStatus,
+        members: membersOf(entry.name, plans).length,
+        drift,
+      };
+    });
+  });
+}
+
+/** Repair `status`-class initiative drift by re-projecting from member plans. */
+export function applyInitiativeReconcile(
+  rows: InitiativeDriftRow[],
+): Effect.Effect<InitiativeDriftRow[], CollectError | PlanWriteError, FileSystem> {
+  return Effect.gen(function* () {
+    const repaired: InitiativeDriftRow[] = [];
+    for (const row of rows) {
+      if (row.drift !== 'status') continue;
+      yield* reconcileInitiativeStatus(row.name);
+      repaired.push(row);
+    }
+    return repaired;
+  });
+}
+
 /**
  * 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[],
@@ -133,7 +222,12 @@ 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);
       repaired.push(row);
     }
     return repaired;

package/extensions/plan-mode/schema.ts

@@ -55,6 +55,31 @@ export const PlanManifestEntrySchema = Schema.Struct({
   completed_at: Schema.NullOr(Schema.String),
   /** Optional human-readable reason, used for terminal statuses. */
   reason: Schema.optional(Schema.String),
+  /** Parent initiative name (kebab). Absent = standalone flat plan. */
+  initiative: Schema.optional(Schema.String),
+  /**
+   * Plan-level dependencies: names of plans this plan depends on. Distinct from
+   * the task-level `depends_on` above. Cross-initiative references are allowed.
+   */
+  depends_on: Schema.optional(Schema.mutable(Schema.Array(Schema.String))),
+});
+
+/**
+ * Initiative lifecycle statuses reuse the plan lifecycle literals. An
+ * initiative's status is a projection of its member plans' statuses, with the
+ * same terminal-guard semantics as plans.
+ */
+export const InitiativeStatusSchema = PlanStatusSchema;
+
+export const InitiativeManifestEntrySchema = Schema.Struct({
+  _type: Schema.Literal('initiative'),
+  name: Schema.String,
+  status: InitiativeStatusSchema,
+  title: Schema.String,
+  created_at: Schema.String,
+  completed_at: Schema.NullOr(Schema.String),
+  /** Optional human-readable reason, used for terminal statuses. */
+  reason: Schema.optional(Schema.String),
 });
 
 export const ExecPendingConfigSchema = Schema.Struct({
@@ -66,4 +91,7 @@ export const decodeTaskRecord = Schema.decodeUnknownEither(TaskRecordSchema);
 export const decodeTaskMeta = Schema.decodeUnknownEither(TaskMetaSchema);
 export const decodeTasksLine = Schema.decodeUnknownEither(TasksLineSchema);
 export const decodePlanManifestEntry = Schema.decodeUnknownEither(PlanManifestEntrySchema);
+export const decodeInitiativeManifestEntry = Schema.decodeUnknownEither(
+  InitiativeManifestEntrySchema,
+);
 export const decodeExecPendingConfig = Schema.decodeUnknownEither(ExecPendingConfigSchema);

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));
+}