@soleri/core 2.4.0 → 2.5.0

package/src/runtime/planning-extra-ops.ts

@@ -1,21 +1,31 @@
 /**
- * Extended planning operations — 9 ops for advanced plan lifecycle management.
+ * Extended planning operations — 22 ops for advanced plan lifecycle management.
  *
  * These complement the 5 basic planning ops in core-ops.ts with:
  * iteration, splitting, reconciliation, lifecycle completion,
- * dispatch, review, archival, task listing, and statistics.
+ * dispatch, review, archival, task listing, statistics,
+ * evidence submission, verification, validation, auto-reconciliation,
+ * review prompt generation, brainstorming, execution metrics,
+ * deliverable submission, and deliverable verification.
  */
 
 import { z } from 'zod';
 import type { OpDefinition } from '../facades/types.js';
 import type { AgentRuntime } from './types.js';
-import type { DriftItem } from '../planning/planner.js';
+import type { DriftItem, TaskEvidence } from '../planning/planner.js';
+import { matchPlaybooks, type PlaybookMatchResult } from '../playbooks/index.js';
+import { entryToPlaybookDefinition } from '../playbooks/index.js';
 
 /**
- * Create 9 extended planning operations for an agent runtime.
+ * Create 22 extended planning operations for an agent runtime.
  *
- * Groups: mutation (plan_iterate, plan_split, plan_reconcile, plan_complete_lifecycle,
- *         plan_review, plan_archive), query (plan_dispatch, plan_list_tasks, plan_stats).
+ * Groups:
+ *   mutation: plan_iterate, plan_split, plan_reconcile, plan_complete_lifecycle,
+ *             plan_review, plan_archive, plan_submit_evidence, plan_auto_reconcile,
+ *             plan_review_outcome, plan_record_task_metrics, plan_submit_deliverable
+ *   query:   plan_dispatch, plan_list_tasks, plan_stats, plan_verify_task,
+ *             plan_verify_plan, plan_validate, plan_review_spec, plan_review_quality,
+ *             plan_brainstorm, plan_execution_metrics, plan_verify_deliverables
  */
 export function createPlanningExtraOps(runtime: AgentRuntime): OpDefinition[] {
   const { planner, vault } = runtime;
@@ -31,15 +41,15 @@ export function createPlanningExtraOps(runtime: AgentRuntime): OpDefinition[] {
         planId: z.string().describe('ID of the draft plan to iterate on'),
         objective: z.string().optional().describe('New objective (replaces existing)'),
         scope: z.string().optional().describe('New scope (replaces existing)'),
-        decisions: z.array(z.string()).optional().describe('New decisions list (replaces existing)'),
+        decisions: z
+          .array(z.string())
+          .optional()
+          .describe('New decisions list (replaces existing)'),
         addTasks: z
           .array(z.object({ title: z.string(), description: z.string() }))
           .optional()
           .describe('Tasks to append'),
-        removeTasks: z
-          .array(z.string())
-          .optional()
-          .describe('Task IDs to remove'),
+        removeTasks: z.array(z.string()).optional().describe('Task IDs to remove'),
       }),
       handler: async (params) => {
         try {
@@ -135,10 +145,7 @@ export function createPlanningExtraOps(runtime: AgentRuntime): OpDefinition[] {
       auth: 'write',
       schema: z.object({
         planId: z.string().describe('Plan ID (must be completed with reconciliation data)'),
-        patterns: z
-          .array(z.string())
-          .optional()
-          .describe('Patterns discovered during execution'),
+        patterns: z.array(z.string()).optional().describe('Patterns discovered during execution'),
         antiPatterns: z
           .array(z.string())
           .optional()
@@ -208,10 +215,7 @@ export function createPlanningExtraOps(runtime: AgentRuntime): OpDefinition[] {
       }),
       handler: async (params) => {
         try {
-          const dispatch = planner.getDispatch(
-            params.planId as string,
-            params.taskId as string,
-          );
+          const dispatch = planner.getDispatch(params.planId as string, params.taskId as string);
           return dispatch;
         } catch (err) {
           return { error: (err as Error).message };
@@ -229,9 +233,7 @@ export function createPlanningExtraOps(runtime: AgentRuntime): OpDefinition[] {
         planId: z.string().describe('Plan ID to review'),
         taskId: z.string().optional().describe('Specific task ID (omit to review the whole plan)'),
         reviewer: z.string().describe('Name or ID of reviewer'),
-        outcome: z
-          .enum(['approved', 'rejected', 'needs_changes'])
-          .describe('Review outcome'),
+        outcome: z.enum(['approved', 'rejected', 'needs_changes']).describe('Review outcome'),
         comments: z.string().describe('Review comments'),
       }),
       handler: async (params) => {
@@ -266,7 +268,10 @@ export function createPlanningExtraOps(runtime: AgentRuntime): OpDefinition[] {
         try {
           const olderThanDays = (params.olderThanDays as number) ?? 30;
           const archived = planner.archive(olderThanDays);
-          return { archived: archived.length, plans: archived.map((p) => ({ id: p.id, objective: p.objective })) };
+          return {
+            archived: archived.length,
+            plans: archived.map((p) => ({ id: p.id, objective: p.objective })),
+          };
         } catch (err) {
           return { error: (err as Error).message };
         }
@@ -323,5 +328,391 @@ export function createPlanningExtraOps(runtime: AgentRuntime): OpDefinition[] {
         }
       },
     },
+
+    // ─── Evidence Submission (#148) ──────────────────────────────
+    {
+      name: 'plan_submit_evidence',
+      description:
+        'Submit command output evidence for a task acceptance criterion. Makes playbook verification gates enforceable.',
+      auth: 'write',
+      schema: z.object({
+        planId: z.string().describe('Plan ID'),
+        taskId: z.string().describe('Task ID to submit evidence for'),
+        criterion: z.string().describe('Which acceptance criterion this evidence satisfies'),
+        content: z
+          .string()
+          .describe('Evidence content — command output, URL, file path, or description'),
+        type: z.enum(['command_output', 'url', 'file', 'description']).describe('Evidence type'),
+      }),
+      handler: async (params) => {
+        try {
+          const task = planner.submitEvidence(params.planId as string, params.taskId as string, {
+            criterion: params.criterion as string,
+            content: params.content as string,
+            type: params.type as TaskEvidence['type'],
+          });
+          return {
+            submitted: true,
+            taskId: task.id,
+            evidenceCount: task.evidence?.length ?? 0,
+          };
+        } catch (err) {
+          return { error: (err as Error).message };
+        }
+      },
+    },
+
+    // ─── Verify Task (#148) ─────────────────────────────────────
+    {
+      name: 'plan_verify_task',
+      description:
+        'Check task evidence submitted + reviews passed → mark verified. Returns verification status with details.',
+      auth: 'read',
+      schema: z.object({
+        planId: z.string().describe('Plan ID'),
+        taskId: z.string().describe('Task ID to verify'),
+      }),
+      handler: async (params) => {
+        try {
+          return planner.verifyTask(params.planId as string, params.taskId as string);
+        } catch (err) {
+          return { error: (err as Error).message };
+        }
+      },
+    },
+
+    // ─── Verify Plan (#148) ─────────────────────────────────────
+    {
+      name: 'plan_verify_plan',
+      description:
+        'Check all tasks verified → plan is ready for reconciliation. Returns validation status with per-task issues.',
+      auth: 'read',
+      schema: z.object({
+        planId: z.string().describe('Plan ID to verify'),
+      }),
+      handler: async (params) => {
+        try {
+          return planner.verifyPlan(params.planId as string);
+        } catch (err) {
+          return { error: (err as Error).message };
+        }
+      },
+    },
+
+    // ─── Review Spec (#149) ─────────────────────────────────────
+    {
+      name: 'plan_review_spec',
+      description:
+        'Generate a spec compliance review prompt for a task. Stage 1 of the two-stage subagent review model.',
+      auth: 'read',
+      schema: z.object({
+        planId: z.string().describe('Plan ID'),
+        taskId: z.string().describe('Task ID to generate review prompt for'),
+      }),
+      handler: async (params) => {
+        try {
+          return planner.generateReviewSpec(params.planId as string, params.taskId as string);
+        } catch (err) {
+          return { error: (err as Error).message };
+        }
+      },
+    },
+
+    // ─── Review Quality (#149) ──────────────────────────────────
+    {
+      name: 'plan_review_quality',
+      description:
+        'Generate a code quality review prompt for a task. Stage 2 of the two-stage subagent review model.',
+      auth: 'read',
+      schema: z.object({
+        planId: z.string().describe('Plan ID'),
+        taskId: z.string().describe('Task ID to generate review prompt for'),
+      }),
+      handler: async (params) => {
+        try {
+          return planner.generateReviewQuality(params.planId as string, params.taskId as string);
+        } catch (err) {
+          return { error: (err as Error).message };
+        }
+      },
+    },
+
+    // ─── Review Outcome (#149) ──────────────────────────────────
+    {
+      name: 'plan_review_outcome',
+      description:
+        'Record a subagent review pass/fail result with feedback. Works alongside plan_review for structured review tracking.',
+      auth: 'write',
+      schema: z.object({
+        planId: z.string().describe('Plan ID'),
+        taskId: z.string().describe('Task ID being reviewed'),
+        reviewType: z
+          .enum(['spec', 'quality'])
+          .describe('Type of review — spec compliance or code quality'),
+        reviewer: z.string().describe('Reviewer identifier (subagent name)'),
+        outcome: z.enum(['approved', 'rejected', 'needs_changes']).describe('Review outcome'),
+        comments: z.string().describe('Review comments and feedback'),
+      }),
+      handler: async (params) => {
+        try {
+          const plan = planner.addReview(params.planId as string, {
+            taskId: params.taskId as string,
+            reviewer: `${params.reviewType}-review:${params.reviewer}`,
+            outcome: params.outcome as 'approved' | 'rejected' | 'needs_changes',
+            comments: params.comments as string,
+          });
+          return {
+            recorded: true,
+            totalReviews: plan.reviews?.length ?? 0,
+            taskId: params.taskId,
+            reviewType: params.reviewType,
+            outcome: params.outcome,
+          };
+        } catch (err) {
+          return { error: (err as Error).message };
+        }
+      },
+    },
+
+    // ─── Brainstorm (#150) ──────────────────────────────────────
+    {
+      name: 'plan_brainstorm',
+      description:
+        'Match a playbook for the given intent/text and return its brainstorm sections. ' +
+        'Enforces the brainstorming gate — design must be explored before plan creation.',
+      auth: 'read',
+      schema: z.object({
+        intent: z
+          .enum(['BUILD', 'FIX', 'REVIEW', 'PLAN', 'IMPROVE', 'DELIVER'])
+          .optional()
+          .describe('Detected intent (optional, improves matching)'),
+        text: z.string().describe('Task description text to match against playbooks'),
+      }),
+      handler: async (params) => {
+        try {
+          // Load vault playbooks for matching
+          const vaultEntries = vault.list({ type: 'playbook' });
+          const vaultPlaybooks = vaultEntries
+            .map((e) => entryToPlaybookDefinition(e))
+            .filter((p): p is NonNullable<typeof p> => p !== null);
+
+          const intent = params.intent as
+            | 'BUILD'
+            | 'FIX'
+            | 'REVIEW'
+            | 'PLAN'
+            | 'IMPROVE'
+            | 'DELIVER'
+            | undefined;
+          const result: PlaybookMatchResult = matchPlaybooks(
+            intent,
+            params.text as string,
+            vaultPlaybooks,
+          );
+
+          if (!result.playbook) {
+            return { matched: false, sections: [], playbook: null };
+          }
+
+          // Gather brainstorm sections from matched playbooks
+          const sections = [
+            ...(result.playbook.generic?.brainstormSections ?? []),
+            ...(result.playbook.domain?.brainstormSections ?? []),
+          ];
+
+          return {
+            matched: true,
+            label: result.playbook.label,
+            genericMatch: result.genericMatch ?? null,
+            domainMatch: result.domainMatch ?? null,
+            sections,
+            gates: result.playbook.mergedGates,
+            toolInjections: result.playbook.mergedTools,
+          };
+        } catch (err) {
+          return { error: (err as Error).message };
+        }
+      },
+    },
+
+    // ─── Auto-Reconcile (#151) ──────────────────────────────────
+    {
+      name: 'plan_auto_reconcile',
+      description:
+        'Automated fast-path reconciliation. Checks task completion status, generates drift report automatically. ' +
+        'Returns null if drift is too significant (>2 non-completed tasks).',
+      auth: 'write',
+      schema: z.object({
+        planId: z.string().describe('Plan ID to auto-reconcile'),
+      }),
+      handler: async (params) => {
+        try {
+          const result = planner.autoReconcile(params.planId as string);
+          if (!result) {
+            return {
+              autoReconciled: false,
+              reason: 'Drift too significant for auto-reconciliation — use manual plan_reconcile',
+            };
+          }
+          return {
+            autoReconciled: true,
+            accuracy: result.reconciliation!.accuracy,
+            driftCount: result.reconciliation!.driftItems.length,
+            plan: result,
+          };
+        } catch (err) {
+          return { error: (err as Error).message };
+        }
+      },
+    },
+
+    // ─── Validate Plan (#152) ───────────────────────────────────
+    {
+      name: 'plan_validate',
+      description:
+        'Post-execution validation — checks all tasks final, evidence exists for verification tasks, ' +
+        'no tasks stuck in_progress. Run before reconciliation.',
+      auth: 'read',
+      schema: z.object({
+        planId: z.string().describe('Plan ID to validate'),
+      }),
+      handler: async (params) => {
+        try {
+          return planner.verifyPlan(params.planId as string);
+        } catch (err) {
+          return { error: (err as Error).message };
+        }
+      },
+    },
+
+    // ─── Execution Metrics (#80) ─────────────────────────────────
+    {
+      name: 'plan_execution_metrics',
+      description:
+        'Per-task timing and aggregate execution summary for a plan. Shows duration, status counts, and average task time.',
+      auth: 'read',
+      schema: z.object({
+        planId: z.string().describe('Plan ID to get metrics for'),
+      }),
+      handler: async (params) => {
+        try {
+          const plan = planner.get(params.planId as string);
+          if (!plan) return { error: `Plan not found: ${params.planId}` };
+
+          const taskMetrics = plan.tasks.map((t) => ({
+            id: t.id,
+            title: t.title,
+            status: t.status,
+            startedAt: t.startedAt ?? null,
+            completedAt: t.completedAt ?? null,
+            metrics: t.metrics ?? null,
+          }));
+
+          return {
+            planId: plan.id,
+            status: plan.status,
+            executionSummary: plan.executionSummary ?? null,
+            taskMetrics,
+          };
+        } catch (err) {
+          return { error: (err as Error).message };
+        }
+      },
+    },
+
+    // ─── Record Task Metrics (#80) ──────────────────────────────
+    {
+      name: 'plan_record_task_metrics',
+      description:
+        'Record execution metrics for a task — tool calls, model tier, estimated cost. Merges with existing metrics.',
+      auth: 'write',
+      schema: z.object({
+        planId: z.string().describe('Plan ID'),
+        taskId: z.string().describe('Task ID to record metrics for'),
+        toolCalls: z.number().optional().describe('Number of tool calls made'),
+        modelTier: z.string().optional().describe('Model tier used (e.g., "opus", "sonnet")'),
+        estimatedCostUsd: z.number().optional().describe('Estimated cost in USD'),
+        iterations: z.number().optional().describe('Number of iterations taken'),
+      }),
+      handler: async (params) => {
+        try {
+          const plan = planner.get(params.planId as string);
+          if (!plan) return { error: `Plan not found: ${params.planId}` };
+          const task = plan.tasks.find((t) => t.id === params.taskId);
+          if (!task) return { error: `Task not found: ${params.taskId}` };
+
+          if (!task.metrics) task.metrics = {};
+          if (params.toolCalls !== undefined) task.metrics.toolCalls = params.toolCalls as number;
+          if (params.modelTier !== undefined) task.metrics.modelTier = params.modelTier as string;
+          if (params.estimatedCostUsd !== undefined)
+            task.metrics.estimatedCostUsd = params.estimatedCostUsd as number;
+          if (params.iterations !== undefined)
+            task.metrics.iterations = params.iterations as number;
+
+          task.updatedAt = Date.now();
+          plan.updatedAt = Date.now();
+
+          return {
+            recorded: true,
+            taskId: task.id,
+            metrics: task.metrics,
+          };
+        } catch (err) {
+          return { error: (err as Error).message };
+        }
+      },
+    },
+
+    // ─── Submit Deliverable (#83) ───────────────────────────────
+    {
+      name: 'plan_submit_deliverable',
+      description:
+        'Record a deliverable on a task. Auto-computes SHA-256 hash for file deliverables.',
+      auth: 'write',
+      schema: z.object({
+        planId: z.string().describe('Plan ID'),
+        taskId: z.string().describe('Task ID to attach deliverable to'),
+        type: z.enum(['file', 'vault_entry', 'url']).describe('Deliverable type'),
+        path: z.string().describe('File path, vault entry ID, or URL'),
+      }),
+      handler: async (params) => {
+        try {
+          const task = planner.submitDeliverable(params.planId as string, params.taskId as string, {
+            type: params.type as 'file' | 'vault_entry' | 'url',
+            path: params.path as string,
+          });
+          return {
+            submitted: true,
+            taskId: task.id,
+            deliverableCount: task.deliverables?.length ?? 0,
+          };
+        } catch (err) {
+          return { error: (err as Error).message };
+        }
+      },
+    },
+
+    // ─── Verify Deliverables (#83) ──────────────────────────────
+    {
+      name: 'plan_verify_deliverables',
+      description:
+        'Verify all deliverables for a task — checks file existence + SHA-256 hash match, vault entry existence. Returns stale count.',
+      auth: 'read',
+      schema: z.object({
+        planId: z.string().describe('Plan ID'),
+        taskId: z.string().describe('Task ID to verify deliverables for'),
+      }),
+      handler: async (params) => {
+        try {
+          return planner.verifyDeliverables(
+            params.planId as string,
+            params.taskId as string,
+            vault,
+          );
+        } catch (err) {
+          return { error: (err as Error).message };
+        }
+      },
+    },
   ];
 }

package/src/runtime/playbook-ops.ts

@@ -0,0 +1,169 @@
+/**
+ * Playbook Operations — 5 ops for playbook management.
+ *
+ * Existing ops (moved from core-ops.ts):
+ *   playbook_list, playbook_get, playbook_create
+ *
+ * New ops:
+ *   playbook_match  — match playbooks by intent + text
+ *   playbook_seed   — seed built-in playbooks into vault
+ */
+
+import { z } from 'zod';
+import type { OpDefinition } from '../facades/types.js';
+import type { AgentRuntime } from './types.js';
+import { parsePlaybookFromEntry, validatePlaybook } from '../vault/playbook.js';
+import {
+  matchPlaybooks,
+  seedDefaultPlaybooks,
+  entryToPlaybookDefinition,
+} from '../playbooks/index.js';
+import type { PlaybookIntent } from '../playbooks/index.js';
+
+export function createPlaybookOps(runtime: AgentRuntime): OpDefinition[] {
+  const { vault } = runtime;
+
+  return [
+    // ─── playbook_list ──────────────────────────────────────────────
+    {
+      name: 'playbook_list',
+      description: 'List playbooks stored in the vault, optionally filtered by domain.',
+      auth: 'read',
+      schema: z.object({
+        domain: z.string().optional(),
+        limit: z.number().optional(),
+      }),
+      handler: async (params) => {
+        const entries = vault.list({
+          type: 'playbook',
+          domain: params.domain as string | undefined,
+          limit: (params.limit as number) ?? 50,
+        });
+        const playbooks = entries.map((e) => parsePlaybookFromEntry(e)).filter((p) => p !== null);
+        return { playbooks, count: playbooks.length };
+      },
+    },
+
+    // ─── playbook_get ───────────────────────────────────────────────
+    {
+      name: 'playbook_get',
+      description: 'Get a single playbook by ID, parsed into structured steps.',
+      auth: 'read',
+      schema: z.object({ id: z.string() }),
+      handler: async (params) => {
+        const entry = vault.get(params.id as string);
+        if (!entry) return { error: 'Playbook not found: ' + params.id };
+        if (entry.type !== 'playbook') return { error: 'Entry is not a playbook: ' + params.id };
+        const playbook = parsePlaybookFromEntry(entry);
+        if (!playbook) return { error: 'Failed to parse playbook context: ' + params.id };
+        return playbook;
+      },
+    },
+
+    // ─── playbook_create ────────────────────────────────────────────
+    {
+      name: 'playbook_create',
+      description:
+        'Create a playbook with structured steps. Validates step ordering and builds vault entry automatically.',
+      auth: 'write',
+      schema: z.object({
+        id: z.string().optional(),
+        title: z.string(),
+        domain: z.string(),
+        description: z.string(),
+        steps: z.array(
+          z.object({
+            title: z.string(),
+            description: z.string(),
+            validation: z.string().optional(),
+          }),
+        ),
+        tags: z.array(z.string()).optional().default([]),
+        severity: z.enum(['critical', 'warning', 'suggestion']).optional().default('suggestion'),
+      }),
+      handler: async (params) => {
+        const title = params.title as string;
+        const domain = params.domain as string;
+        const rawSteps = params.steps as Array<{
+          title: string;
+          description: string;
+          validation?: string;
+        }>;
+
+        const steps = rawSteps.map((s, i) => ({ ...s, order: i + 1 }));
+        const id =
+          (params.id as string | undefined) ??
+          `playbook-${domain}-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+
+        const playbook = {
+          id,
+          title,
+          domain,
+          description: params.description as string,
+          steps,
+          tags: params.tags as string[],
+          createdAt: Date.now(),
+          updatedAt: Date.now(),
+        };
+
+        const validation = validatePlaybook(playbook);
+        if (!validation.valid) {
+          return { created: false, id, errors: validation.errors };
+        }
+
+        vault.add({
+          id,
+          type: 'playbook',
+          domain,
+          title,
+          severity:
+            (params.severity as 'critical' | 'warning' | 'suggestion' | undefined) ?? 'suggestion',
+          description: params.description as string,
+          context: JSON.stringify({ steps }),
+          tags: params.tags as string[],
+        });
+
+        return { created: true, id, steps: steps.length };
+      },
+    },
+
+    // ─── playbook_match (NEW) ───────────────────────────────────────
+    {
+      name: 'playbook_match',
+      description:
+        'Match playbooks by intent and text. Combines vault-stored and built-in playbooks, returns best match with merged gates/tasks/tools.',
+      auth: 'read',
+      schema: z.object({
+        intent: z
+          .enum(['BUILD', 'FIX', 'REVIEW', 'PLAN', 'IMPROVE', 'DELIVER'])
+          .optional()
+          .describe('Plan intent for matching'),
+        text: z.string().describe('Plan objective + scope text to match against'),
+      }),
+      handler: async (params) => {
+        const intent = params.intent as PlaybookIntent | undefined;
+        const text = params.text as string;
+
+        // Load vault playbooks and convert to PlaybookDefinition
+        const vaultEntries = vault.list({ type: 'playbook', limit: 200 });
+        const vaultPlaybooks = vaultEntries
+          .map((e) => entryToPlaybookDefinition(e))
+          .filter((p): p is NonNullable<typeof p> => p !== null);
+
+        const result = matchPlaybooks(intent, text, vaultPlaybooks);
+        return result;
+      },
+    },
+
+    // ─── playbook_seed (NEW) ────────────────────────────────────────
+    {
+      name: 'playbook_seed',
+      description:
+        'Seed built-in playbooks into the vault. Idempotent — skips existing playbooks. Seeds 6 generic playbooks (TDD, brainstorming, code-review, subagent-execution, debugging, verification).',
+      auth: 'write',
+      handler: async () => {
+        return seedDefaultPlaybooks(vault);
+      },
+    },
+  ];
+}