mandrel 2.0.0 → 2.2.0

package/.agents/scripts/lib/orchestration/resolve-stories.js

@@ -0,0 +1,344 @@
+/**
+ * lib/orchestration/resolve-stories.js — resolve a set of Story ids into the
+ * `{ stories, dag, done }` envelope the delivery scheduler consumes.
+ *
+ * This is the ONE resolution step for `/deliver`. It generalizes the
+ * envelope shaping proven by the retired `resolve-plan-run.js` and fixes the
+ * two defects that shipped with it:
+ *
+ *   - it fetched with `state: 'open'`, so an already-landed sibling vanished
+ *     from the envelope and `done[]` could never be populated;
+ *   - `done[]` was computed only over label-fetched issues, so a dependency
+ *     outside the fetched set could never be satisfied.
+ *
+ * Both made cross-run, over-time delivery structurally impossible. Here every
+ * dependency — in-set or foreign — is resolved against live issue state, so a
+ * Story whose blocker landed weeks ago in another plan run is simply ready.
+ *
+ * Two contracts differ deliberately from the label-scoped ancestor:
+ *
+ *   1. **Id-scoped fetch means a named non-Story is an ERROR, not a filter.**
+ *      `toStoryRecord` used to return `null` for a non-Story, which is right
+ *      when a label query returns incidental noise and wrong when an operator
+ *      names an id explicitly: silently dropping it yields a partial envelope
+ *      that under-delivers without saying so.
+ *   2. **The native-edge read fails loud.** See {@link readNativeBlockedBy}.
+ *
+ * @module lib/orchestration/resolve-stories
+ */
+
+import { extractEpicIdFromBody, parseBlockedBy } from '../dependency-parser.js';
+import { TYPE_LABELS } from '../label-constants.js';
+import { buildStoryAdjacency } from '../story-adjacency.js';
+import {
+  extractChangePaths,
+  parse as parseStoryBody,
+} from '../story-body/story-body.js';
+
+/** Labels/state that mean a blocker no longer gates its dependents. */
+const DONE_LABEL = 'agent::done';
+
+/**
+ * Module-private: `toStoryRecord` and `isSatisfiedBlocker` are its only
+ * callers. The ancestor exported it with no external consumer, which is how
+ * a symbol ends up baselined as a dead export.
+ *
+ * @param {object} issue
+ * @returns {string[]}
+ */
+function normalizeIssueLabels(issue) {
+  const raw = issue?.labels;
+  if (!Array.isArray(raw)) return [];
+  return raw
+    .map((l) => (typeof l === 'string' ? l : l?.name))
+    .filter((n) => typeof n === 'string' && n.length > 0);
+}
+
+/**
+ * Map one fetched issue into a Story record, or throw naming the id and the
+ * remedy. Unlike the label-scoped ancestor this **never** returns `null`:
+ * under `--ids` the operator named this issue, so dropping it silently would
+ * emit a partial envelope.
+ *
+ * @param {object} issue
+ * @param {number} [requestedId] The id the operator asked for, for error text.
+ * @returns {{ id, title, body, url, labels, state }}
+ */
+export function toStoryRecord(issue, requestedId) {
+  const id = Number(issue?.number ?? issue?.id ?? requestedId);
+  if (!Number.isInteger(id) || id <= 0) {
+    throw new Error(
+      `[resolve-stories] #${requestedId ?? '?'} did not resolve to an issue number.`,
+    );
+  }
+  const labels = normalizeIssueLabels(issue);
+  if (!labels.includes(TYPE_LABELS.STORY)) {
+    throw new Error(
+      `[resolve-stories] Issue #${id} is not a Story (labels: ${labels.join(', ') || 'none'}). ` +
+        `/deliver accepts ${TYPE_LABELS.STORY} tickets only — close it or re-plan it as a v2 Story.`,
+    );
+  }
+  const body = String(issue?.body ?? '');
+  const epicId = extractEpicIdFromBody(body);
+  if (epicId !== null) {
+    throw new Error(
+      `[resolve-stories] Issue #${id} still carries an "Epic: #${epicId}" footer. ` +
+        `v2 is Story-only — re-plan it as a v2 Story or finish it on a pre-v2 checkout.`,
+    );
+  }
+  return {
+    id,
+    title: String(issue?.title ?? ''),
+    body,
+    url: issue?.html_url ?? issue?.url ?? null,
+    labels,
+    state: String(issue?.state ?? 'open').toLowerCase(),
+  };
+}
+
+/**
+ * A blocker stops gating once its issue is closed or carries `agent::done`.
+ *
+ * @param {{ state?: string, labels?: string[] }} issue
+ * @returns {boolean}
+ */
+export function isSatisfiedBlocker(issue) {
+  const state = String(issue?.state ?? '').toLowerCase();
+  if (state === 'closed') return true;
+  return normalizeIssueLabels(issue).includes(DONE_LABEL);
+}
+
+/**
+ * Footprint emitted when a Story's declared changes cannot be READ. It is a
+ * glob, so `storiesOverlap` (`lib/wave-runner/ready-set.js`) treats it as
+ * overlapping every other **declared** footprint and the Story takes its
+ * beat alone. (A Story declaring nothing still overlaps nothing — the guard
+ * short-circuits on an empty footprint either side, which is the deliberate
+ * permissive escape hatch that keeps undeclared work parallel.)
+ *
+ * Deliberately NOT `[]`. An empty footprint means "declares nothing", which
+ * the guard reads as "overlaps nothing" and never withholds — correct for a
+ * Story that genuinely declares no changes, and wrong for one whose changes
+ * we failed to parse. Those are different facts: the second is *unknown*
+ * width, and the same argument that makes a glob overlap everything
+ * ("unknown width is not no width") applies to a body we could not read.
+ */
+const UNKNOWN_FOOTPRINT = Object.freeze(['**']);
+
+/**
+ * Extract a Story's declared file footprint as **plain path strings**.
+ *
+ * The shape matters: `stories-wave-tick.js`'s `parseDag` rejects any `files`
+ * entry that is not a string, while `extractChangePaths` returns
+ * `{ path, isGlob }` objects — so forwarding its output verbatim fails every
+ * multi-Story run with an input error. Map to `.path`.
+ *
+ * Never throws — these are live, human-editable issue bodies, and one
+ * malformed body must not take the whole resolution down. It fails **safe**
+ * rather than open: an unreadable footprint yields {@link UNKNOWN_FOOTPRINT},
+ * serializing that Story instead of silently letting it race.
+ *
+ * @param {string} body
+ * @param {number} [id] Story id, for the warning.
+ * @param {(msg: string) => void} [warn]
+ * @returns {string[]}
+ */
+export function storyFootprintPaths(body, id, warn) {
+  let parsed;
+  try {
+    parsed = parseStoryBody(String(body ?? '')).body;
+  } catch (err) {
+    warn?.(
+      `[resolve-stories] #${id}: body is unparseable, so its file footprint is unknown ` +
+        `(${err?.message ?? err}). Treating it as overlapping every other Story, so it is ` +
+        `never co-dispatched — fix the body to restore parallelism.`,
+    );
+    return [...UNKNOWN_FOOTPRINT];
+  }
+  try {
+    // An empty `changes` is a real declaration of "no files", not a read
+    // failure — it keeps the permissive empty footprint.
+    return extractChangePaths(parsed?.changes ?? [])
+      .map((entry) => entry?.path)
+      .filter((p) => typeof p === 'string' && p.trim().length > 0)
+      .map((p) => p.trim());
+  } catch (err) {
+    warn?.(
+      `[resolve-stories] #${id}: malformed changes entry, so its file footprint is unknown ` +
+        `(${err?.message ?? err}). Treating it as overlapping every other Story.`,
+    );
+    return [...UNKNOWN_FOOTPRINT];
+  }
+}
+
+/**
+ * Build the DAG nodes. `dependsOn` is the union the adjacency builder already
+ * computes (body-parsed `blocked by #N` + explicit fields), plus any native
+ * edges threaded in via `nativeEdges`. `files` is a plain `string[]`.
+ *
+ * @param {object[]} stories
+ * @param {Map<number, number[]>} [nativeEdges]
+ * @param {(msg: string) => void} [warn]
+ * @returns {{ id: number, dependsOn: number[], files: string[] }[]}
+ */
+export function storiesToDag(stories, nativeEdges = new Map(), warn) {
+  const withNative = stories.map((s) => ({
+    ...s,
+    dependsOn: [
+      ...new Set([
+        ...parseBlockedBy(s.body ?? ''),
+        ...(nativeEdges.get(s.id) ?? []),
+      ]),
+    ],
+  }));
+  // dropForeign:false — a dependency outside the requested set is a real
+  // gate, not noise. What changes here is that such a gate is now
+  // *satisfiable*: `done[]` carries foreign blockers resolved from live state.
+  const adjacency = buildStoryAdjacency(withNative, { dropForeign: false });
+  return stories.map((s) => ({
+    id: s.id,
+    dependsOn: adjacency.get(s.id) ?? [],
+    files: storyFootprintPaths(s.body, s.id, warn),
+  }));
+}
+
+/**
+ * Project the dependencies API response onto issue **numbers**.
+ *
+ * The API returns both `id` (database id) and `number` (issue number); the
+ * write path (`providers/github/blocked-by-add.js`) reads `id` because its
+ * POST body needs `issue_id`. Reusing that projection here would build
+ * `dependsOn: [4902374986]` for a blocker whose issue number is 4530 — an id
+ * matching no Story, foreign to the set, never satisfiable, and (because
+ * foreign edges are real gates) a silent permanent wedge.
+ *
+ * Cross-repo blockers are rejected rather than matched: another repo's #4530
+ * is not this repo's #4530, and treating it as one could satisfy a gate that
+ * is still open.
+ *
+ * @param {unknown} data Parsed API response.
+ * @param {{ owner: string, repo: string, issueNumber: number }} ctx
+ * @returns {number[]}
+ */
+export function nativeBlockedByNumbers(data, { owner, repo, issueNumber }) {
+  if (!Array.isArray(data)) return [];
+  const out = [];
+  for (const item of data) {
+    const repoUrl = item?.repository_url ?? item?.repository?.url ?? null;
+    if (typeof repoUrl === 'string' && repoUrl.length > 0) {
+      const expected = `/repos/${owner}/${repo}`;
+      if (!repoUrl.endsWith(expected)) {
+        throw new Error(
+          `[resolve-stories] #${issueNumber} is blocked by an issue in another repository ` +
+            `(${repoUrl}). Cross-repo dependency edges are not supported — its number cannot ` +
+            `be matched against this repo's Stories without risking a false match.`,
+        );
+      }
+    }
+    const number = Number(item?.number);
+    if (Number.isInteger(number) && number > 0) out.push(number);
+  }
+  return [...new Set(out)];
+}
+
+/**
+ * Read an issue's native `blocked_by` edges as issue numbers.
+ *
+ * **Fails loud**, deliberately inverting the write path's non-fatal contract.
+ * A dropped write-side edge is cosmetic (the ordering still lives in the
+ * `blocked by #N` body footer); a dropped READ-side edge silently removes a
+ * dispatch gate, so a 403 (dependencies API disabled, or a token without the
+ * scope) would erase every native edge at once and co-dispatch the whole run
+ * against unlanded blockers. A 404 means "no dependencies on this issue" and
+ * is a legitimate empty result.
+ *
+ * @param {{ gh: object, owner: string, repo: string, issueNumber: number, parseJson: Function }} opts
+ * @returns {Promise<number[]>}
+ */
+export async function readNativeBlockedBy({
+  gh,
+  owner,
+  repo,
+  issueNumber,
+  parseJson,
+}) {
+  let result;
+  try {
+    result = await gh.api({
+      method: 'GET',
+      endpoint: `/repos/${owner}/${repo}/issues/${issueNumber}/dependencies/blocked_by`,
+    });
+  } catch (err) {
+    const detail = String(err?.message ?? err);
+    if (/404|not found/i.test(detail)) return [];
+    throw new Error(
+      `[resolve-stories] Could not read native blocked_by edges for #${issueNumber}: ${detail}. ` +
+        `Refusing to continue: a dropped dependency edge would silently remove a dispatch gate ` +
+        `and co-dispatch this Story against an unlanded blocker.`,
+    );
+  }
+  return nativeBlockedByNumbers(parseJson(result), {
+    owner,
+    repo,
+    issueNumber,
+  });
+}
+
+/**
+ * Assemble the envelope from resolved records.
+ *
+ * @param {object[]} stories
+ * @param {Map<number, number[]>} nativeEdges
+ * @param {number[]} foreignDone Ids outside the set already satisfied.
+ * @param {(msg: string) => void} [warn]
+ * @returns {{ kind: string, stories: object[], dag: object[], done: number[] }}
+ */
+export function buildStoriesEnvelope({
+  stories,
+  nativeEdges = new Map(),
+  foreignDone = [],
+  warn,
+}) {
+  const sorted = [...stories].sort((a, b) => a.id - b.id);
+  const inSetDone = sorted.filter(isSatisfiedBlocker).map((s) => s.id);
+  return {
+    kind: 'stories',
+    stories: sorted.map(({ id, title, url, labels, state }) => ({
+      id,
+      title,
+      url,
+      labels,
+      state,
+    })),
+    dag: storiesToDag(sorted, nativeEdges, warn),
+    done: [...new Set([...inSetDone, ...foreignDone])].sort((a, b) => a - b),
+  };
+}
+
+/**
+ * Parse and validate the `--ids` list.
+ *
+ * @param {string|undefined} raw
+ * @returns {number[]}
+ */
+export function parseIds(raw) {
+  const ids = String(raw ?? '')
+    .split(',')
+    .map((s) => s.trim())
+    .filter(Boolean)
+    .map((s) => {
+      const n = Number.parseInt(s, 10);
+      if (!Number.isInteger(n) || n <= 0 || String(n) !== s) {
+        throw new Error(
+          `[resolve-stories] --ids must be a comma-separated list of positive issue numbers (got "${s}").`,
+        );
+      }
+      return n;
+    });
+  if (ids.length === 0) {
+    throw new Error(
+      '[resolve-stories] --ids is required: node resolve-stories.js --ids 101,102',
+    );
+  }
+  return [...new Set(ids)];
+}

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

