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

package/dist/core/agent/scaffold.js

@@ -0,0 +1,259 @@
+/**
+ * The generated FILES: what a pointer file contains (the stub), what this
+ * binary would write (SLASH_COMMANDS, plannedCommandFiles), and how the files
+ * land and are detected on disk.
+ *
+ * The command and skill files go into the repo `init` runs in, because that is
+ * where the agent is invoked — for whichever tools the repo shows signs of, via
+ * the AGENT_TOOLS registry (tools/registry.ts): one shared body, a per-tool
+ * path and wrapper. A delivery is refreshed only while its bytes still match
+ * the digest loam recorded when it wrote them; a team's edits revoke that
+ * authority and outrank ours.
+ *
+ * Two deliveries, one body. A slash command has to be TYPED, so it only ever
+ * reaches an agent whose operator already knows loam exists. A skill is loaded
+ * by the model itself when the task matches its `description`, which is how the
+ * protocol reaches an agent that was never told about it. That difference is
+ * the whole reason both are written by default.
+ *
+ * The per-tool command and skill files carry the same version stamp AGENTS.md
+ * does (agents-md.ts), for the same reason and with the same answer:
+ * `loam doctor` reports `doctor.agent-files-stale` without writing. A later
+ * `loam init` can refresh only a digest-matched pointer. Without the stamp,
+ * absence was the only drift doctor could see — a command file mangled to one
+ * line left it saying `healthy: true`, which across a hundred repositories is
+ * invisible rot with no repair path.
+ */
+import { createHash } from "node:crypto";
+import { existsSync } from "node:fs";
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { dirname, join, relative } from "node:path";
+import { agentsStampLine } from "./agents-stamp.js";
+import { LOAM_VERSION } from "../envelope/version.js";
+import { AGENT_COMMANDS } from "./protocol.js";
+import { AGENT_TOOLS, CLAUDE } from "./tools/registry.js";
+/**
+ * What a generated file actually contains: the purpose, the spine, and the
+ * command that prints the rest.
+ *
+ * The protocol itself stays in `body` and ships inside the binary, reachable as
+ * `loam instructions <name>`. The file on disk gets a pointer to it, because
+ * these two things go stale in opposite directions and only one of them can be
+ * fixed. A generated file is refreshed only while its bytes still match the
+ * digest loam recorded; any edit revokes that authority because your edits
+ * outrank the template. Without that distinction a repo scaffolded a year ago
+ * holds a year-old protocol: exact
+ * flags, exact finding codes, exact step order, all of it asserted with total
+ * confidence by a file whose reader has no way to know it is describing a
+ * different release. That is not a hypothetical failure mode. It is the one
+ * every project shipping generated agent instructions has had, and the fix
+ * everybody reaches for — regenerate on upgrade — trades it for silently
+ * overwriting what a human wrote.
+ *
+ * Thinning the file is the third option. What remains is what does not move
+ * between releases: what this workflow is for, and the verbs in order. What
+ * leaves is everything version-shaped. `doctor.agent-files-stale` still reports
+ * a file whose stamp has fallen behind, and now has almost nothing to be right
+ * about — which is the point.
+ *
+ * The trade is real and worth stating: an agent that cannot execute `loam` now
+ * has a spine instead of a protocol. That is the correct failure. The exact
+ * diagnostic and lifecycle invocations belong to the binary-owned page; an
+ * agent that cannot run loam cannot finish either kind from an embedded copy —
+ * it can only try using a year-old flag.
+ *
+ * The last clause of the pointer is the one sentence here that changes what an
+ * agent DOES rather than what it knows. `loam instructions loam-check` prints
+ * 84 KB — about a fifth of a 100k-token window, 223 fix-table rows of which a
+ * run needs two or three — and every file written from this stub opens by
+ * telling the agent to run it. `--no-fix-tables` (commands/instructions.ts)
+ * drops the rows, and `loam explain <code>` answers the one row the run turned
+ * out to need in under 500 bytes. The flag is what makes the lazy path payable;
+ * this sentence is what makes an agent take it.
+ */
+function stubBody(c) {
+    const steps = c.spine.map((s, i) => `  ${i + 1}. ${s}`).join("\n");
+    const entry = c.name === "loam-report"
+        ? `This support protocol has two equivalent chat entry points: the explicit command a
+user chooses, and the Agent Skill an unexpected-run request may load. Both reach
+the same local, sanitized report; the agent owns the diagnostic steps.`
+        : `This workflow has two equivalent chat entry points: the explicit command a user
+chooses, and the Agent Skill a natural-language request may load. Both reach this
+same body and must produce the same status/edit/validate loop; do not make the
+user type the internal loam commands one by one.`;
+    const output = c.name === "loam-report"
+        ? `The runtime protocol decides which diagnostics are safe to run and what may enter the
+report. Do not infer permission to retry a writer, repair files or send the result
+from the broader lifecycle commands another generated skill may allow.`
+        : `Every step above is a \`loam\` invocation, and each command's own \`--json\` output
+carries what to do next: findings have stable codes, and \`loam status --json\` puts
+the ordered \`next[]\` — each entry a code and the literal command — in one place.
+Branch on the codes, never on the prose. The check workflow starts with
+\`--no-fix-tables\`; use \`loam explain <code>\` for each code the run actually
+reports, and remove that flag only when you deliberately need the complete table.`;
+    return `${c.purpose}
+
+${entry}
+
+**Run this first.** It is the protocol, and it ships with the binary you are about
+to call — so it names this loam's flags, its finding codes and its fix tables,
+not the ones that were current when this repository was scaffolded:
+
+    ${c.invocation}
+
+The spine it fills in, so you can tell a run that went sideways from one that did not:
+
+${steps}
+
+${output}
+
+This file is a pointer, not the protocol. loam may refresh it while its bytes still
+match the digest recorded in loam.json. Editing it revokes that authority: your
+changes outrank the template and stay untouched. Where this file and
+\`loam instructions\` disagree, the command is right.
+`;
+}
+/**
+ * The command body a file actually gets: the pointer, under the same version
+ * stamp AGENTS.md carries.
+ *
+ * The stamp is applied once, here, rather than in twenty wrappers — it is a
+ * fact about loam, not about a tool's dialect, and a per-wrapper copy is twenty
+ * chances to forget it. It rides at the top of the BODY (not the file) because
+ * every dialect puts something of its own first: YAML frontmatter, a TOML key,
+ * a title line. An HTML comment is invisible in all of them, and
+ * `agentsStampVersion` matches it wherever in the file it lands.
+ *
+ * A repo initialized before stamping existed has unstamped files, which is
+ * exactly what `doctor.agent-files-stale` is for: nobody has confirmed that
+ * those instructions still describe this binary.
+ */
+const stubbed = (c) => ({
+    ...c,
+    body: `${agentsStampLine(LOAM_VERSION)}\n\n${stubBody(c)}`,
+});
+/**
+ * The Claude-format files, keyed by command name: exactly what **this** binary
+ * would write, derived through the same adapter that writes them, so the export
+ * and a freshly scaffolded repo can never disagree.
+ *
+ * Read that scope literally. It used to be described as the on-disk contract of
+ * every repo initialized before `--tools` existed, and that is no longer true
+ * of anything but a fresh scaffold: a file holds the STUB now, every repo
+ * scaffolded before that holds the full protocol. A recorded, byte-identical
+ * pointer can refresh; an older unrecorded file or any customized file cannot,
+ * so an export cannot describe files this binary did not write.
+ *
+ * The protocol those older files carry is `PROTOCOLS`. Anything asserting on
+ * protocol content wants that one — this answers "what would loam write here",
+ * not "what does loam instruct".
+ */
+export const SLASH_COMMANDS = Object.fromEntries(AGENT_COMMANDS.map((c) => [c.name, CLAUDE.format(stubbed(c))]));
+/** The two ways a command body reaches an agent. Both are on by default. */
+export const DELIVERIES = ["commands", "skills"];
+export const AGENT_PROFILES = ["full", "service", "docs"];
+const PROFILE_COMMANDS = {
+    full: new Set(AGENT_COMMANDS.map((command) => command.name)),
+    service: new Set(["loam-adopt", "loam-implement", "loam-check", "loam-verify", "loam-report"]),
+    docs: new Set(["loam-feature", "loam-check", "loam-ship", "loam-report"]),
+};
+/**
+ * Every file the selected tools would lay down, in creation order — the same
+ * list `init` probes for `skipped` BEFORE the scaffold runs, so created +
+ * skipped is the same list on every repo.
+ *
+ * Called with two arguments it returns EVERYTHING the binary would write under
+ * default delivery: commands and skills both. That is the contract callers
+ * outside this module depend on — `loam doctor` asks "what should be here?"
+ * and a half-answer would report a fully-scaffolded repo as fully scaffolded
+ * while ignoring every skill file. The name predates the second delivery and is
+ * kept because it is imported elsewhere; `delivery` narrows it.
+ */
+export function plannedCommandFiles(cwd, toolIds, delivery = DELIVERIES, profile = "full") {
+    return toolIds.flatMap((id) => {
+        const tool = AGENT_TOOLS[id];
+        if (tool === undefined)
+            throw new Error(`unknown agent tool: ${id}`);
+        const emitters = [];
+        // A tool declares only the deliveries it actually reads, so an absent
+        // emitter is a fact about the tool, never a reason to fall back to some
+        // other tool's convention.
+        const { path, format, skill } = tool;
+        if (delivery.includes("commands") && path !== undefined && format !== undefined) {
+            emitters.push({ path, format });
+        }
+        if (delivery.includes("skills") && skill !== undefined)
+            emitters.push(skill);
+        return emitters.flatMap((e) => AGENT_COMMANDS.filter((command) => PROFILE_COMMANDS[profile].has(command.name)).map((c) => ({
+            path: join(cwd, ...e.path(c.name)),
+            content: e.format(stubbed(c)),
+        })));
+    });
+}
+function contentDigest(content) {
+    return createHash("sha256").update(content).digest("hex");
+}
+function manifestPath(cwd, path) {
+    return relative(cwd, path).replaceAll("\\", "/");
+}
+export function updatedAgentFileManifest(cwd, planned, existing, managed) {
+    const out = { ...existing };
+    for (const file of planned)
+        delete out[manifestPath(cwd, file.path)];
+    return Object.assign(out, managed);
+}
+/**
+ * Create missing files and refresh only files still byte-identical to the
+ * digest recorded when loam last wrote them. A human edit breaks that equality
+ * and therefore revokes loam's authority over the file without a marker block
+ * or a prompt.
+ */
+export async function syncAgentCommands(req) {
+    const { cwd, toolIds = ["claude"], delivery = DELIVERIES, profile = "full", known = {} } = req;
+    const out = { created: [], refreshed: [], managed: {} };
+    for (const { path, content } of plannedCommandFiles(cwd, toolIds, delivery, profile)) {
+        const key = manifestPath(cwd, path);
+        const desired = contentDigest(content);
+        if (!existsSync(path)) {
+            await mkdir(dirname(path), { recursive: true });
+            await writeFile(path, content, "utf8");
+            out.created.push(path);
+            out.managed[key] = desired;
+            continue;
+        }
+        const current = contentDigest(await readFile(path));
+        if (current === desired) {
+            out.managed[key] = desired;
+            continue;
+        }
+        if (known[key] !== current)
+            continue;
+        await writeFile(path, content, "utf8");
+        out.refreshed.push(path);
+        out.managed[key] = desired;
+    }
+    return out;
+}
+/**
+ * Backward-compatible create-only wrapper. Callers that own no digest manifest
+ * leave every existing file alone and receive only the paths created.
+ */
+export async function scaffoldAgentCommands(cwd, toolIds = ["claude"], delivery = DELIVERIES) {
+    return (await syncAgentCommands({ cwd, toolIds, delivery })).created;
+}
+/**
+ * The registry ids whose marker paths are present in `cwd` — what `loam init`
+ * writes for when nobody passed `--tools`.
+ *
+ * A repo with `.cursor/` and no Claude Code used to get `.claude/commands/`
+ * and nothing it could actually run. Presence is the whole test, and existence
+ * (not directory-ness) is what is asked, because a marker is as often a file as
+ * a directory — `.github/copilot-instructions.md` is the honest signal for
+ * Copilot where `.github/` itself is noise.
+ */
+export function detectAgentTools(cwd) {
+    return Object.entries(AGENT_TOOLS)
+        .filter(([, tool]) => tool.detect.some((marker) => existsSync(join(cwd, marker))))
+        .map(([id]) => id);
+}
+//# sourceMappingURL=scaffold.js.map

