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 BlockedConfig struct {
	// VisibleTo lists roles that may see the BLOCKED section. Empty = all roles.
	VisibleTo []string `yaml:"visible_to,omitempty"`

	// Scope filters which blocked specs appear: "all" (default), "involved",
	// or "owning_role".
	Scope string `yaml:"scope,omitempty"`
}

type BuildConfig struct {
	// MaxParallel bounds how many ready nodes the orchestrator fans out at
	// once. Surfaced to the agent via the DAG resource. Defaults to 4.
	MaxParallel int `yaml:"max_parallel,omitempty"`

	// Router selects the skill-routing model handed to the build engine:
	// "registry" (default) routes per-node from .agents/skills/registry.yaml;
	// "none" routes nothing and lets the harness discover skills. Empty = default.
	Router string `yaml:"router,omitempty"`

	// Strategy selects the VCS/review workflow: "stacked-draft-pr" (default)
	// stacks a draft PR per node; "none" keeps work on local branches with no
	// finishing tools. Empty = default.
	Strategy string `yaml:"strategy,omitempty"`
}

type DashboardConfig struct {
	StaleThreshold string        `yaml:"stale_threshold"`
	RefreshTTL     int           `yaml:"refresh_ttl"`
	Blocked        BlockedConfig `yaml:"blocked,omitempty"`
	Urgency        UrgencyConfig `yaml:"urgency,omitempty"`
	Review         ReviewConfig  `yaml:"review,omitempty"`
}

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

type Diagnostic struct {
	File       string   `json:"file"`
	Line       int      `json:"line"`
	Column     int      `json:"column,omitempty"`
	Severity   Severity `json:"severity"`
	Field      string   `json:"field,omitempty"`
	Message    string   `json:"message"`
	Suggestion string   `json:"suggestion,omitempty"`
}

type DoScope string

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"`
}

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 JiraConfig struct {
	BaseURL    string
	Email      string
	Token      string
	ProjectKey string

	// BoardID scopes board analytics; 0 means unset.
	BoardID int
	// TeamID is the Jira Team field value (Advanced Roadmaps / Plans).
	TeamID string

	EpicIssueType  string
	StoryIssueType string

	// Fields maps logical field names (epic_name, team, sprint, story_points)
	// to instance-specific custom-field ids (e.g. customfield_10011).
	Fields map[string]string

	// Labels are applied to every spec-created issue; Components likewise.
	Labels     []string
	Components []string

	// SyncStories opts into creating Jira stories from build steps.
	SyncStories bool

	// StatusMap maps spec pipeline stage names to Jira status names. A stage
	// absent from the map is a no-op for status sync.
	StatusMap map[string]string

	RequestTimeout time.Duration
}

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

type LintResult struct {
	File        string       `json:"file"`
	Diagnostics []Diagnostic `json:"diagnostics"`
}

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"`
}

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,
	// kanagawa, everforest-dark, everforest-light, github-dark, github-light,
	// ayu-mirage, ayu-light, modus-vivendi, modus-operandi, graphite.
	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 ReviewConfig struct {
	// StaleAfter is the review-age window for the time-urgency gradient on
	// REVIEW rows, measured from when the PR was opened. Accepts m/h/d/w units
	// (e.g. "4h", "2d"). Empty, "none", or "0" (the default) means review rows
	// are never coloured — the gradient is opt-in, with no global fallback.
	StaleAfter string `yaml:"stale_after,omitempty"`
}

type Severity 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"`

	// Dashboard controls how this stage's specs surface in the DO section.
	Dashboard StageDashboardConfig `yaml:"dashboard,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"`

	// StaleAfter is the dwell window for the time-urgency gradient: once a spec
	// has spent this long in this stage, its dashboard/pipeline row reaches full
	// urgency. Accepts m/h/d/w units (e.g. "30m", "48h", "5d", "2w"). Empty,
	// "none", or "0" means the stage is never stale and shows no colouring —
	// there is no global fallback window.
	StaleAfter string `yaml:"stale_after,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 StageDashboardConfig struct {
	// DoScope controls who sees specs at this stage in their DO section.
	// One of: "role" (default), "assignee", "author", "none".
	DoScope string `yaml:"do_scope,omitempty"`

	// Claimable, when true (the default), surfaces unassigned specs to the
	// whole owning role under assignee scope so they can be claimed. Set false
	// to hide unassigned specs from everyone until explicitly assigned.
	Claimable *bool `yaml:"claimable,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"`
	// AutoPush governs whether local edits and comments are published to the
	// specs repo automatically. One of AutoPushAuto, AutoPushPrompt, AutoPushOff.
	AutoPush string `yaml:"auto_push"`
}

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"`

	// Build configures the agentic build orchestration (DAG fan-out).
	Build BuildConfig `yaml:"build,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 UrgencyConfig struct {
	// Easing selects how the raw dwell fraction is shaped into colour intensity:
	// "linear", "ease-in" (default), or "ease-in-strong".
	Easing string `yaml:"easing,omitempty"`
}

type UserConfig struct {
	User struct {
		OwnerRole string `yaml:"owner_role"`
		Name      string `yaml:"name"`
		// Handle is the spec-canonical identity token — a stable, user-chosen
		// name that identifies the person inside spec (frontmatter author and
		// assignees, thread author, decision log). It never leaves spec, so it
		// can be anything the user likes. It is also the universal fallback for
		// any per-integration identity that is not explicitly mapped.
		Handle string `yaml:"handle"`
		// Identities maps an integration provider name (e.g. "github", "slack",
		// "teams", "jira") to the user's handle on that service. A person's
		// handle differs on every service, so adapter calls must receive the
		// service-specific value, not the canonical handle. Optional and
		// additive: an absent or partial map falls back to Handle, so existing
		// configs behave identically.
		Identities map[string]string `yaml:"identities,omitempty"`
	} `yaml:"user"`

	Preferences PreferencesConfig `yaml:"preferences"`

	// Agent is an OPTIONAL per-user coding-agent override. A coding harness is
	// a personal tool, so each engineer may pick their own (e.g. claude-code or
	// pi) regardless of the team default. When set (provider non-empty), it
	// takes precedence over integrations.agent in the team config.
	Agent *ProviderConfig `yaml:"agent,omitempty"`

	// 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 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
}