@schneiderjoseph/devia 0.2.0 → 0.4.0

package/CHANGELOG.md

@@ -1,5 +1,64 @@
 # Changelog
 
+## 0.4.0 — 2026-09-09
+
+The standard is unchanged: `VERSION` stays at 0.1.0, no adopter needs `devia sync`.
+
+### A manifest is not always at the root
+
+Running `devia init` on a real project for the first time — a Next.js app whose manifest lives
+in `apps/web/` — exposed five gates reporting `SKIP  no package.json` to a repository that has
+one, with a lockfile, a lint script and thirteen dependencies. The letter of the rule was kept,
+since nothing was rounded up to `PASS`; the reason given was false, which is worse. A reader
+believes the tool looked.
+
+- `check` reads every `package.json` in the repository, nearest the root first, and takes the
+  union of their dependencies: "does this project use X" is not a question about one directory
+- A lockfile is looked for next to each manifest, not only at the root
+- A migrations directory is found at any depth
+- `SKIP` now says `no package.json anywhere in the repository`, and findings name the file they
+  came from — `no npm test script in apps/web/package.json`
+- `init` detects the profile from the nearest manifest instead of falling back to a default, and
+  records the directories holding manifests in `code.paths`, which is what `doctor` watches for
+  staleness
+
+On that project: six SKIPs became two, four gates turned into real findings, and the dependency
+lockfile went from invisible to `PASS  apps/web/package-lock.json`.
+
+- G1 closed and reframed: the blind spot was never the ecosystem, it was the root assumption.
+  D9 records what is still root-only: `pyproject.toml`, `go.mod`, `Cargo.toml`
+- G7 opened: what devia should do when a repository already carries an ad-hoc memory of its own
+
+### Fixed
+
+- Nested directories were not excluded from the scan on Windows when git was unavailable: the
+  separator class only matched `/`, so `apps/web/node_modules` was walked. Both separators now.
+
+## 0.3.0 — 2026-09-09
+
+The standard is unchanged: `VERSION` stays at 0.1.0, no adopter needs `devia sync`.
+
+### devia is for every agent
+
+0.2.0 shipped `--global` serving Claude Code alone and reported the other agents as SKIP. Two of
+those reasons were wrong: they came from an absence never verified. `~/.cursor/rules/` holds
+user-level `.mdc` rules, and `~/.codex/skills/` uses the same `SKILL.md` convention as Claude
+Code. The decision is recorded as G6: no agent is privileged.
+
+`devia skills install --global` now writes, each in the format the agent actually reads:
+
+| Agent | Path | File |
+|---|---|---|
+| Claude Code | `~/.claude/skills/devia/SKILL.md` | skill pack |
+| Codex | `~/.codex/skills/devia/SKILL.md` | skill pack |
+| Cursor | `~/.cursor/rules/devia.mdc` | rules adapter |
+| Gemini | `~/.gemini/GEMINI.md` | universal contract, only when absent or empty |
+| Copilot, Windsurf | — | `SKIP`: user-level configuration is editor settings, not a file devia can place (`12_DEBT.md` D8) |
+
+`CLAUDE_CONFIG_DIR` and `CODEX_HOME` are honoured when set. A directory the agent owns is
+written to freely; a file the **user** owns is written only when absent or empty, and otherwise
+skipped with the reason rather than replaced. `--force` overrides both and names every path.
+
 ## 0.2.0 — 2026-09-09
 
 The standard is unchanged: `VERSION` stays at 0.1.0 and no adopter needs `devia sync`. This

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@schneiderjoseph/devia",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "description": "One standard, one memory: engineering and design rules plus living project memory for AI coding agents",
   "type": "module",
   "license": "MIT",

package/src/commands/check.mjs

