@opengsd/get-shit-done-redux 1.0.0

package/sdk/src/query/pipeline.test.ts

@@ -0,0 +1,169 @@
+/**
+ * Unit tests for pipeline middleware.
+ *
+ * Tests wrapWithPipeline with dry-run mode, prepare/finalize callbacks,
+ * and normal execution passthrough.
+ */
+
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
+import { mkdtemp, writeFile, mkdir, rm } from 'node:fs/promises';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+import { QueryRegistry } from './registry.js';
+import { wrapWithPipeline } from './pipeline.js';
+import type { QueryResult } from './utils.js';
+
+let tmpDir: string;
+
+beforeEach(async () => {
+  tmpDir = await mkdtemp(join(tmpdir(), 'gsd-pipeline-'));
+  await mkdir(join(tmpDir, '.planning'), { recursive: true });
+  await writeFile(join(tmpDir, '.planning', 'STATE.md'), '# State\nstatus: idle\n');
+});
+
+afterEach(async () => {
+  await rm(tmpDir, { recursive: true, force: true });
+});
+
+// ─── Helper ───────────────────────────────────────────────────────────────
+
+function makeRegistry(): QueryRegistry {
+  const registry = new QueryRegistry();
+  registry.register('read-cmd', async (_args, _dir) => ({ data: { read: true } }));
+  registry.register('mut-cmd', async (_args, dir) => {
+    // Simulate a mutation: write a file to the project dir
+    const { writeFile: wf } = await import('node:fs/promises');
+    await wf(join(dir, '.planning', 'MUTATED.md'), '# mutated');
+    return { data: { mutated: true } };
+  });
+  return registry;
+}
+
+const MUTATION_SET = new Set(['mut-cmd']);
+
+// ─── Tests ─────────────────────────────────────────────────────────────────
+
+describe('wrapWithPipeline — passthrough (no options)', () => {
+  it('read command passes through normally', async () => {
+    const registry = makeRegistry();
+    wrapWithPipeline(registry, MUTATION_SET, {});
+    const result = await registry.dispatch('read-cmd', [], tmpDir);
+    expect((result.data as Record<string, unknown>).read).toBe(true);
+  });
+
+  it('mutation command executes and writes to disk when dryRun=false', async () => {
+    const registry = makeRegistry();
+    wrapWithPipeline(registry, MUTATION_SET, { dryRun: false });
+    const result = await registry.dispatch('mut-cmd', [], tmpDir);
+    expect((result.data as Record<string, unknown>).mutated).toBe(true);
+    // File should have been written to the real dir
+    const { existsSync } = await import('node:fs');
+    expect(existsSync(join(tmpDir, '.planning', 'MUTATED.md'))).toBe(true);
+  });
+});
+
+describe('wrapWithPipeline — dry-run mode', () => {
+  it('dry-run mutation returns diff without writing to disk', async () => {
+    const registry = makeRegistry();
+    wrapWithPipeline(registry, MUTATION_SET, { dryRun: true });
+    const result = await registry.dispatch('mut-cmd', [], tmpDir);
+    const data = result.data as Record<string, unknown>;
+
+    // Should be a dry-run result
+    expect(data.dry_run).toBe(true);
+    expect(data.command).toBe('mut-cmd');
+    expect(data.diff).toBeDefined();
+    expect(typeof data.changes_summary).toBe('string');
+
+    // Real project should NOT have been written to
+    const { existsSync } = await import('node:fs');
+    expect(existsSync(join(tmpDir, '.planning', 'MUTATED.md'))).toBe(false);
+  });
+
+  it('dry-run diff contains before/after for changed files', async () => {
+    const registry = makeRegistry();
+    wrapWithPipeline(registry, MUTATION_SET, { dryRun: true });
+    const result = await registry.dispatch('mut-cmd', [], tmpDir);
+    const data = result.data as Record<string, unknown>;
+    const diff = data.diff as Record<string, { before: string | null; after: string | null }>;
+
+    // MUTATED.md is a new file — before should be null
+    const mutatedKey = Object.keys(diff).find(k => k.includes('MUTATED'));
+    expect(mutatedKey).toBeDefined();
+    expect(diff[mutatedKey!].before).toBeNull();
+    expect(diff[mutatedKey!].after).toBe('# mutated');
+  });
+
+  it('dry-run read command executes normally (side-effect-free)', async () => {
+    const registry = makeRegistry();
+    wrapWithPipeline(registry, MUTATION_SET, { dryRun: true });
+    // read-cmd is NOT in MUTATION_SET, so it's not wrapped at all
+    const result = await registry.dispatch('read-cmd', [], tmpDir);
+    expect((result.data as Record<string, unknown>).read).toBe(true);
+  });
+
+  it('dry-run changes_summary reflects number of changed files', async () => {
+    const registry = makeRegistry();
+    wrapWithPipeline(registry, MUTATION_SET, { dryRun: true });
+    const result = await registry.dispatch('mut-cmd', [], tmpDir);
+    const data = result.data as Record<string, unknown>;
+    expect(data.changes_summary).toContain('1 file');
+  });
+});
+
+describe('wrapWithPipeline — prepare/finalize callbacks', () => {
+  it('onPrepare fires before mutation execution', async () => {
+    const registry = makeRegistry();
+    const preparedCommands: string[] = [];
+    wrapWithPipeline(registry, MUTATION_SET, {
+      onPrepare: async (cmd) => { preparedCommands.push(cmd); },
+    });
+    await registry.dispatch('mut-cmd', ['arg1'], tmpDir);
+    expect(preparedCommands).toContain('mut-cmd');
+  });
+
+  it('onFinalize fires after mutation with result', async () => {
+    const registry = makeRegistry();
+    let capturedResult: QueryResult | null = null;
+    wrapWithPipeline(registry, MUTATION_SET, {
+      onFinalize: async (_cmd, _args, result) => { capturedResult = result; },
+    });
+    await registry.dispatch('mut-cmd', [], tmpDir);
+    expect(capturedResult).not.toBeNull();
+  });
+
+  it('onPrepare receives correct args', async () => {
+    const registry = makeRegistry();
+    let capturedArgs: string[] = [];
+    wrapWithPipeline(registry, MUTATION_SET, {
+      onPrepare: async (_cmd, args) => { capturedArgs = args; },
+    });
+    await registry.dispatch('mut-cmd', ['foo', 'bar'], tmpDir);
+    expect(capturedArgs).toEqual(['foo', 'bar']);
+  });
+
+  it('onFinalize fires even in dry-run mode', async () => {
+    const registry = makeRegistry();
+    let finalizeCalled = false;
+    wrapWithPipeline(registry, MUTATION_SET, {
+      dryRun: true,
+      onFinalize: async () => { finalizeCalled = true; },
+    });
+    await registry.dispatch('mut-cmd', [], tmpDir);
+    expect(finalizeCalled).toBe(true);
+  });
+});
+
+describe('wrapWithPipeline — unregistered command passthrough', () => {
+  it('commands not in mutation set are not wrapped', async () => {
+    const registry = makeRegistry();
+    const spy = vi.fn(async (_args: string[], _dir: string): Promise<QueryResult> => ({ data: { value: 42 } }));
+    registry.register('other-cmd', spy);
+    wrapWithPipeline(registry, MUTATION_SET, {
+      onPrepare: async () => { /* should not fire for non-mutation */ },
+    });
+    const result = await registry.dispatch('other-cmd', [], tmpDir);
+    // Since other-cmd is not in MUTATION_SET, it's not wrapped
+    expect((result.data as Record<string, unknown>).value).toBe(42);
+  });
+});

