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

package/examples/docs/services/platform/notification-service/spec.md

@@ -0,0 +1,112 @@
+---
+service: notification-service
+status: draft
+owner: growth-team
+sources:
+  - internal/consumer/
+  - internal/sender/
+  - cmd/notifier/
+---
+
+# notification-service
+
+Turns fleet events into customer email and SMS. This is the **living spec** — the complete
+current state; feature deltas merge in here on `loam archive`.
+
+This service exposes **no HTTP API**: the liveness and readiness probes in `health.yaml` are the
+only ports it listens on, and nothing in the fleet calls them. That is a documented shape rather
+than a gap — no edge in the landscape carries `metadata { op }` into this service, so
+`loam validate` stays silent about the missing `openapi.yaml` instead of warning. The silence is
+earned rather than granted: it turns into a warning the moment the landscape stops proving
+nobody calls this service — it goes missing, or it stops parsing — and into an error the moment
+a requirement here grows an `Operations:` line or an op-linked edge points in. Every requirement
+below therefore carries a `Consumes:` line and no `Operations:` line: what this service promises
+is a reaction to a message, and the message name is the only join it has.
+
+## Requirements
+
+### Requirement: Notify a customer when an order is placed
+
+Requirement-ID: NTF-ORDER-PLACED
+The service SHALL send exactly one order-confirmation notification per order, addressed to the
+contact details it holds for the customer at the moment the confirmation is rendered.
+
+Consumes: order.OrderPlaced
+Capability: order-notifications
+
+#### Scenario: First delivery of an order event
+- **Given** an `order.OrderPlaced` carrying an `orderId` this service has never sent a confirmation for
+- **When** the consumer handles it
+- **Then** a confirmation is rendered from the contact details on file and handed to the provider
+- **And** the delivery log records the send under that `orderId`
+
+#### Scenario: The broker redelivers an event already sent
+- **Given** a confirmation already recorded in the delivery log for that `orderId`
+- **When** kafka redelivers the same `order.OrderPlaced`
+- **Then** no second notification is sent and the event is acknowledged
+- **And** the customer is not told twice about one order
+
+### Requirement: Send a receipt when a payment is captured
+
+Requirement-ID: NTF-RECEIPT
+The service SHALL send a receipt for every captured payment, stating the captured amount and
+currency exactly as the capture reported them.
+
+Consumes: payment.PaymentCaptured
+Capability: order-notifications
+
+#### Scenario: Receipt follows a capture
+- **Given** a `payment.PaymentCaptured` for an order this service has already confirmed
+- **When** the consumer handles it
+- **Then** a receipt showing `capturedAmount` in `currency` is sent to the contact on file
+
+#### Scenario: A capture arrives before the order it belongs to
+- **Given** a `payment.PaymentCaptured` whose `orderId` this service has not yet seen on the order topic
+- **When** the consumer handles it
+- **Then** the receipt is held until the matching `order.OrderPlaced` arrives, and sent then
+- **And** no receipt is sent for an order the customer has not been told exists
+
+### Requirement: Keep contact details current
+
+Requirement-ID: NTF-CONTACT
+The service SHALL keep its copy of a customer's email and phone in step with the CRM, applying
+an update only when it is newer than the copy already held.
+
+Consumes: crm.CustomerUpdated
+
+#### Scenario: A newer update replaces the copy on file
+- **Given** contact details held at `version` 4 for a customer
+- **When** a `crm.CustomerUpdated` for that customer arrives at `version` 5
+- **Then** the stored email and phone are replaced with the ones the event carries
+
+#### Scenario: An out-of-order update is ignored
+- **Given** contact details held at `version` 5 for a customer
+- **When** a `crm.CustomerUpdated` for that customer arrives at `version` 4
+- **Then** the stored details are left as they are
+- **And** the next notification still goes to the newer address
+
+#### Scenario: A customer this service has never notified
+- **Given** a `crm.CustomerUpdated` for a `customerId` with no contact details on file
+- **When** the consumer handles it
+- **Then** the details are stored, so the first notification for that customer is addressable
+
+### Requirement: Notify a customer when a refund completes
+
+Requirement-ID: NTF-REFUND
+The service SHALL send exactly one refund notification per refunded payment, stating the
+refunded amount and currency exactly as the refund reported them, and SHALL NOT send one
+until the refund is complete.
+
+Consumes: payment.PaymentRefunded
+Capability: order-notifications
+
+#### Scenario: A completed refund is announced once
+- **Given** a `payment.PaymentRefunded` for an order this service has already confirmed
+- **When** the consumer handles it
+- **Then** a refund notification is rendered with the refunded amount and currency
+- **And** the delivery log records the send under that `paymentId`
+
+#### Scenario: The broker redelivers a refund already announced
+- **Given** a refund notification already recorded in the delivery log for that `paymentId`
+- **When** kafka redelivers the same `payment.PaymentRefunded`
+- **Then** no second notification is sent and the event is acknowledged

