Skip to content

Commit d01209c

Browse files
dmealingclaude
andcommitted
docs: claims come down to what shipped — requirements checks, six pillars, the 1.0.4 scaffold
FR-042 closes on the four first-touch surfaces. The Verify clause said the build fails "when a feature someone marked done has nothing implementing it". Measured on 1.0.4, a live requirement naming nothing is WARN_REQUIREMENT_NOTHING_IMPLEMENTS (exit 0), and only a named implementation that is gone fails (ERR_REQUIREMENT_DANGLING_REF). The pitch now says "fails or warns", with wording signed off. The same overclaim sat in the registered requirement.functional and requirement.architectural descriptions (the architectural check only fails a live policy applied to nothing). Those are corrected in spec/metamodel and every port copy, the registry-conformance manifest, the metamodel-docs fixture, the requirement harness and site-reference. The change is prose only, so metamodelVersion holds at 1.0. Labelling each pillar found a second overclaim: AGENTS.md, README and llms said the requirements verify checks ship in every port. They run in the Node meta CLI, and the other ports load and validate, as docs/CONFORMANCE.md already said. - README and both llms mirrors: six pillars, each with a maturity label, plus Libraries and metadata-dependency rows in the capability matrix. FR-023 sharing is claimed below the fold with its scope clause: TS publishes, TS and Python consume, path transport only, Java, Kotlin and C# in Phase 2. - The positioning gate bans blanket "all five/six ship today" and "new/newest" pillar claims, with self-test cases in both directions. - Docs that still described the pre-1.0.4 scaffold (init copying four generators, src/db.ts throwing stub, dbImport scaffolded) now describe gen --list --probe and eject: docs/ports/typescript*.md, recipes, codegen-concepts, AGENTS.md, llms.txt, and the audit and runtime-ui skills (agent-context corpus regenerated). - FR-042 spec §3 amendment, §4 maturity-label rule, §7 ticked, §8 progress. Roadmap row updated. The hero drift recording and drift-demo page remain. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01BHEQGNA9McKNBwDkesNMDC
1 parent 9675927 commit d01209c

57 files changed

Lines changed: 322 additions & 181 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎AGENTS.md‎

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -8,13 +8,13 @@ The metamodel is the **durable spine**; generated code is the **disposable artif
88

99
## Six pillars
1010

