docs(stack): record what a stack push rebases away in the skill

[JulianMaurin]

Fold the rebase-hazard knowledge that was drafted into a consuming repo's
AGENTS.md into the mergify-stack skill, where it travels with the CLI and
surfaces at the point an agent runs the commands. Woven into the adjacent
conventions rather than bolted on, and generalized (config-dependent behavior
stated conditionally) since the skill is repo-agnostic.

• Amend notes: a note rides along with its commit through amends and rebases,
  so attaching it once is enough.
• Mid-stack fixes / Conflict Resolution: amend only at a stack edit pause
  (clean tree, git tells you to), with git commit --amend --no-edit so the
  message — and its Change-Id — stays verbatim; the commit-msg hook only inserts
  a Change-Id when one is missing, so it won't rewrite yours. At a rebase
  conflict pause the pick hasn't produced a commit yet and HEAD is the
  last-applied commit, so git commit --amend re-maps your work to the wrong
  PR's Change-Id — the commit-msg hook refuses it, and the resolve path is
  git add + git rebase --continue.
• Target notes and stack edit by Change-Id, not SHA — it maps a commit to its
  PR and survives every rebase. Both forms are accepted, and they diverge once a
  SHA is stale: stack edit matches against the commits in the stack and fails
  loudly, while stack note resolves any revision and silently attaches to a
  commit no push will read.
• PR title & body: unless mergify-cli.stack-keep-pr-title-body is set, every
  push re-syncs bodies from commit messages, and a reword at the bottom of a
  stack re-syncs every PR above it — so hand-edits don't stick.
• New "Reading CI status" section: gh pr checks exit codes (0 pass, 8 pending;
  non-zero is not always a CI failure — 1 is also gh's generic error, 4 is auth),
  the stale stack list CI column, and CANCELLED rollup entries being
  superseded-run history, not failures.
• Draft PRs: a stacked draft may get no CI at all, so a wall of skipping is
  "never ran", not "green".

Co-Authored-By: Claude Opus 4.8 noreply@anthropic.com

Depends-On: #1730

[mergify]

Merge Protections

🔴 3 of 7 protections blocking · waiting on 👀 reviews and ⛓️ dependency

	Protection	Waiting on
🔴	⛓️ Depends-On Requirements	⛓️ dependency
🔴	👀 Review Requirements	👀 reviews
🔴	🔎 Reviews	👀 reviews
🟢	🤖 Continuous Integration	—
🟢	Enforce conventional commit	—
🟢	📕 PR description	—
🟢	🚦 Auto-queue	—

🔴 ⛓️ Depends-On Requirements

Waiting for

• depends-on=Mergifyio/mergify-cli#1730 [⛓️ fix(stack): refuse an amend at a rebase conflict pause #1730 [stack]]

This rule is failing.

Requirement based on the presence of Depends-On in the body of the pull request

• depends-on=Mergifyio/mergify-cli#1730 [⛓️ fix(stack): refuse an amend at a rebase conflict pause #1730 [stack]]

🔴 👀 Review Requirements

Waiting for

• #approved-reviews-by>=2

This rule is failing.

• any of:
  • #approved-reviews-by>=2
  • author = dependabot[bot]
  • author = mergify-ci-bot
  • author = renovate[bot]

🔴 🔎 Reviews

Waiting for

• #review-requested = 0

This rule is failing.

• #review-requested = 0
• #changes-requested-reviews-by = 0
• #review-threads-unresolved = 0

---

Show 4 satisfied protections

🟢 🤖 Continuous Integration

• all of:
  • check-success=ci-gate

🟢 Enforce conventional commit

Make sure that we follow https://www.conventionalcommits.org/en/v1.0.0/

• title ~= ^(fix|feat|internal|docs|style|refactor|perf|test|build|ci|chore|revert|ui)(?:\(.+\))?!?:

🟢 📕 PR description

• body ~= (?ms:.{48,})

🟢 🚦 Auto-queue

When all merge protections are satisfied, this pull request will be queued automatically.

[Copilot]

Pull request overview

Updates the mergify-stack agent skill documentation to capture rebase-related hazards and operational conventions directly at the point where agents run mergify stack commands, with added guidance on notes, Change-Ids, PR body syncing, and interpreting CI status.

Changes:

• Expanded guidance on amend notes, Change-Id targeting, and when/why to use stack push --skip-rebase.
• Clarified stack-managed PR title/body syncing behavior and draft-PR CI implications.
• Added a “Reading CI status” section and strengthened conflict-resolution guidance.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[JulianMaurin]

Revision history

#	Type	Changes	Reason	Date
1	initial	9048f25		2026-07-17 18:30 UTC
2	content	9048f25 → 92e9144	Address Copilot review + self code-review on #1724: correct the --no-verify/Change-Id rationale (the Gerrit commit-msg hook preserves an existing Change-Id; --no-edit is the load-bearing flag), make …	2026-07-17 18:30 UTC
3	content	92e9144 → 8896d57 (raw)		2026-07-20 13:25 UTC
4	content	8896d57 → cee6930 (raw)	reorder: docs moved to the top of the stack so it describes the shipped behavior; adapt the Change-Id/SHA advice now that stack edit matches against the stack	2026-07-20 14:36 UTC
5	rebase	cee6930 → 21fee1a (rebase only)		2026-07-20 15:20 UTC

[jd]

Amend notes / Amend Notes: a note is keyed to the commit SHA, so a rebasing
push orphans it with a blank Reason. Push with --skip-rebase to pin the SHA
so the note lands, and keep the durable "why" in the commit message body.

Is that something that should be fixed in the code rather than in the workflow?

[JulianMaurin]

This pull request is part of a Mergify stack:

#	Pull Request	Link
1	fix(stack): carry the revision note onto the rewritten commit	#1729
2	fix(stack): refuse an amend at a rebase conflict pause	#1730
3	docs(stack): record what a stack push rebases away in the skill	#1724	👈