Internal

internal/core/spec

Package spec defines the normalized model for living Markdown task specs.

import "github.com/nilstate/scafld/v2/internal/core/spec"

Package spec defines the normalized model for living Markdown task specs.

Constants

Source: internal/core/spec/model.go:40

const (
	// HardenNotRun means no hardening round has been opened.
	HardenNotRun HardenStatus = "not_run"
	// HardenInProgress means a hardening round is waiting for answers.
	HardenInProgress HardenStatus = "in_progress"
	// HardenPassed means hardening completed successfully.
	HardenPassed HardenStatus = "passed"
	// HardenFailed means hardening identified unresolved blockers.
	HardenFailed HardenStatus = "failed"
)

Source: internal/core/spec/model.go:66

const (
	// RiskLow describes low implementation risk.
	RiskLow RiskLevel = "low"
	// RiskMedium describes medium implementation risk.
	RiskMedium RiskLevel = "medium"
	// RiskHigh describes high implementation risk.
	RiskHigh RiskLevel = "high"
)

Source: internal/core/spec/model.go:54

const (
	// SizeSmall describes a small task.
	SizeSmall Size = "small"
	// SizeMedium describes a medium task.
	SizeMedium Size = "medium"
	// SizeLarge describes a large task.
	SizeLarge Size = "large"
)

Source: internal/core/spec/model.go:18

const (
	// StatusDraft is the editable pre-approval state.
	StatusDraft Status = "draft"
	// StatusApproved is ready for execution.
	StatusApproved Status = "approved"
	// StatusActive is actively executing acceptance criteria.
	StatusActive Status = "active"
	// StatusBlocked means execution or review found blocking work.
	StatusBlocked Status = "blocked"
	// StatusReview is waiting on or inside the review gate.
	StatusReview Status = "review"
	// StatusCompleted is the terminal successful state.
	StatusCompleted Status = "completed"
	// StatusFailed is the terminal unsuccessful state.
	StatusFailed Status = "failed"
	// StatusCancelled is the terminal abandoned state.
	StatusCancelled Status = "cancelled"
)

Variables

Source: internal/core/spec/model.go:75

var (
	// ErrInvalidSpec wraps normalized spec validation failures.
	ErrInvalidSpec = errors.New("invalid spec")
)

Functions

func ValidHardenStatus(status HardenStatus) bool

Source: internal/core/spec/model.go:337

ValidHardenStatus reports whether status is a supported hardening status.

func ValidStatus(status Status) bool

Source: internal/core/spec/model.go:327

ValidStatus reports whether status is a supported lifecycle status.

func Validate(model Model) Validation

Source: internal/core/spec/model.go:245

Validate checks model shape and executable acceptance semantics.

Types

type Acceptance

Source: internal/core/spec/model.go:134

Acceptance groups global definition-of-done and criterion checks.

type Acceptance struct {
	ValidationProfile string          `json:"validation_profile"`
	DefinitionDone    []ChecklistItem `json:"definition_done"`
	Criteria          []Criterion     `json:"criteria"`
}
Fields
  • ValidationProfile string `json:"validation_profile"`
  • DefinitionDone []ChecklistItem `json:"definition_done"`
  • Criteria []Criterion `json:"criteria"`

type ChecklistItem

Source: internal/core/spec/model.go:154

ChecklistItem is one human-readable checklist row.

type ChecklistItem struct {
	ID      string `json:"id"`
	Text    string `json:"text"`
	Checked bool   `json:"checked"`
}
Fields
  • ID string `json:"id"`
  • Text string `json:"text"`
  • Checked bool `json:"checked"`

type Context

Source: internal/core/spec/model.go:172

Context captures workspace and codebase surfaces relevant to the task.

type Context struct {
	CWD           string   `json:"cwd"`
	Packages      []string `json:"packages"`
	FilesImpacted []string `json:"files_impacted"`
	Invariants    []string `json:"invariants"`
	RelatedDocs   []string `json:"related_docs"`
}
Fields
  • CWD string `json:"cwd"`
  • Packages []string `json:"packages"`
  • FilesImpacted []string `json:"files_impacted"`
  • Invariants []string `json:"invariants"`
  • RelatedDocs []string `json:"related_docs"`

type Criterion

Source: internal/core/spec/model.go:141

Criterion is a machine-checkable acceptance item.

type Criterion struct {
	ID           string                  `json:"id"`
	Title        string                  `json:"title"`
	Type         string                  `json:"type"`
	PhaseID      string                  `json:"phase_id"`
	Command      string                  `json:"command"`
	ExpectedKind acceptance.ExpectedKind `json:"expected_kind"`
	Status       string                  `json:"status"`
	Evidence     string                  `json:"evidence"`
	SourceEvent  string                  `json:"source_event"`
}
Fields
  • ID string `json:"id"`
  • Title string `json:"title"`
  • Type string `json:"type"`
  • PhaseID string `json:"phase_id"`
  • Command string `json:"command"`
  • ExpectedKind acceptance.ExpectedKind `json:"expected_kind"`
  • Status string `json:"status"`
  • Evidence string `json:"evidence"`
  • SourceEvent string `json:"source_event"`

