feat(app,github,cli): add structured logging, circuit breaker, and trace IDs

- Add internal/log package using log/slog with RedactedString for credential scrubbing
- Wire structured logger through main, CLI, and app service with per-component attribution
- Generate UUID trace ID per invocation for cross-line log correlation
- Add circuit breaker to GitHub retry transport with closed/open/half-open states
- Add circuit breaker tests covering all state transitions
- Add .github/labels.yml with priority, type, and area labels
- Expand runbooks with deployment observability and circuit breaker troubleshooting
- Exclude .factory/ from git tracking

Author: morluto

.github/labels.yml

@@ -0,0 +1,58 @@
+# Priority labels
+- name: "priority/critical"
+  color: "B60205"
+  description: "Must be addressed immediately"
+- name: "priority/high"
+  color: "D93F0B"
+  description: "Should be addressed in current sprint"
+- name: "priority/medium"
+  color: "FBCA04"
+  description: "Should be addressed soon"
+- name: "priority/low"
+  color: "0E8A16"
+  description: "Nice to have"
+
+# Type labels
+- name: "bug"
+  color: "D73A4A"
+  description: "Something isn't working"
+- name: "enhancement"
+  color: "A2EEEF"
+  description: "New feature or improvement"
+- name: "chore"
+  color: "FEF2C0"
+  description: "Maintenance or tooling work"
+- name: "documentation"
+  color: "0075CA"
+  description: "Documentation improvements"
+
+# Area labels
+- name: "area/cli"
+  color: "0052CC"
+  description: "CLI adapter and user interface"
+- name: "area/corpus"
+  color: "5319E7"
+  description: "Storage, SQLite, and query layer"
+- name: "area/github"
+  color: "EDEDED"
+  description: "GitHub API client and network I/O"
+- name: "area/app"
+  color: "D4C5F9"
+  description: "Application service and orchestration"
+- name: "area/testing"
+  color: "1D76DB"
+  description: "Test infrastructure and coverage"
+- name: "area/ci"
+  color: "BFDADC"
+  description: "CI/CD workflows and automation"
+
+# Dependency labels
+- name: "dependencies"
+  color: "0366D6"
+  description: "Dependency updates"
+- name: "go"
+  color: "00ADD8"
+  description: "Go-related changes"
+- name: "ci"
+  color: "BFC1C3"
+  description: "CI/CD changes"

.gitignore

@@ -25,6 +25,7 @@ go.work.sum
 # === IDE ===
 .idea/
 .vscode/
+.factory/
 *.swp
 *.swo
 *~

cmd/gitcontribute/main.go

@@ -8,9 +8,11 @@ import (
 	"os/signal"
 	"syscall"
 
+	"github.com/google/uuid"
 	"github.com/morluto/gitcontribute/internal/app"
 	"github.com/morluto/gitcontribute/internal/cli"
 	"github.com/morluto/gitcontribute/internal/config"
+	gitlog "github.com/morluto/gitcontribute/internal/log"
 	"github.com/morluto/gitcontribute/internal/tui"
 )
 
@@ -20,25 +22,54 @@ func main() {
 	ctx, stop := signal.NotifyContext(context.Background(), os.Interrupt, syscall.SIGTERM)
 	defer stop()
 
+	logger := gitlog.New("main")
+
+	// Generate a trace ID for this invocation so all log lines from the
+	// same command run can be correlated.
+	traceID := uuid.NewString()
+	logger.InfoContext(ctx, "starting",
+		"version", version,
+		"trace_id", traceID,
+		"args", os.Args[1:],
+	)
+	ctx = gitlog.WithTrace(ctx, traceID)
+
 	paths := config.NewPaths(nil)
-	svc, err := app.New(paths, version)
+	svc, err := app.New(paths, version, logger.With("component", "app"))
 	if err != nil {
+		logger.ErrorContext(ctx, "failed to initialize application", "error", err)
 		fmt.Fprintln(os.Stderr, err)
 		os.Exit(ExitGeneral)
 	}
-	defer func() { _ = svc.Close() }()
+	defer func() {
+		if err := svc.Close(); err != nil {
+			logger.ErrorContext(ctx, "error during shutdown", "error", err)
+		}
+	}()
 
 	c := cli.New(svc, svc.NewMCPRunner(), os.Stdout, os.Stderr)
+	c.SetLogger(logger.With("component", "cli"))
 	c.SetTUIRunner(tui.NewRunner(svc, os.Stdin, os.Stdout))
 	if err := c.Run(ctx, os.Args[1:]); err != nil {
 		var ce *cli.CLIError
 		if errors.As(err, &ce) {
+			logger.ErrorContext(ctx, "command failed",
+				"error", ce.Error(),
+				"code", ce.Code,
+				"trace_id", traceID,
+			)
 			fmt.Fprintln(os.Stderr, ce.Error())
 			os.Exit(ce.Code)
 		}
+		logger.ErrorContext(ctx, "command failed",
+			"error", err,
+			"trace_id", traceID,
+		)
 		fmt.Fprintln(os.Stderr, err)
 		os.Exit(ExitGeneral)
 	}
+
+	logger.InfoContext(ctx, "command completed", "trace_id", traceID)
 }
 
 const ExitGeneral = 1

