feat(catalog): model GitHub Code Quality as its own billing tier

AGENTS.md

@@ -32,8 +32,13 @@ repositories pin by full commit SHA. Docs under `docs/` are human mirrors;
 - Tier claims (public / private-free / private-paid) must match the real
   GitHub billing contract. Known plan gate: GitHub Artifact Attestations are
   public-only on Free/Pro/Team plans; private/internal repositories require
-  GitHub Enterprise Cloud (GHAS/Code Security does not unlock them). GitHub
-  Code Quality becomes a paid product on 2026-07-20 — refresh that fact then.
+  GitHub Enterprise Cloud (GHAS/Code Security does not unlock them). Second
+  known gate: GitHub Code Quality (GA and billable since 2026-07-20) is **not**
+  sorted by visibility — it is billed per active committer on public repos too,
+  on a licence independent of GHAS, with committers counted once per
+  organization. It is a platform feature with no REST/GraphQL API, so it carries
+  `workflow: null` / `example: null` and lives in its own tier doc
+  (`docs/16-code-quality.md`); never fold it into the public tier.
 
 ## CI skills
 

CHANGELOG.md

@@ -2,6 +2,75 @@
 
 ## [Unreleased]
 
+### Added
+
+- **GitHub Code Quality is now a modelled tier instead of an unattached price
+  tag.** The product existed in the ledger as `github-code-quality-transition`
+  and nowhere else: no capability, no tier doc, no mention in the tier tables —
+  so the catalog priced a product it never told adopters how to place. It gets
+  `catalog/capabilities.yml` entry `github-code-quality` and a tier doc,
+  `docs/16-code-quality.md`.
+
+  It is deliberately **not** folded into the public tier. Re-verification
+  against the billing docs on 2026-08-01 established that visibility does not
+  gate the licence: a public repository is billed the same per-active-committer
+  rate as a private one, and being public only removes the Actions-minutes
+  component. That contradicted `docs/01-public-oss-free.md`, which promised the
+  "entire security and supply-chain suite for free" — a claim that would have
+  been false for any adopter who enabled Code Quality on a public repo. The
+  three-tier model sorts by visibility and plan; this product obeys neither, so
+  it is documented as an orthogonal fourth tier and **excluded** from both free
+  tiers, with the free maintainability substitutes (`coverage-gate.yml`,
+  `docs-quality.yml`, `pr-hygiene.yml`, zizmor, the language packs) named
+  explicitly.
+
+  Two further billing facts are now recorded because they invert the usual
+  cost-control instinct: committers are counted **once per organization**, so
+  enabling one repository already bills the whole active-committer set and a
+  "few paid repos, many free repos" split saves nothing unless the committer
+  sets actually differ; and the licence is independent of Code Security and
+  Secret Protection, so GHAS does not include it and holding both means paying
+  two products to drive one CodeQL engine.
+
+  The capability carries `workflow: null` and `example: null`, which is the
+  honest shape rather than a gap: Code Quality has no Action, no `workflow_call`
+  entrypoint, and no REST or GraphQL API, so enablement is UI-only and cannot be
+  pinned by SHA, asserted, or drift-checked from CI. For the same reason the
+  merge gate — ruleset rule "Require code quality results", severity threshold,
+  check `CodeQL - Code Quality` — is documented as a UI procedure and **not**
+  encoded in `.github/rulesets/`: those specs are shaped for
+  `POST /repos/{owner}/{repo}/rulesets` and the rule-type identifier for this
+  rule is undocumented. `AGENTS.md` records the gate so the next contributor does
+  not re-derive it, replacing a stale instruction to "refresh that fact" on a
+  date that has passed.
+
+- **The library described GitHub's price list, not this estate's receipts.**
+  Every tier doc reasoned from what GitHub charges a hypothetical adopter, so a
+  private NDDev repository was configured as if it were on the free plan while
+  the organization was already paying for Enterprise Cloud, Code Security,
+  Secret Protection, and Code Quality. `docs/17-nddev-tier.md` records the
+  verified entitlements and the advice that consequently does not apply.
+
+  The concrete loss this closes: `docs/02-private-free.md` routes private
+  releases to `release-supply-chain-free.yml` because Artifact Attestations
+  require Enterprise Cloud on private repos. This estate **has** Enterprise
+  Cloud, so all 26 private repositories were emitting `slsa_build_level: null`
+  and discarding provenance that was already bought. They can use the attested
+  `release-supply-chain.yml`.
+
+  Also recorded, because it inverts the usual cost instinct: these products bill
+  per active committer counted **once per organization**, so with one committer
+  the estate pays the same whether one repository or fifty are enabled — partial
+  coverage would have cost identically and protected less. `examples/nddev/`
+  joins the aggregate-example allowlist in `validate_catalog.py`, alongside the
+  three existing per-tier security suites.
+
+  The doc is explicit about what is *absent* too: Copilot Autofix is unavailable
+  (Copilot Business provisioned, zero seats assigned), and SHA pinning is
+  unenforced at both org and enterprise (`sha_pinning_required: false`) — flagged
+  rather than recommended blindly, since enabling it org-wide would break any
+  repository still pinning actions by tag.
+
 ### Fixed
 
 - **A grouped action bump could not land on its own.** Dependabot updates the

