devrites 3.2.28 → 4.0.0

package/engine/internal/state/cursor_test.go

@@ -97,3 +97,60 @@ func TestUpsertAndDeleteCursorFieldStayInsideCursorTable(t *testing.T) {
 		t.Fatalf("DeleteCursorField left return phase:\n%s", strings.Join(lines, "\n"))
 	}
 }
+
+func TestCursorHelpersIgnoreFencedExamples(t *testing.T) {
+	lines := strings.Split(`# State
+
+~~~md
+## Cursor
+| Key | Value |
+| --- | --- |
+| status | example |
+~~~
+
+## Cursor
+| Key | Value |
+| --- | --- |
+| phase | build |
+| status | running |`, "\n")
+
+	if got, ok := CursorField(lines, CursorStatus); !ok || got != "running" {
+		t.Fatalf("CursorField(status) = %q, %v; want running, true", got, ok)
+	}
+	lines, ok := SetCursorField(lines, CursorStatus, "complete")
+	if !ok || lines[6] != "| status | example |" || lines[13] != "| status | complete |" {
+		t.Fatalf("SetCursorField changed the wrong line:\n%s", strings.Join(lines, "\n"))
+	}
+	lines = UpsertCursorField(lines, CursorReturnPhase, "build")
+	if lines[6] != "| status | example |" {
+		t.Fatalf("UpsertCursorField changed fenced content:\n%s", strings.Join(lines, "\n"))
+	}
+	lines = DeleteCursorField(lines, CursorStatus)
+	if lines[6] != "| status | example |" {
+		t.Fatalf("DeleteCursorField changed fenced content:\n%s", strings.Join(lines, "\n"))
+	}
+	if _, ok := CursorField(lines, CursorStatus); ok {
+		t.Fatalf("DeleteCursorField left an authoritative status:\n%s", strings.Join(lines, "\n"))
+	}
+}
+
+func TestCursorHelpersRejectCorruptTextWithoutMutation(t *testing.T) {
+	for _, lines := range [][]string{
+		{"| status | run\x00ning |"},
+		{"| status | run\xffning |"},
+	} {
+		original := strings.Join(lines, "\n")
+		if value, ok := CursorField(lines, CursorStatus); ok || value != "" {
+			t.Fatalf("CursorField(corrupt) = %q, %v", value, ok)
+		}
+		if got, ok := SetCursorField(lines, CursorStatus, "complete"); ok || strings.Join(got, "\n") != original {
+			t.Fatalf("SetCursorField(corrupt) = %q, %v", got, ok)
+		}
+		if got := UpsertCursorField(lines, CursorStatus, "complete"); strings.Join(got, "\n") != original {
+			t.Fatalf("UpsertCursorField(corrupt) mutated input: %q", got)
+		}
+		if got := DeleteCursorField(lines, CursorStatus); strings.Join(got, "\n") != original {
+			t.Fatalf("DeleteCursorField(corrupt) mutated input: %q", got)
+		}
+	}
+}

package/engine/internal/state/feature.go

@@ -6,10 +6,10 @@ import (
 	"os"
 	"path/filepath"
 	"sort"
-	"strconv"
 	"strings"
 
 	"github.com/devrites/devrites/internal/devritespaths"
+	"github.com/devrites/devrites/internal/markdowntext"
 	"github.com/devrites/devrites/internal/rootfacts"
 )
 
@@ -31,124 +31,68 @@ type Feature struct {
 	Phase        Phase
 	Present      map[Section]bool
 	PresentFiles map[string]bool
-	LegacyLayout bool
 }
 
-// featureDir is where per-feature state lives under the root. work/ is the
-// canonical layout; features/ remains readable as a compatibility alias.
+// featureDir is the canonical per-feature state directory under root.
 func featureDir(root, slug string) string {
 	return devritespaths.FeatureDir(root, slug)
 }
 
