@bompus/house-rules 0.14.1 → 0.15.0

package/README.md

@@ -236,6 +236,7 @@ in name order, after the modifiers.
 | `backlog-outline`                                                                                                                                        | A backlog report adds a Markdown outline of every open item grouped by what it waits on; nothing is rendered, so it reads the same on every host.                                                                                                                     |
 | `backlog-visual`                                                                                                                                         | A backlog report adds one dark panel of every open item grouped by what it waits on, with a table for waiting items and one row per decision; hosts without a render tool get the same outline in Markdown.                                                           |
 | `coded-offers`                                                                                                                                           | Offers use numbered questions and coded options (`1A`, `1B`) so one short reply answers every decision.                                                                                                                                                               |
+| `compression-codecs`                                                                                                                                     | Prefer zstd, then brotli, then gzip for data you write, with browser negotiation, gzip exceptions and measured levels.                                                                                                                                                |
 | `cross-session-relay`                                                                                                                                    | Relayed work between sessions keeps its source and authorized scope, and an authorized push that changes inherited guidance or tooling is announced to the affected sessions.                                                                                         |
 | `effort-estimates`                                                                                                                                       | Options that differ in cost, or work that waits on CI, a build or a deploy, carry a wall-clock estimate based on comparable finished work. Estimates from workers, docs or other models are converted the same way or dropped.                                        |
 | `land-when-done`                                                                                                                                         | Authorized repository work is not finished until it is in the remote default branch.                                                                                                                                                                                  |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bompus/house-rules",
-  "version": "0.14.1",
+  "version": "0.15.0",
   "description": "Composable working rules and skills for AI coding agents",
   "homepage": "https://github.com/bompus/house-rules#readme",
   "license": "MIT",

package/rules/core.md

@@ -190,6 +190,8 @@ Transfer to another top-level conversation only at the user's direction, under a
 
 Keep independent repository edits on separate branches and isolated worktrees when a checkout may be shared. Leave other people's and sessions' edits alone.
 
+Before creating a branch or worktree, read the default branch of the repository the change will land in (`gh repo view <owner>/<repo> --json defaultBranchRef` or `git ls-remote --symref <remote> HEAD`), fetch it and base the work on its tip. That repository is your fork when the change lands there and upstream when a pull request targets upstream. A branch name shown by a tool or harness is not evidence of the default branch, which need not be `main`. If the repository's own guidance names another base, follow it and say so.
+
 Before creating an issue or pull request, search the target repository's open and closed issues and pull requests for the same change. Reuse or coordinate with a match; otherwise link related work and say how yours differs. If you cannot search, say so instead of claiming no matches.
 
 Before submitting a pull request to an external upstream project, review the
@@ -223,9 +225,11 @@ At task completion, unlanded or uncommitted task changes get one landing option,
 Before integration, updating a default checkout or deleting a landed branch, read
 [the landing procedure](references/landing.md).
 
-Leave alone a checkout another
-session or job uses, or whose use you cannot tell. Never merge, reset, stash or
-switch it to make it match the default.
+Never reset, stash, switch or merge-commit a checkout to make it match the default.
+A session or job running in it is not a reason to wait or ask. A checkout of the
+default branch that is strictly behind, with no uncommitted changes to tracked files, is fast-forwarded
+with `git merge --ff-only <sha>`. Leave a dirty, diverged or mid-operation one, report its path and reason,
+and do not ask the user.
 
 Before the first publish step of a version bump (tag, publish, release, announcement), review unreleased changelog entries and public materials (READMEs, charts, graphics with alt text, listing text, announcement) and fix what is stale first; an urgent release may limit only the materials to what it affects.
 
@@ -236,7 +240,7 @@ Remove a task worktree only when the default branch contains its work, its tree
 ## Coordination and isolation
 
 A coordination roster, where there is one, may omit sessions. Check checkout and
