aidlc

type ConflictStrategy string

type DimensionScore struct {
	// ID is the dimension identifier.
	ID string `json:"id" yaml:"id"`

	// Name is the dimension display name.
	Name string `json:"name" yaml:"name"`

	// Score is the dimension score (0.0-1.0).
	Score float64 `json:"score" yaml:"score"`

	// Weight is the dimension weight in the overall score.
	Weight float64 `json:"weight" yaml:"weight"`

	// Findings are dimension-specific issues.
	Findings []Issue `json:"findings,omitempty" yaml:"findings,omitempty"`
}

type DocType string

type Document struct {
	// Type is the document type.
	Type DocType `json:"type" yaml:"type"`

	// Phase is the workflow phase this document belongs to.
	Phase Phase `json:"phase" yaml:"phase"`

	// Path is the file path relative to the project root.
	Path string `json:"path" yaml:"path"`

	// Title is the document title.
	Title string `json:"title" yaml:"title"`

	// Status is the current document status.
	Status DocumentStatus `json:"status" yaml:"status"`

	// Content is the raw markdown content.
	Content string `json:"content,omitempty" yaml:"content,omitempty"`

	// Metadata contains frontmatter and other parsed metadata.
	Metadata map[string]any `json:"metadata,omitempty" yaml:"metadata,omitempty"`

	// Score is the quality evaluation score (if evaluated).
	Score *QualityScore `json:"score,omitempty" yaml:"score,omitempty"`

	// UpdatedAt is when the document was last modified.
	UpdatedAt time.Time `json:"updated_at" yaml:"updated_at"`

	// Checksum is the content hash for change detection.
	Checksum string `json:"checksum,omitempty" yaml:"checksum,omitempty"`
}

type DocumentStatus string

type EdgeType string

type EvaluationResult struct {
	// Document is the evaluated document.
	Document *Document

	// RubricSet is the rubric used for evaluation.
	RubricSet *rubric.RubricSet

	// Report is the full evaluation report.
	Report *rubric.Rubric

	// QualityScore is the aggregated quality score in AIDLC format.
	QualityScore *QualityScore

	// Decision is the evaluation decision.
	Decision *rubric.Decision

	// Error contains any evaluation error.
	Error error
}

type Evaluator struct {
	// Judge is the LLM judge for evaluation.
	// When nil, Evaluate returns a stub result.
	Judge Judge
}

type ExecutionMetrics struct {
	// TotalSteps is the total number of steps.
	TotalSteps int `json:"total_steps" yaml:"total_steps"`

	// CompletedSteps is the number of completed steps.
	CompletedSteps int `json:"completed_steps" yaml:"completed_steps"`

	// InProgressSteps is the number of in-progress steps.
	InProgressSteps int `json:"in_progress_steps" yaml:"in_progress_steps"`

	// BlockedSteps is the number of blocked steps.
	BlockedSteps int `json:"blocked_steps" yaml:"blocked_steps"`

	// PendingSteps is the number of pending steps.
	PendingSteps int `json:"pending_steps" yaml:"pending_steps"`

	// FailedSteps is the number of failed steps.
	FailedSteps int `json:"failed_steps" yaml:"failed_steps"`

	// ProgressPercent is the completion percentage.
	ProgressPercent float64 `json:"progress_percent" yaml:"progress_percent"`

	// ElapsedTime is the total elapsed time.
	ElapsedTime time.Duration `json:"elapsed_time" yaml:"elapsed_time"`

	// EstimatedRemaining is the estimated remaining time (if available).
	EstimatedRemaining time.Duration `json:"estimated_remaining,omitempty" yaml:"estimated_remaining,omitempty"`

	// PhaseMetrics contains per-phase metrics.
	PhaseMetrics map[string]*PhaseMetrics `json:"phase_metrics,omitempty" yaml:"phase_metrics,omitempty"`
}

