plan

type ChangeStatusOptions struct {
	// SpecRoot is the project root that contains the `spec/` subtree
	// (NOT the `spec/` directory itself). The Plan is resolved at
	// SpecRoot/spec/plans/<slug>.md (flat) or .../spec/plans/<slug>/README.md
	// (the optional directory form).
	SpecRoot string

	// Slug is the Plan slug, e.g. "user-auth". Caller is expected to have
	// validated it via plan.ValidateSlug.
	Slug string

	// To is the canonical (title-case) target status. The cobra adapter parses
	// the raw --to value via lifecycle.ParseStatus and rejects execution-band /
	// unrecognized values BEFORE reaching this function.
	To lifecycle.Status

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

	// Successor is the slug of the plan that supersedes this one. REQUIRED
	// (enforced by the cobra adapter) for --to=Superseded, rejected otherwise.
	// It is 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 DeferredAC struct {
	ACID   string // `<feature-slug>#ac:<ac-slug>`
	Line   int    // 1-based line of the entry
	Reason string // text after the em-dash; opaque to lint
}

type Mode string

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

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

	SourceFeature     string // value of `**Source Feature:**` (empty when missing)
	SourceFeatureLine int    // 1-based line of the field; 0 when absent
	SourceIdea        string // Idea slug from `**Source:** idea:<slug>` (empty when not idea-sourced)
	SourceNone        bool   // true when the source line is `**Source:** none` (source-less plan)
	SourceRaw         string // raw value of a `**Source:**` line as written (empty when absent)
	SourceLine        int    // 1-based line of the `**Source:**` field; 0 when absent
	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
	Parent            string // value of `**Parent:**` (empty when missing) — master/sub-plan composition
	ParentLine        int    // 1-based line of the field; 0 when absent
	Mode              Mode   // `full` (default) or `stub`
	ModeLine          int    // 1-based line of `**Mode:**`; 0 when absent
	ModeRaw           string // raw value as written (used by P-004 to report invalid tokens)
	ModeRawPresent    bool   // true when the field was present at all
	ModeValueValid    bool   // true when ModeRaw parsed cleanly into Mode

	Tasks []Task // task blocks in source order

	DeferredACs     []DeferredAC // entries under `## Deferred AC Coverage`
	DeferredACsLine int          // 1-based line of the H2 heading; 0 when absent
}

type PostMutationHook func() error

type Rollup struct {
	Total      int `yaml:"total" json:"total"`
	Done       int `yaml:"done" json:"done"`
	InProgress int `yaml:"in-progress" json:"in-progress"`
	Pending    int `yaml:"pending" json:"pending"`
	Blocked    int `yaml:"blocked" json:"blocked"`
}

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
	// At most one of SourceFeature / SourceIdea may be set: a plan decomposes
	// one Feature, one Idea, or no source at all (source-less, emitted as
	// `**Source:** none`) (cli/plan/new#req:source-optional).
	SourceFeature string
	SourceIdea    string
	// Parent, when non-empty, records the master plan this plan is a sub-plan of
	// (cli/plan/new#req:parent-ref-optional). It is emitted verbatim as a
	// `**Parent:** <value>` header line after `**Supersedes:**`; resolution is
	// deferred to lint (P-005). A same-repo slug or a cross-repo
	// `<repo-slug>:<plan-slug>` soft reference.
	Parent string
}

type Task struct {
	Number      int      // parsed N from `### Task N:`
	Name        string   // text after `Task N: `
	HeadingLine int      // 1-based line of the `### Task N:` heading
	BodyLines   []string // lines after the heading, up to the next task / H2 / EOF (verbatim)
	BodyStart   int      // 1-based line where the body begins (one past the heading)

	Verifies         []string // AC IDs from `**Verifies:**`, in source order
	VerifiesLine     int      // 1-based line of `**Verifies:**`; 0 when absent
	VerifiesPresent  bool     // true when the field was present
	Status           TaskStatus
	StatusLine       int    // 1-based line of `**Status:**`; 0 when absent
	StatusRaw        string // raw value as written
	StatusPresent    bool   // true when the field was present
	StatusValueValid bool   // true when StatusRaw parsed cleanly into TaskStatus
	DependsOn        []int  // predecessor task numbers, empty when none
	DependsOnLine    int    // 1-based line of `**Depends-On:**`; 0 when absent
	DependsOnRaw     string // raw value as written
	DependsOnPresent bool
	DependsOnValid   bool // true when raw value parsed cleanly (em-dash or list of ints)
	HasPlaceholder   bool // true when the body contains the placeholder token on its own line
	PlaceholderLine  int  // 1-based line of the placeholder; 0 when absent
}

type TaskStatus string