npm - mandrel - Versions diffs - 2.0.0 → 2.2.0 - Mend

mandrel 2.0.0 → 2.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (323) hide show

package/.agents/scripts/lib/orchestration/change-set.js ADDED Viewed

@@ -0,0 +1,103 @@
+/**
+ * lib/orchestration/change-set.js — the **one** Story change-set enumerator
+ * (Story #4593).
+ *
+ * ## Why this exists
+ *
+ * A single Story delivery used to enumerate `git diff --name-only
+ * <base>...<head>` three to four separate times: once for the ceremony
+ * derivation in `helpers/deliver-story`, once inside `runCodeReview` (to derive
+ * the review depth), once for the Story-scope local-lens roster, and once more
+ * per fresh acceptance critic. Every one of those consumers must agree about
+ * *what changed* — ceremony level and review depth both flow from
+ * `deriveChangeLevel`, so two enumerations straddling a commit could route the
+ * same Story two different ways. Computing the set once and injecting it closes
+ * that window and drops the redundant git calls.
+ *
+ * ## Contract
+ *
+ * {@link computeChangeSet} is **total**: it never throws. A diff it cannot
+ * enumerate (git failure, missing ref, spawn error) yields
+ * `{ files: null, enumerated: false }` — the neutral "diff unknown" signal that
+ * `deriveChangeLevel` / `resolveDepth` already fail safe on (`standard` depth, a
+ * `fresh` critic). `null` is deliberately distinct from `[]`: an empty array is
+ * the *fact* that nothing changed, whereas `null` is the *absence* of evidence,
+ * and only the latter must never buy a change less checking.
+ *
+ * The returned `files` are trimmed, de-duplicated, and sorted, so two consumers
+ * comparing the same change set compare byte-identical lists. The refs the set
+ * was computed against ride along on the envelope so a downstream consumer can
+ * report (or assert) its provenance rather than re-deriving it.
+ *
+ * @typedef {{
+ *   baseRef: string,
+ *   headRef: string,
+ *   files: string[]|null,
+ *   enumerated: boolean,
+ * }} ChangeSet
+ *
+ * @typedef {typeof gitSpawn} GitSpawnFn
+ */
+import { gitSpawn } from '../git-utils.js';
+/**
+ * Trim, drop empties, de-duplicate, and sort raw `git diff --name-only` output.
+ * Pure.
+ *
+ * @param {string} stdout
+ * @returns {string[]}
+ */
+function normalizeFileList(stdout) {
+  const seen = new Set();
+  for (const line of stdout.split('\n')) {
+    const file = line.trim();
+    if (file.length > 0) seen.add(file);
+  }
+  return [...seen].sort();
+}
+/**
+ * Compute the change set for the `baseRef...headRef` diff **once**, for every
+ * consumer that needs to know what a Story touched.
+ *
+ * Total — never throws; see the module header for the `null` vs `[]` contract.
+ *
+ * @param {{
+ *   baseRef: string,
+ *   headRef: string,
+ *   cwd?: string,
+ *   gitSpawnFn?: typeof gitSpawn,
+ * }} args
+ * @returns {ChangeSet}
+ */
+export function computeChangeSet({
+  baseRef,
+  headRef,
+  cwd = process.cwd(),
+  gitSpawnFn = gitSpawn,
+} = {}) {
+  const unknown = { baseRef, headRef, files: null, enumerated: false };
+  if (typeof baseRef !== 'string' || baseRef.length === 0) return unknown;
+  if (typeof headRef !== 'string' || headRef.length === 0) return unknown;
+  try {
+    const result = gitSpawnFn(
+      cwd,
+      'diff',
+      '--name-only',
+      `${baseRef}...${headRef}`,
+    );
+    if (!result || result.status !== 0 || typeof result.stdout !== 'string') {
+      return unknown;
+    }
+    return {
+      baseRef,
+      headRef,
+      files: normalizeFileList(result.stdout),
+      enumerated: true,
+    };
+  } catch {
+    return unknown;
+  }
+}

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

@@ -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.
@@ -38,8 +41,8 @@
 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 { computeChangeSet } from './change-set.js';
+import { deriveChangeLevel, resolveDepth } from './review-depth.js';
 import {
   countBySeverity,
   renderFindings,
@@ -49,84 +52,19 @@ 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.
- *
- * @param {{ baseRef: string, headRef: string, gitSpawnFn?: typeof gitSpawn }} args
- * @returns {number|null}
- */
-function countChangedFiles({ baseRef, headRef, gitSpawnFn = gitSpawn }) {
-  try {
-    const result = gitSpawnFn(
-      process.cwd(),
-      'diff',
-      `${baseRef}...${headRef}`,
-      '--name-only',
-    );
-    if (!result || result.status !== 0 || typeof result.stdout !== 'string') {
-      return null;
-    }
-    return result.stdout
-      .trim()
-      .split('\n')
-      .filter((line) => line.length > 0).length;
-  } 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 +90,6 @@ function resolveCommentTargetId(commentTargetId, fallback) {
  *   baseRef: string,
  *   headRef: string,
  *   commentTargetId: number,
- *   epicIdForLedger: null,
  * }}
  */
 function resolveStoryScope(opts, config) {
@@ -175,53 +112,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,38 +139,30 @@ 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,
+ *   gitSpawnFn?: import('./change-set.js').GitSpawnFn,
  *   resolveConfigFn?: typeof resolveConfig,
  *   createReviewProviderFn?: typeof createReviewProvider,
  *   upsertCommentFn?: typeof upsertStructuredComment,
@@ -307,24 +199,47 @@ function resolveProviderName(codeReviewConfig) {
   return 'native';
 }
+/**
+ * Resolve the change set the depth derivation reads (Story #4593).
+ *
+ * `opts.changedFiles` is an injection with three distinct states,
+ * and the difference is load-bearing: an **array** is the change set to use
+ * verbatim; an explicit **null** is a caller (`runStoryReviewCore`) reporting
+ * that it already tried and the diff is unenumerable — re-running git here would
+ * only fail again, so it degrades straight to the fail-safe tier; **absent**
+ * means no caller enumerated at all, so the shared {@link computeChangeSet}
+ * enumerator runs as the fallback (standalone CLI use). On the close path the
+ * spine always injects, so the diff is enumerated exactly once per delivery and
+ * this pillar can never disagree with the lens pass about what changed.
+ */
+function resolveInjectedChangedFiles({ opts, baseRef, headRef }) {
+  if (opts.changedFiles === undefined) {
+    return computeChangeSet({ baseRef, headRef, gitSpawnFn: opts.gitSpawnFn })
+      .files;
+  }
+  return Array.isArray(opts.changedFiles) ? opts.changedFiles : null;
+}
 /**
  * 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 = resolveInjectedChangedFiles({ opts, baseRef, headRef });
   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 +333,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 +392,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 CHANGED Viewed

@@ -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).