/**
 * Spec-Kit Types
 *
 * Unified TypeScript interfaces for Spec-Kit artifacts and the
 * CONSTITUTION.md parser. This file merges definitions added in both
 * branches so the codebase retains both sets of improvements.
 *
 * @module strategies/speckit/types
 * @see {@link https://github.com/Anselmoo/mcp-ai-agent-guidelines/blob/development/plan-v0.13.x/specs/SPEC-005-speckit-integration.md SPEC-005}
 */
/**
 * Metadata about the constitution document
 */
export interface ConstitutionMetadata {
    /** Document title */
    title?: string;
    /** Semantic version of the constitution */
    version?: string;
    /** Date the constitution was adopted */
    adopted?: string;
    /** ISO-8601 timestamp of last update */
    lastUpdated?: string;
    /** Version or scope this applies to */
    appliesTo?: string;
    /** File path where this was parsed from */
    sourcePath?: string;
}
/**
 * A fundamental principle guiding project decisions.
 *
 * Principles are high-level tenets that inform decision-making.
 */
export interface Principle {
    /** Unique identifier for the principle (e.g. PRIN-001 or numeric index) */
    id: string;
    /** Short, descriptive title */
    title: string;
    /** Detailed explanation of the principle */
    description: string;
    /** Type discriminator */
    type: "principle";
}
/**
 * A constraint limiting implementation choices.
 *
 * Constraints are enforceable rules with RFC2119 severity when applicable.
 */
export interface Constraint {
    /** Unique identifier for the constraint (e.g. CONS-001) */
    id: string;
    /** Short, descriptive title */
    title: string;
    /** Detailed explanation of the constraint */
    description: string;
    /**
     * RFC 2119 severity level where applicable
     * - must: Absolute requirement
     * - should: Strong recommendation
     * - may: Optional suggestion
     */
    severity?: "must" | "should" | "may";
    /** Type discriminator */
    type: "constraint";
}
/**
 * An architecture-level rule or pattern.
 */
export interface ArchitectureRule {
    /** Unique identifier for the rule (e.g. AR1) */
    id: string;
    /** Short, descriptive title */
    title: string;
    /** Detailed explanation of the rule */
    description: string;
    /** Type discriminator */
    type: "architecture-rule";
}
/**
 * A design-level principle or guideline.
 */
export interface DesignPrinciple {
    /** Unique identifier for the principle */
    id: string;
    /** Short, descriptive title */
    title: string;
    /** Detailed explanation of the principle */
    description: string;
    /** Type discriminator */
    type: "design-principle";
}
/**
 * Complete parsed CONSTITUTION.md document
 */
export interface Constitution {
    /** Core principles guiding the project */
    principles: Principle[];
    /** Hard and soft constraints on implementation */
    constraints: Constraint[];
    /** Architecture-level rules and patterns */
    architectureRules: ArchitectureRule[];
    /** Design-level principles and guidelines */
    designPrinciples: DesignPrinciple[];
    /** Optional metadata about the constitution */
    metadata?: ConstitutionMetadata;
}
/**
 * Parsed specification document.
 */
export interface ParsedSpec {
    /** Specification title */
    title: string;
    /** High-level overview of the project */
    overview: string;
    /** Strategic objectives */
    objectives: Objective[];
    /** Functional requirements */
    functionalRequirements: Requirement[];
    /** Non-functional requirements (performance, security, etc.) */
    nonFunctionalRequirements: Requirement[];
    /** References to constitution constraints */
    constraints: ConstraintReference[];
    /** Acceptance criteria for completion */
    acceptanceCriteria: AcceptanceCriterion[];
    /** Explicitly out-of-scope items */
    outOfScope: string[];
}
export interface Objective {
    id: string;
    description: string;
    priority: "high" | "medium" | "low";
}
export interface Requirement {
    id: string;
    description: string;
    priority: "high" | "medium" | "low";
    derivedTasks?: DerivedTask[];
}
export interface ConstraintReference {
    constitutionId: string;
    type: "principle" | "constraint" | "architecture-rule" | "design-principle";
    notes?: string;
}
/**
 * Acceptance criterion for requirement verification.
 *
 * Defines how to verify that a requirement has been properly implemented.
 *
 * @interface AcceptanceCriterion
 * @example
 * ```typescript
 * {
 *   id: "AC-001",
 *   description: "User can authenticate with Google OAuth",
 *   verificationMethod: "automated"
 * }
 * ```
 */
export interface AcceptanceCriterion {
    /** Unique identifier for the criterion */
    id: string;
    /** Description of what must be verified */
    description: string;
    /** Method for verifying this criterion */
    verificationMethod: "automated" | "manual" | "review";
}
/**
 * Implementation plan.
 *
 * Describes the overall approach, phases, dependencies, risks,
 * and timeline for executing the project.
 *
 * @interface Plan
 */
