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

package/CHANGELOG.md

@@ -2,6 +2,55 @@
 
 All notable project changes are recorded here. The format follows Keep a Changelog, and release versions follow Semantic Versioning.
 
+## [Unreleased]
+
+## [0.1.0-beta.2] - 2026-08-07
+
+Still a prerelease, still under the `beta` dist-tag: the 5–10 service pilot has not run yet, and this release changes what `loam init` leaves in a repository, which is exactly the kind of thing a pilot is for. Two new commands, that change to the generated files, and a code-quality pass over `src/` with the defects it turned up. The refactoring half is invisible by construction; what follows is only the part a user can observe.
+
+### Added
+
+- **`loam explore [<service>...]`** — read the fleet around a change nobody has written down yet, and write nothing. It answers the one question `loam new` takes as an argument: which services a feature touches. For each seed it reports the ring one hop out in the fleet map, each service's maturity rung and living operations, who already calls whom, the active features already covering the same services, and the literal `loam new` line the seeds imply. `--op <operationId>` seeds from an operation when you know the call but not who owns it; `--as <FEAT>` names the feature in the suggested line. A seed naming no `services/<id>/` is reported with its near-misses rather than refused — a feature may be introducing that service, and a typo looks identical until you read the list. The neighbours are deliberately **not** folded into the suggested command: loam knows those services are connected, not whether you change them.
+- **`loam instructions [<workflow>] [args...]`** — print one of the six workflow protocols (`loam-adopt`, `loam-feature`, `loam-implement`, `loam-check`, `loam-verify`, `loam-ship`) with `$1`, `$2` filled in from the arguments given. With no argument it lists them. It is the only command that reads no `loam.json` and no docs repo, deliberately: `loam-adopt`'s own first step is to run `loam init` when there is no config, so it cannot be the step that requires one.
+- **[WORKFLOW.md](WORKFLOW.md)** — the working protocol as a document: the artifact graph and its five derived states, what actually gates and what only advises, the six workflows, how an agent drives the cycle from `--json`, and why there is no task-list artifact.
+
+### Changed — what `loam init` writes into a command or skill file
+
+- **A generated file is now a pointer at `loam instructions`, not a copy of the protocol.** It carries the workflow's purpose and its spine — the verbs, in order — and defers this release's flags, finding codes and fix tables to the binary; a fresh `.claude/commands/` drops from about 53 KB to about 11 KB, and the finding-code tables move with it. The protocol itself is unchanged and complete; only its delivery moved. The reason is that the two go stale in opposite directions and only one is fixable: loam never regenerates a generated file (your edits outrank the template, and that is not changing), so a protocol copied into a repository will eventually describe a different loam with total confidence, while a pointer cannot. `doctor.agent-files-stale` still reports a file whose version stamp has fallen behind, and now has almost nothing to be wrong about.
+- **Nothing rewrites an existing file.** A repository scaffolded by an earlier loam keeps exactly the files it was given, full protocol text and all — re-running `loam init` over it leaves them byte-unchanged. The version stamp is how you tell, and `loam doctor` raises `doctor.agent-files-stale` against them only once this binary's stamp is ahead of theirs. To take the new form, delete the files and re-run `loam init`.
+- Both new commands reuse the existing refusal codes (`invalid-option`, `unknown-target`). No stable code was added, changed or removed.
+- **The feature-id grammar has one home.** It was spelled privately in `loam new` and again in the OpenSpec migration; `core/ids.ts` owns it now, so an id one command accepts cannot be an id the other refuses. The only user-visible edge is wording: `migrate-openspec`'s `mapping.feature-id-invalid` message now ends with the same "e.g. FEAT-101 or BUG-42" example every other refusal gives. The code is unchanged.
+
+### Fixed — commands that wrote or attested on evidence they had not checked
+
+- **`archive` no longer installs an unreadable feature contract as the living one.** A feature `openapi.yaml` that does not parse as an OpenAPI document was planned verbatim into `services/<svc>/openapi.yaml` and reported `ok: true`; every other command reads `readOpenapi`'s `unreadable` flag, and the one that writes was the one that did not. It now refuses with `merge-failed`, naming the file. The same code now answers when the contract is being created rather than merged — that case used to escape as `internal`.
+- **`verify --record` no longer attests when it could not check the report.** The committed-report binding check tested for git's exit code 1 and nothing else, so a `git diff` killed by a signal — a CI timeout, the OOM killer, a fork failure — skipped the check and wrote the attestation anyway. A run that cannot reach an exit status is now a refusal that says git could not be run to completion.
+- **An interrupted `archive` can be retried on a docs repo composed of symlinks.** Checking whether the snapshot was stale resolved the manifest's paths through a symlink test meant for writes, so a `services/<svc>/` mounted from a sibling checkout — a layout every walk of the repo follows on purpose — turned every retry into a permanent refusal. That check only reads a file and compares a digest; containment is now judged without resolving the mount. `unarchive`, which writes the pre-image back, deliberately keeps the stricter test.
+- **A malformed `.loam-before/manifest.json` or `.loam-lock` is answered, not assumed.** Both were read through a cast: well-formed JSON that was not an object slipped past as "a different loam", and a bare `null` threw a `TypeError` out of the refusal itself. They now answer `commit-interrupted` and `docs-busy` respectively — the codes that case always deserved.
+- **A `spec.md` whose bytes are UTF-16LE is refused on the write path.** The write path's UTF-8 guard was a weaker copy of the read path's and missed exactly the file the read path had been hardened against: such a document parsed as zero requirements, so a merge computed over an empty baseline and wrote that back.
+
+### Fixed — user errors reported as `internal`
+
+- **`list`, `show` and `validate` report `repository-unavailable`** where a filesystem failure carries no path — a directory where `spec.md` belongs reports EISDIR with no `path`, which defeated the guard. `status` had this fix; the other three copies of the same catch block did not.
+- **`loam.json` that cannot be read reports `config-invalid`.** The read sat one line above its own `try`, so a config file that was a directory, or carried a restrictive permission bit, crashed every command in the CLI.
+- **`loam new` refuses instead of scaffolding into a directory that is not a docs repo**, and **`loam adopt` refuses (`docs-missing`)** instead of briefing an agent to write a baseline into a docs repo that does not exist. Both previously exited 0.
+
+### Fixed — checks that answered differently depending on where they were asked
+
+- **A relocated operation grades the same under `validate`, `status` and `archive`.** `FleetContext` carried a second implementation of `serviceOperationIds` that interleaved removals with upserts, so an operation removed at one path and defined at another answered "undefined" or "defined" depending on which the author spelled first — and `spec-api.op-undefined` is a gating error.
+- **`c4.op-ungoverned` joins per service.** Operation ids are unique only within a contract, so an operation governed on one service suppressed the warning for an unrelated service that shared its name.
+- **`api.covered` no longer counts a REMOVED requirement as governing.** An operation whose only governing requirement was removed now reports `api.ungoverned` (a warning; nothing about gating or exit codes changes).
+- **`loam status` (fleet form) reports `blocked` for a repo holding an interrupted commit journal**, agreeing with the per-feature form, which already did. It previously said `done` and "ship it" over a tree the other form called blocked.
+- **`loam delta` exits 1 when the feature's `openapi.yaml` does not parse**, matching the rule the architecture axis already had, and its `--json` payload carries an `openapi` key saying so. An unparseable contract used to project as "no operations".
+
+### Fixed — deletion that reached outside the repository
+
+- **`loam gherkin` orphan cleanup no longer follows a symlinked directory out of the repo.** Enumeration follows symlinks by design, so a planted `<gherkinDir>/loam/sub -> /outside` produced orphan paths that `unlink` resolved and deleted elsewhere. A symlinked `.feature` sitting directly in `loam/` is still removed — the link goes, its target survives — which is the distinction the guard now draws.
+
+### Changed — internal structure
+
+No behaviour depends on this, and it is recorded because the next contributor will notice it: the eight runtime import cycles in `src/core/` are gone, five helper modules were extracted from the modules that happened to hold them (`document-bytes`, `records`, `steps`, `concurrency`, and the docs-repo gate), and the duplicated spellings of six shared rules now have one home each. `docs/CODE-STYLE.md` records the conventions and the defect behind each one.
+
 ## [0.1.0-beta.1] - 2026-08-06
 
 The first published release, and a prerelease on purpose: it ships under the `beta` dist-tag, not `latest`. This entry covers the pre-publication hardening pass. Most of it is not new capability — it is the difference between a command that reports a problem and one that was quietly blind to it, and in four places it is the difference between an undo that works and one that certifies text nobody wrote. Grouped by what a user would notice.

