From 4791abd04386ee4690cb3706c45a05fb8398325e Mon Sep 17 00:00:00 2001 From: Codex Date: Tue, 8 Sep 2026 16:33:23 -0300 Subject: [PATCH] docs: add contributor foundation --- .gitattributes | 2 + AGENTS.md | 40 +++++++++++++ docs/architecture.md | 55 +++++++++++++++++ docs/data-policy.md | 52 ++++++++++++++++ docs/product.md | 35 +++++++++++ .../plans/2026-09-06-agent-foundation.md | 60 +++++++++++++++++++ 6 files changed, 244 insertions(+) create mode 100644 .gitattributes create mode 100644 AGENTS.md create mode 100644 docs/architecture.md create mode 100644 docs/data-policy.md create mode 100644 docs/product.md create mode 100644 docs/superpowers/plans/2026-09-06-agent-foundation.md diff --git a/.gitattributes b/.gitattributes new file mode 100644 index 0000000..efdba87 --- /dev/null +++ b/.gitattributes @@ -0,0 +1,2 @@ +* text=auto +*.sh text eol=lf diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..a922352 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,40 @@ +# Contributor instructions + +Before substantive work, read [product scope](docs/product.md), +[architecture](docs/architecture.md), [data policy](docs/data-policy.md), and +[roadmap](docs/roadmap.md). This file is the authoritative agent entry point. + +## Binding decisions + +- Gizmoduck is the clean successor to Robopato. +- Use Python, Django, PostgreSQL, migrations from the beginning, Docker Compose + for local infrastructure, and pytest for automated tests. +- Import bank accounts from CSV and Banco do Brasil/Ourocard credit cards from + TXT. OFX is not supported. +- Keep parsing, normalization, validation, duplicate detection, preview, and + persistence separate. +- Obtain owner approval before changing these constraints or product scope. + +## Working rules + +- Preserve user changes and avoid unrelated edits. +- Make small, cohesive changes with verification appropriate to their risk. +- Use isolated Git worktrees for concurrent implementation that could overlap. +- Design and plan substantial subsystems before implementing them. +- Report assumptions, checks performed, and unresolved risks accurately. +- Do not perform destructive operations, pushes, merges, releases, or history + rewrites without explicit authorization. +- Focused local commits are allowed after verification. Inspect both staged + paths and staged content for real financial data and secrets before every + commit. When uncertain whether data is safe, stop and ask the owner. +- Agent-authored commits use repository-local `Codex `; + human-authored commits retain the human contributor's identity. + +## Financial data + +Agents may read every file in Robopato and copy real documents for local +development, parser validation, migration, and compatibility testing. Store +real data only in ignored local directories or local databases. Never commit +raw data, identifying excerpts, snapshots, logs, screenshots, reports, or dumps. +Committed fixtures must be synthetic or irreversibly sanitized. Follow the +[full data policy](docs/data-policy.md) before handling source documents. diff --git a/docs/architecture.md b/docs/architecture.md new file mode 100644 index 0000000..08acb49 --- /dev/null +++ b/docs/architecture.md @@ -0,0 +1,55 @@ +# Architecture + +## Binding stack + +Use Python and Django for the application, PostgreSQL for persistent storage, +schema migrations from the beginning, Docker Compose for local infrastructure, +and pytest for automated tests. Changes require explicit owner approval and a +documented architectural decision. + +Dependency versions and tooling will be selected in the application-skeleton +design. This foundation does not prescribe a database schema or UI framework. + +## Import boundaries + +```text +source document + -> source-specific parsing + -> normalization + -> validation + -> duplicate detection + -> preview + -> explicit commit and persistence + -> categorization and reporting +``` + +Bank-account parsers consume CSV; Banco do Brasil/Ourocard card parsers consume +TXT. OFX is unsupported. Parsers are pure transformations of supplied input; +they do not query or write the database. Normalization maps parser output into +a common candidate representation without committing transactions. + +Validation reports issues for review. Duplicate detection compares candidates +with the relevant import and persisted records through a separate boundary. +Preview displays candidates and issues without committing financial records. +Persistence owns database writes, migrations, and commit integrity. Parser +grammars, candidate contracts, duplicate rules, and transaction boundaries are +specified and tested when the import subsystem is designed. + +## Data and accountability + +Preserve import provenance. Imports and material data changes record actor, +source, timestamp, and outcome so human, application, and automated activity can +be distinguished. Keep sensitive audit details in local storage governed by +the [data policy](data-policy.md). + +Use separate least-privilege database accounts for development and application +processes. Credentials belong in local environment configuration, never in +tracked source. The skeleton design must define role provisioning and migration +permissions. Schema changes must use migrations, not manual database drift. + +## Delivery boundaries + +The financial domain model, UI, importer grammar, duplicate algorithm, deployment +model, and backup implementation each require design before substantial work. +Follow the [roadmap](roadmap.md) for sequencing and [product scope](product.md) +for acceptance boundaries. diff --git a/docs/data-policy.md b/docs/data-policy.md new file mode 100644 index 0000000..f0b77ac --- /dev/null +++ b/docs/data-policy.md @@ -0,0 +1,52 @@ +# Financial data policy + +## Authorized local use + +Agents may read every file in the Robopato repository and copy real financial +documents for local development, parser validation, migration, and compatibility +testing. This permission does not authorize committing that material or sending +it to external services. + +Real financial data may exist only in ignored local directories and local +databases. Use these repository-root directories: + +| Location | Purpose | +| --- | --- | +| `data/` | Local working data and database storage | +| `documents/` | Source documents copied from Robopato | +| `imports/` | Local import inputs and intermediate results | +| `uploads/` and `media/` | Application-managed local files | +| `exports/` | User exports and generated reports | +| `backups/` | Database and application backups | + +Verify the destination with `git check-ignore` before copying financial data. +Keep local credentials in ignored `.env` files; `.env.example` may contain only +non-secret examples. Keep sensitive execution output out of shared transcripts. + +## Git boundary + +Never add real financial data to Git. This includes raw documents, database +dumps, copied excerpts, snapshots, logs, screenshots, generated reports, and +documentation containing identifying transaction data. Ignoring a file does +not remove data that was already tracked. Never use force-add to bypass this +policy. + +Committed tests and examples must use synthetic or irreversibly sanitized data. +Use `tests/fixtures/synthetic/` for explicitly synthetic CSV, TXT, and PDF +fixtures. A fixture exception in `.gitignore` is not evidence that its contents +are safe. Sanitization must remove identifying information and prevent recovery +of the original sensitive data; changing a name alone is insufficient. + +Before every commit, inspect `git diff --cached --name-only` and +`git diff --cached`, including newly added fixtures, for financial data and +secrets. When uncertain whether material is safe, stop and ask the owner. + +## Runtime handling + +Use separate least-privilege development and application database accounts. +Record actor, source, timestamp, and outcome for imports and material changes. +Treat audit records, errors containing source rows, and test output derived from +real documents as financial data. Use synthetic data for shareable diagnostics. + +If sensitive material is accidentally tracked, stop propagation and notify the +owner. Do not push it or rewrite history without explicit authorization. diff --git a/docs/product.md b/docs/product.md new file mode 100644 index 0000000..151a20c --- /dev/null +++ b/docs/product.md @@ -0,0 +1,35 @@ +# Product scope + +Gizmoduck is a privacy-conscious personal finance application for an individual +managing their own accounts and credit cards locally. It succeeds Robopato, +retaining lessons from Banco do Brasil statements and Ourocard invoices without +carrying forward notebook-driven architecture or importing historical data by +default. + +## MVP + +- Manage bank accounts and credit cards. +- Import bank-account CSV and Banco do Brasil/Ourocard credit-card TXT. +- Preview parsed transactions, validation issues, and suspected duplicates + before committing an import. +- Preserve provenance and detect duplicates across imports. +- Organize transactions by payee and category. +- Represent transfers, refunds, and installments correctly. +- Inspect monthly cash flow and spending summaries. +- Export and back up user-owned data. + +A successful MVP supports the local path from source file through reviewed +import to understandable transactions and summaries, with tests using synthetic +or irreversibly sanitized fixtures. A failed or cancelled preview must not +commit financial transactions. Exact importer grammars and financial modeling +rules require subsystem designs before implementation. + +## Exclusions + +OFX is not supported. Bank APIs, investment tracking, mobile clients, receipt +recognition, forecasting, and AI categorization are outside the MVP. Hosted +multi-user operation is not part of the initial local release. + +The owner must approve scope changes. Technical choices are defined in +[architecture](architecture.md); financial data handling follows the +[data policy](data-policy.md). diff --git a/docs/superpowers/plans/2026-09-06-agent-foundation.md b/docs/superpowers/plans/2026-09-06-agent-foundation.md new file mode 100644 index 0000000..3b7530b --- /dev/null +++ b/docs/superpowers/plans/2026-09-06-agent-foundation.md @@ -0,0 +1,60 @@ +# Agent Foundation Implementation Plan + +> **For agentic workers:** Use superpowers:executing-plans to implement this plan inline, task by task. + +**Goal:** Establish the approved contributor guidance and privacy boundaries. + +**Architecture:** Keep AGENTS.md concise and authoritative. Separate product, +architecture, data policy, and delivery sequence into linked documents. + +**Tech Stack:** Markdown and Git; the application will use Python, Django, +PostgreSQL, Docker Compose, and pytest. + +**Spec:** [Approved foundation design](../specs/2026-09-06-agent-foundation-design.md). + +## Global constraints + +- The project is named Gizmoduck and is the clean successor to Robopato. +- The backend uses Python and Django. +- Persistent storage uses PostgreSQL with migrations from the beginning. +- Local infrastructure uses Docker Compose. +- Automated tests use pytest. +- Bank-account transactions are imported from CSV. +- Credit-card transactions are imported from Banco do Brasil/Ourocard TXT. +- OFX is not supported. +- Parsing, normalization, validation, duplicate detection, preview, and + persistence remain separate stages. +- Real financial data and secrets must never enter Git. +- Preserve existing README and ignore-file content while making targeted updates. + +## Task 1: Publish contributor and project guidance + +**Files:** Create AGENTS.md, docs/product.md, docs/architecture.md, +docs/data-policy.md, docs/roadmap.md; update README.md. + +**Interfaces:** Consumes the approved spec; produces linked contributor policy. + +- [x] Write AGENTS.md with binding constraints, reading order, operating rules, + local commit identity, and links to the four project documents. +- [x] Write product scope and exclusions, architecture boundaries, permitted + Robopato access and local-data locations, and milestone acceptance criteria. +- [x] Link the documents from README and align its architecture language with + the approved binding choices. +- [x] Check that every relative Markdown link resolves and review all documents + against the approved spec for contradictions and unresolved policy choices. + +## Task 2: Verify data exclusions and readiness + +**Files:** Update .gitignore only where approved protections are missing. + +**Interfaces:** Consumes data-policy locations; produces Git exclusion rules. + +- [x] Exclude raw financial CSV/TXT/PDF and database dump formats, keeping + explicitly synthetic fixture paths trackable. Preserve existing rules. +- [x] Use git check-ignore with representative paths under each local-data + directory, secret and dump formats, and synthetic fixtures. Confirm raw data + is ignored and synthetic fixtures remain trackable without creating real data. +- [x] Run git diff --check; verify repository-local user.name and user.email + equal Codex and codex@localhost; inspect changed files for secrets/data. +- [x] Report the completed foundation and next application-skeleton milestone. + Leave existing user edits and new documents available for review locally.