@schneiderjoseph/devia 0.1.0

package/schema/component.schema.json

@@ -0,0 +1,37 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "ComponentSpec",
+  "type": "object",
+  "required": [
+    "id",
+    "name",
+    "states"
+  ],
+  "properties": {
+    "id": {
+      "type": "string"
+    },
+    "name": {
+      "type": "string"
+    },
+    "states": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      },
+      "minItems": 1
+    },
+    "tokens": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      }
+    },
+    "a11y": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      }
+    }
+  }
+}

package/schema/project-config.schema.json

@@ -0,0 +1,70 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/schneiderjoseph/devia/schema/project-config.schema.json",
+  "title": "DeviaProjectConfig",
+  "description": "Shape of .devia/devia.json, written by `devia init` and read by validate, check, doctor and sync.",
+  "type": "object",
+  "required": ["standardVersion", "project", "maturity"],
+  "properties": {
+    "deviaVersion": {
+      "type": "string",
+      "description": "Version of the devia package that last wrote this file."
+    },
+    "standardVersion": {
+      "type": "string",
+      "description": "Version of the standard pinned in .devia/standard/. `devia sync` updates it."
+    },
+    "project": {
+      "type": "object",
+      "required": ["name"],
+      "properties": {
+        "name": { "type": "string", "minLength": 1 },
+        "profile": {
+          "enum": ["web-app", "service", "library", "cli", "design-system", "docs"]
+        }
+      }
+    },
+    "maturity": {
+      "type": "object",
+      "description": "Declared tier. Agents must never claim a tier the checks do not support.",
+      "properties": {
+        "target": { "enum": ["bronze", "silver", "gold", "platinum"] },
+        "current": { "enum": ["bronze", "silver", "gold", "platinum"] }
+      }
+    },
+    "code": {
+      "type": "object",
+      "description": "Paths that hold the code the memory describes; `devia doctor` compares their history with .devia/.",
+      "properties": {
+        "paths": { "type": "array", "items": { "type": "string" } }
+      }
+    },
+    "modules": {
+      "type": "object",
+      "description": "Which parts of the standard apply to this project.",
+      "properties": {
+        "engineering": { "type": "boolean" },
+        "design": { "type": "boolean" },
+        "memory": { "type": "boolean" }
+      }
+    },
+    "waivers": {
+      "type": "array",
+      "description": "Time-boxed exceptions. An expired or undated waiver fails `devia check`.",
+      "items": {
+        "type": "object",
+        "required": ["rule_id", "reason", "owner", "expires"],
+        "properties": {
+          "rule_id": { "type": "string", "pattern": "^[A-Z][A-Z0-9]*(-[A-Z0-9]+)+$" },
+          "scope": { "type": "string" },
+          "reason": { "type": "string", "minLength": 10 },
+          "owner": { "type": "string" },
+          "expires": { "type": "string", "format": "date" },
+          "risk": { "enum": ["low", "medium", "high"] }
+        }
+      }
+    },
+    "initializedAt": { "type": "string", "format": "date" }
+  },
+  "additionalProperties": true
+}

package/schema/rule.schema.json

@@ -0,0 +1,104 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/schneiderjoseph/devia/schema/rule.schema.json",
+  "title": "DeviaRule",
+  "type": "object",
+  "required": [
+    "id",
+    "title",
+    "severity",
+    "status",
+    "domain",
+    "priority",
+    "source",
+    "requirement",
+    "validation"
+  ],
+  "properties": {
+    "id": {
+      "type": "string",
+      "pattern": "^[A-Z][A-Z0-9]*(-[A-Z0-9]+)+$"
+    },
+    "title": {
+      "type": "string",
+      "minLength": 3
+    },
+    "severity": {
+      "enum": [
+        "MUST",
+        "SHOULD",
+        "MAY",
+        "MUST NOT"
+      ],
+      "description": "The obligation itself."
+    },
+    "status": {
+      "enum": [
+        "draft",
+        "proposed",
+        "active",
+        "deprecated",
+        "superseded",
+        "removed"
+      ]
+    },
+    "domain": {
+      "type": "string"
+    },
+    "source": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      },
+      "minItems": 1
+    },
+    "applies_to": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      }
+    },
+    "success_criteria": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      }
+    },
+    "requirement": {
+      "type": "string",
+      "minLength": 10
+    },
+    "validation": {
+      "type": "object",
+      "required": [
+        "automated",
+        "manual"
+      ],
+      "properties": {
+        "automated": {
+          "type": "boolean"
+        },
+        "manual": {
+          "type": "boolean"
+        }
+      }
+    },
+    "exceptions": {
+      "type": "string"
+    },
+    "priority": {
+      "enum": [
+        "P0",
+        "P1",
+        "P2",
+        "P3"
+      ],
+      "description": "When the obligation blocks: P0 blocker, P1 required, P2 recommended, P3 optional."
+    },
+    "superseded_by": {
+      "type": "string",
+      "pattern": "^[A-Z][A-Z0-9]*(-[A-Z0-9]+)+$"
+    }
+  },
+  "additionalProperties": true
+}

