mach12:gh-issue-read

Read GitHub Issue

Goals

• Return the caller an authoritative issue snapshot containing the parent metadata and complete chronological comment stream.
• When requested, identify the most recent matching marker comment and its numeric ID without weakening completeness checks.
• Make incomplete or malformed history explicit rather than presenting partial evidence as authoritative.

This subroutine is gh-specific. A future forge-agnostic command set would substitute an equivalent glab-issue-read (or similar); the marker-hunt logic stays the same.

Step 1: Parse input

Extract:

• The issue number (required, first token).
• An optional --marker <html-marker> flag naming an HTML comment marker to locate (e.g., --marker mach12-plan, --marker mach12-decisions).
• An optional --repo <owner/repo> flag identifying a canonical public GitHub repository to read instead of the checkout repository. Accept only a validated owner/repo identity; reject malformed, non-canonical or inaccessible targets rather than falling back to the checkout.

If no issue number is present, return an error to the caller and stop.

Step 2: Read the issue and complete comment stream

When --repo is omitted, resolve the canonical owner/name with gh repo view --json nameWithOwner. When supplied, resolve gh repo view <owner/repo> --json nameWithOwner,url, require a canonical https://github.com/<owner>/<repo> URL and verify that the returned identity matches the requested owner/repo (GitHub identity comparison is case-insensitive). Use this resolved owner and name, never the checkout's defaults, for repository(owner:$owner,name:$name) in the gh api graphql --paginate query. Pass explicit variables for owner, name, issue number, and $endCursor. Request parent title, body, createdAt, updatedAt, and:

comments(first: 100, after: $endCursor) {
  totalCount
  nodes { databaseId body author { login } authorAssociation createdAt url }
  pageInfo { hasNextPage endCursor }
}