@schneiderjoseph/devia 0.1.0

package/rules/memory/MEM-001.md

@@ -0,0 +1,44 @@
+---
+id: MEM-001
+title: Undecided is never coded as a silent truth
+severity: MUST
+status: active
+domain: memory
+priority: P0
+source:
+  - devia
+applies_to:
+  - agent
+  - repository
+success_criteria:
+  []
+requirement: >
+  When a rule has not been decided, the implementation MUST make its assumption visible and the open question MUST be recorded in `.devia/11_GAPS.md`. Silent defaults MUST NOT become de facto policy.
+validation:
+  automated: false
+  manual: true
+exceptions: none
+---
+
+# MEM-001 — Undecided is never coded as a silent truth
+
+**Requirement:** When a rule has not been decided, the implementation MUST make its assumption visible and the open question MUST be recorded in `.devia/11_GAPS.md`. Silent defaults MUST NOT become de facto policy.
+
+**Bad:** The code rounds down, nobody decided that, and in six months it is 'how it works'.
+
+**Good:** A named constant, a comment pointing at the gap line, and a gap entry awaiting a decision.
+
+## Validation
+
+- The gap registry contains the open question
+- The code's assumption is visible
+
+## Lifecycle
+
+- Status: `active`
+- Priority: `P0`
+- Exceptions: `none`
+
+## See also
+
+- [MEMORY.md](../../MEMORY.md)

package/rules/memory/MEM-002.md

@@ -0,0 +1,39 @@
+---
+id: MEM-002
+title: Decided but not built is recorded as debt
+severity: MUST
+status: active
+domain: memory
+priority: P1
+source:
+  - devia
+applies_to:
+  - agent
+  - repository
+success_criteria:
+  []
+requirement: >
+  When the project has decided a rule and the code does not honour it yet, a debt line MUST be added to `.devia/12_DEBT.md` — even when the agent is not going to fix it now.
+validation:
+  automated: false
+  manual: true
+exceptions: documented-only
+---
+
+# MEM-002 — Decided but not built is recorded as debt
+
+**Requirement:** When the project has decided a rule and the code does not honour it yet, a debt line MUST be added to `.devia/12_DEBT.md` — even when the agent is not going to fix it now.
+
+**Bad:** Noticing that a validation is missing and moving on because it was not the task.
+
+**Good:** A debt line naming the rule, the place, and what it would take.
+
+## Validation
+
+- The debt registry gained a line for what was found
+
+## Lifecycle
+
+- Status: `active`
+- Priority: `P1`
+- Exceptions: `documented-only`

package/rules/memory/MEM-003.md

@@ -0,0 +1,38 @@
+---
+id: MEM-003
+title: Debt lines are closed only by the change that discharges them
+severity: MUST
+status: active
+domain: memory
+priority: P1
+source:
+  - devia
+applies_to:
+  - repository
+success_criteria:
+  []
+requirement: >
+  A debt line MUST be removed in the same change that makes it false, and MUST be reduced rather than deleted when the work is partly done. Removing a line for tidiness is forbidden.
+validation:
+  automated: false
+  manual: true
+exceptions: documented-only
+---
+
+# MEM-003 — Debt lines are closed only by the change that discharges them
+
+**Requirement:** A debt line MUST be removed in the same change that makes it false, and MUST be reduced rather than deleted when the work is partly done. Removing a line for tidiness is forbidden.
+
+**Bad:** Deleting three debt lines during cleanup because they 'look old'.
+
+**Good:** The line for the fixed part is removed; the remainder is rewritten to what is still true.
+
+## Validation
+
+- Every removed debt line is discharged by the same diff
+
+## Lifecycle
+
+- Status: `active`
+- Priority: `P1`
+- Exceptions: `documented-only`

package/rules/memory/MEM-004.md

