@fission-ai/openspec 1.13.2 → 1.14.0

package/dist/core/command-generation/adapters/gigacode.js

@@ -0,0 +1,31 @@
+/**
+ * GigaCode Command Adapter
+ *
+ * Formats commands for GigaCode using its Markdown custom command format.
+ * Project commands live in `.gigacode/commands/` and accept an optional
+ * `description` field in YAML frontmatter.
+ *
+ * @see https://gitverse.ru/docs/ai/ai-assistant-gigacode/gigacode-cli/commands
+ */
+import path from 'path';
+import { escapeYamlValue } from '../yaml.js';
+/**
+ * GigaCode adapter for command generation.
+ * File path: .gigacode/commands/opsx-<id>.md
+ * Format: Markdown with description frontmatter
+ */
+export const gigacodeAdapter = {
+    toolId: 'gigacode',
+    getFilePath(commandId) {
+        return path.join('.gigacode', 'commands', `opsx-${commandId}.md`);
+    },
+    formatFile(content) {
+        return `---
+description: ${escapeYamlValue(content.description)}
+---
+
+${content.body}
+`;
+    },
+};
+//# sourceMappingURL=gigacode.js.map

package/dist/core/command-generation/adapters/index.d.ts

@@ -5,20 +5,24 @@
  */
 export { amazonQAdapter } from './amazon-q.js';
 export { antigravityAdapter } from './antigravity.js';
+export { atomcodeAdapter } from './atomcode.js';
 export { auggieAdapter } from './auggie.js';
 export { bobAdapter } from './bob.js';
 export { claudeAdapter } from './claude.js';
 export { clineAdapter } from './cline.js';
 export { commandCodeAdapter } from './command-code.js';
 export { codebuddyAdapter } from './codebuddy.js';
+export { codeStudioAdapter } from './codestudio.js';
 export { continueAdapter } from './continue.js';
 export { costrictAdapter } from './costrict.js';
 export { crushAdapter } from './crush.js';
 export { cursorAdapter } from './cursor.js';
 export { devinAdapter } from './devin.js';
+export { easycodeAdapter } from './easycode.js';
 export { factoryAdapter } from './factory.js';
 export { geminiAdapter } from './gemini.js';
 export { githubCopilotAdapter } from './github-copilot.js';
+export { gigacodeAdapter } from './gigacode.js';
 export { iflowAdapter } from './iflow.js';
 export { junieAdapter } from './junie.js';
 export { kilocodeAdapter } from './kilocode.js';

package/dist/core/command-generation/adapters/index.js

@@ -5,20 +5,24 @@
  */
 export { amazonQAdapter } from './amazon-q.js';
 export { antigravityAdapter } from './antigravity.js';
+export { atomcodeAdapter } from './atomcode.js';
 export { auggieAdapter } from './auggie.js';
 export { bobAdapter } from './bob.js';
 export { claudeAdapter } from './claude.js';
 export { clineAdapter } from './cline.js';
 export { commandCodeAdapter } from './command-code.js';
 export { codebuddyAdapter } from './codebuddy.js';
+export { codeStudioAdapter } from './codestudio.js';
 export { continueAdapter } from './continue.js';
 export { costrictAdapter } from './costrict.js';
 export { crushAdapter } from './crush.js';
 export { cursorAdapter } from './cursor.js';
 export { devinAdapter } from './devin.js';
+export { easycodeAdapter } from './easycode.js';
 export { factoryAdapter } from './factory.js';
 export { geminiAdapter } from './gemini.js';
 export { githubCopilotAdapter } from './github-copilot.js';
+export { gigacodeAdapter } from './gigacode.js';
 export { iflowAdapter } from './iflow.js';
 export { junieAdapter } from './junie.js';
 export { kilocodeAdapter } from './kilocode.js';

package/dist/core/command-generation/registry.js

@@ -6,6 +6,7 @@
  */
 import { amazonQAdapter } from './adapters/amazon-q.js';
 import { antigravityAdapter } from './adapters/antigravity.js';
+import { atomcodeAdapter } from './adapters/atomcode.js';
 import { auggieAdapter } from './adapters/auggie.js';
 import { bobAdapter } from './adapters/bob.js';
 import { claudeAdapter } from './adapters/claude.js';
@@ -13,13 +14,16 @@ import { clineAdapter } from './adapters/cline.js';
 import { commandCodeAdapter } from './adapters/command-code.js';
 import { devinAdapter } from './adapters/devin.js';
 import { codebuddyAdapter } from './adapters/codebuddy.js';
