@fission-ai/openspec 1.8.0 → 1.9.0

package/dist/core/templates/workflows/apply-change.js

@@ -99,6 +99,7 @@ ${STORE_SELECTION_GUIDANCE}
    **Pause if:**
    - Task is unclear → ask for clarification
    - Implementation reveals a design issue → suggest updating artifacts
+   - A task needs work beyond what the spec and tasks describe, or you are tempted to drop, narrow, defer, or accept exceptions to specified behavior to make it fit → surface the added scope and ask; do not absorb it silently
    - Error or blocker encountered → report and wait for guidance
    - User interrupts
 
@@ -169,6 +170,8 @@ What would you like to do?
 - Keep code changes minimal and scoped to each task
 - Update task checkbox immediately after completing each task
 - Pause on errors, blockers, or unclear requirements - don't guess
+- When a task needs work beyond what the spec describes, surface the added scope and pause - never silently narrow, defer, or simplify away specified behavior
+- Only mark a task \`- [x]\` when its specified behavior is fully implemented, not when it is partially done or deferred
 - Use contextFiles from CLI output, don't assume specific file names
 - Do not use context or operation guidance as proof that a task is complete
 - Apply relevant project context; report conflicts with controlling workflow inputs

package/dist/core/templates/workflows/propose.js

@@ -42,7 +42,7 @@ ${STORE_SELECTION_GUIDANCE}
 
    **Use a different schema only if the user:**
    - Explicitly requests a specific schema by name → use \`--schema <schema-name>\`
-   - Asks to "show workflows" or asks "what workflows" exist → resolve the authoritative root by running \`openspec context --json\` from the current working directory. If the user explicitly selected a registered store, use \`openspec context --json --store "<store-id>"\`. Then run \`openspec schemas --json\` with its working directory set to the returned \`root.path\` and let them choose. This preserves roots selected by a local \`store:\` pointer or the global \`defaultStore\`; \`schemas\` does not accept \`--store\`. If context reports only \`no_openspec_root\`, run \`openspec schemas --json\` from the current working directory instead. Do not use this fallback for invalid or unavailable stores.
+   - Asks to "show workflows" or asks "what workflows" exist → resolve the authoritative root by running \`openspec context --json\` from the current working directory. If the user explicitly selected a registered store, use \`openspec context --json --store "<store-id>"\`. Then run \`openspec schemas --json\` with its working directory set to the returned \`root.path\` and let them choose. This preserves roots selected by a local \`store:\` pointer or the global \`defaultStore\`; when a registered store was explicitly selected, append \`--store "<store-id>"\` to \`openspec schemas --json\` as well. If context reports only \`no_openspec_root\`, run \`openspec schemas --json\` from the current working directory instead. Do not use this fallback for invalid or unavailable stores.
 
    Otherwise, omit \`--schema\` to preserve the configured default.
 
@@ -190,7 +190,7 @@ ${STORE_SELECTION_GUIDANCE}
 
    **Use a different schema only if the user:**
    - Explicitly requests a specific schema by name → use \`--schema <schema-name>\`
-   - Asks to "show workflows" or asks "what workflows" exist → resolve the authoritative root by running \`openspec context --json\` from the current working directory. If the user explicitly selected a registered store, use \`openspec context --json --store "<store-id>"\`. Then run \`openspec schemas --json\` with its working directory set to the returned \`root.path\` and let them choose. This preserves roots selected by a local \`store:\` pointer or the global \`defaultStore\`; \`schemas\` does not accept \`--store\`. If context reports only \`no_openspec_root\`, run \`openspec schemas --json\` from the current working directory instead. Do not use this fallback for invalid or unavailable stores.
+   - Asks to "show workflows" or asks "what workflows" exist → resolve the authoritative root by running \`openspec context --json\` from the current working directory. If the user explicitly selected a registered store, use \`openspec context --json --store "<store-id>"\`. Then run \`openspec schemas --json\` with its working directory set to the returned \`root.path\` and let them choose. This preserves roots selected by a local \`store:\` pointer or the global \`defaultStore\`; when a registered store was explicitly selected, append \`--store "<store-id>"\` to \`openspec schemas --json\` as well. If context reports only \`no_openspec_root\`, run \`openspec schemas --json\` from the current working directory instead. Do not use this fallback for invalid or unavailable stores.
 
    Otherwise, omit \`--schema\` to preserve the configured default.
 

package/dist/core/templates/workflows/store-selection.d.ts

@@ -4,5 +4,5 @@
  * Interpolated into every workflow's instructions so generated skills
  * consistently teach how to target a registered store with `--store <id>`.
  */
-export declare const STORE_SELECTION_GUIDANCE = "**Store selection:** If the user names a store (a store is a standalone OpenSpec repo registered on this machine) or the work lives in one, run `openspec store list --json` to discover registered store ids, then pass `--store <id>` on the commands that read or write specs and changes (`new change`, `status`, `instructions`, `list`, `show`, `validate`, `archive`, `doctor`, `context`, `view`). Once selected, treat `--store <id>` as sticky for the rest of the workflow. Every unscoped example of those commands below is shorthand: before running it, append the flag. For example, run `openspec status --change \"<name>\" --json --store \"<id>\"`, not the unscoped form shown below. Other commands do not take the flag. Hints printed by commands already carry the flag; keep it on follow-ups. Without a store, commands act on the nearest local `openspec/` root.";
+export declare const STORE_SELECTION_GUIDANCE = "**Store selection:** If the user names a store (a store is a standalone OpenSpec repo registered on this machine) or the work lives in one, run `openspec store list --json` to discover registered store ids, then pass `--store <id>` on the commands that read or write specs and changes (`new change`, `status`, `instructions`, `list`, `show`, `validate`, `archive`, `doctor`, `context`, `schemas`, `view`). Once selected, treat `--store <id>` as sticky for the rest of the workflow. Every unscoped example of those commands below is shorthand: before running it, append the flag. For example, run `openspec status --change \"<name>\" --json --store \"<id>\"`, not the unscoped form shown below. Other commands do not take the flag. Hints printed by commands already carry the flag; keep it on follow-ups. Without a store, commands act on the nearest local `openspec/` root.";
 //# sourceMappingURL=store-selection.d.ts.map