-branch ownership independently before treating them as free.
+branch ownership independently before treating them as free to edit or remove.
 
 Stop only processes you started, by the PID you recorded when starting them.
 Never kill by pattern (`pkill -f`, `pgrep | kill`, or a PID found by matching

package/rules/modifiers/compression-codecs.md

@@ -0,0 +1,55 @@
+---
+description: Prefer zstd, then brotli, then gzip for data you write, with browser negotiation, gzip exceptions and measured levels.
+after: Implementation economy
+---
+
+## Compression codecs
+
+When you choose how to compress data a project writes itself (logs, snapshots,
+caches, archives, API payloads), prefer zstd, then brotli, then gzip. Use the
+first codec in that order that every writer and reader of the data supports. A
+preference does not add a codec to a runtime. Node added `zlib.createZstdCompress`
+in 22.15.0 and 23.8.0 and marks it experimental as of Node 26. Check the version
+and the API before relying on it.
+
+These figures are single runs on Node. They use three 10.5 MB log files. Zstd at level 9
+compressed 10.0 to 13.2 times, brotli at 4 compressed 9.5 to 12.9 times and gzip at
+6 compressed 4.9 to 9.8 times. Compression took 9 to 14 ms at zstd 3, 24 to 33 ms
+at brotli 4 and 40 to 85 ms at gzip 6. The runs did not time zstd 9 or measure the
+ratio at zstd 3, so they do not show zstd winning on both size and speed at one level.
+
+On JSON payloads of 0.1 to 7 MB, also single runs, zstd 3 compressed 1.7 to 2.3
+times faster than brotli 4. Its output was 1% to 4% larger up to 1 MB and 19% larger
+at 7 MB. All of this comes from a few files in one project, not a general claim.
+
+Treat these levels as starting points and verify them on your data. Use zstd 3 on hot
+paths and zstd 9 for cold data kept at rest. Use brotli 4 for responses compressed on
+request and brotli 11 for static files compressed ahead of time. The runs above did not
+measure brotli 11.
+
+For HTTP responses to browsers, negotiate by `Accept-Encoding` instead of sending
+zstd to every client. Pick the first of zstd, brotli and gzip that the header accepts. A coding
+listed with `q=0` is not acceptable, so skip it. If none is acceptable, send the
+response uncompressed unless the header also rules out `identity`, as `identity;q=0` does.
+Then answer 406 Not Acceptable. Zstd content encoding needs Chrome 123, Edge 123
+or Firefox 126, or later. Safari takes its support from the operating system. It has
+zstd from Safari 26.3 on the 26.3 releases of iOS, iPadOS, visionOS and macOS Tahoe.
+Safari on older releases lacks it, and Can I use shows macOS Safari as only partial. Smaller output matters more on high-latency or slow links, where
+brotli can win despite slower compression.
+
+Keep gzip where another tool must read the file: `zcat`, tarballs, npm and release
+assets. WebSocket compression stays on `permessage-deflate`, the only extension
+browsers offer; IANA registers no zstd or brotli extension.
+
+Before choosing between codecs or changing a working one, measure on the real data.
+Use `hr-benchmarking`'s defaults: 3 runs per codec, and 2 more when the gap is within
+the run-to-run variation. The gain is output size for cold data and compression time
+for hot paths. The other measure is a constraint, and it must not get worse outside the
+run-to-run variation. Change a working codec only when the gain lies outside that
+variation. Converting existing data is outside a task unless the task asks
+for it.
+
+References: [Node zlib](https://nodejs.org/api/zlib.html),
+[MDN Content-Encoding](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/Content-Encoding),
+[WebKit features for Safari 26.3](https://webkit.org/blog/17798/webkit-features-for-safari-26-3/) and
+[Can I use zstd](https://caniuse.com/zstd).

package/rules/modifiers/squash-landing.md

@@ -13,10 +13,10 @@ When a review bot reviews pull requests, merge only after it finishes; fix or
 answer all findings, resolve threads, and read the full review body.
 
 During integration, never switch, reset, force-move or remove the session's
-checkout. Default-branch updates must meet the fast-forward and ownership
+checkout. Default-branch updates must meet the fast-forward
 conditions in § Landing. After the merge, fetch first; move off a landed branch
 only when its content is in the base and the tree is clean. When the base is
 checked out elsewhere, detach at the fetched base. Never merge, reset or stash
 to move the checkout. Leave app-managed checkouts for the app to retire.
-If the tree is dirty or ownership is uncertain, stop and record its owner.
+If the tree is dirty, leave the checkout where it is and record the merged commit, its path and the blocker; the landing stands.
 Update the task record and follow § Cleanup after each landing.

package/rules/modifiers/upstream-contributions.md

@@ -19,8 +19,10 @@ issues invite, such as performance fixes or a reported defect.
    request. A behavior change, or a project that asks for prior approval, starts
    with a comment or discussion, not a pull request. Count the underlying
    problems and split the submission when the guide asks for one per request.
-3. Meet § Repository work first: the search for existing reports, the review of
-   the diff, the relevant checks, and the project's template and disclosure ask.
+3. Meet § Repository work first. Base the work on the default branch of the
+   repository the pull request targets. Search for existing reports, review the
+   diff, run the relevant checks, and follow the project's template and
+   disclosure ask.
 4. Show the user the exact text and channel once before posting. Posting is
    public and cannot be undone; this rule makes submitting the expected next
    step, not a waiver of that look. Only a user instruction naming the kind of

package/rules/references/landing.md

@@ -9,25 +9,34 @@ recommended option includes it, is that direction.
 
 At task completion, unlanded or uncommitted task changes get one landing option, `Land PR #<n>` or `Commit and land <change>`, never a bare done; only an explicit user deferral (recorded with branch, commits and reason) leaves it out. The option covers this section and § Cleanup, merge included; name only departures from that. Land through the repository's required path without bypassing checks. Landing is done when a fresh fetch shows the change in the default branch.
 
-Leave alone a checkout another
-session or job uses, or whose use you cannot tell. Never merge, reset, stash or
-switch it to make it match the default.
+Never reset, stash, switch or merge-commit a checkout to make it match the default.
+A session or job running in it is not a reason to wait or ask. A checkout of the
+default branch that is strictly behind, with no uncommitted changes to tracked files, is fast-forwarded
+with `git merge --ff-only <sha>`. Leave a dirty, diverged or mid-operation one, report its path and reason,
+and do not ask the user.
+Landing never waits on a local checkout, and a roster entry in one is not an input either: the
+checkout's own state decides whether it can be fast-forwarded (below). Removing a worktree is
+different; § Cleanup still waits on use.
 
 After integration:
 
-- Fetch, then bring the local default branch current. When it is clean,
-  strictly behind and not checked out elsewhere, fast-forward it. When another
-  worktree has it checked out and you know no session or running job is using
-  that worktree (your own main checkout, for example), run
-  `git merge --ff-only <sha>` there with the remote head you just fetched and
-  verified; unrelated uncommitted files may stay. Avoid `git pull` there: a
-  fetch by another process can rewrite the shared `FETCH_HEAD` mid-pull and
-  fail it with "Cannot fast-forward to multiple branches". When you cannot
-  tell, treat it as in use. Confirm the local and fetched remote heads match.
-- If the default branch is diverged, on another branch, in use, or the merge
-  refuses because local edits would be overwritten, leave it and report its
-  path and the blocker. Never merge, reset, stash or switch branches to make it
-  match, and never update other sessions' worktrees or separate clones.
+- Fetch, then bring the local default branch current, whoever else has it open.
+  When no checkout has it, fast-forward the branch ref. When one checkout has it
+  (your own, the primary or another linked worktree), run `git merge --ff-only <sha>`
+  there with the remote head you just fetched and verified, provided that checkout
+  is on the default branch, has no uncommitted changes to tracked files and no
+  unfinished Git operation (merge, rebase, cherry-pick, revert, bisect), and is
+  strictly behind. Read that state right before the merge. Untracked files may
+  stay, and Git refuses a merge that would overwrite one. Avoid `git pull` there: a fetch by another process can rewrite the shared
+  `FETCH_HEAD` mid-pull and fail it with "Cannot fast-forward to multiple
+  branches". Confirm the local and fetched remote heads match.
+- If that checkout is dirty, diverged, mid-operation or no longer on the default
+  branch, or the merge refuses because local edits would be overwritten, leave it
+  and write down its path and the reason as a pending local sync. The landing
+  stands, so finish the task and do not ask the user to confirm or wait for the
+  checkout to go idle. Never merge, reset, stash or switch branches to make it
+  match, and never touch a separate clone or a worktree that does not hold the
+  default branch.
 - Delete the merged remote branch when it is this task's own branch
   (`git push origin --delete <branch>` when the merge did not); § Cleanup
   covers branches others may rely on. Before merging a pull request that another open pull

package/rules/references/squash-landing.md

@@ -26,8 +26,9 @@ During integration, never switch, reset or remove the session's own checkout: no
 `checkout` or `switch` to another ref, no `reset` or branch force-move, and no
 `worktree remove` on it. Updating the default branch it has checked out
 (`merge --squash`, or `merge --ff-only` to the fetched remote head after a remote merge)
-under the fast-forward conditions in § Landing is expected; report other paths
-to their owners.
+under the fast-forward conditions in § Landing is expected, and so is fast-forwarding
+the one other checkout that holds the default branch. Report a checkout that cannot be
+fast-forwarded with its path and reason.
 
 After the merge, do not leave the session's own checkout on a landed branch.
 Fetch first, then:
@@ -41,8 +42,8 @@ Fetch first, then:
   commits.
 - When an app manages the checkout, leave it for the app to retire. Report it;
   it is not a blocker.
-- When the tree is dirty or ownership is in doubt, stop: record the
-  merged commit, the checkout path and the owner wherever you track the task.
+- When the tree is dirty, leave the checkout where it is and record the merged
+  commit, the checkout path and the blocker. The landing stands.
 
 After each landing, update the task list and any active handoff with the
 commit, the verification result and the remaining work, then retire the task

package/skills/hr-pr-followup/references/review-helpers.md

@@ -108,18 +108,38 @@ It does not clear that gate's review-body findings or change the landing workflo
 Three scripts in `scripts/` implement the landing steps § Landing describes. They never
 reset, switch or delete a checkout.
 
-- `merge-pr.sh <pr> [--merge] [--remote <name>] [--idle-primary <path>]` squash-merges
+- `merge-pr.sh <pr> [--merge] [--remote <name>]` squash-merges
   (or merge-commits) an open pull request and deletes its remote head without
   `gh pr merge --delete-branch`, which removes other sessions' linked worktrees. It
   refuses while review feedback is open (`check-pr-review.ts`), while another open pull
   request targets the head, and for a repository listed in `HR_PUSH_LANDED`
   (space-separated `owner/repo`; those land by fast-forward push, which it prints). The
   merge passes `--match-head-commit`. It lists worktrees still on the merged branch so
-  their owners clean up.
-- `verify-landed.sh --commit <sha> [--ff [--idle-primary <path>]]` fetches, checks that
-  the default branch contains the commit, and checks the local default; `--ff`
-  fast-forwards a clean default checkout. `--preflight --ff` checks eligibility before
-  landing. After a blocked check, rerun this script, not `merge-pr.sh`.
+  their owners clean up. The merge never waits on a local checkout; the local default is
+  synchronized afterwards as `verify-landed.sh` describes.
+- `verify-landed.sh --commit <sha> [--ff]` fetches, checks that the default branch
+  contains the commit, and checks the local default. `--ff` brings the local default
+  current: it moves the branch ref when no checkout has it, and runs
+  `merge --ff-only <sha>` in the one checkout that has it when that checkout is on the
+  default branch, free of uncommitted changes to tracked files and of an unfinished Git
+  operation, and strictly behind. Untracked files may stay; Git refuses a fast-forward
+  that would overwrite one. Sessions,
+  processes and roster entries are never inputs. Any other checkout is left alone and
+  reported on one line, `sync skipped at <path>: <reason>`, with a reason of
+  `working tree dirty` (tracked changes), `diverged from <remote>/<default>`, `on branch
+<name>, not <default>`, `unfinished Git operation: <name>`, `fast-forward refused: <why>`,
+  `cannot inspect Git state` or `cannot inspect working tree`.
+  Exit 0 means landed and current; 1 is a failure; 2 is usage; 3 means landed with a local
+  sync pending, which is not a failed landing and needs no question to the user: record
+  the path and reason in the task plan. Both scripts use these exit codes. After a
+  failure, rerun this script, not `merge-pr.sh`. Both scripts accept the old
+  `--idle-primary <path>` flag and ignore it with a note. It takes the next argument as its path unless that
+  argument is missing or starts with `-`. `verify-landed.sh` also accepts `--preflight`. Without
+  `--commit` and `--branch`, it prints a note and `preflight skipped: it no longer gates landing`, checks
+  nothing and exits 0. With either one it exits 2. `merge-pr.sh` rejects `--preflight` with exit 2. Both
+  flags will be removed.
 - `check-landing.py [--path <checkout>] [--base <ref>]` reports whether a checkout's
   work is in the base branch by content, so squash-merged branches count as landed, and
-  lists live processes whose working directory is inside the checkout (Linux only).
+  lists live processes whose working directory is inside the checkout (Linux only). That
+  list is a blocker for removing the worktree only. Landing and syncing the default
+  checkout never read it.

package/skills/hr-pr-followup/scripts/check-landing.py

@@ -8,7 +8,8 @@ the base. Read-only; never fetches — the caller fetches first.
 
 It also lists live processes whose working directory is inside the checkout
 (Linux /proc only), excluding the checker's ancestors and its pipeline. Each listed process
-blocks worktree removal unless its PID is one you recorded when you started it. `own_session`
+blocks worktree removal unless its PID is one you recorded when you started it. The list says nothing
+about landing or about fast-forwarding a default checkout: neither reads it. `own_session`
 is true only for a process that descends from the nearest agent CLI above the checker (a
 process whose comm is one of AGENT_COMMS); a process under another session of the same agent
 host's server, or any process when the checker has no agent ancestor, is false. A process

package/skills/hr-pr-followup/scripts/merge-pr.sh

@@ -15,25 +15,26 @@
 # empty by default): its own guidance lands by fast-forwarding the base to the head, because a GitHub
 # merge writes the account's profile name into public history. It prints that push instead.
 #
-# Before merging, verifies that the local default can be synchronized, even if it is current.
-# Refuses a dirty/diverged target or a default held in another checkout without --idle-primary.
-# After merging, fast-forwards the confirmed local default and fails if it is still stale.
-# To update the primary checkout from a task worktree, pass --idle-primary <path>
-# using existing ownership evidence or the operator's standing idle direction, unless current
-# evidence contradicts it; keep it idle through landing.
-# If verification
-# fails after "merged", rerun verify-landed.sh with the printed commit, not this script.
+# Landing never waits on a local checkout. After the merge it fast-forwards the checkout that holds
+# the default branch when that checkout is on the default branch, clean, free of an unfinished Git
+# operation and strictly behind (verify-landed.sh), whoever else has it open. Otherwise it leaves the
+# checkout alone, prints `sync skipped at <path>: <reason>` and exits 3: landed, local sync pending.
+# Record the path and reason in the task plan; nothing needs the user. If verification fails after
+# "merged" (exit 1), rerun verify-landed.sh with the printed commit, not this script.
 #
 # --merge lands with a merge commit instead of a squash. Use it only for a PR whose second parent
 # must stay in history, such as an `-s ours` merge that records an upstream reconcile; a squash
 # would drop that parent. Every other PR is squashed.
 #
-# Usage: bash scripts/merge-pr.sh <pr> [--merge] [--remote <name>] [--idle-primary <path>]
+# Exit status: 0 landed and every local default current; 1 refused or failed; 2 usage; 3 landed, local sync pending.
+# --idle-primary <path> is deprecated: accepted and ignored with a note on stderr, removed in a later release.
+#
+# Usage: bash scripts/merge-pr.sh <pr> [--merge] [--remote <name>]
 set -euo pipefail
 
 PUSH_LANDED=" ${HR_PUSH_LANDED:-} "
 
-PR="${1:?usage: merge-pr.sh <pr> [--merge] [--remote <name>] [--idle-primary <path>]}"
+PR="${1:?usage: merge-pr.sh <pr> [--merge] [--remote <name>]}"
 shift
 REMOTE=origin
 STRATEGY=--squash
@@ -42,7 +43,9 @@ while [ $# -gt 0 ]; do
   case "$1" in
     --merge) STRATEGY=--merge; shift;;
     --remote) REMOTE="${2:?}"; shift 2;;
-    --idle-primary) SYNC_ARGS+=(--idle-primary "${2:?}"); shift 2;;
+    --idle-primary)
+      echo "note: --idle-primary is ignored; the checkout holding the default branch is fast-forwarded when it is clean and strictly behind. The flag will be removed in a later release." >&2
+      shift; case "${1:-}" in ''|-*) ;; *) shift;; esac;;
     *) echo "unknown argument: $1" >&2; exit 2;;
   esac
 done
