lifecycle

package
v0.35.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Aug 14, 2026 License: Apache-2.0 Imports: 11 Imported by: 0

Documentation

Overview

Package lifecycle hosts a kind-parameterized state machine for SpecScore artifact Status transitions. It is the shared implementation layer that the per-kind `change-status` CLI verbs consume.

The package is deliberately kind-agnostic: Idea, Feature, and any future doc kind plug their own legal-transition matrix into the package's lookup tables. Verb-specific logic (archive relocation, feature-id resolution, cobra wiring, exit-code mapping) lives in the calling CLI verbs, not here.

Architectural contract implemented by this package (see spec/features/cli/lifecycle-transitions/README.md):

  • REQ: state-machine-strictness — Transition rejects any (from, to) pair not declared in the kind's matrix.
  • REQ: not-idempotent — the matrix MUST NOT contain a self-loop (from == to). The package's init step panics if a self-loop is declared, so corruption is caught at startup rather than runtime.
  • REQ: status-line-rewrite — Rewrite mutates only the **Status:** line, preserving every other byte (including line endings and trailing whitespace).
  • Existing-artifact writers use one fail-fast per-path transaction, read and validate under lock, and atomically replace only expected bytes.
  • Rollback remains an explicit legacy operation for callers whose broader contract still requires it; transaction users do not perform a late stale rollback after post-commit work fails.

Index

Constants

This section is empty.

Variables

View Source 
var ErrConcurrentMutation = errors.New("lifecycle: artifact changed before amendment write")

ErrConcurrentMutation means the artifact changed after its caller read the exact bytes it intended to amend. Callers must re-read and make a fresh, explicit decision rather than overwrite the other writer's record.

View Source 
var ErrInvalidTransition = errors.New("invalid lifecycle transition")

ErrInvalidTransition is returned by Transition (and Validate) when the requested (from, to) pair is not present in the kind's matrix.

The error carries the kind, source status, target status, and the legal target set from the current source, so the CLI layer can render a user-friendly message without re-querying the matrix.

View Source 
var ErrStatusLineNotFound = errors.New("lifecycle: artifact has no **Status:** line")

ErrStatusLineNotFound is returned by Validate/Rewrite when the artifact does not contain a recognizable `**Status:**` line.

Functions

func AppendResolutionNote added in v0.11.0 

func AppendResolutionNote(artifactPath, note string) (original []byte, wrote bool, err error)

AppendResolutionNote writes the supplied markdown into the artifact body as a `## Resolution` section, implementing lifecycle-transitions#REQ:optional-transition-note.

Semantics:

  • An empty or whitespace-only note is treated as absent: the file is left untouched, wrote is false, and original is nil.
  • If a `## Resolution` H2 section already exists, the note is appended as a new trailing paragraph within it (the section is never relocated).
  • If absent, the section is created immediately before the artifact footer line (`*This document follows the …*`) when one is present, else at EOF.

The markdown is written verbatim except for trailing-newline normalization; it is never reflowed, wrapped, truncated, or sanitized.

This wrapper is retained for historical compensating callers. On a write, original holds its exact pre-invocation bytes, but that snapshot is not post-commit rollback authority. Transaction-profile Task/Plan writers call AppendResolutionNoteBytes inside their single artifact transaction.

func AppendResolutionNoteBytes added in v0.35.0 

func AppendResolutionNoteBytes(orig []byte, note string) ([]byte, bool, error)

AppendResolutionNoteBytes appends a resolution paragraph in memory.

func CommittedError added in v0.35.0 

func CommittedError(path, phase string, err error) error

CommittedError constructs a typed recovery-required error for work that failed only after an artifact transaction became visible.

func GuardReason added in v0.11.0 

func GuardReason(set ReasonRequiredSet, from, to Status, note string) error

GuardReason is the pre-mutation guard for reason-required transitions. If (from, to) is designated reason-required in set and note is empty or whitespace-only, it returns a *ReasonRequiredError naming the transition. Otherwise it returns nil.

Callers MUST invoke GuardReason BEFORE any artifact mutation, so a designated transition with a missing reason fails without touching the file (REQ: reason-required-transitions). Non-designated transitions and an empty set always return nil here, leaving `--note` optional.

