Stale comments: improvementSignal is described as unwired/test-only but is actually a live caller in processors.ts

[JSONbored]

Context

improvementSignal (epic #4737, config-as-code foundation #4738) is now a fully wired, live converged feature — but four module header/doc comments still describe it as inert/never-called, which is no longer true and actively misleads anyone reading the code to understand the feature's current state.

1. src/review/improvement-signal-wire.ts (module header, lines 1-8) currently reads:

"This PR wires activation only: nothing calls resolveConvergedFeature(env, manifest, "improvementSignal", repoFullName) yet outside this feature's own tests."

This is false today. src/queue/processors.ts:7821 calls convergedFeatureActive(env, repoFullName, "improvementSignal") — the async wrapper around exactly that resolveConvergedFeature call (see src/review/feature-activation.ts's convergedFeatureActive) — and its result (improvementSignalAllowed) is used at src/queue/processors.ts:9361 (improvementSignal: improvementSignalAllowed, passed into the AI-review options) and src/queue/processors.ts:10062-10068 (gates a real call to buildStructuralImprovementAssessment).

2. src/signals/improvement.ts (module header, lines 8-11) currently reads:

"Activation wiring already exists (#4738/#4753: isImprovementSignalEnabled + the improvementSignal ConvergedFeatureKey) but nothing calls resolveConvergedFeature for it yet, and this module is not an exception — it is a pure, standalone computation consumed only by its own tests until the panel-surfacing sub-issue (#4744) wires a caller."

Also false: buildStructuralImprovementAssessment (defined at src/signals/improvement.ts:112) is imported and called by src/queue/processors.ts:478 (import) / :10063 (call site), gated by the same improvementSignalAllowed. #4744 ("PR panel: new advisory improvement-signal section") is itself closed, consistent with this wiring now existing.

3. src/services/ai-review.ts (doc comment on the improvementSignal?: boolean field, ~lines 322-334) currently reads:

"Absent/false (the default, and the only reachable value until a caller starts resolving the feature) ⇒ no instruction is appended and the model is never asked"

Also false in the same way — processors.ts:9361 is a real caller that resolves the feature and can pass true.

4. packages/loopover-engine/src/focus-manifest.ts (comment directly above the CONVERGED_FEATURE_KEYS array, ~lines 263-267) currently reads:

"improvementSignal (#4738, foundation phase of the #4737 PR-improvement-signal epic) is likewise a plain symmetric override... This is activation wiring only -- no tier reads the resolved value yet (sibling sub-issues #4739-#4746 build the deterministic/LLM/panel behavior that will gate on it)."

Same false claim as the other three — processors.ts already reads the resolved value (see point 1).

None of the underlying LOGIC is wrong or needs to change — resolveFeatureActivation, resolveConvergedFeature, and buildStructuralImprovementAssessment all behave correctly today. This is purely a documentation-drift bug: four comments describing a "not wired yet" state that shipped and closed out (epic #4737 and its sub-issues #4738-#4746 are all closed) without the comments being updated to match.

Requirements

1. Update src/review/improvement-signal-wire.ts's module header comment to state that the feature IS resolved and consumed, citing src/queue/processors.ts as the real caller (via convergedFeatureActive), instead of claiming no caller exists outside tests.
2. Update src/signals/improvement.ts's module header comment the same way — remove or correct the "nothing calls resolveConvergedFeature for it yet" / "consumed only by its own tests" claims, and note that buildStructuralImprovementAssessment is now called from src/queue/processors.ts.
3. Update src/services/ai-review.ts's doc comment on the improvementSignal?: boolean field to remove the "the only reachable value until a caller starts resolving the feature" claim, since processors.ts is now that caller.
4. Update packages/loopover-engine/src/focus-manifest.ts's comment above CONVERGED_FEATURE_KEYS to remove the "no tier reads the resolved value yet" claim about improvementSignal, for the same reason.
5. Do NOT touch the parts of these comments that are still accurate and unrelated to activation-wiring status (e.g. improvement.ts's explanation of why complexityDeltas/duplicationDeltas/patchCoverageDeltaPercent still have no live data source — that specific sub-claim is independently still true today and must be left as-is; only the "is this module/feature wired to a caller" claim is stale).
6. This is a comment-only change — no runtime behavior, exports, types, or function signatures in any of the four files may change.

Deliverables

• src/review/improvement-signal-wire.ts header comment corrected.
• src/signals/improvement.ts header comment corrected.
• src/services/ai-review.ts improvementSignal field doc comment corrected.
• packages/loopover-engine/src/focus-manifest.ts comment above CONVERGED_FEATURE_KEYS corrected.

Test Coverage Requirements

This is a documentation-only change (comments, no code paths altered), so no new test coverage is required. Run the existing test suite to confirm nothing else was inadvertently changed; the Codecov patch gate does not apply to comment-only diffs (no executable lines touched).

Expected Outcome

All four comments accurately describe improvementSignal as a live, wired feature with src/queue/processors.ts as its real caller, matching the code that has been true since epic #4737's sub-issues (#4738-#4746) closed. A future reader of any of these four files no longer gets misled into thinking the feature is dormant/test-only.

Links & Resources

• src/review/improvement-signal-wire.ts (module header)
• src/signals/improvement.ts (module header, buildStructuralImprovementAssessment at line 112)
• src/services/ai-review.ts (improvementSignal?: boolean field doc comment, ~lines 322-334)
• packages/loopover-engine/src/focus-manifest.ts (comment above CONVERGED_FEATURE_KEYS, ~lines 263-267)
• src/review/feature-activation.ts (convergedFeatureActive, the real resolution path)
• src/queue/processors.ts (the real caller: line 7821 convergedFeatureActive(...), line 9361 improvementSignal: improvementSignalAllowed, lines 10062-10068 buildStructuralImprovementAssessment(...) call)
• Epic Epic: PR improvement signal — quality-delta scoring as the positive-axis counterpart to slop-risk #4737 and sub-issues Config-as-code foundation: improvementSignal as a converged feature (global + per-repo) #4738-MCP pre-submit value-potential tool #4746 (all closed — the work these comments describe as "not yet done" already shipped)

[linear-code]

JSO-4491

[JSONbored]

Found a 4th instance of the same stale claim while auditing a neighboring file:

packages/loopover-engine/src/focus-manifest.ts (comment directly above CONVERGED_FEATURE_KEYS, ~lines 263-267) currently reads:

"improvementSignal (#4738, foundation phase of the #4737 PR-improvement-signal epic) is likewise a plain symmetric override... This is activation wiring only -- no tier reads the resolved value yet (sibling sub-issues #4739-#4746 build the deterministic/LLM/panel behavior that will gate on it)."

Same issue as the other three: src/queue/processors.ts is now a real caller (see the Context section above), so "no tier reads the resolved value yet" is stale. Please correct this comment as part of the same change — it documents the identical fact as the other three and should be fixed together so all four stay consistent.