Merge branch 'main' into dev/jacquelinezhong/fix-657-sort-id-index-first

Author: tnaum-ms

.github/copilot-instructions.md

@@ -61,8 +61,8 @@ Before finishing work on a PR, agents **must** run the following steps in order:
 
 ## Branching
 
-- **`next`**: Target branch for PRs (default)
-- **`main`**: Production releases only
+- **`main`**: Default branch; all PRs target it.
+- **`release/<X.Y>`**: Short-lived stabilization branches cut from `main` at freeze; release tags (`vX.Y.0`, `vX.Y.1`, …) live here.
 
 ## TypeScript Guidelines
 

.github/skills/accessibility-aria-expert/SKILL.md

@@ -171,7 +171,7 @@ Voice control users say "click Refresh" – only works if accessible name contai
 ✅ **Fix**: Use the `Announcer` component
 
 ```tsx
-import { Announcer } from '../../api/webview-client/accessibility';
+import { Announcer } from '<relative-path>/components/accessibility';
 
 // Announces when `when` transitions from false to true
 <Announcer when={isLoading} message={l10n.t('Loading...')} />
@@ -265,7 +265,7 @@ For keyboard-accessible badges with tooltips:
 Use the `Announcer` component for WCAG 4.1.3 (Status Messages) compliance.
 
 ```tsx
-import { Announcer } from '../../api/webview-client/accessibility';
+import { Announcer } from '<relative-path>/components/accessibility';
 ```
 
 ### Basic Usage

.github/skills/react-webview-architecture/SKILL.md

@@ -38,7 +38,7 @@ root.render(
 
 - **`DynamicThemeProvider`** — adapts Fluent UI theming to VS Code's active color theme
 - **`WithWebviewContext`** — provides `vscodeApi` (postMessage) via React Context
-- **`WebviewRegistry`** — maps webview names → React components (in `api/configuration/WebviewRegistry`)
+- **`WebviewRegistry`** — maps webview names → React components (in `_integration/WebviewRegistry`)
 
 Configuration from the extension host is read via `useConfiguration<T>()`.
 

.github/skills/react-webview-architecture/references/REACT_ARCHITECTURE_GUIDELINES.md

@@ -784,7 +784,7 @@ trpcClient.common.reportEvent
 The webview rendering pipeline starts in `index.tsx`:
 
 ```tsx
-import { WebviewRegistry } from './api/configuration/WebviewRegistry';
+import { WebviewRegistry } from './_integration/WebviewRegistry';
 import { DynamicThemeProvider } from './theme/DynamicThemeProvider';
 import { WithWebviewContext } from './WebviewContext';
 

.github/skills/review-external-pr/SKILL.md

@@ -1,101 +1,195 @@
 ---
 name: review-external-pr
-description: Prepare an external contributor's PR for maintainer review by redirecting it into a dedicated review branch, then merging and creating a new finalization PR targeting next. Use when triaging/reviewing contributor PRs, merging external PRs with maintainer changes, or setting up a review workflow for incoming community contributions.
+description: Triage an external contributor's PR and prepare it for merge. Detects push permission, base branch, draft state, size, and history quality, then picks one of three paths (review-only, direct push to contributor branch, or a `reviews/` staging branch). Use when triaging or reviewing a community PR, deciding whether maintainer changes are needed, choosing a merge strategy (squash/merge/rebase), or merging an external contribution.
 ---
 
 # Review External PR Workflow
 
-Redirects an external contributor's PR into a `reviews/` staging branch so a maintainer can inspect, add changes, then merge everything into `next` cleanly.
+A triage-first workflow for handling community PRs. The skill **inspects first, asks two questions, then executes**. It never creates branches preemptively.
 
 ## When to Use
 
-- An external contributor opened a PR targeting `next` and you want to add changes before merging
-- You want to formally review and finalize a community contribution
-- You want the contributor to get proper merge credit while still controlling what lands in `next`
+- A contributor PR is open and you want to review and merge it
+- Trigger phrases: "prepare this external PR", "review PR #N", "let's review this contribution", or invocation while the user is on a `pr/<owner>/<PR_NUMBER>` branch (created by `gh pr checkout`)
+- You want a recommendation on push path and merge strategy before doing anything
 
-## Workflow Steps
+## Phase 1 — Triage (read-only, no prompts)
 
-### 1. Gather PR Info
+### Identify the PR
+
+Resolve, in order:
+
+1. The PR number the user mentioned.
+2. Current branch matches `pr/<owner>/<PR_NUMBER>` → extract `<PR_NUMBER>`.
+3. `gh pr status` → active PR for current branch.
+
+### Fetch metadata in one call
 
 ```bash
-gh pr view <PR_NUMBER> --json title,author,headRefName,baseRefName,body
+gh pr view <PR_NUMBER> --json number,title,author,url,state,isDraft,\
+headRefName,baseRefName,headRepositoryOwner,maintainerCanModify,\
+mergeable,mergeStateStatus,additions,deletions,changedFiles,commits,labels
 ```
 
-Note the **PR number**, **title**, and **author login** — you'll need them for branch naming and PR descriptions.
+### Derive signals
 
