mandrel 2.0.0 → 2.1.0

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,

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

@@ -50,11 +50,6 @@ import {
 } from '../../maintainability-engine.js';
 import { PROJECT_ROOT } from '../../project-root.js';
 import { transpileIfNeeded } from '../../transpile.js';
-import {
-  hashCommandConfig,
-  recordPass,
-  shouldSkip,
-} from '../../validation-evidence.js';
 
 /** Worker entry that scores one file into a full maintainability report. */
 const MAINTAINABILITY_REPORT_WORKER_URL = new URL(
@@ -141,13 +136,6 @@ export function partitionFilesForLint(changedFiles) {
   return { code, md };
 }
 
-function resolveCurrentSha(cwd, gitSpawnFn = gitSpawn) {
-  const res = gitSpawnFn(cwd, 'rev-parse', 'HEAD');
-  if (res.status !== 0) return null;
-  const sha = (res.stdout || '').trim();
-  return sha.length > 0 ? sha : null;
-}
-
 /**
  * Read a changed file's content as it exists at `headRef` via
  * `git show <headRef>:<relPath>`, rather than reading the on-disk copy at
@@ -260,28 +248,6 @@ export function runScopedLint(changedFiles, cwd, runnerFn = spawnLintRunner) {
   return { ...summary, skipped: false, mode: 'changed-only' };
 }
 
-/**
- * Compute the canonical command-config hash for the scoped-lint runner. The
- * caller passes the partitioned biome + markdown lists so the hash captures
- * the exact set of files; any change to that set invalidates the prior
- * evidence and forces a re-lint.
- *
- * Exported for testing.
- */
-export function buildLintEvidenceConfig(changedFiles, cwd) {
-  const { code, md } = partitionFilesForLint(changedFiles);
-  const args = [];
-  if (code.length > 0) args.push('biome', 'lint', ...code);
-  if (md.length > 0) {
-    args.push('markdownlint', ...md, '--ignore', 'node_modules');
-  }
-  return hashCommandConfig({
-    cmd: 'epic-code-review/scoped-lint',
-    args,
-    cwd,
-  });
-}
-
 /**
  * Pure: classify a single file's maintainability report into a row + optional
  * Finding-shaped entries. `reportFn` is the thunk that produces the file's
@@ -548,87 +514,9 @@ function _emptyResults() {
   };
 }
 
-function tryEvidenceSkip({
-  storyId,
-  epicId,
-  useEvidence,
-  headSha,
-  evidenceCfg,
-  shouldSkipFn,
-  logger,
-}) {
-  if (!(useEvidence && storyId && epicId && headSha)) return null;
-  const verdict = shouldSkipFn(
-    {
-      storyId,
-      gateName: 'epic-code-review/lint',
-      currentSha: headSha,
-      configHash: evidenceCfg,
-    },
-    { cwd: PROJECT_ROOT, epicId },
-  );
-  if (!verdict.skip) return null;
-  logger?.info?.(
-    `[native-review] Scoped lint skipped (evidence match: SHA=${headSha.slice(
-      0,
-      7,
-    )}, recorded ${verdict.record?.timestamp ?? 'n/a'}).`,
-  );
-  return {
-    errors: 0,
-    warnings: 0,
-    parsed: false,
-    skipped: true,
-    mode: 'changed-only',
-    evidenceSkipped: true,
-  };
-}
-
-function maybeRecordLintEvidence({
-  storyId,
-  epicId,
-  useEvidence,
-  headSha,
-  evidenceCfg,
-  lintSummary,
-  recordPassFn,
-  logger,
-}) {
-  const eligible =
-    useEvidence &&
-    storyId &&
-    epicId &&
-    headSha &&
-    lintSummary.errors === 0 &&
-    !lintSummary.skipped;
-  if (!eligible) return;
-  try {
-    recordPassFn(
-      {
-        storyId,
-        gateName: 'epic-code-review/lint',
-        sha: headSha,
-        configHash: evidenceCfg,
-        exitCode: 0,
-      },
-      { cwd: PROJECT_ROOT, epicId },
-    );
-  } catch (err) {
-    logger?.warn?.(
-      `[native-review] Failed to record lint evidence: ${err?.message ?? err}`,
-    );
-  }
-}
-
 async function runLintPhase({
   scopeLint,
   changedFiles,
-  storyId,
-  epicId,
-  useEvidence,
-  gitSpawnFn,
-  shouldSkipFn,
-  recordPassFn,
   runScopedLintFn,
   logger,
 }) {
@@ -644,34 +532,10 @@ async function runLintPhase({
       mode: 'off',
     };
   }
-  const evidenceCfg = buildLintEvidenceConfig(changedFiles, PROJECT_ROOT);
-  const headSha = resolveCurrentSha(PROJECT_ROOT, gitSpawnFn);
-  const skipSummary = tryEvidenceSkip({
-    storyId,
-    epicId,
-    useEvidence,
-    headSha,
-    evidenceCfg,
-    shouldSkipFn,
-    logger,
-  });
-  if (skipSummary) return skipSummary;
-
   logger?.info?.(
     '[native-review] Linting changed files only (biome + markdownlint, scoped to diff)...',
   );
-  const lintSummary = runScopedLintFn(changedFiles, PROJECT_ROOT);
-  maybeRecordLintEvidence({
-    storyId,
-    epicId,
-    useEvidence,
-    headSha,
-    evidenceCfg,
-    lintSummary,
-    recordPassFn,
-    logger,
-  });
-  return lintSummary;
+  return runScopedLintFn(changedFiles, PROJECT_ROOT);
 }
 
 /**
@@ -686,12 +550,8 @@ async function runLintPhase({
  *   runScopedLintFn?: typeof runScopedLint,
  *   analyzeChangedFilesFn?: typeof analyzeChangedFiles,
  *   buildLintFindingsFn?: typeof buildLintFindings,
- *   shouldSkipFn?: typeof shouldSkip,
- *   recordPassFn?: typeof recordPass,
  *   logger?: { info?: Function, warn?: Function, error?: Function },
  *   scopeLint?: 'changed-only'|'off',
- *   storyId?: number|null,
- *   useEvidence?: boolean,
  * }} [deps]
  * @returns {ReviewProvider}
  */
@@ -701,12 +561,8 @@ export function createNativeProvider(deps = {}) {
     runScopedLintFn = runScopedLint,
     analyzeChangedFilesFn = analyzeChangedFiles,
     buildLintFindingsFn = buildLintFindings,
-    shouldSkipFn = shouldSkip,
-    recordPassFn = recordPass,
     logger,
     scopeLint = 'changed-only',
-    storyId = null,
-    useEvidence = true,
   } = deps;
 
   return {
@@ -761,18 +617,9 @@ export function createNativeProvider(deps = {}) {
         gitSpawnFn,
       });
 
-      // Epic-scope reviews flow through validation-evidence; story-scope
-      // reviews currently share the same gate name, keyed on the storyId.
-      const epicId = scope === 'epic' ? ticketId : null;
       const lintSummary = await runLintPhase({
         scopeLint,
         changedFiles,
-        storyId: storyId ?? (scope === 'story' ? ticketId : null),
-        epicId,
-        useEvidence,
-        gitSpawnFn,
-        shouldSkipFn,
-        recordPassFn,
         runScopedLintFn,
         logger,
       });

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

@@ -3,8 +3,9 @@
  * LLM-backed review providers.
  *
  * Story #3937 / #3938 — the depth lever (`light` / `standard` / `deep`,
- * resolved from judged risk AND diff width by `resolveDepth` in
- * `lib/orchestration/review-depth.js`) is threaded into every
+ * 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

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

