@seanmars/tospec 0.19.0-beta.8 → 0.21.0

package/dist/core/specs-apply.js

@@ -1,22 +1,11 @@
-/**
- * Spec Application Logic
- *
- * Extracted from ArchiveCommand to enable standalone spec application.
- * Applies delta specs from a change to main specs without archiving.
- */
+/** Applies a change's delta specs to the main specs, independently of archiving. */
 import { promises as fs } from 'fs';
 import path from 'path';
-import { extractRequirementsSection, parseDeltaSpec, normalizeRequirementName, foldRequirementName, } from './parsers/requirement-blocks.js';
+import { extractRequirementsSection, parseDeltaSpec, normalizeRequirementName, foldRequirementName, REQUIREMENT_HEADER_REGEX, } from './parsers/requirement-blocks.js';
 import { findMainSpecStructureIssues } from './parsers/spec-structure.js';
 import { isAbsentDirectoryError, isMissingPathError } from '../utils/file-system.js';
-import { buildCodeFenceMask, findMissingScenarios } from './parsers/requirement-text.js';
+import { buildCodeFenceMask, findMissingScenarios, normalizeDocument } from './parsers/requirement-text.js';
 import { PURPOSE_PLACEHOLDER_PREFIX, PURPOSE_PLACEHOLDER_SUFFIX, } from './validation/constants.js';
