feat(config): add review.linkedIssueSatisfaction knob (off/advisory/block, default off) (#2173)

[nickmopen]

Closes #2173 (config slice for #1961).

Wires the review.linkedIssueSatisfaction config-as-code knob through the FocusManifestReviewConfig parse path only — parse + normalize + default-off. Default null (unset) ⇒ byte-identical to today. It deliberately does not touch the merge/close decision; that maintainer-only slice reads the resolved mode separately.

What's here

• focus-manifest.ts — LinkedIssueSatisfactionMode ('off' | 'advisory' | 'block') + linkedIssueSatisfaction on FocusManifestReviewConfig; parsed with the shared normalizeOptionalEnum (warn + ignore on malformed), default null; reviewConfigToJson round-trip (omitted when null ⇒ byte-identical) + present + the EMPTY literals.
• .gittensory.yml.example — documented the knob (distinct from the existing linkedIssuePolicy, which only checks a link exists; this is about whether it's satisfied).

Validation

Typecheck clean. Focused suites green (incl. the documents review.* doc-parity test that enforces the .gittensory.yml entry, and the updated review-config literals):

Test Files  3 passed (3)
     Tests  485 passed (485)

Tests cover: absent → null (omitted on serialize), each valid mode round-trips + marks present, and malformed / non-string → warn + null.

[superagent-security]

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

[loopover-orb]

Caution

🟥🟥🟥🟥🟥🟥🟥🟥🟥🟥🟥🟥

🛑 Gittensory review result - fixes required

_{Review updated: 2026-07-06 00:14:06 UTC}

5 files · 1 AI reviewer · no blockers · readiness 62/100 · CI failing · blocked

🛑 Suggested Action - Fix Blockers

Review summary
This wires a new `review.linkedIssueSatisfaction` config-as-code knob through the focus-manifest parse path only (parse via `normalizeOptionalEnum`, `present` calc, `reviewConfigToJson` round-trip), explicitly deferring the actual gate/merge-decision logic to a separate slice per the PR description. The change is mechanical and follows the exact pattern used for other optional-enum review fields, default `null` is omitted on serialize (byte-identical when unset), and tests cover absent/valid/malformed/non-string cases plus the doc-parity test. One inconsistency: the new key is read/written as camelCase (`r.linkedIssueSatisfaction`, yml key `linkedIssueSatisfaction:`) while every sibling review key in the same file uses snake_case (`labeling_rules`, `ai_model`), which is self-consistent but breaks the established config-key convention.

Nits — 5 non-blocking

• src/signals/focus-manifest.ts:1655 and .gittensory.yml.example:756 — the new key is camelCase (`linkedIssueSatisfaction`) while every other `review.*` key in this file is snake_case (`labeling_rules`, `ai_model`, `pre_merge_checks`); this is internally consistent (parser key matches example key) but inconsistent with the file's established naming convention and could confuse users writing config by pattern-matching neighboring keys.
• The doc comment on `FocusManifestReviewConfig.linkedIssueSatisfaction` (focus-manifest.ts:381-384) embeds the issue number `feat(config): add review.linkedIssueSatisfaction config knob (off/advisory/block, default off) #2173` inline rather than as a named constant, per the magic-number scan — minor, but consider a shared comment convention for future config-slice PRs.
• Rename the yml example key and the `r.linkedIssueSatisfaction` read to snake_case (`linked_issue_satisfaction`) to match `labeling_rules`/`ai_model`/etc., unless there's a documented reason review-config keys are transitioning to camelCase.
• Since this is explicitly a config-slice PR with the gate logic deferred, confirm the tracking issue (AI linked-issue satisfaction assessment #1961) for the actual merge/close wiring is referenced somewhere discoverable (e.g., a follow-up TODO or issue link) so the deferred half doesn't get lost.
• Readiness score is below the configured threshold — Use the readiness panel as advisory maintainer context; the score does not block this PR.

CI checks failing

• validate
• validate-code

Signal	Result	Evidence
Code review	✅ No blockers	1 reviewer
Linked issue	✅ Linked	#2173
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	❌ 5/25	Preflight is holding this PR: the review lane is unavailable, so it is not ready for automated review.
Contributor workload	✅ 10/10	Author activity: 129 registered-repo PR(s), 86 merged, 0 issue(s).
Contributor context	✅ Confirmed Gittensor contributor	nickmopen; Gittensor profile; 129 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 registration is not available in the local Gittensory cache.
• Public profile languages: TypeScript
• Official Gittensor activity: 129 PR(s), 0 issue(s).
• Related work: Titles/paths share 8 meaningful terms. (issue #2189, issue #2184)
• Related work: Titles/paths share 5 meaningful terms. (issue #2189, issue #1681)

Contributor next steps

• Review top overlaps.
• Add a concise scope and risk note.
• Await review-lane availability.
• Refresh registry data or choose a registered active repo.
• 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

[codecov]

❌ 1 Tests Failed:

Tests completed	Failed	Passed	Skipped
9787	1	9786	7

View the top 1 failed test(s) by shortest run time

test/unit/config-templates.test.ts > config/examples review templates (#1682) > gittensory.full.yml body matches .gittensory.yml.example from WHERE IT LIVES onward

Stack Traces | 0.018s run time

AssertionError: expected '# WHERE IT LIVES (first match wins):\…' to be '# WHERE IT LIVES (first match wins):\…' // Object.is equality

- Expected
+ Received

@@ -737,16 +737,10 @@
  #   # When true, an inline finding is ALSO tagged with a category (security/correctness/performance/
  #   # maintainability/tests/style) -- the AI reviewer self-categorizes, with a deterministic path/keyword
  #   # fallback for whatever it omits. Only takes effect when inline_comments is already on. Bool or null.
  #   # Default: null/false.
  #   finding_categories: false
- #   # How strictly a linked issue must actually be SATISFIED by the PR (distinct from linkedIssuePolicy,
- #   # which only checks a link EXISTS). off = not evaluated; advisory = surface a finding; block = can
- #   # become a hard blocker (confirmed-contributor-gated). This is the config knob only — parsed and
- #   # normalized here; the merge/close decision that reads it is a separate maintainer slice.
- #   # off | advisory | block. Default: off (byte-identical when unset).
- #   linkedIssueSatisfaction: off
  #   # Maintainer-declared DETERMINISTIC content assertions (title/description must contain a phrase, a
  #   # label must be present), optionally gated to a path glob. A failed check is advisory by default;
  #   # `enforce: true` makes it a hard gate blocker. Empty/default ⇒ no finding (no AI judgment involved).
  #   pre_merge_checks:
  #     - name: "require a linked issue reference in the description"

 ❯ test/unit/config-templates.test.ts:34:57

To view more test analytics, go to the Test Analytics Dashboard
_{📋 Got 3 mins? Take this short survey to help us improve Test Analytics.}

[loopover-orb]

Gittensory is closing this pull request on the maintainer's behalf (CI is failing (validate, validate-code)). 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.