mandrel 1.89.0 → 1.91.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/epic-deliver-preflight.js

@@ -11,7 +11,12 @@
  *      `storyCount`, `installCostSeconds`, `dependencyDepth`,
  *      `githubApiRequests`, `claudeQuotaTokens`, plus `breaches`
  *      (the non-empty subset of `delivery.preflight.max*` thresholds the
- *      estimate exceeds).
+ *      estimate exceeds), plus `remoteVerified` / `remoteProbe` — the
+ *      issue #4483 deterministic remote evidence (`git remote get-url
+ *      origin` + bounded `git ls-remote origin HEAD`). On
+ *      `remoteVerified: false` the workflow MUST flip the Epic to
+ *      `agent::blocked` quoting `remoteProbe.detail` — inline delivery to
+ *      local `main` is never a sanctioned fallback.
  *   2. When `--post` is set (and `--dry-run` is not), an upserted
  *      `delivery-preflight` structured comment on the Epic ticket so
  *      reviewers reading the Epic discover the same numbers without
@@ -66,6 +71,7 @@ import {
   computeBaseSha,
   writePreflightCache,
 } from './lib/orchestration/preflight-cache.js';
+import { verifyRemote } from './lib/orchestration/remote-verifier.js';
 import { upsertStructuredComment } from './lib/orchestration/ticketing.js';
 import { createProvider } from './lib/provider-factory.js';
 
@@ -218,10 +224,23 @@ export function renderPreflightBody({
   estimate,
   breaches,
   thresholds,
+  remote,
 }) {
   const lines = [];
   lines.push(`### 🛫 Delivery preflight — Epic #${epicId}`);
   lines.push('');
+  // Issue #4483 — verified remote evidence at entry. Rendered before the
+  // metric table so a reviewer (and the orchestrating agent) sees the
+  // land-or-block fact first. Omitted when the caller has no probe result
+  // (legacy callers / tests that only exercise the estimate math).
+  if (remote) {
+    lines.push(
+      remote.remoteVerified
+        ? `✅ **remoteVerified: true** — ${remote.detail}`
+        : `⛔ **remoteVerified: false** — ${remote.detail} — \`/deliver\` MUST transition the Epic to \`agent::blocked\` quoting this probe; inline delivery to local \`main\` is forbidden.`,
+    );
+    lines.push('');
+  }
   lines.push('| Metric | Estimate | Threshold |');
   lines.push('| --- | ---: | ---: |');
   const rows = [
@@ -276,6 +295,7 @@ export function renderPreflightBody({
  *   perStoryClaudeTokens?: number,
  *   injectedProvider?: object,
  *   injectedConfig?: object,
+ *   verifyRemoteFn?: typeof verifyRemote,
  * }} args
  */
 export async function runPreflight({
@@ -288,6 +308,7 @@ export async function runPreflight({
   perStoryClaudeTokens,
   injectedProvider,
   injectedConfig,
+  verifyRemoteFn = verifyRemote,
 }) {
   if (!Number.isInteger(epicId) || epicId <= 0) {
     throw new TypeError('runPreflight: --epic must be a positive integer');
@@ -297,6 +318,13 @@ export async function runPreflight({
   const provider = injectedProvider ?? createProvider(config);
   const thresholds = getPreflight(config);
 
+  // Issue #4483 — deterministic remote evidence at entry. Probe BEFORE any
+  // provider work so the envelope always carries verified fact (not the
+  // agent's perception) about whether a live, pushable `origin` exists.
+  // The CLI records; the `/deliver` workflow owns the `agent::blocked`
+  // transition on `remoteVerified: false` (same split as breach handling).
+  const remote = verifyRemoteFn({ cwd });
+
   // Compose the same two phases /deliver Phase 1 runs so the
   // preflight numbers match the actual dispatch plan.
   const ctx = { epicId, provider };
@@ -348,6 +376,13 @@ export async function runPreflight({
     thresholds,
     baseSha,
     cacheWritten,
+    // Issue #4483 — verified remote evidence. `remoteVerified: false`
+    // REQUIRES the workflow to block explicitly (never build inline).
+    remoteVerified: remote.remoteVerified,
+    remoteProbe: {
+      remoteUrl: remote.remoteUrl,
+      detail: remote.detail,
+    },
   };
 
   if (post && !dryRun) {
@@ -356,6 +391,7 @@ export async function runPreflight({
       estimate,
       breaches,
       thresholds,
+      remote,
     });
     await upsertStructuredComment(provider, epicId, 'delivery-preflight', body);
     envelope.commentUpserted = true;

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