mandrel 1.94.0 → 2.0.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 {'epic'|'story'|'run'}  [anchorKind]    Wording in titles/bodies (default `epic`).
  * @property {string}                frameworkRepo   `"<owner>/<repo>"`.
  * @property {string}                consumerRepo    `"<owner>/<repo>"`.
  * @property {FrictionSignal[]}      [signals]
@@ -142,23 +143,53 @@ function dominantSource(entry) {
   return entry.firstSource;
 }
 
+/**
+ * @param {'epic'|'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; Epic/run keep ≥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: 'epic'|'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: 'epic'|'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: 'epic'|'story'|'run',
  *   frameworkRepo: string,
  *   consumerRepo: string,
  *   signals: FrictionSignal[],
  *   unresolvedBlockedEvents: BlockedEvent[],
  * } | null}
  */
+function normalizeAnchorKind(kind) {
+  return kind === 'story' || kind === 'run' || kind === 'epic' ? kind : 'epic';
+}
+
 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

@@ -10,11 +10,11 @@
  *
  * 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.
+ *                  the wide-change scale (`diffWidth.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
+ *                  below the small-change scale (`diffWidth.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
@@ -29,14 +29,25 @@
  * 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 changed-file count from the diff they already run and supply it here.
+ *
+ * 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
  */
 
-import { DEFAULT_TASK_SIZING } from './ticket-validator-sizing.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,
+});
 
 /**
  * Coerce an arbitrary input into a non-negative integer changed-file count, or
@@ -61,6 +72,7 @@ function normalizeChangedFileCount(value) {
  *   overallLevel?: ('low'|'medium'|'high'|string|null|undefined),
  *   changedFileCount?: (number|null|undefined),
  *   sizing?: { softFiles?: number, hardFiles?: number }|null,
+ *   diffWidth?: { softFiles?: number, hardFiles?: number }|null,
  * }} [input]
  * @returns {ReviewDepth}
  */
@@ -72,11 +84,13 @@ export function resolveDepth(input = {}) {
       ? 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;

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/review-provider-factory.js

@@ -1,34 +1,27 @@
 /**
  * review-providers/review-provider-factory.js — resolve
- * `codeReview.provider` / `codeReview.providers` to a concrete
- * `ReviewProvider` instance.
+ * `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 — extends the factory for multi-provider chains:
- *   - Legacy single-string `codeReview.provider`: factory returns the
- *     single `ReviewProvider` adapter as before (back-compat for the
- *     shape and for every existing test).
- *   - New `codeReview.providers: ProviderEntry[]`: factory 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.
+ * 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 / missing `codeReview.provider` defaults to `'native'`.
+ *   - 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.
- *   - When both `provider` (legacy single) and `providers` (chain) are
- *     present, `providers` wins; `provider` is ignored with a warning.
  *
  * @typedef {import('./types.js').ReviewProvider}        ReviewProvider
  * @typedef {import('./types.js').ManualPromptProvider}  ManualPromptProvider
@@ -70,8 +63,8 @@ const PROMPT_PROVIDERS = Object.freeze({
 });
 
 /**
- * The provider name used when `codeReview.provider` is unset or the
- * `codeReview` block is absent entirely.
+ * The inline provider name used when `codeReview.providers` is unset,
+ * empty, or the `codeReview` block is absent entirely.
  */
 export const DEFAULT_PROVIDER_NAME = 'native';
 
@@ -127,13 +120,10 @@ export function isScopeApplicable(declaredScopes, currentScope) {
  * config block. Pass the `codeReview` sub-object (not the full
  * config) so callers can compose with their own config readers.
  *
- * Story #2871 — when `codeReviewConfig.providers` is a non-empty
- * array, returns a `ChainProvider` (fans out across entries);
- * otherwise returns the single legacy adapter selected by
- * `codeReviewConfig.provider`.
+ * Always returns a `ChainProvider`. When `codeReviewConfig.providers`
+ * is unset or empty, the chain defaults to `[{ name: 'native' }]`.
  *
  * @param {{
- *   provider?: string,
  *   providers?: Array<object>,
  *   providerConfig?: object,
  * }|null|undefined} codeReviewConfig
@@ -152,44 +142,19 @@ export function createReviewProvider(codeReviewConfig, opts = {}) {
   const promptRegistry = opts.promptRegistry ?? PROMPT_PROVIDERS;
   const logger = opts.logger;
 
-  // Chain shape wins when present.
-  if (
+  const entries =
     codeReviewConfig &&
     Array.isArray(codeReviewConfig.providers) &&
     codeReviewConfig.providers.length > 0
-  ) {
-    if (typeof codeReviewConfig.provider === 'string') {
-      logger?.warn?.(
-        '[ReviewProviderFactory] Both `provider` and `providers` are set; ' +
-          '`providers` wins. Remove the legacy `provider` field to silence ' +
-          'this warning.',
-      );
-    }
-    const chain = buildProviderChain(codeReviewConfig.providers, {
-      inlineRegistry,
-      promptRegistry,
-      logger,
-    });
-    return createChainProvider(chain, { logger });
-  }
+      ? codeReviewConfig.providers
+      : [{ name: DEFAULT_PROVIDER_NAME }];
 
-  // Legacy single-string shape.
-  const name =
-    codeReviewConfig && typeof codeReviewConfig.provider === 'string'
-      ? codeReviewConfig.provider
-      : DEFAULT_PROVIDER_NAME;
-
-  const ctor = inlineRegistry[name];
-  if (!ctor) {
-    const supported = Object.keys(inlineRegistry).sort().join(', ');
-    throw new Error(
-      `[ReviewProviderFactory] Unknown codeReview.provider "${name}". ` +
-        `Supported values: ${supported}. ` +
-        'Set codeReview.provider in .agentrc.json to one of the supported ' +
-        'values, or remove the field to use the default ("native").',
-    );
-  }
-  return ctor();
+  const chain = buildProviderChain(entries, {
+    inlineRegistry,
+    promptRegistry,
+    logger,
+  });
+  return createChainProvider(chain, { logger });
 }
 
 /**