@codewalla_india/openspec 1.3.1 → 1.3.2

package/dist/cli/index.js

@@ -3,10 +3,11 @@ import { Command, Option } from 'commander';
 import { createRequire } from 'module';
 import ora from 'ora';
 import path from 'path';
-import { fileURLToPath } from 'url';
+import { fileURLToPath } from 'node:url';
 import { promises as fs } from 'fs';
-import { AI_TOOLS } from '../core/config.js';
+import { AI_TOOLS, TOOL_ID_ALIASES } from '../core/config.js';
 import { UpdateCommand } from '../core/update.js';
+import { getAvailableCliUpdate, displayCliUpdateNote, shouldOfferUpgrade, getInstallDir, offerCliUpgrade, rerunUpdateWithUpgradedCli, displayUpgradeCommand, isSourceCheckout, } from '../core/version-check.js';
 import { ListCommand } from '../core/list.js';
 import { ArchiveCommand } from '../core/archive.js';
 import { ViewCommand } from '../core/view.js';
@@ -23,10 +24,12 @@ import { registerStoreCommand } from '../commands/store.js';
 import { registerDoctorCommand } from '../commands/doctor.js';
 import { registerContextCommand } from '../commands/context.js';
 import { registerWorksetCommand } from '../commands/workset.js';
-import { statusCommand, instructionsCommand, applyInstructionsCommand, modifyInstructionsCommand, templatesCommand, schemasCommand, newChangeCommand, DEFAULT_SCHEMA, } from '../commands/workflow/index.js';
-import { requireTelemetryIdentity, TelemetryIdentityRequiredError, trackCommand, shutdown } from '../telemetry/index.js';
-import { buildCommandTelemetryContext, resolveTelemetryCommandPath, } from '../telemetry/command-context.js';
+import { createModifyCommand } from '../commands/modify.js';
+import { statusCommand, instructionsCommand, applyInstructionsCommand, archiveInstructionsCommand, templatesCommand, schemasCommand, newChangeCommand, DEFAULT_SCHEMA, } from '../commands/workflow/index.js';
+import { maybeShowTelemetryNotice, trackCommand, shutdown } from '../telemetry/index.js';
+import { readIdentity } from '../telemetry/identity.js';
 import { COMMON_FLAGS } from '../core/completions/shared-flags.js';
+import { isInteractive } from '../utils/interactive.js';
 const STORE_OPTION_DESCRIPTION = COMMON_FLAGS.store.description;
 // Deliberate rejection path: --store-path stays registered (hidden) so the
 // resolver can explain that registering the path is the supported route,
@@ -71,33 +74,6 @@ export function getCommandPath(command) {
     }
     return names.join(':') || 'openspec';
 }
-function commandUsesJson(command) {
-    let current = command;
-    while (current) {
-        if (current.opts()?.json === true) {
-            return true;
-        }
-        current = current.parent;
-    }
-    return false;
-}
-function exitTelemetryIdentityRequired(error, json) {
-    if (json) {
-        console.log(JSON.stringify({
-            status: [
-                {
-                    severity: 'error',
-                    code: error.code,
-                    message: error.message,
-                },
-            ],
-        }, null, 2));
-    }
-    else {
-        console.error(`Error: ${error.message}`);
-    }
-    process.exit(1);
-}
 program
     .name('openspec')
     .description('AI-native system for spec-driven development')