package/dist/core/templates/workflows/store-selection.js

@@ -4,5 +4,5 @@
  * Interpolated into every workflow's instructions so generated skills
  * consistently teach how to target a registered store with `--store <id>`.
  */
-export const STORE_SELECTION_GUIDANCE = `**Store selection:** If the user names a store (a store is a standalone OpenSpec repo registered on this machine) or the work lives in one, run \`openspec store list --json\` to discover registered store ids, then pass \`--store <id>\` on the commands that read or write specs and changes (\`new change\`, \`status\`, \`instructions\`, \`list\`, \`show\`, \`validate\`, \`archive\`, \`doctor\`, \`context\`, \`view\`). Once selected, treat \`--store <id>\` as sticky for the rest of the workflow. Every unscoped example of those commands below is shorthand: before running it, append the flag. For example, run \`openspec status --change "<name>" --json --store "<id>"\`, not the unscoped form shown below. Other commands do not take the flag. Hints printed by commands already carry the flag; keep it on follow-ups. Without a store, commands act on the nearest local \`openspec/\` root.`;
+export const STORE_SELECTION_GUIDANCE = `**Store selection:** If the user names a store (a store is a standalone OpenSpec repo registered on this machine) or the work lives in one, run \`openspec store list --json\` to discover registered store ids, then pass \`--store <id>\` on the commands that read or write specs and changes (\`new change\`, \`status\`, \`instructions\`, \`list\`, \`show\`, \`validate\`, \`archive\`, \`doctor\`, \`context\`, \`schemas\`, \`view\`). Once selected, treat \`--store <id>\` as sticky for the rest of the workflow. Every unscoped example of those commands below is shorthand: before running it, append the flag. For example, run \`openspec status --change "<name>" --json --store "<id>"\`, not the unscoped form shown below. Other commands do not take the flag. Hints printed by commands already carry the flag; keep it on follow-ups. Without a store, commands act on the nearest local \`openspec/\` root.`;
 //# sourceMappingURL=store-selection.js.map

package/dist/core/templates/workflows/update-change.js

@@ -9,7 +9,7 @@ ${STORE_SELECTION_GUIDANCE}
 
 **Input**: Optionally specify a change name. If omitted, check if it can be inferred from conversation context. If vague or ambiguous you MUST prompt for available changes.
 
