devrites 3.0.0 → 3.0.2

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"
 )
 
@@ -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,9 @@ 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:]]|$)`)
-
 	// 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 +310,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, "question_id")
+	if waitingOn != qid {
 		return nil
 	}
 
@@ -336,12 +335,6 @@ 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
@@ -360,6 +353,8 @@ func clearAwaiting(sfile, qid string) error {
 	if inLog && !logAppended {
 		out = append(out, fmt.Sprintf("- %s build: resolved %s", ts, qid))
 	}
+	out, _ = state.SetCursorField(out, "status", "running")
+	out, _ = state.SetCursorField(out, "next_action", "(resume — `"+workflow.ForVerb("build").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/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, "afk_slices_remaining")
+	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, "afk_slices_remaining", strconv.Itoa(n))
+	return []byte(strings.Join(updated, "\n") + "\n")
 }

package/engine/internal/migrate/migrate.go

@@ -141,29 +141,29 @@ 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{"phase", "status"} {
+		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]
@@ -173,18 +173,30 @@ func mapLegacyPhase(word string) (state.Phase, bool) {
 		return state.PhaseFrame, true
 	case "spec", "specced", "specifying":
 		return state.PhaseSpec, true
-	case "plan", "planned", "define", "defined":
+	case "temper", "tempered", "tempering":
+		return state.PhaseTemper, true
+	case "define", "defined", "defining":
+		return state.PhaseDefine, true
+	case "plan", "planned", "planning":
 		return state.PhasePlan, true
+	case "vet", "vetted", "vetting":
+		return state.PhaseVet, true
 	case "build", "building", "wip", "in", "in-progress":
 		return state.PhaseBuild, true
+	case "converge", "converged", "converging":
+		return state.PhaseConverge, true
 	case "prove", "proving", "proven", "testing":
 		return state.PhaseProve, true
-	case "vet", "review", "reviewing", "vetting":
-		return state.PhaseVet, true
+	case "polish", "polished", "polishing":
+		return state.PhasePolish, true
+	case "review", "reviewed", "reviewing":
+		return state.PhaseReview, true
 	case "seal", "sealed", "sealing":
 		return state.PhaseSeal, true
-	case "ship", "shipped", "done", "closed", "complete", "completed":
+	case "ship", "shipped", "shipping":
 		return state.PhaseShip, true
+	case "done", "closed", "complete", "completed":
+		return state.PhaseDone, true
 	default:
 		return "", false
 	}

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")
 
@@ -87,7 +87,9 @@ 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: "temper", want: state.PhaseTemper, 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/cursor.go

@@ -0,0 +1,84 @@
+package state
+
+import (
+	"strings"
+	"unicode"
+)
+
+type cursorLineKind uint8
+
+const (
+	cursorLineUnknown cursorLineKind = iota
+	cursorLineLegacy
+	cursorLineTable
+)
+
+// CursorField reads a state.md field from either the canonical | key | value |
+// cursor table or the legacy "- Key: value" form.
+func CursorField(lines []string, key string) (string, bool) {
+	want := normalizeCursorKey(key)
+	for _, line := range lines {
+		gotKey, value, _, ok := parseCursorLine(line)
+		if ok && normalizeCursorKey(gotKey) == want {
+			return value, true
+		}
+	}
+	return "", false
+}
+
+// SetCursorField replaces an existing state.md field without changing whether
+// the file uses the canonical table or legacy bullet form.
+func SetCursorField(lines []string, key, value string) ([]string, bool) {
+	want := normalizeCursorKey(key)
+	out := append([]string(nil), lines...)
+	for i, line := range out {
+		gotKey, _, kind, ok := parseCursorLine(line)
+		if !ok || normalizeCursorKey(gotKey) != want {
+			continue
+		}
+		switch kind {
+		case cursorLineTable:
+			indent := line[:len(line)-len(strings.TrimLeft(line, " \t"))]
+			out[i] = indent + "| " + strings.TrimSpace(gotKey) + " | " + value + " |"
+		case cursorLineLegacy:
+			colon := strings.IndexByte(line, ':')
+			out[i] = line[:colon+1] + " " + value
+		}
+		return out, true
+	}
+	return out, false
+}
+
+func parseCursorLine(line string) (key, value string, kind cursorLineKind, ok bool) {
+	trimmed := strings.TrimSpace(line)
+	if len(trimmed) >= 2 && trimmed[0] == '|' && trimmed[len(trimmed)-1] == '|' {
+		cells := strings.Split(trimmed[1:len(trimmed)-1], "|")
+		if len(cells) >= 2 {
+			return strings.TrimSpace(cells[0]), strings.TrimSpace(cells[1]), cursorLineTable, true
+		}
+	}
+
+	trimmed = strings.TrimLeft(trimmed, "-*+ \t")
+	key, value, ok = strings.Cut(trimmed, ":")
+	if !ok || strings.TrimSpace(key) == "" {
+		return "", "", cursorLineUnknown, false
+	}
+	return strings.TrimSpace(key), strings.TrimSpace(value), cursorLineLegacy, true
+}
+
+func normalizeCursorKey(key string) string {
+	var b strings.Builder
+	for _, r := range strings.ToLower(key) {
+		if unicode.IsLetter(r) || unicode.IsDigit(r) {
+			b.WriteRune(r)
+		}
+	}
+	switch b.String() {
+	case "nextstep":
+		return "nextaction"
+	case "qid":
+		return "questionid"
+	default:
+		return b.String()
+	}
+}

