sync-man¶

Your project guide keeper and configuration validator

Sync-man monitors CLAUDE.md files across all F3L1X realms, detects drift from actual codebase state, and ensures your project guide stays synchronized with reality. It prevents the common problem of documentation becoming stale while code evolves.

What It Does¶

Sync-man watches for three problems:

1. CLAUDE.md Drift - When docs describe features that don't exist anymore
2. Codebase Divergence - When code exists but isn't documented
3. Outdated Commands - When commands in CLAUDE.md don't match actual code
4. Missing Port Registrations - When services run on wrong ports
5. Broken Conventions - When code doesn't follow documented patterns

Sync-man alerts you to these issues before they cause confusion and errors.

Key Capabilities¶

Drift Detection¶

• CLAUDE.md vs Code: Compare documented commands to actual implementation
• Configuration Staleness: Flag settings older than 90 days
• Port Registry Validation: Verify all services on documented ports
• Pattern Compliance: Check code follows documented conventions

Validation Checks¶

• Syntax Validation: Ensure CLAUDE.md markdown is valid
• Link Validation: Check all internal documentation links work
• Code References: Verify code snippets still exist and work
• Command Testing: Actually run documented commands to verify they work

Automatic Updates¶

• Port Registry Sync: Auto-update port numbers if services move
• Command Fixes: Suggest corrections for broken commands
• Documentation Generation: Auto-generate missing sections
• Version Tracking: Track CLAUDE.md versions over time

Change Tracking¶

• Modification History: See who changed CLAUDE.md and when
• Change Approval: Require confirmation before auto-updates
• Rollback Capability: Revert CLAUDE.md to previous version
• Audit Trail: Complete history of all changes

Accessing sync-man¶

Web Dashboard¶

URL: http://127.0.0.1:8063

The sync-man dashboard shows:
- CLAUDE.md files across all realms
- Drift detection results
- Validation warnings
- Suggested fixes
- Change history

Command Line Interface¶

# Check drift for current project
python manage.py check-drift

# Validate all CLAUDE.md files
python manage.py validate-all

# Show drift report
python manage.py drift-report --realm <name>

# Auto-fix fixable issues
python manage.py auto-fix --realm <name> --confirm

Validation API¶

Common Use Cases¶

Use Case 1: Start Session with Documentation Check¶

Goal: Ensure CLAUDE.md is current before beginning work

python manage.py check-drift

Output:

═════════════════════════════════════════════════
SYNC-MAN Drift Report - herald
═════════════════════════════════════════════════

✅ Passing Checks
   - Port 8014 verified running
   - All API endpoints accessible
   - Documentation links valid

⚠️  Drift Detected
   - [LOW] Command "python manage.py runserver" returns deprecation warning
           CLAUDE.md says: runserver (old)
           Actual command: runserver --noreload (recommended)

   - [MED] Documentation shows Redis as "optional dependency"
           Reality: Redis is CRITICAL for WebSocket messaging

🔧 Suggested Fixes
   1. Update command documentation: runserver -> runserver --noreload
   2. Change Redis from "optional" to "critical"
   3. Add section on Redis setup

═════════════════════════════════════════════════

Use Case 2: Detect Codebase Changes Not Documented¶

Goal: Find features that exist but aren't documented

Sync-man discovers:
- New API endpoint /api/tools/categories/ not in CLAUDE.md
- New Django management command cleanup-stale-tokens not listed
- New environment variable WEBHOOK_SECRET not documented

Alerts: "3 undocumented features found. Update CLAUDE.md?"

Use Case 3: Verify Documented Patterns Still Work¶

Goal: Ensure code examples in CLAUDE.md actually run

Sync-man tests:

# Documented pattern: "python manage.py test --parallel"
✅ WORKS - Runs all tests successfully

# Documented pattern: "heroku deploy main"
❌ BROKEN - Heroku CLI not installed, command fails

# Documented pattern: "SELECT * FROM users;" (SQL)
❌ UNSAFE - Suggests using Django ORM instead

Use Case 4: Track Documentation Quality Over Time¶

Goal: See how documentation stays current

Dashboard shows:
- CLAUDE.md update frequency (should be within 30 days)
- Number of drift issues discovered
- Trend: improving/degrading documentation quality
- Team members most active in updating docs

Important Notes¶

Drift Severity Levels¶

CLAUDE.md Location Convention¶

All realms should have CLAUDE.md in root directory:

active/{realm}/
├── CLAUDE.md              ← Sync-man validates this
├── spec.md
├── init.sh
├── manage.py
└── ...

Sync-man monitors:
- Root CLAUDE.md in each realm
- Root CLAUDE.md in project master directory
- Pipeline-go kernel (@~/.claude/pipeline-go.md)

Auto-Fix Safety¶

Sync-man's auto-fix has safeguards:

# Suggest fixes without applying
python manage.py auto-fix --realm herald --dry-run

# Show what would change
python manage.py auto-fix --realm herald --preview

# Actually apply fixes (requires confirmation)
python manage.py auto-fix --realm herald --confirm

Only applies fixes that are:
- High confidence (documented feature exists)
- Non-breaking (doesn't require code changes)
- Reversible (can rollback if needed)

Troubleshooting¶

Sync-man reports false positives¶

Symptom: Drift detected but code is actually correct
Fix: Update CLAUDE.md wording to match actual code, or check if code needs fixing

Auto-fix changed wrong thing¶

Symptom: Sync-man's automatic update caused problems
Fix: Rollback from change history: python manage.py rollback-drift --realm <name> --version <date>

CLAUDE.md validation fails¶

Symptom: Markdown syntax errors reported
Fix: Check CLAUDE.md file for malformed markdown, broken links, invalid YAML frontmatter

Drift report shows old changes¶

Symptom: Already-fixed issues still appear in drift report
Fix: Run python manage.py refresh-drift-cache to force rescan

Port registry out of sync¶

Symptom: Services running on different ports than documented
Fix: Either move service to documented port, or run auto-fix --realm <name> to update docs

Related Realms¶

• doc-u-me - Stores historical CLAUDE.md versions for archival
• mr-greet - May skip /hello if critical drift detected
• worker-bee - Tests documented commands during health checks
• pipeline-go - Defines CLAUDE.md format and conventions
• All active realms - All have CLAUDE.md files synced by sync-man

Further Reading¶

• CLAUDE.md Format Standard
• Documentation Best Practices
• Configuration Management