sinapse-ai 9.2.0 → 9.3.0

package/squads/squad-storytelling/knowledge-base/story-circle-dan-harmon.md

@@ -0,0 +1,171 @@
+# Story Circle — Dan Harmon Deep Reference
+
+> Version: 1.0.0 | Agent: dan-harmon | Domain: tv-episodic, character-driven
+
+## Overview
+
+Dan Harmon developed the Story Circle while running Channel 101 and later as showrunner of Community (NBC). It is the most practical and approachable narrative framework ever created — a compression of Campbell's monomyth into 8 steps that can be drawn as a circle and applied at any story scale.
+
+**Origin:** Harmon kept failing to write stories that felt satisfying. He obsessively studied structure until he found the minimum viable unit of story. The circle was the result.
+
+---
+
+## The 8-Step Story Circle
+
+```
+                    YOU (1)
+                 /           \
+          CHANGE (8)         NEED (2)
+         /                         \
+    RETURN (7)                   GO (3)
+         \                         /
+          TAKE (6)            SEARCH (4)
+                 \           /
+                   FIND (5)
+```
+
+| Step | Name | Description |
+|------|------|-------------|
+| **1** | **YOU** | A character exists in their zone of comfort — the familiar world, the status quo. |
+| **2** | **NEED** | Something is needed or wanted — a lack, a desire, a problem that demands attention. |
+| **3** | **GO** | The character enters an unfamiliar situation — crosses the threshold into the unknown. |
+| **4** | **SEARCH** | The character adapts to the unfamiliar, struggles, fails, learns — the messy middle. |
+| **5** | **FIND** | The character gets what they wanted — the apparent goal is achieved. |
+| **6** | **TAKE** | The character pays a price — getting what you want always costs something. |
+| **7** | **RETURN** | The character returns to their familiar situation — transformed. |
+| **8** | **CHANGE** | The character has changed — they are different from who they were in step 1. |
+
+---
+
+## The Circle as Philosophy
+
+The circle encodes a profound truth: **every meaningful story is about change, and change requires cost.**
+
+The top half of the circle is the **comfortable, familiar world** (consciousness/daytime).
+The bottom half is the **unfamiliar, dangerous world** (unconscious/nighttime).
+
+Crossing into the bottom half is always a choice. The step from GO to SEARCH is the "yes" that makes the story happen. The step from RETURN to CHANGE is the proof that something real occurred.
+
+**Harmon's core insight:** If someone wants something, goes somewhere, struggles, gets it, but there's no cost and no change — it's not a story. It's a sequence of events.
+
+---
+
+## The Fractal Property
+
+The Story Circle works at every scale simultaneously:
+
+| Scale | Example |
+|-------|---------|
+| **Series** | Breaking Bad: Walter White (YOU) needs money → goes into drugs (GO) → becomes Heisenberg (FIND) → loses family (TAKE) → admits the truth (CHANGE) |
+| **Season** | Each season of Community follows a full circle arc |
+| **Episode** | A single episode follows the complete circle |
+| **Scene** | A 3-minute conversation can have all 8 steps |
+| **Beat** | A single moment of realization is a micro-circle |
+
+This is why great TV feels simultaneously satisfying in each individual scene AND across the full series — the fractal is operational at all levels.
+
+---
+
+## Characters Have Needs AND Goals
+
+Harmon distinguishes between what the character **wants** (the goal, the conscious desire) and what the character **needs** (the deeper lack, often unconscious):
+
+- **Want:** External objective — what the plot is about
+- **Need:** Internal wound — what the story is really about
+
+The character achieves the WANT by the midpoint (step 5). The NEED is only resolved by CHANGE (step 8). The want and need are usually in tension. Getting the want often prevents getting the need — until the character learns to sacrifice the want.
+
+**Example — Community's Jeff Winger:**
+- Want: Fake his way through college, avoid genuine connection
+- Need: Authentic friendship and belonging
+- The story only works because these are in conflict
+
+---
+
+## Applying the Story Circle to Business Content
+
+### For Customer Stories
+```
+YOU:     [Customer before your product — their daily reality]
+NEED:    [The specific problem or desire that was nagging them]
+GO:      [The decision to try your solution — crossing the threshold]
+SEARCH:  [The learning curve, the first attempts, the friction]
+FIND:    [The moment it clicked — the specific win]
+TAKE:    [What they had to give up or change — honesty adds credibility]
+RETURN:  [Back to daily work, but now different]
+CHANGE:  [How they see themselves and their work differently now]
+```
+
+### For Personal Brand Content
+```
+YOU:     [Who I was before the insight]
+NEED:    [What was missing or broken in my thinking]
+GO:      [The decision to explore, experiment, or change]
+SEARCH:  [The struggle, the failure, the confusion]
+FIND:    [The realization, the discovery, the breakthrough]
+TAKE:    [What I had to let go of — an old belief, a comfortable habit]
+RETURN:  [Back to practice, but with new understanding]
+CHANGE:  [How my work is different now]
+```
+
+### For Brand Origin Stories
+```
+YOU:     [The founder in the ordinary world — their expertise, their frustration]
+NEED:    [The market gap or problem they couldn't ignore]
+GO:      [The decision to build — quitting the job, starting the company]
+SEARCH:  [The early struggles, the pivots, the failures]
+FIND:    [The product-market fit, the first real win]
+TAKE:    [The cost — relationships strained, resources depleted, years spent]
+RETURN:  [Back to the market, now with a real solution]
+CHANGE:  [The company and the founder as a different entity]
+```
+
+---
+
+## The Story Circle vs. The Hero's Journey
+
+| Dimension | Hero's Journey (Campbell) | Story Circle (Harmon) |
+|-----------|--------------------------|----------------------|
+| Steps | 17 (Campbell) / 12 (Vogler) | 8 |
+| Complexity | High — requires deep study | Low — learnable in one session |
+| Scale | Macro (epics, films, myths) | Any scale (scene to series) |
+| Emphasis | External journey and transformation | Internal need and change |
+| Best for | Epic narratives, brand mythology | TV, episodic, any practical writing |
+| Overlap | Stages 1-5 map to Departure/Initiation | Compression of the same pattern |
+
+---
+
+## Episode Structure Application
+
+For a 22-minute sitcom episode (Community model):
+
+| Step | Approx. Time | What Happens |
+|------|-------------|--------------|
+| YOU | 0:00-2:00 | Character in normal context |
+| NEED | 2:00-4:00 | Problem or desire established |
+| GO | 4:00-6:00 | Character commits to a course of action |
+| SEARCH | 6:00-14:00 | The long middle — obstacles, escalating complications |
+| FIND | 14:00-16:00 | Apparent resolution — gets what they wanted |
+| TAKE | 16:00-18:00 | Cost becomes clear — it wasn't worth it, or came with conditions |
+| RETURN | 18:00-20:00 | Back to the original world |
+| CHANGE | 20:00-22:00 | Reflection, transformation, new state |
+
+---
+
+## Common Story Circle Failures
+
+| Failure | Diagnosis | Fix |
+|---------|-----------|-----|
+| No real change in step 8 | The character just had an adventure | The final state must differ from step 1 |
+| No cost in step 6 | Story feels too easy | What does getting the want cost? |
+| Skipping step 4 | Story resolves too quickly | The search needs real struggle and failure |
+| Want = Need | No internal conflict | Separate external goal from internal wound |
+| The circle is too tidy | Story feels mechanical | The circle is a diagnostic, not a recipe |
+
+---
+
+## Cross-Reference
+
+- **Campbell's Monomyth** is the mythic substrate — Harmon's circle is its practical compression
+- **Blake Snyder's Beat Sheet** maps similarly but focuses on commercial screenplay structure
+- **Kindra Hall's Normal-Explosion-New Normal** is a further compression for business stories

