SCM Projects, Proactive Issues, and PR/MR Reactions (tatara-operator) Implementation Plan¶

For agentic workers: REQUIRED SUB-SKILL: superpowers:subagent-driven-development. Dispatch implementation tasks to sonnet subagents; the merge that integrates parallel work runs in opus. Every task is TDD (superpowers:test-driven-development): write the failing test first, run it red, write minimal code, run it green, commit. Steps use checkbox (- [ ]) syntax.

Goal

Extend the operator's SCM egress so tatara participates on a project board (GitHub Projects v2 / GitLab issue board), proactively opens human-gated issues (awaiting-approval), and reacts to PRs/MRs conditionally on author: if tatara authored it tatara may improve / merge / close; if a human authored it tatara may only comment / suggest / approve / request-changes. A human is never silently mutated; tatara never merges unattended unless autoMergeOnGreenCI AND CI exists; every tatara-proposed item is gated behind a human-removable label. The operator is the SOLE caller of any SCM write.

Architecture

Ingress: scm.Client.DetectAndVerify parses inbound webhooks and now captures author/action/number/isPR/headSHA/headBranch/changedLabel. webhook.Server dispatch fans push/issue/PR/MR/review/comment events to handlers that select a Task Kind (implement|review|selfImprove), set ApprovalRequired, and apply prReactionScope gating. Egress: controller.SCMFor returns a widened scm.SCMWriter (the old 2-method Writer), implemented by *GitHub (REST v3 + a net-new Projects v2 GraphQL helper) and *GitLab (REST, label-driven boards). TaskReconciler adds an approval gate and a proposal-creation branch (the only place issues are created); doWriteBack branches on Task.Spec.Kind. Agents emit intent over three new operator REST endpoints (POST /projects/{p}/issues, /tasks/{t}/review, /tasks/{t}/pr-outcome) that ONLY write CRDs.

Tech Stack

Go 1.26.3 (go.mod directive pinned exact-minor), controller-runtime, chi v5, kubebuilder/controller-gen, prometheus/client_golang, stdlib log/slog (JSON), net/http + net/http/httptest for SCM fakes, envtest for controller flow. gofmt + golangci-lint clean. Table-driven tests with t.Run. Errors wrapped fmt.Errorf("...: %w", err). Build/deploy from main only; develop in a worktree per superpowers:using-git-worktrees.

File Structure¶

Task 1: SCM value types, WebhookEvent fields, SCMWriter interface¶

Files: - Modify: internal/scm/scm.go (WebhookEvent struct :10-19; new types after :19; Client iface stays :23-28; add SCMWriter iface) - Test: internal/scm/scm_types_test.go (Create)

• Step 1: Failing test for the new value types + interface satisfaction. Write internal/scm/scm_types_test.go:

  package scm
  
  import "testing"
  
  func TestValueTypesZero(t *testing.T) {
    r := IssueReq{Title: "t", Body: "b", Labels: []string{"x"}}
    if r.Title != "t" || r.Labels[0] != "x" {
        t.Fatalf("IssueReq fields not wired: %+v", r)
    }
    ref := IssueRef{Ref: "o/r#1", URL: "https://x/1"}
    if ref.Ref != "o/r#1" || ref.URL == "" {
        t.Fatalf("IssueRef fields not wired: %+v", ref)
    }
    st := PRState{Author: "a", HeadSHA: "sha", HeadBranch: "br", Mergeable: true, CIStatus: "success"}
    if !st.Mergeable || st.CIStatus != "success" {
        t.Fatalf("PRState fields not wired: %+v", st)
    }
    s := Suggestion{Path: "a.go", Line: 12, Body: "fix"}
    if s.Line != 12 {
        t.Fatalf("Suggestion fields not wired: %+v", s)
    }
    b := BoardRef{Provider: "github", Owner: "o", GitHubProjectNumber: 3, GitLabBoardID: 0, StatusField: "Status"}
    if b.GitHubProjectNumber != 3 || b.StatusField != "Status" {
        t.Fatalf("BoardRef fields not wired: %+v", b)
    }
    ev := WebhookEvent{AuthorLogin: "bot", Action: "labeled", Number: 7, IsPR: true, HeadSHA: "deadbeef", HeadBranch: "feat", ChangedLabel: "tatara/awaiting-approval"}
    if ev.AuthorLogin != "bot" || !ev.IsPR || ev.ChangedLabel == "" {
        t.Fatalf("WebhookEvent new fields not wired: %+v", ev)
    }
  }
  
  func TestProvidersSatisfySCMWriter(t *testing.T) {
    var _ SCMWriter = (*GitHub)(nil)
    var _ SCMWriter = (*GitLab)(nil)
  }
  