package/README.md

@@ -141,6 +141,8 @@ The same split runs the done-check. `verify` cannot compare a generated model to
 | `loam status [<FEAT>]` | Where the work stands and what to do next, as a projection over the two gates. Derived every run; writes nothing. |
 | `loam doctor` | Read-only preflight for runtime, config, docs-repo access, fleet roots, counts, and the current service binding. Blockers exit 1; incomplete optional bindings stay warnings. |
 | `loam dependencies [<FEAT>]` | Derive the active-feature dependency graph and same-identity conflicts from requirement deltas and OpenAPI operationIds. Optional focus includes transitive prerequisites. |
+| `loam explore [<service>...]` | Read the fleet around a change nobody has written down yet: the ring one hop out, each service's maturity and living operations, the features already in flight over the same ground, and the `loam new` line the seeds imply. `--op <id>` seeds from an operation. Writes nothing. |
+| `loam instructions [<workflow>] [args...]` | Print one of the six workflow protocols, `$1`/`$2` filled in — version-matched to this binary, which is what the generated command and skill files point at. Reads no config. |
 | `loam new <FEAT> [--title <t>] [--touches <id>] [--new-service <id>]` | Scaffold a feature: intent, C4 delta, and a requirement delta for every service named by `--touches` / `--new-service` (both repeatable). The title is optional and becomes the directory slug. |
 | `loam show <service\|FEAT>` | Everything loam knows about one service or feature. |
 | `loam adopt --service <id>` | Brief an agent to write this service's baseline into the docs repo as `draft`. Writes nothing. |
