mandrel 2.59.0 → 2.61.0

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

@@ -1,29 +1,7 @@
 /**
- * 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.
+ * review-providers/security-review.js — runs `/security-review` through
+ * `claude --print`. A missing CLI throws at construction; unparseable output
+ * becomes one advisory finding rather than being dropped.
  *
  * @typedef {import('./types.js').Finding}        Finding
  * @typedef {import('./types.js').ReviewInput}    ReviewInput
@@ -35,10 +13,6 @@ import { spawnSync } from 'node:child_process';
 import { parseProviderFindings } from './parse-findings.js';
 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) ' +
@@ -49,12 +23,7 @@ export const SECURITY_REVIEW_REMEDIATIONS = Object.freeze({
 });
 
 /**
- * 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.
+ * Synchronous so a missing CLI surfaces at construction, not mid-review.
  *
  * @param {{ spawnFn?: typeof spawnSync }} [opts]
  * @returns {boolean}
@@ -74,10 +43,6 @@ function defaultProbeClaudeCli(opts = {}) {
 }
 
 /**
- * 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() {
@@ -89,9 +54,7 @@ export function buildSecurityReviewUnavailableError() {
 }
 
 /**
- * Severity vocabulary mapping. Mirrors `CODEX_SEVERITY_MAP` so
- * operators see a consistent severity-tier vocabulary regardless of
- * which adapter produced the finding.
+ * Mirrors `CODEX_SEVERITY_MAP` for a consistent vocabulary across adapters.
  *
  * @type {Readonly<Record<string, Severity>>}
  */
@@ -113,9 +76,6 @@ export const SECURITY_REVIEW_SEVERITY_MAP = Object.freeze({
 });
 
 /**
- * Map a single security-review severity string onto the canonical
- * enum. Unknown / missing values collapse to `'suggestion'`.
- *
  * @param {unknown} raw
  * @returns {Severity}
  */
@@ -126,14 +86,6 @@ export function mapSecurityReviewSeverity(raw) {
 }
 
 /**
- * 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.
@@ -147,21 +99,7 @@ export function parseSecurityReviewFindings(rawStdout) {
   });
 }
 
-/**
- * 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.
- */
+/** Wraps `/security-review` with an explicit JSON-emit instruction. */
 const SECURITY_REVIEW_INVOKE_PROMPT =
   'Run /security-review against the diff `{baseRef}`...`{headRef}` ' +
   'for {scopeLabel} #{ticketId}. {depthDirective} After the review, emit ' +
@@ -174,13 +112,6 @@ const SECURITY_REVIEW_INVOKE_PROMPT =
   '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}
  */
@@ -200,11 +131,6 @@ export function buildSecurityReviewPrompt(input) {
 }
 
 /**
- * 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 }}
  */
@@ -223,10 +149,6 @@ function defaultInvokeSecurityReview(input) {
 }
 
 /**
- * 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() {
@@ -243,8 +165,6 @@ export function buildUnparseableFallbackFinding() {
 }
 
 /**
- * Build a `ReviewProvider` instance backed by `/security-review`.
- *
  * @param {{
  *   probeFn?: () => boolean,
  *   invokeFn?: (input: ReviewInput) => { status: number, stdout: string, stderr: string },
@@ -311,9 +231,6 @@ export function createSecurityReviewProvider(deps = {}) {
 }
 
 /**
- * Zero-arg factory entry point used by the `review-provider-factory`
- * registry. Mirrors `createCodexProviderForRegistry`.
- *
  * @returns {ReviewProvider}
  */
 export function createSecurityReviewProviderForRegistry() {

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

@@ -1,90 +1,60 @@
 /**
- * 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.
+ * review-providers/types.js — the pluggable Code Review contract, as
+ * `@typedef` lookups only (no runtime exports).
  *
  * @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 {Severity} severity
+ * @property {string}   title
+ * @property {string}   body         - Markdown.
  * @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').
+ * @property {number=}  line         - 1-based, when attributable.
+ * @property {string=}  category     - e.g. 'security', 'lint'.
  *
  * @typedef {'story'} 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. Derived from the diff's
- *   changed-file count and sensitive-path hits
- *   (`lib/orchestration/review-depth.js`; the judged-risk input was
- *   retired in #4542) 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`.
+ * @property {ReviewScope} scope
+ * @property {number}      ticketId
+ * @property {string}      baseRef
+ * @property {string}      headRef
+ * @property {ReviewDepth=} depth    - Diff-derived thoroughness lever; LLM-backed
+ *   providers MUST render it into their prompt. Absent → `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.
+ * Manual-prompt providers run no review; they contribute a one-line operator
+ * suggestion for tools that cannot be invoked programmatically.
  *
  * @typedef {object} ManualPromptResult
- * @property {string} message  - Markdown one-liner appended under "Manual review suggestions".
+ * @property {string} message
  *
  * @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.
+ * @property {ReviewScope}           scope
+ * @property {ReadonlyArray<string>} labels
  *
  * @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.
+ * @property {string}          name
+ * @property {ReviewProvider}  provider
+ * @property {ProviderGate}    gate      - 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.
+ * @property {string}                name
+ * @property {ManualPromptProvider}  provider
+ * @property {ProviderGate}          gate
  *
  * @typedef {object} ProviderChain
- * @property {InlineChainEntry[]} inline  - Inline adapters (run, merge Finding[]).
- * @property {PromptChainEntry[]} prompts - Manual-prompt adapters (render suggestion strings).
+ * @property {InlineChainEntry[]} inline
+ * @property {PromptChainEntry[]} prompts
  */
 
 export {};

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

@@ -1,22 +1,7 @@
 /**
- * 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
+ * review-providers/ultrareview.js — manual-prompt provider nudging the
+ * operator to run `/ultrareview`, which is user-triggered and cannot be
+ * invoked programmatically. Pure and host-agnostic (no CLI probe); it MUST
  * NEVER throw under any host.
  *
  * @typedef {import('./types.js').ManualPromptProvider} ManualPromptProvider
@@ -26,16 +11,6 @@
 
 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 — ' +
@@ -44,13 +19,6 @@ export const ULTRAREVIEW_PROMPT_TEMPLATE =
   '(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}
  */
@@ -65,13 +33,6 @@ export function buildUltrareviewMessage(input) {
 }
 
 /**
- * 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]
@@ -96,10 +57,6 @@ export function createUltrareviewProvider(deps = {}) {
 }
 
 /**
- * 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() {