@specsafe/core 0.4.0 → 0.5.0

package/dist/ears/validator.js

@@ -0,0 +1,234 @@
+/**
+ * EARS Validator
+ * Validates requirements against EARS patterns and suggests improvements
+ */
+import { parseEARSRequirement } from './parser.js';
+/**
+ * Validate all requirements in a spec for EARS compliance
+ */
+export function validateRequirements(spec) {
+    const validations = [];
+    for (const requirement of spec.requirements) {
+        const validation = validateRequirement(requirement.text);
+        validations.push(validation);
+    }
+    // Calculate summary
+    const compliantCount = validations.filter(v => v.isCompliant).length;
+    const score = spec.requirements.length > 0
+        ? Math.round((compliantCount / spec.requirements.length) * 100)
+        : 0;
+    // Group by EARS type
+    const typeCounts = new Map();
+    for (const validation of validations) {
+        if (validation.earsRequirement) {
+            const type = validation.earsRequirement.type;
+            typeCounts.set(type, (typeCounts.get(type) || 0) + 1);
+        }
+    }
+    const summary = Array.from(typeCounts.entries()).map(([type, count]) => ({
+        type,
+        count
+    }));
+    // Generate recommendation
+    let recommendation = '';
+    if (score >= 90) {
+        recommendation = '✅ Excellent EARS compliance! Requirements are well-structured and testable.';
+    }
+    else if (score >= 70) {
+        recommendation = '⚠️ Good EARS compliance, but some requirements could be improved for better testability.';
+    }
+    else if (score >= 50) {
+        recommendation = '⚠️ Moderate EARS compliance. Consider rewriting requirements using EARS patterns.';
+    }
+    else {
+        recommendation = '❌ Low EARS compliance. Requirements should be rewritten using EARS patterns for testability.';
+    }
+    return {
+        score,
+        totalRequirements: spec.requirements.length,
+        compliantCount,
+        requirements: validations,
+        summary,
+        recommendation
+    };
+}
+/**
+ * Validate a single requirement text
+ *
+ * Note: A requirement is considered compliant (isCompliant = true) ONLY if it both:
+ * 1. Matches an EARS pattern with sufficient confidence, AND
+ * 2. Has zero quality issues (no ambiguous words, vague terms, etc.)
+ *
+ * @param text - The requirement text to validate
+ * @returns Validation result with compliance status, issues, and suggestions
+ */
+export function validateRequirement(text) {
+    const earsRequirement = parseEARSRequirement(text);
+    const issues = [];
+    let isCompliant = false;
+    let suggestion;
+    // Check if it matches an EARS pattern
+    if (earsRequirement.type === 'unknown') {
+        issues.push('Does not follow any EARS pattern');
+        suggestion = generateEARSSuggestion(text);
+    }
+    else if (earsRequirement.confidence < 0.7) {
+        issues.push('Weak EARS pattern match');
+        suggestion = generateEARSSuggestion(text);
+    }
+    else {
+        isCompliant = true;
+    }
+    // Additional quality checks
+    if (!text.match(/\b(shall|must|will)\b/i)) {
+        issues.push('Missing modal verb (shall/must/will)');
+    }
+    if (text.split(' ').length < 5) {
+        issues.push('Requirement is too short - may lack necessary detail');
+    }
+    if (text.split(' ').length > 40) {
+        issues.push('Requirement is too long - consider splitting into multiple requirements');
+    }
+    // Check for ambiguous words
+    const ambiguousWords = ['should', 'may', 'might', 'could', 'possibly', 'probably', 'usually', 'maybe', 'perhaps'];
+    for (const word of ambiguousWords) {
+        if (new RegExp(`\\b${word}\\b`, 'i').test(text)) {
+            issues.push(`Contains ambiguous word: "${word}"`);
+        }
+    }
+    // Check for vague terms (precompiled with word boundaries to avoid false positives)
+    const vagueTerms = ['appropriate', 'adequate', 'reasonable', 'efficient', 'user-friendly', 'as needed'];
+    const vagueTermPatterns = vagueTerms.map(term => new RegExp(`\\b${term}\\b`, 'i'));
+    for (let i = 0; i < vagueTerms.length; i++) {
+        if (vagueTermPatterns[i].test(text)) {
+            issues.push(`Contains vague term: "${vagueTerms[i]}" - specify measurable criteria`);
+        }
+    }
+    return {
+        text,
+        isCompliant: isCompliant && issues.length === 0,
+        earsRequirement: earsRequirement.type !== 'unknown' ? earsRequirement : undefined,
+        issues,
+        suggestion
+    };
+}
+/**
+ * Generate an EARS-formatted suggestion for a non-compliant requirement
+ */
+function generateEARSSuggestion(text) {
+    // Try to detect implicit patterns and suggest EARS format
+    // If it mentions a trigger condition, suggest event-driven
+    if (/\b(after|once|following|receives|detects|triggers)\b/i.test(text)) {
+        return `Consider event-driven EARS: "When [event occurs], the system shall [action]"\nExample: "When user submits the form, the system shall validate all fields"`;
+    }
+    // If it mentions a state, suggest state-driven
+    if (/\b(during|active|running|enabled|in\s+\w+\s+mode)\b/i.test(text)) {
+        return `Consider state-driven EARS: "While [state exists], the system shall [action]"\nExample: "While user is logged in, the system shall display the dashboard"`;
+    }
+    // If it mentions a condition, suggest optional
+    if (/\b(if|when|in case|for|with)\b/i.test(text) && !/then/i.test(text)) {
+        return `Consider optional EARS: "Where [condition], the system shall [action]"\nExample: "Where user has admin privileges, the system shall allow access to settings"`;
+    }
+    // If it mentions error handling, suggest unwanted
+    if (/\b(error|fail|invalid|incorrect|wrong|exception)\b/i.test(text)) {
+        return `Consider unwanted behavior EARS: "If [unwanted condition], then the system shall [action]"\nExample: "If user enters invalid credentials, then the system shall display an error message"`;
+    }
+    // Default to ubiquitous
+    return `Consider ubiquitous EARS: "The system shall [action]"\nExample: "The system shall encrypt all sensitive data at rest"`;
+}
+/**
+ * Get EARS compliance score for a spec (0-100)
+ */
+export function getEARSScore(spec) {
+    const result = validateRequirements(spec);
+    return result.score;
+}
+/**
+ * Check if a spec meets minimum EARS compliance threshold
+ * @param spec - The spec to check
+ * @param threshold - Minimum score (0-100)
+ * @param precomputedScore - Optional pre-computed score to avoid re-validation
+ */
+export function meetsEARSThreshold(spec, threshold = 80, precomputedScore) {
+    const score = precomputedScore !== undefined ? precomputedScore : getEARSScore(spec);
+    return score >= threshold;
+}
+/**
+ * Generate a detailed EARS compliance report as markdown
+ */
+export function generateEARSReport(spec) {
+    const result = validateRequirements(spec);
+    let report = `# EARS Compliance Report\n\n`;
+    report += `**Spec ID:** ${spec.id}\n`;
+    report += `**Spec Name:** ${spec.name}\n`;
+    report += `**Date:** ${new Date().toISOString().split('T')[0]}\n\n`;
+    report += `## Overall Score: ${result.score}/100\n\n`;
+    report += `${result.recommendation}\n\n`;
+    report += `### Summary\n`;
+    report += `- **Total Requirements:** ${result.totalRequirements}\n`;
+    report += `- **Compliant:** ${result.compliantCount}\n`;
+    report += `- **Non-Compliant:** ${result.totalRequirements - result.compliantCount}\n\n`;
+    if (result.summary.length > 0) {
+        report += `### Requirements by EARS Type\n\n`;
+        for (const { type, count } of result.summary) {
+            const emoji = getEARSTypeEmoji(type);
+            report += `- ${emoji} **${type}:** ${count}\n`;
+        }
+        report += `\n`;
+    }
+    report += `## Detailed Analysis\n\n`;
+    for (let i = 0; i < result.requirements.length; i++) {
+        const validation = result.requirements[i];
+        const status = validation.isCompliant ? '✅' : '❌';
+        report += `### ${status} Requirement ${i + 1}\n\n`;
+        report += `**Text:** "${validation.text}"\n\n`;
+        if (validation.earsRequirement && validation.earsRequirement.type !== 'unknown') {
+            const ears = validation.earsRequirement;
+            report += `**EARS Type:** ${ears.type}\n`;
+            report += `**Confidence:** ${Math.round(ears.confidence * 100)}%\n\n`;
+            if (ears.event)
+                report += `- **Event:** ${ears.event}\n`;
+            if (ears.state)
+                report += `- **State:** ${ears.state}\n`;
+            if (ears.condition)
+                report += `- **Condition:** ${ears.condition}\n`;
+            if (ears.unwantedCondition)
+                report += `- **Unwanted Condition:** ${ears.unwantedCondition}\n`;
+            if (ears.conditions) {
+                report += `- **Conditions:**\n`;
+                for (const cond of ears.conditions) {
+                    report += `  - ${cond.type}: ${cond.value}\n`;
+                }
+            }
+            report += `- **Action:** ${ears.action}\n\n`;
+        }
+        if (validation.issues.length > 0) {
+            report += `**Issues:**\n`;
+            for (const issue of validation.issues) {
+                report += `- ⚠️ ${issue}\n`;
+            }
+            report += `\n`;
+        }
+        if (validation.suggestion) {
+            report += `**Suggestion:**\n${validation.suggestion}\n\n`;
+        }
+        report += `---\n\n`;
+    }
+    return report;
+}
+/**
+ * Get emoji for EARS type
+ */
+function getEARSTypeEmoji(type) {
+    const emojis = {
+        ubiquitous: '🌐',
+        event: '⚡',
+        state: '🔄',
+        optional: '🔀',
+        unwanted: '🚫',
+        complex: '🔗',
+        unknown: '❓'
+    };
+    return emojis[type] || '❓';
+}
+//# sourceMappingURL=validator.js.map

