@ybotok/loam 0.1.0-beta.3 → 0.2.0-alpha.1

package/dist/core/brief/landscape.js

@@ -0,0 +1,194 @@
+/**
+ * The fleet-map half of the adoption brief: what `architecture/landscape.likec4`
+ * already says about one service — its elements, its inbound and outbound
+ * edges, the operations the fleet already calls on it — and the block the
+ * service still owes the file when nothing in it resolves to the service yet.
+ * Both halves exist to stop an agent inventing a parallel model: the fleet has
+ * already drawn some of these boxes and edges, and a baseline has to attach to
+ * them.
+ */
+import { existsSync } from "node:fs";
+import { loadFile } from "../c4/likec4.js";
+import { elementService, serviceResolver } from "../c4/resolve/service.js";
+import { landscapePath } from "../repo/paths.js";
+import { enumeratedServiceIds, serviceTreePathOf } from "../repo/service-target.js";
+/**
+ * The LikeC4 identifier the fleet map's element for a service conventionally
+ * carries: the directory name, camel-cased. It is a suggestion and nothing
+ * more — `metadata { service '<id>' }` is what actually joins the element to
+ * the directory — but a brief that hands over a concrete block gets followed,
+ * and one that describes a block in prose gets improvised on.
+ */
+function elementIdFor(service) {
+    const parts = service.split(/[^A-Za-z0-9]+/).filter((p) => p !== "");
+    if (parts.length === 0)
+        return "service";
+    const head = parts[0].toLowerCase();
+    const tail = parts.slice(1).map((p) => p[0].toUpperCase() + p.slice(1).toLowerCase());
+    const id = head + tail.join("");
+    // LikeC4 identifiers cannot open with a digit; a service id can.
+    return /^[0-9]/.test(id) ? `svc${id[0].toUpperCase()}${id.slice(1)}` : id;
+}
+/**
+ * The block this service still owes `architecture/landscape.likec4`.
+ *
+ * `expects` is what the fleet ALREADY calls on the service — those edges exist
+ * in the map today, so the example draws the outbound side as a comment rather
+ * than telling an agent to duplicate an edge that is already there.
+ */
+function landscapeBlock(service, expects, present) {
+    const id = elementIdFor(service);
+    const calls = expects.length > 0
+        ? expects.map((op) => `//   <caller> -> ${id} 'Calls ${op}' { metadata { op '${op}' } }`)
+        : [`//   <caller> -> ${id} 'Calls <operationId>' { metadata { op '<operationId>' } }`];
+    const model = [
+        "model {",
+        ...(present ? ["  // ... the fleet's other services stay exactly as they are ...", ""] : []),
+        `  ${id} = softwareSystem '${service}' {`,
+        "    description '<one line: what this service is responsible for>'",
+        `    metadata { service '${service}' }`,
+        "  }",
+        "",
+        "  // every call in or out of it, one edge each:",
+        ...calls.map((line) => `  ${line}`),
+        "}",
+    ];
+    // When the file does not exist the example is the WHOLE file, so it carries
+    // the `specification` block a bare `model` would be rejected without: the
+    // brief must never hand over a document `loam validate` refuses. When the file
+    // does exist the example is a fragment to splice, and repeating a
+    // `specification` block there would invite a second one.
+    return present
+        ? model.join("\n")
+        : ["specification {", "  element softwareSystem", "}", "", ...model].join("\n");
+}
+/** The fleet map's own brief — assembled per service, because the block it owes names the service. */
+export function landscapeArtifact(service, expects, present, servicePath) {
+    return {
+        artifact: "landscape.likec4",
+        required: true,
+        purpose: "the fleet map — until an element here resolves to this directory, the service is documented and invisible to every cross-service check",
+        shape: [
+            "This file is the WHOLE FLEET's, not this service's. Add to it; never rewrite it. Everything already in `model { ... }` belongs to the other services, and replacing the file destroys their map along with their edges.",
+            `Add one top-level element for the service, bound to its directory: \`metadata { service '${service}' }\`. Until an element resolves to \`${servicePath}/\`, \`loam validate --all\` reports \`landscape.service-unmodelled\` (error).`,
+            "Bind rather than rename: a binding whose id names no directory is `landscape.binding-unknown` (error), and two elements binding the SAME directory is `landscape.binding-duplicate` (warn) — every element→service join then picks one of them arbitrarily.",
+            "Draw every cross-service call as an edge carrying the operation it uses: `a -> b 'Calls createSplit' { metadata { op 'createSplit' } }`. The `op` must be an operationId the TARGET's openapi.yaml defines, or `spine.op-undefined` (error) — a broken contract between services.",
+            "If the file does not exist yet, create it with a `specification { ... }` block declaring the kinds you use, then the `model { ... }` block. A landscape that does not parse is `landscape.invalid` (error) and blinds every cross-service check at once.",
+        ],
+        example: landscapeBlock(service, expects, present),
+    };
+}
+/**
+ * The service ids the resolver may fall back on when an element carries no
+ * `metadata { service }` binding — the same positive evidence `validate` and
+ * `list` hand it. A docs repo that cannot be enumerated (no `services/` yet:
+ * `adopt` runs there) leaves the resolver with bindings alone, which is what it
+ * had before.
+ */
+async function knownServices(docsDir) {
+    return new Set(await enumeratedServiceIds(docsDir));
+}
+/**
+ * What the living landscape already says about this service.
+ *
+ * This is the half of the brief that stops an agent inventing a parallel model:
+ * the fleet has already drawn some of these boxes and edges, and the baseline has
+ * to attach to them. A landscape that does not parse yields `modelled: null` —
+ * "nothing models it" would be a claim about a document nobody could read.
+ */
+export async function landscapeContext(docsDir, service) {
+    const path = landscapePath(docsDir);
+    // The service's own directory, spelled from the enumeration rather than joined
+    // at the root: this text is handed to an AGENT that will go and edit files, and
+    // a filed service named at `services/<id>/` sends it to create a second
+    // directory beside the one that already exists.
+    const servicePath = await serviceTreePathOf(docsDir, service);
+    const empty = {
+        present: existsSync(path),
+        parses: false,
+        modelled: null,
+        elements: [],
+        inbound: [],
+        outbound: [],
+        expects: [],
+        instruction: null,
+    };
+    if (!empty.present)
+        return { ...empty, modelled: false, instruction: instructionFor(service, "absent", [], servicePath) };
+    const land = await loadFile(path);
+    if (land.errors.length > 0)
+        return { ...empty, instruction: instructionFor(service, "unparseable", [], servicePath) };
+    const mine = (e) => elementService(e) === service;
+    const elements = land.elements.filter(mine).map((e) => ({
+        id: e.id,
+        title: e.title,
+        kind: e.kind,
+        tags: e.tags,
+        bound: e.service !== undefined,
+    }));
+    // One resolver for the whole scan, built with the real service ids: an edge
+    // drawn into a modelled container (`paymentService.api`) is an edge into the
+    // service, and `expects` — which now decides whether this service owes an
+    // OpenAPI contract at all — has to see it. Building it once also stops the
+    // per-edge rebuild the old `serviceOf(land.elements, id)` call did.
+    const svcOf = serviceResolver(land.elements, await knownServices(docsDir));
+    const inbound = [];
+    const outbound = [];
+    for (const r of land.relationships) {
+        const edge = { op: r.op ?? null, title: r.title ?? null };
+        if (svcOf(r.target) === service)
+            inbound.push({ from: svcOf(r.source), ...edge });
+        else if (svcOf(r.source) === service)
+            outbound.push({ to: svcOf(r.target), ...edge });
+    }
+    const expects = [...new Set(inbound.map((e) => e.op).filter((op) => op !== null))];
+    return {
+        present: true,
+        parses: true,
+        modelled: elements.length > 0,
+        elements,
+        inbound,
+        outbound,
+        expects,
+        instruction: elements.length > 0 ? null : instructionFor(service, "unmodelled", expects, servicePath),
+    };
+}
+/**
+ * The fleet-map instruction, in the three states a landscape can be in.
+ *
+ * It says the file, the block, and the consequence, in that order. The
+ * consequence is the part agents acted on: "add an element" reads as tidiness,
+ * "until you do, `loam validate --all` fails and no cross-service check can see
+ * this service" reads as work.
+ */
+function instructionFor(service, state, expects, servicePath) {
+    const id = elementIdFor(service);
+    const bind = `an element bound with \`metadata { service '${service}' }\``;
+    const consequence = `Until one resolves, \`loam validate --all\` reports \`landscape.service-unmodelled\` (error) for ` +
+        `${servicePath}/: the service is documented and invisible — no edge into it can be checked ` +
+        `against its openapi.yaml, and no feature can draw a call to it.`;
+    // `expects` is reachable only through elements that already resolve to this
+    // service, so it is empty in every state that produces an instruction. It is
+    // threaded through anyway rather than dropped: the caller computes it once,
+    // and the day an unmodelled service can inherit an edge (a container-level
+    // binding, say) the sentence is already here instead of being noticed missing.
+    const owed = expects.length > 0
+        ? ` The fleet already calls ${expects.map((o) => `'${o}'`).join(", ")} on this service, so those edges exist; your element is what they will resolve to.`
+        : "";
+    if (state === "absent") {
+        return (`architecture/landscape.likec4 does not exist yet. Create it with a \`specification { ... }\` block ` +
+            `declaring the kinds you use and a \`model { ... }\` block containing ${bind} ` +
+            `(conventionally \`${id} = softwareSystem '${service}'\`), plus one edge per cross-service call, each ` +
+            `carrying \`metadata { op '<operationId>' }\`. ${consequence}${owed}`);
+    }
+    if (state === "unparseable") {
+        return (`architecture/landscape.likec4 exists but does not parse (\`landscape.invalid\`), so nothing can be said ` +
+            `about what it already models. Fix the parse errors first — they blind every cross-service check at once — ` +
+            `then make sure it holds ${bind}. ${consequence}`);
+    }
+    return (`Nothing in architecture/landscape.likec4 resolves to ${servicePath}/. ADD to that file — do not rewrite ` +
+        `it, every other service's map is in there — ${bind}, conventionally ` +
+        `\`${id} = softwareSystem '${service}'\`, inside the existing \`model { ... }\` block, and draw each ` +
+        `cross-service call as an edge carrying \`metadata { op '<operationId>' }\`. ${consequence}${owed}`);
+}
+//# sourceMappingURL=landscape.js.map