@@ -191,7 +193,9 @@ API retirement is explicit and reviewable: a feature marks the exact path/method
 
 Which tools is detected from the repo: `init` scans each of the 20 tools it knows for its own marker paths — usually just its dot-directory, but Copilot's are the files *inside* `.github/`, because almost every repo has a `.github/` and almost none of them means Copilot. The twenty are Claude Code, Cursor, GitHub Copilot, Gemini CLI, opencode, Cline, Amazon Q, Antigravity, Auggie, Codex, Continue, Crush, Devin, Factory, Junie, Kilo Code, Kiro, Qwen, Roo Code and Trae. It writes for the ones it finds, and falls back to Claude Code when it finds none. `--tools <ids>|all` overrides the scan; an unknown id is refused, not skipped. What it wrote for is recorded in `loam.json` as `agentTools`, which is how `loam doctor` reports a command or skill file that a newer loam would lay down (`doctor.agent-files-missing`) without mistaking a tool nobody selected for one that fell behind — and a repo that asked for one delivery only (`--no-skills`, `--no-commands`) is not reported as missing the other.
 
-**Nothing is ever overwritten and nothing is ever refreshed**, and that is the whole difference from `openspec update`: your edits to a generated file outrank the template, so drift is reported and never repaired. To make that reportable at all, every generated command and skill body opens with `<!-- generated by loam vX.Y.Z -->`; `loam doctor` reads **only that line** and raises `doctor.agent-files-stale` for a file carrying no stamp or an older one. It never compares bodies — "your file differs from the template" is one step from offering to rewrite it. The fix is a human's: read the file, then bump the stamp, or delete it and re-run `loam init`. The AGENTS.md version stamp (`agents.stale`) works the same way. Running a tool loam has no adapter for? Point it at `AGENTS.md` — the commands are thin wrappers over the CLI, so any runner that can read a file and exec `loam` has everything.
+**A generated file is a pointer, not a protocol.** It carries what does not move between releases — what the workflow is for, and the verbs in order — and defers this release's flags, finding codes and fix tables to `loam instructions <workflow>`, which ships inside the binary you are about to run. That split exists because the two go stale in opposite directions and only one of them is fixable: a file written once and never regenerated will eventually describe a different loam with total confidence, while the command cannot. `loam instructions` reads no `loam.json` and no docs repo, deliberately — `loam-adopt`'s own first step is to run `loam init` when there is no config, so it cannot be the step that requires one.
+
+**Nothing is ever overwritten and nothing is ever refreshed**, and that is the whole difference from `openspec update`: your edits to a generated file outrank the template, so drift is reported and never repaired. To make that reportable at all, every generated command and skill body opens with `<!-- generated by loam vX.Y.Z -->`; `loam doctor` reads **only that line** and raises `doctor.agent-files-stale` for a file carrying no stamp or an older one. It never compares bodies — "your file differs from the template" is one step from offering to rewrite it. The fix is a human's: read the file, then bump the stamp, or delete it and re-run `loam init`. The AGENTS.md version stamp (`agents.stale`) works the same way. A repo scaffolded by an older loam keeps the files it was given, protocol text and all — nothing rewrites them, and the stamp is how you know. Running a tool loam has no adapter for? Point it at `AGENTS.md` — the commands are thin wrappers over the CLI, so any runner that can read a file and exec `loam` has everything.
 
 ## Fleet scale
 
