feat: staleness detection — specsync stale command + check --stale flag (#189)

* feat: staleness detection — `specsync stale` command + check --stale flag (#188)

Add git-based staleness detection to warn when source files have changed
but specs haven't been updated. Three integration points:

- New `specsync stale` subcommand: focused detection with per-file details,
  all output formats (text/json/markdown), configurable threshold (default 5)
- `specsync check --stale[=N]`: integrates git drift warnings into check
- Scoring freshness: penalizes specs 5+ commits behind source files

Extracted git helpers from report.rs into shared git_utils.rs module.
Full specs for git_utils and cmd_stale. 100% file/LOC coverage maintained.

Closes #188

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* fix(ci): add missing requirements.md for cmd_stale and git_utils specs

CI uses --strict which treats warnings as errors. The two new specs
were missing companion requirements.md files.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>

Author: corvid-agent

specs/cmd_check/cmd_check.spec.md

@@ -9,6 +9,7 @@ tracks: []
 depends_on:
   - specs/commands/commands.spec.md
   - specs/ai/ai.spec.md
+  - specs/git_utils/git_utils.spec.md
   - specs/hash_cache/hash_cache.spec.md
   - specs/ignore/ignore.spec.md
   - specs/output/output.spec.md

specs/cmd_report/cmd_report.spec.md

@@ -8,6 +8,7 @@ db_tables: []
 tracks: []
 depends_on:
   - specs/commands/commands.spec.md
+  - specs/git_utils/git_utils.spec.md
   - specs/parser/parser.spec.md
   - specs/types/types.spec.md
   - specs/validator/validator.spec.md

specs/cmd_stale/cmd_stale.spec.md

@@ -0,0 +1,79 @@
+---
+module: cmd_stale
+version: 1
+status: stable
+files:
+  - src/commands/stale.rs
+db_tables: []
+tracks:
+  - 188
+depends_on:
+  - specs/commands/commands.spec.md
+  - specs/git_utils/git_utils.spec.md
+  - specs/parser/parser.spec.md
+  - specs/types/types.spec.md
+---
+
+# Cmd Stale
+
+## Purpose
+
+Implements the `specsync stale` command — a focused staleness detection tool that identifies specs whose source files have diverged via git commit history. Reports which specs need updating, how many commits they are behind, and which specific source files have drifted. Supports text, JSON, markdown, and GitHub output formats.
+
+## Public API
+
+### Exported Functions
+
+| Function | Parameters | Returns | Description |
+|----------|-----------|---------|-------------|
+| `cmd_stale` | `root: &Path, format: OutputFormat, threshold: usize` | `()` | Detect and report stale specs based on git commit distance |
+
+## Invariants
+
+1. Staleness is determined by `git_commits_between`: a spec is stale when any source file has >= `threshold` commits since the spec was last modified (default: 5)
+2. Specs with no `files` in frontmatter are counted as fresh (no source files to compare against)
+3. Specs not yet tracked by git (no commit history) are skipped and counted as fresh
+4. Results are sorted by most-stale-first (highest `max_commits_behind`)
+5. Exit code is 1 when any stale specs are found, 0 when all are fresh
+6. Requires a git repository — exits with error if `is_git_repo` returns false
+
+## Behavioral Examples
+
+### Scenario: All specs fresh
+
+- **Given** all specs were updated after their source files
+- **When** `specsync stale` is run
+- **Then** prints "All specs are up to date" and exits 0
+
+### Scenario: Spec behind source by 8 commits (threshold 5)
+
+- **Given** module "auth" has source file `src/auth.rs` with 8 commits since spec was last updated
+- **When** `specsync stale --threshold 5` is run
+- **Then** reports auth as stale with "8 commits behind" and exits 1
+
+### Scenario: JSON output
+
+- **Given** 2 stale specs out of 10 total
+- **When** `specsync stale --format json` is run
+- **Then** outputs JSON with `total_specs: 10`, `stale_count: 2`, `stale_specs` array with per-file details
+
+## Error Cases
+
+| Condition | Behavior |
+|-----------|----------|
+| Not a git repository | Prints error, exits 1 |
+| Spec file unreadable | Skipped silently |
+| No frontmatter | Skipped silently |
+| Source file doesn't exist on disk | Skipped in commit distance check |
+
+## Dependencies
+
+- `git_utils` — git commit history queries
+- `parser` — frontmatter parsing for module name and files list
+- `commands` — `load_and_discover` for config and spec file discovery
+
+## Change Log
+
+| Date | Change |
+|------|--------|
+| 2026-04-10 | Initial — dedicated staleness detection command (closes #188) |

specs/cmd_stale/requirements.md

@@ -0,0 +1,22 @@
+---
+spec: cmd_stale.spec.md
+---
+
+## User Stories
+
+- As a developer, I want to know which specs have drifted from their source files so I can update them
+- As a CI operator, I want staleness checks integrated into the validation pipeline so drift is caught early
+
+## Acceptance Criteria
+
+- `specsync stale` lists specs whose source files have changed since the spec was last modified
+- Reports include commit count, changed file list, and last commit details
+- JSON output mode (`--format json`) produces machine-readable staleness data
+- `specsync check --stale` integrates drift warnings into the standard check pipeline
+- Exit code is non-zero when stale specs are detected (for CI usage)
+
+## Constraints
+
+- Must not panic on expected error conditions — return Results or print and exit
+- Must work with the project's Clap-based CLI argument parsing
+- Git operations must handle missing git repos gracefully (non-git directories)

specs/commands/commands.spec.md

@@ -58,6 +58,7 @@ Shared command infrastructure used by all CLI subcommands. Provides config loadi
 | `new` | Quick-create minimal specs |
 | `report` | Per-module coverage report with staleness |
 | `resolve` | Resolve cross-project dependency refs |
+| `stale` | Git-based staleness detection for spec drift |
 | `scaffold` | Full spec scaffolding with templates |
 | `score` | Spec quality scoring (0-100, A-F) |
 | `view` | Role-filtered spec rendering |
@@ -128,6 +129,7 @@ Shared command infrastructure used by all CLI subcommands. Provides config loadi
 | cmd_score | `load_and_discover`, `filter_specs` |
 | cmd_report | `load_and_discover` |
 | cmd_resolve | `load_and_discover` |
+| cmd_stale | `load_and_discover` |
 | cmd_diff | `load_and_discover` |
 
 ## Change Log

specs/git_utils/git_utils.spec.md

@@ -0,0 +1,71 @@
+---
+module: git_utils
+version: 1
+status: stable
+files:
+  - src/git_utils.rs
+db_tables: []
+tracks: []
+depends_on: []
+---
+
+# Git Utils
+
+## Purpose
+
+Shared git utility functions for querying repository history. Provides commit hash lookup, commit distance counting, and git repository detection. Used by the `stale`, `report`, and `scoring` modules to determine spec freshness relative to source file changes.
+
+## Public API
+
+### Exported Functions
+
+| Function | Parameters | Returns | Description |
+|----------|-----------|---------|-------------|
+| `git_last_commit_hash` | `root: &Path, file: &str` | `Option<String>` | Get the SHA hash of the last commit that touched a file |
+| `git_commits_between` | `root: &Path, spec_file: &str, source_file: &str` | `usize` | Count commits to source_file since spec_file was last modified |
+| `is_git_repo` | `root: &Path` | `bool` | Check if a directory is inside a git work tree |
+
+### Exported Types
+
+| Type | Kind | Description |
+|------|------|-------------|
+| `StaleInfo` | struct | Staleness summary for a single spec: path, module name, max commits behind, per-file details |
+
+## Invariants
+
+1. All git commands execute with `current_dir(root)` to ensure correct repository context
+2. Functions return safe defaults (None, 0, false) when git is unavailable or commands fail
+3. `git_commits_between` uses `git rev-list --count {spec_commit}..HEAD -- {source_file}` to count divergence
+4. `StaleInfo.source_details` only includes files with commits_behind > 0
+
+## Behavioral Examples
+
+### Scenario: File not tracked by git
+
+- **Given** a file that has never been committed
+- **When** `git_last_commit_hash` is called
+- **Then** returns `None`
+
+### Scenario: Source file changed after spec
+
+- **Given** a spec last committed at commit A, and a source file with 3 commits after A
+- **When** `git_commits_between` is called
+- **Then** returns `3`
+
+## Error Cases
+
+| Condition | Behavior |
+|-----------|----------|
+| Not a git repository | `is_git_repo` returns false; other functions return safe defaults |
+| Git not installed | All functions return None/0/false |
+| File doesn't exist in git history | Returns None or 0 |
+
+## Dependencies
+
+None (only uses `std::process::Command` for git CLI calls).
+
+## Change Log
+
+| Date | Change |
+|------|--------|
+| 2026-04-10 | Initial — extracted from cmd_report for shared use by stale, report, and scoring |

specs/git_utils/requirements.md

@@ -0,0 +1,21 @@
+---
+spec: git_utils.spec.md
+---
+
+## User Stories
+
+- As a developer, I want git-aware spec tooling so that staleness and freshness are tracked automatically
+- As a module consumer, I want a clean API for git log queries without reimplementing git2 boilerplate
+
+## Acceptance Criteria
+
+- `commits_since` returns accurate commit counts for files since a given timestamp
+- `last_commit_for_file` returns the most recent commit touching a specific file
+- `changed_files_since` lists files modified since a reference point
+- All functions handle missing repos, untracked files, and shallow clones gracefully
+
+## Constraints
+
+- Must not panic on expected error conditions — return Results
+- Must use git2 (libgit2) for git operations, not shell commands
+- Must not hold repository locks longer than necessary

specs/scoring/scoring.spec.md

@@ -10,6 +10,7 @@ depends_on:
   - specs/types/types.spec.md
   - specs/parser/parser.spec.md
   - specs/exports/exports.spec.md
+  - specs/git_utils/git_utils.spec.md
 ---
 
 # Scoring

src/cli.rs

@@ -55,6 +55,9 @@ pub enum Command {
         /// Show per-category score breakdown explaining why each spec lost points
         #[arg(long)]
         explain: bool,
+        /// Include git-based staleness warnings (specs behind source by N+ commits)
+        #[arg(long)]
+        stale: Option<Option<usize>>,
         /// Spec filters — validates all if omitted. Matches by: module name (e.g. "cli"),
         /// filename stem ("cli.spec"), relative path ("specs/cli/cli.spec.md"), or absolute path.
         #[arg(value_name = "SPEC")]
@@ -201,6 +204,12 @@ pub enum Command {
         #[arg(long)]
         repo: Option<String>,
     },
+    /// Detect specs that have drifted from their source files (git-based)
+    Stale {
+        /// Flag specs whose source files have N+ commits since the spec was last updated
+        #[arg(long, default_value = "5")]
+        threshold: usize,
+    },
     /// Per-module coverage report with stale and incomplete detection
     Report {
         /// Flag modules whose specs are N+ commits behind their source files

src/commands/check.rs

@@ -6,10 +6,12 @@ use std::process;
 
 use crate::ai;
 use crate::comment;
+use crate::git_utils;
 use crate::github;
 use crate::hash_cache;
 use crate::ignore::IgnoreRules;
 use crate::output::{print_check_markdown, print_coverage_line, print_summary};
+use crate::parser;
 use crate::types;
 use crate::validator::{compute_coverage, get_schema_table_names};
 
@@ -29,6 +31,7 @@ pub fn cmd_check(
     force: bool,
     create_issues: bool,
     explain: bool,
+    stale: Option<Option<usize>>,
     spec_filters: &[String],
 ) {
     use hash_cache::{ChangeClassification, ChangeKind};
@@ -204,8 +207,89 @@ pub fn cmd_check(
         explain,
         &ignore_rules,
     );
+    // Git-based staleness detection (--stale flag)
+    let stale_threshold = stale.map(|opt| opt.unwrap_or(5));
+    let mut git_stale_warnings: usize = 0;
+    let mut git_stale_entries: Vec<serde_json::Value> = Vec::new();
+
+    if let Some(threshold) = stale_threshold {
+        if git_utils::is_git_repo(root) {
+            for spec_file in &spec_files {
+                let content = match fs::read_to_string(spec_file) {
+                    Ok(c) => c.replace("\r\n", "\n"),
+                    Err(_) => continue,
+                };
+                let parsed = match parser::parse_frontmatter(&content) {
+                    Some(p) => p,
+                    None => continue,
+                };
+                let fm = &parsed.frontmatter;
+                if fm.files.is_empty() {
+                    continue;
+                }
+
+                let rel_spec = spec_file
+                    .strip_prefix(root)
+                    .unwrap_or(spec_file)
+                    .to_string_lossy()
+                    .to_string();
+
+                let spec_commit = git_utils::git_last_commit_hash(root, &rel_spec);
+                if spec_commit.is_none() {
+                    continue;
+                }
+
+                let mut max_behind: usize = 0;
+                let mut drifted_files: Vec<(String, usize)> = Vec::new();
+                for source_file in &fm.files {
+                    if !root.join(source_file).exists() {
+                        continue;
+                    }
+                    let behind = git_utils::git_commits_between(root, &rel_spec, source_file);
+                    if behind >= threshold {
+                        drifted_files.push((source_file.clone(), behind));
+                    }
+                    max_behind = max_behind.max(behind);
+                }
+
+                if max_behind >= threshold {
+                    git_stale_warnings += 1;
+                    if matches!(format, types::OutputFormat::Text) {
+                        let module = fm.module.as_deref().unwrap_or(&rel_spec);
+                        println!(
+                            "  {} {module}: spec is {max_behind} commits behind source files",
+                            "⚠".yellow()
+                        );
+                        for (file, behind) in &drifted_files {
+                            println!(
+                                "      {} {file} ({behind} commit{})",
+                                "→".dimmed(),
+                                if *behind == 1 { "" } else { "s" },
+                            );
+                        }
+                    }
+                    let details: Vec<serde_json::Value> = drifted_files
+                        .iter()
+                        .map(|(f, n)| serde_json::json!({"file": f, "commits_behind": n}))
+                        .collect();
+                    git_stale_entries.push(serde_json::json!({
+                        "spec": rel_spec,
+                        "reason": "git_drift",
+                        "commits_behind": max_behind,
+                        "drifted_files": details,
+                    }));
+                }
+            }
+
+            if git_stale_warnings > 0 && matches!(format, types::OutputFormat::Text) {
+                println!();
+            }
+        }
+    }
+    stale_entries.extend(git_stale_entries);
+
     // Include staleness warnings in total when --strict
-    let effective_warnings = total_warnings + staleness_warnings;
+    let effective_warnings = total_warnings + staleness_warnings + git_stale_warnings;
     let coverage = compute_coverage(root, &spec_files, &config);
 
     // Update hash cache after validation (only when no errors).