func IsPlanDisposition added in v0.32.1 

func IsPlanDisposition(s Status) bool

IsPlanDisposition reports whether a Plan status is one of the four terminal dispositions — the states a Plan is retired INTO, and from which no work resumes.

Implemented is deliberately absent: it is the successful end of execution and still the live account of what was built, so a caller that treats a retired Plan as frozen history must not treat Implemented that way. Both `plan reconcile` (which refuses to resurrect a disposition) and the P-001/P-002 lint rules (which stop validating a retired Plan against a Feature that has since moved on) need exactly this set, so it is declared once here instead of being spelled out at each call site.

func RestoreBody added in v0.11.0 

func RestoreBody(artifactPath string, original []byte) error

RestoreBody is the explicit legacy whole-body compensating writer. It is not part of the Task/Plan transaction profile and MUST NOT be used after their artifact commit or post-mutation callback failure.

func Rewrite 

func Rewrite(artifactPath string, newStatus Status) (string, error)

Rewrite mutates the artifact's `**Status:**` line in place, replacing only the value text. Every other byte of the file (line ordering, indentation, line endings, trailing whitespace) is preserved (REQ: status-line-rewrite).

Rewrite is retained for historical single-field callers. The returned string is the original line content for their explicitly documented legacy compensation path. Transaction-profile Task/Plan writers use RewriteBytes inside one TransformArtifact callback and never perform a late rollback.

If the file has no `**Status:**` line, Rewrite returns ErrStatusLineNotFound and the file is left untouched.

func RewriteBytes added in v0.35.0 

func RewriteBytes(original []byte, newStatus Status) ([]byte, string, error)

RewriteBytes rewrites Status (and its frontmatter mirror) in memory. It is the pure transform used by compound artifact transactions.

func Rollback 

func Rollback(artifactPath string, originalStatusLine string) error

Rollback is the explicit legacy compensating status-line writer. It is not part of the Task/Plan transaction profile and MUST NOT be used after their artifact commit or post-mutation callback failure.

Rollback locates the file's current `**Status:**` line (which is now the MUTATED value), replaces that single line with originalStatusLine, and writes the file back. After Rollback returns nil, the file content is byte-identical to its pre-Rewrite state.

If the file has been mutated externally between Rewrite and Rollback such that no `**Status:**` line remains, Rollback returns ErrStatusLineNotFound. It does not prove ownership of unrelated current bytes; callers that have migrated to ArtifactTransaction must retain committed state instead.

func RollbackBytes added in v0.35.0 

func RollbackBytes(current []byte, originalStatusLine string) ([]byte, error)

RollbackBytes is the pure in-memory legacy status-line restoration transform.

func SetSupersededBy added in v0.13.0 

func SetSupersededBy(artifactPath, successor string) (original []byte, wrote bool, err error)

SetSupersededBy writes a `**Superseded By:** <successor>` reference into the artifact's header block, mirroring the Decision "Superseded By" convention. It is retained as a legacy single-field wrapper. Transaction-profile Task/Plan writers call SetSupersededByBytes inside their one artifact transaction and do not stitch this wrapper into a multi-write sequence.

Semantics:

  • An empty or whitespace-only successor is treated as absent: the file is left untouched, wrote is false, and original is nil.
  • If a `**Superseded By:**` line already exists, its value is rewritten in place (indentation and trailing whitespace preserved).
  • Otherwise the line is inserted immediately after the `**Supersedes:**` header line when present, else immediately after the `**Status:**` line. A file with neither anchor returns ErrStatusLineNotFound and is left untouched.

On a write, original holds the exact pre-invocation bytes for historical compensating callers only; it is not a post-commit rollback authority.

func SetSupersededByBytes added in v0.35.0 

func SetSupersededByBytes(orig []byte, successor string) ([]byte, bool, error)

SetSupersededByBytes applies the successor header transform in memory.

func SetSupersedes added in v0.32.0 

func SetSupersedes(artifactPath, target string) (original []byte, wrote bool, err error)