package/schema/token.schema.json

@@ -0,0 +1,15 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "DesignTokenFile",
+  "type": "object",
+  "description": "Minimal wrapper; prefer W3C DTCG token files in consuming repos.",
+  "properties": {
+    "$schema": {
+      "type": "string"
+    },
+    "tokens": {
+      "type": "object"
+    }
+  },
+  "additionalProperties": true
+}

package/schema/waiver.schema.json

@@ -0,0 +1,33 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "RuleWaiver",
+  "type": "object",
+  "required": [
+    "rule_id",
+    "reason",
+    "owner",
+    "expires"
+  ],
+  "properties": {
+    "rule_id": {
+      "type": "string"
+    },
+    "reason": {
+      "type": "string"
+    },
+    "owner": {
+      "type": "string"
+    },
+    "expires": {
+      "type": "string",
+      "format": "date"
+    },
+    "risk": {
+      "enum": [
+        "low",
+        "medium",
+        "high"
+      ]
+    }
+  }
+}

package/scripts/build-index.mjs

@@ -0,0 +1,178 @@
+#!/usr/bin/env node
+/**
+ * Regenerate the files derived from the rule registry:
+ *   rules/README.md              — the index
+ *   compliance/COVERAGE.md       — counts
+ *   compliance/TRACEABILITY.md   — rule → source → validation matrix
+ *
+ * Run `npm run build:index` after adding or changing a rule. CI checks the result is current.
+ */
+import path from "node:path";
+import process from "node:process";
+import { loadRules, ruleStats } from "../src/lib/rules.mjs";
+import { packageRoot, writeFile, read } from "../src/lib/fs.mjs";
+
+const check = process.argv.includes("--check");
+const rulesDir = path.join(packageRoot, "rules");
+const { rules, errors } = loadRules(rulesDir);
+
+if (errors.length) {
+  console.error("cannot build the index while rules are invalid:");
+  for (const e of errors) console.error(" -", e);
+  process.exit(1);
+}
+
+const GROUPS = [
+  ["Agent discipline", ["agent", "memory"]],
+  ["Engineering", ["architecture", "api", "database", "security", "testing", "devops", "observability", "privacy", "ai"]],
+  ["Design", ["accessibility", "components", "content", "data-display", "design-system", "interaction", "localization", "motion", "responsive", "states", "ui", "ux"]],
+];
+
+function row(r) {
+  const auto = r.validation?.automated ? "yes" : "no";
+  return `| [${r.id}](${r.file}) | ${r.title} | ${r.severity} | ${r.priority} | ${r.domain} | ${auto} | ${r.status} |`;
+}
+
+function index() {
+  const stats = ruleStats(rules);
+  const out = [];
+  out.push("# Rules registry");
+  out.push("");
+  out.push("Machine-readable rules with stable IDs. Narrative guidance lives under");
+  out.push("[`standard/`](../standard/README.md); these files are what agents and reviews cite.");
+  out.push("");
+  out.push("Severity is the obligation (`MUST` · `MUST NOT` · `SHOULD` · `MAY`).");
+  out.push("Priority is when it blocks (`P0` · `P1` · `P2` · `P3` — see [`MATURITY.md`](../MATURITY.md)).");
+  out.push("");
+  out.push("> Generated by `npm run build:index`. Edit the rule files, not this page.");
+  const seen = new Set();
+  for (const [label, domains] of GROUPS) {
+    const group = rules.filter((r) => domains.includes(r.domain));
+    if (!group.length) continue;
+    out.push("");
+    out.push(`## ${label}`);
+    out.push("");
+    out.push("| ID | Title | Severity | Priority | Domain | Auto | Status |");
+    out.push("|---|---|---|---|---|---|---|");
+    for (const r of group) {
+      out.push(row(r));
+      seen.add(r.id);
+    }
+  }
+  const rest = rules.filter((r) => !seen.has(r.id));
+  if (rest.length) {
+    out.push("");
+    out.push("## Other");
+    out.push("");
+    out.push("| ID | Title | Severity | Priority | Domain | Auto | Status |");
+    out.push("|---|---|---|---|---|---|---|");
+    for (const r of rest) out.push(row(r));
+  }
+  out.push("");
+  out.push(
+    `**Total:** ${stats.total} rules · ${stats.active} active · ${stats.automatable} automatable · schema v1`
+  );
+  out.push("");
+  out.push("Lifecycle and supersession: [`LIFECYCLE.md`](LIFECYCLE.md).");
+  out.push("");
+  return out.join("\n");
+}
+
+function coverage() {
+  const s = ruleStats(rules);
+  const out = [];
+  out.push("# Coverage");
+  out.push("");
+  out.push("> Generated by `npm run build:index`.");
+  out.push("");
+  out.push("| Metric | Value |");
+  out.push("|---|---|");
+  out.push(`| Rules total | ${s.total} |`);
+  out.push(`| Active | ${s.active} |`);
+  for (const sev of ["MUST", "MUST NOT", "SHOULD", "MAY"]) {
+    if (s.severity[sev]) out.push(`| ${sev} | ${s.severity[sev]} |`);
+  }
+  for (const p of ["P0", "P1", "P2", "P3"]) {
+    if (s.priority[p]) out.push(`| ${p} | ${s.priority[p]} |`);
+  }
+  out.push(`| Automatable | ${s.automatable} |`);
+  out.push(`| Domains | ${Object.keys(s.domain).length} |`);
+  out.push("");
+  out.push("## By domain");
+  out.push("");
+  out.push("| Domain | Rules | P0 |");
+  out.push("|---|---|---|");
+  for (const d of Object.keys(s.domain).sort()) {
+    const p0 = rules.filter((r) => r.domain === d && r.priority === "P0").length;
+    out.push(`| ${d} | ${s.domain[d]} | ${p0} |`);
+  }
+  out.push("");
+  out.push(
+    "A domain with rules and no automatable check is not a failure — it is a backlog item for [`LEVELS.md`](../LEVELS.md) level 2."
+  );
+  out.push("");
+  return out.join("\n");
+}
+
+function traceability() {
+  const out = [];
+  out.push("# Traceability");
+  out.push("");
+  out.push("Every rule maps down to something a human or a machine can check.");
+  out.push("");
+  out.push("```text");
+  out.push("Rule ID");
+  out.push("   ↓");
+  out.push("Authoritative source (REFERENCES.md)");
+  out.push("   ↓");
+  out.push("Success criterion (when the source has one)");
+  out.push("   ↓");
+  out.push("Guidance in standard/");
+  out.push("   ↓");
+  out.push("Checklist item");
+  out.push("   ↓");
+  out.push("Automated check or recorded manual review");
+  out.push("```");
+  out.push("");
+  out.push("> Generated by `npm run build:index`.");
+  out.push("");
+  out.push("| Rule | Domain | Severity | Priority | Source | Criteria | Validation |");
+  out.push("|---|---|---|---|---|---|---|");
+  for (const r of rules) {
+    const v = [];
+    if (r.validation?.automated) v.push("automated");
+    if (r.validation?.manual) v.push("manual");
+    const sc = Array.isArray(r.success_criteria) && r.success_criteria.length
+      ? r.success_criteria.join(", ")
+      : "—";
+    out.push(
+      `| [${r.id}](../rules/${r.file}) | ${r.domain} | ${r.severity} | ${r.priority} | ${(r.source || []).join(", ")} | ${sc} | ${v.join(" + ") || "—"} |`
+    );
+  }
+  out.push("");
+  return out.join("\n");
+}
+
+const targets = [
+  [path.join(packageRoot, "rules", "README.md"), index()],
+  [path.join(packageRoot, "compliance", "COVERAGE.md"), coverage()],
+  [path.join(packageRoot, "compliance", "TRACEABILITY.md"), traceability()],
+];
+
+let stale = 0;
+for (const [file, content] of targets) {
+  const rel = path.relative(packageRoot, file).split(path.sep).join("/");
+  if (check) {
+    const current = (read(file) ?? "").replace(/\r\n/g, "\n");
+    if (current !== content) {
+      console.error(`stale: ${rel} — run \`npm run build:index\``);
+      stale++;
+    }
+  } else {
+    writeFile(file, content);
+    console.log(`wrote ${rel}`);
+  }
+}
+
+if (check && stale) process.exit(1);
+if (check) console.log(`generated files are current (${rules.length} rules)`);

