@schneiderjoseph/devia 0.1.0

package/standard/engineering/testing/TESTING.md

@@ -0,0 +1,27 @@
+# Testing
+
+## Pyramid
+
+```text
+        E2E (critical journeys)
+       /                    \
+  Integration (API/DB/auth)
+     /                        \
+Unit (domain rules, validators)
+```
+
+## P0
+
+1. Features that touch authz/payments/data isolation ship with tests in the same change
+2. CI runs tests on every PR; red builds do not merge
+3. Every production bug gets a regression test
+
+## P1
+
+1. Critical business journeys covered by E2E/smoke
+2. LLM features have frozen eval fixtures when output is contractual
+3. Load testing before expected traffic spikes
+
+## Rule
+
+Test business-critical paths — not only trivial pure functions.

package/templates/agents/AGENTS.md

@@ -0,0 +1,34 @@
+# AGENTS.md
+
+This repository uses **devia**: a standard plus a living project memory in `.devia/`.
+
+## Before any work
+
+1. Read [`.devia/AGENTS.md`](.devia/AGENTS.md) — the work contract for this repository
+2. Read [`.devia/10_NEVER_ALWAYS.md`](.devia/10_NEVER_ALWAYS.md) — what is already banned here
+3. Read [`.devia/00_OVERVIEW.md`](.devia/00_OVERVIEW.md) — what this project is
+4. Read the memory file for the surface you are touching — see
+   [`.devia/14_INDEX.md`](.devia/14_INDEX.md)
+
+If `.devia/` is missing, run `npx devia init` and fill `00_OVERVIEW.md` before writing code.
+
+## While working
+
+- Never invent endpoints, fields, config keys or business rules. Unknown means ask, or record it
+  in `.devia/11_GAPS.md`
+- Decided but not built goes in `.devia/12_DEBT.md`, even when you are not fixing it
+- Smallest change that satisfies the request
+- Never disable a test, bypass a hook, or weaken a rule to make a check pass
+
+## Before reporting
+
+```bash
+npx devia validate    # memory integrity
+npx devia check       # readiness gates
+```
+
+Update `.devia/` in the same change (see `.devia/impact-map.yaml`), then report what you changed
+**and what you did not verify**.
+
+Full standard: [`.devia/standard/AGENTS.md`](.devia/standard/AGENTS.md) ·
+rules by ID: [`.devia/standard/rules/README.md`](.devia/standard/rules/README.md)

package/templates/agents/CLAUDE.md

@@ -0,0 +1,33 @@
+# CLAUDE.md
+
+This repository runs on **devia**. The project memory lives in `.devia/` and is read before any
+work, updated with every change.
+
+## Start here, every session
+
+1. `.devia/AGENTS.md` — the work contract
+2. `.devia/10_NEVER_ALWAYS.md` — what this project has banned
+3. `.devia/00_OVERVIEW.md` — what this project is
+4. The memory file for the surface you are touching (`.devia/14_INDEX.md`)
+
+No `.devia/`? Run `npx devia init` and fill `00_OVERVIEW.md` before writing code.
+
+## Rules that override default behaviour
+
+- Never invent an endpoint, field, config key or business rule. Record the unknown in
+  `.devia/11_GAPS.md` or ask.
+- Decided but not built goes to `.devia/12_DEBT.md`. Never delete a line you did not discharge.
+- Smallest change that satisfies the request; no drive-by refactors.
+- Never skip a hook, disable a test, or weaken a rule to make a check pass.
+- Update `.devia/` in the same change (`.devia/impact-map.yaml` says which files).
+
+## Before you report
+
+```bash
+npx devia validate
+npx devia check
+```
+
+Report the checks that ran, the rule IDs involved, and what you did **not** verify.
+
+Full contract: `.devia/standard/AGENTS.md`. Rules by ID: `.devia/standard/rules/README.md`.

package/templates/agents/copilot-instructions.md