SetSupersedes writes a `**Supersedes:** <target>` reference into the artifact's header block — the other half of the bidirectional link completed by SetSupersededBy on the target artifact. It is the Decision-kind counterpart: `decision change-status --to=superseded` calls SetSupersededBy on the OLD decision and SetSupersedes on the NEW (successor) decision in the same atomic transition, per D-supersedes-bidirectional.

Semantics mirror SetSupersededBy exactly:

  • An empty or whitespace-only target is treated as absent: the file is left untouched, wrote is false, and original is nil.
  • If a `**Supersedes:**` line already exists, its value is rewritten in place (indentation and trailing whitespace preserved). This is the common case for a Decision, whose scaffold always emits the field (defaulted to `—`).
  • Otherwise the line is inserted immediately after the `**Status:**` header line. A file with no `**Status:**` line returns ErrStatusLineNotFound and is left untouched.

On a write, original holds the exact pre-invocation file bytes so the caller can roll back via RestoreBody as part of the surrounding atomic transition.

func SetSupersedesBytes added in v0.35.0 

func SetSupersedesBytes(original []byte, target string) ([]byte, bool, error)

SetSupersedesBytes applies the predecessor header transform in memory.

func TransformArtifact added in v0.35.0 

func TransformArtifact(path string, transform func(before []byte) (after []byte, err error)) error

TransformArtifact runs one complete existing-artifact transaction: acquire the per-artifact lifecycle fence, read the exact current bytes, resolve and validate against those bytes in transform, then atomically replace them when transform returns changed bytes. Transform must be pure: it must not call a public lifecycle writer (which would acquire the same non-reentrant lock).

func Transition 

func Transition(kind Kind, from Status, to Status) error

Transition validates that (from, to) is a legal transition in kind's matrix. It returns nil on success and a wrapped ErrInvalidTransition on failure. The wrapped error carries the legal target set from the current source so callers can render a useful message.

Transition does NOT touch the filesystem; it is pure matrix lookup.

func WithArtifactTransaction added in v0.35.0 

func WithArtifactTransaction(path string, fn func(*ArtifactTransaction) error) error

WithArtifactTransaction locks path, reads its exact bytes, and invokes fn. It never waits: contention is immediately ErrConcurrentMutation. The callback may perform pre-publication work for a classified new-artifact publisher, then commit the board/index bytes through tx.Commit; ordinary writers should use TransformArtifact's pure callback.

Types

type ArtifactTransaction added in v0.35.0 

type ArtifactTransaction struct {
	// contains filtered or unexported fields
}

ArtifactTransaction is the one existing-artifact mutation boundary. Before is read only after the path lock is acquired. Commit may be called at most once and performs the final expected-byte check, atomic replacement, and directory durability fence without reacquiring the lock.

func (*ArtifactTransaction) Before added in v0.35.0 

func (t *ArtifactTransaction) Before() []byte

func (*ArtifactTransaction) Commit added in v0.35.0 

func (t *ArtifactTransaction) Commit(after []byte) error

type CommittedMutationError added in v0.35.0 

type CommittedMutationError struct {
	Path  string
	Phase string
	Err   error
}

CommittedMutationError reports that the canonical artifact bytes are already visible and must be retained even though later durable-fence or derived work failed. Callers must surface recovery-required state; they must never roll the artifact back from a stale snapshot.

func (*CommittedMutationError) Error added in v0.35.0 

func (e *CommittedMutationError) Error() string

func (*CommittedMutationError) Unwrap added in v0.35.0 

func (e *CommittedMutationError) Unwrap() error

type InvalidTransitionError 

type InvalidTransitionError struct {
	Kind         Kind
	From         Status
	To           Status
	LegalTargets []Status
}

InvalidTransitionError is a typed error carrying the context of a rejected transition. It wraps ErrInvalidTransition, so callers can use errors.Is to detect this category.

func (*InvalidTransitionError) Error 

func (e *InvalidTransitionError) Error() string

Error implements the error interface. The message is human-readable and names both endpoints plus the legal target set from the current source.

func (*InvalidTransitionError) Unwrap 

func (e *InvalidTransitionError) Unwrap() error

