sentinelayer-cli 0.8.0 → 0.8.1

package/src/review/reconciliation-rules.js

@@ -0,0 +1,329 @@
+/**
+ * Reconciliation ruleset (#investor-dd-29).
+ *
+ * Cross-references source-level findings emitted by the persona runner
+ * with live-web observations captured by the live-validator (devTestBot
+ * via AIdenID). Each rule matches a (finding-pattern, live-observation-
+ * pattern) pair and assigns a verdict.
+ *
+ * Verdicts:
+ *   CONFIRMED       — source claim validated by live behavior (or code
+ *                     claim paired with consistent live observation).
+ *   FALSE_POSITIVE  — source flagged an issue, live behavior proves it
+ *                     is not actually broken in production.
+ *   CONTRADICTORY   — source claim and live observation actively
+ *                     disagree (rare; warrants human review).
+ *   UNVERIFIABLE    — no live observation covered this finding, or no
+ *                     rule matched the pair; reported as-is.
+ *
+ * Each rule is a pure function pair:
+ *   matchFinding(finding)       → bool    (source side)
+ *   matchObservation(observation, finding) → bool  (live side, may use
+ *                                 the finding context to match to a
+ *                                 specific interaction)
+ *
+ * Rules are intentionally declarative and small: the ruleset grows as
+ * new finding classes appear. The engine (PR-28) walks rules in order
+ * and picks the first verdict.
+ */
+
+/**
+ * @typedef {object} Finding
+ * @property {string} [kind]       - e.g., "sast.eval", "authz.missing-guard".
+ * @property {string} [severity]
+ * @property {string} [file]
+ * @property {number} [line]
+ * @property {string} [personaId]
+ * @property {string} [evidence]
+ * @property {string} [recommendedFix]
+ */
+
+/**
+ * @typedef {object} LiveObservation
+ * @property {string} interactionId        - UUID for the clicked button/form/nav.
+ * @property {string} [elementLabel]
+ * @property {string} [sourceFile]         - File that declared the element (if static extract worked).
+ * @property {number} [statusCodeObserved]
+ * @property {string[]} [consoleErrors]
+ * @property {Array<object>} [networkErrors]
+ * @property {boolean} [navigated]
+ * @property {string} [observedBehavior]   - Free-form summary from the recorder.
+ * @property {object} [payload]            - Request/response summary when relevant.
+ */
+
+/**
+ * @typedef {object} ReconciliationVerdict
+ * @property {"CONFIRMED" | "FALSE_POSITIVE" | "CONTRADICTORY" | "UNVERIFIABLE"} verdict
+ * @property {string} ruleId
+ * @property {number} confidence           - 0.0-1.0
+ * @property {string} [reason]
+ */
+
+const RULES = Object.freeze([
+  // CONTRADICTORY rules MUST come before CONFIRMED/FALSE_POSITIVE rules
+  // for the same finding kind — they capture the ambiguity that the
+  // simpler rules would otherwise collapse in the wrong direction.
+  {
+    id: "R11",
+    description:
+      "Source says broken, live shows 2xx, but observed text claims failure — human review",
+    matchFinding: (f) =>
+      f.kind === "frontend.broken-handler" ||
+      /broken (click|button|onclick|handler)/i.test(String(f.evidence || "")),
+    matchObservation: (obs) =>
+      obs &&
+      (obs.statusCodeObserved || 0) >= 200 &&
+      (obs.statusCodeObserved || 0) < 400 &&
+      /(error|failed|denied)/i.test(String(obs.observedBehavior || "")),
+    verdict: "CONTRADICTORY",
+    confidence: 0.7,
+    reason: "Live 2xx response but observed text suggests failure — human review",
+  },
+
+  {
+    id: "R01",
+    description:
+      "UI click finding marked as broken in source, live click succeeded + no console error + expected network call ≥ 200",
+    matchFinding: (f) =>
+      f.kind === "frontend.broken-handler" ||
+      /broken (click|button|onclick|handler)/i.test(String(f.evidence || "")),
+    matchObservation: (obs) =>
+      obs &&
+      (obs.statusCodeObserved || 0) >= 200 &&
+      (obs.statusCodeObserved || 0) < 400 &&
+      (obs.consoleErrors || []).length === 0,
+    verdict: "FALSE_POSITIVE",
+    confidence: 0.9,
+    reason: "Live interaction succeeded with no console error",
+  },
+
+  {
+    id: "R02",
+    description:
+      "UI click finding and live click actually threw a console error matching the claimed stack",
+    matchFinding: (f) =>
+      f.kind === "frontend.broken-handler" ||
+      /broken (click|button|onclick|handler)/i.test(String(f.evidence || "")),
+    matchObservation: (obs, finding) => {
+      if (!obs || !(obs.consoleErrors || []).length) return false;
+      const evidence = String(finding?.evidence || "").toLowerCase();
+      if (!evidence) return false;
+      // Bidirectional substring: either finding evidence contains the
+      // live console msg, or the live msg contains a chunk of the
+      // evidence. Either direction proves the live failure matches the
+      // static claim.
+      return (obs.consoleErrors || []).some((e) => {
+        const msg = String(e.msg || e).toLowerCase();
+        if (!msg) return false;
+        if (evidence.includes(msg)) return true;
+        if (msg.includes(evidence.slice(0, 40))) return true;
+        // Token overlap fallback: if 3+ contiguous tokens appear in both
+        // strings, call it a match.
+        const evidenceTokens = evidence.split(/\s+/).filter((t) => t.length >= 4);
+        for (let i = 0; i + 3 <= evidenceTokens.length; i += 1) {
+          const window = evidenceTokens.slice(i, i + 3).join(" ");
+          if (msg.includes(window)) return true;
+        }
+        return false;
+      });
+    },
+    verdict: "CONFIRMED",
+    confidence: 0.85,
+    reason: "Live console error matches source evidence",
+  },
+
+  {
+    id: "R03",
+    description: "Source flagged auth bypass; live unauth request returned 200 with sensitive data",
+    matchFinding: (f) =>
+      f.kind === "authz.missing-guard" ||
+      /auth (bypass|missing)/i.test(String(f.evidence || "")),
+    matchObservation: (obs) =>
+      obs &&
+      obs.statusCodeObserved === 200 &&
+      /token|secret|user\s*id|email|ssn|credit/i.test(String(obs.observedBehavior || "")),
+    verdict: "CONFIRMED",
+    confidence: 0.95,
+    reason: "Unauthenticated 200 with sensitive data surfaced",
+  },
+
+  {
+    id: "R04",
+    description: "Source flagged auth bypass; live unauth request returned 401/403",
+    matchFinding: (f) =>
+      f.kind === "authz.missing-guard" ||
+      /auth (bypass|missing)/i.test(String(f.evidence || "")),
+    matchObservation: (obs) =>
+      obs && (obs.statusCodeObserved === 401 || obs.statusCodeObserved === 403),
+    verdict: "FALSE_POSITIVE",
+    confidence: 0.9,
+    reason: "Unauthenticated request was properly rejected",
+  },
+
+  {
+    id: "R05",
+    description: "Source flagged XSS vector; live payload injected and executed",
+    matchFinding: (f) => /xss/i.test(String(f.kind || f.evidence || "")),
+    matchObservation: (obs) =>
+      obs &&
+      (obs.observedBehavior || "").toLowerCase().includes("payload executed"),
+    verdict: "CONFIRMED",
+    confidence: 0.95,
+    reason: "Live probe confirmed XSS payload executed",
+  },
+
+  {
+    id: "R06",
+    description: "Source flagged unbounded fetch; live request returned > 10MB or > 10k rows",
+    matchFinding: (f) =>
+      /unbounded[\s.-](fetch|query|list)/i.test(String(f.kind || f.evidence || "")),
+    matchObservation: (obs) => {
+      if (!obs || !obs.payload) return false;
+      const bytes = obs.payload.bytes || 0;
+      const rows = obs.payload.rows || 0;
+      return bytes > 10 * 1024 * 1024 || rows > 10_000;
+    },
+    verdict: "CONFIRMED",
+    confidence: 0.9,
+    reason: "Payload size/row count exceeded thresholds",
+  },
+
+  {
+    id: "R07",
+    description: "Source flagged missing idempotency; double-submit created N > 1 rows",
+    matchFinding: (f) =>
+      /idempoten|double(-|\s)?submit/i.test(String(f.kind || f.evidence || "")),
+    matchObservation: (obs) =>
+      obs &&
+      typeof obs.payload?.rowsCreatedOnDoubleSubmit === "number" &&
+      obs.payload.rowsCreatedOnDoubleSubmit > 1,
+    verdict: "CONFIRMED",
+    confidence: 0.95,
+    reason: "Double-submit resulted in multiple created rows",
+  },
+
+  {
+    id: "R08",
+    description: "Source flagged CORS too permissive; live response sent permissive Access-Control-Allow-Origin",
+    matchFinding: (f) => /cors/i.test(String(f.kind || f.evidence || "")),
+    matchObservation: (obs) => {
+      const header = obs?.payload?.headers?.["access-control-allow-origin"];
+      return header === "*" || header === "null";
+    },
+    verdict: "CONFIRMED",
+    confidence: 0.9,
+    reason: "CORS header permissive in live response",
+  },
+
+  {
+    id: "R09",
+    description:
+      "Source flagged element not rendered; live DOM snapshot shows the element and it is interactive",
+    matchFinding: (f) =>
+      /not rendered|missing element/i.test(String(f.kind || f.evidence || "")),
+    matchObservation: (obs) => obs && obs.elementLabel && !obs.navigated === false,
+    verdict: "FALSE_POSITIVE",
+    confidence: 0.8,
+    reason: "Element present and interactive in live run",
+  },
+
+  {
+    id: "R10",
+    description:
+      "Source flagged rate-limit bypass; live 10x-burst returned ≥ 1 non-429 success",
+    matchFinding: (f) => /rate[\s-]?limit/i.test(String(f.kind || f.evidence || "")),
+    matchObservation: (obs) => {
+      const burst = obs?.payload?.burstResults || [];
+      return burst.length >= 10 && burst.some((s) => s >= 200 && s < 400);
+    },
+    verdict: "CONFIRMED",
+    confidence: 0.9,
+    reason: "Rate-limit was bypassed under burst",
+  },
+
+]);
+
+/**
+ * Evaluate a single (finding, observation) pair against the ruleset.
+ * Returns the first matching verdict, or UNVERIFIABLE if no rule fires.
+ *
+ * @param {Finding} finding
+ * @param {LiveObservation | null} observation
+ * @returns {ReconciliationVerdict}
+ */
+export function reconcileFindingWithObservation(finding, observation) {
+  if (!finding) {
+    return {
+      verdict: "UNVERIFIABLE",
+      ruleId: "R-PREFLIGHT",
+      confidence: 0.0,
+      reason: "No finding supplied",
+    };
+  }
+  for (const rule of RULES) {
+    try {
+      if (!rule.matchFinding(finding)) continue;
+      if (!rule.matchObservation(observation, finding)) continue;
+      return {
+        verdict: rule.verdict,
+        ruleId: rule.id,
+        confidence: rule.confidence,
+        reason: rule.reason,
+      };
+    } catch {
+      // defensive: if a rule throws, continue walking — a misconfigured
+      // rule must never block the whole reconciliation pass.
+      continue;
+    }
+  }
+  return {
+    verdict: "UNVERIFIABLE",
+    ruleId: "R-NO-MATCH",
+    confidence: 0.0,
+    reason: observation
+      ? "No ruleset match for this (finding, observation) pair"
+      : "No live observation covered this finding",
+  };
+}
+
+/**
+ * Apply reconciliation to a batch of findings + observations. Observations
+ * are keyed by `finding.file`+`finding.line`+`observation.sourceFile` via
+ * the pair function; simplest form is to pair each finding with 0 or 1
+ * observation from a lookup the caller provides.
+ *
+ * @param {Array<Finding>} findings
+ * @param {(finding: Finding) => LiveObservation | null} pair
+ * @returns {Array<Finding & { reconciliation: ReconciliationVerdict }>}
+ */
+export function reconcileFindings(findings, pair) {
+  if (!Array.isArray(findings)) return [];
+  const pairFn = typeof pair === "function" ? pair : () => null;
+  return findings.map((f) => ({
+    ...f,
+    reconciliation: reconcileFindingWithObservation(f, pairFn(f)),
+  }));
+}
+
+/**
+ * Policy helper: decide whether a finding should ship in the final
+ * report. FALSE_POSITIVE is suppressed unless the caller forces HITL
+ * review; CONTRADICTORY ships with a banner; CONFIRMED and UNVERIFIABLE
+ * ship as-is.
+ *
+ * @param {Finding & { reconciliation: ReconciliationVerdict }} finding
+ * @param {object} [options]
+ * @param {boolean} [options.keepFalsePositivesForHitl=false]
+ * @returns {"include" | "include-with-banner" | "suppress"}
+ */
+export function applyReportPolicy(finding, { keepFalsePositivesForHitl = false } = {}) {
+  const verdict = finding?.reconciliation?.verdict;
+  if (verdict === "FALSE_POSITIVE") {
+    return keepFalsePositivesForHitl ? "include-with-banner" : "suppress";
+  }
+  if (verdict === "CONTRADICTORY") return "include-with-banner";
+  return "include";
+}
+
+export const RECONCILIATION_RULESET_VERSION = "1.0.0";
+export const RECONCILIATION_RULES = RULES;

