campaign

type CampaignApprovalPolicy struct {
	RequiredApprovals int      `yaml:"required-approvals,omitempty" json:"required-approvals,omitempty"`
	RequiredRoles     []string `yaml:"required-roles,omitempty" json:"required-roles,omitempty"`
	ChangeControl     bool     `yaml:"change-control,omitempty" json:"change-control,omitempty"`
}

type CampaignBootstrapConfig struct {
	// Mode determines the bootstrap strategy when no work items are discovered.
	// Valid values:
	//   - "seeder-worker": Dispatch a seeder/scanner worker workflow to discover work
	//   - "project-todos": Read items from Project board's "Todo" column
	//   - "manual": Skip bootstrap, wait for manual work item creation
	Mode string `yaml:"mode" json:"mode"`

	// SeederWorker specifies which worker workflow to dispatch for initial scanning.
	// Only used when Mode is "seeder-worker".
	SeederWorker *SeederWorkerConfig `yaml:"seeder-worker,omitempty" json:"seeder_worker,omitempty"`

	// ProjectTodos specifies configuration for reading from Project board.
	// Only used when Mode is "project-todos".
	ProjectTodos *ProjectTodosConfig `yaml:"project-todos,omitempty" json:"project_todos,omitempty"`
}

type CampaignGovernancePolicy struct {
	// MaxNewItemsPerRun caps how many new items (issues/PRs) the launcher should
	// add to the Project board per run. 0 means "use defaults".
	MaxNewItemsPerRun int `yaml:"max-new-items-per-run,omitempty" json:"max_new_items_per_run,omitempty"`

	// MaxDiscoveryItemsPerRun caps how many candidate issues/PRs the launcher
	// and orchestrator may scan during discovery in a single run.
	// 0 means "use defaults".
	MaxDiscoveryItemsPerRun int `yaml:"max-discovery-items-per-run,omitempty" json:"max_discovery_items_per_run,omitempty"`

	// MaxDiscoveryPagesPerRun caps how many pages of results the launcher and
	// orchestrator may fetch in a single run.
	// 0 means "use defaults".
	MaxDiscoveryPagesPerRun int `yaml:"max-discovery-pages-per-run,omitempty" json:"max_discovery_pages_per_run,omitempty"`

	// OptOutLabels is a list of labels that opt an issue/PR out of campaign
	// tracking. Items with any of these labels should be ignored by launcher/
	// orchestrator.
	OptOutLabels []string `yaml:"opt-out-labels,omitempty" json:"opt_out_labels,omitempty"`

	// DoNotDowngradeDoneItems prevents moving Project status backwards (e.g.
	// Done -> In Progress) if the underlying issue/PR is reopened.
	DoNotDowngradeDoneItems *bool `yaml:"do-not-downgrade-done-items,omitempty" json:"do_not_downgrade_done_items,omitempty"`

	// MaxProjectUpdatesPerRun controls the update-project safe-output maximum
	// for generated coordinator workflows. 0 means "use defaults".
	MaxProjectUpdatesPerRun int `yaml:"max-project-updates-per-run,omitempty" json:"max_project_updates_per_run,omitempty"`

	// MaxCommentsPerRun controls the add-comment safe-output maximum for
	// generated coordinator workflows. 0 means "use defaults".
	MaxCommentsPerRun int `yaml:"max-comments-per-run,omitempty" json:"max_comments_per_run,omitempty"`
}

type CampaignKPI struct {
	// ID is an optional stable identifier for this KPI.
	ID string `yaml:"id,omitempty" json:"id,omitempty"`

	// Name is a human-readable KPI name.
	Name string `yaml:"name" json:"name"`

	// Priority indicates whether this KPI is the primary KPI or a supporting KPI.
	// Expected values: primary, supporting.
	Priority string `yaml:"priority,omitempty" json:"priority,omitempty"`

	// Unit is an optional unit string (e.g., percent, days, count).
	Unit string `yaml:"unit,omitempty" json:"unit,omitempty"`

	// Baseline is the baseline KPI value.
	Baseline float64 `yaml:"baseline" json:"baseline"`

	// Target is the target KPI value.
	Target float64 `yaml:"target" json:"target"`

	// TimeWindowDays is the rolling time window (in days) used to compute the KPI.
	TimeWindowDays int `yaml:"time-window-days" json:"time-window-days"`

	// Direction indicates whether improvement means increasing or decreasing.
	// Expected values: increase, decrease.
	Direction string `yaml:"direction,omitempty" json:"direction,omitempty"`

	// Source describes the signal source used to compute the KPI.
	// Expected values: ci, pull_requests, code_security, custom.
	Source string `yaml:"source,omitempty" json:"source,omitempty"`
}

