@metaobjectsdev/sdk 0.22.1 → 0.23.0

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,63 @@ 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.
-Regrouping *moves* a node; it does not edit a parent string.
+**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:
 
-**Architectural requirements are the other kind.** `requirement.architectural` carries no
-level — a uuid-PK rule, change attribution, tenant scoping. Its check is *universality*
+- `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 an object, **L5** binds a field,
+view or identity. `implementedBy` above L4 is an error. Regrouping *moves* a node; it does
+not edit a parent string.
+
+**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/package.json

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