@soleri/core 9.3.1 → 9.4.0

package/src/runtime/plan-feedback-helper.test.ts

@@ -0,0 +1,173 @@
+import { describe, it, expect, vi } from 'vitest';
+import { recordPlanFeedback } from './plan-feedback-helper.js';
+
+// ─── Mock Factories ───────────────────────────────────────────────────
+
+function makeBrain() {
+  return {
+    recordFeedback: vi.fn(),
+  };
+}
+
+function makeBrainIntelligence() {
+  return {
+    maybeAutoBuildOnFeedback: vi.fn(),
+  };
+}
+
+function makePlan(decisions: (string | { decision: string })[] = []) {
+  return {
+    objective: 'Test objective',
+    decisions,
+  };
+}
+
+// ─── Tests ────────────────────────────────────────────────────────────
+
+describe('recordPlanFeedback', () => {
+  it('should extract entryIds from decision strings and record feedback', () => {
+    const brain = makeBrain();
+    const intelligence = makeBrainIntelligence();
+    const plan = makePlan([
+      'Brain pattern: TDD (strength: 52.5) [entryId:method-tdd-123]',
+      'Brain pattern: Vault hooks (strength: 87.5) [entryId:arch-vault-456]',
+    ]);
+
+    const count = recordPlanFeedback(plan, brain as unknown, intelligence as unknown);
+
+    expect(count).toBe(2);
+    expect(brain.recordFeedback).toHaveBeenCalledTimes(2);
+    expect(brain.recordFeedback).toHaveBeenCalledWith(
+      'Test objective',
+      'method-tdd-123',
+      'accepted',
+    );
+    expect(brain.recordFeedback).toHaveBeenCalledWith(
+      'Test objective',
+      'arch-vault-456',
+      'accepted',
+    );
+    expect(intelligence.maybeAutoBuildOnFeedback).toHaveBeenCalledOnce();
+  });
+
+  it('should handle decision objects with .decision property', () => {
+    const brain = makeBrain();
+    const plan = makePlan([{ decision: 'Use vault pattern [entryId:obj-entry-1]' }]);
+
+    const count = recordPlanFeedback(plan, brain as unknown);
+
+    expect(count).toBe(1);
+    expect(brain.recordFeedback).toHaveBeenCalledWith('Test objective', 'obj-entry-1', 'accepted');
+  });
+
+  it('should skip decisions without entryId markers', () => {
+    const brain = makeBrain();
+    const plan = makePlan([
+      'Brain pattern: TDD (strength: 52.5)',
+      'Some decision without an entry ID',
+      'Brain pattern: Vault hooks (strength: 87.5) [entryId:arch-vault-456]',
+    ]);
+
+    const count = recordPlanFeedback(plan, brain as unknown);
+
+    expect(count).toBe(1);
+    expect(brain.recordFeedback).toHaveBeenCalledTimes(1);
+    expect(brain.recordFeedback).toHaveBeenCalledWith(
+      'Test objective',
+      'arch-vault-456',
+      'accepted',
+    );
+  });
+
+  it('should skip malformed entryId markers gracefully', () => {
+    const brain = makeBrain();
+    const plan = makePlan(['Brain pattern: X [entryId:]', 'Brain pattern: Y [entryId:valid-id]']);
+
+    const count = recordPlanFeedback(plan, brain as unknown);
+
+    // [entryId:] won't match because the regex requires at least one char after :
+    // Actually the regex [^\]]+ requires 1+ chars, so empty entryId won't match
+    expect(count).toBe(1);
+    expect(brain.recordFeedback).toHaveBeenCalledWith('Test objective', 'valid-id', 'accepted');
+  });
+
+  it('should not double-record duplicate entryIds', () => {
+    const brain = makeBrain();
+    const plan = makePlan([
+      'Decision 1 [entryId:same-entry]',
+      'Decision 2 [entryId:same-entry]',
+      'Decision 3 [entryId:different-entry]',
+    ]);
+
+    const count = recordPlanFeedback(plan, brain as unknown);
+
+    expect(count).toBe(2);
+    expect(brain.recordFeedback).toHaveBeenCalledTimes(2);
+    expect(brain.recordFeedback).toHaveBeenCalledWith('Test objective', 'same-entry', 'accepted');
+    expect(brain.recordFeedback).toHaveBeenCalledWith(
+      'Test objective',
+      'different-entry',
+      'accepted',
+    );
+  });
+
+  it('should gracefully handle recordFeedback throwing', () => {
+    const brain = makeBrain();
+    brain.recordFeedback.mockImplementationOnce(() => {
+      throw new Error('Entry not found');
+    });
+    const plan = makePlan([
+      'Decision 1 [entryId:missing-entry]',
+      'Decision 2 [entryId:valid-entry]',
+    ]);
+
+    const count = recordPlanFeedback(plan, brain as unknown);
+
+    // First one throws, second succeeds
+    expect(count).toBe(1);
+    expect(brain.recordFeedback).toHaveBeenCalledTimes(2);
+  });
+
+  it('should return 0 and not call maybeAutoBuild when no entryIds found', () => {
+    const brain = makeBrain();
+    const intelligence = makeBrainIntelligence();
+    const plan = makePlan(['Decision without markers', 'Another plain decision']);
+
+    const count = recordPlanFeedback(plan, brain as unknown, intelligence as unknown);
+
+    expect(count).toBe(0);
+    expect(brain.recordFeedback).not.toHaveBeenCalled();
+    expect(intelligence.maybeAutoBuildOnFeedback).not.toHaveBeenCalled();
+  });
+
+  it('should handle empty decisions array', () => {
+    const brain = makeBrain();
+    const plan = makePlan([]);
+
+    const count = recordPlanFeedback(plan, brain as unknown);
+
+    expect(count).toBe(0);
+    expect(brain.recordFeedback).not.toHaveBeenCalled();
+  });
+
+  it('should work without brainIntelligence (optional param)', () => {
+    const brain = makeBrain();
+    const plan = makePlan(['Decision [entryId:entry-1]']);
+
+    const count = recordPlanFeedback(plan, brain as unknown);
+
+    expect(count).toBe(1);
+    // No error thrown despite missing brainIntelligence
+  });
+
+  it('should extract multiple entryIds from a single decision string', () => {
+    const brain = makeBrain();
+    const plan = makePlan(['Combined: [entryId:first-entry] and also [entryId:second-entry]']);
+
+    const count = recordPlanFeedback(plan, brain as unknown);
+
+    expect(count).toBe(2);
+    expect(brain.recordFeedback).toHaveBeenCalledWith('Test objective', 'first-entry', 'accepted');
+    expect(brain.recordFeedback).toHaveBeenCalledWith('Test objective', 'second-entry', 'accepted');
+  });
+});