• Step 2: Run it red. go test ./internal/scm/ -run 'TestValueTypesZero|TestProvidersSatisfySCMWriter' -v -> FAIL: undefined IssueReq/IssueRef/PRState/Suggestion/BoardRef, undefined SCMWriter, and unknown fields on WebhookEvent.
• Step 3: Add WebhookEvent fields. In internal/scm/scm.go replace the WebhookEvent struct body (:10-19) with:

  type WebhookEvent struct {
    Kind     string // "push" | "issue" | "mr" | "other"
    Repo     string // remote URL
    Branch   string // for push
    Labels   []string
    Title    string
    Body     string
    IssueRef string // owner/repo#123 (github) or group/proj!iid (gitlab)
    URL      string
    AuthorLogin  string // login of the issue/PR/MR author (board identity)
    Action       string // opened|labeled|unlabeled|closed|synchronize|submitted|created|other
    Number       int    // issue/PR/MR number (github) or iid (gitlab)
    IsPR         bool   // true for mr/pull_request events
    HeadSHA      string // PR/MR head commit (for CI lookup)
    HeadBranch   string // PR/MR source branch (for selfImprove push target)
    ChangedLabel string // for labeled/unlabeled: the single label added/removed
  }
  

• Step 4: Add value types + SCMWriter. After the WebhookEvent struct in internal/scm/scm.go, before the Client interface, insert:

  // IssueReq is the payload for creating an issue.
  type IssueReq struct {
    Title  string
    Body   string
    Labels []string
  }
  
  // IssueRef identifies a created issue.
  type IssueRef struct {
    Ref string // owner/repo#n (github) or group/proj#iid (gitlab)
    URL string // html/web url
  }
  
  // PRState is the inspected state of a PR/MR.
  type PRState struct {
    Author     string
    HeadSHA    string
    HeadBranch string
    Mergeable  bool
    CIStatus   string // "" none | pending | success | failure
  }
  
  // Suggestion is one inline code suggestion on a PR/MR.
  type Suggestion struct {
    Path string
    Line int
    Body string
  }
  
  // BoardRef identifies a project board (GitHub Projects v2 or GitLab issue board).
  type BoardRef struct {
    Provider            string
    Owner               string
    GitHubProjectNumber int
    GitLabBoardID       int
    StatusField         string // GH single-select field; default "Status"
  }
  
  // SCMWriter is what controller.SCMFor returns; *GitHub and *GitLab satisfy it.
  type SCMWriter interface {
    OpenChange(ctx context.Context, repoURL, token, sourceBranch, targetBranch, title, body string) (string, error)
    Comment(ctx context.Context, token, issueRef, body string) error
    CreateIssue(ctx context.Context, repoURL, token string, req IssueReq) (IssueRef, error)
    AddLabel(ctx context.Context, token, issueRef, label string) error
    RemoveLabel(ctx context.Context, token, issueRef, label string) error
    GetPRState(ctx context.Context, repoURL, token string, number int) (PRState, error)
    Approve(ctx context.Context, repoURL, token string, number int, body string) error
    RequestChanges(ctx context.Context, repoURL, token string, number int, body string) error
    Suggest(ctx context.Context, repoURL, token string, number int, sugg []Suggestion) error
    Merge(ctx context.Context, repoURL, token string, number int, method string) error
    ClosePR(ctx context.Context, repoURL, token string, number int, body string) error
    AddBoardItem(ctx context.Context, token string, board BoardRef, itemURL string) error
    SetBoardColumn(ctx context.Context, token string, board BoardRef, itemURL, column string) error
  }
  

  TestProvidersSatisfySCMWriter stays red until Tasks 2-5 add the methods; keep it compiling by leaving the assertion. It will pass at the end of Task 5. The TestValueTypesZero test passes now.
• Step 5: Run TestValueTypesZero green. go test ./internal/scm/ -run TestValueTypesZero -v -> PASS.
• Step 6: Commit. git add internal/scm/scm.go internal/scm/scm_types_test.go && git commit -m "feat(scm): add IssueReq/IssueRef/PRState/Suggestion/BoardRef value types, WebhookEvent fields, SCMWriter interface"

Task 2: GitHub IssueAuthor (CreateIssue/AddLabel/RemoveLabel)¶

Files: - Modify: internal/scm/github.go (reuse ghDo :164, ghOwnerRepo :134, ghIssueRef :147) - Test: internal/scm/github_capabilities_test.go (Create)

