[repository-quality] 🎯 Repository Quality: Debug Observability & Test Build Tag Compliance (2026-06-02)

[github-actions[bot]]

🎯 Repository Quality Improvement Report - Debug Observability & Test Build Tag Compliance

Analysis Date: 2026-06-02 | Strategy: Custom

Executive Summary

Two compliance gaps identified: (1) 5 test files in pkg/workflow and pkg/cli missing the mandatory //go:build !integration tag (AGENTS.md), and (2) 32 source files >300 lines with zero debug logger instrumentation — creating blindspots in critical subsystems including action updates, MCP tool dispatch, and workflow compilation.

The build tag fix is mandatory: 1,233 of 1,238 test files comply (99.6%), but 5 remain. The logger gap is systemic: update_actions.go (775L), gateway_logs_timeline_render.go (725L), compiler_activation_job_builder.go (668L), and mcp_tools_privileged.go (631L) operate with no DEBUG=* visibility.

Full Metrics & Analysis

Metric	Value	Status
Test files with build tags	1,233 / 1,238	⚠️
Test files missing build tags	5	❌
pkg/cli files without logger	50 / 309 (16%)	⚠️
pkg/workflow files without logger	97 / 394 (25%)	⚠️
Source files >300L without logger	32	❌
Source files >500L without logger	10	❌

Test Files Missing Build Tags

File	Has Test* functions?
pkg/workflow/compilerenv/manager_test.go	Yes
pkg/workflow/compiler_test_helpers_test.go	No (helpers)
pkg/workflow/tools_defaults_test.go	Yes
pkg/workflow/test_helpers_shared_test.go	No (helpers)
pkg/cli/test_helpers_git_test.go	No (helpers)

Largest Files Without Logger

File	Lines
pkg/cli/update_actions.go	775
pkg/cli/gateway_logs_timeline_render.go	725
pkg/cli/update_workflows.go	689
pkg/workflow/compiler_activation_job_builder.go	668
pkg/cli/mcp_tools_privileged.go	631
pkg/workflow/side_repo_maintenance.go	626
pkg/cli/logs_run_processor.go	554
pkg/cli/includes.go	552
pkg/cli/mcp_tools_readonly.go	492
pkg/workflow/permissions_validation.go	484

---

🤖 Tasks for Copilot Agent

NOTE TO PLANNER AGENT: Split the following tasks into individual work items.

Task 1: Add Missing //go:build !integration Tags to 5 Test Files

Priority: High | Effort: Small

Description: Add mandatory //go:build !integration as line 1 (+ blank line) to 5 non-compliant test files. The 3 helper-only files (no Test* functions) should also receive a package-level doc comment clarifying their purpose.

Acceptance Criteria:

• //go:build !integration is line 1 of each file, followed by blank line
• make build && make fmt && make test-unit passes

Code Region: pkg/workflow/compilerenv/manager_test.go, pkg/workflow/compiler_test_helpers_test.go, pkg/workflow/tools_defaults_test.go, pkg/workflow/test_helpers_shared_test.go, pkg/cli/test_helpers_git_test.go

Add the mandatory `//go:build !integration` build tag to 5 test files (AGENTS.md policy):
1. `pkg/workflow/compilerenv/manager_test.go`
2. `pkg/workflow/compiler_test_helpers_test.go`
3. `pkg/workflow/tools_defaults_test.go`
4. `pkg/workflow/test_helpers_shared_test.go`
5. `pkg/cli/test_helpers_git_test.go`

Insert `//go:build !integration` as line 1, blank line after. Files 2, 4, 5 have no Test* functions — add a doc comment like `// Package workflow provides shared test helpers.`

Validate: `make build && make fmt && make test-unit`

---

Task 2: Add Debug Logger to update_actions.go and update_workflows.go

Priority: High | Effort: Medium

Description: Two large CLI files (775+689 lines) handling action pinning and workflow updates have no debug logging. Add logger.New("cli:update_actions") and logger.New("cli:update_workflows"), instrument ≥5 decision points each.

Acceptance Criteria:

• Package-level var log = logger.New("cli:update_*") in each file
• ≥5 log.Printf(...) calls covering: entry, key branches, errors, outcomes
• make build && make fmt && make lint passes

Code Region: pkg/cli/update_actions.go, pkg/cli/update_workflows.go

Add debug loggers to two large, un-instrumented CLI files:

`pkg/cli/update_actions.go` (775 lines): Add `var updateActionsLog = logger.New("cli:update_actions")`. Log at: scan start, per-action processing, version resolution, pin/skip decision, final counts.

`pkg/cli/update_workflows.go` (689 lines): Add `var updateWorkflowsLog = logger.New("cli:update_workflows")`. Log at: workflow discovery, each update step, writes, errors.

Import: `"github.com/github/gh-aw/pkg/logger"`. See `pkg/cli/compile_command.go` for pattern.
Validate: `make build && make fmt && make lint`

---

Task 3: Add Debug Logger to Workflow Compiler Files

Priority: Medium | Effort: Medium

Description: compiler_activation_job_builder.go (668L) and side_repo_maintenance.go (626L) are on the hot path for gh aw compile with no trace capability. Add workflow:activation_job_builder and workflow:side_repo_maintenance loggers.

Acceptance Criteria:

• Package-level logger with workflow: namespace in each file
• Key builder functions log trigger type, step decisions, output counts
• make build && make fmt && make lint && go test -run "TestCompile" ./pkg/workflow/ passes

Code Region: pkg/workflow/compiler_activation_job_builder.go, pkg/workflow/side_repo_maintenance.go

Add debug loggers to two workflow compiler files:

`pkg/workflow/compiler_activation_job_builder.go` (668 lines): Add `var activationJobLog = logger.New("workflow:activation_job_builder")`. Log at: build entry/trigger type, condition decisions, step additions, output job name.

`pkg/workflow/side_repo_maintenance.go` (626 lines): Add `var sideRepoLog = logger.New("workflow:side_repo_maintenance")`. Log at: generation entry, maintenance steps added, feature flag checks, final count.

Validate: `make build && make fmt && make lint && go test -v -run "TestCompile" ./pkg/workflow/`

---

Task 4: Add Debug Logger to MCP Tool Handler Files

Priority: Medium | Effort: Medium

Description: mcp_tools_privileged.go (631L) and mcp_tools_readonly.go (492L) define all MCP tool handlers without debug trace. Privileged MCP invocation failures are completely opaque without DEBUG=cli:*.

Acceptance Criteria:

• logger.New("cli:mcp_tools_privileged") and logger.New("cli:mcp_tools_readonly") added
• Tool registration and invocation paths logged
• make build && make fmt && make lint passes

Code Region: pkg/cli/mcp_tools_privileged.go, pkg/cli/mcp_tools_readonly.go

Add debug loggers to two MCP tool files:

`pkg/cli/mcp_tools_privileged.go` (631 lines): Add `var mcpToolsPrivLog = logger.New("cli:mcp_tools_privileged")`. Log at: tool registration, each invocation entry, permission outcomes, errors.

`pkg/cli/mcp_tools_readonly.go` (492 lines): Add `var mcpToolsROLog = logger.New("cli:mcp_tools_readonly")`. Log at: tool registration, each invocation, result sizes, errors.

Validate: `make build && make fmt && make lint`

---

📊 Historical Context

Previous Focus Areas (9 runs)

Date	Focus Area	Custom
2026-05-20	Large File Refactoring	Y
2026-05-21	Error Message Quality	Y
2026-05-22	MCP Integration Robustness	Y
2026-05-25	Test Infrastructure & Build Tags	Y
2026-05-26	Go Dependency Hygiene	Y
2026-05-27	Agentic Workflow Runtime Safety	Y
2026-05-28	Semantic Constant Adoption	Y
2026-05-29	CI/CD Pipeline Resilience	N
2026-06-01	Command Registration Architecture	Y

---

🎯 Recommendations

Immediate (This Week)

1. Fix build tags on 5 test files — mandatory policy compliance
2. Add loggers to update_actions.go and update_workflows.go

Short-term (This Month)

1. Logger for workflow compiler files (Tasks 3–4)

Long-term (This Quarter)

1. Custom linter: flag files >200 lines with no logger call

📈 Success Metrics

• Build tag compliance: 5 missing → 0
• Files >300L without logger: 32 → <20
• Files >500L without logger: 10 → <5

References: §26825499430

Generated by ⚡ Repository Quality Improvement Agent · sonnet46 2.9M · ◷

• expires on Jun 3, 2026, 2:24 PM UTC

[github-actions[bot]]

This discussion has been marked as outdated by Repository Quality Improvement Agent.

A newer discussion is available at Discussion #36655.