+import { codeStudioAdapter } from './adapters/codestudio.js';
 import { continueAdapter } from './adapters/continue.js';
 import { costrictAdapter } from './adapters/costrict.js';
 import { crushAdapter } from './adapters/crush.js';
 import { cursorAdapter } from './adapters/cursor.js';
+import { easycodeAdapter } from './adapters/easycode.js';
 import { factoryAdapter } from './adapters/factory.js';
 import { geminiAdapter } from './adapters/gemini.js';
 import { githubCopilotAdapter } from './adapters/github-copilot.js';
+import { gigacodeAdapter } from './adapters/gigacode.js';
 import { iflowAdapter } from './adapters/iflow.js';
 import { junieAdapter } from './adapters/junie.js';
 import { kilocodeAdapter } from './adapters/kilocode.js';
@@ -43,6 +47,7 @@ export class CommandAdapterRegistry {
     static {
         CommandAdapterRegistry.register(amazonQAdapter);
         CommandAdapterRegistry.register(antigravityAdapter);
+        CommandAdapterRegistry.register(atomcodeAdapter);
         CommandAdapterRegistry.register(auggieAdapter);
         CommandAdapterRegistry.register(bobAdapter);
         CommandAdapterRegistry.register(claudeAdapter);
@@ -50,13 +55,16 @@ export class CommandAdapterRegistry {
         CommandAdapterRegistry.register(commandCodeAdapter);
         CommandAdapterRegistry.register(devinAdapter);
         CommandAdapterRegistry.register(codebuddyAdapter);
+        CommandAdapterRegistry.register(codeStudioAdapter);
         CommandAdapterRegistry.register(continueAdapter);
         CommandAdapterRegistry.register(costrictAdapter);
         CommandAdapterRegistry.register(crushAdapter);
         CommandAdapterRegistry.register(cursorAdapter);
+        CommandAdapterRegistry.register(easycodeAdapter);
         CommandAdapterRegistry.register(factoryAdapter);
         CommandAdapterRegistry.register(geminiAdapter);
         CommandAdapterRegistry.register(githubCopilotAdapter);
+        CommandAdapterRegistry.register(gigacodeAdapter);
         CommandAdapterRegistry.register(iflowAdapter);
         CommandAdapterRegistry.register(junieAdapter);
         CommandAdapterRegistry.register(kilocodeAdapter);

package/dist/core/command-generation/toml.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Shared TOML string escaping for command adapters.
+ */
+/**
+ * TOML basic strings are escape-active: a backslash or double quote in the
+ * value breaks the file if written raw. Newlines cannot appear in a
+ * single-line basic string at all, so they are escaped too.
+ */
+export declare function escapeTomlBasicString(value: string): string;
+/**
+ * Multiline basic strings keep raw newlines and tabs, but backslashes are
+ * still escape-active, any run of three quotes would end the string, and the
+ * same control characters are invalid as in single-line basic strings — a
+ * lone carriage return included (only LF and CRLF may appear raw; CRLF is
+ * normalized away so the emitted file is single-convention). Escapes are
+ * introduced after backslash-doubling so they are not re-doubled.
+ */
+export declare function escapeTomlMultilineBasicString(value: string): string;
+//# sourceMappingURL=toml.d.ts.map

package/dist/core/command-generation/toml.js

@@ -0,0 +1,39 @@
+/**
+ * Shared TOML string escaping for command adapters.
+ */
+/**
+ * Control characters (C0 except tab/newline/carriage return, plus DEL) are
+ * invalid inside TOML strings and must be written as escapes.
+ */
+const TOML_CONTROL_CHARS = new RegExp('[\\u0000-\\u0008\\u000b\\u000c\\u000e-\\u001f\\u007f]', 'g');
+/**
+ * TOML basic strings are escape-active: a backslash or double quote in the
+ * value breaks the file if written raw. Newlines cannot appear in a
+ * single-line basic string at all, so they are escaped too.
+ */
+export function escapeTomlBasicString(value) {
+    return value
+        .replace(/\\/g, '\\\\')
+        .replace(/"/g, '\\"')
+        .replace(/\n/g, '\\n')
+        .replace(/\r/g, '\\r')
+        .replace(/\t/g, '\\t')
+        .replace(TOML_CONTROL_CHARS, (c) => `\\u${c.charCodeAt(0).toString(16).padStart(4, '0')}`);
+}
+/**
+ * Multiline basic strings keep raw newlines and tabs, but backslashes are
+ * still escape-active, any run of three quotes would end the string, and the
+ * same control characters are invalid as in single-line basic strings — a
+ * lone carriage return included (only LF and CRLF may appear raw; CRLF is
+ * normalized away so the emitted file is single-convention). Escapes are
+ * introduced after backslash-doubling so they are not re-doubled.
+ */
+export function escapeTomlMultilineBasicString(value) {
+    return value
+        .replace(/\r\n/g, '\n')
+        .replace(/\\/g, '\\\\')
+        .replace(/"""/g, '""\\"')
+        .replace(/\r/g, '\\r')
+        .replace(TOML_CONTROL_CHARS, (c) => `\\u${c.charCodeAt(0).toString(16).padStart(4, '0')}`);
+}
+//# sourceMappingURL=toml.js.map

package/dist/core/command-surface.js

@@ -13,7 +13,7 @@ export function resolveCommandSurfaceCapability(toolId) {
     if (CommandAdapterRegistry.has(toolId)) {
         return 'adapter-backed';
     }
-    if (toolId === 'codex') {
+    if (toolId === 'codex' || toolId === 'warp') {
         return 'skills-invocable';
     }
     return 'none';

package/dist/core/completions/command-registry.js

@@ -54,6 +54,17 @@ export const COMMAND_REGISTRY = [
             },
         ],
     },
+    {
+        name: 'version',
+        description: 'Report the installed OpenSpec version and update availability',
+        flags: [
+            COMMON_FLAGS.json,
+            {
+                name: 'check',
+                description: 'Check the registry for a newer version',
+            },
+        ],
+    },
     {
         name: 'list',
         description: 'List items (changes by default, or specs with --specs)',
@@ -66,6 +77,14 @@ export const COMMAND_REGISTRY = [
                 name: 'changes',
                 description: 'List changes explicitly (default)',
             },
+            {
+                name: 'archived',
+                description: 'Show only archived changes',
+            },
+            {
+                name: 'all',
+                description: 'Show both active and archived changes',
+            },
             {
                 name: 'sort',
                 description: 'Sort order: "recent" (default) or "name"',

package/dist/core/completions/installers/zsh-installer.js

@@ -194,8 +194,10 @@ export class ZshInstaller {
             }
             // Remove lines between markers (inclusive)
             lines.splice(startIndex, endIndex - startIndex + 1);
-            // Remove trailing empty lines at the start if the markers were at the top
-            while (lines.length > 0 && lines[0].trim() === '') {
+            // Install puts the block at the top of the file followed by one blank
+            // separator line; drop that line too so the file reads as it did before.
+            // Everything else, including blank lines the user had at the top, is left as is.
+            if (startIndex === 0 && lines.length > 0 && lines[0].trim() === '') {
                 lines.shift();
             }
             // Write back

package/dist/core/config-prompts.js

@@ -19,13 +19,13 @@ export function serializeConfig(config) {
     else {
         // Context section with comments
         lines.push('# Project context (optional)');
-        lines.push('# This is shown to AI when creating artifacts.');
-        lines.push('# Add your tech stack, conventions, style guides, domain knowledge, etc.');
+        lines.push('# Add only constraints that should guide OpenSpec artifacts and workflows.');
+        lines.push('# Include constraints an agent cannot infer by reading the code.');
+        lines.push('# Keep general project documentation and discoverable codebase facts out.');
         lines.push('# Example:');
         lines.push('#   context: |');
-        lines.push('#     Tech stack: TypeScript, React, Node.js');
-        lines.push('#     We use conventional commits');
-        lines.push('#     Domain: e-commerce platform');
+        lines.push('#     Designs and tasks must cover Windows, macOS, and Linux');
+        lines.push('#     Write all artifacts in Spanish');
         lines.push('');
     }
     // Rules section with comments
@@ -35,7 +35,7 @@ export function serializeConfig(config) {
     lines.push('#   rules:');
     lines.push('#     proposal:');
     lines.push('#       - Keep proposals under 500 words');
-    lines.push('#       - Always include a "Non-goals" section');
+    lines.push('#       - Always state what is out of scope');
     lines.push('#     tasks:');
     lines.push('#       - Break tasks into chunks of max 2 hours');
     lines.push('');

package/dist/core/config.js

@@ -19,29 +19,37 @@ export const OPENSPEC_MARKERS = {
 };
 export const AI_TOOLS = [
     { name: 'Amazon Q Developer', value: 'amazon-q', available: true, successLabel: 'Amazon Q Developer', skillsDir: '.amazonq', requiresIdeRestart: true },
+    { name: 'Amp', value: 'amp', available: true, successLabel: 'Amp', skillsDir: '.agents', detectionPaths: ['.amp', '.agents/skills'] },
     // Antigravity moved workspace skills and workflows from `.agent` to the
     // shared `.agents` root in v1.20.5. Detection keys off `.agent` and
     // `.agents/workflows` rather than the bare `.agents` root: that root is
     // shared with Codex, Zed, and the vendor-neutral target, so its presence
     // alone says nothing about Antigravity.
     { name: 'Antigravity', value: 'antigravity', available: true, successLabel: 'Antigravity', skillsDir: '.agents', legacySkillsDirs: ['.agent'], detectionPaths: ['.agent', '.agents/workflows'], requiresIdeRestart: true },
+    { name: 'AtomCode', value: 'atomcode', available: true, successLabel: 'AtomCode', skillsDir: '.atomcode' },
     { name: 'Auggie (Augment CLI)', value: 'auggie', available: true, successLabel: 'Auggie', skillsDir: '.augment' },
-    { name: 'Bob Shell', value: 'bob', available: true, successLabel: 'Bob Shell', skillsDir: '.bob' },
+    { name: 'IBM Bob', value: 'bob', available: true, successLabel: 'IBM Bob', skillsDir: '.bob' },
     { name: 'Claude Code', value: 'claude', available: true, successLabel: 'Claude Code', skillsDir: '.claude' },
     { name: 'Cline', value: 'cline', available: true, successLabel: 'Cline', skillsDir: '.cline', requiresIdeRestart: true },
     { name: 'Command Code', value: 'command-code', available: true, successLabel: 'Command Code', skillsDir: '.commandcode' },
     { name: 'CodeArts', value: 'codeartsagent', available: true, successLabel: 'CodeArts', skillsDir: '.codeartsdoer' },
     { name: 'Codex', value: 'codex', available: true, successLabel: 'Codex', skillsDir: '.agents', legacySkillsDirs: ['.codex'], detectionPaths: ['.agents/skills', '.codex/skills'] },
+    { name: 'DeepSeek Harness', value: 'dsh', available: true, successLabel: 'DeepSeek Harness', skillsDir: '.dsh' },
     { name: 'Devin Desktop (formerly Windsurf)', value: 'devin', available: true, successLabel: 'Devin Desktop', skillsDir: '.devin', detectionPaths: ['.devin', '.windsurf'], requiresIdeRestart: true },
     { name: 'ForgeCode', value: 'forgecode', available: true, successLabel: 'ForgeCode', skillsDir: '.forge' },
     { name: 'CodeBuddy Code (CLI)', value: 'codebuddy', available: true, successLabel: 'CodeBuddy Code', skillsDir: '.codebuddy' },
+    { name: 'Code Studio', value: 'codestudio', available: true, successLabel: 'Code Studio', skillsDir: '.codestudio', requiresIdeRestart: true },
     { name: 'Continue', value: 'continue', available: true, successLabel: 'Continue (VS Code / JetBrains / Cli)', skillsDir: '.continue', requiresIdeRestart: true },
     { name: 'CoStrict', value: 'costrict', available: true, successLabel: 'CoStrict', skillsDir: '.cospec', requiresIdeRestart: true },
     { name: 'Crush', value: 'crush', available: true, successLabel: 'Crush', skillsDir: '.crush' },
     { name: 'Cursor', value: 'cursor', available: true, successLabel: 'Cursor', skillsDir: '.cursor', requiresIdeRestart: true },
+    { name: 'EasyCode', value: 'easycode', available: true, successLabel: 'EasyCode', skillsDir: '.easycode' },
     { name: 'Factory Droid', value: 'factory', available: true, successLabel: 'Factory Droid', skillsDir: '.factory' },
     { name: 'Gemini CLI', value: 'gemini', available: true, successLabel: 'Gemini CLI', skillsDir: '.gemini' },
     { name: 'GitHub Copilot', value: 'github-copilot', available: true, successLabel: 'GitHub Copilot', skillsDir: '.github', detectionPaths: ['.github/copilot-instructions.md', '.github/instructions', '.github/workflows/copilot-setup-steps.yml', '.github/prompts', '.github/agents', '.github/skills', '.github/.mcp.json'], requiresIdeRestart: true },
+    { name: 'GigaCode', value: 'gigacode', available: true, successLabel: 'GigaCode', skillsDir: '.gigacode' },
+    { name: 'Grok Build', value: 'grok', available: true, successLabel: 'Grok Build', skillsDir: '.grok' },
+    { name: 'GSD', value: 'gsd', available: true, successLabel: 'GSD', skillsDir: '.agents', detectionPaths: ['.gsd'] },
     { name: 'Hermes Agent', value: 'hermes', available: true, successLabel: 'Hermes Agent', skillsDir: '.hermes', detectionPaths: ['.hermes', 'HERMES.md', '.hermes.md'], setupNote: "Hermes only loads skills from ~/.hermes/skills by default. Add this project's .hermes/skills directory to skills.external_dirs in ~/.hermes/config.yaml so Hermes picks up the generated OpenSpec skills." },
     { name: 'iFlow', value: 'iflow', available: true, successLabel: 'iFlow', skillsDir: '.iflow' },
     { name: 'Junie', value: 'junie', available: true, successLabel: 'Junie', skillsDir: '.junie', requiresIdeRestart: true },
@@ -60,6 +68,8 @@ export const AI_TOOLS = [
     { name: 'Rovo Dev CLI', value: 'rovodev', available: true, successLabel: 'Rovo Dev CLI', skillsDir: '.rovodev', detectionPaths: ['.rovodev/skills', '.rovodev'] },
     { name: 'Zoo Code', value: 'roocode', available: true, successLabel: 'Zoo Code', skillsDir: '.roo', requiresIdeRestart: true },
     { name: 'Trae', value: 'trae', available: true, successLabel: 'Trae', skillsDir: '.trae', requiresIdeRestart: true },
+    { name: 'Veai', value: 'veai', available: true, successLabel: 'Veai', skillsDir: '.veai' },
+    { name: 'Warp', value: 'warp', available: true, successLabel: 'Warp', skillsDir: '.warp', detectionPaths: ['.warp', 'WARP.md'] },
     { name: 'Zed Agent', value: 'zed', available: true, successLabel: 'Zed Agent', skillsDir: '.agents', detectionPaths: ['.zed', '.agents/skills'] },
     { name: 'ZCode', value: 'zcode', available: true, successLabel: 'ZCode', skillsDir: '.zcode' },
     // Vendor-neutral target for assistants that read the shared `.agents` root.

package/dist/core/init.js

@@ -12,6 +12,7 @@ import { createRequire } from 'module';
 import { FileSystemUtils } from '../utils/file-system.js';
 import { classifyOpenSpecDir, MAX_CONTEXT_SIZE, readProjectConfig, storePointerProblem, } from './project-config.js';
 import { findRepoPlanningRootSync } from './planning-home.js';
+import { resolveOpenSpecRoot } from './root-selection.js';
 import { ANCHORED_OPENSPEC_DIRS, ensureDirectoryAnchor } from './openspec-root.js';
 import { getSkillReferenceTransformer, getTransformerForTool, usesNaturalLanguageSkillReferences } from '../utils/command-references.js';
 import { AI_TOOLS, getUniversalTool, universalToolFallbackHint, OPENSPEC_DIR_NAME, resolveToolIdAlias, } from './config.js';
@@ -81,7 +82,7 @@ export class InitCommand {
         this.copilotCloudOption = options.copilotCloud;
     }
     async execute(targetPath) {
-        const projectPath = path.resolve(targetPath);
+        const projectPath = FileSystemUtils.canonicalizeExistingPath(targetPath);
         const openspecDir = OPENSPEC_DIR_NAME;
         const openspecPath = path.join(projectPath, openspecDir);
         // Validation happens silently in the background
@@ -94,6 +95,7 @@ export class InitCommand {
         // finds the nearest ancestor root (so pointer-repo subdirectories
         // refuse exactly where a normal command would resolve the pointer).
         const guardRoot = findRepoPlanningRootSync(projectPath);
+        let integrationsOnly = false;
         if (guardRoot) {
             const { hasPlanningShape, pointer } = classifyOpenSpecDir(guardRoot);
             if (!hasPlanningShape) {
@@ -103,14 +105,30 @@ export class InitCommand {
                         `). Fix or remove the store: line before running openspec init.`);
                 }
                 if (pointer.value !== undefined) {
-                    throw new Error(`This repo's planning is externalized to store '${pointer.value}' (${pointer.filePath}). ` +
-                        `Remove the store: line first to convert this repo to a local OpenSpec root.`);
+                    if (path.resolve(guardRoot) !== projectPath) {
+                        throw new Error(`This repo's planning is externalized to store '${pointer.value}' (${pointer.filePath}). ` +
+                            'Run openspec init from the pointer repo root to install integrations.');
+                    }
+                    // A valid pointer repo already has its planning root in the declared
+                    // store. Init should still be able to install agent integrations in
+                    // the code repo, without creating a second local planning root.
+                    await resolveOpenSpecRoot({ startPath: projectPath });
+                    integrationsOnly = true;
                 }
             }
         }
-        await this.assertLanguageCanBeApplied(projectPath, openspecPath);
-        // Check for legacy artifacts and handle cleanup
-        const deferredLegacyCleanup = await this.handleLegacyCleanup(projectPath, extendMode);
+        if (!integrationsOnly) {
+            await this.assertLanguageCanBeApplied(projectPath, openspecPath);
+        }
+        else if (this.language) {
+            throw new Error('--language cannot update an external store through a pointer repo. ' +
+                'Run init in the store root, or edit the store config directly.');
+        }
+        // Pointer repos keep their local planning files untouched. Normal init may
+        // still remove OpenSpec-managed artifacts from older layouts.
+        const deferredLegacyCleanup = integrationsOnly
+            ? null
+            : await this.handleLegacyCleanup(projectPath, extendMode);
         // Migrate OpenSpec-managed skills left in renamed tool directories
         // (e.g. .kimi -> .kimi-code) before detection so they stay recognized.
         migrateLegacyToolDirs(projectPath);
@@ -154,8 +172,11 @@ export class InitCommand {
         // is made before generation so the write can be gated, and persisted after
         // config.yaml exists so future non-interactive updates honor it.
         const copilotDecision = await this.resolveCopilotCloudDecision(projectPath, validatedTools);
-        // Create directory structure and config
-        await this.createDirectoryStructure(openspecPath, extendMode);
+        // Pointer repos only receive integrations. Their planning structure and
+        // config stay in the declared store.
+        if (!integrationsOnly) {
+            await this.createDirectoryStructure(openspecPath, extendMode);
+        }
         // Generate skills and commands for each tool
         const results = await this.generateSkillsAndCommands(projectPath, validatedTools, copilotDecision.write);
         // Legacy cleanup was deferred to avoid interfering with skill/command generation;
@@ -163,12 +184,15 @@ export class InitCommand {
         if (deferredLegacyCleanup) {
             await this.finalizeDeferredLegacyCleanup(projectPath, deferredLegacyCleanup);
         }
-        // Create config.yaml if needed
-        const configStatus = await this.createConfig(openspecPath, extendMode);
+        // Create config.yaml if needed. A pointer repo already has the config that
+        // declares its store, so preserve it byte-for-byte.
+        const configStatus = integrationsOnly
+            ? 'exists'
+            : await this.createConfig(openspecPath, extendMode);
         // Persist an explicit Copilot cloud decision so `openspec update` (which
         // never prompts) honors it. Best-effort: a config-write failure must not
         // fail an otherwise-successful init.
-        if (copilotDecision.persist !== undefined) {
+        if (!integrationsOnly && copilotDecision.persist !== undefined) {
             try {
                 await persistCopilotCloudOptIn(projectPath, copilotDecision.persist);
             }

package/dist/core/legacy-cleanup.js

@@ -745,10 +745,10 @@ export function formatDetectionSummary(detection) {
     lines.push('agents. This simplifies your setup while keeping everything working');
     lines.push('as before.');
     lines.push('');
-    // Section 1: Files to remove (no user content to preserve)
+    // Section 1: Files to remove entirely
     if (removals.length > 0) {
         lines.push(chalk.bold('Files to remove'));
-        lines.push(chalk.dim('No user content to preserve:'));
+        lines.push(chalk.dim('These files will be deleted entirely. Back up any custom content before proceeding:'));
         for (const { path } of removals) {
             lines.push(`  • ${path}`);
         }
@@ -953,12 +953,16 @@ export function formatProjectMdMigrationHint() {
     lines.push('  • openspec/project.md');
     lines.push(chalk.dim('    We won\'t delete this file. It may contain useful project context.'));
     lines.push('');
-    lines.push(chalk.dim('    The new openspec/config.yaml has a "context:" section for planning'));
-    lines.push(chalk.dim('    context. This is included in every OpenSpec request and works more'));
-    lines.push(chalk.dim('    reliably than the old project.md approach.'));
+    lines.push(chalk.dim('    Ask your AI assistant:'));
     lines.push('');
-    lines.push(chalk.dim('    Review project.md, move any useful content to config.yaml\'s context'));
-    lines.push(chalk.dim('    section, then delete the file when ready.'));
+    lines.push(chalk.dim('    Review openspec/project.md and migrate its useful content to'));
+    lines.push(chalk.dim('    openspec/config.yaml. Keep context concise: include only project-wide'));
+    lines.push(chalk.dim('    facts needed during artifact creation, apply, and archive. Move'));
+    lines.push(chalk.dim('    artifact-specific guidance into rules for the matching artifacts.'));
+    lines.push(chalk.dim('    Move guidance for apply or archive into the matching operations entry.'));
+    lines.push(chalk.dim('    Leave out generic, outdated, or verbose material. Do not delete project.md.'));
+    lines.push('');
+    lines.push(chalk.dim('    Review config.yaml, then delete project.md when ready.'));
     return lines.join('\n');
 }
 //# sourceMappingURL=legacy-cleanup.js.map

package/dist/core/list.d.ts

@@ -3,6 +3,8 @@ interface ListOptions {
     sort?: 'recent' | 'name';
     json?: boolean;
     root?: RootOutput;
+    archived?: boolean;
+    all?: boolean;
 }
 export declare class ListCommand {
     execute(targetPath?: string, mode?: 'changes' | 'specs', options?: ListOptions): Promise<void>;

package/dist/core/list.js

@@ -35,8 +35,9 @@ async function readChangeDirectoryEntries(changesDir) {
 /**
  * Get the most recent modification time of any file in a directory (recursive).
  * Falls back to the directory's own mtime if no files are found.
+ * Archived links use their own mtime: moving a change can break relative targets.
  */
-async function getLastModified(dirPath) {
+async function getLastModified(dirPath, archived = false) {
     let latest = null;
     async function walk(dir) {
         const entries = await fs.readdir(dir, { withFileTypes: true });
@@ -47,7 +48,9 @@ async function getLastModified(dirPath) {
                     await walk(fullPath);
                 }
                 else {
-                    const stat = await fs.stat(fullPath);
+                    const stat = archived && entry.isSymbolicLink()
+                        ? await fs.lstat(fullPath)
+                        : await fs.stat(fullPath);
                     if (latest === null || stat.mtime > latest) {
                         latest = stat.mtime;
                     }
@@ -96,20 +99,31 @@ function formatRelativeTime(date) {
 }
 export class ListCommand {
     async execute(targetPath = '.', mode = 'changes', options = {}) {
-        const { sort = 'recent', json = false, root } = options;
+        const { sort = 'recent', json = false, root, archived = false, all = false } = options;
+        if (mode === 'specs' && (archived || all)) {
+            throw new Error('--archived and --all can only be used when listing changes.');
+        }
         if (mode === 'changes') {
             const changesDir = path.join(targetPath, 'openspec', 'changes');
-            // Get all directories in changes (excluding archive)
+            const archiveDir = path.join(changesDir, 'archive');
+            const includeArchived = archived || all;
+            // Read the parent even for --archived: Windows can report ENOENT for
+            // changes/archive when changes is a file, hiding a malformed root.
             const entries = await readChangeDirectoryEntries(changesDir);
-            const changeDirs = entries
+            const activeDirs = !archived || all ? entries
                 .filter(entry => entry.isDirectory() && entry.name !== 'archive')
-                .map(entry => entry.name);
+                .map(entry => ({ name: entry.name, parent: changesDir, archived: false })) : [];
+            const archiveEntries = includeArchived ? await readChangeDirectoryEntries(archiveDir) : [];
+            const archivedDirs = archiveEntries
+                .filter(entry => entry.isDirectory() && !entry.name.startsWith('.'))
+                .map(entry => ({ name: entry.name, parent: archiveDir, archived: true }));
+            const changeDirs = [...activeDirs, ...archivedDirs];
             if (changeDirs.length === 0) {
                 if (json) {
                     console.log(JSON.stringify({ changes: [], ...(root ? { root } : {}) }, null, 2));
                 }
                 else {
-                    console.log('No active changes found.');
+                    console.log(all ? 'No changes found.' : archived ? 'No archived changes found.' : 'No active changes found.');
                 }
                 return;
             }
@@ -118,18 +132,21 @@ export class ListCommand {
             // A directory that only wraps nested change directories is still listed -
             // hiding it would hide a real change whenever the probe is wrong - but it
             // is listed as what it is, so the nesting stops failing silently (#1846).
-            const nestedFindings = await findNestedChanges(changesDir, changeDirs);
+            const nestedFindings = await findNestedChanges(changesDir, activeDirs.map((changeDir) => changeDir.name));
             const nestedByName = new Map(nestedFindings.map((finding) => [finding.name, finding]));
             for (const changeDir of changeDirs) {
-                const progress = await getTaskProgressForChange(changesDir, changeDir, targetPath);
-                const changePath = path.join(changesDir, changeDir);
-                const lastModified = await getLastModified(changePath);
+                const progress = await getTaskProgressForChange(changeDir.parent, changeDir.name, targetPath);
+                const changePath = path.join(changeDir.parent, changeDir.name);
+                const lastModified = await getLastModified(changePath, changeDir.archived);
                 changes.push({
-                    name: changeDir,
+                    name: changeDir.name,
                     completedTasks: progress.completed,
                     totalTasks: progress.total,
                     lastModified,
-                    ...(nestedByName.has(changeDir) ? { nested: nestedByName.get(changeDir).nested } : {})
+                    archived: changeDir.archived,
+                    ...(!changeDir.archived && nestedByName.has(changeDir.name)
+                        ? { nested: nestedByName.get(changeDir.name).nested }
+                        : {})
                 });
             }
             // Sort by preference (default: recent first)
@@ -147,6 +164,7 @@ export class ListCommand {
                     totalTasks: c.totalTasks,
                     lastModified: c.lastModified.toISOString(),
                     status: c.totalTasks === 0 ? 'no-tasks' : c.completedTasks === c.totalTasks ? 'complete' : 'in-progress',
+                    ...(includeArchived ? { archived: c.archived } : {}),
                     ...(c.nested ? { nested: c.nested } : {})
                 }));
                 // Additive: the entries keep their shape so existing consumers are
@@ -165,16 +183,24 @@ export class ListCommand {
                 return;
             }
             // Display results
-            console.log('Changes:');
-            const padding = '  ';
-            const nameWidth = Math.max(...changes.map(c => c.name.length));
-            for (const change of changes) {
-                const paddedName = change.name.padEnd(nameWidth);
-                const status = change.nested
-                    ? 'not a change'
-                    : formatTaskStatus({ total: change.totalTasks, completed: change.completedTasks });
-                const timeAgo = formatRelativeTime(change.lastModified);
-                console.log(`${padding}${paddedName}     ${status.padEnd(12)}  ${timeAgo}`);
+            const groups = [
+                { heading: 'Changes:', changes: changes.filter(change => !change.archived) },
+                { heading: 'Archived Changes:', changes: changes.filter(change => change.archived) }
+            ].filter(group => group.changes.length > 0);
+            for (const [index, group] of groups.entries()) {
+                if (index > 0)
+                    console.log('');
+                console.log(group.heading);
+                const padding = '  ';
+                const nameWidth = Math.max(...group.changes.map(c => c.name.length));
+                for (const change of group.changes) {
+                    const paddedName = change.name.padEnd(nameWidth);
+                    const status = change.nested
+                        ? 'not a change'
+                        : formatTaskStatus({ total: change.totalTasks, completed: change.completedTasks });
+                    const timeAgo = formatRelativeTime(change.lastModified);
+                    console.log(`${padding}${paddedName}     ${status.padEnd(12)}  ${timeAgo}`);
+                }
             }
             for (const finding of nestedFindings) {
                 console.log('');

package/dist/core/parsers/markdown-parser.js

@@ -1,4 +1,5 @@
 import { buildCodeFenceMask, extractRequirementText, hasScenarioBody } from './requirement-text.js';
+import { normalizeRequirementName, scenarioNameFromHeaderText } from './requirement-blocks.js';
 export class MarkdownParser {
     lines;
     codeFenceLineMask;
@@ -121,6 +122,9 @@ export class MarkdownParser {
             const text = extractRequirementText(child.title, child.content.split('\n'));
             const scenarios = this.parseScenarios(child);
             requirements.push({
+                // The name archive matches on, so a JSON reader can cite a requirement
+                // the way a MODIFIED or REMOVED header must.
+                name: normalizeRequirementName(child.title.replace(/^Requirement:\s*/i, '')),
                 text,
                 scenarios,
             });
@@ -134,6 +138,7 @@ export class MarkdownParser {
             // body is not a scenario; the delta counter applies the same rule.
             if (hasScenarioBody(scenarioSection.content)) {
                 scenarios.push({
+                    name: scenarioNameFromHeaderText(scenarioSection.title),
                     rawText: scenarioSection.content
                 });
             }