@fission-ai/openspec 1.6.0 → 1.8.0

package/README.md

@@ -76,6 +76,29 @@ AI:  Archived to openspec/changes/archive/2025-01-23-add-dark-mode/
      Specs updated. Ready for the next feature.
 ```
 
+<details>
+<summary><strong>What do the specs actually look like?</strong></summary>
+
+Plain Markdown — requirements with concrete scenarios, no special syntax to learn. Here's what goes in the `specs/` folder created above:
+
+```markdown
+## ADDED Requirements
+
+### Requirement: Theme selection
+The app SHALL let users switch between light and dark themes,
+defaulting to the system preference.
+
+#### Scenario: User toggles dark mode
+- **WHEN** the user clicks the theme toggle
+- **THEN** the app switches to dark mode and persists the choice
+```
+
+Your AI writes these; you review the plan before any code is written.
+
+OpenSpec is built with OpenSpec — browse this repo's live [specs](openspec/specs) and in-flight [changes](openspec/changes) for real examples at scale.
+
+</details>
+
 <details>
 <summary><strong>OpenSpec Dashboard</strong></summary>
 
@@ -114,6 +137,8 @@ cd your-project
 openspec init
 ```
 
+> **Want your AI to do it?** Paste the [setup prompt](docs/installation.md#install-with-your-ai-assistant) into your coding assistant — it installs the CLI, runs `openspec init`, and verifies the result.
+
 Now talk to your AI:
 
 - **Not sure what to build yet?** Start with `/opsx:explore`, a no-stakes thinking partner that reads your code, weighs options, and shapes a plan before anything is written. ([Explore guide](docs/explore.md))
@@ -121,8 +146,10 @@ Now talk to your AI:
 
 Both are in the default profile. If you want the expanded workflow (`/opsx:new`, `/opsx:continue`, `/opsx:ff`, `/opsx:verify`, `/opsx:bulk-archive`, `/opsx:onboard`), select it with `openspec config profile` and apply with `openspec update`.
 
+`/opsx:propose` is the canonical name; your tool may spell it `/opsx-propose` (Cursor, GitHub Copilot), `@opsx-propose` (Amazon Q) or `$openspec-propose` (Codex). `openspec init` prints the right form for the tools you picked — see [How To Invoke](docs/supported-tools.md#how-to-invoke).
+
 > [!NOTE]
-> Not sure if your tool is supported? [View the full list](docs/supported-tools.md) – we support 25+ tools and growing.
+> Not sure if your tool is supported? [View the full list](docs/supported-tools.md) – we support 30+ tools and growing.
 >
 > Also works with pnpm, yarn, bun, and nix. [See installation options](docs/installation.md).
 
@@ -221,7 +248,9 @@ OpenSpec collects anonymous usage stats.
 
 We collect only command names and version to understand usage patterns. No arguments, paths, content, or PII. Automatically disabled in CI.
 
-**Opt-out:** `export OPENSPEC_TELEMETRY=0` or `export DO_NOT_TRACK=1`
+**Opt-out (any one is enough):**
+- `openspec config set telemetry.enabled false` (global config; unset means on)
+- `export OPENSPEC_TELEMETRY=0` or `export DO_NOT_TRACK=1` (env overrides config)
 
 </details>
 

package/dist/cli/index.js

@@ -5,8 +5,9 @@ import ora from 'ora';
 import path from 'path';
 import { fileURLToPath } from '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,9 +24,10 @@ 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, templatesCommand, schemasCommand, newChangeCommand, DEFAULT_SCHEMA, } from '../commands/workflow/index.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 { 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,
@@ -95,14 +97,22 @@ program.hook('preAction', async (thisCommand, actionCommand) => {
 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
@@ -130,6 +140,8 @@ program
             tools: options?.tools,
             force: options?.force,
             profile: options?.profile,
+            animation: options?.animation,
+            copilotCloud: options?.copilotCloud,
         });
         await initCommand.execute(targetPath);
     }
@@ -165,8 +177,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);
@@ -212,10 +271,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);
@@ -460,7 +528,7 @@ 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, or archive')
     .option('--change <id>', 'Change name')
     .option('--schema <name>', 'Schema override (auto-detected from config.yaml)')
     .option('--json', 'Output as JSON')
