@fission-ai/openspec 1.15.0 → 1.16.1

package/README.md

@@ -117,21 +117,19 @@ Solo, OpenSpec keeps you and your AI honest on a single repo. On a team, the har
 
 ## Quick Start
 
-Install OpenSpec. It is a single file and needs no Node.js (on Alpine Linux, first run `apk add libstdc++ libgcc`).
-
-macOS and Linux:
+Install OpenSpec. On macOS or Linux, in your terminal:
 
 ```bash
-curl -fsSL https://raw.githubusercontent.com/Fission-AI/OpenSpec/main/scripts/binary/install.sh | sh
+curl -fsSL https://openspec.dev/cli/install.sh | sh
 ```
 
-Windows (PowerShell):
+On Windows, in PowerShell:
 
 ```powershell
-irm https://raw.githubusercontent.com/Fission-AI/OpenSpec/main/scripts/binary/install.ps1 | iex
+irm https://openspec.dev/cli/install.ps1 | iex
 ```
 
-Prefer a package manager? `npm install -g @fission-ai/openspec@latest` (needs Node.js 20.19.0 or higher) or the official [Homebrew formula](https://formulae.brew.sh/formula/openspec), `brew install openspec`.
+Prefer a package manager? `npm install -g @fission-ai/openspec@latest` (needs Node.js 22.12.0 or higher) or the official [Homebrew formula](https://formulae.brew.sh/formula/openspec), `brew install openspec`.
 
 Then navigate to your project directory and initialize:
 

package/dist/cli/index.js

@@ -123,7 +123,7 @@ program
     .action(async (options) => {
     const { getCliInstallInfo, checkForCliUpdate, getCliUpdateCommand, canSelfUpgrade, buildVersionReportLines, } = await import('../core/version-check.js');
     const install = getCliInstallInfo();
-    const update = options.check ? await checkForCliUpdate() : undefined;
+    const update = options.check ? await checkForCliUpdate({ requested: true }) : undefined;
     const command = update?.status === 'available' ? getCliUpdateCommand(install) : null;
     const output = {
         schemaVersion: 1,

package/dist/commands/completion.js

@@ -1,4 +1,5 @@
 import { CompletionFactory } from '../core/completions/factory.js';
+import { zshrcDisplayPath } from '../core/completions/installers/zsh-installer.js';
 import { COMMAND_REGISTRY } from '../core/completions/command-registry.js';
 import { detectShell } from '../utils/shell-detection.js';
 import { CompletionProvider } from '../core/completions/completion-provider.js';
@@ -113,7 +114,7 @@ export class CompletionCommand {
                     const configWasUpdated = result.zshrcConfigured || result.bashrcConfigured || result.profileConfigured;
                     if (configWasUpdated) {
                         const configPaths = {
-                            zsh: '~/.zshrc',
+                            zsh: zshrcDisplayPath(),
                             bash: '~/.bashrc',
                             fish: '~/.config/fish/config.fish',
                             powershell: '$PROFILE',
@@ -174,7 +175,8 @@ export class CompletionCommand {
             const { confirm } = await import('@inquirer/prompts');
             // Get shell-specific config file path
             const configPaths = {
-                zsh: '~/.zshrc',
+                // Uninstall also clears a block an older install left in ~/.zshrc.
+                zsh: zshrcDisplayPath() === '~/.zshrc' ? '~/.zshrc' : `${zshrcDisplayPath()} (and ~/.zshrc if an older install wrote there)`,
                 bash: '~/.bashrc',
                 fish: 'Fish configuration', // Fish doesn't modify profile, just removes script file
                 powershell: '$PROFILE',

package/dist/commands/validate.js

@@ -11,6 +11,7 @@ import { promises as fs } from 'fs';
 import { getTaskProgressDetailForChange } from '../utils/task-progress.js';
 import { FileSystemUtils } from '../utils/file-system.js';
 import { folderStyleNameProblem } from '../core/id.js';
+import { readConfigParseError } from '../core/project-config.js';
 /** Findings are a distinct report, not a partial full-v1 items collection. */
 export function projectValidationFindings(full, scope) {
     const itemFindings = full.items.filter(item => item.issues.length > 0);
@@ -66,6 +67,28 @@ export class ValidateCommand {
         if (!root) {
             return;
         }
+        // Every other command ignores an unreadable or unparseable config with a
+        // warning, so validate is where CI has to catch it (#1892).
+        const configError = readConfigParseError(root.path);
+        if (configError) {
+            const unreadable = configError.kind === 'read';
+            const message = unreadable
+                ? `Could not read ${configError.filePath} (${configError.message}).`
+                : `Could not parse ${configError.filePath} (${configError.message}).`;
+            const fix = unreadable
+                ? `Make ${configError.filePath} a readable file, or remove it.`
+                : `Fix the YAML syntax in ${configError.filePath}.`;
+            const code = unreadable ? 'unreadable_config' : 'unparseable_config';
+            if (options.json) {
+                console.log(JSON.stringify({ status: [{ severity: 'error', code, message, fix }] }, null, 2));
+            }
+            else {
+                console.error(`Error: ${message}`);
+                console.error(`Fix: ${fix}`);
+            }
+            process.exitCode = 1;
+            return;
+        }
         const interactive = isInteractive(options);
         // Archived-task linting is its own scope: it checks task completion of
         // already-archived changes, not delta specs (whose operations are already

package/dist/core/completions/installers/zsh-installer.d.ts

@@ -1,4 +1,6 @@
 import { InstallationResult } from '../factory.js';
+/** The .zshrc zsh will read, as shown to the user: `~/.zshrc` unless ZDOTDIR moves it. */
+export declare function zshrcDisplayPath(homeDir?: string): string;
 /**
  * Installer for Zsh completion scripts.
  * Supports both Oh My Zsh and standard Zsh configurations.
@@ -47,6 +49,11 @@ export declare class ZshInstaller {
      * @returns Path to .zshrc
      */
     private getZshrcPath;
+    /**
+     * Every .zshrc that may hold an OpenSpec block: the one zsh reads, plus
+     * ~/.zshrc, where installs before #2138 wrote it even under ZDOTDIR.
+     */
+    private getZshrcCandidates;
     /**
      * Generate .zshrc configuration content
      *
@@ -72,9 +79,10 @@ export declare class ZshInstaller {
      * Remove .zshrc configuration
      * Used during uninstallation
      *
+     * @param zshrcPath - The .zshrc to clean; defaults to the one zsh reads
      * @returns true if removed successfully, false otherwise
      */
-    removeZshrcConfig(): Promise<boolean>;
+    removeZshrcConfig(zshrcPath?: string): Promise<boolean>;
     /**
      * Install the completion script
      *

package/dist/core/completions/installers/zsh-installer.js

@@ -3,6 +3,23 @@ import path from 'path';
 import os from 'os';
 import { FileSystemUtils } from '../../../utils/file-system.js';
 import { shellSingleQuote } from './shell-quote.js';
+/**
+ * zsh reads its startup files from $ZDOTDIR when it is set, and from $HOME
+ * only otherwise, so a block written to ~/.zshrc under an XDG-style
+ * ZDOTDIR is never loaded (#2138).
+ */
+function zshrcDir(homeDir) {
+    const zdotdir = process.env.ZDOTDIR;
+    // zsh does not expand `~` in ZDOTDIR, and path.join would resolve a relative
+    // or `~/...` value against the current directory, writing a stray .zshrc
+    // into the user's project. Only an absolute ZDOTDIR moves the file.
+    return zdotdir && path.isAbsolute(zdotdir) ? zdotdir : homeDir;
+}
+/** The .zshrc zsh will read, as shown to the user: `~/.zshrc` unless ZDOTDIR moves it. */
+export function zshrcDisplayPath(homeDir = os.homedir()) {
+    const zshrcPath = path.join(zshrcDir(homeDir), '.zshrc');
+    return zshrcPath === path.join(homeDir, '.zshrc') ? '~/.zshrc' : zshrcPath;
+}
 /**
  * Installer for Zsh completion scripts.
  * Supports both Oh My Zsh and standard Zsh configurations.
@@ -99,7 +116,14 @@ export class ZshInstaller {
      * @returns Path to .zshrc
      */
     getZshrcPath() {
-        return path.join(this.homeDir, '.zshrc');
+        return path.join(zshrcDir(this.homeDir), '.zshrc');
+    }
+    /**
+     * Every .zshrc that may hold an OpenSpec block: the one zsh reads, plus
+     * ~/.zshrc, where installs before #2138 wrote it even under ZDOTDIR.
+     */
+    getZshrcCandidates() {
+        return [...new Set([this.getZshrcPath(), path.join(this.homeDir, '.zshrc')])];
     }
     /**
      * Generate .zshrc configuration content
@@ -150,9 +174,8 @@ export class ZshInstaller {
      *
      * @returns true if .zshrc exists and has markers
      */
-    async hasZshrcConfig() {
+    async hasZshrcConfig(zshrcPath = this.getZshrcPath()) {
         try {
-            const zshrcPath = this.getZshrcPath();
             const content = await fs.readFile(zshrcPath, 'utf-8');
             return content.includes(this.ZSHRC_MARKERS.start) && content.includes(this.ZSHRC_MARKERS.end);
         }
@@ -164,11 +187,11 @@ export class ZshInstaller {
      * Remove .zshrc configuration
      * Used during uninstallation
      *
+     * @param zshrcPath - The .zshrc to clean; defaults to the one zsh reads
      * @returns true if removed successfully, false otherwise
      */
-    async removeZshrcConfig() {
+    async removeZshrcConfig(zshrcPath = this.getZshrcPath()) {
         try {
-            const zshrcPath = this.getZshrcPath();
             // Check if file exists
             try {
                 await fs.access(zshrcPath);
@@ -224,16 +247,24 @@ export class ZshInstaller {
             try {
                 const existingContent = await fs.readFile(targetPath, 'utf-8');
                 if (existingContent === completionScript) {
-                    // Already installed and up to date
+                    // Already installed and up to date. Still make sure the .zshrc zsh
+                    // reads has the block: an install made before #2138 under ZDOTDIR
+                    // wrote it to ~/.zshrc, and re-running install is how that's fixed.
+                    const zshrcConfigured = isOhMyZsh
+                        ? false
+                        : await this.configureZshrc(path.dirname(targetPath));
                     return {
                         success: true,
                         installedPath: targetPath,
                         isOhMyZsh,
+                        zshrcConfigured,
                         message: 'Completion script is already installed (up to date)',
-                        instructions: [
-                            'The completion script is already installed and up to date.',
-                            'If completions are not working, try: exec zsh',
-                        ],
+                        instructions: isOhMyZsh || zshrcConfigured
+                            ? [
+                                'The completion script is already installed and up to date.',
+                                'If completions are not working, try: exec zsh',
+                            ]
+                            : this.generateInstructions(false, targetPath),
                     };
                 }
                 // File exists but content is different - this is an update
@@ -336,11 +367,11 @@ export class ZshInstaller {
         }
         else {
             const completionsDir = path.dirname(installedPath);
-            const zshrcPath = path.join(this.homeDir, '.zshrc');
+            const zshrcPath = this.getZshrcPath();
             return [
                 'Completion script installed to ~/.zsh/completions/',
                 '',
-                'To enable completions, add the following to your ~/.zshrc file:',
+                `To enable completions, add the following to your ${zshrcDisplayPath(this.homeDir)} file:`,
                 '',
                 `  # Add completions directory to fpath`,
                 `  fpath=(${shellSingleQuote(completionsDir)} $fpath)`,
@@ -375,11 +406,19 @@ export class ZshInstaller {
             }
             // Try to remove .zshrc configuration (only for standard Zsh)
             let zshrcWasPresent = false;
-            let zshrcCleaned = false;
+            const cleanedZshrcs = [];
+            const failedZshrcs = [];
             if (!isOhMyZsh) {
-                zshrcWasPresent = await this.hasZshrcConfig();
-                if (zshrcWasPresent) {
-                    zshrcCleaned = await this.removeZshrcConfig();
+                for (const zshrcPath of this.getZshrcCandidates()) {
+                    if (await this.hasZshrcConfig(zshrcPath)) {
+                        zshrcWasPresent = true;
+                        if (await this.removeZshrcConfig(zshrcPath)) {
+                            cleanedZshrcs.push(zshrcPath);
+                        }
+                        else {
+                            failedZshrcs.push(zshrcPath);
+                        }
+                    }
                 }
             }
             if (!scriptRemoved && !zshrcWasPresent) {
@@ -392,11 +431,17 @@ export class ZshInstaller {
             if (scriptRemoved) {
                 messages.push(`Completion script removed from ${targetPath}`);
             }
-            if (zshrcCleaned && !isOhMyZsh) {
-                messages.push('Removed OpenSpec configuration from ~/.zshrc');
+            const label = (zshrcPath) => zshrcPath === path.join(this.homeDir, '.zshrc') ? '~/.zshrc' : zshrcPath;
+            for (const zshrcPath of cleanedZshrcs) {
+                messages.push(`Removed OpenSpec configuration from ${label(zshrcPath)}`);
+            }
+            // A block left behind keeps loading the completions, so say so instead
+            // of reporting a clean uninstall.
+            for (const zshrcPath of failedZshrcs) {
+                messages.push(`Could not remove the OpenSpec block from ${label(zshrcPath)}; delete the lines between # OPENSPEC:START and # OPENSPEC:END by hand`);
             }
             return {
-                success: true,
+                success: failedZshrcs.length === 0,
                 message: messages.join('. '),
             };
         }

package/dist/core/id.d.ts

@@ -4,6 +4,14 @@
  */
 export declare const KEBAB_ID_REGEX: RegExp;
 export declare function isKebabId(value: string): boolean;
+/**
+ * Best-effort normalization of an arbitrary name into the kebab grammar:
+ * lowercases, splits camelCase/PascalCase boundaries, and folds every
+ * non-alphanumeric run into a single hyphen. Used to turn a git repository
+ * name into a candidate store id; the result is only ever a candidate and
+ * is validated with {@link isKebabId} before use.
+ */
+export declare function toKebabCase(value: string): string;
 /** Human rendering of the grammar, shared so the wording never forks. */
 export declare const KEBAB_ID_DESCRIPTION = "must be kebab-case with lowercase letters, numbers, and single hyphen separators";
 /** The fix-line twin of KEBAB_ID_DESCRIPTION, shared for the same reason. */

package/dist/core/id.js

@@ -6,6 +6,21 @@ export const KEBAB_ID_REGEX = /^[a-z0-9]+(?:-[a-z0-9]+)*$/u;
 export function isKebabId(value) {
     return KEBAB_ID_REGEX.test(value);
 }
+/**
+ * Best-effort normalization of an arbitrary name into the kebab grammar:
+ * lowercases, splits camelCase/PascalCase boundaries, and folds every
+ * non-alphanumeric run into a single hyphen. Used to turn a git repository
+ * name into a candidate store id; the result is only ever a candidate and
+ * is validated with {@link isKebabId} before use.
+ */
+export function toKebabCase(value) {
+    return value
+        .replace(/([a-z0-9])([A-Z])/g, '$1-$2')
+        .replace(/([A-Z])([A-Z][a-z])/g, '$1-$2')
+        .replace(/[^a-zA-Z0-9]+/g, '-')
+        .replace(/^-+|-+$/g, '')
+        .toLowerCase();
+}
 /** Human rendering of the grammar, shared so the wording never forks. */
 export const KEBAB_ID_DESCRIPTION = 'must be kebab-case with lowercase letters, numbers, and single hyphen separators';
 /** The fix-line twin of KEBAB_ID_DESCRIPTION, shared for the same reason. */

package/dist/core/parsers/change-parser.js

@@ -1,6 +1,6 @@
 import { MarkdownParser } from './markdown-parser.js';
 import { buildCodeFenceMask } from './requirement-text.js';
-import { parseDeltaSpec } from './requirement-blocks.js';
+import { parseDeltaSpec, stripClosingSequence } from './requirement-blocks.js';
 import path from 'path';
 import { promises as fs } from 'fs';
 import { discoverSpecFiles } from '../../utils/spec-discovery.js';
@@ -171,7 +171,8 @@ export class ChangeParser extends MarkdownParser {
             const headerMatch = line.match(/^(#{1,6})\s+(.+)$/);
             if (headerMatch) {
                 const level = headerMatch[1].length;
-                const title = headerMatch[2].trim();
+                // `## Purpose ##` is the same heading as `## Purpose`.
+                const title = stripClosingSequence(headerMatch[2]);
                 const contentLines = this.getContentUntilNextHeaderFromLines(lines, codeFenceLineMask, i + 1, level);
                 const section = {
                     level,

package/dist/core/parsers/code-fence.js

@@ -8,10 +8,18 @@
  * requirements during validation and archiving.
  */
 function getFenceMarker(line) {
-    const fenceMatch = line.match(/^\s*(`{3,}|~{3,})/);
+    // Unanchored at the end: `.` does not match `\r`, so `(.*)$` would reject
+    // every opener on a line that still carries a CRLF ending.
+    const fenceMatch = line.match(/^\s*(`{3,}|~{3,})(.*)/);
     if (!fenceMatch) {
         return null;
     }
+    // CommonMark: a backtick fence's info string may not contain a backtick, so
+    // a line like ```npm test``` is inline code, not a fence opener. Treating it
+    // as one masked every following line, hiding later requirements.
+    if (fenceMatch[1][0] === '`' && fenceMatch[2].includes('`')) {
+        return null;
+    }
     return {
         marker: fenceMatch[1][0],
         length: fenceMatch[1].length,

package/dist/core/parsers/markdown-parser.js

@@ -1,5 +1,5 @@
 import { buildCodeFenceMask, extractRequirementText, hasScenarioBody } from './requirement-text.js';
-import { normalizeRequirementName, scenarioNameFromHeaderText } from './requirement-blocks.js';
+import { normalizeRequirementName, scenarioNameFromHeaderText, stripClosingSequence } from './requirement-blocks.js';
 export class MarkdownParser {
     lines;
     codeFenceLineMask;
@@ -68,7 +68,8 @@ export class MarkdownParser {
             const headerMatch = line.match(/^(#{1,6})\s+(.+)$/);
             if (headerMatch) {
                 const level = headerMatch[1].length;
-                const title = headerMatch[2].trim();
+                // `## Purpose ##` is the same heading as `## Purpose`.
+                const title = stripClosingSequence(headerMatch[2]);
                 const content = this.getContentUntilNextHeader(i + 1, level);
                 const section = {
                     level,

package/dist/core/parsers/requirement-blocks.d.ts

@@ -10,6 +10,15 @@ export interface RequirementsSectionParts {
     bodyBlocks: RequirementBlock[];
     after: string;
 }
+/**
+ * Drop an ATX heading's closing run of `#`s: `## Purpose ##` renders as
+ * `Purpose`, so the run is not part of the title. As for scenario names, only a
+ * run preceded by a space or tab closes the heading, so `C#` keeps its `#`, and
+ * `[ \t]` rather than `\s` keeps an NBSP-separated run in the title.
+ */
+export declare function stripClosingSequence(title: string): string;
+/** The main spec's `## Requirements` header, closing run allowed (`## Requirements ##`). */
+export declare const REQUIREMENTS_SECTION_HEADER_REGEX: RegExp;
 export declare function normalizeRequirementName(name: string): string;
 /**
  * Case- and whitespace-insensitive fold of a requirement name. Requirement
@@ -105,7 +114,26 @@ export interface DeltaPlan {
  * Parse a delta-formatted spec change file content into a DeltaPlan with raw blocks.
  */
 export declare function parseDeltaSpec(content: string): DeltaPlan;
+/**
+ * True when an orphaned requirement sits under a `## ... Requirements` header
+ * that is not one of the four delta sections - `## DEPRECATED Requirements`,
+ * `## Add Requirements`, `## Requirements`. Such a header reads as a delta
+ * operation, so its requirements were meant to be applied: validate reports
+ * them as an ERROR and archive refuses (#2195). Orphans under prose sections
+ * (`## Notes`, `## Behavior`) or above the first `## ` stay warnings.
+ */
+export declare function isUnrecognizedDeltaSection(section: string | null): boolean;
 export declare function describeUnappliedContent(content: UnappliedContent, sentenceStart?: boolean): string;
+/**
+ * One `#### ` child of a requirement block: its rendered name and its lines,
+ * header included. Exported because the validator's scenario-step check walks
+ * the same blocks the loss comparison does — a second reader of the same
+ * format is how the two drifted apart before.
+ */
+export interface ScenarioBlock {
+    name: string;
+    raw: string;
+}
 /** Both directions of the scenario-name comparison, plus the two totals. */
 export interface ScenarioNameDiff {
     /** Names the current block has that the incoming block does not cover. */
@@ -153,4 +181,24 @@ export declare function describeScenarioBalance(diff: ScenarioNameDiff): string;
  * exactly as the MODIFIED loss check does.
  */
 export declare function scenarioNameFromHeaderText(headerText: string): string;
+/**
+ * Whether a `#### ` header line carries the canonical `Scenario:` label. Any
+ * level-4 child counts as a scenario for counting and loss purposes (the
+ * parity the SCENARIO_HEADER comment protects), but the step check warns only
+ * about blocks that claim to be scenarios: a `#### Notes` child is prose on
+ * purpose, and a missing WHEN/THEN there is noise, not a finding.
+ */
+export declare function isScenarioLabeledHeader(headerLine: string): boolean;
+/**
+ * Every `#### ` child of a requirement block, header line included in `raw`,
+ * in document order. A scenario is ANY non-fenced `#### ` header, matching the
+ * spec path's SCENARIO_HEADER / countScenarios (requirement-text.ts) exactly —
+ * not only `#### Scenario:`. The two MUST agree: a level-4 child whose header
+ * is not literally `Scenario:` (e.g. `#### Edge case`) is still a scenario the
+ * spec path counts, so a MODIFIED block that drops it would otherwise slip past
+ * the loss check and be deleted by archive with no error (the parity the
+ * SCENARIO_HEADER comment warns not to break). A `####` inside a fenced example
+ * is masked out, matching countScenarios.
+ */
+export declare function parseScenarioBlocks(requirementRaw: string): ScenarioBlock[];
 //# sourceMappingURL=requirement-blocks.d.ts.map

package/dist/core/parsers/requirement-blocks.js

@@ -1,10 +1,18 @@
 import { buildCodeFenceMask, SCENARIO_HEADER } from './requirement-text.js';
+/**
+ * Drop an ATX heading's closing run of `#`s: `## Purpose ##` renders as
+ * `Purpose`, so the run is not part of the title. As for scenario names, only a
+ * run preceded by a space or tab closes the heading, so `C#` keeps its `#`, and
+ * `[ \t]` rather than `\s` keeps an NBSP-separated run in the title.
+ */
+export function stripClosingSequence(title) {
+    return title.replace(/[ \t]+#+[ \t]*$/, '').trim();
+}
+/** The main spec's `## Requirements` header, closing run allowed (`## Requirements ##`). */
+export const REQUIREMENTS_SECTION_HEADER_REGEX = /^##\s+Requirements(?:[ \t]+#+)?\s*$/i;
 export function normalizeRequirementName(name) {
-    // An ATX heading may end in a closing run of `#`s: `### Requirement: Foo ###`
-    // renders as `Foo`, so the run is not part of the name. As for scenario names,
-    // only a run preceded by a space or tab closes the heading, so `C#` keeps its
-    // `#`, and `[ \t]` rather than `\s` keeps an NBSP-separated run in the name.
-    return name.replace(/[ \t]+#+[ \t]*$/, '').trim();
+    // `### Requirement: Foo ###` names the requirement `Foo`.
+    return stripClosingSequence(name);
 }
 /**
  * Case- and whitespace-insensitive fold of a requirement name. Requirement
@@ -26,7 +34,7 @@ export function extractRequirementsSection(content) {
     const normalized = normalizeLineEndings(content);
     const lines = normalized.split('\n');
     const fenceMask = buildCodeFenceMask(lines);
-    const reqHeaderIndex = lines.findIndex((l, i) => !fenceMask[i] && /^##\s+Requirements\s*$/i.test(l));
+    const reqHeaderIndex = lines.findIndex((l, i) => !fenceMask[i] && REQUIREMENTS_SECTION_HEADER_REGEX.test(l));
     if (reqHeaderIndex === -1) {
         // No requirements section; create an empty one at the end
         const before = content.trimEnd();
@@ -154,6 +162,19 @@ export function parseDeltaSpec(content) {
  * under it would be dropped without this warning.
  */
 const DELTA_SECTION_TITLES = new Set(['ADDED Requirements', 'MODIFIED Requirements', 'REMOVED Requirements', 'RENAMED Requirements'].map((title) => title.toLowerCase()));
+/**
+ * True when an orphaned requirement sits under a `## ... Requirements` header
+ * that is not one of the four delta sections - `## DEPRECATED Requirements`,
+ * `## Add Requirements`, `## Requirements`. Such a header reads as a delta
+ * operation, so its requirements were meant to be applied: validate reports
+ * them as an ERROR and archive refuses (#2195). Orphans under prose sections
+ * (`## Notes`, `## Behavior`) or above the first `## ` stay warnings.
+ */
+export function isUnrecognizedDeltaSection(section) {
+    return (section !== null &&
+        /\brequirements?$/i.test(section) &&
+        !DELTA_SECTION_TITLES.has(section.toLowerCase()));
+}
 /**
  * Every canonical `### Requirement:` header that is not inside a delta section,
  * in document order.
@@ -161,10 +182,12 @@ const DELTA_SECTION_TITLES = new Set(['ADDED Requirements', 'MODIFIED Requiremen
  * Walks the whole file rather than the parsed sections so a requirement written
  * ABOVE the first `## ` header is reported too - it is dropped just as silently
  * as one under `## Notes`. Fenced lines are skipped, so a requirement shown
- * inside a markdown example is not mistaken for an authored one.
+ * inside a markdown example is not mistaken for an authored one, and so are
+ * HTML comments, so a commented-out draft is not reported as dropped.
  */
 function findOrphanedRequirements(lines, fenceMask) {
     const orphans = [];
+    const masked = maskHtmlComments(lines, fenceMask);
     let section = null;
     for (let i = 0; i < lines.length; i++) {
         if (fenceMask[i])
@@ -172,12 +195,12 @@ function findOrphanedRequirements(lines, fenceMask) {
         // The same `## ` test splitTopLevelSections uses, so both agree on sections.
         const sectionMatch = lines[i].match(/^(##)\s+(.+)$/);
         if (sectionMatch) {
-            section = sectionMatch[2].trim();
+            section = stripClosingSequence(sectionMatch[2]);
             continue;
         }
         if (section !== null && DELTA_SECTION_TITLES.has(section.toLowerCase()))
             continue;
-        const header = lines[i].match(REQUIREMENT_HEADER_REGEX);
+        const header = masked[i].match(REQUIREMENT_HEADER_REGEX);
         if (header) {
             orphans.push({
                 name: normalizeRequirementName(header[1]),
@@ -201,18 +224,24 @@ export function describeUnappliedContent(content, sentenceStart = false) {
  * (warned about separately), REMOVED/RENAMED bodies, and stray `###` headers
  * before the first requirement (INFO since #498) are not reported.
  */
-function findUnappliedContent(lines, fenceMask) {
-    // Blank out comments outside fences, keeping line count; an unterminated one
-    // runs to EOF. Comments only decide whether a line holds text: sections come
-    // from the same split the merge reads, where a `## ` line inside a comment is
-    // still a boundary. Fenced lines keep their text, so a `<!--` in a code sample
-    // never hides what follows the fence.
+/**
+ * Blank out comments outside fences, keeping line count; an unterminated one
+ * runs to EOF. Fenced lines keep their text, so a `<!--` in a code sample never
+ * hides what follows the fence.
+ */
+function maskHtmlComments(lines, fenceMask) {
     const comments = lines
         .map((line, i) => (fenceMask[i] ? '' : line))
         .join('\n')
         .replace(/<!--[\s\S]*?(?:--!?>|$)/g, (m) => m.replace(/[^\n]/g, ' '))
         .split('\n');
-    const masked = lines.map((line, i) => (fenceMask[i] ? line : comments[i]));
+    return lines.map((line, i) => (fenceMask[i] ? line : comments[i]));
+}
+function findUnappliedContent(lines, fenceMask) {
+    // Comments only decide whether a line holds text: sections come from the
+    // same split the merge reads, where a `## ` line inside a comment is still a
+    // boundary.
+    const masked = maskHtmlComments(lines, fenceMask);
     const sections = splitTopLevelSections(lines, fenceMask);
     const firstText = (from, to, skip) => {
         for (let i = from; i < to; i++)
@@ -260,7 +289,8 @@ function splitTopLevelSections(lines, fenceMask) {
             continue;
         const m = lines[i].match(/^(##)\s+(.+)$/);
         if (m) {
-            indices.push({ title: m[2].trim(), index: i });
+            // `## ADDED Requirements ##` is the same section as `## ADDED Requirements`.
+            indices.push({ title: stripClosingSequence(m[2]), index: i });
         }
     }
     for (let i = 0; i < indices.length; i++) {
@@ -547,16 +577,29 @@ export function scenarioNameFromHeaderText(headerText) {
         .replace(/^Scenario:\s*/i, '')
         .trim();
 }
-function parseScenarioBlocks(requirementRaw) {
+/**
+ * Whether a `#### ` header line carries the canonical `Scenario:` label. Any
+ * level-4 child counts as a scenario for counting and loss purposes (the
+ * parity the SCENARIO_HEADER comment protects), but the step check warns only
+ * about blocks that claim to be scenarios: a `#### Notes` child is prose on
+ * purpose, and a missing WHEN/THEN there is noise, not a finding.
+ */
+export function isScenarioLabeledHeader(headerLine) {
+    return /^Scenario:\s*/i.test(headerLine.replace(SCENARIO_HEADER, ''));
+}
+/**
+ * Every `#### ` child of a requirement block, header line included in `raw`,
+ * in document order. A scenario is ANY non-fenced `#### ` header, matching the
+ * spec path's SCENARIO_HEADER / countScenarios (requirement-text.ts) exactly —
+ * not only `#### Scenario:`. The two MUST agree: a level-4 child whose header
+ * is not literally `Scenario:` (e.g. `#### Edge case`) is still a scenario the
+ * spec path counts, so a MODIFIED block that drops it would otherwise slip past
+ * the loss check and be deleted by archive with no error (the parity the
+ * SCENARIO_HEADER comment warns not to break). A `####` inside a fenced example
+ * is masked out, matching countScenarios.
+ */
+export function parseScenarioBlocks(requirementRaw) {
     const lines = requirementRaw.replace(/\r\n?/g, '\n').split('\n');
-    // A scenario is ANY non-fenced `#### ` header, matching the spec path's
-    // SCENARIO_HEADER / countScenarios (requirement-text.ts) exactly — not only
-    // `#### Scenario:`. The two MUST agree: a level-4 child whose header is not
-    // literally `Scenario:` (e.g. `#### Edge case`) is still a scenario the spec
-    // path counts, so a MODIFIED block that drops it would otherwise slip past
-    // this loss check and be deleted by archive with no error (the parity the
-    // SCENARIO_HEADER comment warns not to break). A `####` inside a fenced
-    // example is masked out, matching countScenarios.
     const mask = buildCodeFenceMask(lines);
     const scenarios = [];
     let index = 0;

package/dist/core/parsers/requirement-text.d.ts

@@ -62,6 +62,20 @@ export declare function extractRequirementText(headerTitle: string, bodyLines: s
  * example is not a real scenario and is not counted.
  */
 export declare function countScenarios(bodyLines: string[]): number;
+/** The two halves of a scenario, as carried by its non-fenced body lines. */
+export interface ScenarioStepCoverage {
+    hasTrigger: boolean;
+    hasOutcome: boolean;
+}
+/**
+ * Whether a scenario block (header line included, as `parseScenarioBlocks`
+ * returns it) carries a trigger step (**WHEN** or **GIVEN**) and an outcome
+ * step (**THEN**) outside fenced examples. `AND` only continues a step that is
+ * already there, so neither half can be carried by an `AND` line; a keyword
+ * inside a fenced block is documentation, not a step — the same masking
+ * `extractRequirementBody` applies to requirement text.
+ */
+export declare function scenarioStepCoverage(scenarioRaw: string): ScenarioStepCoverage;
 /** Count the `#### ` headers in a requirement block that have no body under them. */
 export declare function countEmptyScenarios(bodyLines: string[]): number;
 //# sourceMappingURL=requirement-text.d.ts.map