@@ -0,0 +1,15 @@
+# Copilot instructions
+
+This repository runs on devia. The project memory is `.devia/`.
+
+- Read `.devia/AGENTS.md`, `.devia/10_NEVER_ALWAYS.md` and `.devia/00_OVERVIEW.md` before
+  suggesting changes; read the memory file for the surface you are touching
+  (`.devia/14_INDEX.md`).
+- Do not invent endpoints, fields, config keys or business rules. Follow the contracts recorded
+  in `.devia/02_SURFACES.md` and `.devia/03_DATA_MODEL.md`.
+- Authorization is server-side; input is validated at the boundary; no secrets in source; schema
+  changes are versioned migrations.
+- UI changes need an accessible name, a keyboard path, visible focus, persistent labels, and
+  complete states — including empty, loading and error.
+- Suggest the matching `.devia/` update alongside the code change.
+- Never suggest disabling a test, skipping a hook, or loosening a check to make CI pass.

package/templates/agents/cursor.mdc

@@ -0,0 +1,27 @@
+---
+description: devia — read .devia memory before coding, update it in the same change
+alwaysApply: true
+---
+
+This repository runs on devia. `.devia/` is the project memory and it is not optional.
+
+1. Before the first edit, read `.devia/AGENTS.md`, `.devia/10_NEVER_ALWAYS.md`,
+   `.devia/00_OVERVIEW.md`, and the memory file for the surface you are touching
+   (`.devia/14_INDEX.md`). If `.devia/` does not exist, run `npx devia init` first (AGT-001,
+   AGT-002).
+2. Never invent an endpoint, field, config key or business rule. Unknown goes to
+   `.devia/11_GAPS.md` or to the human — never into the code as a quiet default (AGT-004,
+   MEM-001).
+3. Decided but not built goes in `.devia/12_DEBT.md`, even when you are not fixing it (MEM-002).
+   Never delete a registry line you did not discharge (MEM-011).
+4. Smallest change that satisfies the request (AGT-003). No opportunistic refactors.
+5. Never disable a test, bypass a hook, or weaken a rule or threshold to go green (TST-003,
+   OPS-003, AGT-011).
+6. Server-side authorization, validated input, no secrets, versioned migrations (SEC-001,
+   SEC-002, SEC-003, DB-001).
+7. Any UI change satisfies the design MUSTs: accessible name, keyboard path, visible focus,
+   persistent labels, complete states, never colour alone (A11Y-001, A11Y-004, A11Y-006, UX-007,
+   UI-004).
+8. Update `.devia/` in the same change, per `.devia/impact-map.yaml` (MEM-009).
+9. Cite rule IDs, and always report what you did **not** verify (AGT-006, AGT-007).
+10. Never claim done or production ready without naming the checks that ran (AGT-005).

package/templates/agents/windsurfrules.md

@@ -0,0 +1,17 @@
+# devia rules
+
+This repository runs on devia. `.devia/` is the project memory.
+
+1. Read `.devia/AGENTS.md`, `.devia/10_NEVER_ALWAYS.md`, `.devia/00_OVERVIEW.md` and the memory
+   file for the surface you are touching before editing anything. No `.devia/`? Run
+   `npx devia init` first.
+2. Never invent an endpoint, field, config key or business rule — record the unknown in
+   `.devia/11_GAPS.md` or ask.
+3. Decided but not built goes to `.devia/12_DEBT.md`; never delete a line you did not discharge.
+4. Smallest change that satisfies the request.
+5. Server-side authorization, validated input, no secrets, versioned migrations.
+6. UI: accessible name, keyboard path, visible focus, persistent labels, complete states, never
+   colour alone.
+7. Never disable a test, bypass a hook, or weaken a rule to go green.
+8. Update `.devia/` in the same change (`.devia/impact-map.yaml`).
+9. Report the checks you ran, the rule IDs, and what you did not verify.

package/templates/docs/ADR.md

@@ -0,0 +1,16 @@
+# ADR: Title
+
+- Status: Proposed | Accepted | Superseded
+- Date:
+- Deciders:
+
+## Context
+
+## Options
+
+1.
+2.
+
+## Decision
+
+## Consequences

package/templates/docs/FEATURE.md

