tribunal-kit 6.0.1 → 7.0.0

package/.agent/scripts/context_broker.js

@@ -45,37 +45,41 @@
  *   prompt           — full injected prompt text ready for an LLM
  */
 
-"use strict";
+'use strict';
 
-const fs = require("fs");
-const path = require("path");
-const { execFileSync } = require("child_process");
+const fs = require('fs');
+const path = require('path');
+const { execFileSync } = require('child_process');
 
 // ── Colours & Shared Utilities ────────────────────────────────────────────────
-const { GREEN, YELLOW, CYAN, RED, BOLD, DIM, RESET } = require("./_colors");
-const { findAgentDir } = require("./_utils");
+const { GREEN, YELLOW, CYAN, RED, BOLD, DIM, RESET } = require('./_colors');
+const { findAgentDir } = require('./_utils');
 
 /**
  * Attempt native Rust context resolution for sub-15ms execution
  */
 function tryNativeContextBroker(repoPath, targetFile) {
-  if (process.env.TK_DISABLE_RUST === "1") return null;
+  if (process.env.TK_DISABLE_RUST === '1') return null;
 
   const candidates = [
-    path.join(__dirname, "../../target/release/tribunal-core.exe"),
-    path.join(__dirname, "../../target/release/tribunal-core"),
-    path.join(__dirname, "../../target/debug/tribunal-core.exe"),
-    path.join(__dirname, "../../target/debug/tribunal-core"),
-    "tribunal-core"
+    path.join(__dirname, '../../target/release/tribunal-core.exe'),
+    path.join(__dirname, '../../target/release/tribunal-core'),
+    path.join(__dirname, '../../target/debug/tribunal-core.exe'),
+    path.join(__dirname, '../../target/debug/tribunal-core'),
+    'tribunal-core',
   ];
 
   for (const bin of candidates) {
     try {
       if (bin.includes(path.sep) && !fs.existsSync(bin)) continue;
-      const args = ["context-broker", "--repo-path", repoPath];
-      if (targetFile) args.push("--target-file", targetFile);
-      const out = execFileSync(bin, args, { encoding: "utf8", timeout: 2000, stdio: ["ignore", "pipe", "ignore"] });
-      if (out && out.trim().startsWith("{")) {
+      const args = ['context-broker', '--repo-path', repoPath];
+      if (targetFile) args.push('--target-file', targetFile);
+      const out = execFileSync(bin, args, {
+        encoding: 'utf8',
+        timeout: 2000,
+        stdio: ['ignore', 'pipe', 'ignore'],
+      });
+      if (out && out.trim().startsWith('{')) {
         return JSON.parse(out);
       }
     } catch (_) {
@@ -85,305 +89,187 @@ function tryNativeContextBroker(repoPath, targetFile) {
   return null;
 }
 
-
-
 // ── Domain → Skill affinity map ───────────────────────────────────────────────
 // Keywords in the user's task that strongly indicate specific skills.
 // Higher weight = stronger signal.
 const DOMAIN_AFFINITIES = [
   // Backend / API
   {
-    keywords: [
-      "api",
-      "rest",
-      "route",
-      "endpoint",
-      "handler",
-      "express",
-      "fastapi",
-      "hono",
-    ],
-    skills: [
-      "api-patterns",
-      "nodejs-best-practices",
-      "backend-specialist",
-      "error-resilience",
-    ],
+    keywords: ['api', 'rest', 'route', 'endpoint', 'handler', 'express', 'fastapi', 'hono'],
+    skills: ['api-patterns', 'nodejs-best-practices', 'backend-specialist', 'error-resilience'],
     weight: 3,
   },
   // Database
   {
     keywords: [
-      "sql",
-      "query",
-      "database",
-      "prisma",
-      "drizzle",
-      "orm",
-      "postgres",
-      "mysql",
-      "schema",
+      'sql',
+      'query',
+      'database',
+      'prisma',
+      'drizzle',
+      'orm',
+      'postgres',
+      'mysql',
+      'schema',
     ],
-    skills: ["database-design", "sql-pro", "supabase-postgres-best-practices"],
+    skills: ['database-design', 'sql-pro', 'supabase-postgres-best-practices'],
     weight: 3,
   },
   // Authentication
   {
-    keywords: [
-      "auth",
-      "jwt",
-      "login",
-      "oauth",
-      "session",
-      "password",
-      "token",
-      "rbac",
-    ],
-    skills: [
-      "authentication-best-practices",
-      "vulnerability-scanner",
-      "api-security-auditor",
-    ],
+    keywords: ['auth', 'jwt', 'login', 'oauth', 'session', 'password', 'token', 'rbac'],
+    skills: ['authentication-best-practices', 'vulnerability-scanner', 'api-security-auditor'],
     weight: 3,
   },
   // React / Next.js
   {
     keywords: [
-      "react",
-      "next",
-      "nextjs",
-      "component",
-      "hook",
-      "jsx",
-      "tsx",
-      "server component",
-      "server action",
+      'react',
+      'next',
+      'nextjs',
+      'component',
+      'hook',
+      'jsx',
+      'tsx',
+      'server component',
+      'server action',
     ],
-    skills: ["react-specialist", "nextjs-react-expert", "frontend-design"],
+    skills: ['react-specialist', 'nextjs-react-expert', 'frontend-design'],
     weight: 3,
   },
   // Frontend / UI
   {
     keywords: [
-      "ui",
-      "design",
-      "landing",
-      "page",
-      "layout",
-      "responsive",
-      "tailwind",
-      "css",
-      "style",
-    ],
-    skills: [
-      "frontend-design",
-      "ui-ux-pro-max",
-      "tailwind-patterns",
-      "web-design-guidelines",
+      'ui',
+      'design',
+      'landing',
+      'page',
+      'layout',
+      'responsive',
+      'tailwind',
+      'css',
+      'style',
     ],
+    skills: ['frontend-design', 'ui-ux-pro-max', 'tailwind-patterns', 'web-design-guidelines'],
     weight: 2,
   },
   // Animation / Motion
   {
-    keywords: [
-      "animation",
-      "gsap",
-      "framer",
-      "motion",
-      "scroll",
-      "transition",
-      "parallax",
-    ],
-    skills: [
-      "motion-engineering",
-      "framer-motion-expert",
-      "gsap-core",
-      "gsap-scrolltrigger",
-    ],
+    keywords: ['animation', 'gsap', 'framer', 'motion', 'scroll', 'transition', 'parallax'],
+    skills: ['motion-engineering', 'framer-motion-expert', 'gsap-core', 'gsap-scrolltrigger'],
     weight: 3,
   },
   // AI / LLM
   {
     keywords: [
-      "llm",
-      "openai",
-      "anthropic",
-      "gemini",
-      "embedding",
-      "ai",
-      "rag",
-      "vector",
-      "chat",
-      "prompt",
-    ],
-    skills: [
-      "llm-engineering",
-      "ai-prompt-injection-defense",
-      "agentic-patterns",
+      'llm',
+      'openai',
+      'anthropic',
+      'gemini',
+      'embedding',
+      'ai',
+      'rag',
+      'vector',
+      'chat',
+      'prompt',
     ],
+    skills: ['llm-engineering', 'ai-prompt-injection-defense', 'agentic-patterns'],
     weight: 3,
   },
   // Security
   {
     keywords: [
-      "security",
-      "xss",
-      "injection",
-      "owasp",
-      "vulnerability",
-      "csrf",
-      "sanitize",
-      "audit",
-    ],
-    skills: [
-      "vulnerability-scanner",
-      "api-security-auditor",
-      "authentication-best-practices",
+      'security',
+      'xss',
+      'injection',
+      'owasp',
+      'vulnerability',
+      'csrf',
+      'sanitize',
+      'audit',
     ],
+    skills: ['vulnerability-scanner', 'api-security-auditor', 'authentication-best-practices'],
     weight: 3,
   },
   // Testing
   {
-    keywords: [
-      "test",
-      "spec",
-      "jest",
-      "vitest",
-      "playwright",
-      "unit test",
-      "e2e",
-      "mock",
-    ],
-    skills: ["testing-patterns", "playwright-best-practices", "tdd-workflow"],
+    keywords: ['test', 'spec', 'jest', 'vitest', 'playwright', 'unit test', 'e2e', 'mock'],
+    skills: ['testing-patterns', 'playwright-best-practices', 'tdd-workflow'],
     weight: 3,
   },
   // Performance
   {
-    keywords: [
-      "performance",
-      "optimize",
-      "bundle",
-      "cache",
-      "speed",
-      "slow",
-      "lighthouse",
-      "cwv",
-    ],
-    skills: ["performance-profiling", "motion-engineering", "edge-computing"],
+    keywords: ['performance', 'optimize', 'bundle', 'cache', 'speed', 'slow', 'lighthouse', 'cwv'],
+    skills: ['performance-profiling', 'motion-engineering', 'edge-computing'],
     weight: 2,
   },
   // Mobile
   {
-    keywords: [
-      "mobile",
-      "react native",
-      "expo",
-      "ios",
-      "android",
-      "gesture",
-      "haptic",
-    ],
-    skills: ["building-native-ui", "mobile-design", "agentic-patterns"],
+    keywords: ['mobile', 'react native', 'expo', 'ios', 'android', 'gesture', 'haptic'],
+    skills: ['building-native-ui', 'mobile-design', 'agentic-patterns'],
     weight: 3,
   },
   // DevOps / CI
   {
-    keywords: [
-      "docker",
-      "ci",
-      "cd",
-      "deploy",
-      "pipeline",
-      "k8s",
-      "kubernetes",
-      "github actions",
-    ],
-    skills: ["devops-engineer", "deployment-procedures", "observability"],
+    keywords: ['docker', 'ci', 'cd', 'deploy', 'pipeline', 'k8s', 'kubernetes', 'github actions'],
+    skills: ['devops-engineer', 'deployment-procedures', 'observability'],
     weight: 2,
   },
   // Real-time
   {
-    keywords: [
-      "realtime",
-      "websocket",
-      "sse",
-      "socket",
-      "live",
-      "multiplayer",
-      "collaborative",
-    ],
-    skills: ["realtime-patterns", "error-resilience"],
+    keywords: ['realtime', 'websocket', 'sse', 'socket', 'live', 'multiplayer', 'collaborative'],
+    skills: ['realtime-patterns', 'error-resilience'],
     weight: 3,
   },
   // TypeScript
   {
-    keywords: [
-      "typescript",
-      "type",
-      "generic",
-      "interface",
-      "satisfies",
-      "zod",
-      "pydantic",
-    ],
-    skills: ["typescript-advanced", "data-validation-schemas"],
+    keywords: ['typescript', 'type', 'generic', 'interface', 'satisfies', 'zod', 'pydantic'],
+    skills: ['typescript-advanced', 'data-validation-schemas'],
     weight: 2,
   },
   // Python
   {
-    keywords: ["python", "fastapi", "django", "flask", "pydantic", "asyncio"],
-    skills: ["python-pro", "python-patterns"],
+    keywords: ['python', 'fastapi', 'django', 'flask', 'pydantic', 'asyncio'],
+    skills: ['python-pro', 'python-patterns'],
     weight: 3,
   },
   // Architecture
   {
     keywords: [
-      "architecture",
-      "refactor",
-      "clean",
-      "solid",
-      "design pattern",
-      "monorepo",
-      "microservice",
+      'architecture',
+      'refactor',
+      'clean',
+      'solid',
+      'design pattern',
+      'monorepo',
+      'microservice',
     ],
-    skills: ["architecture", "clean-code", "monorepo-management"],
+    skills: ['architecture', 'clean-code', 'monorepo-management'],
     weight: 2,
   },
   // C# / .NET
   {
-    keywords: [
-      "csharp",
-      "c#",
-      "dotnet",
-      ".net",
-      "blazor",
-      "aspnet",
-      "entity framework",
-    ],
-    skills: ["csharp-developer"],
+    keywords: ['csharp', 'c#', 'dotnet', '.net', 'blazor', 'aspnet', 'entity framework'],
+    skills: ['csharp-developer'],
     weight: 3,
   },
 ];
 
 // ── File extension → skill boost map ─────────────────────────────────────────
 const EXT_AFFINITIES = {
-  ".tsx": ["react-specialist", "nextjs-react-expert", "typescript-advanced"],
-  ".jsx": ["react-specialist", "frontend-design"],
-  ".ts": ["typescript-advanced", "nodejs-best-practices"],
-  ".vue": ["vue-expert"],
-  ".py": ["python-pro", "python-patterns"],
-  ".cs": ["csharp-developer"],
-  ".sql": ["sql-pro", "database-design"],
-  ".css": ["tailwind-patterns", "frontend-design"],
+  '.tsx': ['react-specialist', 'nextjs-react-expert', 'typescript-advanced'],
+  '.jsx': ['react-specialist', 'frontend-design'],
+  '.ts': ['typescript-advanced', 'nodejs-best-practices'],
+  '.vue': ['vue-expert'],
+  '.py': ['python-pro', 'python-patterns'],
+  '.cs': ['csharp-developer'],
+  '.sql': ['sql-pro', 'database-design'],
+  '.css': ['tailwind-patterns', 'frontend-design'],
 };
 
 // ── Core baseline skills — always available to all model sizes ────────────────
 // These are injected for every request at a condensed level.
-const BASELINE_SKILLS = [
-  "clean-code",
-  "systematic-debugging",
-  "error-resilience",
-];
+const BASELINE_SKILLS = ['clean-code', 'systematic-debugging', 'error-resilience'];
 
 // ── Skill catalogue (loaded from disk) ───────────────────────────────────────
 
@@ -397,14 +283,14 @@ function parseFrontmatter(content) {
   if (!match) return null;
   const yaml = match[1];
   const obj = {};
-  for (const line of yaml.split("\n")) {
-    const sep = line.indexOf(":");
+  for (const line of yaml.split('\n')) {
+    const sep = line.indexOf(':');
     if (sep === -1) continue;
     const key = line.slice(0, sep).trim();
     const val = line
       .slice(sep + 1)
       .trim()
-      .replace(/^["']|["']$/g, "");
+      .replace(/^["']|["']$/g, '');
     obj[key] = val;
   }
   return obj;
@@ -422,18 +308,25 @@ function extractKeyRules(content) {
   );
   if (sectionMatch) return sectionMatch[1].trim().slice(0, 1200);
   // Fallback: strip frontmatter and take first 800 chars
-  const bodyStart = content.indexOf("---", 3);
+  const bodyStart = content.indexOf('---', 3);
   const body = bodyStart !== -1 ? content.slice(bodyStart + 3).trim() : content;
   return body.slice(0, 800).trim();
 }
 
+let _loadedSkillsCache = null;
+let _loadedSkillsAgentDir = null;
+
 /**
  * Load all skills from .agent/skills/ directory.
- * Returns an array of { name, file, frontmatter, content, keyRules } objects.
+ * Returns an array of { name, file, frontmatter, content, keyRules, tokens } objects.
  * @param {string} agentDir
  */
 function loadSkills(agentDir) {
-  const skillsDir = path.join(agentDir, "skills");
+  if (_loadedSkillsCache && _loadedSkillsAgentDir === agentDir) {
+    return _loadedSkillsCache;
+  }
+
+  const skillsDir = path.join(agentDir, 'skills');
   if (!fs.existsSync(skillsDir)) return [];
 
   const skills = [];
@@ -441,33 +334,44 @@ function loadSkills(agentDir) {
 
   for (const entry of entries) {
     if (!entry.isDirectory()) continue;
-    const skillFile = path.join(skillsDir, entry.name, "SKILL.md");
+    const skillFile = path.join(skillsDir, entry.name, 'SKILL.md');
     if (!fs.existsSync(skillFile)) continue;
 
     try {
-      let content = fs.readFileSync(skillFile, "utf8");
-      
+      let content = fs.readFileSync(skillFile, 'utf8');
+
       // Strip duplicated global boilerplate sections
-      content = content.replace(/AI coding assistants often fall into specific bad habits[\s\S]*$/g, "");
-      content = content.replace(/## 🤖 LLM-Specific Traps[\s\S]*$/g, "");
-      content = content.replace(/## 🏛️ Tribunal Integration[\s\S]*$/g, "");
-      content = content.replace(/## Pre-Flight Checklist[\s\S]*$/g, "");
+      content = content.replace(
+        /AI coding assistants often fall into specific bad habits[\s\S]*$/g,
+        '',
+      );
+      content = content.replace(/## 🤖 LLM-Specific Traps[\s\S]*$/g, '');
+      content = content.replace(/## 🏛️ Tribunal Integration[\s\S]*$/g, '');
+      content = content.replace(/## Pre-Flight Checklist[\s\S]*$/g, '');
       content = content.trim();
 
       const frontmatter = parseFrontmatter(content) || {};
       const keyRules = extractKeyRules(content);
+      const description = frontmatter.description || '';
+      const skillText = (entry.name + ' ' + description).toLowerCase();
+      const tokens = new Set(tokenize(skillText));
+
       skills.push({
         name: entry.name,
         file: skillFile,
         frontmatter,
         content,
         keyRules,
-        description: frontmatter.description || "",
+        description,
+        tokens,
       });
     } catch {
       // Skip unreadable skills silently
     }
   }
+
+  _loadedSkillsCache = skills;
+  _loadedSkillsAgentDir = agentDir;
   return skills;
 }
 
@@ -479,9 +383,13 @@ function loadSkills(agentDir) {
  * @returns {string[]}
  */
 function tokenize(text) {
-  return (text.match(/\b[a-zA-Z_][a-zA-Z0-9_]{2,}\b/g) || []).map((t) =>
-    t.toLowerCase(),
-  );
+  const str =
+    typeof text === 'string'
+      ? text
+      : text && typeof text === 'object'
+        ? text.task || text.spec || JSON.stringify(text)
+        : String(text || '');
+  return (str.match(/\b[a-zA-Z_][a-zA-Z0-9_]{2,}\b/g) || []).map(t => t.toLowerCase());
 }
 
 /**
@@ -493,7 +401,7 @@ function tokenize(text) {
  *   - File extension affinity: +2 per match
  *   - Baseline skill bonus: +1 (always present)
  *
- * @param {{ name, description, content }} skill
+ * @param {{ name, description, content, tokens }} skill
  * @param {string} task           - Raw task text from the user
  * @param {string[]} fileExts     - File extensions being touched
  * @param {string[]} taskTokens   - Pre-tokenized task
@@ -501,19 +409,24 @@ function tokenize(text) {
  */
 function scoreSkill(skill, task, fileExts, taskTokens) {
   let score = 0;
-  const taskLower = task.toLowerCase();
-  const skillText = (skill.name + " " + skill.description).toLowerCase();
-  const skillTokens = tokenize(skillText);
-
-  // 1. Token overlap (lightweight TF match — no IDF needed at this scale)
-  const skillSet = new Set(skillTokens);
+  const taskStr =
+    typeof task === 'string'
+      ? task
+      : task && typeof task === 'object'
+        ? task.task || task.spec || ''
+        : String(task || '');
+  const taskLower = taskStr.toLowerCase();
+
+  // 1. Token overlap (lightweight TF match using pre-built Set)
+  const skillSet =
+    skill.tokens || new Set(tokenize((skill.name + ' ' + skill.description).toLowerCase()));
   for (const token of taskTokens) {
     if (skillSet.has(token)) score += 1;
   }
 
   // 2. Domain affinity boost
   for (const affinity of DOMAIN_AFFINITIES) {
-    const keywordMatch = affinity.keywords.some((k) => taskLower.includes(k));
+    const keywordMatch = affinity.keywords.some(k => taskLower.includes(k));
     if (!keywordMatch) continue;
     if (affinity.skills.includes(skill.name)) {
       score += affinity.weight;
@@ -541,16 +454,22 @@ function scoreSkill(skill, task, fileExts, taskTokens) {
  * @param {object[]} skills   - Loaded skills array from loadSkills()
  * @returns {{ essential: object[], supplementary: object[], available: object[], scores: Map }}
  */
-function selectSkills(task, files, model, skills) {
-  const taskTokens = tokenize(task);
-  const fileExts = files
-    .map((f) => path.extname(f).toLowerCase())
+function selectSkills(task, files = [], model = 'large', skills = []) {
+  const taskStr =
+    typeof task === 'string'
+      ? task
+      : task && typeof task === 'object'
+        ? task.task || task.spec || ''
+        : String(task || '');
+  const taskTokens = tokenize(taskStr);
+  const fileExts = (Array.isArray(files) ? files : [])
+    .map(f => path.extname(f).toLowerCase())
     .filter(Boolean);
 
   // Score every available skill
-  const scored = skills.map((skill) => ({
+  const scored = skills.map(skill => ({
     ...skill,
-    score: scoreSkill(skill, task, fileExts, taskTokens),
+    score: scoreSkill(skill, taskStr, fileExts, taskTokens),
   }));
   scored.sort((a, b) => b.score - a.score);
 
@@ -559,26 +478,22 @@ function selectSkills(task, files, model, skills) {
   const tier0Cut = Math.max(maxScore * 0.65, 2); // Essential: top 65%+ of max score
   const tier1Cut = Math.max(maxScore * 0.3, 1); // Supplementary: 30–65%
 
-  const essential = scored.filter((s) => s.score >= tier0Cut).slice(0, 10);
-  const supplementary = scored
-    .filter((s) => s.score < tier0Cut && s.score >= tier1Cut)
-    .slice(0, 8);
-  const available = scored
-    .filter((s) => s.score < tier1Cut && s.score > 0)
-    .slice(0, 10);
+  const essential = scored.filter(s => s.score >= tier0Cut).slice(0, 10);
+  const supplementary = scored.filter(s => s.score < tier0Cut && s.score >= tier1Cut).slice(0, 8);
+  const available = scored.filter(s => s.score < tier1Cut && s.score > 0).slice(0, 10);
 
   // Ensure baseline skills always appear at minimum in supplementary
   for (const base of BASELINE_SKILLS) {
-    const inEssential = essential.find((s) => s.name === base);
-    const inSupplementary = supplementary.find((s) => s.name === base);
+    const inEssential = essential.find(s => s.name === base);
+    const inSupplementary = supplementary.find(s => s.name === base);
     if (!inEssential && !inSupplementary) {
-      const baseSkill = skills.find((s) => s.name === base);
+      const baseSkill = skills.find(s => s.name === base);
       if (baseSkill) supplementary.push({ ...baseSkill, score: 0.5 });
     }
   }
 
   // For small models: collapse supplementary into available
-  if (model === "small") {
+  if (model === 'small') {
     return {
       essential: essential.slice(0, 6),
       supplementary: [],
@@ -602,14 +517,10 @@ function formatReport(task, model, selection, elapsed) {
   const { essential, supplementary, available } = selection;
   const total = essential.length + supplementary.length + available.length;
 
+  console.log(`\n${BOLD}${CYAN}━━━ Context Broker — Skill Selection ━━━━━━━━━━━━━━━${RESET}`);
+  console.log(`  Task   : ${BOLD}${task.slice(0, 80)}${task.length > 80 ? '...' : ''}${RESET}`);
   console.log(
-    `\n${BOLD}${CYAN}━━━ Context Broker — Skill Selection ━━━━━━━━━━━━━━━${RESET}`,
-  );
-  console.log(
-    `  Task   : ${BOLD}${task.slice(0, 80)}${task.length > 80 ? "..." : ""}${RESET}`,
-  );
-  console.log(
-    `  Model  : ${model === "large" ? GREEN : YELLOW}${model}${RESET}  ${DIM}(Focus without Compromise)${RESET}`,
+    `  Model  : ${model === 'large' ? GREEN : YELLOW}${model}${RESET}  ${DIM}(Focus without Compromise)${RESET}`,
   );
   console.log(
     `  Skills : ${GREEN}${essential.length} essential${RESET} + ${YELLOW}${supplementary.length} supplementary${RESET} + ${DIM}${available.length} available${RESET}  of ${total} matched`,
@@ -617,47 +528,36 @@ function formatReport(task, model, selection, elapsed) {
   console.log(`  Time   : ${elapsed}ms\n`);
 
   if (essential.length) {
-    console.log(
-      `  ${GREEN}${BOLD}▶ Level 0 — Essential (Full Context, Top Priority):${RESET}`,
-    );
+    console.log(`  ${GREEN}${BOLD}▶ Level 0 — Essential (Full Context, Top Priority):${RESET}`);
     for (const s of essential) {
       const score = selection.scores.get(s.name) || 0;
       console.log(
         `    ${GREEN}✦${RESET} ${BOLD}${s.name}${RESET}  ${DIM}score=${score.toFixed(1)}${RESET}`,
       );
-      if (s.description)
-        console.log(`       ${DIM}${s.description.slice(0, 90)}${RESET}`);
+      if (s.description) console.log(`       ${DIM}${s.description.slice(0, 90)}${RESET}`);
     }
   }
 
   if (supplementary.length) {
-    console.log(
-      `\n  ${YELLOW}${BOLD}▶ Level 1 — Supplementary (Key Rules Only):${RESET}`,
-    );
+    console.log(`\n  ${YELLOW}${BOLD}▶ Level 1 — Supplementary (Key Rules Only):${RESET}`);
     for (const s of supplementary) {
       const score = selection.scores.get(s.name) || 0;
-      console.log(
-        `    ${YELLOW}◆${RESET} ${s.name}  ${DIM}score=${score.toFixed(1)}${RESET}`,
-      );
+      console.log(`    ${YELLOW}◆${RESET} ${s.name}  ${DIM}score=${score.toFixed(1)}${RESET}`);
     }
   }
 
   if (available.length) {
-    console.log(
-      `\n  ${DIM}▶ Level 2 — Available (Name Reference Only):${RESET}`,
-    );
-    console.log(`    ${DIM}${available.map((s) => s.name).join(", ")}${RESET}`);
+    console.log(`\n  ${DIM}▶ Level 2 — Available (Name Reference Only):${RESET}`);
+    console.log(`    ${DIM}${available.map(s => s.name).join(', ')}${RESET}`);
   }
 
-  if (model === "small") {
+  if (model === 'small') {
     console.log(
       `\n  ${YELLOW}⚡ Small model mode: supplementary collapsed. Essential only injected.${RESET}`,
     );
   }
 
-  console.log(
-    `\n${CYAN}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${RESET}\n`,
-  );
+  console.log(`\n${CYAN}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${RESET}\n`);
 }
 
 function formatJson(task, model, selection) {
@@ -666,16 +566,16 @@ function formatJson(task, model, selection) {
       task,
       model,
       timestamp: new Date().toISOString(),
-      essential: selection.essential.map((s) => ({
+      essential: selection.essential.map(s => ({
         name: s.name,
         score: selection.scores.get(s.name),
         description: s.description,
       })),
-      supplementary: selection.supplementary.map((s) => ({
+      supplementary: selection.supplementary.map(s => ({
         name: s.name,
         score: selection.scores.get(s.name),
       })),
-      available: selection.available.map((s) => s.name),
+      available: selection.available.map(s => s.name),
     },
     null,
     2,
@@ -684,10 +584,8 @@ function formatJson(task, model, selection) {
 
 function formatNames(selection, model) {
   const all =
-    model === "large"
-      ? [...selection.essential, ...selection.supplementary]
-      : selection.essential;
-  return all.map((s) => s.name).join("\n");
+    model === 'large' ? [...selection.essential, ...selection.supplementary] : selection.essential;
+  return all.map(s => s.name).join('\n');
 }
 
 /**
@@ -708,60 +606,57 @@ function formatPrompt(task, model, selection) {
     `# Task: ${task}`,
     `# Model tier: ${model}`,
     `# Generated: ${new Date().toISOString()}`,
-    "",
-    "## Instructions for the AI",
-    "The following skills are ordered by relevance to the current task.",
-    "Level 0 skills contain full rule sets. Level 1 skills contain key rules only.",
-    "Treat ALL injected rules as mandatory constraints, not suggestions.",
-    "",
-    "---",
-    "",
+    '',
+    '## Instructions for the AI',
+    'The following skills are ordered by relevance to the current task.',
+    'Level 0 skills contain full rule sets. Level 1 skills contain key rules only.',
+    'Treat ALL injected rules as mandatory constraints, not suggestions.',
+    '',
+    '---',
+    '',
   ];
 
   if (selection.essential.length) {
-    lines.push("## Level 0 — Essential Skills (Full Context)");
-    lines.push("");
+    lines.push('## Level 0 — Essential Skills (Full Context)');
+    lines.push('');
     for (const s of selection.essential) {
       lines.push(`### Skill: ${s.name}`);
-      lines.push("");
-      if (model === "large") {
+      lines.push('');
+      if (model === 'large') {
         lines.push(s.content || s.keyRules);
       } else {
         lines.push(s.keyRules);
       }
-      lines.push("");
-      lines.push("---");
-      lines.push("");
+      lines.push('');
+      lines.push('---');
+      lines.push('');
     }
   }
 
-  if (model === "large" && selection.supplementary.length) {
-    lines.push("## Level 1 — Supplementary Skills (Key Rules)");
-    lines.push("");
+  if (model === 'large' && selection.supplementary.length) {
+    lines.push('## Level 1 — Supplementary Skills (Key Rules)');
+    lines.push('');
     for (const s of selection.supplementary) {
       lines.push(`### Skill: ${s.name} (condensed)`);
-      lines.push("");
+      lines.push('');
       lines.push(s.keyRules);
-      lines.push("");
-      lines.push("---");
-      lines.push("");
+      lines.push('');
+      lines.push('---');
+      lines.push('');
     }
   }
 
   if (selection.available.length) {
-    lines.push("## Level 2 — Available Skills (Reference Names Only)");
-    lines.push("");
+    lines.push('## Level 2 — Available Skills (Reference Names Only)');
+    lines.push('');
+    lines.push('The following skills are relevant but not injected to maintain context density.');
     lines.push(
-      "The following skills are relevant but not injected to maintain context density.",
+      'Request their full content if needed: ' + selection.available.map(s => s.name).join(', '),
     );
-    lines.push(
-      "Request their full content if needed: " +
-        selection.available.map((s) => s.name).join(", "),
-    );
-    lines.push("");
+    lines.push('');
   }
 
-  return lines.join("\n");
+  return lines.join('\n');
 }
 
 // ── Built-in demo ─────────────────────────────────────────────────────────────
@@ -771,58 +666,49 @@ function runDemo(agentDir) {
 
   const scenarios = [
     {
-      task: "Build a JWT authentication API with Express.js and Zod validation",
-      file: "auth.ts",
-      model: "large",
+      task: 'Build a JWT authentication API with Express.js and Zod validation',
+      file: 'auth.ts',
+      model: 'large',
     },
     {
-      task: "Design a premium landing page with GSAP scroll animations",
-      file: "Hero.tsx",
-      model: "large",
+      task: 'Design a premium landing page with GSAP scroll animations',
+      file: 'Hero.tsx',
+      model: 'large',
     },
     {
-      task: "Write a Prisma query for paginated user orders",
-      file: "orders.ts",
-      model: "small",
+      task: 'Write a Prisma query for paginated user orders',
+      file: 'orders.ts',
+      model: 'small',
     },
     {
-      task: "Add RAG pipeline to an OpenAI-powered chat interface",
-      file: "chat.ts",
-      model: "large",
+      task: 'Add RAG pipeline to an OpenAI-powered chat interface',
+      file: 'chat.ts',
+      model: 'large',
     },
   ];
 
-  console.log(
-    `\n${BOLD}${CYAN}━━━ Context Broker — Demo Mode ━━━━━━━━━━━━━━━━━━━━━${RESET}`,
-  );
+  console.log(`\n${BOLD}${CYAN}━━━ Context Broker — Demo Mode ━━━━━━━━━━━━━━━━━━━━━${RESET}`);
   console.log(`  Loaded ${skills.length} skills from .agent/skills/\n`);
 
   for (const scenario of scenarios) {
     const t0 = Date.now();
     const model = scenario.model;
-    const selection = selectSkills(
-      scenario.task,
-      [scenario.file],
-      model,
-      skills,
-    );
+    const selection = selectSkills(scenario.task, [scenario.file], model, skills);
     const elapsed = Date.now() - t0;
 
     console.log(
       `\n  ${BOLD}Task: "${scenario.task.slice(0, 70)}"${RESET}  ${DIM}[${model} model]${RESET}`,
     );
     console.log(
-      `    Essential     : ${GREEN}${selection.essential.map((s) => s.name).join(", ")}${RESET}`,
+      `    Essential     : ${GREEN}${selection.essential.map(s => s.name).join(', ')}${RESET}`,
     );
     console.log(
-      `    Supplementary : ${YELLOW}${selection.supplementary.map((s) => s.name).join(", ") || "(small mode)"}${RESET}`,
+      `    Supplementary : ${YELLOW}${selection.supplementary.map(s => s.name).join(', ') || '(small mode)'}${RESET}`,
     );
     console.log(`    Time          : ${DIM}${elapsed}ms${RESET}`);
   }
 
-  console.log(
-    `\n${CYAN}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${RESET}\n`,
-  );
+  console.log(`\n${CYAN}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${RESET}\n`);
 }
 
 // ── Public API ────────────────────────────────────────────────────────────────
@@ -836,11 +722,22 @@ function runDemo(agentDir) {
  * @param {string}   agentDir - Path to .agent/ directory
  * @returns {{ essential, supplementary, available, promptText }}
  */
-function broker(task, files = [], model = "large", agentDir = null) {
+function broker(task, files = [], model = 'large', agentDir = null) {
+  let taskStr = task;
+  let filesArr = files;
+  let modelStr = model;
+
+  if (typeof task === 'object' && task !== null) {
+    taskStr = task.task || task.spec || '';
+    if (task.files) filesArr = task.files;
+    if (task.file) filesArr = [task.file];
+    if (task.model) modelStr = task.model;
+  }
+
   const resolvedAgentDir = agentDir || findAgentDir();
   const skills = loadSkills(resolvedAgentDir);
-  const selection = selectSkills(task, files, model, skills);
-  const promptText = formatPrompt(task, model, selection);
+  const selection = selectSkills(taskStr, filesArr, modelStr, skills);
+  const promptText = formatPrompt(taskStr, modelStr, selection);
   return { ...selection, promptText };
 }
 
@@ -857,16 +754,16 @@ function broker(task, files = [], model = "large", agentDir = null) {
  * @param {string}   agentDir - Path to .agent/ directory
  * @returns {object} Phase-specific context
  */
-function brokerForPipeline(task, files = [], phase = "build", agentDir = null) {
+function brokerForPipeline(task, files = [], phase = 'build', agentDir = null) {
   const resolvedAgentDir = agentDir || findAgentDir();
   const skills = loadSkills(resolvedAgentDir);
   // Always use "small" model tier for aggressive pruning in pipeline mode
-  const selection = selectSkills(task, files, "small", skills);
+  const selection = selectSkills(task, files, 'small', skills);
 
-  if (phase === "plan") {
+  if (phase === 'plan') {
     // Plan phase: skill names and descriptions only — no content, no keyRules
     return {
-      phase: "plan",
+      phase: 'plan',
       skills: selection.essential.slice(0, 6).map(s => ({
         name: s.name,
         description: s.description,
@@ -876,23 +773,23 @@ function brokerForPipeline(task, files = [], phase = "build", agentDir = null) {
     };
   }
 
-  if (phase === "build") {
+  if (phase === 'build') {
     // Build phase: top 3 essential keyRules — maximum density, minimum tokens
     return {
-      phase: "build",
+      phase: 'build',
       skills: selection.essential.slice(0, 3).map(s => ({
         name: s.name,
-        keyRules: s.keyRules || "",
+        keyRules: s.keyRules || '',
         score: selection.scores.get(s.name) || 0,
       })),
     };
   }
 
-  if (phase === "validate") {
+  if (phase === 'validate') {
     // Validate phase: return detected stack for targeted pattern matching
     const fileExts = files.map(f => path.extname(f).toLowerCase()).filter(Boolean);
     return {
-      phase: "validate",
+      phase: 'validate',
       detectedExtensions: fileExts,
       essentialSkillNames: selection.essential.slice(0, 3).map(s => s.name),
     };
@@ -910,18 +807,20 @@ function brokerForPipeline(task, files = [], phase = "build", agentDir = null) {
  */
 function formatPipelinePlan(task, pipelineResult) {
   const lines = [
-    "# Pipeline Planner Context",
+    '# Pipeline Planner Context',
     `# Task: ${task}`,
-    "",
-    "## Matched Skills (by relevance)",
-    "",
+    '',
+    '## Matched Skills (by relevance)',
+    '',
   ];
   for (const s of pipelineResult.skills) {
-    lines.push(`- **${s.name}** (score: ${s.score.toFixed(1)}): ${(s.description || "").slice(0, 120)}`);
+    lines.push(
+      `- **${s.name}** (score: ${s.score.toFixed(1)}): ${(s.description || '').slice(0, 120)}`,
+    );
   }
-  lines.push("");
+  lines.push('');
   lines.push(`Total matched: ${pipelineResult.total_matched}`);
-  return lines.join("\n");
+  return lines.join('\n');
 }
 
 /**
@@ -931,24 +830,38 @@ function formatPipelinePlan(task, pipelineResult) {
  * @returns {string}
  */
 function formatPipelineBuild(task, pipelineResult) {
-  const lines = [
-    "# Builder Context — Essential Rules Only",
-    `# Task: ${task}`,
-    "",
-  ];
+  const lines = ['# Builder Context — Essential Rules Only', `# Task: ${task}`, ''];
   for (const s of pipelineResult.skills) {
     lines.push(`## ${s.name}`);
-    lines.push("");
-    lines.push(s.keyRules || "(no key rules extracted)");
-    lines.push("");
-    lines.push("---");
-    lines.push("");
+    lines.push('');
+    lines.push(s.keyRules || '(no key rules extracted)');
+    lines.push('');
+    lines.push('---');
+    lines.push('');
   }
-  return lines.join("\n");
+  return lines.join('\n');
+}
+
+function resolveContext(opts = {}) {
+  let task = '';
+  let files = [];
+  let model = 'large';
+  let agentDir = null;
+
+  if (typeof opts === 'string') {
+    task = opts;
+  } else if (opts && typeof opts === 'object') {
+    task = opts.task || opts.spec || '';
+    files = opts.files || (opts.file ? [opts.file] : []);
+    model = opts.model || 'large';
+    agentDir = opts.agentDir || null;
+  }
+  return broker(task, files, model, agentDir);
 }
 
 module.exports = {
   broker,
+  resolveContext,
   brokerForPipeline,
   selectSkills,
   loadSkills,
@@ -964,7 +877,7 @@ module.exports = {
 if (require.main === module) {
   const argv = process.argv.slice(2);
 
-  if (!argv.length || argv.includes("--help") || argv.includes("-h")) {
+  if (!argv.length || argv.includes('--help') || argv.includes('-h')) {
     console.log(`
 ${BOLD}context_broker.js${RESET} — Tribunal Focus-without-Compromise Context Engine
 
@@ -993,21 +906,19 @@ ${BOLD}Examples:${RESET}
 
   const agentDir = findAgentDir();
 
-  if (argv[0] === "demo") {
+  if (argv[0] === 'demo') {
     runDemo(agentDir);
     process.exit(0);
   }
 
   // Parse args
-  const taskIdx = argv.indexOf("--task");
-  const modelIdx = argv.indexOf("--model");
-  const outputIdx = argv.indexOf("--output");
+  const taskIdx = argv.indexOf('--task');
+  const modelIdx = argv.indexOf('--model');
+  const outputIdx = argv.indexOf('--output');
 
-  const task = taskIdx !== -1 && argv[taskIdx + 1] ? argv[taskIdx + 1] : "";
-  const model =
-    modelIdx !== -1 && argv[modelIdx + 1] ? argv[modelIdx + 1] : "large";
-  const output =
-    outputIdx !== -1 && argv[outputIdx + 1] ? argv[outputIdx + 1] : "report";
+  const task = taskIdx !== -1 && argv[taskIdx + 1] ? argv[taskIdx + 1] : '';
+  const model = modelIdx !== -1 && argv[modelIdx + 1] ? argv[modelIdx + 1] : 'large';
+  const output = outputIdx !== -1 && argv[outputIdx + 1] ? argv[outputIdx + 1] : 'report';
 
   if (!task) {
     console.error(`${RED}✖ --task is required${RESET}`);
@@ -1017,16 +928,14 @@ ${BOLD}Examples:${RESET}
   // Collect --file arguments (may appear multiple times)
   const files = [];
   for (let i = 0; i < argv.length; i++) {
-    if (argv[i] === "--file" && argv[i + 1]) files.push(argv[i + 1]);
+    if (argv[i] === '--file' && argv[i + 1]) files.push(argv[i + 1]);
   }
 
-  const validModels = ["large", "small"];
+  const validModels = ['large', 'small'];
   let effectiveModel = model;
   if (!validModels.includes(model)) {
-    console.error(
-      `${YELLOW}⚠ Unknown model tier "${model}" — defaulting to "large"${RESET}`,
-    );
-    effectiveModel = "large";
+    console.error(`${YELLOW}⚠ Unknown model tier "${model}" — defaulting to "large"${RESET}`);
+    effectiveModel = 'large';
   }
 
   const t0 = Date.now();
@@ -1035,22 +944,22 @@ ${BOLD}Examples:${RESET}
   const elapsed = Date.now() - t0;
 
   switch (output) {
-    case "json":
+    case 'json':
       console.log(formatJson(task, effectiveModel, selection));
       break;
-    case "names":
+    case 'names':
       console.log(formatNames(selection, effectiveModel));
       break;
-    case "prompt":
+    case 'prompt':
       console.log(formatPrompt(task, effectiveModel, selection));
       break;
-    case "pipeline-plan": {
-      const pipelinePlan = brokerForPipeline(task, files, "plan", agentDir);
+    case 'pipeline-plan': {
+      const pipelinePlan = brokerForPipeline(task, files, 'plan', agentDir);
       console.log(formatPipelinePlan(task, pipelinePlan));
       break;
     }
-    case "pipeline-build": {
-      const pipelineBuild = brokerForPipeline(task, files, "build", agentDir);
+    case 'pipeline-build': {
+      const pipelineBuild = brokerForPipeline(task, files, 'build', agentDir);
       console.log(formatPipelineBuild(task, pipelineBuild));
       break;
     }
@@ -1059,7 +968,3 @@ ${BOLD}Examples:${RESET}
       break;
   }
 }
-
-
-
-