Unwrap exposes ErrInvalidTransition so errors.Is(err, ErrInvalidTransition) returns true.

type Kind 

type Kind string

Kind names a doc kind that participates in the lifecycle state machine. 

const (
	KindIdea     Kind = "idea"
	KindFeature  Kind = "feature"
	KindPlan     Kind = "plan"
	KindTask     Kind = "task"
	KindLesson   Kind = "lesson"
	KindDecision Kind = "decision"
)

type ReasonRequiredError added in v0.11.0 

type ReasonRequiredError struct {
	From Status
	To   Status
}

ReasonRequiredError is returned by GuardReason when a designated reason-required transition is attempted without a non-empty note. It carries the (from, to) transition so the consuming verb can render a message and map it to exit code 2 (InvalidArgs).

func (*ReasonRequiredError) Error added in v0.11.0 

func (e *ReasonRequiredError) Error() string

Error implements the error interface. The message names the transition and states that a reason is required, satisfying the contract's stderr message requirement.

type ReasonRequiredSet added in v0.11.0 

type ReasonRequiredSet struct {
	// contains filtered or unexported fields
}

ReasonRequiredSet is the set of transitions a verb designates as reason-required. The zero value is a valid empty set (designates nothing).

func NewReasonRequiredSet added in v0.11.0 

func NewReasonRequiredSet(transitions ...ReasonRequiredTransition) ReasonRequiredSet

NewReasonRequiredSet builds a ReasonRequiredSet from the given transitions. Passing no transitions yields an empty set, equivalent to the zero value.

func (ReasonRequiredSet) RequiresReason added in v0.11.0 

func (s ReasonRequiredSet) RequiresReason(from, to Status) bool

RequiresReason reports whether the (from, to) transition is designated reason-required in this set.

type ReasonRequiredTransition added in v0.11.0 

type ReasonRequiredTransition struct {
	From Status
	To   Status
}

ReasonRequiredTransition names a single (from, to) arc a verb designates as reason-required.

type Status 

type Status string

Status is a domain-scoped status value. The set of legal Status values is per-Kind and validated by the kind's transition table; callers SHOULD use ParseStatus to obtain a canonical Status from a raw flag string. 

const (
	IdeaDraft        Status = "Draft"
	IdeaInReview     Status = "In Review"
	IdeaApproved     Status = "Approved"
	IdeaSpecifying   Status = "Specifying"
	IdeaSpecified    Status = "Specified"
	IdeaImplementing Status = "Implementing"
	IdeaImplemented  Status = "Implemented"
	IdeaRejected     Status = "Rejected"
	IdeaStale        Status = "Stale"
)

Idea statuses. 

const (
	FeatureDraft        Status = "Draft"
	FeatureInReview     Status = "In Review"
	FeatureApproved     Status = "Approved"
	FeatureImplementing Status = "Implementing"
	FeatureStable       Status = "Stable"
	FeatureAmending     Status = "Amending"
	FeatureRejected     Status = "Rejected"
	FeatureDeprecated   Status = "Deprecated"
)

Feature statuses. 

const (
	PlanDraft       Status = "Draft"
	PlanInReview    Status = "In Review"
	PlanApproved    Status = "Approved"
	PlanExecuting   Status = "Executing"
	PlanBlocked     Status = "Blocked"
	PlanImplemented Status = "Implemented"
	PlanFailed      Status = "Failed"
	PlanRejected    Status = "Rejected"
	PlanWithdrawn   Status = "Withdrawn"
	PlanSuperseded  Status = "Superseded"
	PlanDeprecated  Status = "Deprecated"
)

Plan statuses. The status models a plan's full lifecycle in three bands (prep / execution / disposition); see spec/features/plan/README.md. Only the prep band and the dispositions are human-authored — `plan change-status` owns those arcs. The execution band (Executing/Blocked/Implemented/Failed) is LINT-DERIVED from the task-status rollup (rule P-007) and MUST NOT be settable via change-status; those values appear in this matrix only as From-states for dispositions. 

