@fission-ai/openspec 1.14.3 → 1.16.0

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/legacy-cleanup.d.ts

@@ -166,7 +166,17 @@ export interface CleanupResult {
  * @param detection - Detection result from detectLegacyArtifacts
  * @returns Cleanup result with summary of actions taken
  */
-export declare function cleanupLegacyArtifacts(projectPath: string, detection: LegacyDetectionResult): Promise<CleanupResult>;
+/**
+ * Every change cleanup makes on disk. `update --dry-run` passes a recorder, so
+ * the plan comes from this same code rather than a description of it.
+ */
+export interface LegacyCleanupOps {
+    writeFile(filePath: string, content: string): Promise<void>;
+    removeFile(filePath: string): Promise<void>;
+    /** Removes a directory already known to be empty. */
+    removeEmptyDirectory(dirPath: string): Promise<void>;
+}
+export declare function cleanupLegacyArtifacts(projectPath: string, detection: LegacyDetectionResult, ops?: LegacyCleanupOps): Promise<CleanupResult>;
 /**
  * Generates a cleanup summary message for display.
  *

package/dist/core/legacy-cleanup.js

@@ -323,14 +323,14 @@ function legacyCommandDirForFile(file) {
  * or records what is left in it as kept. Never recursive: whatever remains was
  * not written by OpenSpec. Returns true when the directory was removed.
  */
-async function settleLegacyCommandDir(projectPath, dirPath, result) {
+async function settleLegacyCommandDir(projectPath, dirPath, result, ops = DIRECT_CLEANUP_OPS) {
     const fullPath = FileSystemUtils.joinPath(projectPath, dirPath);
     const remaining = await readLegacyCommandDir(fullPath, []);
     if (!remaining) {
         return false;
     }
     if (remaining.others.length === 0) {
-        await fs.rmdir(fullPath);
+        await ops.removeEmptyDirectory(fullPath);
         result.deletedDirs.push(dirPath);
         return true;
     }
@@ -493,15 +493,12 @@ export function isOnlyOpenSpecContent(content) {
 export function removeMarkerBlock(content) {
     return removeMarkerBlockUtil(content, OPENSPEC_MARKERS.start, OPENSPEC_MARKERS.end);
 }
-/**
- * Cleans up legacy OpenSpec artifacts from a project.
- * Preserves openspec/project.md (shows migration hint instead of deleting).
- *
- * @param projectPath - The root path of the project
- * @param detection - Detection result from detectLegacyArtifacts
- * @returns Cleanup result with summary of actions taken
- */
-export async function cleanupLegacyArtifacts(projectPath, detection) {
+const DIRECT_CLEANUP_OPS = {
+    writeFile: (filePath, content) => FileSystemUtils.writeFile(filePath, content),
+    removeFile: (filePath) => fs.unlink(filePath),
+    removeEmptyDirectory: (dirPath) => fs.rmdir(dirPath),
+};
+export async function cleanupLegacyArtifacts(projectPath, detection, ops = DIRECT_CLEANUP_OPS) {
     const result = {
         deletedFiles: [],
         deletedFileReplacementLabels: {},
@@ -519,7 +516,7 @@ export async function cleanupLegacyArtifacts(projectPath, detection) {
             const content = await FileSystemUtils.readFile(filePath);
             const newContent = removeMarkerBlock(content);
             // Always write the file, even if empty - never delete user config files
-            await FileSystemUtils.writeFile(filePath, newContent);
+            await ops.writeFile(filePath, newContent);
             result.modifiedFiles.push(fileName);
         }
         catch (error) {
@@ -545,10 +542,10 @@ export async function cleanupLegacyArtifacts(projectPath, detection) {
                 if (!(await isGeneratedLegacyCommand(filePath))) {
                     continue;
                 }
-                await fs.unlink(filePath);
+                await ops.removeFile(filePath);
                 deleted.push(name);
             }
-            if (!(await settleLegacyCommandDir(projectPath, dirPath, result))) {
+            if (!(await settleLegacyCommandDir(projectPath, dirPath, result, ops))) {
                 result.deletedFiles.push(...deleted.map((name) => `${dirPath}/${name}`));
             }
         }
@@ -570,7 +567,7 @@ export async function cleanupLegacyArtifacts(projectPath, detection) {
                     continue;
                 }
             }
-            await fs.unlink(fullPath);
+            await ops.removeFile(fullPath);
             result.deletedFiles.push(filePath);
         }
         catch (error) {
@@ -581,7 +578,7 @@ export async function cleanupLegacyArtifacts(projectPath, detection) {
     // file by file above; record what was left in it.
     for (const dirPath of partlyCleanedDirs) {
         try {
-            await settleLegacyCommandDir(projectPath, dirPath, result);
+            await settleLegacyCommandDir(projectPath, dirPath, result, ops);
         }
         catch (error) {
             result.errors.push(`Failed to delete directory ${dirPath}: ${error.message}`);
@@ -595,7 +592,7 @@ export async function cleanupLegacyArtifacts(projectPath, detection) {
             continue;
         }
         try {
-            await fs.unlink(filePath);
+            await ops.removeFile(filePath);
             result.deletedFiles.push(filePath);
             const promptMatch = globalPromptMatchesByPath.get(filePath);
             if (promptMatch?.replacementLabel) {
@@ -611,7 +608,7 @@ export async function cleanupLegacyArtifacts(projectPath, detection) {
         const agentsPath = FileSystemUtils.joinPath(projectPath, 'openspec', 'AGENTS.md');
         if (await FileSystemUtils.fileExists(agentsPath)) {
             try {
-                await fs.unlink(agentsPath);
+                await ops.removeFile(agentsPath);
                 result.deletedFiles.push('openspec/AGENTS.md');
             }
             catch (error) {

package/dist/core/migration.d.ts

@@ -5,6 +5,8 @@
  * Called by both init and update commands before profile resolution.
  */
 import { type AIToolOption } from './config.js';
+import { type Delivery, type GlobalConfig, type Profile } from './global-config.js';
+import { type FileView } from './file-view.js';
 export interface LegacyToolRoot {
     /** Former tool root, e.g. '.kimi' */
     root: string;
@@ -41,11 +43,27 @@ export interface LegacyToolMigration {
     /** Whether this move needs the user's consent first */
     needsConsent: boolean;
 }
+/** One file a legacy-root migration would move or drop. */
+export interface LegacyMigrationFileOp {
+    toolId: string;
+    source: string;
+    destination: string;
+    disposition: 'move' | 'drop';
+    /** Whether an interactive run asks before this move */
+    needsConsent: boolean;
+}
 /**
  * Reports the OpenSpec content sitting under each tool's legacy root, without
  * moving anything. Callers use this to ask before a move that needs consent.
  */
 export declare function findLegacyToolMigrations(projectPath: string, timing?: 'before-generation' | 'after-generation'): LegacyToolMigration[];
+/**
+ * Lists, file by file, what `migrateLegacyToolDirs` would move or drop, without
+ * touching anything. Consent-gated roots are included: a non-interactive run
+ * moves them without asking. `view` decides what already sits at each
+ * destination, so a dry run can plan against files it has not written.
+ */
+export declare function planLegacyToolMigrations(projectPath: string, timing: 'before-generation' | 'after-generation', toolIds: string[] | undefined, view: FileView): LegacyMigrationFileOp[];
 /**
  * Moves OpenSpec-managed skill directories (openspec-*) and command files
  * (opsx-*) from a tool's legacy root to its current one. When the destination
@@ -81,7 +99,7 @@ export declare function legacyMigrationNotice(migration: LegacyToolMigration): s
  * Scans installed workflow files across all detected tools and returns
  * the union of installed workflow IDs.
  */
-export declare function scanInstalledWorkflows(projectPath: string, tools: AIToolOption[]): string[];
+export declare function scanInstalledWorkflows(projectPath: string, tools: AIToolOption[], view?: FileView): string[];
 /**
  * Performs one-time migration if the global config does not yet have a profile field.
  * Called by both init and update before profile resolution.
@@ -91,5 +109,13 @@ export declare function scanInstalledWorkflows(projectPath: string, tools: AIToo
  * - If no profile field exists and no workflows are installed: no-op (defaults apply).
  * - If profile field already exists: no-op.
  */
+export declare function computeProfileMigration(projectPath: string, tools: AIToolOption[], view?: FileView): ProfileMigration | null;
+export type ProfileMigration = {
+    profile: Profile;
+    workflows: string[];
+    delivery?: Delivery;
+};
+/** The global config the one-time profile migration saves. */
+export declare function applyProfileMigration(migration: ProfileMigration): GlobalConfig;
 export declare function migrateIfNeeded(projectPath: string, tools: AIToolOption[]): void;
 //# sourceMappingURL=migration.d.ts.map

package/dist/core/migration.js

@@ -14,6 +14,7 @@ import { ALL_WORKFLOWS } from './profiles.js';
 import { getSkillReferenceTransformer, getTransformerForTool } from '../utils/command-references.js';
 import { FileSystemUtils } from '../utils/file-system.js';
 import { isSharedSkillTargetActive } from './shared-skill-target.js';
+import { DISK_VIEW } from './file-view.js';
 import { isLegacyCodexSkillEquivalentToCurrent } from './shared/skill-content-equivalence.js';
 import path from 'path';
 import * as fs from 'fs';
@@ -41,14 +42,14 @@ export const LEGACY_TOOL_ROOTS = {
     // reported and kept rather than overwritten.
     antigravity: [{ root: '.agent', needsConsent: false, timing: 'after-generation' }],
 };
-function classifyManagedFile(source, destination) {
+function classifyManagedFile(source, destination, view = DISK_VIEW) {
     if (isSamePath(source, destination))
         return 'skip';
-    if (!fs.existsSync(destination))
+    if (!view.exists(destination))
         return 'move';
     try {
         const sourceContent = fs.readFileSync(source, 'utf-8');
-        const destinationContent = fs.readFileSync(destination, 'utf-8');
+        const destinationContent = view.read(destination);
         const equivalentGeneratedSkills = path.basename(source) === 'SKILL.md' &&
             path.basename(destination) === 'SKILL.md' &&
             isLegacyCodexSkillEquivalentToCurrent(sourceContent, destinationContent);
@@ -85,6 +86,17 @@ function legacyCommandPath(commandPath, currentRoot, legacyRoot) {
 export function findLegacyToolMigrations(projectPath, timing = 'before-generation') {
     return collectLegacyToolMigrations(projectPath, false, undefined, timing);
 }
+/**
+ * Lists, file by file, what `migrateLegacyToolDirs` would move or drop, without
+ * touching anything. Consent-gated roots are included: a non-interactive run
+ * moves them without asking. `view` decides what already sits at each
+ * destination, so a dry run can plan against files it has not written.
+ */
+export function planLegacyToolMigrations(projectPath, timing, toolIds, view) {
+    const ops = [];
+    collectLegacyToolMigrations(projectPath, false, toolIds, timing, { view, ops });
+    return ops;
+}
 /**
  * Moves OpenSpec-managed skill directories (openspec-*) and command files
  * (opsx-*) from a tool's legacy root to its current one. When the destination
@@ -99,7 +111,7 @@ export function findLegacyToolMigrations(projectPath, timing = 'before-generatio
 export function migrateLegacyToolDirs(projectPath, toolIds, timing = 'before-generation') {
     return collectLegacyToolMigrations(projectPath, true, toolIds, timing);
 }
-function collectLegacyToolMigrations(projectPath, apply, toolIds, timing = 'before-generation') {
+function collectLegacyToolMigrations(projectPath, apply, toolIds, timing = 'before-generation', plan) {
     const migrations = [];
     for (const tool of AI_TOOLS) {
         if (!tool.skillsDir)
@@ -126,8 +138,11 @@ function collectLegacyToolMigrations(projectPath, apply, toolIds, timing = 'befo
                 console.warn(`Skipping legacy ${legacy.root}/ migration because the directory resolves outside this project.`);
                 continue;
             }
-            const skills = migrateSkillDirs(projectPath, tool.skillsDir, legacy.root, apply, legacyTiming === 'after-generation');
-            const commands = migrateCommandFiles(projectPath, tool, legacy.root, apply, legacyTiming === 'after-generation');
+            const sink = plan
+                ? { ...plan, toolId: tool.value, needsConsent: legacy.needsConsent }
+                : undefined;
+            const skills = migrateSkillDirs(projectPath, tool.skillsDir, legacy.root, apply, legacyTiming === 'after-generation', sink);
+            const commands = migrateCommandFiles(projectPath, tool, legacy.root, apply, legacyTiming === 'after-generation', sink);
             if (apply) {
                 removeDirIfEmpty(path.join(legacyRootPath, 'skills'));
                 removeDirIfEmpty(path.join(legacyRootPath, 'workflows'));
@@ -152,7 +167,8 @@ function collectLegacyToolMigrations(projectPath, apply, toolIds, timing = 'befo
     }
     return migrations;
 }
-function migrateSkillDirs(projectPath, currentRoot, legacyRoot, apply, requireDestination = false) {
+function migrateSkillDirs(projectPath, currentRoot, legacyRoot, apply, requireDestination = false, sink) {
+    const view = sink?.view ?? DISK_VIEW;
     const legacySkillsDir = path.join(projectPath, legacyRoot, 'skills');
     if (!fs.existsSync(legacySkillsDir))
         return { moved: 0, kept: 0 };
@@ -167,13 +183,13 @@ function migrateSkillDirs(projectPath, currentRoot, legacyRoot, apply, requireDe
             continue;
         const destination = path.join(currentSkillsDir, dirName);
         const destinationSkill = path.join(destination, 'SKILL.md');
-        if (requireDestination && !fs.existsSync(destinationSkill))
+        if (requireDestination && !view.exists(destinationSkill))
             continue;
         if (!areProjectArtifacts(projectPath, sourceSkill, destinationSkill)) {
             console.warn(`Skipping legacy ${legacyRoot}/skills/${dirName} migration because it resolves outside this project.`);
             continue;
         }
-        const disposition = classifyManagedFile(sourceSkill, destinationSkill);
+        const disposition = classifyManagedFile(sourceSkill, destinationSkill, view);
         if (disposition === 'skip')
             continue;
         if (disposition === 'keep') {
@@ -181,6 +197,13 @@ function migrateSkillDirs(projectPath, currentRoot, legacyRoot, apply, requireDe
             continue;
         }
         if (!apply) {
+            sink?.ops.push({
+                toolId: sink.toolId,
+                source: sourceSkill,
+                destination: destinationSkill,
+                disposition,
+                needsConsent: sink.needsConsent,
+            });
             moved++;
             continue;
         }
@@ -207,7 +230,8 @@ function migrateSkillDirs(projectPath, currentRoot, legacyRoot, apply, requireDe
     }
     return { moved, kept };
 }
-function migrateCommandFiles(projectPath, tool, legacyRoot, apply, requireDestination = false) {
+function migrateCommandFiles(projectPath, tool, legacyRoot, apply, requireDestination = false, sink) {
+    const view = sink?.view ?? DISK_VIEW;
     const adapter = CommandAdapterRegistry.get(tool.value);
     if (!adapter || !tool.skillsDir)
         return { moved: 0, kept: 0 };
@@ -226,13 +250,13 @@ function migrateCommandFiles(projectPath, tool, legacyRoot, apply, requireDestin
         // No replacement means this command is not one OpenSpec installs now — a
         // skills-only delivery or a deselected workflow — so relocating the legacy
         // file would resurrect it under the current root.
-        if (requireDestination && !fs.existsSync(destination))
+        if (requireDestination && !view.exists(destination))
             continue;
         if (!areProjectArtifacts(projectPath, source, destination)) {
             console.warn(`Skipping legacy ${legacyPath} migration because it resolves outside this project.`);
             continue;
         }
-        const disposition = classifyManagedFile(source, destination);
+        const disposition = classifyManagedFile(source, destination, view);
         if (disposition === 'skip')
             continue;
         if (disposition === 'keep') {
@@ -240,6 +264,13 @@ function migrateCommandFiles(projectPath, tool, legacyRoot, apply, requireDestin
             continue;
         }
         if (!apply) {
+            sink?.ops.push({
+                toolId: sink.toolId,
+                source,
+                destination,
+                disposition,
+                needsConsent: sink.needsConsent,
+            });
             moved++;
             continue;
         }
@@ -344,7 +375,7 @@ function removeDirIfEmpty(dirPath) {
         // Missing or non-empty directory — nothing to do
     }
 }
-function scanInstalledWorkflowArtifacts(projectPath, tools, includeLegacyRoots = false) {
+function scanInstalledWorkflowArtifacts(projectPath, tools, includeLegacyRoots = false, view = DISK_VIEW) {
     const installed = new Set();
     let hasSkills = false;
     let hasCommands = false;
@@ -355,7 +386,7 @@ function scanInstalledWorkflowArtifacts(projectPath, tools, includeLegacyRoots =
         if (tool.globalSkillsDir) {
             skillsDirs.push(resolveToolSkillsDir(projectPath, tool));
         }
-        else if (isSharedSkillTargetActive(projectPath, tool.value)) {
+        else if (isSharedSkillTargetActive(projectPath, tool.value, view)) {
             skillsDirs.push(resolveToolSkillsDir(projectPath, tool));
             if (includeLegacyRoots) {
                 skillsDirs.push(...(tool.legacySkillsDirs ?? []).map((root) => path.join(projectPath, root, 'skills')));
@@ -365,7 +396,7 @@ function scanInstalledWorkflowArtifacts(projectPath, tools, includeLegacyRoots =
             for (const workflowId of ALL_WORKFLOWS) {
                 const skillDirName = WORKFLOW_TO_SKILL_DIR[workflowId];
                 const skillFile = path.join(skillsDir, skillDirName, 'SKILL.md');
-                if (fs.existsSync(skillFile)) {
+                if (view.exists(skillFile)) {
                     installed.add(workflowId);
                     hasSkills = true;
                 }
@@ -395,7 +426,7 @@ function scanInstalledWorkflowArtifacts(projectPath, tools, includeLegacyRoots =
                 const fullPath = path.isAbsolute(candidate)
                     ? candidate
                     : path.join(projectPath, candidate);
-                if (fs.existsSync(fullPath)) {
+                if (view.exists(fullPath)) {
                     installed.add(workflowId);
                     hasCommands = true;
                     break;
@@ -413,8 +444,8 @@ function scanInstalledWorkflowArtifacts(projectPath, tools, includeLegacyRoots =
  * Scans installed workflow files across all detected tools and returns
  * the union of installed workflow IDs.
  */
-export function scanInstalledWorkflows(projectPath, tools) {
-    return scanInstalledWorkflowArtifacts(projectPath, tools).workflows;
+export function scanInstalledWorkflows(projectPath, tools, view = DISK_VIEW) {
+    return scanInstalledWorkflowArtifacts(projectPath, tools, false, view).workflows;
 }
 function inferDelivery(artifacts) {
     if (artifacts.hasSkills && artifacts.hasCommands) {
@@ -434,13 +465,12 @@ function inferDelivery(artifacts) {
  * - If no profile field exists and no workflows are installed: no-op (defaults apply).
  * - If profile field already exists: no-op.
  */
-export function migrateIfNeeded(projectPath, tools) {
+export function computeProfileMigration(projectPath, tools, view = DISK_VIEW) {
     // A config that cannot be parsed, or is not a JSON object, is never saved
     // over; skip migration rather than fail init or update on it.
     if (isGlobalConfigUnreadable()) {
-        return;
+        return null;
     }
-    const config = getGlobalConfig();
     // Check raw config file for profile field presence
     const configPath = getGlobalConfigPath();
     let rawConfig = {};
@@ -450,25 +480,43 @@ export function migrateIfNeeded(projectPath, tools) {
         }
     }
     catch {
-        return; // Can't read config, skip migration
+        return null; // Can't read config, skip migration
     }
     // If profile is already explicitly set, no migration needed
     if (rawConfig.profile !== undefined) {
-        return;
+        return null;
     }
     // Scan for installed workflows
-    const artifacts = scanInstalledWorkflowArtifacts(projectPath, tools, true);
+    const artifacts = scanInstalledWorkflowArtifacts(projectPath, tools, true, view);
     const installedWorkflows = artifacts.workflows;
     if (installedWorkflows.length === 0) {
         // No workflows installed, new user — defaults will apply
-        return;
+        return null;
     }
+    return {
+        profile: 'custom',
+        workflows: installedWorkflows,
+        ...(rawConfig.delivery === undefined ? { delivery: inferDelivery(artifacts) } : {}),
+    };
+}
+/** The global config the one-time profile migration saves. */
+export function applyProfileMigration(migration) {
+    const config = getGlobalConfig();
     // Migrate: set profile to custom with detected workflows
-    config.profile = 'custom';
-    config.workflows = installedWorkflows;
-    if (rawConfig.delivery === undefined) {
-        config.delivery = inferDelivery(artifacts);
+    config.profile = migration.profile;
+    config.workflows = migration.workflows;
+    if (migration.delivery !== undefined) {
+        config.delivery = migration.delivery;
+    }
+    return config;
+}
+export function migrateIfNeeded(projectPath, tools) {
+    const migration = computeProfileMigration(projectPath, tools);
+    if (!migration) {
+        return;
     }
+    const config = applyProfileMigration(migration);
+    const installedWorkflows = migration.workflows;
     saveGlobalConfig(config);
     console.log(`Migrated: custom profile with ${installedWorkflows.length} workflows`);
     // Each detected tool resolves to a propose reference for its surface: the

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);