export interface Plan {
    /** High-level approach description */
    approach: string;
    /** Implementation phases */
    phases: Phase[];
    /** External and internal dependencies */
    dependencies: Dependency[];
    /** Identified risks and mitigation strategies */
    risks: Risk[];
    /** Timeline with phase scheduling */
    timeline: TimelineEntry[];
}
/**
 * A project phase.
 *
 * Phases group related work with clear deliverables and durations.
 *
 * @interface Phase
 * @example
 * ```typescript
 * {
 *   id: "PHASE-001",
 *   name: "Foundation",
 *   description: "Establish core architecture",
 *   deliverables: ["Architecture diagram", "Core interfaces"],
 *   duration: "2 weeks"
 * }
 * ```
 */
export interface Phase {
    /** Unique identifier for the phase */
    id: string;
    /** Phase name */
    name: string;
    /** Description of phase objectives */
    description: string;
    /** Expected deliverables */
    deliverables: string[];
    /** Estimated duration */
    duration: string;
}
/**
 * A project dependency.
 *
 * Dependencies are prerequisites or blockers that must be addressed.
 *
 * @interface Dependency
 * @example
 * ```typescript
 * {
 *   id: "DEP-001",
 *   description: "OAuth provider API access",
 *   owner: "security-team"
 * }
 * ```
 */
export interface Dependency {
    /** Unique identifier for the dependency */
    id: string;
    /** Description of the dependency */
    description: string;
    /** Optional owner responsible for resolving */
    owner?: string;
}
/**
 * A project risk.
 *
 * Risks are potential issues with mitigation strategies.
 *
 * @interface Risk
 * @example
 * ```typescript
 * {
 *   id: "RISK-001",
 *   description: "Third-party API rate limits",
 *   severity: "medium",
 *   mitigation: "Implement request caching and retry logic"
 * }
 * ```
 */
export interface Risk {
    /** Unique identifier for the risk */
    id: string;
    /** Description of the risk */
    description: string;
    /** Risk severity level */
    severity: "high" | "medium" | "low";
    /** Mitigation strategy */
    mitigation: string;
}
/**
 * Timeline entry mapping phases to schedule.
 *
 * @interface TimelineEntry
 * @example
 * ```typescript
 * {
 *   phase: "PHASE-001",
 *   startWeek: 1,
 *   endWeek: 2
 * }
 * ```
 */
export interface TimelineEntry {
    /** Phase identifier */
    phase: string;
    /** Starting week number */
    startWeek: number;
    /** Ending week number */
    endWeek: number;
}
/**
 * A derived implementation task.
 *
 * Tasks are concrete work items derived from requirements.
 * They represent actionable units of work.
 *
 * @interface DerivedTask
 * @example
 * ```typescript
 * {
 *   id: "TASK-001",
 *   title: "Implement OAuth login flow",
 *   description: "Create OAuth 2.0 authentication with Google provider",
 *   priority: "high",
 *   estimate: "3 days",
 *   phase: "PHASE-001",
 *   acceptanceCriteria: ["User can log in", "Token is securely stored"],
 *   dependencies: ["TASK-002"]
 * }
 * ```
 */
export interface DerivedTask {
    /** Unique identifier for the task */
    id: string;
    /** Task title */
    title: string;
    /** Detailed task description */
    description: string;
    /** Priority level */
    priority: "high" | "medium" | "low";
    /** Time estimate */
    estimate: string;
    /** Optional phase assignment */
    phase?: string;
    /** Task acceptance criteria */
    acceptanceCriteria: string[];
    /** Optional task dependencies */
    dependencies?: string[];
}
/**
 * Collection of tasks with metadata.
 *
 * Represents all tasks for a project or specification.
 *
 * @interface Tasks
 * @example
 * ```typescript
 * {
 *   items: [
 *     { id: "TASK-001", title: "Setup database", ... },
 *     { id: "TASK-002", title: "Create API", ... }
 *   ],
 *   metadata: {
 *     version: "1.0.0",
 *     createdAt: "2026-01-13T00:00:00Z"
 *   }
 * }
 * ```
 */
export interface Tasks {
    /** Array of tasks */
    items: DerivedTask[];
    /** Optional metadata about the task collection */
    metadata?: {
        /** Version of the task list */
        version?: string;
        /** Creation timestamp */
        createdAt?: string;
        /** Last updated timestamp */
        lastUpdated?: string;
    };
}
/**
 * Progress metrics for task completion.
 *
 * Provides statistical summary of task progress.
 *
 * @interface ProgressMetrics
 * @example
 * ```typescript
 * {
 *   total: 10,
 *   completed: 7,
 *   remaining: 3,
 *   percentComplete: 70
 * }
 * ```
 */
export interface ProgressMetrics {
    /** Total number of tasks */
    total: number;
    /** Number of completed tasks */
    completed: number;
    /** Number of remaining tasks */
    remaining: number;
    /** Percentage complete (0-100) */
    percentComplete: number;
}
/**
 * Project progress tracking.
 *
 * Tracks completion status, recent updates, blockers, and next steps.
 *
 * @interface Progress
 */
