sinapse-ai 7.5.2 → 7.7.0

package/.claude/hooks/write-path-validation.cjs

@@ -0,0 +1,132 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * Hook: Write Path Validation (CJS port)
+ *
+ * RULE: Documentation files should go to the correct paths per conventions.
+ *       This hook WARNS (never blocks) when a doc path looks wrong.
+ *
+ * Protocol: always exit 0 (warn-only, never blocks).
+ *
+ * @module write-path-validation
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+// ---------------------------------------------------------------------------
+// Configuration
+// ---------------------------------------------------------------------------
+
+const PATH_RULES = [
+  {
+    namePatterns: [/session/i, /handoff/i, /^2\d{3}-\d{2}-\d{2}/],
+    expectedPath: 'docs/sessions/',
+    description: 'Session logs e handoffs → docs/sessions/YYYY-MM/',
+  },
+  {
+    namePatterns: [/architecture/i, /system-design/i, /infra/i],
+    expectedPath: 'docs/architecture/',
+    description: 'Docs de arquitetura → docs/architecture/',
+    excludePatterns: [/ARCHITECTURE_RULES/i],
+  },
+  {
+    namePatterns: [/guide/i, /tutorial/i, /how-to/i],
+    expectedPath: 'docs/guides/',
+    description: 'Guias e tutoriais → docs/guides/',
+  },
+  {
+    namePatterns: [/prd\.md$/i, /epic.*\.md$/i, /story.*\.md$/i],
+    expectedPath: 'docs/projects/',
+    description: 'PRDs, Epics, Stories → docs/projects/{project}/',
+  },
+  {
+    namePatterns: [/mind.*specific/i, /mind.*validation/i],
+    expectedPath: 'outputs/minds/',
+    description: 'Docs de mind → outputs/minds/{slug}/docs/',
+  },
+];
+
+const ALWAYS_VALID = [
+  '.claude/', '.sinapse-ai/', '.sinapse-upstream/', 'squads/',
+  'node_modules/', '.git/', 'app/', 'supabase/', 'outputs/',
+];
+
+const DOC_EXTENSIONS = ['.md', '.mdx', '.txt', '.rst'];
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function projectRoot() {
+  return process.env.CLAUDE_PROJECT_DIR || process.cwd();
+}
+
+function relativize(filePath, root) {
+  if (filePath.startsWith(root)) return filePath.slice(root.length).replace(/^[/\\]+/, '');
+  return filePath;
+}
+
+function isAlwaysValid(rel) {
+  return ALWAYS_VALID.some((v) => rel.startsWith(v));
+}
+
+function isDocFile(rel) {
+  return DOC_EXTENSIONS.some((ext) => rel.endsWith(ext));
+}
+
+function checkRules(rel) {
+  const filename = path.basename(rel);
+  for (const rule of PATH_RULES) {
+    const matchesName = rule.namePatterns.some((p) => p.test(filename));
+    if (!matchesName) continue;
+
+    if (rule.excludePatterns && rule.excludePatterns.some((p) => p.test(filename))) continue;
+
+    if (!rel.startsWith(rule.expectedPath)) {
+      return { currentPath: rel, expectedPath: rule.expectedPath, description: rule.description };
+    }
+  }
+  return null;
+}
+
+// ---------------------------------------------------------------------------
+// Main
+// ---------------------------------------------------------------------------
+
+function main() {
+  let input;
+  try {
+    input = JSON.parse(fs.readFileSync(0, 'utf8'));
+  } catch {
+    process.exit(0);
+  }
+
+  const toolName = input.tool_name || '';
+  if (toolName !== 'Write' && toolName !== 'Edit') process.exit(0);
+
+  const filePath = (input.tool_input || {}).file_path || '';
+  if (!filePath) process.exit(0);
+
+  const root = projectRoot();
+  const rel = relativize(filePath, root);
+
+  if (isAlwaysValid(rel)) process.exit(0);
+  if (!isDocFile(rel)) process.exit(0);
+
+  const violation = checkRules(rel);
+  if (!violation) process.exit(0);
+
+  // WARN only — never block
+  process.stderr.write(
+    `\nPATH WARNING: Document may be in the wrong location.\n` +
+    `  File:     ${violation.currentPath}\n` +
+    `  Expected: ${violation.expectedPath}\n` +
+    `  Rule:     ${violation.description}\n` +
+    `  NOTE: This is a WARNING only — the operation will proceed.\n`,
+  );
+  process.exit(0);
+}
+
+main();

