Merge pull request #657 from Fallout-build/upmerge/main-to-develop

Upmerge main into develop

Author: dennisdoomen

.agents/skills/adding-a-migration-step/SKILL.md

@@ -0,0 +1,40 @@
+---
+name: adding-a-migration-step
+description: How to make fallout-migrate handle a new rename, removal, or rewrite by extending an existing IMigrationStep, and when a genuinely new step is warranted. Trigger when asked to add a rename/rewrite rule to fallout-migrate, or to touch src/Fallout.Migrate/Migration.cs or its Steps.
+---
+
+`fallout-migrate` runs a fixed, ordered list of `IMigrationStep` implementations,
+built in `src/Fallout.Migrate/Migration.cs`. A **step is one operation over one
+set of files**, and it owns the rewrite rules for those files.
+`RewriteCsprojsStep` holds the rules for `*.csproj`; `RewriteCsFilesStep` holds
+the rules for `*.cs`.
+
+## Adding a new rename, removal, or rewrite
+
+1. Find the step for that file type — `RewriteCsprojsStep` for `*.csproj`,
+   `RewriteCsFilesStep` for `*.cs`, `RewriteBootstrapScriptsStep` for the
+   bootstrap scripts.
+2. Add a `private static readonly Regex` field to that step, with a comment
+   saying what moved and why.
+3. Apply it as another statement in the step's `Rewrite` method, incrementing
+   `edits` per replacement.
+4. Add cases to that step's spec class in `tests/Fallout.Migrate.Specs`.
+
+**Do not add a step per rename.** A new step means a second pass over the same
+files, so each file is written twice and the `Summary` edit count is inflated.
+Rule order also matters — a specific rule usually has to run before a general
+one — and inside one `Rewrite` method that order is plain statement order.
+Split across steps it becomes a hidden dependency between entries in
+`Migration.steps`.
+
+## When a new step actually is warranted
+
+Only for a new set of files or a genuinely different operation, such as
+renaming a directory or prompting the user. That's one new class implementing
+`IMigrationStep` plus one line in `Migration.steps`. If the new step depends on
+an earlier one, say so in the comment on that list entry, the way
+`ResolveFalloutVersionStep` does.
+
+Keep `Steps/` free of helper classes. A rewriter that only serves one step
+belongs inside that step — see `aef6c073` (`CsprojRewriter`) and #528
+(`CodeRewriter`) for the shape.

.agents/skills/adding-a-tool-wrapper/SKILL.md

