feat(agent-context): add metaobjects-audit adoption-review skill

[dmealing]

Intent

Build a new 'metaobjects-audit' agent-context skill (the 6th metaobjects-* skill) that reviews how well an adopter project has integrated MetaObjects and where it can improve — supporting both brand-new (greenfield first-pass) and deeply-integrated projects, covering codegen AND runtime-driven usage. Design decisions: the skill is read-only/propose-only (never mutates adopter code), emits two artifacts (.metaobjects/adoption-audit.json typed findings + a Markdown report), and uses a THREE-surface scoring model with NO single global score (a maturity tier Greenfield->Partial->Deep->Exemplary that is AND-gated/worst-of, a per-pillar breakdown, and a binary CI drift-gate signal). It has an audit->action bridge (typed findings -> dry-run -> review -> apply, mapping onto 'meta gen --dry-run' + 'verify --codegen'). Capability coverage is registry-grounded: references/capability-checklist.md enumerates every metamodel type/subtype/attr and a grounding test asserts each token exists in expected-registry.json with principled cut/TS-only/planned exemptions. The skill DELIBERATELY names retired/cut anti-pattern vocabulary (source.dbTable, @dbColumn, field.byte/short/class) because its job is to recognize them, so it is exempted from the cruder drift.test.ts vocabulary scan and governed instead by the stricter grounding test (which the fix wave extended to scan SKILL.md + all references, not just the checklist). Five per-port reference fragments (ts/csharp/java/kotlin/python) carry real CLI commands + calibration rules that mark per-port codegen gaps and cross-port version skew as NON-defects. Registered as 6th/last in SKILL_NAMES; all 4 agent-context conformance fixtures regenerated. Executed via subagent-driven-development with a final whole-branch review + one fix wave that removed an invented 'meta gen --watch' command (also removing the same dropped line from the sibling metaobjects-codegen skill), closed a grounding coverage hole, and reworded dangling spec cross-references. Includes the design spec + implementation plan docs.

What Changed

• Adds a new metaobjects-audit agent-context skill (6th and last in SKILL_NAMES) — a read-only/propose-only adoption reviewer that emits typed .metaobjects/adoption-audit.json findings plus a Markdown report, scores integration via a three-surface model (AND-gated maturity tier, per-pillar breakdown, binary CI drift-gate) with no single global score, and bridges audit→action onto meta gen --dry-run + verify --codegen. Ships SKILL.md, a registry-grounded capability-checklist.md, and five per-port reference fragments (ts/csharp/java/kotlin/python) with real per-port CLI commands and calibration rules treating per-port codegen gaps and version skew as non-defects.
• Adds an agent-context-capability-grounding.test.ts that asserts every metamodel token in the checklist (extended in the fix wave to all of SKILL.md + references) exists in expected-registry.json, with principled cut/TS-only/planned exemptions; exempts the audit skill from the cruder drift.test.ts vocabulary scan since it deliberately names retired anti-pattern vocabulary (source.dbTable, @dbColumn, field.byte/short/class) to recognize them.
• Regenerates all four agent-context conformance fixtures (csharp/java-react/python/typescript-react-tanstack) to bundle the new skill, removes the invented meta gen --watch command from both the audit and sibling metaobjects-codegen skills, and adds the design spec + implementation plan docs.

Risk Assessment

✅ Low: The change is almost entirely additive documentation (a new read-only skill, design/plan docs, regenerated fixtures) plus a one-line constant addition and well-constructed tests whose registry-grounding assertions I independently verified pass; no behavioral code paths are altered.

Testing

Ran the change's three new/modified tests (registry-grounding, types/SKILL_NAMES, drift exemption) plus the agent-context conformance corpus and the full sdk agent-context suite — all pass. Because this is an inspectable-Markdown agent-context skill with no executable runtime, I demonstrated the real end-user surface by driving assemble() for a TS+React adopter stack and capturing the 7 audit files that ship into .claude/skills/metaobjects-audit/ along with the rendered SKILL.md the agent reads; the conformance test independently proves that assembly is byte-identical to the committed fixtures across all four stacks. One initial failure in bundle.test.ts was purely environmental (the gitignored build bundle hadn't been generated in this fresh checkout); running the bundle script produced it correctly including the new skill, after which I removed the transient output, leaving the worktree clean.

Evidence: Audit skill assembled into an adopter repo (file list + rendered SKILL.md head)

Files shipped into adopter repo for the metaobjects-audit skill:

  .claude/skills/metaobjects-audit/SKILL.md
  .claude/skills/metaobjects-audit/references/capability-checklist.md
  .claude/skills/metaobjects-audit/references/csharp.md
  .claude/skills/metaobjects-audit/references/java.md
  .claude/skills/metaobjects-audit/references/kotlin.md
  .claude/skills/metaobjects-audit/references/python.md
  .claude/skills/metaobjects-audit/references/typescript.md

--- metaobjects-audit/SKILL.md (first 40 lines as the agent would read it) ---

---
name: metaobjects-audit
description: Use when assessing how well a project has adopted MetaObjects — greenfield first-pass or deep double-check; produces a scored, prioritized adoption-audit report covering codegen, runtime, drift-gates, and prompts.
---

