@ybotok/loam 0.2.0-alpha.1 → 0.2.0-alpha.13

package/dist/cli.js

@@ -11,6 +11,7 @@ import { registerShow } from "./commands/show/show.js";
 import { registerStatus } from "./commands/status/status.js";
 import { registerSubsystem } from "./commands/subsystem/subsystem.js";
 import { registerDelta } from "./commands/delta/delta.js";
+import { registerTasks } from "./commands/tasks/tasks.js";
 import { registerDiff } from "./commands/diff/diff.js";
 import { registerGherkin } from "./commands/gherkin/gherkin.js";
 import { registerRebase } from "./commands/rebase/rebase.js";
@@ -30,7 +31,7 @@ import { registerOpen } from "./commands/open.js";
 import { registerInstructions } from "./commands/instructions.js";
 import { registerExplain } from "./commands/explain/explain.js";
 import { registerMigrateOpenSpec } from "./commands/migrate-openspec/migrate-openspec.js";
-import { emitJsonError } from "./core/envelope/json.js";
+import { emitJsonError, sayExplain } from "./core/envelope/json.js";
 import { LOAM_VERSION } from "./core/envelope/version.js";
 /**
  * The whole CLI surface, as a program nobody has parsed yet.
@@ -69,6 +70,7 @@ export function buildProgram() {
     registerStatus(program);
     registerSubsystem(program);
     registerDelta(program);
+    registerTasks(program);
     registerDiff(program);
     registerGherkin(program);
     registerRebase(program);
@@ -93,10 +95,10 @@ export function buildProgram() {
  * The two lines under the command list: where to start, and what to run when
  * lost.
  *
- * {@link HELP_GROUPS} does nearly all of the orienting work — twenty-nine
+ * {@link HELP_GROUPS} does nearly all of the orienting work — thirty
  * commands under seven headings, in the order of the work — but it stops one
  * step short of the two facts a newcomer does not have. Nothing on the page
- * said that `init` must run before any of the other twenty-eight, and nothing
+ * said that `init` must run before any of the others, and nothing
  * named the command that answers "what now"; the last thing a first
  * `loam --help` printed was `help [command]`.
  *
@@ -123,7 +125,7 @@ export const HELP_EPILOG = [
  * protocols (`loam instructions`) rather than inventing a second taxonomy, so a
  * reader who has met one has met the other.
  *
- * Twenty-nine commands printed as one flat registration-ordered list tells a
+ * Thirty commands printed as one flat registration-ordered list tells a
  * new reader nothing about which four to run first. NOTHING IS HIDDEN — a
  * hidden command is a command an agent cannot discover, and every one of these
  * still parses, still appears, and still carries the same flags. This is
@@ -135,7 +137,7 @@ const HELP_GROUPS = {
     explore: "Read the fleet", context: "Read the fleet", dependencies: "Read the fleet",
     explain: "Read the fleet", instructions: "Read the fleet", steps: "Read the fleet",
     adopt: "Adopt what exists", vouch: "Adopt what exists",
-    new: "Change it", delta: "Change it", gherkin: "Change it", rebase: "Change it",
+    new: "Change it", delta: "Change it", tasks: "Change it", gherkin: "Change it", rebase: "Change it",
     subsystem: "Change it",
     validate: "Check it", diff: "Check it", verify: "Check it", gate: "Check it",
     archive: "Ship it", unarchive: "Ship it",
@@ -144,7 +146,7 @@ const HELP_GROUPS = {
 /**
  * Apply {@link HELP_GROUPS}, and FAIL CLOSED on a command it does not name.
  *
- * The throw is the point. A thirtieth command added without a heading would
+ * The throw is the point. A thirty-first command added without a heading would
  * otherwise land silently in an "unclassified" bucket at the bottom of the
  * page, which is the drift this whole file's neighbours are written to prevent;
  * `test/help-groups.test.ts` catches it at gate time, and this catches it the
@@ -162,6 +164,19 @@ function groupCommands(program) {
 }
 /** CommanderError codes whose output (already printed) is the point, not a failure to wrap. */
 const PASS_THROUGH = new Set(["commander.help", "commander.helpDisplayed", "commander.version"]);