export interface Progress {
    /** Overall status */
    status: "on-track" | "at-risk" | "blocked" | "completed";
    /** Percentage complete (0-100) */
    completionPercentage: number;
    /** Number of completed tasks */
    tasksCompleted: number;
    /** Total number of tasks */
    totalTasks: number;
    /** Recent progress updates */
    recentUpdates: ProgressUpdate[];
    /** Active blockers */
    blockers: Blocker[];
    /** Planned next steps */
    nextSteps: string[];
    /** Last update timestamp */
    lastUpdated: Date;
}
/**
 * A progress update entry.
 *
 * Records a specific progress event with completed tasks.
 *
 * @interface ProgressUpdate
 * @example
 * ```typescript
 * {
 *   date: new Date("2024-01-15"),
 *   description: "Completed OAuth integration",
 *   tasksCompleted: ["TASK-001", "TASK-002"]
 * }
 * ```
 */
export interface ProgressUpdate {
    /** Update date */
    date: Date;
    /** Update description */
    description: string;
    /** Task IDs completed in this update */
    tasksCompleted: string[];
}
/**
 * A project blocker.
 *
 * Blockers are issues preventing progress that need resolution.
 *
 * @interface Blocker
 * @example
 * ```typescript
 * {
 *   id: "BLOCK-001",
 *   description: "API credentials pending approval",
 *   severity: "critical",
 *   owner: "platform-team"
 * }
 * ```
 */
export interface Blocker {
    /** Unique identifier for the blocker */
    id: string;
    /** Description of the blocker */
    description: string;
    /** Blocker severity */
    severity: "critical" | "major" | "minor";
    /** Optional owner responsible for resolution */
    owner?: string;
}
/**
 * Complete Spec-Kit artifacts collection.
 *
 * Aggregates all Spec-Kit documents into a single type-safe structure.
 * Used for generating the complete .specify/ directory.
 *
 * @interface SpecKitArtifacts
 * @example
 * ```typescript
 * const artifacts: SpecKitArtifacts = {
 *   spec: { title: "...", ... },
 *   plan: { approach: "...", ... },
 *   tasks: [...],
 *   progress: { status: "on-track", ... },
 *   constitution: { principles: [...], ... }
 * };
 * ```
 */
export interface SpecKitArtifacts {
    /** Parsed specification */
    spec: ParsedSpec;
    /** Implementation plan */
    plan: Plan;
    /** Derived tasks */
    tasks: DerivedTask[];
    /** Progress tracking */
    progress: Progress;
    /** Optional project constitution */
    constitution?: Constitution;
}
/**
 * Severity level for validation issues
 */
export type ValidationSeverity = "error" | "warning" | "info";
/**
 * A validation issue found during spec validation
 */
export interface ValidationIssue {
    /** Severity level of the issue */
    severity: ValidationSeverity;
    /** Unique code identifying the issue type */
    code: string;
    /** Human-readable message describing the issue */
    message: string;
    /** Optional reference to the violated constraint */
    constraint?: {
        id: string;
        type: "principle" | "constraint" | "architecture-rule" | "design-principle";
        description?: string;
    };
    /** Optional location information */
    location?: {
        section?: string;
        field?: string;
        line?: number;
        column?: number;
    };
    /** Optional suggestion for resolving the issue */
    suggestion?: string;
    /** Whether the issue can be automatically fixed */
    fixable?: boolean;
}
/**
 * Result of spec validation
 */
export interface ValidationResult {
    /** Whether the spec is valid (no errors) */
    valid: boolean;
    /** Validation score (0-100) */
    score: number;
    /** List of validation issues found */
    issues: ValidationIssue[];
    /** Number of constraints checked */
    checkedConstraints: number;
    /** Number of constraints passed */
    passedConstraints: number;
}
/**
 * Comprehensive validation report with metrics and categorization
 */
export interface ValidationReport {
    /** Whether the spec is valid (no errors) */
    valid: boolean;
    /** Validation score (0-100) */
    score: number;
    /** ISO-8601 timestamp when the report was generated */
    timestamp: string;
    /** Summary metrics */
    metrics: {
        /** Total number of constraints checked */
        total: number;
        /** Number of constraints passed */
        passed: number;
        /** Number of errors found */
        failed: number;
        /** Number of warnings found */
        warnings: number;
        /** Number of info items found */
        info: number;
    };
    /** Breakdown of results by constraint type */
    byType: {
        /** Principles validation results */
        principles: {
            checked: number;
            passed: number;
        };
        /** Constraints validation results */
        constraints: {
            checked: number;
            passed: number;
        };
        /** Architecture rules validation results */
        architectureRules: {
            checked: number;
            passed: number;
        };
        /** Design principles validation results */
        designPrinciples: {
            checked: number;
            passed: number;
        };
    };
    /** List of validation issues found */
    issues: ValidationIssue[];
    /** Optional recommendations for improvement */
    recommendations?: string[];
}
/**
 * Specification content to be validated
 */
export interface SpecContent {
    /** Specification title */
    title?: string;
    /** Overview/description of the specification */
    overview?: string;
    /** List of objectives */
    objectives?: {
        description: string;
        priority?: string;
    }[];
    /** List of requirements */
    requirements?: {
        description: string;
        type?: string;
    }[];
    /** Acceptance criteria */
    acceptanceCriteria?: string[];
    /** Raw markdown content */
    rawMarkdown?: string;
}
//# sourceMappingURL=types.d.ts.map