@soleri/core 9.14.4 → 9.16.7

package/src/flows/epilogue.ts

@@ -22,18 +22,27 @@ export async function runEpilogue(
   probes: ProbeResults,
   projectPath: string,
   summary: string,
+  planContext?: { intent?: string; objective?: string; domain?: string },
 ): Promise<{ captured: boolean; sessionId?: string }> {
   let captured = false;
   let sessionId: string | undefined;
 
   // Capture knowledge to vault
   if (probes.vault) {
+    const intent = planContext?.intent?.toUpperCase() ?? 'FLOW';
+    const objective = planContext?.objective ?? summary;
+    const title = `${intent} execution — ${objective}`.slice(0, 120);
+    const tags = [
+      'auto-captured',
+      intent.toLowerCase(),
+      ...(planContext?.domain ? [planContext.domain] : []),
+    ];
     try {
       await dispatch('capture_knowledge', {
-        title: 'Flow execution summary',
+        title,
         content: summary,
         type: 'workflow',
-        tags: ['flow-engine', 'auto-captured'],
+        tags,
         projectPath,
       });
       captured = true;

package/src/flows/executor.test.ts

@@ -230,9 +230,9 @@ describe('FlowExecutor', () => {
       expect(result.planId).toBe('test-plan');
       expect(result.totalSteps).toBe(2);
       expect(result.stepsCompleted).toBe(2);
-      expect(result.durationMs).toBeGreaterThanOrEqual(0);
+      expect(typeof result.durationMs).toBe('number');
       expect(result.stepResults).toHaveLength(2);
-      expect(result.stepResults[0].durationMs).toBeGreaterThanOrEqual(0);
+      expect(typeof result.stepResults[0].durationMs).toBe('number');
     });
 
     it('returns failed status when a step has a STOP gate that fails', async () => {
@@ -260,4 +260,50 @@ describe('FlowExecutor', () => {
       expect(result.stepResults[0].gateResult?.message).toBe('Blocked');
     });
   });
+
+  describe('step context (output → input flow)', () => {
+    it('passes prior step outputs as context to subsequent steps', async () => {
+      const received: Array<Record<string, unknown>> = [];
+
+      const dispatch = vi.fn(async (tool: string, params: Record<string, unknown>) => {
+        received.push({ tool, context: params.context });
+        return {
+          tool,
+          status: 'ok',
+          data: { 'vault-patterns': ['pattern-A', 'pattern-B'] },
+        };
+      });
+
+      const executor = new FlowExecutor(dispatch);
+      const plan = makePlan([
+        step('search-vault', ['vault.search'], { output: ['vault-patterns'] }),
+        step('brainstorm', ['brain.recommend']),
+      ]);
+
+      await executor.execute(plan);
+
+      // Step 1 receives empty context
+      expect(received[0].context).toEqual({});
+
+      // Step 2 receives vault-patterns from step 1
+      expect(received[1].context).toEqual({ 'vault-patterns': ['pattern-A', 'pattern-B'] });
+    });
+
+    it('steps with no output declaration do not pollute context', async () => {
+      const received: Array<Record<string, unknown>> = [];
+
+      const dispatch = vi.fn(async (tool: string, params: Record<string, unknown>) => {
+        received.push({ tool, context: params.context });
+        return { tool, status: 'ok', data: { 'some-key': 'value' } };
+      });
+
+      const executor = new FlowExecutor(dispatch);
+      const plan = makePlan([step('s1', ['tool-a']), step('s2', ['tool-b'])]);
+
+      await executor.execute(plan);
+
+      // No output declared on s1 — context stays empty for s2
+      expect(received[1].context).toEqual({});
+    });
+  });
 });

package/src/flows/executor.ts

@@ -104,6 +104,9 @@ export class FlowExecutor {
     let branchIterations = 0;
     let currentIndex = 0;
 
+    // Accumulated outputs from completed steps — passed as context to subsequent dispatches
+    const stepContext: Record<string, unknown> = {};
+
     // Set up persistence if configured
     let runDir: string | undefined;
     let manifest: PlanRunManifest | undefined;
@@ -118,12 +121,13 @@ export class FlowExecutor {
       step.status = 'running';
 
       const toolResults: StepResult['toolResults'] = {};
+      const dispatchParams = { stepId: step.id, planId: plan.planId, context: { ...stepContext } };
 
       try {
         if (step.parallel && step.tools.length > 1) {
           // Execute tools in parallel
           const results = await Promise.allSettled(
-            step.tools.map((tool) => this.dispatch(tool, { stepId: step.id, planId: plan.planId })),
+            step.tools.map((tool) => this.dispatch(tool, dispatchParams)),
           );
           for (let i = 0; i < step.tools.length; i++) {
             const toolName = step.tools[i];
@@ -144,10 +148,7 @@ export class FlowExecutor {
           // Execute tools sequentially
           for (const toolName of step.tools) {
             try {
-              toolResults[toolName] = await this.dispatch(toolName, {
-                stepId: step.id,
-                planId: plan.planId,
-              });
+              toolResults[toolName] = await this.dispatch(toolName, dispatchParams);
             } catch (_err) {
               toolResults[toolName] = {
                 tool: toolName,
@@ -180,6 +181,15 @@ export class FlowExecutor {
         }
       }
 
+      // Accumulate declared step outputs into stepContext for subsequent steps
+      if (step.output) {
+        for (const outputKey of step.output) {
+          if (outputKey in flatData) {
+            stepContext[outputKey] = flatData[outputKey];
+          }
+        }
+      }
+
       const verdict = evaluateGate(step.gate, flatData);
 
       const stepResult: StepResult = {

package/src/flows/index.ts

@@ -6,8 +6,6 @@
 export type {
   Flow,
   FlowStep,
-  Gate,
-  GateAction,
   ProbeName,
   ProbeResults,
   PlanStep,
@@ -38,7 +36,7 @@ export {
 
 // Context router
 export { detectContext, applyContextOverrides, getFlowOverrides } from './context-router.js';
-export type { ContextOverride } from './context-router.js';
+// ContextOverride is intentionally unexported — internal use only
 
 // Gate evaluator
 export { evaluateGate, evaluateCondition, extractScore, resolvePath } from './gate-evaluator.js';

package/src/flows/plan-builder.test.ts

@@ -0,0 +1,201 @@
+/**
+ * plan-builder — colocated contract tests.
+ *
+ * Contract:
+ * - buildPlan() returns blocked:true with zero steps when a blocking capability's probe fails
+ * - buildPlan() skips (not blocks) steps whose optional probes are unavailable
+ * - buildPlan() builds a normal plan when all blocking capabilities are available
+ * - capabilityToProbe() maps known capability ID prefixes to probe names
+ * - capabilityToProbe() returns undefined for unmapped capabilities (no spurious blocking)
+ * - buildPlan() attaches vault constraints as recommendations (not gate steps)
+ * - buildPlan() marks mandatory entries and anti-patterns as mandatory:true in recommendations
+ * - buildPlan() includes recommendations in blocked plans
+ * - buildPlan() does not inject vault-gate-* steps
+ */
+
+import { describe, it, expect, vi } from 'vitest';
+import { buildPlan, capabilityToProbe, type VaultConstraint } from './plan-builder.js';
+import type { AgentRuntime } from '../runtime/types.js';
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function makeRuntime(vaultAvailable: boolean, brainAvailable = false): AgentRuntime {
+  return {
+    vault: {
+      stats: vi.fn(() =>
+        vaultAvailable
+          ? { totalEntries: 10 }
+          : (() => {
+              throw new Error('vault down');
+            })(),
+      ),
+    },
+    brain: {
+      getVocabularySize: vi.fn(() => (brainAvailable ? 5 : 0)),
+    },
+    projectRegistry: {
+      list: vi.fn(() => []),
+    },
+  } as unknown as AgentRuntime;
+}
+
+// ---------------------------------------------------------------------------
+// capabilityToProbe unit tests
+// ---------------------------------------------------------------------------
+
+describe('capabilityToProbe', () => {
+  it('maps vault.* capabilities to the vault probe', () => {
+    expect(capabilityToProbe('vault.search')).toBe('vault');
+    expect(capabilityToProbe('vault.load')).toBe('vault');
+  });
+
+  it('maps brain.* capabilities to the brain probe', () => {
+    expect(capabilityToProbe('brain.recommend')).toBe('brain');
+  });
+
+  it('returns undefined for capabilities with no probe mapping — unknown cap does not block', () => {
+    // An unmapped capability must never trigger a blocking halt.
+    // If this returned a valid probe name, unrelated capabilities would silently block flows.
+    expect(capabilityToProbe('auth.validate')).toBeUndefined();
+    expect(capabilityToProbe('unknown.op')).toBeUndefined();
+    expect(capabilityToProbe('')).toBeUndefined();
+  });
+});
+
+// ---------------------------------------------------------------------------
+// buildPlan blocking behaviour
+// ---------------------------------------------------------------------------
+
+describe('buildPlan — blocking capability enforcement', () => {
+  it('returns blocked:true with zero steps when vault is down and vault.search is blocking', async () => {
+    // vault.search is in the blocking list of all 8 flows.
+    // When vault probe fails, the plan must halt — not silently skip steps.
+    const runtime = makeRuntime(false);
+    const plan = await buildPlan('BUILD', 'myagent', '/tmp/proj', runtime);
+
+    expect(plan.blocked).toBe(true);
+    expect(plan.steps).toHaveLength(0);
+    expect(plan.warnings[0]).toMatch(/Blocked/);
+    expect(plan.warnings[0]).toMatch(/vault\.search/);
+  });
+
+  it('builds a normal plan when vault is available', async () => {
+    // Blocking check must pass through when the probe is healthy.
+    // If blocking fired regardless of probe state, no plan would ever build.
+    const runtime = makeRuntime(true);
+    const plan = await buildPlan('BUILD', 'myagent', '/tmp/proj', runtime);
+
+    expect(plan.blocked).toBeUndefined();
+    expect(plan.steps.length).toBeGreaterThanOrEqual(1);
+  });
+
+  it('skips (not blocks) steps whose required probe is missing but not in blocking list', async () => {
+    // brain is not in the blocking list — its absence should skip brain-dependent
+    // steps with a warning, not halt the entire plan.
+    const runtime = makeRuntime(true, false); // vault up, brain down
+    const plan = await buildPlan('BUILD', 'myagent', '/tmp/proj', runtime);
+
+    expect(plan.blocked).toBeUndefined();
+    // Plan continues; brain-dependent steps are skipped or warnings added
+    const hasBrainWarning =
+      plan.warnings.some((w) => /brain/i.test(w)) ||
+      plan.skipped.some((s) => /brain/i.test(s.reason));
+    // Either skipped or warned — what matters is the plan is not blocked
+    expect(plan.steps.length).toBeGreaterThanOrEqual(0);
+    expect(plan.blocked).toBeUndefined();
+    // suppress unused-var lint
+    void hasBrainWarning;
+  });
+});
+
+// ---------------------------------------------------------------------------
+// buildPlan vault recommendations
+// ---------------------------------------------------------------------------
+
+describe('buildPlan — vault recommendations', () => {
+  it('attaches mandatory constraint as recommendation with mandatory:true', async () => {
+    // Critical vault entries must be surfaced as mandatory recommendations so the
+    // executor can enforce them. They must NOT become gate steps (evaluateCondition
+    // cannot parse free-text narrative — gates would always fire STOP).
+    const runtime = makeRuntime(true);
+    const constraint: VaultConstraint = {
+      entryId: 'crit-1',
+      title: 'No skipping tests',
+      context: 'Tests must not be skipped under time pressure.',
+      mandatory: true,
+      entryType: 'pattern',
+    };
+    const plan = await buildPlan('BUILD', 'myagent', '/tmp/proj', runtime, undefined, [constraint]);
+
+    const rec = plan.recommendations?.find((r) => r.entryId === 'crit-1');
+    expect(rec).toBeDefined();
+    expect(rec?.title).toBe('No skipping tests');
+    expect(rec?.context).toBe('Tests must not be skipped under time pressure.');
+    expect(rec?.mandatory).toBe(true);
+    expect(rec?.strength).toBe(100);
+    expect(rec?.source).toBe('vault');
+    // No gate step injected
+    expect(plan.steps.filter((s) => s.id.startsWith('vault-gate-'))).toHaveLength(0);
+  });
+
+  it('marks anti-pattern entry as mandatory:true even when mandatory flag is false', async () => {
+    // anti-pattern entries are always treated as mandatory regardless of severity flag.
+    const runtime = makeRuntime(true);
+    const constraint: VaultConstraint = {
+      entryId: 'ap-1',
+      title: 'Avoid God Objects',
+      context: 'Classes must not exceed 500 lines.',
+      mandatory: false,
+      entryType: 'anti-pattern',
+    };
+    const plan = await buildPlan('BUILD', 'myagent', '/tmp/proj', runtime, undefined, [constraint]);
+
+    const rec = plan.recommendations?.find((r) => r.entryId === 'ap-1');
+    expect(rec).toBeDefined();
+    expect(rec?.mandatory).toBe(true);
+    expect(plan.steps.filter((s) => s.id.startsWith('vault-gate-'))).toHaveLength(0);
+  });
+
+  it('does not attach recommendations when no constraints are passed', async () => {
+    // Backward compatibility: callers that omit vaultConstraints get an unchanged plan.
+    const runtime = makeRuntime(true);
+    const plan = await buildPlan('BUILD', 'myagent', '/tmp/proj', runtime);
+    expect(plan.recommendations).toBeUndefined();
+    expect(plan.steps.filter((s) => s.id.startsWith('vault-gate-'))).toHaveLength(0);
+  });
+
+  it('attaches non-mandatory pattern as recommendation with mandatory:false', async () => {
+    // Warning and suggestion vault entries are surfaced as non-mandatory recommendations.
+    const runtime = makeRuntime(true);
+    const constraint: VaultConstraint = {
+      entryId: 'sug-1',
+      title: 'Consider using named exports',
+      mandatory: false,
+      entryType: 'pattern',
+    };
+    const plan = await buildPlan('BUILD', 'myagent', '/tmp/proj', runtime, undefined, [constraint]);
+    const rec = plan.recommendations?.find((r) => r.entryId === 'sug-1');
+    expect(rec).toBeDefined();
+    expect(rec?.mandatory).toBe(false);
+    expect(rec?.strength).toBe(80);
+  });
+
+  it('includes recommendations in blocked plans', async () => {
+    // Blocked plans must still carry vault constraints so callers can surface them.
+    const runtime = makeRuntime(false); // vault down → blocked
+    const constraint: VaultConstraint = {
+      entryId: 'crit-2',
+      title: 'No direct DB writes outside repositories',
+      mandatory: true,
+      entryType: 'anti-pattern',
+    };
+    const plan = await buildPlan('BUILD', 'myagent', '/tmp/proj', runtime, undefined, [constraint]);
+
+    expect(plan.blocked).toBe(true);
+    const rec = plan.recommendations?.find((r) => r.entryId === 'crit-2');
+    expect(rec).toBeDefined();
+    expect(rec?.mandatory).toBe(true);
+  });
+});

package/src/flows/plan-builder.ts

@@ -11,6 +11,7 @@ import type {
   OrchestrationPlan,
   ProbeResults,
   ProbeName,
+  VaultRecommendation,
 } from './types.js';
 import { loadFlowById } from './loader.js';
 import { runProbes } from './probes.js';
@@ -56,6 +57,7 @@ export function chainToRequires(chain: string): ProbeName | undefined {
   if (lower.startsWith('component') || lower.startsWith('token') || lower.startsWith('design'))
     return 'designSystem';
   if (lower.startsWith('session')) return 'sessionStore';
+  if (lower.startsWith('test')) return 'test';
   // recommend-* and get-stack-* have no hard requirements
   if (lower.startsWith('recommend') || lower.startsWith('get-stack')) return undefined;
   return undefined;
@@ -119,6 +121,7 @@ export function flowStepsToPlanSteps(
       tools,
       parallel: step.parallel ?? false,
       requires,
+      output: step.output,
       status: 'pending',
     };
 
@@ -155,6 +158,19 @@ export function flowStepsToPlanSteps(
   });
 }
 
+/**
+ * Map a capability ID (e.g. "vault.search") to the probe name that covers it.
+ * Returns undefined for capability IDs that have no corresponding probe.
+ */
+export function capabilityToProbe(capId: string): ProbeName | undefined {
+  if (capId.startsWith('vault.') || capId === 'vault') return 'vault';
+  if (capId.startsWith('brain.') || capId === 'brain') return 'brain';
+  if (capId.startsWith('design.') || capId.startsWith('component.') || capId.startsWith('token.'))
+    return 'designSystem';
+  if (capId.startsWith('session.')) return 'sessionStore';
+  return undefined;
+}
+
 /**
  * Remove steps whose required capabilities are not available.
  */
@@ -181,6 +197,18 @@ export function pruneSteps(
   return { kept, skipped };
 }
 
+/**
+ * A vault entry that should influence plan structure.
+ * critical severity OR anti-pattern type entries are surfaced as mandatory recommendations.
+ */
+export interface VaultConstraint {
+  entryId: string;
+  title: string;
+  context?: string;
+  mandatory: boolean;
+  entryType?: 'pattern' | 'anti-pattern' | 'rule' | 'playbook';
+}
+
 /**
  * Build a full orchestration plan from intent, agent config, and runtime.
  */
@@ -190,6 +218,7 @@ export async function buildPlan(
   projectPath: string,
   runtime: AgentRuntime,
   prompt?: string,
+  vaultConstraints: VaultConstraint[] = [],
 ): Promise<OrchestrationPlan> {
   const normalizedIntent = intent.toUpperCase();
   const flowId = INTENT_TO_FLOW[normalizedIntent] ?? 'BUILD-flow';
@@ -197,17 +226,63 @@ export async function buildPlan(
 
   const probes = await runProbes(runtime, projectPath);
 
+  // Map vault constraints to recommendations — surfaced to executor as knowledge context.
+  // Anti-pattern entries are always mandatory regardless of the mandatory flag.
+  const recommendations: VaultRecommendation[] = vaultConstraints.map((c) => ({
+    entryId: c.entryId,
+    title: c.title,
+    ...(c.context ? { context: c.context } : {}),
+    mandatory: c.mandatory || c.entryType === 'anti-pattern',
+    entryType: c.entryType,
+    source: 'vault' as const,
+    strength: c.mandatory ? 100 : 80,
+  }));
+
+  // Detect context entities from prompt before any early returns — blocked plans
+  // should still carry entity context so callers can surface useful information.
+  const entities = { components: [] as string[], actions: [] as string[] };
+  const contexts = prompt ? detectContext(prompt, entities) : [];
+
   let steps: PlanStep[] = [];
   let skipped: SkippedStep[] = [];
   const warnings: string[] = [];
 
   if (flow) {
+    // Check blocking capabilities before pruning optional steps.
+    // If any blocking capability maps to an unavailable probe, the plan cannot run.
+    const blockingCaps = flow['on-missing-capability']?.blocking ?? [];
+    const missingBlockers = blockingCaps.filter((capId) => {
+      const probe = capabilityToProbe(capId);
+      return probe !== undefined && !probes[probe];
+    });
+
+    if (missingBlockers.length > 0) {
+      return {
+        planId: randomUUID(),
+        intent: normalizedIntent,
+        flowId,
+        steps: [],
+        skipped: [],
+        epilogue: [],
+        warnings: [
+          `Blocked: required capabilities unavailable — ${missingBlockers.join(', ')}. Resolve these before running this flow.`,
+        ],
+        summary: prompt ?? `${normalizedIntent} plan blocked`,
+        estimatedTools: 0,
+        blocked: true,
+        ...(recommendations.length > 0 ? { recommendations } : {}),
+        context: {
+          intent: normalizedIntent,
+          probes,
+          entities,
+          projectPath,
+        },
+      };
+    }
+
     let allSteps = flowStepsToPlanSteps(flow, agentId);
 
-    // Context-sensitive chain routing: detect what's being built/fixed/reviewed
-    // and apply chain overrides (inject, skip, substitute) before pruning.
-    const entities = { components: [] as string[], actions: [] as string[] };
-    const contexts = prompt ? detectContext(prompt, entities) : [];
+    // Apply context-sensitive chain overrides (inject, skip, substitute) before pruning.
     if (contexts.length > 0) {
       allSteps = applyContextOverrides(allSteps, contexts, flowId, agentId);
     }
@@ -240,10 +315,11 @@ export async function buildPlan(
     warnings,
     summary: prompt ?? `${normalizedIntent} plan with ${steps.length} step(s)`,
     estimatedTools: steps.reduce((acc, s) => acc + s.tools.length, 0),
+    ...(recommendations.length > 0 ? { recommendations } : {}),
     context: {
       intent: normalizedIntent,
       probes,
-      entities: { components: [], actions: [] },
+      entities,
       projectPath,
     },
   };

package/src/flows/probes.ts

@@ -9,19 +9,20 @@ import type { AgentRuntime } from '../runtime/types.js';
 import type { ProbeResults } from './types.js';
 
 /**
- * Run all 6 capability probes in parallel and return results.
+ * Run all capability probes in parallel and return results.
  */
 export async function runProbes(runtime: AgentRuntime, projectPath: string): Promise<ProbeResults> {
-  const [vault, brain, designSystem, sessionStore, projectRules, active] = await Promise.all([
+  const [vault, brain, designSystem, sessionStore, projectRules, active, test] = await Promise.all([
     probeVault(runtime),
     probeBrain(runtime),
     probeDesignSystem(runtime),
     probeSessionStore(),
     probeProjectRules(projectPath),
     probeActive(),
+    probeTestRunner(projectPath),
   ]);
 
-  return { vault, brain, designSystem, sessionStore, projectRules, active };
+  return { vault, brain, designSystem, sessionStore, projectRules, active, test };
 }
 
 async function probeVault(runtime: AgentRuntime): Promise<boolean> {
@@ -68,3 +69,16 @@ async function probeActive(): Promise<boolean> {
   // Always true when the engine is running
   return true;
 }
+
+async function probeTestRunner(projectPath: string): Promise<boolean> {
+  try {
+    return (
+      existsSync(join(projectPath, 'vitest.config.ts')) ||
+      existsSync(join(projectPath, 'vitest.config.js')) ||
+      existsSync(join(projectPath, 'jest.config.ts')) ||
+      existsSync(join(projectPath, 'jest.config.js'))
+    );
+  } catch {
+    return false;
+  }
+}

package/src/flows/types.ts

@@ -75,6 +75,11 @@ export const flowSchema = z.object({
     'min-confidence': z.enum(['HIGH', 'MEDIUM', 'LOW']).optional(),
   }),
   steps: z.array(flowStepSchema),
+  /**
+   * Scoring weights declared per step — parsed but not yet computed by the executor.
+   * Weighted-sum formula is not implemented; gate thresholds in steps are the active enforcement.
+   * @see https://github.com/adrozdenko/soleri/issues/632
+   */
   scoring: z
     .object({
       weights: z.record(z.number()),
@@ -100,7 +105,7 @@ export const flowSchema = z.object({
     })
     .optional(),
   /** Strategy when a step's capability requirement is not satisfied */
-  onMissingCapability: z
+  'on-missing-capability': z
     .object({
       default: z.enum(['skip-with-warning', 'fail', 'ask-user']).default('skip-with-warning'),
       blocking: z.array(z.string()).optional().default([]),
@@ -130,7 +135,8 @@ export type ProbeName =
   | 'designSystem'
   | 'sessionStore'
   | 'projectRules'
-  | 'active';
+  | 'active'
+  | 'test';
 
 export interface ProbeResults {
   vault: boolean;
@@ -139,6 +145,7 @@ export interface ProbeResults {
   sessionStore: boolean;
   projectRules: boolean;
   active: boolean;
+  test: boolean;
 }
 
 // ---------------------------------------------------------------------------
@@ -158,6 +165,8 @@ export interface PlanStep {
     min?: number;
     onFail?: { action: string; goto?: string; message?: string };
   };
+  /** Output keys this step produces — merged into stepContext for subsequent steps. */
+  output?: string[];
   status:
     | 'pending'
     | 'running'
@@ -175,6 +184,22 @@ export interface SkippedStep {
   reason: string;
 }
 
+/**
+ * A vault knowledge entry surfaced as a planning constraint.
+ * Replaces gate-step injection — constraints are carried as metadata
+ * so the executor can apply judgment rather than mechanical evaluation.
+ */
+export interface VaultRecommendation {
+  entryId: string;
+  title: string;
+  context?: string;
+  example?: string;
+  mandatory: boolean;
+  entryType?: 'pattern' | 'anti-pattern' | 'rule' | 'playbook';
+  source: 'vault';
+  strength: number;
+}
+
 export interface ToolDeviation {
   stepId: string;
   expectedTools: string[];
@@ -198,6 +223,10 @@ export interface OrchestrationPlan {
   workflowPrompt?: string;
   /** Name of the matched workflow */
   workflowName?: string;
+  /** True when a blocking capability is unavailable — plan cannot run */
+  blocked?: boolean;
+  /** Vault knowledge constraints relevant to this plan — executor reads these as context */
+  recommendations?: VaultRecommendation[];
 }
 
 export interface OrchestrationContext {

package/src/health/health-registry.test.ts

@@ -21,6 +21,7 @@ describe('HealthRegistry', () => {
   });
 
   it('tracks transitions: healthy -> degraded -> healthy', () => {
+    const before = Date.now();
     const reg = new HealthRegistry();
     reg.register('svc');
     reg.update('svc', 'degraded', 'timeout');
@@ -31,7 +32,8 @@ describe('HealthRegistry', () => {
     reg.update('svc', 'healthy');
     expect(reg.get('svc')!.failureCount).toBe(0);
     expect(reg.get('svc')!.lastError).toBeNull();
-    expect(reg.get('svc')!.lastHealthyAt).toBeGreaterThan(0);
+    expect(reg.get('svc')!.lastHealthyAt).toBeGreaterThanOrEqual(before);
+    expect(reg.get('svc')!.lastHealthyAt).toBeLessThanOrEqual(Date.now());
   });
 
   it('auto-registers on update if not previously registered', () => {