sdd-mcp-server 1.5.1 → 1.6.1

package/README.md

@@ -6,11 +6,11 @@
 
 A Model Context Protocol (MCP) server implementing Spec-Driven Development (SDD) workflows for AI-agent CLIs and IDEs like Claude Code, Cursor, and others.
 
-> 🎯 **v1.5.0 - Interactive Requirements Clarification**: `sdd-init` now **blocks vague requirements**! The agent analyzes your project description (quality score 0-100) and interactively asks targeted clarification questions if score < 70%. Focuses on **WHY** (business justification), WHO (target users), WHAT (core features), and success criteria. Context-aware using existing steering docs. Prevents "garbage in, garbage out" with enriched 5W1H structured descriptions. **New service**: `RequirementsClarificationService` with 13 passing unit tests ✅
+> 🚀 **v1.6.0 - Architecture Refactoring**: Decomposed requirements clarification into **5 focused services** following Single Responsibility Principle! Each service now has one clear purpose: `SteeringContextLoader` (I/O), `DescriptionAnalyzer` (scored semantic detection 0-100), `QuestionGenerator` (template-based), `AnswerValidator` (validation + security), `DescriptionEnricher` (5W1H synthesis). Replaced brittle boolean regex with **scored semantic detection** for better accuracy. Externalized question templates to configuration. **62 new unit tests** (65 total passing) ✅. Services average ~100 LOC vs previous 500 LOC monolith. Better maintainability, testability, and type safety!
 
-> ✅ **v1.4.5**: Internal improvements! Reorganized test structure for better maintainability, centralized static steering document creation following DRY principle, improved code organization with better separation of concerns.
+> 🎯 **v1.5.0 - Interactive Requirements Clarification**: `sdd-init` now **blocks vague requirements**! The agent analyzes your project description (quality score 0-100) and interactively asks targeted clarification questions if score < 70%. Focuses on **WHY** (business justification), WHO (target users), WHAT (core features), and success criteria. Context-aware using existing steering docs. Prevents "garbage in, garbage out" with enriched 5W1H structured descriptions.
 
