devrites 3.0.6 → 3.1.0

package/engine/internal/state/clarify_transition_test.go

@@ -0,0 +1,130 @@
+package state
+
+import (
+	"errors"
+	"strings"
+	"testing"
+)
+
+func TestNextClarifyCursorCases(t *testing.T) {
+	build := ClarifyCursor{Phase: PhaseBuild, Status: "running", NextAction: "/rite-build"}
+	clarify := ClarifyCursor{
+		Phase:            PhaseClarify,
+		Status:           "running",
+		NextAction:       "/rite-clarify",
+		ReturnPhase:      PhaseBuild,
+		ReturnNextAction: "/rite-build",
+		HasReturn:        true,
+	}
+	cases := []struct {
+		name    string
+		intent  ClarifyIntent
+		current ClarifyCursor
+		want    ClarifyCursor
+		wantErr bool
+	}{
+		{"enter", ClarifyEnter, build, clarify, false},
+		{"duplicate enter", ClarifyEnter, clarify, clarify, false},
+		{"too early enter", ClarifyEnter, ClarifyCursor{Phase: PhaseSpec}, ClarifyCursor{}, true},
+		{"missing restore target", ClarifyRestore, ClarifyCursor{Phase: PhaseClarify}, ClarifyCursor{Phase: PhaseClarify}, false},
+		{"invalid restore target", ClarifyRestore, ClarifyCursor{Phase: PhaseClarify, ReturnPhase: PhaseSpec, HasReturn: true}, ClarifyCursor{}, true},
+		{"restore", ClarifyRestore, clarify, build, false},
+	}
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			got, err := NextClarifyCursor(tc.intent, ClarifyTransitionInput{
+				Cursor:                  tc.current,
+				ClarifyNextAction:       "/rite-clarify",
+				DefaultReturnNextAction: "/rite-build",
+			})
+			if tc.wantErr {
+				var transitionErr *ClarifyTransitionError
+				if !errors.As(err, &transitionErr) {
+					t.Fatalf("error=%v, want ClarifyTransitionError", err)
+				}
+				return
+			}
+			if err != nil || got != tc.want {
+				t.Fatalf("NextClarifyCursor()=(%+v, %v), want %+v", got, err, tc.want)
+			}
+		})
+	}
+}
+
+func TestClarifyCursorSerializationIsByteIdempotent(t *testing.T) {
+	original := []string{
+		"# State",
+		"",
+		"## Cursor",
+		"| Key | Value |",
+		"| --- | --- |",
+		"| phase | build |",
+		"| status | running |",
+		"| next_action | /rite-build |",
+		"",
+		"Curated note stays exactly here.",
+	}
+	current, err := ParseClarifyCursor(original)
+	if err != nil {
+		t.Fatal(err)
+	}
+	entered, err := NextClarifyCursor(ClarifyEnter, ClarifyTransitionInput{
+		Cursor:                  current,
+		ClarifyNextAction:       "/rite-clarify",
+		DefaultReturnNextAction: "/rite-build",
+	})
+	if err != nil {
+		t.Fatal(err)
+	}
+	once := ApplyClarifyCursor(original, entered)
+	parsed, err := ParseClarifyCursor(once)
+	if err != nil {
+		t.Fatal(err)
+	}
+	twiceState, err := NextClarifyCursor(ClarifyEnter, ClarifyTransitionInput{
+		Cursor:                  parsed,
+		ClarifyNextAction:       "/rite-clarify",
+		DefaultReturnNextAction: "/rite-build",
+	})
+	if err != nil {
+		t.Fatal(err)
+	}
+	twice := ApplyClarifyCursor(once, twiceState)
+	if got, want := strings.Join(twice, "\n"), strings.Join(once, "\n"); got != want {
+		t.Fatalf("second serialization changed bytes:\n--- once\n%s\n--- twice\n%s", want, got)
+	}
+	if !strings.Contains(strings.Join(once, "\n"), "Curated note stays exactly here.") {
+		t.Fatal("serializer removed curated Markdown")
+	}
+
+	restored, err := NextClarifyCursor(ClarifyRestore, ClarifyTransitionInput{
+		Cursor:                  parsed,
+		ClarifyNextAction:       "/rite-clarify",
+		DefaultReturnNextAction: "/rite-build",
+	})
+	if err != nil {
+		t.Fatal(err)
+	}
+	restoreOnce := ApplyClarifyCursor(once, restored)
+	restoreParsed, err := ParseClarifyCursor(restoreOnce)
+	if err != nil {
+		t.Fatal(err)
+	}
+	restoreTwice, err := NextClarifyCursor(ClarifyRestore, ClarifyTransitionInput{Cursor: restoreParsed})
+	if err != nil {
+		t.Fatal(err)
+	}
+	if got, want := strings.Join(ApplyClarifyCursor(restoreOnce, restoreTwice), "\n"), strings.Join(restoreOnce, "\n"); got != want {
+		t.Fatalf("second restore serialization changed bytes:\n--- once\n%s\n--- twice\n%s", want, got)
+	}
+}
+
+func TestParseClarifyCursorRejectsInvalidReturnPhase(t *testing.T) {
+	_, err := ParseClarifyCursor([]string{
+		"| phase | clarify |",
+		"| return_phase | not-a-phase |",
+	})
+	if err == nil || !strings.Contains(err.Error(), "invalid return phase") {
+		t.Fatalf("error=%v, want invalid return phase", err)
+	}
+}

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

