feat(miner-selfimprove): engine-parity drift detector (#4260)

[jimcody1995]

Summary

• Adds scripts/check-engine-parity.mjs, a mechanical CI tripwire that discovers hand-duplicated (non-shim) twins under src/{review,settings,signals} ↔ packages/gittensory-engine/src/{review,settings,signals}, normalizes known-harmless import-path aliases, and fails on normalized body drift.
• Adds a version-skew check comparing the installed @jsonbored/gittensory-engine semver against the monorepo engine package version (wired into test:ci via engine-parity:drift-check).
• Extends gittensory-miner doctor with an engine-version-skew check (installed vs monorepo/pinned expected minimum) and ships packages/gittensory-miner/expected-engine.version for published-miner fallback.
• Syncs three pairs that had drifted on main: guardrail-config (e2e-test-commit glob), change-guardrail (guardrailPathMatches structure), and linked-issue-label-propagation (comment wording).

Closes #4260

Test plan

• npm run engine-parity:drift-check passes on this branch (16 pairs + version skew)
• vitest run test/unit/check-engine-parity-script.test.ts — identical pass, diverged fail, semver equal/behind/ahead, regression guard on real repo pairs
• vitest run test/unit/miner-status.test.ts — doctor includes engine-version-skew; behind/ahead/skipped/missing-installed cases
• test:ci chain includes engine-parity:drift-check alongside manifest:drift-check

Notes

• Does not duplicate test(engine): build a true live-gate-vs-predicted-gate cross-check #4257 (live-gate-vs-predicted-gate behavioral cross-check); this is the lightweight mechanical drift/skew tripwire scoped in feat(miner-selfimprove): engine-parity drift detector — flag when gittensory-engine diverges from src/ #4260.
• Engine stubs (check-names, review-thread-findings) and thin re-export shims (duplicate-winner, test-evidence) are auto-excluded from the pair sweep.

Made with Cursor

[superagent-security]

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

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 93.98%. Comparing base (6f40ce1) to head (f256671).
⚠️ Report is 10 commits behind head on main.

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #4349   +/-   ##
=======================================
  Coverage   93.98%   93.98%           
=======================================
  Files         406      406           
  Lines       36993    37001    +8     
  Branches    13521    13524    +3     
=======================================
+ Hits        34767    34775    +8     
  Misses       1570     1570           
  Partials      656      656           

Files with missing lines	Coverage Δ
...s/gittensory-engine/src/review/guardrail-config.ts	100.00% <ø> (ø)
...ngine/src/review/linked-issue-label-propagation.ts	100.00% <ø> (ø)
...es/gittensory-engine/src/settings/pr-type-label.ts	100.00% <100.00%> (ø)
src/signals/change-guardrail.ts	97.77% <100.00%> (+0.15%)	⬆️

🚀 New features to boost your workflow:

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

[superagent-security]

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

[loopover-orb]

Warning

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

⏸️ Gittensory review result - manual review recommended

_{Review updated: 2026-07-09 17:23:16 UTC}

14 files · 1 AI reviewer · no blockers · readiness 100/100 · CI green · unstable

⏸️ Suggested Action - Manual Review

• Touches a guarded path — held for manual review: This PR changes guardrail-protected path(s): scripts/check-engine-parity.ts (matched scripts/**), scripts/check-miner-package.mjs (matched scripts/**).

Review summary
This adds a mechanical CI tripwire (scripts/check-engine-parity.ts) that discovers hand-duplicated src/{review,settings,signals} ↔ gittensory-engine twin files, normalizes known import-path aliases, and fails on body drift, plus a version-skew check wired into both `test:ci` and `gittensory-miner doctor`. It also syncs three previously-drifted twin pairs (guardrail-config, change-guardrail, linked-issue-label-propagation). The change-guardrail.ts edit is a pure refactor (if/continue replacing a short-circuit OR) with no behavioral difference, and the script/tests are well-structured with real regression guards against the actual repo tree (discoverEngineParityPairs run against process.cwd()). The PR closes #4260 and is narrowly scoped to review-stack correctness tooling.

Nits — 6 non-blocking

• scripts/check-engine-parity.ts:checkEngineParityDrift re-reads every pair's host/engine file a second time even though discoverEngineParityPairs already read them once per pair — harmless for a one-shot CI script but avoidable duplicate I/O.
• packages/gittensory-miner/lib/status.js:readInstalledEnginePackageVersion's catch fallback calls readInstalledEnginePackageVersionFromPaths("", ...), and join("", "..", "package.json") resolves relative to process.cwd() rather than a package-relative path — it's guarded by try/catch and falls through to the workspace pin, but could silently pick up an unrelated package.json if one happens to exist a directory above cwd; worth resolving from `__dirname` instead of an empty string.
• packages/gittensory-miner/expected-engine.version is a manually-maintained pin (currently 0.2.0) that must be bumped in lockstep with packages/gittensory-engine/package.json's version for published-miner installs to report accurate skew — consider a script assertion (or the same drift-check) that fails if the pin falls out of sync with the monorepo engine version.
• scripts/check-engine-parity.ts:isEngineStubPair's heuristic (srcCompact > engineCompact*3 && engineCompact<250) is a magic-number heuristic that could misclassify a small legitimate twin as a stub; a comment justifying the specific thresholds (mirroring the ReDoS-benchmark style comments elsewhere in this PR) would help future maintainers adjust it safely.
• Consider having check-engine-parity.ts's checkEngineParityDrift accept the already-read hostText/engineText from discoverEngineParityPairs instead of re-reading, to keep the script trivially fast as more pairs are added.
• Touches a guarded path — held for manual review — A maintainer must review and merge this change.

Flagged checks (non-blocking)

• Contributor trust — Contributor flagged for review

Signal	Result	Evidence
Code review	✅ No blockers	1 reviewer
Linked issue	✅ Linked	#4260
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	⚠️ Not blocking	Advisory; not blocking this PR.

Linked issue satisfaction

Addressed
The PR adds scripts/check-engine-parity.ts which discovers and byte-diffs (after normalizing known-harmless import aliases) the hand-duplicated src/ vs gittensory-engine pairs, adds a version-skew comparator (checkEngineVersionSkew / buildEngineVersionSkewCheck) wired into both a new doctor check and test:ci via engine-parity:drift-check, and includes unit tests for identical/diverged pairs and eq

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.