Record dock tool create contract change in api-gaps registry

[jeremy]

Registers the BC4→BC5 dock tool creation contract change (clone → create-by-type) in the api-gaps registry, following the memories-emptied-regression precedent for live contract regressions, and records it as the third cross-team contract decision in COORDINATION.md.

Summary

• New entry spec/api-gaps/dock-tool-create-contract.md: four required source_recording_id on POST /buckets/{bucket_id}/dock/tools.json; BC5 (master) creates by tool_type and 404s the documented clone shape (surfaced live as tools create returns a 404 instead of creating a new tool in the project basecamp-cli#471).
• Compatibility posture is settled by release — BC5 replaced BC4 in production, so there is no live BC4 backend to shim. four survives as the wire-format reference (compatibility.bc3-four) for BC4-era clients; the live-world impact is BC4-era clients on the documented clone contract failing against production.
• The precise gap record: a hybrid wire body (source_recording_id + tool_type + title) is structurally accepted by both contract snapshots, but the SDK CreateTool signature (Update dock tool creation to current bucket-scoped API #327) cannot emit it; the route exists on both (resource :dock { resources :tools } under resources :buckets on four and master), so the divergence is body-level only.
• COORDINATION.md §Contract decisions gains item 3 (settled by release; doc tail bc3#12364).
• Status is absorbed-in-sdk with smithy_refs: [CreateTool] — Update dock tool creation to current bucket-scoped API #327 merged 2026-07-22. The only remaining tail is the upstream doc rewrite (bc3#12364).

Context in basecamp/basecamp-cli#471.

Verification

• make validate-api-gaps — clean (16 entries + allowlist).

[github-actions]

Spec Change Impact

• Operations Added: None

• Operations Modified: DockToolCreateContract

• Operations Removed: None

• Types/Resources Added: None

• Types/Resources Modified: None

• Types/Resources Removed: None

• SDKs Needing Regeneration: All

• Breaking Change: No

Checklist of SDKs needing updates:

• Go
• TypeScript
• Ruby
• Kotlin
• Swift

[Copilot]

Pull request overview

Registers the BC4→BC5 dock tool creation contract flip (clone-by-source_recording_id → create-by-tool_type) in the spec/api-gaps/ registry so the cross-version incompatibility is tracked through the “detect → address → absorb” lifecycle.

Changes:

• Added a new api-gap entry documenting the BC4 vs BC5 request-body divergence for POST /:account_id/buckets/:bucket_id/dock/tools.json.
• Updated the api-gaps registry index to include the new entry as partial-coverage.

Tip

If you aren't ready for review, convert to a draft PR.
Click "Convert to draft" or run gh pr ready --undo.
Click "Ready for review" or run gh pr ready to reengage.

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated no comments.

File	Description
spec/api-gaps/README.md	Adds the new gap to the registry table with partial-coverage status.
spec/api-gaps/dock-tool-create-contract.md	New gap entry documenting the BC4↔BC5 dock tool create contract change and SDK compatibility implications.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 53abf5f416

ℹ️ 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".

[cubic-dev-ai]

All reported issues were addressed across 2 files

<sub>Reply with feedback, questions, or to request a fix.

Re-trigger cubic</sub>

[Copilot]

Pull request overview

Copilot reviewed 2 out of 2 changed files in this pull request and generated 1 comment.

[Copilot]

Pull request overview

Copilot reviewed 2 out of 2 changed files in this pull request and generated no new comments.

[Copilot]

Pull request overview

Copilot reviewed 2 out of 2 changed files in this pull request and generated no new comments.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: ccaafd65af

ℹ️ 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".

[Copilot]

Pull request overview

Copilot reviewed 3 out of 3 changed files in this pull request and generated no new comments.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 07799e109e

ℹ️ 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".

[Copilot]

Pull request overview

Copilot reviewed 3 out of 3 changed files in this pull request and generated 1 comment.

[Copilot]

Pull request overview

Copilot reviewed 3 out of 3 changed files in this pull request and generated 1 comment.

[Copilot]

Pull request overview

Copilot reviewed 3 out of 3 changed files in this pull request and generated no new comments.