mandrel 1.57.0

package/.agents/scripts/lib/orchestration/review-providers/security-review.js

@@ -0,0 +1,373 @@
+/**
+ * review-providers/security-review.js — Inline ReviewProvider that
+ * invokes Anthropic's built-in `/security-review` Claude Code skill.
+ *
+ * Story #2871 — extends the pluggable Code Review chain (Epic #2815)
+ * to surface security-specific findings before a Story or Epic
+ * merges. The adapter shells out to the host's `claude` CLI with a
+ * prompt that wraps `/security-review` and asks for JSON-shaped
+ * findings on stdout, then maps each entry onto the canonical
+ * `Finding[]` contract so the existing `runCodeReview()` halting
+ * gate ("any critical → halted: true") applies without a parallel
+ * code path.
+ *
+ * Probe semantics: the provider checks for a `claude` binary on
+ * PATH at construction. When absent, the constructor throws a
+ * descriptive Error. The chain treats a constructor throw as a
+ * skip when the entry was declared `optional: true` (the canonical
+ * choice for `security-review` on non-Claude hosts), and as a
+ * hard-fail when not.
+ *
+ * Output parsing is liberal: the provider accepts (a) a bare JSON
+ * array, (b) `{findings: [...]}`, or (c) either shape wrapped in a
+ * `result`/`data` envelope. Free-text output that does not parse as
+ * JSON collapses to a single advisory `suggestion` finding pointing
+ * the operator at the manual command — the chain still runs, but
+ * the security signal is downgraded honestly rather than dropped.
+ *
+ * @typedef {import('./types.js').Finding}        Finding
+ * @typedef {import('./types.js').ReviewInput}    ReviewInput
+ * @typedef {import('./types.js').ReviewProvider} ReviewProvider
+ * @typedef {import('./types.js').Severity}       Severity
+ */
+
+import { spawnSync } from 'node:child_process';
+import { renderDepthDirective } from './review-depth.js';
+
+/**
+ * Canonical install/remediation guidance baked into every probe
+ * failure. Exported so tests assert against the exact strings.
+ */
+export const SECURITY_REVIEW_REMEDIATIONS = Object.freeze({
+  install:
+    'Install the Claude Code CLI (https://docs.anthropic.com/en/docs/claude-code) ' +
+    'so the host registers the `/security-review` built-in skill.',
+  fallback:
+    'Or mark this provider entry as `optional: true` in .agentrc.json so ' +
+    'the chain skips it on hosts without the skill.',
+});
+
+/**
+ * Default probe: returns true when `claude --version` exits cleanly.
+ * Synchronous + cheap; the worst case (claude absent) MUST surface
+ * at factory construction time so the operator sees the remediation
+ * before the first review run.
+ *
+ * Exported for testing — tests inject a stub `probeFn` to bypass.
+ *
+ * @param {{ spawnFn?: typeof spawnSync }} [opts]
+ * @returns {boolean}
+ */
+export function defaultProbeClaudeCli(opts = {}) {
+  const spawnFn = opts.spawnFn ?? spawnSync;
+  try {
+    const result = spawnFn('claude', ['--version'], {
+      encoding: 'utf-8',
+      shell: process.platform === 'win32',
+      timeout: 5000,
+    });
+    return (result?.status ?? 1) === 0;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Build the hard-fail Error thrown when the probe reports the
+ * `claude` CLI is absent. Exported so the registry entry and tests
+ * share one message shape.
+ *
+ * @returns {Error}
+ */
+export function buildSecurityReviewUnavailableError() {
+  return new Error(
+    '[ReviewProviderFactory] codeReview provider "security-review" requires ' +
+      'the `claude` CLI on PATH but it was not detected. ' +
+      `${SECURITY_REVIEW_REMEDIATIONS.install} ${SECURITY_REVIEW_REMEDIATIONS.fallback}`,
+  );
+}
+
+/**
+ * Severity vocabulary mapping. Mirrors `CODEX_SEVERITY_MAP` so
+ * operators see a consistent severity-tier vocabulary regardless of
+ * which adapter produced the finding.
+ *
+ * @type {Readonly<Record<string, Severity>>}
+ */
+export const SECURITY_REVIEW_SEVERITY_MAP = Object.freeze({
+  blocker: 'critical',
+  critical: 'critical',
+  fatal: 'critical',
+  major: 'high',
+  high: 'high',
+  error: 'high',
+  minor: 'medium',
+  medium: 'medium',
+  warning: 'medium',
+  info: 'suggestion',
+  nit: 'suggestion',
+  style: 'suggestion',
+  suggestion: 'suggestion',
+  note: 'suggestion',
+});
+
+/**
+ * Map a single security-review severity string onto the canonical
+ * enum. Unknown / missing values collapse to `'suggestion'`.
+ *
+ * @param {unknown} raw
+ * @returns {Severity}
+ */
+export function mapSecurityReviewSeverity(raw) {
+  if (typeof raw !== 'string') return 'suggestion';
+  const key = raw.trim().toLowerCase();
+  return SECURITY_REVIEW_SEVERITY_MAP[key] ?? 'suggestion';
+}
+
+/**
+ * Parse `/security-review` JSON output into `Finding[]`. Liberal:
+ * accepts a bare array, `{findings: [...]}`, or either shape
+ * wrapped in a `result`/`data` envelope. Free-text output that
+ * fails to parse throws — the caller decides whether to fall back
+ * to a single advisory finding.
+ *
+ * Exported for testing.
+ *
+ * @param {string} rawStdout
+ * @returns {Finding[]}
+ * @throws {Error} when stdout is not parseable JSON.
+ */
+export function parseSecurityReviewFindings(rawStdout) {
+  const text = (rawStdout ?? '').trim();
+  if (text.length === 0) return [];
+
+  let parsed;
+  try {
+    parsed = JSON.parse(text);
+  } catch (err) {
+    throw new Error(
+      `[security-review] Failed to parse /security-review stdout as JSON: ${
+        err?.message ?? err
+      }`,
+    );
+  }
+
+  if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {
+    if (Array.isArray(parsed.findings)) parsed = parsed.findings;
+    else if (parsed.result !== undefined) parsed = parsed.result;
+    else if (parsed.data !== undefined) parsed = parsed.data;
+  }
+  if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {
+    if (Array.isArray(parsed.findings)) parsed = parsed.findings;
+  }
+
+  if (!Array.isArray(parsed)) return [];
+
+  /** @type {Finding[]} */
+  const findings = [];
+  for (const entry of parsed) {
+    if (!entry || typeof entry !== 'object') continue;
+    const title =
+      typeof entry.title === 'string' && entry.title.trim().length > 0
+        ? entry.title.trim()
+        : null;
+    const body =
+      typeof entry.body === 'string' && entry.body.trim().length > 0
+        ? entry.body
+        : typeof entry.message === 'string' && entry.message.trim().length > 0
+          ? entry.message
+          : null;
+    if (!title || !body) continue;
+    /** @type {Finding} */
+    const finding = {
+      severity: mapSecurityReviewSeverity(entry.severity),
+      title,
+      body,
+      category:
+        typeof entry.category === 'string' && entry.category.length > 0
+          ? entry.category
+          : 'security',
+    };
+    if (typeof entry.file === 'string' && entry.file.length > 0) {
+      finding.file = entry.file;
+    }
+    if (Number.isInteger(entry.line) && entry.line > 0) {
+      finding.line = entry.line;
+    }
+    findings.push(finding);
+  }
+  return findings;
+}
+
+/**
+ * Prompt body sent to `claude --print` to wrap the built-in
+ * `/security-review` skill with an explicit JSON-emit instruction.
+ * Exported so doc tooling and tests reference one canonical string.
+ *
+ * The prompt is intentionally narrow: it asks the model to run the
+ * skill against a specific git range and emit findings as a JSON
+ * array. Any prose preface or trailing commentary is parseable as
+ * "garbage before/after JSON" — `parseSecurityReviewFindings` uses
+ * the first JSON-shaped substring rather than the whole stdout.
+ *
+ * The `{depthDirective}` slot renders the risk-derived thoroughness lever
+ * (Story #3937) so a high-risk Epic instructs the model toward a deeper
+ * second-pass review while a low-risk one keeps it light.
+ */
+export const SECURITY_REVIEW_INVOKE_PROMPT =
+  'Run /security-review against the diff `{baseRef}`...`{headRef}` ' +
+  'for {scopeLabel} #{ticketId}. {depthDirective} After the review, emit ' +
+  'ONLY a JSON array of findings on stdout with this exact shape:\n\n' +
+  '```\n[{"severity":"critical|high|medium|suggestion","title":"...",' +
+  '"body":"...","file":"...","line":1,"category":"security"}]\n```\n\n' +
+  'Use severity "critical" for blockers (must fix before merge), ' +
+  '"high" for material risks, "medium" for issues worth fixing, and ' +
+  '"suggestion" for advisory notes. Emit `[]` if you find nothing. ' +
+  'No prose around the JSON.';
+
+/**
+ * Build the `claude --print` prompt for a specific review input. The
+ * risk-derived `depth` lever (Story #3937) is rendered into the prompt via
+ * `renderDepthDirective` so the model's thoroughness tracks the Epic's judged
+ * risk; an absent depth renders the `standard` directive.
+ *
+ * Exported for testing.
+ *
+ * @param {ReviewInput} input
+ * @returns {string}
+ */
+export function buildSecurityReviewPrompt(input) {
+  const scopeLabel = input?.scope === 'epic' ? 'Epic' : 'Story';
+  const baseRef = typeof input?.baseRef === 'string' ? input.baseRef : '?';
+  const headRef = typeof input?.headRef === 'string' ? input.headRef : '?';
+  const ticketId =
+    Number.isInteger(input?.ticketId) && input.ticketId > 0
+      ? String(input.ticketId)
+      : '?';
+  return SECURITY_REVIEW_INVOKE_PROMPT.replace('{baseRef}', baseRef)
+    .replace('{headRef}', headRef)
+    .replace('{scopeLabel}', scopeLabel)
+    .replace('{ticketId}', ticketId)
+    .replace('{depthDirective}', renderDepthDirective(input?.depth));
+}
+
+/**
+ * Default invoker: shell out to the host's `claude` CLI to run the
+ * `/security-review` skill via a JSON-emit prompt. Exported for
+ * testing — the production adapter accepts an `invokeFn` override
+ * so tests never spawn a real process.
+ *
+ * @param {ReviewInput} input
+ * @returns {{ status: number, stdout: string, stderr: string }}
+ */
+export function defaultInvokeSecurityReview(input) {
+  const prompt = buildSecurityReviewPrompt(input);
+  const result = spawnSync('claude', ['--print', prompt], {
+    encoding: 'utf-8',
+    shell: process.platform === 'win32',
+    timeout: 10 * 60 * 1000,
+  });
+  return {
+    status: result.status ?? 1,
+    stdout: result.stdout ?? '',
+    stderr: result.stderr ?? '',
+  };
+}
+
+/**
+ * Build the advisory fallback finding emitted when `/security-review`
+ * exits cleanly but its stdout is not parseable JSON. Pure +
+ * exported so tests assert against the exact shape.
+ *
+ * @returns {Finding}
+ */
+export function buildUnparseableFallbackFinding() {
+  return {
+    severity: 'suggestion',
+    title: 'Security review output not parseable as JSON',
+    body:
+      'The `/security-review` skill returned text that did not parse as a ' +
+      'JSON findings array. The review still ran — operators should inspect ' +
+      'the skill output manually before merging. Treat as advisory; the ' +
+      'chain did not halt.',
+    category: 'security',
+  };
+}
+
+/**
+ * Build a `ReviewProvider` instance backed by `/security-review`.
+ *
+ * @param {{
+ *   probeFn?: () => boolean,
+ *   invokeFn?: (input: ReviewInput) => { status: number, stdout: string, stderr: string },
+ *   logger?: { info?: Function, warn?: Function, error?: Function },
+ * }} [deps]
+ * @returns {ReviewProvider}
+ */
+export function createSecurityReviewProvider(deps = {}) {
+  const probeFn = deps.probeFn ?? defaultProbeClaudeCli;
+  if (!probeFn()) {
+    throw buildSecurityReviewUnavailableError();
+  }
+  const invokeFn = deps.invokeFn ?? defaultInvokeSecurityReview;
+  const logger = deps.logger;
+
+  return {
+    /**
+     * @param {ReviewInput} input
+     * @returns {Promise<Finding[]>}
+     */
+    async runReview(input) {
+      const { scope, ticketId, baseRef, headRef } = input ?? {};
+      if (!baseRef || !headRef) {
+        throw new TypeError(
+          '[security-review] runReview requires baseRef and headRef.',
+        );
+      }
+      if (!Number.isInteger(ticketId) || ticketId <= 0) {
+        throw new TypeError(
+          '[security-review] runReview requires a positive integer ticketId.',
+        );
+      }
+
+      logger?.info?.(
+        `[security-review] Invoking /security-review for ${scope} #${ticketId} (${baseRef}...${headRef})...`,
+      );
+
+      const result = invokeFn({ scope, ticketId, baseRef, headRef });
+      if (result.status !== 0) {
+        throw new Error(
+          `[security-review] claude --print /security-review exited with ` +
+            `status ${result.status}: ${
+              result.stderr || result.stdout || '<no output>'
+            }`,
+        );
+      }
+
+      try {
+        const findings = parseSecurityReviewFindings(result.stdout);
+        logger?.info?.(
+          `[security-review] Parsed ${findings.length} finding(s) from /security-review.`,
+        );
+        return findings;
+      } catch (err) {
+        logger?.warn?.(
+          `[security-review] Could not parse stdout as JSON; emitting advisory fallback: ${
+            err?.message ?? err
+          }`,
+        );
+        return [buildUnparseableFallbackFinding()];
+      }
+    },
+  };
+}
+
+/**
+ * Zero-arg factory entry point used by the `review-provider-factory`
+ * registry. Mirrors `createCodexProviderForRegistry`.
+ *
+ * @returns {ReviewProvider}
+ */
+export function createSecurityReviewProviderForRegistry() {
+  return createSecurityReviewProvider();
+}

package/.agents/scripts/lib/orchestration/review-providers/types.js

@@ -0,0 +1,89 @@
+/**
+ * review-providers/types.js — Pluggable Code Review contract typedefs.
+ *
+ * Story #2825 (Epic #2815) — defines the `Finding` and `ReviewProvider`
+ * shapes that adapters under `review-providers/` must conform to. The
+ * factory loads an adapter, the adapter returns `Finding[]`, and the
+ * `findings-renderer` turns that array into the structured-comment body
+ * posted to the Story/Epic ticket.
+ *
+ * Story #2871 — extends the contract for multi-provider chains and
+ * adds `ManualPromptProvider` for operator-prompt providers
+ * (e.g. ultrareview) that emit a non-blocking suggestion into the
+ * structured comment instead of running a real review.
+ *
+ * This file is JSDoc-only — no runtime exports. It exists so other
+ * modules and tests have a single canonical reference to import via
+ * `@typedef` lookups.
+ *
+ * @typedef {'critical'|'high'|'medium'|'suggestion'} Severity
+ *
+ * @typedef {object} Finding
+ * @property {Severity} severity     - Severity tier; maps to the 🔴/🟠/🟡/🟢 emoji set.
+ * @property {string}   title        - One-line summary.
+ * @property {string}   body         - Markdown body rendered inside the comment.
+ * @property {string=}  file         - Relative path, when attributable.
+ * @property {number=}  line         - 1-based line number, when attributable.
+ * @property {string=}  category     - Free-form tag (e.g. 'security', 'docs', 'lint').
+ *
+ * @typedef {'story'|'epic'} ReviewScope
+ *
+ * @typedef {'light'|'standard'|'deep'} ReviewDepth
+ *
+ * @typedef {object} ReviewInput
+ * @property {ReviewScope} scope     - Which close boundary is invoking the review.
+ * @property {number}      ticketId  - Story or Epic issue number.
+ * @property {string}      baseRef   - Git ref to diff against (e.g. 'main', 'epic/2815').
+ * @property {string}      headRef   - Git ref under review (e.g. 'story-2820', 'epic/2815').
+ * @property {ReviewDepth=} depth    - Risk-and-width-derived review thoroughness
+ *   lever (Story #3876/#3937/#3938). `light` → single-pass review focused on
+ *   Pillar 1 (spec adherence) with Pillars 2–3 reduced to a quick scan;
+ *   `standard` → all pillars at baseline depth; `deep` → all pillars plus a
+ *   second adversarial pass over the diff. Resolved from the judged risk
+ *   envelope AND the changed-file count of the diff by `resolveDepth`
+ *   (`lib/orchestration/review-depth.js`) and threaded into `runReview`.
+ *   LLM-backed
+ *   providers MUST render this into the prompt/instructions they emit; the
+ *   native provider documents why its mechanical sweep ignores it. Absent →
+ *   providers treat the review as `standard`.
+ *
+ * @typedef {object} ReviewProvider
+ * @property {(input: ReviewInput) => Promise<Finding[]>} runReview
+ *
+ * Manual-prompt providers (Story #2871) do NOT run a review — they
+ * contribute a one-line operator-facing suggestion to the structured
+ * comment. Used for cloud or user-triggered review tools (e.g.
+ * `/ultrareview`) that cannot be invoked programmatically from a
+ * Node orchestrator.
+ *
+ * @typedef {object} ManualPromptResult
+ * @property {string} message  - Markdown one-liner appended under "Manual review suggestions".
+ *
+ * @typedef {object} ManualPromptProvider
+ * @property {(input: ReviewInput) => Promise<ManualPromptResult>} renderPrompt
+ *
+ * Chain entries (Story #2871) wrap an adapter with metadata used by
+ * the orchestrator to gate invocation per-scope and per-label.
+ *
+ * @typedef {object} ProviderGateContext
+ * @property {ReviewScope}           scope    - Current invocation scope.
+ * @property {ReadonlyArray<string>} labels   - Ticket labels at invocation time.
+ *
+ * @typedef {(ctx: ProviderGateContext) => boolean} ProviderGate
+ *
+ * @typedef {object} InlineChainEntry
+ * @property {string}          name      - Registered provider key (for logs/attribution).
+ * @property {ReviewProvider}  provider  - Constructed inline adapter.
+ * @property {ProviderGate}    gate      - Pure predicate; false → skip this entry.
+ *
+ * @typedef {object} PromptChainEntry
+ * @property {string}                name      - Registered provider key.
+ * @property {ManualPromptProvider}  provider  - Constructed manual-prompt adapter.
+ * @property {ProviderGate}          gate      - Pure predicate; false → skip this entry.
+ *
+ * @typedef {object} ProviderChain
+ * @property {InlineChainEntry[]} inline  - Inline adapters (run, merge Finding[]).
+ * @property {PromptChainEntry[]} prompts - Manual-prompt adapters (render suggestion strings).
+ */
+
+export {};

package/.agents/scripts/lib/orchestration/review-providers/ultrareview.js

@@ -0,0 +1,107 @@
+/**
+ * review-providers/ultrareview.js — Manual-prompt provider for
+ * Anthropic's `/ultrareview` cloud multi-agent review.
+ *
+ * Story #2871 — `/ultrareview` is user-triggered and billed by
+ * Anthropic; it cannot be invoked programmatically from a Node
+ * orchestrator. This adapter implements the `ManualPromptProvider`
+ * shape instead of `ReviewProvider`: it emits a single Markdown
+ * suggestion line into the structured `code-review` comment so the
+ * operator sees the nudge inline with the rest of the review.
+ *
+ * The adapter is intentionally pure and host-agnostic. It does NOT
+ * probe the host for Claude CLI availability — `renderPrompt()` only
+ * produces text, and the worst case under a non-Claude host is a
+ * suggestion the operator cannot act on. Documenting that suggestion
+ * is still useful (consumer projects pin to a framework version, and
+ * upgrading to a Claude-capable runtime exposes the value).
+ *
+ * Per the story acceptance contract: manual-prompt providers MUST
+ * NEVER throw under any host.
+ *
+ * @typedef {import('./types.js').ManualPromptProvider} ManualPromptProvider
+ * @typedef {import('./types.js').ManualPromptResult}   ManualPromptResult
+ * @typedef {import('./types.js').ReviewInput}          ReviewInput
+ */
+
+import { renderDepthDirective } from './review-depth.js';
+
+/**
+ * Canonical suggestion string. Exported so tests can assert against
+ * the exact wording rather than free-text matching, and so doc
+ * tooling can lift the line without spawning a fake review.
+ *
+ * The `{depthDirective}` slot renders the risk-derived thoroughness lever
+ * (Story #3937) so the operator nudge tells the human reviewer how deep to go
+ * when they trigger `/ultrareview` — a high-risk Epic asks for a deep
+ * second-pass review, a low-risk one keeps it light.
+ */
+export const ULTRAREVIEW_PROMPT_TEMPLATE =
+  '💡 **Suggested:** Consider running `/ultrareview` on this ' +
+  '{scopeLabel} (`{baseRef}`…`{headRef}`) before merging — ' +
+  "Anthropic's multi-agent cloud review surfaces issues that " +
+  'single-pass review can miss. This is operator-triggered ' +
+  '(billed by Anthropic); not a blocker. {depthDirective}';
+
+/**
+ * Render the canonical suggestion string with the live scope/baseRef/
+ * headRef substituted, and the risk-derived `depth` lever (Story #3937)
+ * rendered into the nudge via `renderDepthDirective` (absent depth → the
+ * `standard` directive).
+ *
+ * Pure — exported for testing.
+ *
+ * @param {ReviewInput} input
+ * @returns {string}
+ */
+export function buildUltrareviewMessage(input) {
+  const scopeLabel = input?.scope === 'epic' ? 'Epic' : 'Story';
+  const baseRef = typeof input?.baseRef === 'string' ? input.baseRef : '?';
+  const headRef = typeof input?.headRef === 'string' ? input.headRef : '?';
+  return ULTRAREVIEW_PROMPT_TEMPLATE.replace('{scopeLabel}', scopeLabel)
+    .replace('{baseRef}', baseRef)
+    .replace('{headRef}', headRef)
+    .replace('{depthDirective}', renderDepthDirective(input?.depth));
+}
+
+/**
+ * Build a `ManualPromptProvider` instance for the `ultrareview`
+ * registry slot.
+ *
+ * The `deps` overload exists only for test parity with the inline
+ * provider factories — production callers (the factory) invoke
+ * `createUltrareviewProvider()` with no arguments.
+ *
+ * @param {{
+ *   logger?: { info?: Function, warn?: Function },
+ * }} [deps]
+ * @returns {ManualPromptProvider}
+ */
+export function createUltrareviewProvider(deps = {}) {
+  const logger = deps.logger;
+
+  return {
+    /**
+     * @param {ReviewInput} input
+     * @returns {Promise<ManualPromptResult>}
+     */
+    async renderPrompt(input) {
+      const message = buildUltrareviewMessage(input);
+      logger?.info?.(
+        '[ultrareview] Manual-prompt suggestion rendered (non-blocking).',
+      );
+      return { message };
+    },
+  };
+}
+
+/**
+ * Zero-arg factory entry point used by the `review-provider-factory`
+ * registry. Mirrors `createCodexProviderForRegistry` so the registry
+ * signature stays `() => ManualPromptProvider`.
+ *
+ * @returns {ManualPromptProvider}
+ */
+export function createUltrareviewProviderForRegistry() {
+  return createUltrareviewProvider();
+}