@soleri/core 9.8.0 → 9.9.0

package/src/runtime/facades/curator-facade.test.ts

@@ -3,24 +3,43 @@ import { createCuratorFacadeOps } from './curator-facade.js';
 import type { OpDefinition } from '../../facades/types.js';
 import type { AgentRuntime } from '../types.js';
 
+interface MockLinkManager {
+  backfillLinks: ReturnType<typeof vi.fn>;
+  getOrphans: ReturnType<typeof vi.fn>;
+}
+
+function getLinkManager(rt: AgentRuntime): MockLinkManager {
+  return (rt as unknown as { linkManager: MockLinkManager }).linkManager;
+}
+
 function mockRuntime(): AgentRuntime {
   return {
     curator: {
-      getStatus: vi.fn().mockReturnValue({ initialized: true, entriesGroomed: 5 }),
+      getStatus: vi
+        .fn()
+        .mockReturnValue({ initialized: true, entriesGroomed: 5, tables: { entries: 100 } }),
       detectDuplicates: vi.fn().mockReturnValue([]),
       detectContradictions: vi.fn(),
       getContradictions: vi.fn().mockReturnValue([]),
       resolveContradiction: vi.fn().mockReturnValue({ resolved: true }),
       groomEntry: vi.fn().mockReturnValue({ groomed: true }),
       groomAll: vi.fn().mockReturnValue({ groomed: 10 }),
-      consolidate: vi.fn().mockReturnValue({ duplicates: 0, stale: 0 }),
-      healthAudit: vi.fn().mockReturnValue({ score: 85 }),
+      consolidate: vi.fn().mockReturnValue({ duplicates: 0, stale: 0, durationMs: 10 }),
+      healthAudit: vi.fn().mockReturnValue({
+        score: 85,
+        metrics: { coverage: 1, freshness: 1, quality: 1, tagHealth: 1 },
+        recommendations: [],
+      }),
       getVersionHistory: vi.fn().mockReturnValue([]),
       recordSnapshot: vi.fn().mockReturnValue({ recorded: true }),
       getQueueStats: vi.fn().mockReturnValue({ total: 20, groomed: 15 }),
       enrichMetadata: vi.fn().mockReturnValue({ enriched: true }),
       detectContradictionsHybrid: vi.fn().mockReturnValue([]),
     },
+    linkManager: {
+      backfillLinks: vi.fn().mockReturnValue({ processed: 5, linksCreated: 3, durationMs: 50 }),
+      getOrphans: vi.fn().mockReturnValue([]),
+    },
     jobQueue: {
       enqueue: vi.fn().mockImplementation((_type, _params) => `job-${Date.now()}`),
       getStats: vi.fn().mockReturnValue({ pending: 0, running: 0 }),
@@ -91,7 +110,7 @@ describe('createCuratorFacadeOps', () => {
   describe('curator_status', () => {
     it('returns curator status', async () => {
       const result = await findOp(ops, 'curator_status').handler({});
-      expect(result).toEqual({ initialized: true, entriesGroomed: 5 });
+      expect(result).toEqual({ initialized: true, entriesGroomed: 5, tables: { entries: 100 } });
     });
   });
 
@@ -168,15 +187,18 @@ describe('createCuratorFacadeOps', () => {
   });
 
   describe('curator_consolidate', () => {
-    it('consolidates with default params', async () => {
+    it('consolidates with default params and includes linksCreated', async () => {
       const result = await findOp(ops, 'curator_consolidate').handler({});
-      expect(result).toEqual({ duplicates: 0, stale: 0 });
+      expect(result).toEqual({ duplicates: 0, stale: 0, durationMs: 10, linksCreated: 3 });
       expect(runtime.curator.consolidate).toHaveBeenCalledWith({
         dryRun: undefined,
         staleDaysThreshold: undefined,
         duplicateThreshold: undefined,
         contradictionThreshold: undefined,
       });
+      expect(getLinkManager(runtime).backfillLinks).toHaveBeenCalledWith({
+        dryRun: undefined,
+      });
     });
 
     it('consolidates with custom params', async () => {
@@ -193,12 +215,68 @@ describe('createCuratorFacadeOps', () => {
         contradictionThreshold: 0.3,
       });
     });
+
+    it('returns linksCreated: 0 when linkManager throws', async () => {
+      const lm = getLinkManager(runtime);
+      vi.mocked(lm.backfillLinks).mockImplementation(() => {
+        throw new Error('link module unavailable');
+      });
+      const result = (await findOp(ops, 'curator_consolidate').handler({})) as Record<
+        string,
+        unknown
+      >;
+      expect(result.linksCreated).toBe(0);
+    });
   });
 
   describe('curator_health_audit', () => {
-    it('returns audit result', async () => {
-      const result = await findOp(ops, 'curator_health_audit').handler({});
-      expect(result).toEqual({ score: 85 });
+    it('returns audit result with orphan metrics', async () => {
+      const result = (await findOp(ops, 'curator_health_audit').handler({})) as Record<
+        string,
+        unknown
+      >;
+      expect(result.score).toBe(85);
+      expect(result.orphanCount).toBe(0);
+      expect(result.orphanPercentage).toBe(0);
+    });
+
+    it('reduces quality when orphan percentage > 10%', async () => {
+      const lm = getLinkManager(runtime);
+      // 15 orphans out of 100 entries = 15%
+      vi.mocked(lm.getOrphans).mockReturnValue(
+        Array.from({ length: 15 }, (_, i) => ({
+          id: `orphan-${i}`,
+          title: `o${i}`,
+          type: 'pattern',
+          domain: 'test',
+        })),
+      );
+      const result = (await findOp(ops, 'curator_health_audit').handler({})) as Record<
+        string,
+        unknown
+      >;
+      expect(result.orphanCount).toBe(15);
+      expect(result.orphanPercentage).toBe(15);
+      const metrics = result.metrics as Record<string, number>;
+      expect(metrics.quality).toBe(0.7); // 1 * 0.7
+      expect(
+        (result.recommendations as string[]).some(
+          (r: string) => r.includes('orphan entries') && r.includes('no links'),
+        ),
+      ).toBe(true);
+    });
+
+    it('succeeds when linkManager throws', async () => {
+      const lm = getLinkManager(runtime);
+      vi.mocked(lm.getOrphans).mockImplementation(() => {
+        throw new Error('link module unavailable');
+      });
+      const result = (await findOp(ops, 'curator_health_audit').handler({})) as Record<
+        string,
+        unknown
+      >;
+      expect(result.orphanCount).toBe(0);
+      expect(result.orphanPercentage).toBe(0);
     });
   });
 

package/src/runtime/facades/curator-facade.ts

@@ -108,7 +108,7 @@ export function createCuratorFacadeOps(runtime: AgentRuntime): OpDefinition[] {
     {
       name: 'curator_consolidate',
       description:
-        'Consolidate vault — find duplicates, stale entries, contradictions. Dry-run by default.',
+        'Consolidate vault — find duplicates, stale entries, contradictions, and backfill Zettelkasten links for orphan entries. Dry-run by default.',
       auth: 'write',
       schema: z.object({
         dryRun: z.boolean().optional().describe('Default true. Set false to apply mutations.'),
@@ -126,21 +126,77 @@ export function createCuratorFacadeOps(runtime: AgentRuntime): OpDefinition[] {
           .describe('Contradiction threshold. Default 0.4.'),
       }),
       handler: async (params) => {
-        return curator.consolidate({
+        const result = curator.consolidate({
           dryRun: params.dryRun as boolean | undefined,
           staleDaysThreshold: params.staleDaysThreshold as number | undefined,
           duplicateThreshold: params.duplicateThreshold as number | undefined,
           contradictionThreshold: params.contradictionThreshold as number | undefined,
         });
+
+        // Backfill Zettelkasten links for orphan entries
+        let linksCreated = 0;
+        try {
+          const { linkManager } = runtime;
+          if (linkManager) {
+            const backfillResult = linkManager.backfillLinks({
+              dryRun: params.dryRun as boolean | undefined,
+            });
+            linksCreated = backfillResult.linksCreated;
+          }
+        } catch {
+          // Link module unavailable — degrade gracefully
+        }
+
+        return { ...result, linksCreated };
       },
     },
     {
       name: 'curator_health_audit',
       description:
-        'Audit vault health — score (0-100), coverage, freshness, quality, tag health, recommendations.',
+        'Audit vault health — score (0-100), coverage, freshness, quality, tag health, orphan count, recommendations.',
       auth: 'read',
       handler: async () => {
-        return curator.healthAudit();
+        const result = curator.healthAudit();
+
+        // Enrich with orphan statistics from link manager
+        let orphanCount = 0;
+        let orphanPercentage = 0;
+        try {
+          const { linkManager } = runtime;
+          if (linkManager) {
+            // getOrphans returns up to limit entries; use a high limit to count all
+            const orphans = linkManager.getOrphans(10000);
+            orphanCount = orphans.length;
+            // Compute percentage against total entries via curator status
+            const status = curator.getStatus();
+            const totalEntries = Object.values(status.tables).reduce(
+              (sum, count) => sum + count,
+              0,
+            );
+            orphanPercentage =
+              totalEntries > 0 ? Math.round((orphanCount / totalEntries) * 100) : 0;
+          }
+        } catch {
+          // Link module unavailable — degrade gracefully
+        }
+
+        // Apply quality penalty if orphan percentage > 10%
+        const metrics = { ...result.metrics };
+        const recommendations = [...result.recommendations];
+        if (orphanPercentage > 10) {
+          metrics.quality = Math.round(metrics.quality * 0.7 * 100) / 100;
+          recommendations.push(
+            `${orphanCount} orphan entries (${orphanPercentage}%) have no links — run consolidation to backfill.`,
+          );
+        }
+
+        return {
+          ...result,
+          metrics,
+          recommendations,
+          orphanCount,
+          orphanPercentage,
+        };
       },
     },
 

package/src/runtime/orchestrate-ops.ts

@@ -21,6 +21,8 @@ import { runEpilogue } from '../flows/epilogue.js';
 import type { OrchestrationPlan, ExecutionResult } from '../flows/types.js';
 import type { ContextHealthStatus } from './context-health.js';
 import type { OperatorSignals } from '../operator/operator-context-types.js';
+import { loadAgentWorkflows, getWorkflowForIntent } from '../workflows/workflow-loader.js';
+import type { WorkflowOverride } from '../workflows/workflow-loader.js';
 import {
   detectGitHubContext,
   findMatchingMilestone,
@@ -65,6 +67,70 @@ function detectIntent(prompt: string): string {
   return 'BUILD'; // default
 }
 
+// ---------------------------------------------------------------------------
+// Workflow override merge
+// ---------------------------------------------------------------------------
+
+/**
+ * Merge a workflow override into an OrchestrationPlan (mutates in place).
+ *
+ * - Gates: each workflow gate becomes a gate on the matching plan step
+ *   (matched by phase → step id prefix). Unmatched gates are appended as
+ *   new gate-only steps at the end.
+ * - Tools: workflow tools are merged into every step's `tools` array
+ *   (deduped). This ensures the tools are available to the executor.
+ */
+export function applyWorkflowOverride(plan: OrchestrationPlan, override: WorkflowOverride): void {
+  // Merge gates into plan steps
+  for (const gate of override.gates) {
+    // Try to find a step whose id starts with the gate phase
+    const matchingStep = plan.steps.find((s) =>
+      s.id.toLowerCase().startsWith(gate.phase.toLowerCase()),
+    );
+    if (matchingStep) {
+      // Attach/replace gate on the step
+      matchingStep.gate = {
+        type: 'GATE',
+        condition: gate.requirement,
+        onFail: { action: 'STOP', message: `Gate check failed: ${gate.check}` },
+      };
+    } else {
+      // No matching step — append a new gate-only step
+      plan.steps.push({
+        id: `workflow-gate-${gate.phase}`,
+        name: `${gate.phase} gate (${override.name})`,
+        tools: [],
+        parallel: false,
+        requires: [],
+        gate: {
+          type: 'GATE',
+          condition: gate.requirement,
+          onFail: { action: 'STOP', message: `Gate check failed: ${gate.check}` },
+        },
+        status: 'pending',
+      });
+    }
+  }
+
+  // Merge tools into plan steps (deduplicated)
+  if (override.tools.length > 0) {
+    for (const step of plan.steps) {
+      for (const tool of override.tools) {
+        if (!step.tools.includes(tool)) {
+          step.tools.push(tool);
+        }
+      }
+    }
+    // Update estimated tools count
+    plan.estimatedTools = plan.steps.reduce((acc, s) => acc + s.tools.length, 0);
+  }
+
+  // Add workflow info to warnings for visibility
+  plan.warnings.push(
+    `Workflow override "${override.name}" applied (${override.gates.length} gate(s), ${override.tools.length} tool(s)).`,
+  );
+}
+
 // ---------------------------------------------------------------------------
 // In-memory plan store
 // ---------------------------------------------------------------------------
@@ -312,6 +378,23 @@ export function createOrchestrateOps(
         // 3. Build flow-engine plan
         const plan = await buildPlan(intent, agentId, projectPath, runtime, prompt);
 
+        // 3b. Merge workflow overrides (gates + tools) if agent has a matching workflow
+        let workflowApplied: string | undefined;
+        const agentDir = runtime.config.agentDir;
+        if (agentDir) {
+          try {
+            const workflowsDir = path.join(agentDir, 'workflows');
+            const agentWorkflows = loadAgentWorkflows(workflowsDir);
+            const workflowOverride = getWorkflowForIntent(agentWorkflows, intent);
+            if (workflowOverride) {
+              applyWorkflowOverride(plan, workflowOverride);
+              workflowApplied = workflowOverride.name;
+            }
+          } catch {
+            // Workflow loading failed — plan is still valid without overrides
+          }
+        }
+
         // 4. Store in planStore
         planStore.set(plan.planId, { plan, createdAt: Date.now() });
 
@@ -373,6 +456,7 @@ export function createOrchestrateOps(
             skippedCount: plan.skipped.length,
             warnings: plan.warnings,
             estimatedTools: plan.estimatedTools,
+            ...(workflowApplied ? { workflowOverride: workflowApplied } : {}),
           },
         };
       },

package/src/vault/vault-markdown-sync.test.ts

@@ -128,6 +128,46 @@ describe('vault-markdown-sync', () => {
       const filePath = join(deepDir, 'vault', 'architecture', 'deep-entry.md');
       expect(existsSync(filePath)).toBe(true);
     });
+
+    it('should skip rewrite when content hash matches (dedup)', async () => {
+      const entry = makeEntry({ domain: 'design', title: 'Stable Token' });
+
+      // First write
+      const first = await syncEntryToMarkdown(entry, tmpDir);
+      expect(first.written).toBe(true);
+
+      const filePath = join(tmpDir, 'vault', 'design', 'stable-token.md');
+      const mtimeBefore = readFileSync(filePath, 'utf-8');
+
+      // Second write with same content — should skip
+      const second = await syncEntryToMarkdown(entry, tmpDir);
+      expect(second.written).toBe(false);
+
+      // File content should be identical (not rewritten)
+      const mtimeAfter = readFileSync(filePath, 'utf-8');
+      expect(mtimeAfter).toBe(mtimeBefore);
+    });
+
+    it('should rewrite when content changes', async () => {
+      const entry = makeEntry({ domain: 'design', title: 'Changing Token' });
+      const first = await syncEntryToMarkdown(entry, tmpDir);
+      expect(first.written).toBe(true);
+
+      // Modify the entry
+      entry.description = 'Updated description that changes the hash.';
+      const second = await syncEntryToMarkdown(entry, tmpDir);
+      expect(second.written).toBe(true);
+
+      const filePath = join(tmpDir, 'vault', 'design', 'changing-token.md');
+      const content = readFileSync(filePath, 'utf-8');
+      expect(content).toContain('Updated description');
+    });
+
+    it('should return written:false for empty slug', async () => {
+      const entry = makeEntry({ title: '!!!' }); // slugifies to empty
+      const result = await syncEntryToMarkdown(entry, tmpDir);
+      expect(result.written).toBe(false);
+    });
   });
 
   // ── syncAllToMarkdown ────────────────────────────────────────────

package/src/vault/vault-markdown-sync.ts

@@ -76,21 +76,34 @@ export function entryToMarkdown(entry: IntelligenceEntry): string {
 
 // ─── Sync ───────────────────────────────────────────────────────────
 
-/** Write a single entry as a markdown file to knowledge/vault/{domain}/{slug}.md */
+/** Write a single entry as a markdown file to knowledge/vault/{domain}/{slug}.md.
+ *  Skips the write if the file already exists with a matching content hash (dedup). */
 export async function syncEntryToMarkdown(
   entry: IntelligenceEntry,
   knowledgeDir: string,
-): Promise<void> {
+): Promise<{ written: boolean }> {
   const domain = entry.domain || '_general';
   const slug = titleToSlug(entry.title);
-  if (!slug) return;
+  if (!slug) return { written: false };
 
   const dir = join(knowledgeDir, 'vault', domain);
   mkdirSync(dir, { recursive: true });
 
   const filePath = join(dir, `${slug}.md`);
+
+  // Content-hash dedup: skip rewrite when file content hasn't changed
+  const contentHash = computeContentHash(entry);
+  if (existsSync(filePath)) {
+    const existing = readFileSync(filePath, 'utf-8');
+    const hashMatch = existing.match(/^content_hash:\s*"([^"]+)"/m);
+    if (hashMatch && hashMatch[1] === contentHash) {
+      return { written: false };
+    }
+  }
+
   const content = entryToMarkdown(entry);
   writeFileSync(filePath, content, 'utf-8');
+  return { written: true };
 }
 
 /** Sync all vault entries to markdown, skipping entries whose content hash matches. */

package/src/workflows/index.ts

@@ -0,0 +1,12 @@
+/**
+ * Workflow overrides — barrel export.
+ */
+export {
+  loadAgentWorkflows,
+  getWorkflowForIntent,
+  WORKFLOW_TO_INTENT,
+  WorkflowGateSchema,
+  WorkflowOverrideSchema,
+} from './workflow-loader.js';
+
+export type { WorkflowGate, WorkflowOverride } from './workflow-loader.js';

package/src/workflows/orchestrate-integration.test.ts

@@ -0,0 +1,166 @@
+import { describe, it, expect } from 'vitest';
+import { applyWorkflowOverride } from '../runtime/orchestrate-ops.js';
+import type { OrchestrationPlan, PlanStep } from '../flows/types.js';
+import type { WorkflowOverride } from './workflow-loader.js';
+
+function makePlan(steps: PlanStep[]): OrchestrationPlan {
+  return {
+    planId: 'test-plan-1',
+    intent: 'BUILD',
+    flowId: 'BUILD-flow',
+    steps,
+    skipped: [],
+    epilogue: ['capture_knowledge'],
+    warnings: [],
+    summary: 'Test plan',
+    estimatedTools: steps.reduce((acc, s) => acc + s.tools.length, 0),
+    context: {
+      intent: 'BUILD',
+      probes: {
+        vault: true,
+        brain: false,
+        designSystem: false,
+        sessionStore: true,
+        projectRules: false,
+        active: true,
+      },
+      entities: { components: [], actions: [] },
+      projectPath: '.',
+    },
+  };
+}
+
+function makeStep(id: string, tools: string[] = []): PlanStep {
+  return {
+    id,
+    name: id,
+    tools,
+    parallel: false,
+    requires: [],
+    status: 'pending',
+  };
+}
+
+describe('applyWorkflowOverride', () => {
+  it('merges gates into matching plan steps', () => {
+    const plan = makePlan([
+      makeStep('pre-execution-vault-search', ['vault_search']),
+      makeStep('completion-capture', ['capture_knowledge']),
+    ]);
+
+    const override: WorkflowOverride = {
+      name: 'feature-dev',
+      gates: [
+        {
+          phase: 'pre-execution',
+          requirement: 'Plan approved by user',
+          check: 'plan-approved',
+        },
+        {
+          phase: 'completion',
+          requirement: 'Knowledge captured',
+          check: 'knowledge-captured',
+        },
+      ],
+      tools: [],
+    };
+
+    applyWorkflowOverride(plan, override);
+
+    // Gates should be attached to matching steps
+    expect(plan.steps[0].gate).toBeDefined();
+    expect(plan.steps[0].gate!.type).toBe('GATE');
+    expect(plan.steps[0].gate!.condition).toBe('Plan approved by user');
+
+    expect(plan.steps[1].gate).toBeDefined();
+    expect(plan.steps[1].gate!.condition).toBe('Knowledge captured');
+  });
+
+  it('appends unmatched gates as new steps', () => {
+    const plan = makePlan([makeStep('vault-search', ['vault_search'])]);
+
+    const override: WorkflowOverride = {
+      name: 'bug-fix',
+      gates: [
+        {
+          phase: 'post-task',
+          requirement: 'All tests pass',
+          check: 'tests-pass',
+        },
+      ],
+      tools: [],
+    };
+
+    applyWorkflowOverride(plan, override);
+
+    // Original step untouched
+    expect(plan.steps[0].gate).toBeUndefined();
+
+    // New gate step appended
+    expect(plan.steps).toHaveLength(2);
+    expect(plan.steps[1].id).toBe('workflow-gate-post-task');
+    expect(plan.steps[1].gate!.condition).toBe('All tests pass');
+  });
+
+  it('merges tools into all plan steps (deduplicated)', () => {
+    const plan = makePlan([makeStep('step1', ['existing_tool']), makeStep('step2', [])]);
+
+    const override: WorkflowOverride = {
+      name: 'feature-dev',
+      gates: [],
+      tools: ['soleri_vault op:search_intelligent', 'existing_tool'],
+    };
+
+    applyWorkflowOverride(plan, override);
+
+    // step1 already had existing_tool — should not duplicate
+    expect(plan.steps[0].tools).toEqual(['existing_tool', 'soleri_vault op:search_intelligent']);
+    // step2 gets the tools
+    expect(plan.steps[1].tools).toEqual(['soleri_vault op:search_intelligent', 'existing_tool']);
+    // estimatedTools updated
+    expect(plan.estimatedTools).toBe(plan.steps.reduce((acc, s) => acc + s.tools.length, 0));
+  });
+
+  it('does nothing when override has no gates or tools', () => {
+    const plan = makePlan([makeStep('step1', ['t1'])]);
+    const originalSteps = plan.steps.length;
+    const originalTools = plan.steps[0].tools.length;
+
+    const override: WorkflowOverride = {
+      name: 'empty',
+      gates: [],
+      tools: [],
+    };
+
+    applyWorkflowOverride(plan, override);
+
+    expect(plan.steps).toHaveLength(originalSteps);
+    expect(plan.steps[0].tools).toHaveLength(originalTools);
+    // Warning still added
+    expect(plan.warnings).toContain('Workflow override "empty" applied (0 gate(s), 0 tool(s)).');
+  });
+
+  it('plan remains unchanged when no workflow matches', () => {
+    // This tests the calling code path — if getWorkflowForIntent returns null,
+    // applyWorkflowOverride is never called
+    const plan = makePlan([makeStep('step1', ['t1'])]);
+    expect(plan.warnings).toHaveLength(0);
+    expect(plan.steps[0].gate).toBeUndefined();
+  });
+
+  it('adds info warning about applied override', () => {
+    const plan = makePlan([makeStep('step1')]);
+
+    const override: WorkflowOverride = {
+      name: 'feature-dev',
+      gates: [{ phase: 'pre', requirement: 'ok', check: 'go' }],
+      tools: ['tool1', 'tool2'],
+    };
+
+    applyWorkflowOverride(plan, override);
+
+    expect(plan.warnings).toContain(
+      'Workflow override "feature-dev" applied (1 gate(s), 2 tool(s)).',
+    );
+  });
+});