package/scripts/validate-links.mjs

@@ -0,0 +1,43 @@
+#!/usr/bin/env node
+/** Every relative markdown link in this repository must resolve to a file that exists. */
+import fs from "node:fs";
+import path from "node:path";
+import process from "node:process";
+import { packageRoot, walk } from "../src/lib/fs.mjs";
+
+const linkRe = /\[[^\]]*\]\(([^)\s]+)(?:\s+"[^"]*")?\)/g;
+
+// `templates/` is written into a project, where its links resolve against `.devia/`.
+// Those are checked against a materialised project in tests/cli.test.mjs instead.
+const skipDirs = new Set([".git", "node_modules", ".devia", "templates"]);
+
+const files = walk(packageRoot, {
+  filter: (rel) => rel.endsWith(".md"),
+  skip: (rel) => skipDirs.has(rel.split(path.sep)[0]),
+});
+
+let broken = 0;
+let checked = 0;
+
+for (const rel of files) {
+  const file = path.join(packageRoot, rel);
+  const text = fs.readFileSync(file, "utf8");
+  let m;
+  while ((m = linkRe.exec(text))) {
+    const target = m[1].split("#")[0].split("?")[0];
+    if (!target) continue;
+    if (/^(https?:|mailto:|tel:)/.test(target)) continue;
+    checked++;
+    const resolved = path.resolve(path.dirname(file), target);
+    if (!fs.existsSync(resolved)) {
+      console.error(`broken link  ${rel.split(path.sep).join("/")} -> ${target}`);
+      broken++;
+    }
+  }
+}
+
+if (broken) {
+  console.error(`validate-links FAILED: ${broken} broken of ${checked}`);
+  process.exit(1);
+}
+console.log(`validate-links OK: ${checked} links in ${files.length} files`);

