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

package/CHANGELOG.md

@@ -1,5 +1,30 @@
 # @dreki-gg/pi-plan-mode
 
+## 0.24.0
+
+### Minor Changes
+
+- Add an **initiatives** layer above plans for decomposing large work (beads-style grouping + cross-plan dependencies).
+
+  - New `submit_initiative`, `update_initiative`, and `initiative_status` tools, plus a `/initiatives` command.
+  - `submit_plan` / `revise_plan` gain optional `initiative` and `depends_on_plans` (plan-level dependencies; cross-initiative allowed).
+  - An initiative's status is a projection of its member plans (mirroring how a plan's status projects from its tasks); `done` is derived automatically while `superseded` / `abandoned` stay explicit.
+  - `initiative_status` computes ready-work — which member plans are unblocked (all dependencies `done`) vs blocked-by — so work can be split across sessions or subagents.
+  - `reconcile_plans` now also detects/repairs initiative-level status drift; the `clean` CLI archives closed initiatives alongside closed plans.
+  - New `.plans/initiatives.jsonl` registry and `.plans/<initiative>/INITIATIVE.md` overview. All new fields are optional — existing flat plans are unaffected.
+
+## 0.23.0
+
+### Minor Changes
+
+- `preview_prototype` is now freeform. The tool dropped its Pug dependency and the imposed wrapper template (fixed dark theme, badge header, purple-accent panel) that made every prototype look the same. It now takes a `html` parameter — a complete, self-contained HTML document the agent authors with full freedom over markup, fonts, colors, layout, and inline scripts — and only persists and opens it. A bare fragment is tolerated and wrapped in a minimal unstyled shell. The `visual-prototype` skill and plan-mode prompt now steer the agent toward product-fitting designs and toward delegating the markup to the `ux-designer` subagent for real design taste, instead of generic boilerplate.
+
+## 0.22.0
+
+### Minor Changes
+
+- Add `/plans` command to list, filter, and sort plans interactively. Supports filtering by status (in-progress, done, superseded, abandoned) and sorting by date, task count, or name. Works both interactively and with inline args (e.g. `/plans done oldest`).
+
 ## 0.21.0
 
 ### Minor Changes

package/README.md

@@ -24,6 +24,8 @@ pi install npm:@dreki-gg/pi-questionnaire
 | Command  | `/plan [prompt]` | Enter plan mode, optionally with a starting prompt |
 | Command  | `/plan resume` | Pick up an in-progress plan from disk          |
 | Command  | `/plan focus <name>` | Pin a plan so tracking calls default to it (multi-plan repos) |
+| Command  | `/plans`       | List/filter/sort plans                          |
+| Command  | `/initiatives` | List initiatives with member-plan rollup        |
 | Command  | `/todos`       | Show current plan progress                     |
 | Shortcut | `Ctrl+Alt+P`   | Toggle plan mode                               |
 | Tool     | `revise_plan`  | Rewrite an existing plan in place (title/handoff/tasks) |
@@ -33,7 +35,45 @@ pi install npm:@dreki-gg/pi-questionnaire
 | Tool     | `plan_status`  | Read-only snapshot; progress table when many plans are active |
 | Tool     | `set_active_plan` | Pin a plan as active (tool form of `/plan focus`) so tracking calls target it |
 | Tool     | `update_plan`  | Close/reopen a plan: done, superseded, abandoned, in-progress |
