config

type AutoAdvanceConfig struct {
	// Enabled allows explicitly disabling auto-advance even if When is set.
	Enabled *bool `yaml:"enabled,omitempty"`

	// When is an expression that triggers auto-advance when true.
	// Example: "prs.all_approved and prs.threads_resolved"
	When string `yaml:"when,omitempty"`

	// Notify lists targets to notify on auto-advance.
	// Example: ["author", "next_owner"]
	Notify []string `yaml:"notify,omitempty"`

	// QuietHours prevents auto-advance during specified hours.
	// Format: "HH:MM-HH:MM" in local timezone.
	// Example: "22:00-08:00"
	QuietHours string `yaml:"quiet_hours,omitempty"`

	// RequireApproval requires a specific role to have approved (e.g., "tl").
	RequireApproval string `yaml:"require_approval,omitempty"`

	// ExcludeLabels prevents auto-advance for specs with these labels.
	ExcludeLabels []string `yaml:"exclude_labels,omitempty"`
}

type DashboardConfig struct {
	StaleThreshold string `yaml:"stale_threshold"`
	RefreshTTL     int    `yaml:"refresh_ttl"`
}

type DeployConfig struct {
	Provider     string        `yaml:"provider"`
	Environments []Environment `yaml:"environments"`
}

type EffectConfig struct {
	// Notify sends a notification. Can be a string (target) or NotifyEffect.
	Notify *NotifyEffect `yaml:"notify,omitempty"`

	// Sync triggers document sync ("outbound" or "inbound").
	Sync string `yaml:"sync,omitempty"`

	// UpdatePM updates the PM tool (Jira, Linear, etc.).
	UpdatePM *UpdatePMEffect `yaml:"update_pm,omitempty"`

	// LogDecision adds an entry to the decision log.
	LogDecision string `yaml:"log_decision,omitempty"`

	// Increment increments a frontmatter counter (e.g., "revert_count").
	Increment string `yaml:"increment,omitempty"`

	// Webhook calls an external URL.
	Webhook *WebhookEffect `yaml:"webhook,omitempty"`

	// Archive moves the spec to archive/.
	Archive bool `yaml:"archive,omitempty"`

	// Trigger invokes a named workflow or action.
	Trigger string `yaml:"trigger,omitempty"`

	// When is an expression that must be true for this effect to run.
	When string `yaml:"when,omitempty"`
}

type Environment struct {
	Name string `yaml:"name"`
	Auto bool   `yaml:"auto"`
	Gate string `yaml:"gate,omitempty"`
}

type FastTrackConfig struct {
	// Enabled allows fast-track bug fixes. Defaults to false.
	Enabled bool `yaml:"enabled,omitempty"`

	// AllowedRoles lists roles that can create fast-track specs.
	// Defaults to ["engineer", "tl"].
	AllowedRoles []string `yaml:"allowed_roles,omitempty"`

	// MaxDuration is the maximum time before escalation (e.g., "2d", "48h").
	// If exceeded, notifies TL and/or PM.
	MaxDuration string `yaml:"max_duration,omitempty"`

	// RequireLabels requires fast-track specs to have specific labels (e.g., ["bug", "hotfix"]).
	RequireLabels []string `yaml:"require_labels,omitempty"`

	// PipelineVariant is the pipeline variant to use for fast-track specs.
	// If empty, uses a minimal default: build → pr-review → done.
	PipelineVariant string `yaml:"pipeline_variant,omitempty"`

	// ExcludedStages lists stages to skip in fast-track (if not using a variant).
	ExcludedStages []string `yaml:"excluded_stages,omitempty"`
}

type GateConfig struct {
	// Simple gate types (mutually exclusive with Expr)
	SectionNotEmpty string          `yaml:"section_not_empty,omitempty"`
	SectionComplete string          `yaml:"section_complete,omitempty"` // Deprecated: use SectionNotEmpty
	PRStackExists   *bool           `yaml:"pr_stack_exists,omitempty"`  // Deprecated: use StepsExists
	StepsExists     *bool           `yaml:"steps_exists,omitempty"`     // Build plan has at least one step
	PRsApproved     *bool           `yaml:"prs_approved,omitempty"`
	ReviewApproved  *bool           `yaml:"review_approved,omitempty"` // Technical plan review is approved
	Duration        string          `yaml:"duration,omitempty"`
	LinkExists      *LinkExistsGate `yaml:"link_exists,omitempty"`

	// Expression gate
	Expr    string `yaml:"expr,omitempty"`
	Message string `yaml:"message,omitempty"`

	// Logical operators (contain nested gates)
	All []GateConfig `yaml:"all,omitempty"`
	Any []GateConfig `yaml:"any,omitempty"`
	Not *GateConfig  `yaml:"not,omitempty"`
}