type CampaignMetricsSnapshot struct {
	Date                string  `json:"date"`            // Required: YYYY-MM-DD format
	CampaignID          string  `json:"campaign_id"`     // Required: campaign identifier
	TasksTotal          int     `json:"tasks_total"`     // Required: total task count (>= 0)
	TasksCompleted      int     `json:"tasks_completed"` // Required: completed task count (>= 0)
	TasksInProgress     int     `json:"tasks_in_progress,omitempty"`
	TasksBlocked        int     `json:"tasks_blocked,omitempty"`
	VelocityPerDay      float64 `json:"velocity_per_day,omitempty"`
	EstimatedCompletion string  `json:"estimated_completion,omitempty"`
}

type CampaignPromptData struct {
	// CampaignID is the unique identifier for this campaign.
	CampaignID string

	// CampaignName is the human-readable name of this campaign.
	CampaignName string

	// Objective is the campaign objective statement.
	Objective string

	// KPIs is the KPI definition list for this campaign.
	KPIs []CampaignKPI

	// ProjectURL is the GitHub Project URL
	ProjectURL string

	// CursorGlob is a glob for locating the durable cursor/checkpoint file in repo-memory.
	CursorGlob string

	// MetricsGlob is a glob for locating the metrics snapshot directory in repo-memory.
	MetricsGlob string

	// MaxDiscoveryItemsPerRun caps how many candidate items may be scanned during discovery.
	MaxDiscoveryItemsPerRun int

	// MaxDiscoveryPagesPerRun caps how many pages may be fetched during discovery.
	MaxDiscoveryPagesPerRun int

	// MaxProjectUpdatesPerRun caps how many project update writes may happen per run.
	MaxProjectUpdatesPerRun int

	// MaxProjectCommentsPerRun caps how many comments may be written per run.
	MaxProjectCommentsPerRun int

	// Workflows is the list of worker workflow IDs associated with this campaign.
	Workflows []string

	// Bootstrap configuration
	BootstrapMode  string
	SeederWorkerID string
	SeederPayload  string
	SeederMaxItems int
	StatusField    string
	TodoValue      string
	TodoMaxItems   int
	RequireFields  []string
	WorkerMetadata []WorkerMetadata
}

type CampaignRuntimeStatus struct {
	ID        string   `json:"id" console:"header:ID"`
	Name      string   `json:"name" console:"header:Name"`
	Workflows []string `json:"workflows,omitempty" console:"header:Workflows,omitempty"`
	Compiled  string   `json:"compiled" console:"header:Compiled"`

	// Optional metrics from repo-memory (when MetricsGlob is set and a
	// matching JSON snapshot is found on the memory/campaigns branch).
	MetricsTasksTotal          int     `json:"metrics_tasks_total,omitempty" console:"header:Tasks Total,omitempty"`
	MetricsTasksCompleted      int     `json:"metrics_tasks_completed,omitempty" console:"header:Tasks Completed,omitempty"`
	MetricsVelocityPerDay      float64 `json:"metrics_velocity_per_day,omitempty" console:"header:Velocity/Day,omitempty"`
	MetricsEstimatedCompletion string  `json:"metrics_estimated_completion,omitempty" console:"header:ETA,omitempty"`

	// Optional durable cursor/checkpoint info from repo-memory.
	CursorPath      string `json:"cursor_path,omitempty" console:"header:Cursor Path,omitempty,maxlen:40"`
	CursorUpdatedAt string `json:"cursor_updated_at,omitempty" console:"header:Cursor Updated,omitempty,maxlen:30"`
}