• Step 1: Failing test for CreateIssue/AddLabel/RemoveLabel. Write internal/scm/github_capabilities_test.go:

  package scm
  
  import (
    "context"
    "encoding/json"
    "io"
    "net/http"
    "net/http/httptest"
    "testing"
  )
  
  func TestGitHubIssueAuthor(t *testing.T) {
    t.Run("CreateIssue", func(t *testing.T) {
        var gotPath, gotAuth string
        var gotBody map[string]any
        srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
            gotPath, gotAuth = r.URL.Path, r.Header.Get("Authorization")
            b, _ := io.ReadAll(r.Body)
            _ = json.Unmarshal(b, &gotBody)
            _ = json.NewEncoder(w).Encode(map[string]any{"number": 42, "html_url": "https://gh/o/r/issues/42"})
        }))
        defer srv.Close()
        c := &GitHub{apiBase: srv.URL}
        ref, err := c.CreateIssue(context.Background(), "https://github.com/o/r", "tok", IssueReq{Title: "T", Body: "B", Labels: []string{"l1"}})
        if err != nil {
            t.Fatalf("CreateIssue: %v", err)
        }
        if gotPath != "/repos/o/r/issues" {
            t.Fatalf("path = %q", gotPath)
        }
        if gotAuth != "Bearer tok" {
            t.Fatalf("auth = %q", gotAuth)
        }
        if gotBody["title"] != "T" || gotBody["body"] != "B" {
            t.Fatalf("body = %+v", gotBody)
        }
        labels, _ := gotBody["labels"].([]any)
        if len(labels) != 1 || labels[0] != "l1" {
            t.Fatalf("labels = %+v", gotBody["labels"])
        }
        if ref.Ref != "o/r#42" || ref.URL != "https://gh/o/r/issues/42" {
            t.Fatalf("ref = %+v", ref)
        }
    })
    t.Run("AddLabel", func(t *testing.T) {
        var gotPath string
        var gotBody map[string]any
        srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
            gotPath = r.URL.Path
            b, _ := io.ReadAll(r.Body)
            _ = json.Unmarshal(b, &gotBody)
        }))
        defer srv.Close()
        c := &GitHub{apiBase: srv.URL}
        if err := c.AddLabel(context.Background(), "tok", "o/r#7", "tatara/awaiting-approval"); err != nil {
            t.Fatalf("AddLabel: %v", err)
        }
        if gotPath != "/repos/o/r/issues/7/labels" {
            t.Fatalf("path = %q", gotPath)
        }
        labels, _ := gotBody["labels"].([]any)
        if len(labels) != 1 || labels[0] != "tatara/awaiting-approval" {
            t.Fatalf("labels = %+v", gotBody["labels"])
        }
    })
    t.Run("RemoveLabel", func(t *testing.T) {
        var gotPath, gotMethod string
        srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
            gotPath, gotMethod = r.URL.Path, r.Method
        }))
        defer srv.Close()
        c := &GitHub{apiBase: srv.URL}
        if err := c.RemoveLabel(context.Background(), "tok", "o/r#7", "tatara/awaiting-approval"); err != nil {
            t.Fatalf("RemoveLabel: %v", err)
        }
        if gotMethod != http.MethodDelete {
            t.Fatalf("method = %q", gotMethod)
        }
        if gotPath != "/repos/o/r/issues/7/labels/tatara/awaiting-approval" {
            t.Fatalf("path = %q", gotPath)
        }
    })
  }
  

• Step 2: Run it red. go test ./internal/scm/ -run TestGitHubIssueAuthor -v -> FAIL: c.CreateIssue / c.AddLabel / c.RemoveLabel undefined.
• Step 3: Implement the three methods. Append to internal/scm/github.go:

  // CreateIssue opens an issue and returns its ref + url.
  func (c *GitHub) CreateIssue(ctx context.Context, repoURL, token string, req IssueReq) (IssueRef, error) {
    owner, repo, err := ghOwnerRepo(repoURL)
    if err != nil {
        return IssueRef{}, err
    }
    path := fmt.Sprintf("/repos/%s/%s/issues", owner, repo)
    in := map[string]any{"title": req.Title, "body": req.Body}
    if len(req.Labels) > 0 {
        in["labels"] = req.Labels
    }
    var out struct {
        Number  int    `json:"number"`
        HTMLURL string `json:"html_url"`
    }
    if err := ghDo(ctx, c.base(), http.MethodPost, path, token, in, &out); err != nil {
        return IssueRef{}, err
    }
    return IssueRef{Ref: fmt.Sprintf("%s/%s#%d", owner, repo, out.Number), URL: out.HTMLURL}, nil
  }
  
  // AddLabel adds a single label to an issue/PR identified by owner/repo#number.
  func (c *GitHub) AddLabel(ctx context.Context, token, issueRef, label string) error {
    owner, repo, number, err := ghIssueRef(issueRef)
    if err != nil {
        return err
    }
    path := fmt.Sprintf("/repos/%s/%s/issues/%d/labels", owner, repo, number)
    return ghDo(ctx, c.base(), http.MethodPost, path, token, map[string][]string{"labels": {label}}, nil)
  }
  
  // RemoveLabel removes a single label from an issue/PR.
  func (c *GitHub) RemoveLabel(ctx context.Context, token, issueRef, label string) error {
    owner, repo, number, err := ghIssueRef(issueRef)
    if err != nil {
        return err
    }
    path := fmt.Sprintf("/repos/%s/%s/issues/%d/labels/%s", owner, repo, number, label)
    return ghDo(ctx, c.base(), http.MethodDelete, path, token, nil, nil)
  }
  

