mandrel 2.35.0 → 2.36.0

package/.agents/scripts/lib/orchestration/merge-poll.js

@@ -243,6 +243,170 @@ export function requiredCheckFailedBlocksMerge(prProbe) {
   );
 }
 
+/**
+ * The one `mergeStateStatus` value that means the PR is mergeable **despite**
+ * red runs — GitHub's own words are "mergeable with non-passing commit
+ * status". It is the required-vs-advisory discriminator the rollup itself
+ * cannot supply: under `UNSTABLE` the red runs are, by definition, not
+ * required, so native auto-merge will land the PR over them.
+ *
+ * The exact complement of {@link MERGE_GATED_STATE}: `BLOCKED` means the red
+ * run gates the merge (`failingChecksBlockMerge`), `UNSTABLE` means it does
+ * not and only mandrel can stop the landing.
+ */
+const MERGE_ADVISORY_STATE = 'UNSTABLE';
+
+/**
+ * Pure: project the HEAD-ANCHORED runs that genuinely concluded red, naming
+ * each one (Story #5096).
+ *
+ * Same red-ness test as {@link deriveRequiredRunEvidence} — `FAILURE` /
+ * `ERROR` only, never `CANCELLED` / `TIMED_OUT` / `SKIPPED`, which are the
+ * superseded-push and sibling-invalidated runs a bare rollup read miscounts
+ * (the #4695 / #4710 trap) — but it returns the runs rather than a boolean, so
+ * a block summary can name the offending job and the advisory allowlist can
+ * match on it.
+ *
+ * `name` is the CheckRun's `name`, falling back to a legacy StatusContext's
+ * `context`, and is `null` when the projection carries neither. A run with no
+ * readable name can never match an allowlist entry, so it always blocks — the
+ * conservative direction for a gate whose whole purpose is to stop a silent
+ * landing.
+ *
+ * @param {Array<{name?: string, context?: string, status?: string, conclusion?: string, state?: string}>} statusCheckRollup
+ * @returns {Array<{ name: string|null, conclusion: string }>}
+ */
+export function deriveRedHeadRuns(statusCheckRollup) {
+  if (!Array.isArray(statusCheckRollup)) return [];
+  const red = [];
+  for (const check of statusCheckRollup) {
+    const conclusion = String(check?.conclusion ?? '').toUpperCase();
+    const state = String(check?.state ?? '').toUpperCase();
+    const isRed =
+      conclusion === 'FAILURE' ||
+      conclusion === 'ERROR' ||
+      state === 'FAILURE' ||
+      state === 'ERROR';
+    if (!isRed) continue;
+    const name =
+      typeof check?.name === 'string' && check.name
+        ? check.name
+        : typeof check?.context === 'string' && check.context
+          ? check.context
+          : null;
+    red.push({ name, conclusion: conclusion || state });
+  }
+  return red;
+}
+
+/**
+ * Pure: drop the red runs a consumer has exempted via
+ * `delivery.ci.advisoryAllowlist`, returning the ones that still block.
+ *
+ * Matching is exact on the run name. An unnamed run never matches (see
+ * {@link deriveRedHeadRuns}).
+ *
+ * @param {Array<{ name: string|null, conclusion: string }>} redHeadRuns
+ * @param {string[]} [allowlist]
+ * @returns {Array<{ name: string|null, conclusion: string }>}
+ */
+export function selectBlockingRedRuns(redHeadRuns, allowlist = []) {
+  if (!Array.isArray(redHeadRuns) || redHeadRuns.length === 0) return [];
+  const exempt = new Set(
+    (Array.isArray(allowlist) ? allowlist : [])
+      .filter((entry) => typeof entry === 'string' && entry)
+      .map((entry) => entry),
+  );
+  if (exempt.size === 0) return [...redHeadRuns];
+  return redHeadRuns.filter((run) => !(run?.name && exempt.has(run.name)));
+}
+
+/**
+ * Pure: does this PR carry a genuinely red ADVISORY run — one that will NOT
+ * stop GitHub from landing the PR, and therefore one only mandrel can act on?
+ * (Story #5096.)
+ *
+ * The complement of {@link requiredCheckFailedBlocksMerge}. That predicate
+ * answers "is a red REQUIRED check gating the merge" (`BLOCKED`); this one
+ * answers "is a red NON-required check about to be merged straight past"
+ * (`UNSTABLE`). The two are mutually exclusive by construction, so a red
+ * required check keeps its existing `checks-failed` treatment untouched.
+ *
+ * **Fails OPEN by design.** `UNKNOWN`, `CLEAN`, `BEHIND`, or an absent
+ * `mergeStateStatus` all return `false`. The asymmetry is the same one
+ * {@link failingChecksBlockMerge} documents and is deliberate: failing to
+ * block costs an unattended landing the operator can still revert, whereas
+ * blocking wrongly strands a mergeable PR at `agent::blocked` that only an
+ * operator can unpick. A transient `UNKNOWN` must never do the latter.
+ *
+ * @param {{ mergeStateStatus?: string, redHeadRuns?: Array<{name: string|null, conclusion: string}> }} [prProbe]
+ * @param {string[]} [allowlist] `delivery.ci.advisoryAllowlist`.
+ * @returns {boolean}
+ */
+export function advisoryCheckFailedBlocksArm(prProbe, allowlist = []) {
+  if (
+    String(prProbe?.mergeStateStatus ?? '').toUpperCase() !==
+    MERGE_ADVISORY_STATE
+  ) {
+    return false;
+  }
+  return selectBlockingRedRuns(prProbe?.redHeadRuns, allowlist).length > 0;
+}
+
+/**
+ * Pure: the merge wait's advisory-gate decision, the sibling of
+ * {@link decideMergeWaitFailFast} (Story #5096).
+ *
+ * Encapsulates the whole policy — the knob, the predicate, and the allowlist
+ * projection — so the poll body carries a single assignment rather than three
+ * decision points. `runMergePoll` sits above `check-cyclomatic`'s ceiling
+ * already; every branch added inline there is a real regression, and this
+ * policy has a natural home beside the predicate it consumes.
+ *
+ * Returns `null` when the wait should keep polling — the knob is off, the PR
+ * is not in the advisory-red state, or every red run is allowlisted.
+ *
+ * @param {object} args
+ * @returns {{ blockingRuns: Array<object>, reason: string } | null}
+ */
+export function decideAdvisoryGateBlock({
+  probe,
+  blockOnAdvisoryFailure,
+  advisoryAllowlist,
+}) {
+  if (!blockOnAdvisoryFailure) return null;
+  if (!advisoryCheckFailedBlocksArm(probe, advisoryAllowlist)) return null;
+  const blockingRuns = selectBlockingRedRuns(
+    probe?.redHeadRuns,
+    advisoryAllowlist,
+  );
+  return { blockingRuns, reason: formatAdvisoryGateReason(blockingRuns) };
+}
+
+/**
+ * Format the one-line reason a `merge.unlanded` record and the operator-facing
+ * block carry for an `advisory-gate-red` verdict, naming each offending job
+ * and its conclusion.
+ *
+ * @param {Array<{ name: string|null, conclusion: string }>} blockingRuns
+ * @returns {string}
+ */
+export function formatAdvisoryGateReason(blockingRuns) {
+  const named = (Array.isArray(blockingRuns) ? blockingRuns : [])
+    .map(
+      (run) =>
+        `${run?.name ?? '(unnamed run)'} → ${run?.conclusion ?? 'FAILURE'}`,
+    )
+    .join(', ');
+  return (
+    'A non-required (advisory) check concluded red on the PR head, and GitHub ' +
+    'reports the PR mergeable anyway (mergeStateStatus=UNSTABLE) — native ' +
+    'auto-merge would land it over the failure. Red advisory job(s): ' +
+    `${named || '(none named)'}. Merge by hand to land over it deliberately, ` +
+    'or exempt the job via delivery.ci.advisoryAllowlist.'
+  );
+}
+
 /**
  * Pure: the merge wait's single fail-fast decision (Story #4710 — extracted
  * from the two near-verbatim inline blocks in `runConfirmMergePhase`'s poll

package/.agents/scripts/lib/orchestration/single-story-close/phases/auto-merge.js

@@ -63,6 +63,12 @@
 
 import { gh as defaultGh } from '../../../gh-exec.js';
 import { resolveAutoMergeArmCwd } from '../../auto-merge-cwd.js';
+import {
+  advisoryCheckFailedBlocksArm,
+  deriveRedHeadRuns,
+  formatAdvisoryGateReason,
+  selectBlockingRedRuns,
+} from '../../merge-poll.js';
 
 /**
  * Arm reasons that mean **the operator deliberately owns the merge** — the PR
@@ -321,6 +327,116 @@ function makeDefaultGhAutoMergeRunner(gh) {
   };
 }
 
+/**
+ * Evaluate the pre-arm advisory-gate verdict (Story #5096).
+ *
+ * GitHub native auto-merge is defined to wait on REQUIRED contexts only, so a
+ * red ADVISORY quality gate — a coverage, mutation, duplication, a11y or
+ * bundle-size ratchet a consumer deliberately left non-required — is merged
+ * straight past once the required contexts go green. The arming decision is
+ * mandrel's, not GitHub's, so this is where it has to be made.
+ *
+ * Reads the SAME head-anchored derivation the merge wait uses
+ * (`readPrWaitProbe` → `deriveRedHeadRuns`), so a `CANCELLED` superseded-push
+ * run or a sibling-invalidated run is never mistaken for a red gate (the
+ * #4695 / #4710 trap), and `mergeStateStatus: UNSTABLE` supplies the
+ * required-vs-advisory discrimination the rollup itself lacks.
+ *
+ * **Non-fatal and fail-open in every degraded case.** A probe error, an absent
+ * or `UNKNOWN` merge state, or a disabled knob all return "do not block" — the
+ * arm proceeds exactly as it did before this Story. Only a positive verdict
+ * refuses.
+ *
+ * @param {object} args
+ * @returns {Promise<{ blocked: boolean, blockingRuns?: Array<object>, reason?: string }>}
+ */
+async function readAdvisoryProbe({ prNumber, gh }) {
+  const view = await (gh ?? defaultGh).pr.view(prNumber, [
+    'mergeStateStatus',
+    'statusCheckRollup',
+  ]);
+  return {
+    mergeStateStatus:
+      typeof view?.mergeStateStatus === 'string'
+        ? view.mergeStateStatus
+        : undefined,
+    redHeadRuns: deriveRedHeadRuns(view?.statusCheckRollup),
+  };
+}
+
+/**
+ * Disarm GitHub native auto-merge on a PR (Story #5096).
+ *
+ * Lives here, beside the arm, because `lifecycle-lint`'s merge-lockout rule
+ * confines every `gh pr merge` invocation to this module: auto-merge
+ * enablement — and therefore its reversal — must flow through the Story close
+ * path rather than being spelled out wherever a caller happens to need it.
+ * The merge wait imports this rather than shelling out itself.
+ *
+ * Best-effort by contract: the caller blocks the Story either way, and a
+ * failed disarm is reported rather than thrown, because the one thing it
+ * cannot do is stop GitHub from landing the PR.
+ *
+ * @returns {Promise<boolean>} whether the disarm actually took.
+ */
+export async function disarmAutoMerge({ prNumber, gh, progress }) {
+  try {
+    await (gh ?? defaultGh).pr.merge(String(prNumber), ['--disable-auto']);
+    progress?.(
+      'CONFIRM',
+      `🔓 Auto-merge DISARMED on PR #${prNumber} — the PR stays open and hand-mergeable.`,
+    );
+    return true;
+  } catch (err) {
+    progress?.(
+      'CONFIRM',
+      `⚠️ Could not disarm auto-merge on PR #${prNumber} (${err?.message ?? err}) — ` +
+        'GitHub may still land it when the required checks pass. Disarm by hand.',
+    );
+    return false;
+  }
+}
+
+async function evaluateAdvisoryGate({
+  prNumber,
+  gh,
+  blockOnAdvisoryFailure,
+  advisoryAllowlist,
+  readPrWaitProbeFn,
+  progress,
+}) {
+  if (!blockOnAdvisoryFailure) return { blocked: false };
+  let probe;
+  try {
+    probe = await readPrWaitProbeFn({ prNumber, gh });
+  } catch (err) {
+    progress?.(
+      'PR',
+      `⚠️ Advisory-gate probe failed (${err?.message ?? err}) — arming anyway.`,
+    );
+    return { blocked: false };
+  }
+  if (probe?.error) {
+    progress?.(
+      'PR',
+      `⚠️ Advisory-gate probe unavailable (${probe.error}) — arming anyway.`,
+    );
+    return { blocked: false };
+  }
+  if (!advisoryCheckFailedBlocksArm(probe, advisoryAllowlist)) {
+    return { blocked: false };
+  }
+  const blockingRuns = selectBlockingRedRuns(
+    probe.redHeadRuns,
+    advisoryAllowlist,
+  );
+  return {
+    blocked: true,
+    blockingRuns,
+    reason: formatAdvisoryGateReason(blockingRuns),
+  };
+}
+
 /**
  * Dispatch auto-merge enablement based on `--no-auto-merge`, an
  * unparseable PR number, or a `gh` failure. Returns the structured
@@ -347,8 +463,11 @@ export async function runAutoMergePhase({
   prUrl,
   noAutoMerge,
   autoMergePolicy = 'trust-ci',
+  blockOnAdvisoryFailure = true,
+  advisoryAllowlist = [],
   gh,
   progress,
+  readPrWaitProbeFn = readAdvisoryProbe,
 }) {
   if (noAutoMerge) {
     progress('PR', '⏭  Auto-merge disabled (--no-auto-merge).');
@@ -381,6 +500,32 @@ export async function runAutoMergePhase({
       autoMergeReason: 'pr-number-unparseable',
     };
   }
+  // Story #5096 — refuse to arm over a genuinely red ADVISORY check. This
+  // gate covers the narrow case where the gate is ALREADY red at close time
+  // (a re-close, or a gate carried over from an earlier push); the merge
+  // wait owns the common case, where the gate reddens after arming.
+  const advisory = await evaluateAdvisoryGate({
+    prNumber,
+    gh,
+    blockOnAdvisoryFailure,
+    advisoryAllowlist,
+    readPrWaitProbeFn,
+    progress,
+  });
+  if (advisory.blocked) {
+    progress(
+      'PR',
+      `🛑 Auto-merge NOT armed on PR #${prNumber}: ${advisory.reason}`,
+    );
+    return {
+      autoMergeEnabled: false,
+      autoMergeReason: 'advisory-gate-red',
+      advisoryGate: {
+        blockingRuns: advisory.blockingRuns,
+        reason: advisory.reason,
+      },
+    };
+  }
   const result = await enableAutoMergeWith({ cwd, prNumber, gh });
   if (result.enabled) {
     if (result.directMerged) {

package/.agents/scripts/lib/orchestration/single-story-close/phases/confirm-merge.js

@@ -90,6 +90,7 @@
  *     confirm.
  */
 