package/examples/docs/services/platform/subsystem.yaml

@@ -0,0 +1,2 @@
+title: Platform
+description: Cross-cutting identity and messaging

package/examples/fleet.yaml

@@ -0,0 +1,57 @@
+# The whole input to `loam seed` — the fleet map's first hour, stated by a human.
+#
+# This is the file the spine-first entry starts from (README's "Start from the
+# fleet spine", WORKFLOW.md's day zero step 2). It names the five services of
+# `examples/docs`, the one subsystem they are filed under, the externals they
+# reach, and who calls whom. `loam seed --from examples/fleet.yaml` templates
+# `architecture/landscape.likec4` and one `services/<id>/` directory per entry
+# from exactly these facts and guesses nothing else.
+#
+# What it deliberately does NOT carry is the operation on each edge. `seed`
+# draws the call; a human writes `metadata { op 'createOrder' }` on it, and
+# that token is what turns a drawn arrow into a checked join against the
+# provider's `openapi.yaml`. That is the labour the spine-first entry asks for,
+# and it is the artifact nothing else produces.
+#
+# Re-running is safe: seed refuses (`seed-landscape-edited`) rather than
+# overwrite a landscape a human has touched.
+
+services:
+  - checkout-web
+  - order-service
+  - payment-service
+  # A service filed under a subsystem is written as a mapping. The subsystem is
+  # a directory under services/ and a grouping element in the map; no identity
+  # depends on it, so a service can move later without breaking a single join.
+  - id: identity-service
+    subsystem: platform
+  - id: notification-service
+    subsystem: platform
+
+subsystems:
+  - platform
+
+# Named here, they are drawn as elements the fleet reaches but does not own.
+# An external never becomes a directory under services/, so it is never graded
+# for a spec, a contract or provenance — which is the point: `stripe` is not a
+# service anybody here documents.
+externals:
+  - customer
+  - stripe
+  - kafka
+
+# `a -> b`, where each endpoint is a service id or an external declared above.
+# Every one of these becomes an edge in the landscape with no operation on it;
+# the follow-up work is naming the operation each call actually makes.
+calls:
+  - customer -> checkout-web
+  - checkout-web -> order-service
+  - checkout-web -> payment-service
+  - order-service -> payment-service
+  - order-service -> identity-service
+  - payment-service -> identity-service
+  - payment-service -> stripe
+  - payment-service -> kafka
+  - order-service -> kafka
+  - kafka -> order-service
+  - kafka -> notification-service

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@ybotok/loam",
-  "version": "0.1.0-beta.3",
-  "description": "Architecture-first spec framework for microservice fleets: reverse-engineer service docs from code, drive cross-service features from C4 deltas.",
+  "version": "0.2.0-alpha.2",
+  "description": "Architecture-first semantic integrity and change governance for evolving software systems: connect C4, requirements, contracts, and verification evidence.",
   "author": "spentsov",
   "repository": {
     "type": "git",
@@ -13,9 +13,13 @@
   },
   "keywords": [
     "architecture",
+    "architecture-governance",
     "c4",
+    "distributed-systems",
     "gherkin",
     "microservices",
+    "modular-monolith",
+    "semantic-integrity",
     "spec-driven-development"
   ],
   "type": "module",
