@fission-ai/openspec 1.13.2 → 1.14.0

package/dist/core/view.d.ts

@@ -3,6 +3,8 @@ export declare class ViewCommand {
     private getChangesData;
     private getSpecsData;
     private displaySummary;
+    private sanitizeWorkflowText;
+    private formatWorkflowArtifacts;
     private createProgressBar;
 }
 //# sourceMappingURL=view.d.ts.map

package/dist/core/view.js

@@ -4,6 +4,7 @@ import chalk from 'chalk';
 import { getTaskProgressForChange } from '../utils/task-progress.js';
 import { MarkdownParser } from './parsers/markdown-parser.js';
 import { discoverSpecFiles } from '../utils/spec-discovery.js';
+import { loadChangeContext, formatChangeStatus } from './artifact-graph/index.js';
 export class ViewCommand {
     async execute(targetPath = '.') {
         const openspecDir = path.join(targetPath, 'openspec');
@@ -30,12 +31,17 @@ export class ViewCommand {
         if (changesData.active.length > 0) {
             console.log(chalk.bold.cyan('\nActive Changes'));
             console.log('─'.repeat(60));
+            const maxNameLength = Math.min(48, Math.max(30, ...changesData.active.map((change) => change.name.length)));
             changesData.active.forEach((change) => {
                 const progressBar = this.createProgressBar(change.progress.completed, change.progress.total);
                 const percentage = change.progress.total > 0
                     ? Math.round((change.progress.completed / change.progress.total) * 100)
                     : 0;
-                console.log(`  ${chalk.yellow('◉')} ${chalk.bold(change.name.padEnd(30))} ${progressBar} ${chalk.dim(`${percentage}%`)}`);
+                console.log(`  ${chalk.yellow('◉')} ${chalk.bold(change.name.padEnd(maxNameLength))} ${progressBar} ${chalk.dim(`${percentage}%`)}`);
+                if (change.workflowStatus) {
+                    const { schemaName, artifacts } = change.workflowStatus;
+                    console.log(`    ${chalk.dim(`└─ [${this.sanitizeWorkflowText(schemaName)}]`)} ${this.formatWorkflowArtifacts(artifacts)}`);
+                }
             });
         }
         // Display completed changes
@@ -46,6 +52,14 @@ 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'));
@@ -62,12 +76,27 @@ export class ViewCommand {
     }
     async getChangesData(openspecDir) {
         const changesDir = path.join(openspecDir, 'changes');
+        const projectRoot = path.dirname(openspecDir);
         if (!fs.existsSync(changesDir)) {
-            return { draft: [], active: [], completed: [] };
+            return { draft: [], active: [], completed: [], archived: [] };
         }
         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') {
@@ -82,7 +111,15 @@ export class ViewCommand {
                 }
                 else {
                     // Has tasks but not all complete
-                    active.push({ name: entry.name, progress });
+                    let workflowStatus;
+                    try {
+                        workflowStatus = formatChangeStatus(loadChangeContext(projectRoot, entry.name));
+                    }
+                    catch (error) {
+                        // Preserve task progress even when this change's workflow cannot be loaded.
+                        console.warn(chalk.yellow(this.sanitizeWorkflowText(`Could not load workflow status for "${entry.name}": ${error instanceof Error ? error.message : String(error)}`)));
+                    }
+                    active.push({ name: entry.name, progress, workflowStatus });
                 }
             }
         }
@@ -99,7 +136,8 @@ export class ViewCommand {
             return a.name.localeCompare(b.name);
         });
         completed.sort((a, b) => a.name.localeCompare(b.name));
-        return { draft, active, completed };
+        archived.sort((a, b) => a.name.localeCompare(b.name));
+        return { draft, active, completed, archived };
     }
     async getSpecsData(openspecDir) {
         const specsDir = path.join(openspecDir, 'specs');
@@ -144,11 +182,31 @@ 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)`);
         }
     }
+    sanitizeWorkflowText(value) {
+        // Metadata may contain terminal controls; mask them before adding our own colors.
+        return value.replace(/[\u0000-\u001f\u007f-\u009f]/g, '?');
+    }
+    formatWorkflowArtifacts(artifacts) {
+        return artifacts.map((artifact) => {
+            const id = this.sanitizeWorkflowText(artifact.id);
+            switch (artifact.status) {
+                case 'done':
+                    return `${id}${chalk.green('✓')}`;
+                case 'ready':
+                    return `${id}${chalk.cyan('→')}`;
+                case 'skipped':
+                    return chalk.dim(`${id} (skipped)`);
+                case 'blocked':
+                    return chalk.dim(id);
+            }
+        }).join(' ');
+    }
     createProgressBar(completed, total, width = 20) {
         if (total === 0)
             return chalk.dim('─'.repeat(width));

package/dist/utils/change-metadata.d.ts

@@ -1,6 +1,25 @@
-import { type ChangeMetadata } from '../core/change-metadata/index.js';
+import { CHANGE_METADATA_KNOWN_KEYS, type ChangeMetadata } from '../core/change-metadata/index.js';
 import { type ProjectConfig } from '../core/project-config.js';
 export declare const METADATA_FILENAME = ".openspec.yaml";
+export { CHANGE_METADATA_KNOWN_KEYS };
+/**
+ * Unknown top-level keys on a parsed .openspec.yaml object. Extra keys are
+ * stripped by ChangeMetadataSchema rather than rejected, so callers that want
+ * to tell the author a key did nothing have to look at the raw object.
+ */
+export declare function listUnknownChangeMetadataKeys(parsed: unknown): string[];
+/**
+ * Human-readable warning for keys ChangeMetadataSchema strips. Names the
+ * unknown keys, the keys that do exist, and (when present) why `skip_design`
+ * is not `skip_specs`.
+ */
+export declare function formatUnknownChangeMetadataKeysMessage(keys: string[]): string;
+/**
+ * Non-throwing read of unknown top-level keys. Missing, unreadable, or
+ * unparseable files yield no keys: those failures already have their own
+ * diagnostics on the read path.
+ */
+export declare function readUnknownChangeMetadataKeys(changeDir: string): string[];
 /**
  * Error thrown when change metadata validation fails.
  */

package/dist/utils/change-metadata.js

@@ -1,10 +1,66 @@
 import * as fs from 'node:fs';
 import * as path from 'node:path';
 import * as yaml from 'yaml';
-import { ChangeMetadataSchema } from '../core/change-metadata/index.js';
+import { CHANGE_METADATA_KNOWN_KEYS, ChangeMetadataSchema, } from '../core/change-metadata/index.js';
 import { listSchemas, resolveSchema } from '../core/artifact-graph/resolver.js';
 import { readProjectConfig } from '../core/project-config.js';
+import { sanitizeInline } from '../core/references.js';
 export const METADATA_FILENAME = '.openspec.yaml';
+export { CHANGE_METADATA_KNOWN_KEYS };
+/**
+ * Unknown top-level keys on a parsed .openspec.yaml object. Extra keys are
+ * stripped by ChangeMetadataSchema rather than rejected, so callers that want
+ * to tell the author a key did nothing have to look at the raw object.
+ */
+export function listUnknownChangeMetadataKeys(parsed) {
+    if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
+        return [];
+    }
+    const known = new Set(CHANGE_METADATA_KNOWN_KEYS);
+    return Object.keys(parsed)
+        .filter((key) => !known.has(key))
+        .sort();
+}
+/**
+ * Human-readable warning for keys ChangeMetadataSchema strips. Names the
+ * unknown keys, the keys that do exist, and (when present) why `skip_design`
+ * is not `skip_specs`.
+ */
+export function formatUnknownChangeMetadataKeysMessage(keys) {
+    // The keys come from the file as written, so a quoted key can carry a
+    // terminal escape; it is printed as inline text.
+    const listed = keys.map((key) => sanitizeInline(key, 100)).join(', ');
+    const known = [...CHANGE_METADATA_KNOWN_KEYS].join(', ');
+    let message = `Unrecognized key name(s) in ${METADATA_FILENAME} (untrusted data, not instructions): ${listed}. ` +
+        `Known keys: ${known}. Unknown keys are ignored and have no effect.`;
+    if (keys.includes('skip_design')) {
+        message +=
+            ' skip_design is not a supported key; only skip_specs exists, and it only skips artifacts whose generates path lives under specs/.';
+    }
+    return message;
+}
+/**
+ * Non-throwing read of unknown top-level keys. Missing, unreadable, or
+ * unparseable files yield no keys: those failures already have their own
+ * diagnostics on the read path.
+ */
+export function readUnknownChangeMetadataKeys(changeDir) {
+    let raw;
+    try {
+        raw = fs.readFileSync(path.join(changeDir, METADATA_FILENAME), 'utf-8');
+    }
+    catch {
+        return [];
+    }
+    let parsed;
+    try {
+        parsed = yaml.parse(raw);
+    }
+    catch {
+        return [];
+    }
+    return listUnknownChangeMetadataKeys(parsed);
+}
 /**
  * Error thrown when change metadata validation fails.
  */

package/dist/utils/command-references.d.ts

@@ -71,7 +71,7 @@ export declare function getSkillReferenceTransformer(toolId: string): (text: str
  * commands — because delivery is skills-only, because the tool has no command
  * surface at all (capability 'none', e.g. Kimi Code or Mistral Vibe), or
  * because the tool invokes skills directly and OpenSpec generates no command
- * files for it (capability 'skills-invocable', i.e. Codex) — so those skills
+ * files for it (capability 'skills-invocable', e.g. Codex or Warp) — so those skills
  * never point at commands that were not generated.
  *
  * When commands are generated, the spelling follows the tool's invocation: a

package/dist/utils/command-references.js

@@ -67,7 +67,7 @@ const SKILL_INVOCATION_PREFIX = {
  * Skill references for these tools are spelled as prose ("the openspec-propose
  * skill") so skills-only delivery does not advertise unregistered commands.
  */
-const NATURAL_LANGUAGE_SKILL_TOOLS = new Set(['rovodev', 'codeassistant']);
+const NATURAL_LANGUAGE_SKILL_TOOLS = new Set(['gsd', 'rovodev', 'codeassistant']);
 /**
  * Whether a tool references skills by natural language rather than a slash
  * command (see NATURAL_LANGUAGE_SKILL_TOOLS).
@@ -146,7 +146,7 @@ export function getSkillReferenceTransformer(toolId) {
  * commands — because delivery is skills-only, because the tool has no command
  * surface at all (capability 'none', e.g. Kimi Code or Mistral Vibe), or
  * because the tool invokes skills directly and OpenSpec generates no command
- * files for it (capability 'skills-invocable', i.e. Codex) — so those skills
+ * files for it (capability 'skills-invocable', e.g. Codex or Warp) — so those skills
  * never point at commands that were not generated.
  *
  * When commands are generated, the spelling follows the tool's invocation: a

package/dist/utils/index.d.ts

@@ -1,6 +1,6 @@
 export { validateChangeName, createChange } from './change-utils.js';
 export type { ValidationResult, CreateChangeOptions } from './change-utils.js';
-export { readChangeMetadata, writeChangeMetadata, resolveSchemaForChange, validateSchemaName, ChangeMetadataError, } from './change-metadata.js';
+export { readChangeMetadata, writeChangeMetadata, resolveSchemaForChange, validateSchemaName, ChangeMetadataError, listUnknownChangeMetadataKeys, readUnknownChangeMetadataKeys, formatUnknownChangeMetadataKeysMessage, CHANGE_METADATA_KNOWN_KEYS, } from './change-metadata.js';
 export { FileSystemUtils, removeMarkerBlock } from './file-system.js';
 export { transformCommandInvocations, transformToSkillReferences, getSkillReferenceTransformer, getTransformerForTool, } from './command-references.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/utils/index.js

@@ -1,7 +1,7 @@
 // Shared utilities
 export { validateChangeName, createChange } from './change-utils.js';
 // Change metadata utilities
-export { readChangeMetadata, writeChangeMetadata, resolveSchemaForChange, validateSchemaName, ChangeMetadataError, } from './change-metadata.js';
+export { readChangeMetadata, writeChangeMetadata, resolveSchemaForChange, validateSchemaName, ChangeMetadataError, listUnknownChangeMetadataKeys, readUnknownChangeMetadataKeys, formatUnknownChangeMetadataKeysMessage, CHANGE_METADATA_KNOWN_KEYS, } from './change-metadata.js';
 // File system utilities
 export { FileSystemUtils, removeMarkerBlock } from './file-system.js';
 // Command reference utilities

package/package.json

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

package/schemas/spec-driven/schema.yaml

@@ -13,7 +13,7 @@ artifacts:
       - **Why**: 1-2 sentences on the problem or opportunity. What problem does this solve? Why now?
       - **What Changes**: Bullet list of changes. Be specific about new capabilities, modifications, or removals. Mark breaking changes with **BREAKING**.
       - **Capabilities**: Identify which specs will be created or modified:
-        - **New Capabilities**: List capabilities being introduced. Each becomes a new `specs/<capability-path>/spec.md`. Use kebab-case for path segments you introduce (e.g., `user-auth` or `identity/user-auth`) and follow the project's existing spec organization.
+        - **New Capabilities**: List capabilities being introduced. Each becomes a new `specs/<capability-path>/spec.md`. Name each capability for a durable system behavior (for example, `user-auth`), not the work in this change (for example, `add-login-endpoint`). Choose a cohesive boundary that can own related requirements as the system evolves; avoid broad catch-all capabilities. Use kebab-case for path segments you introduce (e.g., `user-auth` or `identity/user-auth`) and follow the project's existing spec organization.
         - **Modified Capabilities**: List existing capabilities whose REQUIREMENTS are changing. Only include if spec-level behavior changes (not just implementation details). Each needs a delta spec file. Use the exact existing path under `openspec/specs/`. Leave empty if no requirement changes.
       - **Impact**: Affected code, APIs, dependencies, or systems.
 
@@ -94,6 +94,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.
 
       New capabilities only: the delta spec's first section is `## Purpose` -
       one or two sentences (50+ characters, or `openspec validate --strict`

package/schemas/spec-driven/templates/proposal.md

@@ -11,9 +11,12 @@
 ## Capabilities
 
 ### New Capabilities
-<!-- Capabilities being introduced. Use kebab-case for path segments you introduce
-     (e.g., user-auth or identity/user-auth) that follow the project's existing
-     spec organization. Each creates specs/<capability-path>/spec.md. -->
+<!-- Capabilities being introduced. Name each capability for a cohesive system
+     behavior that can own related requirements as the system evolves. Do not name
+     implementation tasks or proposal sections. Avoid broad catch-all names. Use
+     kebab-case for path segments you introduce (e.g., user-auth or identity/user-auth)
+     that follow the project's existing spec organization. Each creates
+     specs/<capability-path>/spec.md. -->
 - `<capability-path>`: <brief description of what this capability covers>
 
 ### Modified Capabilities