• Step 4: Run green. go test ./internal/scm/ -run TestGitHubIssueAuthor -v -> PASS.
• Step 5: Commit. git add internal/scm/github.go internal/scm/github_capabilities_test.go && git commit -m "feat(scm): GitHub IssueAuthor verbs (CreateIssue/AddLabel/RemoveLabel)"

Task 3: GitHub Reviewer (GetPRState/Approve/RequestChanges/Comment/Suggest/Merge/ClosePR)¶

Files: - Modify: internal/scm/github.go (reuse ghDo, ghOwnerRepo) - Test: internal/scm/github_capabilities_test.go (extend)

• Step 1: Failing test for GetPRState CI derivation. Append to internal/scm/github_capabilities_test.go:

  func TestGitHubGetPRState(t *testing.T) {
    cases := []struct {
        name       string
        runs       []map[string]string // status,conclusion
        wantCI     string
    }{
        {"no runs", nil, ""},
        {"in progress", []map[string]string{{"status": "in_progress", "conclusion": ""}}, "pending"},
        {"all success", []map[string]string{{"status": "completed", "conclusion": "success"}}, "success"},
        {"one failure", []map[string]string{{"status": "completed", "conclusion": "success"}, {"status": "completed", "conclusion": "failure"}}, "failure"},
    }
    for _, tc := range cases {
        t.Run(tc.name, func(t *testing.T) {
            srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
                switch {
                case r.URL.Path == "/repos/o/r/pulls/5":
                    _ = json.NewEncoder(w).Encode(map[string]any{
                        "user":     map[string]any{"login": "alice"},
                        "mergeable": true,
                        "head":     map[string]any{"sha": "abc", "ref": "feature"},
                    })
                case r.URL.Path == "/repos/o/r/commits/abc/check-runs":
                    runs := make([]map[string]any, 0, len(tc.runs))
                    for _, run := range tc.runs {
                        runs = append(runs, map[string]any{"status": run["status"], "conclusion": run["conclusion"]})
                    }
                    _ = json.NewEncoder(w).Encode(map[string]any{"check_runs": runs})
                default:
                    t.Fatalf("unexpected path %q", r.URL.Path)
                }
            }))
            defer srv.Close()
            c := &GitHub{apiBase: srv.URL}
            st, err := c.GetPRState(context.Background(), "https://github.com/o/r", "tok", 5)
            if err != nil {
                t.Fatalf("GetPRState: %v", err)
            }
            if st.Author != "alice" || st.HeadSHA != "abc" || st.HeadBranch != "feature" || !st.Mergeable {
                t.Fatalf("state = %+v", st)
            }
            if st.CIStatus != tc.wantCI {
                t.Fatalf("CIStatus = %q, want %q", st.CIStatus, tc.wantCI)
            }
        })
    }
  }
  

• Step 2: Run it red. go test ./internal/scm/ -run TestGitHubGetPRState -v -> FAIL: c.GetPRState undefined.
• Step 3: Implement GetPRState. Append to internal/scm/github.go:

  // GetPRState reads a PR plus its head check-runs, deriving CIStatus.
  func (c *GitHub) GetPRState(ctx context.Context, repoURL, token string, number int) (PRState, error) {
    owner, repo, err := ghOwnerRepo(repoURL)
    if err != nil {
        return PRState{}, err
    }
    var pr struct {
        User      struct{ Login string `json:"login"` } `json:"user"`
        Mergeable bool                                   `json:"mergeable"`
        Head      struct {
            SHA string `json:"sha"`
            Ref string `json:"ref"`
        } `json:"head"`
    }
    if err := ghDo(ctx, c.base(), http.MethodGet, fmt.Sprintf("/repos/%s/%s/pulls/%d", owner, repo, number), token, nil, &pr); err != nil {
        return PRState{}, err
    }
    st := PRState{Author: pr.User.Login, HeadSHA: pr.Head.SHA, HeadBranch: pr.Head.Ref, Mergeable: pr.Mergeable}
    var checks struct {
        CheckRuns []struct {
            Status     string `json:"status"`
            Conclusion string `json:"conclusion"`
        } `json:"check_runs"`
    }
    if err := ghDo(ctx, c.base(), http.MethodGet, fmt.Sprintf("/repos/%s/%s/commits/%s/check-runs", owner, repo, pr.Head.SHA), token, nil, &checks); err != nil {
        return PRState{}, err
    }
    st.CIStatus = deriveGHCIStatus(checks.CheckRuns)
    return st, nil
  }
  
  func deriveGHCIStatus(runs []struct {
    Status     string `json:"status"`
    Conclusion string `json:"conclusion"`
  }) string {
    if len(runs) == 0 {
        return ""
    }
    failure, pending := false, false
    for _, run := range runs {
        if run.Status != "completed" {
            pending = true
            continue
        }
        if run.Conclusion != "success" && run.Conclusion != "neutral" && run.Conclusion != "skipped" {
            failure = true
        }
    }
    switch {
    case failure:
        return "failure"
    case pending:
        return "pending"
    default:
        return "success"
    }
  }
  

