@metaobjectsdev/sdk 0.24.1 → 0.24.2

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

@@ -71,10 +71,33 @@ code behind a grep hit; a "duplicate" validator's *divergence* is the finding.
   design, and a real estate reports most of itself unclaimed on day one). Score the prose
   it would replace, and prefer ONE concrete claim an author can check over a
   whole-estate migration.
+  **First establish the estate LOADS.** An older ledger fails the load outright, so
+  `meta verify` never runs and everything in `references/requirements.md` is unavailable:
+  `@violation` and `@verifiedBy` were retired in **0.24.0** (no deprecation shim — ADR-0023
+  seals the registry); an index key declaring both `@fields` and `@expr` is refused since
+  **0.24.1**; and **0.24.2** turned `@status: abandoned | superseded` into **`retired`**. Run
+  **`meta upgrade`** (previews by default; `--apply` writes) before auditing, and audit the
+  upgraded tree. It rewrites only what has one correct answer and **refuses the rest, exiting
+  non-zero** — a refusal is itself a finding, naming the entries whose disposition nobody
+  recorded.
+  **Then audit the `retired` entries specifically.** They are where the ledger earns its
+  keep — agents proposing a retired capability's rebuild is the one failure this mechanism
+  has controlled evidence against — and they are also where it decays quietly. Check that
+  each `@statement` reads as a PROHIBITION rather than a diary entry ("X is never done",
+  not "we used to do X"), and that `@counterexample` describes the REVIVAL. A retired entry
+  whose statement narrates history is invisible to the reader it exists to stop.
 - [ ] **F. Drift-gate adoption.** Is `meta verify` wired into CI / pre-commit? Which
   subverbs (`--codegen` / `--templates` / `--db`)? Committed-codegen freshness gate?
   Advisories heeded? Routine `--no-verify` bypass? Loader `ERR_*` / warnings addressed?
   Parse the stable `code` field, not message text (ADR-0009).
+  **Is any advisory half switched OFF?** A gate can be wired, green, and muted. The
+  requirements authoring lint is advisory and mutable — `--no-requirement-lint` or
+  `META_NO_REQUIREMENT_LINT=1` silences it while the gate above it still runs and can still
+  exit 1, so a green pipeline says nothing about the seven `WARN_REQUIREMENT_*` authoring
+  checks. Grep CI config and scripts for both spellings. Muted is not automatically a defect —
+  a project that made a deliberate call is fine — but it moves those checks back onto the
+  auditor (see `references/requirements.md`), so **say which it is** rather than reporting the
+  ledger as lint-clean.
   **Coverage completeness — "wired" is not "covers it all."** A gate can be present
   yet blind to a whole artifact class. Confirm each subverb actually covers what the
   project HAS: (a) **templates** — `verify --templates` on a CLI before the #193 fix

package/agent-context/skills/metaobjects-audit/references/capability-checklist.md

@@ -114,8 +114,10 @@ classify it (using the classification scheme in `SKILL.md`) and route the cutove
 
 - **`identity.primary`** (`@generation`) — hunt hand-assigned primary keys / ID generation
   the primary identity's `@generation` strategy models.
-- **`identity.secondary`** (`@fields`; physical escapes `@using`/`@expr`/`@where`/`@orders`) — a
-  UNIQUE alternate key (uniqueness is the type — the legacy `@unique` attr was removed from it);
+- **`identity.secondary`** (keys off `@fields` XOR `@expr` — exactly one, never both; physical
+  escapes `@using`/`@where`/`@orders`) — a UNIQUE alternate key (uniqueness is the type — the
+  legacy `@unique` attr was removed from it, and the same XOR rule as `index.lookup` applies here
+  because ADR-0040 puts uniqueness in the TYPE: a secondary identity IS a unique index);
   hunt hand-rolled unique constraints or raw-SQL partial/functional unique indexes it models.
 - **`identity.reference`** (`@references`, `@enforce`) — hunt hand-written FK constraints /
   reference enforcement the reference identity already declares.
@@ -238,6 +240,12 @@ subtypes with opposite polarity: `requirement.functional` fails when NOTHING imp
   recorded as a TODO, or a ticket number in a comment. **ABSENT disposition means UNDECIDED**,
   which is the point: a gap nobody has ruled on reads differently from one deliberately
   accepted.