@@ -185,7 +185,7 @@ export const SECURITY_REVIEW_INVOKE_PROMPT =
  * @returns {string}
  */
 export function buildSecurityReviewPrompt(input) {
-  const scopeLabel = input?.scope === 'epic' ? 'Epic' : 'Story';
+  const scopeLabel = 'Story';
   const baseRef = typeof input?.baseRef === 'string' ? input.baseRef : '?';
   const headRef = typeof input?.headRef === 'string' ? input.headRef : '?';
   const ticketId =

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

@@ -26,7 +26,7 @@
  * @property {number=}  line         - 1-based line number, when attributable.
  * @property {string=}  category     - Free-form tag (e.g. 'security', 'docs', 'lint').
  *
- * @typedef {'story'|'epic'} ReviewScope
+ * @typedef {'story'} ReviewScope
  *
  * @typedef {'light'|'standard'|'deep'} ReviewDepth
  *
@@ -39,9 +39,10 @@
  *   lever (Story #3876/#3937/#3938). `light` → single-pass review focused on
  *   Pillar 1 (spec adherence) with Pillars 2–3 reduced to a quick scan;
  *   `standard` → all pillars at baseline depth; `deep` → all pillars plus a
- *   second adversarial pass over the diff. Resolved from the judged risk
- *   envelope AND the changed-file count of the diff by `resolveDepth`
- *   (`lib/orchestration/review-depth.js`) and threaded into `runReview`.
+ *   second adversarial pass over the diff. Derived from the diff's
+ *   changed-file count and sensitive-path hits
+ *   (`lib/orchestration/review-depth.js`; the judged-risk input was
+ *   retired in #4542) and threaded into `runReview`.
  *   LLM-backed
  *   providers MUST render this into the prompt/instructions they emit; the
  *   native provider documents why its mechanical sweep ignores it. Absent →

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

@@ -55,7 +55,7 @@ export const ULTRAREVIEW_PROMPT_TEMPLATE =
  * @returns {string}
  */
 export function buildUltrareviewMessage(input) {
-  const scopeLabel = input?.scope === 'epic' ? 'Epic' : 'Story';
+  const scopeLabel = 'Story';
   const baseRef = typeof input?.baseRef === 'string' ? input.baseRef : '?';
   const headRef = typeof input?.headRef === 'string' ? input.headRef : '?';
   return ULTRAREVIEW_PROMPT_TEMPLATE.replace('{scopeLabel}', scopeLabel)