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"
	// HardenNeedsRevision means hardening identified draft contract work before approval.
	HardenNeedsRevision HardenStatus = "needs_revision"
	// HardenError means the hardening provider or recorded harden evidence could not be accepted.
	HardenError HardenStatus = "error"
)

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

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:56

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:77

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

Functions

func ValidHardenStatus(status HardenStatus) bool

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

ValidHardenStatus reports whether status is a supported hardening status.

func ValidStatus(status Status) bool

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

ValidStatus reports whether status is a supported lifecycle status.

func Validate(model Model) Validation

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

Validate checks model shape and executable acceptance semantics.

Types

type Acceptance

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

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:156

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:174

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:143

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:163

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 HardenCheck

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

HardenCheck records one evidence-backed audit pass from a hardening round.

type HardenCheck struct {
	Name       string `json:"name"`
	GroundedIn string `json:"grounded_in"`
	Result     string `json:"result"`
	Evidence   string `json:"evidence"`
}
Fields
  • Name string `json:"name"`
  • GroundedIn string `json:"grounded_in"`
  • Result string `json:"result"`
  • Evidence string `json:"evidence"`

type HardenIssue

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

HardenIssue records one approval blocker or non-blocking harden advisory.

type HardenIssue struct {
	ID                string `json:"id"`
	Kind              string `json:"kind"`
	Severity          string `json:"severity"`
	BlocksApproval    bool   `json:"blocks_approval"`
	Status            string `json:"status"`
	GroundedIn        string `json:"grounded_in"`
	Summary           string `json:"summary"`
	Evidence          string `json:"evidence"`
	Recommendation    string `json:"recommendation"`
	Question          string `json:"question,omitempty"`
	RecommendedAnswer string `json:"recommended_answer,omitempty"`
	IfUnanswered      string `json:"if_unanswered,omitempty"`
}
Fields
  • ID string `json:"id"`
  • Kind string `json:"kind"`
  • Severity string `json:"severity"`
  • BlocksApproval bool `json:"blocks_approval"`
  • Status string `json:"status"`
  • GroundedIn string `json:"grounded_in"`
  • Summary string `json:"summary"`
  • Evidence string `json:"evidence"`
  • Recommendation string `json:"recommendation"`
  • Question string `json:"question,omitempty"`
  • RecommendedAnswer string `json:"recommended_answer,omitempty"`
  • IfUnanswered string `json:"if_unanswered,omitempty"`

type HardenRound

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

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"`
	Verdict      string        `json:"verdict,omitempty"`
	Summary      string        `json:"summary,omitempty"`
	Provider     string        `json:"provider,omitempty"`
	Model        string        `json:"model,omitempty"`
	OutputFormat string        `json:"output_format,omitempty"`
	Checks       []HardenCheck `json:"checks"`
	Issues       []HardenIssue `json:"issues,omitempty"`
}
Fields
  • ID string `json:"id"`
  • Status string `json:"status"`
  • StartedAt string `json:"started_at"`
  • EndedAt string `json:"ended_at"`
  • Verdict string `json:"verdict,omitempty"`
  • Summary string `json:"summary,omitempty"`
  • Provider string `json:"provider,omitempty"`
  • Model string `json:"model,omitempty"`
  • OutputFormat string `json:"output_format,omitempty"`
  • Checks []HardenCheck `json:"checks"`
  • Issues []HardenIssue `json:"issues,omitempty"`

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:82

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:380

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

func WithStatus(status Status) Model

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

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

type Origin

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

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:122

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:249

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:114

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:189

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"`
	Provider       string                      `json:"provider,omitempty"`
	Model          string                      `json:"model,omitempty"`
	OutputFormat   string                      `json:"output_format,omitempty"`
	Normalizations []string                    `json:"normalizations,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"`
  • Provider string `json:"provider,omitempty"`
  • Model string `json:"model,omitempty"`
  • OutputFormat string `json:"output_format,omitempty"`
  • Normalizations []string `json:"normalizations,omitempty"`

type Risk

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

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:64

RiskLevel estimates implementation risk.

type RiskLevel string

type Size

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

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:255

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:260

func Unwrap() error

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