@@ -201,6 +205,7 @@ The shape that has been measured, on a generated 120-service fleet with 400 and
 
 ## Docs
 
+- [WORKFLOW.md](WORKFLOW.md) — the working protocol: the artifact graph and its derived states, what gates and what only advises, the six workflows, and how an agent drives the whole cycle from `--json`.
 - [SCHEMA.md](SCHEMA.md) — the docs-repo layout, each artifact's grammar, and the decisions behind them: the coherence rules, how `archive` writes and `unarchive` undoes, operating at fleet scale.
 - [COMPARISON.md](COMPARISON.md) — loam vs OpenSpec, honestly: seven axes, when OpenSpec is enough, what loam refuses to borrow.
 - [MIGRATING-from-OpenSpec.md](MIGRATING-from-OpenSpec.md) — moving an OpenSpec repo onto loam: what maps, what is lost, what must be added.

package/dist/cli.js

@@ -18,6 +18,8 @@ import { registerVerify } from "./commands/verify.js";
 import { registerVouch } from "./commands/vouch.js";
 import { registerDoctor } from "./commands/doctor.js";
 import { registerDependencies } from "./commands/dependencies.js";
+import { registerExplore } from "./commands/explore.js";
+import { registerInstructions } from "./commands/instructions.js";
 import { registerMigrateOpenSpec } from "./commands/migrate-openspec.js";
 import { emitJsonError } from "./core/json.js";
 import { LOAM_VERSION } from "./core/version.js";