type IntakeConfig struct {
	Sources []IntakeSource `yaml:"sources"`
}

type IntakeSource struct {
	Provider   string `yaml:"provider"`
	AutoCreate bool   `yaml:"auto_create"`
	Filter     string `yaml:"filter,omitempty"`
	Channel    string `yaml:"channel,omitempty"`
	Trigger    string `yaml:"trigger,omitempty"`
	Token      string `yaml:"token,omitempty"`
}

type IntegrationsConfig struct {
	Comms  ProviderConfig `yaml:"comms"`
	PM     ProviderConfig `yaml:"pm"`
	Docs   ProviderConfig `yaml:"docs"`
	Repo   ProviderConfig `yaml:"repo"`
	Agent  ProviderConfig `yaml:"agent"`
	AI     ProviderConfig `yaml:"ai"`
	Design ProviderConfig `yaml:"design"`
	Deploy DeployConfig   `yaml:"deploy"`
	Intake IntakeConfig   `yaml:"intake"`
}

type LabelVariantMapping struct {
	// Label is the spec label to match.
	Label string `yaml:"label,omitempty"`

	// Variant is the variant name to use when the label matches.
	Variant string `yaml:"variant"`

	// Default marks this as the default variant when no labels match.
	Default bool `yaml:"default,omitempty"`
}

type LinkExistsGate struct {
	Section string `yaml:"section"`
	Type    string `yaml:"type,omitempty"` // e.g., "figma", "github"
}

type NotifyEffect struct {
	// Target is who to notify (e.g., "next_owner", "tl", "#channel", "@user").
	Target string `yaml:"target,omitempty"`

	// Targets allows multiple notification targets.
	Targets []string `yaml:"targets,omitempty"`

	// Channel overrides the default channel.
	Channel string `yaml:"channel,omitempty"`

	// Template is the notification template name.
	Template string `yaml:"template,omitempty"`
}

type Owners []string

type PassiveAwarenessConfig struct {
	// Show whitelists item types to display. If empty, shows all.
	// Valid types: review_requests, spec_owned, mentions, triage, fyi, blocked
	Show []string `yaml:"show,omitempty"`

	// Hide blacklists item types to suppress.
	Hide []string `yaml:"hide,omitempty"`

	// DuringBuild shows awareness during `spec do` and `spec build`.
	// Defaults to false to avoid interrupting flow state.
	DuringBuild bool `yaml:"during_build,omitempty"`

	// DismissDuration is how long dismissed items stay hidden.
	// Defaults to "2h". Valid formats: "30m", "2h", "1d".
	DismissDuration string `yaml:"dismiss_duration,omitempty"`
}

type PipelineConfig struct {
	// Preset is the name of a built-in pipeline preset (e.g., "minimal", "product").
	// If set, the preset's stages are used as the base configuration.
	Preset string `yaml:"preset,omitempty"`

	// Skip lists stage names to remove from the preset.
	// Only meaningful when Preset is set.
	Skip []string `yaml:"skip,omitempty"`

	// Stages defines the pipeline stages. When Preset is set, these override
	// or extend the preset's stages. When Preset is empty, these are the
	// complete stage definitions.
	Stages []StageConfig `yaml:"stages,omitempty"`

	// Variants defines alternative pipelines for different work types.
	Variants map[string]VariantConfig `yaml:"variants,omitempty"`

	// Default is the default variant name when multiple variants exist.
	Default string `yaml:"default,omitempty"`

	// VariantFromLabels maps spec labels to variant names for auto-selection.
	VariantFromLabels []LabelVariantMapping `yaml:"variant_from_labels,omitempty"`
}

