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

package/dist/core/agent/workflows/adopt.js

@@ -0,0 +1,280 @@
+/** The adoption protocol: write one service's baseline docs from its code, as draft. */
+export const LOAM_ADOPT = {
+    name: "loam-adopt",
+    description: "Adopt a service — write its baseline docs from its code, as draft, then validate",
+    argumentHint: "<service-id>",
+    purpose: "Write one service's baseline documentation into the docs repo from its code, as `draft`. You read the code; loam states the work and checks the result — it never reads the service, so anything you cannot show, do not write.",
+    invocation: "loam instructions loam-adopt $1",
+    placeholders: ["service"],
+    spine: [
+        "wire this repo (`loam init`, then `loam doctor`) if it has no ./loam.json yet",
+        "`loam adopt` — the brief: the order to read the service in, every file to write, the grammar of each, and what the fleet map already says",
+        "walk the service in the brief's order — shape first, then one surface at a time — keeping the list of every path you open, because that list becomes `sources`",
+        "write the artifacts, everything `status: draft` — the model EXTENDS the fleet map — then `loam subsystem sync` for the renderer wiring, which is loam's and never yours",
+        "validate the service, then validate the whole fleet — a baseline that passes one and fails the other is documented and invisible",
+        "hand back with what you could not determine from the code, which directories you never opened, the branch-to-scenario count per operation, and three behaviours your documents do not describe — then let a human vouch",
+    ],
+    body: `Write one service's baseline documentation into the loam docs repo (its path is
+\`docsDir\` in ./loam.json). You read the code; loam states the work and checks the
+result. It never reads the service — so anything you cannot show, do not write.
+
+**The bar this artifact set aims at is reproducibility**: a reader should be able
+to answer, from these files alone — what this boundary exposes, what it reaches,
+what shapes it exchanges, how it is run, and what pages whom — without opening
+the code. \`loam validate\` grades form and joins, never depth: green means the
+files agree with each other, and the bar is what "done" is measured against — a
+thin baseline that validates is thin, not done.
+
+0. If there is no ./loam.json here, wire the repo first with
+   \`loam init --docs <path-to-docs-repo> --service $1 --agent-profile service\`.
+   ONLY if the docs repo does not exist yet, this is the single-repo trial: run
+   \`loam init --docs <path-to-docs-repo> --create --service $1\` instead, and its one
+   checkout keeps the full profile. Then \`loam doctor\` — it resolves \`docsDir\`,
+   checks the docs repo is one, and reports the service binding. Do not go on with
+   \`docs-missing\`, \`services-missing\` or any \`doctor.*\` blocker standing.
+   Every \`doctor\` finding carries a \`fix\` field spelling the exact command —
+   type that, not an approximation of it.
+   If this repo is already wired, \`loam status --json\` in the docs repo is the
+   fastest way to see whether $1 is even the service that owes work next: its
+   \`next.adopt\` entries name the services with nothing written down yet.
+1. \`loam adopt --service $1 --json\`. That output IS the brief:
+   - \`warnings[]\` — read these FIRST. A near-miss against an existing service id
+     usually means \`$1\` is a typo, and a brief followed to the letter then produces
+     a complete, validating baseline for a service that does not exist.
+   - \`targets[]\` — every file to write. \`action: "diff"\` means the file ALREADY EXISTS:
+     read it, diff your findings against it, report what disagrees. Do not replace it.
+     \`action: "edit"\` appears on exactly one target — \`architecture/landscape.likec4\`,
+     the WHOLE FLEET's map: add this service's element and edges to it, never rewrite it.
+     It appears while nothing resolves to the service AND while the element that does
+     has no edge touching it; \`targets[].shape\` says which of the two you are in.
+     It does NOT appear when loam could not READ the map (\`landscape.modelled: null\`
+     — a broken landscape, or a broken sibling under \`architecture/\`): nothing is
+     known about what the map already draws, so no write to the whole fleet's map is
+     briefed. \`landscape.instruction\` carries the answer and names the documents that
+     failed; fix those and re-run.
+   - \`targets[].shape\` — the grammar of each artifact, and \`example\` where one is
+     shorter than a description. Every rule there is one a later check depends on;
+     rules nothing checks are in \`unchecked[]\` instead, and are still worth following.
+   - \`landscape\` — the elements and edges the fleet already has for this service.
+     Bind to them; do not draw a second version of the same box. \`landscape.expects\`
+     lists operations other services already call — your openapi.yaml owes them.
+     \`landscape.instruction\` is the write the fleet map still owes this service; it
+     is \`null\` once an element resolves to it AND at least one edge ANYWHERE in the
+     \`architecture/\` project touches that element (\`landscape.touched\`), and only
+     then — one edge closes the state, so draw every call in one pass.
+     \`landscape.attested\` lists the
+     calls \`services/$1/model.likec4\` already declares across its boundary — those
+     are the edges the map owes, collapsed to the service; an empty list on a
+     service with no model is not licence to invent one, and the instruction says so.
+   - \`frontmatter\` — what to put in the header of every markdown artifact.
+   - \`checks[]\` — what \`loam validate\` will run. \`unchecked[]\` — what it will not.
+2. Read \`AGENTS.md\` at the docs repo root, then walk the service — \`walk[]\` in the
+   same \`adopt\` output is the order, and it is an order, not a menu. Each stop
+   names what to open, what to take from it, and which artifacts it feeds
+   (\`lands\`). The first two stops fix what the service IS — how many processes,
+   built from what — before any surface is enumerated: an agent that opens the
+   HTTP routes first has already decided the service is an API by the time it
+   meets the scheduler, and the consumer group and the outbox never get written
+   down. Do not stop at the surface you recognise fastest.
+   \`walkClose\` is the question that ends it: **list the directories you did not
+   open.** Nothing downstream can find a service you documented a third of —
+   \`api.ungoverned\` grades the operations you WROTE, and is silent about the twelve
+   you never did.
+   **Keep a list of every path you actually open.** That list becomes \`sources\` —
+   written as files and directories, never glob patterns — and it is the only line
+   tying the document to the repository. Never pad it with paths you did not read:
+   it is a record, and \`loam vouch\` hashes exactly what it names.
+3. Write the artifacts under \`services/$1/\`, in the order the brief lists them, and
+   make the landscape edit the brief asks for — the element where none resolves, the
+   edges where the element stands alone, and the map's own housekeeping
+   \`unchecked[]\` names: a placeholder tag to clear, a curated view to add the
+   element to.
+   **Every edge you draw gets a relationship kind, and a direction you can
+   show.** \`calls\` is a request the code makes. \`publishes\` runs from the
+   producer to the topic and \`delivers\` from the topic to the consumer.
+   \`reads\`, \`writes\` and \`readsWrites\` are always written service \`->\` store,
+   with the arrowhead put where the data lands by the kind's style.
+   Take the direction from this service's code, from a configuration name that
+   says which side it is on (\`*_PRODUCER_*\`, \`*_CONSUMER_*\`, a consumer-group
+   id), or from its own \`asyncapi.yaml\` (\`send\` publishes, \`receive\` consumes).
+   Never take it from deployment configuration that only lists an address: that
+   says two things are connected and nothing more, so it is drawn \`connects\`.
+   You are reading the code now, so turn every \`connects\` edge that touches $1
+   into its real kind, and name in step 6 the ones the code did not settle. Use
+   the kinds the map's \`specification\` declares, and declare a missing one
+   there, once, in the same landscape edit. \`loam instructions loam-drawing\`
+   has the kinds, their styles and the views a person can read.
+   **model.likec4 EXTENDS the fleet map.** It declares no \`specification\` block and
+   no copy of anything the map already draws: its whole body is
+   \`model { extend <fqn> { …containers… } }\`, where \`<fqn>\` is the FULLY-QUALIFIED
+   id of the element bound to \`services/$1/\` (the brief's \`landscape.elements\` names
+   it; \`extend orderService\` resolves to nothing when the id is
+   \`marketplace.orderService\`). Kinds and tags come from
+   \`architecture/landscape.likec4\` — a kind you need and the map does not declare
+   (\`element database\`, \`element queue\`) is added THERE, once, in the same landscape
+   edit. Cross-boundary edges are written OUTSIDE the extend block, from the container
+   that makes the call to the other party's element as the map spells it; an element
+   this file declares outside its own is \`c4.element-unowned\` (warn), and which fix
+   applies depends on whose it is — a store or component this service OWNS belongs
+   INSIDE the \`extend\` block (its id becomes \`<fqn>.<name>\`), a system the service
+   merely reaches is declared in the map instead, and another service's internals
+   belong in that service's model. If you are DIFFING an existing model
+   that carries its own \`specification\`, leave it alone: that shape is still legal
+   and still parsed on its own, and \`c4.declaration-diverged\` is what reports where
+   its copies of the map's elements have drifted. Migrating one is the recipe in
+   SCHEMA.md, "Two shapes of a service model" — not something to do inside an
+   adoption you were not asked to widen.
+   A flow behind one of your arch.spec.md requirements — a \`dynamic view\`
+   over this service's own containers — goes in a \`.likec4\` beside model.likec4
+   (\`services/$1/usecases/<name>.likec4\` by convention; \`views.likec4\` reads the
+   same, because the renderer's per-service project reads every \`.likec4\` under the
+   directory and so does loam), tagged \`#req-<Requirement-ID>\` of a requirement in
+   this service's spec.md or arch.spec.md, with the tag declared in the map's
+   \`specification\` block or in a tags-only \`specification { tag req-… }\` beside the
+   \`extend\` — in exactly ONE of the two. Declared in both, the model's own project
+   holds the tag twice: the error lands on whichever document carries the second
+   declaration, as \`c4.invalid\` (an error, and the model's grading is suspended
+   behind it) when that is model.likec4, or as \`usecase.flow-invalid\` when it is the
+   sibling. Step 4 grades it. It never goes in \`architecture/usecases/\`,
+   which cannot see your containers and turns the whole fleet \`landscape.invalid\`; a
+   flow that crosses services goes there and is tagged \`#cap-\`. Never a \`#cap-\` tag
+   beside a model. Then run \`loam subsystem sync\` (from
+   this repo or the docs repo — it resolves \`docsDir\`): once the docs root carries
+   the \`likec4.config.json\` step 0's doctor asks for, it keeps that file's
+   \`exclude\` list covering exactly the service directories whose models stand alone —
+   so an extending model stays inside the root project, where it is the only place it
+   parses and where the renderer draws it beside the map — and writes
+   \`services/<…>/<id>/likec4.config.json\` beside each STANDALONE model that has none.
+   Both are loam's — never write one yourself, never list it in \`sources\`, never
+   diff it, never hand-edit the root \`exclude\`'s \`services/\` entries — and \`sync\`
+   leaves what it wrote untracked for you to commit. A repo whose models all extend
+   the map usually has nothing for \`sync\` to write here, and that is the healthy
+   state, not a skipped step.
+   Everything \`status: draft\`. Never write \`last_verified\`, \`sources_digest\`,
+   \`content_digest\` or \`sources_files\`. A spec.md whose frontmatter says
+   \`adoption: partial\` is one archived feature's slice written into this service
+   before anyone adopted it: keep every requirement in it, write the rest of the
+   service's behaviour around them from the code, and when the document describes
+   the service — not just that feature — DELETE the \`adoption: partial\` line. It is
+   the only thing that clears it; until then \`loam list\` keeps the service
+   \`partial\` and \`loam status\` keeps asking for this adoption (\`next.adopt\`).
+4. \`loam validate --service $1 --json\`. Fix every error. \`c4.valid\` reading
+   "extends the fleet map" is the confirmation that the model was read as one
+   document with the map; \`c4.invalid\` on this run means the model plus the map do
+   not parse together, and every error is YOURS even where the message names
+   \`architecture/landscape.likec4\` — the map parses clean on its own, or
+   \`spine.landscape-invalid\` would say so instead and this model could not be read
+   at all. \`c4.element-unowned\` (warn) is an element you declared outside the
+   element you extend — nest it inside the \`extend\` block if this service owns it,
+   declare it in the map if the service only reaches it. \`sources.unvouched\` is
+   expected on a fresh baseline — it closes when a person vouches, not when you do.
+   \`sources.unwalked\` is the walk graded against the repository: its \`details\` name
+   the top-level paths git tracks and \`sources\` never reached into. Treat each one
+   as a place to go back to, not as a line to silence — the fix is reading it, or
+   one sentence in step 6 saying why this document does not owe it.
+   \`usecase.*\` findings on this run are about the flows beside model.likec4:
+   \`usecase.step-unbacked\` is a hop no relationship in model.likec4 backs,
+   \`usecase.step-contested\` two edges backing one hop and naming different
+   operations (open the step's title with the operation id it means, then
+   punctuation),
+   \`usecase.requirement-unresolved\` a \`#req-\` tag naming no
+   \`Requirement-ID:\` of this service's spec.md or arch.spec.md,
+   \`usecase.capability-unresolved\` a \`#cap-\` tag beside a model (drop it — a
+   capability is claimed on the fleet map, never inside one service), and
+   \`usecase.flow-invalid\` a file beside the model that does not read — the flows
+   were not graded, the model still was. \`usecase.step-unlinked\` never fires on a hop
+   whose caller and provider resolve to the same service — a service owes no
+   operationId to itself — but a hop from such a flow into another service's element
+   (a stand-in model.likec4 declares for a sibling, with no \`metadata { op }\`) still
+   warns here, exactly as it does on the fleet map.
+5. \`loam validate --all --json\` in the docs repo. This is the run that grades the
+   fleet map: \`landscape.service-unmodelled\` means the element never landed,
+   \`landscape.binding-unknown\` / \`landscape.binding-duplicate\` mean it landed wrong,
+   and \`landscape.missing\` means there is no map at all. A baseline that passes step 4
+   and fails this one is documented and invisible.
+   \`landscape.service-isolated\` (a warning) means the element landed with no edge
+   anywhere in \`architecture/\` while \`services/$1/model.likec4\` declares calls across
+   its boundary — the map owes those edges. It goes quiet on the FIRST edge, so draw
+   every call the brief listed in one pass: nothing will name the ones you leave out.
+   A service whose model declares no such call and whose element
+   has no edge is SILENT here: \`landscape.touched: false\` in step 1's brief is the
+   only place that state is named, so read it before this run rather than hoping
+   for it in it.
+   Six warnings on this run are about the RENDERER's wiring rather than about any
+   document, and one command fixes four of them: \`service.model-excluded\` (the root
+   \`likec4.config.json\` excludes a directory holding a model that extends the map, so
+   the renderer never loads it), \`service.model-unexcluded\` (its mirror, and the most
+   damaging — a model that STANDS ALONE whose directory the root \`exclude\` does not
+   cover merges into the root project and duplicates every kind the map declares,
+   which blanks the whole project rather than one service),
+   \`service.likec4-config-stray\` (a project file beside an extending model, which
+   claims the model out of the root project),
+   \`service.likec4-config-missing\` (a model that stands alone with no project file of
+   its own) and, when the first four are clear, \`c4.fleet-project-invalid\` — every
+   document reads clean where loam grades it and the ONE project the renderer builds
+   out of the map plus every extending model does not parse, because something is
+   declared in two of them. The first four: run \`loam subsystem sync\` — it rewrites
+   the root \`exclude\`, writes the missing project file and DELETES the stray one. The
+   fifth is an authoring fix: the message names the file and line, and the answer is
+   to declare the tag or element once, in the map or in the single service that owns it.
+   A sixth reads the same list and is NOT one of sync's: \`landscape.excluded\` says the
+   root \`exclude\` covers \`architecture/landscape.likec4\` itself, so the renderer has no
+   map to draw at all and every extending model in the root project resolves against
+   nothing — delete or narrow that entry by hand, at the line the finding quotes. While
+   it stands, \`c4.fleet-project-invalid\` is not graded at all: that check reads the
+   renderer's project, so the one entry would come back once per model instead of once as
+   the cause. Fix it first, then re-run and read the fifth.
+   Done, stated once: step 4 clean when run from inside the service's own repo, this
+   run reporting no \`landscape.*\` finding, no \`service.*\` renderer warning and no
+   \`c4.fleet-project-invalid\`, and
+   step 1's brief re-run reporting \`landscape.touched: true\` — or, for a service that
+   truly makes and receives no call, a stated reason its element is edgeless.
+   The fleet run is never SILENT —
+   \`sources.unverifiable-from-here\` (severity ok) appears per service as a
+   confirmation, not work — so "keep going until validation is quiet" is the wrong
+   loop; the two runs are the test.
+6. Hand back, and say eight things:
+   - what you could not determine from the code;
+   - what the existing artifacts disagreed with;
+   - which parts you are least sure of;
+   - what you did not open — every path \`sources.unwalked\` named, with one line
+     each on why the baseline does not owe it. That list is the only account
+     anybody gets of how much of the service was actually read; loam can name the
+     paths, and it can never say whether skipping one was right;
+   - every edge touching the service that is still drawn \`connects\`, with what
+     would settle its direction. An unresolved edge looks finished on the map,
+     so this list is the one place that says it is not;
+   - **two counts per operation**: how many decisions its code makes — permission
+     checks, conditionally required fields, defaults and normalisations, refused
+     transitions — and how many scenarios you wrote for it.
+     \`12 branches / 3 scenarios\` is a fact a reader can act on; "the
+     requirements look complete" is not, and no check loam has can tell the two
+     apart;
+   - **how well this service is covered by its own tests**, and how many of them
+     became scenarios. Say the number the service's own coverage tooling
+     reports, and where you read it. This is the ceiling on the whole baseline:
+     a well-covered service can be documented from evidence, and a service with
+     almost no tests can only be documented from a reading of its code, which is
+     a weaker document however carefully it is written. Nothing in loam can
+     compute this — say it, or nobody ever knows which kind they are holding;
+   - **three behaviours this service has that your documents do not describe.**
+     Not "is this enough" — that question is answered yes by every agent that
+     ever wrote a baseline, including the ones that documented a third of a
+     service, because the only thing it can be answered against is the document
+     itself. Name three. If you looked for three and found none, say exactly
+     that: it is a claim a reviewer can go and check, which "it is complete"
+     is not.
+   Then a human runs \`loam vouch --service $1\` in the service's own repo.
+
+An empty docs repo's \`loam status --json\` names this recipe's own states as its
+first-hour ladder: \`next.author-landscape\` (the fleet map is missing, or still the
+scaffold's untouched bytes — step 3's landscape edit is what discharges it),
+\`next.bind-service\` (no service repository is wired to the fleet yet — step 0) and
+\`next.adopt-first\` (services/ is empty — this protocol, from step 1). Landing on
+one of those codes means: run this recipe, starting at the step it points at.
+
+Where the code does not say, write that it does not say. A confident sentence about
+behaviour nobody can find is the one failure mode none of loam's checks can catch.
+`,
+};
+//# sourceMappingURL=adopt.js.map

