chore: final polish for public release

- Add GitHub Actions CI
- Enhance git analyzer with branch age and drift detection
- Update rules engine for smarter nudges
- Update docs (README, CONTRIBUTING, rules)

Author: backslash-ux

.github/workflows/ci.yml

@@ -0,0 +1,36 @@
+name: Python CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
+
+    steps:
+      - uses: actions/checkout@v4
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install .[dev]
+
+      - name: Run tests with pytest
+        run: |
+          pytest tests/ -v --cov=src/flowcheck --cov-report=xml
+
+      - name: Upload coverage to Codecov
+        uses: codecov/codecov-action@v4
+        with:
+          file: ./coverage.xml
+          fail_ci_if_error: false

src/flowcheck/core/git_analyzer.py

@@ -75,8 +75,46 @@ def get_minutes_since_last_commit(repo: Repo) -> int:
         now = datetime.now(tz=timezone.utc)
         delta = now - commit_time
         return int(delta.total_seconds() / 60)
-    except (ValueError, GitCommandError):
-        # No commits in repository
+    except (ValueError, GitCommandError, AttributeError):
+        # No commits or detached HEAD with no history
+        return 0
+
+
+def get_branch_age_days(repo: Repo) -> int:
+    """Calculate the age of the current branch in days.
+
+    Age is measured from the first commit that is only in this branch.
+    """
+    try:
+        # Get the timestamp of the very first commit in this branch
+        commits = list(repo.iter_commits(
+            rev=repo.active_branch.name, reverse=True, max_count=1))
+        if not commits:
+            return 0
+        first_commit_date = commits[0].committed_date
+        dt = datetime.fromtimestamp(first_commit_date, tz=timezone.utc)
+        delta = datetime.now(tz=timezone.utc) - dt
+        return max(0, delta.days)
+    except Exception:
+        return 0
+
+
+def get_commits_behind_main(repo: Repo) -> int:
+    """Check how many commits the current branch is behind 'main' or 'master'."""
+    try:
+        main_name = "main" if "main" in repo.heads else "master" if "master" in repo.heads else None
+        if not main_name or repo.active_branch.name == main_name:
+            return 0
+
+        # Get merge-base
+        base = repo.merge_base(repo.active_branch, repo.heads[main_name])
+        if not base:
+            return 0
+
+        # Count commits on main after base
+        behind = list(repo.iter_commits(f"{base[0]}..{main_name}"))
+        return len(behind)
+    except Exception:
         return 0
 
 
@@ -148,6 +186,8 @@ def analyze_repo(repo_path: str) -> dict:
         - minutes_since_last_commit: Minutes since last commit
         - uncommitted_files: Count of changed files
         - uncommitted_lines: Total lines changed
+        - branch_age_days: Age of branch in days
+        - behind_main_by_commits: Count of commits behind main
 
     Raises:
         NotAGitRepositoryError: If path is not a valid Git repository.
@@ -157,10 +197,14 @@ def analyze_repo(repo_path: str) -> dict:
     branch_name = get_current_branch(repo)
     minutes_since_last_commit = get_minutes_since_last_commit(repo)
     uncommitted_files, uncommitted_lines = get_uncommitted_stats(repo)
+    branch_age_days = get_branch_age_days(repo)
+    behind_main_by_commits = get_commits_behind_main(repo)
 
     return {
         "branch_name": branch_name,
         "minutes_since_last_commit": minutes_since_last_commit,
         "uncommitted_files": uncommitted_files,
         "uncommitted_lines": uncommitted_lines,
+        "branch_age_days": branch_age_days,
+        "behind_main_by_commits": behind_main_by_commits,
     }

src/flowcheck/core/models.py

@@ -30,6 +30,8 @@ class FlowState:
     uncommitted_files: int
     branch_name: str
     status: Status
+    branch_age_days: int = 0
+    behind_main_by_commits: int = 0
 
     def to_dict(self) -> dict:
         """Convert to dictionary for JSON serialization."""
@@ -39,6 +41,8 @@ def to_dict(self) -> dict:
             "uncommitted_files": self.uncommitted_files,
             "branch_name": self.branch_name,
             "status": self.status.value,
+            "branch_age_days": self.branch_age_days,
+            "behind_main_by_commits": self.behind_main_by_commits,
         }
 
     @classmethod
@@ -50,4 +54,6 @@ def from_dict(cls, data: dict) -> "FlowState":
             uncommitted_files=data["uncommitted_files"],
             branch_name=data["branch_name"],
             status=Status(data["status"]),
+            branch_age_days=data.get("branch_age_days", 0),
+            behind_main_by_commits=data.get("behind_main_by_commits", 0),
         )

src/flowcheck/rules/engine.py

@@ -92,6 +92,20 @@ def generate_recommendations(
             f"Consider grouping related changes into separate commits."
         )
 
+    # Branch age recommendation
+    if flow_state.branch_age_days > 7:
+        recommendations.append(
+            f"🌿 This branch is {flow_state.branch_age_days} days old. "
+            f"Consider finishing up or merging to avoid long-lived branches."
+        )
+
+    # Main branch sync recommendation
+    if flow_state.behind_main_by_commits > 10:
+        recommendations.append(
+            f"🔄 You are behind main by {flow_state.behind_main_by_commits} commits. "
+            f"Consider merging main into your branch to stay up to date and avoid conflicts."
+        )
+
     # All good message
     if not recommendations:
         recommendations.append(
@@ -126,4 +140,6 @@ def build_flow_state(
         uncommitted_files=raw_metrics["uncommitted_files"],
         branch_name=raw_metrics["branch_name"],
         status=status,
+        branch_age_days=raw_metrics.get("branch_age_days", 0),
+        behind_main_by_commits=raw_metrics.get("behind_main_by_commits", 0),
     )