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

package/dist/core/{frontmatter.js → document/frontmatter.js}

@@ -9,7 +9,7 @@
 import { existsSync } from "node:fs";
 import { readFile } from "node:fs/promises";
 import { isMap, parse, parseDocument } from "yaml";
-import { decodeDocument, NotUtf8DocumentError } from "./document-bytes.js";
+import { decodeDocument, NotUtf8DocumentError } from "../kernel/document-bytes.js";
 /**
  * Drop a leading byte-order mark.
  *
@@ -132,8 +132,24 @@ export function listField(fm, key) {
  * A document with no frontmatter gets one, and the text that was there becomes
  * the body. A header that does not parse (or is not a mapping) is replaced
  * rather than merged into — it cannot be edited without guessing what it meant.
+ *
+ * Keys named in `remove` are DELETED. That is not a convenience: `loam vouch`
+ * stamps `vouch_scope` when a person read only a sample of the document, and
+ * a full vouch afterwards has to take that claim back out. Left behind, a
+ * stale scope would keep a fully-read document reading as sampled forever —
+ * on `loam list`, in `loam validate`'s `sources.sampled-vouch`, and in the
+ * frontmatter a person opens — which is the same class of lie as a stamp with
+ * nothing behind it, pointing the other way.
+ *
+ * Deletion is a separate LIST rather than a null value in `fields`, and the
+ * difference is the compiler's: `string | null` is the most common field shape
+ * in this codebase (`stringField(fm, k) ?? null` appears in a dozen readers),
+ * so a writer that stamped a field it had just read back — `{ owner }` — would
+ * silently delete `owner` on every document that never had one, where today
+ * that line does not compile. Clearing a key is something a call site says,
+ * never something a value happens to be.
  */