@@ -46,6 +48,7 @@ export function buildProgram() {
     registerInit(program);
     registerAdopt(program);
     registerList(program);
+    registerExplore(program);
     registerNew(program);
     registerShow(program);
     registerStatus(program);
@@ -59,6 +62,7 @@ export function buildProgram() {
     registerVouch(program);
     registerDoctor(program);
     registerDependencies(program);
+    registerInstructions(program);
     registerMigrateOpenSpec(program);
     return program;
 }

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.js\";\nimport { registerAdopt } from \"./commands/adopt.js\";\nimport { registerList } from \"./commands/list.js\";\nimport { registerNew } from \"./commands/new.js\";\nimport { registerShow } from \"./commands/show.js\";\nimport { registerStatus } from \"./commands/status.js\";\nimport { registerDelta } from \"./commands/delta.js\";\nimport { registerGherkin } from \"./commands/gherkin.js\";\nimport { registerRebase } from \"./commands/rebase.js\";\nimport { registerArchive } from \"./commands/archive.js\";\nimport { registerUnarchive } from \"./commands/unarchive.js\";\nimport { registerValidate } from \"./commands/validate.js\";\nimport { registerVerify } from \"./commands/verify.js\";\nimport { registerVouch } from \"./commands/vouch.js\";\nimport { registerDoctor } from \"./commands/doctor.js\";\nimport { registerDependencies } from \"./commands/dependencies.js\";\nimport { registerMigrateOpenSpec } from \"./commands/migrate-openspec.js\";\nimport { emitJsonError } from \"./core/json.js\";\nimport { LOAM_VERSION } from \"./core/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 spec framework for microservice fleets\")\n    .version(LOAM_VERSION);\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  registerNew(program);\n  registerShow(program);\n  registerStatus(program);\n  registerDelta(program);\n  registerGherkin(program);\n  registerRebase(program);\n  registerArchive(program);\n  registerUnarchive(program);\n  registerValidate(program);\n  registerVerify(program);\n  registerVouch(program);\n  registerDoctor(program);\n  registerDependencies(program);\n  registerMigrateOpenSpec(program);\n\n  return program;\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.js\";\nimport { registerAdopt } from \"./commands/adopt.js\";\nimport { registerList } from \"./commands/list.js\";\nimport { registerNew } from \"./commands/new.js\";\nimport { registerShow } from \"./commands/show.js\";\nimport { registerStatus } from \"./commands/status.js\";\nimport { registerDelta } from \"./commands/delta.js\";\nimport { registerGherkin } from \"./commands/gherkin.js\";\nimport { registerRebase } from \"./commands/rebase.js\";\nimport { registerArchive } from \"./commands/archive.js\";\nimport { registerUnarchive } from \"./commands/unarchive.js\";\nimport { registerValidate } from \"./commands/validate.js\";\nimport { registerVerify } from \"./commands/verify.js\";\nimport { registerVouch } from \"./commands/vouch.js\";\nimport { registerDoctor } from \"./commands/doctor.js\";\nimport { registerDependencies } from \"./commands/dependencies.js\";\nimport { registerExplore } from \"./commands/explore.js\";\nimport { registerInstructions } from \"./commands/instructions.js\";\nimport { registerMigrateOpenSpec } from \"./commands/migrate-openspec.js\";\nimport { emitJsonError } from \"./core/json.js\";\nimport { LOAM_VERSION } from \"./core/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 spec framework for microservice fleets\")\n    .version(LOAM_VERSION);\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  registerNew(program);\n  registerShow(program);\n  registerStatus(program);\n  registerDelta(program);\n  registerGherkin(program);\n  registerRebase(program);\n  registerArchive(program);\n  registerUnarchive(program);\n  registerValidate(program);\n  registerVerify(program);\n  registerVouch(program);\n  registerDoctor(program);\n  registerDependencies(program);\n  registerInstructions(program);\n  registerMigrateOpenSpec(program);\n\n  return program;\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"]}

package/dist/commands/adopt.js

@@ -2,9 +2,11 @@ import { existsSync } from "node:fs";
 import { closeIds } from "../core/arch.js";
 import { loadConfig } from "../core/config.js";
 import { InvalidIdError, assertServiceId } from "../core/ids.js";
-import { emitJson, fail, reportNoConfig } from "../core/json.js";
+import { emitJson, fail, NO_SERVICE_MESSAGE, reportNoConfig } from "../core/json.js";
 import { DocsRepoUnavailableError, listServices, servicePaths } from "../core/repo.js";
+import { SEVERITY_MARK } from "../core/report.js";
 import { serviceBrief, VIA_ALL } from "../core/brief.js";
