@fission-ai/openspec 1.7.0 → 1.9.0

package/dist/core/update.js

@@ -13,8 +13,8 @@ import { FileSystemUtils } from '../utils/file-system.js';
 import { getSkillReferenceTransformer, getTransformerForTool, transformToSkillReferences } from '../utils/command-references.js';
 import { AI_TOOLS, OPENSPEC_DIR_NAME } from './config.js';
 import { generateCommands, CommandAdapterRegistry, } from './command-generation/index.js';
-import { getToolVersionStatus, getSkillTemplates, getCommandContents, generateSkillContent, getToolsWithSkillsDir, } from './shared/index.js';
-import { detectLegacyArtifacts, cleanupLegacyArtifacts, formatDeferredGlobalPromptSummary, formatCleanupSummary, formatDetectionSummary, getLegacyGlobalPromptMatches, getLegacyWorkflowIdsForTool, getToolsFromLegacyArtifacts, omitGlobalLegacyPromptFiles, pickGlobalLegacyPromptFiles, } from './legacy-cleanup.js';
+import { getToolVersionStatus, getSkillTemplates, getCommandContents, generateSkillContent, getToolsWithSkillsDir, hasGlobalSkillTarget, resolveToolSkillsDir, toolSupportsSkills, } from './shared/index.js';
+import { detectLegacyArtifacts, cleanupLegacyArtifacts, formatDeferredGlobalPromptSummary, formatCleanupSummary, formatDetectionSummary, getLegacyGlobalPromptMatches, getLegacyWorkflowIdsForTool, getToolsFromLegacyArtifacts, omitGlobalLegacyPromptFiles, omitToolLegacyArtifacts, pickGlobalLegacyPromptFiles, } from './legacy-cleanup.js';
 import { isInteractive } from '../utils/interactive.js';
 import { getGlobalConfig } from './global-config.js';
 import { getProfileWorkflows, ALL_WORKFLOWS, CORE_WORKFLOWS } from './profiles.js';
@@ -23,6 +23,8 @@ import { getAvailableTools } from './available-tools.js';
 import { WORKFLOW_TO_SKILL_DIR, getConfiguredToolsForProfileSync, getToolsNeedingProfileSync, } from './profile-sync-drift.js';
 import { scanInstalledWorkflows as scanInstalledWorkflowsShared, migrateIfNeeded as migrateIfNeededShared, findLegacyToolMigrations, migrateLegacyToolDirs, describeLegacyMigration, legacyMigrationNotice, keptInPlaceNotice, hasMovableContent, } from './migration.js';
 import { resolveCommandSurfaceCapability, resolveCommandInvocation, shouldGenerateCommandsForTool, shouldGenerateSkillsForTool, shouldReconcileCommandFilesForTool, shouldRemoveSkillsForTool, } from './command-surface.js';