@@ -468,10 +536,13 @@ program
     .addOption(hiddenStorePathOption())
     .action(async (artifactId, options) => {
     try {
-        // Special case: "apply" is not an artifact, but a command to get apply instructions
+        // Workflow instruction surfaces are reserved command branches, not artifacts.
         if (artifactId === 'apply') {
             await applyInstructionsCommand(options);
         }
+        else if (artifactId === 'archive') {
+            await archiveInstructionsCommand(options);
+        }
         else {
             await instructionsCommand(artifactId, options);
         }

package/dist/commands/change.d.ts

@@ -31,7 +31,6 @@ export declare class ChangeCommand {
         json?: boolean;
         noInteractive?: boolean;
     }): Promise<void>;
-    private getActiveChanges;
     private extractTitle;
     private printNextSteps;
 }

package/dist/commands/change.js

@@ -2,12 +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';
 import { getTaskProgressForChange } from '../utils/task-progress.js';
-// Constants for better maintainability
-const ARCHIVE_DIR = 'archive';
+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;
@@ -30,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({
@@ -51,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;
@@ -78,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);
         }
@@ -89,18 +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 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);
-                    // Resolve task progress through the shared tracked-tasks helper so
-                    // this deprecated noun-form list cannot re-fork the resolution (#1202).
-                    const taskStatus = await getTaskProgressForChange(changesPath, changeName, process.cwd());
                     return {
                         id: changeName,
                         title: this.extractTitle(content, changeName),
@@ -108,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));
@@ -133,20 +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 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);
-                    const { total, completed } = await getTaskProgressForChange(changesPath, changeName, process.cwd());
-                    const taskStatusText = total > 0 ? ` [tasks ${completed}/${total}]` : '';
-                    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}`);
                 }
             }
         }
@@ -177,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);
         }
@@ -184,7 +242,11 @@ 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'),
+        });
         if (options?.json) {
             console.log(JSON.stringify(report, null, 2));
         }
@@ -200,44 +262,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;
     }
-    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,12 +1,13 @@
-import { spawn, execSync } from 'node:child_process';
+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',
@@ -233,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;
         }
@@ -527,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;

package/dist/commands/doctor.js

@@ -6,7 +6,7 @@
 import { Option } from 'commander';
 import { resolveRootForCommand, } from '../core/root-selection.js';
 import { readOptionalStoreMetadataState } from '../core/store/foundation.js';
-import { gitOriginUrl, isGitRepositoryAtRoot } from '../core/store/git.js';
+import { gitOriginUrl, gitTrackingDrift, isGitRepositoryAtRoot } from '../core/store/git.js';
 import { classifyOpenSpecDir, readProjectConfig, resolveConfigFilePath, } from '../core/project-config.js';
 import { findRepoPlanningRootSync } from '../core/planning-home.js';
 import { gatherRelationshipData } from './shared-gather.js';
@@ -27,7 +27,8 @@ async function gatherHealth(root) {
         referenceEntries,
         registryUnreadable,
     };
-    // Store facts for store-backed roots (explicit --store or declared).
+    // Store facts for store-backed roots (explicit --store, a declared
+    // pointer, or the global default).
     // Missing/invalid metadata never reaches here: store resolution
     // verifies identity first and fails with the existing taxonomy
     // (recorded amendment - corrupt store.yaml is an exit-1 resolution
@@ -35,14 +36,18 @@ async function gatherHealth(root) {
     if (root.storeId) {
         const metadata = await readOptionalStoreMetadataState(root.path).catch(() => null);
         // git -C walks UP the tree: probing a non-repo store nested inside
-        // another repo would record the ENCLOSING repo's origin.
-        const originUrl = (await isGitRepositoryAtRoot(root.path)) ? await gitOriginUrl(root.path) : null;
+        // another repo would record the ENCLOSING repo's origin (and drift).
+        const isRepo = await isGitRepositoryAtRoot(root.path);
+        const [originUrl, drift] = isRepo
+            ? await Promise.all([gitOriginUrl(root.path), gitTrackingDrift(root.path)])
+            : [null, null];
         input.storeFacts = {
             id: root.storeId,
             metadataPresent: metadata !== null,
             metadataValid: metadata !== null,
             ...(metadata?.remote ? { canonicalRemote: metadata.remote } : {}),
             ...(originUrl ? { originUrl } : {}),
+            ...(drift ? { drift } : {}),
         };
     }
     // The 3.2 both-shapes wrong turn, structured — including a malformed