@1aboveio/skills 0.10.0

package/skills/engineering/resolve-issues/scripts/contract-revision.mjs

@@ -0,0 +1,220 @@
+// contract-revision — the MECHANIZED contract-freshness gate.
+//
+// The doctrine (SKILL.md "Contract-revision gate", run-state.md
+// units[].contractRevision) says: a human-approved contract revision on the
+// target branch supersedes older issue text, PR summaries, and prior verdicts;
+// before every producer/reviewer spawn and on resume, the unit's HEAD must
+// contain that revision, and a review is authoritative only if it ran against it.
+//
+// Prose alone leaves that a lookalike — the resolve-issues removal-path audit
+// found `contractRevision`/`reviewedContractSha` written to the manifest with
+// ZERO script readers: recorded, never enforced. This makes the load-bearing
+// sentence real: "Git ancestry — not a cached boolean — answers whether unit HEAD
+// contains the revision" is exactly `git merge-base --is-ancestor`, gathered live
+// and failing closed. It reuses combine-and-verify's isAncestor rather than
+// re-deriving the check.
+//
+//   node contract-revision.mjs check --in <manifest.json> --unit <id> --head <ref>
+//   node contract-revision.mjs check --sha <approvedSha> --head <ref> [--reviewed <sha>]
+//     [--skip-ref-check] to skip artifact existence (refs kept outside this repo)
+//     exit 0 = FRESH (HEAD contains the approved revision → the spawn may proceed)
+//     exit 1 = STALE (HEAD lacks it → re-enter intake: rebase + whole-contract reconcile)
+//     exit 2 = the pointer itself is unusable — malformed shape, or a path-shaped ref
+//              that does not exist at the approved commit (fix the pointer; a rebase
+//              cannot repair a citation to a file nobody wrote)
+//     A FRESH unit whose reviewedContractSha ≠ the approved sha still owes a
+//     full-scope review before it may exit — reported, exit stays 0 (proceeding is
+//     correct; it's the *exit* gate, not the spawn gate, that blocks there).
+//
+// Named incident: seven review rounds implemented an obsolete route-based control
+// plane (#936) before a human-approved Cloud Run Job contract (#946) landed on the
+// target branch; the stale-contract loop had no mechanized way to notice.
+
+import fs from 'node:fs'
+import { execFileSync } from 'node:child_process'
+import { isAncestor } from './combine-and-verify.mjs'
+import { isMainModule } from '../../engineering-runtime/scripts/main-module.mjs'
+
+// ---- pure, unit-testable core (no git) ----
+
+// Shape check for units[].contractRevision. `sha` and at least one `ref` are
+// required — a pointer with no commit or no artifact points at nothing. The
+// provenance fields (source/approvedAt/supersedesReviewThroughRound) are typed
+// when present but optional, so the validator accepts the real manifest shape
+// without forcing every writer to fill provenance it may add later.
+export function validateContractRevision(cr) {
+  const errors = []
+  if (cr == null) return { ok: true, errors } // absent is legal — not every unit has an approved revision yet
+  if (typeof cr !== 'object' || Array.isArray(cr)) return { ok: false, errors: ['contractRevision must be an object'] }
+  const allowed = ['sha', 'refs', 'source', 'approvedAt', 'supersedesReviewThroughRound']
+  for (const k of Object.keys(cr)) if (!allowed.includes(k)) errors.push(`contractRevision has unknown property: ${k}`)
+  if (typeof cr.sha !== 'string' || !cr.sha.trim()) errors.push('contractRevision.sha is required (the approved target-branch commit)')
+  if (!Array.isArray(cr.refs) || cr.refs.length === 0) errors.push('contractRevision.refs must be a non-empty array of the authoritative artifacts')
+  else if (!cr.refs.every((r) => typeof r === 'string' && r.trim())) errors.push('contractRevision.refs entries must be non-empty strings')
+  if (cr.source !== undefined && (typeof cr.source !== 'string' || !cr.source.trim())) errors.push('contractRevision.source must be a non-empty string when present')
+  if (cr.approvedAt !== undefined && (typeof cr.approvedAt !== 'string' || !cr.approvedAt.trim())) errors.push('contractRevision.approvedAt must be a non-empty string when present')
+  if (cr.supersedesReviewThroughRound !== undefined && (!Number.isInteger(cr.supersedesReviewThroughRound) || cr.supersedesReviewThroughRound < 0)) {
+    errors.push('contractRevision.supersedesReviewThroughRound must be a non-negative integer when present')
+  }
+  return { ok: errors.length === 0, errors }
+}
+
+// A ref must name an artifact that exists at the approved commit. Requiring a
+// non-empty `refs` array (above) only proves someone typed something; it does not
+// prove the design doc is there to build against. A contract citing a file that is
+// not in the tree is a pointer to nothing — and it fails silently, because every
+// downstream reader (producer, reviewer) is told to treat refs as the source
+// authority and simply finds no source.
+//
+// Only PATH-shaped refs are checked. `refs` legitimately carries non-path pointers
+// — the `(cli)` sentinel, `pr:#123`, `#849`, an https URL — and those are not
+// answerable with `git cat-file`. Skipped refs are reported, never silently
+// dropped: "checked 1 of 3" must be visible, or the gate reads as stronger than it is.
+//
+// Named incident: a unit that spent a review round correcting Review-Contract
+// citations pointing at two ADR/design files that did not exist in the repo.
+// A ref may carry a section anchor — the real epic-848 shape is
+// `CONTEXT.md#Blacklist Repair Plan Preparation`, naming a heading inside the file.
+// The anchor is for a human reader; git resolves the path only, so strip it before
+// asking. (Missing this turns every anchored ref into a false "missing artifact",
+// which is the failure mode that gets a new gate switched off in a day.) A leading
+// `#` is different — that is an issue reference, not a path, and stays non-path.
+const NON_PATH_REF = /^(\(|#|[a-z][a-z0-9+.-]*:)/i
+
+export function refPath(ref) {
+  return String(ref).trim().split('#')[0].trim()
+}
+
+export function isPathRef(ref) {
+  return typeof ref === 'string' && ref.trim() !== '' && !NON_PATH_REF.test(ref.trim()) && refPath(ref) !== ''
+}
+
+// Pure: split refs into what this gate can answer and what it cannot, given the
+// missing set gathered live.
+export function classifyRefs(refs, missing = []) {
+  const all = Array.isArray(refs) ? refs : []
+  const checked = all.filter(isPathRef)
+  const skipped = all.filter((r) => !isPathRef(r))
+  const missingSet = checked.filter((r) => missing.includes(r))
+  return {
+    ok: missingSet.length === 0,
+    checked,
+    skipped,
+    missing: missingSet,
+    errors: missingSet.map(
+      (r) => `contractRevision.refs entry "${r}" does not exist at the approved commit — the contract cites an artifact that is not in the tree`,
+    ),
+  }
+}
+
+// The freshness verdict from decidable facts. Two independent questions:
+//   fresh          — does HEAD contain the approved revision? (spawn gate)
+//   reviewCurrent  — did the latest verdict run against that exact revision? (exit gate)
+// A unit with no contractRevision is vacuously fresh — nothing supersedes it.
+export function contractFreshness({ contractRevision, reviewedContractSha, headContainsRevision }) {
+  if (contractRevision == null) return { fresh: true, reviewCurrent: true, mustReenter: false, owesFullReview: false, reasons: [] }
+  const reasons = []
+  const fresh = headContainsRevision === true
+  const reviewCurrent = fresh && reviewedContractSha === contractRevision.sha
+  if (!fresh) reasons.push(`unit HEAD does not contain the approved contract revision ${contractRevision.sha.slice(0, 8)} — re-enter intake: rebase onto the target branch and reconcile the whole implementation to the current invariant list`)
+  else if (!reviewCurrent) reasons.push(`HEAD contains the approved revision but the last review ran against ${reviewedContractSha == null ? 'no recorded revision' : reviewedContractSha.slice(0, 8)}, not ${contractRevision.sha.slice(0, 8)} — the next review is full-scope and prior verdicts/CI/lastReviewedSha are historical only`)
+  return {
+    fresh,
+    reviewCurrent,
+    mustReenter: !fresh, // HEAD lacks it → the producer must rebase before any further spawn
+    owesFullReview: fresh && !reviewCurrent, // HEAD has it but review is stale against it
+    reasons,
+  }
+}
+
+// ---- live facts (side-effecting) ----
+
+export function gatherFreshness(contractRevision, head, ancestry = isAncestor) {
+  return { headContainsRevision: contractRevision == null ? true : ancestry(contractRevision.sha, head) }
+}
+
+// Does `<sha>:<ref>` resolve to an object in this repo? Fails closed: any git
+// error (unknown sha, path absent, not a repo) counts the ref as missing, because
+// "we could not prove the artifact is there" and "the artifact is not there" have
+// the same consequence for a spawn told to build against it.
+export function refExistsAt(sha, ref) {
+  try {
+    execFileSync('git', ['cat-file', '-e', `${sha}:${ref}`], { stdio: 'ignore' })
+    return true
+  } catch {
+    return false
+  }
+}
+
+export function gatherMissingRefs(contractRevision, exists = refExistsAt) {
+  if (contractRevision == null) return []
+  return (contractRevision.refs || []).filter(isPathRef).filter((r) => !exists(contractRevision.sha, refPath(r)))
+}
+
+// ---- CLI ----
+
+function parseArgs(argv) {
+  const f = {}
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i]
+    if (a === '--in') f.in = argv[++i]
+    else if (a === '--unit') f.unit = argv[++i]
+    else if (a === '--head') f.head = argv[++i]
+    else if (a === '--sha') f.sha = argv[++i]
+    else if (a === '--reviewed') f.reviewed = argv[++i]
+    else if (a === '--skip-ref-check') f.skipRefCheck = true
+    else if (!f.cmd) f.cmd = a
+  }
+  return f
+}
+
+const USAGE = `contract-revision — the mechanized contract-freshness gate.
+Usage:
+  contract-revision check --in <manifest.json> --unit <id> --head <ref>
+  contract-revision check --sha <approvedSha> --head <ref> [--reviewed <sha>] [--skip-ref-check]
+Exit: 0 = FRESH (HEAD contains the approved revision), 1 = STALE (re-enter intake), 2 = pointer unusable. See the file header for the full contract.`
+
+export function runCli(argv) {
+  const f = parseArgs(argv)
+  if (f.cmd === 'help' || f.cmd === '--help' || f.cmd === '-h') { console.log(USAGE); return 0 }
+  if (f.cmd !== 'check') { console.error('usage: contract-revision check (--in <manifest> --unit <id> | --sha <sha> [--reviewed <sha>]) --head <ref> [--skip-ref-check]'); return 2 }
+  if (!f.head) { console.error('--head <ref> is required (the unit branch HEAD to test)'); return 2 }
+
+  let contractRevision, reviewedContractSha
+  if (f.in) {
+    if (!f.unit) { console.error('--in requires --unit <id>'); return 2 }
+    const manifest = JSON.parse(fs.readFileSync(f.in, 'utf8'))
+    const unit = (manifest.units || []).find((u) => u.id === f.unit)
+    if (!unit) { console.error(`unit ${f.unit} not found in ${f.in}`); return 2 }
+    const shape = validateContractRevision(unit.contractRevision)
+    if (!shape.ok) { console.error('contractRevision is malformed:'); shape.errors.forEach((e) => console.error(`  ✗ ${e}`)); return 2 }
+    contractRevision = unit.contractRevision ?? null
+    reviewedContractSha = unit.reviewedContractSha ?? null
+  } else if (f.sha) {
+    contractRevision = { sha: f.sha, refs: ['(cli)'] }
+    reviewedContractSha = f.reviewed ?? null
+  } else { console.error('provide either --in/--unit or --sha'); return 2 }
+
+  // Refs first: a contract whose artifacts are not in the tree cannot authorize a
+  // spawn no matter how the ancestry check comes out, and reporting it alongside a
+  // FRESH verdict would read as approval. Malformed pointer → 2, same as a shape failure.
+  if (!f.skipRefCheck && contractRevision != null) {
+    const refs = classifyRefs(contractRevision.refs, gatherMissingRefs(contractRevision))
+    if (refs.skipped.length) console.log(`contract-revision: refs — checked ${refs.checked.length}, skipped ${refs.skipped.length} non-path (${refs.skipped.join(', ')})`)
+    if (!refs.ok) {
+      console.error('contract-revision: ❌ contract cites artifacts missing at the approved commit:')
+      refs.errors.forEach((e) => console.error(`  ✗ ${e}`))
+      console.error('  fix the pointer (or land the artifact) — do not spawn against a contract that is not in the tree')
+      return 2
+    }
+  }
+
+  const facts = gatherFreshness(contractRevision, f.head)
+  const v = contractFreshness({ contractRevision, reviewedContractSha, headContainsRevision: facts.headContainsRevision })
+  if (v.fresh && v.reviewCurrent) console.log('contract-revision: ✅ FRESH — HEAD contains the approved revision and the last review ran against it')
+  else if (v.fresh) { console.log('contract-revision: ⚠️ FRESH but review is stale — proceed, but the exit gate owes a full-scope review:'); v.reasons.forEach((r) => console.log(`  · ${r}`)) }
+  else { console.log('contract-revision: ❌ STALE — do not spawn; re-enter intake:'); v.reasons.forEach((r) => console.log(`  ✗ ${r}`)) }
+  return v.mustReenter ? 1 : 0
+}
+
+if (isMainModule(import.meta.url)) process.exit(runCli(process.argv.slice(2)))