@@ -59,7 +59,9 @@ const TEXT_EXT = new Set([
  * secret scan that silently scanned nothing is worse than one that over-reports.
  */
 function sourceFiles(root) {
-  const skipped = (rel) => rel.split(/[\/]/).some((seg) => SKIP_DIRS.has(seg));
+  // Both separators: git reports "/", walk() reports path.sep, and a nested node_modules must be
+  // skipped in either shape.
+  const skipped = (rel) => rel.split(/[\\/]/).some((seg) => SKIP_DIRS.has(seg));
   const wanted = (rel) => TEXT_EXT.has(path.extname(rel).toLowerCase());
 
   const tracked = trackedFiles(root);
@@ -81,13 +83,31 @@ function anyExists(root, candidates) {
 }
 
 function makeChecks(root, ctx) {
-  const pkg = readJSON(path.join(root, "package.json"));
-  const scripts = pkg?.scripts || {};
-  const deps = { ...(pkg?.dependencies || {}), ...(pkg?.devDependencies || {}) };
   const config = readJSON(path.join(root, ".devia", "devia.json"));
   const files = sourceFiles(root);
   const rel = (p) => p.split(path.sep).join("/");
 
+  /**
+   * A manifest is not always at the repository root: `apps/web/package.json` is as real as
+   * `./package.json`. Reading only the root turned "I did not look there" into "you have no
+   * package.json", which is a wrong answer dressed as a SKIP — worse than no answer, because
+   * the reader believes the tool looked.
+   */
+  const manifests = files
+    .filter((f) => /(^|[\\/])package\.json$/.test(f))
+    .sort((a, b) => a.split(path.sep).length - b.split(path.sep).length || a.localeCompare(b));
+  const primary = manifests[0] || null;
+  const pkg = primary ? readJSON(path.join(root, primary)) : null;
+  const pkgWhere = primary ? rel(primary) : null;
+  const scripts = pkg?.scripts || {};
+  // Dependencies are asked as "does this project use X anywhere", so every manifest counts.
+  const deps = {};
+  for (const m of manifests) {
+    const json = readJSON(path.join(root, m)) || {};
+    Object.assign(deps, json.dependencies, json.devDependencies);
+  }
+  const noManifest = `no package.json anywhere in the repository`;
+
   const hasDep = (...names) => names.some((n) => n in deps);
   const grepFiles = (re, limit = 40) => {
     const hits = [];
@@ -305,12 +325,13 @@ function makeChecks(root, ctx) {
       rule: "TST-001",
       title: "A test command exists",
       run: () => {
-        if (!pkg) return { kind: "SKIP", detail: "no package.json" };
+        if (!pkg) return { kind: "SKIP", detail: noManifest };
         const t = scripts.test;
-        if (!t) return { kind: "WARN", detail: "no npm test script" };
+        const where = pkgWhere === "package.json" ? "" : ` in ${pkgWhere}`;
+        if (!t) return { kind: "WARN", detail: `no npm test script${where}` };
         return /no test specified/.test(t)
-          ? { kind: "FAIL", detail: "test script is the npm placeholder" }
-          : { kind: "PASS" };
+          ? { kind: "FAIL", detail: `test script is the npm placeholder${where}` }
+          : { kind: "PASS", detail: where.trim() };
       },
     },
     {
@@ -319,9 +340,7 @@ function makeChecks(root, ctx) {
       rule: "OPS-004",
       title: "Dependency lockfile committed",
       run: () => {
-        const manifests = ["package.json", "pyproject.toml", "go.mod", "Cargo.toml", "Gemfile"];
-        if (!anyExists(root, manifests)) return { kind: "SKIP", detail: "no manifest" };
-        const lock = anyExists(root, [
+        const LOCKS = [
           "package-lock.json",
           "pnpm-lock.yaml",
           "yarn.lock",
@@ -331,10 +350,23 @@ function makeChecks(root, ctx) {
           "go.sum",
           "Cargo.lock",
           "Gemfile.lock",
+        ];
+        // A lockfile sits next to the manifest it locks, which is not always the root.
+        const dirs = new Set(["."]);
+        for (const m of manifests) dirs.add(path.dirname(m));
+        const rootManifest = anyExists(root, [
+          "package.json",
+          "pyproject.toml",
+          "go.mod",
+          "Cargo.toml",
+          "Gemfile",
         ]);
-        return lock
-          ? { kind: "PASS", detail: lock }
-          : { kind: "FAIL", detail: "no lockfile" };
+        if (!rootManifest && !manifests.length) return { kind: "SKIP", detail: "no manifest" };
+        for (const dir of dirs) {
+          const found = LOCKS.find((l) => exists(path.join(root, dir, l)));
+          if (found) return { kind: "PASS", detail: rel(path.join(dir, found)) };
+        }
+        return { kind: "FAIL", detail: "no lockfile" };
       },
     },
     {
@@ -355,8 +387,14 @@ function makeChecks(root, ctx) {
           "alembic",
           path.join("src", "migrations"),
         ]);
-        return dir
-          ? { kind: "PASS", detail: dir }
+        if (dir) return { kind: "PASS", detail: dir };
+        // Not only at the root: a migrations directory can live under any package.
+        const SEGMENTS = new Set(["migrations", "migrate", "alembic"]);
+        const nested = files
+          .map(rel)
+          .find((f) => f.split("/").slice(0, -1).some((seg) => SEGMENTS.has(seg)));
+        return nested
+          ? { kind: "PASS", detail: nested.split("/").slice(0, -1).join("/") }
           : { kind: "FAIL", detail: "database in use, no migrations directory" };
       },
     },
@@ -388,7 +426,7 @@ function makeChecks(root, ctx) {
       run: () => {
         if (config && config.modules && config.modules.design === false)
           return { kind: "SKIP", detail: "design module disabled" };
-        if (!pkg) return { kind: "SKIP", detail: "no package.json" };
+        if (!pkg) return { kind: "SKIP", detail: noManifest };
         const found = hasDep(
           "axe-core", "@axe-core/react", "@axe-core/playwright", "jest-axe",
           "eslint-plugin-jsx-a11y", "pa11y", "@storybook/addon-a11y", "lighthouse"
@@ -407,7 +445,7 @@ function makeChecks(root, ctx) {
         const profile = config?.project?.profile;
         if (["cli", "library", "docs"].includes(profile))
           return { kind: "SKIP", detail: `${profile} does not run as a watched service` };
-        if (!pkg) return { kind: "SKIP", detail: "no package.json" };
+        if (!pkg) return { kind: "SKIP", detail: noManifest };
         const found = hasDep("@sentry/node", "@sentry/browser", "@sentry/nextjs", "bugsnag",
           "rollbar", "datadog-lambda-js", "dd-trace", "@opentelemetry/api");
         return found

package/src/commands/init.mjs

@@ -1,6 +1,7 @@
 import fs from "node:fs";
 import path from "node:path";
 import { packageRoot, exists, read, writeFile, writeJSON, walk } from "../lib/fs.mjs";
+import { trackedFiles } from "../lib/git.mjs";
 import { cliVersion, standardVersion } from "../lib/version.mjs";
 import { vendorStandard } from "../lib/vendor.mjs";
 import { color, heading, status, line } from "../lib/ui.mjs";
@@ -15,10 +16,22 @@ const PROFILES = {
   docs: "Documentation or content repository",
 };
 
+/**
+ * Every package.json in the repository, nearest to the root first. A monorepo keeps its real
+ * manifest in `apps/web/` or `packages/*`, and a profile detected from the root alone falls back
+ * to a default while the evidence sits one directory down.
+ */
+function findManifests(root) {
+  const tracked = trackedFiles(root);
+  if (!tracked) return exists(path.join(root, "package.json")) ? ["package.json"] : [];
+  return tracked
+    .filter((f) => /(^|\/)package\.json$/.test(f) && !f.includes("node_modules/"))
+    .sort((a, b) => a.split("/").length - b.split("/").length || a.localeCompare(b));
+}
+
 function detectProfile(root) {
-  const pkg = path.join(root, "package.json");
-  if (exists(pkg)) {
-    const json = JSON.parse(read(pkg) || "{}");
+  for (const manifest of findManifests(root)) {
+    const json = JSON.parse(read(path.join(root, manifest)) || "{}");
     const deps = { ...json.dependencies, ...json.devDependencies };
     if (json.bin) return "cli";
     if (deps.next || deps.react || deps.vue || deps.svelte || deps["@angular/core"])
@@ -46,8 +59,14 @@ function detectName(root) {
 }
 
 function detectCodePaths(root) {
-  const candidates = ["src", "app", "lib", "packages", "server", "api", "web", "components"];
-  return candidates.filter((c) => exists(path.join(root, c)));
+  const candidates = ["src", "app", "apps", "lib", "packages", "server", "api", "web", "components"];
+  const found = candidates.filter((c) => exists(path.join(root, c)));
+  // The directory holding a manifest is code by definition, wherever it sits.
+  for (const manifest of findManifests(root)) {
+    const dir = path.posix.dirname(manifest);
+    if (dir !== "." && !found.some((f) => dir === f || dir.startsWith(`${f}/`))) found.push(dir);
+  }
+  return found;
 }
 
 function fill(text, vars) {

package/src/commands/skills.mjs

@@ -38,57 +38,84 @@ export function installAdapters(root, { force = false, agents = Object.keys(ADAP
   return { written, kept };
 }
 
+const SKILL_PACK = path.join("skills", "devia", "SKILL.md");
+const adapter = (file) => path.join("templates", "agents", file);
+
 /**
- * Where an agent keeps skills for every project, not one.
+ * Where each agent keeps a contract that applies to every project, not one.
  *
- * Only agents whose user-level location devia can actually determine are listed. The rest are
- * reported as SKIP with the reason: guessing a path in someone's home directory and writing to
- * it is exactly the kind of confident wrong answer this tool exists to prevent.
+ * devia is for every agent, so an agent is listed here as soon as its user-level location is
+ * known — and reported as SKIP with the reason when it is not. Each entry carries the file the
+ * agent actually reads: a skill pack where the agent loads skills, its own rules format
+ * otherwise. Guessing a path inside someone's home directory is the confident wrong answer this
+ * tool exists to prevent, so absence of evidence is reported, never rounded up.
  */
-function globalSkillTargets() {
+function globalTargets() {
   const home = os.homedir();
-  const claudeDir = process.env.CLAUDE_CONFIG_DIR
-    ? path.resolve(process.env.CLAUDE_CONFIG_DIR)
-    : path.join(home, ".claude");
+  const configDir = (envVar, fallback) =>
+    process.env[envVar] ? path.resolve(process.env[envVar]) : path.join(home, fallback);
+
   return {
     claude: {
-      target: path.join(claudeDir, "skills", "devia", "SKILL.md"),
+      target: path.join(configDir("CLAUDE_CONFIG_DIR", ".claude"), "skills", "devia", "SKILL.md"),
+      source: SKILL_PACK,
+    },
+    codex: {
+      target: path.join(configDir("CODEX_HOME", ".codex"), "skills", "devia", "SKILL.md"),
+      source: SKILL_PACK,
     },
     cursor: {
-      reason: "no user-level skill directory — use the per-project .cursor/rules/devia.mdc",
+      target: path.join(home, ".cursor", "rules", "devia.mdc"),
+      source: adapter("cursor.mdc"),
+    },
+    gemini: {
+      // One file the user owns, not a directory devia can add to: written only when it is
+      // absent or empty, so a global instruction file is never silently replaced.
+      target: path.join(home, ".gemini", "GEMINI.md"),
+      source: adapter("AGENTS.md"),
+      onlyWhenEmpty: true,
     },
     copilot: {
-      reason: "instructions are per-repository — .github/copilot-instructions.md",
+      reason: "user-level instructions live in the editor's settings, not a file devia can place",
     },
     windsurf: {
-      reason: "rules are per-repository — .windsurfrules",
+      reason: "no user-level rules file — .windsurfrules is per repository",
     },
   };
 }
 
 /**
- * Install the skill once for every project. This is the only path that writes outside `--root`,
- * it happens only behind `--global`, and it prints every path it touches (04_PERMISSIONS.md).
+ * Install the contract once for every project. This is the only path that writes outside
+ * `--root`: it happens behind `--global`, and it prints every path it touches
+ * (`04_PERMISSIONS.md`).
  */
 export function installGlobalSkill({ force = false } = {}) {
-  const skill = read(path.join(packageRoot, "skills", "devia", "SKILL.md"));
   const written = [];
   const kept = [];
   const skipped = [];
-  for (const [key, entry] of Object.entries(globalSkillTargets())) {
+
+  for (const [key, entry] of Object.entries(globalTargets())) {
     if (!entry.target) {
       skipped.push([key, entry.reason]);
       continue;
     }
-    if (skill === null) {
-      skipped.push([key, "skill pack missing from the installed package"]);
+    const content = read(path.join(packageRoot, entry.source));
+    if (content === null) {
+      skipped.push([key, `${entry.source} missing from the installed package`]);
       continue;
     }
     if (exists(entry.target) && !force) {
-      kept.push([key, entry.target]);
-      continue;
+      const current = read(entry.target) || "";
+      if (entry.onlyWhenEmpty && current.trim()) {
+        skipped.push([key, `${path.basename(entry.target)} already has content — add the contract yourself`]);
+        continue;
+      }
+      if (current.trim()) {
+        kept.push([key, entry.target]);
+        continue;
+      }
     }
-    writeFile(entry.target, skill);
+    writeFile(entry.target, content);
     written.push([key, entry.target]);
   }
   return { written, kept, skipped };