mandrel 1.89.0 → 1.91.0

package/.agents/scripts/lib/orchestration/remote-verifier.js

@@ -0,0 +1,165 @@
+// .agents/scripts/lib/orchestration/remote-verifier.js
+/**
+ * remote-verifier.js — deterministic "is there a live, pushable remote?"
+ * evidence for the delivery entry seams. Issue #4483.
+ *
+ * `/deliver` could silently shortcut the entire orchestration — building
+ * the delivery inline and committing to local `main` without pushing —
+ * when the driving agent *perceived* the environment had no live GitHub
+ * remote. The judgment was vibes, not fact. This module gives the entry
+ * seams (`epic-deliver-preflight.js`, `single-story-init.js`) a verified
+ * probe result to record in their envelopes so the workflow can branch on
+ * `remoteVerified: true|false` deterministically: use the remote, or
+ * transition to `agent::blocked` quoting the probe output — never a
+ * silent local build.
+ *
+ * Two probes, both bounded (a hung git spawn must not park the entry
+ * seam — mirrors the `ghPrListHead` timeout contract in `finalizer.js`):
+ *
+ *   1. `git remote get-url origin`  — is an `origin` remote configured?
+ *   2. `git ls-remote origin HEAD`  — is it reachable with current auth?
+ *
+ * `remoteVerified` is true only when BOTH succeed. The CLI callers do
+ * NOT flip labels on a false result — the workflow owns the
+ * `agent::blocked` transition (same division of labour as the preflight
+ * breach handling).
+ */
+
+import { spawnSync } from 'node:child_process';
+
+/**
+ * Bounded timeout for each git probe. `ls-remote` is a network call;
+ * SIGKILL at the bound so an unreachable or hanging remote degrades to a
+ * deterministic `remoteVerified: false` instead of a stuck entry seam.
+ */
+export const REMOTE_PROBE_TIMEOUT_MS = 30_000;
+
+function runProbe({ args, cwd, spawnFn, timeoutMs }) {
+  const result = spawnFn('git', args, {
+    cwd,
+    encoding: 'utf-8',
+    shell: false,
+    timeout: timeoutMs,
+    killSignal: 'SIGKILL',
+  });
+  return {
+    args: ['git', ...args].join(' '),
+    status: result.status ?? 1,
+    stdout: (result.stdout ?? '').trim(),
+    stderr: (result.stderr ?? '').trim(),
+  };
+}
+
+/**
+ * Probe the `origin` remote for existence + reachability.
+ *
+ * @param {{
+ *   cwd?: string,
+ *   spawnFn?: typeof spawnSync,
+ *   timeoutMs?: number,
+ * }} [opts]
+ * @returns {{
+ *   remoteVerified: boolean,
+ *   remoteUrl: string|null,
+ *   detail: string,
+ *   probes: {
+ *     getUrl: { args: string, status: number, stdout: string, stderr: string },
+ *     lsRemote: { args: string, status: number, stdout: string, stderr: string }|null,
+ *   },
+ * }}
+ */
+export function verifyRemote({
+  cwd = process.cwd(),
+  spawnFn = spawnSync,
+  timeoutMs = REMOTE_PROBE_TIMEOUT_MS,
+} = {}) {
+  const getUrl = runProbe({
+    args: ['remote', 'get-url', 'origin'],
+    cwd,
+    spawnFn,
+    timeoutMs,
+  });
+  if (getUrl.status !== 0) {
+    return {
+      remoteVerified: false,
+      remoteUrl: null,
+      detail: `no 'origin' remote configured — \`${getUrl.args}\` exited ${getUrl.status}: ${getUrl.stderr || '(no stderr)'}`,
+      probes: { getUrl, lsRemote: null },
+    };
+  }
+  const remoteUrl = getUrl.stdout;
+
+  const lsRemote = runProbe({
+    args: ['ls-remote', 'origin', 'HEAD'],
+    cwd,
+    spawnFn,
+    timeoutMs,
+  });
+  if (lsRemote.status !== 0 || lsRemote.stdout.length === 0) {
+    return {
+      remoteVerified: false,
+      remoteUrl,
+      detail: `'origin' (${remoteUrl}) is unreachable — \`${lsRemote.args}\` exited ${lsRemote.status}: ${lsRemote.stderr || '(empty ls-remote output)'}`,
+      probes: { getUrl, lsRemote },
+    };
+  }
+
+  return {
+    remoteVerified: true,
+    remoteUrl,
+    detail: `origin verified (${remoteUrl}); ls-remote HEAD → ${lsRemote.stdout.split(/\s+/)[0]}`,
+    probes: { getUrl, lsRemote },
+  };
+}
+
+/**
+ * Probe whether a specific branch exists on `origin` — the deterministic
+ * finalize backstop (issue #4483 fix direction 3): a delivery branch that
+ * was never pushed MUST fail finalize with an explicit blocker rather
+ * than let the run declare success.
+ *
+ * Distinct from `git-branch-lifecycle.js#branchExistsRemotely` in two
+ * load-bearing ways: the spawn is bounded (timeout + SIGKILL, so a hung
+ * remote cannot park the finalize seam) and the result carries the probe
+ * detail for the blocker envelope instead of a bare boolean.
+ *
+ * @param {{
+ *   branch: string,
+ *   cwd?: string,
+ *   spawnFn?: typeof spawnSync,
+ *   timeoutMs?: number,
+ * }} opts
+ * @returns {{ exists: boolean, detail: string }}
+ */
+export function probeRemoteBranch({
+  branch,
+  cwd = process.cwd(),
+  spawnFn = spawnSync,
+  timeoutMs = REMOTE_PROBE_TIMEOUT_MS,
+}) {
+  if (typeof branch !== 'string' || branch.length === 0) {
+    throw new TypeError('probeRemoteBranch: branch must be a non-empty string');
+  }
+  const probe = runProbe({
+    args: ['ls-remote', '--heads', 'origin', branch],
+    cwd,
+    spawnFn,
+    timeoutMs,
+  });
+  if (probe.status !== 0) {
+    return {
+      exists: false,
+      detail: `\`${probe.args}\` exited ${probe.status}: ${probe.stderr || '(no stderr)'}`,
+    };
+  }
+  if (probe.stdout.length === 0) {
+    return {
+      exists: false,
+      detail: `\`${probe.args}\` found no ref — ${branch} was never pushed to origin`,
+    };
+  }
+  return {
+    exists: true,
+    detail: `${branch} on origin at ${probe.stdout.split(/\s+/)[0]}`,
+  };
+}

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/single-story-close/phases/push.js

