Community Repo Resolver: GitHub Issue Ingestion, Resolution & Convergence Management
1. Executive Summary
This architectural specification defines the integration of GitHub issue ingestion, lifecycle management, resolution tracking, and policy-driven convergence steering directly into the community repo resolver subsystem (pkg/community).
The repo resolver orchestrates automated repository convergence, validating that code, pipeline telemetry, and external defect tracking align with operational stability invariants. By embedding GitHub issue ingestion and resolution tracking natively into RepoResolverConvergenceSession, active critical issues (such as blocking bugs or regressions) directly influence pipeline convergence evaluations, preventing premature cycle advancement while prescribing targeted triage actions.
2. Component Architecture & Integration Topology
graph TD
GH["GitHub Repository Issues API"] -->|"IngestGitHubIssue(s)"| RRCS["RepoResolverConvergenceSession"]
CI["Pipeline Telemetry Engine"] -->|IngestMetrics| RRCS
subgraph "Repo Resolver Convergence Engine"
RRCS --> IM["Issue Store & Index (s.Issues)"]
RRCS --> RM["Resolution Store (s.Resolutions)"]
RRCS --> TM["Pipeline Tracking Matrix"]
IM --> EV["Convergence Evaluator (EvaluateConvergence)"]
RM --> EV
TM --> EV
EV --> PolAdv["PolicyActionAdvanceCycle"]
EV --> PolTri["PolicyActionTriageFailures"]
EV --> PolRet["PolicyActionRetryFlaky"]
end
EV --> Out["Convergence Evaluation & Steering Decision"]
2.1 Core Architectural Principles
- Thread-Safe In-Memory State: All issue ingestion, resolution lookups, and evaluations are governed by
sync.RWMutex, providing sub-millisecond retrieval and concurrent mutation safety. - Defect-Aware Convergence Gate: A 100% successful build or test pipeline does NOT imply release readiness if unresolved critical or blocking defects exist. Pending critical issues actively suppress
PolicyActionAdvanceCycleand triggerPolicyActionTriageFailures. - Audit-Grade Resolution Trajectory: Resolutions record target commit hashes, outcome classifications (
resolved,deferred,duplicate,wontfix), and timestamps, ensuring complete lineage from issue intake to code remediation. - Deterministic Ordering: All listing methods (
ListPendingGitHubIssues,ListResolvedGitHubIssues) return slices sorted deterministically byIssueNumberascending.
3. GitHub Issue Lifecycle & State Machine
stateDiagram-v2
[*] --> IngestedOpen: IngestGitHubIssue (State: open)
[*] --> IngestedClosed: IngestGitHubIssue (State: closed)
IngestedOpen --> Deferred: ResolveGitHubIssue (status: deferred)
Deferred --> Resolved: ResolveGitHubIssue (status: resolved)
IngestedOpen --> Resolved: ResolveGitHubIssue (status: resolved)
IngestedOpen --> Duplicate: ResolveGitHubIssue (status: duplicate)
IngestedOpen --> WontFix: ResolveGitHubIssue (status: wontfix)
Resolved --> [*]
Duplicate --> [*]
WontFix --> [*]
IngestedClosed --> [*]
State Transitions & Convergence Invariants
IngestedOpen: An issue ingested withState == "open". If labeledcritical,blocker,p0,p1,security, orbug, it immediately registers as a pending critical defect inCountPendingCriticalIssues().Deferred: An issue resolved withResolutionStatus == "deferred". The resolution is recorded for auditability, but the issue remains pending inListPendingGitHubIssues().Resolved/Duplicate/WontFix: Terminal resolutions. Transitions the issue state toState == "closed", populatesClosedAt, and immediately unblocks convergence evaluation once all critical issues reach resolution.
4. End-to-End Sequence Diagram
sequenceDiagram
participant GH as GitHub Webhook / Poller
participant Resolver as RepoResolverConvergenceSession
participant CI as Pipeline Runner
participant TPM as TPM / Agentic Swarm
Note over GH,Resolver: 1. Issue Ingestion
GH->>Resolver: IngestGitHubIssue(#101, "Kernel leak", labels: ["critical"])
Resolver-->>GH: Accepted (Tracked in s.Issues)
Note over CI,Resolver: 2. Pipeline Execution
CI->>Resolver: IngestMetrics(build=success, unit-test=success)
Note over TPM,Resolver: 3. Convergence Evaluation (Blocked)
TPM->>Resolver: EvaluateConvergence()
Resolver-->>TPM: Status: ActionRequired, Action: triage_pipeline_failures<br/>(Blocked: 1 critical issue pending)
Note over TPM,Resolver: 4. Defect Remediation & Resolution
TPM->>Resolver: ResolveGitHubIssue(#101, status: "resolved", commit: "c0ffee1234")
Resolver-->>TPM: Accepted (Closed #101)
Note over TPM,Resolver: 5. Convergence Evaluation (Unblocked)
TPM->>Resolver: EvaluateConvergence()
Resolver-->>TPM: Status: Converged, Action: advance_convergence_cycle<br/>(100% pipeline pass, 0 pending critical issues)
5. Three-Fold Verification Proof Matrix
| Proof Dimension | Invariant Guaranteed | Test Fixture |
|---|---|---|
| Static Floor Invariant | Non-positive issue numbers rejected with ErrInvalidIssueNumber.Empty/whitespace titles rejected with ErrEmptyIssueTitle.Invalid states rejected with ErrInvalidIssueState.Invalid resolution statuses rejected with ErrInvalidResolutionStatus.Nil receivers on all session methods return clean errors or zero values without panics. Critical heuristic recognizes critical, blocker, p0, p1, bug, security, and bracketed titles. |
TestRepoResolverIssueManagement_StaticFloorInvariant |
| Operational Dynamic Proof | Ingestion of single and batch issues.ListPendingGitHubIssues filters closed/resolved items with deterministic sorting.ResolveGitHubIssue updates state and timestamps.GetIssueResolution retrieves accurate records.Active critical issues dynamically suppress advance_convergence_cycle and promote triage_pipeline_failures.Resolving all critical issues unblocks convergence to converged.ExportSessionSummary provides accurate issue counts. |
TestRepoResolverIssueManagement_OperationalDynamicProof |
| Negative Adversarial Boundary | Resolving un-ingested issue returns ErrIssueNotFound.Invalid resolution payloads fail closed. Batch ingestion with invalid item fails atomically. Negative issue lookups return ErrInvalidIssueNumber.High-concurrency stress test with 20 ingestion workers, 20 resolution workers, and 5 reader workers under POL-CONCURRENCY with zero race conditions or deadlocks. |
TestRepoResolverIssueManagement_NegativeAdversarialBoundary |
6. Concurrency Hygiene & Policy Compliance
All background test workers and asynchronous operations strictly adhere to POL-CONCURRENCY:
- Zero naked
go func()calls throughout the codebase. -
All background execution is governed via:
go goroutinelabels.NewGoroutine("<worker_name>", "<purpose>").StartSimple(func() { // safe worker body }) -
Mutex access is strictly bounded, ensuring read-write separation between telemetry metric ingestion, GitHub issue updates, and convergence matrix calculations.