supipowers 1.5.3 → 2.0.1

package/src/planning/approval-flow.ts

@@ -1,9 +1,13 @@
 import type { Platform } from "../platform/types.js";
 import type { DebugLogger } from "../debug/logger.js";
-import type { ResolvedModel } from "../types.js";
+import type { Plan, ResolvedModel } from "../types.js";
 import type { PlanningSystemPromptOptions } from "./system-prompt.js";
 import { applyModelOverride } from "../config/model-resolver.js";
-import { listPlans, readPlanFile } from "../storage/plans.js";
+import { listPlans, parsePlan, readPlanFile } from "../storage/plans.js";
+import { validatePlanMarkdown } from "./validate.js";
+import { getProjectStatePath } from "../workspace/state-paths.js";
+import * as path from "node:path";
+import { appendReliabilityRecord } from "../storage/reliability-metrics.js";
 
 /**
  * Plan approval flow state.
@@ -79,13 +83,135 @@ export function getPlanningDebugLogger(): DebugLogger | null {
   return planningDebugLogger;
 }
 
+/**
+ * Mirrors OMP 14.5.11+'s `todo_write` payload shape just enough to hand the
+ * agent a ready-to-execute payload after plan approval.
+ *
+ * The canonical schema lives in OMP \u2014 keep this type local; we only construct
+ * the payload to embed in a prompt string. Task identity is the task content
+ * verbatim; later progress updates (`start`/`done`/`note`) refer to that exact
+ * string, not synthetic ids.
+ */
+type TodoWriteOp =
+  | {
+      op: "init";
+      list: Array<{ phase: string; items: string[] }>;
+    }
+  | { op: "note"; task: string; text: string };
+
+/** Cap individual task labels so the embedded payload stays bounded. */
+const TODO_WRITE_TASK_LABEL_MAX_CHARS = 200;
+
+/**
+ * Single phase name supipowers' planner emits today. Imported into the
+ * execution prompt so the prose stays in lock-step with the JSON payload \u2014
+ * change here and `buildExecutionPrompt` follows automatically.
+ */
+const PLAN_PHASE_NAME = "Implementation";
+
+function truncateTaskLabel(label: string): string {
+  if (label.length <= TODO_WRITE_TASK_LABEL_MAX_CHARS) return label;
+  return `${label.slice(0, TODO_WRITE_TASK_LABEL_MAX_CHARS - 1).trimEnd()}\u2026`;
+}
+
+function appendTaskLabelOrdinal(label: string, ordinal: number): string {
+  const suffix = ` (${ordinal})`;
+  if (label.length + suffix.length <= TODO_WRITE_TASK_LABEL_MAX_CHARS) {
+    return `${label}${suffix}`;
+  }
+  const prefixMax = TODO_WRITE_TASK_LABEL_MAX_CHARS - suffix.length - 1;
+  return `${label.slice(0, prefixMax).trimEnd()}\u2026${suffix}`;
+}
+
+function uniqueTaskLabels(names: string[]): string[] {
+  const used = new Set<string>();
+  const nextOrdinalByBase = new Map<string, number>();
+  return names.map((name) => {
+    const base = truncateTaskLabel(name);
+    let label = base;
+    if (used.has(label)) {
+      let ordinal = nextOrdinalByBase.get(base) ?? 2;
+      do {
+        label = appendTaskLabelOrdinal(base, ordinal);
+        ordinal += 1;
+      } while (used.has(label));
+      nextOrdinalByBase.set(base, ordinal);
+    } else {
+      nextOrdinalByBase.set(base, 2);
+    }
+    used.add(label);
+    return label;
+  });
+}
+
+/**
+ * Build the canonical `todo_write` ops payload from a parsed plan.
+ *
+ * Empty plans return `{ ops: [] }` so callers can skip emit cleanly.
+ * Non-empty plans always start with a single `init` op containing one phase
+ * (`Implementation`) whose `items` is one task content string per `plan.tasks`
+ * entry. Task names are truncated and de-duplicated before they become todo
+ * identities. Tasks that carry acceptance criteria get a follow-up `note` op
+ * whose `task` field is the exact item label, keeping note targets in lock-step
+ */
+export function buildTodoWriteOpsForPlan(plan: Plan): { ops: TodoWriteOp[] } {
+  if (plan.tasks.length === 0) return { ops: [] };
+
+  const items = uniqueTaskLabels(plan.tasks.map((task) => task.name));
+
+  const ops: TodoWriteOp[] = [
+    {
+      op: "init",
+      list: [{ phase: PLAN_PHASE_NAME, items }],
+    },
+  ];
+
+  for (const [index, task] of plan.tasks.entries()) {
+    const trimmed = task.criteria.trim();
+    if (!trimmed) continue;
+    // Note targets MUST equal the item label verbatim \u2014 task identity is the
+    // task content string, never a synthetic id.
+    ops.push({ op: "note", task: items[index], text: trimmed });
+  }
+
+  return { ops };
+}
+
 /**
  * Build the execution handoff prompt from an approved plan.
  *
  * Mirrors OMP's `plan-mode-approved.md` template: critical directive
  * to execute, the full plan content, and step-by-step instructions.
+ *
+ * When `plan` is provided and has tasks, the prompt also embeds the
+ * exact `todo_write` payload the agent must call before doing any work.
  */
