Org File Review Checker

A Python tool for tracking document review compliance in org-mode files. Designed for network engineers and security managers who need to maintain audit trails and ensure timely document reviews across large infrastructure documentation.

Features

• 🔍 Recursive scanning - Scans entire directory trees for .org files
• ✅ Compliance tracking - Identifies documents with missing review properties
• ⚠️ Overdue detection - Flags documents past their review date
• 📅 Upcoming reviews - Shows reviews due in the next 30 days
• 📊 Clear reporting - Generates prioritized compliance reports
• 🔧 Git integration - Helper tool to set Created dates from git commit history

Version History

See CHANGELOG.md for detailed version history and release notes.

Requirements

• Python 3.8+
• uv for dependency management

Installation

# Clone or download this project
cd org-review-checker

# No dependencies to install - uses Python standard library only!

Usage

Basic usage

# Scan current directory
uv run check_reviews.py

# Scan specific directory
uv run check_reviews.py /path/to/your/org/files

# Scan with examples
uv run check_reviews.py ./examples

# Only check file headers (ignore individual headings)
uv run check_reviews.py --header-only ./examples

Org file structure

Each org heading that represents a reviewable document should have these properties:

* Document Title
:PROPERTIES:
:Created: 2024-01-15
:Revisited: 2024-12-01
:NextReview: 2025-03-01
:ReviewCycle: 90
:Status: Current
:END:

Alternatively, you can add properties to the file header (before any headings) to track the entire file as a single document:

#+TITLE: Network Infrastructure Documentation
#+AUTHOR: Ralph
#+DATE: 2024-01-15

:PROPERTIES:
:Created: 2024-01-15
:Revisited: 2024-12-01
:NextReview: 2025-03-01
:ReviewCycle: 90
:Status: Current
:END:

Your content here...

Use --header-only to only check file-level properties and ignore individual headings.

Required properties:

• :Created: - Original document creation date (YYYY-MM-DD)
• :Revisited: - Last review date (YYYY-MM-DD)
• :NextReview: - Next scheduled review date (YYYY-MM-DD)

Optional properties:

• :ReviewCycle: - Days between reviews (e.g., 90, 180)
• :Status: - Current status (e.g., Current, Needs Review, Critical)
• :Owner: - Responsible team or person

Output example

================================================================================
DOCUMENT REVIEW STATUS REPORT
================================================================================

Files scanned: 3
Documents with missing properties: 4
Overdue reviews: 2
Upcoming reviews (next 30 days): 2

⚠️  OVERDUE REVIEWS
--------------------------------------------------------------------------------

📄 examples/example.org
  • Incident Response Plan
    Due: 2024-09-01 (102 days overdue)
    Last reviewed: 2024-06-01
  • Server Infrastructure Documentation
    Due: 2024-11-01 (40 days overdue)
    Last reviewed: 2024-08-01

❌ MISSING REVIEW PROPERTIES
--------------------------------------------------------------------------------

📄 examples/example.org
  • Backup Procedures
    Missing: Created, Revisited, NextReview
  • Password Policy
    Missing: Created, Revisited, NextReview

📅 UPCOMING REVIEWS (Next 30 days)
--------------------------------------------------------------------------------

📄 examples/example.org
  • Network Diagram
    Due: 2025-01-05 (in 25 days)
  • Compliance Checklist
    Due: 2025-01-15 (in 35 days)

✅ 2 documents are current (reviews > 30 days away)

Helper Utilities

Setting Created dates from git history

The set_created_dates.py script automatically sets the Created property in your org files based on the first git commit date of each file.

Updating NextReview dates

The update_next_review.py script automatically calculates and updates the NextReview property based on the more recent of Created or Revisited dates plus the ReviewCycle days.

Calculation formula: NextReview = max(Created, Revisited) + ReviewCycle days

Usage (update_next_review.py)

# Preview changes (dry-run)
uv run update_next_review.py --dry-run file.org

# Update a single file's header
uv run update_next_review.py file.org

# Update all headings in a file (not just the header)
uv run update_next_review.py --all-headings file.org

# Process all org files in a directory
uv run update_next_review.py --directory ./docs

# Dry-run on entire directory
uv run update_next_review.py --dry-run --directory ./examples

Options (update_next_review.py)

• --directory, -d - Treat path as directory and process all .org files recursively
• --all-headings - Update NextReview dates in all heading properties, not just file header
• --dry-run, -n - Preview changes without modifying files

How it works (update_next_review.py)

