feat(config): add review.fixHandoff toggle (default off) for fix-handoff blocks (#2176)

[nickmopen]

Closes #2176 (config slice for #1962).

A per-repo boolean under review that gates whether fix-handoff blocks are emitted, ANDed with a global env kill-switch and the convergence cutover allowlist. Default-off, byte-identical when unset. Follows the inline_comments toggle precedent exactly.

What's here

• focus-manifest.ts — fixHandoff: boolean | null on FocusManifestReviewConfig (mirrors inlineComments): normalizeOptionalBoolean parse, default null; reviewConfigToJson round-trip (omitted when null ⇒ byte-identical) + present + EMPTY literals.
• src/review/fix-handoff.ts — isFixHandoffEnabled(env) kill-switch (mirrors isInlineCommentsEnabled) + pure shouldEmitFixHandoff() ANDing manifest toggle + env flag + cutover allowlist (mirrors shouldRequestInlineFindings). No emission/render here — a separate slice — so the gate/verdict is untouched.
• Docs — review.fixHandoff in both .gittensory.yml.example and config/examples/gittensory.full.yml (the config-templates parity test enforces they match).

Validation

Ran the full suite locally (npm run test), not just focused tests:

Test Files  519 passed | 2 skipped (521)
     Tests  10349 passed | 7 skipped   (0 failed)

Typecheck clean. Covers config absent/true/false round-trip + non-boolean warn, the env kill-switch (truthy/falsy), and the resolver's three-way gate.

[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.41%. Comparing base (fd8b3da) to head (83b37f7).

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #3824   +/-   ##
=======================================
  Coverage   93.41%   93.41%           
=======================================
  Files         325      326    +1     
  Lines       32844    32848    +4     
  Branches    12030    12033    +3     
=======================================
+ Hits        30680    30684    +4     
  Misses       1530     1530           
  Partials      634      634           

Files with missing lines	Coverage Δ
src/review/fix-handoff.ts	100.00% <100.00%> (ø)
src/signals/focus-manifest.ts	99.12% <100.00%> (+<0.01%)	⬆️

🚀 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-06 13:25:53 UTC}

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

✅ Suggested Action - Approve/Merge

• safe to merge

Review summary
This PR adds a `review.fixHandoff` boolean toggle to the focus-manifest config, mirroring the existing `inlineComments` precedent exactly: `normalizeOptionalBoolean` parsing, byte-identical omission when null, and a pure `shouldEmitFixHandoff()` resolver that ANDs the manifest toggle, an env kill-switch, and the convergence cutover allowlist. All EMPTY/emptyManifest/test fixture literals were updated consistently across the touched files, and the new `fix-handoff.ts` module does not touch emission/render, so the gate/verdict path is untouched. The implementation is correct and well-tested, but the new config key is written as `fixHandoff` (camelCase) in both the parser (`r.fixHandoff`) and the two YAML example files, breaking the snake_case convention used by every sibling field in the same object (`inline_comments`, `security_focus`, `changed_files_summary`, `effort_score`, `test_generation`, `finding_categories`, etc.).

Nits — 5 non-blocking

• src/signals/focus-manifest.ts: the new field is parsed as `r.fixHandoff` and documented as `fixHandoff:` in .gittensory.yml.example and config/examples/gittensory.full.yml, breaking the snake_case convention every other `review.*` key follows (e.g. `inline_comments`, `security_focus`) — worth renaming to `fix_handoff` for config consistency even though it's internally self-consistent and byte-identical when unset.
• src/review/fix-handoff.ts:1-5: the large top-of-file comment restates what the type signatures and JSDoc below it already say; could be trimmed since the per-function JSDoc already covers the AND semantics.
• src/signals/focus-manifest.ts:345 embeds the issue number `2176` in a doc comment only — fine as a reference but not something that needs a named constant.
• Rename the YAML/parsed key from `fixHandoff` to `fix_handoff` in src/signals/focus-manifest.ts, .gittensory.yml.example, config/examples/gittensory.full.yml, and the corresponding test fixtures, to match the snake_case convention of every other `review.*` toggle.
• Consider a brief note in the fix-handoff.ts header pointing directly at `shouldRequestInlineFindings` (the mirrored precedent) so future readers can diff the two resolvers side by side.

Signal	Result	Evidence
Code review	✅ No blockers	1 reviewer
Linked issue	✅ Linked	#2176
Related work	⚠️ 2 scoped overlaps	Top overlaps are listed below; lower-confidence bulk is hidden.
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: 133 registered-repo PR(s), 90 merged, 0 issue(s).
Contributor context	✅ Confirmed Gittensor contributor	nickmopen; Gittensor profile; 133 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 is configured for direct PR review.
• Public profile languages: TypeScript
• Official Gittensor activity: 133 PR(s), 0 issue(s).
• Related work: Titles/paths share 8 meaningful terms. (issue #2189, issue #2184)
• Related work: Titles/paths share 6 meaningful terms. (issue #2184, issue #2182)

Contributor next steps

• Review top overlaps.
• Add a concise scope and risk note.
• Check active issues and PRs before submitting.

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 approves — the gate is satisfied and CI is green.