idea

type ArchiveOptions struct {
	// SpecRoot is the project root that contains the `spec/` subtree.
	SpecRoot string
	// Slug is the Idea slug; the active file is resolved at
	// SpecRoot/spec/ideas/<Slug>.md.
	Slug string
	// Note is an optional free-form `**Archive Note:**` value tied to the
	// archive action. Empty (after trimming) writes no note line. The
	// disposition reason belongs on the terminal status transition, not here.
	Note string
	// PostMutation is the post-relocation hook (typically a spec-lint pass).
	// Required.
	PostMutation PostMutationHook
}

type ArchiveResult struct {
	Slug string
	// From is the path the file moved from; To is where it now lives.
	From string
	To   string
}

type ChangeStatusOptions struct {
	// SpecRoot is the project root that contains the `spec/` subtree
	// (NOT the `spec/` directory itself). The Idea file is resolved at
	// SpecRoot/spec/ideas/<Slug>.md.
	SpecRoot string

	// Slug is the Idea slug, e.g. "payment-fraud". Caller is expected
	// to have validated it via idea.ValidateSlug.
	Slug string

	// To is the canonical (title-case) target status, e.g. "Approved"
	// or "Stale". The cobra adapter parses the raw --to value via
	// lifecycle.ParseStatus before reaching this function. (Archival is
	// not a status — see the `idea archive` verb.)
	To lifecycle.Status

	// PostMutation is the post-rewrite hook (typically a spec-lint
	// pass). Required; ChangeStatus returns exit 10 if nil.
	PostMutation PostMutationHook

	// Note is an optional free-form markdown transition note. When non-
	// empty after trimming, it is written into the artifact body as a
	// `## Resolution` section, atomically with the status rewrite, per
	// lifecycle-transitions#REQ:optional-transition-note. An empty or
	// whitespace-only value is a no-op (today's behavior). The note write
	// participates in the same rollback guarantee as the status rewrite.
	Note string
}

type ChangeStatusResult struct {
	Slug string
	From lifecycle.Status
	To   lifecycle.Status
}

type Discovered struct {
	Slug       string
	Path       string // absolute or relative path to the .md file
	Archived   bool   // true if located under archived/
	IsProposal bool   // true if located under spec/features/*/proposals/
	FeatureDir string // non-empty for proposals: the feature directory slug
}

type HeaderField struct {
	Name  string
	Value string
	Line  int
}

type Idea struct {
	Path           string
	Slug           string
	Title          string // full title line (without leading "# ")
	TitleName      string // name portion after "Idea: " or "Proposal: "
	TitleOK        bool   // true if title matches "# Idea: <Name>" or "# Proposal: <Name>"
	TitlePrefix    string // "Idea" or "Proposal" (set when TitleOK is true)
	TitleLine      int
	HasTitle       bool
	Fields         []HeaderField // in-order header fields encountered
	FieldByName    map[string]HeaderField
	Sections       []Section
	SectionByTitle map[string]*Section
	RawLines       []string
}

type PostMutationHook func() error

type ScaffoldOptions struct {
	Slug string
	// Title is the human-readable name after `# Idea: ` or `# Proposal: `.
	// Defaults to a title-cased version of the slug.
	Title string
	Owner string
	// Date in ISO-8601 (YYYY-MM-DD). Defaults to today's UTC date.
	Date string
	// Status defaults to "Draft".
	Status string

	// Type is the idea type: "feature-request" (default) or "change-request".
	// When "change-request", the title prefix becomes "# Proposal: " and the
	// Type/Targets fields are emitted in the header.
	Type string
	// Targets is the feature slug this change-request targets. Only meaningful
	// when Type is "change-request".
	Targets string
	// Phase is an optional lifecycle phase value pre-populated in the header.
	Phase string

	// Section content. Empty strings leave the default prompt in place.
	HMW                  string // Problem Statement
	Context              string
	RecommendedDirection string
	Alternatives         []string // Each element is a bullet for Alternatives Considered.
	MVP                  string
	// NotDoing is a list of exclusions. When empty, a lint-clean default
	// list is emitted so the Not Doing section passes idea-not-doing-non-empty.
	NotDoing []string
	// Assumptions is an optional list of assumption-table rows.
	// Each row is {Tier, Assumption, HowToValidate}. When empty, a
	// lint-clean default table with one Must-be-true row is emitted.
	Assumptions [][3]string
	// SpecScore Integration overrides.
	NewFeatures  string
	Existing     string
	Dependencies string
	// OpenQuestions bullets (optional).
	OpenQuestions []string
}

type Section struct {
	Title     string
	StartLine int
	EndLine   int
	Body      string
	Items     []string // lines starting with "- "
}

type Table struct {
	Headers []string
	Rows    [][]string
}

type UnarchiveOptions struct {
	SpecRoot     string
	Slug         string
	PostMutation PostMutationHook
}