mandrel 1.94.0 → 2.1.0

package/.agents/scripts/lib/orchestration/retro-proposals.js

@@ -42,7 +42,8 @@
  * @property {string} [summary]
  *
  * @typedef {Object} RoutedProposalsInput
- * @property {number}                epicId
+ * @property {number}                anchorId      Story or run/Epic id in titles.
+ * @property {'story'|'run'}  [anchorKind]    Wording in titles/bodies (default `story`).
  * @property {string}                frameworkRepo   `"<owner>/<repo>"`.
  * @property {string}                consumerRepo    `"<owner>/<repo>"`.
  * @property {FrictionSignal[]}      [signals]
@@ -142,23 +143,53 @@ function dominantSource(entry) {
   return entry.firstSource;
 }
 
+/**
+ * @param {'story'|'run'} kind
+ * @param {number} id
+ * @returns {string}
+ */
+function formatAnchor(kind, id) {
+  if (kind === 'story') return `Story #${id}`;
+  if (kind === 'run') return `plan-run ${id}`;
+  return `Epic #${id}`;
+}
+
+/** Story scope promotes single-occurrence friction; run keeps ≥2. */
+function isActionableFriction(total, force, anchorKind) {
+  const threshold = anchorKind === 'story' ? 1 : 2;
+  return total >= threshold || Boolean(force);
+}
+
 /**
  * Render the issue body. Plain text — no markdown headings — so the
  * pre-drafted `gh issue create --body-file` heredoc remains a faithful
  * representation of what the operator would paste.
  *
- * @param {{ epicId: number, category: string, occurrences: number, source: "framework"|"consumer" }} args
+ * @param {{
+ *   anchorId: number,
+ *   anchorKind: 'story'|'run',
+ *   category: string,
+ *   occurrences: number,
+ *   source: "framework"|"consumer",
+ * }} args
  * @returns {string}
  */
