plancontract

type Acceptance struct {
	ID    string `json:"id"`
	Scope string `json:"scope"`
	// Check is the concrete check (command, route, or steps reference). It is
	// optional for KindManual, which is reported rather than run.
	Check string `json:"check,omitempty"`
	Kind  Kind   `json:"kind"`
	// Steps are the scripted browser steps for KindInteraction items
	// in execution order. They are empty for every other
	// kind; the validator enforces both rules (required non-empty for
	// interaction, forbidden otherwise).
	Steps []BrowseStep `json:"steps,omitempty"`
}

type BrowseStep struct {
	// Action is the step verb (e.g. "click", "fill", "assert_text"). It is
	// required and non-empty (mirroring parseBrowseSteps); the action set
	// itself is validated by the executor at runtime, not by the plan
	// validator.
	Action string `json:"action"`
	// Selector is the CSS selector the step targets, where applicable.
	Selector string `json:"selector,omitempty"`
	// Value is the value the step types or fills, where applicable.
	Value string `json:"value,omitempty"`
	// Key is the keyboard key for press-style steps, where applicable.
	Key string `json:"key,omitempty"`
	// Millis is a wait time in milliseconds for sleep-style steps, where
	// applicable.
	Millis int `json:"millis,omitempty"`
	// Script is a JavaScript snippet for eval-style steps, where applicable.
	Script string `json:"script,omitempty"`
	// Expect is the expected value or text for assert-style steps, where
	// applicable.
	Expect string `json:"expect,omitempty"`
	// ScreenshotPath is the file path for a screenshot_selector step's
	// cropped element screenshot, where applicable.
	ScreenshotPath string `json:"screenshot_path,omitempty"`
}

type Kind string

type OutOfScope struct {
	Item   string `json:"item"`
	Reason string `json:"reason"`
}

type Plan struct {
	// Version is the schema version of this document.
	Version int `json:"version"`
	// Revision increments on every edit to the plan; the store
	// bumps it on each write. A persisted plan is always >= 1.
	Revision int `json:"revision"`
	// Created and Updated are the plan's lifecycle timestamps (RFC3339 in
	// JSON).
	Created time.Time `json:"created"`
	Updated time.Time `json:"updated"`

	// Goal is what the work is for, in one or two sentences.
	Goal string `json:"goal"`

	// Scope is the set of features or changes the plan covers.
	Scope []ScopeItem `json:"scope"`
	// Steps are the ordered implementation steps; each references a scope item.
	Steps []Step `json:"steps"`
	// Design is an optional reference to screens or files under design/
	// (SP-140 directory contract).
	Design string `json:"design,omitempty"`
	// Starter is an optional starter ID when the project uses one.
	Starter string `json:"starter,omitempty"`

	// Acceptance are the machine- or human-checkable criteria. Every scope
	// item must be covered by at least one acceptance item.
	Acceptance []Acceptance `json:"acceptance"`
	// OutOfScope are items discussed and deliberately excluded, with the
	// reason, so scope does not creep silently between sessions.
	OutOfScope []OutOfScope `json:"out_of_scope"`
}

type ScopeItem struct {
	ID          string `json:"id"`
	Title       string `json:"title"`
	Description string `json:"description,omitempty"`
}

type Step struct {
	// Scope is the id of the scope item this step implements.
	Scope string `json:"scope"`
	// Description says what the step does.
	Description string `json:"description"`
}

type ValidationError struct {
	Problems []string
}