-\`/opsx:continue\` is an expanded-profile workflow and may not be installed. Before suggesting it anywhere below, verify that it is available. If it is unavailable, \`openspec status --change "<name>" --json\` shows the next artifact and \`openspec instructions "<artifact-id>" --change "<name>" --json\` explains how to create it.
+\`/opsx:continue\` is an optional workflow and may not be installed. Before suggesting it anywhere below, verify that it is available. If it is unavailable, \`openspec status --change "<name>" --json\` shows the next artifact and \`openspec instructions "<artifact-id>" --change "<name>" --json\` explains how to create it.
 
 **Steps**
 
@@ -81,7 +81,7 @@ After each invocation, show:
 - Edit only the concrete files in \`existingOutputPaths\`; never write to a glob \`resolvedOutputPath\`.
 - Do not advance the build frontier: no new artifacts, no new files under glob artifacts - that is \`/opsx:continue\`'s job.
 - Confirm every edit with the user before writing.
-- If the request changes the change's *intent* rather than refining it, first verify whether the expanded-profile \`/opsx:new\` workflow is available. If it is, recommend starting fresh with \`/opsx:new\` (the "Update vs. Start Fresh" heuristic). If it is unavailable, ask for a distinct unused change name and recommend \`openspec new change "<new-change-name>"\` instead.`,
+- If the request changes the change's *intent* rather than refining it, first verify whether the optional \`/opsx:new\` workflow is available. If it is, recommend starting fresh with \`/opsx:new\` (the "Update vs. Start Fresh" heuristic). If it is unavailable, ask for a distinct unused change name and recommend \`openspec new change "<new-change-name>"\` instead.`,
         license: 'MIT',
         compatibility: 'Requires openspec CLI.',
         metadata: { author: 'openspec', version: '1.0' },
@@ -99,7 +99,7 @@ ${STORE_SELECTION_GUIDANCE}
 
 **Input**: Optionally specify a change name after \`/opsx:update\` (e.g., \`/opsx:update add-auth\`). If omitted, check if it can be inferred from conversation context. If vague or ambiguous you MUST prompt for available changes.
 
-\`/opsx:continue\` is an expanded-profile workflow and may not be installed. Before suggesting it anywhere below, verify that it is available. If it is unavailable, \`openspec status --change "<name>" --json\` shows the next artifact and \`openspec instructions "<artifact-id>" --change "<name>" --json\` explains how to create it.
+\`/opsx:continue\` is an optional workflow and may not be installed. Before suggesting it anywhere below, verify that it is available. If it is unavailable, \`openspec status --change "<name>" --json\` shows the next artifact and \`openspec instructions "<artifact-id>" --change "<name>" --json\` explains how to create it.
 
 **Steps**
 
@@ -171,7 +171,7 @@ After each invocation, show:
 - Edit only the concrete files in \`existingOutputPaths\`; never write to a glob \`resolvedOutputPath\`.
 - Do not advance the build frontier: no new artifacts, no new files under glob artifacts - that is \`/opsx:continue\`'s job.
 - Confirm every edit with the user before writing.
-- If the request changes the change's *intent* rather than refining it, first verify whether the expanded-profile \`/opsx:new\` workflow is available. If it is, recommend starting fresh with \`/opsx:new\` (the "Update vs. Start Fresh" heuristic). If it is unavailable, ask for a distinct unused change name and recommend \`openspec new change "<new-change-name>"\` instead.`
+- If the request changes the change's *intent* rather than refining it, first verify whether the optional \`/opsx:new\` workflow is available. If it is, recommend starting fresh with \`/opsx:new\` (the "Update vs. Start Fresh" heuristic). If it is unavailable, ask for a distinct unused change name and recommend \`openspec new change "<new-change-name>"\` instead.`
     };
 }
 //# sourceMappingURL=update-change.js.map

package/dist/core/update.js

