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

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

@@ -0,0 +1 @@
+{"version":3,"file":"agents-md.js","sourceRoot":"","sources":["../../../src/core/agent/agents-md.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AACpD,OAAO,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAC;AAEtD,MAAM,WAAW,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA6JnB,CAAC;AAEF,MAAM,CAAC,MAAM,SAAS,GAAG,GAAG,eAAe,CAAC,YAAY,CAAC,KAAK,WAAW,EAAE,CAAC","sourcesContent":["/**\n * The small, always-loaded orientation contract for a loam docs repository.\n *\n * Detailed grammars and workflows live behind `loam instructions`: those pages\n * describe the binary that is about to run, while this file is written once and\n * may be loaded into every agent turn for years. Keep only enough here to form\n * the next question, find the relevant page, and avoid an unsafe write.\n */\nimport { agentsStampLine } from \"./agents-stamp.js\";\nimport { LOAM_VERSION } from \"../envelope/version.js\";\n\nconst ORIENTATION = `# Working in this docs repo\n\nThis is a **loam** docs repo: plain files are the shared source of truth for a governed software\nfleet's architecture, requirements, contracts and verification evidence. A service may be a modular monolith, a network service, a CLI or a worker.\nloam has no server or database. Delete it and the documents still make sense.\n\n## What is where\n\n\\`architecture/landscape.likec4\\` is the fleet map, and\n\\`architecture/adrs/\\` optional system-level decisions — only their links are graded.\n\\`services/<id>/\\` holds a boundary's living \\`model.likec4\\`, \\`spec.md\\`,\n\\`arch.spec.md\\`, OpenAPI, AsyncAPI, runbook and health facts.\n\\`features/<FEAT>/\\` holds a change in flight: \\`intent.md\\`, \\`delta.likec4\\`,\nper-service requirement and contract deltas, and \\`verification.yaml\\`.\n\\`features/archive/\\` is shipped history.\n\nLiving documents are the complete current state. A feature document is a diff\nagainst them, reviewed as a diff; \\`loam archive\\` folds it into living state.\nDo not hand-edit the living landscape to add a feature change.\n\n## Linking between documents\n\nDocuments join with **standard markdown links** whose targets are real relative\npaths, for example \\`[decision](../adrs/ADR-001.md)\\`. They render in pull-request\nreview instead of showing literal brackets,\nand make “does this link resolve” a filesystem question; \\`[[Wikilinks]]\\` would\nrequire shortest-unique-path guessing.\nObsidian supports markdown links, autocomplete and rename-tracking when its\nwikilink setting is off. \\`link.unresolved\\` grades missing targets and CASE\n**is** graded; links outside this repository, \\`#section\\` targets, a fenced code\nblock or an inline code span are deliberately not graded.\n\n## \\`loam.json\\` — the wiring\n\nEvery repository commits its own \\`loam.json\\`:\n\n\\`{ \"docsDir\": \"../docs\", \"service\": \"payment-service\", \"gherkinDir\": \"features\" }\\`\n\n\\`docsDir\\` is stored exactly as it was passed and resolved against the directory\nholding the \\`loam.json\\`, so a relative path survives a clone; an absolute one\nraises \\`doctor.docs-absolute\\`. \\`service\\` binds a service checkout to the one boundary\nit may write evidence for. \\`gherkinDir\\` is optional. \\`agentTools\\` and\n\\`agentProfile\\` record which agent surfaces and workflow subset init manages;\n\\`agentFiles\\` records digests so unchanged generated pointers can refresh while\ncustomized ones remain untouched. With no config, loam refuses with \\`no-config\\`\nrather than guessing.\n\n\\`loam init --docs <dir>\\` **joins** an existing docs repo. Add \\`--create\\` only\nwhen creating a new one; a typo must not scaffold a second source of truth.\n\n## Starting from chat\n\nThere are two equivalent entry points into the same version-matched protocol.\nPrefer the explicit one when a user wants a predictable lifecycle: invoke\n\\`/loam-feature <FEAT> \"<title>\"\\` to propose, \\`/loam-implement <FEAT> [service]\\`\nto build, \\`/loam-check\\` and \\`/loam-verify <FEAT>\\` to grade it, and\n\\`/loam-ship <FEAT>\\` to finish. Most hosts use that flat slash\nspelling; Gemini uses \\`/loam:feature\\`, Amazon Q uses \\`@loam-feature\\`, and a\nskills-only host can invoke \\`$loam-feature\\`. Natural-language requests may load\nthe matching Agent Skill instead. Once either entry point is selected, the agent\ndrives the internal status/edit/validate loop and asks the user only for a real\ndecision or human-only act; the user does not have to type every loam command.\n\nIf loam or an agent integration behaves unexpectedly, invoke \\`/loam-report\\` (or\nload \\`$loam-report\\` on a skills-only host). It collects a sanitized, reproducible\nMarkdown report under \\`loam-reports/\\` without repairing the repository, retrying a\nwriter or uploading anything. This is support, not a seventh lifecycle step.\n\n## The cycle\n\n0. **Wire the repo** — in each service checkout run\n   \\`loam init --docs <path-to-docs-repo> --service <id>\\`, then \\`loam doctor\\`.\n1. **Adopt** — for an undocumented boundary load \\`loam instructions loam-adopt\n   <id>\\`, then use \\`loam adopt --service <id> --json\\`. Write drafts; a person,\n   never an agent, later vouches for them.\n2. **Understand** — start or resume with \\`loam status --json\\`; its ordered\n   \\`next[]\\` is the work queue. Read \\`next[0].execution\\`: run it only when\n   \\`runnable\\` is true; otherwise use \\`kind\\`, \\`cwd\\`, \\`needs\\` and \\`after\\`\n   to complete the edit or external-repo step. Use \\`loam list --json\\`, \\`loam show <id> --json\\`\n   and \\`loam explore <id> --json\\` before proposing a change. Never propose a\n   change to a service you have not read.\n3. **Scaffold** — load \\`loam instructions loam-feature <FEAT>\\`, then run\n   \\`loam new <FEAT> --title \"...\" --touches <service>\\`.\n4. **Author** — fill the scaffolded TODOs and run \\`loam rebase <FEAT>\\` after\n   reading the living baselines. The exact joins and authoring grammars are in\n   the reference pages below.\n5. **Check** — load \\`loam instructions loam-check --no-fix-tables\\`, run\n   \\`loam validate <FEAT> --json\\`, and use \\`loam explain <code>\\` for reported\n   codes. \\`loam dependencies --json\\` names features that must archive first.\n6. **Build** — load \\`loam instructions loam-implement <FEAT>\\`.\n   \\`loam delta <FEAT> --service <id> --json\\` is one service's task; in that\n   service checkout, \\`loam gherkin <FEAT>\\` emits its executable scenarios.\n7. **Verify** — \\`loam verify <FEAT> --json\\` is the checklist. Record evidence\n   from each affected service's own checkout. Read\n   \\`loam instructions loam-done-check\\` before recording anything.\n8. **Ship** — load \\`loam instructions loam-ship <FEAT>\\`; begin with\n   \\`loam archive <FEAT> --dry-run --json\\`, then archive only after the code is\n   merged and the plan is the one reviewed.\n\n## Reading loam's output\n\nEvery command takes \\`--json\\`. The envelope has \\`contractVersion\\`, \\`ok\\` and,\non refusal, \\`error.code\\`. Unknown flags are \\`invalid-option\\`; \\`--help\\` and\n\\`--version\\` pass through. Branch on stable codes, never message prose.\n\nValidation \\`findings[]\\` carry \\`severity\\`; archive-related findings also carry\n\\`gates\\`. Severity and gating are two different questions: errors invalidate,\nwhile \\`gates: true\\` makes archive refuse — archive is gated on coherence, so a\ngating finding stops it whatever its severity. Advisory warnings never block.\n\\`--approve\\` overrides the gating issues — only those that are judgement calls —\nand never a mechanical loss. For example \\`delta.requirement-not-merged\\` warns but gates;\n\\`living.requirement-outside-requirements\\` cannot be approved, while\n\\`openapi.op-modified\\` is reviewable.\n\n\\`loam status --json\\` orders executable next actions. Findings include structured\n\\`locations[]\\`; use their paths instead of extracting filenames from prose.\n\\`loam show <FEAT> --json\\` includes a \\`review\\` pack with intent, architecture,\ncontracts, dependencies, verification, blockers and the same next actions.\n\\`loam explain <code> --json\\`\nreturns one code's meaning and fix; \\`loam explain --codes --json\\` lists them.\nWhich codes an INVOCATION can raise is in \\`loam instructions loam-codes\\`.\n\n## The identity rule\n\nA service is the element whose \\`metadata { service '<id>' }\\` matches its\n\\`services/<id>/\\` directory. An exact element id is the legacy fallback. Never\ninfer identity from display names or containment. Relationships join to contracts\nthrough exact ids: OpenAPI \\`operationId\\`, requirement \\`Operations:\\`, and C4\n\\`metadata { op '...' }\\`. Consult \\`loam instructions loam-spine\\` before editing\na join.\n\n## Reference pages — fetch when needed\n\n- \\`loam instructions loam-codes\\` — finding/refusal inventory and fixes.\n- \\`loam instructions loam-spine\\` — operation, message, coverage, permission,\n  capability and baseline joins.\n- \\`loam instructions loam-authoring\\` — arch requirements, generated Gherkin\n  and frontmatter/vouch grammar.\n- \\`loam instructions loam-done-check\\` — verification evidence and verdicts.\n\nBare \\`loam instructions\\` lists the six workflows, the separate \\`loam-report\\`\nsupport protocol and these references. Generated agent command/skill files are\nsmall pointers to them, so the runtime page wins if an old pointer disagrees with\nthe installed binary. MCP clients can read the same pages as\n\\`loam://orientation\\` and \\`loam://instructions/<name>\\` resources.\n\n## Safety and hand-back\n\nloam's writers are journaled, but the lifecycle still matters. Do not run\n\\`loam vouch\\` for a human, do not invent evidence, do not archive before code is\nmerged, and do not edit generated files under \\`<gherkinDir>/loam/\\` by hand.\n\\`loam unarchive <FEAT>\\` is the supported undo. To abandon a feature that was\nnever archived, review it and use \\`git rm -r features/<FEAT>\\`; loam deliberately\nhas no destructive drop command.\n\nFinish by reporting remaining warnings, unverifiable claims, files or directories\nyou did not inspect, and the exact human action still owed.\n`;\n\nexport const AGENTS_MD = `${agentsStampLine(LOAM_VERSION)}\\n${ORIENTATION}`;\n"]}

package/dist/core/{agents-stamp.js → agent/agents-stamp.js}

@@ -72,6 +72,56 @@ export function versionTrails(stamp, binary) {
     }
     return comparePre(s.pre, b.pre) < 0;
 }
