feat: add /fix workflow — iterative review → fix → re-review loop

.github/agents/expert-reviewer.agent.md

@@ -13,12 +13,12 @@ You are a thorough PR reviewer for PolyPilot. Read `.github/copilot-instructions
 
 ## 1. Gather Context
 
-```
-gh pr diff <number>                           # full diff
-gh pr view <number> --json title,body         # description
-gh pr checks <number>                         # CI status
-gh pr view <number> --json reviews,comments   # existing feedback — don't duplicate
-```
+Use the GitHub MCP tools (not `gh` CLI — credentials are scrubbed inside the agent container):
+
+- `get_pull_request` — read PR title, body, metadata
+- `list_pull_request_files` — list of changed files
+- `get_pull_request_diff` — full diff
+- `get_pull_request_reviews` and `list_pull_request_comments` — existing feedback (don't duplicate)
 
 Read `.github/copilot-instructions.md` from the repo checkout for project conventions, architecture, and review dimensions.
 
@@ -55,17 +55,17 @@ If a model is unavailable, proceed with the remaining models.
 ## 4. Post Results
 
 Before posting inline comments, validate **both** the file path AND line number:
-- **Path**: must be a file that appears in `gh pr diff --name-only`. Comments on files not in the diff cause the entire review to fail with "Path could not be resolved".
+- **Path**: must be a file that appears in the diff. Use `list_pull_request_files` MCP tool to get valid paths. Comments on files not in the diff cause the entire review to fail with "Path could not be resolved".
 - **Line**: must fall within a `@@` diff hunk for that file. Lines outside any hunk cause "Line could not be resolved".
 - **If either fails**: post the finding via `add_comment` as a design-level concern instead.
 
-Run `gh pr diff <number> --name-only` to get the list of valid paths before posting.
+Use `list_pull_request_files` to get the list of valid paths before posting.
 
 1. **Inline comments** — `create_pull_request_review_comment` for findings where BOTH path and line are valid
 2. **Design-level concerns** — `add_comment` for findings outside the diff (wrong path, wrong line, or design-level). One comment, multiple bullets.
 3. **Final verdict** — `submit_pull_request_review` with:
    - Findings ranked by severity with consensus markers (e.g., "3/3 reviewers")
    - CI status, test coverage assessment, prior review status
    - Never mention specific model names — use "Reviewer 1/2/3"
-   - `event: "REQUEST_CHANGES"` if any CRITICAL/MODERATE; `event: "COMMENT"` otherwise
+   - `event: "COMMENT"` always — severity is communicated via emoji markers in the body, not the review event type. (Using `REQUEST_CHANGES` causes stale blocking reviews that can't be dismissed by the agent.)
    - **Never use APPROVE**

.github/instructions/gh-aw-workflows.sync.yaml

@@ -0,0 +1,86 @@
+# Drift tracking manifest for gh-aw-guide skill
+# Used by the instruction-drift skill to detect when upstream sources change.
+# See .github/skills/instruction-drift/SKILL.md for details.
+
+target: ../skills/gh-aw-guide/SKILL.md
+secondary_targets:
+  - ../skills/gh-aw-guide/references/architecture.md
+
+# Sections containing our own operational knowledge (not from upstream).
+# The instruction-drift skill will never suggest removing these.
+divergence:
+  - section: "Security Boundaries"
+    reason: "Our defense-in-depth assessment and workflow author rules"
+  - section: "Safe Pattern: Checkout + Restore"
+    reason: "Documents our custom Checkout-GhAwPr.ps1 script"
+  - section: "Common Patterns"
+    reason: "Our specific usage patterns for pre-agent data prep, concurrency, noise reduction"
+
+sources:
+  # Reference documentation pages — check for content changes
+  # Core reference (high-change frequency)
+  - url: https://github.github.com/gh-aw/reference/triggers/
+    sections: ["Anti-Patterns", "Common Patterns", "Limitations"]
+  - url: https://github.github.com/gh-aw/reference/frontmatter/
+    sections: ["Anti-Patterns", "Architecture", "Additional Frontmatter Features"]
+  - url: https://github.github.com/gh-aw/reference/safe-outputs/
+    sections: ["Anti-Patterns", "Safe Outputs Quick Reference"]
+  - url: https://github.github.com/gh-aw/reference/safe-outputs-pull-requests/
+    sections: ["Safe Outputs Quick Reference"]
+  - url: https://github.github.com/gh-aw/reference/integrity/
+    sections: ["Security Boundaries"]
+    coverage_gaps:
+      - "endorsement-reactions / disapproval-reactions (v0.68.2+)"
+      - "approval-labels for promoting items"
+      - "allowed-repos scoping"
+      - "integrity-proxy: false opt-out"
+      - "centralized management via GH_AW_GITHUB_* variables"
+      - "effective integrity computation order"
+      - "DIFC_FILTERED logging and gh aw logs --filtered-integrity"
+      - "public repos auto-apply min-integrity: approved when unconfigured"
+      - "GitHub Actions expressions for blocked-users/trusted-users/approval-labels"
+  - url: https://github.github.com/gh-aw/reference/custom-safe-outputs/
+    sections: ["Anti-Patterns", "Safe Outputs Quick Reference"]
+  - url: https://github.github.com/gh-aw/reference/triggering-ci/
+    sections: ["Limitations", "Troubleshooting"]
+  - url: https://github.github.com/gh-aw/reference/command-triggers/
+    sections: ["Anti-Patterns"]
+
+  # Extended reference (lower change frequency, but contain important context)
+  - url: https://github.github.com/gh-aw/reference/engines/
+    sections: ["Additional Frontmatter Features"]
+  - url: https://github.github.com/gh-aw/reference/network/
+    sections: ["Security Boundaries"]
+  - url: https://github.github.com/gh-aw/reference/github-tools/
+    sections: ["Security Boundaries"]
+  - url: https://github.github.com/gh-aw/reference/imports/
+    sections: ["Common Patterns"]
+  - url: https://github.github.com/gh-aw/reference/workflow-structure/
+    sections: ["Architecture"]
+
+  # Patterns (best practices that inform our anti-patterns table)
+  - url: https://github.github.com/gh-aw/patterns/trial-ops/
+    sections: ["Common Patterns"]
+  - url: https://github.github.com/gh-aw/patterns/chat-ops/
+    sections: ["Common Patterns", "Anti-Patterns"]
+  - url: https://github.github.com/gh-aw/patterns/label-ops/
+    sections: ["Common Patterns"]
+
+  # Tracked GitHub issues — check open/closed state
+  # NOTE: Only set resolution_expected: true for issues whose closure
+  # has NOT yet been incorporated into our docs. All 5 below are already
+  # documented as resolved — no need to flag them on every run.
+  - issue: github/gh-aw#18481
+  - issue: github/gh-aw#18518
+  - issue: github/gh-aw#18521
+  - issue: github/gh-aw#23769
+  - issue: github/gh-aw#25439
+
+  # GitHub releases — check for new versions
+  - releases: github/gh-aw
+
+style: |
+  Match existing section structure. Use tables for feature comparisons.
+  Include code examples for common patterns. Mark items as anti-patterns
+  when a manual reimplementation should use a built-in feature instead.
+  Keep security guidance precise — never simplify away nuance.