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

[davion-knight]

Adds packages/gittensory-miner/docs/coding-agent-driver.md — the design note + authoring guide for the CodingAgentDriver interface seam (#4262), matching the existing docs/ prose convention (miner-goal-spec.md, cross-repo-discovery-phase1.md).

Covers

• What & why: the one interface a miner runs a coding agent through — a local CLI subprocess or an in-process Agent-SDK query() loop behind a provider-agnostic contract — and the rationale for mirroring SelfHostAi (single run(), injected deps) rather than inventing a new pattern.
• The contract: the CodingAgentDriverTask / CodingAgentDriverResult / run() shapes.
• The neighborhood: a table mapping each surrounding primitive to its module — execution mode (paused/dry_run/live), invokeCodingAgentDriver, the factory, the attempt log (feat(miner-hands): driver-level structured attempt log (JSONL event trace per attempt) #4294), metering (feat(miner-hands): per-attempt cost/turn metering for CodingAgentDriver runs #4311), acceptance criteria (feat(miner-hands): immutable acceptance-criteria file written before the coding agent starts #4271), and worktree isolation (feat(miner-hands): git-worktree-per-attempt isolation primitive #4269).
• Authoring guide: the five steps a third driver implementation must satisfy (implement the interface with injected deps, honor task scoping, return the result shape faithfully, register in the factory, get covered by the parity/contract suite test(miner-hands): parity/contract test suite for CodingAgentDriver implementations #4296).
• A worked attempt lifecycle end-to-end through the landed primitives.

Accuracy

Written against the seam's actual landed shape — the CLI-subprocess (#4266) and Agent-SDK (#4267) backends are framed as the planned first two, since createCodingAgentDriver today resolves the built-in noop driver (CODING_AGENT_DRIVER_NAMES = ["noop"]). Every referenced export was verified against packages/gittensory-engine/src/miner/. Prose only — not one of the enumerable surfaces check-docs-drift.mjs tracks, so it has no automated drift check (docs:drift-check stays green); the relative link to the interface resolves.

Closes #4312

[loopover-orb]

Tip

🟩🟩🟩🟩🟩🟩🟩🟩🟩🟩🟩🟩

✅ Gittensory review result - approve/merge recommended

_{Review updated: 2026-07-09 20:20:03 UTC}

1 file · 1 AI reviewer · no blockers · readiness 100/100 · CI green · clean

✅ Suggested Action - Approve/Merge

• safe to merge

Review summary
This is a pure prose documentation addition (packages/gittensory-miner/docs/coding-agent-driver.md, +100/-0) describing the CodingAgentDriver seam, its contract, surrounding primitives, and a driver-authoring guide. Every symbol it references (CodingAgentDriverTask, CodingAgentDriverResult, CodingAgentDriver, createFakeCodingAgentDriver, createNoopCodingAgentDriver, CODING_AGENT_DRIVER_NAMES) matches the actual coding-agent-driver.ts source shown in context, and the relative link (../../gittensory-engine/src/miner/coding-agent-driver.ts) resolves correctly from the doc's location. No code, schema, or migration changes are involved, so there's nothing to break; the change is self-contained and closes its own linked issue (#4312).

Nits — 6 non-blocking

• The doc cites specific exports from coding-agent-mode.ts, coding-agent-invoke.ts, driver-factory.ts, attempt-log.ts, and attempt-metering.ts, none of which were provided in this review's context — worth a second pass to confirm names like `resolveCodingAgentExecutionMode` (used in the lifecycle diagram) and `codingAgentModeExecutes` (used in the primitives table) are both real and not conflated.
• Only the core interface file gets a clickable relative link; the five sibling modules in the primitives table (coding-agent-mode.ts, coding-agent-invoke.ts, driver-factory.ts, attempt-log.ts, attempt-metering.ts) are just backticked filenames with no links, which is a minor inconsistency within the same doc.
• The authoring guide's step 4 says to add the new driver name to `CODING_AGENT_DRIVER_NAMES` but doesn't mention updating `resolveConfiguredCodingAgentDriverNames`'s allow-list logic explicitly beyond 'wire createCodingAgentDriver' — could be more explicit for a first-time contributor following the guide.
• Add relative links for the other primitive modules (coding-agent-mode.ts, coding-agent-invoke.ts, driver-factory.ts, attempt-log.ts, attempt-metering.ts) to match the treatment given to coding-agent-driver.ts, for consistency and easier navigation.
• Since feat(miner-hands): CLI-subprocess CodingAgentDriver (reuse SpawnFn/redactSecrets/EFFORT_TIMEOUT_MS pattern) #4266/feat(miner-hands): Agent-SDK CodingAgentDriver (query() loop) #4267 (the CLI-subprocess and Agent-SDK drivers) are explicitly framed as 'planned,' consider adding a one-line note on how/when this doc should be revisited once those land, so it doesn't silently drift once `CODING_AGENT_DRIVER_NAMES` grows beyond `["noop"]`.
• Diff looks like trivial or whitespace-only churn — Reduce whitespace-only or formatting-only churn and keep the diff focused on substantive changes.

Signal	Result	Evidence
Code review	✅ No blockers	1 reviewer
Linked issue	✅ Linked	#4312
Related work	✅ No active overlap found	No same-issue or scoped active PR overlap found.
Change scope	✅ 20/20	Low review scope from cached public metadata (1 linked issue).
Validation posture	✅ 25/25	PR body includes validation/test evidence.
Contributor workload	✅ 10/10	Author activity: 83 registered-repo PR(s), 48 merged, 3 issue(s).
Contributor context	✅ Confirmed Gittensor contributor	davion-knight; Gittensor profile; 83 PR(s), 3 issue(s).
Gate result	✅ Passing	No configured blocker found.

Linked issue satisfaction

Addressed
The PR adds packages/gittensory-miner/docs/coding-agent-driver.md covering the interface's what/why, a design-rationale section mirroring SelfHostAi, the contract shapes, a five-step driver-authoring guide, a table cross-referencing the surrounding primitives (#4266/#4267/#4269/#4271/#4289/#4294/#4296/#4311), and a worked end-to-end attempt lifecycle, matching every deliverable in the issue. It al

Review context

• Author: davion-knight
• Role context: outside_contributor
• Public audience mode: oss maintainer
• Lane context: Repository is configured for direct PR review.
• Public profile languages: Rust
• Official Gittensor activity: 83 PR(s), 3 issue(s).
• PR-specific overlap: none found.

Contributor next steps

• Keep the PR focused and include validation evidence before maintainer review.

Signal definitions

• Related work = same linked issue, overlapping active PRs, or title/path similarity.
• Change scope = cached public metadata such as size labels, draft state, and review-burden hints.
• Validation posture = whether the PR provides enough public validation/test evidence for maintainer review.
• Contributor workload = public contributor activity and cleanup pressure, not a repo-wide quality failure.
• Contributor context = public GitHub/Gittensor identity context; non-Gittensor status is not a blocker.

_{🟩 Safe / merged · 🟦 Advisory · 🟨 Held for review · 🟥 Blocked / closed}

---

💰 Earn for open-source contributions like this. Gittensor lets GitHub contributors earn for the work they already do — register to start earning →.

Checked by Gittensory, a quiet PR intelligence layer for OSS maintainers.

• Re-run Gittensory review