• Step 4: Run green. go test ./internal/scm/ -run TestGitHubGetPRState -v -> PASS.
• Step 5: Failing test for Approve/RequestChanges/Comment/Suggest/Merge/ClosePR. Append:

  func TestGitHubReviewVerbs(t *testing.T) {
    t.Run("Approve", func(t *testing.T) {
        var gotPath string
        var body map[string]any
        srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
            gotPath = r.URL.Path
            b, _ := io.ReadAll(r.Body)
            _ = json.Unmarshal(b, &body)
        }))
        defer srv.Close()
        c := &GitHub{apiBase: srv.URL}
        if err := c.Approve(context.Background(), "https://github.com/o/r", "tok", 5, "lgtm"); err != nil {
            t.Fatalf("Approve: %v", err)
        }
        if gotPath != "/repos/o/r/pulls/5/reviews" || body["event"] != "APPROVE" || body["body"] != "lgtm" {
            t.Fatalf("path=%q body=%+v", gotPath, body)
        }
    })
    t.Run("RequestChanges", func(t *testing.T) {
        var body map[string]any
        srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
            b, _ := io.ReadAll(r.Body)
            _ = json.Unmarshal(b, &body)
        }))
        defer srv.Close()
        c := &GitHub{apiBase: srv.URL}
        if err := c.RequestChanges(context.Background(), "https://github.com/o/r", "tok", 5, "nope"); err != nil {
            t.Fatalf("RequestChanges: %v", err)
        }
        if body["event"] != "REQUEST_CHANGES" {
            t.Fatalf("event = %v", body["event"])
        }
    })
    t.Run("Suggest", func(t *testing.T) {
        var body map[string]any
        srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
            b, _ := io.ReadAll(r.Body)
            _ = json.Unmarshal(b, &body)
        }))
        defer srv.Close()
        c := &GitHub{apiBase: srv.URL}
        err := c.Suggest(context.Background(), "https://github.com/o/r", "tok", 5, []Suggestion{{Path: "a.go", Line: 12, Body: "x := 1"}})
        if err != nil {
            t.Fatalf("Suggest: %v", err)
        }
        if body["event"] != "COMMENT" {
            t.Fatalf("event = %v", body["event"])
        }
        comments, _ := body["comments"].([]any)
        if len(comments) != 1 {
            t.Fatalf("comments = %+v", body["comments"])
        }
        first, _ := comments[0].(map[string]any)
        if first["path"] != "a.go" || first["line"].(float64) != 12 {
            t.Fatalf("comment = %+v", first)
        }
        if cbody, _ := first["body"].(string); cbody != "```suggestion\nx := 1\n```" {
            t.Fatalf("comment body = %q", cbody)
        }
    })
    t.Run("Merge", func(t *testing.T) {
        var gotPath, gotMethod string
        var body map[string]any
        srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
            gotPath, gotMethod = r.URL.Path, r.Method
            b, _ := io.ReadAll(r.Body)
            _ = json.Unmarshal(b, &body)
        }))
        defer srv.Close()
        c := &GitHub{apiBase: srv.URL}
        if err := c.Merge(context.Background(), "https://github.com/o/r", "tok", 5, "squash"); err != nil {
            t.Fatalf("Merge: %v", err)
        }
        if gotPath != "/repos/o/r/pulls/5/merge" || gotMethod != http.MethodPut || body["merge_method"] != "squash" {
            t.Fatalf("path=%q method=%q body=%+v", gotPath, gotMethod, body)
        }
    })
    t.Run("ClosePR", func(t *testing.T) {
        paths := map[string]bool{}
        srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
            paths[r.Method+" "+r.URL.Path] = true
        }))
        defer srv.Close()
        c := &GitHub{apiBase: srv.URL}
        if err := c.ClosePR(context.Background(), "https://github.com/o/r", "tok", 5, "rejecting"); err != nil {
            t.Fatalf("ClosePR: %v", err)
        }
        if !paths["PATCH /repos/o/r/pulls/5"] {
            t.Fatalf("missing PATCH; got %+v", paths)
        }
        if !paths["POST /repos/o/r/issues/5/comments"] {
            t.Fatalf("missing comment; got %+v", paths)
        }
    })
  }
  

