lesson

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

	// Slug is the Lesson slug. Caller is expected to have validated it via
	// lesson.ValidateSlug.
	Slug string

	// To is the canonical (title-case) target status.
	To lifecycle.Status

	// Note is the optional free-form markdown transition note, written as a
	// `## Resolution` section. REQUIRED (enforced by the cobra adapter) for
	// the Withdrawn and Superseded dispositions.
	Note string

	// Successor is the slug of the lesson that supersedes this one. REQUIRED
	// (enforced by the cobra adapter) for --to=Superseded, rejected
	// otherwise. Written as a `**Superseded By:** <slug>` header line.
	Successor string

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

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

type Lesson struct {
	Path string // absolute path on disk
	Slug string // filename without `.md`

	HasLessonTitle bool   // first H1 line was `# Lesson: <title>`
	TitleLine      int    // 1-based line number of the title (0 when absent)
	Title          string // the `<title>` portion after `# Lesson: `

	Status     string // value of `**Status:**` (empty when missing)
	StatusLine int    // 1-based line of the field; 0 when absent

	Date     string // value of `**Date:**` (empty when missing)
	DateLine int    // 1-based line of the field; 0 when absent

	Owner     string // value of `**Owner:**` (empty when missing)
	OwnerLine int    // 1-based line of the field; 0 when absent

	Recurred      int    // parsed `**Recurred:**` count; 0 when absent or unparsable
	RecurredRaw   string // raw value as written
	RecurredLine  int    // 1-based line of the field; 0 when absent
	RecurredValid bool   // true when RecurredRaw parsed cleanly as a non-negative integer

	SupersededBy     string // value of `**Superseded By:**` (empty when missing)
	SupersededByLine int    // 1-based line of the field; 0 when absent

	// SectionLines maps a present H2 section title to its 1-based heading
	// line. Only sections found in the body appear here; callers check
	// RequiredSections membership against this map's keys to find gaps.
	SectionLines map[string]int
}

type PostMutationHook func() error

type ScaffoldOptions struct {
	Slug  string
	Title string // defaults to a title-cased slug
	Owner string // defaults to "unknown"
	Date  string // ISO-8601 (YYYY-MM-DD); defaults to today's UTC date
}