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

package/dist/core/agent/agents-stamp.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agents-stamp.js","sourceRoot":"","sources":["../../../src/core/agent/agents-stamp.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * The AGENTS.md version stamp: detection, never refresh.\n *\n * AGENTS.md is written once by `loam init` and never touched again — that is\n * the ownership contract (agent.ts): it is a starting point, and a team's edits\n * to it outrank ours. But the file tells agents to branch on flag and code\n * tables, and those tables describe the binary that wrote them. OpenSpec hit\n * the same wall and answered with auto-refresh, which teaches everyone the file\n * belongs to the tool after all; loam answers with the smallest honest thing —\n * a version stamp in the generated file, and one warning when the stamp is\n * missing or trails the running binary. Reviewing the file and bumping the\n * stamp is a human act, and a hand-curated file silences the warning the same\n * way: by saying, in the stamp, that someone has looked.\n */\nimport type { Finding } from \"../vocabulary/report.js\";\n\n/** The stamp `loam init` writes at the top of AGENTS.md. */\nexport function agentsStampLine(version: string): string {\n  return `<!-- generated by loam v${version} -->`;\n}\n\n/** Matches a stamp line anywhere in the file; the capture is the version text. */\nconst STAMP_RE = /<!--\\s*generated by loam v(\\S+?)\\s*-->/;\n\n/**\n * `text` with its stamp, when it has one, rewritten to name `version` — every\n * other byte untouched. What lets a caller ask whether a generated file differs\n * from what a binary would write in anything BUT the stamp: the pointer files\n * carry this same line, and a release that changes nothing in their body still\n * changes it.\n */\nexport function restamped(text: string, version: string): string {\n  return text.replace(STAMP_RE, agentsStampLine(version));\n}\n\n/**\n * The version the stamp names, or null when there is no stamp (or one whose\n * version does not read as numbers — unparseable is indistinguishable from\n * absent, and both get the same advice).\n */\nexport function agentsStampVersion(text: string): string | null {\n  const m = STAMP_RE.exec(text);\n  return m !== null && parseVersion(m[1]!) !== null ? m[1]! : null;\n}\n\n/** A version split the way precedence is decided: the triple, then the prerelease identifiers. */\ninterface ParsedVersion {\n  release: [number, number, number];\n  /**\n   * The dot-separated identifiers of a `-beta.2` suffix, empty for a final\n   * release. Build metadata (`+sha`) is dropped — semver excludes it from\n   * precedence, and two builds of one version are the same instructions.\n   */\n  pre: string[];\n}\n\n/** `X.Y.Z[-pre][+build]`, or null when the leading triple does not read as numbers. */\nfunction parseVersion(v: string): ParsedVersion | null {\n  const m = /^(\\d+)\\.(\\d+)\\.(\\d+)(?:-([0-9A-Za-z.-]+))?(?:\\+[0-9A-Za-z.-]+)?$/.exec(v);\n  if (m === null) return null;\n  return {\n    release: [Number(m[1]), Number(m[2]), Number(m[3])],\n    pre: m[4] === undefined ? [] : m[4].split(\".\"),\n  };\n}\n\n/**\n * Semver identifier precedence: numeric identifiers compare numerically and\n * rank below alphanumeric ones, and a longer identifier list outranks a prefix\n * of itself. -1 / 0 / 1, so the caller reads like the triple comparison above.\n */\nfunction comparePre(a: string[], b: string[]): number {\n  // No prerelease outranks any prerelease — `1.2.0` is newer than `1.2.0-beta.9`\n  // — which is why this cannot be the plain lexicographic walk the identifiers get.\n  if (a.length === 0 || b.length === 0) return a.length === b.length ? 0 : a.length === 0 ? 1 : -1;\n  for (let i = 0; i < Math.min(a.length, b.length); i += 1) {\n    const [x, y] = [a[i]!, b[i]!];\n    if (x === y) continue;\n    const [nx, ny] = [/^\\d+$/.test(x), /^\\d+$/.test(y)];\n    if (nx && ny) return Number(x) < Number(y) ? -1 : 1;\n    if (nx !== ny) return nx ? -1 : 1;\n    return x < y ? -1 : 1;\n  }\n  return a.length === b.length ? 0 : a.length < b.length ? -1 : 1;\n}\n\n/**\n * Does `stamp` name an older version than `binary`? A stamp NEWER than the\n * binary does not trail: that is an old binary, not a stale file, and the fix\n * (upgrade loam) is not an AGENTS.md edit.\n *\n * Prerelease identifiers are compared, not ignored, and the difference is the\n * whole reason this check exists. Comparing the numeric triple alone made\n * `0.1.0-beta.1` and `0.1.0-beta.2` indistinguishable — and beta.2 is precisely\n * the release that changed the FORM of every generated file (embedded protocol\n * text became a pointer at `loam instructions`), with a CHANGELOG telling\n * readers to delete the files and re-run `loam init`. The one upgrade that most\n * needed the warning was the one bump shape that could not raise it. A\n * prerelease line is where a generated file's form actually moves, because that\n * is what a prerelease is for.\n */\nexport function versionTrails(stamp: string, binary: string): boolean {\n  const s = parseVersion(stamp);\n  const b = parseVersion(binary);\n  if (s === null || b === null) return false;\n  for (let i = 0; i < 3; i += 1) {\n    if (s.release[i]! !== b.release[i]!) return s.release[i]! < b.release[i]!;\n  }\n  return comparePre(s.pre, b.pre) < 0;\n}\n\n/**\n * Does `stamp` name a version NEWER than the binary reading it? The mirror of\n * {@link versionTrails}, and a different subject rather than its negation:\n * equal versions are neither.\n */\nexport function versionAhead(stamp: string, binary: string): boolean {\n  return versionTrails(binary, stamp);\n}\n\n/**\n * `docs.binary-behind` — this loam is OLDER than the loam that wrote the docs\n * repo it is reading.\n *\n * The false-green this closes is the sharpest one in the product, because it\n * inverts the meaning of a passing run rather than merely missing a defect.\n * loam's whole promise is that a token spelled here must be spelled there — so\n * every check is an existence constraint over a value the parser recognised.\n * A binary that predates a grammar addition does not FAIL on the newer\n * directive; it does not see it, produces no value, has nothing to join, and\n * reports green. The corpus is checked less than it looks, and nothing anywhere\n * says so. `agents.stale` is the opposite direction and explicitly declines\n * this case (\"that is an old binary, not a stale file\") — correctly, because\n * the fix is different: upgrade loam, do not edit the file.\n *\n * A WARNING, not an error, and the reasoning is the `sources.stale` doctrine.\n * A mixed-version fleet is ordinary — one engineer's global install trails a\n * release by a week — and failing every command in that repo would be a\n * refusal aimed at the wrong person on the wrong day. What the message must do\n * instead is say plainly that a green run from this binary is worth less than\n * it appears, which no other finding says. A fleet that wants it to gate has\n * `--strict`, which is exactly the lever that doctrine reserves for this.\n *\n * Silent when there is no file, no stamp, or the stamp is equal or older —\n * every one of those is somebody else's finding.\n */\nexport function binaryBehindFinding(text: string | null, binary: string): Finding | null {\n  if (text === null) return null;\n  const stamp = agentsStampVersion(text);\n  if (stamp === null || !versionAhead(stamp, binary)) return null;\n  return {\n    severity: \"warn\",\n    code: \"docs.binary-behind\",\n    message:\n      `This docs repo was written by loam v${stamp}; this binary is v${binary}. A newer loam may check ` +\n      \"joins this one cannot parse — an unrecognised directive is read as prose, so it produces no \" +\n      \"join to fail and this run reports green without having graded it. Treat a pass from this \" +\n      `binary as incomplete rather than clean, and upgrade to v${stamp} or later (\\`npm i -g @ybotok/loam\\`). ` +\n      \"Nothing here is wrong with the documents; the reader is behind them.\",\n  };\n}\n\n/**\n * The one finding `loam validate --all` owes the agent contract. `text` is the\n * docs repo's AGENTS.md, or null when there is none — no file means no contract\n * to have drifted, and this check stays silent rather than inventing a second\n * meaning for its code. Returns null when the stamp is current (or newer).\n */\nexport function agentsStaleFinding(text: string | null, binary: string): Finding | null {\n  if (text === null) return null;\n  const stamp = agentsStampVersion(text);\n  if (stamp === null) {\n    return {\n      severity: \"warn\",\n      code: \"agents.stale\",\n      message:\n        \"AGENTS.md has no version stamp — it predates stamping or was hand-created, so nothing says \" +\n        \"which loam its flag and code tables describe. Review it against the current `loam --help`, \" +\n        `then add \\`${agentsStampLine(binary)}\\` near the top; a hand-curated file keeps the warning ` +\n        \"off the same way, by keeping the stamp current.\",\n    };\n  }\n  if (!versionTrails(stamp, binary)) return null;\n  return {\n    severity: \"warn\",\n    code: \"agents.stale\",\n    message:\n      `AGENTS.md was written by loam v${stamp}; this binary is v${binary} — the flag and code tables ` +\n      \"agents branch on may have moved. Review the file against the current `loam --help`, then \" +\n      `update the stamp line to v${binary} (a hand-curated file silences this by bumping the stamp itself).`,\n  };\n}\n"]}

