@schneiderjoseph/devia 0.1.0

package/standard/design/ux/information-architecture.md

@@ -0,0 +1,6 @@
+# Information Architecture
+
+Canonical rules:
+
+- [UX-003](../../../rules/ux/UX-003.md)
+- [UX-004](../../../rules/ux/UX-004.md)

package/standard/design/ux/navigation.md

@@ -0,0 +1,6 @@
+# Navigation
+
+Canonical rules:
+
+- [UX-005](../../../rules/ux/UX-005.md)
+- [UX-006](../../../rules/ux/UX-006.md)

package/standard/design/ux/usability.md

@@ -0,0 +1,6 @@
+# Usability
+
+Canonical rules:
+
+- [UX-001](../../../rules/ux/UX-001.md)
+- [UX-002](../../../rules/ux/UX-002.md)

package/standard/engineering/README.md

@@ -0,0 +1,29 @@
+# Engineering standard
+
+Deep policy by domain. Pair every change with the matching rules and the checklist under
+[`../../checklists/engineering/`](../../checklists/README.md).
+
+Spine: [`../../PRINCIPLES.md`](../../PRINCIPLES.md) · [`../../LEVELS.md`](../../LEVELS.md) ·
+[`../../MATURITY.md`](../../MATURITY.md) · `devia check`
+
+| Domain | Pages | Rules |
+|---|---|---|
+| Architecture | [`architecture/`](architecture/ARCHITECTURE.md), [`ADR.md`](architecture/ADR.md), [`THREAT_MODEL.md`](architecture/THREAT_MODEL.md) | `ARC-*` |
+| Security | [`security/`](security/SECURITY.md), [`AUTHENTICATION.md`](security/AUTHENTICATION.md), [`AUTHORIZATION.md`](security/AUTHORIZATION.md), [`SECRETS.md`](security/SECRETS.md), [`API_SECURITY.md`](security/API_SECURITY.md), [`DATA_SECURITY.md`](security/DATA_SECURITY.md) | `SEC-*` |
+| ASVS mapping | [`security/OWASP_ASVS.md`](security/OWASP_ASVS.md), [`security/ASVS_REGISTRY.md`](security/ASVS_REGISTRY.md), [`security/ASVS_5.0/`](security/ASVS_5.0/V1_ARCHITECTURE.md) | `SEC-*` |
+| Database | [`database/DATABASE.md`](database/DATABASE.md), [`MIGRATIONS.md`](database/MIGRATIONS.md), [`BACKUPS.md`](database/BACKUPS.md) | `DB-*` |
+| API / backend | [`backend/API.md`](backend/API.md), [`ERROR_HANDLING.md`](backend/ERROR_HANDLING.md), [`LOGGING.md`](backend/LOGGING.md), [`BACKGROUND_JOBS.md`](backend/BACKGROUND_JOBS.md) | `API-*` |
+| Testing | [`testing/TESTING.md`](testing/TESTING.md) | `TST-*` |
+| DevOps | [`devops/CI_CD.md`](devops/CI_CD.md), [`BRANCH_PROTECTION.md`](devops/BRANCH_PROTECTION.md), [`DEPLOYMENT.md`](devops/DEPLOYMENT.md), [`ENVIRONMENTS.md`](devops/ENVIRONMENTS.md), [`DOCKER.md`](devops/DOCKER.md), [`RELEASE.md`](devops/RELEASE.md), [`ROLLBACK.md`](devops/ROLLBACK.md) | `OPS-*` |
+| Observability | [`observability/MONITORING.md`](observability/MONITORING.md), [`ALERTING.md`](observability/ALERTING.md), [`INCIDENTS.md`](observability/INCIDENTS.md) | `OBS-*` |
+| Performance | [`performance/PERFORMANCE.md`](performance/PERFORMANCE.md) | — |
+| Privacy | [`compliance/PRIVACY.md`](compliance/PRIVACY.md), [`DATA_RETENTION.md`](compliance/DATA_RETENTION.md) | `PRIV-*` |
+| Payments | [`payments/PAYMENTS.md`](payments/PAYMENTS.md) | `SEC-007`, `API-004` |
+| AI features | [`ai/AI_SECURITY.md`](ai/AI_SECURITY.md), [`PROMPT_SECURITY.md`](ai/PROMPT_SECURITY.md) | `AI-*` |
+| Frontend | [`frontend/FRONTEND.md`](frontend/FRONTEND.md), [`ACCESSIBILITY.md`](frontend/ACCESSIBILITY.md), [`UX.md`](frontend/UX.md), [`DESIGN_SYSTEM.md`](frontend/DESIGN_SYSTEM.md) | design rules — see [`../design/README.md`](../design/README.md) |
+
+Sources: [`REFERENCES.md`](REFERENCES.md).
+
+Frontend pages here cover the engineering side of the interface — bundles, state, XSS, storage.
+The interface itself is governed by [`../design/README.md`](../design/README.md); a UI that ships
+without its design rules is not done, however clean the code is.

