@seanmars/tospec 0.24.0 → 0.26.0-beta

package/dist/commands/validate.js

@@ -1,22 +1,24 @@
 import path from 'path';
 import { promises as fs } from 'fs';
 import { Validator } from '../core/validation/validator.js';
-import { issueSymbol } from '../core/validation/types.js';
+import { issueSymbol, ARCHIVE_REFUSAL_CODE } from '../core/validation/types.js';
 import { validateSections } from '../core/validation/section-validator.js';
 import { resolveSchema, getSchemaDir } from '../core/artifact-graph/resolver.js';
 import { resolveArtifactOutputs } from '../core/artifact-graph/outputs.js';
-import { isStubArtifactFile } from '../core/artifact-graph/stub-detection.js';
-import { METADATA_FILENAME, readSkipSpecsMarker, resolveSchemaForChange, } from '../utils/change-metadata.js';
+import { detectStubArtifact } from '../core/artifact-graph/stub-detection.js';
+import { ChangeMetadataError, METADATA_FILENAME, UnknownChangeSchemaError, readSkipSpecsMarker, resolveSchemaForChange, findChangeSchemaFault, findUnknownMetadataKeys, readChangeMetadata, suggestMetadataKey, } from '../utils/change-metadata.js';
+import { findDecisionReferenceProblems } from './decision.js';
 import { FileSystemUtils } from '../utils/file-system.js';
-import { findSpecFiles } from '../utils/spec-files.js';
+import { findRootDeltaFiles, findSkipSpecsContradictions } from '../utils/spec-files.js';
 import { resolveRootForCommand, toRootOutput, } from '../core/root-selection.js';
 import { isInteractive, resolveNoInteractive } from '../utils/interactive.js';
-import { emitSuccess, emitFailureStatus } from './shared-output.js';
+import { emitSuccess, emitFailureStatus, indentContinuation } from './shared-output.js';
 import { getSpecIds } from '../utils/item-discovery.js';
 import { getAvailableChanges } from './workflow/shared.js';
 import { nearestMatches } from '../utils/match.js';
 import { resolveTaskFiles } from '../utils/task-progress.js';
 import { findTaskNumberingIssues, } from '../core/validation/task-numbering.js';
