mandrel 2.60.0 → 2.62.0

package/.agents/scripts/lib/orchestration/review-providers/parse-findings.js

@@ -1,47 +1,15 @@
 /**
- * review-providers/parse-findings.js — shared JSON-findings parser.
- *
- * Story #3981 — extracts the verbatim-duplicated parsing logic from
- * `parseCodexFindings` (codex.js) and `parseSecurityReviewFindings`
- * (security-review.js) into one templated parser. Both adapters emit
- * JSON; the parser is liberal in what it accepts:
- *   - A bare array of finding objects.
- *   - An object with a `findings` array.
- *   - Either shape wrapped in an outer envelope with a `result` or
- *     `data` key (covers minor wire-format drift across versions
- *     without re-shimming).
- *
- * Each entry's severity is funnelled through the caller-supplied
- * `mapSeverity` so the canonical enum is the only thing that reaches
- * the renderer. Entries without a `title` or `body` are skipped — the
- * orchestrator cannot post an empty finding, and silently dropping the
- * entry is safer than fabricating one.
- *
- * Per-provider deltas ride in as options:
- *   - `errorPrefix`     — prefix for the JSON-parse failure message.
- *   - `mapSeverity`     — provider severity vocabulary → canonical enum.
- *   - `defaultCategory` — when set, entries missing a `category` get
- *     this value (security-review defaults to `'security'`); when
- *     omitted, `category` is only set when present (codex behavior).
- *
- * Story #4074 — the parser body was a CC-30 ternary thicket. The
- * per-field branching now lives in three small, independently-testable
- * pure helpers (`unwrapEnvelope`, `coerceString`, `buildFinding`), so the
- * orchestration body collapses to: unwrap → `Array.isArray` guard →
- * `map(buildFinding).filter(Boolean)`.
+ * review-providers/parse-findings.js — the JSON-findings parser shared by the
+ * LLM-backed providers. Entries without a title or body are dropped rather
+ * than fabricated.
  *
  * @typedef {import('./types.js').Finding}  Finding
  * @typedef {import('./types.js').Severity} Severity
  */
 
 /**
- * Unwrap up to two layers of envelope around a findings array.
- *
- * Accepts a bare array unchanged, an object with a `findings` array, or
- * either shape nested one level deep under a `result` / `data` key. The
- * second pass resolves `{ result: { findings: [] } }`-style
- * double-envelopes. Anything that does not resolve to an array is
- * returned as-is for the caller's `Array.isArray` guard to reject.
+ * Unwrap a bare array, `{ findings }`, or either under `result`/`data`.
+ * A non-array result is returned for the caller to reject.
  *
  * @param {unknown} parsed
  * @returns {unknown}
@@ -60,11 +28,6 @@ export function unwrapEnvelope(parsed) {
 }
 
 /**
- * Coerce a value to a non-empty trimmed string, or null.
- *
- * Returns the trimmed string when `value` is a string with
- * non-whitespace content; otherwise null.
- *
  * @param {unknown} value
  * @returns {string | null}
  */
