@codyswann/lisa 4.34.6 → 4.34.7

package/package.json

@@ -166,7 +166,7 @@
     "zod-validation-error": "^4.0.0"
   },
   "name": "@codyswann/lisa",
-  "version": "4.34.6",
+  "version": "4.34.7",
   "description": "Claude Code governance framework that applies guardrails, guidance, and automated enforcement to projects",
   "main": "dist/index.js",
   "exports": {
@@ -314,7 +314,7 @@
     "test": "tests"
   },
   "types": "./dist/index.d.ts",
-  "lisaReleaseCommit": "825a67c494db413e3fb3305e1db7c2048d8ecdfa",
-  "gitHead": "825a67c494db413e3fb3305e1db7c2048d8ecdfa",
-  "lisaReleaseTag": "v4.34.6"
+  "lisaReleaseCommit": "f8ef00f1ee6983cc64b50c18461d52e70f5ae887",
+  "gitHead": "f8ef00f1ee6983cc64b50c18461d52e70f5ae887",
+  "lisaReleaseTag": "v4.34.7"
 }

package/plugins/lisa/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa",
-  "version": "4.34.6",
+  "version": "4.34.7",
   "description": "Universal governance — agents, skills, commands, hooks, and rules for all projects",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa",
-  "version": "4.34.6",
+  "version": "4.34.7",
   "description": "Universal governance: agents, skills, commands, hooks, and rules for all projects.",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa/.codex-plugin/skills/lisa-drive-pr-to-merge/SKILL.md

@@ -29,8 +29,11 @@ merges" loop. Other skills delegate here instead of re-implementing it. Runs
 - `verify_commit=<sha>` — the commit that MUST end up in the merged base (for the
   ancestry check). Default: the PR head at the time this skill starts.
 - `auto_merge=<true|false>` — whether this skill is allowed to merge the PR at
