@codewalla_india/openspec 1.3.0 → 1.3.2

package/dist/telemetry/sanitization.js

@@ -0,0 +1,114 @@
+/**
+ * Data sanitization module for telemetry.
+ *
+ * Sanitizes sensitive information from telemetry events:
+ * - Removes file paths from stack traces while preserving function names
+ * - Excludes file paths from event properties
+ * - Sanitizes artifact bodies for comprehension events
+ * - Ensures IP address exclusion consistency
+ */
+/**
+ * Sanitize a stack trace by removing file paths while preserving function names and error types.
+ *
+ * @param stackTrace - The raw stack trace string
+ * @returns The sanitized stack trace
+ */
+export function sanitizeStackTrace(stackTrace) {
+    if (!stackTrace) {
+        return '';
+    }
+    // Remove file paths (both Unix and Windows styles)
+    // Pattern matches: /path/to/file.js:line:column or C:\path\to\file.js:line:column
+    const sanitized = stackTrace
+        .replace(/at\s+.*?\.js:\d+:\d+/g, 'at <redacted>')
+        .replace(/at\s+.*?\.ts:\d+:\d+/g, 'at <redacted>')
+        .replace(/at\s+.*?\.mjs:\d+:\d+/g, 'at <redacted>')
+        .replace(/at\s+.*?\.cjs:\d+:\d+/g, 'at <redacted>')
+        // Remove absolute paths in error messages
+        .replace(/[A-Za-z]:\\[^\\]+\\/g, '<redacted>')
+        .replace(/\/[^\/\s]+\/[^\/\s]+/g, '<redacted>');
+    return sanitized;
+}
+/**
+ * Sanitize an object by removing file paths from string properties.
+ *
+ * @param obj - The object to sanitize
+ * @returns The sanitized object
+ */
+export function sanitizeObject(obj) {
+    const sanitized = {};
+    for (const [key, value] of Object.entries(obj)) {
+        if (typeof value === 'string') {
+            // Remove file paths from string values
+            sanitized[key] = sanitizeString(value);
+        }
+        else if (typeof value === 'object' && value !== null && !Array.isArray(value)) {
+            // Recursively sanitize nested objects
+            sanitized[key] = sanitizeObject(value);
+        }
+        else if (Array.isArray(value)) {
+            // Recursively sanitize array elements
+            sanitized[key] = value.map((item) => {
+                if (typeof item === 'string') {
+                    return sanitizeString(item);
+                }
+                else if (typeof item === 'object' && item !== null) {
+                    return sanitizeObject(item);
+                }
+                return item;
+            });
+        }
+        else {
+            sanitized[key] = value;
+        }
+    }
+    return sanitized;
+}
+/**
+ * Sanitize a string by removing file paths.
+ *
+ * @param str - The string to sanitize
+ * @returns The sanitized string
+ */
+function sanitizeString(str) {
+    // Remove absolute file paths (both Unix and Windows)
+    return str
+        .replace(/[A-Za-z]:\\[^\\]+\\/g, '<redacted>')
+        .replace(/\/[^\/\s]+\/[^\/\s]+/g, '<redacted>');
+}
+/**
+ * Sanitize artifact body content for comprehension events.
+ *
+ * Removes file paths and sensitive information while preserving code structure.
+ *
+ * @param content - The artifact body content
+ * @returns The sanitized artifact body
+ */
+export function sanitizeArtifactBody(content) {
+    if (!content) {
+        return '';
+    }
+    // Remove file paths in comments and strings
+    const lines = content.split('\n');
+    const sanitizedLines = lines.map((line) => {
+        // Remove file paths from import statements and require calls
+        if (line.includes('from ') || line.includes('require(') || line.includes('import ')) {
+            return sanitizeString(line);
+        }
+        return line;
+    });
+    return sanitizedLines.join('\n');
+}
+/**
+ * Ensure IP address exclusion by setting $ip to null in event properties.
+ *
+ * @param properties - The event properties object
+ * @returns The properties with $ip set to null
+ */
+export function ensureIpExclusion(properties) {
+    return {
+        ...properties,
+        $ip: null,
+    };
+}
+//# sourceMappingURL=sanitization.js.map

