Design proposal for #13.

Scope: implement this as a cache-first read feature on top of the existing PR comments collection before adding any speculative GitCode endpoint. The current adapter already reads GET /api/v5/repos/{owner}/{repo}/pulls/{number}/comments; #13 should make the payload richer, durable, and agent-friendly.

Architecture:

flowchart TD
  A["GitCode PR comments API"] --> B["gitcode.PRComment normalizer"]
  B --> C["BulkSyncPRComments"]
  C --> D["cache: pr_comment source + review metadata"]
  D --> E["service.ListPRDiscussions"]
  E --> F["CLI read command"]
  E --> G["MCP list_pr_discussions"]

Data shape:

erDiagram
  PULL_REQUEST ||--o{ PR_COMMENT : has
  PR_DISCUSSION ||--o{ PR_COMMENT : groups
  PR_COMMENT {
    string id
    string discussion_id
    string kind
    string body
    string author
    string path
    int line
    int start_line
    bool resolved
    string parent_id
  }

Proposed changes:

1. Extend gitcode.PRComment normalization to preserve optional review metadata when GitCode provides it: inline/general kind, path/file path, line/range/position fields, parent/reply id, resolvable/resolved state, author, timestamps, and discussion id.
2. Persist the metadata during BulkSyncPRComments so normal reads do not need live network access.
3. Add a service read API that returns discussions grouped by discussion_id, with fallback grouping for general comments that do not have a discussion id. Replies should stay in the same group through parent/discussion ids.
4. Add unresolved-only filtering. Because resolved may be absent from some GitCode payloads, use tri-state semantics internally: absent metadata should not be treated as resolved.
5. Expose the read through MCP as list_pr_discussions and through a CLI command with JSON output. Empty PR/comment state should return discussions: [].
6. Update docs with a sanitized public-safe example and note that inline path/line/resolution fields are present only when GitCode includes them.

Test plan:

• GitCode model/client fixture test for inline review comment metadata decoding.
• Service test for grouping replies under discussions and separating general vs inline comments.
• Service/MCP test for unresolved_only filtering and empty-state behavior.
• CLI test for JSON output shape.
• Regression test that existing PR comment sync still creates searchable pr_comment sources.

Main design choice: I would keep the live API surface narrow for this PR and avoid endpoint discovery churn. If later evidence shows GitCode has a better discussions endpoint than /pulls/{number}/comments, the provider can swap to it behind the same service/MCP contract.