feat: gh-aw skills, security scanner, and instruction drift tooling

.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"
-   - Always use `event: "COMMENT"` — blocking `REQUEST_CHANGES` reviews can't be auto-dismissed on re-review and cause stale blocks (see gh-aw limitation)
-   - **Never use APPROVE or REQUEST_CHANGES**
+   - `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.instructions.md

@@ -6,29 +6,35 @@ applyTo:
 
 # gh-aw (GitHub Agentic Workflows) Guidelines
 
-> **Full documentation:** Read the `gh-aw-guide` skill (`.github/skills/gh-aw-guide/SKILL.md`) for complete coverage including anti-patterns table, common patterns, security boundaries, and architecture deep-dive.
+When working on gh-aw workflow files, use the **`gh-aw-guide`** skill for the complete reference (architecture, security, safe outputs, fork handling, anti-patterns, troubleshooting).
 
 ## Essential Rules
 
-1. **Never edit `.lock.yml` files** — they're auto-generated by `gh aw compile`. Always commit the lock file alongside the source `.md`.
-2. **Prefer built-in gh-aw features** over manual reimplementations — check the [triggers](https://github.github.com/gh-aw/reference/triggers/), [frontmatter](https://github.github.com/gh-aw/reference/frontmatter/), and [safe-outputs](https://github.github.com/gh-aw/reference/safe-outputs/) references first.
-3. **Use `slash_command:` trigger** instead of `issue_comment` + `startsWith(comment.body, '/cmd')`.
-4. **Use `steps:` for GitHub API calls** — `gh` CLI credentials are scrubbed inside the agent container.
-5. **Never execute untrusted PR code** (`dotnet build`, `npm install`) inside the agent — build hooks can read `COPILOT_TOKEN`.
-6. **Use `Checkout-GhAwPr.ps1`** for `workflow_dispatch` triggers to check out the PR branch and restore trusted `.github/` from base.
-7. **Include all PR number sources** in concurrency groups: `github.event.issue.number || github.event.pull_request.number || inputs.pr_number || github.run_id`.
-8. **Block agent PR approvals** with `allowed-events: [COMMENT]` on `submit-pull-request-review` (see rule 10).
-9. **Split `slash_command` + `pull_request`** into separate workflow files importing a shared `shared/*.md` — the compiler rejects them in the same file.
-10. **COMMENT-only reviews** — use `allowed-events: [COMMENT]` (not `REQUEST_CHANGES`) to avoid stale blocking reviews that can't be auto-dismissed. See the "Known Limitation: Stale Blocking Reviews" section in the `gh-aw-guide` skill.
+1. **Never edit `.lock.yml` files manually** — they are auto-generated by `gh aw compile`
+2. **Always compile after changes**: `gh aw compile .github/workflows/<name>.md`
+3. **Always commit the lock file** alongside the source `.md`
+4. **Prefer built-in gh-aw features** over manual reimplementations — invoke the `gh-aw-guide` skill for the complete anti-patterns table before implementing triggers, outputs, or scheduling manually
+5. **Never execute untrusted PR code** with elevated credentials — treat PR contents as passive data only
+6. **Never approve PRs from workflows** — use `allowed-events: [COMMENT]` on `submit-pull-request-review` to block approvals. Prefer `[COMMENT]` over `[COMMENT, REQUEST_CHANGES]` — `REQUEST_CHANGES` reviews from `github-actions[bot]` cannot be dismissed by the agent (no `dismiss-pull-request-review` safe output), causing stale blocking reviews (gh-aw#25439)
+7. **Always use `github-token-for-extra-empty-commit:`** (PAT/App token) on `create-pull-request` — `GITHUB_TOKEN` pushes do not trigger CI
+8. **Set `protected-files: fallback-to-issue`** on `create-pull-request` when the agent may touch package manifests or `.github/` — prevents PR creation from failing silently
+9. **Use `Checkout-GhAwPr.ps1`** for `workflow_dispatch` workflows that check out a PR — it verifies write access and restores trusted `.github/` from base branch
+10. **Set `min-integrity: approved`** on `tools.github` for workflows that process external PR content — prevents prompt injection from first-timer/contributor comments
 
-## Quick Anti-Pattern Check
+## Quick Anti-Pattern Check (Critical Subset)
+
+These are the most commonly missed built-in replacements. **Invoke the `gh-aw-guide` skill for the complete 21-row table** — this list covers only the highest-impact items:
 
 | If you're about to implement... | Use this built-in instead |
 |---------------------------------|--------------------------|
 | `issue_comment` + `startsWith(comment.body, '/cmd')` | `slash_command:` trigger |
-| Manual emoji reaction on triggering comment | `reaction:` field under `on:` |
-| Posting "workflow started/completed" status comments | `status-comment: true` under `on:` |
-| Editing old comments to collapse them | `hide-older-comments: true` on `add-comment:` |
-| Triggering CI on agent-created PRs | `github-token-for-extra-empty-commit:` on `create-pull-request` |
+| Triggering CI on agent-created PRs manually | `github-token-for-extra-empty-commit:` on `create-pull-request` |
+| No guard against agent approving PRs | `allowed-events: [COMMENT]` on `submit-pull-request-review` (avoids stale blocking reviews) |
+| Manual role/bot filtering with `if:` conditions | `skip-bots:`, `skip-roles:` under `on:` |
+| Manual approval gating before workflow runs | `manual-approval:` under `on:` |
+| Manual label check + removal for one-shot commands | `label_command:` trigger |
+| `slash_command:` without `events:` filter | `events: [pull_request_comment]` — default subscribes to ALL comment events |
+| `cancel-in-progress: true` on `slash_command:` workflows | `cancel-in-progress: false` — prevents non-matching events from killing agent runs |
+| Using `pull_request` trigger for agentic workflows | `slash_command:` or `schedule` — `pull_request` causes the "Approve and run" gate for ALL workflows |
 
-See `.github/skills/gh-aw-guide/SKILL.md` for the full 19-row anti-patterns table.
+For the complete anti-patterns table, architecture, security model, fork handling, and all safe output options, invoke the **`gh-aw-guide`** skill.

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

@@ -1,52 +1,92 @@
-# Sync manifest for gh-aw workflow instructions
-# Used by the instruction-drift skill to detect when upstream docs change.
-# Run: pwsh .github/skills/instruction-drift/scripts/Check-Staleness.ps1 -SyncManifest .github/instructions/gh-aw-workflows.sync.yaml
-
-sync:
-  target: "../skills/gh-aw-guide/SKILL.md"
-  secondary_targets:
-    - "../skills/gh-aw-guide/references/architecture.md"
-
-  # Upstream documentation pages to monitor for changes
-  reference_urls:
-    - https://github.github.com/gh-aw/reference/triggers/
-    - https://github.github.com/gh-aw/reference/frontmatter/
-    - https://github.github.com/gh-aw/reference/safe-outputs/
-    - https://github.github.com/gh-aw/reference/command-triggers/
-    - https://github.github.com/gh-aw/reference/custom-safe-outputs/
-    - https://github.github.com/gh-aw/reference/triggering-ci/
-    - https://github.github.com/gh-aw/patterns/monitoring/
-    - https://securitylab.github.com/resources/github-actions-preventing-pwn-requests/
-
-  # GitHub issues whose resolution may require instruction updates
-  tracked_issues:
-    - url: https://github.com/github/gh-aw/issues/18481
-      status: closed
-      note: "Fork support tracking — all sub-items shipped"
-    - url: https://github.com/github/gh-aw/issues/18518
-      status: closed
-      note: "gh aw init now warns in forks"
-    - url: https://github.com/github/gh-aw/issues/18521
-      status: closed
-      note: "Fork support docs created"
-    - url: https://github.com/github/gh-aw/issues/23769
-      status: closed
-      note: "Platform auto-restores .github/ from base branch"
-    - url: https://github.com/github/gh-aw/issues/25439
-      status: closed
-      note: "submit-pull-request-review allowed-events fix shipped"
-    # PolyPilot-specific: tracking the stale review gap
-    # gh-aw#25869 — another team independently adopted COMMENT-only workaround
-    # No upstream issue for supersede-older-reviews yet; monitor gh-aw releases
-
-  # Sections that intentionally diverge from upstream / other repos
-  divergence_sections:
-    - "Known Limitation: Stale Blocking Reviews"
-    - "Security Boundaries"
-    - "Safe Pattern: Checkout + Restore"
-    - "Common Patterns"
-
-  # Monitor for new gh-aw platform releases
-  releases_source: https://github.com/github/gh-aw/releases.atom
-
-  last_reviewed: "2025-07-14"
+# 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
+    # Tracked upstream issues — all resolved. resolution_expected: true means
+  # the script expects them closed and won't flag them as stale.
+  - issue: github/gh-aw#18481
+    resolution_expected: true
+  - issue: github/gh-aw#18518
+    resolution_expected: true
+  - issue: github/gh-aw#18521
+    resolution_expected: true
+  - issue: github/gh-aw#23769
+    resolution_expected: true
+  - issue: github/gh-aw#25439
+    resolution_expected: true
+
+  # 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.