supipowers 2.1.0 → 2.2.1

package/README.md

@@ -72,15 +72,16 @@ The installer scans for these and offers to install missing tooling where it can
 | `/supi:config`           | Interactive settings TUI                                      |
 | `/supi:status`           | Show project plans and configuration summary                  |
 | `/supi:doctor`           | Diagnose extension health and missing dependencies            |
-| `/supi:generate`        | Documentation drift detection                                |
+| `/supi:generate`        | Documentation drift checks via `docs` (default); use `--target <package>` to scope |
 | `/supi:update`           | Update supipowers to the latest version                       |
 | `/supi:agents`           | Manage review agents                                          |
 | `/supi:ultraplan`        | Multi-stage authoring pipeline (intake → scout → discover → research → synthesize → review → approve) |
 | `/supi:harness`          | Harness engineering pipeline and anti-slop guardrails         |
 | `/supi:memory`           | Manage native MemPalace memory integration (`status`, `setup`) |
+| `/runbook`              | Show registered OMP rules, TTSR conditions, and slash commands without an LLM turn |
 | `/supi:clear`            | Clear metrics, cache, session knowledge, and memory           |
 
-Most commands steer the AI session. These are TUI-only — they open native dialogs without triggering the AI: `/supi`, `/supi:config`, `/supi:status`, `/supi:review`, `/supi:update`, `/supi:doctor`, `/supi:model`, `/supi:context`, `/supi:optimize-context`, `/supi:commit`, `/supi:release`, `/supi:checks`, `/supi:agents`, `/supi:ultraplan`, `/supi:harness`, `/supi:memory`, `/supi:clear`.
+Most commands steer the AI session. These are TUI-only — they open native dialogs without triggering the AI: `/supi`, `/supi:config`, `/supi:status`, `/supi:review`, `/supi:update`, `/supi:doctor`, `/supi:model`, `/supi:context`, `/supi:optimize-context`, `/supi:commit`, `/supi:release`, `/supi:checks`, `/supi:agents`, `/supi:ultraplan`, `/supi:harness`, `/supi:memory`, `/supi:clear`, `/runbook`.
 
 ## How it works
 
@@ -88,6 +89,8 @@ Most commands steer the AI session. These are TUI-only — they open native dial
 
 **Quality gates.** `/supi:checks` runs deterministic quality gates. Six gates are available: `lsp-diagnostics`, `lint`, `typecheck`, `format`, `test-suite`, and `build`. Each gate can be enabled independently via `/supi:config` or the shared repository config at `.omp/supipowers/config.json`. In monorepos, `/supi:checks` defaults to `All`, which runs the root target plus every workspace target sequentially; use `--target <package>` to narrow the run or `--target all` to request the batch mode explicitly. Gates report issues with severity levels.
 
+**Documentation drift.** `/supi:generate docs` checks tracked documentation for drift from the current codebase. `docs` is the default subcommand, and `--target <package>` scopes discovery and checking to a workspace/package target; the root target covers repository-level docs.
+
 **AI code review.** `/supi:review` runs a programmatic AI review pipeline with configurable depth (quick, deep, or multi-agent). It uses headless agent sessions with structured JSON validation, always validates findings before user action, writes the current validated findings to a session `findings.md` document, and then presents three next-step choices: `Fix now`, `Document only`, or `Discuss before fixing`.
 
 **Review agents.** Multi-agent review loads agents from two scopes: global and project.
@@ -101,7 +104,7 @@ Most commands steer the AI session. These are TUI-only — they open native dial
 
 Use `/supi:agents` to inspect the merged set that will actually run.
 
-**PR fixing.** `/supi:fix-pr` fetches PR review comments, critically assesses each one, checks for ripple effects, then fixes or rejects with evidence. Bot reviewers are auto-detected and filtered out.
+**PR fixing.** `/supi:fix-pr` fetches PR review comments, critically assesses each one, checks for ripple effects, then fixes or rejects with evidence. Known bot reviewers in the selected comment snapshot are auto-detected to configure re-review triggering; bot-authored comments are not filtered out solely because they are bots.
 
 **Context protection.** Supipowers always enables built-in context protection through native `ctx_*` tools and routing hooks. Search/find and web-fetch style operations are redirected to sandboxed execution or indexed storage, and oversized tool results are compressed before they reach the conversation.
 
