@schneiderjoseph/devia 0.1.0

package/rules/architecture/ARC-006.md

@@ -0,0 +1,39 @@
+---
+id: ARC-006
+title: Environment-specific values come from configuration
+severity: MUST
+status: active
+domain: architecture
+priority: P1
+source:
+  - devia
+applies_to:
+  - repository
+success_criteria:
+  []
+requirement: >
+  Hosts, URLs, credentials, feature flags and limits MUST come from configuration, never from literals in application code, and MUST have a documented default for local development.
+validation:
+  automated: true
+  manual: true
+exceptions: documented-only
+---
+
+# ARC-006 — Environment-specific values come from configuration
+
+**Requirement:** Hosts, URLs, credentials, feature flags and limits MUST come from configuration, never from literals in application code, and MUST have a documented default for local development.
+
+**Bad:** `https://api.staging.example.com` hardcoded in a client module.
+
+**Good:** `config.apiBaseUrl`, sourced from the environment, documented in `.env.example`.
+
+## Validation
+
+- Grep the diff for environment hostnames and absolute paths
+- `.env.example` updated
+
+## Lifecycle
+
+- Status: `active`
+- Priority: `P1`
+- Exceptions: `documented-only`

package/rules/components/CMP-001.md

@@ -0,0 +1,39 @@
+---
+id: CMP-001
+title: Button hierarchy
+severity: MUST
+status: active
+priority: P1
+domain: components
+source:
+  - GOV.UK
+  - Carbon
+applies_to:
+  - button
+success_criteria:
+  []
+requirement: >
+  A view MUST NOT present multiple primary buttons of equal weight for competing actions.
+validation:
+  automated: false
+  manual: true
+exceptions: documented-only
+---
+
+# CMP-001 — Button hierarchy
+
+**Requirement:** A view MUST NOT present multiple primary buttons of equal weight for competing actions.
+
+**Bad:** Three filled primary buttons in one toolbar.
+
+**Good:** One primary; others secondary/tertiary/ghost.
+
+## Validation
+
+- Design or engineering review
+
+## Lifecycle
+
+- Status: `active`
+- Priority: `P1`
+- Exceptions: `documented-only`

package/rules/components/CMP-002.md

@@ -0,0 +1,38 @@
+---
+id: CMP-002
+title: Disabled action explains enablement
+severity: SHOULD
+status: active
+priority: P2
+domain: components
+source:
+  - NN/g
+applies_to:
+  - button
+success_criteria:
+  []
+requirement: >
+  If a primary action is disabled, the UI SHOULD explain how to enable it.
+validation:
+  automated: false
+  manual: true
+exceptions: documented-only
+---
+
+# CMP-002 — Disabled action explains enablement
+
+**Requirement:** If a primary action is disabled, the UI SHOULD explain how to enable it.
+
+**Bad:** Gray Save with no hint.
+
+**Good:** Inline hint: ‘Complete required fields to save’.
+
+## Validation
+
+- Design or engineering review
+
+## Lifecycle
+
+- Status: `active`
+- Priority: `P2`
+- Exceptions: `documented-only`

package/rules/components/CMP-003.md

@@ -0,0 +1,39 @@
+---
+id: CMP-003
+title: Data table headers
+severity: MUST
+status: active
+priority: P1
+domain: components
+source:
+  - WCAG-2.2
+applies_to:
+  - table
+success_criteria:
+  - "1.3.1"
+requirement: >
+  Data tables MUST use proper header cells associated with data.
+validation:
+  automated: true
+  manual: true
+exceptions: documented-only
+---
+
+# CMP-003 — Data table headers
+
+**Requirement:** Data tables MUST use proper header cells associated with data.
+
+**Bad:** Bold first row of td only.
+
+**Good:** th scope="col" (or row headers when needed).
+
+## Validation
+
+- Automated checks / lint / a11y tooling where applicable
+- Design or engineering review
+
+## Lifecycle
+
+- Status: `active`
+- Priority: `P1`
+- Exceptions: `documented-only`

package/rules/components/CMP-004.md