package/engine/internal/state/cursor_test.go

@@ -0,0 +1,58 @@
+package state
+
+import "testing"
+
+func TestCursorFieldReadsCanonicalTableAndLegacyLines(t *testing.T) {
+	table := []string{
+		"| Key | Value |",
+		"| --- | --- |",
+		"| phase | temper |",
+		"| status | awaiting_human |",
+		"| next_action | /rite-define |",
+	}
+	legacy := []string{
+		"- Phase: build",
+		"- Status: running",
+		"- Next step: /rite-prove",
+	}
+
+	for _, tc := range []struct {
+		name  string
+		lines []string
+		key   string
+		want  string
+	}{
+		{"table phase", table, "phase", "temper"},
+		{"table status", table, "status", "awaiting_human"},
+		{"table next alias", table, "Next step", "/rite-define"},
+		{"legacy phase", legacy, "phase", "build"},
+		{"legacy next alias", legacy, "next_action", "/rite-prove"},
+	} {
+		t.Run(tc.name, func(t *testing.T) {
+			got, ok := CursorField(tc.lines, tc.key)
+			if !ok || got != tc.want {
+				t.Fatalf("CursorField(%q) = %q, %v; want %q, true", tc.key, got, ok, tc.want)
+			}
+		})
+	}
+}
+
+func TestSetCursorFieldPreservesCanonicalAndLegacyFormats(t *testing.T) {
+	for _, tc := range []struct {
+		name  string
+		lines []string
+		key   string
+		value string
+		want  string
+	}{
+		{"table", []string{"| status | awaiting_human |"}, "status", "running", "| status | running |"},
+		{"legacy", []string{"- AFK slices remaining: 2"}, "afk_slices_remaining", "1", "- AFK slices remaining: 1"},
+	} {
+		t.Run(tc.name, func(t *testing.T) {
+			got, ok := SetCursorField(tc.lines, tc.key, tc.value)
+			if !ok || len(got) != 1 || got[0] != tc.want {
+				t.Fatalf("SetCursorField() = %v, %v; want [%q], true", got, ok, tc.want)
+			}
+		})
+	}
+}

package/engine/internal/state/feature.go

@@ -124,11 +124,11 @@ func CandidateFiles(root, slug string) []string {
 	return files
 }
 
