@event4u/agent-config 16.3.0 → 16.5.0

package/dist/agent-src/skills/frontend-render-security/SKILL.md

@@ -51,6 +51,7 @@ NO SECRET, PRIVILEGED KEY, OR SESSION TOKEN LIVES IN CLIENT CODE OR localStorage
 | `eval` / `new Function` / string-`setTimeout` on input | Eval injection / RCE (CWE-95) | a parser or explicit allow-list |
 | `target="_blank"` without `rel="noopener"` | Reverse tabnabbing (CWE-1022) | add `rel="noopener noreferrer"` |
 | Missing CSP; missing alt/label/contrast | No XSS second line of defense; a11y failures | strict CSP (no `unsafe-inline`); alt text, labels, AA contrast |
+| Untrusted SVG markup into an HTML sink — `innerHTML` / `v-html` / `dangerouslySetInnerHTML`, or inlined server-side | An inlined SVG is live DOM, not an image: `on*` event attributes, `<script>`, `foreignObject`, a `javascript:` href and external references all execute, and a DOCTYPE with entities reads local files (CWE-79, CWE-611) | sanitize with an SVG profile chosen for the **delivery context** — inline DOM runs script and handlers in the host origin; a standalone `.svg` opened directly runs them in its own; `<img>` and CSS `background-image` run no script and load no external reference — or deliver through `<img>`, with CSP as the second line. Uploads are `threat-modeling`'s `data/threats.csv:9`, not this row |
 
 ## The server-composed bootstrap payload
 
@@ -108,6 +109,14 @@ rg -n "origin:\s*['\"]\*['\"]|Access-Control-Allow-Origin.*\*"
 rg -n "addEventListener\(\s*['\"]message['\"]"   # then confirm each checks event.origin
 # Unhardened external links
 rg -n 'target=["'\'']_blank["'\'']'   # then confirm rel="noopener" present
+# SVG active content — markup that executes once the SVG is inlined.
+# Scoped to *.svg, where an on* attribute is always a defect. In .jsx/.tsx an
+# on* attribute is ordinary React and matching it there would bury the signal;
+# an on* on INLINE svg inside a host document is DQ4's case, not this grep's.
+# <script is listed because the row above names it and the pattern did not.
+# A locator, not a verdict: entity-encoded or tab-split javascript:, <svg:script>
+# and SMIL writes into href get past it. `lint_svg_asset` (svg-authoring) decodes them.
+rg -n '<foreignObject|<script[\s>]|\son[a-z]+\s*=|(?:xlink:)?href\s*=\s*["'\'']?\s*javascript:' -g '*.svg'
 # Server-composed bootstrap payload — LOCATES it; the per-field judgement is yours
 rg -n '__NEXT_DATA__|__NUXT__|window\.__INITIAL_STATE__|@json\(|json_encode\([^)]*\)\s*\)?\s*</script>|dehydratedState'
 ```

package/dist/agent-src/skills/git-workflow/SKILL.md

@@ -56,7 +56,7 @@ gh pr view <number> --json number,state,mergeStateStatus,mergedAt,baseRefName
   **same turn**; never merge on a status seen earlier in the conversation.
 - **"Based on main" / "current"** → prove it with
   `npx tsx node_modules/@event4u/agent-config/src/scripts/check_branch_freshness.ts`;
-  exit `1` ⇒ the branch is behind and is **not** current — merge the base in,
+  exit `1` ⇒ the branch is behind and is **not** current (or the named base does not exist on the remote; the message says which) — update it from the base per `git.update_strategy` ([`references/branch-update.md`](references/branch-update.md)),
   regenerate the derived files, then open the PR (see
   [`/create-pr`](../../commands/pr/create.md) § 1b). Exit `0` means only that
   the gate did **not refuse**: read the line. `branch is current` is the pass;
@@ -76,13 +76,13 @@ gh pr view <number> --json number,state,mergeStateStatus,mergedAt,baseRefName
 ## Conventions
 
 → See guideline `docs/guidelines/php/git.md` for branch naming, commit messages, PR conventions.
-→ See `commit-conventions` rule for commit format, types, and scope rules.
+→ See `commit-conventions` rule for commit format, types, and scope rules; a team convention is declared in the `git:` settings (`commit_format`, `branch_pattern`, `update_strategy`).
 → Use `conventional-commits-writing` skill for generating/reviewing commit messages.
 
 ## Procedure: Before opening a PR
 
 1. Quality pipeline + tests — only when `quality.local_auto_run: true` (see [`quality-tools` § Execution policy](../quality-tools/SKILL.md)): type-checker → auto-fixer → linter → type-checker, then the project's test command (detect from manifest: `php artisan test` / `vendor/bin/phpunit` (PHP), `npm test` / `pnpm test` / `vitest` / `jest` (JS-TS), `pytest` (Python), `cargo test` (Rust), `go test ./...` (Go)). Under the default (`false` / missing) skip both — remote CI on the PR is the gate; say so instead of claiming they passed.
-2. Rebase onto `main`.
+2. Update the branch from its base — [`references/branch-update.md`](references/branch-update.md).
 3. Fill in PR template completely.
 
 ## Procedure: Finish a branch
@@ -100,11 +100,11 @@ Work complete. What would you like to do?
 ### Option 1: Push and create PR
 
 1. Run quality pipeline + tests (only when `quality.local_auto_run: true`; default `false` → skip, remote CI is the gate).
-2. **The push-ready sequence** — fetch → integrate the base SET → regenerate →
+2. **The push-ready sequence** — fetch → integrate the base SET (per `git.update_strategy`, [`references/branch-update.md`](references/branch-update.md)) → regenerate →
    verify → re-check freshness (this repo wires it as a `push-ready` task target;
    a consumer wires its own). Not optional housekeeping: see § A push closes its
    own loop. A stale push is refused, so skipping this buys the refusal.
-3. `git push -u origin <branch>`.
+3. `git push -u origin "<branch>"` (a rendered name is always quoted) — after a rebase of a pushed branch, `--force-with-lease` per `references/branch-update.md`.
 4. `gh pr create` using PR template.
 5. **Settle it** — the turn is not over at step 4:
    `npx tsx node_modules/@event4u/agent-config/src/scripts/ci_settle.ts <pr>`
@@ -136,7 +136,7 @@ legitimate — **ending the turn silently on one is not**.
 `ci_settle` non-zero → read only the failing part
 (`gh run view --job <id> --log-failed | grep -E '×|FAIL|Error'`), fix, push
 again; the author of the red is irrelevant (`fix-what-you-see`). Three failed
-attempts on one target → stop and surface them (`autonomous-execution` N=3).
+attempts on one target trigger `autonomous-execution`'s mandatory strategy shift.
 Exit `2` is **not** a verdict — the wait timed out or the API could not be read.
 Counts, carrier limits and the honest cost:
 [`references/push-closes-its-loop.md`](references/push-closes-its-loop.md).
@@ -153,7 +153,7 @@ The project uses `.github/pull_request_template.md`:
 ## Default branch
 
 - `main` is default/production branch.
-- Merge strategy: merge commits (not squash).
+- Merge method: read from the forge (`/pr:merge` § 9), never assumed; rebase-and-merge keeps every commit, so each subject must follow the convention.
 
 ## Procedure: Safe squash-after-push
 
@@ -165,26 +165,28 @@ Trigger context: `git-history-discipline` rule routed here.
 
 ### 1. Snapshot before touching anything
 
+`REMOTE`/`RB`: the published ref, from the `resolve` block of [`references/branch-update.md`](references/branch-update.md) § The rebase sequence — never `@{u}`; unresolved → no squash.
+
 ```bash
