markdown

type AnchorMatch struct {
	Found     bool
	Ambiguous bool
	Line      int
	Col       int
}

type AnchorToken struct {
	Text string
	Line int
	Col  int
}

type BlockRange struct {
	StartLine int
	EndLine   int
}

type BuildStep struct {
	// Repo is the repository this step targets.
	Repo string `yaml:"repo"`

	// Description is a brief summary of what this step accomplishes.
	Description string `yaml:"description"`

	// Branch is the git branch name for this step (auto-generated if empty).
	Branch string `yaml:"branch,omitempty"`

	// PR is the pull request number once created.
	PR int `yaml:"pr,omitempty"`

	// StoryKey is the linked PM story key for this step (e.g. "PLAT-201"),
	// set when story sync is enabled so board analytics track build progress.
	StoryKey string `yaml:"story_key,omitempty"`

	// Status tracks the step's progress: pending, in-progress, complete, blocked.
	Status string `yaml:"status"`

	// BlockedReason explains why this step is blocked (when Status == "blocked").
	BlockedReason string `yaml:"blocked_reason,omitempty"`
}

type DecisionEntry struct {
	Number    int
	Question  string
	Options   string
	Decision  string
	Rationale string
	DecidedBy string
	Date      string
}

type ReviewApproval struct {
	Reviewer   string `yaml:"reviewer"`
	ApprovedAt string `yaml:"approved_at"`
}

type ReviewState struct {
	// RequestedAt is when the review was requested.
	RequestedAt string `yaml:"requested_at,omitempty"`

	// Reviewers is the list of users/roles who should review.
	Reviewers []string `yaml:"reviewers,omitempty"`

	// Approvals records who has approved and when.
	Approvals []ReviewApproval `yaml:"approvals,omitempty"`

	// Status is the overall review state: pending, approved, changes_requested.
	Status string `yaml:"status"`

	// Feedback contains reviewer feedback when changes are requested.
	Feedback string `yaml:"feedback,omitempty"`
}

type Section struct {
	Slug      string // e.g., "problem_statement"
	Heading   string // e.g., "## 1. Problem Statement"
	Level     int    // heading level (2 = ##, 3 = ###)
	Owner     string // from <!-- owner: role --> marker, or "auto"
	Content   string // raw markdown content (excluding heading line)
	StartLine int    // line number in the source file (1-indexed)
	EndLine   int    // line number (exclusive)
}

type SpecMeta struct {
	ID          string   `yaml:"id"`
	Title       string   `yaml:"title"`
	Status      string   `yaml:"status"`
	Version     string   `yaml:"version"`
	Author      string   `yaml:"author"`
	Cycle       string   `yaml:"cycle"`
	EpicKey     string   `yaml:"epic_key,omitempty"`
	Repos       []string `yaml:"repos,omitempty"`
	RevertCount int      `yaml:"revert_count"`
	Source      string   `yaml:"source,omitempty"`
	Created     string   `yaml:"created"`
	Updated     string   `yaml:"updated"`

	// StageEnteredAt records when the spec entered its current stage (RFC3339).
	// It drives the time-urgency gradient's dwell calculation and is stamped on
	// every stage transition (advance/revert/eject/resume). Unlike Updated it is
	// NOT reset by ordinary edits, so editing a spec does not reset its
	// staleness. Legacy specs without it fall back to Updated.
	StageEnteredAt string `yaml:"stage_entered_at,omitempty"`

	// Assignees are the people responsible for moving the spec at its current
	// stage. Drives personal dashboard scope (assignee-scoped stages). Empty
	// means the spec is unclaimed and surfaces to the whole owning role.
	Assignees []string `yaml:"assignees,omitempty"`

	// BlockedFrom records the stage a spec was in when it was ejected to
	// `blocked`, so the dashboard can role-scope the BLOCKED section and
	// `spec resume` can restore the stage without parsing the escape-hatch log.
	BlockedFrom string `yaml:"blocked_from,omitempty"`

	// Steps is the structured build plan.
	// Replaces unstructured §7.3 prose with authoritative step tracking.
	Steps []BuildStep `yaml:"steps,omitempty"`

	// Review tracks plan review state for the engineering stage.
	Review *ReviewState `yaml:"review,omitempty"`

	// FastTrack marks this as a fast-track bug fix (skips ceremony stages).
	FastTrack bool `yaml:"fast_track,omitempty"`
}

type TriageComment struct {
	Actor   string `yaml:"actor"`
	Message string `yaml:"message"`
	At      string `yaml:"at"` // RFC3339 timestamp
}

type TriageMeta struct {
	ID         string          `yaml:"id"`
	Title      string          `yaml:"title"`
	Status     string          `yaml:"status"`
	Priority   string          `yaml:"priority"`
	Severity   string          `yaml:"severity,omitempty"`    // "urgent" or "normal" (default normal)
	LinkedSpec string          `yaml:"linked_spec,omitempty"` // SPEC-NNN if manually linked
	Source     string          `yaml:"source,omitempty"`
	SourceRef  string          `yaml:"source_ref,omitempty"`
	ReportedBy string          `yaml:"reported_by,omitempty"`
	Created    string          `yaml:"created"`
	ResolvedAt string          `yaml:"resolved_at,omitempty"` // set when closed/archived
	Comments   []TriageComment `yaml:"comments,omitempty"`    // append-only history log
}