feat(miner-config): parse a feasibilityGate policy block from .gittensory-miner.yml

[joaovictor91123]

Summary

• Closes feat(miner-config): parse a feasibility-gate policy block from .gittensory-miner.yml #4275 by adding a feasibilityGate policy block to MinerGoalSpec (packages/gittensory-engine/src/miner-goal-spec.ts), the canonical config surface for .gittensory-miner.yml that packages/gittensory-miner/lib/opportunity-ranker.js already consumes via parseMinerGoalSpecContent(content).spec.
• Per the issue's explicit scope: this is config-parsing surface only — it does not wire the field into buildFeasibilityVerdict or its callers (that consumption is left to feat(miner-plan): wire the feasibility gate into a new MCP tool + miner CLI command #4270's follow-up work, "coordinating loosely" as the issue puts it). No changes to feasibility.ts or the (separately-shipped, unrelated) feasibility MCP tool/CLI command.
• Shape chosen (the issue explicitly left this open, offering "override/suppress specific avoid/raise reasons" or "just tune thresholds" as options): { enabled: boolean, suppressedReasons: string[] }. enabled mirrors the existing minerEnabled-style opt-out pattern; suppressedReasons is a data-only list of buildFeasibilityVerdict reason codes (e.g. duplicate_cluster_high) a future consumer can filter on — deliberately the more conservative of the two options since it needs no new enum/threshold surface and stays a simple mirror of the existing normalizeStringList/normalizeBoolean primitives already used throughout this file.
• Extended parseMinerGoalSpec/hasConfiguredGoalFields with a new normalizeFeasibilityGatePolicy helper (nested-object variant of the existing per-field normalizers: absent → default, non-mapping → warn+default, each sub-field independently normalized via the existing normalizeBoolean/normalizeStringList). Explicitly did not touch miner-goal-spec-parse.ts, the second non-exported/uncalled implementation the issue flags as a trap.
• Updated the JSON Schema (packages/gittensory-miner/schema/miner-goal-spec.schema.json), the field docs (packages/gittensory-miner/docs/miner-goal-spec.md), and the root example config (.gittensory-miner.yml.example) to match.

Scope

• The PR title follows type(scope): short summary Conventional Commit format.
• This PR is focused: one new field through the type/parser/schema/docs/example, plus the minimal test-literal fixes required elsewhere for the new required field to typecheck. No unrelated backend/UI/dependency changes, and no change to the feasibility composer or its existing consumers.
• This follows CONTRIBUTING.md and does not reintroduce GitHub Pages, VitePress, site/, or CNAME.
• I linked an issue, or this is small enough that the summary explains why an issue is not needed.

Validation