+import { writeSharedSkillTarget, sharedSkillRootOwner } from './shared-skill-target.js';
+import { includesGitHubCopilot, writeCopilotCloudFiles, removeCopilotCloudFiles, isCopilotCloudEnabled, readCopilotCloudOptIn, findUnmanagedCloudFiles } from './github-copilot/cloud-agent.js';
 const require = createRequire(import.meta.url);
 const { version: OPENSPEC_VERSION } = require('../../package.json');
 /**
@@ -80,6 +82,7 @@ export class UpdateCommand {
         const { newlyConfiguredTools, workflowOverrides: legacyWorkflowOverrides, deferredGlobalCleanup, } = legacyUpgrade;
         // 5. Find configured tools
         const configuredTools = getConfiguredToolsForProfileSync(resolvedProjectPath);
+        const configuredAndNewTools = [...new Set([...configuredTools, ...newlyConfiguredTools])];
         if (configuredTools.length === 0 && newlyConfiguredTools.length === 0) {
             if (deferredGlobalCleanup) {
                 await this.performDeferredGlobalPromptCleanup(resolvedProjectPath, deferredGlobalCleanup);
@@ -94,6 +97,7 @@ export class UpdateCommand {
                 }
                 return;
             }
+            await this.syncCopilotCloudFiles(resolvedProjectPath, configuredAndNewTools);
             console.log(chalk.yellow('No configured tools found.'));
             console.log(chalk.dim('Run "openspec init" to set up tools.'));
             return;
@@ -107,7 +111,13 @@ export class UpdateCommand {
         const statusByTool = new Map(toolStatuses.map((status) => [status.toolId, status]));
         // 7. Smart update detection
         const toolsNeedingVersionUpdate = toolStatuses
-            .filter((s) => s.needsUpdate)
+            .filter((s) => {
+            if (!s.needsUpdate || delivery !== 'commands') {
+                return s.needsUpdate;
+            }
+            const tool = AI_TOOLS.find((candidate) => candidate.value === s.toolId);
+            return !tool || !hasGlobalSkillTarget(tool);
+        })
             .map((s) => s.toolId);
         const toolsNeedingConfigSync = getToolsNeedingProfileSync(resolvedProjectPath, desiredWorkflows, delivery, configuredTools);
         const toolsToUpdateSet = new Set([
@@ -121,6 +131,7 @@ export class UpdateCommand {
             }
             // All tools are up to date
             this.displayUpToDateMessage(toolStatuses);
+            await this.syncCopilotCloudFiles(resolvedProjectPath, configuredAndNewTools);
             // Still check for new tool directories and extra workflows
             this.detectNewTools(resolvedProjectPath, configuredTools);
             this.displayExtraWorkflowsNote(resolvedProjectPath, configuredTools, desiredWorkflows);
@@ -153,11 +164,12 @@ export class UpdateCommand {
         let removedDeselectedSkillCount = 0;
         for (const toolId of toolsToUpdate) {
             const tool = AI_TOOLS.find((t) => t.value === toolId);
-            if (!tool?.skillsDir)
+            if (!tool || !toolSupportsSkills(tool))
                 continue;
             const spinner = ora(`Updating ${tool.name}...`).start();
             try {
-                const skillsDir = path.join(resolvedProjectPath, tool.skillsDir, 'skills');
+                const skillsDir = resolveToolSkillsDir(resolvedProjectPath, tool);
+                const skillsRoot = hasGlobalSkillTarget(tool) ? skillsDir : resolvedProjectPath;
                 const shouldGenerateSkills = shouldGenerateSkillsForTool(tool.value, delivery);
                 const shouldGenerateCommands = shouldGenerateCommandsForTool(tool.value, delivery);
                 const toolWorkflows = legacyWorkflowOverrides[tool.value] ?? desiredWorkflows;
@@ -170,13 +182,18 @@ export class UpdateCommand {
                         const skillFile = path.join(skillDir, 'SKILL.md');
                         const transformer = getTransformerForTool(tool.value, delivery, resolveCommandSurfaceCapability(tool.value), resolveCommandInvocation(tool.value));
                         const skillContent = generateSkillContent(template, OPENSPEC_VERSION, transformer);
+                        FileSystemUtils.assertPathWithin(skillsRoot, skillFile);
                         await FileSystemUtils.writeFile(skillFile, skillContent);
                     }
-                    removedDeselectedSkillCount += await this.removeUnselectedSkillDirs(skillsDir, toolWorkflows);
+                    writeSharedSkillTarget(resolvedProjectPath, tool.value);
+                    removedDeselectedSkillCount += await this.removeUnselectedSkillDirs(skillsRoot, skillsDir, toolWorkflows);
                 }
                 // Delete skill directories if delivery is commands-only
-                if (shouldRemoveSkillsForTool(tool.value, delivery)) {
-                    removedSkillCount += await this.removeSkillDirs(skillsDir);
+                if (shouldRemoveSkillsForTool(tool.value, delivery) && !hasGlobalSkillTarget(tool)) {
+                    removedSkillCount += await this.removeSkillDirs(skillsRoot, skillsDir);
+                    // Persist the selected owner even when commands-only delivery leaves
+                    // this target with no generated skills.
+                    writeSharedSkillTarget(resolvedProjectPath, tool.value);
                     // A tool with no command adapter now has zero OpenSpec artifacts;
                     // say so like init does, rather than deleting its skills silently
                     // and letting tool detection re-suggest an init that would also
@@ -191,7 +208,7 @@ export class UpdateCommand {
                     if (adapter) {
                         const generatedCommands = generateCommands(commandContents, adapter);
                         for (const cmd of generatedCommands) {
-                            const commandFile = path.isAbsolute(cmd.path) ? cmd.path : path.join(resolvedProjectPath, cmd.path);
+                            const commandFile = FileSystemUtils.resolveProjectArtifactPath(resolvedProjectPath, cmd.path);
                             await FileSystemUtils.writeFile(commandFile, cmd.fileContent);
                         }
                         removedDeselectedCommandCount += await this.removeUnselectedCommandFiles(resolvedProjectPath, toolId, toolWorkflows);
@@ -206,6 +223,12 @@ export class UpdateCommand {
                 }
                 spinner.succeed(`Updated ${tool.name}`);
                 updatedTools.push(tool.name);
+                for (const migration of migrateLegacyToolDirs(resolvedProjectPath, [tool.value], 'after-generation')) {
+                    if (hasMovableContent(migration)) {
+                        console.log(chalk.dim(`Migrated ${describeLegacyMigration(migration)}: ${migration.from} → ${migration.to}`));
+                    }
+                    this.reportKeptInPlace(migration);
+                }
             }
             catch (error) {
                 spinner.fail(`Failed to update ${tool.name}`);
@@ -282,7 +305,7 @@ export class UpdateCommand {
             }
             console.log(`Learn more: ${chalk.cyan('https://github.com/Fission-AI/OpenSpec')}`);
         }
-        const configuredAndNewTools = [...new Set([...configuredTools, ...newlyConfiguredTools])];
+        await this.syncCopilotCloudFiles(resolvedProjectPath, configuredAndNewTools);
         // 13. Detect new tool directories not currently configured
         this.detectNewTools(resolvedProjectPath, configuredAndNewTools);
         // 14. Display note about extra workflows not in profile
@@ -296,6 +319,51 @@ export class UpdateCommand {
         }
         console.log();
         console.log(chalk.dim('Restart your IDE for changes to take effect.'));
+        if (failedTools.length > 0) {
+            throw new Error(`OpenSpec update failed for: ${failedTools.map((tool) => tool.name).join(', ')}`);
+        }
+    }
+    async syncCopilotCloudFiles(projectPath, configuredTools) {
+        try {
+            if (includesGitHubCopilot(configuredTools)) {
+                // Cloud files are opt-in (see cloud-agent.ts). `update` never prompts,
+                // so it only refreshes files the user has already opted into (via
+                // `openspec init` or a `githubCopilot.cloudAgent: true` config), or that
+                // a pre-opt-in project already has. Opting in is a deliberate init/config
+                // step, never a silent side effect of running update.
+                if (await isCopilotCloudEnabled(projectPath)) {
+                    await writeCopilotCloudFiles(projectPath);
+                    const collisions = await findUnmanagedCloudFiles(projectPath);
+                    if (collisions.length > 0) {
+                        console.log(chalk.dim(`Left your existing ${collisions.join(' and ')} untouched — add the OpenSpec ` +
+                            `install step by hand so the Copilot cloud agent can run openspec.`));
+                    }
+                    return;
+                }
+                // Explicit opt-out (githubCopilot.cloudAgent: false) means "not here":
+                // remove any managed files a prior opt-in left behind (customized files
+                // are preserved). If the user simply never decided, stay quiet unless
+                // we're at an interactive terminal, where a one-line hint aids discovery.
+                if (readCopilotCloudOptIn(projectPath) === false) {
+                    const removed = await removeCopilotCloudFiles(projectPath);
+                    if (removed > 0) {
+                        console.log(chalk.dim(`Removed: ${removed} Copilot cloud agent file(s) (opted out of cloud files)`));
+                    }
+                }
+                else if (isInteractive()) {
+                    console.log(chalk.dim("GitHub Copilot cloud coding-agent files are available (opt-in). Enable with 'openspec init --copilot-cloud'."));
+                }
+                return;
+            }
+            const removed = await removeCopilotCloudFiles(projectPath);
+            if (removed > 0) {
+                console.log(chalk.dim(`Removed: ${removed} Copilot cloud agent file(s) (github-copilot not configured)`));
+            }
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            console.warn(`Warning: failed to sync Copilot cloud agent files: ${message}`);
+        }
     }
     /**
      * Display message when all tools are up to date.
@@ -387,18 +455,19 @@ export class UpdateCommand {
      * Removes skill directories for workflows when delivery changed to commands-only.
      * Returns the number of directories removed.
      */
-    async removeSkillDirs(skillsDir) {
+    async removeSkillDirs(skillsRoot, skillsDir) {
         let removed = 0;
         for (const workflow of ALL_WORKFLOWS) {
             const dirName = WORKFLOW_TO_SKILL_DIR[workflow];
             if (!dirName)
                 continue;
             const skillDir = path.join(skillsDir, dirName);
+            if (!fs.existsSync(skillDir))
+                continue;
+            FileSystemUtils.assertPathWithin(skillsRoot, skillDir);
             try {
-                if (fs.existsSync(skillDir)) {
-                    await fs.promises.rm(skillDir, { recursive: true, force: true });
-                    removed++;
-                }
+                await fs.promises.rm(skillDir, { recursive: true, force: true });
+                removed++;
             }
             catch {
                 // Ignore errors
@@ -410,7 +479,7 @@ export class UpdateCommand {
      * Removes skill directories for workflows that are no longer selected in the active profile.
      * Returns the number of directories removed.
      */
-    async removeUnselectedSkillDirs(skillsDir, desiredWorkflows) {
+    async removeUnselectedSkillDirs(skillsRoot, skillsDir, desiredWorkflows) {
         const desiredSet = new Set(desiredWorkflows);
         let removed = 0;
         for (const workflow of ALL_WORKFLOWS) {
@@ -420,11 +489,12 @@ export class UpdateCommand {
             if (!dirName)
                 continue;
             const skillDir = path.join(skillsDir, dirName);
+            if (!fs.existsSync(skillDir))
+                continue;
+            FileSystemUtils.assertPathWithin(skillsRoot, skillDir);
             try {
-                if (fs.existsSync(skillDir)) {
-                    await fs.promises.rm(skillDir, { recursive: true, force: true });
-                    removed++;
-                }
+                await fs.promises.rm(skillDir, { recursive: true, force: true });
+                removed++;
             }
             catch {
                 // Ignore errors
@@ -443,7 +513,7 @@ export class UpdateCommand {
             return 0;
         for (const workflow of ALL_WORKFLOWS) {
             const cmdPath = adapter.getFilePath(workflow);
-            const fullPath = path.isAbsolute(cmdPath) ? cmdPath : path.join(projectPath, cmdPath);
+            const fullPath = FileSystemUtils.resolveProjectArtifactPath(projectPath, cmdPath);
             try {
                 if (fs.existsSync(fullPath)) {
                     await fs.promises.unlink(fullPath);
@@ -470,7 +540,7 @@ export class UpdateCommand {
             if (desiredSet.has(workflow))
                 continue;
             const cmdPath = adapter.getFilePath(workflow);
-            const fullPath = path.isAbsolute(cmdPath) ? cmdPath : path.join(projectPath, cmdPath);
+            const fullPath = FileSystemUtils.resolveProjectArtifactPath(projectPath, cmdPath);
             try {
                 if (fs.existsSync(fullPath)) {
                     await fs.promises.unlink(fullPath);
@@ -577,7 +647,7 @@ export class UpdateCommand {
         const canPrompt = isInteractive();
         if (this.force) {
             const legacyUpgrade = await this.upgradeLegacyTools(projectPath, detection, canPrompt, desiredWorkflows, delivery);
-            await this.performImmediateLegacyCleanup(projectPath, detection);
+            await this.performImmediateLegacyCleanup(projectPath, detection, legacyUpgrade.skippedSharedSkillTools);
             return {
                 ...legacyUpgrade,
                 deferredGlobalCleanup: pickGlobalLegacyPromptFiles(detection, detection.globalSlashCommandFiles),
@@ -598,7 +668,7 @@ export class UpdateCommand {
         });
         if (shouldCleanup) {
             const legacyUpgrade = await this.upgradeLegacyTools(projectPath, detection, canPrompt, desiredWorkflows, delivery);
-            await this.performImmediateLegacyCleanup(projectPath, detection);
+            await this.performImmediateLegacyCleanup(projectPath, detection, legacyUpgrade.skippedSharedSkillTools);
             return {
                 ...legacyUpgrade,
                 deferredGlobalCleanup: pickGlobalLegacyPromptFiles(detection, detection.globalSlashCommandFiles),
@@ -613,8 +683,10 @@ export class UpdateCommand {
     /**
      * Cleans approved repo-local legacy artifacts before configured tools refresh.
      */
-    async performImmediateLegacyCleanup(projectPath, detection) {
-        const immediateDetection = omitGlobalLegacyPromptFiles(detection);
+    async performImmediateLegacyCleanup(projectPath, detection, skippedSharedSkillTools = []) {
+        // Tools whose upgrade was skipped (shared root owned by another) had no
+        // replacement written, so their repo-local legacy files must be preserved.
+        const immediateDetection = omitToolLegacyArtifacts(omitGlobalLegacyPromptFiles(detection), skippedSharedSkillTools);
         if (immediateDetection.hasLegacyArtifacts) {
             await this.performLegacyCleanup(projectPath, immediateDetection);
         }
@@ -718,14 +790,16 @@ export class UpdateCommand {
         const inferredCodexWorkflows = getLegacyWorkflowIdsForTool(detection, 'codex');
         // Create skills/commands for selected tools using effective profile+delivery.
         const newlyConfigured = [];
+        const skippedSharedSkillTools = [];
         const workflowOverrides = {};
         for (const toolId of selectedTools) {
             const tool = AI_TOOLS.find((t) => t.value === toolId);
-            if (!tool?.skillsDir)
+            if (!tool || !toolSupportsSkills(tool))
                 continue;
             const spinner = ora(`Setting up ${tool.name}...`).start();
             try {
-                const skillsDir = path.join(projectPath, tool.skillsDir, 'skills');
+                const skillsDir = resolveToolSkillsDir(projectPath, tool);
+                const skillsRoot = hasGlobalSkillTarget(tool) ? skillsDir : projectPath;
                 const shouldGenerateSkills = shouldGenerateSkillsForTool(tool.value, delivery);
                 const shouldGenerateCommands = shouldGenerateCommandsForTool(tool.value, delivery);
                 const toolWorkflows = (tool.value === 'codex' && inferredCodexWorkflows.length > 0
@@ -736,6 +810,30 @@ export class UpdateCommand {
                 }
                 const skillTemplates = getSkillTemplates(toolWorkflows);
                 const commandContents = getCommandContents(toolWorkflows);
+                // A shared skills root (e.g. `.agents`) already owned by another tool
+                // must not be overwritten by a tool inferred from legacy artifacts: a
+                // Codex install detected only from global `~/.codex/prompts` would
+                // otherwise rewrite an existing vendor-neutral `agents` tree with
+                // Codex-specific syntax and flip its ownership marker `agents → codex`.
+                // Leave the established owner in place. (init applies the same
+                // one-writer rule up front when both targets are selected.)
+                //
+                // Skipping here means the tool is never recorded as configured, so a
+                // persistent legacy signal re-offers it on later runs. Because no
+                // replacement is written, this tool is also exempted from immediate
+                // legacy cleanup (see skippedSharedSkillTools) — otherwise a repo-local
+                // `.codex/prompts` would be deleted with nothing put in its place. That
+                // repeat is idempotent and harmless — the alternative is the silent
+                // hijack this prevents.
+                const sharedOwner = shouldGenerateSkills
+                    ? sharedSkillRootOwner(projectPath, tool.value)
+                    : undefined;
+                if (sharedOwner) {
+                    const ownerName = AI_TOOLS.find((candidate) => candidate.value === sharedOwner)?.name ?? sharedOwner;
+                    spinner.info(`Skipped ${tool.name}: ${tool.skillsDir}/skills is already managed by another tool (${ownerName}).`);
+                    skippedSharedSkillTools.push(tool.value);
+                    continue;
+                }
                 // Create skill files when delivery includes skills
                 if (shouldGenerateSkills) {
                     for (const { template, dirName } of skillTemplates) {
@@ -743,8 +841,10 @@ export class UpdateCommand {
                         const skillFile = path.join(skillDir, 'SKILL.md');
                         const transformer = getTransformerForTool(tool.value, delivery, resolveCommandSurfaceCapability(tool.value), resolveCommandInvocation(tool.value));
                         const skillContent = generateSkillContent(template, OPENSPEC_VERSION, transformer);
+                        FileSystemUtils.assertPathWithin(skillsRoot, skillFile);
                         await FileSystemUtils.writeFile(skillFile, skillContent);
                     }
+                    writeSharedSkillTarget(projectPath, tool.value);
                 }
                 // Create commands when delivery includes commands
                 if (shouldGenerateCommands) {
@@ -752,13 +852,19 @@ export class UpdateCommand {
                     if (adapter) {
                         const generatedCommands = generateCommands(commandContents, adapter);
                         for (const cmd of generatedCommands) {
-                            const commandFile = path.isAbsolute(cmd.path) ? cmd.path : path.join(projectPath, cmd.path);
+                            const commandFile = FileSystemUtils.resolveProjectArtifactPath(projectPath, cmd.path);
                             await FileSystemUtils.writeFile(commandFile, cmd.fileContent);
                         }
                     }
                 }
                 spinner.succeed(`Setup complete for ${tool.name}`);
                 newlyConfigured.push(toolId);
+                for (const migration of migrateLegacyToolDirs(projectPath, [tool.value], 'after-generation')) {
+                    if (hasMovableContent(migration)) {
+                        console.log(chalk.dim(`Migrated ${describeLegacyMigration(migration)}: ${migration.from} → ${migration.to}`));
+                    }
+                    this.reportKeptInPlace(migration);
+                }
             }
             catch (error) {
                 spinner.fail(`Failed to set up ${tool.name}`);
@@ -768,7 +874,7 @@ export class UpdateCommand {
         if (newlyConfigured.length > 0) {
             console.log();
         }
-        return { newlyConfiguredTools: newlyConfigured, workflowOverrides };
+        return { newlyConfiguredTools: newlyConfigured, workflowOverrides, skippedSharedSkillTools };
     }
 }
 //# sourceMappingURL=update.js.map

package/dist/core/validation/task-numbering.d.ts

@@ -0,0 +1,16 @@
+export interface TaskNumberingDocument {
+    path: string;
+    content: string;
+}
+export interface TaskNumberingIssue {
+    path: string;
+    line: number;
+    message: string;
+}
+/**
+ * Finds ambiguous task references across the task files tracked by a change.
+ * Numbering is interpreted only inside `## N.` groups. Unnumbered sections,
+ * unnumbered tasks, and files without numbered groups are intentionally ignored.
+ */
+export declare function findTaskNumberingIssues(documents: readonly TaskNumberingDocument[]): TaskNumberingIssue[];
+//# sourceMappingURL=task-numbering.d.ts.map

package/dist/core/validation/task-numbering.js

@@ -0,0 +1,57 @@
+import { parseTaskLines } from '../../utils/task-progress.js';
+const LEVEL_TWO_HEADING = /^ {0,3}##(?!#)(?:[ \t]+|[ \t]*\r?$)/;
+const NUMBERED_GROUP_HEADING = /^ {0,3}##[ \t]+(\d+)\.(?:[ \t]|\r?$)/;
+const TASK_ID = /^(\d+(?:\.\d+)+(?:[A-Za-z]+)?)(?=\s|$)/;
+/**
+ * Finds ambiguous task references across the task files tracked by a change.
+ * Numbering is interpreted only inside `## N.` groups. Unnumbered sections,
+ * unnumbered tasks, and files without numbered groups are intentionally ignored.
+ */
+export function findTaskNumberingIssues(documents) {
+    const issues = [];
+    const firstLocationById = new Map();
+    for (const document of documents) {
+        const lines = document.content.split('\n');
+        if (!lines.some((line) => NUMBERED_GROUP_HEADING.test(line)))
+            continue;
+        let currentGroup;
+        lines.forEach((line, index) => {
+            if (LEVEL_TWO_HEADING.test(line)) {
+                currentGroup = line.match(NUMBERED_GROUP_HEADING)?.[1];
+            }
+            if (currentGroup === undefined)
+                return;
+            const task = parseTaskLines(line)[0];
+            const id = task?.description.match(TASK_ID)?.[1];
+            if (!id)
+                return;
+            const lineNumber = index + 1;
+            const taskGroup = id.split('.')[0];
+            const normalizedTaskGroup = taskGroup.replace(/^0+(?=\d)/, '');
+            const normalizedCurrentGroup = currentGroup.replace(/^0+(?=\d)/, '');
+            if (normalizedTaskGroup !== normalizedCurrentGroup) {
+                issues.push({
+                    path: document.path,
+                    line: lineNumber,
+                    message: `Task "${id}" is under group ${currentGroup}, but its leading number points to group ${taskGroup}. Move it to group ${taskGroup} or renumber it.`,
+                });
+            }
+            const firstLocation = firstLocationById.get(id);
+            if (firstLocation !== undefined) {
+                const firstDeclaration = firstLocation.path === document.path
+                    ? `on line ${firstLocation.line}`
+                    : `in ${firstLocation.path} on line ${firstLocation.line}`;
+                issues.push({
+                    path: document.path,
+                    line: lineNumber,
+                    message: `Task ID "${id}" is duplicated; it was first declared ${firstDeclaration}.`,
+                });
+            }
+            else {
+                firstLocationById.set(id, { path: document.path, line: lineNumber });
+            }
+        });
+    }
+    return issues;
+}
+//# sourceMappingURL=task-numbering.js.map

package/dist/core/validation/validator.d.ts

@@ -12,12 +12,35 @@ export declare class Validator {
      * Validate delta-formatted spec files under a change directory.
      * Enforces:
      * - At least one delta across all files
-     * - ADDED/MODIFIED: each requirement has SHALL/MUST and at least one scenario
+     * - ADDED/MODIFIED: each requirement has at least one scenario; missing
+     *   English SHALL/MUST keywords are guidance unless strict mode is enabled
      * - REMOVED: names only; no scenario/description required
      * - RENAMED: pairs well-formed
      * - No duplicates within sections; no cross-section conflicts per spec
+     *
+     * When `options.mainSpecsDir` is given, MODIFIED blocks are also checked
+     * against the current main specs for the scenario loss archive refuses to
+     * apply (#1477). When `options.projectRoot` is given, the schema's tracked
+     * task files are checked for ambiguous numbering (#1520). Omitting either
+     * option keeps existing library and archive callers behaving as before.
+     */
+    validateChangeDeltaSpecs(changeDir: string, options?: {
+        mainSpecsDir?: string;
+        projectRoot?: string;
+    }): Promise<ValidationReport>;
+    private collectTaskNumberingIssues;
+    /**
+     * Report MODIFIED requirements whose block omits a scenario the main spec
+     * still carries. Uses the same comparison archive applies, so validate can
+     * only report what archive would refuse.
+     *
+     * Silent when the main spec or the requirement header is absent: applying a
+     * MODIFIED against a base that is not there yet is a different failure (a
+     * sister change still in flight is the legitimate case), and archive is the
+     * gate for it. A spec that exists but cannot be read is not absent, though —
+     * archive aborts on it, so reporting it beats calling the change valid.
      */
-    validateChangeDeltaSpecs(changeDir: string): Promise<ValidationReport>;
+    private findScenarioLossIssues;
     private formatInvalidMarkerMessage;
     private convertZodErrors;
     private applySpecRules;
@@ -29,7 +52,7 @@ export declare class Validator {
     private extractRequirementText;
     private containsShallOrMust;
     /**
-     * Build an error message for a requirement block whose body lacks SHALL/MUST.
+     * Build a message for a requirement block whose body lacks SHALL/MUST.
      *
      * When the SHALL/MUST keyword already appears in the requirement header (e.g.
      * `### Requirement: The system SHALL ...`) the original generic error