@fission-ai/openspec 1.15.0 → 1.16.1

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

@@ -1,9 +1,8 @@
 import { buildCodeFenceMask } from './code-fence.js';
-import { normalizeRequirementName } from './requirement-blocks.js';
-const REQUIREMENTS_SECTION_HEADER = /^##\s+Requirements\s*$/i;
+import { normalizeRequirementName, REQUIREMENTS_SECTION_HEADER_REGEX as REQUIREMENTS_SECTION_HEADER, } from './requirement-blocks.js';
 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 DELTA_HEADER = /^##\s+(ADDED|MODIFIED|REMOVED|RENAMED)\s+Requirements(?:[ \t]+#+)?\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/specs-apply.js

@@ -8,7 +8,7 @@ import { promises as fs } from 'fs';
 import { randomUUID } from 'crypto';
 import path from 'path';
 import chalk from 'chalk';
-import { extractRequirementsSection, diffScenarioNames, describeScenarioBalance, describeUnappliedContent, foldRequirementName, parseDeltaSpec, normalizeRequirementName, } from './parsers/requirement-blocks.js';
+import { extractRequirementsSection, diffScenarioNames, describeScenarioBalance, describeUnappliedContent, foldRequirementName, isUnrecognizedDeltaSection, parseDeltaSpec, normalizeRequirementName, } from './parsers/requirement-blocks.js';
 import { findMainSpecStructureIssues } from './parsers/spec-structure.js';
 import { buildCodeFenceMask } from './parsers/code-fence.js';
 import { MarkdownParser } from './parsers/markdown-parser.js';
@@ -137,7 +137,15 @@ export async function buildUpdatedSpec(update, changeName, options = {}) {
     // A well-formed requirement written outside every delta section is not
     // applied. Say so here as well as in validate: archive is the last point at
     // which the author can still notice, and the block reads exactly like one
-    // that would have applied.
+    // that would have applied. Under an unrecognized `## ... Requirements`
+    // header it was meant as a delta operation, so refuse rather than drop it -
+    // the same verdict validate gives (#2195).
+    const misplaced = plan.orphanedRequirements.find((o) => isUnrecognizedDeltaSection(o.section));
+    if (misplaced) {
+        throw new Error(`${specName} validation failed - requirement "${misplaced.name}" (line ${misplaced.line}) is under ` +
+            `"## ${misplaced.section}", which is not a delta section, so it would not be applied. ` +
+            `Move it under ADDED/MODIFIED/REMOVED/RENAMED Requirements.`);
+    }
     for (const orphan of plan.orphanedRequirements) {
         const where = orphan.section
             ? `under "## ${orphan.section}"`
@@ -1141,7 +1149,7 @@ function extractPurposeSection(content) {
     const masked = maskHtmlComments(normalized).split('\n');
     const fenceMask = buildCodeFenceMask(masked);
     const isStructural = (i) => !fenceMask[i];
-    const start = masked.findIndex((line, i) => isStructural(i) && /^##\s+Purpose\s*$/i.test(line));
+    const start = masked.findIndex((line, i) => isStructural(i) && /^##\s+Purpose(?:[ \t]+#+)?\s*$/i.test(line));
     if (start === -1)
         return undefined;
     let end = masked.length;

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/purpose-placeholder.js

@@ -25,7 +25,7 @@ const MARKER_PUNCTUATION = '(?=[ \\t]*(?:$|\\n|[:\\-\u2013\u2014.,;()\\[\\]{}]))
 const LEADING_MARKER_SHOUTED = new RegExp(`^(?:TBD|TODO)${WORD_END}`, 'u');
 /** Any other case: a marker only when punctuation or the line end says so. */
 const LEADING_MARKER_PUNCTUATED = new RegExp(`^(?:TBD|TODO)${WORD_END}${MARKER_PUNCTUATION}`, 'iu');
-const PURPOSE_HEADER = /^ {0,3}##(?!#)[ \t]+Purpose[ \t]*$/i;
+const PURPOSE_HEADER = /^ {0,3}##(?!#)[ \t]+Purpose(?:[ \t]+#+)?[ \t]*$/i;
 const TOP_LEVEL_HEADER = /^ {0,3}#{1,2}(?!#)[ \t]+/;
 /**
  * The lines of `text` that sit outside a fenced code block, with line endings

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, isUnrecognizedDeltaSection, } 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
@@ -193,12 +195,15 @@ export class Validator {
                 // ignored - reported as a WARNING rather than an ERROR because a
                 // handful of pre-format archived changes still carry this shape, and
                 // the fix is to move the block, not to reject the change outright.
+                // Under an unrecognized `## ... Requirements` header it is an ERROR:
+                // that header reads as a delta operation, so the requirement was meant
+                // to be applied and archive refuses it too (#2195).
                 for (const orphan of plan.orphanedRequirements) {
                     const where = orphan.section
                         ? `under "## ${orphan.section}"`
                         : 'above the first "## " section';
                     issues.push({
-                        level: 'WARNING',
+                        level: isUnrecognizedDeltaSection(orphan.section) ? 'ERROR' : 'WARNING',
                         path: entryPath,
                         line: orphan.line,
                         message: `Requirement "${orphan.name}" is ${where}, which is not a delta section, so it is ignored. Move it under "## ADDED Requirements", "## MODIFIED Requirements", "## REMOVED Requirements", or "## RENAMED Requirements".`,
@@ -278,6 +283,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 +316,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 +705,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 +782,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 +959,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

@@ -28,9 +28,12 @@ export interface CliUpdateCheck {
 }
 /**
  * Checks the registry while preserving enough detail for callers to explain
- * why no newer version was reported. Never throws.
+ * why no newer version was reported. Never throws. Pass `requested` only when
+ * the user explicitly asked for the check.
  */
-export declare function checkForCliUpdate(): Promise<CliUpdateCheck>;
+export declare function checkForCliUpdate(options?: {
+    requested?: boolean;
+}): Promise<CliUpdateCheck>;
 /**
  * Returns the published version when the installed CLI is behind it, otherwise
  * null. Kept as the compatibility surface used by `openspec update`.