@kal-elsam/kairo-runtime 0.16.0 → 0.18.0

package/src/global/intelligence/official-benchmark-snapshots.js

@@ -0,0 +1,162 @@
+// Manufacturer-published benchmark snapshots — deliberately NOT a live API
+// (OpenAI/Anthropic don't expose one; their comparison tables are static
+// blog posts). Hand-curated and versioned instead, refreshed only when a
+// vendor publishes a new one. This is the source that finally gives Codex
+// and Claude real cross-vendor evidence — Hugging Face's leaderboards have
+// zero coverage of either (verified separately; see
+// model-capability-registry-sources.js's HF comment), since neither is
+// hosted on the HF Hub.
+//
+// Hard rule, per explicit decision: manufacturer-reported is never treated
+// as independent. Every entry here is `verified: false` in the registry —
+// OpenAI grading its own model against a competitor's public score is real
+// data worth keeping, but it is not the same epistemic weight as an
+// independently-run, third-party eval. Provenance (source, published date,
+// exact benchmark version, and the vendor's own methodology caveat) is
+// kept alongside every number specifically so this distinction survives
+// into anything built on top of it.
+
+/**
+ * Each entry is one benchmark's real, cross-vendor comparison table as
+ * published by ONE vendor at ONE point in time. `caveat` is the vendor's
+ * own stated methodology note — never omitted, since it changes how much
+ * weight the number deserves (e.g. "safeguards can zero out a task").
+ * Values below were verified directly (Anthropic's page, fetched live) or
+ * cross-checked against multiple independent third-party sources (OpenAI's
+ * page blocks direct fetches; corroborated via Vellum, llm-stats, and
+ * Artificial Analysis's own coverage of the same launch) — not copied
+ * from a single unverified paste.
+ */
+export const OFFICIAL_BENCHMARK_SNAPSHOTS = [
+  {
+    source: "openai-official",
+    url: "https://openai.com/index/gpt-6-astra/",
+    published: "2026-09-03",
+    benchmark: "terminal-bench", benchmarkVersion: "4.0",
+    // Corrected from an earlier 57.7 (a transcription error introduced by
+    // paraphrasing a search summary instead of the source) after
+    // cross-checking multiple independent citations of OpenAI's own
+    // launch page. Other real numbers exist for other configs — Astra at
+    // "xhigh"/"max" reasoning effort, and Artificial Analysis's own
+    // independently-measured snapshot — but those are different real
+    // measurements, not this one; they belong in their own entries if
+    // ever added, never blended into this vendor's reported baseline.
+    caveat: "OpenAI's own reported results, run at maximum reasoning effort in an environment that may differ from production.",
+    scores: [
+      { adapterId: "codex", modelId: "gpt-6-astra", value: 57.9 },
+      { adapterId: "codex", modelId: "gpt-5.6-sol", value: 37.3 },
+      { adapterId: "claude", modelId: "claude-fable-5-1", value: 55.8 }
+    ]
+  },
+  {
+    source: "openai-official",
+    url: "https://openai.com/index/gpt-6-astra/",
+    published: "2026-09-03",
+    // Kept as "gpqa-diamond", deliberately distinct from AA's own "gpqa"
+    // metric: same underlying benchmark, but AA reports it as a 0-1
+    // fraction while this manufacturer table reports a 0-100 score —
+    // merging them under one key would let bestEvidence silently pick
+    // whichever is more recent and display it without a scale, which
+    // would misrepresent the other source's real number.
+    benchmark: "gpqa-diamond", benchmarkVersion: null,
+    caveat: "OpenAI's own reported results, run at maximum reasoning effort in an environment that may differ from production.",
+    scores: [
+      { adapterId: "codex", modelId: "gpt-6-astra", value: 96.0 },
+      { adapterId: "codex", modelId: "gpt-5.6-sol", value: 94.6 }
+    ]
+  },
+  {
+    source: "anthropic-official",
+    url: "https://www.anthropic.com/claude-fable-and-mythos-5-1",
+    published: "2026-09-03",
+    benchmark: "terminal-bench", benchmarkVersion: "4.0",
+    caveat: "Fable 5.1 was evaluated with its production safeguards enabled; on tasks where safeguards intervened, it scored zero, which can understate its real capability relative to models evaluated without that constraint.",
+    scores: [
+      { adapterId: "claude", modelId: "claude-fable-5-1", value: 55.8 },
+      { adapterId: "claude", modelId: "claude-opus-5", value: 52.3 },
+      { adapterId: "codex", modelId: "gpt-5.6-sol", value: 37.3 }
+    ]
+  },
+  {
+    source: "anthropic-official",
+    url: "https://www.anthropic.com/claude-fable-and-mythos-5-1",
+    published: "2026-09-03",
+    benchmark: "terminal-bench-science", benchmarkVersion: "0.1",
+    caveat: "Fable 5.1 was evaluated with its production safeguards enabled; on tasks where safeguards intervened, it scored zero.",
+    scores: [
+      { adapterId: "claude", modelId: "claude-fable-5-1", value: 52.6 },
+      { adapterId: "claude", modelId: "claude-opus-5", value: 29.0 },
+      { adapterId: "codex", modelId: "gpt-5.6-sol", value: 22.4 }
+    ]
+  },
+  {
+    source: "anthropic-official",
+    url: "https://www.anthropic.com/claude-fable-and-mythos-5-1",
+    published: "2026-09-03",
+    benchmark: "cursorbench", benchmarkVersion: "3.2.0",
+    caveat: "Anthropic's own reported results; real statistical variance applies, not stated per-model on this page.",
+    scores: [
+      { adapterId: "claude", modelId: "claude-fable-5-1", value: 73.4 },
+      { adapterId: "claude", modelId: "claude-opus-5", value: 70.0 },
+      { adapterId: "codex", modelId: "gpt-5.6-sol", value: 67.2 }
+    ]
+  }
+];
+
+const DATE_PATTERN = /^\d{4}-\d{2}-\d{2}$/;
+
+/**
+ * Structural integrity check for hand-curated snapshot data — this can't
+ * verify a number is *correct* against the live source (nothing here can
+ * re-fetch OpenAI's blocked page), but it can catch the failure modes that
+ * actually happened while authoring this file: a missing citation, a
+ * malformed date, an unreferenced adapter/model, or an accidental exact
+ * duplicate row within the same vendor snapshot. Throws on the first
+ * violation — fail loud, never ingest a malformed entry silently.
+ * @param {Array<object>} snapshots
+ */
+export function validateSnapshotIntegrity(snapshots) {
+  const seen = new Set();
+  snapshots.forEach((snapshot, index) => {
+    const where = `snapshot[${index}] (${snapshot.source ?? "?"}/${snapshot.benchmark ?? "?"})`;
+    if (!snapshot.source) throw new Error(`${where}: missing source`);
+    if (!/^https:\/\//.test(snapshot.url ?? "")) throw new Error(`${where}: url must be a real https link, got ${snapshot.url}`);
+    if (!DATE_PATTERN.test(snapshot.published ?? "")) throw new Error(`${where}: published must be an ISO date (YYYY-MM-DD), got ${snapshot.published}`);
+    if (!snapshot.benchmark) throw new Error(`${where}: missing benchmark`);
+    if (!snapshot.caveat) throw new Error(`${where}: missing the vendor's own methodology caveat`);
+    if (!Array.isArray(snapshot.scores) || !snapshot.scores.length) throw new Error(`${where}: scores must be a non-empty array`);
+    for (const score of snapshot.scores) {
+      if (!score.adapterId || !score.modelId) throw new Error(`${where}: every score needs adapterId and modelId, got ${JSON.stringify(score)}`);
+      if (score.value != null && !Number.isFinite(score.value)) throw new Error(`${where}: score.value must be a finite number or null, got ${score.value}`);
+      const key = `${snapshot.source}|${snapshot.benchmark}|${snapshot.benchmarkVersion}|${score.adapterId}|${score.modelId}`;
+      if (seen.has(key)) throw new Error(`${where}: duplicate row for ${score.adapterId}/${score.modelId} — same vendor reporting the same benchmark/model twice is almost certainly a copy-paste mistake`);
+      seen.add(key);
+    }
+  });
+}
+
+/**
+ * Registers every model named in a snapshot and records its real reported
+ * score as evidence — always `verified: false` (manufacturer-reported is
+ * never independent, regardless of which vendor published it), with the
+ * vendor's own caveat preserved as `modelConfig` so it isn't lost.
+ * Validates snapshot integrity first (see validateSnapshotIntegrity) —
+ * never ingests a structurally malformed entry.
+ * @param {ReturnType<import("./model-capability-registry.js").createCapabilityRegistry>} registry
+ * @param {Array<object>} [snapshots] - defaults to OFFICIAL_BENCHMARK_SNAPSHOTS
+ */
+export function ingestOfficialSnapshotEvidence(registry, snapshots = OFFICIAL_BENCHMARK_SNAPSHOTS) {
+  validateSnapshotIntegrity(snapshots);
+  for (const snapshot of snapshots) {
+    for (const { adapterId, modelId, value } of snapshot.scores) {
+      if (value == null) continue;
+      const id = registry.registerIdentity(adapterId, modelId);
+      registry.addEvidence(id, {
+        metric: snapshot.benchmark, value, source: snapshot.source,
+        benchmarkVersion: snapshot.benchmarkVersion, modelConfig: snapshot.caveat,
+        date: snapshot.published, verified: false
+      });
+    }
+  }
+  return registry;
+}

package/src/global/intelligence/quick-ask.js

@@ -0,0 +1,149 @@
+import { spawn as defaultSpawn } from "node:child_process";
+import { mkdtemp, readFile, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { buildClaudeExecutionEnv } from "../runtime/execution-adapters/claude.js";
+
+// A real, read-only question -> answer call — no task, no plan, no
+// approval gate. This spends real provider usage (unlike the zero-cost
+// /usage local_command probes), which is expected: answering a real
+// question is real work. Fail-closed: any spawn/parse error yields
+// `status: "error"`, never a fabricated answer.
+const DEFAULT_TIMEOUT_MS = 30_000;
+
+// The child process never inherits Kairo's own real environment
+// unscrubbed — `cwd` alone (even a sanitized snapshot dir) says nothing
+// about what env vars a spawned process can read, and Kairo's own
+// process env can carry real secrets (provider API keys, tokens) that
+// have nothing to do with the question being asked. Mirrors
+// execution-adapters/claude.js's own SAFE_ENV_KEYS precedent — reused
+// directly for Claude; Codex gets an analogous, separately-scoped list
+// (CODEX_HOME instead of CLAUDE_CONFIG_DIR) rather than a shared
+// abstraction neither adapter asked for.
+const CODEX_SAFE_ENV_KEYS = Object.freeze([
+  "PATH", "HOME", "USER", "LOGNAME", "SHELL", "LANG", "LC_ALL", "LC_CTYPE",
+  "TMPDIR", "TERM", "CODEX_HOME", "HTTP_PROXY", "HTTPS_PROXY", "NO_PROXY",
+  "http_proxy", "https_proxy", "no_proxy", "NODE_EXTRA_CA_CERTS"
+]);
+function buildCodexExecutionEnv(sourceEnv = process.env) {
+  const env = Object.create(null);
+  for (const key of CODEX_SAFE_ENV_KEYS) {
+    if (sourceEnv[key] != null && sourceEnv[key] !== "") env[key] = sourceEnv[key];
+  }
+  return env;
+}
+
+function unknown(error) {
+  return { status: "error", answer: null, error: String(error) };
+}
+
+/** @param {{question:string, model:string|null, cwd:string, spawn:Function, timeoutMs:number, env:object}} args */
+function askClaude({ question, model, cwd, spawn, timeoutMs, env }) {
+  // --restricted: removes Bash/code-execution tools and WebFetch, ignores
+  // project/user settings, and confines the remaining file tools to cwd
+  // — the closest real equivalent to Codex's --sandbox read-only, since
+  // plain -p alone enforces no tool restriction at all.
+  // --strict-mcp-config: skip MCP servers too, so --restricted's own
+  // isolation isn't reopened by a configured MCP server with broader access.
+  const args = ["-p", question, "--output-format", "json", "--restricted", "--strict-mcp-config"];
+  if (model) args.push("--model", model);
+  return new Promise((resolve) => {
+    let child;
+    try {
+      child = spawn("claude", args, { cwd, env, stdio: ["ignore", "pipe", "pipe"] });
+    } catch (error) {
+      resolve(unknown(error?.message ?? error));
+      return;
+    }
+    let stdout = "";
+    let finished = false;
+    const timer = setTimeout(() => finish(unknown("claude -p timed out")), timeoutMs);
+    function finish(result) {
+      if (finished) return;
+      finished = true;
+      clearTimeout(timer);
+      try { child.kill?.(); } catch { /* best effort */ }
+      resolve(result);
+    }
+    child.stdout?.on("data", (chunk) => { stdout += chunk; });
+    child.once?.("error", (error) => finish(unknown(error?.message ?? error)));
+    child.once?.("close", () => {
+      let parsed;
+      try { parsed = JSON.parse(stdout); } catch { return finish(unknown("malformed JSON from claude -p")); }
+      if (typeof parsed?.result !== "string") return finish(unknown("no result text in claude -p response"));
+      finish({ status: "answered", answer: parsed.result, error: null });
+    });
+  });
+}
+
+/** @param {{question:string, model:string|null, cwd:string, spawn:Function, timeoutMs:number, env:object}} args */
+async function askCodex({ question, model, cwd, spawn, timeoutMs, env }) {
+  let outDir;
+  try {
+    outDir = await mkdtemp(join(tmpdir(), "kairo-ask-codex-"));
+  } catch (error) {
+    return unknown(error?.message ?? error);
+  }
+  const outFile = join(outDir, "answer.txt");
+  // read-only sandbox has nothing to approve, so --approve-for-me would
+  // conflict with --sandbox (the real CLI rejects combining them).
+  // --skip-git-repo-check: `cwd` is sometimes a sanitized snapshot
+  // directory (see conversation/sanitized-snapshot.js), which is
+  // deliberately not a real git repo (it excludes .git entirely) —
+  // without this, codex exec would refuse to run there at all. Harmless
+  // when cwd genuinely is a real git repo (the plain ASK-mode case).
+  const args = ["exec", "--sandbox", "read-only", "--skip-git-repo-check", "-o", outFile];
+  if (model) args.unshift("--model", model);
+  args.push(question);
+
+  try {
+    return await new Promise((resolve) => {
+      let child;
+      try {
+        child = spawn("codex", args, { cwd, env, stdio: ["ignore", "pipe", "pipe"] });
+      } catch (error) {
+        resolve(unknown(error?.message ?? error));
+        return;
+      }
+      let finished = false;
+      const timer = setTimeout(() => finish(unknown("codex exec timed out")), timeoutMs);
+      function finish(result) {
+        if (finished) return;
+        finished = true;
+        clearTimeout(timer);
+        try { child.kill?.(); } catch { /* best effort */ }
+        resolve(result);
+      }
+      child.once?.("error", (error) => finish(unknown(error?.message ?? error)));
+      child.once?.("close", async () => {
+        try {
+          const text = (await readFile(outFile, "utf8")).trim();
+          if (!text) return finish(unknown("codex exec produced no final message"));
+          finish({ status: "answered", answer: text, error: null });
+        } catch (error) {
+          finish(unknown(error?.message ?? error));
+        }
+      });
+    });
+  } finally {
+    await rm(outDir, { recursive: true, force: true }).catch(() => {});
+  }
+}
+
+/**
+ * Asks the given provider a real, read-only question and returns its real
+ * answer text. Supports Codex and Claude today; any other provider yields
+ * an honest "unsupported" result rather than a guess.
+ * @param {object} args
+ * @param {"codex"|"claude"} args.provider
+ * @param {string} args.question
+ * @param {string|null} [args.model]
+ * @param {string} args.cwd
+ */
+export async function askProvider({
+  provider, question, model = null, cwd, spawn = defaultSpawn, timeoutMs = DEFAULT_TIMEOUT_MS, sourceEnv = process.env
+}) {
+  if (provider === "claude") return askClaude({ question, model, cwd, spawn, timeoutMs, env: buildClaudeExecutionEnv(sourceEnv) });
+  if (provider === "codex") return askCodex({ question, model, cwd, spawn, timeoutMs, env: buildCodexExecutionEnv(sourceEnv) });
+  return { status: "unsupported", answer: null, error: `ASK is not supported for provider "${provider}" yet.` };
+}

package/src/global/intelligence/role-profiles.js

@@ -0,0 +1,251 @@
+// RoleProfile: the canonical definition of Kairo's six team-vocabulary
+// roles (Explorer / Architect / Builder / Debugger / Tester / Reviewer)
+// — what each role is FOR, what real model can do its work, what it's
+// allowed to do, what it must hand back, how risky its own mistakes are,
+// when it's "done", and when it should escalate to a stronger model.
+// This module is the source of truth; model-intelligence.js imports
+// ROLE_CAPABILITIES from here (and re-exports it, so existing external
+// callers keep working) rather than the other way around — a real
+// routing layer will need to import BOTH role-profiles.js (policy) and
+// capability-scoring.js (scoring) without ever routing through each
+// other, and role-profiles.js -> model-intelligence.js -> capability-
+// scoring.js would have made that a cycle the moment routing imported
+// role-profiles.js too.
+//
+// ROLE_CAPABILITIES answers "which real model can do this role's work";
+// the rest of RoleProfile answers "what does doing this role's work
+// actually mean, and under what constraints". A RoleProfile's own
+// `capabilities` field is a direct reference to ROLE_CAPABILITIES[role],
+// never a duplicate — the two stay in sync by construction, not by
+// remembering to update two places.
+//
+// Economy has no RoleProfile. Per the "Convertir la guía en un equipo
+// operativo real" plan, Economy stops being a 7th role competing for its
+// own slot and becomes an EXECUTION POLICY any of the six real roles can
+// run under (cheapest real model that still clears the role's own
+// requiredRoleFit floor, instead of the role's own leader/near-
+// equivalence pick) — see model-intelligence.js's own Economy handling,
+// still unchanged as of this module; wiring RoleProfile-aware routing to
+// actually apply that policy per-role is a later increment, not this one.
+
+// Each role's real relevant capabilities (see capability-scoring.js),
+// derived from the plan's per-role table. "Hard problem solving" folds
+// into reasoning (GPQA/HLE are themselves hard-reasoning benchmarks);
+// "scientific coding" folds into coding (SciCode is already one of
+// coding's real component benchmarks) rather than inventing a separate
+// capability neither BENCHMARK_IDENTITIES nor any real source measures
+// directly. Tester/Reviewer/Explorer rows were truncated in the source
+// plan — inferred from this codebase's own pre-existing role-definition
+// pattern (Tester: coding + terminal execution; Reviewer: independent
+// reasoning + coding review; Explorer: the same reasoning-only signal
+// Architect always had) rather than guessed from nothing.
+// required: a model MUST have real evidence for every one of these to
+// compete for the role at all — missing evidence on even one required
+// capability excludes it from the ranking entirely (see
+// model-intelligence.js's buildAiTeamRoleDefinitions's compute()).
+// required capabilities ALONE decide both the ranking order
+// (requiredRoleFit, i.e. RoleEvaluation.capabilityPercentile computed
+// only from `required`) and how close two real picks are (gapValueByRole,
+// computed the same way) — optional capabilities never dilute either
+// number. optional: real evidence, when present, is scored completely
+// separately (optionalEvaluationsByRole) and used ONLY as a tiebreak
+// among candidates already equally fit on required capabilities — it can
+// never move a model up in requiredRoleFit order, and its absence never
+// excludes a model. Before this split, an optional capability was folded
+// into the SAME median as required ones — so a generalist's real
+// requiredRoleFit gap on the capabilities that actually define the role
+// could be smoothed over by an unrelated optional signal. Whether this
+// alone changes a specific real pick (e.g. Muse Spark 1.3 on Architect)
+// still depends on the per-role near-equivalence band
+// (model-intelligence.js's ROLE_NEAR_EQUIVALENCE_BAND) — verify against
+// real data, never assume.
+//
+// softwareExecution is optional everywhere it appears (Builder, Debugger),
+// not required — verified against two independent real catalogs before
+// deciding this, not assumed: the full multi-provider catalog (Codex +
+// Claude + Cursor + OpenCode Go, 81 scored candidates) showed real
+// evidence for only 3 of them; crm's own real candidate pool (9 scored
+// candidates) showed only 2. Coverage is a fact about the CURRENT real
+// catalog, never a fixed constant — these specific numbers will already
+// be stale by the time this comment is read; re-measure via
+// capability-scoring.js's computeCapabilityPercentile against the real
+// scored pool in hand, never assume a ratio. Making softwareExecution
+// required at either measured ratio would have left Builder/Debugger with
+// only 2-3 real candidates system-wide, no matter how many other models
+// are genuinely capable — instructionFollowing is optional everywhere for
+// the same reason (never load-bearing enough for any role to gate on).
+export const ROLE_CAPABILITIES = {
+  Explorer: { required: ["reasoning"], optional: ["instructionFollowing"] },
+  Architect: { required: ["reasoning", "coding"], optional: ["instructionFollowing"] },
+  Builder: { required: ["coding", "terminalExecution"], optional: ["softwareExecution", "instructionFollowing"] },
+  Debugger: { required: ["reasoning", "coding", "terminalExecution"], optional: ["softwareExecution"] },
+  Tester: { required: ["coding", "terminalExecution"], optional: [] },
+  Reviewer: { required: ["reasoning", "coding"], optional: [] }
+};
+
+// Stable, machine-checkable vocabularies for a router to branch on — the
+// human-readable `allowedActions`/`escalationConditions` strings below
+// are for prompts and UI copy; a router must never parse or pattern-match
+// those sentences to decide anything, since wording can change for
+// clarity without meaning to change behavior. `allowedActionIds`/
+// `escalationSignalIds` are the actual decision surface: closed,
+// versioned sets a router (or a test) can validate membership against.
+// Every id used in ROLE_PROFILES below must come from one of these two
+// sets — see role-profiles.test.js's own membership check.
+export const ALLOWED_ACTION_IDS = [
+  "repo.read", "repo.search", "repo.inspect_history",
+  "plan.write", "repo.write", "build.run", "lint.run", "test.run", "test.write", "review.write"
+];
+export const ESCALATION_SIGNAL_IDS = [
+  "large_scope", "architectural_intent_required", "cross_subsystem", "high_reversal_cost",
+  "plan_invalidated", "security_sensitive", "root_cause_not_found", "high_uncertainty"
+];
+
+/**
+ * @typedef {object} RoleProfile
+ * @property {string} role
+ * @property {string} objective - what this role is trying to accomplish, in one sentence.
+ * @property {string} responsibility - the concrete scope of work this role owns.
+ * @property {{required: string[], optional: string[]}} capabilities - direct reference to ROLE_CAPABILITIES[role].
+ * @property {string[]} allowedActions - human-readable description of what this role may do — prompts/UI only, never evaluated mechanically. See `allowedActionIds` for the real decision surface.
+ * @property {string[]} allowedActionIds - stable ids from ALLOWED_ACTION_IDS; what a router actually checks.
+ * @property {string} deliverable - what this role must hand back when it finishes.
+ * @property {"low"|"medium"|"high"} riskLevel - how costly a mistake from this role is to the rest of the team; already a stable enum, safe for a router to branch on directly.
+ * @property {string} completionCriteria - the real, checkable condition that marks this role's work as done (human-readable; not yet machine-evaluable — see role-profiles.js's own module doc).
+ * @property {string[]} escalationConditions - human-readable description of when this role should escalate — prompts/UI only. See `escalationSignalIds` for the real decision surface.
+ * @property {string[]} escalationSignalIds - stable ids from ESCALATION_SIGNAL_IDS; what a router actually checks to decide whether to escalate.
+ * @property {{dependsOn: string[], independentOf: string[]}} dependencies - which other roles this one's output depends on, and which it must stay independent from.
+ */
+
+/**
+ * The six real RoleProfiles. Order matches ROLE_CAPABILITIES's own
+ * declaration order (Explorer, Architect, Builder, Debugger, Tester,
+ * Reviewer) — not alphabetical, not risk-ordered — so a reader who
+ * already knows one table can find the same role in the other without
+ * re-deriving the order.
+ * @type {Record<string, RoleProfile>}
+ */
+export const ROLE_PROFILES = {
+  Explorer: {
+    role: "Explorer",
+    objective: "Investigate a real question or area of the codebase and come back with real, checkable evidence — never a guess.",
+    responsibility: "Read-only reconnaissance: locate the relevant real files, trace how something actually works today, and summarize findings a later role (usually Architect) can act on.",
+    capabilities: ROLE_CAPABILITIES.Explorer,
+    allowedActions: ["read files", "search/grep the repository", "run read-only inspection commands (e.g. git log, git blame)"],
+    allowedActionIds: ["repo.read", "repo.search", "repo.inspect_history"],
+    deliverable: "A findings summary with real file:line references for every claim — no unverified assertion presented as fact.",
+    riskLevel: "low",
+    completionCriteria: "Every question the investigation was scoped to answer has a real, cited answer, or is explicitly listed as unresolved with why.",
+    escalationConditions: [
+      "the area under investigation is large enough that a shallow read risks missing a real contradiction elsewhere in the codebase",
+      "the question requires understanding real architectural intent, not just locating code"
+    ],
+    escalationSignalIds: ["large_scope", "architectural_intent_required"],
+    dependencies: { dependsOn: [], independentOf: ["Builder", "Reviewer"] }
+  },
+  Architect: {
+    role: "Architect",
+    objective: "Turn a real requirement (and, when available, Explorer's findings) into a concrete, buildable plan — decide the approach before any code changes.",
+    responsibility: "Design and sequence the real work: which files change, in what order, what the acceptance criteria are, and what tradeoffs were considered and rejected.",
+    capabilities: ROLE_CAPABILITIES.Architect,
+    allowedActions: ["read files", "search/grep the repository", "produce a written plan or design document"],
+    allowedActionIds: ["repo.read", "repo.search", "plan.write"],
+    deliverable: "A plan concrete enough for Builder to execute without re-deciding the approach — real file targets, real ordering, real acceptance criteria.",
+    riskLevel: "high",
+    completionCriteria: "The plan covers every real file the work will touch, states its acceptance criteria explicitly, and names the tradeoffs it chose between.",
+    escalationConditions: [
+      "the requirement touches multiple subsystems whose real interaction isn't already well understood",
+      "a wrong architectural decision here would be expensive to reverse once Builder has acted on it"
+    ],
+    escalationSignalIds: ["cross_subsystem", "high_reversal_cost"],
+    dependencies: { dependsOn: ["Explorer"], independentOf: [] }
+  },
+  Builder: {
+    role: "Builder",
+    objective: "Implement the real plan Architect produced — write, edit, or remove real code.",
+    responsibility: "Execute the approved plan faithfully: make the real file changes it calls for, following this codebase's own existing conventions rather than inventing new ones.",
+    capabilities: ROLE_CAPABILITIES.Builder,
+    allowedActions: ["read files", "write/edit files", "run build/lint commands to self-check"],
+    allowedActionIds: ["repo.read", "repo.write", "build.run", "lint.run"],
+    deliverable: "The real code change described by the plan, in a state ready for Tester/Reviewer — not a partial or half-finished implementation.",
+    riskLevel: "medium",
+    completionCriteria: "Every file target in the plan is actually changed, the change builds/lints cleanly, and no acceptance criterion from the plan is left unaddressed.",
+    escalationConditions: [
+      "the real implementation reveals the plan's approach doesn't actually work and needs Architect to reconsider it",
+      "the change touches a real security- or data-integrity-sensitive path"
+    ],
+    escalationSignalIds: ["plan_invalidated", "security_sensitive"],
+    dependencies: { dependsOn: ["Architect"], independentOf: [] }
+  },
+  Debugger: {
+    role: "Debugger",
+    objective: "Find the real root cause of a real failure and fix it — never patch the symptom without understanding why it happened.",
+    responsibility: "Reproduce the real failure, trace it to its real cause in the code, and make the minimal real change that actually fixes that cause.",
+    capabilities: ROLE_CAPABILITIES.Debugger,
+    allowedActions: ["read files", "write/edit files", "run tests and reproduction commands"],
+    // test.write, not just test.run: this role's own deliverable requires
+    // handing back a real regression test — per this project's own Zero
+    // Bugs Policy ("every bug fix requires a regression test that fails
+    // first, then passes with the fix"), the same actor that finds and
+    // fixes the real root cause writes that specific test, not a
+    // mandatory Debugger->Tester handoff for every fix. Debugger already
+    // has broad repo.write; this is a more specific, explicit grant of
+    // the same real capability, not an expansion of what it can touch.
+    allowedActionIds: ["repo.read", "repo.write", "test.write", "test.run"],
+    deliverable: "A fix with a real regression test that fails before the fix and passes after it, plus a stated root cause.",
+    riskLevel: "high",
+    completionCriteria: "The real failure no longer reproduces, a regression test proves it, and the stated root cause is the actual cause, not a plausible-sounding guess.",
+    escalationConditions: [
+      "the failure's real root cause isn't found after a reasonable real investigation — guessing at fixes past that point is worse than escalating",
+      "the failure is in a real security- or data-integrity-sensitive path"
+    ],
+    escalationSignalIds: ["root_cause_not_found", "security_sensitive"],
+    dependencies: { dependsOn: [], independentOf: ["Builder"] }
+  },
+  Tester: {
+    role: "Tester",
+    objective: "Verify the real behavior of a change, including its real edge cases — not just the happy path Builder already checked.",
+    responsibility: "Write and run real tests that would catch a real regression, deliberately probing edge cases and failure modes the implementation might have missed.",
+    capabilities: ROLE_CAPABILITIES.Tester,
+    allowedActions: ["read files", "write/edit test files", "run test commands"],
+    allowedActionIds: ["repo.read", "test.write", "test.run"],
+    deliverable: "A real, passing test suite covering the change's stated behavior and its real edge cases, with any gap found reported honestly.",
+    riskLevel: "medium",
+    completionCriteria: "The relevant real test command passes, and the edge cases specific to this change (not just a generic checklist) are actually covered.",
+    escalationConditions: [
+      "the edge cases under test require reasoning about a real, non-obvious interaction between subsystems"
+    ],
+    escalationSignalIds: ["cross_subsystem"],
+    dependencies: { dependsOn: ["Builder"], independentOf: [] }
+  },
+  Reviewer: {
+    role: "Reviewer",
+    objective: "Independently verify a real change is correct, safe, and consistent with this codebase's own conventions — the team's last real check before delivery.",
+    responsibility: "Read the real diff with an adversarial eye: look for correctness issues, security issues, and departures from established patterns Builder may have missed or rationalized.",
+    capabilities: ROLE_CAPABILITIES.Reviewer,
+    allowedActions: ["read files", "search/grep the repository", "produce a written review with real file:line findings"],
+    allowedActionIds: ["repo.read", "repo.search", "review.write"],
+    deliverable: "A review that either approves the change or lists real, concrete, file:line-anchored findings — never a vague 'looks fine' or an unfounded objection.",
+    riskLevel: "high",
+    completionCriteria: "Every real file the change touches has been read, and every finding raised is backed by a concrete file:line reference and a real failure scenario.",
+    escalationConditions: [
+      "the change touches a real security- or data-integrity-sensitive path",
+      "the reviewer's own uncertainty about correctness is high enough that a second, independent pass would materially change the outcome"
+    ],
+    escalationSignalIds: ["security_sensitive", "high_uncertainty"],
+    // Reviewer's independence from Builder isn't just a design principle
+    // here — model-intelligence.js's buildAiTeam enforces it mechanically
+    // (a Reviewer pick is barred from Builder's own chosen adapter
+    // whenever a real, near-equivalent or floor-clearing alternative
+    // exists — see passesConcentration's reviewerBuilderAdapter check).
+    dependencies: { dependsOn: ["Builder"], independentOf: ["Builder"] }
+  }
+};
+
+/**
+ * @param {string} role
+ * @returns {RoleProfile|null}
+ */
+export function getRoleProfile(role) {
+  return ROLE_PROFILES[role] ?? null;
+}

package/src/global/intelligence/skill-catalog.js

@@ -0,0 +1,67 @@
+import { existsSync } from "node:fs";
+import { readdir, readFile } from "node:fs/promises";
+import { join } from "node:path";
+
+// Reads the real project-local skill catalog (SKILL.md name + description
+// per skill) from the same directories context-compiler.js already scans
+// for skill *names* — this reads their real descriptions too, so the
+// execution router can match a task against what a skill actually claims
+// to do instead of guessing from bare folder names.
+const SKILL_ROOTS = ["docs/skills", ".cursor/skills", ".codex/skills", ".claude/skills"];
+
+/**
+ * Minimal frontmatter parser for SKILL.md's `---\nkey: value\n---` header —
+ * no YAML dependency, since skill frontmatter is flat key/value pairs (per
+ * the vercel-labs/skills format: required `name` and `description`).
+ * @param {string} text
+ */
+export function parseSkillFrontmatter(text) {
+  const match = /^---\r?\n([\s\S]*?)\r?\n---/.exec(text ?? "");
+  if (!match) return null;
+  const fields = {};
+  for (const line of match[1].split("\n")) {
+    const fieldMatch = /^([\w.-]+):\s*(.*)$/.exec(line.trim());
+    if (!fieldMatch) continue;
+    fields[fieldMatch[1]] = fieldMatch[2].trim().replace(/^["']|["']$/g, "");
+  }
+  return fields;
+}
+
+/**
+ * Reads every SKILL.md under this project's standard skill directories and
+ * returns their real `name`/`description`. Skills without both fields are
+ * skipped rather than guessed at.
+ * @param {string} root - project root
+ * @returns {Promise<Array<{name: string, description: string, path: string}>>}
+ */
+export async function readSkillCatalog(root) {
+  const skills = [];
+  const seenNames = new Set();
+  for (const skillRoot of SKILL_ROOTS) {
+    const dir = join(root, skillRoot);
+    if (!existsSync(dir)) continue;
+    let entries;
+    try {
+      entries = await readdir(dir, { withFileTypes: true });
+    } catch {
+      continue;
+    }
+    for (const entry of entries) {
+      if (!entry.isDirectory()) continue;
+      const skillMdPath = join(dir, entry.name, "SKILL.md");
+      if (!existsSync(skillMdPath)) continue;
+      let raw;
+      try {
+        raw = await readFile(skillMdPath, "utf8");
+      } catch {
+        continue;
+      }
+      const frontmatter = parseSkillFrontmatter(raw);
+      const name = frontmatter?.name ?? entry.name;
+      if (!frontmatter?.description || seenNames.has(name)) continue;
+      seenNames.add(name);
+      skills.push({ name, description: frontmatter.description, path: join(skillRoot, entry.name, "SKILL.md") });
+    }
+  }
+  return skills;
+}