@seanmars/tospec 0.19.0-beta.8 → 0.21.0

package/dist/core/archive.js

@@ -2,10 +2,12 @@ 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';
@@ -13,34 +15,52 @@ 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';
-/**
- * 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;
@@ -69,10 +89,27 @@ 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.
+ * The copy fallback finished but the source could not be removed, so `dest` is
+ * complete and `src` may be partly deleted. Distinct from a failed copy because
+ * the recovery is the opposite: keep `dest`. A caller that rolled back by
+ * deleting `dest` would lose whatever the failed removal had already taken.
+ */
+export class MoveSourceNotRemovedError extends Error {
+    source;
+    destination;
+    constructor(source, destination, cause) {
+        super(`Copied ${source} to ${destination}, but could not remove the original ` +
+            `(${cause instanceof Error ? cause.message : String(cause)}). ` +
+            `${destination} is complete; delete what is left of ${source} by hand.`);
+        this.source = source;
+        this.destination = destination;
+        this.name = 'MoveSourceNotRemovedError';
+    }
+}
+/**
+ * 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 {
@@ -81,11 +118,17 @@ 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 });
+            // The same open handle that made rename fail with EPERM can fail this
+            // removal partway, after some files are already gone.
+            try {
+                await fs.rm(src, { recursive: true, force: true });
+            }
+            catch (rmError) {
+                throw new MoveSourceNotRemovedError(src, dest, rmError);
+            }
         }
         else {
             throw err;
@@ -93,16 +136,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;
@@ -116,35 +151,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.
-    //
-    // A read failure falls back to '\n' rather than returning: `appendFile` needs
-    // no read permission, so bailing out here would drop the section on a
-    // write-only ticket that the pre-CRLF code appended to successfully — trading
-    // a cosmetic line-ending mismatch for silent, permanent data loss.
+    // `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 {
-        // Fall through with the default.
-    }
+    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);
     }
 }
@@ -164,16 +198,20 @@ 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,
-            // See workflow/status.ts: an implicit root means no ancestor holds a
-            // `tospec/` dir, and archiving there can only fail — but with a plain
-            // "no changes directory" message rather than the shared no_tospec_root
-            // diagnostic its sibling commands report for the same condition.
+            // 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 },
         });
@@ -181,9 +219,8 @@ export class ArchiveCommand {
             return;
         }
         if (json) {
-            // A gate overridden by --yes has something to report but did not fail —
-            // exit 0 stands, and the warning rides on `status` instead of being
-            // dropped, since prose on stdout would corrupt the JSON document.
+            // 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, jsonWarnings);
@@ -193,10 +230,8 @@ export class ArchiveCommand {
                 emitSuccess({ archive: result, ...(jsonWarnings.length ? { status: jsonWarnings } : {}) }, toRootOutput(root));
             }
             catch (error) {
-                // The gates that were overridden before the failure still happened, and
-                // a run that both skipped validation *and* then failed is exactly when
-                // the reader needs to know. Dropping them here reproduced, on the
-                // failure path, the discard this collection exists to prevent.
+                // 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;
@@ -213,21 +248,15 @@ export class ArchiveCommand {
         }, 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) {
-                // No `fix`. Every gate's fix is phrased for the caller who is being
-                // blocked and ends in "or rerun with --yes" — advice that read as
-                // nonsense in the output of a run that already passed `--yes`, telling
-                // the reader to do the thing they just did. The archive has happened;
-                // there is nothing left to act on, so the message stands alone.
+                // 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 {
@@ -247,29 +276,23 @@ export class ArchiveCommand {
         return true;
     }
     /**
-     * Required artifacts the change never produced, in schema order.
-     *
-     * Reads the same graph `tospec status` does, so the two can never disagree
-     * about what "required" means. `skipped` covers the legitimate opt-out
-     * (`skip_specs: true`), and optional artifacts are the schema's own statement
-     * that their absence is fine — neither is reported here.
+     * 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.
      *
-     * A change whose graph cannot be loaded at all (unreadable metadata, unknown
-     * schema) returns nothing rather than throwing: this gate exists to describe
-     * a change, not to become a second way for archive to fail on one. Whatever
-     * broke the load is already validation's to report.
+     * 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 on purpose: loadChangeContext reads it from the
-            // change's own metadata, the same way `status` does.
+            // 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 and still holds the template, so reporting it
-                // the same way as an absent one sent the reader to look for a file that
-                // was right there. The status is what distinguishes the two, and it is
-                // already in hand here.
+                // 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 {
@@ -277,54 +300,54 @@ export class ArchiveCommand {
         }
     }
     /**
-     * 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.
+     * 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, jsonWarnings) {
         const changesDir = root.changesDir;
         const archiveDir = root.archiveDir;
         const mainSpecsDir = root.specsDir;
-        // Check if changes directory exists
         try {
             await fs.access(changesDir);
         }
-        catch {
+        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.");
         }
-        // Captured before the interactive branch can overwrite `changeName`: the
-        // kebab guard below applies to the argument only, and provenance is the
-        // thing it actually branches on. Relying on statement order instead would
-        // leave a reader to infer that from position.
-        // An empty string is not a name the user supplied, it is the absence of one:
-        // `!changeName` below sends it to the picker, so treating it as an argument
-        // would apply the kebab guard to whatever the picker returned — the one case
-        // this flag exists to exclude.
+        // 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;
-        // Get change name interactively if not provided
         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.
+        // 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;
@@ -336,14 +359,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) => {
@@ -354,33 +373,38 @@ 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 {
+            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.
-        //
-        // Minus the archive preflight, which is a dry run of the merge this function
-        // performs a few lines below. It rebuilds every updated spec to report at
-        // INFO what the merge would refuse; here that is the same work twice for a
-        // finding that cannot gate anything, while the real merge turns the same
-        // precondition into archive_spec_update_failed and exits non-zero. The
-        // equivalence above is about the verdict, and INFO never moved it.
+        // 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, {
                 archivePreflight: false,
@@ -388,15 +412,14 @@ export class ArchiveCommand {
             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.`
@@ -417,13 +440,9 @@ export class ArchiveCommand {
                 json,
                 yes: !!options.yes,
                 code: 'archive_confirmation_required',
-                // States the condition, not the remedy. A gate's `message` is reused
-                // verbatim when `--yes` overrides the gate, where "rerun with --yes"
-                // told the reader to do the thing they had just done — the same defect
-                // that removing `fix` from overridden gates was meant to end. The other
-                // two gates were already written this way ("N incomplete task(s) found"),
-                // which is why only this one carried it. Remedies belong in `fix`, which
-                // an overridden gate drops.
+                // 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)',
@@ -438,23 +457,16 @@ export class ArchiveCommand {
                 console.error(`Affected files: ${changeDir}`);
             }
         }
-        // The artifact graph already knows which artifacts a schema requires, and
-        // `status` reports it as isComplete — but nothing consulted that before
-        // archiving, so a change carrying only a delta spec archived clean with no
-        // proposal and no design. Validation cannot catch it: it checks the content
-        // of files that exist, and these do not exist.
-        //
-        // Archive is the last moment this is recoverable. Afterwards the change is
-        // in archive/ and its deltas are merged, so the why and the how the schema
-        // asked for are gone for good — and the person who had the answers has
-        // moved on. Overridable like every other gate, because a schema artifact is
-        // a planning obligation rather than a correctness one.
+        // 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", because the list holds both: an artifact with no
-            // file, and one whose file is still the unfilled template. Saying "missing"
-            // of the second sent the reader looking for a file already on disk.
+            // "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,
@@ -468,9 +480,8 @@ export class ArchiveCommand {
             if (!proceed)
                 return null;
         }
-        // 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.
+        // 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);
@@ -505,22 +516,15 @@ export class ArchiveCommand {
             if (!proceed)
                 return null;
         }
-        // Handle spec updates unless skipSpecs flag is set
         let specsUpdated = false;
         let totals = { added: 0, modified: 0, removed: 0, renamed: 0, retired: 0 };
         if (options.skipSpecs) {
-            // Round 4 report 2. `--skip-specs` is documented for changes that have no
-            // deltas, so pointing it at one that does is user error — but archiving in
-            // silence made the mistake unrecoverable: the change moved to archive/ and
-            // the capability never reached the main specs, with nothing in the output
-            // saying so. The metadata spelling of the same intent (`skip_specs: true`)
-            // is an ERROR under exactly this shape; this at least names what was left
-            // behind. It stays a warning rather than a block because the flag is an
-            // explicit instruction and `--yes` already means "I confirm".
+            // `--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 — the capability is
-                // the directory that names it, the same level findSpecUpdates walks.
+                // source is <changeDir>/specs/<capability>/spec.md.
                 const listed = discarded
                     .map((update) => path.basename(path.dirname(update.source)))
                     .join(', ');
@@ -537,15 +541,12 @@ export class ArchiveCommand {
             }
         }
         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
@@ -564,10 +565,14 @@ export class ArchiveCommand {
                     }
                 }
                 let shouldUpdateSpecs = true;
-                if (!options.yes) {
-                    if (json) {
-                        throw new ArchiveBlockedError('archive_confirmation_required', `Updating ${specUpdates.length} spec(s) requires confirmation: rerun with --yes.`, 'tospec archive <change-name> --json --yes');
-                    }
+                // JSON mode merges without asking. The merge is what archive is for,
+                // and `--skip-specs` is the explicit way to decline it; the human
+                // prompt below defaults to yes for the same reason. Demanding `--yes`
+                // here made the flag mandatory on every sdd archive, and `--yes` is
+                // also the blanket override for the task, artifact and `--no-validate`
+                // gates, so a caller who only wanted the merge had to disarm every
+                // gate to get it.
+                if (!options.yes && !json) {
                     const { confirm } = await import('@inquirer/prompts');
                     shouldUpdateSpecs = await confirm({
                         message: 'Proceed with spec updates?',
@@ -578,104 +583,117 @@ 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 });
-                            // In human mode buildUpdatedSpec already printed these. In JSON mode
-                            // it stayed silent, so `status[]` is where they have to land — a
-                            // dangling REMOVED used to be a completely invisible no-op for
-                            // agent callers.
+                    // 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) {
-                                for (const n of built.notices) {
-                                    jsonWarnings.push({ severity: 'warning', code: n.code, message: n.message });
-                                }
+                                throw new ArchiveBlockedError('archive_spec_update_failed', String(err.message || err), 'Fix the change delta specs and rerun. No files were changed.');
                             }
-                            prepared.push({ update, rebuilt: built.rebuilt, crlf: built.crlf, retired: built.retired, counts: built.counts });
+                            console.error(String(err.message || err));
+                            console.error('Aborted. No files were changed.');
+                            process.exitCode = 1;
+                            return writeTotalsSentinel;
                         }
-                    }
-                    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.');
+                        // 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(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) {
+                        const writeTotals = { added: 0, modified: 0, removed: 0, renamed: 0, retired: 0 };
                         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}`);
-                                }
-                                console.error('Aborted. No files were changed.');
-                                process.exitCode = 1;
-                                return null;
+                            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;
                         }
-                    }
-                    // 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;
+                        // 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}`);
+                            }
                         }
-                        else {
-                            await writeUpdatedSpec(p.update, p.rebuilt, p.counts, {
-                                silent: json,
-                                crlf: p.crlf,
-                            });
+                        if (!json) {
+                            console.log(`Totals: + ${writeTotals.added}, ~ ${writeTotals.modified}, - ${writeTotals.removed}, → ${writeTotals.renamed}` +
+                                (writeTotals.retired ? `, retired ${writeTotals.retired}` : ''));
+                            console.log('Specs updated successfully.');
                         }
-                        writeTotals.added += p.counts.added;
-                        writeTotals.modified += p.counts.modified;
-                        writeTotals.removed += p.counts.removed;
-                        writeTotals.renamed += p.counts.renamed;
-                    }
+                        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.
+        // 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 exists only because the change was recreated
-        // before this was fixed, so the later stamp is the one describing the change
-        // being archived — taking `readdir` order filed the run under the abandoned
-        // attempt's ticket and stranded the real one (round 4 report 6). Reported
-        // rather than cleaned up: the leftovers are the user's to keep or delete,
-        // and archive must not silently remove a record.
+        // 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
@@ -694,9 +712,33 @@ export class ArchiveCommand {
             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}'.`);
@@ -716,7 +758,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 = [];
@@ -731,19 +773,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;
         }
     }