Add vmr-codeflow-status Copilot skill

.github/skills/vmr-codeflow-status/SKILL.md

@@ -0,0 +1,114 @@
+---
+name: vmr-codeflow-status
+description: Analyze VMR codeflow PR status for dotnet repositories. Use when investigating stale codeflow PRs, checking if fixes have flowed through the VMR pipeline, or debugging dependency update issues in PRs authored by dotnet-maestro[bot].
+---
+
+# VMR Codeflow Status
+
+Analyze the health of VMR codeflow PRs (backflow from `dotnet/dotnet` to product repositories like `dotnet/sdk`).
+
+## When to Use This Skill
+
+Use this skill when:
+- A codeflow PR (from `dotnet-maestro[bot]`) has failing tests and you need to know if it's stale
+- You need to check if a specific fix has flowed through the VMR pipeline to a codeflow PR
+- A PR has a Maestro staleness warning ("codeflow cannot continue") or conflict
+- You need to understand what manual commits would be lost if a codeflow PR is closed
+- You want to know if expected backflow PRs are missing for a repo/branch
+- Asked questions like "is this codeflow PR up to date", "has the runtime revert reached this PR", "why is the codeflow blocked"
+
+## Quick Start
+
+```powershell
+# Check codeflow PR status (most common)
+./scripts/Get-CodeflowStatus.ps1 -PRNumber 52727 -Repository "dotnet/sdk"
+
+# Trace a specific fix through the pipeline
+./scripts/Get-CodeflowStatus.ps1 -PRNumber 52727 -Repository "dotnet/sdk" -TraceFix "dotnet/runtime#123974"
+
+# Show individual VMR commits that are missing
+./scripts/Get-CodeflowStatus.ps1 -PRNumber 52727 -Repository "dotnet/sdk" -ShowCommits
+
+# Check if any backflow PRs are missing for a repo
+./scripts/Get-CodeflowStatus.ps1 -Repository "dotnet/roslyn" -CheckMissing
+
+# Check a specific branch only
+./scripts/Get-CodeflowStatus.ps1 -Repository "dotnet/sdk" -CheckMissing -Branch "main"
+```
+
+## Key Parameters
+
+| Parameter | Description |
+|-----------|-------------|
+| `-PRNumber` | GitHub PR number to analyze (required unless `-CheckMissing`) |
+| `-Repository` | Target repo in `owner/repo` format (default: `dotnet/sdk`) |
+| `-TraceFix` | Trace a repo PR through the pipeline (e.g., `dotnet/runtime#123974`) |
+| `-ShowCommits` | Show individual VMR commits between PR snapshot and branch HEAD |
+| `-CheckMissing` | Check if backflow PRs are expected but missing for a repository |
+| `-Branch` | With `-CheckMissing`, only check a specific branch |
+
+## What the Script Does
+
+1. **Parses PR metadata** — Extracts VMR commit, subscription ID, build info from PR body
+2. **Validates snapshot** — Cross-references PR body commit against branch commit messages to detect stale metadata
+3. **Checks VMR freshness** — Compares PR's VMR snapshot against current VMR branch HEAD
+4. **Shows pending forward flow** — For behind backflow PRs, finds open forward flow PRs that would close part of the gap
+5. **Detects staleness & conflicts** — Finds Maestro "codeflow cannot continue" warnings and "Conflict detected" messages with file lists and resolve commands
+6. **Analyzes PR commits** — Categorizes as auto-updates vs manual commits
+7. **Traces fixes** (optional) — Checks if a specific fix has flowed through VMR → codeflow PR
+8. **Recommends actions** — Suggests force trigger, close/reopen, merge as-is, resolve conflicts, or wait
+9. **Checks for missing backflow** (optional) — Finds branches where a backflow PR should exist but doesn't
+
+## Interpreting Results
+
+### Freshness
+- **✅ Up to date**: PR has the latest VMR snapshot
+- **⚠️ VMR is N commits ahead**: The PR is missing updates. Check if the missing commits contain the fix you need.
+- **📊 Forward flow coverage**: Shows how many missing repos have pending forward flow PRs that would close part of the gap once merged.
+
+### Snapshot Validation
+- **✅ Match**: PR body commit matches the branch's actual "Backflow from" commit
+- **⚠️ Mismatch**: PR body is stale — the script automatically uses the branch-derived commit for freshness checks
+- **ℹ️ Initial commit only**: PR body can't be verified yet (no "Backflow from" commit exists)
+
+### Staleness & Conflicts
+- **✅ No warnings**: Maestro can freely update the PR
+- **⚠️ Staleness warning**: A forward flow merged while this backflow PR was open. Maestro blocked further updates.
+- **🔴 Conflict detected**: Maestro found merge conflicts. Shows conflicting files and `darc vmr resolve-conflict` command.
+
+### Manual Commits
+Manual commits on the PR branch are at risk if the PR is closed or force-triggered. The script lists them so you can decide whether to preserve them.
+
+### Fix Tracing
+When using `-TraceFix`:
+- **✅ Fix is in VMR manifest**: The fix has flowed to the VMR
+- **✅ Fix is in PR snapshot**: The codeflow PR already includes this fix
+- **❌ Fix is NOT in PR snapshot**: The PR needs a codeflow update to get this fix
+
+## Darc Commands for Remediation
+
+After analyzing the codeflow status, common next steps involve `darc` commands:
+
+```bash
+# Force trigger the subscription to get a fresh codeflow update
+darc trigger-subscriptions --id <subscription-id> --force
+
+# Normal trigger (only works if not stale)
+darc trigger-subscriptions --id <subscription-id>
+
+# Check subscription details
+darc get-subscriptions --target-repo dotnet/sdk --source-repo dotnet/dotnet
+
+# Get BAR build details
+darc get-build --id <bar-build-id>
+
+# Resolve codeflow conflicts locally
+darc vmr resolve-conflict --subscription <subscription-id>
+```
+
+Install darc via `eng\common\darc-init.ps1` in any arcade-enabled repository.
+
+## References
+
+- **VMR codeflow concepts**: See [references/vmr-codeflow-reference.md](references/vmr-codeflow-reference.md)
+- **Codeflow PR documentation**: [dotnet/dotnet Codeflow-PRs.md](https://github.com/dotnet/dotnet/blob/main/docs/Codeflow-PRs.md)

.github/skills/vmr-codeflow-status/references/vmr-codeflow-reference.md

@@ -0,0 +1,144 @@
+# VMR Codeflow Reference
+
+## Key Concepts
+
+### Codeflow Types
+- **Backflow** (VMR → product repo): Automated PRs created by Maestro that bring VMR source updates + dependency updates into product repos (e.g., `dotnet/sdk`). These are titled `[branch] Source code updates from dotnet/dotnet`.
+- **Forward flow** (product repo → VMR): Changes from product repos flowing into the VMR. These are titled `[branch] Source code updates from dotnet/<repo>`.
+
+### Staleness
+When a product repo pushes changes to the VMR (forward flow merges) while a backflow PR is already open, Maestro blocks further codeflow updates to that PR. The bot posts a warning comment with options:
+1. Merge the PR as-is, then Maestro creates a new PR with remaining changes
+2. Close the PR and let Maestro open a fresh one (loses manual commits)
+3. Force trigger: `darc trigger-subscriptions --id <subscription-id> --force` (manual commits may be reverted)
+
+### Key Files
+- **`src/source-manifest.json`** (in VMR): Tracks the exact commit SHA for each product repo synchronized into the VMR. This is the authoritative source of truth.
+- **`eng/Version.Details.xml`** (in product repos): Tracks dependencies and includes a `<Source>` tag for codeflow tracking.
+
+## PR Body Metadata Format
+
+Codeflow PRs have structured metadata in their body:
+
+```
+[marker]: <> (Begin:<subscription-id>)
+## From https://github.com/dotnet/dotnet
+- **Subscription**: [<subscription-id>](https://maestro.dot.net/subscriptions?search=<subscription-id>)
+- **Build**: [<build-number>](<azdo-build-url>) ([<bar-id>](<maestro-channel-url>))
+- **Date Produced**: <date>
+- **Commit**: [<vmr-commit-sha>](<vmr-commit-url>)
+- **Commit Diff**: [<from>...<to>](<compare-url>)
+- **Branch**: [<branch>](<branch-url>)
+[marker]: <> (End:<subscription-id>)
+```
+
+## Darc CLI Commands
+
+The `darc` tool (Dependency ARcade) manages dependency flow in the .NET ecosystem. Install via `eng\common\darc-init.ps1` in any arcade-enabled repo.
+
+### Essential Commands for Codeflow Analysis
+
+#### Get subscription details
+```bash
+# Find all subscriptions flowing to a repo
+darc get-subscriptions --target-repo dotnet/sdk --source-repo dotnet/dotnet
+
+# Output shows subscription ID, channel, update frequency, merge policies
+```
+
+#### Trigger a codeflow update
+```bash
+# Normal trigger (only works if not stale)
+darc trigger-subscriptions --id <subscription-id>
+
+# Force trigger (works even when stale, but may revert manual commits)
+darc trigger-subscriptions --id <subscription-id> --force
+
+# Trigger with a specific build
+darc trigger-subscriptions --id <subscription-id> --build <bar-build-id>
+```
+
+#### Get build information
+```bash
+# Get BAR build details by ID (found in PR body or AzDO logs)
+darc get-build --id <bar-build-id>
+
+# Get latest build for a repo on a channel
+darc get-latest-build --repo dotnet/dotnet --channel ".NET 11 Preview 1"
+```
+
+#### Check subscription health
+```bash
+# See if dependencies are missing subscriptions or have issues
+darc get-health --channel ".NET 11 Preview 1"
+```
+
+#### Simulate a subscription update locally
+```bash
+# Dry-run to see what a subscription would update
+darc update-dependencies --subscription <subscription-id> --dry-run
+```
+
+### VMR-Specific Commands
+
+```bash
+# Resolve codeflow conflicts locally
+darc vmr resolve-conflict --subscription <subscription-id> --build <bar-build-id>
+
+# Flow source from VMR → local repo
+darc vmr backflow --subscription <subscription-id>
+
+# Flow source from local repo → local VMR
+darc vmr forwardflow --subscription <subscription-id>
+
+# Get version (SHA) of a repo in the VMR
+darc vmr get-version
+
+# Diff VMR vs product repos
+darc vmr diff
+```
+
+### Halting and Restarting Dependency Flow
+
+- **Disable default channel**: `darc default-channel-status --disable --id <id>` — stops new builds from flowing
+- **Disable subscription**: `darc subscription-status --disable --id <id>` — stops flow between specific repos
+- **Pin dependency**: Add `Pinned="true"` to dependency in `Version.Details.xml` — prevents specific dependency from updating
+
+## API Endpoints
+
+### GitHub API
+- PR details: `GET /repos/{owner}/{repo}/pulls/{pr_number}`
+- PR comments: `GET /repos/{owner}/{repo}/issues/{pr_number}/comments`
+- PR commits: `GET /repos/{owner}/{repo}/pulls/{pr_number}/commits`
+- Compare commits: `GET /repos/{owner}/{repo}/compare/{base}...{head}`
+- File contents: `GET /repos/{owner}/{repo}/contents/{path}?ref={branch}`
+
+### VMR Source Manifest
+```
+GET /repos/dotnet/dotnet/contents/src/source-manifest.json?ref={branch}
+```
+Returns JSON with `repositories[]` array, each having `path`, `remoteUri`, `commitSha`.
+
+### Maestro/BAR REST API
+Base URL: `https://maestro.dot.net`
+- Swagger: `https://maestro.dot.net/swagger`
+- Get subscriptions: `GET /api/subscriptions`
+- Get builds: `GET /api/builds`
+- Get build by ID: `GET /api/builds/{id}`
+
+## Common Scenarios
+
+### 1. Codeflow is stale — a fix landed but hasn't reached the PR
+**Symptoms**: Tests failing on the codeflow PR; the fix is merged in a product repo.
+**Diagnosis**: Compare `source-manifest.json` on VMR branch HEAD vs the PR's VMR snapshot commit.
+**Resolution**: Close PR + reopen, or force trigger the subscription.
+
+### 2. Opposite codeflow merged — staleness warning
+**Symptoms**: Maestro bot comment saying "codeflow cannot continue".
+**Diagnosis**: Check PR comments for the warning. Check if forward flow PRs merged after the backflow PR was opened.
+**Resolution**: Follow the options in the bot's comment.
+
+### 3. Manual commits on the codeflow PR
+**Symptoms**: Developers added manual fixes to unblock the PR (baseline updates, workarounds).
+**Diagnosis**: Analyze PR commits to identify non-maestro commits.
+**Risk**: Closing the PR loses these. Force-triggering may revert them.