@fission-ai/openspec 1.13.1 → 1.14.0

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);
             }
@@ -992,9 +1016,15 @@ export class InitCommand {
                     // Tools with no slash surface (e.g. Rovo Dev) reference skills as
                     // prose ("the openspec-propose skill"); phrase the hint so it reads
                     // as an instruction rather than a dead command with an argument.
-                    hint = usesNaturalLanguageSkillReferences(tool.value)
-                        ? `Start your first change: ask ${tool.name} to use ${skillReference} with "your idea"`
-                        : `Start your first change: ${skillReference} "your idea"`;
+                    if (usesNaturalLanguageSkillReferences(tool.value)) {
+                        hint = `Start your first change: ask ${tool.name} to use ${skillReference} with "your idea"`;
+                    }
+                    else if (tool.value === 'codex') {
+                        hint = `Start your first change: ${skillReference} "your idea" (Codex CLI or IDE); in the Codex desktop app, select ${skillReference.slice(1)} from Skills in the sidebar`;
+                    }
+                    else {
+                        hint = `Start your first change: ${skillReference} "your idea"`;
+                    }
                 }
                 else {
                     continue;

package/dist/core/legacy-cleanup.d.ts

@@ -2,7 +2,7 @@
  * Legacy cleanup module for detecting and removing OpenSpec artifacts
  * from previous init versions during the migration to the skill-based workflow.
  */
-import type { WorkflowId } from './profiles.js';
+import { type WorkflowId } from './profiles.js';
 /**
  * Legacy config file names from the old ToolRegistry.
  * These were config files created at project root with OpenSpec markers.

package/dist/core/legacy-cleanup.js

@@ -4,10 +4,11 @@
  */
 import path from 'path';
 import os from 'os';
-import { promises as fs } from 'fs';
+import { promises as fs, constants as fsConstants } from 'fs';
 import chalk from 'chalk';
 import { FileSystemUtils, removeMarkerBlock as removeMarkerBlockUtil } from '../utils/file-system.js';
 import { OPENSPEC_MARKERS } from './config.js';
+import { ALL_WORKFLOWS } from './profiles.js';
 /**
  * Legacy config file names from the old ToolRegistry.
  * These were config files created at project root with OpenSpec markers.
@@ -24,6 +25,13 @@ export const LEGACY_CONFIG_FILES = [
 ];
 /** The three commands the old SlashCommandRegistry wrote into each directory. */
 const LEGACY_DIRECTORY_COMMAND_FILES = ['proposal.md', 'apply.md', 'archive.md'];
+/** Exact Kilo workflow files written by OpenSpec before the command path moved. */
+const LEGACY_KILOCODE_COMMAND_FILES = [
+    ...ALL_WORKFLOWS.map(workflow => `.kilocode/workflows/opsx-${workflow}.md`),
+    '.kilocode/workflows/openspec-proposal.md',
+    '.kilocode/workflows/openspec-apply.md',
+    '.kilocode/workflows/openspec-archive.md',
+];
 /**
  * Legacy slash command patterns from the old SlashCommandRegistry.
  * These map toolId to the path pattern where legacy commands were created.
@@ -48,7 +56,12 @@ export const LEGACY_SLASH_COMMAND_PATHS = {
     // belong to `devin` — the id Windsurf became. Only `.windsurf/` is listed:
     // `.devin/` postdates the opsx rename and never held `openspec-*` files.
     'devin': { type: 'files', pattern: '.windsurf/workflows/openspec-*.md' },
-    'kilocode': { type: 'files', pattern: '.kilocode/workflows/openspec-*.md' },
+    // Kilo now writes commands under `.kilo/command/`. Clean up both generations
+    // of OpenSpec workflows from Kilo's legacy `.kilocode/workflows/` folder.
+    'kilocode': {
+        type: 'files',
+        pattern: LEGACY_KILOCODE_COMMAND_FILES,
+    },
     'kiro': { type: 'files', pattern: '.kiro/prompts/openspec-*.prompt.md' },
     'github-copilot': { type: 'files', pattern: '.github/prompts/openspec-*.prompt.md' },
     'amazon-q': { type: 'files', pattern: '.amazonq/prompts/openspec-*.md' },
@@ -331,15 +344,27 @@ async function settleLegacyCommandDir(projectPath, dirPath, result) {
  * a same-named file without them is the user's.
  */
 async function isGeneratedLegacyCommand(filePath) {
+    // Judge the opened handle, not the path, so the file checked is the file
+    // read. O_NOFOLLOW refuses a link and O_NONBLOCK keeps a FIFO from hanging;
+    // Windows has neither flag, so a link is refused there by lstat instead.
+    const { O_RDONLY, O_NOFOLLOW, O_NONBLOCK } = fsConstants;
+    let handle;
     try {
-        if (!(await fs.lstat(filePath)).isFile()) {
+        handle = await fs.open(filePath, O_RDONLY | (O_NOFOLLOW ?? 0) | (O_NONBLOCK ?? 0));
+        if (O_NOFOLLOW === undefined && (await fs.lstat(filePath)).isSymbolicLink()) {
+            return false;
+        }
+        if (!(await handle.stat()).isFile()) {
             return false;
         }
-        return hasOpenSpecMarkers(await fs.readFile(filePath, 'utf-8'));
+        return hasOpenSpecMarkers(await handle.readFile('utf-8'));
     }
     catch {
         return false;
     }
+    finally {
+        await handle?.close();
+    }
 }
 /**
  * Detects legacy global slash command files.
@@ -720,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}`);
         }
@@ -928,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 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 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 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
                 });
             }

package/dist/core/parsers/requirement-blocks.d.ts

@@ -95,14 +95,51 @@ export interface DeltaPlan {
  * Parse a delta-formatted spec change file content into a DeltaPlan with raw blocks.
  */
 export declare function parseDeltaSpec(content: string): DeltaPlan;
+/** Both directions of the scenario-name comparison, plus the two totals. */
+export interface ScenarioNameDiff {
+    /** Names the current block has that the incoming block does not cover. */
+    missing: string[];
+    /** Names the incoming block introduces that the current block does not have. */
+    added: string[];
+    /** Level-4 headers in the current block. */
+    currentCount: number;
+    /** Level-4 headers in the incoming block. */
+    incomingCount: number;
+}
+/**
+ * Compare the scenario names of a current requirement block and an incoming
+ * (MODIFIED) one, in both directions.
+ *
+ * `missing` is the loss the guard exists to catch: a MODIFIED requirement
+ * replaces the whole block, so every name there would be dropped from the main
+ * spec. `added` and the two counts are reported alongside it, because they are
+ * the first thing a reader checks once it fires (#1697) - a block that omits
+ * two names and introduces two is shaped like a rename, one that omits two and
+ * introduces none is shaped like a truncation. Neither is proof, and intent is
+ * not recoverable from structure, so this decides nothing and only says what
+ * the two blocks contain.
+ */
+export declare function diffScenarioNames(current: RequirementBlock, incoming: RequirementBlock): ScenarioNameDiff;
 /**
  * Scenario names the current requirement block has and the incoming
  * (MODIFIED) block does not. A MODIFIED requirement replaces the whole block,
  * so every name reported here would be dropped from the main spec.
  *
- * Shared by archive (which refuses to apply the block) and validate (which
- * reports the same loss at authoring time, #1477), so the two cannot disagree
- * about what counts as a dropped scenario.
+ * The `missing` half of diffScenarioNames, which archive (refusing to apply
+ * the block) and validate (reporting the same loss at authoring time, #1477)
+ * both go through, so the two cannot disagree about what counts as a dropped
+ * scenario.
  */
 export declare function findMissingCurrentScenarios(current: RequirementBlock, incoming: RequirementBlock): string[];
+/**
+ * The one sentence archive and validate both append when the guard fires, so
+ * the counts a reader sees cannot differ between the two commands.
+ */
+export declare function describeScenarioBalance(diff: ScenarioNameDiff): string;
+/**
+ * scenarioNameAt for header text whose leading `####` is already gone, as the
+ * section parser (MarkdownParser) holds it, so `show --json` names a scenario
+ * exactly as the MODIFIED loss check does.
+ */
+export declare function scenarioNameFromHeaderText(headerText: string): string;
 //# sourceMappingURL=requirement-blocks.d.ts.map

package/dist/core/parsers/requirement-blocks.js

@@ -380,37 +380,79 @@ function parseRenamedPairs(sectionBody, unpaired) {
         drop('FROM', pending.name, pending.line);
     return pairs;
 }
+/**
+ * Compare the scenario names of a current requirement block and an incoming
+ * (MODIFIED) one, in both directions.
+ *
+ * `missing` is the loss the guard exists to catch: a MODIFIED requirement
+ * replaces the whole block, so every name there would be dropped from the main
+ * spec. `added` and the two counts are reported alongside it, because they are
+ * the first thing a reader checks once it fires (#1697) - a block that omits
+ * two names and introduces two is shaped like a rename, one that omits two and
+ * introduces none is shaped like a truncation. Neither is proof, and intent is
+ * not recoverable from structure, so this decides nothing and only says what
+ * the two blocks contain.
+ */
+export function diffScenarioNames(current, incoming) {
+    const currentNames = parseScenarioBlocks(current.raw).map((scenario) => scenario.name);
+    const incomingNames = parseScenarioBlocks(incoming.raw).map((scenario) => scenario.name);
+    // Multiplicity-aware: a name present N times on one side and M times on the
+    // other leaves max(0, N - M) instances unmatched. Set membership would treat
+    // N>M as fully covered and let archive silently drop duplicates (residual
+    // #1246 / duplicate-scenario-name blind spot).
+    const unmatched = (names, against) => {
+        const remaining = new Map();
+        for (const name of against)
+            remaining.set(name, (remaining.get(name) ?? 0) + 1);
+        const out = [];
+        for (const name of names) {
+            const left = remaining.get(name) ?? 0;
+            if (left > 0)
+                remaining.set(name, left - 1);
+            else
+                out.push(name);
+        }
+        return out;
+    };
+    return {
+        missing: unmatched(currentNames, incomingNames),
+        added: unmatched(incomingNames, currentNames),
+        currentCount: currentNames.length,
+        incomingCount: incomingNames.length,
+    };
+}
 /**
  * Scenario names the current requirement block has and the incoming
  * (MODIFIED) block does not. A MODIFIED requirement replaces the whole block,
  * so every name reported here would be dropped from the main spec.
  *
- * Shared by archive (which refuses to apply the block) and validate (which
- * reports the same loss at authoring time, #1477), so the two cannot disagree
- * about what counts as a dropped scenario.
+ * The `missing` half of diffScenarioNames, which archive (refusing to apply
+ * the block) and validate (reporting the same loss at authoring time, #1477)
+ * both go through, so the two cannot disagree about what counts as a dropped
+ * scenario.
  */
 export function findMissingCurrentScenarios(current, incoming) {
-    // Multiplicity-aware: a name present N times in current and M times in
-    // incoming means max(0, N - M) instances are missing. Set membership would
-    // treat N>M as fully covered and let archive silently drop duplicates
-    // (residual #1246 / duplicate-scenario-name blind spot).
-    const remainingIncoming = new Map();
-    for (const scenario of parseScenarioBlocks(incoming.raw)) {
-        const name = scenario.name;
-        remainingIncoming.set(name, (remainingIncoming.get(name) ?? 0) + 1);
-    }
-    const missing = [];
-    for (const scenario of parseScenarioBlocks(current.raw)) {
-        const name = scenario.name;
-        const remaining = remainingIncoming.get(name) ?? 0;
-        if (remaining > 0) {
-            remainingIncoming.set(name, remaining - 1);
-        }
-        else {
-            missing.push(name);
-        }
+    return diffScenarioNames(current, incoming).missing;
+}
+/** At most this many added names are listed before the rest are counted. */
+const MAX_LISTED_ADDED_SCENARIOS = 3;
+/**
+ * The one sentence archive and validate both append when the guard fires, so
+ * the counts a reader sees cannot differ between the two commands.
+ */
+export function describeScenarioBalance(diff) {
+    const count = (value) => `${value} ${value === 1 ? 'scenario' : 'scenarios'}`;
+    const scale = `The modified block has ${count(diff.incomingCount)}; the current spec has ${count(diff.currentCount)}.`;
+    if (diff.added.length === 0) {
+        return `${scale} It adds none.`;
     }
-    return missing;
+    const listed = diff.added
+        .slice(0, MAX_LISTED_ADDED_SCENARIOS)
+        .map((name) => `"${name}"`)
+        .join(', ');
+    const rest = diff.added.length - MAX_LISTED_ADDED_SCENARIOS;
+    const names = rest > 0 ? `${listed} and ${rest} more` : listed;
+    return `${scale} It adds ${count(diff.added.length)} not in the current spec: ${names}.`;
 }
 /**
  * Any non-fenced level-4 header on the given (masked) line. Reuses the spec
@@ -429,8 +471,15 @@ function scenarioHeaderAt(lines, mask, index) {
  * ATX-closed, one not) are not mistaken for a dropped scenario.
  */
 function scenarioNameAt(line) {
-    return line
-        .replace(SCENARIO_HEADER, '')
+    return scenarioNameFromHeaderText(line.replace(SCENARIO_HEADER, ''));
+}
+/**
+ * scenarioNameAt for header text whose leading `####` is already gone, as the
+ * section parser (MarkdownParser) holds it, so `show --json` names a scenario
+ * exactly as the MODIFIED loss check does.
+ */
+export function scenarioNameFromHeaderText(headerText) {
+    return headerText
         // Optional ATX closing sequence. CommonMark only treats a trailing `#` run
         // as a close when it is preceded by a space or tab — not any Unicode space —
         // so this uses `[ \t]`, not `\s`. A looser `\s` could strip a `#` run after