-// LoadFeature reads feature <slug> under root. The phase comes from the manifest
-// (feature.md) frontmatter when present, otherwise from the working-state ledger
-// (state.md, a "- Phase: <p>" line) the live pack writes. A feature with neither a
-// manifest nor a ledger does not exist. Section content is read from the canonical
-// section files or their transitional aliases (see sectionFiles).
+// LoadFeature reads feature <slug> under root. The phase comes from the live
+// working-state ledger when it declares one, otherwise from feature.md
+// frontmatter. A feature with neither a manifest nor a ledger does not exist.
+// Section content is read from the canonical section files or their transitional
+// aliases (see sectionFiles).
 func LoadFeature(root, slug string) (*Feature, error) {
 	dir := featureDir(root, slug)
 
@@ -142,7 +142,7 @@ func LoadFeature(root, slug string) (*Feature, error) {
 		return nil, fmt.Errorf("feature %q not found", slug)
 	}
 
-	var phase Phase
+	var manifestPhase Phase
 	if hasManifest {
 		fm, _ := splitFrontmatter(manifest)
 		if v := strings.TrimSpace(fm["schemaVersion"]); v != "" {
@@ -154,12 +154,16 @@ func LoadFeature(root, slug string) (*Feature, error) {
 				return nil, fmt.Errorf("feature %q: schemaVersion %d is newer than this engine supports (%d); upgrade devrites", slug, n, SchemaVersion)
 			}
 		}
-		phase = Phase(strings.TrimSpace(fm["phase"]))
+		manifestPhase = Phase(strings.TrimSpace(fm["phase"]))
 	}
-	// Ledger fallback: only when the manifest did not declare a phase, so a manifest
-	// with an explicit-but-unknown phase still surfaces as that error below.
-	if phase == "" {
-		phase = PhaseFromLedger(filepath.Join(dir, LedgerFile))
+
+	// state.md is the mutable runtime cursor, so it must win over the manifest,
+	// which migration and compatibility flows may leave stale. Preserve an
+	// explicitly unknown ledger value so the validation below reports it rather
+	// than silently falling back to feature.md.
+	phase, ledgerDeclared := declaredPhaseFromLedger(filepath.Join(dir, LedgerFile))
+	if !ledgerDeclared {
+		phase = manifestPhase
 	}
 	if phase == "" {
 		return nil, fmt.Errorf("feature %q: no phase in feature.md frontmatter or %s ledger", slug, LedgerFile)
@@ -186,31 +190,30 @@ func sectionPresentAny(dir string, s Section) bool {
 	return false
 }
 
-// PhaseFromLedger reads a phase from the working-state ledger: the value of a
-// "- Phase: <p>" line (leading list markers tolerated), taking the first token
-// and accepting it only if it is a phase the engine understands. Returns "" when
-// the file is absent or declares no recognized phase. Unlike migrate's tolerant
-// legacy mapping, this accepts only canonical phase words — the live pack's form.
+// PhaseFromLedger reads a phase from the canonical cursor table or the legacy
+// "- Phase: <p>" form, accepting only phases the engine understands.
 func PhaseFromLedger(path string) Phase {
+	phase, declared := declaredPhaseFromLedger(path)
+	if declared && KnownPhase(phase) {
+		return phase
+	}
+	return ""
+}
+
+func declaredPhaseFromLedger(path string) (Phase, bool) {
 	raw, err := os.ReadFile(path)
 	if err != nil {
-		return ""
+		return "", false
 	}
-	for _, line := range strings.Split(string(raw), "\n") {
-		t := strings.TrimLeft(strings.TrimSpace(line), "-*+ \t")
-		key, val, ok := strings.Cut(t, ":")
-		if !ok || !strings.EqualFold(strings.TrimSpace(key), "phase") {
-			continue
-		}
-		word := strings.ToLower(strings.TrimSpace(val))
-		if i := strings.IndexAny(word, " \t"); i > 0 {
-			word = word[:i]
-		}
-		if p := Phase(word); KnownPhase(p) {
-			return p
-		}
+	value, ok := CursorField(strings.Split(string(raw), "\n"), "phase")
+	if !ok {
+		return "", false
 	}
-	return ""
+	word := strings.ToLower(strings.TrimSpace(value))
+	if i := strings.IndexAny(word, " \t"); i > 0 {
+		word = word[:i]
+	}
+	return Phase(word), true
 }
 
 // ReadDeclaredSchemaVersion returns the schemaVersion declared in a feature's

package/engine/internal/state/schema.go

@@ -46,36 +46,48 @@ var sectionFiles = map[Section][]string{
 }
 
 // LedgerFile is the working-state ledger the live pack writes. It carries the
-// phase (as a "- Phase: <p>" line) when no feature.md manifest declares one, and
-// it satisfies the status section.
+// phase in its canonical cursor table (legacy "- Phase: <p>" remains readable)
+// when no feature.md manifest declares one, and it satisfies the status section.
 const LedgerFile = "state.md"
 
 // Phase is a workflow state. The order mirrors the rite-* arc.
 type Phase string
 
 const (
-	PhaseFrame Phase = "frame" // problem framing
-	PhaseSpec  Phase = "spec"  // specification
-	PhasePlan  Phase = "plan"  // planning
-	PhaseBuild Phase = "build" // implementation
-	PhaseProve Phase = "prove" // proof / testing
-	PhaseVet   Phase = "vet"   // review
-	PhaseSeal  Phase = "seal"  // completeness seal
-	PhaseShip  Phase = "ship"  // shipping
+	PhaseFrame    Phase = "frame"    // problem framing
+	PhaseSpec     Phase = "spec"     // specification
+	PhaseTemper   Phase = "temper"   // strategic specification review
+	PhaseDefine   Phase = "define"   // plan definition
+	PhasePlan     Phase = "plan"     // approved plan
+	PhaseVet      Phase = "vet"      // pre-build engineering review
+	PhaseBuild    Phase = "build"    // implementation
+	PhaseConverge Phase = "converge" // post-build gap closure
+	PhaseProve    Phase = "prove"    // proof / testing
+	PhasePolish   Phase = "polish"   // quality pass
+	PhaseReview   Phase = "review"   // post-proof review
+	PhaseSeal     Phase = "seal"     // completeness seal
+	PhaseShip     Phase = "ship"     // shipping
+	PhaseDone     Phase = "done"     // archived completion
 )
 
 // requiredByPhase lists the sections that must have real content to complete a
 // phase. Completeness is phase-relative: a section not yet required (e.g. proof
 // during the spec phase) never blocks. The set is additive down the arc.
 var requiredByPhase = map[Phase][]Section{
-	PhaseFrame: {},
-	PhaseSpec:  {SectionSpec},
-	PhasePlan:  {SectionSpec, SectionPlan},
-	PhaseBuild: {SectionSpec, SectionPlan, SectionDecisions, SectionTasks},
-	PhaseProve: {SectionSpec, SectionPlan, SectionDecisions, SectionTasks, SectionProof},
-	PhaseVet:   {SectionSpec, SectionPlan, SectionDecisions, SectionTasks, SectionProof},
-	PhaseSeal:  {SectionSpec, SectionPlan, SectionDecisions, SectionTasks, SectionProof, SectionStatus},
-	PhaseShip:  {SectionSpec, SectionPlan, SectionDecisions, SectionTasks, SectionProof, SectionStatus},
+	PhaseFrame:    {},
+	PhaseSpec:     {SectionSpec},
+	PhaseTemper:   {SectionSpec},
+	PhaseDefine:   {SectionSpec, SectionPlan},
+	PhasePlan:     {SectionSpec, SectionPlan},
+	PhaseVet:      {SectionSpec, SectionPlan, SectionDecisions, SectionTasks},
+	PhaseBuild:    {SectionSpec, SectionPlan, SectionDecisions, SectionTasks},
+	PhaseConverge: {SectionSpec, SectionPlan, SectionDecisions, SectionTasks},
+	PhaseProve:    {SectionSpec, SectionPlan, SectionDecisions, SectionTasks, SectionProof},
+	PhasePolish:   {SectionSpec, SectionPlan, SectionDecisions, SectionTasks, SectionProof},
+	PhaseReview:   {SectionSpec, SectionPlan, SectionDecisions, SectionTasks, SectionProof},
+	PhaseSeal:     {SectionSpec, SectionPlan, SectionDecisions, SectionTasks, SectionProof, SectionStatus},
+	PhaseShip:     {SectionSpec, SectionPlan, SectionDecisions, SectionTasks, SectionProof, SectionStatus},
+	PhaseDone:     {SectionSpec, SectionPlan, SectionDecisions, SectionTasks, SectionProof, SectionStatus},
 }
 
 // KnownPhase reports whether p is a phase the engine understands.

package/engine/internal/state/snapshot.go

@@ -121,7 +121,7 @@ func Snapshot(root, slug string) (*WorkspaceSnapshot, error) {
 	}
 
 	workDir := featureDir(root, report.Slug)
-	next := workflow.ForPhase(string(report.Phase))
+	next := nextCommand(workDir, report.Phase)
 	snap := &WorkspaceSnapshot{
 		SchemaVersion:  WorkspaceSnapshotSchema,
 		Slug:           report.Slug,
@@ -152,7 +152,7 @@ func Snapshot(root, slug string) (*WorkspaceSnapshot, error) {
 	if snap.RunMode == "AFK" && len(snap.MissingSections) > 0 {
 		snap.Warnings = append(snap.Warnings, "AFK workspace has missing required sections")
 	}
-	if snap.Evidence.Status == "missing" && (report.Phase == PhaseProve || report.Phase == PhaseSeal || report.Phase == PhaseShip) {
+	if report.Required[SectionProof] && snap.Evidence.Status != "fresh" {
 		snap.Warnings = append(snap.Warnings, "proof phase requires fresh evidence")
 	}
 	if snap.Drift.Open > 0 {
@@ -161,6 +161,17 @@ func Snapshot(root, slug string) (*WorkspaceSnapshot, error) {
 	return snap, nil
 }
 
+func nextCommand(workDir string, phase Phase) workflow.Command {
+	if raw, err := os.ReadFile(filepath.Join(workDir, LedgerFile)); err == nil {
+		if action, ok := CursorField(strings.Split(string(raw), "\n"), "next_action"); ok {
+			if command := workflow.ForAction(action); command.Verb != "" {
+				return command
+			}
+		}
+	}
+	return workflow.ForPhase(string(phase))
+}
+
 func readActiveSlug(root string) string {
 	if ws := devritespaths.WorkspaceOverride(root, ""); ws != "" {
 		return filepath.Base(ws)

package/engine/internal/state/state_test.go

@@ -126,6 +126,52 @@ func TestLoadFeatureFromLedgerAndAliases(t *testing.T) {
 	}
 }
 
+func TestLedgerPhaseOverridesStaleManifestPhase(t *testing.T) {
+	root := filepath.Join(t.TempDir(), ".devrites")
+	writeWorkSection(t, root, "live", "feature.md", "---\nphase: spec\nschemaVersion: 1\n---\n")
+	writeWorkSection(t, root, "live", "state.md", "| Key | Value |\n| --- | --- |\n| phase | temper |\n")
+	writeWorkSection(t, root, "live", "spec.md", "# Spec\n\nReady.\n")
+
+	rep, err := Status(root, "live")
+	if err != nil {
+		t.Fatal(err)
+	}
+	if rep.Phase != PhaseTemper {
+		t.Fatalf("phase=%q, want current ledger phase %q", rep.Phase, PhaseTemper)
+	}
+}
+
+func TestSnapshotUsesCanonicalNextActionAndWarnsWhenRequiredProofMissing(t *testing.T) {
+	root := filepath.Join(t.TempDir(), ".devrites")
+	writeWorkSection(t, root, "live", "state.md", `# State
+
+| Key | Value |
+| --- | --- |
+| phase | review |
+| status | running |
+| next_action | /rite-seal after review is clean |
+`)
+	for name, body := range map[string]string{
+		"spec.md":      "# Spec\n\nReady.\n",
+		"plan.md":      "# Plan\n\nReady.\n",
+		"decisions.md": "# Decisions\n\nReady.\n",
+		"tasks.md":     "# Tasks\n\nReady.\n",
+	} {
+		writeWorkSection(t, root, "live", name, body)
+	}
+
+	snap, err := Snapshot(root, "live")
+	if err != nil {
+		t.Fatal(err)
+	}
+	if snap.NextCommands.Verb != "seal" || snap.NextCommand != "/rite-seal" {
+		t.Fatalf("next commands=%+v legacy=%q, want canonical next_action seal", snap.NextCommands, snap.NextCommand)
+	}
+	if got := strings.Join(snap.Warnings, "\n"); !strings.Contains(got, "requires fresh evidence") {
+		t.Fatalf("warnings=%v, want missing required-proof warning", snap.Warnings)
+	}
+}
+
 func TestWorkLayoutIsCanonicalAndFeaturesIsAlias(t *testing.T) {
 	root := filepath.Join(t.TempDir(), ".devrites")
 	writeWorkSection(t, root, "live", "state.md", "- Phase: build\n")
@@ -148,9 +194,8 @@ func TestWorkLayoutIsCanonicalAndFeaturesIsAlias(t *testing.T) {
 	}
 }
 
-// An unknown phase word in the ledger is ignored (not accepted as a phase), so a
-// ledger-only feature with no recognizable phase is a clear error, not a silent
-// mis-load.
+// An unknown phase word in the ledger is rejected, so a ledger-only feature is a
+// clear error rather than silently falling back or mis-loading.
 func TestLedgerPhaseRejectsUnknownWord(t *testing.T) {
 	root := filepath.Join(t.TempDir(), ".devrites")
 	writeSection(t, root, "bogus", "state.md", "- Phase: banana\n")