+import { docsRepoReady } from "./docs-repo-gate.js";
 /**
  * What is suspicious about this invocation without being wrong.
  *
@@ -60,9 +62,21 @@ export function registerAdopt(program) {
             reportNoConfig(json);
             return;
         }
+        // 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,
+        // with the near-miss warning below silently switched off (listServices
+        // throws, `invocationWarnings` swallows it and returns nothing). The same
+        // refusal every enumerating command owes; see docs-repo-gate.ts.
+        //
+        // `docs`, not `services`: a docs repo that has no services/ yet is exactly
+        // the repo adopt exists to fill, and refusing there would refuse the
+        // command's own first use.
+        if (!docsRepoReady(json, config.docsDir, "docs"))
+            return;
         const service = opts.service ?? config.service;
         if (service === undefined) {
-            fail(json, "invalid-option", "No service. Pass --service <id> or set it in loam.json.");
+            fail(json, "invalid-option", NO_SERVICE_MESSAGE);
             return;
         }
         // The id becomes `services/<id>/` in a shared repo, so it goes through the
@@ -142,7 +156,7 @@ function render(b, warnings) {
     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.", "    "));
 }
 function printCheck(c) {
-    console.log(`    ${c.severity === "error" ? "✗" : "⚠"} ${c.code}`);
+    console.log(`    ${SEVERITY_MARK[c.severity]} ${c.code}`);
     console.log(wrap(c.what, "        "));
 }
 const ACTION_NOTE = {

package/dist/commands/adopt.js.map

@@ -1 +1 @@
-{"version":3,"file":"adopt.js","sourceRoot":"","sources":["../../src/commands/adopt.ts"],"names":[],"mappings":"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","sourcesContent":["/**\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 */\nimport type { Command } from \"commander\";\nimport { existsSync } from \"node:fs\";\nimport { closeIds } from \"../core/arch.js\";\nimport { loadConfig } from \"../core/config.js\";\nimport { InvalidIdError, assertServiceId } from \"../core/ids.js\";\nimport { emitJson, fail, reportNoConfig } from \"../core/json.js\";\nimport { DocsRepoUnavailableError, listServices, servicePaths } from \"../core/repo.js\";\nimport { serviceBrief, VIA_ALL, type Brief, type BriefCheck, type BriefTarget } from \"../core/brief.js\";\n\ninterface AdoptOptions {\n  service?: string;\n  json?: boolean;\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: string,\n  service: string,\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  if (existsSync(servicePaths(docsDir, service).dir)) return warnings;\n\n  // A near-miss is only computable when the docs repo can be enumerated at all;\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  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\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(\"--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 loadConfig();\n      if (!config) {\n        reportNoConfig(json);\n        return;\n      }\n\n      const service = opts.service ?? config.service;\n      if (service === undefined) {\n        fail(json, \"invalid-option\", \"No service. Pass --service <id> or set it in loam.json.\");\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      const brief = await serviceBrief(config.docsDir, service);\n      if (json) {\n        emitJson({ ...brief, warnings });\n        return;\n      }\n      render(brief, warnings);\n    });\n}\n\n/* ------------------------------------------------------------------ */\n/* Text                                                                */\n/* ------------------------------------------------------------------ */\n\nfunction render(b: Brief, warnings: 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  console.log(wrap(b.rule, \"  \"));\n\n  console.log(\"\\n  artifacts\\n\");\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  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  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\nfunction printCheck(c: BriefCheck): void {\n  console.log(`    ${c.severity === \"error\" ? \"✗\" : \"⚠\"} ${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): string {\n  const hang = /^\\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":"adopt.js","sourceRoot":"","sources":["../../src/commands/adopt.ts"],"names":[],"mappings":"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","sourcesContent":["/**\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 */\nimport type { Command } from \"commander\";\nimport { existsSync } from \"node:fs\";\nimport { closeIds } from \"../core/arch.js\";\nimport { loadConfig } from \"../core/config.js\";\nimport { InvalidIdError, assertServiceId } from \"../core/ids.js\";\nimport { emitJson, fail, NO_SERVICE_MESSAGE, reportNoConfig } from \"../core/json.js\";\nimport { DocsRepoUnavailableError, listServices, servicePaths } from \"../core/repo.js\";\nimport { SEVERITY_MARK } from \"../core/report.js\";\nimport { serviceBrief, VIA_ALL, type Brief, type BriefCheck, type BriefTarget } from \"../core/brief.js\";\nimport { docsRepoReady } from \"./docs-repo-gate.js\";\n\ninterface AdoptOptions {\n  service?: string;\n  json?: boolean;\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: string,\n  service: string,\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  if (existsSync(servicePaths(docsDir, service).dir)) return warnings;\n\n  // A near-miss is only computable when the docs repo can be enumerated at all;\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  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\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(\"--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 loadConfig();\n      if (!config) {\n        reportNoConfig(json);\n        return;\n      }\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      const brief = await serviceBrief(config.docsDir, service);\n      if (json) {\n        emitJson({ ...brief, warnings });\n        return;\n      }\n      render(brief, warnings);\n    });\n}\n\n/* ------------------------------------------------------------------ */\n/* Text                                                                */\n/* ------------------------------------------------------------------ */\n\nfunction render(b: Brief, warnings: 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  console.log(wrap(b.rule, \"  \"));\n\n  console.log(\"\\n  artifacts\\n\");\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  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  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\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): string {\n  const hang = /^\\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"]}

