feat(miner-foundation): MinerGoalSpec file discovery + example doc (#2294)

[nickmopen]

Closes #2294.

The tolerant parser for .gittensory-miner.yml (parseMinerGoalSpec / parseMinerGoalSpecContent) landed in the meantime via #2652 and #2658. This PR adds the remaining #2294 deliverables that are still missing on main — file discovery and the example doc — built directly on the merged parser (no duplication).

Deliverables

• discoverMinerGoalSpecPath(exists) + MINER_GOAL_SPEC_FILENAMES in miner-goal-spec.ts (exported from the barrel): the documented discovery order — .gittensory-miner.yml → .github/gittensory-miner.yml → .gittensory-miner.json → .github/gittensory-miner.json, first match wins. Pure — the existence check is injected, so it stays IO-free and unit-testable; a caller reads the returned path and feeds its content to parseMinerGoalSpecContent.
• .gittensory-miner.yml.example at the repo root, matching .gittensory.yml.example's header + per-field Default: X style.

Validation

npm test in packages/gittensory-engine: 37/37 pass (new: discovery order, first-match-wins, null when absent, and that only the listed candidates are probed — the parser itself is already covered by #2652/#2658's tests). tsc clean under strict.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 96.13%. Comparing base (4c72212) to head (818c566).
⚠️ Report is 3 commits behind head on main.

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #2685   +/-   ##
=======================================
  Coverage   96.13%   96.13%           
=======================================
  Files         239      239           
  Lines       26739    26739           
  Branches     9699     9699           
=======================================
  Hits        25705    25705           
  Misses        424      424           
  Partials      610      610           

🚀 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-03 06:12:30 UTC}

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

⏸️ Suggested Action - Manual Review

Review summary
This adds a pure MinerGoalSpec discovery helper, exports it through the engine barrel, and documents the supported filename precedence with a root example file. The implementation is small and matches the stated order, and the tests cover ordering, first-match behavior, no-match behavior, and the exact probed candidate list. I do not see a reachable correctness defect in the provided changed files.

Nits — 4 non-blocking

• nit: packages/gittensory-engine/test/miner-goal-spec-discovery.test.ts:16 does not assert short-circuiting after a later candidate match, so a regression that keeps probing after the first true result would not be caught.
• nit: .gittensory-miner.yml.example:1 uses Unicode punctuation/arrows while much of this repo’s config/examples are easier to edit and diff when kept ASCII-only.
• packages/gittensory-engine/test/miner-goal-spec-discovery.test.ts:16: add a probe-recording case where `.github/gittensory-miner.yml` returns true and assert the root JSON variants are never probed.
• .gittensory-miner.yml.example:12: consider replacing the arrows with ASCII `->` for consistency with copy/paste-friendly config docs.

Signal	Result	Evidence
Code review	✅ No blockers	1 reviewer
Linked issue	✅ Linked	#2294
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 (size label size:M; 1 linked issue).
Validation posture	❌ 5/25	Preflight is holding this PR: the review lane is unavailable, so it is not ready for automated review.
Contributor workload	✅ 10/10	Author activity: 100 registered-repo PR(s), 67 merged, 0 issue(s).
Contributor context	✅ Confirmed Gittensor contributor	nickmopen; Gittensor profile; 100 PR(s), 0 issue(s).
Gate result	✅ Passing	No configured blocker found.

Review context

• Author: nickmopen
• Role context: outside_contributor
• Public audience mode: oss maintainer
• Lane context: Repository registration is not available in the local Gittensory cache.
• Public profile languages: not available
• Official Gittensor activity: 100 PR(s), 0 issue(s).
• PR-specific overlap: none found.

Contributor next steps

• Await review-lane availability.
• Refresh registry data or choose a registered active repo.

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