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

package/dist/core/mcp/tools.js

@@ -0,0 +1,324 @@
+/**
+ * The curated MCP tool table: which loam commands an MCP client can reach,
+ * and how a JSON argument object becomes an argv the CLI already trusts.
+ *
+ * This base table is read-only. Opt-in writers live in `./author-tools.ts`;
+ * vouch and a committing archive remain absent: an MCP caller is definitionally
+ * an agent, `loam vouch` is a HUMAN act (the CLI refuses unattended runs with
+ * vouch-unattended), and exposing it here would rebuild the hole the generated
+ * skill files' allowlist was narrowed to close. verify is excluded with them: its read form and its
+ * attesting `--record`/`--results`/`--contract-results` form are one command,
+ * and a facade that exposes "only the read half" of a writer is one
+ * flag-mapping bug away from exposing the writer.
+ *
+ * The inclusion of the two commands that read no CONFIG — `explain` and
+ * `instructions` — is equally deliberate, and is recorded here because the
+ * gap is otherwise re-derivable as an oversight: an agent meets both BEFORE
+ * the repository is wired (every generated skill's first line is `loam
+ * instructions <workflow>`, and `loam explain <code>` answers a code from a
+ * run that has not happened yet), so an MCP-only host that could not reach
+ * them could not fetch the protocol its own generated skill points at.
+ *
+ * `adopt` is here for the same reason one step later: it writes nothing — it
+ * emits the brief an agent then writes a baseline from — and the loam-adopt
+ * protocol an MCP-only host fetches through `loam_instructions` opens by
+ * running it. Without the tool that host could read the protocol and never
+ * receive the brief the protocol is about.
+ *
+ * Every table entry mirrors a real registration in `src/commands/` — same
+ * positionals, same flags, same spellings — so the contract an MCP client
+ * sees is the CLI contract, not a second one. `--json` is appended by
+ * `toArgv` unconditionally: the tool result IS the machine envelope.
+ */
+import { TERMS } from "../explain/terms.js";
+/**
+ * The concept-term names, from the registry that owns them — `loam_explain`'s
+ * schema description must not be a hand copy that silently trails TERMS.
+ */
+const TERM_LIST = TERMS.map(({ term }) => term).join(", ");
+const SERVICE_FLAG = {
+    property: "service",
+    flag: "--service",
+    kind: "string",
+    description: "service id (defaults to the one loam.json configures)",
+};
+/**
+ * The tool annotations EVERY entry in this table carries — one shared literal,
+ * because the table is read-only by construction and a per-tool copy is a
+ * place for one of them to drift into claiming something else.
+ *
+ * `readOnlyHint` is the whole point: without it a host has no machine signal
+ * that `loam_validate` or `loam_context` is safe, so a call that only reads
+ * files falls into the same approval prompt as a mutating tool. Read-only
+ * hints are what let a host auto-approve, and the reason the writers are
+ * excluded from the table above is precisely so this hint can be true of
+ * everything left. `openWorldHint: false` states the other half a host acts
+ * on: loam reaches no network and no service — it reads the files in the
+ * directory the server started in, and nothing else.
+ *
+ * `idempotentHint` and `destructiveHint` are deliberately ABSENT rather than
+ * spelled `true`/`false`: MCP defines both as meaningful only when
+ * `readOnlyHint` is false, so shipping them would be noise a reviewer has to
+ * justify before deciding they mean nothing here.
+ *
+ * `outputSchema` lives in `./protocol.ts`, beside `toolReply`: the declaration
+ * and the fallback structured envelope have to change together or a client is
+ * promised structured content one branch can omit.
+ */
+export const READ_ONLY_ANNOTATIONS = { readOnlyHint: true, openWorldHint: false };
+/**
+ * The `loam_` prefix on every name: multi-server MCP hosts flatten tool names
+ * into one namespace, and a bare `validate` collides with anybody else's.
+ * Each description names the CLI command it mirrors, so the equivalence is
+ * stated where the client reads it.
+ */
+export const MCP_TOOLS = [
+    {
+        name: "loam_validate",
+        command: "validate",
+        description: "Validate a service (C4 + requirement coverage), a feature (delta + coverage), or the whole fleet. " +
+            "CLI equivalent: loam validate [target] [--service <id>] [--feature <id>] [--all] [--strict] [--errors-only] --json",
+        positionals: [
+            {
+                property: "target",
+                required: false,
+                variadic: false,
+                description: "service or feature id (a feature wins when both match; service/feature force the reading)",
+            },
+        ],
+        flags: [
+            { ...SERVICE_FLAG, description: "service to validate (defaults to the configured service)" },
+            { property: "feature", flag: "--feature", kind: "string", description: "validate a feature delta instead of a service" },
+            { property: "all", flag: "--all", kind: "boolean", description: "validate every service and every active feature" },
+            { property: "strict", flag: "--strict", kind: "boolean", description: "exit 1 on any warning too; the payload does not change" },
+            { property: "errorsOnly", flag: "--errors-only", kind: "boolean", description: "print only errors and warnings; the payload does not change" },
+        ],
+    },
+    {
+        name: "loam_status",
+        command: "status",
+        description: "Where the work stands and what to do next, derived from the files. " +
+            "CLI equivalent: loam status [feature] [--service <id>] --json",
+        positionals: [
+            { property: "feature", required: false, variadic: false, description: "feature id or directory name; omit for the whole repository" },
+        ],
+        flags: [{ ...SERVICE_FLAG, description: "narrow the per-service view to one service" }],
+    },
+    {
+        name: "loam_list",
+        command: "list",
+        description: "List the services and features in the docs repo. " +
+            "CLI equivalent: loam list [section] [name] [--archived] [--needs-work] [--review-order] [--subsystem <name>] [--owners <path>] --json",
+        positionals: [
+            { property: "section", required: false, variadic: false, description: "services | features | capabilities | glossary | suites (default: services + features)" },
+            { property: "name", required: false, variadic: false, description: "suites only: the one suite to show" },
+        ],
+        flags: [
+            { property: "archived", flag: "--archived", kind: "boolean", description: "include archived features" },
+            { property: "needsWork", flag: "--needs-work", kind: "boolean", description: "services only: every service below vouched, with what it is missing" },
+            { property: "reviewOrder", flag: "--review-order", kind: "boolean", description: "with needsWork: order the worklist by fan-in, highest blast radius first" },
+            { property: "subsystem", flag: "--subsystem", kind: "string", description: "services only: limit the listing to services filed under this subsystem, at any depth ('unfiled' selects the ones filed under none)" },
+            { property: "owners", flag: "--owners", kind: "string", description: "services only: group the listing by owning team from this CODEOWNERS file (directory-pattern rules only; unsupported rules are listed as skipped, never guessed)" },
+        ],
+    },
+    {
+        name: "loam_show",
+        command: "show",
+        description: "Everything loam knows about a service or a feature. " +
+            "CLI equivalent: loam show <target> [--type service|feature] --json",
+        positionals: [
+            { property: "target", required: true, variadic: false, description: "service id or feature id" },
+        ],
+        flags: [
+            { property: "type", flag: "--type", kind: "string", description: "force the reading: service | feature" },
+        ],
+    },
+    {
+        name: "loam_delta",
+        command: "delta",
+        description: "Project a feature onto a service: why + requirement delta + C4 changes. " +
+            "CLI equivalent: loam delta <featureId> [--service <id>] --json",
+        positionals: [
+            { property: "featureId", required: true, variadic: false, description: "feature id, e.g. FEAT-101" },
+        ],
+        flags: [{ ...SERVICE_FLAG, description: "service to project onto (defaults to the configured service)" }],
+    },
+    {
+        name: "loam_tasks",
+        command: "tasks",
+        description: "What is still open on a feature, at which step, and what closes each unit — a read-only projection that writes nothing. " +
+            "CLI equivalent: loam tasks <featureId> [--service <id>] [--next] --json",
+        positionals: [
+            { property: "featureId", required: true, variadic: false, description: "feature id, e.g. FEAT-101" },
+        ],
+        flags: [
+            { ...SERVICE_FLAG, description: "narrow the packet to the units one service owns (a lens: no binding needed)" },
+            { property: "next", flag: "--next", kind: "boolean", description: "the frontier head alone — the single leaf to hand to a worker" },
+        ],
+    },
+    {
+        name: "loam_explore",
+        command: "explore",
+        description: "Read the fleet around a change nobody has written down yet — writes nothing. " +
+            "CLI equivalent: loam explore [service...] [--op <id>] [--capability <id>] [--as <FEAT>] --json",
+        positionals: [
+            { property: "services", required: false, variadic: true, description: "service ids the change starts from" },
+        ],
+        flags: [
+            { property: "op", flag: "--op", kind: "strings", description: "seed from an operation instead of a service; repeatable" },
+            { property: "capability", flag: "--capability", kind: "strings", description: "seed from a declared capability's realizing services; repeatable" },
+            { property: "as", flag: "--as", kind: "string", description: "feature id for the suggested command line" },
+        ],
+    },
+    {
+        name: "loam_dependencies",
+        command: "dependencies",
+        description: "Dependencies and conflicts derived from active feature artifacts. " +
+            "CLI equivalent: loam dependencies [featureId] --json",
+        positionals: [
+            { property: "featureId", required: false, variadic: false, description: "active feature id; omit for the whole in-flight graph" },
+        ],
+        flags: [],
+    },
+    {
+        name: "loam_diff",
+        command: "diff",
+        description: "Semantic diff of the living docs against a base git ref of the docs repo — removals graded against their current consumers; read-only. " +
+            "CLI equivalent: loam diff --base <ref> --json",
+        positionals: [],
+        flags: [
+            {
+                property: "base",
+                flag: "--base",
+                kind: "string",
+                required: true,
+                description: "base git ref of the docs repo (e.g. main, origin/main, a commit sha)",
+            },
+        ],
+    },
+    {
+        name: "loam_doctor",
+        command: "doctor",
+        description: "Diagnose local loam configuration and docs-repo accessibility without writing. " +
+            "CLI equivalent: loam doctor --json",
+        positionals: [],
+        flags: [],
+    },
+    {
+        name: "loam_context",
+        command: "context",
+        description: "Assemble one service's whole docs slice as one deterministic briefing. " +
+            "CLI equivalent: loam context <service> [--feature <FEAT>] --json",
+        positionals: [
+            { property: "service", required: true, variadic: false, description: "service id, e.g. payment-service" },
+        ],
+        flags: [
+            { property: "feature", flag: "--feature", kind: "string", description: "narrow the in-flight section to this one feature" },
+        ],
+    },
+    {
+        name: "loam_adopt",
+        command: "adopt",
+        description: "Brief an agent to write one service's baseline docs from its code, and say what will be checked — writes nothing. " +
+            "CLI equivalent: loam adopt [--service <id>] [--subsystem <name>] [--targets] --json",
+        positionals: [],
+        flags: [
+            { ...SERVICE_FLAG, description: "service to adopt (defaults to the configured service)" },
+            { property: "subsystem", flag: "--subsystem", kind: "string", description: "brief a NEW service's baseline into this subsystem instead of the services/ root" },
+            { property: "targets", flag: "--targets", kind: "boolean", description: "only what varies by service; a `full` field names the run that carries the walk, the checks and the unchecked list" },
+        ],
+    },
+    {
+        name: "loam_gate",
+        command: "gate",
+        description: "Can this service deploy? A read-only query over recorded evidence — advisory by default. " +
+            "CLI equivalent: loam gate [--service <id>] [--since <ref>] [--strict] --json",
+        positionals: [],
+        flags: [
+            { ...SERVICE_FLAG, description: "the service being deployed (defaults to the configured service)" },
+            { property: "since", flag: "--since", kind: "string", description: "also grade features archived after this docs-repo git ref; without it only in-flight features are read" },
+            { property: "strict", flag: "--strict", kind: "boolean", description: "exit 1 on any warning too; the payload does not change" },
+        ],
+    },
+    {
+        name: "loam_steps",
+        command: "steps",
+        description: "Inventory the step phrases of a service's scenarios — how many step definitions its suite needs. " +
+            "CLI equivalent: loam steps [--service <id>] [--duplicates] --json",
+        positionals: [],
+        flags: [
+            { ...SERVICE_FLAG, description: "service to inventory (defaults to the configured service)" },
+            {
+                property: "duplicates",
+                flag: "--duplicates",
+                kind: "boolean",
+                description: "list only the near-duplicate groups — phrases that differ by an article or a trailing clause",
+            },
+        ],
+    },
+    {
+        name: "loam_explain",
+        command: "explain",
+        description: "Explain a finding code, a refusal code, or a loam concept term, version-matched to this binary; reads no config and no docs repo. " +
+            "CLI equivalent: loam explain [subject] --json",
+        positionals: [
+            {
+                property: "subject",
+                required: false,
+                variadic: false,
+                description: `finding code (spine.op-undefined), refusal code (docs-busy), or concept term (${TERM_LIST}); omit to list the terms`,
+            },
+        ],
+        flags: [],
+    },
+    {
+        name: "loam_instructions",
+        command: "instructions",
+        description: "Print a workflow, support protocol or reference page, version-matched to this binary; reads no config and no docs repo, so it answers " +
+            "before the repository is wired. Ask for loam-check DELIBERATELY: it is by far the largest protocol " +
+            "(almost all of what it prints is its per-code fix tables), and noFixTables true returns the narrowed page " +
+            "— every paragraph that introduces a table, none of the rows — after which loam_explain answers any one code " +
+            "a run reports, on its own. " +
+            "CLI equivalent: loam instructions [workflow] [args...] [--no-fix-tables] --json",
+        positionals: [
+            {
+                property: "workflow",
+                required: false,
+                variadic: false,
+                description: "workflow, support or reference name (loam-adopt, loam-report, loam-codes, …); omit to list them",
+            },
+            {
+                property: "args",
+                required: false,
+                variadic: true,
+                description: "values substituted for the protocol's $1, $2, … placeholders",
+            },
+        ],
+        flags: [
+            {
+                // `noFixTables`, not `fixTables`, and the mismatch with commander's own
+                // attribute name (`fixTables`, because `--no-` negates) is the point:
+                // `toArgv` spells a true boolean as its flag string, so a property named
+                // for the option's ATTRIBUTE would make `{fixTables: true}` emit
+                // `--no-fix-tables` and turn the tables off. The JSON property is named
+                // for what setting it true DOES.
+                property: "noFixTables",
+                flag: "--no-fix-tables",
+                kind: "boolean",
+                description: "drop the per-code fix tables; loam_explain answers any code a run reports",
+            },
+        ],
+    },
+];
+export function toolByName(name, tools = MCP_TOOLS) {
+    return tools.find((tool) => tool.name === name);
+}
+// How a tool call's JSON arguments become an argv — including the refusal of
+// any string a shell-less argv would still read as a flag — lives in
+// `./argv.ts`: the table above says WHAT the tools are, that module says how
+// a call crosses into the CLI's own parsing. The inputSchema each tool is
+// advertised with (`toInputSchema`) lives there too: it DECLARES the argument
+// contract `toArgv` ENFORCES — the closed object, the required set, the order
+// the positionals are read in — and the two halves change together or a
+// client validates against one rule and is refused by another.
+//# sourceMappingURL=tools.js.map

