SPEC and waiver hygiene: per-line skip roster, current facts, doc-example and lint fixes - #535
Conversation
…nt-POST set, stale waiver flips The §19 zero-skip roster becomes a per-line enumeration of all 38 live skips across the five runners (each tagged waiver-backed, architectural, or unwaivered), so a PR that closes a gap deletes exactly its own lines. The §19 category table and Appendix D gain the 7 fixture files they omitted. The idempotent-POST enumeration catches up to the current seven (CreateBookmark and PrioritizeAssignment joined). rubric-audit.json: the Go 3C.6 waiver flips to a plain pass (Go auto-paginates with same-origin enforcement), 2D.5/3A.5/ 1B.5 notes are corrected to six-SDK reality, and the audit date is current. AGENTS.md names the four non-generated files under generated/ as explicit exceptions to the never-edit rule.
Six examples still used the stale two-ID calling convention (list(projectId, todolistId)) that predates the single-ID todo surface, and BaseService.kt's KDoc sketched a listAsFlow method that exists nowhere and a requestPaginated call that would not compile (trailing lambda binding to the wrong parameter, stale OperationInfo shape). Same defect class as #511. Every example verified against the real generated signatures; valid examples left untouched.
Two imports referenced only from prose doc comments are dropped (RequestInfo in client.ts, FallbackReason in discovery.ts — both types stay publicly exported via their home modules), and the deliberate control-character guard in discovery.ts gets an explicit no-control-regex disable with its rationale: the WHATWG URL parser silently strips or rewrites those characters, so without the guard a malformed origin spelling would be accepted.
github-actions
Bot
added
typescript
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: fd30d23a76
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
…ice examples as generator output Codex caught a real generator inconsistency behind the 1B.5 overclaim: Ruby's datetime coercion keys on the exact x-go-type time.Time spelling, so MyNote's nullable *time.Time timestamps decode as raw strings (filed as #537; the note now says so). The two BaseService KDoc examples are reframed as illustrative generator output so they cannot be read as a recipe for hand-written wire methods, which AGENTS.md forbids.
|
Bot-review status: Codex reviewed both rounds — its two P2 findings (real generator inconsistency → #537; example framing) are fixed in 8f9fc21, threads resolved with evidence. Copilot errored on the initial review and was re-requested once per the standing flaky-Copilot convention; merging on Codex + green CI. |
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 8f9fc21585
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| * } | ||
| * OperationInfo("Todos", "ListTodos", "todo", false, resourceId = todolistId), | ||
| * null, | ||
| * { httpGet("/todolists/$todolistId/todos.json") }, |
There was a problem hiding this comment.
Because this block is now presented as the shape the generator emits, its httpGet call must pass operationName = info.operation, as the actual generated todos.kt does. Without it, BasecampHttpClient receives the default null, skips the Metadata.operations lookup, and therefore does not apply ListTodos's per-operation retry status set or attempt ceiling to the initial page; the future streaming example repeats the same omission.
AGENTS.md reference: AGENTS.md:L3-L6
Useful? React with 👍 / 👎.
Governance docs had drifted from the code across three fronts. This PR trues them up so later work (conformance-closure PRs in flight) can delete exactly its own roster lines instead of rebasing a prose paragraph.
SPEC §19 + Appendix D
link-headerskip that lives outsideKOTLIN_SKIPS— found by adversarial review running the Kotlin runner: 9 live skips, not the 8 in its skip map).downloads,network-retry,uploads_download,todos_write,cards_write,schedule_entries_write,live-my-surface(the last documented as opt-in viaBASECAMP_LIVE, owned by CONTRIBUTING.md's live-canary machinery).conformancegate line adds the python runner, whichmake conformancehas run all along.behavior-model.jsonidempotent: truewithopenapi.jsonmethods): CompleteTodo, CreateBookmark, EnableCardColumnOnHold, PauseQuestion, PrioritizeAssignment, Subscribe, SubscribeToCardColumn. The on_retry pseudocode note now says all six SDKs ship the (failed, upcoming) pair (true since Swift retry lifecycle: SPEC-correct onRetry numbering, re-auth on every retry path, no events from catch #517).rubric-audit.json
AGENTS.md
The "NEVER edit
*/generated/" rule now names its four real exceptions (_base.py,_async_base.py,base_service.rb, and Python's empty package-root__init__.py) — the exact confusion behind #518's refuted review finding. Verified against both generators: none of the four is emitted;generated/services/__init__.pyis.Source fixes riding along
list(projectId, todolistId)convention;BaseService.kt's KDoc sketched a nonexistentlistAsFlowand arequestPaginatedcall that could not compile. Valid examples untouched.discovery.tsgets an explicitno-control-regexdisable with rationale (WHATWG URL silently strips/rewrites those characters).Verification: TS lint (0 warnings), typecheck, build, tests green; Kotlin
compileKotlinJvmgreen; edited KDoc examples manually re-verified against declarations (KDoc isn't compiled). Adversarial review (4 lenses) ran over the diff; its 5 findings (2 P1) are incorporated above.Summary by cubic
Aligns SPEC, rubric, and governance docs with current SDK behavior and runner output. Makes future conformance-closure PRs remove exact skip lines instead of editing prose.
Refactors
conformancegate.rubric-audit.json: flipped Go3C.6to a plain pass; corrected notes for2D.5,3A.5,1B.5(Ruby nullable*time.Timetimestamps currently pass through as strings; tracked in Ruby generator: datetime coercion keys on the exact x-go-type time.Time spelling, missing nullable *time.Time timestamps #537); updated the audit date.AGENTS.md: documented the four non-generated exceptions undergenerated/.Bug Fixes
BaseService.ktKDoc examples as illustrative generator output and corrected pagination examples).no-control-regexdisable with rationale intypescript/src/oauth/discovery.ts.Written for commit 8f9fc21. Summary will update on new commits.