@@ -0,0 +1,38 @@
+---
+id: MEM-004
+title: Registry identifiers are monotone and never reused
+severity: MUST
+status: active
+domain: memory
+priority: P1
+source:
+  - devia
+applies_to:
+  - repository
+success_criteria:
+  []
+requirement: >
+  Gap and debt identifiers MUST increase and MUST NOT be reused after closure, so that an old reference never resolves to a different subject.
+validation:
+  automated: true
+  manual: true
+exceptions: documented-only
+---
+
+# MEM-004 — Registry identifiers are monotone and never reused
+
+**Requirement:** Gap and debt identifiers MUST increase and MUST NOT be reused after closure, so that an old reference never resolves to a different subject.
+
+**Bad:** Reusing `G7` for a new gap after the original was closed.
+
+**Good:** The next gap is `G23`; `G7` stays closed and readable in history.
+
+## Validation
+
+- `devia validate` reports no duplicate or reused id
+
+## Lifecycle
+
+- Status: `active`
+- Priority: `P1`
+- Exceptions: `documented-only`

package/rules/memory/MEM-005.md

@@ -0,0 +1,38 @@
+---
+id: MEM-005
+title: Verify before recording
+severity: MUST
+status: active
+domain: memory
+priority: P1
+source:
+  - devia
+applies_to:
+  - agent
+success_criteria:
+  []
+requirement: >
+  A gap, debt or never/always line MUST be checked against the code before it is written. A false line is worse than a missing one because it is trusted.
+validation:
+  automated: false
+  manual: true
+exceptions: documented-only
+---
+
+# MEM-005 — Verify before recording
+
+**Requirement:** A gap, debt or never/always line MUST be checked against the code before it is written. A false line is worse than a missing one because it is trusted.
+
+**Bad:** Recording 'no rate limiting anywhere' without opening the middleware that implements it.
+
+**Good:** The claim is checked, then recorded with the file that shows it.
+
+## Validation
+
+- Each new registry line names where the claim was verified
+
+## Lifecycle
+
+- Status: `active`
+- Priority: `P1`
+- Exceptions: `documented-only`

package/rules/memory/MEM-006.md

@@ -0,0 +1,38 @@
+---
+id: MEM-006
+title: Sweep the surface you touch
+severity: MUST
+status: active
+domain: memory
+priority: P1
+source:
+  - devia
+applies_to:
+  - repository
+success_criteria:
+  []
+requirement: >
+  A change to a shared surface — schema, route family, port, interface, design token — MUST sweep that surface for other violations and record what it finds. Finding nothing is a valid result and MUST be stated.
+validation:
+  automated: false
+  manual: true
+exceptions: documented-only
+---
+
+# MEM-006 — Sweep the surface you touch
+
+**Requirement:** A change to a shared surface — schema, route family, port, interface, design token — MUST sweep that surface for other violations and record what it finds. Finding nothing is a valid result and MUST be stated.
+
+**Bad:** Fixing one endpoint's authorization and leaving the four siblings unexamined and unrecorded.
+
+**Good:** All five are checked; three are fine; two become debt lines.
+
+## Validation
+
+- The report states the swept surface and the outcome
+
+## Lifecycle
+
+- Status: `active`
+- Priority: `P1`
+- Exceptions: `documented-only`

package/rules/memory/MEM-007.md

@@ -0,0 +1,38 @@
+---
+id: MEM-007
+title: No perishable facts in overview or index files
+severity: MUST NOT
+status: active
+domain: memory
+priority: P1
+source:
+  - devia
+applies_to:
+  - repository
+success_criteria:
+  []
+requirement: >
+  Memory files describing what the project is MUST NOT contain counters, current branches, sprint plans or 'next we will' statements. Perishable facts belong to the registries and the tracker.
+validation:
+  automated: true
+  manual: true
+exceptions: documented-only
+---
+
+# MEM-007 — No perishable facts in overview or index files
+
+**Requirement:** Memory files describing what the project is MUST NOT contain counters, current branches, sprint plans or 'next we will' statements. Perishable facts belong to the registries and the tracker.
+
+**Bad:** '42 tests passing, currently building the invoice screen' in `00_OVERVIEW.md`.
+
+**Good:** The overview describes the product and the stack; progress lives in the registries.
+
+## Validation
+
+- `devia validate` finds no perishable-fact markers
+
+## Lifecycle
+
+- Status: `active`
+- Priority: `P1`
+- Exceptions: `documented-only`

