@fission-ai/openspec 1.13.0 → 1.13.2

package/dist/core/parsers/change-parser.js

@@ -1,8 +1,14 @@
 import { MarkdownParser } from './markdown-parser.js';
 import { buildCodeFenceMask } from './requirement-text.js';
+import { parseDeltaSpec } from './requirement-blocks.js';
 import path from 'path';
 import { promises as fs } from 'fs';
 import { discoverSpecFiles } from '../../utils/spec-discovery.js';
+/** A header-only block for a REMOVED entry written in the bullet form. */
+function removedNameBlock(name) {
+    const headerLine = `### Requirement: ${name}`;
+    return { headerLine, name, raw: headerLine };
+}
 export class ChangeParser extends MarkdownParser {
     changeDir;
     constructor(content, changeDir) {
@@ -19,13 +25,16 @@ export class ChangeParser extends MarkdownParser {
         if (!whatChanges) {
             throw new Error('Change must have a What Changes section');
         }
-        // Parse deltas from the What Changes section (simple format)
-        const simpleDeltas = this.parseDeltas(whatChanges);
-        // Check if there are spec files with delta format
-        const specsDir = path.join(this.changeDir, 'specs');
-        const deltaDeltas = await this.parseDeltaSpecs(specsDir);
-        // Combine both types of deltas, preferring delta format if available
-        const deltas = deltaDeltas.length > 0 ? deltaDeltas : simpleDeltas;
+        // Delta spec files that carry a delta section are the only source of
+        // structured deltas, even when those sections hold no entry archive can
+        // apply. Falling back to the "What Changes" prose then reported operations
+        // that never happen: a bullet-form REMOVED showed up as an invented
+        // MODIFIED. The prose (simple format) is still read when no spec file
+        // carries a delta section at all: a change with no spec files, or a legacy
+        // change whose specs/ hold full future-state specs.
+        const specFiles = await discoverSpecFiles(path.join(this.changeDir, 'specs'));
+        const { deltas: specDeltas, hasDeltaSections } = await this.parseDeltaSpecs(specFiles);
+        const deltas = hasDeltaSections ? specDeltas : this.parseDeltas(whatChanges);
         return {
             name,
             why: why.trim(),
@@ -37,23 +46,25 @@ export class ChangeParser extends MarkdownParser {
             },
         };
     }
-    async parseDeltaSpecs(specsDir) {
+    // The spec files come from discoverSpecFiles, which walks specs/ recursively
+    // so nested layouts like specs/<area>/<capability>/spec.md are parsed too (#1353)
+    async parseDeltaSpecs(specFiles) {
         const deltas = [];
-        // Discover delta specs recursively so nested layouts like
-        // specs/<area>/<capability>/spec.md are parsed too (#1353)
-        const specFiles = await discoverSpecFiles(specsDir);
+        let hasDeltaSections = false;
         for (const { id, specFile } of specFiles) {
             try {
                 const content = await fs.readFile(specFile, 'utf-8');
-                const specDeltas = this.parseSpecDeltas(id, content);
-                deltas.push(...specDeltas);
+                const plan = parseDeltaSpec(content);
+                if (Object.values(plan.sectionPresence).some(Boolean))
+                    hasDeltaSections = true;
+                deltas.push(...this.parseSpecDeltas(id, plan));
             }
             catch (error) {
                 // Spec file might not be readable, which is okay
                 continue;
             }
         }
-        return deltas;
+        return { deltas, hasDeltaSections };
     }
     /**
      * Read requirements from a delta section, ignoring headers that are not
@@ -75,89 +86,76 @@ export class ChangeParser extends MarkdownParser {
             children: section.children.filter((child) => /^Requirement:\s*\S/i.test(child.title.trim())),
         });
     }
-    parseSpecDeltas(specName, content) {
+    /**
+     * The deltas in one spec file, read by parseDeltaSpec — the reader archive
+     * applies — so what `show` reports is what archive will do. This used to be a
+     * second reader that disagreed with it: a bullet-form REMOVED was invisible,
+     * a repeated section header was read only once, and a RENAMED line written
+     * with `*` or `+` was dropped.
+     */
+    parseSpecDeltas(specName, plan) {
         const deltas = [];
-        const sections = this.parseSectionsFromContent(content);
         // Parse ADDED requirements
-        const addedSection = this.findSection(sections, 'ADDED Requirements');
-        if (addedSection) {
-            const requirements = this.parseRequirements(addedSection);
-            requirements.forEach(req => {
-                deltas.push({
-                    spec: specName,
-                    operation: 'ADDED',
-                    description: `Add requirement: ${req.text}`,
-                    // Provide both single and plural forms for compatibility
-                    requirement: req,
-                    requirements: [req],
-                });
+        this.toRequirements(plan.added).forEach(req => {
+            deltas.push({
+                spec: specName,
+                operation: 'ADDED',
+                description: `Add requirement: ${req.text}`,
+                // Provide both single and plural forms for compatibility
+                requirement: req,
+                requirements: [req],
             });
-        }
+        });
         // Parse MODIFIED requirements
-        const modifiedSection = this.findSection(sections, 'MODIFIED Requirements');
-        if (modifiedSection) {
-            const requirements = this.parseRequirements(modifiedSection);
-            requirements.forEach(req => {
-                deltas.push({
-                    spec: specName,
-                    operation: 'MODIFIED',
-                    description: `Modify requirement: ${req.text}`,
-                    requirement: req,
-                    requirements: [req],
-                });
+        this.toRequirements(plan.modified).forEach(req => {
+            deltas.push({
+                spec: specName,
+                operation: 'MODIFIED',
+                description: `Modify requirement: ${req.text}`,
+                requirement: req,
+                requirements: [req],
             });
-        }
-        // Parse REMOVED requirements
-        const removedSection = this.findSection(sections, 'REMOVED Requirements');
-        if (removedSection) {
-            const requirements = this.parseRequirements(removedSection);
-            requirements.forEach(req => {
-                deltas.push({
-                    spec: specName,
-                    operation: 'REMOVED',
-                    description: `Remove requirement: ${req.text}`,
-                    requirement: req,
-                    requirements: [req],
-                });
+        });
+        // Parse REMOVED requirements, in document order. A bullet-form entry
+        // carries only a name, so it reads as a header-form removal with no body.
+        const removedBlocks = [...plan.removedBlocks];
+        const removed = plan.removed.map((name) => {
+            const index = removedBlocks.findIndex((block) => block.name === name);
+            return index === -1 ? removedNameBlock(name) : removedBlocks.splice(index, 1)[0];
+        });
+        this.toRequirements(removed).forEach(req => {
+            deltas.push({
+                spec: specName,
+                operation: 'REMOVED',
+                description: `Remove requirement: ${req.text}`,
+                requirement: req,
+                requirements: [req],
             });
-        }
+        });
         // Parse RENAMED requirements
-        const renamedSection = this.findSection(sections, 'RENAMED Requirements');
-        if (renamedSection) {
-            const renames = this.parseRenames(renamedSection.content);
-            renames.forEach(rename => {
-                deltas.push({
-                    spec: specName,
-                    operation: 'RENAMED',
-                    description: `Rename requirement from "${rename.from}" to "${rename.to}"`,
-                    rename,
-                });
+        plan.renamed.forEach(rename => {
+            deltas.push({
+                spec: specName,
+                operation: 'RENAMED',
+                description: `Rename requirement from "${rename.from}" to "${rename.to}"`,
+                rename,
             });
-        }
+        });
         return deltas;
     }
-    parseRenames(content) {
-        const renames = [];
-        const lines = ChangeParser.normalizeContent(content).split('\n');
-        let currentRename = {};
-        for (const line of lines) {
-            const fromMatch = line.match(/^\s*-?\s*FROM:\s*`?###\s*Requirement:\s*(.+?)`?\s*$/);
-            const toMatch = line.match(/^\s*-?\s*TO:\s*`?###\s*Requirement:\s*(.+?)`?\s*$/);
-            if (fromMatch) {
-                currentRename.from = fromMatch[1].trim();
-            }
-            else if (toMatch) {
-                currentRename.to = toMatch[1].trim();
-                if (currentRename.from && currentRename.to) {
-                    renames.push({
-                        from: currentRename.from,
-                        to: currentRename.to,
-                    });
-                    currentRename = {};
-                }
-            }
-        }
-        return renames;
+    /**
+     * One Requirement per block, read by the same section parser (and the
+     * header filter above) as before, so text and scenarios are unchanged.
+     */
+    toRequirements(blocks) {
+        return blocks.flatMap((block) => {
+            const [headerLine, ...body] = block.raw.split('\n');
+            // Canonical header: the delta reader also accepts `###Requirement:` with
+            // no space, which the section parser would not see as a header.
+            const title = headerLine.replace(/^###\s*/, '').trim();
+            const [section] = this.parseSectionsFromContent([`### ${title}`, ...body].join('\n'));
+            return this.parseRequirements({ level: 2, title: '', content: '', children: [section] });
+        });
     }
     parseSectionsFromContent(content) {
         const normalizedContent = ChangeParser.normalizeContent(content);

package/dist/core/parsers/markdown-parser.js

@@ -1,4 +1,4 @@
-import { buildCodeFenceMask, extractRequirementText } from './requirement-text.js';
+import { buildCodeFenceMask, extractRequirementText, hasScenarioBody } from './requirement-text.js';
 export class MarkdownParser {
     lines;
     codeFenceLineMask;
@@ -130,8 +130,9 @@ export class MarkdownParser {
     parseScenarios(requirementSection) {
         const scenarios = [];
         for (const scenarioSection of requirementSection.children) {
-            // Store the raw text content of the scenario section
-            if (scenarioSection.content.trim()) {
+            // Store the raw text content of the scenario section. A header with no
+            // body is not a scenario; the delta counter applies the same rule.
+            if (hasScenarioBody(scenarioSection.content)) {
                 scenarios.push({
                     rawText: scenarioSection.content
                 });

package/dist/core/parsers/requirement-blocks.d.ts

@@ -14,9 +14,10 @@ export declare function normalizeRequirementName(name: string): string;
 /**
  * Case- and whitespace-insensitive fold of a requirement name. Requirement
  * matching itself is case-sensitive (normalizeRequirementName); this fold
- * exists only for typo detection - near-miss REMOVED headers and the
- * RENAMED+REMOVED cross-section conflict - where two spellings that differ
- * only in case or interior whitespace mean a mistake, never two requirements.
+ * exists only for typo detection - near-miss REMOVED, ADDED and RENAMED
+ * headers and the RENAMED+REMOVED cross-section conflict - where two spellings
+ * that differ only in case or interior whitespace mean a mistake, never two
+ * requirements.
  */
 export declare function foldRequirementName(name: string): string;
 /**
@@ -33,6 +34,42 @@ export interface SkippedHeader {
     section: string;
     line: number;
 }
+/**
+ * A `FROM:` or `TO:` line in `## RENAMED Requirements` that never formed a pair,
+ * recorded at the moment the reader steps over it.
+ *
+ * The pair reader used to carry one mutable `{ from, to }` and drop whatever did
+ * not fit: a second `FROM:` overwrote an unpaired first, a `TO:` with no pending
+ * `FROM:` vanished, and a trailing `FROM:` was forgotten at the end of the
+ * section. Nothing counted any of it, so a rename the author asked for could
+ * silently not happen - or, when the lines interleaved, a DIFFERENT requirement
+ * could be renamed under a name meant for another one.
+ *
+ * Recording them is what lets `validate` report the problem and `buildUpdatedSpec`
+ * refuse, rather than guess a pairing and rewrite the spec from it.
+ */
+export interface UnpairedRename {
+    side: 'FROM' | 'TO';
+    name: string;
+    line: number;
+}
+/**
+ * A canonical `### Requirement:` block that sits outside every delta section -
+ * under `## Notes`, under a misspelled `## Add Requirements`, or above the
+ * first `## ` header entirely.
+ *
+ * The delta reader only ever looks inside the four delta sections, so a block
+ * written anywhere else was dropped with no error, no warning and no note -
+ * even though it is well formed and reads exactly like one that would apply.
+ * That was the inconsistency worth closing: the ADJACENT mistake, a
+ * non-canonical `###` header INSIDE a delta section, has been reported as INFO
+ * since #498 (`skippedHeaders`), while the costlier one said nothing at all.
+ */
+export interface OrphanedRequirement {
+    name: string;
+    section: string | null;
+    line: number;
+}
 export interface DeltaPlan {
     added: RequirementBlock[];
     modified: RequirementBlock[];
@@ -42,6 +79,10 @@ export interface DeltaPlan {
         from: string;
         to: string;
     }>;
+    /** FROM:/TO: lines in RENAMED that never formed a pair. */
+    unpairedRenames: UnpairedRename[];
+    /** Canonical requirement blocks written outside every delta section. */
+    orphanedRequirements: OrphanedRequirement[];
     skippedHeaders: SkippedHeader[];
     sectionPresence: {
         added: boolean;
@@ -54,14 +95,45 @@ export interface DeltaPlan {
  * Parse a delta-formatted spec change file content into a DeltaPlan with raw blocks.
  */
 export declare function parseDeltaSpec(content: string): DeltaPlan;
+/** Both directions of the scenario-name comparison, plus the two totals. */
+export interface ScenarioNameDiff {
+    /** Names the current block has that the incoming block does not cover. */
+    missing: string[];
+    /** Names the incoming block introduces that the current block does not have. */
+    added: string[];
+    /** Level-4 headers in the current block. */
+    currentCount: number;
+    /** Level-4 headers in the incoming block. */
+    incomingCount: number;
+}
+/**
+ * Compare the scenario names of a current requirement block and an incoming
+ * (MODIFIED) one, in both directions.
+ *
+ * `missing` is the loss the guard exists to catch: a MODIFIED requirement
+ * replaces the whole block, so every name there would be dropped from the main
+ * spec. `added` and the two counts are reported alongside it, because they are
+ * the first thing a reader checks once it fires (#1697) - a block that omits
+ * two names and introduces two is shaped like a rename, one that omits two and
+ * introduces none is shaped like a truncation. Neither is proof, and intent is
+ * not recoverable from structure, so this decides nothing and only says what
+ * the two blocks contain.
+ */
+export declare function diffScenarioNames(current: RequirementBlock, incoming: RequirementBlock): ScenarioNameDiff;
 /**
  * Scenario names the current requirement block has and the incoming
  * (MODIFIED) block does not. A MODIFIED requirement replaces the whole block,
  * so every name reported here would be dropped from the main spec.
  *
- * Shared by archive (which refuses to apply the block) and validate (which
- * reports the same loss at authoring time, #1477), so the two cannot disagree
- * about what counts as a dropped scenario.
+ * The `missing` half of diffScenarioNames, which archive (refusing to apply
+ * the block) and validate (reporting the same loss at authoring time, #1477)
+ * both go through, so the two cannot disagree about what counts as a dropped
+ * scenario.
  */
 export declare function findMissingCurrentScenarios(current: RequirementBlock, incoming: RequirementBlock): string[];
+/**
+ * The one sentence archive and validate both append when the guard fires, so
+ * the counts a reader sees cannot differ between the two commands.
+ */
+export declare function describeScenarioBalance(diff: ScenarioNameDiff): string;
 //# sourceMappingURL=requirement-blocks.d.ts.map

package/dist/core/parsers/requirement-blocks.js

@@ -1,13 +1,18 @@
 import { buildCodeFenceMask, SCENARIO_HEADER } from './requirement-text.js';
 export function normalizeRequirementName(name) {
-    return name.trim();
+    // An ATX heading may end in a closing run of `#`s: `### Requirement: Foo ###`
+    // renders as `Foo`, so the run is not part of the name. As for scenario names,
+    // only a run preceded by a space or tab closes the heading, so `C#` keeps its
+    // `#`, and `[ \t]` rather than `\s` keeps an NBSP-separated run in the name.
+    return name.replace(/[ \t]+#+[ \t]*$/, '').trim();
 }
 /**
  * Case- and whitespace-insensitive fold of a requirement name. Requirement
  * matching itself is case-sensitive (normalizeRequirementName); this fold
- * exists only for typo detection - near-miss REMOVED headers and the
- * RENAMED+REMOVED cross-section conflict - where two spellings that differ
- * only in case or interior whitespace mean a mistake, never two requirements.
+ * exists only for typo detection - near-miss REMOVED, ADDED and RENAMED
+ * headers and the RENAMED+REMOVED cross-section conflict - where two spellings
+ * that differ only in case or interior whitespace mean a mistake, never two
+ * requirements.
  */
 export function foldRequirementName(name) {
     return normalizeRequirementName(name).toLowerCase().replace(/\s+/g, ' ');
@@ -117,8 +122,11 @@ export function parseDeltaSpec(content) {
     const removedNames = removedLookup.bodies.flatMap((body) => parseRemovedNames(body));
     const removedBlocks = removedLookup.bodies.flatMap((body) => parseRequirementBlocksFromSection(body));
     // Pairs are read per section, so a FROM in one copy of the header can never
-    // pair with a TO in another.
-    const renamedPairs = renamedLookup.bodies.flatMap((body) => parseRenamedPairs(body));
+    // pair with a TO in another: a FROM left pending at the end of one copy is
+    // reported as unpaired rather than carried into the next.
+    const unpairedRenames = [];
+    const renamedPairs = renamedLookup.bodies.flatMap((body) => parseRenamedPairs(body, unpairedRenames));
+    unpairedRenames.sort((a, b) => a.line - b.line);
     skippedHeaders.sort((a, b) => a.line - b.line);
     return {
         added,
@@ -126,6 +134,8 @@ export function parseDeltaSpec(content) {
         removed: removedNames,
         removedBlocks,
         renamed: renamedPairs,
+        unpairedRenames,
+        orphanedRequirements: findOrphanedRequirements(lines, fenceMask),
         skippedHeaders,
         sectionPresence: {
             added: addedLookup.found,
@@ -135,6 +145,48 @@ export function parseDeltaSpec(content) {
         },
     };
 }
+/**
+ * The four section titles the delta reader acts on, folded the way
+ * `getSectionsCaseInsensitive` folds them. Matching the reader exactly matters:
+ * a looser test (say, any run of whitespace) would treat `## ADDED  Requirements`
+ * as a delta section here while the reader ignores it, and the requirements
+ * under it would be dropped without this warning.
+ */
+const DELTA_SECTION_TITLES = new Set(['ADDED Requirements', 'MODIFIED Requirements', 'REMOVED Requirements', 'RENAMED Requirements'].map((title) => title.toLowerCase()));
+/**
+ * Every canonical `### Requirement:` header that is not inside a delta section,
+ * in document order.
+ *
+ * Walks the whole file rather than the parsed sections so a requirement written
+ * ABOVE the first `## ` header is reported too - it is dropped just as silently
+ * as one under `## Notes`. Fenced lines are skipped, so a requirement shown
+ * inside a markdown example is not mistaken for an authored one.
+ */
+function findOrphanedRequirements(lines, fenceMask) {
+    const orphans = [];
+    let section = null;
+    for (let i = 0; i < lines.length; i++) {
+        if (fenceMask[i])
+            continue;
+        // The same `## ` test splitTopLevelSections uses, so both agree on sections.
+        const sectionMatch = lines[i].match(/^(##)\s+(.+)$/);
+        if (sectionMatch) {
+            section = sectionMatch[2].trim();
+            continue;
+        }
+        if (section !== null && DELTA_SECTION_TITLES.has(section.toLowerCase()))
+            continue;
+        const header = lines[i].match(REQUIREMENT_HEADER_REGEX);
+        if (header) {
+            orphans.push({
+                name: normalizeRequirementName(header[1]),
+                section,
+                line: i + 1,
+            });
+        }
+    }
+    return orphans;
+}
 /**
  * Every `## ` section, as a LIST rather than a title-keyed record.
  *
@@ -271,18 +323,35 @@ function parseRemovedNames(sectionBody) {
     return names;
 }
 /**
- * `FROM:`/`TO:` rename pairs from `## RENAMED Requirements`, in document order.
+ * Read `FROM:`/`TO:` entries into rename pairs, recording every line that never
+ * formed one.
+ *
+ * A pair is a `FROM:` followed by a `TO:` with no second `FROM:` in between -
+ * the shape the documented format uses. Anything else is reported through
+ * `unpaired` rather than absorbed:
+ *
+ *   - a `FROM:` displaced by another `FROM:` before its `TO:` arrived
+ *   - a `TO:` with no pending `FROM:`
+ *   - a `FROM:` still pending when the section ends
+ *
+ * Silently dropping these is what let a requested rename not happen, and what
+ * let interleaved lines (`FROM a`, `FROM b`, `TO x`, `TO y`) pair b with x -
+ * renaming a requirement the author never named, under a name meant for a
+ * different one. Callers refuse the delta instead of guessing.
  *
  * The bullet is optional, and every CommonMark bullet marker is accepted: a
  * rename written with `*` or `+` used to match nothing at all, so the rename
  * silently never happened while archive still reported success.
  */
-function parseRenamedPairs(sectionBody) {
-    const { lines, fenceMask } = sectionBody;
+function parseRenamedPairs(sectionBody, unpaired) {
+    const { lines, fenceMask, bodyStartLine } = sectionBody;
     if (lines.length === 0)
         return [];
     const pairs = [];
-    let current = {};
+    let pending;
+    const drop = (side, name, line) => {
+        unpaired?.push({ side, name, line });
+    };
     for (let i = 0; i < lines.length; i++) {
         if (fenceMask[i])
             continue;
@@ -293,49 +362,97 @@ function parseRenamedPairs(sectionBody) {
         const fromMatch = line.match(/^\s*[-*+]?\s*FROM:\s*`?###\s*Requirement:\s*(.+?)`?\s*$/);
         const toMatch = line.match(/^\s*[-*+]?\s*TO:\s*`?###\s*Requirement:\s*(.+?)`?\s*$/);
         if (fromMatch) {
-            current.from = normalizeRequirementName(fromMatch[1]);
+            if (pending)
+                drop('FROM', pending.name, pending.line);
+            pending = { name: normalizeRequirementName(fromMatch[1]), line: bodyStartLine + i };
         }
         else if (toMatch) {
-            current.to = normalizeRequirementName(toMatch[1]);
-            if (current.from && current.to) {
-                pairs.push({ from: current.from, to: current.to });
-                current = {};
+            const to = normalizeRequirementName(toMatch[1]);
+            if (!pending) {
+                drop('TO', to, bodyStartLine + i);
+                continue;
             }
+            pairs.push({ from: pending.name, to });
+            pending = undefined;
         }
     }
+    if (pending)
+        drop('FROM', pending.name, pending.line);
     return pairs;
 }
+/**
+ * Compare the scenario names of a current requirement block and an incoming
+ * (MODIFIED) one, in both directions.
+ *
+ * `missing` is the loss the guard exists to catch: a MODIFIED requirement
+ * replaces the whole block, so every name there would be dropped from the main
+ * spec. `added` and the two counts are reported alongside it, because they are
+ * the first thing a reader checks once it fires (#1697) - a block that omits
+ * two names and introduces two is shaped like a rename, one that omits two and
+ * introduces none is shaped like a truncation. Neither is proof, and intent is
+ * not recoverable from structure, so this decides nothing and only says what
+ * the two blocks contain.
+ */
+export function diffScenarioNames(current, incoming) {
+    const currentNames = parseScenarioBlocks(current.raw).map((scenario) => scenario.name);
+    const incomingNames = parseScenarioBlocks(incoming.raw).map((scenario) => scenario.name);
+    // Multiplicity-aware: a name present N times on one side and M times on the
+    // other leaves max(0, N - M) instances unmatched. Set membership would treat
+    // N>M as fully covered and let archive silently drop duplicates (residual
+    // #1246 / duplicate-scenario-name blind spot).
+    const unmatched = (names, against) => {
+        const remaining = new Map();
+        for (const name of against)
+            remaining.set(name, (remaining.get(name) ?? 0) + 1);
+        const out = [];
+        for (const name of names) {
+            const left = remaining.get(name) ?? 0;
+            if (left > 0)
+                remaining.set(name, left - 1);
+            else
+                out.push(name);
+        }
+        return out;
+    };
+    return {
+        missing: unmatched(currentNames, incomingNames),
+        added: unmatched(incomingNames, currentNames),
+        currentCount: currentNames.length,
+        incomingCount: incomingNames.length,
+    };
+}
 /**
  * Scenario names the current requirement block has and the incoming
  * (MODIFIED) block does not. A MODIFIED requirement replaces the whole block,
  * so every name reported here would be dropped from the main spec.
  *
- * Shared by archive (which refuses to apply the block) and validate (which
- * reports the same loss at authoring time, #1477), so the two cannot disagree
- * about what counts as a dropped scenario.
+ * The `missing` half of diffScenarioNames, which archive (refusing to apply
+ * the block) and validate (reporting the same loss at authoring time, #1477)
+ * both go through, so the two cannot disagree about what counts as a dropped
+ * scenario.
  */
 export function findMissingCurrentScenarios(current, incoming) {
-    // Multiplicity-aware: a name present N times in current and M times in
-    // incoming means max(0, N - M) instances are missing. Set membership would
-    // treat N>M as fully covered and let archive silently drop duplicates
-    // (residual #1246 / duplicate-scenario-name blind spot).
-    const remainingIncoming = new Map();
-    for (const scenario of parseScenarioBlocks(incoming.raw)) {
-        const name = scenario.name;
-        remainingIncoming.set(name, (remainingIncoming.get(name) ?? 0) + 1);
-    }
-    const missing = [];
-    for (const scenario of parseScenarioBlocks(current.raw)) {
-        const name = scenario.name;
-        const remaining = remainingIncoming.get(name) ?? 0;
-        if (remaining > 0) {
-            remainingIncoming.set(name, remaining - 1);
-        }
-        else {
-            missing.push(name);
-        }
+    return diffScenarioNames(current, incoming).missing;
+}
+/** At most this many added names are listed before the rest are counted. */
+const MAX_LISTED_ADDED_SCENARIOS = 3;
+/**
+ * The one sentence archive and validate both append when the guard fires, so
+ * the counts a reader sees cannot differ between the two commands.
+ */
+export function describeScenarioBalance(diff) {
+    const count = (value) => `${value} ${value === 1 ? 'scenario' : 'scenarios'}`;
+    const scale = `The modified block has ${count(diff.incomingCount)}; the current spec has ${count(diff.currentCount)}.`;
+    if (diff.added.length === 0) {
+        return `${scale} It adds none.`;
     }
-    return missing;
+    const listed = diff.added
+        .slice(0, MAX_LISTED_ADDED_SCENARIOS)
+        .map((name) => `"${name}"`)
+        .join(', ');
+    const rest = diff.added.length - MAX_LISTED_ADDED_SCENARIOS;
+    const names = rest > 0 ? `${listed} and ${rest} more` : listed;
+    return `${scale} It adds ${count(diff.added.length)} not in the current spec: ${names}.`;
 }
 /**
  * Any non-fenced level-4 header on the given (masked) line. Reuses the spec

package/dist/core/parsers/requirement-text.d.ts

@@ -15,8 +15,17 @@ export { buildCodeFenceMask } from './code-fence.js';
  * as a scenario, so the delta counter must too (parity). The delta/loss path
  * reuses this exact constant via `scenarioHeaderAt` in requirement-blocks.ts;
  * keep both paths on it rather than reintroducing a separate `Scenario:` regex.
+ * A header alone is not yet a scenario on either path: see hasScenarioBody.
  */
 export declare const SCENARIO_HEADER: RegExp;
+/**
+ * Whether a scenario's body has content. The spec path
+ * (`MarkdownParser.parseScenarios`) drops a scenario whose body is empty, so
+ * the delta counter must too (parity): otherwise `validate` accepts a
+ * requirement whose only scenario is a bare header, and archive rejects it when
+ * it validates the rebuilt spec.
+ */
+export declare function hasScenarioBody(body: string): boolean;
 /**
  * The one predicate for normative-keyword detection. Matches `SHALL` or `MUST`
  * as whole words so the change-delta reader and the schema-based reader accept
@@ -49,8 +58,10 @@ export declare function extractRequirementBody(bodyLines: string[]): string;
 export declare function extractRequirementText(headerTitle: string, bodyLines: string[]): string;
 /**
  * Count the real scenarios in a requirement block: `#### ` headers on non-fenced
- * lines. A `#### Scenario:` that lives inside a fenced example is not a real
- * scenario and is not counted.
+ * lines whose body has content. A `#### Scenario:` that lives inside a fenced
+ * example is not a real scenario and is not counted.
  */
 export declare function countScenarios(bodyLines: string[]): number;
+/** Count the `#### ` headers in a requirement block that have no body under them. */
+export declare function countEmptyScenarios(bodyLines: string[]): number;
 //# sourceMappingURL=requirement-text.d.ts.map