@metaobjectsdev/sdk 0.15.4 → 0.15.5

package/agent-context/skills/metaobjects-verify/SKILL.md

@@ -98,6 +98,29 @@ So even in a Java or Python or C# project, schema migration and `verify --db` ru
 through the Node `meta` tool. The per-port `gen`/codegen tooling stays native to
 the language; only schema crosses to Node.
 
+## Never hand-edit the live database — apply schema only through the tool
+
+The live schema is a derived artifact, exactly like generated code. **Do not mutate a running
+database by hand** — no `psql`/console `ALTER TABLE` / `CREATE` / `DROP`, not to preview a column, not
+to patch a mismatch, not to "just unblock" a boot. It is the single most common way a database ends up
+in a state no migration can reproduce:
+
+- The column now exists but no migration recorded it, so the next `meta migrate` (or a JVM app's
+  boot-time migrator) tries to add it again and dies on `column ... already exists` — or worse,
+  silently diverges and the drift only surfaces days later.
+- "I'll just add it real quick so I can see it in the tool" is the exact rationalization to catch. It
+  doesn't *feel* like a schema change, so it skips the metadata-first check — but it is one.
+
+Apply every schema change the same way: change the metadata, then let `meta migrate` (or, for a
+project still driving its own migrator, a migration authored *to match* the regenerated schema) apply
+it. Want to see a new column in a tool or an app? Apply the migration and re-read — never reach for
+`psql`.
+
+**Make `meta verify --db` a done-check, not just a CI gate.** Run it after any work that touched the
+database or the schema-shaping metadata, before you consider the task finished — it introspects the
+live DB against the metadata and fails on exactly this drift (a hand-added column, a missing index, a
+mismatched type), catching a manual poke immediately instead of at the next boot.
+
 ## Interpreting conformance / test failures
 
 MetaObjects' behavior is pinned by cross-port **conformance corpora** (metamodel,

package/agent-context/templates/always-on.md.mustache

@@ -7,6 +7,7 @@ spine; generated code is the disposable artifact. Regenerate with `{{codegenComm
 
 ## Principles
 - Pattern-derivable from metadata = codegen, never hand-write — FKs, CRUD, validators, finders, and the database schema and migrations. The schema is a disposable, generated artifact: change the metadata and regenerate, never hand-write SQL.
+- The **live database** is a derived artifact too — never hand-apply a schema change to a running DB (ad-hoc `psql`/console `ALTER`/`CREATE`/`DROP`), not even to preview a column or unblock a boot. Apply schema only through `meta migrate` (metadata → DDL). A hand-applied change drifts the live DB from the metadata + migration history and collides at the next migrate/boot ("column already exists") — a state no migration can reproduce. Run `meta verify --db` after any DB-touching work to catch that drift early.
 - Never hand-edit generated files — change the metadata and regenerate (three-way merge preserves hand-written regions).
 - Use the generated constants for any string that names metadata.
 - The loaded metadata model is READ-ONLY — never inject nodes or mutate the tree at load time (no "enrich the model on load" hooks). Need an extra field/column? Author it in the metadata, or derive it during codegen (read the metadata, emit output). Mutating the loaded model makes it diverge from what's declared — a bad practice reserved for very rare cases.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@metaobjectsdev/sdk",
-  "version": "0.15.4",
+  "version": "0.15.5",
   "description": "Workspace helpers and agent-docs utilities for MetaObjects projects.",
   "type": "module",
   "main": "./dist/index.js",
@@ -56,7 +56,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@metaobjectsdev/metadata": "0.15.4",
+    "@metaobjectsdev/metadata": "0.15.5",
     "zod": "^3.23.0"
   },
   "devDependencies": {