@kognai/build 0.6.0

package/dist/bin/kognai-build.js

@@ -0,0 +1,774 @@
+#!/usr/bin/env node
+"use strict";
+/**
+ * @kognai/build — npx kognai-build "<task>"
+ *
+ * Submit one task to the Kognai sovereign orchestrator runtime:
+ * a coder generates the file, two reviewers grade code quality,
+ * a third reviewer checks constitutional + legal + security compliance.
+ * Triple consensus decides ship or reject.
+ *
+ * This package is the BUILDER-FACING distribution. It uses the
+ * canonical Kognai orchestrator presentation language defined in
+ * docs/specs/orchestrator-presentation.md (in the kognai monorepo).
+ *
+ * Requires: ANTHROPIC_API_KEY env var. Optionally CLAUDE_MODEL to override
+ * the default model (claude-sonnet-4-20250514).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+require("../lib/boot-env"); // MUST be first: sets KOGNAI_ROOT before the engine loads (KSL scoping)
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const node_readline_1 = require("node:readline");
+// TICKET-233 Phase 1: route ALL model calls through the published engine.
+const orchestrator_core_1 = require("@kognai/orchestrator-core");
+const router_1 = require("../lib/router");
+const swarm_1 = require("../lib/swarm");
+const KSL_RUN_ID = 'kb-' + Math.floor(Date.now() / 1000).toString(36);
+// TICKET-203 + TICKET-207: workspace primitive — auto-discover .kognai/ in cwd.
+// When found: deliverables write to workspace.deliverable_root (not /tmp),
+// planner gets knowledge + memory context, session summary appends at end.
+const workspace_1 = require("../lib/workspace");
+const knowledge_1 = require("../lib/knowledge");
+const memory_1 = require("../lib/memory");
+// TICKET-202 PACT onboarding: a signed mandate is the autonomy envelope. Aliased
+// imports avoid clashing with this file's local estimateCost()/PlannedTask.
+const registry_1 = require("../templates/registry");
+const cost_estimator_1 = require("../lib/cost-estimator");
+const mandate_1 = require("../lib/mandate");
+// TICKET-233: validate template capabilities against the real registries.
+const skill_bank_1 = require("../lib/skill-bank");
+const tool_layer_1 = require("../lib/tool-layer");
+const workspace = (() => {
+    try {
+        return (0, workspace_1.discoverWorkspace)();
+    }
+    catch {
+        return null;
+    }
+})();
+// ─── Visual primitives (canonical presentation language v1.0) ────────────────
+const C = {
+    reset: '\x1b[0m', dim: '\x1b[2m', bold: '\x1b[1m', italic: '\x1b[3m',
+    red: '\x1b[31m', green: '\x1b[32m', yellow: '\x1b[33m', blue: '\x1b[34m',
+    magenta: '\x1b[35m', cyan: '\x1b[36m', gray: '\x1b[90m',
+    jade: '\x1b[38;5;79m',
+};
+const out = (s = '') => process.stdout.write(s + '\n');
+const W = 72;
+function wrap(text, width, indent) {
+    return text.split('\n').flatMap((para) => {
+        if (!para.trim())
+            return [''];
+        const words = para.split(/\s+/);
+        const lines = [];
+        let cur = '';
+        for (const w of words) {
+            if (cur.length + w.length + 1 > width) {
+                if (cur)
+                    lines.push(cur);
+                cur = w;
+            }
+            else {
+                cur = cur ? `${cur} ${w}` : w;
+            }
+        }
+        if (cur)
+            lines.push(cur);
+        return lines;
+    }).map((l) => indent + l).join('\n');
+}
+const visLen = (s) => s.replace(/\x1b\[[0-9;]*m/g, '').length;
+const ms = (n) => `${(n / 1000).toFixed(1)}s`;
+// TICKET-135 optimization profile axes (10 standard from ISO/IEC 25010 + 1 Kognai-native).
+// 'unspecified' = legacy default, treated as no-op (no profile guidance, supervisor reviews neutral).
+const VALID_PROFILES = ['security', 'reliability', 'performance', 'maintainability', 'compatibility', 'usability', 'portability', 'compliance', 'cost-efficiency', 'time-to-market', 'sovereignty'];
+function parseArgs() {
+    const args = process.argv.slice(2);
+    if (args.length === 0 || args[0] === '--help' || args[0] === '-h') {
+        out(`
+   ${C.bold}${C.jade}kognai-build${C.reset} ${C.gray}· sovereign orchestrator${C.reset}
+
+   Two surfaces. ${C.bold}Task mode${C.reset} runs the triple-supervisor on ONE
+   deliverable. ${C.bold}Goal mode${C.reset} decomposes the goal into tasks (CEO planner),
+   then runs each through the triple-supervisor — TICKET-135 hierarchy
+   visible end-to-end.
+
+   ${C.bold}Task mode${C.reset}
+     kognai-build "<task>" [--out <path>] [--profile <axis>] [--no-compliance]
+       npx @kognai/build "Postgres backup rotation script"
+       npx @kognai/build "Stripe webhook handler" --out src/webhook.ts
+       npx @kognai/build "rate limiter" --profile security
+
+   ${C.bold}Goal mode${C.reset}
+     kognai-build --goal "<goal>" [--out-dir <dir>] [--profile <axis>] [--no-compliance]
+       npx @kognai/build --goal "TypeScript SDK for a TODO REST API"
+       npx @kognai/build --goal "Express CRUD service with Postgres" --out-dir ./svc
+       npx @kognai/build --goal "auth service" --profile security --out-dir ./auth
+
+   ${C.bold}Mandate mode${C.reset} ${C.gray}(TICKET-202 — session = signed PACT mandate)${C.reset}
+     kognai-build --mandate "<goal>" [--out-dir <dir>] [--profile <axis>]
+       Recommends a template, previews capabilities + a heuristic cost envelope,
+       signs a local PACT mandate, then executes the goal within that envelope.
+       The signed mandate persists to .swarm-state/mandates/<id>.json.
+
+   ${C.bold}Swarm mode${C.reset} ${C.gray}(TICKET-233 — full @kognai/orchestrator-core swarm)${C.reset}
+     kognai-build --swarm "<goal>" [--out-dir <dir>] [--sovereign]
+       Decomposes the goal, then delegates to the full orchestrator swarm:
+       CEO planning · CTO governance gate · dual-supervisor review · reconciliation.
+       Heavier than the default pipeline; --sovereign runs it $0-local end to end.
+
+   ${C.bold}Sovereign${C.reset} ${C.gray}(any mode)${C.reset}
+     --sovereign   Route all inference to local Ollama ($0; no ANTHROPIC_API_KEY needed).
+
+   ${C.bold}Optimization profile${C.reset} (TICKET-135 axes — per the runtime doctrine)
+     security · reliability · performance · maintainability · compatibility
+     usability · portability · compliance · cost-efficiency · time-to-market · sovereignty
+     When set, the coder optimizes for the axis AND the supervisor lens matches it.
+     Default: unspecified (no profile guidance, neutral review).
+
+   ${C.bold}Pipeline${C.reset}
+     Task mode:  generate → code review × 2 → compliance review → ship | reject
+     Goal mode:  CEO planner (decompose) → per-task pipeline → goal verdict
+                 (sequential tasks; later tasks see earlier deliverables in context)
+
+   ${C.bold}Auth${C.reset}
+     export ANTHROPIC_API_KEY=sk-ant-...    (required)
+     export CLAUDE_MODEL=claude-sonnet-4-20250514   (optional override)
+
+   ${C.bold}Compliance${C.reset} is non-overridable. A code-grade-A deliverable with a
+   compliance FAIL is rejected. Use --no-compliance only for trusted tasks.
+`);
+        process.exit(args.length === 0 ? 1 : 0);
+    }
+    const positional = args.find((a) => !a.startsWith('--')) || '';
+    const mandate = args.includes('--mandate');
+    // --swarm delegates the decomposed goal to the full orchestrator-core swarm.
+    const swarm = args.includes('--swarm');
+    // --mandate is goal-shaped: it decomposes, estimates a cost envelope, and signs
+    // a PACT mandate before executing. It therefore implies goal mode. --swarm too.
+    const isGoal = args.includes('--goal') || mandate || swarm;
+    const outIdx = args.indexOf('--out');
+    const outDirIdx = args.indexOf('--out-dir');
+    const profileIdx = args.indexOf('--profile');
+    const compliance = !args.includes('--no-compliance');
+    const sid = Math.floor(Date.now() / 1000).toString(36).slice(-4);
+    let profile;
+    if (profileIdx >= 0) {
+        const p = args[profileIdx + 1];
+        if (!p || !VALID_PROFILES.includes(p)) {
+            out(`\n   ${C.red}error:${C.reset} --profile must be one of: ${VALID_PROFILES.join(', ')}\n`);
+            process.exit(2);
+        }
+        profile = p;
+    }
+    return {
+        mode: isGoal ? 'goal' : 'task',
+        input: positional,
+        outPath: outIdx >= 0 ? args[outIdx + 1] : `/tmp/kognai-build-${Date.now()}.ts`,
+        outDir: outDirIdx >= 0 ? args[outDirIdx + 1] : (workspace?.deliverable_root ?? `/tmp/kognai-goal-${sid}`),
+        compliance,
+        profile,
+        mandate,
+        sovereign: args.includes('--sovereign'),
+        swarm,
+    };
+}
+/** Profile guidance appended to coder + reviewer system prompts when profile is set.
+ *  Per TICKET-135: 'two engineers given the same task produce structurally different
+ *  outputs depending on what they silently optimize for.' Making it explicit prevents
+ *  the silent-axis drift. */
+function profileGuidance(profile, role) {
+    if (!profile)
+        return '';
+    const axisDesc = {
+        'security': 'confidentiality, integrity, authorization, threat resistance — favor secure defaults, fail closed, audit trails',
+        'reliability': 'availability, fault tolerance, recoverability — favor retries, circuit breakers, SLO-friendly error handling',
+        'performance': 'latency, throughput, resource efficiency — favor minimal allocations, batched IO, profile-aware data structures',
+        'maintainability': 'modularity, modifiability, testability, readability — favor clear naming, small units, explicit contracts',
+        'compatibility': 'interoperability, coexistence with other systems — favor standard formats, version-tolerant interfaces',
+        'usability': 'UX quality, accessibility, learnability — favor clear errors, sensible defaults, discoverable interfaces',
+        'portability': 'adaptability, installability, replaceability — favor pure functions, dep injection, no platform-specific calls',
+        'compliance': 'regulatory adherence (GDPR, HIPAA, jurisdictional) — favor consent gates, data minimization, audit-friendly output',
+        'cost-efficiency': 'infrastructure cost, operational cost, TCO — favor frugal designs, cache hits, avoid heavyweight services',
+        'time-to-market': 'delivery speed — favor pragmatic over perfect, well-known patterns, minimal viable shape',
+        'sovereignty': 'self-hosted / local / BYO-vault deployment over hosted services — favor local-first, no vendor lock-in, portable data formats',
+    };
+    const desc = axisDesc[profile] || profile;
+    if (role === 'coder') {
+        return `\n\nOPTIMIZATION PROFILE: this task is optimized for ${profile} (${desc}). When tradeoffs arise, favor this axis. Do not sacrifice it for stylistic gain.`;
+    }
+    return `\n\nOPTIMIZATION PROFILE: this deliverable was decomposed under '${profile}' (${desc}). Grade it against THIS axis — do not penalize for not optimizing other axes. A 'speed-first' deliverable that is verbose but fast should rate well; a 'maintainability-first' deliverable that is slower but cleaner should also rate well. Match your lens to the declared profile.`;
+}
+// ─── Model gateway (TICKET-233 Phase 1) ──────────────────────────────────────
+// Every model call routes through @kognai/orchestrator-core's registered
+// ModelRouter (see makeBuildRouter). CODER/REVIEWER models are now hints mapped
+// to engine complexity tiers; the router decides cloud (BYO key) vs local ($0).
+const CODER_MODEL = process.env.CLAUDE_MODEL || 'claude-sonnet-4-6';
+const REVIEWER_MODEL = process.env.CLAUDE_MODEL || 'claude-sonnet-4-6';
+function modelToComplexity(model) {
+    if (/opus/i.test(model))
+        return 'apex';
+    if (/haiku/i.test(model))
+        return 'nano';
+    return 'power'; // sonnet / default
+}
+async function callClaude(systemPrompt, userPrompt, maxTokens, model) {
+    const t0 = Date.now();
+    const r = await (0, orchestrator_core_1.getModelRouter)().callLLM(userPrompt, {
+        systemPrompt,
+        complexity: modelToComplexity(model),
+        maxTokens,
+        agentId: 'kognai-build',
+        taskType: 'build',
+    });
+    return { text: r.content, model: r.model, cost: r.cost_usd, ms: Date.now() - t0 };
+}
+async function generate(task, outPath, profile) {
+    const sys = `You are a Kognai coder agent. Output ONLY the file content for the deliverable — no commentary, no fences, no preamble. Production-quality, all imports, error handling. Target language inferred from file extension: ${outPath.split('.').pop() || 'ts'}.${profileGuidance(profile, 'coder')}`;
+    const r = await callClaude(sys, `Task: ${task}\nDeliverable file: ${outPath}\nOutput the complete file content now:`, 4096, CODER_MODEL);
+    const stripped = r.text.replace(/^```[\w]*\n/, '').replace(/\n```\s*$/, '').trim();
+    return { content: stripped, model: r.model, cost: r.cost, ms: r.ms };
+}
+// ─── Robust JSON extraction ──────────────────────────────────────────────────
+function safeParseJSON(raw) {
+    let s = raw.replace(/<think>[\s\S]*?<\/think>/g, '').trim();
+    s = s.replace(/^```(?:json)?\s*/i, '').replace(/```\s*$/, '').trim();
+    const m = s.match(/\{[\s\S]*\}/);
+    if (!m)
+        return null;
+    let candidate = m[0];
+    try {
+        return JSON.parse(candidate);
+    }
+    catch { /* fall through */ }
+    candidate = candidate.replace(/([{,]\s*)([A-Za-z_][A-Za-z0-9_]*)\s*:/g, '$1"$2":');
+    candidate = candidate.replace(/,(\s*[}\]])/g, '$1');
+    try {
+        return JSON.parse(candidate);
+    }
+    catch {
+        return null;
+    }
+}
+async function reviewCode(label, task, code, profile) {
+    const sys = `You are a Kognai code-quality reviewer. Grade the deliverable A–F on: correctness vs the task, completeness (no TODOs/stubs), code quality, error handling.
+
+CRITICAL OUTPUT RULES:
+- Reply with VALID JSON only. No markdown fences, no <think> blocks, no commentary.
+- Use double-quoted keys: {"grade":"A","summary":"..."}, NOT {grade:"A",summary:"..."}.
+- Grade must be exactly one of: A, B, C, D, F.
+- Summary should be a complete thought (1-3 sentences). No mid-sentence truncation.
+
+Example: {"grade":"B","summary":"Correct implementation with proper types and error handling. Minor: redundant regex check after early-return, and no upper-bound length validation."}${profileGuidance(profile, 'reviewer')}`;
+    const r = await callClaude(sys, `Task: ${task}\n\n--- DELIVERABLE ---\n${code}\n--- END ---\n\nGrade now (JSON only):`, 512, REVIEWER_MODEL);
+    const parsed = safeParseJSON(r.text);
+    if (!parsed || !parsed.grade) {
+        return { label, grade: 'F', summary: `unparseable reply (raw: ${r.text.slice(0, 200).replace(/\n/g, ' ')}…)`, model: r.model, cost: r.cost, ms: r.ms };
+    }
+    const grade = ['A', 'B', 'C', 'D', 'F'].includes(parsed.grade) ? parsed.grade : 'F';
+    return { label, grade, summary: String(parsed.summary || '(no summary)'), model: r.model, cost: r.cost, ms: r.ms };
+}
+async function reviewCompliance(task, code) {
+    const sys = `You are the Kognai COMPLIANCE reviewer — the third review pass that distinguishes Kognai's orchestrator from a thin LLM wrapper. Check the deliverable against:
+
+  CONSTITUTIONAL (the 3 Laws, non-overridable):
+    I.  Never Harm — no code that damages clients, agents, or counterparties.
+    II. Earn Existence — no fake/deceptive functionality, no fabricated metrics, no hidden surveillance.
+    III. Transparency to Creator — no obfuscation, no embedded credentials, no telemetry without disclosure.
+
+  LEGAL / REGULATORY:
+    - No GDPR-violating PII handling without consent gates.
+    - No tax-evasion shortcuts.
+    - No license-incompatible code lift from copyleft sources.
+
+  SECURITY (auto-fail):
+    - Hard-coded secrets, API keys, private keys, wallet seeds.
+    - SQL injection, command injection, path traversal vulnerabilities.
+    - Disabled TLS, certificate validation bypass.
+    - eval() / unrestricted dynamic execution on untrusted input.
+
+CRITICAL OUTPUT RULES:
+- Reply with VALID JSON only. No markdown fences, no <think> blocks, no commentary.
+- Use double-quoted keys: {"pass":true,"reasons":["..."]}.
+- "pass" must be a JSON boolean.
+- "reasons" must be a JSON array of short, complete strings.
+
+Example PASS: {"pass":true,"reasons":["No secrets or credentials","No injection vectors","No PII handling or external calls"]}
+Example FAIL: {"pass":false,"reasons":["Hard-coded API key on line 12","Missing consent gate before PII fetch"]}
+
+PASS means SHIPPABLE under all 3 categories. FAIL on ANY violation — the supervisor cannot override.`;
+    const r = await callClaude(sys, `Task: ${task}\n\n--- DELIVERABLE ---\n${code}\n--- END ---\n\nCompliance verdict (JSON only):`, 1024, REVIEWER_MODEL);
+    const parsed = safeParseJSON(r.text);
+    if (!parsed || typeof parsed.pass !== 'boolean') {
+        return { pass: false, reasons: [`Unparseable reply — failing safe. Raw: ${r.text.slice(0, 200).replace(/\n/g, ' ')}…`], model: r.model, cost: r.cost, ms: r.ms };
+    }
+    return { pass: parsed.pass, reasons: Array.isArray(parsed.reasons) ? parsed.reasons.map(String) : [], model: r.model, cost: r.cost, ms: r.ms };
+}
+function gradeRank(g) { return { A: 5, B: 4, C: 3, D: 2, F: 1 }[g] ?? 0; }
+function gradeColor(g) { return gradeRank(g) >= 4 ? C.green : gradeRank(g) >= 3 ? C.yellow : C.red; }
+// ─── Presentation (canonical design language v1.0) ───────────────────────────
+function sessionId() { return Math.floor(Date.now() / 1000).toString(36).slice(-4); }
+function banner(compliance) {
+    const ts = new Date().toISOString().replace('T', ' ').slice(0, 19);
+    const sid = sessionId();
+    const mode = compliance ? 'triple-supervisor + compliance' : 'triple-supervisor (compliance OFF)';
+    const left = `${C.jade}●${C.reset}  ${C.bold}KOGNAI RUNTIME${C.reset} ${C.gray}·${C.reset} ${C.jade}${C.bold}ENGAGED${C.reset}`;
+    const right = `${C.gray}${ts}${C.reset}`;
+    const sub = `   ${C.gray}builder console · ${mode} · session #${sid}${C.reset}`;
+    const innerPad = W - visLen(left) - visLen(right) - 4;
+    out('');
+    out(`   ${C.jade}╔${'═'.repeat(W - 2)}╗${C.reset}`);
+    out(`   ${C.jade}║${C.reset}  ${left}${' '.repeat(Math.max(2, innerPad))}${right}  ${C.jade}║${C.reset}`);
+    out(`   ${C.jade}║${C.reset}${sub}${' '.repeat(Math.max(0, W - visLen(sub) - 2))}${C.jade}║${C.reset}`);
+    out(`   ${C.jade}╚${'═'.repeat(W - 2)}╝${C.reset}`);
+    // TICKET-207: workspace line below banner
+    if (workspace) {
+        out(`   ${C.jade}Workspace:${C.reset} ${workspace.kognai_dir}`);
+    }
+    else {
+        out(`   ${C.gray}Workspace: (none — deliverables to /tmp; create .kognai/config.yaml to bind)${C.reset}`);
+    }
+    out('');
+}
+function header(task, compliance) {
+    banner(compliance);
+    out(`   ${C.gray}╭─ Task ${'─'.repeat(W - 9)}╮${C.reset}`);
+    out(wrap(task, W - 4, `   ${C.gray}│${C.reset} `));
+    out(`   ${C.gray}╰${'─'.repeat(W - 2)}╯${C.reset}`);
+    out('');
+}
+function goalHeader(goal, compliance) {
+    banner(compliance);
+    out(`   ${C.gray}╭─ Goal ${'─'.repeat(W - 9)}╮${C.reset}`);
+    out(wrap(goal, W - 4, `   ${C.gray}│${C.reset} `));
+    out(`   ${C.gray}╰${'─'.repeat(W - 2)}╯${C.reset}`);
+    out('');
+}
+function section(label) {
+    out('');
+    out(`   ${C.bold}${C.jade}◇${C.reset} ${C.bold}${label}${C.reset}`);
+    out('');
+}
+function generationSummary(g) {
+    const lines = g.content.split('\n').length;
+    out(`     ${C.gray}Routed to:${C.reset}  ${C.bold}${g.model}${C.reset} ${C.gray}(${g.model.startsWith('claude') ? 'cloud' : 'local · $0'})${C.reset}`);
+    out(`     ${C.gray}Produced:${C.reset}   ${g.content.length} chars · ${lines} lines · ${ms(g.ms)} · ${C.gray}$${g.cost.toFixed(4)}${C.reset}`);
+}
+function codeReviewBlock(r) {
+    const colour = gradeColor(r.grade);
+    out(`     ${C.bold}▸ ${r.label}${C.reset}${' '.repeat(Math.max(2, 28 - r.label.length))}${C.gray}Grade:${C.reset} ${colour}${C.bold}${r.grade}${C.reset}   ${C.gray}${r.model} · ${ms(r.ms)}${C.reset}`);
+    out(wrap(r.summary, W - 8, `       `));
+    out('');
+}
+function complianceReviewBlock(r) {
+    const colour = r.pass ? C.green : C.red;
+    const verdict = r.pass ? 'PASS' : 'FAIL';
+    out(`     ${C.bold}▸ Compliance review${C.reset}${' '.repeat(28 - 'Compliance review'.length)}${C.gray}Result:${C.reset} ${colour}${C.bold}${verdict}${C.reset}   ${C.gray}${r.model} · ${ms(r.ms)}${C.reset}`);
+    for (const reason of r.reasons) {
+        const mark = r.pass ? `${C.green}✓${C.reset}` : `${C.red}✗${C.reset}`;
+        out(`       ${mark} ${reason}`);
+    }
+    out('');
+}
+function verdictBlock(sup1, sup2, sup3, ship) {
+    const codeOk = gradeRank(sup1.grade) >= 3 || gradeRank(sup2.grade) >= 3;
+    const verdict = ship ? `${C.green}${C.bold}SHIPPABLE${C.reset}` : `${C.red}${C.bold}REJECTED${C.reset}`;
+    out(`   ${C.bold}${C.jade}◇${C.reset} ${C.bold}Verdict${C.reset}: ${verdict}`);
+    out('');
+    out(`     ${C.gray}Code quality:${C.reset}  ${codeOk ? C.green + 'PASS' : C.red + 'FAIL'}${C.reset}  ${C.gray}(${sup1.label} ${sup1.grade}, ${sup2.label} ${sup2.grade} — threshold C)${C.reset}`);
+    out(`     ${C.gray}Compliance:${C.reset}    ${sup3.pass ? C.green + 'PASS' : C.red + 'FAIL'}${C.reset}  ${C.gray}(${sup3.reasons.length} ${sup3.reasons.length === 1 ? 'finding' : 'findings'})${C.reset}`);
+}
+function deliverableBlock(content, outPath, ship) {
+    const lines = content.split('\n');
+    if (ship) {
+        out(`     ${C.gray}Path:${C.reset}   ${C.bold}${outPath}${C.reset}`);
+        out(`     ${C.gray}Size:${C.reset}   ${content.length} chars · ${lines.length} lines`);
+        out('');
+        out(`     ${C.gray}── preview ${'─'.repeat(W - 14)}${C.reset}`);
+        for (const l of lines.slice(0, 15))
+            out(`     ${C.dim}${l}${C.reset}`);
+        if (lines.length > 15)
+            out(`     ${C.gray}…  (${lines.length - 15} more lines — open the file at the path above)${C.reset}`);
+        out(`     ${C.gray}${'─'.repeat(W - 4)}${C.reset}`);
+    }
+    else {
+        out(`     ${C.red}Deliverable was NOT written.${C.reset}`);
+        out(`     ${C.gray}Compliance failures are non-overridable by the supervisor; fix the${C.reset}`);
+        out(`     ${C.gray}cited issues and resubmit, or pass --no-compliance for trusted tasks.${C.reset}`);
+    }
+}
+function footer(elapsedMs, totalCost, callCount, outPath, ship) {
+    out('');
+    out(`   ${C.gray}Total: ${ms(elapsedMs)} · ${callCount} model calls · $${totalCost.toFixed(4)}${C.reset}`);
+    if (ship) {
+        out('');
+        out(`   ${C.gray}Next:${C.reset}`);
+        out(`     ${C.gray}cat${C.reset} ${outPath}${C.gray}                # see the full file${C.reset}`);
+        out(`     ${C.gray}# or rerun with${C.reset} ${C.bold}--out ${C.reset}${C.gray}your/project/file.ts to write into your repo${C.reset}`);
+    }
+    out('');
+}
+async function decompose(goal, outDir) {
+    // TICKET-207: workspace knowledge + memory prepended to planner system prompt
+    let prefix = '';
+    if (workspace) {
+        try {
+            const k = (0, knowledge_1.loadKnowledge)(workspace);
+            const m = (0, memory_1.loadMemory)(workspace);
+            prefix = (0, knowledge_1.renderKnowledgePrefix)(k) + (0, memory_1.renderMemoryPrefix)(m);
+            if (k.files_read.length || m.files_read.length) {
+                out(`     ${C.gray}Workspace context: ${k.files_read.length} knowledge + ${m.files_read.length} memory file(s) loaded${C.reset}`);
+            }
+        }
+        catch (e) {
+            out(`     ${C.gray}Workspace context: skipped (${(e?.message || String(e)).slice(0, 80)})${C.reset}`);
+        }
+    }
+    const sys = `${prefix}You are the Kognai CEO planner. You decompose a high-level builder goal into 1-5 atomic tasks that a coder agent can execute one-by-one. Each task ships ONE file.
+
+CRITICAL OUTPUT RULES:
+- Reply with VALID JSON only. No fences, no commentary.
+- Use double-quoted keys.
+- Shape: {"rationale":"<1-2 sentences why this decomposition>","tasks":[{"file":"<relative path>","description":"<concrete task>"}, ...]}
+- Max 5 tasks. Order matters: later tasks may depend on earlier ones (e.g. types.ts before client.ts).
+- File paths are relative; the caller writes them into a base directory.
+- Each description is concrete enough that a coder agent can satisfy it without re-asking what the goal was.
+
+Example for goal "TypeScript SDK for TODO REST API":
+{"rationale":"Standard SDK shape: types first, then a client that consumes them, then a public entry point.","tasks":[{"file":"types.ts","description":"Define TypeScript types for Todo (id, title, done) and a TodoInput type for create operations"},{"file":"client.ts","description":"Implement TodoClient class with list/get/create/update/delete methods using fetch, backed by types from ./types"},{"file":"index.ts","description":"Public entry point re-exporting TodoClient and types"}]}`;
+    const r = await callClaude(sys, `Goal: ${goal}\nBase directory: ${outDir}\n\nDecompose now (JSON only):`, 2048, REVIEWER_MODEL);
+    const parsed = safeParseJSON(r.text);
+    if (!parsed || !Array.isArray(parsed.tasks) || parsed.tasks.length === 0) {
+        throw new Error(`planner returned unparseable plan. Raw: ${r.text.slice(0, 300)}`);
+    }
+    const tasks = parsed.tasks.slice(0, 5).map((t) => ({
+        file: String(t.file || 'untitled.ts'),
+        description: String(t.description || '(no description)'),
+    }));
+    return { tasks, rationale: String(parsed.rationale || ''), model: r.model, cost: r.cost, ms: r.ms };
+}
+function planningBlock(plan, outDir) {
+    out(`     ${C.gray}Routed to:${C.reset}  ${C.bold}${plan.model}${C.reset} ${C.gray}(planner)${C.reset}`);
+    out(`     ${C.gray}Decomposed:${C.reset} ${plan.tasks.length} task${plan.tasks.length === 1 ? '' : 's'} · ${ms(plan.ms)} · ${C.gray}$${plan.cost.toFixed(4)}${C.reset}`);
+    out('');
+    if (plan.rationale) {
+        out(wrap(`${C.gray}Rationale:${C.reset} ${plan.rationale}`, W - 6, '     '));
+        out('');
+    }
+    out(`     ${C.gray}Output dir:${C.reset} ${C.bold}${outDir}${C.reset}`);
+    out('');
+    for (let i = 0; i < plan.tasks.length; i++) {
+        const t = plan.tasks[i];
+        const num = `${i + 1}.`;
+        out(`     ${C.bold}${C.jade}${num}${C.reset} ${C.bold}${t.file}${C.reset}`);
+        out(wrap(t.description, W - 9, `        ${C.gray}`).replace(/\x1b\[0m/g, C.reset) + C.reset);
+        out('');
+    }
+}
+function taskHeader(idx, total, file) {
+    out('');
+    out(`   ${C.bold}${C.jade}◇${C.reset} ${C.bold}Task ${idx}/${total}${C.reset} ${C.gray}—${C.reset} ${C.bold}${file}${C.reset}`);
+    out('');
+}
+function goalVerdictBlock(shipped, total, outDir, deliverables) {
+    const allShipped = shipped === total;
+    const verdict = allShipped
+        ? `${C.green}${C.bold}GOAL ACHIEVED${C.reset}`
+        : shipped > 0
+            ? `${C.yellow}${C.bold}PARTIAL (${shipped}/${total})${C.reset}`
+            : `${C.red}${C.bold}GOAL FAILED${C.reset}`;
+    out(`   ${C.bold}${C.jade}◇${C.reset} ${C.bold}Goal verdict${C.reset}: ${verdict}`);
+    out('');
+    out(`     ${C.gray}Tasks shipped:${C.reset}  ${shipped} / ${total}`);
+    out(`     ${C.gray}Output dir:${C.reset}     ${C.bold}${outDir}${C.reset}`);
+    if (deliverables.length > 0) {
+        out('');
+        out(`     ${C.gray}Deliverables:${C.reset}`);
+        for (const d of deliverables)
+            out(`       ${C.green}✓${C.reset} ${d}`);
+    }
+}
+// ─── Mandate flow (TICKET-202 PACT onboarding) ───────────────────────────────
+// Between decomposition and execution: pick a template, preview capabilities,
+// estimate a heuristic cost envelope, and sign a local PACT mandate. The signed
+// mandate IS the autonomy envelope the swarm then runs within. Phase-1 core:
+// non-interactive (signs on the founder's behalf); the interactive sign/cancel/edit
+// prompt and sprint-runner envelope enforcement are the next slice.
+function slugifyFile(file) {
+    return file.replace(/[^a-zA-Z0-9]+/g, '-').replace(/^-+|-+$/g, '').toLowerCase() || 'task';
+}
+// Build (but do NOT sign) the recommended mandate from the plan. Splitting build
+// from sign lets us preview it and let the founder confirm before it's signed.
+function prepareMandate(goal, plan, outDir, profile) {
+    // Template selection from the registry (confirmation-required posture per
+    // TICKET-140: take the top-ranked candidate). selectTemplates always returns a
+    // candidate when no profile filter excludes everything; fall back defensively.
+    const candidates = (0, registry_1.selectTemplates)(goal, undefined, 1);
+    const template = candidates[0]?.template ?? (0, registry_1.getTemplateById)('webapp-standard-default');
+    if (!template)
+        throw new Error('no template available for mandate selection');
+    // Bridge the goal-mode plan ({file, description}) to the cost-estimator's
+    // PlannedTask ({id, title, task_target}). Phase 1 routes every task cloud-code.
+    const costTasks = plan.tasks.map((t, i) => ({
+        id: `${i + 1}-${slugifyFile(t.file)}`,
+        title: t.description,
+        task_target: 'cloud-code',
+    }));
+    const envelope = (0, cost_estimator_1.estimateCost)(costTasks, template);
+    const profileObj = {
+        primary: profile || template.default_profile.primary,
+        secondary: template.default_profile.secondary,
+        hard_constraints: [],
+    };
+    const capabilities = {
+        skills: template.skills,
+        tools: template.tools,
+        agents: template.composition.roles.map((r) => r.role),
+    };
+    // Validate the template's declared capabilities against the skill-bank +
+    // tool-layer registries — surfaces drift between templates and the registries.
+    const missingSkills = (0, skill_bank_1.unknownSkillIds)(capabilities.skills);
+    const missingTools = (0, tool_layer_1.unknownToolIds)(capabilities.tools);
+    if (missingSkills.length)
+        out(`   ${C.yellow}⚠ unknown skills (not in skill-bank):${C.reset} ${missingSkills.join(', ')}`);
+    if (missingTools.length)
+        out(`   ${C.yellow}⚠ unknown tools (not in tool-layer):${C.reset} ${missingTools.join(', ')}`);
+    const success_criteria = [
+        `Ship all ${plan.tasks.length} planned deliverable(s) under triple-supervisor review`,
+        ...plan.tasks.slice(0, 8).map((t) => `${t.file}: ${t.description}`),
+    ];
+    const scope_boundaries = [
+        `Deliverables limited to ${outDir}`,
+        `Template ${template.id} · ${profileObj.primary} profile`,
+    ];
+    const unsigned = (0, mandate_1.buildMandate)({
+        objective: goal,
+        success_criteria,
+        scope_boundaries,
+        template_id: template.id,
+        profile: profileObj,
+        capabilities,
+        cost_envelope: envelope,
+        deadline: null,
+    });
+    return { unsigned, template };
+}
+function mandatePreviewBlock(u, template) {
+    section('Recommended Mandate');
+    const row = (k, v) => out(`     ${C.gray}${k}${C.reset}${' '.repeat(Math.max(2, 14 - k.length))}${v}`);
+    row('Template', `${C.bold}${template.name}${C.reset} ${C.gray}(${template.id})${C.reset}`);
+    row('Intent', template.intent.slice(0, 3).join(' / '));
+    row('Profile', `${C.bold}${u.profile.primary}${C.reset}${u.profile.secondary.length ? `${C.gray} + ${u.profile.secondary.join(' × ')}${C.reset}` : ''}`);
+    row('Skills', u.capabilities.skills.join(', ') || '—');
+    row('Tools', u.capabilities.tools.join(', ') || '—');
+    row('Agents', u.capabilities.agents.join(', ') || '—');
+    row('Cost', `~$${u.cost_envelope.estimated_usdc.toFixed(4)} USDC ${C.gray}(hard cap $${u.cost_envelope.max_usdc.toFixed(4)})${C.reset}`);
+    row('Deadline', u.deadline ?? 'none');
+    out('');
+    for (const sb of u.scope_boundaries)
+        out(`     ${C.gray}Scope:${C.reset} ${sb}`);
+    out('');
+}
+function mandateSignedLine(m) {
+    out(`   ${C.jade}◇${C.reset} ${C.bold}Mandate ${m.mandate_id.slice(0, 8)}…${C.reset} ${C.green}signed${C.reset} ${C.gray}(${m.signed_by}, HMAC)${C.reset} — swarm executing within envelope.`);
+    out(`     ${C.gray}Persisted:${C.reset} .swarm-state/mandates/${m.mandate_id}.json`);
+    out(`     ${C.gray}Revoke:${C.reset}    kognai /revoke ${m.mandate_id.slice(0, 8)}… ${C.gray}(halts at next task boundary)${C.reset}`);
+    out('');
+}
+// Interactive sign | cancel | edit gate (TICKET-202). Returns the signed mandate,
+// or null if the founder cancels. On a non-TTY stdin (piped / CI) it auto-signs so
+// scripted runs keep working. `edit` lets the founder set a deadline and add scope
+// boundaries, then re-previews.
+async function confirmAndSignMandate(u, template) {
+    if (!process.stdin.isTTY) {
+        out(`   ${C.gray}(non-interactive stdin — auto-signing on the founder's behalf)${C.reset}`);
+        const m = (0, mandate_1.signMandate)(u, 'founder');
+        (0, mandate_1.persistMandate)(m);
+        mandateSignedLine(m);
+        return m;
+    }
+    const rl = (0, node_readline_1.createInterface)({ input: process.stdin, output: process.stdout });
+    const ask = (q) => new Promise((res) => rl.question(q, (a) => res(a.trim())));
+    try {
+        for (let i = 0; i < 6; i++) {
+            const ans = (await ask(`   ${C.jade}◇${C.reset} ${C.bold}sign${C.reset} | ${C.bold}cancel${C.reset} | ${C.bold}edit${C.reset} ${C.gray}›${C.reset} `)).toLowerCase();
+            if (ans === 'sign' || ans === 's' || ans === '') {
+                const m = (0, mandate_1.signMandate)(u, 'founder');
+                (0, mandate_1.persistMandate)(m);
+                mandateSignedLine(m);
+                return m;
+            }
+            if (ans === 'cancel' || ans === 'c' || ans === 'n') {
+                out(`   ${C.yellow}Mandate cancelled — nothing signed, no tasks run.${C.reset}`);
+                out('');
+                return null;
+            }
+            if (ans === 'edit' || ans === 'e') {
+                const dl = await ask(`     ${C.gray}deadline (ISO 8601, or blank for none) ›${C.reset} `);
+                u.deadline = dl ? dl : null;
+                const sc = await ask(`     ${C.gray}add a scope boundary (blank to skip) ›${C.reset} `);
+                if (sc)
+                    u.scope_boundaries = [...u.scope_boundaries, sc];
+                out('');
+                mandatePreviewBlock(u, template);
+                continue;
+            }
+            out(`   ${C.yellow}please type ${C.bold}sign${C.reset}${C.yellow}, ${C.bold}cancel${C.reset}${C.yellow}, or ${C.bold}edit${C.reset}${C.yellow}.${C.reset}`);
+        }
+        out(`   ${C.yellow}too many attempts — cancelled.${C.reset}`);
+        return null;
+    }
+    finally {
+        rl.close();
+    }
+}
+async function runOneTask(taskDesc, outPath, compliance, profile) {
+    const t0 = Date.now();
+    let cost = 0;
+    let calls = 0;
+    section('Generation');
+    const gen = await generate(taskDesc, outPath, profile);
+    generationSummary(gen);
+    cost += gen.cost;
+    calls += 1;
+    section('Review');
+    const reviews = await Promise.all([
+        reviewCode('Code review (primary)', taskDesc, gen.content, profile),
+        reviewCode('Code review (second pass)', taskDesc, gen.content, profile),
+        compliance
+            ? reviewCompliance(taskDesc, gen.content)
+            : Promise.resolve({ pass: true, reasons: ['SKIPPED (--no-compliance)'], model: '—', cost: 0, ms: 0 }),
+    ]);
+    const sup1 = reviews[0];
+    const sup2 = reviews[1];
+    const sup3 = reviews[2];
+    cost += sup1.cost + sup2.cost + sup3.cost;
+    calls += compliance ? 3 : 2;
+    codeReviewBlock(sup1);
+    codeReviewBlock(sup2);
+    complianceReviewBlock(sup3);
+    const codeOk = gradeRank(sup1.grade) >= 3 || gradeRank(sup2.grade) >= 3;
+    const ship = codeOk && sup3.pass;
+    verdictBlock(sup1, sup2, sup3, ship);
+    out('');
+    if (ship) {
+        (0, node_fs_1.mkdirSync)((0, node_path_1.dirname)(outPath), { recursive: true });
+        (0, node_fs_1.writeFileSync)(outPath, gen.content);
+    }
+    section('Deliverable');
+    deliverableBlock(gen.content, outPath, ship);
+    // TICKET-233 Phase 1: KSL measurement — only when a .kognai workspace is bound
+    // (KOGNAI_ROOT set by boot-env), so plain CLI runs write nothing extra.
+    if (workspace) {
+        try {
+            orchestrator_core_1.ksl.tapAttempt({
+                sprint_id: KSL_RUN_ID,
+                task_id: (outPath.split('/').pop() || 'task').replace(/[^A-Za-z0-9._-]/g, '_'),
+                attempt: 1,
+                agent: 'kognai-build',
+                model: gen.model,
+                prompt: taskDesc,
+                reply: gen.content,
+                cost_usd: cost,
+                duration_ms: Date.now() - t0,
+                signal_strength: ship ? 'high' : 'low',
+            });
+        }
+        catch { /* KSL is best-effort — never block a deliverable */ }
+    }
+    return { ship, cost, calls };
+}
+// ─── Main ────────────────────────────────────────────────────────────────────
+(async () => {
+    const args = parseArgs();
+    // TICKET-233 Phase 1: register the engine-backed router. --sovereign → $0 local.
+    (0, orchestrator_core_1.setModelRouter)((0, router_1.makeBuildRouter)(args.sovereign));
+    const t0 = Date.now();
+    const startedAtISO = new Date(t0).toISOString();
+    if (args.mode === 'task') {
+        header(args.input, args.compliance);
+        if (args.profile)
+            out(`   ${C.gray}optimization profile:${C.reset} ${C.bold}${args.profile}${C.reset}\n`);
+        const r = await runOneTask(args.input, args.outPath, args.compliance, args.profile);
+        footer(Date.now() - t0, r.cost, r.calls, args.outPath, r.ship);
+        process.exit(r.ship ? 0 : 1);
+    }
+    // Goal mode: TICKET-135 hierarchy — planner decomposes goal → tasks → per-task pipeline → goal verdict
+    goalHeader(args.input, args.compliance);
+    if (args.profile)
+        out(`   ${C.gray}optimization profile:${C.reset} ${C.bold}${args.profile}${C.reset}${C.gray} (cascades to every task)${C.reset}\n`);
+    section('Planning');
+    const plan = await decompose(args.input, args.outDir);
+    planningBlock(plan, args.outDir);
+    let cost = plan.cost;
+    let calls = 1;
+    // TICKET-202: preview + sign a PACT mandate from the plan before executing. The
+    // mandate is the autonomy envelope (template + capabilities + cost ceiling + scope).
+    // Cancelling at the prompt aborts before any task runs.
+    if (args.mandate) {
+        const { unsigned, template } = prepareMandate(args.input, plan, args.outDir, args.profile);
+        mandatePreviewBlock(unsigned, template);
+        const signed = await confirmAndSignMandate(unsigned, template);
+        if (!signed) {
+            footer(Date.now() - t0, cost, calls, args.outDir, false);
+            process.exit(0);
+        }
+    }
+    // TICKET-233 Phase 2: --swarm delegates the decomposed plan to the FULL
+    // orchestrator-core swarm (CEO · CTO governance gate · dual-supervisor) instead
+    // of the in-process triple-supervisor. Honors --sovereign ($0 local) via the
+    // registered router. The engine renders its own canonical swarm UI.
+    if (args.swarm) {
+        out(`\n   ${C.gray}swarm mode — delegating to @kognai/orchestrator-core (CEO · CTO gate · dual-supervisor)${args.sovereign ? ' · sovereign $0' : ''}${C.reset}\n`);
+        const sw = await (0, swarm_1.runSwarm)(args.input, plan.tasks, args.outDir);
+        out(`\n   ${C.bold}Swarm deliverables:${C.reset} ${sw.deliverables.length}/${sw.total} → ${args.outDir}`);
+        for (const d of sw.deliverables)
+            out(`     ${C.green}✓${C.reset} ${d}`);
+        footer(Date.now() - t0, cost, calls, args.outDir, sw.deliverables.length > 0);
+        process.exit(sw.deliverables.length > 0 ? 0 : 1);
+    }
+    const shipped = [];
+    for (let i = 0; i < plan.tasks.length; i++) {
+        const t = plan.tasks[i];
+        const outPath = `${args.outDir}/${t.file}`;
+        taskHeader(i + 1, plan.tasks.length, t.file);
+        const r = await runOneTask(t.description, outPath, args.compliance, args.profile);
+        cost += r.cost;
+        calls += r.calls;
+        if (r.ship)
+            shipped.push(outPath);
+    }
+    out('');
+    goalVerdictBlock(shipped.length, plan.tasks.length, args.outDir, shipped);
+    footer(Date.now() - t0, cost, calls, args.outDir, shipped.length > 0);
+    // TICKET-207 #6: append a session summary to .kognai/memory/kognai/ after the
+    // goal verdict. Guarded by workspace presence + config opt-in. Never fatal —
+    // a memory-write failure must not fail an otherwise-successful build.
+    if (workspace && workspace.config.memory.append_session_summary) {
+        try {
+            const summaryPath = (0, memory_1.writeSessionSummary)(workspace, {
+                goal: args.input,
+                profile: args.profile,
+                tasks_shipped: shipped.length,
+                tasks_total: plan.tasks.length,
+                cost_usdc: cost,
+                files: shipped,
+                started_at: startedAtISO,
+                ended_at: new Date().toISOString(),
+            });
+            out(`   ${C.gray}Memory:${C.reset} appended session summary to ${summaryPath}`);
+            out('');
+        }
+        catch (e) {
+            out(`   ${C.gray}Memory: session summary skipped (${(e?.message || String(e)).slice(0, 80)})${C.reset}`);
+            out('');
+        }
+    }
+    process.exit(shipped.length === plan.tasks.length ? 0 : 1);
+})().catch((e) => {
+    out('');
+    out(`   ${C.red}${C.bold}error:${C.reset} ${e.message}`);
+    out('');
+    process.exit(2);
+});