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

package/dist/core/archive.js

@@ -2,44 +2,65 @@ import { promises as fs } from 'fs';
 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 { 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 { buildCodeFenceMask, normalizeDocument, stripBom } from './parsers/requirement-text.js';
 import { formatTimestamp } from '../utils/timestamp.js';
 import { findSpecFiles } from '../utils/spec-files.js';
 import { FileSystemUtils, isMissingPathError } from '../utils/file-system.js';
 import { isKebabId, KEBAB_ID_DESCRIPTION } from './id.js';
-import { findTicketPath, listActiveChangeDirs } from '../utils/item-discovery.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';
-/**
- * Archive directory names are always CLI-generated from this — agents must
- * never assemble the timestamp themselves. Alias of the shared
- * `formatTimestamp` (ticket filenames use the same helper).
- */
+import { withFileLock } from '../utils/file-lock.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. */
+const SYNC_CONCLUSION_LINE = /^Conclusion:\s*(PASS|FAIL)(?:\s*\([^)]*\))?\s*$/;
 /**
- * Extracts the first `Conclusion: PASS|FAIL` conclusion line from a
- * sync-report.md body, per the format `tospec-sync`'s instruction
- * produces. Returns null when no conclusion line is found (unparseable report).
+ * Returns null when no conclusion is found, when the line is an unfilled
+ * template (`Conclusion: PASS | FAIL`), or when two conclusions disagree —
+ * each must leave the `--require-sync` gate shut.
+ *
+ * Fenced lines are masked because the `tospec-sync` skill documents this format
+ * *inside* a fence: a report quoting the template carries a `Conclusion: PASS`
+ * that was never a verdict.
  */
 export function parseSyncReportConclusion(content) {
-    const conclusionLine = content
-        .split(/\r?\n/)
-        .map((line) => line.trim())
-        .find((line) => line.startsWith('Conclusion:'));
-    if (!conclusionLine)
-        return null;
-    // Reject an unfilled template such as `Conclusion: PASS | FAIL`; only an
-    // unambiguous conclusion (optionally followed by a parenthetical note) is
-    // machine-authoritative enough to open the archive gate.
-    const match = conclusionLine.match(/^Conclusion:\s*(PASS|FAIL)(?:\s*\([^)]*\))?\s*$/);
-    return match ? match[1] : null;
+    const lines = normalizeDocument(content).split('\n');
+    const fenced = buildCodeFenceMask(lines);
+    let verdict = null;
+    for (let i = 0; i < lines.length; i++) {
+        if (fenced[i])
+            continue;
+        const line = lines[i].trim();
+        if (!line.startsWith('Conclusion:'))
+            continue;
+        const match = line.match(SYNC_CONCLUSION_LINE);
+        // Not "keep looking": scanning past an unparseable conclusion would let a
+        // later, well-formed line answer for a verdict this code cannot read.
+        if (!match)
+            return null;
+        const found = match[1];
+        if (verdict === null)
+            verdict = found;
+        else if (verdict !== found)
+            return null; // two conclusions, no way to pick
+    }
+    return verdict;
+}
+/** Whether any unfenced line opens with `Conclusion:`, parseable or not. */
+function hasConclusionLine(content) {
+    const lines = normalizeDocument(content).split('\n');
+    const fenced = buildCodeFenceMask(lines);
+    return lines.some((line, i) => !fenced[i] && line.trim().startsWith('Conclusion:'));
 }
 /**
- * JSON mode is non-interactive: any point where the human flow would prompt or
- * print prose instead throws this error, which becomes a machine-readable
- * status entry with a non-zero exit code.
+ * JSON mode is non-interactive: wherever the human flow would prompt or print
+ * prose, this is thrown instead and becomes a machine-readable status entry.
  */
 class ArchiveBlockedError extends Error {
     diagnostic;
@@ -68,10 +89,9 @@ function toArchiveDiagnostic(error) {
     };
 }
 /**
- * Move a directory from src to dest. On Windows, fs.rename() often fails with
- * EPERM when the directory is non-empty or another process has it open (IDE,
- * file watcher, antivirus). Fall back to copy-then-remove when rename fails
- * with EPERM or EXDEV. Exported for migrate's two-phase promotion.
+ * 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
+ * back to copy-then-remove. Exported for migrate's two-phase promotion.
  */
 export async function moveDirectory(src, dest) {
     try {
@@ -80,9 +100,8 @@ export async function moveDirectory(src, dest) {
     catch (err) {
         const code = err?.code;
         if (code === 'EPERM' || code === 'EXDEV') {
-            // Preserve relative symlink text. Without verbatimSymlinks, Node may
-            // rewrite links to absolute paths under `src`; removing `src` below then
-            // leaves those copied links dangling (notably on Windows).
+            // 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 });
             await fs.rm(src, { recursive: true, force: true });
         }
@@ -92,16 +111,8 @@ export async function moveDirectory(src, dest) {
     }
 }
 /**
- * After a ticket moves into tickets/archive/, its `ref` still points at the
- * change's pre-archive location. Rewrite the `ref:` frontmatter line to the
- * archived change path (project-root-relative), keeping the referenced filename
- * (proposal.md or task.md). No-op if the line is absent or has no path.
- */
-/**
- * Appends a `## Related Decisions` section to the archived ticket linking the ADRs the
- * change's metadata records (`decisions`), so the permanent archive record can
- * be traced back to the decisions that drove it. Best-effort: unreadable
- * metadata or no decisions → no section, never blocks the archive.
+ * Links the ADRs in the change's metadata from the archived ticket. Best-effort:
+ * unreadable metadata or no decisions → no section, never blocks the archive.
  */
 async function appendDecisionLinks(ticketFile, archivedChangeDir, projectRoot) {
     let decisions;
@@ -115,32 +126,34 @@ async function appendDecisionLinks(ticketFile, archivedChangeDir, projectRoot) {
         return;
     // Ticket lives in tospec/tickets/archive/, decisions in tospec/decisions/.
     const lines = decisions.map((d) => `- [${d}](../../decisions/${d})`);
-    // Append with the ticket's own line endings. `appendFile` never reads the
-    // file, so a hardcoded '\n' left a CRLF ticket mixed: CRLF above the heading
-    // and LF below it. Reading first is the only way to know, and a read failure
-    // here is as harmless as the metadata failure above — skip the section rather
-    // than block the archive.
-    let existing;
+    // `appendFile` never reads the file, so a hardcoded '\n' left a CRLF ticket
+    // mixed. A read failure falls back to '\n' rather than returning: `appendFile`
+    // needs no read permission, and bailing would drop the section.
+    let existing = '';
     try {
         existing = await fs.readFile(ticketFile, 'utf-8');
     }
-    catch {
-        return;
-    }
+    catch { }
     const eol = existing.includes('\r\n') ? '\r\n' : '\n';
     const block = ['', '## Related Decisions', '', ...lines, ''].join(eol);
     await fs.appendFile(ticketFile, block);
 }
 /**
- * Line endings survive here without special handling, deliberately: the pattern
- * excludes line terminators (`[^/\r\n]+`, no `s` flag), so `replace` only ever
- * rewrites within a line and whatever terminated it is untouched. Do not
+ * Repoints an archived ticket's `ref:` frontmatter at the change's new path,
+ * keeping the referenced filename. No-op when the line is absent.
+ *
+ * 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.
  */
 async function retargetTicketRef(ticketFile, archiveName) {
-    const content = await fs.readFile(ticketFile, 'utf-8');
+    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 !== content) {
+    if (updated !== raw) {
         await fs.writeFile(ticketFile, updated);
     }
 }
@@ -160,47 +173,70 @@ export async function moveFile(src, dest) {
         }
     }
 }
+/**
+ * Returned by the locked merge when a human-mode failure path already printed
+ * and set the exit code. Distinct from `null` so the caller cannot forget to
+ * handle it.
+ */
+const writeTotalsSentinel = Symbol('archive-merge-aborted');
 export class ArchiveCommand {
     async execute(changeName, options = {}) {
         const json = !!options.json;
-        // Same root resolution adapter as every other command (report 4.3).
         const root = await resolveRootForCommand(options, {
             json,
-            failurePayload: { archive: null },
+            // An implicit root means no ancestor holds `tospec/`, so archiving can
+            // only fail — and with a vaguer message than the shared no_tospec_root
+            // diagnostic.
+            allowImplicitRoot: false,
+            failurePayload: { archive: null, root: null },
         });
         if (!root) {
             return;
         }
         if (json) {
+            // A gate overridden by --yes did not fail, so exit 0 stands and its
+            // warning rides on `status` — prose on stdout would corrupt the JSON.
+            const jsonWarnings = [];
             try {
-                const result = await this.run(changeName, options, root, true);
+                const result = await this.run(changeName, options, root, true, jsonWarnings);
                 if (!result) {
                     return;
                 }
-                emitSuccess({ archive: result }, toRootOutput(root));
+                emitSuccess({ archive: result, ...(jsonWarnings.length ? { status: jsonWarnings } : {}) }, toRootOutput(root));
             }
             catch (error) {
-                this.printJsonFailure(root, toArchiveDiagnostic(error));
+                // Gates overridden before the failure still happened, and a run that
+                // skipped validation *and* then failed is when the reader needs to know.
+                this.printJsonFailure(root, toArchiveDiagnostic(error), jsonWarnings);
             }
             return;
         }
-        await this.run(changeName, options, root, false);
+        await this.run(changeName, options, root, false, []);
     }
-    printJsonFailure(root, diagnostic) {
-        emitFailureStatus({ archive: null, ...(root ? { root: toRootOutput(root) } : {}) }, diagnostic);
+    printJsonFailure(root, diagnostic, jsonWarnings = []) {
+        // emitFailureStatus appends the error to any `status` already in the
+        // payload, so the warnings keep their order and precede the failure.
+        emitFailureStatus({
+            archive: null,
+            ...(root ? { root: toRootOutput(root) } : {}),
+            ...(jsonWarnings.length ? { status: jsonWarnings } : {}),
+        }, diagnostic);
     }
     /**
-     * One archive gate. JSON mode is non-interactive, so a blocked path throws;
-     * human mode prompts; `--yes` downgrades either to a warning. Returns false
-     * when the user declines, and the caller returns null.
-     *
-     * The gates used to be written out longhand at each site and had to stay in
-     * step by hand for the "every blocked path throws in JSON mode" invariant.
+     * One archive gate, so the "every blocked path throws in JSON mode" invariant
+     * lives in one place. JSON mode throws; human mode prompts; `--yes` downgrades
+     * either to a warning. False means the user declined.
      */
     async gate(opts) {
         if (opts.yes) {
-            if (!opts.json)
+            if (opts.json) {
+                // No `fix`: every gate's fix ends in "or rerun with --yes", which tells
+                // a reader who already passed `--yes` to do what they just did.
+                opts.warnings.push({ severity: 'warning', code: opts.code, message: opts.message });
+            }
+            else {
                 console.error(opts.warning);
+            }
             return true;
         }
         if (opts.json) {
@@ -215,45 +251,78 @@ export class ArchiveCommand {
         return true;
     }
     /**
-     * Shared archive flow. In human mode (json=false) prompts and prose match
-     * the historical behavior and cancellations return null. In JSON mode no
-     * prose reaches stdout and every blocked path throws.
+     * Required artifacts the change never produced, in schema order. Reads the
+     * same graph `tospec status` does, so the two cannot disagree about what
+     * "required" means; `skipped` and `optional` are legitimate absences.
+     *
+     * An unloadable graph returns nothing rather than throwing: this gate must not
+     * become a second way for archive to fail. Whatever broke the load is
+     * validation's to report.
+     */
+    findMissingRequiredArtifacts(projectRoot, changeName, changeDir) {
+        try {
+            // Schema left undefined: loadChangeContext reads it from the change's own
+            // metadata, as `status` does.
+            const status = formatChangeStatus(loadChangeContext(projectRoot, changeName, undefined, { changeDir }));
+            return status.artifacts
+                .filter((artifact) => !artifact.optional && artifact.status !== 'done' && artifact.status !== 'skipped')
+                // A stub's file is on disk holding the template, so reporting it like an
+                // absent one sends the reader looking for a file that is right there.
+                .map((artifact) => (artifact.status === 'stub' ? `${artifact.id} (stub)` : artifact.id));
+        }
+        catch {
+            return [];
+        }
+    }
+    /**
+     * Shared archive flow. Human mode prompts and returns null on cancellation;
+     * JSON mode keeps stdout clean and throws from every blocked path.
      */
-    async run(changeName, options, root, json) {
+    async run(changeName, options, root, json, jsonWarnings) {
         const changesDir = root.changesDir;
         const archiveDir = root.archiveDir;
         const mainSpecsDir = root.specsDir;
-        // Check if changes directory exists
         try {
             await fs.access(changesDir);
         }
-        catch {
-            throw new Error("No Tospec changes directory found. Run 'tospec init' first.");
+        catch (error) {
+            // Only an absent directory is "run init"; a directory that exists but
+            // cannot be entered (EACCES) is a different problem with a different fix.
+            if (!isMissingPathError(error))
+                throw error;
+            throw new ArchiveBlockedError('changes_dir_missing', 'No Tospec changes directory found.', "Run 'tospec init' first.");
         }
-        // Get change name interactively if not provided
+        // Captured before the interactive branch overwrites `changeName`: the kebab
+        // guard below applies to the argument only, never to what the picker
+        // returned. An empty string is the absence of a name.
+        const nameFromArgument = typeof changeName === 'string' && changeName.length > 0;
         if (!changeName) {
             if (json) {
                 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>');
+            }
             const selectedChange = await this.selectChange(changesDir, root.path);
             if (!selectedChange) {
+                // The same outcome as Ctrl-C on the confirmation prompt, so the same
+                // exit code: an abort the user chose is not a successful run.
                 console.error('No change selected. Aborting.');
+                process.exitCode = 130;
                 return null;
             }
             changeName = selectedChange;
         }
-        // Only validate a name that came from the argument. The interactive
-        // selection path lists real directories, some of which predate this
-        // constraint in existing projects — rejecting one the CLI just offered would
-        // make an archivable change unarchivable.
-        if (!isKebabId(changeName)) {
+        // The picker lists real directories, some predating this constraint;
+        // rejecting one the CLI just offered would make it unarchivable.
+        if (nameFromArgument && !isKebabId(changeName)) {
             throw new ArchiveBlockedError('archive_change_name_invalid', `Change name '${changeName}' is not a valid change id — it ${KEBAB_ID_DESCRIPTION}.`);
         }
         const changeDir = path.join(changesDir, changeName);
-        // Verify change exists. `.catch` rather than a try/catch around the branch:
-        // the old shape threw `Change not found` from inside its own try, so that
-        // branch was dead code, and the bare catch also rewrote genuine IO failures
-        // (EACCES, EIO) as "not found". Only a missing path may answer that.
+        // Only a missing path may answer "not found" — a bare catch here rewrote
+        // genuine IO failures (EACCES, EIO) as a nonexistent change.
         const stat = await fs.stat(changeDir).catch((error) => {
             if (isMissingPathError(error))
                 return null;
@@ -265,14 +334,10 @@ export class ArchiveCommand {
                 ? `Change '${changeName}' not found. Available changes: ${available.join(', ')}`
                 : `Change '${changeName}' not found. No active changes exist in this root.`);
         }
-        // Reserve the archive name before anything is written. This check needs only
-        // the timestamp and the change name — no merge result — but it used to run
-        // *after* the main specs had been written, so a collision left specs merged
-        // with the change still in tospec/changes/: a retry re-applied the same
-        // deltas, and REMOVED/RENAMED then took their "already synced" branch with
-        // counts that no longer described reality. The stamp is computed once here
-        // and reused for the move below, so the directory that was checked is the
-        // directory that gets created.
+        // 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
+        // below, so the checked directory is the one made.
         const archiveName = `${formatArchiveStamp(new Date())}-${changeName}`;
         const archivePath = path.join(archiveDir, archiveName);
         const archiveTargetStat = await fs.stat(archivePath).catch((error) => {
@@ -283,40 +348,53 @@ export class ArchiveCommand {
         if (archiveTargetStat) {
             throw new ArchiveBlockedError('archive_target_exists', `Archive '${archiveName}' already exists.`);
         }
-        // --require-sync gate: the machine-checkable half of the
-        // tospec-sync workflow (the semantic half — does the report's content
-        // actually reflect reality — is the sync agent's job, not ours).
+        // The machine-checkable half of tospec-sync; whether the report's content
+        // reflects reality is the sync agent's job, not ours.
         if (options.requireSync) {
             const syncReportPath = path.join(changeDir, 'sync-report.md');
             let syncReportContent;
             try {
                 syncReportContent = await fs.readFile(syncReportPath, 'utf-8');
             }
-            catch {
-                throw new ArchiveBlockedError('SYNC_REPORT_MISSING', `sync-report.md not found for change '${changeName}'.`, 'Run tospec-sync first, or omit --require-sync.');
+            catch (error) {
+                // "Run tospec-sync" is the fix for an absent report only; an unreadable
+                // one (EACCES) would be re-written by sync and still not be readable.
+                if (!isMissingPathError(error))
+                    throw error;
+                throw new ArchiveBlockedError('sync_report_missing', `sync-report.md not found for change '${changeName}'.`, 'Run tospec-sync first, or omit --require-sync.');
             }
             const conclusion = parseSyncReportConclusion(syncReportContent);
             if (conclusion !== 'PASS') {
-                throw new ArchiveBlockedError('SYNC_REPORT_FAILED', `sync-report.md for change '${changeName}' does not report a PASS conclusion (found: ${conclusion ?? 'unparseable'}).`, 'Resolve the flagged Requirement(s) via tospec-apply, then re-run tospec-sync.');
+                // Three states, three fixes: FAIL means requirements to resolve; no
+                // `Conclusion:` line means the sync report was never finished; a line
+                // that is there but unreadable (an unfilled `PASS | FAIL` template, or
+                // two verdicts that disagree) means the report needs editing, not
+                // another apply pass.
+                const found = conclusion ?? (hasConclusionLine(syncReportContent) ? 'unparseable Conclusion line' : 'no Conclusion line');
+                throw new ArchiveBlockedError('sync_report_failed', `sync-report.md for change '${changeName}' does not report a PASS conclusion (found: ${found}).`, conclusion === 'FAIL'
+                    ? 'Resolve the flagged Requirement(s) via tospec-apply, then re-run tospec-sync.'
+                    : 'Finish the report with a single `Conclusion: PASS` or `Conclusion: FAIL` line outside any code fence, or re-run tospec-sync.');
             }
         }
         const skipValidation = options.validate === false || options.noValidate === true;
-        // Validate specs and change before archiving — the exact same pipeline
-        // `tospec validate` runs, so validate green ⟺ archive passes validation.
+        // 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.
         if (!skipValidation) {
-            const report = await validateChangeArtifacts(root.path, changeDir);
+            const report = await validateChangeArtifacts(root.path, changeDir, {
+                archivePreflight: false,
+            });
             if (!json && report.issues.length > 0) {
                 console.error(`\nValidation issues for change '${changeName}':`);
                 for (const issue of report.issues) {
-                    const symbol = issue.level === 'ERROR' ? '✗' : issue.level === 'WARNING' ? '⚠' : 'ℹ';
+                    const symbol = issueSymbol(issue.level);
                     console.error(`  ${symbol} ${issue.path}: ${issue.message}`);
                 }
             }
             if (!report.valid) {
-                // --skip-specs is honoured further down, long after this gate, so a
-                // change with no deltas fails here no matter what the flag says. Point
-                // at the marker that actually resolves it rather than at --no-validate,
-                // which only buries the question.
+                // --skip-specs is honoured long after this gate, so a change with no
+                // deltas fails here regardless. Point at the marker that resolves it,
+                // 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.`
@@ -337,10 +415,14 @@ export class ArchiveCommand {
                 json,
                 yes: !!options.yes,
                 code: 'archive_confirmation_required',
-                message: 'Skipping validation requires confirmation: rerun with --yes.',
+                // States the condition, not the remedy: `message` is reused verbatim
+                // 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.',
+                warnings: jsonWarnings,
             });
             if (!proceed)
                 return null;
@@ -350,9 +432,31 @@ export class ArchiveCommand {
                 console.error(`Affected files: ${changeDir}`);
             }
         }
-        // Show progress and check for incomplete tasks
-        // Use the already-resolved root rather than re-deriving it from changesDir:
-        // the '..','..' hop silently encodes the tospec/changes layout.
+        // Validation checks the content of files that exist, so it cannot catch a
+        // change archiving with no proposal and no design. Archive is the last
+        // recoverable moment. Overridable, because a schema artifact is a planning
+        // obligation rather than a correctness one.
+        const missingArtifacts = this.findMissingRequiredArtifacts(root.path, changeName, changeDir);
+        if (missingArtifacts.length > 0) {
+            const names = missingArtifacts.join(', ');
+            // "missing or incomplete": the list holds both absent files and unfilled
+            // templates, and calling the second "missing" sends readers hunting for a
+            // file already on disk.
+            const proceed = await this.gate({
+                json,
+                yes: !!options.yes,
+                code: 'archive_artifacts_incomplete',
+                message: `Change '${changeName}' is missing or has incomplete required artifact(s): ${names}.`,
+                fix: `Run tospec status --change ${changeName} for the next step, or rerun with --yes.`,
+                prompt: `Warning: missing or incomplete required artifact(s): ${names}. Continue?`,
+                warning: `Warning: missing or incomplete required artifact(s): ${names}. Continuing due to --yes flag.`,
+                warnings: jsonWarnings,
+            });
+            if (!proceed)
+                return null;
+        }
+        // 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);
         if (!json) {
             const status = formatTaskStatus(progress);
@@ -368,6 +472,7 @@ export class ArchiveCommand {
                 fix: 'Create the schema-tracked tasks file with checkboxes, or rerun with --yes.',
                 prompt: 'Warning: no tracked task checkboxes were found. Continue?',
                 warning: 'Warning: no tracked task checkboxes were found. Continuing due to --yes flag.',
+                warnings: jsonWarnings,
             });
             if (!proceed)
                 return null;
@@ -381,28 +486,42 @@ export class ArchiveCommand {
                 fix: 'Complete the tasks or rerun with --yes.',
                 prompt: `Warning: ${incompleteTasks} incomplete task(s) found. Continue?`,
                 warning: `Warning: ${incompleteTasks} incomplete task(s) found. Continuing due to --yes flag.`,
+                warnings: jsonWarnings,
             });
             if (!proceed)
                 return null;
         }
-        // Handle spec updates unless skipSpecs flag is set
         let specsUpdated = false;
-        let totals;
+        let totals = { added: 0, modified: 0, removed: 0, renamed: 0, retired: 0 };
         if (options.skipSpecs) {
-            if (!json) {
+            // `--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) {
+                // source is <changeDir>/specs/<capability>/spec.md.
+                const listed = discarded
+                    .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}.`;
+                if (json) {
+                    jsonWarnings.push({ severity: 'warning', code: 'archive_deltas_discarded', message });
+                }
+                else {
+                    console.log(`Warning: ${message}`);
+                }
+            }
+            else if (!json) {
                 console.log('Skipping spec updates (--skip-specs flag provided).');
             }
         }
         else {
-            // Find specs to update
             const specUpdates = await findSpecUpdates(changeDir, mainSpecsDir);
             if (specUpdates.length === 0) {
-                // findSpecUpdates only reads specs/<capability>/spec.md. Validation
-                // rejects anything else, so reaching here with delta files present means
-                // validation was skipped (--no-validate). Merging nothing and reporting
-                // success would drop the requirements without a word — the exact failure
-                // this guard exists to make impossible. Match on spec.md only: a stray
-                // NOTES.md under specs/ is not a delta and must not block an archive.
+                // 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'));
                 if (orphans.length > 0) {
                     const listed = orphans
@@ -435,96 +554,162 @@ export class ArchiveCommand {
                     }
                 }
                 if (shouldUpdateSpecs) {
-                    // Prepare all updates first (validation pass, no writes)
-                    const prepared = [];
-                    try {
-                        for (const update of specUpdates) {
-                            const built = await buildUpdatedSpec(update, changeName, { silent: json });
-                            prepared.push({ update, rebuilt: built.rebuilt, crlf: built.crlf, retired: built.retired, counts: built.counts });
+                    // Everything to the last write is one critical section: the merge
+                    // reads each main spec, builds the new text in memory and only then
+                    // writes, so two concurrent archives both read the pre-merge text and
+                    // the second erases the first one's requirement.
+                    //
+                    // The lock starts here, not at the top of `run`: a lock held across
+                    // the picker or the confirmation prompt above would block every other
+                    // process until someone returns to the terminal.
+                    const locked = await withFileLock(path.join(root.path, 'tospec', '.archive.lock'), async () => {
+                        // Prepare every update before writing any of them.
+                        const prepared = [];
+                        // Held back until every spec is written. A notice describes what the
+                        // merge did ("wrote a TBD placeholder"), so surfacing it from a run
+                        // that then aborted with "No files were changed" contradicts itself.
+                        const mergeNotices = [];
+                        try {
+                            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 });
+                            }
                         }
-                    }
-                    catch (err) {
-                        if (json) {
-                            throw new ArchiveBlockedError('archive_spec_update_failed', String(err.message || err), 'Fix the change delta specs and rerun. No files were changed.');
+                        catch (err) {
+                            if (json) {
+                                throw new ArchiveBlockedError('archive_spec_update_failed', String(err.message || err), 'Fix the change delta specs and rerun. No files were changed.');
+                            }
+                            console.error(String(err.message || err));
+                            console.error('Aborted. No files were changed.');
+                            process.exitCode = 1;
+                            return writeTotalsSentinel;
                         }
-                        console.error(String(err.message || err));
-                        console.error('Aborted. No files were changed.');
-                        process.exitCode = 1;
-                        return null;
-                    }
-                    // Validate every rebuilt spec before writing any of them, so a
-                    // late validation failure really does leave all targets unchanged.
-                    if (!skipValidation) {
-                        for (const p of prepared) {
-                            // A retired capability has no requirements left, so validating its
-                            // rebuilt text would always fail on "at least one requirement" -
-                            // the very deadlock retirement exists to break. It is deleted, not
-                            // written, so there is no content to hold to that rule.
-                            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) {
-                                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.`);
-                                }
-                                console.error(`\nValidation errors in rebuilt spec for ${specName} (will not write changes):`);
-                                for (const issue of report.issues) {
-                                    if (issue.level === 'ERROR')
-                                        console.error(`  ✗ ${issue.message}`);
-                                    else if (issue.level === 'WARNING')
-                                        console.error(`  ⚠ ${issue.message}`);
+                        // Validate every rebuilt spec before writing any of them, so a
+                        // late validation failure really does leave all targets unchanged.
+                        if (!skipValidation) {
+                            for (const p of prepared) {
+                                // A retired capability has no requirements left, so validating it
+                                // would always fail on "at least one requirement". It is deleted,
+                                // not written.
+                                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) {
+                                    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.`);
+                                    }
+                                    console.error(`\nValidation errors in rebuilt spec for ${specName} (will not write changes):`);
+                                    for (const issue of report.issues) {
+                                        if (issue.level === 'ERROR')
+                                            console.error(`  ✗ ${issue.message}`);
+                                        else if (issue.level === 'WARNING')
+                                            console.error(`  ⚠ ${issue.message}`);
+                                    }
+                                    console.error('Aborted. No files were changed.');
+                                    process.exitCode = 1;
+                                    return writeTotalsSentinel;
                                 }
-                                console.error('Aborted. No files were changed.');
-                                process.exitCode = 1;
-                                return null;
                             }
                         }
-                    }
-                    // All validations passed; write files and display counts
-                    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 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;
+                            }
+                            else {
+                                await writeUpdatedSpec(p.update, p.rebuilt, p.counts, {
+                                    silent: json,
+                                    crlf: p.crlf,
+                                });
+                            }
+                            writeTotals.added += p.counts.added;
+                            writeTotals.modified += p.counts.modified;
+                            writeTotals.removed += p.counts.removed;
+                            writeTotals.renamed += p.counts.renamed;
                         }
-                        else {
-                            await writeUpdatedSpec(p.update, p.rebuilt, p.counts, {
-                                silent: json,
-                                crlf: p.crlf,
-                            });
+                        // Now true: the files the notices talk about exist on disk. In JSON
+                        // mode a dangling REMOVED used to be an invisible no-op, hence the
+                        // envelope entry rather than silence.
+                        for (const n of mergeNotices) {
+                            if (json) {
+                                jsonWarnings.push({ severity: 'warning', code: n.code, message: n.message });
+                            }
+                            else {
+                                console.log(`Warning: ${n.message}`);
+                            }
                         }
-                        writeTotals.added += p.counts.added;
-                        writeTotals.modified += p.counts.modified;
-                        writeTotals.removed += p.counts.removed;
-                        writeTotals.renamed += p.counts.renamed;
-                    }
+                        if (!json) {
+                            console.log(`Totals: + ${writeTotals.added}, ~ ${writeTotals.modified}, - ${writeTotals.removed}, → ${writeTotals.renamed}` +
+                                (writeTotals.retired ? `, retired ${writeTotals.retired}` : ''));
+                            console.log('Specs updated successfully.');
+                        }
+                        return { totals: writeTotals };
+                    }, { operation: `archive ${changeName}` });
+                    // The human-mode failure paths above already printed and set the exit code.
+                    if (locked === writeTotalsSentinel)
+                        return null;
                     specsUpdated = true;
-                    totals = writeTotals;
-                    if (!json) {
-                        console.log(`Totals: + ${writeTotals.added}, ~ ${writeTotals.modified}, - ${writeTotals.removed}, → ${writeTotals.renamed}` +
-                            (writeTotals.retired ? `, retired ${writeTotals.retired}` : ''));
-                        console.log('Specs updated successfully.');
-                    }
+                    totals = locked.totals;
                 }
             }
         }
-        // `archiveName` / `archivePath` were resolved and checked for collision
-        // before any spec was written; see the reservation above.
+        // Name and collision were settled at the reservation above.
         await fs.mkdir(archiveDir, { recursive: true });
-        // Move change to archive (uses copy+remove on EPERM/EXDEV, e.g. Windows)
         await moveDirectory(changeDir, archivePath);
-        // The change's ticket lives in the global tospec/tickets/ index (outside the
-        // change dir), so move it alongside into tickets/archive/ to keep the active
-        // index limited to in-flight changes.
-        const ticketPath = await findTicketPath(root.path, changeName);
+        // 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);
+        // 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.
+        const ticketPath = ticketPaths[ticketPaths.length - 1];
+        if (ticketPaths.length > 1) {
+            const stranded = ticketPaths
+                .slice(0, -1)
+                .map((file) => path.basename(file))
+                .join(', ');
+            const message = `${ticketPaths.length} active tickets name change '${changeName}'; archived ${path.basename(ticketPath)} and left the rest in tospec/tickets/: ${stranded}.`;
+            if (json) {
+                jsonWarnings.push({ severity: 'warning', code: 'ticket_duplicates_left', message });
+            }
+            else {
+                console.log(`Warning: ${message}`);
+            }
+        }
         if (ticketPath) {
             const ticketArchiveDir = path.join(root.path, 'tospec', 'tickets', 'archive');
             await fs.mkdir(ticketArchiveDir, { recursive: true });
             const archivedTicketPath = path.join(ticketArchiveDir, path.basename(ticketPath));
-            await moveFile(ticketPath, archivedTicketPath);
-            await retargetTicketRef(archivedTicketPath, archiveName);
-            await appendDecisionLinks(archivedTicketPath, archivePath, root.path);
+            // `moveFile` overwrites, and two tickets share a filename when the same
+            // change name is created twice in one second with an archive between.
+            // Left in place and reported rather than renamed around: inventing a
+            // second filename would make the index disagree with its frontmatter.
+            const archivedTicketExists = await fs
+                .stat(archivedTicketPath)
+                .then(() => true)
+                .catch((error) => {
+                if (isMissingPathError(error))
+                    return false;
+                throw error;
+            });
+            if (archivedTicketExists) {
+                const message = `tospec/tickets/archive/${path.basename(archivedTicketPath)} already exists, so this change's ticket ` +
+                    `was left in tospec/tickets/ rather than overwriting it. Rename one of the two — they describe different changes.`;
+                if (json) {
+                    jsonWarnings.push({ severity: 'warning', code: 'ticket_archive_collision', message });
+                }
+                else {
+                    console.log(`Warning: ${message}`);
+                }
+            }
+            else {
+                await moveFile(ticketPath, archivedTicketPath);
+                await retargetTicketRef(archivedTicketPath, archiveName);
+                await appendDecisionLinks(archivedTicketPath, archivePath, root.path);
+            }
         }
         if (!json) {
             console.log(`Change '${changeName}' archived as '${archiveName}'.`);
@@ -534,7 +719,7 @@ export class ArchiveCommand {
             archivedAs: archiveName,
             path: archivePath,
             specsUpdated,
-            ...(totals ? { totals } : {}),
+            totals,
         };
     }
     async selectChange(changesDir, projectRoot) {
@@ -544,7 +729,7 @@ export class ArchiveCommand {
             console.log('No active changes found.');
             return null;
         }
-        // Build choices with progress inline to avoid duplicate lists
+        // Task progress is decoration; on any failure the plain names still work.
         let choices = changeDirs.map(name => ({ name, value: name }));
         try {
             const progressList = [];
@@ -559,19 +744,15 @@ export class ArchiveCommand {
                 value: p.id
             }));
         }
-        catch {
-            // If anything fails, fall back to simple names
-            choices = changeDirs.map(name => ({ name, value: name }));
-        }
+        catch { }
         try {
-            const answer = await select({
+            return await select({
                 message: 'Select a change to archive',
                 choices
             });
-            return answer;
         }
-        catch (error) {
-            // User cancelled (Ctrl+C)
+        catch {
+            // Ctrl+C.
             return null;
         }
     }