design+structure: full plan audit, 6 new ADRs, drop dead weight

Plan audit follow-up addressing every gap raised in the design review.

PLAN.md cleanup (cut dead weight):
- Drop Org Standards section detail referencing private AzureLocal/platform
  (file contents, badge URLs, version pins moved to private repo memory)
- Drop "Phase 0 platform compliance checklist" (Phase 0 is complete; checklist
  was stale)
- Drop "Blog & New Repo Reminders" block (project-management noise, not design)
- Drop stale MkDocs nav example (live mkdocs.yml is source of truth)
- Fix Override pack name in Key Decisions table:
  AzureLocal.SCOM.MP.Overrides.xml -> AzureLocal.SCOM.Override.xml (per ADR 0007)
- Fix Org standards row in Key Decisions table (no longer references public badge)
- Fix repo structure tree: squaredup/ shown at root -> moved under src/
- Reconcile SquaredUp appendix: drop "Evaluate" language, point to committed
  Phase 3 Step 4 / Phase 4 Step 5 work

Mermaid diagrams moved into docs/ (so MkDocs renders them):
- diagrams/mermaid/scom-health-rollup.md   -> docs/scom-mp/diagrams/health-tree.md
- diagrams/mermaid/azure-monitor-entity-graph.md -> docs/azure-monitor/diagrams/entity-graph.md
- diagrams/mermaid/health-state-flow.md    -> docs/design/diagrams/health-state-flow.md
- diagrams/mermaid/ removed (drawio/ stays as editable originals)
- mkdocs.yml nav: add Diagrams sub-section to SCOM MP, Azure Monitor, and Design

Six new ADRs (all Accepted) filling design gaps:

  ADR 0014 - CI/CD Pipeline Strategy
    GitHub Actions only; one workflow per artifact stream (mp-build,
    bicep-validate, pwsh-test, kql-validate, parity-check, docs-build,
    docs-deploy, release-please). OIDC-only auth to Azure. release-please
    in Conventional Commits mode. parity-check.yml mechanically enforces
    ADR 0007 cross-track naming.

  ADR 0015 - Testing Strategy
    5-layer test pyramid: static/lint, unit (Pester + KustoLoco),
    integration (bicep what-if + LAW seed), cross-track parity (THE
    keystone gate for ADR 0007), and behavioral acceptance at release.
    tests/Test-Parity.ps1 walks signal-catalog.md and asserts every
    threshold name appears in BOTH the SCOM override pack AND a bicepparam
    tier.

  ADR 0016 - Signing & Secrets Management
    Two-key SCOM MP signing model: test key (free dev access) vs release
    key (HSM-backed Key Vault, OIDC-only, manual-approval release env).
    Three OIDC-federated SPNs (pr/lab/release) - zero long-lived secrets
    in repo. gitleaks pre-commit + push-protection. Release key never
    rotated (sealed-MP version contract).

  ADR 0017 - Versioning & Release Policy
    Single repo SemVer version covers all three artifact streams (sealed
    MPs, Bicep, docs). Detailed bump rules table (add class = minor,
    rename param = major, etc). Library MP coupling rule: any Library
    version change is Minor minimum, never Patch. Conventional Commits
    -> release-please. mike-versioned docs site with version selector.

  ADR 0018 - Self-Observability ("Monitor the Monitor")
    9 new AzureLocal.Monitoring.* entities + 12 signals covering SCOM
    agent, AMA extension, DCR association, DCMA, LAW ingestion, alert-rule
    health, and signal-query health. Rolls up under a parallel root
    branch (NOT under cluster) so a dead pipeline turns the root red even
    when cluster shows stale Healthy. Dedicated Sev2 action group, own
    dashboard panel.

  ADR 0019 - Cost, Scale, and Data Retention
    Per-tier ingestion envelope: Lab ~250 MB/day, Standard ~600 MB/day,
    Strict ~1.2 GB/day per 4-node cluster. Hard scale cap: 50 clusters
    per service group; >50 = shard via per-region service groups.
    Retention by data class: HealthState 90d, Perf 30d interactive +
    365d archive, Self-Observability 30d. 5-step cost downgrade playbook.