-| Tool     | `reconcile_plans` | Detect & repair drift between tasks.jsonl and the registry |
+| Tool     | `submit_initiative` | Create an initiative that groups multiple plans          |
+| Tool     | `update_initiative` | Close/reopen an initiative: done, superseded, abandoned, in-progress |
+| Tool     | `initiative_status` | Snapshot an initiative: member plans, progress, ready/blocked |
+| Tool     | `reconcile_plans` | Detect & repair drift between tasks.jsonl and the registry (plans **and** initiatives) |
+
+## Initiatives — grouping large work
+
+When a body of work is too large for a single plan, group it under an **initiative**.
+An initiative is one level above a plan; the same projection rule applies one level up:
+
+```
+Initiative  status = projection of its member plans' statuses
+   Plan     status = projection of its tasks' statuses
+      Task  base state
+```
+
+An initiative is `done` when it has ≥1 member plan and every member is terminal
+(`done` / `superseded` / `abandoned`). Member plans link to the initiative by name and
+carry **plan-level** `depends_on` (cross-initiative allowed), so the extension can compute
+*ready work* — plans whose dependencies are all `done`. `initiative_status` surfaces, per
+member plan, whether it is **ready** or **blocked by** which plans — the view you want when
+splitting an initiative across sessions or subagents.
+
+```text
+# 1. Create the initiative
+submit_initiative(name: "auth-overhaul", title: "Auth Overhaul", overview: "...")
+
+# 2. Submit member plans linked + ordered
+submit_plan(name: "auth-schema",  initiative: "auth-overhaul")
+submit_plan(name: "auth-jwt",     initiative: "auth-overhaul", depends_on_plans: ["auth-schema"])
+submit_plan(name: "auth-ui",      initiative: "auth-overhaul", depends_on_plans: ["auth-jwt"])
+
+# 3. See what's ready to pick up
+initiative_status(initiative: "auth-overhaul")
+```
+
+Initiative lifecycle mirrors plans: `done` is projected automatically, while `superseded` /
+`abandoned` (and reopen) are explicit via `update_initiative` with a `reason`. The `clean`
+CLI archives closed initiatives the same way it archives closed plans.
 
 ### Plan lifecycle status
 
@@ -99,10 +139,13 @@ When **Execute Plan** is selected:
 
 ```
 .plans/
-├── plans.json                # Tracking manifest — plan status lifecycle
-└── add-auth-middleware/
-    ├── PLAN.md               # Numbered plan with context
-    ├── START-PROMPT.md       # Self-contained executor handoff prompt
+├── plans.jsonl               # Plan registry — plan status lifecycle
+├── initiatives.jsonl         # Initiative registry — groups member plans
+├── auth-overhaul/            # An initiative directory
+│   └── INITIATIVE.md         # Initiative overview + plan breakdown
+└── auth-jwt/                 # A member plan (linked by name in the registry)
+    ├── HANDOFF.md            # Self-contained executor handoff
+    ├── tasks.jsonl           # Tasks (gains optional initiative + plan-level depends_on)
     └── ...                   # Optional supporting files
 ```
 

package/bin/clean-plans.js

