@fission-ai/openspec 1.8.0 → 1.10.0

package/dist/core/templates/workflows/update-change.js

@@ -9,7 +9,7 @@ ${STORE_SELECTION_GUIDANCE}
 
 **Input**: Optionally specify a change name. If omitted, check if it can be inferred from conversation context. If vague or ambiguous you MUST prompt for available changes.
 
-\`/opsx:continue\` is an expanded-profile workflow and may not be installed. Before suggesting it anywhere below, verify that it is available. If it is unavailable, \`openspec status --change "<name>" --json\` shows the next artifact and \`openspec instructions "<artifact-id>" --change "<name>" --json\` explains how to create it.
+\`/opsx:continue\` is an optional workflow and may not be installed. Before suggesting it anywhere below, verify that it is available. If it is unavailable, \`openspec status --change "<name>" --json\` shows the next artifact and \`openspec instructions "<artifact-id>" --change "<name>" --json\` explains how to create it.
 
 **Steps**
 
@@ -81,7 +81,7 @@ After each invocation, show:
 - Edit only the concrete files in \`existingOutputPaths\`; never write to a glob \`resolvedOutputPath\`.
 - Do not advance the build frontier: no new artifacts, no new files under glob artifacts - that is \`/opsx:continue\`'s job.
 - Confirm every edit with the user before writing.
-- If the request changes the change's *intent* rather than refining it, first verify whether the expanded-profile \`/opsx:new\` workflow is available. If it is, recommend starting fresh with \`/opsx:new\` (the "Update vs. Start Fresh" heuristic). If it is unavailable, ask for a distinct unused change name and recommend \`openspec new change "<new-change-name>"\` instead.`,
+- If the request changes the change's *intent* rather than refining it, first verify whether the optional \`/opsx:new\` workflow is available. If it is, recommend starting fresh with \`/opsx:new\` (the "Update vs. Start Fresh" heuristic). If it is unavailable, ask for a distinct unused change name and recommend \`openspec new change "<new-change-name>"\` instead.`,
         license: 'MIT',
         compatibility: 'Requires openspec CLI.',
         metadata: { author: 'openspec', version: '1.0' },
@@ -99,7 +99,7 @@ ${STORE_SELECTION_GUIDANCE}
 
 **Input**: Optionally specify a change name after \`/opsx:update\` (e.g., \`/opsx:update add-auth\`). If omitted, check if it can be inferred from conversation context. If vague or ambiguous you MUST prompt for available changes.
 
-\`/opsx:continue\` is an expanded-profile workflow and may not be installed. Before suggesting it anywhere below, verify that it is available. If it is unavailable, \`openspec status --change "<name>" --json\` shows the next artifact and \`openspec instructions "<artifact-id>" --change "<name>" --json\` explains how to create it.
+\`/opsx:continue\` is an optional workflow and may not be installed. Before suggesting it anywhere below, verify that it is available. If it is unavailable, \`openspec status --change "<name>" --json\` shows the next artifact and \`openspec instructions "<artifact-id>" --change "<name>" --json\` explains how to create it.
 
 **Steps**
 
@@ -171,7 +171,7 @@ After each invocation, show:
 - Edit only the concrete files in \`existingOutputPaths\`; never write to a glob \`resolvedOutputPath\`.
 - Do not advance the build frontier: no new artifacts, no new files under glob artifacts - that is \`/opsx:continue\`'s job.
 - Confirm every edit with the user before writing.
-- If the request changes the change's *intent* rather than refining it, first verify whether the expanded-profile \`/opsx:new\` workflow is available. If it is, recommend starting fresh with \`/opsx:new\` (the "Update vs. Start Fresh" heuristic). If it is unavailable, ask for a distinct unused change name and recommend \`openspec new change "<new-change-name>"\` instead.`
+- If the request changes the change's *intent* rather than refining it, first verify whether the optional \`/opsx:new\` workflow is available. If it is, recommend starting fresh with \`/opsx:new\` (the "Update vs. Start Fresh" heuristic). If it is unavailable, ask for a distinct unused change name and recommend \`openspec new change "<new-change-name>"\` instead.`
     };
 }
 //# sourceMappingURL=update-change.js.map

package/dist/core/update.js

