Shift-left Azure SDK Architecture reviews: merge with REST API Stewardship Board, review in-PR on azure-rest-api-specs

## The pitch in one line

Combine the **Azure REST API Stewardship Board** and the **Azure SDK Architecture Board** into a single **Azure API Board** that reviews TypeSpec + every language's API surface together, in the same GitHub PR, in the `Azure/azure-rest-api-specs` repo.

## Background — how it works today

- **Azure REST API Stewardship Board** — reviews Azure service API specs for compliance with our guidelines. Currently reviews service teams' TypeSpec projects in PRs against `Azure/azure-rest-api-specs`.
- **Azure SDK Architecture Board** — reviews the API surface layer of Azure SDK libraries to make sure they follow per-language norms and our guidelines. Structure: one architect per language plus a deputy architect per language as backup.
- These reviews happen in **different places, at different times, by different people**, against the same underlying API.

## What we're proposing

- Merge the two boards into a single **Azure API Board** (working name).
- Treat REST API stewardship as one more "language" the board reviews, alongside the per-language architects.
- All reviews happen **in the service team's PR against `Azure/azure-rest-api-specs`**.
- Each architect reviews the file(s) for their language; REST stewardship reviewers review the TypeSpec.
- Cross-language discussion uses the PR Conversations tab.
- Architects can see each other's comments in one place.

## Hard dependency: move off the APIView site

The current APIView site is a separate web app. For this to work, APIView-style review needs to live **in the PR**. Team resources also can't sustain APIView site maintenance long-term, so this is both an enabling step and an anti-goal worth pursuing on its own.

**New goal:** an APIView-styled file (per language) is included in every service-team PR to `Azure/azure-rest-api-specs`. Architects review that file in the PR like any other diff.

---

## Work that has to happen for this to land

### 1. Generating the APIView-styled files

Two routes — both viable, both have tradeoffs.

#### Option A — Automation generates and commits

- When a service team opens / updates a PR against `Azure/azure-rest-api-specs`, automation runs and:
- Generates the SDK libraries from the TypeSpec (or, if possible, generates the APIView-styled files directly from TypeSpec without going through full library generation — preferred if feasible)
- Generates the APIView-styled files from those
- Commits those files back into the PR
- **Risk:** human and bot pushing to the same branch at the same time creates merge conflicts. Should be resolvable, but it's an assumption about how service teams will react to bot-authored commits on their branches that we can't fully verify until we try.

#### Option B — Azure SDK Tools Agent does it locally

- The agent already helps service teams author/update TypeSpec. Extend the agent so, as part of its validation flow (the step where it confirms the TypeSpec still compiles and the project is valid), it also regenerates / updates the APIView-styled files for each language SDK.
- When the service team opens the PR, those files go up with everything else.
- **Required:** a CI check on the PR that verifies the APIView-styled files match the current TypeSpec. Otherwise we can't be sure the service team kept the files up to date with their latest TypeSpec edits.

We don't have to pick yet — both could be prototyped in parallel.

### 2. Bring over the language-specific CI checks

Today each language SDK repo runs CI checks on its PRs that act as **pre-review gates** — they keep architects from burning time on libraries that aren't yet high enough quality to warrant review (catching trivial issues that should never reach a human reviewer).

Those checks need to run against the same APIView-styled files generated above, on the PR in `Azure/azure-rest-api-specs`. The checks have to be ported / wired in so the gating behavior survives the move.

### 3. APIView Diagnostics → PR check that comments on lines

This one is mechanically simple. GitHub PR CI checks can leave file-and-line-specific annotations and comments on a PR. Wire APIView Diagnostics to do exactly that: same diagnostics, same content, just delivered as inline PR comments on the APIView-styled file instead of inside the APIView site UI.

### 4. APIView Copilot → custom Copilot reviewer for the PR

APIView Copilot today is more than a prompt — it pulls from knowledge bases. A naive port to a GitHub Copilot reviewer (which is more like an instruction file) will lose capability.

Proposal: use this transition to **simplify the architecture** so architects can own and edit it directly.

- Architects own the source material (the guidelines).
- The Copilot reviewer **must always cite its sources** when leaving a comment — naming the specific guideline it's invoking.
- When a reviewer comment is bad, the architect can trace it straight to the guideline that needs updating.
- Drop the "self-improve based on architect scoring" loop in favor of this. The improvement path becomes: architects keep the guidelines accurate; the reviewer follows them; sourcing is mandatory.

Open question: how much of the existing APIView Copilot knowledge base maps cleanly to "guideline documents," and what gets dropped vs. ported.

---

## Why this is worth doing

- **One review surface.** Service teams don't bounce between APIView and GitHub. Architects don't either.
- **Reviews happen earlier.** Architecture feedback lands while the team is still editing TypeSpec, not after libraries have been generated and they've moved on.
- **Less infra to maintain.** APIView site goes away (or shrinks dramatically).
- **Cross-language consistency.** All architects see each other's comments and can have those discussions in the PR Conversations tab.

## Open questions / unknowns

- Can APIView-styled files be generated directly from TypeSpec, or do we have to go through full library generation first?
- How do service teams react to bot commits on their branches (Option A) vs. the extra agent step locally (Option B)?
- What's the migration plan for in-flight reviews on the APIView site when the cutover happens?
- What happens to APIView's revision history and existing review comments?
- Does the merged board need new governance / RACI, or does it inherit from the two existing boards?

Start by reading the proposed workflow in Azure/azure-rest-api-specs, then inspect the Azure SDK Tools Agent, APIView Diagnostics, and APIView Copilot components mentioned in the issue. The work is done when APIView-styled files, language-specific CI gates, inline diagnostics, and the Copilot reviewer operate in the service team's GitHub PR, with a migration approach for existing reviews.

Written by the indexing model from the issue text.