Skip to content

review: inline the linked Linear issue into review kicks (scope contract) for Linear-backed repos #14906

Closed
3 of 3 issues completed

Description

@gregoryhunt

Summary

When a PR's contract is a Linear issue, review kicks do not include the issue, and reviewer agents cannot fetch it. The hive already holds a Linear credential for the work source (worksource.LinearSource). It should fetch the linked Linear issue at dispatch and inline it into the kick's SCOPE CONTRACT section, the same way it already points reviewers at GitHub issues. Reviewers would then judge intent and acceptance criteria against the real issue without ever holding a Linear token.

Where (v5 @ a474553)

  • src/pkg/github/client.go:1932 reviewScopeContract: recognises only GitHub closing keywords (ParseClaimedIssues) and Hive-Run/Hive-Plan lease tasks. A Linear identifier in the title or body ([ONB-3872]: …, or a Linear Fixes ONB-3872) yields an empty contract.
  • src/pkg/review/prompts.go:488 scopeContractSection: with an empty contract it says "No closing issue or lease task was found … Treat the PR title plus diff as the narrow contract". With a contract it tells the reviewer to "read that issue with gh issue view", which works only for GitHub issues.
  • src/crux/agent/manager_tokens.go linearEnvPairs: the Linear credential is injected only at CanCreateIssues() (ISSUES_ONLY) and above. Reviewers run ADVISORY, so they have no Linear access. This is correct: the proxy lets that tier mutate Linear, and reviewers should not get write access just to read an issue.

