Module plan 

The plan: milestones, issues, the two graphs between them, and everything derived from them — execution waves, issue status, milestone status, the roadmap order, the active milestone, the next executable issue and every validation finding.

This is a second reader of one set of semantics, not a second set. lib/project.awk is the incumbent engine: the shell tool, the site generator and the GitHub adapter all call it, and it has been the only implementation since the model existed. This module derives the same values in Rust so that the capability registry can answer them — an agent asking the shared MCP server what to work on next could not be told otherwise — and the two are held to byte equality by test/cases/99_plan_capabilities.sh, which runs both over every record in this repository and over a fixture built to hit the edges. Where the two disagree the awk is right; this file is the one that changes.

The order of derivation below follows lib/project.awk step for step, including the order findings are produced in, because that order is observable: a reader diffing the two engines diffs a sequence, not a set. Comments name the awk block each step mirrors.

Nothing here reads a file. Milestones and issues are ordinary declarative objects of the layer — kinds milestone and issue, whole-YAML metadata — already discovered, parsed and schema-validated by the time the index holds them, so building the plan is a walk of values already in memory. That is what lets it be built on demand, inside the handler of a plan capability, rather than eagerly when a crate::capability::Context is composed: App::load has a stated budget and 200 project records have no business inside it.

Structs

Plan

The whole derived plan: what every plan capability answers out of.

PlanCounts

A milestone’s issues counted: the two denominators, then one entry per declared status.

PlanEdge

One dependency edge, from before to.

PlanFinding

One validation finding, in the shape project.finding-carries-reproduce asks for.

PlanIssue

One issue, as its record declares it and as the graph derives it.

PlanMilestone

One milestone, as its record declares it and as the two graphs derive it.

PlanProject

The plan’s header: what this repository is, plus the one field nobody authors.

PlanVocabulary

The status vocabularies, so a reader never has to know which statuses exist.

PlanWave

One execution wave: the issues the graph allows to run at the same time.

Enums

Transition

One lifecycle move.

TransitionError

Why a transition did not happen.

Constants

ISSUE

The kind of an issue record.

ISSUE_STATUSES

The issue status vocabulary, in derivation order. The same list, in the same order, as ISTATUS in lib/project.awk; a status assigned that this does not declare is a finding, in both engines.

MILESTONE

The kind of a milestone record.

MILESTONE_STATUSES

The milestone status vocabulary, in derivation order (MSTATUS in lib/project.awk).

PROJECT

The kind of the plan’s header record.

SEALED_FROM

The first instant a stamp could only have been written with its seal (ADR 0097).

Functions

check

Whether transition is legal for issue as the plan reads now, and why not when it is not.

overlap

Does path a contain path b, or the reverse? Trailing slashes and ./ are normalised so that a hand-written scope entry cannot silently miss an overlap. overlap() in lib/project.awk.

scalar

One YAML scalar as the flattener would have written it: the text an awk comparison sees.

seal

The seal of one transition: the proof, tracked in the record beside the stamp, that the stamp was written by the transition that appends its event.

transition

Perform one transition: check it, stamp the record, append the event.