type PreferencesConfig struct {
	Editor            string   `yaml:"editor"`
	DashboardSections []string `yaml:"dashboard_sections"`
	StandupAutoPost   bool     `yaml:"standup_auto_post"`
	AIDrafts          *bool    `yaml:"ai_drafts,omitempty"`

	// Theme sets the TUI colour theme.
	// Valid values: auto (default), catppuccin-mocha, catppuccin-latte,
	// catppuccin-macchiato, catppuccin-frappe, gruvbox-dark, dracula,
	// tokyo-night, nord, solarized-dark, solarized-light, rose-pine.
	Theme string `yaml:"theme,omitempty"`

	// RefreshInterval sets the TUI auto-refresh period (e.g. "30s", "1m").
	// Defaults to 30s.
	RefreshInterval string `yaml:"refresh_interval,omitempty"`

	// Mouse enables mouse support in the TUI (click tabs, click items).
	// Defaults to false.
	Mouse bool `yaml:"mouse,omitempty"`

	// Multiplexer specifies the terminal multiplexer for cross-repo navigation.
	// Valid values: tmux, zellij, wezterm, iterm2, none
	// If empty or "none", falls back to manual navigation prompts.
	Multiplexer string `yaml:"multiplexer,omitempty"`

	// AutoPull automatically pulls stale specs when running `spec do`.
	// If false, prompts the user before pulling.
	AutoPull bool `yaml:"auto_pull,omitempty"`

	// AutoNavigate opens a new terminal pane when switching repos.
	// Defaults to true. Set to false for manual navigation.
	AutoNavigate *bool `yaml:"auto_navigate,omitempty"`

	// PassiveAwareness configures the passive awareness line shown on commands.
	PassiveAwareness *PassiveAwarenessConfig `yaml:"passive_awareness,omitempty"`
}

type ProviderConfig struct {
	Provider string            `yaml:"provider"`
	Extra    map[string]string `yaml:"-"`
	// contains filtered or unexported fields
}

type ResolvedConfig struct {
	Team *TeamConfig
	User *UserConfig

	// TeamConfigPath is the path to the team config file, if found.
	TeamConfigPath string
	// UserConfigPath is the path to the user config file.
	UserConfigPath string

	// SpecsRepoDir is the local path to the specs/ sub-directory within
	// the specs repo clone. All spec, triage, and archive content lives here.
	SpecsRepoDir string
}

type SpecsRepoConfig struct {
	Provider string `yaml:"provider"`
	Owner    string `yaml:"owner"`
	Repo     string `yaml:"repo"`
	Branch   string `yaml:"branch"`
	Token    string `yaml:"token"`
}

type StageConfig struct {
	// Name is the stage identifier (lowercase, underscores allowed).
	Name string `yaml:"name"`

	// Owner is the role(s) that own this stage. Can be a single role
	// or an array of roles in YAML.
	Owner Owners `yaml:"owner,omitempty"`

	// OwnerRole is the legacy field for backward compatibility.
	//
	// Deprecated: Use Owner instead.
	OwnerRole string `yaml:"owner_role,omitempty"`

	// Icon is an emoji displayed in pipeline views.
	Icon string `yaml:"icon,omitempty"`

	// Optional marks the stage as skippable in the pipeline flow.
	Optional bool `yaml:"optional,omitempty"`

	// SkipWhen is an expression that, when true, causes the stage to be
	// automatically skipped during advancement.
	SkipWhen string `yaml:"skip_when,omitempty"`

	// Gates are conditions that must be satisfied to advance from this stage.
	Gates []GateConfig `yaml:"gates,omitempty"`

	// Warnings are time-based alerts that don't block advancement.
	Warnings []WarningConfig `yaml:"warnings,omitempty"`

	// Transitions customizes advance and revert behavior.
	Transitions TransitionsConfig `yaml:"transitions,omitempty"`

	// OnEnter lists effects to execute when entering this stage.
	OnEnter []EffectConfig `yaml:"on_enter,omitempty"`

	// OnExit lists effects to execute when leaving this stage.
	OnExit []EffectConfig `yaml:"on_exit,omitempty"`

	// AutoArchive moves the spec to archive/ when entering this stage.
	AutoArchive bool `yaml:"auto_archive,omitempty"`

	// Review configures plan review requirements for this stage.
	// Used primarily for the engineering stage to require technical plan approval.
	Review *StageReviewConfig `yaml:"review,omitempty"`

	// AutoAdvance configures automatic stage advancement when gates are satisfied.
	AutoAdvance *AutoAdvanceConfig `yaml:"auto_advance,omitempty"`
}

