@kal-elsam/kairo-runtime 0.16.0 → 0.18.0

package/src/global/conversation/cursor-sandbox.js

@@ -0,0 +1,215 @@
+// Real OS-level filesystem confinement for the Cursor CLI (cursor-agent),
+// used ONLY for Bootstrap Analysis, mirroring codex-sandbox.js exactly —
+// general ASK never routes Cursor through this module.
+//
+// Empirically proven necessary AND sufficient, not assumed: Cursor's own
+// `--sandbox enabled` (documented in `cursor-agent --help` as "Explicitly
+// enable or disable sandbox mode") does NOT confine file reads to
+// --workspace — a real absolute-path read outside the workspace
+// succeeded and disclosed real content under `--sandbox enabled` alone.
+// The same external sandbox-exec wrapper approach that closed this gap
+// for Codex (codex-sandbox.js) was then independently canary-tested
+// against the real cursor-agent CLI and DOES hold: wrapping `cursor-agent`
+// in an external macOS sandbox-exec profile, with Cursor's own internal
+// sandbox disabled (`--sandbox disabled`, so only the external wrapper
+// enforces anything — avoids any risk of the kind of nested-sandbox
+// conflict that broke every Codex tool call when both layers tried to
+// sandbox at once), produces a real, held boundary: an in-bounds read
+// succeeds, an out-of-bounds absolute-path read is denied
+// ("Permission denied", not a model claim in prose).
+//
+// Two real gotchas found only by testing the ACTUAL cursor-agent binary
+// (not assumed from Codex's profile):
+//  1. cursor-agent's real binary lives under `~/.local` (a wrapper script
+//     at ~/.local/bin/cursor-agent execs the real binary under
+//     ~/.local/share/cursor-agent/versions/...) — that whole tree must be
+//     readable+executable, or the CLI can't even launch.
+//  2. cursor-agent's stored auth ("Authentication tokens stored
+//     securely") lives in the macOS Keychain, not a plain file under its
+//     config home — ~/Library/Keychains must be read+write accessible or
+//     every real invocation fails with "Authentication required" even
+//     though the session is genuinely logged in. The wrapper script also
+//     writes to /dev/null, which needs explicit file-write access (unlike
+//     Codex's profile, which never needed it).
+//
+// A workspace cursor-agent has never seen before triggers an interactive
+// "Workspace Trust Required" prompt that blocks non-interactive use —
+// `--trust` is required for automation, safe here because snapshotRoot is
+// always Kairo's own freshly-generated temp directory, never an
+// arbitrary user-chosen one (same category of bypass as Codex's
+// --skip-git-repo-check for a snapshot that deliberately excludes .git).
+
+import { spawn as defaultSpawn } from "node:child_process";
+import { access, mkdtemp, realpath, rm, writeFile } from "node:fs/promises";
+import { constants as fsConstants } from "node:fs";
+import { tmpdir, homedir } from "node:os";
+import { join } from "node:path";
+
+const SANDBOX_EXEC_PATH = "/usr/bin/sandbox-exec";
+const DEFAULT_TIMEOUT_MS = 180_000;
+
+const SAFE_ENV_KEYS = Object.freeze([
+  "PATH", "HOME", "USER", "LOGNAME", "SHELL", "LANG", "LC_ALL", "LC_CTYPE",
+  "TMPDIR", "TERM", "HTTP_PROXY", "HTTPS_PROXY", "NO_PROXY",
+  "http_proxy", "https_proxy", "no_proxy", "NODE_EXTRA_CA_CERTS"
+]);
+
+function buildSandboxedCursorEnv(sourceEnv = process.env) {
+  const env = Object.create(null);
+  for (const key of 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) };
+}
+
+export async function isCursorSandboxSupported(deps = {}) {
+  if ((deps.platform ?? process.platform) !== "darwin") return false;
+  try {
+    await (deps.access ?? access)(SANDBOX_EXEC_PATH, fsConstants.X_OK);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export async function getCursorIsolationStatus(deps = {}) {
+  const available = await isCursorSandboxSupported(deps);
+  return {
+    available,
+    platform: deps.platform ?? process.platform,
+    boundaryVerified: available,
+    reason: available
+      ? null
+      : "OS-level read confinement for Cursor (sandbox-exec) is only implemented for macOS; Cursor is not eligible for isolated Bootstrap Analysis on this platform."
+  };
+}
+
+async function resolvedForms(path, deps) {
+  const forms = new Set([path]);
+  try {
+    forms.add(await (deps.realpath ?? realpath)(path));
+  } catch {
+    // fine — the literal form alone still covers it
+  }
+  return [...forms];
+}
+
+function subpathRules(paths) {
+  return paths.map((p) => `  (subpath "${p}")`).join("\n");
+}
+
+export async function buildCursorSandboxProfile({
+  snapshotRoot,
+  cursorHome = join(homedir(), ".cursor"),
+  cursorLocalHome = join(homedir(), ".local"),
+  keychainsHome = join(homedir(), "Library", "Keychains")
+}, deps = {}) {
+  const snapshotForms = await resolvedForms(snapshotRoot, deps);
+  const cursorHomeForms = await resolvedForms(cursorHome, deps);
+  const cursorLocalForms = await resolvedForms(cursorLocalHome, deps);
+  const keychainsForms = await resolvedForms(keychainsHome, deps);
+  const readableExtra = [
+    "/usr", "/System", "/bin", "/sbin", "/private/var/db/dyld", "/Library", "/opt", "/private/etc"
+  ];
+  return `(version 1)
+(deny default)
+(allow process-fork)
+(allow process-exec)
+(allow file-read-metadata (subpath "/"))
+(allow file-read-data (literal "/"))
+(allow file-read*
+${subpathRules([...snapshotForms, ...cursorHomeForms, ...cursorLocalForms, ...keychainsForms, ...readableExtra])}
+  (literal "/dev/null")
+  (literal "/dev/urandom")
+  (literal "/dev/tty"))
+(allow file-write*
+  (literal "/dev/null")
+${subpathRules([...snapshotForms, ...cursorHomeForms, ...keychainsForms, "/private/var/folders", "/private/tmp"])})
+(allow file-read-metadata (subpath "/private/var/folders"))
+(allow sysctl-read)
+(allow mach-lookup)
+(allow signal (target self))
+(allow network*)
+(allow system-socket)
+`;
+}
+
+/**
+ * Runs a real, OS-sandboxed Cursor Bootstrap Analysis question. The ONLY
+ * intended caller is bootstrap-analyzer-adapters.js's Cursor adapter.
+ * Fails closed with `status: "error", error: "isolation_unavailable"`
+ * (never a silent fallback to Cursor's own non-confining --sandbox
+ * enabled) when this platform has no verified boundary.
+ * @param {object} args
+ * @param {string} args.question
+ * @param {string|null} [args.model] - omit (or pass null) for Cursor Auto
+ * @param {string} args.snapshotRoot
+ */
+export async function runCursorSandboxedBootstrap({
+  question, model = null, snapshotRoot,
+  cursorHome = join(homedir(), ".cursor"), cursorLocalHome = join(homedir(), ".local"),
+  keychainsHome = join(homedir(), "Library", "Keychains"),
+  spawn = defaultSpawn, timeoutMs = DEFAULT_TIMEOUT_MS, sourceEnv = process.env, deps = {}
+}) {
+  const isolation = await getCursorIsolationStatus(deps);
+  if (!isolation.available) {
+    return { status: "error", answer: null, error: "isolation_unavailable", isolation };
+  }
+
+  let workDir;
+  try {
+    workDir = await (deps.mkdtemp ?? mkdtemp)(join(tmpdir(), "kairo-cursor-sandbox-"));
+  } catch (error) {
+    return { ...unknown(error?.message ?? error), isolation };
+  }
+  const profilePath = join(workDir, "bootstrap.sb");
+
+  try {
+    const profile = await buildCursorSandboxProfile({ snapshotRoot, cursorHome, cursorLocalHome, keychainsHome }, deps);
+    await (deps.writeFile ?? writeFile)(profilePath, profile, "utf8");
+
+    const args = [
+      "-f", profilePath, "cursor-agent", "-p", question,
+      "--output-format", "json", "--mode", "ask", "--sandbox", "disabled",
+      "--workspace", snapshotRoot, "--trust"
+    ];
+    if (model) args.push("--model", model);
+
+    const env = buildSandboxedCursorEnv(sourceEnv);
+    const result = await new Promise((resolve) => {
+      let child;
+      try {
+        child = spawn("sandbox-exec", args, { cwd: snapshotRoot, env, stdio: ["ignore", "pipe", "pipe"] });
+      } catch (error) {
+        resolve(unknown(error?.message ?? error));
+        return;
+      }
+      let stdout = "";
+      let finished = false;
+      const timer = setTimeout(() => finish(unknown("sandboxed cursor-agent -p timed out")), timeoutMs);
+      function finish(res) {
+        if (finished) return;
+        finished = true;
+        clearTimeout(timer);
+        try { child.kill?.(); } catch { /* best effort */ }
+        resolve(res);
+      }
+      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 sandboxed cursor-agent -p")); }
+        const answer = parsed?.result ?? parsed?.text ?? parsed?.message ?? null;
+        if (typeof answer !== "string") return finish(unknown("no result text in sandboxed cursor-agent -p response"));
+        finish({ status: "answered", answer, error: null });
+      });
+    });
+    return { ...result, isolation };
+  } finally {
+    await (deps.rm ?? rm)(workDir, { recursive: true, force: true }).catch(() => {});
+  }
+}

