docs(planner): bring doc.go to the data-structure documentation standard

[bdchatham]

What

Companion to Tide#126 (the /idiomatic expert). This is the pilot output applied to the package the expert reviewed.

internal/planner/doc.go — expanded to the package data-structure documentation standard. Adds the four missing required sections:

• Type Roles — TaskPlan, PlannedTask, the builders, and Executor[T]: who constructs / reads / mutates each, and where it lives (.status vs in-memory).
• Invariants — atomic plan creation, single-patch, optimistic-lock, FailedPhase=="" means retry, nil plan == steady state, terminal-plan cleanup, conditions-always-present. Each tagged with its guarding test or marked documented-but-unguarded.
• Zero-Value & Sentinel Semantics — what nil plan / empty FailedPhase / empty TargetPhase / nil SubmittedAt mean.
• Concurrency & Staleness — the optimistic-lock + single-patch story, now stated at the structure's definition (it previously lived only in CLAUDE.md — this resolves that doc drift).

Existing sections (Purpose, Lifecycle, Condition Ownership, Plan Types, Task Types) are preserved verbatim. gofmt-clean; go vet ./internal/planner passes; go doc ./internal/planner renders.

CLAUDE.md — wired the idiomatic-reviewer subagent into the Subagents list so idiom-conformance review is automatically in the loop here.

Follow-up

The review surfaced three documented-but-unguarded invariants (persist-before-execute ordering, patch-count-per-reconcile, NodeUpdate-failure-stays-Running). Tracked separately — these are test-coverage additions, not part of this docs change.

🤖 Generated with Claude Code

[cursor]

PR Summary

Low Risk
Comments and agent guidance only; no controller, API, or runtime behavior changes.

Overview
Documentation-only PR that brings internal/planner/doc.go up to the package data-structure standard and registers the idiomatic-reviewer subagent in CLAUDE.md.

doc.go gains four sections while existing lifecycle/plan-type content stays intact: Type Roles (who builds, persists, and mutates TaskPlan, PlannedTask, builders, and Executor); Invariants (atomic plan creation, single-patch reconcile, optimistic-lock status writes, retry vs terminal failure, nil plan as steady state, terminal cleanup, always-present conditions), each tied to a guarding test or labeled documented-but-unguarded; Zero-Value & Sentinel Semantics; and Concurrency & Staleness (optimistic lock + single patch at the type’s definition, reducing drift vs repo-wide rules in CLAUDE.md).

CLAUDE.md adds idiomatic-reviewer to the Subagents list so idiom review against CLAUDE.md and package doc.go is part of the workflow.

^{Reviewed by Cursor Bugbot for commit dfd73b2. Bugbot is set up for automated code reviews on this repo. Configure here.}