package/dist/core/brief/landscape.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"landscape.js","sourceRoot":"","sources":["../../../src/core/brief/landscape.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * The fleet-map half of the adoption brief: what `architecture/landscape.likec4`\n * already says about one service — its elements, its inbound and outbound\n * edges, the operations the fleet already calls on it — and the block the\n * service still owes the file when nothing in it resolves to the service yet.\n * Both halves exist to stop an agent inventing a parallel model: the fleet has\n * already drawn some of these boxes and edges, and a baseline has to attach to\n * them.\n */\nimport { existsSync } from \"node:fs\";\nimport { loadFile, type Elem } from \"../c4/likec4.js\";\nimport { elementService, serviceResolver } from \"../c4/resolve/service.js\";\nimport { landscapePath } from \"../repo/paths.js\";\nimport { enumeratedServiceIds, serviceTreePathOf } from \"../repo/service-target.js\";\nimport type { BriefTarget } from \"./targets.js\";\nimport type { DocsDir } from \"../kernel/ids/dirs.js\";\n\n/**\n * The LikeC4 identifier the fleet map's element for a service conventionally\n * carries: the directory name, camel-cased. It is a suggestion and nothing\n * more — `metadata { service '<id>' }` is what actually joins the element to\n * the directory — but a brief that hands over a concrete block gets followed,\n * and one that describes a block in prose gets improvised on.\n */\nfunction elementIdFor(service: string): string {\n  const parts = service.split(/[^A-Za-z0-9]+/).filter((p) => p !== \"\");\n  if (parts.length === 0) return \"service\";\n  const head = parts[0]!.toLowerCase();\n  const tail = parts.slice(1).map((p) => p[0]!.toUpperCase() + p.slice(1).toLowerCase());\n  const id = head + tail.join(\"\");\n  // LikeC4 identifiers cannot open with a digit; a service id can.\n  return /^[0-9]/.test(id) ? `svc${id[0]!.toUpperCase()}${id.slice(1)}` : id;\n}\n\n/**\n * The block this service still owes `architecture/landscape.likec4`.\n *\n * `expects` is what the fleet ALREADY calls on the service — those edges exist\n * in the map today, so the example draws the outbound side as a comment rather\n * than telling an agent to duplicate an edge that is already there.\n */\nfunction landscapeBlock(service: string, expects: string[], present: boolean): string {\n  const id = elementIdFor(service);\n  const calls =\n    expects.length > 0\n      ? expects.map((op) => `//   <caller> -> ${id} 'Calls ${op}' { metadata { op '${op}' } }`)\n      : [`//   <caller> -> ${id} 'Calls <operationId>' { metadata { op '<operationId>' } }`];\n  const model = [\n    \"model {\",\n    ...(present ? [\"  // ... the fleet's other services stay exactly as they are ...\", \"\"] : []),\n    `  ${id} = softwareSystem '${service}' {`,\n    \"    description '<one line: what this service is responsible for>'\",\n    `    metadata { service '${service}' }`,\n    \"  }\",\n    \"\",\n    \"  // every call in or out of it, one edge each:\",\n    ...calls.map((line) => `  ${line}`),\n    \"}\",\n  ];\n  // When the file does not exist the example is the WHOLE file, so it carries\n  // the `specification` block a bare `model` would be rejected without: the\n  // brief must never hand over a document `loam validate` refuses. When the file\n  // does exist the example is a fragment to splice, and repeating a\n  // `specification` block there would invite a second one.\n  return present\n    ? model.join(\"\\n\")\n    : [\"specification {\", \"  element softwareSystem\", \"}\", \"\", ...model].join(\"\\n\");\n}\n\n/** The fleet map's own brief — assembled per service, because the block it owes names the service. */\nexport function landscapeArtifact(\n  service: string,\n  expects: string[],\n  present: boolean,\n  servicePath: string,\n): Omit<BriefTarget, \"path\" | \"exists\" | \"action\"> {\n  return {\n    artifact: \"landscape.likec4\",\n    required: true,\n    purpose:\n      \"the fleet map — until an element here resolves to this directory, the service is documented and invisible to every cross-service check\",\n    shape: [\n      \"This file is the WHOLE FLEET's, not this service's. Add to it; never rewrite it. Everything already in `model { ... }` belongs to the other services, and replacing the file destroys their map along with their edges.\",\n      `Add one top-level element for the service, bound to its directory: \\`metadata { service '${service}' }\\`. Until an element resolves to \\`${servicePath}/\\`, \\`loam validate --all\\` reports \\`landscape.service-unmodelled\\` (error).`,\n      \"Bind rather than rename: a binding whose id names no directory is `landscape.binding-unknown` (error), and two elements binding the SAME directory is `landscape.binding-duplicate` (warn) — every element→service join then picks one of them arbitrarily.\",\n      \"Draw every cross-service call as an edge carrying the operation it uses: `a -> b 'Calls createSplit' { metadata { op 'createSplit' } }`. The `op` must be an operationId the TARGET's openapi.yaml defines, or `spine.op-undefined` (error) — a broken contract between services.\",\n      \"If the file does not exist yet, create it with a `specification { ... }` block declaring the kinds you use, then the `model { ... }` block. A landscape that does not parse is `landscape.invalid` (error) and blinds every cross-service check at once.\",\n    ],\n    example: landscapeBlock(service, expects, present),\n  };\n}\n\n/* ------------------------------------------------------------------ */\n/* What the fleet already says about this service                      */\n/* ------------------------------------------------------------------ */\n\nexport interface LandscapeElement {\n  id: string;\n  title: string;\n  kind: string;\n  tags: string[];\n  /** True when the element binds explicitly with `metadata { service }`. */\n  bound: boolean;\n}\n\nexport interface LandscapeEdge {\n  from?: string;\n  to?: string;\n  op: string | null;\n  title: string | null;\n}\n\nexport interface LandscapeContext {\n  present: boolean;\n  /** False when the landscape exists but does not parse. */\n  parses: boolean;\n  /** Whether any element resolves to this service — null when nothing could be read. */\n  modelled: boolean | null;\n  elements: LandscapeElement[];\n  inbound: LandscapeEdge[];\n  outbound: LandscapeEdge[];\n  /** Operations other services already call on this one: the contract owes them. */\n  expects: string[];\n  /**\n   * The write this service still owes the fleet map, in prose — null once an\n   * element resolves to it.\n   *\n   * It duplicates the `landscape.likec4` target's shape rules on purpose: an\n   * agent driving off `--json` reads `landscape` to learn what the fleet\n   * already says, and every `targets[]` consumer walks the artifact list. Only\n   * one of those two readers used to exist, so `adopt` briefed eight files and\n   * never once said the ninth thing — that a documented service nobody drew is\n   * invisible to the whole cross-service layer.\n   */\n  instruction: string | null;\n}\n\n/**\n * The service ids the resolver may fall back on when an element carries no\n * `metadata { service }` binding — the same positive evidence `validate` and\n * `list` hand it. A docs repo that cannot be enumerated (no `services/` yet:\n * `adopt` runs there) leaves the resolver with bindings alone, which is what it\n * had before.\n */\nasync function knownServices(docsDir: DocsDir): Promise<ReadonlySet<string>> {\n  return new Set(await enumeratedServiceIds(docsDir));\n}\n\n/**\n * What the living landscape already says about this service.\n *\n * This is the half of the brief that stops an agent inventing a parallel model:\n * the fleet has already drawn some of these boxes and edges, and the baseline has\n * to attach to them. A landscape that does not parse yields `modelled: null` —\n * \"nothing models it\" would be a claim about a document nobody could read.\n */\nexport async function landscapeContext(docsDir: DocsDir, service: string): Promise<LandscapeContext> {\n  const path = landscapePath(docsDir);\n  // The service's own directory, spelled from the enumeration rather than joined\n  // at the root: this text is handed to an AGENT that will go and edit files, and\n  // a filed service named at `services/<id>/` sends it to create a second\n  // directory beside the one that already exists.\n  const servicePath = await serviceTreePathOf(docsDir, service);\n  const empty: LandscapeContext = {\n    present: existsSync(path),\n    parses: false,\n    modelled: null,\n    elements: [],\n    inbound: [],\n    outbound: [],\n    expects: [],\n    instruction: null,\n  };\n  if (!empty.present)\n    return { ...empty, modelled: false, instruction: instructionFor(service, \"absent\", [], servicePath) };\n\n  const land = await loadFile(path);\n  if (land.errors.length > 0)\n    return { ...empty, instruction: instructionFor(service, \"unparseable\", [], servicePath) };\n\n  const mine = (e: Elem): boolean => elementService(e) === service;\n  const elements: LandscapeElement[] = land.elements.filter(mine).map((e) => ({\n    id: e.id,\n    title: e.title,\n    kind: e.kind,\n    tags: e.tags,\n    bound: e.service !== undefined,\n  }));\n\n  // One resolver for the whole scan, built with the real service ids: an edge\n  // drawn into a modelled container (`paymentService.api`) is an edge into the\n  // service, and `expects` — which now decides whether this service owes an\n  // OpenAPI contract at all — has to see it. Building it once also stops the\n  // per-edge rebuild the old `serviceOf(land.elements, id)` call did.\n  const svcOf = serviceResolver(land.elements, await knownServices(docsDir));\n  const inbound: LandscapeEdge[] = [];\n  const outbound: LandscapeEdge[] = [];\n  for (const r of land.relationships) {\n    const edge = { op: r.op ?? null, title: r.title ?? null };\n    if (svcOf(r.target) === service) inbound.push({ from: svcOf(r.source), ...edge });\n    else if (svcOf(r.source) === service) outbound.push({ to: svcOf(r.target), ...edge });\n  }\n\n  const expects = [...new Set(inbound.map((e) => e.op).filter((op): op is string => op !== null))];\n  return {\n    present: true,\n    parses: true,\n    modelled: elements.length > 0,\n    elements,\n    inbound,\n    outbound,\n    expects,\n    instruction:\n      elements.length > 0 ? null : instructionFor(service, \"unmodelled\", expects, servicePath),\n  };\n}\n\n/**\n * The fleet-map instruction, in the three states a landscape can be in.\n *\n * It says the file, the block, and the consequence, in that order. The\n * consequence is the part agents acted on: \"add an element\" reads as tidiness,\n * \"until you do, `loam validate --all` fails and no cross-service check can see\n * this service\" reads as work.\n */\nfunction instructionFor(\n  service: string,\n  state: \"absent\" | \"unparseable\" | \"unmodelled\",\n  expects: string[],\n  servicePath: string,\n): string {\n  const id = elementIdFor(service);\n  const bind = `an element bound with \\`metadata { service '${service}' }\\``;\n  const consequence =\n    `Until one resolves, \\`loam validate --all\\` reports \\`landscape.service-unmodelled\\` (error) for ` +\n    `${servicePath}/: the service is documented and invisible — no edge into it can be checked ` +\n    `against its openapi.yaml, and no feature can draw a call to it.`;\n  // `expects` is reachable only through elements that already resolve to this\n  // service, so it is empty in every state that produces an instruction. It is\n  // threaded through anyway rather than dropped: the caller computes it once,\n  // and the day an unmodelled service can inherit an edge (a container-level\n  // binding, say) the sentence is already here instead of being noticed missing.\n  const owed =\n    expects.length > 0\n      ? ` The fleet already calls ${expects.map((o) => `'${o}'`).join(\", \")} on this service, so those edges exist; your element is what they will resolve to.`\n      : \"\";\n\n  if (state === \"absent\") {\n    return (\n      `architecture/landscape.likec4 does not exist yet. Create it with a \\`specification { ... }\\` block ` +\n      `declaring the kinds you use and a \\`model { ... }\\` block containing ${bind} ` +\n      `(conventionally \\`${id} = softwareSystem '${service}'\\`), plus one edge per cross-service call, each ` +\n      `carrying \\`metadata { op '<operationId>' }\\`. ${consequence}${owed}`\n    );\n  }\n  if (state === \"unparseable\") {\n    return (\n      `architecture/landscape.likec4 exists but does not parse (\\`landscape.invalid\\`), so nothing can be said ` +\n      `about what it already models. Fix the parse errors first — they blind every cross-service check at once — ` +\n      `then make sure it holds ${bind}. ${consequence}`\n    );\n  }\n  return (\n    `Nothing in architecture/landscape.likec4 resolves to ${servicePath}/. ADD to that file — do not rewrite ` +\n    `it, every other service's map is in there — ${bind}, conventionally ` +\n    `\\`${id} = softwareSystem '${service}'\\`, inside the existing \\`model { ... }\\` block, and draw each ` +\n    `cross-service call as an edge carrying \\`metadata { op '<operationId>' }\\`. ${consequence}${owed}`\n  );\n}\n"]}

