issue

type ChangeStatusOptions struct {
	// SpecRoot is the project root that contains the `spec/` subtree
	// (NOT the `spec/` directory itself).
	SpecRoot string

	// Slug is the Issue slug.
	Slug string

	// To is the target status (lowercase): investigating, resolved, rejected.
	To string

	// Severity is an optional severity override. Required when transitioning
	// and current severity is absent.
	Severity string

	// Reason is required when To=rejected.
	Reason string

	// Notes is optional when To=rejected.
	Notes string

	// PostMutation is the post-rewrite hook (typically a spec-lint pass).
	PostMutation PostMutationHook
}

type ChangeStatusResult struct {
	Slug string
	Path string
	From string
	To   string
}

type Discovered struct {
	// Path is the absolute path to the file.
	Path string
	// RelPath is the path relative to the spec root, with forward slashes.
	RelPath string
	// Slug is the basename minus `.md`.
	Slug string
	// MatchesPattern is true when RelPath matches one of the two
	// canonical PathPatterns. Files declaring `type: issue` outside
	// the patterns have MatchesPattern == false (I-009 candidates).
	MatchesPattern bool
	// FeatureSlug, when non-empty, is the parent Feature slug for a
	// Feature-scoped issue (RelPath of the form
	// `features/<feature-slug>/issues/<slug>.md`). Empty for root-level
	// issues or off-pattern issues.
	FeatureSlug string
}

type Issue struct {
	// Path is the absolute (or otherwise caller-supplied) path to the file.
	Path string
	// Slug is the basename minus `.md`.
	Slug string
	// Type is the frontmatter `type` value (empty when missing or
	// unparseable). Only files where Type == TypeValue are considered
	// issue artifacts.
	Type string
	// Frontmatter holds the top-level YAML mapping keys (values
	// stringified). nil when no frontmatter could be parsed.
	Frontmatter map[string]string
	// FrontmatterKeyOrder preserves the order keys appeared in the
	// source YAML.
	FrontmatterKeyOrder []string
	// Body is the markdown body after the closing `---`.
	Body string
	// HasFrontmatter is true when the file begins with `---` and a
	// closing `---` line is found.
	HasFrontmatter bool
	// BugsRaw is the raw YAML node for the `bugs` frontmatter field, or
	// nil when the field is absent. Exposed so list-aware rules (I-004)
	// can inspect the node's Kind and elements without re-parsing.
	BugsRaw *yaml.Node
}

type PostMutationHook func() error

type ScaffoldOptions struct {
	Slug              string
	Title             string // defaults to title-cased slug
	CapturedBy        string // defaults to $USER
	CapturedAt        string // RFC 3339 timestamp, defaults to now UTC
	Severity          string // optional: low|medium|high|critical
	AffectedComponent string // optional: Feature slug
	FirstSeen         string // optional
	GithubIssue       string // optional
}