package/dist/core/agent/scaffold.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"scaffold.js","sourceRoot":"","sources":["../../../src/core/agent/scaffold.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * The generated FILES: what a pointer file contains (the stub), what this\n * binary would write (SLASH_COMMANDS, plannedCommandFiles), and how the files\n * land and are detected on disk.\n *\n * The command and skill files go into the repo `init` runs in, because that is\n * where the agent is invoked — for whichever tools the repo shows signs of, via\n * the AGENT_TOOLS registry (tools/registry.ts): one shared body, a per-tool\n * path and wrapper. A delivery is refreshed only while its bytes still match\n * the digest loam recorded when it wrote them; a team's edits revoke that\n * authority and outrank ours.\n *\n * Two deliveries, one body. A slash command has to be TYPED, so it only ever\n * reaches an agent whose operator already knows loam exists. A skill is loaded\n * by the model itself when the task matches its `description`, which is how the\n * protocol reaches an agent that was never told about it. That difference is\n * the whole reason both are written by default.\n *\n * The per-tool command and skill files carry the same version stamp AGENTS.md\n * does (agents-md.ts), for the same reason and with the same answer:\n * `loam doctor` reports `doctor.agent-files-stale` without writing. A later\n * `loam init` can refresh only a digest-matched pointer. Without the stamp,\n * absence was the only drift doctor could see — a command file mangled to one\n * line left it saying `healthy: true`, which across a hundred repositories is\n * invisible rot with no repair path.\n */\nimport { createHash } from \"node:crypto\";\nimport { existsSync } from \"node:fs\";\nimport { mkdir, readFile, writeFile } from \"node:fs/promises\";\nimport { dirname, join, relative } from \"node:path\";\nimport { agentsStampLine } from \"./agents-stamp.js\";\nimport { LOAM_VERSION } from \"../envelope/version.js\";\nimport type { AgentFileEmitter, CommandContent } from \"./contract.js\";\nimport { AGENT_COMMANDS } from \"./protocol.js\";\nimport { AGENT_TOOLS, CLAUDE } from \"./tools/registry.js\";\n\n/**\n * What a generated file actually contains: the purpose, the spine, and the\n * command that prints the rest.\n *\n * The protocol itself stays in `body` and ships inside the binary, reachable as\n * `loam instructions <name>`. The file on disk gets a pointer to it, because\n * these two things go stale in opposite directions and only one of them can be\n * fixed. A generated file is refreshed only while its bytes still match the\n * digest loam recorded; any edit revokes that authority because your edits\n * outrank the template. Without that distinction a repo scaffolded a year ago\n * holds a year-old protocol: exact\n * flags, exact finding codes, exact step order, all of it asserted with total\n * confidence by a file whose reader has no way to know it is describing a\n * different release. That is not a hypothetical failure mode. It is the one\n * every project shipping generated agent instructions has had, and the fix\n * everybody reaches for — regenerate on upgrade — trades it for silently\n * overwriting what a human wrote.\n *\n * Thinning the file is the third option. What remains is what does not move\n * between releases: what this workflow is for, and the verbs in order. What\n * leaves is everything version-shaped. `doctor.agent-files-stale` still reports\n * a file whose stamp has fallen behind, and now has almost nothing to be right\n * about — which is the point.\n *\n * The trade is real and worth stating: an agent that cannot execute `loam` now\n * has a spine instead of a protocol. That is the correct failure. The exact\n * diagnostic and lifecycle invocations belong to the binary-owned page; an\n * agent that cannot run loam cannot finish either kind from an embedded copy —\n * it can only try using a year-old flag.\n *\n * The last clause of the pointer is the one sentence here that changes what an\n * agent DOES rather than what it knows. `loam instructions loam-check` prints\n * 84 KB — about a fifth of a 100k-token window, 223 fix-table rows of which a\n * run needs two or three — and every file written from this stub opens by\n * telling the agent to run it. `--no-fix-tables` (commands/instructions.ts)\n * drops the rows, and `loam explain <code>` answers the one row the run turned\n * out to need in under 500 bytes. The flag is what makes the lazy path payable;\n * this sentence is what makes an agent take it.\n */\nfunction stubBody(c: CommandContent): string {\n  const steps = c.spine.map((s, i) => `  ${i + 1}. ${s}`).join(\"\\n\");\n  const entry = c.name === \"loam-report\"\n    ? `This support protocol has two equivalent chat entry points: the explicit command a\nuser chooses, and the Agent Skill an unexpected-run request may load. Both reach\nthe same local, sanitized report; the agent owns the diagnostic steps.`\n    : `This workflow has two equivalent chat entry points: the explicit command a user\nchooses, and the Agent Skill a natural-language request may load. Both reach this\nsame body and must produce the same status/edit/validate loop; do not make the\nuser type the internal loam commands one by one.`;\n  const output = c.name === \"loam-report\"\n    ? `The runtime protocol decides which diagnostics are safe to run and what may enter the\nreport. Do not infer permission to retry a writer, repair files or send the result\nfrom the broader lifecycle commands another generated skill may allow.`\n    : `Every step above is a \\`loam\\` invocation, and each command's own \\`--json\\` output\ncarries what to do next: findings have stable codes, and \\`loam status --json\\` puts\nthe ordered \\`next[]\\` — each entry a code and the literal command — in one place.\nBranch on the codes, never on the prose. The check workflow starts with\n\\`--no-fix-tables\\`; use \\`loam explain <code>\\` for each code the run actually\nreports, and remove that flag only when you deliberately need the complete table.`;\n  return `${c.purpose}\n\n${entry}\n\n**Run this first.** It is the protocol, and it ships with the binary you are about\nto call — so it names this loam's flags, its finding codes and its fix tables,\nnot the ones that were current when this repository was scaffolded:\n\n    ${c.invocation}\n\nThe spine it fills in, so you can tell a run that went sideways from one that did not:\n\n${steps}\n\n${output}\n\nThis file is a pointer, not the protocol. loam may refresh it while its bytes still\nmatch the digest recorded in loam.json. Editing it revokes that authority: your\nchanges outrank the template and stay untouched. Where this file and\n\\`loam instructions\\` disagree, the command is right.\n`;\n}\n\n/**\n * The command body a file actually gets: the pointer, under the same version\n * stamp AGENTS.md carries.\n *\n * The stamp is applied once, here, rather than in twenty wrappers — it is a\n * fact about loam, not about a tool's dialect, and a per-wrapper copy is twenty\n * chances to forget it. It rides at the top of the BODY (not the file) because\n * every dialect puts something of its own first: YAML frontmatter, a TOML key,\n * a title line. An HTML comment is invisible in all of them, and\n * `agentsStampVersion` matches it wherever in the file it lands.\n *\n * A repo initialized before stamping existed has unstamped files, which is\n * exactly what `doctor.agent-files-stale` is for: nobody has confirmed that\n * those instructions still describe this binary.\n */\nconst stubbed = (c: CommandContent): CommandContent => ({\n  ...c,\n  body: `${agentsStampLine(LOAM_VERSION)}\\n\\n${stubBody(c)}`,\n});\n\n/**\n * The Claude-format files, keyed by command name: exactly what **this** binary\n * would write, derived through the same adapter that writes them, so the export\n * and a freshly scaffolded repo can never disagree.\n *\n * Read that scope literally. It used to be described as the on-disk contract of\n * every repo initialized before `--tools` existed, and that is no longer true\n * of anything but a fresh scaffold: a file holds the STUB now, every repo\n * scaffolded before that holds the full protocol. A recorded, byte-identical\n * pointer can refresh; an older unrecorded file or any customized file cannot,\n * so an export cannot describe files this binary did not write.\n *\n * The protocol those older files carry is `PROTOCOLS`. Anything asserting on\n * protocol content wants that one — this answers \"what would loam write here\",\n * not \"what does loam instruct\".\n */\nexport const SLASH_COMMANDS: Record<string, string> = Object.fromEntries(\n  AGENT_COMMANDS.map((c) => [c.name, CLAUDE.format(stubbed(c))]),\n);\n\n/** The two ways a command body reaches an agent. Both are on by default. */\nexport const DELIVERIES = [\"commands\", \"skills\"] as const;\nexport type Delivery = (typeof DELIVERIES)[number];\n\nexport const AGENT_PROFILES = [\"full\", \"service\", \"docs\"] as const;\nexport type AgentProfile = (typeof AGENT_PROFILES)[number];\n\nconst PROFILE_COMMANDS: Record<AgentProfile, ReadonlySet<string>> = {\n  full: new Set(AGENT_COMMANDS.map((command) => command.name)),\n  service: new Set([\"loam-adopt\", \"loam-implement\", \"loam-check\", \"loam-verify\", \"loam-report\"]),\n  docs: new Set([\"loam-feature\", \"loam-check\", \"loam-ship\", \"loam-report\"]),\n};\n\n/**\n * Every file the selected tools would lay down, in creation order — the same\n * list `init` probes for `skipped` BEFORE the scaffold runs, so created +\n * skipped is the same list on every repo.\n *\n * Called with two arguments it returns EVERYTHING the binary would write under\n * default delivery: commands and skills both. That is the contract callers\n * outside this module depend on — `loam doctor` asks \"what should be here?\"\n * and a half-answer would report a fully-scaffolded repo as fully scaffolded\n * while ignoring every skill file. The name predates the second delivery and is\n * kept because it is imported elsewhere; `delivery` narrows it.\n */\nexport function plannedCommandFiles(\n  cwd: string,\n  toolIds: string[],\n  delivery: readonly Delivery[] = DELIVERIES,\n  profile: AgentProfile = \"full\",\n): Array<{ path: string; content: string }> {\n  return toolIds.flatMap((id) => {\n    const tool = AGENT_TOOLS[id];\n    if (tool === undefined) throw new Error(`unknown agent tool: ${id}`);\n    const emitters: AgentFileEmitter[] = [];\n    // A tool declares only the deliveries it actually reads, so an absent\n    // emitter is a fact about the tool, never a reason to fall back to some\n    // other tool's convention.\n    const { path, format, skill } = tool;\n    if (delivery.includes(\"commands\") && path !== undefined && format !== undefined) {\n      emitters.push({ path, format });\n    }\n    if (delivery.includes(\"skills\") && skill !== undefined) emitters.push(skill);\n    return emitters.flatMap((e) =>\n      AGENT_COMMANDS.filter((command) => PROFILE_COMMANDS[profile].has(command.name)).map((c) => ({\n        path: join(cwd, ...e.path(c.name)),\n        content: e.format(stubbed(c)),\n      })),\n    );\n  });\n}\n\nfunction contentDigest(content: string | Buffer): string {\n  return createHash(\"sha256\").update(content).digest(\"hex\");\n}\n\nfunction manifestPath(cwd: string, path: string): string {\n  return relative(cwd, path).replaceAll(\"\\\\\", \"/\");\n}\n\nexport function updatedAgentFileManifest(\n  cwd: string,\n  planned: Array<{ path: string }>,\n  existing: Readonly<Record<string, string>> | undefined,\n  managed: Readonly<Record<string, string>>,\n): Record<string, string> {\n  const out = { ...existing };\n  for (const file of planned) delete out[manifestPath(cwd, file.path)];\n  return Object.assign(out, managed);\n}\n\nexport interface AgentFileSync {\n  created: string[];\n  refreshed: string[];\n  /** Repo-relative path -> digest of the bytes loam is allowed to refresh. */\n  managed: Record<string, string>;\n}\n\n/**\n * Create missing files and refresh only files still byte-identical to the\n * digest recorded when loam last wrote them. A human edit breaks that equality\n * and therefore revokes loam's authority over the file without a marker block\n * or a prompt.\n */\nexport async function syncAgentCommands(req: {\n  cwd: string;\n  toolIds?: string[];\n  delivery?: readonly Delivery[];\n  profile?: AgentProfile;\n  known?: Readonly<Record<string, string>>;\n}): Promise<AgentFileSync> {\n  const { cwd, toolIds = [\"claude\"], delivery = DELIVERIES, profile = \"full\", known = {} } = req;\n  const out: AgentFileSync = { created: [], refreshed: [], managed: {} };\n  for (const { path, content } of plannedCommandFiles(cwd, toolIds, delivery, profile)) {\n    const key = manifestPath(cwd, path);\n    const desired = contentDigest(content);\n    if (!existsSync(path)) {\n      await mkdir(dirname(path), { recursive: true });\n      await writeFile(path, content, \"utf8\");\n      out.created.push(path);\n      out.managed[key] = desired;\n      continue;\n    }\n    const current = contentDigest(await readFile(path));\n    if (current === desired) {\n      out.managed[key] = desired;\n      continue;\n    }\n    if (known[key] !== current) continue;\n    await writeFile(path, content, \"utf8\");\n    out.refreshed.push(path);\n    out.managed[key] = desired;\n  }\n  return out;\n}\n\n/**\n * Backward-compatible create-only wrapper. Callers that own no digest manifest\n * leave every existing file alone and receive only the paths created.\n */\nexport async function scaffoldAgentCommands(\n  cwd: string,\n  toolIds: string[] = [\"claude\"],\n  delivery: readonly Delivery[] = DELIVERIES,\n): Promise<string[]> {\n  return (await syncAgentCommands({ cwd, toolIds, delivery })).created;\n}\n\n/**\n * The registry ids whose marker paths are present in `cwd` — what `loam init`\n * writes for when nobody passed `--tools`.\n *\n * A repo with `.cursor/` and no Claude Code used to get `.claude/commands/`\n * and nothing it could actually run. Presence is the whole test, and existence\n * (not directory-ness) is what is asked, because a marker is as often a file as\n * a directory — `.github/copilot-instructions.md` is the honest signal for\n * Copilot where `.github/` itself is noise.\n */\nexport function detectAgentTools(cwd: string): string[] {\n  return Object.entries(AGENT_TOOLS)\n    .filter(([, tool]) => tool.detect.some((marker) => existsSync(join(cwd, marker))))\n    .map(([id]) => id);\n}\n"]}

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