package/dist/core/brief/targets.js

@@ -0,0 +1,226 @@
+/**
+ * The artifacts of the adoption brief: what each file under `services/<svc>/`
+ * is for, the grammar it has to be written in, and a minimal valid example
+ * where showing one is shorter than describing it. Every `shape` rule here is
+ * one a later check depends on, and test/agent-contract.test.ts pins the
+ * mapping. This module is the list alone — `serviceBrief` (brief.ts) resolves
+ * it against a docs repo, and the fleet map's own target, whose block names
+ * the service, is assembled per service in landscape.ts.
+ */
+/** The artifacts, in the order a baseline is best written in. */
+export const ARTIFACTS = [
+    {
+        artifact: "model.likec4",
+        key: "model",
+        required: true,
+        purpose: "the service's C4 — what it is, what is inside it, what it talks to",
+        // Every rule below is one a later check depends on, and the mapping is
+        // pinned in test/agent-contract.test.ts. Rules nobody checks — the `views`
+        // block, "exactly one top-level element" — used to sit here reading exactly
+        // like the enforced ones, which is how a brief teaches an agent that
+        // `loam validate` passing means more than it does. They now live in
+        // UNCHECKED, where their status is the point.
+        shape: [
+            "A `specification { ... }` block declaring every element kind you use (`element softwareSystem`, `element container`). LikeC4 rejects an undeclared kind, and `loam validate --service <id>` reports it as `c4.invalid` with line numbers.",
+            "A `model { ... }` block holding the service's element, with containers and components nested inside it. The whole file has to parse — `loam validate` runs LikeC4 in-process and reports `c4.invalid` with line numbers.",
+            "The service element binds to this directory: `metadata { service '<id>' }`. Without a binding the element's TITLE has to equal the directory name — and then renaming the box silently unlinks every check that joined the two. The same binding is what makes the FLEET map resolve an element to `services/<id>/`; until one does, `loam validate --all` reports `landscape.service-unmodelled`.",
+            "A call to another service is an edge that names the operation it uses: `a -> b 'Calls createSplit' { metadata { op 'createSplit' } }`. Cross-service edges belong in `architecture/landscape.likec4` (a target of its own, below) — this file cannot even resolve the other service's element — and there the `op` must be an operationId the TARGET's openapi.yaml defines, or `spine.op-undefined` fires.",
+        ],
+        example: `specification {
+  element softwareSystem
+  element container
+}
+
+model {
+  paymentService = softwareSystem 'payment-service' {
+    description 'Owns payment authorization and capture'
+    metadata { service 'payment-service' }
+
+    api = container 'HTTP API'
+    ledger = container 'Ledger store'
+  }
+}
+
+// Views are LikeC4's, not loam's: loam parses this file and computes no view,
+// and it never reads a STATIC view's contents in any document, so nothing below
+// is read by any check (docs/DESIGN.md rule 26 — the one thing loam does read is
+// a dynamic view's declared steps, and only in the fleet landscape).
+// Keep it for the renderer, which does draw it — 'npx likec4 start services/<id>' from the docs repo, pointed at THIS
+// directory. Not the repo root: every service model declares its own
+// 'specification' block, so the root is scoped to architecture/ (likec4.config.json)
+// and one model at a time is how these files are meant to be read.
+// Scoped to one service 'include *' is cheap; the same line in
+// architecture/landscape.likec4 walks every call in the fleet and takes minutes.
+views {
+  view of paymentService {
+    include *
+  }
+}
+`,
+    },
+    {
+        artifact: "spec.md",
+        key: "spec",
+        required: true,
+        purpose: "the living requirements — what this service is required to do, as it stands today",
+        shape: [
+            "Frontmatter (below), then a `## Requirements` heading.",
+            "`### Requirement: <name>` — ONE observable behaviour, written with SHALL, testable without reading the code. Add `Requirement-ID: <id>` in its body for stable identity across heading renames; legacy requirements without one continue to match by exact name.",
+            "At least one `#### Scenario: <name>` per requirement, with Given/When/Then bullets. This is gated (`requirements.missing-scenarios`) — scenarios are the acceptance criteria and the source for tests.",
+            "A markdown TABLE in a scenario body becomes the `Examples` of a `Scenario Outline`: the header names the placeholders the steps use (`<permission>`), one row per case. This is how a matrix is written — a permission matrix, a validation matrix, a status-code table is ONE scenario with twenty rows, never twenty scenarios. `loam gherkin` emits the outline, cucumber reports one result per row carrying that scenario's digest tag, and `loam verify --results` confirms the claim only when EVERY row passed. Every row must have the header's column count and a header needs at least one row: a table loam cannot read stays in the description, the scenario then runs once instead of once per case, and the emission says so out loud.",
+            "A step takes an ARGUMENT by carrying it INDENTED under the bullet, and this is what lets one scenario assert a whole data pass rather than a sentence. An indented table becomes that step's Gherkin DATA TABLE — `- **Then** the outbox holds:` followed by the rows it must hold; a fenced block becomes its DOCSTRING, indentation intact — `- **When** the caller posts:` followed by the JSON body. Indentation is the entire disambiguation: indented under a step means this step's rows, at the margin means the scenario's cases, and both ride into the scenario digest. Write the ASSERTIONS OUT, one bullet each, including the negative ones (`no row is created in ...`, `... is not invoked`) and each meter separately: a scenario that summarises them reads complete, emits valid Gherkin, grades green, and tests a fraction of what it claims.",
+            "`Requires: <subject>/<permission>[, ...]` in the requirement body names the authorization it is gated on, resolved against the FLEET vocabulary in `architecture/permissions.yaml`. An entry that is not declared there is `permissions.unknown` (error) — the same grade as `Operations:`, because an invented permission reads exactly like a real one everywhere downstream. Add the permission to that file when this service enforces one nobody has written down yet; the subject is the entity it is checked ON (`user`, `profile`, `service`), which is not always the caller.",
+            "`Capability: <id>[, ...]` in the requirement body names the fleet capabilities this requirement realizes part of, declared in `architecture/capabilities.yaml`. A LIST, because the relation is many-to-many: one requirement commonly closes part of two capabilities. The FILE is this axis's opt-in — a fleet without it gets no capability findings — and once it exists an undeclared name is `capability.unknown` (error). Write the line only where the requirement genuinely carries part of the named capability.",
+            "Write the requirement body in EARS form — `WHEN <trigger> THE SYSTEM SHALL <response>`, `IF <precondition> THEN THE SYSTEM SHALL <response>`, `WHERE <feature is included> THE SYSTEM SHALL <response>`, or a bare `THE SYSTEM SHALL <response>` when it is unconditional. **Nothing checks this** — it is a writing convention, and it is here because the grammar forces the trigger and the response to be named separately, while free prose lets a requirement read as complete while stating no condition at all. That is the exact shape a guard collapses into when it is summarised rather than enumerated.",
+            "`Operations: <operationId>[, <operationId>]` in the requirement body names the API operations it governs. Every one must exist in this service's openapi.yaml — a name that does not is `spec-api.op-undefined` (error), reported against the LIVING spec, not only inside a feature delta.",
+            "Document what the service DOES today, not what it should do. This is the baseline; changes to it belong in a feature delta.",
+        ],
+        example: `---
+service: payment-service
+status: draft
+owner: payments-team
+sources:
+  - src/main/java/com/shop/payment/
+---
+
+# payment-service
+
+## Requirements
+
+### Requirement: Authorize a payment
+WHEN authorization is requested for a captured-eligible order THE SYSTEM SHALL
+authorize it against the issuer before any capture.
+
+Operations: authorizePayment
+
+#### Scenario: Successful authorization
+- **Given** a valid card and an amount within its limit
+- **When** authorization is requested
+- **Then** the payment is authorized and an authorization id is returned
+
+### Requirement: Refunding is permission-gated
+IF the caller lacks the refund permission THEN THE SYSTEM SHALL refuse the
+request and leave the payment untouched.
+
+Operations: refundPayment
+
+#### Scenario: Refund by permission
+- **Given** a captured payment
+- **When** a caller holding <permission> requests a refund
+- **Then** the response is <status> and the payment is <state>
+
+| permission      | status | state    |
+|-----------------|--------|----------|
+| payments:refund | 200    | refunded |
+| payments:read   | 403    | captured |
+| (none)          | 401    | captured |
+`,
+    },
+    {
+        artifact: "arch.spec.md",
+        key: "archSpec",
+        required: false,
+        purpose: "the living architecture requirements — the obligations the business spec never carries: outbox, retries, idempotency, metrics, alerts",
+        shape: [
+            "Same grammar and frontmatter as spec.md: `## Requirements`, `### Requirement:` + `#### Scenario:` with Given/When/Then. The same checks read it.",
+            "A `Covers:` line per requirement names what its scenarios exercise: a C4 element id (`paymentService.db`), an edge (`paymentService -> kafka`), or a health signal from health.yaml (`alert:<id>` / `sli:<id>`). Every entry must resolve, or `covers.unknown` (warn) flags the typo.",
+            "Optional, but expected for a service with real architecture: every alert/SLI health.yaml declares wants a covering requirement here (`health.uncovered`, warn) — a signal nothing tests is dashboard decoration.",
+            "Write the obligations no business requirement states — the transactional outbox, what a caller's retry may assume, what pages whom. An arch scenario becomes an integration/ops test, not an acceptance test.",
+        ],
+        example: `---
+service: payment-service
+status: draft
+owner: payments-team
+sources:
+  - src/main/java/com/shop/payment/
+---
+
+# payment-service — architecture
+
+## Requirements
+
+### Requirement: Events leave through the transactional outbox
+The service SHALL write a domain event and its state change in one transaction,
+published by an outbox relay — never a dual write.
+
+Covers: paymentService.db, paymentService -> kafka
+
+#### Scenario: Broker down at commit time
+- **Given** an event in the outbox
+- **When** the broker is unavailable
+- **Then** the state stays committed and the event is published once it returns
+`,
+    },
+    {
+        artifact: "openapi.yaml",
+        key: "openapi",
+        // Overridden per service in `serviceBrief` (brief.ts): an API is required
+        // only where the fleet expects one. See `apiExpected` there.
+        required: true,
+        purpose: "the API contract — the operations this service exposes",
+        shape: [
+            "OpenAPI 3.x with a `paths` map.",
+            "EVERY operation carries an `operationId`. That token is the spine: the C4 edge's `metadata { op }`, the requirement's `Operations:` line and this `operationId` are one name spelled three times, and they must be identical.",
+            "loam reads operationIds, and probes the rest by PRESENCE only: an operation whose responses declare no schema warns (`openapi.response-undescribed`), an internal `$ref` to nothing warns (`openapi.ref-unresolved`). What a declared schema SAYS is still never checked — the schemas are for humans, codegen and review, so getting them wrong is invisible here and expensive later.",
+            "Document the endpoints that exist. An operation the fleet already calls (see `landscape.expects`) must be in here, or the contract breaks the moment this lands.",
+            // The instruction the brief was missing, and the one that matters most:
+            // it used to mark this artifact required unconditionally, in capitals,
+            // which for a UI, a worker or a cron told the agent to invent an API into
+            // the source of truth. `required` is derived now; this says so in prose
+            // as well, because an agent reading the shape rules must not re-derive
+            // "MISSING" as "write something".
+            "If this service exposes no HTTP API, there is no file to write. Do not invent one — an empty or imagined contract is a claim the whole fleet then joins against. `required` above is derived from the fleet map: it is false exactly when the landscape parses and no edge calls an operation on this service, which is the same evidence that keeps `service.no-openapi` quiet.",
+        ],
+    },
+    {
+        artifact: "asyncapi.yaml",
+        key: "asyncapi",
+        // Never required. Unlike the HTTP contract, whose necessity the fleet map
+        // can PROVE (an op-linked edge points here), most services in a legacy fleet
+        // touch no topic at all — and a required artifact nobody owes is how a
+        // whole adoption wave learns to ignore the brief.
+        required: false,
+        purpose: "the async contract — the messages this service puts on and takes off the bus",
+        shape: [
+            "AsyncAPI **3.0** with `channels`, `operations` and `components.messages`. Only 3.0 is read: its operations are named top-level objects carrying `action: send|receive`, which is what makes a message's direction legible. A 2.x document declares no `operations` and reads as a contract with no messages.",
+            "EVERY message carries a `name` (or is declared under the key you intend to reference). That token is the spine: the C4 edge's `metadata { publishes }` / `metadata { consumes }`, the requirement's `Publishes:` / `Consumes:` line and this name are one name spelled three times.",
+            "Namespace the name by the domain that owns it — `payment.PaymentAuthorized`. One message has exactly one producer; two services declaring they send one name is `asyncapi.message-contested`, and then which contract a consumer reads is a coin flip.",
+            "loam reads message names and the `action` of the operation carrying them. **It never joins on anything inside `payload`** — the one look inside is a presence probe: a payload declaring no shape at all warns (`asyncapi.payload-undescribed`), and a payload with a non-JSON `schemaFormat` is skipped outright. Write the payload as JSON Schema today; if the fleet later adopts Avro, that is a `schemaFormat` line here and nothing in loam changes.",
+            "Keep payloads in `components.schemas` in THIS file rather than `$ref`-ing an external `.avsc`. External references are out of scope for the merge, exactly as on the OpenAPI axis, so a schema in another file will not travel with the message that needs it.",
+            "If this service publishes and consumes nothing, there is no file to write. Do not invent one.",
+        ],
+    },
+    {
+        artifact: "adrs/",
+        key: "adrsDir",
+        required: false,
+        purpose: "the decisions behind the shape of the service",
+        shape: [
+            "One file per decision: `adrs/NNNN-<slug>.md`, MADR-style (context · decision · consequences).",
+            "Only decisions whose consequences are still visible in the code. A reconstructed rationale for something nobody decided is fiction, and it is the kind that survives review because it sounds reasonable.",
+            "If a decision is evident but its reasoning is not, write the decision and say the reasoning is unknown. That is a fact; a plausible motive is not.",
+        ],
+    },
+    {
+        artifact: "runbook.md",
+        key: "runbook",
+        required: false,
+        purpose: "how it is run — deploys, dependencies, what to do when it pages",
+        shape: [
+            "Frontmatter, then how it is deployed and configured, what it depends on, and what to do about the failures that actually happen.",
+            "Written from what is in the repo (pipelines, manifests, alert definitions). Whoever carries the pager verifies it; leave `status: draft` until they have.",
+            "A 'configured but not a dependency, and why' list: every capability the configuration wires up that the deploy manifest switches off. Without it, the next reader re-derives the dependency from the config and re-adds what the manifest already removed.",
+        ],
+    },
+    {
+        artifact: "health.yaml",
+        key: "health",
+        required: false,
+        purpose: "SLIs, SLOs, checks and the dependencies that are critical",
+        shape: [
+            "SLIs and SLOs as they have been AGREED, plus health checks and critical dependencies.",
+            "If no SLO has ever been agreed, say so and leave it out. An invented 99.9% becomes a number other teams plan against.",
+        ],
+    },
+];
+//# sourceMappingURL=targets.js.map

