docs(miner): add the repo-agnostic capability audit checklist

[nickmopen]

Summary

Adds the repo-agnostic capability audit for the miner package (#4780) — a checklist, organized by file/module, of every hardcoded or implicitly gittensory-specific assumption in the miner's discovery/claim/scoring code that must become per-tenant configuration. This is the deliverable that #4784 executes directly; audit-and-document only, no code changes (per the issue's boundaries).

Doc: packages/gittensory-miner/docs/repo-agnostic-capability-audit.md.

Each finding carries a file:line citation, its category, current override status, and the target per-tenant config. Key conclusions:

• The miner's discovery/claim/scoring code is already largely repo-agnostic — discovery queries are caller-supplied, label preferences are generic config (.gittensory-miner.yml uses bug/enhancement, not gittensor:*), and ranking/feasibility are engine-delegated with config-overridable inputs. The audit explicitly lists what's already parameterized so De-hardcode discovery from gittensory's own conventions #4784 doesn't redo it.
• The real gaps: GitHub-forge hardcoding in opportunity-fanout.js (API version, headers, REST paths, search-qualifier dialect), an apiBaseUrl override that exists in the fan-out but isn't threaded to discover-cli, and engine label/goal-spec defaults (DEFAULT_TYPE_LABELS, DEFAULT_MINER_GOAL_SPEC) that silently fall back to gittensory's conventions.

Scope

• The PR title follows type(scope): short summary Conventional Commit format.
• This PR is focused (a single new doc) and does not mix unrelated changes.
• This follows CONTRIBUTING.md and does not reintroduce GitHub Pages, VitePress, site/, or CNAME.
• I linked a currently open issue this PR resolves — Closes #4780.

Validation

• git diff --check
• npm run docs:drift-check (passes — the new doc makes no mechanically-checkable claim that goes stale)
• Every file:line citation in the doc spot-verified against the current source (opportunity-fanout.js 4/7/202/241, discover-cli.js:102, engine pr-type-label.ts:26-28)

If any required check was skipped, explain why:

• Docs-only change (one new .md, no code). No src/**/apps/**/package changes, so Codecov and the backend/UI/MCP CI jobs are path-skipped; there is no code to test.

Safety

• No secrets, wallet details, hotkeys, coldkeys, PATs, private keys, raw trust scores, private rankings, or maintainer evidence are exposed — the doc references only public source paths and public config keys.
• Public GitHub text stays sanitized, low-noise, and implies no compensation guarantees or optimization tactics.
• No changelog edited.

Notes

• Per the issue's acceptance criterion, the checklist is meant to be reviewed/confirmed complete by whoever implements De-hardcode discovery from gittensory's own conventions #4784 — happy to adjust scope or granularity to match how you'd like De-hardcode discovery from gittensory's own conventions #4784 framed.

Closes #4780

[superagent-security]

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

[loopover-orb]

Tip

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

✅ Gittensory review result - approve/merge recommended

_{Review updated: 2026-07-12 14:58:17 UTC}

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

✅ Suggested Action - Approve/Merge

• safe to merge

Review summary
This PR adds a documentation-only audit checklist for the miner package, cataloguing hardcoded GitHub-forge assumptions and per-tenant config gaps with file:line citations, as scoped by issue #4780. It contains no code changes, explicitly defers execution to a follow-up PR (#4784), and the content is internally consistent (findings, already-parameterized list, and prioritized checklist align with each other). The claims are plausible and well-organized, though I cannot independently verify each file:line citation against the actual source of opportunity-fanout.js, discover-cli.js, etc. since those files aren't shown in this diff.

Nits — 6 non-blocking

• The doc cites specific line numbers (e.g. opportunity-fanout.js:4,7,69–71,83,202,241,70) that will drift as soon as those files are touched — consider a note that these are point-in-time citations, or link to the audit's generation commit SHA.
• The engine dependency section cites `src/settings/pr-type-label.ts:26–28` in a separate package (`@​jsonbored/gittensory-engine`) that isn't part of this repo's diff — worth confirming that path/line is accurate since it's the one citation not verifiable from this package alone.
• Consider adding a short 'How this audit was produced' note (manual read-through vs. grep-assisted) so future readers can judge how to re-verify staleness.
• If `docs:drift-check` doesn't mechanically verify file:line citations, consider a lightweight follow-up script that greps for the cited constants to catch citation drift automatically.
• packages/gittensory-miner/docs/repo-agnostic-capability-audit.md:29 uses bare source line numbers for an audit checklist, which will drift quickly as the implementation changes; prefer function or symbol anchors alongside the line references.
• 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	2 reviewers, synthesized
Linked issue	✅ Linked	#4780
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: 141 registered-repo PR(s), 87 merged, 12 issue(s).
Contributor context	✅ Confirmed Gittensor contributor	nickmopen; Gittensor profile; 141 PR(s), 12 issue(s).
Gate result	✅ Passing	No configured blocker found.
Improvement	⚠️ ℹ️ Insufficient signal	risk: low · value: insufficient-signal — Nothing measurable for the structural-improvement analyzers on this PR (e.g. no code files changed). LLM value judgment: moderate — The audit is a well-scoped, actionable planning artifact that directly unblocks the follow-up config-extraction work (#4784) by identifying concrete gaps and explicitly marking what's already done, avoiding duplicated effort.

Linked issue satisfaction

Addressed
The PR delivers exactly the requested audit-and-document deliverable: a file/module-organized checklist of gittensory-specific assumptions (labels, forge endpoints, scoring defaults) in the miner's discovery/claim/scoring code, explicitly scoped as input for #4784, with no code changes per the issue's boundaries.

Review context

• Author: nickmopen
• Role context: outside_contributor
• Public audience mode: oss maintainer
• Lane context: Repository is configured for direct PR review.
• Public profile languages: not available
• Official Gittensor activity: 141 PR(s), 12 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.

[BETA] Chat with Gittensory

Ask Gittensory a question about this PR directly in a comment — grounded only in the same cached, public-safe facts shown above, never a new claim.

• @gittensory ask <question> answers contribution-quality Q&A with source citations and freshness.
• @gittensory chat <question> answers in natural prose from cached decision-pack facts via local inference (maintainer/collaborator; read-only).
• A plain-language @gittensory mention with a real question is routed to the closest matching read-only command automatically -- no exact syntax required.

Full command reference: https://gittensory.aethereal.dev/docs/gittensory-commands

_{🟩 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 approves — the gate is satisfied and CI is green.