@fission-ai/openspec 1.14.0 → 1.14.1

package/dist/core/archive.js

@@ -247,6 +247,14 @@ function toArchiveDiagnostic(error) {
     if (isRootSelectionError(error)) {
         return error.diagnostic;
     }
+    if (error instanceof RetirementCleanupError) {
+        return {
+            severity: 'error',
+            code: 'archive_retirement_cleanup_failed',
+            message: error.message,
+            fix: 'Inspect the archived change and all recovery paths in this diagnostic; preserve any needed content before cleanup.',
+        };
+    }
     return {
         severity: 'error',
         code: 'archive_error',
@@ -379,7 +387,7 @@ async function assertCopiedDirectoryUnchanged(stagedSource, destination, expecte
  */
 class MoveDestinationRetainedError extends Error {
 }
-class RetirementBackupsRetainedError extends Error {
+class RetirementCleanupError extends Error {
 }
 function isFallbackRenameCode(code) {
     return code === 'EPERM' || code === 'EXDEV';
@@ -1012,12 +1020,12 @@ async function finalizeRetirementBackups(snapshots, mainSpecsDir) {
             snapshot.displacedPath = undefined;
         }
         catch (error) {
-            errors.push(`Could not remove the committed retirement backup at ${displacedPath} ` +
+            errors.push(`Could not finalize the retirement backup at ${displacedPath} ` +
                 `(${error instanceof Error ? error.message : String(error)}).`);
         }
     }
     if (errors.length > 0) {
-        throw new RetirementBackupsRetainedError(`${errors.join(' ')} The change remains archived and each listed backup was retained for recovery.`);
+        throw new RetirementCleanupError(`${errors.join(' ')} The change was archived, but retirement cleanup did not complete. Inspect all reported recovery paths before recovery or cleanup.`);
     }
 }
 export class ArchiveCommand {
@@ -1777,11 +1785,11 @@ export class ArchiveCommand {
                                     await finalizeRetirementBackups(specSnapshots, mainSpecsDir);
                                 }
                                 catch (cleanupError) {
-                                    throw new RetirementBackupsRetainedError(`${error.message} ${cleanupError instanceof Error ? cleanupError.message : String(cleanupError)}`);
+                                    throw new RetirementCleanupError(`${error.message} ${cleanupError instanceof Error ? cleanupError.message : String(cleanupError)}`);
                                 }
                                 throw error;
                             }
-                            if (error instanceof RetirementBackupsRetainedError)
+                            if (error instanceof RetirementCleanupError)
                                 throw error;
                             const rollbackErrors = [];
                             try {

package/dist/core/completion-tip.js

@@ -22,7 +22,6 @@ import { getGlobalConfigPath } from './global-config.js';
 import { writeFileAtomically } from './file-state.js';
 import { isCiEnvironment } from '../utils/ci.js';
 import { detectShell } from '../utils/shell-detection.js';
-import { CompletionFactory } from './completions/factory.js';
 export const COMPLETION_TIP_MESSAGE = "Tip: Run 'openspec completion install' for shell completions";
 function isSuppressedByEnv() {
     // isCiEnvironment, not a CI==='true' string check: providers set CI to "True",
@@ -54,6 +53,9 @@ async function decideTip() {
         if (!shell) {
             return 'retire';
         }
+        // Loaded only here: every shell's generator and installer, needed only on
+        // the rare run that still owes the tip.
+        const { CompletionFactory } = await import('./completions/factory.js');
         return (await CompletionFactory.createInstaller(shell).isInstalled())
             ? 'retire'
             : 'show';

package/dist/core/config-schema.d.ts

@@ -10,9 +10,9 @@ export declare const GlobalConfigSchema: z.ZodObject<{
         core: "core";
     }>>>;
     delivery: z.ZodDefault<z.ZodOptional<z.ZodEnum<{
-        commands: "commands";
         both: "both";
         skills: "skills";
+        commands: "commands";
     }>>>;
     workflows: z.ZodOptional<z.ZodArray<z.ZodString>>;
     defaultStore: z.ZodOptional<z.ZodString>;

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

@@ -66,7 +66,7 @@ ${PROJECT_ROOT_GUARD}
    - If \`state: "blocked"\`: show the message and pause implementation.
      - If \`missingArtifacts\` is non-empty: ${BLOCKED_STATE_HANDOFF}
      - Otherwise, follow the CLI instruction to create or repair the schema-configured tracking file from existing planning artifacts. Do not assume another artifact is ready or start implementation while blocked.
-   - If \`state: "all_done"\`: congratulate, suggest archive
+   - If \`state: "all_done"\`: report that all tracked tasks are complete and suggest review or verification as appropriate before archiving
    - Otherwise: proceed to implementation
 
    Treat \`context\` as a required prompt-level input. Read and consider it, and
@@ -125,7 +125,7 @@ ${PROJECT_ROOT_GUARD}
    Display:
    - Tasks completed this session
    - Overall progress: "N/M tasks complete"
-   - If all done: suggest archive
+   - If all done: report that tracked tasks are complete and suggest review or verification as appropriate before archiving
    - If paused: explain why and wait for guidance
 
 **Output During Implementation**
@@ -156,7 +156,8 @@ Working on task 4/7: <task description>
 - [x] Task 2
 ...
 
-All tasks complete! ${ARCHIVE_HANDOFF}
+All tracked tasks are complete. Review or verify the change as appropriate
+before archiving. ${ARCHIVE_HANDOFF}
 \`\`\`
 
 **Output On Pause (Issue Encountered)**

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

@@ -7,6 +7,15 @@ import { PROJECT_ROOT_GUARD } from './project-root.js';
  * optional-workflow.ts).
  */
 const PLANNING_COMPLETE_HANDOFF = optionalWorkflow('apply', 'You can now implement this change with `/opsx:apply`.', 'You can now implement this change - `openspec instructions apply --change "<name>" --json` returns the tasks and how to work them.') + ' ' + optionalWorkflow('archive', 'Once implementation and any tracked work are complete, archive it with `/opsx:archive`.', 'Once implementation and any tracked work are complete, archive it with `openspec archive "<name>"`.');
+/**
+ * A glob artifact reads `done` once one matching file exists, so a run
+ * interrupted while writing several files leaves it `done` with files missing,
+ * and the next run would move on without reading its instruction again (#2034).
+ */
+const PARTIAL_ARTIFACT_CHECK = `**Before anything else, finish a partly written artifact**:
+   - An artifact whose output is a glob pattern (e.g. \`specs/**/*.md\`) reads \`done\` as soon as one matching file exists, so a run interrupted while writing its files leaves it \`done\` with some still missing
+   - For each such \`done\` artifact, first get its instructions and read any completed dependencies needed to determine the expected files. Then compare those files with \`artifactPaths.<id>.existingOutputPaths\`. For spec-driven's \`specs\`, read the proposal and check for one \`specs/<capability-path>/spec.md\` per capability it lists; resolve each expected path against \`changeRoot\` before comparing path identity
+   - If any are missing, write only the missing files, and STOP - that counts as this invocation's ONE artifact. If you cannot tell whether a file was left out on purpose, ask the user`;
 export function getContinueChangeSkillTemplate() {
     return {
         name: 'openspec-continue-change',
@@ -51,6 +60,10 @@ ${PROJECT_ROOT_GUARD}
 
    ---
 
+   ${PARTIAL_ARTIFACT_CHECK}
+
+   ---
+
    **If all planning artifacts are complete (\`isPlanningComplete: true\`, or legacy \`isComplete: true\`)**:
    - Congratulate the user
    - Show final status including the schema used
@@ -169,6 +182,10 @@ ${PROJECT_ROOT_GUARD}
 
    ---
 
+   ${PARTIAL_ARTIFACT_CHECK}
+
+   ---
+
    **If all planning artifacts are complete (\`isPlanningComplete: true\`, or legacy \`isComplete: true\`)**:
    - Congratulate the user
    - Show final status including the schema used

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

@@ -76,9 +76,9 @@ ${PROJECT_ROOT_GUARD}
      - Recommendation: "Complete task: <description>" or "Mark as done if already implemented"
 
    **Spec Coverage**:
-   - If status marks the spec artifact skipped by \`skip_specs: true\`, or the schema defines no spec artifact, report the spec-dependent checks as not applicable.
-   - Otherwise, \`contextFiles\` is keyed by artifact id, and artifact ids come from the active schema. If \`contextFiles.specs\` is absent or empty, mark **Spec Coverage**, **Requirement Implementation Mapping**, and **Scenario Coverage** as not verified; do not treat any of them as clean.
-   - If delta specs exist in \`contextFiles.specs\`:
+   - If status marks the spec artifact skipped by \`skip_specs: true\`, or the schema defines no spec artifact (no artifact whose \`artifactPaths.<id>.outputPath\` is under \`specs/\`), report the spec-dependent checks as not applicable.
+   - Otherwise, \`contextFiles\` is keyed by artifact id, and artifact ids come from the active schema, so do not assume an id such as \`specs\`. The spec artifacts are those whose \`artifactPaths.<id>.outputPath\` is under \`specs/\`; read their files from \`contextFiles.<id>\`. If those spec files are absent or empty, mark **Spec Coverage**, **Requirement Implementation Mapping**, and **Scenario Coverage** as not verified; do not treat any of them as clean.
+   - If delta specs exist in those spec files:
      - Extract all requirements (marked with "### Requirement:", or listed as \`FROM:\`/\`TO:\` pairs under \`## RENAMED Requirements\`) and note the delta section each one sits under: \`## ADDED\`, \`## MODIFIED\`, \`## REMOVED\`, or \`## RENAMED Requirements\`. The section decides what the check looks for.
      - For each ADDED or MODIFIED requirement (for MODIFIED, check the text in the delta, not the old wording):
        - Search codebase for keywords related to the requirement
@@ -127,14 +127,14 @@ ${PROJECT_ROOT_GUARD}
 7. **Verify Coherence**
 
    **Design Adherence**:
-   - If the schema defines no design artifact, report **Design Adherence** as not applicable.
-   - If \`contextFiles.design\` exists:
+   - If the schema defines no design artifact (no artifact with id \`design\`, and none whose \`artifactPaths.<id>.outputPath\` is or ends in \`design.md\`), report **Design Adherence** as not applicable.
+   - If the design artifact's \`contextFiles.<id>\` file exists:
      - Extract key decisions (look for sections like "Decision:", "Approach:", "Architecture:")
      - Verify implementation follows those decisions
      - If contradiction detected:
        - Add WARNING: "Design decision not followed: <decision>"
        - Recommendation: "Update implementation or revise design.md to match reality"
-   - Otherwise, if \`contextFiles.design\` is absent or empty: mark **Design Adherence** as not verified. With other supporting artifacts, **Code Pattern Consistency** still runs; the task-only case remains limited to task completion.
+   - Otherwise, if the design artifact's \`contextFiles.<id>\` file is absent or empty: mark **Design Adherence** as not verified. With other supporting artifacts, **Code Pattern Consistency** still runs; the task-only case remains limited to task completion.
 
    **Code Pattern Consistency**:
    - If implementation changes cannot be identified, mark **Code Pattern Consistency** as not verified and explain the missing evidence.
@@ -285,9 +285,9 @@ ${PROJECT_ROOT_GUARD}
      - Recommendation: "Complete task: <description>" or "Mark as done if already implemented"
 
    **Spec Coverage**:
-   - If status marks the spec artifact skipped by \`skip_specs: true\`, or the schema defines no spec artifact, report the spec-dependent checks as not applicable.
-   - Otherwise, \`contextFiles\` is keyed by artifact id, and artifact ids come from the active schema. If \`contextFiles.specs\` is absent or empty, mark **Spec Coverage**, **Requirement Implementation Mapping**, and **Scenario Coverage** as not verified; do not treat any of them as clean.
-   - If delta specs exist in \`contextFiles.specs\`:
+   - If status marks the spec artifact skipped by \`skip_specs: true\`, or the schema defines no spec artifact (no artifact whose \`artifactPaths.<id>.outputPath\` is under \`specs/\`), report the spec-dependent checks as not applicable.
+   - Otherwise, \`contextFiles\` is keyed by artifact id, and artifact ids come from the active schema, so do not assume an id such as \`specs\`. The spec artifacts are those whose \`artifactPaths.<id>.outputPath\` is under \`specs/\`; read their files from \`contextFiles.<id>\`. If those spec files are absent or empty, mark **Spec Coverage**, **Requirement Implementation Mapping**, and **Scenario Coverage** as not verified; do not treat any of them as clean.
+   - If delta specs exist in those spec files:
      - Extract all requirements (marked with "### Requirement:", or listed as \`FROM:\`/\`TO:\` pairs under \`## RENAMED Requirements\`) and note the delta section each one sits under: \`## ADDED\`, \`## MODIFIED\`, \`## REMOVED\`, or \`## RENAMED Requirements\`. The section decides what the check looks for.
      - For each ADDED or MODIFIED requirement (for MODIFIED, check the text in the delta, not the old wording):
        - Search codebase for keywords related to the requirement
@@ -336,14 +336,14 @@ ${PROJECT_ROOT_GUARD}
 7. **Verify Coherence**
 
    **Design Adherence**:
-   - If the schema defines no design artifact, report **Design Adherence** as not applicable.
-   - If \`contextFiles.design\` exists:
+   - If the schema defines no design artifact (no artifact with id \`design\`, and none whose \`artifactPaths.<id>.outputPath\` is or ends in \`design.md\`), report **Design Adherence** as not applicable.
+   - If the design artifact's \`contextFiles.<id>\` file exists:
      - Extract key decisions (look for sections like "Decision:", "Approach:", "Architecture:")
      - Verify implementation follows those decisions
      - If contradiction detected:
        - Add WARNING: "Design decision not followed: <decision>"
        - Recommendation: "Update implementation or revise design.md to match reality"
-   - Otherwise, if \`contextFiles.design\` is absent or empty: mark **Design Adherence** as not verified. With other supporting artifacts, **Code Pattern Consistency** still runs; the task-only case remains limited to task completion.
+   - Otherwise, if the design artifact's \`contextFiles.<id>\` file is absent or empty: mark **Design Adherence** as not verified. With other supporting artifacts, **Code Pattern Consistency** still runs; the task-only case remains limited to task completion.
 
    **Code Pattern Consistency**:
    - If implementation changes cannot be identified, mark **Code Pattern Consistency** as not verified and explain the missing evidence.

package/dist/core/validation/validator.js

@@ -252,6 +252,17 @@ export class Validator {
                             message: this.buildMissingShallOrMustMessage(`ADDED "${block.name}"`, block.name, true),
                         });
                     }
+                    // Same limit the main spec enforces after archive (#1976), so
+                    // `validate <change> --strict` catches a new overlong requirement
+                    // before it lands. MODIFIED is left alone: its text is the existing
+                    // requirement, which the specs instruction says to keep whole.
+                    if (requirementText && requirementText.length > MAX_REQUIREMENT_TEXT_LENGTH) {
+                        issues.push({
+                            level: 'WARNING',
+                            path: entryPath,
+                            message: `ADDED "${block.name}": ${VALIDATION_MESSAGES.REQUIREMENT_TOO_LONG}`,
+                        });
+                    }
                     const scenarioCount = this.countScenarios(block.raw);
                     if (scenarioCount < 1) {
                         issues.push({ level: 'ERROR', path: entryPath, message: `ADDED "${block.name}" must include at least one scenario${this.emptyScenarioHint(block.raw)}` });
@@ -711,7 +722,7 @@ export class Validator {
         spec.requirements.forEach((req, index) => {
             if (req.text.length > MAX_REQUIREMENT_TEXT_LENGTH) {
                 issues.push({
-                    level: 'INFO',
+                    level: 'WARNING',
                     path: `requirements[${index}]`,
                     message: VALIDATION_MESSAGES.REQUIREMENT_TOO_LONG,
                 });

package/dist/core/view.js

@@ -52,14 +52,6 @@ export class ViewCommand {
                 console.log(`  ${chalk.green('✓')} ${change.name}`);
             });
         }
-        // Display archived changes
-        if (changesData.archived.length > 0) {
-            console.log(chalk.bold.gray('\nArchived Changes'));
-            console.log('─'.repeat(60));
-            changesData.archived.forEach((change) => {
-                console.log(chalk.gray(`  ◦ ${change.name}`));
-            });
-        }
         // Display specifications
         if (specsData.length > 0) {
             console.log(chalk.bold.blue('\nSpecifications'));
@@ -78,25 +70,11 @@ export class ViewCommand {
         const changesDir = path.join(openspecDir, 'changes');
         const projectRoot = path.dirname(openspecDir);
         if (!fs.existsSync(changesDir)) {
-            return { draft: [], active: [], completed: [], archived: [] };
+            return { draft: [], active: [], completed: [] };
         }
         const draft = [];
         const active = [];
         const completed = [];
-        let archived = [];
-        try {
-            archived = fs.readdirSync(path.join(changesDir, 'archive'), { withFileTypes: true })
-                .filter((entry) => entry.isDirectory() && !entry.name.startsWith('.'))
-                .map((entry) => ({ name: entry.name }));
-        }
-        catch (error) {
-            // A missing archive, or an `archive` path that is a file, has no archived
-            // changes to show; neither should break the rest of the dashboard.
-            const code = error.code;
-            if (code !== 'ENOENT' && code !== 'ENOTDIR') {
-                throw error;
-            }
-        }
         const entries = fs.readdirSync(changesDir, { withFileTypes: true });
         for (const entry of entries) {
             if (entry.isDirectory() && entry.name !== 'archive') {
@@ -136,8 +114,7 @@ export class ViewCommand {
             return a.name.localeCompare(b.name);
         });
         completed.sort((a, b) => a.name.localeCompare(b.name));
-        archived.sort((a, b) => a.name.localeCompare(b.name));
-        return { draft, active, completed, archived };
+        return { draft, active, completed };
     }
     async getSpecsData(openspecDir) {
         const specsDir = path.join(openspecDir, 'specs');
@@ -182,7 +159,6 @@ export class ViewCommand {
         }
         console.log(`  ${chalk.yellow('●')} Active Changes: ${chalk.bold(changesData.active.length)} in progress`);
         console.log(`  ${chalk.green('●')} Completed Changes: ${chalk.bold(changesData.completed.length)}`);
-        console.log(`  ${chalk.gray('●')} Archived Changes: ${chalk.bold(changesData.archived.length)}`);
         if (totalTasks > 0) {
             const overallProgress = Math.round((completedTasks / totalTasks) * 100);
             console.log(`  ${chalk.magenta('●')} Task Progress: ${chalk.bold(`${completedTasks}/${totalTasks}`)} (${overallProgress}% complete)`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fission-ai/openspec",
-  "version": "1.14.0",
+  "version": "1.14.1",
   "description": "AI-native system for spec-driven development",
   "keywords": [
     "openspec",

package/schemas/spec-driven/schema.yaml

@@ -77,6 +77,17 @@ artifacts:
       - New capabilities: use the exact path from the proposal at `specs/<capability-path>/spec.md`. Any path segment newly introduced in the proposal must be kebab-case. Follow the project's existing organization; do not add a new domain level when the project uses a flat layout.
       - Modified capabilities: use the exact existing path from `openspec/specs/<capability-path>/` when creating the delta at `specs/<capability-path>/spec.md`. Run `openspec list --specs` to confirm that path before writing the delta, appending `--store "<id>"` only for a registered standalone store - a mistyped or invented path targets a capability that does not exist rather than the one you meant. Do not move or rename the capability.
 
+      Write the spec files one at a time, so the user sees progress and an
+      interrupted run keeps the files it already wrote:
+      - Before writing anything, compare the capabilities the proposal lists
+        with the `specs/<capability-path>/spec.md` files that already exist,
+        and start with the first capability that has no file. Do not rewrite
+        an existing file unless the user asks you to.
+      - Before each file, say in one line which capability you are writing.
+      - Write each file as soon as you have drafted it. Do not plan every file
+        before writing the first.
+      - Stop when every capability the proposal lists has its file.
+
       There must be at least one spec file unless the change's `.openspec.yaml`
       sets `skip_specs: true` (no spec-level behavior change) - `openspec validate`
       rejects a zero-delta change without that marker. If the proposal lists no
@@ -94,7 +105,7 @@ artifacts:
       - Each scenario: `#### Scenario: <name>` with WHEN/THEN format
       - **CRITICAL**: Scenarios MUST use exactly 4 hashtags (`####`). Using 3 hashtags or bullets will fail silently.
       - Every requirement MUST have at least one scenario.
-      - Keep each requirement's description (the text between `### Requirement:` and its first scenario) to 500 characters or fewer. `openspec validate` flags longer descriptions once they reach the main spec. This is an informational hint, not an error. When writing a new requirement, state one behavior per requirement: move examples and edge cases into scenarios, and split a requirement that covers several behaviors into separate `### Requirement:` blocks, each with its own scenarios. Under MODIFIED, keep the existing requirement block whole; never split, trim or rewrite existing text just to meet the length.
+      - Keep each requirement's description (the text between `### Requirement:` and its first scenario) to 500 characters or fewer. `openspec validate` flags longer descriptions in ADDED requirements and in the main spec. This is a warning: normal validation still passes, but `openspec validate --strict` fails on it. When writing a new requirement, state one behavior per requirement: move examples and edge cases into scenarios, and split a requirement that covers several behaviors into separate `### Requirement:` blocks, each with its own scenarios. Under MODIFIED, keep the existing requirement block whole; never split, trim or rewrite existing text just to meet the length. Split an existing long requirement only when the user asks for it, in a change made for that purpose: under MODIFIED, keep its header and every scenario and cut its description down to one behavior without changing its meaning, then add each behavior you removed as its own ADDED requirement with its own scenarios.
 
       New capabilities only: the delta spec's first section is `## Purpose` -
       one or two sentences (50+ characters, or `openspec validate --strict`
@@ -195,17 +206,22 @@ artifacts:
       would change what gets built, resolve them with the user first - do not
       bake an unstated assumption into the task list.
 
-      **IMPORTANT: Follow the template below exactly.** The apply phase parses
+      **IMPORTANT: Follow the template below for tracked tasks.** The apply phase parses
       checkbox format to track progress. A box holding only `x` counts as done,
       upper or lower case and with any spacing, so `- [ x]` is done too. Every
       other marker, including `- [~]`, `- [-]` and an empty `- []`, reads as
       unfinished. A line with no checkbox is not tracked at all.
 
       Guidelines:
-      - Group related tasks under ## numbered headings
-      - Each task MUST be a checkbox: `- [ ] X.Y Task description`
+      - Group related tracked tasks under ## numbered headings
+      - Each tracked task MUST be a checkbox: `- [ ] X.Y Task description`
       - Tasks should be small enough to complete in one session
       - Order tasks by dependency (what must be done first?)
+      - Track implementation and verification work that can be completed before
+        archive. If the requested workflow includes archive or work that requires
+        this change to be archived, preserve those steps as plain bullets in an
+        optional `## Workflow follow-up` section at the end of tasks.md. These
+        bullets are reference information outside tracked task progress.
       - Each task MUST state how to verify completion (a test, command,
         observable behavior, or delivered artifact). Put the verification in
         that task's checkbox description. Use a separate verification task only
@@ -235,6 +251,14 @@ artifacts:
       - [ ] 2.3 Document the export API in docs/export.md and verify the documented command runs as written
       ```
 
+      When applicable, append workflow follow-up as plain bullets, for example:
+      ```
+      ## Workflow follow-up
+
+      - Archive the change after the project's review requirements are satisfied.
+      - Verify the archived result.
+      ```
+
       Reference specs for what needs to be built, design for how to build it.
     requires:
       - specs