@schneiderjoseph/devia 0.1.0

package/AGENTS.md

@@ -0,0 +1,149 @@
+# AGENTS.md — Work contract for AI coding agents
+
+You are working on software under **devia**. This file is your employment contract.
+Violating it is a failed task, not a stylistic difference.
+
+You are not here to produce plausible code. You are here to make a verified change to a system
+you understand, and to leave the project's memory true afterwards.
+
+## Rule zero — memory before code
+
+```text
+Work requested
+    ↓
+.devia/ exists in the repo? ──NO──► run `devia init` and fill 00_OVERVIEW before coding
+    ↓ YES
+Read .devia/AGENTS.md → .devia/10_NEVER_ALWAYS.md → .devia/00_OVERVIEW.md
+    ↓
+Read the .devia file for the surface you are touching (see 14_INDEX.md)
+    ↓
+Read the standard section for the domain (standard/ + rules/)
+    ↓
+Work
+    ↓
+Update .devia/ in the SAME change
+```
+
+Never start coding "to explore" and read the memory later. The memory is what stops you from
+inventing.
+
+## Required workflow
+
+```text
+Read the contract (this file + .devia/AGENTS.md)
+    ↓
+Read the relevant memory + domain policy + matching checklist
+    ↓
+Understand the existing patterns in the target repo before adding new ones
+    ↓
+Implement the smallest change that satisfies the request
+    ↓
+Run the checks that exist (lint · typecheck · tests · devia check)
+    ↓
+Update .devia/ (memory, registries, impact map) in the same change
+    ↓
+Report what changed, and report what was NOT verified
+```
+
+## Non-negotiable
+
+1. **Read before you write.** Read the file you are about to edit, and the memory entry that
+   describes it.
+2. **Never invent.** No APIs, business rules, DB fields, config keys, or endpoints that are not
+   in the spec, the ADR, or the memory. If it is not decided, it goes in `.devia/11_GAPS.md` —
+   it does not go in the code as a silent truth.
+3. **Smallest change that satisfies the request.** No opportunistic refactors riding along.
+4. **Complexity must be earned.** No Redis, Kubernetes, microservices, queues, GraphQL or extra
+   databases "because serious apps have them" (`PRINCIPLES.md`).
+5. **Every new dependency is a liability.** Justify it before adding it.
+6. **Code and memory ship together.** If the change makes a `.devia` file false, the same change
+   fixes it (`impact-map.yaml` says which).
+7. **Registries are not optional.** Decided-but-not-built goes in `.devia/12_DEBT.md`; the line is
+   removed only by the change that discharges it, and reduced — never deleted — when partly done.
+8. **Cite rule IDs** in compliance summaries (`UX-007`, `SEC-002`, `MEM-003`).
+9. **Report what you did not verify.** Silence about unverified work is a false claim of
+   completeness.
+10. **Never claim "done" or "production ready"** while a P0 gate is failing or unrun.
+
+## Hard stops (refuse or escalate — do not "work around")
+
+- Secrets or credentials in source, config, logs, or client bundles
+- Client-only security: hiding UI without a server-side authorization check
+- Any path where one user or tenant can read or write another's data
+- Raw stack traces, SQL errors, or internal identifiers returned to production clients
+- Payment or webhook handling without signature verification and replay protection
+- Schema change without a versioned migration, or editing an already-applied migration
+- Disabling, skipping, or weakening a failing test or check to make CI green
+- `--no-verify` or any hook bypass to get a commit through
+- Committing directly to `main` when the project uses branch + PR
+- Deleting a gap or debt line you did not discharge
+- Third-party documentation, schemas, or assets pasted in as original work
+- Claiming WCAG conformance without contrast, keyboard, and accessible-name evidence
+
+## You may NOT declare "production ready" unless
+
+Evidence exists across **all** of:
+
+```text
+Code quality · Security · Architecture · Database · Tests
+Infrastructure · Observability · Backup · Documentation · Compliance · UI/a11y
+```
+
+Minimum bar: `devia check` reports **no P0 FAIL**, and every residual WARN is listed explicitly
+for the human. Passing unit tests is not Gold maturity — see [`MATURITY.md`](MATURITY.md).
+
+## Routing
+
+| Task involves… | Read |
+|---|---|
+| What this project is, its stack, its history | `.devia/00_OVERVIEW.md`, `.devia/01_ARCHITECTURE.md` |
+| Things this project has already banned | `.devia/10_NEVER_ALWAYS.md` |
+| Something undecided / not built | `.devia/11_GAPS.md`, `.devia/12_DEBT.md` |
+| How to do a routine task here | `.devia/13_RECIPES.md` |
+| How the standard is enforced | `LEVELS.md`, `MATURITY.md`, `PRINCIPLES.md` |
+| Agent behaviour and memory discipline | `rules/agent/`, `rules/memory/`, `MEMORY.md` |
+| Login, sessions, roles, tenancy | `standard/engineering/security/AUTHENTICATION.md`, `AUTHORIZATION.md`, `rules/security/` |
+| ASVS control mapping | `standard/engineering/security/ASVS_REGISTRY.md` |
+| Schema, migrations, indexes, backups | `standard/engineering/database/`, `rules/database/` |
+| Endpoints, validation, versioning, webhooks | `standard/engineering/backend/API.md`, `rules/api/` |
+| Tests, CI gates | `standard/engineering/testing/`, `standard/engineering/devops/CI_CD.md`, `rules/testing/` |
+| Deploy, environments, rollback | `standard/engineering/devops/`, `rules/devops/` |
+| Logs, metrics, alerts, incidents | `standard/engineering/observability/`, `rules/observability/` |
+| Privacy, retention, deletion/export | `standard/engineering/compliance/`, `rules/privacy/` |
+| LLM features, prompts, agent tools | `standard/engineering/ai/`, `rules/ai/` |
+| Any user-facing UI | `standard/design/`, `rules/ux/`, `rules/ui/`, `rules/accessibility/`, `rules/states/` |
+| Money, dates, numbers on screen | `standard/design/data-display/`, `rules/data-display/` |
+| "Is it production ready?" | `checklists/engineering/production.md` + `devia check` |
+
+## UI work is not exempt
+
+Every user-facing surface must satisfy the design rules as well as the engineering ones:
+accessible name, keyboard path, visible focus, persistent labels, complete states
+(default · hover · focus · active · disabled · loading · empty · error · success), tokens instead
+of one-off values, and never colour as the only carrier of meaning.
+
+A pretty screen does not waive an engineering P0. A green test suite does not waive `A11Y-006`.
+
+## Output contract
+
+End substantial work with:
+
+```text
+## Devia compliance
+- Memory read: <files>
+- Domains touched: ...
+- Rules applied (IDs): ...
+- Rules violated / waived (IDs + why): ...
+- P0 status: ...
+- P1 remaining: ...
+- Checks run: ...
+- Checks NOT run (and why): ...
+- Tests added/updated: ...
+- .devia updated: <files> (or: none required, because ...)
+- Registries: gaps added/closed, debt added/reduced/discharged
+- New dependencies (justification, or none): ...
+- Not verified: ...
+```
+
+"Not verified" is never empty for a non-trivial change. If you believe it is, you have not
+looked hard enough.

