@ybotok/loam 0.2.0-alpha.1 → 0.2.0-alpha.13

package/examples/docs/services/platform/notification-service/model.likec4

@@ -1,35 +1,21 @@
-// Per-service C4. Written by an agent from the `loam adopt` brief, then curated.
+// notification-service's own C4 — what is INSIDE the element the fleet map binds
+// to services/platform/notification-service/. Written by an agent from the
+// `loam adopt` brief, then curated.
 //
-// Every .likec4 file is parsed ALONE, so the kinds this document uses have to be
-// declared in this document: a `specification` block here is not a duplicate of
-// the landscape's, it is what makes this file readable without it.
-specification {
-  element softwareSystem
-  element container
-  element database
-  // Declared because the consumption edges below point at CHANNELS rather than
-  // at the broker. Three edges into one `kafka` box would say only "talks to
-  // kafka"; three edges into three topics say which contracts this service is
-  // standing on, and they line up one-for-one with the channels in
-  // asyncapi.yaml.
-  element topic {
-    style {
-      shape queue
-    }
-  }
-}
-
+// An EXTENDING model: no `specification` block, no partner copies. The topics
+// this service consumes — `kafka.orderEvents`, `kafka.paymentEvents`,
+// `kafka.crmEvents` — are the MAP's, declared there once with the `topic` kind
+// that carries `#external` and `#platform`; this file points at them. So is
+// `notificationProvider`, the third-party gateway: a system this service reaches
+// belongs in architecture/landscape.likec4, and declaring a copy of it here
+// would be `c4.element-unowned`. `extend` takes the fully-qualified id because
+// the element is nested in the `marketplace` group.
+//
+// SCHEMA.md, "Two shapes of a service model", has the standalone shape — a model
+// that declares its own `specification` and is therefore parsed alone — and the
+// ordered recipe for migrating one to this shape.
 model {
-  notificationService = softwareSystem 'notification-service' {
-    description 'Turns fleet events into customer email and SMS'
-    // The binding, not the title, is what ties this element to
-    // services/notification-service/. With only a title, renaming the box in a
-    // diagram silently detaches every join that runs through it — health.yaml's
-    // dependencies, `Covers:` entries, the landscape's service checks.
-    metadata {
-      service 'notification-service'
-    }
-
+  extend marketplace.notificationService {
     consumer = container 'consumer' {
       description 'Kafka consumer group; one handler per message name'
       technology 'Go'
@@ -39,11 +25,10 @@ model {
       technology 'Go'
     }
     // Both stores are nested INSIDE the service and neither is drawn beside it
-    // in the landscape: a store with one consumer drawn as a fleet-level peer
-    // reads as a system other services may depend on, which is what
-    // `landscape.datastore-private` pushes back on. Neither appears in
-    // health.yaml's dependencies either — they share this service's lifecycle
-    // rather than being something it reaches across a boundary.
+    // in the landscape — the example's choice, and one loam does not grade
+    // either way. Neither appears in health.yaml's dependencies either: they
+    // share this service's lifecycle rather than being something it reaches
+    // across a boundary, and that is the fact the nesting is drawn from.
     deliveryLog = database 'delivery-log' {
       description 'One row per (message id, channel) — the idempotency key that makes redelivery a no-op — carrying the orderId and customer each send was addressed to, so a receipt can find its order and a capture that arrives first has somewhere to wait'
       technology 'PostgreSQL'
@@ -67,30 +52,12 @@ model {
     sender -> deliveryLog 'Records delivered / failed'
   }
 
-  // Everything the service touches belongs in its own model, cross-boundary
-  // dependencies included — the landscape carries only the boundary crossing.
-  // health.yaml names `kafka` as a critical dependency and that id has to resolve
-  // HERE, by element id, `metadata { service }` binding or title
-  // (`health.dependency-unmodelled` otherwise); and a model with elements and no
-  // edges beside a health.yaml that declares dependencies is `c4.no-relationships`
-  // — a service that reaches nothing is almost never true.
-  kafka = softwareSystem 'kafka' {
-    description 'Event backbone (platform)'
-    orderEvents = topic 'order.events'
-    paymentEvents = topic 'payment.events'
-    crmEvents = topic 'crm.events'
-  }
-
-  // The second thing this service reaches across its own boundary, and the one
-  // the runbook spends an incident section on: while the provider is down or
-  // throttling, nothing is delivered and there is no fallback path. It belongs
-  // here for the same reason payment-service's model draws `stripe` — a model
-  // that stopped at the broker would show a worker whose only failure mode is
-  // lag, which is the half of the picture the on-call graphs already give you.
-  provider = softwareSystem 'notification-provider' {
-    description 'Third-party email and SMS gateway — quota-limited, and outside this fleet'
-  }
-
+  // The three channels this service takes messages off, pointing at the map's
+  // topics. health.yaml names `kafka` as a critical dependency and that id has to
+  // resolve through this model (`health.dependency-unmodelled` otherwise): it
+  // does, because a partner brings its ANCESTORS with it — the edges name the
+  // topics and the broker answers for them.
+  //
   // No `metadata { consumes }` on these edges, and adding it would change
   // nothing: loam reads the event spine off `architecture/landscape.likec4`
   // alone, never off a service model. What resolves a consumed name against
@@ -104,15 +71,27 @@ model {
   // Drawn topic → consumer, the direction the landscape uses and the one the
   // event spine requires there: `consumes` binds the edge's TARGET, so the same
   // edge drawn the other way round binds to nothing at all.
-  kafka.orderEvents -> notificationService.consumer 'OrderPlaced triggers the confirmation'
-  kafka.paymentEvents -> notificationService.consumer 'PaymentCaptured triggers the receipt'
-  kafka.crmEvents -> notificationService.consumer 'CustomerUpdated refreshes contact details'
+  kafka.orderEvents -> marketplace.notificationService.consumer 'OrderPlaced triggers the confirmation'
+  kafka.paymentEvents -> marketplace.notificationService.consumer 'PaymentCaptured triggers the receipt'
+  kafka.crmEvents -> marketplace.notificationService.consumer 'CustomerUpdated refreshes contact details'
 
-  notificationService.sender -> provider 'Sends email and SMS, and backs off on 429'
+  // The second thing this service reaches across its own boundary, and the one
+  // the runbook spends an incident section on: while the provider is down or
+  // throttling, nothing is delivered and there is no fallback path. Its element
+  // is the map's, and the map also carries the SERVICE-level twin of this edge
+  // (`marketplace.notificationService -> notificationProvider`), because every
+  // fleet check reads the map alone. The cross-boundary call is written twice on
+  // purpose — container-level here, service-level there — and that remainder is
+  // recorded in ROADMAP.md rather than hidden.
+  marketplace.notificationService.sender -> notificationProvider 'Sends email and SMS, and backs off on 429'
 }
 
+// Views belong to LikeC4's renderer; no loam check reads anything below. This
+// file is part of the root project, so `npx likec4 start` at the docs root draws
+// this view beside the fleet map — there is no per-service likec4.config.json,
+// and loam never writes one beside an extending model.
 views {
-  view notification_service of notificationService {
+  view notification_service of marketplace.notificationService {
     include *
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ybotok/loam",
-  "version": "0.2.0-alpha.1",
+  "version": "0.2.0-alpha.13",
   "description": "Architecture-first semantic integrity and change governance for evolving software systems: connect C4, requirements, contracts, and verification evidence.",
   "author": "spentsov",
   "repository": {

package/dist/commands/validate/checks/vocabulary.js

@@ -1,31 +0,0 @@
-/**
- * The handful of facts every validate check speaks, and none of them owns.
- *
- * A leaf module rather than a paragraph beside its first caller, because the
- * checks are spread across packages and each of these is read from more than
- * one of them: the dispatcher's rollup and the service target's sources check
- * both name one finding code, and several targets render parser diagnostics
- * the same way. ACTOR_KINDS and EXTERNAL_TAG lived here too, until they
- * reached a third copy (`core/gate/partners.ts`, `core/verify/checklist.ts`);
- * their shared spelling is now `core/vocabulary/maturity.ts`, beside the
- * landscape evidence that asks the same questions.
- */
-import {} from "../../../core/c4/likec4.js";
-/** The one code the rollup line counts; spelled once so the two cannot drift. */
-export const UNVERIFIABLE = "sources.unverifiable-from-here";
-/**
- * One parser diagnostic as a finding's evidence line: `L12:` when the parser
- * knew a line, because that lets a reader open the file at the fault instead of
- * searching for it.
- *
- * Three other modules hand-roll the same ternary (`commands/show.ts`,
- * `commands/delta.ts`, `core/c4/splice/landscape-merge.ts`). All four belong
- * beside `LikeC4Error` in `core/c4/likec4.ts`. That used to be blocked by the
- * file limit — nine lines of headroom — and is not any more: moving the resolver
- * out to `core/c4/resolve/service.ts` left the loader around 100 lines under.
- * The consolidation is now unblocked and simply owed.
- */
-export function errorText(e) {
-    return typeof e.line === "number" ? `L${e.line}: ${e.message}` : e.message;
-}
-//# sourceMappingURL=vocabulary.js.map

package/dist/commands/validate/checks/vocabulary.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"vocabulary.js","sourceRoot":"","sources":["../../../../src/commands/validate/checks/vocabulary.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,OAAO,EAAoB,MAAM,4BAA4B,CAAC;AAE9D,iFAAiF;AACjF,MAAM,CAAC,MAAM,YAAY,GAAG,gCAAgC,CAAC;AAE7D;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,SAAS,CAAC,CAAc;IACtC,OAAO,OAAO,CAAC,CAAC,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,IAAI,KAAK,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC;AAC7E,CAAC","sourcesContent":["/**\n * The handful of facts every validate check speaks, and none of them owns.\n *\n * A leaf module rather than a paragraph beside its first caller, because the\n * checks are spread across packages and each of these is read from more than\n * one of them: the dispatcher's rollup and the service target's sources check\n * both name one finding code, and several targets render parser diagnostics\n * the same way. ACTOR_KINDS and EXTERNAL_TAG lived here too, until they\n * reached a third copy (`core/gate/partners.ts`, `core/verify/checklist.ts`);\n * their shared spelling is now `core/vocabulary/maturity.ts`, beside the\n * landscape evidence that asks the same questions.\n */\nimport { type LikeC4Error } from \"../../../core/c4/likec4.js\";\n\n/** The one code the rollup line counts; spelled once so the two cannot drift. */\nexport const UNVERIFIABLE = \"sources.unverifiable-from-here\";\n\n/**\n * One parser diagnostic as a finding's evidence line: `L12:` when the parser\n * knew a line, because that lets a reader open the file at the fault instead of\n * searching for it.\n *\n * Three other modules hand-roll the same ternary (`commands/show.ts`,\n * `commands/delta.ts`, `core/c4/splice/landscape-merge.ts`). All four belong\n * beside `LikeC4Error` in `core/c4/likec4.ts`. That used to be blocked by the\n * file limit — nine lines of headroom — and is not any more: moving the resolver\n * out to `core/c4/resolve/service.ts` left the loader around 100 lines under.\n * The consolidation is now unblocked and simply owed.\n */\nexport function errorText(e: LikeC4Error): string {\n  return typeof e.line === \"number\" ? `L${e.line}: ${e.message}` : e.message;\n}\n"]}

package/dist/commands/validate/fleet/usecases/capability-tag.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"capability-tag.js","sourceRoot":"","sources":["../../../../../src/commands/validate/fleet/usecases/capability-tag.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,OAAO,EACL,cAAc,EACd,OAAO,GAER,MAAM,+CAA+C,CAAC;AAGvD,OAAO,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAEvC,qGAAqG;AACrG,SAAS,QAAQ,CAAC,EAAU;IAC1B,OAAO,GAAG,EAAE,MAAM,cAAc,GAAG,OAAO,CAAC,EAAE,CAAC,GAAG,CAAC;AACpD,CAAC;AAED;;;;;;;;GAQG;AACH,SAAS,WAAW,CAAC,IAAgB,EAAE,KAAiD;IACtF,MAAM,IAAI,GACR,KAAK,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC;QACpB,CAAC,CAAC,iBAAiB,KAAK,CAAC,KAAK,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG;QAC1D,CAAC,CAAC,kFAAkF,CAAC;IACzF,OAAO,CACL,GAAG,SAAS,CAAC,IAAI,CAAC,eAAe,KAAK,CAAC,GAAG,kCAAkC;QAC5E,+CAA+C,KAAK,CAAC,IAAI,MAAM,IAAI,GAAG;QACtE,mIAAmI,CACpI,CAAC;AACJ,CAAC;AAED;;;;GAIG;AACH,SAAS,WAAW,CAAC,IAAgB,EAAE,KAAiD;IACtF,OAAO,CACL,GAAG,SAAS,CAAC,IAAI,CAAC,eAAe,KAAK,CAAC,GAAG,SAAS,KAAK,CAAC,GAAG,CAAC,MAAM,oCAAoC;QACvG,IAAI,KAAK,CAAC,IAAI,MAAM,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,mEAAmE;QAC3G,0GAA0G;QAC1G,2GAA2G;QAC3G,qBAAqB,CACtB,CAAC;AACJ,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,qBAAqB,CAAC,IAAgB,EAAE,MAAkC;IACxF,MAAM,QAAQ,GAAc,EAAE,CAAC;IAC/B,KAAK,MAAM,KAAK,IAAI,MAAM,EAAE,CAAC;QAC3B,IAAI,KAAK,CAAC,IAAI,KAAK,UAAU;YAAE,SAAS;QACxC,QAAQ,CAAC,IAAI,CAAC;YACZ,QAAQ,EAAE,OAAO;YACjB,IAAI,EAAE,+BAA+B;YACrC,wEAAwE;YACxE,0EAA0E;YAC1E,aAAa;YACb,OAAO,EAAE,IAAI,CAAC,EAAE;YAChB,OAAO,EAAE,KAAK,CAAC,IAAI,KAAK,MAAM,CAAC,CAAC,CAAC,WAAW,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC,CAAC,CAAC,WAAW,CAAC,IAAI,EAAE,KAAK,CAAC;SACrF,CAAC,CAAC;IACL,CAAC;IACD,OAAO,QAAQ,CAAC;AAClB,CAAC","sourcesContent":["/**\n * `usecase.capability-unresolved` — the `#cap-` tag that names no declared\n * capability, or more than one.\n *\n * The join itself lives in `core/capabilities/usecase-join.ts` and none of it is\n * repeated here: this module owns the grade and the sentence, nothing else. That\n * split is why the tag can answer \"many\" at all — the slug is not injective, so\n * `payments/refunds` and `payments-refunds` both flatten to\n * `payments-refunds` — and why the close candidates a message offers are real\n * declared ids rather than loam's flattened spelling of them.\n *\n * ERROR, the same grade `capability.unknown` carries on a `Capability:` line and\n * for its reason: an invented capability reads exactly like a real one. Here it\n * reads that way at flow altitude — the tag is what files a whole business\n * sequence under an owner, so a claim that resolves to nothing produces a use\n * case nobody can find and a capability nobody can see is realized.\n *\n * SUPPRESSED ENTIRELY when the vocabulary is absent or unreadable: the caller\n * resolves no claims at all in that case, so this answers with nothing. The\n * claims are RESOLVED BY THE CALLER rather than here because the `#req-` grade\n * beside this one is scoped by the very same verdicts, and two resolutions of\n * one view's tags are two chances to disagree about which capability a flow is\n * about. The ladder that produces the suppressing `null` is\n * `gradableCapabilityIds` in `core/capabilities/findings.ts` — one function, called by every site that needs the graded id list, this module's\n * caller in `../landscape.ts` included. The FILE is this axis's opt-in, so a\n * fleet with no `architecture/capabilities.yaml` produces no capability finding\n * at all, and an unreadable one is `capability.invalid` alone rather than one\n * unresolved tag per use case in the fleet, which is a cascade and not a\n * diagnosis. That rule is not re-decided here: a second reading of\n * `CapabilityVocabulary` anywhere in this package is the copy that goes stale\n * the day a fourth un-gradable state is added, so call the function.\n */\nimport {\n  CAP_TAG_PREFIX,\n  tagSlug,\n  type CapabilityClaim,\n} from \"../../../../core/capabilities/usecase-join.js\";\nimport type { ParsedView } from \"../../../../core/c4/parsed/dynamic-views.js\";\nimport type { Finding } from \"../../../../core/vocabulary/report.js\";\nimport { viewPlace } from \"./place.js\";\n\n/** A capability id as an author must write it in a tag: `identity/tokens (#cap-identity-tokens)`. */\nfunction idAndTag(id: string): string {\n  return `${id} (#${CAP_TAG_PREFIX}${tagSlug(id)})`;\n}\n\n/**\n * A tag nothing declares, with the close names spelled as TAGS as well as ids.\n *\n * Both spellings, because either alone sends the author somewhere wrong: the id\n * is what `capabilities.yaml` holds and the tag is what the view must carry, and\n * an author handed only `identity/tokens` writes `#cap-identity/tokens`, which\n * LikeC4 refuses to parse. The flattening rule is stated in the same breath so\n * the reader can derive the next one without being told again.\n */\nfunction noneMessage(view: ParsedView, claim: Extract<CapabilityClaim, { kind: \"none\" }>): string {\n  const hint =\n    claim.close.length > 0\n      ? `Did you mean: ${claim.close.map(idAndTag).join(\", \")}?`\n      : \"Declare it there (`capabilities: {<id>: {description, owner}}`), or fix the tag.\";\n  return (\n    `${viewPlace(view)} is tagged #${claim.tag}, and no capability declared in ` +\n    `architecture/capabilities.yaml flattens to '${claim.slug}'. ${hint} ` +\n    \"A tag spells the id with every character outside `[A-Za-z0-9_-]` flattened to `-`, because that is all a LikeC4 tag name accepts.\"\n  );\n}\n\n/**\n * A tag two or more declared ids answer to. Every colliding id is named — a\n * message that stopped at the first would be reporting the ambiguity while\n * hiding half of what makes it one.\n */\nfunction manyMessage(view: ParsedView, claim: Extract<CapabilityClaim, { kind: \"many\" }>): string {\n  return (\n    `${viewPlace(view)} is tagged #${claim.tag}, and ${claim.ids.length} declared capabilities flatten to ` +\n    `'${claim.slug}' (${claim.ids.join(\", \")}) — nothing in the tag can say which one this use case realizes. ` +\n    \"Rename one of them in architecture/capabilities.yaml: a guessed capability files every hop of the flow, \" +\n    \"and every rollup built over it, under an owner who never claimed it — and the wrong answer looks exactly \" +\n    \"like the right one.\"\n  );\n}\n\n/**\n * One finding per `#cap-` tag that does not resolve — never one per view.\n *\n * A view may legitimately carry two capability tags (a checkout flow that also\n * issues the identity token realizes both), and `resolveCapabilityTags` answers\n * each on its own terms for that reason. Collapsing them here would either\n * swallow a broken tag beside a working one or lose the capability the view\n * genuinely does realize; one tag, one verdict, one finding keeps both facts.\n */\nexport function capabilityTagFindings(view: ParsedView, claims: readonly CapabilityClaim[]): Finding[] {\n  const findings: Finding[] = [];\n  for (const claim of claims) {\n    if (claim.kind === \"resolved\") continue;\n    findings.push({\n      severity: \"error\",\n      code: \"usecase.capability-unresolved\",\n      // The VIEW, not the tag: a subject is what a reader goes and opens, and\n      // `subjectsWith` counts one broken use case once however many of its tags\n      // are wrong.\n      subject: view.id,\n      message: claim.kind === \"none\" ? noneMessage(view, claim) : manyMessage(view, claim),\n    });\n  }\n  return findings;\n}\n"]}

package/dist/commands/validate/fleet/usecases/requirement-tag.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"requirement-tag.js","sourceRoot":"","sources":["../../../../../src/commands/validate/fleet/usecases/requirement-tag.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,OAAO,EACL,cAAc,EACd,OAAO,EACP,sBAAsB,GAGvB,MAAM,+CAA+C,CAAC;AAGvD,OAAO,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAEvC,0FAA0F;AAC1F,SAAS,QAAQ,CAAC,EAAU;IAC1B,OAAO,GAAG,EAAE,MAAM,cAAc,GAAG,OAAO,CAAC,EAAE,CAAC,GAAG,CAAC;AACpD,CAAC;AAED;;;;GAIG;AACH,SAAS,MAAM,CAAC,KAAsD;IACpE,QAAQ,KAAK,CAAC,IAAI,EAAE,CAAC;QACnB,KAAK,UAAU;YACb,OAAO,KAAK,CAAC,YAAY,CAAC,MAAM,KAAK,CAAC;gBACpC,CAAC,CAAC,oGAAoG;oBAClG,4FAA4F;oBAC5F,qEAAqE;gBACzE,CAAC,CAAC,qBAAqB,KAAK,CAAC,YAAY,CAAC,MAAM,kBAAkB,KAAK,CAAC,YAAY,CAAC,IAAI,CAAC,IAAI,CAAC,KAAK;oBAChG,oGAAoG;oBACpG,iGAAiG;oBACjG,mGAAmG,CAAC;QAC5G,KAAK,cAAc;YACjB,OAAO,CACL,eAAe,KAAK,CAAC,UAAU,yCAAyC,KAAK,CAAC,UAAU,YAAY;gBACpG,kGAAkG;gBAClG,4DAA4D,CAC7D,CAAC;QACJ,KAAK,OAAO;YACV,OAAO,CACL,gBAAgB,KAAK,CAAC,UAAU,qDAAqD;gBACrF,qFAAqF,CACtF,CAAC;QACJ,KAAK,MAAM;YACT,OAAO,KAAK,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC;gBAC3B,CAAC,CAAC,gBAAgB,KAAK,CAAC,UAAU,mDAAmD,KAAK,CAAC,IAAI,KAAK;oBAChG,iBAAiB,KAAK,CAAC,KAAK,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG;gBAC5D,CAAC,CAAC,gBAAgB,KAAK,CAAC,UAAU,mDAAmD,KAAK,CAAC,IAAI,MAAM;oBACjG,qDAAqD,CAAC;QAC9D;YACE,OAAO,CACL,GAAG,KAAK,CAAC,GAAG,CAAC,MAAM,qBAAqB,KAAK,CAAC,UAAU,iBAAiB,KAAK,CAAC,IAAI,IAAI;gBACvF,IAAI,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,gEAAgE;gBACxF,mGAAmG;gBACnG,8DAA8D,CAC/D,CAAC;IACN,CAAC;AACH,CAAC;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,sBAAsB,CACpC,IAAgB,EAChB,MAAkC,EAClC,cAAuE;IAEvE,MAAM,KAAK,GAAG,MAAM,CAAC,OAAO,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC,KAAK,CAAC,IAAI,KAAK,UAAU,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;IACvF,MAAM,QAAQ,GAAc,EAAE,CAAC;IAC/B,KAAK,MAAM,KAAK,IAAI,sBAAsB,CAAC,IAAI,CAAC,IAAI,EAAE,KAAK,EAAE,cAAc,CAAC,EAAE,CAAC;QAC7E,IAAI,KAAK,CAAC,IAAI,KAAK,UAAU;YAAE,SAAS;QACxC,QAAQ,CAAC,IAAI,CAAC;YACZ,QAAQ,EAAE,OAAO;YACjB,IAAI,EAAE,gCAAgC;YACtC,yEAAyE;YACzE,sEAAsE;YACtE,OAAO,EAAE,IAAI,CAAC,EAAE;YAChB,OAAO,EAAE,GAAG,SAAS,CAAC,IAAI,CAAC,eAAe,KAAK,CAAC,GAAG,8BAA8B,MAAM,CAAC,KAAK,CAAC,EAAE;SACjG,CAAC,CAAC;IACL,CAAC;IACD,OAAO,QAAQ,CAAC;AAClB,CAAC","sourcesContent":["/**\n * `usecase.requirement-unresolved` — the `#req-` tag that names no requirement\n * of the capability the view is about.\n *\n * The join lives in `core/capabilities/usecase-join.ts` and none of it is\n * repeated here: this module owns the grade and the sentences. Six arms, six\n * fixes, and they are deliberately the same vocabulary\n * `capability.realizes-unknown` uses for the OTHER carrier of this claim — an\n * author who has learned one set of messages has learned both.\n *\n * ERROR, for `usecase.capability-unresolved`'s reason one join deeper: the tag\n * is the architect's claim that a flow satisfies a named business promise, and a\n * claim that resolves to nothing reads exactly like one that does — in the view,\n * in review, and to anyone asking which flow keeps that promise.\n *\n * AN UNRESOLVED CLAIM SUPPRESSES NOTHING. `capability.requirement-unrealized`\n * counts only RESOLVED claims, so a typo'd `#req-` tag leaves the requirement\n * reported as realized by nobody — which is the truth, and is exactly what a\n * broken claim should not be able to hide. The two findings arriving together is\n * the intended reading: one says the tag is wrong, the other says the promise is\n * still unkept.\n */\nimport {\n  REQ_TAG_PREFIX,\n  tagSlug,\n  resolveRequirementTags,\n  type CapabilityClaim,\n  type RequirementClaim,\n} from \"../../../../core/capabilities/usecase-join.js\";\nimport type { ParsedView } from \"../../../../core/c4/parsed/dynamic-views.js\";\nimport type { Finding } from \"../../../../core/vocabulary/report.js\";\nimport { viewPlace } from \"./place.js\";\n\n/** A `Requirement-ID` as an author must write it in a tag: `CHK.ONCE (#req-CHK-ONCE)`. */\nfunction idAndTag(id: string): string {\n  return `${id} (#${REQ_TAG_PREFIX}${tagSlug(id)})`;\n}\n\n/**\n * The fix for one unresolved claim. The `unscoped` arm splits in two on the\n * count, because none and several are opposite mistakes: one author forgot to\n * say which capability, the other said two and left the id homeless.\n */\nfunction advice(claim: Exclude<RequirementClaim, { kind: \"resolved\" }>): string {\n  switch (claim.kind) {\n    case \"unscoped\":\n      return claim.capabilities.length === 0\n        ? \"the view carries no `#cap-` tag that resolves to a declared capability, and a `Requirement-ID` is \" +\n            \"unique only inside its own document — so there is nothing for this id to be looked up in. \" +\n            \"Add the `#cap-<slug>` tag naming the capability this flow is about.\"\n        : `the view resolves ${claim.capabilities.length} capabilities (${claim.capabilities.join(\", \")}), ` +\n            \"so nothing says which document the id belongs to. A flow realizing promises from two capabilities \" +\n            \"needs one `#req-` tag per capability to be unambiguous, which the tag grammar cannot express — \" +\n            \"split the flow, or drop the `#req-` tag and let `Realizes:` on the service requirements carry it.\";\n    case \"undocumented\":\n      return (\n        `capability '${claim.capability}' is declared but has no capabilities/${claim.capability}/spec.md, ` +\n        \"so it carries no requirements to satisfy. Write the document — a name alone can be claimed with \" +\n        \"`#cap-`, but only a document has promises a flow can keep.\"\n      );\n    case \"empty\":\n      return (\n        `capabilities/${claim.capability}/spec.md exists and declares no requirements yet — ` +\n        \"add the `## Requirements` section, each requirement carrying its `Requirement-ID:`.\"\n      );\n    case \"none\":\n      return claim.close.length > 0\n        ? `capabilities/${claim.capability}/spec.md declares no requirement flattening to '${claim.slug}'. ` +\n            `Did you mean: ${claim.close.map(idAndTag).join(\", \")}?`\n        : `capabilities/${claim.capability}/spec.md declares no requirement flattening to '${claim.slug}' — ` +\n            \"check the `Requirement-ID:` lines in that document.\";\n    default:\n      return (\n        `${claim.ids.length} requirements of '${claim.capability}' flatten to '${claim.slug}' ` +\n        `(${claim.ids.join(\", \")}) — nothing in the tag can say which promise this flow keeps. ` +\n        \"Rename one of them: a guessed requirement reports the wrong promise as kept and the right one as \" +\n        \"unimplemented, and both answers look exactly like the truth.\"\n      );\n  }\n}\n\n/**\n * One finding per `#req-` tag that does not resolve — never one per view.\n *\n * Several `#req-` tags on one view are legal and normal: a checkout flow that\n * charges once AND honours the price keeps two promises, and there is no honest\n * way to make its author pick one. So a broken tag beside a working one must\n * neither swallow the break nor lose the promise the view genuinely does keep.\n *\n * `claims` is the view's OWN capability verdicts, already resolved by the\n * caller — passed rather than recomputed so the scope this grade uses and the\n * scope `capabilityTagFindings` graded are the same list, and an unresolved\n * `#cap-` tag cannot silently scope a requirement lookup.\n */\nexport function requirementTagFindings(\n  view: ParsedView,\n  claims: readonly CapabilityClaim[],\n  requirementsOf: (capability: string) => ReadonlySet<string> | undefined,\n): Finding[] {\n  const scope = claims.flatMap((claim) => (claim.kind === \"resolved\" ? [claim.id] : []));\n  const findings: Finding[] = [];\n  for (const claim of resolveRequirementTags(view.tags, scope, requirementsOf)) {\n    if (claim.kind === \"resolved\") continue;\n    findings.push({\n      severity: \"error\",\n      code: \"usecase.requirement-unresolved\",\n      // The VIEW, not the tag — a subject is what a reader goes and opens, and\n      // one broken use case counts once however many of its tags are wrong.\n      subject: view.id,\n      message: `${viewPlace(view)} is tagged #${claim.tag}, and it does not resolve: ${advice(claim)}`,\n    });\n  }\n  return findings;\n}\n"]}

package/dist/commands/validate/fleet/usecases/steps.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"steps.js","sourceRoot":"","sources":["../../../../../src/commands/validate/fleet/usecases/steps.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * The three grades one hop of a use case can earn: `usecase.step-unbacked`,\n * `usecase.step-contested` and `usecase.step-unlinked`.\n *\n * The attribution itself is `core/c4/arch.ts`'s `attributeStep` — which declared\n * relationship backs a hop, oriented on `isBackward` and decided by the\n * DISTINCT-op count — and none of that reasoning is repeated here. This module\n * owns three things: which verdict earns which code, the three guards that keep\n * the warn honest, and the sentences.\n *\n * WHY `step-unbacked` IS THE CHECK THAT EARNS THE FEATURE. A hop between two\n * elements that both exist, with no relationship between them anywhere in the\n * model, is ZERO LikeC4 errors: a `dynamic view` is allowed to show a call the\n * model never declared, so the diagram renders, the project parses, and every\n * other check in loam stays green. The flow reads as fine in every tool the\n * fleet has. If loam does not convict it, nothing does — which is why it is an\n * error rather than an advisory.\n *\n * ONE BREACH, ONE FINDING, and here that is structural rather than remembered.\n * `contested` and `attributed` are disjoint verdicts, so deriving\n * `step-unlinked` from the `attributed` arm — never from the candidate\n * relationships — is what makes a contested step report once. A grader that\n * walked `rels` looking for a missing `op` would convict the same hop twice:\n * once for the disagreement, and once for whichever candidate happened to carry\n * no operation at all.\n */\nimport { attributeStep, type StepAttribution, type StepScope } from \"../../../../core/c4/arch.js\";\nimport type { Elem, Rel } from \"../../../../core/c4/likec4.js\";\nimport type { ParsedStep, ParsedView } from \"../../../../core/c4/parsed/dynamic-views.js\";\nimport { ACTOR_KINDS } from \"../../../../core/vocabulary/maturity.js\";\nimport type { Finding } from \"../../../../core/vocabulary/report.js\";\nimport { stepPlace } from \"../../../../core/usecases/place.js\";\nimport { viewPlace } from \"./place.js\";\n\n/** One hop being graded and the view it belongs to — never passed apart. */\nexport interface GradedStep {\n  view: ParsedView;\n  step: ParsedStep;\n}\n\n/**\n * What a hop is graded against, built ONCE per run.\n *\n * `services` and `model.known` are the same set by construction (`./usecases.ts`\n * builds both from one value), which is what stops \"which service is this\n * element\" being answered one way by the attribution and another by the provider\n * guard below. `resolve` is injected for the same reason `fleetShapeFindings`\n * takes it: the fleet target already holds the shared element→service resolver,\n * and a second one built here could not disagree today but would be a second\n * place to change.\n */\nexport interface StepGrading {\n  model: StepScope;\n  /** The `services/<id>/` directories that exist. */\n  services: ReadonlySet<string>;\n  /** The shared element→service resolver every other edge join uses. */\n  resolve: (id: string) => string;\n}\n\ntype Unbacked = Extract<StepAttribution, { verdict: \"unbacked\" }>;\ntype Contested = Extract<StepAttribution, { verdict: \"contested\" }>;\ntype Attributed = Extract<StepAttribution, { verdict: \"attributed\" }>;\n\n/** `…checkout.likec4 — dynamic view 'uc_checkout' step 2 'authorizes the payment'`. */\nfunction placeOf(hop: GradedStep): string {\n  return `${viewPlace(hop.view)} ${stepPlace(hop.step)}`;\n}\n\n/**\n * A hop nothing in the model backs.\n *\n * Two fixes, because there are genuinely two mistakes that land here and the\n * author is the only one who can say which they made: the edge really is\n * missing, or the hop is a reply written the long way round. The second is\n * offered as the OTHER spelling of what they already typed — suggesting the\n * spelling they used would be a hint that restates the defect — and the sentence\n * says which pair that spelling looks the hop up under, because `<-` attributes\n * a reply to the CALL it answers rather than to the direction the message\n * travels (`callPair` in core/c4/arch.ts holds the measurement).\n */\nfunction unbackedFinding(hop: GradedStep, attribution: Unbacked): Finding {\n  const other = hop.step.isBackward\n    ? { spelling: `${hop.step.source} -> ${hop.step.target}`, when: \"is not a return step\" }\n    : { spelling: `${hop.step.target} <- ${hop.step.source}`, when: \"is a return step\" };\n  return {\n    severity: \"error\",\n    code: \"usecase.step-unbacked\",\n    subject: hop.view.id,\n    message:\n      `${placeOf(hop)}: nothing in the model declares ${attribution.from} -> ${attribution.to}, so this hop is ` +\n      \"backed by no relationship — and LikeC4 reports no error for it, so the view still renders and the \" +\n      \"project still parses. Draw the edge in `model { }` (with `metadata { op '<operationId>' }` where it is \" +\n      `a call), or, if this hop ${other.when}, write it as \\`${other.spelling}\\` — a reply is attributed to the ` +\n      `call it answers, so that spelling looks the hop up under ${attribution.to} -> ${attribution.from} instead.`,\n  };\n}\n\n/** `web -> orders.api \"Calls createOrder\" (op: createOrder)`, or `(no op)` where the edge declares none. */\nfunction candidateLine(rel: Rel): string {\n  const op = rel.op === undefined ? \"no op\" : `op: ${rel.op}`;\n  return `${rel.source} -> ${rel.target} \"${rel.title ?? \"\"}\" (${op})`;\n}\n\n/**\n * A hop whose candidates disagree about the operation.\n *\n * WARN, not error, because the model is complete — every candidate is a\n * relationship somebody drew on purpose — and the honest answer is sometimes\n * \"two paths, one flow\". What loam refuses to do is pick: a guessed operation is\n * indistinguishable from a right one in every rollup built over the use case,\n * and it stays wrong invisibly.\n *\n * `details` carries every candidate rather than the distinct ops, because the\n * repair is made on a RELATIONSHIP: the author has to find the edge that names\n * the wrong operation, and a list of operation names does not say which edge\n * that is. An absent `metadata { op }` prints as `no op` and is a candidate like\n * any other — it is exactly as much of a disagreement as a second name.\n */\nfunction contestedFinding(hop: GradedStep, attribution: Contested): Finding {\n  return {\n    severity: \"warn\",\n    code: \"usecase.step-contested\",\n    subject: hop.view.id,\n    message:\n      `${placeOf(hop)}: ${attribution.rels.length} relationships back ${attribution.from} -> ` +\n      `${attribution.to} and they name ${attribution.ops.length} different operations, so nothing can say ` +\n      \"which one this hop exercises. loam names the candidates instead of picking one — a guessed operation \" +\n      \"reads exactly like a right one in every rollup built over this flow. Give the candidates one operation, \" +\n      \"or draw the hop between the elements that name exactly one.\",\n    details: attribution.rels.map(candidateLine),\n  };\n}\n\n/**\n * The service this hop calls, when the hop is a `step-unlinked` candidate at\n * all — `null` when any of the three guards refuses. ALL THREE are mechanical,\n * and each closes a whole class of warnings that would otherwise be simply\n * wrong. The count is stated because a reader auditing this function is meant to\n * find three bullets and three `return null`s below and conclude that none of\n * them is surplus: the one a miscount invites deleting is the last, and deleting\n * it puts the warning back on the first hop of almost every flow.\n *\n *  - A `publishes` or `consumes` on ANY candidate means the hop does reach a\n *    declared API — an AsyncAPI one. The event spine already grades it\n *    (`spine.message-undefined` and its family), and asking for an `op` as well\n *    would be loam demanding an HTTP operationId for a Kafka message. Read\n *    across every candidate rather than the first, because on the service tier\n *    the candidates are one call drawn as containers.\n *  - The target must resolve to a real `services/<id>/`. Without it every hop\n *    into an `#external` system, an actor, a database, a cache or a queue warns\n *    — none of which owns an `openapi.yaml`, so none of them CAN carry the\n *    operationId the message would be asking for. Through the shared resolver,\n *    so \"the provider\" here and \"the provider\" in the spine check cannot\n *    disagree about which element stands for which directory.\n *  - The CALLER must not be an actor. A person is not a caller: `customer ->\n *    checkoutWeb 'opens the basket'` is somebody using the app, and the app owes\n *    no operationId for a click. The guard above does not cover this, because it\n *    reads the TARGET — and the target here is one of ours, so without this the\n *    warning fired on the FIRST HOP OF ALMOST EVERY FLOW, which is where a\n *    sequence diagram puts its actor. Measured on the published example fleet\n *    before it was added. This is the same exemption `fleet/census.ts`,\n *    `arch-coverage.ts`, `core/gate/partners.ts` and `core/verify/checklist.ts`\n *    each already apply, through the same `ACTOR_KINDS` — a person was never a\n *    participant in any of loam's other censuses either.\n *\n * The op test reads the ATTRIBUTION rather than the relationships: an\n * `attributed` verdict with no `op` means every candidate agreed the hop names\n * no operation, which is the state this warn is about. Candidates that disagree\n * never reach here at all — that is the suppression, and it is why it cannot be\n * forgotten.\n */\nfunction unlinkedProvider(attribution: Attributed, grading: StepGrading): string | null {\n  if (attribution.op !== undefined) return null;\n  if (attribution.rels.some((rel) => rel.publishes !== undefined || rel.consumes !== undefined)) return null;\n  if (isActor(attribution.from, grading.model.elements)) return null;\n  const provider = grading.resolve(attribution.to);\n  return grading.services.has(provider) ? provider : null;\n}\n\n/**\n * Is this endpoint a person rather than a system?\n *\n * Exact id, not the ancestor walk the service resolver does: an actor is a\n * top-level element in every landscape loam has seen, and a nested one would be\n * a person inside a system, which is not a shape the model has. An endpoint that\n * names no element cannot occur — a step naming one is a LikeC4 reference error,\n * so the document never reaches a check.\n */\nfunction isActor(id: string, elements: Elem[]): boolean {\n  const element = elements.find((candidate) => candidate.id === id);\n  return element !== undefined && ACTOR_KINDS.has(element.kind.toLowerCase());\n}\n\n/**\n * A hop backed by the model and joined to no contract.\n *\n * The mirror of `spine.op-link-missing` at flow altitude: the use case reaches\n * the fleet map and stops there, so nothing can say which operation of the\n * provider's contract the step exercises — and the whole point of grading a use\n * case is that the flow joins through to the API it drives.\n */\nfunction unlinkedFinding(hop: GradedStep, attribution: Attributed, provider: string): Finding {\n  const backing =\n    attribution.rels.length === 1 ? \"one relationship\" : `${attribution.rels.length} relationships`;\n  return {\n    severity: \"warn\",\n    code: \"usecase.step-unlinked\",\n    subject: hop.view.id,\n    message:\n      `${placeOf(hop)}: ${attribution.from} -> ${attribution.to} is backed by ${backing} carrying no ` +\n      \"`metadata { op }` and no `publishes`/`consumes`, so this hop names no operation of \" +\n      `${provider}'s contract — the use case reaches the fleet map and stops there. Add ` +\n      \"`metadata { op '<operationId>' }` to the edge in `model { }`, or `metadata { publishes '<message>' }` / \" +\n      \"`consumes` where the hop is an event.\",\n  };\n}\n\n/**\n * The findings one hop earns — at most one, whatever is wrong with it.\n *\n * A `switch` over the closed verdict union with every arm returning, so a fourth\n * verdict added upstream is a compile error here rather than a hop that silently\n * stops being graded.\n */\nexport function stepFindings(hop: GradedStep, grading: StepGrading): Finding[] {\n  const attribution = attributeStep(hop.step, grading.model);\n  switch (attribution.verdict) {\n    case \"unbacked\":\n      return [unbackedFinding(hop, attribution)];\n    case \"contested\":\n      return [contestedFinding(hop, attribution)];\n    case \"attributed\": {\n      const provider = unlinkedProvider(attribution, grading);\n      return provider === null ? [] : [unlinkedFinding(hop, attribution, provider)];\n    }\n  }\n}\n"]}

package/dist/commands/validate/fleet/usecases/usecases.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"usecases.js","sourceRoot":"","sources":["../../../../../src/commands/validate/fleet/usecases/usecases.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,OAAO,EAAE,UAAU,EAAE,MAAM,kCAAkC,CAAC;AAC9D,OAAO,EAAE,qBAAqB,EAAE,MAAM,+CAA+C,CAAC;AACtF,OAAO,EAAE,SAAS,EAAE,MAAM,oCAAoC,CAAC;AAI/D,OAAO,EAAE,qBAAqB,EAAE,MAAM,qBAAqB,CAAC;AAC5D,OAAO,EAAE,sBAAsB,EAAE,MAAM,sBAAsB,CAAC;AAC9D,OAAO,EAAE,YAAY,EAAoB,MAAM,YAAY,CAAC;AAC5D,OAAO,EAAE,QAAQ,EAAE,MAAM,oCAAoC,CAAC;AA8C9D;;;;;;;;;;;;;;;;GAgBG;AACH,SAAS,WAAW,CAAC,KAA4B;IAC/C,OAAO,KAAK;SACT,MAAM,CAAC,SAAS,CAAC;SACjB,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,UAAU,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,QAAQ,CAAC,CAAC,CAAC,CAAC,IAAI,UAAU,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;AACpF,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,eAAe,CAAC,KAAmB;IACjD,MAAM,OAAO,GAAgB;QAC3B,mEAAmE;QACnE,0EAA0E;QAC1E,8DAA8D;QAC9D,KAAK,EAAE,EAAE,QAAQ,EAAE,KAAK,CAAC,QAAQ,EAAE,aAAa,EAAE,KAAK,CAAC,aAAa,EAAE,KAAK,EAAE,KAAK,CAAC,QAAQ,EAAE;QAC9F,QAAQ,EAAE,KAAK,CAAC,QAAQ;QACxB,OAAO,EAAE,KAAK,CAAC,OAAO;KACvB,CAAC;IACF,MAAM,QAAQ,GAAc,EAAE,CAAC;IAC/B,KAAK,MAAM,IAAI,IAAI,WAAW,CAAC,KAAK,CAAC,KAAK,CAAC,EAAE,CAAC;QAC5C,4EAA4E;QAC5E,6EAA6E;QAC7E,sEAAsE;QACtE,gDAAgD;QAChD,EAAE;QACF,wEAAwE;QACxE,2EAA2E;QAC3E,wEAAwE;QACxE,0EAA0E;QAC1E,oEAAoE;QACpE,IAAI,KAAK,CAAC,YAAY,KAAK,IAAI,EAAE,CAAC;YAChC,MAAM,MAAM,GAAG,qBAAqB,CAAC,IAAI,CAAC,IAAI,EAAE,KAAK,CAAC,YAAY,CAAC,CAAC;YACpE,QAAQ,CAAC,IAAI,CAAC,GAAG,qBAAqB,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC,CAAC;YACtD,QAAQ,CAAC,IAAI,CAAC,GAAG,sBAAsB,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,CAAC,cAAc,CAAC,CAAC,CAAC;QAC/E,CAAC;QACD,KAAK,MAAM,IAAI,IAAI,IAAI,CAAC,KAAK;YAAE,QAAQ,CAAC,IAAI,CAAC,GAAG,YAAY,CAAC,EAAE,IAAI,EAAE,IAAI,EAAE,EAAE,OAAO,CAAC,CAAC,CAAC;IACzF,CAAC;IACD,OAAO,QAAQ,CAAC;AAClB,CAAC","sourcesContent":["/**\n * The use-case axis of `validate --all`: the `dynamic view`s a fleet declares,\n * graded as business flows against the model they are drawn over.\n *\n * ONLY VIEWS CARRYING A RESERVED TAG ARE GRADED, and that opt-in is what lets\n * this ship into a fleet that already has diagrams. An untagged `dynamic view`\n * is somebody's hand-drawn sequence — drawn to explain something to a person,\n * not to be joined to a model — and grading it would turn every existing docs\n * repo red on upgrade over documents nobody promised anything about. A `#cap-`\n * or `#req-` tag is the author saying \"this is a use case; hold it to the\n * model\", and nothing else says it: a view with no tags and a view whose tags\n * are all somebody's own vocabulary are the same thing here.\n *\n * THE TAG OPTS A VIEW IN WHETHER OR NOT IT RESOLVES. A `#cap-` slug that names\n * no declared capability is a broken claim about the vocabulary, not a withdrawn\n * one, so its steps are still graded — and the step grades read\n * `architecture/capabilities.yaml` nowhere at all. Coupling them would mean a\n * fleet that has not adopted the capability axis could never have a use case\n * checked, which inverts the adoption order the whole axis is built on: draw the\n * flow first, name the capability when the vocabulary exists.\n *\n * Everything here is LINEAR IN STEPS over documents `validate --all` has already\n * parsed, and nothing in it reads a file or throws — a fleet with no tagged view\n * produces exactly nothing. Linear in steps is not free per step: `attributeStep`\n * scans `relationships` once for the exact tier and again for the resolved one,\n * and `isActor` scans `elements`, so the real shape is O(steps × relationships)\n * plus O(steps × elements). That is why `StepGrading` is built once below rather\n * than per hop — the per-hop cost is a scan, so anything rebuilt per hop is paid\n * against every hop in the fleet.\n */\nimport { compareIds } from \"../../../../core/repo/entries.js\";\nimport { resolveCapabilityTags } from \"../../../../core/capabilities/usecase-join.js\";\nimport { isUseCase } from \"../../../../core/usecases/fleet.js\";\nimport type { Elem, Rel } from \"../../../../core/c4/likec4.js\";\nimport type { ParsedView } from \"../../../../core/c4/parsed/dynamic-views.js\";\nimport type { Finding } from \"../../../../core/vocabulary/report.js\";\nimport { capabilityTagFindings } from \"./capability-tag.js\";\nimport { requirementTagFindings } from \"./requirement-tag.js\";\nimport { stepFindings, type StepGrading } from \"./steps.js\";\nimport { viewFile } from \"../../../../core/usecases/place.js\";\n\n/** What the use-case grades run over: the views, the model they are drawn on, and the fleet. */\nexport interface UseCaseScope {\n  /**\n   * Every `dynamic view` the `architecture/` PROJECT declares, each carrying the\n   * file it was written in.\n   *\n   * The caller must pass views that came from `loadProject` and no others. Only\n   * that loader gives a view a `sourcePath` relative to `architecture/`; the\n   * single-file loaders name every document after themselves (`source.c4`), and\n   * a finding built from one of those would name a file that has never existed\n   * — see `./place.ts`, which is where the path is spelled.\n   */\n  views: readonly ParsedView[];\n  elements: Elem[];\n  relationships: Rel[];\n  /** The `services/<id>/` directories that exist. */\n  services: ReadonlySet<string>;\n  /** The shared element→service resolver — the same one every other edge join uses. */\n  resolve: (id: string) => string;\n  /**\n   * The declared capability ids, or `null` when `architecture/capabilities.yaml`\n   * is absent or does not read as a vocabulary.\n   *\n   * `null` and `[]` are deliberately different answers, and the join at\n   * `core/capabilities/usecase-join.ts` says why it cannot tell them apart\n   * itself: an empty list means \"the fleet declares no capabilities\", which is a\n   * real verdict every tag then fails against, while `null` means \"there is no\n   * vocabulary to grade against\" and suspends the tag grade entirely. The\n   * caller applies the ladder because the caller is the one that read the file.\n   */\n  capabilities: readonly string[] | null;\n  /**\n   * The requirement ids one capability's document declares, or `undefined` for a\n   * capability with no document — the scope a `#req-` tag is resolved in.\n   *\n   * A function rather than the map itself, so this package never learns what a\n   * capability document is: the fleet target reads them once\n   * (`capabilityRequirementIndex`) and hands the lookup over. `undefined` and an\n   * empty set are different answers here, exactly as they are one join over —\n   * no document at all, against a document declaring no promises yet.\n   */\n  requirementsOf: (capability: string) => ReadonlySet<string> | undefined;\n}\n\n/**\n * The views that opted in, in a stable order.\n *\n * The opt-in itself is `isUseCase` in `core/usecases/fleet.ts` and is not\n * restated here. It used to be — the same `startsWith` pair, spelled a second\n * time — and the two spellings drifted: this one took either reserved prefix\n * while the reader-side one took `#cap-` alone, so `validate` graded a\n * `#req-`-only flow that `loam diff`, `delta`, `status`, the packs and `list\n * capabilities` could not see. What is left here is the ORDER, which is this\n * package's own concern.\n *\n * Sorted by (file, view id) rather than reported in LikeC4's own record order:\n * nothing in loam has measured that the parse preserves declaration order, so a\n * report whose row order depends on that would reorder under a dependency bump\n * — the diff-stability rule `core/capabilities/rollup.ts` states for its rows,\n * applied to findings.\n */\nfunction gradedViews(views: readonly ParsedView[]): ParsedView[] {\n  return views\n    .filter(isUseCase)\n    .sort((a, b) => compareIds(viewFile(a), viewFile(b)) || compareIds(a.id, b.id));\n}\n\n/**\n * Every use-case finding a fleet's declared views earn.\n *\n * The grading record is built once and shared across every step of every view:\n * `attributeStep` caches its element→service resolver on the identity of the\n * elements array and the fleet set, so handing it one `StepScope` for the whole\n * run is what keeps the fleet's use cases from rebuilding that id map per hop.\n */\nexport function useCaseFindings(scope: UseCaseScope): Finding[] {\n  const grading: StepGrading = {\n    // `known` and `services` come from ONE value, so the fleet set the\n    // attribution resolves against and the fleet set the provider guard tests\n    // cannot drift apart into two answers about the same element.\n    model: { elements: scope.elements, relationships: scope.relationships, known: scope.services },\n    services: scope.services,\n    resolve: scope.resolve,\n  };\n  const findings: Finding[] = [];\n  for (const view of gradedViews(scope.views)) {\n    // ONE resolution of this view's capability tags, shared by both grades. The\n    // `#req-` tag is scoped by exactly the capabilities the `#cap-` tags resolve\n    // to, so resolving twice would be two chances to disagree about which\n    // document a `Requirement-ID` is unique inside.\n    //\n    // THE LADDER IS THE `null`, NOT AN EMPTY LIST, and the distinction is a\n    // wrong answer away: a suspended vocabulary handed on as `[]` reads to the\n    // requirement grade as \"this view resolves no capability\", which is its\n    // `unscoped` ERROR — so every `#req-` tag in a fleet that has not adopted\n    // the capability axis would be convicted for the axis not existing.\n    if (scope.capabilities !== null) {\n      const claims = resolveCapabilityTags(view.tags, scope.capabilities);\n      findings.push(...capabilityTagFindings(view, claims));\n      findings.push(...requirementTagFindings(view, claims, scope.requirementsOf));\n    }\n    for (const step of view.steps) findings.push(...stepFindings({ view, step }, grading));\n  }\n  return findings;\n}\n"]}

package/dist/core/agent/agents-md/artifacts.js

@@ -1,220 +0,0 @@
-/**
- * The document's opening arc: what the docs repo HOLDS — the layout, how its
- * documents link to each other, the glossary, architectural obligations, and
- * the `loam.json` wiring every repository commits.
- *
- * The three sections that used to close this file — the architecture spec
- * axis, the generated Gherkin suite, and the frontmatter/vouch chain — are now
- * the `loam-authoring` reference page (../workflows/reference/authoring.ts),
- * printed by `loam instructions loam-authoring` rather than written into
- * AGENTS.md. They are grammars consulted while writing ONE document, and the
- * file they were in is auto-loaded on every session by hosts that truncate it
- * silently; ./command-map.ts's header carries the measurement that decided it.
- * What is left here is what an agent must know before it can form a question
- * at all.
- *
- * One section of the AGENTS.md template. ../agents-md.ts assembles the
- * document by PLAIN CONCATENATION — no join separator — so every section
- * starts at the first character of its opening line and ends with the newline
- * that closes its last one. Keep that shape when editing, or two sections glue
- * onto one line in every docs repo loam scaffolds from now on.
- */
-export const ARTIFACTS = `# Working in this docs repo
-
-This is a **loam** docs repo: the shared source of truth for a governed software
-system — its architecture, requirements, contracts and evidence. Everything here
-is plain files. \`loam\` reads and writes them; delete \`loam\` and the docs remain.
-
-**The bar this artifact set aims at is reproducibility**: a reader should be able
-to answer, from these files alone — what each governed boundary exposes, what it
-reaches, what shapes it exchanges, how it is run, and what pages whom —
-without opening the code. \`loam validate\` grades form and joins, never depth:
-green means the files agree with each other, and the bar is what "done" is
-measured against — a thin baseline that validates is thin, not done.
-
-## Layout
-
-\`\`\`
-architecture/landscape.likec4     the living C4 model of the whole system
-architecture/permissions.yaml     optional system-wide authorization vocabulary
-architecture/obligations.yaml     optional ARCHITECTURAL obligations (#obl-<name> on the map)
-architecture/adrs/NNNN-*.md       optional SYSTEM-level decisions (MADR) — only their links are graded
-glossary/<term>.md                optional domain vocabulary — one file per term, nesting allowed
-services/<svc>/
-  model.likec4                    this governed boundary's C4
-  spec.md                         its living requirements (current state)
-  arch.spec.md                    its living ARCHITECTURE requirements (outbox, retries, alerts)
-  openapi.yaml                    its API contract
-  asyncapi.yaml                   its AsyncAPI 3 event contract
-  adrs/  runbook.md  health.yaml  why it is like this, how to run it
-features/<FEAT>/                  a change in flight
-  intent.md                       why, in business terms
-  delta.likec4                    the architecture change, tagged #<FEAT>
-  specs/<svc>/spec.md             the requirement change for one governed boundary
-  specs/<svc>/arch.spec.md        the architectural requirement change, same delta grammar
-  specs/<svc>/openapi.yaml        the endpoints this feature adds
-  specs/<svc>/asyncapi.yaml       the event-contract delta (optional; a complete AsyncAPI 3 document)
-  verification.yaml               what was checked once the code was built
-features/archive/<FEAT>/          shipped changes — the evolution history
-\`\`\`
-
-## Linking between documents
-
-Documents here link to each other with **standard markdown links**, and the
-target is a relative path to the file:
-
-\`\`\`markdown
-[0001 — transactional outbox](../../architecture/adrs/0001-transactional-outbox.md)
-\`\`\`
-
-Two reasons, and the second is the one that decides it. A markdown link renders
-as a link in pull-request review, which is where these documents are actually
-read, while \`[[0001 transactional outbox]]\` renders there as the literal
-brackets somebody typed. And its target is a real relative path, so "does this
-link resolve" is a filesystem question with a yes-or-no answer — where resolving
-a wikilink means reimplementing Obsidian's shortest-unique-path search across the
-whole repo, which is guessing, and loam refuses and names rather than guessing.
-
-You lose nothing by it. Obsidian reads a repo written this way with no
-integration at all — graph view, backlinks and search all work on markdown links
-— and its per-vault \`Use [[Wikilinks]]\` setting turns OFF, after which its own
-autocomplete and rename-tracking produce markdown links too. The authoring
-comfort is a toggle in somebody's editor, not a decision this repo carries.
-
-**\`loam validate\` resolves these links** (\`link.unresolved\`, error): a relative
-target that names nothing is a broken join, reported once per document with
-every bad link and its line. A link here is a **join**, not decoration — a
-requirement that names a term wants that term's document linked, and an ADR that
-supersedes another wants to say which, the same kind of relationship
-\`Operations:\` and \`Covers:\` already state.
-
-Three things are deliberately NOT graded, so write them freely: a target outside
-this repository (\`../../some-service/README.md\` — that tree may not be checked
-out beside these documents), a link to a heading (\`#section\`), and any link
-inside a fenced code block or an inline code span, which is how a document shows
-the convention without being convicted for it.
-
-CASE **is** graded, and deliberately: \`[Order](Order.md)\` beside a file called
-\`order.md\` resolves on Windows and macOS and 404s on GitHub and every Linux
-runner, so the message names the stored spelling on all of them alike.
-
-## The glossary — the system's domain words
-
-\`glossary/<term>.md\`, one file per term, nesting allowed
-(\`glossary/payments/authorization.md\` is the term \`payments/authorization\`). There is
-no \`glossary.yaml\`: a definition is prose, and the DIRECTORY is the list. The
-directory's existence is the opt-in — a system without one hears nothing.
-
-**A term is checkable because a link is a join.** Cite it from the document that
-uses the word — a requirement, a capability document, a feature's intent — with an
-ordinary relative link:
-
-\`\`\`markdown
-An [Order](../../glossary/order.md) is what a customer has confirmed.
-\`\`\`
-
-A citation that does not resolve is \`link.unresolved\` like any other; a term nothing
-outside \`glossary/\` cites is \`glossary.unlinked\` (warn). Terms citing each other is
-normal and does NOT count as adoption — a glossary is a network of definitions, and
-two terms defining each other say nothing about whether the system uses either word.
-\`loam list glossary\` prints every term with the documents that cite it.
-
-**A feature may bring a new word with it**: write it at
-\`features/<FEAT>/glossary/<term>.md\` and \`loam archive\` copies it into \`glossary/\`,
-\`loam unarchive\` takes it back out. This route is CREATE-ONLY — a term the living
-glossary already defines is \`glossary.term-exists\`, which \`--approve\` does not
-override, because the merge is a whole-file copy and would replace an authored
-definition wholesale. To CHANGE a definition, edit \`glossary/<term>.md\` directly in
-the same pull request, where git produces an ordinary conflict.
-
-Cite the new word at its FUTURE living path (\`../../../../glossary/order.md\` from a
-\`specs/<svc>/\` delta) — that link resolves while the feature is in flight, and the
-merge re-expresses it from wherever the text lands, so it keeps resolving afterwards.
-
-Write the definition for a reader who knows the business and not this system: what the
-word means, and what it is NOT (an order is not a cart). Never which service owns it —
-that is the system map's question and it changes.
-
-
-## Architectural obligations — what the architect hands the team
-
-An architect has always had one checked channel here: an edge carrying
-\`metadata { op 'authorizePayment' }\` obliges the provider to define that operationId,
-or \`spine.op-undefined\` fails the gate. Obligations are the same handoff for the rules
-that VARY — an outbox on this publisher and not that one, a circuit breaker on two
-edges out of five — and they are three separate things on purpose:
-
-- an **ADR** in \`architecture/adrs/\` says WHAT was decided, as thin or as thick as the
-  decision needs;
-- a **\`#obl-<name>\` tag** on an element or an edge in \`architecture/landscape.likec4\`
-  says WHERE it applies, so one ADR governs three edges and not the fourth without the
-  document forking;
-- **\`architecture/obligations.yaml\`** declares the names, so a mistyped tag is an error
-  rather than a word nobody notices.
-
-\`\`\`yaml
-obligations:
-  outbox:
-    description: Publishers write the event and the state change in one transaction.
-    adr: architecture/adrs/0001-transactional-outbox.md   # relative to the docs repo root
-\`\`\`
-
-**Your side of it is \`Covers:\`**. A tagged object with no living requirement covering it
-is \`obligation.uncovered\` (warn), and the finding names the service, the object and the
-exact line to write — \`Covers: <element>\` or \`Covers: <source> -> <target>\` in that
-service's \`arch.spec.md\`, with a scenario that proves it. An id is its own tag suffix,
-so it may hold letters, digits, \`_\` and \`-\` only.
-
-## \`loam.json\` — the wiring, in every repo
-
-A governed system is **N + 1 repositories**: this docs repo, and one per governed
-implementation boundary. Paths and commands call that boundary a \`service\`; it
-may be a modular monolith, a network service, a CLI or a worker. Every repo
-commits its own \`loam.json\`, so an agent, human or CI runner can find the rest
-of the system. There is no global config; without a \`loam.json\`, commands refuse
-with \`no-config\` rather than guessing.
-
-\`\`\`json
-{ "docsDir": "../docs-repo", "service": "payment-service", "gherkinDir": "features" }
-\`\`\`
-
-- \`docsDir\` — where the docs repo is, **stored exactly as it was passed** and
-  resolved against the directory holding the \`loam.json\`. So \`../docs-repo\`
-  keeps working on every machine that checks the repos out side by side, which
-  is the point of committing the file. An absolute path is a warning
-  (\`doctor.docs-absolute\`): it resolves only on the machine that ran \`loam init\`.
-  The docs repo's own \`loam.json\` says \`"docsDir": "."\`.
-- \`service\` — the canonical id of the governed boundary THIS repo contains, i.e. the
-  \`services/<id>/\` directory it is allowed to speak for. \`loam vouch\`,
-  \`loam gherkin\` and \`loam verify --service\` when writing with \`--record\`,
-  \`--results\` or \`--contract-results\` bind to it; without it they refuse
-  (\`repository-unavailable\`) rather than write another boundary's documents
-  from a repo that is not that boundary's. A read-only verify checklist needs no
-  binding and works from the docs repo.
-- \`gherkinDir\` — optional, default \`features\`: the directory \`loam gherkin\`
-  writes its own \`loam/\` subtree into.
-- \`agentTools\` — optional: the agent tools \`loam init\` has written command and
-  skill files for here, accumulated across runs. Written by \`init\`, read by
-  \`loam doctor\`; nothing else depends on it, and a config without it loads.
-
-**Step 0 of everything below, once per repo:**
-
-\`\`\`sh
-loam init --docs ../docs-repo --service payment-service   # in EACH service repo
-loam doctor                                               # before you trust any of it
-\`\`\`
-
-\`loam init --docs <dir>\` **joins** an existing docs repo; creating a new one
-takes \`--create\`, so a mistyped path cannot quietly scaffold a second source of
-truth beside the real one. \`loam doctor\` is the read-only preflight: it reads
-loam.json defensively, resolves \`docsDir\`, probes access, checks \`services/\` and
-the system map, and reports the service binding — run it first when anything
-behaves as though the system were empty.
-
-**Living vs delta.** \`services/<svc>/spec.md\` is the complete current state.
-\`features/<FEAT>/specs/<svc>/spec.md\` is a diff against it, reviewed as a diff, with
-requirements grouped under \`## ADDED\`, \`## MODIFIED\` or \`## REMOVED Requirements\`.
-\`loam archive\` folds the delta into the living state.
-
-`;
-//# sourceMappingURL=artifacts.js.map

package/dist/core/agent/agents-md/artifacts.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"artifacts.js","sourceRoot":"","sources":["../../../../src/core/agent/agents-md/artifacts.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,CAAC,MAAM,SAAS,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAqMxB,CAAC","sourcesContent":["/**\n * The document's opening arc: what the docs repo HOLDS — the layout, how its\n * documents link to each other, the glossary, architectural obligations, and\n * the `loam.json` wiring every repository commits.\n *\n * The three sections that used to close this file — the architecture spec\n * axis, the generated Gherkin suite, and the frontmatter/vouch chain — are now\n * the `loam-authoring` reference page (../workflows/reference/authoring.ts),\n * printed by `loam instructions loam-authoring` rather than written into\n * AGENTS.md. They are grammars consulted while writing ONE document, and the\n * file they were in is auto-loaded on every session by hosts that truncate it\n * silently; ./command-map.ts's header carries the measurement that decided it.\n * What is left here is what an agent must know before it can form a question\n * at all.\n *\n * One section of the AGENTS.md template. ../agents-md.ts assembles the\n * document by PLAIN CONCATENATION — no join separator — so every section\n * starts at the first character of its opening line and ends with the newline\n * that closes its last one. Keep that shape when editing, or two sections glue\n * onto one line in every docs repo loam scaffolds from now on.\n */\nexport const ARTIFACTS = `# Working in this docs repo\n\nThis is a **loam** docs repo: the shared source of truth for a governed software\nsystem — its architecture, requirements, contracts and evidence. Everything here\nis plain files. \\`loam\\` reads and writes them; delete \\`loam\\` and the docs remain.\n\n**The bar this artifact set aims at is reproducibility**: a reader should be able\nto answer, from these files alone — what each governed boundary exposes, what it\nreaches, what shapes it exchanges, how it is run, and what pages whom —\nwithout opening the code. \\`loam validate\\` grades form and joins, never depth:\ngreen means the files agree with each other, and the bar is what \"done\" is\nmeasured against — a thin baseline that validates is thin, not done.\n\n## Layout\n\n\\`\\`\\`\narchitecture/landscape.likec4     the living C4 model of the whole system\narchitecture/permissions.yaml     optional system-wide authorization vocabulary\narchitecture/obligations.yaml     optional ARCHITECTURAL obligations (#obl-<name> on the map)\narchitecture/adrs/NNNN-*.md       optional SYSTEM-level decisions (MADR) — only their links are graded\nglossary/<term>.md                optional domain vocabulary — one file per term, nesting allowed\nservices/<svc>/\n  model.likec4                    this governed boundary's C4\n  spec.md                         its living requirements (current state)\n  arch.spec.md                    its living ARCHITECTURE requirements (outbox, retries, alerts)\n  openapi.yaml                    its API contract\n  asyncapi.yaml                   its AsyncAPI 3 event contract\n  adrs/  runbook.md  health.yaml  why it is like this, how to run it\nfeatures/<FEAT>/                  a change in flight\n  intent.md                       why, in business terms\n  delta.likec4                    the architecture change, tagged #<FEAT>\n  specs/<svc>/spec.md             the requirement change for one governed boundary\n  specs/<svc>/arch.spec.md        the architectural requirement change, same delta grammar\n  specs/<svc>/openapi.yaml        the endpoints this feature adds\n  specs/<svc>/asyncapi.yaml       the event-contract delta (optional; a complete AsyncAPI 3 document)\n  verification.yaml               what was checked once the code was built\nfeatures/archive/<FEAT>/          shipped changes — the evolution history\n\\`\\`\\`\n\n## Linking between documents\n\nDocuments here link to each other with **standard markdown links**, and the\ntarget is a relative path to the file:\n\n\\`\\`\\`markdown\n[0001 — transactional outbox](../../architecture/adrs/0001-transactional-outbox.md)\n\\`\\`\\`\n\nTwo reasons, and the second is the one that decides it. A markdown link renders\nas a link in pull-request review, which is where these documents are actually\nread, while \\`[[0001 transactional outbox]]\\` renders there as the literal\nbrackets somebody typed. And its target is a real relative path, so \"does this\nlink resolve\" is a filesystem question with a yes-or-no answer — where resolving\na wikilink means reimplementing Obsidian's shortest-unique-path search across the\nwhole repo, which is guessing, and loam refuses and names rather than guessing.\n\nYou lose nothing by it. Obsidian reads a repo written this way with no\nintegration at all — graph view, backlinks and search all work on markdown links\n— and its per-vault \\`Use [[Wikilinks]]\\` setting turns OFF, after which its own\nautocomplete and rename-tracking produce markdown links too. The authoring\ncomfort is a toggle in somebody's editor, not a decision this repo carries.\n\n**\\`loam validate\\` resolves these links** (\\`link.unresolved\\`, error): a relative\ntarget that names nothing is a broken join, reported once per document with\nevery bad link and its line. A link here is a **join**, not decoration — a\nrequirement that names a term wants that term's document linked, and an ADR that\nsupersedes another wants to say which, the same kind of relationship\n\\`Operations:\\` and \\`Covers:\\` already state.\n\nThree things are deliberately NOT graded, so write them freely: a target outside\nthis repository (\\`../../some-service/README.md\\` — that tree may not be checked\nout beside these documents), a link to a heading (\\`#section\\`), and any link\ninside a fenced code block or an inline code span, which is how a document shows\nthe convention without being convicted for it.\n\nCASE **is** graded, and deliberately: \\`[Order](Order.md)\\` beside a file called\n\\`order.md\\` resolves on Windows and macOS and 404s on GitHub and every Linux\nrunner, so the message names the stored spelling on all of them alike.\n\n## The glossary — the system's domain words\n\n\\`glossary/<term>.md\\`, one file per term, nesting allowed\n(\\`glossary/payments/authorization.md\\` is the term \\`payments/authorization\\`). There is\nno \\`glossary.yaml\\`: a definition is prose, and the DIRECTORY is the list. The\ndirectory's existence is the opt-in — a system without one hears nothing.\n\n**A term is checkable because a link is a join.** Cite it from the document that\nuses the word — a requirement, a capability document, a feature's intent — with an\nordinary relative link:\n\n\\`\\`\\`markdown\nAn [Order](../../glossary/order.md) is what a customer has confirmed.\n\\`\\`\\`\n\nA citation that does not resolve is \\`link.unresolved\\` like any other; a term nothing\noutside \\`glossary/\\` cites is \\`glossary.unlinked\\` (warn). Terms citing each other is\nnormal and does NOT count as adoption — a glossary is a network of definitions, and\ntwo terms defining each other say nothing about whether the system uses either word.\n\\`loam list glossary\\` prints every term with the documents that cite it.\n\n**A feature may bring a new word with it**: write it at\n\\`features/<FEAT>/glossary/<term>.md\\` and \\`loam archive\\` copies it into \\`glossary/\\`,\n\\`loam unarchive\\` takes it back out. This route is CREATE-ONLY — a term the living\nglossary already defines is \\`glossary.term-exists\\`, which \\`--approve\\` does not\noverride, because the merge is a whole-file copy and would replace an authored\ndefinition wholesale. To CHANGE a definition, edit \\`glossary/<term>.md\\` directly in\nthe same pull request, where git produces an ordinary conflict.\n\nCite the new word at its FUTURE living path (\\`../../../../glossary/order.md\\` from a\n\\`specs/<svc>/\\` delta) — that link resolves while the feature is in flight, and the\nmerge re-expresses it from wherever the text lands, so it keeps resolving afterwards.\n\nWrite the definition for a reader who knows the business and not this system: what the\nword means, and what it is NOT (an order is not a cart). Never which service owns it —\nthat is the system map's question and it changes.\n\n\n## Architectural obligations — what the architect hands the team\n\nAn architect has always had one checked channel here: an edge carrying\n\\`metadata { op 'authorizePayment' }\\` obliges the provider to define that operationId,\nor \\`spine.op-undefined\\` fails the gate. Obligations are the same handoff for the rules\nthat VARY — an outbox on this publisher and not that one, a circuit breaker on two\nedges out of five — and they are three separate things on purpose:\n\n- an **ADR** in \\`architecture/adrs/\\` says WHAT was decided, as thin or as thick as the\n  decision needs;\n- a **\\`#obl-<name>\\` tag** on an element or an edge in \\`architecture/landscape.likec4\\`\n  says WHERE it applies, so one ADR governs three edges and not the fourth without the\n  document forking;\n- **\\`architecture/obligations.yaml\\`** declares the names, so a mistyped tag is an error\n  rather than a word nobody notices.\n\n\\`\\`\\`yaml\nobligations:\n  outbox:\n    description: Publishers write the event and the state change in one transaction.\n    adr: architecture/adrs/0001-transactional-outbox.md   # relative to the docs repo root\n\\`\\`\\`\n\n**Your side of it is \\`Covers:\\`**. A tagged object with no living requirement covering it\nis \\`obligation.uncovered\\` (warn), and the finding names the service, the object and the\nexact line to write — \\`Covers: <element>\\` or \\`Covers: <source> -> <target>\\` in that\nservice's \\`arch.spec.md\\`, with a scenario that proves it. An id is its own tag suffix,\nso it may hold letters, digits, \\`_\\` and \\`-\\` only.\n\n## \\`loam.json\\` — the wiring, in every repo\n\nA governed system is **N + 1 repositories**: this docs repo, and one per governed\nimplementation boundary. Paths and commands call that boundary a \\`service\\`; it\nmay be a modular monolith, a network service, a CLI or a worker. Every repo\ncommits its own \\`loam.json\\`, so an agent, human or CI runner can find the rest\nof the system. There is no global config; without a \\`loam.json\\`, commands refuse\nwith \\`no-config\\` rather than guessing.\n\n\\`\\`\\`json\n{ \"docsDir\": \"../docs-repo\", \"service\": \"payment-service\", \"gherkinDir\": \"features\" }\n\\`\\`\\`\n\n- \\`docsDir\\` — where the docs repo is, **stored exactly as it was passed** and\n  resolved against the directory holding the \\`loam.json\\`. So \\`../docs-repo\\`\n  keeps working on every machine that checks the repos out side by side, which\n  is the point of committing the file. An absolute path is a warning\n  (\\`doctor.docs-absolute\\`): it resolves only on the machine that ran \\`loam init\\`.\n  The docs repo's own \\`loam.json\\` says \\`\"docsDir\": \".\"\\`.\n- \\`service\\` — the canonical id of the governed boundary THIS repo contains, i.e. the\n  \\`services/<id>/\\` directory it is allowed to speak for. \\`loam vouch\\`,\n  \\`loam gherkin\\` and \\`loam verify --service\\` when writing with \\`--record\\`,\n  \\`--results\\` or \\`--contract-results\\` bind to it; without it they refuse\n  (\\`repository-unavailable\\`) rather than write another boundary's documents\n  from a repo that is not that boundary's. A read-only verify checklist needs no\n  binding and works from the docs repo.\n- \\`gherkinDir\\` — optional, default \\`features\\`: the directory \\`loam gherkin\\`\n  writes its own \\`loam/\\` subtree into.\n- \\`agentTools\\` — optional: the agent tools \\`loam init\\` has written command and\n  skill files for here, accumulated across runs. Written by \\`init\\`, read by\n  \\`loam doctor\\`; nothing else depends on it, and a config without it loads.\n\n**Step 0 of everything below, once per repo:**\n\n\\`\\`\\`sh\nloam init --docs ../docs-repo --service payment-service   # in EACH service repo\nloam doctor                                               # before you trust any of it\n\\`\\`\\`\n\n\\`loam init --docs <dir>\\` **joins** an existing docs repo; creating a new one\ntakes \\`--create\\`, so a mistyped path cannot quietly scaffold a second source of\ntruth beside the real one. \\`loam doctor\\` is the read-only preflight: it reads\nloam.json defensively, resolves \\`docsDir\\`, probes access, checks \\`services/\\` and\nthe system map, and reports the service binding — run it first when anything\nbehaves as though the system were empty.\n\n**Living vs delta.** \\`services/<svc>/spec.md\\` is the complete current state.\n\\`features/<FEAT>/specs/<svc>/spec.md\\` is a diff against it, reviewed as a diff, with\nrequirements grouped under \\`## ADDED\\`, \\`## MODIFIED\\` or \\`## REMOVED Requirements\\`.\n\\`loam archive\\` folds the delta into the living state.\n\n`;\n"]}