1. Reads the Created, Revisited, and ReviewCycle properties from each document
2. Calculates the next review date using: max(Created, Revisited) + ReviewCycle days
3. Updates or adds the NextReview: property with the calculated date
4. Skips documents that are already up-to-date
5. Reports which documents were updated and the new dates

This is useful when:

• You've updated the Revisited date after reviewing a document
• You've changed the ReviewCycle and need to recalculate review dates
• You want to ensure all NextReview dates are consistent with the review policy
• Initializing org files with proper review dates

Automated Updates with Forgejo Workflow

For org-mode repositories hosted on Forgejo, you can automate NextReview updates using the included workflow file .forgejo/workflows/update-nextreview.yml.

Setup:

1. Copy update_next_review.py to your org-mode repository root
2. Create .forgejo/workflows/update-nextreview.yml with the workflow configuration from this repository
3. Ensure Forgejo Actions are enabled for your repository

How it works:

• Triggers on every push to the main branch
• Runs update_next_review.py --directory . to update all org files
• Automatically commits changes with message "nextreview updated by script"
• Skips commit if no files were modified (prevents empty commits)

This ensures your NextReview dates are always calculated correctly without manual intervention

Usage (set_created_dates.py)

# Preview changes (dry-run)
uv run set_created_dates.py --dry-run file.org

# Update a single file's header
uv run set_created_dates.py file.org

# Update all headings in a file (not just the header)
uv run set_created_dates.py --all-headings file.org

# Process all org files in a directory
uv run set_created_dates.py --directory ./docs

# Dry-run on entire directory
uv run set_created_dates.py --dry-run --directory ./examples

Options

• --directory, -d - Treat path as directory and process all .org files recursively
• --all-headings - Update Created dates in all heading properties, not just file header
• --dry-run, -n - Preview changes without modifying files

How it works

1. Queries git history to find the first commit that added each file
2. Updates or adds the Created: property in the file header to match that date
3. Optionally updates Created: in all heading property drawers with --all-headings
4. Skips common excluded directories (.git, archive, drafts, etc.)

This is useful when:

• Initializing org files for review tracking
• Your files were created before you started tracking review dates
• You want historically accurate creation dates from your version control

Configuration

Excluded directories

By default, these directories are skipped:

• archive
• .git
• drafts
• backup
• __pycache__

To customize, modify the exclude_dirs parameter in the scan_directory() function.

Use cases

For compliance audits

Run before quarterly audits to identify documentation gaps:

uv run check_reviews.py /infrastructure/docs > audit_prep_report.txt

File-level tracking

If you track entire files (not individual sections), use header-only mode:

uv run check_reviews.py --header-only /policies > policy_review_status.txt

Weekly team reports

Add to cron for weekly review reminders:

0 9 * * 1 cd /docs && uv run /path/to/check_reviews.py . | mail -s "Weekly Doc Reviews" team@example.com

Integration with org-agenda

Use output to create TODO items in Emacs org-mode for overdue reviews.

Development with Claude Code

This project is designed to work seamlessly with Claude Code for iterative development.

Project structure

org-review-checker/
├── check_reviews.py            # Main review checking script
├── set_created_dates.py        # Helper to set Created dates from git
├── update_next_review.py       # Helper to calculate NextReview dates
├── examples/
│   ├── example.org             # Test data with various review states
│   └── header-example.org      # File-level tracking example
├── tests/
│   ├── test_check_reviews.py        # Test suite for main script
│   ├── test_set_created_dates.py    # Test suite for Created dates helper
│   └── test_update_next_review.py   # Test suite for NextReview helper
├── CHANGELOG.md                # Version history (Keep a Changelog format)
├── README.md                   # This file
├── pyproject.toml              # Project configuration
└── .python-version             # Python version for uv

Working with Claude Code

# Start Claude Code session
claude-code

# Ask Claude to:
# - Add CSV export functionality
# - Implement email notifications
# - Add support for custom date formats
# - Create unit tests
# - Add colorized terminal output

Roadmap

• CSV/JSON export for external processing
• Email notifications for overdue reviews
• Integration with calendar systems (ical export)
• Automatic NextReview calculation based on ReviewCycle
• Web dashboard for team visibility
• Support for custom property names
• Batch update tool for setting Created dates from git history
• Batch update tool for NextReview calculation

Contributing

Suggestions and improvements welcome! This tool is designed for network operations and security compliance use cases.

License

MIT License - feel free to use and modify for your organization's needs.

Author

Created for network engineers and security managers who manage documentation compliance across large infrastructures.