+/**
+ * Does `stamp` name a version NEWER than the binary reading it? The mirror of
+ * {@link versionTrails}, and a different subject rather than its negation:
+ * equal versions are neither.
+ */
+export function versionAhead(stamp, binary) {
+    return versionTrails(binary, stamp);
+}
+/**
+ * `docs.binary-behind` — this loam is OLDER than the loam that wrote the docs
+ * repo it is reading.
+ *
+ * The false-green this closes is the sharpest one in the product, because it
+ * inverts the meaning of a passing run rather than merely missing a defect.
+ * loam's whole promise is that a token spelled here must be spelled there — so
+ * every check is an existence constraint over a value the parser recognised.
+ * A binary that predates a grammar addition does not FAIL on the newer
+ * directive; it does not see it, produces no value, has nothing to join, and
+ * reports green. The corpus is checked less than it looks, and nothing anywhere
+ * says so. `agents.stale` is the opposite direction and explicitly declines
+ * this case ("that is an old binary, not a stale file") — correctly, because
+ * the fix is different: upgrade loam, do not edit the file.
+ *
+ * A WARNING, not an error, and the reasoning is the `sources.stale` doctrine.
+ * A mixed-version fleet is ordinary — one engineer's global install trails a
+ * release by a week — and failing every command in that repo would be a
+ * refusal aimed at the wrong person on the wrong day. What the message must do
+ * instead is say plainly that a green run from this binary is worth less than
+ * it appears, which no other finding says. A fleet that wants it to gate has
+ * `--strict`, which is exactly the lever that doctrine reserves for this.
+ *
+ * Silent when there is no file, no stamp, or the stamp is equal or older —
+ * every one of those is somebody else's finding.
+ */
+export function binaryBehindFinding(text, binary) {
+    if (text === null)
+        return null;
+    const stamp = agentsStampVersion(text);
+    if (stamp === null || !versionAhead(stamp, binary))
+        return null;
+    return {
+        severity: "warn",
+        code: "docs.binary-behind",
+        message: `This docs repo was written by loam v${stamp}; this binary is v${binary}. A newer loam may check ` +
+            "joins this one cannot parse — an unrecognised directive is read as prose, so it produces no " +
+            "join to fail and this run reports green without having graded it. Treat a pass from this " +
+            `binary as incomplete rather than clean, and upgrade to v${stamp} or later (\`npm i -g @ybotok/loam\`). ` +
+            "Nothing here is wrong with the documents; the reader is behind them.",
+    };
+}
 /**
  * The one finding `loam validate --all` owes the agent contract. `text` is the
  * docs repo's AGENTS.md, or null when there is none — no file means no contract

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 * 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 four 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 four 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,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