package/dist/commands/archive.js

@@ -6,11 +6,11 @@ import { emitJson, emitJsonError, fail, repoPath, reportNoConfig } from "../core
 import { gatesArchive } from "../core/issue.js";
 import { acquireDocsLock, clearCommitIntent, DocsBusyError, InterruptedCommitError, message, NotUtf8Error, planWrite, quietPruneEmptyParents, quietRm, readUtf8, recoverInterruptedCommit, rollbackError, rollbackStaged, snapshotDir, SnapshotClobberError, stageWrites, swapStaged, writeCommitIntent, writeSnapshot, SNAPSHOT_DIR, } from "../core/staging.js";
 import { elementService, loadFile, loadSource, maskSource, matchBrace, scanModel, serviceOf, } from "../core/likec4.js";
-import { featurePaths, featureSpecPaths, featureSpecServices, featuresDir as featuresRoot, landscapePath as landscapeFile, missingFeatureMessage, resolveFeature, servicePaths, SPEC_AXES, } from "../core/repo.js";
+import { archiveDir as archiveRoot, featurePaths, featureSpecPaths, featureSpecServices, landscapePath as landscapeFile, missingFeatureMessage, resolveFeature, servicePaths, SPEC_AXES, } from "../core/repo.js";
 import { readOpenapi } from "../core/openapi.js";
 import { mergeOpenapiPaths, OpenapiMergeError, stripOpenapiRemovalMarkers, } from "../core/openapi-merge.js";
 import { featureCoherence, livingMergeConflicts, unknownDeltaServices } from "../core/coherence.js";