• git diff --check
• npm run actionlint — not run; no workflow files touched.
• npm run typecheck (clean on this diff; the repo's one pre-existing failure — a missing aws4fetch type declaration in src/selfhost/s3-blob-store.ts — reproduces identically on a clean main checkout and is unrelated). Adding a new required MinerGoalSpec field surfaced 5 pre-existing hand-written MinerGoalSpec object literals across test/unit/miner-opportunity-ranker.test.ts, test/unit/opportunity-branch-internals.test.ts, and test/unit/opportunity-metadata-signals.test.ts; all five now include the new field so they still satisfy the type.
• npm run test:coverage locally — ran packages/gittensory-engine/src/miner-goal-spec.ts's coverage in isolation against every test file that exercises it: 100% statements/branches/functions/lines on every line this diff touches (the file's only uncovered lines, 325-326, are the pre-existing, untouched discoverMinerGoalSpecPath — unrelated to this change). Also ran npm run test --workspace @jsonbored/gittensory-engine (the package's own node:test suite, which duplicates the parser/default-spec assertions): 322/322 pass. Did not run the full unsharded npm run test:coverage (this dev machine is shared with several other concurrent contributor sessions and a full run does not complete in reasonable time).
• npm run test:workers — not run; no Cloudflare Worker code touched.
• npm run build:mcp / npm run test:mcp-pack / miner-pack equivalents — not run directly, but npm --workspace @jsonbored/gittensory-engine run build was run locally (required to exercise the compiled package in tests) and succeeds. test:mcp-pack/test:miner-pack themselves fail on this Windows machine for an unrelated, pre-existing reason (spawnSync("npm", ...) needs shell:true on Windows; reproduces identically on a clean main checkout).
• npm run docs:drift-check — clean, unaffected.
• npm run ui:openapi:check / ui:lint / ui:build — not run; no UI files touched.
• npm audit --audit-level=moderate — not run; no dependency changes.
• New or changed behavior has unit/integration tests for new branches, fallback paths, and sanitizer boundaries, mirroring the existing per-field coverage pattern in both test/unit/miner-goal-spec-parser.test.ts (vitest) and packages/gittensory-engine/test/miner-goal-spec-parser.test.ts (node:test): present/valid, absent (defaults), non-mapping (warn + default), each nested sub-field malformed independently, and a policy-only config (no other fields set) still marking the spec present.

If any required check was skipped, explain why:

• Everything skipped above is either inapplicable to this diff (no UI/Worker/dependency/workflow surface touched) or blocked by a pre-existing, reproducible-on-clean-main Windows-local environment issue (npm pack's spawnSync Windows incompatibility) that does not reflect real CI behavior (GitHub Actions runs on Linux, and a dedicated CI step already builds @jsonbored/gittensory-engine before test:coverage runs).

Safety

• No secrets, wallet details, hotkeys, coldkeys, user PATs, private keys, raw trust scores, private rankings, or private maintainer evidence are exposed.
• Public GitHub text stays sanitized, low-noise, and does not imply compensation guarantees or optimization tactics.
• Auth, cookie, CORS, GitHub App, Cloudflare, or session behavior is not changed.
• API/OpenAPI/MCP behavior is not changed.
• No visible UI changes; UI evidence is not applicable.
• Public docs/changelogs are not changed (the .md file touched is the field reference doc this issue explicitly asks to update, not a changelog).

UI Evidence

Not applicable; config-parsing surface change only, no UI.

Notes

• Two commits: the feature itself, plus a small follow-up fixing three MinerGoalSpec test literals that a concurrent merge (landed between my initial implementation and pushing) reintroduced during a rebase.

[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 94.01%. Comparing base (861e8b7) to head (ee5d1bd).
⚠️ Report is 6 commits behind head on main.

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #4456   +/-   ##
=======================================
  Coverage   94.01%   94.01%           
=======================================
  Files         418      418           
  Lines       37417    37423    +6     
  Branches    13677    13679    +2     
=======================================
+ Hits        35178    35184    +6     
  Misses       1583     1583           
  Partials      656      656           

Files with missing lines	Coverage Δ
packages/gittensory-engine/src/miner-goal-spec.ts	97.64% <100.00%> (+0.17%)	⬆️

🚀 New features to boost your workflow:

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

[loopover-orb]

Tip

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

✅ Gittensory review result - approve/merge recommended

_{Review updated: 2026-07-09 19:59:30 UTC}

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

✅ Suggested Action - Approve/Merge

• safe to merge

Review summary
This PR adds a narrowly-scoped `feasibilityGate` config block ({enabled, suppressedReasons}) to `MinerGoalSpec` in `miner-goal-spec.ts`, following the file's existing per-field normalizer pattern (`normalizeBoolean`/`normalizeStringList`) via a new nested-object normalizer `normalizeFeasibilityGatePolicy`. It correctly threads the new field through `DEFAULT_MINER_GOAL_SPEC`, `cloneDefaultMinerGoalSpec` (deep-cloning the nested array so the frozen singleton can't be mutated), `hasConfiguredGoalFields`, the JSON schema, docs, example config, and the barrel export, and is accompanied by thorough tests covering the happy path, non-mapping rejection, independent sub-field fallback, and presence-detection edge cases. The description explicitly confirms this is config-parsing-only per the linked issue's stated scope (not wiring into `buildFeasibilityVerdict`), which matches what the diff actually does — no scope creep into `feasibility.ts` visible.

Nits — 4 non-blocking

• packages/gittensory-engine/src/miner-goal-spec.ts: `normalizeFeasibilityGatePolicy` passes `fallback.suppressedReasons` nowhere into `normalizeStringList` (that helper has no fallback param and always returns `[]` for an absent/invalid value) — harmless today since the default is always `[]`, but it's a latent trap if this nested-normalizer pattern is copied for a field whose default list is non-empty.
• verify feat(miner-config): parse a feasibility-gate policy block from .gittensory-miner.yml #4275 actually scopes this PR to parsing-only (per the external brief the linked-issue coverage looks partial) — if the issue expected any wiring/consumption stub, this diff wouldn't close it.
• Consider a short comment at `normalizeFeasibilityGatePolicy`'s call site or JSDoc noting that sub-field fallbacks currently only work for scalar defaults, given the `normalizeStringList` gap above.
• The `additionalProperties: true` on the new `feasibilityGate` schema object mirrors the top-level object's leniency, which is consistent — no change needed, just flagging it was a deliberate match rather than an oversight.

Signal	Result	Evidence
Code review	✅ No blockers	1 reviewer
Linked issue	✅ Linked	#4275
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: 95 registered-repo PR(s), 45 merged, 11 issue(s).
Contributor context	✅ Confirmed Gittensor contributor	joaovictor91123; Gittensor profile; 95 PR(s), 11 issue(s).
Gate result	✅ Passing	No configured blocker found.

Linked issue satisfaction

Addressed
The diff adds a feasibilityGate field (enabled + suppressedReasons) to MinerGoalSpec with a default entry, a normalizeFeasibilityGatePolicy helper wired into parseMinerGoalSpec and hasConfiguredGoalFields, updates the JSON schema, docs, and example config, avoids touching the flagged sibling miner-goal-spec-parse.ts, and adds tests covering present/absent/malformed/nested sub-field cases as reques

Review context

• Author: joaovictor91123
• 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: 95 PR(s), 11 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