@ybotok/loam 0.2.0-alpha.4 → 0.2.0-alpha.6

package/dist/core/agent/support/report.js

@@ -63,11 +63,31 @@ more for secrets before handing it back.
 
 ## Write one separate report
 
-Create \`loam-reports/YYYY-MM-DD-<short-slug>.md\` at the current repository root. Use a short neutral
-slug based on the symptom, not a customer, person or secret. Never overwrite a different incident;
-add a numeric suffix when the path exists. Reports are ordinary project files so the team can
-review or commit them deliberately, but do not upload, submit an issue, send telemetry, or contact
-any service automatically.
+Create \`loam-reports/NNN-YYYY-MM-DD-<short-slug>.md\` in the directory holding the \`loam.json\` that
+resolved — or, when a \`loam.json\` was found but does not parse, beside that file, so a report about
+the broken config joins the corpus already there; only when there is no config file at or above you
+is it the directory you run in.
+\`loam doctor --json\` hands you that whole directory — that root WITH \`loam-reports/\`
+already on the end — as \`reports.dir\`: write inside the path it gives, never joined onto
+\`loam-reports/\` a second time. \`NNN\` is an ordinal of at least three digits, zero-padded, one more
+than the highest already in that directory — read \`reports.next\` from the same output, which says
+\`001\` when the directory is empty or absent, and widens past three digits rather than reusing a
+number once the corpus gets there. Use a short neutral slug based on the symptom, not a customer,
+person or secret. Never
+overwrite a different incident: a path that already exists means a concurrent report claimed that
+ordinal, so take the next one rather than adding a suffix. That check is on the PATH, and the
+promise is about the ordinal, so re-run \`loam doctor --json\` after writing: if two entries carry
+the same \`ordinal\`, the one with the later \`Recorded\` timestamp renames itself to the next free
+number. The ordinal is the report's handle —
+cite one by its number in a commit message, an issue, or another report's cross-references, and
+never by filename, which is free to be renamed. The ordinal is unique within that directory, not
+across a fleet: a service repository and the docs repository each number their own, so when two
+repositories are in play cite \`<repo>/loam-reports/NNN\`.
+
+Reports are ordinary project files so the team can review or commit them deliberately, but
+do not upload, submit an issue, send telemetry, or contact any service automatically.
+\`loam doctor\` reads the directory — how many reports it holds, how many are in each status, and
+which ordinal comes next — and that is a local read of local files: nothing is transmitted.
 
 Use this shape, omitting only fields that truly cannot be known and marking them \`not collected\`:
 
@@ -75,6 +95,7 @@ Use this shape, omitting only fields that truly cannot be known and marking them
 
     - Recorded: <ISO-8601 timestamp>
     - Classification: <one value above>
+    - Status: open
     - Repository role: <docs | service | combined | unresolved>
     - loam version: <version>
     - Entry point: <chat command, skill, or CLI command; sanitized>
@@ -91,6 +112,19 @@ Use this shape, omitting only fields that truly cannot be known and marking them
     ## Missing evidence
     ## Sanitization
 
+\`Status\` is written as \`open\` and stays the report's own record of where it got to. The vocabulary
+is \`open\`, \`sent\` (handed to loam's author — the person forwarding a report sets this, never the
+agent writing it), \`fixed in <version>\`, and \`superseded by <NNN>\` naming the report that
+replaced this one. Close a report by editing its own \`Status\` line: there is no index to keep in
+step, and \`loam doctor\` counts the directory by reading that line's first word, so
+\`fixed in 0.2.0-alpha.5\` counts as fixed. It reads that line from the HEADER FIELD BLOCK only —
+the lines above the first \`##\` heading, quoted code skipped in either markdown spelling: a fence
+(closed only by a run of the same character at least as long as the one that opened it, so a
+\`\`\` inside a \`\`\`\` block is content) and an indented block, which is the shape THIS template is
+printed in above. So a report that quotes this template, however it quotes it, still counts as
+whatever its own header says. A report written before this
+field existed has no \`Status\` line and counts as unstated.
+
 In \`Machine contract\`, include exit code plus the stable envelope fields and relevant finding
 codes/locations; do not paste an entire large JSON payload. In \`Sanitization\`, list the kinds of
 values removed without revealing them. If no workaround is known, say so rather than inventing one.

package/dist/core/agent/support/report.js.map

@@ -1 +1 @@
-{"version":3,"file":"report.js","sourceRoot":"","sources":["../../../../src/core/agent/support/report.ts"],"names":[],"mappings":"AAEA;;;;GAIG;AACH,MAAM,CAAC,MAAM,WAAW,GAAmB;IACzC,IAAI,EAAE,aAAa;IACnB,WAAW,EACT,uFAAuF;IACzF,YAAY,EAAE,EAAE;IAChB,OAAO,EACL,oOAAoO;IACtO,UAAU,EAAE,+BAA+B;IAC3C,YAAY,EAAE,EAAE;IAChB,KAAK,EAAE;QACL,+EAA+E;QAC/E,iFAAiF;QACjF,yFAAyF;QACzF,gFAAgF;QAChF,wFAAwF;KACzF;IACD,IAAI,EAAE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAiFP;CACA,CAAC","sourcesContent":["import type { CommandContent } from \"../contract.js\";\n\n/**\n * The incident-reporting protocol: preserve a small, sanitized reproducer when\n * loam or its agent integration behaves unexpectedly, without turning loam\n * into a telemetry service or retrying a risky write.\n */\nexport const LOAM_REPORT: CommandContent = {\n  name: \"loam-report\",\n  description:\n    \"Record unexpected loam or agent behavior as a sanitized, reproducible Markdown report\",\n  argumentHint: \"\",\n  purpose:\n    \"Collect one unexpected loam or agent-integration incident into a separate, reviewable Markdown file. This is local diagnostics only: redact secrets, never upload automatically, and never repeat a writer merely to reproduce it.\",\n  invocation: \"loam instructions loam-report\",\n  placeholders: [],\n  spine: [\n    \"preserve the user's original symptom and expected result before investigating\",\n    \"collect the binary version, wiring diagnosis and the smallest safe reproduction\",\n    \"classify the failure without repairing, retrying a writer or changing project documents\",\n    \"sanitize commands, paths and output, then write one report under loam-reports/\",\n    \"hand back the report path, classification and any evidence that could not be collected\",\n  ],\n  body: `Record one incident where loam, a generated command/skill, or the agent following it\nbehaved unexpectedly. The result is a local diagnostic document, not a repair and not telemetry.\nDo not change architecture/spec files while collecting it.\n\n## Preserve the symptom first\n\nBefore running anything, write down the user's original request, what they expected, what actually\nhappened, the command or chat entry point involved, and whether any files may already have changed.\nDo not improve or reinterpret the failing command yet: a cleaned-up command is not a reproduction.\n\nClassify the incident as one of these, using \\`inconclusive\\` until the evidence supports another:\n\n- \\`loam-product\\` — the binary violated its documented contract or produced internally inconsistent output;\n- \\`project-data\\` — the binary correctly reported invalid, incomplete or stale repository documents;\n- \\`agent-workflow\\` — the generated command/skill was missing, stale, misrouted or followed incorrectly;\n- \\`host-infrastructure\\` — permissions, filesystem, process, shell or tool-host behavior prevented the run;\n- \\`inconclusive\\` — the available evidence does not distinguish the above.\n\n## Collect only safe evidence\n\n1. Run \\`loam --version\\` and record the result.\n2. Run \\`loam doctor --json\\`. If it succeeds, keep \\`healthy\\`, the finding codes and their structured\n   locations/fixes, the resolved repository role, and the write-path state. If it refuses, keep\n   \\`error.code\\` and the sanitized message. Do not apply the fixes during reporting.\n3. When the repository is wired, run \\`loam status --json\\` and keep only the state and next-action\n   rows relevant to this incident. A refusal is evidence too; keep its \\`error.code\\`.\n4. Re-run the original operation only when it is read-only and safe. Never re-run \\`init\\`, \\`new\\`,\n   \\`rebase\\`, \\`subsystem\\`, \\`archive\\`, \\`unarchive\\`, \\`vouch\\`, a recording form of \\`verify\\`, or\n   any other writer merely to make it fail twice. For a writer, record its original exit/output and\n   inspect \\`doctor\\`, \\`status\\` and version only. Do not repair, roll back or delete anything unless\n   the user separately asks for that action.\n5. Prefer the JSON envelope: record \\`contractVersion\\`, \\`ok\\`, \\`command\\`, \\`error.code\\`, finding\n   codes and \\`locations[]\\`. Quote only the smallest stdout/stderr excerpt that demonstrates the\n   symptom. State what was omitted.\n\n## Sanitize before writing\n\nNever include credentials, tokens, cookies, authorization headers, private keys, environment dumps,\nor values of variables whose names contain \\`TOKEN\\`, \\`SECRET\\`, \\`PASSWORD\\`, \\`AUTH\\`, \\`COOKIE\\` or\n\\`KEY\\`. Replace each value with \\`<redacted>\\`. Replace the user's home directory with \\`<home>\\` and\nprefer repository-relative paths. Do not copy source files, architecture/spec bodies, or a complete\ncommand output when a code and short excerpt prove the same fact. Review the finished report once\nmore for secrets before handing it back.\n\n## Write one separate report\n\nCreate \\`loam-reports/YYYY-MM-DD-<short-slug>.md\\` at the current repository root. Use a short neutral\nslug based on the symptom, not a customer, person or secret. Never overwrite a different incident;\nadd a numeric suffix when the path exists. Reports are ordinary project files so the team can\nreview or commit them deliberately, but do not upload, submit an issue, send telemetry, or contact\nany service automatically.\n\nUse this shape, omitting only fields that truly cannot be known and marking them \\`not collected\\`:\n\n    # loam problem report: <short title>\n\n    - Recorded: <ISO-8601 timestamp>\n    - Classification: <one value above>\n    - Repository role: <docs | service | combined | unresolved>\n    - loam version: <version>\n    - Entry point: <chat command, skill, or CLI command; sanitized>\n    - Side effects observed: <none known | paths changed | unknown>\n\n    ## Summary\n    ## Expected\n    ## Actual\n    ## Minimal safe reproduction\n    ## Machine contract\n    ## Doctor and status evidence\n    ## Files changed or write state\n    ## Workaround\n    ## Missing evidence\n    ## Sanitization\n\nIn \\`Machine contract\\`, include exit code plus the stable envelope fields and relevant finding\ncodes/locations; do not paste an entire large JSON payload. In \\`Sanitization\\`, list the kinds of\nvalues removed without revealing them. If no workaround is known, say so rather than inventing one.\n\nFinish by telling the user the report path, classification, whether project files changed, and which\nevidence was unavailable. Keep diagnosis separate from certainty: a plausible cause belongs under\n\\`Summary\\` as a hypothesis until the reproduction proves it.\n`,\n};\n"]}
+{"version":3,"file":"report.js","sourceRoot":"","sources":["../../../../src/core/agent/support/report.ts"],"names":[],"mappings":"AAEA;;;;GAIG;AACH,MAAM,CAAC,MAAM,WAAW,GAAmB;IACzC,IAAI,EAAE,aAAa;IACnB,WAAW,EACT,uFAAuF;IACzF,YAAY,EAAE,EAAE;IAChB,OAAO,EACL,oOAAoO;IACtO,UAAU,EAAE,+BAA+B;IAC3C,YAAY,EAAE,EAAE;IAChB,KAAK,EAAE;QACL,+EAA+E;QAC/E,iFAAiF;QACjF,yFAAyF;QACzF,gFAAgF;QAChF,wFAAwF;KACzF;IACD,IAAI,EAAE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAmHP;CACA,CAAC","sourcesContent":["import type { CommandContent } from \"../contract.js\";\n\n/**\n * The incident-reporting protocol: preserve a small, sanitized reproducer when\n * loam or its agent integration behaves unexpectedly, without turning loam\n * into a telemetry service or retrying a risky write.\n */\nexport const LOAM_REPORT: CommandContent = {\n  name: \"loam-report\",\n  description:\n    \"Record unexpected loam or agent behavior as a sanitized, reproducible Markdown report\",\n  argumentHint: \"\",\n  purpose:\n    \"Collect one unexpected loam or agent-integration incident into a separate, reviewable Markdown file. This is local diagnostics only: redact secrets, never upload automatically, and never repeat a writer merely to reproduce it.\",\n  invocation: \"loam instructions loam-report\",\n  placeholders: [],\n  spine: [\n    \"preserve the user's original symptom and expected result before investigating\",\n    \"collect the binary version, wiring diagnosis and the smallest safe reproduction\",\n    \"classify the failure without repairing, retrying a writer or changing project documents\",\n    \"sanitize commands, paths and output, then write one report under loam-reports/\",\n    \"hand back the report path, classification and any evidence that could not be collected\",\n  ],\n  body: `Record one incident where loam, a generated command/skill, or the agent following it\nbehaved unexpectedly. The result is a local diagnostic document, not a repair and not telemetry.\nDo not change architecture/spec files while collecting it.\n\n## Preserve the symptom first\n\nBefore running anything, write down the user's original request, what they expected, what actually\nhappened, the command or chat entry point involved, and whether any files may already have changed.\nDo not improve or reinterpret the failing command yet: a cleaned-up command is not a reproduction.\n\nClassify the incident as one of these, using \\`inconclusive\\` until the evidence supports another:\n\n- \\`loam-product\\` — the binary violated its documented contract or produced internally inconsistent output;\n- \\`project-data\\` — the binary correctly reported invalid, incomplete or stale repository documents;\n- \\`agent-workflow\\` — the generated command/skill was missing, stale, misrouted or followed incorrectly;\n- \\`host-infrastructure\\` — permissions, filesystem, process, shell or tool-host behavior prevented the run;\n- \\`inconclusive\\` — the available evidence does not distinguish the above.\n\n## Collect only safe evidence\n\n1. Run \\`loam --version\\` and record the result.\n2. Run \\`loam doctor --json\\`. If it succeeds, keep \\`healthy\\`, the finding codes and their structured\n   locations/fixes, the resolved repository role, and the write-path state. If it refuses, keep\n   \\`error.code\\` and the sanitized message. Do not apply the fixes during reporting.\n3. When the repository is wired, run \\`loam status --json\\` and keep only the state and next-action\n   rows relevant to this incident. A refusal is evidence too; keep its \\`error.code\\`.\n4. Re-run the original operation only when it is read-only and safe. Never re-run \\`init\\`, \\`new\\`,\n   \\`rebase\\`, \\`subsystem\\`, \\`archive\\`, \\`unarchive\\`, \\`vouch\\`, a recording form of \\`verify\\`, or\n   any other writer merely to make it fail twice. For a writer, record its original exit/output and\n   inspect \\`doctor\\`, \\`status\\` and version only. Do not repair, roll back or delete anything unless\n   the user separately asks for that action.\n5. Prefer the JSON envelope: record \\`contractVersion\\`, \\`ok\\`, \\`command\\`, \\`error.code\\`, finding\n   codes and \\`locations[]\\`. Quote only the smallest stdout/stderr excerpt that demonstrates the\n   symptom. State what was omitted.\n\n## Sanitize before writing\n\nNever include credentials, tokens, cookies, authorization headers, private keys, environment dumps,\nor values of variables whose names contain \\`TOKEN\\`, \\`SECRET\\`, \\`PASSWORD\\`, \\`AUTH\\`, \\`COOKIE\\` or\n\\`KEY\\`. Replace each value with \\`<redacted>\\`. Replace the user's home directory with \\`<home>\\` and\nprefer repository-relative paths. Do not copy source files, architecture/spec bodies, or a complete\ncommand output when a code and short excerpt prove the same fact. Review the finished report once\nmore for secrets before handing it back.\n\n## Write one separate report\n\nCreate \\`loam-reports/NNN-YYYY-MM-DD-<short-slug>.md\\` in the directory holding the \\`loam.json\\` that\nresolved — or, when a \\`loam.json\\` was found but does not parse, beside that file, so a report about\nthe broken config joins the corpus already there; only when there is no config file at or above you\nis it the directory you run in.\n\\`loam doctor --json\\` hands you that whole directory — that root WITH \\`loam-reports/\\`\nalready on the end — as \\`reports.dir\\`: write inside the path it gives, never joined onto\n\\`loam-reports/\\` a second time. \\`NNN\\` is an ordinal of at least three digits, zero-padded, one more\nthan the highest already in that directory — read \\`reports.next\\` from the same output, which says\n\\`001\\` when the directory is empty or absent, and widens past three digits rather than reusing a\nnumber once the corpus gets there. Use a short neutral slug based on the symptom, not a customer,\nperson or secret. Never\noverwrite a different incident: a path that already exists means a concurrent report claimed that\nordinal, so take the next one rather than adding a suffix. That check is on the PATH, and the\npromise is about the ordinal, so re-run \\`loam doctor --json\\` after writing: if two entries carry\nthe same \\`ordinal\\`, the one with the later \\`Recorded\\` timestamp renames itself to the next free\nnumber. The ordinal is the report's handle —\ncite one by its number in a commit message, an issue, or another report's cross-references, and\nnever by filename, which is free to be renamed. The ordinal is unique within that directory, not\nacross a fleet: a service repository and the docs repository each number their own, so when two\nrepositories are in play cite \\`<repo>/loam-reports/NNN\\`.\n\nReports are ordinary project files so the team can review or commit them deliberately, but\ndo not upload, submit an issue, send telemetry, or contact any service automatically.\n\\`loam doctor\\` reads the directory — how many reports it holds, how many are in each status, and\nwhich ordinal comes next — and that is a local read of local files: nothing is transmitted.\n\nUse this shape, omitting only fields that truly cannot be known and marking them \\`not collected\\`:\n\n    # loam problem report: <short title>\n\n    - Recorded: <ISO-8601 timestamp>\n    - Classification: <one value above>\n    - Status: open\n    - Repository role: <docs | service | combined | unresolved>\n    - loam version: <version>\n    - Entry point: <chat command, skill, or CLI command; sanitized>\n    - Side effects observed: <none known | paths changed | unknown>\n\n    ## Summary\n    ## Expected\n    ## Actual\n    ## Minimal safe reproduction\n    ## Machine contract\n    ## Doctor and status evidence\n    ## Files changed or write state\n    ## Workaround\n    ## Missing evidence\n    ## Sanitization\n\n\\`Status\\` is written as \\`open\\` and stays the report's own record of where it got to. The vocabulary\nis \\`open\\`, \\`sent\\` (handed to loam's author — the person forwarding a report sets this, never the\nagent writing it), \\`fixed in <version>\\`, and \\`superseded by <NNN>\\` naming the report that\nreplaced this one. Close a report by editing its own \\`Status\\` line: there is no index to keep in\nstep, and \\`loam doctor\\` counts the directory by reading that line's first word, so\n\\`fixed in 0.2.0-alpha.5\\` counts as fixed. It reads that line from the HEADER FIELD BLOCK only —\nthe lines above the first \\`##\\` heading, quoted code skipped in either markdown spelling: a fence\n(closed only by a run of the same character at least as long as the one that opened it, so a\n\\`\\`\\` inside a \\`\\`\\`\\` block is content) and an indented block, which is the shape THIS template is\nprinted in above. So a report that quotes this template, however it quotes it, still counts as\nwhatever its own header says. A report written before this\nfield existed has no \\`Status\\` line and counts as unstated.\n\nIn \\`Machine contract\\`, include exit code plus the stable envelope fields and relevant finding\ncodes/locations; do not paste an entire large JSON payload. In \\`Sanitization\\`, list the kinds of\nvalues removed without revealing them. If no workaround is known, say so rather than inventing one.\n\nFinish by telling the user the report path, classification, whether project files changed, and which\nevidence was unavailable. Keep diagnosis separate from certainty: a plausible cause belongs under\n\\`Summary\\` as a hypothesis until the reproduction proves it.\n`,\n};\n"]}

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