@@ -24,11 +28,16 @@
   },
   "files": [
     "dist",
+    "examples",
     "CHANGELOG.md",
     "COMPARISON.md",
+    "CONTRIBUTING.md",
     "MIGRATING-from-OpenSpec.md",
+    "QUICKSTART.md",
+    "ROADMAP.md",
     "SCHEMA.md",
-    "SECURITY.md"
+    "SECURITY.md",
+    "WORKFLOW.md"
   ],
   "publishConfig": {
     "access": "public",
@@ -44,16 +53,20 @@
     "dev": "tsx src/cli.ts",
     "start": "node dist/cli.js",
     "lint": "oxlint -D correctness --import-plugin --promise-plugin --node-plugin --deny-warnings src test scripts",
-    "typecheck": "tsc --noEmit",
+    "typecheck": "tsc --noEmit && tsc -p tsconfig.scripts.json",
     "test": "vitest run",
     "test:coverage": "vitest run --coverage",
+    "arch:graph": "node scripts/package-graph.mjs",
+    "arch:check": "node scripts/arch-check.mjs",
+    "meta:model": "node scripts/self-model.mjs --print",
+    "meta:agents": "tsx scripts/meta-agents.ts",
+    "meta:check": "node scripts/self-model.mjs",
     "test:package": "node scripts/package-smoke.mjs",
     "release:check": "node scripts/release-check.mjs",
     "release:check:selftest": "node scripts/release-check.mjs --fixture-ready",
     "release:pack": "node scripts/pack-release.mjs",
-    "pilot:run": "node scripts/pilot-harness.mjs",
-    "pilot:check": "node scripts/pilot-harness.mjs --check-manifest docs/pilot/manifest.example.json --selftest",
     "test:openspec-corpus": "tsx scripts/check-openspec-corpus.ts",
+    "bench:validate": "tsx scripts/bench-validate.ts",
     "setup": "bash scripts/setup.sh"
   },
   "license": "MIT",

package/dist/commands/adopt.js

