@fission-ai/openspec 1.7.0 → 1.8.0

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

@@ -12,12 +12,32 @@ 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, options?: {
+        mainSpecsDir?: string;
+    }): Promise<ValidationReport>;
+    /**
+     * 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.
      */
-    validateChangeDeltaSpecs(changeDir: string): Promise<ValidationReport>;
+    private findScenarioLossIssues;
     private formatInvalidMarkerMessage;
     private convertZodErrors;
     private applySpecRules;
@@ -29,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,7 +4,7 @@ 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, foldRequirementName, 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';
@@ -101,12 +101,18 @@ 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;
@@ -119,7 +125,7 @@ export class Validator {
             // 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 specFiles = (await discoverSpecFiles(specsDir)).map(spec => spec.specFile);
+            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).
@@ -131,10 +137,10 @@ export class Validator {
                 issues.push({
                     level: 'ERROR',
                     path: 'spec.md',
-                    message: 'Delta spec found at specs/spec.md. Delta specs must live in a capability folder (e.g. specs/<capability>/spec.md) — a file at the specs/ root is ignored when the change is applied or archived.',
+                    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 specFile of specFiles) {
+            for (const { id: specId, specFile } of discoveredSpecs) {
                 let content;
                 try {
                     content = await fs.readFile(specFile, 'utf-8');
@@ -204,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) {
@@ -232,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);
@@ -368,6 +389,94 @@ export class Validator {
         }
         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;
+        };
+        // 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})`;
     }
@@ -417,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;
     }
@@ -520,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
@@ -529,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.js

@@ -4,6 +4,8 @@ import https from 'https';
 import path from 'path';
 import { createRequire } from 'module';
 import chalk from 'chalk';
+import { isCiEnvironment } from '../utils/ci.js';
+import { getGlobalConfig } from './global-config.js';
 const require = createRequire(import.meta.url);
 const { name: PACKAGE_NAME, version: OPENSPEC_VERSION } = require('../../package.json');
 const DEFAULT_REGISTRY = 'https://registry.npmjs.org';
@@ -11,16 +13,6 @@ const REQUEST_TIMEOUT_MS = 1500;
 const MAX_RESPONSE_BYTES = 256 * 1024;
 const VERSION_PROBE_TIMEOUT_MS = 5000;
 const MAX_REDIRECTS = 3;
-/**
- * `CI` set to anything meaningful means CI. Providers use "true", "1", "yes";
- * only an explicit off-value counts as "not CI", so a value we do not know
- * still suppresses the request rather than surprising a build.
- */
-const CI_DISABLED_VALUES = new Set(['', 'false', '0', 'no', 'off']);
-function isCiEnvironment() {
-    const value = process.env.CI;
-    return value !== undefined && !CI_DISABLED_VALUES.has(value.trim().toLowerCase());
-}
 /**
  * A version we are willing to print. The registry only ever serves SemVer here,
  * so anything else is either a broken mirror or a hostile response — and since
@@ -32,7 +24,7 @@ const SAFE_VERSION = /^\d{1,10}\.\d{1,10}\.\d{1,10}(?:-[0-9A-Za-z.-]{1,64})?(?:\
  * The check is opt-out and must never get in the way: no network in CI or
  * tests, an explicit escape hatch for anyone offline or air-gapped, and the
  * same privacy signals telemetry already honors — a user who set DO_NOT_TRACK
- * did not agree to a different outbound request.
+ * or telemetry.enabled false did not agree to a different outbound request.
  */
 function isCheckEnabled() {
     if (process.env.OPENSPEC_NO_UPDATE_CHECK !== undefined)
@@ -45,6 +37,9 @@ function isCheckEnabled() {
         return false;
     if (process.env.NODE_ENV === 'test')
         return false;
+    // Same config opt-out as telemetry (env remains the hard override above).
+    if (getGlobalConfig().telemetry?.enabled === false)
+        return false;
     return true;
 }
 /**

package/dist/telemetry/config.d.ts

@@ -1,9 +1,8 @@
+import { type TelemetryConfig } from '../core/global-config.js';
 export declare const CONFIG_DIR_NAME = "openspec";
 export declare const CONFIG_FILE_NAME = "config.json";
-export interface TelemetryConfig {
-    anonymousId?: string;
-    noticeSeen?: boolean;
-}
+/** Re-export shared telemetry section type (single source of truth in global-config). */
+export type { TelemetryConfig };
 export interface GlobalConfig {
     telemetry?: TelemetryConfig;
     [key: string]: unknown;

package/dist/telemetry/index.d.ts

@@ -1,10 +1,15 @@
 /**
  * Check if telemetry is enabled.
  *
- * Disabled when:
- * - OPENSPEC_TELEMETRY=0
- * - DO_NOT_TRACK=1
- * - CI=true (any CI environment)
+ * Precedence (first match wins):
+ * 1. OPENSPEC_TELEMETRY=0 → disabled
+ * 2. DO_NOT_TRACK=1 → disabled
+ * 3. CI set to a truthy/on value → disabled (same rule as version-check)
+ * 4. global config telemetry.enabled === false → disabled
+ * 5. otherwise enabled (unset config means on; opt-out model)
+ *
+ * Kept synchronous so call sites need not become async. Reads config via
+ * sync getGlobalConfig() rather than async getTelemetryConfig().
  */
 export declare function isTelemetryEnabled(): boolean;
 /**

package/dist/telemetry/index.js

@@ -4,7 +4,8 @@
  * Privacy-first design:
  * - Only tracks command name and version
  * - No arguments, file paths, or content
- * - Opt-out via OPENSPEC_TELEMETRY=0 or DO_NOT_TRACK=1
+ * - Opt-out via OPENSPEC_TELEMETRY=0, DO_NOT_TRACK=1, or
+ *   `openspec config set telemetry.enabled false`
  * - Auto-disabled in CI environments
  * - Anonymous ID is a random UUID with no relation to the user
  *
@@ -19,6 +20,8 @@
  * versions and broke installs (#1390).
  */
 import { randomUUID } from 'crypto';
+import { getGlobalConfig } from '../core/global-config.js';
+import { isCiEnvironment } from '../utils/ci.js';
 import { getTelemetryConfig, updateTelemetryConfig } from './config.js';
 // PostHog API key - public key for client-side analytics
 // This is safe to embed as it only allows sending events, not reading data
@@ -55,10 +58,15 @@ async function safeTelemetryFetch(url, options) {
 /**
  * Check if telemetry is enabled.
  *
- * Disabled when:
- * - OPENSPEC_TELEMETRY=0
- * - DO_NOT_TRACK=1
- * - CI=true (any CI environment)
+ * Precedence (first match wins):
+ * 1. OPENSPEC_TELEMETRY=0 → disabled
+ * 2. DO_NOT_TRACK=1 → disabled
+ * 3. CI set to a truthy/on value → disabled (same rule as version-check)
+ * 4. global config telemetry.enabled === false → disabled
+ * 5. otherwise enabled (unset config means on; opt-out model)
+ *
+ * Kept synchronous so call sites need not become async. Reads config via
+ * sync getGlobalConfig() rather than async getTelemetryConfig().
  */
 export function isTelemetryEnabled() {
     // Check explicit opt-out
@@ -69,8 +77,12 @@ export function isTelemetryEnabled() {
     if (process.env.DO_NOT_TRACK === '1') {
         return false;
     }
-    // Auto-disable in CI environments
-    if (process.env.CI === 'true') {
+    // Auto-disable in CI environments (providers use true/1/yes/…)
+    if (isCiEnvironment()) {
+        return false;
+    }
+    // Global config opt-out (env/CI remain hard overrides above)
+    if (getGlobalConfig().telemetry?.enabled === false) {
         return false;
     }
     return true;
@@ -157,7 +169,7 @@ export async function maybeShowTelemetryNotice() {
             return;
         }
         // Display notice
-        console.log('Note: OpenSpec collects anonymous usage stats. Opt out: OPENSPEC_TELEMETRY=0');
+        console.log('Note: OpenSpec collects anonymous usage stats. Opt out: OPENSPEC_TELEMETRY=0 or openspec config set telemetry.enabled false');
         // Mark as seen
         await updateTelemetryConfig({ noticeSeen: true });
     }

package/dist/utils/change-metadata.d.ts

@@ -55,19 +55,21 @@ export interface ResolveSchemaForChangeOptions {
  * @returns The resolved schema name
  */
 export declare function resolveSchemaForChange(changeDir: string, explicitSchema?: string, projectRootOverride?: string, options?: ResolveSchemaForChangeOptions): string;
-export interface SkipSpecsMarker {
+export interface MetadataMarker {
     /**
      * True when the metadata parses under ChangeMetadataSchema, sets
-     * skip_specs: true, and names a schema that loads.
+     * the requested boolean marker to true, and names a schema that loads.
      */
     declared: boolean;
     /**
-     * Set when the marker cannot be honored: skip_specs appears in a file that
+     * Set when the marker cannot be honored: it appears in a file that
      * fails the metadata contract, or the metadata file exists but cannot be
      * read at all (so whether the marker is set cannot even be determined).
      */
     invalidReason?: string;
 }
+/** @deprecated Use MetadataMarker. */
+export type SkipSpecsMarker = MetadataMarker;
 /**
  * Non-throwing read of the skip_specs marker. The marker only counts when the
  * metadata would load for status/instructions: the file parses under
@@ -81,5 +83,16 @@ export interface SkipSpecsMarker {
  * Missing metadata means "not declared"; a marker that cannot be honored
  * yields invalidReason so callers can say why.
  */
-export declare function readSkipSpecsMarker(changeDir: string): SkipSpecsMarker;
+export declare function readSkipSpecsMarker(changeDir: string): MetadataMarker;
+/**
+ * Non-throwing read of the retire_capabilities marker, with exactly the
+ * semantics `readSkipSpecsMarker` documents above.
+ *
+ * Gates the one archive action that removes a file from `openspec/specs/`: when
+ * a change's REMOVED entries take a capability's last requirement, archive
+ * deletes the emptied main spec rather than aborting on a spec it cannot write
+ * (#1302). Declared rather than inferred because the delete is recoverable only
+ * from git, so it is the author's call.
+ */
+export declare function readRetireCapabilitiesMarker(changeDir: string): MetadataMarker;
 //# sourceMappingURL=change-metadata.d.ts.map

package/dist/utils/change-metadata.js

@@ -159,6 +159,27 @@ export function resolveSchemaForChange(changeDir, explicitSchema, projectRootOve
  * yields invalidReason so callers can say why.
  */
 export function readSkipSpecsMarker(changeDir) {
+    return readBooleanMarker(changeDir, 'skip_specs');
+}
+/**
+ * Non-throwing read of the retire_capabilities marker, with exactly the
+ * semantics `readSkipSpecsMarker` documents above.
+ *
+ * Gates the one archive action that removes a file from `openspec/specs/`: when
+ * a change's REMOVED entries take a capability's last requirement, archive
+ * deletes the emptied main spec rather than aborting on a spec it cannot write
+ * (#1302). Declared rather than inferred because the delete is recoverable only
+ * from git, so it is the author's call.
+ */
+export function readRetireCapabilitiesMarker(changeDir) {
+    return readBooleanMarker(changeDir, 'retire_capabilities');
+}
+/**
+ * Shared implementation for the boolean change-metadata markers, keyed by field
+ * name. One body rather than two, so a marker can never drift into honoring
+ * metadata the other rejects - the whole point of the contract described above.
+ */
+function readBooleanMarker(changeDir, key) {
     let raw;
     try {
         raw = fs.readFileSync(path.join(changeDir, METADATA_FILENAME), 'utf-8');
@@ -184,13 +205,14 @@ export function readSkipSpecsMarker(changeDir) {
     catch {
         // Anchored so a comment like "# maybe add skip_specs later" does not
         // claim the marker was set.
-        return /^\s*(['"]?)skip_specs\1\s*:/m.test(raw)
+        const mentioned = new RegExp(`^\\s*(['"]?)${key}\\1\\s*:`, 'm').test(raw);
+        return mentioned
             ? { declared: false, invalidReason: 'the file is not valid YAML' }
             : { declared: false };
     }
     const result = ChangeMetadataSchema.safeParse(parsed);
     if (result.success) {
-        if (result.data.skip_specs !== true) {
+        if (result.data[key] !== true) {
             return { declared: false };
         }
         // Schema loading is checked only when the marker is set: a broken schema
@@ -223,8 +245,8 @@ export function readSkipSpecsMarker(changeDir) {
     // validate - the change simply is not marked.
     const markerMentioned = typeof parsed === 'object' &&
         parsed !== null &&
-        'skip_specs' in parsed &&
-        parsed.skip_specs !== false;
+        key in parsed &&
+        parsed[key] !== false;
     if (markerMentioned) {
         const first = result.error.issues[0];
         const where = first.path.length > 0 ? `${first.path.join('.')}: ` : '';

package/dist/utils/ci.d.ts

@@ -0,0 +1,12 @@
+/**
+ * CI environment detection shared by telemetry and the version check.
+ *
+ * Providers set CI to "true", "1", "yes", etc. Only an explicit off-value
+ * counts as "not CI", so an unknown value still suppresses outbound requests
+ * rather than surprising a build.
+ */
+/**
+ * True when `CI` is set to anything other than an explicit off-value.
+ */
+export declare function isCiEnvironment(env?: NodeJS.ProcessEnv): boolean;
+//# sourceMappingURL=ci.d.ts.map

package/dist/utils/ci.js

@@ -0,0 +1,16 @@
+/**
+ * CI environment detection shared by telemetry and the version check.
+ *
+ * Providers set CI to "true", "1", "yes", etc. Only an explicit off-value
+ * counts as "not CI", so an unknown value still suppresses outbound requests
+ * rather than surprising a build.
+ */
+const CI_DISABLED_VALUES = new Set(['', 'false', '0', 'no', 'off']);
+/**
+ * True when `CI` is set to anything other than an explicit off-value.
+ */
+export function isCiEnvironment(env = process.env) {
+    const value = env.CI;
+    return value !== undefined && !CI_DISABLED_VALUES.has(value.trim().toLowerCase());
+}
+//# sourceMappingURL=ci.js.map

package/dist/utils/command-references.d.ts

@@ -25,6 +25,16 @@ import type { CommandInvocation } from '../core/command-generation/invocation.js
  * transformCommandInvocations('/opsx:new', { style: 'flat', prefix: '@' }) // '@opsx-new'
  */
 export declare function transformCommandInvocations(text: string, invocation: CommandInvocation): string;
+/**
+ * Whether a tool references skills by natural language rather than a slash
+ * command (see NATURAL_LANGUAGE_SKILL_TOOLS).
+ */
+export declare function usesNaturalLanguageSkillReferences(toolId: string): boolean;
+/**
+ * Keeps Codex's `$<name>` spelling first while making its canonical shared
+ * `.agents` tree usable by agents that invoke the same skills with `/<name>`.
+ */
+export declare function transformToCodexCompatibleSkillReferences(text: string): string;
 /**
  * Transforms command references to skill references using the default `/`
  * invocation prefix. Converts `/opsx:<command>` patterns to
@@ -46,9 +56,11 @@ export declare function transformToSkillReferences(text: string): string;
 /**
  * Returns the skill-reference transformer for a specific tool, honoring the
  * tool's documented skill invocation syntax (e.g. Kimi Code's
- * `/skill:openspec-propose`). Falls back to the default `/openspec-*` form.
+ * `/skill:openspec-propose`). Tools with no slash surface (e.g. Rovo Dev) get
+ * natural-language references ("the openspec-propose skill"); everything else
+ * falls back to the default `/openspec-*` form.
  *
- * @param toolId - The AI tool identifier (e.g. 'kimi', 'vibe')
+ * @param toolId - The AI tool identifier (e.g. 'kimi', 'vibe', 'rovodev')
  * @returns A transformer converting `/opsx:*` references to skill invocations
  */
 export declare function getSkillReferenceTransformer(toolId: string): (text: string) => string;