docs: design agent foundation

docs/superpowers/specs/2026-09-06-agent-foundation-design.md

@@ -0,0 +1,105 @@
+# Gizmoduck Agent Foundation Design
+
+**Date:** 2026-09-06  
+**Status:** Approved for planning
+
+## Purpose
+
+Establish a small, durable set of documents that gives human and automated
+contributors a shared understanding of Gizmoduck before application code is
+written. The documents must make binding technical decisions, privacy
+boundaries, project scope, and agent behavior easy to discover.
+
+## Document structure
+
+The agent foundation will use a layered structure:
+
+- `AGENTS.md` is the concise, authoritative entry point for every agent.
+- `docs/product.md` defines the product purpose, users, MVP, and exclusions.
+- `docs/architecture.md` records binding technology choices and component
+  boundaries.
+- `docs/data-policy.md` governs access to and handling of real financial data.
+- `docs/roadmap.md` orders the initial delivery milestones without becoming a
+  task tracker.
+
+The README remains the human-facing introduction and links to these documents
+once they exist. Detailed feature designs will be written separately rather
+than accumulated in `AGENTS.md`.
+
+## Binding project constraints
+
+Until the owner explicitly approves a change, agents must treat the following
+as binding:
+
+- 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.
+
+Agents may identify risks or propose reconsideration, but they may not silently
+replace these choices while implementing unrelated work.
+
+## Robopato access and financial-data policy
+
+Gizmoduck agents are authorized to read every file in the Robopato repository.
+They may copy real financial documents from Robopato for local development,
+parser validation, migration, and compatibility testing.
+
+Real financial data must never be added to Git. This prohibition includes raw
+documents, database dumps, copied excerpts, test snapshots, logs, screenshots,
+generated reports, and documentation containing identifying transaction data.
+Real data may exist only in ignored local directories and local databases.
+
+Committed tests must use synthetic data or data that has been irreversibly
+sanitized. Before every commit, agents must inspect staged paths and staged
+content for financial data and secrets. When uncertain whether data is safe,
+agents must stop and ask the owner.
+
+## Agent operating policy
+
+Agents will:
+
+- read `AGENTS.md` and its linked documents before substantive work;
+- preserve user changes and avoid unrelated edits;
+- clarify changes that would alter binding constraints or product scope;
+- prefer small, cohesive changes with tests appropriate to their risk;
+- use isolated Git worktrees for concurrent implementation that could overlap;
+- report assumptions, verification performed, and unresolved risks; and
+- avoid destructive operations, pushes, merges, releases, and history rewrites
+  without explicit authorization.
+
+Agents may create focused local commits after relevant verification succeeds.
+Agent-authored commits use a repository-local identity:
+
+```text
+Codex <codex@localhost>
+```
+
+Human-authored commits retain the human contributor's own Git identity.
+
+## Verification
+
+The documentation task is complete when:
+
+- every planned document exists and links resolve;
+- the README points readers to the agent and project documentation;
+- constraints are consistent across all documents;
+- no placeholders or unresolved policy choices remain;
+- `.gitignore` protects the approved local-data locations and common secret and
+  dump formats;
+- sample checks confirm real-data paths are ignored while synthetic fixtures
+  remain trackable; and
+- Git reports `Codex <codex@localhost>` as the repository-local identity.
+
+## Deferred work
+
+This foundation does not define the detailed financial domain model, database
+schema, UI, importer grammar, duplicate-detection algorithm, deployment model,
+or backup implementation. Each substantial subsystem will receive its own
+design and implementation plan before development.