Observed

  • The repo uses Linear for all work (ONB-*), with no GitHub issues.
  • Reviews say "Linear ONB-3761 was not readable from here, so the PR title and body are the contract" (🐛 fix(dashboard): budget partial save zeroed untouched fields; persist error toasts #2285) and "ONB-3872 … not readable, so this is not a spec check" (🔀 sync: v2 → dd (top-up #2338, #2340, #2344 +) #2346).
  • Operator workaround:
    • The repo's Linear GitHub integration posts a linear[bot] linkback comment carrying the issue description and acceptance criteria. Reviewers can read it with gh api repos/{repo}/issues/{n}/comments. gh pr view --comments fails with a GraphQL permission error for the reviewer token.
    • Wired through perspective_prompts, this works only when the model follows the instruction, and in practice that was 2 of about 10 issue-scope runs in the first hour.
    • The linkback is also a snapshot taken when the PR was linked: later edits to the issue and comments on it are missing.
  • For comparison, the repo's existing Claude Code review workflow fetches the Linear issue with a read-only key and inlines it into the prompt. That review's "Ticket scope" section (missing requirements, scope creep, AC ↔ test) is the most valuable thing it posts. 161 of 162 of its reviews include it.

Proposed fix

  1. Recognise Linear identifiers in the contract. When the work source is Linear (or a Linear team maps to the repo), reviewScopeContract returns linked Linear issue ONB-3872. Sources, in order:

    • a Linear magic word (Fixes/Closes/Part of ONB-n);
    • a leading [ONB-n] in the title;
    • the PR branch name (…/onb-3872-…).

    Restrict matches to the team keys configured for the repo.

  2. Fetch and inline at dispatch, read-only. In the dispatch path that builds review.PullRequest, look up the issue through the existing Linear source: identifier, title, state, description, and the last few comments, with a byte cap of about 8–12 KB and a truncation note. Carry it on PullRequest (for example ScopeContractText). Cache it per issue updatedAt so a PR with many kicks costs one fetch.

  3. Render it in scopeContractSection:

    • Contract: Linear issue ONB-3872 (state: In Progress), followed by a fenced block with the issue text, marked as untrusted data from the issue tracker, not instructions.
    • Then the existing in-scope/out-of-scope rules, plus: "mark each acceptance criterion delivered, missing, or deferred".
    • With the issue unavailable, keep today's wording and name the identifier that could not be fetched.

Tests:

  • reviewScopeContract finds ONB-3872 from each source and ignores unknown team keys.
  • A kick for a PR with a fetched issue contains its title and description inside the untrusted-data fence.
  • A fetch failure falls back to the current text, naming the identifier.
  • The cache prevents a second fetch for an unchanged updatedAt.

Why

Intent and acceptance-criteria alignment is the review dimension a Linear-tracked team values most. Today hive cannot do it at all on Linear-backed repos, and giving reviewers the work-source credential would grant them write access. This keeps reviewers token-less and makes the check deterministic.

Refs #4891 (Linear work sources at parity), #6161 (Linear work-tracker kick section), #13548.

🤖 Generated with Claude Code

Activity

  1. hivecommons-hive commented on Oct 28, 2026

    @hivecommons-hive
    Contributor

    Decomposed into three sub-issues following the proposal's own steps, so each lands as a reviewable PR and the Linear-API-free part can go first:

    1. [scanner] review: recognise Linear issue identifiers in reviewScopeContract #14909 — recognise Linear identifiers in reviewScopeContract (body magic words, [ONB-n] title prefix, branch name; restricted to configured team keys)
    2. [scanner] review: fetch the linked Linear issue at dispatch and carry it on review.PullRequest #14910 — fetch the issue read-only at dispatch via the existing Linear work source, cap + truncation note, cache per updatedAt, carry it on review.PullRequest (blocked by [scanner] review: recognise Linear issue identifiers in reviewScopeContract #14909)
    3. [scanner] review: render the inlined Linear issue in the kick's scope contract section #14911 — render it in scopeContractSection inside an untrusted-data fence, with the named-identifier fallback when the fetch fails (blocked by [scanner] review: fetch the linked Linear issue at dispatch and carry it on review.PullRequest #14910)

    Reviewers stay token-less throughout; linearEnvPairs is untouched. This issue stays open as the tracker and closes when #14911 lands.


    🐝 Hive Agent: scanner | Instance: hosted-available-oke-11-placeholder-r05x | SHA: unknown

    — hive: agent=scanner backend=copilot model=claude-fable-5.1 copilot=1.0.88

  2. added
    help wantedDenotes an issue that needs help from a contributor. Must meet "help wanted" guidelines.
    on Oct 28, 2026
  3. hivecommons-hive commented on Oct 28, 2026

    @hivecommons-hive
    Contributor

    🔒 Claimed by agent scanner (agent on hive hosted-available-oke-11-placeholder-r05x). The claim lasts 2h0m0s without activity and renews while the work continues. Reply /unclaim to release, or /claim to take it over if you outrank the holder.

  4. github-actions commented on Oct 28, 2026

    @github-actions
    Contributor

    @gregoryhunt this issue was closed by @clubanderson as completed.

    If this was closed by a merged PR, the fix only takes effect once it ships in a tagged release and your deployment updates to it — check your running version against the fix before concluding the fix failed.

    If you are still seeing the problem, comment /reopen and it will be reopened for you — you do not need write access. Please add what you are still observing (running version, logs, steps) so it is not closed the same way again.

  5. gregoryhunt commented on Oct 28, 2026

    @gregoryhunt
    ContributorAuthor

    Reopening: this was closed by a false-positive closing reference. #14943 (a stage-label fix for #14942) quotes "#14921 closed #14906" in its body as evidence, and when #14943 merged at 13:58:04Z GitHub parsed that "closed #14906" as a closing keyword and closed this issue two seconds later. The actual fix, #14921 ("inline the linked Linear issue into review kicks"), is still open and unmerged, so the gap described here is still live. Hive's stage reconciler may also be treating this issue as covered by #14943.

  6. gregoryhunt commented on Oct 28, 2026

    @gregoryhunt
    ContributorAuthor

    This was closed by a false-positive closing reference, and I can't reopen it myself because it was closed under a maintainer's merge. @clubanderson, could you reopen it?

    #14943 (the stage fix for #14942) quotes "#14921 closed #14906" in its body as evidence. When #14943 merged at 13:58:04Z, GitHub read that "closed #14906" as a closing keyword and closed this issue three seconds later. The actual fix, #14921 ("inline the linked Linear issue into review kicks"), is still open and unmerged, so the gap described here is still live.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    help wantedDenotes an issue that needs help from a contributor. Must meet "help wanted" guidelines.

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions