@fission-ai/openspec 1.10.0 → 1.11.0

package/dist/core/completions/types.d.ts

@@ -19,6 +19,10 @@ export interface FlagDefinition {
      * Whether the flag takes an argument value
      */
     takesValue?: boolean;
+    /**
+     * Completion type for the flag value.
+     */
+    completionType?: PositionalType;
     /**
      * Possible values for the flag (for completion suggestions)
      */

package/dist/core/config.js

@@ -19,7 +19,12 @@ 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: 'Antigravity', value: 'antigravity', available: true, successLabel: 'Antigravity', skillsDir: '.agent', requiresIdeRestart: true },
+    // 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: 'Auggie (Augment CLI)', value: 'auggie', available: true, successLabel: 'Auggie', skillsDir: '.augment' },
     { name: 'Bob Shell', value: 'bob', available: true, successLabel: 'Bob Shell', skillsDir: '.bob' },
     { name: 'Claude Code', value: 'claude', available: true, successLabel: 'Claude Code', skillsDir: '.claude' },

package/dist/core/init.js

@@ -23,7 +23,7 @@ import { getToolsWithSkillsDir, getToolStates, getSkillTemplates, getCommandCont
 import { getGlobalConfig } from './global-config.js';
 import { getProfileWorkflows, ALL_WORKFLOWS } from './profiles.js';
 import { getAvailableTools } from './available-tools.js';
-import { writeSharedSkillTarget } from './shared-skill-target.js';
+import { resolveSharedSkillWriters, sharedSkillRootOwner, writeSharedSkillTarget, } from './shared-skill-target.js';
 import { migrateIfNeeded, migrateLegacyToolDirs, describeLegacyMigration, keptInPlaceNotice, hasMovableContent, scanInstalledWorkflows as scanInstalledWorkflowsShared } from './migration.js';
 import { resolveCommandSurfaceCapability, resolveCommandInvocation, shouldGenerateCommandsForTool, shouldGenerateSkillsForTool, shouldReconcileCommandFilesForTool, shouldRemoveSkillsForTool, } from './command-surface.js';
 import { writeCopilotCloudFiles, readCopilotCloudOptIn, hasExistingManagedCloudFiles, persistCopilotCloudOptIn, removeCopilotCloudFiles, findUnmanagedCloudFiles, listManagedCloudFiles, } from './github-copilot/cloud-agent.js';
@@ -526,34 +526,8 @@ export class InitCommand {
         return deduped;
     }
     validateTools(toolIds, toolStates, projectPath) {
-        const validatedTools = [];
-        const sharedAgentsTargets = ['codex', 'zed', 'agents'];
-        const selectedSharedTargets = sharedAgentsTargets.filter((toolId) => toolIds.includes(toolId));
-        // A Codex-rendered tree already serves Zed. Keep it when Zed is added later
-        // so Codex users do not lose the `$openspec-*` references they require.
-        const preserveConfiguredCodex = selectedSharedTargets.includes('zed') &&
-            toolStates.get('codex')?.configured;
-        const sharedTargetCandidates = preserveConfiguredCodex
-            ? [...new Set([...selectedSharedTargets, 'codex'])]
-            : selectedSharedTargets;
-        const sharedTargetOwner = sharedTargetCandidates.includes('codex')
-            ? 'codex'
-            : selectedSharedTargets.includes('zed')
-                ? 'zed'
-                : selectedSharedTargets[0];
-        const firstSharedIndex = toolIds.findIndex((id) => sharedAgentsTargets.includes(id));
-        const reconciledToolIds = sharedTargetCandidates.length > 1
-            ? toolIds.flatMap((toolId, index) => {
-                if (!sharedAgentsTargets.includes(toolId))
-                    return [toolId];
-                return index === firstSharedIndex && sharedTargetOwner ? [sharedTargetOwner] : [];
-            })
-            : toolIds;
-        if (reconciledToolIds.length !== toolIds.length ||
-            reconciledToolIds.some((toolId, index) => toolId !== toolIds[index])) {
-            console.log(chalk.dim(`Codex, Zed, and agents share .agents/skills; writing one tree for ${sharedTargetOwner}.`));
-        }
-        for (const toolId of reconciledToolIds) {
+        const selectedTools = [];
+        for (const toolId of toolIds) {
             const tool = AI_TOOLS.find((t) => t.value === toolId);
             if (!tool) {
                 const validToolIds = getToolsWithSkillsDir();
@@ -563,6 +537,48 @@ export class InitCommand {
                 const validToolsWithSkills = getToolsWithSkillsDir();
                 throw new Error(`Tool '${toolId}' does not support skill generation.\nTools with skill generation support:\n  ${validToolsWithSkills.join('\n  ')}`);
             }
+            selectedTools.push(tool);
+        }
+        // A selected tool may share its physical skills root with an already
+        // configured owner. Include that owner in the refresh without dropping the
+        // selected tool: it may still have an independent command surface.
+        const generationTools = [...selectedTools];
+        const delivery = getGlobalConfig().delivery ?? 'both';
+        for (const selected of selectedTools) {
+            if (!selected.skillsDir)
+                continue;
+            const selectedOwner = selected.value === 'codex' ||
+                !shouldGenerateSkillsForTool(selected.value, delivery)
+                ? undefined
+                : sharedSkillRootOwner(projectPath, selected.value);
+            for (const candidate of AI_TOOLS) {
+                if (candidate.skillsDir === selected.skillsDir &&
+                    toolStates.get(candidate.value)?.configured &&
+                    candidate.value === selectedOwner &&
+                    !generationTools.includes(candidate)) {
+                    generationTools.push(candidate);
+                }
+            }
+        }
+        const skillWriters = resolveSharedSkillWriters(projectPath, generationTools);
+        const sharedRoots = new Map();
+        for (const tool of generationTools) {
+            if (!tool.skillsDir)
+                continue;
+            const group = sharedRoots.get(tool.skillsDir) ?? [];
+            group.push(tool);
+            sharedRoots.set(tool.skillsDir, group);
+        }
+        for (const [root, group] of sharedRoots) {
+            if (group.length < 2)
+                continue;
+            const owner = group.find((tool) => skillWriters.has(tool.value));
+            console.log(chalk.dim(`${group.map((tool) => tool.name).join(', ')} share ${root}/skills; writing one tree for ${owner?.value}.`));
+        }
+        const validatedTools = [];
+        for (const tool of generationTools) {
+            if (!toolSupportsSkills(tool))
+                continue;
             const preState = toolStates.get(tool.value);
             const skillsPath = resolveToolSkillsDir(projectPath, tool);
             const isGlobalSkillTarget = hasGlobalSkillTarget(tool);
@@ -575,6 +591,7 @@ export class InitCommand {
                 isGlobalSkillTarget,
                 wasConfigured: preState?.configured ?? false,
                 requiresIdeRestart: tool.requiresIdeRestart,
+                writesSkills: !tool.skillsDir || skillWriters.has(tool.value),
             });
         }
         return validatedTools;
@@ -648,7 +665,7 @@ export class InitCommand {
                 const shouldGenerateSkills = shouldGenerateSkillsForTool(tool.value, delivery);
                 const shouldGenerateCommands = shouldGenerateCommandsForTool(tool.value, delivery);
                 // Generate skill files if the selected delivery and tool capability allow skills
-                if (shouldGenerateSkills) {
+                if (shouldGenerateSkills && tool.writesSkills) {
                     // Create skill directories and SKILL.md files
                     for (const { template, dirName } of skillTemplates) {
                         const skillDir = path.join(tool.skillsPath, dirName);
@@ -662,7 +679,9 @@ export class InitCommand {
                     }
                     writeSharedSkillTarget(projectPath, tool.value);
                 }
-                if (shouldRemoveSkillsForTool(tool.value, delivery) && !tool.isGlobalSkillTarget) {
+                if (shouldRemoveSkillsForTool(tool.value, delivery) &&
+                    tool.writesSkills &&
+                    !tool.isGlobalSkillTarget) {
                     removedSkillCount += await this.removeSkillDirs(tool.skillsRoot, tool.skillsPath);
                     // Retain an explicit selection even when this delivery mode produces
                     // no skills, so a divergent legacy sibling cannot reclaim ownership.

package/dist/core/legacy-cleanup.js

@@ -51,6 +51,12 @@ export const LEGACY_SLASH_COMMAND_PATHS = {
     'factory': { type: 'files', pattern: '.factory/commands/openspec-*.md' },
     'opencode': { type: 'files', pattern: ['.opencode/command/opsx-*.md', '.opencode/command/openspec-*.md'] },
     'continue': { type: 'files', pattern: '.continue/prompts/openspec-*.prompt' },
+    // Scoped to the pre-opsx filenames under Antigravity's former `.agent` root.
+    // The current `.agents/workflows/opsx-*.md` files postdate that rename, and
+    // the `.agent` copies of them are relocated by LEGACY_TOOL_ROOTS, which
+    // preserves a customized file instead of deleting it. These patterns are
+    // matched in every project, so a shared root like `.agents` is not listed:
+    // OpenSpec never wrote `openspec-*` files there, and a user might have.
     'antigravity': { type: 'files', pattern: '.agent/workflows/openspec-*.md' },
     'iflow': { type: 'files', pattern: '.iflow/commands/openspec-*.md' },
     'qwen': { type: 'files', pattern: ['.qwen/commands/opsx-*.toml', '.qwen/commands/openspec-*.toml'] },

package/dist/core/migration.js

@@ -34,6 +34,12 @@ export const LEGACY_TOOL_ROOTS = {
     // Codex now reads the canonical shared .agents root. Generate the current
     // replacement first so a divergent legacy file is preserved, not overwritten.
     codex: [{ root: '.codex', needsConsent: false, timing: 'after-generation' }],
+    // Antigravity v1.20.5 moved workspace skills and workflows to `.agents` and
+    // reads the old `.agent` root only as a fallback, so leaving a copy there
+    // just gives the agent two of everything. Same after-generation timing as
+    // Codex: the replacement is written first, so a divergent legacy file is
+    // reported and kept rather than overwritten.
+    antigravity: [{ root: '.agent', needsConsent: false, timing: 'after-generation' }],
 };
 function classifyManagedFile(source, destination) {
     if (isSamePath(source, destination))
@@ -121,7 +127,7 @@ function collectLegacyToolMigrations(projectPath, apply, toolIds, timing = 'befo
                 continue;
             }
             const skills = migrateSkillDirs(projectPath, tool.skillsDir, legacy.root, apply, legacyTiming === 'after-generation');
-            const commands = migrateCommandFiles(projectPath, tool, legacy.root, apply);
+            const commands = migrateCommandFiles(projectPath, tool, legacy.root, apply, legacyTiming === 'after-generation');
             if (apply) {
                 removeDirIfEmpty(path.join(legacyRootPath, 'skills'));
                 removeDirIfEmpty(path.join(legacyRootPath, 'workflows'));
@@ -201,7 +207,7 @@ function migrateSkillDirs(projectPath, currentRoot, legacyRoot, apply, requireDe
     }
     return { moved, kept };
 }
-function migrateCommandFiles(projectPath, tool, legacyRoot, apply) {
+function migrateCommandFiles(projectPath, tool, legacyRoot, apply, requireDestination = false) {
     const adapter = CommandAdapterRegistry.get(tool.value);
     if (!adapter || !tool.skillsDir)
         return { moved: 0, kept: 0 };
@@ -212,10 +218,16 @@ function migrateCommandFiles(projectPath, tool, legacyRoot, apply) {
         const legacyPath = legacyCommandPath(currentPath, tool.skillsDir, legacyRoot);
         if (!legacyPath)
             continue;
-        const source = path.join(projectPath, legacyPath);
+        const source = FileSystemUtils.resolveProjectArtifactPath(projectPath, legacyPath);
         if (!fs.existsSync(source))
             continue;
-        const destination = path.join(projectPath, currentPath);
+        const destination = FileSystemUtils.resolveProjectArtifactPath(projectPath, currentPath.split(/[\\/]/).join(path.sep));
+        // An after-generation move runs once the tool has written its replacement.
+        // No replacement means this command is not one OpenSpec installs now — a
+        // skills-only delivery or a deselected workflow — so relocating the legacy
+        // file would resurrect it under the current root.
+        if (requireDestination && !fs.existsSync(destination))
+            continue;
         if (!areProjectArtifacts(projectPath, source, destination)) {
             console.warn(`Skipping legacy ${legacyPath} migration because it resolves outside this project.`);
             continue;
@@ -332,7 +344,7 @@ function removeDirIfEmpty(dirPath) {
         // Missing or non-empty directory — nothing to do
     }
 }
-function scanInstalledWorkflowArtifacts(projectPath, tools, includeLegacySkills = false) {
+function scanInstalledWorkflowArtifacts(projectPath, tools, includeLegacyRoots = false) {
     const installed = new Set();
     let hasSkills = false;
     let hasCommands = false;
@@ -345,7 +357,7 @@ function scanInstalledWorkflowArtifacts(projectPath, tools, includeLegacySkills
         }
         else if (isSharedSkillTargetActive(projectPath, tool.value)) {
             skillsDirs.push(resolveToolSkillsDir(projectPath, tool));
-            if (includeLegacySkills) {
+            if (includeLegacyRoots) {
                 skillsDirs.push(...(tool.legacySkillsDirs ?? []).map((root) => path.join(projectPath, root, 'skills')));
             }
         }
@@ -362,14 +374,32 @@ function scanInstalledWorkflowArtifacts(projectPath, tools, includeLegacySkills
         const adapter = CommandAdapterRegistry.get(tool.value);
         if (!adapter)
             continue;
+        // A root the tool has moved away from still holds the command files the
+        // user installed there. Reading only the current root would report a
+        // commands install as skills-only, and delivery inferred from that answer
+        // deletes those commands on the next update.
+        const legacyRoots = includeLegacyRoots
+            ? (LEGACY_TOOL_ROOTS[tool.value] ?? []).map((legacy) => legacy.root)
+            : [];
         for (const workflowId of ALL_WORKFLOWS) {
             const commandPath = adapter.getFilePath(workflowId);
-            const fullPath = path.isAbsolute(commandPath)
-                ? commandPath
-                : path.join(projectPath, commandPath);
-            if (fs.existsSync(fullPath)) {
-                installed.add(workflowId);
-                hasCommands = true;
+            const candidates = [commandPath];
+            if (tool.skillsDir) {
+                for (const root of legacyRoots) {
+                    const legacyPath = legacyCommandPath(commandPath, tool.skillsDir, root);
+                    if (legacyPath)
+                        candidates.push(legacyPath);
+                }
+            }
+            for (const candidate of candidates) {
+                const fullPath = path.isAbsolute(candidate)
+                    ? candidate
+                    : path.join(projectPath, candidate);
+                if (fs.existsSync(fullPath)) {
+                    installed.add(workflowId);
+                    hasCommands = true;
+                    break;
+                }
             }
         }
     }

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

@@ -37,6 +37,7 @@ export interface DeltaPlan {
     added: RequirementBlock[];
     modified: RequirementBlock[];
     removed: string[];
+    removedBlocks: RequirementBlock[];
     renamed: Array<{
         from: string;
         to: string;

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

@@ -115,12 +115,14 @@ export function parseDeltaSpec(content) {
         sink: skippedHeaders,
     });
     const removedNames = parseRemovedNames(removedLookup.body);
+    const removedBlocks = parseRequirementBlocksFromSection(removedLookup.body);
     const renamedPairs = parseRenamedPairs(renamedLookup.body);
     skippedHeaders.sort((a, b) => a.line - b.line);
     return {
         added,
         modified,
         removed: removedNames,
+        removedBlocks,
         renamed: renamedPairs,
         skippedHeaders,
         sectionPresence: {

package/dist/core/shared/tool-detection.js

@@ -10,8 +10,8 @@ import { CommandAdapterRegistry, generateCommands } from '../command-generation/
 import { getCommandContents } from './skill-generation.js';
 import { getGlobalConfig } from '../global-config.js';
 import { getProfileWorkflows, ALL_WORKFLOWS } from '../profiles.js';
-import { isSharedSkillTargetActive, readSharedSkillTarget, reconcileSharedSkillTargets, } from '../shared-skill-target.js';
-import { shouldGenerateCommandsForTool, shouldGenerateSkillsForTool, } from '../command-surface.js';
+import { isSharedSkillTargetActive, hasLegacySkills, readSharedSkillTarget, reconcileSharedSkillTargets, } from '../shared-skill-target.js';
+import { shouldGenerateCommandsForTool, shouldGenerateSkillsForTool, resolveCommandSurfaceCapability, } from '../command-surface.js';
 import { getSkillCapableTools, resolveToolSkillsDir, toolSupportsSkills, } from './skill-paths.js';
 /**
  * Names of skill directories created by openspec init.
@@ -272,12 +272,18 @@ export function getConfiguredTools(projectRoot) {
             return false;
         return (getToolSkillStatus(projectRoot, t.value).configured ||
             toolHasAnyConfiguredCommand(projectRoot, t.value) ||
+            (resolveCommandSurfaceCapability(t.value) === 'adapter-backed' &&
+                hasLegacySkills(projectRoot, t)) ||
             (Boolean(t.skillsDir) &&
                 readSharedSkillTarget(projectRoot, t.skillsDir) === t.value));
     });
     const activeProjectTools = new Set(reconcileSharedSkillTargets(projectRoot, configured.filter((tool) => tool.skillsDir)).map((tool) => tool.value));
     return configured
-        .filter((tool) => tool.globalSkillsDir || activeProjectTools.has(tool.value))
+        .filter((tool) => tool.globalSkillsDir ||
+        toolHasAnyConfiguredCommand(projectRoot, tool.value) ||
+        (resolveCommandSurfaceCapability(tool.value) === 'adapter-backed' &&
+            hasLegacySkills(projectRoot, tool)) ||
+        activeProjectTools.has(tool.value))
         .map((tool) => tool.value);
 }
 /**

package/dist/core/shared-skill-target.d.ts

@@ -1,6 +1,19 @@
 import { type AIToolOption } from './config.js';
 /** Reads a valid-looking marker value without letting linked roots escape. */
 export declare function readSharedSkillTarget(projectPath: string, skillsDir: string): string | undefined;
+/** Whether a tool still has an allowlisted managed skill under an old root. */
+export declare function hasLegacySkills(projectPath: string, tool: AIToolOption): boolean;
+/**
+ * Chooses the one selected tool that may render each physical skills root.
+ * Command files are not part of this arbitration: tools that share a skills
+ * root can still write their own command surface elsewhere under that root.
+ *
+ * Existing compatible owners win. On a new root, prefer a skills-native
+ * renderer over an adapter-backed renderer because its references remain
+ * usable by every consumer of the shared tree. Codex is the best fresh owner
+ * because its renderer includes both Codex and generic skill invocation forms.
+ */
+export declare function resolveSharedSkillWriters(projectPath: string, tools: AIToolOption[]): Set<string>;
 /**
  * A shared skill root can only hold one rendered variant of each skill.
  * Keep the writer recorded so later updates do not infer every tool that

package/dist/core/shared-skill-target.js

@@ -2,6 +2,7 @@ import path from 'path';
 import * as fs from 'fs';
 import { AI_TOOLS, OPENSPEC_SKILL_NAMES } from './config.js';
 import { FileSystemUtils } from '../utils/file-system.js';
+import { resolveCommandSurfaceCapability } from './command-surface.js';
 const TARGET_MARKER = '.openspec-target';
 /** Returns the ownership-marker path for one shared skills root. */
 function markerPath(projectPath, skillsDir) {
@@ -19,7 +20,7 @@ export function readSharedSkillTarget(projectPath, skillsDir) {
     }
 }
 /** Whether a tool still has an allowlisted managed skill under an old root. */
-function hasLegacySkills(projectPath, tool) {
+export function hasLegacySkills(projectPath, tool) {
     return (tool.legacySkillsDirs ?? []).some((root) => {
         const skillsDir = path.join(projectPath, root, 'skills');
         return OPENSPEC_SKILL_NAMES.some((skillName) => {
@@ -69,6 +70,47 @@ function hasCurrentSkills(projectPath, skillsDir) {
         }
     });
 }
+/**
+ * Chooses the one selected tool that may render each physical skills root.
+ * Command files are not part of this arbitration: tools that share a skills
+ * root can still write their own command surface elsewhere under that root.
+ *
+ * Existing compatible owners win. On a new root, prefer a skills-native
+ * renderer over an adapter-backed renderer because its references remain
+ * usable by every consumer of the shared tree. Codex is the best fresh owner
+ * because its renderer includes both Codex and generic skill invocation forms.
+ */
+export function resolveSharedSkillWriters(projectPath, tools) {
+    const byRoot = new Map();
+    const writers = new Set();
+    for (const tool of tools) {
+        if (!tool.skillsDir)
+            continue;
+        const group = byRoot.get(tool.skillsDir) ?? [];
+        group.push(tool);
+        byRoot.set(tool.skillsDir, group);
+    }
+    for (const [root, unsortedGroup] of byRoot) {
+        const group = [...unsortedGroup].sort((left, right) => AI_TOOLS.indexOf(left) - AI_TOOLS.indexOf(right));
+        if (group.length === 1) {
+            writers.add(group[0].value);
+            continue;
+        }
+        const skillsNative = group.filter((tool) => resolveCommandSurfaceCapability(tool.value) !== 'adapter-backed');
+        const preferredPool = skillsNative.length > 0 ? skillsNative : group;
+        const marked = readSharedSkillTarget(projectPath, root);
+        const inferred = inferSharedSkillTarget(projectPath, root);
+        const owner = preferredPool.find((tool) => tool.value === marked) ??
+            preferredPool.find((tool) => tool.value === inferred) ??
+            (hasCurrentSkills(projectPath, root)
+                ? preferredPool.find((tool) => tool.value === 'agents')
+                : undefined) ??
+            preferredPool.find((tool) => tool.value === 'codex') ??
+            preferredPool[0];
+        writers.add(owner.value);
+    }
+    return writers;
+}
 /**
  * A shared skill root can only hold one rendered variant of each skill.
  * Keep the writer recorded so later updates do not infer every tool that

package/dist/core/specs-apply.js

@@ -12,7 +12,7 @@ import { extractRequirementsSection, findMissingCurrentScenarios, foldRequiremen
 import { findMainSpecStructureIssues } from './parsers/spec-structure.js';
 import { buildCodeFenceMask } from './parsers/code-fence.js';
 import { MarkdownParser } from './parsers/markdown-parser.js';
-import { MIN_PURPOSE_LENGTH } from './validation/constants.js';
+import { MIN_PURPOSE_LENGTH, PURPOSE_PLACEHOLDER_PREFIX, PURPOSE_PLACEHOLDER_SUFFIX, } from './validation/constants.js';
 import { discoverSpecFiles } from '../utils/spec-discovery.js';
 import { FileSystemUtils } from '../utils/file-system.js';
 function isLexicallyWithin(allowedDirectory, targetPath) {
@@ -254,10 +254,12 @@ export async function buildUpdatedSpec(update, changeName, options = {}) {
     for (const block of parts.bodyBlocks) {
         nameToBlock.set(normalizeRequirementName(block.name), block);
     }
+    // Keep source blocks immutable for loss attribution. This parallel key list
+    // carries only positional identity as renames change lookup keys.
+    const orderedKeys = parts.bodyBlocks.map((block) => normalizeRequirementName(block.name));
     // Apply operations in order: RENAMED → REMOVED → MODIFIED → ADDED
     // RENAMED
     let renamedApplied = 0;
-    const renamedTargets = new Map();
     for (const r of plan.renamed) {
         const from = normalizeRequirementName(r.from);
         const to = normalizeRequirementName(r.to);
@@ -291,7 +293,12 @@ export async function buildUpdatedSpec(update, changeName, options = {}) {
         };
         nameToBlock.delete(from);
         nameToBlock.set(to, renamedBlock);
-        renamedTargets.set(from, to);
+        // A Map delete+set moves the renamed block to insertion-order tail. Carry
+        // its new key in the source slot instead; chained renames update it again.
+        const orderIndex = orderedKeys.indexOf(from);
+        if (orderIndex >= 0) {
+            orderedKeys[orderIndex] = to;
+        }
         renamedApplied++;
     }
     // REMOVED
@@ -364,8 +371,9 @@ export async function buildUpdatedSpec(update, changeName, options = {}) {
     // Recompose requirements section preserving original ordering where possible
     const keptOrder = [];
     const seen = new Set();
-    for (const block of parts.bodyBlocks) {
-        const key = normalizeRequirementName(block.name);
+    for (let index = 0; index < parts.bodyBlocks.length; index++) {
+        const block = parts.bodyBlocks[index];
+        const key = orderedKeys[index];
         const replacement = nameToBlock.get(key);
         if (replacement) {
             keptOrder.push(replacement);
@@ -377,8 +385,7 @@ export async function buildUpdatedSpec(update, changeName, options = {}) {
         // full absorbed suffix. RENAMED carries the original raw content under a
         // new map key, and MODIFIED may repeat the suffix deliberately; neither is
         // data loss.
-        const renamedTarget = renamedTargets.get(key);
-        const replacementFromOriginal = replacement ?? (renamedTarget ? nameToBlock.get(renamedTarget) : undefined);
+        const replacementFromOriginal = replacement;
         if (replacementFromOriginal !== block) {
             const foreign = firstForeignTail(block.raw);
             const replacementRaw = replacementFromOriginal?.raw;
@@ -917,7 +924,8 @@ function readableOverview(skeleton, specName) {
  */
 export function buildSpecSkeleton(specFolderName, changeName, purpose) {
     const titleBase = specFolderName;
-    const purposeBody = purpose?.trim() || `TBD - created by archiving change ${changeName}. Update Purpose after archive.`;
+    const purposeBody = purpose?.trim() ||
+        `${PURPOSE_PLACEHOLDER_PREFIX}${changeName}${PURPOSE_PLACEHOLDER_SUFFIX}`;
     return `# ${titleBase} Specification\n\n## Purpose\n${purposeBody}\n\n## Requirements\n`;
 }
 //# sourceMappingURL=specs-apply.js.map