Skip to content

docs: api-coverage.md omits shipped routes and needs a re-score pass #109

Description

@Adron

Split out of the 2026-09-17 doc sync (PR #108), which corrected work-consolidation.md but deliberately left this file alone.

The gap

docs/api-coverage.md omits rows entirely for routes the client now builds and ships:

Route Shipped in
DELETE /api/user/identities PR #93 (#47)
POST /api/user/identities/verify PR #93 (#47)
GET /api/auth/github/status PR #93 (#47)
GET /api/github/orgs PR #93 (#47)
GET/PUT/DELETE /api/user/app-settings/{appKey} PRs #25/#30, corrected #102 (#56)
GET /api/user/app-settings/{appKey}/bootstrap same
GET/POST /api/user/app-settings/{appKey}/devices same
PATCH/DELETE …/devices/{deviceId} same
GET/PUT …/devices/{deviceId}/settings same, and PR #107 (#104)
GET/POST/PUT/DELETE /api/lists/{id}/views + fork PR #105 (#81)

Some of these have been shipped for weeks. A coverage matrix that does not list a route the client calls is worse than one that lists it as unbuilt — it reads as "not in the API" rather than "not scored".

Why it was not fixed in passing

The file maintains arithmetic invariants: per-section subtotals and a grand total, both stated in prose and already corrected once for an off-by-thirty slip (footnote 14, and the 2026-09-05 entry). Adding rows without recomputing those makes the document internally inconsistent, which is a worse failure than the omission.

It also has a maintenance rule governing when Implemented / Tested may flip — a tested App-layer view model has to drive the row end-to-end. Several of the routes above now qualify, and several do not, and deciding that per row is the actual work.

Also worth re-scoring while in there

The 2026-09-14 pass explicitly did not re-score Implemented/Tested — it only derived the Auth column from the live spec. Since then PRs #86#107 shipped a great deal, so the scored state is stale in both directions: rows marked ☐ that now have end-to-end tests, and rows whose method or path changed under them (the list-schema family in #85, the notification routes in #95).

Acceptance

  • Every route the client builds has a row.
  • Section subtotals and the grand total are recomputed from the rows themselves, not carried forward.
  • Implemented/Tested re-scored under the file's existing rule, with the wave's PRs cited per flipped row.
  • The Auth column stays derived from x-auth-type, and any row whose auth annotation was corrected this wave (/api/user/identities → Bearer, PR feat(settings): the Integrations surface — and three live identity defects underneath it (G33) #93) reflects it.

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    documentationImprovements or additions to documentation

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions