BlackLine

Build a local, single-user bank reconciliation tool. No accounts, no cloud, no telemetry, no hosted anything.

Stack, non-negotiable:
- Python 3.11
- Typer for the CLI
- pandas for CSV handling
- SQLite via sqlite3 for persistence (file: recon.db)
- Jinja2 to render a static HTML report
- pytest for tests
No web server, no auth, no Docker, no external API calls.

What it does:
1. `recon import --side bank --file path.csv` and `--side ledger` ingest CSVs into SQLite. Support column mapping via a mapping.yml so the user can point date/amount/description/reference at their own headers. Store a stable row hash so re-importing the same file does not duplicate rows.
2. `recon match --period 2026-07` runs matching in passes, most confident first: (a) exact amount + exact reference, (b) exact amount within a configurable date window (default 3 days), (c) exact amount + fuzzy description via difflib ratio above a threshold, (d) many-to-one sums where several ledger lines total one bank line, capped at 4 lines to keep it tractable. Every match records the pass that made it and a confidence score.
3. `recon review --period 2026-07` interactive CLI: step through low-confidence and unmatched items, accept, reject, or tag as a known timing difference or fee. Decisions persist so re-running match does not undo human calls.
4. `recon report --period 2026-07 --out report.html` renders: opening balance, matched total, unmatched bank items, unmatched ledger items, tagged differences, and the closing difference that must reconcile to zero. Include a plain-text summary printed to stdout.
5. `recon rules` reads rules.yml for auto-tagging patterns (regex on description to category), applied during match.

Explicitly out of scope: multi-entity consolidation, FX revaluation, journal entry posting, approval workflows, ERP connectors, anything claiming to be audit evidence.

Deliverables: README with a worked example using two generated sample CSVs, mapping.yml and rules.yml examples, tests covering each matching pass plus the many-to-one case, and a Makefile with install/test/demo targets. Config paths and thresholds in .env or config.yml, never hardcoded. Print a one-line disclaimer in the report footer: this is a personal tool, not audit evidence.

# AGENTS.md — Build guide for BlackLine

## Project scope
Ingest a bank CSV and a ledger CSV, auto-match on amount plus date tolerance plus reference fuzz, and produce a reconciliation report listing matched pairs, unmatched items on each side, and a running difference.

Catalogue verdict: no. You can absolutely build a transaction matcher: read two CSVs, fuzzy match on amount and date, flag the leftovers. That is maybe five percent of what BlackLine is being paid for. The rest is certified reconciliations with named preparers and reviewers, immutable audit trails an external auditor will accept, SOX control evidence, multi-entity intercompany elimination, and live connectors into SAP, Oracle and NetSuite that survive a chart-of-accounts change. A personal replacement is a category error here: nobody buys this for themselves, a controller buys it so the audit does not become a quarter-long forensic exercise. If you are a solo operator reconciling one bank account against one ledger, you never needed it anyway.
Use the implementation prompt below to define the deliverable. Complete each phase's acceptance checks before extending the scope.

## Working agreement
- Inspect the repository and its existing instructions before choosing paths, dependencies or commands. Keep one coherent stack and explain changes to the proposed architecture.
- Plan a vertical slice that accepts a real input and produces the useful output described below. Persist only the state the prompt calls for; respect memory-only and upstream-managed workflows. Use fixtures only when they are clearly labelled.
- After scaffolding, document the actual install, development, check and build commands in README and keep them synchronized with the package or project manifest. Do not report commands as successful unless they ran.
- Work in small steps. At handoff, list implemented flows, checks actually performed, remaining blockers, and any credentials or provider setup the owner must supply.
- Do not publish, spend money, contact customers, delete source data or run irreversible migrations without the project owner's authorization.

## Prerequisites
- Python 3.11 and a local terminal
- CSV exports from your bank and your accounting system
- Willingness to hand-tune matching rules for your own transaction descriptions
- No auditor who needs to sign off on the result

## Stack and architecture
- Python 3.11.
- `recon review --period 2026-07` interactive CLI: step through low-confidence and unmatched items, accept, reject, or tag as a known timing difference or fee. Decisions persist so re-running match does not undo human calls.
- Interface for this financial close and reconciliation workflow: a focused financial close and reconciliation input, review, and export interface.

## Security and data integrity
- On invalid input or interrupted processing, keep the original record, show the failed step, and permit a safe retry.
- Validate imported records and file paths; keep user data within the storage location named in the prompt.
- State the practical limit: Audit-defensible evidence: preparer/reviewer sign-off, timestamps, locked periods, nothing editable after certification.

## Agent implementation rules
- Project rule, data: `recon review --period 2026-07` interactive CLI: step through low-confidence and unmatched items, accept, reject, or tag as a known timing difference or fee. Decisions persist so re-running match does not undo human calls.
- Project rule, behavior: Explicitly out of scope: multi-entity consolidation, FX revaluation, journal entry posting, approval workflows, ERP connectors, anything claiming to be audit evidence.
- Project rule, recovery: On invalid input or interrupted processing, keep the original record, show the failed step, and permit a safe retry.

## Optional agent skills and references
No installable skill is listed for this guide; use the project rules and the stack documentation.

Read the linked SKILL.md and its dependencies before adding a skill. Select only the skills matching this project's runtime and task; their documentation does not supply API access, credentials or approval to perform external actions. Pin the reviewed revision where the tool supports it. Follow the chosen agent's documented project-level installation mechanism.

