@seanmars/tospec 0.23.0 → 0.26.0-beta

package/dist/core/specs-apply.js

@@ -1,14 +1,111 @@
 /** Applies a change's delta specs to the main specs, independently of archiving. */
 import { promises as fs } from 'fs';
 import path from 'path';
-import { extractRequirementsSection, parseDeltaSpec, normalizeRequirementName, foldRequirementName, REQUIREMENT_HEADER_REGEX, } from './parsers/requirement-blocks.js';
+import { extractRequirementsSection, parseDeltaSpec, normalizeRequirementName, foldRequirementName, findFoldedMatch, matchRequirementHeader, sectionHeaderKey, postRenameRemovalHint, } from './parsers/requirement-blocks.js';
 import { findMainSpecStructureIssues } from './parsers/spec-structure.js';
-import { isAbsentDirectoryError, isMissingPathError } from '../utils/file-system.js';
+import { headingLevel } from './parsers/markdown-parser.js';
+import { isAbsentDirectoryError, isDirectoryEntry, isMissingPathError } from '../utils/file-system.js';
 import { buildCodeFenceMask, findMissingScenarios, normalizeDocument } from './parsers/requirement-text.js';
 import { PURPOSE_PLACEHOLDER_PREFIX, PURPOSE_PLACEHOLDER_SUFFIX, } from './validation/constants.js';