@@ -14,7 +14,7 @@ import { getSkillReferenceTransformer, getTransformerForTool, transformToSkillRe
 import { AI_TOOLS, OPENSPEC_DIR_NAME } from './config.js';
 import { generateCommands, CommandAdapterRegistry, } from './command-generation/index.js';
 import { getToolVersionStatus, getSkillTemplates, getCommandContents, generateSkillContent, getToolsWithSkillsDir, hasGlobalSkillTarget, resolveToolSkillsDir, toolSupportsSkills, } from './shared/index.js';
-import { detectLegacyArtifacts, cleanupLegacyArtifacts, formatDeferredGlobalPromptSummary, formatCleanupSummary, formatDetectionSummary, getLegacyGlobalPromptMatches, getLegacyWorkflowIdsForTool, getToolsFromLegacyArtifacts, omitGlobalLegacyPromptFiles, pickGlobalLegacyPromptFiles, } from './legacy-cleanup.js';
+import { detectLegacyArtifacts, cleanupLegacyArtifacts, formatDeferredGlobalPromptSummary, formatCleanupSummary, formatDetectionSummary, getLegacyGlobalPromptMatches, getLegacyWorkflowIdsForTool, getToolsFromLegacyArtifacts, omitGlobalLegacyPromptFiles, omitToolLegacyArtifacts, pickGlobalLegacyPromptFiles, } from './legacy-cleanup.js';
 import { isInteractive } from '../utils/interactive.js';
 import { getGlobalConfig } from './global-config.js';
 import { getProfileWorkflows, ALL_WORKFLOWS, CORE_WORKFLOWS } from './profiles.js';
@@ -23,7 +23,7 @@ import { getAvailableTools } from './available-tools.js';
 import { WORKFLOW_TO_SKILL_DIR, getConfiguredToolsForProfileSync, getToolsNeedingProfileSync, } from './profile-sync-drift.js';
 import { scanInstalledWorkflows as scanInstalledWorkflowsShared, migrateIfNeeded as migrateIfNeededShared, findLegacyToolMigrations, migrateLegacyToolDirs, describeLegacyMigration, legacyMigrationNotice, keptInPlaceNotice, hasMovableContent, } from './migration.js';
 import { resolveCommandSurfaceCapability, resolveCommandInvocation, shouldGenerateCommandsForTool, shouldGenerateSkillsForTool, shouldReconcileCommandFilesForTool, shouldRemoveSkillsForTool, } from './command-surface.js';
-import { writeSharedSkillTarget } from './shared-skill-target.js';
+import { writeSharedSkillTarget, sharedSkillRootOwner } from './shared-skill-target.js';
 import { includesGitHubCopilot, writeCopilotCloudFiles, removeCopilotCloudFiles, isCopilotCloudEnabled, readCopilotCloudOptIn, findUnmanagedCloudFiles } from './github-copilot/cloud-agent.js';
 const require = createRequire(import.meta.url);
 const { version: OPENSPEC_VERSION } = require('../../package.json');
@@ -135,7 +135,7 @@ export class UpdateCommand {
             // Still check for new tool directories and extra workflows
             this.detectNewTools(resolvedProjectPath, configuredTools);
             this.displayExtraWorkflowsNote(resolvedProjectPath, configuredTools, desiredWorkflows);
-            this.displayMissingCoreWorkflowsNote(profile, globalConfig.workflows);
+            this.displayMissingCoreWorkflowsNote(profile, desiredWorkflows);
             this.displaySetupNotes(configuredTools);
             return;
         }
@@ -155,6 +155,7 @@ export class UpdateCommand {
         // 10. Update tools (all if force, otherwise only those needing update)
         const toolsToUpdate = this.force ? configuredTools : [...toolsToUpdateSet];
         const updatedTools = [];
+        const updatedToolIds = [];
         const failedTools = [];
         const skillsInvocableCommandSkips = [];
         const zeroArtifactTools = [];
@@ -223,6 +224,7 @@ export class UpdateCommand {
                 }
                 spinner.succeed(`Updated ${tool.name}`);
                 updatedTools.push(tool.name);
+                updatedToolIds.push(tool.value);
                 for (const migration of migrateLegacyToolDirs(resolvedProjectPath, [tool.value], 'after-generation')) {
                     if (hasMovableContent(migration)) {
                         console.log(chalk.dim(`Migrated ${describeLegacyMigration(migration)}: ${migration.from} → ${migration.to}`));
@@ -310,7 +312,7 @@ export class UpdateCommand {
         this.detectNewTools(resolvedProjectPath, configuredAndNewTools);
         // 14. Display note about extra workflows not in profile
         this.displayExtraWorkflowsNote(resolvedProjectPath, configuredAndNewTools, desiredWorkflows);
-        this.displayMissingCoreWorkflowsNote(profile, globalConfig.workflows);
+        this.displayMissingCoreWorkflowsNote(profile, desiredWorkflows);
         this.displaySetupNotes(configuredAndNewTools);
         // 15. List affected tools
         if (updatedTools.length > 0) {
@@ -318,7 +320,16 @@ export class UpdateCommand {
             console.log(chalk.dim(`Tools: ${toolDisplayNames.join(', ')}`));
         }
         console.log();
-        console.log(chalk.dim('Restart your IDE for changes to take effect.'));
+        const affectedToolIds = [...new Set([...newlyConfiguredTools, ...updatedToolIds])];
+        const shouldRestartIde = affectedToolIds.some((toolId) => {
+            const tool = AI_TOOLS.find((candidate) => candidate.value === toolId);
+            return Boolean(tool?.requiresIdeRestart &&
+                (shouldGenerateCommandsForTool(toolId, delivery) ||
+                    shouldGenerateSkillsForTool(toolId, delivery)));
+        });
+        if (shouldRestartIde) {
+            console.log(chalk.dim('Restart your IDE for changes to take effect.'));
+        }
         if (failedTools.length > 0) {
             throw new Error(`OpenSpec update failed for: ${failedTools.map((tool) => tool.name).join(', ')}`);
         }
@@ -647,7 +658,7 @@ export class UpdateCommand {
         const canPrompt = isInteractive();
         if (this.force) {
             const legacyUpgrade = await this.upgradeLegacyTools(projectPath, detection, canPrompt, desiredWorkflows, delivery);
-            await this.performImmediateLegacyCleanup(projectPath, detection);
+            await this.performImmediateLegacyCleanup(projectPath, detection, legacyUpgrade.skippedSharedSkillTools);
             return {
                 ...legacyUpgrade,
                 deferredGlobalCleanup: pickGlobalLegacyPromptFiles(detection, detection.globalSlashCommandFiles),
@@ -668,7 +679,7 @@ export class UpdateCommand {
         });
         if (shouldCleanup) {
             const legacyUpgrade = await this.upgradeLegacyTools(projectPath, detection, canPrompt, desiredWorkflows, delivery);
-            await this.performImmediateLegacyCleanup(projectPath, detection);
+            await this.performImmediateLegacyCleanup(projectPath, detection, legacyUpgrade.skippedSharedSkillTools);
             return {
                 ...legacyUpgrade,
                 deferredGlobalCleanup: pickGlobalLegacyPromptFiles(detection, detection.globalSlashCommandFiles),
@@ -683,8 +694,10 @@ export class UpdateCommand {
     /**
      * Cleans approved repo-local legacy artifacts before configured tools refresh.
      */
-    async performImmediateLegacyCleanup(projectPath, detection) {
-        const immediateDetection = omitGlobalLegacyPromptFiles(detection);
+    async performImmediateLegacyCleanup(projectPath, detection, skippedSharedSkillTools = []) {
+        // Tools whose upgrade was skipped (shared root owned by another) had no
+        // replacement written, so their repo-local legacy files must be preserved.
+        const immediateDetection = omitToolLegacyArtifacts(omitGlobalLegacyPromptFiles(detection), skippedSharedSkillTools);
         if (immediateDetection.hasLegacyArtifacts) {
             await this.performLegacyCleanup(projectPath, immediateDetection);
         }
@@ -785,9 +798,10 @@ export class UpdateCommand {
                 return { newlyConfiguredTools: [], workflowOverrides: {} };
             }
         }
-        const inferredCodexWorkflows = getLegacyWorkflowIdsForTool(detection, 'codex');
+        const inferredCodexWorkflows = getProfileWorkflows('custom', getLegacyWorkflowIdsForTool(detection, 'codex')).filter((workflow) => ALL_WORKFLOWS.includes(workflow));
         // Create skills/commands for selected tools using effective profile+delivery.
         const newlyConfigured = [];
+        const skippedSharedSkillTools = [];
         const workflowOverrides = {};
         for (const toolId of selectedTools) {
             const tool = AI_TOOLS.find((t) => t.value === toolId);
@@ -807,6 +821,30 @@ export class UpdateCommand {
                 }
                 const skillTemplates = getSkillTemplates(toolWorkflows);
                 const commandContents = getCommandContents(toolWorkflows);
+                // A shared skills root (e.g. `.agents`) already owned by another tool
+                // must not be overwritten by a tool inferred from legacy artifacts: a
+                // Codex install detected only from global `~/.codex/prompts` would
+                // otherwise rewrite an existing vendor-neutral `agents` tree with
+                // Codex-specific syntax and flip its ownership marker `agents → codex`.
+                // Leave the established owner in place. (init applies the same
+                // one-writer rule up front when both targets are selected.)
+                //
+                // Skipping here means the tool is never recorded as configured, so a
+                // persistent legacy signal re-offers it on later runs. Because no
+                // replacement is written, this tool is also exempted from immediate
+                // legacy cleanup (see skippedSharedSkillTools) — otherwise a repo-local
+                // `.codex/prompts` would be deleted with nothing put in its place. That
+                // repeat is idempotent and harmless — the alternative is the silent
+                // hijack this prevents.
+                const sharedOwner = shouldGenerateSkills
+                    ? sharedSkillRootOwner(projectPath, tool.value)
+                    : undefined;
+                if (sharedOwner) {
+                    const ownerName = AI_TOOLS.find((candidate) => candidate.value === sharedOwner)?.name ?? sharedOwner;
+                    spinner.info(`Skipped ${tool.name}: ${tool.skillsDir}/skills is already managed by another tool (${ownerName}).`);
+                    skippedSharedSkillTools.push(tool.value);
+                    continue;
+                }
                 // Create skill files when delivery includes skills
                 if (shouldGenerateSkills) {
                     for (const { template, dirName } of skillTemplates) {
@@ -847,7 +885,7 @@ export class UpdateCommand {
         if (newlyConfigured.length > 0) {
             console.log();
         }
-        return { newlyConfiguredTools: newlyConfigured, workflowOverrides };
+        return { newlyConfiguredTools: newlyConfigured, workflowOverrides, skippedSharedSkillTools };
     }
 }
 //# sourceMappingURL=update.js.map

package/dist/core/validation/task-numbering.d.ts

@@ -0,0 +1,16 @@
+export interface TaskNumberingDocument {
+    path: string;
+    content: string;
+}
+export interface TaskNumberingIssue {
+    path: string;
+    line: number;
+    message: string;
+}
+/**
+ * Finds ambiguous task references across the task files tracked by a change.
+ * Numbering is interpreted only inside `## N.` groups. Unnumbered sections,
+ * unnumbered tasks, and files without numbered groups are intentionally ignored.
+ */
+export declare function findTaskNumberingIssues(documents: readonly TaskNumberingDocument[]): TaskNumberingIssue[];
+//# sourceMappingURL=task-numbering.d.ts.map

package/dist/core/validation/task-numbering.js

@@ -0,0 +1,57 @@
+import { parseTaskLines } from '../../utils/task-progress.js';
+const LEVEL_TWO_HEADING = /^ {0,3}##(?!#)(?:[ \t]+|[ \t]*\r?$)/;
+const NUMBERED_GROUP_HEADING = /^ {0,3}##[ \t]+(\d+)\.(?:[ \t]|\r?$)/;
+const TASK_ID = /^(\d+(?:\.\d+)+(?:[A-Za-z]+)?)(?=\s|$)/;
+/**
+ * Finds ambiguous task references across the task files tracked by a change.
+ * Numbering is interpreted only inside `## N.` groups. Unnumbered sections,
+ * unnumbered tasks, and files without numbered groups are intentionally ignored.
+ */
+export function findTaskNumberingIssues(documents) {
+    const issues = [];
+    const firstLocationById = new Map();
+    for (const document of documents) {
+        const lines = document.content.split('\n');
+        if (!lines.some((line) => NUMBERED_GROUP_HEADING.test(line)))
+            continue;
+        let currentGroup;
+        lines.forEach((line, index) => {
+            if (LEVEL_TWO_HEADING.test(line)) {
+                currentGroup = line.match(NUMBERED_GROUP_HEADING)?.[1];
+            }
+            if (currentGroup === undefined)
+                return;
+            const task = parseTaskLines(line)[0];
+            const id = task?.description.match(TASK_ID)?.[1];
+            if (!id)
+                return;
+            const lineNumber = index + 1;
+            const taskGroup = id.split('.')[0];
+            const normalizedTaskGroup = taskGroup.replace(/^0+(?=\d)/, '');
+            const normalizedCurrentGroup = currentGroup.replace(/^0+(?=\d)/, '');
+            if (normalizedTaskGroup !== normalizedCurrentGroup) {
+                issues.push({
+                    path: document.path,
+                    line: lineNumber,
+                    message: `Task "${id}" is under group ${currentGroup}, but its leading number points to group ${taskGroup}. Move it to group ${taskGroup} or renumber it.`,
+                });
+            }
+            const firstLocation = firstLocationById.get(id);
+            if (firstLocation !== undefined) {
+                const firstDeclaration = firstLocation.path === document.path
+                    ? `on line ${firstLocation.line}`
+                    : `in ${firstLocation.path} on line ${firstLocation.line}`;
+                issues.push({
+                    path: document.path,
+                    line: lineNumber,
+                    message: `Task ID "${id}" is duplicated; it was first declared ${firstDeclaration}.`,
+                });
+            }
+            else {
+                firstLocationById.set(id, { path: document.path, line: lineNumber });
+            }
+        });
+    }
+    return issues;
+}
+//# sourceMappingURL=task-numbering.js.map

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

@@ -20,12 +20,15 @@ export declare class Validator {
      *
      * 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.
+     * apply (#1477). When `options.projectRoot` is given, the schema's tracked
+     * task files are checked for ambiguous numbering (#1520). Omitting either
+     * option keeps existing library and archive callers behaving as before.
      */
     validateChangeDeltaSpecs(changeDir: string, options?: {
         mainSpecsDir?: string;
+        projectRoot?: string;
     }): Promise<ValidationReport>;
+    private collectTaskNumberingIssues;
     /**
      * Report MODIFIED requirements whose block omits a scenario the main spec
      * still carries. Uses the same comparison archive applies, so validate can

package/dist/core/validation/validator.js

@@ -9,7 +9,10 @@ import { extractRequirementBody as extractRequirementBodyShared, containsShallOr
 import { findMainSpecStructureIssues } from '../parsers/spec-structure.js';
 import { FileSystemUtils } from '../../utils/file-system.js';
 import { discoverSpecFiles, hasAnyFileUnder } from '../../utils/spec-discovery.js';
-import { METADATA_FILENAME, readSkipSpecsMarker } from '../../utils/change-metadata.js';
+import { METADATA_FILENAME, readSkipSpecsMarker, resolveSchemaForChange, } from '../../utils/change-metadata.js';
+import { resolveTaskFilesForChange } from '../../utils/task-progress.js';
+import { findTaskNumberingIssues } from './task-numbering.js';
+import { getPackageSchemasDir, getSchemaDir } from '../artifact-graph/index.js';
 export class Validator {
     strictMode;
     constructor(strictMode = false) {
@@ -109,8 +112,9 @@ export class Validator {
      *
      * 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.
+     * apply (#1477). When `options.projectRoot` is given, the schema's tracked
+     * task files are checked for ambiguous numbering (#1520). Omitting either
+     * option keeps existing library and archive callers behaving as before.
      */
     async validateChangeDeltaSpecs(changeDir, options = {}) {
         const issues = [];
@@ -387,8 +391,58 @@ export class Validator {
                 issues.push({ level: 'ERROR', path: 'file', message: this.enrichTopLevelError('change', VALIDATION_MESSAGES.CHANGE_NO_DELTAS) });
             }
         }
+        if (options.projectRoot) {
+            issues.push(...await this.collectTaskNumberingIssues(changeDir, options.projectRoot));
+        }
         return this.createReport(issues);
     }
+    async collectTaskNumberingIssues(changeDir, projectRoot) {
+        try {
+            const schemaName = resolveSchemaForChange(changeDir, undefined, projectRoot).replace(/\.ya?ml$/, '');
+            const schemaDir = getSchemaDir(schemaName, projectRoot);
+            const builtInSchemaDir = path.join(getPackageSchemasDir(), 'spec-driven');
+            if (schemaName !== 'spec-driven' ||
+                schemaDir === null ||
+                FileSystemUtils.canonicalizeExistingPath(schemaDir) !==
+                    FileSystemUtils.canonicalizeExistingPath(builtInSchemaDir)) {
+                return [];
+            }
+        }
+        catch {
+            return [];
+        }
+        let taskFiles;
+        try {
+            taskFiles = resolveTaskFilesForChange(changeDir, projectRoot);
+        }
+        catch {
+            return [];
+        }
+        if (taskFiles.length === 0) {
+            taskFiles = [path.join(changeDir, 'tasks.md')];
+        }
+        const documents = [];
+        for (const taskFile of taskFiles) {
+            let content;
+            try {
+                content = await fs.readFile(taskFile, 'utf-8');
+            }
+            catch {
+                continue;
+            }
+            documents.push({
+                path: FileSystemUtils.toPosixPath(path.relative(changeDir, taskFile)),
+                content,
+            });
+        }
+        documents.sort((left, right) => left.path.localeCompare(right.path));
+        return findTaskNumberingIssues(documents).map((issue) => ({
+            level: 'WARNING',
+            path: issue.path,
+            line: issue.line,
+            message: issue.message,
+        }));
+    }
     /**
      * Report MODIFIED requirements whose block omits a scenario the main spec
      * still carries. Uses the same comparison archive applies, so validate can

package/dist/telemetry/index.d.ts

@@ -27,7 +27,9 @@ export declare function trackCommand(commandName: string, version: string): Prom
 /**
  * Show first-run telemetry notice if not already seen.
  */
-export declare function maybeShowTelemetryNotice(): Promise<void>;
+export declare function maybeShowTelemetryNotice(options?: {
+    silent?: boolean;
+}): Promise<void>;
 /**
  * Flush pending telemetry events.
  * Call this before CLI exit.

package/dist/telemetry/index.js

@@ -159,7 +159,7 @@ export async function trackCommand(commandName, version) {
 /**
  * Show first-run telemetry notice if not already seen.
  */
-export async function maybeShowTelemetryNotice() {
+export async function maybeShowTelemetryNotice(options = {}) {
     if (!isTelemetryEnabled()) {
         return;
     }
@@ -168,8 +168,15 @@ export async function maybeShowTelemetryNotice() {
         if (config.noticeSeen) {
             return;
         }
-        // Display notice
-        console.log('Note: OpenSpec collects anonymous usage stats. Opt out: OPENSPEC_TELEMETRY=0 or openspec config set telemetry.enabled false');
+        // In --json mode the notice would pollute stdout and break parsers, so
+        // defer it: skip the notice AND leave noticeSeen unset so the disclosure
+        // still appears on the user's first later non-JSON run.
+        if (options.silent) {
+            return;
+        }
+        // Display notice on stderr, not stdout: stdout is reserved for command
+        // output (raw passthrough text, JSON, etc.) and must stay parser/pipe-safe.
+        console.error('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.js

@@ -179,6 +179,18 @@ export function readRetireCapabilitiesMarker(changeDir) {
  * 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.
  */
+/**
+ * A marker that cannot be honored, with its reason made safe to print.
+ *
+ * Every reason quotes something the author wrote - a schema name, a parser
+ * message carrying one, a filesystem error carrying a path - and callers print
+ * it straight to a terminal (`openspec archive`, `openspec validate`). A raw CR
+ * could forge a line of its own and an ESC could redraw the screen, so control
+ * characters never leave this function.
+ */
+function unhonorable(reason) {
+    return { declared: false, invalidReason: reason.replace(/[\u0000-\u001f\u007f]/g, '?') };
+}
 function readBooleanMarker(changeDir, key) {
     let raw;
     try {
@@ -193,10 +205,7 @@ function readBooleanMarker(changeDir, key) {
         // 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})`,
-        };
+        return unhonorable(`the metadata file cannot be read (${message})`);
     }
     let parsed;
     try {
@@ -206,9 +215,7 @@ function readBooleanMarker(changeDir, key) {
         // 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 };
+        return mentioned ? unhonorable('the file is not valid YAML') : { declared: false };
     }
     const result = ChangeMetadataSchema.safeParse(parsed);
     if (result.success) {
@@ -225,16 +232,13 @@ function readBooleanMarker(changeDir, key) {
         try {
             const projectRoot = path.resolve(changeDir, '../../..');
             if (!listSchemas(projectRoot).includes(result.data.schema)) {
-                return {
-                    declared: false,
-                    invalidReason: `schema: unknown schema '${result.data.schema}'`,
-                };
+                return unhonorable(`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 unhonorable(message);
         }
         return { declared: true };
     }
@@ -250,7 +254,7 @@ function readBooleanMarker(changeDir, key) {
     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 unhonorable(`${where}${first.message}`);
     }
     return { declared: false };
 }

package/dist/utils/change-utils.js

@@ -4,6 +4,8 @@ import { writeChangeMetadata, validateSchemaName } from './change-metadata.js';
 import { formatLocalDate } from './date.js';
 import { readProjectConfig } from '../core/project-config.js';
 import { isKebabId } from '../core/id.js';
+import { resolveSchema } from '../core/artifact-graph/resolver.js';
+import { isSpecsArtifactPath } from '../core/artifact-graph/outputs.js';
 const DEFAULT_SCHEMA = 'spec-driven';
 /**
  * Validates that a change name follows kebab-case conventions.
@@ -117,6 +119,8 @@ export async function createChange(projectRoot, name, options = {}) {
     if (await FileSystemUtils.directoryExists(changeDir)) {
         throw new Error(`Change '${name}' already exists at ${changeDir}`);
     }
+    const schema = resolveSchema(schemaName, projectRoot);
+    const skipsSpecs = !schema.artifacts.some(artifact => isSpecsArtifactPath(artifact.generates));
     // Creating a change may scaffold or complete the root itself (an
     // implicit root, or a config-only/incomplete clone). Never leave a
     // half-root behind that doctor immediately calls unhealthy: ensure
@@ -138,6 +142,7 @@ export async function createChange(projectRoot, name, options = {}) {
     writeChangeMetadata(changeDir, {
         schema: schemaName,
         created: formatLocalDate(),
+        ...(skipsSpecs ? { skip_specs: true } : {}),
         ...options.metadata,
     }, projectRoot);
     return { schema: schemaName, changeDir };

package/dist/utils/interactive.d.ts

@@ -1,3 +1,4 @@
+import type { Readable, Writable } from 'node:stream';
 export type InteractiveOptions = {
     /**
      * Explicit "disable prompts" flag passed by internal callers.
@@ -35,7 +36,35 @@ export declare function isInteractive(value?: boolean | InteractiveOptions): boo
  *   somebody was there and chose to quit.
  *
  * Beyond that it defers to `isInteractive()`, so `CI`, `OPEN_SPEC_INTERACTIVE=0`
- * and `--no-interactive` count even when a runner allocated a pty.
+ * and `--no-interactive` count even when a runner allocated a pty. It also
+ * counts a redirected stdout: `confirmPrompt` drops to the plain reader whenever
+ * *either* stream is not a TTY, so a stdin-TTY-but-stdout-redirected run
+ * (`openspec archive x > log.txt` from a terminal) that hits EOF must classify
+ * the same way the prompt was selected — otherwise it would leak the raw
+ * `ExitPromptError` instead of the `--yes` guidance.
  */
 export declare function isNonInteractivePromptError(error: unknown, value?: boolean | InteractiveOptions): boolean;
+export type ConfirmPrompt = {
+    message: string;
+    default: boolean;
+};
+/**
+ * Ask a yes/no question. A real terminal gets @inquirer's rich prompt;
+ * everything else — a pipe, a file redirect, an agent that captures stdout —
+ * reads one plain line instead.
+ *
+ * @inquirer renders `confirm` by writing ANSI cursor-movement escape sequences,
+ * and it emits them even when stdout is not a TTY. Redirected to a file those
+ * sequences are noise, and in some non-TTY hosts the render loop never settles
+ * and repeats `ESC[NNG` cursor moves until the disk fills (#1526). Reading
+ * the answer ourselves keeps the single piped answer @inquirer ever supported
+ * working (`printf 'y\n' | openspec archive ...`) without emitting any escapes.
+ *
+ * `io` overrides the streams; it exists for tests and mirrors @inquirer's own
+ * `{ input, output }` context. Production callers pass only the prompt.
+ */
+export declare function confirmPrompt(prompt: ConfirmPrompt, io?: {
+    input?: Readable;
+    output?: Writable;
+}): Promise<boolean>;
 //# sourceMappingURL=interactive.d.ts.map