type CampaignSpec struct {
	ID          string `yaml:"id" json:"id" console:"header:ID"`
	Name        string `yaml:"name" json:"name" console:"header:Name,maxlen:30"`
	Description string `yaml:"description,omitempty" json:"description,omitempty" console:"header:Description,omitempty,maxlen:60"`

	// Objective is an optional outcome-owned statement describing what success means
	// for this campaign.
	Objective string `yaml:"objective,omitempty" json:"objective,omitempty" console:"header:Objective,omitempty,maxlen:60"`

	// KPIs is an optional list of KPIs used to measure progress toward the objective.
	// Recommended: 1 primary KPI plus up to 2 supporting KPIs.
	KPIs []CampaignKPI `yaml:"kpis,omitempty" json:"kpis,omitempty"`

	// ProjectURL points to the GitHub Project used as the primary campaign
	// dashboard.
	ProjectURL string `yaml:"project-url,omitempty" json:"project_url,omitempty" console:"header:Project URL,omitempty,maxlen:40"`

	// Version is an optional spec version string (for example: v1).
	// When omitted, it defaults to v1 during validation.
	Version string `yaml:"version,omitempty" json:"version,omitempty" console:"header:Version,omitempty"`

	// Workflows associates this campaign with one or more workflow IDs
	// (basename of the Markdown file without .md).
	Workflows []string `yaml:"workflows,omitempty" json:"workflows,omitempty" console:"header:Workflows,omitempty,maxlen:40"`

	// TrackerLabel is an optional label used to discover worker-created issues/PRs
	// (for example: campaign:security-q1-2025). When set, the discovery precomputation
	// step will search for items with this label.
	TrackerLabel string `yaml:"tracker-label,omitempty" json:"tracker_label,omitempty" console:"header:Tracker Label,omitempty,maxlen:40"`

	// DiscoveryRepos defines the explicit list of repositories (in owner/repo format)
	// where worker workflows are discovered. This controls the scope of GitHub searches
	// for issues/PRs created by worker workflows.
	DiscoveryRepos []string `yaml:"discovery-repos,omitempty" json:"discovery_repos,omitempty" console:"header:Discovery Repos,omitempty,maxlen:60"`

	// DiscoveryOrgs optionally defines the list of GitHub organizations where worker
	// workflows are discovered. When specified, any repository within these organizations
	// is searched for worker-created issues/PRs.
	DiscoveryOrgs []string `yaml:"discovery-orgs,omitempty" json:"discovery_orgs,omitempty" console:"header:Discovery Orgs,omitempty,maxlen:40"`

	// AllowedRepos defines the explicit list of repositories (in owner/repo format)
	// that this campaign is allowed to discover and operate on. When omitted, defaults
	// to the current repository where the campaign is defined.
	AllowedRepos []string `yaml:"allowed-repos,omitempty" json:"allowed_repos,omitempty" console:"header:Allowed Repos,omitempty,maxlen:60"`

	// AllowedOrgs optionally defines the list of GitHub organizations that this
	// campaign is allowed to discover and operate on. When specified, any repository
	// within these organizations is considered in-scope.
	AllowedOrgs []string `yaml:"allowed-orgs,omitempty" json:"allowed_orgs,omitempty" console:"header:Allowed Orgs,omitempty,maxlen:40"`

	// MemoryPaths documents where this campaign writes its repo-memory
	// (for example: memory/campaigns/incident-response/**).
	MemoryPaths []string `yaml:"memory-paths,omitempty" json:"memory_paths,omitempty" console:"header:Memory Paths,omitempty,maxlen:40"`

	// MetricsGlob is an optional glob (relative to the repository root)
	// used to locate JSON metrics snapshots stored in the
	// memory/campaigns branch. When set, `gh aw campaign status` will
	// attempt to read the latest matching metrics file and surface a few
	// key fields.
	MetricsGlob string `yaml:"metrics-glob,omitempty" json:"metrics_glob,omitempty" console:"header:Metrics Glob,omitempty,maxlen:30"`

	// CursorGlob is an optional glob (relative to the repository root)
	// used to locate a durable cursor/checkpoint file stored in the
	// memory/campaigns branch. When set, generated coordinator workflows
	// will be instructed to continue incremental discovery from this cursor
	// and `gh aw campaign status` will surface its freshness.
	CursorGlob string `yaml:"cursor-glob,omitempty" json:"cursor_glob,omitempty" console:"header:Cursor Glob,omitempty,maxlen:30"`

	// Owners lists the primary human owners for this campaign.
	Owners []string `yaml:"owners,omitempty" json:"owners,omitempty" console:"header:Owners,omitempty,maxlen:30"`

	// ExecutiveSponsors lists executive stakeholders or sponsors who are
	// accountable for the outcome of this campaign.
	ExecutiveSponsors []string `` /* 127-byte string literal not displayed */

	// RiskLevel is an optional free-form field (e.g. low/medium/high).
	RiskLevel string `yaml:"risk-level,omitempty" json:"risk_level,omitempty" console:"header:Risk Level,omitempty"`

	// State describes the lifecycle stage of the campaign definition.
	// Valid values are: planned, active, paused, completed, archived.
	State string `yaml:"state,omitempty" json:"state,omitempty" console:"header:State,omitempty"`

	// Tags provide free-form categorization for reporting (for example:
	// security, modernization, rollout).
	Tags []string `yaml:"tags,omitempty" json:"tags,omitempty" console:"header:Tags,omitempty,maxlen:30"`

	// AllowedSafeOutputs documents which safe-outputs operations this
	// campaign is expected to use (for example: create-issue,
	// create-pull-request). This is currently informational but can be
	// enforced by validation in the future.
	AllowedSafeOutputs []string `` /* 133-byte string literal not displayed */

	// ProjectGitHubToken is an optional GitHub token expression (e.g.,
	// ${{ secrets.GH_AW_PROJECT_GITHUB_TOKEN }}) used for GitHub Projects v2
	// operations. When specified, this token is passed to the update-project
	// safe output configuration in the generated orchestrator workflow.
	ProjectGitHubToken string `` /* 126-byte string literal not displayed */

	// Governance configures lightweight pacing and opt-out policies for campaign
	// orchestrator workflows. These guardrails are primarily enforced through
	// generated prompts and safe-output maxima.
	Governance *CampaignGovernancePolicy `yaml:"governance,omitempty" json:"governance,omitempty"`

	// ApprovalPolicy describes high-level approval expectations for this
	// campaign (for example: number of approvals and required roles).
	ApprovalPolicy *CampaignApprovalPolicy `yaml:"approval-policy,omitempty" json:"approval-policy,omitempty"`

	// Engine specifies the AI engine to use for the campaign orchestrator.
	// Valid values: copilot, claude, codex, custom.
	// Default: copilot (when not specified).
	Engine string `yaml:"engine,omitempty" json:"engine,omitempty" console:"header:Engine,omitempty"`

	// Bootstrap defines the initial work item creation strategy when discovery
	// returns zero items. This provides a way to seed the campaign with initial
	// work when there are no worker-created items to discover.
	Bootstrap *CampaignBootstrapConfig `yaml:"bootstrap,omitempty" json:"bootstrap,omitempty"`

	// Workers defines metadata for worker workflows, including their capabilities,
	// payload schemas, and output labeling contracts. This enables deterministic
	// worker selection and ensures worker outputs are discoverable.
	Workers []WorkerMetadata `yaml:"workers,omitempty" json:"workers,omitempty"`

	// ConfigPath is populated at load time with the relative path of
	// the YAML file on disk, to help users locate definitions.
	ConfigPath string `yaml:"-" json:"config_path" console:"header:Config Path,maxlen:60"`
}