package/dist/core/mcp/tools.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tools.js","sourceRoot":"","sources":["../../../src/core/mcp/tools.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * The curated MCP tool table: which loam commands an MCP client can reach,\n * and how a JSON argument object becomes an argv the CLI already trusts.\n *\n * This base table is read-only. Opt-in writers live in `./author-tools.ts`;\n * vouch and a committing archive remain absent: an MCP caller is definitionally\n * an agent, `loam vouch` is a HUMAN act (the CLI refuses unattended runs with\n * vouch-unattended), and exposing it here would rebuild the hole the generated\n * skill files' allowlist was narrowed to close. verify is excluded with them: its read form and its\n * attesting `--record`/`--results`/`--contract-results` form are one command,\n * and a facade that exposes \"only the read half\" of a writer is one\n * flag-mapping bug away from exposing the writer.\n *\n * The inclusion of the two commands that read no CONFIG — `explain` and\n * `instructions` — is equally deliberate, and is recorded here because the\n * gap is otherwise re-derivable as an oversight: an agent meets both BEFORE\n * the repository is wired (every generated skill's first line is `loam\n * instructions <workflow>`, and `loam explain <code>` answers a code from a\n * run that has not happened yet), so an MCP-only host that could not reach\n * them could not fetch the protocol its own generated skill points at.\n *\n * `adopt` is here for the same reason one step later: it writes nothing — it\n * emits the brief an agent then writes a baseline from — and the loam-adopt\n * protocol an MCP-only host fetches through `loam_instructions` opens by\n * running it. Without the tool that host could read the protocol and never\n * receive the brief the protocol is about.\n *\n * Every table entry mirrors a real registration in `src/commands/` — same\n * positionals, same flags, same spellings — so the contract an MCP client\n * sees is the CLI contract, not a second one. `--json` is appended by\n * `toArgv` unconditionally: the tool result IS the machine envelope.\n */\n\nimport { TERMS } from \"../explain/terms.js\";\n\n/**\n * The concept-term names, from the registry that owns them — `loam_explain`'s\n * schema description must not be a hand copy that silently trails TERMS.\n */\nconst TERM_LIST = TERMS.map(({ term }) => term).join(\", \");\n\n/** A positional argument, in declaration order. A variadic one is always last. */\nexport interface ToolPositional {\n  readonly property: string;\n  readonly required: boolean;\n  /** True when the JSON argument is an array of strings spread as trailing positionals. */\n  readonly variadic: boolean;\n  readonly description: string;\n}\n\n/** One CLI flag: `kind` decides both the JSON Schema type and the argv shape. */\nexport interface ToolFlag {\n  readonly property: string;\n  readonly flag: string;\n  readonly kind: \"string\" | \"boolean\" | \"strings\";\n  /**\n   * Set when the CLI declares the option with `requiredOption` — the schema\n   * then requires the property and the argv builder refuses its absence, so\n   * a client learns the requirement from the schema instead of from an\n   * invalid-option envelope after the call. The shape test asserts this\n   * mirrors commander's own `mandatory`, both ways.\n   */\n  readonly required?: true;\n  readonly description: string;\n}\n\nexport interface McpTool {\n  readonly name: string;\n  readonly command: string;\n  readonly description: string;\n  readonly positionals: readonly ToolPositional[];\n  readonly flags: readonly ToolFlag[];\n  /** Arguments enforced by the server rather than exposed to the caller. */\n  readonly fixed?: readonly string[];\n  readonly annotations?: Readonly<Record<string, boolean>>;\n}\n\nconst SERVICE_FLAG = {\n  property: \"service\",\n  flag: \"--service\",\n  kind: \"string\",\n  description: \"service id (defaults to the one loam.json configures)\",\n} as const;\n\n/**\n * The tool annotations EVERY entry in this table carries — one shared literal,\n * because the table is read-only by construction and a per-tool copy is a\n * place for one of them to drift into claiming something else.\n *\n * `readOnlyHint` is the whole point: without it a host has no machine signal\n * that `loam_validate` or `loam_context` is safe, so a call that only reads\n * files falls into the same approval prompt as a mutating tool. Read-only\n * hints are what let a host auto-approve, and the reason the writers are\n * excluded from the table above is precisely so this hint can be true of\n * everything left. `openWorldHint: false` states the other half a host acts\n * on: loam reaches no network and no service — it reads the files in the\n * directory the server started in, and nothing else.\n *\n * `idempotentHint` and `destructiveHint` are deliberately ABSENT rather than\n * spelled `true`/`false`: MCP defines both as meaningful only when\n * `readOnlyHint` is false, so shipping them would be noise a reviewer has to\n * justify before deciding they mean nothing here.\n *\n * `outputSchema` lives in `./protocol.ts`, beside `toolReply`: the declaration\n * and the fallback structured envelope have to change together or a client is\n * promised structured content one branch can omit.\n */\nexport const READ_ONLY_ANNOTATIONS = { readOnlyHint: true, openWorldHint: false } as const;\n\n/**\n * The `loam_` prefix on every name: multi-server MCP hosts flatten tool names\n * into one namespace, and a bare `validate` collides with anybody else's.\n * Each description names the CLI command it mirrors, so the equivalence is\n * stated where the client reads it.\n */\nexport const MCP_TOOLS: readonly McpTool[] = [\n  {\n    name: \"loam_validate\",\n    command: \"validate\",\n    description:\n      \"Validate a service (C4 + requirement coverage), a feature (delta + coverage), or the whole fleet. \" +\n      \"CLI equivalent: loam validate [target] [--service <id>] [--feature <id>] [--all] [--strict] [--errors-only] --json\",\n    positionals: [\n      {\n        property: \"target\",\n        required: false,\n        variadic: false,\n        description: \"service or feature id (a feature wins when both match; service/feature force the reading)\",\n      },\n    ],\n    flags: [\n      { ...SERVICE_FLAG, description: \"service to validate (defaults to the configured service)\" },\n      { property: \"feature\", flag: \"--feature\", kind: \"string\", description: \"validate a feature delta instead of a service\" },\n      { property: \"all\", flag: \"--all\", kind: \"boolean\", description: \"validate every service and every active feature\" },\n      { property: \"strict\", flag: \"--strict\", kind: \"boolean\", description: \"exit 1 on any warning too; the payload does not change\" },\n      { property: \"errorsOnly\", flag: \"--errors-only\", kind: \"boolean\", description: \"print only errors and warnings; the payload does not change\" },\n    ],\n  },\n  {\n    name: \"loam_status\",\n    command: \"status\",\n    description:\n      \"Where the work stands and what to do next, derived from the files. \" +\n      \"CLI equivalent: loam status [feature] [--service <id>] --json\",\n    positionals: [\n      { property: \"feature\", required: false, variadic: false, description: \"feature id or directory name; omit for the whole repository\" },\n    ],\n    flags: [{ ...SERVICE_FLAG, description: \"narrow the per-service view to one service\" }],\n  },\n  {\n    name: \"loam_list\",\n    command: \"list\",\n    description:\n      \"List the services and features in the docs repo. \" +\n      \"CLI equivalent: loam list [section] [name] [--archived] [--needs-work] [--review-order] [--subsystem <name>] [--owners <path>] --json\",\n    positionals: [\n      { property: \"section\", required: false, variadic: false, description: \"services | features | capabilities | glossary | suites (default: services + features)\" },\n      { property: \"name\", required: false, variadic: false, description: \"suites only: the one suite to show\" },\n    ],\n    flags: [\n      { property: \"archived\", flag: \"--archived\", kind: \"boolean\", description: \"include archived features\" },\n      { property: \"needsWork\", flag: \"--needs-work\", kind: \"boolean\", description: \"services only: every service below vouched, with what it is missing\" },\n      { property: \"reviewOrder\", flag: \"--review-order\", kind: \"boolean\", description: \"with needsWork: order the worklist by fan-in, highest blast radius first\" },\n      { property: \"subsystem\", flag: \"--subsystem\", kind: \"string\", description: \"services only: limit the listing to services filed under this subsystem, at any depth ('unfiled' selects the ones filed under none)\" },\n      { property: \"owners\", flag: \"--owners\", kind: \"string\", description: \"services only: group the listing by owning team from this CODEOWNERS file (directory-pattern rules only; unsupported rules are listed as skipped, never guessed)\" },\n    ],\n  },\n  {\n    name: \"loam_show\",\n    command: \"show\",\n    description:\n      \"Everything loam knows about a service or a feature. \" +\n      \"CLI equivalent: loam show <target> [--type service|feature] --json\",\n    positionals: [\n      { property: \"target\", required: true, variadic: false, description: \"service id or feature id\" },\n    ],\n    flags: [\n      { property: \"type\", flag: \"--type\", kind: \"string\", description: \"force the reading: service | feature\" },\n    ],\n  },\n  {\n    name: \"loam_delta\",\n    command: \"delta\",\n    description:\n      \"Project a feature onto a service: why + requirement delta + C4 changes. \" +\n      \"CLI equivalent: loam delta <featureId> [--service <id>] --json\",\n    positionals: [\n      { property: \"featureId\", required: true, variadic: false, description: \"feature id, e.g. FEAT-101\" },\n    ],\n    flags: [{ ...SERVICE_FLAG, description: \"service to project onto (defaults to the configured service)\" }],\n  },\n  {\n    name: \"loam_tasks\",\n    command: \"tasks\",\n    description:\n      \"What is still open on a feature, at which step, and what closes each unit — a read-only projection that writes nothing. \" +\n      \"CLI equivalent: loam tasks <featureId> [--service <id>] [--next] --json\",\n    positionals: [\n      { property: \"featureId\", required: true, variadic: false, description: \"feature id, e.g. FEAT-101\" },\n    ],\n    flags: [\n      { ...SERVICE_FLAG, description: \"narrow the packet to the units one service owns (a lens: no binding needed)\" },\n      { property: \"next\", flag: \"--next\", kind: \"boolean\", description: \"the frontier head alone — the single leaf to hand to a worker\" },\n    ],\n  },\n  {\n    name: \"loam_explore\",\n    command: \"explore\",\n    description:\n      \"Read the fleet around a change nobody has written down yet — writes nothing. \" +\n      \"CLI equivalent: loam explore [service...] [--op <id>] [--capability <id>] [--as <FEAT>] --json\",\n    positionals: [\n      { property: \"services\", required: false, variadic: true, description: \"service ids the change starts from\" },\n    ],\n    flags: [\n      { property: \"op\", flag: \"--op\", kind: \"strings\", description: \"seed from an operation instead of a service; repeatable\" },\n      { property: \"capability\", flag: \"--capability\", kind: \"strings\", description: \"seed from a declared capability's realizing services; repeatable\" },\n      { property: \"as\", flag: \"--as\", kind: \"string\", description: \"feature id for the suggested command line\" },\n    ],\n  },\n  {\n    name: \"loam_dependencies\",\n    command: \"dependencies\",\n    description:\n      \"Dependencies and conflicts derived from active feature artifacts. \" +\n      \"CLI equivalent: loam dependencies [featureId] --json\",\n    positionals: [\n      { property: \"featureId\", required: false, variadic: false, description: \"active feature id; omit for the whole in-flight graph\" },\n    ],\n    flags: [],\n  },\n  {\n    name: \"loam_diff\",\n    command: \"diff\",\n    description:\n      \"Semantic diff of the living docs against a base git ref of the docs repo — removals graded against their current consumers; read-only. \" +\n      \"CLI equivalent: loam diff --base <ref> --json\",\n    positionals: [],\n    flags: [\n      {\n        property: \"base\",\n        flag: \"--base\",\n        kind: \"string\",\n        required: true,\n        description: \"base git ref of the docs repo (e.g. main, origin/main, a commit sha)\",\n      },\n    ],\n  },\n  {\n    name: \"loam_doctor\",\n    command: \"doctor\",\n    description:\n      \"Diagnose local loam configuration and docs-repo accessibility without writing. \" +\n      \"CLI equivalent: loam doctor --json\",\n    positionals: [],\n    flags: [],\n  },\n  {\n    name: \"loam_context\",\n    command: \"context\",\n    description:\n      \"Assemble one service's whole docs slice as one deterministic briefing. \" +\n      \"CLI equivalent: loam context <service> [--feature <FEAT>] --json\",\n    positionals: [\n      { property: \"service\", required: true, variadic: false, description: \"service id, e.g. payment-service\" },\n    ],\n    flags: [\n      { property: \"feature\", flag: \"--feature\", kind: \"string\", description: \"narrow the in-flight section to this one feature\" },\n    ],\n  },\n  {\n    name: \"loam_adopt\",\n    command: \"adopt\",\n    description:\n      \"Brief an agent to write one service's baseline docs from its code, and say what will be checked — writes nothing. \" +\n      \"CLI equivalent: loam adopt [--service <id>] [--subsystem <name>] [--targets] --json\",\n    positionals: [],\n    flags: [\n      { ...SERVICE_FLAG, description: \"service to adopt (defaults to the configured service)\" },\n      { property: \"subsystem\", flag: \"--subsystem\", kind: \"string\", description: \"brief a NEW service's baseline into this subsystem instead of the services/ root\" },\n      { property: \"targets\", flag: \"--targets\", kind: \"boolean\", description: \"only what varies by service; a `full` field names the run that carries the walk, the checks and the unchecked list\" },\n    ],\n  },\n  {\n    name: \"loam_gate\",\n    command: \"gate\",\n    description:\n      \"Can this service deploy? A read-only query over recorded evidence — advisory by default. \" +\n      \"CLI equivalent: loam gate [--service <id>] [--since <ref>] [--strict] --json\",\n    positionals: [],\n    flags: [\n      { ...SERVICE_FLAG, description: \"the service being deployed (defaults to the configured service)\" },\n      { property: \"since\", flag: \"--since\", kind: \"string\", description: \"also grade features archived after this docs-repo git ref; without it only in-flight features are read\" },\n      { property: \"strict\", flag: \"--strict\", kind: \"boolean\", description: \"exit 1 on any warning too; the payload does not change\" },\n    ],\n  },\n  {\n    name: \"loam_steps\",\n    command: \"steps\",\n    description:\n      \"Inventory the step phrases of a service's scenarios — how many step definitions its suite needs. \" +\n      \"CLI equivalent: loam steps [--service <id>] [--duplicates] --json\",\n    positionals: [],\n    flags: [\n      { ...SERVICE_FLAG, description: \"service to inventory (defaults to the configured service)\" },\n      {\n        property: \"duplicates\",\n        flag: \"--duplicates\",\n        kind: \"boolean\",\n        description: \"list only the near-duplicate groups — phrases that differ by an article or a trailing clause\",\n      },\n    ],\n  },\n  {\n    name: \"loam_explain\",\n    command: \"explain\",\n    description:\n      \"Explain a finding code, a refusal code, or a loam concept term, version-matched to this binary; reads no config and no docs repo. \" +\n      \"CLI equivalent: loam explain [subject] --json\",\n    positionals: [\n      {\n        property: \"subject\",\n        required: false,\n        variadic: false,\n        description: `finding code (spine.op-undefined), refusal code (docs-busy), or concept term (${TERM_LIST}); omit to list the terms`,\n      },\n    ],\n    flags: [],\n  },\n  {\n    name: \"loam_instructions\",\n    command: \"instructions\",\n    description:\n      \"Print a workflow, support protocol or reference page, version-matched to this binary; reads no config and no docs repo, so it answers \" +\n      \"before the repository is wired. Ask for loam-check DELIBERATELY: it is by far the largest protocol \" +\n      \"(almost all of what it prints is its per-code fix tables), and noFixTables true returns the narrowed page \" +\n      \"— every paragraph that introduces a table, none of the rows — after which loam_explain answers any one code \" +\n      \"a run reports, on its own. \" +\n      \"CLI equivalent: loam instructions [workflow] [args...] [--no-fix-tables] --json\",\n    positionals: [\n      {\n        property: \"workflow\",\n        required: false,\n        variadic: false,\n        description: \"workflow, support or reference name (loam-adopt, loam-report, loam-codes, …); omit to list them\",\n      },\n      {\n        property: \"args\",\n        required: false,\n        variadic: true,\n        description: \"values substituted for the protocol's $1, $2, … placeholders\",\n      },\n    ],\n    flags: [\n      {\n        // `noFixTables`, not `fixTables`, and the mismatch with commander's own\n        // attribute name (`fixTables`, because `--no-` negates) is the point:\n        // `toArgv` spells a true boolean as its flag string, so a property named\n        // for the option's ATTRIBUTE would make `{fixTables: true}` emit\n        // `--no-fix-tables` and turn the tables off. The JSON property is named\n        // for what setting it true DOES.\n        property: \"noFixTables\",\n        flag: \"--no-fix-tables\",\n        kind: \"boolean\",\n        description: \"drop the per-code fix tables; loam_explain answers any code a run reports\",\n      },\n    ],\n  },\n];\n\nexport function toolByName(\n  name: string,\n  tools: readonly McpTool[] = MCP_TOOLS,\n): McpTool | undefined {\n  return tools.find((tool) => tool.name === name);\n}\n\n// How a tool call's JSON arguments become an argv — including the refusal of\n// any string a shell-less argv would still read as a flag — lives in\n// `./argv.ts`: the table above says WHAT the tools are, that module says how\n// a call crosses into the CLI's own parsing. The inputSchema each tool is\n// advertised with (`toInputSchema`) lives there too: it DECLARES the argument\n// contract `toArgv` ENFORCES — the closed object, the required set, the order\n// the positionals are read in — and the two halves change together or a\n// client validates against one rule and is refused by another.\n"]}

