@fission-ai/openspec 1.13.0 → 1.13.2

package/dist/core/validation/task-checkboxes.d.ts

@@ -0,0 +1,34 @@
+export interface TaskCheckboxDocument {
+    path: string;
+    content: string;
+}
+export interface TaskCheckboxIssue {
+    path: string;
+    line: number;
+    message: string;
+}
+/**
+ * Reports tracked task files that list work as plain bullets or numbered items
+ * instead of checkboxes (#354).
+ *
+ * Progress counts checkboxes and nothing else, so a tasks file written as a
+ * bare list is worse than an empty one: `openspec list` prints "No tasks",
+ * `openspec status` treats the change as having no work left, and
+ * `openspec archive` has no incomplete task to warn about. The file looks
+ * finished to the tool and unfinished to the reader.
+ *
+ * Reported only when the change's *whole* tracked set has zero checkboxes.
+ * One nested tasks file of prose beside a real checklist is not the failure
+ * this catches, and a change that is mid-authoring keeps its progress the
+ * moment a single checkbox exists.
+ *
+ * The scan for the offending line looks at rendered content only: fenced
+ * blocks, HTML comments, YAML front matter and top-level indented code are
+ * skipped. Every one of those
+ * exclusions can only *silence* a warning, never drop a real task — that is the
+ * opposite trade from the task parser, where fence awareness would hide work
+ * that `archive` must still refuse, and it is why the parser stays literal
+ * while this scan does not.
+ */
+export declare function findMissingTaskCheckboxIssues(documents: readonly TaskCheckboxDocument[]): TaskCheckboxIssue[];
+//# sourceMappingURL=task-checkboxes.d.ts.map

package/dist/core/validation/task-checkboxes.js