package/rules/memory/MEM-008.md

@@ -0,0 +1,38 @@
+---
+id: MEM-008
+title: Memory points at documentation, it does not duplicate it
+severity: MUST
+status: active
+domain: memory
+priority: P1
+source:
+  - devia
+applies_to:
+  - repository
+success_criteria:
+  []
+requirement: >
+  Memory files MUST reference the authoritative document or file for detail instead of copying it, so there is exactly one place to change when the detail changes.
+validation:
+  automated: false
+  manual: true
+exceptions: documented-only
+---
+
+# MEM-008 — Memory points at documentation, it does not duplicate it
+
+**Requirement:** Memory files MUST reference the authoritative document or file for detail instead of copying it, so there is exactly one place to change when the detail changes.
+
+**Bad:** The full table definition pasted into the memory, drifting from the migration within a week.
+
+**Good:** '`invoice` — defined in `migrations/20260812_invoice.sql`, rules in `docs/BILLING.md` §4.'
+
+## Validation
+
+- New memory content links rather than copies
+
+## Lifecycle
+
+- Status: `active`
+- Priority: `P1`
+- Exceptions: `documented-only`

package/rules/memory/MEM-009.md

@@ -0,0 +1,39 @@
+---
+id: MEM-009
+title: Code and memory ship in the same change
+severity: MUST
+status: active
+domain: memory
+priority: P0
+source:
+  - devia
+applies_to:
+  - repository
+success_criteria:
+  []
+requirement: >
+  When a change makes a memory file false, the same change MUST fix it. `impact-map.yaml` names which files each kind of change touches.
+validation:
+  automated: true
+  manual: true
+exceptions: none
+---
+
+# MEM-009 — Code and memory ship in the same change
+
+**Requirement:** When a change makes a memory file false, the same change MUST fix it. `impact-map.yaml` names which files each kind of change touches.
+
+**Bad:** A new endpoint merged on Monday; `02_SURFACES.md` updated 'later'.
+
+**Good:** The endpoint and the surfaces entry land in the same pull request.
+
+## Validation
+
+- `devia doctor` reports no memory lag for the surfaces touched
+- The impact map entry was honoured
+
+## Lifecycle
+
+- Status: `active`
+- Priority: `P0`
+- Exceptions: `none`

package/rules/memory/MEM-010.md

@@ -0,0 +1,38 @@
+---
+id: MEM-010
+title: Never/always lines come from real incidents
+severity: SHOULD
+status: active
+domain: memory
+priority: P2
+source:
+  - devia
+applies_to:
+  - repository
+success_criteria:
+  []
+requirement: >
+  `10_NEVER_ALWAYS.md` SHOULD grow one line at a time, each earned by a mistake that actually happened or a decision that was actually contested. Speculative rules dilute the file and train agents to skim.
+validation:
+  automated: false
+  manual: true
+exceptions: documented-only
+---
+
+# MEM-010 — Never/always lines come from real incidents
+
+**Requirement:** `10_NEVER_ALWAYS.md` SHOULD grow one line at a time, each earned by a mistake that actually happened or a decision that was actually contested. Speculative rules dilute the file and train agents to skim.
+
+**Bad:** Forty generic best-practice lines copied from a blog post.
+
+**Good:** Six lines, each traceable to a bug this project actually shipped.
+
+## Validation
+
+- Each line names the trap and the correct move
+
+## Lifecycle
+
+- Status: `active`
+- Priority: `P2`
+- Exceptions: `documented-only`

