internal/core/spec
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 stringtype 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 stringtype Size
Source: internal/core/spec/model.go:50
Size estimates implementation effort.
type Size stringtype Status
Source: internal/core/spec/model.go:14
Status names a task's lifecycle state in the normalized spec model.
type Status stringtype 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"`