package/CHANGELOG.md

@@ -0,0 +1,78 @@
+# Changelog
+
+## 0.1.0 — 2026-09-03
+
+First release. Devia consolidates three bodies of work into one maintained standard plus a
+living project memory.
+
+### Standard
+
+- Work contract for agents: [`AGENTS.md`](AGENTS.md) — rule zero, hard stops, output contract
+- [`PRINCIPLES.md`](PRINCIPLES.md), [`LEVELS.md`](LEVELS.md) (memory → policy → check →
+  enforcement), [`MATURITY.md`](MATURITY.md) (P0–P3, Bronze → Platinum),
+  [`GOVERNANCE.md`](GOVERNANCE.md)
+- [`MEMORY.md`](MEMORY.md) — the living-memory doctrine: the two registries, sweep discipline,
+  the impact map, no perishable facts, freshness
+
+### Rules
+
+- Unified registry of **138 rules** with stable IDs, severity, priority, source and validation
+  method: [`rules/README.md`](rules/README.md)
+- 58 design rules carried over unchanged from `design-system-standard`: `A11Y-*`, `CMP-*`,
+  `CNT-*`, `DATA-*`, `DS-*`, `I18N-*`, `INT-*`, `MOT-*`, `RWD-*`, `STATE-*`, `UI-*`, `UX-*`
+- 80 new engineering, agent and memory rules: `ARC-*`, `SEC-*`, `DB-*`, `API-*`, `TST-*`,
+  `OPS-*`, `OBS-*`, `PRIV-*`, `AI-*`, `AGT-*`, `MEM-*`
+- `priority` (P0–P3) added to every rule, including the carried-over design rules
+- Generated index, coverage and traceability: `npm run build:index`
+
+### Corpus
+
+- `production-app-standard` absorbed into [`standard/engineering/`](standard/engineering/README.md)
+  and `checklists/engineering/`
+- `design-system-standard` absorbed into [`standard/design/`](standard/design/README.md) and
+  `checklists/design/`
+- See [`MIGRATION.md`](MIGRATION.md) for the path mapping
+
+### CLI
+
+- `devia init` — writes `.devia/`, vendors the standard, installs the agent adapters
+- `devia validate` — memory integrity: structure, config, impact map, registry ids,
+  placeholders, perishable facts
+- `devia check` — readiness gates with P0 blocking, replacing `scripts/production-check.mjs`
+- `devia doctor` — adoption, version drift, and whether the memory lags the code
+- `devia rules` — query the registry by id, domain, priority, severity or text
+- `devia sync` — refresh the vendored standard and report what changed
+- `devia gap` / `devia debt` — registry lines with monotone ids that are never reused
+- `devia skills install` — adapters for Cursor, Claude Code, Copilot, Windsurf and the universal
+  `AGENTS.md`
+- `devia --version` prints both versions: the CLI, and the standard it carries
+- `devia init` refuses a root it inferred that is not the current directory — `--root` says
+  where, `--yes` accepts the detected one; nothing is written before that is settled
+- `devia check` scans what git carries: tracked files plus untracked ones that are not ignored.
+  An ignored build artefact can no longer fail a P0 gate. Without git, the tree is walked instead
+- `.devia/standard/` is vendored together with everything its files link to (`templates/docs/`,
+  `templates/github/`, `MIGRATION.md`, `CHANGELOG.md`), so every relative link resolves in the
+  adopter's copy; the test walks the materialised tree to prove it
+- `devia.json` records the CLI version in `deviaVersion` and the corpus version in
+  `standardVersion` — the two move independently
+- Closing a registry line splices the row out instead of blanking it, which used to leave a
+  blank line that ended the markdown table and orphaned every row below it
+- No runtime dependencies
+
+### Enforcement
+
+- CI runs the whole suite on ubuntu and windows, Node 20 and 22: the CLI writes files on both
+- `npm publish` re-runs `npm run validate`, the tests and both self-checks (`prepublishOnly`)
+
+### Adopting
+
+```bash
+npm install -D @schneiderjoseph/devia && npx devia init
+```
+
+Replace `node scripts/production-check.mjs` in CI with `npx devia check`, and add
+`npx devia validate`.
+
+The package is scoped, the command is not: npm refused the bare name `devia` as too similar to
+existing packages, so installs read `@schneiderjoseph/devia` while everything you type afterwards
+stays `devia`.

