fix(engine): gate-decision twin version-bump tripwire

[RealDiligent]

Summary

• Extends scripts/check-engine-parity.ts to monitor the hand-duplicated gate-decision twin pair src/rules/advisory.ts ↔ packages/gittensory-engine/src/advisory/gate-advisory.ts.
• Adds a PR diff tripwire: editing only one twin without also editing the other requires a semver bump in packages/gittensory-engine/package.json; updating both twins together passes without a bump.
• Includes regression tests for the advisory pair discovery, single-sided failure, coordinated pass, and version-bump pass cases.

Closes #4518

Test plan

• npx vitest run test/unit/check-engine-parity-script.test.ts -t gate-decision
• CI green on upstream PR

[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.10%. Comparing base (ae70406) to head (51eb024).
⚠️ Report is 1 commits behind head on main.

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #4569   +/-   ##
=======================================
  Coverage   94.10%   94.10%           
=======================================
  Files         427      427           
  Lines       38022    38022           
  Branches    13877    13877           
=======================================
  Hits        35779    35779           
  Misses       1586     1586           
  Partials      657      657           

🚀 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-10 04:31:22 UTC}

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

⏸️ 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/**).

Review summary
This PR closes a real monitoring gap: the hand-duplicated gate-decision twin pair (src/rules/advisory.ts <-> packages/gittensory-engine/src/advisory/gate-advisory.ts) lives outside ENGINE_PARITY_AREAS (review/settings/signals), so discoverEngineParityPairs never scanned it before — the fix is at the right layer, not a symptom patch. The version-bump gate (checkGateDecisionVersionBump) correctly no-ops when neither or both twins are touched and requires either a matching edit or a semver bump on a single-sided change. Tests exercise real repo files (discoverGateDecisionTwinPair against process.cwd()) plus realistic injected fixtures for the pure functions, not fabricated impossible states, and CI is green with #4518 properly linked and scope matching the description.

Nits — 6 non-blocking

• scripts/check-engine-parity.ts: in runEngineParityChecks, if headEngineVersion resolves to null (unreadable/malformed package.json), the version-bump check is skipped entirely (changedFiles.length > 0 && headEngineVersion is falsy) rather than failing closed — low-likelihood in practice but worth a one-line comment or explicit failure for that path.
• scripts/check-engine-parity.ts has grown to ~529 lines with three largely independent concerns (drift diff, gate-decision twin presence/version-bump, version-skew/pin-sync); consider splitting the gate-decision logic into its own module for readability.
• checkGateDecisionTwinPresence only checks for marker substrings, not full normalized-body parity like checkEngineParityDrift does for the other twin pairs — worth a comment explaining why this pair intentionally gets a weaker check (version-bump escape hatch) instead of the stricter byte-diff comparison.
• listChangedEngineParityFiles falls back to `git merge-base ... origin/main` / `upstream/main` when GITTENSORY_ENGINE_PARITY_BASE_REF/GITHUB_BASE_SHA are unset — fine for GH Actions PR context but silently returns [] (and thus skips the version-bump check) in any environment lacking those remotes; a log/comment noting this is best-effort would help future debugging.
• Consider failing closed (i.e., treating unreadable head engine version as a bump-check failure) in runEngineParityChecks rather than skipping the check, to avoid an accidental full bypass of the tripwire this PR adds.
• Touches a guarded path — held for manual review — A maintainer must review and merge this change.

Signal	Result	Evidence
Code review	✅ No blockers	1 reviewer
Linked issue	✅ Linked	#4518
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: 314 registered-repo PR(s), 128 merged, 19 issue(s).
Contributor context	✅ Confirmed Gittensor contributor	RealDiligent; Gittensor profile; 314 PR(s), 19 issue(s).
Gate result	⚠️ Not blocking	Advisory; not blocking this PR.

Linked issue satisfaction

Addressed
The PR extends check-engine-parity.ts with an explicit GATE_DECISION_TWIN_PAIR covering src/rules/advisory.ts and packages/gittensory-engine/src/advisory/gate-advisory.ts, adds a checkGateDecisionVersionBump gate that fails PRs editing only one twin without a corresponding engine package.json version bump, and includes regression tests for single-sided failure, coordinated-edit pass, and version-b

Review context

• Author: RealDiligent
• 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: 314 PR(s), 19 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