package/.claude/rules/agent-handoff.md

@@ -44,6 +44,18 @@ The incoming agent receives:
 2. The **handoff artifact** from the previous agent (compact summary)
 3. **NOT** the previous agent's full persona/instructions/tool definitions
 
+### Scratchpad Protocol (v1.1)
+
+**Before starting work**, the incoming agent MUST:
+1. Check if `.sinapse/scratchpad/{story-id}/` exists
+2. If yes, read ALL files in that directory (discoveries from previous agents)
+3. Use those insights to inform decisions (avoid rediscovering known issues)
+
+**Before handing off**, the outgoing agent SHOULD:
+1. Write key discoveries to `.sinapse/scratchpad/{story-id}/{agent-id}.md`
+2. Include the scratchpad path in the handoff artifact `scratchpad_path` field
+3. Keep each file under 2KB (focused insights, not logs)
+
 ### Compaction Limits
 
 | Limit | Value |

package/.claude/rules/cross-squad-routing.md

@@ -0,0 +1,47 @@
+# Cross-Squad Routing Rules
+
+> Applies to Imperator (sinapse-orqx) and ALL squad orchestrators (*-orqx).
+
+## Single-Squad Requests
+
+When a request maps cleanly to one domain, route directly:
+
+```
+"Crie um headline" → @copy-orqx → @headline-specialist
+"Audite a marca" → @brand-orqx → @brand-auditor
+"Otimize SEO" → @growth-orqx → @seo-specialist
+```
+
+## Multi-Squad Patterns
+
+For requests spanning multiple domains, use established patterns:
+
+| Pattern | Squads | Trigger |
+|---------|--------|---------|
+| `brand_launch` | brand + design + content + copy + animations | New brand from scratch |
+| `go_to_market` | product + commercial + content + paidmedia + growth | Launch product/service |
+| `strategic_pivot` | council + research + finance + product | Major direction change |
+| `full_digital_presence` | brand + design + content + animations + growth + paidmedia | Complete digital setup |
+| `security_compliance_audit` | cybersecurity + research | Security assessment |
+| `content_campaign` | content + copy + growth + paidmedia | Multi-channel campaign |
+| `course_launch` | courses + content + copy + commercial | Course/workshop launch |
+
+## Routing Priority
+
+1. **Exact match** — Request clearly belongs to one squad
+2. **Pattern match** — Request matches a known multi-squad pattern
+3. **Diagnostic** — Unclear request → Imperator diagnoses before routing
+
+## Handoff Between Squads
+
+When work flows from one squad to another:
+1. Outgoing squad writes deliverables to `docs/` or project files
+2. Outgoing orchestrator generates handoff artifact
+3. Incoming orchestrator receives artifact + reads deliverables
+4. Incoming orchestrator routes to appropriate specialist
+
+## Anti-Patterns
+
+- Never have two squads working on the same file simultaneously
+- Never skip the orchestrator (user → specialist directly) for multi-squad work
+- Never route to a squad without providing context from the previous squad

package/.claude/rules/hook-governance.md