@@ -0,0 +1,181 @@
+import { parseTaskLines } from '../../utils/task-progress.js';
+/**
+ * A list item that carries text but no checkbox: `- item`, `* item`, `+ item`,
+ * `1. item`, `1) item`. Checkbox lines match this too, so callers must rule the
+ * document set out on checkbox count first.
+ *
+ * Matches at any indent; the caller decides how deep is too deep. See
+ * `CODE_BLOCK_COLUMN`.
+ *
+ * A thematic break (`---`, `***`, `- - -`) is not a list item: the run has no
+ * text after it, and this pattern requires a non-space character. `* * *` is
+ * the one break spelled like a list of `*` items, and it is accepted as a list
+ * item rather than special-cased, because a file whose only list-shaped line is
+ * a horizontal rule still has zero tasks — the warning stays true, it just
+ * points at an odd line.
+ *
+ * An ordered marker runs at most nine digits, as CommonMark and the scenario
+ * bullet pattern in `specs-apply.ts` both require.
+ */
+const LIST_ITEM = /^\s*(?:[-*+]|\d{1,9}[.)])\s+\S/;
+/**
+ * The indent at which a top-level line stops being content and becomes an
+ * indented code block, per CommonMark.
+ *
+ * The fence logic already treats four spaces as code; the list scan did not,
+ * so a sample of terminal output written as `    - example output` was
+ * reported as an uncheckboxed task list, and under `--strict` that false
+ * positive failed validation on a correct file.
+ *
+ * Genuine nested lists survive the cut, because this scan reports the *first*
+ * list item it finds and a nested item always sits under a shallower parent.
+ * That parent is what gets reported, exactly as before. A list-shaped line
+ * four columns deep with no shallower item above it is not nested under
+ * anything, which is precisely what makes it code.
+ */
+const CODE_BLOCK_COLUMN = 4;
+/** Leading whitespace of a line in visual columns, a tab counting as four. */
+function indentColumns(line) {
+    let column = 0;
+    for (const char of line) {
+        if (char === ' ')
+            column += 1;
+        else if (char === '\t')
+            column += CODE_BLOCK_COLUMN - (column % CODE_BLOCK_COLUMN);
+        else
+            break;
+    }
+    return column;
+}
+/**
+ * A fenced block delimiter: a run of three or more backticks or tildes, plus
+ * whatever follows it on the line (an info string on an opener, nothing on a
+ * valid closer).
+ *
+ * Indented by at most three spaces, as CommonMark requires: at four, the line is
+ * an indented code block rather than a fence, and treating it as an opener would
+ * leave the scan inside a block that never began and hide every list below it.
+ *
+ * Deliberately unanchored at the end: `.` does not match `\r`, so `(.*)$` would
+ * fail on every line of a CRLF file and blind the scan to fences entirely.
+ */
+const FENCE = /^ {0,3}(`{3,}|~{3,})(.*)/;
+/**
+ * The YAML front-matter delimiter: exactly three dashes. A longer run is a
+ * thematic break, so `----` must not open a block that swallows the list under
+ * it until the next `---`.
+ */
+const FRONT_MATTER = /^-{3}\s*$/;
+const COMMENT_OPEN = '<!--';
+const COMMENT_CLOSE = '-->';
+/**
+ * Reports tracked task files that list work as plain bullets or numbered items
+ * instead of checkboxes (#354).
+ *
+ * Progress counts checkboxes and nothing else, so a tasks file written as a
+ * bare list is worse than an empty one: `openspec list` prints "No tasks",
+ * `openspec status` treats the change as having no work left, and
+ * `openspec archive` has no incomplete task to warn about. The file looks
+ * finished to the tool and unfinished to the reader.
+ *
+ * Reported only when the change's *whole* tracked set has zero checkboxes.
+ * One nested tasks file of prose beside a real checklist is not the failure
+ * this catches, and a change that is mid-authoring keeps its progress the
+ * moment a single checkbox exists.
+ *
+ * The scan for the offending line looks at rendered content only: fenced
+ * blocks, HTML comments, YAML front matter and top-level indented code are
+ * skipped. Every one of those
+ * exclusions can only *silence* a warning, never drop a real task — that is the
+ * opposite trade from the task parser, where fence awareness would hide work
+ * that `archive` must still refuse, and it is why the parser stays literal
+ * while this scan does not.
+ */
+export function findMissingTaskCheckboxIssues(documents) {
+    if (documents.length === 0)
+        return [];
+    if (documents.some((document) => parseTaskLines(document.content).length > 0))
+        return [];
+    const issues = [];
+    for (const document of documents) {
+        const line = findFirstListItemLine(document.content);
+        if (line === undefined)
+            continue;
+        issues.push({
+            path: document.path,
+            line,
+            message: 'This change counts as 0 tasks: no line in its tracked task files is a checkbox, ' +
+                'so "openspec list" and "openspec status" report no work and "openspec archive" ' +
+                'has nothing to flag as incomplete. Write each task as "- [ ] 1.1 Description".',
+        });
+    }
+    return issues;
+}
+/** 1-based line of the first list item in rendered content, if any. */
+function findFirstListItemLine(content) {
+    const lines = content.split('\n');
+    let openFence;
+    let inComment = false;
+    let index = skipFrontMatter(lines);
+    for (; index < lines.length; index++) {
+        const line = lines[index];
+        if (inComment) {
+            if (line.includes(COMMENT_CLOSE))
+                inComment = false;
+            continue;
+        }
+        const fence = line.match(FENCE);
+        if (fence) {
+            const marker = fence[1][0];
+            const length = fence[1].length;
+            if (openFence === undefined) {
+                openFence = { marker, length };
+            }
+            else if (marker === openFence.marker &&
+                length >= openFence.length &&
+                fence[2].trim() === '') {
+                // CommonMark: a closer matches its opener's character, runs at least as
+                // long, and carries no info string. A shorter or annotated run inside a
+                // block is content, so a ```` ``` ```` sample nested in a ```` ```` ````
+                // block does not end the block early and expose its bullets.
+                openFence = undefined;
+            }
+            continue;
+        }
+        if (openFence !== undefined)
+            continue;
+        // Only a comment that opens the line hides it. `- [ ] 1.1 do it <!-- note`
+        // is a task line first, and the template's own `## 1. <!-- Task Group -->`
+        // must not swallow the checklist that follows it.
+        if (line.trimStart().startsWith(COMMENT_OPEN)) {
+            if (!line.includes(COMMENT_CLOSE, line.indexOf(COMMENT_OPEN) + COMMENT_OPEN.length)) {
+                inComment = true;
+            }
+            continue;
+        }
+        if (LIST_ITEM.test(line) && indentColumns(line) < CODE_BLOCK_COLUMN)
+            return index + 1;
+    }
+    return undefined;
+}
+/**
+ * Index of the first line after a YAML front-matter block, or 0 when the
+ * document does not open with one. A list under `tags:` is metadata about the
+ * file, never the work it tracks, and pointing a "write checkboxes" warning at
+ * it would name the wrong line.
+ */
+function skipFrontMatter(lines) {
+    // A UTF-8 BOM, prepended by Windows editors and PowerShell redirects, would
+    // otherwise hide the opener and expose a `tags:` list to the scan.
+    if (lines.length === 0 || !FRONT_MATTER.test(lines[0].replace(/^/, '').trimEnd())) {
+        return 0;
+    }
+    for (let index = 1; index < lines.length; index++) {
+        if (FRONT_MATTER.test(lines[index].trimEnd()))
+            return index + 1;
+    }
+    // An unterminated opener is a thematic break, not front matter: rewinding to
+    // the top keeps every list in the document visible to the scan.
+    return 0;
+}
+//# sourceMappingURL=task-checkboxes.js.map

