@specsafe/core 0.4.0 → 0.6.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/elicitation/engine.d.ts

@@ -0,0 +1,75 @@
+/**
+ * Elicitation Engine
+ * Manages interactive specification elicitation workflows
+ */
+import type { ElicitationFlow, ElicitationStep, ElicitationResult } from './types.js';
+/**
+ * Engine for running elicitation flows
+ *
+ * @example
+ * ```typescript
+ * const engine = new ElicitationEngine(quickFlow);
+ * const firstStep = engine.start();
+ *
+ * while (!engine.isComplete()) {
+ *   const current = engine.getCurrentStep();
+ *   const userAnswer = await getUserInput(current);
+ *   const nextStep = engine.answer(current.id, userAnswer);
+ * }
+ *
+ * const result = engine.getResult();
+ * ```
+ */
+export declare class ElicitationEngine {
+    private flow;
+    private answers;
+    private skipped;
+    private currentIndex;
+    private startedAt;
+    private completedAt;
+    /**
+     * Create a new elicitation engine
+     * @param flow The elicitation flow to execute
+     */
+    constructor(flow: ElicitationFlow);
+    /**
+     * Start the elicitation flow
+     * @returns The first step to present to the user, or null if no valid steps
+     */
+    start(): ElicitationStep | null;
+    /**
+     * Record an answer and move to the next step
+     * @param stepId The step ID being answered
+     * @param value The user's answer
+     * @returns The next step, or null if flow is complete
+     */
+    answer(stepId: string, value: any): ElicitationStep | null;
+    /**
+     * Skip a step (only allowed if not required)
+     * @param stepId The step ID to skip
+     * @returns The next step, or null if flow is complete
+     */
+    skip(stepId: string): ElicitationStep | null;
+    /**
+     * Get the current step
+     * @returns The current step, or null if not started or completed
+     */
+    getCurrentStep(): ElicitationStep | null;
+    /**
+     * Check if the flow is complete
+     * @returns True if all steps have been processed
+     */
+    isComplete(): boolean;
+    /**
+     * Get the elicitation result
+     * @returns The complete result with answers and metadata
+     */
+    getResult(): ElicitationResult;
+    /**
+     * Find the next valid step, skipping conditional steps that don't match
+     * @param startIndex Index to start searching from
+     * @returns The next valid step, or null if flow is complete
+     */
+    private getNextValidStep;
+}
+//# sourceMappingURL=engine.d.ts.map

package/dist/elicitation/engine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"engine.d.ts","sourceRoot":"","sources":["../../src/elicitation/engine.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EACV,eAAe,EACf,eAAe,EACf,iBAAiB,EAClB,MAAM,YAAY,CAAC;AAEpB;;;;;;;;;;;;;;;;GAgBG;AACH,qBAAa,iBAAiB;IAC5B,OAAO,CAAC,IAAI,CAAkB;IAC9B,OAAO,CAAC,OAAO,CAA2B;IAC1C,OAAO,CAAC,OAAO,CAAgB;IAC/B,OAAO,CAAC,YAAY,CAAc;IAClC,OAAO,CAAC,SAAS,CAAqB;IACtC,OAAO,CAAC,WAAW,CAAqB;IAExC;;;OAGG;gBACS,IAAI,EAAE,eAAe;IAIjC;;;OAGG;IACH,KAAK,IAAI,eAAe,GAAG,IAAI;IAM/B;;;;;OAKG;IACH,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,GAAG,GAAG,eAAe,GAAG,IAAI;IA0C1D;;;;OAIG;IACH,IAAI,CAAC,MAAM,EAAE,MAAM,GAAG,eAAe,GAAG,IAAI;IA8B5C;;;OAGG;IACH,cAAc,IAAI,eAAe,GAAG,IAAI;IAOxC;;;OAGG;IACH,UAAU,IAAI,OAAO;IAIrB;;;OAGG;IACH,SAAS,IAAI,iBAAiB;IAgB9B;;;;OAIG;IACH,OAAO,CAAC,gBAAgB;CAuBzB"}

package/dist/elicitation/engine.js