@@ -67,9 +70,6 @@ if [[ "$PUSH_LANDED" == *" $REPO "* ]]; then
   exit 1
 fi
 
-bash "$(dirname "${BASH_SOURCE[0]}")/verify-landed.sh" --preflight \
-  --default "$BASE" --remote "$REMOTE" "${SYNC_ARGS[@]}"
-
 gh pr merge "$PR" "$STRATEGY" --match-head-commit "$OID"
 SHA="$(gh pr view "$PR" --json mergeCommit --jq '.mergeCommit.oid // empty')"
 if ! [[ "$SHA" =~ ^([0-9a-f]{40}|[0-9a-f]{64})$ ]]; then
@@ -91,10 +91,13 @@ if [ "$FORK" != true ]; then
   fi
 fi
 
+# Exit 3 (local sync pending) is not a failure: finish the worktree report, then pass it on.
+STATUS=0
 bash "$(dirname "${BASH_SOURCE[0]}")/verify-landed.sh" --commit "$SHA" --branch "$HEAD" \
-  --default "$BASE" --remote "$REMOTE" "${SYNC_ARGS[@]}"
+  --default "$BASE" --remote "$REMOTE" "${SYNC_ARGS[@]}" || STATUS=$?
 
 git worktree list --porcelain | awk -v want="branch refs/heads/$HEAD" '
   /^worktree / { path = substr($0, 10) }
   $0 == want { print "still on " substr(want, 19) ": " path " (its owner retires it)" }
 '