@@ -0,0 +1,61 @@
+# Hook Governance Rules
+
+> Applies to ALL agents. Hooks are the enforcement layer of the Constitution.
+
+## Active Hook Registry
+
+### PreToolUse — Bash
+| Hook | Purpose | Behavior |
+|------|---------|----------|
+| `enforce-git-push-authority.sh` | Art. II — Only @devops can push | BLOCK (deny) |
+| `sql-governance.py` | Security — Block dangerous SQL | BLOCK (exit 2) |
+| `enforce-delegation.cjs` | Art. VIII — Orchestrators can't execute | BLOCK (exit 2) |
+
+### PreToolUse — Write|Edit
+| Hook | Purpose | Behavior |
+|------|---------|----------|
+| `enforce-architecture-first.cjs` | Art. III — Docs before protected code | BLOCK (exit 2) |
+| `write-path-validation.cjs` | Convention — Warn wrong doc paths | WARN (exit 0) |
+| `enforce-story-gate.cjs` | Art. III — Story required for code | BLOCK (exit 2) |
+| `slug-validation.py` | Convention — Validate naming | WARN (exit 0) |
+| `mind-clone-governance.py` | Cloning — DNA required | BLOCK (exit 2) |
+| `enforce-delegation.cjs` | Art. VIII — Orchestrators can't execute | BLOCK (exit 2) |
+
+### PreToolUse — Read
+| Hook | Purpose | Behavior |
+|------|---------|----------|
+| `read-protection.py` | Security — Control sensitive file access | WARN (exit 0) |
+
+### UserPromptSubmit
+| Hook | Purpose | Behavior |
+|------|---------|----------|
+| `synapse-wrapper.cjs` | SYNAPSE context injection | ALLOW (exit 0) |
+
+### PreCompact
+| Hook | Purpose | Behavior |
+|------|---------|----------|
+| `precompact-wrapper.cjs` | Session digest before compaction | ALLOW (exit 0) |
+
+## Hook Design Principles
+
+1. **Fail-open** — If a hook crashes or can't parse input, exit 0 (allow)
+2. **Fast** — Each hook must complete in < 5 seconds
+3. **Silent on success** — Only output on block or warning
+4. **Deterministic** — Same input always produces same output
+5. **No side effects** — Hooks read state but don't modify it
+
+## Adding New Hooks
+
+1. Create script in `.claude/hooks/` (prefer CJS for portability)
+2. Add entry to `.claude/settings.json` under appropriate event
+3. Document in this file (hook-governance.md)
+4. Test with mock JSON via stdin
+5. Verify fail-open behavior with invalid input
+
+## Exit Code Protocol
+
+| Code | Meaning | Effect |
+|------|---------|--------|
+| 0 | Allow | Operation proceeds |
+| 2 | Block | Operation denied, message shown to model |
+| Other | Ignored | Operation proceeds (treated as 0) |

package/.claude/rules/security-scanning.md

@@ -0,0 +1,42 @@
+# Security Scanning Rules
+
+> Applies to ALL agents writing code or configuration files.
+
+## Secret Detection
+
+NEVER commit files containing:
+- API keys, tokens, or passwords in plaintext
+- `.env` files with real values (use `.env.example` with placeholders)
+- OAuth credentials (`access_token`, `refresh_token`, `client_secret`)
+- Private keys (RSA, SSH, PGP)
+- Database connection strings with credentials
+- Webhook URLs with embedded tokens
+
+## Path Traversal Prevention
+
+When handling file paths from user input or external sources:
+- Reject paths containing `..` segments
+- Reject absolute paths outside project root
+- Normalize paths before validation (`path.resolve()` then check prefix)
+- Never construct paths with string concatenation from untrusted input
+
+## SQL Injection Prevention
+
+- Always use parameterized queries — never string interpolation
+- Supabase RPC functions must use `$1, $2` parameter placeholders
+- Edge functions must validate and sanitize all query parameters
+- `sql-governance.py` hook blocks dangerous SQL patterns automatically
+
+## Dependency Security
+
+- Review new dependencies before adding (`npm audit`)
+- Prefer well-maintained packages (>1K weekly downloads, recent updates)
+- Pin exact versions in production dependencies
+- Never install packages with known critical vulnerabilities
+
+## Hooks Enforcement
+
+Active security hooks in `.claude/settings.json`:
+- `sql-governance.py` — blocks dangerous SQL in Bash commands
+- `read-protection.py` — controls access to sensitive config files
+- `enforce-architecture-first.cjs` — requires docs before protected code paths

package/.sinapse-ai/cli/commands/health/index.js