+/**
+ * A merge refused for what the main spec holds, not the delta. Typed so the
+ * caller can point its fix at the main spec: every merge error used to read
+ * "Fix the change delta specs", including a structural fault in the main spec,
+ * where no edit to the delta helps.
+ */
+export class MainSpecMergeError extends Error {
+    specPath;
+    constructor(message, 
+    /** Project-relative POSIX path of the main spec to edit. */
+    specPath) {
+        super(message);
+        this.specPath = specPath;
+        this.name = 'MainSpecMergeError';
+    }
+}
+/**
+ * A MODIFIED, REMOVED or RENAMED aimed at a capability that has no main spec. Typed so
+ * validate can tell this refusal from the others: it is the one another
+ * in-progress change's archive can resolve, and validate names that change.
+ */
+export class MissingTargetSpecError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'MissingTargetSpecError';
+    }
+}
+/**
+ * A MODIFIED or RENAMED whose requirement the main spec lacks, with no near
+ * miss to blame. Typed for the reason `MissingTargetSpecError` is: a sister
+ * change may still be adding that requirement, and validate names it.
+ */
+export class MissingTargetRequirementError extends Error {
+    requirement;
+    operation;
+    constructor(message, 
+    /** The requirement name as the delta wrote it. */
+    requirement, 
+    /** Which entry named it, so validate reads it as the delta touch it is. */
+    operation) {
+        super(message);
+        this.requirement = requirement;
+        this.operation = operation;
+        this.name = 'MissingTargetRequirementError';
+    }
+}
+/**
+ * A MODIFIED, REMOVED or RENAMED (FROM) name the main spec holds only under
+ * a spelling that differs in case or spacing. Typed so validate can hand the
+ * main spec's exact name on as `suggestedHeader`: reading it back out of the
+ * message would break on any rewording of it.
+ */
+export class RequirementNearMissError extends Error {
+    requirement;
+    existing;
+    operation;
+    constructor(message, 
+    /** The requirement name as the delta wrote it. */
+    requirement, 
+    /** The main spec's exact name, the one the delta has to use. */
+    existing, operation) {
+        super(message);
+        this.requirement = requirement;
+        this.existing = existing;
+        this.operation = operation;
+        this.name = 'RequirementNearMissError';
+    }
+}
 export async function findSpecUpdates(changeDir, mainSpecsDir) {
     const updates = [];
-    const changeSpecsDir = path.join(changeDir, 'specs');
+    for (const { capability, source } of await findDeltaSpecSources(path.join(changeDir, 'specs'))) {
+        const targetFile = path.join(mainSpecsDir, capability, 'spec.md');
+        // Same rule: calling an unreachable target absent sends the merge down the
+        // new-capability path, which rebuilds the spec from a skeleton.
+        let exists = true;
+        try {
+            await fs.access(targetFile);
+        }
+        catch (error) {
+            if (!isMissingPathError(error))
+                throw error;
+            exists = false;
+        }
+        updates.push({
+            source,
+            target: targetFile,
+            exists,
+        });
+    }
+    return updates;
+}
+/**
+ * The delta files the merge reads, one per capability folder. `show` reads
+ * this list too: with a walk of its own it listed a `SPEC.md` (on a
+ * case-insensitive file system) and a dot folder's spec.md as deltas, which
+ * validate and archive never read.
+ */
+export async function findDeltaSpecSources(changeSpecsDir) {
+    const sources = [];
     let entries;
     try {
         entries = await fs.readdir(changeSpecsDir, { withFileTypes: true });
@@ -17,42 +114,47 @@ export async function findSpecUpdates(changeDir, mainSpecsDir) {
         // An empty result means "no deltas", and archive merges nothing and reports
         // success on it. Only a genuinely absent directory may say that.
         if (isAbsentDirectoryError(error))
-            return updates;
+            return sources;
         throw error;
     }
     for (const entry of entries) {
-        if (!entry.isDirectory())
+        // Dot-directories are not capabilities: validate rejects one as a delta
+        // folder, and list, show, validate --specs and artifact status all skip
+        // one. Merging it wrote a main spec at tospec/specs/.<name>/ that none of
+        // them can reach; left out here, archive names it as an unmerged file.
+        // A linked capability folder is followed, as status and instructions
+        // follow it: skipped here, its delta was reported as nothing to merge.
+        if (!isDirectoryEntry(changeSpecsDir, entry) || entry.name.startsWith('.'))
             continue;
-        const specFile = path.join(changeSpecsDir, entry.name, 'spec.md');
-        const targetFile = path.join(mainSpecsDir, entry.name, 'spec.md');
+        const capabilityDir = path.join(changeSpecsDir, entry.name);
+        const specFile = path.join(capabilityDir, 'spec.md');
+        // Spelled exactly spec.md, as validate, findSpecFiles and artifact status
+        // read it. Asking the file system for the path lets it decide the case: on
+        // Windows and default macOS a specs/<capability>/SPEC.md merged here while
+        // validate called it ignored, and a case-sensitive file system dropped it.
+        // Left out on both, archive names it with the other misnamed deltas.
+        if (!(await fs.readdir(capabilityDir)).includes('spec.md'))
+            continue;
+        // stat, not Dirent.isFile(): it follows a link, so a linked spec.md stays a
+        // delta. A directory named spec.md is not one; taken as a source, it failed
+        // the merge with EISDIR. The access() this replaced only repeated the name
+        // check above and let that directory through.
+        let stats;
         try {
-            await fs.access(specFile);
+            stats = await fs.stat(specFile);
         }
         catch (error) {
-            // A capability folder with no spec.md is not a delta; an unreachable
-            // spec.md is one, and skipping it drops its requirements silently.
+            // A dangling link is not a delta; an unreachable spec.md is one, and
+            // skipping it drops its requirements silently.
             if (isMissingPathError(error))
                 continue;
             throw error;
         }
-        // Same rule: calling an unreachable target absent sends the merge down the
-        // new-capability path, which rebuilds the spec from a skeleton.
-        let exists = true;
-        try {
-            await fs.access(targetFile);
-        }
-        catch (error) {
-            if (!isMissingPathError(error))
-                throw error;
-            exists = false;
-        }
-        updates.push({
-            source: specFile,
-            target: targetFile,
-            exists,
-        });
+        if (!stats.isFile())
+            continue;
+        sources.push({ capability: entry.name, source: specFile });
     }
-    return updates;
+    return sources;
 }
 /**
  * The capability directory's real name on disk, or `fallback` when absent.
@@ -60,7 +162,7 @@ export async function findSpecUpdates(changeDir, mainSpecsDir) {
  * `specs/regexcap` are one directory — this normalises a message, it does not
  * merge anything.
  */
-async function resolveOnDiskSpecName(targetPath, fallback) {
+export async function resolveOnDiskSpecName(targetPath, fallback) {
     const parent = path.dirname(path.dirname(targetPath));
     try {
         const entries = await fs.readdir(parent);
@@ -77,6 +179,19 @@ export async function buildUpdatedSpec(update, changeName, options = {}) {
         if (!options.silent)
             console.log(`Warning: ${message}`);
     };
+    const structuralFailures = [];
+    const structural = (message) => {
+        if (!options.deferStructural)
+            throw new Error(message);
+        structuralFailures.push(message);
+    };
+    // Names the delta contradicts itself about (a duplicate, a cross-section
+    // conflict, an unpaired rename). Its intent for them is unknown, so a deferred
+    // run applies no operation on them: checking one against the main spec would
+    // report a consequence of the contradiction (a MODIFIED "not found" after the
+    // REMOVED that conflicts with it ran) as a second mistake. Stays empty when
+    // not deferring, since the contradiction throws first.
+    const contested = new Set();
     const changeContent = await fs.readFile(update.source, 'utf-8');
     const plan = parseDeltaSpec(changeContent);
     // The capability as the delta spelled it — messages about the delta's own
@@ -86,12 +201,21 @@ export async function buildUpdatedSpec(update, changeName, options = {}) {
     // filesystem: a delta under `specs/RegexCap/` resolves to the existing
     // `tospec/specs/regexcap/`.
     const onDiskSpecName = await resolveOnDiskSpecName(update.target, specName);
+    const mainSpecPath = `tospec/specs/${onDiskSpecName}/spec.md`;
+    // Duplicates are judged folded, the rule the cross-section checks below and
+    // the main-spec guard apply: `Foo` + `foo` in one ADDED landed two
+    // requirements no reader can tell apart, and in REMOVED the second turned
+    // into a silent "already removed" no-op.
+    const foldedDuplicateNote = (earlier, name) => earlier === name ? '' : ` (differs only in case or spacing from "${earlier}")`;
     const collectUnique = (names, section) => {
         const seen = new Set();
         for (const original of names) {
             const name = normalizeRequirementName(original);
-            if (seen.has(name)) {
-                throw new Error(`${specName} validation failed - duplicate requirement in ${section} for header "### Requirement: ${original}"`);
+            const earlier = findFoldedMatch(seen, name);
+            if (earlier !== undefined) {
+                structural(`${specName} validation failed - duplicate requirement in ${section} for header "### Requirement: ${original}"${foldedDuplicateNote(earlier, name)}`);
+                contested.add(earlier).add(name);
+                continue;
             }
             seen.add(name);
         }
@@ -100,6 +224,19 @@ export async function buildUpdatedSpec(update, changeName, options = {}) {
     const addedNames = collectUnique(plan.added.map((add) => add.name), 'ADDED');
     const modifiedNames = collectUnique(plan.modified.map((mod) => mod.name), 'MODIFIED');
     const removedNamesSet = collectUnique(plan.removed, 'REMOVED');
+    // A FROM or TO with no partner. The pairs the parser did form around it are
+    // a guess (`FROM a / FROM b / TO x / TO y` pairs b->x), and validate rejects
+    // the delta; without this, `--no-validate` applied the guess.
+    if (plan.renamedIssues.length > 0) {
+        const issue = plan.renamedIssues[0];
+        const side = issue.kind === 'from-without-to' ? 'FROM' : 'TO';
+        const missing = issue.kind === 'from-without-to' ? 'TO:' : 'FROM:';
+        structural(`${specName} validation failed - RENAMED ${side} "${issue.name}" (line ${issue.line}) has no matching ${missing} line; write RENAMED entries as FROM:/TO: pairs`);
+        // Every pair the parser formed is a guess once one side is unpaired.
+        for (const { from, to } of plan.renamed) {
+            contested.add(normalizeRequirementName(from)).add(normalizeRequirementName(to));
+        }
+    }
     // Checked per entry rather than via collectUnique: a pair that duplicates
     // both sides must report the FROM/TO the original interleaving would.
     const renamedFromSet = new Set();
@@ -107,11 +244,17 @@ export async function buildUpdatedSpec(update, changeName, options = {}) {
     for (const { from, to } of plan.renamed) {
         const fromNorm = normalizeRequirementName(from);
         const toNorm = normalizeRequirementName(to);
-        if (renamedFromSet.has(fromNorm)) {
-            throw new Error(`${specName} validation failed - duplicate FROM in RENAMED for header "### Requirement: ${from}"`);
+        const earlierFrom = findFoldedMatch(renamedFromSet, fromNorm);
+        if (earlierFrom !== undefined) {
+            structural(`${specName} validation failed - duplicate FROM in RENAMED for header "### Requirement: ${from}"${foldedDuplicateNote(earlierFrom, fromNorm)}`);
+            contested.add(earlierFrom).add(fromNorm).add(toNorm);
+            continue;
         }
-        if (renamedToSet.has(toNorm)) {
-            throw new Error(`${specName} validation failed - duplicate TO in RENAMED for header "### Requirement: ${to}"`);
+        const earlierTo = findFoldedMatch(renamedToSet, toNorm);
+        if (earlierTo !== undefined) {
+            structural(`${specName} validation failed - duplicate TO in RENAMED for header "### Requirement: ${to}"${foldedDuplicateNote(earlierTo, toNorm)}`);
+            contested.add(earlierTo).add(fromNorm).add(toNorm);
+            continue;
         }
         renamedFromSet.add(fromNorm);
         renamedToSet.add(toNorm);
@@ -133,27 +276,46 @@ export async function buildUpdatedSpec(update, changeName, options = {}) {
         // A REMOVED naming the FROM side contradicts the rename. Since a missing
         // REMOVED target is a no-op (early-sync), this must be rejected explicitly.
         // Folded, so a case or whitespace variant cannot slip past as a no-op.
-        const removedFoldMatch = [...removedNamesSet].find((r) => foldRequirementName(r) === foldRequirementName(fromNorm));
+        const removedFoldMatch = findFoldedMatch(removedNamesSet, fromNorm);
         if (removedFoldMatch !== undefined) {
-            throw new Error(`${specName} validation failed - requirement present in multiple sections (RENAMED and REMOVED) for header "### Requirement: ${from}"` +
+            structural(`${specName} validation failed - requirement present in multiple sections (RENAMED and REMOVED) for header "### Requirement: ${from}"` +
                 (removedFoldMatch === fromNorm ? '' : ` (REMOVED spells it "${removedFoldMatch}")`));
+            contested.add(removedFoldMatch).add(fromNorm).add(toNorm);
         }
         if (modifiedNames.has(fromNorm)) {
-            throw new Error(`${specName} validation failed - when a rename exists, MODIFIED must reference the NEW header "### Requirement: ${to}"`);
+            structural(`${specName} validation failed - when a rename exists, MODIFIED must reference the NEW header "### Requirement: ${to}"`);
+            contested.add(fromNorm).add(toNorm);
         }
-        if (addedNames.has(toNorm)) {
-            throw new Error(`${specName} validation failed - RENAMED TO header collides with ADDED for "### Requirement: ${to}"`);
+        // Folded: `LATE  FEES` and `late fees` are one name to a reader, and both
+        // landing would leave two requirements no one can tell apart.
+        const addedFoldMatch = findFoldedMatch(addedNames, toNorm);
+        if (addedFoldMatch !== undefined) {
+            structural(`${specName} validation failed - RENAMED TO header collides with ADDED for "### Requirement: ${to}"` +
+                (addedFoldMatch === toNorm ? '' : ` (ADDED spells it "${addedFoldMatch}")`));
+            contested.add(addedFoldMatch).add(fromNorm).add(toNorm);
         }
     }
     if (conflicts.length > 0) {
         const c = conflicts[0];
-        throw new Error(`${specName} validation failed - requirement present in multiple sections (${c.a} and ${c.b}) for header "### Requirement: ${c.name}"`);
+        structural(`${specName} validation failed - requirement present in multiple sections (${c.a} and ${c.b}) for header "### Requirement: ${c.name}"`);
+        for (const conflict of conflicts)
+            contested.add(conflict.name);
     }
     const hasAnyDelta = plan.added.length + plan.modified.length + plan.removed.length + plan.renamed.length > 0;
     if (!hasAnyDelta) {
-        throw new Error(`Delta parsing found no operations for ${path.basename(path.dirname(update.source))}. ` +
+        structural(`Delta parsing found no operations for ${path.basename(path.dirname(update.source))}. ` +
             `Provide ADDED/MODIFIED/REMOVED/RENAMED sections in change spec.`);
     }
+    // The merge reads delta sections only. Anything else in the file stays in the
+    // archived change and never reaches the main spec, so name it at the moment
+    // the author can still move it.
+    const strays = [
+        ...plan.orphanRequirements.map((orphan) => `requirement "${orphan.name}" (line ${orphan.line})`),
+        ...plan.unmergedSections.map((section) => `"${section.title}" (line ${section.line})`),
+    ];
+    if (strays.length > 0) {
+        notice('archive_delta_content_not_merged', `${specName} - content outside the delta sections is not merged into the main spec: ${strays.join(', ')}.`);
+    }
     let targetContent;
     let isNewSpec = false;
     try {
@@ -164,11 +326,14 @@ export async function buildUpdatedSpec(update, changeName, options = {}) {
         // may exist with content the skeleton rebuild below would discard.
         if (!isMissingPathError(error))
             throw error;
-        if (plan.modified.length > 0 || plan.renamed.length > 0) {
-            throw new Error(`${specName}: target spec does not exist; only ADDED requirements are allowed for new specs. MODIFIED and RENAMED operations require an existing spec.`);
-        }
-        if (plan.removed.length > 0) {
-            notice('archive_removed_ignored_new_spec', `${specName} - ${plan.removed.length} REMOVED requirement(s) ignored for new spec (nothing to remove).`);
+        // REMOVED included: it was a notice ("nothing to remove") and the merge went
+        // on, so a REMOVED-only delta failed later as an empty rebuilt spec, and one
+        // beside an ADDED archived with its removal dropped. A REMOVED names a
+        // requirement its author expects to exist; with no main spec, that is a
+        // sister change's ADDED (archived after this, it brings the requirement
+        // back) or a wrong capability, and either way the refusal is the answer.
+        if (plan.modified.length > 0 || plan.removed.length > 0 || plan.renamed.length > 0) {
+            throw new MissingTargetSpecError(`${specName}: target spec does not exist; only ADDED requirements are allowed for new specs. MODIFIED, REMOVED and RENAMED operations require an existing spec.`);
         }
         isNewSpec = true;
         // Only plain prose is carried; a Purpose that could restructure the spec
@@ -209,7 +374,7 @@ export async function buildUpdatedSpec(update, changeName, options = {}) {
         const details = structureIssues
             .map(issue => `line ${issue.line}: ${issue.message}`)
             .join('\n');
-        throw new Error(`${specName}: target spec is structurally invalid and cannot be updated until fixed:\n${details}`);
+        throw new MainSpecMergeError(`${specName}: target spec is structurally invalid and cannot be updated until fixed:\n${details}`, mainSpecPath);
     }
     const parts = extractRequirementsSection(targetContent);
     const nameToBlock = new Map();
@@ -225,16 +390,33 @@ export async function buildUpdatedSpec(update, changeName, options = {}) {
     for (const r of plan.renamed) {
         const from = normalizeRequirementName(r.from);
         const to = normalizeRequirementName(r.to);
+        if (contested.has(from) || contested.has(to))
+            continue;
         if (!nameToBlock.has(from)) {
             // Source gone but target present: the rename was already synced.
             if (nameToBlock.has(to)) {
                 continue;
             }
-            throw new Error(`${specName} RENAMED failed for header "### Requirement: ${r.from}" - source not found`);
+            // The near miss MODIFIED and REMOVED report. "source not found" alone
+            // is also what a sister change still adding the requirement looks like,
+            // so a case typo here read as an archive-order problem.
+            const nearMiss = findFoldedMatch(nameToBlock.keys(), from);
+            if (nearMiss !== undefined) {
+                const existing = nameToBlock.get(nearMiss).name;
+                throw new RequirementNearMissError(`${specName} RENAMED failed for header "### Requirement: ${r.from}" - source not found, but "### Requirement: ${existing}" exists; fix the FROM line to match it exactly`, r.from, existing, 'RENAMED');
+            }
+            throw new MissingTargetRequirementError(`${specName} RENAMED failed for header "### Requirement: ${r.from}" - source not found`, r.from, 'RENAMED');
         }
         if (nameToBlock.has(to)) {
             throw new Error(`${specName} RENAMED failed for header "### Requirement: ${r.to}" - target already exists`);
         }
+        // The source is exempt, so a case-only rename (`late fees` -> `Late Fees`)
+        // stays legal; any other folded match is a second spelling of a name the
+        // spec already has.
+        const renameNearMiss = findFoldedNameClash(nameToBlock, to, from);
+        if (renameNearMiss !== undefined) {
+            throw new Error(`${specName} RENAMED failed for header "### Requirement: ${r.to}" - "### Requirement: ${renameNearMiss}" already exists and differs only in case or spacing`);
+        }
         const block = nameToBlock.get(from);
         const newHeader = `### Requirement: ${to}`;
         const rawLines = block.raw.split('\n');
@@ -262,17 +444,19 @@ export async function buildUpdatedSpec(update, changeName, options = {}) {
     const removedKeys = new Set();
     for (const name of plan.removed) {
         const key = normalizeRequirementName(name);
+        if (contested.has(key))
+            continue;
         if (!nameToBlock.has(key)) {
             // Already gone means the removal was already synced. A near miss — one
             // still present differing only in case or interior whitespace — is a typo
-            // instead, and stays a hard abort.
-            if (!isNewSpec) {
-                const nearMiss = [...nameToBlock.keys()].find((k) => foldRequirementName(k) === foldRequirementName(key));
-                if (nearMiss !== undefined) {
-                    throw new Error(`${specName} REMOVED failed for header "### Requirement: ${name}" - not found, but "### Requirement: ${nameToBlock.get(nearMiss).name}" exists; fix the header to match it exactly`);
-                }
-                notice('archive_removed_requirement_absent', `${specName} - REMOVED requirement "${name}" is not in the current spec; treating it as already removed. Nothing was deleted — if you meant to remove a requirement, check the header spelling against tospec/specs/${onDiskSpecName}/spec.md.`);
+            // instead, and stays a hard abort. A new spec never gets here: a REMOVED
+            // without a main spec is refused above.
+            const nearMiss = findFoldedMatch(nameToBlock.keys(), key);
+            if (nearMiss !== undefined) {
+                const existing = nameToBlock.get(nearMiss).name;
+                throw new RequirementNearMissError(`${specName} REMOVED failed for header "### Requirement: ${name}" - not found, but "### Requirement: ${existing}" exists; fix the header to match it exactly`, name, existing, 'REMOVED');
             }
+            notice('archive_removed_requirement_absent', `${specName} - REMOVED requirement "${name}" is not in the current spec; treating it as already removed. Nothing was deleted — if you meant to remove a requirement, check the header spelling against tospec/specs/${onDiskSpecName}/spec.md.`);
             continue;
         }
         nameToBlock.delete(key);
@@ -288,12 +472,21 @@ export async function buildUpdatedSpec(update, changeName, options = {}) {
     const unmatchedDeclarations = new Set(plan.removedScenarios);
     for (const mod of plan.modified) {
         const key = normalizeRequirementName(mod.name);
+        if (contested.has(key))
+            continue;
         const currentBlock = nameToBlock.get(key);
         if (!currentBlock) {
-            throw new Error(`${specName} MODIFIED failed for header "### Requirement: ${mod.name}" - not found`);
-        }
-        const modHeaderMatch = mod.raw.split('\n')[0].match(REQUIREMENT_HEADER_REGEX);
-        if (!modHeaderMatch || normalizeRequirementName(modHeaderMatch[1]) !== key) {
+            // The same near-miss hint REMOVED gives: "not found" alone sends the
+            // author looking for a missing requirement rather than a case typo.
+            const nearMiss = findFoldedMatch(nameToBlock.keys(), key);
+            const notFound = `${specName} MODIFIED failed for header "### Requirement: ${mod.name}" - not found`;
+            if (nearMiss === undefined)
+                throw new MissingTargetRequirementError(notFound, mod.name, 'MODIFIED');
+            const existing = nameToBlock.get(nearMiss).name;
+            throw new RequirementNearMissError(`${notFound}, but "### Requirement: ${existing}" exists; fix the header to match it exactly`, mod.name, existing, 'MODIFIED');
+        }
+        const modHeaderName = matchRequirementHeader(mod.raw.split('\n')[0]);
+        if (modHeaderName === null || normalizeRequirementName(modHeaderName) !== key) {
             throw new Error(`${specName} MODIFIED failed for header "### Requirement: ${mod.name}" - header mismatch in content`);
         }
         // Guards against a stale MODIFIED block dropping scenarios a previous
@@ -310,7 +503,9 @@ export async function buildUpdatedSpec(update, changeName, options = {}) {
             return false;
         });
         if (missingScenarios.length > 0) {
-            throw new Error(`${specName} MODIFIED failed for header "### Requirement: ${mod.name}" - current spec contains scenario(s) not present in the modified block: ${missingScenarios.map(name => `"${name}"`).join(', ')}. Refresh the change spec before archiving to avoid dropping scenarios.`);
+            // Deferred, the block is applied as written: the scenario loss is the
+            // only fault, and it does not change which names the spec holds.
+            structural(`${specName} MODIFIED failed for header "### Requirement: ${mod.name}" - current spec contains scenario(s) not present in the modified block: ${missingScenarios.map(name => `"${name}"`).join(', ')}. Refresh the change spec before archiving to avoid dropping scenarios.`);
         }
         // A plain `### Notes` after the requirement is absorbed into its block (see
         // the recompose pass below), and replacing the block wholesale deleted it
@@ -320,11 +515,23 @@ export async function buildUpdatedSpec(update, changeName, options = {}) {
         nameToBlock.set(key, absorbed ? { ...mod, raw: `${mod.raw.trimEnd()}\n\n${absorbed}` } : mod);
     }
     for (const entry of unmatchedDeclarations) {
-        throw new Error(`${specName} REMOVED Scenarios declares "${entry.scenario}" under requirement "${entry.requirement}", but no MODIFIED block for that requirement drops that scenario - the declaration removes nothing on its own. Restate the requirement under "## MODIFIED Requirements" without that scenario, or check both names against the current spec.`);
+        const renameHint = postRenameRemovalHint(entry, plan.renamed);
+        const message = `${specName} REMOVED Scenarios declares "${entry.scenario}" under requirement "${entry.requirement}", but no MODIFIED block for that requirement drops that scenario - the declaration removes nothing on its own. ` +
+            (renameHint === undefined
+                ? 'Restate the requirement under "## MODIFIED Requirements" without that scenario, or check both names against the current spec.'
+                : `${renameHint}.`);
+        // Structural only against an existing main spec: that is the only case
+        // validate's own check reads (it has no spec to match a new capability's
+        // declarations against), so deferring a new capability's would hide it.
+        if (isNewSpec)
+            throw new Error(message);
+        structural(message);
     }
     let addedApplied = 0;
     for (const add of plan.added) {
         const key = normalizeRequirementName(add.name);
+        if (contested.has(key))
+            continue;
         const existing = nameToBlock.get(key);
         if (existing) {
             // Identical content means it was already synced; only differing content
@@ -334,6 +541,10 @@ export async function buildUpdatedSpec(update, changeName, options = {}) {
             }
             throw new Error(`${specName} ADDED failed for header "### Requirement: ${add.name}" - already exists`);
         }
+        const addNearMiss = findFoldedNameClash(nameToBlock, key);
+        if (addNearMiss !== undefined) {
+            throw new Error(`${specName} ADDED failed for header "### Requirement: ${add.name}" - "### Requirement: ${addNearMiss}" already exists and differs only in case or spacing`);
+        }
         nameToBlock.set(key, add);
         addedApplied++;
     }
@@ -375,7 +586,17 @@ export async function buildUpdatedSpec(update, changeName, options = {}) {
     // delete that content with the file; writing it would produce a spec with no
     // requirements, which cannot validate. Neither is safe to choose silently.
     if (keptRequirements === 0 && removedApplied > 0 && salvagedCount > 0) {
-        throw new Error(`${specName}: removing every requirement would leave content that is not part of any requirement (e.g. a "### Notes" section). Move that content out of ${specName}/spec.md first, then archive again.`);
+        throw new MainSpecMergeError(`${specName}: removing every requirement would leave content that is not part of any requirement (e.g. a "### Notes" section). Move that content out of ${specName}/spec.md first, then archive again.`, mainSpecPath);
+    }
+    // The same refusal for a section outside `## Requirements`: retiring deleted
+    // a `## Notes` or `# Appendix` with the file, with no word, while the same
+    // notes inside a requirement block were refused above. The title, Purpose and
+    // the Requirements section itself are what a retirement is meant to delete.
+    if (keptRequirements === 0 && removedApplied > 0) {
+        const lost = sectionsLostOnRetire(parts.before, parts.after);
+        if (lost.length > 0) {
+            throw new MainSpecMergeError(`${specName}: removing every requirement would delete ${onDiskSpecName}/spec.md, and with it the content outside its requirements: ${lost.map((title) => `"${title}"`).join(', ')}. Move that content out of ${specName}/spec.md first, then archive again.`, mainSpecPath);
+        }
     }
     const reqBody = [parts.preamble && parts.preamble.trim() ? parts.preamble.trimEnd() : '']
         .filter(Boolean)
@@ -403,8 +624,60 @@ export async function buildUpdatedSpec(update, changeName, options = {}) {
             removed: removedApplied,
             renamed: renamedApplied,
         },
+        // The main spec as read, for a caller that must tell whether a rebuilt
+        // spec fails because of the delta or because of what it was merged into.
+        // Absent for a new capability, whose skeleton is the merge's own text.
+        original: isNewSpec ? undefined : { path: mainSpecPath, content: targetContent },
+        // Non-empty only under `deferStructural`, and then `rebuilt` is a partial
+        // merge: it skipped what the failures name and must not be judged as the
+        // spec archive would write.
+        structuralFailures,
     };
 }
+/**
+ * The name of a requirement already in `blocks` that differs from `name` only
+ * in case or interior whitespace, ignoring `exempt` (a rename's own source).
+ * Matching stays exact everywhere else; this only refuses a second spelling.
+ */
+function findFoldedNameClash(blocks, name, exempt) {
+    const folded = foldRequirementName(name);
+    for (const [key, block] of blocks) {
+        if (key === name || key === exempt)
+            continue;
+        if (foldRequirementName(key) === folded)
+            return block.name;
+    }
+    return undefined;
+}
+/**
+ * The sections of a main spec, outside `## Requirements`, that hold a
+ * non-blank line: the content a retirement would delete with the file. The
+ * title line and `## Purpose` (its `###` subheadings included) are not
+ * counted; text under the title, or under any other `#` or `##` heading, is.
+ * A heading with nothing under it loses nothing, as migrate drops an empty
+ * section. Fenced lines are content and never headings.
+ */
+function sectionsLostOnRetire(before, after) {
+    const lost = [];
+    for (const text of [before, after]) {
+        const lines = text.split('\n');
+        const mask = buildCodeFenceMask(lines);
+        let current = { title: 'the text above the title', kept: false, reported: false };
+        for (let i = 0; i < lines.length; i++) {
+            const level = mask[i] ? null : headingLevel(lines[i]);
+            if (level !== null && level <= 2) {
+                const kept = level === 2 && sectionHeaderKey(lines[i]) === 'purpose';
+                current = { title: lines[i].trim(), kept, reported: false };
+                continue;
+            }
+            if (current.kept || current.reported || lines[i].trim() === '')
+                continue;
+            lost.push(current.title);
+            current.reported = true;
+        }
+    }
+    return lost;
+}
 function normalizeBlockRaw(raw) {
     return normalizeDocument(raw).trim();
 }
@@ -473,6 +746,93 @@ function salvageAbsorbedContent(requirementRaw) {
     }
     return '';
 }
+const MAX_LINK_HOPS = 40;
+/**
+ * Where a path really lands: the realpath of its deepest existing ancestor,
+ * with the not-yet-created remainder appended. A target that does not exist yet
+ * (a new capability) still resolves through a linked `specs/` above it.
+ *
+ * `fs.realpath` follows both a POSIX symlink and a Windows junction, so one
+ * check covers both — they differ in how they are created and recorded, not in
+ * where a write through them lands.
+ *
+ * A dangling link (file or directory) makes `realpath` fail exactly like an
+ * absent path, yet `writeFile` and `mkdir` follow it. Appending its name to the
+ * ancestor judged the link's own in-project path, so the first missing segment
+ * is `lstat`ed and, when it is a link, resolution restarts from its target.
+ */
+async function resolveRealPath(target) {
+    let pending = path.resolve(target);
+    // Bounds a chain of dangling links that point at each other; `realpath`
+    // reports a cycle of existing links itself (ELOOP).
+    for (let hop = 0; hop < MAX_LINK_HOPS; hop++) {
+        const rest = [];
+        let existing = pending;
+        let resolved = null;
+        while (resolved === null) {
+            try {
+                resolved = await fs.realpath(existing);
+            }
+            catch (error) {
+                if (!isMissingPathError(error))
+                    throw error;
+                const parent = path.dirname(existing);
+                if (parent === existing)
+                    return pending;
+                rest.unshift(path.basename(existing));
+                existing = parent;
+            }
+        }
+        if (rest.length === 0)
+            return resolved;
+        const firstMissing = path.join(resolved, rest[0]);
+        const isLink = await fs
+            .lstat(firstMissing)
+            .then((stat) => stat.isSymbolicLink())
+            .catch((error) => {
+            if (isMissingPathError(error))
+                return false;
+            throw error;
+        });
+        if (!isLink)
+            return path.join(resolved, ...rest);
+        pending = path.resolve(resolved, await fs.readlink(firstMissing), ...rest.slice(1));
+    }
+    throw new Error(`Too many levels of symbolic links resolving ${target}`);
+}
+function isInsideDirectory(child, parent) {
+    const relative = path.relative(parent, child);
+    if (relative === '')
+        return true;
+    // Only a whole `..` segment steps out; `..shared` is a directory name.
+    const leavesParent = relative === '..' || relative.startsWith(`..${path.sep}`);
+    return !leavesParent && !path.isAbsolute(relative);
+}
+/**
+ * Checks a prepared update against the project boundary before anything is
+ * written. A capability directory (or `tospec/specs` itself) linked outside the
+ * project made archive write — and on retire, `fs.rm` — a file the project does
+ * not own.
+ *
+ * A write is allowed and named, since a shared specs directory is a legitimate
+ * setup; a delete is refused, since removing a file outside the project is
+ * never what archiving a change means. Throws so the caller's all-or-nothing
+ * prepare pass aborts with nothing changed.
+ */
+export async function checkTargetWithinProject(update, projectRoot, retired) {
+    const realTarget = await resolveRealPath(update.target);
+    const realRoot = await resolveRealPath(projectRoot);
+    if (isInsideDirectory(realTarget, realRoot))
+        return null;
+    const specName = path.basename(path.dirname(update.target));
+    if (retired) {
+        throw new Error(`${specName}: removing every requirement would delete tospec/specs/${specName}/spec.md, which resolves to ${realTarget}, outside the project (a symlink or junction). Refusing to delete a file outside the project; remove it there yourself if that is intended.`);
+    }
+    return {
+        code: 'archive_spec_outside_project',
+        message: `${specName} - tospec/specs/${specName}/spec.md resolves to ${realTarget}, outside the project (a symlink or junction); the merge was written there.`,
+    };
+}
 /**
  * Delete an emptied capability's `spec.md` and prune the directories that
  * leaves empty. Pruning stops at `specsRoot` (a project with no capabilities
@@ -525,7 +885,10 @@ export function extractDeltaPurpose(content) {
     for (let i = 0; i < lines.length; i++) {
         if (mask[i])
             continue;
-        if (/^##\s+Purpose\s*$/i.test(lines[i])) {
+        // A closing `#` run is peeled as `parseDeltaSpec` peels it: that parser
+        // reads `## Purpose ##` as Purpose and leaves it off the unmerged list, so
+        // missing it here dropped the text with no notice at all.
+        if (sectionHeaderKey(lines[i]) === 'purpose') {
             start = i + 1;
             break;
         }