package/.sinapse-ai/core/health-check/checks/services/gemini-cli.js

@@ -1,239 +0,0 @@
-/**
- * Gemini CLI Check
- *
- * Verifies Gemini CLI installation, authentication, and configuration.
- * Detects available features including Preview features, Extensions, and Hooks.
- *
- * @module sinapse-ai/health-check/checks/services/gemini-cli
- * @version 1.0.0
- * @story GEMINI-INT Story 1 - Gemini CLI Health Check & Detection
- */
-
-const fs = require('fs').promises;
-const path = require('path');
-const os = require('os');
-const { execSync } = require('child_process');
-const { BaseCheck, CheckSeverity, CheckDomain } = require('../../base-check');
-
-/**
- * Gemini CLI check
- *
- * @class GeminiCliCheck
- * @extends BaseCheck
- */
-class GeminiCliCheck extends BaseCheck {
-  constructor() {
-    super({
-      id: 'services.gemini-cli',
-      name: 'Gemini CLI',
-      description: 'Verifies Gemini CLI installation and configuration',
-      domain: CheckDomain.SERVICES,
-      severity: CheckSeverity.LOW,
-      timeout: 5000,
-      cacheable: true,
-      healingTier: 0,
-      tags: ['gemini', 'google', 'ai', 'cli'],
-    });
-  }
-
-  /**
-   * Execute the check
-   * @param {Object} context - Execution context
-   * @returns {Promise<Object>} Check result
-   */
-  async execute(context) {
-    const projectRoot = context.projectRoot || process.cwd();
-    const homeDir = os.homedir();
-
-    const details = {
-      installed: false,
-      version: null,
-      authenticated: false,
-      projectConfig: false,
-      globalConfig: false,
-      features: {
-        previewFeatures: false,
-        hooks: false,
-        extensions: [],
-      },
-    };
-
-    // Check if gemini is installed
-    try {
-      const version = execSync('gemini --version', {
-        encoding: 'utf8',
-        timeout: 5000,
-        windowsHide: true,
-      }).trim();
-
-      details.installed = true;
-      details.version = version;
-    } catch {
-      // Not installed
-    }
-
-    // Check authentication status
-    if (details.installed) {
-      try {
-        const authStatus = execSync('gemini auth status 2>&1', {
-          encoding: 'utf8',
-          timeout: 5000,
-          windowsHide: true,
-        });
-        details.authenticated = !authStatus.toLowerCase().includes('not authenticated');
-      } catch {
-        details.authenticated = false;
-      }
-    }
-
-    // Check project .gemini directory
-    try {
-      const geminiDir = path.join(projectRoot, '.gemini');
-      await fs.access(geminiDir);
-      details.projectConfig = true;
-
-      // Check for rules.md (SINAPSE rules)
-      try {
-        await fs.access(path.join(geminiDir, 'rules.md'));
-        details.hasProjectRules = true;
-      } catch {
-        details.hasProjectRules = false;
-      }
-
-      // Check for settings.json (hooks, extensions config)
-      try {
-        const settingsPath = path.join(geminiDir, 'settings.json');
-        const settingsContent = await fs.readFile(settingsPath, 'utf8');
-        const settings = JSON.parse(settingsContent);
-
-        // Check for hooks configuration
-        if (settings.hooks && Object.keys(settings.hooks).length > 0) {
-          details.features.hooks = true;
-          details.features.hookEvents = Object.keys(settings.hooks);
-        }
-
-        // Check for preview features
-        if (settings.previewFeatures === true) {
-          details.features.previewFeatures = true;
-        }
-      } catch {
-        // No settings.json or invalid JSON
-      }
-
-      // Check for SINAPSE agents
-      try {
-        const agentsDir = path.join(geminiDir, 'rules', 'SINAPSE', 'agents');
-        const agentFiles = await fs.readdir(agentsDir);
-        details.sinapseAgents = agentFiles.filter((f) => f.endsWith('.md')).length;
-      } catch {
-        details.sinapseAgents = 0;
-      }
-    } catch {
-      // No project config
-    }
-
-    // Check global config (~/.gemini or similar)
-    try {
-      const globalGeminiDir = path.join(homeDir, '.gemini');
-      await fs.access(globalGeminiDir);
-      details.globalConfig = true;
-
-      // Check global settings
-      try {
-        const globalSettingsPath = path.join(globalGeminiDir, 'settings.json');
-        const globalSettings = JSON.parse(await fs.readFile(globalSettingsPath, 'utf8'));
-
-        if (globalSettings.previewFeatures === true) {
-          details.features.previewFeatures = true;
-        }
-      } catch {
-        // No global settings
-      }
-    } catch {
-      // No global config
-    }
-
-    // Check for installed extensions
-    if (details.installed) {
-      try {
-        const extensionsList = execSync('gemini extensions list --output-format json 2>/dev/null', {
-          encoding: 'utf8',
-          timeout: 10000,
-          windowsHide: true,
-        });
-        const extensions = JSON.parse(extensionsList);
-        if (Array.isArray(extensions)) {
-          details.features.extensions = extensions.map((e) => e.name || e);
-        }
-      } catch {
-        // Extensions command not available or failed
-      }
-    }
-
-    // Not using Gemini CLI
-    if (!details.installed && !details.projectConfig && !details.globalConfig) {
-      return this.pass('Gemini CLI not detected (not using Gemini CLI)', {
-        details,
-      });
-    }
-
-    const issues = [];
-    const warnings = [];
-
-    // Check for issues
-    if (details.installed && !details.authenticated) {
-      issues.push('Not authenticated');
-    }
-
-    if (!details.projectConfig) {
-      warnings.push('No project-level .gemini directory');
-    }
-
-    if (details.projectConfig && !details.hasProjectRules) {
-      warnings.push('Project .gemini/rules.md not found');
-    }
-
-    if (details.projectConfig && details.sinapseAgents === 0) {
-      warnings.push('No SINAPSE agents installed for Gemini CLI');
-    }
-
-    if (!details.features.previewFeatures) {
-      warnings.push('Preview features not enabled (needed for Gemini 3)');
-    }
-
-    // Return result based on severity
-    if (issues.length > 0) {
-      return this.warning(`Gemini CLI needs attention: ${issues.join(', ')}`, {
-        recommendation: issues.includes('Not authenticated')
-          ? 'Run `gemini` to authenticate with your Google account'
-          : 'Run `npx sinapse-ai install` and select Gemini CLI',
-        details: { ...details, issues, warnings },
-      });
-    }
-
-    if (warnings.length > 0) {
-      return this.warning(`Gemini CLI configuration incomplete: ${warnings.join(', ')}`, {
-        recommendation: 'Run `npx sinapse-ai install` and select Gemini CLI',
-        details: { ...details, warnings },
-      });
-    }
-
-    // Build success message
-    const parts = [];
-    if (details.installed) parts.push(`CLI v${details.version}`);
-    if (details.authenticated) parts.push('authenticated');
-    if (details.projectConfig) parts.push('project config');
-    if (details.features.previewFeatures) parts.push('preview features');
-    if (details.features.hooks) parts.push(`${details.features.hookEvents.length} hooks`);
-    if (details.features.extensions.length > 0) {
-      parts.push(`${details.features.extensions.length} extensions`);
-    }
-    if (details.sinapseAgents > 0) parts.push(`${details.sinapseAgents} SINAPSE agents`);
-
-    return this.pass(`Gemini CLI configured (${parts.join(', ')})`, {
-      details,
-    });
-  }
-}
-
-module.exports = GeminiCliCheck;

