Dashboard 2.0 - Commit-Task Linking Guide

🎯 Overview

Dashboard 2.0 automatically links git commits to tasks using:

Explicit References: #123, task-123, fixes #456
Inferred Matching: AI-powered similarity matching
Confidence Scores: 0.0-1.0 (only ≥0.3 are stored)

This enables you to see which commits contribute to each task and track feature progress through git history.

📊 How It Appears in Dashboard

Activity Timeline

Commits appear in the "What's Happening?" quadrant:

📝 API Test: Test commit for API validation
   Linked to: Initialize project structure (#1091)
   Confidence: 100% (explicit)
   2 hours ago

Task Detail View

Each task shows linked commits:

Task #1091: Initialize project structure
Status: ✅ Completed

Commits (3):
  • abc123de - feat: Complete project setup #1091 (100%)
  • def456gh - docs: Add project README (86%)
  • ghi789jk - fix: Correct directory structure (72%)

🔧 Setup Methods

Method 1: Git Post-Commit Hook (Automatic)

Install the hook to send commits automatically after each commit:

Installation:

# Navigate to your repository
cd /path/to/your/repo

# Copy the post-commit hook
cp /path/to/dashboard-2.0/poc/git-hooks/post-commit .git/hooks/

# Make it executable
chmod +x .git/hooks/post-commit

# Configure Dashboard API URL (if not localhost:5001)
# Edit .git/hooks/post-commit and change API_URL

What happens:

Every git commit automatically sends commit data to Dashboard API
Linking happens in real-time (< 100ms)
No manual intervention needed

Example commit message:

git commit -m "feat: Implement user authentication #1091

Added JWT token generation and validation.
Closes task-1092 for password hashing."

Result: Automatically linked to tasks #1091 and #1092

Method 2: GitHub Actions (CI/CD)

Create .github/workflows/dashboard-sync.yml:

name: Dashboard 2.0 Sync

on:
  push:
    branches: [ main, develop ]

jobs:
  sync-commits:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout code
        uses: actions/checkout@v3
        with:
          fetch-depth: 0  # Get full history

      - name: Send commits to Dashboard
        env:
          DASHBOARD_API_URL: ${{ secrets.DASHBOARD_API_URL }}
        run: |
          # Get commits since last push
          COMMITS=$(git log origin/main..HEAD --pretty=format:'{
            "sha": "%H",
            "message": "%B",
            "author": "%an",
            "timestamp": "%cI"
          },')

          # Send to Dashboard API
          echo "[$COMMITS]" | jq -c '.[]' | while read commit; do
            curl -X POST "$DASHBOARD_API_URL/api/v1/git/commits" \
              -H "Content-Type: application/json" \
              -d "$commit"
          done

Configuration:

Add DASHBOARD_API_URL secret to GitHub repository settings
Set to your Dashboard API endpoint (e.g., https://dashboard.example.com)

Method 3: Manual Sync Script

Use the included test script for manual syncing:

cd /path/to/dashboard-2.0/poc

# Send latest commit
./test-commit-linking.sh

# Or use curl directly:
curl -X POST http://localhost:5001/api/v1/git/commits \
  -H "Content-Type: application/json" \
  -d '{
    "sha": "'"$(git rev-parse HEAD)"'",
    "message": "'"$(git log -1 --pretty=%B)"'",
    "author": "'"$(git log -1 --pretty=format:'%an')"'",
    "timestamp": "'"$(git log -1 --pretty=format:'%cI')"'",
    "repo_name": "'"$(basename $(git rev-parse --show-toplevel))"'",
    "repo_url": "'"$(git remote get-url origin)"'"
  }'

📝 Commit Message Best Practices

Explicit Task References

Pattern 1: #123 (GitHub style)

feat: Add user authentication #1091

Implemented JWT token generation with RS256 signing.

→ Links to task #1091 (100% confidence)

Pattern 2: task-123

fix: Resolve database connection timeout task-1092

Updated connection pool settings to prevent timeouts.

→ Links to task #1092 (100% confidence)

Pattern 3: Multiple tasks

refactor: Reorganize project structure #1091 #1093

- Updated directory layout
- Moved configuration files
- Closes task-1095 (duplicate)

→ Links to tasks #1091, #1093, #1095 (100% confidence)

Conventional Commit Format

Use conventional commits for better categorization:

<type>(<scope>): <description> #<task-id>

<body>

<footer>

Types:

feat: - New feature
fix: - Bug fix
docs: - Documentation
refactor: - Code refactoring
test: - Adding tests
chore: - Maintenance

Example:

feat(auth): Implement JWT authentication #1091

Added RS256 token signing and validation middleware.
Includes user session management with 24h expiry.

Closes #1091

Inferred Matching (No Explicit Reference)

If you forget the task ID, the system will try to match by similarity:

Task Title: "Implement user authentication system with JWT"

Commit Message:

feat: Add JWT authentication system

Implemented token generation and validation.

→ Automatically linked with ~86% confidence (inferred)

🔍 How Linking Works

1. Explicit Reference Detection

Regex patterns:

#\d+           → #1091
task-\d+       → task-1091
fixes #\d+     → fixes #1091
closes #\d+    → closes #1091

Confidence: 100% (explicit reference)

2. Title Similarity Matching

Uses TF-IDF (Term Frequency-Inverse Document Frequency) to compare:

Commit message vs. task title
Commit message vs. task description

Scoring:

90-100%: Very high confidence (likely correct)
70-89%: High confidence (probable match)
50-69%: Medium confidence (possible match)
30-49%: Low confidence (stored but flagged)
< 30%: Not stored (too uncertain)

3. Project Context

Links are scoped to projects:

Commits automatically associated with default project
Or use project_id in webhook payload for multi-project repos

📡 API Endpoints

POST /api/v1/git/commits

Send commit data for automatic task linking.

Request:

{
  "sha": "abc123def456",
  "message": "feat: Complete project setup #1091\n\nAdded directory structure and config files.",
  "author": "Hal Casteel",
  "timestamp": "2025-11-28T00:30:00Z",
  "repo_name": "dashboard-2.0-poc",
  "repo_url": "https://github.com/example/dashboard-2.0-poc"
}

Response:

{
  "commit_sha": "abc123def456",
  "links_created": 2,
  "links": [
    {
      "task_id": 1091,
      "task_title": "Initialize project structure",
      "confidence": 1.0,
      "link_type": "explicit",
      "evidence": "Explicit reference: #1091"
    },
    {
      "task_id": 1093,
      "task_title": "Configure CI/CD pipeline",
      "confidence": 0.86,
      "link_type": "inferred",
      "evidence": "Title match: 96%"
    }
  ]
}

GET /api/v1/git/commits/{sha}/tasks

Get all tasks linked to a specific commit.

Response:

{
  "commit_sha": "abc123def456",
  "tasks": [
    {
      "task_id": 1091,
      "title": "Initialize project structure",
      "checked": true,
      "confidence": 1.0
    }
  ]
}

GET /api/v1/tasks/{id}?links=true

Get task with all linked commits.

Response:

{
  "id": 1091,
  "title": "Initialize project structure",
  "checked": true,
  "commits": [
    {
      "sha": "abc123def456",
      "message": "feat: Complete project setup #1091",
      "author": "Hal Casteel",
      "timestamp": "2025-11-28T00:30:00Z",
      "confidence": 1.0
    }
  ]
}

🎨 Dashboard Visualization

Activity Timeline (Quadrant 3): Shows most recent commits (max 5) linked to tasks:

Commit icon: 📝
Priority: 50 (medium - between task events and LLM sessions)
Includes: commit message, linked tasks, time ago

Kanban Board

Tasks show commit count badges:

✅ Initialize project structure (#1091)
   📝 3 commits | 🔗 2 PRs | 💬 5 sessions

Project Detail View

Commit History Tab:

All commits linked to project tasks
Filterable by task, author, date range
Shows confidence scores for inferred links

🚀 Quick Start

1. Install git hook (5 minutes)

cd your-repo
cp dashboard-2.0/poc/git-hooks/post-commit .git/hooks/
chmod +x .git/hooks/post-commit

2. Start making commits with task references

git commit -m "feat: Implement authentication #1091"

3. View in Dashboard

Open http://localhost:8082
Check "What's Happening?" quadrant
See commit linked to task #1091

4. Verify linking worked

curl http://localhost:5001/api/v1/git/commits/$(git rev-parse HEAD)/tasks

🔧 Troubleshooting

Commits Not Appearing in Dashboard

Problem: Commits sent but not showing in activity feed

Solutions:

Check API is running: curl http://localhost:5001/api/health
Verify commit was received: Check API logs
Ensure task IDs exist: curl http://localhost:5001/api/v1/tasks | grep <task-id>
Hard refresh dashboard: Cmd+Shift+R (Mac) or Ctrl+Shift+F5 (Windows)

Links Not Created

Problem: Commit received but 0 links created

Possible causes:

Task doesn't exist: Reference #123 but no task with ID 123
Wrong project: Commit sent to different project than task belongs to
Low confidence: Inferred match < 0.3 threshold (not stored)

Debug:

# Check if task exists
curl http://localhost:5001/api/v1/tasks/1091

# Check commit was stored
curl http://localhost:5001/api/v1/git/commits/<sha>/tasks

# Check API logs for linking errors
tail -f backend/logs/api.log

Duplicate Links

Problem: Same commit linked multiple times

Solution: Commit webhook should be idempotent (SHA is unique)

Re-sending same SHA updates existing commit, doesn't duplicate
Check git hook isn't running multiple times

📈 Advanced Features

LLM Session Linking

Dashboard also links Claude Code sessions to tasks:

# POST /api/v1/llm/sessions
{
  "session_id": "session-123",
  "messages": [...],
  "timestamp": "2025-11-28T00:30:00Z"
}

Sessions are analyzed for task references and appear in activity feed.

Multi-Repository Support

For monorepos or multiple projects:

Send project_id in webhook:

{
  "sha": "abc123",
  "message": "feat: Update dashboard",
  "project_id": 7
}

Or use repo_name for auto-project mapping:
- API auto-creates projects based on repo_name
- Links commits to correct project

Confidence Thresholds

Configure in backend/linkers.py:

CONFIDENCE_THRESHOLD = 0.3  # Default: 30%

# Adjust for stricter or looser matching:
CONFIDENCE_THRESHOLD = 0.5  # Stricter (50%)
CONFIDENCE_THRESHOLD = 0.2  # Looser (20%)

📚 Next Steps

Install git hook - Automate commit tracking
Configure GitHub Actions - CI/CD integration
Standardize commit messages - Use conventional commits
Monitor dashboard - Watch task progress via commits
Review confidence scores - Tune thresholds if needed

Questions? Check /docs/dashboard-2.0/phase-2b-complete.md for API details.

Dashboard URL: http://localhost:8082 API URL: http://localhost:5001

Last Updated: November 28, 2025 Version: Dashboard 2.0 POC - Phase 3 Complete

🎯 Overview​

📊 How It Appears in Dashboard​

Activity Timeline​

Task Detail View​

🔧 Setup Methods​

Method 1: Git Post-Commit Hook (Automatic)​

Method 2: GitHub Actions (CI/CD)​

Method 3: Manual Sync Script​

📝 Commit Message Best Practices​

Explicit Task References​

Conventional Commit Format​

Inferred Matching (No Explicit Reference)​

🔍 How Linking Works​

1. Explicit Reference Detection​

2. Title Similarity Matching​

3. Project Context​

📡 API Endpoints​

POST /api/v1/git/commits​

GET /api/v1/git/commits/{sha}/tasks​

GET /api/v1/tasks/{id}?links=true​

🎨 Dashboard Visualization​

GPS Navigation Dashboard​

Kanban Board​

Project Detail View​

🚀 Quick Start​

🔧 Troubleshooting​

Commits Not Appearing in Dashboard​

Links Not Created​

Duplicate Links​

📈 Advanced Features​

LLM Session Linking​

Multi-Repository Support​

Confidence Thresholds​

📚 Next Steps​

🎯 Overview

📊 How It Appears in Dashboard

Activity Timeline

Task Detail View

🔧 Setup Methods

Method 1: Git Post-Commit Hook (Automatic)

Method 2: GitHub Actions (CI/CD)

Method 3: Manual Sync Script

📝 Commit Message Best Practices

Explicit Task References

Conventional Commit Format

Inferred Matching (No Explicit Reference)

🔍 How Linking Works

1. Explicit Reference Detection

2. Title Similarity Matching

3. Project Context

📡 API Endpoints

POST /api/v1/git/commits

GET /api/v1/git/commits/{sha}/tasks

GET /api/v1/tasks/{id}?links=true

🎨 Dashboard Visualization

GPS Navigation Dashboard

Kanban Board

Project Detail View

🚀 Quick Start

🔧 Troubleshooting

Commits Not Appearing in Dashboard

Links Not Created

Duplicate Links

📈 Advanced Features

LLM Session Linking

Multi-Repository Support

Confidence Thresholds

📚 Next Steps