@@ -10,7 +10,7 @@ export const LOAM_ADOPT = {
         "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`",
+        "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",
     ],
@@ -43,6 +43,13 @@ thin baseline that validates is thin, not done.
      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.
@@ -50,7 +57,13 @@ thin baseline that validates is thin, not done.
      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 only then.
+     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
@@ -70,22 +83,128 @@ thin baseline that validates is thin, not done.
    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.
+   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.
+   **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\`.
-4. \`loam validate --service $1 --json\`. Fix every error. \`sources.unvouched\` is
+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, \`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.
-   Done, stated once: step 4 clean when run from inside the service's own repo, and
-   this run reporting no \`landscape.*\` finding. The fleet run is never SILENT —
+   \`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.

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

@@ -1 +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,iDAAiD;QACjD,kIAAkI;QAClI,yNAAyN;KAC1N;IACD,IAAI,EAAE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAkHP;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`\",\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:\n   \\`loam init --docs <path-to-docs-repo> --service $1\\` (add \\`--create\\` ONLY if the\n   docs repo does not exist yet), 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   - \\`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 only then.\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.\n   Everything \\`status: draft\\`. Never write \\`last_verified\\`, \\`sources_digest\\`,\n   \\`content_digest\\` or \\`sources_files\\`.\n4. \\`loam validate --service $1 --json\\`. Fix every error. \\`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.\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   Done, stated once: step 4 clean when run from inside the service's own repo, and\n   this run reporting no \\`landscape.*\\` finding. 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 seven 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   - **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"]}
+{"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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAyOP;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:\n   \\`loam init --docs <path-to-docs-repo> --service $1\\` (add \\`--create\\` ONLY if the\n   docs repo does not exist yet), 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   **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\\`.\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, \\`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 seven 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   - **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"]}