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

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

@@ -0,0 +1,133 @@
+/** 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`",
+        "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:
+   \`loam init --docs <path-to-docs-repo> --service $1\` (add \`--create\` ONLY if the
+   docs repo does not exist yet), 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.
+   - \`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 only then.
+   - \`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.
+   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
+   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.
+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 —
+   \`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 seven 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;
+   - **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,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"]}