docs(spec): refresh the gen:openapi exemption why with the #5757 measurement (#6949)

The exemption said a stale OpenAPI artifact "fails nothing". True, but an
understatement: #5757's measurement round found staleness is structurally
unreachable on every canonical path, not merely unpunished. Record the two
measured facts so the next reader does not re-file the gate card.

No logic change: one `why` string plus the comment above it.


Claude-Session: https://claude.ai/code/session_01AZgRyPVwi1jLb1mNNuUQ9o

Co-authored-by: Claude <noreply@anthropic.com>

Author: os-project-manager

packages/spec/scripts/check-generated.ts

@@ -238,13 +238,29 @@ const UNGATED_GENERATORS: ReadonlyArray<{ gen: string; why: string }> = [
   // #5744 that names a reconciliation with no second party: the document
   // carries no route section at all — built-in routes are produced at serve
   // time by the package that mounts them (#5588 ruling C, #5078, ADR-0076), so
-  // there is nothing here to compare against a route table. What IS still
-  // ungated is staleness against `src/api`: nothing fails when a contract
-  // schema changes and the artifact is not regenerated. Coherence is covered
-  // (the generator self-checks before writing, #5168) — currency is not.
+  // there is nothing here to compare against a route table. Coherence is
+  // covered (the generator self-checks before writing, #5168); currency this
+  // aggregate still does not verify. #5757 measured what that omission costs
+  // and the answer was nothing — staleness here is unreachable, not merely
+  // unpunished — so "add a gate" was ruled not planned. The `why` carries the
+  // measurement so the next reader does not re-file it.
   {
     gen: 'gen:openapi',
-    why: 'the OpenAPI document is generated but nothing compares its components.schemas against src/api — a stale artifact fails nothing (it IS self-checked for coherence at write time, #5168, and since #5744 it describes no routes to reconcile)',
+    why:
+      'nothing here compares the document\'s components.schemas against src/api — but per the #5757 ' +
+      'measurement a stale artifact is not merely unpunished, it is unreachable on every canonical path. ' +
+      'Staleness cannot outlive one build of this package: `json-schema/**` is a turbo build OUTPUT and is ' +
+      'gitignored, so it is never a task input; `build` declares no `inputs`, so it hashes every git-tracked ' +
+      'file in the package; and everything this generator reads sits in there (the `src/**` closure reached ' +
+      'through `src/api`, these scripts, the manifest). That input surface is a SUBSET of the build task\'s, ' +
+      'so any edit able to make the artifact stale is exactly the edit that busts the cache — and `build` ' +
+      'runs the generator unconditionally (`gen:schema && gen:openapi && tsup`). Deleting the artifact does ' +
+      'not even bust the cache: the next build restores it byte-identically (measured, FULL TURBO). What a ' +
+      'stale copy could mislead is bounded too — the served document holds 0 $refs into components.schemas, ' +
+      'leaving the nine contract schemas an unreferenced island (#6797). It IS self-checked for coherence at ' +
+      'write time (#5168), and since #5744 it describes no routes to reconcile. Gating it would also be ' +
+      'dormant: CI runs this aggregate only as `--reconcile-only` (lint.yml), and a full run sits after ' +
+      '`pnpm build` — green by construction, the #4177/#4232 class.',
   },
   { gen: 'gen:sbom', why: 'the SBOM is a release artifact, regenerated at publish time rather than checked in' },
 ];