@@ -1,240 +0,0 @@
-import { existsSync } from "node:fs";
-import { closeIds } from "../core/arch.js";
-import { loadConfig } from "../core/config.js";
-import { InvalidIdError, assertServiceId } from "../core/ids.js";
-import { emitJson, fail, NO_SERVICE_MESSAGE, reportNoConfig } from "../core/json.js";
-import { DocsRepoUnavailableError, listServices, servicePaths } from "../core/repo.js";
-import { SEVERITY_MARK } from "../core/report.js";
-import { serviceBrief, VIA_ALL } from "../core/brief.js";
-import { docsRepoReady } from "./docs-repo-gate.js";
-/**
- * What is suspicious about this invocation without being wrong.
- *
- * Adopting a service that has no `services/<id>/` yet is the NORMAL case — it
- * is the whole point of the command — so neither of these can be a refusal.
- * But both used to be silent, and both produce the same outcome: a complete,
- * validating baseline written under a directory name nobody meant. `adopt
- * --service biling-service` briefed a phantom service beside the real
- * `billing-service`, and an agent following the brief created it.
- */
-async function invocationWarnings(docsDir, service, bound) {
-    const warnings = [];
-    if (bound !== undefined && bound !== service) {
-        warnings.push(`This repository's loam.json declares service '${bound}', but you asked to adopt '${service}'. ` +
-            `That is legal — one repo can author another service's baseline — but \`loam vouch\`, ` +
-            `\`loam gherkin\` and \`loam verify --service\` all bind to '${bound}' here, so the baseline ` +
-            `you write cannot be vouched from this repo. If '${service}' is a typo, fix it; otherwise run ` +
-            `adopt from '${service}''s own repository.`);
-    }
-    if (existsSync(servicePaths(docsDir, service).dir))
-        return warnings;
-    // A near-miss is only computable when the docs repo can be enumerated at all;
-    // a repo that refuses enumeration is a different problem, reported by every
-    // other command, and adopt has nothing useful to add to it.
-    let known = [];
-    try {
-        known = (await listServices(docsDir)).map((s) => s.id);
-    }
-    catch (err) {
-        if (!(err instanceof DocsRepoUnavailableError))
-            throw err;
-        return warnings;
-    }
-    const close = closeIds(service, known);
-    if (close.length > 0) {
-        warnings.push(`There is no services/${service}/ yet, but the docs repo already has ${close.join(", ")}. ` +
-            `If '${service}' is a misspelling of one of those, stop now: an agent following this brief ` +
-            `writes a complete, validating baseline for a service that does not exist, and nothing ` +
-            `downstream can tell it from a real one. If it really is a new service, this is expected.`);
-    }
-    return warnings;
-}
-export function registerAdopt(program) {
-    program
-        .command("adopt")
-        .description("Brief an agent to write one service's baseline docs from its code, and say what will be checked")
-        .option("--service <id>", "service to adopt (defaults to the configured service)")
-        .option("--json", "emit the machine contract instead of the human view")
-        .action(async (opts) => {
-        const json = opts.json === true;
-        const config = await loadConfig();
-        if (!config) {
-            reportNoConfig(json);
-            return;
-        }
-        // This command writes nothing, but it briefs an agent to write a whole
-        // baseline — so a docsDir that does not exist is not a harmless read: it
-        // hands over eight target paths under a directory nobody has, at exit 0,
-        // with the near-miss warning below silently switched off (listServices
-        // throws, `invocationWarnings` swallows it and returns nothing). The same
-        // refusal every enumerating command owes; see docs-repo-gate.ts.
-        //
-        // `docs`, not `services`: a docs repo that has no services/ yet is exactly
-        // the repo adopt exists to fill, and refusing there would refuse the
-        // command's own first use.
-        if (!docsRepoReady(json, config.docsDir, "docs"))
-            return;
-        const service = opts.service ?? config.service;
-        if (service === undefined) {
-            fail(json, "invalid-option", NO_SERVICE_MESSAGE);
-            return;
-        }
-        // The id becomes `services/<id>/` in a shared repo, so it goes through the
-        // one grammar before anything interpolates it into a path.
-        try {
-            assertServiceId(service, opts.service === undefined ? "service (loam.json)" : "--service");
-        }
-        catch (err) {
-            if (!(err instanceof InvalidIdError))
-                throw err;
-            fail(json, "invalid-option", err.message);
-            return;
-        }
-        const warnings = await invocationWarnings(config.docsDir, service, config.service);
-        const brief = await serviceBrief(config.docsDir, service);
-        if (json) {
-            emitJson({ ...brief, warnings });
-            return;
-        }
-        render(brief, warnings);
-    });
-}
-/* ------------------------------------------------------------------ */
-/* Text                                                                */
-/* ------------------------------------------------------------------ */
-function render(b, warnings) {
-    console.log(`adopt ${b.service} — write the baseline into ${b.path}/\n`);
-    // In the header, before the work: a warning printed after eight artifact
-    // shapes is a warning read after the agent has started writing.
-    for (const w of warnings) {
-        console.log(wrap(`! ${w}`, "  "));
-        console.log("");
-    }
-    console.log(wrap(b.rule, "  "));
-    console.log("\n  artifacts\n");
-    const width = Math.max(...b.targets.map((t) => t.artifact.length));
-    for (const t of b.targets) {
-        // `edit` is the shared fleet map: the file exists, but "present" would read
-        // as "nothing to do here", which is the opposite of why it is on the list.
-        const flag = t.action === "edit" ? "UNDRAWN" : t.exists ? "present" : t.required ? "MISSING" : "missing";
-        console.log(`    ${t.artifact.padEnd(width)}  ${t.action.padEnd(6)}  ${flag.padEnd(7)}  ${t.purpose}`);
-    }
-    for (const t of b.targets)
-        printShape(t);
-    printLandscape(b);
-    console.log("\n  frontmatter — on every markdown artifact\n");
-    for (const [field, what] of Object.entries(b.frontmatter.fields)) {
-        console.log(`    ${field}`);
-        console.log(wrap(what, "      "));
-    }
-    console.log(`\n    never write by hand: ${b.frontmatter.never.join(", ")}`);
-    console.log(`\n${wrap(b.frontmatter.why, "    ")}`);
-    // Attribution matters here: the fleet cross-check runs under `--all`, and a
-    // header promising it to `--service` sent agents chasing a finding that
-    // invocation never reports.
-    console.log(`\n  what \`loam validate --service ${b.service}\` then checks\n`);
-    for (const c of b.checks) {
-        if (c.via !== VIA_ALL)
-            printCheck(c);
-    }
-    console.log(`\n  and what only \`loam validate --all\` surfaces\n`);
-    for (const c of b.checks) {
-        if (c.via === VIA_ALL)
-            printCheck(c);
-    }
-    console.log("\n  what nothing checks\n");
-    for (const u of b.unchecked)
-        console.log(bullet(u, "    "));
-    console.log("\n  when you are done\n");
-    console.log(`    loam validate --service ${b.service} --json    # fix every error`);
-    // The fleet run is not a nicety: --service never reports the landscape
-    // cross-check, so a baseline can pass the line above with the fleet map
-    // never edited at all.
-    console.log(`    loam validate --all --json                        # in the docs repo: the fleet map`);
-    console.log(`    loam vouch --service ${b.service}              # a HUMAN, in the service's own repo`);
-    console.log("");
-    console.log(wrap("Leave everything `status: draft`. Vouching is somebody reading the code and saying the document matches it — it is not yours to do, and a status with no digest behind it is a claim with nothing behind it.", "    "));
-}
-function printCheck(c) {
-    console.log(`    ${SEVERITY_MARK[c.severity]} ${c.code}`);
-    console.log(wrap(c.what, "        "));
-}
-const ACTION_NOTE = {
-    create: "",
-    diff: "   (exists — diff, do not replace)",
-    edit: "   (the whole fleet's file — ADD to it, never rewrite it)",
-};
-function printShape(t) {
-    console.log(`\n  ${t.path}${ACTION_NOTE[t.action]}\n`);
-    for (const rule of t.shape)
-        console.log(bullet(rule, "    "));
-    if (t.example === undefined)
-        return;
-    console.log("");
-    for (const line of t.example.trimEnd().split("\n"))
-        console.log(`      ${line}`.trimEnd());
-}
-function printLandscape(b) {
-    const l = b.landscape;
-    console.log("\n  what the fleet already says about this service\n");
-    // The instruction is the same sentence the JSON carries, printed from the
-    // same field — the text view and `--json` cannot drift into briefing two
-    // different writes.
-    if (!l.present) {
-        console.log("    architecture/landscape.likec4 does not exist yet — nothing to bind to.");
-        console.log("");
-        console.log(wrap(l.instruction ?? "", "    "));
-        return;
-    }
-    if (!l.parses) {
-        console.log("    architecture/landscape.likec4 does not parse — bind by hand, and fix it first.");
-        console.log("");
-        console.log(wrap(l.instruction ?? "", "    "));
-        return;
-    }
-    if (l.elements.length === 0) {
-        console.log(`    Nothing in the landscape models '${b.service}'.`);
-        console.log("");
-        console.log(wrap(l.instruction ?? "", "    "));
-        return;
-    }
-    for (const e of l.elements) {
-        const bound = e.bound ? "bound" : "matched by title — bind it";
-        console.log(`    ${e.id} = ${e.kind} '${e.title}'   (${bound})`);
-    }
-    for (const e of l.inbound)
-        console.log(`    ← ${e.from}  ${e.op ?? `"${e.title ?? ""}"`}`);
-    for (const e of l.outbound)
-        console.log(`    → ${e.to}  ${e.op ?? `"${e.title ?? ""}"`}`);
-    if (l.expects.length > 0) {
-        console.log("");
-        console.log(wrap(`openapi.yaml must define ${l.expects.map((o) => `'${o}'`).join(", ")} — the fleet already calls ${l.expects.length === 1 ? "it" : "them"}, and a contract that omits ${l.expects.length === 1 ? "it" : "them"} fails spine.op-undefined the moment it lands.`, "    "));
-    }
-}
-/**
- * Wrap prose so the brief is readable in a terminal. Continuation lines are
- * indented past the marker, so a wrapped bullet cannot be misread as two.
- */
-function wrap(text, indent, width = 88) {
-    const hang = /^\s*-\s/.test(text) ? `${indent}  ` : indent;
-    const out = [];
-    let line = indent;
-    let pad = indent;
-    for (const word of text.trim().split(/\s+/)) {
-        if (line.length > pad.length && line.length + 1 + word.length > width) {
-            out.push(line);
-            pad = hang;
-            line = hang + word;
-        }
-        else {
-            line = line.length > pad.length ? `${line} ${word}` : line + word;
-        }
-    }
-    out.push(line);
-    return out.join("\n");
-}
-/** A bullet, wrapped with its continuation lines hanging under the text. */
-function bullet(text, indent) {
-    return wrap(`- ${text}`, indent);
-}
-//# sourceMappingURL=adopt.js.map