@@ -0,0 +1,237 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * sinapse health — Framework Health Analytics
+ *
+ * Analyzes the health of a SINAPSE installation:
+ * - Hook connectivity (wired vs orphaned)
+ * - Squad completeness (metadata, preferences, KBs)
+ * - Rule coverage
+ * - Agent authority compliance
+ * - Skill activation coverage
+ *
+ * Usage:
+ *   sinapse health              # Full health report
+ *   sinapse health --json       # JSON output
+ *   sinapse health --fix        # Auto-fix common issues
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+function findProjectRoot() {
+  let dir = process.cwd();
+  while (dir !== path.dirname(dir)) {
+    if (fs.existsSync(path.join(dir, '.sinapse-ai'))) return dir;
+    dir = path.dirname(dir);
+  }
+  return process.cwd();
+}
+
+function checkHooks(root) {
+  const results = { score: 0, max: 0, issues: [] };
+  const settingsPath = path.join(root, '.claude', 'settings.json');
+
+  results.max += 3;
+  if (!fs.existsSync(settingsPath)) {
+    results.issues.push({ severity: 'critical', msg: '.claude/settings.json not found' });
+    return results;
+  }
+
+  const settings = JSON.parse(fs.readFileSync(settingsPath, 'utf8'));
+  const hooks = settings.hooks || {};
+
+  // Check PreToolUse exists
+  if (hooks.PreToolUse && hooks.PreToolUse.length > 0) {
+    results.score += 1;
+  } else {
+    results.issues.push({ severity: 'high', msg: 'No PreToolUse hooks configured' });
+  }
+
+  // Check UserPromptSubmit exists
+  if (hooks.UserPromptSubmit && hooks.UserPromptSubmit.length > 0) {
+    results.score += 1;
+  } else {
+    results.issues.push({ severity: 'medium', msg: 'No UserPromptSubmit hooks configured' });
+  }
+
+  // Count total connected hooks
+  let connected = 0;
+  Object.values(hooks).forEach((matchers) =>
+    matchers.forEach((m) => (m.hooks || []).forEach(() => connected++)),
+  );
+
+  // Check hook files exist
+  const hooksDir = path.join(root, '.claude', 'hooks');
+  if (fs.existsSync(hooksDir)) {
+    const hookFiles = fs.readdirSync(hooksDir).filter((f) => f.endsWith('.cjs') || f.endsWith('.sh') || f.endsWith('.py'));
+    const orphaned = hookFiles.length - connected;
+    if (orphaned <= 5) results.score += 1; // Some orphaned is OK (utilities, legacy)
+    else results.issues.push({ severity: 'low', msg: `${orphaned} hook files not connected to settings.json` });
+  }
+
+  results.connected = connected;
+  return results;
+}
+
+function checkSquads(root) {
+  const results = { score: 0, max: 0, issues: [], squads: [] };
+  const squadsDir = path.join(root, 'squads');
+
+  if (!fs.existsSync(squadsDir)) {
+    results.issues.push({ severity: 'medium', msg: 'squads/ directory not found' });
+    return results;
+  }
+
+  const squadDirs = fs.readdirSync(squadsDir).filter((d) => d.startsWith('squad-') && fs.statSync(path.join(squadsDir, d)).isDirectory());
+
+  for (const squad of squadDirs) {
+    const dir = path.join(squadsDir, squad);
+    const checks = { name: squad, metadata: false, preferences: false, agents: 0, tasks: 0 };
+    results.max += 2;
+
+    // Check metadata
+    const yamlPath = path.join(dir, 'squad.yaml');
+    if (fs.existsSync(yamlPath)) {
+      const content = fs.readFileSync(yamlPath, 'utf8');
+      checks.metadata = /agents_count|total_files/.test(content);
+      if (checks.metadata) results.score += 1;
+      else results.issues.push({ severity: 'low', msg: `${squad}: missing metadata in squad.yaml` });
+    }
+
+    // Check preferences
+    checks.preferences = fs.existsSync(path.join(dir, 'preferences'));
+    if (checks.preferences) results.score += 1;
+    else results.issues.push({ severity: 'low', msg: `${squad}: missing preferences/ directory` });
+
+    // Count assets
+    const agentsDir = path.join(dir, 'agents');
+    const tasksDir = path.join(dir, 'tasks');
+    checks.agents = fs.existsSync(agentsDir) ? fs.readdirSync(agentsDir).filter((f) => f.endsWith('.md')).length : 0;
+    checks.tasks = fs.existsSync(tasksDir) ? fs.readdirSync(tasksDir).filter((f) => f.endsWith('.md')).length : 0;
+
+    results.squads.push(checks);
+  }
+
+  return results;
+}
+
+function checkRules(root) {
+  const results = { score: 0, max: 1, issues: [] };
+  const rulesDir = path.join(root, '.claude', 'rules');
+
+  if (!fs.existsSync(rulesDir)) {
+    results.issues.push({ severity: 'high', msg: '.claude/rules/ not found' });
+    return results;
+  }
+
+  const rules = fs.readdirSync(rulesDir).filter((f) => f.endsWith('.md'));
+  if (rules.length >= 13) results.score += 1;
+  else results.issues.push({ severity: 'medium', msg: `Only ${rules.length} rules (recommended: 16+)` });
+
+  results.count = rules.length;
+  return results;
+}
+
+function checkSkills(root) {
+  const results = { score: 0, max: 1, issues: [] };
+  const skillsDir = path.join(root, '.claude', 'skills');
+
+  if (!fs.existsSync(skillsDir)) {
+    results.issues.push({ severity: 'medium', msg: '.claude/skills/ not found' });
+    return results;
+  }
+
+  const skills = fs.readdirSync(skillsDir).filter((f) => f.endsWith('.md') || fs.statSync(path.join(skillsDir, f)).isDirectory());
+  // Check for path-activated skills
+  let pathActivated = 0;
+  for (const skill of skills) {
+    const skillPath = path.join(skillsDir, skill);
+    if (fs.statSync(skillPath).isFile()) {
+      const content = fs.readFileSync(skillPath, 'utf8');
+      if (/^paths:/m.test(content)) pathActivated++;
+    }
+  }
+
+  if (pathActivated >= 3) results.score += 1;
+  else results.issues.push({ severity: 'low', msg: `Only ${pathActivated} path-activated skills (recommended: 5+)` });
+
+  results.total = skills.length;
+  results.pathActivated = pathActivated;
+  return results;
+}
+
+async function runHealth(options = {}) {
+  const root = findProjectRoot();
+  const pkg = JSON.parse(fs.readFileSync(path.join(root, 'package.json'), 'utf8'));
+
+  const hookResults = checkHooks(root);
+  const squadResults = checkSquads(root);
+  const ruleResults = checkRules(root);
+  const skillResults = checkSkills(root);
+
+  const totalScore = hookResults.score + squadResults.score + ruleResults.score + skillResults.score;
+  const totalMax = hookResults.max + squadResults.max + ruleResults.max + skillResults.max;
+  const percentage = Math.round((totalScore / totalMax) * 100);
+
+  const allIssues = [
+    ...hookResults.issues,
+    ...squadResults.issues,
+    ...ruleResults.issues,
+    ...skillResults.issues,
+  ];
+
+  if (options.json) {
+    console.log(JSON.stringify({
+      version: pkg.version,
+      health: percentage,
+      score: `${totalScore}/${totalMax}`,
+      hooks: { connected: hookResults.connected, score: `${hookResults.score}/${hookResults.max}` },
+      squads: { count: squadResults.squads.length, score: `${squadResults.score}/${squadResults.max}` },
+      rules: { count: ruleResults.count, score: `${ruleResults.score}/${ruleResults.max}` },
+      skills: { total: skillResults.total, pathActivated: skillResults.pathActivated, score: `${skillResults.score}/${skillResults.max}` },
+      issues: allIssues,
+    }, null, 2));
+    return;
+  }
+
+  // Pretty output
+  const bar = (score, max) => {
+    const filled = Math.round((score / max) * 10);
+    return '█'.repeat(filled) + '░'.repeat(10 - filled);
+  };
+
+  console.log(`\n  SINAPSE Health Report — v${pkg.version}`);
+  console.log(`  ${'═'.repeat(50)}\n`);
+  console.log(`  Overall Health: ${percentage}% ${bar(totalScore, totalMax)} (${totalScore}/${totalMax})\n`);
+  console.log(`  Hooks:   ${bar(hookResults.score, hookResults.max)} ${hookResults.connected || 0} connected`);
+  console.log(`  Squads:  ${bar(squadResults.score, squadResults.max)} ${squadResults.squads.length} squads`);
+  console.log(`  Rules:   ${bar(ruleResults.score, ruleResults.max)} ${ruleResults.count || 0} rules`);
+  console.log(`  Skills:  ${bar(skillResults.score, skillResults.max)} ${skillResults.pathActivated || 0} path-activated\n`);
+
+  if (allIssues.length > 0) {
+    console.log(`  Issues (${allIssues.length}):`);
+    for (const issue of allIssues.slice(0, 10)) {
+      const icon = issue.severity === 'critical' ? '🔴' : issue.severity === 'high' ? '🟠' : issue.severity === 'medium' ? '🟡' : '🔵';
+      console.log(`    ${icon} ${issue.msg}`);
+    }
+    if (allIssues.length > 10) console.log(`    ... and ${allIssues.length - 10} more`);
+    console.log('');
+  } else {
+    console.log('  ✅ No issues found!\n');
+  }
+}
+
+module.exports = { runHealth };
+
+if (require.main === module) {
+  const args = process.argv.slice(2);
+  runHealth({
+    json: args.includes('--json'),
+    fix: args.includes('--fix'),
+  }).catch((err) => {
+    console.error(`Error: ${err.message}`);
+    process.exit(1);
+  });
+}