-function buildExecutionPrompt(planContent: string, planPath: string): string {
+function buildExecutionPrompt(
+  planContent: string,
+  planPath: string,
+  plan?: Plan,
+): string {
+  const todoBlock: string[] = [];
+  if (plan && plan.tasks.length > 0) {
+    const payload = buildTodoWriteOpsForPlan(plan);
+    const initOp = payload.ops.find(
+      (op): op is Extract<TodoWriteOp, { op: "init" }> => op.op === "init",
+    );
+    const phaseName = initOp?.list[0]?.phase ?? PLAN_PHASE_NAME;
+    todoBlock.push(
+      "",
+      "## Initialize todo tracker",
+      "",
+      "Before any other work, call `todo_write` with exactly this payload:",
+      "",
+      "```json",
+      JSON.stringify(payload, null, 2),
+      "```",
+      "",
+      `Task identity is the task content verbatim. Later progress updates (\`start\`, \`done\`, \`note\`) MUST pass \`task\` equal to the exact item string above; phase updates MUST pass \`phase: "${phaseName}"\`. Mark the first task \`in_progress\` and proceed.`,
+    );
+  }
+
   return [
     "<critical>",
     "Plan approved. You **MUST** execute it now.",
@@ -100,9 +226,8 @@ function buildExecutionPrompt(planContent: string, planPath: string): string {
     "<instruction>",
     `You **MUST** execute this plan step by step from \`${planPath}\`.`,
     "You **MUST** verify each step before proceeding to the next.",
-    "Before execution, you **MUST** initialize todo tracking with the task list.",
-    "After each completed step, immediately update progress so it stays visible.",
     "</instruction>",
+    ...todoBlock,
     "",
     "<critical>",
     "You **MUST** keep going until complete. This matters.",
@@ -128,8 +253,9 @@ async function executeApproveFlow(
   newSession: ((options?: any) => Promise<{ cancelled: boolean }>) | null,
   resolvedModel: ResolvedModel | null,
   debugLogger: DebugLogger | null,
+  plan: Plan | null,
  ): Promise<void> {
-  const prompt = buildExecutionPrompt(planContent, planPath);
+  const prompt = buildExecutionPrompt(planContent, planPath, plan ?? undefined);
   debugLogger?.log("execution_handoff_started", {
     planPath,
     promptLength: prompt.length,
@@ -211,7 +337,76 @@ export function registerPlanApprovalHook(platform: Platform): void {
       return;
     }
 
-    const planPath = `${platform.paths.dotDirDisplay}/supipowers/plans/${planName}`;
+    // Schema-first validation: the plan must parse into a valid PlanSpec.
+    // Invalid plans trigger a retry steer — no approval UI until the agent
+    // produces an artifact whose task list matches the PlanSpec contract.
+    //
+    // We validate but do NOT canonicalize the on-disk file. Today's plan
+    // writer produces rich markdown (architecture, per-task TDD steps) that
+    // the parser intentionally does not capture. Rewriting the file from the
+    // parsed PlanSpec would strip that structure. The schema is the
+    // validation gate; markdown stays the user-visible form until a future
+    // phase lifts the agent to write PlanSpec directly.
+    const validated = validatePlanMarkdown(planContent, planName);
+    if (!validated.output) {
+      debugLogger?.log("approval_flow_plan_invalid", {
+        planName,
+        error: validated.error,
+        errors: validated.errors,
+      });
+      try {
+        appendReliabilityRecord(platform.paths, planCwd, {
+          ts: new Date().toISOString(),
+          command: "plan",
+          operation: "plan-spec",
+          outcome: "blocked",
+          attempts: 1,
+          reason: validated.error ?? "Plan validation failed.",
+          cwd: planCwd,
+        });
+      } catch {}
+      plansBefore = plansNow;
+      const steer = [
+        `The plan you just wrote to \`${path.join(getProjectStatePath(platform.paths, planCwd, "plans"), planName)}\` does not match the required schema.`,
+        "",
+        "Validation errors:",
+        ...validated.errors.map((err) => `- ${err.path}: ${err.message}`),
+        "",
+        "Fix the plan and rewrite the file so every task includes id, name, files, criteria, and complexity (small|medium|large).",
+      ].join("\n");
+      platform.sendMessage(
+        {
+          customType: "supi-plan-invalid",
+          content: [{ type: "text", text: steer }],
+          display: "none",
+        },
+        { deliverAs: "steer", triggerTurn: true },
+      );
+      return;
+    }
+
+    const canonicalContent = planContent;
+    const planPath = path.join(getProjectStatePath(platform.paths, planCwd, "plans"), planName);
+    let parsedPlan: Plan | null = null;
+    try {
+      parsedPlan = parsePlan(planContent, planPath);
+    } catch (error) {
+      debugLogger?.log("approval_flow_plan_parse_failed", {
+        planName,
+        planPath,
+        error: error instanceof Error ? error.message : String(error),
+      });
+    }
+    try {
+      appendReliabilityRecord(platform.paths, planCwd, {
+        ts: new Date().toISOString(),
+        command: "plan",
+        operation: "plan-spec",
+        outcome: "ok",
+        attempts: 1,
+        cwd: planCwd,
+      });
+    } catch {}
     const approvalOptions = [
       "Approve and execute",
       "Refine plan",
@@ -238,11 +433,12 @@ export function registerPlanApprovalHook(platform: Platform): void {
       await executeApproveFlow(
         platform,
         ctx,
-        planContent,
+        canonicalContent,
         planPath,
         executionNewSession,
         executionModel,
         debugLogger,
+        parsedPlan,
       );
     } else if (choice === "Refine plan") {
       // Keep planning active, let user type refinement.
@@ -260,11 +456,12 @@ export function registerPlanApprovalHook(platform: Platform): void {
         await executeApproveFlow(
         platform,
         ctx,
-        planContent,
+        canonicalContent,
         planPath,
         executionNewSession,
         executionModel,
         debugLogger,
+        parsedPlan,
       );
       } else {
         debugLogger?.log("approval_flow_refine_requested", {

package/src/planning/plan-writer-prompt.ts

@@ -3,7 +3,8 @@ import { PLAN_CODE_CONTENT_REQUIREMENTS, formatPlanReviewCategorySummary } from
 
 export interface PlanWriterOptions {
   specPath: string;
-  dotDirDisplay: string;
+  /** Absolute path to the directory where the plan must be saved. */
+  plansDir: string;
 }
 
 /**
@@ -18,7 +19,7 @@ export interface PlanWriterOptions {
  * - Execution handoff
  */
 export function buildPlanWriterPrompt(options: PlanWriterOptions): string {
-  const { specPath, dotDirDisplay } = options;
+  const { specPath, plansDir } = options;
 
   const sections: string[] = [
     "You are writing a comprehensive implementation plan from an approved design spec.",
@@ -134,7 +135,7 @@ export function buildPlanWriterPrompt(options: PlanWriterOptions): string {
     // ── Save Location ────────────────────────────────────────────
     "## Step 5: Save Plan",
     "",
-    `Save the plan to \`${dotDirDisplay}/supipowers/plans/YYYY-MM-DD-<feature-name>.md\``,
+    `Save the plan to \`${plansDir}/YYYY-MM-DD-<feature-name>.md\``,
     "",
 
     // ── Execution Handoff ────────────────────────────────────────

package/src/planning/planning-ask-tool.ts

@@ -1,4 +1,6 @@
 import type { Platform } from "../platform/types.js";
+import { isPlanningActive } from "./approval-flow.js";
+import { isUiDesignActive, recordUiDesignReviewApproval } from "../ui-design/session.js";
 
 /**
  * Register a `planning_ask` tool — identical to the built-in `ask` tool
@@ -66,6 +68,7 @@ export function registerPlanningAskTool(platform: Platform): void {
       });
 
       const selected = choice ?? labels[params.recommended ?? 0] ?? labels[0];
+      recordUiDesignReviewApproval(params.question, labels, selected);
 
       return {
         content: [
@@ -79,3 +82,39 @@ export function registerPlanningAskTool(platform: Platform): void {
     },
   });
 }
+
+function getAskRedirectReason(): string | null {
+  if (isPlanningActive()) {
+    return "Planning mode: use the `planning_ask` tool instead of `ask`. `planning_ask` has no timeout so the user can think without pressure.";
+  }
+
+  if (isUiDesignActive()) {
+    return "UI-design mode: use the `planning_ask` tool instead of `ask`. The Design Director workflow requires auditable gated responses through `planning_ask`.";
+  }
+
+  return null;
+}
+
+/**
+ * Register a tool_call guard that blocks the generic `ask` tool during
+ * active planning or ui-design sessions and points the model at
+ * `planning_ask` instead.
+ *
+ * This is the runtime complement to the prompt-level directive in the
+ * planning and ui-design prompts: even if prompt wording drifts or the
+ * model ignores it, invoking `ask` in those modes returns a block result
+ * with a truthful redirection.
+ */
+export function registerPlanningAskToolGuard(platform: Platform): void {
+  platform.on("tool_call", (event) => {
+    if (event.toolName !== "ask") return;
+
+    const reason = getAskRedirectReason();
+    if (!reason) return;
+
+    return {
+      block: true,
+      reason,
+    };
+  });
+}

package/src/planning/render-markdown.ts

@@ -0,0 +1,74 @@
+// src/planning/render-markdown.ts
+//
+// Deterministic PlanSpec → markdown renderer. Every saved plan comes from
+// this module, so the on-disk representation cannot drift from the
+// canonical PlanSpec. Parsers in src/storage/plans.ts must be able to
+// recover a valid PlanSpec from this output — covered by the round-trip
+// test in tests/planning/render-markdown.test.ts.
+
+import type { PlanSpec, PlanSpecTask } from "./spec.js";
+
+function renderFrontmatter(spec: PlanSpec): string {
+  const lines = ["---"];
+  lines.push(`name: ${spec.name}`);
+  if (spec.created) lines.push(`created: ${spec.created}`);
+  lines.push(`tags: [${spec.tags.join(", ")}]`);
+  lines.push("---");
+  return lines.join("\n");
+}
+
+function renderContextSection(context: string): string {
+  const body = context.trim();
+  return body.length > 0 ? `## Context\n\n${body}` : "## Context\n";
+}
+
+function renderFilesList(files: string[]): string {
+  if (files.length === 0) return "**files**: (none)";
+  return files.map((file) => `- \`${file}\``).join("\n");
+}
+
+function renderTask(task: PlanSpecTask): string {
+  const header = `### Task ${task.id}: ${task.name}${task.model ? ` [model: ${task.model}]` : ""}`;
+  const parts: string[] = [header, ""];
+
+  parts.push("**files**:");
+  parts.push(renderFilesList(task.files));
+  parts.push("");
+
+  parts.push(`**criteria**: ${task.criteria}`);
+  parts.push(`**complexity**: ${task.complexity}`);
+
+  if (task.description && task.description.trim() !== task.name.trim()) {
+    parts.push("");
+    parts.push(task.description.trim());
+  }
+
+  return parts.join("\n");
+}
+
+/**
+ * Render a validated PlanSpec to the canonical markdown representation
+ * accepted by src/storage/plans.ts's parser. Output is stable across
+ * identical input so diffs stay reviewable.
+ */
+export function renderPlanSpec(spec: PlanSpec): string {
+  const sections: string[] = [
+    renderFrontmatter(spec),
+    "",
+    `# ${spec.name}`,
+    "",
+    renderContextSection(spec.context),
+  ];
+
+  if (spec.tasks.length > 0) {
+    sections.push("");
+    sections.push("## Tasks");
+    for (const task of spec.tasks) {
+      sections.push("");
+      sections.push(renderTask(task));
+    }
+  }
+
+  // Trailing newline for POSIX hygiene.
+  return sections.join("\n") + "\n";
+}

package/src/planning/spec.ts

@@ -0,0 +1,42 @@
+// src/planning/spec.ts
+//
+// Canonical TypeBox contract for a supipowers implementation plan (PlanSpec).
+// The agent produces markdown, src/storage/plans.ts parses it, and this
+// schema is the validator of record. Markdown that doesn't parse into a
+// PlanSpec is rejected — no silent promotion of partial artifacts.
+//
+// Phase 3 exit gate: PlanSpec is the canonical planning artifact; markdown
+// is rendered from it via render-markdown.ts, not the other way around.
+
+import { Type, type Static } from "@sinclair/typebox";
+
+export const TASK_COMPLEXITY_VALUES = ["small", "medium", "large"] as const;
+
+export const PlanSpecTaskSchema = Type.Object(
+  {
+    id: Type.Integer({ minimum: 1 }),
+    name: Type.String({ minLength: 1 }),
+    description: Type.String(),
+    files: Type.Array(Type.String({ minLength: 1 })),
+    criteria: Type.String(),
+    complexity: Type.Union(TASK_COMPLEXITY_VALUES.map((v) => Type.Literal(v))),
+    model: Type.Optional(Type.String({ minLength: 1 })),
+  },
+  { additionalProperties: false },
+);
+
+export const PlanSpecSchema = Type.Object(
+  {
+    name: Type.String({ minLength: 1 }),
+    /** ISO date string, e.g. "2026-04-17". Empty string is tolerated for
+     * legacy plans produced before the field was required. */
+    created: Type.String(),
+    tags: Type.Array(Type.String()),
+    context: Type.String(),
+    tasks: Type.Array(PlanSpecTaskSchema),
+  },
+  { additionalProperties: false },
+);
+
+export type PlanSpec = Static<typeof PlanSpecSchema>;
+export type PlanSpecTask = Static<typeof PlanSpecTaskSchema>;

package/src/planning/system-prompt.ts

@@ -1,4 +1,5 @@
 import type { Platform } from "../platform/types.js";
+import { systemPromptText } from "../platform/system-prompt.js";
 import { createDebugLogger } from "../debug/logger.js";
 import { getPlanningDebugLogger, getPlanningPromptOptions, isPlanningActive } from "./approval-flow.js";
 import { buildPlanWriterPrompt } from "./plan-writer-prompt.js";
@@ -8,6 +9,9 @@ import { buildSpecReviewerPrompt } from "./spec-reviewer.js";
 export interface PlanningSystemPromptOptions {
   skillContent?: string;
   dotDirDisplay: string;
+  /** Absolute path to the directory where plans must be saved.
+   * Owned by approval-flow's listPlans watcher; the agent MUST write here. */
+  plansDir: string;
   topic?: string;
   isQuick?: boolean;
 }
@@ -81,7 +85,7 @@ function buildFullPlanningSection(options: PlanningSystemPromptOptions): string
   const specReviewerPrompt = buildSpecReviewerPrompt("<path-to-spec-file>");
   const planWriterPrompt = buildPlanWriterPrompt({
     specPath: "<path-to-approved-spec>",
-    dotDirDisplay: options.dotDirDisplay,
+    plansDir: options.plansDir,
   });
 
   return [
@@ -97,10 +101,9 @@ function buildFullPlanningSection(options: PlanningSystemPromptOptions): string
     "## HARD-GATE",
     "",
     "- Do NOT write production code, apply patches, or claim that you changed files during planning.",
-    "- The only allowed file writes are the approved design doc under `.omp/supipowers/specs/` and the final implementation plan under `.omp/supipowers/plans/`.",
+    `- The only allowed file writes are the approved design doc under \`${options.dotDirDisplay}/supipowers/specs/\` and the final implementation plan under \`${options.plansDir}/\`.`,
     "- Keep planning artifacts local. Do NOT stage, commit, or push the design doc or implementation plan.",
     "- If the user asks to jump into coding early, explain that planning mode must finish first.",
-    "- When you need to ask the user a question with options, use the `planning_ask` tool instead of `ask`. It has no timeout so the user can think without pressure.",
     "",
     "## Planning Workflow",
     "",
@@ -131,7 +134,7 @@ function buildFullPlanningSection(options: PlanningSystemPromptOptions): string
     "- Apply YAGNI ruthlessly and prefer isolated units with clear boundaries.",
     "",
     "### Phase 5: Write the design doc",
-    "- After the user approves the design, write `.omp/supipowers/specs/YYYY-MM-DD-<topic>-design.md`.",
+    `- After the user approves the design, write \`${options.dotDirDisplay}/supipowers/specs/YYYY-MM-DD-<topic>-design.md\`.`,
     "- Use concise, implementation-ready language.",
     "- Keep the design doc local; do NOT commit it to git.",
     "",
@@ -209,7 +212,7 @@ function buildQuickPlanningSection(options: PlanningSystemPromptOptions): string
     "",
     "4. Each task must include name, files, criteria, and complexity (small/medium/large).",
     `   - ${QUICK_PLAN_TASK_CONTENT_REQUIREMENT}`,
-    "5. Save the plan under `.omp/supipowers/plans/YYYY-MM-DD-<feature-name>.md`.",
+    `5. Save the plan under \`${options.plansDir}/YYYY-MM-DD-<feature-name>.md\`.`,
     "6. After saving, tell the user: `Plan saved to <path>. Review it and approve when ready.`",
     "7. Then stop and wait. The approval UI handles execution handoff.",
     ...buildAdditionalGuidelines(options.skillContent),
@@ -232,7 +235,7 @@ function buildPlanningCriticalBlock(options: PlanningSystemPromptOptions): strin
     "This is NOT native OMP plan mode.",
     "You **MUST NOT** call `exit_plan_mode` or `ExitPlanMode` — it will fail.",
     `You **MUST NOT** write plans to \`local://PLAN.md\` — that is OMP's native plan location and will not trigger the approval flow.`,
-    `You **MUST** save the plan to \`${options.dotDirDisplay}/supipowers/plans/YYYY-MM-DD-<feature-name>.md\` using the Write tool.`,
+    `You **MUST** save the plan to \`${options.plansDir}/YYYY-MM-DD-<feature-name>.md\` using the Write tool.`,
     "After saving, tell the user the plan path, then **stop and yield your turn**.",
     "The approval UI appears automatically when your turn ends and a new plan file is detected in that directory.",
     "</critical>",
@@ -270,7 +273,7 @@ export function registerPlanningSystemPromptHook(platform: Platform): void {
 
     const debugLogger = getPlanningDebugLogger() ?? createDebugLogger(platform.paths, ctx as any, "plan");
     const options = getPlanningPromptOptions();
-    const basePrompt = (event as any).systemPrompt as string | undefined;
+    const basePrompt = systemPromptText((event as any).systemPrompt);
     if (!options || !basePrompt) {
       debugLogger.log("system_prompt_override_skipped", {
         hasPlanningOptions: Boolean(options),
@@ -288,6 +291,6 @@ export function registerPlanningSystemPromptHook(platform: Platform): void {
       systemPrompt,
     });
 
-    return { systemPrompt };
+    return { systemPrompt: [systemPrompt] };
   });
 }

package/src/planning/validate.ts

@@ -0,0 +1,84 @@
+// src/planning/validate.ts
+//
+// Typed validation helpers for PlanSpec. Consumers (plan command, approval
+// flow) call `validatePlanSpec(data)` and branch on `.output` vs `.error`.
+// Everyone converges on the same path so validation errors surface in one
+// consistent shape with field-level paths.
+
+import { Value } from "@sinclair/typebox/value";
+import { collectValidationErrors, formatValidationErrors } from "../ai/structured-output.js";
+import type { ValidationError } from "../types.js";
+import { PlanSpecSchema, type PlanSpec } from "./spec.js";
+
+export interface PlanSpecValidationResult {
+  output: PlanSpec | null;
+  error: string | null;
+  errors: ValidationError[];
+}
+
+/**
+ * Validate an arbitrary value against PlanSpecSchema. Returns `{output, null}`
+ * on success and `{null, error, errors}` on failure, where `error` is a
+ * human-readable summary and `errors` lists every field-level issue.
+ */
+export function validatePlanSpec(data: unknown): PlanSpecValidationResult {
+  if (Value.Check(PlanSpecSchema, data)) {
+    return { output: data as PlanSpec, error: null, errors: [] };
+  }
+
+  const errors = collectValidationErrors(PlanSpecSchema, data);
+  const error = errors.length > 0
+    ? formatValidationErrors(errors).join("; ")
+    : "Plan does not match the PlanSpec schema.";
+  return { output: null, error, errors };
+}
+
+/**
+ * Narrowing predicate for PlanSpec. Use when you do not need error detail.
+ */
+export function isPlanSpec(value: unknown): value is PlanSpec {
+  return Value.Check(PlanSpecSchema, value);
+}
+
+
+// ---------------------------------------------------------------------------
+// Markdown-level convenience
+// ---------------------------------------------------------------------------
+
+import { parsePlan } from "../storage/plans.js";
+import { renderPlanSpec } from "./render-markdown.js";
+
+export interface PlanMarkdownValidationResult extends PlanSpecValidationResult {
+  /** Canonical markdown rendered from the validated PlanSpec. Null on failure. */
+  canonicalMarkdown: string | null;
+}
+
+/**
+ * Parse a plan markdown document, project it into a PlanSpec candidate,
+ * validate against PlanSpecSchema, and render the canonical markdown for a
+ * validated spec. On failure, returns `canonicalMarkdown: null` alongside
+ * the usual error and errors fields.
+ */
+export function validatePlanMarkdown(content: string, planFileName: string = ""): PlanMarkdownValidationResult {
+  const parsed = parsePlan(content, planFileName);
+  const candidate = {
+    name: parsed.name,
+    created: parsed.created,
+    tags: parsed.tags,
+    context: parsed.context,
+    tasks: parsed.tasks.map((t) => ({
+      id: t.id,
+      name: t.name,
+      description: t.description,
+      files: t.files,
+      criteria: t.criteria,
+      complexity: t.complexity,
+      ...(t.model ? { model: t.model } : {}),
+    })),
+  };
+  const validated = validatePlanSpec(candidate);
+  return {
+    ...validated,
+    canonicalMarkdown: validated.output ? renderPlanSpec(validated.output) : null,
+  };
+}