@seanmars/tospec 0.23.0 → 0.26.0-beta

package/dist/core/archive.js

@@ -3,19 +3,24 @@ import path from 'path';
 import { getTaskProgressForChange, formatTaskStatus } from '../utils/task-progress.js';
 import { Validator } from './validation/validator.js';
 import { issueSymbol } from './validation/types.js';
-import { validateChangeArtifacts } from '../commands/validate.js';
+import { changeRequiresDeltas, validateChangeArtifacts } from '../commands/validate.js';
 import { isRootSelectionError, resolveRootForCommand, toRootOutput, } from './root-selection.js';
-import { findSpecUpdates, buildUpdatedSpec, writeUpdatedSpec, retireSpec, } from './specs-apply.js';
-import { loadChangeContext, formatChangeStatus } from './artifact-graph/index.js';
+import { findSpecUpdates, MainSpecMergeError, buildUpdatedSpec, writeUpdatedSpec, retireSpec, checkTargetWithinProject, } from './specs-apply.js';
+import { loadChangeContext, formatChangeStatus, findSchemaWarnings, resolveSchema, } from './artifact-graph/index.js';
 import { buildCodeFenceMask, normalizeDocument, stripBom } from './parsers/requirement-text.js';
+import { parseDeltaSpec } from './parsers/requirement-blocks.js';
+import { findSharedRequirements, listDeltaTouches, listSisterChangeDeltas, } from './validation/sister-changes.js';
 import { formatTimestamp } from '../utils/timestamp.js';
-import { findSpecFiles } from '../utils/spec-files.js';
+import { findMisnamedDeltaFiles, findRootDeltaFiles, findRootSpecDelta, findSpecFiles } from '../utils/spec-files.js';
 import { FileSystemUtils, isMissingPathError } from '../utils/file-system.js';
 import { isKebabId, KEBAB_ID_DESCRIPTION } from './id.js';
 import { findTicketPaths, listActiveChangeDirs } from '../utils/item-discovery.js';
-import { METADATA_FILENAME, readChangeMetadata } from '../utils/change-metadata.js';
-import { emitSuccess, emitFailureStatus } from '../commands/shared-output.js';
+import { findLayoutPathNotDirectory, LayoutPathNotDirectoryError } from './project-layout.js';
+import { isReservedChangeName, RESERVED_CHANGE_NAME_REASON } from '../utils/change-utils.js';
+import { METADATA_FILENAME, readChangeMetadata, resolveSchemaForChange } from '../utils/change-metadata.js';
+import { emitSuccess, emitFailureStatus, formatLabeled, indentContinuation, } from '../commands/shared-output.js';
 import { withFileLock } from '../utils/file-lock.js';
+import { isInteractive } from '../utils/interactive.js';
 /** Alias of `formatTimestamp`: agents must never assemble archive stamps by hand. */
 export const formatArchiveStamp = formatTimestamp;
 /** `Conclusion: PASS` / `Conclusion: FAIL`, with an optional `(reason)` note. */