package/dist/core/brief/targets.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"targets.js","sourceRoot":"","sources":["../../../src/core/brief/targets.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAiDH,iEAAiE;AACjE,MAAM,CAAC,MAAM,SAAS,GAA8E;IAClG;QACE,QAAQ,EAAE,cAAc;QACxB,GAAG,EAAE,OAAO;QACZ,QAAQ,EAAE,IAAI;QACd,OAAO,EAAE,oEAAoE;QAC7E,uEAAuE;QACvE,2EAA2E;QAC3E,4EAA4E;QAC5E,qEAAqE;QACrE,oEAAoE;QACpE,8CAA8C;QAC9C,KAAK,EAAE;YACL,2OAA2O;YAC3O,0NAA0N;YAC1N,oYAAoY;YACpY,6YAA6Y;SAC9Y;QACD,OAAO,EAAE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA8BZ;KACE;IACD;QACE,QAAQ,EAAE,SAAS;QACnB,GAAG,EAAE,MAAM;QACX,QAAQ,EAAE,IAAI;QACd,OAAO,EAAE,mFAAmF;QAC5F,KAAK,EAAE;YACL,wDAAwD;YACxD,kQAAkQ;YAClQ,wMAAwM;YACxM,wtBAAwtB;YACxtB,o0BAAo0B;YACp0B,wjBAAwjB;YACxjB,4fAA4f;YAC5f,slBAAslB;YACtlB,6RAA6R;YAC7R,6HAA6H;SAC9H;QACD,OAAO,EAAE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAuCZ;KACE;IACD;QACE,QAAQ,EAAE,cAAc;QACxB,GAAG,EAAE,UAAU;QACf,QAAQ,EAAE,KAAK;QACf,OAAO,EACL,uIAAuI;QACzI,KAAK,EAAE;YACL,kJAAkJ;YAClJ,uRAAuR;YACvR,kNAAkN;YAClN,+MAA+M;SAChN;QACD,OAAO,EAAE;;;;;;;;;;;;;;;;;;;;;;CAsBZ;KACE;IACD;QACE,QAAQ,EAAE,cAAc;QACxB,GAAG,EAAE,SAAS;QACd,0EAA0E;QAC1E,6DAA6D;QAC7D,QAAQ,EAAE,IAAI;QACd,OAAO,EAAE,wDAAwD;QACjE,KAAK,EAAE;YACL,iCAAiC;YACjC,+NAA+N;YAC/N,yXAAyX;YACzX,kKAAkK;YAClK,wEAAwE;YACxE,uEAAuE;YACvE,0EAA0E;YAC1E,wEAAwE;YACxE,uEAAuE;YACvE,kCAAkC;YAClC,kXAAkX;SACnX;KACF;IACD;QACE,QAAQ,EAAE,eAAe;QACzB,GAAG,EAAE,UAAU;QACf,0EAA0E;QAC1E,6EAA6E;QAC7E,uEAAuE;QACvE,kDAAkD;QAClD,QAAQ,EAAE,KAAK;QACf,OAAO,EAAE,8EAA8E;QACvF,KAAK,EAAE;YACL,8SAA8S;YAC9S,qRAAqR;YACrR,wPAAwP;YACxP,4bAA4b;YAC5b,gQAAgQ;YAChQ,+FAA+F;SAChG;KACF;IACD;QACE,QAAQ,EAAE,OAAO;QACjB,GAAG,EAAE,SAAS;QACd,QAAQ,EAAE,KAAK;QACf,OAAO,EAAE,+CAA+C;QACxD,KAAK,EAAE;YACL,+FAA+F;YAC/F,2MAA2M;YAC3M,oJAAoJ;SACrJ;KACF;IACD;QACE,QAAQ,EAAE,YAAY;QACtB,GAAG,EAAE,SAAS;QACd,QAAQ,EAAE,KAAK;QACf,OAAO,EAAE,iEAAiE;QAC1E,KAAK,EAAE;YACL,kIAAkI;YAClI,2JAA2J;YAC3J,4PAA4P;SAC7P;KACF;IACD;QACE,QAAQ,EAAE,aAAa;QACvB,GAAG,EAAE,QAAQ;QACb,QAAQ,EAAE,KAAK;QACf,OAAO,EAAE,2DAA2D;QACpE,KAAK,EAAE;YACL,uFAAuF;YACvF,uHAAuH;SACxH;KACF;CACF,CAAC","sourcesContent":["/**\n * The artifacts of the adoption brief: what each file under `services/<svc>/`\n * is for, the grammar it has to be written in, and a minimal valid example\n * where showing one is shorter than describing it. Every `shape` rule here is\n * one a later check depends on, and test/agent-contract.test.ts pins the\n * mapping. This module is the list alone — `serviceBrief` (brief.ts) resolves\n * it against a docs repo, and the fleet map's own target, whose block names\n * the service, is assembled per service in landscape.ts.\n */\n\n/* ------------------------------------------------------------------ */\n/* The artifacts                                                       */\n/* ------------------------------------------------------------------ */\n\nexport interface BriefTarget {\n  /** File name as it appears under `services/<svc>/`. */\n  artifact: string;\n  /** Repo-relative path to write. */\n  path: string;\n  exists: boolean;\n  /**\n   * `create` a missing artifact; `diff` an existing one — never overwrite it.\n   *\n   * `edit` is the third case and belongs to exactly one target: the fleet map.\n   * `architecture/landscape.likec4` is a SHARED document that already holds\n   * every other service, so \"diff it and report what disagrees\" is the wrong\n   * instruction — the file is not this service's baseline, it is the fleet's,\n   * and what this service owes it is an addition inside the existing\n   * `model { … }` block. Spelling that as `diff` taught agents to leave the\n   * fleet map alone; spelling it as `create` would have taught them to\n   * overwrite ten other services.\n   */\n  action: \"create\" | \"diff\" | \"edit\";\n  /**\n   * False for artifacts a baseline can legitimately ship without. True means\n   * required for a COMPLETE baseline — validate grades a missing spec.md or\n   * openapi.yaml as a warn (`service.no-spec` / `service.no-openapi`), not an\n   * error: partial adoption is a supported state, and the warns are the\n   * progress meter.\n   *\n   * Constant per artifact except one: `openapi.yaml` is required only where the\n   * fleet map shows an API is expected (see `apiExpected` in brief.ts), because\n   * the brief is read as an instruction and \"MISSING openapi.yaml\" told an agent\n   * to write a contract for a service that serves no requests.\n   */\n  required: boolean;\n  /** What the artifact is for, in one line. */\n  purpose: string;\n  /** The grammar. Every rule here is one a later check depends on. */\n  shape: string[];\n  /** A minimal valid instance, where showing one is shorter than describing it. */\n  example?: string;\n}\n\n/** Where an artifact lives — `repo/paths.ts` spells the filenames, this only points at them. */\ntype PathKey = \"model\" | \"spec\" | \"archSpec\" | \"openapi\" | \"asyncapi\" | \"adrsDir\" | \"runbook\" | \"health\";\n\n/** The artifacts, in the order a baseline is best written in. */\nexport const ARTIFACTS: Array<Omit<BriefTarget, \"path\" | \"exists\" | \"action\"> & { key: PathKey }> = [\n  {\n    artifact: \"model.likec4\",\n    key: \"model\",\n    required: true,\n    purpose: \"the service's C4 — what it is, what is inside it, what it talks to\",\n    // Every rule below is one a later check depends on, and the mapping is\n    // pinned in test/agent-contract.test.ts. Rules nobody checks — the `views`\n    // block, \"exactly one top-level element\" — used to sit here reading exactly\n    // like the enforced ones, which is how a brief teaches an agent that\n    // `loam validate` passing means more than it does. They now live in\n    // UNCHECKED, where their status is the point.\n    shape: [\n      \"A `specification { ... }` block declaring every element kind you use (`element softwareSystem`, `element container`). LikeC4 rejects an undeclared kind, and `loam validate --service <id>` reports it as `c4.invalid` with line numbers.\",\n      \"A `model { ... }` block holding the service's element, with containers and components nested inside it. The whole file has to parse — `loam validate` runs LikeC4 in-process and reports `c4.invalid` with line numbers.\",\n      \"The service element binds to this directory: `metadata { service '<id>' }`. Without a binding the element's TITLE has to equal the directory name — and then renaming the box silently unlinks every check that joined the two. The same binding is what makes the FLEET map resolve an element to `services/<id>/`; until one does, `loam validate --all` reports `landscape.service-unmodelled`.\",\n      \"A call to another service is an edge that names the operation it uses: `a -> b 'Calls createSplit' { metadata { op 'createSplit' } }`. Cross-service edges belong in `architecture/landscape.likec4` (a target of its own, below) — this file cannot even resolve the other service's element — and there the `op` must be an operationId the TARGET's openapi.yaml defines, or `spine.op-undefined` fires.\",\n    ],\n    example: `specification {\n  element softwareSystem\n  element container\n}\n\nmodel {\n  paymentService = softwareSystem 'payment-service' {\n    description 'Owns payment authorization and capture'\n    metadata { service 'payment-service' }\n\n    api = container 'HTTP API'\n    ledger = container 'Ledger store'\n  }\n}\n\n// Views are LikeC4's, not loam's: loam parses this file and computes no view,\n// and it never reads a STATIC view's contents in any document, so nothing below\n// is read by any check (docs/DESIGN.md rule 26 — the one thing loam does read is\n// a dynamic view's declared steps, and only in the fleet landscape).\n// Keep it for the renderer, which does draw it — 'npx likec4 start services/<id>' from the docs repo, pointed at THIS\n// directory. Not the repo root: every service model declares its own\n// 'specification' block, so the root is scoped to architecture/ (likec4.config.json)\n// and one model at a time is how these files are meant to be read.\n// Scoped to one service 'include *' is cheap; the same line in\n// architecture/landscape.likec4 walks every call in the fleet and takes minutes.\nviews {\n  view of paymentService {\n    include *\n  }\n}\n`,\n  },\n  {\n    artifact: \"spec.md\",\n    key: \"spec\",\n    required: true,\n    purpose: \"the living requirements — what this service is required to do, as it stands today\",\n    shape: [\n      \"Frontmatter (below), then a `## Requirements` heading.\",\n      \"`### Requirement: <name>` — ONE observable behaviour, written with SHALL, testable without reading the code. Add `Requirement-ID: <id>` in its body for stable identity across heading renames; legacy requirements without one continue to match by exact name.\",\n      \"At least one `#### Scenario: <name>` per requirement, with Given/When/Then bullets. This is gated (`requirements.missing-scenarios`) — scenarios are the acceptance criteria and the source for tests.\",\n      \"A markdown TABLE in a scenario body becomes the `Examples` of a `Scenario Outline`: the header names the placeholders the steps use (`<permission>`), one row per case. This is how a matrix is written — a permission matrix, a validation matrix, a status-code table is ONE scenario with twenty rows, never twenty scenarios. `loam gherkin` emits the outline, cucumber reports one result per row carrying that scenario's digest tag, and `loam verify --results` confirms the claim only when EVERY row passed. Every row must have the header's column count and a header needs at least one row: a table loam cannot read stays in the description, the scenario then runs once instead of once per case, and the emission says so out loud.\",\n      \"A step takes an ARGUMENT by carrying it INDENTED under the bullet, and this is what lets one scenario assert a whole data pass rather than a sentence. An indented table becomes that step's Gherkin DATA TABLE — `- **Then** the outbox holds:` followed by the rows it must hold; a fenced block becomes its DOCSTRING, indentation intact — `- **When** the caller posts:` followed by the JSON body. Indentation is the entire disambiguation: indented under a step means this step's rows, at the margin means the scenario's cases, and both ride into the scenario digest. Write the ASSERTIONS OUT, one bullet each, including the negative ones (`no row is created in ...`, `... is not invoked`) and each meter separately: a scenario that summarises them reads complete, emits valid Gherkin, grades green, and tests a fraction of what it claims.\",\n      \"`Requires: <subject>/<permission>[, ...]` in the requirement body names the authorization it is gated on, resolved against the FLEET vocabulary in `architecture/permissions.yaml`. An entry that is not declared there is `permissions.unknown` (error) — the same grade as `Operations:`, because an invented permission reads exactly like a real one everywhere downstream. Add the permission to that file when this service enforces one nobody has written down yet; the subject is the entity it is checked ON (`user`, `profile`, `service`), which is not always the caller.\",\n      \"`Capability: <id>[, ...]` in the requirement body names the fleet capabilities this requirement realizes part of, declared in `architecture/capabilities.yaml`. A LIST, because the relation is many-to-many: one requirement commonly closes part of two capabilities. The FILE is this axis's opt-in — a fleet without it gets no capability findings — and once it exists an undeclared name is `capability.unknown` (error). Write the line only where the requirement genuinely carries part of the named capability.\",\n      \"Write the requirement body in EARS form — `WHEN <trigger> THE SYSTEM SHALL <response>`, `IF <precondition> THEN THE SYSTEM SHALL <response>`, `WHERE <feature is included> THE SYSTEM SHALL <response>`, or a bare `THE SYSTEM SHALL <response>` when it is unconditional. **Nothing checks this** — it is a writing convention, and it is here because the grammar forces the trigger and the response to be named separately, while free prose lets a requirement read as complete while stating no condition at all. That is the exact shape a guard collapses into when it is summarised rather than enumerated.\",\n      \"`Operations: <operationId>[, <operationId>]` in the requirement body names the API operations it governs. Every one must exist in this service's openapi.yaml — a name that does not is `spec-api.op-undefined` (error), reported against the LIVING spec, not only inside a feature delta.\",\n      \"Document what the service DOES today, not what it should do. This is the baseline; changes to it belong in a feature delta.\",\n    ],\n    example: `---\nservice: payment-service\nstatus: draft\nowner: payments-team\nsources:\n  - src/main/java/com/shop/payment/\n---\n\n# payment-service\n\n## Requirements\n\n### Requirement: Authorize a payment\nWHEN authorization is requested for a captured-eligible order THE SYSTEM SHALL\nauthorize it against the issuer before any capture.\n\nOperations: authorizePayment\n\n#### Scenario: Successful authorization\n- **Given** a valid card and an amount within its limit\n- **When** authorization is requested\n- **Then** the payment is authorized and an authorization id is returned\n\n### Requirement: Refunding is permission-gated\nIF the caller lacks the refund permission THEN THE SYSTEM SHALL refuse the\nrequest and leave the payment untouched.\n\nOperations: refundPayment\n\n#### Scenario: Refund by permission\n- **Given** a captured payment\n- **When** a caller holding <permission> requests a refund\n- **Then** the response is <status> and the payment is <state>\n\n| permission      | status | state    |\n|-----------------|--------|----------|\n| payments:refund | 200    | refunded |\n| payments:read   | 403    | captured |\n| (none)          | 401    | captured |\n`,\n  },\n  {\n    artifact: \"arch.spec.md\",\n    key: \"archSpec\",\n    required: false,\n    purpose:\n      \"the living architecture requirements — the obligations the business spec never carries: outbox, retries, idempotency, metrics, alerts\",\n    shape: [\n      \"Same grammar and frontmatter as spec.md: `## Requirements`, `### Requirement:` + `#### Scenario:` with Given/When/Then. The same checks read it.\",\n      \"A `Covers:` line per requirement names what its scenarios exercise: a C4 element id (`paymentService.db`), an edge (`paymentService -> kafka`), or a health signal from health.yaml (`alert:<id>` / `sli:<id>`). Every entry must resolve, or `covers.unknown` (warn) flags the typo.\",\n      \"Optional, but expected for a service with real architecture: every alert/SLI health.yaml declares wants a covering requirement here (`health.uncovered`, warn) — a signal nothing tests is dashboard decoration.\",\n      \"Write the obligations no business requirement states — the transactional outbox, what a caller's retry may assume, what pages whom. An arch scenario becomes an integration/ops test, not an acceptance test.\",\n    ],\n    example: `---\nservice: payment-service\nstatus: draft\nowner: payments-team\nsources:\n  - src/main/java/com/shop/payment/\n---\n\n# payment-service — architecture\n\n## Requirements\n\n### Requirement: Events leave through the transactional outbox\nThe service SHALL write a domain event and its state change in one transaction,\npublished by an outbox relay — never a dual write.\n\nCovers: paymentService.db, paymentService -> kafka\n\n#### Scenario: Broker down at commit time\n- **Given** an event in the outbox\n- **When** the broker is unavailable\n- **Then** the state stays committed and the event is published once it returns\n`,\n  },\n  {\n    artifact: \"openapi.yaml\",\n    key: \"openapi\",\n    // Overridden per service in `serviceBrief` (brief.ts): an API is required\n    // only where the fleet expects one. See `apiExpected` there.\n    required: true,\n    purpose: \"the API contract — the operations this service exposes\",\n    shape: [\n      \"OpenAPI 3.x with a `paths` map.\",\n      \"EVERY operation carries an `operationId`. That token is the spine: the C4 edge's `metadata { op }`, the requirement's `Operations:` line and this `operationId` are one name spelled three times, and they must be identical.\",\n      \"loam reads operationIds, and probes the rest by PRESENCE only: an operation whose responses declare no schema warns (`openapi.response-undescribed`), an internal `$ref` to nothing warns (`openapi.ref-unresolved`). What a declared schema SAYS is still never checked — the schemas are for humans, codegen and review, so getting them wrong is invisible here and expensive later.\",\n      \"Document the endpoints that exist. An operation the fleet already calls (see `landscape.expects`) must be in here, or the contract breaks the moment this lands.\",\n      // The instruction the brief was missing, and the one that matters most:\n      // it used to mark this artifact required unconditionally, in capitals,\n      // which for a UI, a worker or a cron told the agent to invent an API into\n      // the source of truth. `required` is derived now; this says so in prose\n      // as well, because an agent reading the shape rules must not re-derive\n      // \"MISSING\" as \"write something\".\n      \"If this service exposes no HTTP API, there is no file to write. Do not invent one — an empty or imagined contract is a claim the whole fleet then joins against. `required` above is derived from the fleet map: it is false exactly when the landscape parses and no edge calls an operation on this service, which is the same evidence that keeps `service.no-openapi` quiet.\",\n    ],\n  },\n  {\n    artifact: \"asyncapi.yaml\",\n    key: \"asyncapi\",\n    // Never required. Unlike the HTTP contract, whose necessity the fleet map\n    // can PROVE (an op-linked edge points here), most services in a legacy fleet\n    // touch no topic at all — and a required artifact nobody owes is how a\n    // whole adoption wave learns to ignore the brief.\n    required: false,\n    purpose: \"the async contract — the messages this service puts on and takes off the bus\",\n    shape: [\n      \"AsyncAPI **3.0** with `channels`, `operations` and `components.messages`. Only 3.0 is read: its operations are named top-level objects carrying `action: send|receive`, which is what makes a message's direction legible. A 2.x document declares no `operations` and reads as a contract with no messages.\",\n      \"EVERY message carries a `name` (or is declared under the key you intend to reference). That token is the spine: the C4 edge's `metadata { publishes }` / `metadata { consumes }`, the requirement's `Publishes:` / `Consumes:` line and this name are one name spelled three times.\",\n      \"Namespace the name by the domain that owns it — `payment.PaymentAuthorized`. One message has exactly one producer; two services declaring they send one name is `asyncapi.message-contested`, and then which contract a consumer reads is a coin flip.\",\n      \"loam reads message names and the `action` of the operation carrying them. **It never joins on anything inside `payload`** — the one look inside is a presence probe: a payload declaring no shape at all warns (`asyncapi.payload-undescribed`), and a payload with a non-JSON `schemaFormat` is skipped outright. Write the payload as JSON Schema today; if the fleet later adopts Avro, that is a `schemaFormat` line here and nothing in loam changes.\",\n      \"Keep payloads in `components.schemas` in THIS file rather than `$ref`-ing an external `.avsc`. External references are out of scope for the merge, exactly as on the OpenAPI axis, so a schema in another file will not travel with the message that needs it.\",\n      \"If this service publishes and consumes nothing, there is no file to write. Do not invent one.\",\n    ],\n  },\n  {\n    artifact: \"adrs/\",\n    key: \"adrsDir\",\n    required: false,\n    purpose: \"the decisions behind the shape of the service\",\n    shape: [\n      \"One file per decision: `adrs/NNNN-<slug>.md`, MADR-style (context · decision · consequences).\",\n      \"Only decisions whose consequences are still visible in the code. A reconstructed rationale for something nobody decided is fiction, and it is the kind that survives review because it sounds reasonable.\",\n      \"If a decision is evident but its reasoning is not, write the decision and say the reasoning is unknown. That is a fact; a plausible motive is not.\",\n    ],\n  },\n  {\n    artifact: \"runbook.md\",\n    key: \"runbook\",\n    required: false,\n    purpose: \"how it is run — deploys, dependencies, what to do when it pages\",\n    shape: [\n      \"Frontmatter, then how it is deployed and configured, what it depends on, and what to do about the failures that actually happen.\",\n      \"Written from what is in the repo (pipelines, manifests, alert definitions). Whoever carries the pager verifies it; leave `status: draft` until they have.\",\n      \"A 'configured but not a dependency, and why' list: every capability the configuration wires up that the deploy manifest switches off. Without it, the next reader re-derives the dependency from the config and re-adds what the manifest already removed.\",\n    ],\n  },\n  {\n    artifact: \"health.yaml\",\n    key: \"health\",\n    required: false,\n    purpose: \"SLIs, SLOs, checks and the dependencies that are critical\",\n    shape: [\n      \"SLIs and SLOs as they have been AGREED, plus health checks and critical dependencies.\",\n      \"If no SLO has ever been agreed, say so and leave it out. An invented 99.9% becomes a number other teams plan against.\",\n    ],\n  },\n];\n"]}

