devrites 3.0.1 → 3.0.3

package/engine/internal/lib/cursor_compat_test.go

@@ -0,0 +1,120 @@
+package lib
+
+import (
+	"bytes"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+)
+
+const canonicalCursor = `# State
+
+## Cursor
+| Key | Value |
+| --- | --- |
+| phase | temper |
+| status | running |
+| next_action | /rite-define |
+| plan_approved | 2026-07-20 |
+| afk_slices_remaining | 2 |
+`
+
+func TestCanonicalCursorReadAndWriteConsumers(t *testing.T) {
+	root := t.TempDir()
+	dir := filepath.Join(root, "work", "demo")
+	if err := os.MkdirAll(dir, 0o755); err != nil {
+		t.Fatal(err)
+	}
+	statePath := filepath.Join(dir, "state.md")
+	if err := os.WriteFile(statePath, []byte(canonicalCursor), 0o644); err != nil {
+		t.Fatal(err)
+	}
+
+	t.Run("build readiness", func(t *testing.T) {
+		var stdout, stderr bytes.Buffer
+		if code := BuildReadiness(root, []string{"demo"}, &stdout, &stderr); code != 0 {
+			t.Fatalf("code=%d, stderr=%s", code, stderr.String())
+		}
+	})
+
+	t.Run("progress", func(t *testing.T) {
+		var stdout bytes.Buffer
+		if code := Progress(root, []string{"demo"}, &stdout, &bytes.Buffer{}); code != 0 {
+			t.Fatalf("code=%d", code)
+		}
+		if !strings.Contains(stdout.String(), "rite-temper") || !strings.Contains(stdout.String(), "temper ◉") {
+			t.Fatalf("progress ignored table phase:\n%s", stdout.String())
+		}
+	})
+
+	t.Run("tick AFK", func(t *testing.T) {
+		var stdout, stderr bytes.Buffer
+		if code := TickAfk([]string{statePath}, &stdout, &stderr); code != 0 {
+			t.Fatalf("code=%d, stderr=%s", code, stderr.String())
+		}
+		raw, err := os.ReadFile(statePath)
+		if err != nil {
+			t.Fatal(err)
+		}
+		if !strings.Contains(string(raw), "| afk_slices_remaining | 1 |") {
+			t.Fatalf("tick AFK did not preserve/update table:\n%s", raw)
+		}
+	})
+}
+
+func TestClearAwaitingSupportsCanonicalCursor(t *testing.T) {
+	path := filepath.Join(t.TempDir(), "state.md")
+	state := canonicalCursor + `
+## Awaiting human
+| Key | Value |
+| --- | --- |
+| question_id | Q-001 |
+| gate | blocking |
+`
+	state = strings.Replace(state, "| status | running |", "| status | awaiting_human |", 1)
+	if err := os.WriteFile(path, []byte(state), 0o644); err != nil {
+		t.Fatal(err)
+	}
+
+	if err := clearAwaiting(path, "Q-001"); err != nil {
+		t.Fatal(err)
+	}
+	raw, err := os.ReadFile(path)
+	if err != nil {
+		t.Fatal(err)
+	}
+	text := string(raw)
+	if strings.Contains(text, "## Awaiting human") || !strings.Contains(text, "| status | running |") {
+		t.Fatalf("canonical awaiting state was not cleared:\n%s", text)
+	}
+	if !strings.Contains(text, "$rite-temper") || strings.Contains(text, "$rite-build") {
+		t.Fatalf("canonical awaiting state resumed the wrong phase:\n%s", text)
+	}
+}
+
+func TestProgressReadsCanonicalSlicesAndShowsPlanPhase(t *testing.T) {
+	root := t.TempDir()
+	dir := filepath.Join(root, "work", "demo")
+	if err := os.MkdirAll(dir, 0o755); err != nil {
+		t.Fatal(err)
+	}
+	stateText := strings.Replace(canonicalCursor, "| phase | temper |", "| phase | plan |", 1)
+	stateText = strings.Replace(stateText, "| afk_slices_remaining | 2 |", "| active_slice | SLICE-002 |", 1)
+	if err := os.WriteFile(filepath.Join(dir, "state.md"), []byte(stateText), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	tasks := "## SLICE-001 First\nStatus: built\n\n## SLICE-002 Second\nStatus: pending\n"
+	if err := os.WriteFile(filepath.Join(dir, "tasks.md"), []byte(tasks), 0o644); err != nil {
+		t.Fatal(err)
+	}
+
+	var stdout bytes.Buffer
+	if code := Progress(root, []string{"demo"}, &stdout, &bytes.Buffer{}); code != 0 {
+		t.Fatalf("code=%d", code)
+	}
+	text := stdout.String()
+	if !strings.Contains(text, "Slice 1/2") || !strings.Contains(text, "plan ◉") || strings.Contains(text, "build ◉") {
+		t.Fatalf("progress missed canonical slice/plan state:\n%s", text)
+	}
+}

package/engine/internal/lib/preamble.go

@@ -117,7 +117,7 @@ func tallyOpenQuestions(data []byte) (blocking, validating, advisory, escalating
 	}
 	for _, line := range splitLinesNoTrailing(data) {
 		switch {
-		case strings.HasPrefix(line, "## q-"):
+		case strings.HasPrefix(strings.ToLower(line), "## q-"):
 			finalize()
 			inQ, status, gate = true, "", ""
 		case inQ && strings.HasPrefix(line, "status:"):

package/engine/internal/lib/preamble_questions_test.go

@@ -0,0 +1,10 @@
+package lib
+
+import "testing"
+
+func TestTallyOpenQuestionsAcceptsCanonicalUppercaseIDs(t *testing.T) {
+	b, v, a, e := tallyOpenQuestions([]byte("## Q-001\nstatus: open\ngate: blocking\n\n## q-2026-07-20-001\nstatus: open\ngate: escalating\n"))
+	if b != 1 || v != 0 || a != 0 || e != 1 {
+		t.Fatalf("counts=(%d,%d,%d,%d), want (1,0,0,1)", b, v, a, e)
+	}
+}

package/engine/internal/lib/progress.go

@@ -7,18 +7,20 @@ import (
 	"path/filepath"
 	"regexp"
 	"strings"
+
+	"github.com/devrites/devrites/internal/state"
 )
 
 // State-parsing patterns ported verbatim from progress.sh's awk. Each name-strip
 // sub is anchored (^ or $), so it matches at most once per line — ReplaceAllString
 // is therefore equivalent to awk's single-match sub.
 var (
-	phaseSplitRe   = regexp.MustCompile(`: *`)
 	sliceCheckRe   = regexp.MustCompile(`^- \[[^\]]*\][[:space:]]*`)             // drop "- [x] "
 	sliceNameRe    = regexp.MustCompile(`^Slice[[:space:]]*[0-9]+:[[:space:]]*`) // drop "Slice N: "
 	sliceStateRe   = regexp.MustCompile(`[[:space:]]+(built|pending)[[:space:]]*$`)
 	sliceSepRe     = regexp.MustCompile(`[[:space:]]+[^[:alnum:][:space:]]+[[:space:]]*$`) // drop " — "
 	sliceCheckedRe = regexp.MustCompile(`\[[xX]\]`)
+	sliceHeadingRe = regexp.MustCompile(`^##[[:space:]]+(SLICE-[0-9]{3})(?:[[:space:]]+(.*))?$`)
 )
 
 // Progress renders the active feature's position — the deterministic footer every
@@ -49,6 +51,9 @@ func Progress(root string, args []string, stdout, stderr io.Writer) int {
 		phase = "spec"
 	}
 	total, built, lastbuilt := tallySlices(lines)
+	if total == 0 {
+		total, built, lastbuilt = tallyCanonicalSlices(workDir)
+	}
 
 	// Header rule: pad "── rite-<phase> " with box glyphs to ≥44 BYTES. Under the
 	// oracle's LC_ALL=C the bash `${#header}` counts bytes, which len() matches.
@@ -77,22 +82,30 @@ func Progress(root string, args []string, stdout, stderr io.Writer) int {
 		}
 	}
 
-	// Flow ribbon: the lifecycle spine; temper/vet appear only once their artifact
-	// exists.
-	order := []string{"spec"}
-	if isFile(filepath.Join(workDir, "strategy.md")) {
-		order = append(order, "temper")
-	}
-	order = append(order, "define")
-	if isFile(filepath.Join(workDir, "eng-review.md")) {
-		order = append(order, "vet")
+	// Flow ribbon: the lifecycle spine; optional phases appear once their artifact
+	// exists or while they are the active phase, so the cursor is never omitted.
+	order := make([]string, 0, len(state.LifecyclePhases()))
+	for _, lifecyclePhase := range state.LifecyclePhases() {
+		name := string(lifecyclePhase)
+		include := true
+		switch lifecyclePhase {
+		case state.PhaseFrame:
+			include = phase == name
+		case state.PhaseTemper:
+			include = phase == name || isFile(filepath.Join(workDir, "strategy.md"))
+		case state.PhaseDone:
+			include = false
+		case state.PhaseVet:
+			include = phase == name || isFile(filepath.Join(workDir, "eng-review.md"))
+		case state.PhaseConverge:
+			include = phase == name
+		}
+		if include {
+			order = append(order, name)
+		}
 	}
-	order = append(order, "build", "prove", "polish", "review", "seal", "ship")
 
 	cur := phase
-	if cur == "plan" { // replan sits at build
-		cur = "build"
-	}
 	idx := -1
 	if phase == "done" { // past ship
 		idx = len(order)
@@ -118,25 +131,52 @@ func Progress(root string, args []string, stdout, stderr io.Writer) int {
 	return 0
 }
 
-// parsePhase returns the first whitespace token of the value on the first
-// "- Phase:" line, mirroring progress.sh's `awk -F': *' '/^- Phase:/{print $2}' |
-// awk '{print $1}'`. Empty when absent.
-func parsePhase(lines []string) string {
-	for _, line := range lines {
-		if !strings.HasPrefix(line, "- Phase:") {
-			continue
+func tallyCanonicalSlices(workDir string) (total, built int, lastbuilt string) {
+	raw, err := os.ReadFile(filepath.Join(workDir, "tasks.md"))
+	if err != nil {
+		return 0, 0, ""
+	}
+	name, sliceState := "", ""
+	finalize := func() {
+		if name == "" {
+			return
 		}
-		fields := phaseSplitRe.Split(line, -1)
-		if len(fields) < 2 {
-			return ""
+		total++
+		if sliceState == "built" {
+			built++
+			lastbuilt = name
 		}
-		toks := strings.Fields(fields[1])
-		if len(toks) == 0 {
-			return ""
+	}
+	for _, line := range strings.Split(string(raw), "\n") {
+		if match := sliceHeadingRe.FindStringSubmatch(strings.TrimSpace(line)); match != nil {
+			finalize()
+			name = match[1]
+			if strings.TrimSpace(match[2]) != "" {
+				name += " " + strings.TrimSpace(match[2])
+			}
+			sliceState = "pending"
+			continue
 		}
-		return toks[0]
+		if name != "" && strings.HasPrefix(strings.ToLower(strings.TrimSpace(line)), "status:") {
+			_, value, _ := strings.Cut(strings.TrimSpace(line), ":")
+			sliceState = strings.ToLower(strings.TrimSpace(value))
+		}
+	}
+	finalize()
+	return total, built, lastbuilt
+}
+
+// parsePhase returns the first token of the canonical or legacy phase field.
+func parsePhase(lines []string) string {
+	value, ok := state.CursorField(lines, state.CursorPhase)
+	if !ok {
+		return ""
+	}
+	toks := strings.Fields(value)
+	if len(toks) == 0 {
+		return ""
 	}
-	return ""
+	return toks[0]
 }
 
 // tallySlices reads the "## Slice progress" block: total slice lines, how many are

package/engine/internal/lib/resolve.go

@@ -10,6 +10,7 @@ import (
 	"time"
 
 	"github.com/devrites/devrites/internal/fsutil"
+	"github.com/devrites/devrites/internal/state"
 	"github.com/devrites/devrites/internal/workflow"
 )
 
@@ -219,7 +220,7 @@ func resolveQuestion(qfile, qid, status, answer string, stderr io.Writer) int {
 }
 
 var (
-	qHeaderRe    = regexp.MustCompile(`^## q-`)
+	qHeaderRe    = regexp.MustCompile(`(?i)^## q-`)
 	statusLineRe = regexp.MustCompile(`^status:`)
 	statusStrip  = regexp.MustCompile(`^status:[[:space:]]*`)
 	answeredAtRe = regexp.MustCompile(`^answered_at:`)
@@ -285,8 +286,6 @@ func rewriteQuestionFields(lines []string, target *regexp.Regexp, status, answer
 var (
 	awaitingRe = regexp.MustCompile(`^## Awaiting human`)
 	hdrSpaceRe = regexp.MustCompile(`^##[[:space:]]`)
-	statusMdRe = regexp.MustCompile(`^- Status:`)
-	nextStepRe = regexp.MustCompile(`^- Next step:`)
 	logHdrRe   = regexp.MustCompile(`^## Log`)
 )
 
@@ -300,10 +299,18 @@ func clearAwaiting(sfile, qid string) error {
 		return fmt.Errorf("read state %s: %w", sfile, err)
 	}
 	lines := splitLinesNoTrailing(data)
-	qidRef := regexp.MustCompile(`qid:[[:space:]]*` + regexp.QuoteMeta(qid) + `([[:space:]]|$)`)
-
+	resumePhase := state.PhaseBuild
+	if rawPhase, ok := state.CursorField(lines, state.CursorPhase); ok {
+		if fields := strings.Fields(strings.ToLower(rawPhase)); len(fields) > 0 {
+			if phase, known := state.PhaseForName(fields[0]); known && state.ResumeVerb(phase) != "" {
+				resumePhase = phase
+			}
+		}
+	}
+	resumeCommand := workflow.ForVerb(state.ResumeVerb(resumePhase))
 	// First check whether the awaiting block references this question at all.
-	inAw, matched := false, false
+	inAw := false
+	var awaitingLines []string
 	for _, line := range lines {
 		switch {
 		case awaitingRe.MatchString(line):
@@ -312,11 +319,12 @@ func clearAwaiting(sfile, qid string) error {
 		case inAw && hdrSpaceRe.MatchString(line):
 			inAw = false
 		}
-		if inAw && qidRef.MatchString(line) {
-			matched = true
+		if inAw {
+			awaitingLines = append(awaitingLines, line)
 		}
 	}
-	if !matched {
+	waitingOn, _ := state.CursorField(awaitingLines, state.CursorQuestionID)
+	if waitingOn != qid {
 		return nil
 	}
 
@@ -336,19 +344,13 @@ func clearAwaiting(sfile, qid string) error {
 			continue
 		}
 		switch {
-		case statusMdRe.MatchString(line):
-			out = append(out, "- Status: running")
-			continue
-		case nextStepRe.MatchString(line):
-			out = append(out, "- Next step: (resume — `"+workflow.ForVerb("build").Both()+"` to continue the workflow)")
-			continue
 		case logHdrRe.MatchString(line):
 			out = append(out, line)
 			inLog = true
 			continue
 		case inLog && hdrSpaceRe.MatchString(line):
 			if !logAppended {
-				out = append(out, fmt.Sprintf("- %s build: resolved %s", ts, qid))
+				out = append(out, fmt.Sprintf("- %s %s: resolved %s", ts, resumePhase, qid))
 				logAppended = true
 			}
 			inLog = false
@@ -358,8 +360,10 @@ func clearAwaiting(sfile, qid string) error {
 		out = append(out, line)
 	}
 	if inLog && !logAppended {
-		out = append(out, fmt.Sprintf("- %s build: resolved %s", ts, qid))
+		out = append(out, fmt.Sprintf("- %s %s: resolved %s", ts, resumePhase, qid))
 	}
+	out, _ = state.SetCursorField(out, state.CursorStatus, "running")
+	out, _ = state.SetCursorField(out, state.CursorNextAction, "(resume — `"+resumeCommand.Both()+"` to continue the workflow)")
 	if err := fsutil.WriteFileAtomic(sfile, joinRecords(out), 0o644); err != nil {
 		return fmt.Errorf("update state %s: %w", sfile, err)
 	}

package/engine/internal/lib/resolve_remediation_test.go

@@ -39,6 +39,15 @@ func TestResolveCompletesMissingAnswerFieldsInSingleRewrite(t *testing.T) {
 	}
 }
 
+func TestResolveAcceptsCanonicalUppercaseQuestionID(t *testing.T) {
+	root := resolveWorkspace(t, "## Q-001 blocking\nstatus: open\n")
+	var stdout, stderr bytes.Buffer
+
+	if code := Resolve(root, []string{"Q-001", "canonical answer"}, &stdout, &stderr); code != 0 {
+		t.Fatalf("code = %d, want 0; stderr=%q", code, stderr.String())
+	}
+}
+
 func resolveWorkspace(t *testing.T, questions string) string {
 	t.Helper()
 	root := t.TempDir()

package/engine/internal/lib/tickafk.go

@@ -4,17 +4,13 @@ import (
 	"fmt"
 	"io"
 	"os"
-	"regexp"
 	"strconv"
 	"strings"
 
 	"github.com/devrites/devrites/internal/fsutil"
+	"github.com/devrites/devrites/internal/state"
 )
 
-// budgetField matches an "AFK slices remaining:" line and captures the value that
-// follows. The optional leading "- " tolerates state.md's markdown-bullet form.
-var budgetField = regexp.MustCompile(`^[[:space:]]*-?[[:space:]]*AFK slices remaining:[[:space:]]*`)
-
 // TickAfk spends one slice from a run's AFK budget: it reads the "AFK slices
 // remaining" count from the state.md at args[0], decrements it, and writes the
 // file back. /rite-build calls it after building a slice unattended.
@@ -69,31 +65,18 @@ func TickAfk(args []string, stdout, stderr io.Writer) int {
 // readBudget returns the current "AFK slices remaining" value — the first blank-
 // delimited token after the field — and whether the field is present at all.
 func readBudget(lines []string) (value string, found bool) {
-	for _, line := range lines {
-		loc := budgetField.FindStringIndex(line)
-		if loc == nil {
-			continue
-		}
-		value = line[loc[1]:]
-		if i := strings.IndexAny(value, spaceChars); i >= 0 {
-			value = value[:i]
-		}
-		return value, true
+	value, found = state.CursorField(lines, state.CursorAFKSlicesRemaining)
+	if !found {
+		return "", false
 	}
-	return "", false
+	if i := strings.IndexAny(value, spaceChars); i >= 0 {
+		value = value[:i]
+	}
+	return value, true
 }
 
-// setBudget rewrites every budget line to the canonical bullet form with the new
-// count, passing all other lines through. The result is newline-terminated.
+// setBudget preserves the cursor's canonical-table or legacy-bullet format.
 func setBudget(lines []string, n int) []byte {
-	var b strings.Builder
-	for _, line := range lines {
-		if budgetField.MatchString(line) {
-			fmt.Fprintf(&b, "- AFK slices remaining: %d", n)
-		} else {
-			b.WriteString(line)
-		}
-		b.WriteByte('\n')
-	}
-	return []byte(b.String())
+	updated, _ := state.SetCursorField(lines, state.CursorAFKSlicesRemaining, strconv.Itoa(n))
+	return []byte(strings.Join(updated, "\n") + "\n")
 }

package/engine/internal/migrate/migrate.go

@@ -141,53 +141,34 @@ Normalized by DevRites migration.
 `, slug, slug, phase, state.SchemaVersion)
 }
 
-// derivePhase reads the legacy state.md and maps its recorded phase/status onto a
-// v1 phase. An unreadable or unrecognised state defaults to build — the safe
-// middle of the arc, from which the completeness gates re-derive what's missing.
+// derivePhase reads state.md in either canonical cursor-table or legacy form and
+// maps its recorded phase/status onto the current lifecycle. An unreadable or
+// unrecognised state defaults to build — the safe middle of the arc, from which
+// the completeness gates re-derive what's missing.
 func derivePhase(statePath string) state.Phase {
 	raw, err := os.ReadFile(statePath)
 	if err != nil {
 		return state.PhaseBuild
 	}
-	for _, line := range strings.Split(string(raw), "\n") {
-		t := strings.TrimLeft(strings.ToLower(strings.TrimSpace(line)), "-*+ \t")
-		key, val, ok := strings.Cut(t, ":")
-		if !ok || (strings.TrimSpace(key) != "phase" && strings.TrimSpace(key) != "status") {
-			continue
-		}
-		if p, ok := mapLegacyPhase(strings.TrimSpace(val)); ok {
-			return p
+	lines := strings.Split(string(raw), "\n")
+	for _, key := range []string{state.CursorPhase, state.CursorStatus} {
+		if value, found := state.CursorField(lines, key); found {
+			if p, ok := mapLegacyPhase(value); ok {
+				return p
+			}
 		}
 	}
 	return state.PhaseBuild
 }
 
-// mapLegacyPhase maps a legacy phase/status word onto a v1 phase.
+// mapLegacyPhase maps a current or legacy phase/status word onto the lifecycle.
 func mapLegacyPhase(word string) (state.Phase, bool) {
+	word = strings.ToLower(strings.TrimSpace(word))
 	// Take the first token, so "done — shipped 2024" maps on "done".
 	if i := strings.IndexAny(word, " \t—-"); i > 0 {
 		word = word[:i]
 	}
-	switch word {
-	case "frame":
-		return state.PhaseFrame, true
-	case "spec", "specced", "specifying":
-		return state.PhaseSpec, true
-	case "plan", "planned", "define", "defined":
-		return state.PhasePlan, true
-	case "build", "building", "wip", "in", "in-progress":
-		return state.PhaseBuild, true
-	case "prove", "proving", "proven", "testing":
-		return state.PhaseProve, true
-	case "vet", "review", "reviewing", "vetting":
-		return state.PhaseVet, true
-	case "seal", "sealed", "sealing":
-		return state.PhaseSeal, true
-	case "ship", "shipped", "done", "closed", "complete", "completed":
-		return state.PhaseShip, true
-	default:
-		return "", false
-	}
+	return state.PhaseForName(word)
 }
 
 // backupWorkspace snapshots mutable state (work/, features/, and the ACTIVE pointer) into

package/engine/internal/migrate/migrate_test.go

@@ -41,8 +41,8 @@ func TestRunNormalizesCanonicalWorkLayout(t *testing.T) {
 	if err != nil {
 		t.Fatal(err)
 	}
-	if f.Phase != state.PhaseShip {
-		t.Fatalf("migrated phase=%q, want %q", f.Phase, state.PhaseShip)
+	if f.Phase != state.PhaseDone {
+		t.Fatalf("migrated phase=%q, want %q", f.Phase, state.PhaseDone)
 	}
 	assertFile(t, res.BackupDir, "ACTIVE", "alpha\n")
 
@@ -80,6 +80,13 @@ func TestRunNormalizesLiveFeatureAliases(t *testing.T) {
 }
 
 func TestMapLegacyPhase(t *testing.T) {
+	for _, phase := range state.LifecyclePhases() {
+		got, ok := mapLegacyPhase(string(phase))
+		if !ok || got != phase {
+			t.Fatalf("mapLegacyPhase(%q)=(%q,%v), want canonical phase", phase, got, ok)
+		}
+	}
+
 	for _, tc := range []struct {
 		word string
 		want state.Phase
@@ -87,7 +94,8 @@ func TestMapLegacyPhase(t *testing.T) {
 	}{
 		{word: "specced", want: state.PhaseSpec, ok: true},
 		{word: "in-progress", want: state.PhaseBuild, ok: true},
-		{word: "done - shipped", want: state.PhaseShip, ok: true},
+		{word: "reviewing", want: state.PhaseReview, ok: true},
+		{word: "done - shipped", want: state.PhaseDone, ok: true},
 		{word: "mystery"},
 	} {
 		got, ok := mapLegacyPhase(tc.word)

package/engine/internal/state/cmd/workflowmanifest/main.go

@@ -0,0 +1,54 @@
+// Command workflowmanifest writes the deterministic cross-language derivative
+// of state.WorkflowPhases. The typed Go registry remains the authority.
+package main
+
+import (
+	"bytes"
+	"encoding/json"
+	"flag"
+	"fmt"
+	"os"
+
+	"github.com/devrites/devrites/internal/state"
+)
+
+func main() {
+	outPath := flag.String("out", "workflow_manifest.json", "output path")
+	check := flag.Bool("check", false, "fail when the output is stale")
+	flag.Parse()
+
+	document := struct {
+		GeneratedBy      string                 `json:"generatedBy"`
+		SchemaVersion    int                    `json:"schemaVersion"`
+		Phases           []state.WorkflowPhase  `json:"phases"`
+		CursorKeyAliases []state.CursorKeyAlias `json:"cursorKeyAliases"`
+	}{
+		GeneratedBy:      "go generate ./internal/state; DO NOT EDIT",
+		SchemaVersion:    state.SchemaVersion,
+		Phases:           state.WorkflowPhases(),
+		CursorKeyAliases: state.CursorKeyAliases(),
+	}
+	data, err := json.MarshalIndent(document, "", "  ")
+	if err != nil {
+		fatal(err)
+	}
+	data = append(data, '\n')
+	if *check {
+		current, err := os.ReadFile(*outPath)
+		if err != nil {
+			fatal(err)
+		}
+		if !bytes.Equal(current, data) {
+			fatal(fmt.Errorf("%s is stale; run go generate ./internal/state", *outPath))
+		}
+		return
+	}
+	if err := os.WriteFile(*outPath, data, 0o644); err != nil {
+		fatal(err)
+	}
+}
+
+func fatal(err error) {
+	fmt.Fprintln(os.Stderr, err)
+	os.Exit(1)
+}