Post-meeting propagation: merge draft-v8 into draft-v9

Author: BillWagner

.github/prompts/post-meeting-converge.prompt.md

@@ -0,0 +1,28 @@
+---
+mode: agent
+description: (Stub) Converge a finished version's draft and alpha branches.
+---
+
+# Post-meeting: converge draft and alpha for a completed version
+
+> **Status: not finalized.** The exact end-state for converging `draft-vN` and `vN-alpha` when version N is finished has not been decided by the committee. **Do not run this prompt yet.** Ask the user for the intended target state first, then update this prompt with the agreed procedure before executing anything.
+
+## Open questions to resolve before implementing
+
+- When v8 is finalized, does `draft-v8` become `standard-v8`, and is `v8-alpha` deleted? Or is `v8-alpha` merged into `draft-v8` first(and if so, which way do feature-PR conflicts resolve)? Note that v8 currently has no alpha branch.
+- What renames or branch-protection updates are needed?
+- What needs to happen to in-flight feature PRs whose base was the retired `vN-alpha`?
+- Is there a Word/PDF artifact step to run at convergence?
+- How do we reconcile feature PRs whose `draft-vN` head differs from the version already merged into `vN-alpha`? See the alpha-drift handling in `post-meeting-rebase-prs.prompt.md` (Step 0). Convergence must define whether the canonical text is the alpha version, the draft version, or requires per-file manual reconciliation.
+- How do we audit that no committee-approved deletion on `vN-alpha` was silently resurrected during the version's propagation history? Suggested: a final `git log --diff-filter=D` review against the `standard-v(N-1)` baseline at convergence time.
+- Disposition of any unrouted or still-unresolved vNext HTML comments remaining in `standard/*.md` when version N converges (see Step 0.5 of `post-meeting-rebase-prs.prompt.md`). Do they get applied, deferred to v(N+1), or deleted?
+
+## Outline (to be fleshed out once decided)
+
+1. Verify all feature PRs targeting `vN-alpha` and `draft-vN` are merged or reassigned to a later branch.
+2. Reconcile `draft-vN` and `vN-alpha` per the committee's decision.
+3. Rename / retire branches as decided.
+4. Update `admin/branch-diagram.md`, `README.md`, and the propagate prompt's chain to remove the retired branches.
+5. Update branch protection rules and `.github/workflows/update-on-merge.yaml`.
+
+When the semantics are decided, replace this stub with a full procedure modeled on `post-meeting-propagate.prompt.md`.

.github/prompts/post-meeting-propagate.prompt.md