package/dist/core/brief/unchecked.js

@@ -0,0 +1,47 @@
+/**
+ * What no check will ever tell you. Read it as the list of ways to be wrong
+ * quietly. The checks that do exist — the table an adoption baseline actually
+ * meets — live in checks.ts; this module is that table's counterpart, split
+ * out so each half can grow without crowding the other.
+ *
+ * The first two entries are here because they used to be `shape` rules on
+ * model.likec4, phrased exactly like the enforced ones. A brief that states an
+ * unenforced rule beside four enforced ones is not merely useless — it is the
+ * way an agent learns that a green `loam validate` means more than it does.
+ * Anything nothing checks belongs on this list, where its status IS the point.
+ */
+export const UNCHECKED = [
+    // Not merely unchecked — unread. This entry used to end "write one", on the
+    // theory that a view is what makes a model legible. It is, to LikeC4's
+    // renderer; loam computes none. Saying otherwise taught agents that a views
+    // block was owed to loam, and an `include *` over the FLEET map is the one
+    // shape that costs minutes rather than milliseconds.
+    //
+    // Still exactly true of PRESENCE, which is what this entry is about. Rule 26
+    // lets loam read a dynamic view's declared steps WHERE ONE EXISTS; nothing
+    // grades their absence, and the failure this comment records — agents
+    // learning that a views block is owed to loam — is the one rule 26 is
+    // written to prevent recurring.
+    "Whether model.likec4 declares a `views { ... }` block, or any view at all — and nothing in loam ever will. What loam reads, when a `dynamic view` IS present, is only what its author declared: the view's tags and its ordered steps. It computes no view and renders nothing, and it never grades a model for lacking one — a fleet that draws no diagrams owes loam no views block, today or ever. Views belong to LikeC4's own renderer: write them if you want diagrams, and read them with `npx likec4 start <dir>` pointed at ONE directory — `services/<id>` for a service model, the docs repo root for the fleet map (`likec4.config.json` scopes that root project to `architecture/`). The renderer merges every `.likec4` file it is given into one model, and loam parses each of them alone, so each declares its own `specification` block: point it at a directory holding two of them and every declaration reads as a duplicate. Scope your views too — computing a view is superlinear in the number of edges, and an `include *` over `architecture/landscape.likec4` is the expensive one, because that file holds every call in the fleet.",
+    // The readability half of the entry above. They are separate entries because
+    // the failures are: one is a view that takes minutes to compute, the other is
+    // a view that computes instantly and cannot be read. A fleet acquires the
+    // second one the day its second service starts publishing, and every service
+    // after that makes it worse by exactly one edge — which is why it arrives as
+    // a surprise on a map that was fine last quarter.
+    "Whether the fleet map is LEGIBLE — nothing in loam draws it, so nothing in loam notices. The shape that goes first is a shared broker: Kafka, a bus, a gateway, drawn as ONE element, is the node every service in the fleet points at, and a view over it is a star with sixty spokes. Model the TOPIC rather than the broker — `paymentEvents = topic 'payment.events'` nested inside the broker's element, with the edges pointing at `kafka.paymentEvents` — and one hub of degree sixty becomes twelve of degree five, which is also the truer model: the contract a producer and a consumer share is the topic, never the broker. Declare `element topic { #external, style { shape queue } }` in the `specification` block and give the nested elements that kind: LikeC4 does not inherit tags, so a topic under an `#external` broker is NOT external itself and `loam validate --all` asks for a `services/payment.events/` nobody owes (`landscape.service-undocumented`). Then scope the views, which is where the rest of the legibility lives: `exclude element.tag = #external` keeps the fleet overview to the calls between our own services, and a second view over the broker draws the event spine on its own.",
+    "Whether the model has exactly ONE top-level element for the service, with its containers nested inside. Five top-level boxes for one service parse, validate and bind exactly as well as one — and then the fleet map, which joins elements to directories, has five candidates for the same service and no way to say which is wrong.",
+    "Whether the model is the architecture the code actually has. loam parses model.likec4; it never reads a line of the service.",
+    "Whether a requirement is TRUE of the service. `loam validate` checks that a requirement has a scenario, never that either one describes real behaviour.",
+    "Whether the scenarios are acceptance criteria somebody could test, or the requirement restated in Given/When/Then.",
+    "Whether an operationId is the one the code serves, and whether the request and response schemas resemble what the endpoint really accepts and returns. Presence is probed — an operation with no response schema at all is warned about — but what a declared schema SAYS is never compared with anything; only the operationId joins.",
+    "Whether the runbook's steps work, or the health.yaml SLOs are numbers anyone agreed to.",
+    "Whether an arch scenario really exercises what its `Covers:` line names. The entries are resolved against the model and health.yaml — never against code, tests, dashboards or alert rules.",
+    "Whether an ADR records a decision that was made, or one reconstructed afterwards to justify the code.",
+    "COMPLETENESS. Forty behaviours documented as one requirement passes every check loam has. So does a service with one endpoint documented out of thirty.",
+    "REPRODUCIBILITY — the bar the artifact set aims at: could a reader answer, without the code, what the service exposes, what it reaches, what shapes it exchanges, how it is run and what pages whom. The depth probes catch an EMPTY contract; nothing measures a shallow one against the service, so green means the files agree with each other, never that they reach the bar.",
+    "Whether an arch requirement recording effective configuration or a library's semantics ('retries: -1 is unbounded, proven from the bytecode') is still true of the chart and the classpath. The convention names arch.spec.md as the home for such facts; loam never verifies the values.",
+    "Whether a permission in `architecture/permissions.yaml` is one the system actually has. `Requires:` is checked against that file and the file against nothing: a vocabulary that agrees with every requirement citing it can still name three permissions the identity provider retired last year, and `owned_by` / `enforced_by` are read as prose — neither is resolved against `services/`, and a realm is never opened. The check is a spelling guard between documents, exactly as `Operations:` is; whether the word is real is a question only the running system answers.",
+    "Whether `sources` names the files you read. loam checks those paths exist — not that they are the ones the document came from.",
+];
+//# sourceMappingURL=unchecked.js.map

