Vitto Intelligence v2 — Design Specification (Updated)

Session: S208 → S210 | Date: 2026-03-12 (original), 2026-03-12 (updated) Author: Senior Engineering Review (Claude Code) Status: Active — S209.3 partial implementation complete, remaining gaps identified Supersedes: Phases 3-6 of docs/english/Plans/vitto-more-reliable-intelligence.plan.md (S202) Cross-ref: docs/english/Plans/S209-vitto-jarvis-level-agent-ux.plan.md (S209 items 2.4-2.6, 3.1-3.3)

Executive Summary

Vitto Intelligence v2 is a cohesive system upgrade that closes the self-improvement loop no competitor has. While Manus starts fresh every task, Devin has no memory, and OpenAI/Claude SDKs ship no learning infrastructure — Vitto learns from every execution, knows every user personally, reaches out proactively across all channels, and verifies its own behavior.

The Jarvis Test: Every feature must pass — "Would Jarvis do this?" Jarvis is always present, talks first when something matters, never forgets you, knows your workspace deeply, learns from mistakes, gets sharper over time, and doesn't waste your time or money.

This spec covers 7 subsystems designed as an integrated intelligence layer:

1. Skills Closed Loop — Extract skills from successes, mine anti-patterns from failures, inject both with confidence tiers, feedback loop updates quality
2. Proactive Intelligence — Multi-channel dispatcher (WhatsApp + Slack + Web + email) with safety guards, rule-based triggers, reach users wherever they are 24/7
3. Dossier Enhancement — Bidirectional sync, channel preferences, skill personalization, space context wiring, dialectic enrichment
4. Golden Path Tests — Two-tier regression suite (CI behavioral contracts + nightly integration smokes)
5. Cost Improvements — Per-feature budget enforcement with dynamic executive configuration and tiered actions (warn/throttle/block)
6. Jarvis UX Features — "Ask Vitto" memory query, brain real-time overlay, introspection drill-down
7. Execution Consolidation — Deprecate AgentProcessService, unify learning pipeline

Progress Tracker

What S209.3 Closed (DO NOT RE-IMPLEMENT)

Section 1: Skills Closed Loop

1.1 Problem

Skill extraction fires on task completion with 4 quality gates. Skill retrieval IS wired into context-assembly (line ~480, Promise.all block). However, the loop is open:

• Retrieval output has no confidence tiers — all skills injected equally regardless of success rate
• No outcome feedback — when a task uses an injected skill, the skill's success/failure count is never updated
• No anti-pattern learning — pattern mining runs only on successes, failures are ignored
• No user control — users cannot pin trusted skills or ban unhelpful ones

1.2 Solution

Close the feedback loop: extraction → storage → retrieval (with confidence tiers) → injection → outcome feedback → quality update. Add anti-pattern mining from failures. Add user skill preferences.

1.3 Confidence-Gated Injection

Modify SkillRetrievalService.getRelevantSkillsPrompt() to tier output by confidence:

Applies to BOTH injection paths:

• context-assembly.service.ts:655 — web chat system prompt
• sub-agent.service.ts:buildSystemPrompt() — sub-agent execution (S209.3 already pulls training data from ai-api)

1.4 Anti-Pattern Learning

Data source problem: Task failures live in execution_traces (vitto-mind DB on backend-vitto-api), but pattern mining runs on backend-ai-api. Solution: backend-vitto-api periodically pushes failed execution summaries to backend-ai-api via the existing postExecutionOutcome() method (already wired in S166). The execution-outcomes collection on ai-agents DB already receives these. mineFailurePatterns() queries this collection — no cross-DB access needed.

New method on PatternMiningJob: mineFailurePatterns()

• Queries execution-outcomes collection where outcome = 'failed' (last 30 days)
• Groups by task type + failure reason similarity
• Threshold: 2+ failures with same approach for same task type → create AntiPattern
• AntiPattern schema mirrors LearnedPattern with additions:
  • avoidReason: string — why this approach fails
  • failureExamples: string[] — concrete examples of failure
• Lifecycle: if a subsequent attempt with the flagged approach succeeds 3 times, the anti-pattern is archived

New file: APIs/backend-ai-api/src/app/learning/schemas/anti-pattern.schema.ts

New endpoint on backend-ai-api: GET /learning/anti-patterns?taskType=...&limit=3 in LearningController — returns anti-patterns for a task type, sorted by frequency descending.

New method on BackendAiClientService: getAntiPatternsForTask(taskType: string) — calls the endpoint above with 2s timeout, graceful fallback to empty array.

