Documentation
¶
Overview ¶
Package plan parses plan files under docs/plans and scaffolds new plans from the rendered plans template (awf new plan). Unlike internal/adr it is not coupled to sequential numbering - plans are date-prefixed.
Index ¶
- Variables
- func NewFileLeased(root string, lease *filesystem.Lease, files *filesystem.Handle, ...) (string, error)
- func RenderProjection(p Plan, selector string) ([]byte, error)
- func RenderProjectionInput(input ProjectionInput) ([]byte, error)
- func Select(p Plan, selector string) (Phase, Task, error)
- type ADRLink
- type AmbiguousError
- type DecisionRef
- type Diagnostic
- type DiagnosticsError
- type DoDItem
- type ExecutionMode
- type InvalidSelectorError
- type NotFoundError
- type PathEntry
- type PathKind
- type Phase
- type Plan
- type ProjectionInput
- type ResolvedDecision
- type Source
- type Task
- type TaskFields
- type TaskKind
- type TaskLatitude
- type TerminalReconciliation
Constants ¶
This section is empty.
Variables ¶
var FilenameRe = regexp.MustCompile(`^\d{4}-\d{2}-\d{2}-.+\.md$`)
FilenameRe matches a plan filename (YYYY-MM-DD-slug.md); it excludes template.md and README.md just as adr.FilenameRe's numeric form does.
var ValidStatuses = map[string]bool{"Proposed": true, "Implemented": true}
ValidStatuses are the two plan lifecycle states (ADR-0097): mutable while Proposed, frozen at Implemented.
Functions ¶
func NewFileLeased ¶ added in v0.41.0
func NewFileLeased(root string, lease *filesystem.Lease, files *filesystem.Handle, plansDir, title string) (string, error)
NewFileLeased scaffolds one plan through the caller-held selected-root capability. plansDir is root-relative, so template observation and exclusive publication remain confined to the authority protected by the caller's lease. touches-state: adr-system/plan-artifacts:plan-new-unnumbered - unnumbered dated plan scaffold; proof in plan_test.go
func RenderProjection ¶ added in v0.30.0
RenderProjection renders an executable closure selected by canonical P or P.T.
func RenderProjectionInput ¶ added in v0.30.0
func RenderProjectionInput(input ProjectionInput) ([]byte, error)
RenderProjectionInput renders only the supplied plan-owned projection input.
Types ¶
type ADRLink ¶ added in v0.30.0
ADRLink is one `adrs:` frontmatter entry. A plan links a decision record by its number or, before integration numbers it, by the retained slug of a pending record, so the link stays valid across numbering without the plan being rewritten (ADR-0202 item 14). Exactly one field is set.
func (ADRLink) Identity ¶ added in v0.30.0
Identity returns the entry's corpus identity key: the four-digit number for a numeric entry, and the retained slug for a slug entry. It is the key adr.Corpus.ByIdentity resolves, so one lookup covers both spellings.
func (*ADRLink) UnmarshalYAML ¶ added in v0.30.0
UnmarshalYAML reads one `adrs:` entry: a digits-only scalar is a number, and any other non-empty string scalar is a slug. A slug is not validated against the slug grammar here - an entry that names no record in the corpus fails link validation with a scoped finding (ADR-0202 item 14) rather than taking the whole check down. The number case is matched first, so an entirely numeric slug would be read as a number; the ADR scaffold refuses an all-digit slug for exactly that reason. Any other node names itself in the error.
type AmbiguousError ¶ added in v0.30.0
AmbiguousError reports an exact spelling that names more than one plan.
func (*AmbiguousError) Error ¶ added in v0.30.0
func (e *AmbiguousError) Error() string
type DecisionRef ¶ added in v0.30.0
DecisionRef is a typed, unresolved plan-v2 Decision reference.
type Diagnostic ¶ added in v0.30.0
Diagnostic describes a stable plan parse, resolution, or projection failure. Path names the affected plan when one has been selected.
func (*Diagnostic) Error ¶ added in v0.30.0
func (d *Diagnostic) Error() string
type DiagnosticsError ¶ added in v0.30.0
type DiagnosticsError struct {
Diagnostics []*Diagnostic
}
DiagnosticsError retains every independently malformed plan in one directory parse while allowing valid siblings to remain available to project checks.
func (*DiagnosticsError) Error ¶ added in v0.30.0
func (e *DiagnosticsError) Error() string
func (*DiagnosticsError) Unwrap ¶ added in v0.30.0
func (e *DiagnosticsError) Unwrap() []error
type ExecutionMode ¶ added in v0.30.0
type ExecutionMode string
ExecutionMode identifies the transaction owner declared by a plan-v1 phase.
const ( ExecutionInline ExecutionMode = "inline" ExecutionSubagentDriven ExecutionMode = "subagent-driven" )
type InvalidSelectorError ¶ added in v0.30.0
InvalidSelectorError reports a selector outside canonical positive P or P.T syntax. Available carries the exact selectors accepted by the selected plan.
func (*InvalidSelectorError) Error ¶ added in v0.30.0
func (e *InvalidSelectorError) Error() string
type NotFoundError ¶ added in v0.30.0
NotFoundError reports an exact plan name or selector that did not resolve.
func (*NotFoundError) Error ¶ added in v0.30.0
func (e *NotFoundError) Error() string
type PathEntry ¶ added in v0.30.0
PathEntry is one validated Paths entry. Authored retains the decoded JSON string. Value is the prefix-free literal/glob value or the complete Git pathspec payload, which consumers must pass byte-for-byte.
type PathKind ¶ added in v0.30.0
type PathKind string
PathKind identifies how a Paths entry is interpreted.
type Phase ¶ added in v0.30.0
type Phase struct {
Number int
Title string
Prefix string
ExecutionMode ExecutionMode
Tasks []Task
Advances []string
Completes []string
Close string
}
Phase is one ordered executable phase in a plan-v1 document. Prefix retains the phase heading, spacing, and execution-mode declaration exactly.
type Plan ¶
type Plan struct {
Filename string
Path string
Date string
ADRs []ADRLink
Status string
Format string
HasFrontmatter bool
// Source retains the authored bytes. plan-v1 projections render only from
// the parsed model and these retained sections; legacy callers need not use it.
Source []byte
Preamble string
Title string
Goal string
ArchitectureSummary string
Phases []Phase
DefinitionOfDone string
DoD []DoDItem
Notes string
// TerminalReconciliation is the optional parsed terminal-history record.
TerminalReconciliation *TerminalReconciliation
// CommitSubjects are the planned commit subjects a plan marks with “`commit
// fences (ADR-0111): the first non-empty line of each fenced block whose info
// string's first token is `commit` and which carries no `awf-ignore` opt-out.
CommitSubjects []string
}
Plan is a parsed plan record. HasFrontmatter is false for the grandfathered pre-convention corpus (ADR-0098), which the checks skip.
func ParseDir ¶
ParseDir scans dir for plan files (YYYY-MM-DD-*.md) and parses each. Files without frontmatter parse to a Plan with HasFrontmatter false.
func ParseSources ¶ added in v0.30.0
ParseSources parses one already-confined source set in its supplied order. It retains valid siblings when independent documents carry diagnostics.
func Resolve ¶ added in v0.30.0
Resolve parses the supplied plans directory and selects an exact filename or filename stem. It deliberately accepts no path grammar or fuzzy title match.
func (Plan) IsImplemented ¶ added in v0.41.0
IsImplemented reports whether the plan body is terminal history.
func (Plan) IsProposed ¶ added in v0.30.0
IsProposed reports whether this plan remains amendable and receives coverage notes.
type ProjectionInput ¶ added in v0.30.0
type ProjectionInput struct {
Plan Plan
Selector string
Applying, Context []ResolvedDecision
}
ProjectionInput supplies a parsed plan and its selected resolved context.
type ResolvedDecision ¶ added in v0.30.0
type ResolvedDecision struct{ Key, ADRIdentity, Title, Status, Markdown string }
ResolvedDecision is plan-owned resolved Decision context for a projection.
type Source ¶ added in v0.30.0
Source is one plan document supplied by a filesystem or immutable snapshot. Filename identifies the plan, Path is its diagnostic display path, and Bytes are the complete authored source.
type Task ¶ added in v0.30.0
type Task struct {
Phase int
Number int
Title string
Fields TaskFields
Content string
}
Task is one ordered task in a plan-v1 phase. Content retains its complete authored block so projection never reparses or reconstructs Markdown.
type TaskFields ¶ added in v0.30.0
type TaskFields struct {
Kind TaskKind
Latitude TaskLatitude
Question string
Paths []PathEntry
Representative string
Edge string
PostCheck string
Applying []DecisionRef
Context []DecisionRef
}
TaskFields is the typed field vocabulary directly beneath a task heading.
type TaskKind ¶ added in v0.30.0
type TaskKind string
TaskKind identifies the optional specialized form of a plan-v1 task.
type TaskLatitude ¶ added in v0.30.0
type TaskLatitude string
TaskLatitude identifies the optional exact authoring form of a plan-v1 task.
const ( TaskQualifying TaskLatitude = "" TaskExact TaskLatitude = "exact" )
type TerminalReconciliation ¶ added in v0.41.0
type TerminalReconciliation struct {
ImplementationRange string
TouchedPaths []string
MaterialDeviations []string
}
TerminalReconciliation is the parsed historical evidence recorded when a Proposed plan becomes Implemented. It deliberately records what landed, rather than a comparison with planned choreography.
func ParseTerminalReconciliation ¶ added in v0.41.0
func ParseTerminalReconciliation(notes string) (*TerminalReconciliation, error)
ParseTerminalReconciliation parses the optional, exact Notes subsection. An absent subsection is ordinary while a plan remains Proposed; terminal transition validation requires it.
func (TerminalReconciliation) ImplementationEndpoints ¶ added in v0.41.0
func (r TerminalReconciliation) ImplementationEndpoints() (base, head string)
ImplementationEndpoints returns the already grammar-validated immutable base and head identifiers in the terminal implementation range.