@@ -113,33 +89,43 @@ program.hook('preAction', async (thisCommand, actionCommand) => {
     if (opts.color === false) {
         process.env.NO_COLOR = '1';
     }
-    const commandPath = resolveTelemetryCommandPath(getCommandPath(actionCommand), actionCommand);
-    const isBootstrap = commandPath === 'init' || commandPath === 'update';
-    if (!isBootstrap) {
-        try {
-            await requireTelemetryIdentity();
-        }
-        catch (error) {
-            if (error instanceof TelemetryIdentityRequiredError) {
-                exitTelemetryIdentityRequired(error, commandUsesJson(actionCommand));
-            }
-            throw error;
+    // Identity gating: check for identity before executing command
+    // Exempt commands: init and update
+    const commandPath = getCommandPath(actionCommand);
+    const isExemptCommand = commandPath === 'init' || commandPath === 'update';
+    if (!isExemptCommand) {
+        const identity = await readIdentity();
+        if (!identity) {
+            console.error('Error: Identity required. Configure with: openspec init');
+            process.exitCode = 1;
+            process.exit(1);
         }
     }
-    await trackCommand(commandPath, version, buildCommandTelemetryContext(actionCommand));
+    // Show first-run telemetry notice (if not seen)
+    await maybeShowTelemetryNotice();
+    // Track command execution (use actionCommand to get the actual subcommand)
+    await trackCommand(commandPath, version);
 });
 // Shutdown telemetry after command completes
 program.hook('postAction', async () => {
     await shutdown();
 });
-const availableToolIds = AI_TOOLS.filter((tool) => tool.skillsDir).map((tool) => tool.value);
-const toolsOptionDescription = `Configure AI tools non-interactively. Use "all", "none", or a comma-separated list of: ${availableToolIds.join(', ')}`;
+const availableToolIds = AI_TOOLS
+    .filter((tool) => tool.skillsDir || tool.globalSkillsDir)
+    .map((tool) => tool.value);
+const toolAliasNote = Object.entries(TOOL_ID_ALIASES)
+    .map(([retired, current]) => `${retired} (now ${current})`)
+    .join(', ');
+const toolsOptionDescription = `Configure AI tools non-interactively. Use "all", "none", or a comma-separated list of: ${availableToolIds.join(', ')}. Also accepted: ${toolAliasNote}`;
 program
     .command('init [path]')
     .description('Initialize OpenSpec in your project')
     .option('--tools <tools>', toolsOptionDescription)
     .option('--force', 'Auto-cleanup legacy files without prompting')
     .option('--profile <profile>', 'Override global config profile (core or custom)')
+    .option('--no-animation', 'Show a static welcome screen instead of the animated one')
+    .option('--copilot-cloud', 'Set up GitHub Copilot cloud coding-agent files without prompting')
+    .option('--no-copilot-cloud', 'Skip GitHub Copilot cloud coding-agent files without prompting')
     .action(async (targetPath = '.', options) => {
     try {
         // Validate that the path is a valid directory
@@ -167,6 +153,8 @@ program
             tools: options?.tools,
             force: options?.force,
             profile: options?.profile,
+            animation: options?.animation,
+            copilotCloud: options?.copilotCloud,
         });
         await initCommand.execute(targetPath);
     }
@@ -202,8 +190,55 @@ program
     .option('--force', 'Force update even when tools are up to date')
     .action(async (targetPath = '.', options) => {
     try {
+        const installDir = getInstallDir();
+        // Running from a clone: the version is whatever the branch says, so any
+        // upgrade advice would be noise. Decided before the request, so a
+        // contributor never waits on an answer that gets thrown away.
+        const latestVersion = isSourceCheckout(installDir) ? null : await getAvailableCliUpdate();
+        const announce = latestVersion !== null;
+        // Offer to upgrade first: this process generates files from its own
+        // templates, so upgrading afterwards would leave the old ones on disk.
+        // Both streams must be a terminal — with stdout redirected the question
+        // lands in the file and the user waits at a blank screen forever.
+        const canOffer = announce &&
+            shouldOfferUpgrade({
+                installDir,
+                projectPath: targetPath,
+                interactive: isInteractive(),
+                stdoutIsTty: Boolean(process.stdout.isTTY),
+            });
+        let declined = false;
+        if (latestVersion && canOffer) {
+            displayCliUpdateNote(latestVersion, targetPath, { withCommand: false });
+            const outcome = await offerCliUpgrade(latestVersion);
+            // Set the code and return rather than process.exit: exiting here would
+            // skip commander's postAction hook, killing the telemetry flush
+            // mid-request.
+            if (outcome === 'cancelled') {
+                // Ctrl-C means stop the command, not fall through to more prompts.
+                process.exitCode = 130;
+                return;
+            }
+            if (outcome === 'upgraded') {
+                process.exitCode = await rerunUpdateWithUpgradedCli(targetPath, {
+                    force: options?.force,
+                });
+                return;
+            }
+            // Declined, failed, or upgraded-but-unreachable: fall through to the
+            // update, then leave the command on screen underneath it.
+            declined = true;
+        }
         const updateCommand = new UpdateCommand({ force: options?.force });
         await updateCommand.execute(targetPath);
+        if (declined) {
+            // The headline was printed before the prompt; only the manual route is
+            // still owed, and it belongs where the user is looking now.
+            displayUpgradeCommand(targetPath);
+        }
+        else if (latestVersion) {
+            displayCliUpdateNote(latestVersion, targetPath);
+        }
     }
     catch (error) {
         failWithError(error);
@@ -249,10 +284,19 @@ program
 program
     .command('view')
     .description('Display an interactive dashboard of specs and changes')
-    .action(async () => {
+    .option('--store <id>', STORE_OPTION_DESCRIPTION)
+    .addOption(hiddenStorePathOption())
+    .action(async (options) => {
     try {
+        // Implicit cwd fallback stays enabled so `view` keeps accepting the same
+        // directories as `list`/`status` — notably pre-config.yaml `openspec/`
+        // dirs. ViewCommand still reports a missing openspec/ directory itself.
+        const root = await resolveRootForCommand(options ?? {});
+        if (!root) {
+            return;
+        }
         const viewCommand = new ViewCommand();
-        await viewCommand.execute('.');
+        await viewCommand.execute(root.path);
     }
     catch (error) {
         failWithError(error);
@@ -497,27 +541,24 @@ program
 // Instructions command
 program
     .command('instructions [artifact]')
-    .description('Output enriched instructions for creating an artifact or applying tasks')
+    .description('Output enriched instructions for artifacts, apply, archive, or modify')
     .option('--change <id>', 'Change name')
     .option('--schema <name>', 'Schema override (auto-detected from config.yaml)')
     .option('--json', 'Output as JSON')
-    .option('--record-comprehension-pass', 'Record a successful comprehension quiz pass (use with instructions apply)')
-    .option('--score <percent>', 'Quiz score 0-100 (required with --record-comprehension-pass)', parseInt)
-    .option('--attempt <n>', 'Quiz attempt number', parseInt)
-    .option('--question-count <n>', 'Number of quiz questions taken', parseInt)
-    .option('--artifact <id>', 'Source artifact to modify (use with: instructions modify)')
-    .option('--workflow-input <text>', 'User modify request for telemetry (use with: instructions modify)')
-    .option('--workflow-input-file <path>', 'Read modify request from a file (use with: instructions modify)')
-    .option('--editor <tool>', 'AI editor used (cursor, windsurf, claude)')
     .option('--store <id>', STORE_OPTION_DESCRIPTION)
     .addOption(hiddenStorePathOption())
     .action(async (artifactId, options) => {
     try {
+        // Workflow instruction surfaces are reserved command branches, not artifacts.
         if (artifactId === 'apply') {
             await applyInstructionsCommand(options);
         }
+        else if (artifactId === 'archive') {
+            await archiveInstructionsCommand(options);
+        }
         else if (artifactId === 'modify') {
-            await modifyInstructionsCommand(options);
+            const modifyCommand = createModifyCommand();
+            modifyCommand.parse(process.argv.slice(2));
         }
         else {
             await instructionsCommand(artifactId, options);
@@ -565,10 +606,6 @@ newCmd
     .option('--description <text>', 'Description to add to README.md')
     .option('--goal <text>', 'Optional goal metadata to store with the change')
     .option('--schema <name>', `Workflow schema to use (default: ${DEFAULT_SCHEMA})`)
-    .option('--entry-point <point>', 'Workflow entry point (propose, new, ff, manual)', 'manual')
-    .option('--workflow-input <text>', 'User workflow intent for telemetry (verbatim chat/slash input)')
-    .option('--workflow-input-file <path>', 'Read workflow intent from a file for telemetry')
-    .option('--editor <tool>', 'AI editor used (cursor, windsurf, claude)')
     .option('--json', 'Output as JSON')
     .option('--store <id>', STORE_OPTION_DESCRIPTION)
     .addOption(hiddenStorePathOption())

package/dist/commands/change.d.ts

@@ -31,9 +31,7 @@ export declare class ChangeCommand {
         json?: boolean;
         noInteractive?: boolean;
     }): Promise<void>;
-    private getActiveChanges;
     private extractTitle;
-    private countTasks;
     private printNextSteps;
 }
 //# sourceMappingURL=change.d.ts.map

package/dist/commands/change.js

@@ -2,13 +2,31 @@ import { promises as fs } from 'fs';
 import path from 'path';
 import { JsonConverter } from '../core/converters/json-converter.js';
 import { Validator } from '../core/validation/validator.js';
+import { VALIDATION_MESSAGES } from '../core/validation/constants.js';
 import { ChangeParser } from '../core/parsers/change-parser.js';
 import { isInteractive } from '../utils/interactive.js';
 import { getActiveChangeIds } from '../utils/item-discovery.js';
-// Constants for better maintainability
-const ARCHIVE_DIR = 'archive';
-const TASK_PATTERN = /^[-*]\s+\[[\sx]\]/i;
-const COMPLETED_TASK_PATTERN = /^[-*]\s+\[x\]/i;
+import { getTaskProgressForChange } from '../utils/task-progress.js';
+import { FileSystemUtils } from '../utils/file-system.js';
+/**
+ * True only when `target` is definitively absent. An EACCES or I/O failure
+ * means existence cannot be determined, so callers fall through to their
+ * read-error path rather than claim the file was never written.
+ */
+async function isDefinitelyMissing(target) {
+    return fs
+        .access(target)
+        .then(() => false)
+        .catch((error) => error?.code === 'ENOENT');
+}
+/**
+ * A change is a directory directly under changes/. Rejecting anything else up
+ * front keeps a traversing name (`../..`) from reading a proposal outside the
+ * changes directory, and keeps the missing-proposal message honest.
+ */
+function isChangeDirectoryName(changesPath, changeDir) {
+    return path.dirname(path.resolve(changeDir)) === path.resolve(changesPath);
+}
 export class ChangeCommand {
     converter;
     rootPath;
@@ -31,7 +49,8 @@ export class ChangeCommand {
         const changesPath = this.getChangesPath();
         if (!changeName) {
             const canPrompt = isInteractive(options);
-            const changes = await this.getActiveChanges(changesPath);
+            // Offer exactly the changes `show <name>` can resolve.
+            const changes = await getActiveChangeIds(this.rootPath ?? process.cwd());
             if (canPrompt && changes.length > 0) {
                 const { select } = await import('@inquirer/prompts');
                 const selected = await select({
@@ -52,19 +71,40 @@ export class ChangeCommand {
                 return;
             }
         }
-        const proposalPath = path.join(changesPath, changeName, 'proposal.md');
+        const changeDir = path.join(changesPath, changeName);
+        const proposalPath = path.join(changeDir, 'proposal.md');
+        if (!isChangeDirectoryName(changesPath, changeDir)) {
+            throw new Error(`Change "${changeName}" not found at ${proposalPath}`);
+        }
         try {
             await fs.access(proposalPath);
         }
         catch {
+            // A change can exist without a proposal: `openspec new change` scaffolds
+            // only .openspec.yaml, and a custom schema need not define a proposal
+            // artifact. Say which of the two cases this is instead of reporting a
+            // change that does exist as missing. A stray file under changes/ is not a
+            // change, and naming it one would point the user at a `status --change`
+            // call that cannot work.
+            const isChangeDirectory = await fs
+                .stat(changeDir)
+                .then((stats) => stats.isDirectory())
+                .catch(() => false);
+            if (isChangeDirectory) {
+                throw new Error(`Change "${changeName}" has no proposal.md yet. ` +
+                    `Run "openspec status --change ${changeName}" to see which artifact comes next.`);
+            }
             throw new Error(`Change "${changeName}" not found at ${proposalPath}`);
         }
+        FileSystemUtils.assertPathWithin(path.dirname(proposalPath), proposalPath);
         if (options?.json) {
+            FileSystemUtils.assertPathWithin(changeDir, proposalPath);
             const jsonOutput = await this.converter.convertChangeToJson(proposalPath);
             if (options.requirementsOnly) {
                 console.error('Flag --requirements-only is deprecated; use --deltas-only instead.');
             }
             const parsed = JSON.parse(jsonOutput);
+            FileSystemUtils.assertPathWithin(changeDir, proposalPath);
             const contentForTitle = await fs.readFile(proposalPath, 'utf-8');
             const title = this.extractTitle(contentForTitle, changeName);
             const id = parsed.name;
@@ -79,6 +119,7 @@ export class ChangeCommand {
             console.log(JSON.stringify(output, null, 2));
         }
         else {
+            FileSystemUtils.assertPathWithin(changeDir, proposalPath);
             const content = await fs.readFile(proposalPath, 'utf-8');
             console.log(content);
         }
@@ -90,27 +131,31 @@ export class ChangeCommand {
      */
     async list(options) {
         const changesPath = path.join(process.cwd(), 'openspec', 'changes');
-        const changes = await this.getActiveChanges(changesPath);
+        // Same directory-based resolution as `openspec list`, the command this
+        // deprecated alias points users at. Every output path below already
+        // tolerates a change whose proposal.md is missing or unreadable.
+        const changes = await getActiveChangeIds();
         if (options?.json) {
             const changeDetails = await Promise.all(changes.map(async (changeName) => {
-                const proposalPath = path.join(changesPath, changeName, 'proposal.md');
-                const tasksPath = path.join(changesPath, changeName, 'tasks.md');
+                const changeDir = path.join(changesPath, changeName);
+                const proposalPath = path.join(changeDir, 'proposal.md');
+                // Resolve task progress through the shared tracked-tasks helper so
+                // this deprecated noun-form list cannot re-fork the resolution
+                // (#1202). Tasks are independent of the proposal: a change can carry
+                // tasks before, or without, a proposal.md.
+                const taskStatus = await getTaskProgressForChange(changesPath, changeName, process.cwd());
+                // No proposal yet is an ordinary state (scaffolded change, or a
+                // schema with no proposal artifact), so name the change rather than
+                // labelling it Unknown. Unknown stays for a proposal that exists but
+                // cannot be read or parsed.
+                if (await isDefinitelyMissing(proposalPath)) {
+                    return { id: changeName, title: changeName, deltaCount: 0, taskStatus };
+                }
                 try {
+                    FileSystemUtils.assertPathWithin(changeDir, proposalPath);
                     const content = await fs.readFile(proposalPath, 'utf-8');
-                    const changeDir = path.join(changesPath, changeName);
                     const parser = new ChangeParser(content, changeDir);
                     const change = await parser.parseChangeWithDeltas(changeName);
-                    let taskStatus = { total: 0, completed: 0 };
-                    try {
-                        const tasksContent = await fs.readFile(tasksPath, 'utf-8');
-                        taskStatus = this.countTasks(tasksContent);
-                    }
-                    catch (error) {
-                        // Tasks file may not exist, which is okay
-                        if (process.env.DEBUG) {
-                            console.error(`Failed to read tasks file at ${tasksPath}:`, error);
-                        }
-                    }
                     return {
                         id: changeName,
                         title: this.extractTitle(content, changeName),
@@ -118,13 +163,8 @@ export class ChangeCommand {
                         taskStatus,
                     };
                 }
-                catch (error) {
-                    return {
-                        id: changeName,
-                        title: 'Unknown',
-                        deltaCount: 0,
-                        taskStatus: { total: 0, completed: 0 },
-                    };
+                catch {
+                    return { id: changeName, title: 'Unknown', deltaCount: 0, taskStatus };
                 }
             }));
             const sorted = changeDetails.sort((a, b) => a.id.localeCompare(b.id));
@@ -143,30 +183,25 @@ export class ChangeCommand {
             }
             // Long format: id: title and minimal counts
             for (const changeName of sorted) {
-                const proposalPath = path.join(changesPath, changeName, 'proposal.md');
-                const tasksPath = path.join(changesPath, changeName, 'tasks.md');
+                const changeDir = path.join(changesPath, changeName);
+                const proposalPath = path.join(changeDir, 'proposal.md');
+                const { total, completed } = await getTaskProgressForChange(changesPath, changeName, process.cwd());
+                const taskStatusText = total > 0 ? ` [tasks ${completed}/${total}]` : '';
+                if (await isDefinitelyMissing(proposalPath)) {
+                    console.log(`${changeName}: (no proposal.md yet)${taskStatusText}`);
+                    continue;
+                }
                 try {
+                    FileSystemUtils.assertPathWithin(changeDir, proposalPath);
                     const content = await fs.readFile(proposalPath, 'utf-8');
                     const title = this.extractTitle(content, changeName);
-                    let taskStatusText = '';
-                    try {
-                        const tasksContent = await fs.readFile(tasksPath, 'utf-8');
-                        const { total, completed } = this.countTasks(tasksContent);
-                        taskStatusText = ` [tasks ${completed}/${total}]`;
-                    }
-                    catch (error) {
-                        if (process.env.DEBUG) {
-                            console.error(`Failed to read tasks file at ${tasksPath}:`, error);
-                        }
-                    }
-                    const changeDir = path.join(changesPath, changeName);
-                    const parser = new ChangeParser(await fs.readFile(proposalPath, 'utf-8'), changeDir);
+                    const parser = new ChangeParser(content, changeDir);
                     const change = await parser.parseChangeWithDeltas(changeName);
                     const deltaCountText = ` [deltas ${change.deltas.length}]`;
                     console.log(`${changeName}: ${title}${deltaCountText}${taskStatusText}`);
                 }
                 catch {
-                    console.log(`${changeName}: (unable to read)`);
+                    console.log(`${changeName}: (unable to read)${taskStatusText}`);
                 }
             }
         }
@@ -197,6 +232,9 @@ export class ChangeCommand {
             }
         }
         const changeDir = path.join(changesPath, changeName);
+        if (!isChangeDirectoryName(changesPath, changeDir)) {
+            throw new Error(`Change "${changeName}" not found at ${changeDir}`);
+        }
         try {
             await fs.access(changeDir);
         }
@@ -204,7 +242,12 @@ export class ChangeCommand {
             throw new Error(`Change "${changeName}" not found at ${changeDir}`);
         }
         const validator = new Validator(options?.strict || false);
-        const report = await validator.validateChangeDeltaSpecs(changeDir);
+        const report = await validator.validateChangeDeltaSpecs(changeDir, {
+            // Derived from changesPath so the main specs come from the same root the
+            // change itself was resolved against.
+            mainSpecsDir: path.join(path.dirname(changesPath), 'specs'),
+            projectRoot: path.dirname(path.dirname(changesPath)),
+        });
         if (options?.json) {
             console.log(JSON.stringify(report, null, 2));
         }
@@ -220,58 +263,36 @@ export class ChangeCommand {
                     console.error(`${prefix} [${label}] ${issue.path}: ${issue.message}`);
                 });
                 // Next steps footer to guide fixing issues
-                this.printNextSteps();
+                this.printNextSteps(report.issues);
                 if (!options?.json) {
                     process.exitCode = 1;
                 }
             }
         }
     }
-    async getActiveChanges(changesPath) {
-        try {
-            const entries = await fs.readdir(changesPath, { withFileTypes: true });
-            const result = [];
-            for (const entry of entries) {
-                if (!entry.isDirectory() || entry.name.startsWith('.') || entry.name === ARCHIVE_DIR)
-                    continue;
-                const proposalPath = path.join(changesPath, entry.name, 'proposal.md');
-                try {
-                    await fs.access(proposalPath);
-                    result.push(entry.name);
-                }
-                catch {
-                    // skip directories without proposal.md
-                }
-            }
-            return result.sort();
-        }
-        catch {
-            return [];
-        }
-    }
     extractTitle(content, changeName) {
         const match = content.match(/^#\s+(?:Change:\s+)?(.+)$/im);
         return match ? match[1].trim() : changeName;
     }
-    countTasks(content) {
-        const lines = content.split('\n');
-        let total = 0;
-        let completed = 0;
-        for (const line of lines) {
-            if (line.match(TASK_PATTERN)) {
-                total++;
-                if (line.match(COMPLETED_TASK_PATTERN)) {
-                    completed++;
-                }
-            }
-        }
-        return { total, completed };
-    }
-    printNextSteps() {
+    printNextSteps(issues = []) {
         const bullets = [];
-        bullets.push('- Ensure change has deltas in specs/: use headers ## ADDED/MODIFIED/REMOVED/RENAMED Requirements');
-        bullets.push('- Each requirement MUST include at least one #### Scenario: block');
-        bullets.push('- Debug parsed deltas: openspec change show <id> --json --deltas-only');
+        // Branch on the exact marker messages: the generic no-deltas guidance
+        // also mentions skip_specs and must not trigger the marker bullets.
+        const conflictIssue = issues.some(i => i.message.includes(VALIDATION_MESSAGES.CHANGE_SKIP_SPECS_CONFLICT));
+        const invalidMarkerIssue = issues.some(i => i.message.includes(VALIDATION_MESSAGES.CHANGE_SKIP_SPECS_INVALID_METADATA));
+        if (conflictIssue) {
+            bullets.push('- This change declares skip_specs (no spec deltas): delete the files under specs/, or remove skip_specs from .openspec.yaml if requirements do change');
+            bullets.push('- skip_specs is only honored when .openspec.yaml is valid change metadata (schema: <name> is required)');
+        }
+        else if (invalidMarkerIssue) {
+            bullets.push('- Fix .openspec.yaml so the skip_specs marker can be honored (schema: <name> is required)');
+            bullets.push('- Or remove skip_specs from .openspec.yaml and add delta specs instead');
+        }
+        else {
+            bullets.push('- Ensure change has deltas in specs/: use headers ## ADDED/MODIFIED/REMOVED/RENAMED Requirements');
+            bullets.push('- Each requirement MUST include at least one #### Scenario: block');
+            bullets.push('- Debug parsed deltas: openspec change show <id> --json --deltas-only');
+        }
         console.error('Next steps:');
         bullets.forEach(b => console.error(`  ${b}`));
     }

package/dist/commands/config.js

@@ -1,13 +1,13 @@
-import { spawn, execSync } from 'node:child_process';
-import { trackEvent } from '../telemetry/index.js';
+import { spawn } from 'node:child_process';
 import * as fs from 'node:fs';
 import * as path from 'node:path';
 import { getGlobalConfigPath, getGlobalConfig, saveGlobalConfig, } from '../core/global-config.js';
-import { getNestedValue, setNestedValue, deleteNestedValue, coerceValue, formatValueYaml, validateConfigKeyPath, validateConfig, DEFAULT_CONFIG, } from '../core/config-schema.js';
+import { getNestedValue, setNestedValue, deleteNestedValue, coerceValue, formatValueYaml, validateConfigKeyPath, hasUnsafeKeySegment, validateConfig, DEFAULT_CONFIG, } from '../core/config-schema.js';
 import { CORE_WORKFLOWS, ALL_WORKFLOWS, getProfileWorkflows } from '../core/profiles.js';
 import { OPENSPEC_DIR_NAME } from '../core/config.js';
 import { hasProjectConfigDrift } from '../core/profile-sync-drift.js';
-import { isPromptCancellationError } from './shared-output.js';
+import { UpdateCommand } from '../core/update.js';
+import { asErrorMessage, isPromptCancellationError } from './shared-output.js';
 const WORKFLOW_PROMPT_META = {
     propose: {
         name: 'Propose change',
@@ -234,11 +234,15 @@ export function registerConfigCommand(program) {
         .action((key, value, options) => {
         const allowUnknown = Boolean(options.allowUnknown);
         const keyValidation = validateConfigKeyPath(key);
-        if (!keyValidation.valid && !allowUnknown) {
+        // --allow-unknown relaxes the known-key check, but never the prototype-safety check.
+        const unsafeKey = hasUnsafeKeySegment(key);
+        if (!keyValidation.valid && (!allowUnknown || unsafeKey)) {
             const reason = keyValidation.reason ? ` ${keyValidation.reason}.` : '';
             console.error(`Error: Invalid configuration key "${key}".${reason}`);
             console.error('Use "openspec config list" to see available keys.');
-            console.error('Pass --allow-unknown to bypass this check.');
+            if (!allowUnknown && !unsafeKey) {
+                console.error('Pass --allow-unknown to bypass this check.');
+            }
             process.exitCode = 1;
             return;
         }
@@ -257,7 +261,6 @@ export function registerConfigCommand(program) {
         // Apply changes and save
         setNestedValue(config, key, coercedValue);
         saveGlobalConfig(config);
-        trackEvent('config_value_set', { key });
         const displayValue = typeof coercedValue === 'string' ? `"${coercedValue}"` : String(coercedValue);
         console.log(`Set ${key} = ${displayValue}`);
     });
@@ -519,12 +522,6 @@ export function registerConfigCommand(program) {
             config.delivery = nextState.delivery;
             config.workflows = nextState.workflows;
             saveGlobalConfig(config);
-            trackEvent('config_profile_changed', {
-                profile: nextState.profile,
-                delivery: nextState.delivery,
-                workflow_count: nextState.workflows.length,
-                changes: diff.lines,
-            });
             // Check if inside an OpenSpec project
             const projectDir = process.cwd();
             const openspecDir = path.join(projectDir, OPENSPEC_DIR_NAME);
@@ -535,11 +532,12 @@ export function registerConfigCommand(program) {
                 });
                 if (applyNow) {
                     try {
-                        execSync('npx openspec update', { stdio: 'inherit', cwd: projectDir });
+                        await new UpdateCommand().execute(projectDir);
                         console.log('Run `openspec update` in your other projects to apply.');
                     }
-                    catch {
-                        console.error('`openspec update` failed. Please run it manually to apply the profile changes.');
+                    catch (error) {
+                        console.error(`\`openspec update\` failed: ${asErrorMessage(error)}`);
+                        console.error('Please run it manually to apply the profile changes.');
                         process.exitCode = 1;
                     }
                     return;