docs(miner-hands): CodingAgentDriver seam design doc + driver-authoring guide

[JSONbored]

Depends on #4262 landing first — this documents the interface's ACTUAL shape once real, not a speculative design written ahead of the code (which would drift the moment #4262's implementation details settle). The natural home is packages/gittensory-miner/docs/, which already holds exactly this kind of design-note markdown for other miner primitives: packages/gittensory-miner/docs/miner-goal-spec.md and packages/gittensory-miner/docs/cross-repo-discovery-phase1.md. This is prose documentation, not one of the enumerable code-driven surfaces scripts/check-docs-drift.mjs cross-checks (feature flags, @gittensory commands, gate-mode dimensions) — so it has no automated drift check, which makes it MORE important to write accurately the first time and keep it current by hand.

Deliverables

• packages/gittensory-miner/docs/coding-agent-driver.md (matching the existing docs/ naming convention — lowercase-hyphenated, topic-named) covering: what CodingAgentDriver is and why it exists (the seam that lets the miner run EITHER a CLI subprocess OR the Agent SDK behind one interface), and a design-rationale section explaining the choice to mirror SelfHostAi (src/selfhost/ai.ts) rather than invent a new pattern.
• A driver-authoring guide: concretely, what a THIRD implementation (beyond feat(miner-hands): CLI-subprocess CodingAgentDriver (reuse SpawnFn/redactSecrets/EFFORT_TIMEOUT_MS pattern) #4266's CLI-subprocess and feat(miner-hands): Agent-SDK CodingAgentDriver (query() loop) #4267's Agent-SDK drivers) would need to satisfy — the interface contract, the injected-dependency testability convention (mirroring SpawnFn injection), how to plug into the factory (feat(miner-hands): CodingAgentDriver factory + provider-style config resolution #4289), and how to get covered by the parity/contract suite (test(miner-hands): parity/contract test suite for CodingAgentDriver implementations #4296).
• Cross-reference (not duplicate) the acceptance-criteria file (feat(miner-hands): immutable acceptance-criteria file written before the coding agent starts #4271), worktree isolation (feat(miner-hands): git-worktree-per-attempt isolation primitive #4269), attempt log (feat(miner-hands): driver-level structured attempt log (JSONL event trace per attempt) #4294), and metering (feat(miner-hands): per-attempt cost/turn metering for CodingAgentDriver runs #4311) as the surrounding primitives a driver implementation interacts with, so this doc reads as the map of the whole neighborhood, not just the interface in isolation.
• A worked example (even if abbreviated) showing one full attempt lifecycle end-to-end through the primitives this batch built, since that's the fastest way for a future contributor to understand how the pieces compose.

References

• packages/gittensory-miner/docs/miner-goal-spec.md, packages/gittensory-miner/docs/cross-repo-discovery-phase1.md (existing docs-directory precedent and naming convention)
• scripts/check-docs-drift.mjs:1-9 (confirms this doc is NOT covered by the existing automated docs-drift check — it's prose, not an enumerable code-driven surface)
• src/selfhost/ai.ts:1-7 (header comment — the existing design-rationale-in-a-comment style this doc's design-rationale section can draw from)
• Depends on feat(miner-hands): define the CodingAgentDriver interface seam #4262 (this batch) landing first — documents its real, settled shape
• Cross-references feat(miner-hands): CLI-subprocess CodingAgentDriver (reuse SpawnFn/redactSecrets/EFFORT_TIMEOUT_MS pattern) #4266, feat(miner-hands): Agent-SDK CodingAgentDriver (query() loop) #4267, feat(miner-hands): git-worktree-per-attempt isolation primitive #4269, feat(miner-hands): immutable acceptance-criteria file written before the coding agent starts #4271, feat(miner-hands): CodingAgentDriver factory + provider-style config resolution #4289, feat(miner-hands): driver-level structured attempt log (JSONL event trace per attempt) #4294, test(miner-hands): parity/contract test suite for CodingAgentDriver implementations #4296, feat(miner-hands): per-attempt cost/turn metering for CodingAgentDriver runs #4311 (this batch) as the primitives a driver-authoring guide needs to situate

[linear-code]

JSO-3299