@seanmars/tospec 0.19.0-beta.1 → 0.19.0-beta.13

package/dist/core/validation/validator.js

@@ -1,16 +1,54 @@
 import { readFileSync, promises as fs } from 'fs';
 import path from 'path';
-import { SpecSchema, ChangeSchema } from '../schemas/index.js';
+import { SpecSchema } from '../schemas/index.js';
 import { MarkdownParser } from '../parsers/markdown-parser.js';
-import { ChangeParser } from '../parsers/change-parser.js';
-import { MIN_PURPOSE_LENGTH, MAX_REQUIREMENT_TEXT_LENGTH, VALIDATION_MESSAGES } from './constants.js';
+import { MIN_PURPOSE_LENGTH, MAX_REQUIREMENT_TEXT_LENGTH, MAX_DELTAS_PER_CHANGE, VALIDATION_MESSAGES } from './constants.js';
+import { proseLength } from './prose-length.js';
 import { parseDeltaSpec, normalizeRequirementName, extractRequirementsSection } from '../parsers/requirement-blocks.js';
-import { extractRequirementBody as extractRequirementBodyShared, containsShallOrMust as containsShallOrMustShared, analyzeScenarios, scanCodeFences, findMissingScenarios, } from '../parsers/requirement-text.js';
+import { extractRequirementBody as extractRequirementBodyShared, containsShallOrMust, analyzeScenarios, scanCodeFences, findMissingScenarios, findDroppedBullets, withoutScenarios, normalizeDocument, } from '../parsers/requirement-text.js';
 import { findMainSpecStructureIssues } from '../parsers/spec-structure.js';
 import { findPurposePlaceholderIssue } from './purpose-placeholder.js';
 import { FileSystemUtils, extractNameFromPath, isMissingPathError } from '../../utils/file-system.js';
-import { findSpecFiles } from '../../utils/spec-files.js';
-import { findSpecUpdates, buildUpdatedSpec } from '../specs-apply.js';
+import { findAllMarkdownFiles } from '../../utils/spec-files.js';
+import { findSpecUpdates, buildUpdatedSpec, extractDeltaPurpose } from '../specs-apply.js';
+/**
+ * The one place the `## REMOVED Scenarios` grammar is spelled out in a
+ * message. Both the "omits scenario(s)" error and the empty-section error
+ * point here, so an author who reached either sees the exact lines to write
+ * instead of being sent to the template.
+ */
+const REMOVED_SCENARIOS_GRAMMAR = 'Each entry is three bullets: "- Requirement: `<name>`" / "- Scenario: `<name>`" / "- Reason: <why>".';
+/**
+ * Merge notices the archive dry run forwards as validation warnings: a REMOVED
+ * block naming something the target spec does not have, so archiving deletes
+ * nothing. Matched by code, not message text, so rewording a notice cannot
+ * switch the check off.
+ */
+const REMOVED_NOOP_NOTICE_CODES = new Set([
+    'archive_removed_requirement_absent',
+    'archive_removed_ignored_new_spec',
+]);
+/**
+ * Merge failures the structural pass already reports under its own wording:
+ * duplicate or cross-section names (`validation failed - ...`), a section that
+ * parsed to nothing, and a MODIFIED that drops a scenario. Matched by the
+ * fixed prefix each message opens with; the rest of a message carries names
+ * that vary per delta.
+ */
+const STRUCTURAL_MERGE_FAILURE = /( validation failed - |^Delta parsing found no operations|current spec contains scenario\(s\) not present)/;
+/**
+ * One `path` notation across the report. Zod hands back a segment array that
+ * `join('.')` renders as `requirements.0.scenarios`, while every hand-written
+ * rule here writes `requirements[0]` — so the same report used two spellings
+ * for the same address and neither was safely parseable.
+ */
+function formatIssuePath(segments) {
+    return segments.reduce((acc, segment) => {
+        if (typeof segment === 'number')
+            return `${acc}[${segment}]`;
+        return acc ? `${acc}.${String(segment)}` : String(segment);
+    }, '');
+}
 export class Validator {
     strictMode;
     constructor(strictMode = false) {
@@ -28,14 +66,10 @@ export class Validator {
                 { level: 'ERROR', path: 'file', message: this.enrichTopLevelError(specName, baseMessage) },
             ]);
         }
-        // Everything past the read is identical to the content path — keeping one
-        // body is what stops `validate` and `archive` grading the same spec
-        // differently.
+        // One body past the read, so `validate` and `archive` cannot grade the same
+        // spec differently.
         return this.validateSpecContent(specName, content);
     }
