docs(governance): track context docs and add relay rollout controls

2026-03-24 12:26:32 +00:00
parent 2ac2f51fc3
commit ad0d2bf285
11 changed files with 847 additions and 1 deletions
@@ -0,0 +1,52 @@
+# Coding Conventions (Repository-Specific)
+
+## Language and Style
+
+- Default to JavaScript for new work unless area is already TypeScript.
+- Use existing formatting:
+    - 4 spaces
+    - no trailing commas
+    - preserve existing quote style in touched file
+- Avoid broad stylistic rewrites in functional changes.
+
+## File Placement and Boundaries
+
+- Keep `pages/` focused on route wiring, data fetch orchestration, and composition.
+- Move reusable domain logic into `lib/` or `actions/`.
+- Keep reusable UI in `components/` (feature subfolders preferred).
+- Keep Redux behavior changes localized to relevant slice and `store/store.js` integration points.
+
+## API Route Conventions
+
+- Follow existing API naming where present (`*_api.js` in `pages/api/endpoint`, `pages/api/file`, `pages/api/admin`).
+- Maintain explicit error handling and return predictable response shapes.
+- For sensitive endpoints, include authorization and invalid-input paths.
+
+## Auth/Session Conventions
+
+- `pages/api/auth/[...nextauth].js` is authoritative for auth flow behavior.
+- Do not bypass session checks in protected routes/components.
+- Preserve secure redirect/callback behavior and cookie safety settings.
+
+## i18n Conventions
+
+- Add user-facing strings to locale files (`locales/en`, `locales/cy`) where feasible.
+- Keep EN/CY route behavior aligned when adding/changing pages.
+- If a route alias changes in Welsh, verify rewrite mapping in `next.config.js` and page namespaces in `i18n.js`.
+
+## Accessibility Conventions
+
+- Use semantic HTML and maintain heading hierarchy.
+- Ensure keyboard access and visible focus states.
+- Provide meaningful labels and error messages.
+
+## Logging and Error Handling
+
+- Never log secrets, tokens, personal details, or raw credential payloads.
+- Keep operational logs concise and safe for production telemetry.
+- Prefer structured, actionable errors over generic catch-and-ignore patterns.
+
+## Legacy and Mixed-Pattern Guidance
+
+- Where conventions conflict between folders, follow the dominant local pattern and record exceptions in `memory-bank/decisions.md`.
+- Refactor incrementally: separate behavior changes from structural cleanup.