package/GOVERNANCE.md

@@ -0,0 +1,51 @@
+# Governance
+
+## Purpose
+
+This repository defines the standard. Application repositories **consume** it through
+`devia init` and their own `.devia/`; they do not casually fork conflicting rules.
+
+Devia is the only standard maintained here. `production-app-standard` and
+`design-system-standard` are absorbed and frozen — see [`MIGRATION.md`](MIGRATION.md).
+
+## Levels
+
+Policy → Check → Enforcement, on top of Memory. See [`LEVELS.md`](LEVELS.md).
+A rule without a check is aspirational; a check without CI is a suggestion. Both are allowed,
+provided the rule says which it is.
+
+## Changing a rule
+
+- A change to a `MUST` requires a PR with rationale and a traceability update
+- Rule IDs are **stable**: supersede, never reuse
+- A rule is never silently deleted: `deprecated` → `superseded` → `removed`, with a changelog
+  entry and a migration note (see [`rules/LIFECYCLE.md`](rules/LIFECYCLE.md))
+- New rules start `draft` or `proposed` and carry at least one source
+- Schema changes bump `rule_schema_version` in [`VERSION`](VERSION)
+
+## Changing the project template
+
+`templates/project/` is what every adopter receives. A change there affects every future
+`devia init`, so it takes the same review bar as a `MUST` rule, plus a note in
+[`CHANGELOG.md`](CHANGELOG.md) telling existing adopters whether `devia sync` is enough.
+
+## Versioning
+
+[`VERSION`](VERSION) carries the standard version and the schema versions. Breaking changes to
+rule IDs, to the `.devia/` layout, or to the CLI contract bump the version and ship with a
+migration path.
+
+Vendored copies in `.devia/standard/` are pinned to the version that wrote them. `devia sync`
+updates them and reports what changed.
+
+## Waivers
+
+A project may waive a rule. It may not do so silently: the waiver lives in `.devia/`, and names
+the rule ID, the scope, the reason, the accepting human, and an expiry date. An expired waiver
+is a finding, not a habit. Schema: [`schema/waiver.schema.json`](schema/waiver.schema.json).
+
+## Scope
+
+Devia interprets upstream standards (WCAG 2.2, ARIA APG, OWASP ASVS 5.0, NN/g, and adopted
+design systems). It does not replace an accessibility audit, a penetration test, or legal
+advice.