+import { findTaskMarkerIssues } from '../core/validation/task-markers.js';
 /**
  * The one null-shape every `validate --json` failure carries, so a caller
  * reading `result.summary.totals` never gets `undefined` from one failure path
@@ -105,7 +107,7 @@ export class ValidateCommand {
         items.push(...changes.map(id => ({ name: `change/${id}`, value: { type: 'change', id } })));
         items.push(...specs.map(id => ({ name: `spec/${id}`, value: { type: 'spec', id } })));
         if (items.length === 0) {
-            console.error('No items found to validate.');
+            console.error('Error: No items found to validate.');
             process.exitCode = 1;
             return;
         }
@@ -132,10 +134,12 @@ export class ValidateCommand {
             });
             return;
         }
-        console.error('Nothing to validate. Try one of:');
+        // Every line after `Error:` is indented, as a multi-line fix is: a bare
+        // line would read as a second message.
+        console.error('Error: Nothing to validate. Try one of:');
         for (const line of fix)
             console.error(`  ${line}`);
-        console.error('Or run in an interactive terminal.');
+        console.error('  Or run in an interactive terminal.');
         process.exitCode = 1;
     }
     async validateDirectItem(root, itemName, opts) {
@@ -162,7 +166,7 @@ export class ValidateCommand {
                 emitFailureStatus({ ...VALIDATE_FAILURE_PAYLOAD, root: toRootOutput(root) }, { severity: 'error', code: 'unknown_item', message });
             }
             else {
-                console.error(message);
+                console.error(`Error: ${message}`);
                 process.exitCode = 1;
             }
             return;
@@ -178,7 +182,7 @@ export class ValidateCommand {
                 emitFailureStatus({ ...VALIDATE_FAILURE_PAYLOAD, root: toRootOutput(root) }, { severity: 'error', code: 'unknown_item', message });
             }
             else {
-                console.error(message);
+                console.error(`Error: ${message}`);
                 process.exitCode = 1;
             }
             return;
@@ -193,8 +197,8 @@ export class ValidateCommand {
                 });
                 return;
             }
-            console.error(`Ambiguous item '${itemName}' matches both a change and a spec.`);
-            console.error('Pass --type change|spec, or use: tospec validate --changes / tospec validate --specs');
+            console.error(`Error: Ambiguous item '${itemName}' matches both a change and a spec.`);
+            console.error('Fix: Pass --type change|spec, or use: tospec validate --changes / tospec validate --specs');
             process.exitCode = 1;
             return;
         }
@@ -220,6 +224,8 @@ export class ValidateCommand {
     }
     printReport(type, id, report, durationMs, json, root, strict = false) {
         if (json) {
+            const archiveRefusals = countArchiveRefusals(report.issues);
+            const counts = { items: 1, passed: report.valid ? 1 : 0, failed: report.valid ? 0 : 1, archiveRefusals };
             emitSuccess({
                 items: [
                     {
@@ -229,9 +235,10 @@ export class ValidateCommand {
                         issues: report.issues,
                         ...(report.notes?.length ? { notes: report.notes } : {}),
                         durationMs,
+                        archiveRefusals,
                     },
                 ],
-                summary: { totals: { items: 1, passed: report.valid ? 1 : 0, failed: report.valid ? 0 : 1 }, byType: { [type]: { items: 1, passed: report.valid ? 1 : 0, failed: report.valid ? 0 : 1 } } },
+                summary: { totals: counts, byType: { [type]: { ...counts } } },
             }, toRootOutput(root));
             return;
         }
@@ -272,6 +279,19 @@ export class ValidateCommand {
     printNextSteps(type, id, root, issues, strict) {
         const bullets = [];
         if (type === 'change') {
+            // The metadata and the whole-change "No deltas found" ERROR sit outside
+            // `<capability>/spec.md`, so the delta hints below never matched them,
+            // and a change failing on those too was told only to add a section.
+            // Their messages carry the fix; the bullet says it is still owed. It does
+            // not say "Fix .tospec.yaml": a schema issue filed there may be fixed in
+            // tospec/config.yaml or the schema's own file.
+            const fails = (issue) => issue.level === 'ERROR' || strict;
+            if (issues.some((issue) => issue.path === METADATA_FILENAME && fails(issue))) {
+                bullets.push(`- Resolve the ${METADATA_FILENAME} issue as its message above says`);
+            }
+            if (issues.some((issue) => issue.path === 'file' && /No deltas found/.test(issue.message) && fails(issue))) {
+                bullets.push('- Write the delta specs under specs/<capability>/spec.md, or set `skip_specs: true` in .tospec.yaml only when the user confirms this change needs no delta spec');
+            }
             // Each delta hint answers one failure. A missing Migration field or a
             // SHALL/MUST warning under --strict is a delta issue too, and used to be
             // told to add a Scenario block it already had.
@@ -357,10 +377,10 @@ export class ValidateCommand {
         }
         if (queue.length === 0) {
             const summary = {
-                totals: { items: 0, passed: 0, failed: 0 },
+                totals: { items: 0, passed: 0, failed: 0, archiveRefusals: 0 },
                 byType: {
-                    ...(scope.changes ? { change: { items: 0, passed: 0, failed: 0 } } : {}),
-                    ...(scope.specs ? { spec: { items: 0, passed: 0, failed: 0 } } : {}),
+                    ...(scope.changes ? { change: { items: 0, passed: 0, failed: 0, archiveRefusals: 0 } } : {}),
+                    ...(scope.specs ? { spec: { items: 0, passed: 0, failed: 0, archiveRefusals: 0 } } : {}),
                 },
             };
             if (opts.json) {
@@ -415,7 +435,7 @@ export class ValidateCommand {
         const passed = results.filter((res) => res.valid).length;
         const failed = results.length - passed;
         const summary = {
-            totals: { items: results.length, passed, failed },
+            totals: { items: results.length, passed, failed, archiveRefusals: sumArchiveRefusals(results) },
             byType: {
                 ...(scope.changes ? { change: summarizeType(results, 'change') } : {}),
                 ...(scope.specs ? { spec: summarizeType(results, 'spec') } : {}),
@@ -423,7 +443,10 @@ export class ValidateCommand {
         };
         // One copy per run: a sweep of forty specs trips the same rule forty times.
         const runNotes = [...new Set(results.flatMap((res) => res.notes ?? []))];
-        const items = results.map(({ notes: _notes, ...res }) => res);
+        const items = results.map(({ notes: _notes, ...res }) => ({
+            ...res,
+            archiveRefusals: countArchiveRefusals(res.issues),
+        }));
         if (opts.json) {
             emitSuccess({ items, summary, ...(runNotes.length ? { notes: runNotes } : {}) }, toRootOutput(root));
         }
@@ -475,17 +498,24 @@ export async function validateArtifactSections(projectRoot, changeDir) {
         return issues;
     }
     const schemaDir = getSchemaDir(schemaName, projectRoot);
+    const changeName = path.basename(changeDir);
     for (const artifact of schema.artifacts) {
         for (const file of resolveArtifactOutputs(changeDir, artifact.generates)) {
             const relPath = FileSystemUtils.toPosixPath(path.relative(changeDir, file));
             // Runs before the section rules because a template satisfies them by
             // construction — it is where every required heading came from. WARNING, so
             // `--strict` is what refuses it.
-            if (isStubArtifactFile(file, schemaName, artifact.template, projectRoot)) {
+            // The change's own name, not a `<name>` placeholder: the message is the
+            // fix, and a placeholder makes the reader rebuild the command by hand.
+            const stub = detectStubArtifact(file, schemaName, artifact.template, projectRoot);
+            if (stub !== null) {
+                const instructions = `tospec instructions ${artifact.id} --change "${changeName}" --json`;
                 issues.push({
                     level: 'WARNING',
                     path: relPath,
-                    message: `Artifact "${artifact.id}" is still the unfilled template. Run tospec instructions ${artifact.id} --change <name> --json, then replace the file's contents.`,
+                    message: stub === 'empty'
+                        ? `Artifact "${artifact.id}" is empty. Run ${instructions}, then write the file's contents.`
+                        : `Artifact "${artifact.id}" is still the unfilled template. Run ${instructions}, then replace the file's contents.`,
                 });
                 continue;
             }
@@ -514,12 +544,13 @@ export async function validateArtifactSections(projectRoot, changeDir) {
 }
 const EMPTY_REPORT = { valid: true, issues: [], summary: { errors: 0, warnings: 0, info: 0 } };
 /**
- * Ambiguous task numbering, as WARNINGs. Task IDs are how apply refers to work,
- * so a duplicate makes that reference point at the wrong item — but the
- * numbering is a convention, not a structural requirement, so it reports rather
- * than blocks (`--strict` still refuses).
+ * Ambiguous task numbering and task lines the counter cannot see, as WARNINGs.
+ * Task IDs are how apply refers to work, so a duplicate makes that reference
+ * point at the wrong item; a `[~]` box drops out of the count, so the change
+ * reads done. Both are conventions, not structural requirements, so they report
+ * rather than block (`--strict` still refuses).
  */