@@ -0,0 +1,40 @@
+---
+id: CMP-004
+title: Row actions usable on small widths
+severity: SHOULD
+status: active
+priority: P2
+domain: components
+source:
+  - Carbon
+  - Atlassian
+applies_to:
+  - table
+  - mobile
+success_criteria:
+  []
+requirement: >
+  Row actions SHOULD remain usable at common widths (overflow menu or alternative).
+validation:
+  automated: false
+  manual: true
+exceptions: documented-only
+---
+
+# CMP-004 — Row actions usable on small widths
+
+**Requirement:** Row actions SHOULD remain usable at common widths (overflow menu or alternative).
+
+**Bad:** Six icon actions crushed on mobile with no menu.
+
+**Good:** Overflow menu or responsive action pattern.
+
+## Validation
+
+- Design or engineering review
+
+## Lifecycle
+
+- Status: `active`
+- Priority: `P2`
+- Exceptions: `documented-only`

package/rules/components/CMP-005.md

@@ -0,0 +1,39 @@
+---
+id: CMP-005
+title: Dialog accessibility pattern
+severity: MUST
+status: active
+priority: P0
+domain: components
+source:
+  - WAI-ARIA-APG
+applies_to:
+  - dialog
+success_criteria:
+  []
+requirement: >
+  Modal dialogs MUST: label the dialog, trap focus, close on Escape, restore focus, and inert background content.
+validation:
+  automated: true
+  manual: true
+exceptions: documented-only
+---
+
+# CMP-005 — Dialog accessibility pattern
+
+**Requirement:** Modal dialogs MUST: label the dialog, trap focus, close on Escape, restore focus, and inert background content.
+
+**Bad:** Div overlay, focus escapes, no Escape.
+
+**Good:** APG-compliant dialog component.
+
+## Validation
+
+- Automated checks / lint / a11y tooling where applicable
+- Design or engineering review
+
+## Lifecycle
+
+- Status: `active`
+- Priority: `P0`
+- Exceptions: `documented-only`

package/rules/content/CNT-001.md

@@ -0,0 +1,39 @@
+---
+id: CNT-001
+title: Action-oriented labels
+severity: SHOULD
+status: active
+priority: P2
+domain: content
+source:
+  - GOV.UK
+applies_to:
+  - button
+  - dialogs
+success_criteria:
+  []
+requirement: >
+  Buttons SHOULD say the outcome (‘Save changes’), not vague OK/Submit when context is unclear.
+validation:
+  automated: false
+  manual: true
+exceptions: documented-only
+---
+
+# CNT-001 — Action-oriented labels
+
+**Requirement:** Buttons SHOULD say the outcome (‘Save changes’), not vague OK/Submit when context is unclear.
+
+**Bad:** Modal: OK / Cancel with ambiguous title.
+
+**Good:** Delete customer / Keep customer.
+
+## Validation
+
+- Design or engineering review
+
+## Lifecycle
+
+- Status: `active`
+- Priority: `P2`
+- Exceptions: `documented-only`

package/rules/data-display/DATA-001.md

@@ -0,0 +1,39 @@
+---
+id: DATA-001
+title: Currency context explicit
+severity: MUST
+status: active
+priority: P1
+domain: data-display
+source:
+  - i18n-best-practice
+applies_to:
+  - currency
+  - tables
+success_criteria:
+  []
+requirement: >
+  Currency values MUST retain explicit currency context (code or symbol+locale-aware formatting).
+validation:
+  automated: false
+  manual: true
+exceptions: documented-only
+---
+
+# DATA-001 — Currency context explicit
+
+**Requirement:** Currency values MUST retain explicit currency context (code or symbol+locale-aware formatting).
+
+**Bad:** 1,250.00
+
+**Good:** HTG 1,250.00 / USD 1,250.00 (locale-aware).
+
+## Validation
+
+- Design or engineering review
+
+## Lifecycle
+
+- Status: `active`
+- Priority: `P1`
+- Exceptions: `documented-only`

package/rules/data-display/DATA-002.md

@@ -0,0 +1,39 @@
+---
+id: DATA-002
+title: Dates unambiguous
+severity: MUST
+status: active
+priority: P1
+domain: data-display
+source:
+  - i18n-best-practice
+applies_to:
+  - dates
+  - tables
+success_criteria:
+  []
+requirement: >
+  Dates MUST be unambiguous for the audience locale (avoid 03/04/05 without context).
+validation:
+  automated: false
+  manual: true
+exceptions: documented-only
+---
+
+# DATA-002 — Dates unambiguous
+
+**Requirement:** Dates MUST be unambiguous for the audience locale (avoid 03/04/05 without context).
+
+**Bad:** 03/04/05 in mixed FR/EN teams.
+
+**Good:** 4 Mar 2026 or ISO date in dense tables with legend.
+
+## Validation
+
+- Design or engineering review
+
+## Lifecycle
+
+- Status: `active`
+- Priority: `P1`
+- Exceptions: `documented-only`