package/LEVELS.md

@@ -0,0 +1,78 @@
+# Four levels of the standard
+
+Documentation alone is not a standard. Devia operates on four levels, and each one is worthless
+without the next.
+
+```text
+LEVEL 0 — MEMORY       what is true about this project
+LEVEL 1 — POLICY       what must be true of the work
+LEVEL 2 — CHECK        how we verify it
+LEVEL 3 — ENFORCEMENT  how CI says no
+```
+
+## Level 0 — Memory
+
+`.devia/` in the target repo: overview, architecture, surfaces, data model, permissions,
+never/always, gaps, debt, recipes, index, impact map.
+
+Without it every agent starts cold, and policy has nothing to attach to: "follow the existing
+pattern" is meaningless if nobody wrote down what the pattern is.
+
+Verified by `devia validate` (structure, registries, staleness markers) and `devia doctor`
+(is the memory older than the code it describes?).
+
+## Level 1 — Policy
+
+Rules with stable IDs under [`rules/`](rules/README.md), domain policy under
+[`standard/`](standard/README.md), and priorities in [`MATURITY.md`](MATURITY.md).
+
+Examples: server-side authorization on every sensitive route (`SEC-001`), versioned migrations
+(`DB-001`), visible focus (`A11Y-006`), no undecided rule coded as a silent truth (`MEM-001`).
+
+## Level 2 — Check
+
+Commands that produce evidence:
+
+```bash
+npm run lint
+npm run typecheck
+npm test
+npm audit --omit=dev
+npx devia validate      # memory integrity
+npx devia check         # readiness gates (P0/P1) → PASS / WARN / FAIL
+npx devia doctor        # adoption, drift, staleness
+```
+
+`devia check` aggregates evidence into PASS / WARN / FAIL and exits non-zero on any P0 FAIL.
+
+## Level 3 — Enforcement
+
+CI must be able to say **NO** to a pull request.
+
+Copy [`templates/github/workflows/app-ci.yml`](templates/github/workflows/app-ci.yml) into the
+application repo and mark the checks required in branch protection.
+
+```text
+PR
+├── Lint / Typecheck / Unit        required
+├── Integration                    required (when present)
+├── Dependency audit               required
+├── Secret scan                    required
+├── devia validate (memory)        required
+├── devia check (P0)               required
+├── Accessibility gates            required for UI paths
+├── E2E / smoke                    required for release paths
+└── MERGE BLOCKED on any FAIL
+```
+
+## Mapping rule
+
+Every P0 policy item should map all the way down:
+
+```text
+Memory fact → Policy rule → Checklist item → Automated check → CI gate
+```
+
+If a P0 cannot be automated yet, document the manual check and treat it as a release-blocking
+sign-off — never as "optional". A rule with no check is aspirational; say so in the rule's
+`validation` block instead of pretending.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Joseph Schneider
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/MATURITY.md