+exit "$STATUS"

package/skills/hr-pr-followup/scripts/verify-landed.sh

@@ -2,25 +2,35 @@
 # Post-merge landing checks: containment, local-default state, leftover remote branches.
 # Fetches and verifies both remote containment and local-default equality. A stale local default
 # fails even when the remote contains the commit. Never resets, switches or deletes.
-# With --ff it updates a default checked out nowhere or here with a clean tree.
-# --idle-primary <path> additionally permits a fast-forward of this repository's primary checkout:
-# use existing ownership evidence or the operator's standing idle direction, unless current
-# evidence contradicts it. Git preserves
-# unrelated local edits and refuses a fast-forward that would overwrite them. It moves the
-# primary to the verified remote commit with `merge --ff-only <sha>` rather than `pull`, because
+#
+# With --ff it brings the local default branch current, whoever else has that checkout open. Which
+# processes, sessions or roster entries sit in a checkout is never an input. The branch moves when
+# it is checked out nowhere (a ref update), or when the one checkout that holds it is on the default
+# branch, free of uncommitted changes to tracked files and of an unfinished Git operation, and
+# strictly behind: then
+# `merge --ff-only <sha>` runs there. It uses the verified remote commit rather than `pull`, because
 # `pull` re-fetches into the shared FETCH_HEAD, which a concurrent fetch in the same checkout can