## Distribution ideas
These are optional planning notes. Obtain the owner's approval before publishing or contacting anyone.
- Demonstrate this financial close and reconciliation operation with sample or user-owned data: Explicitly out of scope: multi-entity consolidation, FX revaluation, journal entry posting, approval workflows, ERP connectors, anything claiming to be audit evidence.
- Show a concrete result or export: Deliverables: README with a worked example using two generated sample CSVs, mapping.yml and rules.yml examples, tests covering each matching pass plus the many-to-one case, and a Makefile with install/test/demo targets. Config paths and thresholds in .env or config.yml, never hardcoded. Print a one-line disclaimer in the report footer: this is a personal tool, not audit evidence.
- State the practical limit: Audit-defensible evidence: preparer/reviewer sign-off, timestamps, locked periods, nothing editable after certification.

## Engineering roadmap
1. Phase 1, architecture and data: Python 3.11. `recon review --period 2026-07` interactive CLI: step through low-confidence and unmatched items, accept, reject, or tag as a known timing difference or fee. Decisions persist so re-running match does not undo human calls.
2. Phase 2, implement: Explicitly out of scope: multi-entity consolidation, FX revaluation, journal entry posting, approval workflows, ERP connectors, anything claiming to be audit evidence.
3. Phase 3, implement: Deliverables: README with a worked example using two generated sample CSVs, mapping.yml and rules.yml examples, tests covering each matching pass plus the many-to-one case, and a Makefile with install/test/demo targets. Config paths and thresholds in .env or config.yml, never hardcoded. Print a one-line disclaimer in the report footer: this is a personal tool, not audit evidence.
4. Phase 4, review and output: Ingest a bank CSV and a ledger CSV, auto-match on amount plus date tolerance plus reference fuzz, and produce a reconciliation report listing matched pairs, unmatched items on each side, and a running difference. Deliverables: README with a worked example using two generated sample CSVs, mapping.yml and rules.yml examples, tests covering each matching pass plus the many-to-one case, and a Makefile with install/test/demo targets. Config paths and thresholds in .env or config.yml, never hardcoded. Print a one-line disclaimer in the report footer: this is a personal tool, not audit evidence.
5. Phase 5, recovery and acceptance: On invalid input or interrupted processing, keep the original record, show the failed step, and permit a safe retry. Verify this invariant with a saved fixture: The sum of debits and credits must balance for posted entries; an import retry cannot change the closing balance. State the practical limit: Audit-defensible evidence: preparer/reviewer sign-off, timestamps, locked periods, nothing editable after certification.

## Paid-product capabilities outside this build
- Audit-defensible evidence: preparer/reviewer sign-off, timestamps, locked periods, nothing editable after certification
- SOX and internal-control reporting that auditors already know how to read
- Live ERP integrations (SAP, Oracle, NetSuite, Dynamics) instead of manual CSV exports
- Multi-entity and intercompany handling, FX, and consolidation-scale volumes
- Someone accountable when the numbers are wrong at year end

## Implementation prompt
Build a local, single-user bank reconciliation tool. No accounts, no cloud, no telemetry, no hosted anything.

Stack, non-negotiable:
- Python 3.11
- Typer for the CLI
- pandas for CSV handling
- SQLite via sqlite3 for persistence (file: recon.db)
- Jinja2 to render a static HTML report
- pytest for tests
No web server, no auth, no Docker, no external API calls.

What it does:
1. `recon import --side bank --file path.csv` and `--side ledger` ingest CSVs into SQLite. Support column mapping via a mapping.yml so the user can point date/amount/description/reference at their own headers. Store a stable row hash so re-importing the same file does not duplicate rows.
2. `recon match --period 2026-07` runs matching in passes, most confident first: (a) exact amount + exact reference, (b) exact amount within a configurable date window (default 3 days), (c) exact amount + fuzzy description via difflib ratio above a threshold, (d) many-to-one sums where several ledger lines total one bank line, capped at 4 lines to keep it tractable. Every match records the pass that made it and a confidence score.
3. `recon review --period 2026-07` interactive CLI: step through low-confidence and unmatched items, accept, reject, or tag as a known timing difference or fee. Decisions persist so re-running match does not undo human calls.
4. `recon report --period 2026-07 --out report.html` renders: opening balance, matched total, unmatched bank items, unmatched ledger items, tagged differences, and the closing difference that must reconcile to zero. Include a plain-text summary printed to stdout.
5. `recon rules` reads rules.yml for auto-tagging patterns (regex on description to category), applied during match.

Explicitly out of scope: multi-entity consolidation, FX revaluation, journal entry posting, approval workflows, ERP connectors, anything claiming to be audit evidence.

Deliverables: README with a worked example using two generated sample CSVs, mapping.yml and rules.yml examples, tests covering each matching pass plus the many-to-one case, and a Makefile with install/test/demo targets. Config paths and thresholds in .env or config.yml, never hardcoded. Print a one-line disclaimer in the report footer: this is a personal tool, not audit evidence.

## Completion evidence
Demonstrate the prompt's acceptance scenarios against the scoped workflow. Include setup from a clean checkout and failure recovery. Check persistence across restart and export/restore only for the state the prompt says to store; for memory-only tools, confirm that temporary content is discarded as specified. Record actual results and remaining limitations. A detailed plan alone does not establish a working replacement.