QT/sure

mirror of https://github.com/we-promise/sure.git synced 2026-09-08 08:04:15 +00:00

Files

T

Juan José Mata 157daf5176 Consolidate repository instructions after auditing their history (#3409 )

* Document instruction inventory and preservation decisions

Trace main history from September 2025 through September 2026, including earlier policy origins. Record preserved requirements, detailed-guide destinations, stale facts, harness boundaries and explicit policy-strength decisions before consolidating instruction sources.

* Consolidate repository instructions into shared guidance

Keep AGENTS concise and vendor neutral, move detailed conventions into shared guides, and use thin adapters with preserved Cursor scopes. Preserve the strict pre-PR checks globally and document the stronger scope, retired migration pin and rule-generation trigger. Update existing API guidance verification without changing application behavior.

* Narrow the always-on Cursor UI adapter and correct the SimpleFIN comment

Split the design-system guidance out of docs/llm-guides/ui.md into
docs/llm-guides/design-system.md. The ui-ux-design-guidelines rule is
alwaysApply: true, so importing all of ui.md loaded the Stimulus,
localization and ViewComponent guidance (previously confined to scoped
rules) on every Cursor session; the always-on adapter now imports only the
design-system guide, matching the scope it had before the consolidation.
view_conventions and stimulus_conventions keep the full UI guide.

Also correct the stale Provider::Simplefin header comment: pending
inclusion defaults on and is resolved by the importer (explicit argument,
then SIMPLEFIN_INCLUDE_PENDING, then Setting.syncs_include_pending); the
previous comment described the flag as default-off.

* Read guidance files as UTF-8 in the API consistency validators

The frontmatter regex match ran against content read with the locale
default external encoding; the Cursor rule's description contains an em
dash, so under US-ASCII (LC_ALL=C) Regexp#match raised ArgumentError,
breaking the standalone no-Rails fallback the docs point contributors to.
Read all checked files with an explicit UTF-8 encoding in both the
standalone script and the Rails test.

2026-09-06 07:14:43 +02:00

4.8 KiB

Raw Blame History

Repository guidance

Working in the repository

Read architecture and conventions before changing code, and the relevant task guides.
Rails code lives in app/; keep business logic in models, concerns and POROs, with thin controllers. JavaScript is in app/javascript/, components in app/components/, assets in app/assets/, and configuration in config/.
Minitest tests mirror app/ under test/; fixtures are in test/fixtures/. Migrations and schema are in db/, scripts in bin/, shared libraries in lib/.
Use Current.user and Current.family, never current_user or current_family. Preserve family tenancy and existing authorization boundaries.
Prefer built-in Rails patterns and established dependencies. New dependencies need a strong technical or business reason. Keep changes focused, readable and consistent with nearby code.
Ruby uses two-space indentation, snake_case methods/variables and CamelCase classes. JavaScript uses lowerCamelCase variables/functions and PascalCase classes; follow Biome. Keep domain logic out of ERB.
Never commit secrets; use environment variables and .env.local for local configuration.
Do not start rails server, touch tmp/restart.txt, run rails credentials, or automatically run migrations. Setup and database commands in the development guide are for explicitly requested environment work.
New migrations use the current Rails migration version; leave historical migration versions intact.

Tests and pull requests

Use Minitest and fixtures for behavioral tests, with Mocha and VCR where needed. RSpec/rswag is for OpenAPI documentation only. Follow the testing guide.
Run bin/rails test and ensure it is green before pushing. Before opening a PR, run all checks in the pre-PR checklist: full Rails tests, applicable system tests, Ruby and ERB lint, Biome and Brakeman. Only create the PR when all required checks pass.
Commits use imperative subjects of at most 72 characters, with rationale and issue references where relevant. Target main with small, cohesive changes.
PRs explain the problem, resulting behavior and validation; link issues and include screenshots for UI changes and migration notes when applicable. Ensure CI passes and the branch is up to date before requesting review; see CONTRIBUTING.md.

UI changes

When touching ERB, view components or CSS, follow the design system guide:

Use functional tokens from app/assets/tailwind/sure-design-system.css, such as bg-container, text-primary, border-primary, bg-warning/10 and text-destructive. No raw Tailwind palette classes or hex literals.
Check app/components/DS/ first for alerts, badges, buttons, disclosures, dialogs and inputs. Use existing DS::* primitives.
If the same hand-built shape appears at least twice in a diff with no DS equivalent, propose a new DS::* primitive before the second copy lands.
Use the icon helper, never lucide_icon directly; no raw SVG outside DS primitives. Use t() for user-facing strings and scale tokens instead of arbitrary pixel values when a scale token fits.
Adding styles to app/assets/tailwind/sure-design-system.css or app/assets/tailwind/application.css requires explicit permission.
Reviewers escalate DS reuse and repeated-shape violations to close/rewrite; token and icon/SVG/localization/scale violations are request-changes.

API changes

Adding or modifying app/controllers/api/v1/ endpoints requires Minitest behavioral coverage and corresponding documentation-only rswag specs in spec/requests/api/v1/. Reusable schemas belong in spec/swagger_helper.rb; regenerate docs/api/openapi.yaml with RAILS_ENV=test bundle exec rake rswag:specs:swaggerize after changes.

Post-commit API consistency: after every API endpoint commit, follow the API checklist: Minitest coverage, no behavioral assertions in rswag, and the shared X-Api-Key authentication pattern in those tests/specs.

Provider and feature work

Read provider sync guidance when changing imports, pending transactions, FX metadata or diagnostics. Use DebugLogEntry.capture(...) for support-relevant failures and partial responses, with provider/source metadata and family/account-provider context where available.
For securities providers, follow adding a securities provider.
For feature rollout, follow preview-feature gating; for goals, read the Goals guide.

4.8 KiB Raw Blame History