@fission-ai/openspec 1.13.1 → 1.14.0

package/dist/core/validation/purpose-placeholder.js

@@ -1,15 +1,30 @@
 import { buildCodeFenceMask } from '../parsers/code-fence.js';
 import { PURPOSE_PLACEHOLDER_PREFIX, PURPOSE_PLACEHOLDER_SUFFIX } from './constants.js';
 /**
- * A `TBD` or `TODO` opening the Purpose. The lookahead keeps it off a longer
- * word that merely begins with those letters, like "TBDs" or "TODOs", while
- * still allowing the punctuation a marker is usually written with: `TODO:`,
- * `TBD -`. It rejects any letter, digit or combining mark rather than only the
- * ASCII ones `\b` knows about, because a Purpose is prose and prose is not
- * always written in Latin script - `TBD` followed by an Arabic-Indic digit is
- * as much a longer word as `TBDs` is.
+ * A `TBD` or `TODO` opening the Purpose.
+ *
+ * `WORD_END` keeps the marker off a longer word that merely begins with those
+ * letters, like "TBDs" or "TODOs", while still allowing the punctuation a
+ * marker is usually written with: `TODO:`, `TBD -`. It rejects any letter,
+ * digit or combining mark rather than only the ASCII ones `\b` knows about,
+ * because a Purpose is prose and prose is not always written in Latin script -
+ * `TBD` followed by an Arabic-Indic digit is as much a longer word as `TBDs`.
+ *
+ * Case is what separates the marker from the word. `TODO` shouted in capitals
+ * is the marker whatever follows it, so `TODO write this later` is still an
+ * unwritten Purpose. Written in any other case it is only a marker when
+ * punctuation or the end of the line says so, because `todo` is an extremely
+ * frequent sentence opener in Spanish ("Todo el...") and Portuguese ("Todo
+ * o..."), and ordinary prose in those languages is not a placeholder. That
+ * keeps the lowercase forms an agent really does leave behind - `todo - write
+ * this later`, `tbd.` - reported, without reading a Spanish sentence as one.
  */
