# DonUI Standing Context Bundle > Aggregated long-form standing context for the DonUI (Donations Frontend) > agent. This file concatenates the **agent charter**, the **project > constitution**, and a pointer to the **DonUI behavioral specification** so an > agent can pull the full standing layer in one fetch. Per the Vercel > agent-readability spec (). > > The concise index is at [`/llms.txt`](https://raw.githubusercontent.com/CitizenGO-Org/soft-donui/main/public/llms.txt). > The operational runbook ([`AGENTS.md`](https://raw.githubusercontent.com/CitizenGO-Org/soft-donui/main/AGENTS.md)) > is intentionally **not** inlined here — it changes more often and is best > read fresh from the working tree. > > If this file disagrees with the source documents it cites, the source > documents win. Sources of truth (canonical on `main`): > > - > - > - --- ## Section 1 — Agent Charter Source: [`docs/agent-spec/01-charter.md`](docs/agent-spec/01-charter.md). # DonUI Agent Charter _Status: v1.0 — Phase 1 of the DonUI Agent Spec_ _Owner: [@adam-palka-cgo](https://github.com/adam-palka-cgo)_ _Last updated: 2026-06-17_ ## Purpose This charter is the **stable contract** for any AI agent that develops the DonUI (Donations Frontend) project. It defines what the agent is allowed to do, what it must never do, and the quality bar every change must clear. Operational "how-to" instructions (commands, repo stack, CI details) live in [`AGENTS.md`](AGENTS.md) and apply to any AI agent working in this repo. Engineering principles and release-quality rules live in [`.specify/memory/constitution.md`](.specify/memory/constitution.md). This charter and the constitution cover different layers and do not override each other: the charter is authoritative on **agent operational boundaries**, the constitution is authoritative on **engineering principles and release quality**. `AGENTS.md` is the shared runbook that executes within those boundaries. ## Precedence The charter and the constitution cover different layers: - **Charter** is authoritative on _agent operational boundaries_: agent permissions, scope of autonomy, stop conditions, git/safety rules for agent actions, and the speckit-flow obligation below. - **Constitution** is authoritative on _engineering principles and release quality_: product scope, quality gates, payment and sensitive-data safety, localization, architecture boundaries, UX/accessibility/performance, and delivery governance. When guidance conflicts, the agent MUST follow this order: 1. Direct user instruction in the current task 2. The document that owns the layer in question (this charter for agent behavior; the constitution for engineering principles) 3. The other of the two, as cross-reference 4. `AGENTS.md` runbook rules 5. Other docs under `docs/` If a conflict cannot be resolved, or the layers themselves disagree, the agent MUST stop and ask for human decision rather than guess. ## Context Delivery (Auto-Load Surface) This charter and the constitution are the **authoritative** layer, but no agent tool auto-loads them. Across tools, only `AGENTS.md` is guaranteed to be in context on every run: Codex reads it literally, and Claude Code pulls it in via the `@AGENTS.md` import in `CLAUDE.md`. The `@path` import directive is **not** cross-tool portable — Codex does not expand it (tracked upstream at [openai/codex#17401](https://github.com/openai/codex/issues/17401)), so a rule that lives only in a linked or imported file is not guaranteed to reach a non-Claude agent at execution time. Consequence: any rule the agent must apply _while working_ — quality gates, the CI/PR done-criteria, the PR output template — is **restated in `AGENTS.md`**, the operative auto-load surface. The charter and constitution remain the single source of truth, fetched on demand when the agent reasons about policy; `AGENTS.md` carries the operative subset and cites them by anchor rather than duplicating prose. When the two disagree, the authoritative document wins (see Precedence), and the `AGENTS.md` restatement is corrected to match — never the reverse. ## Mission and Scope The agent exists to help ship **safe, reliable, conversion-preserving** changes to the DonUI React SPA. In-scope work: - Feature work inside `src/` (components, stores, payment providers, utils, list configurations) - Translations under `public/locales/` - Tests co-located with source (`src/**/*.test.{ts,tsx}`) - Documentation under `docs/` - Local tooling and scripts under `scripts/` and config files when explicitly requested Out-of-scope without explicit human approval: - Changes to payment provider contracts or secrets handling beyond the abstractions already in `src/payment/` - Modifications to CI/CD workflows under `.github/workflows/` - Dependency additions or upgrades (runtime or dev) - Infrastructure, hosting, or Firebase configuration changes - Edits to `.specify/memory/constitution.md` (follow the constitution's own amendment procedure in its Governance section; requires human approval) ## Spec-Driven Workflow (speckit) For any **non-trivial** change, the agent MUST use the speckit flow under `.specify/` rather than jumping straight to code: 1. `/speckit.specify` — produce a feature spec 2. `/speckit.clarify` — resolve underspecified areas 3. `/speckit.plan` — produce the implementation plan (runs the constitution check) 4. `/speckit.tasks` — produce the dependency-ordered task list 5. `/speckit.analyze` — cross-artifact consistency check 6. `/speckit.implement` — execute Artifacts land under `.specify/` (memory, templates) and the feature's spec directory. The constitution check inside the plan template is mandatory; a plan that fails the check MUST NOT proceed to tasks or implementation without a documented Constitutional Exception. **Non-trivial** means any of: new feature or user-visible behavior change, cross-cutting refactor touching more than one module, changes to routing, payment flow, stores, i18n structure, or architecture. **Trivial** means: typo fixes, single-file bug fixes with an obvious root cause, single translation string updates, dependency-free test additions, or doc-only changes. Trivial changes MAY skip the speckit flow but still MUST pass the Mandatory Quality Gates below. When in doubt, use the speckit flow. ### Spec-Kit Behavioral-Spec Integration Feature specs and plans produced by the speckit flow MUST reference the DonUI behavioral specification (under `docs/agent-spec/behavioral/`) by entry **path** (the file path under `behavioral/` without the `.md` suffix, optionally extended with a `#fragment` anchor), never by copying spec content. Concretely: - `/speckit.plan` and `/speckit.tasks` outputs MUST include a "Behavioral-spec references" section listing every behavioral entry they touch, by path (e.g., `capabilities/amount-selection#preset-amount-selected`, `screens/payment-step`, `business-rules#currency-fallback`). - Spec files cite behavioral entries; they do not duplicate prose, scenarios, or screen descriptions from the behavioral spec into the spec. - The behavioral spec is the single source of truth for what DonUI does: capabilities, user flows, screens, business rules, integration contracts, and the configuration surface. - Template enforcement lives in `.specify/templates/`: both `plan-template.md` and `tasks-template.md` pre-populate a "Behavioral-spec references" section that authors must fill with the entries the plan or tasks file actually touches. ## Non-Negotiable Guardrails The agent MUST NOT: - Self-approve or merge its own PRs ([`§VII-no-self-approve`](/.specify/memory/constitution.md#VII-no-self-approve)). - Force-push, rewrite, amend, or otherwise alter git history (including `git push --force`, `git reset --hard` on shared branches, rebase of published commits, or `git commit --amend` after push) without explicit user permission for that specific operation. (Agent-scope: not in the constitution because it constrains agent _actions_, not committed code.) - Produce code that violates [`§III-no-sensitive-logging`](/.specify/memory/constitution.md#III-no-sensitive-logging) or [`§III-ephemeral-secrets`](/.specify/memory/constitution.md#III-ephemeral-secrets), or weaken any payment / sensitive-data safety control ([`§VII-amendment-safety`](/.specify/memory/constitution.md#VII-amendment-safety)). - Include production URLs, API tokens, or real donor data in prompts, tests, fixtures, or commit messages. (Agent-scope.) - Modify more than 3 unrelated modules in a single PR without the `approved-refactor` label and a linked spec ([`§I-pr-module-cap`](/.specify/memory/constitution.md#I-pr-module-cap)). - Introduce GPL or AGPL licensed dependencies into production code. (Agent-scope; license review is an agent-action constraint, not a constitution rule.) - Bypass or disable pre-commit hooks, lint rules, or type checks to make a change pass. (Agent-scope: the gates themselves live at [`§II-lint-type-test`](/.specify/memory/constitution.md#II-lint-type-test) and [`§II-coverage-gate`](/.specify/memory/constitution.md#II-coverage-gate); this rule says the agent must not route around them.) ## Mandatory Quality Gates Quality gates are owned by the constitution, not the charter. Before proposing any change as "done", the agent MUST confirm every Hard Rule under Principle II and the Release Readiness Checklist in [`.specify/memory/constitution.md`](.specify/memory/constitution.md): - [`§II-lint-type-test`](/.specify/memory/constitution.md#II-lint-type-test), [`§II-translation-types`](/.specify/memory/constitution.md#II-translation-types), [`§II-critical-behavior-tests`](/.specify/memory/constitution.md#II-critical-behavior-tests), [`§II-critical-path-coverage`](/.specify/memory/constitution.md#II-critical-path-coverage), [`§II-coverage-gate`](/.specify/memory/constitution.md#II-coverage-gate), [`§II-bugfix-test`](/.specify/memory/constitution.md#II-bugfix-test). - Release Readiness: [`§RR-quality-gates`](/.specify/memory/constitution.md#RR-quality-gates), [`§RR-critical-path-tests`](/.specify/memory/constitution.md#RR-critical-path-tests), [`§RR-coverage-gate`](/.specify/memory/constitution.md#RR-coverage-gate), [`§RR-translation-integrity`](/.specify/memory/constitution.md#RR-translation-integrity), [`§RR-payment-data-safety`](/.specify/memory/constitution.md#RR-payment-data-safety), [`§RR-localization-determinism`](/.specify/memory/constitution.md#RR-localization-determinism), [`§RR-architecture-discipline`](/.specify/memory/constitution.md#RR-architecture-discipline), [`§RR-bug-regression-tests`](/.specify/memory/constitution.md#RR-bug-regression-tests), [`§RR-governance`](/.specify/memory/constitution.md#RR-governance), and the UX/compat checklist row [`§RR-ux-a11y-perf-compat`](/.specify/memory/constitution.md#RR-ux-a11y-perf-compat) for UI/flow changes. If any gate cannot be verified in the current environment, the agent MUST state this explicitly in its summary rather than claim success. Single-run test invocation in agent environments is `yarn vitest run`. ## Definition of Done > The operative restatement of this checklist that agents execute against lives > in `AGENTS.md` (see _Context Delivery_ above). This section remains > authoritative; `AGENTS.md` mirrors its operative subset. A change is only complete when all of the following are true: 1. Every constitution gate listed above (Principle II + Release Readiness Checklist) is green. 2. The PR description includes the governance fields required by [`§VII-pr-fields`](/.specify/memory/constitution.md#VII-pr-fields) (intent, scope, risk assessment, test evidence, rollback notes for high-risk changes). 3. AI attribution footer is present in the PR body (see `AGENTS.md`). 4. For non-trivial changes, a spec exists under `specs/` (per the spec-driven workflow) and the PR description references it by path. 5. A human Tech Lead or AI Maintainer has reviewed and approved (per [`§VII-no-self-approve`](/.specify/memory/constitution.md#VII-no-self-approve)). ## Safety, Privacy, and Data Handling Payment and sensitive-data safety is owned by the constitution. The agent MUST satisfy [`§III-no-sensitive-logging`](/.specify/memory/constitution.md#III-no-sensitive-logging) and [`§III-ephemeral-secrets`](/.specify/memory/constitution.md#III-ephemeral-secrets), and MUST NOT introduce third-party scripts or trackers into the donation flow without explicit human approval (charter scope; this is an agent-action constraint, not a code constraint). ## Escalation and Stop Conditions The agent MUST stop execution and request human input when: - A task requires a change that is out of scope per this charter - A mandatory quality gate cannot be satisfied and the root cause is unclear - A test or lint failure appears unrelated to the current change and may indicate a pre-existing issue - Secrets, credentials, or donor data would be required to proceed - The requested change would weaken payment or sensitive-data safety controls - The change would touch more than 3 unrelated modules - Guidance across sources (user, charter, constitution, `AGENTS.md`) conflicts in a non-trivial way On stop, the agent MUST report: what it tried, what blocked it, what it needs from a human to continue. ## Review and Amendment - This charter is the authoritative decision layer for DonUI agent operational boundaries. Engineering-principle changes belong in the constitution. - Amendments require a PR with rationale, impact notes, and confirmation that no payment or sensitive-data safety control is weakened. - The constitution's versioning policy (MAJOR/MINOR/PATCH) applies by analogy when non-trivial changes are made here. ## References - [`AGENTS.md`](AGENTS.md) — runbook, commands, CEI gates, AI policy - [`.specify/memory/constitution.md`](.specify/memory/constitution.md) — engineering principles and governance - [`.husky/pre-commit`](.husky/pre-commit) — enforced local gate - [`docs/qa-prod.md`](/docs/qa-prod.md) — QA/CD narrative --- ## Section 2 — Project Constitution Source: [`.specify/memory/constitution.md`](.specify/memory/constitution.md). **Version**: 1.6.2 # Donations Frontend Constitution ## Core Principles ### I. Product Scope and Compatibility Guardrails Rationale: Donations are trust-critical and conversion-critical; reliability and donor confidence outrank local elegance. Hard Rules: - The product MUST be treated as a donation flow system where reliability, trust, and conversion safety are primary objectives. - Core donation routes and language-first routing behavior MUST remain backward compatible unless a breaking change is explicitly approved and migration notes exist. - A single PR MUST NOT modify more than 3 unrelated modules or touch files outside its stated feature scope. Cross-cutting refactors require an explicit approval label and a dedicated spec document. Verification: - Plan/spec documents include explicit compatibility impact and migration notes when route behavior changes. - PR description lists all modified modules; changes spanning more than 3 modules require an "approved-refactor" label and linked spec. ### II. Non-Negotiable Quality Gates Rationale: Payment, routing, validation, and state behavior regressions directly affect donations and donor trust. Hard Rules: - Before merge, `yarn lint`, `yarn tsc -b`, and `yarn test` MUST pass. - Any translation-related change MUST run translation type generation and MUST commit updated `src/types/resources.d.ts` when output changes. - Behavior changes in payment, routing, stores, i18n, and form validation MUST include tests. - Changed critical paths (payments, form steps, routing) MUST be covered by tests; untested critical-path logic MUST NOT be merged. - Every modified source file MUST reach 100% statement and branch coverage, verified per file via `yarn test:coverage --coverage.include=""`. Gaps MUST be closed with additional tests, not coverage exclusions. The CI coverage report MUST be reviewed on every PR before merge. - Every bug fix — whether a regression caught in production or a defect reported as a task — MUST be accompanied by a unit test that fails before the fix and passes after. The test MUST be committed in the same PR as the fix. Verification: - CI artifacts show passing lint, type-check, and tests. - PR test evidence maps each changed critical-path behavior to at least one test file. - Diff review confirms `src/types/resources.d.ts` synchronization for translation edits. - CI coverage report is reviewed on every PR before merge. ### III. Payment and Sensitive Data Safety Rationale: Payment flows are high-risk and must minimize exposure of donor-sensitive information. Hard Rules: - Code MUST NOT log card or bank details, client secrets, tokens, credentials, or raw provider payloads with sensitive fields. - Client secrets MUST be handled ephemerally in memory; they MUST NOT be persisted in stores, local storage, session storage, or analytics payloads. Verification: - Review checklist includes explicit "no sensitive logging/persistence" confirmation. ### IV. Localization and Routing Determinism Rationale: Locale integrity is core to donor clarity and legal/campaign correctness. Hard Rules: - `en-row` MUST remain the source-of-truth fallback locale. - New translation keys MUST include `en-row` updates and structure consistency checks across touched locales. - Source code MUST NOT call `t('key', ...)` with a key absent from `en-row/translation.json`. Use a hardcoded string or i18next fallback default instead. Referencing non-existent keys is a locale integrity violation even when a runtime fallback is provided. - Language behavior in routes MUST stay deterministic and language-first. - Locale configuration and translation resources MUST stay synchronized on each merge. Verification: - Translation-change PRs include evidence of key parity and regenerated types. - Routing tests assert deterministic language-first URL handling. ### V. Architecture Boundaries and State Discipline Rationale: Stable domain boundaries reduce regressions and make payment logic auditable. Hard Rules: - Domain store boundaries MUST be preserved: payment, campaign, member, method, and config responsibilities remain explicit. - Shared utilities SHOULD stay pure and independently testable; unavoidable side effects MUST be isolated behind clear interfaces. - UI components MUST NOT couple directly to provider internals when an abstraction exists. Verification: - Design notes/PR rationale explain any boundary shift and why it is unavoidable. - Tests cover pure utilities and abstraction contracts when behavior changes. ### VI. UX, Accessibility, Performance, and Browser/Device Compatibility Rationale: Donation completion depends on clear steps, mobile usability, responsive interactions, and consistent behavior across the browsers and devices donors actually use. Hard Rules: - Donation flow updates MUST preserve mobile usability and clear step progression. - Accessibility regressions are prohibited for form inputs, labels, focus, and interaction controls. - Performance-sensitive paths (initial load and form interactions) SHOULD avoid unnecessary rerenders and heavy synchronous work. - The donation flow MUST function correctly on the two latest stable versions of Chrome, Firefox, Safari, and Edge. - Mobile viewport rendering MUST be validated on representative iOS (Safari) and Android (Chrome) devices or emulators; layout breakage or unusable payment inputs are blocking issues. - Browser-specific workarounds MUST be isolated (e.g., feature-detect, polyfill, or targeted CSS) and MUST NOT degrade the primary supported-browser experience. Verification: - PR evidence includes mobile and accessibility checks for changed flow screens. - Performance-sensitive changes include rationale for render impact and mitigation. - UI/flow changes include cross-browser smoke-test evidence (screenshots or CI matrix results) covering the required browser matrix. - Mobile-viewport layout is validated on at least one iOS and one Android target before merge. ### VII. Delivery Governance and Anti-Overengineering Rationale: Predictable delivery quality depends on explicit risk control and disciplined scope. Hard Rules: - Package manager standard is `yarn`; new scripts and docs MUST use `yarn` commands. - PRs MUST include intent, risk assessment, test evidence, and rollback notes for high-risk changes. - AI-generated changes MUST receive human review; AI systems MUST NOT self-approve. - New dependencies or major abstractions require explicit justification: problem, alternatives considered, and trade-offs. - Constitution amendments MUST include rationale and impact notes, and MUST NOT weaken payment or sensitive data safety controls. Verification: - PR template/review comments show required governance fields. - Amendment diffs include rationale and impact notes with explicit safety non-regression. ## Operational Standards - Runtime stack baseline: React 19, TypeScript, Vite, Zustand, Vitest, and payment providers Stripe/PayPal/PayU/GoCardless. - Default implementation strategy is the simplest compliant approach; complexity is allowed only with clear, written justification. - Any unavoidable rule exception MUST be documented in the plan under a "Constitutional Exception" entry with approver and expiry. ## Release Readiness Checklist - `Quality Gates`: `yarn lint`, `yarn tsc -b`, and `yarn test` all pass. - `Critical Path Tests`: payment/form-step/routing changes include passing tests; no untested critical logic is merged. - `Coverage Gate`: every modified source file reaches 100% statement and branch coverage via `yarn test:coverage --coverage.include=""`; CI report reviewed on every PR before merge. Gaps closed with tests, not exclusions. - `Translation Integrity`: translation changes regenerated via `yarn generate-translation-types`, with `src/types/resources.d.ts` committed when changed. No source-code `t('key')` calls reference keys absent from `en-row/translation.json`; hardcoded strings or fallback defaults used instead. - `Payment/Data Safety`: sensitive data is not logged or persisted. - `Localization Determinism`: `en-row` fallback and language-first routing remain valid. - `Architecture Discipline`: store boundaries and provider abstractions are preserved. - `UX/A11y/Performance/Compat`: no form accessibility regressions; mobile flow and interaction responsiveness validated; cross-browser smoke test covers Chrome, Firefox, Safari, and Edge (latest 2 versions); iOS and Android mobile viewports validated. - `Bug/Regression Tests`: every bug fix includes a unit test that fails before the fix and passes after; test ships in the same PR as the fix. - `Governance`: PR includes intent, risk, test evidence, and rollback notes for high-risk changes; human review completed. ## Governance - This constitution is authoritative for **engineering principles, product scope, and release quality** in Donations Frontend: planning, specification, tasks, review, and release decisions about how code is written and shipped. - The DonUI Agent Charter (`docs/agent-spec/01-charter.md`) is the companion authority for **AI agent operational boundaries**: what an agent may do, must not do, and when it must stop. The two layers are complementary; neither overrides the other within its own layer. Where a question spans both layers and the documents disagree, the work MUST stop for human decision. - Compliance review is mandatory in planning and PR review; unresolved non-compliance blocks merge. - Versioning policy: - MAJOR: backward-incompatible governance or principle removal/redefinition. - MINOR: new principle/section or materially expanded mandatory guidance. - PATCH: clarifications that do not change obligations. - Amendment procedure: - Propose amendment with rationale, impact analysis, and migration steps if needed. - Confirm no weakening of payment/data safety controls. - Record updated version and amendment date in this file. - Dependent documents (the agent charter, spec-kit templates, `AGENTS.md`, and `public/llms-full.txt`) MUST cite this constitution by anchor id rather than restating Hard Rule, Verification, or Release Readiness text. Citations MUST use the Markdown link form with a repo-rooted absolute path: `[§](/.specify/memory/constitution.md#)` (for example, `[§II-bugfix-test](/.specify/memory/constitution.md#II-bugfix-test)`). The repo-rooted path makes the link resolve from any file location on GitHub (templates, instantiated specs under `specs/`, charter, `AGENTS.md`), and lets Markdown link checkers validate both the target file and the `#anchor` fragment. Plain-text `§` references without a link MUST NOT be introduced in new edits to these dependent documents. This keeps single-rule amendments localized to this file (plus a regenerated `llms-full.txt`) and prevents drift between the constitution and its consumers. **Version**: 1.6.2 | **Ratified**: 2026-02-25 | **Last Amended**: 2026-05-12 --- ## Section 3 — Behavioral Specification Pointer Source: [`docs/agent-spec/behavioral/`](docs/agent-spec/behavioral/). Entry point: [`behavioral/overview.md`](docs/agent-spec/behavioral/overview.md). Phase 9 is v1 sign-off. Citation rules for spec-kit artefacts live in charter § _Spec-Kit Behavioral-Spec Integration_. --- _End of standing context bundle._