• Step 6: Run it red. go test ./internal/scm/ -run TestGitHubReviewVerbs -v -> FAIL: methods undefined.
• Step 7: Implement the review verbs. Append to internal/scm/github.go:

  func (c *GitHub) review(ctx context.Context, repoURL, token string, number int, event, body string, comments []map[string]any) error {
    owner, repo, err := ghOwnerRepo(repoURL)
    if err != nil {
        return err
    }
    in := map[string]any{"event": event}
    if body != "" {
        in["body"] = body
    }
    if comments != nil {
        in["comments"] = comments
    }
    path := fmt.Sprintf("/repos/%s/%s/pulls/%d/reviews", owner, repo, number)
    return ghDo(ctx, c.base(), http.MethodPost, path, token, in, nil)
  }
  
  // Approve posts an APPROVE review.
  func (c *GitHub) Approve(ctx context.Context, repoURL, token string, number int, body string) error {
    return c.review(ctx, repoURL, token, number, "APPROVE", body, nil)
  }
  
  // RequestChanges posts a REQUEST_CHANGES review.
  func (c *GitHub) RequestChanges(ctx context.Context, repoURL, token string, number int, body string) error {
    return c.review(ctx, repoURL, token, number, "REQUEST_CHANGES", body, nil)
  }
  
  // Suggest posts inline review comments with ```suggestion bodies.
  func (c *GitHub) Suggest(ctx context.Context, repoURL, token string, number int, sugg []Suggestion) error {
    comments := make([]map[string]any, 0, len(sugg))
    for _, s := range sugg {
        comments = append(comments, map[string]any{
            "path": s.Path,
            "line": s.Line,
            "body": "```suggestion\n" + s.Body + "\n```",
        })
    }
    return c.review(ctx, repoURL, token, number, "COMMENT", "", comments)
  }
  
  // Merge merges a PR with the given method (squash|merge|rebase).
  func (c *GitHub) Merge(ctx context.Context, repoURL, token string, number int, method string) error {
    owner, repo, err := ghOwnerRepo(repoURL)
    if err != nil {
        return err
    }
    path := fmt.Sprintf("/repos/%s/%s/pulls/%d/merge", owner, repo, number)
    return ghDo(ctx, c.base(), http.MethodPut, path, token, map[string]string{"merge_method": method}, nil)
  }
  
  // ClosePR closes a PR (state=closed) and posts a comment with the reason.
  func (c *GitHub) ClosePR(ctx context.Context, repoURL, token string, number int, body string) error {
    owner, repo, err := ghOwnerRepo(repoURL)
    if err != nil {
        return err
    }
    path := fmt.Sprintf("/repos/%s/%s/pulls/%d", owner, repo, number)
    if err := ghDo(ctx, c.base(), http.MethodPatch, path, token, map[string]string{"state": "closed"}, nil); err != nil {
        return err
    }
    if body == "" {
        return nil
    }
    return c.Comment(ctx, token, fmt.Sprintf("%s/%s#%d", owner, repo, number), body)
  }
  

• Step 8: Run green. go test ./internal/scm/ -run TestGitHubReviewVerbs -v -> PASS.
• Step 9: Commit. git add internal/scm/github.go internal/scm/github_capabilities_test.go && git commit -m "feat(scm): GitHub Reviewer verbs (GetPRState CI derivation, Approve/RequestChanges/Suggest/Merge/ClosePR)"

Task 4: GitHub BoardManager via Projects v2 GraphQL helper¶

Files: - Create: internal/scm/github_graphql.go (net-new GraphQL helper + AddBoardItem/SetBoardColumn) - Test: internal/scm/github_graphql_test.go (Create)

• Step 1: Failing test for AddBoardItem + SetBoardColumn. Write internal/scm/github_graphql_test.go:

  package scm
  
  import (
    "context"
    "encoding/json"
    "io"
    "net/http"
    "net/http/httptest"
    "strings"
    "testing"
  )
  
  func TestGitHubBoardManager(t *testing.T) {
    t.Run("AddBoardItem", func(t *testing.T) {
        var queries []string
        srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
            b, _ := io.ReadAll(r.Body)
            var req struct {
                Query string `json:"query"`
            }
            _ = json.Unmarshal(b, &req)
            queries = append(queries, req.Query)
            switch {
            case strings.Contains(req.Query, "organization"):
                _ = json.NewEncoder(w).Encode(map[string]any{"data": map[string]any{"organization": map[string]any{"projectV2": map[string]any{"id": "PVT_1"}}}})
            case strings.Contains(req.Query, "resource(url"):
                _ = json.NewEncoder(w).Encode(map[string]any{"data": map[string]any{"resource": map[string]any{"id": "I_1"}}})
            case strings.Contains(req.Query, "addProjectV2ItemById"):
                _ = json.NewEncoder(w).Encode(map[string]any{"data": map[string]any{"addProjectV2ItemById": map[string]any{"item": map[string]any{"id": "ITEM_1"}}}})
            default:
                t.Fatalf("unexpected query %q", req.Query)
            }
        }))
        defer srv.Close()
        c := &GitHub{apiBase: "unused", graphQLBase: srv.URL}
        board := BoardRef{Provider: "github", Owner: "acme", GitHubProjectNumber: 3, StatusField: "Status"}
        if err := c.AddBoardItem(context.Background(), "tok", board, "https://github.com/acme/r/issues/9"); err != nil {
            t.Fatalf("AddBoardItem: %v", err)
        }
        if len(queries) != 3 {
            t.Fatalf("expected 3 graphql calls, got %d", len(queries))
        }
    })
    t.Run("SetBoardColumn", func(t *testing.T) {
        var sawUpdate bool
        srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
            b, _ := io.ReadAll(r.Body)
            var req struct {
                Query string `json:"query"`
            }
            _ = json.Unmarshal(b, &req)
            switch {
            case strings.Contains(req.Query, "organization"):
                _ = json.NewEncoder(w).Encode(map[string]any{"data": map[string]any{"organization": map[string]any{"projectV2": map[string]any{
                    "id": "PVT_1",
                    "field": map[string]any{
                        "id": "FIELD_1",
                        "options": []any{
                            map[string]any{"id": "OPT_PROPOSED", "name": "Proposed"},
                            map[string]any{"id": "OPT_DONE", "name": "Done"},
                        },
                    },
                }}}})
            case strings.Contains(req.Query, "resource(url"):
                _ = json.NewEncoder(w).Encode(map[string]any{"data": map[string]any{"resource": map[string]any{"id": "I_1", "projectItems": map[string]any{"nodes": []any{map[string]any{"id": "ITEM_1", "project": map[string]any{"id": "PVT_1"}}}}}}})
            case strings.Contains(req.Query, "updateProjectV2ItemFieldValue"):
                sawUpdate = true
                if !strings.Contains(req.Query, "OPT_PROPOSED") {
                    t.Fatalf("update did not select Proposed option: %q", req.Query)
                }
                _ = json.NewEncoder(w).Encode(map[string]any{"data": map[string]any{"updateProjectV2ItemFieldValue": map[string]any{"clientMutationId": ""}}})
            default:
                t.Fatalf("unexpected query %q", req.Query)
            }
        }))
        defer srv.Close()
        c := &GitHub{apiBase: "unused", graphQLBase: srv.URL}
        board := BoardRef{Provider: "github", Owner: "acme", GitHubProjectNumber: 3, StatusField: "Status"}
        if err := c.SetBoardColumn(context.Background(), "tok", board, "https://github.com/acme/r/issues/9", "Proposed"); err != nil {
            t.Fatalf("SetBoardColumn: %v", err)
        }
        if !sawUpdate {
            t.Fatalf("updateProjectV2ItemFieldValue not called")
        }
    })
  }
  