@@ -82,6 +87,11 @@ function toArchiveDiagnostic(error) {
     if (isRootSelectionError(error)) {
         return error.diagnostic;
     }
+    // Raised by the change listing, which every other command reports by its own
+    // code; folding it into archive_error would make archive the one exception.
+    if (error instanceof LayoutPathNotDirectoryError) {
+        return error.diagnostic;
+    }
     return {
         severity: 'error',
         code: 'archive_error',
@@ -106,6 +116,52 @@ export class MoveSourceNotRemovedError extends Error {
         this.name = 'MoveSourceNotRemovedError';
     }
 }
+/**
+ * A failure after archive changed something on disk. The fix names the manual
+ * steps left, and says not to rerun: the merge would refuse the change's ADDED
+ * requirements as already present, and a moved change is no longer found.
+ */
+function partiallyAppliedError(error, state) {
+    const rel = (target) => FileSystemUtils.toPosixPath(path.relative(state.projectRoot, target));
+    const changeRel = rel(state.changeDir);
+    const archiveRel = rel(state.archivePath);
+    const unwritten = state.unwrittenCapabilities ?? [];
+    const done = [];
+    if (state.mergedCapabilities.length > 0) {
+        done.push(`merged the specs of ${state.mergedCapabilities.join(', ')} into tospec/specs/`);
+    }
+    if (state.changeMoved)
+        done.push(`moved the change to ${archiveRel}`);
+    const failed = unwritten.length > 0
+        ? `writing the specs of ${unwritten.join(', ')}`
+        : state.changeMoved
+            ? 'archiving the ticket in tospec/tickets/archive/'
+            : `moving the change to ${archiveRel}`;
+    const cause = error instanceof Error ? error.message : String(error);
+    // "Still in": the ticket move can fail after the file moved, while its
+    // change link is rewritten, and the step must not send the user to a file
+    // that is no longer there.
+    const ticketStep = `move the change's ticket, if it has one still in tospec/tickets/, to tospec/tickets/archive/ and point its change link at ${path.basename(state.archivePath)}`;
+    let fix;
+    if (unwritten.length > 0) {
+        fix =
+            `Do not rerun archive: the merge would refuse the requirements it already added. ` +
+                `Merge the change's deltas for ${unwritten.join(', ')} into tospec/specs/ by hand, move ${changeRel} to ${archiveRel}, then ${ticketStep}.`;
+    }
+    else if (state.changeMoved) {
+        fix = `Do not rerun archive: the change is already archived. Finish by hand: ${ticketStep}.`;
+    }
+    else if (error instanceof MoveSourceNotRemovedError) {
+        fix = `Do not rerun archive. ${archiveRel} is complete: delete what is left of ${changeRel}, then ${ticketStep}.`;
+    }
+    else {
+        const clearCopy = state.partialCopyLeft ? ` (delete the partial copy at ${archiveRel} first)` : '';
+        fix =
+            `Do not rerun archive: the merge would refuse the requirements it already added. ` +
+                `Move ${changeRel} to ${archiveRel} by hand${clearCopy}, then ${ticketStep}.`;
+    }
+    return new ArchiveBlockedError('archive_partially_applied', `Archive stopped partway. Done: ${done.join('; ')}. Failed while ${failed}: ${cause}`, fix);
+}
 /**
  * On Windows fs.rename() often fails with EPERM when the directory is non-empty
  * or another process has it open (IDE, watcher, antivirus), so EPERM/EXDEV fall
@@ -118,9 +174,23 @@ export async function moveDirectory(src, dest) {
     catch (err) {
         const code = err?.code;
         if (code === 'EPERM' || code === 'EXDEV') {
-            // verbatimSymlinks: otherwise Node rewrites links to absolute paths under
-            // `src`, and removing `src` below leaves the copies dangling.
-            await fs.cp(src, dest, { recursive: true, verbatimSymlinks: true });
+            // Only a destination this copy created is rolled back: one already there
+            // (rename onto it fails with EPERM on Windows) holds someone else's files.
+            const destExisted = await fs.lstat(dest).then(() => true, () => false);
+            try {
+                // verbatimSymlinks: otherwise Node rewrites links to absolute paths under
+                // `src`, and removing `src` below leaves the copies dangling.
+                await fs.cp(src, dest, { recursive: true, verbatimSymlinks: true });
+            }
+            catch (cpError) {
+                // A copy that dies partway (a file held open elsewhere) leaves half the
+                // source at `dest`, which reads as moved. `src` is still whole, so
+                // removing the copy leaves the plain "not moved" state. rm does not
+                // follow links, so a linked `src` copied as a link removes only that link.
+                if (!destExisted)
+                    await fs.rm(dest, { recursive: true, force: true }).catch(() => { });
+                throw cpError;
+            }
             // The same open handle that made rename fail with EPERM can fail this
             // removal partway, after some files are already gone.
             try {
@@ -164,21 +234,34 @@ async function appendDecisionLinks(ticketFile, archivedChangeDir, projectRoot) {
     await fs.appendFile(ticketFile, block);
 }
 /**
- * Repoints an archived ticket's `ref:` frontmatter at the change's new path,
- * keeping the referenced filename. No-op when the line is absent.
+ * Points a ticket's `ref:` line at the archived change, keeping the referenced
+ * filename. Returns the text unchanged when no line matches.
  *
  * Line endings survive untouched because the pattern excludes line terminators
  * (`[^/\r\n]+`, no `s` flag), so `replace` only rewrites within a line. Do not
  * "simplify" this by splitting and rejoining the file.
+ *
+ * `$2` runs straight to `$`: a `[ \t]*` between them split a blank run with
+ * `[^/\r\n]+` every way, and a filename holding 80k blanks took 13 s. That
+ * `[ \t]*` never matched anything, since the greedy capture reached `$` first,
+ * so trailing blanks stay in `$2` as before. `(?![ \t])` keeps `.*` from
+ * re-splitting the blanks after `ref:` (2 s on a line with no `/`): a shorter
+ * `$1` only hands `.*` blanks, never another `/`, so it could not match anyway.
+ */
+export function retargetRefLine(content, archiveName) {
+    return content.replace(/^(ref:[ \t]*)(?![ \t]).*\/([^/\r\n]+)$/m, `$1tospec/changes/archive/${archiveName}/$2`);
+}
+/**
+ * Repoints an archived ticket's `ref:` frontmatter at the change's new path,
+ * keeping the referenced filename. No-op when the line is absent.
  */
 async function retargetTicketRef(ticketFile, archiveName) {
-    const raw = await fs.readFile(ticketFile, 'utf-8');
-    // Compared against `raw`, not the stripped text, so a ticket whose only
-    // difference is a BOM still gets written back without one: this rewrite is
-    // where tospec re-emits the file, and what it emits is UTF-8 without a BOM.
-    const content = stripBom(raw);
-    const updated = content.replace(/^(ref:[ \t]*).*\/([^/\r\n]+)[ \t]*$/m, `$1tospec/changes/archive/${archiveName}/$2`);
-    if (updated !== raw) {
+    // A rewrite emits UTF-8 without a BOM, as every tospec write does. Compared
+    // against the stripped text, as `writeTicketStub` does, so a ticket with no
+    // `ref:` to retarget is not rewritten just to drop its BOM.
+    const content = stripBom(await fs.readFile(ticketFile, 'utf-8'));
+    const updated = retargetRefLine(content, archiveName);
+    if (updated !== content) {
         await fs.writeFile(ticketFile, updated);
     }
 }
@@ -267,6 +350,12 @@ export class ArchiveCommand {
         if (opts.json) {
             throw new ArchiveBlockedError(opts.code, opts.message, opts.fix);
         }
+        // A prompt with no terminal reads EOF as Ctrl-C, so a CI run without
+        // `--yes` reported a cancellation (exit 130) instead of what it lacked.
+        // Same test as `config reset`, so the two refuse alike.
+        if (!isInteractive()) {
+            throw new ArchiveBlockedError(opts.code, `${opts.message} Cannot confirm it: no interactive terminal.`, opts.fix);
+        }
         const { confirm } = await import('@inquirer/prompts');
         const proceed = await confirm({ message: opts.prompt, default: false });
         if (!proceed) {
@@ -299,6 +388,19 @@ export class ArchiveCommand {
             return [];
         }
     }
+    /**
+     * Same rule as `findMissingRequiredArtifacts`: a schema that does not resolve
+     * yields nothing, because reporting it is validation's job, not this one's.
+     */
+    findChangeSchemaWarnings(projectRoot, changeDir) {
+        try {
+            const schemaName = resolveSchemaForChange(changeDir, undefined, projectRoot);
+            return findSchemaWarnings(resolveSchema(schemaName, projectRoot));
+        }
+        catch {
+            return [];
+        }
+    }
     /**
      * Shared archive flow. Human mode prompts and returns null on cancellation;
      * JSON mode keeps stdout clean and throws from every blocked path.
@@ -326,9 +428,10 @@ export class ArchiveCommand {
                 throw new ArchiveBlockedError('archive_change_name_required', 'A change name is required: archive --json is non-interactive.', 'tospec archive <change-name> --json');
             }
             // Without a terminal the picker cannot be answered: it would paint its
-            // menu into the pipe and then read EOF as "nothing chosen".
-            if (!process.stdin.isTTY) {
-                throw new ArchiveBlockedError('archive_change_name_required', 'A change name is required when stdin is not a terminal.', 'tospec archive <change-name>');
+            // menu into the pipe and then read EOF as "nothing chosen". `CI` counts
+            // as no terminal too, as it does for the confirmation prompts below.
+            if (!isInteractive()) {
+                throw new ArchiveBlockedError('archive_change_name_required', 'A change name is required: no interactive terminal to pick one.', 'tospec archive <change-name>');
             }
             const selectedChange = await this.selectChange(changesDir, root.path);
             if (!selectedChange) {
@@ -345,6 +448,12 @@ export class ArchiveCommand {
         if (nameFromArgument && !isKebabId(changeName)) {
             throw new ArchiveBlockedError('archive_change_name_invalid', `Change name '${changeName}' is not a valid change id — it ${KEBAB_ID_DESCRIPTION}.`);
         }
+        // Before the stat, which the archive directory passes: every gate then let
+        // it through, and only the final rename failed, as EINVAL, moving the
+        // directory into its own subdirectory.
+        if (isReservedChangeName(changeName)) {
+            throw new ArchiveBlockedError('archive_change_name_invalid', `${RESERVED_CHANGE_NAME_REASON}, and is not itself a change.`);
+        }
         const changeDir = path.join(changesDir, changeName);
         // Only a missing path may answer "not found" — a bare catch here rewrote
         // genuine IO failures (EACCES, EIO) as a nonexistent change.
@@ -359,6 +468,17 @@ export class ArchiveCommand {
                 ? `Change '${changeName}' not found. Available changes: ${available.join(', ')}`
                 : `Change '${changeName}' not found. No active changes exist in this root.`);
         }
+        // Read before the move: `fs.rename` moves the link itself, so the archived
+        // entry is the same link and its content never lands in the archive.
+        const linkedTo = (await fs.lstat(changeDir)).isSymbolicLink() ? await fs.realpath(changeDir) : null;
+        // Every directory the move and the ticket move write into, checked before
+        // the first write: a file at one of them otherwise failed only after the
+        // specs merge, as a partly applied archive.
+        for (const dir of [archiveDir, path.join(root.path, 'tospec', 'tickets', 'archive')]) {
+            const occupied = findLayoutPathNotDirectory(root.path, dir);
+            if (occupied)
+                throw occupied;
+        }
         // Reserve the archive name before anything is written. Checking after the
         // merge left specs applied with the change still in tospec/changes/, so a
         // retry re-applied the same deltas. The stamp is computed once and reused
@@ -404,16 +524,34 @@ export class ArchiveCommand {
         const skipValidation = options.validate === false || options.noValidate === true;
         // The exact pipeline `tospec validate` runs, minus the archive preflight —
         // that is a dry run of the merge performed below, which raises
-        // archive_spec_update_failed itself.
+        // archive_spec_update_failed itself — and minus the sister-change check,
+        // which would advise archiving the other change first; the scan after the
+        // merge below names the other change in the direction this run decided.
         if (!skipValidation) {
             const report = await validateChangeArtifacts(root.path, changeDir, {
                 archivePreflight: false,
+                sisterChanges: false,
             });
             if (!json && report.issues.length > 0) {
                 console.error(`\nValidation issues for change '${changeName}':`);
                 for (const issue of report.issues) {
                     const symbol = issueSymbol(issue.level);
-                    console.error(`  ${symbol} ${issue.path}: ${issue.message}`);
+                    console.error(`  ${symbol} ${issue.path}: ${indentContinuation(issue.message, '    ')}`);
+                }
+            }
+            // Human mode printed every finding above while --json printed none, so
+            // an agent archiving with --json never saw a WARNING (a dropped bullet,
+            // a missing SHALL) that a user at a terminal saw. ERRORs stay out:
+            // they fail the gate below, whose fix sends the reader to validate.
+            if (json) {
+                for (const issue of report.issues) {
+                    if (issue.level !== 'WARNING')
+                        continue;
+                    jsonWarnings.push({
+                        severity: 'warning',
+                        code: 'archive_validation_warning',
+                        message: `${issue.path}: ${issue.message}`,
+                    });
                 }
             }
             if (!report.valid) {
@@ -422,15 +560,17 @@ export class ArchiveCommand {
                 // not at --no-validate.
                 const noDeltas = report.issues.some((i) => /at least one delta/i.test(i.message));
                 const deltaFix = noDeltas
-                    ? ` If this change genuinely has no behavioral effect, declare it once by setting \`skip_specs: true\` in the change's ${METADATA_FILENAME} — do not invent a requirement to satisfy validation.`
+                    ? ` If the user confirms this change needs no delta spec, declare it once by setting \`skip_specs: true\` in the change's ${METADATA_FILENAME} — do not invent a requirement to satisfy validation.`
                     : '';
                 if (json) {
                     throw new ArchiveBlockedError('archive_validation_failed', `Validation failed for change '${changeName}'.`, `Run ${`tospec validate ${changeName}`} for details, fix the errors, or rerun with --no-validate.${deltaFix}`);
                 }
-                console.error('\nValidation failed. Please fix the errors before archiving.');
+                // A line under `Error:` that is not `Fix:` is indented, here and at the
+                // merge aborts below: a bare line would read as a second message.
+                console.error('\nError: Validation failed. Please fix the errors before archiving.');
                 if (deltaFix)
                     console.error(`Fix:${deltaFix}`);
-                console.error('To skip validation (not recommended), use --no-validate flag.');
+                console.error('  To skip validation (not recommended), use --no-validate flag.');
                 process.exitCode = 1;
                 return null;
             }
@@ -444,9 +584,11 @@ export class ArchiveCommand {
                 // when `--yes` overrides the gate. Remedies belong in `fix`, which an
                 // overridden gate drops.
                 message: `Validation is disabled for change '${changeName}' (--no-validate).`,
-                fix: 'tospec archive <change-name> --json --no-validate --yes',
-                prompt: '⚠️  WARNING: Skipping validation may archive invalid specs. Continue? (y/N)',
-                warning: '\n⚠️  WARNING: Skipping validation may archive invalid specs.',
+                // The human-mode fix also reaches a run with no terminal; `--json`
+                // there would swap the reader's prose output for a document.
+                fix: `tospec archive ${changeName}${json ? ' --json' : ''} --no-validate --yes`,
+                prompt: 'Warning: Skipping validation may archive invalid specs. Continue?',
+                warning: '\nWarning: Skipping validation may archive invalid specs.',
                 warnings: jsonWarnings,
             });
             if (!proceed)
@@ -480,6 +622,19 @@ export class ArchiveCommand {
             if (!proceed)
                 return null;
         }
+        // Ahead of the task gate: an unmatched `apply.tracks` sends progress to
+        // tasks.md, so the gate reports "no tracked task checkboxes" and asks for a
+        // file while the schema's real one sits in the change. The gate's decision
+        // stands; this is what makes its message make sense.
+        for (const warning of this.findChangeSchemaWarnings(root.path, changeDir)) {
+            if (json) {
+                jsonWarnings.push({ severity: 'warning', ...warning });
+            }
+            else {
+                console.log(`Warning: ${warning.message}`);
+                console.log(`Fix: ${warning.fix}`);
+            }
+        }
         // Pass the resolved root rather than re-deriving it from changesDir: the
         // '..','..' hop silently encodes the tospec/changes layout.
         const progress = await getTaskProgressForChange(changesDir, changeName, root.path);
@@ -517,18 +672,91 @@ export class ArchiveCommand {
                 return null;
         }
         let specsUpdated = false;
+        let mergedCapabilities = [];
         let totals = { added: 0, modified: 0, removed: 0, renamed: 0, retired: 0 };
+        const specsDir = path.join(changeDir, 'specs');
+        const specUpdates = await findSpecUpdates(changeDir, mainSpecsDir);
+        // Where the merge-empty backstop below runs, it refuses and names every
+        // spec.md the merge cannot read. Everywhere else the merge drops those
+        // files, so the warnings below name them; keyed on the one condition, no
+        // file is both a warning and that error.
+        const backstopRuns = !options.skipSpecs && specUpdates.length === 0;
+        // Both outcomes, because the merge below can still stop the archive: a
+        // stopped one leaves the change in place, while a completed one has moved
+        // it to archive/, where it cannot be archived again.
+        const unmergedFix = 'To apply them: if this archive stopped, move each to specs/<capability>/spec.md and rerun; if it completed, write them as specs/<capability>/spec.md in a new change, or merge them into the main specs by hand.';
+        // The same list validate warns about, at the same level: a root `.md` with
+        // delta headers is a delta the merge will not read. Not added to the
+        // backstop below, which refuses — validate only warns here, and archive
+        // must not block what validate passes.
+        //
+        // Ahead of the --skip-specs branch, under one code for both: the file goes
+        // unmerged with or without the flag, so a consumer keyed on the code must
+        // not need to know which was passed. Not folded into
+        // archive_deltas_discarded, which lists the capabilities the flag dropped;
+        // findSpecUpdates never returns a root file, so no file is named twice.
+        //
+        // specs/spec.md joins the list only where the backstop does not run: under
+        // --skip-specs, or beside a capability delta, which gives the merge
+        // something to read. Validate's ERROR refuses a spec.md with a delta header
+        // first, so in practice this is --no-validate. Not added to that backstop
+        // instead: each flag is an explicit instruction, and the --skip-specs
+        // branch only warns about the deltas it drops.
+        const rootDeltas = await findRootDeltaFiles(specsDir, { includeRootSpec: !backstopRuns });
+        if (rootDeltas.length > 0) {
+            const listed = rootDeltas.map((file) => `specs/${path.basename(file)}`).join(', ');
+            const message = `${listed} hold(s) delta sections but sit at the specs/ root, so they are not merged into the main specs.`;
+            if (json) {
+                jsonWarnings.push({ severity: 'warning', code: 'archive_root_delta_ignored', message, fix: unmergedFix });
+            }
+            else {
+                console.log(`Warning: ${message}`);
+                console.log(`Fix: ${unmergedFix}`);
+            }
+        }
+        // The delta files below the root that the merge does not read: a spec.md
+        // deeper than specs/<capability>/ or in a dot folder, and a misnamed file
+        // (specs/<capability>/notes.md, SPEC.md) with a delta header. They are the
+        // files the backstop lists when nothing merges; beside a capability delta
+        // or under --skip-specs they were dropped with nothing naming them.
+        // Validate refuses each of them first, so in practice this is
+        // --no-validate.
+        //
+        // A code of its own rather than archive_root_delta_ignored, whose name and
+        // message say "root", so a consumer reads the two codes as two different
+        // checks. A spec.md is picked by basename, as the backstop and validate's
+        // nested ERROR pick it. A misnamed file needs a delta header, the root's
+        // rule: without one it is notes.
+        if (!backstopRuns) {
+            const merged = new Set(specUpdates.map((update) => update.source));
+            const misplaced = [
+                ...(await findSpecFiles(specsDir)).filter((file) => path.dirname(file) !== specsDir && !merged.has(file)),
+                ...(await findMisnamedDeltaFiles(specsDir)),
+            ].sort();
+            if (misplaced.length > 0) {
+                const listed = misplaced
+                    .map((file) => `specs/${FileSystemUtils.toPosixPath(path.relative(specsDir, file))}`)
+                    .join(', ');
+                const message = `${misplaced.length} delta spec file(s) are not merged into the main specs, because they do not sit at specs/<capability>/spec.md (one folder deep, not a dot folder): ${listed}.`;
+                if (json) {
+                    jsonWarnings.push({ severity: 'warning', code: 'archive_misplaced_delta_ignored', message, fix: unmergedFix });
+                }
+                else {
+                    console.log(`Warning: ${message}`);
+                    console.log(`Fix: ${unmergedFix}`);
+                }
+            }
+        }
         if (options.skipSpecs) {
             // `--skip-specs` is for changes with no deltas, so pointing it at one that
             // has them is user error — and archiving in silence made it unrecoverable.
             // A warning, not a block, because the flag is an explicit instruction.
-            const discarded = await findSpecUpdates(changeDir, mainSpecsDir);
-            if (discarded.length > 0) {
+            if (specUpdates.length > 0) {
                 // source is <changeDir>/specs/<capability>/spec.md.
-                const listed = discarded
+                const listed = specUpdates
                     .map((update) => path.basename(path.dirname(update.source)))
                     .join(', ');
-                const message = `--skip-specs discarded ${discarded.length} delta spec(s); these capabilities were not merged into the main specs: ${listed}.`;
+                const message = `--skip-specs discarded ${specUpdates.length} delta spec(s); these capabilities were not merged into the main specs: ${listed}.`;
                 if (json) {
                     jsonWarnings.push({ severity: 'warning', code: 'archive_deltas_discarded', message });
                 }
@@ -541,16 +769,30 @@ export class ArchiveCommand {
             }
         }
         else {
-            const specUpdates = await findSpecUpdates(changeDir, mainSpecsDir);
             if (specUpdates.length === 0) {
                 // findSpecUpdates only reads specs/<capability>/spec.md, and validation
                 // rejects anything else — so delta files here mean --no-validate, and
                 // reporting success would drop their requirements silently. Matches
-                // spec.md only: a stray NOTES.md is not a delta.
-                const orphans = await findSpecFiles(path.join(changeDir, 'specs'));
+                // spec.md below the root, and another .md below the root only with a
+                // delta header: a stray NOTES.md is not a delta.
+                //
+                // specs/spec.md is picked by validate's own rule, under the name it has
+                // on disk: on a case-insensitive file system a lone SPEC.md is that
+                // ERROR's file. Without a delta header it counts only where the change
+                // must carry a delta; elsewhere validate leaves it as notes, and
+                // counting it anyway refused a change validate had passed while the
+                // Fix: sent the user back to validate.
+                const rootSpec = await findRootSpecDelta(specsDir, {
+                    requireDelta: await changeRequiresDeltas(root.path, changeDir),
+                });
+                const orphans = [
+                    ...(await findSpecFiles(specsDir)).filter((file) => path.dirname(file) !== specsDir),
+                    ...(rootSpec === undefined ? [] : [rootSpec]),
+                    ...(await findMisnamedDeltaFiles(specsDir)),
+                ].sort();
                 if (orphans.length > 0) {
                     const listed = orphans
-                        .map((file) => FileSystemUtils.toPosixPath(path.relative(path.join(changeDir, 'specs'), file)))
+                        .map((file) => FileSystemUtils.toPosixPath(path.relative(specsDir, file)))
                         .join(', ');
                     throw new ArchiveBlockedError('archive_spec_merge_empty', `Found ${orphans.length} delta spec file(s) that cannot be merged, because none sits at specs/<capability>/spec.md: ${listed}.`, `Run ${`tospec validate ${changeName}`} for the exact fix, or move each file to specs/<capability>/spec.md.`);
                 }
@@ -573,6 +815,12 @@ export class ArchiveCommand {
                 // gates, so a caller who only wanted the merge had to disarm every
                 // gate to get it.
                 if (!options.yes && !json) {
+                    // Refuse rather than merge by default as JSON mode does: a human run
+                    // was promised this question. Every gate has passed by this point,
+                    // so a rerun with `--yes` overrides nothing but this prompt.
+                    if (!isInteractive()) {
+                        throw new ArchiveBlockedError('archive_confirmation_required', `Cannot confirm the spec updates for change '${changeName}': no interactive terminal.`, 'Rerun with --yes to merge them.');
+                    }
                     const { confirm } = await import('@inquirer/prompts');
                     shouldUpdateSpecs = await confirm({
                         message: 'Proceed with spec updates?',
@@ -602,15 +850,28 @@ export class ArchiveCommand {
                             for (const update of specUpdates) {
                                 const built = await buildUpdatedSpec(update, changeName, { silent: true });
                                 mergeNotices.push(...built.notices);
-                                prepared.push({ update, rebuilt: built.rebuilt, crlf: built.crlf, retired: built.retired, counts: built.counts });
+                                // Inside the prepare pass, so a refused delete outside the
+                                // project aborts before any spec is written.
+                                const outside = await checkTargetWithinProject(update, root.path, built.retired);
+                                if (outside)
+                                    mergeNotices.push(outside);
+                                prepared.push({ update, rebuilt: built.rebuilt, crlf: built.crlf, retired: built.retired, counts: built.counts, original: built.original });
                             }
                         }
                         catch (err) {
+                            const message = String(err.message || err);
+                            // Each merge error is either the delta's or the main spec's; naming
+                            // the delta for both sent the user to edit a file that was fine.
+                            const fix = err instanceof MainSpecMergeError
+                                ? `Fix ${err.specPath} and rerun. No files were changed.`
+                                : 'Fix the change delta specs and rerun. No files were changed.';
                             if (json) {
-                                throw new ArchiveBlockedError('archive_spec_update_failed', String(err.message || err), 'Fix the change delta specs and rerun. No files were changed.');
+                                throw new ArchiveBlockedError('archive_spec_update_failed', message, fix);
                             }
-                            console.error(String(err.message || err));
-                            console.error('Aborted. No files were changed.');
+                            // The diagnostic --json carries, as emitFailure would print it. Its
+                            // fix already says no files were changed, so no `Aborted.` line.
+                            console.error(formatLabeled('Error', message));
+                            console.error(formatLabeled('Fix', fix));
                             process.exitCode = 1;
                             return writeTotalsSentinel;
                         }
@@ -624,36 +885,77 @@ export class ArchiveCommand {
                                 if (p.retired)
                                     continue;
                                 const specName = path.basename(path.dirname(p.update.target));
-                                const report = await new Validator().validateSpecContent(specName, p.rebuilt);
-                                if (!report.valid) {
+                                const failure = await new Validator().diagnoseRebuiltSpec(specName, p.rebuilt, p.original);
+                                if (failure !== null) {
+                                    // The same attribution `tospec validate` uses for its preflight
+                                    // warning: a main spec that already fails is the file to edit,
+                                    // and sending the user to the delta sent them to a file that
+                                    // was fine.
+                                    const fix = failure.source === 'main'
+                                        ? `Fix ${failure.specPath} and rerun. No files were changed.`
+                                        : `Run ${`tospec validate ${specName}`} after fixing the change deltas.`;
                                     if (json) {
-                                        throw new ArchiveBlockedError('archive_spec_validation_failed', `Rebuilt spec for '${specName}' failed validation. No files were changed.`, `Run ${`tospec validate ${specName}`} after fixing the change deltas.`);
+                                        // The findings ride in the message, as the merge's own
+                                        // refusals carry theirs: a separate field would widen the
+                                        // status-entry contract every agent parses.
+                                        const findings = failure.issues
+                                            .filter((i) => i.level === 'ERROR')
+                                            .map((i) => `  ${i.path}: ${indentContinuation(i.message, '    ')}`);
+                                        const lead = failure.source === 'main'
+                                            ? `Main spec ${failure.specPath} fails validation, so the spec rebuilt from it for '${specName}' would too. No files were changed.`
+                                            : `Rebuilt spec for '${specName}' failed validation. No files were changed.`;
+                                        throw new ArchiveBlockedError('archive_spec_validation_failed', [lead, ...findings].join('\n'), fix);
                                     }
-                                    console.error(`\nValidation errors in rebuilt spec for ${specName} (will not write changes):`);
-                                    for (const issue of report.issues) {
+                                    console.error(failure.source === 'main'
+                                        ? `\nError: Main spec ${failure.specPath} fails validation, so the rebuilt spec for ${specName} would too (will not write changes):`
+                                        : `\nError: Validation errors in rebuilt spec for ${specName} (will not write changes):`);
+                                    // A message's later lines (the scenario example some carry) sit
+                                    // under its text, not at the margin where they read as new lines.
+                                    for (const issue of failure.issues) {
                                         if (issue.level === 'ERROR')
-                                            console.error(`  ✗ ${issue.message}`);
+                                            console.error(`  ✗ ${issue.path}: ${indentContinuation(issue.message, '    ')}`);
                                         else if (issue.level === 'WARNING')
-                                            console.error(`  ⚠ ${issue.message}`);
+                                            console.error(`  ⚠ ${issue.path}: ${indentContinuation(issue.message, '    ')}`);
                                     }
-                                    console.error('Aborted. No files were changed.');
+                                    console.error('  Aborted. No files were changed.');
+                                    console.error(formatLabeled('Fix', fix));
                                     process.exitCode = 1;
                                     return writeTotalsSentinel;
                                 }
                             }
                         }
                         const writeTotals = { added: 0, modified: 0, removed: 0, renamed: 0, retired: 0 };
-                        for (const p of prepared) {
-                            if (p.retired) {
-                                await retireSpec(p.update, mainSpecsDir, { silent: json });
-                                writeTotals.retired += 1;
+                        const capabilityOf = (p) => path.basename(path.dirname(p.update.target));
+                        for (let i = 0; i < prepared.length; i++) {
+                            const p = prepared[i];
+                            // A write failing after an earlier one succeeded leaves the project
+                            // half-merged, which a rerun cannot finish: the specs already
+                            // written refuse the change's ADDED requirements.
+                            try {
+                                if (p.retired) {
+                                    await retireSpec(p.update, mainSpecsDir, { silent: json });
+                                }
+                                else {
+                                    await writeUpdatedSpec(p.update, p.rebuilt, p.counts, {
+                                        silent: json,
+                                        crlf: p.crlf,
+                                    });
+                                }
                             }
-                            else {
-                                await writeUpdatedSpec(p.update, p.rebuilt, p.counts, {
-                                    silent: json,
-                                    crlf: p.crlf,
+                            catch (error) {
+                                if (i === 0)
+                                    throw error;
+                                throw partiallyAppliedError(error, {
+                                    projectRoot: root.path,
+                                    changeDir,
+                                    archivePath,
+                                    mergedCapabilities: prepared.slice(0, i).map(capabilityOf),
+                                    unwrittenCapabilities: prepared.slice(i).map(capabilityOf),
+                                    changeMoved: false,
                                 });
                             }
+                            if (p.retired)
+                                writeTotals.retired += 1;
                             writeTotals.added += p.counts.added;
                             writeTotals.modified += p.counts.modified;
                             writeTotals.removed += p.counts.removed;
@@ -675,22 +977,147 @@ export class ArchiveCommand {
                                 (writeTotals.retired ? `, retired ${writeTotals.retired}` : ''));
                             console.log('Specs updated successfully.');
                         }
-                        return { totals: writeTotals };
+                        return {
+                            totals: writeTotals,
+                            capabilities: prepared.map(capabilityOf),
+                        };
                     }, { operation: `archive ${changeName}` });
                     // The human-mode failure paths above already printed and set the exit code.
                     if (locked === writeTotalsSentinel)
                         return null;
                     specsUpdated = true;
                     totals = locked.totals;
+                    mergedCapabilities = locked.capabilities;
+                    // Only once the merge wrote: a skipped or refused merge replaced no
+                    // text another change could have been written against. Warned, not
+                    // refused, since nothing about this change is wrong.
+                    for (const warning of await this.findStaleSisterRewrites(changesDir, changeName, specUpdates)) {
+                        if (json) {
+                            jsonWarnings.push(warning);
+                        }
+                        else {
+                            console.error(`Warning: ${warning.message}`);
+                            console.error(`Fix: ${warning.fix}`);
+                        }
+                    }
                 }
             }
         }
         // Name and collision were settled at the reservation above.
-        await fs.mkdir(archiveDir, { recursive: true });
-        await moveDirectory(changeDir, archivePath);
-        // The ticket lives in the global tospec/tickets/ index, outside the change
-        // dir, so it moves alongside to keep the active index to in-flight changes.
-        const ticketPaths = await findTicketPaths(root.path, changeName);
+        // From the spec write on, a failure leaves the project half-archived, and a
+        // rerun cannot finish it: the change's ADDED requirements already exist in
+        // the main specs, so the merge refuses them. Reported under its own code
+        // with the manual remaining steps, because `archive_error` with
+        // `archive: null` reads as "nothing changed".
+        let changeMoved = false;
+        try {
+            await fs.mkdir(archiveDir, { recursive: true });
+            await moveDirectory(changeDir, archivePath);
+            changeMoved = true;
+            await this.archiveTicket(root.path, changeName, archiveName, archivePath, json, jsonWarnings);
+        }
+        catch (error) {
+            if (!specsUpdated && !changeMoved)
+                throw error;
+            // moveDirectory removes its partial copy, but that removal can fail too;
+            // the fix names the leftover only when one is actually on disk.
+            const partialCopyLeft = !changeMoved &&
+                (await fs.lstat(archivePath).then(() => true, () => false));
+            throw partiallyAppliedError(error, {
+                projectRoot: root.path,
+                changeDir,
+                archivePath,
+                mergedCapabilities,
+                changeMoved,
+                partialCopyLeft,
+            });
+        }
+        // Warned, not refused: list, status and validate all work on a linked
+        // change, so archive finishing it is consistent; what it cannot do is bring
+        // the content into the project, and that is the reader's to decide.
+        if (linkedTo !== null) {
+            const warning = {
+                code: 'archive_change_linked',
+                message: `Change '${changeName}' is a symlink or junction to ${linkedTo}. Archive moved the link, so tospec/changes/archive/${archiveName} still points there: its content stays outside tospec/changes/archive/ and git does not track it there.`,
+                fix: `To keep the archived change in the project, replace tospec/changes/archive/${archiveName} with a copy of ${linkedTo}.`,
+            };
+            if (json) {
+                jsonWarnings.push({ severity: 'warning', ...warning });
+            }
+            else {
+                console.log(`Warning: ${warning.message}`);
+                console.log(`Fix: ${warning.fix}`);
+            }
+        }
+        if (!json) {
+            console.log(`Change '${changeName}' archived as '${archiveName}'.`);
+        }
+        return {
+            change: changeName,
+            archivedAs: archiveName,
+            path: archivePath,
+            specsUpdated,
+            totals,
+        };
+    }
+    /**
+     * One warning per MODIFIED / REMOVED / RENAMED in another in-progress change
+     * on a requirement this change's merge just wrote. That delta restates the
+     * text from before this archive, often copied from this change's own delta,
+     * and sync may have rewritten the requirement since; archived as is, it
+     * replaces the block and the edit is lost with nothing reporting it.
+     *
+     * Best effort, like the sister read it builds on: an unreadable delta is
+     * skipped, as the archive it warns about has already succeeded.
+     */
+    async findStaleSisterRewrites(changesDir, changeName, specUpdates) {
+        const sisters = await listSisterChangeDeltas(changesDir, changeName);
+        if (sisters.length === 0)
+            return [];
+        const warnings = [];
+        for (const update of specUpdates) {
+            // The delta's folder name, as the sister deltas spell theirs; the target
+            // may carry the on-disk spelling of an existing capability instead.
+            const capability = path.basename(path.dirname(update.source));
+            let touches;
+            try {
+                touches = listDeltaTouches(parseDeltaSpec(await fs.readFile(update.source, 'utf-8')), [
+                    'ADDED',
+                    'MODIFIED',
+                    'REMOVED',
+                    'RENAMED',
+                ]);
+            }
+            catch {
+                continue;
+            }
+            for (const { change, sister } of findSharedRequirements(capability, touches, sisters, [
+                'MODIFIED',
+                'REMOVED',
+                'RENAMED',
+            ])) {
+                warnings.push({
+                    severity: 'warning',
+                    code: 'archive_sister_change_stale',
+                    target: change,
+                    // Only what the match proves: both deltas touch the requirement. The
+                    // sister's base text is unknown here — with a third change archived in
+                    // between, it predates the text this archive replaced — so the message
+                    // claims no base.
+                    message: `The ${sister.operation} "${sister.requirement}" in change '${change}' (specs/${capability}/spec.md) rewrites a requirement this archive just changed in tospec/specs/${capability}/spec.md; archived as is, it would replace this change's edit with its own text.`,
+                    fix: `Rewrite that delta in '${change}' against the updated tospec/specs/${capability}/spec.md before archiving '${change}'.`,
+                });
+            }
+        }
+        return warnings;
+    }
+    /**
+     * Moves the change's ticket out of the active index. The ticket lives in the
+     * global tospec/tickets/ index, outside the change dir, so it moves alongside
+     * to keep the active index to in-flight changes.
+     */
+    async archiveTicket(projectRoot, changeName, archiveName, archivePath, json, jsonWarnings) {
+        const ticketPaths = await findTicketPaths(projectRoot, changeName);
         // Newest wins: a second ticket means the change was recreated, so the later
         // stamp describes the change being archived. The rest are reported, not
         // cleaned up — archive must not silently remove a record.
@@ -709,7 +1136,7 @@ export class ArchiveCommand {
             }
         }
         if (ticketPath) {
-            const ticketArchiveDir = path.join(root.path, 'tospec', 'tickets', 'archive');
+            const ticketArchiveDir = path.join(projectRoot, 'tospec', 'tickets', 'archive');
             await fs.mkdir(ticketArchiveDir, { recursive: true });
             const archivedTicketPath = path.join(ticketArchiveDir, path.basename(ticketPath));
             // `moveFile` overwrites, and two tickets share a filename when the same
@@ -737,19 +1164,9 @@ export class ArchiveCommand {
             else {
                 await moveFile(ticketPath, archivedTicketPath);
                 await retargetTicketRef(archivedTicketPath, archiveName);
-                await appendDecisionLinks(archivedTicketPath, archivePath, root.path);
+                await appendDecisionLinks(archivedTicketPath, archivePath, projectRoot);
             }
         }
-        if (!json) {
-            console.log(`Change '${changeName}' archived as '${archiveName}'.`);
-        }
-        return {
-            change: changeName,
-            archivedAs: archiveName,
-            path: archivePath,
-            specsUpdated,
-            totals,
-        };
     }
     async selectChange(changesDir, projectRoot) {
         const { select } = await import('@inquirer/prompts');