-const LEADING_MARKER = /^(?:TBD|TODO)(?![\p{L}\p{N}\p{M}_])/iu;
+const WORD_END = '(?![\\p{L}\\p{N}\\p{M}_])';
+const MARKER_PUNCTUATION = '(?=[ \\t]*(?:$|\\n|[:\\-\u2013\u2014.,;()\\[\\]{}]))';
+/** `TBD`/`TODO` in capitals: the marker, whatever follows it. */
+const LEADING_MARKER_SHOUTED = new RegExp(`^(?:TBD|TODO)${WORD_END}`, 'u');
+/** Any other case: a marker only when punctuation or the line end says so. */
+const LEADING_MARKER_PUNCTUATED = new RegExp(`^(?:TBD|TODO)${WORD_END}${MARKER_PUNCTUATION}`, 'iu');
 const PURPOSE_HEADER = /^ {0,3}##(?!#)[ \t]+Purpose[ \t]*$/i;
 const TOP_LEVEL_HEADER = /^ {0,3}#{1,2}(?!#)[ \t]+/;
 /**
@@ -60,7 +75,7 @@ export function findPurposePlaceholderIssue(overview, content) {
     // that is nothing but a fenced block reduces to the same empty text here, and
     // is left to the brevity and empty-Purpose rules for the same reason.
     const prose = unfencedLines(overview).join('\n').trim();
-    const leading = LEADING_MARKER.test(prose);
+    const leading = LEADING_MARKER_SHOUTED.test(prose) || LEADING_MARKER_PUNCTUATED.test(prose);
     if (!leading && generatedPlaceholderPrefixIndex(prose) === undefined)
         return null;
     // Which rule matched decides where the placeholder is, so the locator is told.

package/dist/core/validation/validator.js

@@ -5,12 +5,12 @@ import { MarkdownParser } from '../parsers/markdown-parser.js';
 import { ChangeParser } from '../parsers/change-parser.js';
 import { findSpecUpdates, buildUpdatedSpec } from '../specs-apply.js';
 import { MIN_PURPOSE_LENGTH, MAX_REQUIREMENT_TEXT_LENGTH, VALIDATION_MESSAGES } from './constants.js';
-import { parseDeltaSpec, foldRequirementName, normalizeRequirementName, extractRequirementsSection, findMissingCurrentScenarios, } from '../parsers/requirement-blocks.js';
+import { parseDeltaSpec, foldRequirementName, normalizeRequirementName, extractRequirementsSection, diffScenarioNames, describeScenarioBalance, } from '../parsers/requirement-blocks.js';
 import { extractRequirementBody as extractRequirementBodyShared, containsShallOrMust as containsShallOrMustShared, countScenarios as countScenariosShared, countEmptyScenarios, } from '../parsers/requirement-text.js';
 import { findMainSpecStructureIssues } from '../parsers/spec-structure.js';
 import { FileSystemUtils } from '../../utils/file-system.js';
 import { discoverSpecFiles, findUnreadDeltaFiles, hasAnyFileUnder } from '../../utils/spec-discovery.js';
-import { METADATA_FILENAME, readSkipSpecsMarker, resolveSchemaForChange, } from '../../utils/change-metadata.js';
+import { METADATA_FILENAME, formatUnknownChangeMetadataKeysMessage, readSkipSpecsMarker, readUnknownChangeMetadataKeys, resolveSchemaForChange, } from '../../utils/change-metadata.js';
 import { resolveTaskFilesForChange } from '../../utils/task-progress.js';
 import { findTaskNumberingIssues } from './task-numbering.js';
 import { findMissingTaskCheckboxIssues } from './task-checkboxes.js';
@@ -416,6 +416,14 @@ export class Validator {
         if (marker.invalidReason) {
             issues.push({ level: 'ERROR', path: METADATA_FILENAME, message: this.formatInvalidMarkerMessage(marker.invalidReason) });
         }
+        const unknownMetadataKeys = readUnknownChangeMetadataKeys(changeDir);
+        if (unknownMetadataKeys.length > 0) {
+            issues.push({
+                level: 'WARNING',
+                path: METADATA_FILENAME,
+                message: formatUnknownChangeMetadataKeysMessage(unknownMetadataKeys),
+            });
+        }
         // 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
@@ -639,15 +647,16 @@ export class Validator {
             const current = currentBlockFor(key);
             if (!current)
                 continue;
-            const missing = findMissingCurrentScenarios(current, block);
-            if (missing.length === 0)
+            const diff = diffScenarioNames(current, block);
+            if (diff.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).',
+                    `${diff.missing.map(name => `"${name}"`).join(', ')}. ` +
+                    `${describeScenarioBalance(diff)} ` +
+                    'Copy the omitted scenarios into the MODIFIED block (a MODIFIED requirement replaces the whole block, so archive refuses to drop them).',
             });
         }
         return issues;

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

@@ -14,9 +14,19 @@ export declare function registryUrl(): string | null;
  * otherwise. Prereleases sort below their release (1.7.0-beta.1 < 1.7.0).
  */
 export declare function compareVersions(a: string, b: string): number;
+export type CliUpdateStatus = 'available' | 'current' | 'disabled' | 'offline';
+export interface CliUpdateCheck {
+    status: CliUpdateStatus;
+    latest: string | null;
+}
+/**
+ * Checks the registry while preserving enough detail for callers to explain
+ * why no newer version was reported. Never throws.
+ */
+export declare function checkForCliUpdate(): Promise<CliUpdateCheck>;
 /**
  * Returns the published version when the installed CLI is behind it, otherwise
- * null. Never throws and never blocks for longer than the request timeout.
+ * null. Kept as the compatibility surface used by `openspec update`.
  */
 export declare function getAvailableCliUpdate(): Promise<string | null>;
 /**
@@ -69,11 +79,23 @@ export declare function isNpmGlobalInstall(installDir: string | null, roots?: st
  */
 export declare function isSourceCheckout(installDir: string | null): boolean;
 export type PackageManager = 'npm' | 'pnpm' | 'bun' | 'yarn' | 'volta';
