@seanmars/tospec 0.19.0-beta.7 → 0.20.0

package/dist/commands/validate.js

@@ -1,9 +1,11 @@
 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 { 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 { FileSystemUtils } from '../utils/file-system.js';
 import { findSpecFiles } from '../utils/spec-files.js';
@@ -15,44 +17,52 @@ 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';
+/**
+ * The one null-shape every `validate --json` failure carries, so a caller
+ * reading `result.summary.totals` never gets `undefined` from one failure path
+ * and `null` from another.
+ */
+/**
+ * The `--json` null-shape, `root` included: a root-resolution failure has none,
+ * and the sites that do resolve one spread their own over it.
+ */
+export const VALIDATE_FAILURE_PAYLOAD = { items: null, summary: null, root: null };
 export class ValidateCommand {
     async execute(itemName, options = {}) {
-        // A bulk run is the one shape that can succeed vacuously: with an implicit
-        // root it inspects a directory that is not a project, finds nothing, and
-        // reports "0 items, 0 failed" with exit 0 — a diagnostic command answering
-        // "everything is fine" about a place it never checked. Refuse the implicit
-        // root there. Named-item validation keeps it: that path fails loudly on its
-        // own when the item cannot be found, so it cannot pass vacuously.
+        // A bulk run is the one shape that can succeed vacuously: on an implicit
+        // root that is not a project it would report "0 items, 0 failed" with exit 0
+        // about a place it never checked. Named-item validation keeps the implicit
+        // root; it fails loudly instead.
         const isBulk = !!(options.all || options.changes || options.specs);
         const root = await resolveRootForCommand(options, {
             json: options.json,
-            ...(isBulk
-                ? { allowImplicitRoot: false, failurePayload: { items: null, summary: null } }
-                : {}),
+            failurePayload: VALIDATE_FAILURE_PAYLOAD,
+            ...(isBulk ? { allowImplicitRoot: false } : {}),
         });
         if (!root) {
             return;
         }
         const interactive = isInteractive(options);
-        // Handle bulk flags first
         if (isBulk) {
+            // Stderr, as `show` and `list` do for a flag their mode ignores: silently
+            // validating everything reads as a verdict on the one item named.
+            if (itemName) {
+                console.error(`Warning: Ignoring item '${itemName}'; --all/--changes/--specs validate every item.`);
+            }
             await this.runBulkValidation(root, {
                 changes: !!options.all || !!options.changes,
                 specs: !!options.all || !!options.specs,
             }, { strict: !!options.strict, json: !!options.json, concurrency: options.concurrency, noInteractive: resolveNoInteractive(options) });
             return;
         }
-        // No item and no flags
         if (!itemName) {
             if (interactive) {
                 await this.runInteractiveSelector(root, { strict: !!options.strict, json: !!options.json, concurrency: options.concurrency });
                 return;
             }
-            this.printNonInteractiveHint(root);
-            process.exitCode = 1;
+            this.reportNothingToValidate(root, !!options.json);
             return;
         }
-        // Direct item validation with type detection or override
         const typeOverride = this.normalizeType(options.type);
         await this.validateDirectItem(root, itemName, { typeOverride, strict: !!options.strict, json: !!options.json });
     }
@@ -65,11 +75,9 @@ export class ValidateCommand {
         return undefined;
     }
     /**
-     * Resolve change IDs by directory existence within the resolved root — the
-     * same rule `tospec status`/`instructions` use (`getAvailableChanges`) —
-     * rather than requiring `proposal.md`. This lets `validate` resolve a
-     * scaffolded or still-authoring change that the sibling commands already
-     * resolve (#1182). Sorted to preserve the prior `getActiveChangeIds` ordering.
+     * Change IDs by directory existence — the same rule `status` and
+     * `instructions` use — rather than by `proposal.md`, so a scaffolded change
+     * resolves here too.
      */
     async listChangeIds(root) {
         const ids = await getAvailableChanges(root.path, root.changesDir);
@@ -92,7 +100,6 @@ export class ValidateCommand {
             return this.runBulkValidation(root, { changes: true, specs: false }, opts);
         if (choice === 'specs')
             return this.runBulkValidation(root, { changes: false, specs: true }, opts);
-        // one
         const [changes, specs] = await Promise.all([this.listChangeIds(root), getSpecIds(root.path)]);
         const items = [];
         items.push(...changes.map(id => ({ name: `change/${id}`, value: { type: 'change', id } })));
@@ -105,26 +112,70 @@ export class ValidateCommand {
         const picked = await select({ message: 'Pick an item', choices: items });
         await this.validateByType(root, picked.type, picked.id, opts);
     }
-    printNonInteractiveHint(root) {
+    /**
+     * Nothing named and no terminal to ask in. `no_item_specified` is the code
+     * `show` uses for the same situation.
+     */
+    reportNothingToValidate(root, json) {
+        const fix = [
+            'tospec validate --all',
+            'tospec validate --changes',
+            'tospec validate --specs',
+            'tospec validate <item-name>',
+        ];
+        if (json) {
+            emitFailureStatus({ ...VALIDATE_FAILURE_PAYLOAD, root: toRootOutput(root) }, {
+                severity: 'error',
+                code: 'no_item_specified',
+                message: 'Nothing to validate.',
+                fix: fix.join('\n'),
+            });
+            return;
+        }
         console.error('Nothing to validate. Try one of:');
-        console.error(`  ${'tospec validate --all'}`);
-        console.error(`  ${'tospec validate --changes'}`);
-        console.error(`  ${'tospec validate --specs'}`);
-        console.error(`  ${'tospec validate <item-name>'}`);
+        for (const line of fix)
+            console.error(`  ${line}`);
         console.error('Or run in an interactive terminal.');
+        process.exitCode = 1;
     }
     async validateDirectItem(root, itemName, opts) {
         const [changes, specs] = await Promise.all([this.listChangeIds(root), getSpecIds(root.path)]);
         const isChange = changes.includes(itemName);
         const isSpec = specs.includes(itemName);
-        const type = opts.typeOverride ?? (isChange ? 'change' : isSpec ? 'spec' : undefined);
+        let type = opts.typeOverride;
         if (!type) {
-            const suggestions = nearestMatches(itemName, [...changes, ...specs]);
+            if (isChange)
+                type = 'change';
+            else if (isSpec)
+                type = 'spec';
+        }
+        // An explicit --type names a kind the item is not: say that, rather than
+        // letting the read fail with the ENOENT of a path the caller never typed.
+        if (opts.typeOverride && !(opts.typeOverride === 'change' ? isChange : isSpec)) {
+            const location = opts.typeOverride === 'change'
+                ? path.join(root.changesDir, itemName)
+                : path.join(root.specsDir, itemName, 'spec.md');
+            const otherKind = opts.typeOverride === 'change' ? (isSpec ? 'spec' : undefined) : isChange ? 'change' : undefined;
+            const message = `${opts.typeOverride === 'change' ? 'Change' : 'Spec'} '${itemName}' not found at ${location}.` +
+                (otherKind ? ` A ${otherKind} with that name exists: pass --type ${otherKind}.` : '');
+            if (opts.json) {
+                emitFailureStatus({ ...VALIDATE_FAILURE_PAYLOAD, root: toRootOutput(root) }, { severity: 'error', code: 'unknown_item', message });
+            }
+            else {
+                console.error(message);
+                process.exitCode = 1;
+            }
+            return;
+        }
+        if (!type) {
+            // Deduplicated: a name that is both a change and a spec would otherwise
+            // be suggested twice.
+            const suggestions = nearestMatches(itemName, [...new Set([...changes, ...specs])]);
             const message = suggestions.length
                 ? `Unknown item '${itemName}'. Did you mean: ${suggestions.join(', ')}?`
                 : `Unknown item '${itemName}'.`;
             if (opts.json) {
-                emitFailureStatus({ items: null, root: toRootOutput(root) }, { severity: 'error', code: 'unknown_item', message });
+                emitFailureStatus({ ...VALIDATE_FAILURE_PAYLOAD, root: toRootOutput(root) }, { severity: 'error', code: 'unknown_item', message });
             }
             else {
                 console.error(message);
@@ -134,7 +185,7 @@ export class ValidateCommand {
         }
         if (!opts.typeOverride && isChange && isSpec) {
             if (opts.json) {
-                emitFailureStatus({ items: null, root: toRootOutput(root) }, {
+                emitFailureStatus({ ...VALIDATE_FAILURE_PAYLOAD, root: toRootOutput(root) }, {
                     severity: 'error',
                     code: 'ambiguous_item',
                     message: `Ambiguous item '${itemName}' matches both a change and a spec.`,
@@ -156,8 +207,7 @@ export class ValidateCommand {
             const start = Date.now();
             const report = await validateChangeArtifacts(root.path, changeDir, { strict: opts.strict });
             const durationMs = Date.now() - start;
-            this.printReport('change', id, report, durationMs, opts.json, root);
-            // Non-zero exit if invalid (keeps enriched output test semantics)
+            this.printReport('change', id, report, durationMs, opts.json, root, opts.strict);
             process.exitCode = report.valid ? 0 : 1;
             return;
         }
@@ -165,13 +215,22 @@ export class ValidateCommand {
         const start = Date.now();
         const report = await validator.validateSpec(file);
         const durationMs = Date.now() - start;
-        this.printReport('spec', id, report, durationMs, opts.json, root);
+        this.printReport('spec', id, report, durationMs, opts.json, root, opts.strict);
         process.exitCode = report.valid ? 0 : 1;
     }
-    printReport(type, id, report, durationMs, json, root) {
+    printReport(type, id, report, durationMs, json, root, strict = false) {
         if (json) {
             emitSuccess({
-                items: [{ id, type, valid: report.valid, issues: report.issues, durationMs }],
+                items: [
+                    {
+                        id,
+                        type,
+                        valid: report.valid,
+                        issues: report.issues,
+                        ...(report.notes?.length ? { notes: report.notes } : {}),
+                        durationMs,
+                    },
+                ],
                 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 } } },
             }, toRootOutput(root));
             return;
@@ -182,51 +241,65 @@ export class ValidateCommand {
         else {
             console.error(`${type === 'change' ? 'Change' : 'Specification'} '${id}' has issues`);
         }
-        // Outside the verdict branch on purpose. Three checks are deliberately
-        // WARNINGs so the run keeps passing while the author still learns about them
-        // (missing normative keyword, placeholder Purpose, ambiguous task numbering).
-        // Printing only on failure made every one of them invisible outside --json,
-        // which implements the downgrade as a deletion.
-        //
-        // Routed with the verdict, though: on stderr they make a passing run look
-        // failed to anything that reads the stream as an error channel — a hook, a
-        // CI step, an agent — which is the same deletion by a different route, this
-        // time with a false alarm attached. Exit 0 leaves stderr empty.
+        // Printed whatever the verdict: several checks are WARNINGs so a run keeps
+        // passing while the author still learns about them. Routed *with* the
+        // verdict, so a passing run leaves stderr empty for hooks and CI.
         const writeIssue = report.valid ? console.log : console.error;
         for (const issue of report.issues) {
             writeIssue(formatIssueLine(issue));
         }
-        // Still failure-only: a passing item has no next step to take.
+        // Once each: a note explains the rule, which is the same however many lines
+        // tripped it.
+        for (const note of report.notes ?? []) {
+            writeIssue(`Note: ${note}`);
+        }
+        // Failure-only: a passing item has no next step to take.
         if (!report.valid) {
-            this.printNextSteps(type, id, root, report.issues);
+            this.printNextSteps(type, id, root, report.issues, strict);
         }
     }
     /**
-     * Derives hints from what actually failed rather than the item type alone —
-     * every failing change used to get the same three delta hints, so a change
-     * whose only problem was e.g. a missing design.md section was told to check
-     * its delta headers instead.
+     * Hints derived from what actually failed, not from the item type, so a
+     * change whose only problem is a missing design.md section is not told to
+     * check delta headers.
      *
-     * These three hints are about delta *content* (headers, scenarios, parsing),
-     * so they apply to an issue reported against a delta file itself: the delta
-     * validator reports those under `<capability>/spec.md`, relative to the
-     * change's specs/ dir. Three neighbouring shapes deliberately do not qualify,
-     * and the leading slash is what excludes the first two:
-     *   - a misnamed file in a capability folder (`auth/extra.md`) and a delta at
-     *     the specs/ root (`spec.md`) are placement errors; each message already
-     *     names the exact path to rename to, so the generic bullets would be
-     *     advice for a different failure;
-     *   - the whole-change `file` sentinel ("No deltas found") already embeds
-     *     these same three tips via `enrichTopLevelError`.
+     * The delta hints are about delta *content*, so they match only an issue
+     * reported under `<capability>/spec.md`. The leading slash excludes a misnamed
+     * file and a delta at the specs/ root — placement errors whose messages
+     * already name the path to rename to — and the whole-change `file` sentinel,
+     * which `enrichTopLevelError` already covers.
      */
-    printNextSteps(type, id, root, issues) {
+    printNextSteps(type, id, root, issues, strict) {
         const bullets = [];
         if (type === 'change') {
-            const hasDeltaIssue = issues.some((issue) => issue.path.endsWith('/spec.md'));
-            if (hasDeltaIssue) {
+            // 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.
+            const deltaIssues = issues.filter((issue) => issue.path.endsWith('/spec.md'));
+            const mentions = (pattern) => deltaIssues.some((issue) => pattern.test(issue.message));
+            if (mentions(/delta header|No deltas found|not a delta|## ADDED/i)) {
                 bullets.push('- Ensure change has deltas in specs/: use headers ## ADDED/MODIFIED/REMOVED/RENAMED Requirements');
+            }
+            if (mentions(/#### Scenario:/)) {
                 bullets.push('- Each requirement MUST include at least one #### Scenario: block');
-                bullets.push(`- Debug parsed deltas: ${`tospec show ${id} --json --deltas-only`}`);
+            }
+            if (mentions(/omits scenario/)) {
+                bullets.push('- Restate every scenario the current spec still has in the MODIFIED block, or declare the removal under ## REMOVED Scenarios (- Requirement: `<name>` / - Scenario: `<name>` / - Reason: ...)');
+            }
+            if (mentions(/Migration field/)) {
+                bullets.push('- Add a **Migration** field to each REMOVED requirement');
+            }
+            if (mentions(/SHALL or MUST/)) {
+                // The keyword check is English-only, and the way out for a non-English
+                // spec is to drop --strict — advice that only makes sense when it is on.
+                bullets.push(strict
+                    ? '- State the obligation with SHALL or MUST in the requirement body (or run without --strict for non-English specs)'
+                    : '- State the obligation with SHALL or MUST in the requirement body');
+            }
+            // Only a delta issue that failed the run: a WARNING on an otherwise valid
+            // delta (a missing Purpose, say) is not something `show --json` explains.
+            if (deltaIssues.some((issue) => issue.level === 'ERROR' || strict)) {
+                bullets.push(`- Debug parsed deltas: ${`tospec show ${id} --json`}`);
             }
             const hasMissingSection = issues.some((issue) => issue.message.startsWith('Missing required section'));
             if (hasMissingSection) {
@@ -238,8 +311,7 @@ export class ValidateCommand {
             bullets.push('- Each requirement MUST include at least one #### Scenario: block');
             bullets.push('- Re-run with --json to see structured report');
         }
-        // No specific hint applies: printing the old generic three bullets would
-        // be advice for a different failure, so print nothing instead.
+        // Nothing applies: generic bullets would be advice for a different failure.
         if (bullets.length === 0)
             return;
         console.error('Next steps:');
@@ -255,7 +327,7 @@ export class ValidateCommand {
         const concurrency = normalizeConcurrency(opts.concurrency) ?? normalizeConcurrency(process.env.TOSPEC_CONCURRENCY) ?? DEFAULT_CONCURRENCY;
         const validator = new Validator(opts.strict);
         // Each entry carries its own id/type so a rejected task can be reported
-        // without re-deriving them from its queue position.
+        // without re-deriving them from its position.
         const queue = [];
         for (const id of changeIds) {
             queue.push({
@@ -266,7 +338,7 @@ export class ValidateCommand {
                     const changeDir = path.join(root.changesDir, id);
                     const report = await validateChangeArtifacts(root.path, changeDir, { strict: opts.strict });
                     const durationMs = Date.now() - start;
-                    return { id, type: 'change', valid: report.valid, issues: report.issues, durationMs };
+                    return { id, type: 'change', valid: report.valid, issues: report.issues, notes: report.notes, durationMs };
                 },
             });
         }
@@ -279,7 +351,7 @@ export class ValidateCommand {
                     const file = path.join(root.specsDir, id, 'spec.md');
                     const report = await validator.validateSpec(file);
                     const durationMs = Date.now() - start;
-                    return { id, type: 'spec', valid: report.valid, issues: report.issues, durationMs };
+                    return { id, type: 'spec', valid: report.valid, issues: report.issues, notes: report.notes, durationMs };
                 },
             });
         }
@@ -338,8 +410,8 @@ export class ValidateCommand {
             next();
         });
         results.sort((a, b) => a.id.localeCompare(b.id));
-        // Derived from results rather than counted alongside them: two tallies that
-        // must agree is one more thing to keep in sync.
+        // Derived from results rather than counted alongside them, so the two
+        // cannot disagree.
         const passed = results.filter((res) => res.valid).length;
         const failed = results.length - passed;
         const summary = {
@@ -349,8 +421,11 @@ export class ValidateCommand {
                 ...(scope.specs ? { spec: summarizeType(results, 'spec') } : {}),
             },
         };
+        // 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);
         if (opts.json) {
-            emitSuccess({ items: results, summary }, toRootOutput(root));
+            emitSuccess({ items, summary, ...(runNotes.length ? { notes: runNotes } : {}) }, toRootOutput(root));
         }
         else {
             for (const res of results) {
@@ -358,31 +433,35 @@ export class ValidateCommand {
                     console.log(`✓ ${res.type}/${res.id}`);
                 else
                     console.error(`✗ ${res.type}/${res.id}`);
-                // Indented under the item that produced them: a bulk run printing one
-                // tick per line leaves a finding on a *passing* item with no subject,
-                // and the `Details:` hint below only ever names a failure. Each item's
-                // findings follow its own verdict onto the same stream, so a run where
-                // everything passes writes nothing to stderr.
+                // Routed with the item's own verdict, so a run where everything passes
+                // writes nothing to stderr.
                 const writeIssue = res.valid ? console.log : console.error;
                 for (const issue of res.issues) {
                     writeIssue(formatIssueLine(issue, '  '));
                 }
             }
+            for (const note of runNotes) {
+                console.log(`Note: ${note}`);
+            }
             console.log(`Totals: ${summary.totals.passed} passed, ${summary.totals.failed} failed (${summary.totals.items} items)`);
-            const firstFailure = results.find((res) => !res.valid);
-            if (firstFailure) {
-                console.log(`Details: tospec validate ${firstFailure.id} --type ${firstFailure.type}`);
+            // One line per failed item: naming only the first left the rest without
+            // a command to rerun.
+            const failures = results.filter((res) => !res.valid);
+            if (failures.length > 0) {
+                console.log('Details:');
+                for (const failure of failures) {
+                    console.log(`  tospec validate ${failure.id} --type ${failure.type}`);
+                }
             }
         }
         process.exitCode = failed > 0 ? 1 : 0;
     }
 }
 /**
- * Validates schema-declared `requiredSections` for ticket/design/task-style
- * artifacts that have no Requirement grammar of their own. Only artifacts
- * that (a) declare a `validation` block and (b) already have an output file
- * on disk are checked — artifacts not yet produced are `status`'s concern,
- * not validate's.
+ * Validates schema-declared `requiredSections` for artifacts with no Requirement
+ * grammar of their own. Only artifacts that declare a `validation` block and
+ * already have an output file are checked — one not yet produced is `status`'s
+ * concern, not validate's.
  */
 export async function validateArtifactSections(projectRoot, changeDir) {
     const issues = [];
@@ -397,17 +476,27 @@ export async function validateArtifactSections(projectRoot, changeDir) {
     }
     const schemaDir = getSchemaDir(schemaName, projectRoot);
     for (const artifact of schema.artifacts) {
-        if (!artifact.validation)
-            continue;
         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)) {
+                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.`,
+                });
+                continue;
+            }
+            if (!artifact.validation)
+                continue;
             let content;
             try {
                 content = await fs.readFile(file, 'utf-8');
             }
             catch (error) {
-                // File vanished between discovery and read (race) — report it as a
-                // per-file error instead of crashing the whole command.
+                // Vanished between discovery and read: a per-file error, not a crash.
                 issues.push({
                     level: 'ERROR',
                     path: relPath,
@@ -416,7 +505,7 @@ export async function validateArtifactSections(projectRoot, changeDir) {
                 continue;
             }
             const templateRef = schemaDir
-                ? FileSystemUtils.toPosixPath(path.join(path.relative(projectRoot, schemaDir), 'templates', artifact.template))
+                ? describeTemplatePath(projectRoot, schemaDir, artifact.template)
                 : undefined;
             issues.push(...validateSections(content, artifact.validation, { path: relPath, templateRef }));
         }
@@ -426,9 +515,9 @@ 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 or a mismatched group 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).
+ * 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).
  */
 async function validateTaskNumbering(projectRoot, changeDir) {
     const documents = [];
@@ -451,11 +540,8 @@ async function validateTaskNumbering(projectRoot, changeDir) {
     }));
 }
 /**
- * The single validation pipeline for a change — used verbatim by both
- * `tospec validate` and `tospec archive`, so their rule sets and severities
- * can never disagree ("validate green but archive blocked" is structurally
- * impossible). Runs delta-spec validation (when the schema requires deltas
- * or the change produced any) plus schema-declared section validation.
+ * The single validation pipeline for a change, used verbatim by `validate` and
+ * `archive`, so "validate green but archive blocked" is structurally impossible.
  */
 export async function validateChangeArtifacts(projectRoot, changeDir, options = {}) {
     const strict = options.strict ?? false;
@@ -463,11 +549,24 @@ export async function validateChangeArtifacts(projectRoot, changeDir, options =
     const validator = new Validator(strict);
     const marker = readSkipSpecsMarker(changeDir);
     const markerIssues = await skipSpecsMarkerIssues(changeDir, marker);
-    // A declared marker waives the delta requirement — that is its whole job.
-    // A *contradicted* marker (declared, but delta files present) must not: the
-    // files are real and reporting only the contradiction would hide anything
-    // else wrong with them.
-    const requireDeltas = (!marker.declared || markerIssues.length > 0) &&
+    // 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
+    // reported by the marker, and the schema cannot be read out of it either.
+    if (!marker.unreadableReason) {
+        const schemaIssue = schemaResolutionIssue(projectRoot, changeDir);
+        if (schemaIssue) {
+            return mergeSectionIssues(EMPTY_REPORT, [schemaIssue, ...markerIssues], 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
@@ -481,12 +580,43 @@ export async function validateChangeArtifacts(projectRoot, changeDir, options =
     return mergeSectionIssues(deltaReport, [...sectionIssues, ...numberingIssues, ...markerIssues], strict);
 }
 /**
- * Errors in the skip_specs declaration itself: an unusable value, or a change
- * claiming it has no specs while carrying delta files. Both are contradictions
- * the user has to resolve — silently picking one reading would let a change
- * archive under an assumption its own contents deny.
+ * The ERROR for a change whose schema cannot be resolved (`.tospec.yaml` names
+ * one that does not exist, or the schema file itself is broken), or null.
+ * Same message `list` and `status` give, so the three commands agree on what
+ * is wrong with the change.
+ */
+function schemaResolutionIssue(projectRoot, changeDir) {
+    try {
+        resolveSchema(resolveSchemaForChange(changeDir, undefined, projectRoot), projectRoot);
+        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.`,
+        };
+    }
+}
+/**
+ * Errors in the skip_specs declaration itself: unparseable metadata, an unusable
+ * value, or a change claiming no specs while carrying delta files. Each is a
+ * contradiction the user has to resolve.
+ *
+ * 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) {
+    if (marker.unreadableReason) {
+        return [
+            {
+                level: 'ERROR',
+                path: METADATA_FILENAME,
+                message: `Invalid YAML in ${METADATA_FILENAME}: ${marker.unreadableReason} Nothing in this file can be read until it parses — including \`skip_specs\`, so no other check about it means anything yet.`,
+            },
+        ];
+    }
     if (marker.invalidReason) {
         return [
             {
@@ -515,13 +645,9 @@ async function skipSpecsMarkerIssues(changeDir, marker) {
 }
 /**
  * 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, and when it declares one as
- * `optional` and this change produced none. A pure fix with no behavioral change
- * (e.g. an issue schema change) is a legitimate, complete change, not a
- * validation failure. Falls back to requiring deltas (the stricter, pre-existing
- * behavior) when the schema can't be resolved.
+ * schema, not of the change. False when the schema declares no `specs` artifact,
+ * or declares it `optional` and this change produced none: a pure fix with no
+ * behavioral change is a complete change, not a validation failure.
  */
 export async function deltaSpecsRequired(projectRoot, changeDir) {
     let schemaName;
@@ -531,16 +657,14 @@ export async function deltaSpecsRequired(projectRoot, changeDir) {
         schema = resolveSchema(schemaName, projectRoot);
     }
     catch {
-        // Nothing is known about what this schema can produce, so demand the delta:
-        // failing loudly beats passing a change nobody examined. Deliberately NOT
-        // the same answer as the branch below, which is why it stays its own exit.
+        // Nothing is known about what this schema produces, so demand the delta:
+        // failing loudly beats passing a change nobody examined. The opposite
+        // answer from the `!specsArtifact` branch below, deliberately.
         return true;
     }
     const specsArtifact = schema.artifacts.find((a) => a.id === 'specs');
-    // The schema told us what it produces and deltas were not on the list. Asking
-    // for one is unsatisfiable — the file it names is not an artifact of this
-    // schema, so it never appears in `status` and no instruction ever writes it —
-    // and an unsatisfiable error is a dead end, not a rule.
+    // Deltas are not on this schema's list, so asking for one is unsatisfiable:
+    // the file never appears in `status` and no instruction ever writes it.
     if (!specsArtifact)
         return false;
     if (!specsArtifact.optional)
@@ -558,15 +682,24 @@ export function mergeSectionIssues(report, extra, strict) {
     return { valid, issues, summary: { errors, warnings, info } };
 }
 /**
- * One rendering of a finding for every human surface.
- *
- * The named-item and bulk paths print the same three fields and differ only by
- * indentation. This change exists because two renderings of the same data were
- * allowed to disagree; leaving the line format duplicated would reproduce that
- * the next time a field is added.
+ * Where to find an artifact's template, in whichever form is openable: relative
+ * to the project root when the schema lives inside it, absolute otherwise.
+ * `path.relative` on a packaged schema produces routes *out* of the project that
+ * say nothing about what they are relative to. Absolute also matches what
+ * `tospec templates --json` answers.
+ */
+function describeTemplatePath(projectRoot, schemaDir, template) {
+    const absolute = path.join(schemaDir, 'templates', template);
+    const relative = path.relative(projectRoot, absolute);
+    const insideProject = relative !== '' && !relative.startsWith('..') && !path.isAbsolute(relative);
+    return FileSystemUtils.toPosixPath(insideProject ? relative : absolute);
+}
+/**
+ * One rendering of a finding for every human surface. The named-item and bulk
+ * paths print the same three fields and differ only by indentation.
  */
 export function formatIssueLine(issue, indent = '') {
-    const prefix = issue.level === 'ERROR' ? '✗' : issue.level === 'WARNING' ? '⚠' : 'ℹ';
+    const prefix = issueSymbol(issue.level);
     return `${indent}${prefix} [${issue.level}] ${issue.path}: ${issue.message}`;
 }
 function summarizeType(results, type) {