package/dist/ears/validator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"validator.js","sourceRoot":"","sources":["../../src/ears/validator.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -20,7 +20,15 @@
  * ```
  */
 export type { Spec, SpecStage, Requirement, Scenario, QAReport, TestResult, CoverageReport, Issue, ProjectState, SpecSummary, ProjectMetrics } from './types.js';
+export type { DeltaSpec, DeltaRequirement, MergeResult, MergeConflict, MergeStats } from './delta/types.js';
 export { Workflow } from './workflow.js';
 export { ProjectTracker } from './tracker.js';
 export { validateSpecId } from './validation.js';
+export { DeltaParser } from './delta/parser.js';
+export { SemanticMerger } from './delta/merger.js';
+export { generateDeltaTemplate, generateDeltaReadme } from './templates/delta-template.js';
+export type { AgentDefinition, AgentAdapter, AgentRegistryEntry, GenerateOptions, GeneratedFile, } from './agents/index.js';
+export { getAgent, listAgents, getSupportedAgents, isValidAgent, getAgentDefinition, AGENT_DEFINITIONS, } from './agents/index.js';
+export type { EARSType, EARSRequirement, EARSValidationResult, RequirementValidation, } from './ears/index.js';
+export { parseEARSRequirement, hasEARSKeywords, extractRequirements, validateRequirements, validateRequirement, getEARSScore, meetsEARSThreshold, generateEARSReport, generateEARSTemplate, generateEARSExamples, } from './ears/index.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAGH,YAAY,EACV,IAAI,EACJ,SAAS,EACT,WAAW,EACX,QAAQ,EACR,QAAQ,EACR,UAAU,EACV,cAAc,EACd,KAAK,EACL,YAAY,EACZ,WAAW,EACX,cAAc,EACf,MAAM,YAAY,CAAC;AAGpB,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAGzC,OAAO,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAG9C,OAAO,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAGH,YAAY,EACV,IAAI,EACJ,SAAS,EACT,WAAW,EACX,QAAQ,EACR,QAAQ,EACR,UAAU,EACV,cAAc,EACd,KAAK,EACL,YAAY,EACZ,WAAW,EACX,cAAc,EACf,MAAM,YAAY,CAAC;AAGpB,YAAY,EACV,SAAS,EACT,gBAAgB,EAChB,WAAW,EACX,aAAa,EACb,UAAU,EACX,MAAM,kBAAkB,CAAC;AAG1B,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAGzC,OAAO,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAG9C,OAAO,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAGjD,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAChD,OAAO,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AACnD,OAAO,EAAE,qBAAqB,EAAE,mBAAmB,EAAE,MAAM,+BAA+B,CAAC;AAG3F,YAAY,EACV,eAAe,EACf,YAAY,EACZ,kBAAkB,EAClB,eAAe,EACf,aAAa,GACd,MAAM,mBAAmB,CAAC;AAE3B,OAAO,EACL,QAAQ,EACR,UAAU,EACV,kBAAkB,EAClB,YAAY,EACZ,kBAAkB,EAClB,iBAAiB,GAClB,MAAM,mBAAmB,CAAC;AAG3B,YAAY,EACV,QAAQ,EACR,eAAe,EACf,oBAAoB,EACpB,qBAAqB,GACtB,MAAM,iBAAiB,CAAC;AAEzB,OAAO,EACL,oBAAoB,EACpB,eAAe,EACf,mBAAmB,EACnB,oBAAoB,EACpB,mBAAmB,EACnB,YAAY,EACZ,kBAAkB,EAClB,kBAAkB,EAClB,oBAAoB,EACpB,oBAAoB,GACrB,MAAM,iBAAiB,CAAC"}

package/dist/index.js

@@ -25,4 +25,10 @@ export { Workflow } from './workflow.js';
 export { ProjectTracker } from './tracker.js';
 // Validation utilities
 export { validateSpecId } from './validation.js';
+// Delta system
+export { DeltaParser } from './delta/parser.js';
+export { SemanticMerger } from './delta/merger.js';
+export { generateDeltaTemplate, generateDeltaReadme } from './templates/delta-template.js';
+export { getAgent, listAgents, getSupportedAgents, isValidAgent, getAgentDefinition, AGENT_DEFINITIONS, } from './agents/index.js';
+export { parseEARSRequirement, hasEARSKeywords, extractRequirements, validateRequirements, validateRequirement, getEARSScore, meetsEARSThreshold, generateEARSReport, generateEARSTemplate, generateEARSExamples, } from './ears/index.js';
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAiBH,kBAAkB;AAClB,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAEzC,kBAAkB;AAClB,OAAO,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAE9C,uBAAuB;AACvB,OAAO,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AA0BH,kBAAkB;AAClB,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAEzC,kBAAkB;AAClB,OAAO,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAE9C,uBAAuB;AACvB,OAAO,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAEjD,eAAe;AACf,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAChD,OAAO,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AACnD,OAAO,EAAE,qBAAqB,EAAE,mBAAmB,EAAE,MAAM,+BAA+B,CAAC;AAW3F,OAAO,EACL,QAAQ,EACR,UAAU,EACV,kBAAkB,EAClB,YAAY,EACZ,kBAAkB,EAClB,iBAAiB,GAClB,MAAM,mBAAmB,CAAC;AAU3B,OAAO,EACL,oBAAoB,EACpB,eAAe,EACf,mBAAmB,EACnB,oBAAoB,EACpB,mBAAmB,EACnB,YAAY,EACZ,kBAAkB,EAClB,kBAAkB,EAClB,oBAAoB,EACpB,oBAAoB,GACrB,MAAM,iBAAiB,CAAC"}

package/dist/templates/delta-template.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Delta Spec Template
+ * Template for creating delta specs (brownfield changes)
+ */
+/**
+ * Generate a delta spec template
+ * @param deltaId - Delta spec identifier
+ * @param baseSpecId - Base spec this delta applies to
+ * @param author - Author name
+ * @param date - Optional date for testability (defaults to today)
+ */
+export declare function generateDeltaTemplate(deltaId: string, baseSpecId: string, author: string, date?: string): string;
+/**
+ * Generate a README file explaining the delta spec format
+ * @returns Markdown content for delta spec documentation
+ */
+export declare function generateDeltaReadme(): string;
+//# sourceMappingURL=delta-template.d.ts.map

package/dist/templates/delta-template.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"delta-template.d.ts","sourceRoot":"","sources":["../../src/templates/delta-template.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;;;;;GAMG;AACH,wBAAgB,qBAAqB,CACnC,OAAO,EAAE,MAAM,EACf,UAAU,EAAE,MAAM,EAClB,MAAM,EAAE,MAAM,EACd,IAAI,CAAC,EAAE,MAAM,GACZ,MAAM,CAgGR;AAED;;;GAGG;AACH,wBAAgB,mBAAmB,IAAI,MAAM,CA8E5C"}

package/dist/templates/delta-template.js

@@ -0,0 +1,191 @@
+/**
+ * Delta Spec Template
+ * Template for creating delta specs (brownfield changes)
+ */
+/**
+ * Generate a delta spec template
+ * @param deltaId - Delta spec identifier
+ * @param baseSpecId - Base spec this delta applies to
+ * @param author - Author name
+ * @param date - Optional date for testability (defaults to today)
+ */
+export function generateDeltaTemplate(deltaId, baseSpecId, author, date) {
+    const createdDate = date || new Date().toISOString().split('T')[0];
+    return `# Delta Spec: ${deltaId}
+
+**Base Spec:** ${baseSpecId}
+**Created:** ${createdDate}
+**Author:** ${author}
+**Description:** Brief description of changes
+
+---
+
+## Change Summary
+
+What is changing and why?
+
+---
+
+## ADDED Requirements
+
+New requirements being added to the spec.
+
+### FR-NEW-1
+**Priority:** P1
+
+[Requirement text here]
+
+**Scenarios:**
+- Given [context]
+- When [action]
+- Then [outcome]
+
+---
+
+## MODIFIED Requirements
+
+Existing requirements being changed.
+
+### FR-EXISTING-1
+**Priority:** P0
+
+[New requirement text] ← (was [old requirement text])
+
+**Scenarios:**
+- [Updated scenarios]
+
+---
+
+## REMOVED Requirements
+
+Requirements being removed (just list IDs).
+
+- FR-OLD-1
+- FR-OLD-2
+
+---
+
+## Impact Analysis
+
+### Affected Components
+- Component 1
+- Component 2
+
+### Breaking Changes
+- [ ] Yes
+- [x] No
+
+### Migration Required
+- [ ] Yes
+- [x] No
+
+If yes, describe migration path:
+
+---
+
+## Testing Strategy
+
+### Tests to Add
+-
+
+### Tests to Update
+-
+
+### Tests to Remove
+-
+
+---
+
+## Notes
+
+Additional context, links, or references.
+
+---
+
+*Generated by SpecSafe Delta System*
+`;
+}
+/**
+ * Generate a README file explaining the delta spec format
+ * @returns Markdown content for delta spec documentation
+ */
+export function generateDeltaReadme() {
+    return `# Delta Specs
+
+Delta specs describe **incremental changes** to existing specs (brownfield projects).
+
+## Format
+
+Delta specs use three sections:
+
+### ADDED Requirements
+New requirements being added. Each requirement includes:
+- **ID**: Unique requirement ID (e.g., FR-NEW-1)
+- **Priority**: P0, P1, or P2
+- **Text**: Requirement description
+- **Scenarios**: Given/When/Then scenarios
+
+### MODIFIED Requirements
+Existing requirements being changed. Use the notation:
+\`\`\`
+[New text] ← (was [old text])
+\`\`\`
+
+### REMOVED Requirements
+Requirements being removed. Just list the IDs:
+\`\`\`
+- FR-OLD-1
+- FR-OLD-2
+\`\`\`
+
+## Workflow
+
+1. **Create Delta**: \`specsafe delta <spec-id>\`
+   - Opens a template for the delta spec
+   - Edit to describe changes
+
+2. **Preview Changes**: \`specsafe diff <spec-id>\`
+   - Shows what would change
+   - Identifies conflicts
+
+3. **Apply Delta**: \`specsafe apply <spec-id>\`
+   - Merges changes into base spec
+   - Creates backup before applying
+
+## Best Practices
+
+- Keep deltas focused (one feature/fix at a time)
+- Include clear change justification
+- Document breaking changes
+- Update tests alongside requirements
+- Review conflicts before applying
+
+## Example
+
+\`\`\`markdown
+## ADDED Requirements
+
+### FR-AUTH-3
+**Priority:** P0
+
+Users must be able to reset their password via email verification.
+
+**Scenarios:**
+- Given user is on login page
+- When user clicks "Forgot Password"
+- Then system sends reset link to registered email
+
+## MODIFIED Requirements
+
+### FR-AUTH-1
+**Priority:** P0
+
+Users must authenticate using email and password with 2FA enabled ← (was Users must authenticate using email and password)
+
+## REMOVED Requirements
+
+- FR-AUTH-OLD-1
+\`\`\`
+`;
+}
+//# sourceMappingURL=delta-template.js.map

package/dist/templates/delta-template.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"delta-template.js","sourceRoot":"","sources":["../../src/templates/delta-template.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;;;;;GAMG;AACH,MAAM,UAAU,qBAAqB,CACnC,OAAe,EACf,UAAkB,EAClB,MAAc,EACd,IAAa;IAEb,MAAM,WAAW,GAAG,IAAI,IAAI,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;IAEnE,OAAO,iBAAiB,OAAO;;iBAEhB,UAAU;eACZ,WAAW;cACZ,MAAM;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAwFnB,CAAC;AACF,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,mBAAmB;IACjC,OAAO;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA4ER,CAAC;AACF,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@specsafe/core",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Core types and workflow engine for SpecSafe",
   "type": "module",
   "engines": {