+export type InstallScope = 'global' | 'project' | 'temporary' | 'source';
+export interface CliInstallInfo {
+    location: string | null;
+    packageManager: PackageManager | null;
+    scope: InstallScope | null;
+}
 /**
  * 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;
+/** Describes the running copy without guessing when its owner is ambiguous. */
+export declare function getCliInstallInfo(installDir?: string | null, projectPath?: string): CliInstallInfo;
+/** Returns a safe update command only for an install with known global ownership. */
+export declare function getCliUpdateCommand(install: CliInstallInfo): string | null;
+/** Builds the concise human-readable form of the version report. */
+export declare function buildVersionReportLines(version: string, install: CliInstallInfo, update?: CliUpdateCheck, command?: string | null): string[];
 /**
  * Builds the hint, with the upgrade command chosen for how this copy of the CLI
  * was installed. Pure so every branch is assertable.

package/dist/core/version-check.js

@@ -6,6 +6,7 @@ import { createRequire } from 'module';
 import chalk from 'chalk';
 import { isCiEnvironment } from '../utils/ci.js';
 import { isTelemetryOptedOutByEnv } from '../telemetry/opt-out.js';
+import { FileSystemUtils } from '../utils/file-system.js';
 import { getGlobalConfig, isGlobalConfigUnreadable } from './global-config.js';
 const require = createRequire(import.meta.url);
 const { name: PACKAGE_NAME, version: OPENSPEC_VERSION } = require('../../package.json');
@@ -268,22 +269,34 @@ function fetchLatestVersion() {
     });
 }
 /**
- * Returns the published version when the installed CLI is behind it, otherwise
- * null. Never throws and never blocks for longer than the request timeout.
+ * Checks the registry while preserving enough detail for callers to explain
+ * why no newer version was reported. Never throws.
  */