-# overwrite ("Cannot fast-forward to multiple branches"). Other linked worktrees
-# remain their owners' responsibility. After a blocked post-merge check, rerun this script,
-# not merge-pr.sh: the PR is already merged.
-# --preflight checks synchronization eligibility before landing, without moving local branches.
-# It requires --ff and rejects dirty or diverged targets and unconfirmed checkout ownership,
-# even when the local default is current. The caller must keep the target idle until landing
-# finishes; this check cannot establish session ownership or prevent another process starting.
+# overwrite ("Cannot fast-forward to multiple branches"). Untracked files may stay: Git keeps them
+# and refuses a fast-forward that would overwrite one.
+#
+# A checkout that fails any of those conditions is left alone and reported on one line:
+#   sync skipped at <path>: <reason>
+# with a reason of "working tree dirty" (tracked changes), "diverged from <remote>/<default>", "on
+# branch <name>, not <default>", "unfinished Git operation: <name>", "fast-forward refused: <why>",
+# "cannot inspect Git state" or "cannot inspect working tree". A diverged default that no checkout
+# holds is reported at refs/heads/<default>. The landing itself stands; record the path and reason
+# where you track the task and do not ask the user.
+#
+# Exit status: 0 landed and every local default current; 1 a real failure (commit not contained,
+# stale default with nothing skipped, leftover remote branch, fetch failure); 2 usage; 3 landed and
+# verified, but a local checkout was skipped (local sync pending). After a failure, rerun this
+# script, not merge-pr.sh: the PR is already merged.
+#
+# Deprecated, accepted and ignored with a note on stderr, and removed in a later release:
+# --idle-primary <path> and --preflight. Landing no longer waits on any local checkout.
 # Usage:
 #   bash scripts/verify-landed.sh --commit <sha> [--default <branch>]