package/dist/core/agent/workflows/adopt.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"adopt.js","sourceRoot":"","sources":["../../../../src/core/agent/workflows/adopt.ts"],"names":[],"mappings":"AAEA,wFAAwF;AACxF,MAAM,CAAC,MAAM,UAAU,GAAmB;IACxC,IAAI,EAAE,YAAY;IAClB,WAAW,EACT,kFAAkF;IACpF,YAAY,EAAE,cAAc;IAC5B,OAAO,EACL,iOAAiO;IACnO,UAAU,EAAE,iCAAiC;IAC7C,YAAY,EAAE,CAAC,SAAS,CAAC;IACzB,KAAK,EAAE;QACL,+EAA+E;QAC/E,2IAA2I;QAC3I,gKAAgK;QAChK,yKAAyK;QACzK,kIAAkI;QAClI,yNAAyN;KAC1N;IACD,IAAI,EAAE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAqQP;CACA,CAAC","sourcesContent":["import type { CommandContent } from \"../contract.js\";\n\n/** The adoption protocol: write one service's baseline docs from its code, as draft. */\nexport const LOAM_ADOPT: CommandContent = {\n  name: \"loam-adopt\",\n  description:\n    \"Adopt a service — write its baseline docs from its code, as draft, then validate\",\n  argumentHint: \"<service-id>\",\n  purpose:\n    \"Write one service's baseline documentation into the docs repo from its code, as `draft`. You read the code; loam states the work and checks the result — it never reads the service, so anything you cannot show, do not write.\",\n  invocation: \"loam instructions loam-adopt $1\",\n  placeholders: [\"service\"],\n  spine: [\n    \"wire this repo (`loam init`, then `loam doctor`) if it has no ./loam.json yet\",\n    \"`loam adopt` — the brief: the order to read the service in, every file to write, the grammar of each, and what the fleet map already says\",\n    \"walk the service in the brief's order — shape first, then one surface at a time — keeping the list of every path you open, because that list becomes `sources`\",\n    \"write the artifacts, everything `status: draft` — the model EXTENDS the fleet map — then `loam subsystem sync` for the renderer wiring, which is loam's and never yours\",\n    \"validate the service, then validate the whole fleet — a baseline that passes one and fails the other is documented and invisible\",\n    \"hand back with what you could not determine from the code, which directories you never opened, the branch-to-scenario count per operation, and three behaviours your documents do not describe — then let a human vouch\",\n  ],\n  body: `Write one service's baseline documentation into the loam docs repo (its path is\n\\`docsDir\\` in ./loam.json). You read the code; loam states the work and checks the\nresult. It never reads the service — so anything you cannot show, do not write.\n\n**The bar this artifact set aims at is reproducibility**: a reader should be able\nto answer, from these files alone — what this boundary exposes, what it reaches,\nwhat shapes it exchanges, how it is run, and what pages whom — without opening\nthe code. \\`loam validate\\` grades form and joins, never depth: green means the\nfiles agree with each other, and the bar is what \"done\" is measured against — a\nthin baseline that validates is thin, not done.\n\n0. If there is no ./loam.json here, wire the repo first with\n   \\`loam init --docs <path-to-docs-repo> --service $1 --agent-profile service\\`.\n   ONLY if the docs repo does not exist yet, this is the single-repo trial: run\n   \\`loam init --docs <path-to-docs-repo> --create --service $1\\` instead, and its one\n   checkout keeps the full profile. Then \\`loam doctor\\` — it resolves \\`docsDir\\`,\n   checks the docs repo is one, and reports the service binding. Do not go on with\n   \\`docs-missing\\`, \\`services-missing\\` or any \\`doctor.*\\` blocker standing.\n   Every \\`doctor\\` finding carries a \\`fix\\` field spelling the exact command —\n   type that, not an approximation of it.\n   If this repo is already wired, \\`loam status --json\\` in the docs repo is the\n   fastest way to see whether $1 is even the service that owes work next: its\n   \\`next.adopt\\` entries name the services with nothing written down yet.\n1. \\`loam adopt --service $1 --json\\`. That output IS the brief:\n   - \\`warnings[]\\` — read these FIRST. A near-miss against an existing service id\n     usually means \\`$1\\` is a typo, and a brief followed to the letter then produces\n     a complete, validating baseline for a service that does not exist.\n   - \\`targets[]\\` — every file to write. \\`action: \"diff\"\\` means the file ALREADY EXISTS:\n     read it, diff your findings against it, report what disagrees. Do not replace it.\n     \\`action: \"edit\"\\` appears on exactly one target — \\`architecture/landscape.likec4\\`,\n     the WHOLE FLEET's map: add this service's element and edges to it, never rewrite it.\n     It appears while nothing resolves to the service AND while the element that does\n     has no edge touching it; \\`targets[].shape\\` says which of the two you are in.\n     It does NOT appear when loam could not READ the map (\\`landscape.modelled: null\\`\n     — a broken landscape, or a broken sibling under \\`architecture/\\`): nothing is\n     known about what the map already draws, so no write to the whole fleet's map is\n     briefed. \\`landscape.instruction\\` carries the answer and names the documents that\n     failed; fix those and re-run.\n   - \\`targets[].shape\\` — the grammar of each artifact, and \\`example\\` where one is\n     shorter than a description. Every rule there is one a later check depends on;\n     rules nothing checks are in \\`unchecked[]\\` instead, and are still worth following.\n   - \\`landscape\\` — the elements and edges the fleet already has for this service.\n     Bind to them; do not draw a second version of the same box. \\`landscape.expects\\`\n     lists operations other services already call — your openapi.yaml owes them.\n     \\`landscape.instruction\\` is the write the fleet map still owes this service; it\n     is \\`null\\` once an element resolves to it AND at least one edge ANYWHERE in the\n     \\`architecture/\\` project touches that element (\\`landscape.touched\\`), and only\n     then — one edge closes the state, so draw every call in one pass.\n     \\`landscape.attested\\` lists the\n     calls \\`services/$1/model.likec4\\` already declares across its boundary — those\n     are the edges the map owes, collapsed to the service; an empty list on a\n     service with no model is not licence to invent one, and the instruction says so.\n   - \\`frontmatter\\` — what to put in the header of every markdown artifact.\n   - \\`checks[]\\` — what \\`loam validate\\` will run. \\`unchecked[]\\` — what it will not.\n2. Read \\`AGENTS.md\\` at the docs repo root, then walk the service — \\`walk[]\\` in the\n   same \\`adopt\\` output is the order, and it is an order, not a menu. Each stop\n   names what to open, what to take from it, and which artifacts it feeds\n   (\\`lands\\`). The first two stops fix what the service IS — how many processes,\n   built from what — before any surface is enumerated: an agent that opens the\n   HTTP routes first has already decided the service is an API by the time it\n   meets the scheduler, and the consumer group and the outbox never get written\n   down. Do not stop at the surface you recognise fastest.\n   \\`walkClose\\` is the question that ends it: **list the directories you did not\n   open.** Nothing downstream can find a service you documented a third of —\n   \\`api.ungoverned\\` grades the operations you WROTE, and is silent about the twelve\n   you never did.\n   **Keep a list of every path you actually open.** That list becomes \\`sources\\` —\n   written as files and directories, never glob patterns — and it is the only line\n   tying the document to the repository. Never pad it with paths you did not read:\n   it is a record, and \\`loam vouch\\` hashes exactly what it names.\n3. Write the artifacts under \\`services/$1/\\`, in the order the brief lists them, and\n   make the landscape edit the brief asks for — the element where none resolves, the\n   edges where the element stands alone, and the map's own housekeeping\n   \\`unchecked[]\\` names: a placeholder tag to clear, a curated view to add the\n   element to.\n   **Every edge you draw gets a relationship kind, and a direction you can\n   show.** \\`calls\\` is a request the code makes. \\`publishes\\` runs from the\n   producer to the topic and \\`delivers\\` from the topic to the consumer.\n   \\`reads\\`, \\`writes\\` and \\`readsWrites\\` are always written service \\`->\\` store,\n   with the arrowhead put where the data lands by the kind's style.\n   Take the direction from this service's code, from a configuration name that\n   says which side it is on (\\`*_PRODUCER_*\\`, \\`*_CONSUMER_*\\`, a consumer-group\n   id), or from its own \\`asyncapi.yaml\\` (\\`send\\` publishes, \\`receive\\` consumes).\n   Never take it from deployment configuration that only lists an address: that\n   says two things are connected and nothing more, so it is drawn \\`connects\\`.\n   You are reading the code now, so turn every \\`connects\\` edge that touches $1\n   into its real kind, and name in step 6 the ones the code did not settle. Use\n   the kinds the map's \\`specification\\` declares, and declare a missing one\n   there, once, in the same landscape edit. \\`loam instructions loam-drawing\\`\n   has the kinds, their styles and the views a person can read.\n   **model.likec4 EXTENDS the fleet map.** It declares no \\`specification\\` block and\n   no copy of anything the map already draws: its whole body is\n   \\`model { extend <fqn> { …containers… } }\\`, where \\`<fqn>\\` is the FULLY-QUALIFIED\n   id of the element bound to \\`services/$1/\\` (the brief's \\`landscape.elements\\` names\n   it; \\`extend orderService\\` resolves to nothing when the id is\n   \\`marketplace.orderService\\`). Kinds and tags come from\n   \\`architecture/landscape.likec4\\` — a kind you need and the map does not declare\n   (\\`element database\\`, \\`element queue\\`) is added THERE, once, in the same landscape\n   edit. Cross-boundary edges are written OUTSIDE the extend block, from the container\n   that makes the call to the other party's element as the map spells it; an element\n   this file declares outside its own is \\`c4.element-unowned\\` (warn), and which fix\n   applies depends on whose it is — a store or component this service OWNS belongs\n   INSIDE the \\`extend\\` block (its id becomes \\`<fqn>.<name>\\`), a system the service\n   merely reaches is declared in the map instead, and another service's internals\n   belong in that service's model. If you are DIFFING an existing model\n   that carries its own \\`specification\\`, leave it alone: that shape is still legal\n   and still parsed on its own, and \\`c4.declaration-diverged\\` is what reports where\n   its copies of the map's elements have drifted. Migrating one is the recipe in\n   SCHEMA.md, \"Two shapes of a service model\" — not something to do inside an\n   adoption you were not asked to widen.\n   A flow behind one of your arch.spec.md requirements — a \\`dynamic view\\`\n   over this service's own containers — goes in a \\`.likec4\\` beside model.likec4\n   (\\`services/$1/usecases/<name>.likec4\\` by convention; \\`views.likec4\\` reads the\n   same, because the renderer's per-service project reads every \\`.likec4\\` under the\n   directory and so does loam), tagged \\`#req-<Requirement-ID>\\` of a requirement in\n   this service's spec.md or arch.spec.md, with the tag declared in the map's\n   \\`specification\\` block or in a tags-only \\`specification { tag req-… }\\` beside the\n   \\`extend\\` — in exactly ONE of the two. Declared in both, the model's own project\n   holds the tag twice: the error lands on whichever document carries the second\n   declaration, as \\`c4.invalid\\` (an error, and the model's grading is suspended\n   behind it) when that is model.likec4, or as \\`usecase.flow-invalid\\` when it is the\n   sibling. Step 4 grades it. It never goes in \\`architecture/usecases/\\`,\n   which cannot see your containers and turns the whole fleet \\`landscape.invalid\\`; a\n   flow that crosses services goes there and is tagged \\`#cap-\\`. Never a \\`#cap-\\` tag\n   beside a model. Then run \\`loam subsystem sync\\` (from\n   this repo or the docs repo — it resolves \\`docsDir\\`): once the docs root carries\n   the \\`likec4.config.json\\` step 0's doctor asks for, it keeps that file's\n   \\`exclude\\` list covering exactly the service directories whose models stand alone —\n   so an extending model stays inside the root project, where it is the only place it\n   parses and where the renderer draws it beside the map — and writes\n   \\`services/<…>/<id>/likec4.config.json\\` beside each STANDALONE model that has none.\n   Both are loam's — never write one yourself, never list it in \\`sources\\`, never\n   diff it, never hand-edit the root \\`exclude\\`'s \\`services/\\` entries — and \\`sync\\`\n   leaves what it wrote untracked for you to commit. A repo whose models all extend\n   the map usually has nothing for \\`sync\\` to write here, and that is the healthy\n   state, not a skipped step.\n   Everything \\`status: draft\\`. Never write \\`last_verified\\`, \\`sources_digest\\`,\n   \\`content_digest\\` or \\`sources_files\\`. A spec.md whose frontmatter says\n   \\`adoption: partial\\` is one archived feature's slice written into this service\n   before anyone adopted it: keep every requirement in it, write the rest of the\n   service's behaviour around them from the code, and when the document describes\n   the service — not just that feature — DELETE the \\`adoption: partial\\` line. It is\n   the only thing that clears it; until then \\`loam list\\` keeps the service\n   \\`partial\\` and \\`loam status\\` keeps asking for this adoption (\\`next.adopt\\`).\n4. \\`loam validate --service $1 --json\\`. Fix every error. \\`c4.valid\\` reading\n   \"extends the fleet map\" is the confirmation that the model was read as one\n   document with the map; \\`c4.invalid\\` on this run means the model plus the map do\n   not parse together, and every error is YOURS even where the message names\n   \\`architecture/landscape.likec4\\` — the map parses clean on its own, or\n   \\`spine.landscape-invalid\\` would say so instead and this model could not be read\n   at all. \\`c4.element-unowned\\` (warn) is an element you declared outside the\n   element you extend — nest it inside the \\`extend\\` block if this service owns it,\n   declare it in the map if the service only reaches it. \\`sources.unvouched\\` is\n   expected on a fresh baseline — it closes when a person vouches, not when you do.\n   \\`sources.unwalked\\` is the walk graded against the repository: its \\`details\\` name\n   the top-level paths git tracks and \\`sources\\` never reached into. Treat each one\n   as a place to go back to, not as a line to silence — the fix is reading it, or\n   one sentence in step 6 saying why this document does not owe it.\n   \\`usecase.*\\` findings on this run are about the flows beside model.likec4:\n   \\`usecase.step-unbacked\\` is a hop no relationship in model.likec4 backs,\n   \\`usecase.step-contested\\` two edges backing one hop and naming different\n   operations (open the step's title with the operation id it means, then\n   punctuation),\n   \\`usecase.requirement-unresolved\\` a \\`#req-\\` tag naming no\n   \\`Requirement-ID:\\` of this service's spec.md or arch.spec.md,\n   \\`usecase.capability-unresolved\\` a \\`#cap-\\` tag beside a model (drop it — a\n   capability is claimed on the fleet map, never inside one service), and\n   \\`usecase.flow-invalid\\` a file beside the model that does not read — the flows\n   were not graded, the model still was. \\`usecase.step-unlinked\\` never fires on a hop\n   whose caller and provider resolve to the same service — a service owes no\n   operationId to itself — but a hop from such a flow into another service's element\n   (a stand-in model.likec4 declares for a sibling, with no \\`metadata { op }\\`) still\n   warns here, exactly as it does on the fleet map.\n5. \\`loam validate --all --json\\` in the docs repo. This is the run that grades the\n   fleet map: \\`landscape.service-unmodelled\\` means the element never landed,\n   \\`landscape.binding-unknown\\` / \\`landscape.binding-duplicate\\` mean it landed wrong,\n   and \\`landscape.missing\\` means there is no map at all. A baseline that passes step 4\n   and fails this one is documented and invisible.\n   \\`landscape.service-isolated\\` (a warning) means the element landed with no edge\n   anywhere in \\`architecture/\\` while \\`services/$1/model.likec4\\` declares calls across\n   its boundary — the map owes those edges. It goes quiet on the FIRST edge, so draw\n   every call the brief listed in one pass: nothing will name the ones you leave out.\n   A service whose model declares no such call and whose element\n   has no edge is SILENT here: \\`landscape.touched: false\\` in step 1's brief is the\n   only place that state is named, so read it before this run rather than hoping\n   for it in it.\n   Six warnings on this run are about the RENDERER's wiring rather than about any\n   document, and one command fixes four of them: \\`service.model-excluded\\` (the root\n   \\`likec4.config.json\\` excludes a directory holding a model that extends the map, so\n   the renderer never loads it), \\`service.model-unexcluded\\` (its mirror, and the most\n   damaging — a model that STANDS ALONE whose directory the root \\`exclude\\` does not\n   cover merges into the root project and duplicates every kind the map declares,\n   which blanks the whole project rather than one service),\n   \\`service.likec4-config-stray\\` (a project file beside an extending model, which\n   claims the model out of the root project),\n   \\`service.likec4-config-missing\\` (a model that stands alone with no project file of\n   its own) and, when the first four are clear, \\`c4.fleet-project-invalid\\` — every\n   document reads clean where loam grades it and the ONE project the renderer builds\n   out of the map plus every extending model does not parse, because something is\n   declared in two of them. The first four: run \\`loam subsystem sync\\` — it rewrites\n   the root \\`exclude\\`, writes the missing project file and DELETES the stray one. The\n   fifth is an authoring fix: the message names the file and line, and the answer is\n   to declare the tag or element once, in the map or in the single service that owns it.\n   A sixth reads the same list and is NOT one of sync's: \\`landscape.excluded\\` says the\n   root \\`exclude\\` covers \\`architecture/landscape.likec4\\` itself, so the renderer has no\n   map to draw at all and every extending model in the root project resolves against\n   nothing — delete or narrow that entry by hand, at the line the finding quotes. While\n   it stands, \\`c4.fleet-project-invalid\\` is not graded at all: that check reads the\n   renderer's project, so the one entry would come back once per model instead of once as\n   the cause. Fix it first, then re-run and read the fifth.\n   Done, stated once: step 4 clean when run from inside the service's own repo, this\n   run reporting no \\`landscape.*\\` finding, no \\`service.*\\` renderer warning and no\n   \\`c4.fleet-project-invalid\\`, and\n   step 1's brief re-run reporting \\`landscape.touched: true\\` — or, for a service that\n   truly makes and receives no call, a stated reason its element is edgeless.\n   The fleet run is never SILENT —\n   \\`sources.unverifiable-from-here\\` (severity ok) appears per service as a\n   confirmation, not work — so \"keep going until validation is quiet\" is the wrong\n   loop; the two runs are the test.\n6. Hand back, and say eight things:\n   - what you could not determine from the code;\n   - what the existing artifacts disagreed with;\n   - which parts you are least sure of;\n   - what you did not open — every path \\`sources.unwalked\\` named, with one line\n     each on why the baseline does not owe it. That list is the only account\n     anybody gets of how much of the service was actually read; loam can name the\n     paths, and it can never say whether skipping one was right;\n   - every edge touching the service that is still drawn \\`connects\\`, with what\n     would settle its direction. An unresolved edge looks finished on the map,\n     so this list is the one place that says it is not;\n   - **two counts per operation**: how many decisions its code makes — permission\n     checks, conditionally required fields, defaults and normalisations, refused\n     transitions — and how many scenarios you wrote for it.\n     \\`12 branches / 3 scenarios\\` is a fact a reader can act on; \"the\n     requirements look complete\" is not, and no check loam has can tell the two\n     apart;\n   - **how well this service is covered by its own tests**, and how many of them\n     became scenarios. Say the number the service's own coverage tooling\n     reports, and where you read it. This is the ceiling on the whole baseline:\n     a well-covered service can be documented from evidence, and a service with\n     almost no tests can only be documented from a reading of its code, which is\n     a weaker document however carefully it is written. Nothing in loam can\n     compute this — say it, or nobody ever knows which kind they are holding;\n   - **three behaviours this service has that your documents do not describe.**\n     Not \"is this enough\" — that question is answered yes by every agent that\n     ever wrote a baseline, including the ones that documented a third of a\n     service, because the only thing it can be answered against is the document\n     itself. Name three. If you looked for three and found none, say exactly\n     that: it is a claim a reviewer can go and check, which \"it is complete\"\n     is not.\n   Then a human runs \\`loam vouch --service $1\\` in the service's own repo.\n\nAn empty docs repo's \\`loam status --json\\` names this recipe's own states as its\nfirst-hour ladder: \\`next.author-landscape\\` (the fleet map is missing, or still the\nscaffold's untouched bytes — step 3's landscape edit is what discharges it),\n\\`next.bind-service\\` (no service repository is wired to the fleet yet — step 0) and\n\\`next.adopt-first\\` (services/ is empty — this protocol, from step 1). Landing on\none of those codes means: run this recipe, starting at the step it points at.\n\nWhere the code does not say, write that it does not say. A confident sentence about\nbehaviour nobody can find is the one failure mode none of loam's checks can catch.\n`,\n};\n"]}