add merge conflict instructions

[strawgate]

Summary

• Clarifies merge-conflict handling for push_to_pull_request_branch: do not create merge commits, because patch generation uses git format-patch and fails on multi-parent commits.
• Expands conflict-resolution guidance to explicitly avoid git merge, git rebase, and multi-parent git commit-tree, and to resolve conflicts manually against the PR base branch from /tmp/pr-context/pr.json.
• Adds explicit merge-conflict handling steps in the PR assistant flow, including fork-PR push limitations and the required execution order when requests combine conflict resolution with additional code/review tasks.
• Propagates the updated merge-conflict instructions from the shared fragment into compiled workflow lock files to keep behavior consistent.
• Adds the new docs asset docs/assets/specialized-squads.png.

Validation

make compile          # sync triggers + compile to lock files
make lint             # run all linters

Pre-Completion Checklist

• Re-read the issue or request and confirmed this PR directly addresses it
• Reviewed all changed files for correctness
• Ran make compile and make lint with no errors
• Verified no unrelated files were modified

Generated by Update PR Body for issue #462

Generated by Update PR Body for issue #462

[coderabbitai]

Note

Reviews paused

It looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the reviews.auto_review.auto_pause_after_reviewed_commits setting.

Use the following commands to manage reviews:

• @coderabbitai resume to resume automatic reviews.
• @coderabbitai review to trigger a single review.

Use the checkboxes below for quick actions:

• ▶️ Resume reviews
• 🔍 Trigger review

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between fbadb2a and 0e1092d.

📒 Files selected for processing (6)

• .github/workflows/gh-aw-fragments/safe-output-push-to-pr.md
• .github/workflows/gh-aw-mention-in-pr-by-id.lock.yml
• .github/workflows/gh-aw-mention-in-pr-no-sandbox.lock.yml
• .github/workflows/gh-aw-mention-in-pr.lock.yml
• .github/workflows/gh-aw-pr-actions-fixer.lock.yml
• .github/workflows/gh-aw-pr-review-addresser.lock.yml

🚧 Files skipped from review as they are similar to previous changes (1)

• .github/workflows/gh-aw-pr-actions-fixer.lock.yml

---

📝 Walkthrough

Walkthrough

Workflow guidance was tightened to require batching requested actions into a fixed order: resolve merge conflicts first, then apply code changes/review feedback, and perform a single final push with no intermediate pushes. A new "If asked to fix merge conflicts" subsection prescribes a patch-based workflow: detect forked PRs and advise local resolution when pushing is disallowed; read PR head/base from /tmp/pr-context/pr.json; forbid creating merge commits or using rebase/commit-tree with multiple parents; use git merge-tree or git diff to compare against the PR base, edit files, commit as single-parent commits, and push via push_to_pull_request_branch with a resolution summary. The same constraints and steps are applied to PR-review handling paths.

Possibly related PRs

• Updates to Workflows for subagents #445 — adds on-disk PR context (e.g., /tmp/pr-context) and updates PR-handling workflows that read that context, aligning with the patch-based, push_to_pull_request_branch approach.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch add-merge-conflict-instructions

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 4

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Inline comments:
In @.github/workflows/gh-aw-fragments/safe-output-push-to-pr.md:
- Around line 67-69: Replace the hardcoded reference "origin/main" in the
guidance text with a dynamic base-branch placeholder like origin/"<base-branch>"
so the instructions work for PRs targeting non-main branches; update the
sentence that currently reads with origin/main to reference
origin/"<base-branch>" and mention using the workflow's base-branch variable
(e.g., github.base_ref or github.event.pull_request.base.ref) where appropriate
so the guidance aligns with the base-branch-driven workflow and matches the
pattern used elsewhere (see gh-aw-mention-in-pr.md).

In @.github/workflows/gh-aw-mention-in-pr-no-sandbox.lock.yml:
- Around line 455-456: The snippet hardcodes "origin/main" when resolving
conflicts for push_to_pull_request_branch; change it to use the PR base ref
instead of "origin/main" (e.g., derive from the pull request's base ref such as
github.event.pull_request.base.ref) so comparisons use the actual target branch
for the PR; apply this change in the source .md that generates the
.github/workflows/*.lock.yml via gh aw compile so regenerated lockfiles remain
correct.

In @.github/workflows/gh-aw-pr-actions-fixer.lock.yml:
- Around line 300-303: The guidance text still references the hardcoded branch
name `origin/main`; update that occurrence to use the PR base branch variable
(e.g. github.event.pull_request.base.ref) so the instruction is correct for PRs
targeting non-main branches—locate the string `origin/main` in the same block
that mentions `push_to_pull_request_branch` and replace it with the PR base
branch reference (or a template placeholder like `${{
github.event.pull_request.base.ref }}`) so the wording dynamically reflects the
actual target branch.

In @.github/workflows/gh-aw-pr-review-addresser.lock.yml:
- Around line 311-314: Replace the hardcoded "origin/main" string in the
conflict-resolution instructions with the PR's actual base branch read from
/tmp/pr-context/pr.json (use the JSON field that contains the base branch ref,
e.g., pull_request.base.ref or base.ref depending on the payload) so the
guidance works for repos whose default branch is not main; update the message
text to interpolate that value instead of "origin/main" wherever it appears.

---

ℹ️ Review info

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between fe635f1 and fbadb2a.

⛔ Files ignored due to path filters (1)

• docs/assets/specialized-squads.png is excluded by !**/*.png

📒 Files selected for processing (7)

• .github/workflows/gh-aw-fragments/safe-output-push-to-pr.md
• .github/workflows/gh-aw-mention-in-pr-by-id.lock.yml
• .github/workflows/gh-aw-mention-in-pr-no-sandbox.lock.yml
• .github/workflows/gh-aw-mention-in-pr.lock.yml
• .github/workflows/gh-aw-mention-in-pr.md
• .github/workflows/gh-aw-pr-actions-fixer.lock.yml
• .github/workflows/gh-aw-pr-review-addresser.lock.yml

🚧 Files skipped from review as they are similar to previous changes (1)

• .github/workflows/gh-aw-mention-in-pr.md