-#     [--branch <merged-head>] [--remote <name>] [--ff [--idle-primary <path>]]
-#   bash scripts/verify-landed.sh --preflight --ff [--default <branch>]
-#     [--remote <name>] [--idle-primary <path>]
+#     [--branch <merged-head>] [--remote <name>] [--ff]
 set -euo pipefail
 
 REMOTE=origin
@@ -28,8 +38,7 @@ DEFAULT=""
 COMMIT=""
 BRANCH=""
 FF=0
-IDLE_PRIMARY=""
-PREFLIGHT=0
+LEGACY_PREFLIGHT=0
 
 while [ $# -gt 0 ]; do
   case "$1" in
@@ -38,24 +47,22 @@ while [ $# -gt 0 ]; do
     --branch) BRANCH="${2:?}"; shift 2;;
     --remote) REMOTE="${2:?}"; shift 2;;
     --ff) FF=1; shift;;
-    --idle-primary) IDLE_PRIMARY="${2:?}"; shift 2;;
-    --preflight) PREFLIGHT=1; shift;;
+    --idle-primary)
+      echo "note: --idle-primary is ignored; the checkout holding the default branch is fast-forwarded when it is clean and strictly behind. The flag will be removed in a later release." >&2
+      shift; case "${1:-}" in ''|-*) ;; *) shift;; esac;;
+    --preflight)
+      LEGACY_PREFLIGHT=1
+      echo "note: --preflight is ignored; landing no longer waits on local checkouts. The flag will be removed in a later release." >&2
+      shift;;
     *) echo "unknown argument: $1" >&2; exit 2;;
   esac
 done
-if [ "$PREFLIGHT" = 1 ]; then
-  [ "$FF" = 1 ] && [ -z "$COMMIT$BRANCH" ] \
-    || { echo "--preflight requires --ff and excludes --commit/--branch" >&2; exit 2; }
-else
-  [ -n "$COMMIT" ] || { echo "missing --commit <sha>" >&2; exit 2; }
-fi
-if [ -n "$IDLE_PRIMARY" ]; then
-  [ "$FF" = 1 ] || { echo "--idle-primary requires --ff" >&2; exit 2; }
-  PRIMARY="$(git worktree list --porcelain | sed -n '1s/^worktree //p')"
-  IDLE_PRIMARY="$(git -C "$IDLE_PRIMARY" rev-parse --show-toplevel)"
-  [ "$IDLE_PRIMARY" = "$PRIMARY" ] \
-    || { echo "--idle-primary is not this repository's primary checkout: $IDLE_PRIMARY" >&2; exit 2; }
+if [ "$LEGACY_PREFLIGHT" = 1 ]; then
+  [ -z "$COMMIT$BRANCH" ] || { echo "--preflight excludes --commit/--branch" >&2; exit 2; }
+  echo "preflight skipped: it no longer gates landing"
+  exit 0
 fi
+[ -n "$COMMIT" ] || { echo "missing --commit <sha>" >&2; exit 2; }
 
 if [ -z "$DEFAULT" ]; then
   # The remote's own answer wins; the cached origin/HEAD goes stale when the default branch changes.
@@ -76,48 +83,64 @@ HOLDER="$(printf '%s\n' "$WTLS" | awk -v want="branch refs/heads/$DEFAULT" '
 ')"
 HERE="$(git rev-parse --show-toplevel)"
 
-if [ "$PREFLIGHT" = 1 ]; then
-  # A rebase or bisect detaches HEAD while still reserving its original branch.
-  if [ -z "$HOLDER" ]; then
-    while IFS= read -r RECORD; do
-      case "$RECORD" in worktree\ *) CHECKOUT="${RECORD#worktree }";; *) continue;; esac
-      [ -d "$CHECKOUT" ] || continue
-      for ASSOCIATION in rebase-merge/head-name rebase-apply/head-name BISECT_START; do
-        ASSOCIATION_PATH="$(git -C "$CHECKOUT" rev-parse --path-format=absolute --git-path "$ASSOCIATION")"
-        if [ -f "$ASSOCIATION_PATH" ]; then
-          IFS= read -r ASSOCIATED_BRANCH < "$ASSOCIATION_PATH"
-          if [ "$ASSOCIATED_BRANCH" = "refs/heads/$DEFAULT" ] || [ "$ASSOCIATED_BRANCH" = "$DEFAULT" ]; then
-            HOLDER="$CHECKOUT"
-            break 2
-          fi
+# A rebase or bisect detaches HEAD while still reserving its original branch.
+if [ -z "$HOLDER" ]; then
+  while IFS= read -r RECORD; do
+    case "$RECORD" in worktree\ *) CHECKOUT="${RECORD#worktree }";; *) continue;; esac
+    [ -d "$CHECKOUT" ] || continue
+    for ASSOCIATION in rebase-merge/head-name rebase-apply/head-name BISECT_START; do
+      # A checkout whose state cannot be read counts as holding the branch: holder_blocker then skips it.
+      ASSOCIATION_PATH="$(git -C "$CHECKOUT" rev-parse --path-format=absolute --git-path "$ASSOCIATION" 2>/dev/null)" || {
+        HOLDER="$CHECKOUT"
+        break 2
+      }
+      if [ -f "$ASSOCIATION_PATH" ]; then
+        ASSOCIATED_BRANCH=""
+        if ! { IFS= read -r ASSOCIATED_BRANCH < "$ASSOCIATION_PATH" || [ -n "$ASSOCIATED_BRANCH" ]; } 2>/dev/null; then
+          HOLDER="$CHECKOUT"
+          break 2
         fi
