@metaobjectsdev/cli 0.24.1 → 0.24.2

package/src/lib/requirement-check.ts

@@ -48,8 +48,12 @@ export type Severity = "error" | "warn";
 export interface Diagnostic {
   severity: Severity;
   code: string;
-  /** The requirement node's name, when the diagnostic belongs to one. */
-  name?: string;
+  /** The subject's ADDRESS, when the diagnostic has one — the dotted child-name
+   *  path. Two branches of a ledger may reuse a NAME, so a bare name does not
+   *  locate the node, and a diagnostic you cannot locate is one you cannot act on.
+   *  Absent on a diagnostic whose subject is not a requirement (object coverage
+   *  names the entity in its message instead). */
+  path?: string;
   message: string;
 }
 
@@ -151,21 +155,107 @@ function subtreeClaimsAnything(req: MetaRequirement): boolean {
   return false;
 }
 
-/** Every `requirement.*` node in the tree, at any nesting depth. Hierarchy IS
- *  nesting — an L1 solution contains its L2 segments — so this is a walk, not a
- *  scan of a flat list keyed by a `parent` string. */
-export function collectRequirements(root: MetaData): MetaRequirement[] {
-  const out: MetaRequirement[] = [];
-  const walk = (n: MetaData): void => {
+/** A requirement paired with its ADDRESS — the dotted child-name path from the
+ *  root, which is how every other node in the model is addressed, and which the
+ *  requirement-test generator also turns into the stub's filename. */
+export interface AddressedRequirement {
+  readonly node: MetaRequirement;
+  readonly path: string;
+}
+
+/**
+ * Every `requirement.*` node in the tree, at any nesting depth, each with its
+ * dotted path. Hierarchy IS nesting — an L1 solution contains its L2 segments —
+ * so this is a walk, not a scan of a flat list keyed by a `parent` string.
+ *
+ * ONE derivation of the address for the gate AND the authoring lint, deliberately.
+ * They are two sections of a single `meta verify` run, and when they walked
+ * separately they addressed the same node two different ways — the gate by bare
+ * `name`, which is ambiguous the moment two branches of a ledger reuse one, and the
+ * lint by path. A reader cannot reconcile two addressings of one tree.
+ *
+ * The traversal descends through EVERY node rather than only through requirements:
+ * a requirement somewhere the child rules did not anticipate is still gated, which
+ * is the fail-closed direction for a gate.
+ */
+export function collectAddressedRequirements(root: MetaData): AddressedRequirement[] {
+  const out: AddressedRequirement[] = [];
+  const walk = (n: MetaData, prefix: string): void => {
     for (const c of n.children()) {
-      if (c.type === TYPE_REQUIREMENT) out.push(c as MetaRequirement);
-      walk(c);
+      // Only a requirement contributes a path segment. An intervening non-requirement
+      // node is traversed THROUGH, so the address stays the requirement hierarchy.
+      const isReq = c.type === TYPE_REQUIREMENT;
+      const path = isReq ? (prefix === "" ? c.name : `${prefix}.${c.name}`) : prefix;
+      if (isReq) out.push({ node: c as MetaRequirement, path });
+      walk(c, path);
     }
   };
-  walk(root);
+  walk(root, "");
   return out;
 }
 
+
+/**
+ * Resolve a `@supersededBy` reference to a requirement in the same ledger (FR-039).
+ *
+ * A requirement is addressed the way every other node is: a package qualifies the
+ * ROOT-level node only, and each dotted segment after it walks CHILD names — so
+ * `acme::caps::Billing.InvoiceRecord` names the `InvoiceRecord` child of the
+ * root-level `Billing`. A bare reference binds package-locally first and then at
+ * root level, which is the ADR-0042 contract every other reference already follows.
+ *
+ * Deliberately resolves against the LEDGER, not the model: a capability is replaced
+ * by another capability. Pointing this at an entity would be `@implementedBy` wearing
+ * a different name, and `@implementedBy` is exactly what a retired entry may not have.
+ */
+export function resolveRequirementRef(
+  addressed: readonly AddressedRequirement[],
+  ref: string,
+  referrerPkg: string,
+): MetaRequirement | undefined {
+  const keyed = new Map<string, MetaRequirement>();
+  for (const { node, path } of addressed) {
+    const pkg = node.package ?? node.fileDefaultPackage ?? "";
+    if (pkg !== "") keyed.set(`${pkg}::${path}`, node);
+    // Bare path is registered too, so a single-package ledger can reference
+    // without repeating its own package on every line.
+    if (!keyed.has(path)) keyed.set(path, node);
+  }
+  // An FQN binds exactly; a bare ref prefers the referrer's own package.
+  const exact = keyed.get(ref);
+  if (exact !== undefined) return exact;
+  if (referrerPkg !== "") {
+    const local = keyed.get(`${referrerPkg}::${ref}`);
+    if (local !== undefined) return local;
+  }
+  return undefined;
+}
+
+/** The nodes alone, for callers with no use for the address. */
+export function collectRequirements(root: MetaData): MetaRequirement[] {
+  return collectAddressedRequirements(root).map((r) => r.node);
+}
+
+/**
+ * What one `meta verify` run computes once and both requirement passes read.
+ *
+ * The gate and the summary each need the same two things, and each used to derive
+ * both for itself — so a run walked the model twice and resolved every
+ * `@implementedBy` claim twice, the second of which is the expensive half
+ * (resolution is O(claims x root objects)). Threading the result rather than the
+ * function is what the "SHARED by the gate and the summary" note on
+ * `claimedObjectKeys` was always asking for.
+ */
+export interface RequirementScan {
+  readonly addressed: readonly AddressedRequirement[];
+  readonly claimedObjects: ReadonlySet<string>;
+}
+
+export function scanRequirements(root: MetaData): RequirementScan {
+  const addressed = collectAddressedRequirements(root);
+  return { addressed, claimedObjects: claimedObjectKeys(root, addressed.map((r) => r.node)) };
+}
+
 /**
  * Resolution keys of every object claimed by a requirement.
  *
@@ -232,14 +322,12 @@ function coverableEntities(root: MetaData): MetaData[] {
  * prove: that a status is *true*, or that a node actually implements the
  * requirement claiming it. No test can. That truth is the adopter's job.
  */
-export function checkRequirements(root: MetaData): Diagnostic[] {
+export function checkRequirements(root: MetaData, scan: RequirementScan = scanRequirements(root)): Diagnostic[] {
   const out: Diagnostic[] = [];
-  const reqs = collectRequirements(root);
-  if (reqs.length === 0) return out; // opt-in by declaration — no requirements, nothing to say
-
-  const claimedObjects = claimedObjectKeys(root, reqs);
+  const { addressed, claimedObjects } = scan;
+  if (addressed.length === 0) return out; // opt-in by declaration — no requirements, nothing to say
 
-  for (const req of reqs) {
+  for (const { node: req, path: reqPath } of addressed) {
     const architectural = req.subType === REQUIREMENT_SUBTYPE_ARCHITECTURAL;
     const level = req.level();
     const refs = req.implementedBy();
@@ -258,7 +346,7 @@ export function checkRequirements(root: MetaData): Diagnostic[] {
       if (!levelled || !Number.isInteger(level)
           || level < REQUIREMENT_MIN_LEVEL || level > REQUIREMENT_MAX_LEVEL) {
         out.push({
-          severity: "error", code: ERR_REQUIREMENT_BAD_LEVEL, name: req.name,
+          severity: "error", code: ERR_REQUIREMENT_BAD_LEVEL, path: reqPath,
           message: `level must be an integer ${REQUIREMENT_MIN_LEVEL}-${REQUIREMENT_MAX_LEVEL} (got ${String(level)}). ` +
             `L1 solution, L2 segment (app/library), L3 service, L4 object, L5 member.` +
             (architectural ? ` On an architectural requirement the level is optional — omit it for a flat policy.` : ``),
@@ -270,7 +358,7 @@ export function checkRequirements(root: MetaData): Diagnostic[] {
         const pl = (parent as MetaRequirement).level();
         if (pl !== undefined && level !== undefined && level <= pl) {
           out.push({
-            severity: "error", code: ERR_REQUIREMENT_LEVEL_NESTING, name: req.name,
+            severity: "error", code: ERR_REQUIREMENT_LEVEL_NESTING, path: reqPath,
             message: `nested under "${parent.name}" (level ${pl}) but declares level ${level}. ` +
               `Nesting is the hierarchy — a child sits strictly below its parent.`,
           });
@@ -281,7 +369,7 @@ export function checkRequirements(root: MetaData): Diagnostic[] {
     // -- the link boundary ----------------------------------------------------
     if (refs.length > 0 && !req.mayReferenceModel()) {
       out.push({
-        severity: "error", code: ERR_REQUIREMENT_LINK_ABOVE_FLOOR, name: req.name,
+        severity: "error", code: ERR_REQUIREMENT_LINK_ABOVE_FLOOR, path: reqPath,
         message: `'implementedBy' is legal at L${REQUIREMENT_LINK_FLOOR_LEVEL} (object) and ` +
           `L${REQUIREMENT_MAX_LEVEL} (member) only. L1-L3 are organisational and never reference ` +
           `the model — move the links to a nested L${REQUIREMENT_LINK_FLOOR_LEVEL} child.`,
@@ -310,7 +398,7 @@ export function checkRequirements(root: MetaData): Diagnostic[] {
       // promised.
       if (!architectural && level === REQUIREMENT_LINK_FLOOR_LEVEL && !isObjectRef) {
         out.push({
-          severity: "error", code: ERR_REQUIREMENT_L4_NOT_OBJECT, name: req.name,
+          severity: "error", code: ERR_REQUIREMENT_L4_NOT_OBJECT, path: reqPath,
           message: `L${REQUIREMENT_LINK_FLOOR_LEVEL} references an object; '${ref}' names a member. ` +
             `Move it to a nested L${REQUIREMENT_LEVEL_MEMBER} child, or reference the object itself.`,
         });
@@ -318,7 +406,7 @@ export function checkRequirements(root: MetaData): Diagnostic[] {
       }
       if (!architectural && level === REQUIREMENT_LEVEL_MEMBER && isObjectRef) {
         out.push({
-          severity: "error", code: ERR_REQUIREMENT_L5_NOT_MEMBER, name: req.name,
+          severity: "error", code: ERR_REQUIREMENT_L5_NOT_MEMBER, path: reqPath,
           message: `L${REQUIREMENT_LEVEL_MEMBER} references a member (field, view or identity); ` +
             `'${ref}' names an object. Move it to its L${REQUIREMENT_LINK_FLOOR_LEVEL} parent.`,
         });
@@ -332,7 +420,7 @@ export function checkRequirements(root: MetaData): Diagnostic[] {
         // job, and the reason this check cannot live in the loader.
         if (req.requiresLiveNodes()) {
           out.push({
-            severity: "error", code: ERR_REQUIREMENT_DANGLING_REF, name: req.name,
+            severity: "error", code: ERR_REQUIREMENT_DANGLING_REF, path: reqPath,
             message: `'${ref}' does not resolve in the loaded model (status '${String(req.status())}' — ` +
               `the model moved and the requirement is stale).` + didYouMeanHint(root, owner),
           });
@@ -340,6 +428,32 @@ export function checkRequirements(root: MetaData): Diagnostic[] {
       }
     }
 
+    // -- @supersededBy resolution (FR-039) ------------------------------------
+    // The 2026-08-10 ruling asked for exactly this at point 4 — "a supersededBy
+    // that RESOLVES (FQN-checked, so verify can fail on a dangling one), turning
+    // 'deleted in S6' from an inert comment into a build gate" — and 0.24.0
+    // deregistered the unresolved string version without ever building it.
+    //
+    // Resolution is what makes a supersession CHAIN survive. A prose note points
+    // one hop and rots when that hop is itself retired; a resolved reference does
+    // not, because the target is a real node carrying its own @supersededBy.
+    //
+    // The target is a REQUIREMENT, not a model node: a capability is replaced by
+    // another capability. It resolves package-locally under ADR-0042 through the
+    // requirement's own effective package, exactly as @implementedBy does.
+    const superseded = req.supersededBy();
+    if (superseded !== undefined) {
+      const referrerPkg = req.package ?? req.fileDefaultPackage ?? "";
+      if (resolveRequirementRef(addressed, superseded, referrerPkg) === undefined) {
+        out.push({
+          severity: "error", code: ERR_REQUIREMENT_DANGLING_REF, path: reqPath,
+          message: `@supersededBy '${superseded}' does not name a requirement in the loaded ` +
+            `ledger. It must name the requirement that REPLACED this one — if nothing did, ` +
+            `drop the attribute and let \`notes\` carry why the capability went.`,
+        });
+      }
+    }
+
     // -- architectural universality, v1: claim-set arithmetic -----------------
     // A live policy claimed by nothing is the audited-base case: declared and
     // applied to nothing. Deliberately NOT a violation-predicate DSL — that
@@ -362,7 +476,7 @@ export function checkRequirements(root: MetaData): Diagnostic[] {
     // levelled one, true again at the link floor.
     if (architectural && live && refs.length === 0 && req.mayReferenceModel()) {
       out.push({
-        severity: "error", code: ERR_REQUIREMENT_ARCH_NO_IMPLEMENTERS, name: req.name,
+        severity: "error", code: ERR_REQUIREMENT_ARCH_NO_IMPLEMENTERS, path: reqPath,
         message: `architectural requirement is '${String(status)}' but nothing implements it. ` +
           `Its check is universality — a claim set of zero means the policy is declared and unapplied.`,
       });
@@ -372,7 +486,7 @@ export function checkRequirements(root: MetaData): Diagnostic[] {
     const disposition = req.disposition();
     if (disposition !== undefined && !req.hasOutstandingWork()) {
       out.push({
-        severity: "warn", code: WARN_REQUIREMENT_DISPOSITION_NOT_APPLICABLE, name: req.name,
+        severity: "warn", code: WARN_REQUIREMENT_DISPOSITION_NOT_APPLICABLE, path: reqPath,
         message: `carries @disposition '${disposition}' but its status is '${String(status)}', which has no ` +
           `outstanding work to decide about. A disposition is meaningful on 'planned' and 'partial' only — ` +
           `on any other status the decision IS the status.`,
@@ -387,7 +501,7 @@ export function checkRequirements(root: MetaData): Diagnostic[] {
     // is empty is a capability declared and built by nobody.
     if (!architectural && live && !subtreeClaimsAnything(req)) {
       out.push({
-        severity: "warn", code: WARN_REQUIREMENT_NOTHING_IMPLEMENTS, name: req.name,
+        severity: "warn", code: WARN_REQUIREMENT_NOTHING_IMPLEMENTS, path: reqPath,
         message: `is '${String(status)}' but neither it nor anything nested under it names an ` +
           `implementing node. A functional requirement's check is existence — a subtree that claims ` +
           `nothing is a capability nobody built.`,
@@ -396,7 +510,7 @@ export function checkRequirements(root: MetaData): Diagnostic[] {
 
     if (disposition === REQUIREMENT_DISPOSITION_DEFERRED && req.trackedBy().length === 0) {
       out.push({
-        severity: "warn", code: WARN_REQUIREMENT_DEFERRED_UNTRACKED, name: req.name,
+        severity: "warn", code: WARN_REQUIREMENT_DEFERRED_UNTRACKED, path: reqPath,
         message: `is deferred but names no @trackedBy issue. Deferring without a ticket is how a known gap ` +
           `becomes an unknown one — nothing will raise it again.`,
       });
@@ -447,8 +561,11 @@ export function checkRequirements(root: MetaData): Diagnostic[] {
  * are deliberately the ones an author would otherwise have to write a script to
  * get: how many gaps are recorded, and how many of those nobody has ruled on.
  */
-export function summariseRequirements(root: MetaData): RequirementSummary | undefined {
-  const reqs = collectRequirements(root);
+export function summariseRequirements(
+  root: MetaData,
+  scan: RequirementScan = scanRequirements(root),
+): RequirementSummary | undefined {
+  const reqs = scan.addressed.map((r) => r.node);
   if (reqs.length === 0) return undefined; // opt-in by declaration
 
   const summary: RequirementSummary = {
@@ -475,9 +592,10 @@ export function summariseRequirements(root: MetaData): RequirementSummary | unde
     }
   }
 
-  // Both sides of the ratio come from the SAME helpers the gate uses, so the
-  // printed summary cannot disagree with the diagnostics printed beneath it.
-  const claimed = claimedObjectKeys(root, reqs);
+  // Both sides of the ratio come from the SAME scan the gate read, so the printed
+  // summary cannot disagree with the diagnostics printed beneath it — previously
+  // the same helper, now literally the same result.
+  const claimed = scan.claimedObjects;
   for (const ent of coverableEntities(root)) {
     summary.entitiesTotal++;
     if (claimed.has(ent.resolutionKey())) summary.entitiesClaimed++;

package/src/lib/requirement-lint.ts

@@ -0,0 +1,356 @@
+// `meta verify` — the requirement AUTHORING lint.
+//
+// A different kind of claim from the gate in `requirement-check.ts`, which is why
+// it is a separate function rather than more branches inside `checkRequirements`.
+//
+//   THE GATE   referential integrity — links sit at or below the floor, nesting
+//              agrees with levels, references resolve. A finding there means the
+//              ledger DISAGREES WITH THE MODEL.
+//   THE LINT   authoring quality — the name is addressable, the prose slots hold
+//              distinct content, nothing was written into a slot no surface reads.
+//              A finding here means the ledger is INTERNALLY WASTEFUL: it still
+//              agrees with the model, it just records less than its author thinks.
+//
+// Keeping them apart is not tidiness. `meta verify` prints at most 20 warnings, and
+// a ledger with 240 entries can produce hundreds of prose findings — enough to push
+// every WARN_REQUIREMENT_OBJECT_UNCLAIMED off the end of the list. Two sections with
+// two caps means the lint cannot drown the gate.
+//
+// IT READS THE LOADED MODEL, NEVER THE FILES. Extensions and overlays mean the text
+// on disk is not the effective model: an attr set in one file and overridden in
+// another, or inherited through `extends`, reads differently from every angle except
+// the loaded tree. A raw-file linter would be wrong for any project using either.
+//
+// EVERY FINDING IS A WARNING, BY CONSTRUCTION — not by a switch. Stated as a rule so
+// the next check added here follows it: a check newly added to a shipping gate cannot
+// be shown not to fire on an estate that already exists, and prose findings that turn
+// `meta verify` red on upgrade teach people to switch the gate off, which costs more
+// than the padding they caught. The precedent is object coverage, which stayed a
+// warning because on one real estate it reported every entity in the repository.
+//
+// There is deliberately NO severity constant to flip. `verify` prints this section
+// with `log.warn` unconditionally and computes its exit code from the GATE alone, so
+// a constant here would have promised a promotion it could not deliver. If a check in
+// this file ever has to fail a build, the honest move is to move the check into the
+// gate — which is a decision about what the check IS, not a severity edit.
+
+import {
+  DOC_ATTR_DESCRIPTION,
+  DOC_ATTR_SUMMARY,
+  DOC_ATTR_TITLE,
+  REQUIREMENT_ATTR_COUNTEREXAMPLE,
+  REQUIREMENT_ATTR_STATEMENT,
+  REQUIREMENT_ATTR_TRACKED_BY,
+  // The port's ONE identifier splitter, used here for its word boundaries rather
+  // than its underscores: `normalise` lowercases and maps every separator to a
+  // space, so `toSnakeCase(name)` and a hand-rolled camel split are identical
+  // downstream (checked over 20k random identifiers). Sharing it means the lint
+  // splits a name the same way the column/table/kebab namers do — a private copy
+  // would silently stop agreeing the day that rule is corrected.
+  toSnakeCase,
+  type MetaData,
+} from "@metaobjectsdev/metadata";
+// The SAME collection the gate walks, so the two sections of one `meta verify` run
+// address a node identically — and the dotted path each reports is the address the
+// requirement-test generator turns into the stub's filename. (Pinned by a test that
+// compares this path set against `walkRequirements()`, the generator's own walk,
+// rather than leaving the two to agree by inspection.)
+import {
+  collectAddressedRequirements, type AddressedRequirement, type Diagnostic,
+} from "./requirement-check.js";
+
+export const WARN_REQUIREMENT_NAME_NOT_ADDRESSABLE = "WARN_REQUIREMENT_NAME_NOT_ADDRESSABLE";
+export const WARN_REQUIREMENT_NAME_READS_AS_PROSE = "WARN_REQUIREMENT_NAME_READS_AS_PROSE";
+export const WARN_REQUIREMENT_NAME_RESTATES_STATEMENT = "WARN_REQUIREMENT_NAME_RESTATES_STATEMENT";
+export const WARN_REQUIREMENT_PROSE_DUPLICATED = "WARN_REQUIREMENT_PROSE_DUPLICATED";
+export const WARN_REQUIREMENT_PROSE_EMPTY = "WARN_REQUIREMENT_PROSE_EMPTY";
+export const WARN_REQUIREMENT_INERT_DOC_SLOT = "WARN_REQUIREMENT_INERT_DOC_SLOT";
+export const WARN_REQUIREMENT_TITLE_IS_AN_ID = "WARN_REQUIREMENT_TITLE_IS_AN_ID";
+
+/**
+ * Characters that break the two things a requirement's `name` IS.
+ *
+ *   `.`  the dotted-path separator. A name containing one is INDISTINGUISHABLE
+ *        from nesting: a single node named "Orders.Recorded" and a node "Orders"
+ *        containing a node "Recorded" both produce the path `Orders.Recorded`, so
+ *        the address stops identifying one node and the two collide on the same
+ *        emitted stub file.
+ *   `/`  `\`  path separators. The default stub path is
+ *        `requirements/<path>.test.ts`, so a name of `../../thing` writes OUTSIDE
+ *        the stub directory — and `owns()`, which is what lets the runner reap a
+ *        stub whose requirement was deleted, will never claim it back.
+ *   the rest  illegal in a filename on Windows, so the stub cannot be written at
+ *        all there. `:` doubles as half of the `::` package separator.
+ *
+ * Every one of these loads today: the loader constrains a requirement's name no
+ * more than any other node's, and nothing downstream re-checks it.
+ *
+ * A SEAM, recorded so the decision stays visible: the general form of this rule is
+ * not requirement-specific at all — a `.` in ANY node's name breaks the dotted
+ * child-name addressing the whole metamodel uses — so it arguably belongs in the
+ * loader as a cross-port warning, beside WARN_ENUM_NORMALIZE_AMBIGUOUS. It is
+ * scoped here because the requirement surface is where it currently bites (a name
+ * becomes a stub FILENAME only here), and because promoting it means five ports,
+ * expected-warnings.json, conformance fixtures and a metamodelVersion question.
+ * That is an FR, not a line in this file.
+ */
+const UNADDRESSABLE = /[./\\:*?"<>|\p{Cc}]/gu;
+
+/** How one offending character is named in the message, so the author is told which
+ *  one to remove rather than left to diff their name against a regex.
+ *
+ *  Only `.` needs a written entry — the rest are self-describing once quoted, and a
+ *  hand-written entry per character was a table that had to be kept in step with
+ *  UNADDRESSABLE: adding a character to the regex and forgetting the table printed
+ *  a bare code point where the character itself was meant. Derived, so it cannot
+ *  drift. */
+function describeChar(c: string): string {
+  if (c === ".") return "'.' (the dotted-path separator)";
+  // A control character has no printable form to quote, so name its code point.
+  return /\p{Cc}/u.test(c) ? `U+${c.charCodeAt(0).toString(16).padStart(4, "0")}` : `'${c}'`;
+}
+
+/**
+ * Word count at which a name stops reading as a label and starts reading as prose.
+ *
+ * A threshold, and the only one in this file — chosen high on purpose. Five words
+ * is still plausibly a label ("Order recording for placed orders"); six is a
+ * sentence. Under-firing is the right failure here: renaming a requirement changes
+ * its address AND its emitted stub filename, so a false positive asks the author to
+ * pay a migration for nothing.
+ */
+const PROSE_WORD_COUNT = 6;
+
+/**
+ * Slots that say nothing on a requirement — and the two deliberate exclusions.
+ *
+ * `summary` qualifies: `@statement` is REQUIRED on both subtypes and is already the
+ * one-line sentence, so a summary beside it can only repeat it, and nothing reads
+ * it. `spec/capability-ledger.md`'s requirement attribute table does not list it.
+ *
+ * `title` is NOT on this list, and an earlier version of this file had it there —
+ * wrongly. That same attribute table charters it BY NAME on a requirement ("a short
+ * noun-phrase label — `name` is an identifier, this is what an index shows"), which
+ * is exactly this node type's situation: a requirement's address renders as a dotted
+ * camelCase path. Measured against three real ledgers the ban would have told two
+ * adopters to delete 355 authored labels, 123 of which carry words the name does not.
+ * That the requirements page does not render `title` yet is a gap in the RENDERER,
+ * and a tool reporting its own backlog in an adopter's terminal is noise.
+ *
+ * `notes` is excluded for the opposite reason: chartered internal-only, so being
+ * unrendered is the point of it.
+ */
+const INERT_SLOTS = [DOC_ATTR_SUMMARY] as const;
+
+/**
+ * A catalogue or ticket id at the head of a label — `FR-448 …`, `PLAT-77 …`.
+ *
+ * The real failure the id case represents is FIELD OVERLOADING, not an unread slot:
+ * a citation lives in the display label because nothing else was offered, and
+ * `@trackedBy` (free-form, deliberately never resolved) is what was. The measured
+ * values carry an id AND a noun phrase — "FR-448 — prompt construction as typed
+ * payloads through a render engine" — so the fix is to SPLIT them. Moving the whole
+ * string to `@trackedBy` would throw the label away, which is why the message says
+ * split rather than move.
+ */
+const TITLE_IS_AN_ID = /^[A-Z]{2,}[- ]?\d+/;
+
+/** Lowercase, drop everything that is not alphanumeric, collapse the gaps.
+ *  Two slots "say the same thing" only if they survive this identically — no
+ *  similarity score, no threshold. A fuzzy match on prose produces findings the
+ *  author can argue with, and a gate people argue with is a gate people mute. */
+function normalise(text: string): string {
+  return text.toLowerCase().replace(/[^a-z0-9]+/g, " ").trim();
+}
+
+/** Whether `text`'s LEADING sentence says the same thing as `key`. False when the
+ *  text is a single sentence — the caller's whole-string comparison covers that.
+ *
+ *  Newlines are collapsed FIRST. A `description` is routinely authored as a YAML
+ *  literal block, so the repeated opening sentence usually wraps — and `.` in a JS
+ *  regex does not cross a newline, which made this arm silently miss exactly the
+ *  authoring style most likely to trip it. The whole-string arm never had the bug
+ *  because `normalise` already flattens whitespace. */
+function leadingSentenceMatches(text: string, key: string): boolean {
+  const flat = text.replace(/\s+/g, " ").trim();
+  const m = /^(.+?[.!?])\s+\S/.exec(flat);
+  return m?.[1] !== undefined && normalise(m[1]) === key;
+}
+
+/** A resolving string read, normalised so "declared but blank" and "absent" are
+ *  distinguishable — the first is a finding, the second usually is not.
+ *  `attr()` RESOLVES in TypeScript (ADR-0039), so a requirement inheriting its
+ *  prose through `extends` is linted on what it effectively carries. */
+function readSlot(node: MetaData, name: string): string | undefined {
+  const raw = node.attr(name);
+  return typeof raw === "string" ? raw : undefined;
+}
+
+/**
+ * An OWN-ONLY string read — one of the two sanctioned `own*()` uses in this file
+ * (ADR-0039 requires every such call to name its case).
+ *
+ * The checks split by what they are ABOUT, and the split decides the accessor:
+ *
+ *   RESOLVING  a check about what a node effectively SAYS. Two slots holding one
+ *              sentence is a property of the effective node — a child may override
+ *              one slot and inherit the other, and only the resolved pair shows it.
+ *   OWN-ONLY   a check about a DECLARATION, whose fix is a single edit at a single
+ *              node. `title` set once on an abstract is inherited by every child, so
+ *              a resolving read reports it once per child at addresses where the
+ *              author will find no `title` to delete — on a ledger using the shared
+ *              abstract idiom, one mistake can fill the whole lint cap with lines
+ *              nobody can act on where they are pointed.
+ */
+function readOwnSlot(node: MetaData, name: string): string | undefined {
+  const raw = node.ownAttr(name);
+  return typeof raw === "string" ? raw : undefined;
+}
+
+/** Echo an authored value back inside a message without letting a long one take over
+ *  the terminal. Findings are printed one per line and a `description`-length slot
+ *  would wrap for a dozen of them. */
+function excerpt(value: string): string {
+  const LIMIT = 80;
+  const flat = value.replace(/\s+/g, " ").trim();
+  return JSON.stringify(flat.length > LIMIT ? `${flat.slice(0, LIMIT - 1)}…` : flat);
+}
+
+function warn(path: string, code: string, message: string): Diagnostic {
+  return { severity: "warn", code, path, message };
+}
+
+/**
+ * Lint every `requirement.*` node in the loaded model.
+ *
+ * Returns `[]` for a model declaring none — opt-in by declaration, the same way
+ * the gate and the docs surface are, so turning this on by default is a no-op for
+ * every project without a ledger.
+ *
+ * What it CANNOT tell you: whether a statement is true, whether a description is
+ * useful, or whether the counterexample would actually falsify the claim. Those
+ * are the judgements the ledger exists to record and no check reaches them. Every
+ * finding below is about a slot's MECHANICS — is this content reachable, is it
+ * distinct from its neighbour, is the name still an address.
+ */
+export function lintRequirements(
+  root: MetaData,
+  /** The run's already-collected requirements, when one exists. The lint takes the
+   *  ADDRESSES alone rather than the gate's full `RequirementScan`: it has nothing
+   *  to do with who claims what, and asking for the claim set would make a
+   *  standalone call pay for a resolution it never reads. */
+  addressed: readonly AddressedRequirement[] = collectAddressedRequirements(root),
+): Diagnostic[] {
+  const out: Diagnostic[] = [];
+
+  for (const { node, path } of addressed) {
+    const name = node.name;
+
+    // -- the name is an address, not prose ------------------------------------
+    // EVERY problem with one name is reported in ONE finding. These were two
+    // branches of an if/else, so a name that was both padded and dotted reported
+    // only the dot: the author fixed it, re-ran, and was told about the padding on
+    // a second pass. One name is one edit, so it is one finding.
+    const problems: string[] = [];
+    const offenders = [...new Set(name.match(UNADDRESSABLE) ?? [])];
+    if (offenders.length > 0) {
+      problems.push(`contains ${offenders.map(describeChar).join(", ")}`);
+    }
+    if (name.trim() === "") problems.push("is blank");
+    else if (name.trim() !== name) problems.push("has leading or trailing whitespace");
+    if (problems.length > 0) {
+      out.push(warn(path, WARN_REQUIREMENT_NAME_NOT_ADDRESSABLE,
+        `name ${JSON.stringify(name)} ${problems.join(", and ")}. A requirement's name is its ` +
+        `address — it is the segment of the dotted path '${path}' and the filename of its generated ` +
+        `test stub — so this either collides with nesting or produces a path the stub cannot be ` +
+        `written to.`));
+    }
+
+    const statementKey = normalise(readSlot(node, REQUIREMENT_ATTR_STATEMENT) ?? "");
+
+    // -- the name is not the claim --------------------------------------------
+    // Ordered before the prose-shape check and exclusive with it: when the name IS
+    // the statement, "rename it" is the wrong instruction. The instruction is "you
+    // have written the claim twice; @statement is the one that is read".
+    if (statementKey !== "" && normalise(toSnakeCase(name)) === statementKey) {
+      out.push(warn(path, WARN_REQUIREMENT_NAME_RESTATES_STATEMENT,
+        `name '${name}' says the same thing as @statement. The claim belongs in @statement, which every ` +
+        `surface reads; the name is an address and is better as a short identifier.`));
+    } else if (name.trim().split(/\s+/).filter((w) => w !== "").length >= PROSE_WORD_COUNT) {
+      out.push(warn(path, WARN_REQUIREMENT_NAME_READS_AS_PROSE,
+        `name '${name}' reads as a sentence. The name is an address — the dotted path other entries and ` +
+        `the generated stub filename are built from — so a short identifier keeps both legible. Put the ` +
+        `prose in @statement.`));
+    }
+
+    // -- required prose that is present but says nothing -----------------------
+    // The loader enforces PRESENCE (min: 1), never content, so `statement: ""`
+    // loads clean today and satisfies a required attribute with nothing in it.
+    for (const slot of [REQUIREMENT_ATTR_STATEMENT, REQUIREMENT_ATTR_COUNTEREXAMPLE]) {
+      // OWN-ONLY: the fix is deleting or filling one declaration. See readOwnSlot.
+      const value = readOwnSlot(node, slot);
+      if (value !== undefined && value.trim() === "") {
+        out.push(warn(path, WARN_REQUIREMENT_PROSE_EMPTY,
+          `@${slot} is declared but empty. The loader requires the attribute to be present, not to say ` +
+          `anything — an empty one passes every check while recording nothing.`));
+      }
+    }
+
+    // -- two slots holding one sentence ---------------------------------------
+    // The padding failure the authoring guidance names: restating the claim under a
+    // second heading reads as diligence and makes every later reader trust the
+    // ledger less. Only EXACT repeats are reported, whole or as the description's
+    // leading sentence; paraphrase is the broader failure and no mechanical rule
+    // reaches it without inventing findings.
+    if (statementKey !== "") {
+      // No blank-check needed: this arm only runs when `statementKey` is non-empty,
+      // and a blank description normalises to "" — which cannot equal it. That makes
+      // this guard identical to the `counterexample` arm below.
+      const description = readSlot(node, DOC_ATTR_DESCRIPTION);
+      if (description !== undefined) {
+        if (normalise(description) === statementKey) {
+          out.push(warn(path, WARN_REQUIREMENT_PROSE_DUPLICATED,
+            `description repeats @statement verbatim. @statement already IS the description of what the ` +
+            `requirement is; description holds the SCOPE — what the claim covers, what it deliberately ` +
+            `does not, which sibling entry owns the rest. If the scope is obvious, leave it off.`));
+        } else if (leadingSentenceMatches(description, statementKey)) {
+          out.push(warn(path, WARN_REQUIREMENT_PROSE_DUPLICATED,
+            `description opens by repeating @statement verbatim, then continues. Drop the first sentence — ` +
+            `it is already read from @statement, and description is only the scope that follows it.`));
+        }
+      }
+
+      const counterexample = readSlot(node, REQUIREMENT_ATTR_COUNTEREXAMPLE);
+      if (counterexample !== undefined && normalise(counterexample) === statementKey) {
+        out.push(warn(path, WARN_REQUIREMENT_PROSE_DUPLICATED,
+          `@counterexample repeats @statement verbatim. It must describe what BREAKING the claim looks ` +
+          `like — the thing you could point at to falsify it — which is what makes the claim checkable.`));
+      }
+    }
+
+    // -- content written where nothing reads it --------------------------------
+    for (const slot of INERT_SLOTS) {
+      // OWN-ONLY: the fix is deleting one attribute. See readOwnSlot.
+      const value = readOwnSlot(node, slot);
+      if (value === undefined || value.trim() === "") continue;
+      out.push(warn(path, WARN_REQUIREMENT_INERT_DOC_SLOT,
+        `@${slot} says nothing here that @${REQUIREMENT_ATTR_STATEMENT} does not. A requirement's ` +
+        `statement is REQUIRED and is already the one-line sentence, so a summary beside it can only ` +
+        `repeat it — and no requirement surface reads it. Its content is invisible: ${excerpt(value)}. ` +
+        `Delete it. (@title is different and is NOT flagged: it is chartered as the entry's LABEL, ` +
+        `because a requirement's name is an identifier.)`));
+    }
+
+    // -- an id is not a label -------------------------------------------------
+    const title = readOwnSlot(node, DOC_ATTR_TITLE);
+    if (title !== undefined && TITLE_IS_AN_ID.test(title.trim())) {
+      out.push(warn(path, WARN_REQUIREMENT_TITLE_IS_AN_ID,
+        `@title opens with a catalogue or ticket id: ${excerpt(title)}. A title is a NOUN PHRASE and ` +
+        `an id is not a name, so this is two things in one slot. SPLIT them — put the id in ` +
+        `@${REQUIREMENT_ATTR_TRACKED_BY}, which is the free-form reference slot and IS read, and leave ` +
+        `the phrase as the title. Moving the whole string would throw the label away.`));
+    }
+  }
+
+  return out;
+}