ProjectTracker/README.md

# ProjectTracker

**Multi-repository state tracker and coordinator for managing multiple Git projects.**

ProjectTracker scans all tracked repositories, detects changes, pulls updates, identifies conflicts, and generates human-readable summaries of the entire ecosystem state.

## Purpose

Managing 15+ active Git repositories manually is tedious and error-prone. ProjectTracker automates:

- **State Tracking**: Which repos have new commits, uncommitted changes, conflicts
- **Activity Monitoring**: Which projects are active vs dormant
- **Conflict Detection**: Automatic merge conflict identification
- **Categorization**: Organize projects by status (WIP, CONSTANT, PAUSE, etc.)
- **Reporting**: Generate readable summaries for quick ecosystem overview

## Structure

```
ProjectTracker/
├── tools/
│   ├── config.json          # Repository configuration and tracking settings
│   ├── scan.sh              # Main scanner script (bash)
│   └── analyze.py           # Summary generator (Python)
├── projects/
│   ├── META/                # Meta-projects (planning, infrastructure)
│   ├── CONSTANT/            # Ongoing/maintenance projects
│   ├── WIP/                 # Active development projects
│   ├── CONCEPT/             # Early-stage ideas
│   ├── PAUSE/               # Paused projects
│   └── DONE/                # Completed projects
├── .planning/               # Generated state files (auto-created)
│   ├── state.json           # Machine-readable repo state
│   ├── summary.md           # Human-readable summary
│   ├── scan.log             # Detailed scan logs
│   └── conflicts.txt        # List of repos with conflicts
├── .env                     # Gitea credentials and configuration
└── README.md                # This file
```

## Configuration

### 1. Environment Variables (`.env`)

```bash
GITEA_URL=https://git.etheryale.com
GITEA_TOKEN=your_token_here
```

**Note**: Use `wget` instead of `curl` for API calls due to proxy compatibility.

### 2. Repository Tracking (`tools/config.json`)

Define which repos to track, exclude, and categorize:

```json
{
  "repos_root": "C:/Users/alexi/Documents/projects",
  "tracked_repos": ["civjdr", "ChineseClass", "seogeneratorserver", ...],
  "excluded_repos": ["couple-repo", "vba-mcp-demo", ...],
  "project_mapping": {
    "civjdr": "projects/CONSTANT/civjdr.md",
    "ChineseClass": "projects/CONSTANT/ChineseClass.md",
    ...
  }
}
```

**Scan Options**:
- `auto_pull`: Automatically pull updates (default: true)
- `commits_lookback_days`: Activity window for "recent" commits (default: 21)
- `detect_uncommitted_changes`: Check for unstaged/uncommitted files (default: true)

## Usage

### Full Scan and Summary

```bash
cd ProjectTracker
bash tools/scan.sh
```

This will:
1. Fetch updates from all tracked repos
2. Pull changes (if `auto_pull: true`)
3. Detect conflicts, uncommitted changes, ahead/behind status
4. Generate `.planning/state.json` with full repo state
5. Run `analyze.py` to generate `.planning/summary.md`

### Generate Summary Only

If you already have a `state.json` and want to regenerate the summary:

```bash
python tools/analyze.py
```

### View Summary

```bash
cat .planning/summary.md
```

## Output Files

### state.json (Machine-Readable)

JSON snapshot of all repos with detailed metrics:

```json
{
  "last_scan": "2026-01-18T14:30:00+00:00",
  "repos": {
    "civjdr": {
      "last_commit": "abc1234",
      "branch": "main",
      "commits_3w": 8,
      "new_commits_since_last_scan": 2,
      "has_uncommitted_changes": false,
      "has_conflict": false,
      "needs_attention": true,
      ...
    }
  },
  "stats": {
    "total_repos": 18,
    "active_3w": 12,
    "needs_attention": 5,
    "conflicts": 1
  }
}
```

### summary.md (Human-Readable)

Markdown report with:
- **Global Stats**: Total repos, active count, attention needed, conflicts
- **Needs Attention**: Prioritized list (conflicts → uncommitted → new commits → behind)
- **By Category**: Repos organized by status (META, CONSTANT, WIP, etc.)
- **Recent Activity**: Commit counts for active repos (last 3 weeks)

Example:
```markdown
## ⚠️  Needs Attention

- **seogeneratorserver** (develop) - ❌ CONFLICT | 📝 7 uncommitted | 🆕 5 new
  Last: Update SEO templates (3 days ago)
- **ChineseClass** (main) - 📝 3 uncommitted | 🆕 2 new
  Last: Add vocabulary list (2 days ago)
```

## Project Categorization

Projects are organized by development status:

- **META**: Infrastructure, planning, coordination projects
- **CONSTANT**: Ongoing/maintenance projects (no end date)
- **WIP**: Active development (work in progress)
- **CONCEPT**: Early-stage ideas, prototypes
- **PAUSE**: Temporarily paused projects
- **DONE**: Completed projects (archived)

Each project has a corresponding `.md` file in `projects/<CATEGORY>/` with:
- Description
- Current status
- Repository URL
- Next steps
- Notes

## Workflow

1. **Daily/Weekly**: Run `scan.sh` to check ecosystem state
2. **Review**: Check `summary.md` for repos needing attention
3. **Act**: Address conflicts, commit changes, pull updates
4. **Repeat**: Keep repos synchronized and tracked

## Requirements

- **Bash**: For `scan.sh` (Git Bash on Windows, native on Linux/Mac)
- **Python 3.7+**: For `analyze.py`
- **jq**: JSON processor for bash script parsing
- **Git**: Obviously :)

## Notes

- Scanner automatically fetches before pulling
- Conflicts are never auto-resolved (manual intervention required)
- `state.json` tracks previous scan state to detect "new" commits
- All timestamps use ISO 8601 format
- UTF-8 encoding support for emoji indicators on all platforms

---

**Created**: 2026-01-18 (Cycle 2 - External Exploration)
**Purpose**: Coordinate multi-project ecosystem efficiently
**Maintained**: Active