mandrel 2.0.0 → 2.1.0

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

@@ -11,12 +11,15 @@
  * adapter's `runReview()` to collect a `Finding[]`, render the
  * structured-comment body via `findings-renderer`, and post the
  * comment through the GitHub provider here (the adapter is post-free
- * by design). The lifecycle events (`code-review.start`/`.end`)
- * preserve their previous payload shape so the ledger and listener
- * chain are unchanged.
+ * by design).
+ *
+ * v2.0.0 removed the Epic tier. The Epic-scope envelope and the
+ * Epic-scoped `code-review.start` / `.end` lifecycle emits (whose schema
+ * requires `epicId`) went with it; Story scope is the only scope and the
+ * module no longer touches the lifecycle bus.
  *
  * Public API:
- *   - `runCodeReview({ scope, ticketId, provider, logger, bus, ... })` →
+ *   - `runCodeReview({ ticketId, headRef, provider, logger, ... })` →
  *       `{ status, severity, posted, report, halted, blockerReason }`.
  *
  * Behaviour:
@@ -24,7 +27,7 @@
  *     a single `native` chain entry when `delivery.codeReview.providers`
  *     is unset or empty.
  *   - Always posts the unified `verification-results` structured comment on
- *     the Epic issue (the adapter never posts; the orchestrator owns
+ *     the target issue/PR (the adapter never posts; the orchestrator owns
  *     persistence). Story #4411 (Epic #4405) unified the former
  *     `code-review` and `audit-results` findings contracts into this one
  *     `verification-results` marker.
@@ -39,7 +42,7 @@
 import { hasSurvivingCritical } from '../audit-suite/findings.js';
 import { resolveConfig } from '../config-resolver.js';
 import { gitSpawn } from '../git-utils.js';
-import { resolveDepth } from './review-depth.js';
+import { deriveChangeLevel, resolveDepth } from './review-depth.js';
 import {
   countBySeverity,
   renderFindings,
@@ -49,29 +52,30 @@ import { upsertStructuredComment } from './ticketing.js';
 
 /**
  * Review depth tiers, ordered light → standard → deep. The depth is resolved
- * by the shared {@link resolveDepth} resolver from the judged risk envelope's
- * `overallLevel` **and** the mechanical changed-file count of the diff under
- * review, then threaded into the review provider's `runReview` input so a
- * high-risk *or* wide-footprint change gets a deeper pass than a low-risk
- * small one. Depth is an **input** signal only — it never changes the
+ * by the shared {@link resolveDepth} resolver from two observable properties of
+ * the diff under review — whether its changed files touch a registered
+ * sensitive path ({@link deriveChangeLevel}) and their mechanical count — then
+ * threaded into the review provider's `runReview` input so a sensitive *or*
+ * wide-footprint change gets a deeper pass than a small, unremarkable one.
+ * Depth is an **input** signal only — it never changes the
  * `{ status, severity, posted, report, halted, blockerReason }` output
- * envelope nor the `code-review` structured-comment body (Story #3876,
- * extended by Story #3938).
+ * envelope nor the `verification-results` structured-comment body (Story #3876,
+ * extended by Story #3938; re-based off the diff by Story #4542).
  *
  * @typedef {import('./review-depth.js').ReviewDepth} ReviewDepth
  */
 
 /**
- * Count the files changed in the `baseRef...headRef` diff via
- * `git diff --name-only`. Returns the file count, or `null` when the diff
- * cannot be enumerated (git failure, missing ref). A `null` count is the
- * neutral "width unknown" signal {@link resolveDepth} tolerates without
- * downgrading or escalating the depth. Best-effort — never throws.
+ * Enumerate the files changed in the `baseRef...headRef` diff via
+ * `git diff --name-only`. Returns the file list, or `null` when the diff
+ * cannot be enumerated (git failure, missing ref). A `null` list is the neutral
+ * "diff unknown" signal both {@link deriveChangeLevel} and {@link resolveDepth}
+ * tolerate by failing safe to `standard`. Best-effort — never throws.
  *
  * @param {{ baseRef: string, headRef: string, gitSpawnFn?: typeof gitSpawn }} args
- * @returns {number|null}
+ * @returns {string[]|null}
  */
-function countChangedFiles({ baseRef, headRef, gitSpawnFn = gitSpawn }) {
+function listChangedFiles({ baseRef, headRef, gitSpawnFn = gitSpawn }) {
   try {
     const result = gitSpawnFn(
       process.cwd(),
@@ -83,50 +87,14 @@ function countChangedFiles({ baseRef, headRef, gitSpawnFn = gitSpawn }) {
       return null;
     }
     return result.stdout
-      .trim()
       .split('\n')
-      .filter((line) => line.length > 0).length;
+      .map((line) => line.trim())
+      .filter((line) => line.length > 0);
   } catch {
     return null;
   }
 }
 
-/**
- * Build the `code-review.end` payload from the normalized result envelope.
- * The runner result may carry a `report` field (full markdown body) which
- * is NOT included in the lifecycle payload: the schema's
- * `additionalProperties: false` forbids it, and the body can carry inline
- * severity counts that drift from the structured `severity` field. The
- * lifecycle ledger is the structured surface; the report is GitHub's
- * surface (posted via the structured comment).
- *
- * Story #2839: `epicId` is preserved verbatim in the lifecycle payload so
- * the `code-review.end` schema (additionalProperties: false, requires
- * `epicId`) stays unchanged. Story-scope invocations never reach this
- * helper — `runCodeReview` short-circuits the bus emit for `scope: 'story'`
- * because story-scope review sits outside the Epic lifecycle ledger.
- */
-function buildCodeReviewEndPayload({ epicId, result, durationMs }) {
-  const payload = {
-    epicId,
-    status: result.status,
-  };
-  if (result.severity && typeof result.severity === 'object') {
-    payload.severity = {
-      critical: result.severity.critical ?? 0,
-      high: result.severity.high ?? 0,
-      medium: result.severity.medium ?? 0,
-      suggestion: result.severity.suggestion ?? 0,
-    };
-  }
-  if (typeof result.halted === 'boolean') payload.halted = result.halted;
-  if (typeof result.posted === 'boolean') payload.posted = result.posted;
-  if (Number.isFinite(durationMs) && durationMs >= 0) {
-    payload.durationMs = Math.floor(durationMs);
-  }
-  return payload;
-}
-
 /**
  * Resolve the project base branch fallback used when a caller omits
  * `baseRef`.
@@ -152,7 +120,6 @@ function resolveCommentTargetId(commentTargetId, fallback) {
  *   baseRef: string,
  *   headRef: string,
  *   commentTargetId: number,
- *   epicIdForLedger: null,
  * }}
  */
 function resolveStoryScope(opts, config) {
@@ -175,53 +142,16 @@ function resolveStoryScope(opts, config) {
       opts.commentTargetId,
       opts.ticketId,
     ),
-    epicIdForLedger: null,
-  };
-}
-
-/**
- * Resolve the Epic-scope envelope from the parameterized
- * `{ scope: 'epic', ticketId, baseRef, headRef, commentTargetId }` shape.
- * `headRef` defaults to `epic/<ticketId>` and `baseRef` to the project
- * base branch.
- *
- * @returns {{
- *   scope: 'epic',
- *   ticketId: number,
- *   baseRef: string,
- *   headRef: string,
- *   commentTargetId: number,
- *   epicIdForLedger: number,
- * }}
- */
-function resolveEpicScope(opts, config) {
-  if (!Number.isInteger(opts.ticketId) || opts.ticketId <= 0) {
-    throw new TypeError(
-      'runCodeReview: ticketId is required (positive integer) when scope="epic".',
-    );
-  }
-  return {
-    scope: 'epic',
-    ticketId: opts.ticketId,
-    baseRef: opts.baseRef ?? resolveConfigBase(config),
-    headRef: opts.headRef ?? `epic/${opts.ticketId}`,
-    commentTargetId: resolveCommentTargetId(
-      opts.commentTargetId,
-      opts.ticketId,
-    ),
-    epicIdForLedger: opts.ticketId,
   };
 }
 
 /**
- * Dispatch the parameterized scope envelope
- * (`{ scope, ticketId, baseRef, headRef, commentTargetId }`) to the
- * matching pure resolver. `scope` defaults to `'epic'`.
+ * Resolve the scope envelope
+ * (`{ scope, ticketId, baseRef, headRef, commentTargetId }`). v2.0.0
+ * removed the Epic tier, so `'story'` is the only scope.
  */
 function resolveScopeEnvelope(opts, config) {
-  return opts.scope === 'story'
-    ? resolveStoryScope(opts, config)
-    : resolveEpicScope(opts, config);
+  return resolveStoryScope(opts, config);
 }
 
 /**
@@ -239,36 +169,28 @@ function resolveScopeEnvelope(opts, config) {
  * derived from the `Finding[]` returned by the adapter (no separate
  * severity field on the runner result).
  *
- * Story #2839 (Epic #2815) — accepts a parameterized scope envelope
- * so the standalone Story closer can request a Story-scope review
- * against `main`, post the structured findings comment to the PR
- * (via `commentTargetId`), and surface critical findings to the
- * caller as `halted: true`. Lifecycle bus emits are confined to
- * `scope: 'epic'` because the `code-review.end` schema requires
- * `epicId` and the ledger only spans Epic lifecycles.
+ * Story #2839 (Epic #2815) — the Story closer requests a Story-scope
+ * review against `main`, posts the structured findings comment to the PR
+ * (via `commentTargetId`), and surfaces critical findings to the caller
+ * as `halted: true`.
  *
- * Argument shape (parameterized, Epic or Story):
- *   `{ scope, ticketId, baseRef, headRef, [commentTargetId],
- *      provider, bus }`
- *   `scope` defaults to `'epic'`; `baseRef` defaults to the project base
- *   branch and (Epic scope only) `headRef` defaults to `epic/<ticketId>`.
- *   For `scope === 'story'`, `commentTargetId` overrides the post
- *   target (e.g. PR number) while `ticketId` continues to label the
- *   rendered header ("Story #N").
+ * Argument shape:
+ *   `{ ticketId, baseRef, headRef, [commentTargetId], provider }`
+ *   `baseRef` defaults to the project base branch; `headRef` is required.
+ *   `commentTargetId` overrides the post target (e.g. PR number) while
+ *   `ticketId` continues to label the rendered header ("Story #N").
  *
  * @param {{
- *   scope?: 'epic'|'story',
+ *   scope?: 'story',
  *   ticketId: number,
  *   baseRef?: string|null,
  *   headRef?: string|null,
  *   commentTargetId?: number|null,
  *   provider: object,
  *   logger?: { info?: Function, warn?: Function, error?: Function, fatal?: Function, createProgress?: Function },
- *   planningRisk?: { overallLevel?: ('low'|'medium'|'high'), axes?: Array<{ axis?: string, level?: string }> }|null,
+ *   changedFiles?: string[]|null,
  *   changedFileCount?: number|null,
  *   storyId?: number|null,
- *   bus?: object|null,
- *   now?: () => number,
  *   reviewProvider?: { runReview: Function },
  *   gitSpawnFn?: typeof gitSpawn,
  *   resolveConfigFn?: typeof resolveConfig,
@@ -309,22 +231,26 @@ function resolveProviderName(codeReviewConfig) {
 
 /**
  * Build the provider `runReview` input, resolving the review depth from the
- * judged risk envelope's `overallLevel` and the mechanical changed-file
- * count of the diff under review (Story #3876 / #3938). The depth is an
- * input-only signal (light → standard → deep) and never touches the output
- * envelope or the posted comment. Absent risk envelope + unknown width →
- * `standard`. Story #4075 — extracted from `runCodeReview`.
+ * diff under review: its changed files derive the change level (sensitive path
+ * touched or not — Story #4542) and their count supplies the width. The depth
+ * is an input-only signal (light → standard → deep) and never touches the
+ * output envelope or the posted comment. An unenumerable diff → `standard`.
+ * Story #4075 — extracted from `runCodeReview`.
  */
 function buildReviewInput({ opts, scope, ticketId, baseRef, headRef }) {
+  const changedFiles = Array.isArray(opts.changedFiles)
+    ? opts.changedFiles
+    : listChangedFiles({ baseRef, headRef, gitSpawnFn: opts.gitSpawnFn });
   const changedFileCount =
     typeof opts.changedFileCount === 'number'
       ? opts.changedFileCount
-      : countChangedFiles({ baseRef, headRef, gitSpawnFn: opts.gitSpawnFn });
+      : (changedFiles?.length ?? null);
   // v2 Stage 2: review depth uses DEFAULT_DIFF_WIDTH (mechanical file count
   // of the diff under review). It is deliberately decoupled from the
   // planning model-capacity advisory (`DEFAULT_MODEL_CAPACITY`).
+  const { level } = deriveChangeLevel({ changedFiles });
   const depth = resolveDepth({
-    overallLevel: opts.planningRisk?.overallLevel,
+    derivedLevel: level,
     changedFileCount,
   });
   return {
@@ -418,7 +344,7 @@ async function executeReviewPipeline({ opts, config, envelope }) {
     injectedReviewProvider ?? createReviewProviderFn(codeReviewConfig);
 
   logger?.info?.(
-    `[code-review] Running ${providerName} adapter for ${scope === 'epic' ? 'Epic' : 'Story'} #${ticketId} (${baseRef}...${headRef})...`,
+    `[code-review] Running ${providerName} adapter for Story #${ticketId} (${baseRef}...${headRef})...`,
   );
 
   const reviewInput = buildReviewInput({
@@ -477,49 +403,13 @@ async function executeReviewPipeline({ opts, config, envelope }) {
 }
 
 export async function runCodeReview(opts = {}) {
-  const { bus, now = Date.now, resolveConfigFn = resolveConfig } = opts;
+  const { resolveConfigFn = resolveConfig } = opts;
 
   const config = resolveConfigFn();
   const envelope = resolveScopeEnvelope(opts, config);
-  const { scope } = envelope;
 
-  // Epic-scope lifecycle ledger requires `bus`; Story-scope sits outside
-  // the Epic lifecycle so the bus is optional there. A caller without a
-  // bus on the Story path still gets the full review semantics — only the
-  // `code-review.start`/`.end` events are suppressed.
-  if (scope === 'epic' && (!bus || typeof bus.emit !== 'function')) {
-    throw new TypeError('runCodeReview: bus is required (object with emit()).');
-  }
-  const ledgerEnabled =
-    scope === 'epic' && bus && typeof bus.emit === 'function';
-
-  const startedAt = typeof now === 'function' ? now() : Date.now();
-  // Emit the matched `code-review.end` boundary; the ledger must always
-  // show a start/end pair (even on adapter throw, where `result` is the
-  // canonical `{ status: 'invalid' }`).
-  const emitEnd = async (result) => {
-    if (!ledgerEnabled) return;
-    const endedAt = typeof now === 'function' ? now() : Date.now();
-    await bus.emit(
-      'code-review.end',
-      buildCodeReviewEndPayload({
-        epicId: envelope.epicIdForLedger,
-        result,
-        durationMs: Math.max(0, endedAt - startedAt),
-      }),
-    );
-  };
-
-  if (ledgerEnabled) {
-    await bus.emit('code-review.start', { epicId: envelope.epicIdForLedger });
-  }
-
-  try {
-    const result = await executeReviewPipeline({ opts, config, envelope });
-    await emitEnd(result);
-    return result;
-  } catch (err) {
-    await emitEnd({ status: 'invalid' });
-    throw err;
-  }
+  // No lifecycle-bus emit: the `code-review.start` / `.end` ledger pair was
+  // Epic-scoped (its schema requires `epicId`), and v2.0.0 removed the Epic
+  // tier. Story-scope review sits outside the lifecycle ledger entirely.
+  return executeReviewPipeline({ opts, config, envelope });
 }

package/.agents/scripts/lib/orchestration/consolidation-precondition.js

@@ -12,7 +12,7 @@
  * reconcile — dispatching it is pure token spend for a no-op. This module
  * computes that decision **deterministically**, off the same two inputs the
  * critic itself reads (the draft array and the Epic body's Delivery Slicing
- * table), so `helpers/plan-epic.md` Phase 8.3 can skip the sub-agent
+ * table), so the planning workflow can skip the sub-agent
  * dispatch when it is provably safe to.
  *
  * **Fail-open by design.** Every ambiguous case — a missing or unparseable
@@ -123,7 +123,7 @@ export function parseDeliverySlicingTable(epicBody) {
 
 /**
  * True when `story` is the recognized wave-0 BDD scaffold Story — identified
- * by the literal `bdd-scaffold` goal token the `epic-plan-decompose-author`
+ * by the literal `bdd-scaffold` goal token the decomposer prompt
  * skill's WAVE-0 BDD SCAFFOLD STORY section requires. Scaffold Stories are
  * not a Delivery Slicing slice, so they are excluded from the count
  * comparison — BDD-adopting consumer repos still benefit from the
@@ -145,7 +145,7 @@ function isBddScaffoldStory(story) {
  *
  * @param {object} input
  * @param {object[]} input.draftStories - The draft `tickets.json` array
- *   (`epic-plan-decompose-author`'s output) — raw Story ticket objects with
+ *   (the decomposer's output) — raw Story ticket objects with
  *   top-level `slug` / `depends_on` / `body` (serialized string).
  * @param {string} input.epicBody - The Epic body carrying the folded Tech
  *   Spec sections (`## Delivery Slicing` onward).