cfo-validate

name	cfo-validate
description	Run bean-check plus custom validation rules on the ledger. Ensures every entry balances, accounts exist, and no common errors are present. Use after any ledger modification to verify integrity. CLEAR step: L (Log)

/cfo-validate — Quality Control

CLEAR Step

L — Log: Ensure every entry in the ledger is valid and correct.

Role

You are the quality gate. Nothing gets committed without passing your checks.

Workflow

Step 1: Run validation helper

# Prefer explicit path when you know it
./bin/cfo-check ./ledger/main.beancount

# Or rely on auto-discovery
./bin/cfo-check

Discovery order:

1. The explicit path passed to ./bin/cfo-check
2. ./main.beancount
3. ./ledger/main.beancount
4. The first main.beancount found under the current working tree

Report any errors with file, line number, and description.

Step 2: Custom validation rules

Beyond bean-check, verify:

1. Balance assertions exist for every bank/credit card account at month-end
2. No orphaned accounts — every open account has at least one transaction
3. No future-dated transactions (unless explicitly flagged)
4. Consistent payee naming — flag variations (e.g., "Amazon" vs "AMZN" vs "Amazon.ca")
5. Receipt linkage — transactions over $75 should have a receipt reference
6. Tax treatment — all business expenses have tax metadata
7. Flagged transactions — report any ! (flagged) entries that need resolution
8. Duplicate-risk findings — surface unresolved items from the capture duplicate-risk report or manifest conflicts

Step 3: Report

VALIDATION REPORT
═══════════════════
bean-check:     PASS (0 errors)
Balance checks: PASS (12 assertions, all hold)
Orphan accounts: WARN (1 account with no transactions)
Future dates:   PASS
Payee names:    WARN (3 inconsistent names)
Receipts:       WARN (2 transactions >$75 missing receipts)
Tax treatment:  PASS
Flagged:        INFO (1 flagged transaction remaining)
Duplicate risk: WARN (1 corrected reimport waiting for approval)

Overall: PASS with warnings

Constraints

• Run automatically before every /cfo-snapshot commit
• Report all issues — never silently ignore
• Distinguish ERROR (must fix) from WARNING (should fix) from INFO (awareness)

Related Skills

• /cfo-capture-dedupe — emits duplicate-risk findings and import manifests
• /cfo-snapshot — blocked until validation results are acceptable