type Issue struct {
	// Severity is the issue severity.
	Severity IssueSeverity `json:"severity" yaml:"severity"`

	// Category is the issue category (e.g., "clarity", "completeness").
	Category string `json:"category" yaml:"category"`

	// Code is a machine-readable issue code (e.g., "MISSING_ACCEPTANCE_CRITERIA").
	Code string `json:"code,omitempty" yaml:"code,omitempty"`

	// Message is a human-readable description.
	Message string `json:"message" yaml:"message"`

	// Location references where the issue was found (e.g., section or line).
	Location string `json:"location,omitempty" yaml:"location,omitempty"`

	// Suggestion provides remediation guidance.
	Suggestion string `json:"suggestion,omitempty" yaml:"suggestion,omitempty"`
}

type IssueSeverity string

type Judge interface {
	// EvaluateCategory evaluates a document against a single category's criteria.
	// Returns the category result with score, reasoning, and any findings.
	EvaluateCategory(ctx context.Context, content string, category *rubric.Category) (*rubric.CategoryResult, error)
}

type NodeStatus string

type Phase string

type PhaseMetrics struct {
	// PhaseID is the phase identifier.
	PhaseID string `json:"phase_id" yaml:"phase_id"`

	// TotalSteps is the total steps in this phase.
	TotalSteps int `json:"total_steps" yaml:"total_steps"`

	// CompletedSteps is the completed steps in this phase.
	CompletedSteps int `json:"completed_steps" yaml:"completed_steps"`

	// ProgressPercent is the phase completion percentage.
	ProgressPercent float64 `json:"progress_percent" yaml:"progress_percent"`

	// Status is the phase status.
	Status PhaseStatus `json:"status" yaml:"status"`
}

type PhaseRequirements struct {
	// Phase is the phase being checked.
	Phase Phase `json:"phase" yaml:"phase"`

	// RequiredDocs are the required documents.
	RequiredDocs []DocType `json:"required_docs" yaml:"required_docs"`

	// CompletedDocs are the completed required documents.
	CompletedDocs []DocType `json:"completed_docs" yaml:"completed_docs"`

	// PendingDocs are the pending required documents.
	PendingDocs []DocType `json:"pending_docs" yaml:"pending_docs"`

	// ProgressPercent is the completion percentage.
	ProgressPercent float64 `json:"progress_percent" yaml:"progress_percent"`

	// CanAdvance indicates if the phase can advance.
	CanAdvance bool `json:"can_advance" yaml:"can_advance"`
}

type PhaseStatus string

type QualityRating string

type QualityScore struct {
	// Rating is the overall quality rating.
	Rating QualityRating `json:"rating" yaml:"rating"`

	// Score is a numeric score (0.0-1.0).
	Score float64 `json:"score" yaml:"score"`

	// Issues are identified problems.
	Issues []Issue `json:"issues,omitempty" yaml:"issues,omitempty"`

	// Dimensions contains per-dimension scores (if available).
	Dimensions map[string]DimensionScore `json:"dimensions,omitempty" yaml:"dimensions,omitempty"`

	// EvaluatedAt is when the evaluation was performed.
	EvaluatedAt time.Time `json:"evaluated_at" yaml:"evaluated_at"`
}

type State struct {
	// CurrentPhase is the current workflow phase.
	CurrentPhase Phase `json:"current_phase" yaml:"current_phase"`

	// CurrentDocument is the document currently being worked on.
	CurrentDocument DocType `json:"current_document,omitempty" yaml:"current_document,omitempty"`

	// CompletedDocs lists completed document types.
	CompletedDocs []DocType `json:"completed_docs" yaml:"completed_docs"`

	// PendingDocs lists pending document types.
	PendingDocs []DocType `json:"pending_docs" yaml:"pending_docs"`

	// InProgressDocs lists in-progress document types.
	InProgressDocs []DocType `json:"in_progress_docs,omitempty" yaml:"in_progress_docs,omitempty"`

	// DocumentScores maps document types to their quality scores.
	DocumentScores map[DocType]*QualityScore `json:"document_scores,omitempty" yaml:"document_scores,omitempty"`

	// PhaseProgress tracks progress per phase (0.0-1.0).
	PhaseProgress map[Phase]float64 `json:"phase_progress,omitempty" yaml:"phase_progress,omitempty"`

	// LastUpdated is when the state was last modified.
	LastUpdated time.Time `json:"last_updated" yaml:"last_updated"`

	// WorkflowStarted is when the workflow began.
	WorkflowStarted time.Time `json:"workflow_started,omitempty" yaml:"workflow_started,omitempty"`

	// Metadata contains additional parsed state data.
	Metadata map[string]any `json:"metadata,omitempty" yaml:"metadata,omitempty"`
}