@@ -131,17 +134,50 @@ Use `/supi:agents` to inspect the merged set that will actually run.
 
 `/supi:checks` runs deterministic quality gates. Each gate is independently configurable in `quality.gates` via `/supi:config` or the shared config JSON files:
 
-| Gate               | What it checks                  | Config type       |
-| ------------------ | ------------------------------- | ----------------- |
-| `lsp-diagnostics`  | Language server diagnostics     | enabled           |
-| `lint`             | Linter (e.g. `eslint`, `biome`) | enabled + command |
-| `typecheck`        | Type checker (e.g. `tsc`)       | enabled + command |
-| `format`           | Formatter check                 | enabled + command |
-| `test-suite`       | Test runner                     | enabled + command |
-| `build`            | Build verification              | enabled + command |
+| Gate               | What it checks                  | Config type                    |
+| ------------------ | ------------------------------- | ------------------------------ |
+| `lsp-diagnostics`  | Language server diagnostics     | `enabled`                      |
+| `lint`             | Linter (e.g. `eslint`, `biome`) | `enabled: true` + `runs[]`     |
+| `typecheck`        | Type checker (e.g. `tsc`)       | `enabled: true` + `runs[]`     |
+| `format`           | Formatter check                 | `enabled: true` + `runs[]`     |
+| `test-suite`       | Test runner                     | `enabled: true` + `runs[]`     |
+| `build`            | Build verification              | `enabled: true` + `runs[]`     |
 
 Gates default to disabled. Enable them globally in `~/.omp/supipowers/config.json` or per-repository in `.omp/supipowers/config.json`. In monorepos, the repository config is shared by the root target and every workspace, and `/supi:checks` defaults to `All` (root target + every workspace target).
 
+Enabled command gates require `runs: [{ command, target }]`. `target.scope` must be one of `all-targets`, `root`, `all-workspaces`, or `workspace`; `workspace` selectors also require `relativeDir`.
+
+```json
+{
+  "quality": {
+    "gates": {
+      "typecheck": {
+        "enabled": true,
+        "runs": [
+          {
+            "command": "bun run typecheck",
+            "target": { "scope": "all-targets" }
+          }
+        ]
+      },
+      "test-suite": {
+        "enabled": true,
+        "runs": [
+          {
+            "command": "bun test",
+            "target": { "scope": "root" }
+          },
+          {
+            "command": "bun --cwd packages/api test",
+            "target": { "scope": "workspace", "relativeDir": "packages/api" }
+          }
+        ]
+      }
+    }
+  }
+}
+```
+
 ## Configuration
 
 ```
@@ -215,9 +251,32 @@ Supipowers ships runtime-loaded prompt skills that are also available to the age
 | `receiving-code-review` | Agent sessions          |
 | `release`               | `/supi:release`         |
 | `context-mode`          | Context window guidance |
+| `ultraplan-intake`      | `/supi:ultraplan plan` intake stage |
+| `ultraplan-scout`       | `/supi:ultraplan plan` scout stage |
+| `ultraplan-discover`    | `/supi:ultraplan discover` |
+| `ultraplan-research`    | `/supi:ultraplan research` |
+| `ultraplan-synthesize`  | `/supi:ultraplan synthesize` |
+| `ultraplan-review`      | `/supi:ultraplan review` orchestration |
+| `ultraplan-review-structure` | `/supi:ultraplan review` structure checker |
+| `ultraplan-review-scope` | `/supi:ultraplan review` scope checker |
+| `ultraplan-review-tdd`  | `/supi:ultraplan review` TDD checker |
 | `creating-supi-agents`  | Agent creation guidance  |
 | `harness`               | `/supi:harness`         |
 
+## Containerized deployments
+
+Supipowers runs unchanged inside containerized OMP installs (robomp slots, the swarm extension, CI runners). When the slot must stay credential-free, run a sidecar `omp auth-gateway` outside the container and pin the per-provider transport in `~/.omp/agent/models.yml`:
+
+```yaml
+providers:
+  anthropic:
+    transport: pi-native
+    baseUrl: http://llm-gateway.internal:4000
+    apiKey: <gateway-bearer>
+```
+
+The slot keeps resolving pricing, capabilities, and thinking config locally from its bundled `models.json`; only the streaming dispatch is redirected through the gateway, which holds the real provider tokens. Multi-host credential sync uses the matching `omp auth-broker` subcommand. Requires OMP ≥ 15.1.3.
+
 ## Development
 
 ```bash
