@schneiderjoseph/devia 0.1.0

package/rules/database/DB-007.md

@@ -0,0 +1,40 @@
+---
+id: DB-007
+title: Sensitive actions are written to an append-only audit trail
+severity: MUST
+status: active
+domain: database
+priority: P1
+source:
+  - OWASP ASVS 5.0 V7
+applies_to:
+  - database
+  - service
+success_criteria:
+  []
+requirement: >
+  Authentication events, permission changes, money movement, data export and administrative overrides MUST be recorded with actor, timestamp, target and outcome, in a store that is append-only.
+validation:
+  automated: false
+  manual: true
+exceptions: documented-only
+---
+
+# DB-007 — Sensitive actions are written to an append-only audit trail
+
+**Requirement:** Authentication events, permission changes, money movement, data export and administrative overrides MUST be recorded with actor, timestamp, target and outcome, in a store that is append-only.
+
+**Bad:** An admin changes a payout and nothing anywhere records who did it.
+
+**Good:** An `audit_log` row written in the same transaction as the change, never updated afterwards.
+
+## Validation
+
+- The action appears in the audit list in `.devia/04_PERMISSIONS.md`
+- A test asserts the row is written
+
+## Lifecycle
+
+- Status: `active`
+- Priority: `P1`
+- Exceptions: `documented-only`

package/rules/database/DB-008.md

@@ -0,0 +1,40 @@
+---
+id: DB-008
+title: Queries are parameterised
+severity: MUST NOT
+status: active
+domain: database
+priority: P0
+source:
+  - OWASP ASVS 5.0 V5
+applies_to:
+  - database
+  - service
+success_criteria:
+  []
+requirement: >
+  SQL MUST NOT be assembled by concatenating user-controlled values. Use parameters or a query builder that parameterises.
+validation:
+  automated: true
+  manual: true
+exceptions: none
+---
+
+# DB-008 — Queries are parameterised
+
+**Requirement:** SQL MUST NOT be assembled by concatenating user-controlled values. Use parameters or a query builder that parameterises.
+
+**Bad:** `"select * from users where email = '" + email + "'"`.
+
+**Good:** `select * from users where email = $1` with the value passed as a parameter.
+
+## Validation
+
+- Grep the diff for string-built SQL
+- Static analysis rule enabled
+
+## Lifecycle
+
+- Status: `active`
+- Priority: `P0`
+- Exceptions: `none`

package/rules/design-system/DS-001.md