-> ✅ **v1.4.4**: Comprehensive codebase analysis + TDD workflow! Documents are generated with real multi-language detection (TypeScript, Java, Python, Go, Ruby, PHP, Rust, C#, Scala), framework detection (Spring Boot, Django, FastAPI, Rails, Laravel, Express, React, etc.), and architecture pattern recognition. New `principles.md` steering document enforces SOLID, DRY, KISS, YAGNI, Separation of Concerns, and Modularity. Task generation now follows Test-Driven Development (RED-GREEN-REFACTOR) workflow.
+> ✅ **v1.4.5**: Internal improvements! Reorganized test structure for better maintainability, centralized static steering document creation following DRY principle, improved code organization with better separation of concerns.
 
 ## 🚀 Quick Start
 
@@ -20,7 +20,7 @@ A Model Context Protocol (MCP) server implementing Spec-Driven Development (SDD)
 npx -y sdd-mcp-server@latest
 
 # Pin exact version (optional)
-npx -y sdd-mcp-server@1.4.5
+npx -y sdd-mcp-server@1.6.0
 
 # For Claude Code MCP integration, add to your configuration:
 # "sdd-mcp-server": {
@@ -35,7 +35,7 @@ npx -y sdd-mcp-server@1.4.5
 npm install -g sdd-mcp-server@latest
 
 # Pin exact version (optional)
-npm install -g sdd-mcp-server@1.4.5
+npm install -g sdd-mcp-server@1.6.0
 
 # Start the server
 sdd-mcp-server

package/dist/application/services/AnswerValidator.d.ts

@@ -0,0 +1,7 @@
+import { ClarificationQuestion, ClarificationAnswers, AnswerValidationResult } from "../../domain/types.js";
+export declare class AnswerValidator {
+    /**
+     * Validate user-provided clarification answers
+     */
+    validate(questions: ClarificationQuestion[], answers: ClarificationAnswers): AnswerValidationResult;
+}

package/dist/application/services/AnswerValidator.js

@@ -0,0 +1,52 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+import { injectable } from "inversify";
+import { ANSWER_VALIDATION } from "./clarification-constants.js";
+let AnswerValidator = class AnswerValidator {
+    /**
+     * Validate user-provided clarification answers
+     */
+    validate(questions, answers) {
+        const missingRequired = [];
+        const tooShort = [];
+        const containsInvalidContent = [];
+        for (const question of questions) {
+            const answer = answers[question.id]?.trim() || "";
+            // Check for missing required answers
+            if (question.required && !answer) {
+                missingRequired.push(question.question);
+                continue;
+            }
+            // Check for too-short answers
+            if (answer && answer.length < ANSWER_VALIDATION.MIN_ANSWER_LENGTH) {
+                tooShort.push({
+                    question: question.question,
+                    minLength: ANSWER_VALIDATION.MIN_ANSWER_LENGTH,
+                    currentLength: answer.length,
+                });
+            }
+            // Check for potentially malicious content
+            if (answer && ANSWER_VALIDATION.INVALID_CONTENT_PATTERN.test(answer)) {
+                containsInvalidContent.push(question.question);
+            }
+        }
+        const valid = missingRequired.length === 0 &&
+            tooShort.length === 0 &&
+            containsInvalidContent.length === 0;
+        return {
+            valid,
+            missingRequired,
+            tooShort,
+            containsInvalidContent,
+        };
+    }
+};
+AnswerValidator = __decorate([
+    injectable()
+], AnswerValidator);
+export { AnswerValidator };
+//# sourceMappingURL=AnswerValidator.js.map

package/dist/application/services/AnswerValidator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"AnswerValidator.js","sourceRoot":"","sources":["../../../src/application/services/AnswerValidator.ts"],"names":[],"mappings":";;;;;;AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AAMvC,OAAO,EAAE,iBAAiB,EAAE,MAAM,8BAA8B,CAAC;AAG1D,IAAM,eAAe,GAArB,MAAM,eAAe;IAC1B;;OAEG;IACH,QAAQ,CACN,SAAkC,EAClC,OAA6B;QAE7B,MAAM,eAAe,GAAa,EAAE,CAAC;QACrC,MAAM,QAAQ,GAIT,EAAE,CAAC;QACR,MAAM,sBAAsB,GAAa,EAAE,CAAC;QAE5C,KAAK,MAAM,QAAQ,IAAI,SAAS,EAAE,CAAC;YACjC,MAAM,MAAM,GAAG,OAAO,CAAC,QAAQ,CAAC,EAAE,CAAC,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC;YAElD,qCAAqC;YACrC,IAAI,QAAQ,CAAC,QAAQ,IAAI,CAAC,MAAM,EAAE,CAAC;gBACjC,eAAe,CAAC,IAAI,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC;gBACxC,SAAS;YACX,CAAC;YAED,8BAA8B;YAC9B,IAAI,MAAM,IAAI,MAAM,CAAC,MAAM,GAAG,iBAAiB,CAAC,iBAAiB,EAAE,CAAC;gBAClE,QAAQ,CAAC,IAAI,CAAC;oBACZ,QAAQ,EAAE,QAAQ,CAAC,QAAQ;oBAC3B,SAAS,EAAE,iBAAiB,CAAC,iBAAiB;oBAC9C,aAAa,EAAE,MAAM,CAAC,MAAM;iBAC7B,CAAC,CAAC;YACL,CAAC;YAED,0CAA0C;YAC1C,IAAI,MAAM,IAAI,iBAAiB,CAAC,uBAAuB,CAAC,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC;gBACrE,sBAAsB,CAAC,IAAI,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC;YACjD,CAAC;QACH,CAAC;QAED,MAAM,KAAK,GACT,eAAe,CAAC,MAAM,KAAK,CAAC;YAC5B,QAAQ,CAAC,MAAM,KAAK,CAAC;YACrB,sBAAsB,CAAC,MAAM,KAAK,CAAC,CAAC;QAEtC,OAAO;YACL,KAAK;YACL,eAAe;YACf,QAAQ;YACR,sBAAsB;SACvB,CAAC;IACJ,CAAC;CACF,CAAA;AApDY,eAAe;IAD3B,UAAU,EAAE;GACA,eAAe,CAoD3B"}

package/dist/application/services/DescriptionAnalyzer.d.ts

