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

package/dist/core/document/scenarios.js

@@ -0,0 +1,221 @@
+/**
+ * What a requirement's scenarios are MISSING, and where they contradict
+ * themselves — the coverage and shape questions `validate` asks of every spec.
+ *
+ * Separate from `./parse.ts` because these grade a parsed document rather than
+ * produce one, and separate from `./spec.ts` because they answer to
+ * `vocabulary/report.ts`: a stepless scenario is a Finding with a subject and a
+ * label, and that shape belongs to the report, not to the requirement.
+ */
+import { scenarioGherkin } from "../vocabulary/steps.js";
+import {} from "./spec.js";
+/** Requirements with no scenario — the OpenSpec coverage rule (every requirement needs ≥1). */
+export function requirementsMissingScenarios(reqs) {
+    return reqs.filter((r) => r.kind !== "REMOVED" && r.scenarios.length === 0);
+}
+/**
+ * Scenarios that satisfy the coverage rule above and test nothing.
+ *
+ * `requirementsMissingScenarios` counts HEADINGS, so a `#### Scenario:` with no
+ * recognizable Given/When/Then line satisfied the fleet gate's coverage claim
+ * outright — and it is not a hypothetical shape: it is what `loam new`
+ * scaffolds and what an agent writes when it puts the criteria in prose.
+ * Downstream the same emptiness is fatal twice over: cucumber runs a stepless
+ * scenario vacuously green, and `loam verify --results` can never confirm it.
+ *
+ * The detector is `loam gherkin`'s own — `scenarioGherkin` decides what a step
+ * IS, and a second opinion here would mean the gate and the emitted suite could
+ * disagree about whether a scenario has any. That import is the one place these
+ * two modules are circular (gherkin.ts parses requirements); both sides export
+ * only function declarations, which are hoisted, so neither evaluation order
+ * can observe a half-built module.
+ */
+export function steplessScenarios(reqs) {
+    const out = [];
+    for (const r of reqs) {
+        if (r.kind === "REMOVED")
+            continue;
+        for (const s of r.scenarios) {
+            if (scenarioGherkin(s.lines).steps.length === 0)
+                out.push({ requirement: r.name, scenario: s.name });
+        }
+    }
+    return out;
+}
+/**
+ * The stepless half of the coverage check, as findings — the missing-scenario
+ * half stays where it is (`requirementsMissingScenarios`), because the two are
+ * different states with different fixes: one requirement owes acceptance
+ * criteria, the other owes STEPS in criteria somebody has already written.
+ *
+ * `label` is the coverage check's own label (`payment-service: requirements`),
+ * so both halves of one document name it the same way.
+ */
+export function steplessFindings(label, subject, reqs) {
+    const bare = steplessScenarios(reqs);
+    if (bare.length === 0)
+        return [];
+    return [
+        {
+            severity: "error",
+            code: "requirements.stepless-scenario",
+            subject,
+            message: `${label}: ${bare.length} scenario(s) have a heading and no recognizable steps — ` +
+                `they satisfy the coverage rule and test nothing. Cucumber runs a stepless scenario vacuously green and ` +
+                `\`loam verify --results\` can never confirm it. Write the body as \`- **Given/When/Then**\` bullets.`,
+            details: bare.map((s) => `${s.requirement} — ${s.scenario}`),
+            text: { detailPrefix: "- " },
+        },
+    ];
+}
+/**
+ * Scenarios that have steps and assert NOTHING — a body of Given and When with
+ * no Then anywhere in it.
+ *
+ * The third state, and the one that survives both checks above: the requirement
+ * has a scenario, the scenario has steps, and the run can only ever confirm that
+ * the arrangement did not throw. `And`/`But` are continuations, so their meaning
+ * is decided by the keyword they follow — with no `Then` in the body there is
+ * nothing for them to continue but the setup.
+ *
+ * It matters more the more evidence rests on the suite. A stepless scenario is
+ * at least visible as an empty body; this one reads like a real test, emits real
+ * steps, runs green, and answers a `scenario.tested` claim to the same standard
+ * as a scenario that checks twenty things. Under a runner-neutral answer sheet —
+ * one `{digest, status}` entry, no steps to count — this document-side check is
+ * the only thing left that can tell the two apart.
+ */
+export function assertionlessScenarios(reqs) {
+    const out = [];
+    for (const r of reqs) {
+        if (r.kind === "REMOVED")
+            continue;
+        for (const s of r.scenarios) {
+            const { steps } = scenarioGherkin(s.lines);
+            // Disjoint from stepless by construction: a body with no steps at all is
+            // that finding's, and reporting one scenario under both codes would offer
+            // two fixes for one defect.
+            if (steps.length > 0 && !steps.some((st) => /^Then\b/.test(st.text))) {
+                out.push({ requirement: r.name, scenario: s.name });
+            }
+        }
+    }
+    return out;
+}
+const PLACEHOLDER_RE = /<([^<>\s]+)>/g;
+/**
+ * Every `<placeholder>` a scenario's steps reach for, arguments included.
+ *
+ * Docstrings and data tables are scanned too because cucumber substitutes into
+ * them: `<fee>` inside a request payload is a real reference, and a check that
+ * read only the step lines would call its column unreferenced and invite the
+ * author to delete the column the payload depends on.
+ */
+function placeholdersUsed(steps) {
+    const used = new Set();
+    const scan = (text) => {
+        for (const m of text.matchAll(PLACEHOLDER_RE))
+            used.add(m[1]);
+    };
+    for (const st of steps) {
+        scan(st.text);
+        for (const l of st.docstring?.lines ?? [])
+            scan(l);
+        for (const row of st.table ?? [])
+            for (const cell of row)
+                scan(cell);
+    }
+    return used;
+}
+/**
+ * Scenarios whose `Examples` header and `<placeholders>` disagree.
+ *
+ * Only scenarios that HAVE an Examples table are considered, and that scoping is
+ * load-bearing twice over: a plain scenario's `<angle brackets>` are prose (a
+ * generic, a placeholder in a URL template, loam's own scaffold sentinels), and
+ * a fleet that never writes an outline must never earn a finding from this.
+ *
+ * The two halves are different defects. An UNBOUND placeholder is an error the
+ * runner cannot repair: cucumber substitutes nothing, so the step definition
+ * receives the literal text `<fee>` and either fails obscurely or — worse —
+ * matches and asserts against a string nobody meant. An UNREFERENCED column is a
+ * warning, because it is usually the fossil of a rename: the column still lists
+ * six cases, the step that used it now names something else, and the outline
+ * runs six identical passes that read as six cases of coverage.
+ */
+export function examplesMismatches(reqs) {
+    const out = [];
+    for (const r of reqs) {
+        if (r.kind === "REMOVED")
+            continue;
+        for (const s of r.scenarios) {
+            const { steps, examples } = scenarioGherkin(s.lines);
+            if (examples === null)
+                continue;
+            const used = placeholdersUsed(steps);
+            const columns = new Set(examples.header);
+            const unbound = [...used].filter((p) => !columns.has(p)).sort();
+            const unreferenced = examples.header.filter((c) => !used.has(c));
+            if (unbound.length > 0 || unreferenced.length > 0) {
+                out.push({ requirement: r.name, scenario: s.name, unbound, unreferenced });
+            }
+        }
+    }
+    return out;
+}
+/**
+ * The Examples half, as findings — two codes rather than one with two
+ * severities, because a machine cannot branch on a severity that depends on the
+ * case, and the fixes differ: one adds a column, the other removes one or
+ * restores the reference that used to use it.
+ */
+export function examplesFindings(label, subject, reqs) {
+    const all = examplesMismatches(reqs);
+    const findings = [];
+    const unbound = all.filter((m) => m.unbound.length > 0);
+    if (unbound.length > 0) {
+        findings.push({
+            severity: "error",
+            code: "requirements.examples-unbound",
+            subject,
+            message: `${label}: ${unbound.length} scenario(s) use a \`<placeholder>\` no \`Examples\` column supplies — ` +
+                `cucumber substitutes nothing, so the step receives the literal angle-bracket text. ` +
+                `Add the column, or correct the placeholder to one the header names.`,
+            details: unbound.map((m) => `${m.requirement} — ${m.scenario}: ${m.unbound.map((p) => `<${p}>`).join(", ")}`),
+            text: { detailPrefix: "- " },
+        });
+    }
+    const dead = all.filter((m) => m.unreferenced.length > 0);
+    if (dead.length > 0) {
+        findings.push({
+            severity: "warn",
+            code: "requirements.examples-unreferenced",
+            subject,
+            message: `${label}: ${dead.length} scenario(s) declare an \`Examples\` column no step refers to — ` +
+                `usually the fossil of a rename, and the outline then runs its rows as identical passes that read as cases. ` +
+                `Reference the column from a step, or drop it.`,
+            details: dead.map((m) => `${m.requirement} — ${m.scenario}: ${m.unreferenced.join(", ")}`),
+            text: { detailPrefix: "- " },
+        });
+    }
+    return findings;
+}
+/** The assertionless half, as findings — same label and subject as its two siblings. */
+export function assertionlessFindings(label, subject, reqs) {
+    const mute = assertionlessScenarios(reqs);
+    if (mute.length === 0)
+        return [];
+    return [
+        {
+            severity: "error",
+            code: "requirements.assertionless-scenario",
+            subject,
+            message: `${label}: ${mute.length} scenario(s) have steps and no \`Then\` — ` +
+                `they arrange and act, and assert nothing. The run confirms only that the setup did not throw, ` +
+                `and the claim it answers is confirmed on that. Add the \`- **Then**\` the scenario was written for.`,
+            details: mute.map((s) => `${s.requirement} — ${s.scenario}`),
+            text: { detailPrefix: "- " },
+        },
+    ];
+}
+//# sourceMappingURL=scenarios.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"scenarios.js","sourceRoot":"","sources":["../../../src/core/document/scenarios.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * What a requirement's scenarios are MISSING, and where they contradict\n * themselves — the coverage and shape questions `validate` asks of every spec.\n *\n * Separate from `./parse.ts` because these grade a parsed document rather than\n * produce one, and separate from `./spec.ts` because they answer to\n * `vocabulary/report.ts`: a stepless scenario is a Finding with a subject and a\n * label, and that shape belongs to the report, not to the requirement.\n */\nimport { scenarioGherkin, type EmittedStep } from \"../vocabulary/steps.js\";\nimport type { Finding } from \"../vocabulary/report.js\";\nimport { type Requirement } from \"./spec.js\";\n\n/** Requirements with no scenario — the OpenSpec coverage rule (every requirement needs ≥1). */\nexport function requirementsMissingScenarios(reqs: Requirement[]): Requirement[] {\n  return reqs.filter((r) => r.kind !== \"REMOVED\" && r.scenarios.length === 0);\n}\n\n/** A `#### Scenario:` heading whose body holds nothing a runner would execute. */\nexport interface SteplessScenario {\n  requirement: string;\n  scenario: string;\n}\n\n/**\n * Scenarios that satisfy the coverage rule above and test nothing.\n *\n * `requirementsMissingScenarios` counts HEADINGS, so a `#### Scenario:` with no\n * recognizable Given/When/Then line satisfied the fleet gate's coverage claim\n * outright — and it is not a hypothetical shape: it is what `loam new`\n * scaffolds and what an agent writes when it puts the criteria in prose.\n * Downstream the same emptiness is fatal twice over: cucumber runs a stepless\n * scenario vacuously green, and `loam verify --results` can never confirm it.\n *\n * The detector is `loam gherkin`'s own — `scenarioGherkin` decides what a step\n * IS, and a second opinion here would mean the gate and the emitted suite could\n * disagree about whether a scenario has any. That import is the one place these\n * two modules are circular (gherkin.ts parses requirements); both sides export\n * only function declarations, which are hoisted, so neither evaluation order\n * can observe a half-built module.\n */\nexport function steplessScenarios(reqs: Requirement[]): SteplessScenario[] {\n  const out: SteplessScenario[] = [];\n  for (const r of reqs) {\n    if (r.kind === \"REMOVED\") continue;\n    for (const s of r.scenarios) {\n      if (scenarioGherkin(s.lines).steps.length === 0) out.push({ requirement: r.name, scenario: s.name });\n    }\n  }\n  return out;\n}\n\n/**\n * The stepless half of the coverage check, as findings — the missing-scenario\n * half stays where it is (`requirementsMissingScenarios`), because the two are\n * different states with different fixes: one requirement owes acceptance\n * criteria, the other owes STEPS in criteria somebody has already written.\n *\n * `label` is the coverage check's own label (`payment-service: requirements`),\n * so both halves of one document name it the same way.\n */\nexport function steplessFindings(label: string, subject: string, reqs: Requirement[]): Finding[] {\n  const bare = steplessScenarios(reqs);\n  if (bare.length === 0) return [];\n  return [\n    {\n      severity: \"error\",\n      code: \"requirements.stepless-scenario\",\n      subject,\n      message:\n        `${label}: ${bare.length} scenario(s) have a heading and no recognizable steps — ` +\n        `they satisfy the coverage rule and test nothing. Cucumber runs a stepless scenario vacuously green and ` +\n        `\\`loam verify --results\\` can never confirm it. Write the body as \\`- **Given/When/Then**\\` bullets.`,\n      details: bare.map((s) => `${s.requirement} — ${s.scenario}`),\n      text: { detailPrefix: \"- \" },\n    },\n  ];\n}\n\n/**\n * Scenarios that have steps and assert NOTHING — a body of Given and When with\n * no Then anywhere in it.\n *\n * The third state, and the one that survives both checks above: the requirement\n * has a scenario, the scenario has steps, and the run can only ever confirm that\n * the arrangement did not throw. `And`/`But` are continuations, so their meaning\n * is decided by the keyword they follow — with no `Then` in the body there is\n * nothing for them to continue but the setup.\n *\n * It matters more the more evidence rests on the suite. A stepless scenario is\n * at least visible as an empty body; this one reads like a real test, emits real\n * steps, runs green, and answers a `scenario.tested` claim to the same standard\n * as a scenario that checks twenty things. Under a runner-neutral answer sheet —\n * one `{digest, status}` entry, no steps to count — this document-side check is\n * the only thing left that can tell the two apart.\n */\nexport function assertionlessScenarios(reqs: Requirement[]): SteplessScenario[] {\n  const out: SteplessScenario[] = [];\n  for (const r of reqs) {\n    if (r.kind === \"REMOVED\") continue;\n    for (const s of r.scenarios) {\n      const { steps } = scenarioGherkin(s.lines);\n      // Disjoint from stepless by construction: a body with no steps at all is\n      // that finding's, and reporting one scenario under both codes would offer\n      // two fixes for one defect.\n      if (steps.length > 0 && !steps.some((st) => /^Then\\b/.test(st.text))) {\n        out.push({ requirement: r.name, scenario: s.name });\n      }\n    }\n  }\n  return out;\n}\n\n/** One scenario's disagreement between its `Examples` columns and its `<placeholders>`. */\nexport interface ExamplesMismatch {\n  requirement: string;\n  scenario: string;\n  /** `<placeholders>` a step uses that no column supplies. */\n  unbound: string[];\n  /** Columns no step, docstring or data-table cell refers to. */\n  unreferenced: string[];\n}\n\nconst PLACEHOLDER_RE = /<([^<>\\s]+)>/g;\n\n/**\n * Every `<placeholder>` a scenario's steps reach for, arguments included.\n *\n * Docstrings and data tables are scanned too because cucumber substitutes into\n * them: `<fee>` inside a request payload is a real reference, and a check that\n * read only the step lines would call its column unreferenced and invite the\n * author to delete the column the payload depends on.\n */\nfunction placeholdersUsed(steps: EmittedStep[]): Set<string> {\n  const used = new Set<string>();\n  const scan = (text: string): void => {\n    for (const m of text.matchAll(PLACEHOLDER_RE)) used.add(m[1]!);\n  };\n  for (const st of steps) {\n    scan(st.text);\n    for (const l of st.docstring?.lines ?? []) scan(l);\n    for (const row of st.table ?? []) for (const cell of row) scan(cell);\n  }\n  return used;\n}\n\n/**\n * Scenarios whose `Examples` header and `<placeholders>` disagree.\n *\n * Only scenarios that HAVE an Examples table are considered, and that scoping is\n * load-bearing twice over: a plain scenario's `<angle brackets>` are prose (a\n * generic, a placeholder in a URL template, loam's own scaffold sentinels), and\n * a fleet that never writes an outline must never earn a finding from this.\n *\n * The two halves are different defects. An UNBOUND placeholder is an error the\n * runner cannot repair: cucumber substitutes nothing, so the step definition\n * receives the literal text `<fee>` and either fails obscurely or — worse —\n * matches and asserts against a string nobody meant. An UNREFERENCED column is a\n * warning, because it is usually the fossil of a rename: the column still lists\n * six cases, the step that used it now names something else, and the outline\n * runs six identical passes that read as six cases of coverage.\n */\nexport function examplesMismatches(reqs: Requirement[]): ExamplesMismatch[] {\n  const out: ExamplesMismatch[] = [];\n  for (const r of reqs) {\n    if (r.kind === \"REMOVED\") continue;\n    for (const s of r.scenarios) {\n      const { steps, examples } = scenarioGherkin(s.lines);\n      if (examples === null) continue;\n      const used = placeholdersUsed(steps);\n      const columns = new Set(examples.header);\n      const unbound = [...used].filter((p) => !columns.has(p)).sort();\n      const unreferenced = examples.header.filter((c) => !used.has(c));\n      if (unbound.length > 0 || unreferenced.length > 0) {\n        out.push({ requirement: r.name, scenario: s.name, unbound, unreferenced });\n      }\n    }\n  }\n  return out;\n}\n\n/**\n * The Examples half, as findings — two codes rather than one with two\n * severities, because a machine cannot branch on a severity that depends on the\n * case, and the fixes differ: one adds a column, the other removes one or\n * restores the reference that used to use it.\n */\nexport function examplesFindings(label: string, subject: string, reqs: Requirement[]): Finding[] {\n  const all = examplesMismatches(reqs);\n  const findings: Finding[] = [];\n  const unbound = all.filter((m) => m.unbound.length > 0);\n  if (unbound.length > 0) {\n    findings.push({\n      severity: \"error\",\n      code: \"requirements.examples-unbound\",\n      subject,\n      message:\n        `${label}: ${unbound.length} scenario(s) use a \\`<placeholder>\\` no \\`Examples\\` column supplies — ` +\n        `cucumber substitutes nothing, so the step receives the literal angle-bracket text. ` +\n        `Add the column, or correct the placeholder to one the header names.`,\n      details: unbound.map((m) => `${m.requirement} — ${m.scenario}: ${m.unbound.map((p) => `<${p}>`).join(\", \")}`),\n      text: { detailPrefix: \"- \" },\n    });\n  }\n  const dead = all.filter((m) => m.unreferenced.length > 0);\n  if (dead.length > 0) {\n    findings.push({\n      severity: \"warn\",\n      code: \"requirements.examples-unreferenced\",\n      subject,\n      message:\n        `${label}: ${dead.length} scenario(s) declare an \\`Examples\\` column no step refers to — ` +\n        `usually the fossil of a rename, and the outline then runs its rows as identical passes that read as cases. ` +\n        `Reference the column from a step, or drop it.`,\n      details: dead.map((m) => `${m.requirement} — ${m.scenario}: ${m.unreferenced.join(\", \")}`),\n      text: { detailPrefix: \"- \" },\n    });\n  }\n  return findings;\n}\n\n/** The assertionless half, as findings — same label and subject as its two siblings. */\nexport function assertionlessFindings(label: string, subject: string, reqs: Requirement[]): Finding[] {\n  const mute = assertionlessScenarios(reqs);\n  if (mute.length === 0) return [];\n  return [\n    {\n      severity: \"error\",\n      code: \"requirements.assertionless-scenario\",\n      subject,\n      message:\n        `${label}: ${mute.length} scenario(s) have steps and no \\`Then\\` — ` +\n        `they arrange and act, and assert nothing. The run confirms only that the setup did not throw, ` +\n        `and the claim it answers is confirmed on that. Add the \\`- **Then**\\` the scenario was written for.`,\n      details: mute.map((s) => `${s.requirement} — ${s.scenario}`),\n      text: { detailPrefix: \"- \" },\n    },\n  ];\n}\n"]}