type StateParser struct {
	// contains filtered or unexported fields
}

type StepExecutionStatus string

type StepTiming struct {
	// StepID is the step identifier.
	StepID string `json:"step_id" yaml:"step_id"`

	// StartTime is when the step started.
	StartTime time.Time `json:"start_time,omitempty" yaml:"start_time,omitempty"`

	// EndTime is when the step completed.
	EndTime time.Time `json:"end_time,omitempty" yaml:"end_time,omitempty"`

	// Duration is the step duration.
	Duration time.Duration `json:"duration,omitempty" yaml:"duration,omitempty"`

	// Status is the current step status.
	Status StepExecutionStatus `json:"status" yaml:"status"`
}

type SyncAction struct {
	// Direction is the sync direction.
	Direction SyncDirection `json:"direction" yaml:"direction"`

	// DocType is the document type being synced.
	DocType DocType `json:"doc_type" yaml:"doc_type"`

	// SourcePath is the source file path.
	SourcePath string `json:"source_path" yaml:"source_path"`

	// DestPath is the destination file path.
	DestPath string `json:"dest_path" yaml:"dest_path"`

	// Action describes the operation (create, update, delete).
	Action string `json:"action" yaml:"action"`

	// Reason explains why the action is needed.
	Reason string `json:"reason,omitempty" yaml:"reason,omitempty"`
}

type SyncConflict struct {
	// DocType is the conflicting document type.
	DocType DocType `json:"doc_type" yaml:"doc_type"`

	// VisionSpecPath is the VisionSpec file path.
	VisionSpecPath string `json:"visionspec_path" yaml:"visionspec_path"`

	// AIDLCPath is the AIDLC file path.
	AIDLCPath string `json:"aidlc_path" yaml:"aidlc_path"`

	// VisionSpecModTime is when the VisionSpec file was modified.
	VisionSpecModTime time.Time `json:"visionspec_mod_time" yaml:"visionspec_mod_time"`

	// AIDLCModTime is when the AIDLC file was modified.
	AIDLCModTime time.Time `json:"aidlc_mod_time" yaml:"aidlc_mod_time"`

	// Reason explains the conflict.
	Reason string `json:"reason" yaml:"reason"`
}

type SyncDiff struct {
	// VisionSpecDir is the .visionspec directory path.
	VisionSpecDir string `json:"visionspec_dir" yaml:"visionspec_dir"`

	// AIDLCDocsDir is the aidlc-docs directory path.
	AIDLCDocsDir string `json:"aidlc_docs_dir" yaml:"aidlc_docs_dir"`

	// Actions lists required sync operations.
	Actions []SyncAction `json:"actions" yaml:"actions"`

	// Conflicts lists documents with conflicts requiring resolution.
	Conflicts []SyncConflict `json:"conflicts,omitempty" yaml:"conflicts,omitempty"`

	// ComputedAt is when the diff was computed.
	ComputedAt time.Time `json:"computed_at" yaml:"computed_at"`
}

type SyncDirection string

type SyncEngine struct {
	// VisionSpecDir is the .visionspec directory path.
	VisionSpecDir string

	// AIDLCDocsDir is the aidlc-docs directory path.
	AIDLCDocsDir string

	// ConflictStrategy determines how conflicts are resolved.
	ConflictStrategy ConflictStrategy

	// DryRun prevents actual file modifications when true.
	DryRun bool
}