@@ -0,0 +1,79 @@
+# Maturity model
+
+## Priority tags
+
+| Tag | Meaning | Enforcement |
+|---|---|---|
+| **P0** | BLOCKER | Must pass for real users / money / data; CI blocks merge or release |
+| **P1** | REQUIRED | Same milestone unless the human records an explicit risk acceptance |
+| **P2** | RECOMMENDED | Scheduled deliberately, not "later" |
+| **P3** | OPTIONAL | Nice to have; never pretend it is done |
+
+Rule severities (`MUST`, `MUST NOT`, `SHOULD`, `MAY`) describe the obligation. Priority tags
+describe when the obligation blocks. A `MUST` for a surface the product does not have yet is
+still a `MUST` — it is simply not applicable.
+
+## Tiers
+
+### Bronze — functional
+
+Works for a trusted demo or an internal pilot.
+
+- Core happy paths work
+- Basic auth if multi-user
+- Deployable somehow
+- No secrets in the client bundle
+- `.devia/` exists and `00_OVERVIEW.md` is true
+
+Not production for paying customers.
+
+### Silver — seriously tested and secured
+
+- Automated unit tests plus critical integration tests
+- Server-side authorization on every sensitive route
+- Input validation at every external boundary
+- CI on every PR: lint, typecheck, test
+- Dependency audit and secret scan in CI
+- Errors handled without leaking internals
+- Memory current: registries used, `devia validate` clean
+
+### Gold — production-ready
+
+Everything in [`checklists/engineering/production.md`](checklists/engineering/production.md),
+including:
+
+- Cross-user / cross-tenant isolation covered by tests
+- Migrations versioned; backup **and restore** drilled
+- Monitoring, alerting and error tracking in place
+- Staging → production path with a rollback that has actually been used
+- Rate limits on abuse surfaces
+- Privacy baseline matched to the data the product really holds
+- UI surfaces pass the design MUST rules: accessible name, keyboard path, visible focus,
+  contrast, persistent labels, complete states
+
+`devia check` reports **no P0 FAIL**.
+
+### Platinum — production-grade
+
+Gold, plus:
+
+- High availability where justified; documented DR with RPO/RTO and rehearsed drills
+- Full observability: SLOs and alerts a human can act on
+- Security automation: SAST, dependency and image scanning, ASVS tracking
+- Performance budgets enforced in CI
+- Supply-chain controls: lockfile discipline, SBOM where appropriate
+- Compliance controls matched to real obligations, not imagined ones
+- Accessibility validated with assistive technology, not only automated checks
+
+## Declaring a tier
+
+Record it in `.devia/devia.json` and keep it honest:
+
+```json
+{ "maturity": { "target": "gold", "current": "silver" } }
+```
+
+List the blockers in `.devia/12_DEBT.md`.
+
+Agents must never claim Gold or "production ready" while a P0 fails, is unrun, or is unknown.
+"I did not check" is reported, not rounded up.

package/MEMORY.md