package/dist/core/validation/validator.d.ts

@@ -29,7 +29,53 @@ export declare class Validator {
         mainSpecsDir?: string;
         projectRoot?: string;
     }): Promise<ValidationReport>;
-    private collectTaskNumberingIssues;
+    /**
+     * Lints the change's task files.
+     *
+     * Two checks with deliberately different reach. Checkbox formatting is read
+     * from whatever the change's own schema declares as its tracked task output,
+     * because every schema's progress, apply and archive behavior is computed by
+     * counting checkboxes in exactly those files. Numbering stays scoped to the
+     * built-in `spec-driven` schema, whose template is the one that numbers tasks
+     * in the first place.
+     *
+     * The checkbox check never falls back to a bare top-level `tasks.md`: a file
+     * no artifact declares is not a tracked task list, and warning about its
+     * formatting would be a guess about a file the tool does not read.
+     */
+    private collectTaskFileIssues;
+    /**
+     * Reads task files into change-relative documents, counting the ones that
+     * exist but could not be read. A file that is simply absent is not counted:
+     * the resolver only returns files it found, so the remaining read failures
+     * are permissions and I/O, and a check that reasons over the whole set needs
+     * to know its evidence was incomplete.
+     */
+    private readTaskDocuments;
+    /**
+     * Names a task file relative to its change, POSIX-separated.
+     *
+     * Both sides are canonicalized first. `resolveArtifactOutputs` hands back real
+     * paths, while `changeDir` carries whatever spelling the caller resolved, and
+     * the two can differ without being apart: on Windows a short 8.3 alias
+     * (`RUNNER~1`) against its expanded form turned `tasks.md` into a
+     * `../../../..`-prefixed absolute path in the report, and a symlinked project
+     * directory does the same elsewhere. Canonicalizing recovers the real
+     * relationship. The Windows CI job is the regression guard — the mismatch
+     * cannot be staged on POSIX, where the spawned CLI's `process.cwd()` is
+     * already physical.
+     *
+     * A path that still escapes would be a resolver bug rather than a spelling
+     * difference, but the report must never leak an absolute filesystem path, so
+     * the file name stands in.
+     */
+    private taskDocumentPath;
+    /**
+     * True when the change resolves to the package's own `spec-driven` schema. A
+     * project schema that merely reuses the name is not it, so checks written
+     * against the built-in template never fire on someone else's task format.
+     */
+    private usesBuiltInSpecDrivenSchema;
     /**
      * Report MODIFIED requirements whose block omits a scenario the main spec
      * still carries. Uses the same comparison archive applies, so validate can
@@ -72,6 +118,12 @@ export declare class Validator {
      */
     private buildMissingShallOrMustMessage;
     private countScenarios;
+    /**
+     * Why a requirement with a visible scenario header still has no scenario:
+     * the header has no body, and the spec path archive validates against does
+     * not count it. Empty when the block has no bare scenario header.
+     */
+    private emptyScenarioHint;
     private formatSectionList;
 }
 //# sourceMappingURL=validator.d.ts.map

package/dist/core/validation/validator.js