docs/runbooks.md

@@ -8,6 +8,18 @@ gitcontribute health
 
 Checks SQLite database integrity, GitHub API connectivity, and local filesystem state.
 
+## Deployment Observability
+
+**CI Pipeline**: https://github.com/morluto/gitcontribute/actions
+
+Monitor the CI workflow for build status, test coverage trends, and lint results.
+Coverage reports are uploaded as artifacts on each run.
+
+**Release Dashboard**: https://github.com/morluto/gitcontribute/releases
+
+Track version history and release notes. Each release is built via GoReleaser
+with cross-platform binaries and checksums.
+
 ## Database Integrity
 
 If SQLite corruption is detected:
@@ -25,6 +37,18 @@ If GitHub API rate limits are hit:
 2. Wait for the reset window (shown in `X-RateLimit-Reset` header)
 3. Reduce concurrent operations via `--concurrency` flag
 
+## Circuit Breaker
+
+The GitHub client uses a circuit breaker that opens after 5 consecutive failures.
+When the circuit is open, all requests fail fast with `ErrCircuitOpen` rather
+than retrying. After a 30-second cooldown, a single probe request is allowed.
+If the probe succeeds, the circuit closes; if it fails, the circuit re-opens.
+
+To check circuit status, enable debug logging:
+```sh
+GITCONTRIBUTE_LOG_LEVEL=debug gitcontribute sync owner/repo
+```
+
 ## Job Reconciliation
 
 If jobs appear stuck:

internal/app/app.go