package/sdk/src/query/pipeline.ts

@@ -0,0 +1,243 @@
+/**
+ * Staged execution pipeline — registry-level middleware for pre/post hooks
+ * and full in-memory dry-run support.
+ *
+ * Wraps all registry handlers with prepare/execute/finalize stages.
+ * When dryRun=true and the command is a mutation, the mutation executes
+ * against a temporary directory clone of .planning/ instead of the real
+ * project, and the before/after diff is returned without writing to disk.
+ *
+ * Read commands are always executed normally — they are side-effect-free.
+ *
+ * @example
+ * ```typescript
+ * import { createRegistry } from './index.js';
+ * import { wrapWithPipeline } from './pipeline.js';
+ *
+ * const registry = createRegistry();
+ * wrapWithPipeline(registry, MUTATION_COMMANDS, { dryRun: true });
+ * // mutations now return { data: { dry_run: true, diff: { ... } } }
+ * ```
+ */
+
+import { mkdtemp, mkdir, writeFile, readFile, rm } from 'node:fs/promises';
+import { existsSync, readdirSync } from 'node:fs';
+import { join, relative, dirname } from 'node:path';
+import { tmpdir } from 'node:os';
+import type { QueryResult } from './utils.js';
+import type { QueryRegistry } from './registry.js';
+
+// ─── Types ─────────────────────────────────────────────────────────────────
+
+/**
+ * Configuration for the pipeline middleware.
+ */
+export interface PipelineOptions {
+  /** When true, mutations execute against a temp clone and return a diff */
+  dryRun?: boolean;
+  /** Called before each handler invocation */
+  onPrepare?: (command: string, args: string[], projectDir: string) => Promise<void>;
+  /** Called after each handler invocation */
+  onFinalize?: (command: string, args: string[], result: QueryResult) => Promise<void>;
+}
+
+/**
+ * A single stage in the execution pipeline.
+ */
+export type PipelineStage = 'prepare' | 'execute' | 'finalize';
+
+// ─── Internal helpers ──────────────────────────────────────────────────────
+
+/**
+ * Recursively collect all files under a directory.
+ * Returns paths relative to the base directory.
+ */
+function collectFiles(dir: string, base: string): string[] {
+  const results: string[] = [];
+  if (!existsSync(dir)) return results;
+  const entries = readdirSync(dir, { withFileTypes: true });
+  for (const entry of entries) {
+    const fullPath = join(dir, entry.name);
+    const relPath = relative(base, fullPath);
+    if (entry.isFile()) {
+      results.push(relPath);
+    } else if (entry.isDirectory()) {
+      results.push(...collectFiles(fullPath, base));
+    }
+  }
+  return results;
+}
+
+/**
+ * Copy .planning/ subtree from sourceDir to destDir.
+ * Only copies text files relevant to GSD state (skips binaries and logs).
+ */
+async function copyPlanningTree(sourceDir: string, destDir: string): Promise<void> {
+  const planningSource = join(sourceDir, '.planning');
+  if (!existsSync(planningSource)) return;
+
+  const files = collectFiles(planningSource, planningSource);
+  for (const relFile of files) {
+    // Skip large or binary-ish files (> 1MB) — only relevant for text state
+    const sourcePath = join(planningSource, relFile);
+    const destPath = join(destDir, '.planning', relFile);
+    await mkdir(dirname(destPath), { recursive: true });
+    try {
+      const content = await readFile(sourcePath, 'utf-8');
+      await writeFile(destPath, content, 'utf-8');
+    } catch {
+      // Skip unreadable files (binary, permission issues, etc.)
+    }
+  }
+}
+
+/**
+ * Read all files from .planning/ in a directory into a map of relPath → content.
+ */
+async function readPlanningState(projectDir: string): Promise<Map<string, string>> {
+  const planningDir = join(projectDir, '.planning');
+  const result = new Map<string, string>();
+  if (!existsSync(planningDir)) return result;
+
+  const files = collectFiles(planningDir, planningDir);
+  for (const relFile of files) {
+    try {
+      const content = await readFile(join(planningDir, relFile), 'utf-8');
+      result.set(relFile, content);
+    } catch { /* skip unreadable */ }
+  }
+  return result;
+}
+
+/**
+ * Diff two file maps, returning files that changed (with before/after content).
+ */
+function diffPlanningState(
+  before: Map<string, string>,
+  after: Map<string, string>,
+): Record<string, { before: string | null; after: string | null }> {
+  const diff: Record<string, { before: string | null; after: string | null }> = {};
+  const allKeys = new Set([...before.keys(), ...after.keys()]);
+  for (const key of allKeys) {
+    const b = before.get(key) ?? null;
+    const a = after.get(key) ?? null;
+    if (b !== a) {
+      diff[`.planning/${key}`] = { before: b, after: a };
+    }
+  }
+  return diff;
+}
+
+// ─── wrapWithPipeline ──────────────────────────────────────────────────────
+
+/**
+ * Wrap all registered handlers with prepare/execute/finalize pipeline stages.
+ *
+ * When dryRun=true and a mutation command is dispatched, the real projectDir
+ * is cloned (only .planning/ subtree) into a temp directory. The mutation
+ * runs against the clone, a before/after diff is computed, and the temp
+ * directory is cleaned up in a finally block. The real project is never
+ * touched during a dry run.
+ *
+ * @param registry - The registry whose handlers to wrap
+ * @param mutationCommands - Set of command names that perform mutations
+ * @param options - Pipeline configuration
+ */
+export function wrapWithPipeline(
+  registry: QueryRegistry,
+  mutationCommands: Set<string>,
+  options: PipelineOptions,
+): void {
+  const { dryRun = false, onPrepare, onFinalize } = options;
+
+  // Collect all currently registered commands by iterating known handlers
+  // We wrap by re-registering with the same name using the same technique
+  // as event emission wiring in index.ts
+  const commandsToWrap: string[] = [];
+
+  // Enumerate mutation commands via the caller-provided set. QueryRegistry also
+  // exposes commands() for full command lists when needed by tooling.
+  // We wrap the register method temporarily to collect known commands,
+  // then restore. Instead, we use the mutation commands set + a marker approach:
+  // wrap mutation commands for dry-run, and wrap all via onPrepare/onFinalize.
+  //
+  // For pipeline wrapping we use a two-pass approach:
+  // Pass 1: wrap mutation commands (for dry-run + hooks)
+  // Pass 2: wrap non-mutation commands (for hooks only, if hooks provided)
+
+  const wrapHandler = (cmd: string, isMutation: boolean): void => {
+    const original = registry.getHandler(cmd);
+    if (!original) return;
+
+    registry.register(cmd, async (args: string[], projectDir: string) => {
+      // ─── Prepare stage ───────────────────────────────────────────────
+      if (onPrepare) {
+        await onPrepare(cmd, args, projectDir);
+      }
+
+      let result: QueryResult;
+
+      if (dryRun && isMutation) {
+        // ─── Dry-run: clone → mutate → diff ──────────────────────────
+        let tempDir: string | null = null;
+        try {
+          tempDir = await mkdtemp(join(tmpdir(), 'gsd-dryrun-'));
+
+          // Snapshot state before mutation
+          const beforeState = await readPlanningState(projectDir);
+
+          // Copy .planning/ to temp dir
+          await copyPlanningTree(projectDir, tempDir);
+
+          // Execute mutation against temp dir clone
+          await original(args, tempDir);
+
+          // Snapshot state after mutation (from temp dir)
+          const afterState = await readPlanningState(tempDir);
+
+          // Compute diff
+          const diff = diffPlanningState(beforeState, afterState);
+          const changedFiles = Object.keys(diff);
+
+          result = {
+            data: {
+              dry_run: true,
+              command: cmd,
+              args,
+              diff,
+              changes_summary: changedFiles.length > 0
+                ? `${changedFiles.length} file(s) would be modified: ${changedFiles.join(', ')}`
+                : 'No files would be modified',
+            },
+          };
+        } finally {
+          // T-14-06: Always clean up temp dir, even on error
+          if (tempDir) {
+            await rm(tempDir, { recursive: true, force: true }).catch(() => undefined);
+          }
+        }
+      } else {
+        // ─── Normal execution ─────────────────────────────────────────
+        result = await original(args, projectDir);
+      }
+
+      // ─── Finalize stage ───────────────────────────────────────────────
+      if (onFinalize) {
+        await onFinalize(cmd, args, result);
+      }
+
+      return result;
+    });
+
+    commandsToWrap.push(cmd);
+  };
+
+  // Wrap mutation commands (dry-run eligible + hooks)
+  for (const cmd of mutationCommands) {
+    wrapHandler(cmd, true);
+  }
+
+  // Note: non-mutation commands are NOT wrapped here for performance — callers
+  // can provide onPrepare/onFinalize for mutations only. If full wrapping of
+  // read commands is needed, callers should pass their command set explicitly.
+}

