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 EvidenceEntry struct {
	Task int    `yaml:"task" json:"task"`                 // task number carrying the ref
	Id   string `yaml:"id,omitempty" json:"id,omitempty"` // task **Id:** when present
	Ref  string `yaml:"ref" json:"ref"`                   // the `**Implemented-by:**` value
}

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
	Coordination      string   // value of `**Coordination:**` (empty when missing) — <owner>/<repo>@<branch> mutation-authority reference
	CoordinationLine  int      // 1-based line of the field; 0 when absent
	PrerequisitePlans []string // same-repo predecessor plan slugs from `**Prerequisite Plans:**`
	PrerequisiteLine  int      // 1-based line of the field; 0 when absent
	PrerequisiteRaw   string   // raw field value, retained so lint can distinguish malformed input
	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 ReconcileOptions 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; the optional directory form
	// (.../spec/plans/<slug>/README.md) is NOT supported — embedded-task
	// reconciliation requires the single-file parser (pkg/plan.Parse).
	SpecRoot string

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

	// Note is the mandatory justification for the reconciliation: what was
	// actually delivered, and why the tracked change-status flow was
	// skipped. Required — Reconcile refuses (exit 2) when empty or
	// whitespace-only. Written verbatim into the `## Resolution` section
	// alongside the fixed reconciliation preamble.
	Note string

	// Evidence is an optional list of commit SHAs, PR URLs, or file paths
	// backing the claim that the work is actually done. When non-empty it is
	// recorded as a trailing "Evidence: ..." line in the same Resolution
	// paragraph as Note.
	Evidence []string

	// ForceTasks is the caller's explicit, per-task-number acknowledgement
	// that a task recorded as failed or aborted should be overridden to
	// complete anyway. --tasks=complete never silently force-completes a
	// failed/aborted task: a task in either terminal state whose number does
	// NOT appear here blocks the whole reconciliation (exit 4), naming the
	// offending task numbers and their current statuses. Tasks named here
	// that are NOT actually failed/aborted are harmless no-ops. Every task
	// number that IS overridden this way is recorded — by number and prior
	// status — in the `## Resolution` paragraph, never folded silently into
	// the aggregate "N task(s) marked complete" count.
	ForceTasks []int

	// ReopenTasks is an explicit list of falsely-completed embedded tasks to
	// correct to blocked. It is deliberately narrow: only complete tasks may
	// be reopened, and no unlisted task is touched. This is the inverse audit
	// path for an over-stated prior reconciliation, not a general bypass of
	// the task lifecycle.
	ReopenTasks []int

	// PostMutation is the post-rewrite hook (typically a spec-lint pass,
	// which also syncs the frontmatter `status:` mirror and the plans
	// index). Required; Reconcile returns exit 10 if nil.
	PostMutation PostMutationHook
}

type ReconcileResult struct {
	Slug string
	// From is the plan's **Status:** value before reconciliation.
	From lifecycle.Status
	// To is the derived execution-band status the plan is reconciled to.
	// Today this is always lifecycle.PlanImplemented — the only supported
	// --tasks value ("complete") forces every task to StatusComplete, and
	// DeriveExecutionBand's complete-rollup case always yields Implemented.
	To lifecycle.Status
	// TasksReconciled is the count of embedded tasks whose **Status:** line
	// was actually rewritten (tasks already at the target status are left
	// byte-untouched and do not count). This INCLUDES any tasks named in
	// Overrides — they are both counted here and itemized there.
	TasksReconciled int
	// Overrides lists every task whose failed/aborted status was overridden
	// via --force-tasks, by number and prior status. Empty when no task was
	// in a terminal failure state (the common case).
	Overrides []TaskOverride
	// Target is the status written to every reconciled task. Complete is the
	// normal all-task delivery reconciliation; Blocked is used only by the
	// explicit ReopenTasks correction path.
	Target TaskStatus
}

type Rollup struct {
	Total      int `yaml:"total" json:"total"`
	Complete   int `yaml:"complete" json:"complete"`
	InProgress int `yaml:"in_progress" json:"in_progress"`
	Planning   int `yaml:"planning" json:"planning"`
	Queued     int `yaml:"queued" json:"queued"`
	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
	Id               string   // stable task identifier from `**Id:**`; empty when absent
	IdLine           int      // 1-based line of `**Id:**`; 0 when absent
	IdPresent        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

	// Implementation-commit provenance, written by `task change-status` as an
	// `**Implemented-by:** <ref>` field adjacent to the task's **Status:**.
	ImplementationCommit string // raw value of `**Implemented-by:**`; empty when absent or empty
	ImplementedByLine    int    // 1-based line of `**Implemented-by:**`; 0 when absent
	ImplementedByPresent bool   // true when the field was present (even with an empty value)

	// Note is a free-text annotation written by `task change-status --note=`,
	// adjacent to the task's **Status:** (and any **Implemented-by:**). Distinct
	// from ImplementationCommit: Note carries qualitative context (e.g. "verified
	// live"), not a code reference.
	Note        string // raw value of `**Note:**`; empty when absent or empty
	NoteLine    int    // 1-based line of `**Note:**`; 0 when absent
	NotePresent bool   // true when the field was present (even with an empty value)

	// Evidence is a list of supporting references written by
	// `task change-status --evidence=`, adjacent to the task's **Status:**.
	// Unlike ImplementationCommit (a syntactically validated code reference —
	// P-008), Evidence is unstructured: commit SHAs, PR URLs, file paths,
	// deploy/monitoring links, or anything else backing the claim.
	Evidence        []string // parsed comma-separated refs from `**Evidence:**`, in source order
	EvidenceRaw     string   // raw value as written
	EvidenceLine    int      // 1-based line of `**Evidence:**`; 0 when absent
	EvidencePresent bool     // true when the field was present (even with an empty value)
}

type TaskOverride struct {
	Number int
	From   TaskStatus
}

type TaskStatus string