sentinelayer-cli 0.8.0 → 0.8.1

package/src/ingest/ownership.js

@@ -0,0 +1,380 @@
+// File-to-persona ownership routing (#A10, spec §5.7).
+//
+// Personas are expensive: every persona runs an LLM call over whatever files
+// it thinks are in-scope. When 13 personas each scan the whole codebase the
+// token usage compounds. This module lets the orchestrator send each finding
+// (or each file) to only the persona that owns the code, which the spec
+// measures at >40% token savings on multi-persona runs.
+//
+// Two routing modes:
+//   1. Explicit — read `.sentinelayer/scaffold.yaml`, walk `ownership_rules`
+//      as a last-match-wins glob → persona list.
+//   2. Heuristic — no scaffold.yaml, fall back to keyword / extension rules
+//      derived from the 13-persona canon (security, backend, frontend,
+//      testing, code-quality, data-layer, documentation, reliability,
+//      release, observability, infrastructure, supply-chain, ai-governance).
+//
+// All exports are pure functions: no filesystem work except
+// `loadScaffoldConfig` which reads a single YAML file. The rest operate on
+// in-memory inputs so they compose cleanly with existing ingest callers.
+
+import fsp from "node:fs/promises";
+import path from "node:path";
+import process from "node:process";
+
+import YAML from "yaml";
+
+import { PERSONA_IDS } from "../review/persona-prompts.js";
+
+const DEFAULT_HEURISTIC_FALLBACK = "backend";
+const SCAFFOLD_RELATIVE_PATH = ".sentinelayer/scaffold.yaml";
+
+// --- Glob matching -------------------------------------------------------
+
+// Translate a shell-style glob into a RegExp. Supports `*` (single segment),
+// `**` (cross-segment), `?` (single char), and character classes passed
+// through. Not a full fnmatch — but enough for ownership routing and good
+// enough that a pattern like `lib/auth/**/*.{ts,tsx}` could be rewritten as
+// two entries: `lib/auth/**/*.ts` and `lib/auth/**/*.tsx`.
+function globToRegExp(glob) {
+  const raw = String(glob || "").trim();
+  if (!raw) {
+    throw new Error("ownership_rules.pattern is required.");
+  }
+  const normalized = raw.replace(/\\/g, "/").replace(/^\.\//, "");
+
+  let escaped = "";
+  for (let idx = 0; idx < normalized.length; idx += 1) {
+    const ch = normalized[idx];
+    const next = normalized[idx + 1];
+    if (ch === "*") {
+      if (next === "*") {
+        // `**/` matches zero or more path segments, `/** ` matches any tail
+        if (normalized[idx + 2] === "/") {
+          escaped += "(?:.*/)?";
+          idx += 2;
+        } else {
+          escaped += ".*";
+          idx += 1;
+        }
+      } else {
+        escaped += "[^/]*";
+      }
+      continue;
+    }
+    if (ch === "?") {
+      escaped += "[^/]";
+      continue;
+    }
+    if ("\\.+^$(){}|".includes(ch)) {
+      escaped += `\\${ch}`;
+      continue;
+    }
+    escaped += ch;
+  }
+  return new RegExp(`^${escaped}$`);
+}
+
+function matchGlob(pattern, filePath) {
+  return globToRegExp(pattern).test(filePath);
+}
+
+function normalizePathForMatch(filePath) {
+  return String(filePath || "")
+    .trim()
+    .replace(/\\/g, "/")
+    .replace(/^\.\//, "");
+}
+
+function normalizePersonaId(value) {
+  return String(value || "").trim().toLowerCase();
+}
+
+function assertKnownPersona(value) {
+  const normalized = normalizePersonaId(value);
+  if (!normalized) {
+    throw new Error("ownership_rules.persona is required.");
+  }
+  if (!PERSONA_IDS.includes(normalized)) {
+    throw new Error(
+      `ownership_rules.persona must be one of ${PERSONA_IDS.join(", ")} (got "${value}").`
+    );
+  }
+  return normalized;
+}
+
+// --- Scaffold YAML -------------------------------------------------------
+
+export function parseScaffoldYaml(raw) {
+  const text = String(raw || "");
+  const trimmed = text.trim();
+  if (!trimmed) {
+    return { ownershipRules: [] };
+  }
+  let parsed;
+  try {
+    parsed = YAML.parse(text);
+  } catch (err) {
+    throw new Error(`scaffold.yaml is not valid YAML: ${err.message}`);
+  }
+  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+    throw new Error("scaffold.yaml must be a mapping at the top level.");
+  }
+  const rawRules = parsed.ownership_rules;
+  if (rawRules === undefined || rawRules === null) {
+    return { ownershipRules: [] };
+  }
+  if (!Array.isArray(rawRules)) {
+    throw new Error("scaffold.yaml ownership_rules must be a list.");
+  }
+  const ownershipRules = rawRules.map((rule, idx) => {
+    if (!rule || typeof rule !== "object" || Array.isArray(rule)) {
+      throw new Error(`scaffold.yaml ownership_rules[${idx}] must be a mapping.`);
+    }
+    const pattern = String(rule.pattern || "").trim();
+    if (!pattern) {
+      throw new Error(`scaffold.yaml ownership_rules[${idx}].pattern is required.`);
+    }
+    const persona = assertKnownPersona(rule.persona);
+    return { pattern, persona };
+  });
+  return { ownershipRules };
+}
+
+export async function loadScaffoldConfig({
+  targetPath = process.cwd(),
+  relativePath = SCAFFOLD_RELATIVE_PATH,
+} = {}) {
+  const absolutePath = path.join(
+    path.resolve(String(targetPath || ".")),
+    String(relativePath || SCAFFOLD_RELATIVE_PATH)
+  );
+  try {
+    const raw = await fsp.readFile(absolutePath, "utf-8");
+    return { found: true, path: absolutePath, ...parseScaffoldYaml(raw) };
+  } catch (err) {
+    if (err && typeof err === "object" && err.code === "ENOENT") {
+      return { found: false, path: absolutePath, ownershipRules: [] };
+    }
+    throw err;
+  }
+}
+
+// --- Heuristic routing ---------------------------------------------------
+
+// The heuristic table is explicit rather than a big switch: earlier entries
+// are more specific, later entries are broader catch-alls. We iterate in
+// order and take the first match so "docs/api.md" sorts as documentation
+// rather than getting routed to backend by the ".md" extension catch-all.
+const HEURISTIC_RULES = [
+  {
+    persona: "testing",
+    match: (p) =>
+      /(^|\/)(tests?|__tests__|specs?)\//.test(p) ||
+      /\.(test|spec)\.(js|jsx|ts|tsx|mjs|cjs|py|rb|go|rs)$/.test(p),
+  },
+  {
+    persona: "documentation",
+    match: (p) =>
+      /(^|\/)docs?\//.test(p) ||
+      /(^|\/)(README|CHANGELOG|CONTRIBUTING|ADR)(\.md)?$/i.test(p) ||
+      /(^|\/)adr[-_]/i.test(p),
+  },
+  {
+    persona: "supply-chain",
+    match: (p) =>
+      /(^|\/)package(-lock)?\.json$/.test(p) ||
+      /(^|\/)yarn\.lock$/.test(p) ||
+      /(^|\/)pnpm-lock\.yaml$/.test(p) ||
+      /(^|\/)requirements([-.]\w+)?\.txt$/.test(p) ||
+      /(^|\/)pyproject\.toml$/.test(p) ||
+      /(^|\/)Pipfile(\.lock)?$/.test(p) ||
+      /(^|\/)Gemfile(\.lock)?$/.test(p) ||
+      /(^|\/)go\.(mod|sum)$/.test(p) ||
+      /(^|\/)cargo\.toml$/i.test(p) ||
+      /(^|\/)renovate\.json$/.test(p),
+  },
+  {
+    persona: "release",
+    match: (p) =>
+      /(^|\/)\.github\/workflows\//.test(p) ||
+      /(^|\/)release-please/.test(p) ||
+      /(^|\/)action\.yml$/.test(p) ||
+      /(^|\/)\.releaserc/.test(p) ||
+      /(^|\/)(scripts|bin)\/release/.test(p),
+  },
+  {
+    persona: "infrastructure",
+    match: (p) =>
+      /(^|\/)(infra|terraform|k8s|kubernetes|helm)\//.test(p) ||
+      /\.(tf|tfvars|hcl)$/.test(p) ||
+      /(^|\/)Dockerfile(\.\w+)?$/.test(p) ||
+      /(^|\/)docker-compose(\.[-\w]+)?\.ya?ml$/.test(p) ||
+      /(^|\/)\.dockerignore$/.test(p),
+  },
+  {
+    persona: "observability",
+    match: (p) =>
+      /(^|\/)(observability|telemetry|metrics|tracing|logging|monitoring)\//i.test(p) ||
+      /(^|\/)sentry\.(client|server)\./.test(p),
+  },
+  {
+    persona: "ai-governance",
+    match: (p) =>
+      /(^|\/)(prompts?|llm|ai|agents?)\//i.test(p) ||
+      /(^|\/)prompt[-_]/.test(p) ||
+      /\.prompt(\.md)?$/.test(p),
+  },
+  {
+    persona: "data-layer",
+    match: (p) =>
+      /(^|\/)(migrations?|alembic|prisma|db|database|schema)\//i.test(p) ||
+      /\.sql$/.test(p) ||
+      /(^|\/)models?\//i.test(p),
+  },
+  {
+    persona: "security",
+    match: (p) =>
+      /(^|\/)(auth|authn|authz|security)\//i.test(p) ||
+      /(^|\/)(middleware|guards?)\/(auth|security)/i.test(p) ||
+      /(^|\/)\.env(\.\w+)?$/.test(p),
+  },
+  {
+    persona: "frontend",
+    match: (p) =>
+      /(^|\/)(components?|pages?|app|views?|ui|styles?)\//i.test(p) ||
+      /\.(tsx|jsx|vue|svelte|css|scss|sass)$/.test(p),
+  },
+  {
+    persona: "reliability",
+    match: (p) =>
+      /(^|\/)(health|liveness|readiness|circuit[-_]?breaker)\//i.test(p) ||
+      /(^|\/)retries?\//i.test(p),
+  },
+  {
+    persona: "code-quality",
+    match: (p) =>
+      /(^|\/)\.?(eslintrc|prettierrc|biome|stylelintrc)(\.[-\w]+)?$/.test(p) ||
+      /(^|\/)\.editorconfig$/.test(p),
+  },
+  {
+    persona: "backend",
+    match: (p) =>
+      /(^|\/)(api|server|backend|routes?|services?|handlers?|controllers?)\//i.test(
+        p
+      ) ||
+      /\.(py|rb|go|rs)$/.test(p) ||
+      /\.(ts|js|mts|mjs|cts|cjs)$/.test(p),
+  },
+];
+
+export function routeFileHeuristic(
+  filePath,
+  { fallback = DEFAULT_HEURISTIC_FALLBACK } = {}
+) {
+  const normalized = normalizePathForMatch(filePath);
+  if (!normalized) {
+    return fallback;
+  }
+  for (const rule of HEURISTIC_RULES) {
+    if (rule.match(normalized)) {
+      return rule.persona;
+    }
+  }
+  return fallback;
+}
+
+// --- Public API ---------------------------------------------------------
+
+// Given the file list plus (optional) scaffold config, produce a Map of
+// posix-style relative path → persona id. Rules are last-match-wins: the
+// scaffold ordering lets authors put a broad default first, then override
+// subtrees below.
+export function buildOwnershipMap(files, scaffoldConfig = null) {
+  const rules = Array.isArray(scaffoldConfig?.ownershipRules)
+    ? scaffoldConfig.ownershipRules
+    : [];
+  const map = new Map();
+  const fileList = Array.isArray(files) ? files : [];
+  for (const rawFile of fileList) {
+    const file = normalizePathForMatch(rawFile);
+    if (!file) {
+      continue;
+    }
+    if (rules.length > 0) {
+      let owner = null;
+      for (const rule of rules) {
+        if (matchGlob(rule.pattern, file)) {
+          owner = rule.persona;
+        }
+      }
+      if (owner) {
+        map.set(file, owner);
+        continue;
+      }
+    }
+    map.set(file, routeFileHeuristic(file));
+  }
+  return map;
+}
+
+// Bin findings by persona using the ownership map. Findings whose file is
+// not in the map (e.g. a scanner reported on a path outside the ingest)
+// fall back to the heuristic router so they don't get silently dropped.
+export function routeFindingsToPersonas(findings, ownershipMap) {
+  const source = Array.isArray(findings) ? findings : [];
+  const map = ownershipMap instanceof Map ? ownershipMap : new Map();
+  const perPersona = {};
+  for (const finding of source) {
+    if (!finding || typeof finding !== "object") {
+      continue;
+    }
+    const filePath = normalizePathForMatch(
+      finding.file || finding.path || finding.location || ""
+    );
+    let persona = normalizePersonaId(map.get(filePath) || "");
+    if (!persona) {
+      persona = routeFileHeuristic(filePath);
+    }
+    if (!perPersona[persona]) {
+      perPersona[persona] = [];
+    }
+    perPersona[persona].push(finding);
+  }
+  return perPersona;
+}
+
+// Lightweight metric for the spec's ≥40% token-reduction target. Given an
+// ownership map + pre-routing cost assumption (every persona sees every
+// file), report how many files each persona would actually need to scan.
+export function computeRoutingStats(ownershipMap) {
+  const map = ownershipMap instanceof Map ? ownershipMap : new Map();
+  const totalFiles = map.size;
+  if (totalFiles === 0) {
+    return {
+      totalFiles: 0,
+      personaCoverage: {},
+      totalScansUnrouted: 0,
+      totalScansRouted: 0,
+      tokenReductionEstimatePct: 0,
+    };
+  }
+  const personaCoverage = {};
+  for (const persona of map.values()) {
+    personaCoverage[persona] = (personaCoverage[persona] || 0) + 1;
+  }
+  const totalScansUnrouted = totalFiles * PERSONA_IDS.length;
+  const totalScansRouted = totalFiles; // 1 persona per file with last-match-wins routing
+  const tokenReductionEstimatePct = Math.round(
+    (1 - totalScansRouted / totalScansUnrouted) * 100
+  );
+  return {
+    totalFiles,
+    personaCoverage,
+    totalScansUnrouted,
+    totalScansRouted,
+    tokenReductionEstimatePct,
+  };
+}
+
+export { DEFAULT_HEURISTIC_FALLBACK, SCAFFOLD_RELATIVE_PATH };