-function renderIssueBody({ epicId, category, occurrences, source }) {
+function renderIssueBody({
+  anchorId,
+  anchorKind,
+  category,
+  occurrences,
+  source,
+}) {
+  const anchor = formatAnchor(anchorKind, anchorId);
   return [
-    `Recurring friction category "${category}" surfaced ${occurrences} times during Epic #${epicId}.`,
+    `Recurring friction category "${category}" surfaced ${occurrences} times during ${anchor}.`,
     '',
     `Source classification: ${source}.`,
     '',
-    'Captured by the routed-retro composer (Story #2558). Triage and either:',
+    'Captured by the follow-up composer. Triage and either:',
     `- File a follow-on Story to address the underlying ${source} gap, or`,
-    '- Close with "wont-fix" and document the rationale in the Epic retro thread.',
+    `- Close with "wontfix" and document the rationale on ${anchor}.`,
   ].join('\n');
 }
 
@@ -193,7 +224,8 @@ function renderIssueCommand({ repo, title, metaLabel, category, body }) {
  * Build an actionable RoutedItem for a category.
  *
  * @param {{
- *   epicId: number,
+ *   anchorId: number,
+ *   anchorKind: 'story'|'run',
  *   category: string,
  *   occurrences: number,
  *   source: "framework"|"consumer",
@@ -203,15 +235,23 @@ function renderIssueCommand({ repo, title, metaLabel, category, body }) {
  * @returns {RoutedItem}
  */
 function buildRoutedItem({
-  epicId,
+  anchorId,
+  anchorKind,
   category,
   occurrences,
   source,
   frameworkRepo,
   consumerRepo,
 }) {
-  const title = `Friction: ${category} recurred ${occurrences} times in Epic #${epicId}`;
-  const body = renderIssueBody({ epicId, category, occurrences, source });
+  const anchor = formatAnchor(anchorKind, anchorId);
+  const title = `Friction: ${category} recurred ${occurrences} times in ${anchor}`;
+  const body = renderIssueBody({
+    anchorId,
+    anchorKind,
+    category,
+    occurrences,
+    source,
+  });
   const repo = source === 'framework' ? frameworkRepo : consumerRepo;
   const metaLabel =
     source === 'framework' ? 'framework-gap' : 'consumer-improvement';
@@ -231,23 +271,29 @@ function buildRoutedItem({
  *
  * @param {unknown} input
  * @returns {{
- *   epicId: number,
+ *   anchorId: number,
+ *   anchorKind: 'story'|'run',
  *   frameworkRepo: string,
  *   consumerRepo: string,
  *   signals: FrictionSignal[],
  *   unresolvedBlockedEvents: BlockedEvent[],
  * } | null}
  */
+function normalizeAnchorKind(kind) {
+  return kind === 'story' || kind === 'run' ? kind : 'story';
+}
+
 function normaliseInput(input) {
   if (input === null || typeof input !== 'object') return null;
   const record = /** @type {RoutedProposalsInput} */ (input);
-  const epicId = Number(record.epicId);
-  if (!Number.isInteger(epicId) || epicId <= 0) return null;
+  const anchorId = Number(record.anchorId);
+  if (!Number.isInteger(anchorId) || anchorId <= 0) return null;
   const frameworkRepo = asString(record.frameworkRepo);
   const consumerRepo = asString(record.consumerRepo);
-  if (frameworkRepo.length === 0 || consumerRepo.length === 0) return null;
+  if (!frameworkRepo || !consumerRepo) return null;
   return {
-    epicId,
+    anchorId,
+    anchorKind: normalizeAnchorKind(record.anchorKind),
     frameworkRepo,
     consumerRepo,
     signals: Array.isArray(record.signals) ? record.signals : [],
@@ -257,35 +303,7 @@ function normaliseInput(input) {
   };
 }
 
-/**
- * Compose the four routed proposal sections from aggregated source-tagged
- * signals.
- *
- * Pure — no I/O, no time-dependent state, no provider calls. Returns an
- * object with three arrays:
- *   - `framework`: actionable items routed to the framework repo.
- *   - `consumer`: actionable items routed to the consumer repo.
- *   - `discarded`: single-occurrence friction with no follow-on signal.
- *
- * @param {RoutedProposalsInput} input
- * @returns {RoutedProposals}
- */
-export function composeRoutedProposals(input) {
-  const normalised = normaliseInput(input);
-  if (normalised === null) return emptyResult();
-  const {
-    epicId,
-    frameworkRepo,
-    consumerRepo,
-    signals,
-    unresolvedBlockedEvents,
-  } = normalised;
-
-  const byCategory = aggregateByCategory(signals);
-
-  // Unresolved agent::blocked events always promote their category to
-  // actionable — even if the friction count is < 2. The event itself
-  // doesn't count as a friction occurrence; we treat it as a force-flag.
+function blockedForceMap(unresolvedBlockedEvents) {
   /** @type {Map<string, { source: "framework"|"consumer" }>} */
   const blockedForceActionable = new Map();
   for (const evt of unresolvedBlockedEvents) {
@@ -297,56 +315,99 @@ export function composeRoutedProposals(input) {
       blockedForceActionable.set(category, { source });
     }
   }
+  return blockedForceActionable;
+}
 
-  /** @type {RoutedItem[]} */
-  const framework = [];
-  /** @type {RoutedItem[]} */
-  const consumer = [];
-  /** @type {DiscardedItem[]} */
-  const discarded = [];
+function pushRouted(buckets, source, item) {
+  if (source === 'framework') buckets.framework.push(item);
+  else buckets.consumer.push(item);
+}
 
-  // Walk categories present in friction signals first.
+function routeCategoryBuckets({
+  byCategory,
+  blockedForceActionable,
+  anchorId,
+  anchorKind,
+  frameworkRepo,
+  consumerRepo,
+}) {
+  /** @type {RoutedProposals} */
+  const buckets = { framework: [], consumer: [], discarded: [] };
   for (const entry of byCategory.values()) {
     const { category, total } = entry;
     const force = blockedForceActionable.get(category);
     const source = force ? force.source : dominantSource(entry);
-    const actionable = total >= 2 || Boolean(force);
-    if (actionable) {
-      const item = buildRoutedItem({
-        epicId,
+    if (!isActionableFriction(total, force, anchorKind)) {
+      buckets.discarded.push({ category, occurrences: total, source });
+      continue;
+    }
+    pushRouted(
+      buckets,
+      source,
+      buildRoutedItem({
+        anchorId,
+        anchorKind,
         category,
         occurrences: total,
         source,
         frameworkRepo,
         consumerRepo,
-      });
-      if (source === 'framework') framework.push(item);
-      else consumer.push(item);
-      continue;
-    }
-    // total === 1 AND no force flag → discarded.
-    discarded.push({ category, occurrences: total, source });
+      }),
+    );
   }
-
-  // Walk blocked-force categories that had NO friction signal at all —
-  // these still need an issue proposal (the blocker is the trigger).
   for (const [category, info] of blockedForceActionable) {
     if (byCategory.has(category)) continue;
-    const item = buildRoutedItem({
-      epicId,
-      category,
-      occurrences: 0,
-      source: info.source,
-      frameworkRepo,
-      consumerRepo,
-    });
-    if (info.source === 'framework') framework.push(item);
-    else consumer.push(item);
+    pushRouted(
+      buckets,
+      info.source,
+      buildRoutedItem({
+        anchorId,
+        anchorKind,
+        category,
+        occurrences: 0,
+        source: info.source,
+        frameworkRepo,
+        consumerRepo,
+      }),
+    );
   }
+  buckets.framework.sort((a, b) => a.category.localeCompare(b.category));
+  buckets.consumer.sort((a, b) => a.category.localeCompare(b.category));
+  buckets.discarded.sort((a, b) => a.category.localeCompare(b.category));
+  return buckets;
+}
 
-  framework.sort((a, b) => a.category.localeCompare(b.category));
-  consumer.sort((a, b) => a.category.localeCompare(b.category));
-  discarded.sort((a, b) => a.category.localeCompare(b.category));
+/**
+ * Compose the four routed proposal sections from aggregated source-tagged
+ * signals.
+ *
+ * Pure — no I/O, no time-dependent state, no provider calls. Returns an
+ * object with three arrays:
+ *   - `framework`: actionable items routed to the framework repo.
+ *   - `consumer`: actionable items routed to the consumer repo.
+ *   - `discarded`: single-occurrence friction with no follow-on signal.
+ *
+ * @param {RoutedProposalsInput} input
+ * @returns {RoutedProposals}
+ */
+export function composeRoutedProposals(input) {
+  const normalised = normaliseInput(input);
+  if (normalised === null) return emptyResult();
+  const {
+    anchorId,
+    anchorKind,
+    frameworkRepo,
+    consumerRepo,
+    signals,
+    unresolvedBlockedEvents,
+  } = normalised;
 
-  return { framework, consumer, discarded };
+  return routeCategoryBuckets({
+    byCategory: aggregateByCategory(signals),
+    blockedForceActionable: blockedForceMap(unresolvedBlockedEvents),
+    anchorId,
+    anchorKind,
+    frameworkRepo,
+    consumerRepo,
+  });
 }

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

@@ -1,42 +1,117 @@
 /**
- * lib/orchestration/review-depth.js — Shared review-depth resolver combining
- * judged risk and mechanical diff width (Story #3938).
+ * lib/orchestration/review-depth.js — the review-depth authority: derives a
+ * change level from observable facts and folds it with diff width into a tier
+ * (Story #3938, re-based on a derived signal by Story #4542).
  *
- * The single depth authority for the code-review pipeline. It folds the two
- * signals the framework already computes — the planner-judged risk
- * (`planningRisk.overallLevel`) and the mechanical changed-file count of the
- * diff under review — into one tier (`light` / `standard` / `deep`) without
- * inventing a new complexity score or any new config knob.
+ * ## Why the level is derived, not authored
  *
- * Tier rules:
- *   - `deep`     — `overallLevel === 'high'` OR the changed-file count exceeds
- *                  the wide-change scale (`sizing.hardFiles`). A wide-footprint
- *                  Epic whose risk was judged low (or never judged) still earns
- *                  a deep pass on size alone.
- *   - `light`    — `overallLevel === 'low'` AND the changed-file count is at or
- *                  below the small-change scale (`sizing.softFiles`). An
- *                  *unknown* count does NOT block `light`: a missing diff width
- *                  is treated as "not wide", so a low-risk Epic with no count
- *                  still resolves to `light` (preserves the #3937 producer
- *                  contract where depth is resolved from risk before any diff
- *                  is enumerated).
- *   - `standard` — everything else, including absent/malformed risk envelopes
- *                  and a `medium` level. Fail toward the middle, never toward
- *                  `light`: an Epic that skipped `/plan` has no risk
- *                  verdict, and treating it as `light` would under-review
- *                  unjudged work while `standard` preserves today's behaviour.
+ * This module used to consume `planningRisk.overallLevel` — a level the planner
+ * asserted about the plan it had just written. That signal was self-refereed and
+ * its fail-safe ran backwards: an *absent* verdict degraded toward MORE ceremony
+ * (standard depth), while a schema-valid all-low verdict bought `light`. Nothing
+ * cross-checked the claimed axes against the files actually touched, so the one
+ * input that could *reduce* review was exactly the one nobody verified. Story
+ * #4542 inverted that: the level is now derived at close time from the changed
+ * files themselves, which makes it a fact rather than a claim — and therefore
+ * trustworthy enough to reduce ceremony on.
  *
- * Pure and total: inputs in, tier out. No I/O, no throws. `null` / `undefined`
- * / malformed inputs all degrade to `standard` (or `deep`/`light` only when the
- * width signal unambiguously says so). Callers (e.g. `runCodeReview`) enumerate
- * the changed-file count from the diff they already run and supply it here, and
- * pass the operator's `planning.taskSizing` override as `sizing` so retuning
- * sizing retunes the depth thresholds in lockstep with the ticket validator.
+ * ## The two signals
+ *
+ *   - **Sensitive paths** ({@link deriveChangeLevel}) — the changed-file set
+ *     intersected with the `sensitivePaths` classes registered in
+ *     `.agents/schemas/audit-rules.json` (auth, migrations, billing, destructive
+ *     mutation, public API). Registered as **configuration**, matched with the
+ *     audit-suite's existing picomatch machinery. This is what keeps a *narrow*
+ *     high-stakes diff — a three-file auth fix, a small migration — at `deep`,
+ *     the one thing a pure width heuristic would miss.
+ *   - **Diff width** — the mechanical changed-file count, unchanged in role.
+ *
+ * ## Tier rules ({@link resolveDepth})
+ *
+ *   - `deep`     — `derivedLevel === 'high'` (a sensitive path was touched) OR
+ *                  the changed-file count exceeds the wide-change scale
+ *                  (`diffWidth.hardFiles`). A wide diff earns a deep pass on
+ *                  size alone even when it touches nothing sensitive.
+ *   - `light`    — `derivedLevel === 'low'` (the change set is known and touches
+ *                  no sensitive path) AND the count is at or below the
+ *                  small-change scale (`diffWidth.softFiles`). An *unknown*
+ *                  count does not block `light`: a missing width is treated as
+ *                  "not wide".
+ *   - `standard` — everything else, including an absent/underivable level. Fail
+ *                  toward the middle, never toward `light`: when the diff cannot
+ *                  be enumerated there is no evidence the change is safe, and
+ *                  `standard` preserves today's behaviour.
+ *
+ * {@link resolveDepth} is pure and total: inputs in, tier out. No I/O, no
+ * throws. `null` / `undefined` / malformed inputs degrade to `standard` (or
+ * `deep`/`light` only when a signal unambiguously says so). {@link
+ * deriveChangeLevel} owns the one manifest read and is likewise total — any
+ * failure degrades to the `null` (fail-safe) level.
+ *
+ * v2 Stage 2: review depth is **decoupled** from the planning model-capacity
+ * advisory. Diff width is a mechanical review signal (files in the landed
+ * diff); planning capacity is an absolute authored-token session-mass signal.
+ * The two no longer share a constant.
  *
  * @typedef {'light'|'standard'|'deep'} ReviewDepth
+ * @typedef {'low'|'high'} ChangeLevel
  */
 
-import { DEFAULT_TASK_SIZING } from './ticket-validator-sizing.js';
+import { selectSensitivePathClasses } from '../audit-suite/selector.js';
+
+/**
+ * Mechanical diff-width scales for review-depth tiering. These are **not**
+ * planning Story-sizing ceilings (those are gone in v2) — they only classify
+ * the changed-file count of a diff under review.
+ */
+export const DEFAULT_DIFF_WIDTH = Object.freeze({
+  softFiles: 15,
+  hardFiles: 30,
+});
+
+/**
+ * Derive the change level for a change set from observable facts: does the
+ * changed-file set intersect any sensitive-path class registered in
+ * `audit-rules.json`?
+ *
+ * This is the **single source** of the derived level — both the review depth
+ * ({@link resolveDepth}) and the acceptance-critic fresh-vs-inline routing
+ * (`ceremony-routing.js#resolveCeremonyForRisk`) consume what this returns, so
+ * the two ceremony decisions can never disagree about how risky a change is.
+ *
+ * Returns `null` — the fail-safe "no derivable signal" level — when the change
+ * set is empty/unknown or the manifest cannot be read. Both downstream
+ * consumers treat `null` as the more thorough posture (`standard` depth, a
+ * `fresh` critic), so a derivation failure never buys a change less checking.
+ *
+ * Total: never throws.
+ *
+ * @param {{
+ *   changedFiles?: string[]|null,
+ *   injectedRules?: object,
+ *   selectSensitivePathClassesFn?: typeof selectSensitivePathClasses,
+ * }} [input]
+ * @returns {{ level: ChangeLevel|null, classes: string[] }}
+ */
+export function deriveChangeLevel(input = {}) {
+  const changedFiles =
+    input && typeof input === 'object' ? input.changedFiles : null;
+  if (!Array.isArray(changedFiles) || changedFiles.length === 0) {
+    return { level: null, classes: [] };
+  }
+
+  const select =
+    input.selectSensitivePathClassesFn ?? selectSensitivePathClasses;
+  let classes;
+  try {
+    classes = select({ changedFiles, injectedRules: input.injectedRules });
+  } catch {
+    // An unreadable/invalid manifest is not evidence the change is safe.
+    return { level: null, classes: [] };
+  }
+  const matched = Array.isArray(classes) ? classes : [];
+  return { level: matched.length > 0 ? 'high' : 'low', classes: matched };
+}
 
 /**
  * Coerce an arbitrary input into a non-negative integer changed-file count, or
@@ -54,40 +129,44 @@ function normalizeChangedFileCount(value) {
 }
 
 /**
- * Resolve the review depth for a change set from its judged risk and diff
- * width. See the module header for the tier rules.
+ * Resolve the review depth for a change set from its derived level (see
+ * {@link deriveChangeLevel}) and diff width. See the module header for the tier
+ * rules.
  *
  * @param {{
- *   overallLevel?: ('low'|'medium'|'high'|string|null|undefined),
+ *   derivedLevel?: (ChangeLevel|string|null|undefined),
  *   changedFileCount?: (number|null|undefined),
- *   sizing?: { softFiles?: number, hardFiles?: number }|null,
+ *   diffWidth?: { softFiles?: number, hardFiles?: number }|null,
  * }} [input]
  * @returns {ReviewDepth}
  */
 export function resolveDepth(input = {}) {
-  const overallLevel =
-    input && typeof input === 'object' ? input.overallLevel : undefined;
+  const derivedLevel =
+    input && typeof input === 'object' ? input.derivedLevel : undefined;
   const changedFileCount =
     input && typeof input === 'object'
       ? normalizeChangedFileCount(input.changedFileCount)
       : null;
 
-  const mergedSizing = {
-    ...DEFAULT_TASK_SIZING,
-    ...(input && typeof input === 'object' && input.sizing ? input.sizing : {}),
+  const override =
+    input && typeof input === 'object' ? (input.diffWidth ?? {}) : {};
+  const mergedWidth = {
+    ...DEFAULT_DIFF_WIDTH,
+    ...override,
   };
-  const { softFiles, hardFiles } = mergedSizing;
+  const { softFiles, hardFiles } = mergedWidth;
 
   // A known count strictly above the wide-change scale is wide.
   const isWide = changedFileCount !== null && changedFileCount > hardFiles;
   // An unknown count is treated as "not wide" — it does not block `light`.
   const isSmall = changedFileCount === null || changedFileCount <= softFiles;
 
-  // deep — high judged risk OR a wide diff.
-  if (overallLevel === 'high' || isWide) return 'deep';
-  // light — low judged risk AND a (known-or-unknown-but-not-wide) small diff.
-  if (overallLevel === 'low' && isSmall) return 'light';
-  // standard — everything else (medium, absent/malformed level, or a low-risk
-  // diff whose width is between softFiles and hardFiles).
+  // deep — a sensitive path was touched OR the diff is wide.
+  if (derivedLevel === 'high' || isWide) return 'deep';
+  // light — nothing sensitive touched AND a (known-or-unknown-but-not-wide)
+  // small diff.
+  if (derivedLevel === 'low' && isSmall) return 'light';
+  // standard — everything else: an underivable level, or a non-sensitive diff
+  // whose width sits between softFiles and hardFiles.
   return 'standard';
 }

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

@@ -44,7 +44,7 @@ export const CODEX_REMEDIATIONS = Object.freeze({
     'Install the Codex plugin (https://github.com/openai/codex-plugin-cc) ' +
     'so the host registers the `/codex:review` slash command.',
   fallback:
-    'Or set `codeReview.provider` to "native" in .agentrc.json to use the ' +
+    'Or set `codeReview.providers` to [{ name: "native" }] in .agentrc.json to use the ' +
     'in-process maintainability/lint provider instead.',
 });
 
@@ -96,7 +96,7 @@ export function defaultProbeCodexCommand(opts = {}) {
  */
 export function buildCodexUnavailableError() {
   return new Error(
-    '[ReviewProviderFactory] codeReview.provider is set to "codex" but the ' +
+    '[ReviewProviderFactory] codeReview.providers includes "codex" but the ' +
       '`/codex:review` slash command is not registered on this host. ' +
       `${CODEX_REMEDIATIONS.install} ${CODEX_REMEDIATIONS.fallback}`,
   );

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

@@ -13,7 +13,6 @@
  *
  * @typedef {import('./types.js').Finding} Finding
  * @typedef {import('./types.js').Severity} Severity
- * @typedef {import('./types.js').ReviewScope} ReviewScope
  */
 
 /**
@@ -117,7 +116,6 @@ export function renderManualPromptsSection(messages) {
  * non-empty.
  *
  * @param {{
- *   scope: ReviewScope,
  *   ticketId: number,
  *   baseRef: string,
  *   headRef: string,
@@ -128,26 +126,18 @@ export function renderManualPromptsSection(messages) {
  * @returns {string}
  */
 export function renderFindings(input) {
-  const {
-    scope,
-    ticketId,
-    baseRef,
-    headRef,
-    findings,
-    provider,
-    promptMessages,
-  } = input;
+  const { ticketId, baseRef, headRef, findings, provider, promptMessages } =
+    input;
   const counts = countBySeverity(findings);
   const totalKnown =
     counts.critical + counts.high + counts.medium + counts.suggestion;
 
-  const scopeLabel = scope === 'epic' ? 'Epic' : 'Story';
   const providerLine = provider
     ? `**Provider**: \`${provider}\``
     : '**Provider**: _(unspecified)_';
 
   const lines = [
-    `## 🔬 Code Review — ${scopeLabel} #${ticketId}`,
+    `## 🔬 Code Review — Story #${ticketId}`,
     '',
     `**Comparison**: \`${baseRef}\` … \`${headRef}\``,
     providerLine,