@@ -0,0 +1,28 @@
+import { ClarificationAnalysis, SteeringContext } from "../../domain/types.js";
+export declare class DescriptionAnalyzer {
+    /**
+     * Analyzes a project description for completeness using scored semantic detection
+     */
+    analyze(description: string, context: SteeringContext): ClarificationAnalysis;
+    /**
+     * Score semantic presence using keyword density approach
+     * Returns 0-100 based on presence and density of matching patterns
+     */
+    private scoreSemanticPresence;
+    /**
+     * Detect ambiguous terms in the description
+     */
+    private detectAmbiguousTerms;
+    /**
+     * Calculate overall quality score based on presence of elements
+     */
+    private calculateQualityScore;
+    /**
+     * Identify which elements are missing considering steering context
+     */
+    private identifyMissingElements;
+    /**
+     * Extract context around a matched term for better clarity
+     */
+    private extractContext;
+}

package/dist/application/services/DescriptionAnalyzer.js

@@ -0,0 +1,184 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+import { injectable } from "inversify";
+import { QUALITY_SCORE_WEIGHTS, PATTERN_DETECTION, AMBIGUOUS_TERMS, } from "./clarification-constants.js";
+let DescriptionAnalyzer = class DescriptionAnalyzer {
+    /**
+     * Analyzes a project description for completeness using scored semantic detection
+     */
+    analyze(description, context) {
+        // Handle empty descriptions
+        if (!description || description.trim().length === 0) {
+            return {
+                qualityScore: 0,
+                whyScore: 0,
+                whoScore: 0,
+                whatScore: 0,
+                successScore: 0,
+                hasWhy: false,
+                hasWho: false,
+                hasWhat: false,
+                hasSuccessCriteria: false,
+                missingElements: ["WHY", "WHO", "WHAT", "Success Criteria"],
+                ambiguousTerms: [],
+                needsClarification: true,
+            };
+        }
+        // Calculate semantic scores (0-100 each)
+        const whyScore = this.scoreSemanticPresence(description, PATTERN_DETECTION.WHY_PATTERNS);
+        const whoScore = this.scoreSemanticPresence(description, PATTERN_DETECTION.WHO_PATTERNS);
+        const whatScore = this.scoreSemanticPresence(description, PATTERN_DETECTION.WHAT_PATTERNS);
+        const successScore = this.scoreSemanticPresence(description, PATTERN_DETECTION.SUCCESS_PATTERNS);
+        // Derive boolean presence (threshold: 30%)
+        const hasWhy = whyScore > 30;
+        const hasWho = whoScore > 30;
+        const hasWhat = whatScore > 30;
+        const hasSuccessCriteria = successScore > 30;
+        // Detect ambiguous terms
+        const ambiguousTerms = this.detectAmbiguousTerms(description);
+        // Calculate overall quality score
+        const qualityScore = this.calculateQualityScore({
+            hasWhy,
+            hasWho,
+            hasWhat,
+            hasSuccessCriteria,
+            ambiguousTermCount: ambiguousTerms.length,
+            descriptionLength: description.length,
+        });
+        // Determine missing elements considering steering context
+        const missingElements = this.identifyMissingElements({ hasWhy, hasWho, hasWhat, hasSuccessCriteria }, context);
+        // Need clarification if score below threshold or missing critical elements
+        const needsClarification = qualityScore < QUALITY_SCORE_WEIGHTS.MIN_ACCEPTABLE_SCORE ||
+            missingElements.length > 0;
+        return {
+            qualityScore,
+            whyScore,
+            whoScore,
+            whatScore,
+            successScore,
+            hasWhy,
+            hasWho,
+            hasWhat,
+            hasSuccessCriteria,
+            missingElements,
+            ambiguousTerms,
+            needsClarification,
+        };
+    }
+    /**
+     * Score semantic presence using keyword density approach
+     * Returns 0-100 based on presence and density of matching patterns
+     */
+    scoreSemanticPresence(description, patterns) {
+        const words = description
+            .toLowerCase()
+            .split(/\s+/)
+            .filter((w) => w.length > 0);
+        if (words.length === 0)
+            return 0;
+        const matchedWords = words.filter((word) => patterns.some((pattern) => pattern.test(word)));
+        if (matchedWords.length === 0)
+            return 0;
+        // Base score for any presence
+        const coverage = 50;
+        // Density score based on percentage of matched words
+        const density = (matchedWords.length / words.length) * 100;
+        // Total score capped at 100
+        return Math.min(100, coverage + density);
+    }
+    /**
+     * Detect ambiguous terms in the description
+     */
+    detectAmbiguousTerms(description) {
+        const ambiguousTerms = [];
+        for (const { pattern, suggestion } of AMBIGUOUS_TERMS) {
+            const matches = description.match(pattern);
+            if (matches) {
+                for (const match of matches) {
+                    const context = this.extractContext(description, match);
+                    ambiguousTerms.push({
+                        term: match,
+                        context,
+                        suggestion,
+                    });
+                }
+            }
+        }
+        return ambiguousTerms;
+    }
+    /**
+     * Calculate overall quality score based on presence of elements
+     */
+    calculateQualityScore(metrics) {
+        let score = 0;
+        // WHY is most important
+        if (metrics.hasWhy)
+            score += QUALITY_SCORE_WEIGHTS.HAS_WHY;
+        // WHO is critical
+        if (metrics.hasWho)
+            score += QUALITY_SCORE_WEIGHTS.HAS_WHO;
+        // WHAT is essential
+        if (metrics.hasWhat)
+            score += QUALITY_SCORE_WEIGHTS.HAS_WHAT;
+        // Success criteria
+        if (metrics.hasSuccessCriteria)
+            score += QUALITY_SCORE_WEIGHTS.HAS_SUCCESS;
+        // Penalize ambiguous terms
+        const ambiguityPenalty = Math.min(QUALITY_SCORE_WEIGHTS.MAX_AMBIGUITY_PENALTY, metrics.ambiguousTermCount * QUALITY_SCORE_WEIGHTS.AMBIGUITY_PENALTY);
+        score -= ambiguityPenalty;
+        // Length bonus - adequate detail
+        if (metrics.descriptionLength > QUALITY_SCORE_WEIGHTS.LENGTH_BONUS_THRESHOLD_1)
+            score += QUALITY_SCORE_WEIGHTS.LENGTH_BONUS_POINTS;
+        if (metrics.descriptionLength > QUALITY_SCORE_WEIGHTS.LENGTH_BONUS_THRESHOLD_2)
+            score += QUALITY_SCORE_WEIGHTS.LENGTH_BONUS_POINTS;
+        if (metrics.descriptionLength > QUALITY_SCORE_WEIGHTS.LENGTH_BONUS_THRESHOLD_3)
+            score += QUALITY_SCORE_WEIGHTS.LENGTH_BONUS_POINTS;
+        return Math.max(0, Math.min(100, score));
+    }
+    /**
+     * Identify which elements are missing considering steering context
+     */
+    identifyMissingElements(presence, context) {
+        const missing = [];
+        // WHY is required unless product context exists
+        if (!presence.hasWhy && !context.hasProductContext) {
+            missing.push("Business justification (WHY)");
+        }
+        // WHO is required unless target users documented
+        if (!presence.hasWho && !context.hasTargetUsers) {
+            missing.push("Target users (WHO)");
+        }
+        // WHAT is always required
+        if (!presence.hasWhat) {
+            missing.push("Core features (WHAT)");
+        }
+        // Success criteria always required
+        if (!presence.hasSuccessCriteria) {
+            missing.push("Success criteria");
+        }
+        return missing;
+    }
+    /**
+     * Extract context around a matched term for better clarity
+     */
+    extractContext(description, term) {
+        const index = description.toLowerCase().indexOf(term.toLowerCase());
+        if (index === -1)
+            return "";
+        const start = Math.max(0, index - 30);
+        const end = Math.min(description.length, index + term.length + 30);
+        const context = description.substring(start, end);
+        return ((start > 0 ? "..." : "") +
+            context +
+            (end < description.length ? "..." : ""));
+    }
+};
+DescriptionAnalyzer = __decorate([
+    injectable()
+], DescriptionAnalyzer);
+export { DescriptionAnalyzer };
+//# sourceMappingURL=DescriptionAnalyzer.js.map