@@ -0,0 +1,122 @@
+# Living memory
+
+The part of devia that is not a rulebook. `.devia/` is what an agent reads to stop being a
+stranger to the project.
+
+```text
+docs/       long specifications — the source of truth for details
+.devia/     short indexed memory — what exists, where it is, what is decided, what is not
+code        the only thing that is true by construction
+```
+
+`.devia/` points into the other two. It never copies them.
+
+## What memory must answer in under a minute
+
+1. What is this project, and what is it built with?
+2. How is it organised, and what boundaries must not be crossed?
+3. What surfaces exist (pages, endpoints, jobs), and where do they live?
+4. What has this project already banned, and why?
+5. What is decided but not built?
+6. What is not decided at all?
+7. How do I do the routine task I am about to do?
+
+A memory file that cannot answer its question in a scan is too long or too vague.
+
+## The two registries
+
+They are different things and must never be merged.
+
+| Registry | Means | Failure it prevents |
+|---|---|---|
+| `11_GAPS.md` | **Undecided.** Nobody has ruled on it. | The agent quietly picks an answer and encodes it as truth |
+| `12_DEBT.md` | **Decided, not built.** The rule exists; the code does not honour it yet. | "We know about it" — knowledge that leaves no trace and never gets scheduled |
+
+Discipline for both:
+
+- A decided `MUST` that the code violates is a **debt line**, not a shared understanding.
+- You **add** the line even when you are not going to fix it.
+- You **remove** the line in the same change that discharges it — never before, never later.
+- Partly done means you **reduce** the line, not delete it.
+- IDs are monotone and never reused. `G12` always means the same thing forever.
+- A false line is worse than a missing one. Verify before you record.
+- Closing a line requires naming the change that closed it.
+
+## Sweep discipline
+
+A registry fed only by accident gives false confidence: it looks like a map of the problems and
+is actually a map of what somebody happened to notice.
+
+So: a change that touches a **shared surface** sweeps that surface.
+
+```text
+Touched schema     → sweep the tables you touched for rules they violate
+Touched a route    → sweep the routes on that resource
+Touched a port     → sweep every implementation of it
+Touched a token    → sweep the components consuming it
+```
+
+Record what the sweep found. "Found nothing" is a valid, useful result — say it.
+
+## The impact map
+
+`.devia/impact-map.yaml` is the mechanical part: change type → files that must be updated in the
+same change. It is what makes "update the memory" a check instead of a virtue.
+
+```yaml
+new_table:        ["03_DATA_MODEL.md", "docs/DATABASE.md"]
+new_endpoint:     ["02_SURFACES.md"]
+permission_change:["04_PERMISSIONS.md", "docs/PERMISSIONS.md"]
+new_integration:  ["06_INTEGRATIONS.md"]
+design_token:     ["07_DESIGN.md"]
+architecture:     ["01_ARCHITECTURE.md"]
+stack_change:     ["00_OVERVIEW.md", "01_ARCHITECTURE.md"]
+```
+
+Extend it as the project grows a surface. An impact map that never changes is not being used.
+
+## No perishable facts
+
+Overview and index files describe what the project **is**, not where the work happens to be
+this week.
+
+```text
+Ban:   "42 tests passing", "next we build the invoice screen", "currently on branch feat/x"
+Keep:  "payments are escrowed until a release trigger fires (see docs/ESCROW.md §3)"
+```
+
+Perishable facts belong to the registries and the tracker, which have owners and lifecycles.
+Anything with a countdown in it rots into a lie and takes the credibility of the file with it.
+
+## Never / always grows from incidents
+
+`10_NEVER_ALWAYS.md` is not brainstormed up front. Each line earns its place by being a mistake
+that actually happened, or a decision that was actually contested.
+
+```text
+Bug or bad agent change happens
+        ↓
+Fix it
+        ↓
+Add ONE never/always line naming the trap and the correct move
+```
+
+Lines that were never violated by anyone are noise, and noise trains agents to skim.
+
+## Freshness
+
+Memory that lags the code is a trap: it is trusted precisely because it looks maintained.
+
+- `devia validate` checks the structure, the registries, and the placeholders
+- `devia doctor` compares the last commit that touched the code with the last commit that
+  touched `.devia/`, and reports the drift
+- CI runs both; a change that moves a surface without touching the memory fails review
+
+## Ownership
+
+Humans own the decisions. Agents own keeping the record of them true.
+
+An agent may never remove a gap or a debt line to make a report look better, downgrade a `MUST`
+without a waiver, or quietly rewrite a decision it disagrees with. It may — and should — flag
+that the memory contradicts the code, because that is the single highest-value thing it can
+notice.

