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

package/dist/core/gherkin/emit.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"emit.js","sourceRoot":"","sources":["../../../src/core/gherkin/emit.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * A requirement set as a `.feature` file: what gets written where, and what the\n * text says.\n *\n * The plan is separate from the render because the two answer to different\n * owners — where a suite lands is the service repository's layout question\n * (`./stamp.ts` owns the root), while what a scenario reads like is the\n * requirement's. Every emitted scenario carries the digest tag the claim\n * checklist matches on, which is why nothing here may reword a scenario body.\n */\nimport { type Requirement } from \"../document/spec.js\";\nimport { scenarioGherkin } from \"../vocabulary/steps.js\";\nimport { type SpecAxis } from \"../repo/paths.js\";\nimport { type ScenarioAxis } from \"./digest.js\";\nimport { gherkinStampLine, scenarioDigest, scenarioDigestTag } from \"./stamp.js\";\n\n/** The axis label the machine contract speaks. */\nexport function axisLabel(axis: SpecAxis): \"business\" | \"arch\" {\n  return axis.key === \"archSpec\" ? \"arch\" : \"business\";\n}\n\n/**\n * A requirement name as a file name: lowercase, every non-letter/digit run one\n * hyphen, edges trimmed.\n *\n * The keep-set is `\\p{L}\\p{N}`, not `[a-z0-9]`, because an ASCII-only slug is\n * not a slug of a non-Latin fleet — it is the empty string. Every requirement\n * written in Chinese, Japanese, Korean, Greek, Cyrillic or Hebrew slugged to\n * nothing, fell back to `requirement`, and the whole service's suite came out\n * as `requirement.feature`, `requirement-2.feature`, … : file names that name\n * nothing, in the one place the mapping is supposed to be legible. So letters\n * of every script survive as themselves.\n *\n * Accents are folded rather than kept, and that is the reason for NFKD first:\n * decomposing splits `é` into `e` + a combining acute, and dropping the\n * combining marks (`\\p{M}`) leaves `e`. Without the fold `émojis` and `emojis`\n * would be two files that look identical in a directory listing — and on a\n * filesystem that normalises names (APFS, and HFS+ before it) they would be one\n * file, silently, with the second emission overwriting the first.\n *\n * A name this still leaves empty (all punctuation or emoji) falls back to\n * \"requirement\" and lets the collision counter number it. Runs collapse to a\n * SINGLE hyphen, which is what keeps the `arch--` prefix an axis marker no\n * business slug can spell.\n */\nexport function slugOf(name: string): string {\n  const s = name\n    .normalize(\"NFKD\")\n    .replace(/\\p{M}+/gu, \"\")\n    .toLowerCase()\n    .replace(/[^\\p{L}\\p{N}]+/gu, \"-\")\n    .replace(/^-+|-+$/g, \"\");\n  return s.length > 0 ? s : \"requirement\";\n}\n\nexport interface PlannedFeature {\n  /** File name under `<gherkinDir>/loam/` — flat, never a subdirectory. */\n  fileName: string;\n  axis: SpecAxis;\n  requirement: Requirement;\n  /** One digest per scenario, in scenario order — what the stamps say. */\n  digests: string[];\n  /**\n   * Names of scenarios that yielded ZERO steps — numbered-step or prose-only\n   * legacy bodies. Their `Scenario:` blocks are description-only: cucumber\n   * runs them vacuously green, while `--results` (which requires at least one\n   * passed step) can never confirm them — so the emission must say so out\n   * loud, and the fix is rewording the spec bullets, never editing the file.\n   */\n  stepless: string[];\n  /**\n   * Names of scenarios whose markdown table could not be read as `Examples` —\n   * see `ScenarioGherkin.malformedExamples`. The table stays in the description\n   * and the file is valid Gherkin, so nothing downstream can notice: the\n   * emission is the only place this is visible at all.\n   */\n  malformedExamples: string[];\n  /**\n   * Names of scenarios that wrote a fenced block or an indented table where it\n   * could not become a step argument — see `ScenarioGherkin.strandedBlocks`.\n   * The text survives as description, so the file is valid Gherkin and the\n   * document still reads correctly; what is gone is the ARGUMENT, and a step\n   * definition that expected a payload or a table receives nothing.\n   */\n  strandedBlocks: string[];\n  content: string;\n}\n\n/**\n * The emission plan for one scope: one `.feature` per requirement.\n *\n * File naming is the mapping's contract, so it is spelled here once:\n * `<slug>.feature` for the business axis, `arch--<slug>.feature` for the\n * architecture axis — flat and diffable, and collision-proof across axes\n * because slugs collapse punctuation runs to a single hyphen, so no business\n * slug can ever begin `arch--`. Two requirements slugging identically are\n * disambiguated in document order: the first keeps the bare slug, later ones\n * take `-2`, `-3`, … (counting up past any name that already owns the suffix).\n *\n * Tags ride the `Feature:` line and are inherited by every scenario in the\n * file: `@<FEAT>` in feature mode (living emissions carry no feature tag),\n * `@architecture` on the arch axis.\n *\n * `opts.service` is the suite's owner and salts every digest stamp — the same\n * service `loam verify` files the matching claims under. Required, not\n * defaulted: an emission that guessed it would stamp tags no claim matches.\n */\nexport function planEmission(\n  byAxis: Array<{ axis: SpecAxis; reqs: Requirement[] }>,\n  opts: { service: string; featureTag?: string; version: string },\n): PlannedFeature[] {\n  const used = new Set<string>();\n  const out: PlannedFeature[] = [];\n  for (const { axis, reqs } of byAxis) {\n    for (const r of reqs) {\n      const base = (axis.key === \"archSpec\" ? \"arch--\" : \"\") + slugOf(r.name);\n      let fileName = `${base}.feature`;\n      for (let n = 2; used.has(fileName); n += 1) fileName = `${base}-${n}.feature`;\n      used.add(fileName);\n      const tags = [\n        ...(opts.featureTag === undefined ? [] : [`@${opts.featureTag}`]),\n        ...(axis.key === \"archSpec\" ? [\"@architecture\"] : []),\n      ];\n      const { content, digests, stepless, malformedExamples, strandedBlocks } = renderFeature(\n        r,\n        { tags, version: opts.version },\n        opts.service,\n        axisLabel(axis),\n      );\n      out.push({ fileName, axis, requirement: r, digests, stepless, malformedExamples, strandedBlocks, content });\n    }\n  }\n  return out;\n}\n\n/**\n * One requirement as one `.feature` file: `Feature:` is the requirement name,\n * its body text (Operations:/Covers: lines included — they are part of what\n * the requirement says) becomes the feature description, and each scenario\n * renders under its `@loam-digest-…` tag — the tag line sits directly above\n * the `Scenario:` keyword, where Gherkin puts scenario-level tags, so the\n * runner attaches it to the scenario and carries it into the JSON report.\n * Deterministic to the byte.\n *\n * `service` is the owner of the suite being written, and it salts every digest\n * — the same service `loam verify` files the matching claims under. The two\n * have to be the same string or the stamps this writes match no claim at all.\n */\n/** What the emitted file is stamped with, beside the requirement it renders. */\nexport interface Stamp {\n  tags: string[];\n  version: string;\n}\n\nexport function renderFeature(\n  r: Requirement,\n  stamp: Stamp,\n  service: string,\n  axis: ScenarioAxis = \"business\",\n): { content: string; digests: string[]; stepless: string[]; malformedExamples: string[]; strandedBlocks: string[] } {\n  const { tags, version } = stamp;\n  const lines: string[] = [gherkinStampLine(version)];\n  if (tags.length > 0) lines.push(tags.join(\" \"));\n  lines.push(`Feature: ${r.name}`);\n  const text = r.text.join(\"\\n\").trim();\n  if (text.length > 0) {\n    lines.push(\"\");\n    for (const l of text.split(\"\\n\")) lines.push(l.length > 0 ? `  ${l}` : \"\");\n  }\n  const digests: string[] = [];\n  const stepless: string[] = [];\n  const malformedExamples: string[] = [];\n  const strandedBlocks: string[] = [];\n  for (const s of r.scenarios) {\n    // The digest hashes the WHOLE body, table rows included, so a changed cell\n    // is a changed scenario: `gherkin.stale` fires on an edited case exactly as\n    // it does on an edited step, and the claim it answers moves with it. It is\n    // also why a change to THIS renderer moves no digest: the hash is over the\n    // markdown source, so a suite generated before a grammar change keeps its\n    // stamps and grades `gherkin.current` until somebody regenerates it.\n    const digest = scenarioDigest(service, s.lines, axis);\n    digests.push(digest);\n    const { description, steps, examples, malformedExamples: broken, strandedBlocks: stranded } = scenarioGherkin(s.lines);\n    if (steps.length === 0) stepless.push(s.name);\n    if (broken) malformedExamples.push(s.name);\n    if (stranded) strandedBlocks.push(s.name);\n    // The keyword is the whole difference between one case and twenty: cucumber\n    // expands an outline into one report element per row, each carrying this\n    // scenario's tag, and `runnerAnswers` confirms the claim only when every\n    // one of them passed.\n    lines.push(\"\", `  ${scenarioDigestTag(digest)}`, `  ${examples === null ? \"Scenario\" : \"Scenario Outline\"}: ${s.name}`);\n    for (const d of description) lines.push(`    ${d}`);\n    for (const st of steps) {\n      lines.push(`    ${st.text}`);\n      // Gherkin puts a step's argument UNDER the step, indented past it, and\n      // permits at most one of each kind. Docstring first, so a step carrying\n      // both reads request-then-expectation.\n      if (st.docstring !== undefined) {\n        lines.push(`      \"\"\"${st.docstring.contentType ?? \"\"}`);\n        // A payload containing its own `\"\"\"` would close the block early and\n        // silently move the rest of the request body into the step list.\n        for (const l of st.docstring.lines) lines.push(l.length === 0 ? \"\" : `      ${l.replace(/\"\"\"/g, '\\\\\"\\\\\"\\\\\"')}`);\n        lines.push('      \"\"\"');\n      }\n      if (st.table !== undefined) for (const row of st.table) lines.push(`      ${tableRow(row, st.table)}`);\n    }\n    if (examples !== null) {\n      lines.push(\"\", \"    Examples:\");\n      for (const row of [examples.header, ...examples.rows]) lines.push(`      ${tableRow(row, [examples.header, ...examples.rows])}`);\n    }\n  }\n  return { content: lines.join(\"\\n\") + \"\\n\", digests, stepless, malformedExamples, strandedBlocks };\n}\n\n/**\n * One table row — an `Examples` case or a step's data table — with columns\n * padded to the widest cell in that table.\n *\n * Padding is cosmetic to cucumber and deliberate here: these files are read in\n * review as often as they are run, and an unaligned twenty-row matrix is where\n * a wrong cell hides. Deterministic to the byte, like everything else the\n * emitter writes — the widths come from the table alone.\n *\n * ESCAPING IS NOT COSMETIC. Gherkin's table grammar ends a cell at `|`, so a\n * cell containing one silently becomes two cells and every row after it\n * disagrees with the header; `\\` and a literal newline are the same class. The\n * escapes go on before the padding is measured, because the emitted width is\n * the escaped width — measuring the raw cell produced columns that drifted by\n * one character per escape.\n */\nfunction tableRow(row: string[], all: readonly string[][]): string {\n  const esc = (c: string): string => c.replace(/\\\\/g, \"\\\\\\\\\").replace(/\\|/g, \"\\\\|\").replace(/\\n/g, \"\\\\n\");\n  const widths = row.map((_, i) => Math.max(...all.map((r) => esc(r[i] ?? \"\").length)));\n  return `| ${row.map((c, i) => esc(c).padEnd(widths[i]!)).join(\" | \")} |`;\n}\n"]}