@@ -0,0 +1,103 @@
+/**
+ * The incident-reporting protocol: preserve a small, sanitized reproducer when
+ * loam or its agent integration behaves unexpectedly, without turning loam
+ * into a telemetry service or retrying a risky write.
+ */
+export const LOAM_REPORT = {
+    name: "loam-report",
+    description: "Record unexpected loam or agent behavior as a sanitized, reproducible Markdown report",
+    argumentHint: "",
+    purpose: "Collect one unexpected loam or agent-integration incident into a separate, reviewable Markdown file. This is local diagnostics only: redact secrets, never upload automatically, and never repeat a writer merely to reproduce it.",
+    invocation: "loam instructions loam-report",
+    placeholders: [],
+    spine: [
+        "preserve the user's original symptom and expected result before investigating",
+        "collect the binary version, wiring diagnosis and the smallest safe reproduction",
+        "classify the failure without repairing, retrying a writer or changing project documents",
+        "sanitize commands, paths and output, then write one report under loam-reports/",
+        "hand back the report path, classification and any evidence that could not be collected",
+    ],
+    body: `Record one incident where loam, a generated command/skill, or the agent following it
+behaved unexpectedly. The result is a local diagnostic document, not a repair and not telemetry.
+Do not change architecture/spec files while collecting it.
+
+## Preserve the symptom first
+
+Before running anything, write down the user's original request, what they expected, what actually
+happened, the command or chat entry point involved, and whether any files may already have changed.
+Do not improve or reinterpret the failing command yet: a cleaned-up command is not a reproduction.
+
+Classify the incident as one of these, using \`inconclusive\` until the evidence supports another:
+
+- \`loam-product\` — the binary violated its documented contract or produced internally inconsistent output;
+- \`project-data\` — the binary correctly reported invalid, incomplete or stale repository documents;
+- \`agent-workflow\` — the generated command/skill was missing, stale, misrouted or followed incorrectly;
+- \`host-infrastructure\` — permissions, filesystem, process, shell or tool-host behavior prevented the run;
+- \`inconclusive\` — the available evidence does not distinguish the above.
+
+## Collect only safe evidence
+
+1. Run \`loam --version\` and record the result.
+2. Run \`loam doctor --json\`. If it succeeds, keep \`healthy\`, the finding codes and their structured
+   locations/fixes, the resolved repository role, and the write-path state. If it refuses, keep
+   \`error.code\` and the sanitized message. Do not apply the fixes during reporting.
+3. When the repository is wired, run \`loam status --json\` and keep only the state and next-action
+   rows relevant to this incident. A refusal is evidence too; keep its \`error.code\`.
+4. Re-run the original operation only when it is read-only and safe. Never re-run \`init\`, \`new\`,
+   \`rebase\`, \`subsystem\`, \`archive\`, \`unarchive\`, \`vouch\`, a recording form of \`verify\`, or
+   any other writer merely to make it fail twice. For a writer, record its original exit/output and
+   inspect \`doctor\`, \`status\` and version only. Do not repair, roll back or delete anything unless
+   the user separately asks for that action.
+5. Prefer the JSON envelope: record \`contractVersion\`, \`ok\`, \`command\`, \`error.code\`, finding
+   codes and \`locations[]\`. Quote only the smallest stdout/stderr excerpt that demonstrates the
+   symptom. State what was omitted.
+
+## Sanitize before writing
+
+Never include credentials, tokens, cookies, authorization headers, private keys, environment dumps,
+or values of variables whose names contain \`TOKEN\`, \`SECRET\`, \`PASSWORD\`, \`AUTH\`, \`COOKIE\` or
+\`KEY\`. Replace each value with \`<redacted>\`. Replace the user's home directory with \`<home>\` and
+prefer repository-relative paths. Do not copy source files, architecture/spec bodies, or a complete
+command output when a code and short excerpt prove the same fact. Review the finished report once
+more for secrets before handing it back.
+
+## Write one separate report
+
+Create \`loam-reports/YYYY-MM-DD-<short-slug>.md\` at the current repository root. Use a short neutral
+slug based on the symptom, not a customer, person or secret. Never overwrite a different incident;
+add a numeric suffix when the path exists. Reports are ordinary project files so the team can
+review or commit them deliberately, but do not upload, submit an issue, send telemetry, or contact
+any service automatically.
+
+Use this shape, omitting only fields that truly cannot be known and marking them \`not collected\`:
+
+    # loam problem report: <short title>
+
+    - Recorded: <ISO-8601 timestamp>
+    - Classification: <one value above>
+    - Repository role: <docs | service | combined | unresolved>
+    - loam version: <version>
+    - Entry point: <chat command, skill, or CLI command; sanitized>
+    - Side effects observed: <none known | paths changed | unknown>
+
+    ## Summary
+    ## Expected
+    ## Actual
+    ## Minimal safe reproduction
+    ## Machine contract
+    ## Doctor and status evidence
+    ## Files changed or write state
+    ## Workaround
+    ## Missing evidence
+    ## Sanitization
+
+In \`Machine contract\`, include exit code plus the stable envelope fields and relevant finding
+codes/locations; do not paste an entire large JSON payload. In \`Sanitization\`, list the kinds of
+values removed without revealing them. If no workaround is known, say so rather than inventing one.
+
+Finish by telling the user the report path, classification, whether project files changed, and which
+evidence was unavailable. Keep diagnosis separate from certainty: a plausible cause belongs under
+\`Summary\` as a hypothesis until the reproduction proves it.
+`,
+};
+//# sourceMappingURL=report.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"report.js","sourceRoot":"","sources":["../../../../src/core/agent/support/report.ts"],"names":[],"mappings":"AAEA;;;;GAIG;AACH,MAAM,CAAC,MAAM,WAAW,GAAmB;IACzC,IAAI,EAAE,aAAa;IACnB,WAAW,EACT,uFAAuF;IACzF,YAAY,EAAE,EAAE;IAChB,OAAO,EACL,oOAAoO;IACtO,UAAU,EAAE,+BAA+B;IAC3C,YAAY,EAAE,EAAE;IAChB,KAAK,EAAE;QACL,+EAA+E;QAC/E,iFAAiF;QACjF,yFAAyF;QACzF,gFAAgF;QAChF,wFAAwF;KACzF;IACD,IAAI,EAAE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAiFP;CACA,CAAC","sourcesContent":["import type { CommandContent } from \"../contract.js\";\n\n/**\n * The incident-reporting protocol: preserve a small, sanitized reproducer when\n * loam or its agent integration behaves unexpectedly, without turning loam\n * into a telemetry service or retrying a risky write.\n */\nexport const LOAM_REPORT: CommandContent = {\n  name: \"loam-report\",\n  description:\n    \"Record unexpected loam or agent behavior as a sanitized, reproducible Markdown report\",\n  argumentHint: \"\",\n  purpose:\n    \"Collect one unexpected loam or agent-integration incident into a separate, reviewable Markdown file. This is local diagnostics only: redact secrets, never upload automatically, and never repeat a writer merely to reproduce it.\",\n  invocation: \"loam instructions loam-report\",\n  placeholders: [],\n  spine: [\n    \"preserve the user's original symptom and expected result before investigating\",\n    \"collect the binary version, wiring diagnosis and the smallest safe reproduction\",\n    \"classify the failure without repairing, retrying a writer or changing project documents\",\n    \"sanitize commands, paths and output, then write one report under loam-reports/\",\n    \"hand back the report path, classification and any evidence that could not be collected\",\n  ],\n  body: `Record one incident where loam, a generated command/skill, or the agent following it\nbehaved unexpectedly. The result is a local diagnostic document, not a repair and not telemetry.\nDo not change architecture/spec files while collecting it.\n\n## Preserve the symptom first\n\nBefore running anything, write down the user's original request, what they expected, what actually\nhappened, the command or chat entry point involved, and whether any files may already have changed.\nDo not improve or reinterpret the failing command yet: a cleaned-up command is not a reproduction.\n\nClassify the incident as one of these, using \\`inconclusive\\` until the evidence supports another:\n\n- \\`loam-product\\` — the binary violated its documented contract or produced internally inconsistent output;\n- \\`project-data\\` — the binary correctly reported invalid, incomplete or stale repository documents;\n- \\`agent-workflow\\` — the generated command/skill was missing, stale, misrouted or followed incorrectly;\n- \\`host-infrastructure\\` — permissions, filesystem, process, shell or tool-host behavior prevented the run;\n- \\`inconclusive\\` — the available evidence does not distinguish the above.\n\n## Collect only safe evidence\n\n1. Run \\`loam --version\\` and record the result.\n2. Run \\`loam doctor --json\\`. If it succeeds, keep \\`healthy\\`, the finding codes and their structured\n   locations/fixes, the resolved repository role, and the write-path state. If it refuses, keep\n   \\`error.code\\` and the sanitized message. Do not apply the fixes during reporting.\n3. When the repository is wired, run \\`loam status --json\\` and keep only the state and next-action\n   rows relevant to this incident. A refusal is evidence too; keep its \\`error.code\\`.\n4. Re-run the original operation only when it is read-only and safe. Never re-run \\`init\\`, \\`new\\`,\n   \\`rebase\\`, \\`subsystem\\`, \\`archive\\`, \\`unarchive\\`, \\`vouch\\`, a recording form of \\`verify\\`, or\n   any other writer merely to make it fail twice. For a writer, record its original exit/output and\n   inspect \\`doctor\\`, \\`status\\` and version only. Do not repair, roll back or delete anything unless\n   the user separately asks for that action.\n5. Prefer the JSON envelope: record \\`contractVersion\\`, \\`ok\\`, \\`command\\`, \\`error.code\\`, finding\n   codes and \\`locations[]\\`. Quote only the smallest stdout/stderr excerpt that demonstrates the\n   symptom. State what was omitted.\n\n## Sanitize before writing\n\nNever include credentials, tokens, cookies, authorization headers, private keys, environment dumps,\nor values of variables whose names contain \\`TOKEN\\`, \\`SECRET\\`, \\`PASSWORD\\`, \\`AUTH\\`, \\`COOKIE\\` or\n\\`KEY\\`. Replace each value with \\`<redacted>\\`. Replace the user's home directory with \\`<home>\\` and\nprefer repository-relative paths. Do not copy source files, architecture/spec bodies, or a complete\ncommand output when a code and short excerpt prove the same fact. Review the finished report once\nmore for secrets before handing it back.\n\n## Write one separate report\n\nCreate \\`loam-reports/YYYY-MM-DD-<short-slug>.md\\` at the current repository root. Use a short neutral\nslug based on the symptom, not a customer, person or secret. Never overwrite a different incident;\nadd a numeric suffix when the path exists. Reports are ordinary project files so the team can\nreview or commit them deliberately, but do not upload, submit an issue, send telemetry, or contact\nany service automatically.\n\nUse this shape, omitting only fields that truly cannot be known and marking them \\`not collected\\`:\n\n    # loam problem report: <short title>\n\n    - Recorded: <ISO-8601 timestamp>\n    - Classification: <one value above>\n    - Repository role: <docs | service | combined | unresolved>\n    - loam version: <version>\n    - Entry point: <chat command, skill, or CLI command; sanitized>\n    - Side effects observed: <none known | paths changed | unknown>\n\n    ## Summary\n    ## Expected\n    ## Actual\n    ## Minimal safe reproduction\n    ## Machine contract\n    ## Doctor and status evidence\n    ## Files changed or write state\n    ## Workaround\n    ## Missing evidence\n    ## Sanitization\n\nIn \\`Machine contract\\`, include exit code plus the stable envelope fields and relevant finding\ncodes/locations; do not paste an entire large JSON payload. In \\`Sanitization\\`, list the kinds of\nvalues removed without revealing them. If no workaround is known, say so rather than inventing one.\n\nFinish by telling the user the report path, classification, whether project files changed, and which\nevidence was unavailable. Keep diagnosis separate from certainty: a plausible cause belongs under\n\\`Summary\\` as a hypothesis until the reproduction proves it.\n`,\n};\n"]}