PLAN.md updates from new ADRs:
- Phase 2 ADR list: add 0014-0019 (was 0001-0013)
- Phase 2 sign-off: 13 ADRs -> 19 ADRs
- Phase 2 Definition of Done: explicit exit criteria (signal coverage per
  entity per dimension, parity test implementable from catalog, mkdocs
  build --strict passes, Self-Observability branch reflected in topology)
- Phase 3 Step 1: wire CI/CD scaffolding (ADR 0014), wire signing+identity
  (ADR 0016), wire test harness (ADR 0015) before authoring starts
- Phase 3 (added): Self-Observability monitors (ADR 0018), tuning runbooks
  (docs/scom-mp/runbooks/), DB sizing guidance (ADR 0019)
- Phase 4 Step 4 (added): sizing exercise to validate ADR 0019 numbers,
  Self-Observability KQL signals (ADR 0018), cost-tuning playbook (ADR 0019)
- References note: REFERENCES.md is authoritative; docs/references.md is
  generated via include-markdown plugin (no hand-edited duplicate)

mkdocs.yml: nav adds ADRs 0014-0019 + diagram pages under each section
ADR index: full table updated through 0019

Author: kristopherjturner

PLAN.md

@@ -0,0 +1,99 @@
+# ADR 0014 — CI/CD Pipeline Strategy
+
+- **Status**: Accepted
+- **Date**: 2026-05-05
+- **Deciders**: @kturner
+
+## Context
+
+Phase 3 (SCOM MP authoring) and Phase 4 (Azure Monitor Bicep) cannot start safely without a defined
+CI/CD pipeline. We need build-and-validate gates for three independent artifact streams:
+
+1. **SCOM MPs** — sealed `AzureLocal.SCOM.Library.mp` + sealed `AzureLocal.SCOM.Monitoring.mp` +
+   unsealed `AzureLocal.SCOM.Override.xml` (per ADR 0007)
+2. **Azure Monitor Bicep** — `src/azure-monitor/bicep/main.bicep` + modules + `.bicepparam` tiers
+   (per ADR 0013)
+3. **MkDocs documentation site** — published to GitHub Pages with `mike` versioning
+
+There is no pipeline yet. Without one, the three artifacts drift from each other and from the
+design docs, signing keys leak into hand-runs, and there is no reproducible release artifact.
+
+## Decision
+
+Adopt a **GitHub Actions–only** CI/CD model with one workflow per artifact stream, all triggered
+on PR and on push to `main`. Releases are cut by [release-please](https://github.com/googleapis/release-please)
+in Conventional Commits mode.
+
+### Workflows (under `.github/workflows/`)
+
+| Workflow | Trigger | Job summary |
+|---|---|---|
+| `mp-build.yml` | PR + main; tags `v*` | Restore VSAE solution → `MPSeal` against test key (PR) or prod key from KeyVault (release) → `MPVerify` → `MPBPA` → upload `*.mp` + `*.xml` as artifact |
+| `bicep-validate.yml` | PR + main | `bicep build` all `.bicep` → `bicep lint` → `az deployment sub what-if` against the lab subscription using `lab.bicepparam` → publish ARM JSON to `dist/` artifact |
+| `pwsh-test.yml` | PR + main | `Invoke-ScriptAnalyzer -Settings PSGallery -Severity Warning,Error` → run `Pester` against `src/scom-mp/discovery/*.Tests.ps1` and `src/azure-monitor/scripts/*.Tests.ps1` |
+| `kql-validate.yml` | PR + main | Validate every `kql/signals/*.kql` file parses (`Kusto.Language` parser) and runs against the lab LAW with mock seed data; assert expected health state |
+| `parity-check.yml` | PR + main | Custom step (PowerShell) that walks `signal-catalog.md` and asserts every threshold name appears in **both** the SCOM override pack AND a `bicepparam` tier (cross-track parity per ADR 0007) |
+| `docs-build.yml` | PR | `mkdocs build --strict` → run `lychee` link-check across rendered site |
+| `docs-deploy.yml` | push main; release tag | `mike deploy --update-aliases <version> latest` → `mike set-default latest` → push to `gh-pages` |
+| `release-please.yml` | push main | Standard release-please action — opens/maintains release PR, on merge tags `vX.Y.Z` and creates GitHub Release |
+
+### Branch protection on `main`
+
+- All seven workflows above must pass
+- Linear history required; squash-merge only
+- One review required, code-owner required for `src/scom-mp/`, `src/azure-monitor/bicep/`, and `docs/design/decisions/`
+
+### Identity model
+
+- **Cloud-side jobs** (`bicep-validate`, `kql-validate`) authenticate to Azure via **GitHub OIDC**
+  federated to a dedicated lab-only service principal — no long-lived secrets in repo settings.
+- **MP signing key** for release builds is fetched from Azure Key Vault using the same OIDC SPN;
+  scoped to a release-only environment that requires manual approval (see ADR 0016).
+
+### Out of scope (deliberately)
+
+- Self-hosted runners — start on GitHub-hosted, revisit only if KQL or Bicep eval cost becomes
+  a real problem.
+- Container builds — no containers in this repo.
+- Third-party CI (Azure Pipelines, Jenkins) — explicitly rejected; the org standard is GH Actions.
+
+## Consequences
+
+- **Positive**:
+  - Every artifact has a green-build gate before it can land on `main`.
+  - `parity-check.yml` mechanically enforces the cross-track naming guarantee from ADR 0007 —
+    so the design promise survives long-term drift.
+  - Release-please gives clean SemVer tags and an auto-generated changelog matching the
+    org-standard format.
+  - OIDC eliminates the "rotate the SPN secret" toil and the leak-in-logs risk.
+- **Negative**:
+  - More workflow YAML to maintain than a single monolith would need.
+  - `kql-validate` requires a long-lived lab LAW with seeded fixtures — small but ongoing cost.
+- **Neutral**:
+  - Pipeline lives in `.github/workflows/` only; no Azure DevOps mirror.
+- **Affected components / owners**: All Phase 3 and Phase 4 deliverables, plus the Phase 6
+  release process. Workflow files added by the first commit of Phase 3 work.
+
+## Alternatives considered
+
+- **Single monolithic CI workflow** — rejected; couples MP, Bicep, KQL, and docs cycle times,
+  and surfaces unrelated failures on every PR.
+- **Self-hosted runners on a SCOM management server** — rejected for now; GitHub-hosted Windows
+  runners can install VSAE/MPVerify on demand, and self-hosted adds opex without a clear win at
+  Phase 3.
+- **Azure DevOps Pipelines** — rejected; not the org standard, and OIDC + release-please are
+  better-supported in GitHub Actions.
+- **No `parity-check`** — rejected; ADR 0007's cross-track naming promise is unenforceable
+  without a mechanical gate, and would silently rot.
+- **`bicep what-if` only at release time** — rejected; what-if is the cheapest way to catch
+  schema drift on Health Model preview API churn, so it runs every PR.
+
+## References
+
+- ADR 0007 — Naming convention (cross-track parity)
+- ADR 0013 — Azure Monitor deployment strategy (Bicep-first)
+- ADR 0016 — Signing & secrets management (sibling ADR for key handling detail)
+- ADR 0017 — Versioning & release policy (sibling ADR; release-please configuration)
+- [release-please](https://github.com/googleapis/release-please)
+- [Azure login GitHub Action with OIDC](https://learn.microsoft.com/en-us/azure/developer/github/connect-from-azure)
+- Brian Wren MP authoring guide — MPSeal / MPVerify usage

diagrams/mermaid/.gitkeep

@@ -0,0 +1,113 @@
+# ADR 0015 — Testing Strategy
+
+- **Status**: Accepted
+- **Date**: 2026-05-05
+- **Deciders**: @kturner
+
+## Context
+
+The repo ships three artifact streams (sealed SCOM MPs, Bicep modules, MkDocs site) that are
+authored independently but must remain semantically aligned (same logical thresholds, same
+entity model, same health propagation). Phase 3 and Phase 4 cannot have a "done" gate without a
+defined verification approach. ADR 0014 lists the *workflows* that run tests; this ADR defines
+*what* the tests are and *what coverage means* for each artifact.
+
+## Decision
+
+Adopt a **layered test pyramid** scoped to what is realistically testable per artifact, with one
+hard gate per layer. No artifact merges to `main` without its layer passing.
+
+### Layer 1 — Static / lint (every PR, fast)
+
+| Artifact | Tool | Gate |
+|---|---|---|
+| SCOM MP XML | `MPVerify.exe` | Zero errors; warnings reviewed |
+| SCOM MP XML | `MPBPA` (MP Best Practice Analyzer) | Zero criticals; warnings reviewed |
+| Bicep | `bicep build` + `bicep lint --diagnostics-format sarif` | Zero `error`-severity diagnostics |
+| PowerShell | `PSScriptAnalyzer` (Settings: `PSGallery`, Severity ≥ `Warning`) | Zero `Error`; `Warning` reviewed |
+| KQL | `Microsoft.Azure.Kusto.Language` parser | Every `*.kql` parses successfully |
+| Markdown | `markdownlint-cli2` (default rules + `MD013` off) | Zero errors |
+| Links | `lychee` against built MkDocs site | Zero broken internal links; external links cached + warn-only |
+
+### Layer 2 — Unit (every PR, fast, hermetic)
+
+| Artifact | Tool | What gets tested |
+|---|---|---|
+| PowerShell discovery scripts (SCOM) | `Pester 5.x` | Every discovery in `src/scom-mp/discovery/` has a sibling `*.Tests.ps1` that mocks `Get-Cluster`, `Get-PhysicalDisk`, `Get-StoragePool`, etc. and asserts the discovery emits the expected `<Instance>` elements |
+| KQL signals | `KustoLoco` (or LAW with seed table) — local Kusto evaluator | Each `kql/signals/<signal>.kql` has a sibling `<signal>.tests.json` listing `{seed_rows, expected_state}` cases; harness loads seed, runs query, asserts `HealthState` column matches |
+| Bicep modules | `bicep what-if` against an empty resource group | Each module deploys cleanly with `lab.bicepparam`; what-if returns expected resource set |
+| Health rollup logic | Pester | Synthetic entity tree fed through aggregate/dependency monitor logic; assert worst-state per ADR 0003 |
+
+### Layer 3 — Integration (PR + nightly, against lab subscription)
+
+| Artifact | Method | Gate |
+|---|---|---|
+| Bicep stack | `az deployment sub create` against lab subscription using `lab.bicepparam` | Deployment succeeds; smoke test queries `healthmodels` resource and asserts entities match `entities.bicep` count |
+| KQL signals (live) | Run every signal against lab LAW with seeded HCI cluster | Each signal returns at least one row of expected schema (`HealthState`, `EntityId`, `Timestamp`) |
+| MP load test | Import sealed MPs into pre-prod SCOM management group | All discoveries run within 10 minutes; no `Health Service Modules` event-log errors |
+
+### Layer 4 — Cross-track parity (every PR, hard gate)
+
+This is the keystone test that protects ADR 0007's naming-parity promise. A single PowerShell
+script (`tests/Test-Parity.ps1`) walks:
+
+1. `docs/design/signal-catalog.md` — extract every `Threshold name` column entry
+2. `src/scom-mp/AzureLocal.SCOM.Override.xml` — extract every `<Override>` parameter name
+3. `src/azure-monitor/bicep/parameters/*.bicepparam` — extract every parameter assignment
+
+Asserts: **every threshold name in the catalog appears in BOTH the SCOM override pack AND at least
+one bicepparam file**, and vice versa (no orphan parameters on either side). Fails the PR with a
+diff if any names diverge.
+
+### Layer 5 — Behavioral / acceptance (release tag only)
+
+| Artifact | Method |
+|---|---|
+| Full SCOM MP | Deploy to pre-prod SCOM, run for 24h, capture `OperationsManager` event log; assert no script-runtime errors, no orphaned discoveries |
+| Full Azure Monitor stack | Deploy `standard.bicepparam` to a real Azure Local lab cluster, drive a known fault (e.g. fail a physical disk), assert root-entity health flips to Degraded within 15 minutes |
+
+### Test code location
+
+- Pester tests: alongside the script under test (`Foo.ps1` → `Foo.Tests.ps1`)
+- KQL signal seed data: `src/azure-monitor/kql/signals/<signal>.tests.json`
+- Cross-track parity: `tests/Test-Parity.ps1` (top-level `tests/`)
+- Behavioral acceptance scripts: `tests/acceptance/` (excluded from PR runs; tagged `Acceptance`)
+
+### What is **not** tested in CI
+
+- SCOM-side end-to-end with real cluster — too expensive for PR runs; covered by Layer 5 release gate
+- Performance / scale (max cluster size, max signals) — captured as a separate Phase 6 perf-baseline exercise, not a gate
+- Localization — out of scope (English-only deliverable)
+
+## Consequences
+
+- **Positive**:
+  - Every PR has a fast, hermetic gate (Layer 1 + 2) that catches structural and logic regressions before integration cost is paid.
+  - Layer 4 mechanically enforces cross-track parity — the design promise from ADR 0007 cannot silently rot.
+  - Layer 5 acceptance gate gives confidence to cut a SemVer release without manual smoke testing.
+- **Negative**:
+  - Authoring overhead — every discovery script and every KQL signal requires a sibling test file. Will slow down Phase 3 day-1 velocity.
+  - Layer 3 requires an always-on lab subscription with a seeded LAW, which has small but ongoing Azure cost.
+- **Neutral**:
+  - Test runners are GitHub-hosted Windows for MP/Pester, ubuntu-latest for everything else.
+- **Affected components / owners**: All Phase 3 and Phase 4 deliverables. The first PR for Phase 3 must include `tests/Test-Parity.ps1` and at least one Pester test file as the pattern reference.
+
+## Alternatives considered
+
+- **Manual test plan, no automation** — rejected; cross-track parity cannot be sustained by manual review across ~250 signals.
+- **Pester for Bicep too** — rejected; `bicep what-if` is the right tool for IaC validation, Pester for PowerShell only.
+- **End-to-end test on every PR** — rejected; too expensive (Azure deployment time, lab quota), held to nightly + release.
+- **Test in production SCOM** — rejected; Layer 5 uses pre-prod SCOM only.
+- **Skip Layer 4 (parity)** — rejected; ADR 0007's value is gated entirely on this test existing.
+
+## References
+
+- ADR 0003 — Health rollup policy (drives Layer 2 rollup tests)
+- ADR 0007 — Naming convention (drives Layer 4 parity test)
+- ADR 0013 — Azure Monitor deployment strategy (Bicep what-if as Layer 1+3)
+- ADR 0014 — CI/CD pipeline (workflows that run these tests)
+- [Pester](https://pester.dev/)
+- [PSScriptAnalyzer](https://learn.microsoft.com/en-us/powershell/module/psscriptanalyzer/)
+- [KustoLoco](https://github.com/NeilMacMullen/KustoLoco) — local Kusto evaluator for offline KQL tests
+- [bicep what-if](https://learn.microsoft.com/en-us/azure/azure-resource-manager/bicep/deploy-what-if)
+- Brian Wren — MPVerify and MPBPA usage