Add --staged-only flag to fix unstaged changes attribution (Issue #16)

[jalalatlassian]

Pull Request: Add --staged-only flag to fix unstaged changes attribution (Issue #16)

Summary

This PR implements a solution for Issue #16 where unstaged changes were incorrectly attributed to AI agents, corrupting attribution accuracy. The solution adds a --staged-only flag that ensures only explicitly staged changes are tracked for attribution.

Problem

Git-ai was attributing ALL working directory changes (staged, unstaged, and untracked) to the checkpoint author. This caused:

• Unstaged human changes incorrectly attributed to AI agents
• Corrupted human vs AI contribution metrics
• Loss of trust in attribution accuracy

Solution

Added --staged-only flag that:

• ✅ Only tracks staged changes (git add) for attribution
• ✅ Ignores unstaged changes with helpful warnings
• ✅ Preserves backward compatibility (flag is opt-in)
• ✅ Provides clear guidance to users

Changes Made

1. Core Implementation (src/commands/checkpoint.rs)

• Added staged_only parameter to run() function
• Implemented get_staged_files_only() - filters only staged changes using git2::Status flags
• Implemented get_unstaged_files() - detects unstaged changes for warnings
• Added warning system to inform users about ignored unstaged files

2. Command-Line Interface (src/main.rs)

• Added --staged-only flag parsing
• Updated help text with flag documentation
• Passed flag through to checkpoint function

3. Comprehensive Testing (tests/staged_only_attribution.rs)

• Test staged-only flag ignores unstaged changes
• Test without flag includes all changes (backward compatibility)
• Test warning messages for unstaged files
• Test mixed staged/unstaged scenarios

4. Manual Testing (test_staged_only.sh)

• Interactive test script for manual verification
• Demonstrates flag behavior with real git scenarios

Usage Examples

Before (Problematic)

# Human makes changes but doesn't stage
echo "human code" > file.txt

# AI agent runs checkpoint - INCORRECTLY attributes human code to AI
git-ai checkpoint --author "Claude"

After (Fixed)

# Human makes changes but doesn't stage  
echo "human code" > file.txt

# AI agent runs checkpoint with --staged-only - ignores unstaged human code
git-ai checkpoint --author "Claude" --staged-only
# Warning: Found 1 unstaged file(s) that will be ignored:
#   file.txt
# Use 'git add' to stage changes or remove --staged-only to include unstaged changes

# Proper workflow: AI stages its changes
git add ai_generated_file.txt
git-ai checkpoint --author "Claude" --staged-only  # Only tracks AI's staged changes

Backward Compatibility

• ✅ No breaking changes - flag is opt-in
• ✅ Existing workflows continue working without the flag
• ✅ Authorship log format unchanged - no migration needed
• ✅ Clear migration path for users who want accurate attribution

Testing

Run the comprehensive test suite:

cargo test staged_only_attribution

Run manual verification:

./test_staged_only.sh

Future Considerations

This implementation provides a foundation for making staged-only the default behavior in future releases:

1. Phase 1 (This PR): Add --staged-only flag (opt-in)
2. Phase 2 (Future): Make staged-only default with --include-unstaged for backward compatibility
3. Phase 3 (Future): Remove backward compatibility flag

Files Changed

• src/commands/checkpoint.rs (+74 lines) - Core implementation
• src/main.rs (+6 lines) - CLI interface
• tests/staged_only_attribution.rs (+251 lines) - Comprehensive tests
• test_staged_only.sh (+73 lines) - Manual test script

Total: 407 additions, 3 deletions

Fixes

Closes #16

Review Notes

• Implementation is minimal and focused - only adds filtering logic
• No changes to existing data structures or formats
• Clear error messages guide users to correct usage
• Comprehensive test coverage for edge cases
• Ready for immediate deployment with low risk

[acunniffe]

Thanks for this @jalaatlassian, but I don't think this is a bug.

The guidance in the ReadMe is to run git-ai checkpoint right before your agent starts writing to the filesystem. This is meant to mop up and attribute any human changes that were made since the last checkpoint.