@@ -0,0 +1,174 @@
+/**
+ * Elicitation Engine
+ * Manages interactive specification elicitation workflows
+ */
+/**
+ * Engine for running elicitation flows
+ *
+ * @example
+ * ```typescript
+ * const engine = new ElicitationEngine(quickFlow);
+ * const firstStep = engine.start();
+ *
+ * while (!engine.isComplete()) {
+ *   const current = engine.getCurrentStep();
+ *   const userAnswer = await getUserInput(current);
+ *   const nextStep = engine.answer(current.id, userAnswer);
+ * }
+ *
+ * const result = engine.getResult();
+ * ```
+ */
+export class ElicitationEngine {
+    flow;
+    answers = {};
+    skipped = [];
+    currentIndex = -1;
+    startedAt = null;
+    completedAt = null;
+    /**
+     * Create a new elicitation engine
+     * @param flow The elicitation flow to execute
+     */
+    constructor(flow) {
+        this.flow = flow;
+    }
+    /**
+     * Start the elicitation flow
+     * @returns The first step to present to the user, or null if no valid steps
+     */
+    start() {
+        this.startedAt = new Date();
+        this.currentIndex = 0;
+        return this.getNextValidStep(0);
+    }
+    /**
+     * Record an answer and move to the next step
+     * @param stepId The step ID being answered
+     * @param value The user's answer
+     * @returns The next step, or null if flow is complete
+     */
+    answer(stepId, value) {
+        const step = this.flow.steps.find(s => s.id === stepId);
+        if (!step) {
+            throw new Error(`Step not found: ${stepId}`);
+        }
+        // Validate required fields
+        if (step.required && (value === null || value === undefined || value === '')) {
+            throw new Error(`Step '${stepId}' is required`);
+        }
+        // Run custom validation if present
+        if (step.validate) {
+            const validationResult = step.validate(value);
+            if (validationResult !== true) {
+                const errorMessage = typeof validationResult === 'string'
+                    ? validationResult
+                    : `Validation failed for step '${stepId}'`;
+                throw new Error(errorMessage);
+            }
+        }
+        // Store the answer
+        this.answers[stepId] = value;
+        // Move to next step
+        const currentStepIndex = this.flow.steps.findIndex(s => s.id === stepId);
+        if (currentStepIndex === -1) {
+            throw new Error(`Step not found in flow: ${stepId}`);
+        }
+        this.currentIndex = currentStepIndex + 1;
+        // Check if we've completed all steps
+        if (this.currentIndex >= this.flow.steps.length) {
+            this.completedAt = new Date();
+            return null;
+        }
+        return this.getNextValidStep(this.currentIndex);
+    }
+    /**
+     * Skip a step (only allowed if not required)
+     * @param stepId The step ID to skip
+     * @returns The next step, or null if flow is complete
+     */
+    skip(stepId) {
+        const step = this.flow.steps.find(s => s.id === stepId);
+        if (!step) {
+            throw new Error(`Step not found: ${stepId}`);
+        }
+        if (step.required) {
+            throw new Error(`Cannot skip required step: ${stepId}`);
+        }
+        // Mark as skipped
+        this.skipped.push(stepId);
+        // Move to next step
+        const currentStepIndex = this.flow.steps.findIndex(s => s.id === stepId);
+        if (currentStepIndex === -1) {
+            throw new Error(`Step not found in flow: ${stepId}`);
+        }
+        this.currentIndex = currentStepIndex + 1;
+        // Check if we've completed all steps
+        if (this.currentIndex >= this.flow.steps.length) {
+            this.completedAt = new Date();
+            return null;
+        }
+        return this.getNextValidStep(this.currentIndex);
+    }
+    /**
+     * Get the current step
+     * @returns The current step, or null if not started or completed
+     */
+    getCurrentStep() {
+        if (this.currentIndex < 0 || this.currentIndex >= this.flow.steps.length) {
+            return null;
+        }
+        return this.flow.steps[this.currentIndex];
+    }
+    /**
+     * Check if the flow is complete
+     * @returns True if all steps have been processed
+     */
+    isComplete() {
+        return this.completedAt !== null;
+    }
+    /**
+     * Get the elicitation result
+     * @returns The complete result with answers and metadata
+     */
+    getResult() {
+        if (!this.startedAt) {
+            throw new Error('Elicitation has not been started');
+        }
+        return {
+            flowId: this.flow.id,
+            answers: { ...this.answers },
+            metadata: {
+                startedAt: this.startedAt,
+                completedAt: this.completedAt || new Date(),
+                skipped: [...this.skipped],
+            },
+        };
+    }
+    /**
+     * Find the next valid step, skipping conditional steps that don't match
+     * @param startIndex Index to start searching from
+     * @returns The next valid step, or null if flow is complete
+     */
+    getNextValidStep(startIndex) {
+        for (let i = startIndex; i < this.flow.steps.length; i++) {
+            const step = this.flow.steps[i];
+            // Check if step has a condition
+            if (step.condition) {
+                const shouldShow = step.condition(this.answers);
+                if (!shouldShow) {
+                    // Skip this step
+                    this.skipped.push(step.id);
+                    continue;
+                }
+            }
+            // Found a valid step
+            this.currentIndex = i;
+            return step;
+        }
+        // No more valid steps - mark as complete and return null
+        this.completedAt = new Date();
+        return null;
+    }
+}
+//# sourceMappingURL=engine.js.map

