@fission-ai/openspec 1.15.0 → 1.16.0

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/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/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/requirement-blocks.d.ts

@@ -106,6 +106,16 @@ export interface DeltaPlan {
  */
 export declare function parseDeltaSpec(content: string): DeltaPlan;
 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 +163,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

@@ -547,16 +547,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

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

@@ -101,6 +101,45 @@ export function extractRequirementText(headerTitle, bodyLines) {
 export function countScenarios(bodyLines) {
     return readScenarioBodies(bodyLines).filter(hasScenarioBody).length;
 }
+/**
+ * A step keyword as it is actually written: bolded in any case, with or
+ * without a colon inside the bold (`**WHEN**`, `**Given:**`), or bare and
+ * uppercase (`WHEN`). Bold carries the step-ness, so its case can be liberal;
+ * a bare word must be uppercase to count — lowercase `when`/`then` are
+ * ordinary English prose, and the missing-SHALL/MUST check is uppercase-only
+ * for the same reason. Bold is `**` or `__`; the bare pattern cannot catch
+ * `__WHEN__`, because `_` is a word character and `\b` never fires beside it.
+ */
+const BOLD_TRIGGER_STEP = /(?:\*\*|__)(?:WHEN|GIVEN):?(?:\*\*|__)/i;
+const BARE_TRIGGER_STEP = /\b(?:WHEN|GIVEN)\b/;
+const BOLD_OUTCOME_STEP = /(?:\*\*|__)THEN:?(?:\*\*|__)/i;
+const BARE_OUTCOME_STEP = /\bTHEN\b/;
+/**
+ * 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 function scenarioStepCoverage(scenarioRaw) {
+    const lines = scenarioRaw.replace(/\r\n?/g, '\n').split('\n');
+    const mask = buildCodeFenceMask(lines);
+    let hasTrigger = false;
+    let hasOutcome = false;
+    // Line 0 is the scenario's own header: a keyword in the title
+    // (`#### Scenario: What happens THEN`) is a name, not a step.
+    for (let i = 1; i < lines.length; i++) {
+        if (mask[i])
+            continue;
+        const line = lines[i];
+        if (BOLD_TRIGGER_STEP.test(line) || BARE_TRIGGER_STEP.test(line))
+            hasTrigger = true;
+        if (BOLD_OUTCOME_STEP.test(line) || BARE_OUTCOME_STEP.test(line))
+            hasOutcome = true;
+    }
+    return { hasTrigger, hasOutcome };
+}
 /** Count the `#### ` headers in a requirement block that have no body under them. */
 export function countEmptyScenarios(bodyLines) {
     return readScenarioBodies(bodyLines).filter((body) => !hasScenarioBody(body)).length;

package/dist/core/parsers/spec-structure.js

@@ -3,7 +3,7 @@ import { normalizeRequirementName } from './requirement-blocks.js';
 const REQUIREMENTS_SECTION_HEADER = /^##\s+Requirements\s*$/i;
 const TOP_LEVEL_SECTION_HEADER = /^##\s+/;
 const DELTA_HEADER = /^##\s+(ADDED|MODIFIED|REMOVED|RENAMED)\s+Requirements\s*$/i;
-const REQUIREMENT_HEADER = /^###\s+Requirement:\s*(.+)\s*$/i;
+const REQUIREMENT_HEADER = /^###\s*Requirement:\s*(.+)\s*$/i;
 export function findMainSpecStructureIssues(content) {
     const normalized = content.replace(/\r\n?/g, '\n');
     const stripped = stripFencedCodeBlocksPreservingLines(normalized);

package/dist/core/project-config.d.ts

@@ -70,6 +70,16 @@ export declare const MAX_CONTEXT_SIZE: number;
  * @returns Parsed config or null if file doesn't exist
  */
 export declare function readProjectConfig(projectRoot: string): ProjectConfig | null;
+/**
+ * Warning-silent check for a config file that cannot be read or is not valid
+ * YAML at all. `readProjectConfig` ignores such a file with a warning, so
+ * `validate` uses this to fail instead and give CI a non-zero exit (#1892).
+ */
+export declare function readConfigParseError(projectRoot: string): {
+    kind: 'read' | 'parse';
+    filePath: string;
+    message: string;
+} | null;
 /**
  * Validate artifact IDs in rules against the artifacts of every available
  * schema. The `rules:` map is global, but each change can use a different

package/dist/core/project-config.js

@@ -364,6 +364,32 @@ export function readProjectConfig(projectRoot) {
         return null;
     }
 }
+/**
+ * Warning-silent check for a config file that cannot be read or is not valid
+ * YAML at all. `readProjectConfig` ignores such a file with a warning, so
+ * `validate` uses this to fail instead and give CI a non-zero exit (#1892).
+ */
+export function readConfigParseError(projectRoot) {
+    const filePath = resolveConfigFilePath(projectRoot);
+    if (filePath === null) {
+        return null;
+    }
+    const firstLine = (error) => error instanceof Error ? error.message.split('\n')[0] : String(error);
+    let content;
+    try {
+        content = readFileSync(filePath, 'utf-8');
+    }
+    catch (error) {
+        return { kind: 'read', filePath, message: firstLine(error) };
+    }
+    try {
+        parseYaml(content);
+        return null;
+    }
+    catch (error) {
+        return { kind: 'parse', filePath, message: firstLine(error) };
+    }
+}
 function configPathForWarnings(projectRoot) {
     return resolveConfigFilePath(projectRoot) ?? path.join(projectRoot, 'openspec', 'config.yaml');
 }

package/dist/core/root-selection.d.ts

@@ -79,6 +79,12 @@ export type RegisteredStoreInspection = {
     problems: string;
 };
 export declare function inspectRegisteredStore(id: string, storeRoot: string): Promise<RegisteredStoreInspection>;
+/**
+ * Resolve the OpenSpec root for a command, in precedence order: `--store <id>`,
+ * the nearest local `openspec/` directory, the global `defaultStore`, then the
+ * registered-store hint (which names a store matching the repo's origin, if
+ * any) or an implicit root.
+ */
 export declare function resolveOpenSpecRoot(options?: ResolveOpenSpecRootOptions): Promise<ResolvedOpenSpecRoot>;
 export interface RootOutput {
     path: string;

package/dist/core/root-selection.js

@@ -26,6 +26,8 @@ import * as path from 'node:path';
 import { StoreError } from './store/errors.js';
 import { getStoreMetadataPath, listStoreRegistryEntries, readStoreRegistryState, readOptionalStoreMetadataState, validateStoreId, } from './store/foundation.js';
 import { getStoreRootForBackend } from './store/registry.js';
+import { gitOriginUrl, repoNameFromGitUrl } from './store/git.js';
+import { toKebabCase, isKebabId } from './id.js';
 import { inspectOpenSpecRoot } from './openspec-root.js';
 import { findRepoPlanningRootSync } from './planning-home.js';
 import { classifyOpenSpecDir, storePointerProblem } from './project-config.js';
@@ -251,6 +253,32 @@ async function resolveDefaultStoreRoot(id, globalDataDir) {
         throw error;
     }
 }
+/**
+ * Git-remote store suggestion (#2076): the registered store whose id matches
+ * this repo's origin name, or null. Only ever named in the no-root error, never
+ * selected: a basename is not enough authority to redirect writes, because
+ * `company-a/api` and `company-b/api` both match a store called `api`.
+ */
+async function suggestStoreFromGitRemote(startPath, registeredIds) {
+    // `git -C <path>` needs a directory; a file entry path would make the probe
+    // fail. canonicalDirectory resolves that.
+    const url = await gitOriginUrl(canonicalDirectory(startPath));
+    if (!url)
+        return null;
+    const repoName = repoNameFromGitUrl(url);
+    if (!repoName)
+        return null;
+    const candidateId = toKebabCase(repoName);
+    if (!candidateId || !isKebabId(candidateId))
+        return null;
+    return registeredIds.includes(candidateId) ? candidateId : null;
+}
+/**
+ * Resolve the OpenSpec root for a command, in precedence order: `--store <id>`,
+ * the nearest local `openspec/` directory, the global `defaultStore`, then the
+ * registered-store hint (which names a store matching the repo's origin, if
+ * any) or an implicit root.
+ */
 export async function resolveOpenSpecRoot(options = {}) {
     if (options.storePath !== undefined) {
         throw new RootSelectionError('--store-path is not supported. Register the path with openspec store register <path>, then select it with --store <id>.', 'store_path_not_supported', {
@@ -284,6 +312,15 @@ export async function resolveOpenSpecRoot(options = {}) {
         ? listStoreRegistryEntries(registry).map((entry) => entry.id)
         : [];
     if (registeredIds.length > 0) {
+        // Only spawn git on this failure path: a repo whose origin name matches a
+        // registered store gets that store suggested, never selected.
+        const suggested = await suggestStoreFromGitRemote(startPath, registeredIds);
+        if (suggested) {
+            throw new RootSelectionError(`No OpenSpec root found in the current directory or its ancestors. This repo's origin name matches the registered store "${suggested}". To use it, rerun with --store ${suggested}, or add "store: ${suggested}" to openspec/config.yaml so every command here uses it.`, 'no_root_with_registered_stores', {
+                target: 'openspec.root',
+                fix: `Rerun with --store ${suggested}, or add "store: ${suggested}" to openspec/config.yaml.`,
+            });
+        }
         throw new RootSelectionError(`No OpenSpec root found in the current directory or its ancestors. Registered stores: ${registeredIds.join(', ')}. Pass --store <id> to use one, or run openspec init to create a local root.`, 'no_root_with_registered_stores', {
             target: 'openspec.root',
             fix: `Rerun with --store <id> (registered: ${registeredIds.join(', ')}) or run openspec init.`,

package/dist/core/store/git.d.ts

@@ -47,11 +47,32 @@ export declare function isProbeResourceFailure(error: unknown): boolean;
 export declare function gitHasCommits(storeRoot: string): Promise<boolean | null>;
 export declare function gitHasUncommittedChanges(storeRoot: string): Promise<boolean | null>;
 export declare function gitHasRemote(storeRoot: string): Promise<boolean | null>;
+/**
+ * Env vars that point git at a repository other than the one `-C` names.
+ * Git sets some of them for hooks, so a CLI run from a hook inherits them.
+ */
+export declare const GIT_REPO_LOCATION_ENV_VARS: readonly ["GIT_DIR", "GIT_WORK_TREE", "GIT_INDEX_FILE", "GIT_OBJECT_DIRECTORY", "GIT_ALTERNATE_OBJECT_DIRECTORIES", "GIT_COMMON_DIR"];
+/** A copy of `env` without {@link GIT_REPO_LOCATION_ENV_VARS}. */
+export declare function envWithoutGitRepoLocation(env?: NodeJS.ProcessEnv): NodeJS.ProcessEnv;
 /**
  * The configured origin URL, read from local Git config only — never a
- * network touch. Null when there is no repository or no origin.
+ * network touch. Null when there is no repository or no origin. Inherited
+ * repository-location vars are dropped so the answer is always about
+ * `storeRoot`: root selection runs this from wherever the CLI started,
+ * including inside another repository's git hook.
  */
 export declare function gitOriginUrl(storeRoot: string): Promise<string | null>;
+/**
+ * The repository name from an origin URL, with no host or `.git` suffix.
+ * Handles the three common remote spellings:
+ *
+ * - `git@github.com:user/repo.git`
+ * - `https://github.com/user/repo.git`
+ * - `ssh://git@github.com/user/repo.git`
+ *
+ * Returns the last path segment, or `null` when the URL has no parseable name.
+ */
+export declare function repoNameFromGitUrl(url: string): string | null;
 export interface GitTrackingDrift {
     ahead: number;
     behind: number;

package/dist/core/store/git.js

@@ -137,9 +137,9 @@ export function isProbeResourceFailure(error) {
         code === 'ETIMEDOUT' ||
         (killed === true && signal === 'SIGKILL'));
 }
-async function gitProbe(storeRoot, args) {
+async function gitProbe(storeRoot, args, options = {}) {
     try {
-        const { stdout } = await execFileAsync('git', ['-C', storeRoot, ...args]);
+        const { stdout } = await execFileAsync('git', ['-C', storeRoot, ...args], options);
         return stdout;
     }
     catch (error) {
@@ -175,15 +175,70 @@ export async function gitHasRemote(storeRoot) {
     const stdout = await gitProbe(storeRoot, ['remote']);
     return stdout === null ? null : stdout.trim().length > 0;
 }
+/**
+ * Env vars that point git at a repository other than the one `-C` names.
+ * Git sets some of them for hooks, so a CLI run from a hook inherits them.
+ */
+export const GIT_REPO_LOCATION_ENV_VARS = [
+    'GIT_DIR',
+    'GIT_WORK_TREE',
+    'GIT_INDEX_FILE',
+    'GIT_OBJECT_DIRECTORY',
+    'GIT_ALTERNATE_OBJECT_DIRECTORIES',
+    'GIT_COMMON_DIR',
+];
+/** A copy of `env` without {@link GIT_REPO_LOCATION_ENV_VARS}. */
+export function envWithoutGitRepoLocation(env = process.env) {
+    const clean = { ...env };
+    for (const key of GIT_REPO_LOCATION_ENV_VARS) {
+        delete clean[key];
+    }
+    return clean;
+}
 /**
  * The configured origin URL, read from local Git config only — never a
- * network touch. Null when there is no repository or no origin.
+ * network touch. Null when there is no repository or no origin. Inherited
+ * repository-location vars are dropped so the answer is always about
+ * `storeRoot`: root selection runs this from wherever the CLI started,
+ * including inside another repository's git hook.
  */
 export async function gitOriginUrl(storeRoot) {
-    const stdout = await gitProbe(storeRoot, ['remote', 'get-url', 'origin']);
+    const stdout = await gitProbe(storeRoot, ['remote', 'get-url', 'origin'], {
+        env: envWithoutGitRepoLocation(),
+    });
     const url = stdout?.trim();
     return url ? url : null;
 }
+/**
+ * The repository name from an origin URL, with no host or `.git` suffix.
+ * Handles the three common remote spellings:
+ *
+ * - `git@github.com:user/repo.git`
+ * - `https://github.com/user/repo.git`
+ * - `ssh://git@github.com/user/repo.git`
+ *
+ * Returns the last path segment, or `null` when the URL has no parseable name.
+ */
+export function repoNameFromGitUrl(url) {
+    const cleaned = url.trim().replace(/\.git\/?$/i, '');
+    let path = null;
+    // URL-like: scheme://host[/user/repo]. The `://` is required, so scp-like
+    // `git@host:user/repo` (no scheme) never matches this branch.
+    const urlLike = cleaned.match(/^[a-z][a-z0-9+.-]*:\/\/[^/]+(?:\/(.*))?$/i);
+    if (urlLike) {
+        path = urlLike[1] ?? null;
+    }
+    else {
+        // scp-like: git@host:user/repo
+        const scpLike = cleaned.match(/^(?:[\w.-]+@)?[\w.-]+:(.+)$/);
+        path = scpLike ? scpLike[1] : null;
+    }
+    if (!path)
+        return null;
+    const segments = path.split('/').filter(Boolean);
+    const last = segments[segments.length - 1];
+    return last && last !== '.' && last !== '..' ? last : null;
+}
 /**
  * Ahead/behind counts of HEAD against its configured upstream tracking
  * ref, read from local refs only — no fetch, no network. The comparison

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

@@ -12,8 +12,10 @@ export declare class Validator {
      * Validate delta-formatted spec files under a change directory.
      * Enforces:
      * - At least one delta across all files
-     * - ADDED/MODIFIED: each requirement has at least one scenario; missing
-     *   English SHALL/MUST keywords are guidance unless strict mode is enabled
+     * - ADDED/MODIFIED: each requirement has at least one scenario; a scenario
+     *   with no WHEN/GIVEN or THEN step is guidance (WARNING) unless strict mode
+     *   is enabled; missing English SHALL/MUST keywords are guidance unless
+     *   strict mode is enabled
      * - REMOVED: names only; no scenario/description required
      * - RENAMED: pairs well-formed
      * - No duplicates within sections; no cross-section conflicts per spec
@@ -90,6 +92,14 @@ export declare class Validator {
     private findScenarioLossIssues;
     private formatInvalidMarkerMessage;
     private convertZodErrors;
+    /**
+     * Every guidance and error the main-spec path emits about one spec file
+     * (#1156, #243): structure, a placeholder or too-brief Purpose, requirement
+     * length, a requirement with no scenario, a missing English SHALL/MUST in the
+     * body, and a counted scenario with no trigger or outcome. The step check is
+     * the same one the delta path runs, on the same `#### ` blocks, so a scenario
+     * that asserts nothing is reported wherever it lives.
+     */
     private applySpecRules;
     private applyChangeRules;
     private enrichTopLevelError;
@@ -124,6 +134,21 @@ export declare class Validator {
      * not count it. Empty when the block has no bare scenario header.
      */
     private emptyScenarioHint;
+    /**
+     * A counted scenario whose body carries neither a **WHEN** (or **GIVEN**)
+     * step nor a **THEN** step can never fail: nothing triggers it and nothing
+     * is asserted (#2078). Read from the same blocks the scenario-loss comparison
+     * walks, so the two checks cannot disagree about what a scenario is.
+     * Only `Scenario:`-labeled blocks are checked: any level-4 child counts as a
+     * scenario for loss purposes, but an unlabeled `#### Notes` child is prose
+     * on purpose, and a missing WHEN/THEN there is noise, not a finding.
+     *
+     * A WARNING, like the missing SHALL/MUST keyword: plain `validate` and
+     * `archive` keep agreeing, and `--strict` — which already fails on any
+     * warning — is the bar that enforces it.
+     */
+    private findScenarioStepIssues;
+    /** Render a list of section names as prose: `a`, `a and b`, `a, b and c`. */
     private formatSectionList;
 }
 //# sourceMappingURL=validator.d.ts.map

package/dist/core/validation/validator.js

@@ -5,8 +5,8 @@ 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, diffScenarioNames, describeScenarioBalance, describeUnappliedContent, } from '../parsers/requirement-blocks.js';
-import { extractRequirementBody as extractRequirementBodyShared, containsShallOrMust as containsShallOrMustShared, countScenarios as countScenariosShared, countEmptyScenarios, } from '../parsers/requirement-text.js';
+import { parseDeltaSpec, foldRequirementName, normalizeRequirementName, extractRequirementsSection, diffScenarioNames, describeScenarioBalance, parseScenarioBlocks, isScenarioLabeledHeader, describeUnappliedContent, } from '../parsers/requirement-blocks.js';
+import { extractRequirementBody as extractRequirementBodyShared, containsShallOrMust as containsShallOrMustShared, countScenarios as countScenariosShared, countEmptyScenarios, hasScenarioBody, scenarioStepCoverage, } from '../parsers/requirement-text.js';
 import { findMainSpecStructureIssues } from '../parsers/spec-structure.js';
 import { FileSystemUtils } from '../../utils/file-system.js';
 import { assertDiscoveredSpecFile } from '../../utils/spec-path-containment.js';
@@ -108,8 +108,10 @@ export class Validator {
      * Validate delta-formatted spec files under a change directory.
      * Enforces:
      * - At least one delta across all files
-     * - ADDED/MODIFIED: each requirement has at least one scenario; missing
-     *   English SHALL/MUST keywords are guidance unless strict mode is enabled
+     * - ADDED/MODIFIED: each requirement has at least one scenario; a scenario
+     *   with no WHEN/GIVEN or THEN step is guidance (WARNING) unless strict mode
+     *   is enabled; missing English SHALL/MUST keywords are guidance unless
+     *   strict mode is enabled
      * - REMOVED: names only; no scenario/description required
      * - RENAMED: pairs well-formed
      * - No duplicates within sections; no cross-section conflicts per spec
@@ -278,6 +280,7 @@ export class Validator {
                     if (scenarioCount < 1) {
                         issues.push({ level: 'ERROR', path: entryPath, message: `ADDED "${block.name}" must include at least one scenario${this.emptyScenarioHint(block.raw)}` });
                     }
+                    issues.push(...this.findScenarioStepIssues(block.raw, `ADDED "${block.name}"`, entryPath));
                 }
                 // Validate MODIFIED
                 for (const block of plan.modified) {
@@ -310,6 +313,7 @@ export class Validator {
                     if (scenarioCount < 1) {
                         issues.push({ level: 'ERROR', path: entryPath, message: `MODIFIED "${block.name}" must include at least one scenario${this.emptyScenarioHint(block.raw)}` });
                     }
+                    issues.push(...this.findScenarioStepIssues(block.raw, `MODIFIED "${block.name}"`, entryPath));
                 }
                 // Run archive's scenario-loss check here too, so the change fails at
                 // authoring time instead of days later at archive time (#1477).
@@ -698,6 +702,14 @@ export class Validator {
             };
         });
     }
+    /**
+     * Every guidance and error the main-spec path emits about one spec file
+     * (#1156, #243): structure, a placeholder or too-brief Purpose, requirement
+     * length, a requirement with no scenario, a missing English SHALL/MUST in the
+     * body, and a counted scenario with no trigger or outcome. The step check is
+     * the same one the delta path runs, on the same `#### ` blocks, so a scenario
+     * that asserts nothing is reported wherever it lives.
+     */
     applySpecRules(spec, content) {
         const issues = [];
         for (const structuralIssue of findMainSpecStructureIssues(content)) {
@@ -767,6 +779,9 @@ export class Validator {
                     message: this.buildMissingShallOrMustMessage(`Requirement "${block.name}"`, block.name, true),
                 });
             }
+            // Same step check the delta path runs, on the same blocks, so a scenario
+            // that asserts nothing is reported wherever it lives.
+            issues.push(...this.findScenarioStepIssues(block.raw, `Requirement "${block.name}"`, `requirements[${index}].scenarios`));
         });
         return issues;
     }
@@ -941,6 +956,45 @@ export class Validator {
             return '';
         return ' (a scenario header with no body under it does not count; add its steps, e.g. "- **WHEN** ..." and "- **THEN** ...")';
     }
+    /**
+     * A counted scenario whose body carries neither a **WHEN** (or **GIVEN**)
+     * step nor a **THEN** step can never fail: nothing triggers it and nothing
+     * is asserted (#2078). Read from the same blocks the scenario-loss comparison
+     * walks, so the two checks cannot disagree about what a scenario is.
+     * Only `Scenario:`-labeled blocks are checked: any level-4 child counts as a
+     * scenario for loss purposes, but an unlabeled `#### Notes` child is prose
+     * on purpose, and a missing WHEN/THEN there is noise, not a finding.
+     *
+     * A WARNING, like the missing SHALL/MUST keyword: plain `validate` and
+     * `archive` keep agreeing, and `--strict` — which already fails on any
+     * warning — is the bar that enforces it.
+     */
+    findScenarioStepIssues(blockRaw, label, issuePath) {
+        const issues = [];
+        for (const scenario of parseScenarioBlocks(blockRaw)) {
+            // A header with no body is already an ERROR with its own hint; a step
+            // complaint on top of it would say nothing new. parseScenarioBlocks keeps
+            // the header line in `raw`, and hasScenarioBody takes the body alone.
+            const bodyLines = scenario.raw.split('\n').slice(1).join('\n');
+            if (!hasScenarioBody(bodyLines))
+                continue;
+            if (!isScenarioLabeledHeader(scenario.raw.split('\n')[0]))
+                continue;
+            const { hasTrigger, hasOutcome } = scenarioStepCoverage(scenario.raw);
+            if (hasTrigger && hasOutcome)
+                continue;
+            const missing = [!hasTrigger && 'a WHEN/GIVEN step', !hasOutcome && 'a THEN step']
+                .filter((part) => part !== false)
+                .join(' and ');
+            issues.push({
+                level: 'WARNING',
+                path: issuePath,
+                message: `${label}: scenario "${scenario.name}" is missing ${missing}. A scenario needs a trigger and an outcome, e.g. "- **WHEN** an invoice is voided" and "- **THEN** a credit note is issued".`,
+            });
+        }
+        return issues;
+    }
+    /** Render a list of section names as prose: `a`, `a and b`, `a, b and c`. */
     formatSectionList(sections) {
         if (sections.length === 0)
             return '';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fission-ai/openspec",
-  "version": "1.15.0",
+  "version": "1.16.0",
   "description": "AI-native system for spec-driven development",
   "keywords": [
     "openspec",
@@ -38,7 +38,7 @@
     "!dist/**/*.map"
   ],
   "engines": {
-    "node": ">=20.19.0"
+    "node": ">=22.12.0"
   },
   "devDependencies": {
     "@changesets/changelog-github": "^1.0.0",
@@ -50,7 +50,7 @@
     "smol-toml": "^1.7.1",
     "typescript": "^6.0.3",
     "typescript-eslint": "^8.65.0",
-    "vite": "^7.3.7",
+    "vite": "^8.3.5",
     "vitest": "^4.1.12"
   },
   "dependencies": {

package/schemas/spec-driven/schema.yaml

@@ -105,6 +105,7 @@ artifacts:
       - Each scenario: `#### Scenario: <name>` with WHEN/THEN format
       - **CRITICAL**: Scenarios MUST use exactly 4 hashtags (`####`). Using 3 hashtags or bullets will fail silently.
       - Every requirement MUST have at least one scenario.
+      - Every scenario MUST have a WHEN/GIVEN step (its trigger) and a THEN step (its outcome). A scenario with only AND lines or plain prose still counts as a scenario, but `openspec validate` flags it as a warning: normal validation still passes, but `openspec validate --strict` fails on it.
       - Keep each requirement's description (the text between `### Requirement:` and its first scenario) to 500 characters or fewer. `openspec validate` flags longer descriptions in ADDED requirements and in the main spec. This is a warning: normal validation still passes, but `openspec validate --strict` fails on it. When writing a new requirement, state one behavior per requirement: move examples and edge cases into scenarios, and split a requirement that covers several behaviors into separate `### Requirement:` blocks, each with its own scenarios. Under MODIFIED, keep the existing requirement block whole; never split, trim or rewrite existing text just to meet the length. Split an existing long requirement only when the user asks for it, in a change made for that purpose: under MODIFIED, keep its header and every scenario and cut its description down to one behavior without changing its meaning, then add each behavior you removed as its own ADDED requirement with its own scenarios.
 
       New capabilities only: the delta spec's first section is `## Purpose` -