[q] Add Daily Code Metrics Workflow with Trend Tracking

[github-actions]

Q Workflow Optimization Report

Context

This pull request addresses the request from discussion #3605 to create a daily workflow that computes code/codebase size and quality metrics and provides trends over time.

Issues Found (from Analysis)

Current State Assessment

Log Analysis Summary:

• No existing code metrics workflow was found in the repository
• Existing workflows like lockfile-stats and duplicate-code-detector provide partial coverage but don't track comprehensive metrics over time
• No persistent trend tracking mechanism exists for codebase health

Workflow Patterns Identified:

• Repository has 79 agentic workflows tracking various aspects
• Several workflows use cache-memory for persistence (lockfile-stats.md)
• Strong pattern of using bash tools for analysis
• Safe-outputs (create-discussion) pattern well-established for reporting

Changes Made

New Workflow: daily-code-metrics.md

Created a comprehensive daily code metrics tracking workflow that:

1. Tracks Multiple Metric Categories

Codebase Size Metrics:

• Lines of Code (LOC) by language (Go, JavaScript/CJS, YAML, Markdown)
• LOC by directory (cmd/, pkg/, workflows/)
• File counts and distribution
• Directory structure analysis

Code Quality Metrics:

• Complexity indicators (function sizes, nesting depth)
• Code organization metrics
• Comment-to-code ratio
• Large file detection

Test Coverage Metrics:

• Test file counts and distribution
• Test-to-source LOC ratio
• Test organization patterns

Code Churn Metrics (7-day window):

• Files modified
• Lines added/deleted
• Commit frequency
• Most active areas

Workflow Metrics:

• Agentic workflow statistics
• Engine distribution
• Trigger patterns

Documentation Metrics:

• Doc file coverage
• Code-to-docs ratio

2. Implements Persistent Trend Tracking

• Cache Storage: Uses /tmp/gh-aw/cache-memory/metrics/ for persistent data
• Data Format: JSON Lines (.jsonl) for efficient time-series storage
• Historical Analysis: Tracks 30+ days of historical data
• Trend Calculations:
  • 7-day trends (percentage change)
  • 30-day trends (percentage change)
  • Growth rates and volatility indicators

3. Generates Comprehensive Reports

• Executive Summary: High-level metrics with trends
• Detailed Tables: Current vs 7-day vs 30-day comparisons
• Visual Charts: ASCII-based trend visualizations
• Quality Score: Composite score (0-100) based on multiple factors
• Insights & Recommendations: Actionable findings

4. Configuration Details

engine: claude                    # Using Claude for comprehensive analysis
tools:
  cache-memory:
    - id: metrics                 # Persistent storage for trends
      key: code-metrics-${{ github.workflow }}
  bash:                           # Bash tools for data collection
safe-outputs:
  create-discussion:              # Publishes to audits category
    category: "audits"
schedule:
  - cron: "0 8 * * *"            # Daily at 8 AM UTC
timeout-minutes: 15               # Adequate time for analysis
strict: true                      # Enhanced validation

Expected Improvements

Visibility & Tracking

1. Daily Metrics Snapshot: Automated daily collection eliminates manual tracking
2. Trend Detection: Identifies growth patterns, code churn spikes, quality degradation
3. Historical Context: Builds 30+ day history for informed decision-making

Code Quality Insights

4. Quality Score Tracking: Composite metric (0-100) tracks overall codebase health
5. Complexity Monitoring: Detects increasing complexity early
6. Test Coverage Trends: Monitors test-to-code ratio changes

Actionable Intelligence

7. Automated Reports: Published to audits discussion category for team visibility
8. Anomaly Detection: Highlights unusual changes (>10% spikes)
9. Recommendation Engine: Provides context-based suggestions

Team Alignment

10. Shared Metrics: Common baseline for discussions about code health
11. Progress Tracking: Shows impact of refactoring efforts over time
12. Data-Driven Decisions: Objective metrics inform technical debt prioritization

Validation

Compilation Status: ✅ Workflow compiled successfully

✓ .github/workflows/daily-code-metrics.md (211.9 KB)
✓ Compiled 1 workflow(s): 0 error(s), 0 warning(s)

Note: The .lock.yml file will be generated automatically after merge as per Q workflow guidelines.

Implementation Notes

Cache Memory Strategy

• Persistence: GitHub Actions cache preserves data across runs
• Format: JSON Lines for efficient append operations
• Retention: Last 90 days retained in history
• Recovery: Graceful handling of missing historical data

Metric Collection Efficiency