package/.sinapse-ai/core/orchestration/gemini-model-selector.js

@@ -1,161 +0,0 @@
-/**
- * Gemini Model Selector
- * Story GEMINI-INT.16 - Dynamic Model Switching
- *
- * Automatically selects between Gemini Flash and Pro based on task complexity.
- */
-
-const { TaskComplexityClassifier } = require('./task-complexity-classifier');
-
-/**
- * Model configuration
- */
-const MODELS = {
-  flash: {
-    id: 'gemini-2.0-flash',
-    costPer1kTokens: 0.000125,
-    maxTokens: 32000,
-    bestFor: ['simple', 'medium'],
-  },
-  pro: {
-    id: 'gemini-2.0-pro',
-    costPer1kTokens: 0.00125,
-    maxTokens: 128000,
-    bestFor: ['complex'],
-  },
-};
-
-/**
- * Agent-based model overrides
- * Keys match agent IDs (without @ prefix)
- */
-const AGENT_OVERRIDES = {
-  architect: 'pro',
-  analyst: 'pro',
-  qa: 'flash',
-  pm: 'flash',
-  dev: 'auto',
-  devops: 'flash',
-};
-
-class GeminiModelSelector {
-  constructor(config = {}) {
-    this.classifier = new TaskComplexityClassifier();
-    this.defaultModel = config.defaultModel || 'flash';
-    this.agentOverrides = { ...AGENT_OVERRIDES, ...config.agentOverrides };
-    this.qualityFallback = config.qualityFallback !== false;
-    this.minQualityScore = config.minQualityScore || 0.6;
-
-    // Usage tracking
-    this.usage = {
-      flash: { count: 0, tokens: 0, cost: 0 },
-      pro: { count: 0, tokens: 0, cost: 0 },
-    };
-  }
-
-  /**
-   * Select model for a task
-   * @param {Object} task - Task to analyze
-   * @param {string} agentId - Agent handling the task
-   * @returns {Object} Model selection
-   */
-  selectModel(task, agentId = null) {
-    // Normalize agentId (remove @ prefix if present)
-    const normalizedAgentId = agentId?.replace(/^@/, '') || null;
-
-    // Check agent override first
-    if (normalizedAgentId && this.agentOverrides[normalizedAgentId]) {
-      const override = this.agentOverrides[normalizedAgentId];
-      if (override !== 'auto') {
-        return this._buildSelection(override, 'agent_override', normalizedAgentId);
-      }
-    }
-
-    // Classify task complexity
-    const complexity = this.classifier.classify(task);
-
-    // Select based on complexity
-    let model = this.defaultModel;
-
-    if (complexity.level === 'complex' || complexity.score > 0.7) {
-      model = 'pro';
-    } else if (complexity.level === 'simple' || complexity.score < 0.3) {
-      model = 'flash';
-    }
-
-    return this._buildSelection(model, 'complexity', complexity);
-  }
-
-  /**
-   * Handle quality fallback
-   * @param {string} originalModel - Model that was used
-   * @param {number} qualityScore - Quality score of response
-   * @returns {Object|null} Fallback recommendation or null
-   */
-  handleQualityFallback(originalModel, qualityScore) {
-    if (!this.qualityFallback) return null;
-
-    if (originalModel === 'flash' && qualityScore < this.minQualityScore) {
-      return {
-        shouldRetry: true,
-        newModel: 'pro',
-        reason: `Quality score ${qualityScore} below threshold ${this.minQualityScore}`,
-      };
-    }
-
-    return null;
-  }
-
-  /**
-   * Track model usage
-   * @param {string} model - Model used
-   * @param {number} tokens - Tokens consumed
-   */
-  trackUsage(model, tokens) {
-    const modelKey = model.includes('flash') ? 'flash' : 'pro';
-    const modelConfig = MODELS[modelKey];
-
-    this.usage[modelKey].count++;
-    this.usage[modelKey].tokens += tokens;
-    this.usage[modelKey].cost += (tokens / 1000) * modelConfig.costPer1kTokens;
-  }
-
-  /**
-   * Get usage statistics
-   */
-  getUsageStats() {
-    const total = {
-      count: this.usage.flash.count + this.usage.pro.count,
-      tokens: this.usage.flash.tokens + this.usage.pro.tokens,
-      cost: this.usage.flash.cost + this.usage.pro.cost,
-    };
-
-    return {
-      ...this.usage,
-      total,
-      flashRatio: total.count > 0 ? this.usage.flash.count / total.count : 0,
-      costSavings: this._calculateCostSavings(),
-    };
-  }
-
-  _buildSelection(model, reason, details) {
-    const modelConfig = MODELS[model];
-    return {
-      model: modelConfig.id,
-      modelKey: model,
-      reason,
-      details,
-      config: modelConfig,
-    };
-  }
-
-  _calculateCostSavings() {
-    // Calculate how much was saved by using Flash instead of Pro
-    const flashTokens = this.usage.flash.tokens;
-    const proOnlyCost = (flashTokens / 1000) * MODELS.pro.costPer1kTokens;
-    const actualCost = this.usage.flash.cost;
-    return proOnlyCost - actualCost;
-  }
-}
-
-module.exports = { GeminiModelSelector, MODELS, AGENT_OVERRIDES };

