maf-release-watcher

maf-release-watcher

Purpose

When Microsoft ships a new MAF version, this pipeline keeps the toolkit's three artefacts current with zero manual baseline-update work:

• .maf-version — the tracked-current pointer
• docs/compatibility-matrix.md — dependency-version table (new row per release)
• guides/maf-X.Y.Z-migration-guide.md — per-version delta with banner pointing back to the chain
• guides/maf-current-migration-guide.md — auto-regenerated cumulative reference
• .github/skills/maf-obsolete-api-registry/registry.yaml — append-only breaking-change registry

Three of those (matrix row contents, per-version guide sections, registry-entry TODO fields) need judgement the deterministic pipeline can't automate: release notes have to be interpreted and before/after C# examples written. That work runs in the maf-registry-fill agentic workflow (GitHub Agentic Workflows, Copilot engine), which fills the scaffold PR in place.

---

When this skill is "invoked"

It isn't, in the Copilot-Chat sense. The work runs in GitHub Actions VMs, not in a Copilot conversation. This skill is the reference doc explaining what those workflows do, so a maintainer reading the repo can understand the whole loop without piecing it together from two .yml files plus three Python scripts.

Triggers for the pipeline itself:

• Weekly cron: 0 6 * * 4 (Thursday 06:00 UTC) — defined in .github/workflows/maf-release-watcher.yml
• Manual dispatch: gh workflow run maf-release-watcher.yml -f maf_version=X.Y.Z

---

Architecture — the three stages

TRIGGER (cron or gh workflow run)
   │
   ▼
┌────────────────────────────────────────────────────────────────────┐
│  STAGE 1 — Deterministic data extraction                           │
│  .github/workflows/maf-release-watcher.yml                         │
│  Runs on a fresh Ubuntu VM provisioned by GitHub Actions           │
│  NO LLM, NO AGENT — just shell + Python + dotnet CLI               │
├────────────────────────────────────────────────────────────────────┤
│                                                                    │
│  1.1  Select oldest untracked MAF stable from NuGet                │
│       (clean no-op while any watcher scaffold PR is in flight)     │
│  1.2  Resolve + diff the targeted release-critical package surfaces│
│  1.3  Fetch GitHub release notes from microsoft/agent-framework    │
│  1.4  Run `python3 .github/scripts/update_compat_matrix.py`        │
│          → inserts a new row at the top of compatibility-matrix.md │
│  1.5  Run `python3 .github/scripts/gen_guide_section.py`           │
│          → writes guides/maf-X.Y.Z-migration-guide.md              │
│          → ALSO regenerates guides/maf-current-migration-guide.md  │
│  1.6  Run `registry-extract --diff-file` for validated surfaces   │
│          → scoped drafts, no second network diff, then de-duplicate │
│  1.7  Update .maf-version                                          │
│  1.8  Upload plan/diff+extraction ledgers/diff-*.txt/notes         │
│          as workflow artefacts for reviewer audit                  │
│  1.9  git checkout -b release-watcher/maf-X.Y.Z                    │
│       git commit + git push (per-version branch, NOT main)         │
│  1.10 gh pr create --base main --head release-watcher/maf-X.Y.Z    │
│       (never commits to main; one watcher PR open at a time; an    │
│        open one warns after 7 days and fails the watcher at 14)    │
│                                                                    │
└────────────────────────────────────────────────────────────────────┘
                                  │ pull_request: opened
                                  ▼
┌────────────────────────────────────────────────────────────────────┐
│  STAGE 2 — Agentic fill                                            │
│  .github/workflows/maf-registry-fill.md (compiled .lock.yml)       │
│  Copilot engine inside the workflow; THIS is the LLM part          │
├────────────────────────────────────────────────────────────────────┤
│  2.1  Follows .github/scripts/ai_fill_issue_prompt.md.tpl          │
│  2.2  Fills registry TODOs, guide sections, matrix row,            │
│       CompatibilityTool.cs; replaces each REVIEW sentinel with a   │
│       NEW same-package entry                                       │
│  2.3  Runs the release checklist (checks 1-11, incl. the CI        │
│       obligations gate) and iterates until it passes               │
│  2.4  Pushes to the PR branch via safe outputs (data files only)   │
│       and comments a summary for the reviewer                      │
└────────────────────────────────────────────────────────────────────┘
                                  │ pull_request: synchronize
                                  ▼
┌────────────────────────────────────────────────────────────────────┐
│  STAGE 3 — Gates and merge                                         │
├────────────────────────────────────────────────────────────────────┤
│  3.1  maf-ai-fill-verify (required): obligations contract, train   │
│       lock immutability, sentinel rule, verify-registry, cross-    │
│       file consistency, autonomy envelope (data paths only)        │
│  3.2  build-test + ci-invariants (required)                        │
│  3.3  Additive release: auto-merge. Breaking: maintainer review.   │
│  3.4  maf-doctor release: push a vX.Y.Z tag → release.yml          │
└────────────────────────────────────────────────────────────────────┘