@@ -0,0 +1,19 @@
+# Feature spec
+
+## Problem
+
+## User / persona
+
+## Business rules
+
+## Out of scope
+
+## Data impact
+
+## API impact
+
+## Authz rules
+
+## Test plan
+
+## Rollout / flag

package/templates/docs/SECURITY_REPORT.md

@@ -0,0 +1,15 @@
+# Security finding
+
+- Severity: P0 | P1 | P2
+- Component:
+- Reporter:
+
+## Summary
+
+## Reproduction
+
+## Impact
+
+## Recommended fix
+
+## References (OWASP/CWE)

package/templates/docs/accessibility-review.md

@@ -0,0 +1,9 @@
+# Template — accessibility review
+
+## Context
+
+## Details
+
+## Related rule IDs
+
+-

package/templates/docs/component.md

@@ -0,0 +1,9 @@
+# Template — component
+
+## Context
+
+## Details
+
+## Related rule IDs
+
+-

package/templates/docs/decision-record.md

@@ -0,0 +1,9 @@
+# Template — decision record
+
+## Context
+
+## Details
+
+## Related rule IDs
+
+-

package/templates/docs/design-review.md

@@ -0,0 +1,9 @@
+# Template — design review
+
+## Context
+
+## Details
+
+## Related rule IDs
+
+-

package/templates/docs/exception.md

@@ -0,0 +1,9 @@
+# Template — exception
+
+## Context
+
+## Details
+
+## Related rule IDs
+
+-

package/templates/docs/page.md

@@ -0,0 +1,9 @@
+# Template — page
+
+## Context
+
+## Details
+
+## Related rule IDs
+
+-

package/templates/docs/pattern.md

@@ -0,0 +1,9 @@
+# Template — pattern
+
+## Context
+
+## Details
+
+## Related rule IDs
+
+-

package/templates/docs/user-flow.md

@@ -0,0 +1,9 @@
+# Template — user flow
+
+## Context
+
+## Details
+
+## Related rule IDs
+
+-

package/templates/github/workflows/app-ci.yml

