@seanmars/tospec 0.24.0 → 0.26.0-beta

package/dist/core/validation/validator.js

@@ -1,16 +1,20 @@
 import { readFileSync, promises as fs } from 'fs';
 import path from 'path';
 import { SpecSchema } from '../schemas/index.js';
-import { MarkdownParser } from '../parsers/markdown-parser.js';
-import { MIN_PURPOSE_LENGTH, MAX_REQUIREMENT_TEXT_LENGTH, MAX_DELTAS_PER_CHANGE, VALIDATION_MESSAGES } from './constants.js';
+import { MarkdownParser, SpecHeadingLevelError } from '../parsers/markdown-parser.js';
+import { ARCHIVE_REFUSAL_CODE, SISTER_CHANGE_OVERLAP_CODE, REQUIREMENT_HEADER_MISMATCH_CODE, } from './types.js';
+import { appendSentence } from '../../utils/sentence.js';
+import { MIN_PURPOSE_LENGTH, MAX_REQUIREMENT_TEXT_LENGTH, MAX_DELTAS_PER_CHANGE, VALIDATION_MESSAGES, noDeltasGuide } from './constants.js';
 import { proseLength } from './prose-length.js';
-import { parseDeltaSpec, normalizeRequirementName, extractRequirementsSection } from '../parsers/requirement-blocks.js';
+import { parseDeltaSpec, normalizeRequirementName, findFoldedMatch, extractRequirementsSection, postRenameRemovalHint, } from '../parsers/requirement-blocks.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 { findAllMarkdownFiles } from '../../utils/spec-files.js';
-import { findSpecUpdates, buildUpdatedSpec, extractDeltaPurpose } from '../specs-apply.js';
+import { FileSystemUtils, extractNameFromPath, isMissingPathError, isAbsentDirectoryError } from '../../utils/file-system.js';
+import { isUnicodeKebabName, portableNameFault, UNICODE_KEBAB_NAME_DESCRIPTION } from '../id.js';
+import { findAllMarkdownFiles, findRootSpecDelta, specLayoutFault } from '../../utils/spec-files.js';
+import { findSpecUpdates, buildUpdatedSpec, extractDeltaPurpose, resolveOnDiskSpecName, MissingTargetSpecError, MissingTargetRequirementError, RequirementNearMissError, } from '../specs-apply.js';
+import { findHeaderMismatches, findSharedRequirements, listDeltaTouches, listSisterChangeDeltas, readChangeOrderKey, } from './sister-changes.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
@@ -18,24 +22,80 @@ import { findSpecUpdates, buildUpdatedSpec, extractDeltaPurpose } from '../specs
  * instead of being sent to the template.
  */
 const REMOVED_SCENARIOS_GRAMMAR = 'Each entry is three bullets: "- Requirement: `<name>`" / "- Scenario: `<name>`" / "- Reason: <why>".';