type CampaignValidationResult struct {
	ID         string   `json:"id" console:"header:ID"`
	Name       string   `json:"name" console:"header:Name"`
	ConfigPath string   `json:"config_path" console:"header:Config Path"`
	Problems   []string `json:"problems,omitempty" console:"header:Problems,omitempty"`
}

type ProjectTodosConfig struct {
	// StatusField is the name of the Project status field to filter on.
	// Defaults to "Status".
	StatusField string `yaml:"status-field,omitempty" json:"status_field,omitempty"`

	// TodoValue is the status value that indicates a work item is ready to start.
	// Defaults to "Todo".
	TodoValue string `yaml:"todo-value,omitempty" json:"todo_value,omitempty"`

	// MaxItems caps the number of Todo items to process per orchestrator run.
	// 0 means use the governance default.
	MaxItems int `yaml:"max-items,omitempty" json:"max_items,omitempty"`

	// RequireFields lists Project field names that must be populated for an
	// item to be considered valid work. Empty items are skipped.
	RequireFields []string `yaml:"require-fields,omitempty" json:"require_fields,omitempty"`
}

type SeederWorkerConfig struct {
	// WorkflowID is the workflow identifier (basename without .md) to dispatch.
	WorkflowID string `yaml:"workflow-id" json:"workflow_id"`

	// Payload is the JSON payload to send to the seeder worker.
	// This should conform to the worker's payload schema.
	Payload map[string]any `yaml:"payload" json:"payload"`

	// MaxItems caps the number of work items the seeder should return.
	// 0 means use the worker's default.
	MaxItems int `yaml:"max-items,omitempty" json:"max_items,omitempty"`
}