README.md

@@ -4,7 +4,8 @@ A **July-2026 GitHub-native CI/CD, security, governance, and supply-chain
 automation knowledge base plus reusable workflow library** for the NDDev estate.
 
 It separates three billing realities — **public OSS**, **private-free**, and
-**private-paid/GHAS** — ships SHA-pinned reusable workflows for each, and
+**private-paid/GHAS** — plus one opt-in product that ignores all three
+(**Code Quality**), ships SHA-pinned reusable workflows for each, and
 documents every capability with its status, cost model, risk, and implementation
 path in [`docs/`](docs/00-overview.md) and the machine-readable
 [`catalog/`](catalog/README.md).
@@ -21,6 +22,21 @@ See [`docs/01-public-oss-free.md`](docs/01-public-oss-free.md),
 [`docs/02-private-free.md`](docs/02-private-free.md), and
 [`docs/03-private-paid-ghas.md`](docs/03-private-paid-ghas.md).
 
+**GitHub Code Quality sits outside these three.** It is billed per active
+committer at *any* visibility — public repositories are **not** free — on a
+licence GHAS does not include, and committers are counted once per organization
+rather than per repository. Both free tiers exclude it; enable it deliberately
+via the org-level **Repository access** control. See
+[`docs/16-code-quality.md`](docs/16-code-quality.md).
+
+**The NDDev estate is not on the free plan.** The three tiers above describe what
+GitHub offers; [`docs/17-nddev-tier.md`](docs/17-nddev-tier.md) records what this
+organization has already bought — Enterprise Cloud, Code Security, Secret
+Protection, Code Quality — and which generic tier advice therefore does **not**
+apply here. Chiefly: private repositories release with attested
+`release-supply-chain.yml`, not the `-free` variant, because Artifact
+Attestations are gated on Enterprise Cloud and this estate has it.
+
 ## Capability → workflow map
 
 | Capability | Workflow | Public | Private-free | Private-paid |

catalog/capabilities.yml

@@ -34,6 +34,38 @@ capabilities:
       - "https://docs.github.com/en/code-security/code-scanning/introduction-to-code-scanning/about-code-scanning-with-codeql"
       - "https://github.com/github/codeql-action"
 
+  - id: github-code-quality
+    name: GitHub Code Quality
+    product_facts:
+      - github-code-quality-transition
+    cluster: security-scanning
+    status: ga
+    public_oss: paid
+    private_free: paid
+    private_paid: conditional
+    workflow: null
+    example: null
+    required_permissions: []
+    required_settings:
+      - "Team or Enterprise Cloud plan"
+      - "Enterprise owner allows Code Quality at the enterprise level"
+      - "Organization Settings -> Security -> Code quality -> Repository access scoped to the paid-tier repositories"
+      - "GitHub Actions enabled on the repository (scans run as Actions workflows)"
+      - "Optional PR gate: ruleset rule 'Require code quality results' with a severity threshold"
+    risks:
+      - "Billed per active committer on public repositories too; being public does not make it free the way CodeQL and GHAS are"
+      - "Committers are counted once per organization, so enabling a single repository already bills the whole active committer set"
+      - "Scans consume Actions minutes on private repositories; AI-assisted detection and Autofix consume AI credits"
+      - "Platform feature with no REST or GraphQL API: enable and disable are UI-only and cannot be asserted from CI"
+      - "Requiring code quality results blocks merges while analysis is still running or when it fails, e.g. on exhausted Actions minutes"
+    deprecations: null
+    last_verified: "2026-08-01"
+    sources:
+      - "https://docs.github.com/en/code-security/concepts/about-code-quality"
+      - "https://docs.github.com/en/code-security/how-tos/maintain-quality-code/enable-code-quality"
+      - "https://docs.github.com/en/code-security/how-tos/maintain-quality-code/set-pr-thresholds"
+      - "https://docs.github.com/en/billing/concepts/product-billing/github-code-quality"
+
   - id: ossf-scorecard
     name: OpenSSF Scorecard SARIF
     cluster: security-scanning