@@ -0,0 +1,39 @@
+---
+id: DS-001
+title: Git is source of truth for tokens
+severity: MUST
+status: active
+priority: P1
+domain: design-system
+source:
+  - DTCG
+applies_to:
+  - tokens
+success_criteria:
+  []
+requirement: >
+  Token definitions MUST live in version control. Penpot imports/exports — it does not replace Git.
+validation:
+  automated: true
+  manual: true
+exceptions: documented-only
+---
+
+# DS-001 — Git is source of truth for tokens
+
+**Requirement:** Token definitions MUST live in version control. Penpot imports/exports — it does not replace Git.
+
+**Bad:** Colors only exist inside a closed design file.
+
+**Good:** tokens/*.json in repo; Penpot synced from them.
+
+## Validation
+
+- Automated checks / lint / a11y tooling where applicable
+- Design or engineering review
+
+## Lifecycle
+
+- Status: `active`
+- Priority: `P1`
+- Exceptions: `documented-only`

package/rules/design-system/DS-002.md

@@ -0,0 +1,40 @@
+---
+id: DS-002
+title: Semantic tokens in components
+severity: SHOULD
+status: active
+priority: P2
+domain: design-system
+source:
+  - Carbon
+  - DTCG
+applies_to:
+  - tokens
+  - components
+success_criteria:
+  []
+requirement: >
+  App components SHOULD reference semantic tokens, not primitives.
+validation:
+  automated: false
+  manual: true
+exceptions: documented-only
+---
+
+# DS-002 — Semantic tokens in components
+
+**Requirement:** App components SHOULD reference semantic tokens, not primitives.
+
+**Bad:** color.blue.600 in Button.
+
+**Good:** color.primary / button.primary.bg.
+
+## Validation
+
+- Design or engineering review
+
+## Lifecycle
+
+- Status: `active`
+- Priority: `P2`
+- Exceptions: `documented-only`

package/rules/design-system/DS-003.md

@@ -0,0 +1,38 @@
+---
+id: DS-003
+title: Breaking token changes versioned
+severity: MUST
+status: active
+priority: P1
+domain: design-system
+source:
+  - SemVer
+applies_to:
+  - tokens
+success_criteria:
+  []
+requirement: >
+  Breaking token renames/removals MUST bump major (or documented migration) and CHANGELOG.
+validation:
+  automated: false
+  manual: true
+exceptions: documented-only
+---
+
+# DS-003 — Breaking token changes versioned
+
+**Requirement:** Breaking token renames/removals MUST bump major (or documented migration) and CHANGELOG.
+
+**Bad:** Silent rename of color.primary in place.
+
+**Good:** Major bump + migration note + dual-write window if needed.
+
+## Validation
+
+- Design or engineering review
+
+## Lifecycle
+
+- Status: `active`
+- Priority: `P1`
+- Exceptions: `documented-only`

package/rules/devops/OPS-001.md

@@ -0,0 +1,43 @@
+---
+id: OPS-001
+title: CI runs on every pull request with required gates
+severity: MUST
+status: active
+domain: devops
+priority: P0
+source:
+  - devia
+applies_to:
+  - repository
+success_criteria:
+  []
+requirement: >
+  Lint, typecheck, tests, dependency audit, secret scan and `devia check` MUST run on every pull request, and the critical ones MUST be required checks that block the merge.
+validation:
+  automated: true
+  manual: false
+exceptions: none
+---
+
+# OPS-001 — CI runs on every pull request with required gates
+
+**Requirement:** Lint, typecheck, tests, dependency audit, secret scan and `devia check` MUST run on every pull request, and the critical ones MUST be required checks that block the merge.
+
+**Bad:** A workflow that exists but is not required, so a red build merges.
+
+**Good:** Branch protection lists the gates; a failure blocks the merge.
+
+## Validation
+
+- Workflow file present
+- Checks marked required in branch protection
+
+## Lifecycle
+
+- Status: `active`
+- Priority: `P0`
+- Exceptions: `none`
+
+## See also
+
+- [app-ci.yml](../../templates/github/workflows/app-ci.yml)

package/rules/devops/OPS-002.md

@@ -0,0 +1,39 @@
+---
+id: OPS-002
+title: No direct pushes to the default branch
+severity: MUST
+status: active
+domain: devops
+priority: P0
+source:
+  - devia
+applies_to:
+  - repository
+success_criteria:
+  []
+requirement: >
+  Work MUST reach the default branch through a pull request from a branch. Agents MUST NOT commit to the default branch, force-push a shared branch, or rewrite published history.
+validation:
+  automated: true
+  manual: false
+exceptions: none
+---
+
+# OPS-002 — No direct pushes to the default branch
+
+**Requirement:** Work MUST reach the default branch through a pull request from a branch. Agents MUST NOT commit to the default branch, force-push a shared branch, or rewrite published history.
+
+**Bad:** An agent commits straight to `main` because the change 'is small'.
+
+**Good:** `feat/invoice-currency` → pull request → review → merge.
+
+## Validation
+
+- Branch protection enabled
+- The change is on a branch
+
+## Lifecycle
+
+- Status: `active`
+- Priority: `P0`
+- Exceptions: `none`

package/rules/devops/OPS-003.md

@@ -0,0 +1,38 @@
+---
+id: OPS-003
+title: Never bypass a hook or a check
+severity: MUST NOT
+status: active
+domain: devops
+priority: P0
+source:
+  - devia
+applies_to:
+  - repository
+success_criteria:
+  []
+requirement: >
+  `--no-verify`, disabled hooks, `[skip ci]` on a gated change, and locally silenced linters are forbidden. A hook that blocks is either right, or a bug to fix in the open.
+validation:
+  automated: true
+  manual: true
+exceptions: none
+---
+
+# OPS-003 — Never bypass a hook or a check
+
+**Requirement:** `--no-verify`, disabled hooks, `[skip ci]` on a gated change, and locally silenced linters are forbidden. A hook that blocks is either right, or a bug to fix in the open.
+
+**Bad:** `git commit --no-verify` because the formatter is slow.
+
+**Good:** The formatter runs; if it is wrong, the rule is fixed in the repository.
+
+## Validation
+
+- No bypass flag in the command history or scripts
+
+## Lifecycle
+
+- Status: `active`
+- Priority: `P0`
+- Exceptions: `none`

package/rules/devops/OPS-004.md

@@ -0,0 +1,40 @@
+---
+id: OPS-004
+title: Builds are reproducible
+severity: MUST
+status: active
+domain: devops
+priority: P1
+source:
+  - SLSA
+applies_to:
+  - repository
+  - devops
+success_criteria:
+  []
+requirement: >
+  The lockfile MUST be committed and installs MUST use it. Container base images MUST be pinned by digest or an immutable tag. A build MUST NOT depend on a floating latest.
+validation:
+  automated: true
+  manual: true
+exceptions: documented-only
+---
+
+# OPS-004 — Builds are reproducible
+
+**Requirement:** The lockfile MUST be committed and installs MUST use it. Container base images MUST be pinned by digest or an immutable tag. A build MUST NOT depend on a floating latest.
+
+**Bad:** `FROM node:latest` and an install that resolves new versions on every run.
+
+**Good:** `npm ci` against the committed lockfile; a base image pinned by digest.
+
+## Validation
+
+- Lockfile in the diff when the manifest changed
+- No floating image tags
+
+## Lifecycle
+
+- Status: `active`
+- Priority: `P1`
+- Exceptions: `documented-only`

package/rules/devops/OPS-005.md

@@ -0,0 +1,43 @@
+---
+id: OPS-005
+title: There is a rollback path and it has been used
+severity: MUST
+status: active
+domain: devops
+priority: P1
+source:
+  - devia
+applies_to:
+  - devops
+success_criteria:
+  []
+requirement: >
+  Every deployable MUST have a documented way back to the previous good state, including what happens to migrations, and it MUST have been exercised at least once.
+validation:
+  automated: false
+  manual: true
+exceptions: documented-only
+---
+
+# OPS-005 — There is a rollback path and it has been used
+
+**Requirement:** Every deployable MUST have a documented way back to the previous good state, including what happens to migrations, and it MUST have been exercised at least once.
+
+**Bad:** 'We would just redeploy the old commit' — never attempted, and the migration is irreversible.
+
+**Good:** A documented rollback, an expand-then-contract migration strategy, and a rehearsal on record.
+
+## Validation
+
+- Rollback documented
+- Rehearsal recorded with a date
+
+## Lifecycle
+
+- Status: `active`
+- Priority: `P1`
+- Exceptions: `documented-only`
+
+## See also
+
+- [ROLLBACK.md](../../standard/engineering/devops/ROLLBACK.md)

package/rules/devops/OPS-006.md

@@ -0,0 +1,38 @@
+---
+id: OPS-006
+title: Staging behaves like production
+severity: SHOULD
+status: active
+domain: devops
+priority: P2
+source:
+  - devia
+applies_to:
+  - devops
+success_criteria:
+  []
+requirement: >
+  The pre-production environment SHOULD run the same build artifact, the same migrations and the same configuration shape as production, with its own data and credentials.
+validation:
+  automated: false
+  manual: true
+exceptions: documented-only
+---
+
+# OPS-006 — Staging behaves like production
+
+**Requirement:** The pre-production environment SHOULD run the same build artifact, the same migrations and the same configuration shape as production, with its own data and credentials.
+
+**Bad:** Staging runs a different Node version and skips the migration step.
+
+**Good:** Same image, same pipeline, different secrets and data.
+
+## Validation
+
+- Diff the environment configuration
+
+## Lifecycle
+
+- Status: `active`
+- Priority: `P2`
+- Exceptions: `documented-only`

package/rules/devops/OPS-007.md

@@ -0,0 +1,40 @@
+---
+id: OPS-007
+title: Production state is never mutated by hand
+severity: MUST
+status: active
+domain: devops
+priority: P0
+source:
+  - devia
+applies_to:
+  - devops
+  - database
+success_criteria:
+  []
+requirement: >
+  Production data and schema MUST be changed through reviewed, repeatable, logged mechanisms — a migration, a scripted job, an admin action that writes an audit row — never by an ad-hoc console command.
+validation:
+  automated: false
+  manual: true
+exceptions: none
+---
+
+# OPS-007 — Production state is never mutated by hand
+
+**Requirement:** Production data and schema MUST be changed through reviewed, repeatable, logged mechanisms — a migration, a scripted job, an admin action that writes an audit row — never by an ad-hoc console command.
+
+**Bad:** A quick `UPDATE` in a production console to fix one customer.
+
+**Good:** A scripted, reviewed fix that logs what it changed and can run again safely.
+
+## Validation
+
+- The change is a committed artifact
+- The action is auditable
+
+## Lifecycle
+
+- Status: `active`
+- Priority: `P0`
+- Exceptions: `none`

package/rules/interaction/INT-001.md

@@ -0,0 +1,39 @@
+---
+id: INT-001
+title: Touch primary targets
+severity: MUST
+status: active
+priority: P1
+domain: interaction
+source:
+  - WCAG-2.2
+applies_to:
+  - touch
+  - touchscreen
+success_criteria:
+  []
+requirement: >
+  On touch-primary surfaces, primary actions MUST meet comfortable touch sizing (prefer 44×44).
+validation:
+  automated: false
+  manual: true
+exceptions: documented-only
+---
+
+# INT-001 — Touch primary targets
+
+**Requirement:** On touch-primary surfaces, primary actions MUST meet comfortable touch sizing (prefer 44×44).
+
+**Bad:** Desktop-dense toolbar on POS touchscreen.
+
+**Good:** Large hit targets, spacing, no hover-only.
+
+## Validation
+
+- Design or engineering review
+
+## Lifecycle
+
+- Status: `active`
+- Priority: `P1`
+- Exceptions: `documented-only`

package/rules/interaction/INT-002.md

@@ -0,0 +1,39 @@
+---
+id: INT-002
+title: Keyboard parity for pointer features
+severity: MUST
+status: active
+priority: P1
+domain: interaction
+source:
+  - WCAG-2.2
+applies_to:
+  - keyboard
+  - mouse
+success_criteria:
+  - "2.1.1"
+requirement: >
+  Pointer-driven features MUST have a keyboard equivalent when required by WCAG.
+validation:
+  automated: false
+  manual: true
+exceptions: documented-only
+---
+
+# INT-002 — Keyboard parity for pointer features
+
+**Requirement:** Pointer-driven features MUST have a keyboard equivalent when required by WCAG.
+
+**Bad:** Context menu mouse-only.
+
+**Good:** Keyboard menu button + arrows.
+
+## Validation
+
+- Design or engineering review
+
+## Lifecycle
+
+- Status: `active`
+- Priority: `P1`
+- Exceptions: `documented-only`

package/rules/localization/I18N-001.md

@@ -0,0 +1,38 @@
+---
+id: I18N-001
+title: No concatenated sentences
+severity: MUST
+status: active
+priority: P1
+domain: localization
+source:
+  - i18n-best-practice
+applies_to:
+  - content
+success_criteria:
+  []
+requirement: >
+  UI strings MUST NOT be built by concatenating translated fragments in ways that break grammar.
+validation:
+  automated: false
+  manual: true
+exceptions: documented-only
+---
+
+# I18N-001 — No concatenated sentences
+
+**Requirement:** UI strings MUST NOT be built by concatenating translated fragments in ways that break grammar.
+
+**Bad:** 'Delete ' + name + ' now' across locales.
+
+**Good:** Single message with placeholder: Delete {name}?
+
+## Validation
+
+- Design or engineering review
+
+## Lifecycle
+
+- Status: `active`
+- Priority: `P1`
+- Exceptions: `documented-only`

package/rules/localization/I18N-002.md

@@ -0,0 +1,40 @@
+---
+id: I18N-002
+title: Text expansion safe layouts
+severity: SHOULD
+status: active
+priority: P2
+domain: localization
+source:
+  - Material
+  - i18n-best-practice
+applies_to:
+  - layout
+  - buttons
+success_criteria:
+  []
+requirement: >
+  Layouts SHOULD tolerate ~30–40% text expansion without truncation of critical labels.
+validation:
+  automated: false
+  manual: true
+exceptions: documented-only
+---
+
+# I18N-002 — Text expansion safe layouts
+
+**Requirement:** Layouts SHOULD tolerate ~30–40% text expansion without truncation of critical labels.
+
+**Bad:** Fixed-width button cutting German labels.
+
+**Good:** Flexible buttons; allow wrap where needed.
+
+## Validation
+
+- Design or engineering review
+
+## Lifecycle
+
+- Status: `active`
+- Priority: `P2`
+- Exceptions: `documented-only`

package/rules/localization/I18N-003.md

@@ -0,0 +1,39 @@
+---
+id: I18N-003
+title: RTL readiness for mirrored UI
+severity: SHOULD
+status: active
+priority: P2
+domain: localization
+source:
+  - WCAG-2.2
+  - Material
+applies_to:
+  - layout
+success_criteria:
+  []
+requirement: >
+  If RTL locales are in scope, layout MUST mirror logically (start/end, not left/right hardcoding).
+validation:
+  automated: false
+  manual: true
+exceptions: documented-only
+---
+
+# I18N-003 — RTL readiness for mirrored UI
+
+**Requirement:** If RTL locales are in scope, layout MUST mirror logically (start/end, not left/right hardcoding).
+
+**Bad:** margin-left everywhere; broken RTL.
+
+**Good:** Logical properties / start-end tokens.
+
+## Validation
+
+- Design or engineering review
+
+## Lifecycle
+
+- Status: `active`
+- Priority: `P2`
+- Exceptions: `documented-only`