[Reconciliation][P2] Document task read-time plan blocking and create-time model selection #335

Parent workstream: #321
Epic: #318

Priority: P2 · Audit findings: JA-03, BILL-04

Outcome and problem

GET /api/tasks?id= returns 402 plan_limit when a single task is outside its owner plan, but the audited GET reference omits 402. This is the runner preflight skip mechanism and differs from a list read. CreateTaskRequest also omits the supported optional model field while update/read schemas include it. This ticket owns the JA-03/BILL-04 overlap so the same documentation change is not tracked twice.

Scope and ownership

• Add the conditional GET-by-id 402 response using the existing PlanLimitError schema.
• Explain single-task runner preflight versus ordinary task listing and that the task owner plan governs.
• Add optional model to the creation contract with actual default/empty-string behavior.
• Preserve verified timezone and Trigger-run linkage contracts; plan values, billing and grandfathering are owned by separate billing work.

Planning is tracked in Mono. Implementation and release PRs belong in the owning repositories under their current branch rules.

Acceptance criteria

• GET reference lists the real 402 envelope and precisely states when it is returned.
• A contract fixture covers an allowed single-task read, a plan-blocked single-task read and a list read.
• A valid create request with model matches the implemented schema and the public example.
• Both publications reflect the correction, and the consolidated epic references this ticket for both JA-03 and BILL-04.

Evidence and existing work

Baseline: October 10, 2026 audit of July 10–October 10 merges. Recheck current source and existing tracker comments before implementation. Source findings do not establish authenticated production behavior.

• Source evidence 1
• Source evidence 2
• Source evidence 3
• Source evidence 4
• Source evidence 5

Related existing work:

• feat(tasks): timezone-aware scheduling — pass timezone to the Trigger.dev schedule (chat#1881 3c) api#780
• feat(plans): three-plan entitlements, 402 plan_limit task gate, Starter checkout (app#2044 row 3) api#877
• docs(tasks): document optional timezone on task create/update (chat#1881 3c) docs#275
• docs(plans): plan entitlements contract: plan fields on credits, 402 plan_limit on tasks, plan on subscription sessions (app#2044 row 2) docs#324
• Paid funnel v2: the ten changes most likely to convert a paid subscription, in order (Starter tier, task-cap gate, in-app upgrade prompts, Stripe-first checkout) app#2044

Continue or reconcile the linked implementation work; this ticket owns the stated audit correction and does not replace the original feature tracker.

Source corrections released — October 12, 2026

Task creation documents optional model selection, and the guard validates both explicit and omitted models. GET-by-ID documents the owner-plan 402 gate separately from task listing. API behavior is unchanged; create/edit/list versus execution permissions remain distinct.

All five approved source PRs are merged: API #1032, Marketing #152, Docs #373, CLI #26, and App #2242. Mono #373 records the five source references at e650245fe3267a08b94abbb75dc30a8a4108c020. The immutable provenance chain is API 0a590490c0e005045e4cbf399fe552dc41e6b9a3 → Marketing 62cc352c4c90d4578bea4352001fc459b7566e1b → Docs fa6dc9e761056066299dde4525552b0d14442f1f. App source is d13bdcb7b112ff0ed8d9d243ae7c6fd56f9a80d4; CLI source is a11bff0a36e339e94ad6921e55d82ec9472d0e35.

Verified publication: API, App and Marketing main checks pass and their canonical Vercel aliases are READY at those actual merge commits. All 231 merged Docs files/navigation match Marketing. Five representative Markdown pages pass on both public hosts; all 12 downloadable split specs on both hosts exactly match source. Canonical Marketing human pages and both LLM catalogs pass. Both human catalog pages show the 1–366 range; the separate playcount maximum remains 31.

Remaining release gates: CLI build/typecheck/77 tests passed, but npm publication failed with HTTP 404; the registry still serves 0.1.15. The release bot bumped source to 0.1.16 without publishing it. A valid NPM_TOKEN replacement and installed-registry-package verification are required; no token value belongs in an issue. Retained-host normal /llms-full.txt still returns cached v0.1.13/--room-id guidance (cf-cache-status: HIT, max-age=86400); a cache-busted read shows the corrected CLI/Context/Sites content. Its human /mcp still returns 405. Docs main's Mintlify deployment succeeds, but these URL/cache problems are not thereby resolved. Mintlify connection/routing repair and host cutover remain explicitly deferred. No hosted Context, media, OAuth/client, or unresolved-feature acceptance is inferred from this source release.

Ticket acceptance update: Closure evidence: existing getTasksHandler.planLimit fixtures cover blocked GET-by-id (402), allowed GET-by-id (200), and list reads (200, without a plan check); the shared published contract checks explicit and omitted model. Both hosts serve the corrected split spec. JA-03 and BILL-04 remain consolidated in this ticket. Billing runtime behavior was not changed.