# Linked Issue Hydration Fix Design

## Problem

`gh pr view --json closingIssuesReferences` returns lightweight issue references containing fields such as `number`, `url`, and `repository`. It does not guarantee embedded `title` or `body` fields. Version 0.1.0 parses each reference as a complete issue and therefore throws `gh response is missing string field title` for PRs that close an issue.

This is independent of repository visibility. GitHub CLI authentication already provides access to private PR and issue data when the logged-in account has permission.

## Scope

Fix linked-issue parsing and hydration only. Do not add draft review, new authentication settings, GraphQL integration, or unrelated GitHub adapter refactoring.

## Data Flow

1. Parse PR metadata and `closingIssuesReferences` as lightweight references.
2. Extract each reference's issue number, URL, and repository owner/name.
3. If the PR is closed or draft, do not hydrate linked issues or fetch the diff; return the existing skip result inputs.
4. For an open, non-draft PR, hydrate references with:

   ```text
   gh issue view <number> --repo <owner>/<repo> --json number,title,body,url
   ```

5. Limit linked-issue hydration to four concurrent `gh` processes.
6. Preserve reference order in the final `linkedIssues` array.

Same-repository references use the repository returned by the reference. Cross-repository references use their own repository identity and therefore work when the active `gh` account can access that repository.

## Failure Behavior

Linked issue bodies are required inputs for task-objective review. If an explicitly linked issue cannot be hydrated, fail closed before model work with an error that identifies the exact issue:

```text
Unable to load linked issue Sirfetch-d/packageauth#261: <gh diagnostic>
```

Do not silently continue with incomplete task context. Do not expose authentication tokens or environment variables.

Malformed references fail with field-specific paths, such as `closingIssuesReferences[0].repository.owner.login`, instead of the ambiguous `missing string field title` error.

## Testing

Add regression coverage for:

- A lightweight same-repository reference without embedded title/body, followed by successful `gh issue view` hydration.
- Multiple linked issues hydrated with stable output order.
- Hydration failure reporting the repository and issue number.
- A draft PR returning without diff or issue hydration calls.
- Existing PRs without linked issues retaining their current process call sequence and result.

All tests use injected process runners and make no real GitHub mutations.

## Release

Record the fix in `CHANGELOG.md`, bump the package and runtime marker from `0.1.0` to `0.1.1`, regenerate `package-lock.json` with lifecycle scripts disabled, and publish only after checks, tests, package verification, and a real read-only run against packageauth PR #262 succeed. Because PR #262 is currently draft, that live run must verify clean skip behavior without issue hydration; linked-issue hydration itself is verified with tests or after the PR becomes ready for review.