@soleri/core 9.8.0 → 9.10.0

package/src/runtime/claude-md-helpers.test.ts

@@ -12,6 +12,7 @@ import {
   composeIntegrationSection,
   buildInjectionContent,
   injectEngineRulesBlock,
+  removeEngineRulesFromGlobal,
 } from './claude-md-helpers.js';
 import type { AgentRuntimeConfig } from './types.js';
 
@@ -186,4 +187,84 @@ describe('injectEngineRulesBlock', () => {
     expect(result).toContain('AFTER');
     expect(result).toContain('REPLACED');
   });
+
+  it('handles empty content by appending rules', () => {
+    const result = injectEngineRulesBlock('', 'RULES');
+    expect(result).toContain('RULES');
+  });
+
+  it('is idempotent — double injection replaces cleanly', () => {
+    const first = injectEngineRulesBlock('# File', `${RULES_START}\nV1\n${RULES_END}`);
+    const second = injectEngineRulesBlock(first, `${RULES_START}\nV2\n${RULES_END}`);
+    expect(second).toContain('V2');
+    expect(second).not.toContain('V1');
+    // Should have exactly one start marker
+    const startCount = (second.match(/<!-- soleri:engine-rules -->/g) || []).length;
+    expect(startCount).toBe(1);
+  });
+});
+
+describe('removeEngineRulesFromGlobal', () => {
+  const RULES_START = '<!-- soleri:engine-rules -->';
+  const RULES_END = '<!-- /soleri:engine-rules -->';
+
+  it('returns unchanged content when no engine rules present', () => {
+    const content = '# Global CLAUDE.md\n\nSome user content.';
+    const { cleaned, removed } = removeEngineRulesFromGlobal(content);
+    expect(removed).toBe(false);
+    expect(cleaned).toBe(content);
+  });
+
+  it('removes engine rules block from content', () => {
+    const content = `# Global\n\n${RULES_START}\nEngine rules here\n${RULES_END}\n\nUser content`;
+    const { cleaned, removed } = removeEngineRulesFromGlobal(content);
+    expect(removed).toBe(true);
+    expect(cleaned).not.toContain('Engine rules here');
+    expect(cleaned).not.toContain(RULES_START);
+    expect(cleaned).not.toContain(RULES_END);
+    expect(cleaned).toContain('# Global');
+    expect(cleaned).toContain('User content');
+  });
+
+  it('handles engine rules at end of file', () => {
+    const content = `# Global\n\n${RULES_START}\nRules\n${RULES_END}`;
+    const { cleaned, removed } = removeEngineRulesFromGlobal(content);
+    expect(removed).toBe(true);
+    expect(cleaned).toContain('# Global');
+    expect(cleaned).not.toContain('Rules');
+  });
+
+  it('handles engine rules at start of file', () => {
+    const content = `${RULES_START}\nRules\n${RULES_END}\n\n# Global`;
+    const { cleaned, removed } = removeEngineRulesFromGlobal(content);
+    expect(removed).toBe(true);
+    expect(cleaned).toContain('# Global');
+    expect(cleaned).not.toContain(RULES_START);
+  });
+
+  it('preserves agent blocks when removing engine rules', () => {
+    const content = [
+      '# Global',
+      '',
+      '<!-- agent:mybot:mode -->',
+      'Agent content',
+      '<!-- /agent:mybot:mode -->',
+      '',
+      RULES_START,
+      'Engine rules',
+      RULES_END,
+    ].join('\n');
+    const { cleaned, removed } = removeEngineRulesFromGlobal(content);
+    expect(removed).toBe(true);
+    expect(cleaned).toContain('<!-- agent:mybot:mode -->');
+    expect(cleaned).toContain('Agent content');
+    expect(cleaned).not.toContain('Engine rules');
+  });
+
+  it('returns non-empty string for content that is only engine rules', () => {
+    const content = `${RULES_START}\nOnly rules\n${RULES_END}`;
+    const { cleaned, removed } = removeEngineRulesFromGlobal(content);
+    expect(removed).toBe(true);
+    expect(cleaned.length).toBeGreaterThan(0);
+  });
 });

package/src/runtime/claude-md-helpers.ts

@@ -216,3 +216,28 @@ export function injectEngineRulesBlock(content: string, engineRulesContent: stri
   // Append
   return content.trimEnd() + '\n\n' + engineRulesContent + '\n';
 }
+
+/**
+ * Remove engine rules block from content.
+ * Used during self-healing to strip engine rules from global CLAUDE.md
+ * when they were incorrectly injected there (they belong in _engine.md).
+ *
+ * Returns the content without the engine rules block, or unchanged if no block found.
+ */
+export function removeEngineRulesFromGlobal(content: string): {
+  cleaned: string;
+  removed: boolean;
+} {
+  if (!hasEngineRules(content)) {
+    return { cleaned: content, removed: false };
+  }
+
+  const startIdx = content.indexOf(ENGINE_RULES_START);
+  const endIdx = content.indexOf(ENGINE_RULES_END);
+
+  const before = content.slice(0, startIdx).trimEnd();
+  const after = content.slice(endIdx + ENGINE_RULES_END.length).trimStart();
+
+  const cleaned = before + (before && after ? '\n\n' : '') + after;
+  return { cleaned: cleaned || '\n', removed: true };
+}

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/facades/memory-facade.ts

@@ -151,7 +151,8 @@ export function createMemoryFacadeOps(runtime: AgentRuntime): OpDefinition[] {
       }),
       handler: async (params) => {
         const { resolve } = await import('node:path');
-        const projectPath = resolve((params.projectPath as string) ?? '.');
+        const { findProjectRoot } = await import('../../paths.js');
+        const projectPath = findProjectRoot(resolve((params.projectPath as string) ?? '.'));
         const summary = (params.summary ?? params.conversationContext) as string;
         if (!summary) {
           return { captured: false, error: 'Either summary or conversationContext is required.' };

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';