plan

package
v0.36.1 Latest Latest
Warning

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

Go to latest
Published: Aug 13, 2026 License: AGPL-3.0 Imports: 15 Imported by: 0

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

Constants

This section is empty.

Variables

View Source
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.

View Source
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 NewFile

func NewFile(dir, title string) (string, error)

NewFile scaffolds a new plan under dir from the rendered plans template (dir/template.md): today's date filled, marker comments stripped, named YYYY-MM-DD-slug.md. No sequential number is allocated. Refuses to overwrite. 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

func RenderProjection(p Plan, selector string) ([]byte, error)

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.

func Select added in v0.30.0

func Select(p Plan, selector string) (Phase, Task, error)

Select resolves a canonical phase or task selector using the plan's typed selector errors and available values.

Types

type ADRLink struct {
	Number int
	Slug   string
}

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

func (l ADRLink) Identity() string

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

func (l *ADRLink) UnmarshalYAML(node *yaml.Node) error

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

type AmbiguousError struct {
	Value     string
	Available []string
}

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

type DecisionRef struct {
	Authored string
	ADR      string
	Selector string
	Kind     string
}

DecisionRef is a typed, unresolved plan-v2 Decision reference.

type Diagnostic added in v0.30.0

type Diagnostic struct {
	Category string
	Path     string
	Detail   string
}

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 DoDItem added in v0.30.0

type DoDItem struct {
	Slug    string
	Content string
}

DoDItem is one slugged complete plan-v2 definition-of-done bullet.

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

type InvalidSelectorError struct {
	Value     string
	Available []string
}

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

type NotFoundError struct {
	Kind      string
	Value     string
	Available []string
}

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

type PathEntry struct {
	Kind     PathKind
	Authored string
	Value    string
}

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.

const (
	PathLiteral  PathKind = "literal"
	PathGlob     PathKind = "glob"
	PathPathspec PathKind = "pathspec"
)

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
	// 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

func ParseDir(dir string) ([]Plan, error)

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

func ParseSources(sources []Source) ([]Plan, error)

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

func Resolve(dir, name string) (Plan, error)

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) IsProposed added in v0.30.0

func (p Plan) IsProposed() bool

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

type Source struct {
	Filename string
	Path     string
	Bytes    []byte
}

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.

const (
	TaskImplementation TaskKind = ""
	TaskSpike          TaskKind = "spike"
	TaskBatch          TaskKind = "batch"
)

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"
)

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL