Define V1 Write Contract and Mutation Checklist

[deverman]

Summary

Define the v1 write contract for FocusRelay before implementing mutation tools.

This is the write-side equivalent of the existing read/query contract. It should remove ambiguity for future implementation and keep the project aligned with documented Omni Automation APIs.

Scope

Create new documentation that locks:

• allowed documented Omni Automation write APIs for tasks and projects
• v1 mutation surface
• homogeneous bulk-only rule for v1
• ID-only mutation targeting in v1
• previewOnly, verify, and returnFields behavior
• validation and failure semantics
• clear separation between patch, lifecycle, and move operations

Locked V1 Surface

• update_tasks
• set_tasks_completion
• move_tasks
• update_projects
• set_projects_status
• set_projects_completion
• move_projects

Locked Defaults

• homogeneous bulk only in v1
• ID-only mutation targeting
• update_* is for field patches only
• set_*_completion owns lifecycle transitions
• move_* owns structural moves
• mixed batch_mutate_tasks is deferred

Acceptance Criteria

• add a write contract doc parallel to the existing read contract
• add a mutation checklist parallel to the existing query checklist
• document only officially documented Omni Automation write APIs
• explicitly define what is out of scope for v1
• no write issue after this one should require API-shape decisions

Notes

This issue should cite official Omni Automation docs for:

• task markComplete() / markIncomplete()
• project markComplete() / markIncomplete()
• project status
• database moveTasks() / moveSections() / deleteObject()

[deverman]

Execution/merge-order note: issue #28 is intentionally independent from PR #37 / issue #27. This issue is scoped to write-contract and mutation-checklist docs and should stay based on master. It does not need to wait for #27 to merge. Prefer merging #27 when its review is complete, but do not stack #28 on top of it unless a real code dependency appears.

[deverman]

Execution/merge-order update: issue #28 now depends on PR #39 merging first. The docs branch remains intentionally docs-only, but the repository needed a separate dependency update to swift-sdk 0.12.0 so swift test is green again on Swift 6.3.1 / Xcode 26.4.1.

[deverman]

Execution/merge-order update: issue #28 now depends on PR #39 merging first. The docs branch remains intentionally docs-only, but the repository needed a separate dependency update to swift-sdk 0.12.0 so swift test is green again on Swift 6.3.1 / Xcode 26.4.1. After PR #39 merges, PR #38 can merge as the clean write-contract/docs change.