Enforce gh aw compile + lock-file regeneration for agentic workflows (#4298)

Author: priyankatiwari08

.github/instructions/agentic-workflows.instructions.md

@@ -0,0 +1,49 @@
+---
+applyTo: ".github/workflows/**/*.md"
+description: Rules for editing gh-aw agentic workflow Markdown files.
+---
+
+# Agentic Workflow Edit Rules (`gh aw`)
+
+This repository authors GitHub Actions agentic workflows in Markdown using
+[`gh aw`](https://github.com/githubnext/gh-aw). Each workflow `.md` file under
+`.github/workflows/` compiles to a sibling `.lock.yml`, and **only the
+`.lock.yml` is executed by GitHub Actions at runtime.**
+
+## Mandatory rule
+
+Whenever you create, edit, rename, or delete a file matching
+`.github/workflows/**/*.md`, you **MUST**, in the **same commit / PR**:
+
+1. Run `gh aw compile` from the repository root.
+2. Stage and commit the regenerated sibling `<name>.lock.yml`.
+3. If you deleted a workflow `.md`, also delete its `.lock.yml`.
+
+If the `.lock.yml` is stale or missing, the workflow fails at runtime
+(see PR #4279 for the exact failure mode). The
+`Verify gh aw lock files` CI check will block the PR in that case.
+
+## How to verify locally
+
+```bash
+gh aw compile
+git status        # both the .md and .lock.yml should appear
+gh aw compile     # second run must be a no-op (clean diff)
+```
+
+## Code-review checklist
+
+When reviewing a PR that touches `.github/workflows/**/*.md`:
+
+- [ ] A matching `.lock.yml` is updated in the same PR.
+- [ ] `gh aw compile` produces no further diff on top of the PR.
+- [ ] If new tools, network endpoints, or permissions are added in the `.md`,
+      they are present in the regenerated `.lock.yml`.
+
+## Out of scope
+
+- Do **not** hand-edit `.lock.yml` files. They are generated; edit the `.md`
+  source and recompile.
+- For deeper authoring guidance (creating, debugging, upgrading workflows),
+  invoke the `agentic-workflows` agent at
+  `.github/agents/agentic-workflows.agent.md`.

.github/workflows/verify-aw-lock.yml

@@ -0,0 +1,32 @@
+name: Verify gh aw lock files
+
+on:
+  pull_request:
+    paths:
+      - '.github/workflows/**/*.md'
+      - '.github/workflows/**/*.lock.yml'
+
+permissions:
+  contents: read
+
+jobs:
+  verify:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install gh-aw extension
+        uses: github/gh-aw-actions/setup-cli@bc56a0cad2f450c562810785ef38649c04db812a # v0.72.1
+        with:
+          version: v0.72.1
+
+      - name: Recompile agentic workflows
+        run: gh aw compile
+
+      - name: Fail if any .lock.yml is out of date
+        run: |
+          if ! git diff --exit-code -- '.github/workflows/**/*.lock.yml'; then
+            echo "::error::One or more .github/workflows/**/*.lock.yml files are out of date relative to their .md source (running 'gh aw compile' produced a diff)."
+            echo "::error::Run 'gh aw compile' locally and commit the regenerated .lock.yml files in this PR."
+            exit 1
+          fi