# MetaObjects adoption audit

**Thesis.** Typed metadata is the durable spine; generated code is the disposable
artifact. Hand-writing a layer the metadata could own creates a second source of
truth for one fact — it will drift. This audit hunts those second sources of truth
and proposes folding them into the spine.

**Boundary — read-only.** Deliverables: `.metaobjects/adoption-audit.json` (machine-readable
findings) + a rendered Markdown report. The audit **never edits code, never authors
metadata** — `metadata_sketch` per finding is a read-only proposal for human review.
Actual cutovers run through the existing skills mapped per finding tier (§ Bridge).

---

## Phase 0 — Triage (fast, mechanical)

- [ ] MetaObjects present? (`metaobjects/` dir, metadata sources, `@metaobjectsdev/*` /
  `com.metaobjects:*` / `metaobjects` / `MetaObjects.*` deps).
- [ ] Count metadata source lines + all `@generated` / `DO NOT EDIT` files repo-wide.
- [ ] **Owned-generators check:** does the project own generators at `codegen/generators/*`
  (scaffold-and-own via `meta init`), or still import the **deprecated** package export
  (`@metaobjectsdev/codegen-ts/generators`)? Not owning is itself a finding.
- [ ] Classify: **Greenfield** (none/minimal) · **Partial** · **Deep** → choose path below.

---

## Phase 1a — Greenfield path

- [ ] **Shape inventory.** Catalog modelable shapes: entities/tables, DTOs, validation
  schemas, routes, UI lists/forms, prompt sites.
- [ ] **Pick wedge:** one real entity (single-column PK, standard CRUD) to model first.
- [ ] **From-zero roadmap:** `meta init` → model the wedge → `meta gen` the data layer →
  author a projection view → expand to routes/UI → add prompt pillar where LLM calls exist.
  Owning the generators from day 1 is part of the roadmap.

Evidence: Grounding/conformance/registration test transcript

bun test v1.3.8 (b64edcb4)

 11 pass
 0 fail
 138 expect() calls
Ran 11 tests across 3 files. [321.00ms]

Test files exercised (all pass, 0 fail):
  agent-context-capability-grounding.test.ts
    - capability checklist is registry-grounded > every type.subtype named exists in the registry
    - capability checklist is registry-grounded > every @attr named exists in the registry
    - audit skill files (SKILL.md + references) are registry-grounded > there are skill files to check
    - audit skill files (SKILL.md + references) are registry-grounded > every type.subtype named exists or is a principled exemption
    - audit skill files (SKILL.md + references) are registry-grounded > every @attr named exists or is a principled exemption
  agent-context-conformance.test.ts  (assemble() == committed adopter fixtures, byte-identical)
    - csharp, java-react, python, typescript-react-tanstack
  agent-context/types.test.ts
    - the six skills are named and ordered  (metaobjects-audit registered 6th/last)
  agent-context/drift.test.ts
    - vocabulary-drift scan excludes /skills/metaobjects-audit/ by design; rest of corpus clean

Pipeline

Updates from git push no-mistakes

✅ **intent** - passed

✅ No issues found.

✅ **Rebase** - passed

✅ No issues found.

⚠️ **Review** - 1 info

• ℹ️ server/typescript/packages/sdk/test/agent-context-capability-grounding.test.ts:95 - In the checklist @attr grounding test, the comment 'Allow doc-only/config attrs not in the metamodel registry (apiPrefix etc.)' promises tolerance for non-metamodel attrs, but the assertion expect(unknown).toEqual([]) provides no exemption set (unlike the audit-skill-files block, which has CODE_IDENTIFIERS_NOT_METAMODEL_ATTRS). It passes today only because such attrs aren't written backtick-wrapped with an @ in the checklist. A future editor adding e.g. @apiPrefix to the checklist would get a failing test the comment says should be allowed. Harmless now; the comment just contradicts the code.

✅ **Test** - passed

✅ No issues found.

• bun test packages/sdk/test/agent-context-capability-grounding.test.ts — registry-grounding of SKILL.md + all references against expected-registry.json
• bun test packages/sdk/test/agent-context-conformance.test.ts — assemble() == committed adopter fixtures byte-identical for csharp/java-react/python/typescript-react-tanstack (skill shipped into .claude/skills/metaobjects-audit/)
• bun test packages/sdk/test/agent-context/types.test.ts — metaobjects-audit registered 6th/last in SKILL_NAMES
• bun test packages/sdk/test/agent-context/drift.test.ts — audit skill excluded from vocabulary-drift scan, rest of corpus clean
• bun test packages/sdk/test/agent-context (full suite, 42 tests)
• Drove assemble() for a TS+React adopter stack and confirmed all 7 audit files land under .claude/skills/metaobjects-audit/ with correct SKILL.md content (evidence transcript)
• node packages/sdk/scripts/bundle-agent-context.mjs then bundle.test.ts — fixed env-only failure (ungenerated build bundle), confirmed audit skill bundles correctly, then removed transient output

✅ **Document** - passed

✅ No issues found.

✅ **Lint** - passed

✅ No issues found.

✅ **Push** - passed

✅ No issues found.