+- **The doc slots behave differently on this node type** — do not audit them by the generic
+  rule below. `title` is CHARTERED here (a requirement's `name` is an identifier, so the label
+  lives in `title`) and is **rendered** by `meta docs`, heading each entry after its dotted
+  path; `summary` is INERT (nothing reads it, and `@statement` is already the required
+  one-liner) and `meta verify` warns on one. So an absent `summary` is correct, a populated
+  one is the finding, and a populated `title` is correct.
 - **CALIBRATION — entirely opt-in and warning-only where it counts.** A project declaring no
   `requirement.*` nodes sees no diagnostics at all, and object coverage ("entities claimed
   by nothing") ships as a WARNING deliberately — a real estate carrying one requirement will

package/agent-context/skills/metaobjects-audit/references/requirements.md

@@ -9,8 +9,38 @@ effort re-deriving what a green run already proves.
 
 ## What verify has already proven (do not re-check by hand)
 
-Links sit at or below the L4 floor, nesting agrees with levels, `@status` values are legal,
-and references resolve (with dangling allowed on `planned`, whose nodes do not exist yet).
+A run answers two different questions in two separate sections. Both are already-proven
+ground; neither is worth an auditor's time.
+
+**The gate** settles referential integrity: links sit at or below the L4 floor, nesting
+agrees with levels, `@status` values are legal, and references resolve (with dangling allowed
+on `planned`, whose nodes do not exist yet).
+
+**The authoring lint** — printed under its own heading, advisory, and unable to change the
+exit code — settles the naming and prose defects you would otherwise find by reading every
+entry:
+
+| code | what a clean run has already proven |
+|---|---|
+| `WARN_REQUIREMENT_NAME_NOT_ADDRESSABLE` | no `name` is blank, space-padded, or carries a `.` / `/` / `:` that breaks the dotted path or the generated stub's filename |
+| `WARN_REQUIREMENT_NAME_READS_AS_PROSE` | no `name` is a sentence sitting in the address slot |
+| `WARN_REQUIREMENT_NAME_RESTATES_STATEMENT` | no `name` and `@statement` are the same sentence written twice |
+| `WARN_REQUIREMENT_PROSE_EMPTY` | no `@statement` / `@counterexample` is declared-but-blank (the loader enforces presence, never content) |
+| `WARN_REQUIREMENT_PROSE_DUPLICATED` | no `description` repeats `@statement` whole or as its opening sentence, and no `@counterexample` repeats it |
+| `WARN_REQUIREMENT_INERT_DOC_SLOT` | no `summary` is set — nothing reads it, and `@statement` is already the required one-liner |
+| `WARN_REQUIREMENT_TITLE_IS_AN_ID` | no `title` leads with a catalogue or ticket id |
+
+Two limits, and each puts something back on your list:
+
+- **The lint is mutable.** `--no-requirement-lint` / `META_NO_REQUIREMENT_LINT=1` silences the
+  advisory half while the gate still runs. **Establish whether the project mutes it** (§F of
+  the checklist asks this) — against a muted lint the whole table above proves nothing.
+- **It reports only EXACT repeats.** A paraphrase — `description` restating `@statement` in
+  different words, a `@counterexample` that merely negates it — is invisible to the tool and
+  is a legitimate hand finding.
+
+`title` is deliberately NOT flagged as an inert slot; it is chartered as the entry's label and
+is rendered (see item 6). Do not report a populated `title` as a defect.
 
 ## What only a human or an agent reading the code can catch
 
@@ -40,6 +70,14 @@ functional one.
 model. If the tree is flat, or every entry is L3, the levels are carrying no information and
 should be simplified rather than defended.
 
+**6. Titles that are not labels.** `title` is now **rendered** — `meta docs` heads each entry
+`## checkout.payment — Payment capture`, the path first and the label after it — so a slot
+that used to be inert is read by every reader of the generated page. The lint catches only
+the id-shaped case (`FR-448 …`); it cannot tell a *useless* label from a good one. Read the
+titles: one that restates `@statement`, or repeats the path in prose, is now visible noise in
+a heading rather than a private authoring habit. An absent `title` is NOT a finding — the
+entry heads by its path alone, which is what every sibling surface addresses it by.
+
 ## Scope — do NOT flag these as defects
 
 - **Unclaimed `object.value` / `object.projection`.** Exempt by design: a value is a shape, a

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

@@ -596,6 +596,11 @@ Declaring **neither** — or **both** — is `ERR_INVALID_INDEX`. This applies t
 `identity.secondary` as well as `index.lookup`: uniqueness lives in the type, so a unique
 index keys itself the same way.
 
+Legacy metadata declaring both used to load, with `@fields` **silently discarded**. If you
+meet one, `meta upgrade --apply` drops `@fields` — do not hand-pick the survivor: the index
+in the database is the expression one, so keeping `@expr` reproduces it and keeping
+`@fields` would emit a migration against live data.
+
 The db provider contributes physical-tuning attrs alongside either form: `@orders`
 (per-column sort direction), `@using` (access method — `gin`/`gist`/`hash`; default
 `btree`), and `@where` (partial-index predicate).

package/agent-context/skills/metaobjects-authoring/references/requirements.md

@@ -5,13 +5,31 @@ describe. Read the existing requirement nodes before designing anything. Two rul
 more than the rest.
 
 **1. A requirement is PRESCRIPTIVE — it states what should be true, never what happened.**
-So when a capability is retired, **delete its requirement** in the same change that removes
-the code. `status` is `planned | live | partial`; there is no member meaning "we used to do
-this", because every one of those three describes something meant to be true now or soon.
-
-What a deleted entry leaves behind is a diff, which is the right home for it. If something
-about the retirement is worth carrying forward — why it went, what replaced it — put that in
-`notes` on the entry that survives, where a reader looking at today's model will find it.
+`status` is `planned | live | partial | retired`, and every one of them states something
+meant to be true. `retired` is not the exception: it means **"this was built, then
+deliberately removed, and must not be rebuilt"** — a prohibition in force, falsifiable by
+exactly one observable, the capability reappearing.
+
+So write a retired entry as a rule, not a diary. `statement: "An unpaid order is never
+expired by a wall-clock timer"` is a prohibition; `"We used to expire orders on a timer"` is
+history wearing a requirement's shape, and no gate will catch it. On a retired entry
+`counterexample` describes **the revival** — the thing a future reader is about to propose.
+
+**Do not delete a retired capability's entry.** Keeping it is the single most load-bearing
+thing this vocabulary does: given a brief for a capability that had been retired, agents
+working from the model alone proposed rebuilding it 24 times out of 24. The entry is what
+stops that, so a retirement is a status change plus a rewritten statement, never a deletion.
+
+Three rules the loader enforces on `retired`:
+
+- **`implementedBy` is REFUSED** — a retired capability has no implementation by definition.
+  What used to implement it goes in `notes`. If deleting the references feels wrong, the
+  capability is probably not retired: an entry whose nodes are still there is `live` or
+  `partial`.
+- **`supersededBy` names the requirement that replaced it**, legal here only, and RESOLVED —
+  so the chain still works when the replacement is itself retired later.
+- It never counts toward object coverage, and is exempt from the architectural universality
+  check.
 
 Leaving a dangling `implementedBy` is **correct only on `planned`**: the entry precedes the
 nodes. On `live` or `partial` the same dangling reference is an error — the model moved and
@@ -27,10 +45,9 @@ rule kills *"the system is reliable"*. If you cannot say what breaking it looks
 delete it.
 
 **Four prose slots, and `statement` is the one that means "description".** A requirement can
-also carry the common `title`, `description` and `notes`, and they overlap badly unless you
-decide the split before writing any of them:
+also carry the common `description` and `notes`, and they overlap badly unless you decide the
+split before writing any of them:
 
-- `title` — a short **noun-phrase** label (`name` is an identifier; this is what an index shows)
 - `statement` — **the claim**. This IS the description of what the requirement is
 - `counterexample` — **what would falsify the claim**, which is what makes it checkable
 - `description` — **the scope**: what the claim covers, what it deliberately does not, and
@@ -38,12 +55,33 @@ decide the split before writing any of them:
 - `notes` — **the evidence**: how you know the `status` is true — citations, vocabularies, the
   control you ran to prove an absence was real
 
+**`title` is a LABEL and is chartered here; `summary` is not.** A requirement's `name` is an
+identifier and its address renders as a dotted camelCase path, so a short noun-phrase `title` is
+what an index shows — the requirement attribute table in `spec/capability-ledger.md` says so by
+name, and the generated requirements page renders it in the heading after the path
+(`## checkout.payment — Payment capture`). `summary` is different: `statement` is already the
+required one-line sentence, so a `summary` can only repeat it and nothing reads it (`verify` warns,
+`WARN_REQUIREMENT_INERT_DOC_SLOT`). `notes` is unrendered on purpose — chartered internal-only.
+
+**Never put a catalogue or ticket id in `title`.** A title is a noun phrase; an id is not a name.
+`title: "FR-467 — Order recording"` is two things in one slot — put the id in `trackedBy` and
+keep the phrase as the title. `verify` warns (`WARN_REQUIREMENT_TITLE_IS_AN_ID`).
+
+**The `name` is an address, so write it as an identifier.** It is the segment of the dotted
+path (`Ordering.Placement.Recorded`) and the filename of the generated test stub. A `.` in a
+name is indistinguishable from nesting — `Orders.Recorded` and `Orders` containing `Recorded`
+produce the same path — and a sentence for a name puts the claim somewhere nothing reads it.
+Both load; `verify` warns (`WARN_REQUIREMENT_NAME_NOT_ADDRESSABLE`,
+`WARN_REQUIREMENT_NAME_READS_AS_PROSE`, `WARN_REQUIREMENT_NAME_RESTATES_STATEMENT`).
+
 Two failure modes, both of which look like diligence. A `description` that **paraphrases the
 statement** is padding, and it makes every later reader trust the ledger less — leave it off
 instead, it is optional. A `description` that **narrates the evidence** belongs in `notes`;
 the tell is a fact you had to read the implementation to learn. Mechanical test for the last
 line: *would this sentence have to change if the code changed but the model did not?* Then it
-is `notes`.
+is `notes`. `verify` warns on the exact repeats (`WARN_REQUIREMENT_PROSE_DUPLICATED`), and on
+a `statement` or `counterexample` that is present but blank (`WARN_REQUIREMENT_PROSE_EMPTY`) —
+the loader requires those attrs to exist, never to say anything.
 
 **Hierarchy is nesting, and links live at the bottom.** L1 solution, L2 segment, L3
 service — these never reference the model. **L4** binds a declared top-level node — an

package/agent-context/skills/metaobjects-codegen/references/typescript.md

@@ -133,10 +133,10 @@ cross-subtype 404. Conformance-gated by `fixtures/api-contract-conformance/tph`
 (HTTP wire shape) and `fixtures/persistence-conformance/tph-*` (single-table
 runtime semantics).
 
-## Docs — `meta docs` (one door, two surfaces)
+## Docs — `meta docs` (one door, three surfaces)
 
 Documentation is NOT a `meta gen` generator. The single door is the `meta docs`
-command, which emits two cross-linked **surfaces** under one output dir (default
+command, which emits three cross-linked **surfaces** under one output dir (default
 `./docs`):
 
 - **model surface** (`./docs/<Entity>.md`, `./docs/<Template>.md`) — the neutral
@@ -146,11 +146,19 @@ command, which emits two cross-linked **surfaces** under one output dir (default
   `./docs/api/AGENT-API.md`) — the SDK/API reference: the concrete imports,
   function signatures, payload field shapes, and runnable examples for *this*
   project's generated code.
+- **requirements surface** (`./docs/requirements.md`, `./docs/requirements.toon`) —
+  the declared `requirement.*` ledger as documentation, with each entry headed by its
+  dotted path and its `title` where it has one, and each entity page naming the
+  requirements that claim it. Metadata-alone like the model surface, so it needs no
+  gen config. **On by default since 0.24.0** — a project declaring no `requirement.*`
+  nodes writes no requirements file and the run says nothing about the surface at all,
+  deliberately: reporting "0 requirement pages" would advertise a surface that never ran.
 
 ```bash
-npx meta docs                     # both surfaces → ./docs (model) + ./docs/api (api)
+npx meta docs                     # all three → ./docs (model) + ./docs/api + ./docs/requirements.*
 npx meta docs --model             # model surface only
 npx meta docs --api               # api surface only
+npx meta docs --requirements      # requirement ledger only
 npx meta docs --out ./site-docs   # write under a different root
 ```
 

package/agent-context/skills/metaobjects-fit-assessment/SKILL.md

@@ -18,13 +18,14 @@ DEFERRED, ON PURPOSE — capability requirements (`requirement.functional` /
 `requirement.architectural`). This skill deliberately says NOTHING about them, and that is a
 decision, not an omission.
 
-Why not now: (1) the grounding rule above requires every capability claim be verifiable
-against the CURRENT RELEASE, and `requirement.*` is not in one yet. (2) The signal->feature
-mapping is unvalidated against this skill's own kill criterion: the controlled evidence
-(0/24 model-only revivals) measures POST-adoption model-reading, and the feature's premise --
-that the disproof lives nowhere in the model -- cuts against pre-adoption detectability. If
-the reasoning was never written down, there is nothing for an evidence-cited assessment to
-cite. (3) Whether anyone fills the ledger in is itself untested; advertising it pre-adoption
+Why not now: (1) SPENT -- this read "not in a release yet", and it is now. `requirement.*`
+shipped in 0.22.0 and has evolved twice since (0.23.0 added `planned` / `@disposition` /
+`@trackedBy`; 0.24.0 made the vocabulary prescriptive-only). Do not repeat this reason.
+(2) The signal->feature mapping is unvalidated against this skill's own kill criterion: the
+controlled evidence (0/24 model-only revivals) measures POST-adoption model-reading, and the
+feature's premise -- that the disproof lives nowhere in the model -- cuts against pre-adoption
+detectability. If the reasoning was never written down, there is nothing for an evidence-cited
+assessment to cite. (3) Whether anyone fills the ledger in is itself untested; advertising it pre-adoption
 is the brochure failure this skill exists to avoid.
 
 TRIGGER to revisit — the release carrying `requirement.*` has shipped, AND either:
@@ -34,6 +35,23 @@ TRIGGER to revisit — the release carrying `requirement.*` has shipped, AND eit
   Arm B  a team that adopted via this assessment hits a resurrection the ledger would have
          caught, or asks why the assessment never mentioned it.
 
+ARM A HAS FIRED (dogfooded adopter estate, 2026-08-13). Three retired or reversed capability
+decisions were each citable PRE-adoption at file:line -- a removal commit, two explicit
+do-not-reintroduce comments on the very constant an agent would revive, an .env.example line
+saying the knob does not exist. The ANTI-TRIGGER did NOT fire: every one traced to committed
+prose. Bound it honestly -- n=1, and that estate is unusually disciplined about recording
+reversals in co-located prose, which is precisely the manual work `requirement.*` systematizes,
+so it is a confound rather than a clean sample. It also partly falsifies the feature's own
+premise that the disproof lives nowhere in the model.
+
+SO THE DEFERRAL NOW RESTS ON (3) ALONE, which makes it a judgement about VALUE rather than a
+fact about the release. Unprompted uptake is still unmeasured, and a later cross-estate reading
+sharpened the question: ledger value tracks whether the ledger is EXECUTABLE -- whether some
+mechanism can falsify a claim -- not when it was written. The largest ledger measured carried
+no harness and produced no defect found by any mechanism. Advertising that to a team that will
+hand-maintain it is the brochure failure this skill exists to avoid. Revisiting means deciding
+the SHAPE below is worth spending, not re-checking whether the capability exists.
+
 ANTI-TRIGGER (defer -> never): if dogfooded entries trace only to tribal knowledge with no
 repo artifact, this assessment structurally cannot speak to the feature as a finding.
 
@@ -46,8 +64,10 @@ R0 verdict line: no verdict may turn on it.
 
 # MetaObjects Fit & Migration Assessment
 
-_Assessment prompt v1 (post-Phase-0 refinement). Grounded against MetaObjects npm `0.17.x` /
-Maven `7.9.x` — verify every capability claim against the current release before asserting it._
+_Assessment prompt v1 (post-Phase-0 refinement). Body originally grounded against MetaObjects
+npm `0.17.x` / Maven `7.9.x`; capability claims re-swept against npm `0.24.x` / Maven `7.24.x`
+on 2026-08-25, but not every line has been re-derived since — verify every capability claim
+against the current release before asserting it._
 
 You are an AI assistant running a **pre-adoption fit assessment** for MetaObjects
 (https://github.com/metaobjectsdev/metaobjects — the cross-language metadata standard:
@@ -265,11 +285,13 @@ signature class. Hunt all ten classes:
    **necessity test**: expressible when every output column is a passthrough
    (`origin.passthrough @from/@via`), a count/sum/avg/min/max (`origin.aggregate
    @agg/@of/@via`, row-scoped with `@filter`), a predicate quantifier (`origin.aggregate
-   @agg: any|all`), an array rollup (`origin.aggregate @agg: collect`), a non-aggregate
-   derived scalar (`origin.computed @expr`), an argmax-style "one related row's column"
-   pick (`origin.first @via` — covers the common `DISTINCT ON` / lateral-join shape),
-   a soft-delete/status/type row-scope (an
-   object-level `@filter` on `object.projection`), or `extends`-borrowed — and joins
+   @agg: any|all`), an array rollup (`origin.aggregate @agg: collect` — with `@of`
+   naming one column, or `@of` OMITTED since 0.24.1 to collect each related row as the
+   carrying field's declared value object, which is the `json_agg(row_to_json(...))` shape),
+   a non-aggregate derived scalar (`origin.computed @expr`), an argmax-style "one related
+   row's column" pick (`origin.first @via` — covers the common `DISTINCT ON` / lateral-join
+   shape), a soft-delete/status/type row-scope (an object-level `@filter` on
+   `object.projection`), or `extends`-borrowed — and joins
    follow declared relationships/`identity.reference` FKs. Expressible → projection
    candidate (note: an unmodeled hand view is *unmanaged* — invisible to `verify --db`;
    modeling it is what makes it gateable). `DISTINCT ON` and lateral join are **not**
@@ -313,7 +335,7 @@ concrete — lead with it.
 | schema vs model (5 + the DDL copy in 6) | spine owns DDL via `meta migrate`; **`meta verify --db`** (Node `meta` only; PG/SQLite/D1) |
 | opaque JSON columns (6-implicit) | `object.value` + `field.object @storage: jsonb` — the shape gets ONE checkable declaration + generated codecs |
 | read-model SQL (8) | `object.projection` + `origin.*` generate the view DDL |
-| scattered prompts (10) | `template.prompt` + typed payload VO + external text; **`meta verify --templates`** / `Renderer.verify` fails when a `{{field}}` no longer matches the payload; `template.output` (FR-006) + the tolerant `extract` parser and output-format fragment (FR-010) generate both sides of the tag contract |
+| scattered prompts (10) | `template.prompt` + typed payload VO + external text; **`meta verify --templates`** / `Renderer.verify` fails when a `{{field}}` no longer matches the payload; a **responding** `template.prompt` — one carrying `@responseRef` — generates parser-on-receipt (FR-006) plus the output-format fragment and tolerant `extract` (FR-010), i.e. both sides of the tag contract. A `template.output` is **outbound only** and emits no parser (ADR-0052, 0.24.0) |
 | the metadata itself | strict provenance (ADR-0023): unknown attrs fail load |
 
 State the honest limits in the same section: `verify` cannot catch semantic mismodeling
@@ -428,8 +450,11 @@ promising it or counting it in benefits:
   count them).
 - email/URL/IP regexes → `@stringFormat: email` / `field.uri` / `field.inet`.
 - opaque JSON columns → `object.value` + `field.object @storage: jsonb` (from P2-b).
-- inline prompts / ad-hoc payload dicts / regex output parsing → `template.prompt` /
-  `template.output` / `template.toolcall`.
+- inline prompts / ad-hoc payload dicts → `template.prompt` / `template.toolcall`; a
+  hand-rolled regex or JSON-scrape of an LLM **reply** → a *responding* `template.prompt`
+  (one carrying `@responseRef`), never `template.output` — the subtype's axis is DIRECTION
+  and an output is outbound only (ADR-0052). Rendered emails / documents / config exports
+  are what `template.output` is for.
 - doc comments hand-written in migrations (`COMMENT ON`) → the common `description` attr.
 - a recurring closed variant-set as N sibling modules → project-registered provider
   subtype — VOCAB CANDIDATE, advisory only, never load-bearing for the verdict.
@@ -572,9 +597,11 @@ Every prose prediction gets a claim. Ceiling statements (P5-b) MUST carry
   runtime; consumer hand-wires the FastAPI router + repository impl; `metaobjects`
   console script `gen`/`verify` (no migrate).
 - **Prompt pillar** (all five ports): render + payload-VO codegen + `verify` templates +
-  `template.output` parser-on-receipt (FR-006) + output-format fragment & tolerant
-  `extract` (FR-010). MCP exposure of declared prompts/tools: not shipped — never
-  promise it.
+  parser-on-receipt for a **responding `template.prompt`** (FR-006) + output-format fragment
+  & tolerant `extract` (FR-010). Since 0.24.0 that whole inbound tier keys off `@responseRef`
+  on a `template.prompt`; a `template.output` is outbound-only and emits none of it
+  (ADR-0052) — do not promise a parser for one. MCP exposure of declared
+  prompts/tools: not shipped — never promise it.
 - **Not shipped, never promise**: `api.*`/`operation.*`/`binding.*` declared-API surface;
   the cut `byte`/`short`/`class` field stubs (non-functional, removed from the registry);
   `index.fulltext`/`vector`/`spatial` (reserved, unregistered); native PG enums /

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

@@ -46,6 +46,28 @@ Two more are caught structurally rather than by a command: **generated-edited**
 **migration-vs-metadata** (migrations are emitted *from* metadata diffs, so they
 can't drift by construction).
 
+## Before any of this: the metadata has to LOAD — `meta upgrade` for retired vocabulary
+
+`verify` cannot report drift in a model it could not read. The registry is sealed
+(ADR-0023), so a retired name has **no deprecation shim** — it is a load error, and
+the run stops before the first drift check. Retirements that bite an existing estate:
+`@readOnly` → `@mutability` and `origin.collection` → `origin.aggregate @agg: collect`
+(0.24.0); `@violation` → `@counterexample`, plus `@verifiedBy`, `@supersededBy` and
+`@status: abandoned | superseded` on `requirement.*` (0.24.0, FR-038); and an index key
+declaring **both** `@fields` and `@expr`, refused since 0.24.1.
+
+```
+meta upgrade            # previews every rewrite; writes nothing
+meta upgrade --apply    # makes them
+```
+
+Node-only, because it edits the metadata documents every port shares — a Java, Python
+or C# project runs `npx meta upgrade` against its own sources. Canonical JSON and YAML
+alike. It rewrites from the same table the loader's errors are generated from, fixes
+only what has one correct answer, and **refuses the rest with a non-zero exit** so a
+pipeline cannot record a partial migration as done. See
+`references/requirements.md` for what it refuses on a ledger and why.
+
 ## Run `meta verify` before you call a build done
 
 Make a bare `meta verify` the last step before you consider any MetaObjects work

package/agent-context/skills/metaobjects-verify/references/requirements.md

@@ -13,6 +13,37 @@ subverb**: requirements are metadata, so they are checked on *every* `meta verif
 A typo'd `@status` fails the **load** ("failed to load metadata"), before verify runs. If you
 see that, no other diagnostic in the run is trustworthy — fix it first and re-run.
 
+## A load failure on RETIRED vocabulary — run `meta upgrade`, do not hand-sweep
+
+`@status` is not the only way the load fails before any of this runs. **0.24.0** retired
+`@violation` (→ `@counterexample`) and `@verifiedBy`; **0.24.1** made an index key `@fields`
+**XOR** `@expr`, so a node declaring both is now `ERR_INVALID_INDEX`. **0.24.2 reversed half
+of the 0.24.0 cut**: `abandoned` and `superseded` become **`@status: retired`**, and
+`@supersededBy` is registered again — this time as a reference the loader resolves. There is no deprecation shim for any of them —
+the registry is sealed (ADR-0023), so a legacy document does not load at all and every check on
+this page is unreachable until it does.
+
+```
+meta upgrade            # previews every rewrite; writes nothing
+meta upgrade --apply    # makes them
+```
+
+It rewrites from the same table the loader's error text is generated from, so the fix you are
+told about and the edit the tool makes cannot drift apart. It fixes only what has one correct
+answer and **refuses the rest, exiting non-zero** — a partial migration can never be recorded
+as finished by CI. Two refusals are expected on a real ledger and both are yours to decide:
+
+- **`@status: abandoned` / `superseded` are no longer refused** — they rewrite to `retired`,
+  and the same run drops the `@implementedBy` that a retired entry may not carry. This was the
+  canonical judgement case in 0.24.0; FR-039 made it determinate.
+- **`origin.collection`.** Retired to `origin.aggregate @agg: collect`; the attribute sets
+  differ, so the tool will not guess.
+
+`@fields` beside `@expr` **is** rewritten, and the survivor is not a coin toss: that pair loaded
+before 0.24.1 with `@fields` silently discarded, so the index already in your database is the
+expression one. `upgrade` drops `@fields` — which reproduces the object that exists and emits no
+DDL change. Do not hand-pick the other survivor; that invents a new index and migrates live data.
+
 ## The status asymmetry — the one that surprises people
 
 The **same** unresolved `@implementedBy` reference is:
@@ -49,6 +80,8 @@ name the remedy; this table exists so you can act on one without re-deriving the
 | `ERR_REQUIREMENT_ARCH_NO_IMPLEMENTERS` | a `live`/`partial` `requirement.architectural` that nothing implements | a policy declared and applied to nothing. Claim the nodes it governs, or drop it to `planned` — which is exempt, because it is not applied yet by definition. |
 | `ERR_REQUIREMENT_LEVEL_NESTING` | a node's `@level` disagrees with the level of the parent it nests under | nesting IS the hierarchy. Move the node to the right parent rather than editing the level to match where it happens to sit. |
 | `ERR_REQUIREMENT_BAD_LEVEL` | `@level` is not an integer inside the allowed range | levels are L1–L5 and nothing else. |
+| `ERR_REQUIREMENT_RETIRED_HAS_IMPLEMENTORS` | a `@status: retired` entry declares `@implementedBy` | a retired capability has no implementation by definition. Delete the attribute and put what used to implement it in `notes`; if the nodes are still there, the capability is `live` or `partial`, not retired. |
+| `ERR_REQUIREMENT_SUPERSEDED_BY_NOT_RETIRED` | `@supersededBy` on a status other than `retired` | it names what REPLACED a withdrawn capability, so on a live one there is nothing for it to say. |
 | `ERR_MISSING_REQUIRED_ATTR` | a required attr is absent | `@statement`, `@status` and `@counterexample` are required on both subtypes; `@level` is required on `functional` and optional on `architectural`. |
 | `ERR_BAD_ATTR_VALUE` | a closed-enum attr has an unknown value | `@status` and `@disposition` are enforced by the LOADER, so a typo fails the load in every port rather than passing in some. |
 
@@ -56,6 +89,40 @@ name the remedy; this table exists so you can act on one without re-deriving the
 reasons, so reading only the code you hit can send you the wrong way. The question is not
 "is this ref valid?" — usually it is — but "does the LEVEL match the shape of the ref?"
 
+## The authoring lint — a second section, never an error
+
+`verify` also prints an **authoring lint** under its own heading, after the gate's own
+warnings:
+
+```
+meta verify — requirements: 6 authoring warning(s) (advisory — does not fail the build):
+```
+
+Read it as a different claim from everything above. The gate says the ledger **disagrees with
+the model**; the lint says it agrees but **records less than its author thinks**. Every finding
+is a warning and none can change the exit code, so a lint-only run is a passing run.
+
+| code | what it means | fix |
+|---|---|---|
+| `WARN_REQUIREMENT_NAME_NOT_ADDRESSABLE` | the `name` holds a character that breaks the dotted path or the generated stub filename | rename it. A `.` is the common one and the worst: `Orders.Recorded` and `Orders` containing `Recorded` produce the **same** path, so the address stops identifying one node. |
+| `WARN_REQUIREMENT_NAME_READS_AS_PROSE` | the `name` is a sentence | the name is an address — make it an identifier and put the prose in `@statement`. |
+| `WARN_REQUIREMENT_NAME_RESTATES_STATEMENT` | `name` and `@statement` say the same thing | the claim is written twice. Keep `@statement` (every surface reads it) and shorten the name. |
+| `WARN_REQUIREMENT_PROSE_EMPTY` | `@statement` or `@counterexample` is present but blank | the loader requires the attr to EXIST, never to say anything. Write the sentence, or delete the entry. |
+| `WARN_REQUIREMENT_PROSE_DUPLICATED` | `description` repeats `@statement` (whole, or as its opening sentence), or `@counterexample` does | `@statement` is already the description. `description` holds the SCOPE; drop it entirely if the scope is obvious. |
+| `WARN_REQUIREMENT_INERT_DOC_SLOT` | `summary` is set on a requirement | `@statement` is already the required one-line sentence, so a summary can only repeat it, and nothing reads it. Delete it. (`title` is NOT flagged — it is chartered as the entry's label.) |
+| `WARN_REQUIREMENT_TITLE_IS_AN_ID` | `title` holds a catalogue or ticket id | a title is a noun phrase and an id is not a name. **Split** it — the id to `@trackedBy`, the phrase stays the title. Do not move the whole string; that throws the label away. |
+
+Findings from both sections are addressed by the requirement's **dotted path**, never its
+bare name — two branches of a ledger may reuse a name, so a bare one can be ambiguous.
+
+Mute the lint with `--no-requirement-lint` or `META_NO_REQUIREMENT_LINT=1`. That silences the
+advisory half **only** — the gate above still runs and can still exit 1.
+
+Two deliberate silences. The lint reports only **exact** repeats, never a paraphrase — a
+similarity threshold on prose produces findings you can argue with. And it never judges
+whether a statement is true or a counterexample sufficient; those are the judgements the
+ledger exists to record.
+
 ## `verify` does not look at your tests
 
 It used to. `@verifiedBy` asked you to name a test, and `verify` checked that the **name**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@metaobjectsdev/sdk",
-  "version": "0.24.1",
+  "version": "0.24.2",
   "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.24.1",
+    "@metaobjectsdev/metadata": "0.24.2",
     "zod": "^3.23.0"
   },
   "devDependencies": {