package/dist/telemetry/sanitization.test.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Unit tests for sanitization module.
+ */
+export {};
+//# sourceMappingURL=sanitization.test.d.ts.map

package/dist/telemetry/throttling.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Get the path to the throttling state file.
+ *
+ * @returns Path to the throttling state file
+ */
+export declare function getThrottleFilePath(): string;
+/**
+ * Check if $identify call should be throttled based on 24-hour window.
+ *
+ * @param identity - The identity to check throttling for
+ * @returns True if $identify should be throttled, false otherwise
+ */
+export declare function shouldThrottleIdentify(identity: string): Promise<boolean>;
+/**
+ * Record timestamp of $identify call for throttling.
+ *
+ * @param identity - The identity to record the call for
+ */
+export declare function recordIdentifyCall(identity: string): Promise<void>;
+//# sourceMappingURL=throttling.d.ts.map

package/dist/telemetry/throttling.js

@@ -0,0 +1,70 @@
+/**
+ * Throttling module for $identify calls.
+ *
+ * Implements local state persistence to throttle $identify calls to once per 24 hours.
+ */
+import { promises as fs } from 'fs';
+import path from 'path';
+import { getGlobalConfigDir } from '../core/global-config.js';
+// Constants
+const THROTTLE_FILE_NAME = 'telemetry-identify-throttle.json';
+const THROTTLE_WINDOW_MS = 24 * 60 * 60 * 1000; // 24 hours in milliseconds
+/**
+ * Get the path to the throttling state file.
+ *
+ * @returns Path to the throttling state file
+ */
+export function getThrottleFilePath() {
+    const configDir = getGlobalConfigDir();
+    return path.join(configDir, THROTTLE_FILE_NAME);
+}
+/**
+ * Check if $identify call should be throttled based on 24-hour window.
+ *
+ * @param identity - The identity to check throttling for
+ * @returns True if $identify should be throttled, false otherwise
+ */
+export async function shouldThrottleIdentify(identity) {
+    const throttlePath = getThrottleFilePath();
+    try {
+        const content = await fs.readFile(throttlePath, 'utf-8');
+        const state = JSON.parse(content);
+        const lastIdentifyTime = state[identity];
+        if (!lastIdentifyTime) {
+            return false; // No previous call, don't throttle
+        }
+        const now = Date.now();
+        const timeSinceLastCall = now - lastIdentifyTime;
+        return timeSinceLastCall < THROTTLE_WINDOW_MS;
+    }
+    catch (error) {
+        // If file doesn't exist or is invalid, don't throttle
+        return false;
+    }
+}
+/**
+ * Record timestamp of $identify call for throttling.
+ *
+ * @param identity - The identity to record the call for
+ */
+export async function recordIdentifyCall(identity) {
+    const throttlePath = getThrottleFilePath();
+    const throttleDir = path.dirname(throttlePath);
+    // Create directory if it doesn't exist
+    await fs.mkdir(throttleDir, { recursive: true });
+    // Read existing state or create new
+    let state = {};
+    try {
+        const content = await fs.readFile(throttlePath, 'utf-8');
+        state = JSON.parse(content);
+    }
+    catch {
+        // File doesn't exist or is invalid, start fresh
+        state = {};
+    }
+    // Update timestamp for this identity
+    state[identity] = Date.now();
+    // Write back to file
+    await fs.writeFile(throttlePath, JSON.stringify(state, null, 2) + '\n');
+}
+//# sourceMappingURL=throttling.js.map

package/dist/ui/welcome-screen.d.ts

@@ -2,9 +2,17 @@
  * Animated welcome screen for the experimental artifact workflow setup.
  * Shows side-by-side layout with animated ASCII art on left and welcome text on right.
  */