-      done
-    done <<< "$WTLS"
-  fi
-  if [ -n "$HOLDER" ]; then
-    if [ "$HOLDER" != "$HERE" ] && [ "$HOLDER" != "$IDLE_PRIMARY" ]; then
-      echo "sync blocked at $HOLDER: that checkout has the default branch. If nothing is using it, rerun with --idle-primary <primary-path>" >&2
-      exit 1
-    fi
-    STATUS="$(git -C "$HOLDER" status --porcelain)" \
-      || { echo "sync blocked at $HOLDER: cannot inspect working tree" >&2; exit 1; }
-    [ -z "$STATUS" ] \
-      || { echo "sync blocked at $HOLDER: working tree dirty; leave it for its owner" >&2; exit 1; }
-    for OPERATION in MERGE_HEAD CHERRY_PICK_HEAD REVERT_HEAD rebase-merge rebase-apply sequencer BISECT_START; do
-      OPERATION_PATH="$(git -C "$HOLDER" rev-parse --path-format=absolute --git-path "$OPERATION")"
-      [ ! -e "$OPERATION_PATH" ] \
-        || { echo "sync blocked at $HOLDER: unfinished Git operation: $OPERATION" >&2; exit 1; }
+        if [ "$ASSOCIATED_BRANCH" = "refs/heads/$DEFAULT" ] || [ "$ASSOCIATED_BRANCH" = "$DEFAULT" ]; then
+          HOLDER="$CHECKOUT"
+          break 2
+        fi
+      fi
     done
-  fi
-  if git show-ref --verify --quiet "refs/heads/$DEFAULT"; then
-    git merge-base --is-ancestor "$DEFAULT" "$REMOTE/$DEFAULT" \
-      || { echo "sync blocked: $DEFAULT cannot fast-forward to $REMOTE/$DEFAULT" >&2; exit 1; }
-  fi
-  echo "synchronization preflight passed: $DEFAULT (${HOLDER:-not checked out})"
-  exit 0
+  done <<< "$WTLS"
 fi
 
 FAIL=0
+SKIPPED=0
+
+skip() {
+  echo "sync skipped at $1: $2"
+  SKIPPED=1
+}
+
+# Prints why a checkout cannot be fast-forwarded now, or nothing when it can.
+holder_blocker() {
+  local path="$1" operation operation_path branch status
+  for operation in MERGE_HEAD CHERRY_PICK_HEAD REVERT_HEAD rebase-merge rebase-apply sequencer BISECT_START; do
+    operation_path="$(git -C "$path" rev-parse --path-format=absolute --git-path "$operation" 2>/dev/null)" \
+      || { echo "cannot inspect Git state"; return; }
+    if [ -e "$operation_path" ]; then
+      echo "unfinished Git operation: $operation"
+      return
+    fi
+  done
+  branch="$(git -C "$path" symbolic-ref --quiet HEAD 2>/dev/null || true)"
+  if [ "$branch" != "refs/heads/$DEFAULT" ]; then
+    if [ -n "$branch" ]; then
+      echo "on branch ${branch#refs/heads/}, not $DEFAULT"
+    else
+      echo "on branch (detached HEAD), not $DEFAULT"
+    fi
+    return
+  fi
+  # Untracked files may stay: Git itself refuses a fast-forward that would overwrite one.
+  status="$(git -C "$path" status --porcelain --untracked-files=no 2>/dev/null)" || { echo "cannot inspect working tree"; return; }
+  [ -z "$status" ] || echo "working tree dirty"
+}
 
 if git merge-base --is-ancestor "$COMMIT" "$REMOTE/$DEFAULT" 2>/dev/null; then
   echo "contained: $COMMIT in $REMOTE/$DEFAULT"
@@ -133,35 +156,45 @@ if git show-ref --verify --quiet "refs/heads/$DEFAULT"; then
     echo "local $DEFAULT: current ($LOCAL)"
   elif git merge-base --is-ancestor "$LOCAL" "$UPSTREAM" 2>/dev/null; then
     BEHIND="$(git rev-list --count "$LOCAL..$UPSTREAM")"