package/rules/memory/MEM-011.md

@@ -0,0 +1,38 @@
+---
+id: MEM-011
+title: Never delete a registry line you did not discharge
+severity: MUST NOT
+status: active
+domain: memory
+priority: P0
+source:
+  - devia
+applies_to:
+  - agent
+success_criteria:
+  []
+requirement: >
+  An agent MUST NOT remove a gap or debt line to make a report look cleaner, and MUST NOT close a line on the basis that it 'seems handled'. Closure requires naming the change that closed it.
+validation:
+  automated: true
+  manual: true
+exceptions: none
+---
+
+# MEM-011 — Never delete a registry line you did not discharge
+
+**Requirement:** An agent MUST NOT remove a gap or debt line to make a report look cleaner, and MUST NOT close a line on the basis that it 'seems handled'. Closure requires naming the change that closed it.
+
+**Bad:** Clearing the debt file during a refactor because it was 'out of date'.
+
+**Good:** Each closure names its commit; anything unverified stays open.
+
+## Validation
+
+- Removed lines are justified in the same diff
+
+## Lifecycle
+
+- Status: `active`
+- Priority: `P0`
+- Exceptions: `none`

package/rules/motion/MOT-001.md

@@ -0,0 +1,38 @@
+---
+id: MOT-001
+title: Motion has a job
+severity: SHOULD
+status: active
+priority: P2
+domain: motion
+source:
+  - Material
+applies_to:
+  - motion
+success_criteria:
+  []
+requirement: >
+  Animation SHOULD communicate state/hierarchy, not only decoration.
+validation:
+  automated: false
+  manual: true
+exceptions: documented-only
+---
+
+# MOT-001 — Motion has a job
+
+**Requirement:** Animation SHOULD communicate state/hierarchy, not only decoration.
+
+**Bad:** Infinite bouncing logos.
+
+**Good:** Short transition on drawer open.
+
+## Validation
+
+- Design or engineering review
+
+## Lifecycle
+
+- Status: `active`
+- Priority: `P2`
+- Exceptions: `documented-only`

package/rules/observability/OBS-001.md

@@ -0,0 +1,40 @@
+---
+id: OBS-001
+title: Logs are structured, correlated, and free of secrets
+severity: MUST
+status: active
+domain: observability
+priority: P1
+source:
+  - Google SRE
+applies_to:
+  - service
+  - api
+success_criteria:
+  []
+requirement: >
+  Logs MUST be structured, MUST carry a request or trace identifier, and MUST NOT contain credentials, tokens, full payment data or unnecessary personal data.
+validation:
+  automated: true
+  manual: true
+exceptions: documented-only
+---
+
+# OBS-001 — Logs are structured, correlated, and free of secrets
+
+**Requirement:** Logs MUST be structured, MUST carry a request or trace identifier, and MUST NOT contain credentials, tokens, full payment data or unnecessary personal data.
+
+**Bad:** `console.log(request.body)` on a payment route.
+
+**Good:** A structured entry with the correlation id, the operation, the outcome and safe identifiers.
+
+## Validation
+
+- Grep the diff for raw body or header logging
+- Correlation id present on the new paths
+
+## Lifecycle
+
+- Status: `active`
+- Priority: `P1`
+- Exceptions: `documented-only`

package/rules/observability/OBS-002.md