package/.sinapse-ai/hooks/gemini/after-tool.js

@@ -1,77 +0,0 @@
-#!/usr/bin/env node
-/**
- * SINAPSE After Tool Hook for Gemini CLI
- * Story GEMINI-INT.6 - SINAPSE Hooks System
- *
- * Executes after tool completion for audit logging.
- */
-
-const fs = require('fs');
-const path = require('path');
-
-async function afterTool() {
-  const input = process.argv[2] ? JSON.parse(process.argv[2]) : {};
-  const toolName = input.tool || '';
-  const toolResult = input.result || {};
-
-  // Log execution result
-  logToolResult(toolName, toolResult);
-
-  // Track file modifications
-  if (toolName === 'write_file' || toolName === 'replace' || toolName === 'edit') {
-    trackFileModification(input.args?.path || input.args?.file_path);
-  }
-
-  console.log(JSON.stringify({ status: 'success' }));
-  process.exit(0);
-}
-
-function logToolResult(tool, result) {
-  try {
-    const projectDir = process.env.GEMINI_PROJECT_DIR || process.cwd();
-    const logDir = path.join(projectDir, '.sinapse', 'logs');
-
-    if (!fs.existsSync(logDir)) {
-      fs.mkdirSync(logDir, { recursive: true });
-    }
-
-    const logEntry = {
-      timestamp: new Date().toISOString(),
-      tool,
-      success: result.success !== false,
-      provider: 'gemini',
-      sessionId: process.env.GEMINI_SESSION_ID,
-    };
-
-    const logPath = path.join(logDir, 'tool-results.jsonl');
-    fs.appendFileSync(logPath, JSON.stringify(logEntry) + '\n');
-  } catch (error) {
-    // Non-critical
-  }
-}
-
-function trackFileModification(filePath) {
-  if (!filePath) return;
-
-  try {
-    const projectDir = process.env.GEMINI_PROJECT_DIR || process.cwd();
-    const trackPath = path.join(projectDir, '.sinapse', 'session-files.json');
-
-    let files = [];
-    if (fs.existsSync(trackPath)) {
-      files = JSON.parse(fs.readFileSync(trackPath, 'utf8'));
-    }
-
-    if (!files.includes(filePath)) {
-      files.push(filePath);
-      fs.writeFileSync(trackPath, JSON.stringify(files, null, 2));
-    }
-  } catch (error) {
-    // Non-critical
-  }
-}
-
-afterTool().catch((error) => {
-  console.log(JSON.stringify({ status: 'error', error: error.message }));
-  process.exit(0);
-});