package/src/review/reproducibility-chain.js

@@ -0,0 +1,136 @@
+/**
+ * Reproducibility chain (#investor-dd-17).
+ *
+ * For each finding emitted by the investor-DD run, attach a `replay`
+ * block that captures:
+ *
+ *   - replayCommand   — a single-line bash command that re-runs the
+ *                        exact evidence-gathering step (tool dispatch
+ *                        against the same file), so an auditor or the
+ *                        caller can verify without re-running the
+ *                        full investor-DD flow.
+ *   - filesAtTime     — SHA-256 of every file involved in the finding
+ *                        at finding time, so if the repo has changed
+ *                        since, the mismatch is detectable.
+ *   - runId / timestamp for cross-reference.
+ *
+ * The module is a pure decorator: it does not mutate findings, it
+ * returns new ones enriched with reproducibility metadata.
+ */
+
+import crypto from "node:crypto";
+import fsp from "node:fs/promises";
+import path from "node:path";
+
+/**
+ * Compute SHA-256 of a file on disk. Returns null if unreadable so
+ * the chain never blocks the report on transient fs failures.
+ *
+ * @param {string} absPath
+ * @returns {Promise<string | null>}
+ */
+export async function sha256File(absPath) {
+  try {
+    const data = await fsp.readFile(absPath);
+    return crypto.createHash("sha256").update(data).digest("hex");
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Build a single finding's replay block.
+ *
+ * @param {object} params
+ * @param {object} params.finding       - Must have .personaId, .tool, .file.
+ * @param {string} params.rootPath      - Repo root (used to resolve finding.file).
+ * @param {string} params.runId
+ * @param {string} [params.cliName="sl"]  - Display name in replayCommand.
+ * @returns {Promise<{replayCommand: string, filesAtTime: Record<string, string|null>, runId: string, timestamp: string}>}
+ */
+export async function buildReplayBlock({
+  finding,
+  rootPath,
+  runId,
+  cliName = "sl",
+} = {}) {
+  if (!finding) throw new TypeError("buildReplayBlock requires finding");
+  if (!rootPath) throw new TypeError("buildReplayBlock requires rootPath");
+  if (!runId) throw new TypeError("buildReplayBlock requires runId");
+
+  const file = finding.file || "";
+  const tool = finding.tool || finding.kind || "";
+  const personaId = finding.personaId || "";
+
+  const replayCommand = [
+    cliName,
+    "/review",
+    "show",
+    "--run",
+    runId,
+    "--persona",
+    personaId,
+    "--tool",
+    tool,
+    "--file",
+    file,
+  ]
+    .filter(Boolean)
+    .join(" ");
+
+  const filesAtTime = {};
+  if (file) {
+    const abs = path.isAbsolute(file) ? file : path.join(rootPath, file);
+    filesAtTime[file] = await sha256File(abs);
+  }
+
+  return {
+    replayCommand,
+    filesAtTime,
+    runId,
+    timestamp: new Date().toISOString(),
+  };
+}
+
+/**
+ * Decorate an array of findings with reproducibility chains. Runs in
+ * parallel but bounded concurrency so we don't thrash disk on huge
+ * finding sets.
+ *
+ * @param {object} params
+ * @param {Array<object>} params.findings
+ * @param {string} params.rootPath
+ * @param {string} params.runId
+ * @param {string} [params.cliName]
+ * @param {number} [params.concurrency=8]
+ * @returns {Promise<Array<object>>}  Findings with `.reproducibility` attached.
+ */
+export async function attachReproducibilityChain({
+  findings = [],
+  rootPath,
+  runId,
+  cliName = "sl",
+  concurrency = 8,
+} = {}) {
+  if (!Array.isArray(findings)) throw new TypeError("findings must be an array");
+  if (!rootPath) throw new TypeError("rootPath required");
+  if (!runId) throw new TypeError("runId required");
+
+  const result = [];
+  let cursor = 0;
+  async function worker() {
+    while (cursor < findings.length) {
+      const idx = cursor;
+      cursor += 1;
+      const finding = findings[idx];
+      const replay = await buildReplayBlock({ finding, rootPath, runId, cliName });
+      result[idx] = { ...finding, reproducibility: replay };
+    }
+  }
+  const workers = [];
+  for (let i = 0; i < Math.max(1, Math.min(concurrency, findings.length)); i += 1) {
+    workers.push(worker());
+  }
+  await Promise.all(workers);
+  return result;
+}

package/src/review/scan-modes.js

@@ -13,12 +13,33 @@
  * gaps; run `baseline` when you only need security.
  */
 
+// AUTHORITATIVE dispatch list. Anything not in this array does not run,
+// regardless of whether it has a persona prompt or visual identity elsewhere.
+//
+// Cross-reference (keep in sync):
+// - src/review/persona-prompts.js PERSONA_PROMPTS keys → must match this list
+// - src/review/persona-prompts.js SWE_FRAMEWORK_CHECKLIST keys → must match this list
+// - src/agents/persona-visuals.js → may define SUPERSET (visuals for sub-specialties
+//   are allowed, e.g. Maya Volkov has both "architecture" and "backend" visuals
+//   because both roles fold into her architecture dispatch).
+//
+// Canon update (2026-04-18): "backend" (Maya Volkov, ex-AWS Platform),
+// "code-quality" (Ethan Park, ex-Meta Code Health), and "data-layer"
+// (Dr. Linh Tran, ex-Netflix Data Platforms) are now dispatched personas
+// per Carter's canonical 13.
+// Removed:
+// - "architecture" — structural concerns fold into code-quality; runtime
+//   concerns fold into backend.
+// - "performance" — concerns distributed across backend / data-layer /
+//   frontend / observability / reliability.
+// - "compliance" — cross-cutting; distributed across security / ai-governance /
+//   supply-chain / infrastructure / documentation via subagent dispatch.
 const FULL_DEPTH_PERSONAS = [
   "security",
-  "architecture",
+  "backend",
+  "code-quality",
   "testing",
-  "performance",
-  "compliance",
+  "data-layer",
   "reliability",
   "release",
   "observability",
@@ -46,3 +67,81 @@ export function resolveScanMode(mode = "deep") {
 }
 
 export const AVAILABLE_SCAN_MODES = Object.keys(SCAN_MODES);
+
+/**
+ * Parse a comma-separated persona ID list from CLI input.
+ *
+ * Trims whitespace, lowercases, drops empty entries, deduplicates.
+ *
+ * @param {string | string[] | null | undefined} value
+ * @returns {string[]} Cleaned persona ID list.
+ */
+export function parsePersonaCsv(value) {
+  if (value == null) return [];
+  const raw = Array.isArray(value) ? value.join(",") : String(value);
+  const cleaned = raw
+    .split(",")
+    .map((s) => s.trim().toLowerCase())
+    .filter((s) => s.length > 0);
+  return [...new Set(cleaned)];
+}
+
+/**
+ * Resolve a scan mode and then filter the persona list by opt-in / opt-out lists.
+ *
+ * Precedence:
+ *   1. Start with the base persona list for `mode`.
+ *   2. If `includeOnly` is a non-empty array, restrict to those IDs (in the
+ *      order they appear in the base list, for deterministic dispatch).
+ *   3. Remove any IDs in `skipPersonas`.
+ *
+ * If a caller passes `includeOnly` IDs that aren't in the base list, they
+ * are silently dropped (not errored) so typos don't block a run. The caller
+ * can check `result.unknown` to surface warnings in the UI.
+ *
+ * @param {string} [mode="deep"]
+ * @param {object} [options]
+ * @param {string[]} [options.includeOnly]  Only run these personas.
+ * @param {string[]} [options.skipPersonas] Skip these personas.
+ * @returns {{mode: string, personas: string[], dropped: string[], unknown: string[]}}
+ */
+export function resolveFilteredPersonas(mode = "deep", options = {}) {
+  const { includeOnly = null, skipPersonas = [] } = options || {};
+  const { mode: normalized, personas: base } = resolveScanMode(mode);
+
+  const basePersonas = [...base];
+  let filtered = basePersonas;
+  const unknown = [];
+
+  if (Array.isArray(includeOnly) && includeOnly.length > 0) {
+    const normalizedInclude = new Set(
+      includeOnly.map((p) => String(p).trim().toLowerCase()).filter(Boolean),
+    );
+    // Surface any include entries that aren't in the base mode list.
+    for (const id of normalizedInclude) {
+      if (!basePersonas.includes(id)) unknown.push(id);
+    }
+    filtered = basePersonas.filter((id) => normalizedInclude.has(id));
+  }
+
+  const dropped = [];
+  if (Array.isArray(skipPersonas) && skipPersonas.length > 0) {
+    const normalizedSkip = new Set(
+      skipPersonas.map((p) => String(p).trim().toLowerCase()).filter(Boolean),
+    );
+    filtered = filtered.filter((id) => {
+      if (normalizedSkip.has(id)) {
+        dropped.push(id);
+        return false;
+      }
+      return true;
+    });
+  }
+
+  return {
+    mode: normalized,
+    personas: filtered,
+    dropped,
+    unknown,
+  };
+}

package/src/session/agent-registry.js

@@ -6,6 +6,7 @@ import process from "node:process";
 import { STUCK_THRESHOLDS } from "../agents/jules/pulse.js";
 import { createAgentEvent } from "../events/schema.js";
 import { resolveSessionPaths } from "./paths.js";
+import { emitContextBriefing } from "./recap.js";
 import { appendToStream } from "./stream.js";
 
 const AGENT_SNAPSHOT_SCHEMA_VERSION = "1.0.0";
@@ -209,6 +210,12 @@ export async function registerAgent(
     role: snapshot.role,
     status: snapshot.status,
   }, { targetPath });
+  if (normalizeString(snapshot.agentId).toLowerCase() !== "senti") {
+    await emitContextBriefing(paths.sessionId, {
+      forAgentId: snapshot.agentId,
+      targetPath,
+    }).catch(() => {});
+  }
 
   return {
     ...snapshot,