+/**
+ * What a text-mode usage error prints under commander's own diagnostic: the
+ * fix and the stable code, the two lines every other refusal carries through
+ * `fail`. Without them `loam diff` with no `--base` printed commander's one
+ * sentence and nothing else — the only refusals in the CLI a person could not
+ * look up, while `--json` already reported them as `invalid-option`.
+ */
+function sayUsageFix(program) {
+    const name = process.argv.slice(2).find((token) => program.commands.some((c) => c.name() === token));
+    const help = name === undefined ? "`loam --help` lists the commands" : `\`loam ${name} --help\` lists the arguments and options it takes`;
+    console.error(`Fix the invocation: ${help}.`);
+    sayExplain("invalid-option");
+}
 function main() {
     const program = buildProgram();
     // Set once a command's action actually runs: every subcommand declares its own
@@ -194,8 +209,11 @@ function main() {
             // Anything else is a usage error (unknown option/command, missing or
             // invalid argument). Commander has already printed its diagnostic to
             // stderr, and that line stays: the invariant below is about stdout only.
-            if (!PASS_THROUGH.has(err.code) && jsonRequested()) {
-                emitJsonError("invalid-option", err.message.replace(/^error: /, ""));
+            if (!PASS_THROUGH.has(err.code)) {
+                if (jsonRequested())
+                    emitJsonError("invalid-option", err.message.replace(/^error: /, ""));
+                else
+                    sayUsageFix(program);
             }
             process.exitCode = err.exitCode;
             return;

package/dist/cli.js.map

@@ -1 +1 @@
-{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"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","sourcesContent":["#!/usr/bin/env node\nimport { Command, CommanderError } from \"commander\";\nimport { realpathSync } from \"node:fs\";\nimport { fileURLToPath } from \"node:url\";\nimport { registerInit } from \"./commands/init/init.js\";\nimport { registerAdopt } from \"./commands/adopt/adopt.js\";\nimport { registerList } from \"./commands/list/list.js\";\nimport { registerNew } from \"./commands/new/new.js\";\nimport { registerSeed } from \"./commands/seed/seed.js\";\nimport { registerShow } from \"./commands/show/show.js\";\nimport { registerStatus } from \"./commands/status/status.js\";\nimport { registerSubsystem } from \"./commands/subsystem/subsystem.js\";\nimport { registerDelta } from \"./commands/delta/delta.js\";\nimport { registerDiff } from \"./commands/diff/diff.js\";\nimport { registerGherkin } from \"./commands/gherkin/gherkin.js\";\nimport { registerRebase } from \"./commands/rebase/rebase.js\";\nimport { registerArchive } from \"./commands/archive/archive.js\";\nimport { registerUnarchive } from \"./commands/unarchive/unarchive.js\";\nimport { registerValidate } from \"./commands/validate/validate.js\";\nimport { registerVerify } from \"./commands/verify/verify.js\";\nimport { registerVouch } from \"./commands/vouch/vouch.js\";\nimport { registerGate } from \"./commands/gate/gate.js\";\nimport { registerDoctor } from \"./commands/doctor.js\";\nimport { registerDependencies } from \"./commands/dependencies.js\";\nimport { registerSteps } from \"./commands/steps/steps.js\";\nimport { registerExplore } from \"./commands/explore.js\";\nimport { registerContext } from \"./commands/context/context.js\";\nimport { registerMcp } from \"./commands/mcp/mcp.js\";\nimport { registerOpen } from \"./commands/open.js\";\nimport { registerInstructions } from \"./commands/instructions.js\";\nimport { registerExplain } from \"./commands/explain/explain.js\";\nimport { registerMigrateOpenSpec } from \"./commands/migrate-openspec/migrate-openspec.js\";\nimport { emitJsonError } from \"./core/envelope/json.js\";\nimport { LOAM_VERSION } from \"./core/envelope/version.js\";\n\n/**\n * The whole CLI surface, as a program nobody has parsed yet.\n *\n * Exported because loam PRINTS commands — every `loam …` in AGENTS.md, in the\n * generated command and skill bodies, in a `doctor` finding's `fix` and in a\n * `status` next[] step is an instruction somebody (usually an agent) will type\n * back. The only way to prove one of those parses is to hand it to the program\n * that would receive it; a second copy of the registrations in a test agrees\n * with itself and with nothing else, which is exactly how\n * `Run \\`loam adopt <id>\\`` shipped as the first instruction a bound service\n * repo received. `test/agent-commands-runnable.test.ts` is the consumer.\n */\nexport function buildProgram(): Command {\n  const program = new Command();\n\n  program\n    .name(\"loam\")\n    .description(\"Architecture-first semantic integrity and change governance for evolving software systems\")\n    .version(LOAM_VERSION)\n    // The blank line is part of the attachment, not part of the text: commander\n    // writes this straight under the `Commands:` block, and two sentences flush\n    // against `help [command]` read as two more commands.\n    .addHelpText(\"after\", `\\n${HELP_EPILOG}`);\n\n  // Make commander throw a CommanderError instead of process.exit()ing, so a\n  // usage error (mistyped flag, unknown command) can still honour the envelope\n  // invariant in the catch below instead of dying with an empty stdout.\n  program.exitOverride();\n\n  registerInit(program);\n  registerAdopt(program);\n  registerList(program);\n  registerExplore(program);\n  registerContext(program);\n  registerNew(program);\n  registerSeed(program);\n  registerShow(program);\n  registerStatus(program);\n  registerSubsystem(program);\n  registerDelta(program);\n  registerDiff(program);\n  registerGherkin(program);\n  registerRebase(program);\n  registerArchive(program);\n  registerUnarchive(program);\n  registerValidate(program);\n  registerVerify(program);\n  registerVouch(program);\n  registerGate(program);\n  registerDoctor(program);\n  registerDependencies(program);\n  registerSteps(program);\n  registerMcp(program);\n  registerInstructions(program);\n  registerExplain(program);\n  registerOpen(program);\n  registerMigrateOpenSpec(program);\n\n  groupCommands(program);\n\n  return program;\n}\n\n/**\n * The two lines under the command list: where to start, and what to run when\n * lost.\n *\n * {@link HELP_GROUPS} does nearly all of the orienting work — twenty-nine\n * commands under seven headings, in the order of the work — but it stops one\n * step short of the two facts a newcomer does not have. Nothing on the page\n * said that `init` must run before any of the other twenty-eight, and nothing\n * named the command that answers \"what now\"; the last thing a first\n * `loam --help` printed was `help [command]`.\n *\n * Two lines, and no more, because the grouping is what does the work and a\n * paragraph here would compete with it.\n *\n * Both lines name a command that PARSES, and that is not a style rule:\n * `test/agent-commands-runnable.test.ts` takes this constant BY IMPORT and\n * hands both invocations to the real program, exactly as it does the `init`\n * first-hour lines. `loam init --create` is the form that works with no prior\n * knowledge — bare `loam init` defaults `--docs` to a `.loam-docs` that does\n * not exist yet and refuses, which is correct for a repo joining an existing\n * docs repo and wrong as the first thing a newcomer is told to type.\n */\nexport const HELP_EPILOG = [\n  \"New here? Run `loam init --create` first — every other command needs the docs repo it writes.\",\n  \"Lost? Run `loam doctor` — it prints the state, the resolved path, the finding code and a `fix:` line.\",\n].join(\"\\n\");\n\n/**\n * Which heading each command sits under in `loam --help`.\n *\n * The order is the order of the work: wire the repo, read the fleet, adopt what\n * exists, change it, check it, ship it. It mirrors the six shipped workflow\n * protocols (`loam instructions`) rather than inventing a second taxonomy, so a\n * reader who has met one has met the other.\n *\n * Twenty-nine commands printed as one flat registration-ordered list tells a\n * new reader nothing about which four to run first. NOTHING IS HIDDEN — a\n * hidden command is a command an agent cannot discover, and every one of these\n * still parses, still appears, and still carries the same flags. This is\n * typography, not surface.\n */\nconst HELP_GROUPS: Record<string, string> = {\n  init: \"Set up\", seed: \"Set up\", doctor: \"Set up\", open: \"Set up\", mcp: \"Set up\",\n  list: \"Read the fleet\", status: \"Read the fleet\", show: \"Read the fleet\",\n  explore: \"Read the fleet\", context: \"Read the fleet\", dependencies: \"Read the fleet\",\n  explain: \"Read the fleet\", instructions: \"Read the fleet\", steps: \"Read the fleet\",\n  adopt: \"Adopt what exists\", vouch: \"Adopt what exists\",\n  new: \"Change it\", delta: \"Change it\", gherkin: \"Change it\", rebase: \"Change it\",\n  subsystem: \"Change it\",\n  validate: \"Check it\", diff: \"Check it\", verify: \"Check it\", gate: \"Check it\",\n  archive: \"Ship it\", unarchive: \"Ship it\",\n  \"audit-openspec\": \"Migrate\", \"migrate-openspec\": \"Migrate\",\n};\n\n/**\n * Apply {@link HELP_GROUPS}, and FAIL CLOSED on a command it does not name.\n *\n * The throw is the point. A thirtieth command added without a heading would\n * otherwise land silently in an \"unclassified\" bucket at the bottom of the\n * page, which is the drift this whole file's neighbours are written to prevent;\n * `test/help-groups.test.ts` catches it at gate time, and this catches it the\n * first time anybody runs the binary. Same discipline as\n * `test/codes-drift.test.ts` applies to codes.\n */\nfunction groupCommands(program: Command): void {\n  for (const command of program.commands) {\n    const group = HELP_GROUPS[command.name()];\n    if (group === undefined) {\n      throw new Error(`cli: command '${command.name()}' has no HELP_GROUPS heading — add one in src/cli.ts`);\n    }\n    command.helpGroup(group);\n  }\n}\n\n/** CommanderError codes whose output (already printed) is the point, not a failure to wrap. */\nconst PASS_THROUGH = new Set([\"commander.help\", \"commander.helpDisplayed\", \"commander.version\"]);\n\nfunction main(): void {\n  const program = buildProgram();\n\n  // Set once a command's action actually runs: every subcommand declares its own\n  // `--json`, so past that point the parsed option is the authoritative answer.\n  let parsedJson: boolean | undefined;\n  program.hook(\"preAction\", (_thisCommand, actionCommand) => {\n    parsedJson = Boolean((actionCommand.optsWithGlobals() as { json?: boolean }).json);\n  });\n\n  /**\n   * Did this invocation ask for --json? Prefers the parsed option once an action\n   * has run; before that (commander usage errors abort mid-parse) falls back to\n   * scanning raw argv. The scan is a heuristic and cannot be made exact: a token\n   * spelled `--json` that was meant as an option VALUE (e.g. --title \"--json\")\n   * is indistinguishable from the flag in raw argv. It gets the common cases\n   * right: a `--json` token anywhere before a `--` terminator counts, and tokens\n   * after `--` never do.\n   */\n  const jsonRequested = (): boolean => {\n    if (parsedJson !== undefined) return parsedJson;\n    const argv = process.argv.slice(2);\n    const terminator = argv.indexOf(\"--\");\n    return (terminator === -1 ? argv : argv.slice(0, terminator)).includes(\"--json\");\n  };\n\n  program.parseAsync(process.argv).catch((err: unknown) => {\n    if (err instanceof CommanderError) {\n      // Help/version output was already written by commander — pass it through\n      // untouched with the exit code it always had.\n      //\n      // Anything else is a usage error (unknown option/command, missing or\n      // invalid argument). Commander has already printed its diagnostic to\n      // stderr, and that line stays: the invariant below is about stdout only.\n      if (!PASS_THROUGH.has(err.code) && jsonRequested()) {\n        emitJsonError(\"invalid-option\", err.message.replace(/^error: /, \"\"));\n      }\n      process.exitCode = err.exitCode;\n      return;\n    }\n    const message = err instanceof Error ? err.message : String(err);\n    // The envelope's one hard invariant is that stdout is JSON whenever --json\n    // was asked for — an unexpected throw must not be the exception to it.\n    if (jsonRequested()) {\n      emitJsonError(\"internal\", message);\n    } else {\n      console.error(message);\n      process.exitCode = 1;\n    }\n  });\n}\n\n/**\n * Was this file run, or merely imported? Realpath on both sides because the\n * installed entry point is reached through a symlink (`node_modules/.bin/loam`)\n * on every platform that has them, and a string compare against the link would\n * make the binary a no-op. A failure to resolve reads as \"not the entry\" only\n * for the import side; `process.argv[1]` that cannot be realpath'd is not a\n * loam invocation either.\n */\nfunction invokedDirectly(): boolean {\n  const entry = process.argv[1];\n  if (entry === undefined) return false;\n  try {\n    return realpathSync(entry) === realpathSync(fileURLToPath(import.meta.url));\n  } catch {\n    return false;\n  }\n}\n\nif (invokedDirectly()) main();\n"]}
+{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"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","sourcesContent":["#!/usr/bin/env node\nimport { Command, CommanderError } from \"commander\";\nimport { realpathSync } from \"node:fs\";\nimport { fileURLToPath } from \"node:url\";\nimport { registerInit } from \"./commands/init/init.js\";\nimport { registerAdopt } from \"./commands/adopt/adopt.js\";\nimport { registerList } from \"./commands/list/list.js\";\nimport { registerNew } from \"./commands/new/new.js\";\nimport { registerSeed } from \"./commands/seed/seed.js\";\nimport { registerShow } from \"./commands/show/show.js\";\nimport { registerStatus } from \"./commands/status/status.js\";\nimport { registerSubsystem } from \"./commands/subsystem/subsystem.js\";\nimport { registerDelta } from \"./commands/delta/delta.js\";\nimport { registerTasks } from \"./commands/tasks/tasks.js\";\nimport { registerDiff } from \"./commands/diff/diff.js\";\nimport { registerGherkin } from \"./commands/gherkin/gherkin.js\";\nimport { registerRebase } from \"./commands/rebase/rebase.js\";\nimport { registerArchive } from \"./commands/archive/archive.js\";\nimport { registerUnarchive } from \"./commands/unarchive/unarchive.js\";\nimport { registerValidate } from \"./commands/validate/validate.js\";\nimport { registerVerify } from \"./commands/verify/verify.js\";\nimport { registerVouch } from \"./commands/vouch/vouch.js\";\nimport { registerGate } from \"./commands/gate/gate.js\";\nimport { registerDoctor } from \"./commands/doctor.js\";\nimport { registerDependencies } from \"./commands/dependencies.js\";\nimport { registerSteps } from \"./commands/steps/steps.js\";\nimport { registerExplore } from \"./commands/explore.js\";\nimport { registerContext } from \"./commands/context/context.js\";\nimport { registerMcp } from \"./commands/mcp/mcp.js\";\nimport { registerOpen } from \"./commands/open.js\";\nimport { registerInstructions } from \"./commands/instructions.js\";\nimport { registerExplain } from \"./commands/explain/explain.js\";\nimport { registerMigrateOpenSpec } from \"./commands/migrate-openspec/migrate-openspec.js\";\nimport { emitJsonError, sayExplain } from \"./core/envelope/json.js\";\nimport { LOAM_VERSION } from \"./core/envelope/version.js\";\n\n/**\n * The whole CLI surface, as a program nobody has parsed yet.\n *\n * Exported because loam PRINTS commands — every `loam …` in AGENTS.md, in the\n * generated command and skill bodies, in a `doctor` finding's `fix` and in a\n * `status` next[] step is an instruction somebody (usually an agent) will type\n * back. The only way to prove one of those parses is to hand it to the program\n * that would receive it; a second copy of the registrations in a test agrees\n * with itself and with nothing else, which is exactly how\n * `Run \\`loam adopt <id>\\`` shipped as the first instruction a bound service\n * repo received. `test/agent-commands-runnable.test.ts` is the consumer.\n */\nexport function buildProgram(): Command {\n  const program = new Command();\n\n  program\n    .name(\"loam\")\n    .description(\"Architecture-first semantic integrity and change governance for evolving software systems\")\n    .version(LOAM_VERSION)\n    // The blank line is part of the attachment, not part of the text: commander\n    // writes this straight under the `Commands:` block, and two sentences flush\n    // against `help [command]` read as two more commands.\n    .addHelpText(\"after\", `\\n${HELP_EPILOG}`);\n\n  // Make commander throw a CommanderError instead of process.exit()ing, so a\n  // usage error (mistyped flag, unknown command) can still honour the envelope\n  // invariant in the catch below instead of dying with an empty stdout.\n  program.exitOverride();\n\n  registerInit(program);\n  registerAdopt(program);\n  registerList(program);\n  registerExplore(program);\n  registerContext(program);\n  registerNew(program);\n  registerSeed(program);\n  registerShow(program);\n  registerStatus(program);\n  registerSubsystem(program);\n  registerDelta(program);\n  registerTasks(program);\n  registerDiff(program);\n  registerGherkin(program);\n  registerRebase(program);\n  registerArchive(program);\n  registerUnarchive(program);\n  registerValidate(program);\n  registerVerify(program);\n  registerVouch(program);\n  registerGate(program);\n  registerDoctor(program);\n  registerDependencies(program);\n  registerSteps(program);\n  registerMcp(program);\n  registerInstructions(program);\n  registerExplain(program);\n  registerOpen(program);\n  registerMigrateOpenSpec(program);\n\n  groupCommands(program);\n\n  return program;\n}\n\n/**\n * The two lines under the command list: where to start, and what to run when\n * lost.\n *\n * {@link HELP_GROUPS} does nearly all of the orienting work — thirty\n * commands under seven headings, in the order of the work — but it stops one\n * step short of the two facts a newcomer does not have. Nothing on the page\n * said that `init` must run before any of the others, and nothing\n * named the command that answers \"what now\"; the last thing a first\n * `loam --help` printed was `help [command]`.\n *\n * Two lines, and no more, because the grouping is what does the work and a\n * paragraph here would compete with it.\n *\n * Both lines name a command that PARSES, and that is not a style rule:\n * `test/agent-commands-runnable.test.ts` takes this constant BY IMPORT and\n * hands both invocations to the real program, exactly as it does the `init`\n * first-hour lines. `loam init --create` is the form that works with no prior\n * knowledge — bare `loam init` defaults `--docs` to a `.loam-docs` that does\n * not exist yet and refuses, which is correct for a repo joining an existing\n * docs repo and wrong as the first thing a newcomer is told to type.\n */\nexport const HELP_EPILOG = [\n  \"New here? Run `loam init --create` first — every other command needs the docs repo it writes.\",\n  \"Lost? Run `loam doctor` — it prints the state, the resolved path, the finding code and a `fix:` line.\",\n].join(\"\\n\");\n\n/**\n * Which heading each command sits under in `loam --help`.\n *\n * The order is the order of the work: wire the repo, read the fleet, adopt what\n * exists, change it, check it, ship it. It mirrors the six shipped workflow\n * protocols (`loam instructions`) rather than inventing a second taxonomy, so a\n * reader who has met one has met the other.\n *\n * Thirty commands printed as one flat registration-ordered list tells a\n * new reader nothing about which four to run first. NOTHING IS HIDDEN — a\n * hidden command is a command an agent cannot discover, and every one of these\n * still parses, still appears, and still carries the same flags. This is\n * typography, not surface.\n */\nconst HELP_GROUPS: Record<string, string> = {\n  init: \"Set up\", seed: \"Set up\", doctor: \"Set up\", open: \"Set up\", mcp: \"Set up\",\n  list: \"Read the fleet\", status: \"Read the fleet\", show: \"Read the fleet\",\n  explore: \"Read the fleet\", context: \"Read the fleet\", dependencies: \"Read the fleet\",\n  explain: \"Read the fleet\", instructions: \"Read the fleet\", steps: \"Read the fleet\",\n  adopt: \"Adopt what exists\", vouch: \"Adopt what exists\",\n  new: \"Change it\", delta: \"Change it\", tasks: \"Change it\", gherkin: \"Change it\", rebase: \"Change it\",\n  subsystem: \"Change it\",\n  validate: \"Check it\", diff: \"Check it\", verify: \"Check it\", gate: \"Check it\",\n  archive: \"Ship it\", unarchive: \"Ship it\",\n  \"audit-openspec\": \"Migrate\", \"migrate-openspec\": \"Migrate\",\n};\n\n/**\n * Apply {@link HELP_GROUPS}, and FAIL CLOSED on a command it does not name.\n *\n * The throw is the point. A thirty-first command added without a heading would\n * otherwise land silently in an \"unclassified\" bucket at the bottom of the\n * page, which is the drift this whole file's neighbours are written to prevent;\n * `test/help-groups.test.ts` catches it at gate time, and this catches it the\n * first time anybody runs the binary. Same discipline as\n * `test/codes-drift.test.ts` applies to codes.\n */\nfunction groupCommands(program: Command): void {\n  for (const command of program.commands) {\n    const group = HELP_GROUPS[command.name()];\n    if (group === undefined) {\n      throw new Error(`cli: command '${command.name()}' has no HELP_GROUPS heading — add one in src/cli.ts`);\n    }\n    command.helpGroup(group);\n  }\n}\n\n/** CommanderError codes whose output (already printed) is the point, not a failure to wrap. */\nconst PASS_THROUGH = new Set([\"commander.help\", \"commander.helpDisplayed\", \"commander.version\"]);\n\n/**\n * What a text-mode usage error prints under commander's own diagnostic: the\n * fix and the stable code, the two lines every other refusal carries through\n * `fail`. Without them `loam diff` with no `--base` printed commander's one\n * sentence and nothing else — the only refusals in the CLI a person could not\n * look up, while `--json` already reported them as `invalid-option`.\n */\nfunction sayUsageFix(program: Command): void {\n  const name = process.argv.slice(2).find((token) => program.commands.some((c) => c.name() === token));\n  const help = name === undefined ? \"`loam --help` lists the commands\" : `\\`loam ${name} --help\\` lists the arguments and options it takes`;\n  console.error(`Fix the invocation: ${help}.`);\n  sayExplain(\"invalid-option\");\n}\n\nfunction main(): void {\n  const program = buildProgram();\n\n  // Set once a command's action actually runs: every subcommand declares its own\n  // `--json`, so past that point the parsed option is the authoritative answer.\n  let parsedJson: boolean | undefined;\n  program.hook(\"preAction\", (_thisCommand, actionCommand) => {\n    parsedJson = Boolean((actionCommand.optsWithGlobals() as { json?: boolean }).json);\n  });\n\n  /**\n   * Did this invocation ask for --json? Prefers the parsed option once an action\n   * has run; before that (commander usage errors abort mid-parse) falls back to\n   * scanning raw argv. The scan is a heuristic and cannot be made exact: a token\n   * spelled `--json` that was meant as an option VALUE (e.g. --title \"--json\")\n   * is indistinguishable from the flag in raw argv. It gets the common cases\n   * right: a `--json` token anywhere before a `--` terminator counts, and tokens\n   * after `--` never do.\n   */\n  const jsonRequested = (): boolean => {\n    if (parsedJson !== undefined) return parsedJson;\n    const argv = process.argv.slice(2);\n    const terminator = argv.indexOf(\"--\");\n    return (terminator === -1 ? argv : argv.slice(0, terminator)).includes(\"--json\");\n  };\n\n  program.parseAsync(process.argv).catch((err: unknown) => {\n    if (err instanceof CommanderError) {\n      // Help/version output was already written by commander — pass it through\n      // untouched with the exit code it always had.\n      //\n      // Anything else is a usage error (unknown option/command, missing or\n      // invalid argument). Commander has already printed its diagnostic to\n      // stderr, and that line stays: the invariant below is about stdout only.\n      if (!PASS_THROUGH.has(err.code)) {\n        if (jsonRequested()) emitJsonError(\"invalid-option\", err.message.replace(/^error: /, \"\"));\n        else sayUsageFix(program);\n      }\n      process.exitCode = err.exitCode;\n      return;\n    }\n    const message = err instanceof Error ? err.message : String(err);\n    // The envelope's one hard invariant is that stdout is JSON whenever --json\n    // was asked for — an unexpected throw must not be the exception to it.\n    if (jsonRequested()) {\n      emitJsonError(\"internal\", message);\n    } else {\n      console.error(message);\n      process.exitCode = 1;\n    }\n  });\n}\n\n/**\n * Was this file run, or merely imported? Realpath on both sides because the\n * installed entry point is reached through a symlink (`node_modules/.bin/loam`)\n * on every platform that has them, and a string compare against the link would\n * make the binary a no-op. A failure to resolve reads as \"not the entry\" only\n * for the import side; `process.argv[1]` that cannot be realpath'd is not a\n * loam invocation either.\n */\nfunction invokedDirectly(): boolean {\n  const entry = process.argv[1];\n  if (entry === undefined) return false;\n  try {\n    return realpathSync(entry) === realpathSync(fileURLToPath(import.meta.url));\n  } catch {\n    return false;\n  }\n}\n\nif (invokedDirectly()) main();\n"]}

package/dist/commands/adopt/adopt.js

@@ -1,10 +1,9 @@
 import { closeIds } from "../../core/c4/arch.js";
-import { loadConfig } from "../../core/envelope/config.js";
 import { InvalidIdError, assertServiceId } from "../../core/kernel/ids/service.js";
-import { emitJson, fail, NO_SERVICE_MESSAGE, repoPath, reportNoConfig } from "../../core/envelope/json.js";
+import { configOrRefuse, emitJson, fail, NO_SERVICE_MESSAGE, repoPath } from "../../core/envelope/json.js";
 import { DocsRepoUnavailableError } from "../../core/repo/state.js";
 import { listFleetTree, listServices } from "../../core/repo/repo.js";
-import { findInTree, nearestTreeNames } from "../../core/repo/tree/find.js";
+import { closeNamesHint, findInTree } from "../../core/repo/tree/find.js";
 import { servicePathsUnder } from "../../core/repo/paths.js";
 import { serviceBrief } from "../../core/brief/brief.js";
 import { docsRepoReady } from "../policy/gate.js";
@@ -21,9 +20,8 @@ async function subsystemTarget(docsDir, name, service, json) {
     const tree = await listFleetTree(docsDir);
     const hit = findInTree(tree, name);
     if (hit === null) {
-        const close = nearestTreeNames(name, tree.subsystems.map((s) => s.name));
         fail(json, "unknown-target", `No subsystem '${name}' in the tree.` +
-            (close.length > 0 ? ` Close names: ${close.join(", ")}.` : " `loam subsystem new` creates one; `loam subsystem list` shows what exists."));
+            closeNamesHint(name, tree.subsystems.map((s) => s.name), " `loam subsystem new` creates one; `loam subsystem list` shows what exists."));
         return null;
     }
     if (hit.kind === "service") {
@@ -141,12 +139,9 @@ export function registerAdopt(program) {
         .option("--json", "emit the machine contract instead of the human view")
         .action(async (opts) => {
         const json = opts.json === true;
-        const loaded = await loadConfig();
-        if (loaded.kind !== "loaded") {
-            reportNoConfig(json, loaded);
+        const config = await configOrRefuse(json);
+        if (config === null)
             return;
-        }
-        const config = loaded.config;
         // This command writes nothing, but it briefs an agent to write a whole
         // baseline — so a docsDir that does not exist is not a harmless read: it
         // hands over eight target paths under a directory nobody has, at exit 0,

package/dist/commands/adopt/adopt.js.map

@@ -1 +1 @@
-{"version":3,"file":"adopt.js","sourceRoot":"","sources":["../../../src/commands/adopt/adopt.ts"],"names":[],"mappings":"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","sourcesContent":["import type { Command } from \"commander\";\nimport { closeIds } from \"../../core/c4/arch.js\";\nimport { loadConfig } from \"../../core/envelope/config.js\";\nimport { InvalidIdError, assertServiceId, type PathableService } from \"../../core/kernel/ids/service.js\";\nimport { emitJson, fail, NO_SERVICE_MESSAGE, repoPath, reportNoConfig } from \"../../core/envelope/json.js\";\nimport { DocsRepoUnavailableError } from \"../../core/repo/state.js\";\nimport { listFleetTree, listServices } from \"../../core/repo/repo.js\";\nimport { findInTree, nearestTreeNames } from \"../../core/repo/tree/find.js\";\nimport { servicePathsUnder, type ServicePaths } from \"../../core/repo/paths.js\";\nimport { serviceBrief, type Brief } from \"../../core/brief/brief.js\";\nimport { docsRepoReady } from \"../policy/gate.js\";\nimport { render } from \"./render.js\";\nimport type { DocsDir } from \"../../core/kernel/ids/dirs.js\";\n\n/**\n * `loam adopt` — the bootstrap flow, as a contract with an agent.\n *\n * It emits a BRIEF, not an extraction: the artifacts one service's baseline is\n * made of, the grammar each has to be written in, what the fleet already says\n * about the service, the checks that follow, and the checks that do not exist.\n * The agent reads the code; loam states the work and then judges the result.\n *\n * It writes nothing. A command that produced the documents it is asking for\n * would be doing the half of the job it exists to hand over.\n */\n\ninterface AdoptOptions {\n  service?: string;\n  subsystem?: string;\n  targets?: boolean;\n  json?: boolean;\n}\n\n/**\n * Where `--subsystem` points the brief: the target directory inside the\n * group for a service that does not exist yet, or nothing — with a warning —\n * for one that already does, because adopt writes nothing and MOVES nothing\n * (`loam subsystem move` is the verb that relocates). An unknown subsystem\n * refuses with close-name hints, exactly as a mistyped service id warns: a\n * typo here would brief a whole baseline into a group nobody has.\n */\nasync function subsystemTarget(\n  docsDir: DocsDir,\n  name: string,\n  service: PathableService,\n  json: boolean,\n): Promise<{ at?: ServicePaths; warning?: string } | null> {\n  const tree = await listFleetTree(docsDir);\n  const hit = findInTree(tree, name);\n  if (hit === null) {\n    const close = nearestTreeNames(name, tree.subsystems.map((s) => s.name));\n    fail(\n      json,\n      \"unknown-target\",\n      `No subsystem '${name}' in the tree.` +\n        (close.length > 0 ? ` Close names: ${close.join(\", \")}.` : \" `loam subsystem new` creates one; `loam subsystem list` shows what exists.\"),\n    );\n    return null;\n  }\n  if (hit.kind === \"service\") {\n    fail(json, \"invalid-option\", `--subsystem names the service '${name}' — a service never contains other services.`);\n    return null;\n  }\n  const filed = tree.services.find((s) => s.id === service);\n  if (filed !== undefined) {\n    return {\n      warning:\n        `'${service}' already exists at ${repoPath(docsDir, filed.dir)}/ — --subsystem does not move a service ` +\n        `(\\`loam subsystem move ${service} --into ${name}\\` does), so the brief targets its existing directory.`,\n    };\n  }\n  return { at: servicePathsUnder(hit.subsystem.dir, service) };\n}\n\n/**\n * What is suspicious about this invocation without being wrong.\n *\n * Adopting a service that has no `services/<id>/` yet is the NORMAL case — it\n * is the whole point of the command — so neither of these can be a refusal.\n * But both used to be silent, and both produce the same outcome: a complete,\n * validating baseline written under a directory name nobody meant. `adopt\n * --service biling-service` briefed a phantom service beside the real\n * `billing-service`, and an agent following the brief created it.\n */\nasync function invocationWarnings(\n  docsDir: DocsDir,\n  service: PathableService,\n  bound: string | undefined,\n): Promise<string[]> {\n  const warnings: string[] = [];\n\n  if (bound !== undefined && bound !== service) {\n    warnings.push(\n      `This repository's loam.json declares service '${bound}', but you asked to adopt '${service}'. ` +\n        `That is legal — one repo can author another service's baseline — but \\`loam vouch\\`, ` +\n        `\\`loam gherkin\\` and \\`loam verify --service\\` all bind to '${bound}' here, so the baseline ` +\n        `you write cannot be vouched from this repo. If '${service}' is a typo, fix it; otherwise run ` +\n        `adopt from '${service}''s own repository.`,\n    );\n  }\n\n  // \"Does the service already exist\" is enumeration MEMBERSHIP, not an\n  // existsSync of services/<id>/ at the root: a service filed into a subsystem\n  // exists wherever the tree walk found it, and the root probe read every\n  // filed service as new — the near-miss warning then accused its own name of\n  // being a typo. One enumeration answers both this and the near-miss list;\n  // a repo that refuses enumeration is a different problem, reported by every\n  // other command, and adopt has nothing useful to add to it.\n  let known: string[] = [];\n  try {\n    known = (await listServices(docsDir)).map((s) => s.id);\n  } catch (err) {\n    if (!(err instanceof DocsRepoUnavailableError)) throw err;\n    return warnings;\n  }\n  if (known.includes(service)) return warnings;\n  const close = closeIds(service, known);\n  if (close.length > 0) {\n    warnings.push(\n      `There is no services/${service}/ yet, but the docs repo already has ${close.join(\", \")}. ` +\n        `If '${service}' is a misspelling of one of those, stop now: an agent following this brief ` +\n        `writes a complete, validating baseline for a service that does not exist, and nothing ` +\n        `downstream can tell it from a real one. If it really is a new service, this is expected.`,\n    );\n  }\n  return warnings;\n}\n\n/**\n * The half of the brief that is computed from THIS repository, for THIS\n * service — what `--targets` keeps.\n *\n * Everything omitted is a module-level constant: `walk` and `walkClose` are the\n * code-reading order, `frontmatter` the field rules, `checks` the named checks,\n * `unchecked` the statements of what nothing checks, `rule` the never-overwrite\n * instruction. None of them is a function of the service, so a fleet-wide\n * adoption pays for the same bytes once per service — measured on the shipped\n * example fleet, about 23 KB of the 42 KB brief, which is four fifths of what\n * an agent reads and none of what it could not have read once.\n *\n * The keys are picked one by one rather than deleted from a rest — a field\n * added to `Brief` later must land in the DEFAULT payload and stay out of this\n * one until somebody decides it varies by service. Getting that wrong the\n * other way round is how a narrowing flag silently becomes the full brief\n * again.\n */\nfunction narrowed(b: Brief): Pick<Brief, \"service\" | \"docsDir\" | \"path\" | \"targets\" | \"landscape\"> {\n  return { service: b.service, docsDir: b.docsDir, path: b.path, targets: b.targets, landscape: b.landscape };\n}\n\n/**\n * The `full` pointer: the run that carries what `--targets` dropped, and the\n * reason it is worth making.\n *\n * It is REQUIRED in the narrowed envelope, and the second sentence is why. The\n * unchecked list is loam shipping, in the binary, the statements of what no\n * check will ever tell you — the one thing standing between a green\n * `loam validate` and being read as more than it means. Merely leaving it out\n * would not read as \"omitted for brevity\"; it would read as \"there is no such\n * list\", which is the failure `src/core/brief/unchecked.ts` exists to prevent\n * and the one promise the brief keeps that no validator supplies. So the\n * narrowed view never hides it — it says how many there are and where to read\n * them.\n *\n * Every count comes off the brief that was just assembled, never off a number\n * typed here: a literal would be correct until the next check is added and\n * wrong silently forever after.\n */\nfunction fullBrief(b: Brief): string {\n  return (\n    `loam adopt --service ${b.service} --json — everything this view leaves out: the ` +\n    `${b.walk.length}-stop code walk, the frontmatter rules, the ${b.checks.length} named checks, ` +\n    `and the ${b.unchecked.length} statements of what nothing checks. None of it varies by service, ` +\n    `so run it once for the system rather than once per service — but do run it: those ` +\n    `${b.unchecked.length} statements are the only place loam says where its checking stops.`\n  );\n}\n\nexport function registerAdopt(program: Command): void {\n  program\n    .command(\"adopt\")\n    .description(\"Brief an agent to write one service's baseline docs from its code, and say what will be checked\")\n    .option(\"--service <id>\", \"service to adopt (defaults to the configured service)\")\n    .option(\"--subsystem <name>\", \"file the new service's baseline into this subsystem instead of the services/ root\")\n    .option(\"--targets\", \"narrow the brief to what varies by service; the walk, the checks and the unchecked list are omitted, and a `full` field names the run that carries them\")\n    .option(\"--json\", \"emit the machine contract instead of the human view\")\n    .action(async (opts: AdoptOptions) => {\n      const json = opts.json === true;\n\n      const loaded = await loadConfig();\n      if (loaded.kind !== \"loaded\") {\n        reportNoConfig(json, loaded);\n        return;\n      }\n      const config = loaded.config;\n      // This command writes nothing, but it briefs an agent to write a whole\n      // baseline — so a docsDir that does not exist is not a harmless read: it\n      // hands over eight target paths under a directory nobody has, at exit 0,\n      // with the near-miss warning below silently switched off (listServices\n      // throws, `invocationWarnings` swallows it and returns nothing). The same\n      // refusal every enumerating command owes; see docs-repo-gate.ts.\n      //\n      // `docs`, not `services`: a docs repo that has no services/ yet is exactly\n      // the repo adopt exists to fill, and refusing there would refuse the\n      // command's own first use.\n      if (!docsRepoReady(json, config.docsDir, \"docs\")) return;\n\n      const service = opts.service ?? config.service;\n      if (service === undefined) {\n        fail(json, \"invalid-option\", NO_SERVICE_MESSAGE);\n        return;\n      }\n      // The id becomes `services/<id>/` in a shared repo, so it goes through the\n      // one grammar before anything interpolates it into a path.\n      try {\n        assertServiceId(service, opts.service === undefined ? \"service (loam.json)\" : \"--service\");\n      } catch (err) {\n        if (!(err instanceof InvalidIdError)) throw err;\n        fail(json, \"invalid-option\", err.message);\n        return;\n      }\n\n      const warnings = await invocationWarnings(config.docsDir, service, config.service);\n      let at: ServicePaths | undefined;\n      if (opts.subsystem !== undefined) {\n        const target = await subsystemTarget(config.docsDir, opts.subsystem, service, json);\n        if (target === null) return;\n        at = target.at;\n        if (target.warning !== undefined) warnings.push(target.warning);\n      }\n      const brief = await serviceBrief(config.docsDir, service, at);\n      // Computed only under `--targets`, and it is what makes the narrowing\n      // legible from inside the payload: a consumer holding `full` knows there\n      // is more and what it is, and a consumer without it is holding all of it.\n      // The narrowing happens HERE, by omission, so the brief itself is\n      // unchanged and every field it can produce still exists.\n      const full = opts.targets === true ? fullBrief(brief) : undefined;\n      if (json) {\n        // Two separate emits rather than one conditional spread: the default\n        // payload is a frozen contract, and it must stay the same bytes in the\n        // same order whatever this flag grows into.\n        if (full !== undefined) {\n          emitJson({ command: \"adopt\", ...narrowed(brief), warnings, full });\n          return;\n        }\n        emitJson({ command: \"adopt\", ...brief, warnings });\n        return;\n      }\n      render(brief, warnings, full);\n    });\n}\n"]}
+{"version":3,"file":"adopt.js","sourceRoot":"","sources":["../../../src/commands/adopt/adopt.ts"],"names":[],"mappings":"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","sourcesContent":["import type { Command } from \"commander\";\nimport { closeIds } from \"../../core/c4/arch.js\";\nimport { InvalidIdError, assertServiceId, type PathableService } from \"../../core/kernel/ids/service.js\";\nimport { configOrRefuse, emitJson, fail, NO_SERVICE_MESSAGE, repoPath } from \"../../core/envelope/json.js\";\nimport { DocsRepoUnavailableError } from \"../../core/repo/state.js\";\nimport { listFleetTree, listServices } from \"../../core/repo/repo.js\";\nimport { closeNamesHint, findInTree } from \"../../core/repo/tree/find.js\";\nimport { servicePathsUnder, type ServicePaths } from \"../../core/repo/paths.js\";\nimport { serviceBrief, type Brief } from \"../../core/brief/brief.js\";\nimport { docsRepoReady } from \"../policy/gate.js\";\nimport { render } from \"./render.js\";\nimport type { DocsDir } from \"../../core/kernel/ids/dirs.js\";\n\n/**\n * `loam adopt` — the bootstrap flow, as a contract with an agent.\n *\n * It emits a BRIEF, not an extraction: the artifacts one service's baseline is\n * made of, the grammar each has to be written in, what the fleet already says\n * about the service, the checks that follow, and the checks that do not exist.\n * The agent reads the code; loam states the work and then judges the result.\n *\n * It writes nothing. A command that produced the documents it is asking for\n * would be doing the half of the job it exists to hand over.\n */\n\ninterface AdoptOptions {\n  service?: string;\n  subsystem?: string;\n  targets?: boolean;\n  json?: boolean;\n}\n\n/**\n * Where `--subsystem` points the brief: the target directory inside the\n * group for a service that does not exist yet, or nothing — with a warning —\n * for one that already does, because adopt writes nothing and MOVES nothing\n * (`loam subsystem move` is the verb that relocates). An unknown subsystem\n * refuses with close-name hints, exactly as a mistyped service id warns: a\n * typo here would brief a whole baseline into a group nobody has.\n */\nasync function subsystemTarget(\n  docsDir: DocsDir,\n  name: string,\n  service: PathableService,\n  json: boolean,\n): Promise<{ at?: ServicePaths; warning?: string } | null> {\n  const tree = await listFleetTree(docsDir);\n  const hit = findInTree(tree, name);\n  if (hit === null) {\n    fail(\n      json,\n      \"unknown-target\",\n      `No subsystem '${name}' in the tree.` +\n        closeNamesHint(name, tree.subsystems.map((s) => s.name), \" `loam subsystem new` creates one; `loam subsystem list` shows what exists.\"),\n    );\n    return null;\n  }\n  if (hit.kind === \"service\") {\n    fail(json, \"invalid-option\", `--subsystem names the service '${name}' — a service never contains other services.`);\n    return null;\n  }\n  const filed = tree.services.find((s) => s.id === service);\n  if (filed !== undefined) {\n    return {\n      warning:\n        `'${service}' already exists at ${repoPath(docsDir, filed.dir)}/ — --subsystem does not move a service ` +\n        `(\\`loam subsystem move ${service} --into ${name}\\` does), so the brief targets its existing directory.`,\n    };\n  }\n  return { at: servicePathsUnder(hit.subsystem.dir, service) };\n}\n\n/**\n * What is suspicious about this invocation without being wrong.\n *\n * Adopting a service that has no `services/<id>/` yet is the NORMAL case — it\n * is the whole point of the command — so neither of these can be a refusal.\n * But both used to be silent, and both produce the same outcome: a complete,\n * validating baseline written under a directory name nobody meant. `adopt\n * --service biling-service` briefed a phantom service beside the real\n * `billing-service`, and an agent following the brief created it.\n */\nasync function invocationWarnings(\n  docsDir: DocsDir,\n  service: PathableService,\n  bound: string | undefined,\n): Promise<string[]> {\n  const warnings: string[] = [];\n\n  if (bound !== undefined && bound !== service) {\n    warnings.push(\n      `This repository's loam.json declares service '${bound}', but you asked to adopt '${service}'. ` +\n        `That is legal — one repo can author another service's baseline — but \\`loam vouch\\`, ` +\n        `\\`loam gherkin\\` and \\`loam verify --service\\` all bind to '${bound}' here, so the baseline ` +\n        `you write cannot be vouched from this repo. If '${service}' is a typo, fix it; otherwise run ` +\n        `adopt from '${service}''s own repository.`,\n    );\n  }\n\n  // \"Does the service already exist\" is enumeration MEMBERSHIP, not an\n  // existsSync of services/<id>/ at the root: a service filed into a subsystem\n  // exists wherever the tree walk found it, and the root probe read every\n  // filed service as new — the near-miss warning then accused its own name of\n  // being a typo. One enumeration answers both this and the near-miss list;\n  // a repo that refuses enumeration is a different problem, reported by every\n  // other command, and adopt has nothing useful to add to it.\n  let known: string[] = [];\n  try {\n    known = (await listServices(docsDir)).map((s) => s.id);\n  } catch (err) {\n    if (!(err instanceof DocsRepoUnavailableError)) throw err;\n    return warnings;\n  }\n  if (known.includes(service)) return warnings;\n  const close = closeIds(service, known);\n  if (close.length > 0) {\n    warnings.push(\n      `There is no services/${service}/ yet, but the docs repo already has ${close.join(\", \")}. ` +\n        `If '${service}' is a misspelling of one of those, stop now: an agent following this brief ` +\n        `writes a complete, validating baseline for a service that does not exist, and nothing ` +\n        `downstream can tell it from a real one. If it really is a new service, this is expected.`,\n    );\n  }\n  return warnings;\n}\n\n/**\n * The half of the brief that is computed from THIS repository, for THIS\n * service — what `--targets` keeps.\n *\n * Everything omitted is a module-level constant: `walk` and `walkClose` are the\n * code-reading order, `frontmatter` the field rules, `checks` the named checks,\n * `unchecked` the statements of what nothing checks, `rule` the never-overwrite\n * instruction. None of them is a function of the service, so a fleet-wide\n * adoption pays for the same bytes once per service — measured on the shipped\n * example fleet, about 23 KB of the 42 KB brief, which is four fifths of what\n * an agent reads and none of what it could not have read once.\n *\n * The keys are picked one by one rather than deleted from a rest — a field\n * added to `Brief` later must land in the DEFAULT payload and stay out of this\n * one until somebody decides it varies by service. Getting that wrong the\n * other way round is how a narrowing flag silently becomes the full brief\n * again.\n */\nfunction narrowed(b: Brief): Pick<Brief, \"service\" | \"docsDir\" | \"path\" | \"targets\" | \"landscape\"> {\n  return { service: b.service, docsDir: b.docsDir, path: b.path, targets: b.targets, landscape: b.landscape };\n}\n\n/**\n * The `full` pointer: the run that carries what `--targets` dropped, and the\n * reason it is worth making.\n *\n * It is REQUIRED in the narrowed envelope, and the second sentence is why. The\n * unchecked list is loam shipping, in the binary, the statements of what no\n * check will ever tell you — the one thing standing between a green\n * `loam validate` and being read as more than it means. Merely leaving it out\n * would not read as \"omitted for brevity\"; it would read as \"there is no such\n * list\", which is the failure `src/core/brief/unchecked.ts` exists to prevent\n * and the one promise the brief keeps that no validator supplies. So the\n * narrowed view never hides it — it says how many there are and where to read\n * them.\n *\n * Every count comes off the brief that was just assembled, never off a number\n * typed here: a literal would be correct until the next check is added and\n * wrong silently forever after.\n */\nfunction fullBrief(b: Brief): string {\n  return (\n    `loam adopt --service ${b.service} --json — everything this view leaves out: the ` +\n    `${b.walk.length}-stop code walk, the frontmatter rules, the ${b.checks.length} named checks, ` +\n    `and the ${b.unchecked.length} statements of what nothing checks. None of it varies by service, ` +\n    `so run it once for the system rather than once per service — but do run it: those ` +\n    `${b.unchecked.length} statements are the only place loam says where its checking stops.`\n  );\n}\n\nexport function registerAdopt(program: Command): void {\n  program\n    .command(\"adopt\")\n    .description(\"Brief an agent to write one service's baseline docs from its code, and say what will be checked\")\n    .option(\"--service <id>\", \"service to adopt (defaults to the configured service)\")\n    .option(\"--subsystem <name>\", \"file the new service's baseline into this subsystem instead of the services/ root\")\n    .option(\"--targets\", \"narrow the brief to what varies by service; the walk, the checks and the unchecked list are omitted, and a `full` field names the run that carries them\")\n    .option(\"--json\", \"emit the machine contract instead of the human view\")\n    .action(async (opts: AdoptOptions) => {\n      const json = opts.json === true;\n\n      const config = await configOrRefuse(json);\n      if (config === null) return;\n      // This command writes nothing, but it briefs an agent to write a whole\n      // baseline — so a docsDir that does not exist is not a harmless read: it\n      // hands over eight target paths under a directory nobody has, at exit 0,\n      // with the near-miss warning below silently switched off (listServices\n      // throws, `invocationWarnings` swallows it and returns nothing). The same\n      // refusal every enumerating command owes; see docs-repo-gate.ts.\n      //\n      // `docs`, not `services`: a docs repo that has no services/ yet is exactly\n      // the repo adopt exists to fill, and refusing there would refuse the\n      // command's own first use.\n      if (!docsRepoReady(json, config.docsDir, \"docs\")) return;\n\n      const service = opts.service ?? config.service;\n      if (service === undefined) {\n        fail(json, \"invalid-option\", NO_SERVICE_MESSAGE);\n        return;\n      }\n      // The id becomes `services/<id>/` in a shared repo, so it goes through the\n      // one grammar before anything interpolates it into a path.\n      try {\n        assertServiceId(service, opts.service === undefined ? \"service (loam.json)\" : \"--service\");\n      } catch (err) {\n        if (!(err instanceof InvalidIdError)) throw err;\n        fail(json, \"invalid-option\", err.message);\n        return;\n      }\n\n      const warnings = await invocationWarnings(config.docsDir, service, config.service);\n      let at: ServicePaths | undefined;\n      if (opts.subsystem !== undefined) {\n        const target = await subsystemTarget(config.docsDir, opts.subsystem, service, json);\n        if (target === null) return;\n        at = target.at;\n        if (target.warning !== undefined) warnings.push(target.warning);\n      }\n      const brief = await serviceBrief(config.docsDir, service, at);\n      // Computed only under `--targets`, and it is what makes the narrowing\n      // legible from inside the payload: a consumer holding `full` knows there\n      // is more and what it is, and a consumer without it is holding all of it.\n      // The narrowing happens HERE, by omission, so the brief itself is\n      // unchanged and every field it can produce still exists.\n      const full = opts.targets === true ? fullBrief(brief) : undefined;\n      if (json) {\n        // Two separate emits rather than one conditional spread: the default\n        // payload is a frozen contract, and it must stay the same bytes in the\n        // same order whatever this flag grows into.\n        if (full !== undefined) {\n          emitJson({ command: \"adopt\", ...narrowed(brief), warnings, full });\n          return;\n        }\n        emitJson({ command: \"adopt\", ...brief, warnings });\n        return;\n      }\n      render(brief, warnings, full);\n    });\n}\n"]}

package/dist/commands/adopt/render.js

@@ -55,7 +55,21 @@ export function render(b, warnings, full) {
     for (const t of b.targets) {
         // `edit` is the shared fleet map: the file exists, but "present" would read
         // as "nothing to do here", which is the opposite of why it is on the list.
-        const flag = t.action === "edit" ? "UNDRAWN" : t.exists ? "present" : t.required ? "MISSING" : "missing";
+        // Two words for it, because the two states want different work: `UNDRAWN`
+        // when nothing resolves to the service, `EDGELESS` when an element does
+        // and no edge touches it — a reader acting on `UNDRAWN` there would look
+        // for a box that is already on the map.
+        const flag = t.action === "edit"
+            ? b.landscape.modelled === true
+                ? "EDGELESS"
+                : "UNDRAWN"
+            : t.partial === true
+                ? "PARTIAL"
+                : t.exists
+                    ? "present"
+                    : t.required
+                        ? "MISSING"
+                        : "missing";
         console.log(`    ${t.artifact.padEnd(width)}  ${t.action.padEnd(6)}  ${flag.padEnd(7)}  ${t.purpose}`);
     }
     for (const t of b.targets)
@@ -81,8 +95,8 @@ export function render(b, warnings, full) {
     console.log("");
     console.log(wrap("Leave everything `status: draft`. Vouching is somebody reading the code and saying the document matches it — it is not yours to do, and a status with no digest behind it is a claim with nothing behind it.", "    "));
 }
-/** The table's four flags, compressed to one terminal line for the scroll-back reader. */
-const LEGEND_LINE = "MISSING required · missing optional · present diff it · UNDRAWN add to the map";
+/** The table's five flags, compressed to one terminal line for the scroll-back reader. */
+const LEGEND_LINE = "MISSING required · missing optional · present diff it · PARTIAL one feature's slice, adopt around it · UNDRAWN add to the map · EDGELESS an element exists, no edge does";
 /**
  * A required target whose work is still outstanding.
  *
@@ -91,10 +105,11 @@ const LEGEND_LINE = "MISSING required · missing optional · present diff it ·
  * exists, so `exists` is true while nothing in it resolves to this boundary —
  * which `loam validate --all` grades `landscape.service-unmodelled`, an ERROR.
  * `action` carries that distinction and nothing else does: `edit` is only ever
- * the undrawn fleet map (see `BriefTarget.action`, core/brief/targets.ts).
+ * the fleet map still owed — undrawn, or drawn with no edge touching it (see
+ * `BriefTarget.action`, core/brief/targets.ts).
  */
 function outstanding(t) {
-    return t.required && (!t.exists || t.action === "edit");
+    return t.required && (!t.exists || t.action === "edit" || t.partial === true);
 }
 /**
  * The three sentences that make the rest of the page readable: how much of it
@@ -121,7 +136,7 @@ function printOrientation(b) {
     // capitals were emphasis; they are the required/optional distinction, and
     // nothing on the page said so. `UNDRAWN` needs more than a gloss — it is the
     // one row that is not this boundary's file at all.
-    console.log(bullet("The flags in that table: `MISSING` in capitals is required and not there, lowercase `missing` is optional and not there, `present` means the file exists — diff it, never replace it. `UNDRAWN` marks the one row that is not this boundary's own file: `architecture/landscape.likec4` is the whole system's map and already holds every other boundary, so ADD to it rather than rewriting it. Until an element in it resolves to this directory, `loam validate --all` reports `landscape.service-unmodelled` (error).", "    "));
+    console.log(bullet("The flags in that table: `MISSING` in capitals is required and not there, lowercase `missing` is optional and not there, `present` means the file exists — diff it, never replace it. `PARTIAL` is a spec.md marked `adoption: partial`: one archived feature's slice, so keep every requirement in it, write the rest of the service around them, and then delete the `adoption: partial` line. `UNDRAWN` and `EDGELESS` mark the one row that is not this boundary's own file: `architecture/landscape.likec4` is the whole system's map and already holds every other boundary, so ADD to it rather than rewriting it. Until an element in it resolves to this directory, `loam validate --all` reports `landscape.service-unmodelled` (error); `EDGELESS` means an element already does and no edge touches it, so what the map lacks is the calls in and out of it, never a second element.", "    "));
     console.log("");
     // What the rest of the page is, so a reader who stops here still knows what
     // they scrolled past — and where the same content lives for an agent, which
@@ -215,9 +230,15 @@ function printLandscape(b) {
         return;
     }
     if (!l.parses) {
-        console.log("    architecture/landscape.likec4 does not parse — bind by hand, and fix it first.");
+        // Not "architecture/landscape.likec4 does not parse": the map is the whole
+        // `architecture/` project, so the file that broke is usually a sibling —
+        // and this line accused the landscape of errors `validate --all` blamed on
+        // a palette. The instruction printed directly below names the documents
+        // that actually failed, so the headline says the project and nothing more.
+        console.log("    The fleet map (architecture/) does not parse — fix that first; the files are named below.");
         console.log("");
         console.log(wrap(l.instruction ?? "", "    "));
+        printExpects(l);
         return;
     }
     if (l.elements.length === 0) {
@@ -234,10 +255,30 @@ function printLandscape(b) {
         console.log(`    ← ${e.from}  ${e.op ?? `"${e.title ?? ""}"`}`);
     for (const e of l.outbound)
         console.log(`    → ${e.to}  ${e.op ?? `"${e.title ?? ""}"`}`);
-    if (l.expects.length > 0) {
+    // The edgeless state: an element and no edge lines above it. The modelled
+    // branch used to return here without ever printing an instruction, which
+    // is how the text view briefed "the map owes nothing" over two empty lists.
+    if (l.instruction !== null) {
         console.log("");
-        console.log(wrap(`openapi.yaml must define ${l.expects.map((o) => `'${o}'`).join(", ")} — the fleet already calls ${l.expects.length === 1 ? "it" : "them"}, and a contract that omits ${l.expects.length === 1 ? "it" : "them"} fails spine.op-undefined the moment it lands.`, "    "));
+        console.log(wrap(l.instruction, "    "));
     }
+    printExpects(l);
+}
+/**
+ * What the fleet already calls on this service, and why the contract owes it.
+ *
+ * Printed in the unparseable branch as well as the healthy one: the landscape
+ * FILE still answers who calls this service when a sibling under `architecture/`
+ * breaks the project, and it is what decides whether `openapi.yaml` is flagged
+ * required — so a reader who is told the map is unreadable still gets the
+ * evidence behind that row.
+ */
+function printExpects(l) {
+    if (l.expects.length === 0)
+        return;
+    const it = l.expects.length === 1 ? "it" : "them";
+    console.log("");
+    console.log(wrap(`openapi.yaml must define ${l.expects.map((o) => `'${o}'`).join(", ")} — the fleet already calls ${it}, and a contract that omits ${it} fails spine.op-undefined the moment it lands.`, "    "));
 }
 /**
  * Wrap prose so the brief is readable in a terminal. Continuation lines are

package/dist/commands/adopt/render.js.map

@@ -1 +1 @@
-{"version":3,"file":"render.js","sourceRoot":"","sources":["../../../src/commands/adopt/render.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,OAAO,EAAE,aAAa,EAAE,MAAM,iCAAiC,CAAC;AAChE,OAAO,EAAc,MAAM,2BAA2B,CAAC;AACvD,OAAO,EAAE,OAAO,EAAmB,MAAM,4BAA4B,CAAC;AAGtE,wEAAwE;AACxE,yEAAyE;AACzE,wEAAwE;AAExE;;;;;;GAMG;AACH,MAAM,UAAU,MAAM,CAAC,CAAQ,EAAE,QAAkB,EAAE,IAAa;IAChE,OAAO,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC,OAAO,8BAA8B,CAAC,CAAC,IAAI,KAAK,CAAC,CAAC;IACzE,yEAAyE;IACzE,gEAAgE;IAChE,KAAK,MAAM,CAAC,IAAI,QAAQ,EAAE,CAAC;QACzB,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,EAAE,IAAI,CAAC,CAAC,CAAC;QAClC,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;IAClB,CAAC;IACD,IAAI,IAAI,KAAK,SAAS,EAAE,CAAC;QACvB,qEAAqE;QACrE,4EAA4E;QAC5E,uEAAuE;QACvE,qEAAqE;QACrE,2EAA2E;QAC3E,4EAA4E;QAC5E,0EAA0E;QAC1E,0EAA0E;QAC1E,sDAAsD;QACtD,gBAAgB,CAAC,CAAC,CAAC,CAAC;QACpB,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC,CAAC;QAEhC,6EAA6E;QAC7E,uEAAuE;QACvE,SAAS,CAAC,CAAC,CAAC,CAAC;IACf,CAAC;IAED,OAAO,CAAC,GAAG,CAAC,iBAAiB,CAAC,CAAC;IAC/B,4EAA4E;IAC5E,6EAA6E;IAC7E,sEAAsE;IACtE,mCAAmC;IACnC,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,WAAW,EAAE,MAAM,CAAC,CAAC,CAAC;IACvC,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;IAChB,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC;IACnE,KAAK,MAAM,CAAC,IAAI,CAAC,CAAC,OAAO,EAAE,CAAC;QAC1B,4EAA4E;QAC5E,2EAA2E;QAC3E,MAAM,IAAI,GAAG,CAAC,CAAC,MAAM,KAAK,MAAM,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC;QACzG,OAAO,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,QAAQ,CAAC,MAAM,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,KAAK,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC;IACzG,CAAC;IAED,KAAK,MAAM,CAAC,IAAI,CAAC,CAAC,OAAO;QAAE,UAAU,CAAC,CAAC,CAAC,CAAC;IAEzC,cAAc,CAAC,CAAC,CAAC,CAAC;IAElB,IAAI,IAAI,KAAK,SAAS;QAAE,aAAa,CAAC,CAAC,CAAC,CAAC;SACpC,CAAC;QACJ,yEAAyE;QACzE,0EAA0E;QAC1E,uEAAuE;QACvE,8DAA8D;QAC9D,OAAO,CAAC,GAAG,CAAC,6BAA6B,CAAC,CAAC;QAC3C,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC,CAAC;IAClC,CAAC;IAED,OAAO,CAAC,GAAG,CAAC,yBAAyB,CAAC,CAAC;IACvC,OAAO,CAAC,GAAG,CAAC,+BAA+B,CAAC,CAAC,OAAO,8BAA8B,CAAC,CAAC;IACpF,uEAAuE;IACvE,wEAAwE;IACxE,uBAAuB;IACvB,OAAO,CAAC,GAAG,CAAC,yFAAyF,CAAC,CAAC;IACvG,OAAO,CAAC,GAAG,CAAC,4BAA4B,CAAC,CAAC,OAAO,oDAAoD,CAAC,CAAC;IACvG,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;IAChB,OAAO,CAAC,GAAG,CACT,IAAI,CACF,8MAA8M,EAC9M,MAAM,CACP,CACF,CAAC;AACJ,CAAC;AAED,0FAA0F;AAC1F,MAAM,WAAW,GAAG,gFAAgF,CAAC;AAErG;;;;;;;;;GASG;AACH,SAAS,WAAW,CAAC,CAAc;IACjC,OAAO,CAAC,CAAC,QAAQ,IAAI,CAAC,CAAC,CAAC,CAAC,MAAM,IAAI,CAAC,CAAC,MAAM,KAAK,MAAM,CAAC,CAAC;AAC1D,CAAC;AAED;;;;;;;;;;GAUG;AACH,SAAS,gBAAgB,CAAC,CAAQ;IAChC,MAAM,IAAI,GAAG,CAAC,CAAC,OAAO,CAAC,MAAM,CAAC,WAAW,CAAC,CAAC;IAC3C,OAAO,CAAC,GAAG,CAAC,qBAAqB,CAAC,CAAC;IAEnC,6EAA6E;IAC7E,4EAA4E;IAC5E,qCAAqC;IACrC,OAAO,CAAC,GAAG,CACT,MAAM,CACJ,IAAI,CAAC,MAAM,KAAK,CAAC;QACf,CAAC,CAAC,eAAe,MAAM,CAAC,CAAC,CAAC,OAAO,CAAC,MAAM,CAAC,2KAA2K;QACpN,CAAC,CAAC,GAAG,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,WAAW,MAAM,CAAC,CAAC,CAAC,OAAO,CAAC,MAAM,CAAC,oBAAoB,IAAI,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,KAAK,+BAA+B,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,yGAAyG,EAC/R,MAAM,CACP,CACF,CAAC;IACF,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;IAEhB,0EAA0E;IAC1E,0EAA0E;IAC1E,6EAA6E;IAC7E,mDAAmD;IACnD,OAAO,CAAC,GAAG,CACT,MAAM,CACJ,2fAA2f,EAC3f,MAAM,CACP,CACF,CAAC;IACF,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;IAEhB,4EAA4E;IAC5E,4EAA4E;IAC5E,gDAAgD;IAChD,OAAO,CAAC,GAAG,CACT,MAAM,CACJ,wCAAwC,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,oIAAoI,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,8CAA8C,MAAM,CAAC,CAAC,CAAC,SAAS,CAAC,MAAM,CAAC,8DAA8D,CAAC,CAAC,OAAO,2HAA2H,EACle,MAAM,CACP,CACF,CAAC;IACF,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;AAClB,CAAC;AAED;;;;;;GAMG;AACH,SAAS,aAAa,CAAC,CAAQ;IAC7B,OAAO,CAAC,GAAG,CAAC,gDAAgD,CAAC,CAAC;IAC9D,KAAK,MAAM,CAAC,KAAK,EAAE,IAAI,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,WAAW,CAAC,MAAM,CAAC,EAAE,CAAC;QACjE,OAAO,CAAC,GAAG,CAAC,OAAO,KAAK,EAAE,CAAC,CAAC;QAC5B,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC,CAAC;IACpC,CAAC;IACD,OAAO,CAAC,GAAG,CAAC,8BAA8B,CAAC,CAAC,WAAW,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IAC5E,OAAO,CAAC,GAAG,CAAC,KAAK,IAAI,CAAC,CAAC,CAAC,WAAW,CAAC,GAAG,EAAE,MAAM,CAAC,EAAE,CAAC,CAAC;IAEpD,4EAA4E;IAC5E,wEAAwE;IACxE,4BAA4B;IAC5B,OAAO,CAAC,GAAG,CAAC,sCAAsC,CAAC,CAAC,OAAO,kBAAkB,CAAC,CAAC;IAC/E,KAAK,MAAM,CAAC,IAAI,CAAC,CAAC,MAAM,EAAE,CAAC;QACzB,IAAI,CAAC,CAAC,GAAG,KAAK,OAAO;YAAE,UAAU,CAAC,CAAC,CAAC,CAAC;IACvC,CAAC;IACD,OAAO,CAAC,GAAG,CAAC,sDAAsD,CAAC,CAAC;IACpE,KAAK,MAAM,CAAC,IAAI,CAAC,CAAC,MAAM,EAAE,CAAC;QACzB,IAAI,CAAC,CAAC,GAAG,KAAK,OAAO;YAAE,UAAU,CAAC,CAAC,CAAC,CAAC;IACvC,CAAC;IAED,OAAO,CAAC,GAAG,CAAC,2BAA2B,CAAC,CAAC;IACzC,KAAK,MAAM,CAAC,IAAI,CAAC,CAAC,SAAS;QAAE,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,EAAE,MAAM,CAAC,CAAC,CAAC;AAC9D,CAAC;AAED;;;;GAIG;AACH,SAAS,SAAS,CAAC,CAAQ;IACzB,OAAO,CAAC,GAAG,CAAC,iFAAiF,CAAC,CAAC;IAC/F,KAAK,MAAM,CAAC,CAAC,EAAE,IAAI,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,OAAO,EAAE,EAAE,CAAC;QACzC,6EAA6E;QAC7E,yEAAyE;QACzE,4EAA4E;QAC5E,8CAA8C;QAC9C,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,GAAG,MAAM,CAAC,CAAC,GAAG,CAAC,CAAC,KAAK,IAAI,CAAC,KAAK,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE,SAAS,CAAC,CAAC,CAAC;QAC5E,kEAAkE;QAClE,2EAA2E;QAC3E,kCAAkC;QAClC,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,WAAW,CAAC,CAAC,CAAC;QAC1C,OAAO,CAAC,GAAG,CAAC,cAAc,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QACnD,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;IAClB,CAAC;IACD,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,SAAS,EAAE,MAAM,CAAC,CAAC,CAAC;AACzC,CAAC;AAED,SAAS,UAAU,CAAC,CAAa;IAC/B,OAAO,CAAC,GAAG,CAAC,OAAO,aAAa,CAAC,CAAC,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC;IAC1D,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,EAAE,UAAU,CAAC,CAAC,CAAC;AACxC,CAAC;AAED,MAAM,WAAW,GAA0C;IACzD,MAAM,EAAE,EAAE;IACV,IAAI,EAAE,oCAAoC;IAC1C,IAAI,EAAE,2DAA2D;CAClE,CAAC;AAEF,SAAS,UAAU,CAAC,CAAc;IAChC,OAAO,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,IAAI,GAAG,WAAW,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;IACvD,KAAK,MAAM,IAAI,IAAI,CAAC,CAAC,KAAK;QAAE,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC,CAAC;IAC9D,IAAI,CAAC,CAAC,OAAO,KAAK,SAAS;QAAE,OAAO;IACpC,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;IAChB,KAAK,MAAM,IAAI,IAAI,CAAC,CAAC,OAAO,CAAC,OAAO,EAAE,CAAC,KAAK,CAAC,IAAI,CAAC;QAAE,OAAO,CAAC,GAAG,CAAC,SAAS,IAAI,EAAE,CAAC,OAAO,EAAE,CAAC,CAAC;AAC7F,CAAC;AAED,SAAS,cAAc,CAAC,CAAQ;IAC9B,MAAM,CAAC,GAAG,CAAC,CAAC,SAAS,CAAC;IACtB,OAAO,CAAC,GAAG,CAAC,sDAAsD,CAAC,CAAC;IACpE,0EAA0E;IAC1E,yEAAyE;IACzE,oBAAoB;IACpB,IAAI,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC;QACf,OAAO,CAAC,GAAG,CAAC,4EAA4E,CAAC,CAAC;QAC1F,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;QAChB,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,WAAW,IAAI,EAAE,EAAE,MAAM,CAAC,CAAC,CAAC;QAC/C,OAAO;IACT,CAAC;IACD,IAAI,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC;QACd,OAAO,CAAC,GAAG,CAAC,oFAAoF,CAAC,CAAC;QAClG,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;QAChB,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,WAAW,IAAI,EAAE,EAAE,MAAM,CAAC,CAAC,CAAC;QAC/C,OAAO;IACT,CAAC;IACD,IAAI,CAAC,CAAC,QAAQ,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC5B,OAAO,CAAC,GAAG,CAAC,wCAAwC,CAAC,CAAC,OAAO,IAAI,CAAC,CAAC;QACnE,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;QAChB,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,WAAW,IAAI,EAAE,EAAE,MAAM,CAAC,CAAC,CAAC;QAC/C,OAAO;IACT,CAAC;IACD,KAAK,MAAM,CAAC,IAAI,CAAC,CAAC,QAAQ,EAAE,CAAC;QAC3B,MAAM,KAAK,GAAG,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,4BAA4B,CAAC;QAC/D,OAAO,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,EAAE,MAAM,CAAC,CAAC,IAAI,KAAK,CAAC,CAAC,KAAK,QAAQ,KAAK,GAAG,CAAC,CAAC;IACnE,CAAC;IACD,KAAK,MAAM,CAAC,IAAI,CAAC,CAAC,OAAO;QAAE,OAAO,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC,IAAI,KAAK,CAAC,CAAC,EAAE,IAAI,IAAI,CAAC,CAAC,KAAK,IAAI,EAAE,GAAG,EAAE,CAAC,CAAC;IAC3F,KAAK,MAAM,CAAC,IAAI,CAAC,CAAC,QAAQ;QAAE,OAAO,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC,EAAE,IAAI,IAAI,CAAC,CAAC,KAAK,IAAI,EAAE,GAAG,EAAE,CAAC,CAAC;IAC1F,IAAI,CAAC,CAAC,OAAO,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACzB,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;QAChB,OAAO,CAAC,GAAG,CACT,IAAI,CACF,4BAA4B,CAAC,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,8BAA8B,CAAC,CAAC,OAAO,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,MAAM,+BAA+B,CAAC,CAAC,OAAO,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,MAAM,gDAAgD,EAC9P,MAAM,CACP,CACF,CAAC;IACJ,CAAC;AACH,CAAC;AAED;;;GAGG;AACH,SAAS,IAAI,CAAC,IAAY,EAAE,MAAc,EAAE,KAAK,GAAG,EAAE,EAAE,UAAmB;IACzE,MAAM,IAAI,GAAG,UAAU,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,GAAG,MAAM,IAAI,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC;IAC3E,MAAM,GAAG,GAAa,EAAE,CAAC;IACzB,IAAI,IAAI,GAAG,MAAM,CAAC;IAClB,IAAI,GAAG,GAAG,MAAM,CAAC;IACjB,KAAK,MAAM,IAAI,IAAI,IAAI,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,KAAK,CAAC,EAAE,CAAC;QAC5C,IAAI,IAAI,CAAC,MAAM,GAAG,GAAG,CAAC,MAAM,IAAI,IAAI,CAAC,MAAM,GAAG,CAAC,GAAG,IAAI,CAAC,MAAM,GAAG,KAAK,EAAE,CAAC;YACtE,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;YACf,GAAG,GAAG,IAAI,CAAC;YACX,IAAI,GAAG,IAAI,GAAG,IAAI,CAAC;QACrB,CAAC;aAAM,CAAC;YACN,IAAI,GAAG,IAAI,CAAC,MAAM,GAAG,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,GAAG,IAAI,IAAI,IAAI,EAAE,CAAC,CAAC,CAAC,IAAI,GAAG,IAAI,CAAC;QACpE,CAAC;IACH,CAAC;IACD,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACf,OAAO,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AACxB,CAAC;AAED,4EAA4E;AAC5E,SAAS,MAAM,CAAC,IAAY,EAAE,MAAc;IAC1C,OAAO,IAAI,CAAC,KAAK,IAAI,EAAE,EAAE,MAAM,CAAC,CAAC;AACnC,CAAC","sourcesContent":["/**\n * The brief as a person reads it.\n *\n * A module of its own because the brief is the one loam output an agent is\n * expected to FOLLOW rather than parse: `--json` carries the same eight targets,\n * and this decides only how they read. The wrapping matters for that reason —\n * a continuation line indented past its marker cannot be misread as a second\n * bullet, which is what a hand-followed checklist gets wrong first.\n */\nimport { SEVERITY_MARK } from \"../../core/vocabulary/report.js\";\nimport { type Brief } from \"../../core/brief/brief.js\";\nimport { VIA_ALL, type BriefCheck } from \"../../core/brief/checks.js\";\nimport type { BriefTarget } from \"../../core/brief/targets.js\";\n\n/* ------------------------------------------------------------------ */\n/* Text                                                                */\n/* ------------------------------------------------------------------ */\n\n/**\n * `full` is the `--targets` pointer — the sentence naming the run that carries\n * the invariant half of the brief. Its PRESENCE is what narrows this view, so\n * the two views cannot disagree about what `--targets` means: exactly the\n * sections `--targets` omits from `--json` are the sections skipped here.\n * `undefined` is the default brief, unchanged byte for byte.\n */\nexport function render(b: Brief, warnings: string[], full?: string): void {\n  console.log(`adopt ${b.service} — write the baseline into ${b.path}/\\n`);\n  // In the header, before the work: a warning printed after eight artifact\n  // shapes is a warning read after the agent has started writing.\n  for (const w of warnings) {\n    console.log(wrap(`! ${w}`, \"  \"));\n    console.log(\"\");\n  }\n  if (full === undefined) {\n    // First, above even the never-overwrite rule, because the rule is an\n    // instruction and this is the answer to \"what am I looking at\": measured on\n    // the example fleet, this view is over 650 lines and 5,600 words to an\n    // unpaged terminal, and the two rows that actually orient a person —\n    // `model.likec4 create MISSING`, `spec.md create MISSING` — land past line\n    // 450, behind four hundred lines of prose. `--json` is explicitly the agent\n    // contract, so nothing was served by leaving the human view unintroduced.\n    // `--targets` skips it — bullet three describes sections that view omits,\n    // and that view has its own pointer for the same job.\n    printOrientation(b);\n    console.log(wrap(b.rule, \"  \"));\n\n    // Before the artifact table, because the table is the output and this is the\n    // input: an agent that meets the file list first starts writing files.\n    printWalk(b);\n  }\n\n  console.log(\"\\n  artifacts\\n\");\n  // The legend again, next to the thing it decodes. A reader who scrolls back\n  // to the table two hundred lines later arrives at four flags and no key, and\n  // the capital/lowercase distinction is invisible to anyone who has to\n  // remember it rather than read it.\n  console.log(wrap(LEGEND_LINE, \"    \"));\n  console.log(\"\");\n  const width = Math.max(...b.targets.map((t) => t.artifact.length));\n  for (const t of b.targets) {\n    // `edit` is the shared fleet map: the file exists, but \"present\" would read\n    // as \"nothing to do here\", which is the opposite of why it is on the list.\n    const flag = t.action === \"edit\" ? \"UNDRAWN\" : t.exists ? \"present\" : t.required ? \"MISSING\" : \"missing\";\n    console.log(`    ${t.artifact.padEnd(width)}  ${t.action.padEnd(6)}  ${flag.padEnd(7)}  ${t.purpose}`);\n  }\n\n  for (const t of b.targets) printShape(t);\n\n  printLandscape(b);\n\n  if (full === undefined) printChecking(b);\n  else {\n    // The pointer takes the place of the sections it stands for, in the same\n    // position they would have occupied. Anywhere else — a footnote under the\n    // closing instructions, say — and it reads as a cross-reference rather\n    // than as the notice that this brief is not all of the brief.\n    console.log(\"\\n  the rest of the brief\\n\");\n    console.log(wrap(full, \"    \"));\n  }\n\n  console.log(\"\\n  when you are done\\n\");\n  console.log(`    loam validate --service ${b.service} --json    # fix every error`);\n  // The fleet run is not a nicety: --service never reports the landscape\n  // cross-check, so a baseline can pass the line above with the fleet map\n  // never edited at all.\n  console.log(`    loam validate --all --json                        # in the docs repo: the fleet map`);\n  console.log(`    loam vouch --service ${b.service}              # a HUMAN, in the service's own repo`);\n  console.log(\"\");\n  console.log(\n    wrap(\n      \"Leave everything `status: draft`. Vouching is somebody reading the code and saying the document matches it — it is not yours to do, and a status with no digest behind it is a claim with nothing behind it.\",\n      \"    \",\n    ),\n  );\n}\n\n/** The table's four flags, compressed to one terminal line for the scroll-back reader. */\nconst LEGEND_LINE = \"MISSING required · missing optional · present diff it · UNDRAWN add to the map\";\n\n/**\n * A required target whose work is still outstanding.\n *\n * `!t.exists` alone is the wrong test, and the fleet map is the reason: for\n * every repo after its first service `architecture/landscape.likec4` already\n * exists, so `exists` is true while nothing in it resolves to this boundary —\n * which `loam validate --all` grades `landscape.service-unmodelled`, an ERROR.\n * `action` carries that distinction and nothing else does: `edit` is only ever\n * the undrawn fleet map (see `BriefTarget.action`, core/brief/targets.ts).\n */\nfunction outstanding(t: BriefTarget): boolean {\n  return t.required && (!t.exists || t.action === \"edit\");\n}\n\n/**\n * The three sentences that make the rest of the page readable: how much of it\n * is owed, what the table's own convention means, and what the four hundred\n * lines below it are.\n *\n * Every number here is computed from the brief that was just assembled — the\n * outstanding count off `targets`, the section sizes off `walk`, `checks` and\n * `unchecked`. A literal would be right until the next check is added and\n * silently wrong forever after, and this block's whole value is that a reader\n * can trust it instead of scrolling to verify it.\n */\nfunction printOrientation(b: Brief): void {\n  const owed = b.targets.filter(outstanding);\n  console.log(\"  read this first\\n\");\n\n  // What is actually owed, named. The count is the load-bearing half: \"some of\n  // these are required\" is a sentence a reader skips, \"three of the nine, and\n  // here they are\" is one they act on.\n  console.log(\n    bullet(\n      owed.length === 0\n        ? `None of the ${String(b.targets.length)} artifacts below is both required and outstanding — every required one is already there. What is left is optional, or an existing document to diff your findings against.`\n        : `${String(owed.length)} of the ${String(b.targets.length)} artifacts below ${owed.length === 1 ? \"is\" : \"are\"} required and not yet done: ${owed.map((t) => t.artifact).join(\", \")}. Everything else in the table is optional, or already written and wants diffing rather than replacing.`,\n      \"    \",\n    ),\n  );\n  console.log(\"\");\n\n  // The legend, in full. The table prints `MISSING` and `missing` as if the\n  // capitals were emphasis; they are the required/optional distinction, and\n  // nothing on the page said so. `UNDRAWN` needs more than a gloss — it is the\n  // one row that is not this boundary's file at all.\n  console.log(\n    bullet(\n      \"The flags in that table: `MISSING` in capitals is required and not there, lowercase `missing` is optional and not there, `present` means the file exists — diff it, never replace it. `UNDRAWN` marks the one row that is not this boundary's own file: `architecture/landscape.likec4` is the whole system's map and already holds every other boundary, so ADD to it rather than rewriting it. Until an element in it resolves to this directory, `loam validate --all` reports `landscape.service-unmodelled` (error).\",\n      \"    \",\n    ),\n  );\n  console.log(\"\");\n\n  // What the rest of the page is, so a reader who stops here still knows what\n  // they scrolled past — and where the same content lives for an agent, which\n  // is the reader this long body was written for.\n  console.log(\n    bullet(\n      `The rest of this page, in order: the ${String(b.walk.length)}-stop order to read the code in, then the grammar of each artifact — every rule there is one a later check depends on — then the ${String(b.checks.length)} named checks the result will face and the ${String(b.unchecked.length)} statements of what nothing checks. \\`loam adopt --service ${b.service} --json\\` carries the same targets for an agent, and \\`--targets\\` narrows that to only the part that varies by boundary.`,\n      \"    \",\n    ),\n  );\n  console.log(\"\");\n}\n\n/**\n * The invariant half: the frontmatter rules, the checks that run, and the\n * checks that do not exist. A function of its own only so `--targets` can skip\n * all three in one place — the three sections are the exact set `--targets`\n * omits from `--json`, and splitting them here is what keeps that a single\n * decision instead of three that can drift apart.\n */\nfunction printChecking(b: Brief): void {\n  console.log(\"\\n  frontmatter — on every markdown artifact\\n\");\n  for (const [field, what] of Object.entries(b.frontmatter.fields)) {\n    console.log(`    ${field}`);\n    console.log(wrap(what, \"      \"));\n  }\n  console.log(`\\n    never write by hand: ${b.frontmatter.never.join(\", \")}`);\n  console.log(`\\n${wrap(b.frontmatter.why, \"    \")}`);\n\n  // Attribution matters here: the fleet cross-check runs under `--all`, and a\n  // header promising it to `--service` sent agents chasing a finding that\n  // invocation never reports.\n  console.log(`\\n  what \\`loam validate --service ${b.service}\\` then checks\\n`);\n  for (const c of b.checks) {\n    if (c.via !== VIA_ALL) printCheck(c);\n  }\n  console.log(`\\n  and what only \\`loam validate --all\\` surfaces\\n`);\n  for (const c of b.checks) {\n    if (c.via === VIA_ALL) printCheck(c);\n  }\n\n  console.log(\"\\n  what nothing checks\\n\");\n  for (const u of b.unchecked) console.log(bullet(u, \"    \"));\n}\n\n/**\n * The walk, numbered. The numbers are the point: an unordered list of nine\n * places to look reads as nine optional suggestions, and the two stops that fix\n * what the service IS have to happen before the surfaces are enumerated.\n */\nfunction printWalk(b: Brief): void {\n  console.log(\"\\n  read the code in this order — nothing below is written from anything else\\n\");\n  for (const [i, stop] of b.walk.entries()) {\n    // The hang is explicit rather than derived: `wrap` infers one from a leading\n    // `- `, and a numbered stop whose second line starts at the number's own\n    // column reads as the next stop — which for a list whose ORDER is the point\n    // is the one misreading that costs something.\n    console.log(wrap(`${String(i + 1)}. ${stop.where}`, \"    \", 88, \"       \"));\n    // Two more columns than the stop it belongs to: where-to-look and\n    // what-to-take are different sentences, and at one indent the second reads\n    // as a continuation of the first.\n    console.log(wrap(stop.find, \"         \"));\n    console.log(`         → ${stop.lands.join(\", \")}`);\n    console.log(\"\");\n  }\n  console.log(wrap(b.walkClose, \"    \"));\n}\n\nfunction printCheck(c: BriefCheck): void {\n  console.log(`    ${SEVERITY_MARK[c.severity]} ${c.code}`);\n  console.log(wrap(c.what, \"        \"));\n}\n\nconst ACTION_NOTE: Record<BriefTarget[\"action\"], string> = {\n  create: \"\",\n  diff: \"   (exists — diff, do not replace)\",\n  edit: \"   (the whole fleet's file — ADD to it, never rewrite it)\",\n};\n\nfunction printShape(t: BriefTarget): void {\n  console.log(`\\n  ${t.path}${ACTION_NOTE[t.action]}\\n`);\n  for (const rule of t.shape) console.log(bullet(rule, \"    \"));\n  if (t.example === undefined) return;\n  console.log(\"\");\n  for (const line of t.example.trimEnd().split(\"\\n\")) console.log(`      ${line}`.trimEnd());\n}\n\nfunction printLandscape(b: Brief): void {\n  const l = b.landscape;\n  console.log(\"\\n  what the fleet already says about this service\\n\");\n  // The instruction is the same sentence the JSON carries, printed from the\n  // same field — the text view and `--json` cannot drift into briefing two\n  // different writes.\n  if (!l.present) {\n    console.log(\"    architecture/landscape.likec4 does not exist yet — nothing to bind to.\");\n    console.log(\"\");\n    console.log(wrap(l.instruction ?? \"\", \"    \"));\n    return;\n  }\n  if (!l.parses) {\n    console.log(\"    architecture/landscape.likec4 does not parse — bind by hand, and fix it first.\");\n    console.log(\"\");\n    console.log(wrap(l.instruction ?? \"\", \"    \"));\n    return;\n  }\n  if (l.elements.length === 0) {\n    console.log(`    Nothing in the landscape models '${b.service}'.`);\n    console.log(\"\");\n    console.log(wrap(l.instruction ?? \"\", \"    \"));\n    return;\n  }\n  for (const e of l.elements) {\n    const bound = e.bound ? \"bound\" : \"matched by title — bind it\";\n    console.log(`    ${e.id} = ${e.kind} '${e.title}'   (${bound})`);\n  }\n  for (const e of l.inbound) console.log(`    ← ${e.from}  ${e.op ?? `\"${e.title ?? \"\"}\"`}`);\n  for (const e of l.outbound) console.log(`    → ${e.to}  ${e.op ?? `\"${e.title ?? \"\"}\"`}`);\n  if (l.expects.length > 0) {\n    console.log(\"\");\n    console.log(\n      wrap(\n        `openapi.yaml must define ${l.expects.map((o) => `'${o}'`).join(\", \")} — the fleet already calls ${l.expects.length === 1 ? \"it\" : \"them\"}, and a contract that omits ${l.expects.length === 1 ? \"it\" : \"them\"} fails spine.op-undefined the moment it lands.`,\n        \"    \",\n      ),\n    );\n  }\n}\n\n/**\n * Wrap prose so the brief is readable in a terminal. Continuation lines are\n * indented past the marker, so a wrapped bullet cannot be misread as two.\n */\nfunction wrap(text: string, indent: string, width = 88, hangIndent?: string): string {\n  const hang = hangIndent ?? (/^\\s*-\\s/.test(text) ? `${indent}  ` : indent);\n  const out: string[] = [];\n  let line = indent;\n  let pad = indent;\n  for (const word of text.trim().split(/\\s+/)) {\n    if (line.length > pad.length && line.length + 1 + word.length > width) {\n      out.push(line);\n      pad = hang;\n      line = hang + word;\n    } else {\n      line = line.length > pad.length ? `${line} ${word}` : line + word;\n    }\n  }\n  out.push(line);\n  return out.join(\"\\n\");\n}\n\n/** A bullet, wrapped with its continuation lines hanging under the text. */\nfunction bullet(text: string, indent: string): string {\n  return wrap(`- ${text}`, indent);\n}\n"]}
+{"version":3,"file":"render.js","sourceRoot":"","sources":["../../../src/commands/adopt/render.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * The brief as a person reads it.\n *\n * A module of its own because the brief is the one loam output an agent is\n * expected to FOLLOW rather than parse: `--json` carries the same eight targets,\n * and this decides only how they read. The wrapping matters for that reason —\n * a continuation line indented past its marker cannot be misread as a second\n * bullet, which is what a hand-followed checklist gets wrong first.\n */\nimport { SEVERITY_MARK } from \"../../core/vocabulary/report.js\";\nimport { type Brief } from \"../../core/brief/brief.js\";\nimport { VIA_ALL, type BriefCheck } from \"../../core/brief/checks.js\";\nimport type { BriefTarget } from \"../../core/brief/targets.js\";\n\n/* ------------------------------------------------------------------ */\n/* Text                                                                */\n/* ------------------------------------------------------------------ */\n\n/**\n * `full` is the `--targets` pointer — the sentence naming the run that carries\n * the invariant half of the brief. Its PRESENCE is what narrows this view, so\n * the two views cannot disagree about what `--targets` means: exactly the\n * sections `--targets` omits from `--json` are the sections skipped here.\n * `undefined` is the default brief, unchanged byte for byte.\n */\nexport function render(b: Brief, warnings: string[], full?: string): void {\n  console.log(`adopt ${b.service} — write the baseline into ${b.path}/\\n`);\n  // In the header, before the work: a warning printed after eight artifact\n  // shapes is a warning read after the agent has started writing.\n  for (const w of warnings) {\n    console.log(wrap(`! ${w}`, \"  \"));\n    console.log(\"\");\n  }\n  if (full === undefined) {\n    // First, above even the never-overwrite rule, because the rule is an\n    // instruction and this is the answer to \"what am I looking at\": measured on\n    // the example fleet, this view is over 650 lines and 5,600 words to an\n    // unpaged terminal, and the two rows that actually orient a person —\n    // `model.likec4 create MISSING`, `spec.md create MISSING` — land past line\n    // 450, behind four hundred lines of prose. `--json` is explicitly the agent\n    // contract, so nothing was served by leaving the human view unintroduced.\n    // `--targets` skips it — bullet three describes sections that view omits,\n    // and that view has its own pointer for the same job.\n    printOrientation(b);\n    console.log(wrap(b.rule, \"  \"));\n\n    // Before the artifact table, because the table is the output and this is the\n    // input: an agent that meets the file list first starts writing files.\n    printWalk(b);\n  }\n\n  console.log(\"\\n  artifacts\\n\");\n  // The legend again, next to the thing it decodes. A reader who scrolls back\n  // to the table two hundred lines later arrives at four flags and no key, and\n  // the capital/lowercase distinction is invisible to anyone who has to\n  // remember it rather than read it.\n  console.log(wrap(LEGEND_LINE, \"    \"));\n  console.log(\"\");\n  const width = Math.max(...b.targets.map((t) => t.artifact.length));\n  for (const t of b.targets) {\n    // `edit` is the shared fleet map: the file exists, but \"present\" would read\n    // as \"nothing to do here\", which is the opposite of why it is on the list.\n    // Two words for it, because the two states want different work: `UNDRAWN`\n    // when nothing resolves to the service, `EDGELESS` when an element does\n    // and no edge touches it — a reader acting on `UNDRAWN` there would look\n    // for a box that is already on the map.\n    const flag =\n      t.action === \"edit\"\n        ? b.landscape.modelled === true\n          ? \"EDGELESS\"\n          : \"UNDRAWN\"\n        : t.partial === true\n          ? \"PARTIAL\"\n          : t.exists\n            ? \"present\"\n            : t.required\n              ? \"MISSING\"\n              : \"missing\";\n    console.log(`    ${t.artifact.padEnd(width)}  ${t.action.padEnd(6)}  ${flag.padEnd(7)}  ${t.purpose}`);\n  }\n\n  for (const t of b.targets) printShape(t);\n\n  printLandscape(b);\n\n  if (full === undefined) printChecking(b);\n  else {\n    // The pointer takes the place of the sections it stands for, in the same\n    // position they would have occupied. Anywhere else — a footnote under the\n    // closing instructions, say — and it reads as a cross-reference rather\n    // than as the notice that this brief is not all of the brief.\n    console.log(\"\\n  the rest of the brief\\n\");\n    console.log(wrap(full, \"    \"));\n  }\n\n  console.log(\"\\n  when you are done\\n\");\n  console.log(`    loam validate --service ${b.service} --json    # fix every error`);\n  // The fleet run is not a nicety: --service never reports the landscape\n  // cross-check, so a baseline can pass the line above with the fleet map\n  // never edited at all.\n  console.log(`    loam validate --all --json                        # in the docs repo: the fleet map`);\n  console.log(`    loam vouch --service ${b.service}              # a HUMAN, in the service's own repo`);\n  console.log(\"\");\n  console.log(\n    wrap(\n      \"Leave everything `status: draft`. Vouching is somebody reading the code and saying the document matches it — it is not yours to do, and a status with no digest behind it is a claim with nothing behind it.\",\n      \"    \",\n    ),\n  );\n}\n\n/** The table's five flags, compressed to one terminal line for the scroll-back reader. */\nconst LEGEND_LINE =\n  \"MISSING required · missing optional · present diff it · PARTIAL one feature's slice, adopt around it · UNDRAWN add to the map · EDGELESS an element exists, no edge does\";\n\n/**\n * A required target whose work is still outstanding.\n *\n * `!t.exists` alone is the wrong test, and the fleet map is the reason: for\n * every repo after its first service `architecture/landscape.likec4` already\n * exists, so `exists` is true while nothing in it resolves to this boundary —\n * which `loam validate --all` grades `landscape.service-unmodelled`, an ERROR.\n * `action` carries that distinction and nothing else does: `edit` is only ever\n * the fleet map still owed — undrawn, or drawn with no edge touching it (see\n * `BriefTarget.action`, core/brief/targets.ts).\n */\nfunction outstanding(t: BriefTarget): boolean {\n  return t.required && (!t.exists || t.action === \"edit\" || t.partial === true);\n}\n\n/**\n * The three sentences that make the rest of the page readable: how much of it\n * is owed, what the table's own convention means, and what the four hundred\n * lines below it are.\n *\n * Every number here is computed from the brief that was just assembled — the\n * outstanding count off `targets`, the section sizes off `walk`, `checks` and\n * `unchecked`. A literal would be right until the next check is added and\n * silently wrong forever after, and this block's whole value is that a reader\n * can trust it instead of scrolling to verify it.\n */\nfunction printOrientation(b: Brief): void {\n  const owed = b.targets.filter(outstanding);\n  console.log(\"  read this first\\n\");\n\n  // What is actually owed, named. The count is the load-bearing half: \"some of\n  // these are required\" is a sentence a reader skips, \"three of the nine, and\n  // here they are\" is one they act on.\n  console.log(\n    bullet(\n      owed.length === 0\n        ? `None of the ${String(b.targets.length)} artifacts below is both required and outstanding — every required one is already there. What is left is optional, or an existing document to diff your findings against.`\n        : `${String(owed.length)} of the ${String(b.targets.length)} artifacts below ${owed.length === 1 ? \"is\" : \"are\"} required and not yet done: ${owed.map((t) => t.artifact).join(\", \")}. Everything else in the table is optional, or already written and wants diffing rather than replacing.`,\n      \"    \",\n    ),\n  );\n  console.log(\"\");\n\n  // The legend, in full. The table prints `MISSING` and `missing` as if the\n  // capitals were emphasis; they are the required/optional distinction, and\n  // nothing on the page said so. `UNDRAWN` needs more than a gloss — it is the\n  // one row that is not this boundary's file at all.\n  console.log(\n    bullet(\n      \"The flags in that table: `MISSING` in capitals is required and not there, lowercase `missing` is optional and not there, `present` means the file exists — diff it, never replace it. `PARTIAL` is a spec.md marked `adoption: partial`: one archived feature's slice, so keep every requirement in it, write the rest of the service around them, and then delete the `adoption: partial` line. `UNDRAWN` and `EDGELESS` mark the one row that is not this boundary's own file: `architecture/landscape.likec4` is the whole system's map and already holds every other boundary, so ADD to it rather than rewriting it. Until an element in it resolves to this directory, `loam validate --all` reports `landscape.service-unmodelled` (error); `EDGELESS` means an element already does and no edge touches it, so what the map lacks is the calls in and out of it, never a second element.\",\n      \"    \",\n    ),\n  );\n  console.log(\"\");\n\n  // What the rest of the page is, so a reader who stops here still knows what\n  // they scrolled past — and where the same content lives for an agent, which\n  // is the reader this long body was written for.\n  console.log(\n    bullet(\n      `The rest of this page, in order: the ${String(b.walk.length)}-stop order to read the code in, then the grammar of each artifact — every rule there is one a later check depends on — then the ${String(b.checks.length)} named checks the result will face and the ${String(b.unchecked.length)} statements of what nothing checks. \\`loam adopt --service ${b.service} --json\\` carries the same targets for an agent, and \\`--targets\\` narrows that to only the part that varies by boundary.`,\n      \"    \",\n    ),\n  );\n  console.log(\"\");\n}\n\n/**\n * The invariant half: the frontmatter rules, the checks that run, and the\n * checks that do not exist. A function of its own only so `--targets` can skip\n * all three in one place — the three sections are the exact set `--targets`\n * omits from `--json`, and splitting them here is what keeps that a single\n * decision instead of three that can drift apart.\n */\nfunction printChecking(b: Brief): void {\n  console.log(\"\\n  frontmatter — on every markdown artifact\\n\");\n  for (const [field, what] of Object.entries(b.frontmatter.fields)) {\n    console.log(`    ${field}`);\n    console.log(wrap(what, \"      \"));\n  }\n  console.log(`\\n    never write by hand: ${b.frontmatter.never.join(\", \")}`);\n  console.log(`\\n${wrap(b.frontmatter.why, \"    \")}`);\n\n  // Attribution matters here: the fleet cross-check runs under `--all`, and a\n  // header promising it to `--service` sent agents chasing a finding that\n  // invocation never reports.\n  console.log(`\\n  what \\`loam validate --service ${b.service}\\` then checks\\n`);\n  for (const c of b.checks) {\n    if (c.via !== VIA_ALL) printCheck(c);\n  }\n  console.log(`\\n  and what only \\`loam validate --all\\` surfaces\\n`);\n  for (const c of b.checks) {\n    if (c.via === VIA_ALL) printCheck(c);\n  }\n\n  console.log(\"\\n  what nothing checks\\n\");\n  for (const u of b.unchecked) console.log(bullet(u, \"    \"));\n}\n\n/**\n * The walk, numbered. The numbers are the point: an unordered list of nine\n * places to look reads as nine optional suggestions, and the two stops that fix\n * what the service IS have to happen before the surfaces are enumerated.\n */\nfunction printWalk(b: Brief): void {\n  console.log(\"\\n  read the code in this order — nothing below is written from anything else\\n\");\n  for (const [i, stop] of b.walk.entries()) {\n    // The hang is explicit rather than derived: `wrap` infers one from a leading\n    // `- `, and a numbered stop whose second line starts at the number's own\n    // column reads as the next stop — which for a list whose ORDER is the point\n    // is the one misreading that costs something.\n    console.log(wrap(`${String(i + 1)}. ${stop.where}`, \"    \", 88, \"       \"));\n    // Two more columns than the stop it belongs to: where-to-look and\n    // what-to-take are different sentences, and at one indent the second reads\n    // as a continuation of the first.\n    console.log(wrap(stop.find, \"         \"));\n    console.log(`         → ${stop.lands.join(\", \")}`);\n    console.log(\"\");\n  }\n  console.log(wrap(b.walkClose, \"    \"));\n}\n\nfunction printCheck(c: BriefCheck): void {\n  console.log(`    ${SEVERITY_MARK[c.severity]} ${c.code}`);\n  console.log(wrap(c.what, \"        \"));\n}\n\nconst ACTION_NOTE: Record<BriefTarget[\"action\"], string> = {\n  create: \"\",\n  diff: \"   (exists — diff, do not replace)\",\n  edit: \"   (the whole fleet's file — ADD to it, never rewrite it)\",\n};\n\nfunction printShape(t: BriefTarget): void {\n  console.log(`\\n  ${t.path}${ACTION_NOTE[t.action]}\\n`);\n  for (const rule of t.shape) console.log(bullet(rule, \"    \"));\n  if (t.example === undefined) return;\n  console.log(\"\");\n  for (const line of t.example.trimEnd().split(\"\\n\")) console.log(`      ${line}`.trimEnd());\n}\n\nfunction printLandscape(b: Brief): void {\n  const l = b.landscape;\n  console.log(\"\\n  what the fleet already says about this service\\n\");\n  // The instruction is the same sentence the JSON carries, printed from the\n  // same field — the text view and `--json` cannot drift into briefing two\n  // different writes.\n  if (!l.present) {\n    console.log(\"    architecture/landscape.likec4 does not exist yet — nothing to bind to.\");\n    console.log(\"\");\n    console.log(wrap(l.instruction ?? \"\", \"    \"));\n    return;\n  }\n  if (!l.parses) {\n    // Not \"architecture/landscape.likec4 does not parse\": the map is the whole\n    // `architecture/` project, so the file that broke is usually a sibling —\n    // and this line accused the landscape of errors `validate --all` blamed on\n    // a palette. The instruction printed directly below names the documents\n    // that actually failed, so the headline says the project and nothing more.\n    console.log(\"    The fleet map (architecture/) does not parse — fix that first; the files are named below.\");\n    console.log(\"\");\n    console.log(wrap(l.instruction ?? \"\", \"    \"));\n    printExpects(l);\n    return;\n  }\n  if (l.elements.length === 0) {\n    console.log(`    Nothing in the landscape models '${b.service}'.`);\n    console.log(\"\");\n    console.log(wrap(l.instruction ?? \"\", \"    \"));\n    return;\n  }\n  for (const e of l.elements) {\n    const bound = e.bound ? \"bound\" : \"matched by title — bind it\";\n    console.log(`    ${e.id} = ${e.kind} '${e.title}'   (${bound})`);\n  }\n  for (const e of l.inbound) console.log(`    ← ${e.from}  ${e.op ?? `\"${e.title ?? \"\"}\"`}`);\n  for (const e of l.outbound) console.log(`    → ${e.to}  ${e.op ?? `\"${e.title ?? \"\"}\"`}`);\n  // The edgeless state: an element and no edge lines above it. The modelled\n  // branch used to return here without ever printing an instruction, which\n  // is how the text view briefed \"the map owes nothing\" over two empty lists.\n  if (l.instruction !== null) {\n    console.log(\"\");\n    console.log(wrap(l.instruction, \"    \"));\n  }\n  printExpects(l);\n}\n\n/**\n * What the fleet already calls on this service, and why the contract owes it.\n *\n * Printed in the unparseable branch as well as the healthy one: the landscape\n * FILE still answers who calls this service when a sibling under `architecture/`\n * breaks the project, and it is what decides whether `openapi.yaml` is flagged\n * required — so a reader who is told the map is unreadable still gets the\n * evidence behind that row.\n */\nfunction printExpects(l: Brief[\"landscape\"]): void {\n  if (l.expects.length === 0) return;\n  const it = l.expects.length === 1 ? \"it\" : \"them\";\n  console.log(\"\");\n  console.log(\n    wrap(\n      `openapi.yaml must define ${l.expects.map((o) => `'${o}'`).join(\", \")} — the fleet already calls ${it}, and a contract that omits ${it} fails spine.op-undefined the moment it lands.`,\n      \"    \",\n    ),\n  );\n}\n\n/**\n * Wrap prose so the brief is readable in a terminal. Continuation lines are\n * indented past the marker, so a wrapped bullet cannot be misread as two.\n */\nfunction wrap(text: string, indent: string, width = 88, hangIndent?: string): string {\n  const hang = hangIndent ?? (/^\\s*-\\s/.test(text) ? `${indent}  ` : indent);\n  const out: string[] = [];\n  let line = indent;\n  let pad = indent;\n  for (const word of text.trim().split(/\\s+/)) {\n    if (line.length > pad.length && line.length + 1 + word.length > width) {\n      out.push(line);\n      pad = hang;\n      line = hang + word;\n    } else {\n      line = line.length > pad.length ? `${line} ${word}` : line + word;\n    }\n  }\n  out.push(line);\n  return out.join(\"\\n\");\n}\n\n/** A bullet, wrapped with its continuation lines hanging under the text. */\nfunction bullet(text: string, indent: string): string {\n  return wrap(`- ${text}`, indent);\n}\n"]}