mandrel 1.89.0 → 1.90.0

package/.agents/docs/configuration.md

@@ -300,6 +300,7 @@ top-level keys are validation errors.
 | `ci.watch.maxPolls` | No | `integer` | — | — |
 | `ci.watch.maxResumes` | No | `integer` | — | — |
 | `ci.autoMerge` | No | `"trust-ci"` \| `"strict"` | — | Story #4356 (Epic #4355). Merge posture. 'trust-ci' (default) merges once required checks pass; 'strict' additionally requires a clean review gate. |
+| `ci.requireChecks` | No | `boolean` | — | Story #4472. Fail-closed-without-checks policy. When true, the AutomergePredicate refuses to arm merge in a repo that reports zero required checks ('no checks reported'), treating the absent CI gate as a hard block. Defaults to false so a checks-less repo with green close-validation gates lands headlessly instead of parking on the operator-merges path. |
 | `preflight` | No | `object` | — | Story #2899 (Epic #2880, F13). Thresholds consumed by `.agents/scripts/epic-deliver-preflight.js`. When any value is exceeded the preflight envelope flags a breach and /deliver Phase 1 surfaces it via agent::blocked. |
 | `preflight.maxStories` | No | `integer` | — | — |
 | `preflight.maxWaves` | No | `integer` | — | — |

package/.agents/schemas/agentrc.schema.json

@@ -1456,6 +1456,10 @@
               "type": "string",
               "enum": ["trust-ci", "strict"],
               "description": "Story #4356 (Epic #4355). Merge posture. 'trust-ci' (default) merges once required checks pass; 'strict' additionally requires a clean review gate."
+            },
+            "requireChecks": {
+              "type": "boolean",
+              "description": "Story #4472. Fail-closed-without-checks policy. When true, the AutomergePredicate refuses to arm merge in a repo that reports zero required checks ('no checks reported'), treating the absent CI gate as a hard block. Defaults to false so a checks-less repo with green close-validation gates lands headlessly instead of parking on the operator-merges path."
             }
           },
           "additionalProperties": false

package/.agents/schemas/lifecycle/epic.blocked.schema.json

@@ -2,7 +2,7 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://github.com/dsj1984/mandrel/blob/main/.agents/schemas/lifecycle/epic.blocked.schema.json",
   "title": "epic.blocked",
-  "description": "Emitted by AcceptanceReconciler (on a failed acceptance reconciliation) and MergeWatcher (on a merge-watch timeout) when the Epic transitions to agent::blocked. Subscribed by NotifyDispatcher, which fans the blocker out to the curated webhook channel. The reason field carries either a typed marker (timeout:<event>, waiver, …) or a free-form summary; sourceStoryId scopes the blocker to a child Story when applicable.",
+  "description": "Emitted by AcceptanceReconciler (on a failed acceptance reconciliation), MergeWatcher (on a merge-watch timeout), and — in headless runs (Story #4472) — AutomergePredicate (on a predicate refusal that would otherwise silently park) and AutomergeArmer (on a genuine arm failure) when the Epic transitions to agent::blocked. Subscribed by NotifyDispatcher, which fans the blocker out to the curated webhook channel. The reason field carries either a typed marker (timeout:<event>, merge-predicate:refused, merge-arm:failed, waiver, …) or a free-form summary; sourceStoryId scopes the blocker to a child Story when applicable.",
   "type": "object",
   "required": ["reason"],
   "properties": {

package/.agents/schemas/lifecycle/merge.unlanded.schema.json

@@ -27,7 +27,8 @@
         "checks-pending-timeout",
         "branch-protection-human-required",
         "arm-failure",
-        "api-race-other"
+        "api-race-other",
+        "predicate-refused"
       ]
     },
     "reason": { "type": "string", "minLength": 1 },

package/.agents/scripts/coverage-capture.js

@@ -33,6 +33,7 @@ import {
 } from './lib/coverage-capture.js';
 
 import { Logger } from './lib/Logger.js';