package/dist/core/document/spec.js

@@ -0,0 +1,241 @@
+/**
+ * What a requirement IS, what makes one the same requirement twice, and the one
+ * canonical way it is written back out.
+ *
+ * Living specs use `## Requirements` with `### Requirement:` + `#### Scenario:`.
+ * Feature deltas group requirements under `## ADDED|MODIFIED|REMOVED
+ * Requirements`. Scenarios are the acceptance criteria (Given/When/Then) and
+ * the source for tests.
+ *
+ * Identity and serialization cannot be separated here: `requirementDigest` is
+ * defined AS the sha256 of the serialized requirement without its baseline, so
+ * a second module owning the writer would mean the digest and the bytes it
+ * claims to describe could disagree. `./parse.ts` turns markdown into these,
+ * `./apply.ts` folds a delta into a living set of them.
+ */
+import { createHash } from "node:crypto";
+export const KIND_RE = /^##\s+(ADDED|MODIFIED|REMOVED)\s+Requirements\s*$/i;
+export const REQUIREMENT_ID_LINE_RE = /^\s*Requirement-ID:\s*(.*?)\s*$/i;
+export const BASED_ON_LINE_RE = /^\s*Based-On:\s*(.*?)\s*$/i;
+/**
+ * The `Capability:` body line (also accepted: `Capabilities:`), exactly as the
+ * parser reads it — `./parse.ts` consumes the capture, migrate-openspec's
+ * materializer tests presence with it before appending its own line. One
+ * spelling on purpose: two copies of a grammar is how a "presence" test and
+ * the parse quietly stop agreeing about what counts as the line.
+ */
+export const CAPABILITY_LINE_RE = /^\s*Capabilit(?:y|ies):\s*(.+?)\s*$/i;
+/**
+ * The `Realizes:` body line. One spelling only — no `Realize:` singular
+ * alternative, unlike `Operations?:` and the rest — because the verb already
+ * reads correctly for one entry and for six, and the plural forms in the older
+ * lines exist to forgive a NOUN that changes shape. A grammar with an
+ * alternative nobody needs is one more thing two readers can disagree about.
+ */
+export const REALIZES_LINE_RE = /^\s*Realizes:\s*(.+?)\s*$/i;
+/**
+ * The separator between a `Realizes:` target and the digest of the capability
+ * requirement it was written against — `checkout#CHK-1@9f2c1a4b`.
+ *
+ * `@` and not a second `#`, because the two halves are read by different rules:
+ * `splitRealizesEntry` takes the LAST `#` to find the requirement half, so a
+ * second one would move that boundary and re-parse every existing entry. `@`
+ * is also excluded from `REQUIREMENT_ID_RE`, which is what makes the split
+ * unambiguous rather than a convention — an id can never contain one.
+ *
+ * NOBODY TYPES THIS. `loam rebase --living` writes it and rewrites it; a human
+ * writes `Realizes: checkout#CHK-1` and is never asked for more. An entry
+ * without a pin is not a defect and never becomes one — it is a claim that has
+ * not been pinned yet, and it grades exactly as it did before pins existed.
+ */
+export const REALIZES_PIN_SEPARATOR = "@";
+/**
+ * One `Realizes:` entry split into the target it names and the digest it was
+ * written against, or `pin: null` when it carries none.
+ *
+ * A suffix that is not a well-formed digest is NOT a pin and NOT a refusal:
+ * the whole entry stays the target, so `checkout#CHK-1@nonsense` resolves — or
+ * fails to resolve — exactly as it would have before, under
+ * `capability.realizes-unknown`, whose message names the entry the author
+ * actually typed. Inventing a second refusal for one mistake is the failure
+ * `splitRealizesEntry` already refuses two lines up.
+ */
+export function splitRealizesPin(entry) {
+    const at = entry.lastIndexOf(REALIZES_PIN_SEPARATOR);
+    if (at <= 0)
+        return { target: entry, pin: null };
+    const suffix = entry.slice(at + 1);
+    if (!REQUIREMENT_DIGEST_RE.test(suffix))
+        return { target: entry, pin: null };
+    return { target: entry.slice(0, at), pin: suffix };
+}
+/** Portable, review-friendly stable IDs. Case-sensitive by design. */
+export const REQUIREMENT_ID_RE = /^[A-Za-z][A-Za-z0-9._-]{0,127}$/;
+/**
+ * How much of the sha256 a `Based-On:` line carries — the length
+ * `sources_digest` already uses (core/provenance/stamp.ts), for one reason a reader
+ * can hold: every digest loam writes into a document reads the same.
+ */
+export const REQUIREMENT_DIGEST_LENGTH = 16;
+/** The value shape of a `Based-On:` line, exactly as `requirementDigest` writes it. */
+export const REQUIREMENT_DIGEST_RE = new RegExp(`^[0-9a-f]{${REQUIREMENT_DIGEST_LENGTH}}$`);
+/** Every authored Requirement-ID value in a requirement body, including blanks. */
+export function requirementIdDeclarations(requirement) {
+    return requirement.text.flatMap((line) => {
+        const match = REQUIREMENT_ID_LINE_RE.exec(line);
+        return match === null ? [] : [match[1].trim()];
+    });
+}
+/** Structural ID problems within one spec/delta document. */
+export function requirementIdProblems(reqs) {
+    const problems = [];
+    const owners = new Map();
+    for (const requirement of reqs) {
+        const declarations = requirementIdDeclarations(requirement);
+        const values = declarations.length > 0
+            ? declarations
+            : requirement.id === undefined
+                ? []
+                : [requirement.id];
+        if (declarations.length > 1) {
+            problems.push({ kind: "repeated", requirement: requirement.name, values: declarations });
+        }
+        for (const value of values) {
+            if (!REQUIREMENT_ID_RE.test(value)) {
+                problems.push({ kind: "invalid", requirement: requirement.name, value });
+            }
+        }
+        // A repeated declaration is already an error. Do not also pretend its
+        // keep-last parse result is an unambiguous document identity.
+        if (values.length !== 1 || !REQUIREMENT_ID_RE.test(values[0]))
+            continue;
+        const names = owners.get(values[0]) ?? [];
+        names.push(requirement.name);
+        owners.set(values[0], names);
+    }
+    for (const [id, requirements] of owners) {
+        if (requirements.length > 1)
+            problems.push({ kind: "duplicate", id, requirements });
+    }
+    return problems;
+}
+/** Every authored `Based-On:` value in a requirement body, including blanks. */
+export function basedOnDeclarations(requirement) {
+    return requirement.text.flatMap((line) => {
+        const match = BASED_ON_LINE_RE.exec(line);
+        return match === null ? [] : [match[1].trim()];
+    });
+}
+/**
+ * The requirement without its baseline marker — what a digest is taken over,
+ * and what archive merges into the living document.
+ *
+ * `Based-On:` is a statement ABOUT a delta ("this was written against that"),
+ * never part of the requirement it describes, and both consequences of
+ * forgetting that are bad. Left in the digest input, a requirement's digest
+ * would depend on the pin pointing at it, so no baseline could ever be
+ * self-consistent. Left in the merged text — `applyRequirementDelta` copies the
+ * delta's body into living wholesale — the living document would grow a pin to
+ * a version of itself, and the NEXT feature's baseline would be taken over a
+ * document containing the previous feature's bookkeeping.
+ */
+export function withoutBaseline(requirement) {
+    const { basedOn: _dropped, ...rest } = requirement;
+    return { ...rest, text: requirement.text.filter((line) => !BASED_ON_LINE_RE.test(line)) };
+}
+/**
+ * The requirement with every `Realizes:` pin stripped back to its bare target —
+ * the second thing a digest is taken over, for the same reason as the first.
+ *
+ * `withoutBaseline`'s argument, one axis over: a pin is a statement ABOUT a
+ * join ("this claim was written against that version of the promise"), never
+ * part of the requirement making the claim. Left in the digest input it would
+ * make re-pinning a content change, so every requirement realizing a capability
+ * would go stale against ITS OWN consumers the moment the capability moved —
+ * one edit cascading through the corpus, which is the failure the pin exists to
+ * report rather than to cause.
+ *
+ * The line is kept and only the suffix removed, unlike `withoutBaseline` which
+ * drops the whole line: the target ids ARE content, and a requirement that
+ * stops naming the promise it keeps is a different requirement.
+ */
+export function withoutRealizesPins(requirement) {
+    return {
+        ...requirement,
+        text: requirement.text.map((line) => {
+            const match = REALIZES_LINE_RE.exec(line);
+            if (match === null)
+                return line;
+            const bare = match[1]
+                .split(",")
+                .map((entry) => splitRealizesPin(entry.trim()).target)
+                .join(", ");
+            return line.replace(match[1], bare);
+        }),
+    };
+}
+/**
+ * The identity of a requirement's CONTENT: sha256 over its canonical
+ * serialization, truncated like every other digest loam stamps.
+ *
+ * Canonical, not raw bytes, and deliberately: a living spec is rewritten by
+ * `serializeRequirements` on every archive, so hashing the file's bytes would
+ * make a baseline go stale over reflowed blank lines — a false alarm on the one
+ * check whose whole value is that it only fires when something real moved.
+ * What the hash therefore covers is exactly what survives a round trip: the
+ * heading, the body (`Requirement-ID:` and `Operations:`/`Covers:` lines
+ * included), and every scenario with its Given/When/Then lines. `kind` and
+ * `section` are not serialized and so are not hashed — a requirement does not
+ * change because the document quoting it moved it under another heading.
+ *
+ * The two normalizations are the two kinds of bookkeeping a requirement can
+ * carry about its own joins — the baseline pointing AT it, and the `Realizes:`
+ * pins pointing OUT of it. Both are stripped for the same reason: a digest that
+ * moved when bookkeeping moved would make every pin self-invalidating.
+ */
+export function requirementDigest(requirement) {
+    return createHash("sha256")
+        .update(serializeRequirements([withoutRealizesPins(withoutBaseline(requirement))]), "utf8")
+        .digest("hex")
+        .slice(0, REQUIREMENT_DIGEST_LENGTH);
+}
+/** Serialize requirements back to OpenSpec markdown (`### Requirement:` + `#### Scenario:`). */
+export function serializeRequirements(reqs) {
+    // Framing (blank lines between sections) is normalized here; body content is
+    // only edge-trimmed, never collapsed — blank lines inside a scenario (e.g. in
+    // fenced code blocks) are verbatim content.
+    const chunks = [];
+    for (const r of reqs) {
+        const chunk = [`### Requirement: ${r.name}`];
+        const body = [...r.text];
+        // Parsed documents already carry the authored line in `text`. This branch
+        // also makes programmatically constructed Requirements serialize fully.
+        if (r.id !== undefined && !body.some((line) => REQUIREMENT_ID_LINE_RE.test(line))) {
+            body.unshift(`Requirement-ID: ${r.id}`);
+        }
+        // Directly under the identity it pins, which is where `loam rebase` writes
+        // it too — the two lines are read together, so they are never apart.
+        if (r.basedOn !== undefined && !body.some((line) => BASED_ON_LINE_RE.test(line))) {
+            body.splice(body.findIndex((line) => REQUIREMENT_ID_LINE_RE.test(line)) + 1, 0, `Based-On: ${r.basedOn}`);
+        }
+        const text = body.join("\n").trim();
+        if (text)
+            chunk.push("", text);
+        for (const s of r.scenarios) {
+            chunk.push("", `#### Scenario: ${s.name}`);
+            const body = s.lines.join("\n").trim();
+            if (body)
+                chunk.push(body);
+        }
+        chunks.push(chunk.join("\n"));
+    }
+    return chunks.join("\n\n").trim() + "\n";
+}
+/**
+ * A delta requirement as it lands in the living document, with the bookkeeping
+ * that belongs to the DELTA left behind: the `Based-On:` pin (a claim about
+ * which living version this was written against — meaningless once it IS the
+ * living version, and poison for the next feature's baseline, which would then
+ * hash the previous feature's pin) and the line it was parsed from.
+ */
+//# sourceMappingURL=spec.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"spec.js","sourceRoot":"","sources":["../../../src/core/document/spec.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * What a requirement IS, what makes one the same requirement twice, and the one\n * canonical way it is written back out.\n *\n * Living specs use `## Requirements` with `### Requirement:` + `#### Scenario:`.\n * Feature deltas group requirements under `## ADDED|MODIFIED|REMOVED\n * Requirements`. Scenarios are the acceptance criteria (Given/When/Then) and\n * the source for tests.\n *\n * Identity and serialization cannot be separated here: `requirementDigest` is\n * defined AS the sha256 of the serialized requirement without its baseline, so\n * a second module owning the writer would mean the digest and the bytes it\n * claims to describe could disagree. `./parse.ts` turns markdown into these,\n * `./apply.ts` folds a delta into a living set of them.\n */\nimport { createHash } from \"node:crypto\";\n\nexport type DeltaKind = \"ADDED\" | \"MODIFIED\" | \"REMOVED\" | \"BASE\";\n\nexport interface Scenario {\n  name: string;\n  lines: string[];\n}\n\nexport interface Requirement {\n  /** BASE for a living spec; ADDED/MODIFIED/REMOVED inside a feature delta. */\n  kind: DeltaKind;\n  /**\n   * Stable identity from a `Requirement-ID:` body line. Optional so existing\n   * OpenSpec-compatible documents continue to use their heading as identity.\n   */\n  id?: string;\n  /**\n   * The living requirement this delta was WRITTEN AGAINST, from a `Based-On:`\n   * body line — `requirementDigest` of that requirement at authoring time.\n   *\n   * Delta-only, and meaningful on MODIFIED/REMOVED alone: those two address a\n   * requirement that already exists, and a MODIFIED carries its full new text,\n   * so archive does not merge the living wording — it REPLACES it. Two features\n   * rewriting one requirement therefore lose the loser's text outright, and the\n   * in-flight warning (`delta.modified-conflict`) cannot see the case that\n   * actually happens: once the first archives it leaves `changes/`, the second\n   * goes green again, and its stale text lands on top without a word. This is\n   * the pin that closes that window — the same trick as `sources_digest`\n   * (core/provenance/stamp.ts), one requirement wide.\n   *\n   * Absent on requirements adopted from OpenSpec, which never had the line;\n   * those keep the older, weaker protection and are told so once (warn).\n   */\n  basedOn?: string;\n  name: string;\n  text: string[];\n  /** OpenAPI operationIds this requirement governs, from an `Operations:` line. */\n  operations: string[];\n  /**\n   * What this requirement's scenarios exercise, from a `Covers:` line — the\n   * architecture analog of `Operations:`. Entries are C4 element ids, edges\n   * (`source -> target`), or health signals (`alert:<id>` / `sli:<id>`);\n   * core/c4/arch.ts owns the grammar and the resolution. Parsed everywhere for one\n   * grammar's sake, meaningful in arch.spec.md.\n   */\n  covers: string[];\n  /**\n   * Authorization this requirement is gated on, from a `Requires:` line —\n   * `<subject>/<permission>` entries declared in `architecture/permissions.yaml`.\n   *\n   * A third join beside `Operations:` and `Covers:`, and it exists because the\n   * other two cannot carry it. A permission is not an operation (one operation\n   * is gated by several, and the same permission gates several operations) and\n   * it is not a C4 element (it is a domain fact, not a structural one). The\n   * subject half is what the OpenAPI security model cannot express at all:\n   * `security` names what the CALLER must hold, while a permission is as often\n   * checked on an entity inside the request — the profile a message is sent\n   * from, the org a resource belongs to.\n   */\n  requires: string[];\n  /**\n   * Fleet capabilities this requirement realizes part of, from a `Capability:`\n   * (also accepted: `Capabilities:`) line — ids declared in\n   * `architecture/capabilities.yaml`.\n   *\n   * A fourth join beside `Operations:`, `Covers:` and `Requires:`, and a LIST\n   * because the relation is many-to-many in both directions: one requirement\n   * commonly closes part of two capabilities, and a capability is realized by\n   * many requirements across several services — a single-valued field would\n   * force authors to pick a lie. Neither existing line can carry it: a\n   * capability is not an operation (it is behaviour above any one endpoint)\n   * and not a C4 element (it is a business fact, not a structural one).\n   * The parse is additive exactly as `requires` is — the line rides in\n   * `req.text` and therefore inside `requirementDigest`, so no living\n   * document's digest moves merely because loam learned to read it.\n   */\n  capabilities: string[];\n  /**\n   * Capability REQUIREMENTS this requirement realizes part of, from a\n   * `Realizes:` line — entries spelled `<capability-id>#<Requirement-ID>`,\n   * resolving against `capabilities/<cap>/spec.md`.\n   *\n   * A fifth join, and the one that makes the business tree checkable rather\n   * than merely present. `Capability:` beside it answers a DIFFERENT question\n   * and neither replaces the other: `Capability: checkout` says this\n   * requirement is part of that capability, which is a claim about theme;\n   * `Realizes: checkout#CHECKOUT-CHARGE-ONCE` says it is part of what makes one\n   * named promise true, which is a claim loam can grade in both directions —\n   * an entry that resolves to nothing, and a capability requirement nothing\n   * realizes.\n   *\n   * WHY A COMPOSITE ENTRY RATHER THAN TWO LINES. A `Requirement-ID` is only\n   * unique inside its own document, so the capability half is not decoration —\n   * it is what makes the target addressable at all. Two lines would let a\n   * requirement name three capabilities and four ids with nothing saying which\n   * belongs to which.\n   *\n   * WHY THE SEPARATOR IS THE LAST `#` AND NOT THE FIRST. The requirement half\n   * has a strict grammar (`REQUIREMENT_ID_RE`) that excludes `#`, while the\n   * capability half is a YAML key and a directory name and is not constrained\n   * here at all. Splitting at the last `#` is therefore unambiguous for every\n   * capability id there is; splitting at the first would mis-parse any id that\n   * contained one, and would do it silently.\n   *\n   * Parsed additively exactly as `capabilities` is — the line rides in\n   * `req.text` and therefore inside `requirementDigest`, so no living\n   * document's digest moves merely because loam learned to read it.\n   */\n  realizes: string[];\n  /**\n   * AsyncAPI message names this requirement governs on the PRODUCING side, from\n   * a `Publishes:` line — the event-axis analog of `Operations:`.\n   *\n   * Two lines rather than one, because the async spine is directional in a way\n   * the HTTP one is not: `Publishes:` resolves against this service's OWN\n   * contract, while `Consumes:` names a message another service declares, and\n   * only a fleet-wide view can say whether anybody does. Grading them alike\n   * would either excuse a typo in a producer or point a consumer's error at the\n   * wrong repository.\n   */\n  publishes: string[];\n  /** AsyncAPI message names this requirement consumes, from a `Consumes:` line. See `publishes`. */\n  consumes: string[];\n  scenarios: Scenario[];\n  /**\n   * The H2 heading of its SOURCE DOCUMENT this requirement was parsed under,\n   * verbatim (`## Behavior`), or absent if it preceded every heading. Records where\n   * the text came from, so it stays true after a merge re-homes the requirement.\n   *\n   * `kind` alone cannot explain why a requirement is BASE, and the two BASE cases\n   * differ completely: under `## Requirements` a delta is legally quoting the\n   * living state, while under `## Behavior` the author wrote a change that archive\n   * will silently not merge. `delta.requirement-not-merged` tells them apart.\n   */\n  section?: string;\n  /**\n   * 1-based line of this requirement's `### Requirement:` heading in its source\n   * document. Body line `text[i]` is therefore at line `line + 1 + i` — the\n   * capture is contiguous from the heading to the first scenario — which is what\n   * lets `loam rebase` rewrite one `Based-On:` line by surgery instead of\n   * reserializing the document and flattening the author's sections and prose.\n   */\n  line?: number;\n}\n\nexport const KIND_RE = /^##\\s+(ADDED|MODIFIED|REMOVED)\\s+Requirements\\s*$/i;\nexport const REQUIREMENT_ID_LINE_RE = /^\\s*Requirement-ID:\\s*(.*?)\\s*$/i;\nexport const BASED_ON_LINE_RE = /^\\s*Based-On:\\s*(.*?)\\s*$/i;\n\n/**\n * The `Capability:` body line (also accepted: `Capabilities:`), exactly as the\n * parser reads it — `./parse.ts` consumes the capture, migrate-openspec's\n * materializer tests presence with it before appending its own line. One\n * spelling on purpose: two copies of a grammar is how a \"presence\" test and\n * the parse quietly stop agreeing about what counts as the line.\n */\nexport const CAPABILITY_LINE_RE = /^\\s*Capabilit(?:y|ies):\\s*(.+?)\\s*$/i;\n\n/**\n * The `Realizes:` body line. One spelling only — no `Realize:` singular\n * alternative, unlike `Operations?:` and the rest — because the verb already\n * reads correctly for one entry and for six, and the plural forms in the older\n * lines exist to forgive a NOUN that changes shape. A grammar with an\n * alternative nobody needs is one more thing two readers can disagree about.\n */\nexport const REALIZES_LINE_RE = /^\\s*Realizes:\\s*(.+?)\\s*$/i;\n\n/**\n * The separator between a `Realizes:` target and the digest of the capability\n * requirement it was written against — `checkout#CHK-1@9f2c1a4b`.\n *\n * `@` and not a second `#`, because the two halves are read by different rules:\n * `splitRealizesEntry` takes the LAST `#` to find the requirement half, so a\n * second one would move that boundary and re-parse every existing entry. `@`\n * is also excluded from `REQUIREMENT_ID_RE`, which is what makes the split\n * unambiguous rather than a convention — an id can never contain one.\n *\n * NOBODY TYPES THIS. `loam rebase --living` writes it and rewrites it; a human\n * writes `Realizes: checkout#CHK-1` and is never asked for more. An entry\n * without a pin is not a defect and never becomes one — it is a claim that has\n * not been pinned yet, and it grades exactly as it did before pins existed.\n */\nexport const REALIZES_PIN_SEPARATOR = \"@\";\n\n/**\n * One `Realizes:` entry split into the target it names and the digest it was\n * written against, or `pin: null` when it carries none.\n *\n * A suffix that is not a well-formed digest is NOT a pin and NOT a refusal:\n * the whole entry stays the target, so `checkout#CHK-1@nonsense` resolves — or\n * fails to resolve — exactly as it would have before, under\n * `capability.realizes-unknown`, whose message names the entry the author\n * actually typed. Inventing a second refusal for one mistake is the failure\n * `splitRealizesEntry` already refuses two lines up.\n */\nexport function splitRealizesPin(entry: string): { target: string; pin: string | null } {\n  const at = entry.lastIndexOf(REALIZES_PIN_SEPARATOR);\n  if (at <= 0) return { target: entry, pin: null };\n  const suffix = entry.slice(at + 1);\n  if (!REQUIREMENT_DIGEST_RE.test(suffix)) return { target: entry, pin: null };\n  return { target: entry.slice(0, at), pin: suffix };\n}\n\n/** Portable, review-friendly stable IDs. Case-sensitive by design. */\nexport const REQUIREMENT_ID_RE = /^[A-Za-z][A-Za-z0-9._-]{0,127}$/;\n\n/**\n * How much of the sha256 a `Based-On:` line carries — the length\n * `sources_digest` already uses (core/provenance/stamp.ts), for one reason a reader\n * can hold: every digest loam writes into a document reads the same.\n */\nexport const REQUIREMENT_DIGEST_LENGTH = 16;\n\n/** The value shape of a `Based-On:` line, exactly as `requirementDigest` writes it. */\nexport const REQUIREMENT_DIGEST_RE = new RegExp(`^[0-9a-f]{${REQUIREMENT_DIGEST_LENGTH}}$`);\n\nexport type RequirementIdProblem =\n  | { kind: \"invalid\"; requirement: string; value: string }\n  | { kind: \"repeated\"; requirement: string; values: string[] }\n  | { kind: \"duplicate\"; id: string; requirements: string[] };\n\n/** Every authored Requirement-ID value in a requirement body, including blanks. */\nexport function requirementIdDeclarations(requirement: Requirement): string[] {\n  return requirement.text.flatMap((line) => {\n    const match = REQUIREMENT_ID_LINE_RE.exec(line);\n    return match === null ? [] : [match[1]!.trim()];\n  });\n}\n\n/** Structural ID problems within one spec/delta document. */\nexport function requirementIdProblems(reqs: Requirement[]): RequirementIdProblem[] {\n  const problems: RequirementIdProblem[] = [];\n  const owners = new Map<string, string[]>();\n  for (const requirement of reqs) {\n    const declarations = requirementIdDeclarations(requirement);\n    const values = declarations.length > 0\n      ? declarations\n      : requirement.id === undefined\n        ? []\n        : [requirement.id];\n    if (declarations.length > 1) {\n      problems.push({ kind: \"repeated\", requirement: requirement.name, values: declarations });\n    }\n    for (const value of values) {\n      if (!REQUIREMENT_ID_RE.test(value)) {\n        problems.push({ kind: \"invalid\", requirement: requirement.name, value });\n      }\n    }\n    // A repeated declaration is already an error. Do not also pretend its\n    // keep-last parse result is an unambiguous document identity.\n    if (values.length !== 1 || !REQUIREMENT_ID_RE.test(values[0]!)) continue;\n    const names = owners.get(values[0]!) ?? [];\n    names.push(requirement.name);\n    owners.set(values[0]!, names);\n  }\n  for (const [id, requirements] of owners) {\n    if (requirements.length > 1) problems.push({ kind: \"duplicate\", id, requirements });\n  }\n  return problems;\n}\n\n/** Every authored `Based-On:` value in a requirement body, including blanks. */\nexport function basedOnDeclarations(requirement: Requirement): string[] {\n  return requirement.text.flatMap((line) => {\n    const match = BASED_ON_LINE_RE.exec(line);\n    return match === null ? [] : [match[1]!.trim()];\n  });\n}\n\n/**\n * The requirement without its baseline marker — what a digest is taken over,\n * and what archive merges into the living document.\n *\n * `Based-On:` is a statement ABOUT a delta (\"this was written against that\"),\n * never part of the requirement it describes, and both consequences of\n * forgetting that are bad. Left in the digest input, a requirement's digest\n * would depend on the pin pointing at it, so no baseline could ever be\n * self-consistent. Left in the merged text — `applyRequirementDelta` copies the\n * delta's body into living wholesale — the living document would grow a pin to\n * a version of itself, and the NEXT feature's baseline would be taken over a\n * document containing the previous feature's bookkeeping.\n */\nexport function withoutBaseline(requirement: Requirement): Requirement {\n  const { basedOn: _dropped, ...rest } = requirement;\n  return { ...rest, text: requirement.text.filter((line) => !BASED_ON_LINE_RE.test(line)) };\n}\n\n/**\n * The requirement with every `Realizes:` pin stripped back to its bare target —\n * the second thing a digest is taken over, for the same reason as the first.\n *\n * `withoutBaseline`'s argument, one axis over: a pin is a statement ABOUT a\n * join (\"this claim was written against that version of the promise\"), never\n * part of the requirement making the claim. Left in the digest input it would\n * make re-pinning a content change, so every requirement realizing a capability\n * would go stale against ITS OWN consumers the moment the capability moved —\n * one edit cascading through the corpus, which is the failure the pin exists to\n * report rather than to cause.\n *\n * The line is kept and only the suffix removed, unlike `withoutBaseline` which\n * drops the whole line: the target ids ARE content, and a requirement that\n * stops naming the promise it keeps is a different requirement.\n */\nexport function withoutRealizesPins(requirement: Requirement): Requirement {\n  return {\n    ...requirement,\n    text: requirement.text.map((line) => {\n      const match = REALIZES_LINE_RE.exec(line);\n      if (match === null) return line;\n      const bare = match[1]!\n        .split(\",\")\n        .map((entry) => splitRealizesPin(entry.trim()).target)\n        .join(\", \");\n      return line.replace(match[1]!, bare);\n    }),\n  };\n}\n\n/**\n * The identity of a requirement's CONTENT: sha256 over its canonical\n * serialization, truncated like every other digest loam stamps.\n *\n * Canonical, not raw bytes, and deliberately: a living spec is rewritten by\n * `serializeRequirements` on every archive, so hashing the file's bytes would\n * make a baseline go stale over reflowed blank lines — a false alarm on the one\n * check whose whole value is that it only fires when something real moved.\n * What the hash therefore covers is exactly what survives a round trip: the\n * heading, the body (`Requirement-ID:` and `Operations:`/`Covers:` lines\n * included), and every scenario with its Given/When/Then lines. `kind` and\n * `section` are not serialized and so are not hashed — a requirement does not\n * change because the document quoting it moved it under another heading.\n *\n * The two normalizations are the two kinds of bookkeeping a requirement can\n * carry about its own joins — the baseline pointing AT it, and the `Realizes:`\n * pins pointing OUT of it. Both are stripped for the same reason: a digest that\n * moved when bookkeeping moved would make every pin self-invalidating.\n */\nexport function requirementDigest(requirement: Requirement): string {\n  return createHash(\"sha256\")\n    .update(serializeRequirements([withoutRealizesPins(withoutBaseline(requirement))]), \"utf8\")\n    .digest(\"hex\")\n    .slice(0, REQUIREMENT_DIGEST_LENGTH);\n}\n\n/** Serialize requirements back to OpenSpec markdown (`### Requirement:` + `#### Scenario:`). */\nexport function serializeRequirements(reqs: Requirement[]): string {\n  // Framing (blank lines between sections) is normalized here; body content is\n  // only edge-trimmed, never collapsed — blank lines inside a scenario (e.g. in\n  // fenced code blocks) are verbatim content.\n  const chunks: string[] = [];\n  for (const r of reqs) {\n    const chunk: string[] = [`### Requirement: ${r.name}`];\n    const body = [...r.text];\n    // Parsed documents already carry the authored line in `text`. This branch\n    // also makes programmatically constructed Requirements serialize fully.\n    if (r.id !== undefined && !body.some((line) => REQUIREMENT_ID_LINE_RE.test(line))) {\n      body.unshift(`Requirement-ID: ${r.id}`);\n    }\n    // Directly under the identity it pins, which is where `loam rebase` writes\n    // it too — the two lines are read together, so they are never apart.\n    if (r.basedOn !== undefined && !body.some((line) => BASED_ON_LINE_RE.test(line))) {\n      body.splice(body.findIndex((line) => REQUIREMENT_ID_LINE_RE.test(line)) + 1, 0, `Based-On: ${r.basedOn}`);\n    }\n    const text = body.join(\"\\n\").trim();\n    if (text) chunk.push(\"\", text);\n    for (const s of r.scenarios) {\n      chunk.push(\"\", `#### Scenario: ${s.name}`);\n      const body = s.lines.join(\"\\n\").trim();\n      if (body) chunk.push(body);\n    }\n    chunks.push(chunk.join(\"\\n\"));\n  }\n  return chunks.join(\"\\n\\n\").trim() + \"\\n\";\n}\n\n/**\n * A delta requirement as it lands in the living document, with the bookkeeping\n * that belongs to the DELTA left behind: the `Based-On:` pin (a claim about\n * which living version this was written against — meaningless once it IS the\n * living version, and poison for the next feature's baseline, which would then\n * hash the previous feature's pin) and the line it was parsed from.\n */\n"]}