-BRANCH=$(git branch --show-current)
 DATE=$(date +%F)
-git fetch origin
-git tag "safe-squash-pre/${BRANCH}/${DATE}" HEAD
-git tag "safe-squash-origin/${BRANCH}/${DATE}" "@{u}"
+PUBLISHED=$(git ls-remote "$REMOTE" "refs/heads/$RB") || { echo "STOP: could not read $REMOTE/$RB — nothing was rewritten" >&2; exit 1; }; EXPECTED=$(cut -f1 <<<"$PUBLISHED")
+git fetch -q "$REMOTE" "refs/heads/$RB"
+SNAP="refs/agent-config/rewrites/squash-${DATE}-$$"
+git update-ref "$SNAP/before" HEAD
+git update-ref "$SNAP/published" "$EXPECTED"
 ```
 
-Two tags = two recoveries (local tip + origin tip). Do not skip the
-tags — `git reflog` is TTL-bounded and unreliable across sessions.
+Two refs = two recoveries (local tip + published tip), private — `git push --tags` cannot publish them; `git reflog` is TTL-bounded and unreliable across sessions.
 
 ### 2. Verify aligned starting state
 
 ```bash
-git rev-list --left-right --count HEAD...@{u}
+git rev-list --left-right --count "HEAD...$EXPECTED"
 ```
 
 - `0  0` → aligned, proceed.
 - `N  0` (local ahead) → unpushed work, proceed.
-- `0  N` (origin ahead) → `git pull --ff-only` first, then re-check.
+- `0  N` (published ref ahead) → `git merge --ff-only "$EXPECTED"` first, then re-check.
 - `M  N` (both non-zero) → **divergent**. Abandon the squash and run
   § Divergent-State Recovery below.
 
@@ -197,18 +199,16 @@ git reset --soft "$(git merge-base HEAD <base>)"
 git commit -m "<conventional commit message>"
 ```
 
-Interactive rebase only when the user wants per-commit control — it
-replays derived files (`dist/agent-src/`, router projections)
-per commit and conflicts on every replay.
+Interactive rebase only when the user wants per-commit control — it replays
+derived files (`dist/agent-src/`, router projections) and conflicts on every replay.
 
 ### 4. Re-push in the SAME turn
 
 ```bash
-FETCHED_SHA=$(git rev-parse "@{u}")
-git push --force-with-lease="${BRANCH}:${FETCHED_SHA}" origin "${BRANCH}"
-git fetch origin
-[ "$(git rev-parse HEAD)" = "$(git rev-parse @{u})" ] \
-  && echo "OK: origin matches HEAD" \
+# $EXPECTED is the SHA pinned in step 1 — re-reading it would lease a collaborator's push
+git push --force-with-lease="refs/heads/$RB:$EXPECTED" "$REMOTE" "HEAD:refs/heads/$RB"
+[ "$(git ls-remote "$REMOTE" "refs/heads/$RB" | cut -f1)" = "$(git rev-parse HEAD)" ] \
+  && echo "OK: the published ref matches HEAD" \
   || echo "MISMATCH — do not end session"
 ```
 