const (
	TaskPlanning   Status = "planning"
	TaskQueued     Status = "queued"
	TaskInProgress Status = "in_progress"
	TaskBlocked    Status = "blocked"
	TaskComplete   Status = "complete"
	TaskFailed     Status = "failed"
	TaskAborted    Status = "aborted"
)

Task statuses. A task moves through seven lifecycle states; the legal arcs are declared in the KindTask matrix below. The terminal states (Complete, Failed, Aborted) have no outgoing arcs. Values are lowercase to match the on-disk task-file **Status:** convention. 

const (
	LessonRecorded   Status = "Recorded"
	LessonStated     Status = "Stated"
	LessonEnforced   Status = "Enforced"
	LessonWithdrawn  Status = "Withdrawn"
	LessonSuperseded Status = "Superseded"
)

Lesson statuses. A Lesson climbs the enforcement ladder — Recorded (Tier 0, written down), Stated (Tier 1, loaded by an agent before acting), Enforced (Tier 2, a machine refuses) — and may reach one of two terminal dispositions at any rung: Withdrawn (turned out wrong / not applicable) or Superseded (replaced by a newer lesson). The vocabulary deliberately mirrors the Plan disposition set rather than inventing new terms. 

const (
	DecisionDraft      Status = "Draft"
	DecisionInReview   Status = "In Review"
	DecisionApproved   Status = "Approved"
	DecisionRejected   Status = "Rejected"
	DecisionSuperseded Status = "Superseded"
	DecisionDeprecated Status = "Deprecated"
)

Decision statuses. The vocabulary is closed by pkg/lint's D-status-values rule (decisionValidStatuses in pkg/lint/decision_rules.go) — these six values are the ONLY recognized **Status:** tokens for a Decision artifact; this const block mirrors that closed set rather than inventing one.

The three pre-terminal statuses (Draft, In Review, Approved) form the prep band, mirroring Plan's shape. The three dispositions (Rejected, Superseded, Deprecated) are terminal: D-archived-location requires every Decision carrying one of them to live under spec/decisions/archived/, which `decision change-status` enforces by relocating the file as part of the same atomic transition (see pkg/decision.ChangeStatus).

func LegalSources 

func LegalSources(kind Kind, to Status) []Status

LegalSources is the inverse of LegalTargets: which from-states can transition INTO to. Used by error-message construction when target is valid as a status name but invalid for the current source state.

func LegalStatuses 

func LegalStatuses(kind Kind) []Status

LegalStatuses returns every recognized status for a kind (the union of every From and To in its matrix), sorted alphabetically. Used by the CLI layer to validate a --to flag value before invoking the state-machine check.

func LegalTargets 

func LegalTargets(kind Kind, from Status) []Status

LegalTargets returns the legal target statuses reachable from (kind, from), sorted alphabetically. The empty slice is returned (never nil for an unknown kind, but never nil for a known kind either) when from is not a legal source state in the kind's matrix.

func ParseStatus 

func ParseStatus(kind Kind, raw string) (Status, bool)

ParseStatus does case-insensitive parsing of a raw flag-string against the kind's recognized statuses, returning the canonical title-cased Status on success.

Whitespace is trimmed; case is folded (so "draft", "Draft", "DRAFT", and " Draft " all match). Multi-word statuses ("Under Review") match case-insensitively but the internal-whitespace shape MUST match (i.e., "underreview" without a space does NOT match "Under Review"). This is the least-surprising behavior for a CLI flag.

func StatusFromBytes added in v0.35.0 

func StatusFromBytes(original []byte) (Status, error)

StatusFromBytes returns the body Status parsed from bytes held by a compound transaction. It never reads from disk.

func Validate 

func Validate(kind Kind, artifactPath string, to Status) (Status, error)

Validate is a legacy convenience that reads artifactPath, extracts its current Status, and checks that the transition is legal. It does not mutate. Transaction-profile writers MUST instead parse and call Transition from the exact bytes supplied by TransformArtifact; stitching Validate and Rewrite together would validate outside the artifact lock.

It returns the from status on success. On failure it returns one of:

  • an os error if the file cannot be opened or read
  • ErrStatusLineNotFound if the file has no recognizable **Status:** line
  • an *InvalidTransitionError if the transition is illegal in kind's matrix

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.