-  all. Default `true` (existing behavior, byte-identical for every current
-  caller). With `auto_merge=false` the PR is deliberately left for a human:
+  all. Default `true`. `true` is permission to merge, **not** an instruction to
+  arm the latch immediately: arming is gated on the review context having done
+  work (section 1's arm gate), and under a vacuous context the merge is made
+  here, in the open, or not at all. With `auto_merge=false` the PR is
+  deliberately left for a human:
   skip the **entire** "## 1. Enable auto-merge" step — including its
   direct-merge capability fallback — and never run any `gh pr merge` variant.
   Still drive every blocker per `on_blocker` (green checks, resolved reviews,
@@ -44,12 +47,13 @@ merges" loop. Other skills delegate here instead of re-implementing it. Runs
     resolve review comments, dismiss stale review gates — drive until merged.
   - **`report`** (diagnose & mechanically nudge only): perform just the safe,
     idempotent, non-destructive actions — ensure auto-merge is enabled (when
-    `auto_merge=true`) and, if the
+    `auto_merge=true` **and the arm gate cleared**; arming against a review that
+    did no work is authorising a merge, which is not diagnosis) and, if the
     PR is `BEHIND` but otherwise clean, run `gh pr update-branch` only when the
     base branch requires strict up-to-date checks. For **anything** that would
     require editing code, resolving threads, or dismissing a review, **do not
     act** — stop and return a structured blocker classification
-    (`merged` / `will-merge-after-resync` / `blocked:<conflict|checks|changes_requested|deploy|pending-auto-fix>`)
+    (`merged` / `will-merge-after-resync` / `blocked:<conflict|checks|changes_requested|deploy|pending-auto-fix|unreviewed>`)
     so the caller applies its own policy. This is the mode `repair-intake` and the
     build-intake skills use to diagnose-and-route without fixing in place.
 
@@ -120,6 +124,157 @@ If the disarm fails or the re-read still shows an armed `autoMergeRequest`,
 PR could merge without a human. Once disarmed (or already unarmed), proceed
 straight to the watch loop (section 2).
 
+### The arm gate — never arm against a review that did no work
+
+**This gate governs the `auto_merge=true` path, and it decides WHETHER to arm.
+It does not touch the rule below that a latch, once armed, stays armed.** Those
+are two different questions with two different answers: arming prematurely is
+what this gate prevents; turning off a live latch is what the rest of section
+1 forbids.
+
+**Scope: repositories that declare a review check.** The defect is a required
+review context reporting satisfied having read nothing, so where no such
+context exists there is no false green to withhold the latch from, and arming is
+unchanged. A repository with no `evidence_bearing_checks` in
+`.github/required-checks.json` — or none at all — passes this gate immediately.
+Holding those PRs would redden a whole fleet for a gate none of them asked for,
+which is how a guard gets deleted rather than adopted.
+
+Arming is a decision to merge, made in advance and executed by GitHub without
+you. Everything this skill knows about the review — step (d)'s `reviewed` /
+`NOT REVIEWED` verdict, the five sole-gate conditions, the mandatory
+`MERGED — NOT REVIEWED` report line — is evaluated in the watch loop, which runs
+AFTER the latch is on. So an armed latch never merges on that reasoning. It
+merges on green checks, and whatever the loop would have concluded is simply
+never consulted.
+
+Measured (#3439): `auto_merge` defaults to `true` and `lisa-git-submit-pr` armed
+the latch at submit time, before any review existed. Step (d)'s exception —
+five live-verified conditions and a mandatory report line — could not fire on
+any pull request, because GitHub had already merged it the moment CI went green.
+A guard that cannot be reached is not a guard: the merge happened on the latch,
+not on the reasoning.
+
+**So the latch may only ever be armed against a review context that did work.**
+The consequence is the whole point. An unreviewed merge then has exactly one
+route left — step (d), which verifies its five conditions against a live poll
+and is *required* to write `MERGED — NOT REVIEWED`. This does not forbid the
+unreviewed merge; the owner's ruling on #3221 is explicit that a vendor
+entitlement state must not redden every pull request. It makes the unreviewed
+merge VISIBLE, by leaving it only one path that can produce it, and that path
+reports itself.
+
+#### Classify before arming
+
+**Vacuity is the prover's answer, not a string you match here.** The repository
+already ships the detector; consult it on the merge path instead of re-deriving
+its vocabulary, which is how the two drift apart:
+
+```bash
+node scripts/check-skipped-required-checks.mjs --vacuity --pr=<pr> --json
+```
+
+When `scripts/` carries no installed copy, try the in-repo template at
+`typescript/copy-overwrite/scripts/check-skipped-required-checks.mjs` — the same
+second address `review-evidence.yml` resolves. `--vacuity` is the mode that WAITS
+for the declared checks to settle, which is exactly what "before arming" needs:
+a pull request carries several intermediate statuses on one head SHA, and
+judging the first one seen would classify every PR as vacuous.
+
+Read `violations[].kind` and `inspected`, **never the exit code** — a named
+entitlement waiver is report-only under every flag by the #3221 ruling, so a
+zero exit is not evidence that a review happened:
+
+| reading | what it means | arm? |
+| --- | --- | --- |
+| `inspected: true`, no review-related violation | the check did work | **arm** |
+| `review_evidence_unsatisfied` | a review RAN AND OBJECTED | no — a real blocker; steps (d)/(e) |
+| `review_evidence_waived` | a named vendor entitlement | no — vacuous |
+| `vacuous_required_check` | success carrying a no-work description | no — vacuous |
+| `unproven_required_check` | a description proving nothing either way, or no status at all | no — vacuous |
+| `inspected: false` with `vacuity_none_declared` | this repository declares no review check | **arm** — out of scope, see above |
+| `inspected: false`, any other refusal | something was supposed to be read and was not | no — an empty inspection is not a pass |
+
+The last two rows are the same field and opposite answers, so read the refusal
+kind rather than the `inspected` flag. `vacuity_none_declared` means there is
+nothing to inspect; `vacuity_pr_unresolved`, `vacuity_checks_unreadable` and
+`vacuity_no_checks_reported` mean there is, and it was not inspected — most
+often a missing `actions: read`, which makes `gh` exit non-zero with empty
+stdout and never says the word "permission". Collapsing those into one answer is
+this file's own thesis about false greens, aimed at itself.
+
+If the prover cannot be run at all, fall back to reading the check yourself and
+require a POSITIVE reading before arming:
+
+```bash
+gh pr checks <pr> --json name,state,description,bucket \
+  --jq '.[] | select(.name == "<review-context>")'
+```
+
+`<review-context>` is whatever `.github/required-checks.json` declares under
+`evidence_bearing_checks` — do not assume `CodeRabbit`, and if nothing is
+declared, arm normally (the scope rule above). Where one IS declared, absent a
+description that positively states a review ran, treat the context as vacuous.
+Fail closed: absence of evidence is not evidence of a review.
+
+#### Vacuous and transient are different properties
+
+A vacuous context is not automatically something to wait out, and this is the
+distinction a naive wait-and-arm gets wrong — it waits forever on a repository
+where the state never clears. **Only the rate limit has both properties.**
+
+| description | vacuous? | clears on its own? |
+| --- | --- | --- |
+| `Review rate limited` | yes | **yes** — a throughput window |
+| `Review skipped: manual review required for this OSS repository` | yes | **no** — a standing vendor policy for public repositories |
+| `Review skipped: N files exceed the limit of M` | yes | **no** — not without splitting the pull request |
+| `Review skipped` (bare, no stated reason) | yes | **unknown — treat as standing** |
+
+A bare skip carries no machine-readable reason, so nothing distinguishes it from
+the standing forms. Requiring a stated reason before treating a skip as vacuous
+is how the commonest form gets missed.
+
+- **Transient (the rate limit, and only the rate limit)** — do not arm yet. Wait
+  the window out and re-request the review **at most once**, then re-classify.
+  If it now proves work, arm. If it does not, stop and treat it as standing.
+  **Never loop**: a retry loop re-triggers the very limit it is escaping, and
+  measured on #3220 a single explicit re-request in this repository was
+  acknowledged, went `Review in progress`, and settled back at
+  `Review rate limited` two seconds later having reviewed nothing — minting a
+  second hollow green. One attempt, then report.
+- **Standing** — do not wait at all, and do not re-request. There is no window
+  to wait out, so waiting produces a stall that reads as progress. Go straight
+  to the watch loop and let step (d) adjudicate the merge in the open.
+
+#### A latch somebody else armed
+
+Not arming is not enough. `lisa-git-submit-pr`, an older Lisa version, or a
+previous session may have left the latch on, and an armed latch merges the
+instant checks go green no matter what this gate concluded. So when the gate
+says do not arm, turn any existing latch off and prove it took — the same
+mechanism and the same fail-closed re-read the `auto_merge=false` contract above
+uses:
+
+```bash
+armed=$(gh pr view <pr> --json autoMergeRequest -q .autoMergeRequest)
+if [ "$armed" != "null" ] && [ -n "$armed" ]; then
+  gh pr merge <pr> --disable-auto
+fi
+gh pr view <pr> --json autoMergeRequest -q .autoMergeRequest   # must print null
+```
+
+If the re-read still shows an armed `autoMergeRequest`, **fail closed**: report a
+hard block (section 4) rather than proceeding into a state where the PR can
+merge with neither a review nor step (d)'s recorded decision.
+
+**What this costs, stated plainly.** While the review context is vacuous the PR
+cannot merge unattended, so a run that ends early leaves it open. That is the
+opposite trade from the armed-across-fix-pushes rule below, and it is deliberate:
+there, the thing at risk was a PR sitting unmerged; here, the thing at risk is
+code shipping that nothing read. The cost is bounded — the moment the context
+proves work, the latch is armed and the unattended behaviour returns — and the
+open PR is REPORTED (`blocked:unreviewed`, section 4), not silently abandoned.
+
 Before enabling auto-merge, capture the live PR head and compare it to
 `verify_commit`:
 
@@ -176,15 +331,23 @@ is what CATCHES a raced merge — it fails loudly when the fix SHA is not an
 ancestor of the base branch — so the rare miss is detected rather than silent.
 
 **Invariant:** never terminate having left auto-merge OFF on an open PR when
-`auto_merge=true`. If some future path does disable it, restoring it is a
-terminal obligation on EVERY exit — including give-up, budget-exhausted and error
-paths — not a later step in a sequence.
+`auto_merge=true` **and the arm gate cleared**. If some future path does turn it
+off, restoring it is a terminal obligation on EVERY exit — including give-up,
+budget-exhausted and error paths — not a later step in a sequence. A PR the arm
+gate held unarmed is outside this invariant: holding it is the gate's purpose,
+and `blocked:unreviewed` (section 4) is how that exit is reported rather than
+passed off as success.
 
 - **Capability fallback** (`auto_merge=true` only): if the repo disallows
-  auto-merge, do not fail. Keep watching; once checks are green, the review gate
-  is clear, and `mergeable == MERGEABLE`, run `gh pr merge <pr> --<merge_method>`
-  directly. This fallback lives inside the gated section above — with
-  `auto_merge=false` it never fires; the PR remains open awaiting a human.
+  auto-merge, do not fail. Keep watching; once checks are green, the arm gate
+  clears — a review context that proved work, not merely a green one — and
+  `mergeable == MERGEABLE`, run `gh pr merge <pr> --<merge_method>` directly.
+  A green review context that did no work does NOT clear the gate here either:
+  on a repo without auto-merge this fallback is the merge, so exempting it would
+  reinstate the whole defect one layer down. Under a vacuous context the merge
+  belongs to step (d), with its conditions and its report line, or to
+  `blocked:unreviewed`. This fallback lives inside the gated section above —
+  with `auto_merge=false` it never fires; the PR remains open awaiting a human.
 
 ## 2. The watch loop
 
@@ -224,11 +387,17 @@ review gate, and `mergeable == MERGEABLE`. Never enable auto-merge or merge
 directly in this mode.
 
 In **`on_blocker=report`** mode, only the mechanical step (a) and auto-merge enabling
-(when `auto_merge=true`) apply; for any of (b)–(f) do not act — classify the blocker
+(when `auto_merge=true` **and the arm gate cleared**) apply; for any of (b)–(f) do
+not act — classify the blocker
 and return per the input contract above. That includes (f): adjudicating a pending
 auto-fix PR (merging, closing, or deleting its branch) is destructive work, not
 diagnosis — return its classification (`blocked:pending-auto-fix`) instead.
 
+The arm gate binds in report mode too, and this is the mode where forgetting it
+does the most damage: a diagnose-only run that arms the latch has not diagnosed
+anything, it has authorised a merge. Under a vacuous review context, report mode
+neither arms nor takes step (d)'s exception — it returns `blocked:unreviewed`.
+
 ### a. Branch behind base (`mergeStateStatus == BEHIND`)
 Before proactively syncing a clean `BEHIND` PR, check whether the base branch
 actually requires up-to-date branches:
@@ -425,14 +594,37 @@ throttle, which is a billing matter no amount of driving will clear. It is a
 **substitution** obligation followed by a **reporting** obligation: something
 read the diff, and the report says what did.
 
-**Merging past a hollow review is permitted — but ONLY when that review is the
-sole gate still blocking the merge, and only after the substitute is posted.**
-Prove the hollow signal from the commit status API as above; a
-merely pending or queued check is not proof of anything and must keep polling. Once that signal is explicit,
-and with `auto_merge=true`, the PR already has auto-merge enabled (section 1), so
-leave the latch armed and merge directly with `gh pr merge <pr> --<merge_method>`
-(pass `--admin` only if branch protection lists the hollow context as
-required and refuses the plain merge). "Sole gate" means every one of these is
+**Merging past a vacuous review context is permitted — but ONLY when that
+context is the sole gate still blocking the merge, and only after the substitute
+is posted.** This is the *only* route by
+which a PR merges unreviewed: the arm gate (section 1) holds the latch off while
+the context is vacuous precisely so that this decision, with its conditions and
+its mandatory report line, is the one that merges. If you find yourself merging
+unreviewed anywhere else, that is the defect, not a shortcut.
+
+**Every vacuity mode qualifies, not just the rate limit.** A size-limit skip, the
+public-repository policy skip, and a bare `Review skipped` are the same vacuity
+wearing different strings; a rule keyed on `Review rate limited` alone would
+pass a repository's rate-limited merges while leaving every other mode
+unconsidered, and would look complete. Use the arm gate's classification — the
+prover's `violations[].kind` — rather than matching one vendor string here. That
+classification and the allowlist above answer the same question from two
+directions and must agree: the prover says whether the context did work, and the
+configured reviewed-when phrase says what "did work" looks like for this
+project.
+
+Prove the signal from the commit status API as above; a merely pending or queued
+check is not proof of anything and must keep polling. **A transient vacuity is not adjudicated here until the arm gate's
+single wait-and-re-request has been spent** (section 1): a rate limit has a
+window, and merging past one you never waited out is a choice you did not have
+to make. A standing vacuity has no window, so it arrives here immediately.
+
+Once the signal is explicit, merge directly with `gh pr merge <pr>
+--<merge_method>` (pass `--admin` only if branch protection lists the vacuous
+context as required and refuses the plain merge).
+**Do not arm the latch to accomplish this** — arming would hand the decision
+back to GitHub and lose the report, and under the arm gate (section 1) the
+latch is deliberately not armed in the first place. "Sole gate" means every one of these is
 already true at the moment you merge — verify each against the live poll, never
 from memory:
 
@@ -484,11 +676,32 @@ mode. Record the result as `MERGED — NOT REVIEWED (<context> "<observed
 description>"), local adversarial review substituted and posted` in the terminal
 report (section 4).
 
+When a condition does not hold and cannot be cleared, the terminal state is
+`blocked:unreviewed` (section 4), not a silent stop and never an arm-and-hope.
+
 ### e. Review gate stall (`reviewDecision == CHANGES_REQUESTED`)
 After the requested changes are addressed and threads resolved, the prior
 `CHANGES_REQUESTED` review still blocks — a later `COMMENTED` review does not clear
-it. Dismiss the stale (often bot) review where repo policy permits, else re-request
-review:
+it.
+
+**The discriminator between a stranded verdict and a live objection is the
+unresolved thread count, not `reviewDecision`.** The same vendor limit produces
+opposite failures, and the two signals diverge in BOTH directions: a green
+review context can sit on a review that read nothing (step d), and a
+`CHANGES_REQUESTED` can outlive every thread that justified it, because the
+verdict does not self-dismiss when a later head fixes the code. Measured: one
+pull request was blocked by two genuine unresolved threads, and two hours later
+still reported `CHANGES_REQUESTED` with ZERO unresolved. Neither signal is a
+proxy for the other, so read them separately:
+
+- unresolved threads > 0 → a live objection. Work it through the (d) cycle
+  first; the verdict is correct and dismissing it would be the bypass.
+- unresolved threads == 0 and `CHANGES_REQUESTED` at an earlier head → a
+  stranded verdict. It is safe to dismiss, and leaving it is what makes a PR sit
+  wedged looking abandoned.
+
+Never dismiss on `reviewDecision` alone. Dismiss the stale (often bot) review
+where repo policy permits, else re-request review:
 ```bash
 gh api -X PUT repos/<owner>/<repo>/pulls/<pr>/reviews/<review_id>/dismissals \
   -f message="Addressed; threads resolved." -f event=DISMISS
@@ -714,14 +927,25 @@ Loop until one of:
   (`gh pr view <pr> --json autoMergeRequest` shows `null`). Report the PR URL
   and state — a human decides whether it merges. This is the intended outcome
   of auto-merge-off mode, not a stall; do not keep looping for `MERGED`.
+- **`blocked:unreviewed`** — the PR is green and mergeable, but the review
+  context did no work and step (d)'s sole-gate conditions were not all met (or
+  the mode forbids acting on them: `on_blocker=report`). The latch is
+  deliberately not armed, so the PR sits OPEN rather than merging on a review
+  nothing performed. Report the PR URL, the review context's settled
+  description, whether it is transient or standing, and which sole-gate
+  condition failed. This is an outcome that needs an operator, stated in one
+  line a non-technical reader can act on — for example: *"PR #123 is ready to
+  merge but nobody reviewed it: the review tool says it skips public
+  repositories, and that will not change on its own. Merge it yourself or ask
+  for a human review."*
 - **`CLOSED`** → report (PR was closed without merge).
 - **Hard block needing a human**: an unresolvable conflict, a failing check that
   needs design input, or genuine unresolved human objection (not a bot gate). Stop
   and report exactly what is blocking and what was already tried — never force the
   merge or weaken a gate to get past it. The one sanctioned exception is a
-  hollow third-party review that is the *sole* remaining gate on an auto-merge
-  enabled PR, and only once the adversarial-review substitute is posted (step
-  d); it never extends to any other gate.
+  hollow third-party review that is the *sole* remaining gate, and only once the
+  adversarial-review substitute is posted (step d); it never extends to any
+  other gate.
 
 At every terminal state, release the babysitter lease
 (`gh pr edit <pr> --remove-label "lisa:babysitter-on-duty"`) so the CI
@@ -738,10 +962,18 @@ So state the verdict alongside the outcome:
 - `MERGED — NOT REVIEWED (<context> "Review rate limited"), local adversarial review substituted and posted`
 - `MERGED — NOT REVIEWED (<context> "<unrecognised description>"), local adversarial review substituted and posted`
 - `MERGED — no third-party reviewer configured; local review not substituted for one that was never declared`
+- `NOT MERGED — NOT REVIEWED: blocked:unreviewed, auto-merge deliberately not armed`
 
 Spell the reviewer as the configured context, not a vendor name: a project may
 declare none, one, or several, and each shows its own evidence.
 
-This is reporting, never a terminal state of its own. `NOT REVIEWED` does not
-turn a merged PR into a blocked one, and it must never be used to withhold a
-merge — it changes what the record says, not what the loop does.
+Quote the description that was actually read. A report that says "rate limited"
+on a policy skip is a wrong record, and the two call for different operator
+actions: one clears itself, the other never will.
+
+`NOT REVIEWED` is reporting, and on a merged PR it is never a terminal state of
+its own: it does not turn a merged PR into a blocked one. What it does gate is
+ARMING — section 1 will not hand GitHub a merge decision on a review that did no
+work, because an armed latch merges without ever writing this line. The
+distinction is exact: `NOT REVIEWED` never withholds a merge this skill decides
+to make, and it always withholds the merge this skill would have delegated.

package/plugins/lisa/.codex-plugin/skills/lisa-git-submit-pr/SKILL.md

@@ -14,7 +14,7 @@ Recognized optional hints:
 - `target_branch=<branch>` or `base=<branch>` — intended PR base branch.
 - `tracker_provider=<github|linear|jira|none>` — explicit provider when the ref shape is ambiguous.
 - `pr_url=<url>` — live pull request URL, only needed when updating tracker backlinks from an existing PR context.
-- `auto_merge=<true|false>` — whether the PR should merge automatically. Default `true` (existing behavior for every current caller). With `auto_merge=false`, skip step 5 entirely (never run `gh pr merge --auto`) and pass `auto_merge=false` through to the `drive-pr-to-merge` delegation in step 6 so the PR is driven to a clean, green, OPEN state and then left awaiting a human.
+- `auto_merge=<true|false>` — whether the PR should merge automatically. Default `true` (existing behavior for every current caller). This skill **never arms the latch itself** in either mode; it passes the value through to the `drive-pr-to-merge` delegation in step 6, which owns the arm decision. With `auto_merge=false` the PR is driven to a clean, green, OPEN state and then left awaiting a human.
 
 ## Workflow
 
@@ -35,10 +35,18 @@ Recognized optional hints:
    - Include native development linkage for the source work item when `work_item_ref` can be inferred from `$ARGUMENTS`, the current branch name, an existing PR body, or the issue/ticket context passed by the caller.
    - After the PR exists, ensure the source work item has a backlink to the PR: invoke `lisa-tracker-sync` with the work item, milestone `pr-ready`, the live `pr_url`, and `tracker_provider` when known. This makes ticket -> PR linkage mandatory, not just a best-effort milestone comment.
    - After the PR exists, re-resolve the live Pull Request node id and, when `github.projects.v2` is enabled, invoke `lisa-github-project-v2` with `operation: ensure-item` and `content_node_id: <pull-request-node-id>` so linked pull requests join the configured shared Project without replacing the PR as the durable review/merge surface.
-5. **Auto-merge** (only when `auto_merge=true`, the default — with `auto_merge=false` skip this step entirely): Choose merge strategy by PR type:
-   - **Promotion PRs** (env → env, e.g. `dev` → `staging`): use `gh pr merge --auto --merge` (never squash). Squashing flattens the constituent `chore(release): X.Y.Z [skip ci]` commits into one commit titled with the PR title, stripping the `[skip ci]` markers and breaking the release workflow's promotion-detection regex — the destination branch then double-bumps its version. `--merge` keeps each `chore(release)` commit (and its `[skip ci]` marker) intact under a clean merge commit subject the workflow can recognize.
-   - **Feature PRs** (anything → `dev`): use `gh pr merge --auto --merge`.
-6. **Drive to merge**: Opening the PR and enabling auto-merge is not terminal. Delegate the full mergeability loop to the `drive-pr-to-merge` skill — invoke it with the PR number and `merge_method=merge` (and `verify_commit=<pushed head sha>` for the ancestry check). When the caller passed `auto_merge=false`, also pass `auto_merge=false` so the delegated loop drives the PR to green-and-open (`awaiting-human`) instead of merged — never merging it, even on repos that disallow auto-merge. That skill is the single source of truth for clearing every blocker: auto-merge with direct-merge fallback, `BEHIND` re-sync, conflict resolution, failing-check fixes, human + bot (CodeRabbit) review-comment handling with GraphQL thread resolution, stale `CHANGES_REQUESTED` dismissal, and post-merge ancestry verification. It runs inline and uses plain `gh`/`git` so Claude and Codex behave identically. Do not re-implement the loop here.
+5. **Do not arm auto-merge here.** Never run `gh pr merge --auto` in this skill, in either `auto_merge` mode. Arming is delegated to `drive-pr-to-merge` (step 6), which is the only place that first checks whether the review context did any work.
+
+   **Why this step is a prohibition rather than a command.** It used to arm the latch unconditionally when `auto_merge=true`. At submit time no review exists yet — that is what "submit" means — so the latch went on before anything could have read the code, and GitHub then merged the PR the moment CI went green. `drive-pr-to-merge` carries a careful exception for merging past a review check that reported success without reviewing anything: five conditions verified against a live poll, and a mandatory `MERGED — NOT REVIEWED` line in the report. **That exception could never fire**, because the merge had already been authorised here (#3439). The merge happened on the latch, not on the reasoning.
+
+   Removing the arm from this step does not lose auto-merge: step 6 always delegates to `drive-pr-to-merge`, which arms as soon as the review context proves work, and adjudicates in the open when it does not. What is lost is the ability to authorise a merge before anything could have objected.
+
+   The merge strategy is still decided here and passed through, because it is a property of the PR rather than of the review:
+   - **Promotion PRs** (env → env, e.g. `dev` → `staging`): `merge_method=merge` (never squash). Squashing flattens the constituent `chore(release): X.Y.Z [skip ci]` commits into one commit titled with the PR title, stripping the `[skip ci]` markers and breaking the release workflow's promotion-detection regex — the destination branch then double-bumps its version. `--merge` keeps each `chore(release)` commit (and its `[skip ci]` marker) intact under a clean merge commit subject the workflow can recognize.
+   - **Feature PRs** (anything → `dev`): `merge_method=merge`.
+6. **Drive to merge**: Opening the PR is not terminal. Delegate the full mergeability loop to the `drive-pr-to-merge` skill — invoke it with the PR number and `merge_method=merge` (and `verify_commit=<pushed head sha>` for the ancestry check). When the caller passed `auto_merge=false`, also pass `auto_merge=false` so the delegated loop drives the PR to green-and-open (`awaiting-human`) instead of merged — never merging it, even on repos that disallow auto-merge. That skill is the single source of truth for clearing every blocker: the arm gate and auto-merge with direct-merge fallback, `BEHIND` re-sync, conflict resolution, failing-check fixes, human + bot (CodeRabbit) review-comment handling with GraphQL thread resolution, stale `CHANGES_REQUESTED` dismissal, and post-merge ancestry verification. It runs inline and uses plain `gh`/`git` so Claude and Codex behave identically. Do not re-implement the loop here.
+
+   This delegation is now load-bearing rather than a convenience: it is the only path that arms auto-merge, so skipping it leaves the PR open rather than quietly merging it. Reporting submission as complete without invoking it is a failed submit, not a partial one — say so instead of implying the PR is on its way to merged.
 
 ### Native Development Linkage