chore(platform): close remaining epic gaps — ADR-0005, script fix, project ID

- decisions/0005-reusable-workflow-split.md formalises the .github vs
  platform reusable-workflow split rule (closes ADR-0001 §pending)
- New-AzureLocalRepo.ps1: pull remote LICENSE before push (gh repo
  create --license MIT auto-seeds main); fail loudly on push errors
  instead of falsely logging PASS. Adds -SolutionOptionId parameter
  + {{SOLUTION_OPTION_ID}} token so add-to-project.yml is no longer
  templated with a placeholder
- _common/add-to-project.yml: token instead of REPLACE_WITH placeholder
- platform/add-to-project.yml: real Platform option GUID 9c3da2ef
- decisions/README.md: index now lists ADR-0003, 0004, 0005

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: Kristopher Turner

.github/workflows/add-to-project.yml

@@ -11,9 +11,7 @@ jobs:
     uses: AzureLocal/.github/.github/workflows/reusable-add-to-project.yml@main
     with:
       id-prefix: PLATFORM
-      # TODO: Update solution-option-id to the GUID for the "Platform" option on the Azure Local Solutions project board.
-      # The ID can be found via: gh api graphql -f query='{ organization(login: "AzureLocal") { projectV2(number: 3) { fields(first: 20) { nodes { ... on ProjectV2SingleSelectField { name options { id name } } } } } } }'
-      solution-option-id: REPLACE_WITH_SOLUTION_OPTION_ID
+      solution-option-id: '9c3da2ef'
     secrets:
       AZL_APP_ID: ${{ secrets.AZL_APP_ID }}
       AZL_APP_PRIVATE_KEY: ${{ secrets.AZL_APP_PRIVATE_KEY }}

decisions/0005-reusable-workflow-split.md