@@ -5,6 +5,16 @@
  * subsequent fetches are cheap. A push failure raises so the caller
  * fails non-zero — the operator must resolve before retrying.
  *
+ * Issue #4483 — this phase IS the standalone path's deterministic
+ * land-or-block backstop (the counterpart to the Epic finalize seam's
+ * `delivery-branch-missing-on-origin` blocker). `git push` exits 0 only
+ * after origin has accepted the ref, so the throw below is the origin
+ * assertion: every later close phase (PR open, auto-merge, the
+ * `closeResult` success envelope) is unreachable unless the Story branch
+ * verifiably landed on origin. No post-push `ls-remote` re-probe is
+ * added because it would re-ask a question the push exit code already
+ * answered authoritatively.
+ *
  * `gitSync` is accepted as an injected dependency rather than statically
  * imported so the caller's (cache-busted) binding wins. The
  * `single-story-close.js` orchestrator owns the static import; test

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/.agents/scripts/single-story-init.js

@@ -59,6 +59,7 @@ import {
   executeFastForward,
   planFastForward,
 } from './lib/orchestration/git-cleanup/phases/fast-forward.js';
+import { verifyRemote } from './lib/orchestration/remote-verifier.js';
 import { acquireStoryLease } from './lib/orchestration/single-story-lease-guard.js';
 import {
   STATE_LABELS,
@@ -446,6 +447,7 @@ export async function runSingleStoryInit({
   injectedAcquireLease,
   steal = false,
   leaseNow,
+  injectedVerifyRemote,
 } = {}) {
   const parsed =
     storyIdParam !== undefined
@@ -487,6 +489,20 @@ export async function runSingleStoryInit({
   );
   progress('INIT', `Initializing standalone Story #${storyId}...`);
 
+  // Issue #4483 — deterministic remote evidence at the standalone entry
+  // seam (the counterpart to `epic-deliver-preflight.js`'s probe). The
+  // probe is read-only, so it runs under --dry-run too. The CLI records
+  // the fact; the workflow owns the `agent::blocked` transition on
+  // `remoteVerified: false` — inline delivery to local `main` is never a
+  // sanctioned fallback.
+  const remote = (injectedVerifyRemote ?? verifyRemote)({ cwd });
+  progress(
+    'REMOTE',
+    remote.remoteVerified
+      ? `✅ remoteVerified=true — ${remote.detail}`
+      : `⛔ remoteVerified=false — ${remote.detail}`,
+  );
+
   const story = await provider.getTicket(storyId);
   assertDeliverableStory(story, storyId);
 
@@ -563,6 +579,9 @@ export async function runSingleStoryInit({
     dependenciesInstalled,
     installFailed: installStatus.status === 'failed',
     dryRun,
+    // Issue #4483 — verified remote evidence for the orchestrating agent.
+    remoteVerified: remote.remoteVerified,
+    remoteProbe: { remoteUrl: remote.remoteUrl, detail: remote.detail },
   };
 
   // Upsert the `story-init` structured comment + flip Story to executing.
@@ -632,6 +651,8 @@ export function renderSingleStoryInitComment(result) {
     worktreeCreated: result.worktreeCreated,
     dependenciesInstalled: result.dependenciesInstalled,
     installStatus: result.installStatus,
+    remoteVerified: result.remoteVerified,
+    remoteProbe: result.remoteProbe,
   };
   return [
     '## Story init (standalone)',
@@ -641,6 +662,7 @@ export function renderSingleStoryInitComment(result) {
     `- **baseBranch:** \`${result.baseBranch}\``,
     `- **workCwd:** \`${result.workCwd}\``,
     `- **worktreeEnabled:** \`${result.worktreeEnabled}\``,
+    `- **remoteVerified:** \`${result.remoteVerified}\``,
     `- **dependenciesInstalled:** \`${result.dependenciesInstalled}\``,
     '',
     '```json',

package/.agents/workflows/deliver.md

@@ -131,6 +131,14 @@ the standalone segment; segments themselves remain strictly sequential.
 
 ## Constraints
 
+- **Land or block — never a silent local build (issue #4483).** The
+  helpers' orchestration path (worktrees, `story-<id>`/`epic/<id>` branches,
+  close-validation, PR) is the ONLY sanctioned delivery mechanism.
+  Executing story slices inline in this session and/or committing the
+  delivery to local `main` is expressly forbidden, regardless of how the
+  environment looks. Each path surfaces verified remote evidence
+  (`remoteVerified`) at entry; on `false`, transition the ticket to
+  `agent::blocked` quoting `remoteProbe.detail` and halt.
 - `/deliver` requires planned tickets: Epics at `agent::ready` (the
   Epic helper's preflight enforces this, per segment) or well-formed
   standalone Stories. Planning happens in [`/plan`](plan.md); the

package/.agents/workflows/helpers/deliver-epic.md

@@ -181,6 +181,17 @@ Threshold defaults live in `delivery.preflight.*` in `.agentrc.json`
 (all keys default to "no cap" — the gate is opt-in until an operator
 configures `maxStories` etc.).
 
+**Remote evidence — land or block (issue #4483).** The envelope also
+carries `remoteVerified` + `remoteProbe` (deterministic probes:
+`git remote get-url origin`, bounded `git ls-remote origin HEAD`). When
+`remoteVerified` is `false`, flip the Epic to `agent::blocked`, post a
+friction comment quoting `remoteProbe.detail`, and halt — the same
+explicit-block shape as #4425/#4480. NEVER fall back to executing Stories
+inline in this session or committing the delivery to local `main`; the
+worktree/branch/PR path below is the only sanctioned mechanism. Phase 7's
+finalize additionally refuses with a `delivery-branch-missing-on-origin`
+blocker when `epic/<epicId>` never reached origin.
+
 ### Phase 1 main — Seed the wave plan
 
 ```bash

package/.agents/workflows/helpers/single-story-deliver.md

@@ -97,6 +97,14 @@ Capture `workCwd` from the result envelope. Add `--dry-run` to inspect
 the planned actions without git or ticket mutations (dry-run also skips
 the lease and the sweep).
 
+**Remote evidence — land or block (issue #4483).** The envelope also
+carries `remoteVerified` + `remoteProbe` (`git remote get-url origin` +
+bounded `git ls-remote origin HEAD`). When `remoteVerified` is `false`,
+transition the Story to `agent::blocked` quoting `remoteProbe.detail` and
+stop. Implementing the Story inline outside the worktree/branch/PR path
+and/or committing it to local `main` is expressly forbidden — the close
+pipeline's push is the only sanctioned landing.
+
 ### Step 0.5 — `cd` into the workCwd
 
 ```bash

package/docs/CHANGELOG.md

@@ -2,6 +2,20 @@
 
 All notable changes to this project will be documented in this file.
 
+## [1.91.0](https://github.com/dsj1984/mandrel/compare/mandrel-v1.90.0...mandrel-v1.91.0) (2026-07-12)
+
+
+### Fixed
+
+* **deliver:** verify the remote at entry and assert the delivery branch on origin (refs [#4483](https://github.com/dsj1984/mandrel/issues/4483)) ([#4484](https://github.com/dsj1984/mandrel/issues/4484)) ([a99ca2f](https://github.com/dsj1984/mandrel/commit/a99ca2fc4c74f7c397041dc4c703d845fae640c2))
+
+## [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.91.0",
   "description": "Claude Code-first opinionated workflow framework: instructions, personas, skills, and SDLC workflows that govern AI coding assistants.",
   "files": [
     ".agents/",