Restricted Funds Compliance Ledger

Goal

Create a reconciled compliance ledger that maps each expense to the correct restricted funding source, verifies allowability, links required documentation, flags unsupported or ambiguous items, and delivers exception and approval reports ready for audit.

Inputs to gather

• Organization name (identifies entity for ledger).
• Reporting period start / end and accounting basis (defines scope).
• Base currency and any FX rules (normalizes multi-currency data).
• Chart of accounts and program/class structure (categorization backbone).
• Approval contact(s) for finance review (route ambiguous items).
• Policies: indirect cost rate(s), shared-cost allocation bases, pre-award rules, documentation standards, grant tagging/class conventions (drives mapping logic).
• Desired output formats: CSV or Excel for ledger/reports, MD or TXT for summaries (proper deliverables).
• Grant & donation artifacts: agreements, amendments, donor letters, budget schedules, indirect policies (derive restrictions).
• Program budgets mapped to COA categories (budget caps).
• Expense/GL detail export for the period (transaction data).
• Bank statement exports, including restricted cash accounts (cash verification).
• Source documents: receipts, invoices, contracts, timesheets, approval records (documentation linkage).

Before doing any work, ask the user for these inputs in ONE message. Skip anything they already provided. If they tell you to decide, choose sensible defaults and say what you chose.

Workflow

1. Confirm scope and assumptions. Record all provided inputs and clarify any gaps or ambiguities with the user.
2. Ingest and normalize data (use Read tool).
   a. Extract restrictions, periods, budgets, caps, prohibited costs, and documentation requirements from grant/donation artifacts.
   b. Normalize program budgets to the chart of accounts.
   c. Load GL detail, bank exports, and source documents; standardize field names and currencies.
3. Build the Restrictions Registry for every grant/fund, including allowable accounts/categories, indirect rules, allocation bases, and required documentation. Generate an allowability matrix.
4. Construct the Transaction Table.
   a. Merge GL detail with bank data, handling posting-date tolerances.
   b. Link source documents; mark MISSING_DOC when unmatched.
   c. Normalize currencies and identify special cases (payroll splits, refunds, transfers).
5. Map expenses to restricted sources in priority order: explicit tags → period + program/class + allowable category → keyword/context. Enforce budget caps, period limits, and allowability rules. Allocate shared costs per policies. Mark NOT_ALLOWED or AMBIGUOUS where fitting.
6. Validate compliance. Apply reason codes: OUT_OF_PERIOD, NOT_ALLOWED_CATEGORY, MISSING_DOC, OVER_BUDGET, DUPLICATE, BANK_MISMATCH, AMBIGUOUS.
7. Prepare reports.
   a. Exceptions report with reason codes and links.
   b. Approval packets for AMBIGUOUS items, including context, candidate grants, budget impact, and recommended mapping.
8. Build the Compliance Ledger (use Edit tool). Include every allocation with audit fields: grant_id, txn_id, amounts, fx_rate, allocation_pct, allowability_status, source_doc_link, reason_codes, reviewer, notes.
9. Reconcile totals. Tie restricted allocations to GL and bank movements, explain variances, and ensure every restricted-dollar line has documentation and a final allowability status. Loop back to earlier steps if issues remain.
10. Finalize. Produce completion checklist, changelog of mapping rules and overrides, journal-entry proposals for reclasses (do not post), and next-step guidance for finance. Confirm delivery of all requested file formats.

Check in with the user after step 5 (initial mapping results and exceptions preview) and after step 9 (reconciliation results) before moving to the next phase.

Output

1. compliance_ledger.csv or .xlsx with allocation-level rows and all audit fields.
2. exceptions_report.csv listing every unsupported, misclassified, or ambiguous transaction with reason codes.
3. approvals_queue.csv containing detailed packets awaiting finance decisions.
4. reconciliation_summary.md describing tie-outs, remaining funds, variances, and open items.
5. completion_checklist.md and changelog.txt documenting processes, rule precedence, and version history.