ideator

type Idea struct {
	// Title is a short label for `ideate` print output and the
	// queue list. Empty → orchestrator derives one from the first
	// line of SuggestedPrompt.
	Title string
	// Summary is a 1–3 sentence rationale; the operator reads this
	// when deciding whether to Accept. Stored as Item.Note in the
	// queue.
	Summary string
	// SourceName names the IdeaSource that produced this Idea.
	// Optional in the source-side struct; orchestrator backfills
	// from IdeaSource.Name() when empty.
	SourceName string
	// Evidence carries the file:line / test name / ADR section
	// reference / bench-baseline diff — anything the operator can
	// grep to verify the suggestion isn't fabricated.
	Evidence string
	// SuggestedPriority is the base score (typically 0..10);
	// orchestrator may apply a small evidence-recency bump before
	// final ranking.
	SuggestedPriority int
	// SuggestedPrompt is the verbatim text the agent will receive
	// when it eventually claims the item. Written in the second
	// person ("Investigate the TODO at ..."). Empty → idea is
	// silently dropped by the orchestrator.
	SuggestedPrompt string
	// DedupeKey is a stable hash combining source + evidence;
	// re-running ideate over the same repo state must not multiply
	// the queue. Source authors hash once at construction; the
	// orchestrator AND queue.Propose both deduplicate by this key.
	DedupeKey string
}

type IdeaSource interface {
	Name() string
	Scan(ctx context.Context, repoRoot string) ([]Idea, error)
}

type Options struct {
	RepoRoot     string
	SourceFilter string
	TopK         int
	Sources      []IdeaSource
	Warn         io.Writer
	// MaxConcurrency caps how many sources run at once. 0 → use
	// DefaultMaxConcurrency. Sources fork-exec heavy CLIs (gh,
	// govulncheck, deadcode); on slow filesystems (WSL2 /mnt/c,
	// network shares) unbounded parallelism saturates I/O and
	// bloats wall time 5× vs. running individually. The default
	// is conservative — operators on fast hosts can raise it via
	// CLAWTOOL_IDEATOR_MAX_CONCURRENCY.
	MaxConcurrency int
}

type RunResult struct {
	Ideas        []Idea            `json:"ideas"`
	PerSource    map[string]int    `json:"per_source"`
	Deduped      int               `json:"deduped"`
	Added        int               `json:"added"`
	Skipped      int               `json:"skipped"`
	SourceErrors map[string]string `json:"source_errors,omitempty"`
}