11-
The first four ship per-language today across the five ports (TS / C# / Java / Python / Kotlin), with cross-port conformance corpora verifying byte-identical behavior. The fifth ships its vocabulary and its `verify` checks in every port, and its test scaffolding in TypeScript only. The sixth is content the other five compose, shipped as named opt-in artifacts:
11+
The first four ship per-language today across the five ports (TS / C# / Java / Python / Kotlin), with cross-port conformance corpora verifying byte-identical behavior. The fifth ships its vocabulary in every port, its `meta verify` checks in the Node `meta` CLI, and its test scaffolding in TypeScript only. The sixth is content the other five compose, shipped as named opt-in artifacts:
1212

1313
1. **Codegen** — emit idiomatic per-language code (Drizzle/Zod + Fastify for TS, EF Core + ASP.NET for C#, Spring REST + DTO + Repository for Java via `codegen-spring`, Pydantic + FastAPI for Python, KotlinPoet + Exposed + Spring for Kotlin via `codegen-kotlin`). Hand-edit-preserving regen via three-way merge.
1414
2. **Runtime metadata** — load metadata at runtime, drive behavior dynamically (CRUD, validation, relationships, dynamic admin UIs, LLM tool registration). On Kysely (TS), a DB-API 2 driver via ObjectManager (Python), modernized JDBC + Spring-tx via OMDB (Java), Exposed (Kotlin), EF Core (C#).
1515
3. **Drift detection** — `meta verify` catches divergence between code and metadata (covers entity codegen, prompt templates, output parsers, schema). Quality-of-life on top of codegen + runtime.
1616
4. **Prompt construction** — a prompt is code, not a string scattered across services. Declare a prompt's payload as a typed projection (payload bloat becomes a diff), keep its text external and provider-resolved, and render it deterministically: snapshot-testable, cache-stable (no whitespace change silently breaking exact-prefix prompt-cache hits), and drift-checked at build time so a renamed field can't degrade a prompt. Conformance-gated, so the guarantee holds in every language port. **Render + payload-VO codegen + `verify` + parser-on-receipt for a *responding* `template.prompt` — one carrying `@responseRef` (FR-006) — + the output-format prompt fragment & tolerant `extract` parser (FR-010) ship in all five ports today** (since 0.24.0 the whole inbound tier keys off `@responseRef`; a `template.output` is outbound-only and emits no parser — ADR-0052) — the library-side building blocks of the pillar are complete. The one remaining library-side piece is MCP exposure of declared prompts/tools (see `spec/roadmap.md`); the application-level consolidation (eval harness, end-to-end declared-prompt orchestration) and consumer adoption are exercised in adopter projects, not in this library repo. Designed in `docs/superpowers/specs/2026-05-22-fr-004-cross-language-prompt-construction-design.md`.
17-
5. **Requirements and testing** — declare what the software is supposed to *do* in the same model as the entities, so a capability claim is checkable instead of prose. The other four pillars keep the code honest about the *model*; this one asks whether the thing you said the software does is actually built — an absence no test can fail on, because a test exercises code that exists. `requirement.functional` (fails when *nothing* implements it) and `requirement.architectural` (fails when something *violates* it) are registered vocabulary in all five ports, with the loader enforcing the closed `@status` enum. `@implementedBy` is **resolved, not trusted** — it names a real member of the real model, so a claim whose implementation was renamed or deleted fails the build instead of going quietly stale. `meta verify` reports the ledger on every run (unresolved links, entities no claim covers, gaps recorded versus gaps nobody has ruled on) plus an authoring lint whose findings can never fail a build; `meta docs` renders it for humans and for agents. **The port split, stated exactly: the vocabulary and the `verify` checks are cross-port; `requirementTests()` — which scaffolds a test stub per claim — is TypeScript-only.** A project that declares no `requirement.*` nodes sees no change at all. Note the standing carve-out: `agent-context/skills/metaobjects-fit-assessment/SKILL.md` deliberately does NOT treat `requirement.*` as an assessment axis — see the ruling in that file before "finishing the job" there.
17+
5. **Requirements and testing** — declare what the software is supposed to *do* in the same model as the entities, so a capability claim is checkable instead of prose. The other four pillars keep the code honest about the *model*; this one asks whether the thing you said the software does is actually built — an absence no test can fail on, because a test exercises code that exists. `requirement.functional` (existence: `meta verify` WARNS when nothing implements it) and `requirement.architectural` (universality: `meta verify` FAILS a live policy applied to nothing, and does not check that each claimed node complies) are registered vocabulary in all five ports, with the loader enforcing the closed `@status` enum. `@implementedBy` is **resolved, not trusted** — it names a real member of the real model, so a claim whose implementation was renamed or deleted fails the build instead of going quietly stale. `meta verify` reports the ledger on every run (unresolved links, entities no claim covers, gaps recorded versus gaps nobody has ruled on) plus an authoring lint whose findings can never fail a build; `meta docs` renders it for humans and for agents. **The port split, stated exactly: the vocabulary loads and validates in all five ports; the `meta verify` checks run in the Node `meta` CLI only (no other port's CLI runs them — `docs/CONFORMANCE.md` "Split coverage"); `requirementTests()` — which scaffolds a test stub per claim — is TypeScript-only.** A green run proves referential integrity, never that a status is true or an implementation correct (`docs/features/requirements.md`, "What a green run does not prove"). A project that declares no `requirement.*` nodes sees no change at all. Note the standing carve-out: `agent-context/skills/metaobjects-fit-assessment/SKILL.md` deliberately does NOT treat `requirement.*` as an assessment axis — see the ruling in that file before "finishing the job" there.
1818

1919
6. **Libraries** — reusable declared design, shipped as metadata and opted into by name (`"libraries": ["iam"]` in `.metaobjects/config.json`). Not a sixth verb: a library is the **reuse unit that composes the other five** — entities, requirements, the generators its design implies, its runtime packages — as one named, opt-in, drift-gated artifact. What makes it a pillar rather than a folder of YAML is the fifth: without requirements a library is a schema snippet; with them it is design an adopter's build is held to, which is the same test the requirements pillar passes (*does it change what an agent can be checked against?*). **A library is LAYERED and its core layer is INERT** — the core declares no `source.rdb`, and a sourceless object generates nothing and migrates to nothing (#248), so `["iam"]` adds zero tables and zero generated code while making the design present and resolvable; `["iam", "iam/db"]` is the separate opt-in that proposes the schema. **Copy is the expected mode** (`meta eject <library>` — ADR-0034's ruling applied to metadata), and an ejected copy still named in `libraries` is refused at load (`ERR_LIBRARY_PACKAGE_COLLISION`) rather than merging asymmetrically. Object coverage activates on ADOPTER-authored requirements only, so a library cannot volunteer a project for a gate it did not ask for. `iam` (preview) and `ai` (stable) ship today; rows appear in `meta gen --list` beside the generators. See [docs/features/libraries.md](docs/features/libraries.md) and `docs/superpowers/specs/2026-09-13-fr-043-feature-and-nfr-packages-design.md`.
2020

@@ -204,7 +204,7 @@ A user's `metaobjects.config.ts`:
204204

205205
```ts
206206
import { defineConfig } from "@metaobjectsdev/cli";
207-
// Owned generators scaffolded by `meta init` (ADR-0034 scaffold-and-own).
207+
// Owned generators, copied in by `meta eject` (ADR-0034 scaffold-and-own; `meta init` wires none).
208208
import { entityFile } from "./codegen/generators/entity";
209209
import { queriesFile } from "./codegen/generators/queries";
210210
import { routesFile } from "./codegen/generators/routes";
@@ -348,13 +348,13 @@ interface Generator {
348348

349349
Helpers `perEntity()` and `oncePerRun()` cover the common "file per entity" / "one-shot" cases.
350350

351-
**Built-in factories**: `entityFile`, `queriesFile`, `routesFile`, `formFile`, `barrel`. Per ADR-0034 (scaffold-and-own), `meta init` copies the `entityFile`/`queriesFile`/`routesFile`/`barrel` reference templates into the consumer repo at `codegen/generators/*.ts` and the scaffolded config imports those owned local copies. The owned copy is the ONLY import path for those four: the deprecated `@metaobjectsdev/codegen-ts/generators` re-export of them was **removed at the 1.0 cut**. `meta eject <generator>` copies any other ejectable generator at any time (`--list` names them all).
351+
**Built-in factories**: `entityFile`, `queriesFile`, `routesFile`, `formFile`, `barrel`. Per ADR-0034 (scaffold-and-own) and its Amendment 2 (opt-in codegen), `meta init` scaffolds `codegen/generators/` EMPTY with `generators: []`; `meta gen --list --probe` is the catalog, and `meta eject <name>...` copies each chosen reference template into the consumer repo at `codegen/generators/*.ts` and prints the import and entry to wire. The owned copy is the ONLY import path for `entityFile`/`queriesFile`/`routesFile`/`barrel`: the deprecated `@metaobjectsdev/codegen-ts/generators` re-export of them was **removed at the 1.0 cut**.
352352

353353
**User wiring** (`metaobjects.config.ts`):
354354

355355
```ts
356356
import { defineConfig } from "@metaobjectsdev/cli";
357-
// Owned generators scaffolded by `meta init` (ADR-0034 scaffold-and-own).
357+
// Owned generators, copied in by `meta eject` (ADR-0034 scaffold-and-own; `meta init` wires none).
358358
import { entityFile } from "./codegen/generators/entity";
359359
import { queriesFile } from "./codegen/generators/queries";
360360
import { routesFile } from "./codegen/generators/routes";

‎CHANGELOG.md‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -10,6 +10,24 @@ here.**
1010

1111
## [Unreleased]
1212

13+
_`metamodelVersion` stays `1.0`. The `requirement.*` change below is a prose-only manifest
14+
edit (two registered `description` strings) and was ruled a hold, as 1.0.4's was._
15+
16+
### Changed
17+
18+
- **The registered `requirement.functional` and `requirement.architectural` descriptions
19+
now say what `meta verify` enforces.** They said a functional requirement "fails when
20+
nothing implements it" and an architectural one "fails when something VIOLATES it". In
21+
fact a `live`/`partial` functional claim that names nothing is a **warning**
22+
(`WARN_REQUIREMENT_NOTHING_IMPLEMENTS`, exit 0), and only a named node that no longer
23+
exists fails (`ERR_REQUIREMENT_DANGLING_REF`). The architectural check fails a live policy
24+
applied to nothing (`ERR_REQUIREMENT_ARCH_NO_IMPLEMENTERS`) and never checks that a claimed
25+
node complies. Every port's embedded copy, the registry-conformance manifest, the
26+
metamodel-docs fixture, the requirement harness and the published reference pages carry
27+
the corrected text. Behaviour is unchanged. The README, `llms.txt` and the audit skill
28+
also stop saying the `verify` checks run in every port: the vocabulary loads and
29+
validates in all five, and the checks run in the Node `meta` CLI.
30+
1331
### Fixed
1432

1533
- **`meta eject` and `meta gen --list` print an install command you can paste.** The line

0 commit comments

Comments
 (0)