From 7bde2ae7671f304e2cf54dde4579eee0e5aea355 Mon Sep 17 00:00:00 2001 From: Mike Stankavich Date: Sat, 30 May 2026 15:34:21 -0500 Subject: [PATCH 1/4] =?UTF-8?q?docs(spec):=20TRA-892=20docs-hygiene=20bund?= =?UTF-8?q?le=20=E2=80=94=203=20one-line=20fixes=20+=20contact.url=20defer?= =?UTF-8?q?ral=20grooming?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-Authored-By: Claude Opus 4.8 (1M context) --- ...5-30-tra-892-docs-hygiene-bundle-design.md | 78 +++++++++++++++++++ 1 file changed, 78 insertions(+) create mode 100644 superpowers/specs/2026-05-30-tra-892-docs-hygiene-bundle-design.md diff --git a/superpowers/specs/2026-05-30-tra-892-docs-hygiene-bundle-design.md b/superpowers/specs/2026-05-30-tra-892-docs-hygiene-bundle-design.md new file mode 100644 index 0000000..db9c0b6 --- /dev/null +++ b/superpowers/specs/2026-05-30-tra-892-docs-hygiene-bundle-design.md @@ -0,0 +1,78 @@ +# TRA-892 — Docs-hygiene bundle: 3 one-line API-docs fixes + groom the `contact.url` deferral + +**Date:** 2026-05-30 +**Ticket:** TRA-892 +**Type:** Docs-only PR (4 wording/backlog edits) + one Linear grooming comment + +## Problem + +The 2.6.1 black-box fleet (runs bb-261/262/263, svc `v1.1.1-165-g8ca09556`) surfaced four +documentation-hygiene items. **None gate the prod launch** — zero service/contract defects +were found. Each is a one-line wording correction or backlog grooming, safe to land any time. + +## Prerequisite verification (done before writing) + +Verified each claim against the live preview (`app.preview.trakrf.id`) and the current docs: + +| Claim to verify | Finding | Consequence | +| ------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------ | +| `AssetView` has no `location_id` field | Confirmed — current location is exposed only on `GET /reports/asset-locations` and `GET /assets/{id}/history` (`tracking:read`); `resource-identifiers.md` already states this correctly | Fix only the BB onboarding-wrapper shorthand (item 1) | +| Empty `PATCH {}` still advances `updated_at` | Confirmed by ticket's live evidence (200, `updated_at` drift); `quickstart.mdx:167` already documents the always-advance behavior in full | Add a one-line qualifier at the compressed mention `quickstart.mdx:145-146` (item 2) | +| Docs-origin `/health.json` lacks API/spec version | Confirmed — docs origin returns only the docs build stamp; `app` origin `/health.json` carries `version` + `spec_refreshed_at` | Point BB's version check at the app origin (item 3) | +| `info.contact.url` restored by design | Confirmed — live spec serves `info.contact.url: https://trakrf.id` (Stripe pattern: marketing root + `support@trakrf.id`), restored via platform TRA-882 (PR #440) | The `BACKLOG.md` "restore the URL when a helpdesk lands" deferral is now obsolete (item 4) | + +## Scope — four edits + +### Item 1 — `tests/blackbox/BB_PRE_KEY.md` (fixture-data section) + +`:47` currently reads as if `location_id` is a field on the asset object. Reword to state the +current location is resolved from scan history via the asset-locations report / history +endpoints, **not a field on the asset object**. Also reconcile `:49`'s parallel +"materialized `location_id` on every asset" phrasing so the doc stays internally consistent +after the item-1 fix (otherwise the two lines contradict). Both are minimal; the determinism +promise (every fixture asset has a resolvable current location) is preserved, only the +"it's a field" implication is removed. + +### Item 2 — `docs/api/quickstart.mdx` (§ minimal PATCH) + +`:145-146` compresses "`{}` is a documented no-op" too far. Reword to "a documented no-op +**against settable fields** (it still advances `updated_at`)". Chosen over "link to the design +note" because the same code block's prose at `:167` already deep-links +`design-notes#updated_at-is-an-optimistic-concurrency-token-on-patch`; the inline qualifier +closes the gap where a reader stops at the comment. + +### Item 3 — `tests/blackbox/BB.md` (context-block version check) + +`:209` tells the BB harness to fetch the spec/build version from `$API_TEST_DOCS_URL/health.json`, +which carries only the docs build stamp. Repoint it at `$API_TEST_APP_URL/health.json` (the +authoritative `version` + `spec_refreshed_at` surface) and note that the docs origin only +carries the docs build stamp, so the cohort stops filing "version missing" where-to-look nits. +Chosen over surfacing the API/spec version on the docs host — that is an infra/build change +outside doc-hygiene scope, and the ticket explicitly offers the BB.md correction as the +alternative. + +### Item 4 — groom the `contact.url` deferral + +TRA-743 (which removed `info.contact.url`) is **already Done**; the URL has since been restored +by design (TRA-882). So "close as resolved" reduces to grooming the residue: + +- **Docs:** remove the now-stale `tests/blackbox/BACKLOG.md:47` row ("Restore `info.contact.url` + … when a helpdesk lands"). The deferred work is done — keeping the row would advertise a + removal that no longer reflects reality. +- **Linear:** add a comment to TRA-743 recording the course reversal (URL restored by design, + Stripe pattern, `https://trakrf.id`) and that the BACKLOG deferral has been removed as obsolete. + No state change — the ticket is already Done. + +## Out of scope + +- Surfacing API/spec version on the docs host (item 3's other option) — infra/build change. +- Any platform/spec change — `info.contact.url` is already correct on the live spec; no paired + platform edit is needed for any item. +- Touching `tests/blackbox/.env.local` — already re-keyed this session, unrelated. + +## Verification + +- `pnpm build` and `pnpm lint` pass (Redocusaurus fetches the live spec at build time; no spec + change here, so the build is unaffected). +- The three doc edits are wording-only; the BACKLOG edit removes one table row. +- TRA-743 grooming comment posted. From 0608f630b85b60d02ed5bced8bef02e29f58c4b8 Mon Sep 17 00:00:00 2001 From: Mike Stankavich Date: Sat, 30 May 2026 15:34:21 -0500 Subject: [PATCH 2/4] docs(plan): TRA-892 docs-hygiene bundle implementation plan Co-Authored-By: Claude Opus 4.8 (1M context) --- .../2026-05-30-tra-892-docs-hygiene-bundle.md | 142 ++++++++++++++++++ 1 file changed, 142 insertions(+) create mode 100644 superpowers/plans/2026-05-30-tra-892-docs-hygiene-bundle.md diff --git a/superpowers/plans/2026-05-30-tra-892-docs-hygiene-bundle.md b/superpowers/plans/2026-05-30-tra-892-docs-hygiene-bundle.md new file mode 100644 index 0000000..14fa764 --- /dev/null +++ b/superpowers/plans/2026-05-30-tra-892-docs-hygiene-bundle.md @@ -0,0 +1,142 @@ +# TRA-892 Docs-Hygiene Bundle Implementation Plan + +> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking. + +**Goal:** Land four BB-fleet doc-hygiene corrections (3 wording one-liners + remove one stale backlog row) and groom the `contact.url` deferral in Linear. + +**Architecture:** Docs-only edits in `trakrf/docs`. No spec/platform change — `info.contact.url` is already correct live. Verification is `pnpm build` + `pnpm lint` (no test suite for prose) plus targeted greps confirming each before/after. + +**Tech Stack:** Docusaurus / Redocusaurus, pnpm, Markdown/MDX. Linear MCP for the grooming comment. + +--- + +## File Structure + +- Modify: `tests/blackbox/BB_PRE_KEY.md` — fixture-data wording (item 1) +- Modify: `docs/api/quickstart.mdx` — minimal-PATCH comment (item 2) +- Modify: `tests/blackbox/BB.md` — context-block version check (item 3) +- Modify: `tests/blackbox/BACKLOG.md` — remove obsolete deferral row (item 4a) +- Linear: comment on TRA-743 (item 4b) + +--- + +### Task 1: `BB_PRE_KEY.md` — location is a scan projection, not an asset field + +**Files:** + +- Modify: `tests/blackbox/BB_PRE_KEY.md:47` and `:49` + +- [ ] **Step 1: Edit line 47.** Replace: + +``` +- Every asset has `location_id` resolved from scan history — no asset on this fixture reads as `location_id: null`. +``` + +with: + +``` +- Every asset has a resolvable current location, but location is **not** a field on the asset object — it is resolved from scan history via the asset-locations report (`GET /api/v1/reports/asset-locations`) and per-asset history (`GET /api/v1/assets/{asset_id}/history`), both gated `tracking:read`. No fixture asset reads as location-unknown. +``` + +- [ ] **Step 2: Reconcile line 49** so it does not re-imply a field on the asset. Replace: + +``` +**Scans:** populated. Each org carries ~25 `asset_scans` per asset over a 90-day window (~675 per org), and the materialized `location_id` on every asset reflects the most-recent scan. +``` + +with: + +``` +**Scans:** populated. Each org carries ~25 `asset_scans` per asset over a 90-day window (~675 per org), and the current location reported for every asset (via the scan-data endpoints above) reflects its most-recent scan. +``` + +(Leave the rest of line 49 — the `tracking:read` sentence — unchanged.) + +- [ ] **Step 3: Verify.** Run: `grep -n "location_id\` resolved\|materialized \`location_id\`" tests/blackbox/BB_PRE_KEY.md` + Expected: no matches (both imprecise phrasings gone). + +--- + +### Task 2: `quickstart.mdx` — `{}` no-op qualifier + +**Files:** + +- Modify: `docs/api/quickstart.mdx:146` + +- [ ] **Step 1: Edit line 146.** Replace: + +``` +# nullable field; `{}` is a documented no-op. +``` + +with: + +``` +# nullable field; `{}` is a documented no-op against settable fields (it still advances `updated_at`). +``` + +- [ ] **Step 2: Verify.** Run: `grep -n "documented no-op" docs/api/quickstart.mdx` + Expected: the line now contains "against settable fields (it still advances `updated_at`)". + +--- + +### Task 3: `BB.md` — point version check at the app origin + +**Files:** + +- Modify: `tests/blackbox/BB.md:209` + +- [ ] **Step 1: Edit line 209.** Replace: + +``` +- Spec/build version — fetch `$API_TEST_DOCS_URL/health.json` and record what it returns. If `/health.json` 404s, that's a finding; record what you did get. +``` + +with: + +``` +- Spec/build version — fetch `$API_TEST_APP_URL/health.json` (the app origin carries `version` + `spec_refreshed_at`; the docs origin's `/health.json` carries only the docs build stamp). Record what it returns. If `/health.json` 404s, that's a finding; record what you did get. +``` + +- [ ] **Step 2: Verify.** Run: `grep -n "Spec/build version" tests/blackbox/BB.md` + Expected: line now references `$API_TEST_APP_URL/health.json`. + +--- + +### Task 4: `BACKLOG.md` — remove the obsolete `contact.url` deferral row + +**Files:** + +- Modify: `tests/blackbox/BACKLOG.md:47` + +- [ ] **Step 1: Delete the entire table row** beginning `| Restore \`info.contact.url\` on OpenAPI spec` (line 47). Remove the whole line; leave the table header (41-42) and the three preceding rows (43-46) intact. + +- [ ] **Step 2: Verify.** Run: `grep -n "info.contact.url" tests/blackbox/BACKLOG.md` + Expected: no matches. Run: `grep -c "^| " tests/blackbox/BACKLOG.md` and confirm the deferred-work table dropped by exactly one row. + +--- + +### Task 5: Build + lint + +- [ ] **Step 1:** Run: `pnpm build` Expected: success (no spec change; Redocusaurus fetches live spec). +- [ ] **Step 2:** Run: `pnpm lint` Expected: pass. + +--- + +### Task 6: Commit + groom Linear + +- [ ] **Step 1: Commit** the four file edits: + +```bash +git add tests/blackbox/BB_PRE_KEY.md docs/api/quickstart.mdx tests/blackbox/BB.md tests/blackbox/BACKLOG.md +git commit -m "docs(api): TRA-892 BB-fleet hygiene — location-projection wording, PATCH no-op qualifier, BB version-check origin, retire contact.url deferral" +``` + +- [ ] **Step 2: Groom TRA-743 (already Done).** Add a Linear comment recording that `info.contact.url` was restored by design (TRA-882, Stripe pattern `https://trakrf.id`), so the `BACKLOG.md` "restore when a helpdesk lands" deferral has been removed as obsolete. No state change. + +--- + +### Task 7: Push + PR (hold for approval before merge) + +- [ ] **Step 1:** Push branch `docs/tra-892-docs-bundle`. +- [ ] **Step 2:** Open PR with the spec/plan link and the four-item summary. **Do not merge** — hold for user approval. From 11a449fa0cff2c80f3507a46d500d023e06d085c Mon Sep 17 00:00:00 2001 From: Mike Stankavich Date: Sat, 30 May 2026 15:34:21 -0500 Subject: [PATCH 3/4] =?UTF-8?q?docs(api):=20TRA-892=20BB-fleet=20hygiene?= =?UTF-8?q?=20=E2=80=94=20location-projection=20wording,=20PATCH=20no-op?= =?UTF-8?q?=20qualifier,=20BB=20version-check=20origin,=20retire=20contact?= =?UTF-8?q?.url=20deferral?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Surfaced by the 2.6.1 black-box fleet (bb-261/262/263, svc v1.1.1-165-g8ca09556); none gate launch. 1. BB_PRE_KEY.md: clarify current location is a scan projection (asset-locations report / history endpoints), not a field on the asset object; reconcile the parallel 'materialized location_id' line. 2. quickstart.mdx: empty PATCH {} is a no-op only against settable fields — it still advances updated_at. 3. BB.md: fetch spec/build version from the app origin /health.json (carries version + spec_refreshed_at); docs origin has only the docs build stamp. 4. BACKLOG.md: retire the 'restore info.contact.url' deferral — restored by design (Stripe pattern, https://trakrf.id) via platform TRA-882. Co-Authored-By: Claude Opus 4.8 (1M context) --- docs/api/quickstart.mdx | 2 +- tests/blackbox/BACKLOG.md | 13 ++++++------- tests/blackbox/BB.md | 2 +- tests/blackbox/BB_PRE_KEY.md | 4 ++-- 4 files changed, 10 insertions(+), 11 deletions(-) diff --git a/docs/api/quickstart.mdx b/docs/api/quickstart.mdx index ce55c0a..5f58aa9 100644 --- a/docs/api/quickstart.mdx +++ b/docs/api/quickstart.mdx @@ -143,7 +143,7 @@ curl -H "Authorization: Bearer $TRAKRF_ACCESS_TOKEN" \ # Update — partial merge-patch per RFC 7396. Only fields in the body are # changed; omitted fields are left unchanged. Send `null` to clear a -# nullable field; `{}` is a documented no-op. +# nullable field; `{}` is a documented no-op against settable fields (it still advances `updated_at`). curl -X PATCH "$BASE_URL/api/v1/assets/$ASSET_ID" \ -H "Authorization: Bearer $TRAKRF_ACCESS_TOKEN" \ -H "Content-Type: application/merge-patch+json" \ diff --git a/tests/blackbox/BACKLOG.md b/tests/blackbox/BACKLOG.md index 05afcc3..21cbf30 100644 --- a/tests/blackbox/BACKLOG.md +++ b/tests/blackbox/BACKLOG.md @@ -38,10 +38,9 @@ Test-org artifact states that BB cycles will observe but should not flag as serv Items with real fixes that cost-benefit deliberately deferred. Each entry has an explicit trigger condition; the registry is groomed at post-launch milestones and whenever a trigger fires. -| Work | Origin | Trigger to revisit | -| ------------------------------------------------------------------------------------------ | ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| Bigint storage migration | TRA-720 | When cloud catches up to preview schema state AND customer volume hits the int32 ceiling (or enterprise data-residency requirements force it sooner). Retires the wire-vs-runtime int64 soft contract entirely; path-param maximum constraint (TRA-726) removed in same PR. | -| OpenAPI 3.1 migration | BB37 F5 context | When the generator ecosystem stabilizes 3.1 support across all targets we care about. Fixes `datamodel-codegen` nullable handling without per-generator workarounds; would let us drop the nullable design note from `/docs/api/design-notes`. | -| Path-param maximum constraint removal | BB37 F2 / TRA-726 | Same trigger as bigint storage migration (TRA-720). Documented in TRA-726 acceptance criteria. | -| Add `x-extensible-enum: true` annotations to `tag_type` discriminator and `OrgView.scopes` | BB39 F7 | Same trigger as the OpenAPI 3.1 migration above. 3.1's `const` keyword and improved discriminator support let us express closed/open splits cleanly; a standalone annotation now would carry forward, but the 3.1 migration retires the question. | -| Restore `info.contact.url` on OpenAPI spec | TRA-743 | When a helpdesk lands (Zendesk, Help Scout, Intercom, similar) or a marketing `/contact` page with topic routing ships. Add the URL back targeting that surface — GitHub pattern is a deep link with topic-routing parameter (`https://support.example.com/contact?tags=api`); Stripe pattern is a marketing root plus a dedicated team email. `docs.trakrf.id` was rejected as the target (env-leak from preview); `app.trakrf.id/api` was rejected (404/SPA shell, the bug BB42 surfaced). Current state is `info.contact.{name,email}` only — renders fine in Redoc and Swagger UI; adding URL later is non-breaking by OpenAPI 3.0 design. | +| Work | Origin | Trigger to revisit | +| ------------------------------------------------------------------------------------------ | ----------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Bigint storage migration | TRA-720 | When cloud catches up to preview schema state AND customer volume hits the int32 ceiling (or enterprise data-residency requirements force it sooner). Retires the wire-vs-runtime int64 soft contract entirely; path-param maximum constraint (TRA-726) removed in same PR. | +| OpenAPI 3.1 migration | BB37 F5 context | When the generator ecosystem stabilizes 3.1 support across all targets we care about. Fixes `datamodel-codegen` nullable handling without per-generator workarounds; would let us drop the nullable design note from `/docs/api/design-notes`. | +| Path-param maximum constraint removal | BB37 F2 / TRA-726 | Same trigger as bigint storage migration (TRA-720). Documented in TRA-726 acceptance criteria. | +| Add `x-extensible-enum: true` annotations to `tag_type` discriminator and `OrgView.scopes` | BB39 F7 | Same trigger as the OpenAPI 3.1 migration above. 3.1's `const` keyword and improved discriminator support let us express closed/open splits cleanly; a standalone annotation now would carry forward, but the 3.1 migration retires the question. | diff --git a/tests/blackbox/BB.md b/tests/blackbox/BB.md index 072a6fe..f87839c 100644 --- a/tests/blackbox/BB.md +++ b/tests/blackbox/BB.md @@ -206,7 +206,7 @@ Begin FINDINGS.md with a context block recording: - Environment URL (`API_TEST_APP_URL` value) - Docs URL (`API_TEST_DOCS_URL` value) - Track (mint-key or pre-key) and — for pre-key — the value of `$BB_ORG` and `$BB_ORG_ID` -- Spec/build version — fetch `$API_TEST_DOCS_URL/health.json` and record what it returns. If `/health.json` 404s, that's a finding; record what you did get. +- Spec/build version — fetch `$API_TEST_APP_URL/health.json` (the app origin carries `version` + `spec_refreshed_at`; the docs origin's `/health.json` carries only the docs build stamp). Record what it returns. If `/health.json` 404s, that's a finding; record what you did get. - HTTP client(s) used in the exploratory pass (curl, Python `requests`, Node `fetch`, generated TypeScript client, etc.) - Codegen tool(s) and version(s) used in step 10 — list each separately - Date and time of the run (UTC) diff --git a/tests/blackbox/BB_PRE_KEY.md b/tests/blackbox/BB_PRE_KEY.md index 4674981..1cf888d 100644 --- a/tests/blackbox/BB_PRE_KEY.md +++ b/tests/blackbox/BB_PRE_KEY.md @@ -44,9 +44,9 @@ BB1, BB2, and BB3 carry identical, deterministic data. You can assert against li **Assets — 27 per org:** - 11 OC-origin (`ASSET-0001` … `ASSET-0011`), 9 CD-origin under the `ASSET-NNNN` namespace above the OC ceiling (`ASSET-0012` … `ASSET-0020`), and 7 CD-origin under the `CD-ASSET-NNNN` namespace (`CD-ASSET-0001` … `CD-ASSET-0007` — the rows that would have collided with OC). 11 + 9 + 7 = 27. -- Every asset has `location_id` resolved from scan history — no asset on this fixture reads as `location_id: null`. +- Every asset has a resolvable current location, but location is **not** a field on the asset object — it is resolved from scan history via the asset-locations report (`GET /api/v1/reports/asset-locations`) and per-asset history (`GET /api/v1/assets/{asset_id}/history`), both gated `tracking:read`. No fixture asset reads as location-unknown. -**Scans:** populated. Each org carries ~25 `asset_scans` per asset over a 90-day window (~675 per org), and the materialized `location_id` on every asset reflects the most-recent scan. `tracking:read` coverage is in-scope — exercise both `/api/v1/assets/{asset_id}/history` and `/api/v1/reports/asset-locations` with literal-value assertions. +**Scans:** populated. Each org carries ~25 `asset_scans` per asset over a 90-day window (~675 per org), and the current location reported for every asset (via the scan-data endpoints above) reflects its most-recent scan. `tracking:read` coverage is in-scope — exercise both `/api/v1/assets/{asset_id}/history` and `/api/v1/reports/asset-locations` with literal-value assertions. **Tags:** not pre-seeded on fixture rows. Tags **are** part of the v1 public-API surface, though — the `POST`/`DELETE …/tags` subresources on both assets and locations, gated by the parent resource's `:write` scope. Don't skip the tags surface just because the fixture ships no tag rows: exercise it by creating your own (e.g. `POST /api/v1/assets/{asset_id}/tags`) and round-tripping. From 6838343816a54caccaa86c1e705af219755eafb4 Mon Sep 17 00:00:00 2001 From: Mike Stankavich Date: Sat, 30 May 2026 15:43:33 -0500 Subject: [PATCH 4/4] =?UTF-8?q?docs(bb):=20TRA-892=20=E2=80=94=20retire=20?= =?UTF-8?q?bigint-coupled=20deferrals=20from=20BB=20BACKLOG?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The all-bigint post-720 schema has landed (TRA-720 + the TRA-810 GKE migration); preview/prod run on it. Both deferred-registry rows whose trigger was 'bigint migration lands' are now resolved: - 'Bigint storage migration' (TRA-720) — done. - 'Path-param maximum constraint removal' (TRA-726 F2) — verified done in the live spec: surrogate path params now declare format: int64 + maximum: 9007199254740991 (no 2147483647 cap remains on any id). Co-Authored-By: Claude Opus 4.8 (1M context) --- tests/blackbox/BACKLOG.md | 10 ++++------ 1 file changed, 4 insertions(+), 6 deletions(-) diff --git a/tests/blackbox/BACKLOG.md b/tests/blackbox/BACKLOG.md index 21cbf30..505c9de 100644 --- a/tests/blackbox/BACKLOG.md +++ b/tests/blackbox/BACKLOG.md @@ -38,9 +38,7 @@ Test-org artifact states that BB cycles will observe but should not flag as serv Items with real fixes that cost-benefit deliberately deferred. Each entry has an explicit trigger condition; the registry is groomed at post-launch milestones and whenever a trigger fires. -| Work | Origin | Trigger to revisit | -| ------------------------------------------------------------------------------------------ | ----------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| Bigint storage migration | TRA-720 | When cloud catches up to preview schema state AND customer volume hits the int32 ceiling (or enterprise data-residency requirements force it sooner). Retires the wire-vs-runtime int64 soft contract entirely; path-param maximum constraint (TRA-726) removed in same PR. | -| OpenAPI 3.1 migration | BB37 F5 context | When the generator ecosystem stabilizes 3.1 support across all targets we care about. Fixes `datamodel-codegen` nullable handling without per-generator workarounds; would let us drop the nullable design note from `/docs/api/design-notes`. | -| Path-param maximum constraint removal | BB37 F2 / TRA-726 | Same trigger as bigint storage migration (TRA-720). Documented in TRA-726 acceptance criteria. | -| Add `x-extensible-enum: true` annotations to `tag_type` discriminator and `OrgView.scopes` | BB39 F7 | Same trigger as the OpenAPI 3.1 migration above. 3.1's `const` keyword and improved discriminator support let us express closed/open splits cleanly; a standalone annotation now would carry forward, but the 3.1 migration retires the question. | +| Work | Origin | Trigger to revisit | +| ------------------------------------------------------------------------------------------ | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| OpenAPI 3.1 migration | BB37 F5 context | When the generator ecosystem stabilizes 3.1 support across all targets we care about. Fixes `datamodel-codegen` nullable handling without per-generator workarounds; would let us drop the nullable design note from `/docs/api/design-notes`. | +| Add `x-extensible-enum: true` annotations to `tag_type` discriminator and `OrgView.scopes` | BB39 F7 | Same trigger as the OpenAPI 3.1 migration above. 3.1's `const` keyword and improved discriminator support let us express closed/open splits cleanly; a standalone annotation now would carry forward, but the 3.1 migration retires the question. |