package/.sinapse-ai/cli/commands/performance/index.js

@@ -0,0 +1,157 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * sinapse performance — Squad & Agent Performance Ranking
+ *
+ * Analyzes squad and agent completeness, ranking by:
+ * - Asset coverage (agents, tasks, KBs, workflows, templates, checklists)
+ * - Metadata completeness
+ * - Preferences tracking
+ * - Orchestrator enrichment level
+ *
+ * Usage:
+ *   sinapse performance              # Full ranking
+ *   sinapse performance --json       # JSON output
+ *   sinapse performance --top 5      # Top 5 only
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+function findProjectRoot() {
+  let dir = process.cwd();
+  while (dir !== path.dirname(dir)) {
+    if (fs.existsSync(path.join(dir, '.sinapse-ai'))) return dir;
+    dir = path.dirname(dir);
+  }
+  return process.cwd();
+}
+
+function analyzeSquad(squadDir, squadName) {
+  const result = {
+    name: squadName,
+    agents: 0,
+    tasks: 0,
+    kbs: 0,
+    workflows: 0,
+    templates: 0,
+    checklists: 0,
+    hasMetadata: false,
+    hasPreferences: false,
+    orchestratorLines: 0,
+    score: 0,
+  };
+
+  // Count assets
+  const countMd = (subdir) => {
+    const dir = path.join(squadDir, subdir);
+    if (!fs.existsSync(dir)) return 0;
+    return fs.readdirSync(dir).filter((f) => f.endsWith('.md')).length;
+  };
+
+  const countAny = (subdir) => {
+    const dir = path.join(squadDir, subdir);
+    if (!fs.existsSync(dir)) return 0;
+    return fs.readdirSync(dir).filter((f) => !f.startsWith('.')).length;
+  };
+
+  result.agents = countMd('agents');
+  result.tasks = countMd('tasks');
+  // Try both naming conventions
+  result.kbs = countAny('knowledge-bases') || countAny('knowledge-base');
+  result.workflows = countAny('workflows');
+  result.templates = countMd('templates') || countAny('templates');
+  result.checklists = countMd('checklists') || countAny('checklists');
+
+  // Metadata check
+  const yamlPath = path.join(squadDir, 'squad.yaml');
+  if (fs.existsSync(yamlPath)) {
+    const content = fs.readFileSync(yamlPath, 'utf8');
+    result.hasMetadata = /agents_count|total_files/.test(content);
+  }
+
+  // Preferences check
+  result.hasPreferences = fs.existsSync(path.join(squadDir, 'preferences'));
+
+  // Orchestrator enrichment
+  const orqxFile = fs.readdirSync(path.join(squadDir, 'agents')).find((f) => f.includes('-orqx'));
+  if (orqxFile) {
+    const content = fs.readFileSync(path.join(squadDir, 'agents', orqxFile), 'utf8');
+    result.orchestratorLines = content.split('\n').length;
+  }
+
+  // Calculate score (weighted)
+  result.score =
+    (result.agents >= 6 ? 15 : result.agents * 2.5) +
+    (result.tasks >= 50 ? 25 : result.tasks * 0.5) +
+    (result.kbs >= 8 ? 15 : result.kbs * 1.875) +
+    (result.workflows >= 3 ? 10 : result.workflows * 3.33) +
+    (result.templates >= 3 ? 10 : result.templates * 3.33) +
+    (result.checklists >= 2 ? 5 : result.checklists * 2.5) +
+    (result.hasMetadata ? 5 : 0) +
+    (result.hasPreferences ? 5 : 0) +
+    (result.orchestratorLines >= 100 ? 10 : result.orchestratorLines * 0.1);
+
+  result.score = Math.round(result.score * 10) / 10;
+
+  return result;
+}
+
+async function runPerformance(options = {}) {
+  const root = findProjectRoot();
+  const squadsDir = path.join(root, 'squads');
+
+  if (!fs.existsSync(squadsDir)) {
+    console.error('No squads/ directory found.');
+    process.exit(1);
+  }
+
+  const squadDirs = fs.readdirSync(squadsDir)
+    .filter((d) => d.startsWith('squad-') && fs.statSync(path.join(squadsDir, d)).isDirectory());
+
+  const rankings = squadDirs
+    .map((d) => analyzeSquad(path.join(squadsDir, d), d))
+    .sort((a, b) => b.score - a.score);
+
+  const limit = options.top || rankings.length;
+  const display = rankings.slice(0, limit);
+
+  if (options.json) {
+    console.log(JSON.stringify({ rankings: display, total: rankings.length }, null, 2));
+    return;
+  }
+
+  // Pretty output
+  console.log(`\n  SINAPSE Performance Ranking — ${rankings.length} Squads`);
+  console.log(`  ${'═'.repeat(60)}\n`);
+
+  const maxScore = rankings[0]?.score || 100;
+
+  display.forEach((sq, i) => {
+    const rank = i + 1;
+    const barLen = Math.round((sq.score / maxScore) * 20);
+    const bar = '█'.repeat(barLen) + '░'.repeat(20 - barLen);
+    const medal = rank === 1 ? '🥇' : rank === 2 ? '🥈' : rank === 3 ? '🥉' : `#${rank}`;
+    const meta = sq.hasMetadata ? '✓' : '✗';
+    const pref = sq.hasPreferences ? '✓' : '✗';
+
+    console.log(`  ${String(medal).padEnd(4)} ${sq.name.padEnd(25)} ${bar} ${sq.score.toFixed(1)}`);
+    console.log(`       ${sq.agents}a ${sq.tasks}t ${sq.kbs}kb ${sq.workflows}wf ${sq.templates}tpl ${sq.checklists}ck | meta:${meta} pref:${pref} orqx:${sq.orchestratorLines}L`);
+    console.log('');
+  });
+}
+
+module.exports = { runPerformance };
+
+if (require.main === module) {
+  const args = process.argv.slice(2);
+  const topIdx = args.indexOf('--top');
+  runPerformance({
+    json: args.includes('--json'),
+    top: topIdx >= 0 ? parseInt(args[topIdx + 1], 10) : undefined,
+  }).catch((err) => {
+    console.error(`Error: ${err.message}`);
+    process.exit(1);
+  });
+}