-import { findingJson } from "../core/report.js";
+import { findingJson, SEVERITY_MARK } from "../core/report.js";
 import { parseRequirements, serializeRequirements, applyRequirementDelta, isRequirementsHeading, sectionHeadings, splitRequirementsSection, } from "../core/spec.js";
 /**
  * A refusal or failure with its stable `--json` code attached. Thrown from the
@@ -52,6 +52,14 @@ function archiveErrorCode(err) {
         return err.code;
     if (err instanceof NotUtf8Error)
         return "merge-failed";
+    // The merge branch wraps its own call and re-throws as merge-failed; the
+    // create branch (`stripOpenapiRemovalMarkers`) does not, so one unreadable
+    // feature contract answered merge-failed or `internal` depending on whether
+    // the service already had a living openapi.yaml. The code answers "can I
+    // trust the repo?", and that answer does not turn on which side of the merge
+    // the document sat on.
+    if (err instanceof OpenapiMergeError)
+        return "merge-failed";
     if (err instanceof InterruptedCommitError)
         return "commit-interrupted";
     return "internal";
@@ -139,7 +147,6 @@ async function archiveLocked(config, featureId, opts) {
     const recovered = await recoverInterruptedCommit(config.docsDir);
     if (recovered !== null && !json)
         sayRecovery(recovered);
-    const featuresDir = featuresRoot(config.docsDir);
     const feature = await resolveFeature(config.docsDir, featureId, "exclude");
     if (!feature) {
         fail(json, "unknown-target", await missingFeatureMessage(config.docsDir, featureId));
@@ -201,7 +208,7 @@ async function archiveLocked(config, featureId, opts) {
         }
         console.error(`${msg}:`);
         for (const i of issues)
-            console.error(`  ${i.severity === "error" ? "✗" : "⚠"} ${i.message}`);
+            console.error(`  ${SEVERITY_MARK[i.severity]} ${i.message}`);
         console.error(`\nFix the gating issues (advisory warnings never block), or re-run with --approve to override them (may corrupt the living docs).`);
         process.exitCode = 1;
         return;
@@ -209,7 +216,7 @@ async function archiveLocked(config, featureId, opts) {
     if (gating.length > 0) {
         say(`⚠ archiving despite ${gating.length} gating issue(s) (--approve):`);
         for (const i of gating)
-            say(`  ${i.severity === "error" ? "✗" : "⚠"} ${i.message}`);
+            say(`  ${SEVERITY_MARK[i.severity]} ${i.message}`);
         say();
     }
     if (advisory.length > 0) {
@@ -297,7 +304,7 @@ async function archiveLocked(config, featureId, opts) {
     }
     // Pre-flight: the archive destination must be free, or the final move would fail
     // after the living docs were already rewritten.
-    const archiveDir = join(featuresDir, "archive");
+    const archiveDir = archiveRoot(config.docsDir);
     const archiveDest = join(archiveDir, dirName);
     if (existsSync(archiveDest)) {
         fail(json, "archive-exists", `archive ${id} — BLOCKED: features/archive/${dirName} already exists. Remove or rename it, then re-run.`);
@@ -368,6 +375,17 @@ async function archiveLocked(config, featureId, opts) {
         const featText = await readUtf8(featOpenapi);
         const livingOpenapi = servicePaths(config.docsDir, svc).openapi;
         const featDoc = await readOpenapi(featOpenapi);
+        // Every other reader of this flag suspends its own judgement when it is set
+        // — validate grades `openapi.invalid`, show and status print that the file
+        // does not parse. Archive was the only one that never looked, and it is the
+        // command that WRITES: a feature openapi.yaml holding a sequence instead of
+        // a mapping was planned verbatim into services/<svc>/openapi.yaml, `ok:
+        // true`, printing `created ()` because the reader saw no operations in it.
+        // A document loam cannot read is one it cannot merge, and that is the same
+        // answer as any other merge it could not compute: nothing is written.
+        if (featDoc.unreadable) {
+            throw new ArchiveFailure("merge-failed", `feature openapi ${repoPath(config.docsDir, featOpenapi)} for ${svc} does not read as an OpenAPI document (${featDoc.error ?? "not a YAML mapping"}) — the API axis cannot be merged; fix the file, or delete it if this feature has no contract delta`);
+        }
         const ops = featDoc.ops.filter((op) => !op.remove).map((op) => op.id);
         // An `x-loam-remove: true` written at PATH level retires nothing: the marker
         // addresses one operation, and beside the methods there is no operation for
@@ -507,8 +525,6 @@ async function archiveLocked(config, featureId, opts) {
     // here would make onboarding a new service impossible in one command.
     const newServices = [...new Set([...deltaServices, ...architectureServices])].filter((svc) => !existsSync(servicePaths(config.docsDir, svc).dir));
     for (const svc of newServices) {
-        if (existsSync(servicePaths(config.docsDir, svc).model))
-            continue;
         // Two shapes of the same debt: a service with a requirement delta gets its
         // directory from this merge, one that arrives only in the landscape gets no
         // directory at all — and `validate --all` fails the second harder