-    if [ -z "${HOLDER:-}" ]; then
-      if [ "$FF" = 1 ] && [ "$FAIL" = 0 ]; then
-        git update-ref -m "verify-landed: fast-forward $DEFAULT" "refs/heads/$DEFAULT" "$UPSTREAM" "$LOCAL"
-        echo "local $DEFAULT: fast-forwarded $BEHIND commit(s) to $UPSTREAM (not checked out anywhere)"
+    if [ "$FF" != 1 ] || [ "$FAIL" != 0 ]; then
+      WHY="not updated without --ff"
+      [ "$FF" != 1 ] || WHY="not updated: the landing check failed"
+      if [ -z "$HOLDER" ]; then
+        if [ "$FF" != 1 ]; then
+          echo "local $DEFAULT: $BEHIND behind, not checked out anywhere. Safe: git fetch $REMOTE $DEFAULT:$DEFAULT"
+        else
+          echo "local $DEFAULT: $BEHIND behind, not checked out anywhere; $WHY"
+        fi
       else
-        echo "local $DEFAULT: $BEHIND behind, not checked out anywhere — safe: git fetch $REMOTE $DEFAULT:$DEFAULT"
+        echo "local $DEFAULT: $BEHIND behind, checked out at $HOLDER; $WHY"
       fi
-    elif [ "$HOLDER" != "$HERE" ]; then
-      if [ "$FF" = 1 ] && [ "$FAIL" = 0 ] && [ "$HOLDER" = "$IDLE_PRIMARY" ]; then
-        [ "$(git -C "$HOLDER" symbolic-ref --quiet --short HEAD)" = "$DEFAULT" ] \
-          || { echo "primary checkout changed branches; refusing update" >&2; exit 1; }
-        git -C "$HOLDER" merge --quiet --ff-only "$UPSTREAM"
-        echo "local $DEFAULT: fast-forwarded $BEHIND commit(s) in confirmed idle primary $HOLDER"
+    elif [ -z "$HOLDER" ]; then
+      if REF_ERR="$(git update-ref -m "verify-landed: fast-forward $DEFAULT" "refs/heads/$DEFAULT" "$UPSTREAM" "$LOCAL" 2>&1)"; then
+        echo "local $DEFAULT: fast-forwarded $BEHIND commit(s) to $UPSTREAM (not checked out anywhere)"
       else
-        echo "local $DEFAULT: $BEHIND behind, checked out at $HOLDER (not here) — leave for its owner; if you know it is idle: git -C $HOLDER merge --ff-only $UPSTREAM"
-        echo "If nothing is using that checkout, rerun verify-landed.sh with --ff --idle-primary <primary-path>." >&2
+        skip "refs/heads/$DEFAULT" "fast-forward refused: $(printf '%s' "$REF_ERR" | head -n 1)"
       fi
-    elif [ -n "$(git status --porcelain)" ]; then
-      echo "local $DEFAULT: $BEHIND behind but working tree dirty — report, do not touch"
-    elif [ "$FF" = 1 ] && [ "$FAIL" = 0 ]; then
-      git merge --quiet --ff-only "$UPSTREAM"
-      echo "local $DEFAULT: fast-forwarded $BEHIND commit(s) to $UPSTREAM (checked out here)"
     else
-      echo "local $DEFAULT: $BEHIND behind, clean, checked out here — safe to fast-forward"
+      # The state is read right before the merge; Git refuses it if edits would be overwritten.
+      REASON="$(holder_blocker "$HOLDER")"
+      if [ -n "$REASON" ]; then
+        skip "$HOLDER" "$REASON"
+      elif MERGE_ERR="$(git -C "$HOLDER" merge --quiet --ff-only "$UPSTREAM" 2>&1)"; then
+        if [ "$HOLDER" = "$HERE" ]; then
+          echo "local $DEFAULT: fast-forwarded $BEHIND commit(s) to $UPSTREAM (checked out here)"
+        else
+          echo "local $DEFAULT: fast-forwarded $BEHIND commit(s) to $UPSTREAM in $HOLDER"
+        fi
+      elif printf '%s' "$MERGE_ERR" | grep -q "would be overwritten"; then
+        skip "$HOLDER" "fast-forward refused: local edits would be overwritten"
+      else
+        skip "$HOLDER" "fast-forward refused: $(printf '%s' "$MERGE_ERR" | head -n 1)"
+      fi
     fi
   else
-    echo "local $DEFAULT: diverged from $REMOTE/$DEFAULT — report, do not touch"
+    skip "${HOLDER:-refs/heads/$DEFAULT}" "diverged from $REMOTE/$DEFAULT"
   fi
-  if [ "$(git rev-parse "$DEFAULT")" != "$(git rev-parse "$REMOTE/$DEFAULT")" ]; then
+  if [ "$(git rev-parse "$DEFAULT")" != "$(git rev-parse "$REMOTE/$DEFAULT")" ] && [ "$SKIPPED" = 0 ]; then
     echo "LOCAL DEFAULT NOT CURRENT: $DEFAULT differs from $REMOTE/$DEFAULT; landing incomplete" >&2
     FAIL=1
   fi
@@ -181,4 +214,11 @@ if [ -n "$BRANCH" ]; then
   fi
 fi
 
-exit "$FAIL"
+if [ "$FAIL" != 0 ]; then
+  exit 1
+fi
+if [ "$SKIPPED" = 1 ]; then
+  echo "landed; local sync pending (exit 3): record the path and reason above in the task plan"
+  exit 3
+fi
+exit 0