package/sdk/src/query/plan-scan.test.ts

@@ -0,0 +1,35 @@
+import { describe, expect, it } from 'vitest';
+import { mkdtemp, mkdir, rm, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+
+import { scanPhasePlans } from './plan-scan.js';
+
+describe('scanPhasePlans', () => {
+  it('counts flat and nested plan files while excluding derivative files', async () => {
+    const tmpDir = await mkdtemp(join(tmpdir(), 'gsd-plan-scan-'));
+    try {
+      const phaseDir = join(tmpDir, 'phases', '1');
+      const nestedDir = join(phaseDir, 'plans');
+      await mkdir(nestedDir, { recursive: true });
+      await writeFile(join(phaseDir, '01-01-PLAN.md'), '# Plan');
+      await writeFile(join(phaseDir, '01-01-SUMMARY.md'), '# Summary');
+      await writeFile(join(phaseDir, '01-01-PLAN-OUTLINE.md'), '# Outline');
+      await writeFile(join(nestedDir, 'PLAN-02-next.md'), '# Plan');
+      await writeFile(join(nestedDir, 'SUMMARY-02-next.md'), '# Summary');
+      await writeFile(join(nestedDir, 'PLAN-03-draft.pre-bounce.md'), '# Draft');
+      await writeFile(join(nestedDir, 'PLAN-04-OUTLINE.md'), '# Outline');
+
+      expect(scanPhasePlans(phaseDir)).toMatchObject({
+        planCount: 2,
+        summaryCount: 2,
+        completed: true,
+        hasNestedPlans: true,
+        planFiles: ['01-01-PLAN.md', 'PLAN-02-next.md'],
+        summaryFiles: ['01-01-SUMMARY.md', 'SUMMARY-02-next.md'],
+      });
+    } finally {
+      await rm(tmpDir, { recursive: true, force: true });
+    }
+  });
+});

package/sdk/src/query/plan-scan.ts

@@ -0,0 +1,82 @@
+import { existsSync, readdirSync } from 'node:fs';
+import { join } from 'node:path';
+
+const PLAN_OUTLINE_RE = /-OUTLINE\.md$/i;
+const PLAN_PRE_BOUNCE_RE = /\.pre-bounce\.md$/i;
+
+export interface PhasePlanScan {
+  planCount: number;
+  summaryCount: number;
+  completed: boolean;
+  hasNestedPlans: boolean;
+  planFiles: string[];
+  summaryFiles: string[];
+}
+
+export function isRootPlanFile(fileName: string): boolean {
+  if (PLAN_OUTLINE_RE.test(fileName)) return false;
+  if (PLAN_PRE_BOUNCE_RE.test(fileName)) return false;
+  if (fileName.endsWith('-PLAN.md') || fileName === 'PLAN.md') return true;
+  return /\.md$/i.test(fileName) && /PLAN/i.test(fileName);
+}
+
+export function isNestedPlanFile(fileName: string): boolean {
+  if (PLAN_OUTLINE_RE.test(fileName)) return false;
+  if (PLAN_PRE_BOUNCE_RE.test(fileName)) return false;
+  return /^PLAN-\d+.*\.md$/i.test(fileName) || /-PLAN-\d+.*\.md$/i.test(fileName);
+}
+
+export function isRootSummaryFile(fileName: string): boolean {
+  return fileName.endsWith('-SUMMARY.md') || fileName === 'SUMMARY.md';
+}
+
+export function isNestedSummaryFile(fileName: string): boolean {
+  return /^SUMMARY-\d+.*\.md$/i.test(fileName) || /-SUMMARY-\d+.*\.md$/i.test(fileName);
+}
+
+export function scanPhasePlans(phaseDir: string): PhasePlanScan {
+  let rootFiles: string[];
+  try {
+    rootFiles = readdirSync(phaseDir);
+  } catch {
+    return {
+      planCount: 0,
+      summaryCount: 0,
+      completed: false,
+      hasNestedPlans: false,
+      planFiles: [],
+      summaryFiles: [],
+    };
+  }
+
+  const rootPlanFiles = rootFiles.filter(isRootPlanFile);
+  const rootSummaryFiles = rootFiles.filter(isRootSummaryFile);
+
+  let nestedPlanFiles: string[] = [];
+  let nestedSummaryFiles: string[] = [];
+  let hasNestedPlans = false;
+
+  const nestedDir = join(phaseDir, 'plans');
+  if (existsSync(nestedDir)) {
+    try {
+      const nestedFiles = readdirSync(nestedDir);
+      nestedPlanFiles = nestedFiles.filter(isNestedPlanFile);
+      nestedSummaryFiles = nestedFiles.filter(isNestedSummaryFile);
+      hasNestedPlans = nestedPlanFiles.length > 0;
+    } catch { /* ignore unreadable nested layout */ }
+  }
+
+  const planFiles = rootPlanFiles.concat(nestedPlanFiles);
+  const summaryFiles = rootSummaryFiles.concat(nestedSummaryFiles);
+  const planCount = planFiles.length;
+  const summaryCount = summaryFiles.length;
+
+  return {
+    planCount,
+    summaryCount,
+    completed: planCount > 0 && summaryCount >= planCount,
+    hasNestedPlans,
+    planFiles,
+    summaryFiles,
+  };
+}

package/sdk/src/query/plan-task-structure.test.ts

@@ -0,0 +1,65 @@
+/**
+ * Unit tests for plan.task-structure.
+ */
+
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { mkdtemp, writeFile, mkdir, rm } from 'node:fs/promises';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+import { planTaskStructure } from './plan-task-structure.js';
+
+const PLAN = `---
+phase: 09-foundation
+plan: "01"
+wave: 2
+depends_on: []
+autonomous: false
+---
+
+<objective>
+Test objective
+</objective>
+
+<tasks>
+<task type="auto">
+  <name>First</name>
+</task>
+<task type="checkpoint">
+  <name>Gate</name>
+</task>
+</tasks>
+`;
+
+let tmpDir: string;
+let planPath: string;
+
+beforeEach(async () => {
+  tmpDir = await mkdtemp(join(tmpdir(), 'gsd-pts-'));
+  const rel = join('.planning', 'phases', '09-x', '09-01-PLAN.md');
+  planPath = join(tmpDir, rel);
+  await mkdir(join(tmpDir, '.planning', 'phases', '09-x'), { recursive: true });
+  await writeFile(planPath, PLAN);
+});
+
+afterEach(async () => {
+  await rm(tmpDir, { recursive: true, force: true });
+});
+
+describe('planTaskStructure', () => {
+  it('returns wave, tasks, and checkpoints', async () => {
+    const rel = join('.planning', 'phases', '09-x', '09-01-PLAN.md');
+    const r = await planTaskStructure([rel], tmpDir);
+    const d = r.data as {
+      wave: number;
+      autonomous: boolean;
+      task_count: number;
+      checkpoint_count: number;
+      tasks: Array<{ is_checkpoint: boolean }>;
+    };
+    expect(d.wave).toBe(2);
+    expect(d.autonomous).toBe(false);
+    expect(d.task_count).toBe(2);
+    expect(d.checkpoint_count).toBe(1);
+    expect(d.tasks.filter((t) => t.is_checkpoint).length).toBe(1);
+  });
+});

package/sdk/src/query/plan-task-structure.ts

@@ -0,0 +1,63 @@
+/**
+ * plan.task-structure — structured task / checkpoint / wave metadata from a PLAN.md file.
+ */
+
+import { readFile } from 'node:fs/promises';
+import { GSDError, ErrorClassification } from '../errors.js';
+import { parsePlan } from '../plan-parser.js';
+import { resolvePathUnderProject } from './helpers.js';
+import type { QueryHandler } from './utils.js';
+
+/**
+ * Args: `<path-to-PLAN.md>` (repo-relative or absolute under projectDir)
+ */
+export const planTaskStructure: QueryHandler = async (args, projectDir) => {
+  const rel = args[0];
+  if (!rel) {
+    throw new GSDError('PLAN.md path required', ErrorClassification.Validation);
+  }
+
+  let path: string;
+  try {
+    path = await resolvePathUnderProject(projectDir, rel);
+  } catch (err) {
+    if (err instanceof GSDError) {
+      throw new GSDError(`cannot read plan file: ${err.message}`, ErrorClassification.Blocked);
+    }
+    throw err;
+  }
+
+  let content: string;
+  try {
+    content = await readFile(path, 'utf-8');
+  } catch {
+    throw new GSDError(`cannot read plan file: ${rel}`, ErrorClassification.Blocked);
+  }
+
+  const parsed = parsePlan(content);
+  const fm = parsed.frontmatter;
+  const checkpoints = parsed.tasks.filter((t) => t.type === 'checkpoint');
+
+  return {
+    data: {
+      path: rel,
+      plan: fm.plan || null,
+      phase: fm.phase || null,
+      wave: fm.wave ?? 1,
+      depends_on: fm.depends_on ?? [],
+      autonomous: fm.autonomous !== false,
+      task_count: parsed.tasks.length,
+      checkpoint_count: checkpoints.length,
+      tasks: parsed.tasks.map((t, i) => ({
+        index: i + 1,
+        type: t.type,
+        name: t.name,
+        is_checkpoint: t.type === 'checkpoint',
+      })),
+      checkpoints: checkpoints.map((t, i) => ({
+        index: i + 1,
+        name: t.name,
+      })),
+    },
+  };
+};

package/sdk/src/query/policy-convergence.test.ts

@@ -0,0 +1,28 @@
+import { describe, it, expect } from 'vitest';
+import { QUERY_MUTATION_COMMAND_LIST, TRANSPORT_RAW_COMMANDS, isQueryMutationCommand } from './query-policy-capability.js';
+
+describe('policy convergence', () => {
+  it('contains expected raw transport aliases', () => {
+    expect(TRANSPORT_RAW_COMMANDS).toEqual([
+      'state.load',
+      'commit',
+      'config-set',
+      'verify-summary',
+      'verify.summary',
+      'verify summary',
+    ]);
+  });
+
+  it('contains key mutation commands and aliases', () => {
+    expect(QUERY_MUTATION_COMMAND_LIST).toContain('state.update');
+    expect(QUERY_MUTATION_COMMAND_LIST).toContain('phase complete');
+    expect(QUERY_MUTATION_COMMAND_LIST).toContain('roadmap.update-plan-progress');
+    expect(QUERY_MUTATION_COMMAND_LIST).toContain('workstream.progress');
+    expect(QUERY_MUTATION_COMMAND_LIST).toContain('learnings prune');
+  });
+
+  it('classifies mutation commands via semantic helper', () => {
+    expect(isQueryMutationCommand('state.update')).toBe(true);
+    expect(isQueryMutationCommand('state.json')).toBe(false);
+  });
+});