-export async function getAvailableCliUpdate() {
-    if (!isCheckEnabled())
-        return null;
+export async function checkForCliUpdate() {
+    if (!isCheckEnabled() || registryUrl() === null) {
+        return { status: 'disabled', latest: null };
+    }
     try {
         const latest = await fetchLatestVersion();
         if (!latest)
-            return null;
-        return compareVersions(latest, OPENSPEC_VERSION) > 0 ? latest : null;
+            return { status: 'offline', latest: null };
+        return {
+            status: compareVersions(latest, OPENSPEC_VERSION) > 0 ? 'available' : 'current',
+            latest,
+        };
     }
     catch {
-        return null;
+        return { status: 'offline', latest: null };
     }
 }
+/**
+ * Returns the published version when the installed CLI is behind it, otherwise
+ * null. Kept as the compatibility surface used by `openspec update`.
+ */
+export async function getAvailableCliUpdate() {
+    const result = await checkForCliUpdate();
+    return result.status === 'available' ? result.latest : 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
@@ -312,8 +325,8 @@ export function isProjectLocalInstall(installDir, projectPath = '.') {
     // Windows paths differ in case and drive-letter casing between sources.
     const normalize = (value) => process.platform === 'win32' ? value.toLowerCase() : value;
     try {
-        let dir = path.resolve(projectPath);
-        const target = normalize(installDir);
+        let dir = FileSystemUtils.canonicalizeExistingPath(projectPath);
+        const target = normalize(FileSystemUtils.canonicalizeExistingPath(installDir));
         for (;;) {
             if (target.startsWith(normalize(path.join(dir, 'node_modules') + path.sep))) {
                 return true;
@@ -443,32 +456,29 @@ export function isSourceCheckout(installDir) {
         return false;
     }
 }
-/**
- * The package manager that owns this copy, so the printed command is one the
- * user's setup will actually honor.
- */
-export function detectPackageManager(installDir) {
-    // Lowercased because the Windows directories are capitalized and undotted:
-    // %LOCALAPPDATA%\\Volta, \\Yarn\\Data, \\pnpm-cache.
+function detectKnownPackageManager(installDir) {
     const segments = (installDir ?? '').split(/[\\/]/).map((segment) => segment.toLowerCase());
     const has = (...names) => names.some((name) => segments.includes(name));
-    // The undotted spelling exists for Windows (%LOCALAPPDATA%\Volta), whose
-    // layout nests tools\image; require both segments so a user or project
-    // directory merely named "volta" (even one with its own "tools" dir) does
-    // not steal the install.
     if (has('.volta') || (has('volta') && has('tools') && has('image')))
         return 'volta';
-    if (has('.bun'))
+    if (has('.bun', '_bunx', 'bun-cache'))
         return 'bun';
-    // These two need a corroborating segment: a directory merely named "pnpm" or
-    // "yarn" (a user's home, a project) is not a global install of one.
-    if (has('.pnpm-global', 'pnpm-cache'))
+    if (has('_npx'))
+        return 'npm';
+    if (has('.pnpm', '.pnpm-global', 'pnpm-cache'))
         return 'pnpm';
     if (has('pnpm') && has('global', 'dlx', 'store'))
         return 'pnpm';
     if (has('.yarn') || (has('yarn') && has('global')))
         return 'yarn';
-    return 'npm';
+    return null;
+}
+/**
+ * The package manager that owns this copy, so the printed command is one the
+ * user's setup will actually honor.
+ */
+export function detectPackageManager(installDir) {
+    return detectKnownPackageManager(installDir) ?? 'npm';
 }
 const GLOBAL_UPGRADE_COMMANDS = {
     npm: `npm install -g ${PACKAGE_NAME}@latest`,
@@ -477,6 +487,82 @@ const GLOBAL_UPGRADE_COMMANDS = {
     yarn: `yarn global add ${PACKAGE_NAME}@latest`,
     volta: `volta install ${PACKAGE_NAME}@latest`,
 };
+function detectGlobalPackageManager(installDir) {
+    if (isNpmGlobalInstall(installDir))
+        return 'npm';
+    if (!installDir)
+        return null;
+    const segments = installDir.split(/[\\/]/).map((segment) => segment.toLowerCase());
+    const has = (...names) => names.some((name) => segments.includes(name));
+    const hasSequence = (...names) => segments.some((_, index) => names.every((name, offset) => segments[index + offset] === name));
+    if (hasSequence('.volta', 'tools', 'image') || hasSequence('volta', 'tools', 'image')) {
+        return 'volta';
+    }
+    if (has('.pnpm-global') || hasSequence('pnpm', 'global'))
+        return 'pnpm';
+    if (hasSequence('yarn', 'global') || hasSequence('yarn', 'data', 'global'))
+        return 'yarn';
+    if (hasSequence('.bun', 'install', 'global'))
+        return 'bun';
+    return null;
+}
+/** Describes the running copy without guessing when its owner is ambiguous. */
+export function getCliInstallInfo(installDir = getInstallDir(), projectPath = '.') {
+    if (!installDir) {
+        return { location: null, packageManager: null, scope: null };
+    }
+    if (isSourceCheckout(installDir)) {
+        return { location: installDir, packageManager: null, scope: 'source' };
+    }
+    if (isEphemeralRunnerInstall(installDir)) {
+        return {
+            location: installDir,
+            packageManager: detectKnownPackageManager(installDir),
+            scope: 'temporary',
+        };
+    }
+    if (isProjectLocalInstall(installDir, projectPath)) {
+        return {
+            location: installDir,
+            packageManager: detectKnownPackageManager(installDir),
+            scope: 'project',
+        };
+    }
+    const packageManager = detectGlobalPackageManager(installDir);
+    return {
+        location: installDir,
+        packageManager,
+        scope: packageManager ? 'global' : null,
+    };
+}
+/** Returns a safe update command only for an install with known global ownership. */
+export function getCliUpdateCommand(install) {
+    if (install.scope !== 'global' || install.packageManager === null)
+        return null;
+    return GLOBAL_UPGRADE_COMMANDS[install.packageManager];
+}
+/** Builds the concise human-readable form of the version report. */
+export function buildVersionReportLines(version, install, update, command = null) {
+    const details = [install.packageManager, install.scope].filter(Boolean).join(', ');
+    const lines = [`OpenSpec ${version}${details ? ` (${details})` : ''}`];
+    if (!update)
+        return lines;
+    if (update.status === 'available') {
+        lines.push(`Update available: ${update.latest}`);
+        if (command)
+            lines.push(`  ${command}`);
+    }
+    else if (update.status === 'current') {
+        lines.push('OpenSpec is up to date.');
+    }
+    else if (update.status === 'disabled') {
+        lines.push('Update check disabled.');
+    }
+    else {
+        lines.push('Could not check for updates.');
+    }
+    return lines;
+}
 /**
  * Builds the hint, with the upgrade command chosen for how this copy of the CLI
  * was installed. Pure so every branch is assertable.

package/dist/core/view.d.ts

@@ -3,6 +3,8 @@ export declare class ViewCommand {
     private getChangesData;
     private getSpecsData;
     private displaySummary;
+    private sanitizeWorkflowText;
+    private formatWorkflowArtifacts;
     private createProgressBar;
 }
 //# sourceMappingURL=view.d.ts.map

package/dist/core/view.js

@@ -4,6 +4,7 @@ import chalk from 'chalk';
 import { getTaskProgressForChange } from '../utils/task-progress.js';
 import { MarkdownParser } from './parsers/markdown-parser.js';
 import { discoverSpecFiles } from '../utils/spec-discovery.js';
+import { loadChangeContext, formatChangeStatus } from './artifact-graph/index.js';
 export class ViewCommand {
     async execute(targetPath = '.') {
         const openspecDir = path.join(targetPath, 'openspec');
@@ -30,12 +31,17 @@ export class ViewCommand {
         if (changesData.active.length > 0) {
             console.log(chalk.bold.cyan('\nActive Changes'));
             console.log('─'.repeat(60));
+            const maxNameLength = Math.min(48, Math.max(30, ...changesData.active.map((change) => change.name.length)));
             changesData.active.forEach((change) => {
                 const progressBar = this.createProgressBar(change.progress.completed, change.progress.total);
                 const percentage = change.progress.total > 0
                     ? Math.round((change.progress.completed / change.progress.total) * 100)
                     : 0;
-                console.log(`  ${chalk.yellow('◉')} ${chalk.bold(change.name.padEnd(30))} ${progressBar} ${chalk.dim(`${percentage}%`)}`);
+                console.log(`  ${chalk.yellow('◉')} ${chalk.bold(change.name.padEnd(maxNameLength))} ${progressBar} ${chalk.dim(`${percentage}%`)}`);
+                if (change.workflowStatus) {
+                    const { schemaName, artifacts } = change.workflowStatus;
+                    console.log(`    ${chalk.dim(`└─ [${this.sanitizeWorkflowText(schemaName)}]`)} ${this.formatWorkflowArtifacts(artifacts)}`);
+                }
             });
         }
         // Display completed changes
@@ -46,6 +52,14 @@ export class ViewCommand {
                 console.log(`  ${chalk.green('✓')} ${change.name}`);
             });
         }
+        // Display archived changes
+        if (changesData.archived.length > 0) {
+            console.log(chalk.bold.gray('\nArchived Changes'));
+            console.log('─'.repeat(60));
+            changesData.archived.forEach((change) => {
+                console.log(chalk.gray(`  ◦ ${change.name}`));
+            });
+        }
         // Display specifications
         if (specsData.length > 0) {
             console.log(chalk.bold.blue('\nSpecifications'));
@@ -62,12 +76,27 @@ export class ViewCommand {
     }
     async getChangesData(openspecDir) {
         const changesDir = path.join(openspecDir, 'changes');
+        const projectRoot = path.dirname(openspecDir);
         if (!fs.existsSync(changesDir)) {
-            return { draft: [], active: [], completed: [] };
+            return { draft: [], active: [], completed: [], archived: [] };
         }
         const draft = [];
         const active = [];
         const completed = [];
+        let archived = [];
+        try {
+            archived = fs.readdirSync(path.join(changesDir, 'archive'), { withFileTypes: true })
+                .filter((entry) => entry.isDirectory() && !entry.name.startsWith('.'))
+                .map((entry) => ({ name: entry.name }));
+        }
+        catch (error) {
+            // A missing archive, or an `archive` path that is a file, has no archived
+            // changes to show; neither should break the rest of the dashboard.
+            const code = error.code;
+            if (code !== 'ENOENT' && code !== 'ENOTDIR') {
+                throw error;
+            }
+        }
         const entries = fs.readdirSync(changesDir, { withFileTypes: true });
         for (const entry of entries) {
             if (entry.isDirectory() && entry.name !== 'archive') {
@@ -82,7 +111,15 @@ export class ViewCommand {
                 }
                 else {
                     // Has tasks but not all complete
-                    active.push({ name: entry.name, progress });
+                    let workflowStatus;
+                    try {
+                        workflowStatus = formatChangeStatus(loadChangeContext(projectRoot, entry.name));
+                    }
+                    catch (error) {
+                        // Preserve task progress even when this change's workflow cannot be loaded.
+                        console.warn(chalk.yellow(this.sanitizeWorkflowText(`Could not load workflow status for "${entry.name}": ${error instanceof Error ? error.message : String(error)}`)));
+                    }
+                    active.push({ name: entry.name, progress, workflowStatus });
                 }
             }
         }
@@ -99,7 +136,8 @@ export class ViewCommand {
             return a.name.localeCompare(b.name);
         });
         completed.sort((a, b) => a.name.localeCompare(b.name));
-        return { draft, active, completed };
+        archived.sort((a, b) => a.name.localeCompare(b.name));
+        return { draft, active, completed, archived };
     }
     async getSpecsData(openspecDir) {
         const specsDir = path.join(openspecDir, 'specs');
@@ -144,11 +182,31 @@ export class ViewCommand {
         }
         console.log(`  ${chalk.yellow('●')} Active Changes: ${chalk.bold(changesData.active.length)} in progress`);
         console.log(`  ${chalk.green('●')} Completed Changes: ${chalk.bold(changesData.completed.length)}`);
+        console.log(`  ${chalk.gray('●')} Archived Changes: ${chalk.bold(changesData.archived.length)}`);
         if (totalTasks > 0) {
             const overallProgress = Math.round((completedTasks / totalTasks) * 100);
             console.log(`  ${chalk.magenta('●')} Task Progress: ${chalk.bold(`${completedTasks}/${totalTasks}`)} (${overallProgress}% complete)`);
         }
     }
+    sanitizeWorkflowText(value) {
+        // Metadata may contain terminal controls; mask them before adding our own colors.
+        return value.replace(/[\u0000-\u001f\u007f-\u009f]/g, '?');
+    }
+    formatWorkflowArtifacts(artifacts) {
+        return artifacts.map((artifact) => {
+            const id = this.sanitizeWorkflowText(artifact.id);
+            switch (artifact.status) {
+                case 'done':
+                    return `${id}${chalk.green('✓')}`;
+                case 'ready':
+                    return `${id}${chalk.cyan('→')}`;
+                case 'skipped':
+                    return chalk.dim(`${id} (skipped)`);
+                case 'blocked':
+                    return chalk.dim(id);
+            }
+        }).join(' ');
+    }
     createProgressBar(completed, total, width = 20) {
         if (total === 0)
             return chalk.dim('─'.repeat(width));

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

@@ -1,6 +1,25 @@
-import { type ChangeMetadata } from '../core/change-metadata/index.js';
+import { CHANGE_METADATA_KNOWN_KEYS, type ChangeMetadata } from '../core/change-metadata/index.js';
 import { type ProjectConfig } from '../core/project-config.js';
 export declare const METADATA_FILENAME = ".openspec.yaml";
+export { CHANGE_METADATA_KNOWN_KEYS };
+/**
+ * Unknown top-level keys on a parsed .openspec.yaml object. Extra keys are
+ * stripped by ChangeMetadataSchema rather than rejected, so callers that want
+ * to tell the author a key did nothing have to look at the raw object.
+ */
+export declare function listUnknownChangeMetadataKeys(parsed: unknown): string[];
+/**
+ * Human-readable warning for keys ChangeMetadataSchema strips. Names the
+ * unknown keys, the keys that do exist, and (when present) why `skip_design`
+ * is not `skip_specs`.
+ */
+export declare function formatUnknownChangeMetadataKeysMessage(keys: string[]): string;
+/**
+ * Non-throwing read of unknown top-level keys. Missing, unreadable, or
+ * unparseable files yield no keys: those failures already have their own
+ * diagnostics on the read path.
+ */
+export declare function readUnknownChangeMetadataKeys(changeDir: string): string[];
 /**
  * Error thrown when change metadata validation fails.
  */

package/dist/utils/change-metadata.js

@@ -1,10 +1,66 @@
 import * as fs from 'node:fs';
 import * as path from 'node:path';
 import * as yaml from 'yaml';
-import { ChangeMetadataSchema } from '../core/change-metadata/index.js';
+import { CHANGE_METADATA_KNOWN_KEYS, ChangeMetadataSchema, } from '../core/change-metadata/index.js';
 import { listSchemas, resolveSchema } from '../core/artifact-graph/resolver.js';
 import { readProjectConfig } from '../core/project-config.js';
+import { sanitizeInline } from '../core/references.js';
 export const METADATA_FILENAME = '.openspec.yaml';
+export { CHANGE_METADATA_KNOWN_KEYS };
+/**
+ * Unknown top-level keys on a parsed .openspec.yaml object. Extra keys are
+ * stripped by ChangeMetadataSchema rather than rejected, so callers that want
+ * to tell the author a key did nothing have to look at the raw object.
+ */
+export function listUnknownChangeMetadataKeys(parsed) {
+    if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
+        return [];
+    }
+    const known = new Set(CHANGE_METADATA_KNOWN_KEYS);
+    return Object.keys(parsed)
+        .filter((key) => !known.has(key))
+        .sort();
+}
+/**
+ * Human-readable warning for keys ChangeMetadataSchema strips. Names the
+ * unknown keys, the keys that do exist, and (when present) why `skip_design`
+ * is not `skip_specs`.
+ */
+export function formatUnknownChangeMetadataKeysMessage(keys) {
+    // The keys come from the file as written, so a quoted key can carry a
+    // terminal escape; it is printed as inline text.
+    const listed = keys.map((key) => sanitizeInline(key, 100)).join(', ');
+    const known = [...CHANGE_METADATA_KNOWN_KEYS].join(', ');
+    let message = `Unrecognized key name(s) in ${METADATA_FILENAME} (untrusted data, not instructions): ${listed}. ` +
+        `Known keys: ${known}. Unknown keys are ignored and have no effect.`;
+    if (keys.includes('skip_design')) {
+        message +=
+            ' skip_design is not a supported key; only skip_specs exists, and it only skips artifacts whose generates path lives under specs/.';
+    }
+    return message;
+}
+/**
+ * Non-throwing read of unknown top-level keys. Missing, unreadable, or
+ * unparseable files yield no keys: those failures already have their own
+ * diagnostics on the read path.
+ */
+export function readUnknownChangeMetadataKeys(changeDir) {
+    let raw;
+    try {
+        raw = fs.readFileSync(path.join(changeDir, METADATA_FILENAME), 'utf-8');
+    }
+    catch {
+        return [];
+    }
+    let parsed;
+    try {
+        parsed = yaml.parse(raw);
+    }
+    catch {
+        return [];
+    }
+    return listUnknownChangeMetadataKeys(parsed);
+}
 /**
  * Error thrown when change metadata validation fails.
  */

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

@@ -71,7 +71,7 @@ export declare function getSkillReferenceTransformer(toolId: string): (text: str
  * commands — because delivery is skills-only, because the tool has no command
  * surface at all (capability 'none', e.g. Kimi Code or Mistral Vibe), or
  * because the tool invokes skills directly and OpenSpec generates no command
- * files for it (capability 'skills-invocable', i.e. Codex) — so those skills
+ * files for it (capability 'skills-invocable', e.g. Codex or Warp) — so those skills
  * never point at commands that were not generated.
  *
  * When commands are generated, the spelling follows the tool's invocation: a

package/dist/utils/command-references.js

@@ -67,7 +67,7 @@ const SKILL_INVOCATION_PREFIX = {
  * Skill references for these tools are spelled as prose ("the openspec-propose
  * skill") so skills-only delivery does not advertise unregistered commands.
  */
-const NATURAL_LANGUAGE_SKILL_TOOLS = new Set(['rovodev', 'codeassistant']);
+const NATURAL_LANGUAGE_SKILL_TOOLS = new Set(['gsd', 'rovodev', 'codeassistant']);
 /**
  * Whether a tool references skills by natural language rather than a slash
  * command (see NATURAL_LANGUAGE_SKILL_TOOLS).
@@ -146,7 +146,7 @@ export function getSkillReferenceTransformer(toolId) {
  * commands — because delivery is skills-only, because the tool has no command
  * surface at all (capability 'none', e.g. Kimi Code or Mistral Vibe), or
  * because the tool invokes skills directly and OpenSpec generates no command
- * files for it (capability 'skills-invocable', i.e. Codex) — so those skills
+ * files for it (capability 'skills-invocable', e.g. Codex or Warp) — so those skills
  * never point at commands that were not generated.
  *
  * When commands are generated, the spelling follows the tool's invocation: a

package/dist/utils/file-system.js

@@ -1,5 +1,6 @@
 import * as nodeFs from 'fs';
 import path from 'path';
+import { detectLineEnding, matchLineEnding } from './line-endings.js';
 const fs = nodeFs.promises;
 const { constants: fsConstants } = nodeFs;
 function hasOwnerGroupOrOtherWriteBit(stats) {
@@ -277,8 +278,14 @@ export class FileSystemUtils {
     }
     static async updateFileWithMarkers(filePath, content, startMarker, endMarker) {
         let existingContent = '';
+        // The managed block is composed with '\n', so splicing it into a CRLF file
+        // would leave mixed endings behind. bash reports a stray '\r' in .bashrc as
+        // "$'\r': command not found", so settle the whole file on the convention it
+        // already used. A file that does not exist yet stays LF.
+        let originalContent;
         if (await this.fileExists(filePath)) {
             existingContent = await this.readFile(filePath);
+            originalContent = existingContent;
             const startIndex = findMarkerIndex(existingContent, startMarker);
             const endIndex = startIndex !== -1
                 ? findMarkerIndex(existingContent, endMarker, startIndex + startMarker.length)
@@ -301,7 +308,9 @@ export class FileSystemUtils {
         else {
             existingContent = startMarker + '\n' + content + '\n' + endMarker;
         }
-        await this.writeFile(filePath, existingContent);
+        await this.writeFile(filePath, originalContent === undefined
+            ? existingContent
+            : matchLineEnding(existingContent, originalContent));
     }
     static async ensureWritePermissions(dirPath) {
         try {
@@ -377,14 +386,22 @@ export function removeMarkerBlock(content, startMarker, endMarker) {
     }
     const before = content.substring(0, lineStart);
     const after = content.substring(lineEnd);
+    // The file's own newline, used for every ending this function writes. The
+    // blank-line collapse below rebuilds the separator it matched, so spelling it
+    // '\n' would leave a CRLF file with a mixed pair wherever a run was collapsed
+    // - the stray '\r' that bash reports as "$'\r': command not found".
+    //
+    // Dominant rather than "contains a CRLF anywhere", so that one stray CRLF in
+    // an otherwise-LF file does not pull the whole rewrite to CRLF. This is the
+    // same reading matchLineEnding uses, so both write paths agree.
+    const newline = detectLineEnding(content) ?? '\n';
     // Clean up double blank lines (handle both Unix \n and Windows \r\n)
     let result = before + after;
-    result = result.replace(/(\r?\n){3,}/g, '\n\n');
+    result = result.replace(/(\r?\n){3,}/g, newline + newline);
     // Trim trailing whitespace but preserve leading whitespace and original newline style
     if (result.trimEnd() === '') {
         return '';
     }
-    const newline = content.includes('\r\n') ? '\r\n' : '\n';
     return result.trimEnd() + newline;
 }
 //# sourceMappingURL=file-system.js.map