@metaobjectsdev/sdk 0.22.1 → 0.23.1-rc.1

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

@@ -976,7 +976,28 @@ mapping).
 
 ## Requirements — capability ledger (opt-in)
 
-If this project declares `requirement.functional` / `requirement.architectural` nodes, read `references/requirements.md` for the full authoring rules.
+**This capability exists whether or not the project uses it yet.** `requirement.functional` and `requirement.architectural` are registered metadata types, declared in `metaobjects/` beside the entities they describe and loaded by the same loader — no side file, no bespoke parser. They record *why* each part of the model exists, so a field with no reason to exist becomes visible as one.
+
+Reach for it when the project needs to answer any of:
+
+- **"Why is this field here?"** — an L5 requirement binds a claim to a specific member. Authoring these exhaustively is what surfaces columns nothing reads and vocabularies nobody documented.
+- **"What is broken but known?"** — `@status: partial` plus `@disposition: accepted | deferred`. Absent disposition means *undecided*, and `meta verify` counts those: the gaps nobody has ruled on.
+- **"What did we build and then retire?"** — `@status: abandoned` is the one status where a dangling `@implementedBy` is *correct*, so the record survives the deletion.
+- **"What have we committed to build?"** — `@status: planned`. Its references may dangle, and it never counts toward object coverage.
+- **"Which ticket covers this?"** — `@trackedBy`.
+
+Every requirement must be **violable**: if you cannot say what breaking it looks like, it is a description, not a requirement.
+
+If the project declares any `requirement.*` node, `references/requirements.md` is installed with the full authoring rules. If it does not and you are adding the first one, the shape is:
+
+```yaml
+- requirement.architectural:
+    name: everyStoredRowIsAddressable
+    status: live
+    statement: Every persisted row declares the identity by which it is addressed.
+    violation: A row that can be inserted but never pointed at.
+    implementedBy: [acme::shop::Order]
+```
 
 ---
 

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

@@ -27,19 +27,69 @@ key. *"Things are persisted"* is not, and is a description rather than a require
 rule kills *"the system is reliable"*. If you cannot say what breaking it looks like,
 delete it.
 
-**Hierarchy is nesting, and links live at the bottom.** L1 solution, L2 segment (an
-application or library), L3 service — these never reference the model. **L4** binds an
-object, **L5** binds a field, view or identity. `implementedBy` above L4 is an error.
+**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:
+
+- `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
+- `violation` — **the counterexample** that makes the claim checkable
+- `description` — **the scope**: what the claim covers, what it deliberately does not, and
+  which sibling entry owns the rest
+- `notes` — **the evidence**: how you know the `status` is true — citations, vocabularies, the
+  control you ran to prove an absence was real
+
+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`.
+
+**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
+`object.*` **or a `template.*`** — and **L5** binds a member of one: a field, view,
+validator, identity, or a template's child. `implementedBy` above L4 is an error.
 Regrouping *moves* a node; it does not edit a parent string.
 
-**Architectural requirements are the other kind.** `requirement.architectural` carries no
-level — a uuid-PK rule, change attribution, tenant scoping. Its check is *universality*
+Claim your prompts. A `template.prompt` is a model node realising a capability exactly as
+an entity is, and it is the node whose retirement is hardest to see later — a removed
+prompt leaves no table behind. A prompt estate with no requirement entries is the same
+blind spot this whole mechanism exists to close.
+
+**L1–L3 are levels of abstraction and ownership in the problem domain** — whose need is
+this, and at what altitude — and are NEVER a directory, package, deployable or module.
+Technical constructs appear only at L4/L5, which is the allocation step. Test every node:
+*if a refactor that changes no behaviour would force it to move, its level is wrong.*
+
+**Architectural requirements are the other kind.** `requirement.architectural` is flat by
+default — a uuid-PK rule, change attribution, tenant scoping. Its check is *universality*
 rather than existence, so one that is `live` and claimed by nothing fails: a policy
-declared and applied to nothing.
+declared and applied to nothing. A `@level` is OPTIONAL here and opts the node into a tree
+(for organising non-functional requirements under a quality taxonomy); once levelled, the
+same nesting and link-floor rules apply as to a functional node.
 
 `@status` is a closed enum enforced by the loader, so a typo fails the load rather than
 silently disabling the entry.
 
+**Record gaps rather than rounding them off.** `partial` says *this works and here is what
+is wrong with it*, and it is the most useful status in the enum — a ledger with none is
+usually one nobody read carefully. Then say what was DECIDED, which is a separate question:
+
+- `@disposition: accepted` — understood, deliberately not being closed
+- `@disposition: deferred` — will be closed, not now (name a ticket in `@trackedBy`, or
+  `verify` warns; deferring without one is how a known problem becomes an unknown one)
+- **absent** — undecided, and that is a real state. `verify` counts these, because
+  *"which gaps has nobody ruled on?"* is the question a review exists to answer.
+
+A `partial` nobody intends to finish is usually `abandoned` — built then deliberately
+retired, the one status where a dangling reference is correct.
+
+**`status: planned` locks in work you have not started.** Its references may dangle (write
+the requirement before the entity), and it never counts toward object coverage — otherwise
+declaring an intention would clear the unclaimed-entity warning and the gate would measure
+ambition rather than work.
+
 ```yaml
 - requirement.functional:
     name: Pacing

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

@@ -35,9 +35,26 @@ mechanism exists to preserve.
 | `@implementedBy` above the L4 link floor | 1 |
 | live `requirement.architectural` claimed by nothing | 1 |
 | `@verifiedBy` naming a test that exists nowhere | 1 |
+| `@verifiedBy` naming a name found only in an **unrecognised** test file | 0 (warning) |
 | `@verifiedBy` naming a test that is **skipped** | 0 (warning) |
 | an entity no requirement claims | 0 (warning) |
 
+## What counts as a test file is YOUR project's call
+
+The scan ships patterns for jest/vitest/bun, JUnit, Maven Failsafe (`*IT`), xUnit/NUnit,
+pytest and Kotlin. Those are a convenience, **not an authority** — a built-in list is a guess
+about your repository, and a wrong guess reports a real test as a broken claim. Declare your
+conventions and they are added to the built-ins:
+
+```ts
+// metaobjects.config.ts
+export default defineConfig({ verify: { testFiles: ["**/*IT.kt", "**/*.feature"] } });
+```
+
+If a named test is missing from the corpus but present in some other source file, `verify`
+warns and names that file rather than failing — an unrecognised convention is the tool's
+ignorance, not your mistake.
+
 ## What a green run does NOT prove
 
 It proves **referential integrity**: statuses parse, levels are in range, links sit at or

package/package.json

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