package/dist/core/brief/unchecked.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"unchecked.js","sourceRoot":"","sources":["../../../src/core/brief/unchecked.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,MAAM,CAAC,MAAM,SAAS,GAAa;IACjC,4EAA4E;IAC5E,uEAAuE;IACvE,4EAA4E;IAC5E,2EAA2E;IAC3E,qDAAqD;IACrD,EAAE;IACF,6EAA6E;IAC7E,2EAA2E;IAC3E,sEAAsE;IACtE,sEAAsE;IACtE,gCAAgC;IAChC,mmCAAmmC;IACnmC,6EAA6E;IAC7E,8EAA8E;IAC9E,0EAA0E;IAC1E,6EAA6E;IAC7E,6EAA6E;IAC7E,kDAAkD;IAClD,oqCAAoqC;IACpqC,wUAAwU;IACxU,8HAA8H;IAC9H,yJAAyJ;IACzJ,oHAAoH;IACpH,wUAAwU;IACxU,yFAAyF;IACzF,6LAA6L;IAC7L,uGAAuG;IACvG,yJAAyJ;IACzJ,mXAAmX;IACnX,2RAA2R;IAC3R,mjBAAmjB;IACnjB,gIAAgI;CACjI,CAAC","sourcesContent":["/**\n * What no check will ever tell you. Read it as the list of ways to be wrong\n * quietly. The checks that do exist — the table an adoption baseline actually\n * meets — live in checks.ts; this module is that table's counterpart, split\n * out so each half can grow without crowding the other.\n *\n * The first two entries are here because they used to be `shape` rules on\n * model.likec4, phrased exactly like the enforced ones. A brief that states an\n * unenforced rule beside four enforced ones is not merely useless — it is the\n * way an agent learns that a green `loam validate` means more than it does.\n * Anything nothing checks belongs on this list, where its status IS the point.\n */\nexport const UNCHECKED: string[] = [\n  // Not merely unchecked — unread. This entry used to end \"write one\", on the\n  // theory that a view is what makes a model legible. It is, to LikeC4's\n  // renderer; loam computes none. Saying otherwise taught agents that a views\n  // block was owed to loam, and an `include *` over the FLEET map is the one\n  // shape that costs minutes rather than milliseconds.\n  //\n  // Still exactly true of PRESENCE, which is what this entry is about. Rule 26\n  // lets loam read a dynamic view's declared steps WHERE ONE EXISTS; nothing\n  // grades their absence, and the failure this comment records — agents\n  // learning that a views block is owed to loam — is the one rule 26 is\n  // written to prevent recurring.\n  \"Whether model.likec4 declares a `views { ... }` block, or any view at all — and nothing in loam ever will. What loam reads, when a `dynamic view` IS present, is only what its author declared: the view's tags and its ordered steps. It computes no view and renders nothing, and it never grades a model for lacking one — a fleet that draws no diagrams owes loam no views block, today or ever. Views belong to LikeC4's own renderer: write them if you want diagrams, and read them with `npx likec4 start <dir>` pointed at ONE directory — `services/<id>` for a service model, the docs repo root for the fleet map (`likec4.config.json` scopes that root project to `architecture/`). The renderer merges every `.likec4` file it is given into one model, and loam parses each of them alone, so each declares its own `specification` block: point it at a directory holding two of them and every declaration reads as a duplicate. Scope your views too — computing a view is superlinear in the number of edges, and an `include *` over `architecture/landscape.likec4` is the expensive one, because that file holds every call in the fleet.\",\n  // The readability half of the entry above. They are separate entries because\n  // the failures are: one is a view that takes minutes to compute, the other is\n  // a view that computes instantly and cannot be read. A fleet acquires the\n  // second one the day its second service starts publishing, and every service\n  // after that makes it worse by exactly one edge — which is why it arrives as\n  // a surprise on a map that was fine last quarter.\n  \"Whether the fleet map is LEGIBLE — nothing in loam draws it, so nothing in loam notices. The shape that goes first is a shared broker: Kafka, a bus, a gateway, drawn as ONE element, is the node every service in the fleet points at, and a view over it is a star with sixty spokes. Model the TOPIC rather than the broker — `paymentEvents = topic 'payment.events'` nested inside the broker's element, with the edges pointing at `kafka.paymentEvents` — and one hub of degree sixty becomes twelve of degree five, which is also the truer model: the contract a producer and a consumer share is the topic, never the broker. Declare `element topic { #external, style { shape queue } }` in the `specification` block and give the nested elements that kind: LikeC4 does not inherit tags, so a topic under an `#external` broker is NOT external itself and `loam validate --all` asks for a `services/payment.events/` nobody owes (`landscape.service-undocumented`). Then scope the views, which is where the rest of the legibility lives: `exclude element.tag = #external` keeps the fleet overview to the calls between our own services, and a second view over the broker draws the event spine on its own.\",\n  \"Whether the model has exactly ONE top-level element for the service, with its containers nested inside. Five top-level boxes for one service parse, validate and bind exactly as well as one — and then the fleet map, which joins elements to directories, has five candidates for the same service and no way to say which is wrong.\",\n  \"Whether the model is the architecture the code actually has. loam parses model.likec4; it never reads a line of the service.\",\n  \"Whether a requirement is TRUE of the service. `loam validate` checks that a requirement has a scenario, never that either one describes real behaviour.\",\n  \"Whether the scenarios are acceptance criteria somebody could test, or the requirement restated in Given/When/Then.\",\n  \"Whether an operationId is the one the code serves, and whether the request and response schemas resemble what the endpoint really accepts and returns. Presence is probed — an operation with no response schema at all is warned about — but what a declared schema SAYS is never compared with anything; only the operationId joins.\",\n  \"Whether the runbook's steps work, or the health.yaml SLOs are numbers anyone agreed to.\",\n  \"Whether an arch scenario really exercises what its `Covers:` line names. The entries are resolved against the model and health.yaml — never against code, tests, dashboards or alert rules.\",\n  \"Whether an ADR records a decision that was made, or one reconstructed afterwards to justify the code.\",\n  \"COMPLETENESS. Forty behaviours documented as one requirement passes every check loam has. So does a service with one endpoint documented out of thirty.\",\n  \"REPRODUCIBILITY — the bar the artifact set aims at: could a reader answer, without the code, what the service exposes, what it reaches, what shapes it exchanges, how it is run and what pages whom. The depth probes catch an EMPTY contract; nothing measures a shallow one against the service, so green means the files agree with each other, never that they reach the bar.\",\n  \"Whether an arch requirement recording effective configuration or a library's semantics ('retries: -1 is unbounded, proven from the bytecode') is still true of the chart and the classpath. The convention names arch.spec.md as the home for such facts; loam never verifies the values.\",\n  \"Whether a permission in `architecture/permissions.yaml` is one the system actually has. `Requires:` is checked against that file and the file against nothing: a vocabulary that agrees with every requirement citing it can still name three permissions the identity provider retired last year, and `owned_by` / `enforced_by` are read as prose — neither is resolved against `services/`, and a realm is never opened. The check is a spelling guard between documents, exactly as `Operations:` is; whether the word is real is a question only the running system answers.\",\n  \"Whether `sources` names the files you read. loam checks those paths exist — not that they are the ones the document came from.\",\n];\n"]}