package/scripts/validate-rules.mjs

@@ -0,0 +1,42 @@
+#!/usr/bin/env node
+/**
+ * Validate the rule registry against `schema/rule.schema.json` and the invariants the schema
+ * cannot express: unique ids, filename equals id, directory equals domain, superseded rules
+ * pointing at a rule that exists.
+ */
+import path from "node:path";
+import process from "node:process";
+import { loadRules, ruleStats } from "../src/lib/rules.mjs";
+import { packageRoot, readJSON } from "../src/lib/fs.mjs";
+
+const schema = readJSON(path.join(packageRoot, "schema", "rule.schema.json"));
+if (!schema) {
+  console.error("schema/rule.schema.json is missing or invalid JSON");
+  process.exit(1);
+}
+
+const { rules, errors } = loadRules(path.join(packageRoot, "rules"));
+const ids = new Set(rules.map((r) => r.id));
+
+for (const r of rules) {
+  for (const key of schema.required || []) {
+    if (r[key] === undefined || r[key] === null) errors.push(`${r.file}: missing ${key}`);
+  }
+  if (r.status === "superseded" && !ids.has(r.superseded_by)) {
+    errors.push(`${r.file}: superseded rules must name an existing superseded_by`);
+  }
+  if (r.validation && !r.validation.automated && !r.validation.manual) {
+    errors.push(`${r.file}: a rule with no validation at all cannot be enforced`);
+  }
+}
+
+if (errors.length) {
+  console.error("validate-rules FAILED:");
+  for (const e of errors) console.error(" -", e);
+  process.exit(1);
+}
+
+const s = ruleStats(rules);
+console.log(
+  `validate-rules OK: ${s.total} rules · ${s.priority.P0 || 0} P0 · ${s.automatable} automatable · ${Object.keys(s.domain).length} domains`
+);