@@ -0,0 +1,22 @@
+---
+name: adding-a-tool-wrapper
+description: Recipe for adding or extending a CLI tool wrapper under src/Fallout.Common/Tools/<Tool>/<Tool>.json. Trigger when asked to add a new tool wrapper, add a command/argument to an existing one, or when a Tools/*.json file is being edited.
+---
+
+Tool wrapper `.json` files are the source of truth; the `.cs` next to each one
+is generated — never hand-edit the generated file.
+
+1. Find the closest existing tool under `src/Fallout.Common/Tools/<Tool>/<Tool>.json`
+   and copy its shape.
+2. Cover a full command with all its arguments, not just the one option you need.
+3. Use formatting tags in `help` text:
+   - `<c>` for inline code
+   - `<a>` for links
+   - `<ul>` / `<ol>` for lists
+   - `<em>` for emphasized text
+   - `<para/>` between paragraphs (not `<p>...</p>`)
+4. Don't write `secret: false` — it's the default.
+5. Don't write `default: xxx` — obsolete field, omit it.
+6. Run `./build.ps1 GenerateTools` to regenerate the `.cs` output.
+7. Commit the regenerated `.cs` alongside the `.json` spec in the same commit —
+   `VerifyGeneratedTools` fails CI if they drift.

.agents/skills/creating-a-pr/SKILL.md

@@ -0,0 +1,70 @@
+---
+name: creating-a-pr
+description: Steps for opening a pull request in the Fallout repo — picking the right base branch, creating it as a draft, applying the target/vCurrent-or-vNext and changelog-category labels, and handling breaking changes. Trigger whenever you are about to run `gh pr create`, decide a branch/base, write commit messages, or write a PR/issue description.
+---
+
+Follow this exactly when opening a PR. Don't skip the labelling — it's easy to
+drop because it's just flags on the same `gh pr create` call.
+
+## 0. Working from a fork?
+
+Check `git remote -v`. If it shows both `origin` (your fork) and `upstream`
+(`Fallout-build/Fallout`), branch from `upstream/develop` — never
+`origin/develop`, which can be far behind and cause needless conflicts:
+
+```bash
+git fetch upstream develop
+git switch -c <branch> upstream/develop
+git push -u origin <branch>
+gh pr create --repo Fallout-build/Fallout --draft ...
+```
+
+Skip this for a plain single-remote clone.
+
+## 1. Create as a draft
+
+`gh pr create --draft` unless the user explicitly asked for ready-for-review.
+
+## 2. Label at creation time, not as a follow-up
+
+- **`target/vCurrent`** (default) or **`target/vNext`** (breaking changes — see
+  below) — pass `--label target/vCurrent`.
+- **One changelog-category label** from [`.github/release.yml`](../../../.github/release.yml):
+  `enhancement`, `bug`, `security`, `documentation`, `breaking-change`, or
+  `skip-changelog` for housekeeping. Don't leave a PR uncategorized — it falls
+  through to "Other Changes".
+
+## 3. Breaking change? Do all of this too
+
+A change is breaking if a commit uses the `!` suffix, has a `BREAKING CHANGE:`
+footer, or a reviewer would reasonably flag it (renamed/removed public API,
+package ID change, on-disk format change, CI/CD shape change consumers depend
+on) — except changes to `[Experimental]` surface, which carries no guarantee.
+
+1. `--label target/vNext --label breaking-change` (use `breaking-change`
+   instead of `enhancement`/`bug` as the changelog category).
+2. Open the PR body with a `⚠️ Breaking change` callout: name the affected
+   surface and the consumer-side impact in one sentence.
+3. **Target `develop`**, never `release/vX.Y` or `main` — confirm the breaking
+   surface sits behind `[Experimental("FALLOUT0xx")]` (see the
+   `marking-experimental-apis` skill), or, if it can't be gated, on a
+   short-lived branch off `develop` held for the next major. Don't bump
+   `version.json`'s major — that happens once, at the cut.
+4. Spell out the migration path (one paragraph minimum) — what a consumer
+   changes and what they run. There's no `CHANGELOG.md`; the `breaking-change`
+   label is what carries this into the generated release notes.
+
+If you only discover the breaking nature mid-review, apply all of this before
+requesting re-review.
+
+## Writing the description
+
+Follow the [plain-english skill](../plain-english/SKILL.md) for the terse,
+scannable shape (issues too) — lead with the point, bullets over prose, link
+don't recap.
+
+## Full policy reference
+
+[references/pr-creation-flow.md](references/pr-creation-flow.md) has the
+complete versioning-policy and milestone-labelling background behind the
+steps above, if you need the "why".

.agents/skills/creating-a-pr/references/pr-creation-flow.md

@@ -0,0 +1,43 @@
+# PR-creation flow — full policy background
+
+The step-by-step procedure lives in the parent [SKILL.md](../SKILL.md). This
+file is the "why" behind it: the versioning policy a breaking-change PR must
+satisfy, and how milestones map to the `target/*` labels.
+
+## Versioning policy
+
+This project ships classic semver ([ADR-0009](../../../../docs/adr/0009-gitflow-and-semver-reversion.md)).
+The rule: **breaking changes wait for the next major**, and there's no fixed
+date for that — the project stays on `10.x` for as long as it can, and the
+eventual move to v11 will go through `fallout-migrate`.
+
+There is **no `CHANGELOG.md`** — the file was retired. Release notes are
+generated from PR labels via [`.github/release.yml`](../../../../.github/release.yml).
+The PR description and its labels are now the lasting record of a change.
+
+- A breaking change lands on **`develop`, behind `[Experimental("FALLOUT0xx")]`**
+  (or, if that doesn't fit, on a short-lived branch off `develop` held until
+  the cut). It does **not** bump `version.json`'s major mid-cycle.
+- **A `release/vX.Y` or `main` production line never takes a breaking change.**
+  It only takes non-breaking work. The review before a production cut is the
+  backstop that keeps an ungated breaking change off the production line.
+- Surface that isn't ready to commit to yet can ship behind
+  `[Experimental("FALLOUT0xx")]` instead of being held back — see the
+  `marking-experimental-apis` skill.
+
+**Reviewer responsibility:** if a PR carries `!` (or a flagged breaking
+change), check that it targets `develop`, not a production branch. Check that
+the breaking surface is behind `[Experimental("FALLOUT0xx")]` (or on a topic
+branch, if it can't be gated). Check that the PR description has the
+`⚠️ Breaking change` callout with a migration path. Block the PR if any of
+that is missing.
+
+## Milestones and version targeting
+
+Milestones are **theme-based** (e.g. "Plugin Architecture Foundation &
+Rebrand Completion", "Public Plugin SDK", "Continuous Delivery Vision") and
+carry across releases; version targeting uses **evergreen `target/vCurrent` /
+`target/vNext`** labels — `target/vCurrent` is the current release line,
+`target/vNext` is the next major. A breaking change is held for the next
+major, so its PR carries `target/vNext`. See [docs/roadmap.md](../../../../docs/roadmap.md)
+for the current milestones.

.agents/skills/cutting-a-release/SKILL.md

@@ -0,0 +1,33 @@
+---
+name: cutting-a-release
+description: Procedure for tagging, publishing, promoting, or cutting a new release/vX.Y branch, hotfixing a production line, or cutting the eventual v11 major. Trigger on requests to cut a release, publish to nuget.org, tag a version, hotfix main or support/v10, or promote a release branch to GA.
+---
+
+The maintainer runbook is [docs/branching-and-release.md](../../../docs/branching-and-release.md)
+— read it and follow it exactly; this file is a quick index into it plus the
+gotchas worth knowing before you start.
+
+## Which section of the runbook you need
+
+| You're asked to... | Read |
+| --- | --- |
+| Cut a new `release/vX.Y` and tag `-rc.N` builds | [Cutting a release](../../../docs/branching-and-release.md#cutting-a-release) |
+| Publish a GA tag to nuget.org | [Publishing to nuget.org](../../../docs/branching-and-release.md#publishing-to-nugetorg) |
+| Ship an emergency fix to `main` or `support/v10` | [Hotfixing production](../../../docs/branching-and-release.md#hotfixing-production) |
+| Cut the eventual v11 | [Cutting v11](../../../docs/branching-and-release.md#cutting-v11-when-it-eventually-happens) |
+| Retire an old `support/*` line | [Deprecating a support/* line](../../../docs/branching-and-release.md#deprecating-a-support-line) |
+| First-ever publish of a new `Fallout.X` package | [First-publish gotcha](../../../docs/branching-and-release.md#adding-a-new-falloutx-package--first-publish-gotcha) |
+
+## Gotchas worth knowing up front
+
+- **`--ref` on `workflow_dispatch` must be the production branch**, not the
+  default branch — it runs *that ref's copy* of the workflow.
+- **`--notes-start-tag` must be the last GA tag**, not the previous rc, or the
+  generated notes only cover since the last rc.
+- **A green pipeline run is not proof anything published** — every publish job
+  is conditional. Verify job conclusions and the nuget.org index after a
+  release (commands in the runbook).
+- **nuget.org is always opt-in** via `workflow_dispatch -f publish-to-nugetorg=true`;
+  a tag push alone only reaches GitHub Packages + GitHub Releases.
+- Never bypass a hotfix through direct pushes — branch protection blocks it
+  everywhere; even a one-commit cherry-pick goes through a PR.

.agents/skills/editing-ci-workflows/SKILL.md

@@ -0,0 +1,32 @@
+---
+name: editing-ci-workflows
+description: Invariants to preserve when touching .github/workflows/**, build/Build.CI.GitHubActions.cs, or anything about which branches/tags trigger CI or publish packages. Trigger before editing a workflow YAML file, the CI generator source, or branch trigger lists.
+---
+
+Read [references/ci-invariants.md](references/ci-invariants.md) in full before
+changing a workflow — most mistakes here are "looks fine, quietly breaks a
+gating assumption." The short version:
+
+- **`build.yml` and `build-cross-platform.yml` are generated** from
+  `build/Build.CI.GitHubActions.cs` — edit the attributes/constants there and
+  regenerate (`./build.sh`), never hand-edit those two `.yml` files.
+  `build-skip.yml`, `publish-packages-preview.yml`, and
+  `publish-packages-release.yml` are hand-written; those you do edit directly.
+- **Feature branches run zero CI** until a PR targets a long-lived branch
+  (`develop`/`main`/`release/*`/`support/*`). Never add a working-branch
+  pattern (`feature/*`, `bugfix/*`, …) to a push/PR trigger.
+- **Cross-platform (`windows`/`macos`) is release-intent-gated** — PRs into
+  `main`/`release/*`/`support/*`, or a `v*` tag push. Never add `develop` to
+  its push triggers.
+- **`concurrency: cancel-in-progress` everywhere except `publish-packages-release.yml`**
+  — never cancel a publish mid-flight.
+- **Every publishing lane runs `Test` before it publishes**, as a single
+  `dotnet fallout Test Pack` invocation, not split steps — splitting
+  double-compiles.
+- Don't add `submodules: recursive` to a checkout step — there are no
+  submodules in this repo.
+
+See also [docs/architecture.md](../../../docs/architecture.md#ci-layout) for
+the current workflow-to-trigger table, and
+[docs/branching-and-release.md](../../../docs/branching-and-release.md) for
+the branch-protection rulesets these triggers back onto.

.agents/skills/editing-ci-workflows/references/ci-invariants.md

@@ -0,0 +1,49 @@
+# CI pipeline & trigger invariants
+
+Shaped by [milestone #18](https://github.com/Fallout-build/Fallout/milestone/18)
+and the branch model in [ADR-0009](../../../../docs/adr/0009-gitflow-and-semver-reversion.md)
+(carrying forward [ADR-0008](../../../../docs/adr/0008-collapse-experimental-into-main.md),
+which collapsed `experimental` into the integration trunk).
+
+- **Feature branches run zero CI until a PR is opened.** Push triggers list
+  **only** long-lived branches; nothing fires on `feature/*`, `bugfix/*`, etc.
+  until they're PR'd against `develop`/`main`/`release/*`/`support/*`. Do
+  **not** add a working-branch pattern to any `OnPush*`/`branches:` trigger.
+- **The Linux PR gate (job `ubuntu-latest`, from `build.yml`) is the only
+  required check** — runs on PRs to the long-lived branches. (Branch
+  protection keys on the job name, not the workflow file.)
+- **A push to `develop` publishes `-preview`** to GitHub Packages
+  (`publish-packages-preview.yml`). It's the only continuous publisher —
+  there is still no `experimental.yml`.
+- **Cross-platform `windows`/`macos` only run on release intent** — one
+  `build-cross-platform.yml` workflow (a job per OS), firing on a PR into
+  `main`/`release/*`/`support/*`, or a `v*` tag push. They do **not** run on
+  `develop` pushes. `develop` relies on the Linux gate instead.
+- **`concurrency: cancel-in-progress` on every build workflow except
+  `publish-packages-release.yml`** — never cancel a publish mid-flight.
+- **Canonical CI-ignore paths:** `docs/**`, `.assets/**`, `**/*.md` — applied
+  to every PR/push trigger.
+- The `build.yml` (Linux gate) and `build-cross-platform.yml` (macOS+Windows)
+  workflows are **generated** from `build/Build.CI.GitHubActions.cs` — edit
+  the attributes + constants there and regenerate (`./build.sh`), never
+  hand-edit the `.yml`. `build-skip.yml`, `publish-packages-preview.yml`, and
+  `publish-packages-release.yml` are hand-written.
+- **Every publishing lane runs `Test` before it publishes** (#324).
+  `publish-packages-preview.yml` and `publish-packages-release.yml` both run
+  a single `dotnet fallout Test Pack` invocation — NUKE executes it as
+  discrete internal stages (Restore → Compile → Test → Pack) and fails at the
+  breaking stage, so a test failure stops the job before the push step. Don't
+  split a lane into separate `dotnet fallout Compile`/`Test`/`Pack` steps —
+  each invocation re-runs the dependency graph (double-compile); the single
+  invocation *is* the staged build.
+- **Caching** (#328): every workflow caches `~/.nuget/packages` +
+  `.fallout/temp`, keyed on `global.json` + `**/*.csproj` +
+  `Directory.Packages.props` (the dependency-affecting set), with a
+  `restore-keys:` prefix fallback for partial restores. There is no
+  `packages.lock.json` to add to the key, and build outputs (`bin`/`obj`) are
+  deliberately **not** cached (stale-artifact correctness risk).
+- Don't add `submodules: recursive` to a checkout — there are no submodules
+  (no `.gitmodules`); it's a dead init step.
+- Don't add `develop` (or any working-branch pattern) to the **push** triggers
+  of the cross-platform workflows — they're release-intent-gated on purpose
+  (milestone #18 / #318 / #326).

.agents/skills/marking-experimental-apis/SKILL.md

@@ -0,0 +1,69 @@
+---
+name: marking-experimental-apis
+description: How to mark a public API as not-yet-stable with [Experimental("FALLOUT0xx")], or deprecate one with [Obsolete(..., DiagnosticId = "FALLOUTOBS0xx")], including diagnostic-ID allocation. Trigger when adding public API that isn't ready for a stability guarantee, or removing/replacing/deprecating an existing public API.
+---
+
+Fallout has two attributes for public-surface churn, each with its own
+diagnostic-ID sequence and registry. Never mix the two sequences.
+
+## `[Experimental]` — opt-in unstable surface
+
+Use [`System.Diagnostics.CodeAnalysis.ExperimentalAttribute`](https://learn.microsoft.com/dotnet/api/system.diagnostics.codeanalysis.experimentalattribute)
+(ships in the .NET 8+ BCL, no package reference needed) for public API that
+isn't ready to commit to a stability guarantee:
+
+```csharp
+using System.Diagnostics.CodeAnalysis;
+
+[Experimental("FALLOUT001")]
+public sealed class NewPluginHost { /* ... */ }
+```
+
+- **Allocate the next `FALLOUT0xx` ID sequentially, never reused.** Register it
+  in [docs/experimental-apis.md](../../../docs/experimental-apis.md) in the
+  same PR.
+- **`ExperimentalAttribute` is error-by-default.** A consumer must explicitly
+  suppress the exact ID (`#pragma warning disable FALLOUT001` or `<NoWarn>`) to
+  use the API — that's the opt-in.
+- **Promoting to stable = deleting the attribute.** No cross-branch dance —
+  the feature already rode the `develop` preview lane. Adding or removing
+  `[Experimental]` is **not** a breaking change.
+- **On a `release/vX.Y` / `main` production line, any risky-but-shipped public
+  surface must wear it.** That's what keeps the production line trustworthy
+  while it still carries new work — there's no separate `experimental` branch.
+- **Don't apply it speculatively.** Marking an API that's already used
+  internally breaks the build everywhere it's referenced — suppress every
+  internal usage in the same change.
+
+## `[Obsolete]` — deprecating a stable API
+
+Use [`System.ObsoleteAttribute`](https://learn.microsoft.com/dotnet/api/system.obsoleteattribute)
+with a `DiagnosticId` (ships in the .NET 5+ BCL) when a stable public API is on
+its way out:
+
+```csharp
+[Obsolete(
+    "Use [GitHubActionsInputAttribute] instead. Removed in v11.",
+    DiagnosticId = "FALLOUTOBS001",
+    UrlFormat = "https://github.com/Fallout-build/Fallout/blob/main/docs/obsolete_apis.md")]
+public string[] OnWorkflowDispatchOptionalInputs { get; set; } = new string[0];
+```
+
+- **Allocate the next `FALLOUTOBS0xx` ID sequentially, never reused** — a
+  separate sequence from `FALLOUT0xx` above. Register it in
+  [docs/obsolete_apis.md](../../../docs/obsolete_apis.md) in the same PR.
+- **Always set `DiagnosticId`.** Without one the compiler reports the generic
+  `CS0618`, so a `TreatWarningsAsErrors` consumer can only fix every usage at
+  once or blanket-suppress every deprecation. A per-deprecation ID lets them
+  suppress just this one while they migrate.
+- **Adding `[Obsolete]` is not a breaking change** — it's warning-level, so
+  existing code keeps compiling. The *removal* is the break, and it waits for
+  the next major. State the removal target in the message (e.g. `Removed in v11.`).
+- **Keep the deprecated surface functional.** Prefer bridging the old member to
+  the new one over leaving it inert, and suppress the internal bridge usage
+  with `#pragma warning disable` scoped to the exact ID.
+
+See [AGENTS.md rule 2](../../../AGENTS.md) for how these fit the
+backwards-compatibility policy, and the `creating-a-pr` skill for how a
+breaking change (as opposed to marking something experimental or obsolete)
+needs to be labelled and targeted.