package/standard/engineering/REFERENCES.md

@@ -0,0 +1,42 @@
+# Reference standards
+
+This standard is intentionally built on recognized sources. Prefer the primary documents when details matter.
+
+## Security
+
+- [OWASP ASVS](https://owasp.org/www-project-application-security-verification-standard/) — verifiable application security requirements
+- [OWASP Top 10](https://owasp.org/www-project-top-ten/) — common risk classes
+- [OWASP API Security Top 10](https://owasp.org/www-project-api-security/)
+- [OWASP Cheat Sheet Series](https://cheatsheetseries.owasp.org/)
+
+## Architecture & delivery
+
+- [12-Factor App](https://12factor.net/)
+- AWS Well-Architected (cloud design trade-offs)
+- SOLID principles (when they reduce complexity, not as dogma)
+
+## Web & accessibility
+
+- [WCAG](https://www.w3.org/WAI/standards-guidelines/wcag/)
+- [WAI-ARIA APG](https://www.w3.org/WAI/ARIA/apg/)
+- HTTP semantics / status codes
+- [OpenAPI Specification](https://www.openapis.org/)
+- UX/UI operational rules: [`../design/REFERENCES.md`](../design/REFERENCES.md) (WCAG, NN/g, GOV.UK, Carbon and the rest)
+
+## Supply chain & DevOps
+
+- OpenSSF / secure software practices
+- SBOM generation for releases when appropriate
+- Container minimal base images + non-root + image scanning
+
+## Data
+
+- PostgreSQL operational best practices
+- Encryption in transit / at rest as required by threat model
+- Backup **and restore testing**
+
+## Quality
+
+- Semantic Versioning
+- Conventional Commits (optional but useful)
+- Automated testing pyramid + critical-path E2E

package/standard/engineering/ai/AI_SECURITY.md

@@ -0,0 +1,15 @@
+# AI feature security
+
+## P0
+
+1. Never ship raw model output to users without validation/encoding
+2. Treat model output as untrusted (XSS, data exfiltration, tool abuse)
+3. Protect against prompt injection when tools/browsing/files are connected
+4. Provider keys stay on the server; rate-limit user-triggered generations
+
+## P1
+
+1. Human approval for high-impact automated actions
+2. Audit logs for tool calls that mutate data
+3. Cost/token controls and model routing for expensive tasks
+4. Evaluation sets for contractual behaviors

package/standard/engineering/ai/PROMPT_SECURITY.md

@@ -0,0 +1,6 @@
+# Prompt security
+
+- Separate trusted system instructions from untrusted user/content input
+- Don’t exfiltrate secrets into prompts/logs
+- For tool-using agents: least privilege tools, confirm destructive actions
+- Version prompts that affect production behavior

package/standard/engineering/architecture/ADR.md

@@ -0,0 +1,11 @@
+# Architecture Decision Records
+
+Use ADRs for decisions that are expensive to reverse: auth provider, multi-tenancy model, event bus, payment provider, primary database, public API shape.
+
+Template: [`templates/ADR.md`](../../../templates/docs/ADR.md)
+
+Rules:
+
+- One decision per ADR
+- Include context, options, decision, consequences
+- Never silently reverse an ADR in code — supersede it with a new ADR

package/standard/engineering/architecture/ARCHITECTURE.md

@@ -0,0 +1,25 @@
+# Architecture
+
+## P0
+
+1. Document what you are building, for whom, and which data is sensitive **before** large features ship.
+2. Keep UI, API/application services, and persistence boundaries clear — business rules do not live only in React components.
+3. Identify critical components and single points of failure; plan recovery for them.
+4. Dependency direction is inward toward domain rules (UI/infrastructure depend on domain — not the reverse).
+
+## P1
+
+1. Record non-trivial decisions as ADRs ([`templates/ADR.md`](../../../templates/docs/ADR.md)).
+2. Maintain a simple architecture diagram and data-flow sketch in the app repo.
+3. Define scalability and availability assumptions explicitly (even if “single region, vertical scale for now”).
+
+## Detect
+
+- Business rules duplicated across frontend and backend with divergent behavior
+- Direct DB access from UI code
+- No threat model for auth, payments, or PII
+
+## Verify
+
+- A new engineer can explain the system from `ARCHITECTURE.md` alone
+- Sensitive data flows are listed end-to-end

package/standard/engineering/architecture/PRINCIPLES.md

@@ -0,0 +1,17 @@
+# Architecture principles
+
+See root [`PRINCIPLES.md`](../../../PRINCIPLES.md) for the full set (complexity earned, dependency liability).
+
+## Architecture-specific
+
+```text
+Simple > Clever
+Explicit > Implicit
+Modular > Spaghetti
+Typed > Untyped (when the stack allows)
+```
+
+- Prefer a modular monolith until scale or team boundaries **force** services.
+- Prefer Postgres features you already run over a new data store.
+- Prefer boring, operable patterns over novel ones.
+- Every irreversible choice gets an ADR ([`ADR.md`](ADR.md)).

package/standard/engineering/architecture/THREAT_MODEL.md

@@ -0,0 +1,14 @@
+# Threat model (lightweight)
+
+For every app, answer:
+
+1. What assets matter (credentials, PII, payments, admin actions)?
+2. Who are the actors (anon, user, admin, attacker, insider)?
+3. What are the trust boundaries (browser, API, DB, third parties)?
+4. What happens on abuse (credential stuffing, IDOR, webhook forgery, prompt injection)?
+
+Minimum outputs:
+
+- List of assets + impact if lost
+- Top abuse cases mapped to controls in `docs/security/`
+- Residual risks accepted by the owner

package/standard/engineering/backend/API.md

@@ -0,0 +1,29 @@
+# API standard
+
+## Request pipeline (conceptual)
+
+```text
+Request → AuthN → AuthZ → Validation → Idempotency → Business rules
+        → Transaction → Persistence → Audit log → Response
+```
+
+## P0
+
+1. Explicit contract per endpoint (accept / return / error / auth)
+2. Validate inputs before business logic
+3. Re-check permissions and ownership on mutating operations
+4. Correct HTTP status codes; stable error codes for clients
+5. No stack traces or SQL text in production responses
+
+## P1
+
+1. Version public APIs (`/v1`, …) + changelog
+2. Pagination / filtering conventions documented
+3. Timeouts on outbound calls; bounded retries
+4. OpenAPI (or equivalent) kept current for public/partner APIs
+5. Request IDs / correlation IDs
+
+## Webhooks
+
+- Verify signatures
+- Handle duplicate deliveries idempotently

package/standard/engineering/backend/BACKGROUND_JOBS.md

@@ -0,0 +1,12 @@
+# Background jobs
+
+## P0
+
+1. Heavy work (email, LLM, webhooks fan-out, reports) runs out of band — not on the request thread when latency matters
+2. Jobs are idempotent where retries exist
+3. Failed jobs are visible (log + alert on spikes)
+
+## P1
+
+1. Dead-letter / retry limits
+2. Job payloads exclude secrets when possible

package/standard/engineering/backend/ERROR_HANDLING.md

@@ -0,0 +1,26 @@
+# Error handling
+
+## Client-safe error shape (example)
+
+```json
+{
+  "error": {
+    "code": "ORDER_NOT_FOUND",
+    "message": "Order not found",
+    "requestId": "req_123"
+  }
+}
+```
+
+## Never expose in production
+
+- Stack traces
+- SQL queries
+- Internal paths
+- Secrets / env values
+- Raw third-party error dumps
+
+## P0
+
+1. Centralize mapping: detailed logs internally, safe messages externally
+2. Bound retries; prefer idempotent handlers

package/standard/engineering/backend/LOGGING.md

@@ -0,0 +1,12 @@
+# Logging
+
+## P0
+
+1. Structured logs with request/correlation ids
+2. Authz failures and payment events are auditable
+3. No secrets or unnecessary PII in logs
+
+## P1
+
+1. Log levels sane in production (`info`/`warn`/`error`)
+2. Retention aligned with privacy policy

package/standard/engineering/compliance/DATA_RETENTION.md

@@ -0,0 +1,10 @@
+# Data retention
+
+Document:
+
+- What categories of data you store
+- How long each category is kept
+- When soft-delete becomes hard-delete
+- What remains in backups and for how long
+
+Deletion requests must account for backups and derived data (search indexes, logs, warehouses).

package/standard/engineering/compliance/PRIVACY.md

@@ -0,0 +1,11 @@
+# Privacy
+
+Apply what your product and jurisdiction require (GDPR and similar). This is not legal advice.
+
+## Engineering P0/P1
+
+1. Data minimization — collect only what you need
+2. Deletion/export pipelines that actually remove orphaned PII
+3. Retention policy documented and enforced
+4. Tenant/user isolation for private data
+5. Consent/cookie flows when applicable to your UI surface

package/standard/engineering/database/BACKUPS.md

@@ -0,0 +1,19 @@
+# Backups & restore
+
+> A backup that has never been restored successfully is not a backup.
+
+## P0
+
+1. Automated database backups
+2. Defined retention
+3. Restore procedure documented
+4. Restore tested on a schedule (and after major version upgrades)
+
+## P1
+
+1. Off-site / separate-account storage when risk warrants
+2. Backup encryption
+3. File/object storage backups if user content exists
+4. Explicit RPO / RTO targets (example: RPO 15m, RTO 1h)
+
+See [`checklists/disaster-recovery.md`](../../../checklists/engineering/disaster-recovery.md).

package/standard/engineering/database/DATABASE.md

@@ -0,0 +1,30 @@
+# Database
+
+Treat the database as a critical production component — not a dumping ground.
+
+## P0
+
+1. Versioned migrations only — **no manual production schema edits**
+2. Primary keys, foreign keys, and essential constraints exist
+3. Tenant/user ownership enforced in queries (or RLS)
+4. Automated backups exist **and restore has been tested**
+5. Connection pooling configured before “scale the DB” theater
+
+## P1
+
+1. Indexes justified by real query paths; eliminate obvious N+1
+2. Transactions around multi-step critical writes
+3. Pagination on large lists
+4. Expand/contract compatible migrations for breaking changes
+
+## Detect
+
+- Schema drift between environments
+- Missing FKs “for speed”
+- Untested backups
+
+## Verify
+
+- Migrate from empty DB to head successfully
+- Restore latest backup into staging and boot the app
+- Cross-tenant read test fails closed

package/standard/engineering/database/MIGRATIONS.md

@@ -0,0 +1,12 @@
+# Migrations
+
+## Rules
+
+- Every schema change is a migration committed to git
+- Migrations are reviewed like code
+- Avoid destructive changes without a expand → backfill → contract plan
+- Seed data is separate from migrations
+
+## Agent rule
+
+If you need a new column/table/index: create a migration. Do not “just alter prod”.

package/standard/engineering/devops/BRANCH_PROTECTION.md

@@ -0,0 +1,17 @@
+# Branch protection (enforcement checklist)
+
+On `main` (GitHub → Settings → Branches):
+
+- [ ] Require a pull request before merging
+- [ ] Require status checks to pass
+- [ ] Require branches to be up to date (recommended)
+- [ ] Required checks include at least:
+  - [ ] Lint · Typecheck · Unit
+  - [ ] Dependency audit
+  - [ ] Secret scan
+  - [ ] Production check (P0) — when adopted
+  - [ ] E2E / smoke — for release-critical repos
+- [ ] Restrict who can push / bypass (no casual admin bypass)
+- [ ] Do not allow bypassing without break-glass policy
+
+Without required checks, Level 3 does not exist — only theater.

package/standard/engineering/devops/CI_CD.md

@@ -0,0 +1,48 @@
+# CI/CD — Level 3 Enforcement
+
+## Goal
+
+GitHub must be able to say **NO** to a PR that violates a critical rule.
+
+```text
+PR #N
+├── Lint / Typecheck / Unit     ✅/❌
+├── Integration                 ✅/❌
+├── Dependency audit            ✅/❌
+├── Secret scan                 ✅/❌
+├── Production check (P0)       ✅/❌
+├── E2E / smoke                 ✅/❌
+└── MERGE BLOCKED on required ❌
+```
+
+## Recommended PR pipeline
+
+```text
+Format → Lint → Typecheck → Unit → Integration → Dependency audit
+ → Secret scan → SAST (as available) → Build → (Docker build/scan)
+ → Staging deploy → Smoke/E2E → Production (protected)
+```
+
+## P0
+
+1. `main` protected: PR + **required** status checks
+2. CI must pass before merge
+3. No laptop-copy deploy as the normal path
+4. Secret scan + dependency audit required
+5. `production-check` required once adopted (FAIL blocks)
+
+## P1
+
+1. Separate staging and production
+2. Rollback strategy documented and exercised
+3. Migrations gated; expand/contract for destructive changes
+4. SAST / container scan as available
+
+## Adopting this standard
+
+1. Copy [`templates/github/workflows/app-ci.yml`](../../../templates/github/workflows/app-ci.yml) → `.github/workflows/ci.yml`
+2. Copy `scripts/production-check.mjs` (and optional config)
+3. In GitHub → Settings → Branches → require the job names you care about
+4. Map maturity target in `MATURITY.md` terms (Silver vs Gold)
+
+Critical control failures **block deployment**, not just “file a ticket”.

package/standard/engineering/devops/DEPLOYMENT.md

@@ -0,0 +1,12 @@
+# Deployment
+
+## P0
+
+1. Health/readiness checks for services that take traffic
+2. Documented deploy path
+3. Ability to roll back (or feature-flag disable) quickly
+
+## P1
+
+1. Prefer progressive delivery (flags/canaries) for risky changes
+2. Announce maintenance when downtime is unavoidable

package/standard/engineering/devops/DOCKER.md

@@ -0,0 +1,9 @@
+# Docker
+
+## P1 baseline
+
+1. Minimal base images
+2. Non-root user
+3. No secrets baked into images
+4. Image scanning in CI for release candidates
+5. Resource limits in orchestration when applicable

package/standard/engineering/devops/ENVIRONMENTS.md

@@ -0,0 +1,12 @@
+# Environments
+
+## P0
+
+1. Distinct local / staging / production configurations
+2. Separate secrets and data per environment
+3. Production data does not casually load into personal laptops
+
+## P1
+
+1. Document required env vars (`.env.example`)
+2. Infra/config changes reviewed like code (IaC preferred)

package/standard/engineering/devops/RELEASE.md

@@ -0,0 +1,6 @@
+# Release management
+
+- Semantic versioning for published packages/APIs when consumers exist
+- Changelog entries for user-facing and breaking changes
+- Release tags on production deploys
+- Use [`checklists/release.md`](../../../checklists/engineering/release.md) and [`checklists/production.md`](../../../checklists/engineering/production.md)

package/standard/engineering/devops/ROLLBACK.md

@@ -0,0 +1,9 @@
+# Rollback
+
+Before each production deploy, know:
+
+1. How to revert the app version
+2. Whether DB migrations are backward-compatible
+3. Who is on-call during the deploy window
+
+If you cannot answer these, you are not ready to deploy.

package/standard/engineering/frontend/ACCESSIBILITY.md

@@ -0,0 +1,16 @@
+# Accessibility
+
+Reference: **WCAG** (aim for AA on primary flows unless product requirements say otherwise).
+
+## P0
+
+1. Primary flows completable by keyboard alone
+2. Interactive controls have accessible names
+3. Meaningful images have appropriate alt text
+
+## P1
+
+1. Contrast meets AA for text and essential UI
+2. Focus management for dialogs/drawers
+3. Do not convey state by color alone
+4. Automated a11y checks on critical pages in CI when feasible

package/standard/engineering/frontend/DESIGN_SYSTEM.md

@@ -0,0 +1,10 @@
+# Design system
+
+If the product has more than a handful of screens:
+
+- Shared typography, color, spacing tokens
+- Reusable components (button, input, table, modal, toast)
+- Document states (default/hover/disabled/error)
+- Prefer consistency over one-off styling
+
+Skip heavy design-system theater for tiny prototypes — introduce structure when duplication hurts.

package/standard/engineering/frontend/FRONTEND.md

@@ -0,0 +1,17 @@
+# Frontend
+
+## P0
+
+1. Loading / empty / error / success states for critical flows
+2. Forms validate before submit; server remains source of truth
+3. No secrets in the client; treat XSS as a first-class risk
+4. Destructive actions require confirmation
+
+## P1
+
+1. Responsive layout across mobile/tablet/desktop targets you claim to support
+2. Error boundaries for resilient UI shells
+3. Performance basics: code splitting, image optimization where relevant
+4. Consistent navigation and feedback (toasts/inline errors)
+
+Security note: frontend checks are UX. Authorization is enforced on the API.

package/standard/engineering/frontend/UX.md

@@ -0,0 +1,15 @@
+# UX baseline
+
+Full MUST/SHOULD rules live in the design standard ([`../../design/ux/`](../../design/ux/heuristics.md), [`checklists/design/ux-review.md`](../../../checklists/design/ux-review.md)).
+
+Minimum here:
+
+- Clear primary action per view
+- Understandable error messages (what happened + what to do)
+- Confirm irreversible actions
+- Don’t trap users in dead ends without recovery
+- Onboarding only as complex as the product requires
+- Empty / loading / error states for data views
+- Tokens + system components over one-off styling
+
+Agents: follow [`AGENTS.md`](../../../AGENTS.md) and the design rules for UI work.

package/standard/engineering/observability/ALERTING.md

@@ -0,0 +1,11 @@
+# Alerting
+
+Alert on symptoms humans must act on:
+
+- API error rate above threshold
+- Database unavailable
+- Disk > 85%
+- Payment/webhook failure spikes
+- Auth abuse patterns (credential stuffing)
+
+Alerts without owners or runbooks become noise — attach a next step.

package/standard/engineering/observability/INCIDENTS.md

@@ -0,0 +1,10 @@
+# Incidents
+
+## Minimum process
+
+1. Detect
+2. Mitigate (rollback/flag/scale/patch)
+3. Communicate (status page or user messaging when impact is real)
+4. Write a short postmortem: timeline, cause, fix, follow-ups
+
+See [`checklists/incident.md`](../../../checklists/engineering/incident.md).

package/standard/engineering/observability/MONITORING.md

@@ -0,0 +1,17 @@
+# Monitoring & observability
+
+You must be able to answer:
+
+> What broke, why, since when, and how many users are affected?
+
+## P0
+
+1. Error tracking in production
+2. Customers are not your primary monitoring system
+3. Alerts on business-critical signals (e.g. checkout/payment success), not only CPU
+
+## P1
+
+1. Structured logs + metrics + (when needed) tracing
+2. Synthetic checks on critical journeys
+3. Dashboards for latency, error rate, saturation

package/standard/engineering/payments/PAYMENTS.md

@@ -0,0 +1,15 @@
+# Payments
+
+## P0
+
+1. Verify webhook signatures before granting entitlements
+2. Idempotent processing — duplicates must not double-charge or double-grant
+3. Never unlock paid features from client-only success callbacks
+4. Money math uses decimal-safe types — never float
+
+## P1
+
+1. Clear states: pending / succeeded / failed / refunded / canceled
+2. Failed payment retry + user messaging + grace period strategy
+3. Refund/dispute runbook before first real chargeback
+4. Reconciliation/audit trail

package/standard/engineering/performance/PERFORMANCE.md

@@ -0,0 +1,19 @@
+# Performance
+
+Define targets — even rough ones — or you cannot manage them.
+
+Example targets (adjust per product):
+
+```text
+API p95 < 500ms
+API p99 < 1s
+Critical DB queries < 100ms
+Error rate < 1%
+```
+
+## P0/P1 practices
+
+- Move heavy work to queues
+- Cache expensive reads deliberately
+- Profile before premature sharding
+- Load-test critical paths before marketing spikes