package/dist/core/agent/contract.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=contract.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"contract.js","sourceRoot":"","sources":["../../../src/core/agent/contract.ts"],"names":[],"mappings":"","sourcesContent":["/**\n * The shapes of the agent contract: what a workflow protocol is made of and\n * what a per-tool delivery adds around it. Types only, deliberately — a leaf\n * module the rest of the package `import type`s from. scripts/package-graph.mjs\n * counts only value imports, so keeping this file value-free is what lets\n * workflows/ and tools/ depend on the shapes without a package edge back into\n * the agent root, and what keeps that graph acyclic.\n */\n/**\n * One slash command, format-free. `body` is the whole protocol — the per-tool\n * emitters in AGENT_TOOLS add only a path and a wrapper (frontmatter fields, a\n * TOML shell), never their own prose: one source of truth, thin spellings.\n * Bodies keep Claude's positional `$1`/`$2` placeholder convention across\n * every tool — dialects differ (Gemini's {{args}}, Copilot's ${input}) and rewriting the\n * text per tool would be a second copy of the protocol in all but name; an\n * agent reading the file still sees which argument goes where.\n */\n/**\n * What a protocol's positional placeholder denotes. `free` is the one that\n * cannot be checked — `loam-feature`'s `$2` is a human title, and any string is\n * a legal one — and it is spelled rather than left implicit so a new\n * placeholder has to state which of the three it is.\n */\nexport type PlaceholderKind = \"service\" | \"feature\" | \"free\";\n\nexport interface CommandContent {\n  /** Stable command name (`loam-check`) — also the flat file name everywhere. */\n  name: string;\n  description: string;\n  /** What the user passes, in Claude's `argument-hint` spelling. */\n  argumentHint: string;\n  /** One or two sentences: what this workflow is for, and who does which half. */\n  purpose: string;\n  /**\n   * The literal `loam instructions …` line the generated file tells an agent to\n   * run, placeholders and all. Spelled per command rather than derived from\n   * `argumentHint`, because the mapping from a hint to positional arguments is\n   * exactly the kind of clever derivation that is right five times and wrong\n   * once — and the once is a command an agent pastes.\n   */\n  invocation: string;\n  /**\n   * What `$1`, `$2`, … stand for in `body`, in order — so the substitution can\n   * be checked instead of merely performed.\n   *\n   * `loam instructions loam-adopt \"$PWD\"` used to render a protocol reading\n   * `services//Users/someone/work/svc/` and `--service /Users/someone/…`: the\n   * placeholder is a service id, the value was an absolute path, and nothing\n   * between the shell and the printed page knew the difference. The commands\n   * downstream all refuse it — `assertServiceId` is one rule in one place, and\n   * it says so well — so a bad brief could never become bad documentation. But\n   * the refusal arrives one step late, after an agent has read a page of\n   * confident instructions built around a value that cannot work, and the\n   * cheapest place to say \"that is not a service id\" is the command that was\n   * told the argument IS one.\n   */\n  placeholders: readonly PlaceholderKind[];\n  /**\n   * The verbs, in order, and nothing else. This is the half of the protocol\n   * that does not move between releases: a reader with a stale file can still\n   * tell whether a run went sideways, without the file claiming to know this\n   * binary's flags or finding codes.\n   */\n  spine: string[];\n  /** The protocol itself: markdown, ends with a newline. */\n  body: string;\n}\n\n/**\n * One delivery of one command: where the file goes, and what goes in it. Both\n * halves are thin by construction — the protocol is `CommandContent.body` and\n * nothing here may restate it.\n */\nexport interface AgentFileEmitter {\n  /** Repo-relative path segments of the file. */\n  path(name: string): string[];\n  /** The full file: this tool's wrapper around the shared body. */\n  format(cmd: CommandContent): string;\n}\n\n/**\n * A tool the commands can be emitted for — the registry key is the `--tools`\n * id (OpenSpec's ids where the tool has one there). A path and a wrapper are\n * the WHOLE adapter: OpenSpec's per-tool command layer, minus everything loam\n * refuses on principle — no version stamps in command files, no\n * overwrite-on-update, no managed marker blocks in anyone else's file. Paths\n * and wrappers follow each tool's own documented convention, pinned in\n * test/agents.test.ts.\n */\nexport interface AgentTool {\n  /**\n   * Repo-relative path segments of one command's file. Absent — together with\n   * `format` — for a tool that registers no command files at all: Codex reads\n   * skills and nothing else, and inventing a command directory for it would\n   * scatter files no agent ever loads.\n   */\n  path?(name: string): string[];\n  /** The full command file: this tool's wrapper around the shared body. */\n  format?(cmd: CommandContent): string;\n  /** The skill delivery. Absent for a tool with no skills convention. */\n  skill?: AgentFileEmitter;\n  /**\n   * Repo-relative paths whose presence means this tool is in use here — what\n   * `loam init` scans when no `--tools` says otherwise. Usually just the tool's\n   * own dot-directory; spelled per tool because the exceptions matter more than\n   * the rule (see `github-copilot`, whose `.github/` says nothing at all).\n   */\n  detect: string[];\n}\n"]}