@@ -0,0 +1,69 @@
+# ADR 0005 — Reusable workflow split between `AzureLocal/.github` and `AzureLocal/platform`
+
+- **Status**: Accepted
+- **Date**: 2026-04-13
+- **Deciders**: @kristopherjturner
+
+## Context
+
+Reusable GitHub Actions workflows for the AzureLocal org could plausibly live in either of two existing repos:
+
+- [`AzureLocal/.github`](https://github.com/AzureLocal/.github) — the org's GitHub-metadata repo. Already hosts `reusable-add-to-project.yml`, `reusable-release-please.yml`, `reusable-validate-structure.yml`.
+- [`AzureLocal/platform`](https://github.com/AzureLocal/platform) — the org's developer-tooling repo created by [ADR-0001](./0001-create-platform-repo.md). Hosts standards, testing frameworks, and templates.
+
+Without a written rule, every new reusable workflow becomes a judgement call about where it should live. ADR-0001 deferred this decision; [`docs/reusable-workflows/split-rule.md`](../docs/reusable-workflows/split-rule.md) sketched the rule informally. This ADR formalises it.
+
+The rule has practical consequences: each repo has its own release cadence (`.github` rarely changes, `platform` evolves with frameworks), its own contributor audience, and a different blast radius if a workflow regresses.
+
+## Decision
+
+Adopt the **stack-vs-governance split**:
+
+> **`AzureLocal/.github` owns governance workflows — those that apply to every repo regardless of stack.**
+>
+> **`AzureLocal/platform` owns stack-specific workflows — those that apply only to certain repo types (PS module, TS web app, IaC, MkDocs site, MAPROOM consumer).**
+
+Plus three corollaries:
+
+1. **Single-consumer workflows are not reusable.** If only one repo uses a workflow, keep it local to that repo. A reusable workflow must have at least two plausible consumers.
+2. **A workflow that's both universal and stack-specific** (e.g., release-please publishing to PSGallery) splits along the seam: the governance half goes to `.github`, the stack-specific half goes to `platform`.
+3. **New universal workflows default to `.github`.** If one ends up in `platform` for convenience, revisit at the next major version.
+
+## Consequences
+
+### Positive
+
+- **Discovery is predictable.** A contributor browsing `AzureLocal/.github` for "how do I contribute" doesn't wade past TypeScript build internals.
+- **Release cadences are decoupled.** `platform` can ship breaking changes to a stack-specific workflow without forcing a `.github` release.
+- **Blast radius is bounded.** A bad governance workflow breaks every repo. A bad stack-specific workflow breaks only the repos in that stack. The split limits the worst case.
+- **Authority is clear for cross-repo conformance.** `Test-RepoConformance` (in `AzureLocal.Common`) only has to check that `deploy-docs.yml` references `AzureLocal/platform/.github/workflows/reusable-mkdocs-deploy.yml@<ref>` — never `.github` — because docs deployment is stack-specific by definition.
+
+### Negative
+
+- **Two repos to track for workflow versions.** Consumers pin two refs separately (`@v1` for `.github`, `@v1` for `platform`). Mitigated by documenting the canonical pin patterns in [`docs/reusable-workflows/consumer-patterns.md`](../docs/reusable-workflows/consumer-patterns.md).
+- **Edge cases require a judgement.** When a workflow blurs the governance/stack line, the corollary in §Decision applies — but applying it correctly requires the maintainer to think carefully. ADR doesn't remove the judgement, only makes it consistent.
+- **Two ADR-required surfaces.** Adding a new reusable workflow to either repo now requires an ADR. Documented overhead, accepted as the cost of explicit decisions.
+
+### Neutral
+
+- The current lineup (`reusable-add-to-project`, `reusable-release-please`, `reusable-validate-structure` in `.github`; the six `reusable-*` workflows in `platform`) already follows the rule. This ADR codifies the existing state, no migration required.
+
+### Affected repos / owners
+
+- **`AzureLocal/.github`**: no change today. Future governance workflows land here.
+- **`AzureLocal/platform`**: no change today. Future stack-specific workflows land here.
+- **All consumer repos**: no change today. Already pin against the correct repos per the rule.
+- **Maintainer**: every new reusable workflow proposal should cite this ADR and state which side of the rule it falls on.
+
+## Alternatives considered
+
+- **Single repo for all reusable workflows** — rejected. Discovery and blast-radius arguments above. The cost of a second repo (already paid — both repos exist) is lower than the cost of mixing governance and stack content.
+- **Per-stack repos** (`AzureLocal/ps-workflows`, `AzureLocal/ts-workflows`, etc.) — rejected. Would multiply the number of repos a consumer pins and the number of major-version axes to track. The current two-repo split is the minimum viable separation.
+- **Live in the consumer repos themselves; share via copy-paste** — rejected. This is the drift problem [ADR-0001](./0001-create-platform-repo.md) and [ADR-0002](./0002-standards-single-source.md) already solved for standards. Rejected on the same grounds.
+- **Keep the rule informal in `docs/reusable-workflows/split-rule.md` only** — rejected. Without an ADR the rule is a documentation note, not a governing decision. ADR makes it citable and reviewable.
+
+## Status
+
+Accepted 2026-04-13. Supersedes the "ADR 0004 — reusable-workflow-split" placeholder referenced in [ADR-0001](./0001-create-platform-repo.md). (ADR-0004 was repurposed for testing-toolset classification.)
+
+The rule is also documented in user-facing form at [`docs/reusable-workflows/split-rule.md`](../docs/reusable-workflows/split-rule.md). When the ADR and the docs page diverge, this ADR wins; update the docs page accordingly.

decisions/README.md

@@ -8,8 +8,9 @@ Lightweight, numbered, immutable records of cross-cutting decisions that affect
 |---|---|---|
 | [0001](./0001-create-platform-repo.md) | Create AzureLocal platform repo | Accepted |
 | [0002](./0002-standards-single-source.md) | Standards as single source of truth | Accepted |
-| `0003` | MAPROOM & IIC canon (pending Phase 2) | Proposed |
-| `0004` | Reusable workflow split between .github and platform | Proposed |
+| [0003](./0003-maproom-iic-canon.md) | MAPROOM framework & IIC canon centralization | Accepted |
+| [0004](./0004-testing-toolset-classification.md) | Testing toolset classification rubric | Accepted |
+| [0005](./0005-reusable-workflow-split.md) | Reusable workflow split between .github and platform | Accepted |
 
 ## When to write an ADR
 

docs/reusable-workflows/split-rule.md

@@ -67,4 +67,4 @@ Ask one question: *does every AzureLocal repo benefit from this, or only a subse
 
 - [Consumer patterns](consumer-patterns.md) — copy-paste examples
 - [Versioning](versioning.md) — how to pin, how to bump
-- [ADR 0004 (pending) — reusable-workflow-split](https://github.com/AzureLocal/platform/blob/main/decisions/0004-reusable-workflow-split.md)
+- [ADR 0005 — reusable-workflow-split](https://github.com/AzureLocal/platform/blob/main/decisions/0005-reusable-workflow-split.md)

repo-management/org-scripts/New-AzureLocalRepo.ps1

@@ -70,6 +70,9 @@ param(
 
     [string]$ModuleName,
 
+    [Parameter(HelpMessage='GUID for the matching option on the AzureLocal Solutions project board (Solution field). Look up via: gh api graphql -f query=''{ organization(login: "AzureLocal") { projectV2(number: 3) { fields(first: 30) { nodes { ... on ProjectV2SingleSelectField { name options { id name } } } } } } }''')]
+    [string]$SolutionOptionId = '',
+
     [switch]$DryRun,
     [switch]$SkipBranchProtection,
     [switch]$SkipLabels,
@@ -113,6 +116,12 @@ $tokens = @{
     '{{MODULE_GUID}}'      = [guid]::NewGuid().ToString()
     '{{ID_PREFIX}}'        = $ModuleName.ToUpper()
     '{{MAPROOM}}'          = if ($Type -eq 'ps-module') { 'true' } else { 'false' }
+    '{{SOLUTION_OPTION_ID}}' = $SolutionOptionId
+}
+
+if (-not $SolutionOptionId) {
+    Log 'WARN' "No -SolutionOptionId supplied. add-to-project.yml will need a manual edit before the workflow runs successfully."
+    Log 'INFO' "Look up the GUID with: gh api graphql -f query='{ organization(login: \"AzureLocal\") { projectV2(number: 3) { fields(first: 30) { nodes { ... on ProjectV2SingleSelectField { name options { id name } } } } } } }'"
 }
 
 # Workflows adopted
@@ -214,9 +223,20 @@ try {
     git config user.email 'github-actions[bot]@users.noreply.github.com'
     git config user.name  'github-actions[bot]'
     git remote add origin "https://github.com/AzureLocal/$Name.git"
+
+    # gh repo create --license MIT seeds remote main with a LICENSE commit.
+    # Pull it in so the scaffold push isn't rejected as non-fast-forward.
+    git fetch origin main --quiet 2>$null
+    if ($LASTEXITCODE -eq 0) {
+        git reset --soft FETCH_HEAD --quiet
+    }
+
     git add -A
     git commit -m "chore: scaffold $Name from platform template ($Type)" --quiet
     git push -u origin main --quiet
+    if ($LASTEXITCODE -ne 0) {
+        throw "git push to AzureLocal/$Name failed (exit $LASTEXITCODE) — scaffold not on remote."
+    }
     Log PASS "Initial commit pushed."
 } finally {
     Pop-Location

templates/_common/.github/workflows/add-to-project.yml

@@ -11,7 +11,7 @@ jobs:
     uses: AzureLocal/.github/.github/workflows/reusable-add-to-project.yml@main
     with:
       id-prefix: {{ID_PREFIX}}
-      solution-option-id: REPLACE_WITH_SOLUTION_OPTION_ID
+      solution-option-id: '{{SOLUTION_OPTION_ID}}'
     secrets:
       AZL_APP_ID: ${{ secrets.AZL_APP_ID }}
       AZL_APP_PRIVATE_KEY: ${{ secrets.AZL_APP_PRIVATE_KEY }}