+import { getCiDelivery } from '../../../config/ci.js';
 import { createGh } from '../../../gh-exec.js';
 import {
   confirmStoryMerged as defaultConfirmStoryMerged,
@@ -106,8 +107,10 @@ import { classifyMergeBlock as defaultClassifyMergeBlock } from '../../merge-blo
 import {
   DEFAULT_INTERVAL_SECONDS,
   DEFAULT_MAX_BUDGET_SECONDS,
+  decideAdvisoryGateBlock,
   decideMergeWaitFailFast,
   deriveChecksStatus,
+  deriveRedHeadRuns,
   deriveRequiredRunEvidence,
   MERGE_WAIT_GH_TIMEOUT_MS,
 } from '../../merge-poll.js';
@@ -117,6 +120,7 @@ import {
   STATE_LABELS,
   transitionTicketState,
 } from '../../ticketing.js';
+import { disarmAutoMerge } from './auto-merge.js';
 import { runPostLandTail as defaultRunPostLandTail } from './post-land.js';
 
 /**
@@ -256,6 +260,10 @@ export async function readPrWaitProbe({
       // the aggregate `checksStatus` folds together. `null` when the rollup is
       // absent/empty — the loop's consecutive-probe fallback owns that path.
       requiredRunEvidence: deriveRequiredRunEvidence(view?.statusCheckRollup),
+      // The named red head runs (Story #5096), so an `advisory-gate-red`
+      // verdict can name the offending job and match the allowlist. Same
+      // red-ness test as `requiredRunEvidence`, so the two cannot disagree.
+      redHeadRuns: deriveRedHeadRuns(view?.statusCheckRollup),
     };
   } catch (err) {
     return {
@@ -263,6 +271,7 @@ export async function readPrWaitProbe({
       mergedAt: null,
       createdAt: null,
       checksStatus: 'pending',
+      redHeadRuns: [],
       error: `PR probe failed: ${err?.message ?? err}`,
     };
   }
@@ -541,6 +550,46 @@ async function blockOnFlipFailed({
  * is best-effort logged rather than thrown — the caller owns surfacing the
  * non-zero exit once this returns.
  */
+/**
+ * Story #5096 — resolve the advisory-gate terminal for one poll.
+ *
+ * Takes the poll's current `unlanded` and returns it unchanged when a terminal
+ * is already decided, so the caller is a single assignment with NO added
+ * branch. `runMergePoll` is already above `check-cyclomatic`'s ceiling; the
+ * three decision points this would otherwise cost inline are a real gate
+ * regression, and they belong with the policy either way.
+ *
+ * Disarms BEFORE returning the terminal: an armed PR can merge out from under
+ * the block the caller is about to record.
+ */
+async function resolveAdvisoryUnlanded({
+  unlanded,
+  probe,
+  blockOnAdvisoryFailure,
+  advisoryAllowlist,
+  prNumber,
+  gh,
+  progress,
+  disarmAutoMergeFn,
+  elapsedSeconds,
+}) {
+  if (unlanded) return unlanded;
+  const advisory = decideAdvisoryGateBlock({
+    probe,
+    blockOnAdvisoryFailure,
+    advisoryAllowlist,
+  });
+  if (!advisory) return null;
+  progress?.('CONFIRM', `🛑 PR #${prNumber}: ${advisory.reason}`);
+  await disarmAutoMergeFn({ prNumber, gh, progress });
+  return {
+    prProbe: probe,
+    budget: { exhausted: false, elapsedSeconds },
+    blockClassOverride: 'advisory-gate-red',
+    reasonOverride: advisory.reason,
+  };
+}
+
 async function blockOnUnlanded({
   storyId,
   prNumber,
@@ -552,12 +601,24 @@ async function blockOnUnlanded({
   progress,
   classifyMergeBlockFn,
   emitMergeUnlandedFn,
+  blockClassOverride,
+  reasonOverride,
 }) {
-  const { blockClass, reason } = classifyMergeBlockFn({
-    armResult,
-    prProbe,
-    budget,
-  });
+  // Story #5096 — `advisory-gate-red` is emitted DIRECTLY, never derived.
+  // `classifyMergeBlock` cannot produce it: by construction GitHub is NOT
+  // gating this merge (`mergeStateStatus: UNSTABLE`), which is the entire
+  // condition the class names, so every classifier heuristic reads the PR as
+  // healthy.
+  const { blockClass, reason } = blockClassOverride
+    ? {
+        blockClass: blockClassOverride,
+        reason: reasonOverride ?? blockClassOverride,
+      }
+    : classifyMergeBlockFn({
+        armResult,
+        prProbe,
+        budget,
+      });
   const elapsedSeconds = budget?.elapsedSeconds ?? 0;
   // Which evidence path produced a `checks-failed` verdict (Story #4695):
   // `per-run` (head-anchored required-run evidence) or `consecutive-probe`
@@ -820,6 +881,7 @@ export async function runConfirmMergePhase({
   prUrl,
   autoMergeEnabled,
   autoMergeReason,
+  advisoryGate,
   provider,
   config,
   maxWaitSeconds: maxWaitSecondsOverride,
@@ -834,6 +896,7 @@ export async function runConfirmMergePhase({
   emitMergeUnlandedFn = defaultEmitMergeUnlanded,
   emitMergeFlipFailedFn = defaultEmitMergeFlipFailed,
   runPostLandTailFn = defaultRunPostLandTail,
+  disarmAutoMergeFn = disarmAutoMerge,
   sleepFn = defaultSleep,
   nowMsFn = Date.now,
   ghTimeoutMs = MERGE_WAIT_GH_TIMEOUT_MS,
@@ -857,6 +920,15 @@ export async function runConfirmMergePhase({
       progress,
       classifyMergeBlockFn,
       emitMergeUnlandedFn,
+      // Story #5096 — the arm phase already refused over a red advisory gate;
+      // carry its verdict through instead of letting the classifier read this
+      // as a generic `arm-failure`.
+      ...(autoMergeReason === 'advisory-gate-red'
+        ? {
+            blockClassOverride: 'advisory-gate-red',
+            reasonOverride: advisoryGate?.reason,
+          }
+        : {}),
     });
   }
 
@@ -871,6 +943,8 @@ export async function runConfirmMergePhase({
     maxWaitSecondsOverride,
     mergeWatchModeOverride,
   );
+  // Story #5096 — the advisory-gate knobs, read once for the whole wait.
+  const { blockOnAdvisoryFailure, advisoryAllowlist } = getCiDelivery(config);
   const intervalMs = intervalSeconds * 1000;
   const startedAtMs = nowMsFn();
   let anchorMs = startedAtMs;
@@ -1020,6 +1094,23 @@ export async function runConfirmMergePhase({
           },
         };
       }
+
+      // Story #5096 — the ADVISORY counterpart, and the half that catches the
+      // common shape. Close arms immediately after opening the PR, while the
+      // gate is still QUEUED, so the pre-arm refusal in `auto-merge.js` sees
+      // nothing; the gate reddens here, mid-wait, and native auto-merge would
+      // land the PR the moment the REQUIRED contexts go green.
+      unlanded = await resolveAdvisoryUnlanded({
+        unlanded,
+        probe,
+        blockOnAdvisoryFailure,
+        advisoryAllowlist,
+        prNumber,
+        gh: injectedGh,
+        progress,
+        disarmAutoMergeFn,
+        elapsedSeconds: Math.round(waitedMs / 1000),
+      });
     }
 
     if (!unlanded) {

package/.agents/scripts/lib/orchestration/single-story-close/runner.js

@@ -485,6 +485,7 @@ async function resolveAutoMergeOutcome({ alreadyMerged, ...phaseArgs }) {
       autoMergeReason: null,
       localCleanupDeferred: false,
       directMerged: false,
+      advisoryGate: null,
     };
   }
   return await runAutoMergePhase(phaseArgs);
@@ -541,6 +542,7 @@ async function finishWithMergeWait(prCtx, deps) {
     prUrl: prCtx.prUrl,
     autoMergeEnabled: prCtx.autoMergeEnabled,
     autoMergeReason: prCtx.autoMergeReason,
+    advisoryGate: prCtx.advisoryGate,
     provider: deps.provider,
     config: prCtx.config,
     maxWaitSeconds: deps.maxWaitSeconds,
@@ -796,18 +798,23 @@ async function runClosePipeline({
     WorktreeManager,
   });
   setPhase('auto-merge');
+  const ciDelivery = getCiDelivery(config);
   const {
     autoMergeEnabled,
     autoMergeReason,
     localCleanupDeferred,
     directMerged,
+    advisoryGate,
   } = await resolveAutoMergeOutcome({
     alreadyMerged,
     cwd: options.cwd,
     prNumber,
     prUrl,
     noAutoMerge: options.noAutoMerge,
-    autoMergePolicy: getCiDelivery(config).autoMerge,
+    autoMergePolicy: ciDelivery.autoMerge,
+    // Story #5096 — the pre-arm advisory-gate refusal.
+    blockOnAdvisoryFailure: ciDelivery.blockOnAdvisoryFailure,
+    advisoryAllowlist: ciDelivery.advisoryAllowlist,
     gh: injectedGh,
     progress,
   });
@@ -866,6 +873,7 @@ async function runClosePipeline({
     prUrl,
     autoMergeEnabled,
     autoMergeReason,
+    advisoryGate,
     worktreeReaped,
     localCleanupDeferred,
     directMerged,

package/.agents/scripts/notify.js

@@ -7,16 +7,10 @@
  * Single dispatch entry point for runtime notifications across two
  * independent channels.
  *
- * Lifecycle-bus integration (Epic #2172): under the Wave-7+ runtime,
- * `notify()` is invoked from the `NotifyDispatcher` listener
- * (`lib/orchestration/lifecycle/listeners/notify-dispatcher.js`),
- * which subscribes to lifecycle events and maps `event.severity` →
- * `notify()` payload. Direct inline calls at phase boundaries are no
- * longer the canonical path — listeners on the bus are. See
- * [`docs/LIFECYCLE.md`](../docs/LIFECYCLE.md) for the bus contract,
- * event taxonomy, and the dispatcher's wiring. Direct CLI / library
- * invocations remain supported for one-shot operator commands and the
- * structured-comment back-channel.
+ * Direct inline calls at phase boundaries are the only path: `notify()`
+ * is invoked from the caller that has something to say. Direct CLI /
+ * library invocations are equally supported, for one-shot operator
+ * commands and the structured-comment back-channel.
  *
  * Channels:
  *

package/.agents/workflows/audit-documentation.md

@@ -38,9 +38,9 @@ union of:
    key for it.
 
 **Generated docs are excluded from per-doc semantic review.** The output of
-`generate-config-docs.js`, `generate-lifecycle-docs.js`, and
-`generate-workflows-doc.js`, and the synced `.claude/commands/` mirrors, are
-generator-owned: hand-editing them is never the remediation. Instead, Step 1
+`generate-config-docs.js` and `generate-workflows-doc.js`, and the synced
+`.claude/commands/` mirrors, are generator-owned: hand-editing them is never
+the remediation. Instead, Step 1
 runs the generators' `--check` mode and emits a **single** "generator output
 dirty" finding when their output is stale — the remediation is "rerun the
 generator", not "edit the doc". Auto-generated changelog files
@@ -79,7 +79,6 @@ are cheap, exact, and de-duplicate the easy findings:
 ```bash
 node .agents/scripts/check-doc-links.js
 node .agents/scripts/generate-config-docs.js --check
-node .agents/scripts/generate-lifecycle-docs.js --check
 node .agents/scripts/generate-workflows-doc.js --check
 node .agents/scripts/resolve-doc-tiers.js --json
 ```
@@ -87,8 +86,8 @@ node .agents/scripts/resolve-doc-tiers.js --json
 Fold the results in as findings:
 
 - **Checker failures** (broken links, generator drift) become individual
-  findings with `Category: Link Integrity` (or `Generator Drift` for the
-  lifecycle gate), citing the checker output verbatim.
+  findings with `Category: Link Integrity`, citing the checker output
+  verbatim.
 - **Generator dirtiness** (any `--check` reporting stale output, including
   a stale `.claude/commands/` mirror) becomes **one single finding** with
   `Category: Generator Drift` — never per-line findings — whose

package/docs/CHANGELOG.md

@@ -15,6 +15,24 @@ All notable changes to this project will be documented in this file.
 -->
 <!-- markdownlint-disable-file MD004 MD012 MD037 -->
 
+## [2.36.0](https://github.com/dsj1984/mandrel/compare/mandrel-v2.35.0...mandrel-v2.36.0) (2026-08-29)
+
+
+### ⚠ BREAKING CHANGES
+
+* `.agents/scripts/generate-lifecycle-docs.js` is removed from the published payload, and the framework no longer requires a consumer `docs/LIFECYCLE.md`. A consumer that created that file only to stop the generator aborting can delete it as residue — nothing else reads it. A consumer invoking the generator by hand, or chaining it in its own `docs:gen` / `docs:check`, should drop the call. The lifecycle schemas under `.agents/schemas/lifecycle/` still ship unchanged and the emit path is untouched.
+
+### Fixed
+
+* **check-doc-links:** percent-decode relative link targets before the existence check (refs [#5090](https://github.com/dsj1984/mandrel/issues/5090)) ([#5092](https://github.com/dsj1984/mandrel/issues/5092)) ([024afff](https://github.com/dsj1984/mandrel/commit/024afff5aa000ace8e4f8ee2df6bf246acd0ae40))
+* gate auto-merge arming and the merge wait on head-anchored advisory check conclusions ([#5096](https://github.com/dsj1984/mandrel/issues/5096)) ([#5097](https://github.com/dsj1984/mandrel/issues/5097)) ([a6ae194](https://github.com/dsj1984/mandrel/commit/a6ae194349951ab8cc459f9a4d21a46785014ffd))
+* **git-cleanup:** branch the merged-tip skip taxonomy on ancestry instead of SHA inequality ([#5086](https://github.com/dsj1984/mandrel/issues/5086)) ([#5087](https://github.com/dsj1984/mandrel/issues/5087)) ([caf41b0](https://github.com/dsj1984/mandrel/commit/caf41b0a973866ba1035c5c10178eb46e7c1b078))
+
+
+### Changed
+
+* stop requiring consumers to carry docs/LIFECYCLE.md — retire the consumer-side lifecycle doc mirror ([#5089](https://github.com/dsj1984/mandrel/issues/5089)) ([#5091](https://github.com/dsj1984/mandrel/issues/5091)) ([ad16df8](https://github.com/dsj1984/mandrel/commit/ad16df881692fc5dd169bc4f0bcf73191a872345))
+
 ## [2.35.0](https://github.com/dsj1984/mandrel/compare/mandrel-v2.34.0...mandrel-v2.35.0) (2026-08-28)
 
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mandrel",
-  "version": "2.35.0",
+  "version": "2.36.0",
   "description": "Claude Code-first opinionated workflow framework: instructions, skills, rules, and SDLC workflows that govern AI coding assistants.",
   "files": [
     ".agents/",
@@ -32,8 +32,8 @@
     "baselines:prune": "node .agents/scripts/prune-baseline-orphans.js",
     "lint:md": "markdownlint-cli2 \".agents/**/*.md\" \"*.md\" \"!node_modules/**\" \"!.worktrees/**\"",
     "lint": "node .agents/scripts/run-lint.js && npm run docs:check",
-    "docs:gen": "node .agents/scripts/generate-config-docs.js && node .agents/scripts/generate-lifecycle-docs.js && node .agents/scripts/generate-workflows-doc.js && node .agents/scripts/generate-lens-checklists.js",
-    "docs:check": "node .agents/scripts/generate-config-docs.js --check && node .agents/scripts/generate-lifecycle-docs.js --check && node .agents/scripts/generate-workflows-doc.js --check && node .agents/scripts/generate-lens-checklists.js --check && node .agents/scripts/check-doc-links.js && npm run skills:check",
+    "docs:gen": "node .agents/scripts/generate-config-docs.js && node .agents/scripts/generate-workflows-doc.js && node .agents/scripts/generate-lens-checklists.js",
+    "docs:check": "node .agents/scripts/generate-config-docs.js --check && node .agents/scripts/generate-workflows-doc.js --check && node .agents/scripts/generate-lens-checklists.js --check && node .agents/scripts/check-doc-links.js && npm run skills:check",
     "skills:index": "node .agents/scripts/generate-skills-index.js",
     "skills:check": "node .agents/scripts/generate-skills-index.js --check",
     "format": "biome format --write .",