docs(miner-hands): CodingAgentDriver seam design doc + interface (#4312)

[jimcody1995]

Summary

• Land the #4262 CodingAgentDriver interface seam in packages/gittensory-engine/src/miner/coding-agent-driver.ts, mirroring the SelfHostAi single-run() pattern and exporting types from the engine barrel.
• Add packages/gittensory-miner/docs/coding-agent-driver.md with design rationale, driver-authoring guide (third-backend checklist), neighborhood cross-references (#4269, #4271, #4294, #4311, #4289, #4296), and an abbreviated end-to-end attempt lifecycle.
• Lock the interface contract with engine + doc acceptance tests so CLI (#4266) and Agent-SDK (#4267) drivers can implement against a settled shape.

Notes

• Issue docs(miner-hands): CodingAgentDriver seam design doc + driver-authoring guide #4312 depended on feat(miner-hands): define the CodingAgentDriver interface seam #4262’s settled interface; this PR includes the minimal feat(miner-hands): define the CodingAgentDriver interface seam #4262 contract (types + fake-driver tests) so the documentation reflects real exported types, not speculation.
• Prose doc is intentionally outside scripts/check-docs-drift.mjs scope (per issue); test/unit/coding-agent-driver-doc.test.ts guards required sections and cross-references.

Test plan

• npm --workspace @jsonbored/gittensory-engine run build
• npm run typecheck
• npm test -- test/unit/coding-agent-driver-doc.test.ts
• npm run test --workspace @jsonbored/gittensory-engine (includes coding-agent-driver.test.ts contract tests)
• Patch lines covered: interface contract tests + doc acceptance tests (type-only seam file has no executable branches)

Closes #4312

Made with Cursor

[superagent-security]

🚨 Contributor flagged. Click here for more info: Superagent Dashboard

[superagent-security]

Superagent didn't find any vulnerabilities or security issues in this PR.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 93.95%. Comparing base (4d0aef1) to head (1b823a1).
⚠️ Report is 41 commits behind head on main.

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #4346   +/-   ##
=======================================
  Coverage   93.95%   93.95%           
=======================================
  Files         399      399           
  Lines       36782    36782           
  Branches    13436    13436           
=======================================
  Hits        34557    34557           
  Misses       1569     1569           
  Partials      656      656           

🚀 New features to boost your workflow:

• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[loopover-orb]

Warning

🟨🟨🟨🟨🟨🟨🟨🟨🟨🟨🟨🟨

⏸️ Gittensory review result - manual review recommended

_{Review updated: 2026-07-09 17:14:28 UTC}

5 files · 1 AI reviewer · no blockers · readiness 100/100 · CI green · dirty

⏸️ Suggested Action - Manual Review

Review summary
This lands the CodingAgentDriver interface seam (#4262) as a type-only file mirroring SelfHostAi's single-run() pattern, wires it through the engine barrel export, and ships a design doc plus contract/doc acceptance tests. The change is correct and low-risk: the interface has zero runtime logic, the contract tests genuinely exercise the exported types via a fake driver, and the doc-acceptance test checks real string containment against the actual source and doc files rather than fabricating state. The PR closes an existing issue (#4312) and stays narrowly scoped to the interface + doc, which is the right shape for a seam-definition PR ahead of the CLI/Agent-SDK driver implementations.

Nits — 5 non-blocking

• packages/gittensory-engine/test/coding-agent-driver.test.ts's third test only regex-matches prose comments in the source file (`SelfHostAi`, `SpawnFn`, `run()`) rather than any type/behavior contract — it's testing comment text, not code, so it will pass even if the actual mirroring is inaccurate; consider dropping it or folding it into the doc-acceptance test instead.
• The design doc at packages/gittensory-miner/docs/coding-agent-driver.md is explicitly exempted from scripts/check-docs-drift.mjs and only guarded by string-containment assertions in test/unit/coding-agent-driver-doc.test.ts, so if fields are added/renamed on `CodingAgentDriverTask`/`CodingAgentDriverResult` later, the doc can silently drift out of sync since the test only checks for currently-known field names, not full parity.
• Contract test imports from `../dist/index.js` (packages/gittensory-engine/test/coding-agent-driver.test.ts:11), so it depends on a fresh build being run first — worth a one-line comment noting the build prerequisite if that isn't already the convention for other engine tests.
• When feat(miner-hands): CLI-subprocess CodingAgentDriver (reuse SpawnFn/redactSecrets/EFFORT_TIMEOUT_MS pattern) #4266/feat(miner-hands): Agent-SDK CodingAgentDriver (query() loop) #4267 land, extend packages/gittensory-engine/test/coding-agent-driver.test.ts's fake-driver coverage to include a case where `usage.provider` carries backend-specific data alongside the opaque contract, verifying it's never destructured by orchestration code.
• Consider trimming the third contract test (comment-matching) discussed above rather than keeping it as permanent regression coverage.

Flagged checks (non-blocking)

• Contributor trust — Contributor flagged for review

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: 147 registered-repo PR(s), 93 merged, 0 issue(s).
Contributor context	✅ Confirmed Gittensor contributor	jimcody1995; Gittensor profile; 147 PR(s), 0 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 what CodingAgentDriver is, the SelfHostAi design rationale, a concrete driver-authoring guide for a third backend (interface contract, DI convention, factory hookup, parity suite), a neighborhood cross-reference table for #4269/#4271/#4289/#4294/#4296/#4311, and an abbreviated end-to-end worked example, matching every deliv

Review context

• Author: jimcody1995
• Role context: outside_contributor
• Public audience mode: oss maintainer
• Lane context: Repository is configured for direct PR review.
• Public profile languages: TypeScript, JavaScript
• Official Gittensor activity: 147 PR(s), 0 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

[loopover-orb]

Gittensory is closing this pull request on the maintainer's behalf (CI is failing (Contributor trust)). This is an automated maintenance action — to pursue this change, please open a new pull request with the issues resolved. Closed PRs may be analyzed later to improve review accuracy, but they are not automatically reopened or re-reviewed.

[loopover-orb]

Gittensory is closing this pull request on the maintainer's behalf (conflicts with the base branch — resolve and open a fresh PR). This is an automated maintenance action — to pursue this change, please open a new pull request with the issues resolved. Closed PRs may be analyzed later to improve review accuracy, but they are not automatically reopened or re-reviewed.