-async function validateTaskNumbering(projectRoot, changeDir) {
+async function validateTaskFiles(projectRoot, changeDir) {
     const documents = [];
     for (const file of resolveTaskFiles(changeDir, projectRoot)) {
         try {
@@ -532,10 +563,10 @@ async function validateTaskNumbering(projectRoot, changeDir) {
             continue; // no tasks file yet — the artifact-status check owns that
         }
     }
-    return findTaskNumberingIssues(documents).map((issue) => ({
+    return [...findTaskNumberingIssues(documents), ...findTaskMarkerIssues(documents)].map((issue) => ({
         level: 'WARNING',
         path: issue.path,
-        line: issue.line,
+        ...(issue.line !== undefined ? { line: issue.line } : {}),
         message: issue.message,
     }));
 }
@@ -549,6 +580,13 @@ export async function validateChangeArtifacts(projectRoot, changeDir, options =
     const validator = new Validator(strict);
     const marker = readSkipSpecsMarker(changeDir);
     const markerIssues = await skipSpecsMarkerIssues(changeDir, marker);
+    // Kept apart from markerIssues: those void the skip_specs waiver below, and
+    // a misspelled sibling key or a dangling ADR link does not contradict
+    // skip_specs. Skipped for a file that does not parse: the marker already
+    // reports it, and it has no keys to name.
+    const metadataFieldIssues = marker.unreadableReason
+        ? []
+        : [...unknownMetadataKeyIssues(changeDir), ...decisionReferenceIssues(projectRoot, changeDir)];
     // A schema that cannot be resolved is the one finding: every other check
     // would run against `sdd` by default and report "no delta" about a change
     // whose real problem is the schema name. Unparseable metadata is already
@@ -556,28 +594,65 @@ export async function validateChangeArtifacts(projectRoot, changeDir, options =
     if (!marker.unreadableReason) {
         const schemaIssue = schemaResolutionIssue(projectRoot, changeDir);
         if (schemaIssue) {
-            return mergeSectionIssues(EMPTY_REPORT, [schemaIssue, ...markerIssues], strict);
+            return mergeSectionIssues(EMPTY_REPORT, [schemaIssue, ...markerIssues, ...metadataFieldIssues], strict);
         }
     }
-    // A declared marker waives the delta requirement; a *contradicted* one
-    // (declared, yet delta files exist) must not, because those files are real.
-    //
-    // Unparseable metadata waives it for the opposite reason: whether skip_specs
-    // was declared is unknowable, so "add a delta or set skip_specs" dead-ends a
-    // user who already set it inside the malformed file.
-    const requireDeltas = !marker.unreadableReason &&
-        (!marker.declared || markerIssues.length > 0) &&
-        (await deltaSpecsRequired(projectRoot, changeDir));
-    const [deltaReport, sectionIssues, numberingIssues] = await Promise.all([
-        requireDeltas
+    const requireDeltas = await requiresDeltas(projectRoot, changeDir, marker, markerIssues);
+    // The delta pass also runs for a schema that demands no delta, whenever the
+    // change has a specs/ directory: archive merges every
+    // specs/<capability>/spec.md whatever the schema says. Gated on requireDeltas
+    // alone, such a schema merged deltas nobody had checked, and a nested or
+    // dot-folder spec.md passed here while the archive backstop refused it and
+    // sent the user back to validate. requireDeltas still decides whether a
+    // delta must exist.
+    const hasSpecsDir = await fs
+        .stat(path.join(changeDir, 'specs'))
+        .then((stat) => stat.isDirectory(), () => false);
+    const [deltaReport, sectionIssues, taskFileIssues, rootDeltaIssues] = await Promise.all([
+        requireDeltas || hasSpecsDir
             ? validator.validateChangeDeltaSpecs(changeDir, path.join(projectRoot, 'tospec', 'specs'), {
                 archivePreflight,
+                requireDelta: requireDeltas,
+                sisterChanges: options.sisterChanges,
             })
             : Promise.resolve(EMPTY_REPORT),
         validateArtifactSections(projectRoot, changeDir),
-        validateTaskNumbering(projectRoot, changeDir),
+        validateTaskFiles(projectRoot, changeDir),
+        rootDeltaFileIssues(changeDir),
     ]);
-    return mergeSectionIssues(deltaReport, [...sectionIssues, ...numberingIssues, ...markerIssues], strict);
+    return mergeSectionIssues(deltaReport, [...sectionIssues, ...taskFileIssues, ...rootDeltaIssues, ...markerIssues, ...metadataFieldIssues], strict);
+}
+/**
+ * WARNING per delta written at `specs/<capability>.md`, which the merge never
+ * reads. Outside the `requireDeltas` gate on purpose: archive warns about the
+ * same list whatever the schema or skip_specs says, and validate running it
+ * only when a delta was demanded passed an issue-schema or skip_specs change
+ * that archive then flagged. WARNING, not ERROR, because a root notes file that
+ * quotes a delta header is legitimate; `--strict` still refuses it.
+ *
+ * `specs/spec.md` is left to the delta pass, which runs whatever the schema
+ * demands.
+ */
+async function rootDeltaFileIssues(changeDir) {
+    return (await findRootDeltaFiles(path.join(changeDir, 'specs'))).map((file) => {
+        const name = path.basename(file);
+        const capability = name.replace(/\.md$/i, '');
+        return {
+            level: 'WARNING',
+            path: name,
+            message: `specs/${name} holds delta sections, but a file at the specs/ root is ignored when the change is archived. Move it to specs/${capability}/spec.md.`,
+        };
+    });
+}
+/**
+ * `message` with trailing blanks dropped and ending in exactly one period.
+ * `trimEnd` strips exactly the `\s` set; the unanchored `/\.?\s*$/` it replaces
+ * retried from every position of an inner blank run, and a schema name holding
+ * 80k blanks took 2.8 s.
+ */
+export function endWithPeriod(message) {
+    const trimmed = message.trimEnd();
+    return trimmed.endsWith('.') ? trimmed : `${trimmed}.`;
 }
 /**
  * The ERROR for a change whose schema cannot be resolved (`.tospec.yaml` names
@@ -586,18 +661,31 @@ export async function validateChangeArtifacts(projectRoot, changeDir, options =
  * is wrong with the change.
  */
 function schemaResolutionIssue(projectRoot, changeDir) {
-    try {
-        resolveSchema(resolveSchemaForChange(changeDir, undefined, projectRoot), projectRoot);
+    const fault = findChangeSchemaFault(changeDir, projectRoot);
+    if (!fault)
         return null;
-    }
-    catch (error) {
-        const reason = (error instanceof Error ? error.message : String(error)).replace(/\.?\s*$/, '.');
-        return {
-            level: 'ERROR',
-            path: METADATA_FILENAME,
-            message: `${reason} Fix the schema name in ${METADATA_FILENAME} before anything else in this change can be checked.`,
-        };
-    }
+    const { error } = fault;
+    const reason = endWithPeriod(error instanceof Error ? error.message : String(error));
+    // A bad field other than `schema` fails the same read, and its message
+    // already names the fix; telling the user to fix the schema name sent them
+    // to a line that was fine.
+    // A schema.yaml that does not read or parse is the same: the name found it,
+    // and the reason already names the file at fault.
+    // A name that came from tospec/config.yaml is not in .tospec.yaml at all, so
+    // the fix names the config field, in the words `new change` uses for it.
+    const fieldAtFault = error instanceof ChangeMetadataError && !(error instanceof UnknownChangeSchemaError);
+    const fix = fault.at === 'schema-file'
+        ? 'Fix that schema file before anything else in this change can be checked.'
+        : fault.at === 'config'
+            ? `Schema '${fault.schemaName}' comes from tospec/config.yaml; fix its 'schema:' field, or set 'schema:' in ${METADATA_FILENAME}, before anything else in this change can be checked.`
+            : fieldAtFault
+                ? `Nothing else in this change can be checked until ${METADATA_FILENAME} reads.`
+                : `Fix the schema name in ${METADATA_FILENAME} before anything else in this change can be checked.`;
+    return {
+        level: 'ERROR',
+        path: METADATA_FILENAME,
+        message: `${reason} ${fix}`,
+    };
 }
 /**
  * Errors in the skip_specs declaration itself: unparseable metadata, an unusable
@@ -607,7 +695,7 @@ function schemaResolutionIssue(projectRoot, changeDir) {
  * Most-fundamental first and one at a time: a file that does not parse cannot
  * also be said to hold a wrong value.
  */
-async function skipSpecsMarkerIssues(changeDir, marker) {
+async function skipSpecsMarkerIssues(changeDir, marker, contradictingSpecs) {
     if (marker.unreadableReason) {
         return [
             {
@@ -622,27 +710,106 @@ async function skipSpecsMarkerIssues(changeDir, marker) {
             {
                 level: 'ERROR',
                 path: METADATA_FILENAME,
-                message: `Invalid ${METADATA_FILENAME}: ${marker.invalidReason} Remove the key, or set it to true only when the change genuinely has no behavioral effect.`,
+                message: `Invalid ${METADATA_FILENAME}: ${marker.invalidReason} Remove the key, or set it to true only when the user confirms this change needs no delta spec.`,
             },
         ];
     }
-    if (!marker.declared)
-        return [];
-    const specsDir = path.join(changeDir, 'specs');
-    const specFiles = await findSpecFiles(specsDir);
+    // The same list `instructions apply` warns about. rootDeltaFileIssues covers
+    // the root `specs/<cap>.md` files it leaves out.
+    const specFiles = contradictingSpecs ?? (await findSkipSpecsContradictions(changeDir, marker));
     if (specFiles.length === 0)
         return [];
-    const listed = specFiles
-        .map((file) => FileSystemUtils.toPosixPath(path.relative(specsDir, file)))
-        .join(', ');
     return [
         {
             level: 'ERROR',
             path: METADATA_FILENAME,
-            message: `skip_specs: true declares this change has no delta specs, but ${specFiles.length} spec file(s) exist: ${listed}. Drop skip_specs, or delete the spec files — never invent a requirement just to satisfy validation.`,
+            message: `skip_specs: true declares this change has no delta specs, but ${specFiles.length} spec file(s) exist: ${specFiles.join(', ')}. Drop skip_specs, or delete the spec files only when the user confirms this change needs no delta spec — never invent a requirement just to satisfy validation.`,
         },
     ];
 }
+/**
+ * WARNING per top-level `.tospec.yaml` key the schema does not know. Not an
+ * ERROR: an unknown key breaks nothing on its own, but what it was meant to
+ * carry is dropped, and `--strict` still refuses it.
+ */
+function unknownMetadataKeyIssues(changeDir) {
+    return findUnknownMetadataKeys(changeDir).map((key) => {
+        const suggestion = suggestMetadataKey(key);
+        return {
+            level: 'WARNING',
+            path: METADATA_FILENAME,
+            message: `Unknown key "${printableKey(key)}" in ${METADATA_FILENAME} is ignored` +
+                (suggestion ? ` — did you mean "${suggestion}"?` : '.') +
+                ' Keep data a tool stores for itself under an `x-` prefixed key (e.g. `x-mytool`), which tospec leaves alone.',
+        };
+    });
+}
+/**
+ * WARNING per `decisions:` value that is not a decision record filename or
+ * names no file under `tospec/decisions/` — the rules `new change --decisions`
+ * refuses by, applied to a value added by hand, which is how an ADR recorded
+ * before the change gets linked. Without it, archive turned such a value into
+ * a dead Related Decisions link.
+ *
+ * WARNING, as for an unknown key, not ERROR: archive's own use of the field is
+ * best-effort and never blocks, and a dangling link loses a reference without
+ * breaking anything the merge writes. `--strict` still refuses it.
+ */
+function decisionReferenceIssues(projectRoot, changeDir) {
+    let decisions;
+    try {
+        decisions = readChangeMetadata(changeDir, projectRoot)?.decisions;
+    }
+    catch {
+        return []; // schemaResolutionIssue reports a file that does not read
+    }
+    if (!decisions || decisions.length === 0)
+        return [];
+    const { notRecords, missing } = findDecisionReferenceProblems(projectRoot, decisions);
+    return [
+        ...notRecords.map((value) => ({
+            level: 'WARNING',
+            path: METADATA_FILENAME,
+            message: `decisions: "${printableKey(value)}" is not a decision record filename. List the bare <yyyyMMdd_HHmmss>-<topic>.md name under tospec/decisions/, without a directory part; \`tospec decision list\` shows them.`,
+        })),
+        ...missing.map((value) => ({
+            level: 'WARNING',
+            path: METADATA_FILENAME,
+            message: `decisions: "${printableKey(value)}" names no file in tospec/decisions/, so archive would link to nothing. Fix the name, or remove the entry.`,
+        })),
+    ];
+}
+/**
+ * A key as it can be shown in a message: the file is user-controlled, so a
+ * control character or escape sequence in a key must not reach the terminal.
+ */
+function printableKey(key) {
+    const cleaned = key.replace(/[\u0000-\u001f\u007f-\u009f]/g, '?');
+    return cleaned.length > 80 ? `${cleaned.slice(0, 80)}…` : cleaned;
+}
+/**
+ * Whether this change must carry a delta spec, as validate decides it. The
+ * archive backstop asks too: it picks the files it refuses by the rule
+ * validate's ERRORs follow, and a `specs/spec.md` without a delta header is
+ * one of them only where a delta is required.
+ */
+export async function changeRequiresDeltas(projectRoot, changeDir, known) {
+    // `known` is for a caller that already read both, as `instructions apply`
+    // does: optional rather than a second export, so the decision keeps one body.
+    const marker = known?.marker ?? readSkipSpecsMarker(changeDir);
+    return requiresDeltas(projectRoot, changeDir, marker, await skipSpecsMarkerIssues(changeDir, marker, known?.contradictingSpecs));
+}
+async function requiresDeltas(projectRoot, changeDir, marker, markerIssues) {
+    // A declared marker waives the delta requirement; a *contradicted* one
+    // (declared, yet delta files exist) must not, because those files are real.
+    //
+    // Unparseable metadata waives it for the opposite reason: whether skip_specs
+    // was declared is unknowable, so "add a delta or set skip_specs" dead-ends a
+    // user who already set it inside the malformed file.
+    return (!marker.unreadableReason &&
+        (!marker.declared || markerIssues.length > 0) &&
+        (await deltaSpecsRequired(projectRoot, changeDir)));
+}
 /**
  * Whether a change's schema requires at least one delta spec — a property of the
  * schema, not of the change. False when the schema declares no `specs` artifact,
@@ -702,14 +869,26 @@ function describeTemplatePath(projectRoot, schemaDir, template) {
  */
 export function formatIssueLine(issue, indent = '') {
     const prefix = issueSymbol(issue.level);
-    return `${indent}${prefix} [${issue.level}] ${issue.path}: ${issue.message}`;
+    // A message's later lines (a code frame, a scenario example) sit under its
+    // text: at the margin they read as the next finding.
+    return `${indent}${prefix} [${issue.level}] ${issue.path}: ${indentContinuation(issue.message, `${indent}    `)}`;
 }
 function summarizeType(results, type) {
     const filtered = results.filter(r => r.type === type);
     const items = filtered.length;
     const passed = filtered.filter(r => r.valid).length;
     const failed = items - passed;
-    return { items, passed, failed };
+    return { items, passed, failed, archiveRefusals: sumArchiveRefusals(filtered) };
+}
+/**
+ * Counted beside `passed` / `failed` because those cannot carry it: a refusal
+ * is a WARNING, so the item still passes and the exit code stays 0.
+ */
+function countArchiveRefusals(issues) {
+    return issues.filter((issue) => issue.code === ARCHIVE_REFUSAL_CODE).length;
+}
+function sumArchiveRefusals(results) {
+    return results.reduce((sum, res) => sum + countArchiveRefusals(res.issues), 0);
 }
 function normalizeConcurrency(value) {
     if (!value)