@@ -1,16 +1,16 @@
 #!/usr/bin/env node
 /**
- * CLI to clean closed plans from `.plans/`.
+ * CLI to clean closed plans (and initiatives) from `.plans/`.
  *
  * Usage:
  *   npx @dreki-gg/pi-plan-mode clean [--dry-run] [--purge]
  *
- * Reads `.plans/plans.jsonl`, and for every plan whose status is terminal
- * (done / superseded / abandoned):
- *   - default:  ARCHIVES the plan directory to `.plans/.archive/<name>/`
- *               (non-destructive — keeps HANDOFF.md + tasks.jsonl as a record)
- *   - --purge:  permanently deletes the plan directory
- * In both cases the entry is removed from the active `plans.jsonl` registry.
+ * Reads `.plans/plans.jsonl` and `.plans/initiatives.jsonl`, and for every
+ * entry whose status is terminal (done / superseded / abandoned):
+ *   - default:  ARCHIVES the directory to `.plans/.archive/<name>/`
+ *               (non-destructive — keeps HANDOFF.md / INITIATIVE.md as a record)
+ *   - --purge:  permanently deletes the directory
+ * In both cases the entry is removed from its active registry.
  *
  * Designed for use in GitHub Actions after merge — similar to changesets.
  * History-preserving by default (FEEDBACK #4): closing out a finished plan must
@@ -22,12 +22,13 @@ import { resolve, join } from 'node:path';
 
 const PLANS_DIR = '.plans';
 const ARCHIVE_DIR = join(PLANS_DIR, '.archive');
-const MANIFEST_PATH = join(PLANS_DIR, 'plans.jsonl');
+const PLANS_MANIFEST = join(PLANS_DIR, 'plans.jsonl');
+const INITIATIVES_MANIFEST = join(PLANS_DIR, 'initiatives.jsonl');
 
 const TERMINAL_STATUSES = new Set(['done', 'superseded', 'abandoned']);
 
-/** Parse `.plans/plans.jsonl` into an array of plan entries. */
-function readManifest(path) {
+/** Parse a `.jsonl` registry into an array of entries. */
+function readManifest(path, label) {
   const text = readFileSync(path, 'utf-8');
   const entries = [];
   for (const [index, raw] of text.split(/\r?\n/).entries()) {
@@ -35,7 +36,7 @@ function readManifest(path) {
     try {
       entries.push(JSON.parse(raw));
     } catch (err) {
-      console.error(`Failed to parse ${MANIFEST_PATH} at line ${index + 1}:`, err);
+      console.error(`Failed to parse ${label} at line ${index + 1}:`, err);
       process.exit(1);
     }
   }
@@ -48,45 +49,31 @@ function writeManifest(path, entries) {
   writeFileSync(path, content);
 }
 
-function main() {
-  const args = process.argv.slice(2);
-  const command = args[0];
-
-  if (command !== 'clean') {
-    console.error('Usage: pi-plan-mode clean [--dry-run] [--purge]\n');
-    console.error('Commands:');
-    console.error('  clean       Archive closed plan directories and update plans.jsonl\n');
-    console.error('Options:');
-    console.error('  --dry-run   Show what would be cleaned without changing anything');
-    console.error('  --purge     Permanently delete instead of archiving to .plans/.archive/');
-    process.exit(1);
-  }
-
-  const dryRun = args.includes('--dry-run');
-  const purge = args.includes('--purge');
-  const manifestPath = resolve(MANIFEST_PATH);
-
-  if (!existsSync(manifestPath)) {
-    console.log(`No ${MANIFEST_PATH} found — nothing to clean.`);
-    process.exit(0);
-  }
+/**
+ * Clean one registry. `noun` is "plan" / "initiative" for messaging. Returns
+ * the number cleaned and how many remain in progress.
+ */
+function cleanRegistry(manifestRelPath, noun, { dryRun, purge }) {
+  const manifestPath = resolve(manifestRelPath);
+  if (!existsSync(manifestPath)) return { cleaned: 0, inFlight: 0, closed: 0 };
 
-  const entries = readManifest(manifestPath);
+  const entries = readManifest(manifestPath, manifestRelPath);
   const closed = entries.filter((entry) => TERMINAL_STATUSES.has(entry.status));
   const inFlight = entries.filter((entry) => entry.status === 'in-progress');
 
   if (closed.length === 0) {
-    console.log('No closed plans to clean.');
+    console.log(`No closed ${noun}s to clean.`);
     if (inFlight.length > 0) {
-      console.log(`\n${inFlight.length} plan(s) still in progress:`);
-      for (const entry of inFlight) console.log(`  ○ ${entry.name} — ${entry.title}`);
+      console.log(`  ${inFlight.length} ${noun}(s) still in progress.`);
     }
-    process.exit(0);
+    return { cleaned: 0, inFlight: inFlight.length, closed: 0 };
   }
 
   const verb = purge ? 'delete' : 'archive';
   console.log(
-    dryRun ? `Dry run — would ${verb}:\n` : `${purge ? 'Deleting' : 'Archiving'} closed plans:\n`,
+    dryRun
+      ? `Dry run — would ${verb} closed ${noun}s:\n`
+      : `${purge ? 'Deleting' : 'Archiving'} closed ${noun}s:\n`,
   );
 
   if (!dryRun && !purge && !existsSync(resolve(ARCHIVE_DIR))) {
@@ -96,8 +83,8 @@ function main() {
   const remaining = [...inFlight];
   let cleaned = 0;
   for (const entry of closed) {
-    const planPath = resolve(join(PLANS_DIR, entry.name));
-    const exists = existsSync(planPath);
+    const dirPath = resolve(join(PLANS_DIR, entry.name));
+    const exists = existsSync(dirPath);
     const label = `${entry.name} — ${entry.title} [${entry.status}]`;
 
     if (dryRun) {
@@ -107,12 +94,12 @@ function main() {
 
     if (exists) {
       if (purge) {
-        rmSync(planPath, { recursive: true, force: true });
+        rmSync(dirPath, { recursive: true, force: true });
         console.log(`  ✓ Deleted ${PLANS_DIR}/${entry.name} — ${label}`);
       } else {
         const dest = resolve(join(ARCHIVE_DIR, entry.name));
         rmSync(dest, { recursive: true, force: true }); // replace any stale archive
-        renameSync(planPath, dest);
+        renameSync(dirPath, dest);
         console.log(`  ✓ Archived ${PLANS_DIR}/${entry.name} → ${ARCHIVE_DIR}/${entry.name}`);
       }
     } else {
@@ -122,11 +109,11 @@ function main() {
   }
 
   if (dryRun) {
-    console.log(`\n${closed.length} plan(s) would be cleaned.`);
+    console.log(`\n${closed.length} ${noun}(s) would be cleaned.`);
     if (inFlight.length > 0) {
-      console.log(`${inFlight.length} plan(s) still in progress (will be kept).`);
+      console.log(`${inFlight.length} ${noun}(s) still in progress (will be kept).`);
     }
-    return;
+    return { cleaned: 0, inFlight: inFlight.length, closed: closed.length };
   }
 
   if (remaining.length === 0) {
@@ -135,9 +122,40 @@ function main() {
     writeManifest(manifestPath, remaining);
   }
 
-  console.log(`\nCleaned ${cleaned} plan(s).`);
-  if (remaining.length > 0) console.log(`${remaining.length} plan(s) still in progress.`);
-  if (!purge) console.log(`Archived plans kept in ${ARCHIVE_DIR}/ (use --purge to delete).`);
+  console.log(`\nCleaned ${cleaned} ${noun}(s).`);
+  if (remaining.length > 0) console.log(`${remaining.length} ${noun}(s) still in progress.`);
+  return { cleaned, inFlight: remaining.length, closed: closed.length };
+}
+
+function main() {
+  const args = process.argv.slice(2);
+  const command = args[0];
+
+  if (command !== 'clean') {
+    console.error('Usage: pi-plan-mode clean [--dry-run] [--purge]\n');
+    console.error('Commands:');
+    console.error('  clean       Archive closed plan + initiative directories and update registries\n');
+    console.error('Options:');
+    console.error('  --dry-run   Show what would be cleaned without changing anything');
+    console.error('  --purge     Permanently delete instead of archiving to .plans/.archive/');
+    process.exit(1);
+  }
+
+  const dryRun = args.includes('--dry-run');
+  const purge = args.includes('--purge');
+
+  if (!existsSync(resolve(PLANS_MANIFEST)) && !existsSync(resolve(INITIATIVES_MANIFEST))) {
+    console.log(`No ${PLANS_MANIFEST} or ${INITIATIVES_MANIFEST} found — nothing to clean.`);
+    process.exit(0);
+  }
+
+  const plans = cleanRegistry(PLANS_MANIFEST, 'plan', { dryRun, purge });
+  console.log('');
+  const initiatives = cleanRegistry(INITIATIVES_MANIFEST, 'initiative', { dryRun, purge });
+
+  if (!dryRun && !purge && (plans.cleaned > 0 || initiatives.cleaned > 0)) {
+    console.log(`\nArchived items kept in ${ARCHIVE_DIR}/ (use --purge to delete).`);
+  }
 }
 
 main();

package/extensions/plan-mode/__tests__/html-render.test.ts

@@ -1,34 +1,48 @@
 import { describe, expect, test } from 'bun:test';
-import { renderPrototypeHtml } from '../html/render.js';
-
-describe('renderPrototypeHtml', () => {
-  test('renders title and intent in a minimal header', () => {
-    const html = renderPrototypeHtml('Sidebar redesign', 'Left-aligned nav with icons', '.nav Nav');
-
-    expect(html).toContain('Sidebar redesign');
-    expect(html).toContain('Left-aligned nav with icons');
-    expect(html).toContain('Prototype');
+import { buildPrototypeDocument } from '../html/render.js';
+
+describe('buildPrototypeDocument', () => {
+  test('returns a full HTML document untouched, with no imposed wrapper', () => {
+    const doc = `<!doctype html>
+<html lang="en">
+  <head><meta charset="utf-8"><title>My own design</title></head>
+  <body style="background: salmon"><h1>Hand-crafted</h1></body>
+</html>`;
+
+    const html = buildPrototypeDocument('Sidebar redesign', doc);
+
+    // Author's document is preserved verbatim — no badge, no theme, no panel.
+    expect(html).toBe(doc.trim());
+    expect(html).not.toContain('Prototype ·');
+    expect(html).not.toContain('class="prototype"');
+    expect(html).not.toContain('Inter');
   });
 
-  test('renders the Pug body markup', () => {
-    const html = renderPrototypeHtml('Card', 'A product card', '.card Product card');
-
-    expect(html).toContain('class="card"');
-    expect(html).toContain('Product card');
+  test('recognizes a full document via <html> even without a doctype', () => {
+    const doc = '<html><body><main>Hello</main></body></html>';
+    const html = buildPrototypeDocument('Card', doc);
+    expect(html).toBe(doc);
   });
 
-  test('does not render tasks or handoff sections', () => {
-    const html = renderPrototypeHtml('Card', 'A product card', '.card Hello');
+  test('wraps a bare fragment in a minimal, unstyled shell', () => {
+    const html = buildPrototypeDocument('Card', '<div class="card">Product card</div>');
 
-    expect(html).not.toContain('Handoff');
-    expect(html).not.toContain('Tasks');
-    expect(html).not.toContain('Depends on');
+    expect(html).toMatch(/^<!doctype html>/i);
+    expect(html).toContain('<title>Card</title>');
+    expect(html).toContain('<div class="card">Product card</div>');
+    // The shell imposes no theme of its own.
+    expect(html).not.toContain('background');
+    expect(html).not.toContain('Inter');
   });
 
-  test('handles an empty prototype body without throwing', () => {
-    const html = renderPrototypeHtml('Empty', 'Nothing yet', '');
+  test('escapes the title when used in the fallback shell', () => {
+    const html = buildPrototypeDocument('A & B <script>', '<p>hi</p>');
+    expect(html).toContain('<title>A &amp; B &lt;script&gt;</title>');
+  });
 
-    expect(html).toContain('Empty');
-    expect(html).toContain('Nothing yet');
+  test('handles an empty body without throwing', () => {
+    const html = buildPrototypeDocument('Empty', '');
+    expect(html).toMatch(/^<!doctype html>/i);
+    expect(html).toContain('<title>Empty</title>');
   });
 });

package/extensions/plan-mode/__tests__/initiative-readiness.test.ts

@@ -0,0 +1,159 @@
+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 {
+  computePlanReadiness,
+  initiativeRollup,
+  isInitiativeFinalizable,
+  reconcileInitiativeForPlan,
+  reconcileInitiativeStatus,
+} from '../initiative.js';
+import { upsertPlanEntry, type PlanManifestEntry } from '../storage/plans-manifest.js';
+import {
+  readInitiativesManifest,
+  upsertInitiativeEntry,
+} from '../storage/initiatives-manifest.js';
+
+const run = <A, E>(program: Effect.Effect<A, E, FileSystem>): Promise<A> =>
+  Effect.runPromise(program.pipe(Effect.provideService(FileSystem, nodeFileSystemService)));
+
+function plan(partial: Partial<PlanManifestEntry> & { name: string }): PlanManifestEntry {
+  return {
+    _type: 'plan',
+    status: 'in-progress',
+    title: partial.name,
+    created_at: 'now',
+    completed_at: null,
+    ...partial,
+  };
+}
+
+describe('computePlanReadiness (pure)', () => {
+  test('a plan with no deps is ready', () => {
+    const rows = computePlanReadiness([plan({ name: 'a' })]);
+    expect(rows).toEqual([{ name: 'a', ready: true, blockedBy: [] }]);
+  });
+
+  test('a plan whose dep is done is ready; otherwise blocked', () => {
+    const plans = [
+      plan({ name: 'schema', status: 'done' }),
+      plan({ name: 'api', depends_on: ['schema'] }),
+      plan({ name: 'ui', depends_on: ['api'] }),
+    ];
+    const byName = new Map(computePlanReadiness(plans).map((r) => [r.name, r]));
+    expect(byName.get('api')?.ready).toBe(true);
+    expect(byName.get('ui')?.ready).toBe(false);
+    expect(byName.get('ui')?.blockedBy).toEqual(['api']);
+  });
+
+  test('only in-progress plans are reported (done dep itself is not a row)', () => {
+    const rows = computePlanReadiness([
+      plan({ name: 'schema', status: 'done' }),
+      plan({ name: 'api', depends_on: ['schema'] }),
+    ]);
+    expect(rows.map((r) => r.name)).toEqual(['api']);
+  });
+
+  test('an unknown or terminally-closed dep keeps a plan blocked', () => {
+    const rows = computePlanReadiness([
+      plan({ name: 'ghost-dep', status: 'abandoned' }),
+      plan({ name: 'x', depends_on: ['ghost-dep', 'missing'] }),
+    ]);
+    const x = rows.find((r) => r.name === 'x');
+    expect(x?.ready).toBe(false);
+    expect(x?.blockedBy.sort()).toEqual(['ghost-dep', 'missing']);
+  });
+});
+
+describe('isInitiativeFinalizable / initiativeRollup (pure)', () => {
+  const plans = [
+    plan({ name: 'a', initiative: 'big', status: 'done' }),
+    plan({ name: 'b', initiative: 'big', status: 'in-progress', depends_on: ['a'] }),
+    plan({ name: 'c', initiative: 'big', status: 'in-progress', depends_on: ['b'] }),
+    plan({ name: 'solo' }), // not a member
+  ];
+
+  test('not finalizable while a member is in-progress', () => {
+    expect(isInitiativeFinalizable('big', plans)).toBe(false);
+  });
+
+  test('finalizable when all members are terminal', () => {
+    const allClosed = [
+      plan({ name: 'a', initiative: 'big', status: 'done' }),
+      plan({ name: 'b', initiative: 'big', status: 'superseded' }),
+    ];
+    expect(isInitiativeFinalizable('big', allClosed)).toBe(true);
+  });
+
+  test('an empty initiative is never finalizable', () => {
+    expect(isInitiativeFinalizable('nope', plans)).toBe(false);
+  });
+
+  test('rollup counts members, progress, and readiness', () => {
+    const r = initiativeRollup('big', plans);
+    expect(r.total).toBe(3);
+    expect(r.done).toBe(1);
+    expect(r.inProgress).toBe(2);
+    expect(r.ready).toBe(1); // b (dep a is done)
+    expect(r.blocked).toBe(1); // c (dep b is in-progress)
+    const b = r.members.find((m) => m.name === 'b');
+    expect(b?.ready).toBe(true);
+    const c = r.members.find((m) => m.name === 'c');
+    expect(c?.blockedBy).toEqual(['b']);
+  });
+});
+
+describe('reconcileInitiativeStatus / reconcileInitiativeForPlan (IO projection)', () => {
+  const originalCwd = process.cwd();
+  let dir: string;
+
+  beforeEach(async () => {
+    dir = await mkdtemp(join(tmpdir(), 'plan-mode-init-proj-'));
+    chdir(dir);
+  });
+  afterEach(async () => {
+    chdir(originalCwd);
+    await rm(dir, { recursive: true, force: true });
+  });
+
+  test('flips an initiative to done when its last in-progress member completes', async () => {
+    await run(upsertInitiativeEntry('big', { status: 'in-progress', title: 'Big' }));
+    await run(upsertPlanEntry('a', { status: 'done', title: 'A', initiative: 'big' }));
+    await run(upsertPlanEntry('b', { status: 'in-progress', title: 'B', initiative: 'big' }));
+
+    await run(reconcileInitiativeStatus('big'));
+    let [entry] = await run(readInitiativesManifest());
+    expect(entry.status).toBe('in-progress'); // b still open
+
+    await run(upsertPlanEntry('b', { status: 'done', title: 'B', initiative: 'big' }));
+    await run(reconcileInitiativeForPlan('b'));
+    [entry] = await run(readInitiativesManifest());
+    expect(entry.status).toBe('done');
+  });
+
+  test('reopens a done initiative when a member goes back in-progress', async () => {
+    await run(upsertInitiativeEntry('big', { status: 'done', title: 'Big' }));
+    await run(upsertPlanEntry('a', { status: 'in-progress', title: 'A', initiative: 'big' }));
+    await run(reconcileInitiativeStatus('big'));
+    const [entry] = await run(readInitiativesManifest());
+    expect(entry.status).toBe('in-progress');
+  });
+
+  test('never overrides a manually-closed (superseded) initiative', async () => {
+    await run(upsertInitiativeEntry('big', { status: 'superseded', title: 'Big', reason: 'x' }));
+    await run(upsertPlanEntry('a', { status: 'done', title: 'A', initiative: 'big' }));
+    await run(reconcileInitiativeStatus('big'));
+    const [entry] = await run(readInitiativesManifest());
+    expect(entry.status).toBe('superseded');
+  });
+
+  test('reconcileInitiativeForPlan is a no-op for a standalone plan', async () => {
+    await run(upsertPlanEntry('solo', { status: 'done', title: 'Solo' }));
+    await run(reconcileInitiativeForPlan('solo'));
+    await expect(run(readInitiativesManifest())).resolves.toEqual([]);
+  });
+});

package/extensions/plan-mode/__tests__/initiative-status.test.ts

@@ -0,0 +1,98 @@
+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 { makePlanRuntime } from '../effects/runtime.js';
+import { upsertPlanEntry } from '../storage/plans-manifest.js';
+import { upsertInitiativeEntry } from '../storage/initiatives-manifest.js';
+import { writeTasksJsonl } from '../storage/task-storage.js';
+import type { TaskRecord } from '../types.js';
+import { registerInitiativeStatusTool } from '../tools/initiative-status.js';
+
+const runPlanIO = makePlanRuntime();
+const run = <A, E>(program: Effect.Effect<A, E, FileSystem>): Promise<A> =>
+  Effect.runPromise(program.pipe(Effect.provideService(FileSystem, nodeFileSystemService)));
+
+interface CapturedTool {
+  execute: (
+    id: string,
+    params: { initiative?: string },
+  ) => Promise<{ content?: Array<{ text: string }>; details?: unknown }>;
+}
+
+function setup(): CapturedTool {
+  let tool: CapturedTool | undefined;
+  const pi = {
+    registerTool: (config: CapturedTool) => {
+      tool = config;
+    },
+  } as unknown as Parameters<typeof registerInitiativeStatusTool>[0];
+  registerInitiativeStatusTool(pi, runPlanIO);
+  return tool!;
+}
+
+function task(id: string, status: TaskRecord['status']): TaskRecord {
+  return { _type: 'task', id, description: id, status, created_at: 'n', updated_at: 'n' };
+}
+
+const originalCwd = process.cwd();
+let dir: string;
+beforeEach(async () => {
+  dir = await mkdtemp(join(tmpdir(), 'plan-mode-init-status-'));
+  chdir(dir);
+});
+afterEach(async () => {
+  chdir(originalCwd);
+  await rm(dir, { recursive: true, force: true });
+});
+
+describe('initiative_status tool', () => {
+  async function seed() {
+    await runPlanIO(upsertInitiativeEntry('big', { status: 'in-progress', title: 'Big' }));
+    await runPlanIO(upsertPlanEntry('schema', { status: 'done', title: 'Schema', initiative: 'big' }));
+    await runPlanIO(
+      upsertPlanEntry('api', { status: 'in-progress', title: 'API', initiative: 'big', depends_on: ['schema'] }),
+    );
+    await runPlanIO(
+      upsertPlanEntry('ui', { status: 'in-progress', title: 'UI', initiative: 'big', depends_on: ['api'] }),
+    );
+    await run(
+      writeTasksJsonl(
+        '.plans/api',
+        { _type: 'meta', title: 'API', plan_name: 'api', created_at: 'n' },
+        [task('t-001', 'done'), task('t-002', 'pending')],
+      ),
+    );
+  }
+
+  test('renders member plans with progress + ready/blocked', async () => {
+    await seed();
+    const result = await setup().execute('c', { initiative: 'big' });
+    const text = result.content?.[0]?.text ?? '';
+    expect(text).toMatch(/Initiative: Big \(big\) — in-progress/);
+    expect(text).toMatch(/api \[in-progress\] 1\/2 tasks  \[ready\]/);
+    expect(text).toMatch(/ui \[in-progress\].*\[blocked by api\]/);
+    const details = result.details as { ready_plans?: string[] };
+    expect(details.ready_plans).toContain('api');
+  });
+
+  test('auto-selects the sole in-progress initiative when none is passed', async () => {
+    await seed();
+    const result = await setup().execute('c', {});
+    expect((result.details as { active?: boolean }).active).toBe(true);
+  });
+
+  test('reports not_found for an unknown initiative', async () => {
+    await seed();
+    const result = await setup().execute('c', { initiative: 'ghost' });
+    expect((result.details as { error?: string }).error).toBe('not_found');
+  });
+
+  test('no in-progress initiative → inactive snapshot', async () => {
+    const result = await setup().execute('c', {});
+    expect((result.details as { active?: boolean }).active).toBe(false);
+  });
+});