@@ -0,0 +1,179 @@
+---
+mode: agent
+description: Propagate post-meeting changes through all draft and alpha branches.
+---
+
+# Post-meeting: propagate changes through draft & alpha branches
+
+You are propagating the changes merged into the current "starting" draft branch (after a TC49-TG2 committee meeting) forward through every future draft and alpha branch. See `admin/branch-diagram.md` for the rationale.
+
+## Assumptions
+
+- The committee secretary has already merged all approved PRs into the starting branch (default: `draft-v8`). Do **not** merge any other open PRs.
+- The `.github/workflows/update-on-merge.yaml` workflow will open an automated PR titled "Automated Section renumber and grammar extraction" on each branch that receives a push. These auto-PRs **must be merged** before the next propagation hop.
+- You have `git` and `gh` available, and push permission to this repo.
+
+## Propagation chain
+
+Walk these branches in order. Each step merges the previous branch into the next with a regular merge commit and pushes.
+
+1. `draft-v8`   (starting branch — no merge in; just merge its auto-PR)
+2. `draft-v9`   ← merges `draft-v8`
+3. `v9-alpha`   ← merges `draft-v9`
+4. `draft-v10`  ← merges `v9-alpha`
+5. `v10-alpha`  ← merges `draft-v10`
+6. `draft-v11`  ← merges `v10-alpha`
+7. `v11-alpha`  ← merges `draft-v11`
+8. `draft-v12`  ← merges `v11-alpha`
+
+> When new version branches are added (v12-alpha, draft-v13, etc.), append
+> them here in the same pattern: each `draft-v(N+1)` merges `vN-alpha`, and
+> each `vN-alpha` merges `draft-vN`. Also add the new branches to
+> `.github/workflows/update-on-merge.yaml` `on.push.branches`.
+
+If the user names a different starting branch, start there and propagate to
+every later branch in the list.
+
+## Pre-flight (run once, before walking the chain)
+
+These artifacts are referenced by Step B (conflict resolution) and Step B.6
+(future-version comment inventory). Capture them up front and persist them
+for the duration of the run.
+
+1. **Baseline.** Determine the SHA on each branch in the chain at the
+   *previous* propagation. A reliable proxy is the most recent merge commit whose subject begins with `Post-meeting propagation:` on that branch (`git log --grep '^Post-meeting propagation:' -1 --format=%H origin/<branch>`). Record `BASE_<branch>` for each branch. If a branch has no such commit yet, fall back to the branch point and warn the user.
+
+2. **Deletion inventory** for the starting branch. Identify text the
+   committee removed in this cycle so Step B can recognize resurrection:
+
+   ```bash
+   # Files where lines were removed since the previous propagation:
+   git log "$BASE_<starting>"..origin/<starting> --diff-filter=MD \
+     --name-only --pretty=format: -- standard/ | sort -u
+
+   # Hunks (negative lines) for review:
+   git log "$BASE_<starting>"..origin/<starting> -p -- standard/ \
+     > /tmp/starting-deletions.patch
+   ```
+
+   Show the user the list of PRs merged this cycle (`gh pr list --base <starting> --state merged --search 'merged:>=<last-meeting-date>'`) and ask which performed substantive prose removals. Persist that list.
+
+3. **vNext-comment baseline** for every branch in the chain. Snapshot the current set of HTML comments in `standard/*.md` mentioning a future version, so Step B.6 can diff against it after each merge:
+
+   ```bash
+   for b in <chain>; do
+     git --no-pager grep -nE '<!--[^>]*(vNext|v[0-9]+|future|upcoming|TODO)' \
+       "origin/$b" -- 'standard/*.md' > /tmp/vnext-baseline-$b.txt || true
+   done
+   ```
+
+   The grep is intentionally loose (false positives are fine — Phase 4 surfaces them for human triage; nothing is auto-applied).
+
+## Procedure
+
+Before starting, confirm the chain with the user and show which branches will be touched. Confirm the pre-flight artifacts above are captured. Then for each branch in order:
+
+### Step A — Process auto-PR on the current branch
+
+1. `git fetch --all --prune`
+2. `git checkout <branch>` and `git pull --ff-only`
+3. Find the auto-PR opened by `update-on-merge.yaml`:
+
+   ```bash
+   gh pr list --base <branch> --state open \
+     --search 'in:title "Automated Section renumber and grammar extraction"' \
+     --json number,headRefName,mergeable,mergeStateStatus
+   ```
+
+4. If found:
+   - Wait until checks pass (`gh pr checks <num> --watch` is acceptable, with a reasonable timeout — if it doesn't go green within a few minutes, stop and ask the user).
+   - The auto-PR's checks include the `StandardAnchorTags` job. If that job reports any `TOC002` ("`<ref>` not found") diagnostic, **stop** even if `gh pr checks` reports the PR overall as mergeable — broken cross-references must be resolved before merging.
+   - Merge it with a **merge commit**: `gh pr merge <num> --merge --delete-branch`.
+   - `git pull --ff-only` on the branch.
+5. If not found and this is the starting branch, ask the user whether to wait, run the tools locally (`tools/run-smarten.sh`, `tools/run-section-renumber.sh`), or proceed without them. Do not run tools locally without explicit consent.
+6. If not found on a downstream branch (it should appear after the merge in step B below), continue.
+
+### Step B — Merge from previous branch (skip on the starting branch)
+
+1. Still on `<branch>`, run:
+
+   ```bash
+   git merge --no-ff origin/<previous-branch> \
+     -m "Post-meeting propagation: merge <previous-branch> into <branch>"
+   ```
+
+2. **Conflicts:**
+   - **Never blanket "take upstream"** on a conflict whose hunks touch
+     prose in `standard/*.md`. Doing so can silently resurrect text the
+     committee deleted on the downstream branch in this cycle or a prior
+     one.
+   - For each conflicted hunk in `standard/*.md`:
+     a. Cross-check the hunk's file and line range against the deletion inventory captured in Pre-flight (`/tmp/starting-deletions.patch`) **and** against any prior `Post-meeting propagation:` merges on the downstream branch (`git log --grep '^Post-meeting propagation:' -p origin/<branch> -- <file>`).
+     b. If the downstream side intentionally removed the text, keep the deletion and re-apply only non-overlapping upstream edits to the surrounding region.
+     c. If unclear, **abort the merge** (`git merge --abort`) and report to the user with the file, line range, and both sides of the hunk.
+   - Mechanical "take upstream" is acceptable **only** for:
+     - regenerated `standard/grammar.md`,
+     - TOC blocks below the `<!-- The remaining text is generated by a tool. Do not hand edit -->`marker,
+     - the generated TOC in `standard/README.md`.
+   - For any conflict in `tools/`, `.github/`, or any prose conflict you are not 100% sure is mechanical: **abort the merge** and stop.
+3. After conflicts are resolved (or if the merge was clean), **do not push yet**. Run Steps B.5 and B.6 below first.
+
+### Step B.5 — Cross-reference validation
+
+Run the section-renumber tool in dry-run mode against the post-merge working tree to surface broken or drifted cross-references *before* pushing:
+
+```bash
+( cd tools && dotnet run --project StandardAnchorTags -- \
+    --owner dotnet --repo csharpstandard --dryrun )
+```
+
+1. **Broken references.** Any `TOC002` ("`<ref>` not found") diagnostic is a **hard stop**. Reset the merge commit (`git reset --hard origin/<branch>`), report the failing references to the user, and do not push.
+2. **Concept drift.** Count how many section numbers the dry run would change (lines beginning with `§` in the tool's diff output). If more than ~25 sections shift, sections have drifted enough that surviving cross-references like `§X.Y (Foo)` may now point at a different concept — the renumber tool fixes the *number* but cannot detect when the *concept* (parenthetical name, surrounding prose) is now wrong. Pause, list the affected references to the user, and proceed only on explicit confirmation.
+3. The actual renumber/grammar regeneration runs in the auto-PR opened by `update-on-merge.yaml` after push (Step A on the next iteration); do not commit dry-run output.
+
+### Step B.6 — Future-version comment inventory
+
+Diff the current branch's HTML comments mentioning future versions
+against the Pre-flight baseline to surface anything new this propagation brought in (these are notes the committee left for upcoming versions and need to be routed to the appropriate feature PRs by `post-meeting-rebase-prs.prompt.md`):
+
+```bash
+git --no-pager grep -nE '<!--[^>]*(vNext|v[0-9]+|future|upcoming|TODO)' \
+  HEAD -- 'standard/*.md' > /tmp/vnext-current-<branch>.txt
+diff /tmp/vnext-baseline-<branch>.txt /tmp/vnext-current-<branch>.txt \
+  > /tmp/vnext-delta-<branch>.txt || true
+```
+
+For each *new* comment in the delta, record:
+
+- file path and line number,
+- full comment text,
+- branch where it appeared (`<branch>`),
+- best-guess target version parsed from the comment (e.g. `v10` from `<!-- v10: tighten wording -->`); leave blank if not parseable.
+
+Persist the accumulated list across the whole run. Include it in the final report so `post-meeting-rebase-prs.prompt.md` can consume it. **Do not edit `standard/*.md` to remove or apply these comments.**
+
+### Step B.7 — Push
+
+1. Push: `git push origin <branch>`.
+2. The push triggers `update-on-merge.yaml`, which will open a fresh auto-PR. Loop back to Step A for this branch before moving on.
+
+### Step C — Move to the next branch
+
+Repeat A–B for the next branch in the chain. Continue until the chain is done.
+
+## Reporting
+
+When finished (or when stopped on a conflict), produce a short report:
+
+- For each branch: action taken (auto-PR merged, propagation merge SHA, skipped).
+- Any branches where you stopped and why.
+- The deletion inventory captured in Pre-flight (file list + originating PR numbers).
+- The accumulated future-version comment inventory from Step B.6 (file:line, comment text, source branch, best-guess target version). Hand this to `post-meeting-rebase-prs.prompt.md`.
+- A reminder to the user to run `post-meeting-rebase-prs.prompt.md` next.
+
+## Safety rules
+
+- Never force-push to any `draft-v*` or `v*-alpha` branch.
+- Never use `git reset --hard` on a tracked branch.
+- Never merge any PR other than the automated renumber/grammar PR.
+- If `gh` shows the auto-PR's checks failing, stop and ask the user.

.github/prompts/post-meeting-rebase-prs.prompt.md

@@ -0,0 +1,149 @@
+---
+mode: agent
+description: Rebase same-repo feature PRs and notify fork PR authors after propagation.
+---
+
+# Post-meeting: rebase / notify feature PRs
+
+After `post-meeting-propagate.prompt.md` has updated all draft/alpha branches, every open feature PR is now stale relative to its base. Update each PR according to whether its head branch is in this repo or on a fork.
+
+This prompt also consumes two artifacts from the propagate run:
+
+- the **future-version comment inventory** (Step B.6 of the propagate prompt) — used by Step 0.5 below to route those notes to the appropriate feature PRs;
+- the deletion inventory — used as context when judging rebase conflicts.
+
+Ask the user for the propagate report (or its location) before starting.
+
+## Procedure
+
+### Step 0 — Detect feature-PR drift across cycles
+
+A feature PR open against `draft-vN` may have been edited between meetings, while an *earlier* version of the same feature was already merged into `vN-alpha` at a previous meeting. Plain propagation will not carry the new edits onto `vN-alpha` until the next meeting. Surface these so authors can decide whether to open a separate alpha-targeted PR sooner.
+
+For every open PR P with base `draft-vN`:
+
+1. Read its files: `gh pr view <num> --json files,author,number,headRefOid`.
+2. Look for prior commits on `vN-alpha` by the same author touching the same files:
+
+   ```bash
+   git log origin/vN-alpha --author='<login>' -- <files…>
+   ```
+
+3. If prior commits exist and the current PR head SHA introduces changes to those files not yet on `vN-alpha`, record P as **"alpha has stale version"**.
+
+Surface the list to the user. **Do not** cherry-pick or push to `vN-alpha`. Instead, post the **alpha-drift notice** comment template (below) on each affected PR; the marker dedupes on rerun.
+
+### Step 0.5 — Route future-version comments to feature PRs
+
+Consume the future-version comment inventory from the propagate prompt's report. For each entry (file:line, comment text, source branch, best-guess target `vN`):
+
+1. List candidate open PRs:
+
+   ```bash
+   gh pr list --base draft-vN --state open --json number,title,files,url
+   gh pr list --base vN-alpha --state open --json number,title,files,url
+   ```
+
+2. Match the comment to candidate PRs by:
+   - **file path**: the comment's file appears in the PR's changed files;
+   - **proximity**: the comment's line is within or near a hunk modified by the PR (best-effort; surface multiple candidates rather than guessing).
+
+3. For each (comment, candidate-PR) pair, post the **vNext-routing** comment template (below) on the PR. The HTML marker `<!-- post-meeting-vnext-routing -->` includes the source `file:line` so re-runs do not duplicate (skip if a comment with that marker and the same `file:line` already exists on the PR).
+
+4. Comments with **no** candidate PR are listed in the final report under "unrouted vNext comments" for the user to triage.
+
+If `vN` is missing or unparseable from the comment, list the entry as unrouted and surface it in the report.
+
+**This step never edits `standard/*.md`.** The prompts neither apply nor remove these comments; the matched PR's author decides whether to fold the change in or open a new PR.
+
+### Step 1 — List target base branches
+
+List target base branches (the propagation chain — see the propagate prompt). Default: `draft-v8 draft-v9 v9-alpha draft-v10 v10-alpha draft-v11 v11-alpha draft-v12`. Allow the user to override.
+
+### Step 2 — For each base branch, list and process open PRs
+
+For each base branch, list open PRs:
+
+```bash
+gh pr list --base <base> --state open \
+  --json number,title,headRefName,headRepositoryOwner,isDraft,author,url
+```
+
+For each PR returned:
+
+- If `headRepositoryOwner.login` matches this repo's owner (`dotnet`), the head is in this repo. **Rebase it:**
+  1. `gh pr checkout <num>`
+  2. **Capture the pre-rebase SHA** so we can recover if the post-rebase cross-reference check fails: `PRE=$(git rev-parse HEAD)`.
+  3. `git fetch origin <base>`
+  4. `git rebase origin/<base>`
+  5. **If the rebase has conflicts:** `git rebase --abort`, record the PR as "needs manual rebase", post the **attempted-rebase** comment below, and move on. Do not attempt to resolve feature-text conflicts.
+  6. **Cross-reference check before push.** Run the renumber tool in dry-run mode against the rebased worktree:
+
+     ```bash
+     ( cd tools && dotnet run --project StandardAnchorTags -- \
+         --owner dotnet --repo csharpstandard --dryrun )
+     ```
+
+     If any `TOC002` diagnostic fires, the rebase has produced broken cross-references. Recover with `git reset --hard "$PRE"`, record the PR as "needs manual rebase", and post the **attempted-rebase** comment below with the failing references quoted in the body. Do not push.
+  7. Otherwise: `git push --force-with-lease`. Record success with the new SHA.
+
+- If the head is on a fork, **do not attempt to rebase.** Post the
+  **please-rebase** comment below. Avoid duplicate comments: skip if any existing comment on the PR already contains the marker `<!-- post-meeting-rebase-notice -->`.
+
+## Comment templates
+
+The HTML comment is a marker so re-runs don't duplicate.
+
+**Please-rebase (fork PRs and any PR not yet notified):**
+
+```markdown
+<!-- post-meeting-rebase-notice -->
+The base branch `{{base}}` has been updated following the latest TC49-TG2 committee meeting. Please rebase this PR onto the latest `{{base}}` and resolve any conflicts. Thanks!
+```
+
+**Attempted-rebase (same-repo PRs that hit conflicts):**
+
+```markdown
+<!-- post-meeting-rebase-notice -->
+I attempted to rebase this PR onto the updated `{{base}}` after the latest TC49-TG2 committee meeting but encountered conflicts. Please rebase locally and resolve them. Thanks!
+```
+
+**Alpha-drift notice (feature PRs whose alpha branch already has an older version of this feature):**
+
+```markdown
+<!-- post-meeting-rebase-notice -->
+An earlier version of this feature is already present on `{{alpha}}` from a prior meeting. Edits made to this PR since then are **not** yet on `{{alpha}}`; they will land at the next propagation. If you need them on `{{alpha}}` sooner, please open a separate PR targeting `{{alpha}}`.
+Thanks!
+```
+
+**vNext-routing (notes left on an older version that target this PR's
+version):**
+
+```markdown
+<!-- post-meeting-vnext-routing source={{file}}:{{line}} -->
+While propagating post-meeting changes, the following note targeting `{{target_version}}` was found on `{{source_branch}}` at `{{file}}:{{line}}`:
+
+> {{comment_text}}
+
+This PR appears to touch the same area. Please consider whether this note applies — either fold the change into this PR or open a follow-up. The note in `standard/*.md` was **not** edited or removed by tooling.
+```
+
+Post via `gh pr comment <num> --body-file <tempfile>`.
+
+## Reporting
+
+At the end, output a table grouped by base branch:
+
+- PRs successfully rebased + force-pushed (with new SHA)
+- PRs left for manual rebase (with reason — including any failing `TOC002` references from the post-rebase cross-reference check)
+- Fork PRs commented on
+- PRs that already had the notice (skipped)
+- PRs flagged with the **alpha-drift notice** (Step 0)
+- vNext comments routed (PR number + source `file:line`) and any **unrouted vNext comments** for human triage (Step 0.5)
+
+## Safety rules
+
+- Never close or merge a feature PR.
+- Never push to a fork.
+- Always use `--force-with-lease`, never `--force`.
+- If `gh pr checkout` fails (e.g. permissions), record and skip.