@@ -0,0 +1,40 @@
+---
+id: OBS-002
+title: Errors reach a system a human watches
+severity: MUST
+status: active
+domain: observability
+priority: P1
+source:
+  - Google SRE
+applies_to:
+  - service
+  - web
+success_criteria:
+  []
+requirement: >
+  Unhandled errors and failed background work MUST be reported to an error tracker or alert channel with enough context to reproduce, and MUST NOT be swallowed by an empty catch.
+validation:
+  automated: true
+  manual: true
+exceptions: documented-only
+---
+
+# OBS-002 — Errors reach a system a human watches
+
+**Requirement:** Unhandled errors and failed background work MUST be reported to an error tracker or alert channel with enough context to reproduce, and MUST NOT be swallowed by an empty catch.
+
+**Bad:** `catch (e) {}` and a job that fails silently every night.
+
+**Good:** The error is reported with the correlation id and the job name; the failure is visible without asking.
+
+## Validation
+
+- No empty catch in the diff
+- The new failure path reports somewhere
+
+## Lifecycle
+
+- Status: `active`
+- Priority: `P1`
+- Exceptions: `documented-only`

package/rules/observability/OBS-003.md

@@ -0,0 +1,38 @@
+---
+id: OBS-003
+title: Alerts are actionable and owned
+severity: MUST
+status: active
+domain: observability
+priority: P1
+source:
+  - Google SRE
+applies_to:
+  - devops
+success_criteria:
+  []
+requirement: >
+  An alert MUST describe a condition a human can act on, name what to do, and have an owner. Alerts nobody acts on MUST be deleted, not muted.
+validation:
+  automated: false
+  manual: true
+exceptions: documented-only
+---
+
+# OBS-003 — Alerts are actionable and owned
+
+**Requirement:** An alert MUST describe a condition a human can act on, name what to do, and have an owner. Alerts nobody acts on MUST be deleted, not muted.
+
+**Bad:** A CPU alert that fires nightly and is ignored by everyone.
+
+**Good:** An alert on user-visible error rate, linked to a runbook, owned by a person.
+
+## Validation
+
+- Each alert has a runbook link and an owner
+
+## Lifecycle
+
+- Status: `active`
+- Priority: `P1`
+- Exceptions: `documented-only`

package/rules/observability/OBS-004.md

@@ -0,0 +1,38 @@
+---
+id: OBS-004
+title: Deployables expose health and readiness
+severity: SHOULD
+status: active
+domain: observability
+priority: P2
+source:
+  - devia
+applies_to:
+  - service
+success_criteria:
+  []
+requirement: >
+  A deployable service SHOULD expose a liveness signal and a readiness signal that reflects its dependencies, and readiness SHOULD gate traffic during deploys.
+validation:
+  automated: true
+  manual: true
+exceptions: documented-only
+---
+
+# OBS-004 — Deployables expose health and readiness
+
+**Requirement:** A deployable service SHOULD expose a liveness signal and a readiness signal that reflects its dependencies, and readiness SHOULD gate traffic during deploys.
+
+**Bad:** A health endpoint that returns 200 while the database connection is dead.
+
+**Good:** Readiness checks the dependencies it truly needs; liveness stays cheap.
+
+## Validation
+
+- Readiness fails when a required dependency is down
+
+## Lifecycle
+
+- Status: `active`
+- Priority: `P2`
+- Exceptions: `documented-only`

package/rules/privacy/PRIV-001.md

@@ -0,0 +1,38 @@
+---
+id: PRIV-001
+title: Collect the minimum personal data
+severity: MUST
+status: active
+domain: privacy
+priority: P1
+source:
+  - GDPR principles
+applies_to:
+  - repository
+success_criteria:
+  []
+requirement: >
+  Personal data MUST be collected only where a stated product need requires it, and every field MUST have a reason recorded in the data model.
+validation:
+  automated: false
+  manual: true
+exceptions: documented-only
+---
+
+# PRIV-001 — Collect the minimum personal data
+
+**Requirement:** Personal data MUST be collected only where a stated product need requires it, and every field MUST have a reason recorded in the data model.
+
+**Bad:** A national identifier collected 'in case we need it later'.
+
+**Good:** Only the fields the flow needs, each with a documented purpose.
+
+## Validation
+
+- Every personal field in the diff has a stated purpose
+
+## Lifecycle
+
+- Status: `active`
+- Priority: `P1`
+- Exceptions: `documented-only`