Injection in context-assembly: Add anti-patterns as an "AVOID" section (max 3, ~150 tokens) in the Promise.all parallel fetch block at line 481.

1.5 Outcome Feedback to Skills

New field on ExecutionTrace: injectedSkillIds: string[] (defaults to [])

Interface change on ContextAssemblyService.buildWebSystemPrompt():

Current return: Promise<string> (assembled prompt text) New return: Promise<{ prompt: string; injectedSkillIds: string[] }>

This is a breaking change affecting 2 callers:

1. vitto-engine.service.ts:runConversationalLoop() (line ~882) — destructure to get both prompt and skill IDs
2. channel-processing.service.ts (if it calls buildWebSystemPrompt directly) — destructure similarly

Inside buildWebSystemPrompt(): the Promise.all block already calls skillsPrompt = await getRelevantSkillsPrompt(). Modify getRelevantSkillsPrompt() to also return the matched skill IDs alongside the prompt text: { text: string; skillIds: string[] }. The assembly function collects skillIds and returns them.

On task completion:

• runConversationalLoop passes injectedSkillIds to the completion handler
• Cross-reference with task outcome
• If success: increment skill.successCount
• If failure: increment skill.failureCount, recalculate successRate
• If successRate < 0.5 and successCount + failureCount >= 5: set status: 'archived'

For sub-agent path: SubAgentService.buildSystemPrompt() similarly returns { prompt: string; injectedSkillIds: string[] }. The executeTask() method captures and records them.

1.6 User Skill Control

New fields on UserDossier:

skillPreferences: {
  pinnedSkillIds: string[]    // always inject (bypass confidence gate)
  bannedSkillIds: string[]    // never inject (regardless of score)
}

Retrieval service checks these before returning results:

• Pinned skills always included (prepended to results, max 2)
• Banned skills excluded from candidate set

1.7 Unified Learning Pipeline (from S209 plan 3.3)

SubAgentService.executeTask() already calls recordOutcome() on the definition. Add: also call BackendAiClientService.logDecision() to record in ai-agents DB. Single source of truth for all execution outcomes.

1.8 Files to Create/Modify

Section 2: Proactive Intelligence

2.1 Problem

Vitto is reactive. The awareness hub enriches responses when users connect, but Vitto never initiates contact. S209.3 added in-app toasts — but those only work when the user has the web UI open. A real Jarvis reaches you wherever you are, 24/7.

2.2 Solution

Two-layer system with multi-channel dispatch: rule-based triggers for immediate value, pattern-driven proposals for self-improving detection (deferred). Dispatches via user's preferred channel with safety guards.

2.3 Architecture

Trigger fires (existing checks + new)
       ↓
ProactiveDispatcher
  1. Resolve user's preferred channel(s) from dossier
  2. Check safety guards (quiet hours, frequency cap, dedup)
  3. Format message for channel
  4. Fan out to delivery endpoints
       ↓
┌──────────────────┐
│ Web (SSE toast)  │ ← S209.3 DONE (ProactiveToastComponent)
│ WhatsApp         │ ← ChannelGatewayService EXISTS, wire to dispatcher
│ Slack            │ ← ChannelGatewayService EXISTS, wire to dispatcher
│ Email            │ ← Future (not in scope)
└──────────────────┘

2.4 Multi-Channel Fan-Out