type CurrentState

Source: internal/core/spec/model.go:161

CurrentState is the readable projection of the next task action.

type CurrentState struct {
	CurrentPhase       string `json:"current_phase"`
	Next               string `json:"next"`
	Reason             string `json:"reason"`
	Blockers           string `json:"blockers"`
	AllowedFollowUp    string `json:"allowed_follow_up"`
	LatestRunnerUpdate string `json:"latest_runner_update"`
	ReviewGate         string `json:"review_gate"`
}
Fields
  • CurrentPhase string `json:"current_phase"`
  • Next string `json:"next"`
  • Reason string `json:"reason"`
  • Blockers string `json:"blockers"`
  • AllowedFollowUp string `json:"allowed_follow_up"`
  • LatestRunnerUpdate string `json:"latest_runner_update"`
  • ReviewGate string `json:"review_gate"`

type HardenQuestion

Source: internal/core/spec/model.go:213

HardenQuestion is one grounded question from a hardening round.

type HardenQuestion struct {
	Question          string `json:"question"`
	GroundedIn        string `json:"grounded_in"`
	RecommendedAnswer string `json:"recommended_answer"`
	IfUnanswered      string `json:"if_unanswered"`
	AnsweredWith      string `json:"answered_with"`
}
Fields
  • Question string `json:"question"`
  • GroundedIn string `json:"grounded_in"`
  • RecommendedAnswer string `json:"recommended_answer"`
  • IfUnanswered string `json:"if_unanswered"`
  • AnsweredWith string `json:"answered_with"`

type HardenRound

Source: internal/core/spec/model.go:204

HardenRound records one pre-approval hardening pass.

type HardenRound struct {
	ID        string           `json:"id"`
	Status    string           `json:"status"`
	StartedAt string           `json:"started_at"`
	EndedAt   string           `json:"ended_at"`
	Questions []HardenQuestion `json:"questions"`
}
Fields
  • ID string `json:"id"`
  • Status string `json:"status"`
  • StartedAt string `json:"started_at"`
  • EndedAt string `json:"ended_at"`
  • Questions []HardenQuestion `json:"questions"`

type HardenStatus

Source: internal/core/spec/model.go:36

HardenStatus names the state of the pre-approval hardening pass.

type HardenStatus string

type Model

Source: internal/core/spec/model.go:80

Model is the normalized in-memory representation of a living Markdown spec.

type Model struct {
	Version      string            `json:"spec_version"`
	TaskID       string            `json:"task_id"`
	Created      string            `json:"created"`
	Updated      string            `json:"updated"`
	Title        string            `json:"title"`
	Summary      string            `json:"summary"`
	Status       Status            `json:"status"`
	HardenStatus HardenStatus      `json:"harden_status"`
	Size         Size              `json:"size"`
	RiskLevel    RiskLevel         `json:"risk_level"`
	CurrentState CurrentState      `json:"current_state"`
	Context      Context           `json:"context"`
	Objectives   []string          `json:"objectives"`
	Scope        []string          `json:"scope"`
	Dependencies []string          `json:"dependencies"`
	Assumptions  []string          `json:"assumptions"`
	Touchpoints  []string          `json:"touchpoints"`
	Risks        []Risk            `json:"risks"`
	Acceptance   Acceptance        `json:"acceptance"`
	Phases       []Phase           `json:"phases"`
	Rollback     []string          `json:"rollback"`
	Review       ReviewState       `json:"review"`
	SelfEval     []string          `json:"self_eval"`
	Deviations   []string          `json:"deviations"`
	Metadata     map[string]string `json:"metadata"`
	Origin       Origin            `json:"origin"`
	HardenRounds []HardenRound     `json:"harden_rounds"`
	PlanningLog  []PlanningEvent   `json:"planning_log"`
}
Fields
  • Version string `json:"spec_version"`
  • TaskID string `json:"task_id"`
  • Created string `json:"created"`
  • Updated string `json:"updated"`
  • Title string `json:"title"`
  • Summary string `json:"summary"`
  • Status Status `json:"status"`
  • HardenStatus HardenStatus `json:"harden_status"`
  • Size Size `json:"size"`
  • RiskLevel RiskLevel `json:"risk_level"`
  • CurrentState CurrentState `json:"current_state"`
  • Context Context `json:"context"`
  • Objectives []string `json:"objectives"`
  • Scope []string `json:"scope"`
  • Dependencies []string `json:"dependencies"`
  • Assumptions []string `json:"assumptions"`
  • Touchpoints []string `json:"touchpoints"`
  • Risks []Risk `json:"risks"`
  • Acceptance Acceptance `json:"acceptance"`
  • Phases []Phase `json:"phases"`
  • Rollback []string `json:"rollback"`
  • Review ReviewState `json:"review"`
  • SelfEval []string `json:"self_eval"`
  • Deviations []string `json:"deviations"`
  • Metadata map[string]string `json:"metadata"`
  • Origin Origin `json:"origin"`
  • HardenRounds []HardenRound `json:"harden_rounds"`
  • PlanningLog []PlanningEvent `json:"planning_log"`

