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

package/dist/core/brief/brief.js

@@ -0,0 +1,225 @@
+/**
+ * The adoption brief: what an agent needs in order to write one service's
+ * baseline documentation, and what will be checked when it does.
+ *
+ * `adopt` was specified for years as "read the code, emit the C4". It is not
+ * being built, because it cannot be: nothing deterministic reads a legacy
+ * service and says what its architecture MEANS, and a guessed model is worse
+ * than no model — everyone downstream has to re-derive it to know whether to
+ * believe it.
+ *
+ * So loam takes the half of the job that IS deterministic. It states the work
+ * precisely (which files, in which grammar, bound to which existing elements),
+ * it says exactly which checks the result will face, and then it says which
+ * checks do not exist — because everything in that last list is honesty no
+ * validator will ever supply, and an agent that does not know where the checking
+ * stops will assume it never does.
+ *
+ * Nothing here reads code. `sources` in the frontmatter is the only line that
+ * ties the result to a repository, which is why the brief argues for it instead
+ * of merely listing it.
+ */
+import { existsSync, statSync } from "node:fs";
+import { readdir } from "node:fs/promises";
+import { join, relative } from "node:path";
+import { landscapePath } from "../repo/paths.js";
+import { locateServicePaths } from "../repo/service-target.js";
+import { VALIDATE_CHECKS } from "./checks.js";
+import { UNCHECKED } from "./unchecked.js";
+import { landscapeArtifact, landscapeContext } from "./landscape.js";
+import { ARTIFACTS } from "./targets.js";
+/**
+ * The architecture walk: the order a service is read in, and what each stop is
+ * for.
+ *
+ * The brief said "read the code: entry points, HTTP routes and handlers,
+ * published events, config, deploy manifests, tests" — one sentence, six nouns,
+ * no order and no landing site. What came back matched the sentence: the HTTP
+ * surface documented well, because it is the noun an agent recognises fastest,
+ * and the scheduler, the consumer group and the outbox missing entirely. Not
+ * because they were judged unimportant — because nothing said to go and look,
+ * and every check loam owns is computed from what was written rather than from
+ * what is there. `UNCHECKED` has said COMPLETENESS is unverifiable since the
+ * beginning; that is an argument for stating the sweep, not for leaving it
+ * implied.
+ *
+ * The order is deliberate and it is not the order a reader browses in. Stops 1
+ * and 2 fix the SHAPE of the service — which processes exist at all — before
+ * any surface is enumerated, because an agent that starts at the HTTP routes
+ * has already concluded the service is an API by the time it meets the
+ * scheduler. Everything after them is one surface each.
+ *
+ * `lands` names artifacts rather than describing them, because the two lists
+ * are joined: test/agent-contract.test.ts requires every name here to be a
+ * target the same brief hands over, so a stop can never feed a file nobody was
+ * asked to write.
+ */
+export const WALK = [
+    {
+        where: "the build and dependency manifests — pom.xml, build.gradle, package.json, go.mod, requirements.txt, and whatever the repo's own README calls the build",
+        find: "what this service is built from, and every client library it links against. A broker client, an HTTP client, a database driver: each one is a dependency that has to appear as an edge or a container later, and this list is the only place they are all named at once. A library whose SEMANTICS decide behaviour — a retry budget, a delivery guarantee, a serialization format — is an arch requirement (arch.spec.md), not a fact to leave in your head.",
+        lands: ["model.likec4", "runbook.md", "arch.spec.md"],
+    },
+    {
+        where: "the entry points — main/Application/server bootstrap, the DI or module wiring, and anything the deploy manifests actually start",
+        find: "how many PROCESSES this service is, and what each one is. An API, a worker, a scheduler, a consumer — a service that is three of those and documented as one is the most common way a baseline is wrong, and it is wrong in a shape no later check can see.",
+        lands: ["model.likec4"],
+    },
+    {
+        where: "the HTTP surface — every route, controller, handler and middleware, counted",
+        find: "the operation set, in full, and inside each operation the DECISIONS its code makes: the permission and role checks — each one is a `Requires:` entry, and a name `architecture/permissions.yaml` does not declare yet is a line to ADD to that shared file, never to invent locally — the fields required only when another field is present, the defaults and normalisations applied before anything is stored, the transitions a request is refused for. Count both — operations, and branches per operation — before you write, and say both counts in the hand-back. `api.ungoverned` can tell you an operation you WROTE has no requirement; nothing at all can tell you about the twelve you never wrote down, or about the thirty branches inside the one you did. A guard is not implementation detail: what a service REFUSES is behaviour its caller observes and a test pins, and it is the half of a legacy service that lives only in the code and in one developer's head.",
+        lands: ["openapi.yaml", "spec.md"],
+    },
+    {
+        where: "the message surface — producers, consumers, listener annotations, topic and queue names, the outbox table and its relay",
+        find: "every message this service puts on and takes off the bus, with its direction, and — on the consuming side — the DECISIONS the handler makes about a message before it acts on one. The direction is the half that gets lost: a consumer documented as a producer is a contract the whole fleet then joins against backwards. The guards are the half nobody looks for at all: which messages are filtered out and on what field, what happens to one whose entity has since been deleted, what is idempotency-keyed against a replay, what is dead-lettered rather than retried. Each of those is a scenario, and none of them appears anywhere in the contract — asyncapi.yaml describes the message, never what this service refuses to do with it.",
+        lands: ["asyncapi.yaml", "landscape.likec4"],
+    },
+    {
+        where: "the scheduled and background work — cron entries, timers, retry loops, reconcilers, migrations that run at boot",
+        find: "behaviour no request ever triggers, and the conditions under which it does or does not run. It has requirements like anything else, and it is invisible to every surface above — which is why a baseline written from routes alone describes a service that does half of what it does. Take the decisions with it: which rows a reconciler SELECTS and which it skips, what a retry loop gives up on and after how long, what a migration does when it finds the state it is meant to fix already fixed. A scheduled job documented as 'runs nightly' is a requirement with no behaviour in it.",
+        lands: ["spec.md", "arch.spec.md"],
+    },
+    {
+        where: "the state — datastores, caches, buckets, and the schema or migration directory that says what is in them",
+        find: "what this service OWNS versus what it borrows. Ownership is the fact the C4 is for, and it is the one nobody can reconstruct later from the code without re-reading all of it.",
+        lands: ["model.likec4"],
+    },
+    {
+        where: "the outbound calls — HTTP clients, generated stubs, gRPC channels, and the config that says which host each one points at",
+        find: "who this service calls, and which operation each call names. These become the fleet map's edges; an edge missing here is a dependency the fleet cannot see, and `loam explore` will under-report the blast radius of every future change to the callee. An edge that only configuration attests is PROVISIONAL until the runtime stop: hold it until the deploy manifests confirm nothing switches that client off.",
+        lands: ["landscape.likec4"],
+    },
+    {
+        where: "the runtime — config and env vars, deploy manifests, pipelines, alert rules, dashboards",
+        find: "how it is run and what pages whom. Alerts are the honest source for health.yaml: an SLO nobody agreed to is invention, but an alert that already fires is a fact somebody wrote down. Deployment manifests OVERRIDE configuration files, and they usually live in another repository — go and find them before any dependency that only configuration attests goes in the model, and check for an environment variable that disables the feature. A capability switched off at deploy time is not a dependency, however completely the config wires it: delete its edge and container, and record it in runbook.md's 'configured but not a dependency, and why' list. A manifest read from another repository is named in the runbook's prose — never in `sources`, which may only hold paths of this service's own repository. An EFFECTIVE configuration value behaviour depends on — the timeout the chart sets, the flag that switches a code path — is an arch requirement in arch.spec.md, with a Covers: line naming what it decides; loam holds its coverage even though it can never check the value.",
+        lands: ["runbook.md", "health.yaml", "arch.spec.md"],
+    },
+    {
+        where: "the tests, integration and component ones first",
+        find: "the behaviours somebody already thought worth pinning. This is the PRIMARY source for scenarios, not the last sweep: a behaviour a test already pins is written FROM that test, and the code is read only for what no test covers. A test suite is the only part of a legacy service that states intent rather than mechanism, and a scenario derived from one is the only kind that starts out true. Carry the shape across as well as the content — a parameterised test (`@ParameterizedTest`, `@parametrize`, `test.each`) is one scenario with a table, not one scenario per case. Then say in the hand-back how well this service is covered and how many of its tests became scenarios: that number is the ceiling on what this whole baseline can be worth, and nothing downstream can compute it.",
+        lands: ["spec.md", "arch.spec.md"],
+    },
+];
+/**
+ * The stop that closes the walk. Separate from `WALK` because it is not a place
+ * to go — it is the question asked once the walking is done, and the only
+ * defence against a sweep that felt thorough because the parts it covered were
+ * covered well.
+ */
+export const WALK_CLOSE = "Then list the directories you did NOT open, and say why for each. `loam validate --service <id>`, run inside the service's own repo, reports the same list back as `sources.unwalked` — it compares your `sources` against the files git tracks. A directory you deliberately skipped is a sentence in the hand-back; a directory you skipped without noticing is the gap this walk exists to find.";
+const FRONTMATTER_BRIEF = {
+    fields: {
+        service: "the directory this file lives under, exactly. A mismatch is an error (`frontmatter.field-mismatch`).",
+        status: "`draft`, always. `verified` is a human's word, stamped by `loam vouch --service <id>` run inside the service's own repo — never written by hand.",
+        owner: "the team or person who answers for this service.",
+        sources: "the paths in THIS SERVICE'S repository you actually read to write the document — files and directories only, a directory covering everything beneath it; glob patterns are refused. Not the paths a reader would expect to have been read. This is NOT a reading list for a human: nobody follows these, and nothing about the document asks them to.",
+    },
+    // `vouch_scope` is in this list for a sharper reason than its siblings: the
+    // others are stamps an agent could only forge, while this one is a stamp an
+    // agent could DELETE — and deleting it turns a vouch that read four sections
+    // into one that read the document, on every surface at once.
+    never: ["last_verified", "sources_digest", "content_digest", "sources_files", "vouch_scope"],
+    why: "`sources` is digest input, not a citation. It is the only mechanical tie between this document and the code — everything else loam checks is internal consistency, and a corpus can agree with itself perfectly while describing nothing that exists. `loam validate`, run inside the service's repo, checks every listed path is still there; `loam vouch` hashes their CONTENT so that a later `validate` can say the code has moved since anyone read it. That hash is the entire point, and it is why padding the list costs something real rather than merely being untidy: a path nobody read still gets hashed, so its next change reports as drift in a document it never described, and a path that WAS read and went unlisted moves under the document in silence. Neither failure is visible to a reader; both are decided by whether this list is honest.",
+};
+const NEVER_OVERWRITE = "Do not overwrite an artifact that already exists. Read it, diff your findings against it, and report what disagrees — a document somebody wrote is evidence, and replacing it destroys the only copy of what they knew.";
+/**
+ * Assemble the brief for one service. Reads the docs repo; writes nothing.
+ * `at` overrides where the artifacts are briefed to land — `adopt
+ * --subsystem`'s target inside a group — and is only ever passed for a
+ * service the enumeration does NOT answer: an existing service is briefed
+ * where it already lives, because the brief's one rule is to never overwrite,
+ * and a second address would brief a duplicate.
+ */
+export async function serviceBrief(docsDir, service, at) {
+    const paths = at ?? (await locateServicePaths(docsDir, service));
+    const rel = (abs) => relative(docsDir, abs).split(/[\\/]/).join("/");
+    // Read before the artifact loop, not after it: what the fleet already says
+    // about this service decides whether it owes an API contract at all.
+    const landscape = await landscapeContext(docsDir, service);
+    const owesApi = apiExpected(landscape);
+    const targets = [];
+    for (const { key, ...artifact } of ARTIFACTS) {
+        // `adrs/` is a directory, and an empty one is not an existing artifact —
+        // reporting it as present would tell the agent to diff against nothing.
+        const dir = key === "adrsDir";
+        const exists = dir ? await hasMarkdown(paths[key]) : existsSync(paths[key]);
+        targets.push({
+            ...artifact,
+            ...(key === "openapi" ? { required: owesApi } : {}),
+            path: dir ? `${rel(paths[key])}/` : rel(paths[key]),
+            exists,
+            action: exists ? "diff" : "create",
+        });
+    }
+    // The eighth target is the fleet map, and it is conditional: a service the
+    // landscape ALREADY resolves an element to owes it nothing, and briefing an
+    // edit there would invite an agent to draw a second box for a service that
+    // has one. Everything else about the target is unconditional — the file is
+    // shared, so `action` is `edit` whenever it exists and `create` only for the
+    // very first service of a brand-new docs repo.
+    if (landscape.modelled !== true) {
+        targets.push({
+            ...landscapeArtifact(service, landscape.expects, landscape.present, rel(paths.dir)),
+            path: rel(landscapePath(docsDir)),
+            exists: landscape.present,
+            action: landscape.present ? "edit" : "create",
+        });
+    }
+    return {
+        service,
+        docsDir,
+        path: rel(paths.dir),
+        targets,
+        walk: WALK,
+        walkClose: WALK_CLOSE,
+        landscape,
+        frontmatter: FRONTMATTER_BRIEF,
+        checks: VALIDATE_CHECKS,
+        unchecked: UNCHECKED,
+        rule: NEVER_OVERWRITE,
+    };
+}
+async function hasMarkdown(dir) {
+    if (!existsSync(dir))
+        return false;
+    const entries = await readdir(dir, { withFileTypes: true });
+    // `statSync` for the symlink case: a Dirent never follows one, so `isFile()`
+    // is false for a symlinked ADR and the directory reads as empty (repo.ts's
+    // `entryIs` is the same rule for `services/` and `features/`).
+    return entries.some((e) => {
+        if (!e.name.endsWith(".md"))
+            return false;
+        if (e.isFile())
+            return true;
+        if (!e.isSymbolicLink())
+            return false;
+        try {
+            return statSync(join(dir, e.name)).isFile();
+        }
+        catch {
+            return false;
+        }
+    });
+}
+/**
+ * Does the fleet expect an API of this service?
+ *
+ * The brief marked `openapi.yaml` required unconditionally, and printed the
+ * absence as `MISSING` in capitals — while `loam validate` and `loam list`
+ * derive the opposite from the same landscape (`service.no-openapi` stays quiet
+ * when nothing calls the service, and `list`'s maturity ladder stops demanding
+ * a contract). For a UI, a worker or a cron the brief was therefore telling an
+ * agent to INVENT an API contract into the source of truth — the one class of
+ * guess this whole module exists to refuse, and the one the brief itself names
+ * in `openapi.yaml`'s shape rules (`ARTIFACTS`, targets.ts).
+ *
+ * Positive evidence only, exactly as `list` reads it: a landscape that is
+ * absent or does not parse proves nothing about who calls this service, so the
+ * contract is still owed. `expects` is the ops on inbound edges, which is
+ * `list`'s `called` set seen from one service.
+ */
+function apiExpected(landscape) {
+    return !landscape.parses || landscape.expects.length > 0;
+}
+//# sourceMappingURL=brief.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"brief.js","sourceRoot":"","sources":["../../../src/core/brief/brief.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * The adoption brief: what an agent needs in order to write one service's\n * baseline documentation, and what will be checked when it does.\n *\n * `adopt` was specified for years as \"read the code, emit the C4\". It is not\n * being built, because it cannot be: nothing deterministic reads a legacy\n * service and says what its architecture MEANS, and a guessed model is worse\n * than no model — everyone downstream has to re-derive it to know whether to\n * believe it.\n *\n * So loam takes the half of the job that IS deterministic. It states the work\n * precisely (which files, in which grammar, bound to which existing elements),\n * it says exactly which checks the result will face, and then it says which\n * checks do not exist — because everything in that last list is honesty no\n * validator will ever supply, and an agent that does not know where the checking\n * stops will assume it never does.\n *\n * Nothing here reads code. `sources` in the frontmatter is the only line that\n * ties the result to a repository, which is why the brief argues for it instead\n * of merely listing it.\n */\nimport { existsSync, statSync } from \"node:fs\";\nimport { readdir } from \"node:fs/promises\";\nimport { join, relative } from \"node:path\";\nimport type { PathableService } from \"../kernel/ids/service.js\";\nimport { landscapePath, type ServicePaths } from \"../repo/paths.js\";\nimport { locateServicePaths } from \"../repo/service-target.js\";\nimport { VALIDATE_CHECKS, type BriefCheck } from \"./checks.js\";\nimport { UNCHECKED } from \"./unchecked.js\";\nimport { landscapeArtifact, landscapeContext, type LandscapeContext } from \"./landscape.js\";\nimport { ARTIFACTS, type BriefTarget } from \"./targets.js\";\nimport type { DocsDir } from \"../kernel/ids/dirs.js\";\n\n/* ------------------------------------------------------------------ */\n/* The walk — what to read, in what order, and where each finding lands */\n/* ------------------------------------------------------------------ */\n\nexport interface WalkStop {\n  /** What to open, named as a thing to go and find rather than a file name. */\n  where: string;\n  /** What to take out of it. */\n  find: string;\n  /** The artifacts this stop feeds, by `artifact` name from `targets[]`. */\n  lands: string[];\n}\n\n/**\n * The architecture walk: the order a service is read in, and what each stop is\n * for.\n *\n * The brief said \"read the code: entry points, HTTP routes and handlers,\n * published events, config, deploy manifests, tests\" — one sentence, six nouns,\n * no order and no landing site. What came back matched the sentence: the HTTP\n * surface documented well, because it is the noun an agent recognises fastest,\n * and the scheduler, the consumer group and the outbox missing entirely. Not\n * because they were judged unimportant — because nothing said to go and look,\n * and every check loam owns is computed from what was written rather than from\n * what is there. `UNCHECKED` has said COMPLETENESS is unverifiable since the\n * beginning; that is an argument for stating the sweep, not for leaving it\n * implied.\n *\n * The order is deliberate and it is not the order a reader browses in. Stops 1\n * and 2 fix the SHAPE of the service — which processes exist at all — before\n * any surface is enumerated, because an agent that starts at the HTTP routes\n * has already concluded the service is an API by the time it meets the\n * scheduler. Everything after them is one surface each.\n *\n * `lands` names artifacts rather than describing them, because the two lists\n * are joined: test/agent-contract.test.ts requires every name here to be a\n * target the same brief hands over, so a stop can never feed a file nobody was\n * asked to write.\n */\nexport const WALK: WalkStop[] = [\n  {\n    where: \"the build and dependency manifests — pom.xml, build.gradle, package.json, go.mod, requirements.txt, and whatever the repo's own README calls the build\",\n    find: \"what this service is built from, and every client library it links against. A broker client, an HTTP client, a database driver: each one is a dependency that has to appear as an edge or a container later, and this list is the only place they are all named at once. A library whose SEMANTICS decide behaviour — a retry budget, a delivery guarantee, a serialization format — is an arch requirement (arch.spec.md), not a fact to leave in your head.\",\n    lands: [\"model.likec4\", \"runbook.md\", \"arch.spec.md\"],\n  },\n  {\n    where: \"the entry points — main/Application/server bootstrap, the DI or module wiring, and anything the deploy manifests actually start\",\n    find: \"how many PROCESSES this service is, and what each one is. An API, a worker, a scheduler, a consumer — a service that is three of those and documented as one is the most common way a baseline is wrong, and it is wrong in a shape no later check can see.\",\n    lands: [\"model.likec4\"],\n  },\n  {\n    where: \"the HTTP surface — every route, controller, handler and middleware, counted\",\n    find: \"the operation set, in full, and inside each operation the DECISIONS its code makes: the permission and role checks — each one is a `Requires:` entry, and a name `architecture/permissions.yaml` does not declare yet is a line to ADD to that shared file, never to invent locally — the fields required only when another field is present, the defaults and normalisations applied before anything is stored, the transitions a request is refused for. Count both — operations, and branches per operation — before you write, and say both counts in the hand-back. `api.ungoverned` can tell you an operation you WROTE has no requirement; nothing at all can tell you about the twelve you never wrote down, or about the thirty branches inside the one you did. A guard is not implementation detail: what a service REFUSES is behaviour its caller observes and a test pins, and it is the half of a legacy service that lives only in the code and in one developer's head.\",\n    lands: [\"openapi.yaml\", \"spec.md\"],\n  },\n  {\n    where: \"the message surface — producers, consumers, listener annotations, topic and queue names, the outbox table and its relay\",\n    find: \"every message this service puts on and takes off the bus, with its direction, and — on the consuming side — the DECISIONS the handler makes about a message before it acts on one. The direction is the half that gets lost: a consumer documented as a producer is a contract the whole fleet then joins against backwards. The guards are the half nobody looks for at all: which messages are filtered out and on what field, what happens to one whose entity has since been deleted, what is idempotency-keyed against a replay, what is dead-lettered rather than retried. Each of those is a scenario, and none of them appears anywhere in the contract — asyncapi.yaml describes the message, never what this service refuses to do with it.\",\n    lands: [\"asyncapi.yaml\", \"landscape.likec4\"],\n  },\n  {\n    where: \"the scheduled and background work — cron entries, timers, retry loops, reconcilers, migrations that run at boot\",\n    find: \"behaviour no request ever triggers, and the conditions under which it does or does not run. It has requirements like anything else, and it is invisible to every surface above — which is why a baseline written from routes alone describes a service that does half of what it does. Take the decisions with it: which rows a reconciler SELECTS and which it skips, what a retry loop gives up on and after how long, what a migration does when it finds the state it is meant to fix already fixed. A scheduled job documented as 'runs nightly' is a requirement with no behaviour in it.\",\n    lands: [\"spec.md\", \"arch.spec.md\"],\n  },\n  {\n    where: \"the state — datastores, caches, buckets, and the schema or migration directory that says what is in them\",\n    find: \"what this service OWNS versus what it borrows. Ownership is the fact the C4 is for, and it is the one nobody can reconstruct later from the code without re-reading all of it.\",\n    lands: [\"model.likec4\"],\n  },\n  {\n    where: \"the outbound calls — HTTP clients, generated stubs, gRPC channels, and the config that says which host each one points at\",\n    find: \"who this service calls, and which operation each call names. These become the fleet map's edges; an edge missing here is a dependency the fleet cannot see, and `loam explore` will under-report the blast radius of every future change to the callee. An edge that only configuration attests is PROVISIONAL until the runtime stop: hold it until the deploy manifests confirm nothing switches that client off.\",\n    lands: [\"landscape.likec4\"],\n  },\n  {\n    where: \"the runtime — config and env vars, deploy manifests, pipelines, alert rules, dashboards\",\n    find: \"how it is run and what pages whom. Alerts are the honest source for health.yaml: an SLO nobody agreed to is invention, but an alert that already fires is a fact somebody wrote down. Deployment manifests OVERRIDE configuration files, and they usually live in another repository — go and find them before any dependency that only configuration attests goes in the model, and check for an environment variable that disables the feature. A capability switched off at deploy time is not a dependency, however completely the config wires it: delete its edge and container, and record it in runbook.md's 'configured but not a dependency, and why' list. A manifest read from another repository is named in the runbook's prose — never in `sources`, which may only hold paths of this service's own repository. An EFFECTIVE configuration value behaviour depends on — the timeout the chart sets, the flag that switches a code path — is an arch requirement in arch.spec.md, with a Covers: line naming what it decides; loam holds its coverage even though it can never check the value.\",\n    lands: [\"runbook.md\", \"health.yaml\", \"arch.spec.md\"],\n  },\n  {\n    where: \"the tests, integration and component ones first\",\n    find: \"the behaviours somebody already thought worth pinning. This is the PRIMARY source for scenarios, not the last sweep: a behaviour a test already pins is written FROM that test, and the code is read only for what no test covers. A test suite is the only part of a legacy service that states intent rather than mechanism, and a scenario derived from one is the only kind that starts out true. Carry the shape across as well as the content — a parameterised test (`@ParameterizedTest`, `@parametrize`, `test.each`) is one scenario with a table, not one scenario per case. Then say in the hand-back how well this service is covered and how many of its tests became scenarios: that number is the ceiling on what this whole baseline can be worth, and nothing downstream can compute it.\",\n    lands: [\"spec.md\", \"arch.spec.md\"],\n  },\n];\n\n/**\n * The stop that closes the walk. Separate from `WALK` because it is not a place\n * to go — it is the question asked once the walking is done, and the only\n * defence against a sweep that felt thorough because the parts it covered were\n * covered well.\n */\nexport const WALK_CLOSE =\n  \"Then list the directories you did NOT open, and say why for each. `loam validate --service <id>`, run inside the service's own repo, reports the same list back as `sources.unwalked` — it compares your `sources` against the files git tracks. A directory you deliberately skipped is a sentence in the hand-back; a directory you skipped without noticing is the gap this walk exists to find.\";\n\n/* ------------------------------------------------------------------ */\n/* The frontmatter                                                     */\n/* ------------------------------------------------------------------ */\n\nexport interface FrontmatterBrief {\n  /** Field -> what to write in it. */\n  fields: Record<string, string>;\n  /** Fields to leave alone entirely. */\n  never: string[];\n  /** Why `sources` carries the weight. */\n  why: string;\n}\n\nconst FRONTMATTER_BRIEF: FrontmatterBrief = {\n  fields: {\n    service: \"the directory this file lives under, exactly. A mismatch is an error (`frontmatter.field-mismatch`).\",\n    status:\n      \"`draft`, always. `verified` is a human's word, stamped by `loam vouch --service <id>` run inside the service's own repo — never written by hand.\",\n    owner: \"the team or person who answers for this service.\",\n    sources:\n      \"the paths in THIS SERVICE'S repository you actually read to write the document — files and directories only, a directory covering everything beneath it; glob patterns are refused. Not the paths a reader would expect to have been read. This is NOT a reading list for a human: nobody follows these, and nothing about the document asks them to.\",\n  },\n  // `vouch_scope` is in this list for a sharper reason than its siblings: the\n  // others are stamps an agent could only forge, while this one is a stamp an\n  // agent could DELETE — and deleting it turns a vouch that read four sections\n  // into one that read the document, on every surface at once.\n  never: [\"last_verified\", \"sources_digest\", \"content_digest\", \"sources_files\", \"vouch_scope\"],\n  why:\n    \"`sources` is digest input, not a citation. It is the only mechanical tie between this document and the code — everything else loam checks is internal consistency, and a corpus can agree with itself perfectly while describing nothing that exists. `loam validate`, run inside the service's repo, checks every listed path is still there; `loam vouch` hashes their CONTENT so that a later `validate` can say the code has moved since anyone read it. That hash is the entire point, and it is why padding the list costs something real rather than merely being untidy: a path nobody read still gets hashed, so its next change reports as drift in a document it never described, and a path that WAS read and went unlisted moves under the document in silence. Neither failure is visible to a reader; both are decided by whether this list is honest.\",\n};\n\nexport interface Brief {\n  service: string;\n  /** Absolute docs repo root — the anchor the repo-relative paths hang off. */\n  docsDir: DocsDir;\n  /** Repo-relative path of services/<id>/. */\n  path: string;\n  targets: BriefTarget[];\n  /** The order to read the service in, and what each stop feeds. */\n  walk: WalkStop[];\n  /** The question the walk ends on — see `WALK_CLOSE`. */\n  walkClose: string;\n  landscape: LandscapeContext;\n  frontmatter: FrontmatterBrief;\n  checks: BriefCheck[];\n  unchecked: string[];\n  /** The one instruction that outranks the rest. */\n  rule: string;\n}\n\nconst NEVER_OVERWRITE =\n  \"Do not overwrite an artifact that already exists. Read it, diff your findings against it, and report what disagrees — a document somebody wrote is evidence, and replacing it destroys the only copy of what they knew.\";\n\n/**\n * Assemble the brief for one service. Reads the docs repo; writes nothing.\n * `at` overrides where the artifacts are briefed to land — `adopt\n * --subsystem`'s target inside a group — and is only ever passed for a\n * service the enumeration does NOT answer: an existing service is briefed\n * where it already lives, because the brief's one rule is to never overwrite,\n * and a second address would brief a duplicate.\n */\nexport async function serviceBrief(\n  docsDir: DocsDir,\n  service: PathableService,\n  at?: ServicePaths,\n): Promise<Brief> {\n  const paths = at ?? (await locateServicePaths(docsDir, service));\n  const rel = (abs: string): string => relative(docsDir, abs).split(/[\\\\/]/).join(\"/\");\n\n  // Read before the artifact loop, not after it: what the fleet already says\n  // about this service decides whether it owes an API contract at all.\n  const landscape = await landscapeContext(docsDir, service);\n  const owesApi = apiExpected(landscape);\n\n  const targets: BriefTarget[] = [];\n  for (const { key, ...artifact } of ARTIFACTS) {\n    // `adrs/` is a directory, and an empty one is not an existing artifact —\n    // reporting it as present would tell the agent to diff against nothing.\n    const dir = key === \"adrsDir\";\n    const exists = dir ? await hasMarkdown(paths[key]) : existsSync(paths[key]);\n    targets.push({\n      ...artifact,\n      ...(key === \"openapi\" ? { required: owesApi } : {}),\n      path: dir ? `${rel(paths[key])}/` : rel(paths[key]),\n      exists,\n      action: exists ? \"diff\" : \"create\",\n    });\n  }\n\n  // The eighth target is the fleet map, and it is conditional: a service the\n  // landscape ALREADY resolves an element to owes it nothing, and briefing an\n  // edit there would invite an agent to draw a second box for a service that\n  // has one. Everything else about the target is unconditional — the file is\n  // shared, so `action` is `edit` whenever it exists and `create` only for the\n  // very first service of a brand-new docs repo.\n  if (landscape.modelled !== true) {\n    targets.push({\n      ...landscapeArtifact(service, landscape.expects, landscape.present, rel(paths.dir)),\n      path: rel(landscapePath(docsDir)),\n      exists: landscape.present,\n      action: landscape.present ? \"edit\" : \"create\",\n    });\n  }\n\n  return {\n    service,\n    docsDir,\n    path: rel(paths.dir),\n    targets,\n    walk: WALK,\n    walkClose: WALK_CLOSE,\n    landscape,\n    frontmatter: FRONTMATTER_BRIEF,\n    checks: VALIDATE_CHECKS,\n    unchecked: UNCHECKED,\n    rule: NEVER_OVERWRITE,\n  };\n}\n\nasync function hasMarkdown(dir: string): Promise<boolean> {\n  if (!existsSync(dir)) return false;\n  const entries = await readdir(dir, { withFileTypes: true });\n  // `statSync` for the symlink case: a Dirent never follows one, so `isFile()`\n  // is false for a symlinked ADR and the directory reads as empty (repo.ts's\n  // `entryIs` is the same rule for `services/` and `features/`).\n  return entries.some((e) => {\n    if (!e.name.endsWith(\".md\")) return false;\n    if (e.isFile()) return true;\n    if (!e.isSymbolicLink()) return false;\n    try {\n      return statSync(join(dir, e.name)).isFile();\n    } catch {\n      return false;\n    }\n  });\n}\n\n/**\n * Does the fleet expect an API of this service?\n *\n * The brief marked `openapi.yaml` required unconditionally, and printed the\n * absence as `MISSING` in capitals — while `loam validate` and `loam list`\n * derive the opposite from the same landscape (`service.no-openapi` stays quiet\n * when nothing calls the service, and `list`'s maturity ladder stops demanding\n * a contract). For a UI, a worker or a cron the brief was therefore telling an\n * agent to INVENT an API contract into the source of truth — the one class of\n * guess this whole module exists to refuse, and the one the brief itself names\n * in `openapi.yaml`'s shape rules (`ARTIFACTS`, targets.ts).\n *\n * Positive evidence only, exactly as `list` reads it: a landscape that is\n * absent or does not parse proves nothing about who calls this service, so the\n * contract is still owed. `expects` is the ops on inbound edges, which is\n * `list`'s `called` set seen from one service.\n */\nfunction apiExpected(landscape: LandscapeContext): boolean {\n  return !landscape.parses || landscape.expects.length > 0;\n}\n"]}