package/rules/data-display/DATA-003.md

@@ -0,0 +1,40 @@
+---
+id: DATA-003
+title: Numeric alignment
+severity: SHOULD
+status: active
+priority: P2
+domain: data-display
+source:
+  - Carbon
+  - Atlassian
+applies_to:
+  - tables
+  - numbers
+success_criteria:
+  []
+requirement: >
+  Columns of comparable numbers SHOULD be right-aligned (or tabular lining) for scanability.
+validation:
+  automated: false
+  manual: true
+exceptions: documented-only
+---
+
+# DATA-003 — Numeric alignment
+
+**Requirement:** Columns of comparable numbers SHOULD be right-aligned (or tabular lining) for scanability.
+
+**Bad:** Left-aligned money column wandering.
+
+**Good:** Tabular nums, consistent decimals.
+
+## Validation
+
+- Design or engineering review
+
+## Lifecycle
+
+- Status: `active`
+- Priority: `P2`
+- Exceptions: `documented-only`

package/rules/data-display/DATA-004.md

@@ -0,0 +1,40 @@
+---
+id: DATA-004
+title: Sort and filter feedback
+severity: MUST
+status: active
+priority: P1
+domain: data-display
+source:
+  - NN/g
+  - Atlassian
+applies_to:
+  - tables
+  - filtering
+success_criteria:
+  []
+requirement: >
+  Active sort/filter MUST be visible; empty filtered results MUST explain how to reset.
+validation:
+  automated: false
+  manual: true
+exceptions: documented-only
+---
+
+# DATA-004 — Sort and filter feedback
+
+**Requirement:** Active sort/filter MUST be visible; empty filtered results MUST explain how to reset.
+
+**Bad:** Invisible filters leaving an empty table.
+
+**Good:** Filter chips + Clear filters.
+
+## Validation
+
+- Design or engineering review
+
+## Lifecycle
+
+- Status: `active`
+- Priority: `P1`
+- Exceptions: `documented-only`

package/rules/database/DB-001.md

@@ -0,0 +1,43 @@
+---
+id: DB-001
+title: Every schema change is a versioned migration
+severity: MUST
+status: active
+domain: database
+priority: P0
+source:
+  - devia
+applies_to:
+  - database
+success_criteria:
+  []
+requirement: >
+  Schema changes MUST ship as ordered, committed migration files that run in CI and in every environment. Schema MUST NOT be changed by hand in any environment, least of all production.
+validation:
+  automated: true
+  manual: true
+exceptions: none
+---
+
+# DB-001 — Every schema change is a versioned migration
+
+**Requirement:** Schema changes MUST ship as ordered, committed migration files that run in CI and in every environment. Schema MUST NOT be changed by hand in any environment, least of all production.
+
+**Bad:** A column added through a database console; the next deploy fails on a machine nobody touched.
+
+**Good:** `migrations/20260903_add_invoice_currency.sql`, applied by the deploy pipeline.
+
+## Validation
+
+- Migration file present in the diff
+- Migration runs on a clean database in CI
+
+## Lifecycle
+
+- Status: `active`
+- Priority: `P0`
+- Exceptions: `none`
+
+## See also
+
+- [MIGRATIONS.md](../../standard/engineering/database/MIGRATIONS.md)

package/rules/database/DB-002.md

@@ -0,0 +1,38 @@
+---
+id: DB-002
+title: Applied migrations are immutable
+severity: MUST NOT
+status: active
+domain: database
+priority: P0
+source:
+  - devia
+applies_to:
+  - database
+success_criteria:
+  []
+requirement: >
+  A migration that has run in any shared environment MUST NOT be edited. Corrections ship as a new migration.
+validation:
+  automated: false
+  manual: true
+exceptions: none
+---
+
+# DB-002 — Applied migrations are immutable
+
+**Requirement:** A migration that has run in any shared environment MUST NOT be edited. Corrections ship as a new migration.
+
+**Bad:** Editing yesterday's migration so it 'works now' — silently diverging every environment that already ran it.
+
+**Good:** A new corrective migration that brings every environment to the same state.
+
+## Validation
+
+- Confirm no already-applied migration file is modified in the diff
+
+## Lifecycle
+
+- Status: `active`
+- Priority: `P0`
+- Exceptions: `none`

package/rules/database/DB-003.md

