@fission-ai/openspec 1.9.0 → 1.11.0

package/dist/core/update.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, sharedSkillRootOwner } from './shared-skill-target.js';
+import { resolveSharedSkillWriters, writeSharedSkillTarget, } 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;
         }
@@ -154,7 +154,11 @@ export class UpdateCommand {
         const deliveryIncludesCommands = delivery !== 'skills';
         // 10. Update tools (all if force, otherwise only those needing update)
         const toolsToUpdate = this.force ? configuredTools : [...toolsToUpdateSet];
+        const sharedSkillWriters = resolveSharedSkillWriters(resolvedProjectPath, configuredAndNewTools
+            .map((toolId) => AI_TOOLS.find((tool) => tool.value === toolId))
+            .filter((tool) => tool !== undefined));
         const updatedTools = [];
+        const updatedToolIds = [];
         const failedTools = [];
         const skillsInvocableCommandSkips = [];
         const zeroArtifactTools = [];
@@ -172,11 +176,12 @@ export class UpdateCommand {
                 const skillsRoot = hasGlobalSkillTarget(tool) ? skillsDir : resolvedProjectPath;
                 const shouldGenerateSkills = shouldGenerateSkillsForTool(tool.value, delivery);
                 const shouldGenerateCommands = shouldGenerateCommandsForTool(tool.value, delivery);
+                const writesSkills = !tool.skillsDir || sharedSkillWriters.has(tool.value);
                 const toolWorkflows = legacyWorkflowOverrides[tool.value] ?? desiredWorkflows;
                 const skillTemplates = getSkillTemplates(toolWorkflows);
                 const commandContents = getCommandContents(toolWorkflows);
                 // Generate skill files if delivery includes skills
-                if (shouldGenerateSkills) {
+                if (shouldGenerateSkills && writesSkills) {
                     for (const { template, dirName } of skillTemplates) {
                         const skillDir = path.join(skillsDir, dirName);
                         const skillFile = path.join(skillDir, 'SKILL.md');
@@ -189,7 +194,9 @@ export class UpdateCommand {
                     removedDeselectedSkillCount += await this.removeUnselectedSkillDirs(skillsRoot, skillsDir, toolWorkflows);
                 }
                 // Delete skill directories if delivery is commands-only
-                if (shouldRemoveSkillsForTool(tool.value, delivery) && !hasGlobalSkillTarget(tool)) {
+                if (shouldRemoveSkillsForTool(tool.value, delivery) &&
+                    writesSkills &&
+                    !hasGlobalSkillTarget(tool)) {
                     removedSkillCount += await this.removeSkillDirs(skillsRoot, skillsDir);
                     // Persist the selected owner even when commands-only delivery leaves
                     // this target with no generated skills.
@@ -223,6 +230,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 +318,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 +326,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(', ')}`);
         }
@@ -787,11 +804,15 @@ 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 = {};
+        const arbitrationTools = [...new Set([...configuredTools, ...selectedTools])]
+            .map((toolId) => AI_TOOLS.find((tool) => tool.value === toolId))
+            .filter((tool) => tool !== undefined);
+        const sharedSkillWriters = resolveSharedSkillWriters(projectPath, arbitrationTools);
         for (const toolId of selectedTools) {
             const tool = AI_TOOLS.find((t) => t.value === toolId);
             if (!tool || !toolSupportsSkills(tool))
@@ -802,6 +823,7 @@ export class UpdateCommand {
                 const skillsRoot = hasGlobalSkillTarget(tool) ? skillsDir : projectPath;
                 const shouldGenerateSkills = shouldGenerateSkillsForTool(tool.value, delivery);
                 const shouldGenerateCommands = shouldGenerateCommandsForTool(tool.value, delivery);
+                const writesSkills = !tool.skillsDir || sharedSkillWriters.has(tool.value);
                 const toolWorkflows = (tool.value === 'codex' && inferredCodexWorkflows.length > 0
                     ? inferredCodexWorkflows
                     : desiredWorkflows);
@@ -810,32 +832,23 @@ 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)
+                // Never overwrite a shared skills root owned by another tool. A tool
+                // with its own command surface can still install those commands: this
+                // is how a legacy Antigravity install gains `.agents/workflows` beside
+                // Codex-owned `.agents/skills`. A skills-only tool has no safe artifact
+                // to install, so preserve its legacy files and re-offer it later.
+                const sharedOwner = shouldGenerateSkills && !writesSkills
+                    ? arbitrationTools.find((candidate) => candidate.skillsDir === tool.skillsDir &&
+                        sharedSkillWriters.has(candidate.value))?.value
                     : undefined;
-                if (sharedOwner) {
+                if (sharedOwner && !shouldGenerateCommands) {
                     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) {
+                if (shouldGenerateSkills && writesSkills) {
                     for (const { template, dirName } of skillTemplates) {
                         const skillDir = path.join(skillsDir, dirName);
                         const skillFile = path.join(skillDir, 'SKILL.md');

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

@@ -6,6 +6,8 @@ export declare const MIN_PURPOSE_LENGTH = 50;
 export declare const MAX_WHY_SECTION_LENGTH = 1000;
 export declare const MAX_REQUIREMENT_TEXT_LENGTH = 500;
 export declare const MAX_DELTAS_PER_CHANGE = 10;
+export declare const PURPOSE_PLACEHOLDER_PREFIX = "TBD - created by archiving change ";
+export declare const PURPOSE_PLACEHOLDER_SUFFIX = ". Update Purpose after archive.";
 export declare const VALIDATION_MESSAGES: {
     readonly SCENARIO_EMPTY: "Scenario text cannot be empty";
     readonly REQUIREMENT_EMPTY: "Requirement text cannot be empty";
@@ -26,6 +28,7 @@ export declare const VALIDATION_MESSAGES: {
     readonly DELTA_SPEC_EMPTY: "Spec name cannot be empty";
     readonly DELTA_DESCRIPTION_EMPTY: "Delta description cannot be empty";
     readonly PURPOSE_TOO_BRIEF: "Purpose section is too brief (less than 50 characters)";
+    readonly PURPOSE_IS_PLACEHOLDER: string;
     readonly REQUIREMENT_TOO_LONG: "Requirement text is very long (>500 characters). Consider breaking it down.";
     readonly DELTA_DESCRIPTION_TOO_BRIEF: "Delta description is too brief";
     readonly DELTA_MISSING_REQUIREMENTS: "Delta should include requirements";

package/dist/core/validation/constants.js

@@ -8,6 +8,14 @@ export const MIN_PURPOSE_LENGTH = 50;
 export const MAX_WHY_SECTION_LENGTH = 1000;
 export const MAX_REQUIREMENT_TEXT_LENGTH = 500;
 export const MAX_DELTAS_PER_CHANGE = 10;
+// The Purpose `openspec archive` writes into a main spec it creates when the
+// delta introduced the capability without a usable `## Purpose`. Named here, and
+// composed from these two halves at the write site, so validation recognises the
+// placeholder through the same definition that produces it: a second, hand-copied
+// spelling would stop matching the day the wording changed, and a check that
+// matches nothing looks exactly like a check that found nothing.
+export const PURPOSE_PLACEHOLDER_PREFIX = 'TBD - created by archiving change ';
+export const PURPOSE_PLACEHOLDER_SUFFIX = '. Update Purpose after archive.';
 // Validation messages
 export const VALIDATION_MESSAGES = {
     // Required content
@@ -31,6 +39,10 @@ export const VALIDATION_MESSAGES = {
     DELTA_DESCRIPTION_EMPTY: 'Delta description cannot be empty',
     // Warnings
     PURPOSE_TOO_BRIEF: `Purpose section is too brief (less than ${MIN_PURPOSE_LENGTH} characters)`,
+    PURPOSE_IS_PLACEHOLDER: 'Purpose section is still a placeholder rather than a Purpose anyone wrote (the sentence `openspec archive` ' +
+        'writes for a new capability, or a `TBD`/`TODO` marker left in its place). Replace it with what this ' +
+        'capability is for, editing the main spec directly: a `## Purpose` in a delta is read only when the ' +
+        'capability is created, so it cannot replace this one.',
     REQUIREMENT_TOO_LONG: `Requirement text is very long (>${MAX_REQUIREMENT_TEXT_LENGTH} characters). Consider breaking it down.`,
     DELTA_DESCRIPTION_TOO_BRIEF: 'Delta description is too brief',
     DELTA_MISSING_REQUIREMENTS: 'Delta should include requirements',

package/dist/core/validation/purpose-placeholder.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Detects a `## Purpose` that is still a placeholder, rather than one somebody
+ * wrote.
+ *
+ * When a delta introduces a capability with no usable `## Purpose`, archive
+ * stamps the placeholder into the new main spec. That text is over
+ * `MIN_PURPOSE_LENGTH`, so the brevity check cannot reach it: the one rule that
+ * exists to catch a Purpose nobody wrote is satisfied by the exact string
+ * meaning nobody wrote one. Nothing else reads it afterwards, so the capability
+ * keeps a to-do in it while every command reports success.
+ *
+ * Two things count, and deliberately nothing else:
+ *
+ * - the placeholder this tool generates, recognised through the same constants
+ *   the writer composes it from, wherever it sits in the Purpose - nobody types
+ *   that sentence by accident;
+ * - a `TBD` or `TODO` **opening** the Purpose, which is the marker left behind
+ *   when someone is told to leave "a brief TBD placeholder" and never comes
+ *   back. Which of the two words got typed says nothing about whether the
+ *   Purpose was written, so both are read the same way.
+ *
+ * A marker inside a sentence is left alone. "The retry budget is TBD pending
+ * benchmarks" is a real Purpose with an open question in it, and reporting it
+ * would teach people to ignore the warning - which costs more than the findings
+ * it would add.
+ *
+ * Fenced code inside the Purpose is quoted material rather than the Purpose
+ * speaking, so it is read out first. Without that, a Purpose documenting the
+ * sentence archive writes is reported as being that sentence: a document about
+ * the placeholder, failing for carrying one.
+ */
+export interface PurposePlaceholderIssue {
+    /** 1-based line of the placeholder text, when it can be located. */
+    line?: number;
+}
+/**
+ * Reports the Purpose of a main spec as an unwritten placeholder, or null when
+ * it reads as authored content.
+ *
+ * An empty Purpose is not reported here - `SPEC_PURPOSE_EMPTY` already covers
+ * it, and reporting both would put two findings on one line. That falls out of
+ * the two rules rather than needing a case of its own.
+ */
+export declare function findPurposePlaceholderIssue(overview: string, content?: string): PurposePlaceholderIssue | null;
+//# sourceMappingURL=purpose-placeholder.d.ts.map

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

@@ -0,0 +1,117 @@
+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.
+ */
+const LEADING_MARKER = /^(?:TBD|TODO)(?![\p{L}\p{N}\p{M}_])/iu;
+const PURPOSE_HEADER = /^ {0,3}##(?!#)[ \t]+Purpose[ \t]*$/i;
+const TOP_LEVEL_HEADER = /^ {0,3}#{1,2}(?!#)[ \t]+/;
+/**
+ * The lines of `text` that sit outside a fenced code block, with line endings
+ * normalised first.
+ *
+ * `buildCodeFenceMask` is the masker the requirement and structure parsers
+ * already share, and its own reason for existing is that a second, private
+ * notion of what a fence is drifts from the first. This check reads Markdown
+ * for the same purpose they do, so it reads fences the same way they do.
+ */
+function unfencedLines(text) {
+    const lines = text.replace(/\r\n?/g, '\n').split('\n');
+    const fenced = buildCodeFenceMask(lines);
+    return lines.filter((_, index) => !fenced[index]);
+}
+/**
+ * True when the text carries the sentence archive writes. Matched as its two
+ * fixed halves in order, because the change name between them varies - so the
+ * check follows the writer's own definition instead of a second copy of it.
+ */
+function generatedPlaceholderPrefixIndex(text) {
+    let suffixAt = text.indexOf(PURPOSE_PLACEHOLDER_SUFFIX);
+    while (suffixAt !== -1) {
+        // Use the closest prefix before this suffix. An authored explanation can
+        // mention the prefix above the real placeholder; choosing the first prefix
+        // would then point the diagnostic at the explanation instead of the text
+        // the user needs to replace.
+        const prefixAt = text.lastIndexOf(PURPOSE_PLACEHOLDER_PREFIX, suffixAt);
+        if (prefixAt !== -1)
+            return prefixAt;
+        suffixAt = text.indexOf(PURPOSE_PLACEHOLDER_SUFFIX, suffixAt + 1);
+    }
+    return undefined;
+}
+/**
+ * Reports the Purpose of a main spec as an unwritten placeholder, or null when
+ * it reads as authored content.
+ *
+ * An empty Purpose is not reported here - `SPEC_PURPOSE_EMPTY` already covers
+ * it, and reporting both would put two findings on one line. That falls out of
+ * the two rules rather than needing a case of its own.
+ */
+export function findPurposePlaceholderIssue(overview, content) {
+    // An empty Purpose needs no branch of its own: neither rule matches empty
+    // text, so it falls through to null on the line below. An early return for it
+    // would be a guard no test could hold, which is worse than none. A Purpose
+    // 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);
+    if (!leading && generatedPlaceholderPrefixIndex(prose) === undefined)
+        return null;
+    // Which rule matched decides where the placeholder is, so the locator is told.
+    // When both match the leading marker wins: it sits at or above the generated
+    // sentence, and the earliest marker is the one a reader scanning down meets.
+    return { line: content === undefined ? undefined : findPlaceholderLine(content, leading) };
+}
+/**
+ * The line inside the `## Purpose` section carrying the placeholder, so the
+ * warning points at the text to replace rather than at the file.
+ *
+ * Which line that is depends on the rule that matched. A leading marker is the
+ * section's first non-blank line by definition. The generated sentence is not:
+ * it can follow prose somebody wrote, and naming the first non-blank line then
+ * points at that prose - a line the reader can see is fine, which reads as the
+ * check being wrong rather than the Purpose being unwritten.
+ *
+ * Fenced lines are skipped on the way, for the reason detection skips them, and
+ * so a `## Requirements` quoted inside a fence cannot end the section early.
+ *
+ * Undefined when the placeholder cannot be located - no section header, or a
+ * generated sentence no single line carries. The caller then reports the finding
+ * without a line rather than with a guessed one, since a wrong line number is
+ * worse than none.
+ *
+ * Line endings are normalised first, so the same spec reports the same line
+ * whether it was saved on Windows or on macOS/Linux.
+ */
+function findPlaceholderLine(content, leading) {
+    const lines = content.replace(/\r\n?/g, '\n').split('\n');
+    const fenced = buildCodeFenceMask(lines);
+    const headerIndex = lines.findIndex((line, index) => !fenced[index] && PURPOSE_HEADER.test(line));
+    if (headerIndex === -1)
+        return undefined;
+    const purposeLines = [];
+    for (let i = headerIndex + 1; i < lines.length; i++) {
+        if (fenced[i])
+            continue;
+        if (TOP_LEVEL_HEADER.test(lines[i]))
+            break;
+        if (leading && lines[i].trim())
+            return i + 1;
+        purposeLines.push({ line: i + 1, text: lines[i] });
+    }
+    if (leading)
+        return undefined;
+    const purpose = purposeLines.map(({ text }) => text).join('\n');
+    const prefixAt = generatedPlaceholderPrefixIndex(purpose);
+    if (prefixAt === undefined)
+        return undefined;
+    const lineOffset = purpose.slice(0, prefixAt).split('\n').length - 1;
+    return purposeLines[lineOffset]?.line;
+}
+//# sourceMappingURL=purpose-placeholder.js.map

package/dist/core/validation/validator.js

@@ -12,6 +12,7 @@ import { discoverSpecFiles, hasAnyFileUnder } from '../../utils/spec-discovery.j
 import { METADATA_FILENAME, readSkipSpecsMarker, resolveSchemaForChange, } from '../../utils/change-metadata.js';
 import { resolveTaskFilesForChange } from '../../utils/task-progress.js';
 import { findTaskNumberingIssues } from './task-numbering.js';
+import { findPurposePlaceholderIssue } from './purpose-placeholder.js';
 import { getPackageSchemasDir, getSchemaDir } from '../artifact-graph/index.js';
 export class Validator {
     strictMode;
@@ -557,7 +558,21 @@ export class Validator {
                 message: structuralIssue.message,
             });
         }
-        if (spec.overview.length < MIN_PURPOSE_LENGTH) {
+        // The placeholder is longer than MIN_PURPOSE_LENGTH, so the brevity check
+        // below cannot reach it; it is reported on its own terms instead. Checked
+        // first because a hand-written "TBD" is both a placeholder and too brief,
+        // and only one of those two tells the author what to do. (A "TODO" opening
+        // the Purpose reads the same way, so it is the same finding.)
+        const placeholder = findPurposePlaceholderIssue(spec.overview, content);
+        if (placeholder) {
+            issues.push({
+                level: 'WARNING',
+                path: 'overview',
+                line: placeholder.line,
+                message: VALIDATION_MESSAGES.PURPOSE_IS_PLACEHOLDER,
+            });
+        }
+        else if (spec.overview.length < MIN_PURPOSE_LENGTH) {
             issues.push({
                 level: 'WARNING',
                 path: 'overview',

package/dist/telemetry/index.js

@@ -174,8 +174,9 @@ export async function maybeShowTelemetryNotice(options = {}) {
         if (options.silent) {
             return;
         }
-        // Display notice
-        console.log('Note: OpenSpec collects anonymous usage stats. Opt out: OPENSPEC_TELEMETRY=0 or openspec config set telemetry.enabled false');
+        // 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/requirement-diff.d.ts

@@ -0,0 +1,42 @@
+/** A main-spec requirement block, and how its header matched the delta's. */
+export interface MatchedRequirementBlock {
+    raw: string;
+    /** The header name as the main spec spells it. */
+    name: string;
+    /**
+     * False when the two headers differ only in case or interior spacing. Archive
+     * matches names exactly, so an inexact match is a real problem to report even
+     * though the diff below it is still the one the author meant.
+     */
+    exact: boolean;
+}
+/**
+ * Find the raw markdown block for a requirement by name in a spec file.
+ *
+ * Delegates to extractRequirementsSection() which already handles code fences,
+ * section boundaries, and requirement header parsing. We just look up by name:
+ * exactly first, then falling back to the shared case/whitespace fold so a
+ * header that differs only in spelling still shows its diff, flagged inexact.
+ *
+ * Returns null if no requirement header matches either way.
+ */
+export declare function extractRequirementBlock(specContent: string, requirementName: string): MatchedRequirementBlock | null;
+/**
+ * Compute a unified diff between a main-spec requirement block and the delta
+ * block that replaces it. A null main block (new capability) diffs against the
+ * empty string, so every line reads as an addition.
+ *
+ * Uses structuredPatch to retain unified-diff hunk ranges while omitting the
+ * synthetic file headers, since the caller provides its own labeling.
+ */
+export declare function diffRequirementBlock(baseBlock: string | null, deltaBlock: string, label: string): string;
+/**
+ * Build a map from folded RENAMED TO name to the original main-spec name.
+ * Renames apply in source order, so a chain such as A -> B -> C maps C back to
+ * A. That is the block a later MODIFIED C replaces.
+ */
+export declare function buildRenameMap(renames: Array<{
+    from: string;
+    to: string;
+}>): Map<string, string>;
+//# sourceMappingURL=requirement-diff.d.ts.map

package/dist/utils/requirement-diff.js

@@ -0,0 +1,61 @@
+import { formatPatch, OMIT_HEADERS, structuredPatch } from 'diff';
+import { extractRequirementsSection, foldRequirementName, normalizeRequirementName, } from '../core/parsers/requirement-blocks.js';
+/**
+ * Find the raw markdown block for a requirement by name in a spec file.
+ *
+ * Delegates to extractRequirementsSection() which already handles code fences,
+ * section boundaries, and requirement header parsing. We just look up by name:
+ * exactly first, then falling back to the shared case/whitespace fold so a
+ * header that differs only in spelling still shows its diff, flagged inexact.
+ *
+ * Returns null if no requirement header matches either way.
+ */
+export function extractRequirementBlock(specContent, requirementName) {
+    const parts = extractRequirementsSection(specContent);
+    const targetName = normalizeRequirementName(requirementName);
+    const foldedTarget = foldRequirementName(targetName);
+    let folded = null;
+    for (const block of parts.bodyBlocks) {
+        const name = normalizeRequirementName(block.name);
+        if (name === targetName) {
+            return { raw: block.raw, name, exact: true };
+        }
+        if (!folded && foldRequirementName(name) === foldedTarget) {
+            folded = { raw: block.raw, name, exact: false };
+        }
+    }
+    return folded;
+}
+/**
+ * Compute a unified diff between a main-spec requirement block and the delta
+ * block that replaces it. A null main block (new capability) diffs against the
+ * empty string, so every line reads as an addition.
+ *
+ * Uses structuredPatch to retain unified-diff hunk ranges while omitting the
+ * synthetic file headers, since the caller provides its own labeling.
+ */
+export function diffRequirementBlock(baseBlock, deltaBlock, label) {
+    const base = ensureTrailingNewline(baseBlock ?? '');
+    const delta = ensureTrailingNewline(deltaBlock);
+    const patch = structuredPatch(label, label, base, delta);
+    return formatPatch(patch, OMIT_HEADERS).trimEnd();
+}
+function ensureTrailingNewline(s) {
+    return s.endsWith('\n') ? s : s + '\n';
+}
+/**
+ * Build a map from folded RENAMED TO name to the original main-spec name.
+ * Renames apply in source order, so a chain such as A -> B -> C maps C back to
+ * A. That is the block a later MODIFIED C replaces.
+ */
+export function buildRenameMap(renames) {
+    const map = new Map();
+    for (const r of renames) {
+        const from = foldRequirementName(r.from);
+        const original = map.get(from) ?? normalizeRequirementName(r.from);
+        map.delete(from);
+        map.set(foldRequirementName(r.to), original);
+    }
+    return map;
+}
+//# sourceMappingURL=requirement-diff.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fission-ai/openspec",
-  "version": "1.9.0",
+  "version": "1.11.0",
   "description": "AI-native system for spec-driven development",
   "keywords": [
     "openspec",
@@ -33,7 +33,6 @@
     "dist",
     "bin",
     "schemas",
-    "scripts/postinstall.js",
     "!dist/**/*.test.js",
     "!dist/**/__tests__",
     "!dist/**/*.map"
@@ -53,10 +52,11 @@
     "vitest": "^3.2.6"
   },
   "dependencies": {
-    "@inquirer/core": "^10.3.2",
-    "@inquirer/prompts": "^7.10.1",
+    "@inquirer/core": "^11.2.1",
+    "@inquirer/prompts": "^8.5.2",
     "chalk": "^5.6.2",
     "commander": "^14.0.0",
+    "diff": "^9.0.0",
     "cross-spawn": "7.0.6",
     "fast-glob": "^3.3.3",
     "ora": "^9.4.1",
@@ -74,8 +74,6 @@
     "test:watch": "vitest",
     "test:ui": "vitest --ui",
     "test:coverage": "vitest --coverage",
-    "test:postinstall": "node scripts/postinstall.js",
-    "postinstall": "node scripts/postinstall.js",
     "check:pack-version": "node scripts/pack-version-check.mjs",
     "release": "pnpm run release:ci",
     "release:ci": "pnpm run check:pack-version && pnpm exec changeset publish",