@@ -18,15 +18,19 @@ func main() {
 	flag.Parse()
 
 	document := struct {
-		GeneratedBy      string                 `json:"generatedBy"`
-		SchemaVersion    int                    `json:"schemaVersion"`
-		Phases           []state.WorkflowPhase  `json:"phases"`
-		CursorKeyAliases []state.CursorKeyAlias `json:"cursorKeyAliases"`
+		GeneratedBy         string                     `json:"generatedBy"`
+		SchemaVersion       int                        `json:"schemaVersion"`
+		AuthorityPolicy     state.AuthorityPolicy      `json:"authorityPolicy"`
+		Phases              []state.WorkflowPhase      `json:"phases"`
+		ClarifyReturnFields []state.ClarifyFieldPolicy `json:"clarifyReturnFields"`
+		CursorKeyAliases    []state.CursorKeyAlias     `json:"cursorKeyAliases"`
 	}{
-		GeneratedBy:      "go generate ./internal/state; DO NOT EDIT",
-		SchemaVersion:    state.SchemaVersion,
-		Phases:           state.WorkflowPhases(),
-		CursorKeyAliases: state.CursorKeyAliases(),
+		GeneratedBy:         "go generate ./internal/state; DO NOT EDIT",
+		SchemaVersion:       state.SchemaVersion,
+		AuthorityPolicy:     state.WorkflowAuthorityPolicy(),
+		Phases:              state.WorkflowPhases(),
+		ClarifyReturnFields: state.ClarifyFieldPolicies(),
+		CursorKeyAliases:    state.CursorKeyAliases(),
 	}
 	data, err := json.MarshalIndent(document, "", "  ")
 	if err != nil {

package/engine/internal/state/cursor.go

@@ -16,6 +16,8 @@ const (
 	CursorQuestionID         = "question_id"
 	CursorActiveSlice        = "active_slice"
 	CursorAFKSlicesRemaining = "afk_slices_remaining"
+	CursorReturnPhase        = "return_phase"
+	CursorReturnNextAction   = "return_next_action"
 )
 
 var cursorKeyAliases = map[string]string{
@@ -87,6 +89,62 @@ func SetCursorField(lines []string, key, value string) ([]string, bool) {
 	return out, false
 }
 
+// UpsertCursorField replaces key when present or inserts it into the canonical
+// cursor table (falling back to a legacy bullet when no table exists).
+func UpsertCursorField(lines []string, key, value string) []string {
+	if out, ok := SetCursorField(lines, key, value); ok {
+		return out
+	}
+	out := append([]string(nil), lines...)
+	lastTable := -1
+	inCursor := false
+	for i, line := range out {
+		trimmed := strings.TrimSpace(line)
+		if strings.HasPrefix(trimmed, "## ") {
+			if inCursor {
+				break
+			}
+			inCursor = strings.EqualFold(strings.TrimSpace(strings.TrimPrefix(trimmed, "## ")), "Cursor")
+			continue
+		}
+		if len(trimmed) >= 2 && trimmed[0] == '|' && trimmed[len(trimmed)-1] == '|' {
+			gotKey, _, kind, ok := parseCursorLine(line)
+			normalized := normalizeCursorKey(gotKey)
+			if !inCursor && ok && (normalized == normalizeCursorKey(CursorPhase) ||
+				normalized == normalizeCursorKey(CursorStatus) ||
+				normalized == normalizeCursorKey(CursorNextAction)) {
+				inCursor = true
+			}
+			if inCursor && ok && kind == cursorLineTable {
+				lastTable = i
+			}
+		}
+	}
+	if lastTable >= 0 {
+		insert := "| " + key + " | " + value + " |"
+		out = append(out, "")
+		copy(out[lastTable+2:], out[lastTable+1:])
+		out[lastTable+1] = insert
+		return out
+	}
+	return append(out, "- "+key+": "+value)
+}
+
+// DeleteCursorField removes every presentation of key from canonical or legacy
+// state without disturbing unrelated prose.
+func DeleteCursorField(lines []string, key string) []string {
+	want := normalizeCursorKey(key)
+	out := make([]string, 0, len(lines))
+	for _, line := range lines {
+		gotKey, _, _, ok := parseCursorLine(line)
+		if ok && normalizeCursorKey(gotKey) == want {
+			continue
+		}
+		out = append(out, line)
+	}
+	return out
+}
+
 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] == '|' {

package/engine/internal/state/cursor_test.go

@@ -1,6 +1,9 @@
 package state
 
-import "testing"
+import (
+	"strings"
+	"testing"
+)
 
 func TestCursorFieldReadsCanonicalTableAndLegacyLines(t *testing.T) {
 	table := []string{
@@ -56,3 +59,41 @@ func TestSetCursorFieldPreservesCanonicalAndLegacyFormats(t *testing.T) {
 		})
 	}
 }
+
+func TestUpsertAndDeleteCursorFieldStayInsideCursorTable(t *testing.T) {
+	lines := []string{
+		"# State",
+		"",
+		"## Cursor",
+		"| Key | Value |",
+		"| --- | --- |",
+		"| phase | build |",
+		"| status | running |",
+		"",
+		"## Awaiting human",
+		"| Key | Value |",
+		"| --- | --- |",
+		"| question_id | q-1 |",
+	}
+	lines = UpsertCursorField(lines, CursorReturnPhase, "build")
+	value, ok := CursorField(lines, CursorReturnPhase)
+	if !ok || value != "build" {
+		t.Fatalf("return phase=(%q,%v), want build", value, ok)
+	}
+	returnIndex, questionIndex := -1, -1
+	for i, line := range lines {
+		if strings.Contains(line, CursorReturnPhase) {
+			returnIndex = i
+		}
+		if strings.Contains(line, CursorQuestionID) {
+			questionIndex = i
+		}
+	}
+	if returnIndex < 0 || questionIndex < 0 || returnIndex > questionIndex {
+		t.Fatalf("upsert inserted outside cursor table:\n%s", strings.Join(lines, "\n"))
+	}
+	lines = DeleteCursorField(lines, CursorReturnPhase)
+	if _, ok := CursorField(lines, CursorReturnPhase); ok {
+		t.Fatalf("DeleteCursorField left return phase:\n%s", strings.Join(lines, "\n"))
+	}
+}

package/engine/internal/state/feature.go

@@ -10,52 +10,28 @@ import (
 	"strings"
 
 	"github.com/devrites/devrites/internal/devritespaths"
+	"github.com/devrites/devrites/internal/rootfacts"
 )
 
 // ResolveRoot returns the .devrites directory to operate on. A non-empty
 // override (e.g. from DEVRITES_ROOT) may name either the project root or its
 // .devrites directory; otherwise the nearest ancestor .devrites is used.
 func ResolveRoot(override string) (string, error) {
-	if override != "" {
-		info, err := os.Stat(override)
-		if err != nil {
-			return "", fmt.Errorf("DEVRITES_ROOT %q: %w", override, err)
-		}
-		if !info.IsDir() {
-			return "", fmt.Errorf("DEVRITES_ROOT %q is not a directory", override)
-		}
-		if filepath.Base(filepath.Clean(override)) == ".devrites" {
-			return override, nil
-		}
-		child := filepath.Join(override, ".devrites")
-		if info, err := os.Stat(child); err == nil && info.IsDir() {
-			return child, nil
-		}
-		return "", fmt.Errorf("DEVRITES_ROOT %q is not a project root or .devrites directory", override)
-	}
-	cwd, err := os.Getwd()
+	facts, err := rootfacts.Resolve(override)
 	if err != nil {
-		return "", fmt.Errorf("resolve working directory: %w", err)
-	}
-	for dir := cwd; ; {
-		cand := filepath.Join(dir, ".devrites")
-		if info, err := os.Stat(cand); err == nil && info.IsDir() {
-			return cand, nil
-		}
-		parent := filepath.Dir(dir)
-		if parent == dir {
-			return "", errors.New("no .devrites directory found (set DEVRITES_ROOT or run inside a DevRites workspace)")
-		}
-		dir = parent
+		return "", err
 	}
+	return facts.PhysicalRoot, nil
 }
 
 // Feature is a loaded per-feature workspace: its declared phase plus which
 // completeness sections currently have real content.
 type Feature struct {
-	Slug    string
-	Phase   Phase
-	Present map[Section]bool
+	Slug         string
+	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
@@ -174,7 +150,17 @@ func LoadFeature(root, slug string) (*Feature, error) {
 	for _, s := range Sections {
 		present[s] = sectionPresentAny(dir, s)
 	}
-	return &Feature{Slug: slug, Phase: phase, Present: present}, nil
+	presentFiles := make(map[string]bool)
+	for _, name := range WorkspaceFiles() {
+		presentFiles[name] = sectionPresent(filepath.Join(dir, name))
+	}
+	return &Feature{
+		Slug:         slug,
+		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
@@ -204,22 +190,23 @@ func declaredPhaseFromLedger(path string) (Phase, bool) {
 	return Phase(word), true
 }
 
-// ReadDeclaredSchemaVersion returns the schemaVersion declared in a feature's
-// feature.md frontmatter, or 0 if the file, frontmatter, or field is
-// absent/unparseable. Unlike LoadFeature it does NOT refuse a version newer than
-// the engine supports: doctor needs to observe a newer version to report skew,
-// not fail on it.
+// 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 {
-	raw, err := os.ReadFile(filepath.Join(featureDir(root, slug), "feature.md"))
-	if err != nil {
-		return 0
-	}
-	fm, _ := splitFrontmatter(raw)
-	n, err := strconv.Atoi(strings.TrimSpace(fm["schemaVersion"]))
-	if err != nil {
-		return 0
+	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
+		}
 	}
-	return n
+	return 0
 }
 
 // MaxDeclaredSchemaVersion returns the highest schemaVersion declared by any

package/engine/internal/state/schema.go

@@ -6,7 +6,7 @@ package state
 // 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.
-const SchemaVersion = 1
+const SchemaVersion = 2
 
 const (
 	WorkspaceMapFile = "README.md"
@@ -20,9 +20,8 @@ func WorkspaceMapFiles() []string {
 	return append([]string(nil), workspaceMapFiles...)
 }
 
-// Section is one single-concern completeness file within a feature directory.
-// Splitting a feature into small files (rather than one long document) keeps
-// each file context-cheap and makes completeness self-evident.
+// Section is one single-purpose completeness file in a feature directory. Small
+// files use less context and make missing content easier to spot.
 type Section string
 
 const (
@@ -47,7 +46,7 @@ var Sections = []Section{
 // 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
+// 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.
 var sectionFiles = map[Section][]string{
@@ -70,6 +69,7 @@ type Phase string
 const (
 	PhaseFrame    Phase = "frame"    // problem framing
 	PhaseSpec     Phase = "spec"     // specification
+	PhaseClarify  Phase = "clarify"  // decision-coverage closure
 	PhaseTemper   Phase = "temper"   // strategic specification review
 	PhaseDefine   Phase = "define"   // plan definition
 	PhasePlan     Phase = "plan"     // approved plan
@@ -84,13 +84,13 @@ const (
 	PhaseDone     Phase = "done"     // archived completion
 )
 
-// phaseDefinition is the single source of truth for lifecycle order and
-// phase-specific behavior. Workflow topology is versioned application logic,
-// rather than deploy-time configuration, so keeping it typed and ordered makes
-// additions compile-visible and lets every consumer derive the same arc.
+// phaseDefinition owns lifecycle order and phase behavior. Workflow topology is
+// versioned application logic rather than deployment configuration, so the
+// compiler sees changes and every consumer derives the same ordering.
 type phaseDefinition struct {
 	phase               Phase
 	resumeVerb          string
+	transitionRight     string
 	required            []Section
 	aliases             []string
 	workspaceRequired   []string
@@ -106,43 +106,64 @@ var (
 	sectionsProof    = []Section{SectionSpec, SectionPlan, SectionDecisions, SectionTasks, SectionProof}
 	sectionsComplete = []Section{SectionSpec, SectionPlan, SectionDecisions, SectionTasks, SectionProof, SectionStatus}
 
-	workspaceFrame = []string{"state.md"}
-	workspaceSpec  = []string{"brief.md", "spec.md", "state.md", "decisions.md", "assumptions.md", "questions.md"}
-	workspacePlan  = []string{"brief.md", "spec.md", "architecture.md", "plan.md", "tasks.md", "traceability.md", "state.md", "decisions.md", "assumptions.md", "questions.md"}
-	workspaceProof = append(append([]string(nil), workspacePlan...), "evidence.md", "touched-files.md")
+	workspaceFrame   = []string{"state.md"}
+	workspaceSpec    = []string{"brief.md", "spec.md", "state.md", "decisions.md", "assumptions.md", "questions.md"}
+	workspaceClarify = append(append([]string(nil), workspaceSpec...), "decision-coverage.md")
+	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")
 )
 
 // Completeness is phase-relative: a section not yet required (e.g. proof during
-// spec) never blocks. Requirements are additive down the arc. Plan resumes at
-// define because plan is the artifact state produced by rite-define; done has no
-// resume command.
+// spec) never blocks. Requirements are additive down the arc. Define is active
+// authoring; Plan is the approved/repaired checkpoint that resumes at Vet.
 var phaseDefinitions = []phaseDefinition{
-	{phase: PhaseFrame, resumeVerb: "frame", workspaceRequired: workspaceFrame},
-	{phase: PhaseSpec, resumeVerb: "spec", required: sectionsSpec, aliases: []string{"specced", "specifying"}, workspaceRequired: workspaceSpec},
-	{phase: PhaseTemper, resumeVerb: "temper", required: sectionsSpec, aliases: []string{"tempered", "tempering"}, workspaceRequired: workspaceSpec},
-	{phase: PhaseDefine, resumeVerb: "define", required: sectionsPlan, aliases: []string{"defined", "defining"}, workspaceRequired: workspacePlan, blocksOpenQuestions: true},
-	{phase: PhasePlan, resumeVerb: "define", required: sectionsPlan, aliases: []string{"planned", "planning"}, workspaceRequired: workspacePlan, blocksOpenQuestions: true},
-	{phase: PhaseVet, resumeVerb: "vet", required: sectionsBuild, aliases: []string{"vetted", "vetting"}, workspaceRequired: workspacePlan, blocksOpenQuestions: true},
-	{phase: PhaseBuild, resumeVerb: "build", required: sectionsBuild, aliases: []string{"building", "wip", "in", "in-progress"}, workspaceRequired: workspacePlan, blocksOpenQuestions: true},
-	{phase: PhaseConverge, resumeVerb: "converge", required: sectionsBuild, aliases: []string{"converged", "converging"}, workspaceRequired: workspacePlan, blocksOpenQuestions: true},
-	{phase: PhaseProve, resumeVerb: "prove", required: sectionsProof, aliases: []string{"proving", "proven", "testing"}, workspaceRequired: workspaceProof, proofRequired: true, blocksOpenQuestions: true},
-	{phase: PhasePolish, resumeVerb: "polish", required: sectionsProof, aliases: []string{"polished", "polishing"}, workspaceRequired: workspaceProof, proofRequired: true, blocksOpenQuestions: true},
-	{phase: PhaseReview, resumeVerb: "review", required: sectionsProof, aliases: []string{"reviewed", "reviewing"}, workspaceRequired: workspaceProof, proofRequired: true, blocksOpenQuestions: true},
-	{phase: PhaseSeal, resumeVerb: "seal", required: sectionsComplete, aliases: []string{"sealed", "sealing"}, workspaceRequired: workspaceProof, proofRequired: true, blocksOpenQuestions: true, shippable: true},
-	{phase: PhaseShip, resumeVerb: "ship", required: sectionsComplete, aliases: []string{"shipped", "shipping"}, workspaceRequired: workspaceProof, proofRequired: true, blocksOpenQuestions: true, shippable: true},
-	{phase: PhaseDone, required: sectionsComplete, aliases: []string{"closed", "complete", "completed"}, workspaceRequired: workspaceProof, proofRequired: true, blocksOpenQuestions: true, shippable: true},
+	{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},
 }
 
 // WorkflowPhase is the read-only cross-format view used to generate the compact
 // manifest consumed by non-Go release tooling.
 type WorkflowPhase struct {
-	ID                  Phase    `json:"id"`
-	ResumeVerb          string   `json:"resumeVerb,omitempty"`
-	Aliases             []string `json:"aliases,omitempty"`
-	WorkspaceRequired   []string `json:"workspaceRequired"`
-	ProofRequired       bool     `json:"proofRequired,omitempty"`
-	BlocksOpenQuestions bool     `json:"blocksOpenQuestions,omitempty"`
-	Shippable           bool     `json:"shippable,omitempty"`
+	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"`
+	BlocksOpenQuestions bool      `json:"blocksOpenQuestions,omitempty"`
+	Shippable           bool      `json:"shippable,omitempty"`
+}
+
+// AuthorityPolicy owns the small cross-format trust and tracking assertions
+// that otherwise drift between current docs.
+type AuthorityPolicy struct {
+	PrinciplesTrust string   `json:"principlesTrust"`
+	TrackedState    []string `json:"trackedState"`
+	LocalState      []string `json:"localState"`
+}
+
+// WorkflowAuthorityPolicy returns copied policy metadata for the manifest.
+func WorkflowAuthorityPolicy() AuthorityPolicy {
+	return AuthorityPolicy{
+		PrinciplesTrust: "Project principles may become project policy only after explicit provenance and validation; arbitrary project-local Markdown is never inherently trusted executable instruction.",
+		TrackedState:    []string{".devrites/specs/"},
+		LocalState:      []string{".devrites/work/", ".devrites/archive/", ".devrites/ACTIVE"},
+	}
 }
 
 // WorkflowPhases returns copied metadata suitable for deterministic generation.
@@ -152,7 +173,9 @@ func WorkflowPhases() []WorkflowPhase {
 		out = append(out, 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,
 			BlocksOpenQuestions: definition.blocksOpenQuestions,
@@ -239,3 +262,33 @@ func RequiredSections(p Phase) []Section {
 	}
 	return out
 }
+
+// RequiredWorkspaceFiles returns the canonical per-file completeness contract
+// for phase p. Unlike the legacy Section view, this includes every durable
+// workflow artifact (for example decision-coverage.md and test-plan.md), so
+// runtime gates cannot silently ignore files added to the lifecycle registry.
+func RequiredWorkspaceFiles(p Phase) []string {
+	definition, ok := definitionFor(p)
+	if !ok {
+		return nil
+	}
+	return append([]string(nil), definition.workspaceRequired...)
+}
+
+// WorkspaceFiles returns every lifecycle-owned workspace filename once, in
+// first-required order. It is derived from phaseDefinitions so the runtime
+// presence model and the generated workflow manifest share one authority.
+func WorkspaceFiles() []string {
+	seen := make(map[string]bool)
+	var out []string
+	for _, definition := range phaseDefinitions {
+		for _, name := range definition.workspaceRequired {
+			if seen[name] {
+				continue
+			}
+			seen[name] = true
+			out = append(out, name)
+		}
+	}
+	return out
+}

package/engine/internal/state/snapshot.go

@@ -38,6 +38,8 @@ type WorkspaceSnapshot struct {
 	Complete        bool                 `json:"complete"`
 	Sections        []SectionSnapshot    `json:"sections"`
 	MissingSections []string             `json:"missingSections,omitempty"`
+	Files           []FileSnapshot       `json:"files"`
+	MissingFiles    []string             `json:"missingFiles,omitempty"`
 	CurrentSlice    *SliceSnapshot       `json:"currentSlice,omitempty"`
 	Evidence        EvidenceSnapshot     `json:"evidence"`
 	Drift           DriftSnapshot        `json:"drift"`
@@ -63,6 +65,12 @@ type SectionSnapshot struct {
 	Required bool   `json:"required"`
 }
 
+type FileSnapshot struct {
+	Name     string `json:"name"`
+	Present  bool   `json:"present"`
+	Required bool   `json:"required"`
+}
+
 type SliceSnapshot struct {
 	Index int    `json:"index"`
 	Total int    `json:"total"`
@@ -150,8 +158,16 @@ func Snapshot(root, slug string) (*WorkspaceSnapshot, error) {
 	for _, section := range report.Missing {
 		snap.MissingSections = append(snap.MissingSections, string(section))
 	}
-	if snap.RunMode == "AFK" && len(snap.MissingSections) > 0 {
-		snap.Warnings = append(snap.Warnings, "AFK workspace has missing required sections")
+	for _, name := range WorkspaceFiles() {
+		snap.Files = append(snap.Files, FileSnapshot{
+			Name:     name,
+			Present:  report.PresentFiles[name],
+			Required: report.RequiredFiles[name],
+		})
+	}
+	snap.MissingFiles = append(snap.MissingFiles, report.MissingFiles...)
+	if snap.RunMode == "AFK" && len(snap.MissingFiles) > 0 {
+		snap.Warnings = append(snap.Warnings, "AFK workspace has missing required files")
 	}
 	if report.Required[SectionProof] && snap.Evidence.Status != "fresh" {
 		snap.Warnings = append(snap.Warnings, "proof phase requires fresh evidence")