-### 2. Create the Review Branch
+| Signal          | Rule                                                                                                                          |
+| --------------- | ----------------------------------------------------------------------------------------------------------------------------- | ----- | -------------- | ---- | ------ | ----- |
+| `canPushToHead` | `headRepositoryOwner.login == "microsoft"` OR `maintainerCanModify`                                                           |
+| `baseBranch`    | `baseRefName` (do **not** hardcode `main`)                                                                                    |
+| `isDraft`       | warn if `true`                                                                                                                |
+| `mergeable`     | warn if `mergeable != "MERGEABLE"` (values: `MERGEABLE`, `CONFLICTING`, `UNKNOWN`)                                            |
+| `mergeReady`    | warn if `mergeStateStatus` is not `CLEAN` (other values: `DIRTY`, `BLOCKED`, `BEHIND`, `UNSTABLE`, `HAS_HOOKS`, `UNKNOWN`)    |
+| `commitCount`   | `commits.length`                                                                                                              |
+| `messyHistory`  | any `commits[].messageHeadline` (the first line of the commit message, returned by `gh pr view --json commits`) matches `/wip | fixup | address review | typo | merge( | $)/i` |
+| `changedLines`  | `additions + deletions`                                                                                                       |
+| `sizeBucket`    | small ≤ 50 changed lines, medium ≤ 300, large > 300 (uses `changedLines`)                                                     |
 
-Branch naming format: `reviews/<helpful-name>-original-pr-<number>`
+### Squash recommendation
 
-```bash
-git fetch origin
-git checkout -b reviews/<helpful-name>-original-pr-<PR_NUMBER> origin/next
-git push origin reviews/<helpful-name>-original-pr-<PR_NUMBER>
+| Condition                                         | Recommend                                               |
+| ------------------------------------------------- | ------------------------------------------------------- |
+| `commitCount == 1`                                | **No squash** (rebase or merge) — history already clean |
+| `commitCount ≤ 3` AND no messy subjects AND small | Ask, **default no squash**                              |
+| `commitCount > 3` OR messy subjects detected      | **Squash** (default)                                    |
+
+### Print the triage report
+
+```
+PR #<PR_NUMBER> — <title>
+  Author:        <login>  (<fork|same-repo>)
+  Base:          <baseBranch>
+  State:         <state>, <draft?>, mergeable=<mergeable>, mergeStateStatus=<mergeStateStatus>
+  Push to head:  <✅ allowed reason | ❌ blocked reason>
+  Size:          +<additions> / -<deletions> across <changedFiles> file(s), <commitCount> commit(s)
+  History:       <clean | messy: "<sample messageHeadline>">
+
+Recommendation:
+  • Path:  <direct push | reviews/ branch | review-only>
+  • Merge: <--squash | --merge | --rebase> (<reason>)
 ```
 
-Example: `reviews/copy-reference-original-pr-545`
+Stop here and present the report.
+
+## Phase 2 — Two questions
+
+Ask **only** these. Pre-select the recommended option.
+
+### Q1: Do you need to add changes before merging?
+
+- **No** → Path A (review & merge)
+- **Yes, small tweaks** → Path B (direct push) if `canPushToHead`, otherwise Path C
+- **Yes, heavy rework / contributor unresponsive** → Path C (`reviews/` staging branch)
+
+If `canPushToHead == false`, omit the "direct push" option and explain: _"Contributor disabled maintainer edits; we must use a `reviews/` branch."_
+
+### Q2: Merge strategy?
+
+Offer `--squash`, `--merge`, `--rebase` with the recommended option marked. Justify the default in one short sentence (e.g., _"4 commits including 'fix typo' — squash recommended"_).
+
+## Phase 3 — Execute
 
-### 3. Retarget the Contributor's PR
+Run commands non-interactively, echoing each one. After merge, print a one-line summary with the merged commit/PR URL.
 
-> ⚠️ **Known issue**: `gh pr edit --base` may emit a deprecation warning about Projects (classic). This is a cosmetic warning only — the base branch change succeeds regardless. Verify with `gh pr view <PR_NUMBER> --json baseRefName`.
+### Path A — Review & merge (no maintainer changes)
 
 ```bash
-gh pr edit <PR_NUMBER> --base reviews/<helpful-name>-original-pr-<PR_NUMBER>
+gh pr checkout <PR_NUMBER>                  # optional, for local inspection
+# review, leave comments via the PR UI or `gh pr review`
+gh pr merge <PR_NUMBER> --<strategy>        # against the PR's actual base
 ```
 
-Verify:
+### Path B — Direct push to the contributor's branch
+
+Requires `canPushToHead == true`.
 
 ```bash