package/dist/core/obligations/obligations.js

@@ -0,0 +1,106 @@
+/**
+ * The fleet's ARCHITECTURAL OBLIGATION vocabulary: which architectural rules
+ * this fleet has decided on, so a `#obl-<name>` tag on the map resolves or
+ * refuses instead of silently labelling.
+ *
+ * THE GAP IT CLOSES is the architect→team handoff, and loam already had exactly
+ * one channel for it: a landscape edge carrying `metadata { op 'authorizePayment' }`
+ * obliges the provider to define that operationId, or `spine.op-undefined` fails
+ * the gate. The architect writes the edge and the team owes the contract. There
+ * was no equivalent for the obligations that VARY — an outbox on this publisher
+ * and not that one, a circuit breaker on two edges out of five — and "vary" is
+ * why a policy document is the wrong shape: a fleet-wide rule every service
+ * inherits is not what an architect actually hands over.
+ *
+ * SO THE DECISION AND ITS SCOPE ARE SEPARATE THINGS, and each lives where it
+ * already belonged. The **ADR** says WHAT was decided, in `architecture/adrs/`,
+ * as thin or as thick as the decision needs. A **tag** on a landscape element or
+ * edge says WHERE it applies, so one ADR governs three edges and not the fourth
+ * without the document forking. This **vocabulary** declares the names, so a
+ * mistyped tag is an error rather than a word nobody notices. And the team's
+ * **`Covers:`** line says it is met, with a scenario proving it.
+ *
+ * THE SHAPE IS `permissions.yaml`'s AND `capabilities.yaml`'s, deliberately: a
+ * fleet file declares names with prose that has no other home, the join is made
+ * elsewhere, and the vocabulary is graded in both directions. What it is NOT is
+ * a policy engine — there are no conditions, no severities, no inheritance.
+ * Everything past a declared name has no ground truth to check against, which
+ * is the same line the permission and capability vocabularies stop at.
+ *
+ * AN ID IS ITS OWN TAG SUFFIX, so an id is refused unless a LikeC4 tag name can
+ * carry it verbatim. The capability axis had to flatten `identity/tokens` into
+ * `#cap-identity-tokens` — lossy, and two ids can collapse into one slug — which
+ * it pays for with a `many` arm at every join. Here the id is chosen by whoever
+ * writes the vocabulary and has no other life, so refusing `payments/outbox` at
+ * the source is strictly better than flattening it: the tag is exact, no slug
+ * exists, and no collision arm is needed anywhere downstream.
+ */
+import { readFile } from "node:fs/promises";
+import { existsSync } from "node:fs";
+import { parse as parseYaml } from "yaml";
+import { isRecord } from "../kernel/records.js";
+/** The reserved tag prefix. `#obl-outbox` applies the obligation `outbox`. */
+export const OBLIGATION_TAG_PREFIX = "obl-";
+/**
+ * Every character a LikeC4 tag name accepts, at the 1.59.2 pin — the same
+ * measured whitelist `core/capabilities/usecase-join.ts` records, applied here
+ * as a REFUSAL rather than as a flattening. A rejected character truncates the
+ * tag rather than failing it (`#obl-a.b` reads back as `obl-a`), so a name that
+ * cannot be a tag is a name whose tag would silently mean something else.
+ */
+const TAG_SAFE_NAME = /^[A-Za-z0-9_-]+$/;
+const EMPTY = { present: false, byId: new Map() };
+/**
+ * Read the vocabulary — the same defensive ladder `permissions.ts` and
+ * `capabilities.ts` walk, because the three files fail the same ways. A missing
+ * file is silence; a YAML error or a non-mapping shape is `invalid`, one finding
+ * for the whole run with the family suspended behind it; an empty document is a
+ * present-and-empty vocabulary; and a declaration whose body is not a mapping is
+ * read as `{}` rather than refusing the whole file over one leaf.
+ *
+ * The one rule that is this file's own is the id grammar above, and it refuses
+ * the FILE rather than dropping the entry: a vocabulary that silently held only
+ * the names loam could tag would grade the rest as undeclared, which reads as
+ * "you have a typo" against a line the author did write.
+ */
+export async function readObligations(path) {
+    if (!existsSync(path))
+        return EMPTY;
+    let doc;
+    try {
+        doc = parseYaml(await readFile(path, "utf8"));
+    }
+    catch (e) {
+        return { ...EMPTY, present: true, invalid: e instanceof Error ? e.message : String(e) };
+    }
+    if (doc === null || doc === undefined)
+        return { ...EMPTY, present: true };
+    if (!isRecord(doc))
+        return { ...EMPTY, present: true, invalid: "the document is not a mapping" };
+    const block = doc["obligations"];
+    if (block === undefined)
+        return { present: true, byId: new Map() };
+    if (!isRecord(block)) {
+        return { ...EMPTY, present: true, invalid: "`obligations` is not a mapping of obligation id to its declaration" };
+    }
+    const byId = new Map();
+    for (const [id, body] of Object.entries(block)) {
+        if (!TAG_SAFE_NAME.test(id)) {
+            return {
+                ...EMPTY,
+                present: true,
+                invalid: `'${id}' cannot be a LikeC4 tag name, and an obligation id IS its tag suffix — ` +
+                    "use letters, digits, `_` and `-` only (a rejected character truncates the tag rather than failing it, " +
+                    "so `#obl-a.b` would read back as the obligation `a`)",
+            };
+        }
+        const decl = isRecord(body) ? body : {};
+        byId.set(id, {
+            id,
+            ...(typeof decl["description"] === "string" ? { description: decl["description"] } : {}),
+            ...(typeof decl["adr"] === "string" ? { adr: decl["adr"] } : {}),
+        });
+    }
+    return { present: true, byId };
+}
+//# sourceMappingURL=obligations.js.map