package/dist/application/services/DescriptionAnalyzer.js.map

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

package/dist/application/services/DescriptionEnricher.d.ts

@@ -0,0 +1,15 @@
+import { ClarificationQuestion, ClarificationAnswers, EnrichedProjectDescription } from "../../domain/types.js";
+export declare class DescriptionEnricher {
+    /**
+     * Synthesize enriched project description from original + clarification answers
+     */
+    synthesize(originalDescription: string, questions: ClarificationQuestion[], answers: ClarificationAnswers): EnrichedProjectDescription;
+    /**
+     * Extract all answers for a specific question category
+     */
+    private extractAnswersByCategory;
+    /**
+     * Build enriched description with 5W1H structure
+     */
+    private buildEnrichedDescription;
+}

package/dist/application/services/DescriptionEnricher.js

@@ -0,0 +1,77 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+import { injectable } from "inversify";
+import { QuestionCategory, } from "../../domain/types.js";
+let DescriptionEnricher = class DescriptionEnricher {
+    /**
+     * Synthesize enriched project description from original + clarification answers
+     */
+    synthesize(originalDescription, questions, answers) {
+        const why = this.extractAnswersByCategory(questions, answers, QuestionCategory.WHY);
+        const who = this.extractAnswersByCategory(questions, answers, QuestionCategory.WHO);
+        const what = this.extractAnswersByCategory(questions, answers, QuestionCategory.WHAT);
+        const how = this.extractAnswersByCategory(questions, answers, QuestionCategory.HOW);
+        const successCriteria = this.extractAnswersByCategory(questions, answers, QuestionCategory.SUCCESS);
+        const enriched = this.buildEnrichedDescription({
+            original: originalDescription,
+            why,
+            who,
+            what,
+            how,
+            successCriteria,
+        });
+        return {
+            original: originalDescription,
+            why,
+            who,
+            what,
+            how,
+            successCriteria,
+            enriched,
+        };
+    }
+    /**
+     * Extract all answers for a specific question category
+     */
+    extractAnswersByCategory(questions, answers, category) {
+        const categoryQuestions = questions.filter((q) => q.category === category);
+        const categoryAnswers = categoryQuestions
+            .map((q) => answers[q.id])
+            .filter((a) => a && a.trim().length > 0);
+        return categoryAnswers.join(" ");
+    }
+    /**
+     * Build enriched description with 5W1H structure
+     */
+    buildEnrichedDescription(components) {
+        const parts = [];
+        if (components.original) {
+            parts.push(`## Original Description\n${components.original}`);
+        }
+        if (components.why) {
+            parts.push(`## Business Justification (Why)\n${components.why}`);
+        }
+        if (components.who) {
+            parts.push(`## Target Users (Who)\n${components.who}`);
+        }
+        if (components.what) {
+            parts.push(`## Core Features (What)\n${components.what}`);
+        }
+        if (components.how) {
+            parts.push(`## Technical Approach (How)\n${components.how}`);
+        }
+        if (components.successCriteria) {
+            parts.push(`## Success Criteria\n${components.successCriteria}`);
+        }
+        return parts.join("\n\n");
+    }
+};
+DescriptionEnricher = __decorate([
+    injectable()
+], DescriptionEnricher);
+export { DescriptionEnricher };
+//# sourceMappingURL=DescriptionEnricher.js.map