-// -----------------------------------------------------------------------------
-// Public API
-// -----------------------------------------------------------------------------
-/**
- * Find all delta spec files that need to be applied from a change.
- */
 export async function findSpecUpdates(changeDir, mainSpecsDir) {
     const updates = [];
     const changeSpecsDir = path.join(changeDir, 'specs');
@@ -25,9 +14,8 @@ export async function findSpecUpdates(changeDir, mainSpecsDir) {
         entries = await fs.readdir(changeSpecsDir, { withFileTypes: true });
     }
     catch (error) {
-        // An empty result reads as "this change has no deltas", which callers act
-        // on: archive merges nothing and reports success. Only a directory that is
-        // genuinely not there may say that.
+        // An empty result means "no deltas", and archive merges nothing and reports
+        // success on it. Only a genuinely absent directory may say that.
         if (isAbsentDirectoryError(error))
             return updates;
         throw error;
@@ -41,16 +29,14 @@ export async function findSpecUpdates(changeDir, mainSpecsDir) {
             await fs.access(specFile);
         }
         catch (error) {
-            // A capability folder with no spec.md is not a delta. A spec.md that
-            // exists and cannot be reached is one, and skipping it drops that
-            // capability's requirements without a word.
+            // A capability folder with no spec.md is not a delta; an unreachable
+            // spec.md is one, and skipping it drops its requirements silently.
             if (isMissingPathError(error))
                 continue;
             throw error;
         }
-        // Whether the capability is new. Same rule again: an unreachable target is
-        // not an absent one, and calling it absent sends the merge down the
-        // new-capability path — which rebuilds the spec from a skeleton.
+        // Same rule: calling an unreachable target absent sends the merge down the
+        // new-capability path, which rebuilds the spec from a skeleton.
         let exists = true;
         try {
             await fs.access(targetFile);
@@ -69,9 +55,21 @@ export async function findSpecUpdates(changeDir, mainSpecsDir) {
     return updates;
 }
 /**
- * Build an updated spec by applying delta operations.
- * Returns the rebuilt content, counts of operations, and any non-fatal notices.
+ * The capability directory's real name on disk, or `fallback` when absent.
+ * Differs only on a case-insensitive filesystem, where `specs/RegexCap` and
+ * `specs/regexcap` are one directory — this normalises a message, it does not
+ * merge anything.
  */
+async function resolveOnDiskSpecName(targetPath, fallback) {
+    const parent = path.dirname(path.dirname(targetPath));
+    try {
+        const entries = await fs.readdir(parent);
+        return entries.find((entry) => entry.toLowerCase() === fallback.toLowerCase()) ?? fallback;
+    }
+    catch {
+        return fallback;
+    }
+}
 export async function buildUpdatedSpec(update, changeName, options = {}) {
     const notices = [];
     const notice = (code, message) => {
@@ -79,36 +77,31 @@ export async function buildUpdatedSpec(update, changeName, options = {}) {
         if (!options.silent)
             console.log(`Warning: ${message}`);
     };
-    // Read change spec content (delta-format expected)
     const changeContent = await fs.readFile(update.source, 'utf-8');
-    // Parse deltas from the change spec file
     const plan = parseDeltaSpec(changeContent);
+    // The capability as the delta spelled it — messages about the delta's own
+    // content echo the author's spelling so they can find it in their file.
     const specName = path.basename(path.dirname(update.target));
-    // Pre-validate duplicates within sections
-    const addedNames = new Set();
-    for (const add of plan.added) {
-        const name = normalizeRequirementName(add.name);
-        if (addedNames.has(name)) {
-            throw new Error(`${specName} validation failed - duplicate requirement in ADDED for header "### Requirement: ${add.name}"`);
-        }
-        addedNames.add(name);
-    }
-    const modifiedNames = new Set();
-    for (const mod of plan.modified) {
-        const name = normalizeRequirementName(mod.name);
-        if (modifiedNames.has(name)) {
-            throw new Error(`${specName} validation failed - duplicate requirement in MODIFIED for header "### Requirement: ${mod.name}"`);
-        }
-        modifiedNames.add(name);
-    }
-    const removedNamesSet = new Set();
-    for (const rem of plan.removed) {
-        const name = normalizeRequirementName(rem);
-        if (removedNamesSet.has(name)) {
-            throw new Error(`${specName} validation failed - duplicate requirement in REMOVED for header "### Requirement: ${rem}"`);
+    // The capability as it exists on disk, which differs on a case-insensitive
+    // filesystem: a delta under `specs/RegexCap/` resolves to the existing
+    // `tospec/specs/regexcap/`.
+    const onDiskSpecName = await resolveOnDiskSpecName(update.target, specName);
+    const collectUnique = (names, section) => {
+        const seen = new Set();
+        for (const original of names) {
+            const name = normalizeRequirementName(original);
+            if (seen.has(name)) {
+                throw new Error(`${specName} validation failed - duplicate requirement in ${section} for header "### Requirement: ${original}"`);
+            }
+            seen.add(name);
         }
-        removedNamesSet.add(name);
-    }
+        return seen;
+    };
+    const addedNames = collectUnique(plan.added.map((add) => add.name), 'ADDED');
+    const modifiedNames = collectUnique(plan.modified.map((mod) => mod.name), 'MODIFIED');
+    const removedNamesSet = collectUnique(plan.removed, 'REMOVED');
+    // Checked per entry rather than via collectUnique: a pair that duplicates
+    // both sides must report the FROM/TO the original interleaving would.
     const renamedFromSet = new Set();
     const renamedToSet = new Set();
     for (const { from, to } of plan.renamed) {
@@ -123,7 +116,6 @@ export async function buildUpdatedSpec(update, changeName, options = {}) {
         renamedFromSet.add(fromNorm);
         renamedToSet.add(toNorm);
     }
-    // Pre-validate cross-section conflicts
     const conflicts = [];
     for (const n of modifiedNames) {
         if (removedNamesSet.has(n))
@@ -135,15 +127,12 @@ export async function buildUpdatedSpec(update, changeName, options = {}) {
         if (removedNamesSet.has(n))
             conflicts.push({ name: n, a: 'ADDED', b: 'REMOVED' });
     }
-    // Renamed interplay: MODIFIED must reference the NEW header, not FROM
     for (const { from, to } of plan.renamed) {
         const fromNorm = normalizeRequirementName(from);
         const toNorm = normalizeRequirementName(to);
-        // A REMOVED naming the FROM side contradicts the rename. Once a missing
-        // REMOVED target is treated as a no-op (early-sync), this conflict must be
-        // rejected explicitly instead of failing incidentally at apply time.
-        // Compared folded, so a case/whitespace variant cannot slip past into a
-        // warned no-op.
+        // A REMOVED naming the FROM side contradicts the rename. Since a missing
+        // REMOVED target is a no-op (early-sync), this must be rejected explicitly.
+        // Folded, so a case or whitespace variant cannot slip past as a no-op.
         const removedFoldMatch = [...removedNamesSet].find((r) => foldRequirementName(r) === foldRequirementName(fromNorm));
         if (removedFoldMatch !== undefined) {
             throw new Error(`${specName} validation failed - requirement present in multiple sections (RENAMED and REMOVED) for header "### Requirement: ${from}"` +
@@ -152,7 +141,6 @@ export async function buildUpdatedSpec(update, changeName, options = {}) {
         if (modifiedNames.has(fromNorm)) {
             throw new Error(`${specName} validation failed - when a rename exists, MODIFIED must reference the NEW header "### Requirement: ${to}"`);
         }
-        // Detect ADDED colliding with a RENAMED TO
         if (addedNames.has(toNorm)) {
             throw new Error(`${specName} validation failed - RENAMED TO header collides with ADDED for "### Requirement: ${to}"`);
         }
@@ -166,33 +154,25 @@ export async function buildUpdatedSpec(update, changeName, options = {}) {
         throw new Error(`Delta parsing found no operations for ${path.basename(path.dirname(update.source))}. ` +
             `Provide ADDED/MODIFIED/REMOVED/RENAMED sections in change spec.`);
     }
-    // Load or create base target content
     let targetContent;
     let isNewSpec = false;
     try {
         targetContent = await fs.readFile(update.target, 'utf-8');
     }
     catch (error) {
-        // Only "the file is not there" means a new capability. Every other failure —
-        // a permission denial, a device error, a directory where the file belongs —
-        // says the spec may well exist with content this path is about to discard.
-        // For an addition-only delta that is silent data loss: the new-capability
-        // branch below accepts it and rebuilds the spec from a skeleton.
+        // Only "not there" means a new capability. Any other failure says the spec
+        // may exist with content the skeleton rebuild below would discard.
         if (!isMissingPathError(error))
             throw error;
-        // Target spec does not exist; MODIFIED and RENAMED are not allowed for new specs
-        // REMOVED will be ignored with a warning since there's nothing to remove
         if (plan.modified.length > 0 || plan.renamed.length > 0) {
             throw new Error(`${specName}: target spec does not exist; only ADDED requirements are allowed for new specs. MODIFIED and RENAMED operations require an existing spec.`);
         }
-        // Warn about REMOVED requirements being ignored for new specs
         if (plan.removed.length > 0) {
             notice('archive_removed_ignored_new_spec', `${specName} - ${plan.removed.length} REMOVED requirement(s) ignored for new spec (nothing to remove).`);
         }
         isNewSpec = true;
-        // Carry the delta's authored Purpose into the new main spec instead of
-        // overwriting it with the placeholder. Only plain prose is carried; a
-        // Purpose that could restructure the spec falls back to the placeholder.
+        // Only plain prose is carried; a Purpose that could restructure the spec
+        // falls back to the placeholder.
         const deltaPurpose = extractDeltaPurpose(changeContent);
         if (deltaPurpose && isPurposeCarrySafe(deltaPurpose)) {
             targetContent = buildSpecSkeleton(specName, changeName, deltaPurpose);
@@ -202,35 +182,27 @@ export async function buildUpdatedSpec(update, changeName, options = {}) {
                 notice('archive_delta_purpose_ignored', `${specName} - delta Purpose ignored (it would leave the new spec unreadable); wrote the placeholder Purpose instead.`);
             }
             else {
-                // The schema calls `## Purpose` mandatory for a new capability, but
-                // nothing enforces it: validation does not check, and this placeholder
-                // let the omission reach the merged spec as the literal word "TBD" with
-                // nobody told. Saying so here is the only moment the change that owns
+                // The schema calls `## Purpose` mandatory for a new capability but
+                // validation does not check it, so the placeholder reaches the merged
+                // spec as a literal "TBD". This is the last moment the change that owns
                 // the answer is still in hand.
                 notice('archive_purpose_placeholder', `${specName} - delta has no "## Purpose"; wrote a TBD placeholder into the new main spec. Edit tospec/specs/${specName}/spec.md to describe why this capability exists.`);
             }
             targetContent = buildSpecSkeleton(specName, changeName);
         }
     }
-    // An existing capability's main spec owns its Purpose; a delta's is read only
-    // on the new-spec branch above, so on this path it was dropped without a word.
-    // The schema instruction tells authors not to write one here — which is
-    // exactly why someone who did needs to hear that it went nowhere, rather than
-    // assume the main spec now says what they wrote.
+    // An existing capability's main spec owns its Purpose, so a delta's is
+    // dropped on this path — an author who wrote one must hear it went nowhere.
     if (!isNewSpec) {
         const strayPurpose = extractDeltaPurpose(changeContent);
         if (strayPurpose) {
-            notice('archive_delta_purpose_ignored', `${specName} - delta "## Purpose" ignored; ${specName} already has a main spec and owns its Purpose. Edit tospec/specs/${specName}/spec.md directly if it needs changing.`);
+            notice('archive_delta_purpose_ignored', `${specName} - delta "## Purpose" ignored; ${onDiskSpecName} already has a main spec and owns its Purpose. Edit tospec/specs/${onDiskSpecName}/spec.md directly if it needs changing.`);
         }
     }
-    // Record the target's ending convention here, on the raw bytes, because
-    // everything downstream destroys it: extractRequirementsSection normalizes the
-    // document to LF before parsing, normalizeBlockRaw does it again per block,
-    // and the recompose joins with '\n'. Normalizing before parsing is correct —
-    // every structural regex below assumes LF — so the fix is to carry the
-    // convention forward, not to stop normalizing. A whole-file flag rather than
-    // per-line endings: a merged spec contains lines that had no original, so
-    // per-line fidelity is undefined for them.
+    // Recorded on the raw bytes because everything downstream normalizes to LF
+    // (every structural regex below assumes it), so the convention has to be
+    // carried forward. A whole-file flag, not per-line: a merged spec contains
+    // lines that had no original.
     const crlf = targetContent.includes('\r\n');
     const structureIssues = findMainSpecStructureIssues(targetContent);
     if (structureIssues.length > 0) {
@@ -239,27 +211,22 @@ export async function buildUpdatedSpec(update, changeName, options = {}) {
             .join('\n');
         throw new Error(`${specName}: target spec is structurally invalid and cannot be updated until fixed:\n${details}`);
     }
-    // Extract requirements section and build name->block map
     const parts = extractRequirementsSection(targetContent);
     const nameToBlock = new Map();
     for (const block of parts.bodyBlocks) {
         nameToBlock.set(normalizeRequirementName(block.name), block);
     }
-    // The lookup key for each original block, by position. RENAMED changes a
-    // block's key, so `bodyBlocks` alone can no longer find it at recompose time;
-    // this list carries the current key in the original slot. `bodyBlocks` stays
-    // untouched because the salvage pass below reads the ORIGINAL raw content.
+    // The current key for each original block, by position: RENAMED changes a
+    // block's key, so `bodyBlocks` alone cannot find it at recompose time.
+    // `bodyBlocks` stays untouched because the salvage pass reads the original raw.
     const orderedKeys = parts.bodyBlocks.map((block) => normalizeRequirementName(block.name));
-    // Apply operations in order: RENAMED → REMOVED → MODIFIED → ADDED
-    // RENAMED
+    // Order matters: RENAMED → REMOVED → MODIFIED → ADDED.
     let renamedApplied = 0;
     for (const r of plan.renamed) {
         const from = normalizeRequirementName(r.from);
         const to = normalizeRequirementName(r.to);
         if (!nameToBlock.has(from)) {
-            // Source gone but target present means the rename was already synced to
-            // the baseline (early-sync pattern) - re-applying it is a no-op, not a
-            // failure. Only a missing source AND target is a genuine error.
+            // Source gone but target present: the rename was already synced.
             if (nameToBlock.has(to)) {
                 continue;
             }
@@ -280,72 +247,88 @@ export async function buildUpdatedSpec(update, changeName, options = {}) {
         };
         nameToBlock.delete(from);
         nameToBlock.set(to, renamedBlock);
-        // delete+set moves the entry to the Map's insertion-order tail, so a rename
-        // would otherwise push the requirement to the end of the rebuilt spec.
-        // Re-key it in place instead; a chain A->B->C updates the same slot twice.
+        // delete+set moves the entry to the Map's insertion-order tail, pushing the
+        // requirement to the end of the rebuilt spec. Re-key in place.
         const orderIndex = orderedKeys.indexOf(from);
         if (orderIndex >= 0) {
             orderedKeys[orderIndex] = to;
         }
         renamedApplied++;
     }
-    // REMOVED
     let removedApplied = 0;
     // Keys this run actually removed. A renamed requirement also disappears from
-    // its old key, so "absent from nameToBlock" alone cannot tell the two apart —
-    // and salvaging a renamed block's tail would duplicate it.
+    // its old key, so "absent from nameToBlock" cannot tell the two apart, and
+    // salvaging a renamed block's tail would duplicate it.
     const removedKeys = new Set();
     for (const name of plan.removed) {
         const key = normalizeRequirementName(name);
         if (!nameToBlock.has(key)) {
-            // Requirement gone from the baseline means the removal was already synced
-            // (early-sync pattern) - re-applying it is a no-op, not a failure. One
-            // signal separates that from a mistyped header: a requirement that differs
-            // only in case or interior whitespace still being present. That is a typo,
-            // and stays a hard abort. For new specs the skip was already warned above.
+            // Already gone means the removal was already synced. A near miss — one
+            // still present differing only in case or interior whitespace — is a typo
+            // instead, and stays a hard abort.
             if (!isNewSpec) {
                 const nearMiss = [...nameToBlock.keys()].find((k) => foldRequirementName(k) === foldRequirementName(key));
                 if (nearMiss !== undefined) {
                     throw new Error(`${specName} REMOVED failed for header "### Requirement: ${name}" - not found, but "### Requirement: ${nameToBlock.get(nearMiss).name}" exists; fix the header to match it exactly`);
                 }
-                notice('archive_removed_requirement_absent', `${specName} - REMOVED requirement "${name}" is not in the current spec; treating it as already removed. Nothing was deleted — if you meant to remove a requirement, check the header spelling against tospec/specs/${specName}/spec.md.`);
+                notice('archive_removed_requirement_absent', `${specName} - REMOVED requirement "${name}" is not in the current spec; treating it as already removed. Nothing was deleted — if you meant to remove a requirement, check the header spelling against tospec/specs/${onDiskSpecName}/spec.md.`);
             }
-            // Skip removal (nothing to remove)
             continue;
         }
         nameToBlock.delete(key);
         removedKeys.add(key);
         removedApplied++;
     }
-    // MODIFIED
+    // Declarations are consumed as a MODIFIED omission matches them. A declaration
+    // still here afterwards removed nothing: the section grants no removal of its
+    // own, so without a matching omission the scenario stays in the spec while
+    // the change says it went. The validator reports the same leftover as an
+    // ERROR; re-checking here keeps `--no-validate` from archiving what validate
+    // refuses.
+    const unmatchedDeclarations = new Set(plan.removedScenarios);
     for (const mod of plan.modified) {
         const key = normalizeRequirementName(mod.name);
         const currentBlock = nameToBlock.get(key);
         if (!currentBlock) {
             throw new Error(`${specName} MODIFIED failed for header "### Requirement: ${mod.name}" - not found`);
         }
-        // Replace block with provided raw (ensure header line matches key)
-        const modHeaderMatch = mod.raw.split('\n')[0].match(/^###\s*Requirement:\s*(.+)\s*$/i);
+        const modHeaderMatch = mod.raw.split('\n')[0].match(REQUIREMENT_HEADER_REGEX);
         if (!modHeaderMatch || normalizeRequirementName(modHeaderMatch[1]) !== key) {
             throw new Error(`${specName} MODIFIED failed for header "### Requirement: ${mod.name}" - header mismatch in content`);
         }
-        // Guard against a stale MODIFIED block silently dropping scenarios that a
-        // previous archive already added to the current spec.
-        const missingScenarios = findMissingScenarios(currentBlock.raw, mod.raw);
+        // Guards against a stale MODIFIED block dropping scenarios a previous
+        // archive added. `## REMOVED Scenarios` exempts them, read from the same
+        // declarations the validator uses so the two cannot disagree.
+        const declaredRemovals = new Set(plan.removedScenarios.filter((entry) => entry.requirement === key).map((entry) => entry.scenario));
+        const missingScenarios = findMissingScenarios(currentBlock.raw, mod.raw).filter((name) => {
+            if (!declaredRemovals.has(name))
+                return true;
+            for (const entry of unmatchedDeclarations) {
+                if (entry.requirement === key && entry.scenario === name)
+                    unmatchedDeclarations.delete(entry);
+            }
+            return false;
+        });
         if (missingScenarios.length > 0) {
             throw new Error(`${specName} MODIFIED failed for header "### Requirement: ${mod.name}" - current spec contains scenario(s) not present in the modified block: ${missingScenarios.map(name => `"${name}"`).join(', ')}. Refresh the change spec before archiving to avoid dropping scenarios.`);
         }
-        nameToBlock.set(key, mod);
+        // A plain `### Notes` after the requirement is absorbed into its block (see
+        // the recompose pass below), and replacing the block wholesale deleted it
+        // with the old body. Same salvage as REMOVED, appended after the new body
+        // so the section keeps its place.
+        const absorbed = salvageAbsorbedContent(currentBlock.raw);
+        nameToBlock.set(key, absorbed ? { ...mod, raw: `${mod.raw.trimEnd()}\n\n${absorbed}` } : mod);
+    }
+    for (const entry of unmatchedDeclarations) {
+        throw new Error(`${specName} REMOVED Scenarios declares "${entry.scenario}" under requirement "${entry.requirement}", but no MODIFIED block for that requirement drops that scenario - the declaration removes nothing on its own. Restate the requirement under "## MODIFIED Requirements" without that scenario, or check both names against the current spec.`);
     }
-    // ADDED
     let addedApplied = 0;
     for (const add of plan.added) {
         const key = normalizeRequirementName(add.name);
         const existing = nameToBlock.get(key);
         if (existing) {
-            // Identical content means the requirement was already synced to the
-            // baseline (early-sync pattern) - re-applying it is a no-op, not a
-            // conflict. Only differing content is a genuine collision.
+            // Identical content means it was already synced; only differing content
+            // is a genuine collision.
             if (normalizeBlockRaw(existing.raw) === normalizeBlockRaw(add.raw)) {
                 continue;
             }
@@ -354,13 +337,10 @@ export async function buildUpdatedSpec(update, changeName, options = {}) {
         nameToBlock.set(key, add);
         addedApplied++;
     }
-    // Duplicates within resulting map are implicitly prevented by key uniqueness.
-    // Recompose requirements section preserving original ordering where possible.
-    // A block's `raw` runs to the next header the parser RECOGNISES, so a heading
-    // it does not — a plain `### Notes` — is absorbed into the requirement above
-    // it. Removing that requirement used to delete the absorbed content with it,
-    // silently: nothing counted it, so nothing warned, and the spec left behind
-    // still validated. Salvage it back into place instead.
+    // Recompose, preserving original ordering. A block's `raw` runs to the next
+    // header the parser recognises, so one it does not — a plain `### Notes` — is
+    // absorbed into the requirement above, and removing that requirement would
+    // delete the absorbed content silently. Salvage it back into place instead.
     const pieces = [];
     const seen = new Set();
     let salvagedCount = 0;
@@ -384,7 +364,7 @@ export async function buildUpdatedSpec(update, changeName, options = {}) {
             }
         }
     }
-    // Append any newly added that were not in original order
+    // Whatever was added rather than replacing an original slot.
     for (const [key, block] of nameToBlock.entries()) {
         if (!seen.has(key)) {
             pieces.push(block.raw);
@@ -392,8 +372,7 @@ export async function buildUpdatedSpec(update, changeName, options = {}) {
         }
     }
     // Every requirement is gone but absorbed content survived. Retiring would
-    // delete that content along with the file, which is the silent loss this
-    // salvage exists to prevent; writing it would produce a spec with no
+    // delete that content with the file; writing it would produce a spec with no
     // requirements, which cannot validate. Neither is safe to choose silently.
     if (keptRequirements === 0 && removedApplied > 0 && salvagedCount > 0) {
         throw new Error(`${specName}: removing every requirement would leave content that is not part of any requirement (e.g. a "### Notes" section). Move that content out of ${specName}/spec.md first, then archive again.`);
@@ -403,26 +382,19 @@ export async function buildUpdatedSpec(update, changeName, options = {}) {
         .concat(pieces)
         .join('\n\n')
         .trimEnd();
-    // The blank lines around `## Requirements` belong to no slice: `before` and
-    // `after` carry at most one boundary newline by construction, `reqBody` and
-    // every block `raw` are trimEnd()ed. Joining with a bare '\n' therefore glued
-    // the heading to the Purpose paragraph above it and the first requirement
-    // below, so every archive rewrote a well-formatted spec into that shape.
-    // Separate non-empty slices with one blank line, and end the file with
-    // exactly one newline instead of inheriting whatever `after` happened to hold.
+    // Every slice is trimmed, so the blank lines around `## Requirements` belong
+    // to no slice: joining with a bare '\n' glues the heading to the Purpose above
+    // and the first requirement below.
     const rebuilt = collapseBlankRunsOutsideFences([parts.before.trimEnd(), parts.headerLine, reqBody, parts.after.trim()]
         .filter((s) => s !== '')
         .join('\n\n')).trimEnd() + '\n';
     return {
         rebuilt,
         crlf,
-        // The capability has no requirements left and this run is what emptied it.
-        // Both halves matter. "No requirements left" alone would delete a spec on a
-        // re-run of an already-synced REMOVED, taking with it any requirement added
-        // since; "removed something" alone would delete a spec that still has
-        // requirements. An emptied spec cannot be written either way — it fails
-        // validation ("Spec must have at least one requirement") — so the caller
-        // retires the capability instead of writing an unusable file.
+        // Both halves matter: "no requirements left" alone would delete a spec on a
+        // re-run of an already-synced REMOVED; "removed something" alone would
+        // delete a spec that still has requirements. An emptied spec cannot be
+        // written (it fails "at least one requirement"), so the caller retires it.
         retired: keptRequirements === 0 && removedApplied > 0,
         notices,
         counts: {
@@ -434,18 +406,13 @@ export async function buildUpdatedSpec(update, changeName, options = {}) {
     };
 }
 function normalizeBlockRaw(raw) {
-    return raw.replace(/\r\n?/g, '\n').trim();
+    return normalizeDocument(raw).trim();
 }
 /**
- * Collapse runs of blank lines to a single blank line, skipping fenced code.
- *
- * The collapse exists because the four slices joined above each carry their own
- * boundary newlines, so the seams between them accumulate blank lines. Applied
- * to the whole document as `replace(/\n{3,}/g, '\n\n')` it could not tell a seam
- * from a blank line an author put inside a code sample deliberately, so every
- * archive quietly edited the examples in a spec. The seams are all outside any
- * fence by construction, so masking fenced lines loses nothing the collapse was
- * written for.
+ * The slices joined above each carry boundary newlines, so their seams
+ * accumulate blank lines. A whole-document `replace(/\n{3,}/g, '\n\n')` cannot
+ * tell a seam from a deliberate blank line inside a code sample. Seams are all
+ * outside fences by construction, so masking loses nothing.
  */
 function collapseBlankRunsOutsideFences(content) {
     const lines = content.split('\n');
@@ -455,9 +422,8 @@ function collapseBlankRunsOutsideFences(content) {
     for (let i = 0; i < lines.length; i++) {
         if (!mask[i] && lines[i].trim() === '') {
             const last = kept.length - 1;
-            // Drop this blank only if the previous kept line is a blank that was also
-            // outside a fence — a blank line inside a fence is content, and it must
-            // not license dropping the one that follows it.
+            // The previous blank must also be outside a fence: a blank inside one is
+            // content, and must not license dropping the line that follows it.
             if (last >= 0 && !keptMask[last] && kept[last].trim() === '')
                 continue;
         }
@@ -466,16 +432,11 @@ function collapseBlankRunsOutsideFences(content) {
     }
     return kept.join('\n');
 }
-/**
- * Write an updated spec to disk.
- */
 export async function writeUpdatedSpec(update, rebuilt, counts, options = {}) {
-    // Create target directory if needed
     const targetDir = path.dirname(update.target);
     await fs.mkdir(targetDir, { recursive: true });
-    // `rebuilt` is pure LF by construction; restore the convention the target had
-    // before the merge so archiving a CRLF spec does not produce a whole-file diff
-    // on Windows. A brand new spec has no prior convention and stays LF.
+    // `rebuilt` is pure LF by construction; restore the target's pre-merge
+    // convention so archiving a CRLF spec is not a whole-file diff on Windows.
     const content = options.crlf ? rebuilt.replace(/\r?\n/g, '\r\n') : rebuilt;
     await fs.writeFile(update.target, content);
     if (options.silent)
@@ -493,19 +454,15 @@ export async function writeUpdatedSpec(update, rebuilt, counts, options = {}) {
 }
 /**
  * The tail of a requirement block that is not part of the requirement: content
- * from the first `#`/`##`/`###` heading after the block's own header line.
- *
- * `####` is excluded deliberately — a requirement's `#### Scenario:` headings
- * are its own and go with it when it is removed.
+ * from the first `#`/`##`/`###` heading after its own header line. `####` is
+ * excluded — a requirement's `#### Scenario:` headings go with it.
  *
- * The alternative was to widen every heading pattern in the parsers so these
- * headings end the block properly. That was rejected: it reclassifies content,
- * so commented-out or indented examples start parsing as real requirements and
- * a spec that was valid becomes invalid. Salvaging on removal changes what a
- * removal deletes without changing what anything parses.
+ * Widening the parsers' heading patterns instead was rejected: it reclassifies
+ * content, so commented-out or indented examples begin parsing as requirements.
+ * Salvaging changes only what a removal deletes, not what anything parses.
  */
 function salvageAbsorbedContent(requirementRaw) {
-    const lines = requirementRaw.replace(/\r\n?/g, '\n').split('\n');
+    const lines = normalizeDocument(requirementRaw).split('\n');
     const mask = buildCodeFenceMask(lines);
     for (let i = 1; i < lines.length; i++) {
         if (mask[i])
@@ -517,12 +474,9 @@ function salvageAbsorbedContent(requirementRaw) {
     return '';
 }
 /**
- * Retire a capability the change emptied: delete its `spec.md`, then remove any
- * directory the deletion left empty.
- *
- * The pruning walks up from the spec file and stops at `specsRoot`, which is
- * never removed even if it ends up empty — a project with no capabilities still
- * has a specs directory. It also stops at the first non-empty directory, so a
+ * Delete an emptied capability's `spec.md` and prune the directories that
+ * leaves empty. Pruning stops at `specsRoot` (a project with no capabilities
+ * still has a specs directory) and at the first non-empty directory, so a
  * sibling capability is never touched.
  */
 export async function retireSpec(update, specsRoot, options = {}) {
@@ -547,9 +501,8 @@ export async function retireSpec(update, specsRoot, options = {}) {
     console.log(`Retiring ${options.displayPath ?? `tospec/specs/${specName}/spec.md`}: no requirements left`);
 }
 /**
- * Build a skeleton spec for new capabilities. Carries the delta's authored
- * Purpose when one is supplied; otherwise writes the TBD placeholder — composed
- * from the constants validation recognises it by, so the two cannot drift.
+ * Skeleton spec for a new capability. The TBD placeholder is composed from the
+ * constants validation recognises it by, so the two cannot drift.
  */
 export function buildSpecSkeleton(specFolderName, changeName, purpose) {
     const titleBase = specFolderName;
@@ -563,8 +516,10 @@ export function buildSpecSkeleton(specFolderName, changeName, purpose) {
  * is none. Fence-masked so a `## Purpose` inside a code example is not mistaken
  * for the real section.
  */
-function extractDeltaPurpose(content) {
-    const lines = content.replace(/\r\n?/g, '\n').split('\n');
+export function extractDeltaPurpose(content) {
+    // normalizeDocument, not a hand-rolled newline collapse: it also strips the
+    // BOM, without which `<BOM>## Purpose` misses the `^##` anchor.
+    const lines = normalizeDocument(content).split('\n');
     const mask = buildCodeFenceMask(lines);
     let start = -1;
     for (let i = 0; i < lines.length; i++) {
@@ -589,13 +544,9 @@ function extractDeltaPurpose(content) {
     return lines.slice(start, end).join('\n').trim();
 }
 /**
- * A carried Purpose must not restructure the new spec. Headings, HTML comments,
- * and code fences each have ways to corrupt or hide the rest of the spec, so a
- * Purpose containing any of them falls back to the placeholder rather than risk
- * it.
- * Limitation: prose-only heuristic; a Purpose that genuinely needs a fence or
- * heading falls back to TBD. Loosen only once those corruption classes are
- * handled the way archive's own validator reads the spec.
+ * A carried Purpose must not restructure the new spec: headings, HTML comments
+ * and code fences can each corrupt or hide the rest of it, so any of them falls
+ * back to the placeholder.
  */
 function isPurposeCarrySafe(body) {
     if (!body)