docs(webhook): annotate sync pipeline helpers

Ultraworked with [Sisyphus](https://github.com/code-yeongyu/oh-my-openagent)

Co-authored-by: Sisyphus <clio-agent@sisyphuslabs.ai>

Author: tae2089

internal/webhook/allowlist.go

@@ -1,31 +1,42 @@
+// @index Repository and branch allowlist rules for webhook-triggered sync.
 package webhook
 
 import (
 	"path"
 	"strings"
 )
 
+// allowRule is one compiled allow or deny pattern with optional negation and wildcard prefix.
+// @intent represent a single Atlantis-style repo pattern in a form cheap to evaluate per webhook.
 type allowRule struct {
 	pattern  string
 	negate   bool
 	wildcard bool
 	prefix   string
 }
 
+// RepoRule is the user-facing config form pairing a repo pattern with optional branch globs.
+// @intent expose a stable shape for CLI/YAML config without leaking the internal compiled rule layout.
 type RepoRule struct {
 	Pattern  string
 	Branches []string
 }
 
+// repoFilterRule binds a compiled allow/deny pattern to its per-rule branch allowlist.
+// @intent keep branch policy attached to the rule that allowed the repo so order-sensitive evaluation stays local.
 type repoFilterRule struct {
 	allowRule
 	branches []string
 }
 
+// RepoFilter holds the ordered rule list used to decide repo and branch admission.
+// @intent provide a single matcher whose result depends on rule declaration order, where later matching rules override earlier ones.
 type RepoFilter struct {
 	rulesFull []repoFilterRule
 }
 
+// NewRepoFilter expands simple string patterns into webhook repo rules.
+// @intent keep CLI-style allowlist configuration compatible with the richer rule matcher.
 func NewRepoFilter(patterns []string) *RepoFilter {
 	rules := make([]RepoRule, 0, len(patterns))
 	for _, p := range patterns {
@@ -34,6 +45,8 @@ func NewRepoFilter(patterns []string) *RepoFilter {
 	return NewRepoFilterFromRules(rules)
 }
 
+// NewRepoFilterFromRules compiles repository and branch rules into a matcher.
+// @intent centralize Atlantis-style repo filtering so webhook dispatch can make one consistent allow decision.
 func NewRepoFilterFromRules(rules []RepoRule) *RepoFilter {
 	full := make([]repoFilterRule, 0, len(rules))
 	for _, r := range rules {
@@ -55,6 +68,10 @@ func NewRepoFilterFromRules(rules []RepoRule) *RepoFilter {
 
 var defaultBranches = []string{"main", "master"}
 
+// IsAllowed reports whether a repository matches the configured allow and deny rules.
+// @intent let callers gate repository-level sync before looking at branch-specific restrictions.
+// @domainRule rules are evaluated in declaration order and the last matching rule wins; a later allow rule overrides an earlier deny match and vice versa.
+// @domainRule a repository with no matching rule is denied (default-deny).
 func (f *RepoFilter) IsAllowed(repoFullName string) bool {
 	allowed := false
 	for _, r := range f.rulesFull {
@@ -70,6 +87,8 @@ func (f *RepoFilter) IsAllowed(repoFullName string) bool {
 	return allowed
 }
 
+// IsAllowedRef resolves a git ref to a branch and applies branch allowlist rules.
+// @intent reject non-branch webhook refs before they can enter the sync pipeline.
 func (f *RepoFilter) IsAllowedRef(repoFullName, ref string) bool {
 	branch, ok := NormalizeBranchRef(ref)
 	if !ok {
@@ -78,6 +97,11 @@ func (f *RepoFilter) IsAllowedRef(repoFullName, ref string) bool {
 	return f.IsAllowedBranch(repoFullName, branch)
 }
 
+// IsAllowedBranch reports whether a repository and branch pair should be processed.
+// @intent combine repo allowlist and branch policy so webhook handlers can skip unsupported pushes cheaply.
+// @domainRule with no rules configured the result is always false (default-deny).
+// @domainRule rules are evaluated in declaration order; each later matching rule replaces the prior decision, so a negate rule clears any previous allow and a subsequent allow rule re-enables the repo.
+// @domainRule when a non-negate rule matches but specifies no branches, the built-in defaults ("main", "master") are used.
 func (f *RepoFilter) IsAllowedBranch(repoFullName, branch string) bool {
 	if len(f.rulesFull) == 0 {
 		return false
@@ -101,6 +125,7 @@ func (f *RepoFilter) IsAllowedBranch(repoFullName, branch string) bool {
 	return allowed
 }
 
+// @intent evaluate branch globs consistently across repo rules without duplicating path-match logic at call sites.
 func matchBranchPatterns(branch string, patterns []string) bool {
 	for _, p := range patterns {
 		if matched, _ := path.Match(p, branch); matched {
@@ -110,6 +135,8 @@ func matchBranchPatterns(branch string, patterns []string) bool {
 	return false
 }
 
+// ParseRepoRule decodes a repo rule string with optional comma-separated branch patterns.
+// @intent preserve compact CLI config while still supporting per-repository branch restrictions.
 func ParseRepoRule(s string) RepoRule {
 	pattern, branchStr, found := strings.Cut(s, ":")
 	if !found {
@@ -119,6 +146,7 @@ func ParseRepoRule(s string) RepoRule {
 	return RepoRule{Pattern: pattern, Branches: branches}
 }
 
+// @intent apply one compiled allow or deny pattern to a repository full name during filter evaluation.
 func (r *allowRule) match(repoFullName string) bool {
 	if r.wildcard {
 		parts := strings.SplitN(repoFullName, "/", 2)

internal/webhook/auth.go

@@ -1,3 +1,4 @@
+// @index Authentication helpers for webhook-driven git access.
 package webhook
 
 import (
@@ -18,6 +19,7 @@ import (
 	"github.com/go-git/go-git/v5/plumbing/transport/ssh"
 )
 
+// @intent bundle the supported git authentication inputs (SSH key, GitHub App credentials, install token) for webhook clone and fetch.
 type GitAuth struct {
 	SSHKeyPath   string
 	SSHKeyData   []byte
@@ -27,6 +29,8 @@ type GitAuth struct {
 	InstallToken string
 }
 
+// Resolve picks the first configured git authentication strategy.
+// @intent allow webhook sync to switch between SSH and GitHub App token auth without branching at call sites.
 func (a *GitAuth) Resolve() (transport.AuthMethod, error) {
 	switch {
 	case a.SSHKeyPath != "":
@@ -43,6 +47,8 @@ func (a *GitAuth) Resolve() (transport.AuthMethod, error) {
 	}
 }
 
+// GenerateAppJWT signs a short-lived GitHub App JWT from the configured private key.
+// @intent mint the app identity token needed to exchange for installation-scoped repository access.
 func GenerateAppJWT(appID int64, privateKeyPEM []byte) (string, error) {
 	block, _ := pem.Decode(privateKeyPEM)
 	if block == nil {

internal/webhook/cloneurl.go

@@ -1,3 +1,4 @@
+// @index Clone URL resolution for webhook-triggered repository sync.
 package webhook
 
 import (
@@ -7,6 +8,8 @@ import (
 	"strings"
 )
 
+// ResolveCloneURL selects a safe clone target from configured base URLs or the payload.
+// @intent keep repository sync deterministic and prevent untrusted webhook payloads from choosing arbitrary clone endpoints unless explicitly allowed.
 func ResolveCloneURL(repoFullName, payloadCloneURL string, baseURLs []string, allowPayload bool) (string, error) {
 	repoPath, err := normalizeRepoPath(repoFullName)
 	if err != nil {
@@ -34,6 +37,13 @@ func ResolveCloneURL(repoFullName, payloadCloneURL string, baseURLs []string, al
 	return "", fmt.Errorf("clone URL is not configured for repo %q", repoFullName)
 }
 
+// normalizeRepoPath validates that a repo full name is a clean two-or-more
+// segment path with no empty, ".", or ".." components and no leading slash.
+//
+// @intent reject repo identifiers that could traverse outside the intended path when joined onto a base URL.
+// @domainRule each path segment must be non-empty and not equal to "." or "..".
+// @domainRule path.Clean(repoFullName) must equal repoFullName and must not start with "/".
+// @ensures returned path equals the input when err == nil.
 func normalizeRepoPath(repoFullName string) (string, error) {
 	parts := strings.Split(repoFullName, "/")
 	if len(parts) < 2 {
@@ -51,6 +61,11 @@ func normalizeRepoPath(repoFullName string) (string, error) {
 	return cleaned, nil
 }
 
+// buildCloneURL joins repoPath onto a validated base URL and appends ".git".
+//
+// @intent derive a clone URL from a trusted base URL plus a normalized repo path so the host/scheme are not taken from webhook payload data.
+// @domainRule resulting path is path.Join(base.Path, repoPath) + ".git".
+// @ensures returned URL preserves the base URL's scheme and host when err == nil.
 func buildCloneURL(baseURL, repoPath string) (string, error) {
 	parsed, err := parseCloneBaseURL(baseURL)
 	if err != nil {
@@ -61,6 +76,11 @@ func buildCloneURL(baseURL, repoPath string) (string, error) {
 	return cloneURL.String(), nil
 }
 
+// parseCloneBaseURL parses and validates a configured clone base URL.
+//
+// @intent ensure each configured base URL is an absolute URL with scheme and host before it is used to construct clone targets.
+// @domainRule baseURL must parse via url.ParseRequestURI and url.Parse without error.
+// @domainRule parsed scheme and host must be non-empty and Opaque must be empty.
 func parseCloneBaseURL(baseURL string) (*url.URL, error) {
 	if _, err := url.ParseRequestURI(baseURL); err != nil {
 		return nil, fmt.Errorf("parse repo clone base URL: %w", err)

internal/webhook/gitops.go

@@ -1,3 +1,4 @@
+// @index Repository locking and clone-or-pull operations for webhook sync.
 package webhook
 
 import (
@@ -19,30 +20,39 @@ import (
 	"github.com/go-git/go-git/v5/plumbing/transport"
 )
 
+// @intent signal that a per-repository lock could not be acquired within the configured wait window.
 var ErrRepoLockTimeout = errors.New("repo lock timeout")
 
+// @intent treat repository lock files older than this threshold as abandoned by a previous process.
 const repoLockStaleAfter = 30 * time.Minute
 
+// @intent keep repository-scoped git operations serialized across concurrent webhook deliveries.
 type RepoLocker struct {
 	timeout time.Duration
 	mu      sync.Mutex
 	locks   map[string]chan struct{}
 }
 
+// @intent persist enough lock provenance to detect and clean up stale repository lock files safely.
 type repoLockMetadata struct {
 	Repo      string    `json:"repo"`
 	PID       int       `json:"pid"`
 	Hostname  string    `json:"hostname"`
 	CreatedAt time.Time `json:"created_at"`
 }
 
+// NewRepoLocker creates a per-repository lock coordinator with a bounded wait time.
+// @intent serialize concurrent webhook sync for the same repo so git operations do not corrupt the working tree.
 func NewRepoLocker(timeout time.Duration) *RepoLocker {
 	if timeout <= 0 {
 		timeout = 30 * time.Second
 	}
 	return &RepoLocker{timeout: timeout, locks: make(map[string]chan struct{})}
 }
 
+// WithLock runs a sync operation while holding both in-process and filesystem repo locks.
+// @intent coordinate webhook workers across goroutines and processes before touching a repository checkout.
+// @sideEffect creates and removes filesystem lock files under the repo root.
 func (l *RepoLocker) WithLock(ctx context.Context, lockRoot, repoFullName string, fn func(context.Context) error) error {
 	if ctx == nil {
 		ctx = context.Background()
@@ -65,6 +75,7 @@ func (l *RepoLocker) WithLock(ctx context.Context, lockRoot, repoFullName string
 	return fn(ctx)
 }
 
+// @intent gate same-process sync attempts for a repository before filesystem locking is attempted.
 func (l *RepoLocker) acquireLocal(ctx context.Context, repoFullName string) (chan struct{}, func(chan struct{}), error) {
 	l.mu.Lock()
 	lock := l.locks[repoFullName]
@@ -83,6 +94,8 @@ func (l *RepoLocker) acquireLocal(ctx context.Context, repoFullName string) (cha
 	}
 }
 
+// @intent coordinate repository sync across processes by creating an exclusive lock file under the repo root.
+// @sideEffect creates and removes repository lock files on disk.
 func acquireFilesystemLock(ctx context.Context, lockRoot, repoFullName string) (*os.File, func(*os.File), error) {
 	lockFile := filepath.Join(lockRoot, ".locks", lockFileName(repoFullName))
 	if err := os.MkdirAll(filepath.Dir(lockFile), 0755); err != nil {
@@ -123,6 +136,8 @@ func acquireFilesystemLock(ctx context.Context, lockRoot, repoFullName string) (
 	}
 }
 
+// @intent write lock ownership metadata so stale lock cleanup can be diagnosed from the filesystem.
+// @sideEffect writes JSON metadata and fsyncs the lock file.
 func writeRepoLockMetadata(file *os.File, repoFullName string) error {
 	hostname, err := os.Hostname()
 	if err != nil {
@@ -140,6 +155,8 @@ func writeRepoLockMetadata(file *os.File, repoFullName string) error {
 	return file.Sync()
 }
 
+// @intent discard abandoned repository lock files after the stale timeout elapses.
+// @sideEffect may remove an on-disk lock file.
 func removeStaleFilesystemLock(lockFile string) (bool, time.Duration) {
 	info, err := os.Stat(lockFile)
 	if err != nil {
@@ -155,19 +172,27 @@ func removeStaleFilesystemLock(lockFile string) (bool, time.Duration) {
 	return true, age
 }
 
+// @intent convert repository names into stable lock-safe filenames.
 func lockFileName(repoFullName string) string {
 	replacer := strings.NewReplacer("/", "-", "\\", "-", ":", "-")
 	return replacer.Replace(repoFullName) + ".lock"
 }
 
+// RepoDir maps a namespace to the checkout directory used for repository sync.
+// @intent keep workspace naming stable across clone, pull, and downstream build steps.
 func RepoDir(repoRoot, namespace string) string {
 	return filepath.Join(repoRoot, namespace)
 }
 
+// CloneOrPull syncs the repository namespace to the default remote branch.
+// @intent give webhook handlers a branch-agnostic entry point for standard repo refresh.
 func CloneOrPull(ctx context.Context, repoURL, repoRoot, namespace string, auth transport.AuthMethod) error {
 	return CloneOrPullBranch(ctx, repoURL, repoRoot, namespace, "", auth)
 }
 
+// CloneOrPullBranch ensures the namespace checkout exists and matches the requested branch head.
+// @intent reuse the same repo sync path for first clone and subsequent updates.
+// @sideEffect creates or hard-resets the namespace checkout on disk.
 func CloneOrPullBranch(ctx context.Context, repoURL, repoRoot, namespace, branch string, auth transport.AuthMethod) error {
 	dest := RepoDir(repoRoot, namespace)
 
@@ -187,6 +212,8 @@ func CloneOrPullBranch(ctx context.Context, repoURL, repoRoot, namespace, branch
 	return syncRepoBranch(ctx, repo, branch, auth)
 }
 
+// CloneOrPullBranchLocked wraps branch sync with repository locking.
+// @intent prevent overlapping webhook deliveries from cloning or resetting the same checkout simultaneously.
 func CloneOrPullBranchLocked(ctx context.Context, locker *RepoLocker, repoURL, repoRoot, repoFullName, namespace, branch string, auth transport.AuthMethod) error {
 	if locker == nil {
 		locker = NewRepoLocker(30 * time.Second)
@@ -196,6 +223,7 @@ func CloneOrPullBranchLocked(ctx context.Context, locker *RepoLocker, repoURL, r
 	})
 }
 
+// @intent log clone URLs without leaking embedded credentials.
 func sanitizeURL(raw string) string {
 	u, err := url.Parse(raw)
 	if err != nil {
@@ -207,6 +235,8 @@ func sanitizeURL(raw string) string {
 	return u.String()
 }
 
+// @intent perform the first namespace clone via a temp directory so partially cloned repos are never promoted.
+// @sideEffect creates temporary directories and renames the completed clone into place.
 func cloneRepo(ctx context.Context, repoURL, repoRoot, dest, namespace, branch string, auth transport.AuthMethod) error {
 	slog.Info("cloning repository", "url", sanitizeURL(repoURL), "dest", dest)
 
@@ -251,6 +281,8 @@ func cloneRepo(ctx context.Context, repoURL, repoRoot, dest, namespace, branch s
 	return nil
 }
 
+// @intent hard-reset an existing checkout to the latest remote branch head for deterministic rebuilds.
+// @sideEffect fetches from origin and rewrites the local worktree state.
 func syncRepoBranch(ctx context.Context, repo *git.Repository, branch string, auth transport.AuthMethod) error {
 	slog.Info("syncing repository to remote branch", "branch", branch)
 
@@ -294,6 +326,7 @@ func syncRepoBranch(ctx context.Context, repo *git.Repository, branch string, au
 	return nil
 }
 
+// @intent build fetch options that keep sync traffic branch-scoped and shallow when possible.
 func fetchOptions(remoteName, branch string, auth transport.AuthMethod) *git.FetchOptions {
 	opts := &git.FetchOptions{RemoteName: remoteName, Depth: 1}
 	if branch != "" {