package/dist/commands/adopt.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"adopt.js","sourceRoot":"","sources":["../../src/commands/adopt.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * `loam adopt` — the bootstrap flow, as a contract with an agent.\n *\n * It emits a BRIEF, not an extraction: the artifacts one service's baseline is\n * made of, the grammar each has to be written in, what the fleet already says\n * about the service, the checks that follow, and the checks that do not exist.\n * The agent reads the code; loam states the work and then judges the result.\n *\n * It writes nothing. A command that produced the documents it is asking for\n * would be doing the half of the job it exists to hand over.\n */\nimport type { Command } from \"commander\";\nimport { existsSync } from \"node:fs\";\nimport { closeIds } from \"../core/arch.js\";\nimport { loadConfig } from \"../core/config.js\";\nimport { InvalidIdError, assertServiceId } from \"../core/ids.js\";\nimport { emitJson, fail, NO_SERVICE_MESSAGE, reportNoConfig } from \"../core/json.js\";\nimport { DocsRepoUnavailableError, listServices, servicePaths } from \"../core/repo.js\";\nimport { SEVERITY_MARK } from \"../core/report.js\";\nimport { serviceBrief, VIA_ALL, type Brief, type BriefCheck, type BriefTarget } from \"../core/brief.js\";\nimport { docsRepoReady } from \"./docs-repo-gate.js\";\n\ninterface AdoptOptions {\n  service?: string;\n  json?: boolean;\n}\n\n/**\n * What is suspicious about this invocation without being wrong.\n *\n * Adopting a service that has no `services/<id>/` yet is the NORMAL case — it\n * is the whole point of the command — so neither of these can be a refusal.\n * But both used to be silent, and both produce the same outcome: a complete,\n * validating baseline written under a directory name nobody meant. `adopt\n * --service biling-service` briefed a phantom service beside the real\n * `billing-service`, and an agent following the brief created it.\n */\nasync function invocationWarnings(\n  docsDir: string,\n  service: string,\n  bound: string | undefined,\n): Promise<string[]> {\n  const warnings: string[] = [];\n\n  if (bound !== undefined && bound !== service) {\n    warnings.push(\n      `This repository's loam.json declares service '${bound}', but you asked to adopt '${service}'. ` +\n        `That is legal — one repo can author another service's baseline — but \\`loam vouch\\`, ` +\n        `\\`loam gherkin\\` and \\`loam verify --service\\` all bind to '${bound}' here, so the baseline ` +\n        `you write cannot be vouched from this repo. If '${service}' is a typo, fix it; otherwise run ` +\n        `adopt from '${service}''s own repository.`,\n    );\n  }\n\n  if (existsSync(servicePaths(docsDir, service).dir)) return warnings;\n\n  // A near-miss is only computable when the docs repo can be enumerated at all;\n  // a repo that refuses enumeration is a different problem, reported by every\n  // other command, and adopt has nothing useful to add to it.\n  let known: string[] = [];\n  try {\n    known = (await listServices(docsDir)).map((s) => s.id);\n  } catch (err) {\n    if (!(err instanceof DocsRepoUnavailableError)) throw err;\n    return warnings;\n  }\n  const close = closeIds(service, known);\n  if (close.length > 0) {\n    warnings.push(\n      `There is no services/${service}/ yet, but the docs repo already has ${close.join(\", \")}. ` +\n        `If '${service}' is a misspelling of one of those, stop now: an agent following this brief ` +\n        `writes a complete, validating baseline for a service that does not exist, and nothing ` +\n        `downstream can tell it from a real one. If it really is a new service, this is expected.`,\n    );\n  }\n  return warnings;\n}\n\nexport function registerAdopt(program: Command): void {\n  program\n    .command(\"adopt\")\n    .description(\"Brief an agent to write one service's baseline docs from its code, and say what will be checked\")\n    .option(\"--service <id>\", \"service to adopt (defaults to the configured service)\")\n    .option(\"--json\", \"emit the machine contract instead of the human view\")\n    .action(async (opts: AdoptOptions) => {\n      const json = opts.json === true;\n\n      const config = await loadConfig();\n      if (!config) {\n        reportNoConfig(json);\n        return;\n      }\n      // This command writes nothing, but it briefs an agent to write a whole\n      // baseline — so a docsDir that does not exist is not a harmless read: it\n      // hands over eight target paths under a directory nobody has, at exit 0,\n      // with the near-miss warning below silently switched off (listServices\n      // throws, `invocationWarnings` swallows it and returns nothing). The same\n      // refusal every enumerating command owes; see docs-repo-gate.ts.\n      //\n      // `docs`, not `services`: a docs repo that has no services/ yet is exactly\n      // the repo adopt exists to fill, and refusing there would refuse the\n      // command's own first use.\n      if (!docsRepoReady(json, config.docsDir, \"docs\")) return;\n\n      const service = opts.service ?? config.service;\n      if (service === undefined) {\n        fail(json, \"invalid-option\", NO_SERVICE_MESSAGE);\n        return;\n      }\n      // The id becomes `services/<id>/` in a shared repo, so it goes through the\n      // one grammar before anything interpolates it into a path.\n      try {\n        assertServiceId(service, opts.service === undefined ? \"service (loam.json)\" : \"--service\");\n      } catch (err) {\n        if (!(err instanceof InvalidIdError)) throw err;\n        fail(json, \"invalid-option\", err.message);\n        return;\n      }\n\n      const warnings = await invocationWarnings(config.docsDir, service, config.service);\n      const brief = await serviceBrief(config.docsDir, service);\n      if (json) {\n        emitJson({ ...brief, warnings });\n        return;\n      }\n      render(brief, warnings);\n    });\n}\n\n/* ------------------------------------------------------------------ */\n/* Text                                                                */\n/* ------------------------------------------------------------------ */\n\nfunction render(b: Brief, warnings: string[]): void {\n  console.log(`adopt ${b.service} — write the baseline into ${b.path}/\\n`);\n  // In the header, before the work: a warning printed after eight artifact\n  // shapes is a warning read after the agent has started writing.\n  for (const w of warnings) {\n    console.log(wrap(`! ${w}`, \"  \"));\n    console.log(\"\");\n  }\n  console.log(wrap(b.rule, \"  \"));\n\n  console.log(\"\\n  artifacts\\n\");\n  const width = Math.max(...b.targets.map((t) => t.artifact.length));\n  for (const t of b.targets) {\n    // `edit` is the shared fleet map: the file exists, but \"present\" would read\n    // as \"nothing to do here\", which is the opposite of why it is on the list.\n    const flag = t.action === \"edit\" ? \"UNDRAWN\" : t.exists ? \"present\" : t.required ? \"MISSING\" : \"missing\";\n    console.log(`    ${t.artifact.padEnd(width)}  ${t.action.padEnd(6)}  ${flag.padEnd(7)}  ${t.purpose}`);\n  }\n\n  for (const t of b.targets) printShape(t);\n\n  printLandscape(b);\n\n  console.log(\"\\n  frontmatter — on every markdown artifact\\n\");\n  for (const [field, what] of Object.entries(b.frontmatter.fields)) {\n    console.log(`    ${field}`);\n    console.log(wrap(what, \"      \"));\n  }\n  console.log(`\\n    never write by hand: ${b.frontmatter.never.join(\", \")}`);\n  console.log(`\\n${wrap(b.frontmatter.why, \"    \")}`);\n\n  // Attribution matters here: the fleet cross-check runs under `--all`, and a\n  // header promising it to `--service` sent agents chasing a finding that\n  // invocation never reports.\n  console.log(`\\n  what \\`loam validate --service ${b.service}\\` then checks\\n`);\n  for (const c of b.checks) {\n    if (c.via !== VIA_ALL) printCheck(c);\n  }\n  console.log(`\\n  and what only \\`loam validate --all\\` surfaces\\n`);\n  for (const c of b.checks) {\n    if (c.via === VIA_ALL) printCheck(c);\n  }\n\n  console.log(\"\\n  what nothing checks\\n\");\n  for (const u of b.unchecked) console.log(bullet(u, \"    \"));\n\n  console.log(\"\\n  when you are done\\n\");\n  console.log(`    loam validate --service ${b.service} --json    # fix every error`);\n  // The fleet run is not a nicety: --service never reports the landscape\n  // cross-check, so a baseline can pass the line above with the fleet map\n  // never edited at all.\n  console.log(`    loam validate --all --json                        # in the docs repo: the fleet map`);\n  console.log(`    loam vouch --service ${b.service}              # a HUMAN, in the service's own repo`);\n  console.log(\"\");\n  console.log(\n    wrap(\n      \"Leave everything `status: draft`. Vouching is somebody reading the code and saying the document matches it — it is not yours to do, and a status with no digest behind it is a claim with nothing behind it.\",\n      \"    \",\n    ),\n  );\n}\n\nfunction printCheck(c: BriefCheck): void {\n  console.log(`    ${SEVERITY_MARK[c.severity]} ${c.code}`);\n  console.log(wrap(c.what, \"        \"));\n}\n\nconst ACTION_NOTE: Record<BriefTarget[\"action\"], string> = {\n  create: \"\",\n  diff: \"   (exists — diff, do not replace)\",\n  edit: \"   (the whole fleet's file — ADD to it, never rewrite it)\",\n};\n\nfunction printShape(t: BriefTarget): void {\n  console.log(`\\n  ${t.path}${ACTION_NOTE[t.action]}\\n`);\n  for (const rule of t.shape) console.log(bullet(rule, \"    \"));\n  if (t.example === undefined) return;\n  console.log(\"\");\n  for (const line of t.example.trimEnd().split(\"\\n\")) console.log(`      ${line}`.trimEnd());\n}\n\nfunction printLandscape(b: Brief): void {\n  const l = b.landscape;\n  console.log(\"\\n  what the fleet already says about this service\\n\");\n  // The instruction is the same sentence the JSON carries, printed from the\n  // same field — the text view and `--json` cannot drift into briefing two\n  // different writes.\n  if (!l.present) {\n    console.log(\"    architecture/landscape.likec4 does not exist yet — nothing to bind to.\");\n    console.log(\"\");\n    console.log(wrap(l.instruction ?? \"\", \"    \"));\n    return;\n  }\n  if (!l.parses) {\n    console.log(\"    architecture/landscape.likec4 does not parse — bind by hand, and fix it first.\");\n    console.log(\"\");\n    console.log(wrap(l.instruction ?? \"\", \"    \"));\n    return;\n  }\n  if (l.elements.length === 0) {\n    console.log(`    Nothing in the landscape models '${b.service}'.`);\n    console.log(\"\");\n    console.log(wrap(l.instruction ?? \"\", \"    \"));\n    return;\n  }\n  for (const e of l.elements) {\n    const bound = e.bound ? \"bound\" : \"matched by title — bind it\";\n    console.log(`    ${e.id} = ${e.kind} '${e.title}'   (${bound})`);\n  }\n  for (const e of l.inbound) console.log(`    ← ${e.from}  ${e.op ?? `\"${e.title ?? \"\"}\"`}`);\n  for (const e of l.outbound) console.log(`    → ${e.to}  ${e.op ?? `\"${e.title ?? \"\"}\"`}`);\n  if (l.expects.length > 0) {\n    console.log(\"\");\n    console.log(\n      wrap(\n        `openapi.yaml must define ${l.expects.map((o) => `'${o}'`).join(\", \")} — the fleet already calls ${l.expects.length === 1 ? \"it\" : \"them\"}, and a contract that omits ${l.expects.length === 1 ? \"it\" : \"them\"} fails spine.op-undefined the moment it lands.`,\n        \"    \",\n      ),\n    );\n  }\n}\n\n/**\n * Wrap prose so the brief is readable in a terminal. Continuation lines are\n * indented past the marker, so a wrapped bullet cannot be misread as two.\n */\nfunction wrap(text: string, indent: string, width = 88): string {\n  const hang = /^\\s*-\\s/.test(text) ? `${indent}  ` : indent;\n  const out: string[] = [];\n  let line = indent;\n  let pad = indent;\n  for (const word of text.trim().split(/\\s+/)) {\n    if (line.length > pad.length && line.length + 1 + word.length > width) {\n      out.push(line);\n      pad = hang;\n      line = hang + word;\n    } else {\n      line = line.length > pad.length ? `${line} ${word}` : line + word;\n    }\n  }\n  out.push(line);\n  return out.join(\"\\n\");\n}\n\n/** A bullet, wrapped with its continuation lines hanging under the text. */\nfunction bullet(text: string, indent: string): string {\n  return wrap(`- ${text}`, indent);\n}\n"]}