• Step 2: Run it red. go test ./internal/scm/ -run TestGitHubBoardManager -v -> FAIL: graphQLBase field and AddBoardItem/SetBoardColumn undefined.
• Step 3: Add graphQLBase to GitHub struct. In internal/scm/scm.go replace the GitHub struct (:41-44):

  // GitHub implements Client for GitHub.
  type GitHub struct {
    apiBase     string
    graphQLBase string
  }
  

• Step 4: Implement the GraphQL helper + board verbs. Create internal/scm/github_graphql.go:

  package scm
  
  import (
    "bytes"
    "context"
    "encoding/json"
    "fmt"
    "io"
    "net/http"
  )
  
  func (c *GitHub) graphQLEndpoint() string {
    if c.graphQLBase != "" {
        return c.graphQLBase
    }
    return "https://api.github.com/graphql"
  }
  
  // ghGraphQL posts a GraphQL query and decodes data into out.
  func (c *GitHub) ghGraphQL(ctx context.Context, token, query string, vars map[string]any, out any) error {
    payload := map[string]any{"query": query}
    if vars != nil {
        payload["variables"] = vars
    }
    b, err := json.Marshal(payload)
    if err != nil {
        return fmt.Errorf("github: encode graphql: %w", err)
    }
    req, err := http.NewRequestWithContext(ctx, http.MethodPost, c.graphQLEndpoint(), bytes.NewReader(b))
    if err != nil {
        return fmt.Errorf("github: build graphql request: %w", err)
    }
    req.Header.Set("Authorization", "Bearer "+token)
    req.Header.Set("Content-Type", "application/json")
    resp, err := http.DefaultClient.Do(req)
    if err != nil {
        return fmt.Errorf("github: do graphql request: %w", err)
    }
    defer func() { _ = resp.Body.Close() }()
    if resp.StatusCode >= 400 {
        buf, _ := io.ReadAll(resp.Body)
        return &HTTPError{Status: resp.StatusCode, Body: string(buf), Path: "/graphql"}
    }
    var env struct {
        Data   json.RawMessage `json:"data"`
        Errors []struct {
            Message string `json:"message"`
        } `json:"errors"`
    }
    if err := json.NewDecoder(resp.Body).Decode(&env); err != nil {
        return fmt.Errorf("github: decode graphql: %w", err)
    }
    if len(env.Errors) > 0 {
        return fmt.Errorf("github: graphql error: %s", env.Errors[0].Message)
    }
    if out == nil {
        return nil
    }
    if err := json.Unmarshal(env.Data, out); err != nil {
        return fmt.Errorf("github: decode graphql data: %w", err)
    }
    return nil
  }
  
  // AddBoardItem resolves the project by org+number, the issue node by URL, and
  // adds the item to the Projects v2 board.
  func (c *GitHub) AddBoardItem(ctx context.Context, token string, board BoardRef, itemURL string) error {
    projectID, err := c.ghProjectID(ctx, token, board)
    if err != nil {
        return err
    }
    contentID, err := c.ghResourceID(ctx, token, itemURL)
    if err != nil {
        return err
    }
    q := fmt.Sprintf(`mutation { addProjectV2ItemById(input:{projectId:%q, contentId:%q}) { item { id } } }`, projectID, contentID)
    return c.ghGraphQL(ctx, token, q, nil, nil)
  }
  
  // SetBoardColumn sets the Status single-select field of the board item for itemURL.
  func (c *GitHub) SetBoardColumn(ctx context.Context, token string, board BoardRef, itemURL, column string) error {
    field := board.StatusField
    if field == "" {
        field = "Status"
    }
    var proj struct {
        Organization struct {
            ProjectV2 struct {
                ID    string `json:"id"`
                Field struct {
                    ID      string `json:"id"`
                    Options []struct {
                        ID   string `json:"id"`
                        Name string `json:"name"`
                    } `json:"options"`
                } `json:"field"`
            } `json:"projectV2"`
        } `json:"organization"`
    }
    pq := fmt.Sprintf(`query { organization(login:%q) { projectV2(number:%d) { id field(name:%q) { ... on ProjectV2SingleSelectField { id options { id name } } } } } }`, board.Owner, board.GitHubProjectNumber, field)
    if err := c.ghGraphQL(ctx, token, pq, nil, &proj); err != nil {
        return err
    }
    optionID := ""
    for _, o := range proj.Organization.ProjectV2.Field.Options {
        if o.Name == column {
            optionID = o.ID
            break
        }
    }
    if optionID == "" {
        return fmt.Errorf("github: board column %q not found in field %q", column, field)
    }
    itemID, err := c.ghProjectItemID(ctx, token, itemURL, proj.Organization.ProjectV2.ID)
    if err != nil {
        return err
    }
    mq := fmt.Sprintf(`mutation { updateProjectV2ItemFieldValue(input:{projectId:%q, itemId:%q, fieldId:%q, value:{singleSelectOptionId:%q}}) { clientMutationId } }`,
        proj.Organization.ProjectV2.ID, itemID, proj.Organization.ProjectV2.Field.ID, optionID)
    return c.ghGraphQL(ctx, token, mq, nil, nil)
  }
  
  func (c *GitHub) ghProjectID(ctx context.Context, token string, board BoardRef) (string, error) {
    var out struct {
        Organization struct {
            ProjectV2 struct {
                ID string `json:"id"`
            } `json:"projectV2"`
        } `json:"organization"`
    }
    q := fmt.Sprintf(`query { organization(login:%q) { projectV2(number:%d) { id } } }`, board.Owner, board.GitHubProjectNumber)
    if err := c.ghGraphQL(ctx, token, q, nil, &out); err != nil {
        return "", err
    }
    if out.Organization.ProjectV2.ID == "" {
        return "", fmt.Errorf("github: project %d not found for org %q", board.GitHubProjectNumber, board.Owner)
    }
    return out.Organization.ProjectV2.ID, nil
  }
  
  func (c *GitHub) ghResourceID(ctx context.Context, token, itemURL string) (string, error) {
    var out struct {
        Resource struct {
            ID string `json:"id"`
        } `json:"resource"`
    }
    q := fmt.Sprintf(`query { resource(url:%q) { ... on Issue { id } ... on PullRequest { id } } }`, itemURL)
    if err := c.ghGraphQL(ctx, token, q, nil, &out); err != nil {
        return "", err
    }
    if out.Resource.ID == "" {
        return "", fmt.Errorf("github: resource not found for url %q", itemURL)
    }
    return out.Resource.ID, nil
  }
  
  func (c *GitHub) ghProjectItemID(ctx context.Context, token, itemURL, projectID string) (string, error) {
    var out struct {
        Resource struct {
            ProjectItems struct {
                Nodes []struct {
                    ID      string `json:"id"`
                    Project struct {
                        ID string `json:"id"`
                    } `json:"project"`
                } `json:"nodes"`
            } `json:"projectItems"`
        } `json:"resource"`
    }
    q := fmt.Sprintf(`query { resource(url:%q) { ... on Issue { projectItems(first:20) { nodes { id project { id } } } } ... on PullRequest { projectItems(first:20) { nodes { id project { id } } } } } }`, itemURL)
    if err := c.ghGraphQL(ctx, token, q, nil, &out); err != nil {
        return "", err
    }
    for _, n := range out.Resource.ProjectItems.Nodes {
        if n.Project.ID == projectID {
            return n.ID, nil
        }
    }
    return "", fmt.Errorf("github: item for %q not on project %q", itemURL, projectID)
  }
  

• Step 5: Run green. go test ./internal/scm/ -run TestGitHubBoardManager -v -> PASS.
• Step 6: Commit. git add internal/scm/scm.go internal/scm/github_graphql.go internal/scm/github_graphql_test.go && git commit -m "feat(scm): GitHub Projects v2 GraphQL board manager (AddBoardItem/SetBoardColumn)"