fix(productivity-review): regenerate description when trigger flips (BLO-22105)

[kkroo]

Thinking Path

• Paperclip is the open-source application people use to manage AI agents for work.
• The productivity-review service creates a review issue when an agent's runs on a source issue look unhealthy, and its durable ## Manager Decision guidance depends on the current primary trigger.
• fix(productivity-review): exclude never-executed runs from no_comment_streak (BLO-21769) #1041 made that guidance trigger-conditional: runtime_failure_streak has an infrastructure remedy menu, while no_comment_streak and related productivity triggers have the productivity menu.
• The ordinary refresh path historically appended evidence but did not regenerate the persisted description, so a trigger flip could leave a reviewer seeing guidance for the wrong condition.
• This independent successor to App-authored fix(productivity-review): regenerate description on refresh when trigger flips (BLO-22105) #1135 preserves its fix: refresh the description only when the persisted trigger differs from the live trigger, without bypassing the refresh floor or overwriting a concurrent manager edit.
• The result keeps Manager Decision guidance consistent with the live evidence while retaining the existing write-throttling and human-edit protections.

Linked Issues or Issue Description

• Fixes: BLO-22105 — a trigger flip on an open productivity review could leave stale Manager Decision guidance in its persisted description.
• Supersedes App-authored fix(productivity-review): regenerate description on refresh when trigger flips (BLO-22105) #1135; that original remains untouched because it cannot satisfy the independent App-review lane.
• GitHub duplicate search found fix(productivity-review): regenerate description on refresh when trigger flips (BLO-22105) #1135 (the intended predecessor) and fix(productivity-review): exclude dependency-gate cancellations from streak, skip blocked issues (BLO-22436) #1158 (a separate BLO-22436 change); neither duplicates this successor.

What Changed

• Added trigger extraction from the persisted review description and regenerate it only when a known, live trigger differs.
• Kept the existing hard refresh interval as the write gate; the refresh-comment cap now limits comment churn without preventing a stale description from being corrected.
• Guarded the description update with its previously-read value so a concurrent manual edit is preserved instead of clobbered.
• Added regression coverage for both trigger directions, unchanged triggers, the comment-cap path, and a concurrent manual-description edit.

Verification

• pnpm --filter @paperclipai/server typecheck
• pnpm --filter @paperclipai/server exec vitest run src/__tests__/productivity-review-service.test.ts -t 'BLO-22105: refresh regenerates the description on a trigger flip'
• Reviewed the exact current PR diff and checked GitHub for related pull requests before marking this independent successor ready.

Risks

• Low risk: no schema or migration change, and updates remain subject to the existing refresh floor.
• An unexpected or hand-edited description format is left unchanged rather than guessed at; that favors avoiding an unsafe overwrite over forcing a rewrite.
• A genuine concurrent human edit wins the guarded update race; the description can then be reconsidered on a later refresh rather than overwriting the manager's text.

Model Used

• OpenAI Codex (GPT-5), coding-agent runtime with code execution and GitHub tooling; context-window details are platform-managed and not exposed by this runtime.

Checklist

• I have included a thinking path that traces from project context to this change
• I have specified the model used (with version and capability details)
• I have checked ROADMAP.md and confirmed this PR does not duplicate planned core work
• I have searched GitHub for duplicate or related PRs and linked them above
• I have either (a) linked existing issues with Fixes: # / Closes # / Refs # OR (b) described the issue in-PR following the relevant issue template
• I have run tests locally and they pass
• I have added or updated tests where applicable
• If this change affects the UI, I have included before/after screenshots — n/a, no UI changes
• I have updated relevant documentation to reflect my changes — n/a
• I have considered and documented any risks above
• All Paperclip CI gates are green — pending on this metadata-trigger push
• Greptile is 5/5 with no open P2s, recommendations, or follow-ups
• I will address all Greptile and reviewer comments before requesting merge

[cursor]

Bugbot is not enabled for your account, so this pull request was not reviewed.

Enable Bugbot in the Cursor dashboard to get automatic reviews on future PRs.

[kkroo]

@ally please review exact head dc35a8d. Successor to #1135.

[allyblockcast]

Hey @kkroo! Before this PR can be reviewed, a few things need attention:

Missing or incomplete:

• Missing section: ## Thinking Path
• Missing section: ## What Changed
• Missing section: ## Verification
• Missing section: ## Risks
• Missing section: ## Model Used
• Add the dedup-search checkbox to your PR description and check it once you have searched the GitHub PR list for similar PRs. See the PR template at .github/PULL_REQUEST_TEMPLATE.md and CONTRIBUTING.md → "Before You Start: Search First".

Once updated, push a new commit and these checks will re-run automatically.

— commitperclip

[kkroo]

@ally please review exact head 787acdf. Corrected required PR metadata; server typecheck and BLO-22105 regressions (5/5) pass.

[allyblockcast]

Ally — Consolidated PR Review

Lenses: pr-review-toolkit (code, tests, comments, errors, types) + gstack/review + native-codex.
Reviewed head: 787acdf

Critical Issues (0)

Important Issues (1)

• [native-codex] server/src/services/productivity-review.ts:2588 — The hard refresh interval stops working after maxRefreshComments is reached. latestCreatedAt can no longer advance because comments are suppressed, so lastRefreshAt remains at the final comment forever. The first post-cap flip is allowed as intended, but every subsequent trigger flip is also allowed immediately, even when less than effectiveRefreshIntervalMs apart; a flapping runtime can therefore rewrite the review description on every scheduler pass, contrary to the stated write-throttling guarantee.
  • Advance a durable refresh timestamp for a post-cap description rewrite (or include the review's current updatedAt when computing the floor), and add a regression test with two post-cap flips less than the refresh interval apart.

Suggestions (0)

Strengths

• The guarded description update correctly avoids clobbering a concurrent edit.
• The added coverage exercises both trigger directions and the comment-cap behavior.

Recommended Action

1. Address the Important issue this cycle.