sentinelayer-cli 0.25.1 → 0.26.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sentinelayer-cli",
-  "version": "0.25.1",
+  "version": "0.26.0",
   "description": "Scaffold Sentinelayer spec/prompt/guide artifacts with secure browser auth and token bootstrap.",
   "type": "module",
   "scripts": {

package/src/agents/jules/tools/investor-dd.js

@@ -0,0 +1,279 @@
+import { frontendAnalyze } from "./frontend-analyze.js";
+
+const SEVERITIES = new Set(["P0", "P1", "P2", "P3"]);
+
+function toPosix(value) {
+  return String(value || "").replace(/\\/g, "/");
+}
+
+function normalizeSeverity(value, fallback = "P2") {
+  const normalized = String(value || "").trim().toUpperCase();
+  return SEVERITIES.has(normalized) ? normalized : fallback;
+}
+
+function normalizeFiles(files) {
+  if (!Array.isArray(files)) return [];
+  return files.map((file) => toPosix(file).trim()).filter(Boolean);
+}
+
+function isInScope(file, scopeFiles) {
+  const normalized = toPosix(file);
+  if (!normalized || scopeFiles.length === 0) return true;
+  return scopeFiles.some((candidate) =>
+    candidate === normalized ||
+    candidate.endsWith(`/${normalized}`) ||
+    normalized.endsWith(`/${candidate}`)
+  );
+}
+
+function createFinding({
+  kind,
+  severity,
+  file = "",
+  line = 0,
+  evidence = "",
+  rootCause = "",
+  recommendedFix = "",
+  confidence = 0.7,
+} = {}) {
+  return {
+    persona: "frontend",
+    tool: "frontend-analyze",
+    kind: String(kind || "frontend.finding"),
+    severity: normalizeSeverity(severity),
+    file: toPosix(file),
+    line: Number.isFinite(Number(line)) ? Math.max(0, Math.floor(Number(line))) : 0,
+    evidence: String(evidence || "").trim().slice(0, 400),
+    rootCause: String(rootCause || "").trim(),
+    recommendedFix: String(recommendedFix || "").trim(),
+    confidence: Math.max(0, Math.min(1, Number(confidence) || 0)),
+  };
+}
+
+function dedupeFindings(findings) {
+  const seen = new Set();
+  const deduped = [];
+  for (const finding of findings) {
+    const key = [
+      finding.kind,
+      finding.file,
+      finding.line,
+      finding.evidence,
+    ].join("|");
+    if (seen.has(key)) continue;
+    seen.add(key);
+    deduped.push(finding);
+  }
+  return deduped;
+}
+
+function analyze(operation, rootPath) {
+  try {
+    return frontendAnalyze({ operation, path: rootPath });
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Deterministic Investor-DD adapter for Jules/frontend.
+ *
+ * `frontendAnalyze` is intentionally repo-scoped, so the Investor-DD runner
+ * invokes this as a single `scope: "repo"` tool per frontend persona run.
+ */
+export async function runFrontendInvestorDdAnalyze({ rootPath, files = [] } = {}) {
+  const scopeFiles = normalizeFiles(files);
+  const findings = [];
+
+  const securitySinks = analyze("find_security_sinks", rootPath);
+  for (const sink of securitySinks?.sinks || []) {
+    if (!isInScope(sink.file, scopeFiles)) continue;
+    findings.push(createFinding({
+      kind: `frontend.security.${String(sink.type || "sink").replace(/\W+/g, "_")}`,
+      severity: sink.severity || "P2",
+      file: sink.file,
+      line: sink.line || 0,
+      evidence: `${sink.type || "frontend security sink"} detected`,
+      rootCause: "Frontend markup or script execution sink can create XSS or client-side code execution risk.",
+      recommendedFix: "Remove the sink or sanitize/escape untrusted content with a reviewed allowlist sanitizer.",
+      confidence: sink.severity === "P0" ? 0.85 : 0.75,
+    }));
+  }
+
+  const envExposure = analyze("find_env_exposure", rootPath);
+  for (const exposure of envExposure?.findings || []) {
+    if (!isInScope(exposure.file, scopeFiles)) continue;
+    findings.push(createFinding({
+      kind: "frontend.env_exposure",
+      severity: exposure.severity || (exposure.sensitive ? "P1" : "P3"),
+      file: exposure.file,
+      line: exposure.line || 0,
+      evidence: `${exposure.variable || "public env variable"} referenced in frontend source`,
+      rootCause: "Public frontend environment prefixes are shipped to the browser; sensitive names can leak credentials or encourage unsafe configuration.",
+      recommendedFix: "Keep secrets server-side and expose only explicitly public, non-sensitive configuration to client bundles.",
+      confidence: exposure.sensitive ? 0.8 : 0.45,
+    }));
+  }
+
+  const missingCleanup = analyze("find_missing_cleanup", rootPath);
+  for (const cleanup of missingCleanup?.findings || []) {
+    if (!isInScope(cleanup.file, scopeFiles)) continue;
+    findings.push(createFinding({
+      kind: "frontend.effect_missing_cleanup",
+      severity: cleanup.severity || "P2",
+      file: cleanup.file,
+      evidence: cleanup.pattern || "Effect with timer/subscription has no cleanup return",
+      rootCause: "Effects that subscribe or schedule timers without cleanup leak work across remounts and route changes.",
+      recommendedFix: "Return a cleanup function that unsubscribes, removes listeners, or clears timers.",
+      confidence: 0.7,
+    }));
+  }
+
+  const staleClosures = analyze("find_stale_closures", rootPath);
+  for (const closure of staleClosures?.findings || []) {
+    if (!isInScope(closure.file, scopeFiles)) continue;
+    findings.push(createFinding({
+      kind: "frontend.stale_closure",
+      severity: closure.severity || "P2",
+      file: closure.file,
+      line: closure.line || 0,
+      evidence: closure.pattern || "useEffect with empty dependency array may capture stale values",
+      rootCause: "Effects with empty dependencies can retain initial state/props while the UI continues to change.",
+      recommendedFix: "Declare dependencies, use stable refs intentionally, or move logic out of the effect.",
+      confidence: 0.55,
+    }));
+  }
+
+  const stateHooks = analyze("count_state_hooks", rootPath);
+  for (const component of stateHooks?.refactorCandidates || []) {
+    if (!isInScope(component.file, scopeFiles)) continue;
+    findings.push(createFinding({
+      kind: "frontend.state_god_component",
+      severity: component.risk === "god_component" ? "P2" : "P3",
+      file: component.file,
+      evidence: `${component.useStateCount} useState calls (${component.risk})`,
+      rootCause: "High local state count usually indicates a component with too many responsibilities and fragile render behavior.",
+      recommendedFix: "Split the component or consolidate related state transitions with a reducer/domain hook.",
+      confidence: component.risk === "god_component" ? 0.7 : 0.45,
+    }));
+  }
+
+  const accessibility = analyze("check_accessibility", rootPath);
+  for (const check of accessibility?.findings || []) {
+    const severity = normalizeSeverity(check.severity, "P3");
+    if (String(check.severity || "").toLowerCase() === "pass") continue;
+    if (Number(check.matchCount || 0) <= 0 && !String(check.check || "").includes("skip navigation")) continue;
+    findings.push(createFinding({
+      kind: "frontend.accessibility_check",
+      severity,
+      evidence: `${check.check || "accessibility heuristic"}; matches=${check.matchCount || 0}`,
+      rootCause: "Accessibility regressions block keyboard and assistive-technology users from completing core flows.",
+      recommendedFix: "Verify semantic labels, keyboard reachability, focus order, skip navigation, and automated axe coverage.",
+      confidence: 0.45,
+    }));
+  }
+
+  const mobile = analyze("check_mobile_responsive", rootPath);
+  for (const check of mobile?.findings || []) {
+    const rawSeverity = String(check.severity || "");
+    if (rawSeverity === "pass" || rawSeverity === "info") continue;
+    findings.push(createFinding({
+      kind: "frontend.mobile_responsive",
+      severity: check.severity || "P2",
+      evidence: `${check.check || "responsive heuristic"}; present=${check.present}; count=${check.count || 0}`,
+      rootCause: "Missing viewport or responsive styling evidence can make primary flows fail on mobile.",
+      recommendedFix: "Add viewport metadata and validate mobile/tablet breakpoints for the core user journey.",
+      confidence: 0.55,
+    }));
+  }
+
+  const errorBoundaries = analyze("check_error_boundaries", rootPath);
+  if (errorBoundaries && errorBoundaries.severity !== "pass") {
+    findings.push(createFinding({
+      kind: "frontend.error_boundary_gap",
+      severity: errorBoundaries.severity || "P2",
+      evidence: `errorBoundaryFiles=${errorBoundaries.errorBoundaryFiles || 0}; routeCount=${errorBoundaries.routeCount || 0}; coverage=${errorBoundaries.coverage || "n/a"}`,
+      rootCause: "Route-level runtime exceptions can blank the UI without a recoverable boundary.",
+      recommendedFix: "Add framework-native error boundaries for routed surfaces and test the failure state.",
+      confidence: 0.65,
+    }));
+  }
+
+  const images = analyze("check_image_optimization", rootPath);
+  if (images && images.severity !== "pass") {
+    findings.push(createFinding({
+      kind: "frontend.image_optimization",
+      severity: images.severity || "P2",
+      evidence: `rawImgTags=${images.rawImgTags || 0}; nextImageUsage=${images.nextImageUsage || 0}; missingDimensions=${images.missingDimensions || 0}`,
+      rootCause: "Unoptimized or dimensionless images can hurt LCP and cause layout shifts.",
+      recommendedFix: "Use framework image components or explicit dimensions/lazy loading for non-critical images.",
+      confidence: 0.55,
+    }));
+  } else if (images && Number(images.missingDimensions || 0) > 0) {
+    findings.push(createFinding({
+      kind: "frontend.image_dimensions_missing",
+      severity: "P2",
+      evidence: `missingDimensions=${images.missingDimensions}`,
+      rootCause: "Images without stable dimensions can cause cumulative layout shift.",
+      recommendedFix: "Set width/height or reserve aspect-ratio boxes for rendered images.",
+      confidence: 0.65,
+    }));
+  }
+
+  const fonts = analyze("check_font_loading", rootPath);
+  if (fonts && fonts.severity !== "pass") {
+    findings.push(createFinding({
+      kind: "frontend.font_loading",
+      severity: fonts.severity || "P2",
+      evidence: `fontDisplayUsage=${fonts.fontDisplayUsage || 0}; googleFontsUsage=${fonts.googleFontsUsage || 0}`,
+      rootCause: "Remote fonts without font-display controls can block text rendering or shift layout.",
+      recommendedFix: "Use font-display swap/optional, preload critical fonts, or self-host critical font assets.",
+      confidence: 0.55,
+    }));
+  }
+
+  const css = analyze("check_css_health", rootPath);
+  if (css && css.severity !== "pass") {
+    findings.push(createFinding({
+      kind: "frontend.css_health",
+      severity: css.severity || "P2",
+      evidence: `importantCount=${css.importantCount || 0}; tailwindConfigured=${Boolean(css.tailwindConfigured)}`,
+      rootCause: "Large numbers of !important declarations make UI state and responsive overrides brittle.",
+      recommendedFix: "Refactor repeated overrides into component variants or ordered utility/style layers.",
+      confidence: 0.45,
+    }));
+  }
+
+  const testCoverage = analyze("find_test_coverage", rootPath);
+  if (testCoverage && Number(testCoverage.componentCount || 0) > 0 && Number(testCoverage.untestedCount || 0) > 0) {
+    findings.push(createFinding({
+      kind: "frontend.test_coverage_gap",
+      severity: Number(testCoverage.testCount || 0) === 0 ? "P2" : "P3",
+      evidence: `components=${testCoverage.componentCount}; tests=${testCoverage.testCount}; untested=${testCoverage.untestedCount}; ratio=${testCoverage.coverageRatio || "n/a"}`,
+      rootCause: "Interactive components without nearby tests are likely to regress without being caught pre-merge.",
+      recommendedFix: "Add component/unit tests for primary states and at least one integration smoke for the core route.",
+      confidence: 0.55,
+    }));
+  }
+
+  return dedupeFindings(findings);
+}
+
+export const FRONTEND_TOOLS = Object.freeze({
+  "frontend-analyze": {
+    id: "frontend-analyze",
+    scope: "repo",
+    description:
+      "Run Jules Tanaka's deterministic frontend analyzer once for the routed frontend surface and convert UI/UX, accessibility, runtime, and web-vital heuristics into Investor-DD findings.",
+    schema: {
+      type: "object",
+      properties: {
+        rootPath: { type: "string" },
+        files: { type: "array", items: { type: "string" } },
+      },
+    },
+    handler: runFrontendInvestorDdAnalyze,
+  },
+});
+
+export const FRONTEND_TOOL_IDS = Object.freeze(Object.keys(FRONTEND_TOOLS));

package/src/legacy-cli.js

@@ -1148,6 +1148,8 @@ async function runLocalOmarGateCommand(args) {
     const requireUsageLedger = hasCommandOption(args, "--require-usage-ledger");
     const model = getCommandOptionValue(args, "--model") || "gpt-5.3-codex";
     const provider = getCommandOptionValue(args, "--provider") || "sentinelayer";
+    const personaCsvFlag = getCommandOptionValue(args, "--persona") || "";
+    const skipPersonaCsvFlag = getCommandOptionValue(args, "--skip-persona") || "";
 
     const targetPath = path.resolve(process.cwd(), pathArg);
     if (!fs.existsSync(targetPath) || !fs.statSync(targetPath).isDirectory()) {
@@ -1155,6 +1157,11 @@ async function runLocalOmarGateCommand(args) {
     }
 
     const { runInvestorDd } = await import("./review/investor-dd-orchestrator.js");
+    const { parsePersonaCsv, resolveFilteredPersonas } = await import("./review/scan-modes.js");
+    const personaFilter = resolveFilteredPersonas("full-depth", {
+      includeOnly: parsePersonaCsv(personaCsvFlag),
+      skipPersonas: parsePersonaCsv(skipPersonaCsvFlag),
+    });
     const reportEmailClient = emailOnComplete
       ? await import("./review/dd-report-email-client.js")
       : null;
@@ -1164,12 +1171,20 @@ async function runLocalOmarGateCommand(args) {
       printInfo(
         `Budget: $${maxCostUsd.toFixed(2)} / ${maxRuntimeMinutes}min / ${maxParallel} parallel`,
       );
+      printInfo(`Personas: ${personaFilter.personas.join(", ")}`);
+      if (personaFilter.unknown.length > 0) {
+        printInfo(`Unknown persona IDs ignored: ${personaFilter.unknown.join(", ")}`);
+      }
+      if (personaFilter.dropped.length > 0) {
+        printInfo(`Skipped personas: ${personaFilter.dropped.join(", ")}`);
+      }
       if (dryRun) printInfo("Mode: dry-run (plan + stub report only)");
     }
     const result = await runInvestorDd({
       rootPath: targetPath,
       outputDir: outputDirArg,
       budgetOptions: { maxCostUsd, maxRuntimeMinutes, maxParallel },
+      personas: personaFilter.personas,
       dryRun,
       devTestBot: {
         enabled: devTestBotEnabled,
@@ -2420,6 +2435,80 @@ jobs:
           echo "- run_id: \\\`\${{ steps.omar.outputs.run_id }}\\\`" >> "\$GITHUB_STEP_SUMMARY"
           echo "- gate_status: \\\`\${{ steps.omar.outputs.gate_status }}\\\`" >> "\$GITHUB_STEP_SUMMARY"
           echo "- findings: P0=\${{ steps.omar.outputs.p0_count }} P1=\${{ steps.omar.outputs.p1_count }} P2=\${{ steps.omar.outputs.p2_count }} P3=\${{ steps.omar.outputs.p3_count }}" >> "\$GITHUB_STEP_SUMMARY"
+      - name: Stage Omar summary artifact
+        shell: bash
+        env:
+          OMAR_RUN_ID: \${{ steps.omar.outputs.run_id || '' }}
+          OMAR_GATE_STATUS: \${{ steps.omar.outputs.gate_status || '' }}
+          OMAR_P0: \${{ steps.omar.outputs.p0_count || '0' }}
+          OMAR_P1: \${{ steps.omar.outputs.p1_count || '0' }}
+          OMAR_P2: \${{ steps.omar.outputs.p2_count || '0' }}
+          OMAR_P3: \${{ steps.omar.outputs.p3_count || '0' }}
+          OMAR_SCAN_MODE: \${{ github.event_name == 'workflow_dispatch' && inputs.scan_mode || 'deep' }}
+          OMAR_SEVERITY_GATE: \${{ github.event_name == 'workflow_dispatch' && inputs.severity_gate || 'P1' }}
+          OMAR_P2_MAX_ALLOWED: \${{ github.event_name == 'workflow_dispatch' && inputs.p2_max_allowed || '5' }}
+        run: |
+          set -euo pipefail
+          mkdir -p omar-artifacts
+          python3 - <<'PY'
+          import json
+          import os
+          from pathlib import Path
+
+          def env(name, default=""):
+              return os.environ.get(name, default)
+
+          def int_env(name):
+              value = env(name, "0").strip()
+              return int(value) if value.isdigit() else 0
+
+          github_run_id = env("GITHUB_RUN_ID")
+          server_url = env("GITHUB_SERVER_URL", "https://github.com").rstrip("/")
+          repository = env("GITHUB_REPOSITORY")
+          run_url = f"{server_url}/{repository}/actions/runs/{github_run_id}" if repository and github_run_id else ""
+          summary = {
+              "schema_version": 1,
+              "kind": "omar_gate_summary",
+              "run_id": env("OMAR_RUN_ID"),
+              "gate_status": env("OMAR_GATE_STATUS"),
+              "findings": {
+                  "P0": int_env("OMAR_P0"),
+                  "P1": int_env("OMAR_P1"),
+                  "P2": int_env("OMAR_P2"),
+                  "P3": int_env("OMAR_P3"),
+              },
+              "threshold": {
+                  "severity_gate": env("OMAR_SEVERITY_GATE", "P1"),
+                  "p2_max_allowed": int_env("OMAR_P2_MAX_ALLOWED"),
+              },
+              "scan": {
+                  "mode": env("OMAR_SCAN_MODE", "deep"),
+                  "action_ref": "mrrCarter/sentinelayer-v1-action@03d7369cba7de2e9f15b959275c982111f0ee493",
+                  "managed_llm": False,
+                  "llm_failure_policy": "block",
+              },
+              "github": {
+                  "repository": repository,
+                  "sha": env("GITHUB_SHA"),
+                  "ref": env("GITHUB_REF"),
+                  "event_name": env("GITHUB_EVENT_NAME"),
+                  "workflow": env("GITHUB_WORKFLOW"),
+                  "run_id": github_run_id,
+                  "run_attempt": env("GITHUB_RUN_ATTEMPT"),
+                  "run_url": run_url,
+              },
+          }
+          Path("omar-artifacts/summary.json").write_text(
+              json.dumps(summary, indent=2, sort_keys=True) + "\n",
+              encoding="utf-8",
+          )
+          PY
+      - name: Upload Omar summary artifact
+        uses: actions/upload-artifact@50769540e7f4bd5e21e526ee35c689e35e0d6874
+        with:
+          name: omar-gate-artifacts
+          path: omar-artifacts/summary.json
+          if-no-files-found: error
 `;
 }
 

package/src/review/investor-dd-orchestrator.js

@@ -41,21 +41,9 @@ import { renderInvestorDdHtml } from "./investor-dd-html-report.js";
 import { runDevTestBotPhase } from "./investor-dd-devtestbot.js";
 import { redactDdEmailError } from "./dd-report-email-client.js";
 import { buildInvestorDdProgress } from "./investor-dd-progress.js";
+import { FULL_DEPTH_PERSONAS } from "./scan-modes.js";
 
-const INVESTOR_DD_PERSONAS = Object.freeze([
-  "security",
-  "backend",
-  "code-quality",
-  "testing",
-  "data-layer",
-  "reliability",
-  "release",
-  "observability",
-  "infrastructure",
-  "supply-chain",
-  "documentation",
-  "ai-governance",
-]);
+const INVESTOR_DD_PERSONAS = Object.freeze([...FULL_DEPTH_PERSONAS]);
 
 /**
  * Walk the target repo and return a list of relative POSIX file paths.
@@ -148,7 +136,10 @@ function buildSummaryMarkdown({ runId, summary, routing, byPersona }) {
   lines.push("");
   lines.push("| Persona | Files routed | Files visited | Findings |");
   lines.push("|---|---:|---:|---:|");
-  for (const personaId of INVESTOR_DD_PERSONAS) {
+  const reportPersonas = Array.isArray(summary.personas) && summary.personas.length > 0
+    ? summary.personas
+    : INVESTOR_DD_PERSONAS;
+  for (const personaId of reportPersonas) {
     const record = byPersona[personaId] || {};
     const routed = (routing[personaId] || []).length;
     const visited = Array.isArray(record.visited) ? record.visited.length : 0;
@@ -264,7 +255,7 @@ async function triggerReportEmail({ reportEmail, runResult, dryRun, emit }) {
  * @param {string} params.rootPath
  * @param {string} [params.outputDir]            - Defaults to `<rootPath>/.sentinelayer/runs/<runId>`.
  * @param {object} [params.budgetOptions]        - Overrides from CLI: { maxUsd, maxRuntimeMinutes, maxParallel }.
- * @param {string[]} [params.personas]           - Override persona list; defaults to all 12.
+ * @param {string[]} [params.personas]           - Override persona list; defaults to all 13.
  * @param {Function} [params.onEvent]            - Extra event sink (NDJSON stream is always written).
  * @param {boolean} [params.dryRun]              - If true, skip tool execution, emit plan.json + stub report only.
  * @param {string[]|null} [params.compliancePacks]  - Compliance pack IDs to run (default: all seven).

package/src/review/investor-dd-persona-runner.js

@@ -1,9 +1,9 @@
 /**
  * Unified per-persona runner for investor-DD (#investor-dd-4..15).
  *
- * Wires the 12 domain personas (security, backend, code-quality, testing,
+ * Wires the 13 domain personas (security, backend, code-quality, testing,
  * data-layer, reliability, release, observability, infrastructure,
- * supply-chain, documentation, ai-governance) into the per-file review
+ * supply-chain, frontend, documentation, ai-governance) into the review
  * loop. Each persona dispatches its declared domain tools against every
  * file the router assigns to it, collects findings, and returns a
  * per-persona coverage proof.
@@ -12,9 +12,8 @@
  * (LLM-driven) layer sits on top in a later PR. Determinism is the
  * investor-DD ground-truth floor; the LLM layer is additive.
  *
- * Frontend (Jules) is excluded here because Jules has its own bespoke
- * envelope with live-web validation; PR-25 routes Jules into investor-DD
- * via a dedicated live-validator dispatcher.
+ * Repo-scoped tools such as Jules' frontend analyzer run once per persona
+ * with the full routed file set; file-scoped tools retain the per-file loop.
  */
 
 import { AI_GOVERNANCE_TOOLS } from "../agents/ai-governance/tools/index.js";
@@ -29,11 +28,12 @@ import { RELIABILITY_TOOLS } from "../agents/reliability/tools/index.js";
 import { SECURITY_TOOLS } from "../agents/security/tools/index.js";
 import { SUPPLY_CHAIN_TOOLS } from "../agents/supply-chain/tools/index.js";
 import { TESTING_TOOLS } from "../agents/testing/tools/index.js";
+import { FRONTEND_TOOLS } from "../agents/jules/tools/investor-dd.js";
 
 import { checkBudget, createBudgetState } from "./investor-dd-file-loop.js";
 
 /**
- * Registry of persona → tool map. Frontend handled separately via Jules.
+ * Registry of persona → tool map.
  */
 export const INVESTOR_DD_PERSONA_TOOL_REGISTRY = Object.freeze({
   security: SECURITY_TOOLS,
@@ -46,6 +46,7 @@ export const INVESTOR_DD_PERSONA_TOOL_REGISTRY = Object.freeze({
   observability: OBSERVABILITY_TOOLS,
   infrastructure: INFRASTRUCTURE_TOOLS,
   "supply-chain": SUPPLY_CHAIN_TOOLS,
+  frontend: FRONTEND_TOOLS,
   documentation: DOCUMENTATION_TOOLS,
   "ai-governance": AI_GOVERNANCE_TOOLS,
 });
@@ -66,31 +67,15 @@ export function getPersonaTools(personaId) {
   return Object.values(map);
 }
 
-/**
- * Dispatch every tool for the persona against a single file scope. Each
- * tool handler is invoked with `{ rootPath, files: [file] }` because
- * every persona's tool contract accepts this shape (see #A13-#A22).
- *
- * @param {object} params
- * @param {string} params.personaId
- * @param {string} params.file            - Single file (relative to rootPath).
- * @param {string} params.rootPath        - Repo root.
- * @param {object} params.budget          - Shared budget state.
- * @param {Function} [params.onEvent]
- * @returns {Promise<{findings: Array, toolInvocations: Array, stoppedEarly: boolean}>}
- */
-export async function runPersonaOnFile({
+async function runTools({
   personaId,
   file,
+  files = null,
   rootPath,
   budget,
+  tools,
   onEvent = () => {},
 } = {}) {
-  if (!personaId) throw new TypeError("runPersonaOnFile requires personaId");
-  if (!file) throw new TypeError("runPersonaOnFile requires file");
-  if (!rootPath) throw new TypeError("runPersonaOnFile requires rootPath");
-
-  const tools = getPersonaTools(personaId);
   const findings = [];
   const toolInvocations = [];
   let stoppedEarly = false;
@@ -112,7 +97,7 @@ export async function runPersonaOnFile({
     onEvent({ type: "persona_file_tool_call", personaId, file, tool: tool.id });
 
     try {
-      const results = await tool.handler({ rootPath, files: [file] });
+      const results = await tool.handler({ rootPath, files: Array.isArray(files) ? files : [file] });
       if (budget) budget.toolCalls = (budget.toolCalls || 0) + 1;
       const normalized = Array.isArray(results) ? results : [];
       for (const f of normalized) {
@@ -142,6 +127,40 @@ export async function runPersonaOnFile({
   return { findings, toolInvocations, stoppedEarly };
 }
 
+/**
+ * Dispatch every tool for the persona against a single file scope. Each
+ * tool handler is invoked with `{ rootPath, files: [file] }` because
+ * every persona's tool contract accepts this shape (see #A13-#A22).
+ *
+ * @param {object} params
+ * @param {string} params.personaId
+ * @param {string} params.file            - Single file (relative to rootPath).
+ * @param {string} params.rootPath        - Repo root.
+ * @param {object} params.budget          - Shared budget state.
+ * @param {Function} [params.onEvent]
+ * @returns {Promise<{findings: Array, toolInvocations: Array, stoppedEarly: boolean}>}
+ */
+export async function runPersonaOnFile({
+  personaId,
+  file,
+  rootPath,
+  budget,
+  onEvent = () => {},
+} = {}) {
+  if (!personaId) throw new TypeError("runPersonaOnFile requires personaId");
+  if (!file) throw new TypeError("runPersonaOnFile requires file");
+  if (!rootPath) throw new TypeError("runPersonaOnFile requires rootPath");
+
+  return runTools({
+    personaId,
+    file,
+    rootPath,
+    budget,
+    tools: getPersonaTools(personaId),
+    onEvent,
+  });
+}
+
 /**
  * Run a single persona across its assigned files in the router output.
  *
@@ -167,6 +186,50 @@ export async function runPersonaAcrossFiles({
   const visited = [];
   const skipped = [];
   let terminationReason = "ok";
+  const tools = getPersonaTools(personaId);
+  const repoScopedTools = tools.filter((tool) => tool.scope === "repo");
+  const fileScopedTools = tools.filter((tool) => tool.scope !== "repo");
+
+  if (repoScopedTools.length > 0) {
+    const budgetCheck = checkBudget(safeBudget);
+    if (!budgetCheck.ok) {
+      terminationReason = budgetCheck.reason;
+      skipped.push(...files);
+      onEvent({ type: "persona_file_skipped", personaId, file: "__repo__", stopReason: budgetCheck.reason });
+    } else {
+      onEvent({ type: "persona_file_start", personaId, file: "__repo__", fileCount: files.length });
+      const { findings, toolInvocations, stoppedEarly } = await runTools({
+        personaId,
+        file: "__repo__",
+        files,
+        rootPath,
+        budget: safeBudget,
+        tools: repoScopedTools,
+        onEvent,
+      });
+      perFile.push({ file: "__repo__", scope: "repo", files, findings, toolInvocations, stoppedEarly });
+      allFindings.push(...findings);
+      visited.push(...files);
+      onEvent({
+        type: "persona_file_complete",
+        personaId,
+        file: "__repo__",
+        findingCount: findings.length,
+        toolCount: toolInvocations.length,
+      });
+    }
+  }
+
+  if (fileScopedTools.length === 0) {
+    return {
+      personaId,
+      perFile,
+      findings: allFindings,
+      visited,
+      skipped,
+      terminationReason,
+    };
+  }
 
   for (const file of files) {
     const budgetCheck = checkBudget(safeBudget);
@@ -178,11 +241,12 @@ export async function runPersonaAcrossFiles({
     }
 
     onEvent({ type: "persona_file_start", personaId, file });
-    const { findings, toolInvocations, stoppedEarly } = await runPersonaOnFile({
+    const { findings, toolInvocations, stoppedEarly } = await runTools({
       personaId,
       file,
       rootPath,
       budget: safeBudget,
+      tools: fileScopedTools,
       onEvent,
     });
     perFile.push({ file, findings, toolInvocations, stoppedEarly });

package/src/review/investor-dd-progress.js

@@ -1,20 +1,8 @@
+import { FULL_DEPTH_PERSONAS } from "./scan-modes.js";
+
 export const INVESTOR_DD_PROGRESS_VERSION = "investor_dd_progress_v1";
 
-export const INVESTOR_DD_EXPECTED_PERSONAS = Object.freeze([
-  "security",
-  "backend",
-  "code-quality",
-  "testing",
-  "data-layer",
-  "reliability",
-  "release",
-  "observability",
-  "infrastructure",
-  "supply-chain",
-  "documentation",
-  "ai-governance",
-  "frontend",
-]);
+export const INVESTOR_DD_EXPECTED_PERSONAS = Object.freeze([...FULL_DEPTH_PERSONAS]);
 
 const REQUIRED_FOR_SELLABLE = Object.freeze([
   "persona_roster",
@@ -335,17 +323,15 @@ export function buildInvestorDdProgress({
       ),
     },
     findingCount: Array.isArray(findings) ? findings.length : 0,
-    nextRecommendedSlices: byId(capabilities, "persona_roster")?.status === "complete"
-      ? [
-          "wire Senti session id and live usage counters into Investor-DD runs",
-          "add per-agent token/time/LOC/customer-price/margin telemetry",
-          "require live reconciliation and report-email proof for sellable DD closeout",
-        ]
-      : [
-          "add the missing frontend/Jules persona to the default Investor-DD roster",
-          "wire Senti session id and live usage counters into Investor-DD runs",
-          "add per-agent token/time/LOC/customer-price/margin telemetry",
-          "require live reconciliation and report-email proof for sellable DD closeout",
-        ],
+    nextRecommendedSlices: [
+      ...(byId(capabilities, "persona_roster")?.status === "complete"
+        ? []
+        : missingPersonas.includes("frontend")
+          ? ["add the missing frontend/Jules persona to the default Investor-DD roster"]
+          : ["run the full 13-persona roster before claiming sellable DD coverage"]),
+      "wire Senti session id and live usage counters into Investor-DD runs",
+      "add per-agent token/time/LOC/customer-price/margin telemetry",
+      "require live reconciliation and report-email proof for sellable DD closeout",
+    ],
   };
 }

package/src/review/scan-modes.js

@@ -34,7 +34,7 @@
 //   frontend / observability / reliability.
 // - "compliance" — cross-cutting; distributed across security / ai-governance /
 //   supply-chain / infrastructure / documentation via subagent dispatch.
-const FULL_DEPTH_PERSONAS = [
+export const FULL_DEPTH_PERSONAS = Object.freeze([
   "security",
   "backend",
   "code-quality",
@@ -48,7 +48,7 @@ const FULL_DEPTH_PERSONAS = [
   "frontend",
   "documentation",
   "ai-governance",
-];
+]);
 
 const SCAN_MODES = {
   baseline: ["security"],

package/src/scan/generator.js

@@ -8,6 +8,7 @@ export const SUPPORTED_PLAYWRIGHT_MODES = Object.freeze(["auto", "off", "baselin
 
 const CHECKOUT_ACTION_REF = "actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683";
 const SETUP_NODE_ACTION_REF = "actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020";
+const UPLOAD_ARTIFACT_ACTION_REF = "actions/upload-artifact@50769540e7f4bd5e21e526ee35c689e35e0d6874";
 const SECRET_NAME_REGEX = /^[A-Z][A-Z0-9_]*$/;
 const REPO_SLUG_REGEX = /^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$/;
 
@@ -274,6 +275,84 @@ export function buildSecurityReviewWorkflow({ secretName = DEFAULT_SCAN_SECRET_N
               'echo "- findings: P0=${{ steps.omar.outputs.p0_count }} P1=${{ steps.omar.outputs.p1_count }} P2=${{ steps.omar.outputs.p2_count }} P3=${{ steps.omar.outputs.p3_count }}" >> "$GITHUB_STEP_SUMMARY"',
             ].join("\n"),
           },
+          {
+            name: "Stage Omar summary artifact",
+            shell: "bash",
+            env: {
+              OMAR_RUN_ID: "${{ steps.omar.outputs.run_id || '' }}",
+              OMAR_GATE_STATUS: "${{ steps.omar.outputs.gate_status || '' }}",
+              OMAR_P0: "${{ steps.omar.outputs.p0_count || '0' }}",
+              OMAR_P1: "${{ steps.omar.outputs.p1_count || '0' }}",
+              OMAR_P2: "${{ steps.omar.outputs.p2_count || '0' }}",
+              OMAR_P3: "${{ steps.omar.outputs.p3_count || '0' }}",
+              OMAR_SCAN_MODE: "${{ github.event_name == 'workflow_dispatch' && inputs.scan_mode || 'deep' }}",
+              OMAR_SEVERITY_GATE: "${{ github.event_name == 'workflow_dispatch' && inputs.severity_gate || 'P1' }}",
+              OMAR_P2_MAX_ALLOWED: "${{ github.event_name == 'workflow_dispatch' && inputs.p2_max_allowed || '5' }}",
+            },
+            run: [
+              "set -euo pipefail",
+              "mkdir -p omar-artifacts",
+              "python3 - <<'PY'",
+              "import json",
+              "import os",
+              "from pathlib import Path",
+              "",
+              "def env(name, default=''):",
+              "    return os.environ.get(name, default)",
+              "",
+              "def int_env(name):",
+              "    value = env(name, '0').strip()",
+              "    return int(value) if value.isdigit() else 0",
+              "",
+              "github_run_id = env('GITHUB_RUN_ID')",
+              "server_url = env('GITHUB_SERVER_URL', 'https://github.com').rstrip('/')",
+              "repository = env('GITHUB_REPOSITORY')",
+              "run_url = f'{server_url}/{repository}/actions/runs/{github_run_id}' if repository and github_run_id else ''",
+              "summary = {",
+              "    'schema_version': 1,",
+              "    'kind': 'omar_gate_summary',",
+              "    'run_id': env('OMAR_RUN_ID'),",
+              "    'gate_status': env('OMAR_GATE_STATUS'),",
+              "    'findings': {",
+              "        'P0': int_env('OMAR_P0'),",
+              "        'P1': int_env('OMAR_P1'),",
+              "        'P2': int_env('OMAR_P2'),",
+              "        'P3': int_env('OMAR_P3'),",
+              "    },",
+              "    'threshold': {",
+              "        'severity_gate': env('OMAR_SEVERITY_GATE', 'P1'),",
+              "        'p2_max_allowed': int_env('OMAR_P2_MAX_ALLOWED'),",
+              "    },",
+              "    'scan': {",
+              "        'mode': env('OMAR_SCAN_MODE', 'deep'),",
+              `        'action_ref': '${SENTINELAYER_ACTION_REF}',`,
+              "        'managed_llm': False,",
+              "        'llm_failure_policy': 'block',",
+              "    },",
+              "    'github': {",
+              "        'repository': repository,",
+              "        'sha': env('GITHUB_SHA'),",
+              "        'ref': env('GITHUB_REF'),",
+              "        'event_name': env('GITHUB_EVENT_NAME'),",
+              "        'workflow': env('GITHUB_WORKFLOW'),",
+              "        'run_id': github_run_id,",
+              "        'run_attempt': env('GITHUB_RUN_ATTEMPT'),",
+              "        'run_url': run_url,",
+              "    },",
+              "}",
+              "Path('omar-artifacts/summary.json').write_text(json.dumps(summary, indent=2, sort_keys=True) + '\\n', encoding='utf-8')",
+              "PY",
+            ].join("\n"),
+          },
+          {
+            name: "Upload Omar summary artifact",
+            uses: UPLOAD_ARTIFACT_ACTION_REF,
+            with: {
+              name: "omar-gate-artifacts",
+              path: "omar-artifacts/summary.json",
+              "if-no-files-found": "error",
+            },
+          },
         ],
       },
     },