package/dist/application/services/DescriptionEnricher.js.map

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

package/dist/application/services/QuestionGenerator.d.ts

@@ -0,0 +1,7 @@
+import { ClarificationQuestion, ClarificationAnalysis, SteeringContext } from "../../domain/types.js";
+export declare class QuestionGenerator {
+    /**
+     * Generate clarification questions based on analysis and steering context
+     */
+    generateQuestions(analysis: ClarificationAnalysis, context: SteeringContext): ClarificationQuestion[];
+}

package/dist/application/services/QuestionGenerator.js

@@ -0,0 +1,30 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+import { injectable } from "inversify";
+import { CLARIFICATION_QUESTIONS } from "./clarification-questions.js";
+let QuestionGenerator = class QuestionGenerator {
+    /**
+     * Generate clarification questions based on analysis and steering context
+     */
+    generateQuestions(analysis, context) {
+        return Object.values(CLARIFICATION_QUESTIONS)
+            .filter((template) => template.condition(analysis, context))
+            .map((template) => ({
+            id: template.id,
+            category: template.category,
+            question: template.question,
+            why: template.rationale,
+            examples: template.examples,
+            required: template.required,
+        }));
+    }
+};
+QuestionGenerator = __decorate([
+    injectable()
+], QuestionGenerator);
+export { QuestionGenerator };
+//# sourceMappingURL=QuestionGenerator.js.map