type WorkerMetadata struct {
	// ID is the workflow identifier (basename without .md).
	ID string `yaml:"id" json:"id"`

	// Name is a human-readable name for the worker.
	Name string `yaml:"name,omitempty" json:"name,omitempty"`

	// Description describes what the worker does.
	Description string `yaml:"description,omitempty" json:"description,omitempty"`

	// Capabilities lists what types of work this worker can perform.
	// Examples: "scan-security-alerts", "fix-dependencies", "update-docs"
	Capabilities []string `yaml:"capabilities" json:"capabilities"`

	// PayloadSchema defines the expected structure of the JSON payload.
	// This is a map of field names to field types/descriptions.
	PayloadSchema map[string]WorkerPayloadField `yaml:"payload-schema" json:"payload_schema"`

	// OutputLabeling defines the labeling contract for worker outputs.
	// This guarantees outputs are discoverable and attributable.
	OutputLabeling WorkerOutputLabeling `yaml:"output-labeling" json:"output_labeling"`

	// IdempotencyStrategy describes how the worker ensures idempotent execution.
	// Valid values: "branch-based", "pr-title-based", "issue-title-based", "cursor-based"
	IdempotencyStrategy string `yaml:"idempotency-strategy" json:"idempotency_strategy"`

	// Priority indicates worker priority for deterministic selection when multiple
	// workers can handle the same work item. Higher numbers = higher priority.
	Priority int `yaml:"priority,omitempty" json:"priority,omitempty"`
}

type WorkerOutputLabeling struct {
	// Labels are the labels the worker applies to created items.
	// The campaign's tracker-label is automatically applied by the worker
	// in addition to these labels.
	// Examples: "security", "automated", "dependencies"
	Labels []string `yaml:"labels,omitempty" json:"labels,omitempty"`

	// KeyInTitle indicates whether the worker includes a deterministic key in
	// the title of created items (format: "[{key}] {title}").
	KeyInTitle bool `yaml:"key-in-title" json:"key_in_title"`

	// KeyFormat describes the key format when KeyInTitle is true.
	// Example: "campaign-{campaign_id}-{repository}-{work_item_id}"
	KeyFormat string `yaml:"key-format,omitempty" json:"key_format,omitempty"`

	// MetadataFields lists Project fields the worker populates with work metadata.
	// Examples: "Campaign Id", "Worker Workflow", "Priority"
	MetadataFields []string `yaml:"metadata-fields,omitempty" json:"metadata_fields,omitempty"`
}

type WorkerPayloadField struct {
	// Type is the field's data type: "string", "number", "boolean", "array", "object"
	Type string `yaml:"type" json:"type"`

	// Description explains what this field contains and how it's used.
	Description string `yaml:"description" json:"description"`

	// Required indicates whether this field must be present in the payload.
	Required bool `yaml:"required,omitempty" json:"required,omitempty"`

	// Example provides a sample value for this field.
	Example any `yaml:"example,omitempty" json:"example,omitempty"`
}

type WorkflowMatch struct {
	ID          string   // Workflow ID (basename without .md)
	FilePath    string   // Relative path to workflow file
	Name        string   // Workflow name from frontmatter
	Description string   // Workflow description
	Keywords    []string // Matching keywords
	Score       int      // Match score (higher is better)
}