+/**
+ * The entry names under `tospec/specs/` as spelled on disk, or undefined when
+ * they cannot be known (no `mainSpecsDir`, or a directory that exists but cannot
+ * be read): then new capabilities cannot be told from existing ones, and
+ * guessing "new" would hold an existing capability to the naming rule.
+ */
+async function listMainSpecNames(mainSpecsDir) {
+    if (mainSpecsDir === undefined)
+        return undefined;
+    try {
+        return await fs.readdir(mainSpecsDir);
+    }
+    catch (error) {
+        return isAbsentDirectoryError(error) ? [] : undefined;
+    }
+}
+/**
+ * The capability folder's name checked against the main specs it will merge
+ * into. Matched against the readdir spelling, never through the file system:
+ * asking whether `tospec/specs/AUTH/spec.md` exists answers yes on Windows and
+ * default macOS and no on Linux, so the same delta merged into `auth` on one
+ * and archived a second capability `AUTH` on the other. An existing
+ * capability keeps the name it has — the rule binds only the name a change is
+ * about to create.
+ */
+function capabilityNameIssues(entryPath, mainSpecNames) {
+    const capability = entryPath.split('/')[0];
+    if (mainSpecNames.includes(capability))
+        return [];
+    const folded = capability.toLowerCase();
+    const clash = mainSpecNames.find((name) => name.toLowerCase() === folded);
+    if (clash !== undefined) {
+        return [
+            {
+                level: 'ERROR',
+                path: entryPath,
+                message: `Capability folder "${capability}" differs only in case from the existing main spec tospec/specs/${clash}/. A case-insensitive file system (Windows, default macOS) merges it into ${clash}, a case-sensitive one archives it as a second capability, so the result depends on the OS. Rename the folder to specs/${clash}/.`,
+            },
+        ];
+    }
+    const fault = portableNameFault(capability);
+    if (fault !== undefined) {
+        return [
+            {
+                level: 'ERROR',
+                path: entryPath,
+                message: `Capability folder "${capability}" ${fault}. Archive creates tospec/specs/${capability}/ from this name, and a repo holding it cannot be checked out on Windows. Rename the folder.`,
+            },
+        ];
+    }
+    // WARNING, not ERROR: the name works on every OS, and a project may have
+    // its own convention. It is raised now because archive turns the folder name
+    // into the main spec's name, and renaming a capability later is a change of
+    // its own.
+    if (!isUnicodeKebabName(capability)) {
+        return [
+            {
+                level: 'WARNING',
+                path: entryPath,
+                message: `Capability folder "${capability}" ${UNICODE_KEBAB_NAME_DESCRIPTION}. Archive turns it into the name of a new main spec, tospec/specs/${capability}/, so rename the folder now if it should follow the convention.`,
+            },
+        ];
+    }
+    return [];
+}
+/** The `specs/spec.md` ERROR. */
+const ROOT_SPEC_DELTA_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.';
 /**
  * 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)/;
+const REMOVED_NOOP_NOTICE_CODES = new Set(['archive_removed_requirement_absent']);
 /**
  * A name the template shipped and nobody replaced: `[name]`, `[old name]`,
  * `[scenario name]`. Bracketed end to end, which is how every placeholder in
@@ -50,6 +110,108 @@ const STRUCTURAL_MERGE_FAILURE = /( validation failed - |^Delta parsing found no
 function isTemplatePlaceholder(name) {
     return /^\[.*\]$/.test(name.trim());
 }
+/**
+ * Names the earlier spelling when a duplicate only folds onto it: without it,
+ * "Duplicate requirement" over two visibly different headers reads as a bug.
+ */
+function foldedDuplicateNote(earlier, name) {
+    return earlier === name ? '' : ` (differs only in case or spacing from "${earlier}")`;
+}
+/**
+ * The in-progress changes whose ADDED delta creates `capability`, or, given
+ * `requirement`, that requirement in it. Matched exactly, as the merge
+ * matches: a folded match named a change whose archive still left the delta
+ * refused, and `blockedBy` promised the opposite. That case is
+ * `findHeaderMismatches`'s.
+ */
+function addingChanges(sisters, capability, requirement) {
+    const exact = requirement === undefined ? undefined : normalizeRequirementName(requirement);
+    return sisters
+        .filter((s) => s.capability === capability &&
+        (exact === undefined
+            ? s.plan.added.length > 0
+            : s.plan.added.some((block) => normalizeRequirementName(block.name) === exact)))
+        .map((s) => s.change);
+}
+/**
+ * The sentence naming the change(s) that add what the delta needs, or
+ * undefined when none does. Without it the refusal reads as a delta written
+ * against the wrong capability or requirement, when the delta is right and
+ * only the archive order is.
+ */
+function addingChangeHint(adders, what) {
+    if (adders.length === 0)
+        return undefined;
+    if (adders.length === 1)
+        return `Archive '${adders[0]}' first: it adds this ${what}.`;
+    return `Archive ${adders.map((name) => `'${name}'`).join(', ')} first: each adds this ${what}.`;
+}
+/**
+ * The requirement names of `capability`'s main spec: [] when it has none,
+ * undefined when it exists but cannot be read. The header-mismatch check
+ * needs them and stays silent on undefined, since the scenario-loss check
+ * already reports an unreadable main spec.
+ */
+async function readMainRequirementNames(mainSpecsDir, capability) {
+    try {
+        const content = await fs.readFile(path.join(mainSpecsDir, capability, 'spec.md'), 'utf-8');
+        return extractRequirementsSection(content).bodyBlocks.map((block) => normalizeRequirementName(block.name));
+    }
+    catch (error) {
+        return isMissingPathError(error) ? [] : undefined;
+    }
+}
+/**
+ * The edit that writes `suggestedHeader` into the delta. A RENAMED names its
+ * requirement on the `- FROM:` bullet, and "change the header" sent the
+ * author to a `### Requirement:` line the entry does not have.
+ */
+export function headerCorrectionClause(operation, suggestedHeader) {
+    const target = operation === 'RENAMED' ? 'the FROM line' : 'the header';
+    return `change ${target} to "### Requirement: ${suggestedHeader}"`;
+}
+/** The `requirement_header_mismatch` ERROR's message. */
+function headerMismatchMessage({ change, own, suggestedHeader }) {
+    const at = own.line === undefined ? '' : ` (line ${own.line})`;
+    return `${own.operation} "${own.requirement}"${at} differs only in case or spacing from "${suggestedHeader}", which in-progress change '${change}' adds. Archive matches requirement names exactly, so archiving '${change}' first does not resolve it: ${headerCorrectionClause(own.operation, suggestedHeader)}.`;
+}
+/** True only for a main spec that is genuinely absent, the case archive refuses a MODIFIED, REMOVED or RENAMED on. */
+async function isMissingMainSpec(mainSpecsDir, capability) {
+    try {
+        await fs.access(path.join(mainSpecsDir, capability, 'spec.md'));
+        return false;
+    }
+    catch (error) {
+        return isMissingPathError(error);
+    }
+}
+/**
+ * The older change first: both sides read the same two keys, so each tells
+ * its author the same order. Equal or unreadable keys give no order at all.
+ */
+function compareChangeAge(own, sister) {
+    if (own === undefined || sister === undefined || own === sister)
+        return 'unknown';
+    return own < sister ? 'this-first' : 'sister-first';
+}
+/**
+ * The advice closing a sister-change WARNING. Each change's validate writes
+ * it from its own side, so the two must say one thing: advising "archive the
+ * other one first" on both, as this did, left an agent no order to follow.
+ * A sister ADDED fixes the order by itself, since a rewrite needs the
+ * requirement to exist; two rewrites are ordered by creation, the older first.
+ */
+function sisterArchiveAdvice(sister, operation, order) {
+    const syncNote = 'sync may also rewrite the requirement during it.';
+    if (order === 'sister-first') {
+        const why = operation === 'ADDED' ? '' : ` (it was created before this change)`;
+        return `Archive '${sister}' first${why}, then rewrite this delta against the main spec that archive produces: ${syncNote}`;
+    }
+    if (order === 'this-first') {
+        return `This change was created before '${sister}', so archive this change first; '${sister}' must then rewrite its delta against the main spec that archive produces: ${syncNote}`;
+    }
+    return `Which of the two was created first cannot be told, so decide which archives first, then rewrite the other one's delta against the main spec that archive produces: ${syncNote}`;
+}
 /**
  * One `path` notation across the report. Zod hands back a segment array that
  * `join('.')` renders as `requirements.0.scenarios`, while every hand-written
@@ -98,10 +260,35 @@ export class Validator {
         catch (error) {
             const baseMessage = error instanceof Error ? error.message : 'Unknown error';
             const enriched = this.enrichTopLevelError(specName, baseMessage);
-            issues.push({ level: 'ERROR', path: 'file', message: enriched });
+            const line = error instanceof SpecHeadingLevelError ? { line: error.line } : {};
+            issues.push({ level: 'ERROR', path: 'file', ...line, message: enriched });
         }
         return this.createReport(issues);
     }
+    /**
+     * Whether archive would refuse to write `rebuilt`, and whose fault that is.
+     * Null when it would write it.
+     *
+     * The verdict counts ERRORs only, whatever this validator's strictness:
+     * archive judges the rebuilt spec non-strictly, and this answers for archive.
+     *
+     * A main spec that already fails is the cause, even if the delta adds its own
+     * faults: those the change's validation reports anyway, while the main
+     * spec's are reported nowhere a change author looks — and its issue paths,
+     * unlike the rebuilt spec's, are the ones `tospec validate <spec>` prints.
+     */
+    async diagnoseRebuiltSpec(specName, rebuilt, original) {
+        const rebuiltReport = await this.validateSpecContent(specName, rebuilt);
+        if (!rebuiltReport.issues.some((i) => i.level === 'ERROR'))
+            return null;
+        if (original !== undefined) {
+            const mainReport = await this.validateSpecContent(specName, original.content);
+            if (mainReport.issues.some((i) => i.level === 'ERROR')) {
+                return { source: 'main', specPath: original.path, issues: mainReport.issues };
+            }
+        }
+        return { source: 'delta', issues: rebuiltReport.issues };
+    }
     /**
      * Validate delta-formatted spec files under a change directory: at least one
      * delta overall, ADDED/MODIFIED requirements carrying SHALL/MUST and a
@@ -115,9 +302,33 @@ export class Validator {
      * `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.
+     *
+     * `requireDelta: false` is for a change whose schema demands no delta. Every
+     * other check still runs, because archive merges each
+     * specs/<capability>/spec.md whatever the schema says. Dropped: the "at least
+     * one delta" ERROR, and the specs/spec.md ERROR for a file with no delta
+     * header, which such a schema leaves as notes, as at the rest of the root.
+     *
+     * `sisterChanges: false` drops the check against other in-progress changes'
+     * deltas. Archive turns it off: it runs its own check, in the direction the
+     * archive decides (this change goes first), where this one would advise
+     * archiving the other change first.
      */
     async validateChangeDeltaSpecs(changeDir, mainSpecsDir, options = {}) {
         const archivePreflight = options.archivePreflight ?? true;
+        const requireDelta = options.requireDelta ?? true;
+        const checkSisterChanges = options.sisterChanges ?? true;
+        let sisters;
+        // Per change dir, read once per run however many requirements two changes share.
+        const orderKeys = new Map();
+        const orderKeyOf = (dir) => {
+            let key = orderKeys.get(dir);
+            if (key === undefined) {
+                key = readChangeOrderKey(dir);
+                orderKeys.set(dir, key);
+            }
+            return key;
+        };
         const issues = [];
         const specsDir = path.join(changeDir, 'specs');
         let totalDeltas = 0;
@@ -127,20 +338,15 @@ export class Validator {
         try {
             // 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).
+            // level.
             // 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');
             // 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) {
+            // folder like any other. Picked by the rule the archive backstop reads.
+            if ((await findRootSpecDelta(specsDir, { requireDelta })) !== undefined) {
                 hasMisplacedSpec = true;
-                issues.push({
-                    level: 'ERROR',
-                    path: 'spec.md',
-                    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.',
-                });
+                issues.push({ level: 'ERROR', path: 'spec.md', message: ROOT_SPEC_DELTA_MESSAGE });
             }
             // 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
@@ -151,12 +357,14 @@ export class Validator {
                     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.
+                // A root .md that carries a delta header is reported by
+                // rootDeltaFileIssues instead, from the one list archive warns about.
                 if (segments.length === 1)
                     continue;
-                if (segments.length > 2) {
+                // Judged by specLayoutFault, the rule apply's apply_specs_misplaced
+                // warning reads, so apply cannot call ready what this refuses.
+                const fault = specLayoutFault(entryPath);
+                if (fault === 'nested') {
                     hasMisplacedSpec = true;
                     // The fix is mechanical, so name the flattened path outright:
                     // specs/platform/session/spec.md -> specs/platform-session/spec.md.
@@ -171,7 +379,7 @@ export class Validator {
                 // 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('.')) {
+                if (fault === 'dot-folder') {
                     hasMisplacedSpec = true;
                     issues.push({
                         level: 'ERROR',
@@ -183,7 +391,7 @@ export class Validator {
                 // 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') {
+                if (fault === 'misnamed') {
                     hasMisplacedSpec = true;
                     issues.push({
                         level: 'ERROR',
@@ -194,8 +402,12 @@ export class Validator {
                 }
                 specFiles.push(specFile);
             }
+            const mainSpecNames = await listMainSpecNames(mainSpecsDir);
             for (const specFile of specFiles) {
                 const entryPath = FileSystemUtils.toPosixPath(path.relative(specsDir, specFile));
+                if (mainSpecNames !== undefined) {
+                    issues.push(...capabilityNameIssues(entryPath, mainSpecNames));
+                }
                 let content;
                 try {
                     content = await fs.readFile(specFile, 'utf-8');
@@ -230,8 +442,9 @@ export class Validator {
                 // 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)));
+                // An existing capability owns its Purpose, so there only the drop is
+                // reported.
+                issues.push(...(await this.collectDeltaPurposeIssues(content, plan, 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) {
@@ -242,6 +455,29 @@ 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.`,
                     });
                 }
+                // WARNING, not ERROR: a requirement outside every delta section is
+                // usually a misplaced one, but the scan cannot tell it from prose that
+                // happens to quote a header, and archive merges nothing from it either way.
+                for (const orphan of plan.orphanRequirements) {
+                    const where = orphan.section === null ? 'before the first "##" section' : `under "## ${orphan.section}", which is not a delta section`;
+                    issues.push({
+                        level: 'WARNING',
+                        path: entryPath,
+                        line: orphan.line,
+                        message: `Requirement "${orphan.name}" (line ${orphan.line}) sits ${where}, so it is neither validated nor merged on archive. Move it under "## ADDED Requirements" or "## MODIFIED Requirements", or fix the section header's spelling.`,
+                    });
+                }
+                // Only near misses of a delta title: archive also leaves `## Notes`
+                // unmerged, but that is a heading the author meant. WARNING for the same
+                // reason as above: the title may sit close to a delta title on purpose.
+                for (const section of plan.misspelledSections) {
+                    issues.push({
+                        level: 'WARNING',
+                        path: entryPath,
+                        line: section.line,
+                        message: `Section "${section.title}" (line ${section.line}) is not a delta section, so nothing under it is validated or merged on archive. Rename it to "${section.suggestion}".`,
+                    });
+                }
                 // 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
@@ -300,8 +536,13 @@ export class Validator {
                             });
                             continue;
                         }
-                        if (seen.has(key)) {
-                            issues.push({ level: 'ERROR', path: entryPath, message: `Duplicate requirement in ${section}: "${block.name}"` });
+                        const earlier = findFoldedMatch(seen, key);
+                        if (earlier !== undefined) {
+                            issues.push({
+                                level: 'ERROR',
+                                path: entryPath,
+                                message: `Duplicate requirement in ${section}: "${block.name}"${foldedDuplicateNote(earlier, key)}`,
+                            });
                         }
                         else {
                             seen.add(key);
@@ -314,7 +555,6 @@ export class Validator {
                             // WARNING, not ERROR: the keyword check is English-only, so at
                             // 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,
@@ -330,7 +570,6 @@ export class Validator {
                 // 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
                 // Dropped from the plan once reported: a placeholder entry would
                 // otherwise also fail the "matched nothing" check, naming one mistake
                 // twice.
@@ -355,7 +594,7 @@ export class Validator {
                     }
                     // 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, renamedToFrom, removedScenarios)));
+                    issues.push(...(await this.collectDroppedScenarioIssues(mainSpecsDir, entryPath.split('/')[0], plan.modified, entryPath, renamedToFrom, removedScenarios, path.basename(changeDir))));
                 }
                 // The template requires Reason and Migration on every REMOVED entry.
                 for (const entry of plan.removedEntries) {
@@ -370,8 +609,13 @@ export class Validator {
                         });
                         continue;
                     }
-                    if (removedNames.has(key)) {
-                        issues.push({ level: 'ERROR', path: entryPath, message: `Duplicate requirement in REMOVED: "${entry.name}"` });
+                    const earlierRemoved = findFoldedMatch(removedNames, key);
+                    if (earlierRemoved !== undefined) {
+                        issues.push({
+                            level: 'ERROR',
+                            path: entryPath,
+                            message: `Duplicate requirement in REMOVED: "${entry.name}"${foldedDuplicateNote(earlierRemoved, key)}`,
+                        });
                     }
                     else {
                         removedNames.add(key);
@@ -420,14 +664,24 @@ export class Validator {
                         });
                         continue;
                     }
-                    if (renamedFrom.has(fromKey)) {
-                        issues.push({ level: 'ERROR', path: entryPath, message: `Duplicate FROM in RENAMED: "${from}"` });
+                    const earlierFrom = findFoldedMatch(renamedFrom, fromKey);
+                    if (earlierFrom !== undefined) {
+                        issues.push({
+                            level: 'ERROR',
+                            path: entryPath,
+                            message: `Duplicate FROM in RENAMED: "${from}"${foldedDuplicateNote(earlierFrom, fromKey)}`,
+                        });
                     }
                     else {
                         renamedFrom.add(fromKey);
                     }
-                    if (renamedTo.has(toKey)) {
-                        issues.push({ level: 'ERROR', path: entryPath, message: `Duplicate TO in RENAMED: "${to}"` });
+                    const earlierTo = findFoldedMatch(renamedTo, toKey);
+                    if (earlierTo !== undefined) {
+                        issues.push({
+                            level: 'ERROR',
+                            path: entryPath,
+                            message: `Duplicate TO in RENAMED: "${to}"${foldedDuplicateNote(earlierTo, toKey)}`,
+                        });
                     }
                     else {
                         renamedTo.add(toKey);
@@ -452,10 +706,75 @@ export class Validator {
                     if (modifiedNames.has(fromKey)) {
                         issues.push({ level: 'ERROR', path: entryPath, message: `MODIFIED references old name from RENAMED. Use new header for "${to}"` });
                     }
-                    if (addedNames.has(toKey)) {
+                    // Folded, as the merge checks it: a TO that differs from an ADDED name
+                    // only in case or spacing would land two requirements no reader can
+                    // tell apart.
+                    if (findFoldedMatch(addedNames, toKey) !== undefined) {
                         issues.push({ level: 'ERROR', path: entryPath, message: `RENAMED TO collides with ADDED for "${to}"` });
                     }
                 }
+                // A MODIFIED replaces the whole main-spec block with the text it was
+                // written against, so two changes rewriting one requirement lose the
+                // edit of whichever archives first. When only the prose differs, the
+                // scenario and bullet checks above see nothing. Comparing the prose to
+                // the main spec would flag every deliberate rewrite, and a recorded
+                // base would be state tospec does not keep; the other change's delta
+                // is the evidence that is on disk. Read once per run, and only when
+                // this delta rewrites something.
+                const rewrites = listDeltaTouches(plan, ['MODIFIED', 'REMOVED', 'RENAMED']);
+                if (mainSpecsDir !== undefined && checkSisterChanges && rewrites.length > 0) {
+                    const changesDir = path.join(path.dirname(mainSpecsDir), 'changes');
+                    sisters ??= await listSisterChangeDeltas(changesDir, path.basename(changeDir));
+                    const capability = entryPath.split('/')[0];
+                    // With no main spec, the archive-blocker WARNING below already names
+                    // every change that ADDs this capability, so a sister ADDED here
+                    // would report one cause twice. Only when that blocker is raised:
+                    // without the preflight, this is the only hint.
+                    const blockerNamesAdders = archivePreflight &&
+                        (plan.modified.length > 0 || plan.removed.length > 0 || plan.renamed.length > 0) &&
+                        (await isMissingMainSpec(mainSpecsDir, capability));
+                    const sisterOperations = blockerNamesAdders
+                        ? ['MODIFIED', 'REMOVED', 'RENAMED']
+                        : ['ADDED', 'MODIFIED', 'REMOVED', 'RENAMED'];
+                    const mainNames = await readMainRequirementNames(mainSpecsDir, capability);
+                    const mismatches = mainNames === undefined ? [] : findHeaderMismatches(capability, rewrites, sisters, mainNames);
+                    for (const mismatch of mismatches) {
+                        // No `blockedBy`: no archive order makes this delta apply, so
+                        // naming the sister would tell an agent to wait on a fix that
+                        // never comes.
+                        issues.push({
+                            level: 'ERROR',
+                            path: entryPath,
+                            ...(mismatch.own.line === undefined ? {} : { line: mismatch.own.line }),
+                            code: REQUIREMENT_HEADER_MISMATCH_CODE,
+                            suggestedHeader: mismatch.suggestedHeader,
+                            message: headerMismatchMessage(mismatch),
+                        });
+                    }
+                    for (const { change, own, sister } of findSharedRequirements(capability, rewrites, sisters, sisterOperations)) {
+                        // The pair the mismatch ERROR names. Its overlap advice ("archive
+                        // the sister first") holds only once the header is fixed, and the
+                        // re-run after that fix reports it, with its `blockedBy`.
+                        if (sister.operation === 'ADDED' && mismatches.some((m) => m.change === change && m.own === own))
+                            continue;
+                        const at = own.line === undefined ? '' : ` (line ${own.line})`;
+                        const order = sister.operation === 'ADDED'
+                            ? 'sister-first'
+                            : compareChangeAge(await orderKeyOf(changeDir), await orderKeyOf(path.join(changesDir, change)));
+                        // `blockedBy` only on the side told to wait. The older side is
+                        // told to archive first and the unordered pair to decide: neither
+                        // waits on anyone, and naming the sister there would tell an
+                        // agent to hold this change back behind it.
+                        issues.push({
+                            level: 'WARNING',
+                            path: entryPath,
+                            ...(own.line === undefined ? {} : { line: own.line }),
+                            code: SISTER_CHANGE_OVERLAP_CODE,
+                            ...(order === 'sister-first' ? { blockedBy: [change] } : {}),
+                            message: `${own.operation} "${own.requirement}"${at}: in-progress change '${change}' also acts on this requirement (${sister.operation}), and the change archived second overwrites the first one's edit with the text it was written against. ${sisterArchiveAdvice(change, sister.operation, order)}`,
+                        });
+                    }
+                }
             }
         }
         catch (error) {
@@ -483,12 +802,22 @@ export class Validator {
         // the main spec's scenarios. None asks whether the main spec can supply the
         // target the delta acts on — the merge's own preconditions.
         if (mainSpecsDir !== undefined && archivePreflight) {
-            issues.push(...(await this.findArchiveBlockers(changeDir, mainSpecsDir)));
+            // A header mismatch is not a structural fault, so it does not vouch for
+            // a rebuilt-spec failure as already reported.
+            const structuralErrorPaths = new Set(issues.filter((i) => i.level === 'ERROR' && i.code !== REQUIREMENT_HEADER_MISMATCH_CODE).map((i) => i.path));
+            const findings = await this.findArchiveBlockers(changeDir, mainSpecsDir, structuralErrorPaths);
+            // Coded here, not in the dry run: apply reads the same findings and
+            // reports them under its own status code.
+            issues.push(...findings.map((finding) => finding.refuses ? { ...finding.issue, code: ARCHIVE_REFUSAL_CODE } : finding.issue));
         }
         // 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) });
+        if (requireDelta && totalDeltas === 0 && !hasMisplacedSpec) {
+            issues.push({
+                level: 'ERROR',
+                path: 'file',
+                message: `${VALIDATION_MESSAGES.CHANGE_NO_DELTAS}. ${noDeltasGuide(path.basename(changeDir))}`,
+            });
         }
         // The ceiling `ChangeSchema.deltas.max()` declares. WARNING because the rule
         // is advice about change size, not a correctness claim; `--strict` is what
@@ -583,7 +912,6 @@ export class Validator {
             // WARNING, not ERROR: the keyword check is English-only, so at ERROR it
             // 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',
@@ -663,18 +991,33 @@ export class Validator {
     /**
      * 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.
+     * For an existing capability, only that a delta Purpose will be dropped.
      *
      * `mainSpecsDir` absent means new capabilities cannot be told from existing
      * ones, so nothing is reported.
      */
-    async collectDeltaPurposeIssues(content, entryPath, mainSpecsDir) {
+    async collectDeltaPurposeIssues(content, plan, entryPath, mainSpecsDir) {
         if (mainSpecsDir === undefined)
             return [];
         const purpose = extractDeltaPurpose(content);
         const capability = entryPath.split('/')[0];
+        const mainSpecPath = path.join(mainSpecsDir, capability, 'spec.md');
         try {
-            await fs.access(path.join(mainSpecsDir, capability, 'spec.md'));
-            return []; // Capability exists: its own spec owns the Purpose.
+            await fs.access(mainSpecPath);
+            // Capability exists: its own spec owns the Purpose, and archive drops the
+            // delta's with `archive_delta_purpose_ignored`. Said here too, worded as
+            // that notice is, because archive is too late: the author who wrote it
+            // meant to change the Purpose, and by then the change is archived.
+            if (!purpose)
+                return [];
+            const onDisk = await resolveOnDiskSpecName(mainSpecPath, capability);
+            return [
+                {
+                    level: 'WARNING',
+                    path: entryPath,
+                    message: `Delta "## Purpose" will be ignored on archive; ${onDisk} already has a main spec and owns its Purpose. Edit tospec/specs/${onDisk}/spec.md directly if it needs changing, and remove the Purpose from this delta.`,
+                },
+            ];
         }
         catch (error) {
             // Only a genuinely absent spec means "new capability"; guessing "new"
@@ -682,6 +1025,13 @@ export class Validator {
             if (!isMissingPathError(error))
                 return [];
         }
+        // Archive refuses a MODIFIED, REMOVED or RENAMED on a capability with no
+        // main spec before it reads the Purpose, and the archive-blocker WARNING
+        // says so. Advice on the Purpose here sent authors to add one, which turns
+        // into "will be ignored on archive" once the change that adds the
+        // capability archives first — the usual way out of this state.
+        if (plan.modified.length > 0 || plan.removed.length > 0 || plan.renamed.length > 0)
+            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
@@ -729,7 +1079,9 @@ export class Validator {
      * author means to drop, so omitting it from the MODIFIED block stops being
      * the accident this check exists to catch.
      */
-    declaredRemovals) {
+    declaredRemovals, 
+    /** Named in the `show --diff` hint, so the hint runs as written. */
+    changeName) {
         let content;
         try {
             content = await fs.readFile(path.join(mainSpecsDir, capability, 'spec.md'), 'utf-8');
@@ -838,19 +1190,24 @@ export class Validator {
                     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.`,
+                        `copy of the requirement — run tospec show "${changeName}" --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.
+        const renamed = [...renamedToFrom].map(([to, from]) => ({ from, to }));
         for (const entry of unmatchedRemovals) {
+            const renameHint = postRenameRemovalHint(entry, renamed);
             issues.push({
                 level: 'ERROR',
                 path: entryPath,
                 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.`,
+                message: `REMOVED Scenarios declares "${entry.scenario}" under requirement "${entry.requirement}", but no MODIFIED block for that requirement drops that scenario. ` +
+                    (renameHint === undefined
+                        ? `Check both names against tospec/specs/${capability}/spec.md — a declaration that matches nothing removes nothing.`
+                        : `${renameHint}.`),
             });
         }
         return issues;
@@ -867,13 +1224,13 @@ export class Validator {
      * 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) {
+    async findArchiveBlockers(changeDir, mainSpecsDir, structuralErrorPaths) {
         // 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 = [];
+        const findings = [];
+        let sisters;
         let updates;
         try {
             updates = await findSpecUpdates(changeDir, mainSpecsDir);
@@ -883,9 +1240,12 @@ export class Validator {
             // the structural pass walks the same tree and its findings are actionable.
             return [
                 {
-                    level: 'INFO',
-                    path: 'specs',
-                    message: `Could not check the merge preconditions: ${error instanceof Error ? error.message : String(error)}`,
+                    refuses: false,
+                    issue: {
+                        level: 'INFO',
+                        path: 'specs',
+                        message: `Could not check the merge preconditions: ${error instanceof Error ? error.message : String(error)}`,
+                    },
                 },
             ];
         }
@@ -895,7 +1255,14 @@ export class Validator {
             const capability = path.basename(path.dirname(update.source));
             const entryPath = FileSystemUtils.toPosixPath(`${capability}/spec.md`);
             try {
-                const built = await buildUpdatedSpec(update, changeName, { silent: true });
+                // The structural pass above already reports the merge's structural
+                // failures in its own, more precise wording, so the merge defers them
+                // and goes on to the preconditions checked nowhere else (a MODIFIED or
+                // RENAMED target the main spec lacks, an ADDED that collides). Throwing
+                // on the first used to hide those until it was fixed, one round trip
+                // per finding; filtering its message afterwards could not bring back
+                // the checks the throw had skipped.
+                const built = await buildUpdatedSpec(update, changeName, { silent: true, deferStructural: 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.
@@ -905,12 +1272,26 @@ export class Validator {
                 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}`,
+                    findings.push({
+                        refuses: false,
+                        issue: {
+                            level: 'WARNING',
+                            path: entryPath,
+                            message: `Archive would accept this delta but remove nothing: ${notice.message}`,
+                        },
                     });
                 }
+                // Archive validates the rebuilt spec before writing it, so a main spec
+                // that is already broken refuses every delta aimed at it — while the
+                // checks above, which read only the delta, call the change valid.
+                // A retired capability is deleted, not validated. A deferred merge is
+                // partial, so judging it would report the structural failures again
+                // under positional paths.
+                if (!built.retired && built.structuralFailures.length === 0) {
+                    const specName = path.basename(path.dirname(update.target));
+                    const blockers = await this.findRebuiltSpecBlockers(specName, entryPath, built, structuralErrorPaths);
+                    findings.push(...blockers.map((issue) => ({ refuses: true, issue })));
+                }
             }
             catch (error) {
                 // Only the thrown preconditions, which carry no errno. A filesystem
@@ -918,24 +1299,124 @@ export class Validator {
                 // `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: 'WARNING',
-                    path: entryPath,
-                    message: `Archive would refuse this delta: ${message}`,
+                let message = error instanceof Error ? error.message : String(error);
+                // The missing capability, or the requirement a MODIFIED or RENAMED
+                // names, may be one a sister change is still adding; then the fix is
+                // archiving that change, not editing this delta. Read once per run and
+                // only for these refusals, the ones it can explain. `blockedBy` comes
+                // from the list the hint is written from, so the field and the
+                // sentence cannot name different changes.
+                let blockedBy = [];
+                let suggestedHeader;
+                let headerCorrection;
+                if (error instanceof RequirementNearMissError) {
+                    // A typo against the main spec, whose name is settled, so the field
+                    // carries it: the agent fixes this WARNING itself, and reading the
+                    // name out of the merge's sentence would break on its rewording.
+                    suggestedHeader = error.existing;
+                    headerCorrection = { operation: error.operation, source: 'main-spec' };
+                }
+                else if (error instanceof MissingTargetSpecError || error instanceof MissingTargetRequirementError) {
+                    sisters ??= await listSisterChangeDeltas(path.join(path.dirname(mainSpecsDir), 'changes'), changeName);
+                    const requirement = error instanceof MissingTargetRequirementError ? error.requirement : undefined;
+                    // A header the sister ADDs under another spelling is a second cause
+                    // no archive order settles, so the order is not the whole cause and
+                    // neither the hint nor `blockedBy` may say it is. The mismatch ERROR
+                    // reports it; `suggestedHeader` rides here so apply can name the fix.
+                    const mismatch = (await this.findDeltaHeaderMismatches(update.source, mainSpecsDir, capability, sisters, error))[0];
+                    if (mismatch !== undefined) {
+                        suggestedHeader = mismatch.suggestedHeader;
+                        headerCorrection = { operation: mismatch.own.operation, source: 'sister-change' };
+                    }
+                    else {
+                        blockedBy = addingChanges(sisters, capability, requirement);
+                        const hint = addingChangeHint(blockedBy, requirement === undefined ? 'capability' : 'requirement');
+                        if (hint !== undefined)
+                            message = appendSentence(message, hint);
+                    }
+                }
+                findings.push({
+                    refuses: true,
+                    issue: {
+                        level: 'WARNING',
+                        path: entryPath,
+                        message: `Archive would refuse this delta: ${message}`,
+                        ...(blockedBy.length > 0 ? { blockedBy } : {}),
+                        ...(suggestedHeader === undefined ? {} : { suggestedHeader }),
+                    },
+                    ...(headerCorrection === undefined ? {} : { headerCorrection }),
                 });
             }
         }
-        return issues;
+        return findings;
+    }
+    /**
+     * The header mismatches behind a missing-target refusal: the one requirement
+     * a MODIFIED or RENAMED names, or, for a capability with no main spec, every
+     * rewrite in the delta, since the merge stops before reading any of them.
+     * Through `findHeaderMismatches`, so the refusal and the sister scan's
+     * ERROR cannot disagree about which headers mismatch.
+     */
+    async findDeltaHeaderMismatches(deltaSource, mainSpecsDir, capability, sisters, error) {
+        const mainNames = await readMainRequirementNames(mainSpecsDir, capability);
+        if (mainNames === undefined)
+            return [];
+        let touches;
+        if (error instanceof MissingTargetRequirementError) {
+            touches = [{ operation: error.operation, requirement: error.requirement }];
+        }
+        else {
+            try {
+                touches = listDeltaTouches(parseDeltaSpec(await fs.readFile(deltaSource, 'utf-8')), ['MODIFIED', 'REMOVED', 'RENAMED']);
+            }
+            catch {
+                return [];
+            }
+        }
+        return findHeaderMismatches(capability, touches, sisters, mainNames);
+    }
+    /**
+     * What archive's merge would refuse in this change, from the dry run above,
+     * for `instructions apply` to report before the work starts: it said ready
+     * for a delta validate already called unarchivable, so the agent learned it
+     * after implementing. One dry run serves both, so they cannot disagree.
+     *
+     * Without the structural pass's paths: apply reports none of its findings,
+     * so a delta fault that resurfaces in the rebuilt spec is the only word apply
+     * gets of it. Suppressed there as already reported, apply would say nothing.
+     */
+    async findArchiveRefusals(changeDir, mainSpecsDir) {
+        const findings = await this.findArchiveBlockers(changeDir, mainSpecsDir, new Set());
+        return findings
+            .filter((finding) => finding.refuses)
+            .map(({ issue, headerCorrection }) => (headerCorrection === undefined ? { issue } : { issue, headerCorrection }));
+    }
+    /**
+     * The rebuilt spec's validation failures, as archive would meet them. WARNING
+     * for the reason `findArchiveBlockers` gives.
+     */
+    async findRebuiltSpecBlockers(specName, entryPath, built, structuralErrorPaths) {
+        const failure = await this.diagnoseRebuiltSpec(specName, built.rebuilt, built.original);
+        if (failure === null)
+            return [];
+        // A delta fault the structural pass already reported for this file
+        // resurfaces in the rebuilt spec as the same mistake under a positional
+        // path (ADDED without a scenario becomes `requirements[3].scenarios`).
+        // Repeating it names one mistake twice; the structural ERROR already fails
+        // the change. Only a fault that pass cannot see is reported here.
+        if (failure.source === 'delta' && structuralErrorPaths.has(entryPath))
+            return [];
+        // The finding goes last because some messages end in a multi-line example.
+        const lead = failure.source === 'main'
+            ? `Archive would refuse this delta: the main spec ${failure.specPath} already fails validation, so fix it first (the delta is not the cause). In ${failure.specPath}, `
+            : 'Archive would refuse this delta: the rebuilt spec fails validation. ';
+        return failure.issues
+            .filter((i) => i.level === 'ERROR')
+            .map((issue) => ({
+            level: 'WARNING',
+            path: entryPath,
+            message: `${lead}${issue.path}: ${issue.message}`,
+        }));
     }
     /**
      * Scenario-quality rules for a delta requirement block: only `#### Scenario:`