package/src/runtime/plan-feedback-helper.ts

@@ -0,0 +1,63 @@
+/**
+ * Shared helper for recording brain feedback from plan decisions and context.
+ *
+ * Used by both plan_complete_lifecycle (planning-extra-ops.ts) and
+ * orchestrate_complete (orchestrate-ops.ts) to close the brain learning loop.
+ */
+
+import type { Brain } from '../brain/brain.js';
+import type { BrainIntelligence } from '../brain/intelligence.js';
+
+/** Regex to extract vault entry IDs embedded in decision/context strings. */
+const ENTRY_ID_REGEX = /\[entryId:([^\]]+)\]/g;
+
+/**
+ * Extract entry IDs from an array of decision or context strings,
+ * record positive feedback for each, and optionally trigger auto-rebuild.
+ *
+ * @returns Number of feedback entries recorded.
+ */
+export function recordPlanFeedback(
+  plan: { objective: string; decisions: (string | { decision: string })[] },
+  brain: Brain,
+  brainIntelligence?: BrainIntelligence,
+): number {
+  let feedbackRecorded = 0;
+  const seen = new Set<string>();
+
+  // Collect all strings to scan: decisions + any context strings
+  const strings: string[] = [];
+
+  for (const d of plan.decisions) {
+    const str = typeof d === 'string' ? d : d.decision;
+    strings.push(str);
+  }
+
+  for (const str of strings) {
+    // Use matchAll to find all entryId markers in each string
+    for (const match of str.matchAll(ENTRY_ID_REGEX)) {
+      const entryId = match[1];
+      // Skip duplicates within the same plan
+      if (seen.has(entryId)) continue;
+      seen.add(entryId);
+
+      try {
+        brain.recordFeedback(plan.objective, entryId, 'accepted');
+        feedbackRecorded++;
+      } catch {
+        // Graceful degradation — skip if entry not found or already recorded
+      }
+    }
+  }
+
+  // Trigger auto-rebuild check after recording feedback
+  if (feedbackRecorded > 0 && brainIntelligence) {
+    try {
+      brainIntelligence.maybeAutoBuildOnFeedback();
+    } catch {
+      // Auto-rebuild is best-effort
+    }
+  }
+
+  return feedbackRecorded;
+}

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

