@causyne/agent 0.0.0-stage → 1.10.0

package/src/slopDetector.js

@@ -0,0 +1,307 @@
+// Anti-AI-Slop Detector (Vision §7, ENFORCED)
+//
+// WHY THIS EXISTS
+// The anti-slop mandate has been prompt-only: PACK_PLAYBOOKS.web tells the model
+// what not to do, and the web guard in agentLoop.js forces it to LOOK at the
+// result. But the model was the only judge of what it saw, and a model that just
+// produced a purple gradient hero does not reliably call its own work generic.
+// This module is the second opinion — a static read of the HTML/CSS the agent
+// actually wrote.
+//
+// DESIGN RULE: WEIGHTED, NEVER A SINGLE TRIPWIRE
+// A purple gradient is not automatically slop; a purple gradient PLUS emoji
+// icons PLUS "Elevate your workflow" PLUS default fonts is. Every signal carries
+// a weight and the verdict is a threshold, because a guard with false positives
+// gets disabled — the same reasoning .agents/rules.json ZM-09 applies to the
+// malware guards.
+//
+// Plaintext by construction: clear names, readable regex, no encoded strings,
+// no shell, no dependency (Vision §10's rule for defence code applies equally to
+// quality code that has to be argued with).
+
+/** Files worth scanning. Anything else is not a rendered surface. */
+const SCANNABLE_EXTENSIONS = /\.(html?|css|jsx?|tsx?|vue|svelte|astro)$/i;
+
+export function isScannableFile(filePath) {
+  return SCANNABLE_EXTENSIONS.test(String(filePath || ''));
+}
+
+// ---------------------------------------------------------------------------
+// Colour helpers
+// ---------------------------------------------------------------------------
+
+function hexToHue(hex) {
+  const clean = hex.replace('#', '');
+  const full = clean.length === 3
+    ? clean.split('').map(c => c + c).join('')
+    : clean;
+  if (full.length !== 6) return null;
+
+  const r = parseInt(full.slice(0, 2), 16) / 255;
+  const g = parseInt(full.slice(2, 4), 16) / 255;
+  const b = parseInt(full.slice(4, 6), 16) / 255;
+  const max = Math.max(r, g, b);
+  const min = Math.min(r, g, b);
+  const delta = max - min;
+  if (delta === 0) return null; // greyscale has no hue to judge
+
+  let hue;
+  if (max === r) hue = ((g - b) / delta) % 6;
+  else if (max === g) hue = (b - r) / delta + 2;
+  else hue = (r - g) / delta + 4;
+
+  hue = Math.round(hue * 60);
+  return hue < 0 ? hue + 360 : hue;
+}
+
+/** Indigo through violet — the band the AI house style lives in. */
+function isPurpleBlueHue(hue) {
+  return hue !== null && hue >= 220 && hue <= 290;
+}
+
+// ---------------------------------------------------------------------------
+// Signals
+//
+// Each returns null, or a finding: { id, weight, evidence, fix }.
+// ---------------------------------------------------------------------------
+
+/**
+ * The exact hex pairs that recur across AI-generated pages. These are not
+ * "purple-ish" — they are the specific values that appear verbatim in
+ * thousands of generated templates, which is why they score highest.
+ */
+const NOTORIOUS_GRADIENT_COLORS = [
+  '#667eea', '#764ba2', // the single most reproduced pair on the web
+  '#6366f1', '#8b5cf6', // indigo-500 / violet-500 straight from the Tailwind ramp
+  '#a855f7', '#7c3aed',
+  '#4f46e5', '#9333ea'
+];
+
+function detectNotoriousGradient(text) {
+  const lower = text.toLowerCase();
+  const hits = NOTORIOUS_GRADIENT_COLORS.filter(color => lower.includes(color));
+  if (hits.length < 2) return null;
+  return {
+    id: 'notorious-gradient-hexes',
+    weight: 40,
+    evidence: `the stock AI gradient colours ${hits.slice(0, 4).join(', ')} appear verbatim`,
+    fix: 'Replace with a palette chosen for THIS project. These specific hexes are the most reproduced values in AI-generated design.'
+  };
+}
+
+/** A linear-gradient whose stops all sit in the indigo→violet band. */
+function detectPurpleBlueGradient(text) {
+  const gradients = text.match(/linear-gradient\s*\([^)]*\)/gi) || [];
+  for (const gradient of gradients) {
+    const hexes = gradient.match(/#[0-9a-f]{3,8}\b/gi) || [];
+    if (hexes.length < 2) continue;
+    const hues = hexes.map(hexToHue).filter(hue => hue !== null);
+    if (hues.length >= 2 && hues.every(isPurpleBlueHue)) {
+      return {
+        id: 'purple-blue-gradient',
+        weight: 30,
+        evidence: `a gradient runs entirely through the indigo/violet band: ${gradient.slice(0, 80)}`,
+        fix: 'Vision §7 bans purple-to-blue as the primary scheme. Commit to a design movement and take the palette from there.'
+      };
+    }
+  }
+  return null;
+}
+
+/** Marketing filler that says nothing about the actual product. */
+const GENERIC_COPY_PATTERNS = [
+  /\belevate your\b/i,
+  /\btransform your\b/i,
+  /\btake your \w+ to the next level\b/i,
+  /\bunlock the (full )?power of\b/i,
+  /\bsupercharge your\b/i,
+  /\brevolutioni[sz]e (your|the)\b/i,
+  /\bseamlessly integrate\b/i,
+  /\blorem ipsum\b/i,
+  /\byour (one[- ]stop|all[- ]in[- ]one) (shop|solution|platform)\b/i,
+  /\bempower(ing)? (your|teams?) \w+\b/i
+];
+
+function detectGenericCopy(text) {
+  const hits = GENERIC_COPY_PATTERNS
+    .map(pattern => text.match(pattern))
+    .filter(Boolean)
+    .map(match => match[0]);
+  if (hits.length === 0) return null;
+  return {
+    id: 'generic-marketing-copy',
+    weight: hits.length >= 2 ? 25 : 15,
+    evidence: `filler copy: ${[...new Set(hits)].slice(0, 3).map(h => `"${h}"`).join(', ')}`,
+    fix: 'Write copy about what this specific product actually does. Placeholder marketing language is a slop signature in itself.'
+  };
+}
+
+/** Emoji standing in for a designed icon set. */
+function detectEmojiIcons(text) {
+  // The recurring "feature card" emoji vocabulary, not emoji in general.
+  const iconEmoji = text.match(/[\u{1F680}\u{2728}\u{1F4A1}\u{1F3AF}\u{26A1}\u{1F512}\u{1F4C8}\u{1F527}\u{1F31F}\u{1F4AA}]/gu) || [];
+  if (iconEmoji.length < 3) return null;
+  return {
+    id: 'emoji-as-icons',
+    weight: 20,
+    evidence: `${iconEmoji.length} placeholder-icon emoji (${[...new Set(iconEmoji)].slice(0, 5).join(' ')})`,
+    fix: 'Use a real icon set, or inline SVG drawn for this project. Rocket/sparkle/bulb emoji as feature icons is a template tell.'
+  };
+}
+
+/** The shadow that ships with every generated card. */
+function detectStockShadow(text) {
+  const shadows = text.match(/box-shadow\s*:\s*0\s+(?:10|20)px\s+(?:20|25|30|40)px\s+rgba\(\s*0\s*,\s*0\s*,\s*0\s*,\s*0?\.\d+\s*\)/gi) || [];
+  if (shadows.length === 0) return null;
+  return {
+    id: 'stock-soft-shadow',
+    weight: 10,
+    evidence: `the default soft card shadow appears ${shadows.length}×`,
+    fix: 'Shadow should follow the movement you chose — brutalism has none, editorial uses hairline rules, deco uses hard offsets.'
+  };
+}
+
+/**
+ * No real typography decision was made.
+ *
+ * Only meaningful for documents that actually declare styling — a stylesheet
+ * fragment that sets no font is not evidence of anything.
+ */
+function detectDefaultTypography(text) {
+  const declaresFontFamily = /font-family\s*:/i.test(text);
+  if (!declaresFontFamily) return null;
+
+  const loadsWebFont = /@font-face|fonts\.googleapis\.com|fonts\.bunny\.net|@import\s+url\([^)]*font/i.test(text);
+  if (loadsWebFont) return null;
+
+  const onlySystemStacks = !/font-family\s*:\s*[^;]*['"][A-Za-z]/i.test(text);
+  if (!onlySystemStacks) return null;
+
+  return {
+    id: 'default-typography',
+    weight: 15,
+    evidence: 'every font-family resolves to a system default; no typeface was chosen',
+    fix: 'Pick a typeface that belongs to the design movement. Typography is the fastest way out of the house style.'
+  };
+}
+
+/** Hero + exactly three feature cards + closing CTA: the generated-SaaS skeleton. */
+function detectCookieCutterStructure(text) {
+  if (!/<html|<body|<section|<main/i.test(text)) return null;
+
+  const hasCenteredHero = /class\s*=\s*["'][^"']*\bhero\b/i.test(text) &&
+                          /text-align\s*:\s*center|\btext-center\b/i.test(text);
+  const featureCards = (text.match(/class\s*=\s*["'][^"']*\b(feature|card)\b/gi) || []).length;
+  const hasCtaPair = /get started/i.test(text) && /learn more/i.test(text);
+
+  const signals = [hasCenteredHero, featureCards >= 3, hasCtaPair].filter(Boolean).length;
+  if (signals < 2) return null;
+
+  return {
+    id: 'cookie-cutter-layout',
+    weight: signals === 3 ? 25 : 15,
+    evidence: `the stock landing skeleton: ${hasCenteredHero ? 'centered hero, ' : ''}${featureCards >= 3 ? `${featureCards} feature cards, ` : ''}${hasCtaPair ? '"Get Started"/"Learn More" pair' : ''}`.replace(/,\s*$/, ''),
+    fix: 'Vision §7 bans the centered-hero + gradient + "Get Started" template. Restructure around the content this page actually has.'
+  };
+}
+
+/** Gradient text — a purple gradient clipped to a headline. */
+function detectGradientText(text) {
+  if (!/background-clip\s*:\s*text|-webkit-background-clip\s*:\s*text/i.test(text)) return null;
+  const hasPurpleGradient = detectPurpleBlueGradient(text) || detectNotoriousGradient(text);
+  if (!hasPurpleGradient) return null;
+  return {
+    id: 'gradient-clipped-headline',
+    weight: 15,
+    evidence: 'a headline is filled with the same purple gradient',
+    fix: 'Gradient-filled display type over a purple ramp is the compound form of the signature. Use solid ink and let layout carry the emphasis.'
+  };
+}
+
+const SIGNALS = [
+  detectNotoriousGradient,
+  detectPurpleBlueGradient,
+  detectGenericCopy,
+  detectEmojiIcons,
+  detectStockShadow,
+  detectDefaultTypography,
+  detectCookieCutterStructure,
+  detectGradientText
+];
+
+/**
+ * Score one document.
+ *
+ * @returns {{score: number, verdict: string, findings: Array}}
+ *   verdict: 'clean' | 'borderline' | 'slop'
+ */
+export function analyzeSource(text) {
+  const source = typeof text === 'string' ? text : '';
+  const findings = [];
+
+  for (const signal of SIGNALS) {
+    try {
+      const finding = signal(source);
+      if (finding) findings.push(finding);
+    } catch (e) { /* one bad signal must not sink the analysis */ }
+  }
+
+  const score = findings.reduce((sum, finding) => sum + finding.weight, 0);
+  return { score, verdict: verdictFor(score), findings };
+}
+
+// A single mid-weight signal is a stylistic choice. Two or three compounding is
+// the house style. The thresholds are deliberately not tight.
+export const BORDERLINE_SCORE = 30;
+export const SLOP_SCORE = 45;
+
+export function verdictFor(score) {
+  if (score >= SLOP_SCORE) return 'slop';
+  if (score >= BORDERLINE_SCORE) return 'borderline';
+  return 'clean';
+}
+
+/**
+ * Score a set of files. Findings are merged across the set, because the
+ * gradient usually lives in the CSS and the copy in the HTML.
+ */
+export function analyzeFiles(files) {
+  const merged = new Map();
+  const scanned = [];
+
+  for (const file of files || []) {
+    if (!file || !isScannableFile(file.path)) continue;
+    scanned.push(file.path);
+    for (const finding of analyzeSource(file.content).findings) {
+      // Keep the highest-weight instance of each signal, and remember where.
+      const existing = merged.get(finding.id);
+      if (!existing || finding.weight > existing.weight) {
+        merged.set(finding.id, { ...finding, path: file.path });
+      }
+    }
+  }
+
+  const findings = [...merged.values()];
+  const score = findings.reduce((sum, finding) => sum + finding.weight, 0);
+  return { score, verdict: verdictFor(score), findings, scanned };
+}
+
+/** Render findings as the corrective message the agent is handed. */
+export function formatFindings(result, movementBrief = '') {
+  const lines = [];
+  lines.push(`[ANTI-SLOP GATE: the generated design scores ${result.score} (${result.verdict}) against Vision §7.]`);
+  lines.push('');
+  lines.push('Detected signatures:');
+  for (const finding of result.findings) {
+    lines.push(`- ${finding.id}${finding.path ? ` (${finding.path})` : ''}: ${finding.evidence}`);
+    lines.push(`  → ${finding.fix}`);
+  }
+  if (movementBrief) {
+    lines.push('');
+    lines.push('Commit to ONE of these movements and rebuild the visual layer from it:');
+    lines.push(movementBrief);
+  }
+  lines.push('');
+  lines.push('Rework the design and verify again. Do not simply swap one gradient for another.');
+  return lines.join('\n');
+}

package/src/taskBuffer.js

@@ -0,0 +1,45 @@
+import fs from 'fs';
+import path from 'path';
+import os from 'os';
+import { causyneHome } from './utils/paths.js';
+
+const BUFFER_DIR = path.join(causyneHome(), 'buffers');
+
+export class TaskBuffer {
+  constructor() {
+    this.ensureDir();
+  }
+
+  ensureDir() {
+    if (!fs.existsSync(BUFFER_DIR)) {
+      fs.mkdirSync(BUFFER_DIR, { recursive: true });
+    }
+  }
+
+  getBufferPath(taskId) {
+    return path.join(BUFFER_DIR, `${taskId}.jsonl`);
+  }
+
+  async appendOutput(taskId, stepData) {
+    const file = this.getBufferPath(taskId);
+    const entry = JSON.stringify({ ts: Date.now(), ...stepData }) + '\n';
+    fs.appendFileSync(file, entry);
+  }
+
+  async getBuffer(taskId) {
+    const file = this.getBufferPath(taskId);
+    if (!fs.existsSync(file)) return [];
+    
+    const content = fs.readFileSync(file, 'utf8');
+    return content.split('\n')
+      .filter(l => l.trim())
+      .map(l => JSON.parse(l));
+  }
+  
+  async clearBuffer(taskId) {
+    const file = this.getBufferPath(taskId);
+    if (fs.existsSync(file)) {
+      fs.unlinkSync(file);
+    }
+  }
+}

package/src/taskShape.js

@@ -0,0 +1,241 @@
+
+
+const PACK_SIGNALS = {
+  game: {
+    strong: ['game', 'gamedev', 'permainan', 'godot', 'unity', 'unreal', 'rpg', 'platformer', 'roguelike', 'arcade', 'voxel', 'minecraft', 'tilemap', 'spritesheet', 'boss fight', 'level design'],
+    weak: ['sprite', 'player', 'enemy', 'quest', 'npc', 'gameplay', 'multiplayer', 'leaderboard']
+  },
+  web: {
+    strong: ['web app', 'webapp', 'website', 'situs', 'landing page', 'homepage', 'frontend', 'front-end', 'dashboard', 'portfolio', 'react', 'vue', 'svelte', 'angular', 'nextjs', 'next.js', 'nuxt', 'astro', 'tailwind', 'html', 'css'],
+    weak: ['web', 'ui', 'ux', 'page', 'halaman', 'responsive', 'browser', 'dom', 'component', 'layout', 'design', 'desain', 'tampilan']
+  },
+  media: {
+    strong: ['generate image', 'generate video', 'generate music', 'text to speech', 'voiceover', 'blender', 'davinci', 'resolve', 'render', '3d model', 'animation', 'animasi'],
+    weak: ['image', 'gambar', 'photo', 'foto', 'video', 'audio', 'sound', 'suara', 'music', 'musik', 'lagu', 'thumbnail', 'poster', 'logo', 'illustration']
+  },
+  system: {
+    strong: ['kill process', 'port', 'zip', 'unzip', 'tar', 'archive', 'clipboard', 'printer', 'print', 'cetak'],
+    weak: ['process', 'proses', 'compress', 'extract', 'ekstrak', 'open app', 'launch']
+  },
+  advanced: {
+    strong: ['pdf', 'forge a tool', 'custom tool', 'subagent', 'sub-agent', 'parallel agent'],
+    weak: ['symbols', 'ast', 'refactor', 'orchestrate', 'swarm']
+  }
+};
+
+const STRONG_WEIGHT = 3;
+const WEAK_WEIGHT = 1;
+const PACK_THRESHOLD = 3;
+
+// ---------------------------------------------------------------------------
+// Task archetypes. Each one carries the phase plan the agent should follow and
+// the tools that matter in each phase.
+// ---------------------------------------------------------------------------
+
+const ARCHETYPES = {
+  integrate: {
+    label: 'Build an application that integrates live external data',
+    match: {
+      strong: ['realtime', 'real-time', 'real time', 'api', 'rest', 'webhook', 'integration', 'integrasi', 'sync', 'sinkron', 'automation', 'automasi', 'otomasi', 'automate', 'otomatis', 'booking', 'tiket', 'ticket', 'calendar', 'kalender', 'jadwal', 'schedule', 'payment', 'pembayaran'],
+      weak: ['live', 'stream', 'fetch', 'data', 'third party', 'oauth', 'token']
+    },
+    phases: [
+      { name: 'Research the data sources FIRST', tools: ['web_search', 'web_fetch'], note: 'Identify the exact official REST APIs, their auth model, rate limits and response shape before writing any code. Prefer documented JSON APIs over browser scraping — reading JSON always beats reading DOM.' },
+      { name: 'Verify access and versions', tools: ['sysRun', 'web_fetch'], note: 'Probe one real endpoint and check current package versions with `npm view <pkg> version` before pinning anything. Never assume a version from memory.' },
+      { name: 'Scaffold', tools: ['fs_write', 'sysRun'], note: 'Create the project structure and dependency manifest.' },
+      { name: 'Implement', tools: ['fs_read', 'fs_edit', 'MultiEdit'], note: 'Build the integration layer first, the UI second. Handle auth failures and rate limits explicitly.' },
+      { name: 'Verify', tools: ['code_verify_syntax', 'sysRun'], note: 'Run the build, lint and type-check. Exercise the live data path end to end, not just the happy path.' }
+    ]
+  },
+  build_app: {
+    label: 'Build a new application from scratch',
+    match: {
+      strong: ['build me', 'buatkan', 'buat aku', 'create a', 'make me', 'bikin', 'develop a', 'new app', 'from scratch'],
+      weak: ['app', 'aplikasi', 'project', 'proyek', 'tool', 'system', 'sistem']
+    },
+    phases: [
+      { name: 'Plan', tools: ['TodoWrite'], note: 'Break the build into atomic, verifiable steps before touching the filesystem.' },
+      { name: 'Scaffold', tools: ['fs_write', 'sysRun'], note: 'Create structure and install dependencies at verified current versions.' },
+      { name: 'Implement', tools: ['fs_write', 'fs_edit', 'MultiEdit'], note: 'Write runnable code with every import and dependency present.' },
+      { name: 'Verify', tools: ['code_verify_syntax', 'sysRun'], note: 'Build, lint and run it. Never assume code works.' }
+    ]
+  },
+  debug: {
+    label: 'Diagnose and fix a defect in existing code',
+    match: {
+      strong: ['bug', 'error', 'crash', 'fix', 'perbaiki', 'benerin', 'broken', 'rusak', 'not working', 'gagal', 'failing', 'exception', 'stack trace', 'regression'],
+      weak: ['issue', 'masalah', 'problem', 'wrong', 'salah', 'debug']
+    },
+    phases: [
+      { name: 'Reproduce', tools: ['sysRun', 'fs_read'], note: 'Reproduce the failure and capture the exact error before changing anything.' },
+      { name: 'Locate', tools: ['code_search_ripgrep', 'codebase_search', 'fs_read'], note: 'Search several phrasings in parallel. Read the file before patching it.' },
+      { name: 'Fix', tools: ['fs_edit', 'MultiEdit'], note: 'Make the smallest correct change. Do not touch unrelated code.' },
+      { name: 'Verify', tools: ['sysRun', 'code_verify_syntax'], note: 'Confirm the original reproduction now passes.' }
+    ]
+  },
+  research: {
+    label: 'Investigate and report, without changing the system',
+    match: {
+      strong: ['explain', 'jelaskan', 'analyse', 'analyze', 'analisa', 'research', 'riset', 'compare', 'bandingkan', 'what is', 'apa itu', 'how does', 'bagaimana', 'review', 'audit'],
+      weak: ['understand', 'pahami', 'find out', 'cari tahu', 'summarize', 'ringkas']
+    },
+    phases: [
+      { name: 'Gather', tools: ['code_search_ripgrep', 'fs_read', 'web_search', 'web_fetch'], note: 'Search broadly with several phrasings in parallel before concluding.' },
+      { name: 'Report', tools: [], note: 'Answer concisely and cite exact file paths or URLs. Do not modify anything unless asked.' }
+    ]
+  },
+  maintain: {
+    label: 'Operate on files, processes or the machine itself',
+    match: {
+      strong: ['organize', 'rapikan', 'clean up', 'bersihkan', 'rename', 'ganti nama', 'move', 'pindahkan', 'backup', 'cadangkan', 'delete', 'hapus', 'install', 'deploy', 'commit', 'merge'],
+      weak: ['folder', 'directory', 'file', 'berkas', 'desktop', 'downloads']
+    },
+    phases: [
+      { name: 'Survey', tools: ['fs_list', 'fs_find'], note: 'List and count what you are about to touch, and report it, before acting.' },
+      { name: 'Act', tools: ['fs_move', 'fs_write', 'sysRun'], note: 'Prefer reversible operations. Flag anything destructive for approval.' },
+      { name: 'Confirm', tools: ['fs_list'], note: 'Verify the end state matches what the user asked for.' }
+    ]
+  }
+};
+
+const ARCHETYPE_NAMES = Object.keys(ARCHETYPES);
+
+// ---------------------------------------------------------------------------
+// Scoring
+// ---------------------------------------------------------------------------
+
+function scoreSignals(text, signals) {
+  let score = 0;
+  const hits = [];
+
+  for (const term of signals.strong || []) {
+    if (text.includes(term)) {
+      score += STRONG_WEIGHT;
+      hits.push(term);
+    }
+  }
+  for (const term of signals.weak || []) {
+    // Word-boundary check for short weak terms so 'ui' cannot match 'build'
+    // and 'race' cannot match 'trace' — the exact class of false positive that
+    // used to drag ordinary tasks into game and web enforcement.
+    const pattern = new RegExp(`(^|[^a-z0-9])${term.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}($|[^a-z0-9])`, 'i');
+    if (pattern.test(text)) {
+      score += WEAK_WEIGHT;
+      hits.push(term);
+    }
+  }
+
+  return { score, hits };
+}
+
+/**
+ * Analyse a request into the shape of the work it implies.
+ *
+ * @param {string} prompt
+ * @param {object} workspaceContext  Optional perception output.
+ * @returns {{
+ *   archetype: string,
+ *   archetypeLabel: string,
+ *   packs: Array<{name: string, score: number}>,
+ *   phases: Array<object>,
+ *   confidence: string
+ * }}
+ */
+export function analyzeTask(prompt, workspaceContext = null) {
+  const text = String(prompt || '').toLowerCase();
+
+  // Which capability packs are worth their token cost for this request.
+  const packScores = [];
+  for (const packName of Object.keys(PACK_SIGNALS)) {
+    const { score } = scoreSignals(text, PACK_SIGNALS[packName]);
+    if (score >= PACK_THRESHOLD) {
+      packScores.push({ name: packName, score });
+    }
+  }
+
+  // Workspace evidence outranks keywords: a Godot project on disk is far more
+  // reliable than any phrasing in the prompt.
+  if (workspaceContext) {
+    const signals = [
+      workspaceContext.framework,
+      workspaceContext.projectType,
+      workspaceContext.designSystem,
+      Array.isArray(workspaceContext.keyFiles) ? workspaceContext.keyFiles.join(' ') : ''
+    ].filter(Boolean).join(' ').toLowerCase();
+
+    const bump = (name, amount) => {
+      const existing = packScores.find(p => p.name === name);
+      if (existing) existing.score += amount;
+      else packScores.push({ name, score: amount });
+    };
+
+    if (/godot|project\.godot|unity|\.tscn/.test(signals)) bump('game', 5);
+    if (/react|vue|svelte|next|nuxt|astro|angular|tailwind|vite|index\.html/.test(signals)) bump('web', 4);
+  }
+
+  packScores.sort((a, b) => b.score - a.score);
+
+  // Which archetype the work follows.
+  let bestArchetype = null;
+  let bestScore = 0;
+  for (const name of ARCHETYPE_NAMES) {
+    const { score } = scoreSignals(text, ARCHETYPES[name].match);
+    if (score > bestScore) {
+      bestScore = score;
+      bestArchetype = name;
+    }
+  }
+
+  // A build request that also talks about live external data is an integration
+  // job first and a build job second — that ordering is what stops the agent
+  // scaffolding a UI before it knows whether the API even exists.
+  const integrationScore = scoreSignals(text, ARCHETYPES.integrate.match).score;
+  if (integrationScore >= STRONG_WEIGHT && bestArchetype === 'build_app') {
+    bestArchetype = 'integrate';
+    bestScore = integrationScore;
+  }
+
+  const archetype = bestArchetype || 'build_app';
+  const confidence = bestScore >= 6 ? 'high' : (bestScore >= 3 ? 'medium' : 'low');
+
+  return {
+    archetype,
+    archetypeLabel: ARCHETYPES[archetype].label,
+    packs: packScores,
+    phases: ARCHETYPES[archetype].phases,
+    confidence
+  };
+}
+
+/**
+ * Render the analysis as a compact brief for the system prompt.
+ *
+ * This is the piece that turns "here are 28 tools" into "here is the order to
+ * use them in". It costs roughly 150-200 tokens and routinely saves whole
+ * exploratory steps, each of which costs thousands.
+ */
+export function buildTaskBrief(shape, availableToolNames) {
+  if (!shape) return '';
+
+  const available = new Set(availableToolNames || []);
+  const lines = [];
+
+  lines.push('# TASK SHAPE (analysed from your request)');
+  lines.push(`Work type: ${shape.archetypeLabel}.`);
+  lines.push('Follow this sequence. Do not skip ahead — each phase de-risks the next.');
+
+  shape.phases.forEach((phase, index) => {
+    const tools = (phase.tools || []).filter(name => available.has(name));
+    const toolList = tools.length > 0 ? ` [${tools.join(', ')}]` : '';
+    lines.push(`${index + 1}. ${phase.name}${toolList} — ${phase.note}`);
+  });
+
+  lines.push('Tools outside this list remain fully available; search for them with tool_search when a phase genuinely needs one.');
+
+  return lines.join('\n');
+}
+
+/** Pack names above threshold, highest score first. */
+export function packsFromShape(shape) {
+  return shape && Array.isArray(shape.packs) ? shape.packs.map(p => p.name) : [];
+}