package/src/legacy-cli.js

@@ -206,12 +206,23 @@ function printUsage() {
   console.log("");
   console.log("Session Coordination:");
   console.log("  sl session start --json            Create an agent coordination session");
+  console.log("  sl session start --template code-review  Start from quick-start preset + launch plan");
+  console.log("  sl session templates --json        List available session quick-start templates");
   console.log("  sl session join <id> --name <n>    Join a session as an agent");
   console.log("  sl session say <id> \"msg\" --json  Append a message event to session stream");
+  console.log("  sl session say <id> \"lock: <file> - <intent>\"  Request an exclusive file lock via Senti");
+  console.log("  sl session say <id> \"assign: @agent <task>\"  Create task assignment + lease");
+  console.log("  sl session say <id> \"assign: @*:reviewer <task>\"  Wildcard route to least-busy role");
+  console.log("  sl session say <id> \"accepted: task <task-id>\" / \"done: task <task-id>\"  Task transitions");
   console.log("  sl session read <id> --tail 20     Read session stream events");
   console.log("  sl session status <id> --json      Show session health, agents, runs, leases");
   console.log("  sl session leave <id>              Leave a session");
   console.log("  sl session list --json             List active sessions");
+  console.log("  sl session setup-guides <id> --json  Upsert AGENTS.md/CLAUDE.md coordination section");
+  console.log("  sl session inject-guide <id> --json  Inject section into existing AGENTS.md/CLAUDE.md files");
+  console.log("  sl session provision-emails <id> --count 5  Provision AIdenID emails for swarm testing");
+  console.log("  sl session admin-kill <id> --reason <reason>  Admin kill one remote session");
+  console.log("  sl session admin-kill-all --confirm  Admin kill ALL remote sessions");
   console.log("  sl session kill --session <id> --agent <id>  Kill agent + revoke active leases");
   console.log("");
   console.log("Security & Review:");
@@ -1099,8 +1110,54 @@ function buildOmarTerminalHandler({ startedAt = Date.now() } = {}) {
 async function runLocalOmarGateCommand(args) {
   const commandStartedAt = Date.now();
   const mode = String(args[0] || "").trim().toLowerCase();
+  if (mode === "investor-dd") {
+    const pathArg = getCommandOptionValue(args, "--path") || ".";
+    const outputDirArg = getCommandOptionValue(args, "--output-dir") || "";
+    const asJson = hasCommandOption(args, "--json");
+    const dryRun = hasCommandOption(args, "--dry-run");
+    const maxCostUsd = parseFloat(getCommandOptionValue(args, "--max-cost") || "25.0") || 25.0;
+    const maxRuntimeMinutes =
+      parseInt(getCommandOptionValue(args, "--max-runtime-minutes") || "45", 10) || 45;
+    const maxParallel =
+      parseInt(getCommandOptionValue(args, "--max-parallel") || "3", 10) || 3;
+    const streamEnabled = hasCommandOption(args, "--stream");
+
+    const targetPath = path.resolve(process.cwd(), pathArg);
+    if (!fs.existsSync(targetPath) || !fs.statSync(targetPath).isDirectory()) {
+      throw new Error(`Invalid --path target: ${targetPath}`);
+    }
+
+    const { runInvestorDd } = await import("./review/investor-dd-orchestrator.js");
+    if (!asJson) {
+      printSection("Investor-DD Audit");
+      printInfo(`Target: ${targetPath}`);
+      printInfo(
+        `Budget: $${maxCostUsd.toFixed(2)} / ${maxRuntimeMinutes}min / ${maxParallel} parallel`,
+      );
+      if (dryRun) printInfo("Mode: dry-run (plan + stub report only)");
+    }
+    const result = await runInvestorDd({
+      rootPath: targetPath,
+      outputDir: outputDirArg,
+      budgetOptions: { maxCostUsd, maxRuntimeMinutes, maxParallel },
+      dryRun,
+      onEvent: streamEnabled
+        ? (event) => process.stdout.write(`${JSON.stringify(event)}\n`)
+        : () => {},
+    });
+    if (asJson) {
+      process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+    } else {
+      printInfo(`Report: ${path.join(result.artifactDir, "report.md")}`);
+      printInfo(`Artifacts: ${result.artifactDir}`);
+      printInfo(`Status: ${result.summary.terminationReason}`);
+      printInfo(`Findings: ${result.summary.totalFindings}`);
+      printInfo(`Elapsed: ${result.summary.durationSeconds.toFixed(1)}s`);
+    }
+    return;
+  }
   if (mode && mode !== "deep") {
-    throw new Error(`Unsupported /omargate mode '${mode}'. Use: /omargate deep`);
+    throw new Error(`Unsupported /omargate mode '${mode}'. Use: /omargate deep | /omargate investor-dd`);
   }
   const asJson = hasCommandOption(args, "--json");
   const pathArg = getCommandOptionValue(args, "--path") || ".";
@@ -1113,6 +1170,14 @@ async function runLocalOmarGateCommand(args) {
   const scanMode = getCommandOptionValue(args, "--scan-mode") || "deep";
   const maxParallel = parseInt(getCommandOptionValue(args, "--max-parallel") || "4", 10) || 4;
   const streamEnabled = hasCommandOption(args, "--stream");
+  // Per-persona filter flags (A-CLI-1). --persona <csv> narrows the dispatch
+  // roster to the listed IDs; --skip-persona <csv> removes listed IDs from
+  // whatever the mode's baseline roster is. Both can be combined.
+  const personaCsvFlag = getCommandOptionValue(args, "--persona") || "";
+  const skipPersonaCsvFlag = getCommandOptionValue(args, "--skip-persona") || "";
+  const { parsePersonaCsv } = await import("./review/scan-modes.js");
+  const includeOnly = parsePersonaCsv(personaCsvFlag);
+  const skipPersonas = parsePersonaCsv(skipPersonaCsvFlag);
   const targetPath = path.resolve(process.cwd(), pathArg);
   if (!fs.existsSync(targetPath) || !fs.statSync(targetPath).isDirectory()) {
     throw new Error(`Invalid --path target: ${targetPath}`);
@@ -1175,6 +1240,8 @@ async function runLocalOmarGateCommand(args) {
           metadata: deterministic.metadata || {},
         },
         onEvent: streamHandler,
+        includeOnly: includeOnly.length > 0 ? includeOnly : null,
+        skipPersonas: skipPersonas.length > 0 ? skipPersonas : null,
       });
 
       // Use orchestrator results as the AI layer. aiResult represents ONLY

package/src/orchestrator/kai-chen.js

@@ -0,0 +1,126 @@
+/**
+ * Dr. Kai Chen — Global Orchestrator (a.k.a. "Senti" / Telegram coordinator).
+ *
+ * Kai Chen is NOT a review persona; he is the orchestration tier that sits
+ * above the 13 domain reviewers (Nina, Maya, Ethan, Priya, Linh, Jules,
+ * Samir, Noah, Omar, Sofia, Kat, Nora, Amina). He picks which personas run,
+ * routes high-signal findings up to the user, and emits the final report.
+ *
+ * Background (Carter's canon):
+ *   - Ex-Google Staff; Chrome V8 performance lead
+ *   - Bias: performance budgets, operational simplicity, correctness over
+ *     cleverness
+ *   - Tone: crisp, evidence-first; hates vague claims; demands reproduction
+ *     steps
+ *   - Output signature: "Here's what breaks, where, why, and what to do next."
+ *
+ * Model routing:
+ *   - Primary: Opus 4.6 (reasoning-heavy orchestration; called ~1-3 times
+ *     per scan or build)
+ *   - NEVER OpenAI gpt-5.3-codex (code-gen workers only)
+ *   - NEVER Gemini (dropped from provider fallback order)
+ *
+ * This module exports the orchestrator DEFINITION + a prompt-assembly helper.
+ * Wiring Kai into actual review/build flows happens in subsequent PRs (the
+ * gate dispatcher, the Telegram entry-point, and the build-pathway planner
+ * all consume this definition).
+ */
+
+const KAI_CHEN_BIAS = Object.freeze([
+  "performance budgets over premature optimization",
+  "operational simplicity over cleverness",
+  "correctness over features",
+  "evidence over vague claims",
+  "reproduction steps for every issue",
+]);
+
+const KAI_CHEN_TONE_RULES = Object.freeze([
+  "crisp sentences; no hedging",
+  "evidence-first; cite file:line or metric name on every claim",
+  "demand reproduction steps before accepting any finding as actionable",
+  "reject reviewer output that is vague, speculative, or missing coverage proof",
+  "call out 'looks fine' conclusions that aren't backed by enumerated checklist coverage",
+]);
+
+const KAI_CHEN_OUTPUT_SIGNATURE = "Here's what breaks, where, why, and what to do next.";
+
+const KAI_CHEN_SYSTEM_PROMPT = [
+  "You are Dr. Kai Chen, global orchestrator for the Sentinelayer review platform.",
+  "",
+  "Your job is NOT to review code directly. Your job is to:",
+  "  1. Pick which specialist personas should run against this target and why.",
+  "  2. Receive the specialists' findings + coverage enumerations.",
+  "  3. Deduplicate across personas (same file:line across domains boosts confidence, not noise).",
+  "  4. Rank by severity × confidence × blast radius.",
+  "  5. Emit a single consolidated report using your output signature.",
+  "",
+  "Non-negotiables:",
+  "  - Every finding you surface to the user MUST have an enumerated reproduction path.",
+  "  - If a specialist returned zero findings, the specialist MUST have enumerated their checklist coverage; if they did not, you reject their output and re-dispatch.",
+  "  - You do not pad reports with speculative or 'theoretical' concerns. Cut them at the orchestrator tier.",
+  "  - You are a performance-focused reviewer by training. Favor operational simplicity over cleverness in your recommendations.",
+  "",
+  "Output signature (end every summary with this exact phrasing, populated):",
+  `  "${KAI_CHEN_OUTPUT_SIGNATURE}"`,
+  "",
+  "Your tone rules:",
+  ...KAI_CHEN_TONE_RULES.map((rule) => `  - ${rule}`),
+].join("\n");
+
+export const ORCHESTRATOR_DEFINITION = Object.freeze({
+  id: "orchestrator-kai-chen",
+  name: "Dr. Kai Chen",
+  shortName: "Kai",
+  role: "Global Orchestrator / Senti",
+  background: "Ex-Google Staff; Chrome V8 performance lead",
+  model: "claude-opus-4-6",
+  modelProvider: "anthropic",
+  bias: KAI_CHEN_BIAS,
+  toneRules: KAI_CHEN_TONE_RULES,
+  outputSignature: KAI_CHEN_OUTPUT_SIGNATURE,
+  systemPrompt: KAI_CHEN_SYSTEM_PROMPT,
+});
+
+/**
+ * Build a context-enriched orchestrator prompt for a specific scan/build run.
+ *
+ * @param {object} [options]
+ * @param {string} [options.targetPath]       - Repository path under review.
+ * @param {string} [options.mode]             - e.g. "baseline" | "deep" | "full-depth" | "build".
+ * @param {string[]} [options.dispatchedPersonas] - Persona IDs dispatched for this run.
+ * @param {object} [options.deterministicSummary] - Pre-LLM deterministic scan summary.
+ * @returns {string} Assembled orchestrator system prompt.
+ */
+export function buildOrchestratorPrompt({
+  targetPath = "",
+  mode = "deep",
+  dispatchedPersonas = [],
+  deterministicSummary = {},
+} = {}) {
+  const personaList = dispatchedPersonas.length > 0
+    ? dispatchedPersonas.map((id) => `  - ${id}`).join("\n")
+    : "  (none specified)";
+
+  const detSummary = [
+    `P0=${deterministicSummary.P0 || 0}`,
+    `P1=${deterministicSummary.P1 || 0}`,
+    `P2=${deterministicSummary.P2 || 0}`,
+    `P3=${deterministicSummary.P3 || 0}`,
+  ].join(" ");
+
+  return [
+    ORCHESTRATOR_DEFINITION.systemPrompt,
+    "",
+    "## Run context",
+    `Target: ${targetPath || "(not provided)"}`,
+    `Mode: ${mode}`,
+    `Deterministic-scan summary (already surfaced, do NOT re-report): ${detSummary}`,
+    "",
+    "## Specialists dispatched for this run",
+    personaList,
+    "",
+    "Begin.",
+  ].join("\n");
+}
+
+export const KAI_CHEN_OUTPUT_SIGNATURE_VALUE = KAI_CHEN_OUTPUT_SIGNATURE;

package/src/review/ai-review.js

@@ -10,6 +10,7 @@ import { loadConfig } from "../config/service.js";
 import { evaluateBudget } from "../cost/budget.js";
 import { appendCostEntry, summarizeCostHistory } from "../cost/history.js";
 import { estimateModelCost } from "../cost/tracker.js";
+import { estimateTokens } from "../cost/tokenizer.js";
 import { appendRunEvent, deriveStopClassFromBudget } from "../telemetry/ledger.js";
 
 const AI_SEVERITIES = new Set(["P0", "P1", "P2", "P3"]);
@@ -36,14 +37,6 @@ function parsePercent(rawValue, field) {
   return normalized;
 }
 
-function estimateTokenCount(text) {
-  const normalized = String(text || "");
-  if (!normalized) {
-    return 0;
-  }
-  return Math.max(1, Math.ceil(normalized.length / 4));
-}
-
 function resolveConfiguredApiKey(provider, resolvedConfig = {}) {
   const normalizedProvider = normalizeString(provider).toLowerCase();
   if (normalizedProvider === "openai") {
@@ -479,8 +472,8 @@ export async function runAiReviewLayer({
   };
   combinedSummary.blocking = combinedSummary.P0 > 0 || combinedSummary.P1 > 0;
 
-  const inputTokens = estimateTokenCount(prompt);
-  const outputTokens = estimateTokenCount(responseText);
+  const inputTokens = estimateTokens(prompt, { model: resolvedModel });
+  const outputTokens = estimateTokens(responseText, { model: resolvedModel });
   const modelCost = maybeEstimateModelCost({
     modelId: resolvedModel,
     inputTokens,