fix(miner): flag real LOOPOVER_MINER_* env vars missing from DEPLOYMENT.md (#6601)

[shin-core]

Summary

packages/loopover-miner/lib/deployment-docs-audit.js only enforced the forward direction of its own contract — a DOCUMENTED env var / path / subcommand must still exist. It never caught the reverse: a real LOOPOVER_MINER_* env-var read that DEPLOYMENT.md simply never documents.

• Added a reverse-direction check to auditDeploymentDocs: every real read that starts with LOOPOVER_MINER_, does not end with _DB (that family is documented generically via one pattern sentence, not enumerated), and is not in claims.envVars now fails the audit, naming the exact var. Bare MINER_*-only tokens are excluded (they also match non-env event/metric/filename constants).
• Exposed reality.envReads as an enumerable set (in both deployment-docs-audit.d.ts and check-miner-deployment-docs.d.mts), populated by buildLiveMinerDeploymentReality from the scanEnvVarTokens result it already builds — no new source-scanning.
• Documented the 13 previously-undocumented env vars in DEPLOYMENT.md (new "Environment variable reference" section) so the doc passes the new check.
• Forward-direction checks (documented-var-without-a-read, dead paths, unregistered subcommands) are unchanged.

Closes #6601

Test plan

• test/unit/miner-deployment-docs-audit.test.ts: new cases for all reverse branches — an undocumented non-_DB LOOPOVER_MINER_* read is flagged by name; a documented one is not; an undocumented *_DB read is NOT flagged; an undocumented bare MINER_* read is NOT flagged.
• test/unit/check-miner-deployment-docs.test.ts: asserts the live-built reality's new envReads field is populated, contains LOOPOVER_MINER_LOG_LEVEL, and agrees with hasEnvRead.
• node scripts/check-miner-deployment-docs.mjs exits 0 against the updated DEPLOYMENT.md (16 env vars, 15 paths, 4 subcommands).
• npm run typecheck clean.
• codecov/patch green (every new branch in auditDeploymentDocs covered by the tests above).

[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.65%. Comparing base (3de7c25) to head (b586810).
⚠️ Report is 2 commits behind head on main.

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #6726   +/-   ##
=======================================
  Coverage   93.65%   93.65%           
=======================================
  Files         682      682           
  Lines       68133    68137    +4     
  Branches    18701    18701           
=======================================
+ Hits        63808    63812    +4     
  Misses       3347     3347           
  Partials      978      978           

Flag	Coverage Δ
shard-1	43.95% <0.00%> (-0.01%)	⬇️
shard-2	36.85% <0.00%> (-0.01%)	⬇️
shard-3	32.31% <100.00%> (+<0.01%)	⬆️
shard-4	34.84% <75.00%> (+<0.01%)	⬆️
shard-5	31.01% <0.00%> (-0.01%)	⬇️
shard-6	45.71% <0.00%> (-0.01%)	⬇️

Flags with carried forward coverage won't be shown. Click here to find out more.

Files with missing lines	Coverage Δ
...ckages/loopover-miner/lib/deployment-docs-audit.js	100.00% <100.00%> (ø)

[loopover-orb]

Warning

⏸️ LoopOver review result - manual review recommended

_{Review updated: 2026-07-17 04:49:52 UTC}

7 files · 1 AI reviewer · no blockers · CI green · unstable

⏸️ Suggested Action - Manual Review

Review summary
This PR adds a reverse-direction check to auditDeploymentDocs that flags real LOOPOVER_MINER_* env-var reads not documented in DEPLOYMENT.md, wires reality.envReads through as an enumerable set (already derived from the existing scanEnvVarTokens result, no new scanning), and backfills DEPLOYMENT.md with 13 previously-undocumented vars. The exclusions (_DB family, bare MINER_* aliases) are sensible and each has a dedicated test, and the change closes the exact gap named in #6601. Implementation is straightforward and low-risk; it's a pure addition of a new failure branch plus doc content, with no changes to existing forward-direction logic.

Nits — 4 non-blocking

• deployment-docs-audit.js:106-115 — the exclusion of the bare `MINER_*` namespace is only implicit via the `LOOPOVER_MINER_` prefix check; a one-line comment or test naming a real bare-`MINER_*` var from the codebase (rather than a synthetic `MINER_PR_OUTCOME_EVENT`) would make the exemption easier to trust at a glance.
• DEPLOYMENT.md's new table lists `LOOPOVER_MINER_AMS_COLLECTOR_URL`/`_TOKEN` and `LOOPOVER_MINER_SENTRY_DSN`/`_ENVIRONMENT` as pairs in single rows — consider one row per var for consistency with the rest of the table and easier future diffing.
• Consider asserting in a test that every entry in `reality.envReads` scanned live actually round-trips through `hasEnvRead`, to guard the two representations from drifting apart if `buildLiveMinerDeploymentReality` is refactored later (partially covered already in check-miner-deployment-docs.test.ts).
• In deployment-docs-audit.d.ts, `envReads: Iterable<string>` is fine but a `ReadonlySet<string>` type would better document that duplicates are already deduped by the producer.

Flagged checks (non-blocking)

• Contributor trust — Contributor flagged for review

Decision drivers

• ✅ Code review — No blockers (1 reviewer)
• ✅ Gate result — Passing (No configured blocker found.)

Context & advisory signals — never blocks the verdict

Signal	Result	Evidence
Linked issue	✅ Linked	#6601
Related work	✅ No active overlap found	No same-issue or scoped active PR overlap found.
Change scope	❌ 8/20	High 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: 43 registered-repo PR(s), 24 merged, 0 issue(s).
Contributor context	✅ Confirmed Gittensor contributor	shin-core; Gittensor profile; 43 PR(s), 0 issue(s).
Improvement	✅ Minor	risk: clean · value: minor · LLM: moderate

Linked issue satisfaction

Addressed
The diff adds the reverse-direction check in auditDeploymentDocs exactly as specified (LOOPOVER_MINER_ prefix, excluding *_DB suffix, checked against claims.envVars), exposes reality.envReads populated from the existing scanEnvVarTokens scan with no new scanning logic, and documents all 13 previously-undocumented env vars in DEPLOYMENT.md while excluding the bare MINER_* namespace from the reverse

Review context

• Author: shin-core
• Role context: outside_contributor
• Public audience mode: oss maintainer
• Lane context: Repository is configured for direct PR review.
• Public profile languages: TypeScript, JavaScript, Solidity, Dart, Python, CSS, PHP, Rust
• Official Gittensor activity: 43 PR(s), 0 issue(s).
• PR-specific overlap: none found.

Contributor next steps

• Start here: Add a concise scope and risk note.
• Then work through the remaining 1 step in the Signals table above.

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.

🧪 Chat with LoopOver

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

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

Full command reference: https://loopover.ai/docs/loopover-commands

🧪 Experimental — new and may change.

_{🟩 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 LoopOver, a quiet PR intelligence layer for OSS maintainers.

• Re-run LoopOver review