package/skills/devia/SKILL.md

@@ -0,0 +1,114 @@
+---
+name: devia
+description: >-
+  Project memory and engineering standard. Use at the START of any work on a repository:
+  initialise or read .devia/, follow the rules it pins, and update it in the same change.
+  Triggers on starting work in an unfamiliar repo, "init devia", memory or standard questions,
+  and before claiming anything is done or production ready.
+---
+
+# devia
+
+A repository worth working on has a memory. `.devia/` is that memory, and this skill is how you
+use it.
+
+## Step 1 — is there a memory?
+
+```bash
+ls .devia
+```
+
+**No `.devia/`** → initialise before writing any code:
+
+```bash
+npx devia init
+```
+
+Then fill `.devia/00_OVERVIEW.md` from what the repository actually contains — stack, modules,
+where the truth lives. Read the code to fill it; do not invent it. This is not paperwork: it is
+the difference between a task and a guess (`AGT-002`).
+
+**`.devia/` exists** → read, in this order:
+
+1. `.devia/AGENTS.md` — the contract for this repository
+2. `.devia/10_NEVER_ALWAYS.md` — what this project has already banned
+3. `.devia/00_OVERVIEW.md` — what this project is
+4. The memory file for the surface you are about to touch (`.devia/14_INDEX.md`)
+
+## Step 2 — work under the rules
+
+The rules are pinned in `.devia/standard/rules/` with stable IDs. The ones that stop most bad
+changes:
+
+| If you are about to… | Rule |
+|---|---|
+| Guess an endpoint, field, config key or business rule | `AGT-004` — do not. Ask, or record a gap |
+| Encode an undecided policy | `MEM-001` — declare it and open a gap |
+| Notice something broken you are not fixing | `MEM-002` — open a debt line |
+| Refactor beyond the request | `AGT-003` — do not |
+| Skip a hook or disable a test | `OPS-003`, `TST-003` — do not |
+| Read user data on the server | `SEC-001`, `SEC-005` — authorize, scope, test it |
+| Accept input from anywhere | `SEC-003` — validate at the boundary |
+| Change the schema | `DB-001`, `DB-002` — versioned migration, never edit an applied one |
+| Ship a screen | `A11Y-001`, `A11Y-004`, `A11Y-006`, `UX-007`, `UI-004`, `STATE-002` |
+| Say "done" | `AGT-005`, `AGT-006` — name the checks, name what is unverified |
+
+Look one up:
+
+```bash
+npx devia rules --id SEC-001
+npx devia rules --domain database --priority P0
+```
+
+## Step 3 — update the memory in the same change
+
+`.devia/impact-map.yaml` maps what you changed to the memory files that must change with it
+(`MEM-009`). New endpoint → `02_SURFACES.md`. New table → `03_DATA_MODEL.md`. Permission change
+→ `04_PERMISSIONS.md`.
+
+Registries:
+
+```bash
+npx devia gap add "Should invoices round per line or per total?"
+npx devia debt add "Refund endpoint has no idempotency key (API-004)"
+```
+
+Never delete a gap or debt line you did not discharge (`MEM-011`).
+
+## Step 4 — verify, then report
+
+```bash
+npx devia validate     # memory integrity: structure, registries, placeholders
+npx devia check        # readiness gates — P0 failures block
+npx devia doctor       # is the memory older than the code?
+```
+
+Report with:
+
+```text
+## Devia compliance
+- Memory read: ...
+- Rules applied (IDs): ...
+- P0 status: ...
+- Checks run / NOT run: ...
+- .devia updated: ...
+- Registries: gaps / debt touched
+- Not verified: ...
+```
+
+For a non-trivial change, "Not verified" is never empty.
+
+## Installing the contract for other agents
+
+`devia init` writes the adapters: `AGENTS.md` (universal), `CLAUDE.md`,
+`.cursor/rules/devia.mdc`, `.github/copilot-instructions.md`, `.windsurfrules`. To refresh them
+later:
+
+```bash
+npx devia skills install --agent all
+```
+
+## What this skill is not
+
+It is not a code generator, and it is not a substitute for reading the repository. It is the
+discipline that makes reading the repository unnecessary a second time.