-// ListFeatures returns the slugs of every feature under root: directories under
-// canonical work/ plus compatibility features/ recognized as a feature: sorted.
-// A directory is a feature if it has a workspace map OR the working-state
-// ledger (state.md), so a live workspace the pack created without a map
-// still lists. Missing layout directories yield an empty list, not an error.
+// ListFeatures returns sorted slugs for canonical work/ directories that carry
+// the state.md ledger. Missing work/ yields an empty list, not an error.
 func ListFeatures(root string) ([]string, error) {
-	seen := map[string]bool{}
-	for _, layout := range []string{"work", "features"} {
-		entries, err := os.ReadDir(filepath.Join(root, layout))
-		if errors.Is(err, os.ErrNotExist) {
-			continue
-		}
-		if err != nil {
-			return nil, fmt.Errorf("list features: %w", err)
-		}
-		for _, e := range entries {
-			if !e.IsDir() {
-				continue
-			}
-			if isFeatureDir(filepath.Join(root, layout, e.Name())) {
-				seen[e.Name()] = true
-			}
-		}
+	entries, err := os.ReadDir(filepath.Join(root, "work"))
+	if errors.Is(err, os.ErrNotExist) {
+		return nil, nil
 	}
-	slugs := make([]string, 0, len(seen))
-	for slug := range seen {
-		slugs = append(slugs, slug)
+	if err != nil {
+		return nil, fmt.Errorf("list features: %w", err)
+	}
+	var slugs []string
+	for _, entry := range entries {
+		if entry.IsDir() && isFeatureDir(filepath.Join(root, "work", entry.Name())) {
+			slugs = append(slugs, entry.Name())
+		}
 	}
 	sort.Strings(slugs)
 	return slugs, nil
 }
 
-// isFeatureDir reports whether dir carries a workspace map or the working-state
-// ledger. Either is a sufficient phase source for LoadFeature.
+// isFeatureDir reports whether dir carries the canonical working-state ledger.
 func isFeatureDir(dir string) bool {
-	if regularFileExists(filepath.Join(dir, LedgerFile)) {
-		return true
-	}
-	for _, name := range workspaceMapFiles {
-		if regularFileExists(filepath.Join(dir, name)) {
-			return true
-		}
-	}
-	return false
+	return regularFileExists(filepath.Join(dir, LedgerFile))
 }
 
+// IsFeatureDir exposes the runtime discovery predicate to repository validators.
+func IsFeatureDir(dir string) bool { return isFeatureDir(dir) }
+
 func regularFileExists(path string) bool {
-	info, err := os.Stat(path)
+	info, err := os.Lstat(path)
 	return err == nil && info.Mode().IsRegular()
 }
 
-// LoadFeature reads feature <slug> under root. The phase comes from the live
-// working-state ledger when it declares one, otherwise from workspace-map
-// frontmatter. A feature with neither a map nor a ledger does not exist.
-// Section content is read from the canonical section files or their
-// aliases (see sectionFiles).
+// LoadFeature reads a canonical feature workspace. state.md is the sole
+// lifecycle authority; optional README.md metadata is not runtime state.
 func LoadFeature(root, slug string) (*Feature, error) {
 	dir := featureDir(root, slug)
-
-	var manifest []byte
-	for _, name := range workspaceMapFiles {
-		data, err := os.ReadFile(filepath.Join(dir, name))
-		if err == nil {
-			manifest = data
-			break
-		}
-		if !errors.Is(err, os.ErrNotExist) {
-			return nil, fmt.Errorf("feature %q: read %s: %w", slug, name, err)
-		}
-	}
-	hasManifest := manifest != nil
-	hasLedger := regularFileExists(filepath.Join(dir, LedgerFile))
-	if !hasManifest && !hasLedger {
+	if !regularFileExists(filepath.Join(dir, LedgerFile)) {
 		return nil, fmt.Errorf("feature %q not found", slug)
 	}
 
-	var manifestPhase Phase
-	if hasManifest {
-		fm, _ := splitFrontmatter(manifest)
-		if v := strings.TrimSpace(fm["schemaVersion"]); v != "" {
-			n, err := strconv.Atoi(v)
-			if err != nil {
-				return nil, fmt.Errorf("feature %q: invalid schemaVersion %q", slug, v)
-			}
-			if n > SchemaVersion {
-				return nil, fmt.Errorf("feature %q: schemaVersion %d is newer than this engine supports (%d); upgrade devrites", slug, n, SchemaVersion)
-			}
-		}
-		manifestPhase = Phase(strings.TrimSpace(fm["phase"]))
+	phase, ledgerDeclared, err := declaredPhaseFromLedger(filepath.Join(dir, LedgerFile))
+	if err != nil {
+		return nil, fmt.Errorf("feature %q: %w", slug, err)
 	}
-
-	// 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 workspace-map frontmatter or %s ledger", slug, LedgerFile)
+		return nil, fmt.Errorf("feature %q: no phase in %s ledger", slug, LedgerFile)
 	}
 	if !KnownPhase(phase) {
 		return nil, fmt.Errorf("feature %q: unknown phase %q", slug, phase)
 	}
 
 	present := make(map[Section]bool, len(Sections))
-	for _, s := range Sections {
-		present[s] = sectionPresentAny(dir, s)
+	for _, section := range Sections {
+		present[section] = sectionPresentAny(dir, section)
 	}
 	presentFiles := make(map[string]bool)
 	for _, name := range WorkspaceFiles() {
@@ -159,12 +103,9 @@ func LoadFeature(root, slug string) (*Feature, error) {
 		Phase:        phase,
 		Present:      present,
 		PresentFiles: presentFiles,
-		LegacyLayout: filepath.Clean(dir) == filepath.Clean(filepath.Join(root, "features", slug)),
 	}, nil
 }
 
-// sectionPresentAny reports whether any file that can satisfy section s has real
-// content: the canonical name or a transitional alias.
 func sectionPresentAny(dir string, s Section) bool {
 	for _, name := range sectionFiles[s] {
 		if sectionPresent(filepath.Join(dir, name)) {
@@ -174,62 +115,40 @@ func sectionPresentAny(dir string, s Section) bool {
 	return false
 }
 
-func declaredPhaseFromLedger(path string) (Phase, bool) {
+func declaredPhaseFromLedger(path string) (Phase, bool, error) {
 	raw, err := os.ReadFile(path)
 	if err != nil {
-		return "", false
+		if errors.Is(err, os.ErrNotExist) {
+			return "", false, nil
+		}
+		return "", false, fmt.Errorf("read %s: %w", LedgerFile, err)
 	}
-	value, ok := CursorField(strings.Split(string(raw), "\n"), CursorPhase)
-	if !ok {
-		return "", false
+	structural, err := markdowntext.Structural(raw)
+	if err != nil {
+		return "", false, fmt.Errorf("read %s: %w", LedgerFile, err)
 	}
-	word := strings.ToLower(strings.TrimSpace(value))
-	if i := strings.IndexAny(word, " \t"); i > 0 {
-		word = word[:i]
+	lines := strings.Split(string(structural), "\n")
+	value, ok := CursorField(lines, CursorPhase)
+	if !ok {
+		return "", false, nil
 	}
-	return Phase(word), true
-}
-
-// ReadDeclaredSchemaVersion returns the schemaVersion from feature.md
-// frontmatter, or 0 if the file, frontmatter, or field is missing or invalid.
-// Unlike LoadFeature, it returns newer versions so doctor can report the skew.
-func ReadDeclaredSchemaVersion(root, slug string) int {
-	dir := featureDir(root, slug)
-	for _, name := range workspaceMapFiles {
-		raw, err := os.ReadFile(filepath.Join(dir, name))
-		if err != nil {
-			continue
-		}
-		fm, _ := splitFrontmatter(raw)
-		n, err := strconv.Atoi(strings.TrimSpace(fm["schemaVersion"]))
-		if err == nil {
-			return n
-		}
+	word := firstPhaseWord(value)
+	if phase, known := PhaseForName(word); known {
+		return phase, true, nil
 	}
-	return 0
+	return Phase(word), true, nil
 }
 
-// MaxDeclaredSchemaVersion returns the highest schemaVersion declared by any
-// feature under root, or 0 when no feature declares one. It is how doctor reports
-// the "state" leg of the version triangle.
-func MaxDeclaredSchemaVersion(root string) (int, error) {
-	slugs, err := ListFeatures(root)
-	if err != nil {
-		return 0, fmt.Errorf("resolve max schema version: %w", err)
-	}
-	max := 0
-	for _, slug := range slugs {
-		if v := ReadDeclaredSchemaVersion(root, slug); v > max {
-			max = v
-		}
+func firstPhaseWord(value string) string {
+	word := strings.ToLower(strings.TrimSpace(value))
+	if i := strings.IndexAny(word, " 	"); i > 0 {
+		word = word[:i]
 	}
-	return max, nil
+	return word
 }
 
-// blankOrHash reports whether a trimmed line carries no meaningful content:
-// it is empty or starts with '#' (a Markdown ATX heading, or a comment inside a
-// frontmatter block). Both the section-content scan and the frontmatter parser
-// skip such lines.
+// blankOrHash reports whether a trimmed line carries no meaningful content: it
+// is empty or starts with '#' (a Markdown ATX heading).
 func blankOrHash(trimmed string) bool {
 	return trimmed == "" || strings.HasPrefix(trimmed, "#")
 }
@@ -243,7 +162,10 @@ func sectionPresent(path string) bool {
 	if err != nil {
 		return false
 	}
-	_, body := splitFrontmatter(raw)
+	if _, err := markdowntext.Structural(raw); err != nil {
+		return false
+	}
+	body := stripFrontmatter(raw)
 	for _, line := range strings.Split(string(body), "\n") {
 		if !blankOrHash(strings.TrimSpace(line)) {
 			return true
@@ -252,16 +174,13 @@ func sectionPresent(path string) bool {
 	return false
 }
 
-// splitFrontmatter separates a leading `---\n ... \n---\n` block from the body.
-// The closing fence must be a line that is exactly `---` (so a `----` rule or a
-// `--- note` line in the body is never mistaken for it). It parses only flat
-// `key: value` scalars (no third-party YAML dependency). With no well-formed
-// block the map is empty and body is the original input.
-func splitFrontmatter(raw []byte) (map[string]string, []byte) {
-	fm := map[string]string{}
+// stripFrontmatter removes a well-formed leading frontmatter block when
+// determining whether an artifact contains substantive body content. The
+// closing fence must be a line that is exactly `---`.
+func stripFrontmatter(raw []byte) []byte {
 	norm := strings.ReplaceAll(string(raw), "\r\n", "\n")
 	if !strings.HasPrefix(norm, "---\n") {
-		return fm, raw
+		return raw
 	}
 	lines := strings.Split(norm[len("---\n"):], "\n")
 	end := -1
@@ -272,16 +191,7 @@ func splitFrontmatter(raw []byte) (map[string]string, []byte) {
 		}
 	}
 	if end < 0 {
-		return fm, raw // no closing fence: treat as if there were no frontmatter
-	}
-	for _, line := range lines[:end] {
-		t := strings.TrimSpace(line)
-		if blankOrHash(t) {
-			continue
-		}
-		if k, v, ok := strings.Cut(t, ":"); ok {
-			fm[strings.TrimSpace(k)] = strings.Trim(strings.TrimSpace(v), `"'`)
-		}
+		return raw // no closing fence: treat as if there were no frontmatter
 	}
-	return fm, []byte(strings.Join(lines[end+1:], "\n"))
+	return []byte(strings.Join(lines[end+1:], "\n"))
 }

package/engine/internal/state/schema.go

@@ -2,23 +2,10 @@ package state
 
 //go:generate go run ./cmd/workflowmanifest -out workflow_manifest.json
 
-// SchemaVersion is the .devrites state-schema version this engine understands.
-// A workspace map may declare its own schemaVersion in frontmatter; the engine
-// refuses a version newer than this (see LoadFeature) and otherwise reads the
-// files, which evolve additively.
+// SchemaVersion versions the persisted workflow/state manifest.
 const SchemaVersion = 2
 
-const (
-	WorkspaceMapFile = "README.md"
-	EvidenceFile     = "evidence.md"
-)
-
-var workspaceMapFiles = []string{WorkspaceMapFile, "feature.md", "index.md"}
-
-// WorkspaceMapFiles returns the canonical workspace map followed by readable aliases.
-func WorkspaceMapFiles() []string {
-	return append([]string(nil), workspaceMapFiles...)
-}
+const EvidenceFile = "evidence.md"
 
 // Section is one single-purpose completeness file in a feature directory. Small
 // files use less context and make missing content easier to spot.
@@ -43,24 +30,19 @@ var Sections = []Section{
 	SectionStatus,
 }
 
-// sectionFiles lists the filenames that can satisfy each section, canonical name
-// first, then supported aliases: the same mapping `devrites-engine migrate`
-// normalizes (proof→evidence, status→state). A section
-// counts as present if any of its files has real content, so the engine reads a
-// live workspace before the pack sweep converges the filenames. The workspace
-// map is not a section; it is handled separately in LoadFeature.
+// sectionFiles maps each completeness section to its one canonical file.
 var sectionFiles = map[Section][]string{
 	SectionSpec:      {"spec.md"},
 	SectionPlan:      {"plan.md"},
 	SectionDecisions: {"decisions.md"},
 	SectionTasks:     {"tasks.md"},
-	SectionProof:     {EvidenceFile, "proof.md"},
-	SectionStatus:    {"state.md", "status.md"},
+	SectionProof:     {EvidenceFile},
+	SectionStatus:    {LedgerFile},
 }
 
-// LedgerFile is the working-state ledger the live pack writes. It carries the
-// phase in its canonical cursor table (legacy "- Phase: <p>" remains readable)
-// when no workspace map declares one, and it satisfies the status section.
+// LedgerFile is the working-state ledger the live pack writes. It is the phase
+// authority through either the canonical cursor table or the released bullet
+// form ("- Phase: <p>"), and it satisfies the status section.
 const LedgerFile = "state.md"
 
 // Phase is a workflow state. The order mirrors the rite-* arc.
@@ -92,7 +74,6 @@ type phaseDefinition struct {
 	resumeVerb          string
 	transitionRight     string
 	required            []Section
-	aliases             []string
 	workspaceRequired   []string
 	proofRequired       bool
 	blocksOpenQuestions bool
@@ -112,6 +93,7 @@ var (
 	workspacePlan    = append(append([]string(nil), workspaceClarify...), "architecture.md", "plan.md", "tasks.md", "traceability.md")
 	workspaceVetted  = append(append([]string(nil), workspacePlan...), "eng-review.md", "test-plan.md")
 	workspaceProof   = append(append([]string(nil), workspaceVetted...), "evidence.md", "touched-files.md")
+	workspaceFinal   = append(append([]string(nil), workspaceProof...), "review.md", "seal.md")
 )
 
 // Completeness is phase-relative: a section not yet required (e.g. proof during
@@ -119,20 +101,20 @@ var (
 // authoring; Plan is the approved/repaired checkpoint that resumes at Vet.
 var phaseDefinitions = []phaseDefinition{
 	{phase: PhaseFrame, resumeVerb: "frame", transitionRight: "Frame an unstructured request before lifecycle work.", workspaceRequired: workspaceFrame},
-	{phase: PhaseSpec, resumeVerb: "spec", transitionRight: "Author the product specification.", required: sectionsSpec, aliases: []string{"specced", "specifying"}, workspaceRequired: workspaceSpec},
-	{phase: PhaseClarify, resumeVerb: "clarify", transitionRight: "Close decision coverage in the written specification.", required: sectionsSpec, aliases: []string{"clarified", "clarifying"}, workspaceRequired: workspaceClarify, blocksOpenQuestions: true},
-	{phase: PhaseTemper, resumeVerb: "temper", transitionRight: "Optionally challenge the clarified specification strategy.", required: sectionsSpec, aliases: []string{"tempered", "tempering"}, workspaceRequired: workspaceClarify, blocksOpenQuestions: true},
-	{phase: PhaseDefine, resumeVerb: "define", transitionRight: "Author and approve the initial implementation plan.", required: sectionsPlan, aliases: []string{"defined", "defining"}, workspaceRequired: workspacePlan, blocksOpenQuestions: true},
-	{phase: PhasePlan, resumeVerb: "vet", transitionRight: "Hold the approved or repaired plan checkpoint for engineering review.", required: sectionsPlan, aliases: []string{"planned", "planning"}, workspaceRequired: workspacePlan, blocksOpenQuestions: true},
-	{phase: PhaseVet, resumeVerb: "vet", transitionRight: "Review implementation readiness before build.", required: sectionsBuild, aliases: []string{"vetted", "vetting"}, workspaceRequired: workspaceVetted, blocksOpenQuestions: true},
-	{phase: PhaseBuild, resumeVerb: "build", transitionRight: "Implement the next approved vertical slice.", required: sectionsBuild, aliases: []string{"building", "wip", "in", "in-progress"}, workspaceRequired: workspaceVetted, blocksOpenQuestions: true},
-	{phase: PhaseConverge, resumeVerb: "converge", transitionRight: "Recover unmet clarified intent into new slices.", required: sectionsBuild, aliases: []string{"converged", "converging"}, workspaceRequired: workspaceVetted, blocksOpenQuestions: true},
-	{phase: PhaseProve, resumeVerb: "prove", transitionRight: "Produce acceptance evidence for the implementation.", required: sectionsProof, aliases: []string{"proving", "proven", "testing"}, workspaceRequired: workspaceProof, proofRequired: true, blocksOpenQuestions: true},
-	{phase: PhasePolish, resumeVerb: "polish", transitionRight: "Apply the bounded quality pass.", required: sectionsProof, aliases: []string{"polished", "polishing"}, workspaceRequired: workspaceProof, proofRequired: true, blocksOpenQuestions: true},
-	{phase: PhaseReview, resumeVerb: "review", transitionRight: "Review the proven implementation.", required: sectionsProof, aliases: []string{"reviewed", "reviewing"}, workspaceRequired: workspaceProof, proofRequired: true, blocksOpenQuestions: true},
-	{phase: PhaseSeal, resumeVerb: "seal", transitionRight: "Decide the final GO or NO-GO.", required: sectionsComplete, aliases: []string{"sealed", "sealing"}, workspaceRequired: workspaceProof, proofRequired: true, blocksOpenQuestions: true, shippable: true},
-	{phase: PhaseShip, resumeVerb: "ship", transitionRight: "Perform authorized release and close-out mutations.", required: sectionsComplete, aliases: []string{"shipped", "shipping"}, workspaceRequired: workspaceProof, proofRequired: true, blocksOpenQuestions: true, shippable: true},
-	{phase: PhaseDone, transitionRight: "Represent archived completion with no resume command.", required: sectionsComplete, aliases: []string{"closed", "complete", "completed"}, workspaceRequired: workspaceProof, proofRequired: true, blocksOpenQuestions: true, shippable: true},
+	{phase: PhaseSpec, resumeVerb: "spec", transitionRight: "Author the product specification.", required: sectionsSpec, workspaceRequired: workspaceSpec},
+	{phase: PhaseClarify, resumeVerb: "clarify", transitionRight: "Close decision coverage in the written specification.", required: sectionsSpec, workspaceRequired: workspaceClarify, blocksOpenQuestions: true},
+	{phase: PhaseTemper, resumeVerb: "temper", transitionRight: "Optionally challenge the clarified specification strategy.", required: sectionsSpec, workspaceRequired: workspaceClarify, blocksOpenQuestions: true},
+	{phase: PhaseDefine, resumeVerb: "define", transitionRight: "Author and approve the initial implementation plan.", required: sectionsPlan, workspaceRequired: workspacePlan, blocksOpenQuestions: true},
+	{phase: PhasePlan, resumeVerb: "vet", transitionRight: "Hold the approved or repaired plan checkpoint for engineering review.", required: sectionsPlan, workspaceRequired: workspacePlan, blocksOpenQuestions: true},
+	{phase: PhaseVet, resumeVerb: "vet", transitionRight: "Review implementation readiness before build.", required: sectionsBuild, workspaceRequired: workspaceVetted, blocksOpenQuestions: true},
+	{phase: PhaseBuild, resumeVerb: "build", transitionRight: "Implement the next approved vertical slice.", required: sectionsBuild, workspaceRequired: workspaceVetted, blocksOpenQuestions: true},
+	{phase: PhaseConverge, resumeVerb: "converge", transitionRight: "Recover unmet clarified intent into new slices.", required: sectionsBuild, workspaceRequired: workspaceVetted, blocksOpenQuestions: true},
+	{phase: PhaseProve, resumeVerb: "prove", transitionRight: "Produce acceptance evidence for the implementation.", required: sectionsProof, workspaceRequired: workspaceProof, proofRequired: true, blocksOpenQuestions: true},
+	{phase: PhasePolish, resumeVerb: "polish", transitionRight: "Apply the bounded quality pass.", required: sectionsProof, workspaceRequired: workspaceProof, proofRequired: true, blocksOpenQuestions: true},
+	{phase: PhaseReview, resumeVerb: "review", transitionRight: "Review the proven implementation.", required: sectionsProof, workspaceRequired: workspaceProof, proofRequired: true, blocksOpenQuestions: true},
+	{phase: PhaseSeal, resumeVerb: "seal", transitionRight: "Decide the final GO or NO-GO.", required: sectionsComplete, workspaceRequired: workspaceFinal, proofRequired: true, blocksOpenQuestions: true, shippable: true},
+	{phase: PhaseShip, resumeVerb: "ship", transitionRight: "Perform authorized release and close-out mutations.", required: sectionsComplete, workspaceRequired: workspaceFinal, proofRequired: true, blocksOpenQuestions: true, shippable: true},
+	{phase: PhaseDone, transitionRight: "Represent archived completion with no resume command.", required: sectionsComplete, workspaceRequired: workspaceFinal, proofRequired: true, blocksOpenQuestions: true, shippable: true},
 }
 
 // WorkflowPhase is the read-only cross-format view used to generate the compact
@@ -141,7 +123,6 @@ type WorkflowPhase struct {
 	ID                  Phase     `json:"id"`
 	ResumeVerb          string    `json:"resumeVerb,omitempty"`
 	TransitionRight     string    `json:"transitionRight"`
-	Aliases             []string  `json:"aliases,omitempty"`
 	RequiredSections    []Section `json:"requiredSections,omitempty"`
 	WorkspaceRequired   []string  `json:"workspaceRequired"`
 	ProofRequired       bool      `json:"proofRequired,omitempty"`
@@ -174,7 +155,6 @@ func WorkflowPhases() []WorkflowPhase {
 			ID:                  definition.phase,
 			ResumeVerb:          definition.resumeVerb,
 			TransitionRight:     definition.transitionRight,
-			Aliases:             append([]string(nil), definition.aliases...),
 			RequiredSections:    append([]Section(nil), definition.required...),
 			WorkspaceRequired:   append([]string(nil), definition.workspaceRequired...),
 			ProofRequired:       definition.proofRequired,
@@ -226,18 +206,12 @@ func ShippablePhase(p Phase) bool {
 	return ok && definition.shippable
 }
 
-// PhaseForName resolves a canonical phase ID or compatibility alias. Callers
-// should normalize surrounding syntax before querying it.
+// PhaseForName resolves a canonical phase ID.
 func PhaseForName(name string) (Phase, bool) {
 	for _, definition := range phaseDefinitions {
 		if string(definition.phase) == name {
 			return definition.phase, true
 		}
-		for _, alias := range definition.aliases {
-			if alias == name {
-				return definition.phase, true
-			}
-		}
 	}
 	return "", false
 }