package/MIGRATION.md

@@ -0,0 +1,62 @@
+# Migration — from two standards to one
+
+Devia consolidates three bodies of work into a single maintained standard:
+
+| Source | Became |
+|---|---|
+| `production-app-standard` | [`standard/engineering/`](standard/engineering/README.md), [`checklists/engineering/`](checklists/README.md), engineering rule IDs |
+| `design-system-standard` | [`standard/design/`](standard/design/README.md), [`checklists/design/`](checklists/README.md), design rule IDs |
+| Ad-hoc project memory (`DEVIA/` folders, agent guides, gap and debt registers) | [`MEMORY.md`](MEMORY.md), `rules/memory/`, `rules/agent/`, the `.devia/` template |
+
+Only devia is maintained. The two source repositories are frozen; do not open PRs against them.
+
+## Path mapping
+
+```text
+production-app-standard/docs/<domain>/X.md   →  devia/standard/engineering/<domain>/X.md
+production-app-standard/checklists/X.md      →  devia/checklists/engineering/X.md
+production-app-standard/templates/ADR.md     →  devia/templates/docs/ADR.md
+production-app-standard/scripts/production-check.mjs
+                                             →  devia check   (CLI command)
+
+design-system-standard/rules/<domain>/ID.md  →  devia/rules/<domain>/ID.md
+design-system-standard/<domain>/X.md         →  devia/standard/design/<domain>/X.md
+design-system-standard/checklists/X.md       →  devia/checklists/design/X.md
+design-system-standard/schema/*.json         →  devia/schema/*.json
+design-system-standard/scripts/validate-*.mjs
+                                             →  devia/scripts/validate-*.mjs
+```
+
+## Rule IDs
+
+Design rule IDs are **unchanged**: `A11Y-*`, `CMP-*`, `CNT-*`, `DATA-*`, `DS-*`, `I18N-*`,
+`INT-*`, `MOT-*`, `RWD-*`, `STATE-*`, `UI-*`, `UX-*`. Anything citing them keeps working.
+
+Engineering and agent rules are **new** IDs, not renames: `ARC-*`, `SEC-*`, `DB-*`, `API-*`,
+`TST-*`, `OPS-*`, `OBS-*`, `PRIV-*`, `AI-*`, `AGT-*`, `MEM-*`. They formalise obligations that
+`production-app-standard` expressed only as prose and checklists.
+
+Note the two `DATA` families do not collide: `DATA-*` is data **display** (design), database
+rules are `DB-*`.
+
+## If a repo already adopted one of the old standards
+
+```bash
+npm install -D @schneiderjoseph/devia
+npx devia init          # writes .devia/ and the agent adapters
+npx devia validate
+npx devia check
+```
+
+Then:
+
+1. Delete `.cursor/rules/production-app-standard.mdc` and
+   `.cursor/rules/design-system-standard.mdc`; `devia init` writes `.cursor/rules/devia.mdc`.
+2. Replace references to `production-app-standard` / `design-system-standard` in the repo's own
+   `AGENTS.md`, `CLAUDE.md` or `CONTRIBUTING.md` with `.devia/AGENTS.md`.
+3. Move anything the project had recorded as "known issues" into `.devia/11_GAPS.md`
+   (undecided) and `.devia/12_DEBT.md` (decided, not built) — the split matters.
+4. Replace `node scripts/production-check.mjs` in CI with `npx devia check`.
+
+Nothing in the old repos is lost: the full text of both is vendored here, and `devia init`
+vendors it again into the project under `.devia/standard/`.