• Optimized Commands: Uses efficient bash one-liners
• Selective Analysis: Excludes .git and node_modules
• Parallel Processing: Where applicable, metrics collected concurrently
• Resource-Aware: Stays within 15-minute timeout

Report Quality

• Markdown Formatting: Clean, readable tables and charts
• Visual Indicators: Emoji trend markers (⬆️➡️⬇️)
• ASCII Charts: Terminal-friendly visualizations
• Structured Sections: Easy navigation and reference

Related Workflows

This workflow complements existing analysis workflows:

• lockfile-stats: Focuses on .lock.yml files
• duplicate-code-detector: Identifies code duplication
• daily-test-improver: Improves test coverage
• daily-perf-improver: Performance optimization

Together they provide comprehensive codebase health monitoring.

Future Enhancements

Potential follow-up improvements:

1. Alerting: Notify on significant metric changes (>20% swings)
2. Benchmarking: Compare against repository/industry standards
3. Predictive Trends: ML-based forecasting of metric trajectories
4. Cross-Repo Comparison: Compare metrics across similar repositories
5. Integration: Link to CI/CD pipeline for PR-level metrics

References

• Triggering Request: Discussion Daily Status - 2025-11-11 #3605 - "/q update daily with computing various code / codebase size/quality metrics and provide trends"
• Pattern Sources:
  • lockfile-stats.md - Cache memory persistence pattern
  • duplicate-code-detector.md - Serena code analysis pattern
  • repo-tree-map.md - Bash-based repository analysis pattern
• Best Practices Research: Code quality metrics automation from Tavily search

---

Files Modified:

• ✅ .github/workflows/daily-code-metrics.md (new workflow, 461 lines)

Lock Files:

• ⏭️ .lock.yml will be generated post-merge (not included in PR)

Validation:

• ✅ Compiled successfully with gh aw compile
• ✅ No errors or warnings
• ✅ Strict mode validation passed

AI generated by Q

---

Note

This was originally intended as a pull request, but the git push operation failed.

Workflow Run: View run details and download patch artifact

The patch file is available as an artifact (aw.patch) in the workflow run linked above.
To apply the patch locally:

# Download the artifact from the workflow run https://github.com/githubnext/gh-aw/actions/runs/19272752901
# (Use GitHub MCP tools if gh CLI is not available)
gh run download 19272752901 -n aw.patch
# Apply the patch
git am aw.patch

Show patch preview (500 of 502 lines)

From 709e385a7d9b56944240556d776f16aed36f8dcc Mon Sep 17 00:00:00 2001
From: "github-actions[bot]" <github-actions[bot]@users.noreply.github.com>
Date: Tue, 11 Nov 2025 17:04:02 +0000
Subject: [PATCH] Add daily code metrics workflow with trend tracking

- Tracks comprehensive codebase metrics (LOC, file counts, complexity)
- Monitors code quality indicators and test coverage
- Analyzes code churn and change patterns
- Uses persistent cache for historical trend analysis
- Generates daily reports with 7-day and 30-day trends
- Publishes findings to audits discussion category
- Runs daily at 8 AM UTC

Metrics tracked:
- Codebase size (LOC by language, files, directories)
- Code quality (file sizes, complexity indicators)
- Test coverage ratios
- Code churn (commits, lines changed)
- Workflow statistics
- Documentation coverage

Implements trend analysis showing:
- Percentage changes over 7 and 30 day periods
- Growth rates and volatility
- Quality score composite (0-100)
- Visual charts and trend indicators
---
 .github/workflows/daily-code-metrics.md | 461 ++++++++++++++++++++++++
 1 file changed, 461 insertions(+)
 create mode 100644 .github/workflows/daily-code-metrics.md

diff --git a/.github/workflows/daily-code-metrics.md b/.github/workflows/daily-code-metrics.md
new file mode 100644
index 0000000..00e8846
--- /dev/null
+++ b/.github/workflows/daily-code-metrics.md
@@ -0,0 +1,461 @@
+---
+name: Daily Code Metrics
+on:
+  schedule:
+    - cron: "0 8 * * *"  # Daily at 8 AM UTC
+  workflow_dispatch:
+permissions:
+  contents: read
+  issues: read
+  pull-requests: read
+engine: claude
+tools:
+  cache-memory:
+    - id: metrics
+      key: code-metrics-${{ github.workflow }}
+  bash:
+safe-outputs:
+  create-discussion:
+    category: "audits"
+    max: 1
+timeout-minutes: 15
+strict: true
+imports:
+  - shared/reporting.md
+---
+
+# Daily Code Metrics & Quality Trends Agent
+
+You are the Code Metrics & Quality Trends Agent - an expert system that tracks, analyzes
... (truncated)