From 25dcccd76dadcbde7bb667fe3f2d50e66d875a93 Mon Sep 17 00:00:00 2001 From: Bill Wagner Date: Fri, 16 Oct 2026 09:07:45 -0400 Subject: [PATCH] Update the post-meeting propagation prompt After the October meeting, propagate merged updates through all the upcoming alpha and draft branches. These changes update the prompts that are used to perform the propagation. --- .../prompts/post-meeting-propagate.prompt.md | 624 +++++------------- .../prompts/post-meeting-rebase-prs.prompt.md | 422 +++--------- 2 files changed, 240 insertions(+), 806 deletions(-) diff --git a/.github/prompts/post-meeting-propagate.prompt.md b/.github/prompts/post-meeting-propagate.prompt.md index 3168964a5..a040561ca 100644 --- a/.github/prompts/post-meeting-propagate.prompt.md +++ b/.github/prompts/post-meeting-propagate.prompt.md @@ -1,481 +1,159 @@ --- mode: agent -description: Phase B — serial per-version sweep that propagates committee changes and finalizes each alpha (committee changes + fresh patches) before advancing. +description: Discover and propagate committee changes one reviewed version at a time, preserving source intent and active feature work. --- -# Post-meeting: propagate changes through draft & alpha branches (Phase B) - -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. - -## Phase B of the two-phase post-meeting workflow - -The monthly post-meeting work is split into two phases (see -`post-meeting-rebase-prs.prompt.md` for **Phase A**): - -- **Phase A1 — feature-PR preparation (runs first).** Dynamically enumerate - the open feature PRs for the discovered draft branches, report the count, - rebase or notify them as appropriate, and produce a patch manifest. Each - manifest entry pins the PR number, base branch, head SHA, patch path, and - per-PR UTC cutoff time. -- **Phase B — this prompt: a single serial sweep up the chain, atomic per - version.** For each version N in chain order, (1) propagate the - committee-merged changes into `draft-vN`, (2) real-renumber `draft-vN` - (watch the concept-drift trap), (3) cheap re-rebase only the vN PRs whose - base moved in step 1 and update their manifest pins, (4) **reconstruct the - version's alpha branch** by surgically applying the fresh feature deltas - onto its existing structure, validate, then (5) advance so - `draft-v(N+1)` is based on the now-finalized discovered alpha branch. -- **Phase A2 — notification follow-up (runs after Phase B).** Consume Phase - B's deletion and future-version comment inventories to post alpha-drift - and routing notices. Phase A2 does not feed alpha reconstruction. - -Do not interpret the phase names as a repeating A/B cycle. The chronology is -**A1 → B → A2**. Phase B may call the narrowly scoped Phase A rebase -machinery only to refresh PRs whose base moved during Phase B. - -### ⚠️ Ordering invariant (the crux — do not violate) - -**Never propagate or build anything downstream of version N's discovered -alpha branch until that branch is finalized with BOTH the committee-merged -changes AND the fresh feature-PR patches.** In one sentence: finalized alpha -= finalized `draft-vN` + fresh vN feature deltas, constructed in **ONE -pass**, before `draft-v(N+1)` is built on it. - -This ordering reduces the risk of a second propagation cascade: propagating -the whole chain before refreshing alpha feature content can make downstream -branches depend on stale alpha text. It does not eliminate downstream drift. -Every later draft and alpha still requires the raw-reference, semantic, and -head-movement checks defined below. - -## Observed failure modes this workflow must detect - -- A numbered heading can retain a stale symbolic anchor such as `§xx` or - `§some-placeholder`. -- A feature PR can move after the patch cutoff, making the recorded patch - stale even when it still applies cleanly. -- A downstream conflict resolution can preserve older normative structure - or wording instead of the intended later-version language. - -## 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. -- Auto-PRs may show a `BLOCKED` merge state due to branch protection rules requiring review approval — this is normal and not a CI failure. Wait for checks to pass, then merge. -- You have `git` and `gh` available, and push permission to this repo. - -## Authoritative remote (set and validate once) - -Use one remote for discovery, baselines, merges, comparisons, and pushes. -This workflow intentionally does not support separate read and write remotes. - -```bash -REMOTE="${REMOTE:-upstream}" -REPO="$(gh repo view --json nameWithOwner -q .nameWithOwner)" -FETCH_REPO="$(gh repo view "$(git remote get-url "$REMOTE")" \ - --json nameWithOwner -q .nameWithOwner)" -PUSH_REPO="$(gh repo view "$(git remote get-url --push "$REMOTE")" \ - --json nameWithOwner -q .nameWithOwner)" -printf 'Authoritative remote: %s (fetch=%s, push=%s, gh=%s)\n' \ - "$REMOTE" "$FETCH_REPO" "$PUSH_REPO" "$REPO" -test "$FETCH_REPO" = "$REPO" && test "$PUSH_REPO" = "$REPO" -``` +# Monthly post-meeting propagation -The final `test` is mandatory. Stop if it fails, if either URL cannot be -resolved, or if the selected remote does not expose every branch in the -propagation chain. Keep `REMOTE` unchanged for the entire A1 → B → A2 run. -The Phase A manifest must record the same remote name and repository; stop -if it does not match. - -## Discover the propagation chain - -Do not rely on a fixed list or assume every alpha is named `alpha-vN`. - -1. Fetch and list the actual remote branch names: - - ```bash - git fetch "$REMOTE" --prune - git for-each-ref "refs/remotes/$REMOTE" \ - --format='%(refname:strip=3)' \ - | grep -E '^(draft-v[0-9]+|alpha-v[0-9]+|v[0-9]+-alpha)$' \ - | sort -V - ``` - -2. Starting with the user-supplied draft branch (default `draft-v8`), - enumerate later `draft-vN` branches by numeric version. For each version, - discover whether the remote has `alpha-vN` or `vN-alpha`; use the one that - exists. `v11-alpha` is valid and must not be rewritten as `alpha-v11`. - Stop if both names exist for one version or if the branch topology is - ambiguous. -3. Build the ordered chain as the starting draft, then each later draft, - followed by its discovered alpha when one exists. Confirm the order - against `admin/branch-diagram.md` and remote ancestry. Report the exact - discovered chain before changing anything. - -> **Walk this chain as a per-version, atomic-per-version sweep.** For each -> version N, finish `draft-vN` (propagate committee changes + renumber + -> cheap re-rebase of moved vN PRs) **and** finalize the discovered alpha -> branch (rebuild it from the fresh vN patches — Step D) BEFORE advancing to -> `draft-v(N+1)`. The discovered alpha branch (`alpha-vN` or `vN-alpha`) is -> never just a plain merge of its draft: it must also receive the fresh -> feature-PR patches in the same pass, per the ordering invariant above. -> -> Inspect `.github/workflows/update-on-merge.yaml` and report which -> discovered branches are covered by `on.push.branches`. Do not assume an -> auto-PR will appear on an uncovered branch. Alpha branches are commonly -> uncovered, so their validation must be completed locally before advancing. - -If the user names a different starting branch, start there and propagate to -every later branch in the discovered chain. - -## 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. **Run directory and Phase A manifest.** Create a persistent, untracked run - directory under `.git`, not a temporary system directory: - - ```bash - RUN_ID="$(date -u +%Y%m%dT%H%M%SZ)" - RUN_DIR="$(git rev-parse --git-path "post-meeting/$RUN_ID")" - mkdir -p "$RUN_DIR" - ``` - - Load Phase A1's feature-PR manifest. Require one record per dynamically - enumerated feature PR, including PR number, base branch, head SHA, patch - path, UTC cutoff time, and the authoritative remote name and repository. - Report the manifest's resulting PR count. Stop if the manifest is missing, - has duplicate PR numbers, names a different remote or repository, or its - count differs from a fresh enumeration of open PRs on the discovered - target draft branches. - -2. **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 "$REMOTE/"`). - Record `BASE_` for each branch. If a branch has no such commit - yet, fall back to the branch point and warn the user. - -3. **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_".."$REMOTE/" --diff-filter=MD \ - --name-only --pretty=format: -- standard/ | sort -u - - # Hunks (negative lines) for review: - git log "$BASE_".."$REMOTE/" -p -- standard/ \ - > "$RUN_DIR/starting-deletions.patch" - ``` - - Show the user the list of PRs merged this cycle (`gh pr list --base --state merged --search 'merged:>='`) and ask which performed substantive prose removals. Persist that list. - -4. **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 ; do - git --no-pager grep -nE '`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. -4. **Section-number drift in alpha branches.** Alpha branches often have - additional sections inserted (e.g. new feature clauses), which shift - subsequent section numbers. When merging upstream changes into an alpha - branch, check for duplicate section headers (e.g. two `## 14.5` headings) - caused by the merge combining the upstream's numbering with the alpha's - shifted numbering. The StandardAnchorTags tool will crash with - `System.InvalidOperationException: Duplicate section header` if this - happens. Fix by renumbering the duplicated header to its correct value. - -### 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 ) -``` +Analyze first, confirm permissions with Bill, then execute one version at a time. +Finalized predecessor -> draft -> authorized feature rebases -> existing alpha -> +local review -> approved publication -> verification -> next authorized version. + +Use `admin/branch-diagram.md` as conceptual context, but discover actual remote +refs. Do not assume names or counts: `v11-alpha` is a valid existing alpha name. +When working with csharp-squad, use its authoritative +`post-meeting-propagation`, `standard-renumber`, +`csharpstandard-version-validation`, and `csharp-standard-alpha-synthesis` skills. +The companion `post-meeting-rebase-prs.prompt.md` handles only the current +version's authorized sources; do not pre-rebase the entire chain. + +## Required authorization + +Confirm repository path, authoritative remote/repository, meeting date and merged +PRs, starting branch, endpoint, and per-version permissions: + +- draft-only, draft plus features, or draft plus features plus existing alpha; +- excluded feature heads whose authors are actively working; +- historical alpha feature set/order, including intentionally retained closed PRs; +- local commit and remote publication permissions, separately; +- exact validation exceptions approved for this cycle. + +Scope changes override earlier permission. No alpha creation, next-version work, +PR merges/comments, workflow dispatches, or protection changes are implied. +Do not retain a version-specific exclusion forever; reconfirm it next meeting. + +## 1. Freeze inventory and recover evidence + +Record remote fetch/push repository identity, all relevant old OIDs, local refs, +protected checkout, worktrees/statuses, stashes, and open PR metadata +(number/base/head/repository/OID/state/draft/mergeability). +Use isolated review refs/worktrees; never reset or overwrite divergent local heads. +Keep resumable JSON/text ledgers and logs outside the working tree. + +Discover both alpha naming forms. Stop on ambiguity. Absence is not permission to +create an alpha. Preserve the actual historically integrated feature set rather +than equating it with today's open-PR list. + +Recover interrupted artifacts before repeating research or mutations. A ledger +must identify exact old/new OIDs and completed stages; verify actual state before +resuming. Never apply stale cleanup stashes. + +## 2. Establish approved changes and deletion precedence + +Inspect the complete merged series, not only its final commit. A rebase merge may +contain several approved commits; capture the correct series boundary. +Build an approved deletion/refactoring inventory, including relevant prior +committee decisions, and retain source PR provenance. + +For example, dotnet/csharpstandard#1691 removed separate pattern subsumption and +exhaustiveness sections while retaining general definitions. Stale +dotnet/csharpstandard#1460 edits must not restore those sections during a rebase or +alpha rebuild. + +Approved committee wording wins over speculative feature text. Preserve genuine +later-version additions separately. A clean patch, successful rebase, or numeric +link audit does not prove semantic fidelity. + +## 3. Finalize the current draft + +Start from actual current upstream draft history and incorporate the verified +finalized predecessor. Preserve unique approved draft changes and the version's +compiler/tooling contract, including intentionally isolated legacy fixtures. + +Resolve conflicts hunk-by-hunk using approved sources and deletion provenance. +Never blanket-select a conflicted prose file. Separate number relocation from +meaning. Stop for normative ambiguity or unexplained tooling changes. + +Finalize draft numbering/grammar with the repository's exact tool when authorized. +From `tools`, with `GH_TOKEN` and `HEAD_SHA` cleared, the command is: -1. **Broken references.** Any *new* `TOC002` ("`` not found") - diagnostic that was not already present on `"$REMOTE/"` before - the merge is a **hard stop**. Compare the tool output against a pre-merge - run (or `git stash && run && git stash pop`) to distinguish new from - pre-existing. Pre-existing TOC002s from incomplete feature PRs on alpha - branches are expected and should be reported but do not block the merge. -2. **Mandatory raw symbolic-reference audit.** Run this independently of - the tool and save the output: - - ```bash - rg -n -e '§[a-z][a-z0-9-]*' -e '§xx' -e '#xx' \ - standard --glob '*.md' \ - > "$RUN_DIR/symbolic-refs-.txt" || true - ``` - - Review every match. A retained placeholder is a hard stop unless the - branch intentionally permits that exact pre-merge placeholder and it is - recorded in the report. This raw audit is mandatory because - `StandardAnchorTags` and its `TOC002` diagnostics previously missed - placeholders that remained in otherwise valid text, including symbolic - anchors left after headings had already been numbered. -3. **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. -4. 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 '`); 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 — Finalize, push, and verify - -For a draft branch, run this step after B.6. For an alpha branch, **defer -this entire step until Step D has applied, validated, and committed every -fresh feature delta**. An alpha's first and only propagation push must -already contain its committee merge and fresh feature content. - -1. Require a clean working tree. For an alpha, also require the Step D - finalization commit and record it as `ALPHA_FINAL_SHA`. -2. Push the exact local head: - - ```bash - git push "$REMOTE" HEAD: - git fetch "$REMOTE" - test "$(git rev-parse HEAD)" = "$(git rev-parse "$REMOTE/")" - ``` - - A failed equality check is a hard stop: the remote branch is not the - validated local result. -3. If `update-on-merge.yaml` covers this branch, the push opens a fresh - auto-PR. Loop back to Step A for this branch. After merging that PR, - fetch again and require `ALPHA_FINAL_SHA` (for an alpha) to be an ancestor - of `"$REMOTE/"`: - - ```bash - git merge-base --is-ancestor "$ALPHA_FINAL_SHA" "$REMOTE/" - ``` - -4. Do not advance to another branch until the remote verification succeeds. - -### Step B.8 — Cheap re-rebase of moved `draft-vN` feature PRs (draft branches with open feature PRs) - -This implements step (3) of the per-version sweep. If Step B moved -`draft-vN` (committee changes landed on it this cycle), the vN feature PRs -that **Phase A** (`post-meeting-rebase-prs.prompt.md`) already rebased now -have a stale base. Run this step only after Step A has merged the auto-PR -created by Step B.7, so the feature PRs rebase onto the final draft head for -this version. - -- Do the **cheap re-rebase of ONLY the vN PRs whose base moved** and - regenerate their `.patch` (Phase A machinery — - `git rebase "$REMOTE/draft-vN"` then - `git format-patch "$REMOTE/draft-vN..$REMOTE/"`). Do **not** - re-rebase PRs whose base did not move. -- Immediately before rebasing each PR, query `headRefOid` again and compare - it with the manifest pin. If it moved after the recorded cutoff, stop for - that PR; do not overwrite or build an alpha from a stale patch. After a - successful rebase, update that PR's manifest entry with the new head SHA, - regenerated patch, and a new UTC cutoff time. -- These refreshed patches are the input to Step D's alpha rebuild. The - patches Phase B applies to the alpha are always the freshest - post-propagation ones, not the Phase-A starting patches. - -### Step D — Surgically reconstruct the alpha from fresh feature deltas - -**This is the step that was previously unprompted — its absence is what let -the ordering slip and produced the 2026-07 double-propagation cascade.** Run -it whenever `` is a discovered alpha branch (`alpha-vN` or -`vN-alpha`), after Step B has propagated the committee changes into it and -**BEFORE** the chain advances to the next draft. - -The discovered alpha must equal **finalized `draft-vN` + the fresh vN -feature deltas**, built in ONE pass: - -1. **Recheck every PR head after the potentially long propagation run.** - Query each manifest PR's current `headRefOid` and compare it with the - pinned SHA and cutoff time. If any head moved, stop alpha reconstruction, - refresh that PR through Phase A machinery, record a new pin and cutoff, - and restart validation. Never silently use the older patch. -2. **Treat patches as feature-delta evidence, not commit-replay scripts.** - Apply the minimal normative delta onto the existing alpha structure. - Do not replay synchronization or base-merge commits wholesale, and do not - replace an alpha file with the feature PR's version. Preserve - branch-specific later-version language and structure unless the feature - itself intentionally changes it. -3. **Perform a semantic three-way comparison for every high-conflict - normative section.** Compare: - - the section in the prior finalized alpha (`BASE_`), - - the section in the finalized target `draft-vN`, and - - the section at the pinned current feature-PR head. - - Record the intended feature semantics, committee changes, and - later-version-only language that the reconstructed alpha must preserve. - Review the resulting alpha against that record. A patch applying cleanly, - a successful rebase, or correct renumbering is not evidence that the - normative result is semantically correct. If the three sources cannot be - reconciled confidently, stop and report the exact section and competing - text. -4. **Watch the renumber concept-drift trap.** The renumber tool keeps a - `§NUMBER` and rewrites the ANCHOR to whatever concept now sits at that - number, silently corrupting cross-refs while the dry-run reports **no** - error. For each drifted ref, read the intended concept from the merged - anchor slug, find that concept's actual number on this branch, and set - BOTH the number and the anchor manually. -5. **Dry-run and raw-reference validate.** Alpha branches commonly get no - auto-PR, so do **not** commit renumber/grammar output; revert only that - generated validation output after checking it, without reverting the - surgical feature-delta edits: - - ```bash - ( cd tools && dotnet run --project StandardAnchorTags -- \ - --owner dotnet --repo csharpstandard --dryrun ) - ``` - - Any *new* `TOC002` diagnostic relative to the pre-rebuild baseline is a - **hard stop**. Also repeat the mandatory raw `rg` audit from Step B.5 - across all `standard/*.md`; any unexplained `§[a-z][a-z0-9-]*`, `§xx`, - or `#xx` match is a hard stop. -6. **Commit the complete alpha delta before any alpha push.** Review - `git status --short`, `git diff --check`, and the full diff. Stage only - the intentional surgical feature-delta files, inspect - `git diff --cached`, and create a normal commit: - - ```bash - git commit -m "Post-meeting propagation: finalize feature deltas" - ALPHA_FINAL_SHA="$(git rev-parse HEAD)" - ``` - - If the manifest has no applicable feature delta and the tree is already - clean, record that no separate delta commit was required and use the - committee merge commit as `ALPHA_FINAL_SHA`. Then run Step B.7. Never - leave alpha delta edits only in the working tree or only in a local - commit. -7. **Finalize before advancing.** Only when the discovered alpha carries BOTH the - committee changes AND the fresh vN patches may the sweep proceed to - `draft-v(N+1)`. Require the verified authoritative remote head from - Step B.7 to contain `ALPHA_FINAL_SHA`. This reduces propagation risk; it - does not replace downstream semantic and reference verification. - -### Step C — Move to the next branch - -Advance the per-version sweep. Before starting `draft-v(N+1)`, confirm -the discovered alpha is finalized per Step D — **the ordering invariant -forbids building `draft-v(N+1)` on an unfinalized alpha.** Repeat A–D 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). -- The validated authoritative remote name and repository used for every - discovery, baseline, merge, comparison, and push. -- The dynamically enumerated feature-PR count and the manifest cutoff time. -- For each version N: whether its discovered alpha branch was **finalized** (committee changes + fresh vN deltas applied surgically, semantic comparison complete, dry-run and raw-reference audits clean) before `draft-v(N+1)` was started, and the list of vN PR numbers, pinned SHAs, and patches applied (Step D / Step B.8). -- Any PR head that moved after cutoff and how it was refreshed or why work stopped. -- The high-conflict normative sections compared and any unresolved semantic differences. -- Any raw symbolic-reference matches and their disposition. -- 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 run the Phase A2 notification pass in - `post-meeting-rebase-prs.prompt.md`. - -## Safety rules - -- Never force-push to any `draft-v*`, `alpha-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. -- Never change `REMOTE` or substitute another remote during the run. -- Never advance past an alpha until its `ALPHA_FINAL_SHA` is present on the - verified authoritative remote branch. -- If `gh` shows the auto-PR's checks failing, stop and ask the user. +Require zero placeholders/symbolic section references, correct hierarchy, +concept-correct links, source-derived grammar, and idempotence. +Do not hand-edit generated `standard/grammar.md`. + +## 4. Refresh only authorized current-version feature sources + +Invoke the companion rebase prompt only after this draft is finalized. +Skip the phase entirely for draft-only versions. Respect all do-not-touch heads. +Freeze/recheck each authorized PR head; do not overwrite author movement. + +Repair defects at the earliest authorized source and propagate them forward. +Audit retired sections on sources and alpha, not only conflict markers. +Never invoke `StandardAnchorTags` on feature branches, including dry runs. + +## 5. Rebuild the existing authorized alpha + +Integrate refreshed feature intent in historical order on an isolated review ref. +Preserve approved retained closed feature content. Compare old alpha, finalized +draft, current feature sources, and committee decisions in overlapping sections. + +Complete source/link/format fixes before finalization. Keep contextual-keyword +Markdown table rows at equal cell counts. ANTLR `contextual_keyword` alternatives +use five columns, allowing a final partial row; preserve tokens and their order. + +The exact section-renumber tool is the **last source-changing operation on the +alpha**. Run it, then the identical command again and prove byte-idempotence. +Regenerate grammar from source. Later source corrections require repeating this +finalization and affected validation. + +Do not build the next draft from a provisional alpha. + +## 6. Validate, classify, and hand off for review + +Prove actual ordinary compiler version, generated-project counts, legacy-fixture +isolation, lint, anchors/TOC, source fidelity, examples, converter, tool tests, +grammar, and applicable PR checks. + +Separate PASS, exact authorized EXCEPTION, blocked-layer UNAVAILABLE, and +NOT-TRIGGERED results. Pre-existing failures are not automatic waivers. Record +exception authorization, exact diagnostics and input digests at each version. +Revalidate changed inputs; stop for different failures. Do not fabricate harness +outputs or silently modify test contracts. + +Provide exact worktree/ref/HEAD, tracked status, diffstat, source fixes, and review +commands. Use `git diff /` for the complete working-tree delta; +appending `HEAD` omits staged/unstaged corrections. Distinguish committed review +changes from additional working-tree edits. Stop for Bill's review. + +## 7. Publish only the reviewed state + +After explicit approval, commit only exact approved files with runtime trailers. +Freeze the resulting reviewed OIDs. Re-read remote OIDs/protection immediately +before writing; stop on unexplained movement or lease failure. + +Use explicit refspecs and exact +`--force-with-lease=refs/heads/:` for every ref, preferably +one atomic authorized version cohort. Drafts/alphas must advance fast-forward. +A lease on a fast-forward is not a history rewrite. Rewritten feature publication +requires explicit permission; no unconditional force or blind lease refresh. + +Verify remote equality, ancestry, source PR state/base/head/mergeability, and +protected checkout/worktrees/stashes/refs. +Inspect actual workflow branch/path filters before waiting for CI or bot PRs. +No triggered Actions run means NOT-TRIGGERED, not green CI. Queued third-party +suites are not proof of relevant validation. Dispatches and bot merges require +separate approval. + +## Closeout + +Persist permissions, topology, provenance, old/new OIDs, exact leases, source +repairs, review evidence, validation classifications, remote equality and +preservation evidence. Record the next-version stop explicitly. + +Future-version notes are inventory for human triage, not permission to edit, +remove, or post them. Report optional notifications for approval. +Completion/publication never automatically authorizes the next version. diff --git a/.github/prompts/post-meeting-rebase-prs.prompt.md b/.github/prompts/post-meeting-rebase-prs.prompt.md index 4dbbf7d2e..83f32366a 100644 --- a/.github/prompts/post-meeting-rebase-prs.prompt.md +++ b/.github/prompts/post-meeting-rebase-prs.prompt.md @@ -1,369 +1,125 @@ --- mode: agent -description: Phase A — rebase same-repo feature PRs onto their own base, produce a fresh per-PR patch for Phase B, and notify fork PR authors. +description: Refresh only authorized current-version feature sources after their draft is finalized; preserve committee changes and active author work. --- -# Phase A — rebase feature PRs & produce per-PR patches (+ notify authors) +# Monthly feature-source refresh -This is **Phase A** of the two-phase post-meeting workflow (see -`post-meeting-propagate.prompt.md` for **Phase B**, the serial per-version -sweep). +This is the source-rebase step of `post-meeting-propagate.prompt.md`, not a +separate whole-chain rebasing pass. Discover/inventory once; for each version, +finalize its draft first, then refresh only its authorized features. Build the +alpha from those fresh sources before advancing downstream. -The complete chronology is: +## Inputs and permission gate -1. **Phase A1 — this prompt's preparation pass.** Discover the actual draft - and alpha branch names, dynamically enumerate the open feature PRs, report - the resulting count, rebase or notify each PR as appropriate, and pin its - patch inputs. -2. **Phase B — propagation and alpha reconstruction.** Run the serial - per-version sweep. If Phase B moves a PR's draft base, it invokes only the - rebase/patch machinery here to refresh that PR's pin. -3. **Phase A2 — this prompt's notification pass.** After Phase B reports its - inventories, route future-version comments and send alpha-drift notices. +- Explicit current version and finalized draft ref/OID. +- Repository path and authoritative remote/repository identity. +- Frozen open PR inventory: number/base/head/repository/OID/state/draft status. +- Explicit included sources, excluded active-author heads, and historical alpha + content/order supplied by the propagation coordinator. +- Protected local refs/worktrees/stashes, artifact directory, validation + exceptions authorized for this cycle, and separate commit/push permissions. -Do not run A2 before Phase B, and do not interpret A2 as input to the alpha -reconstruction. PR processing within A1 is independent and may run in -parallel after the enumeration snapshot is complete. +Draft-only scope skips all feature mutations and validation. Exclusions override +earlier authorization. Fork heads are read-only; comments require approval. +Never merge/close PRs, infer alpha creation, or advance versions. -Phase A does two things: +## 1. Freeze and recheck -1. **Rebase every open feature PR onto its own current base `draft-vN`** - (update each PR per whether its head is in this repo or on a fork), and -2. **Produce a fresh `.patch` per PR** — this is the artifact **Phase B - consumes** in its `alpha-vN` rebuild (Step D of the propagate prompt). - Make the patch explicit: without it Phase B cannot surgically apply the - fresh feature content onto the existing alpha structure. +Discover actual refs and PRs; no hardcoded counts. Query each target draft with +`gh pr list --repo --base --state open --limit 1000` and +capture number, base/head, head repository/owner, head OID, draft status and URL. +If the limit is reached, paginate rather than claiming a complete inventory. -> **Ordering note.** After Phase B propagates the committee changes into -> `draft-vN`, it does a *cheap re-rebase* of only the vN PRs whose base moved -> and **refreshes their patches** (propagate prompt, Step B.8). So the patches -> Phase B ultimately applies are the freshest post-propagation ones; the -> patches produced here are the starting point. +Validate fetch/push remote identity. Record excluded sources without operating on +them. Recheck each included PR's current state/base/head immediately before work. +If an author moved the head, stop that source and request a scope/pin decision. +Do not silently refresh a lease. -## Phase A2 notification and routing depend on Phase B output +Create a new isolated review ref/worktree from the frozen authoritative head. +Never use a failed checkout as permission to reset a divergent user's branch. +Do not apply archived cleanup stashes. -Steps 4 and 5 below (alpha-drift detection and vNext-comment routing) -consume artifacts that **Phase B produces**: +## 2. Rebase source intent onto the finalized draft -- the **future-version comment inventory** (Step B.6 of the propagate prompt) — used by Step 5 below to route those notes to the appropriate feature PRs; -- the deletion inventory — used as context when judging rebase conflicts. +Rebase only the included source commits, preserving authored intent and history. +Record original/new commit correspondence and inspect the full feature delta. -Run the discovery, rebase, pinning, and patch core (Steps 1–3) in A1. Run -Steps 4 and 5 only as A2, after Phase B has produced its report. Ask the -user for the propagate report (or its location) before running A2. +Resolve conflicts hunk-by-hunk: -## Phase A1 — prepare pinned feature-PR inputs +- Approved committee wording/deletions/refactorings supersede stale feature base + text. Preserve genuine feature additions separately. +- Formatting-only changes still need source evidence; no blanket whole-file + selection. Binary tooling conflicts require verified version-aware inputs, + never an unconditional preference for either side. +- Mechanical relocation and additive edits may be reconciled with provenance. +- Normative ambiguity, unknown tooling contracts, or active excluded ownership + stops for Bill's decision. -### Authoritative remote (set and validate once) +Audit resurrection even when a rebase applies cleanly. +Dotnet/csharpstandard#1691 retired separate pattern subsumption/exhaustiveness +sections; do not restore them from dotnet/csharpstandard#1460. General pattern +definitions retained by the committee are intentional. -Use one remote for every read and write against the repository that owns the -draft, alpha, and same-repository feature branches. Do not discover from one -remote and rebase, compare, or push through another. +## 3. Read-only feature audits and validation -```bash -REMOTE="${REMOTE:-upstream}" -REPO="$(gh repo view --json nameWithOwner -q .nameWithOwner)" -REPO_OWNER="${REPO%%/*}" -FETCH_REPO="$(gh repo view "$(git remote get-url "$REMOTE")" \ - --json nameWithOwner -q .nameWithOwner)" -PUSH_REPO="$(gh repo view "$(git remote get-url --push "$REMOTE")" \ - --json nameWithOwner -q .nameWithOwner)" -printf 'Authoritative remote: %s (fetch=%s, push=%s, gh=%s)\n' \ - "$REMOTE" "$FETCH_REPO" "$PUSH_REPO" "$REPO" -test "$FETCH_REPO" = "$REPO" && test "$PUSH_REPO" = "$REPO" -``` - -The final `test` is mandatory. Stop if it fails, if either URL cannot be -resolved, or if the selected remote does not expose both the discovered base -branches and same-repository PR heads. This workflow intentionally does not -support separate read and write remotes. Keep `REMOTE` unchanged for the -entire A1 → B → A2 run and record its name and repository in the manifest. +**Never run `StandardAnchorTags` on a feature branch**, including dry runs and +idempotence checks. Symbolic authoring placeholders may remain where intentional. +Use read-only heading/link/source audits instead. -### Step 1 — Discover branches and enumerate target PRs +Validate actual intended ordinary compiler version, generated project counts, +isolated legacy fixtures, examples, lint, converter, tools, normative grammar +extraction and applicable checks. Compare source intent and approved removals. +Do not hand-edit generated `standard/grammar.md`. -Do not use a fixed branch list or PR count. +Report PASS, exact authorized EXCEPTION, and blocked-layer UNAVAILABLE separately. +Pre-existing failures require explicit current-cycle approval and exact +diagnostic/input proof. A changed failure stops; do not widen the waiver. +Do not alter a harness contract or fabricate reference outputs. -1. Fetch and list the actual remote branch names: +Repair a feature defect here before rebuilding its alpha when authorized. +Excluded sources require a user decision; do not patch them indirectly. - ```bash - git fetch "$REMOTE" --prune - git for-each-ref "refs/remotes/$REMOTE" \ - --format='%(refname:strip=3)' \ - | grep -E '^(draft-v[0-9]+|alpha-v[0-9]+|v[0-9]+-alpha)$' \ - | sort -V - ``` +## 4. Refresh provenance and local review -2. Starting at the user-supplied draft (default `draft-v8`), discover later - `draft-vN` branches and the corresponding alpha branch named either - `alpha-vN` or `vN-alpha`. Use the name that actually exists; - `v11-alpha` is valid. Stop if both alpha spellings exist for a version or - the topology is ambiguous. Confirm the result against - `admin/branch-diagram.md`. -3. Feature PRs target draft branches. For every discovered target - `draft-vN`, list all open PRs with an explicit high limit and capture - `number`, `baseRefName`, `headRefOid`, `headRefName`, - `headRepositoryOwner`, `isDraft`, `author`, `title`, and `url`: +Record original/new OIDs, commit correspondence, intended feature delta, +base OID, conflict decisions, patch evidence, timestamps, and validation results. +Patches are evidence of feature intent, not instructions to replay stale +synchronization/base text on an alpha. - ```bash - gh pr list --base --state open --limit 1000 \ - --json number,baseRefName,headRefOid,headRefName,headRepositoryOwner,isDraft,author,title,url - ``` +Recheck state/base/head/draft/repository metadata. Provide exact review +worktree/ref/HEAD and status. A working-tree comparison against the authoritative +head includes uncommitted corrections; a diff ending in `HEAD` does not. +Freeze the actual reviewed state and stop before unauthorized commits/pushes. -4. Combine and de-duplicate the results by PR number. Report the exact - discovered branch chain and resulting feature-PR count before processing - any PR. The count is run data, never prompt text. +## 5. Approved publication only -### Step 2 — Create the pinned run manifest +After Bill approves, stage only exact reviewed files and include runtime trailers +in any new commits. Re-read each remote head and protection immediately before +publishing. Push only explicit authorized refs, with: -Create a persistent, untracked run directory under `.git`: - -```bash -RUN_ID="$(date -u +%Y%m%dT%H%M%SZ)" -RUN_DIR="$(git rev-parse --git-path "post-meeting/$RUN_ID")" -mkdir -p "$RUN_DIR/patches" +```text +--force-with-lease=refs/heads/: ``` -Create `$RUN_DIR/feature-prs.json` from the dynamic enumeration. Each record -must contain at least: - -- PR number and base branch; -- head branch and repository owner; -- enumerated head SHA; -- patch path and processing status; -- `capturedAt` and `cutoffTime` in UTC. - -Before Phase B starts, recheck every head and set each record's `cutoffTime` -to the time of that successful check. Finalize the manifest with a top-level -UTC `finalizedAt`, the total PR count, the exact discovered branch chain, and -the validated authoritative remote name and repository. Phase B must -reject a missing, duplicate, count-mismatched, or remote-mismatched -manifest. - -### Step 3 — Process each enumerated PR - -For each manifest PR: - -1. Query `gh pr view --json headRefOid,baseRefName,state` immediately - before processing. If the PR closed, changed base, or its head differs - from the enumerated SHA, update the enumeration and restart that PR's - preparation; do not continue from a stale snapshot. -2. Process the PR according to its head repository: - -- If `headRepositoryOwner.login` matches `REPO_OWNER`, the head is in the - authoritative repository. **Rebase it:** - 1. `gh pr checkout ` — if this fails to fast-forward (branch has - diverged from the authoritative remote), run - `git reset --hard "$REMOTE/"` to sync to the authoritative - version of the PR branch before proceeding. - 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 "$REMOTE" ` - 4. `git rebase "$REMOTE/"`. The base, PR head, comparisons, and - push must all use the validated authoritative remote. - 5. **If the rebase has conflicts:** - - **Binary conflicts** in `.github/workflows/dependencies/` (e.g. - `GrammarTestingEnv.tgz`): resolve by taking the PR's version - (`git checkout --theirs && git add `) and continue - the rebase. These are feature-specific test artifacts and the PR's - version is correct. - - **Formatting-only conflicts** in `standard/*.md` (e.g. table - pipe characters, smart-quote vs straight-quote differences): - take the PR's version (`git checkout --theirs && git add - `) and continue. The PR's formatting fix is the intended - change. - - **Independent additive conflicts** in `standard/*.md` (two - features each added text to the same list or paragraph, but the - additions are logically independent): combine both additions in - the correct order, resolve, and continue. - - **Structural/semantic conflicts** in `standard/*.md` (e.g. - grammar reorganization where the base refactored a production - hierarchy and the PR uses the old structure), or conflicts in - `tools/`: `git rebase --abort`, record the PR as "needs manual - rebase", and move on. Do not attempt to resolve conflicts that - require the author's design decision. - 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 *new* `TOC002` diagnostic fires that was not already present - on the PR branch before rebase, the rebase has introduced broken - cross-references. Recover with `git reset --hard "$PRE"`, record - the PR as "needs manual rebase", and move on. To distinguish new - from pre-existing: check the same ref against - `"$REMOTE/"` (the pre-rebase state). Pre-existing - TOC002s from incomplete feature work are expected and do not block - the push. - 7. Immediately before push, query `headRefOid` again. If it differs from - the remote SHA captured immediately before checkout, stop and restart - this PR; the author moved it during the run. Otherwise: - `git push --force-with-lease "$REMOTE" HEAD:`. Then verify: - - ```bash - git fetch "$REMOTE" - test "$(git rev-parse HEAD)" = \ - "$(git rev-parse "$REMOTE/")" - ``` - - Record success with that verified SHA. - 8. **Produce the per-PR patch (Phase B input).** Capture the PR's commits - relative to its base as a patch file so Phase B can surgically apply them - onto `alpha-vN`: - - ```bash - mkdir -p "$RUN_DIR/patches/" - git format-patch "$REMOTE/..$REMOTE/" \ - --stdout > "$RUN_DIR/patches//pr-.patch" - ``` - - Record the patch path, new head SHA, and UTC `capturedAt` in the - manifest. This is the fresh vN patch Phase B consumes; if Phase B later - moves `` via committee propagation, its cheap re-rebase updates - the SHA, patch, and cutoff (propagate prompt, Step B.8). - -- 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 ``. Then capture a **best-effort patch** from the PR's current head so Phase B still has an input for the `alpha-vN` rebuild — note it may need refreshing once the author rebases: - - ```bash - mkdir -p "$RUN_DIR/patches/" - gh pr diff --patch > "$RUN_DIR/patches//pr-.patch" - ``` - - Record the current `headRefOid`, patch path, UTC `capturedAt`, and - `bestEffort: true` in the manifest. Phase B must recheck the fork PR head - and stop if it moved after cutoff. - -After all PRs are processed, query every manifest PR's `headRefOid` one more -time. If any head moved during the long run, refresh it. Otherwise set that -record's `cutoffTime`, then set the top-level `finalizedAt`. Report the final -PR count and cutoff range. - -## Phase A2 — notify and route after Phase B - -### Step 4 — 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 that -version's discovered alpha branch at a previous meeting. Plain propagation -will not carry the new edits onto the 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 --json files,author,number,headRefOid`. -2. Look for prior commits on the discovered alpha branch by the same author - touching the same files: - - ```bash - git log "$REMOTE/" --author='' -- - ``` - -3. If prior commits exist and the current PR head SHA introduces changes to - those files not yet on the discovered alpha, record P as **"alpha has - stale version"**. +Prefer the propagation coordinator's atomic per-version cohort. Never use an +implicit lease, unconditional force, or blind retry. Author movement invalidates +the lease; do not overwrite it. No writes to forks or excluded heads. -Surface the list to the user. **Do not** cherry-pick or push to the alpha. -Instead, post the **alpha-drift notice** comment template (below) on each -affected PR; the marker dedupes on rerun. +Verify exact remote equality and source PR state/base/head/draft/mergeability. +Settle applicable CI under exact exceptions before reporting terminal results. +Refresh alpha inputs from these verified sources, not earlier stale patch pins. -### Step 5 — Route future-version comments to feature PRs +## Optional notifications -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 --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). The HTML marker - `` includes the source `file:line` so - re-runs do not duplicate it. Skip the comment if that marker and the same - `file:line` already exist on the PR. -4. List comments with **no** candidate PR in the final report under - "unrouted vNext comments" for user 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. - -## 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 - -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 - -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 - -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 - -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 --body-file `. +Report fork rebase requests, alpha drift, and future-version comments as proposed +human follow-ups. Post comments only with explicit approval and deduplicate them +with persistent markers. Notifications are not input to alpha reconstruction and +never authorize alpha edits, source rewrites, PR merges, or closures. ## Reporting -At the end, output a table grouped by base branch: - -- PRs successfully rebased + force-pushed (with new SHA) -- The dynamically discovered branch chain, exact feature-PR count, manifest - path, authoritative remote/repository, per-PR UTC cutoffs, and manifest - finalization time -- **Per-PR patches produced** (path `$RUN_DIR/patches//pr-.patch` - per PR, with pinned head SHA) — the Phase B input set the alpha rebuild - consumes; flag any fork PRs whose patch is best-effort/stale pending author - rebase -- Any PR head that moved during the run and how its manifest entry was - refreshed -- 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 4) -- vNext comments routed (PR number + source `file:line`) and any **unrouted vNext comments** for human triage (Step 5) - -## Safety rules - -- Never close or merge a feature PR. -- Never push to a fork. -- Always use `--force-with-lease`, never `--force`. -- Never change `REMOTE` or substitute another remote during the run. -- If `gh pr checkout` fails (e.g. permissions), record and skip. +Group current-version results by target draft: refreshed, excluded, author-moved, +fork/read-only, or blocked. Include exact old/new OIDs, source provenance, +validation classifications, protection/preservation evidence and review commands. +No completion implies permission for the next version.