docs(agent-context): propagate ADR-0037 vocabulary-expansion framework into adopter surfaces (#125)

Translate the metamodel vocabulary-expansion decision framework (ADR-0037) into the
three adopter-facing agent-context surfaces so every app using MetaObjects makes
consistent subtype-vs-attribute-vs-@dbColumnType authoring calls.

- metaobjects-authoring SKILL: new "Choosing the right field shape" section — the
  ordered test (derivable -> derive; physical-only -> @dbColumnType; logical: different
  native type -> subtype, same kind + modifier -> attribute) + a canonical-form table
  for common needs (uuid/currency/enum/timestamp/isArray/string/object/jsonb) + a
  custom-provider "apply ADR-0037" pointer.
- metaobjects-codegen SKILL: brief reference to the authoring guidance + ADR-0037
  pointer in the dialect/column-mapping section ("author the shape right, don't hack
  the template").
- metaobjects-audit SKILL: new advisory axis I "Vocabulary hygiene / modernization" —
  flags retired forms (uuid_array/text_array -> isArray, @kind:text hack -> bare
  field.string, @dbColumnType:uuid -> field.uuid) and checks custom-provider vocab
  against ADR-0037; non-failing, scored as modernization opportunities; carries a
  clearly-marked Wave-2/3 TODO list.

Grounding-safe: examples use only currently-registered vocab. Wave-2/3 spots are marked
with TODO(ADR-0036 Wave 2/3) comments. The planned @localTime/@relationName attrs the
audit skill names in its forward TODO are added to the grounding test's deliberately-
named exemption set.

Regenerated the 12 agent-context conformance fixtures (4 stacks x 3 skills). All
agent-context conformance + drift + capability-grounding tests green (13/13).


Claude-Session: https://claude.ai/code/session_01GF9xLEQZaPus5Y6opk398n

Co-authored-by: Doug Mealing <noreply@anthropic.com>

Author: dmealing

agent-context/skills/metaobjects-audit/SKILL.md

@@ -80,10 +80,53 @@ code behind a grep hit; a "duplicate" validator's *divergence* is the finding.
   in committed canonical JSON (ADR-0032); DB-type-as-logical-subtype (ADR-0013); per-port
   migration engine where schema is Node-`meta`-owned (ADR-0015).
 
+- [ ] **I. Vocabulary hygiene / modernization (ADVISORY).** Flag already-retired or
+  deprecated authoring patterns and recommend the canonical form (see § Vocabulary
+  hygiene). Advisory severity — scored as modernization opportunities, **never a
+  failing finding**.
+
 **Phase 4 — Synthesize** into the tiered roadmap and populate both artifacts.
 
 ---
 
+## Vocabulary hygiene / modernization (axis I — ADVISORY)
+
+Per ADR-0037, vocabulary expansion follows ONE ordered test (derivable → derive;
+physical-only → `@dbColumnType`; logical: different native type → subtype, same kind +
+modifier → attribute). This axis surfaces authoring that predates or contradicts that
+framework. **All findings here are advisory** — modernization opportunities scored as
+such, surfaced in the roadmap, but **non-failing** (the code works; the form is dated).
+
+**Already-retired / deprecated forms → recommend the canonical form:**
+
+- `@dbColumnType: uuid_array` / `@dbColumnType: text_array` (a physical array column
+  type) → **`isArray: true`** on the base subtype. Array-ness is logical and derivable;
+  the array column type is retired.
+- The `@kind: text` hack (forcing text via a kind override) → **bare `field.string`**
+  (text is the default; no override needed).
+- `@dbColumnType: uuid` where a native UUID type is actually wanted → **`field.uuid`**
+  (a distinct native type is a subtype, not a physical override). Keep `@dbColumnType:
+  uuid` ONLY for the deliberate string-over-uuid-column case.
+
+**Custom-provider vocabulary (adopters who register their own types/attrs):** check
+new/custom vocab against the ADR-0037 procedure (advisory) — e.g. *a custom subtype
+that differs from an existing one only by a property should be an attribute, not a
+subtype*; a string-shape validation (email/url) is an attribute (native type unchanged),
+not a subtype. Recommend re-shaping against the ordered test.
+
+**TODO — Wave-2/3 checks to add when the conventions merge (NOT yet active — these
+tokens are pending ADR-0036 Wave 2/3 and not yet registered; do NOT flag adopters for
+them until merged):**
+
+- `@dbColumnType: timestamp_with_tz` → **drop it** (timezone-aware is the
+  `field.timestamp` default) — *pending Wave 2/3*.
+- A bare wall-clock `field.timestamp` meaning naive/local time → flag for the
+  forthcoming `@localTime` zone-flag attribute — *pending Wave 2/3, not yet active*.
+- An author-supplied regex validating email / url shape → flag for the forthcoming
+  `@format` string-format attribute — *pending Wave 2/3, not yet active*.
+
+---
+
 ## Classification scheme (every surface; classify on codegen AND runtime)
 
 | Class | Meaning | Action |
@@ -183,6 +226,10 @@ one-consumer need, read it codegen-locally.
 Coarse bands only (none / some / most / all). Worst-of within a pillar. On re-run, grade
 the delta. Lead with gaps, not the grade.
 
+**Vocabulary hygiene (axis I) is advisory** — it surfaces as modernization
+opportunities in the roadmap, scored as such, and **never gates a tier or fails the
+audit.** Dated-but-working vocabulary is a quality nudge, not a defect.
+
 ---
 
 ## Report

agent-context/skills/metaobjects-authoring/SKILL.md

@@ -161,6 +161,42 @@ name   package   extends   abstract   overlay   isArray   children   value
 Common field attributes: `@required`, `@maxLength`, `@column` (physical column
 name), `@default`, `@filterable`, `@sortable`.
 
+### Choosing the right field shape
+
+When a need doesn't obviously map to a subtype, run this ordered test (ADR-0037) —
+**the first that matches decides:**
+
+1. **Derivable from what you already have?** → derive it, declare NOTHING new. An
+   array is `isArray: true` (never an array column type); a bounded string is
+   `@maxLength`; FK columns come from `identity.reference`. Don't add vocabulary for
+   something the metadata already implies.
+2. **Pure physical-DB detail, native type unchanged?** → the narrow `@dbColumnType`
+   escape hatch (e.g. an open JSON bag). Used sparingly; not a logical type.
+3. **Logical concept** — a *different kind* of value (its own native type, e.g.
+   UUID, money) → a **subtype**; the *same kind* with a modifier (still a string/
+   decimal, just constrained) → an **attribute** (`@maxLength`, `@precision`).
+
+Canonical form for common needs — reach for these before inventing anything:
+
+| Need | Author it as | Note |
+|---|---|---|
+| IDs / unique keys | `field.uuid` | native UUID; use `@dbColumnType: uuid` only to force a string-typed value over a uuid column on purpose |
+| Money | `field.currency` | integer minor units; never a float |
+| Closed set of symbols | `field.enum` | `@values` required |
+| Instant / timestamp | `field.timestamp` | ISO 8601 with timezone on the wire |
+| A list of anything | `isArray: true` | on the base subtype (e.g. `field.string` + `isArray`) — there is **no** array `@dbColumnType` (retired) |
+| Long / unbounded text | bare `field.string` | add `@maxLength` only when you want `varchar(N)` |
+| Nested structured value | `field.object` | `@objectRef` + `@storage` |
+| Open JSON bag (no fixed shape) | `field.string` + `@dbColumnType: jsonb` | logical type stays string; column is jsonb |
+
+<!-- TODO(ADR-0036 Wave 2/3): add @localTime / @format / @relationName guidance when merged -->
+
+**Extending the metamodel (custom providers):** the same ordered test governs new
+vocabulary you register. A would-be subtype that differs from an existing one only
+by a property is an **attribute**, not a subtype; a string-shape validation
+(email/url) is an attribute, not a subtype (its native type is still `string`).
+Apply ADR-0037 before registering anything.
+
 ### Currency
 
 `field.currency` stores money as **integer minor units** (cents for USD, yen for

agent-context/skills/metaobjects-codegen/SKILL.md

@@ -157,6 +157,15 @@ dialect's column types deterministically (`field.string` + `@maxLength` →
 `varchar(N)`, `field.currency` → integer, `field.uuid` → native `uuid` on
 Postgres, `field.enum` → `varchar` + `CHECK`, etc.).
 
+Codegen only ever maps the **shapes you authored** — so author them right. If you
+find the generator emitting the wrong column type, the fix is the field shape, not a
+template hack. See "Choosing the right field shape" in the **`metaobjects-authoring`**
+skill for the ordered subtype-vs-attribute-vs-`@dbColumnType` test (ADR-0037) — e.g.
+arrays are `isArray: true` (never an array column type) and a native UUID is
+`field.uuid` (not a string + `@dbColumnType`). When you register custom vocabulary
+for a custom generator, the same ADR-0037 procedure decides whether it's a subtype or
+an attribute.
+
 ## Per-target output
 
 Generated code can be routed to **multiple output directories/packages** so each

fixtures/agent-context-conformance/java-kotlin-react-tanstack/expected/.claude/skills/metaobjects-audit/SKILL.md

@@ -80,10 +80,53 @@ code behind a grep hit; a "duplicate" validator's *divergence* is the finding.
   in committed canonical JSON (ADR-0032); DB-type-as-logical-subtype (ADR-0013); per-port
   migration engine where schema is Node-`meta`-owned (ADR-0015).
 
+- [ ] **I. Vocabulary hygiene / modernization (ADVISORY).** Flag already-retired or
+  deprecated authoring patterns and recommend the canonical form (see § Vocabulary
+  hygiene). Advisory severity — scored as modernization opportunities, **never a
+  failing finding**.
+
 **Phase 4 — Synthesize** into the tiered roadmap and populate both artifacts.
 
 ---
 
+## Vocabulary hygiene / modernization (axis I — ADVISORY)
+
+Per ADR-0037, vocabulary expansion follows ONE ordered test (derivable → derive;
+physical-only → `@dbColumnType`; logical: different native type → subtype, same kind +
+modifier → attribute). This axis surfaces authoring that predates or contradicts that
+framework. **All findings here are advisory** — modernization opportunities scored as
+such, surfaced in the roadmap, but **non-failing** (the code works; the form is dated).
+
+**Already-retired / deprecated forms → recommend the canonical form:**
+
+- `@dbColumnType: uuid_array` / `@dbColumnType: text_array` (a physical array column
+  type) → **`isArray: true`** on the base subtype. Array-ness is logical and derivable;
+  the array column type is retired.
+- The `@kind: text` hack (forcing text via a kind override) → **bare `field.string`**
+  (text is the default; no override needed).
+- `@dbColumnType: uuid` where a native UUID type is actually wanted → **`field.uuid`**
+  (a distinct native type is a subtype, not a physical override). Keep `@dbColumnType:
+  uuid` ONLY for the deliberate string-over-uuid-column case.
+
+**Custom-provider vocabulary (adopters who register their own types/attrs):** check
+new/custom vocab against the ADR-0037 procedure (advisory) — e.g. *a custom subtype
+that differs from an existing one only by a property should be an attribute, not a
+subtype*; a string-shape validation (email/url) is an attribute (native type unchanged),
+not a subtype. Recommend re-shaping against the ordered test.
+
+**TODO — Wave-2/3 checks to add when the conventions merge (NOT yet active — these
+tokens are pending ADR-0036 Wave 2/3 and not yet registered; do NOT flag adopters for
+them until merged):**
+
+- `@dbColumnType: timestamp_with_tz` → **drop it** (timezone-aware is the
+  `field.timestamp` default) — *pending Wave 2/3*.
+- A bare wall-clock `field.timestamp` meaning naive/local time → flag for the
+  forthcoming `@localTime` zone-flag attribute — *pending Wave 2/3, not yet active*.
+- An author-supplied regex validating email / url shape → flag for the forthcoming
+  `@format` string-format attribute — *pending Wave 2/3, not yet active*.
+
+---
+
 ## Classification scheme (every surface; classify on codegen AND runtime)
 
 | Class | Meaning | Action |
@@ -183,6 +226,10 @@ one-consumer need, read it codegen-locally.
 Coarse bands only (none / some / most / all). Worst-of within a pillar. On re-run, grade
 the delta. Lead with gaps, not the grade.
 
+**Vocabulary hygiene (axis I) is advisory** — it surfaces as modernization
+opportunities in the roadmap, scored as such, and **never gates a tier or fails the
+audit.** Dated-but-working vocabulary is a quality nudge, not a defect.
+
 ---
 
 ## Report

fixtures/agent-context-conformance/java-kotlin-react-tanstack/expected/.claude/skills/metaobjects-authoring/SKILL.md

@@ -161,6 +161,42 @@ name   package   extends   abstract   overlay   isArray   children   value
 Common field attributes: `@required`, `@maxLength`, `@column` (physical column
 name), `@default`, `@filterable`, `@sortable`.
 
+### Choosing the right field shape
+
+When a need doesn't obviously map to a subtype, run this ordered test (ADR-0037) —
+**the first that matches decides:**
+
+1. **Derivable from what you already have?** → derive it, declare NOTHING new. An
+   array is `isArray: true` (never an array column type); a bounded string is
+   `@maxLength`; FK columns come from `identity.reference`. Don't add vocabulary for
+   something the metadata already implies.
+2. **Pure physical-DB detail, native type unchanged?** → the narrow `@dbColumnType`
+   escape hatch (e.g. an open JSON bag). Used sparingly; not a logical type.
+3. **Logical concept** — a *different kind* of value (its own native type, e.g.
+   UUID, money) → a **subtype**; the *same kind* with a modifier (still a string/
+   decimal, just constrained) → an **attribute** (`@maxLength`, `@precision`).
+
+Canonical form for common needs — reach for these before inventing anything:
+
+| Need | Author it as | Note |
+|---|---|---|
+| IDs / unique keys | `field.uuid` | native UUID; use `@dbColumnType: uuid` only to force a string-typed value over a uuid column on purpose |
+| Money | `field.currency` | integer minor units; never a float |
+| Closed set of symbols | `field.enum` | `@values` required |
+| Instant / timestamp | `field.timestamp` | ISO 8601 with timezone on the wire |
+| A list of anything | `isArray: true` | on the base subtype (e.g. `field.string` + `isArray`) — there is **no** array `@dbColumnType` (retired) |
+| Long / unbounded text | bare `field.string` | add `@maxLength` only when you want `varchar(N)` |
+| Nested structured value | `field.object` | `@objectRef` + `@storage` |
+| Open JSON bag (no fixed shape) | `field.string` + `@dbColumnType: jsonb` | logical type stays string; column is jsonb |
+
+<!-- TODO(ADR-0036 Wave 2/3): add @localTime / @format / @relationName guidance when merged -->
+
+**Extending the metamodel (custom providers):** the same ordered test governs new
+vocabulary you register. A would-be subtype that differs from an existing one only
+by a property is an **attribute**, not a subtype; a string-shape validation
+(email/url) is an attribute, not a subtype (its native type is still `string`).
+Apply ADR-0037 before registering anything.
+
 ### Currency
 
 `field.currency` stores money as **integer minor units** (cents for USD, yen for

fixtures/agent-context-conformance/java-kotlin-react-tanstack/expected/.claude/skills/metaobjects-codegen/SKILL.md

@@ -157,6 +157,15 @@ dialect's column types deterministically (`field.string` + `@maxLength` →
 `varchar(N)`, `field.currency` → integer, `field.uuid` → native `uuid` on
 Postgres, `field.enum` → `varchar` + `CHECK`, etc.).
 
+Codegen only ever maps the **shapes you authored** — so author them right. If you
+find the generator emitting the wrong column type, the fix is the field shape, not a
+template hack. See "Choosing the right field shape" in the **`metaobjects-authoring`**
+skill for the ordered subtype-vs-attribute-vs-`@dbColumnType` test (ADR-0037) — e.g.
+arrays are `isArray: true` (never an array column type) and a native UUID is
+`field.uuid` (not a string + `@dbColumnType`). When you register custom vocabulary
+for a custom generator, the same ADR-0037 procedure decides whether it's a subtype or
+an attribute.
+
 ## Per-target output
 
 Generated code can be routed to **multiple output directories/packages** so each

fixtures/agent-context-conformance/java-react/expected/.claude/skills/metaobjects-audit/SKILL.md

@@ -80,10 +80,53 @@ code behind a grep hit; a "duplicate" validator's *divergence* is the finding.
   in committed canonical JSON (ADR-0032); DB-type-as-logical-subtype (ADR-0013); per-port
   migration engine where schema is Node-`meta`-owned (ADR-0015).
 
+- [ ] **I. Vocabulary hygiene / modernization (ADVISORY).** Flag already-retired or
+  deprecated authoring patterns and recommend the canonical form (see § Vocabulary
+  hygiene). Advisory severity — scored as modernization opportunities, **never a
+  failing finding**.
+
 **Phase 4 — Synthesize** into the tiered roadmap and populate both artifacts.
 
 ---
 
+## Vocabulary hygiene / modernization (axis I — ADVISORY)
+
+Per ADR-0037, vocabulary expansion follows ONE ordered test (derivable → derive;
+physical-only → `@dbColumnType`; logical: different native type → subtype, same kind +
+modifier → attribute). This axis surfaces authoring that predates or contradicts that
+framework. **All findings here are advisory** — modernization opportunities scored as
+such, surfaced in the roadmap, but **non-failing** (the code works; the form is dated).
+
+**Already-retired / deprecated forms → recommend the canonical form:**
+
+- `@dbColumnType: uuid_array` / `@dbColumnType: text_array` (a physical array column
+  type) → **`isArray: true`** on the base subtype. Array-ness is logical and derivable;
+  the array column type is retired.
+- The `@kind: text` hack (forcing text via a kind override) → **bare `field.string`**
+  (text is the default; no override needed).
+- `@dbColumnType: uuid` where a native UUID type is actually wanted → **`field.uuid`**
+  (a distinct native type is a subtype, not a physical override). Keep `@dbColumnType:
+  uuid` ONLY for the deliberate string-over-uuid-column case.
+
+**Custom-provider vocabulary (adopters who register their own types/attrs):** check
+new/custom vocab against the ADR-0037 procedure (advisory) — e.g. *a custom subtype
+that differs from an existing one only by a property should be an attribute, not a
+subtype*; a string-shape validation (email/url) is an attribute (native type unchanged),
+not a subtype. Recommend re-shaping against the ordered test.
+
+**TODO — Wave-2/3 checks to add when the conventions merge (NOT yet active — these
+tokens are pending ADR-0036 Wave 2/3 and not yet registered; do NOT flag adopters for
+them until merged):**
+
+- `@dbColumnType: timestamp_with_tz` → **drop it** (timezone-aware is the
+  `field.timestamp` default) — *pending Wave 2/3*.
+- A bare wall-clock `field.timestamp` meaning naive/local time → flag for the
+  forthcoming `@localTime` zone-flag attribute — *pending Wave 2/3, not yet active*.
+- An author-supplied regex validating email / url shape → flag for the forthcoming
+  `@format` string-format attribute — *pending Wave 2/3, not yet active*.
+
+---
+
 ## Classification scheme (every surface; classify on codegen AND runtime)
 
 | Class | Meaning | Action |
@@ -183,6 +226,10 @@ one-consumer need, read it codegen-locally.
 Coarse bands only (none / some / most / all). Worst-of within a pillar. On re-run, grade
 the delta. Lead with gaps, not the grade.
 
+**Vocabulary hygiene (axis I) is advisory** — it surfaces as modernization
+opportunities in the roadmap, scored as such, and **never gates a tier or fails the
+audit.** Dated-but-working vocabulary is a quality nudge, not a defect.
+
 ---
 
 ## Report

fixtures/agent-context-conformance/java-react/expected/.claude/skills/metaobjects-authoring/SKILL.md

@@ -161,6 +161,42 @@ name   package   extends   abstract   overlay   isArray   children   value
 Common field attributes: `@required`, `@maxLength`, `@column` (physical column
 name), `@default`, `@filterable`, `@sortable`.
 
+### Choosing the right field shape
+
+When a need doesn't obviously map to a subtype, run this ordered test (ADR-0037) —
+**the first that matches decides:**
+
+1. **Derivable from what you already have?** → derive it, declare NOTHING new. An
+   array is `isArray: true` (never an array column type); a bounded string is
+   `@maxLength`; FK columns come from `identity.reference`. Don't add vocabulary for
+   something the metadata already implies.
+2. **Pure physical-DB detail, native type unchanged?** → the narrow `@dbColumnType`
+   escape hatch (e.g. an open JSON bag). Used sparingly; not a logical type.
+3. **Logical concept** — a *different kind* of value (its own native type, e.g.
+   UUID, money) → a **subtype**; the *same kind* with a modifier (still a string/
+   decimal, just constrained) → an **attribute** (`@maxLength`, `@precision`).
+
+Canonical form for common needs — reach for these before inventing anything:
+
+| Need | Author it as | Note |
+|---|---|---|
+| IDs / unique keys | `field.uuid` | native UUID; use `@dbColumnType: uuid` only to force a string-typed value over a uuid column on purpose |
+| Money | `field.currency` | integer minor units; never a float |
+| Closed set of symbols | `field.enum` | `@values` required |
+| Instant / timestamp | `field.timestamp` | ISO 8601 with timezone on the wire |
+| A list of anything | `isArray: true` | on the base subtype (e.g. `field.string` + `isArray`) — there is **no** array `@dbColumnType` (retired) |
+| Long / unbounded text | bare `field.string` | add `@maxLength` only when you want `varchar(N)` |
+| Nested structured value | `field.object` | `@objectRef` + `@storage` |
+| Open JSON bag (no fixed shape) | `field.string` + `@dbColumnType: jsonb` | logical type stays string; column is jsonb |
+
+<!-- TODO(ADR-0036 Wave 2/3): add @localTime / @format / @relationName guidance when merged -->
+
+**Extending the metamodel (custom providers):** the same ordered test governs new
+vocabulary you register. A would-be subtype that differs from an existing one only
+by a property is an **attribute**, not a subtype; a string-shape validation
+(email/url) is an attribute, not a subtype (its native type is still `string`).
+Apply ADR-0037 before registering anything.
+
 ### Currency
 
 `field.currency` stores money as **integer minor units** (cents for USD, yen for