package/skills/engineering/resolve-issues/scripts/detect-delivery-mode.mjs

@@ -0,0 +1,420 @@
+// detect-delivery-mode — the MECHANIZED pre-flight delivery-mode probe.
+//
+// `deliveryMode` (direct | queue) decides which action delivers a merge-ready unit,
+// and picking it wrong fails SILENTLY IN BOTH DIRECTIONS: `gh pr merge` on a
+// merge-queue repo bypasses the queue or errors, and an enqueue on a direct repo
+// does nothing at all. That silence is the epic-986 shape.
+//
+// Why this exists as a script and not prose: the first prose version of the rule
+// said "a `.mergify.yml` carrying `queue_rules`, or a merge-queue-enabled ruleset
+// ⇒ queue; otherwise direct". Dogfooding it on the repo that introduced it proved
+// it wrong — this skills repo has NEITHER file and still merges through a live Mergify
+// queue whose `default` rule is configured dashboard-side, outside the repo
+// entirely. Both repos examined so far are configured that way, so a file-only
+// check gets the common case backwards. A queue is a RUNTIME fact: ask it.
+//
+//   node detect-delivery-mode.mjs                 # probe, recommend (JSON on stdout)
+//   node detect-delivery-mode.mjs --repo o/r      # explicit repo (default: gh's current)
+//   node detect-delivery-mode.mjs --branch main   # branch the ruleset/config applies to
+//   node detect-delivery-mode.mjs --help          # usage + exit 0
+//
+// OUTPUT (stdout, always JSON):
+//   { mode: "queue"|"direct"|null, queueProvider: "mergify"|"github"|null,
+//     queueProviderReason, signals: [{name, found, provider?, detail}], probed, reason }
+//
+// EXIT CODES:
+//   0  a mode was determined — and in queue mode, its PROVIDER too
+//   2  UNDETERMINED or usage error — mode null, never a silent "direct". Undetermined
+//      covers three states, all reported in `reason`/`queueProviderReason`: no probe ran
+//      at all; only the FILE probes ran and were negative (file silence is not evidence
+//      of direct mode); and a queue whose provider is unknown or ambiguous.
+// For the MODE there is deliberately no "probes disagree" code: any positive signal
+// proves a queue, so mode signals cannot contradict each other — they only accumulate.
+// That reasoning does NOT extend to the PROVIDER: a repo carrying both a .mergify.yml
+// and a merge_queue ruleset gives two different answers about the same queue, and the
+// mechanics differ per provider, so disagreement there is a human ask (provider null).
+//
+// The fail-closed property is exit 2. "No evidence of a queue" and "could not look
+// for a queue" are different states, and collapsing them is how the wrong default
+// gets recorded as though it had been established. The manifest's absent-mode
+// default (`direct`, for manifests written before the gate) is a LEGACY read, not
+// a licence to guess here.
+
+import { execFileSync } from 'node:child_process'
+import { realpathSync } from 'node:fs'
+import { fileURLToPath } from 'node:url'
+
+// ---- pure, unit-testable core (no network, no subprocesses) ----
+
+// A queue is proved by ANY positive signal, because queue configuration lives in
+// several places and no single one is authoritative:
+//   mergify-config      .mergify.yml with queue_rules            (repo-side Mergify)
+//   github-merge-queue  a ruleset carrying a merge_queue rule    (native GitHub)
+//   mergify-live-queue  the Mergify API answers for this repo    (dashboard-side)
+//   observed-queue-check a recent PR carries a queue check run   (gh-only fallback)
+// The last two are what a file-only check misses.
+export const DELIVERY_SIGNALS = ['mergify-config', 'github-merge-queue', 'mergify-live-queue', 'observed-queue-check']
+
+export function decideDeliveryMode(signals) {
+  const list = Array.isArray(signals) ? signals : []
+  const known = list.filter((s) => DELIVERY_SIGNALS.includes(s?.name))
+  const ran = known.filter((s) => s.ran !== false)
+  // No probe completed → we do not know. This is the whole point of the script:
+  // "could not look" must not read back as "looked and found nothing".
+  if (ran.length === 0) {
+    return { mode: null, probed: false, reason: 'no delivery-mode probe could run — mode is UNKNOWN; settle it with the human rather than defaulting', signals: known }
+  }
+  const positive = ran.filter((s) => s.found === true)
+  if (positive.length > 0) {
+    return { mode: 'queue', probed: true, reason: `a merge queue is live for this repo (${positive.map((s) => s.name).join(', ')}) — delivery is enqueue-then-watch, never \`gh pr merge\``, signals: known }
+  }
+  // Every probe that ran came back negative. A negative from the LIVE probes is
+  // worth more than a negative from the file probes, which is exactly the asymmetry
+  // the first version of this rule got wrong — so say which probes carried it.
+  const liveRan = ran.some((s) => s.name === 'mergify-live-queue' || s.name === 'observed-queue-check')
+  if (!liveRan) {
+    return { mode: null, probed: true, reason: 'only file-based probes ran and found nothing — queue config commonly lives outside the repo, so this is NOT evidence of direct mode; run the live probe or settle with the human', signals: known }
+  }
+  return { mode: 'direct', probed: true, reason: 'no merge queue answers for this repo — delivery is the legacy `gh pr merge` path', signals: known }
+}
+
+// The mode is not the whole answer. `queue` is TWO flows — Mergify and GitHub's native
+// merge queue — and they differ in every mechanic the delivery step uses: how you enqueue
+// (a PR comment vs an API call), where state is read, what the dequeue reasons are called,
+// and whether a re-evaluation request or an acknowledgement exists at all. The prose used
+// to offer "`@mergifyio queue`, or `gh pr merge --auto`" as if they were interchangeable
+// spellings; they are not, and a run that picks the wrong one fails the same silent way
+// picking the wrong MODE does.
+//
+// Note the asymmetry with mode: for mode, "any positive signal proves a queue" and signals
+// cannot contradict each other. For provider they very much can — a repo carrying both a
+// .mergify.yml and a merge_queue ruleset yields two answers, and choosing one by
+// precedence would be a guess wearing a rule. That is a human ask, so it returns null.
+export const SIGNAL_PROVIDERS = {
+  'mergify-config': 'mergify',
+  'mergify-live-queue': 'mergify',
+  'github-merge-queue': 'github',
+  // 'observed-queue-check' carries its own — it matches both vocabularies, so the probe
+  // reports which one it actually saw rather than being mapped blind.
+}
+
+export function decideQueueProvider(signals) {
+  const positive = (Array.isArray(signals) ? signals : []).filter((s) => s?.ran !== false && s?.found === true)
+  const providers = [...new Set(positive.map((s) => s.provider ?? SIGNAL_PROVIDERS[s?.name] ?? null).filter(Boolean))]
+  if (providers.length === 1) {
+    return { provider: providers[0], reason: `queue mechanics are ${providers[0]}'s (${positive.filter((s) => (s.provider ?? SIGNAL_PROVIDERS[s.name]) === providers[0]).map((s) => s.name).join(', ')})` }
+  }
+  if (providers.length > 1) {
+    return { provider: null, reason: `AMBIGUOUS — signals point at more than one queue provider (${providers.join(', ')}); the mechanics differ per provider, so this is a human ask, not a precedence rule` }
+  }
+  return { provider: null, reason: 'a queue answers for this repo but no signal identified WHICH provider runs it — settle it with the human before delivery acts' }
+}
+
+// ---- the third axis: what merges this PR without the loop acting again? ----
+//
+// Mode and provider answer "how do I enqueue". They do NOT answer the question guarantee 4
+// actually depends on: **can this PR reach the target branch without the loop performing a
+// delivery action at all?** A repo can carry an auto-merge rule that fires the moment its
+// conditions are satisfied, and the loop's own routine acts — marking a PR ready, pushing
+// the commit that turns CI green, posting the review verdict — are exactly the things that
+// satisfy them. Where that is true, `mergeShippable: false` is unenforceable: the loop
+// never chooses to merge, it merges as a side effect of reviewing.
+//
+// Note what this axis is NOT. It is not "manual or auto" as alternatives — manual enqueue
+// stays available on an auto repo, so the loop never loses the ability to enqueue. What
+// changes is that a SECOND path exists which the loop does not drive. So the trigger
+// describes what the REPO can do on its own, never what the loop is permitted to do.
+//
+// Grounded in a live config (a consumer harness repo, 2026-07-25):
+//   merge_protections_settings:
+//     auto_merge_conditions:
+//       - base = main
+//       - "-draft"
+//       - "#approved-reviews-by >= 1"
+//       - "#changes-requested-reviews-by = 0"
+//       - check-success = ci
+// Its GitHub rulesets require zero approvals, so that one review condition IS the merge
+// authorization — and the reviewer spawn posting its verdict as an approval is the act
+// that merges. That is the case this probe exists to make visible before delivery starts.
+export const ENQUEUE_TRIGGERS = ['manual', 'auto', 'hybrid']
+
+// Conditions the LOOP can satisfy through its own ordinary work. These are the dangerous
+// ones: a condition only a human can meet (a label a person applies, a schedule) leaves
+// the merge outside the loop's reach, which is safe. A condition the loop trips by doing
+// its job turns a routine step into a merge.
+const LOOP_TRIPPABLE = [
+  { re: /approved-reviews-by/i, act: 'posting an approving review', kind: 'review' },
+  { re: /changes-requested-reviews-by/i, act: 'resolving or not filing a change request', kind: 'review' },
+  { re: /^\s*-?\s*-draft\b/i, act: 'marking the PR ready for review', kind: 'draft' },
+  { re: /check-success|status-success/i, act: 'pushing the commit that turns CI green', kind: 'ci' },
+]
+
+// Deliberately a light structural read, not a YAML parser: this repo's scripts take no
+// dependencies, and the question here is coarse (does an auto-merge block exist, and what
+// does it list?). Anything it cannot parse confidently must read as UNKNOWN rather than as
+// "no auto-merge" — see decideEnqueueTrigger's fail-closed direction.
+export function parseAutoMergeConditions(yamlText) {
+  const text = String(yamlText ?? '')
+  const lines = text.split('\n')
+  const start = lines.findIndex((l) => /^\s*auto_merge_conditions\s*:/.test(l))
+  if (start === -1) return { present: false, conditions: [] }
+  const indent = (lines[start].match(/^\s*/) || [''])[0].length
+  const conditions = []
+  for (let i = start + 1; i < lines.length; i++) {
+    const line = lines[i]
+    if (!line.trim() || /^\s*#/.test(line)) continue
+    const ind = (line.match(/^\s*/) || [''])[0].length
+    if (ind <= indent) break
+    const m = line.match(/^\s*-\s*(.+?)\s*$/)
+    if (!m) break
+    conditions.push(m[1].replace(/^["']|["']$/g, ''))
+  }
+  return { present: true, conditions }
+}
+
+// Which of the auto-merge conditions can this loop satisfy by doing its ordinary work?
+export function loopTrippableConditions(conditions) {
+  return (Array.isArray(conditions) ? conditions : []).flatMap((c) => {
+    const cond = String(c)
+    // A YAML alias (`*gate`) hides its condition behind an anchor defined elsewhere, and
+    // both real configs examined use one for exactly the CI check. Resolving anchors would
+    // mean writing a YAML parser; reporting the alias as harmless would mean deciding, on
+    // no evidence, that the thing we could not read is not one the loop trips. So it is
+    // reported as trippable-unknown — the same fail-closed direction as the trigger itself.
+    if (/^\*\S+$/.test(cond)) {
+      return [{ condition: cond, act: `satisfying \`${cond}\`, a YAML alias this probe cannot resolve`, kind: 'unresolved-alias' }]
+    }
+    const hit = LOOP_TRIPPABLE.find((t) => t.re.test(cond))
+    return hit ? [{ condition: cond, act: hit.act, kind: hit.kind }] : []
+  })
+}
+
+export function decideEnqueueTrigger(signals) {
+  const sig = (Array.isArray(signals) ? signals : []).find((s) => s?.name === 'mergify-auto-merge')
+  // Could not look. Fail closed toward the HAZARD, not toward convenience: assuming
+  // `manual` on a repo that auto-merges is how a run configured to merge nothing merges
+  // anyway, and nothing downstream would report it. Assuming the hazard costs at most an
+  // extra human confirmation.
+  if (!sig || sig.ran === false) {
+    return { trigger: null, autoMergeConditions: [], loopTrippable: [], reason: 'could not read the repo\'s auto-merge configuration — the trigger is UNKNOWN; treat as auto (fail closed) and settle it with the human before posting any review that could satisfy a merge condition' }
+  }
+  if (!sig.found) {
+    return { trigger: 'manual', autoMergeConditions: [], loopTrippable: [], reason: 'no auto-merge rule found — a merge happens only when this loop performs a delivery action' }
+  }
+  const conditions = Array.isArray(sig.conditions) ? sig.conditions : []
+  const trippable = loopTrippableConditions(conditions)
+  // `hybrid` when the manual command is also open: the loop keeps its own enqueue path,
+  // and the auto path exists beside it. The distinction matters for the MECHANICS the
+  // loop uses; for AUTHORIZATION `auto` and `hybrid` are identical, and every gate reads
+  // them that way (trigger !== 'manual').
+  const trigger = sig.manualAlsoAllowed === false ? 'auto' : 'hybrid'
+  return {
+    trigger,
+    autoMergeConditions: conditions,
+    loopTrippable: trippable,
+    reason: trippable.length
+      ? `this repo merges a PR on its own once its auto-merge conditions hold, and this loop can satisfy ${trippable.length} of them by ${trippable.map((t) => t.act).join('; ')} — those acts ARE the merge, so they inherit guarantee 4's authorization`
+      : 'an auto-merge rule exists, but no condition in it is one this loop trips through its ordinary work',
+  }
+}
+
+// ---- impure probes ----
+
+function tryRun(cmd, args, opts = {}) {
+  try { return { ok: true, out: execFileSync(cmd, args, { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'], ...opts }) } }
+  catch (error) { return { ok: false, out: '', error } }
+}
+
+function probeMergifyConfig(repo, branch) {
+  for (const path of ['.mergify.yml', '.mergify/config.yml', '.mergify.yaml']) {
+    const r = tryRun('gh', ['api', `repos/${repo}/contents/${path}?ref=${branch}`, '--jq', '.content'])
+    if (!r.ok || !r.out.trim()) continue
+    let decoded = ''
+    try { decoded = Buffer.from(r.out.replace(/\s/g, ''), 'base64').toString('utf8') } catch { continue }
+    if (/^\s*queue_rules\s*:/m.test(decoded)) return { name: 'mergify-config', ran: true, found: true, detail: `${path} declares queue_rules` }
+    return { name: 'mergify-config', ran: true, found: false, detail: `${path} exists but declares no queue_rules` }
+  }
+  // Every candidate path failed to read. That is only a NEGATIVE if gh could actually
+  // talk to the repo; otherwise the probe did not run, and reporting it as "no
+  // .mergify.yml" fabricates evidence. Distinguish with a cheap reachability check.
+  const reachable = tryRun('gh', ['api', `repos/${repo}`, '--jq', '.name'])
+  if (!reachable.ok) return { name: 'mergify-config', ran: false, found: false, detail: `cannot read ${repo} via gh — probe did not run` }
+  return { name: 'mergify-config', ran: true, found: false, detail: 'no .mergify.yml in the repo' }
+}
+
+function probeGithubMergeQueue(repo, branch) {
+  const r = tryRun('gh', ['api', `repos/${repo}/rulesets`, '--jq', '.[].id'])
+  if (!r.ok) return { name: 'github-merge-queue', ran: false, found: false, detail: 'rulesets unreadable (permissions?)' }
+  const ids = r.out.split('\n').map((s) => s.trim()).filter(Boolean)
+  for (const id of ids) {
+    const d = tryRun('gh', ['api', `repos/${repo}/rulesets/${id}`, '--jq', '[.rules[].type] | join(",")'])
+    if (d.ok && d.out.includes('merge_queue')) return { name: 'github-merge-queue', ran: true, found: true, detail: `ruleset ${id} carries a merge_queue rule` }
+  }
+  return { name: 'github-merge-queue', ran: true, found: false, detail: `no merge_queue rule in ${ids.length} ruleset(s)` }
+}
+
+// The probe the file-only rule was missing. `mergify queue status` answers for a
+// repo whose queue is configured dashboard-side and therefore appears in no file.
+// The pure half of the live probe: given mergify's output, does it answer about the
+// repo we ASKED about? This is where BLOCK-3 lived (a queue reported for the cwd's repo
+// read as evidence about a different one), so it is separated to be testable without
+// shelling out.
+export function readLiveQueueAnswer(repo, out) {
+  const line = (out.split('\n').find((l) => l.includes('Merge Queue:')) || '').trim()
+  if (!line) return { found: false, detail: `no queue reported for ${repo}` }
+  if (!line.includes(repo)) return { found: false, detail: `queue reported for a DIFFERENT repo (${line}) — not evidence about ${repo}` }
+  return { found: true, detail: line }
+}
+
+function probeMergifyLiveQueue(repo) {
+  const r = tryRun('mergify', ['queue', 'status', '--repository', repo])
+  // No cwd-scoped fallback. `mergify queue status` without --repository answers for the
+  // CURRENT checkout, and the command fails non-zero precisely for repos Mergify does
+  // not manage — i.e. every direct-mode candidate. So the fallback turned "this repo has
+  // no queue" into "the repo I happen to be standing in has one", which is the silent
+  // wrong-mode failure this whole script exists to prevent. A failure is `ran: false`.
+  if (!r.ok) return { name: 'mergify-live-queue', ran: false, found: false, detail: `mergify queue status failed for ${repo} (unmanaged repo, CLI unavailable, or unauthenticated)` }
+  return { name: 'mergify-live-queue', ran: true, ...readLiveQueueAnswer(repo, r.out) }
+}
+
+// gh-only fallback for when the mergify CLI is not installed: a repo that merges
+// through a queue leaves a queue check run on its recent PRs.
+function probeObservedQueueCheck(repo) {
+  const r = tryRun('gh', ['pr', 'list', '--repo', repo, '--state', 'merged', '--limit', '5', '--json', 'statusCheckRollup', '--jq', '[.[].statusCheckRollup[]?.name] | join("|")'])
+  if (!r.ok) return { name: 'observed-queue-check', ran: false, found: false, detail: 'recent PR checks unreadable' }
+  const mergify = /Mergify Merge Queue/i.test(r.out)
+  const github = /merge_group/i.test(r.out)
+  const found = mergify || github
+  // Which vocabulary the check-run came from IS the provider evidence. Reporting only
+  // "a queue check exists" throws away the one bit that decides the mechanics.
+  const provider = mergify && github ? null : (mergify ? 'mergify' : (github ? 'github' : null))
+  return {
+    name: 'observed-queue-check', ran: true, found, ...(provider ? { provider } : {}),
+    detail: found ? `a recent merged PR carries a ${provider ?? 'merge-queue (both vocabularies seen)'} check` : 'no merge-queue check on the last 5 merged PRs',
+  }
+}
+
+// Read the repo's Mergify config for an auto-merge block. Reads the same candidate paths
+// as probeMergifyConfig; kept separate because it answers a different question and must
+// report `ran: false` on its own terms — a config it could not read is UNKNOWN, and
+// decideEnqueueTrigger fails closed on that rather than reading it as "no auto-merge".
+function probeMergifyAutoMerge(repo, branch) {
+  for (const path of ['.mergify.yml', '.mergify/config.yml', '.mergify.yaml']) {
+    const r = tryRun('gh', ['api', `repos/${repo}/contents/${path}?ref=${branch}`, '--jq', '.content'])
+    if (!r.ok || !r.out.trim()) continue
+    let decoded = ''
+    try { decoded = Buffer.from(r.out.replace(/\s/g, ''), 'base64').toString('utf8') } catch { continue }
+    const { present, conditions } = parseAutoMergeConditions(decoded)
+    // `commands_restrictions.queue` present means the manual command is gated but still
+    // available — the hybrid shape. Absence of the key does not prove the command is
+    // disabled, so the default stays "manual also allowed", which is the true reading for
+    // every Mergify repo observed so far.
+    const manualAlsoAllowed = true
+    if (!present) return { name: 'mergify-auto-merge', ran: true, found: false, detail: `${path} declares no auto_merge_conditions` }
+    return {
+      name: 'mergify-auto-merge', ran: true, found: true, conditions, manualAlsoAllowed,
+      detail: `${path} auto-merges on: ${conditions.join(' AND ') || '(no conditions parsed)'}`,
+    }
+  }
+  const reachable = tryRun('gh', ['api', `repos/${repo}`, '--jq', '.name'])
+  if (!reachable.ok) return { name: 'mergify-auto-merge', ran: false, found: false, detail: `cannot read ${repo} via gh — probe did not run` }
+  // No Mergify config file at all. That is a real negative for a repo-side auto-merge
+  // rule, but NOT for a dashboard-side one, which this probe cannot see — so it is
+  // reported as a negative with that caveat named in the CLI's reason.
+  return { name: 'mergify-auto-merge', ran: true, found: false, detail: 'no .mergify.yml in the repo (a dashboard-side auto-merge rule would not appear here)' }
+}
+
+export function gatherSignals({ repo, branch }) {
+  return [
+    probeMergifyConfig(repo, branch),
+    probeGithubMergeQueue(repo, branch),
+    probeMergifyLiveQueue(repo),
+    probeObservedQueueCheck(repo),
+    probeMergifyAutoMerge(repo, branch),
+  ]
+}
+
+function currentRepo() {
+  const r = tryRun('gh', ['repo', 'view', '--json', 'nameWithOwner', '--jq', '.nameWithOwner'])
+  return r.ok ? r.out.trim() : null
+}
+
+function parseArgs(argv) {
+  const f = {}
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i]
+    if (a === '--repo') f.repo = argv[++i]
+    else if (a === '--branch') f.branch = argv[++i]
+    else if (a === '--help' || a === '-h') f.help = true
+  }
+  return f
+}
+
+export function runCli(argv) {
+  const f = parseArgs(argv)
+  if (f.help) {
+    console.log(`detect-delivery-mode [--repo <owner/name>] [--branch <branch>]
+Probes three things pre-flight must settle before delivery acts:
+  deliveryMode    direct | queue        — which action delivers a merge-ready unit
+  queueProvider   mergify | github      — whose mechanics the queue uses
+  enqueueTrigger  manual | auto | hybrid — whether the REPO can merge the PR with no
+                  further action from this loop, and which auto-merge conditions this
+                  loop can satisfy through its ordinary work (posting a review, marking
+                  ready, turning CI green). Those acts ARE the merge where they appear.
+exit 0 = all three determined · 2 = mode/provider UNDETERMINED or usage error · 3 = mode known but the trigger is UNKNOWN.
+Nothing is guessed: "could not look" and "looked and found nothing" are different answers, and both the provider and the trigger fail closed.`)
+    return 0
+  }
+  const repo = f.repo || currentRepo()
+  if (!repo) { console.error('detect-delivery-mode: no --repo given and gh could not resolve the current repository'); return 2 }
+  const branch = f.branch || 'main'
+  const signals = gatherSignals({ repo, branch })
+  const decision = decideDeliveryMode(signals)
+  // The provider question only exists in queue mode; in direct mode there is no queue to
+  // have mechanics. Reported alongside the mode so pre-flight settles both in one probe.
+  const provider = decision.mode === 'queue' ? decideQueueProvider(signals) : { provider: null, reason: 'direct mode has no queue provider' }
+  // The trigger is reported in EVERY mode, including direct: an auto-merge rule merges a
+  // PR whether or not a queue is involved, so "direct mode" is not a reason to skip the
+  // question guarantee 4 depends on.
+  const trig = decideEnqueueTrigger(signals)
+  console.log(JSON.stringify({
+    repo, branch, ...decision,
+    queueProvider: provider.provider, queueProviderReason: provider.reason,
+    enqueueTrigger: trig.trigger, enqueueTriggerReason: trig.reason,
+    autoMergeConditions: trig.autoMergeConditions, loopTrippableConditions: trig.loopTrippable,
+  }, null, 2))
+  if (!decision.mode) return 2
+  // Fail closed on the trigger too, and for the same reason as the provider: a run that
+  // does not know whether its own review will merge the PR cannot be allowed to review
+  // first and find out. Exit 3 rather than 2 so the caller can tell "no mode" from "mode
+  // known, authorization semantics unknown" — the second is settled by a different answer.
+  if (!trig.trigger) return 3
+  // Fail CLOSED on the second half of the answer too. A queue whose provider is unknown
+  // cannot be delivered mechanically — the enqueue command itself is unknown — and
+  // returning 0 here would let pre-flight record a mode that delivery then refuses to act
+  // on, which is the wrong-mode silence one layer down.
+  if (decision.mode === 'queue' && !provider.provider) return 2
+  return 0
+}
+
+let launchedDirectly = false
+let mainModuleError = null
+try {
+  const { isMainModule } = await import('../../engineering-runtime/scripts/main-module.mjs')
+  if (typeof isMainModule !== 'function') throw new Error('main-module.mjs does not export isMainModule')
+  launchedDirectly = isMainModule(import.meta.url)
+} catch (error) {
+  mainModuleError = error
+  try {
+    launchedDirectly = realpathSync(process.argv[1]) === realpathSync(fileURLToPath(import.meta.url))
+  } catch {
+    launchedDirectly = false
+  }
+}
+
+if (launchedDirectly && mainModuleError) {
+  console.error(`detect-delivery-mode: cannot load engineering-runtime main-module helper: ${mainModuleError.message}`)
+  process.exitCode = 1
+} else if (launchedDirectly) {
+  process.exit(runCli(process.argv.slice(2)))
+}