@@ -14,7 +14,7 @@ import { getSkillReferenceTransformer, getTransformerForTool, transformToSkillRe
 import { AI_TOOLS, OPENSPEC_DIR_NAME } from './config.js';
 import { generateCommands, CommandAdapterRegistry, } from './command-generation/index.js';
 import { getToolVersionStatus, getSkillTemplates, getCommandContents, generateSkillContent, getToolsWithSkillsDir, hasGlobalSkillTarget, resolveToolSkillsDir, toolSupportsSkills, } from './shared/index.js';
-import { detectLegacyArtifacts, cleanupLegacyArtifacts, formatDeferredGlobalPromptSummary, formatCleanupSummary, formatDetectionSummary, getLegacyGlobalPromptMatches, getLegacyWorkflowIdsForTool, getToolsFromLegacyArtifacts, omitGlobalLegacyPromptFiles, pickGlobalLegacyPromptFiles, } from './legacy-cleanup.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,7 +23,7 @@ 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 } from './shared-skill-target.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');
@@ -647,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),
@@ -668,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),
@@ -683,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);
         }
@@ -788,6 +790,7 @@ 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);
@@ -807,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) {
@@ -847,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

@@ -20,12 +20,15 @@ export declare class Validator {
      *
      * When `options.mainSpecsDir` is given, MODIFIED blocks are also checked
      * against the current main specs for the scenario loss archive refuses to
-     * apply (#1477). Omitting it keeps the change-only checks, so callers with
-     * no main specs root (and existing library callers) behave as before.
+     * 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

package/dist/core/validation/validator.js

@@ -9,7 +9,10 @@ import { extractRequirementBody as extractRequirementBodyShared, containsShallOr
 import { findMainSpecStructureIssues } from '../parsers/spec-structure.js';
 import { FileSystemUtils } from '../../utils/file-system.js';
 import { discoverSpecFiles, hasAnyFileUnder } from '../../utils/spec-discovery.js';
-import { METADATA_FILENAME, readSkipSpecsMarker } from '../../utils/change-metadata.js';
+import { METADATA_FILENAME, readSkipSpecsMarker, resolveSchemaForChange, } from '../../utils/change-metadata.js';
+import { resolveTaskFilesForChange } from '../../utils/task-progress.js';
+import { findTaskNumberingIssues } from './task-numbering.js';
+import { getPackageSchemasDir, getSchemaDir } from '../artifact-graph/index.js';
 export class Validator {
     strictMode;
     constructor(strictMode = false) {
@@ -109,8 +112,9 @@ export class Validator {
      *
      * When `options.mainSpecsDir` is given, MODIFIED blocks are also checked
      * against the current main specs for the scenario loss archive refuses to
-     * apply (#1477). Omitting it keeps the change-only checks, so callers with
-     * no main specs root (and existing library callers) behave as before.
+     * 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.
      */
     async validateChangeDeltaSpecs(changeDir, options = {}) {
         const issues = [];
@@ -387,8 +391,58 @@ export class Validator {
                 issues.push({ level: 'ERROR', path: 'file', message: this.enrichTopLevelError('change', VALIDATION_MESSAGES.CHANGE_NO_DELTAS) });
             }
         }
+        if (options.projectRoot) {
+            issues.push(...await this.collectTaskNumberingIssues(changeDir, options.projectRoot));
+        }
         return this.createReport(issues);
     }
+    async collectTaskNumberingIssues(changeDir, projectRoot) {
+        try {
+            const schemaName = resolveSchemaForChange(changeDir, undefined, projectRoot).replace(/\.ya?ml$/, '');
+            const schemaDir = getSchemaDir(schemaName, projectRoot);
+            const builtInSchemaDir = path.join(getPackageSchemasDir(), 'spec-driven');
+            if (schemaName !== 'spec-driven' ||
+                schemaDir === null ||
+                FileSystemUtils.canonicalizeExistingPath(schemaDir) !==
+                    FileSystemUtils.canonicalizeExistingPath(builtInSchemaDir)) {
+                return [];
+            }
+        }
+        catch {
+            return [];
+        }
+        let taskFiles;
+        try {
+            taskFiles = resolveTaskFilesForChange(changeDir, projectRoot);
+        }
+        catch {
+            return [];
+        }
+        if (taskFiles.length === 0) {
+            taskFiles = [path.join(changeDir, 'tasks.md')];
+        }
+        const documents = [];
+        for (const taskFile of taskFiles) {
+            let content;
+            try {
+                content = await fs.readFile(taskFile, 'utf-8');
+            }
+            catch {
+                continue;
+            }
+            documents.push({
+                path: FileSystemUtils.toPosixPath(path.relative(changeDir, taskFile)),
+                content,
+            });
+        }
+        documents.sort((left, right) => left.path.localeCompare(right.path));
+        return findTaskNumberingIssues(documents).map((issue) => ({
+            level: 'WARNING',
+            path: issue.path,
+            line: issue.line,
+            message: issue.message,
+        }));
+    }
     /**
      * Report MODIFIED requirements whose block omits a scenario the main spec
      * still carries. Uses the same comparison archive applies, so validate can

package/dist/telemetry/index.d.ts

@@ -27,7 +27,9 @@ export declare function trackCommand(commandName: string, version: string): Prom
 /**
  * Show first-run telemetry notice if not already seen.
  */
-export declare function maybeShowTelemetryNotice(): Promise<void>;
+export declare function maybeShowTelemetryNotice(options?: {
+    silent?: boolean;
+}): Promise<void>;
 /**
  * Flush pending telemetry events.
  * Call this before CLI exit.

package/dist/telemetry/index.js

@@ -159,7 +159,7 @@ export async function trackCommand(commandName, version) {
 /**
  * Show first-run telemetry notice if not already seen.
  */
-export async function maybeShowTelemetryNotice() {
+export async function maybeShowTelemetryNotice(options = {}) {
     if (!isTelemetryEnabled()) {
         return;
     }
@@ -168,6 +168,12 @@ export async function maybeShowTelemetryNotice() {
         if (config.noticeSeen) {
             return;
         }
+        // In --json mode the notice would pollute stdout and break parsers, so
+        // defer it: skip the notice AND leave noticeSeen unset so the disclosure
+        // still appears on the user's first later non-JSON run.
+        if (options.silent) {
+            return;
+        }
         // Display notice
         console.log('Note: OpenSpec collects anonymous usage stats. Opt out: OPENSPEC_TELEMETRY=0 or openspec config set telemetry.enabled false');
         // Mark as seen

package/dist/utils/interactive.d.ts

@@ -1,3 +1,4 @@
+import type { Readable, Writable } from 'node:stream';
 export type InteractiveOptions = {
     /**
      * Explicit "disable prompts" flag passed by internal callers.
@@ -35,7 +36,35 @@ export declare function isInteractive(value?: boolean | InteractiveOptions): boo
  *   somebody was there and chose to quit.
  *
  * Beyond that it defers to `isInteractive()`, so `CI`, `OPEN_SPEC_INTERACTIVE=0`
- * and `--no-interactive` count even when a runner allocated a pty.
+ * and `--no-interactive` count even when a runner allocated a pty. It also
+ * counts a redirected stdout: `confirmPrompt` drops to the plain reader whenever
+ * *either* stream is not a TTY, so a stdin-TTY-but-stdout-redirected run
+ * (`openspec archive x > log.txt` from a terminal) that hits EOF must classify
+ * the same way the prompt was selected — otherwise it would leak the raw
+ * `ExitPromptError` instead of the `--yes` guidance.
  */
 export declare function isNonInteractivePromptError(error: unknown, value?: boolean | InteractiveOptions): boolean;
+export type ConfirmPrompt = {
+    message: string;
+    default: boolean;
+};
+/**
+ * Ask a yes/no question. A real terminal gets @inquirer's rich prompt;
+ * everything else — a pipe, a file redirect, an agent that captures stdout —
+ * reads one plain line instead.
+ *
+ * @inquirer renders `confirm` by writing ANSI cursor-movement escape sequences,
+ * and it emits them even when stdout is not a TTY. Redirected to a file those
+ * sequences are noise, and in some non-TTY hosts the render loop never settles
+ * and repeats `ESC[NNG` cursor moves until the disk fills (#1526). Reading
+ * the answer ourselves keeps the single piped answer @inquirer ever supported
+ * working (`printf 'y\n' | openspec archive ...`) without emitting any escapes.
+ *
+ * `io` overrides the streams; it exists for tests and mirrors @inquirer's own
+ * `{ input, output }` context. Production callers pass only the prompt.
+ */
+export declare function confirmPrompt(prompt: ConfirmPrompt, io?: {
+    input?: Readable;
+    output?: Writable;
+}): Promise<boolean>;
 //# sourceMappingURL=interactive.d.ts.map

package/dist/utils/interactive.js

@@ -1,3 +1,4 @@
+import { createInterface } from 'node:readline';
 /**
  * Resolves whether non-interactive mode is requested.
  * Handles both explicit `noInteractive: true` and Commander.js style `interactive: false`.
@@ -38,7 +39,12 @@ export function isInteractive(value) {
  *   somebody was there and chose to quit.
  *
  * Beyond that it defers to `isInteractive()`, so `CI`, `OPEN_SPEC_INTERACTIVE=0`
- * and `--no-interactive` count even when a runner allocated a pty.
+ * and `--no-interactive` count even when a runner allocated a pty. It also
+ * counts a redirected stdout: `confirmPrompt` drops to the plain reader whenever
+ * *either* stream is not a TTY, so a stdin-TTY-but-stdout-redirected run
+ * (`openspec archive x > log.txt` from a terminal) that hits EOF must classify
+ * the same way the prompt was selected — otherwise it would leak the raw
+ * `ExitPromptError` instead of the `--yes` guidance.
  */
 export function isNonInteractivePromptError(error, value) {
     if (!(error instanceof Error))
@@ -48,6 +54,103 @@ export function isNonInteractivePromptError(error, value) {
         return false;
     if (error.message.includes('SIGINT'))
         return false;
-    return !isInteractive(value);
+    return !isInteractive(value) || !process.stdout.isTTY;
+}
+/**
+ * Ask a yes/no question. A real terminal gets @inquirer's rich prompt;
+ * everything else — a pipe, a file redirect, an agent that captures stdout —
+ * reads one plain line instead.
+ *
+ * @inquirer renders `confirm` by writing ANSI cursor-movement escape sequences,
+ * and it emits them even when stdout is not a TTY. Redirected to a file those
+ * sequences are noise, and in some non-TTY hosts the render loop never settles
+ * and repeats `ESC[NNG` cursor moves until the disk fills (#1526). Reading
+ * the answer ourselves keeps the single piped answer @inquirer ever supported
+ * working (`printf 'y\n' | openspec archive ...`) without emitting any escapes.
+ *
+ * `io` overrides the streams; it exists for tests and mirrors @inquirer's own
+ * `{ input, output }` context. Production callers pass only the prompt.
+ */
+export async function confirmPrompt(prompt, io = {}) {
+    const input = io.input ?? process.stdin;
+    const output = io.output ?? process.stdout;
+    const isTerminal = Boolean(input.isTTY) &&
+        Boolean(output.isTTY);
+    if (isTerminal) {
+        const { confirm } = await import('@inquirer/prompts');
+        return confirm(prompt);
+    }
+    return readYesNo(prompt, input, output);
+}
+function readYesNo(prompt, input, output) {
+    return new Promise((resolve, reject) => {
+        let settled = false;
+        // Detach the input-stream error listener on settle: `input` is the
+        // long-lived process.stdin, so a leftover listener would accumulate across
+        // archive's successive prompts and swallow a later, unrelated stdin error.
+        const cleanup = () => {
+            input.removeListener('error', onError);
+        };
+        const blockOnNoAnswer = () => {
+            if (settled)
+                return;
+            settled = true;
+            cleanup();
+            // No line could be read (stdin closed / EOF). Mirror @inquirer's failure
+            // so callers that classify it — isNonInteractivePromptError, the #1479
+            // "rerun with --yes" guidance — keep working unchanged.
+            const error = new Error('User force closed the prompt');
+            error.name = 'ExitPromptError';
+            reject(error);
+        };
+        // A stdin error surfaces on the interface (readline forwards input-stream
+        // errors since Node 16). Without a handler the promise would hang and the
+        // 'error' would go unhandled; settle it with the real fault instead.
+        const onError = (err) => {
+            if (settled)
+                return;
+            settled = true;
+            cleanup();
+            rl.close();
+            reject(err instanceof Error ? err : new Error(String(err)));
+        };
+        // An earlier prompt may have already drained stdin (only one piped answer
+        // was ever supported). A fresh readline over an ended stream never emits
+        // 'close', so guard here rather than hang and exit as a no-op.
+        if (input.readableEnded) {
+            blockOnNoAnswer();
+            return;
+        }
+        output.write(`${prompt.message} ${prompt.default ? '(Y/n)' : '(y/N)'} `);
+        // terminal:false guarantees readline never emits its own line-editing
+        // escapes — an escape-free read is the whole point here.
+        const rl = createInterface({ input, terminal: false });
+        input.once('error', onError);
+        rl.once('error', onError);
+        rl.once('line', (line) => {
+            if (settled)
+                return;
+            settled = true;
+            cleanup();
+            rl.close();
+            output.write('\n');
+            // Mirror @inquirer/confirm's parser (prefix match on y/yes and n/no,
+            // otherwise the default) so a piped answer resolves identically to the
+            // interactive prompt it replaces.
+            const answer = line.trim();
+            if (/^(y|yes)/i.test(answer)) {
+                resolve(true);
+            }
+            else if (/^(n|no)/i.test(answer)) {
+                resolve(false);
+            }
+            else {
+                resolve(prompt.default);
+            }
+        });
+        rl.once('close', () => {
+            blockOnNoAnswer();
+        });
+    });
 }
 //# sourceMappingURL=interactive.js.map

package/dist/utils/task-progress.d.ts

@@ -20,6 +20,27 @@ export interface TaskProgress {
     completed: number;
 }
 export declare function countTasksFromContent(content: string): TaskProgress;
+/**
+ * Run-scoped memo mapping a schema name to its tracked-tasks `generates` glob.
+ * When one command resolves progress for many changes under a constant
+ * `projectRoot` — e.g. `validate --archived` over an append-only archive — this
+ * avoids re-reading and re-parsing (YAML + Zod) the same `schema.yaml` once per
+ * change. Keyed by schema name alone, which is safe *only* because a single run
+ * holds `projectRoot` constant; never reuse one cache across differing roots.
+ */
+export type SchemaGlobCache = Map<string, string | undefined>;
+/** Resolves the task files selected by the schema's apply tracking rule. */
+export declare function resolveTaskFilesForChange(changeDir: string, projectRoot: string, schemaGlobCache?: SchemaGlobCache): string[];
+export interface TaskProgressDetail extends TaskProgress {
+    /**
+     * Task files that exist but could not be read (any error other than ENOENT).
+     * `getTaskProgressForChange` discards this list to preserve its behavior;
+     * callers that must fail loudly on an unreadable tasks file — e.g.
+     * `openspec validate --archived` — read it so an unreadable file is never
+     * silently counted as "no tasks" (#205).
+     */
+    unreadable: string[];
+}
 /**
  * Computes a change's task progress by resolving its tracked-tasks artifact and
  * counting checkboxes across every file matched by that artifact's `generates`
@@ -27,7 +48,19 @@ export declare function countTasksFromContent(content: string): TaskProgress;
  * artifact (`resolveArtifactOutputs`) — so progress is no longer blind to nested
  * `tasks.md` files (#1202). Falls back to a single top-level `tasks.md` (exactly
  * as before) when the schema is unresolvable, no tracked-tasks artifact is found,
- * or the glob matches no file. Never throws.
+ * or the glob matches no file. Also reports task files that exist but could not
+ * be read. Per-file read errors are captured (never thrown); the only throw path
+ * is a malformed/unsafe schema whose glob resolution rejects (path traversal or
+ * a linked-directory cycle in `resolveArtifactOutputs`). Pass `schemaGlobCache`
+ * to memoize schema→glob resolution across many changes in one run.
+ */
+export declare function getTaskProgressDetailForChange(changesDir: string, changeName: string, projectRoot: string, schemaGlobCache?: SchemaGlobCache): Promise<TaskProgressDetail>;
+/**
+ * The task-completion counter `status`, `list`, and `archive` share. Delegates
+ * to `getTaskProgressDetailForChange` and drops the `unreadable` detail, so its
+ * returned totals are unchanged. Throws only on the same malformed/unsafe-schema
+ * glob-resolution path as that function (existing behavior; callers guard it as
+ * they did before).
  */
 export declare function getTaskProgressForChange(changesDir: string, changeName: string, projectRoot: string): Promise<TaskProgress>;
 export declare function formatTaskStatus(progress: TaskProgress): string;