catalog/product-facts.yml

@@ -499,21 +499,29 @@ facts:
   conditions:
   - Public preview before 2026-07-20
   - GA and paid from 2026-07-20
+  - Repository visibility does not discount the licence; public repositories bill the same per-active-committer rate as private
+  - Active committers are counted once per organization across every repository with Code Quality enabled
+  - A committer is active if one of their commits was pushed in the last 90 days, regardless of authoring date
+  - Bot accounts are not billed
+  - Licence is independent of Code Security / Secret Protection; Advanced Security does not include it
   - AI capabilities add usage charges
   - Deterministic CodeQL analysis consumes Actions minutes
-  - Disable before 2026-07-20 to avoid paid enablement if not wanted
+  - Scope with the org-level Repository access control (all / selected / no repositories) to choose which repositories bill
   payment_method: required-from-2026-07-20
   overage: AI usage and Actions minutes may add cost
   status: official
   source_authority: primary
-  verified_at: '2026-07-21'
+  verified_at: '2026-08-01'
   expires_after: '2026-10-21'
   source_urls:
   - https://github.blog/changelog/2026-06-16-github-code-quality-generally-available-july-20-2026/
   - https://docs.github.com/en/billing/concepts/product-billing/github-code-quality
+  - https://docs.github.com/en/code-security/how-tos/maintain-quality-code/enable-code-quality
+  - https://docs.github.com/en/code-security/how-tos/maintain-quality-code/disable-code-quality
   notes:
   - 'GA + paid transition completed 2026-07-20 as scheduled; no longer time-critical.'
   - 'Re-verified 2026-07-21 against the billing docs: standalone per-active-committer license ($10/active committer/month), CodeQL scans consume Actions minutes, AI features consume AI credits at $0.01/credit, independent of Advanced Security licenses; Team + Enterprise Cloud.'
+  - 'Re-verified 2026-08-01: visibility does not gate the licence. Unlike CodeQL/GHAS, a public repository does NOT make Code Quality free — public repos only avoid the Actions-minutes component (standard runners are unmetered on public). This is why the tier docs exclude Code Quality from both free tiers instead of folding it into the public tier.'
 - id: gitlab-free-hosted
   provider: GitLab
   product: GitLab.com Free compute

docs/00-overview.md

@@ -27,6 +27,26 @@ Every doc here maps features to one of three tiers.
 | **Private-free (zero-cost only)** | actionlint, zizmor (no SARIF upload), gitleaks, static validation, SBOM + checksummed immutable releases (attestations need GHEC on private), OIDC, cross-platform smoke. CodeQL / native secret scanning / dependency review / harden-runner are **paid** and excluded | [02-private-free.md](02-private-free.md) |
 | **Private-paid / GHAS** | Code scanning, secret scanning + push protection, dependency review, Copilot Autofix, delegated governance — requires paid GitHub Code Security / Secret Protection | [03-private-paid-ghas.md](03-private-paid-ghas.md) |
 
+### The one capability that ignores the model
+
+**GitHub Code Quality** (GA and billable since 2026-07-20) is **not** sorted by
+visibility: it is billed per active committer on public repositories exactly as
+on private ones, its licence is independent of GHAS, and committers are counted
+once per organization rather than per repository. It therefore sits outside the
+three tiers as an opt-in fourth one — see
+[16 Code Quality tier](16-code-quality.md). Both free tiers exclude it, and the
+free maintainability substitutes are listed there.
+
+### What this estate actually owns
+
+The three tiers describe what GitHub *offers*. [17 NDDev estate
+tier](17-nddev-tier.md) records what the NDDev-it-com organization has **already
+bought** — Enterprise Cloud, Code Security, Secret Protection, and Code Quality —
+so repositories here stop being configured as if they were on the free plan. Its
+most consequential correction: Artifact Attestations are gated on Enterprise
+Cloud for private repos, and this estate **has** it, so private repositories
+release with full provenance instead of the `-free` variant.
+
 ## How to consume a reusable workflow
 
 Reference by `owner/repo/.github/workflows/<name>.yml@<full-sha>` from a caller