@@ -5,14 +5,15 @@ import { MarkdownParser } from '../parsers/markdown-parser.js';
 import { ChangeParser } from '../parsers/change-parser.js';
 import { findSpecUpdates, buildUpdatedSpec } from '../specs-apply.js';
 import { MIN_PURPOSE_LENGTH, MAX_REQUIREMENT_TEXT_LENGTH, VALIDATION_MESSAGES } from './constants.js';
-import { parseDeltaSpec, foldRequirementName, normalizeRequirementName, extractRequirementsSection, findMissingCurrentScenarios, } from '../parsers/requirement-blocks.js';
-import { extractRequirementBody as extractRequirementBodyShared, containsShallOrMust as containsShallOrMustShared, countScenarios as countScenariosShared, } from '../parsers/requirement-text.js';
+import { parseDeltaSpec, foldRequirementName, normalizeRequirementName, extractRequirementsSection, diffScenarioNames, describeScenarioBalance, } from '../parsers/requirement-blocks.js';
+import { extractRequirementBody as extractRequirementBodyShared, containsShallOrMust as containsShallOrMustShared, countScenarios as countScenariosShared, countEmptyScenarios, } from '../parsers/requirement-text.js';
 import { findMainSpecStructureIssues } from '../parsers/spec-structure.js';
 import { FileSystemUtils } from '../../utils/file-system.js';
-import { discoverSpecFiles, hasAnyFileUnder } from '../../utils/spec-discovery.js';
+import { discoverSpecFiles, findUnreadDeltaFiles, hasAnyFileUnder } from '../../utils/spec-discovery.js';
 import { METADATA_FILENAME, readSkipSpecsMarker, resolveSchemaForChange, } from '../../utils/change-metadata.js';
 import { resolveTaskFilesForChange } from '../../utils/task-progress.js';
 import { findTaskNumberingIssues } from './task-numbering.js';
+import { findMissingTaskCheckboxIssues } from './task-checkboxes.js';
 import { findPurposePlaceholderIssue } from './purpose-placeholder.js';
 import { getPackageSchemasDir, getSchemaDir } from '../artifact-graph/index.js';
 export class Validator {
@@ -174,6 +175,34 @@ export class Validator {
                             : `Header "### ${stray.header}" in ${stray.section} is not a "### Requirement:" header and is ignored by validation. Use "### Requirement: ${stray.header}" if it should be validated as a requirement.`,
                     });
                 }
+                // A FROM:/TO: line that never formed a pair. Reported here so the author
+                // learns at authoring time, rather than having archive either skip the
+                // rename or apply it to a requirement they never named.
+                for (const unpaired of plan.unpairedRenames) {
+                    const missing = unpaired.side === 'FROM' ? 'TO' : 'FROM';
+                    issues.push({
+                        level: 'ERROR',
+                        path: entryPath,
+                        line: unpaired.line,
+                        message: `RENAMED ${unpaired.side}: "${unpaired.name}" has no matching ${missing}: line. Write each rename as a FROM: line followed immediately by its TO: line.`,
+                    });
+                }
+                // A well-formed requirement written outside every delta section. The
+                // reader only looks inside the four delta sections, so this block is
+                // ignored - reported as a WARNING rather than an ERROR because a
+                // handful of pre-format archived changes still carry this shape, and
+                // the fix is to move the block, not to reject the change outright.
+                for (const orphan of plan.orphanedRequirements) {
+                    const where = orphan.section
+                        ? `under "## ${orphan.section}"`
+                        : 'above the first "## " section';
+                    issues.push({
+                        level: 'WARNING',
+                        path: entryPath,
+                        line: orphan.line,
+                        message: `Requirement "${orphan.name}" is ${where}, which is not a delta section, so it is ignored. Move it under "## ADDED Requirements", "## MODIFIED Requirements", "## REMOVED Requirements", or "## RENAMED Requirements".`,
+                    });
+                }
                 const sectionNames = [];
                 if (plan.sectionPresence.added)
                     sectionNames.push('## ADDED Requirements');
@@ -225,7 +254,7 @@ export class Validator {
                     }
                     const scenarioCount = this.countScenarios(block.raw);
                     if (scenarioCount < 1) {
-                        issues.push({ level: 'ERROR', path: entryPath, message: `ADDED "${block.name}" must include at least one scenario` });
+                        issues.push({ level: 'ERROR', path: entryPath, message: `ADDED "${block.name}" must include at least one scenario${this.emptyScenarioHint(block.raw)}` });
                     }
                 }
                 // Validate MODIFIED
