sentinelayer-cli 0.26.0 → 0.27.0

package/package.json

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

package/src/commands/legacy-args.js

@@ -58,6 +58,9 @@ export function buildLegacyArgs(baseArgs, { commandOptions = {}, command } = {})
   appendPassthroughFlag(args, "--model", commandOptions.model);
   appendPassthroughFlag(args, "--provider", commandOptions.provider);
   appendPassthroughFlag(args, "--reuse-omargate", commandOptions.reuseOmargate);
+  appendPassthroughFlag(args, "--scope-mode", commandOptions.scopeMode);
+  appendBooleanFlag(args, "--diff", commandOptions.diff);
+  appendBooleanFlag(args, "--staged", commandOptions.staged);
   appendPassthroughFlag(args, "--notify-email", commandOptions.notifyEmail);
   appendPassthroughFlag(args, "--email-on-complete", commandOptions.emailOnComplete);
   appendPassthroughFlag(args, "--notify-session", commandOptions.notifySession);

package/src/commands/omargate.js

@@ -12,6 +12,9 @@ export function registerOmarGateCommand(program, invokeLegacy) {
     .option("--output-dir <path>", "Artifact root for report output")
     .option("--no-ai", "Skip AI review layer (deterministic only)")
     .option("--ai-dry-run", "Run AI layer in dry-run mode (no LLM call)")
+    .option("--scope-mode <mode>", "Deterministic file scope: full, diff, or staged")
+    .option("--diff", "Alias for --scope-mode diff")
+    .option("--staged", "Alias for --scope-mode staged")
     .option("--scan-mode <mode>", "Scan depth: baseline (1 persona), deep (13), full-depth (13)")
     .option("--max-parallel <n>", "Max concurrent persona calls (default: 4)")
     .option("--model <id>", "LLM model override (default: gpt-5.3-codex)")

package/src/legacy-cli.js

@@ -847,6 +847,33 @@ function hasCommandOption(args, optionName) {
   return args.some((arg) => String(arg || "").trim() === optionName);
 }
 
+function resolveScopeModeFromOptions(args, { defaultMode = "full" } = {}) {
+  const explicitMode = String(getCommandOptionValue(args, "--scope-mode") || "").trim().toLowerCase();
+  const diffFlag = hasCommandOption(args, "--diff");
+  const stagedFlag = hasCommandOption(args, "--staged");
+
+  if (diffFlag && stagedFlag) {
+    throw new Error("Use only one of --diff or --staged.");
+  }
+
+  let modeFromFlags = "";
+  if (diffFlag) {
+    modeFromFlags = "diff";
+  } else if (stagedFlag) {
+    modeFromFlags = "staged";
+  }
+
+  if (explicitMode && modeFromFlags && explicitMode !== modeFromFlags) {
+    throw new Error(`Conflicting scope selection: --scope-mode ${explicitMode} with --${modeFromFlags}.`);
+  }
+
+  const resolved = explicitMode || modeFromFlags || defaultMode;
+  if (!["full", "diff", "staged"].includes(resolved)) {
+    throw new Error("scope mode must be one of: full, diff, staged.");
+  }
+  return resolved;
+}
+
 async function collectScanFiles(rootPath) {
   const files = [];
   const stack = [rootPath];
@@ -1237,6 +1264,7 @@ async function runLocalOmarGateCommand(args) {
   const asJson = hasCommandOption(args, "--json");
   const pathArg = getCommandOptionValue(args, "--path") || ".";
   const outputDirArg = getCommandOptionValue(args, "--output-dir") || "";
+  const scopeMode = resolveScopeModeFromOptions(args, { defaultMode: "full" });
   const aiEnabled = !hasCommandOption(args, "--no-ai");
   const aiDryRun = hasCommandOption(args, "--ai-dry-run");
   const maxCostUsd = parseFloat(getCommandOptionValue(args, "--max-cost") || "5.0") || 5.0;
@@ -1261,6 +1289,7 @@ async function runLocalOmarGateCommand(args) {
   if (!asJson) {
     printSection("Local Omar Gate Deep");
     printInfo(`Target: ${targetPath}`);
+    printInfo(`Scope mode: ${scopeMode}`);
     printInfo(`Scan mode: ${scanMode} | AI: ${aiEnabled ? "enabled" : "disabled"}`);
     console.error("");
     console.error(pc.gray(`  [${formatElapsed(Date.now() - commandStartedAt)}] Phase 1: Deterministic analysis (22 rules)...`));
@@ -1270,13 +1299,17 @@ async function runLocalOmarGateCommand(args) {
   const { runDeterministicReviewPipeline } = await import("./review/local-review.js");
   const deterministic = await runDeterministicReviewPipeline({
     targetPath,
-    mode: "full",
+    mode: scopeMode,
     outputDir: outputDirArg,
   });
 
   const detFindings = deterministic.findings || [];
   const detSummary = deterministic.summary || { P0: 0, P1: 0, P2: 0, P3: 0, blocking: false };
-  const scannedFiles = deterministic.metadata?.ingest?.filesScanned || deterministic.metadata?.scannedFiles || detFindings.length;
+  const scannedFiles =
+    deterministic.scope?.scannedFiles ??
+    deterministic.metadata?.ingest?.filesScanned ??
+    deterministic.metadata?.scannedFiles ??
+    detFindings.length;
 
   if (!asJson) {
     console.error(`  ${pc.green("✓")} [${formatElapsed(Date.now() - commandStartedAt)}] Deterministic: ${scannedFiles} files → P1=${detSummary.P1} P2=${detSummary.P2} findings`);
@@ -1312,6 +1345,7 @@ async function runLocalOmarGateCommand(args) {
         deterministic: {
           summary: detSummary,
           findings: detFindings,
+          mode: deterministic.mode || scopeMode,
           scope: deterministic.scope || {},
           layers: deterministic.layers || {},
           metadata: deterministic.metadata || {},
@@ -1430,6 +1464,8 @@ async function runLocalOmarGateCommand(args) {
       runId: orchestratorResult.runId,
       mode: orchestratorResult.mode,
       roster: orchestratorResult.roster,
+      basePersonas: orchestratorResult.basePersonas || [],
+      personaRouting: orchestratorResult.personaRouting || null,
       findings: (orchestratorResult.personas || []).flatMap((p) => []),
       aiFindings: aiFindings,
       personaCount: (orchestratorResult.personas || []).length,
@@ -1445,6 +1481,7 @@ async function runLocalOmarGateCommand(args) {
       findings: orchestratorResult.findings || [],
       summary: orchestratorResult.summary,
       reconciliation: orchestratorResult.reconciliation,
+      personaRouting: orchestratorResult.personaRouting || null,
       findingsBySource: orchestratorResult.findingsBySource,
     });
   }
@@ -1461,6 +1498,8 @@ Elapsed: ${totalElapsed}
 
 Summary:
 - Files scanned: ${scannedFiles}
+- Scope mode: ${scopeMode}
+- Persona routing: ${orchestratorResult?.personaRouting?.enabled ? `${orchestratorResult.personaRouting.effectivePersonas.length}/${orchestratorResult.personaRouting.basePersonas.length} personas for ${orchestratorResult.personaRouting.changedFileCount} changed files` : "full roster"}
 - Deterministic findings: P0=${detSummary.P0} P1=${detSummary.P1} P2=${detSummary.P2} P3=${detSummary.P3 || 0}
 - AI findings (raw, pre-reconciliation): ${aiResult ? `P0=${aiResult.summary?.P0 || 0} P1=${aiResult.summary?.P1 || 0} P2=${aiResult.summary?.P2 || 0} P3=${aiResult.summary?.P3 || 0}` : "skipped"}
 - Reconciled (deduped + confidence-boosted): P0=${combinedP0} P1=${combinedP1} P2=${combinedP2} P3=${combinedP3}
@@ -1494,6 +1533,8 @@ ${formatFindingsMarkdown(allFindings)}
           targetPath,
           runId: omargateRunId,
           reportPath,
+          scopeMode,
+          scopedFiles: deterministic.scope?.scannedRelativeFiles || [],
           scannedFiles,
           p0: combinedP0,
           p1: combinedP1,
@@ -1518,6 +1559,8 @@ ${formatFindingsMarkdown(allFindings)}
               }
             : null,
           reconciliation: orchestratorResult?.reconciliation || null,
+          personaRouting: orchestratorResult?.personaRouting || null,
+          basePersonas: orchestratorResult?.basePersonas || [],
           roster: orchestratorResult?.roster || [],
         },
         null,

package/src/review/omargate-orchestrator.js

@@ -15,6 +15,7 @@ import { reconcileReviewFindings } from "./report.js";
 import { resolvePersonaVisual } from "../agents/persona-visuals.js";
 import { syncRunToDashboard } from "../telemetry/sync.js";
 import { createAgentEvent } from "../events/schema.js";
+import { buildOwnershipMap, computeRoutingStats, loadScaffoldConfig } from "../ingest/ownership.js";
 
 const OMAR_ORCHESTRATOR_AGENT = Object.freeze({
   id: "omar-orchestrator",
@@ -98,6 +99,158 @@ function uniqueScopeFiles(files = []) {
   return normalized;
 }
 
+function normalizeScopeMode(value) {
+  const normalized = normalizeString(value).toLowerCase();
+  if (normalized === "diff" || normalized === "staged") {
+    return normalized;
+  }
+  return "full";
+}
+
+function findingRelativePath(finding = {}) {
+  return toPosixPath(finding.file || finding.path || finding.location || "");
+}
+
+function summarizeDeterministicFindings(findings = []) {
+  return summarizeFindings(findings);
+}
+
+function buildScopeForFiles(scope = {}, files = []) {
+  const wanted = new Set(files.map((file) => toPosixPath(file)));
+  const scopedObjects = filesFromScope(scope).filter((file) => wanted.has(file.path));
+  const scopedFiles =
+    scopedObjects.length > 0
+      ? scopedObjects
+      : files.map((filePath) => ({ path: toPosixPath(filePath), loc: 0 }));
+  const totalLoc = scopedFiles.reduce((sum, file) => sum + (file.loc > 0 ? file.loc : 80), 0);
+  return {
+    ...scope,
+    files: scopedFiles,
+    primary: scopedFiles,
+    scannedFiles: files.length,
+    scannedRelativeFiles: files,
+    totalLoc,
+    estimatedLoc: totalLoc,
+  };
+}
+
+function buildPersonaScopedDeterministic(deterministic = {}, personaId, personaRouting = {}) {
+  if (!personaRouting?.enabled) {
+    return deterministic;
+  }
+  const files = Array.isArray(personaRouting.filesByPersona?.[personaId])
+    ? personaRouting.filesByPersona[personaId]
+    : [];
+  const wanted = new Set(files);
+  const findings = (deterministic?.findings || []).filter((finding) =>
+    wanted.has(findingRelativePath(finding))
+  );
+  const summary = summarizeDeterministicFindings(findings);
+  return {
+    ...deterministic,
+    summary,
+    findings,
+    scope: buildScopeForFiles(deterministic?.scope || {}, files),
+    metadata: {
+      ...(deterministic?.metadata || {}),
+      personaRouting: {
+        enabled: true,
+        scopeMode: personaRouting.scopeMode,
+        personaId,
+        scopedFiles: files.length,
+      },
+    },
+  };
+}
+
+async function resolveChangedFilePersonaRouting({
+  targetPath,
+  personas = [],
+  deterministic = {},
+  manualInclude = false,
+} = {}) {
+  const scopeMode = normalizeScopeMode(deterministic?.mode || deterministic?.metadata?.scopeMode);
+  const basePersonas = [...personas];
+  const base = {
+    enabled: false,
+    scopeMode,
+    reason: "full_scope",
+    basePersonas,
+    effectivePersonas: basePersonas,
+    droppedPersonas: [],
+    changedFileCount: 0,
+    personaCoverage: {},
+    tokenReductionEstimatePct: 0,
+    filesByPersona: {},
+    scaffold: { found: false },
+  };
+
+  if (scopeMode === "full") {
+    return base;
+  }
+  if (manualInclude) {
+    return {
+      ...base,
+      reason: "manual_persona_filter",
+    };
+  }
+
+  const scopedFiles = filesFromScope(deterministic?.scope || {})
+    .map((file) => file.path)
+    .filter(Boolean);
+  if (scopedFiles.length === 0) {
+    return {
+      ...base,
+      enabled: true,
+      reason: "no_changed_files",
+      effectivePersonas: [],
+      droppedPersonas: basePersonas,
+      changedFileCount: 0,
+    };
+  }
+
+  let scaffold = { found: false, ownershipRules: [] };
+  try {
+    scaffold = await loadScaffoldConfig({ targetPath });
+  } catch {
+    scaffold = { found: false, ownershipRules: [] };
+  }
+  const ownershipMap = buildOwnershipMap(scopedFiles, scaffold);
+  const stats = computeRoutingStats(ownershipMap);
+  const allowed = new Set(basePersonas);
+  const filesByPersona = {};
+  for (const [file, persona] of ownershipMap.entries()) {
+    if (!allowed.has(persona)) {
+      continue;
+    }
+    if (!filesByPersona[persona]) {
+      filesByPersona[persona] = [];
+    }
+    filesByPersona[persona].push(file);
+  }
+
+  for (const persona of Object.keys(filesByPersona)) {
+    filesByPersona[persona].sort((left, right) => left.localeCompare(right));
+  }
+
+  const effectivePersonas = basePersonas.filter((persona) => filesByPersona[persona]?.length > 0);
+  return {
+    ...base,
+    enabled: true,
+    reason: "changed_file_scope",
+    effectivePersonas,
+    droppedPersonas: basePersonas.filter((persona) => !effectivePersonas.includes(persona)),
+    changedFileCount: scopedFiles.length,
+    personaCoverage: stats.personaCoverage,
+    tokenReductionEstimatePct: stats.tokenReductionEstimatePct,
+    filesByPersona,
+    scaffold: {
+      found: Boolean(scaffold?.found),
+      ruleCount: Array.isArray(scaffold?.ownershipRules) ? scaffold.ownershipRules.length : 0,
+    },
+  };
+}
+
 function filesFromScope(scope = {}) {
   if (Array.isArray(scope.files)) {
     return uniqueScopeFiles(scope.files);
@@ -624,7 +777,7 @@ export async function runOmarGateOrchestrator({
       })
     : { ...resolveScanMode(scanMode), dropped: [], unknown: [] };
 
-  const { mode, personas } = resolved;
+  const { mode, personas: basePersonas } = resolved;
   const droppedPersonas = resolved.dropped || [];
   const unknownPersonas = resolved.unknown || [];
 
@@ -637,7 +790,28 @@ export async function runOmarGateOrchestrator({
         mode,
         dropped: droppedPersonas,
         unknown: unknownPersonas,
-        effective: personas,
+        effective: basePersonas,
+      },
+      runId,
+    }));
+  }
+
+  const personaRouting = await resolveChangedFilePersonaRouting({
+    targetPath,
+    personas: basePersonas,
+    deterministic,
+    manualInclude: Array.isArray(includeOnly) && includeOnly.length > 0,
+  });
+  const personas = personaRouting.effectivePersonas;
+
+  if (onEvent && personaRouting.enabled) {
+    onEvent(createAgentEvent({
+      event: "omargate_persona_routing",
+      agent: OMAR_ORCHESTRATOR_AGENT,
+      payload: {
+        runId,
+        mode,
+        routing: personaRouting,
       },
       runId,
     }));
@@ -659,7 +833,17 @@ export async function runOmarGateOrchestrator({
     onEvent(createAgentEvent({
       event: "omargate_start",
       agent: OMAR_ORCHESTRATOR_AGENT,
-      payload: { runId, mode, personas, roster, maxParallel, maxCostUsd, dryRun },
+      payload: {
+        runId,
+        mode,
+        personas,
+        basePersonas,
+        roster,
+        maxParallel,
+        maxCostUsd,
+        dryRun,
+        personaRouting,
+      },
       runId,
     }));
   }
@@ -667,8 +851,8 @@ export async function runOmarGateOrchestrator({
   const detSummary = deterministic?.summary || { P0: 0, P1: 0, P2: 0, P3: 0 };
   const detFindings = deterministic?.findings || [];
 
-  // Per-persona cost budget = global / persona count (with minimum floor)
-  const perPersonaCost = Math.max(0.25, maxCostUsd / personas.length);
+  // Per-persona cost budget = global / effective persona count (with minimum floor).
+  const perPersonaCost = personas.length > 0 ? Math.max(0.25, maxCostUsd / personas.length) : 0;
   let runningCostUsd = 0;
 
   const personaResults = await runWithConcurrency(personas, maxParallel, async (personaId) => {
@@ -711,6 +895,11 @@ export async function runOmarGateOrchestrator({
     }
 
     const personaStart = Date.now();
+    const personaDeterministic = buildPersonaScopedDeterministic(
+      deterministic,
+      personaId,
+      personaRouting
+    );
 
     if (onEvent) {
       onEvent(createAgentEvent({
@@ -735,7 +924,7 @@ export async function runOmarGateOrchestrator({
         targetPath,
         mode,
         runId,
-        deterministic,
+        deterministic: personaDeterministic,
         outputDir,
         provider,
         model,
@@ -788,7 +977,7 @@ export async function runOmarGateOrchestrator({
       const systemPrompt = buildPersonaReviewPrompt({
         personaId,
         targetPath,
-        deterministicSummary: detSummary,
+        deterministicSummary: personaDeterministic?.summary || detSummary,
       });
 
       const result = await runAiReviewLayer({
@@ -801,11 +990,11 @@ export async function runOmarGateOrchestrator({
           personaId
         ),
         deterministic: {
-          summary: detSummary,
-          findings: detFindings,
-          scope: deterministic?.scope || {},
-          layers: deterministic?.layers || {},
-          metadata: deterministic?.metadata || {},
+          summary: personaDeterministic?.summary || detSummary,
+          findings: personaDeterministic?.findings || detFindings,
+          scope: personaDeterministic?.scope || deterministic?.scope || {},
+          layers: personaDeterministic?.layers || deterministic?.layers || {},
+          metadata: personaDeterministic?.metadata || deterministic?.metadata || {},
         },
         outputDir,
         provider: provider || undefined,
@@ -982,7 +1171,9 @@ export async function runOmarGateOrchestrator({
   const result = {
     runId,
     mode,
+    basePersonas,
     roster,
+    personaRouting,
     personas: settled.map((r) => ({
       id: r.personaId,
       identity: r.persona,
@@ -1051,6 +1242,7 @@ export async function runOmarGateOrchestrator({
         findings: reconciledFindings.length,
         summary: result.summary,
         reconciliation: result.reconciliation,
+        personaRouting,
         totalCostUsd: totalCost,
         totalDurationMs: totalDuration,
       },