+/**
+ * Best-effort check of the OS-level reduced-motion preference (#722).
+ * Any lookup failure (missing binary, unset key, timeout) means
+ * "no preference detected" and animation stays enabled.
+ */
+export declare function prefersReducedMotion(platform?: NodeJS.Platform): boolean;
 /**
  * Shows the animated welcome screen.
  * Returns when user presses Enter.
  */
-export declare function showWelcomeScreen(): Promise<void>;
+export declare function showWelcomeScreen(workflows: readonly string[], options?: {
+    animate?: boolean;
+}): Promise<void>;
 //# sourceMappingURL=welcome-screen.d.ts.map

package/dist/ui/welcome-screen.js

@@ -3,7 +3,9 @@
  * Shows side-by-side layout with animated ASCII art on left and welcome text on right.
  */
 import chalk from 'chalk';
+import { execFileSync, } from 'node:child_process';
 import { WELCOME_ANIMATION } from './ascii-patterns.js';
+import { getOnboardingCommands } from '../core/onboarding-commands.js';
 // Minimum terminal width for side-by-side layout
 const MIN_WIDTH = 60;
 // Width of the ASCII art column (with padding)
@@ -11,20 +13,35 @@ const ART_COLUMN_WIDTH = 24;
 /**
  * Welcome text content (right column)
  */
-function getWelcomeText() {
+function getWelcomeText(workflows) {
+    const onboardingCommands = getOnboardingCommands(workflows);
+    const quickStart = [];
+    if (onboardingCommands.length > 0) {
+        const commandWidth = Math.max(...onboardingCommands.map((c) => c.command.length));
+        quickStart.push(chalk.white('Quick start after setup:'));
+        for (const { command, description } of onboardingCommands) {
+            quickStart.push(`  ${chalk.yellow(command.padEnd(commandWidth + 1))} ${chalk.dim(description)}`);
+        }
+        // These are the canonical names. How each tool spells them differs
+        // (/opsx-propose, @opsx-propose, $openspec-propose ...) and cannot be known
+        // until tools are picked, one prompt later — so flag it rather than let the
+        // canonical form read as the literal thing to type. "Getting started"
+        // prints the real spelling once the selection is known.
+        quickStart.push(chalk.dim('  (spelling varies by tool)'));
+        quickStart.push('');
+    }
     return [
         chalk.white.bold('Welcome to OpenSpec'),
         chalk.dim('A lightweight spec-driven framework'),
         '',
         chalk.white('This setup will configure:'),
         chalk.dim('  • Agent Skills for AI tools'),
-        chalk.dim('  • /opsx:* slash commands'),
-        '',
-        chalk.white('Quick start after setup:'),
-        `  ${chalk.yellow('/opsx:new')}      ${chalk.dim('Create a change')}`,
-        `  ${chalk.yellow('/opsx:continue')} ${chalk.dim('Next artifact')}`,
-        `  ${chalk.yellow('/opsx:apply')}    ${chalk.dim('Implement tasks')}`,
+        // Not "opsx slash commands": this screen runs before tool selection, and
+        // skills-only tools (Codex, Kimi Code, ...) correctly get no command files
+        // at all. The exact spelling per tool is printed in "Getting started".
+        chalk.dim('  • Workflow commands, if supported'),
         '',
+        ...quickStart,
         chalk.cyan('Press Enter to select tools...'),
     ];
 }
@@ -46,6 +63,36 @@ function renderFrame(artLines, textLines) {
     }
     return lines.join('\n');
 }