@@ -216,20 +216,20 @@ If the push fails (pre-push hook, network, token budget):
 - Fix the underlying cause **now**.
 - Re-push immediately.
 - Do not commit new work on top of the squashed-but-unpushed tip.
-- Do not end the session until `HEAD == @{u}`.
+- Do not end the session until the published ref equals `HEAD`.
 
 ### 5. Hand off only with verified parity
 
 Report exactly:
 - pre-squash tip SHA (from step 1)
-- pre-squash tag name (for recovery)
+- the recovery refs under `$SNAP` — removed with `git update-ref -d` once step 4 verified parity; kept, with `git reset --keep "$SNAP/before"` printed, if anything failed
 - post-squash tip SHA == origin SHA (verified in step 4)
 - PR number, if any, and confirm it picked up the new tip
 
 ## Procedure: Divergent-State Recovery
 
-Fires when `git rev-list --left-right --count HEAD...@{u}` shows
-**both** sides non-zero on the current branch.
+Fires when `git rev-list --left-right --count "HEAD...$EXPECTED"` (the published
+ref's SHA, pinned as in § Safe squash-after-push step 1) shows **both** sides non-zero.
 
 ### 1. Stop. Do not pull.
 
@@ -239,28 +239,28 @@ shape — guaranteed conflict storm in derived files, possible
 double-application of the same change. This is the documented failure
 mode behind `git-history-discipline`.
 
-### 2. Tag both sides immediately
+### 2. Record both sides immediately
 
 ```bash
-TS=$(date +%FT%H%M)
-git tag "diverged-local/${TS}" HEAD
-git tag "diverged-origin/${TS}" "@{u}"
+SNAP="refs/agent-config/rewrites/diverged-$(date +%Y%m%dT%H%M)"
+git update-ref "$SNAP/before" HEAD
+git update-ref "$SNAP/published" "$EXPECTED"
 ```
 
 ### 3. Diagnose: which side is the correct future?
 
 ```bash
-git log --oneline @{u}..HEAD   # local-only commits
-git log --oneline HEAD..@{u}   # origin-only commits
-git diff @{u}..HEAD --stat     # shape of local-ahead work
+git log --oneline "$EXPECTED..HEAD"   # local-only commits
+git log --oneline "HEAD..$EXPECTED"   # published-only commits
+git diff "$EXPECTED..HEAD" --stat     # shape of local-ahead work
 ```
 
 Decision matrix:
 
 | Pattern | Future | Action |
 |---|---|---|
-| Local has the same logical work as origin, just reshaped (squash/rebase) | **Local** | After PR-review check (step 4), `git push --force-with-lease=<branch>:<origin-sha>` |
-| Origin has commits local does not reflect (another contributor pushed) | **Origin** | Tag any local-ahead work for cherry-pick, then `git reset --hard @{u}` |
+| Local has the same logical work as origin, just reshaped (squash/rebase) | **Local** | After PR-review check (step 4), `git push --force-with-lease=refs/heads/<b>:<sha> <remote> HEAD:refs/heads/<b>` |
+| Origin has commits local does not reflect (another contributor pushed) | **Origin** | Keep any local-ahead work at the step-2 refs for cherry-pick, then `git reset --hard "$EXPECTED"` |
 | Both sides have genuine independent work | **ask user** | Never decide silently — surface the two commit lists and let the user pick |
 
 ### 4. PR review-comment check (mandatory before any force-push)
@@ -277,16 +277,16 @@ destroys live review feedback is unrecoverable from the agent side.
 
 ### 5. Recover or proceed
 
-Use the tags from step 2 to restore either side if step 4 surfaces a
-problem. After resolution, verify `HEAD == @{u}` and report both
-SHAs plus the tags created.
+Use the refs from step 2 to restore either side if step 4 surfaces a
+problem. After resolution, verify the published ref equals `HEAD` and report both
+SHAs plus the refs recorded.
 
 ## Hard prohibitions on a pushed branch
 
 - No `git pull --rebase` after detecting divergent state.
-- No `git push --force` without `--force-with-lease=<branch>:<sha>`.
+- No `git push --force`, and no `--force-with-lease` without its fully qualified `refs/heads/<b>:<sha>`.
 - No squash-then-end-session — the push must complete in the same turn.
-- No reflog-only recovery — always tag the state explicitly first.
+- No reflog-only recovery — always record the state under `refs/agent-config/rewrites/` first.
 
 ## Shared-branch & inherited commits — ask-before-drop protocol
 
@@ -321,11 +321,11 @@ force-push would clobber their in-flight work regardless of your local backup.
 
 ## Two protective stops (for the protocol phase)
 
-1. **Pre-rewrite stop.** Before any squash / amend / rebase on a branch that is on origin: `git fetch && git rev-list --left-right --count HEAD...@{u}`. If **either** side is non-zero — STOP and run § Divergent-State Recovery. A blind `git pull --rebase` in this state is the documented failure mode. (§ Safe squash-after-push steps 1–2 implement this stop.)
+1. **Pre-rewrite stop.** Before any squash / amend / rebase of a pushed branch: resolve the ref it publishes (`@{push}`, or the pull request's head repository — [`references/branch-update.md`](references/branch-update.md) § The rebase sequence; never `@{u}`, which is the base for a branch pushed without `-u`), pin its SHA once, then `git rev-list --left-right --count "HEAD...$EXPECTED"`. An unresolved target is no rewrite. Squash / amend: if **either** side is non-zero — STOP and run § Divergent-State Recovery. Rebase: the pinned SHA must already be in `HEAD` — your own unpushed commits travel with the rebase. A blind `git pull --rebase` in this state is the documented failure mode. (§ Safe squash-after-push steps 1–2 implement this stop.)
 
-2. **Post-rewrite stop.** After the rewrite, push in the **same turn** with `--force-with-lease=<branch>:<fetched-sha>` and verify `git rev-parse origin/<branch>` equals `git rev-parse HEAD`. If the push fails (hook, network, token budget) — fix the cause and re-push **before** ending the session, committing new work, or handing off. (§ Safe squash-after-push step 4 implements this stop.)
+2. **Post-rewrite stop.** After the rewrite, push in the **same turn** with `git push --force-with-lease=refs/heads/<b>:<pinned-sha> <remote> HEAD:refs/heads/<b>` and verify `git ls-remote <remote> refs/heads/<b>` equals `git rev-parse HEAD`. A rejected lease is a stop — refetch and report, never a bare `--force-with-lease`, never `--force`. If the push fails (hook, network, token budget) — fix the cause and re-push **before** ending the session, committing new work, or handing off. (§ Safe squash-after-push step 4 implements this stop.)
 
-If either stop fires and resolution is not immediate → tag the state (`git tag local-rewritten-tip-<ISO-date>`) and hand control back to the user. Do not let a new session inherit a dirty divergence.
+If either stop fires and resolution is not immediate → record the state (`git update-ref refs/agent-config/rewrites/<tx>/before HEAD`) and hand control back to the user. Do not let a new session inherit a dirty divergence.
 
 ## Equivalents that are also forbidden by default
 

package/dist/agent-src/skills/git-workflow/references/branch-update.md

@@ -0,0 +1,312 @@
+# Updating a branch from its base
+
+Detail for [`git-workflow`](../SKILL.md) § Live remote state and § Before
+opening a PR. The one place that
+decides how a feature branch takes in its base — `/create-pr` § 1b, `/pr:merge`
+§ 2, `/prepare-for-review` and `/review:changes` defer here. Read
+`git.update_strategy` from `agent-config git:convention show --key update_strategy --base origin/<base>`, which exits 1
+when the value in force is `malformed`, `invalid`, `discarded` or
+`unresolvable` — none of these is a strategy: stop and report the line it
+prints, never fall back to `merge`. A candidate in one of these states is
+printed as a warning with exit 0: the update reads only the value in force.
+A team declares the strategy in `.git-convention.yml` at the repository root
+(ADR-283), and it is read at the commit the branch is judged against — the
+`--base` given, the pull request's base — so a value changed on this branch is
+a candidate `show` prints and applies only once it lands there; `unresolvable`
+means that commit could not be read. Without `--base` the target is the default
+branch, right only for a branch that targets it; nothing asks the forge:
+
+| `git.update_strategy` | Operation | Asked first? |
+|---|---|---|
+| `merge` (default) | `git fetch origin && git merge origin/<base> --no-edit` | no — a merge adds a commit and rewrites nothing |
+| `rebase` | § The rebase sequence below: resolve the ref the branch publishes, pin its SHA once, stop unless that SHA is already in `HEAD`, `git rebase origin/<base>`, report equivalence, regenerate and verify, then push in the same turn with `git push --force-with-lease=refs/heads/<b>:<sha> <remote> HEAD:refs/heads/<b>`, the pinned SHA as the lease | **yes**, unless [`git-history-discipline`](../../../rules/git-history-discipline.md) § When rewrite is allowed already covers it — the user asked this turn, an unrevoked standing instruction ("always rebase before pushing"), or a `pull --rebase` the user started. The setting picks the operation; it is never the authorisation |
+
+## Under `rebase`
+
+- **Never merge the base into the branch instead**, not even to avoid the ask —
+  a `Merge branch 'main' into …` commit is exactly what the setting excludes.
+  No authorisation → stop and ask with numbered options (rebase now / leave the
+  branch behind).
+- **Pushed branch** → § The rebase sequence is the skill's § Two protective
+  stops in their rebase form: commits on the published ref you lack halt the
+  rebase, and the push follows in the same turn.
+- **Shared branch** — commits on it that you did not author this session → do
+  not rebase without the authors' agreement; this is the git-history-discipline
+  inherited-commits law, and the setting does not lift it.
+- **Known descendants** → refuse. When the open pull requests' bases — the
+  chain `/prepare-for-review` already reads
+  (`gh pr list --base <branch> --json number,headRefName`) — show another branch
+  built on this one, the `rebase` row does not run: rewriting the parent leaves
+  every descendant carrying its old commits, and a later
+  `git rebase origin/<parent>` on the child replays them. The sequence enforces
+  it: the caller supplies `DESCENDANTS` (input below) and step 2 stops on a
+  non-empty list, naming it. Restacking the chain is not this procedure, and an
+  unasked `--onto` reseat needs the question the skill's shared-branch protocol
+  asks. Nothing is inferred from branch names — only a pull request whose base
+  is this branch counts.
+- **Completion review** → rebase first, review after: the completion review
+  binds after the last rebase, and one taken before a rebase is re-bound after
+  it — the re-binding reviewer cites the post-rebase commits in a commit of its
+  own. The step 3 equivalence report is supporting data for that reviewer, never
+  the re-binding itself, and nothing edits a findings file automatically
+  ([`plan-review-gates`](../../../docs/contracts/plan-review-gates.md) § 2.5).
+- **Conflicts** → resolve to the correct end state per commit, `git add`,
+  `git rebase --continue`; `git rebase --abort` returns to the pre-rebase state.
+  Re-run the relevant tests afterwards — a conflict-free tree is not a correct
+  one. Detail: [`merge-conflicts`](../../merge-conflicts/SKILL.md).
+- **A base SET** (a non-default target whose branch-convergence policy also
+  carries the default branch): rebase onto the target. When the branch is
+  current with the target and the target itself is behind its default,
+  `sync_pr_branch` exits 3 with the reason code `TARGET_POLICY_STALE` — that is
+  the target's update, not this branch's; report it and do not rebase. A branch
+  also behind the target gets the ordinary behind line first.
+- **`sync_pr_branch` exits** — `0` with a `✅` line: current, or under `merge`
+  merged cleanly; `0` with a `⚠️` `unverified` or `BYPASSED` line: **not
+  checked** (the base commit or origin not fetched, or the convergence policy
+  disabled), never read as current; `1`: a conflict, git refusing the merge
+  before it starts (a dirty tree, an untracked file in the way — git's line is
+  printed), the base could not be resolved, or the target moved before the merge onto a commit carrying another
+  strategy — nothing merged, run again; `2`: a blank `--base` (usage) or an
+  internal error; `3`: behind under a strategy other than `merge`, refused and
+  never merged; `4`: the strategy itself cannot be read — the line names the
+  reason code and the file, and nothing was checked. A current branch passes
+  with exit 0, so automated pre-push syncs stay green when there is nothing to do.
+- **Plain `git push --force` is never used**, and neither is a bare
+  `--force-with-lease` — only the qualified lease the sequence pins, and never
+  against the base branch itself.
+- **Tidying WIP / fixup commits before the PR** (`git commit --fixup`,
+  `git rebase -i --autosquash origin/<base>`) stays a user-requested operation —
+  the skill's § Equivalents that are also forbidden by default lists it; a team
+  that expects curated history asks for it, and the agent offers it, never runs
+  it unasked.
+- **Published commits on the base are never rewritten**; a wrong change there is
+  undone with `git revert <sha>`, a new commit.
+
+## The rebase sequence
+
+The branch's upstream (`@{u}`) is **not** the ref it publishes: a branch cut
+from `origin/main` and pushed without `-u` tracks the base, so a stop or a lease
+read from `@{u}` checks the base and carries the base's SHA. `origin/<branch>`
+is not it either — `branch.<name>.pushRemote`, `remote.pushDefault` and a fork
+head publish elsewhere. The sequence therefore resolves the publish target,
+and an **unresolved target means no rewrite** — never "never pushed". Only a
+resolved target with no remote ref is a branch that was never pushed. The
+remedy the stop names: set the upstream once with `git push -u <remote> <branch>`,
+then run the sequence again.
+
+**Inputs, set before step 1.** `BASE` is required: the pull request's base
+branch, bare (`main`, `release/1.x`). `DESCENDANTS` is required by step 2: the
+head branches of the open pull requests whose base is this branch, space
+separated — `gh pr list --base <branch> --json headRefName --jq '.[].headRefName'`
+— and set empty only when that list is empty; the sequence cannot ask the forge
+itself, so an unset value is a stop. `DESCENDANTS_STATUS` is required with it:
+the exit status of that `gh pr list`
+(`DESCENDANTS=$(gh pr list …); DESCENDANTS_STATUS=$?`), because a failed call
+also prints nothing, and anything but `0` is a stop. `PR_HEAD_REPO` and `PR_HEAD_REF` are set
+only with an open pull request (step 1). **Steps 1–3 are one script** — run
+them in order, in ONE shell session, never as separate tool calls: they share
+`REMOTE`, `RB`, `EXPECTED`, `SAVE` and the `stop` / `keep` functions the first
+block defines. Each later block opens by checking that it shares that session
+and stops otherwise, because an undefined `stop` would be a command that is not
+found and lets the block run on. **Step 4 is a separate run**: step 3 stops
+and prints the `SAVE` and `EXPECTED` it hands on; the caller regenerates the
+derived files and runs its own verification on the rebased tree, then, in one
+shell, runs step 1 again with those two set and runs step 4. Nothing is
+published before that verification.
+
+**1. Resolve.** `@{push}` names the publish target where the push
+configuration determines one; with an open pull request, its head repository and
+`headRefName` (`gh pr view --json headRefName,headRepository,headRepositoryOwner`)
+name it — set `PR_HEAD_REPO=<owner>/<name>` and `PR_HEAD_REF=<headRefName>`
+first. The two must agree when both resolve. A target that names the base
+branch — `BASE`, or the default branch the publish remote reports — is a stop:
+under `push.default=upstream` or `tracking`, `@{push}` of a branch cut with
+`--track origin/main` IS `origin/main`, and nothing later in the sequence would
+notice — the base is an ancestor of `HEAD`, so the pin passes
+and the lease is the base's own SHA.
+
+```bash
+# rebase-sequence: resolve
+stop() { echo "STOP: $*" >&2; exit 1; }
+keep() { stop "$* — the old head is kept at $SAVE; restore it with: git reset --keep $SAVE"; }
+: "${BASE:?STOP: BASE is required — the pull request base branch, bare; nothing was rewritten}"
+REMOTE= RB=
+B=$(git branch --show-current)
+if PUSH=$(git rev-parse --symbolic-full-name '@{push}' 2>/dev/null); then
+  REMOTE=$(git for-each-ref --format='%(push:remotename)' "refs/heads/$B")
+  RB=${PUSH#"refs/remotes/$REMOTE/"}
+fi
+if [ -n "${PR_HEAD_REPO:-}" ]; then
+  PR_REMOTE=$(git remote -v | awk -v r="$PR_HEAD_REPO" '$3 == "(push)" && $2 ~ ("[/:]" r "(\\.git)?$") { print $1; exit }')
+  [ -n "$PR_REMOTE" ] || { echo "STOP: no remote publishes $PR_HEAD_REPO" >&2; exit 1; }
+  if [ -n "$REMOTE" ] && { [ "$REMOTE" != "$PR_REMOTE" ] || [ "$RB" != "$PR_HEAD_REF" ]; }; then
+    echo "STOP: @{push} is $REMOTE/$RB but the pull request head is $PR_HEAD_REPO:$PR_HEAD_REF" >&2; exit 1
+  fi
+  REMOTE=$PR_REMOTE RB=$PR_HEAD_REF
+fi
+[ -n "$REMOTE" ] && [ -n "$RB" ] \
+  || { echo "STOP: publish target unresolved — no rewrite; set the upstream once with git push -u <remote> $B, then run the sequence again" >&2; exit 1; }
+DEF=$(git ls-remote --symref "$REMOTE" HEAD | awk '$1 == "ref:" { sub("^refs/heads/", "", $2); print $2; exit }')
+for b in "${BASE:-}" "$DEF"; do
+  [ -z "$b" ] || [ "$RB" != "$b" ] \
+    || { echo "STOP: the publish target $REMOTE/$RB is the base branch — a rewrite is never published onto its base" >&2; exit 1; }
+done
+```
+
+**2. Stop, pin, rebase.** The stops come first, before anything is
+rewritten: known descendants (`DESCENDANTS` non-empty, § Under `rebase`); a
+dirty working tree; a merge commit in the topic range
+(`git rev-list --merges origin/<base>..HEAD` is non-empty) — the default
+`merge` strategy and `/prepare-for-review` put them there, so a branch switched
+to `rebase` usually carries one, and a plain rebase silently drops it. When
+every such commit is a **base merge** — each parent after the first is
+reachable from `origin/<base>` — the stop names its remedy: a plain rebase that
+drops those merges, run only after the user confirms it this turn, which a run
+started with `DROP_BASE_MERGES=1` stands for; the recovery ref is written
+first, and conflicts resolved inside those merges may come back during the
+rebase. A base merge whose tree differs from the automatic merge of its two
+parents (`git merge-tree --write-tree`) carries changes of its own — a conflict
+resolution, or an edit made inside the merge — and is never dropped: the run
+stops naming it, and whenever merges were dropped step 3 reports "needs
+review". A merge of anything else is still refused even with
+`DROP_BASE_MERGES=1`; `--rebase-merges` is a separate operation the user asks
+for, never a fallback;
+and commits on the branch you did not author (§ Under `rebase`, shared branch)
+— any commit in `origin/<base>..HEAD` whose author email is not
+`git config user.email`. That stop lifts only for a run started with
+`ALLOW_FOREIGN=1`, which stands for the user's answer this turn that those
+commits may be rewritten; it is never set to get past the stop.
+Then the remote ref is read once; that literal is the stop (it must already be
+in `HEAD`) and, unchanged, the lease. A read that fails is a stop of its own,
+never an empty answer: an empty literal means "never pushed", which skips the
+stop. A collaborator's push lands either before
+the pin and halts the stop, or after it and fails the lease — it is never
+overwritten.
+
+Before the rewrite the old head is kept at a private recovery ref,
+`refs/agent-config/rewrites/<tx>/before`, written with `git update-ref` —
+outside `refs/tags/`, so `git push --tags` cannot publish it, and not a tag
+push for anything that counts them. It is removed once the published ref reads
+back as `HEAD`; on any failure it is kept and the one command that restores it
+is printed. A kept ref is removed with `git update-ref -d <ref>`.
+
+```bash
+# rebase-sequence: rebase
+declare -F keep >/dev/null && [ -n "${BASE:-}" ] && [ -n "${REMOTE:-}" ] \
+  || { echo "STOP: run steps 1–3 in one shell session, starting with step 1 — nothing was rewritten" >&2; exit 1; }
+[ "${DESCENDANTS+set}" = set ] \
+  || stop "DESCENDANTS is required — the head branches of open pull requests whose base is this branch, empty when there are none; nothing was rewritten"
+[ "${DESCENDANTS_STATUS+set}" = set ] \
+  || stop "DESCENDANTS_STATUS is required — the exit status of the gh pr list that produced DESCENDANTS; nothing was rewritten"
+[ "$DESCENDANTS_STATUS" = 0 ] \
+  || stop "could not list the pull requests built on this branch (gh exited $DESCENDANTS_STATUS) — an unanswered question is not an empty list; nothing was rewritten"
+[ -z "$DESCENDANTS" ] \
+  || stop "pull requests are built on this branch ($DESCENDANTS) — rewriting it leaves them carrying its old commits; restacking is not this procedure, nothing was rewritten"
+[ -z "$(git status --porcelain --untracked-files=no)" ] || stop "the working tree is dirty — nothing was rewritten"
+git fetch -q origin "$BASE" || stop "could not fetch origin $BASE — nothing was rewritten"
+MERGES=$(git rev-list --merges "origin/$BASE..HEAD") \
+  || stop "could not list the topic range origin/$BASE..HEAD — nothing was rewritten"
+if [ -n "$MERGES" ]; then
+  OTHER=
+  for m in $MERGES; do
+    for p in $(git rev-parse "$m^@" | tail -n +2); do
+      git merge-base --is-ancestor "$p" "origin/$BASE" || { OTHER="$OTHER $(git rev-parse --short "$m")"; break; }
+    done
+  done
+  [ -z "$OTHER" ] \
+    || stop "the topic range carries a merge commit that is not a merge of the base ($OTHER) — a plain rebase drops it; --rebase-merges is a separate operation the user asks for"
+  [ "${DROP_BASE_MERGES:-}" = 1 ] \
+    || stop "the topic range carries a merge commit from an earlier merge of the base, which a plain rebase drops — ask the user; set DROP_BASE_MERGES=1 only on their answer this turn (conflicts resolved inside those merges may come back); keeping them is --rebase-merges, a separate operation the user asks for"
+  for m in $MERGES; do
+    AUTO=$(git merge-tree --write-tree "$m^1" "$m^2" 2>/dev/null | head -n 1) && [ -z "$(git rev-parse -q --verify "$m^3")" ] \
+      && [ "$AUTO" = "$(git rev-parse "$m^{tree}")" ] \
+      || stop "the merge $(git rev-parse --short "$m") carries changes of its own (a conflict resolution or an edit) — dropping it loses them; nothing was rewritten"
+  done
+fi
+ME=$(git config user.email) || stop "git config user.email is unset, so your commits cannot be told from inherited ones — nothing was rewritten"
+AUTHORS=$(git log --format='%h %ae' "origin/$BASE..HEAD") \
+  || stop "could not list the authors of origin/$BASE..HEAD — nothing was rewritten"
+FOREIGN=$(awk -v me="$ME" 'tolower($2) != tolower(me)' <<<"$AUTHORS")
+[ -z "$FOREIGN" ] || [ "${ALLOW_FOREIGN:-}" = 1 ] \
+  || stop "the topic range carries commits you did not author ($(tr '\n' ' ' <<<"$FOREIGN")) — ask the user; set ALLOW_FOREIGN=1 only on their answer this turn"
+PUBLISHED=$(git ls-remote "$REMOTE" "refs/heads/$RB") || stop "could not read $REMOTE/$RB — nothing was rewritten"
+EXPECTED=$(cut -f1 <<<"$PUBLISHED")
+if [ -n "$EXPECTED" ]; then
+  git fetch -q "$REMOTE" "refs/heads/$RB" || stop "could not fetch $REMOTE/$RB — nothing was rewritten"
+  git merge-base --is-ancestor "$EXPECTED" HEAD || stop "$REMOTE/$RB has commits this branch lacks"
+fi
+SAVE="refs/agent-config/rewrites/$(date -u +%Y%m%dT%H%M%SZ)-$$/before"
+git update-ref "$SAVE" HEAD
+git rebase "origin/$BASE" \
+  || keep "the rebase stopped on a conflict — resolve each commit and git rebase --continue, then in one shell run step 1, set SAVE=$SAVE EXPECTED=$EXPECTED, and run step 3 (git rebase --abort first to give up)"
+```
+
+**3. Report equivalence from stable data.** The stable patch ids of the old
+range and the new range are compared: equal sets mean "mechanically
+equivalent"; anything else means "needs review" and names the commits on each
+side that have no match — never a pair inferred from a subject or a position.
+Whenever the old head already contained the new base, the trees must also be
+equal. A conflict resolution changes a patch id, so a mismatch means "needs
+review", never "wrong". A non-empty range that yields no patch id at all — an
+empty commit, or diff output git could not read — is "needs review" too: an
+empty comparison is not an equal one. Colour is forced off, so a
+`color.ui=always` configuration cannot empty both sets. The verdict is a report, not a review: it binds nothing
+and approves nothing. `git range-diff` is shown to the human and never parsed —
+its manual says under OUTPUT STABILITY that the output is not for machines.
+
+```bash
+# rebase-sequence: equivalence
+declare -F keep >/dev/null && [ -n "${SAVE:-}" ] && [ -n "${BASE:-}" ] \
+  || { echo "STOP: run steps 1–3 in one shell session, starting with step 1" >&2; exit 1; }
+pids() { git -c color.ui=never log -p --no-color --no-merges --format='commit %H' "$1" | git patch-id --stable | sort; }
+OLD_BASE=$(git merge-base "$SAVE" "origin/$BASE")
+OLD=$(pids "$OLD_BASE..$SAVE")
+NEW=$(pids "origin/$BASE..HEAD")
+VERDICT="mechanically equivalent"
+[ "$(cut -d' ' -f1 <<<"$OLD")" = "$(cut -d' ' -f1 <<<"$NEW")" ] || VERDICT="needs review"
+[ -n "$OLD" ] || [ "$(git rev-list --count --no-merges "$OLD_BASE..$SAVE")" = 0 ] || VERDICT="needs review"
+[ -n "$NEW" ] || [ "$(git rev-list --count --no-merges "origin/$BASE..HEAD")" = 0 ] || VERDICT="needs review"
+DROPPED=$(git rev-list --merges "$OLD_BASE..$SAVE")
+[ -z "$DROPPED" ] || VERDICT="needs review"
+if git merge-base --is-ancestor "origin/$BASE" "$SAVE" \
+  && [ "$(git rev-parse "$SAVE^{tree}")" != "$(git rev-parse "HEAD^{tree}")" ]; then
+  VERDICT="needs review"
+fi
+echo "EQUIVALENCE: $VERDICT"
+[ -z "$DROPPED" ] || echo "  dropped merge(s): $(git rev-parse --short $DROPPED | tr '\n' ' ')"
+if [ "$VERDICT" = "needs review" ]; then
+  comm -3 <(cut -d' ' -f1 <<<"$OLD") <(cut -d' ' -f1 <<<"$NEW") | tr -d '\t' | sort -u | while read -r p; do
+    [ -n "$p" ] || continue
+    grep "^$p " <<<"$OLD" | while read -r _ c; do echo "  before: $(git log -1 --format='%h %s' "$c")"; done
+    grep "^$p " <<<"$NEW" | while read -r _ c; do echo "  after:  $(git log -1 --format='%h %s' "$c")"; done
+  done
+fi
+git range-diff "$OLD_BASE..$SAVE" "origin/$BASE..HEAD"   # for the human; never parsed
+echo "PUBLISH AFTER VERIFY: SAVE=$SAVE EXPECTED=$EXPECTED — regenerate and verify, then in one shell run step 1 with these two set, then step 4"
+```
+
+**4. Push in the same turn, then read the published ref back** — after the
+caller's regenerate and verify, in a fresh shell that ran step 1 with `SAVE`
+and `EXPECTED` from step 3. It refuses while a rebase is still in progress and when `HEAD` does
+not contain `origin/<base>`: a half-finished rebase is never published. An empty `EXPECTED` (never pushed) makes the lease
+require that the ref does not exist.
+
+```bash
+# rebase-sequence: publish
+declare -F keep >/dev/null && [ -n "${SAVE:-}" ] && [ "${EXPECTED+set}" = set ] && [ -n "${REMOTE:-}" ] && [ -n "${RB:-}" ] \
+  || { echo "STOP: run step 1 in this shell session, with SAVE and EXPECTED from step 3 — nothing was pushed" >&2; exit 1; }
+for d in rebase-merge rebase-apply; do
+  [ ! -e "$(git rev-parse --git-path "$d")" ] || keep "a rebase is in progress — finish it (git rebase --continue) or abort it, then verify again; nothing was pushed"
+done
+git merge-base --is-ancestor "origin/$BASE" HEAD \
+  || keep "HEAD does not contain origin/$BASE, the base it was rebased onto — nothing was pushed"
+git push --force-with-lease="refs/heads/$RB:$EXPECTED" "$REMOTE" "HEAD:refs/heads/$RB" \
+  || keep "the lease was rejected — $REMOTE/$RB moved; refetch and report, never retry without the lease"
+[ "$(git ls-remote "$REMOTE" "refs/heads/$RB" | cut -f1)" = "$(git rev-parse HEAD)" ] \
+  || keep "$REMOTE/$RB does not match HEAD after the push"
+[ -n "$SAVE" ] && git update-ref -d "$SAVE"
+```
+
+A rejected lease is a stop: refetch, report what moved, and hand back — never a
+bare `--force-with-lease`, which compares against whatever the last fetch
+brought in and so overwrites a push it has just fetched, and never `--force`.