type StageReviewConfig struct {
	// Required indicates whether review is required to advance.
	// Defaults to true when Review is present.
	Required *bool `yaml:"required,omitempty"`

	// Reviewers lists who can review (roles like "tl" or named users like "@mike").
	// Special value "author" allows self-review.
	Reviewers []string `yaml:"reviewers,omitempty"`

	// MinApprovals is the minimum number of approvals required.
	// Defaults to 1.
	MinApprovals int `yaml:"min_approvals,omitempty"`
}

type SyncConfig struct {
	OutboundOnAdvance bool   `yaml:"outbound_on_advance"`
	ConflictStrategy  string `yaml:"conflict_strategy"`
}

type TeamConfig struct {
	Version string `yaml:"version"`

	Team struct {
		Name       string `yaml:"name"`
		CycleLabel string `yaml:"cycle_label"`
	} `yaml:"team"`

	SpecsRepo SpecsRepoConfig `yaml:"specs_repo"`

	Integrations IntegrationsConfig `yaml:"integrations"`

	Sync SyncConfig `yaml:"sync"`

	Archive struct {
		Directory string `yaml:"directory"`
	} `yaml:"archive"`

	Dashboard DashboardConfig `yaml:"dashboard"`

	Pipeline PipelineConfig `yaml:"pipeline"`

	// FastTrack configures engineer self-service for small bug fixes.
	FastTrack *FastTrackConfig `yaml:"fast_track,omitempty"`
}

type TransitionConfig struct {
	// To lists allowed target stages. Empty means default (next for advance,
	// any previous for revert).
	To []string `yaml:"to,omitempty"`

	// Gates are additional conditions for this specific transition.
	Gates []GateConfig `yaml:"gates,omitempty"`

	// Require lists required fields (e.g., ["reason"] for reverts).
	Require []string `yaml:"require,omitempty"`

	// Effects are side effects to execute on transition.
	Effects []EffectConfig `yaml:"effects,omitempty"`
}

type TransitionsConfig struct {
	Advance TransitionConfig `yaml:"advance,omitempty"`
	Revert  TransitionConfig `yaml:"revert,omitempty"`
}

type UpdatePMEffect struct {
	Status string `yaml:"status,omitempty"`
}

type UserConfig struct {
	User struct {
		OwnerRole string `yaml:"owner_role"`
		Name      string `yaml:"name"`
		Handle    string `yaml:"handle"`
	} `yaml:"user"`

	Preferences PreferencesConfig `yaml:"preferences"`

	// Workspaces maps repo names to local filesystem paths.
	// Used for cross-repo navigation in multi-repo build plans.
	// Example: workspaces: { auth-service: ~/code/auth-service }
	Workspaces map[string]string `yaml:"workspaces,omitempty"`
}

type VariantConfig struct {
	// Preset is the base preset for this variant.
	Preset string `yaml:"preset,omitempty"`

	// Skip lists stages to remove from the preset.
	Skip []string `yaml:"skip,omitempty"`

	// Stages defines or overrides stages for this variant.
	Stages []StageConfig `yaml:"stages,omitempty"`
}

type WarningConfig struct {
	// After is the duration after which the warning triggers (e.g., "5d", "48h").
	After string `yaml:"after"`

	// Message is displayed when the warning is active.
	Message string `yaml:"message"`

	// Notify is the target to notify (e.g., "tl", "#channel").
	Notify string `yaml:"notify,omitempty"`
}

type WebhookEffect struct {
	URL     string            `yaml:"url"`
	Method  string            `yaml:"method,omitempty"` // default: POST
	Headers map[string]string `yaml:"headers,omitempty"`
	Body    map[string]string `yaml:"body,omitempty"`
	Timeout string            `yaml:"timeout,omitempty"` // default: 10s
}