For critical alerts (severity = critical): send to ALL active channels simultaneously. For warnings: send to preferred channel only. For info: send to web only (don't spam external channels).

2.5 ProactiveDispatcher Service

New file: APIs/backend-vitto-api/src/app/proactive/proactive-dispatcher.service.ts

Channel resolution chain:

1. userDossier.proactivePreferences.preferredChannel → determines channel TYPE
2. UserNotificationPrefs (existing schema) → contains channel-specific IDs (WhatsApp phone, Slack webhook URL)
3. Fallback: Web (in-app SSE toast, always available — no channel ID needed)

User-to-channel-ID mapping: The dispatcher must resolve userId → channel-specific identifier:

• WhatsApp: UserNotificationPrefs.whatsappPhoneNumber → passed to ChannelGatewayService.sendResponse({ channelType: 'whatsapp', channelId: phoneNumber, text })
• Slack: UserNotificationPrefs.slackWebhookUrl or slackUserId → Slack API
• Web: No mapping needed — emit narrative event via VittoNarrativeService.emitConscience(), ProactiveToastComponent picks it up via SSE

If preferred channel has no configured ID (e.g., user set WhatsApp but never provided phone number): fall back to web with a prompt "Set up WhatsApp notifications in Vitto Settings to get alerts on your phone."

Safety guards:

2.6 Trigger Enhancements

New trigger: QualityDropTrigger — hourly cron, queries execution_traces in vitto-mind:

• Calculate 24h success rate: completed / (completed + failed)
• Compare to 7-day rolling average
• If drop > 15%: fire warning alert with affected task types

2.7 Layer 2: Pattern-Driven Proposals — DEFERRED

PatternProposalService requires sufficient outcome data to produce useful proposals. Deferring until skills closed loop + cost improvements have been running for 2+ weeks generating outcomes. Will be implemented in a follow-up session.

2.8 WhatsApp Delivery

Uses existing ChannelGatewayService (Twilio logic embedded).

Requirements for production:

• 3-5 WhatsApp Business template approvals (alert, reminder, digest, question, status-update)
• Template variables populated from alert context
• Session window awareness: if user replied within 24h, use free-form instead of template

2.9 Files to Create/Modify

Section 3: Dossier Enhancement

3.1 Problem

The dossier is one-directional (hydrates FROM gograb-api, never writes back). Missing fields for proactive intelligence and skill personalization. Space brief (getSpaceBriefForPrompt()) returns empty string — Vitto doesn't know what's in the user's workspace.

3.2 New Fields on UserDossier Schema

// Proactive intelligence preferences
proactivePreferences: {
  enabled: boolean;                          // master toggle, default true
  preferredChannel: 'whatsapp' | 'web' | 'slack' | 'telegram' | 'email';
  quietHoursStart: string;                   // "22:00" in user TZ
  quietHoursEnd: string;                     // "08:00" in user TZ
  dailyAlertCap: number;                     // default 5
  disabledTriggers: string[];                // trigger names user opted out of
}

// Skill personalization
skillPreferences: {
  pinnedSkillIds: string[];
  bannedSkillIds: string[];
}

// Subscription tier (for cost budget resolution)
subscriptionTier: 'free' | 'pro' | 'business' | 'enterprise' | 'internal';

// Sync metadata
syncMetadata: {
  lastSyncToGograb: Date;
  lastSyncFromGograb: Date;
  pendingSyncFields: string[];
}

3.3 Bidirectional Sync

New service: DossierSyncService

Outbound (Vitto → gograb-api): Only high-value enrichments:

• personality.knownFacts[] — platform personalizes UI/recommendations
• expertise.technologies[] — platform suggests relevant spaces/modules
• personality.communicationStyle — platform adapts email tone
• proactivePreferences.preferredChannel — platform can also route non-Vitto notifications

Mechanism: Event-driven, debounced. 15-minute cron batch-syncs dirty dossiers (limit 50). Platform (gograb-api) wins on field conflicts.

Outbound target: PUT ${BACKEND_API_URL}/api/users/:userId/profile-enrichment on backend-api (port 3000). This endpoint must be created on gograb-api to accept partial profile updates from Vitto. Auth: BACKEND_API_INTERNAL_TOKEN as Bearer. Request shape: { knownFacts?: string[], technologies?: string[], communicationStyle?: string, preferredChannel?: string }. If the endpoint doesn't exist yet, add it to UserProfileController on backend-api with @UseGuards(SystemTokenGuard) (internal service-to-service only).

Inbound: Existing hydration + staleness check: if lastSyncFromGograb > 24h, re-hydrate on next getDossierForPrompt().

3.4 Wire Space Brief

Implement getSpaceBriefForPrompt() (currently returns empty string):

Output (~300 tokens):

SPACE CONTEXT — "Soccer Club Pro":
Business: Sports management platform (growing maturity, 5 modules generated)
Modules: player-management, team-roster, match-tracking, training-scheduler, fan-engagement
Last generation: 2 days ago, 4/5 modules succeeded
User role: Admin (roleLevel 90), 47 interactions, prefers dashboards
Recent: Added training-scheduler module, requested fan analytics next

3.5 Dialectic Enrichment

Intent-based (not random): on the first 3 interactions with a new user, always ask one missing critical field. After that, only when the field would directly improve the current response.

Critical fields (priority order):

1. expertise.technologies — what the user works with
2. personality.communicationStyle — concise vs detailed
3. identity.timezone — for quiet hours
4. workPatterns.preferredWorkflow — how they like to work

One field per message maximum.

3.6 Files to Create/Modify

Section 4: Golden Path Tests

4.1 Problem

Zero automated tests for agent behavior. Any engine change could silently break workflows.

4.2 Architecture

Tier 1: Behavioral Contracts (CI, every commit)
  JSON fixture → MockLLM → Engine → Assert
  - Deterministic, <30s, $0

Tier 2: Integration Smokes (nightly)
  JSON fixture → Real Haiku → Engine → Soft Assert
  - Non-deterministic, ~2min, ~$0.05/run

4.3 Tier 1: Behavioral Contracts (28 scenarios)

Original 25 from spec + 3 new S209.3 scenarios.

Note: Scenarios that test features from later sub-projects (e.g., GP-004 tests anti-patterns from Sub-project 2) ship as skipped in Sub-project 1, with a @skip marker and dependsOn field in the fixture. They auto-enable when the dependent feature lands. This lets CI stay green while building incrementally.

4.4 Files to Create

Section 5: Cost Improvements

5.1 Problem

Cost tracking exists (getCostByFeature(), CostAlertService). No per-feature budget enforcement. Users can't be throttled per-feature — only global iteration/token limits exist.

5.2 Dynamic Budget Configuration

All budgets stored in MongoDB (feature_budget_configs collection), managed by executives (roleLevel >= 90).

interface FeatureBudgetConfig {
  caller: string;
  displayName: string;
  tiers: {
    free: { maxCostPerRun: number; dailyCap: number; action: 'warn' | 'throttle' | 'block' };
    pro: { maxCostPerRun: number; dailyCap: number; action: 'warn' | 'throttle' | 'block' };
    business: { maxCostPerRun: number; dailyCap: number; action: 'warn' | 'throttle' | 'block' };
    enterprise: { maxCostPerRun: number; dailyCap: number; action: 'warn' | 'throttle' | 'block' };
    internal: { maxCostPerRun: number; dailyCap: number; action: 'warn' | 'throttle' | 'block' };
  };
  globalEnabled: boolean;
  overrides: Array<{
    targetType: 'user' | 'space';
    targetId: string;
    maxCostPerRun: number;
    dailyCap: number;
    action: 'warn' | 'throttle' | 'block';
    reason: string;
    setBy: string;
    expiresAt?: Date;
  }>;
  lastModifiedBy: string;
  lastModifiedAt: Date;
}

5.3 Budget Enforcement Actions

Wire to ProactiveDispatcher: warn action triggers multi-channel alert: "Module generation has used 80% of today's budget. Shall I switch to a lighter model?"

5.4 Resolution Chain

1. User-specific override (if exists and not expired)
2. Space-specific override (if exists and not expired)
3. User's subscription tier config (from dossier.subscriptionTier)
4. Feature globally disabled? → block all

5.5 Files to Create/Modify

Section 6: Jarvis UX Features (from S209 plan)

6.1 "Ask Vitto" Memory Query (S209 item 2.4)

Users ask "what do you know about auth?" and get a synthesized answer — not a memory list.

Backend: New route on MindController (APIs/backend-vitto-api/src/app/mind/mind.controller.ts): GET /mind/memory/ask?query=...&userId=...

• MindService.askMemory(query, userId) — vector search on memories matching query
• Uses Haiku to synthesize 2-3 sentence answer from top matches
• Returns { answer: string; sources: Memory[] }

Frontend: New method askMemory(query, userId) on VittoApiService (@libs-ai/vitto-core) calling GET ${VITTO_API_URL}/mind/memory/ask. Search bar above memory list in memory-manager.component.html. Result shown as conversational card with clickable source links.

Files: mind.controller.ts (add route), mind.service.ts (add askMemory()), vitto-api.service.ts (add frontend method), memory-manager.component.* (add search UI).

6.2 Brain Real-Time Activity Overlay (S209 item 2.5)

Brain visualization pulses with real-time conscience events.

Map conscience categories to brain regions:

• memory → Memory region
• skill → Skills region
• context → Context region
• trust → Trust region
• dossier → Identity region
• personality → Soul core

Animation: CSS region--active class with 2s glow/pulse, auto-removes. signal<Set<string>> tracks active regions.

6.3 Introspection Drill-Down (S209 item 2.6)

If introspection entry has taskId: [routerLink]="['/vitto/queue']" with ?taskId=... If entry has userId: render as [routerLink]="['/vitto/dossier', entry.userId]"

Section 7: Execution Consolidation (from S209 plan Phase 3)

7.1 Deprecate AgentProcessService Execute Endpoints (S209 item 3.1)

1. Add deprecation warning to POST /ai-api/agent-process/execute (SSE) and POST /ai-api/agent-process/execute-sync
2. Create equivalent endpoints on backend-vitto-api:
   • New controller: APIs/backend-vitto-api/src/app/engine/agent-process-compat.controller.ts
   • Route prefix: /engine/agent-process (maps to VITTO_API_URL/engine/agent-process/execute)
   • Request type: mirror AgentExecuteRequest from APIs/backend-ai-api/src/app/agentic-process/types/agent-process.types.ts
   • Internally delegates to SubAgentService.executeTask() after mapping the request shape
3. Frontend AgentExecutorService (libs/libs-ai/ai-agents-training-center/src/lib/services/agent-executor/agent-executor.service.ts) switches injection from AI_API_URL to VITTO_API_URL
4. Keep old endpoints alive with Logger.warn('DEPRECATED: use VITTO_API_URL/engine/agent-process/execute') for 1 session

7.2 Move Unique AgentProcessService Logic to Vitto (S209 item 3.2)

1. Extract MATCH phase (pattern matching) into reusable service
2. Extract VALIDATE phase (code quality checks) into reusable service
3. Wire both as optional phases in SubAgentService.executeTask()
4. Sub-agent definitions opt into validation: definition.enableValidation: boolean

Cross-Cutting: Integration Map

Skills ←→ Dossier (skill preferences pin/ban)
Skills ←→ Golden Paths (GP-003, GP-004 test skill/anti-pattern injection)
Skills ←→ Cost (skill-extraction has budget cap)
Proactive ←→ Dossier (channel preference, quiet hours, opt-out)
Proactive ←→ Cost (CostSpikeTrigger uses per-feature data, warn action fires dispatcher)
Proactive ←→ Golden Paths (GP-022 to GP-025 test proactive behavior)
Golden Paths ←→ Anti-Patterns (3x test failure → auto-created anti-pattern)
Cost ←→ Dossier (subscriptionTier for budget resolution)
Jarvis UX ←→ Dossier (memory query uses dossier context)
Jarvis UX ←→ Conscience (brain overlay subscribes to SSE)

Shared Integration Point: context-assembly.service.ts

All subsystems converge in the parallel fetch block:

Existing:                    New:
- User knowledge             - Confidence-tiered skills (Section 1)
- Memory recall              - Anti-pattern AVOID section (Section 1)
- Semantic recall             - Space brief wired (Section 3)
- Channel history             - Dialectic enrichment hints (Section 3)
- Learning intelligence       - injectedSkillIds tracking (Section 1)
- Awareness hub
- User brief
- Knowledge graph
- Space profile
- Executive instructions
- User dossier

Token Budget Impact

Current system prompt: ~40K tokens (within 60K budget). New additions: ~800 tokens (skills ~300, anti-patterns ~150, space brief ~300, enrichment hint ~50). Total: ~40.8K tokens — well within budget.

Implementation Priority (Build Order)

Sub-project 1: Golden Path Tests (Tier 1)              ~1 sub-session
  Safety net for everything below
  28 behavioral contracts, MockLLM, CI integration

Sub-project 2: Skills Closed Loop                       ~1 sub-session
  Confidence tiers + outcome feedback + anti-patterns
  Includes unified learning pipeline (S209 item 3.3)

Sub-project 3: Dossier Enhancement                      ~1 sub-session
  proactivePreferences + space brief + dialectic enrichment
  Includes "Ask Vitto" memory query (S209 item 2.4)

Sub-project 4: ProactiveDispatcher + Channel Wiring     ~1 sub-session
  Multi-channel delivery + safety guards + QualityDropTrigger
  THE Jarvis feature — reach users everywhere 24/7

Sub-project 5: Cost Improvements                        ~1 sub-session
  Per-feature budgets + enforcement + executive config

Sub-project 6: UX Polish + Tier 2 Tests                 ~0.5 sub-session
  Brain overlay (6.2) + Introspection drill-down (6.3)
  Golden Path Tier 2 integration smokes

Sub-project 7: Execution Consolidation                  ~1 sub-session
  Deprecate AgentProcessService (7.1) + Move MATCH/VALIDATE (7.2)

Total: ~6.5 sub-sessions across 2-3 sessions

What's NOT In This Spec (and Why)

Original: March 12, 2026 — S208 Design Session Updated: March 12, 2026 — S210 Session (post S209.3 implementation, gap analysis, Jarvis vision alignment)