+const REDUCED_MOTION_EXEC_OPTIONS = {
+    encoding: 'utf8',
+    timeout: 500,
+    // SIGKILL so a wedged lookup can never outlive the timeout and stall init.
+    killSignal: 'SIGKILL',
+    stdio: ['ignore', 'pipe', 'ignore'],
+};
+/**
+ * Best-effort check of the OS-level reduced-motion preference (#722).
+ * Any lookup failure (missing binary, unset key, timeout) means
+ * "no preference detected" and animation stays enabled.
+ */
+export function prefersReducedMotion(platform = process.platform) {
+    try {
+        if (platform === 'darwin') {
+            // The key only exists once the user has toggled Reduce Motion; when it
+            // is unset `defaults` exits non-zero and lands in the catch below.
+            const out = execFileSync('defaults', ['read', 'com.apple.universalaccess', 'reduceMotion'], REDUCED_MOTION_EXEC_OPTIONS);
+            return out.trim() === '1';
+        }
+        if (platform === 'linux') {
+            const out = execFileSync('gsettings', ['get', 'org.gnome.desktop.interface', 'enable-animations'], REDUCED_MOTION_EXEC_OPTIONS);
+            return out.trim() === 'false';
+        }
+    }
+    catch {
+        // Detection is best-effort only.
+    }
+    return false;
+}
 /**
  * Checks if the terminal supports animation
  */
@@ -56,54 +103,60 @@ function canAnimate() {
     // Respect NO_COLOR
     if (process.env.NO_COLOR)
         return false;
+    // Manual override for users who need reduced motion (#722). Presence is
+    // what counts: even an empty value disables the animation.
+    if (process.env.OPENSPEC_NO_ANIMATION !== undefined)
+        return false;
     // Check terminal width
     const columns = process.stdout.columns || 80;
     if (columns < MIN_WIDTH)
         return false;
+    // Last so only interactive terminals pay for the OS lookup
+    if (prefersReducedMotion())
+        return false;
     return true;
 }
 /**
  * Wait for Enter key press
  */