@@ -5,6 +5,7 @@ import (
 	"encoding/json"
 	"errors"
 	"fmt"
+	"log/slog"
 	"net/http"
 	"os"
 	"path/filepath"
@@ -35,15 +36,16 @@ type Service struct {
 	archiveFetcher discovery.ArchiveFetcher
 	clock          func() time.Time
 	version        string
+	logger         *slog.Logger
 }
 
 // New creates a Service and resolves local configuration. GitHub credentials
 // are resolved lazily only when a network-reading operation is requested.
-func New(paths *config.Paths, version string) (*Service, error) {
+func New(paths *config.Paths, version string, logger *slog.Logger) (*Service, error) {
 	if paths == nil {
 		paths = config.NewPaths(nil)
 	}
-	s := &Service{paths: paths, version: version, clock: time.Now}
+	s := &Service{paths: paths, version: version, clock: time.Now, logger: logger}
 	if _, err := s.loadConfig(false); err != nil {
 		return nil, err
 	}

internal/app/app_test.go

@@ -179,7 +179,7 @@ func newTestService(t *testing.T, srv *httptest.Server) *Service {
 	t.Helper()
 	ctx := context.Background()
 	paths := config.NewPaths(&config.Env{Home: t.TempDir()})
-	svc, err := New(paths, "test")
+	svc, err := New(paths, "test", nil)
 	if err != nil {
 		t.Fatalf("new service: %v", err)
 	}
@@ -405,7 +405,7 @@ func TestLocalInitializationDoesNotResolveKeyringAuth(t *testing.T) {
 	if err := config.Save(configPath, cfg); err != nil {
 		t.Fatal(err)
 	}
-	svc, err := New(paths, "test")
+	svc, err := New(paths, "test", nil)
 	if err != nil {
 		t.Fatalf("local service construction resolved GitHub auth: %v", err)
 	}
@@ -444,7 +444,7 @@ func TestNewRejectsInvalidConfiguredTokenSource(t *testing.T) {
 		t.Fatal(err)
 	}
 
-	_, err = New(paths, "test")
+	_, err = New(paths, "test", nil)
 	if err == nil || !strings.Contains(err.Error(), "invalid token_source method") {
 		t.Fatalf("New error = %v, want invalid token source", err)
 	}
@@ -537,7 +537,7 @@ func TestMCPSearchRequiresCompleteRepositoryFilter(t *testing.T) {
 func TestSearchCodeUsesStoredSnapshotWithoutNetwork(t *testing.T) {
 	ctx := context.Background()
 	paths := config.NewPaths(&config.Env{Home: t.TempDir()})
-	svc, err := New(paths, "test")
+	svc, err := New(paths, "test", nil)
 	if err != nil {
 		t.Fatal(err)
 	}
@@ -564,7 +564,7 @@ func TestSearchCodeUsesStoredSnapshotWithoutNetwork(t *testing.T) {
 func TestInvestigationAndOpportunityFlow(t *testing.T) {
 	ctx := context.Background()
 	paths := config.NewPaths(&config.Env{Home: t.TempDir()})
-	svc, err := New(paths, "test")
+	svc, err := New(paths, "test", nil)
 	if err != nil {
 		t.Fatal(err)
 	}
@@ -649,7 +649,7 @@ func TestInvestigationAndOpportunityFlow(t *testing.T) {
 func TestPrepareContributionDrafts(t *testing.T) {
 	ctx := context.Background()
 	paths := config.NewPaths(&config.Env{Home: t.TempDir()})
-	svc, err := New(paths, "test")
+	svc, err := New(paths, "test", nil)
 	if err != nil {
 		t.Fatalf("new service: %v", err)
 	}
@@ -725,7 +725,7 @@ func TestPrepareContributionDrafts(t *testing.T) {
 func TestValidationDefineRunAndCompare(t *testing.T) {
 	ctx := context.Background()
 	paths := config.NewPaths(&config.Env{Home: t.TempDir()})
-	svc, err := New(paths, "test")
+	svc, err := New(paths, "test", nil)
 	if err != nil {
 		t.Fatalf("new service: %v", err)
 	}
@@ -794,7 +794,7 @@ func TestValidationDefineRunAndCompare(t *testing.T) {
 func TestDefineValidationParsesQuotedArguments(t *testing.T) {
 	ctx := context.Background()
 	paths := config.NewPaths(&config.Env{Home: t.TempDir()})
-	svc, err := New(paths, "test")
+	svc, err := New(paths, "test", nil)
 	if err != nil {
 		t.Fatal(err)
 	}
@@ -829,7 +829,7 @@ func TestWorkspaceCreateAndShow(t *testing.T) {
 	remote, baseSHA, candidateSHA := setupAppGitRemote(t)
 
 	paths := config.NewPaths(&config.Env{Home: t.TempDir()})
-	svc, err := New(paths, "test")
+	svc, err := New(paths, "test", nil)
 	if err != nil {
 		t.Fatalf("new service: %v", err)
 	}
@@ -935,7 +935,7 @@ func newLocalService(t *testing.T) *Service {
 	t.Helper()
 	ctx := context.Background()
 	paths := config.NewPaths(&config.Env{Home: t.TempDir()})
-	svc, err := New(paths, "test")
+	svc, err := New(paths, "test", nil)
 	if err != nil {
 		t.Fatalf("new service: %v", err)
 	}

internal/app/control_test.go

@@ -22,7 +22,7 @@ func (s failingAuthSource) Token(context.Context) (string, error) { return "", s
 
 func TestMetadataIsLocalAndDoesNotCreateCorpus(t *testing.T) {
 	paths := config.NewPaths(&config.Env{Home: t.TempDir()})
-	svc, err := New(paths, "v1.2.3")
+	svc, err := New(paths, "v1.2.3", nil)
 	if err != nil {
 		t.Fatal(err)
 	}
@@ -45,7 +45,7 @@ func TestMetadataIsLocalAndDoesNotCreateCorpus(t *testing.T) {
 
 func TestConfigureInvalidInputDoesNotReplaceFile(t *testing.T) {
 	paths := config.NewPaths(&config.Env{Home: t.TempDir()})
-	svc, err := New(paths, "test")
+	svc, err := New(paths, "test", nil)
 	if err != nil {
 		t.Fatal(err)
 	}
@@ -77,7 +77,7 @@ func TestConfigureInvalidInputDoesNotReplaceFile(t *testing.T) {
 
 func TestConfigureDryRunDoesNotSave(t *testing.T) {
 	paths := config.NewPaths(&config.Env{Home: t.TempDir()})
-	svc, err := New(paths, "test")
+	svc, err := New(paths, "test", nil)
 	if err != nil {
 		t.Fatal(err)
 	}
@@ -98,7 +98,7 @@ func TestConfigureDryRunDoesNotSave(t *testing.T) {
 
 func TestControlStatusUsesLocalCorpus(t *testing.T) {
 	paths := config.NewPaths(&config.Env{Home: t.TempDir()})
-	svc, err := New(paths, "test")
+	svc, err := New(paths, "test", nil)
 	if err != nil {
 		t.Fatal(err)
 	}
@@ -136,7 +136,7 @@ func TestDoctorDoesNotExposeEnvironmentToken(t *testing.T) {
 	secret := strings.Join([]string{"github_pat", "fixture-control-value"}, "_")
 	t.Setenv("GITCONTRIBUTE_TEST_TOKEN", secret)
 	paths := config.NewPaths(&config.Env{Home: t.TempDir()})
-	svc, err := New(paths, "test")
+	svc, err := New(paths, "test", nil)
 	if err != nil {
 		t.Fatal(err)
 	}
@@ -161,7 +161,7 @@ func TestDoctorDoesNotExposeEnvironmentToken(t *testing.T) {
 
 func TestDoctorInspectsEffectiveRuntimeConfig(t *testing.T) {
 	paths := config.NewPaths(&config.Env{Home: t.TempDir()})
-	svc, err := New(paths, "test")
+	svc, err := New(paths, "test", nil)
 	if err != nil {
 		t.Fatal(err)
 	}
@@ -189,7 +189,7 @@ func TestConfigureDoesNotPersistEnvOverrides(t *testing.T) {
 		t.Fatal(err)
 	}
 
-	svc, err := New(paths, "test")
+	svc, err := New(paths, "test", nil)
 	if err != nil {
 		t.Fatal(err)
 	}

internal/app/discovery_test.go

@@ -641,7 +641,7 @@ func newTestServiceNoNetwork(t *testing.T) *Service {
 	t.Helper()
 	ctx := context.Background()
 	paths := config.NewPaths(&config.Env{Home: t.TempDir()})
-	svc, err := New(paths, "test")
+	svc, err := New(paths, "test", nil)
 	if err != nil {
 		t.Fatalf("new service: %v", err)
 	}

internal/app/dossier_test.go

@@ -18,7 +18,7 @@ import (
 func TestBuildAndGetRepositoryDossier(t *testing.T) {
 	ctx := context.Background()
 	paths := config.NewPaths(&config.Env{Home: t.TempDir()})
-	svc, err := New(paths, "test")
+	svc, err := New(paths, "test", nil)
 	if err != nil {
 		t.Fatal(err)
 	}
@@ -143,7 +143,7 @@ func TestBuildAndGetRepositoryDossier(t *testing.T) {
 func TestExtractSeeds(t *testing.T) {
 	ctx := context.Background()
 	paths := config.NewPaths(&config.Env{Home: t.TempDir()})
-	svc, err := New(paths, "test")
+	svc, err := New(paths, "test", nil)
 	if err != nil {
 		t.Fatal(err)
 	}
@@ -273,7 +273,7 @@ func TestExtractSeeds(t *testing.T) {
 func TestExtractSeedsRequiresNoNetwork(t *testing.T) {
 	ctx := context.Background()
 	paths := config.NewPaths(&config.Env{Home: t.TempDir()})
-	svc, err := New(paths, "test")
+	svc, err := New(paths, "test", nil)
 	if err != nil {
 		t.Fatal(err)
 	}

internal/app/health_test.go

@@ -16,7 +16,7 @@ import (
 func TestRepositoryHealth(t *testing.T) {
 	ctx := context.Background()
 	paths := config.NewPaths(&config.Env{Home: t.TempDir()})
-	svc, err := New(paths, "test")
+	svc, err := New(paths, "test", nil)
 	if err != nil {
 		t.Fatal(err)
 	}