@@ -75,14 +38,8 @@ export function coerceString(value) {
 }
 
 /**
- * Build a single `Finding` from a raw entry, or null when the entry is
- * unusable (not an object, or missing a title/body).
- *
- * `title` is trimmed; `body` falls back to a non-empty `message` alias
- * and is preserved verbatim (untrimmed) to match the historical
- * behavior. `category` is set from the entry when present, else from
- * `defaultCategory` when supplied. `file` / `line` are included only
- * when present and well-formed.
+ * `body` (or its `message` alias) is kept untrimmed; `category` falls back
+ * to `defaultCategory`.
  *
  * @param {unknown} entry
  * @param {{
@@ -121,8 +78,6 @@ export function buildFinding(entry, { mapSeverity, defaultCategory }) {
 }
 
 /**
- * Parse a provider's raw stdout into `Finding[]`.
- *
  * @param {string} rawStdout
  * @param {{
  *   errorPrefix: string,

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

@@ -1,31 +1,11 @@
 /**
- * review-providers/review-depth.js — Shared depth-prompt vocabulary for the
- * LLM-backed review providers.
- *
- * Story #3937 / #3938 — the depth lever (`light` / `standard` / `deep`,
- * derived from the diff's observable width and sensitive-path hits by
- * `lib/orchestration/review-depth.js`; #4542 retired the judged-risk
- * input) is threaded into every
- * provider's `runReview` input. LLM-backed providers (codex, security-review,
- * ultrareview) must render that lever into the prompt/instructions they emit so
- * the model actually changes its thoroughness; the native (mechanical) provider
- * documents in its own JSDoc why depth does not change its lint +
- * maintainability sweep. This module is the single home for the depth → prose
- * mapping so the three LLM providers share one wording rather than each
- * re-spelling the semantics (which would cross the duplication gate).
- *
- * The mapping is intentionally model-agnostic: it describes *how thorough* the
- * review should be, not which tool runs it. A provider appends
- * `renderDepthDirective(depth)` to its prompt to instruct the model.
+ * review-providers/review-depth.js — the one depth → prompt-prose mapping the
+ * LLM-backed providers share; model-agnostic, it says how thorough to be.
  *
  * @typedef {import('./types.js').ReviewDepth} ReviewDepth
  */
 
 /**
- * Canonical per-depth review directive sentences. Keyed by the canonical
- * `ReviewDepth` enum. Exported so tests and doc tooling can assert against the
- * exact wording rather than free-text matching.
- *
  * @type {Readonly<Record<ReviewDepth, string>>}
  */
 const DEPTH_DIRECTIVES = Object.freeze({
@@ -45,11 +25,7 @@ const DEPTH_DIRECTIVES = Object.freeze({
 });
 
 /**
- * Normalize an arbitrary depth value to the canonical enum, defaulting to
- * `standard` for anything unrecognised (including `undefined` — providers may
- * receive an input without a depth from a caller that did not resolve one).
- *
- * Pure. Exported for testing.
+ * Anything unrecognised, including `undefined`, is `standard`.
  *
  * @param {unknown} depth
  * @returns {ReviewDepth}
@@ -59,12 +35,7 @@ function normalizeDepth(depth) {
 }
 
 /**
- * Render the depth directive sentence(s) for a given depth value, ready to
- * append to a provider's prompt. Always returns a non-empty string carrying a
- * `Review depth:` marker so connectivity tests can assert the lever reached the
- * prompt regardless of which tier resolved.
- *
- * Pure. Exported for testing.
+ * Always non-empty and carrying a `Review depth:` marker.
  *
  * @param {ReviewDepth|undefined} depth
  * @returns {string}

package/.agents/scripts/lib/orchestration/review-providers/review-provider-factory.js

@@ -1,27 +1,7 @@
 /**
- * review-providers/review-provider-factory.js — resolve
- * `codeReview.providers` to a concrete `ReviewProvider` instance.
- *
- * Story #2825 (Epic #2815) — the factory is the only entry point.
- * `runCodeReview()` never references a specific adapter directly;
- * adding a backend is (1) implement the interface, (2) register here,
- * (3) extend the schema enum.
- *
- * Story #2871 — the factory always returns a `ChainProvider` that
- * fans out `runReview` across every inline entry (merging `Finding[]`
- * in declaration order) and exposes `getPromptMessages` so the
- * orchestrator can render the trailing "Manual review suggestions"
- * section without knowing about per-provider mechanics.
- *
- * Behaviour:
- *   - Unset / empty `codeReview.providers` defaults to a single-entry
- *     chain `[{ name: 'native' }]`.
- *   - Unknown provider name throws an Error with remediation text
- *     naming the supported values.
- *   - Adapters that throw at construction time (e.g. `codex` probing
- *     for an absent plugin command) bubble their error verbatim —
- *     EXCEPT when the chain entry carries `optional: true`, in which
- *     case the chain logs a warning and skips that entry.
+ * review-providers/review-provider-factory.js — resolves
+ * `codeReview.providers` into a `ChainProvider`. A failing entry throws
+ * unless it is `optional`.
  *
  * @typedef {import('./types.js').ReviewProvider}        ReviewProvider
  * @typedef {import('./types.js').ManualPromptProvider}  ManualPromptProvider
@@ -40,12 +20,7 @@ import { createNativeProviderForRegistry } from './native.js';
 import { createSecurityReviewProviderForRegistry } from './security-review.js';
 import { createUltrareviewProviderForRegistry } from './ultrareview.js';
 
-/**
- * Inline provider registry — entries return a `ReviewProvider` that
- * produces `Finding[]` from a git diff.
- *
- * @type {Readonly<Record<string, () => ReviewProvider>>}
- */
+/** @type {Readonly<Record<string, () => ReviewProvider>>} */
 const INLINE_PROVIDERS = Object.freeze({
   codex: createCodexProviderForRegistry,
   native: createNativeProviderForRegistry,
@@ -53,9 +28,7 @@ const INLINE_PROVIDERS = Object.freeze({
 });
 
 /**
- * Manual-prompt provider registry — entries return a
- * `ManualPromptProvider` that contributes a non-blocking operator
- * suggestion to the structured comment without running a review.
+ * Non-blocking operator suggestions; they run no review.
  *
  * @type {Readonly<Record<string, () => ManualPromptProvider>>}
  */
@@ -63,18 +36,10 @@ const PROMPT_PROVIDERS = Object.freeze({
   ultrareview: createUltrareviewProviderForRegistry,
 });
 
-/**
- * The inline provider name used when `codeReview.providers` is unset,
- * empty, or the `codeReview` block is absent entirely.
- */
 export const DEFAULT_PROVIDER_NAME = 'native';
 
 /**
- * Pure: build a gate predicate from a chain entry's `when` clause.
- * Currently supports `label` (single string) and `labelAny`
- * (string[]); other keys are rejected at the schema layer.
- *
- * `when` absent → gate is "always true".
+ * Gate predicate from a `when` clause (`label` / `labelAny`); absent → always true.
  *
  * @param {{ label?: string, labelAny?: string[] }|undefined} when
  * @returns {ProviderGate}
@@ -100,10 +65,7 @@ export function buildGate(when) {
 }
 
 /**
- * Pure: scope filter — true when the entry's declared scope list
- * includes the current invocation scope. Default (no `scopes`) is
- * "fires on both" so unattended chains keep working at story-close
- * and epic-finalize alike.
+ * No declared `scopes` fires on every scope.
  *
  * @param {string[]|undefined} declaredScopes
  * @param {string} currentScope
@@ -117,12 +79,7 @@ export function isScopeApplicable(declaredScopes, currentScope) {
 }
 
 /**
- * Resolve a `ReviewProvider` instance from the resolved agentrc
- * config block. Pass the `codeReview` sub-object (not the full
- * config) so callers can compose with their own config readers.
- *
- * Always returns a `ChainProvider`. When `codeReviewConfig.providers`
- * is unset or empty, the chain defaults to `[{ name: 'native' }]`.
+ * Takes the `codeReview` sub-object; unset/empty `providers` defaults to native.
  *
  * @param {{
  *   providers?: Array<object>,
@@ -159,11 +116,6 @@ export function createReviewProvider(codeReviewConfig, opts = {}) {
 }
 
 /**
- * Build the inline + prompt entry list from a `providers: []` config.
- * Pure with respect to registry inputs — the registry is the only
- * side-effectful surface (provider constructors may probe disk or
- * spawn binaries).
- *
  * @param {Array<object>} entries
  * @param {{
  *   inlineRegistry: Readonly<Record<string, () => ReviewProvider>>,
@@ -242,10 +194,8 @@ export function buildProviderChain(entries, ctx) {
 }
 
 /**
- * Wrap a resolved chain in a single `ReviewProvider`-compatible
- * object that the orchestrator can call uniformly. Inline adapters
- * fan out via `runReview`; prompt adapters fan out via
- * `getPromptMessages` (a method the orchestrator feature-detects).
+ * Inline findings merge in declaration order; prompt entries render via
+ * `getPromptMessages`.
  *
  * @param {ProviderChain} chain
  * @param {{ logger?: { info?: Function, warn?: Function } }} [opts]
@@ -290,8 +240,7 @@ export function createChainProvider(chain, opts = {}) {
       return merged;
     },
     /**
-     * Degraded gates across the inline chain (Story #4839). Called after
-     * `runReview`.
+     * Called after `runReview`.
      *
      * @returns {Promise<Array<object>>}
      */
@@ -337,9 +286,6 @@ export function createChainProvider(chain, opts = {}) {
 }
 
 /**
- * Expose the registered provider names — primarily for diagnostics
- * and test fixtures. Lists both inline and prompt providers.
- *
  * @returns {string[]}
  */
 export function listRegisteredProviders() {
@@ -351,10 +297,6 @@ export function listRegisteredProviders() {
 }
 
 /**
- * Expose the inline-only provider names — used by adapter tests that
- * need to assert against the inline registry without coupling to
- * manual-prompt entries.
- *
  * @returns {string[]}
  */
 export function listInlineProviders() {
@@ -362,8 +304,6 @@ export function listInlineProviders() {
 }
 
 /**
- * Expose the manual-prompt-only provider names.
- *
  * @returns {string[]}
  */
 export function listPromptProviders() {

package/.agents/scripts/lib/orchestration/review-providers/scoped-lint.js

@@ -1,98 +1,30 @@
 /**
- * review-providers/scoped-lint.js — the scoped-lint surface of the native
- * review provider (extracted from `native.js` by Story #4839).
- *
- * ## Why this module exists
- *
- * The scoped-lint gate reported `executionFailed` — and therefore emitted zero
- * findings while the review reported clean — on 18 of 23 Beestera/swarm-os
- * Stories carrying friction (78%) and on 5 mandrel Stories. Measured
- * 2026-07-29, the cause was **not** environmental and **not** a parse failure.
- * Three defects in how the runners were invoked and reconciled produced the
- * same symptom:
- *
- * 1. **The markdown runner was never resolvable.** The provider spawned
- *    `npx --no markdownlint`, but the binary this project (and the consumer)
- *    installs is `markdownlint-cli2` — `markdownlint-cli2` is the package and
- *    the bin name; a bare `markdownlint` bin does not exist. `npx --no` with an
- *    unresolvable bin exits 1 printing `could not determine executable to run`
- *    and nothing else, so the summary parsed nothing and the gate degraded.
- *    The parser was already written for **cli2's** `Summary: N error(s)` line,
- *    so the invocation and the parser had never agreed. The `--ignore
- *    node_modules` flag was likewise `markdownlint-cli` (v1) syntax, which
- *    cli2 does not accept. Fix: resolve the runner from what is actually
- *    installed and pass each candidate its own argument shape.
- *
- * 2. **One runner's failure poisoned the other's verdict.** The two runs were
- *    folded into a *single* `parseLintOutput` call over concatenated output and
- *    the maximum exit status. So the unresolvable markdown runner's exit 1
- *    became the verdict for biome too: any change set containing at least one
- *    `.md` file degraded the whole gate whenever biome itself had nothing to
- *    report — i.e. exactly the clean case the gate exists to confirm. Fix:
- *    classify each surface independently and merge structurally.
- *
- * 3. **Biome's "nothing in scope" exit was read as a failure.** `biome lint`
- *    exits 1 with `No files were processed in the specified paths.` when every
- *    supplied path is excluded by `biome.json` (`temp/`, `dist/`,
- *    `.worktrees/`, anything in the VCS ignore file). That is an empty scope,
- *    not a runner that could not execute. Fix: recognise the sentinel.
- *
- * ## What a degraded surface now produces
- *
- * `runScopedLint` still reports `executionFailed` — the friction-telemetry
- * emission in `native.js` is deliberately unchanged (Story #4699 routed an
- * unexecutable tool to telemetry so severity tiers reflect code findings only,
- * and that intent stands). It additionally reports a `degradations[]` array
- * naming **which** surface could not run and **why**, so the review outcome can
- * say "this gate did not run" instead of silently reading clean.
- *
- * ## The code surface never got the same treatment (Story #5193)
- *
- * Story #4839 gave the *markdown* surface a disk probe and left the code
- * surface spawning `npx --no biome` and classifying the exit code. On npm 11.x
- * that spawn exits **0 with empty output** when biome is absent, so
- * `parseLintOutput` saw no failure, produced no degradation, and the surface
- * contributed `errors: 0, warnings: 0` — a *silent false clean*, which is
- * strictly worse than a degradation: a degraded surface announces itself, a
- * falsely-clean one is trusted. Since nothing in the framework requires either
- * runner, "absent" is the default state of a consumer checkout.
- *
- * Fix: runner resolution is a **precondition** for every surface, not an
- * outcome inferred from an exit code. Both surfaces now resolve through
- * {@link resolveRunner}, and an unresolved runner is never spawned.
- *
- * The same measurement invalidated the `NPX_UNRESOLVABLE` sentinel: current npm
- * answers an unresolvable bin with `npm error code E404`, not `could not
- * determine executable to run`, so every genuinely-unresolvable runner was
- * being labelled `unparseable-output`. The sentinel now recognises both shapes.
- * It still earns its keep after the disk probe: the probe only sees
- * `node_modules/.bin`, so a runner resolvable some other way can still fail.
+ * review-providers/scoped-lint.js — scoped biome + markdownlint over the
+ * changed surface. Runners resolve on disk before spawning (`npx --no biome`
+ * exits 0 silently when biome is absent), and each surface is classified
+ * independently so one failure cannot become the other's verdict.
  */
 
 import { spawnSync } from 'node:child_process';
 import { existsSync } from 'node:fs';
 import path from 'node:path';
 
-/** Paths these extensions land on the biome (code) runner. */
 const CODE_EXTENSIONS = /\.(js|mjs|cjs|jsx|ts|tsx|json|jsonc)$/i;
 
 /**
- * npx's output when the requested bin cannot be resolved. Two shapes: the
- * legacy message, and the `E404` current npm answers with instead (measured
- * 2026-09-07 on npm 11.13.0). Matching the E404 *code* rather than any
- * `npm error` line keeps a genuine runner error out of this classification.
+ * npx's unresolvable-bin output: the legacy message or current npm's E404.
+ * Matching the E404 code, not any `npm error` line, keeps genuine runner
+ * errors out.
  */
 const NPX_UNRESOLVABLE =
   /could not determine executable to run|npm (?:error|ERR!)\s+code\s+E404/i;
 
-/** Biome's exit-1 message when every supplied path is config-excluded. */
+/** Biome's exit-1 when every path is config-excluded: an empty scope, not a failure. */
 const BIOME_EMPTY_SCOPE = /No files were processed in the specified paths/i;
 
 /**
- * Markdown runners in preference order, each with the argument shape *it*
- * accepts. `markdownlint-cli2` takes bare paths/globs and rejects `--ignore`;
- * `markdownlint` (cli v1) takes `--ignore`. Explicit changed-file paths are
- * passed either way, so the v1 ignore flag is belt-and-braces only.
+ * Markdown runners in preference order, each with its own argument shape:
+ * cli2 rejects `--ignore`, which cli v1 takes.
  */
 const MARKDOWN_RUNNERS = Object.freeze([
   Object.freeze({ bin: 'markdownlint-cli2', extraArgs: Object.freeze([]) }),
@@ -102,16 +34,10 @@ const MARKDOWN_RUNNERS = Object.freeze([
   }),
 ]);
 
-/**
- * Code runners in preference order. `@biomejs/biome` installs a bare `biome`
- * bin, which is also the canonical name this surface reports itself under when
- * nothing resolves.
- */
 const CODE_RUNNERS = Object.freeze([
   Object.freeze({ bin: 'biome', extraArgs: Object.freeze([]) }),
 ]);
 
-/** Reason codes carried on a degradation record. */
 const DEGRADATION_REASONS = Object.freeze({
   RUNNER_NOT_INSTALLED: 'runner-not-installed',
   RUNNER_NOT_RESOLVABLE: 'runner-not-resolvable',
@@ -140,22 +66,9 @@ function spawnLintRunner(bin, args, cwd) {
 }
 
 /**
- * Pure-ish: pick the first candidate whose bin is actually installed under
- * `<cwd>/node_modules/.bin`. Returns `null` when none is — an honest "this
- * surface has no runner" that the caller reports rather than silently folding
- * into a generic parse failure.
- *
- * The disk probe (rather than "spawn and see") is what makes the failure
- * *nameable*, and — since Story #5193 — what makes it *visible at all* on the
- * code surface: `npx --no <missing-bin>` answers with a generic npm error at
- * best and an empty exit 0 at worst, which is precisely how both defects hid.
- *
- * Probing `node_modules/.bin` only is a deliberate bound: a globally-installed
- * runner reads as absent here, which degrades the gate honestly rather than
- * trusting a spawn nobody resolved.
- *
- * Not exported: it is reachable — and asserted — through {@link runScopedLint},
- * whose `existsFn` seam drives every resolution branch.
+ * First candidate installed under `<cwd>/node_modules/.bin`, else `null`.
+ * Deliberately local-only: a global runner reads as absent and degrades
+ * honestly rather than trusting an unresolved spawn.
  *
  * @param {ReadonlyArray<{ bin: string, extraArgs: ReadonlyArray<string> }>} candidates
  * @param {string} cwd
@@ -177,9 +90,7 @@ function resolveRunner(candidates, cwd, existsFn) {
 }
 
 /**
- * Pure: the summary a surface reports when it has no runner to spawn. Counts
- * are zero *and* `executionFailed` is true, so the row can never be read as a
- * clean result — the invariant Story #5193 restored.
+ * Zero counts with `executionFailed: true`, so it can never read as clean.
  *
  * @returns {ReturnType<typeof parseLintOutput>}
  */
@@ -196,7 +107,6 @@ function unresolvedRunnerSummary() {
 
 /**
  * Resolve one surface's runner and, only if it resolved, spawn and classify it.
- * Shared by both surfaces so neither can drift back into spawn-and-see.
  *
  * @param {{
  *   label: string,
@@ -220,8 +130,6 @@ function runSurface({ label, candidates, buildArgs, cwd, runnerFn, existsFn }) {
 }
 
 /**
- * Pure: split changed paths into the file lists each lint runner consumes.
- *
  * @param {string[]} changedFiles
  * @returns {{ code: string[], md: string[] }}
  */
@@ -236,16 +144,8 @@ export function partitionFilesForLint(changedFiles) {
 }
 
 /**
- * Pure: classify **one** runner's result into a summary.
- *
- * Handles the reporter formats composing `npm run lint` here:
- *   - Biome: `Found N error(s).` / `Found N warning(s).`
- *   - markdownlint-cli2: a trailing `Summary: N error(s)` line.
- *
- * A non-zero exit whose output matches no known reporter format is "could not
- * classify" → `executionFailed: true`, with `reason` naming what was actually
- * observed. Biome's empty-scope exit is recognised separately as
- * `emptyScope` — nothing to lint is not a broken runner.
+ * A non-zero exit matching no reporter format is `executionFailed`, except
+ * biome's empty-scope exit.
  *
  * @param {{ status?: number, stdout?: string, stderr?: string }} result
  * @returns {{ errors: number, warnings: number, parsed: boolean, executionFailed: boolean, emptyScope: boolean, reason: string|null }}
@@ -284,18 +184,8 @@ export function parseLintOutput(result) {
 }
 
 /**
- * Pure: merge per-surface summaries into the gate's single summary. Counts add;
- * `executionFailed` is the OR across surfaces; each failed surface contributes
- * one degradation record naming itself. Merging *summaries* rather than raw
- * output is what stops one runner's failure from becoming the other's verdict.
- *
- * The OR is deliberately lossy — it answers "did any surface fail?", which is
- * the only question the degradation channel asks. Story #5282 added the
- * `surfaces[]` rows so a consumer can ask the *other* questions the OR cannot
- * answer: which surface the merged counts came from, and — via each row's
- * `parsed` and `executionFailed` — whether an absent biome or a biome run that
- * simply reported nothing is behind a zero. Consumers that read the flat
- * counts are unaffected; the rows are additive.
+ * Counts add and `executionFailed` is the OR; `surfaces[]` keeps what the
+ * lossy OR cannot answer.
  *
  * @param {Array<{ surface: string, summary: ReturnType<typeof parseLintOutput> }>} surfaces
  */
@@ -325,12 +215,10 @@ function mergeSurfaceSummaries(surfaces) {
 }
 
 /**
- * Run lint scoped to the changed surface only.
- *
  * @param {string[]} changedFiles
  * @param {string} cwd
  * @param {typeof spawnLintRunner} [runnerFn]
- * @param {{ existsFn?: (p: string) => boolean }} [deps]  Test seam for runner resolution.
+ * @param {{ existsFn?: (p: string) => boolean }} [deps]
  * @returns {{ errors: number, warnings: number, parsed: boolean, skipped: boolean, mode: 'changed-only'|'off', executionFailed: boolean, degradations: Array<{ surface: string, reason: string }>, surfaces: Array<{ surface: string, parsed: boolean, errors: number, warnings: number, executionFailed: boolean }> }}
  */
 export function runScopedLint(