func AllCriteria() []Criterion

Source: internal/core/spec/model.go:347

AllCriteria returns global and phase acceptance criteria with phase IDs filled.

func WithStatus(status Status) Model

Source: internal/core/spec/model.go:361

WithStatus returns a copy of the model with status and next state updated.

type Origin

Source: internal/core/spec/model.go:198

Origin records where the spec came from.

type Origin struct {
	CreatedBy string `json:"created_by"`
	Source    string `json:"source"`
}
Fields
  • CreatedBy string `json:"created_by"`
  • Source string `json:"source"`

type Phase

Source: internal/core/spec/model.go:120

Phase describes a numbered execution phase and its evidence-derived state.

type Phase struct {
	ID             string          `json:"id"`
	Number         int             `json:"number"`
	Name           string          `json:"name"`
	Status         string          `json:"status"`
	Reason         string          `json:"reason"`
	Dependencies   []string        `json:"dependencies"`
	Objective      string          `json:"objective"`
	Changes        []string        `json:"changes"`
	Acceptance     []Criterion     `json:"acceptance"`
	DefinitionDone []ChecklistItem `json:"definition_done"`
}
Fields
  • ID string `json:"id"`
  • Number int `json:"number"`
  • Name string `json:"name"`
  • Status string `json:"status"`
  • Reason string `json:"reason"`
  • Dependencies []string `json:"dependencies"`
  • Objective string `json:"objective"`
  • Changes []string `json:"changes"`
  • Acceptance []Criterion `json:"acceptance"`
  • DefinitionDone []ChecklistItem `json:"definition_done"`

type PlanningEvent

Source: internal/core/spec/model.go:222

PlanningEvent records a timestamped planning log entry.

type PlanningEvent struct {
	Time string `json:"time"`
	Text string `json:"text"`
}
Fields
  • Time string `json:"time"`
  • Text string `json:"text"`

type Record

Source: internal/core/spec/model.go:112

Record is a compact listing entry for a task spec.

type Record struct {
	TaskID string `json:"task_id"`
	Status Status `json:"status"`
	Path   string `json:"path"`
	Title  string `json:"title"`
}
Fields
  • TaskID string `json:"task_id"`
  • Status Status `json:"status"`
  • Path string `json:"path"`
  • Title string `json:"title"`

type ReviewState

Source: internal/core/spec/model.go:187

ReviewState stores the latest review gate projection.

type ReviewState struct {
	Status    string                      `json:"status"`
	Verdict   string                      `json:"verdict"`
	Mode      corereview.Mode             `json:"mode,omitempty"`
	Summary   string                      `json:"summary,omitempty"`
	Findings  []corereview.Finding        `json:"findings,omitempty"`
	AttackLog []corereview.AttackLogEntry `json:"attack_log,omitempty"`
	Budget    corereview.Budget           `json:"budget,omitempty"`
}
Fields
  • Status string `json:"status"`
  • Verdict string `json:"verdict"`
  • Mode corereview.Mode `json:"mode,omitempty"`
  • Summary string `json:"summary,omitempty"`
  • Findings []corereview.Finding `json:"findings,omitempty"`
  • AttackLog []corereview.AttackLogEntry `json:"attack_log,omitempty"`
  • Budget corereview.Budget `json:"budget,omitempty"`

type Risk

Source: internal/core/spec/model.go:181

Risk captures one known risk and its mitigation.

type Risk struct {
	Description string `json:"description"`
	Mitigation  string `json:"mitigation"`
}
Fields
  • Description string `json:"description"`
  • Mitigation string `json:"mitigation"`

type RiskLevel

Source: internal/core/spec/model.go:62

RiskLevel estimates implementation risk.

type RiskLevel string

type Size

Source: internal/core/spec/model.go:50

Size estimates implementation effort.

type Size string

type Status

Source: internal/core/spec/model.go:14

Status names a task's lifecycle state in the normalized spec model.

type Status string

type Validation

Source: internal/core/spec/model.go:228

Validation reports whether a spec model satisfies runtime requirements.

type Validation struct {
	Valid  bool     `json:"valid"`
	Errors []string `json:"errors"`
}
Fields
  • Valid bool `json:"valid"`
  • Errors []string `json:"errors"`

func Error() string

Source: internal/core/spec/model.go:233

func Unwrap() error

Source: internal/core/spec/model.go:240