-gh pr view <PR_NUMBER> --json baseRefName
+gh pr checkout <PR_NUMBER>                  # sets up a remote tracking the fork branch
+# make changes, commit
+git push                                    # updates the existing PR in place
+gh pr merge <PR_NUMBER> --<strategy>
 ```
 
-### 4. Merge the Contributor's PR
+The existing PR updates in place; the contributor keeps authorship of their commits and maintainer commits are attributed to the maintainer. No second PR is needed.
+
+### Path C — `reviews/` staging branch
+
+Use when push to head is blocked, or when the maintainer explicitly wants to isolate rework.
+
+**Branch slug sanitization** — derive `<slug>` from the PR title:
 
-Once the base is updated and the PR is ready:
+1. Lowercase.
+2. Replace every run of non-`[a-z0-9]` characters with a single `-`.
+3. Trim leading/trailing `-`.
+4. Truncate to 30 characters; trim trailing `-` again if the cut left one.
+
+Example: `"fix(tree): sort _id_ index first / cleanup"` → `fix-tree-sort-id-index-first-c`.
+
+Full branch name: `reviews/<slug>-pr-<PR_NUMBER>`.
 
 ```bash
-gh pr merge <PR_NUMBER> --squash
+git fetch origin
+git checkout -b reviews/<slug>-pr-<PR_NUMBER> origin/<baseBranch>
+git push -u origin reviews/<slug>-pr-<PR_NUMBER>
 ```
 
-Or approve + merge via the GitHub UI to trigger any required status checks.
+Retarget the contributor's PR:
+
+```bash
+gh pr edit <PR_NUMBER> --base reviews/<slug>-pr-<PR_NUMBER>
+gh pr view <PR_NUMBER> --json baseRefName    # verify
+```
 
-### 5. Create the Finalization PR
+> ⚠️ `gh pr edit --base` may print a deprecation warning about Projects (classic). Cosmetic only — the base change succeeds.
 
-Pull the merged review branch, then open a new PR from it to `next`:
+Merge the contributor's PR into the review branch:
 
 ```bash
-git checkout reviews/<helpful-name>-original-pr-<PR_NUMBER>
-git pull origin reviews/<helpful-name>-original-pr-<PR_NUMBER>
+gh pr merge <PR_NUMBER> --<strategy>
 ```
 
-Create the PR:
+Pull and create the finalization PR back to the original base:
 
 ```bash
+git checkout reviews/<slug>-pr-<PR_NUMBER>
+git pull origin reviews/<slug>-pr-<PR_NUMBER>
+
 gh pr create \
-  --base next \
-  --head reviews/<helpful-name>-original-pr-<PR_NUMBER> \
+  --base <baseBranch> \
+  --head reviews/<slug>-pr-<PR_NUMBER> \
   --title "<original title> [reviewed]" \
-  --body "This PR finalizes the review of the contribution originally submitted by @<author_login> in #<PR_NUMBER>.
+  --body "Finalizes review of @<author>'s contribution in #<PR_NUMBER>.
 
 Original PR: <PR_URL>"
 ```
 
-### 6. Comment on the Original PR
-
-Go back to the contributor's original (now merged) PR and leave a comment linking to the finalization PR:
+Comment on the original PR:
 
 ```bash
-gh pr comment <ORIGINAL_PR_NUMBER> \
-  --body "Thank you for the contribution! The review is continuing in #<NEW_PR_NUMBER> where maintainer changes will be finalized before merging to \`next\`."
+gh pr comment <PR_NUMBER> \
+  --body "Thanks for the contribution! Review continues in #<NEW_PR_NUMBER> where maintainer changes are finalized before merging to \`<baseBranch>\`."
 ```
 
+## Merge Strategy Reference
+
+| Strategy   | When to use                                                                                                          |
+| ---------- | -------------------------------------------------------------------------------------------------------------------- |
+| `--squash` | Default for messy/multi-commit external PRs. One revert undoes the change. Contributor still gets authorship credit. |
+| `--merge`  | Large feature where individual commits are meaningful and worth preserving.                                          |
+| `--rebase` | Single clean commit, or a series of clean atomic commits you want linear on the base.                                |
+
+## Hard Rules
+
+- **Never** hardcode `main` as the base — always read `baseRefName`.
+- **Never** create a `reviews/` branch in Phase 1.
+- **Never** force-push to a contributor's branch.
+- If the PR is a **draft**, refuse to merge and report it back to the maintainer.
+- If `mergeable == "CONFLICTING"` or `mergeStateStatus != "CLEAN"`, stop and surface that before any merge command.
+
 ## Summary
 
-| Step | Action                                     | Result                                    |
-| ---- | ------------------------------------------ | ----------------------------------------- |
-| 1    | Gather PR info                             | Know PR number, title, author             |
-| 2    | Create `reviews/...` branch off `next`     | Staging branch ready                      |
-| 3    | Retarget contributor's PR to review branch | Their diff is scoped to review branch     |
-| 4    | Merge contributor's PR                     | Contributor gets merge credit             |
-| 5    | Create finalization PR to `next`           | Maintainer controls what lands in `next`  |
-| 6    | Comment on original PR with link to new PR | Contributor is informed, thread is linked |
+| Phase | What happens                                               | Output                      |
+| ----- | ---------------------------------------------------------- | --------------------------- |
+| 1     | Read PR metadata, derive push capability + recommendations | Triage report               |
+| 2     | Ask Q1 (path) and Q2 (merge strategy)                      | Decision                    |
+| 3     | Execute the chosen path with the chosen merge strategy     | Merged PR / finalization PR |