@@ -0,0 +1,91 @@
+# Copy into your APPLICATION repo as .github/workflows/ci.yml,
+# then mark these jobs as required status checks on the default branch (OPS-001, OPS-002).
+name: ci
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+concurrency:
+  group: ci-${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  quality:
+    name: Lint · Typecheck · Unit
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "22"
+          cache: npm
+      - run: npm ci
+      - run: npm run lint --if-present
+      - run: npm run typecheck --if-present
+      - run: npm test --if-present
+
+  integration:
+    name: Integration tests
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "22"
+          cache: npm
+      - run: npm ci
+      - run: npm run test:integration --if-present
+
+  dependency-audit:
+    name: Dependency audit
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "22"
+          cache: npm
+      - run: npm ci
+      - run: npm run security:audit --if-present
+      - name: npm audit
+        if: ${{ hashFiles('package.json') != '' }}
+        run: npm audit --audit-level=high
+
+  secret-scan:
+    name: Secret scan
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - name: Gitleaks
+        uses: gitleaks/gitleaks-action@v2
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+  devia:
+    name: Devia — memory + readiness gates
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "22"
+      - name: Memory integrity
+        run: npx --yes devia validate
+      - name: Readiness gates (P0 blocks)
+        run: npx --yes devia check
+
+  e2e:
+    name: E2E / smoke
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "22"
+          cache: npm
+      - run: npm ci
+      - run: npm run test:e2e --if-present

package/templates/project/00_OVERVIEW.md

@@ -0,0 +1,51 @@
+# 00 — Overview
+
+> What this project **is**. No progress, no counters, no plans — those live in the registries
+> and the tracker (`MEM-007`).
+
+## What it is
+
+TODO(devia): one paragraph. What does this product do, for whom, and what would be lost if it
+did not exist?
+
+## Who uses it
+
+TODO(devia): the roles that matter to the code — anonymous visitor, customer, staff, admin,
+machine client. Permissions detail goes in `04_PERMISSIONS.md`.
+
+## Stack
+
+| Layer | Technology | Notes |
+|---|---|---|
+| Language / runtime | TODO(devia) | |
+| Framework | TODO(devia) | |
+| Data store | TODO(devia) | |
+| Frontend | TODO(devia) | |
+| Hosting / deploy | TODO(devia) | |
+| CI | TODO(devia) | |
+
+## Modules
+
+TODO(devia): the three to eight parts of the system a newcomer must know, one line each, with
+where each lives.
+
+| Module | Responsibility | Where |
+|---|---|---|
+| | | |
+
+## Non-goals
+
+TODO(devia): what this project deliberately does **not** do. This is the cheapest way to stop an
+agent from helpfully building the wrong thing.
+
+## Where the truth lives
+
+| Question | Source of truth |
+|---|---|
+| Product intent | TODO(devia) |
+| Data model | TODO(devia) |
+| Permissions | TODO(devia) |
+| API contract | TODO(devia) |
+| Design tokens | TODO(devia) |
+
+This memory **points** at those documents. It never copies them (`MEM-008`).

package/templates/project/01_ARCHITECTURE.md

@@ -0,0 +1,37 @@
+# 01 — Architecture
+
+> How the system is organised, and which boundaries must not be crossed (`ARC-001`).
+
+## Shape
+
+TODO(devia): the diagram in words. Client → API → service → store, or whatever is actually true.
+
+```text
+TODO(devia)
+```
+
+## Layers and boundaries
+
+| Layer | Owns | Must not |
+|---|---|---|
+| TODO(devia) | | |
+
+## Directory map
+
+| Path | Contains |
+|---|---|
+| TODO(devia) | |
+
+## Decisions that constrain new work
+
+TODO(devia): the decisions an agent must not silently reverse, each with a link to the ADR or the
+discussion that settled it (`ARC-002`).
+
+| Decision | Recorded in |
+|---|---|
+| | |
+
+## Current vs target
+
+Where the code and the intended architecture differ, the difference is a **debt line** in
+[`12_DEBT.md`](12_DEBT.md) — not a note here.

package/templates/project/02_SURFACES.md

@@ -0,0 +1,30 @@
+# 02 — Surfaces
+
+> Everything the outside world can reach: pages, endpoints, jobs, events, commands.
+> One capability, one surface (`API-006`).
+
+## Pages / screens
+
+| Route | Purpose | Component | Auth |
+|---|---|---|---|
+| TODO(devia) | | | |
+
+## Endpoints
+
+| Method + path | Purpose | Authorization | Handler |
+|---|---|---|---|
+| TODO(devia) | | | |
+
+## Background work
+
+| Job | Trigger | Idempotent | Where |
+|---|---|---|---|
+| TODO(devia) | | | |
+
+## Inbound events / webhooks
+
+| Source | Event | Verified how | Handler |
+|---|---|---|---|
+| TODO(devia) | | | |
+
+Adding any of these updates this file in the same change (`MEM-009`).

package/templates/project/03_DATA_MODEL.md

@@ -0,0 +1,31 @@
+# 03 — Data model
+
+> What is stored, and where its definition lives. The schema itself stays in the migrations
+> (`MEM-008`).
+
+## Entities
+
+| Entity | Meaning | Defined in | Notes |
+|---|---|---|---|
+| TODO(devia) | | | |
+
+## Invariants
+
+TODO(devia): what must always hold — money exact and carrying its currency (`DB-003`), archive
+instead of delete where history matters (`DB-005`), append-only audit trail (`DB-007`).
+
+## Lifecycles
+
+TODO(devia): the state machines that matter (order, payment, subscription): states, allowed
+transitions, and where the transition code lives. A transition not listed here does not exist.
+
+## Migrations
+
+| Convention | Value |
+|---|---|
+| Location | TODO(devia) |
+| Naming | TODO(devia) |
+| How they run | TODO(devia) |
+| Rollback strategy | TODO(devia) |
+
+Applied migrations are immutable; corrections ship forward (`DB-002`).

package/templates/project/04_PERMISSIONS.md

@@ -0,0 +1,32 @@
+# 04 — Permissions
+
+> Who can do what, enforced on the server (`SEC-001`), and what leaves an audit trail
+> (`DB-007`).
+
+## Roles
+
+| Role | Can | Cannot |
+|---|---|---|
+| TODO(devia) | | |
+
+## Enforcement
+
+| Surface | Enforced where | Test |
+|---|---|---|
+| TODO(devia) | | |
+
+Hiding a control in the interface is never enforcement.
+
+## Isolation
+
+TODO(devia): what scopes the data — user, organisation, tenant — and where that predicate is
+applied. Cross-scope access is covered by a test that fails when the predicate is removed
+(`SEC-005`, `TST-002`).
+
+## Audited actions
+
+TODO(devia): the actions that always write an audit row, with actor, target and outcome.
+
+| Action | Written where |
+|---|---|
+| | |

package/templates/project/05_FLOWS.md

@@ -0,0 +1,20 @@
+# 05 — Flows
+
+> The journeys the product cannot afford to break (`TST-005`).
+
+## Critical journeys
+
+| Journey | Steps | Covered by |
+|---|---|---|
+| TODO(devia) | | |
+
+## Failure behaviour
+
+For each critical journey: what the user sees when it fails, and what the system does — retry,
+refund, queue, alert (`STATE-002`, `UX-012`).
+
+| Journey | Failure mode | User sees | System does |
+|---|---|---|---|
+| TODO(devia) | | | |
+
+A journey with no stated failure behaviour is a journey whose failure behaviour is an accident.

package/templates/project/06_INTEGRATIONS.md

@@ -0,0 +1,21 @@
+# 06 — Integrations
+
+> External services this project depends on. Secret **names** only — never values (`SEC-002`).
+
+| Service | Used for | Environment variable | Failure behaviour |
+|---|---|---|---|
+| TODO(devia) | | | |
+
+## Webhooks in
+
+| Provider | Verification | Idempotency key | Handler |
+|---|---|---|---|
+| TODO(devia) | | | |
+
+Signature verified against the raw body, stale timestamps rejected, replays are no-ops
+(`SEC-007`).
+
+## When one is down
+
+TODO(devia): degrade, queue, or fail closed — per integration. "It breaks" is an acceptable
+answer only if it is a deliberate one.

package/templates/project/07_DESIGN.md

@@ -0,0 +1,33 @@
+# 07 — Design
+
+> The interface decisions specific to this project. The general rules live in the standard
+> (`standard/standard/design/`); this file records what is local.
+
+## Tokens
+
+| Token set | Source of truth | Consumed by |
+|---|---|---|
+| TODO(devia) | | |
+
+Git is the source of truth for tokens (`DS-001`); components consume semantic tokens, not raw
+values (`DS-002`, `UI-003`).
+
+## Components
+
+| Component | Where | States implemented |
+|---|---|---|
+| TODO(devia) | | |
+
+Complete means default, hover, focus, active, disabled, loading, empty, error, success — plus
+permission-denied and offline where they can occur (`STATE-001`, `STATE-002`, `STATE-003`).
+
+## Patterns fixed for this product
+
+TODO(devia): the choices that must stay consistent — table density, date and currency format,
+empty-state voice, how destructive actions are confirmed (`UX-011`).
+
+## Interface decisions
+
+| Decision | Why | Recorded in |
+|---|---|---|
+| TODO(devia) | | |

package/templates/project/10_NEVER_ALWAYS.md

@@ -0,0 +1,26 @@
+# 10 — Never / Always
+
+> Rules this project earned. Each line comes from a real incident or a decision that was actually
+> contested, and names the trap **and** the correct move (`MEM-010`).
+
+## Never
+
+- TODO(devia): the first line goes here, after the first mistake worth remembering.
+
+## Always
+
+- Always read the memory file for a surface before changing it (`AGT-001`).
+- Always update `.devia/` in the same change as the code (`MEM-009`).
+- TODO(devia): add this project's own.
+
+## How a line gets added
+
+```text
+Something broke, or a decision was argued twice
+        ↓
+Fix it
+        ↓
+Add ONE line: what not to do, and what to do instead
+```
+
+A line nobody has ever violated is noise, and noise teaches agents to skim. Delete it.