type SyncResult struct {
	// Direction is the sync direction performed.
	Direction SyncDirection `json:"direction" yaml:"direction"`

	// Created lists newly created files.
	Created []string `json:"created,omitempty" yaml:"created,omitempty"`

	// Updated lists updated files.
	Updated []string `json:"updated,omitempty" yaml:"updated,omitempty"`

	// Skipped lists skipped files (conflicts or errors).
	Skipped []string `json:"skipped,omitempty" yaml:"skipped,omitempty"`

	// Errors lists any errors encountered.
	Errors []string `json:"errors,omitempty" yaml:"errors,omitempty"`

	// CompletedAt is when the sync completed.
	CompletedAt time.Time `json:"completed_at" yaml:"completed_at"`
}

type Template struct {
	// DocType is the document type this template is for.
	DocType DocType `json:"doc_type" yaml:"doc_type"`

	// Name is the template display name.
	Name string `json:"name" yaml:"name"`

	// Description describes the document's purpose.
	Description string `json:"description" yaml:"description"`

	// Content is the markdown template content.
	Content string `json:"content" yaml:"content"`

	// Sections lists the expected sections.
	Sections []TemplateSection `json:"sections" yaml:"sections"`
}

type TemplateData struct {
	// ProjectName is the project name.
	ProjectName string

	// Title is the document title.
	Title string

	// Author is the document author.
	Author string

	// Date is the creation date.
	Date string

	// Version is the document version.
	Version string

	// Description is a brief description.
	Description string

	// Custom contains additional custom fields.
	Custom map[string]string
}

type TemplateSection struct {
	// ID is the section identifier.
	ID string `json:"id" yaml:"id"`

	// Title is the section heading.
	Title string `json:"title" yaml:"title"`

	// Required indicates if this section is mandatory.
	Required bool `json:"required" yaml:"required"`

	// Description explains what goes in this section.
	Description string `json:"description" yaml:"description"`
}

type TransitionEntry struct {
	// FromPhase is the source phase.
	FromPhase Phase `json:"from_phase" yaml:"from_phase"`

	// ToPhase is the target phase.
	ToPhase Phase `json:"to_phase" yaml:"to_phase"`

	// Timestamp is when the transition occurred.
	Timestamp time.Time `json:"timestamp" yaml:"timestamp"`

	// ApprovedBy is who approved the transition (if required).
	ApprovedBy string `json:"approved_by,omitempty" yaml:"approved_by,omitempty"`

	// Notes are optional notes about the transition.
	Notes string `json:"notes,omitempty" yaml:"notes,omitempty"`
}

type TransitionLog struct {
	// Entries are the transition history.
	Entries []TransitionEntry `json:"entries" yaml:"entries"`
}

type TransitionResult struct {
	// Success indicates if the transition succeeded.
	Success bool `json:"success" yaml:"success"`

	// FromPhase is the source phase.
	FromPhase Phase `json:"from_phase" yaml:"from_phase"`

	// ToPhase is the target phase.
	ToPhase Phase `json:"to_phase" yaml:"to_phase"`

	// BlockingDocs are documents preventing transition.
	BlockingDocs []DocType `json:"blocking_docs,omitempty" yaml:"blocking_docs,omitempty"`

	// BlockingIssues are issues preventing transition.
	BlockingIssues []string `json:"blocking_issues,omitempty" yaml:"blocking_issues,omitempty"`

	// Timestamp is when the transition was attempted.
	Timestamp time.Time `json:"timestamp" yaml:"timestamp"`
}

type TransitionRule struct {
	// TargetPhase is the phase to transition to.
	TargetPhase Phase `json:"target_phase" yaml:"target_phase"`

	// RequiredDocs are document types that must be completed.
	RequiredDocs []DocType `json:"required_docs" yaml:"required_docs"`

	// MinScore is the minimum quality score required (0-1).
	MinScore float64 `json:"min_score,omitempty" yaml:"min_score,omitempty"`

	// AllowPartial allows transition with partial scores.
	AllowPartial bool `json:"allow_partial,omitempty" yaml:"allow_partial,omitempty"`

	// RequireApproval requires explicit approval for transition.
	RequireApproval bool `json:"require_approval,omitempty" yaml:"require_approval,omitempty"`
}