@@ -84,7 +104,9 @@ For end-to-end caller examples per tier, see the tier docs and the repository
 
 - Tiers: [01 Public OSS free](01-public-oss-free.md) ·
   [02 Private free](02-private-free.md) ·
-  [03 Private paid / GHAS](03-private-paid-ghas.md)
+  [03 Private paid / GHAS](03-private-paid-ghas.md) ·
+  [16 Code Quality](16-code-quality.md) ·
+  [17 NDDev estate](17-nddev-tier.md)
 - Platform: [04 Actions core](04-actions-core.md) · [05 Runners](05-runners.md)
 - Security: [06 Security scanning](06-security-scanning.md) ·
   [07 Supply chain / SLSA / SBOM / attestations](07-supply-chain-slsa-sbom-attestations.md)

docs/01-public-oss-free.md

@@ -5,6 +5,12 @@ for free**, including features that are paid on private repositories. This is th
 tier the NDDev estate targets for open-source work, and it is where the library
 delivers its full value.
 
+> **One documented exception: GitHub Code Quality is not free on public repos.**
+> Unlike CodeQL and everything else in the table below, it is billed per active
+> committer regardless of visibility. Being public only makes its Actions minutes
+> free. Keep it out of this tier — see
+> [16 Code Quality tier](16-code-quality.md).
+
 ## What public OSS gets free
 
 | Capability | Free on public? | Delivered by |
@@ -19,6 +25,7 @@ delivers its full value.
 | GitHub Pages | ✅ | [10 Deployments & environments](10-deployments-environments.md) |
 | Repository rulesets | ✅ | [08 Governance & rulesets](08-governance-rulesets.md) |
 | harden-runner egress control | ✅ | explicit public/GHAS workflows |
+| GitHub Code Quality | ❌ paid per active committer even on public | [16 Code Quality tier](16-code-quality.md) |
 
 > Standard GitHub-hosted runners are free with unlimited minutes on public
 > repositories. Larger, GPU, and macOS-XL runners are billable **even for

docs/02-private-free.md

@@ -19,6 +19,13 @@ them in the private-free tier:
 | `step-security/harden-runner` | Paid on private repos | use a private-free workflow with no action reference |
 | SARIF upload to code scanning | Requires code scanning (paid) | use the no-SARIF workflow variant |
 | GitHub Artifact Attestations | Require GitHub Enterprise Cloud on private/internal (a plan gate — GHAS does not unlock it) | use `release-supply-chain-free.yml` (below) |
+| GitHub Code Quality | Billed per active committer at **any** visibility, on a licence GHAS does not include | [16 Code Quality tier](16-code-quality.md) |
+
+> Code Quality is the one exclusion here that publishing the repository does
+> **not** solve: it is paid on public repos too. Keeping this tier free means
+> leaving the org-level **Repository access** control off this repository — the
+> free maintainability substitutes are listed in
+> [16 Code Quality tier](16-code-quality.md#what-the-free-tiers-do-instead).
 
 ## The zero-cost private stack
 

docs/03-private-paid-ghas.md

@@ -35,6 +35,14 @@ turning it on for private repos, where it is billed per active committer.
 > `release-supply-chain-free.yml` instead
 > (see [07 Supply chain](07-supply-chain-slsa-sbom-attestations.md)).
 
+> **Also not unlocked by GHAS:** GitHub Code Quality is a **separate licence**,
+> billed per active committer independently of Code Security and Secret
+> Protection. Buying either GHAS product does not include it, and buying Code
+> Quality does not give you CodeQL *security* scanning on a private repo. Both
+> drive CodeQL, so holding both means paying two products to run one engine over
+> the same code for different query suites —
+> see [16 Code Quality tier](16-code-quality.md#relationship-to-ghas).
+
 ## Enabling on a private repo
 
 1. Purchase/assign GHAS (Code Security and/or Secret Protection) at the org or