package/dist/application/services/QuestionGenerator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"QuestionGenerator.js","sourceRoot":"","sources":["../../../src/application/services/QuestionGenerator.ts"],"names":[],"mappings":";;;;;;AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AAMvC,OAAO,EAAE,uBAAuB,EAAE,MAAM,8BAA8B,CAAC;AAGhE,IAAM,iBAAiB,GAAvB,MAAM,iBAAiB;IAC5B;;OAEG;IACH,iBAAiB,CACf,QAA+B,EAC/B,OAAwB;QAExB,OAAO,MAAM,CAAC,MAAM,CAAC,uBAAuB,CAAC;aAC1C,MAAM,CAAC,CAAC,QAAQ,EAAE,EAAE,CAAC,QAAQ,CAAC,SAAS,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC;aAC3D,GAAG,CAAC,CAAC,QAAQ,EAAE,EAAE,CAAC,CAAC;YAClB,EAAE,EAAE,QAAQ,CAAC,EAAE;YACf,QAAQ,EAAE,QAAQ,CAAC,QAAQ;YAC3B,QAAQ,EAAE,QAAQ,CAAC,QAAQ;YAC3B,GAAG,EAAE,QAAQ,CAAC,SAAS;YACvB,QAAQ,EAAE,QAAQ,CAAC,QAAQ;YAC3B,QAAQ,EAAE,QAAQ,CAAC,QAAQ;SAC5B,CAAC,CAAC,CAAC;IACR,CAAC;CACF,CAAA;AAnBY,iBAAiB;IAD7B,UAAU,EAAE;GACA,iBAAiB,CAmB7B"}

package/dist/application/services/RequirementsClarificationService.d.ts

@@ -1,9 +1,28 @@
-import { FileSystemPort, LoggerPort } from "../../domain/ports.js";
+import { LoggerPort } from "../../domain/ports.js";
 import { ClarificationQuestion, EnrichedProjectDescription, ClarificationResult, ClarificationAnswers, AnswerValidationResult } from "../../domain/types.js";
+import { SteeringContextLoader } from "./SteeringContextLoader.js";
+import { DescriptionAnalyzer } from "./DescriptionAnalyzer.js";
+import { QuestionGenerator } from "./QuestionGenerator.js";
+import { AnswerValidator } from "./AnswerValidator.js";
+import { DescriptionEnricher } from "./DescriptionEnricher.js";
+/**
+ * Orchestrator service for requirements clarification workflow
+ *
+ * Delegates to specialized services:
+ * - SteeringContextLoader: Loads steering documents
+ * - DescriptionAnalyzer: Analyzes description quality
+ * - QuestionGenerator: Generates clarification questions
+ * - AnswerValidator: Validates user answers
+ * - DescriptionEnricher: Synthesizes enriched descriptions
+ */
 export declare class RequirementsClarificationService {
-    private readonly fileSystem;
     private readonly logger;
-    constructor(fileSystem: FileSystemPort, logger: LoggerPort);
+    private readonly steeringLoader;
+    private readonly analyzer;
+    private readonly questionGenerator;
+    private readonly answerValidator;
+    private readonly enricher;
+    constructor(logger: LoggerPort, steeringLoader: SteeringContextLoader, analyzer: DescriptionAnalyzer, questionGenerator: QuestionGenerator, answerValidator: AnswerValidator, enricher: DescriptionEnricher);
     /**
      * Analyzes a project description to determine if clarification is needed
      */
@@ -16,52 +35,4 @@ export declare class RequirementsClarificationService {
      * Synthesizes an enriched project description from original + answers
      */
     synthesizeDescription(originalDescription: string, questions: ClarificationQuestion[], answers: ClarificationAnswers): EnrichedProjectDescription;
-    /**
-     * Performs the core analysis of the description
-     */
-    private performAnalysis;
-    /**
-     * Generates targeted clarification questions based on analysis
-     */
-    private generateQuestions;
-    /**
-     * Load steering documents for context
-     */
-    private loadSteeringContext;
-    /**
-     * Detects if description contains WHY (business justification)
-     */
-    private detectWhy;
-    /**
-     * Detects if description contains WHO (target users)
-     */
-    private detectWho;
-    /**
-     * Detects if description contains WHAT (features, scope)
-     */
-    private detectWhat;
-    /**
-     * Detects if description contains success criteria
-     */
-    private detectSuccessCriteria;
-    /**
-     * Detects ambiguous terms that need clarification
-     */
-    private detectAmbiguousTerms;
-    /**
-     * Extracts surrounding context for an ambiguous term
-     */
-    private extractContext;
-    /**
-     * Calculates quality score based on completeness and clarity
-     */
-    private calculateQualityScore;
-    /**
-     * Extracts answers for a specific category
-     */
-    private extractAnswersByCategory;
-    /**
-     * Builds the enriched description from all components
-     */
-    private buildEnrichedDescription;
 }