-    /**
-     * Validate spec content from a string (used for pre-write validation of rebuilt specs)
-     */
     async validateSpecContent(specName, content) {
         const issues = [];
         try {
@@ -54,69 +88,37 @@ export class Validator {
         }
         return this.createReport(issues);
     }
-    async validateChange(filePath) {
-        const issues = [];
-        const changeName = extractNameFromPath(filePath);
-        try {
-            const content = readFileSync(filePath, 'utf-8');
-            const changeDir = path.dirname(filePath);
-            const parser = new ChangeParser(content, changeDir);
-            const change = await parser.parseChangeWithDeltas(changeName);
-            const result = ChangeSchema.safeParse(change);
-            if (!result.success) {
-                issues.push(...this.convertZodErrors(result.error));
-            }
-            issues.push(...this.applyChangeRules(change, content));
-        }
-        catch (error) {
-            const baseMessage = error instanceof Error ? error.message : 'Unknown error';
-            const enriched = this.enrichTopLevelError(changeName, baseMessage);
-            issues.push({
-                level: 'ERROR',
-                path: 'file',
-                message: enriched,
-            });
-        }
-        return this.createReport(issues);
-    }
     /**
-     * Validate delta-formatted spec files under a change directory.
-     * Enforces:
-     * - At least one delta across all files
-     * - ADDED/MODIFIED: each requirement has SHALL/MUST and at least one scenario
-     * - REMOVED: names only; no scenario/description required
-     * - RENAMED: pairs well-formed
-     * - No duplicates within sections; no cross-section conflicts per spec
-     * - MODIFIED: no scenario the current main spec still has is dropped
+     * Validate delta-formatted spec files under a change directory: at least one
+     * delta overall, ADDED/MODIFIED requirements carrying SHALL/MUST and a
+     * scenario, well-formed REMOVED (names only) and RENAMED (FROM:/TO: pairs)
+     * entries, no duplicate or cross-section names, and no scenario the current
+     * main spec still has dropped by a MODIFIED.
      *
-     * `mainSpecsDir` enables that last rule; without it the scenario-loss check is
-     * skipped, because there is nothing to compare against. Callers that have the
-     * project root should always pass it — archive refuses these deltas either
-     * way, and the check only decides whether the user learns now or at archive
-     * time.
+     * `mainSpecsDir` enables that last rule; without it there is nothing to
+     * compare against, so it is skipped. Archive refuses such deltas either way.
+     *
+     * `archivePreflight` is opt-out because the dry run rebuilds every updated
+     * spec. For `tospec validate` that is the point; for `archive` it is
+     * duplication, since the real merge follows moments later.
      */
-    async validateChangeDeltaSpecs(changeDir, mainSpecsDir) {
+    async validateChangeDeltaSpecs(changeDir, mainSpecsDir, options = {}) {
+        const archivePreflight = options.archivePreflight ?? true;
         const issues = [];
         const specsDir = path.join(changeDir, 'specs');
         let totalDeltas = 0;
         let hasMisplacedSpec = false;
         const missingHeaderSpecs = [];
-        const emptySectionSpecs = [];
+        const emptySections = [];
         try {
-            // The walk below is recursive, but its purpose is to *reject* anything
-            // outside specs/<capability>/spec.md, not to support it. The layout is
-            // fixed at exactly one directory level; see
-            // tospec/decisions/20260730_014309-delta-spec-layout-one-level.md, which
-            // reverses the nested multi-area support added in #1182b. Only validation
-            // ever went recursive — the merge path (findSpecUpdates) never did — so a
-            // misplaced file that validates clean is a file that archives into
-            // nothing. Validation is the only place that can catch it.
+            // The walk below is recursive in order to *reject* anything outside
+            // specs/<capability>/spec.md: the layout is fixed at exactly one directory
+            // level (tospec/decisions/20260730_014309-delta-spec-layout-one-level.md).
+            // findSpecUpdates never went recursive, so a misplaced file that validates
+            // clean is a file that archives into nothing.
             const rootSpecPath = path.join(specsDir, 'spec.md');
-            // A spec.md directly at the specs/ root has no capability folder, so the
-            // apply/archive merge path (findSpecUpdates) drops it: without this error
-            // the change validates clean and archives while its requirements never
-            // reach the main specs. Only a regular file counts — a *directory* named
-            // spec.md is a capability folder like any other.
+            // Only a regular file counts — a *directory* named spec.md is a capability
+            // folder like any other.
             const rootSpecStat = await fs.stat(rootSpecPath).catch(() => null);
             if (rootSpecStat?.isFile() === true) {
                 hasMisplacedSpec = true;
@@ -126,15 +128,20 @@ export class Validator {
                     message: 'Delta spec found at specs/spec.md. Delta specs must live in a capability folder (e.g. specs/<capability>/spec.md) — a file at the specs/ root is ignored when the change is applied or archived.',
                 });
             }
-            // Report each misplaced file once, here, and drop it from the delta pass
-            // below — validating it as if it were a real delta would contradict the
-            // error that just said it will never be applied.
+            // Report each misplaced file once and drop it from the delta pass below —
+            // validating it as a real delta would contradict the error that just said
+            // it will never be applied.
             const specFiles = [];
-            for (const specFile of await findSpecFiles(specsDir)) {
+            for (const specFile of await findAllMarkdownFiles(specsDir)) {
                 if (specFile === rootSpecPath)
                     continue; // already reported above
                 const entryPath = FileSystemUtils.toPosixPath(path.relative(specsDir, specFile));
                 const segments = entryPath.split('/');
+                // A stray .md directly at specs/ is not this guard's concern: archive's
+                // orphan backstop treats it as clutter rather than a lost delta, and the
+                // two must keep agreeing.
+                if (segments.length === 1)
+                    continue;
                 if (segments.length > 2) {
                     hasMisplacedSpec = true;
                     // The fix is mechanical, so name the flattened path outright:
@@ -147,10 +154,9 @@ export class Validator {
                     });
                     continue;
                 }
-                // fast-glob (which computes artifact status from the schema's
-                // specs/*/spec.md) skips dot-directories, while the merge path's
-                // readdir does not. A dot capability would archive without ever
-                // showing as done — the same class of silent divergence.
+                // fast-glob (which computes artifact status) skips dot-directories while
+                // the merge path's readdir does not, so a dot capability would archive
+                // without ever showing done.
                 if (segments[0].startsWith('.')) {
                     hasMisplacedSpec = true;
                     issues.push({
@@ -160,21 +166,44 @@ export class Validator {
                     });
                     continue;
                 }
+                // Right folder, wrong basename. findSpecFiles filters on
+                // basename === 'spec.md', so the merge path silently drops the file;
+                // findAllMarkdownFiles is what makes it visible here at all.
+                if (segments[1] !== 'spec.md') {
+                    hasMisplacedSpec = true;
+                    issues.push({
+                        level: 'ERROR',
+                        path: entryPath,
+                        message: `Delta spec found at specs/${entryPath}. A capability folder holds exactly specs/${segments[0]}/spec.md — a different filename is ignored when the change is applied or archived. Rename it to specs/${segments[0]}/spec.md.`,
+                    });
+                    continue;
+                }
                 specFiles.push(specFile);
             }
             for (const specFile of specFiles) {
+                const entryPath = FileSystemUtils.toPosixPath(path.relative(specsDir, specFile));
                 let content;
                 try {
                     content = await fs.readFile(specFile, 'utf-8');
                 }
-                catch {
+                catch (error) {
+                    // A file the walk just listed but cannot be read (EACCES, EIO) is a
+                    // delta, not an absence: skipping it let a change whose only delta
+                    // was unreadable validate clean and fail inside archive instead. Only
+                    // a path that vanished between the walk and the read may be skipped.
+                    if (isMissingPathError(error))
+                        continue;
+                    issues.push({
+                        level: 'ERROR',
+                        path: entryPath,
+                        message: `Delta spec specs/${entryPath} exists but could not be read, so it was not validated: ${error instanceof Error ? error.message : String(error)}`,
+                    });
                     continue;
                 }
                 const plan = parseDeltaSpec(content);
-                const entryPath = FileSystemUtils.toPosixPath(path.relative(specsDir, specFile));
-                // An unclosed fence masks every following line — surface it instead
-                // of silently hiding the rest of the document (report 2.3).
-                const fenceScan = scanCodeFences(content.split(/\r?\n/));
+                // An unclosed fence masks every following line — surface it instead of
+                // silently hiding the rest of the document.
+                const fenceScan = scanCodeFences(normalizeDocument(content).split('\n'));
                 if (fenceScan.unclosedFenceLine !== null) {
                     issues.push({
                         level: 'ERROR',
@@ -183,12 +212,14 @@ export class Validator {
                         message: `Code fence opened at line ${fenceScan.unclosedFenceLine} is never closed — all content after it is invisible to the parser. Close the fence.`,
                     });
                 }
-                // Two identical delta headers are an editing accident (a manual edit, a
-                // badly resolved merge, an agent emitting the section twice), and
-                // combining them would guess which one the author meant. The parser no
-                // longer discards the repeated occurrences, so refusing here costs
-                // nothing that was previously reported: before, the first occurrence's
-                // requirements were invisible to this very check.
+                // A new capability's `## Purpose` is carried verbatim into the main spec
+                // archive creates, so the main-spec Purpose rules must run before the
+                // copy — otherwise the change archives and only then fails
+                // `validate --all --strict`, from a source now under changes/archive/.
+                // New capabilities only: an existing one owns its Purpose.
+                issues.push(...(await this.collectDeltaPurposeIssues(content, entryPath, mainSpecsDir)));
+                // Two identical delta headers are an editing accident, and combining
+                // them would guess which one the author meant.
                 for (const duplicate of plan.duplicateSections) {
                     issues.push({
                         level: 'ERROR',
@@ -197,31 +228,46 @@ export class Validator {
                         message: `Delta section "${duplicate.title}" appears more than once (lines ${duplicate.lines.join(', ')}). Merge them into a single section — two headers with the same name are ambiguous about which requirements belong to which.`,
                     });
                 }
-                const sectionNames = [];
-                if (plan.sectionPresence.added)
-                    sectionNames.push('## ADDED Requirements');
-                if (plan.sectionPresence.modified)
-                    sectionNames.push('## MODIFIED Requirements');
-                if (plan.sectionPresence.removed)
-                    sectionNames.push('## REMOVED Requirements');
-                if (plan.sectionPresence.renamed)
-                    sectionNames.push('## RENAMED Requirements');
-                const hasSections = sectionNames.length > 0;
+                // A present section that yields no entry is a grammar miss, not an
+                // empty section: the author wrote something there. Left unreported, the
+                // MODIFIED block keeps failing the scenario-loss check with no sign that
+                // its declaration was skipped.
+                if (plan.sectionPresence.removedScenarios && plan.removedScenarios.length === 0) {
+                    issues.push({
+                        level: 'ERROR',
+                        path: entryPath,
+                        message: `"## REMOVED Scenarios" declares nothing the parser recognises. ${REMOVED_SCENARIOS_GRAMMAR}`,
+                    });
+                }
+                const hasSections = plan.sectionPresence.added ||
+                    plan.sectionPresence.modified ||
+                    plan.sectionPresence.removed ||
+                    plan.sectionPresence.renamed;
                 const hasEntries = plan.added.length + plan.modified.length + plan.removed.length + plan.renamed.length > 0;
+                // hasEntries sums all four categories, so once it is false every section
+                // present in sectionPresence is individually empty too.
                 if (!hasEntries) {
-                    if (hasSections)
-                        emptySectionSpecs.push({ path: entryPath, sections: sectionNames });
-                    else
+                    if (hasSections) {
+                        if (plan.sectionPresence.added)
+                            emptySections.push({ path: entryPath, kind: 'added', header: '## ADDED Requirements' });
+                        if (plan.sectionPresence.modified)
+                            emptySections.push({ path: entryPath, kind: 'modified', header: '## MODIFIED Requirements' });
+                        if (plan.sectionPresence.removed)
+                            emptySections.push({ path: entryPath, kind: 'removed', header: '## REMOVED Requirements' });
+                        if (plan.sectionPresence.renamed)
+                            emptySections.push({ path: entryPath, kind: 'renamed', header: '## RENAMED Requirements' });
+                    }
+                    else {
                         missingHeaderSpecs.push(entryPath);
+                    }
                 }
                 const addedNames = new Set();
                 const modifiedNames = new Set();
                 const removedNames = new Set();
                 const renamedFrom = new Set();
                 const renamedTo = new Set();
-                // ADDED and MODIFIED carry identical per-requirement rules. One body
-                // means a new rule cannot land on only one of the two sections; the
-                // outer loop preserves the all-ADDED-then-all-MODIFIED issue order.
+                // ADDED and MODIFIED carry identical per-requirement rules, so one body
+                // stops a new rule landing on only one of them.
                 for (const [section, blocks, seen] of [
                     ['ADDED', plan.added, addedNames],
                     ['MODIFIED', plan.modified, modifiedNames],
@@ -239,25 +285,37 @@ export class Validator {
                         if (!requirementText) {
                             issues.push({ level: 'ERROR', path: entryPath, message: `${section} "${block.name}" is missing requirement text` });
                         }
-                        else if (!this.containsShallOrMust(requirementText)) {
+                        else if (!containsShallOrMust(requirementText)) {
                             // WARNING, not ERROR: the keyword check is English-only, so at
-                            // ERROR it blocked any requirement whose body states its
-                            // obligation in another language — enforcing a documentation
-                            // language, not normative strength. `--strict` still refuses it
-                            // (strictMode counts warnings as fatal).
-                            // Decision: tospec/decisions/20260814_134116-shall-must-missing-is-a-warning.md
-                            issues.push({ level: 'WARNING', path: entryPath, message: this.buildMissingShallOrMustMessage(`${section} "${block.name}"`, block.name) });
+                            // ERROR it blocked requirements written in another language.
+                            // `--strict` still refuses it.
+                            // tospec/decisions/20260814_134116-shall-must-missing-is-a-warning.md
+                            issues.push({
+                                level: 'WARNING',
+                                path: entryPath,
+                                ...this.buildMissingShallOrMustMessage(`${section} "${block.name}"`, block.name),
+                            });
                         }
                         issues.push(...this.collectScenarioIssues(section, block, entryPath));
                     }
                 }
-                if (mainSpecsDir !== undefined && plan.modified.length > 0) {
+                // Also entered on declarations alone: a `## REMOVED Scenarios` with no
+                // MODIFIED block matches nothing by construction, and gating on
+                // MODIFIED meant the "declaration matched nothing" error below could
+                // never fire for the one delta shape where it is always true. The
+                // declaration removes nothing by itself (the MODIFIED omission is the
+                // mechanism), so such a change archived with the scenario intact.
+                // tospec/decisions/20260918_230803-removed-scenarios-is-the-declared-path.md
+                if (mainSpecsDir !== undefined && (plan.modified.length > 0 || plan.removedScenarios.length > 0)) {
+                    const renamedToFrom = new Map();
+                    for (const { from, to } of plan.renamed) {
+                        renamedToFrom.set(normalizeRequirementName(to), from);
+                    }
                     // entryPath is always "<capability>/spec.md" here — misplaced and
                     // dot-prefixed files were reported and dropped above.
-                    issues.push(...(await this.collectDroppedScenarioIssues(mainSpecsDir, entryPath.split('/')[0], plan.modified, entryPath)));
+                    issues.push(...(await this.collectDroppedScenarioIssues(mainSpecsDir, entryPath.split('/')[0], plan.modified, entryPath, renamedToFrom, plan.removedScenarios)));
                 }
-                // Validate REMOVED — the template requires Reason and Migration
-                // fields on every entry (report 2.4).
+                // The template requires Reason and Migration on every REMOVED entry.
                 for (const entry of plan.removedEntries) {
                     const key = normalizeRequirementName(entry.name);
                     totalDeltas++;
@@ -284,7 +342,7 @@ export class Validator {
                         });
                     }
                 }
-                // Orphaned FROM:/TO: lines were silently dropped before (report 2.4).
+                // Orphaned FROM:/TO: lines would otherwise be dropped silently.
                 for (const renamedIssue of plan.renamedIssues) {
                     const description = renamedIssue.kind === 'from-without-to'
                         ? `RENAMED FROM "${renamedIssue.name}" (line ${renamedIssue.line}) has no matching TO: line`
@@ -296,7 +354,6 @@ export class Validator {
                         message: `${description} — write RENAMED entries as a FROM:/TO: pair.`,
                     });
                 }
-                // Validate RENAMED pairs
                 for (const { from, to } of plan.renamed) {
                     const fromKey = normalizeRequirementName(from);
                     const toKey = normalizeRequirementName(to);
@@ -314,7 +371,6 @@ export class Validator {
                         renamedTo.add(toKey);
                     }
                 }
-                // Cross-section conflicts (within the same spec file)
                 for (const n of modifiedNames) {
                     if (removedNames.has(n)) {
                         issues.push({ level: 'ERROR', path: entryPath, message: `Requirement present in both MODIFIED and REMOVED: "${n}"` });
@@ -340,14 +396,18 @@ export class Validator {
                 }
             }
         }
-        catch {
-            // If no specs dir, treat as no deltas
+        catch (error) {
+            // Only an absent specs dir means "no deltas". The walk and the reads
+            // above already answer that on their own, so anything else reaching here
+            // is a real failure that a bare catch used to turn into a clean verdict.
+            if (!isMissingPathError(error))
+                throw error;
         }
-        for (const { path: specPath, sections } of emptySectionSpecs) {
+        for (const { path: specPath, kind, header } of emptySections) {
             issues.push({
                 level: 'ERROR',
                 path: specPath,
-                message: `Delta sections ${this.formatSectionList(sections)} were found, but no requirement entries parsed. Ensure each section includes at least one "### Requirement:" block (REMOVED may use bullet list syntax).`,
+                message: this.formatEmptySectionMessage(kind, header),
             });
         }
         for (const path of missingHeaderSpecs) {
@@ -357,24 +417,27 @@ export class Validator {
                 message: 'No delta sections found. Add headers such as "## ADDED Requirements" or move non-delta notes outside specs/.',
             });
         }
-        // Runs here, after every structural error has been pushed, so the exclusion
-        // set below is just "what has already been reported". Calling it inside the
-        // loop above meant hand-splicing the two lists that are only raised down
-        // here — a set that any later check would silently fall out of.
-        //
         // The checks above compare a delta against itself and, for MODIFIED, against
         // the main spec's scenarios. None asks whether the main spec can supply the
-        // target the delta acts on — the merge's own preconditions, which nothing
-        // consulted until archive.
-        if (mainSpecsDir !== undefined) {
-            issues.push(...(await this.findArchiveBlockers(changeDir, mainSpecsDir, issues.filter((issue) => issue.level === 'ERROR').map((issue) => issue.path))));
-        }
-        // A misplaced-spec error already names the file and the fix; adding "No
-        // deltas found" on top would contradict it, since the deltas are sitting in
-        // the file just reported.
+        // target the delta acts on — the merge's own preconditions.
+        if (mainSpecsDir !== undefined && archivePreflight) {
+            issues.push(...(await this.findArchiveBlockers(changeDir, mainSpecsDir)));
+        }
+        // A misplaced-spec error already names the file and the fix; "No deltas
+        // found" on top would contradict it.
         if (totalDeltas === 0 && !hasMisplacedSpec) {
             issues.push({ level: 'ERROR', path: 'file', message: this.enrichTopLevelError('change', VALIDATION_MESSAGES.CHANGE_NO_DELTAS) });
         }
+        // The ceiling `ChangeSchema.deltas.max()` declares. WARNING because the rule
+        // is advice about change size, not a correctness claim; `--strict` is what
+        // turns advice into a gate.
+        if (totalDeltas > MAX_DELTAS_PER_CHANGE) {
+            issues.push({
+                level: 'WARNING',
+                path: 'file',
+                message: `${VALIDATION_MESSAGES.CHANGE_TOO_MANY_DELTAS} (found ${totalDeltas}).`,
+            });
+        }
         return this.createReport(issues);
     }
     convertZodErrors(error) {
@@ -383,16 +446,22 @@ export class Validator {
             if (message === VALIDATION_MESSAGES.CHANGE_NO_DELTAS) {
                 message = `${message}. ${VALIDATION_MESSAGES.GUIDE_NO_DELTAS}`;
             }
+            // The guidance used to ride on a second, lower-severity copy of this
+            // finding emitted by applySpecRules. Appended here instead so the report
+            // carries one issue per fact, at the severity that decides the exit code.
+            if (message === VALIDATION_MESSAGES.REQUIREMENT_NO_SCENARIOS) {
+                message = `${message}. ${VALIDATION_MESSAGES.GUIDE_SCENARIO_FORMAT}`;
+            }
             return {
                 level: 'ERROR',
-                path: err.path.join('.'),
+                path: formatIssuePath(err.path),
                 message,
             };
         });
     }
     applySpecRules(spec, content) {
         const issues = [];
-        const fenceScan = scanCodeFences(content.split(/\r?\n/));
+        const fenceScan = scanCodeFences(normalizeDocument(content).split('\n'));
         if (fenceScan.unclosedFenceLine !== null) {
             issues.push({
                 level: 'ERROR',
@@ -409,10 +478,8 @@ export class Validator {
                 message: structuralIssue.message,
             });
         }
-        // The generated placeholder is longer than MIN_PURPOSE_LENGTH, so the
-        // brevity check below cannot reach it; it is reported on its own terms
-        // instead. Checked first because a hand-written "TBD" is both a placeholder
-        // and too brief, and only one of those two tells the author what to do.
+        // Checked before brevity: a hand-written "TBD" is both a placeholder and too
+        // brief, and only the placeholder message tells the author what to do.
         const placeholder = findPurposePlaceholderIssue(spec.overview, content);
         if (placeholder) {
             issues.push({
@@ -422,7 +489,7 @@ export class Validator {
                 message: VALIDATION_MESSAGES.PURPOSE_IS_PLACEHOLDER,
             });
         }
-        else if (spec.overview.length < MIN_PURPOSE_LENGTH) {
+        else if (proseLength(spec.overview) < MIN_PURPOSE_LENGTH) {
             issues.push({
                 level: 'WARNING',
                 path: 'overview',
@@ -437,62 +504,29 @@ export class Validator {
                     message: VALIDATION_MESSAGES.REQUIREMENT_TOO_LONG,
                 });
             }
-            if (req.scenarios.length === 0) {
-                issues.push({
-                    level: 'WARNING',
-                    path: `requirements[${index}].scenarios`,
-                    message: `${VALIDATION_MESSAGES.REQUIREMENT_NO_SCENARIOS}. ${VALIDATION_MESSAGES.GUIDE_SCENARIO_FORMAT}`,
-                });
-            }
+            // A missing scenario is not checked here: SpecSchema's `scenarios.min(1)`
+            // already reports it as an ERROR, and convertZodErrors appends the same
+            // format guidance this branch used to carry. Two copies of one fact, at
+            // two severities, only made the report ambiguous about which to fix.
         });
-        // SHALL/MUST body-keyword enforcement for main specs (#1156). The main-spec
-        // parser collapses the requirement header into `text`, so we recover the
-        // header+body pairs here (the same source the delta path trusts) and reuse
-        // the delta detection: a body that omits the keyword errors, with the
-        // targeted "move it to the body line" hint when the keyword is in the header
-        // only and the generic message otherwise. Emitted exactly once per
-        // requirement (the Zod refine that used to emit a generic error is removed).
+        // The main-spec parser collapses the requirement header into `text`, so
+        // recover the header+body pairs here — the same source the delta path
+        // trusts — and reuse the delta detection.
         extractRequirementsSection(content).bodyBlocks.forEach((block, index) => {
             const requirementText = this.extractRequirementText(block.raw);
-            // Both conditions stay one branch on purpose. An absent body here is not
-            // a "missing text" defect: it is the header-only pattern
-            // (`### Requirement: The system MUST ...` with no body line), and the
-            // hint that fires for it — move the statement to the body — is the
-            // intended answer. Splitting them re-reports that case as missing text
-            // and loses the hint.
+            // One branch on purpose: an absent body here is the header-only pattern
+            // (`### Requirement: The system MUST ...` with no body line), whose hint —
+            // move the statement to the body — is the intended answer.
             //
             // WARNING, not ERROR: the keyword check is English-only, so at ERROR it
-            // blocked any requirement stating its obligation in another language —
-            // enforcing a documentation language, not normative strength. `--strict`
-            // still refuses it (strictMode counts warnings as fatal).
-            // Decision: tospec/decisions/20260814_134116-shall-must-missing-is-a-warning.md
-            if (!requirementText || !this.containsShallOrMust(requirementText)) {
+            // blocked requirements written in another language. `--strict` still
+            // refuses it.
+            // tospec/decisions/20260814_134116-shall-must-missing-is-a-warning.md
+            if (!requirementText || !containsShallOrMust(requirementText)) {
                 issues.push({
                     level: 'WARNING',
                     path: `requirements[${index}]`,
-                    message: this.buildMissingShallOrMustMessage(`Requirement "${block.name}"`, block.name),
-                });
-            }
-        });
-        return issues;
-    }
-    applyChangeRules(change, content) {
-        const issues = [];
-        const MIN_DELTA_DESCRIPTION_LENGTH = 10;
-        change.deltas.forEach((delta, index) => {
-            if (!delta.description || delta.description.length < MIN_DELTA_DESCRIPTION_LENGTH) {
-                issues.push({
-                    level: 'WARNING',
-                    path: `deltas[${index}].description`,
-                    message: VALIDATION_MESSAGES.DELTA_DESCRIPTION_TOO_BRIEF,
-                });
-            }
-            if ((delta.operation === 'ADDED' || delta.operation === 'MODIFIED') &&
-                (!delta.requirements || delta.requirements.length === 0)) {
-                issues.push({
-                    level: 'WARNING',
-                    path: `deltas[${index}].requirements`,
-                    message: `${delta.operation} ${VALIDATION_MESSAGES.DELTA_MISSING_REQUIREMENTS}`,
+                    ...this.buildMissingShallOrMustMessage(`Requirement "${block.name}"`, block.name),
                 });
             }
         });
@@ -518,78 +552,135 @@ export class Validator {
         const valid = this.strictMode
             ? errors === 0 && warnings === 0
             : errors === 0;
+        // One report, one copy of each rule's background: the note belongs to the
+        // rule, not to the line that tripped it.
+        const notes = [...new Set(issues.map((issue) => issue.note).filter((n) => !!n))];
+        const flattened = issues.map(({ note: _note, ...issue }) => issue);
         return {
             valid,
-            issues,
+            issues: flattened,
             summary: {
                 errors,
                 warnings,
                 info,
             },
+            ...(notes.length ? { notes } : {}),
         };
     }
     extractRequirementText(blockRaw) {
-        // Delegate to the shared, fence-/metadata-/multi-line-aware body reader.
-        // Validation intentionally does not use the parser/display header-title
-        // fallback for canonical `### Requirement:` blocks: a SHALL/MUST that
-        // appears only in the header must still receive the body-keyword hint.
-        // Line 0 is the `### Requirement: ...` header.
+        // Line 0 is the `### Requirement: ...` header. Validation deliberately skips
+        // the parser's header-title fallback: a SHALL/MUST that appears only in the
+        // header must still receive the body-keyword hint.
         const [, ...bodyLines] = blockRaw.split('\n');
         return extractRequirementBodyShared(bodyLines) || undefined;
     }
-    containsShallOrMust(text) {
-        return containsShallOrMustShared(text);
-    }
     /**
-     * Build an error message for a requirement block whose body lacks SHALL/MUST.
-     *
-     * When the SHALL/MUST keyword already appears in the requirement header (e.g.
-     * `### Requirement: The system SHALL ...`) the original generic error
-     * ("must contain SHALL or MUST") is confusing because the keyword is visibly
-     * present in the spec. Per the Tospec conventions the keyword has to live
-     * on the requirement body line (the line right after the header), so we point
-     * the author at that exact fix when the keyword is found in the header only.
+     * When the keyword already appears in the header (`### Requirement: The system
+     * SHALL ...`) the generic "must contain SHALL or MUST" reads as wrong, since
+     * the keyword is visibly there. The convention puts it on the body line, so
+     * point the author at that exact fix instead.
      */
     buildMissingShallOrMustMessage(prefix, blockName) {
         const base = `${prefix} must contain SHALL or MUST`;
-        if (this.containsShallOrMust(blockName)) {
-            return `${base} in the requirement body, not only in the header. Move the SHALL/MUST statement to the line immediately after the "### Requirement: ..." header.`;
+        if (containsShallOrMust(blockName)) {
+            return {
+                message: `${base} in the requirement body, not only in the header. Move the SHALL/MUST statement to the line immediately after the "### Requirement: ..." header.`,
+            };
         }
-        return base;
+        // Carried as a `note`, not appended to the message: it is identical for
+        // every requirement, and inlining reprinted the paragraph once per
+        // occurrence, burying the names that actually differ.
+        return {
+            message: `${base}.`,
+            note: 'SHALL/MUST detection matches those two English keywords only — a requirement that states ' +
+                'its obligation in another language will always report this. It stays a warning for that ' +
+                'reason; if your specs are not written in English, prefer `tospec validate` over `--strict`, ' +
+                'which treats warnings as fatal.',
+        };
+    }
+    /**
+     * The main spec's two Purpose rules, applied to a delta that is about to
+     * create that main spec. Placeholder before brevity, as on the spec path.
+     *
+     * `mainSpecsDir` absent means new capabilities cannot be told from existing
+     * ones, so nothing is reported.
+     */
+    async collectDeltaPurposeIssues(content, entryPath, mainSpecsDir) {
+        if (mainSpecsDir === undefined)
+            return [];
+        const purpose = extractDeltaPurpose(content);
+        const capability = entryPath.split('/')[0];
+        try {
+            await fs.access(path.join(mainSpecsDir, capability, 'spec.md'));
+            return []; // Capability exists: its own spec owns the Purpose.
+        }
+        catch (error) {
+            // Only a genuinely absent spec means "new capability"; guessing "new"
+            // would report a Purpose that is never copied.
+            if (!isMissingPathError(error))
+                return [];
+        }
+        // WARNING, not ERROR: the schema calls the Purpose mandatory, but archive
+        // still completes with a placeholder, so this is advice on where the text
+        // belongs rather than a merge precondition. Reported here because archive
+        // is the only other place that notices, and by then the delta is under
+        // changes/archive/ where nobody edits it.
+        if (!purpose) {
+            return [{ level: 'WARNING', path: entryPath, message: VALIDATION_MESSAGES.DELTA_PURPOSE_MISSING }];
+        }
+        const placeholder = findPurposePlaceholderIssue(purpose, content);
+        if (placeholder) {
+            return [
+                {
+                    level: 'WARNING',
+                    path: entryPath,
+                    line: placeholder.line,
+                    message: VALIDATION_MESSAGES.DELTA_PURPOSE_IS_PLACEHOLDER,
+                },
+            ];
+        }
+        if (proseLength(purpose) < MIN_PURPOSE_LENGTH) {
+            return [{ level: 'WARNING', path: entryPath, message: VALIDATION_MESSAGES.DELTA_PURPOSE_TOO_BRIEF }];
+        }
+        return [];
     }
     /**
      * Scenarios a MODIFIED block would delete from the current main spec.
      *
      * A MODIFIED replaces the whole requirement, so a scenario the block omits is
-     * lost. `specs-apply` already refuses to apply such a block, but only at
-     * archive time — so a change could validate clean, be implemented and
-     * reviewed, and fail days later at the most expensive possible moment. Both
-     * sides now call `findMissingScenarios`, so validate reports exactly what
-     * archive refuses.
+     * lost. `specs-apply` refuses such a block too, but only at archive time. Both
+     * sides call `findMissingScenarios`, so validate reports what archive refuses.
      *
-     * Deliberately silent in two cases, because archive gates them separately and
-     * a warning here would be a false alarm:
-     * - the main spec file does not exist yet (the capability is new)
-     * - the requirement header is absent from it (a MODIFIED written against a
-     *   sister change still in flight)
+     * Silent when the main spec does not exist yet (new capability) or lacks the
+     * requirement header (a MODIFIED written against a sister change still in
+     * flight): archive gates both separately.
      */
-    async collectDroppedScenarioIssues(mainSpecsDir, capability, modified, entryPath) {
+    async collectDroppedScenarioIssues(mainSpecsDir, capability, modified, entryPath, 
+    /**
+     * New name → old name, for requirements this change also renames. Without
+     * it a MODIFIED under the post-rename header finds nothing in the main spec
+     * and is skipped, so archive refuses what validate called valid.
+     */
+    renamedToFrom, 
+    /**
+     * `## REMOVED Scenarios` declarations. A scenario named here is one the
+     * author means to drop, so omitting it from the MODIFIED block stops being
+     * the accident this check exists to catch.
+     */
+    declaredRemovals) {
         let content;
         try {
             content = await fs.readFile(path.join(mainSpecsDir, capability, 'spec.md'), 'utf-8');
         }
         catch (error) {
-            // Silence belongs to the genuinely-absent case documented above. A spec that
-            // exists and could not be read means the check never ran, and returning []
-            // reports that as "nothing to lose" — under the same wording, so the reader
-            // cannot tell a new capability from a broken one.
+            // Silence belongs to the genuinely-absent case only: a spec that exists
+            // and could not be read means the check never ran, and [] would report
+            // that as "nothing to lose".
             if (isMissingPathError(error))
                 return [];
             // Reported rather than thrown: the enclosing handler treats any throw as
-            // "no specs dir" and would swallow this into a misleading no-deltas error.
-            // Reporting also keeps the other capabilities' findings, which a throw
-            // would discard. ERROR because archive reads the same file and now fails
-            // on it too, so this is what archive refuses.
+            // "no specs dir" and would discard the other capabilities' findings.
+            // ERROR because archive reads the same file and fails on it too.
             return [
                 {
                     level: 'ERROR',
@@ -603,40 +694,116 @@ export class Validator {
             currentByName.set(normalizeRequirementName(block.name), block);
         }
         const issues = [];
+        // Declarations are consumed as matched, so a leftover is one that removed
+        // nothing — a typo that would otherwise read as a successful removal.
+        const unmatchedRemovals = new Set(declaredRemovals);
+        const declaredFor = (requirementKey) => {
+            const names = new Set();
+            for (const entry of declaredRemovals) {
+                if (entry.requirement === requirementKey)
+                    names.add(entry.scenario);
+            }
+            return names;
+        };
+        for (const entry of declaredRemovals) {
+            if (!entry.hasReason) {
+                issues.push({
+                    level: 'WARNING',
+                    path: entryPath,
+                    line: entry.startLine,
+                    message: `REMOVED Scenarios entry for "${entry.scenario}" has no Reason. A scenario removal is a behavior removal — record why, the same as a removed requirement does.`,
+                });
+            }
+        }
         for (const block of modified) {
-            const current = currentByName.get(normalizeRequirementName(block.name));
+            const key = normalizeRequirementName(block.name);
+            // Direct hit first; only fall back to the pre-rename name when this change
+            // renames the requirement, so an unrelated MODIFIED is unaffected.
+            const renamedFrom = renamedToFrom.get(key);
+            const current = currentByName.get(key) ??
+                (renamedFrom === undefined ? undefined : currentByName.get(normalizeRequirementName(renamedFrom)));
             if (!current)
                 continue;
-            const missing = findMissingScenarios(current.raw, block.raw);
-            if (missing.length === 0)
+            // Named by its spec header, not its new one: that is the block the reader
+            // has to open to see the scenarios at risk.
+            const target = renamedFrom !== undefined && !currentByName.has(key) ? ` (renamed from "${renamedFrom}")` : '';
+            const declared = declaredFor(currentByName.has(key) ? key : normalizeRequirementName(renamedFrom ?? ''));
+            const missing = findMissingScenarios(current.raw, block.raw).filter((name) => {
+                if (!declared.has(name))
+                    return true;
+                for (const entry of unmatchedRemovals) {
+                    if (entry.scenario === name)
+                        unmatchedRemovals.delete(entry);
+                }
+                return false;
+            });
+            if (missing.length > 0) {
+                issues.push({
+                    level: 'ERROR',
+                    path: entryPath,
+                    message: `MODIFIED "${block.name}"${target} omits scenario(s) the current spec still has: ${missing
+                        .map((name) => `"${name}"`)
+                        .join(', ')}. A MODIFIED block replaces the whole requirement, so archiving would delete them — restate them in the block, or declare the removal under "## REMOVED Scenarios" with a Reason. ${REMOVED_SCENARIOS_GRAMMAR}`,
+                });
+                // One finding per requirement: a block missing whole scenarios is also
+                // missing their bullets, and reporting both buries the actionable one.
                 continue;
+            }
+            // WARNING, not ERROR: rewording a bullet is a legitimate MODIFIED, but on
+            // disk it is indistinguishable from a stale block reverting someone else's
+            // archived edit.
+            //
+            // Compared against the current requirement *minus* the scenarios this
+            // change declared removed: their bullets go with them by definition.
+            const currentRaw = withoutScenarios(current.raw, [...declared]);
+            const dropped = findDroppedBullets(currentRaw, block.raw);
+            // A rewrite replaces bullets; a stale block loses them. When the delta
+            // brings at least as many new bullets as it drops, every dropped line has
+            // a successor and the block is a rewording — reporting it made every
+            // legitimate MODIFIED fail `--strict`. Fewer bullets than before is the
+            // shape of a reverted edit, which is the case this check exists for.
+            const replaced = findDroppedBullets(block.raw, currentRaw);
+            if (dropped.length > 0 && replaced.length < dropped.length) {
+                issues.push({
+                    level: 'WARNING',
+                    path: entryPath,
+                    message: `MODIFIED "${block.name}"${target} drops bullet(s) the current spec still has: ${dropped
+                        .map((line) => `"${line}"`)
+                        .join(', ')}. Confirm this is an intentional rewrite and not a block written against an older ` +
+                        `copy of the requirement — run tospec show <change> --diff to see the full comparison.`,
+                });
+            }
+        }
+        // A declaration that matched nothing: the author believes a scenario was
+        // removed, the spec still has it, and every command reports success. ERROR
+        // because there is no reading of it that is correct.
+        for (const entry of unmatchedRemovals) {
             issues.push({
                 level: 'ERROR',
                 path: entryPath,
-                message: `MODIFIED "${block.name}" omits scenario(s) the current spec still has: ${missing
-                    .map((name) => `"${name}"`)
-                    .join(', ')}. A MODIFIED block replaces the whole requirement, so archiving would delete them — restate them in the block.`,
+                line: entry.startLine,
+                message: `REMOVED Scenarios declares "${entry.scenario}" under requirement "${entry.requirement}", but no MODIFIED block for that requirement drops that scenario. Check both names against tospec/specs/${capability}/spec.md — a declaration that matches nothing removes nothing.`,
             });
         }
         return issues;
     }
     /**
-     * Dry-run the merge and report what it would refuse.
+     * Dry-run the merge and report what it would refuse, plus the one thing it
+     * would accept while doing nothing.
      *
      * Reusing the merge builder rather than restating its preconditions is the
-     * whole point: several of them deliberately read a missing target as
-     * already-synced rather than as a failure, and a second copy of those rules
-     * would be free to drift — which shows up as validate and archive disagreeing,
-     * the one thing this check exists to prevent.
+     * point: a second copy would be free to drift, which shows up as validate and
+     * archive disagreeing.
      *
-     * INFO leaves the verdict alone. A MODIFIED whose target is missing is also
-     * what a change modifying a sibling's unarchived requirement looks like, and
-     * that is valid today; what is missing is the information, not the verdict.
+     * WARNING, not ERROR or INFO. ERROR is wrong because a MODIFIED whose target
+     * is missing is also what a change modifying a sibling's unarchived
+     * requirement looks like. INFO was wrong because `--strict` ignores it, so the
+     * pre-archive gate waved through changes archive would refuse.
+     * tospec/decisions/20260916_154000-archive-dry-run-findings-are-warnings.md
      */
-    async findArchiveBlockers(changeDir, mainSpecsDir, alreadyReportedPaths) {
-        const alreadyReported = new Set(alreadyReportedPaths);
-        // Only ever reaches the generated skeleton's placeholder Purpose, which this
-        // dry run discards along with the rest of the rebuilt content.
+    async findArchiveBlockers(changeDir, mainSpecsDir) {
+        // Only reaches the generated skeleton's placeholder Purpose, which this dry
+        // run discards with the rest of the rebuilt content.
         const changeName = path.basename(changeDir);
         const issues = [];
         let updates;
@@ -644,9 +811,8 @@ export class Validator {
             updates = await findSpecUpdates(changeDir, mainSpecsDir);
         }
         catch (error) {
-            // An advisory check that cannot start must not take the report with it.
-            // The structural pass walks the same tree with fast-glob and reports what
-            // it found; those findings are the ones the author can act on.
+            // An advisory check that cannot start must not take the report with it:
+            // the structural pass walks the same tree and its findings are actionable.
             return [
                 {
                     level: 'INFO',
@@ -660,35 +826,53 @@ export class Validator {
             // rebuilds the same entryPath the checks above report under.
             const capability = path.basename(path.dirname(update.source));
             const entryPath = FileSystemUtils.toPosixPath(`${capability}/spec.md`);
-            // A delta those checks already rejected would be reported twice, the
-            // second time in the merge's wording rather than the wording that names
-            // the actual mistake.
-            if (alreadyReported.has(entryPath))
-                continue;
             try {
-                await buildUpdatedSpec(update, changeName, { silent: true });
+                const built = await buildUpdatedSpec(update, changeName, { silent: true });
+                // The merge would succeed but delete nothing, which is not what the
+                // delta appears to say. A mistyped REMOVED header is the likeliest
+                // cause and the hardest to catch, since nothing visibly happens.
+                //
+                // Only the REMOVED codes: the merge's other notices are about Purpose,
+                // which this validator judges under its own rules.
+                for (const notice of built.notices) {
+                    if (!REMOVED_NOOP_NOTICE_CODES.has(notice.code))
+                        continue;
+                    issues.push({
+                        level: 'WARNING',
+                        path: entryPath,
+                        message: `Archive would accept this delta but remove nothing: ${notice.message}`,
+                    });
+                }
             }
             catch (error) {
                 // Only the thrown preconditions, which carry no errno. A filesystem
-                // error says nothing about whether the delta applies, and `validate
-                // --all` reads several changes at once — a transient EMFILE reported as
-                // a collision is a conflict that is not there.
+                // error says nothing about whether the delta applies, and under
+                // `validate --all` a transient EMFILE would read as a collision.
                 if (error?.code !== undefined)
                     continue;
+                const message = error instanceof Error ? error.message : String(error);
+                // The structural pass above already reported these in its own, more
+                // precise wording; repeating them in the merge's would name the same
+                // mistake twice. Filtered by *kind* rather than by path: the merge's
+                // other preconditions (a MODIFIED or RENAMED target the main spec does
+                // not have, an ADDED that collides) are checked nowhere else, so a delta
+                // with one unrelated grammar error used to hide them until that error
+                // was fixed — one round trip per finding.
+                if (STRUCTURAL_MERGE_FAILURE.test(message))
+                    continue;
                 issues.push({
-                    level: 'INFO',
+                    level: 'WARNING',
                     path: entryPath,
-                    message: `Archive would refuse this delta: ${error instanceof Error ? error.message : String(error)}`,
+                    message: `Archive would refuse this delta: ${message}`,
                 });
             }
         }
         return issues;
     }
     /**
-     * Scenario-quality rules for a delta requirement block (report 2.1): only
-     * `#### Scenario:` headers count as scenarios, each scenario body must
-     * contain WHEN and THEN (uppercase, per the spec convention), and stray
-     * level-4 headers get a WARNING so authors know they were not counted.
+     * Scenario-quality rules for a delta requirement block: only `#### Scenario:`
+     * headers count, each scenario body must contain uppercase WHEN and THEN, and
+     * a stray level-4 header gets a WARNING so the author knows it was not counted.
      */
     collectScenarioIssues(section, block, entryPath) {
         const issues = [];
@@ -703,6 +887,24 @@ export class Validator {
                 message: `${section} "${block.name}" must include at least one "#### Scenario:" block`,
             });
         }
+        // Scenario names are the only handle the MODIFIED scenario-loss guard has —
+        // it counts how many times each name appears on each side. Restating one
+        // twice keeps the count and silently deletes the other's body on archive.
+        const scenarioNames = new Set();
+        for (const scenario of analysis.scenarios) {
+            const key = scenario.title.trim().toLowerCase();
+            if (scenarioNames.has(key)) {
+                issues.push({
+                    level: 'ERROR',
+                    path: entryPath,
+                    line: toLine(scenario.relLine),
+                    message: `${section} "${block.name}" repeats scenario name "${scenario.title}" (line ${toLine(scenario.relLine)}). Scenario names identify a scenario when a later MODIFIED restates this requirement, so two with the same name cannot be told apart — give each one a distinct name.`,
+                });
+            }
+            else {
+                scenarioNames.add(key);
+            }
+        }
         for (const scenario of analysis.scenarios) {
             const missing = [
                 ...(scenario.hasWhen ? [] : ['WHEN']),
@@ -727,14 +929,21 @@ export class Validator {
         }
         return issues;
     }
-    formatSectionList(sections) {
-        if (sections.length === 0)
-            return '';
-        if (sections.length === 1)
-            return sections[0];
-        const head = sections.slice(0, -1);
-        const last = sections[sections.length - 1];
-        return `${head.join(', ')} and ${last}`;
+    /**
+     * RENAMED/REMOVED have their own grammar (FROM:/TO: pairs; name bullets with
+     * Reason/Migration), not the `### Requirement:` block ADDED/MODIFIED use, so
+     * "add a ### Requirement: block" would send their authors to a fix that does
+     * not work.
+     */
+    formatEmptySectionMessage(kind, header) {
+        switch (kind) {
+            case 'renamed':
+                return `Delta section "${header}" was found, but no rename pairs parsed. Write each entry as a FROM:/TO: pair naming the requirement, e.g. "- FROM: \`Old Name\`" then "- TO: \`New Name\`".`;
+            case 'removed':
+                return `Delta section "${header}" was found, but no entries parsed. List each removed requirement as a bullet naming it, e.g. "- Old Name", with Reason and Migration fields below it.`;
+            default:
+                return `Delta section "${header}" was found, but no requirement entries parsed. Ensure it includes at least one "### Requirement:" block.`;
+        }
     }
 }
 //# sourceMappingURL=validator.js.map