type Workflow struct {
	// Name is the workflow name.
	Name string `json:"name" yaml:"name"`

	// Description is a brief description of the workflow.
	Description string `json:"description,omitempty" yaml:"description,omitempty"`

	// Phases are the workflow phases in order.
	Phases []WorkflowPhase `json:"phases" yaml:"phases"`

	// Nodes are all workflow nodes indexed by ID.
	Nodes map[string]*WorkflowNode `json:"nodes" yaml:"nodes"`

	// Edges define dependencies between nodes.
	Edges []WorkflowEdge `json:"edges" yaml:"edges"`
}

type WorkflowEdge struct {
	// From is the source node ID.
	From string `json:"from" yaml:"from"`

	// To is the target node ID.
	To string `json:"to" yaml:"to"`

	// Type is the edge type (dependency, blocks, suggests).
	Type EdgeType `json:"type" yaml:"type"`

	// Label is an optional edge label.
	Label string `json:"label,omitempty" yaml:"label,omitempty"`
}

type WorkflowExecutionContext struct {
	// Workflow is the underlying AIDLC workflow.
	Workflow *Workflow

	// Protocol is the pidl protocol representation.
	Protocol *pidl.Protocol

	// StartTime is when execution started.
	StartTime time.Time

	// StepTimings tracks timing for each step.
	StepTimings map[string]*StepTiming

	// StepStatus tracks the status of each step.
	StepStatus map[string]StepExecutionStatus

	// ExecutionOrder is the topologically sorted execution order.
	ExecutionOrder []string

	// Dependencies maps step ID to its required predecessor step IDs.
	Dependencies map[string][]string

	// Dependents maps step ID to steps that depend on it.
	Dependents map[string][]string
}

type WorkflowNode struct {
	// ID is the unique node identifier.
	ID string `json:"id" yaml:"id"`

	// DocType is the AIDLC document type.
	DocType DocType `json:"doc_type" yaml:"doc_type"`

	// Phase is the workflow phase.
	Phase Phase `json:"phase" yaml:"phase"`

	// Name is the display name.
	Name string `json:"name" yaml:"name"`

	// Description describes the node purpose.
	Description string `json:"description,omitempty" yaml:"description,omitempty"`

	// Status is the node status.
	Status NodeStatus `json:"status" yaml:"status"`

	// Score is the quality score (if evaluated).
	Score *QualityScore `json:"score,omitempty" yaml:"score,omitempty"`

	// DependsOn lists node IDs this node depends on.
	DependsOn []string `json:"depends_on,omitempty" yaml:"depends_on,omitempty"`

	// Blocks lists node IDs blocked by this node.
	Blocks []string `json:"blocks,omitempty" yaml:"blocks,omitempty"`

	// Required indicates if this node is required.
	Required bool `json:"required" yaml:"required"`

	// Automated indicates if this node is LLM-generated.
	Automated bool `json:"automated,omitempty" yaml:"automated,omitempty"`

	// Metadata contains additional node data.
	Metadata map[string]any `json:"metadata,omitempty" yaml:"metadata,omitempty"`
}

type WorkflowPhase struct {
	// ID is the phase identifier.
	ID string `json:"id" yaml:"id"`

	// Name is the display name.
	Name string `json:"name" yaml:"name"`

	// Description describes the phase purpose.
	Description string `json:"description,omitempty" yaml:"description,omitempty"`

	// Order is the phase order (0-indexed).
	Order int `json:"order" yaml:"order"`

	// NodeIDs are the node IDs in this phase.
	NodeIDs []string `json:"node_ids" yaml:"node_ids"`
}

type WorkflowProgress struct {
	// Completed is the number of completed nodes.
	Completed int `json:"completed" yaml:"completed"`

	// Total is the total number of nodes.
	Total int `json:"total" yaml:"total"`

	// Percent is the completion percentage (0-100).
	Percent float64 `json:"percent" yaml:"percent"`

	// PhaseProgress maps phase IDs to progress.
	PhaseProgress map[string]float64 `json:"phase_progress,omitempty" yaml:"phase_progress,omitempty"`
}