package/dist/elicitation/engine.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"engine.js","sourceRoot":"","sources":["../../src/elicitation/engine.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAQH;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,OAAO,iBAAiB;IACpB,IAAI,CAAkB;IACtB,OAAO,GAAwB,EAAE,CAAC;IAClC,OAAO,GAAa,EAAE,CAAC;IACvB,YAAY,GAAW,CAAC,CAAC,CAAC;IAC1B,SAAS,GAAgB,IAAI,CAAC;IAC9B,WAAW,GAAgB,IAAI,CAAC;IAExC;;;OAGG;IACH,YAAY,IAAqB;QAC/B,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;IACnB,CAAC;IAED;;;OAGG;IACH,KAAK;QACH,IAAI,CAAC,SAAS,GAAG,IAAI,IAAI,EAAE,CAAC;QAC5B,IAAI,CAAC,YAAY,GAAG,CAAC,CAAC;QACtB,OAAO,IAAI,CAAC,gBAAgB,CAAC,CAAC,CAAC,CAAC;IAClC,CAAC;IAED;;;;;OAKG;IACH,MAAM,CAAC,MAAc,EAAE,KAAU;QAC/B,MAAM,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,KAAK,MAAM,CAAC,CAAC;QACxD,IAAI,CAAC,IAAI,EAAE,CAAC;YACV,MAAM,IAAI,KAAK,CAAC,mBAAmB,MAAM,EAAE,CAAC,CAAC;QAC/C,CAAC;QAED,2BAA2B;QAC3B,IAAI,IAAI,CAAC,QAAQ,IAAI,CAAC,KAAK,KAAK,IAAI,IAAI,KAAK,KAAK,SAAS,IAAI,KAAK,KAAK,EAAE,CAAC,EAAE,CAAC;YAC7E,MAAM,IAAI,KAAK,CAAC,SAAS,MAAM,eAAe,CAAC,CAAC;QAClD,CAAC;QAED,mCAAmC;QACnC,IAAI,IAAI,CAAC,QAAQ,EAAE,CAAC;YAClB,MAAM,gBAAgB,GAAG,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;YAC9C,IAAI,gBAAgB,KAAK,IAAI,EAAE,CAAC;gBAC9B,MAAM,YAAY,GAAG,OAAO,gBAAgB,KAAK,QAAQ;oBACvD,CAAC,CAAC,gBAAgB;oBAClB,CAAC,CAAC,+BAA+B,MAAM,GAAG,CAAC;gBAC7C,MAAM,IAAI,KAAK,CAAC,YAAY,CAAC,CAAC;YAChC,CAAC;QACH,CAAC;QAED,mBAAmB;QACnB,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,GAAG,KAAK,CAAC;QAE7B,oBAAoB;QACpB,MAAM,gBAAgB,GAAG,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,KAAK,MAAM,CAAC,CAAC;QACzE,IAAI,gBAAgB,KAAK,CAAC,CAAC,EAAE,CAAC;YAC5B,MAAM,IAAI,KAAK,CAAC,2BAA2B,MAAM,EAAE,CAAC,CAAC;QACvD,CAAC;QAED,IAAI,CAAC,YAAY,GAAG,gBAAgB,GAAG,CAAC,CAAC;QAEzC,qCAAqC;QACrC,IAAI,IAAI,CAAC,YAAY,IAAI,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,MAAM,EAAE,CAAC;YAChD,IAAI,CAAC,WAAW,GAAG,IAAI,IAAI,EAAE,CAAC;YAC9B,OAAO,IAAI,CAAC;QACd,CAAC;QAED,OAAO,IAAI,CAAC,gBAAgB,CAAC,IAAI,CAAC,YAAY,CAAC,CAAC;IAClD,CAAC;IAED;;;;OAIG;IACH,IAAI,CAAC,MAAc;QACjB,MAAM,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,KAAK,MAAM,CAAC,CAAC;QACxD,IAAI,CAAC,IAAI,EAAE,CAAC;YACV,MAAM,IAAI,KAAK,CAAC,mBAAmB,MAAM,EAAE,CAAC,CAAC;QAC/C,CAAC;QAED,IAAI,IAAI,CAAC,QAAQ,EAAE,CAAC;YAClB,MAAM,IAAI,KAAK,CAAC,8BAA8B,MAAM,EAAE,CAAC,CAAC;QAC1D,CAAC;QAED,kBAAkB;QAClB,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;QAE1B,oBAAoB;QACpB,MAAM,gBAAgB,GAAG,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,KAAK,MAAM,CAAC,CAAC;QACzE,IAAI,gBAAgB,KAAK,CAAC,CAAC,EAAE,CAAC;YAC5B,MAAM,IAAI,KAAK,CAAC,2BAA2B,MAAM,EAAE,CAAC,CAAC;QACvD,CAAC;QAED,IAAI,CAAC,YAAY,GAAG,gBAAgB,GAAG,CAAC,CAAC;QAEzC,qCAAqC;QACrC,IAAI,IAAI,CAAC,YAAY,IAAI,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,MAAM,EAAE,CAAC;YAChD,IAAI,CAAC,WAAW,GAAG,IAAI,IAAI,EAAE,CAAC;YAC9B,OAAO,IAAI,CAAC;QACd,CAAC;QAED,OAAO,IAAI,CAAC,gBAAgB,CAAC,IAAI,CAAC,YAAY,CAAC,CAAC;IAClD,CAAC;IAED;;;OAGG;IACH,cAAc;QACZ,IAAI,IAAI,CAAC,YAAY,GAAG,CAAC,IAAI,IAAI,CAAC,YAAY,IAAI,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,MAAM,EAAE,CAAC;YACzE,OAAO,IAAI,CAAC;QACd,CAAC;QACD,OAAO,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,YAAY,CAAC,CAAC;IAC5C,CAAC;IAED;;;OAGG;IACH,UAAU;QACR,OAAO,IAAI,CAAC,WAAW,KAAK,IAAI,CAAC;IACnC,CAAC;IAED;;;OAGG;IACH,SAAS;QACP,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,CAAC;YACpB,MAAM,IAAI,KAAK,CAAC,kCAAkC,CAAC,CAAC;QACtD,CAAC;QAED,OAAO;YACL,MAAM,EAAE,IAAI,CAAC,IAAI,CAAC,EAAE;YACpB,OAAO,EAAE,EAAE,GAAG,IAAI,CAAC,OAAO,EAAE;YAC5B,QAAQ,EAAE;gBACR,SAAS,EAAE,IAAI,CAAC,SAAS;gBACzB,WAAW,EAAE,IAAI,CAAC,WAAW,IAAI,IAAI,IAAI,EAAE;gBAC3C,OAAO,EAAE,CAAC,GAAG,IAAI,CAAC,OAAO,CAAC;aAC3B;SACF,CAAC;IACJ,CAAC;IAED;;;;OAIG;IACK,gBAAgB,CAAC,UAAkB;QACzC,KAAK,IAAI,CAAC,GAAG,UAAU,EAAE,CAAC,GAAG,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;YACzD,MAAM,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;YAEhC,gCAAgC;YAChC,IAAI,IAAI,CAAC,SAAS,EAAE,CAAC;gBACnB,MAAM,UAAU,GAAG,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;gBAChD,IAAI,CAAC,UAAU,EAAE,CAAC;oBAChB,iBAAiB;oBACjB,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;oBAC3B,SAAS;gBACX,CAAC;YACH,CAAC;YAED,qBAAqB;YACrB,IAAI,CAAC,YAAY,GAAG,CAAC,CAAC;YACtB,OAAO,IAAI,CAAC;QACd,CAAC;QAED,yDAAyD;QACzD,IAAI,CAAC,WAAW,GAAG,IAAI,IAAI,EAAE,CAAC;QAC9B,OAAO,IAAI,CAAC;IACd,CAAC;CACF"}

package/dist/elicitation/flows.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Built-in Elicitation Flows
+ * Provides pre-configured flows for common spec creation scenarios
+ */
+import type { ElicitationFlow } from './types.js';
+/**
+ * Quick flow: 5 essential questions for rapid spec creation
+ */
+export declare const quickFlow: ElicitationFlow;
+/**
+ * Full flow: Comprehensive spec elicitation (15+ steps)
+ */
+export declare const fullFlow: ElicitationFlow;
+/**
+ * EARS flow: EARS-focused requirement elicitation
+ */
+export declare const earsFlow: ElicitationFlow;
+//# sourceMappingURL=flows.d.ts.map

package/dist/elicitation/flows.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"flows.d.ts","sourceRoot":"","sources":["../../src/elicitation/flows.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAElD;;GAEG;AACH,eAAO,MAAM,SAAS,EAAE,eA6DvB,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,QAAQ,EAAE,eA6HtB,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,QAAQ,EAAE,eAgItB,CAAC"}