package/dist/core/brief/checks.js

@@ -0,0 +1,250 @@
+/**
+ * The checks half of the adoption brief: every check `loam validate` will run
+ * against a baseline, each naming the invocation that surfaces it. Its
+ * counterpart — the UNCHECKED list, the checks that do not exist — lives in
+ * unchecked.ts: honesty no validator will ever supply, and an agent that does
+ * not know where the checking stops will assume it never does.
+ */
+/* ------------------------------------------------------------------ */
+/* The checks                                                          */
+/* ------------------------------------------------------------------ */
+/**
+ * The two invocations a baseline meets. `<id>` is a placeholder for the service
+ * id — the JSON contract keeps it symbolic, the text renderer substitutes it.
+ */
+const VIA_SERVICE = "loam validate --service <id>";
+export const VIA_ALL = "loam validate --all";
+/** What `loam validate` will run against the result — each check names the invocation that surfaces it. */
+export const VALIDATE_CHECKS = [
+    { code: "service.no-model", severity: "error", via: VIA_SERVICE, what: "there is no model.likec4 — every other check stops here" },
+    { code: "c4.invalid", severity: "error", via: VIA_SERVICE, what: "model.likec4 does not parse as LikeC4" },
+    {
+        code: "requirements.missing-scenarios",
+        severity: "error",
+        via: VIA_SERVICE,
+        what: "a requirement in spec.md or arch.spec.md has no `#### Scenario:`",
+    },
+    {
+        code: "spec.duplicate-requirement",
+        severity: "error",
+        via: VIA_SERVICE,
+        what: "one `### Requirement:` name defined twice in one living spec.md or arch.spec.md — a later merge edits only the first, the rest live on as stale copies",
+    },
+    {
+        code: "spec.requirement-id-invalid",
+        severity: "error",
+        via: VIA_SERVICE,
+        what: "an optional `Requirement-ID:` violates `[A-Za-z][A-Za-z0-9._-]{0,127}` — stable identities must be portable and unambiguous",
+    },
+    {
+        code: "spec.requirement-id-repeated",
+        severity: "error",
+        via: VIA_SERVICE,
+        what: "one requirement declares `Requirement-ID:` more than once — keep exactly one identity line",
+    },
+    {
+        code: "spec.requirement-id-duplicate",
+        severity: "error",
+        via: VIA_SERVICE,
+        what: "one stable Requirement-ID identifies multiple requirements in one spec.md or arch.spec.md",
+    },
+    // The keep-last pair: a second `Operations:` / `Covers:` line in one
+    // requirement body REPLACES the first — assignment, not append — so the
+    // author's two-line list silently loses its first line. The semantics stay;
+    // the loss no longer happens in silence.
+    {
+        code: "spec.repeated-operations",
+        severity: "warn",
+        via: VIA_SERVICE,
+        what: "a second `Operations:` line in one requirement body — the last replaces the earlier ones, whose list is silently dropped; merge into one comma-separated line",
+    },
+    {
+        code: "spec.repeated-covers",
+        severity: "warn",
+        via: VIA_SERVICE,
+        what: "a second `Covers:` line in one requirement body — same keep-last rule, same silent loss; merge into one comma-separated line",
+    },
+    // The graded absences: the brief marks spec.md and openapi.yaml required, and
+    // validate agrees they belong — as warns, because partial adoption is a
+    // supported state and these are its honest progress meter, not a gate.
+    {
+        code: "service.no-spec",
+        severity: "warn",
+        via: VIA_SERVICE,
+        what: "spec.md does not exist yet — legal mid-adoption, but requirement coverage and API governance are unchecked until it does",
+    },
+    {
+        // `warn` is the floor, not the whole story, and the difference matters to a
+        // baseline: the absence is graded an ERROR once something already written
+        // down joins into the file — a living requirement's `Operations:` line, or
+        // an op-linked landscape edge (`landscape.expects`, landscape.ts). For a
+        // service the fleet already calls, `required: true` on this target and this
+        // row are the same fact stated twice.
+        code: "service.no-openapi",
+        severity: "warn",
+        via: VIA_SERVICE,
+        what: "openapi.yaml does not exist yet — quiet only when the landscape proves no other service calls an operation on this one, and an ERROR rather than a warning once a living `Operations:` line or a landscape edge already names an operation it would have defined",
+    },
+    {
+        code: "openapi.invalid",
+        severity: "error",
+        via: VIA_SERVICE,
+        what: "openapi.yaml exists but does not parse — an unreadable contract proves nothing, so the `api.*` checks and the spine's op resolution are suspended until it reads",
+    },
+    {
+        code: "api.ungoverned",
+        severity: "warn",
+        via: VIA_SERVICE,
+        what: "an operationId in openapi.yaml that no requirement's `Operations:` line names",
+    },
+    {
+        code: "api.ops-unlinked",
+        severity: "warn",
+        via: VIA_SERVICE,
+        what: "openapi.yaml defines operations and spec.md has requirements, but no `Operations:` line joins them — every cross-axis check is vacuously green",
+    },
+    // The `Operations:` spine, checked against the LIVING contract. It used to
+    // fire only inside a feature delta, so a baseline could ship a requirement
+    // governing an operation nobody defines and stay green until the first
+    // feature touched it.
+    {
+        code: "spec-api.op-undefined",
+        severity: "error",
+        via: VIA_SERVICE,
+        what: "a living requirement's `Operations:` line names an operationId this service's openapi.yaml does not define — the two axes disagree about what the service exposes",
+    },
+    {
+        code: "spec.no-requirements",
+        severity: "warn",
+        via: VIA_SERVICE,
+        what: "spec.md exists but holds no `### Requirement:` block at all — every requirement-driven check below it is vacuous rather than passing",
+    },
+    // The deprecation pair fires on a fresh baseline too — a legacy service is
+    // exactly where ops marked `deprecated: true` coexist with their
+    // replacements, and documenting that lifecycle honestly is part of the
+    // adoption. Mark the flag where the code retires an op; loam reads it, and
+    // has no removal semantics beyond it.
+    {
+        code: "api.requirement-deprecated",
+        severity: "warn",
+        via: VIA_SERVICE,
+        what: "a requirement whose `Operations:` list resolves only to operations openapi.yaml marks `deprecated: true` — the behaviour it governs is being retired",
+    },
+    {
+        code: "spine.op-undefined",
+        severity: "error",
+        via: VIA_SERVICE,
+        what: "a landscape edge into this service calls an operation its openapi.yaml does not define — a broken contract between services",
+    },
+    {
+        code: "spine.op-link-missing",
+        severity: "warn",
+        via: VIA_SERVICE,
+        what: 'a landscape "Calls" edge into this service with no `metadata { op }`',
+    },
+    {
+        code: "spine.op-deprecated",
+        severity: "warn",
+        via: VIA_SERVICE,
+        what: "a landscape edge into this service calls an operation openapi.yaml marks `deprecated: true` — the consumer should be migrating off it",
+    },
+    {
+        code: "covers.unknown",
+        severity: "warn",
+        via: VIA_SERVICE,
+        what: "a `Covers:` entry in arch.spec.md that resolves to no element, edge, alert or SLI — a typo silently costs the coverage it was written for",
+    },
+    {
+        code: "health.invalid",
+        severity: "warn",
+        via: VIA_SERVICE,
+        what: "health.yaml exists but does not parse — its alert/SLI ids are unreadable, so `Covers: alert:/sli:` entries and health coverage go unchecked until it reads (a missing health.yaml stays silent)",
+    },
+    {
+        code: "health.uncovered",
+        severity: "warn",
+        via: VIA_SERVICE,
+        what: "an alert or SLI declared in health.yaml that no arch.spec.md requirement covers — expected until the arch spec is written; each one is a signal nothing tests",
+    },
+    {
+        code: "health.dependency-unmodelled",
+        severity: "warn",
+        via: VIA_SERVICE,
+        what: "a health.yaml `dependencies:` id that nothing in this service's OWN model.likec4 answers to (element id, `metadata { service }` binding, or title) — the model carries everything the service touches, private stores included as nested containers, and the on-call file must name the same world",
+    },
+    {
+        code: "frontmatter.malformed",
+        severity: "error",
+        via: VIA_SERVICE,
+        what: "the frontmatter block does not parse as YAML — owner, status and sources are unreadable, and the field checks are suspended until the header is fixed",
+    },
+    {
+        code: "frontmatter.field-mismatch",
+        severity: "error",
+        via: VIA_SERVICE,
+        what: "spec.md declares a different `service:` than the directory it lives under",
+    },
+    {
+        code: "frontmatter.status-unknown",
+        severity: "error",
+        via: VIA_SERVICE,
+        what: "a status outside `draft` / `verified` — a typo here reads as unverified forever",
+    },
+    { code: "frontmatter.field-missing", severity: "warn", via: VIA_SERVICE, what: "no `owner`, `status` or `service`" },
+    { code: "sources.absent", severity: "warn", via: VIA_SERVICE, what: "spec.md names no `sources`" },
+    {
+        code: "sources.path-missing",
+        severity: "error",
+        via: VIA_SERVICE,
+        what: "a listed source does not exist, or is a glob pattern — no longer supported (checked when loam runs inside the service's repo)",
+    },
+    {
+        code: "sources.unvouched",
+        severity: "warn",
+        via: VIA_SERVICE,
+        what: "`sources` with no digest — nobody has vouched for the document yet. Expected on a fresh baseline; only a human closes it",
+    },
+    {
+        code: "sources.unwalked",
+        severity: "warn",
+        via: VIA_SERVICE,
+        what: "`sources` leaves whole top-level paths of the service repo untouched — the finding names them (checked when loam runs inside the service's repo, against the files git tracks). It grades the WALK, not the writing: the only completeness signal loam can compute, because it is the only one that compares the document against the repository rather than against itself",
+    },
+    // sources.stale, sources.current and content.stale are deliberately absent:
+    // all three compare against digests `loam vouch` stamps, and a fresh baseline
+    // has no stamp to compare — the table lists what a baseline can actually meet.
+    // The gherkin.* staleness chain is absent the same way: it fires only once
+    // `loam gherkin` has generated a suite under <gherkinDir>/loam/ in the
+    // service's own repo, and a fresh baseline has not generated one.
+    {
+        code: "landscape.service-unmodelled",
+        severity: "error",
+        via: VIA_ALL,
+        what: "nothing in architecture/landscape.likec4 resolves to services/<id>/ — the fleet map is incomplete until an element exists or an existing one is bound with `metadata { service '<id>' }`",
+    },
+    {
+        code: "landscape.missing",
+        severity: "error",
+        via: VIA_ALL,
+        what: "architecture/landscape.likec4 does not exist at all — an error as soon as services/ holds one service (a warning only in an empty docs repo): with no fleet map, every cross-service check is blind rather than passing",
+    },
+    {
+        code: "landscape.invalid",
+        severity: "error",
+        via: VIA_ALL,
+        what: "architecture/landscape.likec4 exists but does not parse — fix it before anything else; the whole cross-service layer is unchecked until it reads",
+    },
+    {
+        code: "landscape.binding-unknown",
+        severity: "error",
+        via: VIA_ALL,
+        what: "an element's `metadata { service }` names a directory that does not exist — a binding is a claim about this repo, and this one is false",
+    },
+    {
+        code: "landscape.binding-duplicate",
+        severity: "warn",
+        via: VIA_ALL,
+        what: "two landscape elements resolve to the same services/<id>/ — every element→service join picks one of them arbitrarily, so the other's edges are filed under a service that does not own them",
+    },
+];
+//# sourceMappingURL=checks.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"checks.js","sourceRoot":"","sources":["../../../src/core/brief/checks.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * The checks half of the adoption brief: every check `loam validate` will run\n * against a baseline, each naming the invocation that surfaces it. Its\n * counterpart — the UNCHECKED list, the checks that do not exist — lives in\n * unchecked.ts: honesty no validator will ever supply, and an agent that does\n * not know where the checking stops will assume it never does.\n */\n\n/* ------------------------------------------------------------------ */\n/* The checks                                                          */\n/* ------------------------------------------------------------------ */\n\n/**\n * The two invocations a baseline meets. `<id>` is a placeholder for the service\n * id — the JSON contract keeps it symbolic, the text renderer substitutes it.\n */\nconst VIA_SERVICE = \"loam validate --service <id>\";\nexport const VIA_ALL = \"loam validate --all\";\n\nexport interface BriefCheck {\n  code: string;\n  severity: \"error\" | \"warn\";\n  /**\n   * The invocation that surfaces this check. Most run under `--service`, but\n   * the fleet cross-check does not — attributing it there taught agents to\n   * expect a finding that run never reports.\n   */\n  via: typeof VIA_SERVICE | typeof VIA_ALL;\n  what: string;\n}\n\n/** What `loam validate` will run against the result — each check names the invocation that surfaces it. */\nexport const VALIDATE_CHECKS: BriefCheck[] = [\n  { code: \"service.no-model\", severity: \"error\", via: VIA_SERVICE, what: \"there is no model.likec4 — every other check stops here\" },\n  { code: \"c4.invalid\", severity: \"error\", via: VIA_SERVICE, what: \"model.likec4 does not parse as LikeC4\" },\n  {\n    code: \"requirements.missing-scenarios\",\n    severity: \"error\",\n    via: VIA_SERVICE,\n    what: \"a requirement in spec.md or arch.spec.md has no `#### Scenario:`\",\n  },\n  {\n    code: \"spec.duplicate-requirement\",\n    severity: \"error\",\n    via: VIA_SERVICE,\n    what: \"one `### Requirement:` name defined twice in one living spec.md or arch.spec.md — a later merge edits only the first, the rest live on as stale copies\",\n  },\n  {\n    code: \"spec.requirement-id-invalid\",\n    severity: \"error\",\n    via: VIA_SERVICE,\n    what: \"an optional `Requirement-ID:` violates `[A-Za-z][A-Za-z0-9._-]{0,127}` — stable identities must be portable and unambiguous\",\n  },\n  {\n    code: \"spec.requirement-id-repeated\",\n    severity: \"error\",\n    via: VIA_SERVICE,\n    what: \"one requirement declares `Requirement-ID:` more than once — keep exactly one identity line\",\n  },\n  {\n    code: \"spec.requirement-id-duplicate\",\n    severity: \"error\",\n    via: VIA_SERVICE,\n    what: \"one stable Requirement-ID identifies multiple requirements in one spec.md or arch.spec.md\",\n  },\n  // The keep-last pair: a second `Operations:` / `Covers:` line in one\n  // requirement body REPLACES the first — assignment, not append — so the\n  // author's two-line list silently loses its first line. The semantics stay;\n  // the loss no longer happens in silence.\n  {\n    code: \"spec.repeated-operations\",\n    severity: \"warn\",\n    via: VIA_SERVICE,\n    what: \"a second `Operations:` line in one requirement body — the last replaces the earlier ones, whose list is silently dropped; merge into one comma-separated line\",\n  },\n  {\n    code: \"spec.repeated-covers\",\n    severity: \"warn\",\n    via: VIA_SERVICE,\n    what: \"a second `Covers:` line in one requirement body — same keep-last rule, same silent loss; merge into one comma-separated line\",\n  },\n  // The graded absences: the brief marks spec.md and openapi.yaml required, and\n  // validate agrees they belong — as warns, because partial adoption is a\n  // supported state and these are its honest progress meter, not a gate.\n  {\n    code: \"service.no-spec\",\n    severity: \"warn\",\n    via: VIA_SERVICE,\n    what: \"spec.md does not exist yet — legal mid-adoption, but requirement coverage and API governance are unchecked until it does\",\n  },\n  {\n    // `warn` is the floor, not the whole story, and the difference matters to a\n    // baseline: the absence is graded an ERROR once something already written\n    // down joins into the file — a living requirement's `Operations:` line, or\n    // an op-linked landscape edge (`landscape.expects`, landscape.ts). For a\n    // service the fleet already calls, `required: true` on this target and this\n    // row are the same fact stated twice.\n    code: \"service.no-openapi\",\n    severity: \"warn\",\n    via: VIA_SERVICE,\n    what: \"openapi.yaml does not exist yet — quiet only when the landscape proves no other service calls an operation on this one, and an ERROR rather than a warning once a living `Operations:` line or a landscape edge already names an operation it would have defined\",\n  },\n  {\n    code: \"openapi.invalid\",\n    severity: \"error\",\n    via: VIA_SERVICE,\n    what: \"openapi.yaml exists but does not parse — an unreadable contract proves nothing, so the `api.*` checks and the spine's op resolution are suspended until it reads\",\n  },\n  {\n    code: \"api.ungoverned\",\n    severity: \"warn\",\n    via: VIA_SERVICE,\n    what: \"an operationId in openapi.yaml that no requirement's `Operations:` line names\",\n  },\n  {\n    code: \"api.ops-unlinked\",\n    severity: \"warn\",\n    via: VIA_SERVICE,\n    what: \"openapi.yaml defines operations and spec.md has requirements, but no `Operations:` line joins them — every cross-axis check is vacuously green\",\n  },\n  // The `Operations:` spine, checked against the LIVING contract. It used to\n  // fire only inside a feature delta, so a baseline could ship a requirement\n  // governing an operation nobody defines and stay green until the first\n  // feature touched it.\n  {\n    code: \"spec-api.op-undefined\",\n    severity: \"error\",\n    via: VIA_SERVICE,\n    what: \"a living requirement's `Operations:` line names an operationId this service's openapi.yaml does not define — the two axes disagree about what the service exposes\",\n  },\n  {\n    code: \"spec.no-requirements\",\n    severity: \"warn\",\n    via: VIA_SERVICE,\n    what: \"spec.md exists but holds no `### Requirement:` block at all — every requirement-driven check below it is vacuous rather than passing\",\n  },\n  // The deprecation pair fires on a fresh baseline too — a legacy service is\n  // exactly where ops marked `deprecated: true` coexist with their\n  // replacements, and documenting that lifecycle honestly is part of the\n  // adoption. Mark the flag where the code retires an op; loam reads it, and\n  // has no removal semantics beyond it.\n  {\n    code: \"api.requirement-deprecated\",\n    severity: \"warn\",\n    via: VIA_SERVICE,\n    what: \"a requirement whose `Operations:` list resolves only to operations openapi.yaml marks `deprecated: true` — the behaviour it governs is being retired\",\n  },\n  {\n    code: \"spine.op-undefined\",\n    severity: \"error\",\n    via: VIA_SERVICE,\n    what: \"a landscape edge into this service calls an operation its openapi.yaml does not define — a broken contract between services\",\n  },\n  {\n    code: \"spine.op-link-missing\",\n    severity: \"warn\",\n    via: VIA_SERVICE,\n    what: 'a landscape \"Calls\" edge into this service with no `metadata { op }`',\n  },\n  {\n    code: \"spine.op-deprecated\",\n    severity: \"warn\",\n    via: VIA_SERVICE,\n    what: \"a landscape edge into this service calls an operation openapi.yaml marks `deprecated: true` — the consumer should be migrating off it\",\n  },\n  {\n    code: \"covers.unknown\",\n    severity: \"warn\",\n    via: VIA_SERVICE,\n    what: \"a `Covers:` entry in arch.spec.md that resolves to no element, edge, alert or SLI — a typo silently costs the coverage it was written for\",\n  },\n  {\n    code: \"health.invalid\",\n    severity: \"warn\",\n    via: VIA_SERVICE,\n    what: \"health.yaml exists but does not parse — its alert/SLI ids are unreadable, so `Covers: alert:/sli:` entries and health coverage go unchecked until it reads (a missing health.yaml stays silent)\",\n  },\n  {\n    code: \"health.uncovered\",\n    severity: \"warn\",\n    via: VIA_SERVICE,\n    what: \"an alert or SLI declared in health.yaml that no arch.spec.md requirement covers — expected until the arch spec is written; each one is a signal nothing tests\",\n  },\n  {\n    code: \"health.dependency-unmodelled\",\n    severity: \"warn\",\n    via: VIA_SERVICE,\n    what: \"a health.yaml `dependencies:` id that nothing in this service's OWN model.likec4 answers to (element id, `metadata { service }` binding, or title) — the model carries everything the service touches, private stores included as nested containers, and the on-call file must name the same world\",\n  },\n  {\n    code: \"frontmatter.malformed\",\n    severity: \"error\",\n    via: VIA_SERVICE,\n    what: \"the frontmatter block does not parse as YAML — owner, status and sources are unreadable, and the field checks are suspended until the header is fixed\",\n  },\n  {\n    code: \"frontmatter.field-mismatch\",\n    severity: \"error\",\n    via: VIA_SERVICE,\n    what: \"spec.md declares a different `service:` than the directory it lives under\",\n  },\n  {\n    code: \"frontmatter.status-unknown\",\n    severity: \"error\",\n    via: VIA_SERVICE,\n    what: \"a status outside `draft` / `verified` — a typo here reads as unverified forever\",\n  },\n  { code: \"frontmatter.field-missing\", severity: \"warn\", via: VIA_SERVICE, what: \"no `owner`, `status` or `service`\" },\n  { code: \"sources.absent\", severity: \"warn\", via: VIA_SERVICE, what: \"spec.md names no `sources`\" },\n  {\n    code: \"sources.path-missing\",\n    severity: \"error\",\n    via: VIA_SERVICE,\n    what: \"a listed source does not exist, or is a glob pattern — no longer supported (checked when loam runs inside the service's repo)\",\n  },\n  {\n    code: \"sources.unvouched\",\n    severity: \"warn\",\n    via: VIA_SERVICE,\n    what: \"`sources` with no digest — nobody has vouched for the document yet. Expected on a fresh baseline; only a human closes it\",\n  },\n  {\n    code: \"sources.unwalked\",\n    severity: \"warn\",\n    via: VIA_SERVICE,\n    what: \"`sources` leaves whole top-level paths of the service repo untouched — the finding names them (checked when loam runs inside the service's repo, against the files git tracks). It grades the WALK, not the writing: the only completeness signal loam can compute, because it is the only one that compares the document against the repository rather than against itself\",\n  },\n  // sources.stale, sources.current and content.stale are deliberately absent:\n  // all three compare against digests `loam vouch` stamps, and a fresh baseline\n  // has no stamp to compare — the table lists what a baseline can actually meet.\n  // The gherkin.* staleness chain is absent the same way: it fires only once\n  // `loam gherkin` has generated a suite under <gherkinDir>/loam/ in the\n  // service's own repo, and a fresh baseline has not generated one.\n  {\n    code: \"landscape.service-unmodelled\",\n    severity: \"error\",\n    via: VIA_ALL,\n    what: \"nothing in architecture/landscape.likec4 resolves to services/<id>/ — the fleet map is incomplete until an element exists or an existing one is bound with `metadata { service '<id>' }`\",\n  },\n  {\n    code: \"landscape.missing\",\n    severity: \"error\",\n    via: VIA_ALL,\n    what: \"architecture/landscape.likec4 does not exist at all — an error as soon as services/ holds one service (a warning only in an empty docs repo): with no fleet map, every cross-service check is blind rather than passing\",\n  },\n  {\n    code: \"landscape.invalid\",\n    severity: \"error\",\n    via: VIA_ALL,\n    what: \"architecture/landscape.likec4 exists but does not parse — fix it before anything else; the whole cross-service layer is unchecked until it reads\",\n  },\n  {\n    code: \"landscape.binding-unknown\",\n    severity: \"error\",\n    via: VIA_ALL,\n    what: \"an element's `metadata { service }` names a directory that does not exist — a binding is a claim about this repo, and this one is false\",\n  },\n  {\n    code: \"landscape.binding-duplicate\",\n    severity: \"warn\",\n    via: VIA_ALL,\n    what: \"two landscape elements resolve to the same services/<id>/ — every element→service join picks one of them arbitrarily, so the other's edges are filed under a service that does not own them\",\n  },\n];\n"]}