package/dist/core/agent/tools/dialects.js

@@ -0,0 +1,150 @@
+/**
+ * The loam verbs a generated file pre-approves, so an agent that honors the
+ * field stops asking permission for each call. Everything else a command needs
+ * (Read, Write, the service's own test runner) stays under the user's normal
+ * permission settings, and a tool that does not know the field ignores it.
+ *
+ * Enumerated rather than spelled `Bash(loam:*)`, for one verb's sake. `vouch`
+ * is the only command in loam whose output is a claim about a HUMAN act — a
+ * person read the code and says the document matches it — and a blanket
+ * allowlist pre-approved it, which handed the agent that wrote a draft the
+ * power to promote its own draft to `verified` without anybody being asked.
+ * That inverts the argument loam makes everywhere else: it holds test evidence
+ * to "an agent must not be able to SAY a scenario is tested", and then let one
+ * say a spec matches the code. `vouch` now refuses without a terminal or
+ * `--yes` (commands/vouch.ts) — this list is the other half, so the refusal is
+ * something a person sees rather than something an agent routes around.
+ *
+ * A verb missing from this list is not forbidden, only unapproved: the agent
+ * asks, and the user says yes. That is the correct cost for this one.
+ *
+ * The rule the list obeys is **every verb the CLI registers except the keys of
+ * {@link UNAPPROVED}**, and it admits no silent third category: a verb is
+ * either here or there, with a written reason. The rule it does NOT obey is
+ * "read-only" — that is false of `subsystem`, which writes, and it was never
+ * what this list did anyway: `archive`, `rebase` and `new` all write, and all
+ * three have been on it since the day the wildcard came off.
+ *
+ * The rule is written down because a hand-kept list drifts, and this one had.
+ * Seventeen of the twenty-nine registered verbs were on it, and three of the
+ * twelve missing ones were instructed by loam's own protocols: `loam-implement`
+ * opens with `loam context` and calls `loam steps` mandatory before a step
+ * definition is written, and `loam-check`'s fix table says to run
+ * `loam subsystem sync`. Each stalled on a permission prompt at exactly the
+ * step its own protocol calls required. It was worst for `explain`: every
+ * generated file now tells the agent to read the protocol narrow
+ * (`loam instructions <workflow> --no-fix-tables`) and then look up the codes
+ * the run actually reported — so the one command that makes an 84 KB page
+ * payable was the one the skill could not invoke unasked.
+ */
+const LOAM_ALLOWED_VERBS = [
+    "adopt",
+    "archive",
+    "context",
+    "delta",
+    "dependencies",
+    "diff",
+    "doctor",
+    "explain",
+    "explore",
+    "gate",
+    "gherkin",
+    "init",
+    "instructions",
+    "list",
+    "new",
+    "rebase",
+    "show",
+    "status",
+    "steps",
+    "subsystem",
+    "unarchive",
+    "validate",
+    "verify",
+];
+/**
+ * The verbs deliberately left OFF {@link LOAM_ALLOWED_VERBS}, each with the
+ * reason it is off.
+ *
+ * A map rather than a paragraph, because "every verb but the named exclusions"
+ * is only a checkable rule if the exclusions are a VALUE. test/agents.test.ts
+ * reads this one: the emitted allowlist must equal the CLI's registered
+ * commands minus these keys, so an absent verb is either a decision recorded
+ * here or a test failure — never something nobody can tell from a forgotten
+ * one, which is what the previous list was. Only `vouch` had ever been reasoned
+ * in the source, and its reason is the paragraph above, unchanged.
+ *
+ * The equality is checked in the test layer and cannot be computed here:
+ * deriving the allowlist from the command registry would mean `core/`
+ * importing `commands/`, which AGENTS.md forbids outright.
+ */
+export const UNAPPROVED = {
+    "audit-openspec": "the OpenSpec on-ramp: a one-time migration a person drives against a foreign workspace, named by no workflow protocol",
+    mcp: "a long-running stdio server rather than a call that returns — an agent that starts it inside a step waits forever",
+    "migrate-openspec": "the same on-ramp, and `--apply` materializes a whole target tree from a mapping only a human can have filled in",
+    open: "writes a `.code-workspace` for a person's editor; the output is aimed at the human, and no protocol step reads it",
+    seed: "templates the fleet map from a human-authored fleet.yaml — who exists and who calls whom is the one thing no generator may state",
+    vouch: "a claim about a HUMAN act, so an agent must not be able to SAY a spec matches the code; the refusal has to be something a person sees rather than something an agent routes around",
+};
+const LOAM_ALLOWED_TOOLS = LOAM_ALLOWED_VERBS.map((v) => `Bash(loam ${v}:*)`).join(", ");
+/**
+ * Incident collection is intentionally narrower than a lifecycle workflow.
+ * The body names writers so an agent can recognize and avoid retrying them;
+ * inheriting the lifecycle allowlist would nevertheless pre-authorize those
+ * same writers while diagnosing a bad run. Version, doctor and status are the
+ * complete command set the reporting protocol asks to execute.
+ */
+const REPORT_ALLOWED_TOOLS = [
+    "Bash(loam --version)",
+    "Bash(loam doctor:*)",
+    "Bash(loam instructions:*)",
+    "Bash(loam status:*)",
+].join(", ");
+const skillAllowedTools = (c) => c.name === "loam-report" ? REPORT_ALLOWED_TOOLS : LOAM_ALLOWED_TOOLS;
+/**
+ * The Agent Skills convention loam EMITS: `<root>/skills/<name>/SKILL.md`, YAML
+ * frontmatter, then the shared body verbatim — where `<root>` is whatever the
+ * calling registry entry passes.
+ *
+ * It used to say that every tool in the registry which reads skills spells the
+ * path this way. That was an unevidenced universal, and the `agents` entry
+ * falsifies it: `.agents/skills/` is a vendor-neutral root several tools read
+ * INSTEAD of their own dot-directory, not another tool's directory. Where a
+ * path is documented by the tool, the citation lives on that tool's registry
+ * entry — this helper states only what it writes.
+ *
+ * `description` is load-bearing in a way no command file's is — it is the only
+ * thing the model sees before deciding whether to load the skill — so it comes
+ * from the same `CommandContent.description` the command wrappers use rather
+ * than a second, skill-flavoured copy that could drift into a better pitch for
+ * a worse protocol.
+ */
+export const skillsIn = (dir) => ({
+    path: (name) => [dir, "skills", name, "SKILL.md"],
+    format: (c) => `---\nname: ${c.name}\ndescription: ${c.description}\n` +
+        `allowed-tools: ${skillAllowedTools(c)}\n---\n\n${c.body}`,
+});
+/**
+ * TOML basic-string escapes for the one non-markdown format. Today's bodies
+ * carry neither backslashes nor `"""`, but the escape is what keeps a future
+ * body edit from silently corrupting the generated TOML.
+ */
+export const tomlLine = (s) => s.replace(/\\/g, "\\\\").replace(/"/g, '\\"');
+export const tomlBlock = (s) => s.replace(/\\/g, "\\\\").replace(/"""/g, '""\\"');
+/* The four markdown command dialects the registry actually needs. Shared so a
+ * tool's entry is its PATH and its dialect's name — the part that differs —
+ * instead of a wall of near-identical template literals. `claude` deliberately
+ * spells its own wrapper inline even though `hintedMd` matches it byte for
+ * byte: an edit made here for some other tool must not be able to re-spell the
+ * one format that is frozen. */
+/** Description-only frontmatter — the most common dialect by a wide margin. */
+export const describedMd = (c) => `---\ndescription: ${c.description}\n---\n\n${c.body}`;
+/** Description plus Claude's `argument-hint`, for the tools that copied it. */
+export const hintedMd = (c) => `---\ndescription: ${c.description}\nargument-hint: ${c.argumentHint}\n---\n\n${c.body}`;
+/** Name plus description — the Cascade-style workflow frontmatter. */
+export const namedMd = (c) => `---\nname: ${c.name}\ndescription: ${c.description}\n---\n\n${c.body}`;
+/** No frontmatter at all: a title line is the whole wrapper. */
+export const titledMd = (c) => `# ${c.name}\n\n${c.body}`;
+/** The `loam-` prefix a namespace directory carries instead of the file name. */
+export const unprefixed = (name) => name.replace(/^loam-/, "");
+//# sourceMappingURL=dialects.js.map

package/dist/core/agent/tools/dialects.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"dialects.js","sourceRoot":"","sources":["../../../../src/core/agent/tools/dialects.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * How one shared command body is SPELLED per tool family: the markdown and\n * TOML wrapper dialects, and the Agent Skills convention. registry.ts builds\n * its entries from these — nothing here adds prose of its own, so the body\n * stays one source of truth however many tools spell it.\n */\nimport type { AgentFileEmitter, CommandContent } from \"../contract.js\";\n\n/**\n * The loam verbs a generated file pre-approves, so an agent that honors the\n * field stops asking permission for each call. Everything else a command needs\n * (Read, Write, the service's own test runner) stays under the user's normal\n * permission settings, and a tool that does not know the field ignores it.\n *\n * Enumerated rather than spelled `Bash(loam:*)`, for one verb's sake. `vouch`\n * is the only command in loam whose output is a claim about a HUMAN act — a\n * person read the code and says the document matches it — and a blanket\n * allowlist pre-approved it, which handed the agent that wrote a draft the\n * power to promote its own draft to `verified` without anybody being asked.\n * That inverts the argument loam makes everywhere else: it holds test evidence\n * to \"an agent must not be able to SAY a scenario is tested\", and then let one\n * say a spec matches the code. `vouch` now refuses without a terminal or\n * `--yes` (commands/vouch.ts) — this list is the other half, so the refusal is\n * something a person sees rather than something an agent routes around.\n *\n * A verb missing from this list is not forbidden, only unapproved: the agent\n * asks, and the user says yes. That is the correct cost for this one.\n *\n * The rule the list obeys is **every verb the CLI registers except the keys of\n * {@link UNAPPROVED}**, and it admits no silent third category: a verb is\n * either here or there, with a written reason. The rule it does NOT obey is\n * \"read-only\" — that is false of `subsystem`, which writes, and it was never\n * what this list did anyway: `archive`, `rebase` and `new` all write, and all\n * three have been on it since the day the wildcard came off.\n *\n * The rule is written down because a hand-kept list drifts, and this one had.\n * Seventeen of the twenty-nine registered verbs were on it, and three of the\n * twelve missing ones were instructed by loam's own protocols: `loam-implement`\n * opens with `loam context` and calls `loam steps` mandatory before a step\n * definition is written, and `loam-check`'s fix table says to run\n * `loam subsystem sync`. Each stalled on a permission prompt at exactly the\n * step its own protocol calls required. It was worst for `explain`: every\n * generated file now tells the agent to read the protocol narrow\n * (`loam instructions <workflow> --no-fix-tables`) and then look up the codes\n * the run actually reported — so the one command that makes an 84 KB page\n * payable was the one the skill could not invoke unasked.\n */\nconst LOAM_ALLOWED_VERBS = [\n  \"adopt\",\n  \"archive\",\n  \"context\",\n  \"delta\",\n  \"dependencies\",\n  \"diff\",\n  \"doctor\",\n  \"explain\",\n  \"explore\",\n  \"gate\",\n  \"gherkin\",\n  \"init\",\n  \"instructions\",\n  \"list\",\n  \"new\",\n  \"rebase\",\n  \"show\",\n  \"status\",\n  \"steps\",\n  \"subsystem\",\n  \"unarchive\",\n  \"validate\",\n  \"verify\",\n] as const;\n\n/**\n * The verbs deliberately left OFF {@link LOAM_ALLOWED_VERBS}, each with the\n * reason it is off.\n *\n * A map rather than a paragraph, because \"every verb but the named exclusions\"\n * is only a checkable rule if the exclusions are a VALUE. test/agents.test.ts\n * reads this one: the emitted allowlist must equal the CLI's registered\n * commands minus these keys, so an absent verb is either a decision recorded\n * here or a test failure — never something nobody can tell from a forgotten\n * one, which is what the previous list was. Only `vouch` had ever been reasoned\n * in the source, and its reason is the paragraph above, unchanged.\n *\n * The equality is checked in the test layer and cannot be computed here:\n * deriving the allowlist from the command registry would mean `core/`\n * importing `commands/`, which AGENTS.md forbids outright.\n */\nexport const UNAPPROVED: Record<string, string> = {\n  \"audit-openspec\":\n    \"the OpenSpec on-ramp: a one-time migration a person drives against a foreign workspace, named by no workflow protocol\",\n  mcp: \"a long-running stdio server rather than a call that returns — an agent that starts it inside a step waits forever\",\n  \"migrate-openspec\":\n    \"the same on-ramp, and `--apply` materializes a whole target tree from a mapping only a human can have filled in\",\n  open: \"writes a `.code-workspace` for a person's editor; the output is aimed at the human, and no protocol step reads it\",\n  seed: \"templates the fleet map from a human-authored fleet.yaml — who exists and who calls whom is the one thing no generator may state\",\n  vouch:\n    \"a claim about a HUMAN act, so an agent must not be able to SAY a spec matches the code; the refusal has to be something a person sees rather than something an agent routes around\",\n};\n\nconst LOAM_ALLOWED_TOOLS = LOAM_ALLOWED_VERBS.map((v) => `Bash(loam ${v}:*)`).join(\", \");\n\n/**\n * Incident collection is intentionally narrower than a lifecycle workflow.\n * The body names writers so an agent can recognize and avoid retrying them;\n * inheriting the lifecycle allowlist would nevertheless pre-authorize those\n * same writers while diagnosing a bad run. Version, doctor and status are the\n * complete command set the reporting protocol asks to execute.\n */\nconst REPORT_ALLOWED_TOOLS = [\n  \"Bash(loam --version)\",\n  \"Bash(loam doctor:*)\",\n  \"Bash(loam instructions:*)\",\n  \"Bash(loam status:*)\",\n].join(\", \");\n\nconst skillAllowedTools = (c: CommandContent): string =>\n  c.name === \"loam-report\" ? REPORT_ALLOWED_TOOLS : LOAM_ALLOWED_TOOLS;\n\n/**\n * The Agent Skills convention loam EMITS: `<root>/skills/<name>/SKILL.md`, YAML\n * frontmatter, then the shared body verbatim — where `<root>` is whatever the\n * calling registry entry passes.\n *\n * It used to say that every tool in the registry which reads skills spells the\n * path this way. That was an unevidenced universal, and the `agents` entry\n * falsifies it: `.agents/skills/` is a vendor-neutral root several tools read\n * INSTEAD of their own dot-directory, not another tool's directory. Where a\n * path is documented by the tool, the citation lives on that tool's registry\n * entry — this helper states only what it writes.\n *\n * `description` is load-bearing in a way no command file's is — it is the only\n * thing the model sees before deciding whether to load the skill — so it comes\n * from the same `CommandContent.description` the command wrappers use rather\n * than a second, skill-flavoured copy that could drift into a better pitch for\n * a worse protocol.\n */\nexport const skillsIn = (dir: string): AgentFileEmitter => ({\n  path: (name) => [dir, \"skills\", name, \"SKILL.md\"],\n  format: (c) =>\n    `---\\nname: ${c.name}\\ndescription: ${c.description}\\n` +\n    `allowed-tools: ${skillAllowedTools(c)}\\n---\\n\\n${c.body}`,\n});\n\n/**\n * TOML basic-string escapes for the one non-markdown format. Today's bodies\n * carry neither backslashes nor `\"\"\"`, but the escape is what keeps a future\n * body edit from silently corrupting the generated TOML.\n */\nexport const tomlLine = (s: string): string => s.replace(/\\\\/g, \"\\\\\\\\\").replace(/\"/g, '\\\\\"');\nexport const tomlBlock = (s: string): string => s.replace(/\\\\/g, \"\\\\\\\\\").replace(/\"\"\"/g, '\"\"\\\\\"');\n\n/* The four markdown command dialects the registry actually needs. Shared so a\n * tool's entry is its PATH and its dialect's name — the part that differs —\n * instead of a wall of near-identical template literals. `claude` deliberately\n * spells its own wrapper inline even though `hintedMd` matches it byte for\n * byte: an edit made here for some other tool must not be able to re-spell the\n * one format that is frozen. */\n/** Description-only frontmatter — the most common dialect by a wide margin. */\nexport const describedMd = (c: CommandContent): string =>\n  `---\\ndescription: ${c.description}\\n---\\n\\n${c.body}`;\n/** Description plus Claude's `argument-hint`, for the tools that copied it. */\nexport const hintedMd = (c: CommandContent): string =>\n  `---\\ndescription: ${c.description}\\nargument-hint: ${c.argumentHint}\\n---\\n\\n${c.body}`;\n/** Name plus description — the Cascade-style workflow frontmatter. */\nexport const namedMd = (c: CommandContent): string =>\n  `---\\nname: ${c.name}\\ndescription: ${c.description}\\n---\\n\\n${c.body}`;\n/** No frontmatter at all: a title line is the whole wrapper. */\nexport const titledMd = (c: CommandContent): string => `# ${c.name}\\n\\n${c.body}`;\n\n/** The `loam-` prefix a namespace directory carries instead of the file name. */\nexport const unprefixed = (name: string): string => name.replace(/^loam-/, \"\");\n"]}