-function waitForEnter() {
-    return new Promise((resolve) => {
-        const { stdin } = process;
-        // Handle non-TTY gracefully
-        if (!stdin.isTTY) {
-            resolve();
-            return;
-        }
-        const wasRaw = stdin.isRaw;
-        stdin.setRawMode(true);
-        stdin.resume();
-        const onData = (data) => {
-            const char = data.toString();
-            // Enter key or Ctrl+C
-            if (char === '\r' || char === '\n' || char === '\u0003') {
-                stdin.removeListener('data', onData);
-                stdin.setRawMode(wasRaw);
-                stdin.pause();
-                // Handle Ctrl+C
-                if (char === '\u0003') {
-                    process.stdout.write('\n');
-                    process.exit(0);
-                }
-                resolve();
+async function waitForEnter() {
+    if (!process.stdin.isTTY) {
+        return;
+    }
+    // Keep all interactive input on Inquirer's keypress lifecycle. Mixing a raw
+    // `data` listener between Inquirer prompts breaks arrow/space keys on Windows.
+    const { createPrompt, isEnterKey, useKeypress } = await import('@inquirer/core');
+    const prompt = createPrompt((_config, done) => {
+        useKeypress((key) => {
+            if (key.ctrl && key.name === 'c') {
+                process.stdout.write('\n');
+                process.exit(0);
+            }
+            if (isEnterKey(key)) {
+                done(undefined);
             }
-        };
-        stdin.on('data', onData);
+        });
+        return '';
     });
+    await prompt({});
 }
 /**
  * Shows the animated welcome screen.
  * Returns when user presses Enter.
  */
-export async function showWelcomeScreen() {
-    const textLines = getWelcomeText();
-    if (!canAnimate()) {
-        // Fallback: show static welcome
+export async function showWelcomeScreen(workflows, options = {}) {
+    const textLines = getWelcomeText(workflows);
+    if (options.animate === false || !canAnimate()) {
+        // Fallback: show static welcome. The "Press Enter" line is only honest
+        // when we actually wait; in a TTY, returning immediately would let the
+        // Enter it asks for fall through into the tool picker and submit the
+        // pre-selected tools sight-unseen. Without a TTY, drop the line instead.
+        const staticLines = process.stdin.isTTY
+            ? textLines
+            : textLines.filter((line) => !line.includes('Press Enter'));
         const frame = WELCOME_ANIMATION.frames[3]; // Peak frame
-        process.stdout.write('\n' + renderFrame(frame, textLines) + '\n\n');
+        process.stdout.write('\n' + renderFrame(frame, staticLines) + '\n\n');
+        await waitForEnter();
         return;
     }
     let frameIndex = 0;

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

@@ -1,4 +1,5 @@
 import { type ChangeMetadata } from '../core/change-metadata/index.js';
+import { type ProjectConfig } from '../core/project-config.js';
 export declare const METADATA_FILENAME = ".openspec.yaml";
 /**
  * Error thrown when change metadata validation fails.
@@ -37,6 +38,8 @@ export declare function writeChangeMetadata(changeDir: string, metadata: ChangeM
 export declare function readChangeMetadata(changeDir: string, projectRoot?: string): ChangeMetadata | null;
 export interface ResolveSchemaForChangeOptions {
     metadata?: ChangeMetadata | null;
+    /** Pre-read project config; suppresses the fallback config read when provided. */
+    projectConfig?: ProjectConfig | null;
 }
 /**
  * Resolves the schema for a change, with explicit override taking precedence.
@@ -52,4 +55,44 @@ export interface ResolveSchemaForChangeOptions {
  * @returns The resolved schema name
  */
 export declare function resolveSchemaForChange(changeDir: string, explicitSchema?: string, projectRootOverride?: string, options?: ResolveSchemaForChangeOptions): string;
+export interface MetadataMarker {
+    /**
+     * True when the metadata parses under ChangeMetadataSchema, sets
+     * the requested boolean marker to true, and names a schema that loads.
+     */
+    declared: boolean;
+    /**
+     * 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
+ * ChangeMetadataSchema, its schema name passes readChangeMetadata's
+ * listSchemas membership check, AND the schema itself loads via resolveSchema
+ * (a schema.yaml that exists but does not parse fails status just the same).
+ * Validate and archive must never honor metadata the rest of the CLI rejects,
+ * in either direction. The project root for schema resolution is derived from
+ * changeDir exactly like resolveSchemaForChange (changeDir is
+ * <root>/openspec/changes/<name> for every root type, including store roots).
+ * Missing metadata means "not declared"; a marker that cannot be honored
+ * yields invalidReason so callers can say why.
+ */
+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

@@ -2,7 +2,7 @@ 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 { listSchemas } from '../core/artifact-graph/resolver.js';
+import { listSchemas, resolveSchema } from '../core/artifact-graph/resolver.js';
 import { readProjectConfig } from '../core/project-config.js';
 export const METADATA_FILENAME = '.openspec.yaml';
 /**
@@ -126,16 +126,132 @@ export function resolveSchemaForChange(changeDir, explicitSchema, projectRootOve
         return metadata.schema;
     }
     // 3. Try reading from project config when metadata is absent.
-    try {
-        const config = readProjectConfig(projectRoot);
-        if (config?.schema) {
-            return config.schema;
+    if (options.projectConfig !== undefined) {
+        if (options.projectConfig?.schema) {
+            return options.projectConfig.schema;
         }
     }
-    catch {
-        // If config read fails, fall back to default
+    else {
+        try {
+            const config = readProjectConfig(projectRoot);
+            if (config?.schema) {
+                return config.schema;
+            }
+        }
+        catch {
+            // If config read fails, fall back to default
+        }
     }
     // 4. Default
     return 'spec-driven';
 }
+/**
+ * Non-throwing read of the skip_specs marker. The marker only counts when the
+ * metadata would load for status/instructions: the file parses under
+ * ChangeMetadataSchema, its schema name passes readChangeMetadata's
+ * listSchemas membership check, AND the schema itself loads via resolveSchema
+ * (a schema.yaml that exists but does not parse fails status just the same).
+ * Validate and archive must never honor metadata the rest of the CLI rejects,
+ * in either direction. The project root for schema resolution is derived from
+ * changeDir exactly like resolveSchemaForChange (changeDir is
+ * <root>/openspec/changes/<name> for every root type, including store roots).
+ * Missing metadata means "not declared"; a marker that cannot be honored
+ * 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');
+    }
+    catch (err) {
+        if (err?.code === 'ENOENT') {
+            return { declared: false };
+        }
+        // The file exists but cannot be read (EACCES, EISDIR, ...). Status and
+        // instructions reject the change outright here, and whether a marker is
+        // set cannot be determined - fail closed rather than let archive treat
+        // the change as unmarked while every metadata-reading surface errors.
+        const message = err instanceof Error ? err.message : String(err);
+        return {
+            declared: false,
+            invalidReason: `the metadata file cannot be read (${message})`,
+        };
+    }
+    let parsed;
+    try {
+        parsed = yaml.parse(raw);
+    }
+    catch {
+        // Anchored so a comment like "# maybe add skip_specs later" does not
+        // claim the marker was set.
+        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[key] !== true) {
+            return { declared: false };
+        }
+        // Schema loading is checked only when the marker is set: a broken schema
+        // on an ordinary change is status's problem to report, but honoring a
+        // marker that status rejects would let validate/archive pass what the
+        // rest of the CLI refuses to load. The membership check mirrors
+        // readChangeMetadata (which rejects names like 'spec-driven.yaml' that
+        // resolveSchema alone would normalize and accept); resolveSchema then
+        // proves the schema actually parses. Any failure fails closed.
+        try {
+            const projectRoot = path.resolve(changeDir, '../../..');
+            if (!listSchemas(projectRoot).includes(result.data.schema)) {
+                return {
+                    declared: false,
+                    invalidReason: `schema: unknown schema '${result.data.schema}'`,
+                };
+            }
+            resolveSchema(result.data.schema, projectRoot);
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            return { declared: false, invalidReason: message };
+        }
+        return { declared: true };
+    }
+    // Key presence, not value: skip_specs: "yes" must surface as unhonorable,
+    // not vanish while the zero-delta guidance tells the user to set the very
+    // marker they set. An explicit skip_specs: false is the opposite of setting
+    // the marker, so it must not drag unrelated metadata problems into
+    // validate - the change simply is not marked.
+    const markerMentioned = typeof parsed === 'object' &&
+        parsed !== null &&
+        key in parsed &&
+        parsed[key] !== false;
+    if (markerMentioned) {
+        const first = result.error.issues[0];
+        const where = first.path.length > 0 ? `${first.path.join('.')}: ` : '';
+        return { declared: false, invalidReason: `${where}${first.message}` };
+    }
+    return { declared: false };
+}
 //# sourceMappingURL=change-metadata.js.map

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

@@ -31,17 +31,23 @@ export interface ValidationResult {
 /**
  * Validates that a change name follows kebab-case conventions.
  *
- * Valid names:
- * - Start with a lowercase letter
+ * Uses OpenSpec's shared kebab-id grammar (the same one store ids and change
+ * metadata ids use), so a change name may:
+ * - Start with a lowercase letter or a digit
  * - Contain only lowercase letters, numbers, and hyphens
- * - Do not start or end with a hyphen
- * - Do not contain consecutive hyphens
+ * - Not start or end with a hyphen
+ * - Not contain consecutive hyphens
+ *
+ * A leading digit is allowed so ordering conventions like `100-add-feature` or
+ * `00001-add-auth` work; archive already treats such prefixes as a supported
+ * convention (see ARCHIVE_DATE_PREFIX_PATTERN).
  *
  * @param name - The change name to validate
  * @returns Validation result with `valid: true` or `valid: false` with an error message
  *
  * @example
  * validateChangeName('add-auth') // { valid: true }
+ * validateChangeName('100-add-feature') // { valid: true }
  * validateChangeName('Add-Auth') // { valid: false, error: '...' }
  */
 export declare function validateChangeName(name: string): ValidationResult;