package/dist/core/obligations/obligations.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"obligations.js","sourceRoot":"","sources":["../../../src/core/obligations/obligations.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * The fleet's ARCHITECTURAL OBLIGATION vocabulary: which architectural rules\n * this fleet has decided on, so a `#obl-<name>` tag on the map resolves or\n * refuses instead of silently labelling.\n *\n * THE GAP IT CLOSES is the architect→team handoff, and loam already had exactly\n * one channel for it: a landscape edge carrying `metadata { op 'authorizePayment' }`\n * obliges the provider to define that operationId, or `spine.op-undefined` fails\n * the gate. The architect writes the edge and the team owes the contract. There\n * was no equivalent for the obligations that VARY — an outbox on this publisher\n * and not that one, a circuit breaker on two edges out of five — and \"vary\" is\n * why a policy document is the wrong shape: a fleet-wide rule every service\n * inherits is not what an architect actually hands over.\n *\n * SO THE DECISION AND ITS SCOPE ARE SEPARATE THINGS, and each lives where it\n * already belonged. The **ADR** says WHAT was decided, in `architecture/adrs/`,\n * as thin or as thick as the decision needs. A **tag** on a landscape element or\n * edge says WHERE it applies, so one ADR governs three edges and not the fourth\n * without the document forking. This **vocabulary** declares the names, so a\n * mistyped tag is an error rather than a word nobody notices. And the team's\n * **`Covers:`** line says it is met, with a scenario proving it.\n *\n * THE SHAPE IS `permissions.yaml`'s AND `capabilities.yaml`'s, deliberately: a\n * fleet file declares names with prose that has no other home, the join is made\n * elsewhere, and the vocabulary is graded in both directions. What it is NOT is\n * a policy engine — there are no conditions, no severities, no inheritance.\n * Everything past a declared name has no ground truth to check against, which\n * is the same line the permission and capability vocabularies stop at.\n *\n * AN ID IS ITS OWN TAG SUFFIX, so an id is refused unless a LikeC4 tag name can\n * carry it verbatim. The capability axis had to flatten `identity/tokens` into\n * `#cap-identity-tokens` — lossy, and two ids can collapse into one slug — which\n * it pays for with a `many` arm at every join. Here the id is chosen by whoever\n * writes the vocabulary and has no other life, so refusing `payments/outbox` at\n * the source is strictly better than flattening it: the tag is exact, no slug\n * exists, and no collision arm is needed anywhere downstream.\n */\nimport { readFile } from \"node:fs/promises\";\nimport { existsSync } from \"node:fs\";\nimport { parse as parseYaml } from \"yaml\";\nimport { isRecord } from \"../kernel/records.js\";\n\n/** The reserved tag prefix. `#obl-outbox` applies the obligation `outbox`. */\nexport const OBLIGATION_TAG_PREFIX = \"obl-\";\n\n/**\n * Every character a LikeC4 tag name accepts, at the 1.59.2 pin — the same\n * measured whitelist `core/capabilities/usecase-join.ts` records, applied here\n * as a REFUSAL rather than as a flattening. A rejected character truncates the\n * tag rather than failing it (`#obl-a.b` reads back as `obl-a`), so a name that\n * cannot be a tag is a name whose tag would silently mean something else.\n */\nconst TAG_SAFE_NAME = /^[A-Za-z0-9_-]+$/;\n\n/** One declared architectural obligation. */\nexport interface Obligation {\n  /** The name, which is also the tag suffix: `#obl-<id>`. */\n  id: string;\n  description?: string;\n  /**\n   * The decision record this obligation comes from, as a path relative to the\n   * docs repo root — `architecture/adrs/0001-transactional-outbox.md`.\n   *\n   * Optional, and RESOLVED when present: this is the join that makes \"the ADR\n   * says what, the tag says where\" checkable rather than a convention. An\n   * obligation with no ADR is a legitimate state — the reason may be one\n   * sentence of `description` — but a path that names nothing is a pointer at a\n   * decision nobody can read, which is the same failure `capability.unknown`\n   * catches one axis over.\n   */\n  adr?: string;\n}\n\nexport interface ObligationVocabulary {\n  /**\n   * False when `architecture/obligations.yaml` does not exist. The FILE is the\n   * axis's opt-in, exactly as it is for permissions and capabilities: a fleet\n   * that has decided nothing architectural owes no vocabulary and hears\n   * nothing, however many tags its map already carries.\n   */\n  present: boolean;\n  /** Why the file could not be read as a vocabulary, when it could not. */\n  invalid?: string;\n  /** Declared obligations, keyed by id. */\n  byId: Map<string, Obligation>;\n}\n\nconst EMPTY: ObligationVocabulary = { present: false, byId: new Map() };\n\n/**\n * Read the vocabulary — the same defensive ladder `permissions.ts` and\n * `capabilities.ts` walk, because the three files fail the same ways. A missing\n * file is silence; a YAML error or a non-mapping shape is `invalid`, one finding\n * for the whole run with the family suspended behind it; an empty document is a\n * present-and-empty vocabulary; and a declaration whose body is not a mapping is\n * read as `{}` rather than refusing the whole file over one leaf.\n *\n * The one rule that is this file's own is the id grammar above, and it refuses\n * the FILE rather than dropping the entry: a vocabulary that silently held only\n * the names loam could tag would grade the rest as undeclared, which reads as\n * \"you have a typo\" against a line the author did write.\n */\nexport async function readObligations(path: string): Promise<ObligationVocabulary> {\n  if (!existsSync(path)) return EMPTY;\n  let doc: unknown;\n  try {\n    doc = parseYaml(await readFile(path, \"utf8\"));\n  } catch (e) {\n    return { ...EMPTY, present: true, invalid: e instanceof Error ? e.message : String(e) };\n  }\n  if (doc === null || doc === undefined) return { ...EMPTY, present: true };\n  if (!isRecord(doc)) return { ...EMPTY, present: true, invalid: \"the document is not a mapping\" };\n\n  const block = doc[\"obligations\"];\n  if (block === undefined) return { present: true, byId: new Map() };\n  if (!isRecord(block)) {\n    return { ...EMPTY, present: true, invalid: \"`obligations` is not a mapping of obligation id to its declaration\" };\n  }\n\n  const byId = new Map<string, Obligation>();\n  for (const [id, body] of Object.entries(block)) {\n    if (!TAG_SAFE_NAME.test(id)) {\n      return {\n        ...EMPTY,\n        present: true,\n        invalid:\n          `'${id}' cannot be a LikeC4 tag name, and an obligation id IS its tag suffix — ` +\n          \"use letters, digits, `_` and `-` only (a rejected character truncates the tag rather than failing it, \" +\n          \"so `#obl-a.b` would read back as the obligation `a`)\",\n      };\n    }\n    const decl = isRecord(body) ? body : {};\n    byId.set(id, {\n      id,\n      ...(typeof decl[\"description\"] === \"string\" ? { description: decl[\"description\"] } : {}),\n      ...(typeof decl[\"adr\"] === \"string\" ? { adr: decl[\"adr\"] } : {}),\n    });\n  }\n  return { present: true, byId };\n}\n"]}