@fission-ai/openspec 1.6.0 → 1.8.0

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

@@ -19,6 +19,9 @@ export declare const VALIDATION_MESSAGES: {
     readonly CHANGE_WHY_TOO_LONG: "Why section should not exceed 1000 characters";
     readonly CHANGE_WHAT_EMPTY: "What Changes section cannot be empty";
     readonly CHANGE_NO_DELTAS: "Change must have at least one delta";
+    readonly CHANGE_SKIP_SPECS_CONFLICT: "skip_specs is set in .openspec.yaml but spec files exist under specs/. Remove skip_specs or delete the delta spec files";
+    readonly CHANGE_SKIP_SPECS_ACCEPTED: "skip_specs is set in .openspec.yaml: change declares no spec-level behavior changes, zero deltas accepted";
+    readonly CHANGE_SKIP_SPECS_INVALID_METADATA: "skip_specs is set but .openspec.yaml is not valid change metadata, so the marker is not honored. Fix the metadata";
     readonly CHANGE_TOO_MANY_DELTAS: "Consider splitting changes with more than 10 deltas";
     readonly DELTA_SPEC_EMPTY: "Spec name cannot be empty";
     readonly DELTA_DESCRIPTION_EMPTY: "Delta description cannot be empty";
@@ -26,7 +29,7 @@ export declare const VALIDATION_MESSAGES: {
     readonly REQUIREMENT_TOO_LONG: "Requirement text is very long (>500 characters). Consider breaking it down.";
     readonly DELTA_DESCRIPTION_TOO_BRIEF: "Delta description is too brief";
     readonly DELTA_MISSING_REQUIREMENTS: "Delta should include requirements";
-    readonly GUIDE_NO_DELTAS: "No deltas found. Ensure your change has a specs/ directory with capability folders (e.g. specs/http-server/spec.md) containing .md files that use delta headers (## ADDED/MODIFIED/REMOVED/RENAMED Requirements) and that each requirement includes at least one \"#### Scenario:\" block. Tip: run \"openspec change show <change-id> --json --deltas-only\" to inspect parsed deltas.";
+    readonly GUIDE_NO_DELTAS: "No deltas found. Ensure your change has a specs/ directory with capability folders (e.g. specs/http-server/spec.md) containing .md files that use delta headers (## ADDED/MODIFIED/REMOVED/RENAMED Requirements) and that each requirement includes at least one \"#### Scenario:\" block. If this change intentionally modifies no specs (pure refactor, tooling, docs), set \"skip_specs: true\" in the change's .openspec.yaml instead. Tip: run \"openspec change show <change-id> --json --deltas-only\" to inspect parsed deltas.";
     readonly GUIDE_MISSING_SPEC_SECTIONS: "Missing required sections. Expected headers: \"## Purpose\" and \"## Requirements\". Example:\n## Purpose\n[brief purpose]\n\n## Requirements\n### Requirement: Clear requirement statement\nUsers SHALL ...\n\n#### Scenario: Descriptive name\n- **WHEN** ...\n- **THEN** ...";
     readonly GUIDE_MISSING_CHANGE_SECTIONS: "Missing required sections. Expected headers: \"## Why\" and \"## What Changes\". Ensure deltas are documented in specs/ using delta headers.";
     readonly GUIDE_SCENARIO_FORMAT: "Scenarios must use level-4 headers. Convert bullet lists into:\n#### Scenario: Short name\n- **WHEN** ...\n- **THEN** ...\n- **AND** ...";

package/dist/core/validation/constants.js

@@ -23,6 +23,9 @@ export const VALIDATION_MESSAGES = {
     CHANGE_WHY_TOO_LONG: `Why section should not exceed ${MAX_WHY_SECTION_LENGTH} characters`,
     CHANGE_WHAT_EMPTY: 'What Changes section cannot be empty',
     CHANGE_NO_DELTAS: 'Change must have at least one delta',
+    CHANGE_SKIP_SPECS_CONFLICT: 'skip_specs is set in .openspec.yaml but spec files exist under specs/. Remove skip_specs or delete the delta spec files',
+    CHANGE_SKIP_SPECS_ACCEPTED: 'skip_specs is set in .openspec.yaml: change declares no spec-level behavior changes, zero deltas accepted',
+    CHANGE_SKIP_SPECS_INVALID_METADATA: 'skip_specs is set but .openspec.yaml is not valid change metadata, so the marker is not honored. Fix the metadata',
     CHANGE_TOO_MANY_DELTAS: `Consider splitting changes with more than ${MAX_DELTAS_PER_CHANGE} deltas`,
     DELTA_SPEC_EMPTY: 'Spec name cannot be empty',
     DELTA_DESCRIPTION_EMPTY: 'Delta description cannot be empty',
@@ -32,7 +35,7 @@ export const VALIDATION_MESSAGES = {
     DELTA_DESCRIPTION_TOO_BRIEF: 'Delta description is too brief',
     DELTA_MISSING_REQUIREMENTS: 'Delta should include requirements',
     // Guidance snippets (appended to primary messages for remediation)
-    GUIDE_NO_DELTAS: 'No deltas found. Ensure your change has a specs/ directory with capability folders (e.g. specs/http-server/spec.md) containing .md files that use delta headers (## ADDED/MODIFIED/REMOVED/RENAMED Requirements) and that each requirement includes at least one "#### Scenario:" block. Tip: run "openspec change show <change-id> --json --deltas-only" to inspect parsed deltas.',
+    GUIDE_NO_DELTAS: 'No deltas found. Ensure your change has a specs/ directory with capability folders (e.g. specs/http-server/spec.md) containing .md files that use delta headers (## ADDED/MODIFIED/REMOVED/RENAMED Requirements) and that each requirement includes at least one "#### Scenario:" block. If this change intentionally modifies no specs (pure refactor, tooling, docs), set "skip_specs: true" in the change\'s .openspec.yaml instead. Tip: run "openspec change show <change-id> --json --deltas-only" to inspect parsed deltas.',
     GUIDE_MISSING_SPEC_SECTIONS: 'Missing required sections. Expected headers: "## Purpose" and "## Requirements". Example:\n## Purpose\n[brief purpose]\n\n## Requirements\n### Requirement: Clear requirement statement\nUsers SHALL ...\n\n#### Scenario: Descriptive name\n- **WHEN** ...\n- **THEN** ...',
     GUIDE_MISSING_CHANGE_SECTIONS: 'Missing required sections. Expected headers: "## Why" and "## What Changes". Ensure deltas are documented in specs/ using delta headers.',
     GUIDE_SCENARIO_FORMAT: 'Scenarios must use level-4 headers. Convert bullet lists into:\n#### Scenario: Short name\n- **WHEN** ...\n- **THEN** ...\n- **AND** ...',

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

@@ -12,19 +12,33 @@ 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 SHALL/MUST and at least one scenario
+     * - ADDED/MODIFIED: each requirement has at least one scenario; 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
+     *
+     * When `options.mainSpecsDir` is given, MODIFIED blocks are also checked
+     * against the current main specs for the scenario loss archive refuses to
+     * apply (#1477). Omitting it keeps the change-only checks, so callers with
+     * no main specs root (and existing library callers) behave as before.
      */
-    validateChangeDeltaSpecs(changeDir: string): Promise<ValidationReport>;
+    validateChangeDeltaSpecs(changeDir: string, options?: {
+        mainSpecsDir?: string;
+    }): Promise<ValidationReport>;
     /**
-     * Recursively collect every delta `spec.md` under a change's specs directory,
-     * so both the one-level (specs/<capability>/spec.md) and nested multi-area
-     * (specs/<area>/<capability>/spec.md) layouts are discovered (#1182b).
-     * Returns absolute paths, sorted for deterministic issue ordering.
+     * Report MODIFIED requirements whose block omits a scenario the main spec
+     * still carries. Uses the same comparison archive applies, so validate can
+     * only report what archive would refuse.
+     *
+     * Silent when the main spec or the requirement header is absent: applying a
+     * MODIFIED against a base that is not there yet is a different failure (a
+     * sister change still in flight is the legitimate case), and archive is the
+     * gate for it. A spec that exists but cannot be read is not absent, though —
+     * archive aborts on it, so reporting it beats calling the change valid.
      */
-    private findDeltaSpecFiles;
+    private findScenarioLossIssues;
+    private formatInvalidMarkerMessage;
     private convertZodErrors;
     private applySpecRules;
     private applyChangeRules;
@@ -35,7 +49,7 @@ export declare class Validator {
     private extractRequirementText;
     private containsShallOrMust;
     /**
-     * Build an error message for a requirement block whose body lacks SHALL/MUST.
+     * Build a message for a requirement block whose body lacks SHALL/MUST.
      *
      * When the SHALL/MUST keyword already appears in the requirement header (e.g.
      * `### Requirement: The system SHALL ...`) the original generic error

package/dist/core/validation/validator.js

@@ -4,10 +4,12 @@ import { SpecSchema, ChangeSchema } from '../schemas/index.js';
 import { MarkdownParser } from '../parsers/markdown-parser.js';
 import { ChangeParser } from '../parsers/change-parser.js';
 import { MIN_PURPOSE_LENGTH, MAX_REQUIREMENT_TEXT_LENGTH, VALIDATION_MESSAGES } from './constants.js';
-import { parseDeltaSpec, normalizeRequirementName, extractRequirementsSection } from '../parsers/requirement-blocks.js';
+import { parseDeltaSpec, foldRequirementName, normalizeRequirementName, extractRequirementsSection, findMissingCurrentScenarios, } from '../parsers/requirement-blocks.js';
 import { extractRequirementBody as extractRequirementBodyShared, containsShallOrMust as containsShallOrMustShared, countScenarios as countScenariosShared, } from '../parsers/requirement-text.js';
 import { findMainSpecStructureIssues } from '../parsers/spec-structure.js';
 import { FileSystemUtils } from '../../utils/file-system.js';
+import { discoverSpecFiles, hasAnyFileUnder } from '../../utils/spec-discovery.js';
+import { METADATA_FILENAME, readSkipSpecsMarker } from '../../utils/change-metadata.js';
 export class Validator {
     strictMode;
     constructor(strictMode = false) {
@@ -67,8 +69,20 @@ export class Validator {
             const parser = new ChangeParser(content, changeDir);
             const change = await parser.parseChangeWithDeltas(changeName);
             const result = ChangeSchema.safeParse(change);
+            const marker = readSkipSpecsMarker(changeDir);
+            if (marker.invalidReason) {
+                issues.push({ level: 'ERROR', path: METADATA_FILENAME, message: this.formatInvalidMarkerMessage(marker.invalidReason) });
+            }
             if (!result.success) {
-                issues.push(...this.convertZodErrors(result.error));
+                let zodIssues = this.convertZodErrors(result.error);
+                // Only the no-deltas error is marker-aware here: the marker+files
+                // conflict is validateChangeDeltaSpecs's job, and every caller of
+                // this proposal-level pass (archive's non-blocking warnings) pairs
+                // it with that gate.
+                if (marker.declared) {
+                    zodIssues = zodIssues.filter(issue => !issue.message.startsWith(VALIDATION_MESSAGES.CHANGE_NO_DELTAS));
+                }
+                issues.push(...zodIssues);
             }
             issues.push(...this.applyChangeRules(change, content));
         }
@@ -87,24 +101,46 @@ 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 SHALL/MUST and at least one scenario
+     * - ADDED/MODIFIED: each requirement has at least one scenario; 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
+     *
+     * When `options.mainSpecsDir` is given, MODIFIED blocks are also checked
+     * against the current main specs for the scenario loss archive refuses to
+     * apply (#1477). Omitting it keeps the change-only checks, so callers with
+     * no main specs root (and existing library callers) behave as before.
      */
-    async validateChangeDeltaSpecs(changeDir) {
+    async validateChangeDeltaSpecs(changeDir, options = {}) {
         const issues = [];
         const specsDir = path.join(changeDir, 'specs');
         let totalDeltas = 0;
+        let hasRootLevelSpec = false;
         const missingHeaderSpecs = [];
         const emptySectionSpecs = [];
         try {
-            // Discover delta specs at any depth so the nested multi-area layout
-            // (specs/<area>/<capability>/spec.md) is validated, not just the
-            // one-level specs/<capability>/spec.md layout (#1182b). The spec-driven
-            // specs glob is specs/**/*.md; delta files are always named spec.md.
-            const specFiles = await this.findDeltaSpecFiles(specsDir);
-            for (const specFile of specFiles) {
+            // Discover delta specs through the same helper the change parser, show,
+            // apply, and archive use, so validate never accepts a layout the merge
+            // path silently skips (#1385). It finds spec.md at any depth, covering
+            // both specs/<capability>/spec.md and the nested multi-area
+            // specs/<area>/<capability>/spec.md layout (#1182b).
+            const discoveredSpecs = await discoverSpecFiles(specsDir);
+            // A spec.md directly at the specs/ root has no capability folder, so the
+            // merge path drops it: without this error the change validates clean and
+            // archives while its requirements never reach openspec/specs/ (#1385).
+            // Only a regular file counts — a *directory* named spec.md is a capability
+            // folder like any other, and discoverSpecFiles reads it normally.
+            const rootSpecStat = await fs.stat(path.join(specsDir, 'spec.md')).catch(() => null);
+            hasRootLevelSpec = rootSpecStat?.isFile() === true;
+            if (hasRootLevelSpec) {
+                issues.push({
+                    level: 'ERROR',
+                    path: 'spec.md',
+                    message: 'Delta spec found at specs/spec.md. Delta specs must live under a capability path (e.g. specs/<capability-path>/spec.md) — a file at the specs/ root is ignored when the change is applied or archived.',
+                });
+            }
+            for (const { id: specId, specFile } of discoveredSpecs) {
                 let content;
                 try {
                     content = await fs.readFile(specFile, 'utf-8');
@@ -174,7 +210,11 @@ export class Validator {
                         });
                     }
                     else if (!this.containsShallOrMust(requirementText)) {
-                        issues.push({ level: 'ERROR', path: entryPath, message: this.buildMissingShallOrMustMessage(`ADDED "${block.name}"`, block.name) });
+                        issues.push({
+                            level: 'WARNING',
+                            path: entryPath,
+                            message: this.buildMissingShallOrMustMessage(`ADDED "${block.name}"`, block.name, true),
+                        });
                     }
                     const scenarioCount = this.countScenarios(block.raw);
                     if (scenarioCount < 1) {
@@ -202,13 +242,24 @@ export class Validator {
                         });
                     }
                     else if (!this.containsShallOrMust(requirementText)) {
-                        issues.push({ level: 'ERROR', path: entryPath, message: this.buildMissingShallOrMustMessage(`MODIFIED "${block.name}"`, block.name) });
+                        issues.push({
+                            level: 'WARNING',
+                            path: entryPath,
+                            message: this.buildMissingShallOrMustMessage(`MODIFIED "${block.name}"`, block.name, true),
+                        });
                     }
                     const scenarioCount = this.countScenarios(block.raw);
                     if (scenarioCount < 1) {
                         issues.push({ level: 'ERROR', path: entryPath, message: `MODIFIED "${block.name}" must include at least one scenario` });
                     }
                 }
+                // Run archive's scenario-loss check here too, so the change fails at
+                // authoring time instead of days later at archive time (#1477).
+                if (options.mainSpecsDir && plan.modified.length > 0) {
+                    const mainSpecFile = path.join(options.mainSpecsDir, ...specId.split('/'), 'spec.md');
+                    FileSystemUtils.assertPathWithin(path.dirname(mainSpecFile), mainSpecFile);
+                    issues.push(...(await this.findScenarioLossIssues(plan.modified, plan.renamed, mainSpecFile, entryPath, path.dirname(mainSpecFile))));
+                }
                 // Validate REMOVED (names only)
                 for (const name of plan.removed) {
                     const key = normalizeRequirementName(name);
@@ -261,11 +312,30 @@ export class Validator {
                     if (addedNames.has(toKey)) {
                         issues.push({ level: 'ERROR', path: entryPath, message: `RENAMED TO collides with ADDED for "${to}"` });
                     }
+                    // Folded comparison: a case/whitespace variant of the FROM header
+                    // in REMOVED is the same contradiction, not a different name.
+                    const removedFoldMatch = [...removedNames].find((r) => foldRequirementName(r) === foldRequirementName(fromKey));
+                    if (removedFoldMatch !== undefined) {
+                        issues.push({
+                            level: 'ERROR',
+                            path: entryPath,
+                            message: `Requirement present in both RENAMED and REMOVED: "${from}"` +
+                                (removedFoldMatch === fromKey ? '' : ` (REMOVED spells it "${removedFoldMatch}")`),
+                        });
+                    }
                 }
             }
         }
-        catch {
-            // If no specs dir, treat as no deltas
+        catch (error) {
+            // A missing specs dir (or a stray `specs` file) means no deltas;
+            // anything else (EACCES, EIO) must stay loud — discoverSpecFiles
+            // documents that silently dropping an unreadable capability recreates
+            // the data-loss class it prevents, and archive lets the same error
+            // propagate.
+            const code = error?.code;
+            if (code !== 'ENOENT' && code !== 'ENOTDIR') {
+                throw error;
+            }
         }
         for (const { path: specPath, sections } of emptySectionSpecs) {
             issues.push({
@@ -281,39 +351,134 @@ export class Validator {
                 message: 'No delta sections found. Add headers such as "## ADDED Requirements" or move non-delta notes outside specs/.',
             });
         }
-        if (totalDeltas === 0) {
-            issues.push({ level: 'ERROR', path: 'file', message: this.enrichTopLevelError('change', VALIDATION_MESSAGES.CHANGE_NO_DELTAS) });
+        const marker = readSkipSpecsMarker(changeDir);
+        if (marker.invalidReason) {
+            issues.push({ level: 'ERROR', path: METADATA_FILENAME, message: this.formatInvalidMarkerMessage(marker.invalidReason) });
         }
-        return this.createReport(issues);
-    }
-    /**
-     * Recursively collect every delta `spec.md` under a change's specs directory,
-     * so both the one-level (specs/<capability>/spec.md) and nested multi-area
-     * (specs/<area>/<capability>/spec.md) layouts are discovered (#1182b).
-     * Returns absolute paths, sorted for deterministic issue ordering.
-     */
-    async findDeltaSpecFiles(specsDir) {
-        const results = [];
-        const walk = async (dir) => {
-            let entries;
+        // ANY file under specs/ contradicts the marker - not just parsed deltas.
+        // Headerless or stray files would be silently dropped at archive time (and
+        // some still satisfy the artifact graph's specs/**  glob) while the change
+        // claims to have nothing, so they must surface as an explicit conflict.
+        // Probed only when the marker is declared, and unreadable specs/ (a stray
+        // `specs` file, permission errors) fails closed as a conflict: the marker
+        // claims nothing is there, and validate must not crash where the
+        // historical path degraded to "no deltas".
+        const skipSpecs = marker.declared;
+        let specsDirHasFiles = false;
+        if (skipSpecs) {
             try {
-                entries = await fs.readdir(dir, { withFileTypes: true });
+                specsDirHasFiles = await hasAnyFileUnder(specsDir);
             }
             catch {
-                return;
+                specsDirHasFiles = true;
             }
-            for (const entry of entries) {
-                const full = path.join(dir, entry.name);
-                if (entry.isDirectory()) {
-                    await walk(full);
-                }
-                else if (entry.isFile() && entry.name === 'spec.md') {
-                    results.push(full);
-                }
+        }
+        if (skipSpecs && specsDirHasFiles) {
+            issues.push({ level: 'ERROR', path: 'file', message: VALIDATION_MESSAGES.CHANGE_SKIP_SPECS_CONFLICT });
+        }
+        // The root-level error already names the file and the fix; adding "No
+        // deltas found" on top would contradict it, since the deltas are sitting in
+        // the file just reported.
+        if (totalDeltas === 0 && !hasRootLevelSpec) {
+            if (skipSpecs && !specsDirHasFiles) {
+                issues.push({ level: 'INFO', path: 'file', message: VALIDATION_MESSAGES.CHANGE_SKIP_SPECS_ACCEPTED });
+            }
+            else if (!skipSpecs) {
+                issues.push({ level: 'ERROR', path: 'file', message: this.enrichTopLevelError('change', VALIDATION_MESSAGES.CHANGE_NO_DELTAS) });
+            }
+        }
+        return this.createReport(issues);
+    }
+    /**
+     * Report MODIFIED requirements whose block omits a scenario the main spec
+     * still carries. Uses the same comparison archive applies, so validate can
+     * only report what archive would refuse.
+     *
+     * Silent when the main spec or the requirement header is absent: applying a
+     * MODIFIED against a base that is not there yet is a different failure (a
+     * sister change still in flight is the legitimate case), and archive is the
+     * gate for it. A spec that exists but cannot be read is not absent, though —
+     * archive aborts on it, so reporting it beats calling the change valid.
+     */
+    async findScenarioLossIssues(modified, renamed, mainSpecFile, entryPath, mainSpecRoot) {
+        let mainContent;
+        FileSystemUtils.assertPathWithin(mainSpecRoot, mainSpecFile);
+        try {
+            mainContent = await fs.readFile(mainSpecFile, 'utf-8');
+        }
+        catch (error) {
+            const code = error?.code;
+            // Reported only for the codes that mean the file itself is unusable, and
+            // will be just as unusable when archive reads it. Everything else -
+            // ENOENT/ENOTDIR ("no main spec"), and transient resource errors like
+            // EMFILE that say nothing about the file - stays silent rather than
+            // failing a change that is fine. `validate --all` reads six changes at
+            // once, so a resource error must never become a verdict.
+            const UNUSABLE = new Set(['EACCES', 'EPERM', 'EISDIR', 'ELOOP', 'ENAMETOOLONG']);
+            if (!code || !UNUSABLE.has(code))
+                return [];
+            return [
+                {
+                    level: 'ERROR',
+                    path: entryPath,
+                    message: `Could not read ${FileSystemUtils.toPosixPath(mainSpecFile)} to check the MODIFIED requirements against it ` +
+                        `(${code}). Archive reads the same file, so fix the file before archiving.`,
+                },
+            ];
+        }
+        const currentBlocks = new Map();
+        for (const block of extractRequirementsSection(mainContent).bodyBlocks) {
+            currentBlocks.set(normalizeRequirementName(block.name), block);
+        }
+        // Archive applies RENAMED before MODIFIED, so a MODIFIED naming the new
+        // header is compared against the renamed block's scenarios. Fall back to
+        // the old header, or a rename-plus-modify pair would skip the check.
+        const renamedFrom = new Map(renamed.map(({ from, to }) => [normalizeRequirementName(to), normalizeRequirementName(from)]));
+        // Walked, not looked up once: renames chain (A→B then B→C leaves C holding
+        // A's block), and the visited set stops a cycle from looping forever. Every
+        // name in a rename cycle is also a rename FROM, so the skip above already
+        // keeps the walk out of one; the guard stays because the cost of being
+        // wrong about that is a hung CLI, not a wrong message.
+        const currentBlockFor = (name) => {
+            const visited = new Set();
+            let key = name;
+            while (key !== undefined && !visited.has(key)) {
+                const block = currentBlocks.get(key);
+                if (block)
+                    return block;
+                visited.add(key);
+                key = renamedFrom.get(key);
             }
+            return undefined;
         };
-        await walk(specsDir);
-        return results.sort();
+        // A MODIFIED naming a header the same delta renames away is already
+        // reported ("MODIFIED references old name from RENAMED"), and the block it
+        // would land on is not the one it names — so any scenario named here would
+        // send the author after the wrong requirement.
+        const renamedAway = new Set(renamed.map(({ from }) => normalizeRequirementName(from)));
+        const issues = [];
+        for (const block of modified) {
+            const key = normalizeRequirementName(block.name);
+            if (renamedAway.has(key))
+                continue;
+            const current = currentBlockFor(key);
+            if (!current)
+                continue;
+            const missing = findMissingCurrentScenarios(current, block);
+            if (missing.length === 0)
+                continue;
+            issues.push({
+                level: 'ERROR',
+                path: entryPath,
+                message: `MODIFIED "${block.name}" omits scenario(s) the current spec still has: ` +
+                    `${missing.map(name => `"${name}"`).join(', ')}. ` +
+                    'Copy them into the MODIFIED block (a MODIFIED requirement replaces the whole block, so archive refuses to drop them).',
+            });
+        }
+        return issues;
+    }
+    formatInvalidMarkerMessage(invalidReason) {
+        return `${VALIDATION_MESSAGES.CHANGE_SKIP_SPECS_INVALID_METADATA} (${invalidReason})`;
     }
     convertZodErrors(error) {
         return error.issues.map(err => {
@@ -361,22 +526,28 @@ export class Validator {
                 });
             }
         });
-        // SHALL/MUST body-keyword enforcement for main specs (#1156). The main-spec
+        // SHALL/MUST body-keyword guidance for main specs (#1156, #243). The main-spec
         // parser collapses the requirement header into `text`, so we recover the
         // header+body pairs here (the same source the delta path trusts) and reuse
-        // the delta detection: a body that omits the keyword errors, with the
-        // targeted "move it to the body line" hint when the keyword is in the header
-        // only and the generic message otherwise. Emitted exactly once per
+        // the delta detection. A non-empty body that omits the English keyword gets
+        // guidance, while a missing body remains an error. Emitted exactly once per
         // requirement (the Zod refine that used to emit a generic error is removed).
         extractRequirementsSection(content).bodyBlocks.forEach((block, index) => {
             const requirementText = this.extractRequirementText(block.raw);
-            if (!requirementText || !this.containsShallOrMust(requirementText)) {
+            if (!requirementText) {
                 issues.push({
                     level: 'ERROR',
                     path: `requirements[${index}]`,
                     message: this.buildMissingShallOrMustMessage(`Requirement "${block.name}"`, block.name),
                 });
             }
+            else if (!this.containsShallOrMust(requirementText)) {
+                issues.push({
+                    level: 'WARNING',
+                    path: `requirements[${index}]`,
+                    message: this.buildMissingShallOrMustMessage(`Requirement "${block.name}"`, block.name, true),
+                });
+            }
         });
         return issues;
     }
@@ -464,7 +635,7 @@ export class Validator {
         return containsShallOrMustShared(text);
     }
     /**
-     * Build an error message for a requirement block whose body lacks SHALL/MUST.
+     * Build a message for a requirement block whose body lacks SHALL/MUST.
      *
      * When the SHALL/MUST keyword already appears in the requirement header (e.g.
      * `### Requirement: The system SHALL ...`) the original generic error
@@ -473,12 +644,13 @@ export class Validator {
      * on the requirement body line (the line right after the header), so we point
      * the author at that exact fix when the keyword is found in the header only.
      */
-    buildMissingShallOrMustMessage(prefix, blockName) {
-        const base = `${prefix} must contain SHALL or MUST`;
+    buildMissingShallOrMustMessage(prefix, blockName, guidanceOnly = false) {
+        const base = `${prefix} ${guidanceOnly ? 'should' : 'must'} contain SHALL or MUST`;
+        const suffix = guidanceOnly ? ' (RFC 2119 best practice for English specs)' : '';
         if (this.containsShallOrMust(blockName)) {
-            return `${base} in the requirement body, not only in the header. Move the SHALL/MUST statement to the line immediately after the "### Requirement: ..." header.`;
+            return `${base} in the requirement body, not only in the header. Move the SHALL/MUST statement to the line immediately after the "### Requirement: ..." header.${suffix}`;
         }
-        return base;
+        return `${base}${suffix}`;
     }
     countScenarios(blockRaw) {
         // Fence-aware count via the shared reader: a `#### Scenario:` inside a fenced

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

@@ -0,0 +1,152 @@
+/**
+ * The registry to ask: only the environment variable npm exports (under
+ * `npm run`, or an explicit export). Deliberately not a `registry=` line from
+ * any .npmrc — letting file contents choose the destination of an outbound
+ * request is a flow worth avoiding for a convenience this small, and a project
+ * file would travel with a cloned repository. Anyone on a private mirror can
+ * export `npm_config_registry`, or turn the check off entirely.
+ */
+export declare function registryUrl(): string;
+/**
+ * Compares two semver-ish versions. Returns 1 when a > b, -1 when a < b, 0
+ * otherwise. Prereleases sort below their release (1.7.0-beta.1 < 1.7.0).
+ */
+export declare function compareVersions(a: string, b: string): number;
+/**
+ * Returns the published version when the installed CLI is behind it, otherwise
+ * null. Never throws and never blocks for longer than the request timeout.
+ */
+export declare function getAvailableCliUpdate(): Promise<string | null>;
+/**
+ * Directory the running CLI was loaded from, or null when it cannot be
+ * resolved. Shown in the upgrade hint so anyone who upgraded but still runs an
+ * old binary — a stale pnpm/volta/npx shim, or two installs on PATH — can see
+ * which copy is actually answering.
+ */
+export declare function getInstallDir(): string | null;
+/**
+ * True when the running CLI resolves from a `node_modules` belonging to the
+ * project being updated or any ancestor of it — the hoisted-root layout npm and
+ * pnpm workspaces produce. Anchored on the target path rather than the working
+ * directory, since `openspec update <path>` and running from a sub-package are
+ * both normal. Never throws: process.cwd() fails when the directory has been
+ * deleted, and a wrong upgrade hint must not take down a successful update.
+ */
+export declare function isProjectLocalInstall(installDir: string | null, projectPath?: string): boolean;
+/**
+ * True for the throwaway caches npx/pnpm dlx/bunx unpack into. Telling those
+ * users to install globally would create the second copy on PATH they were
+ * deliberately avoiding.
+ */
+export declare function isEphemeralRunnerInstall(installDir: string | null): boolean;
+/**
+ * Directories npm installs global packages into. Derived from the running node
+ * rather than by shelling out to `npm prefix -g`, which would cost more than
+ * the version check itself. Only a hint: `process.execPath` is realpath'd, so
+ * on Homebrew it lands in the Cellar rather than the brew prefix — which is
+ * why the install's own layout is the primary signal below.
+ */
+export declare function npmGlobalRoots(): string[];
+/**
+ * The prefix of an npm global install, read from the install's own shape:
+ * `<prefix>/lib/node_modules/<pkg>` on POSIX, `<prefix>/node_modules/<pkg>` on
+ * Windows. Self-describing, so it holds for Homebrew, nvm, Debian and anywhere
+ * else npm's prefix is not derivable from the node binary. Null when the
+ * layout does not match.
+ */
+export declare function npmPrefixFromInstallDir(installDir: string | null): string | null;
+/**
+ * True only when npm itself owns this copy. Everything else — a pnpm, bun,
+ * yarn or volta global — would be made worse by `npm install -g`, which adds a
+ * second copy that may not even be the one on PATH.
+ */
+export declare function isNpmGlobalInstall(installDir: string | null, roots?: string[]): boolean;
+/**
+ * True when the CLI is running from a clone rather than an install. Upgrade
+ * advice is meaningless there: the version is whatever the branch says.
+ */
+export declare function isSourceCheckout(installDir: string | null): boolean;
+export type PackageManager = 'npm' | 'pnpm' | 'bun' | 'yarn' | 'volta';
+/**
+ * The package manager that owns this copy, so the printed command is one the
+ * user's setup will actually honor.
+ */
+export declare function detectPackageManager(installDir: string | null): PackageManager;
+/**
+ * Builds the hint, with the upgrade command chosen for how this copy of the CLI
+ * was installed. Pure so every branch is assertable.
+ */
+export declare function buildCliUpdateLines(latestVersion: string, installDir: string | null, projectPath: string, options?: {
+    withCommand?: boolean;
+}): string[];
+/**
+ * The upgrade command for however this copy was installed, plus the reminder
+ * that instruction files come from the CLI and so need a second pass.
+ */
+export declare function buildUpgradeCommandLines(installDir: string | null, projectPath: string): string[];
+/**
+ * Whether we can run the upgrade for the user instead of only printing it.
+ *
+ * Only an npm-owned global install qualifies, because `npm install -g` is the
+ * only command we run: a pnpm/bun/yarn/volta global would get a second copy
+ * that may not be the one on PATH, a project dependency belongs to that
+ * project's package manager, an npx/dlx cache has nothing to upgrade, and a
+ * source checkout is not an install at all.
+ */
+export declare function canSelfUpgrade(installDir: string | null, projectPath: string): boolean;
+/**
+ * Whether to offer the upgrade rather than just print the command. Kept here,
+ * as a pure function of the environment, because the interesting mistakes live
+ * in this decision: offering where `npm install -g` cannot help, or asking a
+ * question no one can answer.
+ */
+export declare function shouldOfferUpgrade(params: {
+    installDir: string | null;
+    projectPath: string;
+    interactive: boolean;
+    stdoutIsTty: boolean;
+}): boolean;
+/**
+ * The `openspec` npm installs alongside its global package, so the upgrade can
+ * be handed to the copy npm just wrote rather than to whatever PATH resolves.
+ * Null when it cannot be found, in which case PATH is the only option left.
+ */
+export declare function upgradedBinPath(roots?: string[], installDir?: string | null): string | null;
+/**
+ * Asks a CLI binary its version. Used to confirm an upgrade actually landed:
+ * `npm install -g` exits 0 even when it installed nothing, so its exit code
+ * alone cannot justify telling the user they are on a new version.
+ */
+export declare function readCliVersion(binPath: string): Promise<string | null>;
+export type UpgradeOutcome = 'upgraded' | 'declined' | 'failed' | 'cancelled' | 'not-on-path';
+/**
+ * Offers to run the upgrade and reports what actually happened. The version is
+ * read back from the installed binary rather than assumed, so "upgraded" is a
+ * fact and a PATH that still answers with the old copy is caught here instead
+ * of silently doing nothing.
+ */
+export declare function offerCliUpgrade(latestVersion: string): Promise<UpgradeOutcome>;
+/**
+ * Runs `openspec update` again with the CLI that was just installed — this
+ * process is still the old code, so it cannot write the new workflows itself.
+ * Resolves the exit code to pass along; when no `openspec` is on PATH the
+ * upgrade still landed but nothing was regenerated, so it says so and
+ * resolves 0 rather than reporting a failure the upgrade did not have.
+ */
+export declare function rerunUpdateWithUpgradedCli(projectPath: string, options?: {
+    force?: boolean;
+    binPath?: string;
+}): Promise<number>;
+/**
+ * Prints the upgrade hint. Instruction files are generated by the installed
+ * CLI, so "up to date" only ever means "matches this CLI" — without this note
+ * a stale install looks like a successful update.
+ */
+export declare function displayCliUpdateNote(latestVersion: string, projectPath?: string, options?: {
+    withCommand?: boolean;
+}): void;
+/**
+ * Prints just the manual command, for when the offer was declined or failed.
+ */
+export declare function displayUpgradeCommand(projectPath?: string): void;
+//# sourceMappingURL=version-check.d.ts.map