@@ -0,0 +1,40 @@
+---
+id: DB-003
+title: Money is exact and carries its currency
+severity: MUST
+status: active
+domain: database
+priority: P0
+source:
+  - devia
+applies_to:
+  - database
+  - service
+success_criteria:
+  []
+requirement: >
+  Monetary amounts MUST use an exact type (decimal or minor-unit integer), never a float, and MUST be stored with an explicit currency. Rounding MUST happen at a single documented point.
+validation:
+  automated: true
+  manual: true
+exceptions: none
+---
+
+# DB-003 — Money is exact and carries its currency
+
+**Requirement:** Monetary amounts MUST use an exact type (decimal or minor-unit integer), never a float, and MUST be stored with an explicit currency. Rounding MUST happen at a single documented point.
+
+**Bad:** `price REAL` and a currency inferred from the user's locale at render time.
+
+**Good:** `amount numeric(14,2)` plus `currency char(3)`, rounded once in the pricing service.
+
+## Validation
+
+- Grep the migration for float or double on money columns
+- Confirm currency is stored, not inferred
+
+## Lifecycle
+
+- Status: `active`
+- Priority: `P0`
+- Exceptions: `none`

package/rules/database/DB-004.md

@@ -0,0 +1,44 @@
+---
+id: DB-004
+title: Backups exist and restore has been rehearsed
+severity: MUST
+status: active
+domain: database
+priority: P0
+source:
+  - devia
+applies_to:
+  - database
+  - devops
+success_criteria:
+  []
+requirement: >
+  Production data MUST be backed up on a defined schedule, and the restore MUST have been performed at least once, with the date and the result recorded. An untested backup is not a backup.
+validation:
+  automated: false
+  manual: true
+exceptions: none
+---
+
+# DB-004 — Backups exist and restore has been rehearsed
+
+**Requirement:** Production data MUST be backed up on a defined schedule, and the restore MUST have been performed at least once, with the date and the result recorded. An untested backup is not a backup.
+
+**Bad:** Nightly snapshots nobody has ever restored.
+
+**Good:** Snapshots plus a rehearsed restore into a scratch environment, recorded with the elapsed time.
+
+## Validation
+
+- Backup schedule documented
+- Restore drill recorded with a date
+
+## Lifecycle
+
+- Status: `active`
+- Priority: `P0`
+- Exceptions: `none`
+
+## See also
+
+- [disaster-recovery.md](../../checklists/engineering/disaster-recovery.md)

package/rules/database/DB-005.md

@@ -0,0 +1,39 @@
+---
+id: DB-005
+title: Destructive operations are recoverable where the domain requires it
+severity: SHOULD
+status: active
+domain: database
+priority: P2
+source:
+  - devia
+applies_to:
+  - database
+  - service
+success_criteria:
+  []
+requirement: >
+  Records that carry history, money or accountability SHOULD be archived or soft-deleted rather than hard-deleted, and the choice SHOULD be recorded in the data model.
+validation:
+  automated: false
+  manual: true
+exceptions: documented-only
+---
+
+# DB-005 — Destructive operations are recoverable where the domain requires it
+
+**Requirement:** Records that carry history, money or accountability SHOULD be archived or soft-deleted rather than hard-deleted, and the choice SHOULD be recorded in the data model.
+
+**Bad:** `DELETE FROM users` on account closure, taking the audit trail with it.
+
+**Good:** `archived_at` plus a retention job that removes personal data on schedule.
+
+## Validation
+
+- The data model states the deletion strategy per entity
+
+## Lifecycle
+
+- Status: `active`
+- Priority: `P2`
+- Exceptions: `documented-only`

package/rules/database/DB-006.md

@@ -0,0 +1,38 @@
+---
+id: DB-006
+title: Queries the application actually runs are indexed
+severity: SHOULD
+status: active
+domain: database
+priority: P2
+source:
+  - devia
+applies_to:
+  - database
+success_criteria:
+  []
+requirement: >
+  Filter, join and sort columns used by real queries SHOULD be indexed, and an index SHOULD be justified by a query rather than added speculatively.
+validation:
+  automated: false
+  manual: true
+exceptions: documented-only
+---
+
+# DB-006 — Queries the application actually runs are indexed
+
+**Requirement:** Filter, join and sort columns used by real queries SHOULD be indexed, and an index SHOULD be justified by a query rather than added speculatively.
+
+**Bad:** A list endpoint scanning a million rows on every request.
+
+**Good:** An index on the actual predicate, verified with an execution plan before and after.
+
+## Validation
+
+- Execution plan for the new or changed query
+
+## Lifecycle
+
+- Status: `active`
+- Priority: `P2`
+- Exceptions: `documented-only`