package/dist/core/agent/protocol.js

@@ -0,0 +1,193 @@
+/**
+ * The protocol surface: six lifecycle workflows, the support protocol and the
+ * reference pages — what `loam instructions` prints (commands/instructions.ts)
+ * and the corpus every check over loam's agent-facing prose reads
+ * (test/codes-drift.test.ts, test/agent-contract.test.ts,
+ * test/agent-commands-runnable.test.ts).
+ */
+import { featureIdProblem } from "../kernel/ids/feature.js";
+import { serviceIdProblem } from "../kernel/ids/service.js";
+import { LOAM_ADOPT } from "./workflows/adopt.js";
+import { LOAM_CHECK } from "./workflows/check.js";
+import { LOAM_VERIFY, LOAM_SHIP } from "./workflows/closing.js";
+import { LOAM_FEATURE } from "./workflows/feature.js";
+import { LOAM_IMPLEMENT } from "./workflows/implement.js";
+import { REFERENCES } from "./workflows/reference/reference.js";
+import { LOAM_REPORT } from "./support/report.js";
+/**
+ * The six protocols, in cycle order. One assembly, exported: scaffold.ts
+ * derives the generated files through this same list, so what
+ * `loam instructions` prints and what a fresh scaffold writes cannot drift
+ * apart.
+ */
+export const COMMANDS = [
+    LOAM_ADOPT,
+    LOAM_FEATURE,
+    LOAM_IMPLEMENT,
+    LOAM_CHECK,
+    LOAM_VERIFY,
+    LOAM_SHIP,
+];
+/**
+ * Support entry points generated beside the lifecycle, but not counted as
+ * lifecycle steps. Reporting a bad run must be discoverable in every profile;
+ * placing it in COMMANDS would make a consumer iterating that list try to run
+ * incident collection after every feature.
+ */
+export const SUPPORT = [LOAM_REPORT];
+/** Every command/skill file init generates, regardless of category. */
+export const AGENT_COMMANDS = [...COMMANDS, ...SUPPORT];
+/**
+ * Everything `loam instructions <name>` can print: the six workflows, support
+ * protocol and five reference pages, in that order.
+ *
+ * The pages join the generated protocols HERE and nowhere else — not in
+ * {@link AGENT_COMMANDS}, which is what scaffold.ts derives `SLASH_COMMANDS`
+ * and `plannedCommandFiles` from. That is the whole mechanism, and the
+ * asymmetry is the point: a page is printable by name but `loam init` writes no
+ * file for it, so moving 44 KB out of AGENTS.md did not put 44 KB back as four
+ * new artifacts in every repository loam touches. The support protocol does
+ * belong in AGENT_COMMANDS because discovery is its purpose, while its separate
+ * menu category keeps it out of the lifecycle. test/agents.test.ts asserts the
+ * reference-page halves separately, because a future edit can break either
+ * alone.
+ */
+const PRINTABLE = [...AGENT_COMMANDS, ...REFERENCES];
+/**
+ * The printable bodies, keyed by name — what `loam instructions <name>` prints,
+ * and the corpus every check over loam's agent-facing prose reads.
+ *
+ * Separate from SLASH_COMMANDS since the file became a pointer: the protocol is
+ * still the thing that must document every stable code (`codes-drift`) and
+ * every `loam …` line it teaches must still parse against the real CLI
+ * (`agent-commands-runnable`). Those two properties are about the INSTRUCTIONS,
+ * and they did not move just because the delivery did.
+ *
+ * The reference pages belong in this record for exactly that reason. Every code
+ * they carry LEFT AGENTS.md to get here, and `codes-drift` reads
+ * `AGENTS_MD + PROTOCOLS` — so the guard stays green by construction, because
+ * the codes moved from one half of that corpus into the other. If it goes red
+ * after a change here, something was deleted rather than moved.
+ */
+export const PROTOCOLS = Object.fromEntries(PRINTABLE.map((c) => [c.name, c.body]));
+/**
+ * What each page's `$1`, `$2`, … denote — see {@link CommandContent.placeholders}.
+ * A reference page declares `[]`, which is not a formality: `placeholderProblems`
+ * keys off this record, and a name absent from it is treated as unknown rather
+ * than as taking no arguments.
+ */
+export const PLACEHOLDERS = Object.fromEntries(PRINTABLE.map((c) => [c.name, c.placeholders]));
+/**
+ * Whether nothing was supplied for this position — the two shapes an absent
+ * argument actually arrives in, in one place because both call sites below owe
+ * the same answer.
+ *
+ * The first is empty; {@link protocolFor} says which dialects send that. The
+ * second is the placeholder ITSELF, arriving as data. One body serves twenty
+ * tool dialects (tools/registry.ts) and keeps Claude's positional `$1`/`$2`
+ * convention in all of them (see {@link CommandContent}), so every generated
+ * stub carries the spelling verbatim: `.gemini/commands/loam/adopt.toml`
+ * contains the literal line `loam instructions loam-adopt $1`. Gemini's own
+ * convention is `{{args}}` and Copilot's is `${input:…}`, and Cline, Kilo Code
+ * and Roo Code substitute nothing whatever — so on those three the `$1` reaches
+ * this command exactly as written, and loam refused the literal first
+ * instruction of its own workflow with `invalid-option`. (Unquoted in a POSIX
+ * shell the same line degrades the other way: `$1` expands to empty, and the
+ * agent receives a protocol addressed to nobody.) The same class already cost
+ * `loam-check` its placeholder — see the comment in workflows/check.ts; this is
+ * the general fix, made once in the RECEIVING command rather than per dialect.
+ *
+ * Scoped to `^\$[1-9]$` and no wider. `{{args}}` and `${input:…}` are
+ * deliberately NOT matched: the tools that spell placeholders that way
+ * substitute them before an agent ever reads the file, so they cannot arrive
+ * here, and loam emits neither. A value that merely CONTAINS a placeholder
+ * (`FEAT-$1`) is a real argument and is still checked as one.
+ */
+const unsupplied = (arg) => arg === undefined || arg === "" || /^\$[1-9]$/.test(arg);
+/**
+ * Why the arguments given to `name` cannot be substituted into its protocol, or
+ * null when they can. One sentence per bad argument, already naming the
+ * placeholder it was meant to fill.
+ *
+ * The grammars are `core/kernel/ids/`'s, never a second copy: a value this accepts
+ * and `loam adopt` refuses would be worse than no check, because the protocol
+ * would still be wrong and now something had approved it. An argument nobody
+ * supplied is not an error — `protocolFor` leaves that placeholder standing on
+ * purpose, so the page reads as "the service id goes here" — and by
+ * {@link unsupplied} that covers the placeholder text arriving as the argument,
+ * which is what an untouched generated stub sends.
+ */
+export function placeholderProblems(name, args) {
+    const kinds = PLACEHOLDERS[name];
+    if (kinds === undefined)
+        return null;
+    const problems = kinds.flatMap((kind, i) => {
+        const arg = args[i];
+        // The `undefined` arm is `unsupplied`'s own; it is repeated here because
+        // that is what narrows `arg` to a string for the id grammars below.
+        if (arg === undefined || unsupplied(arg) || kind === "free")
+            return [];
+        const problem = kind === "service"
+            ? serviceIdProblem(arg, `$${i + 1}`)
+            : featureIdProblem(arg, `feature id ($${i + 1})`);
+        return problem === null ? [] : [problem];
+    });
+    return problems.length === 0 ? null : problems;
+}
+const row = ({ name, description, argumentHint }) => ({ name, description, argumentHint });
+/** The workflow names, in cycle order — `loam instructions` with no argument lists these. */
+export const WORKFLOWS = COMMANDS.map(row);
+/** Support protocols, listed separately so no caller mistakes one for a lifecycle step. */
+export const SUPPORT_PAGES = SUPPORT.map(row);
+/**
+ * The reference-page names, listed by the same bare `loam instructions` and
+ * kept a SEPARATE list rather than appended to {@link WORKFLOWS}.
+ *
+ * A page is not a workflow: it has no steps, it is not part of the cycle, and
+ * running one is not doing anything. A menu that ran the ten together would
+ * read as a ten-step process, which is the one thing the six-step cycle must
+ * not be confused with — so the command prints them under their own heading
+ * (commands/instructions.ts) and test/instructions.test.ts pins that they stay
+ * apart.
+ */
+export const REFERENCE_PAGES = REFERENCES.map(row);
+/**
+ * One workflow's protocol with `$1`, `$2`, … replaced by the arguments given.
+ *
+ * An unsupplied placeholder is LEFT STANDING rather than blanked: the bodies
+ * are written so `$1` reads as "the feature id goes here", and a protocol that
+ * silently dropped it would hand an agent `loam validate --feature --json` — a
+ * command that parses, runs, and answers a different question. Extra arguments
+ * are ignored for the same reason: this substitutes, it does not validate.
+ *
+ * "Unsupplied" is {@link unsupplied}'s two shapes, not merely a missing
+ * element, and neither is pedantry — they are the two things a tool actually
+ * sends. An EMPTY argument is the first: several dialects expand an absent
+ * positional to the empty string, and `loam-feature`'s own invocation quotes
+ * its second one (`--title "$2"`), so `/loam-feature FEAT-101` with no title
+ * arrives here as `["FEAT-101", ""]`. Blanking it produced
+ * `loam new FEAT-101 --title ""` — which is exactly the failure the paragraph
+ * above describes, reached by the one path that paragraph did not cover: the
+ * command succeeds, and writes a feature whose title is the empty string and
+ * whose intent.md opens with a bare `#`.
+ *
+ * The LITERAL PLACEHOLDER is the second: the dialects that substitute nothing
+ * hand this command the `$1` their generated stub was written with, so
+ * `loam instructions loam-adopt $1` renders the same page as
+ * `loam instructions loam-adopt` — the placeholder standing, the protocol
+ * printed. Here the shape mostly falls out anyway (planting `$1` where `$1`
+ * stood is a no-op); it is spelled all the same, because a MISNUMBERED one
+ * would not be — `$3` given for `$1` would renumber the placeholder in the
+ * printed page — and because the check above and this render have to agree on
+ * one definition or a value can pass one and be rewritten by the other.
+ */
+export function protocolFor(name, args = []) {
+    const body = PROTOCOLS[name];
+    if (body === undefined)
+        return null;
+    return body.replace(/\$([1-9])/g, (whole, digit) => {
+        const arg = args[Number(digit) - 1];
+        return arg === undefined || unsupplied(arg) ? whole : arg;
+    });
+}
+//# sourceMappingURL=protocol.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"protocol.js","sourceRoot":"","sources":["../../../src/core/agent/protocol.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * The protocol surface: six lifecycle workflows, the support protocol and the\n * reference pages — what `loam instructions` prints (commands/instructions.ts)\n * and the corpus every check over loam's agent-facing prose reads\n * (test/codes-drift.test.ts, test/agent-contract.test.ts,\n * test/agent-commands-runnable.test.ts).\n */\nimport { featureIdProblem } from \"../kernel/ids/feature.js\";\nimport { serviceIdProblem } from \"../kernel/ids/service.js\";\nimport type { CommandContent, PlaceholderKind } from \"./contract.js\";\nimport { LOAM_ADOPT } from \"./workflows/adopt.js\";\nimport { LOAM_CHECK } from \"./workflows/check.js\";\nimport { LOAM_VERIFY, LOAM_SHIP } from \"./workflows/closing.js\";\nimport { LOAM_FEATURE } from \"./workflows/feature.js\";\nimport { LOAM_IMPLEMENT } from \"./workflows/implement.js\";\nimport { REFERENCES } from \"./workflows/reference/reference.js\";\nimport { LOAM_REPORT } from \"./support/report.js\";\n\n/**\n * The six protocols, in cycle order. One assembly, exported: scaffold.ts\n * derives the generated files through this same list, so what\n * `loam instructions` prints and what a fresh scaffold writes cannot drift\n * apart.\n */\nexport const COMMANDS: CommandContent[] = [\n  LOAM_ADOPT,\n  LOAM_FEATURE,\n  LOAM_IMPLEMENT,\n  LOAM_CHECK,\n  LOAM_VERIFY,\n  LOAM_SHIP,\n];\n\n/**\n * Support entry points generated beside the lifecycle, but not counted as\n * lifecycle steps. Reporting a bad run must be discoverable in every profile;\n * placing it in COMMANDS would make a consumer iterating that list try to run\n * incident collection after every feature.\n */\nexport const SUPPORT: CommandContent[] = [LOAM_REPORT];\n\n/** Every command/skill file init generates, regardless of category. */\nexport const AGENT_COMMANDS: CommandContent[] = [...COMMANDS, ...SUPPORT];\n\n/**\n * Everything `loam instructions <name>` can print: the six workflows, support\n * protocol and five reference pages, in that order.\n *\n * The pages join the generated protocols HERE and nowhere else — not in\n * {@link AGENT_COMMANDS}, which is what scaffold.ts derives `SLASH_COMMANDS`\n * and `plannedCommandFiles` from. That is the whole mechanism, and the\n * asymmetry is the point: a page is printable by name but `loam init` writes no\n * file for it, so moving 44 KB out of AGENTS.md did not put 44 KB back as four\n * new artifacts in every repository loam touches. The support protocol does\n * belong in AGENT_COMMANDS because discovery is its purpose, while its separate\n * menu category keeps it out of the lifecycle. test/agents.test.ts asserts the\n * reference-page halves separately, because a future edit can break either\n * alone.\n */\nconst PRINTABLE: CommandContent[] = [...AGENT_COMMANDS, ...REFERENCES];\n\n/**\n * The printable bodies, keyed by name — what `loam instructions <name>` prints,\n * and the corpus every check over loam's agent-facing prose reads.\n *\n * Separate from SLASH_COMMANDS since the file became a pointer: the protocol is\n * still the thing that must document every stable code (`codes-drift`) and\n * every `loam …` line it teaches must still parse against the real CLI\n * (`agent-commands-runnable`). Those two properties are about the INSTRUCTIONS,\n * and they did not move just because the delivery did.\n *\n * The reference pages belong in this record for exactly that reason. Every code\n * they carry LEFT AGENTS.md to get here, and `codes-drift` reads\n * `AGENTS_MD + PROTOCOLS` — so the guard stays green by construction, because\n * the codes moved from one half of that corpus into the other. If it goes red\n * after a change here, something was deleted rather than moved.\n */\nexport const PROTOCOLS: Record<string, string> = Object.fromEntries(\n  PRINTABLE.map((c) => [c.name, c.body]),\n);\n\n/**\n * What each page's `$1`, `$2`, … denote — see {@link CommandContent.placeholders}.\n * A reference page declares `[]`, which is not a formality: `placeholderProblems`\n * keys off this record, and a name absent from it is treated as unknown rather\n * than as taking no arguments.\n */\nexport const PLACEHOLDERS: Record<string, readonly PlaceholderKind[]> = Object.fromEntries(\n  PRINTABLE.map((c) => [c.name, c.placeholders]),\n);\n\n/**\n * Whether nothing was supplied for this position — the two shapes an absent\n * argument actually arrives in, in one place because both call sites below owe\n * the same answer.\n *\n * The first is empty; {@link protocolFor} says which dialects send that. The\n * second is the placeholder ITSELF, arriving as data. One body serves twenty\n * tool dialects (tools/registry.ts) and keeps Claude's positional `$1`/`$2`\n * convention in all of them (see {@link CommandContent}), so every generated\n * stub carries the spelling verbatim: `.gemini/commands/loam/adopt.toml`\n * contains the literal line `loam instructions loam-adopt $1`. Gemini's own\n * convention is `{{args}}` and Copilot's is `${input:…}`, and Cline, Kilo Code\n * and Roo Code substitute nothing whatever — so on those three the `$1` reaches\n * this command exactly as written, and loam refused the literal first\n * instruction of its own workflow with `invalid-option`. (Unquoted in a POSIX\n * shell the same line degrades the other way: `$1` expands to empty, and the\n * agent receives a protocol addressed to nobody.) The same class already cost\n * `loam-check` its placeholder — see the comment in workflows/check.ts; this is\n * the general fix, made once in the RECEIVING command rather than per dialect.\n *\n * Scoped to `^\\$[1-9]$` and no wider. `{{args}}` and `${input:…}` are\n * deliberately NOT matched: the tools that spell placeholders that way\n * substitute them before an agent ever reads the file, so they cannot arrive\n * here, and loam emits neither. A value that merely CONTAINS a placeholder\n * (`FEAT-$1`) is a real argument and is still checked as one.\n */\nconst unsupplied = (arg: string | undefined): boolean =>\n  arg === undefined || arg === \"\" || /^\\$[1-9]$/.test(arg);\n\n/**\n * Why the arguments given to `name` cannot be substituted into its protocol, or\n * null when they can. One sentence per bad argument, already naming the\n * placeholder it was meant to fill.\n *\n * The grammars are `core/kernel/ids/`'s, never a second copy: a value this accepts\n * and `loam adopt` refuses would be worse than no check, because the protocol\n * would still be wrong and now something had approved it. An argument nobody\n * supplied is not an error — `protocolFor` leaves that placeholder standing on\n * purpose, so the page reads as \"the service id goes here\" — and by\n * {@link unsupplied} that covers the placeholder text arriving as the argument,\n * which is what an untouched generated stub sends.\n */\nexport function placeholderProblems(name: string, args: readonly string[]): string[] | null {\n  const kinds = PLACEHOLDERS[name];\n  if (kinds === undefined) return null;\n  const problems = kinds.flatMap((kind, i) => {\n    const arg = args[i];\n    // The `undefined` arm is `unsupplied`'s own; it is repeated here because\n    // that is what narrows `arg` to a string for the id grammars below.\n    if (arg === undefined || unsupplied(arg) || kind === \"free\") return [];\n    const problem = kind === \"service\"\n      ? serviceIdProblem(arg, `$${i + 1}`)\n      : featureIdProblem(arg, `feature id ($${i + 1})`);\n    return problem === null ? [] : [problem];\n  });\n  return problems.length === 0 ? null : problems;\n}\n\n/** One row of the `loam instructions` menu: enough to choose, and nothing more. */\ntype MenuRow = Pick<CommandContent, \"name\" | \"description\" | \"argumentHint\">;\n\nconst row = ({ name, description, argumentHint }: CommandContent): MenuRow =>\n  ({ name, description, argumentHint });\n\n/** The workflow names, in cycle order — `loam instructions` with no argument lists these. */\nexport const WORKFLOWS: readonly MenuRow[] = COMMANDS.map(row);\n\n/** Support protocols, listed separately so no caller mistakes one for a lifecycle step. */\nexport const SUPPORT_PAGES: readonly MenuRow[] = SUPPORT.map(row);\n\n/**\n * The reference-page names, listed by the same bare `loam instructions` and\n * kept a SEPARATE list rather than appended to {@link WORKFLOWS}.\n *\n * A page is not a workflow: it has no steps, it is not part of the cycle, and\n * running one is not doing anything. A menu that ran the ten together would\n * read as a ten-step process, which is the one thing the six-step cycle must\n * not be confused with — so the command prints them under their own heading\n * (commands/instructions.ts) and test/instructions.test.ts pins that they stay\n * apart.\n */\nexport const REFERENCE_PAGES: readonly MenuRow[] = REFERENCES.map(row);\n\n/**\n * One workflow's protocol with `$1`, `$2`, … replaced by the arguments given.\n *\n * An unsupplied placeholder is LEFT STANDING rather than blanked: the bodies\n * are written so `$1` reads as \"the feature id goes here\", and a protocol that\n * silently dropped it would hand an agent `loam validate --feature --json` — a\n * command that parses, runs, and answers a different question. Extra arguments\n * are ignored for the same reason: this substitutes, it does not validate.\n *\n * \"Unsupplied\" is {@link unsupplied}'s two shapes, not merely a missing\n * element, and neither is pedantry — they are the two things a tool actually\n * sends. An EMPTY argument is the first: several dialects expand an absent\n * positional to the empty string, and `loam-feature`'s own invocation quotes\n * its second one (`--title \"$2\"`), so `/loam-feature FEAT-101` with no title\n * arrives here as `[\"FEAT-101\", \"\"]`. Blanking it produced\n * `loam new FEAT-101 --title \"\"` — which is exactly the failure the paragraph\n * above describes, reached by the one path that paragraph did not cover: the\n * command succeeds, and writes a feature whose title is the empty string and\n * whose intent.md opens with a bare `#`.\n *\n * The LITERAL PLACEHOLDER is the second: the dialects that substitute nothing\n * hand this command the `$1` their generated stub was written with, so\n * `loam instructions loam-adopt $1` renders the same page as\n * `loam instructions loam-adopt` — the placeholder standing, the protocol\n * printed. Here the shape mostly falls out anyway (planting `$1` where `$1`\n * stood is a no-op); it is spelled all the same, because a MISNUMBERED one\n * would not be — `$3` given for `$1` would renumber the placeholder in the\n * printed page — and because the check above and this render have to agree on\n * one definition or a value can pass one and be rewritten by the other.\n */\nexport function protocolFor(name: string, args: readonly string[] = []): string | null {\n  const body = PROTOCOLS[name];\n  if (body === undefined) return null;\n  return body.replace(/\\$([1-9])/g, (whole, digit: string) => {\n    const arg = args[Number(digit) - 1];\n    return arg === undefined || unsupplied(arg) ? whole : arg;\n  });\n}\n"]}

package/dist/core/agent/scaffold.js

@@ -0,0 +1,254 @@
+/**
+ * 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 — once its body, stamp aside, is no
+ * longer the one this binary writes — 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
+ * the largest page loam has — 109 KB measured 2026-10-10 (84 KB when this was
+ * first written), about a quarter of a 100k-token window, and hundreds of
+ * 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 on its own. 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;
+}
+/**
+ * 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 — once its body, stamp aside, is no\n * longer the one this binary writes — 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 * the largest page loam has — 109 KB measured 2026-10-10 (84 KB when this was\n * first written), about a quarter of a 100k-token window, and hundreds of\n * fix-table rows of which a run needs two or three — and every file written\n * from this stub opens by telling the agent to run it. `--no-fix-tables`\n * (commands/instructions.ts) drops the rows, and `loam explain <code>` answers\n * the one row the run turned out to need on its own. The flag is what makes\n * the lazy path payable; 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 * 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"]}