package/dist/core/gherkin/read.js

@@ -0,0 +1,76 @@
+/**
+ * A generated `.feature` file read back — the stamp, the tags, the scenarios.
+ *
+ * The parser is deliberately shallow and forgiving in one direction only: a file
+ * without loam's stamp is not loam's to grade, and returns null rather than a
+ * partially understood suite. Anything that IS stamped is loam's output, so the
+ * digests inside it are trusted to be the ones `./emit.ts` wrote.
+ */
+import { DIGEST_TAG_RE, STAMP_RE } from "./stamp.js";
+/**
+ * Parse a `.feature` file for its loam stamps. Null when line 1 is not the
+ * stamp — an unstamped file is not loam's writing, and no staleness judgment
+ * may be built on it. Tag lines above `Feature:` are the file's tags; a tag
+ * line after it that carries a `@loam-digest-…` token binds that digest to the
+ * immediately following `Scenario:` line (tag lines stack, as Gherkin's do,
+ * without breaking the bond); any other non-blank line between them breaks it.
+ *
+ * DOCSTRING BODIES ARE SKIPPED WHOLE, and that is a correctness requirement
+ * rather than tidiness. Since a step may carry a `"""` payload, a request body
+ * containing a line that reads `Scenario: …` or begins with `@` would otherwise
+ * be read here as a real scenario or a real tag — and every staleness verdict
+ * (`gherkin.stale`, `gherkin.missing`, `gherkin.orphaned`) plus the tag that
+ * decides whether an in-flight feature's file may be replaced rests on this
+ * parse. The payload would be quietly deciding what the suite promises.
+ */
+export function parseStampedFeature(text) {
+    const lines = text.split(/\r?\n/);
+    const m = STAMP_RE.exec(lines[0] ?? "");
+    if (!m)
+        return null;
+    const tags = [];
+    let featureName = null;
+    const scenarios = [];
+    let pending = null;
+    let inDocString = false;
+    for (const line of lines.slice(1)) {
+        // `"""` opens and closes; nothing between the two is structure. The emitter
+        // escapes an inner `"""` as `\"\"\"`, so an unescaped one here is always a
+        // real delimiter.
+        if (/^\s*"""/.test(line)) {
+            inDocString = !inDocString;
+            continue;
+        }
+        if (inDocString)
+            continue;
+        if (/^\s*@/.test(line)) {
+            for (const t of line.trim().split(/\s+/)) {
+                if (featureName === null) {
+                    if (t.startsWith("@"))
+                        tags.push(t.slice(1));
+                    continue;
+                }
+                const d = DIGEST_TAG_RE.exec(t);
+                if (d)
+                    pending = d[1];
+            }
+            continue;
+        }
+        const f = /^\s*Feature:\s*(.*)$/.exec(line);
+        if (f && featureName === null) {
+            featureName = f[1].trim();
+            continue;
+        }
+        const s = /^\s*Scenario(?: Outline)?:\s*(.*)$/.exec(line);
+        if (s) {
+            if (pending !== null)
+                scenarios.push({ name: s[1].trim(), digest: pending });
+            pending = null;
+            continue;
+        }
+        if (pending !== null && line.trim().length > 0)
+            pending = null;
+    }
+    return { version: m[1], tags, featureName, scenarios };
+}
+//# sourceMappingURL=read.js.map

package/dist/core/gherkin/read.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"read.js","sourceRoot":"","sources":["../../../src/core/gherkin/read.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,EAAE,aAAa,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAmBrD;;;;;;;;;;;;;;;GAeG;AACH,MAAM,UAAU,mBAAmB,CAAC,IAAY;IAC9C,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;IAClC,MAAM,CAAC,GAAG,QAAQ,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC;IACxC,IAAI,CAAC,CAAC;QAAE,OAAO,IAAI,CAAC;IACpB,MAAM,IAAI,GAAa,EAAE,CAAC;IAC1B,IAAI,WAAW,GAAkB,IAAI,CAAC;IACtC,MAAM,SAAS,GAAsB,EAAE,CAAC;IACxC,IAAI,OAAO,GAAkB,IAAI,CAAC;IAClC,IAAI,WAAW,GAAG,KAAK,CAAC;IACxB,KAAK,MAAM,IAAI,IAAI,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC;QAClC,4EAA4E;QAC5E,2EAA2E;QAC3E,kBAAkB;QAClB,IAAI,SAAS,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;YACzB,WAAW,GAAG,CAAC,WAAW,CAAC;YAC3B,SAAS;QACX,CAAC;QACD,IAAI,WAAW;YAAE,SAAS;QAC1B,IAAI,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;YACvB,KAAK,MAAM,CAAC,IAAI,IAAI,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,KAAK,CAAC,EAAE,CAAC;gBACzC,IAAI,WAAW,KAAK,IAAI,EAAE,CAAC;oBACzB,IAAI,CAAC,CAAC,UAAU,CAAC,GAAG,CAAC;wBAAE,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;oBAC7C,SAAS;gBACX,CAAC;gBACD,MAAM,CAAC,GAAG,aAAa,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;gBAChC,IAAI,CAAC;oBAAE,OAAO,GAAG,CAAC,CAAC,CAAC,CAAE,CAAC;YACzB,CAAC;YACD,SAAS;QACX,CAAC;QACD,MAAM,CAAC,GAAG,sBAAsB,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QAC5C,IAAI,CAAC,IAAI,WAAW,KAAK,IAAI,EAAE,CAAC;YAC9B,WAAW,GAAG,CAAC,CAAC,CAAC,CAAE,CAAC,IAAI,EAAE,CAAC;YAC3B,SAAS;QACX,CAAC;QACD,MAAM,CAAC,GAAG,oCAAoC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QAC1D,IAAI,CAAC,EAAE,CAAC;YACN,IAAI,OAAO,KAAK,IAAI;gBAAE,SAAS,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,CAAE,CAAC,IAAI,EAAE,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,CAAC;YAC9E,OAAO,GAAG,IAAI,CAAC;YACf,SAAS;QACX,CAAC;QACD,IAAI,OAAO,KAAK,IAAI,IAAI,IAAI,CAAC,IAAI,EAAE,CAAC,MAAM,GAAG,CAAC;YAAE,OAAO,GAAG,IAAI,CAAC;IACjE,CAAC;IACD,OAAO,EAAE,OAAO,EAAE,CAAC,CAAC,CAAC,CAAE,EAAE,IAAI,EAAE,WAAW,EAAE,SAAS,EAAE,CAAC;AAC1D,CAAC","sourcesContent":["/**\n * A generated `.feature` file read back — the stamp, the tags, the scenarios.\n *\n * The parser is deliberately shallow and forgiving in one direction only: a file\n * without loam's stamp is not loam's to grade, and returns null rather than a\n * partially understood suite. Anything that IS stamped is loam's output, so the\n * digests inside it are trusted to be the ones `./emit.ts` wrote.\n */\nimport { DIGEST_TAG_RE, STAMP_RE } from \"./stamp.js\";\n\nexport interface StampedScenario {\n  name: string;\n  digest: string;\n}\n\n/** A generated file as the staleness checks see it. */\nexport interface StampedFeature {\n  /** The version in the stamp line — which loam wrote the file. */\n  version: string;\n  /** Tag tokens (without `@`) from tag lines above `Feature:`. */\n  tags: string[];\n  /** The `Feature:` line's text — the requirement name, by the mapping. */\n  featureName: string | null;\n  /** Scenarios carrying a `@loam-digest-…` tag. A hand-added scenario has none and is invisible here. */\n  scenarios: StampedScenario[];\n}\n\n/**\n * Parse a `.feature` file for its loam stamps. Null when line 1 is not the\n * stamp — an unstamped file is not loam's writing, and no staleness judgment\n * may be built on it. Tag lines above `Feature:` are the file's tags; a tag\n * line after it that carries a `@loam-digest-…` token binds that digest to the\n * immediately following `Scenario:` line (tag lines stack, as Gherkin's do,\n * without breaking the bond); any other non-blank line between them breaks it.\n *\n * DOCSTRING BODIES ARE SKIPPED WHOLE, and that is a correctness requirement\n * rather than tidiness. Since a step may carry a `\"\"\"` payload, a request body\n * containing a line that reads `Scenario: …` or begins with `@` would otherwise\n * be read here as a real scenario or a real tag — and every staleness verdict\n * (`gherkin.stale`, `gherkin.missing`, `gherkin.orphaned`) plus the tag that\n * decides whether an in-flight feature's file may be replaced rests on this\n * parse. The payload would be quietly deciding what the suite promises.\n */\nexport function parseStampedFeature(text: string): StampedFeature | null {\n  const lines = text.split(/\\r?\\n/);\n  const m = STAMP_RE.exec(lines[0] ?? \"\");\n  if (!m) return null;\n  const tags: string[] = [];\n  let featureName: string | null = null;\n  const scenarios: StampedScenario[] = [];\n  let pending: string | null = null;\n  let inDocString = false;\n  for (const line of lines.slice(1)) {\n    // `\"\"\"` opens and closes; nothing between the two is structure. The emitter\n    // escapes an inner `\"\"\"` as `\\\"\\\"\\\"`, so an unescaped one here is always a\n    // real delimiter.\n    if (/^\\s*\"\"\"/.test(line)) {\n      inDocString = !inDocString;\n      continue;\n    }\n    if (inDocString) continue;\n    if (/^\\s*@/.test(line)) {\n      for (const t of line.trim().split(/\\s+/)) {\n        if (featureName === null) {\n          if (t.startsWith(\"@\")) tags.push(t.slice(1));\n          continue;\n        }\n        const d = DIGEST_TAG_RE.exec(t);\n        if (d) pending = d[1]!;\n      }\n      continue;\n    }\n    const f = /^\\s*Feature:\\s*(.*)$/.exec(line);\n    if (f && featureName === null) {\n      featureName = f[1]!.trim();\n      continue;\n    }\n    const s = /^\\s*Scenario(?: Outline)?:\\s*(.*)$/.exec(line);\n    if (s) {\n      if (pending !== null) scenarios.push({ name: s[1]!.trim(), digest: pending });\n      pending = null;\n      continue;\n    }\n    if (pending !== null && line.trim().length > 0) pending = null;\n  }\n  return { version: m[1]!, tags, featureName, scenarios };\n}\n"]}

package/dist/core/gherkin/stale.js

@@ -0,0 +1,210 @@
+/**
+ * What `loam validate` reports about a generated suite: which scenarios moved
+ * out from under it, and which were never generated at all.
+ *
+ * Service-repo-scoped, and silent until a suite exists — a service that never
+ * ran `loam gherkin` has not opted into the axis and is not failing it. The
+ * whole comparison is by digest rather than by name, so a reworded scenario
+ * reads as stale rather than as missing plus new.
+ */
+import { existsSync } from "node:fs";
+import { readdir, readFile } from "node:fs/promises";
+import { join, relative, sep } from "node:path";
+import { SPEC_AXES } from "../repo/paths.js";
+import { locateServicePaths } from "../repo/service-target.js";
+import { listFeatures } from "../repo/repo.js";
+import { entryIs, markDescended } from "../repo/tree/fs.js";
+import { UnsafePathError } from "../kernel/path-safety.js";
+import { gherkinRoot, scenarioDigest } from "./stamp.js";
+import { axisLabel } from "./emit.js";
+import { parseStampedFeature } from "./read.js";
+/**
+ * The gherkin freshness chain, service-repo-scoped like `sources.*`: it needs
+ * the repo (the suite lives there), and it stays quiet until
+ * `<gherkinDir>/loam/` exists — a service that never generated has not opted
+ * in, and silence there is honest, not vacuous.
+ *
+ * The LIVING specs are the reference, with one carve-out. A stamped file
+ * tagged with a feature still in flight answers to that feature's delta, not
+ * to the living spec its requirements have not merged into yet — so it is
+ * skipped here (its regeneration is `loam gherkin <FEAT>`), and the moment the
+ * feature archives, its requirements ARE living requirements, digests
+ * unchanged, and the same file grades current with no rewrite. A tag naming
+ * no active feature (the feature was archived, or abandoned) gets no
+ * exemption: the living spec is all there is to answer to.
+ *
+ * Three warnings, one per way the suite and the spec can disagree, judged
+ * digest-first and by requirement name second:
+ *
+ * - `gherkin.missing` — a living scenario whose digest no stamped scenario of
+ *   its axis carries: the suite has no test for these words.
+ * - `gherkin.stale` — a stamped scenario whose digest matches no living
+ *   scenario while its file's requirement still exists: the spec moved under
+ *   the generated file. (A reworded scenario therefore reports both: the old
+ *   words are stale, the new words are missing — one regeneration clears
+ *   both.)
+ * - `gherkin.orphaned` — a whole file whose requirement no longer exists in
+ *   its axis's living spec; reported once per file, because every scenario in
+ *   it is moot together.
+ *
+ * Digests are content identity within one service and one axis, deliberately:
+ * two identically-worded scenarios of one service's one axis share one digest,
+ * so one stamped copy covers both — while the axes stay separate namespaces
+ * twice over (every comparison here is axis-scoped, and the recipe salts the
+ * arch axis), and the services stay separate because the recipe salts the
+ * service too. That last salt is why a stamped file copied out of another
+ * service's repository grades `gherkin.orphaned`/`gherkin.stale` here instead
+ * of quietly counting as this service's coverage.
+ *
+ * All warnings — `--strict` is the CI escalation — plus one `ok` confirmation
+ * (`gherkin.current`, the `sources.current` pattern) when a generated suite
+ * exists and nothing disagrees.
+ */
+export async function gherkinFindings(ctx) {
+    if (ctx.repoDir === undefined)
+        return [];
+    let root;
+    try {
+        root = gherkinRoot(ctx.repoDir, ctx.gherkinDir);
+    }
+    catch (err) {
+        if (!(err instanceof UnsafePathError))
+            throw err;
+        return [
+            {
+                severity: "error",
+                code: "gherkin.path-outside",
+                subject: ctx.service,
+                message: `The configured Gherkin output is unsafe: ${err.message}. It must stay inside the service repo.`,
+            },
+        ];
+    }
+    if (!existsSync(root))
+        return [];
+    const paths = await locateServicePaths(ctx.docsDir, ctx.service, ctx.fleet);
+    const axes = new Map();
+    for (const axis of SPEC_AXES) {
+        const label = axisLabel(axis);
+        const state = { file: axis.file, reqNames: new Set(), digests: new Set(), scenarios: [] };
+        const path = paths[axis.key];
+        if (existsSync(path)) {
+            for (const r of await ctx.fleet.readRequirements(path)) {
+                if (r.kind === "REMOVED")
+                    continue;
+                state.reqNames.add(r.name);
+                for (const s of r.scenarios) {
+                    const digest = scenarioDigest(ctx.service, s.lines, label);
+                    state.digests.add(digest);
+                    state.scenarios.push({ req: r.name, name: s.name, digest });
+                }
+            }
+        }
+        axes.set(label, state);
+    }
+    // The stamped side. Every stamped digest counts toward coverage — an
+    // in-flight file whose scenario matches the living words IS a test for them.
+    // `Set<string>`, not the ids' own brand: this set answers membership
+    // questions for tags read out of .feature files — document text.
+    const active = new Set((await listFeatures(ctx.docsDir, {}, ctx.fleet)).map((f) => f.id));
+    const stampedDigests = { business: new Set(), arch: new Set() };
+    const parsed = [];
+    let stampedScenarios = 0;
+    for (const abs of await featureFilesUnder(root)) {
+        const file = parseStampedFeature(await readFile(abs, "utf8"));
+        if (file === null)
+            continue;
+        const axis = file.tags.includes("architecture") ? "arch" : "business";
+        for (const s of file.scenarios)
+            stampedDigests[axis].add(s.digest);
+        stampedScenarios += file.scenarios.length;
+        parsed.push({ rel: relative(ctx.repoDir, abs).split(sep).join("/"), axis, file });
+    }
+    const findings = [];
+    const regen = `\`loam gherkin --service ${ctx.service}\``;
+    for (const [axis, state] of axes) {
+        for (const sc of state.scenarios) {
+            if (stampedDigests[axis].has(sc.digest))
+                continue;
+            findings.push({
+                severity: "warn",
+                code: "gherkin.missing",
+                subject: ctx.service,
+                message: `${ctx.service}: scenario '${sc.name}' of requirement '${sc.req}' (${state.file}) has no generated .feature scenario — the suite has no test for these words; ${regen} regenerates it`,
+            });
+        }
+    }
+    for (const { rel, axis, file } of parsed) {
+        if (file.tags.some((t) => active.has(t)))
+            continue;
+        const state = axes.get(axis);
+        if (file.featureName === null || !state.reqNames.has(file.featureName)) {
+            findings.push({
+                severity: "warn",
+                code: "gherkin.orphaned",
+                subject: ctx.service,
+                message: `${ctx.service}: ${rel}: requirement '${file.featureName ?? "(unnamed)"}' no longer exists in the living ${state.file} — the whole file is orphaned; ${regen} removes it`,
+            });
+            continue;
+        }
+        for (const s of file.scenarios) {
+            if (state.digests.has(s.digest))
+                continue;
+            findings.push({
+                severity: "warn",
+                code: "gherkin.stale",
+                subject: ctx.service,
+                message: `${ctx.service}: ${rel}: scenario '${s.name}' matches no scenario in the living ${state.file} — the spec moved under the generated file; ${regen} regenerates it`,
+            });
+        }
+    }
+    if (findings.length === 0) {
+        findings.push({
+            severity: "ok",
+            code: "gherkin.current",
+            message: `${ctx.service}: generated gherkin current (${parsed.length} file(s), ${stampedScenarios} stamped scenario(s) agree with the living specs)`,
+        });
+    }
+    return findings;
+}
+/**
+ * Every `.feature` file at or under `root`, sorted by repo-relative path —
+ * enumeration is part of the output contract, so the order cannot depend on
+ * the filesystem's. Dot-entries are skipped, like every other walk in loam.
+ *
+ * Symlinks are FOLLOWED, through `repo/tree/fs.ts`'s `entryIs` — the rule
+ * every enumeration shares (brief/brief.ts's `hasEntry` too), for the same
+ * reason. A `Dirent` from `readdir(withFileTypes)` never follows one, so
+ * `isFile()` and `isDirectory()` are both false for a
+ * symlinked `.feature`: it was invisible to the orphan scan (`loam gherkin`
+ * left it behind forever) and invisible to the staleness scan (it graded as no
+ * coverage at all). Composing a suite out of links is legitimate, so they are
+ * followed rather than refused, and a dangling one is skipped exactly as an
+ * absent file is.
+ */
+export async function featureFilesUnder(root) {
+    const out = [];
+    // Following links means a cycle is now possible; every directory is entered
+    // once by its resolved path (`markDescended`), so a loop terminates instead
+    // of hanging.
+    const entered = new Set();
+    const walk = async (dir) => {
+        if (!markDescended(dir, entered))
+            return;
+        for (const entry of await readdir(dir, { withFileTypes: true })) {
+            if (entry.name.startsWith("."))
+                continue;
+            const abs = join(dir, entry.name);
+            if (entryIs(dir, entry, "dir"))
+                await walk(abs);
+            else if (entry.name.endsWith(".feature") && entryIs(dir, entry, "file"))
+                out.push(abs);
+        }
+    };
+    await walk(root);
+    return out.sort((a, b) => {
+        const ra = a.split(sep).join("/");
+        const rb = b.split(sep).join("/");
+        return ra < rb ? -1 : ra > rb ? 1 : 0;
+    });
+}
+//# sourceMappingURL=stale.js.map

package/dist/core/gherkin/stale.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"stale.js","sourceRoot":"","sources":["../../../src/core/gherkin/stale.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * What `loam validate` reports about a generated suite: which scenarios moved\n * out from under it, and which were never generated at all.\n *\n * Service-repo-scoped, and silent until a suite exists — a service that never\n * ran `loam gherkin` has not opted into the axis and is not failing it. The\n * whole comparison is by digest rather than by name, so a reworded scenario\n * reads as stale rather than as missing plus new.\n */\nimport { existsSync } from \"node:fs\";\nimport { readdir, readFile } from \"node:fs/promises\";\nimport { join, relative, sep } from \"node:path\";\nimport type { PathableService } from \"../kernel/ids/service.js\";\nimport { SPEC_AXES } from \"../repo/paths.js\";\nimport { locateServicePaths } from \"../repo/service-target.js\";\nimport { listFeatures } from \"../repo/repo.js\";\nimport { entryIs, markDescended } from \"../repo/tree/fs.js\";\nimport type { FleetContext } from \"../fleet-context.js\";\nimport type { Finding } from \"../vocabulary/report.js\";\nimport { UnsafePathError } from \"../kernel/path-safety.js\";\nimport { gherkinRoot, scenarioDigest } from \"./stamp.js\";\nimport { axisLabel } from \"./emit.js\";\nimport { parseStampedFeature, type StampedFeature } from \"./read.js\";\nimport type { DocsDir } from \"../kernel/ids/dirs.js\";\n\n/**\n * The gherkin freshness chain, service-repo-scoped like `sources.*`: it needs\n * the repo (the suite lives there), and it stays quiet until\n * `<gherkinDir>/loam/` exists — a service that never generated has not opted\n * in, and silence there is honest, not vacuous.\n *\n * The LIVING specs are the reference, with one carve-out. A stamped file\n * tagged with a feature still in flight answers to that feature's delta, not\n * to the living spec its requirements have not merged into yet — so it is\n * skipped here (its regeneration is `loam gherkin <FEAT>`), and the moment the\n * feature archives, its requirements ARE living requirements, digests\n * unchanged, and the same file grades current with no rewrite. A tag naming\n * no active feature (the feature was archived, or abandoned) gets no\n * exemption: the living spec is all there is to answer to.\n *\n * Three warnings, one per way the suite and the spec can disagree, judged\n * digest-first and by requirement name second:\n *\n * - `gherkin.missing` — a living scenario whose digest no stamped scenario of\n *   its axis carries: the suite has no test for these words.\n * - `gherkin.stale` — a stamped scenario whose digest matches no living\n *   scenario while its file's requirement still exists: the spec moved under\n *   the generated file. (A reworded scenario therefore reports both: the old\n *   words are stale, the new words are missing — one regeneration clears\n *   both.)\n * - `gherkin.orphaned` — a whole file whose requirement no longer exists in\n *   its axis's living spec; reported once per file, because every scenario in\n *   it is moot together.\n *\n * Digests are content identity within one service and one axis, deliberately:\n * two identically-worded scenarios of one service's one axis share one digest,\n * so one stamped copy covers both — while the axes stay separate namespaces\n * twice over (every comparison here is axis-scoped, and the recipe salts the\n * arch axis), and the services stay separate because the recipe salts the\n * service too. That last salt is why a stamped file copied out of another\n * service's repository grades `gherkin.orphaned`/`gherkin.stale` here instead\n * of quietly counting as this service's coverage.\n *\n * All warnings — `--strict` is the CI escalation — plus one `ok` confirmation\n * (`gherkin.current`, the `sources.current` pattern) when a generated suite\n * exists and nothing disagrees.\n */\nexport async function gherkinFindings(ctx: {\n  docsDir: DocsDir;\n  service: PathableService;\n  /** The service repo, when loam is standing in it. Undefined disables the chain, like sources.*. */\n  repoDir?: string;\n  gherkinDir?: string;\n  fleet: FleetContext;\n}): Promise<Finding[]> {\n  if (ctx.repoDir === undefined) return [];\n  let root: string;\n  try {\n    root = gherkinRoot(ctx.repoDir, ctx.gherkinDir);\n  } catch (err) {\n    if (!(err instanceof UnsafePathError)) throw err;\n    return [\n      {\n        severity: \"error\",\n        code: \"gherkin.path-outside\",\n        subject: ctx.service,\n        message: `The configured Gherkin output is unsafe: ${err.message}. It must stay inside the service repo.`,\n      },\n    ];\n  }\n  if (!existsSync(root)) return [];\n\n  // The living reference, per axis: requirement names, and scenario digests.\n  interface AxisState {\n    file: string;\n    reqNames: Set<string>;\n    digests: Set<string>;\n    scenarios: Array<{ req: string; name: string; digest: string }>;\n  }\n  const paths = await locateServicePaths(ctx.docsDir, ctx.service, ctx.fleet);\n  const axes = new Map<\"business\" | \"arch\", AxisState>();\n  for (const axis of SPEC_AXES) {\n    const label = axisLabel(axis);\n    const state: AxisState = { file: axis.file, reqNames: new Set(), digests: new Set(), scenarios: [] };\n    const path = paths[axis.key];\n    if (existsSync(path)) {\n      for (const r of await ctx.fleet.readRequirements(path)) {\n        if (r.kind === \"REMOVED\") continue;\n        state.reqNames.add(r.name);\n        for (const s of r.scenarios) {\n          const digest = scenarioDigest(ctx.service, s.lines, label);\n          state.digests.add(digest);\n          state.scenarios.push({ req: r.name, name: s.name, digest });\n        }\n      }\n    }\n    axes.set(label, state);\n  }\n\n  // The stamped side. Every stamped digest counts toward coverage — an\n  // in-flight file whose scenario matches the living words IS a test for them.\n  // `Set<string>`, not the ids' own brand: this set answers membership\n  // questions for tags read out of .feature files — document text.\n  const active = new Set<string>((await listFeatures(ctx.docsDir, {}, ctx.fleet)).map((f) => f.id));\n  const stampedDigests = { business: new Set<string>(), arch: new Set<string>() };\n  const parsed: Array<{ rel: string; axis: \"business\" | \"arch\"; file: StampedFeature }> = [];\n  let stampedScenarios = 0;\n  for (const abs of await featureFilesUnder(root)) {\n    const file = parseStampedFeature(await readFile(abs, \"utf8\"));\n    if (file === null) continue;\n    const axis = file.tags.includes(\"architecture\") ? \"arch\" : \"business\";\n    for (const s of file.scenarios) stampedDigests[axis].add(s.digest);\n    stampedScenarios += file.scenarios.length;\n    parsed.push({ rel: relative(ctx.repoDir, abs).split(sep).join(\"/\"), axis, file });\n  }\n\n  const findings: Finding[] = [];\n  const regen = `\\`loam gherkin --service ${ctx.service}\\``;\n  for (const [axis, state] of axes) {\n    for (const sc of state.scenarios) {\n      if (stampedDigests[axis].has(sc.digest)) continue;\n      findings.push({\n        severity: \"warn\",\n        code: \"gherkin.missing\",\n        subject: ctx.service,\n        message: `${ctx.service}: scenario '${sc.name}' of requirement '${sc.req}' (${state.file}) has no generated .feature scenario — the suite has no test for these words; ${regen} regenerates it`,\n      });\n    }\n  }\n  for (const { rel, axis, file } of parsed) {\n    if (file.tags.some((t) => active.has(t))) continue;\n    const state = axes.get(axis)!;\n    if (file.featureName === null || !state.reqNames.has(file.featureName)) {\n      findings.push({\n        severity: \"warn\",\n        code: \"gherkin.orphaned\",\n        subject: ctx.service,\n        message: `${ctx.service}: ${rel}: requirement '${file.featureName ?? \"(unnamed)\"}' no longer exists in the living ${state.file} — the whole file is orphaned; ${regen} removes it`,\n      });\n      continue;\n    }\n    for (const s of file.scenarios) {\n      if (state.digests.has(s.digest)) continue;\n      findings.push({\n        severity: \"warn\",\n        code: \"gherkin.stale\",\n        subject: ctx.service,\n        message: `${ctx.service}: ${rel}: scenario '${s.name}' matches no scenario in the living ${state.file} — the spec moved under the generated file; ${regen} regenerates it`,\n      });\n    }\n  }\n  if (findings.length === 0) {\n    findings.push({\n      severity: \"ok\",\n      code: \"gherkin.current\",\n      message: `${ctx.service}: generated gherkin current (${parsed.length} file(s), ${stampedScenarios} stamped scenario(s) agree with the living specs)`,\n    });\n  }\n  return findings;\n}\n\n/**\n * Every `.feature` file at or under `root`, sorted by repo-relative path —\n * enumeration is part of the output contract, so the order cannot depend on\n * the filesystem's. Dot-entries are skipped, like every other walk in loam.\n *\n * Symlinks are FOLLOWED, through `repo/tree/fs.ts`'s `entryIs` — the rule\n * every enumeration shares (brief/brief.ts's `hasEntry` too), for the same\n * reason. A `Dirent` from `readdir(withFileTypes)` never follows one, so\n * `isFile()` and `isDirectory()` are both false for a\n * symlinked `.feature`: it was invisible to the orphan scan (`loam gherkin`\n * left it behind forever) and invisible to the staleness scan (it graded as no\n * coverage at all). Composing a suite out of links is legitimate, so they are\n * followed rather than refused, and a dangling one is skipped exactly as an\n * absent file is.\n */\nexport async function featureFilesUnder(root: string): Promise<string[]> {\n  const out: string[] = [];\n  // Following links means a cycle is now possible; every directory is entered\n  // once by its resolved path (`markDescended`), so a loop terminates instead\n  // of hanging.\n  const entered = new Set<string>();\n  const walk = async (dir: string): Promise<void> => {\n    if (!markDescended(dir, entered)) return;\n    for (const entry of await readdir(dir, { withFileTypes: true })) {\n      if (entry.name.startsWith(\".\")) continue;\n      const abs = join(dir, entry.name);\n      if (entryIs(dir, entry, \"dir\")) await walk(abs);\n      else if (entry.name.endsWith(\".feature\") && entryIs(dir, entry, \"file\")) out.push(abs);\n    }\n  };\n  await walk(root);\n  return out.sort((a, b) => {\n    const ra = a.split(sep).join(\"/\");\n    const rb = b.split(sep).join(\"/\");\n    return ra < rb ? -1 : ra > rb ? 1 : 0;\n  });\n}\n"]}

package/dist/core/gherkin/stamp.js

@@ -0,0 +1,77 @@
+/**
+ * The Gherkin emission: spec scenarios become real `.feature` files.
+ *
+ * Scenarios have been "the source for tests" since SCHEMA.md's first draft, but
+ * until now they only left the docs repo as projected markdown — prose a coding
+ * agent could paraphrase into something easier to pass. The emission closes the
+ * gap mechanically: one `.feature` file per requirement, steps taken from the
+ * scenario's own bullet lines, and a digest TAG (`@loam-digest-<16hex>`) on
+ * every scenario using the SAME body-hash recipe `loam verify` folds into its
+ * claim ids (`./digest.ts`'s scenarioBodyHash — salted by the owning service and
+ * by the spec axis, so a stamp belongs to one suite and one axis) — so the
+ * test skeleton, the claim and the spec can never quietly disagree about what
+ * a scenario says, and no two repositories can answer each other's. A tag
+ * rather than a comment because tags are what cucumber's JSON report carries
+ * per scenario: the stamp rides through the runner untouched, which is what
+ * lets `loam verify --results` match a report scenario back to its claim.
+ *
+ * The files land in the SERVICE repo — the docs repo states the questions, the
+ * tests live with the code — under `<gherkinDir>/loam/`. That `loam/`
+ * subdirectory is loam's own derived space: regeneration rewrites its scope and
+ * removes its orphans, and loam never writes or deletes a byte outside it.
+ * Everything here is deterministic on purpose: the same specs yield the same
+ * bytes, which is what lets `loam validate` grade staleness by digest instead
+ * of by guesswork.
+ */
+import { join } from "node:path";
+import { scenarioBodyHash } from "./digest.js";
+import { resolveInside } from "../kernel/path-safety.js";
+/** Where Gherkin lives in a service repo when loam.json does not say. */
+const DEFAULT_GHERKIN_DIR = "features";
+/** The subdirectory loam owns outright. Everything loam writes stays inside it. */
+const GHERKIN_SUBDIR = "loam";
+/** How much of the scenario body hash goes into a `@loam-digest-…` tag. */
+export const GHERKIN_DIGEST_LENGTH = 16;
+/** The one directory `loam gherkin` may touch: `<repo>/<gherkinDir>/loam/`. */
+export function gherkinRoot(repoDir, gherkinDir) {
+    return resolveInside(repoDir, join(gherkinDir ?? DEFAULT_GHERKIN_DIR, GHERKIN_SUBDIR), "gherkin output directory");
+}
+/**
+ * The digest stamped onto every generated scenario: verify's scenario body
+ * hash, at the sources-digest length. Content identity WITHIN one service and
+ * one axis, not provenance — two identically-worded scenarios of one service's
+ * one axis share a digest, and that is the point: the stamp answers "does this
+ * suite still contain a test for THESE words".
+ *
+ * Both salts ride in the hash (see `scenarioBodyHash`), so the namespaces stay
+ * separate all the way into a cucumber report: a business run can never answer
+ * for an arch scenario, and one service's green run can never answer another
+ * service's claim just because the two specs spell the sentence the same way.
+ * `service` is required and never defaulted — a stamp that forgot it would be
+ * a tag no claim matches, and the fleet bug it exists to close would come back
+ * silently.
+ */
+export function scenarioDigest(service, lines, axis = "business") {
+    return scenarioBodyHash(service, lines, axis).slice(0, GHERKIN_DIGEST_LENGTH);
+}
+/** The digest as the tag on the line above each `Scenario:`. */
+export function scenarioDigestTag(digest) {
+    return `@loam-digest-${digest}`;
+}
+/**
+ * A tag token carrying a scenario digest — in a generated file, or in a
+ * cucumber JSON report. The leading `@` is optional because some runners
+ * (behave) strip it from the tags they report.
+ */
+export const DIGEST_TAG_RE = /^@?loam-digest-([0-9a-f]{16})$/;
+/**
+ * Line 1 of every generated file — the AGENTS.md stamp pattern, in Gherkin
+ * comment syntax. The version records which loam wrote the file; the rest is
+ * the ownership rule in the reader's face, because `loam/` files are rewritten
+ * wholesale on regeneration and a hand edit would be silently destroyed.
+ */
+export function gherkinStampLine(version) {
+    return `# generated by loam v${version} — \`loam gherkin\`; do not hand-edit, regenerate instead`;
+}
+export const STAMP_RE = /^#\s*generated by loam v(\S+)/;
+//# sourceMappingURL=stamp.js.map

package/dist/core/gherkin/stamp.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"stamp.js","sourceRoot":"","sources":["../../../src/core/gherkin/stamp.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,EAAE,gBAAgB,EAAqB,MAAM,aAAa,CAAC;AAClE,OAAO,EAAE,aAAa,EAAE,MAAM,0BAA0B,CAAC;AAEzD,yEAAyE;AACzE,MAAM,mBAAmB,GAAG,UAAU,CAAC;AAEvC,mFAAmF;AACnF,MAAM,cAAc,GAAG,MAAM,CAAC;AAE9B,2EAA2E;AAC3E,MAAM,CAAC,MAAM,qBAAqB,GAAG,EAAE,CAAC;AAExC,+EAA+E;AAC/E,MAAM,UAAU,WAAW,CAAC,OAAe,EAAE,UAAmB;IAC9D,OAAO,aAAa,CAClB,OAAO,EACP,IAAI,CAAC,UAAU,IAAI,mBAAmB,EAAE,cAAc,CAAC,EACvD,0BAA0B,CAC3B,CAAC;AACJ,CAAC;AAED;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,cAAc,CAC5B,OAAe,EACf,KAAe,EACf,IAAI,GAAiB,UAAU;IAE/B,OAAO,gBAAgB,CAAC,OAAO,EAAE,KAAK,EAAE,IAAI,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,qBAAqB,CAAC,CAAC;AAChF,CAAC;AAED,gEAAgE;AAChE,MAAM,UAAU,iBAAiB,CAAC,MAAc;IAC9C,OAAO,gBAAgB,MAAM,EAAE,CAAC;AAClC,CAAC;AAED;;;;GAIG;AACH,MAAM,CAAC,MAAM,aAAa,GAAG,gCAAgC,CAAC;AAE9D;;;;;GAKG;AACH,MAAM,UAAU,gBAAgB,CAAC,OAAe;IAC9C,OAAO,wBAAwB,OAAO,2DAA2D,CAAC;AACpG,CAAC;AAED,MAAM,CAAC,MAAM,QAAQ,GAAG,+BAA+B,CAAC","sourcesContent":["/**\n * The Gherkin emission: spec scenarios become real `.feature` files.\n *\n * Scenarios have been \"the source for tests\" since SCHEMA.md's first draft, but\n * until now they only left the docs repo as projected markdown — prose a coding\n * agent could paraphrase into something easier to pass. The emission closes the\n * gap mechanically: one `.feature` file per requirement, steps taken from the\n * scenario's own bullet lines, and a digest TAG (`@loam-digest-<16hex>`) on\n * every scenario using the SAME body-hash recipe `loam verify` folds into its\n * claim ids (`./digest.ts`'s scenarioBodyHash — salted by the owning service and\n * by the spec axis, so a stamp belongs to one suite and one axis) — so the\n * test skeleton, the claim and the spec can never quietly disagree about what\n * a scenario says, and no two repositories can answer each other's. A tag\n * rather than a comment because tags are what cucumber's JSON report carries\n * per scenario: the stamp rides through the runner untouched, which is what\n * lets `loam verify --results` match a report scenario back to its claim.\n *\n * The files land in the SERVICE repo — the docs repo states the questions, the\n * tests live with the code — under `<gherkinDir>/loam/`. That `loam/`\n * subdirectory is loam's own derived space: regeneration rewrites its scope and\n * removes its orphans, and loam never writes or deletes a byte outside it.\n * Everything here is deterministic on purpose: the same specs yield the same\n * bytes, which is what lets `loam validate` grade staleness by digest instead\n * of by guesswork.\n */\nimport { join } from \"node:path\";\nimport { scenarioBodyHash, type ScenarioAxis } from \"./digest.js\";\nimport { resolveInside } from \"../kernel/path-safety.js\";\n\n/** Where Gherkin lives in a service repo when loam.json does not say. */\nconst DEFAULT_GHERKIN_DIR = \"features\";\n\n/** The subdirectory loam owns outright. Everything loam writes stays inside it. */\nconst GHERKIN_SUBDIR = \"loam\";\n\n/** How much of the scenario body hash goes into a `@loam-digest-…` tag. */\nexport const GHERKIN_DIGEST_LENGTH = 16;\n\n/** The one directory `loam gherkin` may touch: `<repo>/<gherkinDir>/loam/`. */\nexport function gherkinRoot(repoDir: string, gherkinDir?: string): string {\n  return resolveInside(\n    repoDir,\n    join(gherkinDir ?? DEFAULT_GHERKIN_DIR, GHERKIN_SUBDIR),\n    \"gherkin output directory\",\n  );\n}\n\n/**\n * The digest stamped onto every generated scenario: verify's scenario body\n * hash, at the sources-digest length. Content identity WITHIN one service and\n * one axis, not provenance — two identically-worded scenarios of one service's\n * one axis share a digest, and that is the point: the stamp answers \"does this\n * suite still contain a test for THESE words\".\n *\n * Both salts ride in the hash (see `scenarioBodyHash`), so the namespaces stay\n * separate all the way into a cucumber report: a business run can never answer\n * for an arch scenario, and one service's green run can never answer another\n * service's claim just because the two specs spell the sentence the same way.\n * `service` is required and never defaulted — a stamp that forgot it would be\n * a tag no claim matches, and the fleet bug it exists to close would come back\n * silently.\n */\nexport function scenarioDigest(\n  service: string,\n  lines: string[],\n  axis: ScenarioAxis = \"business\",\n): string {\n  return scenarioBodyHash(service, lines, axis).slice(0, GHERKIN_DIGEST_LENGTH);\n}\n\n/** The digest as the tag on the line above each `Scenario:`. */\nexport function scenarioDigestTag(digest: string): string {\n  return `@loam-digest-${digest}`;\n}\n\n/**\n * A tag token carrying a scenario digest — in a generated file, or in a\n * cucumber JSON report. The leading `@` is optional because some runners\n * (behave) strip it from the tags they report.\n */\nexport const DIGEST_TAG_RE = /^@?loam-digest-([0-9a-f]{16})$/;\n\n/**\n * Line 1 of every generated file — the AGENTS.md stamp pattern, in Gherkin\n * comment syntax. The version records which loam wrote the file; the rest is\n * the ownership rule in the reader's face, because `loam/` files are rewritten\n * wholesale on regeneration and a hand edit would be silently destroyed.\n */\nexport function gherkinStampLine(version: string): string {\n  return `# generated by loam v${version} — \\`loam gherkin\\`; do not hand-edit, regenerate instead`;\n}\n\nexport const STAMP_RE = /^#\\s*generated by loam v(\\S+)/;\n\n"]}

package/dist/core/gherkin/steps/catalogue.js

@@ -0,0 +1,154 @@
+/**
+ * The step catalogue: which phrases somebody has DECIDED the suite defines.
+ *
+ * ## The decision this file records, because it was the open question
+ *
+ * `./inventory.ts` answers how many definitions a suite needs. It stops there on
+ * purpose — no file, no finding, no stable code — and the gap it leaves is the
+ * next ARTIFACT, not the next warning: a team reads the report, writes the glue
+ * by hand, and nothing anywhere records which phrases now have definitions, so
+ * the report is recomputed from scratch every time instead of diffed against a
+ * decision somebody made.
+ *
+ * The catalogue is **AUTHORED**, not emitted, and it lives in the DOCS repo at
+ * `services/<svc>/steps.yaml`. Four things decided it:
+ *
+ *  - It is a DECISION, not an observation. loam does not read code and must
+ *    never present a derived thing as truth (the non-goal is written down); what
+ *    a team can say is "these are the phrases we have agreed to define", and
+ *    that sentence is an authored document by construction. An emitted
+ *    catalogue would have to be derived from a step registry loam cannot read.
+ *  - `loam steps` NEEDS NO SERVICE REPO to stand in — that is its own stated
+ *    design, and it reads the living specs rather than the emitted `.feature`
+ *    files precisely so it answers the same way in a repo that has never run
+ *    `loam gherkin`. A catalogue in the service repo would make the comparison
+ *    require one, which is a different command.
+ *  - The shape rule the glossary and capability trees already settled: an entry
+ *    with prose gets a file, an entry WITHOUT prose stays a line in YAML. A
+ *    catalogue entry is a phrase and nothing else, so it is a line in YAML — the
+ *    same side of that rule `architecture/capabilities.yaml` and
+ *    `permissions.yaml` sit on.
+ *  - Nothing generated may land inside `<gherkinDir>/loam/`, which `loam
+ *    gherkin` owns and overwrites wholesale. Living in the docs repo satisfies
+ *    that by construction rather than by a rule somebody has to remember.
+ *
+ * SERVICE-SCOPED, beside `health.yaml`, because a step registry belongs to one
+ * suite and a suite belongs to one service. A fleet-level catalogue would claim
+ * one registry across services that do not share a test runner.
+ *
+ * ## What it does NOT do, and this is the other half of the decision
+ *
+ * **It gains no stable code, and `loam validate` never reads it.** A phrase
+ * written but not catalogued is a work-list row, not a breach: writing a spec
+ * ahead of the glue is the normal order, and a check that fires on it is the
+ * kind a fleet turns off — at which point the real findings beside it are turned
+ * off too. The near-duplicate groups stay a report for the same reason. So this
+ * axis costs one document kind and zero codes, and everything it produces is
+ * columns in `loam steps`.
+ *
+ * **It claims nothing about whether the glue exists.** A catalogued phrase is a
+ * phrase somebody said they would define; loam cannot see a step registry and
+ * does not pretend to. The two columns are named for what they actually mean —
+ * written-not-catalogued and catalogued-not-written — and neither says "missing
+ * definition".
+ *
+ * ## The grammar
+ *
+ * ```yaml
+ * steps:
+ *   - a payment of 100.00
+ *   - Given it is split 60/40
+ * ```
+ *
+ * A list of step TEXTS, not of keys. The key is loam's own spelling — `{n}`,
+ * `{s}`, `{p}` collapse, keyword stripped (`./phrase.ts`) — and asking an author
+ * to write it would make an internal normalisation a hand-typed contract, where
+ * one wrong brace silently catalogues nothing. So an entry is written the way a
+ * step is written, with or without its keyword, and loam keys it the same way it
+ * keys the written steps it is being compared against. Two entries that collapse
+ * onto one key are reported as such rather than merged: that is the author
+ * cataloguing one definition twice, which is exactly what the near-duplicate
+ * report exists to surface.
+ */
+import { existsSync } from "node:fs";
+import { readFile } from "node:fs/promises";
+import { parse as parseYaml } from "yaml";
+import { isRecord } from "../../kernel/records.js";
+import { compareIds } from "../../repo/entries.js";
+import { phraseOf } from "./phrase.js";
+import {} from "./inventory.js";
+const ABSENT = { present: false, entries: [] };
+/**
+ * Read one service's catalogue.
+ *
+ * A missing file is silence, not an error: the axis's opt-in is the file's
+ * existence, exactly as `capabilities/`'s is a directory's. Anything present and
+ * unparseable is `unreadable` with the reason — never an empty catalogue, which
+ * would report every written phrase as uncatalogued and read as a work-list
+ * somebody has to do.
+ */
+export async function readStepCatalogue(path) {
+    if (!existsSync(path))
+        return ABSENT;
+    let doc;
+    try {
+        doc = parseYaml(await readFile(path, "utf8"));
+    }
+    catch (e) {
+        return { present: true, entries: [], unreadable: e instanceof Error ? e.message : String(e) };
+    }
+    if (doc === null || doc === undefined)
+        return { present: true, entries: [] };
+    if (!isRecord(doc))
+        return { present: true, entries: [], unreadable: "the document is not a mapping" };
+    const block = doc["steps"];
+    if (block === undefined)
+        return { present: true, entries: [] };
+    if (!Array.isArray(block)) {
+        return { present: true, entries: [], unreadable: "`steps` is not a list of step texts" };
+    }
+    const entries = [];
+    for (const item of block) {
+        // A non-string entry refuses the whole file rather than being skipped. A
+        // skipped entry is a phrase silently absent from the catalogue, which prints
+        // as "written but not catalogued" — a work-list row invented by a shape
+        // error, which is the wrong answer this fails closed to avoid.
+        if (typeof item !== "string") {
+            return { present: true, entries: [], unreadable: "every `steps` entry must be a step text (a string)" };
+        }
+        entries.push({ text: item, key: phraseOf(item).key });
+    }
+    return { present: true, entries };
+}
+/**
+ * Written phrases against catalogued ones.
+ *
+ * ORDER IS THE INVENTORY'S for `uncatalogued` — `inv.phrases` is already sorted
+ * count-descending then key-ascending, so the work-list comes out with the
+ * phrase that pays back most first, and stays diffable. `unwritten` and
+ * `duplicated` have no count to sort on and are sorted by key.
+ *
+ * The catalogue's own `present`/`unreadable` state is NOT consulted here: this
+ * is the comparison, and whether it was worth making is the caller's question.
+ * Handing it an unreadable catalogue would produce a full `uncatalogued` list
+ * that reads exactly like a real work-list, which is why the caller checks first.
+ */
+export function compareToCatalogue(inv, catalogue) {
+    const catalogued = new Set(catalogue.entries.map((e) => e.key));
+    const written = new Set(inv.phrases.map((p) => p.key));
+    const bySpelling = new Map();
+    for (const entry of catalogue.entries) {
+        const texts = bySpelling.get(entry.key) ?? [];
+        texts.push(entry.text);
+        bySpelling.set(entry.key, texts);
+    }
+    return {
+        uncatalogued: inv.phrases.filter((p) => !catalogued.has(p.key)).map((p) => p.key),
+        unwritten: [...catalogued].filter((key) => !written.has(key)).sort(compareIds),
+        duplicated: [...bySpelling]
+            .filter(([, texts]) => texts.length > 1)
+            .map(([key, texts]) => ({ key, texts }))
+            .sort((a, b) => compareIds(a.key, b.key)),
+    };
+}
+//# sourceMappingURL=catalogue.js.map