@fission-ai/openspec 1.14.3 → 1.16.0

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/dist/core/version-check.d.ts

@@ -1,3 +1,10 @@
+/**
+ * Called by the standalone binary's entry point. That copy has no package
+ * manager behind it, so a package-manager command is the wrong upgrade advice.
+ */
+export declare function markStandaloneBinary(executablePath: string): void;
+/** The standalone binary's own path, or null when running from a package. */
+export declare function getStandaloneBinaryPath(): string | null;
 /**
  * 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
@@ -79,7 +86,7 @@ export declare function isNpmGlobalInstall(installDir: string | null, roots?: st
  */
 export declare function isSourceCheckout(installDir: string | null): boolean;
 export type PackageManager = 'npm' | 'pnpm' | 'bun' | 'yarn' | 'volta';
-export type InstallScope = 'global' | 'project' | 'temporary' | 'source';
+export type InstallScope = 'global' | 'project' | 'temporary' | 'source' | 'standalone';
 export interface CliInstallInfo {
     location: string | null;
     packageManager: PackageManager | null;

package/dist/core/version-check.js

@@ -3,11 +3,13 @@ import http from 'http';
 import https from 'https';
 import path from 'path';
 import { createRequire } from 'module';
+import { fileURLToPath } from 'url';
 import chalk from 'chalk';
 import { isCiEnvironment } from '../utils/ci.js';
 import { isTelemetryOptedOutByEnv } from '../telemetry/opt-out.js';
 import { FileSystemUtils } from '../utils/file-system.js';
 import { getGlobalConfig, isGlobalConfigUnreadable } from './global-config.js';
+import { findCopiesOnPath, samePath } from '../utils/executable-path.js';
 const require = createRequire(import.meta.url);
 const { name: PACKAGE_NAME, version: OPENSPEC_VERSION } = require('../../package.json');
 const DEFAULT_REGISTRY = 'https://registry.npmjs.org';
@@ -22,6 +24,34 @@ const MAX_REDIRECTS = 3;
  * one could smuggle ANSI cursor controls and repaint the lines around it.
  */
 const SAFE_VERSION = /^\d{1,10}\.\d{1,10}\.\d{1,10}(?:-[0-9A-Za-z.-]{1,64})?(?:\+[0-9A-Za-z.-]{1,64})?$/;
+let standaloneBinaryPath = null;
+/**
+ * Called by the standalone binary's entry point. That copy has no package
+ * manager behind it, so a package-manager command is the wrong upgrade advice.
+ */
+export function markStandaloneBinary(executablePath) {
+    standaloneBinaryPath = executablePath;
+}
+/** The standalone binary's own path, or null when running from a package. */
+export function getStandaloneBinaryPath() {
+    return standaloneBinaryPath;
+}
+/**
+ * `openspec install` reinstalls the standalone binary where it already is,
+ * under its own name, so the new copy cannot end up shadowed by the old one.
+ * Spelled with the full path when `openspec` on PATH is some other copy.
+ * Null when this is not the binary.
+ */
+function standaloneUpgradeCommand() {
+    if (!standaloneBinaryPath)
+        return null;
+    const first = findCopiesOnPath()[0];
+    if (first && samePath(first, standaloneBinaryPath))
+        return 'openspec install';
+    return process.platform === 'win32'
+        ? `& '${standaloneBinaryPath.replace(/'/g, "''")}' install`
+        : `'${standaloneBinaryPath.replace(/'/g, `'\\''`)}' install`;
+}
 /**
  * The check is opt-out and must never get in the way: no network in CI or
  * tests, an explicit escape hatch for anyone offline or air-gapped, and the
@@ -304,12 +334,14 @@ export async function getAvailableCliUpdate() {
  * which copy is actually answering.
  */
 export function getInstallDir() {
-    try {
-        return path.dirname(require.resolve('../../package.json'));
-    }
-    catch {
+    // The binary is not a package install, so no package-manager logic applies.
+    if (standaloneBinaryPath)
         return null;
-    }
+    // Resolved at runtime from this module's own (symlink-resolved) location.
+    // require.resolve would be resolved by the binary's bundler at build time,
+    // baking the build machine's path into it.
+    const packageJson = fileURLToPath(new URL('../../package.json', import.meta.url));
+    return fs.existsSync(packageJson) ? path.dirname(packageJson) : null;
 }
 /**
  * True when the running CLI resolves from a `node_modules` belonging to the
@@ -508,6 +540,9 @@ function detectGlobalPackageManager(installDir) {
 }
 /** Describes the running copy without guessing when its owner is ambiguous. */
 export function getCliInstallInfo(installDir = getInstallDir(), projectPath = '.') {
+    if (standaloneBinaryPath) {
+        return { location: path.dirname(standaloneBinaryPath), packageManager: null, scope: 'standalone' };
+    }
     if (!installDir) {
         return { location: null, packageManager: null, scope: null };
     }
@@ -537,6 +572,8 @@ export function getCliInstallInfo(installDir = getInstallDir(), projectPath = '.
 }
 /** Returns a safe update command only for an install with known global ownership. */
 export function getCliUpdateCommand(install) {
+    if (install.scope === 'standalone')
+        return standaloneUpgradeCommand();
     if (install.scope !== 'global' || install.packageManager === null)
         return null;
     return GLOBAL_UPGRADE_COMMANDS[install.packageManager];
@@ -585,6 +622,12 @@ export function buildCliUpdateLines(latestVersion, installDir, projectPath, opti
  */
 export function buildUpgradeCommandLines(installDir, projectPath) {
     const lines = [];
+    const standalone = standaloneUpgradeCommand();
+    if (standalone) {
+        lines.push(`  ${standalone}`);
+        lines.push('  Then run "openspec update" again to pick up new workflows.');
+        return lines;
+    }
     if (isEphemeralRunnerInstall(installDir)) {
         // That command *is* the update, so there is nothing to run afterwards.
         lines.push(`  npx ${PACKAGE_NAME}@latest update`);

package/dist/utils/executable-path.d.ts

@@ -0,0 +1,5 @@
+/** Every `openspec` on PATH, in the order a shell would find them. */
+export declare function findCopiesOnPath(pathValue?: string, platform?: NodeJS.Platform): string[];
+/** Whether two paths name the same file once symlinks are resolved. */
+export declare function samePath(a: string, b: string): boolean;
+//# sourceMappingURL=executable-path.d.ts.map

package/dist/utils/executable-path.js

@@ -0,0 +1,44 @@
+import fs from 'node:fs';
+import path from 'node:path';
+/** Every `openspec` on PATH, in the order a shell would find them. */
+export function findCopiesOnPath(pathValue = process.env.PATH ?? '', platform = process.platform) {
+    const names = platform === 'win32' ? ['openspec.exe', 'openspec.cmd'] : ['openspec'];
+    const seen = new Set();
+    const copies = [];
+    for (const dir of pathValue.split(path.delimiter)) {
+        if (!dir)
+            continue;
+        for (const name of names) {
+            const candidate = path.join(dir, name);
+            try {
+                if (!fs.statSync(candidate).isFile())
+                    continue;
+                if (platform !== 'win32')
+                    fs.accessSync(candidate, fs.constants.X_OK);
+                const key = platform === 'win32' ? candidate.toLowerCase() : candidate;
+                if (!seen.has(key)) {
+                    seen.add(key);
+                    copies.push(candidate);
+                }
+            }
+            catch {
+                // Not there, or not runnable: not a copy a shell would run.
+            }
+        }
+    }
+    return copies;
+}
+/** Whether two paths name the same file once symlinks are resolved. */
+export function samePath(a, b) {
+    const real = (value) => {
+        try {
+            return fs.realpathSync(value);
+        }
+        catch {
+            return path.resolve(value);
+        }
+    };
+    const [x, y] = [real(a), real(b)];
+    return process.platform === 'win32' ? x.toLowerCase() === y.toLowerCase() : x === y;
+}
+//# sourceMappingURL=executable-path.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fission-ai/openspec",
-  "version": "1.14.3",
+  "version": "1.16.0",
   "description": "AI-native system for spec-driven development",
   "keywords": [
     "openspec",
@@ -38,19 +38,20 @@
     "!dist/**/*.map"
   ],
   "engines": {
-    "node": ">=20.19.0"
+    "node": ">=22.12.0"
   },
   "devDependencies": {
     "@changesets/changelog-github": "^1.0.0",
     "@changesets/cli": "^3.0.1",
     "@types/node": "^20.19.43",
     "@types/picomatch": "^4.0.3",
-    "@vitest/ui": "^4.1.11",
+    "@vitest/ui": "^4.1.12",
     "eslint": "^10.5.0",
     "smol-toml": "^1.7.1",
     "typescript": "^6.0.3",
     "typescript-eslint": "^8.65.0",
-    "vitest": "^4.1.11"
+    "vite": "^8.3.5",
+    "vitest": "^4.1.12"
   },
   "dependencies": {
     "@inquirer/core": "^12.0.0",

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` -