@@ -257,7 +286,7 @@ export class Validator {
                     }
                     const scenarioCount = this.countScenarios(block.raw);
                     if (scenarioCount < 1) {
-                        issues.push({ level: 'ERROR', path: entryPath, message: `MODIFIED "${block.name}" must include at least one scenario` });
+                        issues.push({ level: 'ERROR', path: entryPath, message: `MODIFIED "${block.name}" must include at least one scenario${this.emptyScenarioHint(block.raw)}` });
                     }
                 }
                 // Run archive's scenario-loss check here too, so the change fails at
@@ -358,6 +387,17 @@ export class Validator {
                 throw error;
             }
         }
+        // The same drop happens to delta sections in any other file the merge
+        // path does not read (specs/<capability>.md, a note beside spec.md),
+        // while the artifact graph's specs/**/*.md glob counts it as written.
+        const unreadDeltaFiles = await findUnreadDeltaFiles(specsDir);
+        for (const file of unreadDeltaFiles) {
+            issues.push({
+                level: 'ERROR',
+                path: file.path,
+                message: `Delta spec found at specs/${file.path}. Delta specs must be a spec.md inside a capability folder — this file is ignored when the change is applied or archived. Move its requirements into specs/${file.expected}.`,
+            });
+        }
         for (const { path: specPath, sections } of emptySectionSpecs) {
             issues.push({
                 level: 'ERROR',
@@ -397,10 +437,10 @@ export class Validator {
         if (skipSpecs && specsDirHasFiles) {
             issues.push({ level: 'ERROR', path: 'file', message: VALIDATION_MESSAGES.CHANGE_SKIP_SPECS_CONFLICT });
         }
-        // The root-level error already names the file and the fix; adding "No
-        // deltas found" on top would contradict it, since the deltas are sitting in
-        // the file just reported.
-        if (totalDeltas === 0 && !hasRootLevelSpec) {
+        // The root-level and unread-file errors already name the file and the fix;
+        // adding "No deltas found" on top would contradict them, since the deltas
+        // are sitting in the files just reported.
+        if (totalDeltas === 0 && !hasRootLevelSpec && unreadDeltaFiles.length === 0) {
             if (skipSpecs && !specsDirHasFiles) {
                 issues.push({ level: 'INFO', path: 'file', message: VALIDATION_MESSAGES.CHANGE_SKIP_SPECS_ACCEPTED });
             }
@@ -409,56 +449,120 @@ export class Validator {
             }
         }
         if (options.projectRoot) {
-            issues.push(...await this.collectTaskNumberingIssues(changeDir, options.projectRoot));
+            issues.push(...await this.collectTaskFileIssues(changeDir, options.projectRoot));
         }
         return this.createReport(issues);
     }
-    async collectTaskNumberingIssues(changeDir, projectRoot) {
+    /**
+     * Lints the change's task files.
+     *
+     * Two checks with deliberately different reach. Checkbox formatting is read
+     * from whatever the change's own schema declares as its tracked task output,
+     * because every schema's progress, apply and archive behavior is computed by
+     * counting checkboxes in exactly those files. Numbering stays scoped to the
+     * built-in `spec-driven` schema, whose template is the one that numbers tasks
+     * in the first place.
+     *
+     * The checkbox check never falls back to a bare top-level `tasks.md`: a file
+     * no artifact declares is not a tracked task list, and warning about its
+     * formatting would be a guess about a file the tool does not read.
+     */
+    async collectTaskFileIssues(changeDir, projectRoot) {
+        let trackedFiles;
         try {
-            const schemaName = resolveSchemaForChange(changeDir, undefined, projectRoot).replace(/\.ya?ml$/, '');
-            const schemaDir = getSchemaDir(schemaName, projectRoot);
-            const builtInSchemaDir = path.join(getPackageSchemasDir(), 'spec-driven');
-            if (schemaName !== 'spec-driven' ||
-                schemaDir === null ||
-                FileSystemUtils.canonicalizeExistingPath(schemaDir) !==
-                    FileSystemUtils.canonicalizeExistingPath(builtInSchemaDir)) {
-                return [];
-            }
+            trackedFiles = resolveTaskFilesForChange(changeDir, projectRoot);
         }
         catch {
             return [];
         }
-        let taskFiles;
-        try {
-            taskFiles = resolveTaskFilesForChange(changeDir, projectRoot);
-        }
-        catch {
-            return [];
+        const files = trackedFiles.length > 0 ? trackedFiles : [path.join(changeDir, 'tasks.md')];
+        const { documents, unreadable } = await this.readTaskDocuments(changeDir, files);
+        const toWarning = (issue) => ({
+            level: 'WARNING',
+            path: issue.path,
+            line: issue.line,
+            message: issue.message,
+        });
+        const issues = [];
+        // "No file here holds a checkbox" is a claim about the whole tracked set, so
+        // a file that exists but could not be read withdraws it: the checkboxes may
+        // be in exactly that file. `validate --archived` is the surface that reports
+        // an unreadable task file loudly (#205); this one must not guess from it.
+        if (trackedFiles.length > 0 && unreadable === 0) {
+            issues.push(...findMissingTaskCheckboxIssues(documents).map(toWarning));
         }
-        if (taskFiles.length === 0) {
-            taskFiles = [path.join(changeDir, 'tasks.md')];
+        if (this.usesBuiltInSpecDrivenSchema(changeDir, projectRoot)) {
+            issues.push(...findTaskNumberingIssues(documents).map(toWarning));
         }
+        return issues;
+    }
+    /**
+     * Reads task files into change-relative documents, counting the ones that
+     * exist but could not be read. A file that is simply absent is not counted:
+     * the resolver only returns files it found, so the remaining read failures
+     * are permissions and I/O, and a check that reasons over the whole set needs
+     * to know its evidence was incomplete.
+     */
+    async readTaskDocuments(changeDir, files) {
         const documents = [];
-        for (const taskFile of taskFiles) {
+        let unreadable = 0;
+        for (const file of files) {
             let content;
             try {
-                content = await fs.readFile(taskFile, 'utf-8');
+                content = await fs.readFile(file, 'utf-8');
             }
-            catch {
+            catch (error) {
+                if (error?.code !== 'ENOENT')
+                    unreadable++;
                 continue;
             }
-            documents.push({
-                path: FileSystemUtils.toPosixPath(path.relative(changeDir, taskFile)),
-                content,
-            });
+            documents.push({ path: this.taskDocumentPath(changeDir, file), content });
         }
         documents.sort((left, right) => left.path.localeCompare(right.path));
-        return findTaskNumberingIssues(documents).map((issue) => ({
-            level: 'WARNING',
-            path: issue.path,
-            line: issue.line,
-            message: issue.message,
-        }));
+        return { documents, unreadable };
+    }
+    /**
+     * Names a task file relative to its change, POSIX-separated.
+     *
+     * Both sides are canonicalized first. `resolveArtifactOutputs` hands back real
+     * paths, while `changeDir` carries whatever spelling the caller resolved, and
+     * the two can differ without being apart: on Windows a short 8.3 alias
+     * (`RUNNER~1`) against its expanded form turned `tasks.md` into a
+     * `../../../..`-prefixed absolute path in the report, and a symlinked project
+     * directory does the same elsewhere. Canonicalizing recovers the real
+     * relationship. The Windows CI job is the regression guard — the mismatch
+     * cannot be staged on POSIX, where the spawned CLI's `process.cwd()` is
+     * already physical.
+     *
+     * A path that still escapes would be a resolver bug rather than a spelling
+     * difference, but the report must never leak an absolute filesystem path, so
+     * the file name stands in.
+     */
+    taskDocumentPath(changeDir, file) {
+        const relative = path.relative(FileSystemUtils.canonicalizeExistingPath(changeDir), FileSystemUtils.canonicalizeExistingPath(file));
+        const escapes = relative === '' || relative.startsWith('..') || path.isAbsolute(relative);
+        return escapes ? path.basename(file) : FileSystemUtils.toPosixPath(relative);
+    }
+    /**
+     * True when the change resolves to the package's own `spec-driven` schema. A
+     * project schema that merely reuses the name is not it, so checks written
+     * against the built-in template never fire on someone else's task format.
+     */
+    usesBuiltInSpecDrivenSchema(changeDir, projectRoot) {
+        try {
+            const schemaName = resolveSchemaForChange(changeDir, undefined, projectRoot).replace(/\.ya?ml$/, '');
+            if (schemaName !== 'spec-driven')
+                return false;
+            const schemaDir = getSchemaDir(schemaName, projectRoot);
+            if (schemaDir === null)
+                return false;
+            const builtInSchemaDir = path.join(getPackageSchemasDir(), 'spec-driven');
+            return (FileSystemUtils.canonicalizeExistingPath(schemaDir) ===
+                FileSystemUtils.canonicalizeExistingPath(builtInSchemaDir));
+        }
+        catch {
+            return false;
+        }
     }
     /**
      * Report MODIFIED requirements whose block omits a scenario the main spec
@@ -535,15 +639,16 @@ export class Validator {
             const current = currentBlockFor(key);
             if (!current)
                 continue;
-            const missing = findMissingCurrentScenarios(current, block);
-            if (missing.length === 0)
+            const diff = diffScenarioNames(current, block);
+            if (diff.missing.length === 0)
                 continue;
             issues.push({
                 level: 'ERROR',
                 path: entryPath,
                 message: `MODIFIED "${block.name}" omits scenario(s) the current spec still has: ` +
-                    `${missing.map(name => `"${name}"`).join(', ')}. ` +
-                    'Copy them into the MODIFIED block (a MODIFIED requirement replaces the whole block, so archive refuses to drop them).',
+                    `${diff.missing.map(name => `"${name}"`).join(', ')}. ` +
+                    `${describeScenarioBalance(diff)} ` +
+                    'Copy the omitted scenarios into the MODIFIED block (a MODIFIED requirement replaces the whole block, so archive refuses to drop them).',
             });
         }
         return issues;
@@ -797,6 +902,16 @@ export class Validator {
         // example is not a real scenario. Drop the header line (index 0).
         return countScenariosShared(blockRaw.split('\n').slice(1));
     }
+    /**
+     * Why a requirement with a visible scenario header still has no scenario:
+     * the header has no body, and the spec path archive validates against does
+     * not count it. Empty when the block has no bare scenario header.
+     */
+    emptyScenarioHint(blockRaw) {
+        if (countEmptyScenarios(blockRaw.split('\n').slice(1)) === 0)
+            return '';
+        return ' (a scenario header with no body under it does not count; add its steps, e.g. "- **WHEN** ..." and "- **THEN** ...")';
+    }
     formatSectionList(sections) {
         if (sections.length === 0)
             return '';

package/dist/core/version-check.d.ts

@@ -1,12 +1,14 @@
 /**
- * The registry to ask: only the environment variable npm exports (under
- * `npm run`, or an explicit export). Deliberately not a `registry=` line from
- * any .npmrc — letting file contents choose the destination of an outbound
- * request is a flow worth avoiding for a convenience this small, and a project
- * file would travel with a cloned repository. Anyone on a private mirror can
- * export `npm_config_registry`, or turn the check off entirely.
+ * The registry to ask. A configured registry is honored only over TLS: a
+ * cleartext hop would aim the request at a link-local or internal address and
+ * let anyone on the path choose the "newer version" answer.
+ *
+ * A rejected registry disables the check rather than falling back to public
+ * npm. Falling back would send a request an organization on an internal mirror
+ * deliberately avoided, and would then report a version resolved against a
+ * registry the eventual `npm install -g` does not use.
  */
-export declare function registryUrl(): string;
+export declare function registryUrl(): string | null;
 /**
  * Compares two semver-ish versions. Returns 1 when a > b, -1 when a < b, 0
  * otherwise. Prereleases sort below their release (1.7.0-beta.1 < 1.7.0).
@@ -92,6 +94,11 @@ export declare function buildUpgradeCommandLines(installDir: string | null, proj
  * that may not be the one on PATH, a project dependency belongs to that
  * project's package manager, an npx/dlx cache has nothing to upgrade, and a
  * source checkout is not an install at all.
+ *
+ * A non-default registry is also disqualifying. `npm install -g` resolves
+ * against whatever `npm_config_registry` says, which npm may have read from a
+ * cloned repository's .npmrc — so such a registry may still inform the check,
+ * but must never be the thing that offers to install a global package.
  */
 export declare function canSelfUpgrade(installDir: string | null, projectPath: string): boolean;
 /**