@@ -43,7 +43,7 @@
  *
  * @typedef {Object} RoutedProposalsInput
  * @property {number}                anchorId      Story or run/Epic id in titles.
- * @property {'epic'|'story'|'run'}  [anchorKind]    Wording in titles/bodies (default `epic`).
+ * @property {'story'|'run'}  [anchorKind]    Wording in titles/bodies (default `story`).
  * @property {string}                frameworkRepo   `"<owner>/<repo>"`.
  * @property {string}                consumerRepo    `"<owner>/<repo>"`.
  * @property {FrictionSignal[]}      [signals]
@@ -144,7 +144,7 @@ function dominantSource(entry) {
 }
 
 /**
- * @param {'epic'|'story'|'run'} kind
+ * @param {'story'|'run'} kind
  * @param {number} id
  * @returns {string}
  */
@@ -154,7 +154,7 @@ function formatAnchor(kind, id) {
   return `Epic #${id}`;
 }
 
-/** Story scope promotes single-occurrence friction; Epic/run keep ≥2. */
+/** 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);
@@ -167,7 +167,7 @@ function isActionableFriction(total, force, anchorKind) {
  *
  * @param {{
  *   anchorId: number,
- *   anchorKind: 'epic'|'story'|'run',
+ *   anchorKind: 'story'|'run',
  *   category: string,
  *   occurrences: number,
  *   source: "framework"|"consumer",
@@ -225,7 +225,7 @@ function renderIssueCommand({ repo, title, metaLabel, category, body }) {
  *
  * @param {{
  *   anchorId: number,
- *   anchorKind: 'epic'|'story'|'run',
+ *   anchorKind: 'story'|'run',
  *   category: string,
  *   occurrences: number,
  *   source: "framework"|"consumer",
@@ -272,7 +272,7 @@ function buildRoutedItem({
  * @param {unknown} input
  * @returns {{
  *   anchorId: number,
- *   anchorKind: 'epic'|'story'|'run',
+ *   anchorKind: 'story'|'run',
  *   frameworkRepo: string,
  *   consumerRepo: string,
  *   signals: FrictionSignal[],
@@ -280,7 +280,7 @@ function buildRoutedItem({
  * } | null}
  */
 function normalizeAnchorKind(kind) {
-  return kind === 'story' || kind === 'run' || kind === 'epic' ? kind : 'epic';
+  return kind === 'story' || kind === 'run' ? kind : 'story';
 }
 
 function normaliseInput(input) {

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

@@ -1,35 +1,52 @@
 /**
- * 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 (`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 (`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
- *                  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.
+ * ## 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
@@ -37,8 +54,11 @@
  * The two no longer share a constant.
  *
  * @typedef {'light'|'standard'|'deep'} ReviewDepth
+ * @typedef {'low'|'high'} ChangeLevel
  */
 
+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
@@ -49,6 +69,50 @@ export const DEFAULT_DIFF_WIDTH = Object.freeze({
   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
  * `null` when the count is unknown / unusable. A `null` count is the neutral
@@ -65,20 +129,20 @@ 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)
@@ -97,11 +161,12 @@ export function resolveDepth(input = {}) {
   // 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/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,