+import { hasNpmScript, readPackageScripts } from './lib/npm-scripts.js';
 
 function parseArgs(argv) {
   const out = {
@@ -59,6 +60,22 @@ function main() {
     return 0;
   }
 
+  // Story #4473 — detect the "missing npm script" misconfiguration
+  // distinctly. `close-validation/gates.js` already declines to register
+  // this gate when `test:coverage` is absent, so reaching here without the
+  // script means a direct/pre-push invocation in a consumer that never
+  // defined it. Surface a one-line, fix-naming diagnostic instead of
+  // spawning `npm run test:coverage` only to propagate npm's opaque
+  // "Missing script" exit code.
+  if (!hasNpmScript(readPackageScripts(args.cwd), 'test:coverage')) {
+    Logger.error(
+      '[coverage-capture] ✖ No "test:coverage" script in package.json. ' +
+        'Add one (e.g. "test:coverage": "node --test --experimental-test-coverage") ' +
+        'or disable the CRAP gate via delivery.quality.gates.crap.enabled=false.',
+    );
+    return 1;
+  }
+
   if (args.skipWhenNoCrapFiles) {
     let changed;
     try {

package/.agents/scripts/lib/close-validation/gates.js

@@ -6,6 +6,7 @@
  * runner (`INDEPENDENT_GATE_NAMES` / `partitionGates`).
  */
 
+import { hasNpmScript, readPackageScripts } from '../npm-scripts.js';
 import {
   buildFormatHint,
   FORMAT_CHECK_FALLBACK,
@@ -87,17 +88,30 @@ function isCrapGateEnabled(config) {
 }
 
 /**
- * Conditionally produce the standalone `test` gate entry. Returns an empty
- * array when the CRAP gate is enabled (Story #1798: coverage-capture is the
- * canonical test runner in that mode); returns the legacy single-entry
- * gate otherwise. Splitting this out keeps `buildDefaultGates` flat for
- * the CRAP-cyclomatic gate.
+ * The gates run in the Story worktree, whose `package.json` is the committed
+ * one the consumer ships — the presence of a `test:coverage` script is a
+ * committed fact, so probing at the gate cwd is authoritative. See
+ * `lib/npm-scripts.js` for the shared reader.
+ */
+
+/**
+ * Conditionally produce the standalone `test` gate entry.
  *
- * @param {object|undefined|null} config - Canonical resolved config.
+ * The plain `test` gate is the canonical test runner UNLESS the
+ * coverage-capture gate is taking that role — which happens only when the
+ * CRAP gate is enabled (Story #1798) AND the consumer actually ships a
+ * `test:coverage` script for coverage-capture to run (#4473). When CRAP is
+ * enabled but `test:coverage` is absent, coverage-capture is dropped from
+ * the gate list, so the `test` gate MUST come back — otherwise the consumer
+ * has NO working test gate at all. Splitting this out keeps
+ * `buildDefaultGates` flat for the CRAP-cyclomatic gate.
+ *
+ * @param {boolean} coverageCaptureActive - Whether the coverage-capture gate
+ *   is registered as the test runner for this build.
  * @returns {Gate[]}
  */
-function buildTestGateEntry(config) {
-  if (isCrapGateEnabled(config)) return [];
+function buildTestGateEntry(coverageCaptureActive) {
+  if (coverageCaptureActive) return [];
   return [{ name: 'test', cmd: 'npm', args: ['test'] }];
 }
 
@@ -105,10 +119,13 @@ function buildTestGateEntry(config) {
  * Build the canonical close-validation gate list.
  *
  * Ordering (cheapest fast-fail first): typecheck → lint → [test] →
- * format → coverage-capture → check-baselines. The standalone `test`
- * gate is dropped when `crap.enabled === true` (Story #1798) because
- * coverage-capture carries test-failure signalling under c8 in that
- * mode.
+ * format → [coverage-capture] → check-baselines. The standalone `test`
+ * gate is dropped when coverage-capture is the active test runner — i.e.
+ * `crap.enabled === true` (Story #1798) AND a `test:coverage` script
+ * exists (Story #4473) — because coverage-capture then carries
+ * test-failure signalling under c8. When CRAP is on but `test:coverage` is
+ * absent, coverage-capture is dropped and the `test` gate is restored so
+ * there is always a working test gate.
  *
  * `typecheck` is mandatory; consumers may customise the command via
  * `project.commands.typecheck` (default `npm run typecheck`).
@@ -127,15 +144,34 @@ function buildTestGateEntry(config) {
  * re-discovered inherited main-vs-epic drift in untouched files as phantom
  * regressions and worked around it by hand-setting `BASELINE_REF`.
  *
- * @param {{ config?: object, epicBranch?: string }} [opts] - `config` is the
- *   canonical resolved config (`{ project, delivery, ... }`); gate commands
- *   resolve from `project.commands` and the CRAP toggle from
+ * Story #4473 — the coverage-capture gate spawns `npm run test:coverage`,
+ * so it is registered ONLY when the consumer actually ships that script.
+ * When CRAP is enabled but `test:coverage` is absent, coverage-capture is
+ * dropped and the plain `test` gate is restored (see `buildTestGateEntry`),
+ * so a consumer without a coverage script gets a working degraded test gate
+ * instead of a deterministic close failure with no test gate at all. The
+ * probe reads `package.json` at `cwd` (the gate execution directory).
+ *
+ * @param {{ config?: object, epicBranch?: string, cwd?: string, packageScripts?: Record<string, string> }} [opts]
+ *   `config` is the canonical resolved config (`{ project, delivery, ... }`);
+ *   gate commands resolve from `project.commands` and the CRAP toggle from
  *   `delivery.quality.gates.crap.enabled`. `epicBranch` is the close run's
  *   integration branch (`epic/<id>` for Epic-attached Stories, the base
- *   branch for standalone Stories).
+ *   branch for standalone Stories). `cwd` is where the `package.json`
+ *   coverage-script probe reads from (defaults to `process.cwd()`);
+ *   `packageScripts` injects the scripts map directly (tests) and short-
+ *   circuits the disk read.
  * @returns {Gate[]}
  */
-export function buildDefaultGates({ config, epicBranch } = {}) {
+export function buildDefaultGates({
+  config,
+  epicBranch,
+  cwd,
+  packageScripts,
+} = {}) {
+  const scripts = packageScripts ?? readPackageScripts(cwd);
+  const coverageCaptureActive =
+    isCrapGateEnabled(config) && hasNpmScript(scripts, 'test:coverage');
   const typecheckCmdString = resolveTypecheckCommand(config);
   const [typecheckCmd, ...typecheckArgs] = typecheckCmdString
     .split(/\s+/)
@@ -158,7 +194,7 @@ export function buildDefaultGates({ config, epicBranch } = {}) {
       hint: TYPECHECK_HINT,
     },
     { name: 'lint', cmd: 'npm', args: ['run', 'lint'] },
-    ...buildTestGateEntry(config),
+    ...buildTestGateEntry(coverageCaptureActive),
     {
       // Gate name kept generic ("format") so the close-orchestrator log line
       // and the per-gate phase-timer key don't shift when a repo swaps biome
@@ -172,12 +208,16 @@ export function buildDefaultGates({ config, epicBranch } = {}) {
         ? { changedFileScope: formatChangedFileScope }
         : {}),
     },
-    {
-      name: 'coverage-capture',
-      cmd: 'node',
-      args: ['.agents/scripts/coverage-capture.js'],
-      hint: 'Coverage capture failed — `npm run test:coverage` exited non-zero. Fix failing tests or coverage-threshold breaches, then re-run close.',
-    },
+    ...(coverageCaptureActive
+      ? [
+          {
+            name: 'coverage-capture',
+            cmd: 'node',
+            args: ['.agents/scripts/coverage-capture.js'],
+            hint: 'Coverage capture failed — `npm run test:coverage` exited non-zero. Fix failing tests or coverage-threshold breaches, then re-run close.',
+          },
+        ]
+      : []),
     {
       // Story #2210 — unified `check-baselines` gate is the only path for
       // per-kind regression enforcement. The legacy per-kind in-process

package/.agents/scripts/lib/config/ci.js

@@ -12,12 +12,19 @@
  * waves run; `watch` tunes the merge/CI watch poll loop; and `autoMerge`
  * (default `"trust-ci"`) selects the merge posture — `"trust-ci"` merges once
  * required checks pass, `"strict"` additionally requires a clean review gate.
+ *
+ * Story #4472 adds `requireChecks` (default `false`): when `true` the
+ * AutomergePredicate treats a checks-less repo ("no checks reported") as a
+ * hard block rather than green, so a consumer that wants fail-closed-without-
+ * checks as policy opts into it explicitly instead of the framework blocking
+ * implicitly.
  */
 
 export const CI_DELIVERY_DEFAULTS = Object.freeze({
   skipForStoryPushes: true,
   earlyPr: true,
   autoMerge: 'trust-ci',
+  requireChecks: false,
 });
 
 /**
@@ -28,7 +35,7 @@ export const CI_DELIVERY_DEFAULTS = Object.freeze({
  * defaults; only the scalar knobs carry framework defaults here.
  *
  * @param {object | null | undefined} config
- * @returns {{ skipForStoryPushes: boolean, earlyPr: boolean, autoMerge: 'trust-ci' | 'strict', watch: object | undefined }}
+ * @returns {{ skipForStoryPushes: boolean, earlyPr: boolean, autoMerge: 'trust-ci' | 'strict', requireChecks: boolean, watch: object | undefined }}
  */
 export function getCiDelivery(config) {
   const ci = config?.delivery?.ci ?? config?.ci ?? config ?? {};
@@ -45,6 +52,10 @@ export function getCiDelivery(config) {
       ci.autoMerge === 'trust-ci' || ci.autoMerge === 'strict'
         ? ci.autoMerge
         : CI_DELIVERY_DEFAULTS.autoMerge,
+    requireChecks:
+      typeof ci.requireChecks === 'boolean'
+        ? ci.requireChecks
+        : CI_DELIVERY_DEFAULTS.requireChecks,
     watch:
       ci.watch && typeof ci.watch === 'object' ? { ...ci.watch } : undefined,
   };

package/.agents/scripts/lib/config-settings-schema-delivery.js

@@ -264,6 +264,13 @@ const CI_DELIVERY_SCHEMA = {
     earlyPr: { type: 'boolean' },
     watch: CI_WATCH_SCHEMA,
     autoMerge: { type: 'string', enum: ['trust-ci', 'strict'] },
+    // Story #4472 — fail-closed-without-checks policy. When `true`, the
+    // AutomergePredicate refuses to arm merge in a repo that reports zero
+    // required checks ("no checks reported"), treating the absence of a CI
+    // gate as a hard block instead of green. Defaults to `false` so a
+    // checks-less repo with green close-validation gates lands headlessly
+    // rather than parking on the operator-merges path.
+    requireChecks: { type: 'boolean' },
   },
   additionalProperties: false,
 };

package/.agents/scripts/lib/npm-scripts.js

@@ -0,0 +1,55 @@
+/**
+ * npm-scripts.js — shared `package.json` scripts probe (Story #4473).
+ *
+ * A single, dependency-free reader used wherever the framework must decide
+ * whether a consumer actually ships a given npm script before spawning
+ * `npm run <name>`. Two call sites depend on it:
+ *   - `close-validation/gates.js` — only registers the coverage-capture gate
+ *     when a `test:coverage` script exists (otherwise a consumer without it
+ *     turns the gate into a guaranteed first-try close failure).
+ *   - `coverage-capture.js` — fails fast with a one-line, fix-naming
+ *     diagnostic instead of surfacing npm's opaque "Missing script" exit when
+ *     invoked without the script.
+ *
+ * The reader is deliberately forgiving: any failure (missing file,
+ * unreadable, unparseable, or no `scripts` object) resolves to an empty map
+ * so callers treat "cannot prove the script exists" as "absent" without
+ * throwing.
+ */
+
+import { existsSync, readFileSync } from 'node:fs';
+import path from 'node:path';
+
+/**
+ * Read the `scripts` map from the `package.json` at `cwd`.
+ *
+ * @param {string|undefined|null} cwd - Directory containing `package.json`.
+ *   Defaults to `process.cwd()`.
+ * @returns {Record<string, string>} The scripts map, or `{}` on any failure.
+ */
+export function readPackageScripts(cwd) {
+  try {
+    const pkgPath = path.join(cwd || process.cwd(), 'package.json');
+    if (!existsSync(pkgPath)) return {};
+    const parsed = JSON.parse(readFileSync(pkgPath, 'utf8'));
+    return parsed && typeof parsed.scripts === 'object' && parsed.scripts
+      ? parsed.scripts
+      : {};
+  } catch {
+    return {};
+  }
+}
+
+/**
+ * Does the consumer define a runnable npm script by this name? A script is
+ * "runnable" when it is a present, non-empty string.
+ *
+ * @param {Record<string, string>} scripts - A scripts map (from
+ *   `readPackageScripts`).
+ * @param {string} name - The script name to check (e.g. `test:coverage`).
+ * @returns {boolean}
+ */
+export function hasNpmScript(scripts, name) {
+  const s = scripts?.[name];
+  return typeof s === 'string' && s.trim().length > 0;
+}

package/.agents/scripts/lib/orchestration/lifecycle/emit-merge-unlanded.js

@@ -48,9 +48,13 @@
  *
  * The schema declares `additionalProperties: false`, so this emitter's
  * signature is deliberately narrow: only the schema-allowed fields are
- * accepted. `blockClass` MUST be one of the four classes named in
- * `merge-block-class.js` — pass the classifier's verdict straight
- * through (`classifyMergeBlock(...)` returns `{ blockClass, reason }`).
+ * accepted. `blockClass` MUST be a valid `merge.unlanded` attribution from
+ * `merge-block-class.js` (`MERGE_UNLANDED_BLOCK_CLASSES` — the four
+ * `classifyMergeBlock` outputs plus the directly-emitted `predicate-refused`,
+ * Story #4472). For a post-arm poll-exhaustion block, pass the classifier's
+ * verdict straight through (`classifyMergeBlock(...)` returns
+ * `{ blockClass, reason }`); the predicate/armer refusal paths pass
+ * `predicate-refused` / a classified arm failure directly.
  */
 
 import { appendFileSync, mkdirSync, readFileSync } from 'node:fs';
@@ -98,8 +102,9 @@ function getValidator() {
  * @param {number} opts.ticketId       epicId when `scope === 'epic'`,
  *                                     storyId when `scope === 'story'`.
  * @param {number} opts.prNumber       The PR number that did not land.
- * @param {string} opts.blockClass     One of the four
- *                                     `merge-block-class.js` classes.
+ * @param {string} opts.blockClass     A valid `merge.unlanded` attribution
+ *                                     (`MERGE_UNLANDED_BLOCK_CLASSES` in
+ *                                     `merge-block-class.js`).
  * @param {string} opts.reason         Free-form diagnosis detail — pass
  *                                     the classifier's `reason`.
  * @param {number} opts.elapsedSeconds Elapsed watch/poll time when the

package/.agents/scripts/lib/orchestration/lifecycle/listeners/automerge-armer.js

@@ -54,7 +54,10 @@
 
 import { spawnSync } from 'node:child_process';
 
+import { parsePrNumberFromUrl } from '../../../github-url.js';
 import { resolveAutoMergeArmCwd } from '../../auto-merge-cwd.js';
+import { classifyMergeBlock } from '../../merge-block-class.js';
+import { emitMergeUnlanded } from '../emit-merge-unlanded.js';
 
 /**
  * Default `gh pr view --json autoMergeRequest` probe. Pure-spawn helper
@@ -109,6 +112,64 @@ export function ghPrMergeAuto({
   };
 }
 
+/**
+ * Story #4472 — direct (non-`--auto`) squash-merge fallback.
+ *
+ * GitHub's native auto-merge (`gh pr merge --auto`) can only be QUEUED on a
+ * repository that has the "Allow auto-merge" setting enabled — which in
+ * practice requires branch protection. A repo with zero required checks and
+ * no branch protection (every mandrel-bench sandbox, many real consumer
+ * repos) rejects the `--auto` arm outright with `Auto merge is not allowed
+ * for this repository`. The AutomergePredicate has already cleared the merge
+ * (green/absent required checks + a clean structured-signal verdict) by the
+ * time the armer runs, so the safe, must-land-satisfying fallback is a
+ * direct immediate squash-merge — the epic path's observed de-facto manual
+ * fallback, made legal and kept inside the sole authorized `gh pr merge`
+ * call site.
+ *
+ * Same `--squash --delete-branch` shape and same `resolveArmCwd` re-point as
+ * `ghPrMergeAuto` (so the trailing local `--delete-branch` housekeeping runs
+ * from the primary worktree, not a head-branch worktree). Omitting `--auto`
+ * makes `gh` merge synchronously.
+ */
+export function ghPrMergeDirect({
+  prUrl,
+  cwd,
+  spawnFn = spawnSync,
+  resolveArmCwd = resolveAutoMergeArmCwd,
+}) {
+  const armCwd = resolveArmCwd(cwd);
+  const result = spawnFn(
+    'gh',
+    ['pr', 'merge', prUrl, '--squash', '--delete-branch'],
+    { cwd: armCwd, encoding: 'utf-8', shell: false },
+  );
+  return {
+    status: result.status ?? 1,
+    stdout: result.stdout ?? '',
+    stderr: result.stderr ?? '',
+  };
+}
+
+/**
+ * Pure: does this `gh pr merge --auto` stderr indicate that native
+ * auto-merge is unavailable on the repository (as opposed to a genuine arm
+ * failure — auth, a merge conflict, an already-merged race)? Only this
+ * specific class of failure is safe to retry as a direct merge; everything
+ * else must surface as a real failure. Matched case-insensitively.
+ *
+ * Exported so the marker set is reviewable and testable in isolation.
+ */
+export function isAutoMergeUnavailable(stderr) {
+  const text = String(stderr ?? '').toLowerCase();
+  return (
+    text.includes('auto merge is not allowed') ||
+    text.includes('auto-merge is not allowed') ||
+    text.includes('enablepullrequestautomerge') ||
+    (text.includes('auto') && text.includes('not enabled'))
+  );
+}
+
 /**
  * Pure: parse `gh pr view --json autoMergeRequest,mergeCommit` output.
  * `autoMergeRequest` is `null` when auto-merge is NOT armed; a non-null
@@ -172,9 +233,17 @@ export class AutomergeArmer {
   /**
    * @param {object} opts
    * @param {object} opts.bus
+   * @param {number} [opts.epicId] Epic id — required for the headless
+   *   `merge.unlanded` attribution on a genuine arm failure (Story #4472).
+   * @param {boolean} [opts.headless] When true (a `/deliver --yes` run), a
+   *   genuine (non-fallback) arm failure escalates to an explicit
+   *   `merge.unlanded` + `epic.blocked` terminal instead of returning
+   *   silently (Story #4472). Defaults to `false` (attended).
    * @param {string} [opts.cwd]
    * @param {Function} [opts.ghPrViewAutoMergeFn] override for tests.
    * @param {Function} [opts.ghPrMergeAutoFn] override for tests.
+   * @param {Function} [opts.ghPrMergeDirectFn] override for tests.
+   * @param {Function} [opts.emitMergeUnlandedFn] override for tests.
    * @param {{ info?: Function, warn?: Function, debug?: Function }} [opts.logger]
    */
   constructor(opts = {}) {
@@ -186,9 +255,13 @@ export class AutomergeArmer {
       throw new TypeError('AutomergeArmer requires a bus with on() and emit()');
     }
     this.bus = opts.bus;
+    this.epicId = Number.isInteger(opts.epicId) ? opts.epicId : null;
+    this.headless = opts.headless === true;
     this.cwd = opts.cwd ?? process.cwd();
     this.ghPrViewAutoMergeFn = opts.ghPrViewAutoMergeFn ?? ghPrViewAutoMerge;
     this.ghPrMergeAutoFn = opts.ghPrMergeAutoFn ?? ghPrMergeAuto;
+    this.ghPrMergeDirectFn = opts.ghPrMergeDirectFn ?? ghPrMergeDirect;
+    this.emitMergeUnlandedFn = opts.emitMergeUnlandedFn ?? emitMergeUnlanded;
     this.logger = opts.logger ?? console;
     /** @type {Set<string>} `${event}:${seqId}` idempotency cache. */
     this._seen = new Set();
@@ -293,16 +366,26 @@ export class AutomergeArmer {
         await this._emitArmed(prUrl);
         return;
       }
-      this.classifications.push({
+
+      // Story #4472 — native auto-merge is unavailable on this repository
+      // (no branch protection / "Allow auto-merge" disabled). The predicate
+      // already cleared the merge, so fall back to a direct immediate
+      // squash-merge instead of stranding a landable PR on the
+      // operator-merges path.
+      if (isAutoMergeUnavailable(arm.stderr)) {
+        const armed = await this._tryDirectMerge({ event, seqId, prUrl, arm });
+        if (armed) return;
+      }
+
+      // Genuine arm failure (auth, conflict, an unresolved direct-merge
+      // fallback, …). Classify + escalate.
+      await this._emitArmFailure({
         event,
         seqId,
-        outcome: 'failed',
+        prUrl,
         reason: `arm-failed:status=${arm.status}`,
         ghStderr: arm.stderr,
       });
-      this.logger.warn?.(
-        `[AutomergeArmer] gh pr merge --auto failed (status=${arm.status}): ${arm.stderr}`,
-      );
       return;
     }
 
@@ -320,6 +403,97 @@ export class AutomergeArmer {
     }
   }
 
+  /**
+   * Story #4472 — direct-merge fallback when native auto-merge is
+   * unavailable. Runs an immediate `gh pr merge --squash --delete-branch`
+   * (no `--auto`) then re-probes; on a confirmed merge (or the same
+   * post-merge `--delete-branch` housekeeping grumble the `--auto` path
+   * already tolerates) it emits `epic.merge.armed` so the
+   * MergeWatcher → Cleaner → LabelTransitioner chain engages and confirms
+   * the merge on its first poll.
+   *
+   * @returns {Promise<boolean>} `true` when the fallback landed the PR (an
+   *   `epic.merge.armed` was emitted); `false` when the direct merge did
+   *   not land, so the caller escalates the original arm failure.
+   */
+  async _tryDirectMerge({ event, seqId, prUrl, arm }) {
+    this.logger.info?.(
+      `[AutomergeArmer] native auto-merge unavailable (${arm.stderr?.trim?.() ?? arm.stderr}); falling back to a direct squash-merge on ${prUrl}.`,
+    );
+    const direct = this.ghPrMergeDirectFn({ prUrl, cwd: this.cwd });
+    const recheck = this.ghPrViewAutoMergeFn({ prUrl, cwd: this.cwd });
+    const merged =
+      recheck.status === 0 &&
+      (parsePrMerged(recheck.stdout) || parseAutoMergeArmed(recheck.stdout));
+    if (direct.status === 0 || merged) {
+      this.classifications.push({
+        event,
+        seqId,
+        outcome: 'armed',
+        prUrl,
+        note: `direct-merge fallback (native auto-merge unavailable); direct exit ${direct.status}${direct.status !== 0 ? ` but re-probe shows merged/armed (housekeeping stderr: ${direct.stderr})` : ''}`,
+      });
+      await this._emitArmed(prUrl);
+      return true;
+    }
+    this.logger.warn?.(
+      `[AutomergeArmer] direct-merge fallback failed (status=${direct.status}): ${direct.stderr}`,
+    );
+    return false;
+  }
+
+  /**
+   * Classify + (in headless) escalate a genuine arm failure. The `--auto`
+   * path historically returned silently here; a `/deliver --yes` run has no
+   * operator to notice, so we mirror the MergeWatcher's terminal:
+   * `merge.unlanded` ledger attribution + an explicit `epic.blocked`
+   * transition. Attended runs keep the classify-and-return behaviour.
+   */
+  async _emitArmFailure({ event, seqId, prUrl, reason, ghStderr }) {
+    this.classifications.push({
+      event,
+      seqId,
+      outcome: 'failed',
+      reason,
+      ghStderr,
+    });
+    this.logger.warn?.(
+      `[AutomergeArmer] gh pr merge --auto failed (${reason}): ${ghStderr}`,
+    );
+    if (!this.headless) return;
+    const classification = classifyMergeBlock({
+      armResult: { armed: false, reason: ghStderr },
+    });
+    const prNumber = parsePrNumberFromUrl(prUrl);
+    if (
+      Number.isInteger(this.epicId) &&
+      Number.isInteger(prNumber) &&
+      prNumber > 0
+    ) {
+      try {
+        this.emitMergeUnlandedFn({
+          scope: 'epic',
+          ticketId: this.epicId,
+          prNumber,
+          blockClass: classification.blockClass,
+          reason: classification.reason,
+          elapsedSeconds: 0,
+        });
+      } catch (err) {
+        this.logger.warn?.(
+          `[AutomergeArmer] emitMergeUnlanded failed (swallowed): ${err?.message ?? err}`,
+        );
+      }
+    }
+    try {
+      await this.bus.emit('epic.blocked', { reason: `merge-arm:failed` });
+    } catch (err) {
+      this.logger.warn?.(
+        `[AutomergeArmer] epic.blocked emit on arm failure failed (swallowed): ${err?.message ?? err}`,
+      );
+    }
+  }
+
   reset() {
     this._seen.clear();
     this.classifications = [];

package/.agents/scripts/lib/orchestration/lifecycle/listeners/automerge-predicate.js

@@ -68,8 +68,10 @@ import { spawnSync } from 'node:child_process';
 
 import { hasSurvivingCritical } from '../../../audit-suite/findings.js';
 import { getCiDelivery } from '../../../config/ci.js';
+import { parsePrNumberFromUrl } from '../../../github-url.js';
 import * as epicRunStateStore from '../../epic-run-state-store.js';
 import { findStructuredComment } from '../../ticketing.js';
+import { emitMergeUnlanded } from '../emit-merge-unlanded.js';
 import { normalizeCheckState, RECOGNIZED_CHECK_STATES } from './watcher.js';
 
 /**
@@ -224,19 +226,51 @@ export function probeRequiredChecks({ prUrl, cwd, spawnFn = spawnSync }) {
  * stdout. We parse stdout first (it is populated even on the non-zero
  * exit) and classify from the outcomes.
  *
+ * Story #4472 — checks-less repos. In a repo with zero required checks
+ * (no branch protection, or protection that requires no status checks),
+ * `gh pr checks --required` writes NOTHING to stdout and reports
+ * `no checks reported on the <branch> branch` to stderr with a non-zero
+ * exit. That is the SAME empty-parsed-set condition the outcomes loop
+ * below already treats as green — there is simply nothing to gate on — so
+ * we must not conflate it with a genuine probe failure (auth, network, no
+ * PR). We detect the `no checks reported` stderr signature and return
+ * green, UNLESS the consumer opted into `delivery.ci.requireChecks`, in
+ * which case the absent CI gate is a deliberate hard block.
+ *
  * @param {{ status: number, stdout: string, stderr: string }} probe
+ * @param {{ requireChecks?: boolean }} [opts] When `requireChecks` is
+ *   true, a checks-less repo fails closed instead of arming.
  * @returns {{ ok: boolean, reason: string|null, outcomes: Record<string, string> }}
  */
-export function classifyRequiredChecksProbe(probe) {
+export function classifyRequiredChecksProbe(
+  probe,
+  { requireChecks = false } = {},
+) {
   const stdout = String(probe?.stdout ?? '').trim();
-  // Empty stdout with a non-zero status → probe genuinely failed (auth,
-  // network, no PR). Fail closed.
+  const stderr = String(probe?.stderr ?? '').trim();
+  // Empty stdout: either a checks-less repo (green, nothing to gate on) or
+  // a genuine probe failure. The `no checks reported` stderr signature
+  // distinguishes them.
   if (stdout.length === 0) {
+    const noChecksReported = /no checks reported/i.test(stderr);
+    if (noChecksReported && !requireChecks) {
+      // Zero required checks configured — matches the empty-parsed-set
+      // "treated as green" branch below. Nothing to gate on.
+      return { ok: true, reason: null, outcomes: {} };
+    }
+    if (noChecksReported && requireChecks) {
+      return {
+        ok: false,
+        reason:
+          'no required checks reported and delivery.ci.requireChecks is set — failing closed per policy',
+        outcomes: {},
+      };
+    }
     return {
       ok: false,
       reason:
         `live required-check probe failed (status=${probe?.status ?? 'unknown'})` +
-        (probe?.stderr ? `: ${String(probe.stderr).trim().slice(0, 200)}` : ''),
+        (stderr ? `: ${stderr.slice(0, 200)}` : ''),
       outcomes: {},
     };
   }
@@ -678,8 +712,13 @@ export class AutomergePredicate {
    *   evaluator). Required for the read of run-state + structured
    *   comments.
    * @param {object} [opts.config] Resolved agent config. Read for the
-   *   `delivery.ci.autoMerge` policy via `getCiDelivery`. Defaults to the
-   *   framework default (`trust-ci`) when omitted.
+   *   `delivery.ci.autoMerge` policy and the `delivery.ci.requireChecks`
+   *   fail-closed-without-checks policy via `getCiDelivery`. Defaults to the
+   *   framework defaults (`trust-ci` / `requireChecks: false`) when omitted.
+   * @param {boolean} [opts.headless] When true (a `/deliver --yes` run), a
+   *   predicate refusal escalates to an explicit `merge.unlanded` +
+   *   `epic.blocked` terminal instead of silently parking on the
+   *   operator-merges path (Story #4472). Defaults to `false` (attended).
    * @param {string} [opts.cwd] Working directory for the live
    *   `gh pr checks --required` probe. Defaults to `process.cwd()`.
    * @param {Function} [opts.evaluatePredicateFn] override of
@@ -708,13 +747,20 @@ export class AutomergePredicate {
     this.epicId = opts.epicId;
     this.provider = opts.provider;
     this.cwd = opts.cwd ?? process.cwd();
-    // Resolve the merge posture once at construction. `getCiDelivery`
-    // applies the framework default (`trust-ci`) for any omitted field.
-    this.policy = getCiDelivery(opts.config ?? null).autoMerge;
+    // Resolve the merge posture + fail-closed policy once at construction.
+    // `getCiDelivery` applies the framework defaults (`trust-ci` /
+    // `requireChecks: false`) for any omitted field.
+    const ci = getCiDelivery(opts.config ?? null);
+    this.policy = ci.autoMerge;
+    this.requireChecks = ci.requireChecks;
+    this.headless = opts.headless === true;
     this.evaluatePredicateFn =
       opts.evaluatePredicateFn ?? evaluateAutoMergePredicate;
     this.probeRequiredChecksFn =
       opts.probeRequiredChecksFn ?? probeRequiredChecks;
+    // Injected for tests so the headless terminal escalation can be
+    // observed without touching disk.
+    this.emitMergeUnlandedFn = opts.emitMergeUnlandedFn ?? emitMergeUnlanded;
     this.logger = opts.logger ?? console;
     /** @type {Set<string>} `${event}:${seqId}` idempotency cache. */
     this._seen = new Set();
@@ -786,7 +832,9 @@ export class AutomergePredicate {
       let probeVerdict;
       try {
         const probe = this.probeRequiredChecksFn({ prUrl, cwd: this.cwd });
-        probeVerdict = classifyRequiredChecksProbe(probe);
+        probeVerdict = classifyRequiredChecksProbe(probe, {
+          requireChecks: this.requireChecks,
+        });
       } catch (err) {
         probeVerdict = {
           ok: false,
@@ -878,6 +926,17 @@ export class AutomergePredicate {
    * Emit `epic.merge.blocked`. Helper carved out so the blocking paths
    * (CI failure / predicate dirty / evaluator throw) share the same emit
    * shape.
+   *
+   * Story #4472 — must-land coverage of predicate refusal. In a headless
+   * (`/deliver --yes`) run there is no operator to act on a bare
+   * `epic.merge.blocked` (nothing in the listener chain consumes it), so
+   * the run would silently park on the operator-merges path. When
+   * `this.headless`, we additionally attribute the refusal to the
+   * lifecycle ledger via `merge.unlanded` (blockClass `predicate-refused`)
+   * and drive the explicit `epic.blocked` terminal — the same
+   * escalation the MergeWatcher performs on post-arm budget exhaustion —
+   * so the Epic transitions to `agent::blocked` with an operator-visible
+   * reason instead of stalling.
    */
   async _emitBlocked(prUrl, reason) {
     try {
@@ -887,6 +946,35 @@ export class AutomergePredicate {
         `[AutomergePredicate] epic.merge.blocked emit failed (swallowed): ${err?.message ?? err}`,
       );
     }
+    if (!this.headless) return;
+    // Ledger attribution — best-effort; a failed append must NOT mask the
+    // epic.blocked transition below.
+    try {
+      const prNumber = parsePrNumberFromUrl(prUrl);
+      if (Number.isInteger(prNumber) && prNumber > 0) {
+        this.emitMergeUnlandedFn({
+          scope: 'epic',
+          ticketId: this.epicId,
+          prNumber,
+          blockClass: 'predicate-refused',
+          reason,
+          elapsedSeconds: 0,
+        });
+      }
+    } catch (err) {
+      this.logger.warn?.(
+        `[AutomergePredicate] emitMergeUnlanded failed (swallowed): ${err?.message ?? err}`,
+      );
+    }
+    try {
+      await this.bus.emit('epic.blocked', {
+        reason: `merge-predicate:refused`,
+      });
+    } catch (err) {
+      this.logger.warn?.(
+        `[AutomergePredicate] epic.blocked emit on predicate refusal failed (swallowed): ${err?.message ?? err}`,
+      );
+    }
   }
 
   reset() {

package/.agents/scripts/lib/orchestration/lifecycle/listeners/index.js

@@ -226,10 +226,15 @@ export async function buildDefaultListenerChain(opts = {}) {
   order.push('Finalizer');
 
   // 4. AutomergeArmer — arms `gh pr merge --auto --squash --delete-branch`
-  //    on epic.merge.ready.
+  //    on epic.merge.ready. Story #4472: `headless` gates the direct-merge
+  //    fallback's terminal escalation (a genuine arm failure emits
+  //    `merge.unlanded` + `epic.blocked` in a `--yes` run instead of
+  //    returning silently); `epicId` scopes the `merge.unlanded` ledger row.
   const automergeArmer = new AutomergeArmer({
     bus,
+    epicId,
     cwd: repoRoot,
+    headless,
     logger,
   });
   automergeArmer.register();
@@ -250,6 +255,7 @@ export async function buildDefaultListenerChain(opts = {}) {
       provider,
       config,
       cwd: repoRoot,
+      headless,
       logger,
     });
     automergePredicate.register();

package/.agents/scripts/lib/orchestration/merge-block-class.js

@@ -10,7 +10,7 @@
  * one of four classes from the SAME decision logic, instead of each path
  * inventing its own ad hoc diagnosis.
  *
- * Block classes (Epic #4425 Goal):
+ * Block classes (Epic #4425 Goal; `predicate-refused` added by #4472):
  *   - `checks-pending-timeout`           The watch/poll budget was
  *                                         exhausted while required checks
  *                                         were still pending/running — not
@@ -33,6 +33,18 @@
  *                                         a transient GraphQL/API error, an
  *                                         ambiguous probe result, or a
  *                                         genuinely novel condition.
+ *   - `predicate-refused`                The AutomergePredicate refused to
+ *                                         arm merge BEFORE any arm attempt —
+ *                                         a red/pending required check, an
+ *                                         unreadable check probe, a dirty
+ *                                         structured-signal verdict, or a
+ *                                         `delivery.ci.requireChecks` policy
+ *                                         block on a checks-less repo (#4472).
+ *                                         The must-land contract previously
+ *                                         only covered post-arm poll
+ *                                         exhaustion, so a predicate refusal
+ *                                         in headless mode silently parked;
+ *                                         this class makes it attributable.
  *
  * Pure function, no I/O: callers pass in the already-observed
  * arm-result / PR-probe / budget signals (from `AutomergeArmer`,
@@ -55,12 +67,28 @@ export const BLOCK_CLASSES = Object.freeze([
   'api-race-other',
 ]);
 
-const BLOCK_CLASS_SET = new Set(BLOCK_CLASSES);
+/**
+ * The full set of block-class values a `merge.unlanded` record may carry.
+ * This is the classifier's four outputs PLUS `predicate-refused` (#4472),
+ * which is emitted DIRECTLY by the AutomergePredicate / AutomergeArmer for a
+ * headless refusal that never reached the poll-exhaustion classifier — so it
+ * is a valid attribution value even though `classifyMergeBlock` never
+ * produces it. `isValidBlockClass` (and the `merge.unlanded` schema enum)
+ * validate against this broader set; the classifier's own reachability
+ * invariant stays scoped to `BLOCK_CLASSES`.
+ */
+export const MERGE_UNLANDED_BLOCK_CLASSES = Object.freeze([
+  ...BLOCK_CLASSES,
+  'predicate-refused',
+]);
+
+const BLOCK_CLASS_SET = new Set(MERGE_UNLANDED_BLOCK_CLASSES);
 
 /**
  * @param {string} value
- * @returns {boolean} `true` iff `value` is one of the four canonical
- *   block classes.
+ * @returns {boolean} `true` iff `value` is a valid `merge.unlanded`
+ *   block-class attribution (the four classifier outputs plus the directly-
+ *   emitted `predicate-refused`).
  */
 export function isValidBlockClass(value) {
   return BLOCK_CLASS_SET.has(value);

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

@@ -125,7 +125,11 @@ export async function runCloseValidationPhase({
   const validation = await runCloseValidation({
     cwd,
     worktreePath,
-    gates: buildDefaultGates({ config, epicBranch: baseBranch }),
+    gates: buildDefaultGates({
+      config,
+      epicBranch: baseBranch,
+      cwd: worktreePath || cwd,
+    }),
     log: (m) => Logger.info(m),
     storyId,
     // Story #4250 — standalone storyId-anchored evidence keyspace. No

package/.agents/scripts/lib/orchestration/story-close/pre-merge-validation.js

@@ -133,7 +133,14 @@ export async function runPreMergeGates({
   // `buildDefaultGates` reads the canonical resolved config directly:
   // gate commands resolve from `project.commands` and the CRAP toggle
   // from `delivery.quality.gates.crap.enabled`.
-  const gates = buildDefaultGates({ config, epicBranch });
+  // Probe the coverage script from the gate execution directory (the Story
+  // worktree when present) so coverage-capture is only registered when the
+  // consumer ships `test:coverage` (#4473).
+  const gates = buildDefaultGates({
+    config,
+    epicBranch,
+    cwd: worktreePath || cwd,
+  });
   const gateCount = Array.isArray(gates) ? gates.length : 0;
   // Story #2250 — emit `close-validate.start` only when both an epicId
   // and a storyId are present; the schema requires both, and unit

package/docs/CHANGELOG.md

@@ -2,6 +2,13 @@
 
 All notable changes to this project will be documented in this file.
 
+## [1.90.0](https://github.com/dsj1984/mandrel/compare/mandrel-v1.89.0...mandrel-v1.90.0) (2026-07-12)
+
+
+### Fixed
+
+* **delivery:** land headless PRs in checks-less repos + degrade coverage gate without test:coverage ([#4480](https://github.com/dsj1984/mandrel/issues/4480)) ([9836f1e](https://github.com/dsj1984/mandrel/commit/9836f1ec9beb4b2798bd72e869214e5705296522)), closes [#4472](https://github.com/dsj1984/mandrel/issues/4472) [#4473](https://github.com/dsj1984/mandrel/issues/4473)
+
 ## [1.89.0](https://github.com/dsj1984/mandrel/compare/mandrel-v1.88.0...mandrel-v1.89.0) (2026-07-11)
 
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mandrel",
-  "version": "1.89.0",
+  "version": "1.90.0",
   "description": "Claude Code-first opinionated workflow framework: instructions, personas, skills, and SDLC workflows that govern AI coding assistants.",
   "files": [
     ".agents/",