@@ -69,7 +69,7 @@ function createMockRuntime(): AgentRuntime {
 
   return {
     planner: {
-      iterate: vi.fn(() => plan),
+      iterate: vi.fn(() => ({ plan, mutated: 1 })),
       splitTasks: vi.fn(() => ({
         ...plan,
         tasks: [plan.tasks[0], { id: 'task-2', title: 'Task 2' }],
@@ -159,6 +159,48 @@ describe('createPlanningExtraOps', () => {
       );
     });
 
+    it('returns iterated: false when no changes detected', async () => {
+      vi.mocked(runtime.planner.iterate).mockReturnValue({
+        plan: makePlan() as unknown,
+        mutated: 0,
+      } as unknown);
+      const result = (await findOp(ops, 'plan_iterate').handler({
+        planId: 'plan-1',
+      })) as Record<string, unknown>;
+      expect(result.iterated).toBe(false);
+      expect(result.reason).toBe('no changes detected');
+    });
+
+    it('passes alternatives to planner.iterate', async () => {
+      const result = (await findOp(ops, 'plan_iterate').handler({
+        planId: 'plan-1',
+        alternatives: [
+          { approach: 'Alt A', pros: ['fast'], cons: ['fragile'], rejected_reason: 'Too risky' },
+        ],
+      })) as Record<string, unknown>;
+      expect(result.iterated).toBe(true);
+      expect(runtime.planner.iterate).toHaveBeenCalledWith(
+        'plan-1',
+        expect.objectContaining({
+          alternatives: [expect.objectContaining({ approach: 'Alt A' })],
+        }),
+      );
+    });
+
+    it('passes decisions to planner.iterate', async () => {
+      const result = (await findOp(ops, 'plan_iterate').handler({
+        planId: 'plan-1',
+        decisions: [{ decision: 'Use FTS5', rationale: 'Performance' }],
+      })) as Record<string, unknown>;
+      expect(result.iterated).toBe(true);
+      expect(runtime.planner.iterate).toHaveBeenCalledWith(
+        'plan-1',
+        expect.objectContaining({
+          decisions: [{ decision: 'Use FTS5', rationale: 'Performance' }],
+        }),
+      );
+    });
+
     it('returns error on failure', async () => {
       vi.mocked(runtime.planner.iterate).mockImplementation(() => {
         throw new Error('Not a draft');

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

@@ -17,6 +17,7 @@ import { collectGitEvidence } from '../planning/evidence-collector.js';
 import { matchPlaybooks, type PlaybookMatchResult } from '../playbooks/index.js';
 import { entryToPlaybookDefinition } from '../playbooks/index.js';
 import { closeIssueWithComment } from './github-integration.js';
+import { recordPlanFeedback } from './plan-feedback-helper.js';
 
 /**
  * Create 22 extended planning operations for an agent runtime.
@@ -37,9 +38,9 @@ export function createPlanningExtraOps(runtime: AgentRuntime): OpDefinition[] {
     {
       name: 'plan_iterate',
       description:
-        'Revise a draft plan — change objective, scope, decisions, or add/remove tasks. Only works on draft plans.',
+        'Revise a draft plan — change objective, scope, decisions, alternatives, or add/remove tasks. Only works on draft plans.',
       auth: 'write',
-      schema: z.object({
+      schema: z.strictObject({
         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)'),
@@ -49,21 +50,54 @@ export function createPlanningExtraOps(runtime: AgentRuntime): OpDefinition[] {
           .describe(
             'New decisions list (replaces existing) — strings or {decision, rationale} objects',
           ),
+        alternatives: z
+          .array(
+            z.object({
+              approach: z.string().describe('The alternative approach considered'),
+              pros: z.array(z.string()).describe('Advantages of this approach'),
+              cons: z.array(z.string()).describe('Disadvantages of this approach'),
+              rejected_reason: z.string().describe('Why this alternative was rejected'),
+            }),
+          )
+          .optional()
+          .describe('Rejected alternative approaches (replaces existing)'),
         addTasks: z
-          .array(z.object({ title: z.string(), description: z.string() }))
+          .array(
+            z.object({
+              title: z.string(),
+              description: z.string(),
+              phase: z
+                .string()
+                .optional()
+                .describe('Phase this task belongs to (e.g., "wave-1", "discovery")'),
+              milestone: z
+                .string()
+                .optional()
+                .describe('Milestone this task contributes to (e.g., "v1.0", "mvp")'),
+              parentTaskId: z.string().optional().describe('Parent task ID for sub-task hierarchy'),
+            }),
+          )
           .optional()
           .describe('Tasks to append'),
         removeTasks: z.array(z.string()).optional().describe('Task IDs to remove'),
       }),
       handler: async (params) => {
         try {
-          const plan = planner.iterate(params.planId as string, {
+          const { plan, mutated } = planner.iterate(params.planId as string, {
             objective: params.objective as string | undefined,
             scope: params.scope as string | undefined,
             decisions: params.decisions as string[] | undefined,
+            alternatives: params.alternatives as
+              | Array<{ approach: string; pros: string[]; cons: string[]; rejected_reason: string }>
+              | undefined,
             addTasks: params.addTasks as Array<{ title: string; description: string }> | undefined,
             removeTasks: params.removeTasks as string[] | undefined,
           });
+
+          if (mutated === 0) {
+            return { iterated: false, reason: 'no changes detected', plan };
+          }
+
           return { iterated: true, plan };
         } catch (err) {
           return { error: (err as Error).message };
@@ -85,6 +119,17 @@ export function createPlanningExtraOps(runtime: AgentRuntime): OpDefinition[] {
               title: z.string(),
               description: z.string(),
               dependsOn: z.array(z.string()).optional().describe('Task IDs this task depends on'),
+              phase: z
+                .string()
+                .optional()
+                .describe(
+                  'Phase this task belongs to (e.g., "wave-1", "discovery", "implementation")',
+                ),
+              milestone: z
+                .string()
+                .optional()
+                .describe('Milestone this task contributes to (e.g., "v1.0", "mvp", "beta")'),
+              parentTaskId: z.string().optional().describe('Parent task ID for sub-task hierarchy'),
             }),
           )
           .describe('New task list with optional dependency references (task-1, task-2, etc.)'),
@@ -93,7 +138,14 @@ export function createPlanningExtraOps(runtime: AgentRuntime): OpDefinition[] {
         try {
           const plan = planner.splitTasks(
             params.planId as string,
-            params.tasks as Array<{ title: string; description: string; dependsOn?: string[] }>,
+            params.tasks as Array<{
+              title: string;
+              description: string;
+              dependsOn?: string[];
+              phase?: string;
+              milestone?: string;
+              parentTaskId?: string;
+            }>,
           );
 
           // Auto-start brain session linked to the plan for learning pipeline
@@ -139,20 +191,16 @@ export function createPlanningExtraOps(runtime: AgentRuntime): OpDefinition[] {
           .describe('Specific drift items — differences between plan and reality'),
       }),
       handler: async (params) => {
-        try {
-          const plan = planner.reconcile(params.planId as string, {
-            actualOutcome: params.actualOutcome as string,
-            driftItems: params.driftItems as DriftItem[] | undefined,
-          });
-          return {
-            reconciled: true,
-            accuracy: plan.reconciliation!.accuracy,
-            driftCount: plan.reconciliation!.driftItems.length,
-            plan,
-          };
-        } catch (err) {
-          return { error: (err as Error).message };
-        }
+        const plan = planner.reconcile(params.planId as string, {
+          actualOutcome: params.actualOutcome as string,
+          driftItems: params.driftItems as DriftItem[] | undefined,
+        });
+        return {
+          reconciled: true,
+          accuracy: plan.reconciliation!.accuracy,
+          driftCount: plan.reconciliation!.driftItems.length,
+          plan,
+        };
       },
     },
 
@@ -228,20 +276,7 @@ export function createPlanningExtraOps(runtime: AgentRuntime): OpDefinition[] {
           }
 
           // Auto-record positive feedback for vault entries used as recommendations
-          let feedbackRecorded = 0;
-          const entryIdRegex = /\[entryId:([^\]]+)\]/;
-          for (const d of plan.decisions) {
-            const decisionStr = typeof d === 'string' ? d : d.decision;
-            const match = entryIdRegex.exec(decisionStr);
-            if (match) {
-              try {
-                brain.recordFeedback(plan.objective, match[1], 'accepted');
-                feedbackRecorded++;
-              } catch {
-                // Graceful degradation — skip if entry not found or already recorded
-              }
-            }
-          }
+          const feedbackRecorded = recordPlanFeedback(plan, brain, brainIntelligence);
 
           // Auto-close linked GitHub issue if plan has one
           let issueClosed = false;
@@ -818,6 +853,34 @@ export function createPlanningExtraOps(runtime: AgentRuntime): OpDefinition[] {
       },
     },
 
+    // ─── Plan Close Stale ───────────────────────────────────────
+    {
+      name: 'plan_close_stale',
+      description:
+        'Close stale plans stuck in non-terminal states. Draft/approved plans expire after 30 min. Executing/reconciling plans expire after the configured threshold (default 24h). Returns list of closed plans.',
+      auth: 'write',
+      schema: z.object({
+        olderThanMs: z
+          .number()
+          .optional()
+          .describe(
+            'Custom threshold in milliseconds for executing/reconciling plans (default: 24h). Set to 0 to close ALL non-terminal plans immediately.',
+          ),
+      }),
+      handler: async (params) => {
+        const olderThanMs = params.olderThanMs as number | undefined;
+        const result = planner.closeStale(olderThanMs);
+        return {
+          closed: result.closedPlans.length,
+          plans: result.closedPlans,
+          message:
+            result.closedPlans.length > 0
+              ? `Closed ${result.closedPlans.length} stale plan(s)`
+              : 'No stale plans found',
+        };
+      },
+    },
+
     // ─── Purge Plans (#215) ──────────────────────────────────────────
     {
       name: 'plan_purge',

package/src/runtime/session-briefing.test.ts

@@ -40,6 +40,7 @@ function makeRuntime(overrides?: {
     },
     planner: {
       list: () => o.plans ?? [],
+      closeStale: () => ({ closedIds: [], closedPlans: [] }),
     },
     vault: {
       stats: () => o.vaultStats ?? { totalEntries: 50, byType: { playbook: 5 } },

package/src/runtime/session-briefing.ts

@@ -78,8 +78,17 @@ export function createSessionBriefingOps(runtime: AgentRuntime): OpDefinition[]
           // Session data unavailable — skip
         }
 
-        // 2. Active plans
+        // 2. Active plans — auto-close ancient ones (>24h)
         try {
+          // Auto-close plans stuck in non-terminal states for more than 24h
+          const staleResult = planner.closeStale();
+          if (staleResult.closedPlans.length > 0) {
+            sections.push({
+              label: 'Plans auto-closed',
+              content: `${staleResult.closedPlans.length} stale plan(s) closed: ${staleResult.closedPlans.map((p) => `${p.id.slice(0, 25)}… (${p.reason})`).join(', ')}`,
+            });
+          }
+
           const plans = planner.list();
           const active = plans.filter(
             (p) =>

package/src/runtime/types.ts

@@ -34,6 +34,7 @@ import type { ChainRunner } from '../flows/chain-runner.js';
 import type { JobQueue } from '../queue/job-queue.js';
 import type { PipelineRunner } from '../queue/pipeline-runner.js';
 import type { OperatorProfileStore } from '../operator/operator-profile.js';
+import type { OperatorContextStore } from '../operator/operator-context-store.js';
 import type { ContextHealthMonitor } from './context-health.js';
 
 /**
@@ -121,6 +122,8 @@ export interface AgentRuntime {
   pipelineRunner: PipelineRunner;
   /** Operator profile — personality learning, signals, adaptation. */
   operatorProfile: OperatorProfileStore;
+  /** Operator context store — compounding signals into stable operator profile. */
+  operatorContextStore?: OperatorContextStore;
   /** Agent persona — defines character, voice, and cultural texture. */
   persona: import('../persona/types.js').PersonaConfig;
   /** Generated persona system instructions for LLM context. */

package/src/skills/sync-skills.ts

@@ -41,15 +41,19 @@ export function discoverSkills(skillsDirs: string[]): SkillEntry[] {
   return skills;
 }
 
-/** Inject agent branding after YAML frontmatter */
-function brandSkillContent(content: string, agentName: string): string {
+/** Inject agent branding after YAML frontmatter and rewrite skill name */
+function brandSkillContent(content: string, agentName: string, prefixedName?: string): string {
   // Find end of frontmatter (second ---)
   const fmEnd = content.indexOf('---', content.indexOf('---') + 3);
   if (fmEnd === -1) return content;
 
-  const afterFm = fmEnd + 3;
-  const before = content.slice(0, afterFm);
-  const after = content.slice(afterFm);
+  let before = content.slice(0, fmEnd + 3);
+  const after = content.slice(fmEnd + 3);
+
+  // Rewrite name: field in frontmatter to include agent prefix
+  if (prefixedName) {
+    before = before.replace(/^(name:\s*).+$/m, `$1${prefixedName}`);
+  }
 
   const brandLine = `\n\n> **${agentName}** skill\n`;
   return before + brandLine + after;
@@ -71,10 +75,13 @@ export function syncSkillsToClaudeCode(skillsDirs: string[], agentName?: string)
   mkdirSync(commandsDir, { recursive: true });
 
   for (const skill of skills) {
-    const targetPath = join(commandsDir, `${skill.name}.md`);
+    const prefix = agentName ? `${agentName.toLowerCase().replace(/\s+/g, '-')}-` : '';
+    const targetPath = join(commandsDir, `${prefix}${skill.name}.md`);
     try {
       const sourceContent = readFileSync(skill.sourcePath, 'utf-8');
-      const branded = agentName ? brandSkillContent(sourceContent, agentName) : sourceContent;
+      const branded = agentName
+        ? brandSkillContent(sourceContent, agentName, `${prefix}${skill.name}`)
+        : sourceContent;
 
       if (!existsSync(targetPath)) {
         writeFileSync(targetPath, branded);

package/vitest.config.ts

@@ -6,6 +6,7 @@ export default defineConfig({
     pool: 'forks',
     poolOptions: { forks: { singleFork: true } },
     testTimeout: 30_000,
+    exclude: ['**/node_modules/**', '**/.claude/worktrees/**'],
     coverage: {
       provider: 'v8',
       include: ['src/**/*.ts'],