@@ -229,4 +288,4 @@ bun run build        # emit to dist/
 
 Tests live in `tests/`, mirroring `src/` one-to-one. The test runner is Bun's built-in `bun:test`.
 
-Peer dependencies (`@oh-my-pi/pi-coding-agent`, `@oh-my-pi/pi-ai`, `@oh-my-pi/pi-tui`, `@sinclair/typebox`) are provided by the OMP host; they are devDependencies only for type-checking during development.
+Peer dependencies (`@oh-my-pi/pi-coding-agent`, `@oh-my-pi/pi-ai`, `@oh-my-pi/pi-tui`) are provided by the OMP host at runtime; matching devDependencies are installed for type-checking during development.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "supipowers",
-  "version": "2.1.0",
+  "version": "2.2.1",
   "description": "Workflow extension for OMP coding agents.",
   "type": "module",
   "scripts": {
@@ -67,13 +67,13 @@
   "dependencies": {
     "@clack/prompts": "^0.10.0",
     "handlebars": "^4.7.8",
-    "yaml": "^2.8.3"
+    "yaml": "^2.8.3",
+    "zod": "^4.3.0"
   },
   "peerDependencies": {
     "@oh-my-pi/pi-coding-agent": "*",
     "@oh-my-pi/pi-ai": "*",
-    "@oh-my-pi/pi-tui": "*",
-    "@sinclair/typebox": "*"
+    "@oh-my-pi/pi-tui": "*"
   },
   "peerDependenciesMeta": {
     "@oh-my-pi/pi-coding-agent": {
@@ -84,16 +84,12 @@
     },
     "@oh-my-pi/pi-tui": {
       "optional": true
-    },
-    "@sinclair/typebox": {
-      "optional": true
     }
   },
   "devDependencies": {
     "@oh-my-pi/pi-ai": "latest",
     "@oh-my-pi/pi-coding-agent": "latest",
     "@oh-my-pi/pi-tui": "latest",
-    "@sinclair/typebox": "^0.34.48",
     "@types/node": "^22.0.0",
     "bun-types": "^1.3.11",
     "typescript": "^5.9.3"

package/skills/ui-design/SKILL.md

@@ -7,7 +7,7 @@ description: Design Director state machine for `/supi:ui-design`. Drives 9 model
 
 Guide the Design Director through 9 model-owned phases to produce a validated design artifact under `<sessionDir>`. Loaded by `/supi:ui-design` via system-prompt override.
 
-You **MUST NOT** generate production code, write outside the session directory, or skip phases. You **MUST NOT** call `exit_plan_mode`. Use `planning_ask` for every user question — never the raw `ask` tool.
+You **MUST NOT** generate production code, write outside the session directory, or skip phases. You **MUST NOT** call `resolve` with `extra.title`. Use `planning_ask` for every user question — never the raw `ask` tool.
 
 ## Director state machine
 
@@ -56,7 +56,7 @@ Every sub-agent MUST be passed the full `context.md` so component authors share
 You MUST NOT:
 - Write outside `<sessionDir>`.
 - Generate production code (`.ts`, `.tsx`, `.vue`, `.svelte`, `.py`, etc.) intended for the user's codebase.
-- Call `exit_plan_mode` or `ExitPlanMode` — the `/supi:ui-design` completion flow runs through the `agent_end` approval hook.
+- Call `resolve` with `extra.title` — the `/supi:ui-design` completion flow runs through the `agent_end` approval hook.
 - Use the `ask` tool — use `planning_ask` for every user prompt.
 - Skip a phase or declare "done" without updating `manifest.json`.
 - Invoke `task` without a completed filename-collision check (Phase 3).

package/src/ai/final-message.ts

@@ -56,6 +56,13 @@ function extractTextFromContent(content: unknown): string {
   return "";
 }
 
+function createTimeoutPromise(timeoutMs: number): Promise<never> {
+  return new Promise((_, reject) => {
+    setTimeout(() => reject(new Error(`Agent session timed out after ${timeoutMs}ms.`)), timeoutMs);
+  });
+}
+
+
 /**
  * Walk the message list backwards and return the last assistant message text.
  * Returns null when no assistant message contains usable text.
@@ -99,7 +106,14 @@ export async function runStructuredAgentSession(
   });
 
   try {
-    await session.prompt(options.prompt, { expandPromptTemplates: false });
+    if (options.timeoutMs !== undefined && options.timeoutMs > 0) {
+      await Promise.race([
+        session.prompt(options.prompt, { expandPromptTemplates: false }),
+        createTimeoutPromise(options.timeoutMs),
+      ]);
+    } else {
+      await session.prompt(options.prompt, { expandPromptTemplates: false });
+    }
     const finalText = extractFinalAssistantText(session.state.messages);
 
     if (!finalText) {

package/src/ai/schema-text.ts

@@ -1,7 +1,7 @@
 // src/ai/schema-text.ts
 //
-// Render a TypeBox schema as compact TS-like text suitable for embedding in
-// prompts. One canonical rendering means that adding a field to a TypeBox
+// Render a Zod schema as compact TS-like text suitable for embedding in
+// prompts. One canonical rendering means that adding a field to a Zod
 // contract automatically updates every prompt that references it through
 // this module — no hand-maintained schema prose to drift.
 //
@@ -10,17 +10,24 @@
 //     ReviewOutputSchema / ReviewFixOutputSchema for both the main prompt
 //     and the retry prompt produced by runWithOutputValidation.
 //
+// Implementation note:
+//   We don't walk Zod's internal `_zod.def` tree directly. Zod's JSON Schema
+//   accessor (`z.toJSONSchema`) already emits draft-2020-12 output for every
+//   shape we use; we walk that intermediate JSON Schema instead, which keeps
+//   this module independent of Zod's internal AST changes.
+//
 // Non-goals:
-//   - Produce standards-compliant JSON Schema output. Use TypeBox's own
-//     JSON Schema accessors for that. This renderer optimises for model
-//     readability, not spec compliance.
-//   - Capture every TypeBox modifier. Supported shapes cover the current
-//     contract surface; extend when a real consumer needs more.
+//   - Produce standards-compliant JSON Schema output. Call `z.toJSONSchema`
+//     directly for that. This renderer optimises for model readability.
+//   - Capture every modifier. Supported shapes cover the current contract
+//     surface; extend when a real consumer needs more.
 
-import type { TSchema } from "@sinclair/typebox";
+import { z, type ZodType } from "zod/v4";
 
 const INDENT = "  ";
 
+type JsonSchemaNode = Record<string, unknown>;
+
 export interface RenderSchemaOptions {
   /** Start indent (internal recursion use). */
   depth?: number;
@@ -36,33 +43,37 @@ function renderLiteral(value: unknown): string {
   return String(value);
 }
 
-function renderUnion(parts: readonly TSchema[], depth: number): string {
+function renderUnion(parts: readonly JsonSchemaNode[], depth: number): string {
   if (parts.length === 0) return "never";
-  return parts.map((p) => renderSchemaText(p, { depth })).join(" | ");
+  return parts.map((p) => renderJsonSchema(p, depth)).join(" | ");
 }
 
-function renderObject(schema: any, depth: number): string {
-  const props = schema.properties as Record<string, TSchema> | undefined;
+function renderObject(schema: JsonSchemaNode, depth: number): string {
+  const props = schema.properties as Record<string, JsonSchemaNode> | undefined;
   if (!props || Object.keys(props).length === 0) {
     return "{}";
   }
 
-  const required: string[] = Array.isArray(schema.required) ? schema.required : [];
+  const required: string[] = Array.isArray(schema.required)
+    ? (schema.required as string[])
+    : [];
   const lines: string[] = ["{"];
   const childDepth = depth + 1;
 
   for (const [key, child] of Object.entries(props)) {
     const isRequired = required.includes(key);
     const separator = isRequired ? ":" : "?:";
-    lines.push(`${indent(childDepth)}${key}${separator} ${renderSchemaText(child, { depth: childDepth })};`);
+    lines.push(`${indent(childDepth)}${key}${separator} ${renderJsonSchema(child, childDepth)};`);
   }
 
   lines.push(`${indent(depth)}}`);
   return lines.join("\n");
 }
 
-function renderArray(schema: any, depth: number): string {
-  const inner = renderSchemaText(schema.items as TSchema, { depth });
+function renderArray(schema: JsonSchemaNode, depth: number): string {
+  const items = schema.items as JsonSchemaNode | undefined;
+  if (!items) return "unknown[]";
+  const inner = renderJsonSchema(items, depth);
   // Wrap multiline object types as Array<...> for readability.
   if (inner.includes("\n")) {
     return `Array<${inner}>`;
@@ -70,44 +81,36 @@ function renderArray(schema: any, depth: number): string {
   return `${inner}[]`;
 }
 
-function hasKey(schema: any, key: string): boolean {
-  return schema != null && typeof schema === "object" && key in schema;
+function isZodSchema(value: unknown): value is ZodType {
+  return value !== null && typeof value === "object" && "_zod" in (value as Record<string, unknown>);
 }
 
-/**
- * Render a TypeBox schema as a compact TS-like type string. Safe to pass as
- * the `schema:` param to `runWithOutputValidation` and the `{{outputSchema}}`
- * placeholder inside review prompts.
- */
-export function renderSchemaText(schema: TSchema, options: RenderSchemaOptions = {}): string {
-  const depth = options.depth ?? 0;
-  const any = schema as any;
-
+function renderJsonSchema(schema: JsonSchemaNode, depth: number): string {
   // Literal / const
-  if (hasKey(any, "const")) {
-    return renderLiteral(any.const);
+  if ("const" in schema) {
+    return renderLiteral(schema.const);
   }
 
   // Explicit enum
-  if (Array.isArray(any.enum)) {
-    return any.enum.map(renderLiteral).join(" | ");
+  if (Array.isArray(schema.enum)) {
+    return schema.enum.map(renderLiteral).join(" | ");
   }
 
   // Union (anyOf / oneOf)
-  if (Array.isArray(any.anyOf)) {
-    return renderUnion(any.anyOf, depth);
+  if (Array.isArray(schema.anyOf)) {
+    return renderUnion(schema.anyOf as JsonSchemaNode[], depth);
   }
-  if (Array.isArray(any.oneOf)) {
-    return renderUnion(any.oneOf, depth);
+  if (Array.isArray(schema.oneOf)) {
+    return renderUnion(schema.oneOf as JsonSchemaNode[], depth);
   }
 
   // Primitive / structural by `type`
-  const type = any.type as string | undefined;
+  const type = typeof schema.type === "string" ? schema.type : undefined;
   switch (type) {
     case "object":
-      return renderObject(any, depth);
+      return renderObject(schema, depth);
     case "array":
-      return renderArray(any, depth);
+      return renderArray(schema, depth);
     case "string":
       return "string";
     case "integer":
@@ -119,11 +122,28 @@ export function renderSchemaText(schema: TSchema, options: RenderSchemaOptions =
     case "null":
       return "null";
     default:
-      // Fall through — unknown shape
       break;
   }
 
   // Nothing matched — render as `unknown` rather than throwing so prompts
-  // still get something readable if someone adds an exotic schema.
+  // still get something readable if someone adds an exotic shape.
   return "unknown";
 }
+
+/**
+ * Render a Zod schema as a compact TS-like type string. Safe to pass as
+ * the `schema:` param to `runWithOutputValidation` and the `{{outputSchema}}`
+ * placeholder inside review prompts.
+ *
+ * The OMP runtime injects a Zod-backed shim for any extension that still
+ * imports `@sinclair/typebox`, so even legacy callers reach this function
+ * with a Zod schema. Non-Zod inputs (legitimate JSON Schema literals) are
+ * walked as-is.
+ */
+export function renderSchemaText(schema: ZodType | JsonSchemaNode, options: RenderSchemaOptions = {}): string {
+  const depth = options.depth ?? 0;
+  const jsonSchema = isZodSchema(schema)
+    ? (z.toJSONSchema(schema, { target: "draft-2020-12" }) as JsonSchemaNode)
+    : schema;
+  return renderJsonSchema(jsonSchema, depth);
+}

package/src/ai/schema-validation.ts

@@ -0,0 +1,88 @@
+// src/ai/schema-validation.ts
+//
+// Thin façade over Zod's `safeParse` that produces a flat `ValidationError[]`
+// shape compatible with the rest of supipowers (`parseStructuredOutput`,
+// `getUltraPlanSchemaErrors`, every gate prompt that formats validation
+// failures for retry).
+//
+// All contracts in supipowers are authored as Zod schemas (`zod/v4`). The
+// helpers here intentionally accept the structural interface — anything with
+// a working `safeParse` — so they keep working under the OMP TypeBox-shim
+// (extension load time) without needing a separate code path.
+
+import type { ZodType } from "zod/v4";
+import type { ValidationError } from "../types.js";
+
+interface ZodIssueLike {
+  path: ReadonlyArray<string | number | symbol>;
+  message: string;
+  code?: string;
+  expected?: unknown;
+  received?: unknown;
+  /** Present on Zod 4 `unrecognized_keys` issues. */
+  keys?: ReadonlyArray<string>;
+}
+
+function pathToString(path: ReadonlyArray<string | number | symbol>): string {
+  // Zod 4 path segments are `(string | number | symbol)[]`; symbols only
+  // appear for schemas with symbol keys (not used in supipowers). Drop them
+  // so the printed path stays readable.
+  const stringy = path.filter((segment): segment is string | number => typeof segment !== "symbol");
+  return stringy.length === 0 ? "(root)" : stringy.map(String).join(".");
+}
+
+function expandIssue(issue: ZodIssueLike): ValidationError[] {
+  // Zod 4 reports unrecognized strict-object keys with the offending keys in
+  // `issue.keys` and the path stopped at the parent object. Expand each key
+  // into its own ValidationError with the key appended to the path so
+  // formatted error strings (`<path>: <message>`) still identify the exact
+  // field the model produced wrongly. This matches the prompt-driven
+  // self-correction loop in `parseStructuredOutput`, which needs to tell
+  // the model which key to drop.
+  if (issue.code === "unrecognized_keys" && Array.isArray(issue.keys) && issue.keys.length > 0) {
+    return issue.keys.map((key) => ({
+      path: pathToString([...issue.path, key]),
+      message: issue.message,
+      ...(issue.code ? { code: issue.code } : {}),
+      ...(issue.expected !== undefined ? { expected: issue.expected } : {}),
+      ...(issue.received !== undefined ? { received: issue.received } : {}),
+    }));
+  }
+
+  return [{
+    path: pathToString(issue.path),
+    message: issue.message,
+    ...(issue.code ? { code: issue.code } : {}),
+    ...(issue.expected !== undefined ? { expected: issue.expected } : {}),
+    ...(issue.received !== undefined ? { received: issue.received } : {}),
+  }];
+}
+
+/**
+ * Validate `data` against `schema`. Returns an empty array on success and
+ * a stable `{path, message, ...}` shape on failure. Callers format the
+ * result for prompts/CLI/UI without further normalisation.
+ */
+export function collectSchemaValidationErrors(schema: ZodType, data: unknown): ValidationError[] {
+  const result = schema.safeParse(data);
+  if (result.success) return [];
+  return result.error.issues.flatMap((issue) => expandIssue(issue as ZodIssueLike));
+}
+
+/** Convenience wrapper. Equivalent to `collectSchemaValidationErrors(...).length === 0`. */
+export function checkSchema(schema: ZodType, data: unknown): boolean {
+  return schema.safeParse(data).success;
+}
+
+/**
+ * Parse `data` against `schema`. On success returns the schema-validated
+ * (and Zod-transformed) value; on failure returns the flattened error list.
+ */
+export function parseSchema<T>(schema: ZodType<T>, data: unknown): { success: true; data: T } | { success: false; errors: ValidationError[] } {
+  const result = schema.safeParse(data);
+  if (result.success) return { success: true, data: result.data };
+  return {
+    success: false,
+    errors: result.error.issues.flatMap((issue) => expandIssue(issue as ZodIssueLike)),
+  };
+}

package/src/ai/structured-output.ts

@@ -12,8 +12,7 @@
 // One canonical renderer lives in `./template.ts`. Neither has a review-
 // specific name any more.
 
-import type { TSchema } from "@sinclair/typebox";
-import { Value } from "@sinclair/typebox/value";
+import type { ZodType } from "zod/v4";
 import invalidOutputRetryPrompt from "./prompts/invalid-output-retry.md" with { type: "text" };
 import { runStructuredAgentSession } from "./final-message.js";
 import { renderTemplate } from "./template.js";
@@ -21,6 +20,7 @@ import { stripMarkdownCodeFence } from "../text.js";
 import type { GateExecutionContext, ReliabilityOutcome, ValidationError } from "../types.js";
 import type { PlatformPaths } from "../platform/types.js";
 import { appendReliabilityRecord } from "../storage/reliability-metrics.js";
+import { collectSchemaValidationErrors, parseSchema } from "./schema-validation.js";
 
 export interface StructuredParseResult<T> {
   output: T | null;
@@ -94,35 +94,34 @@ function truncateForPrompt(text: string, maxLength = 1200): string {
   return `${normalized.slice(0, maxLength - 1)}…`;
 }
 
-function normalizeErrorPath(path: string): string {
-  return path.replace(/^\//, "").replace(/\//g, ".") || "(root)";
-}
+
 
 /**
- * Collect schema validation errors for a TypeBox schema in a stable
- * {path, message} shape. Used by parseStructuredOutput and by any code that
- * needs to format schema-check failures for humans or prompts.
+ * Collect schema validation errors in a stable {path, message} shape. Used by
+ * parseStructuredOutput and by any code that needs to format schema-check
+ * failures for humans or prompts.
  */
-export function collectValidationErrors(schema: TSchema, data: unknown): ValidationError[] {
-  return [...Value.Errors(schema, data)].map((error) => ({
-    path: normalizeErrorPath(error.path),
-    message: error.message,
-  }));
+export function collectValidationErrors(schema: ZodType, data: unknown): ValidationError[] {
+  return collectSchemaValidationErrors(schema, data);
 }
 
 /**
  * Render validation errors as `path: message` lines.
  */
 export function formatValidationErrors(errors: ValidationError[]): string[] {
-  return errors.map((error) => `${error.path}: ${error.message}`);
+  return errors.map((error) => {
+    const code = error.code ? ` [${error.code}]` : "";
+    const expected = error.expected !== undefined ? ` Expected: ${JSON.stringify(error.expected)}.` : "";
+    return `${error.path}${code}: ${error.message}${expected}`;
+  });
 }
 
 /**
- * Strip markdown fences, JSON-parse, and schema-check against a TypeBox.
+ * Strip markdown fences, JSON-parse, and schema-check.
  * Returns {output: T, error: null} on success; {output: null, error: string}
  * on failure with a human-readable error suitable for retry prompts.
  */
-export function parseStructuredOutput<T>(raw: string, schema: TSchema): StructuredParseResult<T> {
+export function parseStructuredOutput<T>(raw: string, schema: ZodType<T>): StructuredParseResult<T> {
   let parsed: unknown;
 
   try {
@@ -134,8 +133,9 @@ export function parseStructuredOutput<T>(raw: string, schema: TSchema): Structur
     };
   }
 
-  if (!Value.Check(schema, parsed)) {
-    const errors = formatValidationErrors(collectValidationErrors(schema, parsed));
+  const result = parseSchema<T>(schema, parsed);
+  if (!result.success) {
+    const errors = formatValidationErrors(result.errors);
     return {
       output: null,
       error: errors.length > 0 ? errors.join("; ") : "Output does not match the required schema.",
@@ -143,7 +143,7 @@ export function parseStructuredOutput<T>(raw: string, schema: TSchema): Structur
   }
 
   return {
-    output: parsed as T,
+    output: result.data,
     error: null,
   };
 }

package/src/bootstrap.ts

@@ -43,6 +43,7 @@ import { registerUltraPlanAuthoringTool } from "./ultraplan/authoring-tool.js";
 import { registerUltraPlanAuthoringPipelineTools } from "./ultraplan/authoring/authoring-tools.js";
 import { registerActiveToolController } from "./tool-catalog/active-tool-controller.js";
 import { registerMempalaceHooks } from "./mempalace/hooks.js";
+import { registerRunbookCommand, handleRunbook } from "./commands/runbook.js";
 import { registerMempalaceTool } from "./mempalace/tool.js";
 
 // TUI-only commands — intercepted at the input level to prevent
@@ -65,6 +66,7 @@ const TUI_COMMANDS: Record<string, (platform: Platform, ctx: any, args?: string)
   "supi:ultraplan": (platform, ctx, args) => handleUltraplan(platform, ctx, args),
   "supi:harness": (platform, ctx, args) => { void handleHarness(platform, ctx, args); },
   "supi:memory": (platform, ctx, args) => handleMemory(platform, ctx, args),
+  "runbook": (platform, ctx, args) => handleRunbook(platform, ctx, args),
 };
 
 function getInstalledVersion(platform: Platform): string | null {
@@ -101,6 +103,7 @@ export function bootstrap(platform: Platform): void {
   registerUltraplanCommand(platform);
   registerHarnessCommand(platform);
   registerMemoryCommand(platform);
+  registerRunbookCommand(platform);
 
 
   registerUltraPlanRuntimeTools(platform);