package/src/global/conversation/project-analysis.js

@@ -0,0 +1,204 @@
+// The real Bootstrap Analyst step: a chosen real model actually reads the
+// project (via askProvider — the same real, read-only, no-file-write path
+// ASK mode already uses; never a new execution surface) and returns a
+// structured ProjectAnalysis, validated against a real schema before
+// anything downstream trusts it. An invalid or unparseable response is
+// rejected outright — no ProjectStrategy is ever built from it.
+//
+// The deterministic step (deriveRoleRequirements) then turns that
+// validated analysis into real RoleNeed[] — sanitized against the known
+// capability vocabulary, unioned with the project's own mechanical floor
+// (real test/lint/build commands, already computed by project-profile.js)
+// so a thin or low-confidence analysis can never leave the project with
+// literally zero real role requirements.
+
+export const PROJECT_ANALYSIS_SCHEMA = "kairo.project-analysis/v1";
+
+// The only real capabilities the scoring engine (capability-scoring.js)
+// actually understands — any other token in the analyst's own output is
+// dropped rather than trusted, so a hallucinated capability name can never
+// corrupt scoring (worst case: a role with zero recognized capabilities
+// simply never activates — fails closed, not open).
+const KNOWN_CAPABILITIES = new Set(["reasoning", "coding", "terminalExecution", "softwareExecution", "instructionFollowing"]);
+const KNOWN_ROLES = new Set(["Explorer", "Architect", "Builder", "Debugger", "Tester", "Reviewer"]);
+
+/**
+ * The real, limited context package the Bootstrap Analyst receives — never
+ * the whole repo dumped in, and never anything the analyst could mistake
+ * for permission to write: just what project-profile.js already collected
+ * read-only (stack, real build/test/lint commands, real git hotspots,
+ * real workflow docs present). The analyst can still read further real
+ * files on its own (it runs inside `cwd`), but this is its starting brief.
+ * @param {object} profile - computeProjectProfile() result
+ * @returns {string}
+ */
+export function buildAnalystPrompt(profile) {
+  const lines = [
+    "You are Kairo's Bootstrap Analyst. Investigate this real project, READ-ONLY — never propose or make any file change.",
+    "You may read real files in this working directory to inform your answer, but do not modify anything.",
+    "",
+    "## Known real evidence",
+    `Project: ${profile.projectName}`,
+    `Stack: ${profile.stack.join(", ") || "unknown"}`,
+    `Architecture pattern: ${profile.architecture?.pattern ?? "unknown"}`,
+    `Build command: ${profile.quality.buildCommand ?? "none detected"}`,
+    `Test command: ${profile.quality.testCommand ?? "none detected"}`,
+    `Lint/typecheck: ${profile.quality.lintCommand ?? profile.quality.typeCheckCommand ?? "none detected"}`,
+    `Real git hotspots (most-changed files, last 90 days): ${profile.hotspots.map((h) => h.path).join(", ") || "none"}`,
+    `Workflow docs present: ${profile.workflowCapabilities.join(", ") || "none"}`,
+    `Known risks: ${profile.risks.map((r) => r.detail).join("; ") || "none"}`,
+    "",
+    "## Task",
+    "Respond with ONLY one JSON object (no prose, no markdown fences) matching exactly this shape:",
+    JSON.stringify({
+      architectureTraits: ["string"], complexitySignals: ["string"], criticalAreas: ["string"],
+      contextNeeds: ["string"], workflowNeeds: ["string"],
+      recommendedRoleNeeds: [{
+        role: "Explorer|Architect|Builder|Debugger|Tester|Reviewer",
+        capabilities: ["reasoning|coding|terminalExecution|softwareExecution|instructionFollowing"],
+        reason: "string", evidence: ["real file path you actually read that supports THIS role need"]
+      }],
+      uncertainties: ["string"], evidenceReferences: ["string"]
+    }, null, 2),
+    "",
+    "Every field must reflect something you actually observed in this project — never invent a trait, risk, or role need you have no real evidence for. If you're not sure about something, put it in `uncertainties` instead of guessing.",
+    "Each recommendedRoleNeeds entry's own `evidence` must list the real file path(s) you actually read that support THAT SPECIFIC role need — a role need with no real evidence of its own will be discarded, even if other fields in this response are well-supported."
+  ];
+  return lines.join("\n");
+}
+
+/**
+ * Extracts and validates a ProjectAnalysis from the analyst's raw text
+ * response. Fails closed: any parse failure or shape mismatch returns
+ * `{valid: false}`, never a partially-trusted guess.
+ * @param {string} rawText
+ * @returns {{valid: true, analysis: object}|{valid: false, error: string}}
+ */
+export function parseProjectAnalysis(rawText) {
+  const match = String(rawText ?? "").match(/\{[\s\S]*\}/);
+  if (!match) return { valid: false, error: "No JSON object found in the analyst's response." };
+  let parsed;
+  try {
+    parsed = JSON.parse(match[0]);
+  } catch (error) {
+    return { valid: false, error: `Analyst response is not valid JSON: ${error.message}` };
+  }
+  const arrayFields = ["architectureTraits", "complexitySignals", "criticalAreas", "contextNeeds", "workflowNeeds", "uncertainties", "evidenceReferences"];
+  for (const field of arrayFields) {
+    if (!Array.isArray(parsed[field])) return { valid: false, error: `Missing or invalid real array field "${field}".` };
+  }
+  if (!Array.isArray(parsed.recommendedRoleNeeds)) return { valid: false, error: 'Missing or invalid real array field "recommendedRoleNeeds".' };
+  for (const need of parsed.recommendedRoleNeeds) {
+    if (typeof need?.role !== "string" || !Array.isArray(need.capabilities)) {
+      return { valid: false, error: "Each recommendedRoleNeeds entry needs a real role (string) and capabilities (array)." };
+    }
+  }
+  return {
+    valid: true,
+    analysis: {
+      schema: PROJECT_ANALYSIS_SCHEMA,
+      architectureTraits: parsed.architectureTraits.map(String),
+      complexitySignals: parsed.complexitySignals.map(String),
+      criticalAreas: parsed.criticalAreas.map(String),
+      contextNeeds: parsed.contextNeeds.map(String),
+      workflowNeeds: parsed.workflowNeeds.map(String),
+      // `evidence` defaults to an empty array when the analyst omits it —
+      // never invented, and a role need with no evidence of its own
+      // fails the real per-entry gate in deriveRoleRequirements below,
+      // exactly as if it had cited nothing real.
+      recommendedRoleNeeds: parsed.recommendedRoleNeeds.map((need) => ({
+        role: String(need.role), capabilities: need.capabilities.map(String),
+        reason: typeof need.reason === "string" ? need.reason : null,
+        evidence: Array.isArray(need.evidence) ? need.evidence.map(String) : []
+      })),
+      uncertainties: parsed.uncertainties.map(String),
+      evidenceReferences: parsed.evidenceReferences.map(String)
+    }
+  };
+}
+
+function normalizePath(path) {
+  return String(path ?? "").trim().replace(/^\.\//, "").replace(/\/+$/, "");
+}
+
+/**
+ * Whether a single cited path corresponds to a real file the analyst
+ * actually had access to (the sanitized snapshot's real copied-file
+ * list) — a citation to a path that was never even in the snapshot is a
+ * real, checkable signal the analyst may be describing exploration it
+ * didn't actually do, not evidence it observed. Matching is real-path-
+ * based but tolerant of how a model might phrase a reference (a leading
+ * "./", or citing just the tail of a longer real path) — an exact
+ * string mismatch alone never disqualifies a real match.
+ * @param {string} reference
+ * @param {string[]} realFilePaths
+ * @returns {boolean}
+ */
+function referenceMatchesRealFile(reference, realFilePaths) {
+  const ref = normalizePath(reference);
+  if (!ref) return false;
+  return realFilePaths.some((path) => path === ref || path.endsWith(`/${ref}`) || ref.endsWith(`/${path}`));
+}
+
+/**
+ * Checks which of a list of citations correspond to a real file — used
+ * both for the analysis's own top-level evidenceReferences (informational)
+ * and, per-entry, for each recommendedRoleNeeds' own `evidence` (see
+ * deriveRoleRequirements, which is the one that actually gates on this).
+ * @param {string[]} references
+ * @param {string[]} realFilePaths - the sanitized snapshot's real copiedFiles
+ * @returns {{verified: string[], unverified: string[]}}
+ */
+export function validateReferences(references, realFilePaths) {
+  const real = realFilePaths.map(normalizePath);
+  const verified = [];
+  const unverified = [];
+  for (const raw of references) {
+    (referenceMatchesRealFile(raw, real) ? verified : unverified).push(raw);
+  }
+  return { verified, unverified };
+}
+
+/** Back-compat alias — validates the analysis's own top-level evidenceReferences. @deprecated prefer validateReferences for the per-RoleNeed gate in deriveRoleRequirements. */
+export function validateEvidenceReferences(analysis, realFilePaths) {
+  return validateReferences(analysis.evidenceReferences, realFilePaths);
+}
+
+/**
+ * Deterministically derives real roleRequirements from a validated
+ * ProjectAnalysis, unioned with the project's own mechanical floor (real
+ * build/test/lint commands — see project-profile.js's detectRoleRequirements)
+ * so a thin or low-confidence analysis can never leave a real project with
+ * zero role requirements. The analyst's own role/capability tokens are
+ * sanitized against the known vocabulary first — an unrecognized one is
+ * dropped, never trusted as-is.
+ *
+ * Evidence is checked PER role need, not once for the whole analysis: a
+ * recommendedRoleNeeds entry is only trusted when at least one of ITS OWN
+ * `evidence` citations verifies against a real file the analyst actually
+ * had access to — a single well-evidenced role need can no longer
+ * "vouch for" every other, unrelated role need in the same response.
+ * @param {object} analysis - parseProjectAnalysis().analysis
+ * @param {Array<{role: string, capabilities: string[], reason: string}>} mechanicalFloor - profile.roleRequirements (the pre-existing command-based detection)
+ * @param {string[]} [realFilePaths] - the sanitized snapshot's real copiedFiles; omit only when no real file list is available (falls back to trusting each role need's vocabulary alone, matching this function's pre-sanitized-snapshot behavior)
+ * @returns {Array<{role: string, capabilities: string[], reason: string}>}
+ */
+export function deriveRoleRequirements(analysis, mechanicalFloor, realFilePaths = null) {
+  const byRole = new Map(mechanicalFloor.map((requirement) => [requirement.role, { ...requirement }]));
+  for (const need of analysis.recommendedRoleNeeds) {
+    if (!KNOWN_ROLES.has(need.role)) continue;
+    const capabilities = need.capabilities.filter((c) => KNOWN_CAPABILITIES.has(c));
+    if (!capabilities.length) continue;
+    // Real-evidence-per-recommendation gate: this specific role need is
+    // only trusted when it cites at least one real file of its own.
+    if (realFilePaths && !(need.evidence ?? []).some((ref) => referenceMatchesRealFile(ref, realFilePaths))) continue;
+    const existing = byRole.get(need.role);
+    if (existing) {
+      existing.capabilities = [...new Set([...existing.capabilities, ...capabilities])];
+      existing.reason = `${existing.reason} Bootstrap Analyst: ${need.reason ?? "real project analysis"}.`;
+    } else {
+      byRole.set(need.role, { role: need.role, capabilities, reason: `Bootstrap Analyst: ${need.reason ?? "real project analysis"}.` });
+    }
+  }
+  return [...byRole.values()];
+}

package/src/global/conversation/project-profile.js

@@ -0,0 +1,178 @@
+// Real, evidence-only ProjectProfile: what Kairo can actually detect about
+// THIS project (stack, commands, git recency, Graphify/CodeGraph/Engram
+// availability, docs) — never a value invented for a signal that couldn't
+// be collected. Every heavy detector here is REUSED from where it already
+// exists in this codebase (detectProject, resolveGitHeadSha, probeGraphify,
+// inspectEngramIntegration) rather than reimplemented, so this module stays
+// a thin composition layer, not a second copy of that logic.
+
+import { existsSync } from "node:fs";
+import { spawnSync } from "node:child_process";
+import { createHash } from "node:crypto";
+import { resolve } from "node:path";
+import { detectProject } from "../../project-detection.js";
+import { resolveGitHeadSha, probeGraphify, scrubGitOverrideEnv } from "../observability/graphify-probe.js";
+import { inspectEngramIntegration } from "../integrations/engram-evidence.js";
+
+export const PROJECT_PROFILE_SCHEMA = "kairo.project-profile/v1";
+
+const SDD_DOC = "docs/ai/spec-driven-development.md";
+const TDD_DOC = "docs/ai/test-driven-development.md";
+const AGENTS_DOC = "AGENTS.md";
+
+/**
+ * Real recent-history hotspots: which files changed most often in the last
+ * 90 days, via `git log --name-only` — bounded, fail-soft (never throws;
+ * returns an empty list for a non-git or history-less project). This is
+ * the ONLY new detector this module adds rather than reusing — everything
+ * else composes an existing real function.
+ * @param {string} cwd
+ * @returns {Array<{path: string, changes: number}>}
+ */
+export function detectGitHotspots(cwd, { spawn = spawnSync, timeoutMs = 5000, env = process.env, limit = 5 } = {}) {
+  try {
+    const cleanEnv = scrubGitOverrideEnv(env);
+    const result = spawn("git", ["log", "--since=90.days", "--name-only", "--pretty=format:"], {
+      cwd, encoding: "utf8", timeout: timeoutMs, env: cleanEnv, maxBuffer: 10 * 1024 * 1024
+    });
+    if (result.status !== 0) return [];
+    const counts = new Map();
+    for (const line of String(result.stdout ?? "").split("\n")) {
+      const path = line.trim();
+      if (!path) continue;
+      counts.set(path, (counts.get(path) ?? 0) + 1);
+    }
+    return [...counts.entries()]
+      .sort((a, b) => b[1] - a[1])
+      .slice(0, limit)
+      .map(([path, changes]) => ({ path, changes }));
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * Real risks Kairo can actually detect — never a guessed or generic risk.
+ * @param {object} project - detectProject() result
+ * @param {string} root
+ * @returns {Array<{kind: string, detail: string}>}
+ */
+function detectRisks(project, root) {
+  const risks = [];
+  if (project.commands.test === "Not configured") risks.push({ kind: "no-test-command", detail: "No real test script detected in package.json." });
+  if (project.commands.lint === "Not configured" && project.commands.typeCheck === "Not configured") {
+    risks.push({ kind: "no-static-checks", detail: "No real lint or typecheck script detected." });
+  }
+  if (existsSync(resolve(root, ".env"))) risks.push({ kind: "env-file-present", detail: ".env present at project root — never read into evidence without explicit consent." });
+  return risks;
+}
+
+/**
+ * Real, detected role requirements — derived strictly from what
+ * detectProject actually found (a real build/test/lint command), never
+ * from a guess about what a "typical" project needs. Explorer/Architect
+ * stay baseline (every real project needs investigation + planning);
+ * Builder/Tester/Reviewer only appear when their real command exists.
+ * @param {object} project - detectProject() result
+ * @returns {Array<{role: string, capabilities: string[], reason: string}>}
+ */
+function detectRoleRequirements(project) {
+  const requirements = [
+    { role: "Explorer", capabilities: ["reasoning", "instructionFollowing"], reason: "Baseline investigation role for every real project." },
+    { role: "Architect", capabilities: ["reasoning", "coding", "instructionFollowing"], reason: "Baseline planning role for every real project." }
+  ];
+  if (project.commands.build !== "Not configured" || project.stack !== "Unknown") {
+    requirements.push({ role: "Builder", capabilities: ["coding", "softwareExecution", "terminalExecution", "instructionFollowing"], reason: "Real stack/build command detected." });
+  }
+  if (project.commands.test !== "Not configured") {
+    requirements.push({ role: "Tester", capabilities: ["coding", "terminalExecution"], reason: `Real test command detected: ${project.commands.test}` });
+    requirements.push({ role: "Debugger", capabilities: ["reasoning", "coding", "terminalExecution", "softwareExecution"], reason: "Real test command implies real failures to debug." });
+  }
+  if (project.commands.lint !== "Not configured" || project.commands.typeCheck !== "Not configured") {
+    requirements.push({ role: "Reviewer", capabilities: ["reasoning", "coding"], reason: "Real lint/typecheck command detected." });
+  }
+  return requirements;
+}
+
+/**
+ * A real, deterministic fingerprint of the profile's own inputs (git HEAD
+ * when available, plus the real detected commands/stack) — changes exactly
+ * when the real evidence behind the profile changes, which is what
+ * ProjectStrategy's STALE detection compares against. Never a random id.
+ */
+function computeFingerprint({ headSha, project }) {
+  const basis = JSON.stringify({ headSha: headSha ?? "no-git", stack: project.stack, commands: project.commands });
+  return createHash("sha256").update(basis).digest("hex").slice(0, 16);
+}
+
+/**
+ * Composes every real detector above into one ProjectProfile — strictly
+ * read-only, no file writes, no provider calls. `confidence` reflects how
+ * much REAL evidence was actually collected, never the profile's own
+ * apparent completeness — a project with no git history and a minimal
+ * package.json genuinely IS "low" confidence, not something to round up.
+ * @param {{cwd: string}} args
+ * @param {object} [deps] - injectable for tests
+ * @returns {Promise<object>} ProjectProfile
+ */
+export async function computeProjectProfile({ cwd }, deps = {}) {
+  const detectProjectImpl = deps.detectProject ?? detectProject;
+  const resolveGitHeadShaImpl = deps.resolveGitHeadSha ?? resolveGitHeadSha;
+  const probeGraphifyImpl = deps.probeGraphify ?? probeGraphify;
+  const inspectEngramImpl = deps.inspectEngramIntegration ?? inspectEngramIntegration;
+  const detectGitHotspotsImpl = deps.detectGitHotspots ?? detectGitHotspots;
+
+  const root = resolve(cwd);
+  const project = await detectProjectImpl(root);
+  const headSha = resolveGitHeadShaImpl(root);
+  const graphify = await probeGraphifyImpl({ cwd: root, headSha });
+  const engram = inspectEngramImpl();
+  const codegraphPresent = existsSync(resolve(root, ".codegraph"));
+  const hotspots = headSha ? detectGitHotspotsImpl(root) : [];
+
+  const sdd = existsSync(resolve(root, SDD_DOC));
+  const tdd = existsSync(resolve(root, TDD_DOC));
+  const agentsDoc = existsSync(resolve(root, AGENTS_DOC));
+
+  const workflowCapabilities = [];
+  if (sdd) workflowCapabilities.push("sdd");
+  if (tdd) workflowCapabilities.push("tdd");
+
+  const evidence = [
+    { kind: "package-manifest", detail: `packageManager=${project.packageManager}` },
+    { kind: "git-head", detail: headSha ? `HEAD=${headSha.slice(0, 12)}` : "not a git repository (or HEAD unresolved)" },
+    { kind: "graphify", detail: `state=${graphify.state}` },
+    { kind: "codegraph", detail: codegraphPresent ? ".codegraph/ present" : ".codegraph/ absent" },
+    { kind: "engram", detail: `status=${engram.status}` },
+    { kind: "agents-doc", detail: agentsDoc ? "AGENTS.md present" : "AGENTS.md absent" }
+  ];
+
+  // Real, honest tiers — never rounded up because the profile LOOKS
+  // complete. High requires git history (real recency signal) AND at
+  // least one real code-intelligence integration actually available.
+  let confidence = "low";
+  const hasCodeIntelligence = graphify.state === "available" || codegraphPresent || engram.status === "configured";
+  if (headSha && project.stack !== "Unknown") {
+    confidence = hasCodeIntelligence ? "high" : "medium";
+  }
+
+  return {
+    schema: PROJECT_PROFILE_SCHEMA,
+    projectName: project.name,
+    fingerprint: computeFingerprint({ headSha, project }),
+    stack: [project.stack],
+    architecture: { pattern: project.architecturePattern },
+    quality: {
+      testCommand: project.commands.test !== "Not configured" ? project.commands.test : null,
+      lintCommand: project.commands.lint !== "Not configured" ? project.commands.lint : null,
+      typeCheckCommand: project.commands.typeCheck !== "Not configured" ? project.commands.typeCheck : null,
+      buildCommand: project.commands.build !== "Not configured" ? project.commands.build : null
+    },
+    risks: detectRisks(project, root),
+    hotspots,
+    workflowCapabilities,
+    roleRequirements: detectRoleRequirements(project),
+    evidence,
+    confidence
+  };
+}