-export function withFrontmatterFields(source, fields) {
+export function withFrontmatterFields(source, fields, remove = []) {
     // Stamping a BOM-prefixed document drops the BOM. It sits above the header, so
     // the promise about the body still holds — and leaving it would re-break the
     // file for every parser anchored at position 0, including ours.
@@ -144,6 +160,15 @@ export function withFrontmatterFields(source, fields) {
     const doc = editable ? parsed : parseDocument("");
     for (const [key, value] of Object.entries(fields))
         doc.set(key, value);
+    // Guarded, not because a missing key is a problem — deleting one that is not
+    // there is a no-op — but because yaml's `Document.delete` THROWS ("Expected
+    // a YAML collection as document contents") when the document has no mapping
+    // at all: the empty header of a document that had none, and the replacement
+    // built for a header that would not parse. Both are states this writer
+    // reaches on purpose, and in both there is nothing to clear.
+    if (isMap(doc.contents))
+        for (const key of remove)
+            doc.delete(key);
     const yamlText = doc.toString();
     if (at === null)
         return `---\n${yamlText}---\n\n${md}`;
@@ -196,4 +221,25 @@ export async function readFrontmatter(path) {
 /** The statuses each kind of artifact may carry. */
 export const SERVICE_STATUSES = ["draft", "verified"];
 export const FEATURE_STATUSES = ["proposed", "in_progress", "built", "done"];
+/**
+ * A document's prose with any leading frontmatter block dropped — what
+ * `loam delta` and `loam context` print as a feature's intent.
+ *
+ * Moved verbatim from `commands/delta/slices.ts` when the context pack became
+ * its second caller. It deliberately keeps its own, looser fence rule
+ * (`\n---` as a substring, not `bounds()`'s line-exact match) rather than
+ * delegating to `parseFrontmatter(md).body`: the two agree on every header
+ * loam writes, but the delta brief's output is pinned byte-for-byte by its
+ * tests, and unifying the rules is a behaviour change to make deliberately,
+ * not as a side effect of a move.
+ */
+export function stripFrontmatter(md) {
+    if (!md.startsWith("---"))
+        return md;
+    const close = md.indexOf("\n---", 3);
+    if (close === -1)
+        return md;
+    const nl = md.indexOf("\n", close + 1);
+    return nl === -1 ? "" : md.slice(nl + 1).trimStart();
+}
 //# sourceMappingURL=frontmatter.js.map

package/dist/core/document/frontmatter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"frontmatter.js","sourceRoot":"","sources":["../../../src/core/document/frontmatter.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AACrC,OAAO,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAC5C,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,aAAa,EAAE,MAAM,MAAM,CAAC;AACnD,OAAO,EAAE,cAAc,EAAE,oBAAoB,EAAE,MAAM,6BAA6B,CAAC;AA2CnF;;;;;;;;;;;GAWG;AACH,SAAS,QAAQ,CAAC,IAAY;IAC5B,OAAO,IAAI,CAAC,UAAU,CAAC,CAAC,CAAC,KAAK,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;AAC9D,CAAC;AAED;;;;;;GAMG;AACH,MAAM,QAAQ,GAAG,UAAU,CAAC;AAE5B;;;;;;;;GAQG;AACH,SAAS,MAAM,CAAC,EAAU;IACxB,MAAM,OAAO,GAAG,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;IACjC,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,OAAO,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,KAAK,CAAC,CAAC,EAAE,OAAO,CAAC,CAAC;QAAE,OAAO,IAAI,CAAC;IAC5E,gEAAgE;IAChE,IAAI,OAAO,KAAK,CAAC,CAAC;QAAE,OAAO,IAAI,CAAC;IAChC,MAAM,KAAK,GAAG,OAAO,GAAG,CAAC,CAAC;IAC1B,KAAK,IAAI,SAAS,GAAG,KAAK,IAAM,CAAC;QAC/B,MAAM,EAAE,GAAG,EAAE,CAAC,OAAO,CAAC,IAAI,EAAE,SAAS,CAAC,CAAC;QACvC,MAAM,IAAI,GAAG,EAAE,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,KAAK,CAAC,SAAS,EAAE,EAAE,CAAC,CAAC;QACvE,IAAI,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;YACxB,6EAA6E;YAC7E,OAAO,EAAE,KAAK,EAAE,GAAG,EAAE,SAAS,EAAE,SAAS,EAAE,EAAE,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,GAAG,CAAC,EAAE,CAAC;QAC9E,CAAC;QACD,IAAI,EAAE,KAAK,CAAC,CAAC;YAAE,OAAO,IAAI,CAAC;QAC3B,SAAS,GAAG,EAAE,GAAG,CAAC,CAAC;IACrB,CAAC;AACH,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,gBAAgB,CAAC,MAAc;IAC7C,MAAM,EAAE,GAAG,QAAQ,CAAC,MAAM,CAAC,CAAC;IAC5B,MAAM,EAAE,GAAG,MAAM,CAAC,EAAE,CAAC,CAAC;IACtB,IAAI,EAAE,KAAK,IAAI;QAAE,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,SAAS,EAAE,KAAK,EAAE,IAAI,EAAE,EAAE,EAAE,IAAI,EAAE,EAAE,EAAE,CAAC;IAEjF,MAAM,QAAQ,GAAG,EAAE,CAAC,KAAK,CAAC,EAAE,CAAC,KAAK,EAAE,EAAE,CAAC,GAAG,CAAC,CAAC;IAC5C,MAAM,IAAI,GAAG,EAAE,CAAC,KAAK,CAAC,EAAE,CAAC,SAAS,CAAC,CAAC,SAAS,EAAE,CAAC;IAEhD,IAAI,IAAI,GAA4B,EAAE,CAAC;IACvC,IAAI,SAAS,GAAG,KAAK,CAAC;IACtB,IAAI,CAAC;QACH,MAAM,MAAM,GAAY,KAAK,CAAC,QAAQ,CAAC,CAAC;QACxC,IAAI,MAAM,IAAI,OAAO,MAAM,KAAK,QAAQ,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC;YACnE,IAAI,GAAG,MAAiC,CAAC;QAC3C,CAAC;aAAM,IAAI,MAAM,KAAK,IAAI,EAAE,CAAC;YAC3B,yEAAyE;YACzE,uEAAuE;YACvE,SAAS,GAAG,IAAI,CAAC;QACnB,CAAC;IACH,CAAC;IAAC,MAAM,CAAC;QACP,4EAA4E;QAC5E,0EAA0E;QAC1E,qEAAqE;QACrE,gEAAgE;QAChE,SAAS,GAAG,IAAI,CAAC;IACnB,CAAC;IACD,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC;AAClD,CAAC;AAED,mFAAmF;AACnF,MAAM,UAAU,WAAW,CAAC,EAAe,EAAE,GAAW;IACtD,MAAM,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IACvB,IAAI,CAAC,KAAK,SAAS,IAAI,CAAC,KAAK,IAAI;QAAE,OAAO,SAAS,CAAC;IACpD,IAAI,OAAO,CAAC,KAAK,QAAQ;QAAE,OAAO,CAAC,CAAC;IACpC,IAAI,OAAO,CAAC,KAAK,QAAQ,IAAI,OAAO,CAAC,KAAK,SAAS;QAAE,OAAO,MAAM,CAAC,CAAC,CAAC,CAAC;IACtE,IAAI,CAAC,YAAY,IAAI;QAAE,OAAO,CAAC,CAAC,WAAW,EAAE,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;IAC3D,OAAO,SAAS,CAAC;AACnB,CAAC;AAED,gEAAgE;AAChE,MAAM,UAAU,SAAS,CAAC,EAAe,EAAE,GAAW;IACpD,MAAM,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IACvB,IAAI,CAAC,KAAK,SAAS,IAAI,CAAC,KAAK,IAAI;QAAE,OAAO,EAAE,CAAC;IAC7C,IAAI,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC;QAAE,OAAO,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;IACjF,MAAM,GAAG,GAAG,WAAW,CAAC,EAAE,EAAE,GAAG,CAAC,CAAC;IACjC,OAAO,GAAG,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC;AACxC,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,MAAM,UAAU,qBAAqB,CACnC,MAAc,EACd,MAA8B,EAC9B,MAAM,GAAsB,EAAE;IAE9B,+EAA+E;IAC/E,6EAA6E;IAC7E,gEAAgE;IAChE,MAAM,EAAE,GAAG,QAAQ,CAAC,MAAM,CAAC,CAAC;IAC5B,MAAM,EAAE,GAAG,MAAM,CAAC,EAAE,CAAC,CAAC;IACtB,MAAM,MAAM,GAAG,aAAa,CAAC,EAAE,KAAK,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,KAAK,CAAC,EAAE,CAAC,KAAK,EAAE,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IAC5E,MAAM,QAAQ,GAAG,MAAM,CAAC,MAAM,CAAC,MAAM,KAAK,CAAC,IAAI,CAAC,MAAM,CAAC,QAAQ,KAAK,IAAI,IAAI,KAAK,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC;IACpG,MAAM,GAAG,GAAG,QAAQ,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,aAAa,CAAC,EAAE,CAAC,CAAC;IAElD,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC;QAAE,GAAG,CAAC,GAAG,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;IACvE,6EAA6E;IAC7E,4EAA4E;IAC5E,4EAA4E;IAC5E,4EAA4E;IAC5E,uEAAuE;IACvE,6DAA6D;IAC7D,IAAI,KAAK,CAAC,GAAG,CAAC,QAAQ,CAAC;QAAE,KAAK,MAAM,GAAG,IAAI,MAAM;YAAE,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;IACnE,MAAM,QAAQ,GAAG,GAAG,CAAC,QAAQ,EAAE,CAAC;IAEhC,IAAI,EAAE,KAAK,IAAI;QAAE,OAAO,QAAQ,QAAQ,UAAU,EAAE,EAAE,CAAC;IACvD,OAAO,EAAE,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,KAAK,CAAC,GAAG,QAAQ,GAAG,EAAE,CAAC,KAAK,CAAC,EAAE,CAAC,GAAG,CAAC,CAAC;AAC7D,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,OAAO,CAAC,MAAc;IACpC,MAAM,EAAE,GAAG,QAAQ,CAAC,MAAM,CAAC,CAAC;IAC5B,MAAM,EAAE,GAAG,MAAM,CAAC,EAAE,CAAC,CAAC;IACtB,OAAO,EAAE,KAAK,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,KAAK,CAAC,EAAE,CAAC,SAAS,CAAC,CAAC;AACnD,CAAC;AAED;;;;;;;;;;;;;;;GAeG;AACH,MAAM,CAAC,KAAK,UAAU,eAAe,CAAC,IAAY;IAChD,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC;QAAE,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,SAAS,EAAE,KAAK,EAAE,IAAI,EAAE,EAAE,EAAE,IAAI,EAAE,EAAE,EAAE,CAAC;IACvF,IAAI,IAAY,CAAC;IACjB,IAAI,CAAC;QACH,IAAI,GAAG,cAAc,CAAC,MAAM,QAAQ,CAAC,IAAI,CAAC,EAAE,IAAI,CAAC,CAAC;IACpD,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,IAAI,CAAC,CAAC,GAAG,YAAY,oBAAoB,CAAC;YAAE,MAAM,GAAG,CAAC;QACtD,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,SAAS,EAAE,KAAK,EAAE,UAAU,EAAE,GAAG,CAAC,OAAO,EAAE,IAAI,EAAE,EAAE,EAAE,IAAI,EAAE,EAAE,EAAE,CAAC;IAC3F,CAAC;IACD,OAAO,gBAAgB,CAAC,IAAI,CAAC,CAAC;AAChC,CAAC;AAED,oDAAoD;AACpD,MAAM,CAAC,MAAM,gBAAgB,GAAG,CAAC,OAAO,EAAE,UAAU,CAAU,CAAC;AAC/D,MAAM,CAAC,MAAM,gBAAgB,GAAG,CAAC,UAAU,EAAE,aAAa,EAAE,OAAO,EAAE,MAAM,CAAU,CAAC;AAEtF;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,gBAAgB,CAAC,EAAU;IACzC,IAAI,CAAC,EAAE,CAAC,UAAU,CAAC,KAAK,CAAC;QAAE,OAAO,EAAE,CAAC;IACrC,MAAM,KAAK,GAAG,EAAE,CAAC,OAAO,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC;IACrC,IAAI,KAAK,KAAK,CAAC,CAAC;QAAE,OAAO,EAAE,CAAC;IAC5B,MAAM,EAAE,GAAG,EAAE,CAAC,OAAO,CAAC,IAAI,EAAE,KAAK,GAAG,CAAC,CAAC,CAAC;IACvC,OAAO,EAAE,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,KAAK,CAAC,EAAE,GAAG,CAAC,CAAC,CAAC,SAAS,EAAE,CAAC;AACvD,CAAC","sourcesContent":["/**\n * YAML frontmatter — the provenance of an artifact.\n *\n * `status` says whether a human has vouched for the document, `sources` says\n * which code it was written from. When the prose is written by an agent, these\n * are the only deterministic tie to reality: everything else loam checks is\n * internal consistency, which a fluent enough fiction satisfies perfectly.\n */\nimport { existsSync } from \"node:fs\";\nimport { readFile } from \"node:fs/promises\";\nimport { isMap, parse, parseDocument } from \"yaml\";\nimport { decodeDocument, NotUtf8DocumentError } from \"../kernel/document-bytes.js\";\n\nexport interface Frontmatter {\n  /** True when a terminated `---` block was found, even if it was empty. */\n  present: boolean;\n  /**\n   * True when the block was found but its YAML cannot be read as a mapping —\n   * a parse error, or a scalar/sequence document. `data` is then {}, which is\n   * NOT the same fact as an empty header: the fields are unreadable, not\n   * absent, and a checker that grades them \"missing\" sends the author adding\n   * lines to a block YAML refuses to parse. Validate turns this flag into\n   * `frontmatter.malformed`; the writer (withFrontmatterFields) has its own\n   * replace-don't-merge rule for the same state.\n   */\n  malformed: boolean;\n  /**\n   * Why the FILE could not be read as text at all, or absent when it could —\n   * set only by `readFrontmatter`, since a caller that already holds a string\n   * has nothing left to decode.\n   *\n   * A third state, not a shade of the other two: `present: false` here means\n   * nobody could look, where everywhere else it means nobody wrote a header.\n   * A checker must ask this first, or it reports \"owner/status/sources missing\"\n   * over a file whose lines are right there — the same false cascade\n   * `malformed` exists to stop, one layer lower down.\n   */\n  unreadable?: string;\n  /** The parsed mapping, or {} when absent or malformed. */\n  data: Record<string, unknown>;\n  /** The document with the frontmatter removed. */\n  body: string;\n}\n\n/** Where the header sits in the raw text. */\ninterface Bounds {\n  /** First character of the YAML text. */\n  start: number;\n  /** One past its last character — the newline before the closing fence included. */\n  end: number;\n  /** First character of the body. */\n  bodyStart: number;\n}\n\n/**\n * Drop a leading byte-order mark.\n *\n * With one in front, the opening `---` is no longer at position 0, so the whole\n * header reads as absent: a documented artifact silently becomes an\n * undocumented one — no owner, no status, no `sources` — and nothing says why.\n * The same blindness `spec.ts` had at `^##`.\n *\n * Only at position 0: elsewhere U+FEFF is a zero-width no-break space and is the\n * author's content. Callers strip before measuring, so the offsets `bounds`\n * returns index the same string the caller then slices.\n */\nfunction stripBom(text: string): string {\n  return text.charCodeAt(0) === 0xfeff ? text.slice(1) : text;\n}\n\n/**\n * A fence is a LINE of exactly three dashes. Trailing whitespace is tolerated\n * (`\\s` also swallows the CR of a CRLF file), trailing text is not: `--- title`\n * is prose, `----` is a horizontal rule. Matching the substring `---` instead —\n * as this used to — made both of those fences, so a stray rule closed the\n * header early and a `--- note` closer silently ate its own trailing text.\n */\nconst FENCE_RE = /^---\\s*$/;\n\n/**\n * Locate the frontmatter block. The opener is the very first line, the closer\n * the first subsequent fence line — a later horizontal rule is body, not a\n * second fence. No closer means an unterminated opener: not frontmatter at all.\n *\n * The reader and the writer both go through this, so they can never disagree\n * about which bytes are the header — the writer's promise to leave the body\n * untouched depends on that being one decision, not two.\n */\nfunction bounds(md: string): Bounds | null {\n  const firstNl = md.indexOf(\"\\n\");\n  if (!FENCE_RE.test(firstNl === -1 ? md : md.slice(0, firstNl))) return null;\n  // A lone `---` with nothing after it is an unterminated opener.\n  if (firstNl === -1) return null;\n  const start = firstNl + 1;\n  for (let lineStart = start; ; ) {\n    const nl = md.indexOf(\"\\n\", lineStart);\n    const line = nl === -1 ? md.slice(lineStart) : md.slice(lineStart, nl);\n    if (FENCE_RE.test(line)) {\n      // An empty block (`---\\n---`) has no text between the fences: start === end.\n      return { start, end: lineStart, bodyStart: nl === -1 ? md.length : nl + 1 };\n    }\n    if (nl === -1) return null;\n    lineStart = nl + 1;\n  }\n}\n\n/**\n * Split a markdown document into its frontmatter and body. A document with no\n * frontmatter is returned whole rather than truncated.\n */\nexport function parseFrontmatter(source: string): Frontmatter {\n  const md = stripBom(source);\n  const at = bounds(md);\n  if (at === null) return { present: false, malformed: false, data: {}, body: md };\n\n  const yamlText = md.slice(at.start, at.end);\n  const body = md.slice(at.bodyStart).trimStart();\n\n  let data: Record<string, unknown> = {};\n  let malformed = false;\n  try {\n    const parsed: unknown = parse(yamlText);\n    if (parsed && typeof parsed === \"object\" && !Array.isArray(parsed)) {\n      data = parsed as Record<string, unknown>;\n    } else if (parsed !== null) {\n      // A scalar or sequence header holds no fields to read — as unreadable as\n      // broken YAML. null is the empty block (`---\\n---`): legal, and empty.\n      malformed = true;\n    }\n  } catch {\n    // A bad header must not make the document unreadable (the body is still the\n    // body, and never crashes a command) — but the failure travels as a flag,\n    // so the caller can say `frontmatter.malformed` instead of the false\n    // cascade \"owner/status missing\" the silent {} used to produce.\n    malformed = true;\n  }\n  return { present: true, malformed, data, body };\n}\n\n/** A field as text. Non-string scalars (a bare date, a number) are stringified. */\nexport function stringField(fm: Frontmatter, key: string): string | undefined {\n  const v = fm.data[key];\n  if (v === undefined || v === null) return undefined;\n  if (typeof v === \"string\") return v;\n  if (typeof v === \"number\" || typeof v === \"boolean\") return String(v);\n  if (v instanceof Date) return v.toISOString().slice(0, 10);\n  return undefined;\n}\n\n/** A field as a list. A lone scalar counts as a list of one. */\nexport function listField(fm: Frontmatter, key: string): string[] {\n  const v = fm.data[key];\n  if (v === undefined || v === null) return [];\n  if (Array.isArray(v)) return v.map((x) => String(x)).filter((s) => s.length > 0);\n  const one = stringField(fm, key);\n  return one === undefined ? [] : [one];\n}\n\n/**\n * Return `md` with these frontmatter fields set and everything below the closing\n * fence byte-identical.\n *\n * The header is edited through yaml's document model rather than rebuilt from\n * the parsed data: keys keep their order and their comments, fields nobody named\n * are left exactly as they were, and a value that would read back as something\n * else — a digest of all digits, say — gets quoted for us. Stamping a document\n * is not a licence to reformat it: the diff a reviewer sees should be the lines\n * that changed, and nothing else.\n *\n * A document with no frontmatter gets one, and the text that was there becomes\n * the body. A header that does not parse (or is not a mapping) is replaced\n * rather than merged into — it cannot be edited without guessing what it meant.\n *\n * Keys named in `remove` are DELETED. That is not a convenience: `loam vouch`\n * stamps `vouch_scope` when a person read only a sample of the document, and\n * a full vouch afterwards has to take that claim back out. Left behind, a\n * stale scope would keep a fully-read document reading as sampled forever —\n * on `loam list`, in `loam validate`'s `sources.sampled-vouch`, and in the\n * frontmatter a person opens — which is the same class of lie as a stamp with\n * nothing behind it, pointing the other way.\n *\n * Deletion is a separate LIST rather than a null value in `fields`, and the\n * difference is the compiler's: `string | null` is the most common field shape\n * in this codebase (`stringField(fm, k) ?? null` appears in a dozen readers),\n * so a writer that stamped a field it had just read back — `{ owner }` — would\n * silently delete `owner` on every document that never had one, where today\n * that line does not compile. Clearing a key is something a call site says,\n * never something a value happens to be.\n */\nexport function withFrontmatterFields(\n  source: string,\n  fields: Record<string, string>,\n  remove: readonly string[] = [],\n): string {\n  // Stamping a BOM-prefixed document drops the BOM. It sits above the header, so\n  // the promise about the body still holds — and leaving it would re-break the\n  // file for every parser anchored at position 0, including ours.\n  const md = stripBom(source);\n  const at = bounds(md);\n  const parsed = parseDocument(at === null ? \"\" : md.slice(at.start, at.end));\n  const editable = parsed.errors.length === 0 && (parsed.contents === null || isMap(parsed.contents));\n  const doc = editable ? parsed : parseDocument(\"\");\n\n  for (const [key, value] of Object.entries(fields)) doc.set(key, value);\n  // Guarded, not because a missing key is a problem — deleting one that is not\n  // there is a no-op — but because yaml's `Document.delete` THROWS (\"Expected\n  // a YAML collection as document contents\") when the document has no mapping\n  // at all: the empty header of a document that had none, and the replacement\n  // built for a header that would not parse. Both are states this writer\n  // reaches on purpose, and in both there is nothing to clear.\n  if (isMap(doc.contents)) for (const key of remove) doc.delete(key);\n  const yamlText = doc.toString();\n\n  if (at === null) return `---\\n${yamlText}---\\n\\n${md}`;\n  return md.slice(0, at.start) + yamlText + md.slice(at.end);\n}\n\n/**\n * The document's body, byte-exact: everything after the frontmatter block —\n * the closing `---` line and its newline belong to the HEADER, every byte\n * after them (blank lines included) is body. A document with no frontmatter is\n * all body. This is what `content_digest` hashes, and it deliberately does NOT\n * go through `parseFrontmatter` (whose `body` is trimmed for callers that want\n * text): the digest's writer and its checker must slice the same bytes, so\n * both go through here.\n */\nexport function rawBody(source: string): string {\n  const md = stripBom(source);\n  const at = bounds(md);\n  return at === null ? md : md.slice(at.bodyStart);\n}\n\n/**\n * Read a markdown file's frontmatter; a missing file reads as absent.\n *\n * Bytes in, decoded through `decodeDocument`, because `readFile(path, \"utf8\")`\n * turns a UTF-16 spec.md into mojibake whose opening `---` is no longer at\n * position 0 — so the header reads as ABSENT, and `status`, `owner` and\n * `sources` all come back missing over a file that spells every one of them.\n * The same blindness `stripBom` exists to stop, one encoding wider.\n *\n * The failure travels as a FLAG rather than an exception, which is how every\n * reader here degrades (`readOpenapi`'s `unreadable`) and is load-bearing at\n * exactly this call: this is the read behind the fleet ENUMERATION\n * (repo.ts `listServices`), so throwing would turn one PowerShell-saved file\n * into a `loam list` that reports nothing about the other 119 services.\n * Parsers never diagnose; a checker grades the flag.\n */\nexport async function readFrontmatter(path: string): Promise<Frontmatter> {\n  if (!existsSync(path)) return { present: false, malformed: false, data: {}, body: \"\" };\n  let text: string;\n  try {\n    text = decodeDocument(await readFile(path), path);\n  } catch (err) {\n    if (!(err instanceof NotUtf8DocumentError)) throw err;\n    return { present: false, malformed: false, unreadable: err.message, data: {}, body: \"\" };\n  }\n  return parseFrontmatter(text);\n}\n\n/** The statuses each kind of artifact may carry. */\nexport const SERVICE_STATUSES = [\"draft\", \"verified\"] as const;\nexport const FEATURE_STATUSES = [\"proposed\", \"in_progress\", \"built\", \"done\"] as const;\n\n/**\n * A document's prose with any leading frontmatter block dropped — what\n * `loam delta` and `loam context` print as a feature's intent.\n *\n * Moved verbatim from `commands/delta/slices.ts` when the context pack became\n * its second caller. It deliberately keeps its own, looser fence rule\n * (`\\n---` as a substring, not `bounds()`'s line-exact match) rather than\n * delegating to `parseFrontmatter(md).body`: the two agree on every header\n * loam writes, but the delta brief's output is pinned byte-for-byte by its\n * tests, and unifying the rules is a behaviour change to make deliberately,\n * not as a side effect of a move.\n */\nexport function stripFrontmatter(md: string): string {\n  if (!md.startsWith(\"---\")) return md;\n  const close = md.indexOf(\"\\n---\", 3);\n  if (close === -1) return md;\n  const nl = md.indexOf(\"\\n\", close + 1);\n  return nl === -1 ? \"\" : md.slice(nl + 1).trimStart();\n}\n"]}

package/dist/core/document/grammar/directives.js

@@ -0,0 +1,143 @@
+/**
+ * The requirement BODY-LINE grammar, and what a key nearly was.
+ *
+ * Split out of `commands/validate/service/specs.ts`, which reads and grades a
+ * service's two spec axes — a different subject: that module is about one
+ * service's documents, this one is about the shape of a requirement body
+ * wherever it appears. Nothing here touches the filesystem or knows what a
+ * service is, which is what lets it sit in `core/` beside the parser whose
+ * patterns it borrows.
+ *
+ * Its sibling is `../scenarios.ts`: same shape (requirements in, findings out,
+ * no I/O), one level down the document — that one grades a scenario's steps,
+ * this one grades the keys in the body above them.
+ */
+import {} from "../../vocabulary/report.js";
+import { BASED_ON_LINE_RE, CAPABILITY_LINE_RE, REALIZES_LINE_RE, REQUIREMENT_ID_LINE_RE, } from "../spec.js";
+/**
+ * Every body-line directive the requirement grammar recognises, as the patterns
+ * that recognise them.
+ *
+ * The REGEXES are the recognition half and they are not a copy: three are the
+ * exported constants `core/document/spec.ts` owns, and the rest are the same
+ * literals `core/document/parse.ts` matches with. Recognition therefore cannot
+ * drift into calling a real directive unknown.
+ *
+ * The NAMES below are the did-you-mean half, and they are the half that could
+ * drift — so `test/spec-unknown-directive.test.ts` asserts that every name here,
+ * spelled as a line, is matched by one of the patterns above it. A name that
+ * stops being a directive fails that test rather than going on being suggested.
+ */
+const DIRECTIVE_PATTERNS = [
+    REQUIREMENT_ID_LINE_RE,
+    BASED_ON_LINE_RE,
+    CAPABILITY_LINE_RE,
+    REALIZES_LINE_RE,
+    /^\s*Operations?:\s*(.+?)\s*$/i,
+    /^\s*Covers?:\s*(.+?)\s*$/i,
+    /^\s*Publishes?:\s*(.+?)\s*$/i,
+    /^\s*Consumes?:\s*(.+?)\s*$/i,
+    /^\s*Requires?:\s*(.+?)\s*$/i,
+];
+/** The canonical spelling of each directive — what a near miss is measured against. */
+export const DIRECTIVE_NAMES = [
+    "Requirement-ID",
+    "Based-On",
+    "Capabilities",
+    "Realizes",
+    "Operations",
+    "Covers",
+    "Publishes",
+    "Consumes",
+    "Requires",
+];
+/** A body line that LOOKS like a directive: a short capitalised key, a colon, a value. */
+const CANDIDATE_LINE_RE = /^\s*([A-Za-z][A-Za-z-]{2,30}):\s*\S/;
+/**
+ * A fenced block's opening or closing line — three or more backticks or
+ * tildes, optionally indented, optionally with an info string.
+ *
+ * A requirement body legitimately holds a fenced example, and inside one
+ * `Realises:` is a sample value rather than a misspelled directive. Grading it
+ * would make the check fire on documents that are exactly right, which is the
+ * one thing a near-miss guard may never do — a warning nobody can act on is
+ * worse than no warning. Tables need no equivalent: a `| Realises: |` cell
+ * begins with the pipe, so `CANDIDATE_LINE_RE` never matches it.
+ */
+const FENCE_LINE_RE = /^\s*(`{3,}|~{3,})/;
+/**
+ * Levenshtein distance, capped — a local one rather than `closeIds`, and the
+ * difference matters here.
+ *
+ * `closeIds` accepts a shared three-character prefix, which is right for ids
+ * drawn from a known vocabulary the author was aiming at. Applied to arbitrary
+ * prose keys it fires on words that merely start alike: `Context:` would be
+ * reported as a near miss for `Consumes:`, in a check whose whole value is that
+ * it does not cry wolf. Edit distance separates the two cleanly — `Context` is
+ * five edits from `Consumes`, `Realises` is one from `Realizes`.
+ */
+function editDistance(a, b) {
+    let prev = Array.from({ length: b.length + 1 }, (_, i) => i);
+    for (let i = 1; i <= a.length; i++) {
+        const row = [i];
+        for (let j = 1; j <= b.length; j++) {
+            row[j] = Math.min(prev[j] + 1, row[j - 1] + 1, prev[j - 1] + (a[i - 1] === b[j - 1] ? 0 : 1));
+        }
+        prev = row;
+    }
+    return prev[b.length];
+}
+/**
+ * `spec.unknown-directive` — a body line whose key is one or two characters
+ * away from a directive and is not one.
+ *
+ * THE ONE PLACE THE CORPUS IS QUIETER THAN IT LOOKS. Every join in the product
+ * is an existence check on a parsed value, so a line the parser did not
+ * recognise produces no value, no join, and therefore no finding: `Realises:`,
+ * `Capabilties:` and `Require:` all read as ordinary prose, and every check
+ * downstream stays green because there is nothing to fail. This is the same
+ * judgement `obligation.unknown` already makes one axis over — "a mistyped tag
+ * reads exactly like a rule" — applied to the keys themselves.
+ *
+ * A WARNING, not an error, and the threshold is deliberately mean. A body line
+ * is free prose and a fleet may legitimately write `Owner:` or `Context:` in
+ * one; the check only speaks when the key is within two edits of a directive,
+ * which is close enough that a typo is far likelier than a coincidence. It
+ * gates nothing.
+ */
+export function unknownDirectiveFindings(reqs, target) {
+    const findings = [];
+    for (const r of reqs) {
+        if (r.kind === "REMOVED")
+            continue;
+        let inFence = false;
+        for (const line of r.text) {
+            if (FENCE_LINE_RE.test(line)) {
+                inFence = !inFence;
+                continue;
+            }
+            if (inFence)
+                continue;
+            const candidate = CANDIDATE_LINE_RE.exec(line);
+            if (candidate === null)
+                continue;
+            if (DIRECTIVE_PATTERNS.some((re) => re.test(line)))
+                continue;
+            const key = candidate[1];
+            const near = DIRECTIVE_NAMES.filter((name) => editDistance(key.toLowerCase(), name.toLowerCase()) <= 2);
+            if (near.length === 0)
+                continue;
+            findings.push({
+                severity: "warn",
+                code: "spec.unknown-directive",
+                subject: target.subject,
+                message: `${target.where}: requirement '${r.name}' has a line beginning '${key}:', which is not a directive loam reads — ` +
+                    `did you mean ${near.map((n) => `\`${n}:\``).join(" or ")}? ` +
+                    "A key loam does not recognise is prose: the join it looks like simply does not exist, and every check over it " +
+                    "stays green because there is nothing to fail. Correct the spelling, or reword the line so it does not read as a directive",
+            });
+        }
+    }
+    return findings;
+}
+//# sourceMappingURL=directives.js.map

package/dist/core/document/grammar/directives.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"directives.js","sourceRoot":"","sources":["../../../../src/core/document/grammar/directives.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * The requirement BODY-LINE grammar, and what a key nearly was.\n *\n * Split out of `commands/validate/service/specs.ts`, which reads and grades a\n * service's two spec axes — a different subject: that module is about one\n * service's documents, this one is about the shape of a requirement body\n * wherever it appears. Nothing here touches the filesystem or knows what a\n * service is, which is what lets it sit in `core/` beside the parser whose\n * patterns it borrows.\n *\n * Its sibling is `../scenarios.ts`: same shape (requirements in, findings out,\n * no I/O), one level down the document — that one grades a scenario's steps,\n * this one grades the keys in the body above them.\n */\nimport { type Finding } from \"../../vocabulary/report.js\";\nimport {\n  BASED_ON_LINE_RE,\n  CAPABILITY_LINE_RE,\n  REALIZES_LINE_RE,\n  REQUIREMENT_ID_LINE_RE,\n  type Requirement,\n} from \"../spec.js\";\n\n/**\n * Every body-line directive the requirement grammar recognises, as the patterns\n * that recognise them.\n *\n * The REGEXES are the recognition half and they are not a copy: three are the\n * exported constants `core/document/spec.ts` owns, and the rest are the same\n * literals `core/document/parse.ts` matches with. Recognition therefore cannot\n * drift into calling a real directive unknown.\n *\n * The NAMES below are the did-you-mean half, and they are the half that could\n * drift — so `test/spec-unknown-directive.test.ts` asserts that every name here,\n * spelled as a line, is matched by one of the patterns above it. A name that\n * stops being a directive fails that test rather than going on being suggested.\n */\nconst DIRECTIVE_PATTERNS: readonly RegExp[] = [\n  REQUIREMENT_ID_LINE_RE,\n  BASED_ON_LINE_RE,\n  CAPABILITY_LINE_RE,\n  REALIZES_LINE_RE,\n  /^\\s*Operations?:\\s*(.+?)\\s*$/i,\n  /^\\s*Covers?:\\s*(.+?)\\s*$/i,\n  /^\\s*Publishes?:\\s*(.+?)\\s*$/i,\n  /^\\s*Consumes?:\\s*(.+?)\\s*$/i,\n  /^\\s*Requires?:\\s*(.+?)\\s*$/i,\n];\n\n/** The canonical spelling of each directive — what a near miss is measured against. */\nexport const DIRECTIVE_NAMES: readonly string[] = [\n  \"Requirement-ID\",\n  \"Based-On\",\n  \"Capabilities\",\n  \"Realizes\",\n  \"Operations\",\n  \"Covers\",\n  \"Publishes\",\n  \"Consumes\",\n  \"Requires\",\n];\n\n/** A body line that LOOKS like a directive: a short capitalised key, a colon, a value. */\nconst CANDIDATE_LINE_RE = /^\\s*([A-Za-z][A-Za-z-]{2,30}):\\s*\\S/;\n\n/**\n * A fenced block's opening or closing line — three or more backticks or\n * tildes, optionally indented, optionally with an info string.\n *\n * A requirement body legitimately holds a fenced example, and inside one\n * `Realises:` is a sample value rather than a misspelled directive. Grading it\n * would make the check fire on documents that are exactly right, which is the\n * one thing a near-miss guard may never do — a warning nobody can act on is\n * worse than no warning. Tables need no equivalent: a `| Realises: |` cell\n * begins with the pipe, so `CANDIDATE_LINE_RE` never matches it.\n */\nconst FENCE_LINE_RE = /^\\s*(`{3,}|~{3,})/;\n\n/**\n * Levenshtein distance, capped — a local one rather than `closeIds`, and the\n * difference matters here.\n *\n * `closeIds` accepts a shared three-character prefix, which is right for ids\n * drawn from a known vocabulary the author was aiming at. Applied to arbitrary\n * prose keys it fires on words that merely start alike: `Context:` would be\n * reported as a near miss for `Consumes:`, in a check whose whole value is that\n * it does not cry wolf. Edit distance separates the two cleanly — `Context` is\n * five edits from `Consumes`, `Realises` is one from `Realizes`.\n */\nfunction editDistance(a: string, b: string): number {\n  let prev = Array.from({ length: b.length + 1 }, (_, i) => i);\n  for (let i = 1; i <= a.length; i++) {\n    const row = [i];\n    for (let j = 1; j <= b.length; j++) {\n      row[j] = Math.min(\n        prev[j]! + 1,\n        row[j - 1]! + 1,\n        prev[j - 1]! + (a[i - 1] === b[j - 1] ? 0 : 1),\n      );\n    }\n    prev = row;\n  }\n  return prev[b.length]!;\n}\n\n/**\n * `spec.unknown-directive` — a body line whose key is one or two characters\n * away from a directive and is not one.\n *\n * THE ONE PLACE THE CORPUS IS QUIETER THAN IT LOOKS. Every join in the product\n * is an existence check on a parsed value, so a line the parser did not\n * recognise produces no value, no join, and therefore no finding: `Realises:`,\n * `Capabilties:` and `Require:` all read as ordinary prose, and every check\n * downstream stays green because there is nothing to fail. This is the same\n * judgement `obligation.unknown` already makes one axis over — \"a mistyped tag\n * reads exactly like a rule\" — applied to the keys themselves.\n *\n * A WARNING, not an error, and the threshold is deliberately mean. A body line\n * is free prose and a fleet may legitimately write `Owner:` or `Context:` in\n * one; the check only speaks when the key is within two edits of a directive,\n * which is close enough that a typo is far likelier than a coincidence. It\n * gates nothing.\n */\nexport function unknownDirectiveFindings(\n  reqs: readonly Requirement[],\n  target: { where: string; subject: string },\n): Finding[] {\n  const findings: Finding[] = [];\n  for (const r of reqs) {\n    if (r.kind === \"REMOVED\") continue;\n    let inFence = false;\n    for (const line of r.text) {\n      if (FENCE_LINE_RE.test(line)) {\n        inFence = !inFence;\n        continue;\n      }\n      if (inFence) continue;\n      const candidate = CANDIDATE_LINE_RE.exec(line);\n      if (candidate === null) continue;\n      if (DIRECTIVE_PATTERNS.some((re) => re.test(line))) continue;\n      const key = candidate[1]!;\n      const near = DIRECTIVE_NAMES.filter(\n        (name) => editDistance(key.toLowerCase(), name.toLowerCase()) <= 2,\n      );\n      if (near.length === 0) continue;\n      findings.push({\n        severity: \"warn\",\n        code: \"spec.unknown-directive\",\n        subject: target.subject,\n        message:\n          `${target.where}: requirement '${r.name}' has a line beginning '${key}:', which is not a directive loam reads — ` +\n          `did you mean ${near.map((n) => `\\`${n}:\\``).join(\" or \")}? ` +\n          \"A key loam does not recognise is prose: the join it looks like simply does not exist, and every check over it \" +\n          \"stays green because there is nothing to fail. Correct the spelling, or reword the line so it does not read as a directive\",\n      });\n    }\n  }\n  return findings;\n}\n"]}

package/dist/core/document/parse.js

@@ -0,0 +1,263 @@
+/**
+ * Markdown in: headings, fences, and the one `## Requirements` cut point.
+ *
+ * The cut point is spelled once here on purpose. The archive cut, archive's
+ * stray-requirement guard and the delta-shape exemption used to spell the same
+ * invariant three different ways, and one of them was a PREFIX match that also
+ * hit `## Requirements Extra`.
+ *
+ * Fence tracking is why this is not a set of regexes at the call sites: a
+ * `### Requirement:` inside a fenced code block is prose about a requirement,
+ * not one, and every heading walk here has to agree about that.
+ */
+import { readFile } from "node:fs/promises";
+import { decodeDocument } from "../kernel/document-bytes.js";
+import { fenceTracker } from "../kernel/fences.js";
+import { BASED_ON_LINE_RE, CAPABILITY_LINE_RE, KIND_RE, REALIZES_LINE_RE, REQUIREMENT_ID_LINE_RE, } from "./spec.js";
+const REQ_RE = /^###\s+Requirement:\s*(.+?)\s*$/;
+const SCN_RE = /^####\s+Scenario:\s*(.+?)\s*$/;
+/**
+ * THE requirements section: the one H2 a living spec keeps its requirements
+ * under, the one section `loam archive` rewrites, and the one heading a delta
+ * may legally quote the living state beneath. One definition on purpose — the
+ * archive cut point, archive's stray-requirement guard, and the delta-shape
+ * exemption (core/delta/document.ts) used to spell this invariant three different ways,
+ * and the cut point's substring `indexOf("\n## Requirements")` was a PREFIX
+ * match that also hit `## Requirements Extra`. Full-line match on a trimmed
+ * heading, with KIND_RE's case and interior-whitespace tolerance.
+ */
+const REQUIREMENTS_SECTION_RE = /^##\s+Requirements\s*$/i;
+/** Is this H2 heading line (as sectionHeadings/`Requirement.section` spell it) the `## Requirements` heading? */
+export function isRequirementsHeading(heading) {
+    return REQUIREMENTS_SECTION_RE.test(heading.trim());
+}
+/**
+ * Strip a leading UTF-8 BOM (U+FEFF), which editors on Windows write unasked.
+ *
+ * It has to happen here, at the two functions that take raw markdown, rather than
+ * at each `readFile` call: those are spread across half the commands, so any one of
+ * them could forget, and the failure is invisible. One byte was enough to void an
+ * entire delta — `KIND_RE` is anchored `^##`, delta files routinely open with
+ * `## MODIFIED Requirements` on line 1, and behind a BOM that line stopped being a
+ * heading, so every requirement in the file fell back to BASE and
+ * `applyRequirementDelta` skips BASE. Archive merged nothing and said nothing.
+ * OpenSpec's own reader strips it for exactly this reason.
+ *
+ * Only at position 0: elsewhere U+FEFF is a zero-width no-break space and belongs
+ * to the author's text.
+ */
+function stripBom(md) {
+    return md.charCodeAt(0) === 0xfeff ? md.slice(1) : md;
+}
+/** Every H2 heading outside a fenced block, with its 1-based line number. */
+export function sectionHeadings(md) {
+    const fenced = fenceTracker();
+    const out = [];
+    stripBom(md).split(/\r?\n/).forEach((line, i) => {
+        if (fenced(line))
+            return;
+        if (/^##\s+/.test(line) && !line.startsWith("###"))
+            out.push({ text: line.trim(), line: i + 1 });
+    });
+    return out;
+}
+/**
+ * Split a living spec around its requirements RUN — the stretch of
+ * `### Requirement:` blocks inside the `## Requirements` section — so a merge
+ * can rewrite exactly that and nothing else. All three slices reassemble the
+ * input byte-for-byte (`head + run + tail === text`):
+ *
+ * - `head` — everything before the first requirement in the section: the
+ *   intro, the heading line itself, any prose under the heading.
+ * - `run`  — from the first `### Requirement:` line to the section's end (the
+ *   next `## ` heading, or EOF). Empty when the section holds no requirements.
+ * - `tail` — everything from the section's end onward.
+ *
+ * Returns null when the document has no `## Requirements` heading at all.
+ * Only the FIRST matching heading opens the section; a caller that must not
+ * lose content behind a duplicate (archive) counts matches via
+ * sectionHeadings() and refuses. Heading detection matches parseRequirements:
+ * fenced lines are never structure, and a leading BOM hides no heading — but
+ * the slices themselves are raw bytes, BOM and CRLF included.
+ */
+export function splitRequirementsSection(text) {
+    const fenced = fenceTracker();
+    let inSection = false;
+    let sectionStart = -1;
+    let runStart = -1;
+    let sectionEnd = text.length;
+    let offset = 0;
+    while (offset < text.length) {
+        const nl = text.indexOf("\n", offset);
+        const lineEnd = nl === -1 ? text.length : nl + 1;
+        let line = text.slice(offset, nl === -1 ? text.length : nl);
+        if (line.endsWith("\r"))
+            line = line.slice(0, -1);
+        // Position 0 only, mirroring stripBom: elsewhere U+FEFF is content.
+        if (offset === 0 && line.charCodeAt(0) === 0xfeff)
+            line = line.slice(1);
+        if (!fenced(line)) {
+            if (/^##\s+/.test(line) && !line.startsWith("###")) {
+                if (inSection) {
+                    sectionEnd = offset;
+                    inSection = false;
+                }
+                else if (sectionStart === -1 && isRequirementsHeading(line)) {
+                    sectionStart = offset;
+                    inSection = true;
+                }
+            }
+            else if (inSection && runStart === -1 && REQ_RE.test(line)) {
+                runStart = offset;
+            }
+        }
+        offset = lineEnd;
+    }
+    if (sectionStart === -1)
+        return null;
+    const cut = runStart === -1 ? sectionEnd : runStart;
+    return { head: text.slice(0, cut), run: text.slice(cut, sectionEnd), tail: text.slice(sectionEnd) };
+}
+/**
+ * A requirement document from disk as text — decoded, or refused by name.
+ *
+ * The read that belongs with the parser, because `readFile(path, "utf8")` and
+ * `parseRequirements` together are a trap: a UTF-16 spec.md decodes to a string
+ * in which no line matches `^###\s+Requirement:`, so the parser returns [] and
+ * the document grades as an empty baseline instead of an unreadable one. Every
+ * question loam asks of a spec — is it covered, does the delta merge, what does
+ * the C4 spine touch — is then answered about a file nobody read.
+ *
+ * It THROWS (`NotUtf8DocumentError`, which names the path), unlike
+ * `readFrontmatter` next door, because the two failures are not the same
+ * failure. Frontmatter is read by the fleet enumeration, where one bad file
+ * must not cost the other 119 services, so there it is a flag. A requirement
+ * document is read by ONE target, and the caller is the only one who knows what
+ * to do about it: a read-only command turns it into a finding on that target
+ * (validate's `guarded`, which names the file and keeps grading the rest), a
+ * command that writes refuses outright rather than computing over mojibake.
+ */
+export async function readRequirementsDocument(path) {
+    return decodeDocument(await readFile(path), path);
+}
+/** Parse all requirements (with their scenarios and delta kind) from a markdown doc. */
+export function parseRequirements(md) {
+    const out = [];
+    let kind = "BASE";
+    let section;
+    let req = null;
+    let scn = null;
+    const fenced = fenceTracker();
+    for (const [index, line] of stripBom(md).split(/\r?\n/).entries()) {
+        if (fenced(line)) {
+            // Fenced content, marker included: body of whatever is open, never structure.
+            if (scn)
+                scn.lines.push(line);
+            else if (req)
+                req.text.push(line);
+            continue;
+        }
+        // Any H2 heading ends the current requirement/scenario capture — section prose
+        // must not leak into the previous scenario's body.
+        if (/^##\s+/.test(line) && !line.startsWith("###")) {
+            req = null;
+            scn = null;
+            section = line.trim();
+            const mk = KIND_RE.exec(line);
+            // A non-delta H2 (## Notes, ## Requirements…) starts an unrelated section:
+            // requirements under it are plain BASE, not part of a stale delta section.
+            kind = mk ? mk[1].toUpperCase() : "BASE";
+            continue;
+        }
+        const mr = REQ_RE.exec(line);
+        if (mr) {
+            req = {
+                kind,
+                name: mr[1],
+                text: [],
+                operations: [],
+                covers: [],
+                publishes: [],
+                consumes: [],
+                requires: [],
+                capabilities: [],
+                realizes: [],
+                scenarios: [],
+                section,
+                line: index + 1,
+            };
+            out.push(req);
+            scn = null;
+            continue;
+        }
+        const ms = SCN_RE.exec(line);
+        if (ms && req) {
+            scn = { name: ms[1], lines: [] };
+            req.scenarios.push(scn);
+            continue;
+        }
+        if (scn) {
+            scn.lines.push(line);
+        }
+        else if (req) {
+            req.text.push(line);
+            const mi = REQUIREMENT_ID_LINE_RE.exec(line);
+            if (mi)
+                req.id = mi[1].trim();
+            // Same keep-last quirk as Operations:/Covers: below — a repeated line is
+            // a document problem, reported as one (`delta.baseline-invalid`), never
+            // resolved differently by whoever happens to be reading.
+            const mb = BASED_ON_LINE_RE.exec(line);
+            if (mb)
+                req.basedOn = mb[1].trim();
+            const mo = /^\s*Operations?:\s*(.+?)\s*$/i.exec(line);
+            if (mo)
+                req.operations = mo[1].split(",").map((s) => s.trim()).filter((s) => s.length > 0);
+            // The Covers: mirror — same placement (requirement body, not a scenario),
+            // same comma grammar, and deliberately the same quirk: a second line
+            // REPLACES the first (assignment, not append), so the two lists can never
+            // drift apart in how they read a repeated line.
+            const mc = /^\s*Covers?:\s*(.+?)\s*$/i.exec(line);
+            if (mc)
+                req.covers = mc[1].split(",").map((s) => s.trim()).filter((s) => s.length > 0);
+            // The event axis, same grammar and the same keep-last quirk again. Note
+            // what is NOT happening here: the line stays in `req.text` like every
+            // other body line (the push above is unconditional), so it round-trips
+            // through `serializeRequirements` and rides inside `requirementDigest`
+            // exactly as `Operations:` does. That is what makes this parse purely
+            // additive — no living document's digest moves, and no `Based-On:` pin
+            // goes stale because loam learned to read one more line.
+            const mp = /^\s*Publishes?:\s*(.+?)\s*$/i.exec(line);
+            if (mp)
+                req.publishes = mp[1].split(",").map((s) => s.trim()).filter((s) => s.length > 0);
+            const mcon = /^\s*Consumes?:\s*(.+?)\s*$/i.exec(line);
+            if (mcon)
+                req.consumes = mcon[1].split(",").map((s) => s.trim()).filter((s) => s.length > 0);
+            // The authorization axis. Same grammar, same keep-last quirk, same purely
+            // additive parse — the line rides in `req.text` and therefore inside
+            // `requirementDigest`, so no living document moves because loam learned
+            // to read it.
+            const mreq = /^\s*Requires?:\s*(.+?)\s*$/i.exec(line);
+            if (mreq)
+                req.requires = mreq[1].split(",").map((s) => s.trim()).filter((s) => s.length > 0);
+            // The capability axis. Same grammar, same keep-last quirk, same purely
+            // additive parse as Requires: above — but note the OPT-IN differs: the
+            // vocabulary FILE (architecture/capabilities.yaml) is the opt-in for this
+            // axis, not the line, so entries parsed here grade as nothing at all
+            // until a fleet writes that file (core/capabilities/findings.ts).
+            const mcap = CAPABILITY_LINE_RE.exec(line);
+            if (mcap)
+                req.capabilities = mcap[1].split(",").map((s) => s.trim()).filter((s) => s.length > 0);
+            // The join INTO the authored business tree: `<capability-id>#<Requirement-ID>`
+            // entries, same comma grammar and same keep-last quirk as every line
+            // above. Split into its two halves nowhere near here —
+            // `core/capabilities/realizes/join.ts` owns that, because the rollup and
+            // the grades must not be able to disagree about where the separator is.
+            const mrl = REALIZES_LINE_RE.exec(line);
+            if (mrl)
+                req.realizes = mrl[1].split(",").map((s) => s.trim()).filter((s) => s.length > 0);
+        }
+    }
+    return out;
+}
+//# sourceMappingURL=parse.js.map

package/dist/core/document/parse.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"parse.js","sourceRoot":"","sources":["../../../src/core/document/parse.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Markdown in: headings, fences, and the one `## Requirements` cut point.\n *\n * The cut point is spelled once here on purpose. The archive cut, archive's\n * stray-requirement guard and the delta-shape exemption used to spell the same\n * invariant three different ways, and one of them was a PREFIX match that also\n * hit `## Requirements Extra`.\n *\n * Fence tracking is why this is not a set of regexes at the call sites: a\n * `### Requirement:` inside a fenced code block is prose about a requirement,\n * not one, and every heading walk here has to agree about that.\n */\nimport { readFile } from \"node:fs/promises\";\nimport { decodeDocument } from \"../kernel/document-bytes.js\";\nimport { fenceTracker } from \"../kernel/fences.js\";\nimport {\n  BASED_ON_LINE_RE, CAPABILITY_LINE_RE, KIND_RE, REALIZES_LINE_RE, REQUIREMENT_ID_LINE_RE,\n  type DeltaKind, type Requirement, type Scenario,\n} from \"./spec.js\";\n\nconst REQ_RE = /^###\\s+Requirement:\\s*(.+?)\\s*$/;\nconst SCN_RE = /^####\\s+Scenario:\\s*(.+?)\\s*$/;\n\n/**\n * THE requirements section: the one H2 a living spec keeps its requirements\n * under, the one section `loam archive` rewrites, and the one heading a delta\n * may legally quote the living state beneath. One definition on purpose — the\n * archive cut point, archive's stray-requirement guard, and the delta-shape\n * exemption (core/delta/document.ts) used to spell this invariant three different ways,\n * and the cut point's substring `indexOf(\"\\n## Requirements\")` was a PREFIX\n * match that also hit `## Requirements Extra`. Full-line match on a trimmed\n * heading, with KIND_RE's case and interior-whitespace tolerance.\n */\nconst REQUIREMENTS_SECTION_RE = /^##\\s+Requirements\\s*$/i;\n\n/** Is this H2 heading line (as sectionHeadings/`Requirement.section` spell it) the `## Requirements` heading? */\nexport function isRequirementsHeading(heading: string): boolean {\n  return REQUIREMENTS_SECTION_RE.test(heading.trim());\n}\n\n/**\n * Strip a leading UTF-8 BOM (U+FEFF), which editors on Windows write unasked.\n *\n * It has to happen here, at the two functions that take raw markdown, rather than\n * at each `readFile` call: those are spread across half the commands, so any one of\n * them could forget, and the failure is invisible. One byte was enough to void an\n * entire delta — `KIND_RE` is anchored `^##`, delta files routinely open with\n * `## MODIFIED Requirements` on line 1, and behind a BOM that line stopped being a\n * heading, so every requirement in the file fell back to BASE and\n * `applyRequirementDelta` skips BASE. Archive merged nothing and said nothing.\n * OpenSpec's own reader strips it for exactly this reason.\n *\n * Only at position 0: elsewhere U+FEFF is a zero-width no-break space and belongs\n * to the author's text.\n */\nfunction stripBom(md: string): string {\n  return md.charCodeAt(0) === 0xfeff ? md.slice(1) : md;\n}\n\n/** Every H2 heading outside a fenced block, with its 1-based line number. */\nexport function sectionHeadings(md: string): Array<{ text: string; line: number }> {\n  const fenced = fenceTracker();\n  const out: Array<{ text: string; line: number }> = [];\n  stripBom(md).split(/\\r?\\n/).forEach((line, i) => {\n    if (fenced(line)) return;\n    if (/^##\\s+/.test(line) && !line.startsWith(\"###\")) out.push({ text: line.trim(), line: i + 1 });\n  });\n  return out;\n}\n\n/**\n * Split a living spec around its requirements RUN — the stretch of\n * `### Requirement:` blocks inside the `## Requirements` section — so a merge\n * can rewrite exactly that and nothing else. All three slices reassemble the\n * input byte-for-byte (`head + run + tail === text`):\n *\n * - `head` — everything before the first requirement in the section: the\n *   intro, the heading line itself, any prose under the heading.\n * - `run`  — from the first `### Requirement:` line to the section's end (the\n *   next `## ` heading, or EOF). Empty when the section holds no requirements.\n * - `tail` — everything from the section's end onward.\n *\n * Returns null when the document has no `## Requirements` heading at all.\n * Only the FIRST matching heading opens the section; a caller that must not\n * lose content behind a duplicate (archive) counts matches via\n * sectionHeadings() and refuses. Heading detection matches parseRequirements:\n * fenced lines are never structure, and a leading BOM hides no heading — but\n * the slices themselves are raw bytes, BOM and CRLF included.\n */\nexport function splitRequirementsSection(\n  text: string,\n): { head: string; run: string; tail: string } | null {\n  const fenced = fenceTracker();\n  let inSection = false;\n  let sectionStart = -1;\n  let runStart = -1;\n  let sectionEnd = text.length;\n  let offset = 0;\n  while (offset < text.length) {\n    const nl = text.indexOf(\"\\n\", offset);\n    const lineEnd = nl === -1 ? text.length : nl + 1;\n    let line = text.slice(offset, nl === -1 ? text.length : nl);\n    if (line.endsWith(\"\\r\")) line = line.slice(0, -1);\n    // Position 0 only, mirroring stripBom: elsewhere U+FEFF is content.\n    if (offset === 0 && line.charCodeAt(0) === 0xfeff) line = line.slice(1);\n    if (!fenced(line)) {\n      if (/^##\\s+/.test(line) && !line.startsWith(\"###\")) {\n        if (inSection) {\n          sectionEnd = offset;\n          inSection = false;\n        } else if (sectionStart === -1 && isRequirementsHeading(line)) {\n          sectionStart = offset;\n          inSection = true;\n        }\n      } else if (inSection && runStart === -1 && REQ_RE.test(line)) {\n        runStart = offset;\n      }\n    }\n    offset = lineEnd;\n  }\n  if (sectionStart === -1) return null;\n  const cut = runStart === -1 ? sectionEnd : runStart;\n  return { head: text.slice(0, cut), run: text.slice(cut, sectionEnd), tail: text.slice(sectionEnd) };\n}\n\n/**\n * A requirement document from disk as text — decoded, or refused by name.\n *\n * The read that belongs with the parser, because `readFile(path, \"utf8\")` and\n * `parseRequirements` together are a trap: a UTF-16 spec.md decodes to a string\n * in which no line matches `^###\\s+Requirement:`, so the parser returns [] and\n * the document grades as an empty baseline instead of an unreadable one. Every\n * question loam asks of a spec — is it covered, does the delta merge, what does\n * the C4 spine touch — is then answered about a file nobody read.\n *\n * It THROWS (`NotUtf8DocumentError`, which names the path), unlike\n * `readFrontmatter` next door, because the two failures are not the same\n * failure. Frontmatter is read by the fleet enumeration, where one bad file\n * must not cost the other 119 services, so there it is a flag. A requirement\n * document is read by ONE target, and the caller is the only one who knows what\n * to do about it: a read-only command turns it into a finding on that target\n * (validate's `guarded`, which names the file and keeps grading the rest), a\n * command that writes refuses outright rather than computing over mojibake.\n */\nexport async function readRequirementsDocument(path: string): Promise<string> {\n  return decodeDocument(await readFile(path), path);\n}\n\n/** Parse all requirements (with their scenarios and delta kind) from a markdown doc. */\nexport function parseRequirements(md: string): Requirement[] {\n  const out: Requirement[] = [];\n  let kind: DeltaKind = \"BASE\";\n  let section: string | undefined;\n  let req: Requirement | null = null;\n  let scn: Scenario | null = null;\n  const fenced = fenceTracker();\n\n  for (const [index, line] of stripBom(md).split(/\\r?\\n/).entries()) {\n    if (fenced(line)) {\n      // Fenced content, marker included: body of whatever is open, never structure.\n      if (scn) scn.lines.push(line);\n      else if (req) req.text.push(line);\n      continue;\n    }\n    // Any H2 heading ends the current requirement/scenario capture — section prose\n    // must not leak into the previous scenario's body.\n    if (/^##\\s+/.test(line) && !line.startsWith(\"###\")) {\n      req = null;\n      scn = null;\n      section = line.trim();\n      const mk = KIND_RE.exec(line);\n      // A non-delta H2 (## Notes, ## Requirements…) starts an unrelated section:\n      // requirements under it are plain BASE, not part of a stale delta section.\n      kind = mk ? (mk[1]!.toUpperCase() as DeltaKind) : \"BASE\";\n      continue;\n    }\n    const mr = REQ_RE.exec(line);\n    if (mr) {\n      req = {\n        kind,\n        name: mr[1]!,\n        text: [],\n        operations: [],\n        covers: [],\n        publishes: [],\n        consumes: [],\n        requires: [],\n        capabilities: [],\n        realizes: [],\n        scenarios: [],\n        section,\n        line: index + 1,\n      };\n      out.push(req);\n      scn = null;\n      continue;\n    }\n    const ms = SCN_RE.exec(line);\n    if (ms && req) {\n      scn = { name: ms[1]!, lines: [] };\n      req.scenarios.push(scn);\n      continue;\n    }\n    if (scn) {\n      scn.lines.push(line);\n    } else if (req) {\n      req.text.push(line);\n      const mi = REQUIREMENT_ID_LINE_RE.exec(line);\n      if (mi) req.id = mi[1]!.trim();\n      // Same keep-last quirk as Operations:/Covers: below — a repeated line is\n      // a document problem, reported as one (`delta.baseline-invalid`), never\n      // resolved differently by whoever happens to be reading.\n      const mb = BASED_ON_LINE_RE.exec(line);\n      if (mb) req.basedOn = mb[1]!.trim();\n      const mo = /^\\s*Operations?:\\s*(.+?)\\s*$/i.exec(line);\n      if (mo) req.operations = mo[1]!.split(\",\").map((s) => s.trim()).filter((s) => s.length > 0);\n      // The Covers: mirror — same placement (requirement body, not a scenario),\n      // same comma grammar, and deliberately the same quirk: a second line\n      // REPLACES the first (assignment, not append), so the two lists can never\n      // drift apart in how they read a repeated line.\n      const mc = /^\\s*Covers?:\\s*(.+?)\\s*$/i.exec(line);\n      if (mc) req.covers = mc[1]!.split(\",\").map((s) => s.trim()).filter((s) => s.length > 0);\n      // The event axis, same grammar and the same keep-last quirk again. Note\n      // what is NOT happening here: the line stays in `req.text` like every\n      // other body line (the push above is unconditional), so it round-trips\n      // through `serializeRequirements` and rides inside `requirementDigest`\n      // exactly as `Operations:` does. That is what makes this parse purely\n      // additive — no living document's digest moves, and no `Based-On:` pin\n      // goes stale because loam learned to read one more line.\n      const mp = /^\\s*Publishes?:\\s*(.+?)\\s*$/i.exec(line);\n      if (mp) req.publishes = mp[1]!.split(\",\").map((s) => s.trim()).filter((s) => s.length > 0);\n      const mcon = /^\\s*Consumes?:\\s*(.+?)\\s*$/i.exec(line);\n      if (mcon) req.consumes = mcon[1]!.split(\",\").map((s) => s.trim()).filter((s) => s.length > 0);\n      // The authorization axis. Same grammar, same keep-last quirk, same purely\n      // additive parse — the line rides in `req.text` and therefore inside\n      // `requirementDigest`, so no living document moves because loam learned\n      // to read it.\n      const mreq = /^\\s*Requires?:\\s*(.+?)\\s*$/i.exec(line);\n      if (mreq) req.requires = mreq[1]!.split(\",\").map((s) => s.trim()).filter((s) => s.length > 0);\n      // The capability axis. Same grammar, same keep-last quirk, same purely\n      // additive parse as Requires: above — but note the OPT-IN differs: the\n      // vocabulary FILE (architecture/capabilities.yaml) is the opt-in for this\n      // axis, not the line, so entries parsed here grade as nothing at all\n      // until a fleet writes that file (core/capabilities/findings.ts).\n      const mcap = CAPABILITY_LINE_RE.exec(line);\n      if (mcap) req.capabilities = mcap[1]!.split(\",\").map((s) => s.trim()).filter((s) => s.length > 0);\n      // The join INTO the authored business tree: `<capability-id>#<Requirement-ID>`\n      // entries, same comma grammar and same keep-last quirk as every line\n      // above. Split into its two halves nowhere near here —\n      // `core/capabilities/realizes/join.ts` owns that, because the rollup and\n      // the grades must not be able to disagree about where the separator is.\n      const mrl = REALIZES_LINE_RE.exec(line);\n      if (mrl) req.realizes = mrl[1]!.split(\",\").map((s) => s.trim()).filter((s) => s.length > 0);\n    }\n  }\n\n  return out;\n}\n"]}