devrites 3.0.2 → 3.0.4

package/engine/internal/migrate/migrate_test.go

@@ -1,6 +1,7 @@
 package migrate
 
 import (
+	"os"
 	"path/filepath"
 	"strings"
 	"testing"
@@ -33,8 +34,11 @@ func TestRunNormalizesCanonicalWorkLayout(t *testing.T) {
 	}
 
 	assertFile(t, root, "work/alpha/spec.md", "spec\n")
-	assertFile(t, root, "work/alpha/proof.md", "proof\n")
-	assertFile(t, root, "work/alpha/status.md", "status: done - shipped\n")
+	assertFile(t, root, "work/alpha/evidence.md", "proof\n")
+	assertFile(t, root, "work/alpha/state.md", "status: done - shipped\n")
+	assertFileContains(t, root, "work/alpha/README.md", "phase: done")
+	assertMissing(t, root, "work/alpha/proof.md")
+	assertMissing(t, root, "work/alpha/status.md")
 	assertFile(t, root, "work/alpha/review.md", "review\n")
 
 	f, err := state.LoadFeature(root, "alpha")
@@ -57,8 +61,9 @@ func TestRunNormalizesCanonicalWorkLayout(t *testing.T) {
 
 func TestRunNormalizesLiveFeatureAliases(t *testing.T) {
 	root := t.TempDir()
-	testutil.WriteFile(t, filepath.Join(root, "features/beta/state.md"), "- Phase: prove\n")
-	testutil.WriteFile(t, filepath.Join(root, "features/beta/evidence.md"), "evidence\n")
+	testutil.WriteFile(t, filepath.Join(root, "features/beta/feature.md"), "# Beta\n")
+	testutil.WriteFile(t, filepath.Join(root, "features/beta/status.md"), "- Phase: prove\n")
+	testutil.WriteFile(t, filepath.Join(root, "features/beta/proof.md"), "evidence\n")
 
 	res, err := Run(root)
 	if err != nil {
@@ -67,6 +72,9 @@ func TestRunNormalizesLiveFeatureAliases(t *testing.T) {
 	if got := strings.Join(res.Migrated, ","); got != "beta" {
 		t.Fatalf("Run normalized=%q, want beta", got)
 	}
+	assertFile(t, root, "features/beta/README.md", "# Beta\n")
+	assertFile(t, root, "features/beta/state.md", "- Phase: prove\n")
+	assertFile(t, root, "features/beta/evidence.md", "evidence\n")
 	assertFile(t, root, "features/beta/status.md", "- Phase: prove\n")
 	assertFile(t, root, "features/beta/proof.md", "evidence\n")
 
@@ -80,6 +88,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 +102,6 @@ func TestMapLegacyPhase(t *testing.T) {
 	}{
 		{word: "specced", want: state.PhaseSpec, ok: true},
 		{word: "in-progress", want: state.PhaseBuild, 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"},
@@ -105,3 +119,17 @@ func assertFile(t *testing.T, root, rel, want string) {
 		t.Fatalf("%s=%q, want %q", rel, got, want)
 	}
 }
+
+func assertFileContains(t *testing.T, root, rel, want string) {
+	t.Helper()
+	if got := testutil.ReadFile(t, filepath.Join(root, rel)); !strings.Contains(got, want) {
+		t.Fatalf("%s=%q, want it to contain %q", rel, got, want)
+	}
+}
+
+func assertMissing(t *testing.T, root, rel string) {
+	t.Helper()
+	if _, err := os.Stat(filepath.Join(root, rel)); !os.IsNotExist(err) {
+		t.Fatalf("%s exists or stat failed with %v, want missing", rel, err)
+	}
+}

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)
+}

package/engine/internal/state/cursor.go

@@ -1,10 +1,48 @@
 package state
 
 import (
+	"sort"
 	"strings"
 	"unicode"
 )
 
+// Canonical cursor keys. Callers use these constants so schema spelling changes
+// remain local to the cursor package; normalizeCursorKey still accepts legacy
+// presentation aliases at the text boundary.
+const (
+	CursorPhase              = "phase"
+	CursorStatus             = "status"
+	CursorNextAction         = "next_action"
+	CursorQuestionID         = "question_id"
+	CursorActiveSlice        = "active_slice"
+	CursorAFKSlicesRemaining = "afk_slices_remaining"
+)
+
+var cursorKeyAliases = map[string]string{
+	"nextstep": CursorNextAction,
+	"qid":      CursorQuestionID,
+}
+
+// CursorKeyAlias is the generated-manifest view of a compatibility key.
+type CursorKeyAlias struct {
+	Alias     string `json:"alias"`
+	Canonical string `json:"canonical"`
+}
+
+// CursorKeyAliases returns compatibility keys in deterministic order.
+func CursorKeyAliases() []CursorKeyAlias {
+	aliases := make([]string, 0, len(cursorKeyAliases))
+	for alias := range cursorKeyAliases {
+		aliases = append(aliases, alias)
+	}
+	sort.Strings(aliases)
+	out := make([]CursorKeyAlias, 0, len(aliases))
+	for _, alias := range aliases {
+		out = append(out, CursorKeyAlias{Alias: alias, Canonical: cursorKeyAliases[alias]})
+	}
+	return out
+}
+
 type cursorLineKind uint8
 
 const (
@@ -73,12 +111,9 @@ func normalizeCursorKey(key string) string {
 			b.WriteRune(r)
 		}
 	}
-	switch b.String() {
-	case "nextstep":
-		return "nextaction"
-	case "qid":
-		return "questionid"
-	default:
-		return b.String()
+	normalized := b.String()
+	if canonical, ok := cursorKeyAliases[normalized]; ok {
+		return normalizeCursorKey(canonical)
 	}
+	return normalized
 }

package/engine/internal/state/feature.go

@@ -66,8 +66,8 @@ func featureDir(root, slug string) string {
 
 // 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 manifest (feature.md) OR the working-state
-// ledger (state.md), so a live workspace the pack created without a manifest
+// 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.
 func ListFeatures(root string) ([]string, error) {
 	seen := map[string]bool{}
@@ -96,11 +96,18 @@ func ListFeatures(root string) ([]string, error) {
 	return slugs, nil
 }
 
-// isFeatureDir reports whether dir is a recognized feature: it carries a manifest
-// or the working-state ledger. Either is a sufficient phase source for LoadFeature.
+// isFeatureDir reports whether dir carries a workspace map or the working-state
+// ledger. Either is a sufficient phase source for LoadFeature.
 func isFeatureDir(dir string) bool {
-	return regularFileExists(filepath.Join(dir, "feature.md")) ||
-		regularFileExists(filepath.Join(dir, LedgerFile))
+	if regularFileExists(filepath.Join(dir, LedgerFile)) {
+		return true
+	}
+	for _, name := range workspaceMapFiles {
+		if regularFileExists(filepath.Join(dir, name)) {
+			return true
+		}
+	}
+	return false
 }
 
 func regularFileExists(path string) bool {
@@ -108,35 +115,26 @@ func regularFileExists(path string) bool {
 	return err == nil && info.Mode().IsRegular()
 }
 
-// CandidateFiles returns the paths that make up feature <slug>: its feature.md
-// manifest plus every file that can satisfy a section (canonical names and the
-// transitional aliases), in a stable order. Not all need exist; callers that
-// fingerprint the feature stat and hash the ones that do, so including the alias
-// names means a change to either the canonical or the alias file is detected.
-func CandidateFiles(root, slug string) []string {
-	dir := featureDir(root, slug)
-	files := []string{filepath.Join(dir, "feature.md")}
-	for _, s := range Sections {
-		for _, name := range sectionFiles[s] {
-			files = append(files, filepath.Join(dir, name))
-		}
-	}
-	return files
-}
-
 // 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
+// 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).
 func LoadFeature(root, slug string) (*Feature, error) {
 	dir := featureDir(root, slug)
 
-	manifest, mErr := os.ReadFile(filepath.Join(dir, "feature.md"))
-	if mErr != nil && !errors.Is(mErr, os.ErrNotExist) {
-		return nil, fmt.Errorf("feature %q: %w", slug, mErr)
+	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 := mErr == nil
+	hasManifest := manifest != nil
 	hasLedger := regularFileExists(filepath.Join(dir, LedgerFile))
 	if !hasManifest && !hasLedger {
 		return nil, fmt.Errorf("feature %q not found", slug)
@@ -166,7 +164,7 @@ func LoadFeature(root, slug string) (*Feature, error) {
 		phase = manifestPhase
 	}
 	if phase == "" {
-		return nil, fmt.Errorf("feature %q: no phase in feature.md frontmatter or %s ledger", slug, LedgerFile)
+		return nil, fmt.Errorf("feature %q: no phase in workspace-map frontmatter or %s ledger", slug, LedgerFile)
 	}
 	if !KnownPhase(phase) {
 		return nil, fmt.Errorf("feature %q: unknown phase %q", slug, phase)
@@ -190,22 +188,12 @@ func sectionPresentAny(dir string, s Section) bool {
 	return false
 }
 
-// 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 "", false
 	}
-	value, ok := CursorField(strings.Split(string(raw), "\n"), "phase")
+	value, ok := CursorField(strings.Split(string(raw), "\n"), CursorPhase)
 	if !ok {
 		return "", false
 	}

package/engine/internal/state/schema.go

@@ -1,11 +1,25 @@
 package state
 
+//go:generate go run ./cmd/workflowmanifest -out workflow_manifest.json
+
 // SchemaVersion is the .devrites state-schema version this engine understands.
-// A feature.md may declare its own schemaVersion in frontmatter; the engine
+// 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 (
+	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...)
+}
+
 // 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.
@@ -31,23 +45,23 @@ var Sections = []Section{
 }
 
 // sectionFiles lists the filenames that can satisfy each section, canonical name
-// first, then the transitional aliases the live pack still writes — the same
-// mapping `devrites-engine migrate` normalizes (evidence→proof, state→status). A section
+// 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 manifest
-// (feature.md) is not a section; it is handled separately in LoadFeature.
+// 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{
 	SectionSpec:      {"spec.md"},
 	SectionPlan:      {"plan.md"},
 	SectionDecisions: {"decisions.md"},
 	SectionTasks:     {"tasks.md"},
-	SectionProof:     {"proof.md", "evidence.md"},
-	SectionStatus:    {"status.md", "state.md"},
+	SectionProof:     {EvidenceFile, "proof.md"},
+	SectionStatus:    {"state.md", "status.md"},
 }
 
 // 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 feature.md manifest declares one, and it satisfies the status section.
+// when no workspace map declares one, and it satisfies the status section.
 const LedgerFile = "state.md"
 
 // Phase is a workflow state. The order mirrors the rite-* arc.
@@ -70,36 +84,149 @@ const (
 	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},
-	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},
+// 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.
+type phaseDefinition struct {
+	phase               Phase
+	resumeVerb          string
+	required            []Section
+	aliases             []string
+	workspaceRequired   []string
+	proofRequired       bool
+	blocksOpenQuestions bool
+	shippable           bool
+}
+
+var (
+	sectionsSpec     = []Section{SectionSpec}
+	sectionsPlan     = []Section{SectionSpec, SectionPlan}
+	sectionsBuild    = []Section{SectionSpec, SectionPlan, SectionDecisions, SectionTasks}
+	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")
+)
+
+// 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.
+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},
+}
+
+// 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"`
+}
+
+// WorkflowPhases returns copied metadata suitable for deterministic generation.
+func WorkflowPhases() []WorkflowPhase {
+	out := make([]WorkflowPhase, 0, len(phaseDefinitions))
+	for _, definition := range phaseDefinitions {
+		out = append(out, WorkflowPhase{
+			ID:                  definition.phase,
+			ResumeVerb:          definition.resumeVerb,
+			Aliases:             append([]string(nil), definition.aliases...),
+			WorkspaceRequired:   append([]string(nil), definition.workspaceRequired...),
+			ProofRequired:       definition.proofRequired,
+			BlocksOpenQuestions: definition.blocksOpenQuestions,
+			Shippable:           definition.shippable,
+		})
+	}
+	return out
+}
+
+// LifecyclePhases returns the ordered lifecycle. The returned slice is a copy,
+// so callers cannot mutate the registry.
+func LifecyclePhases() []Phase {
+	phases := make([]Phase, len(phaseDefinitions))
+	for i, definition := range phaseDefinitions {
+		phases[i] = definition.phase
+	}
+	return phases
+}
+
+func definitionFor(p Phase) (phaseDefinition, bool) {
+	for _, definition := range phaseDefinitions {
+		if definition.phase == p {
+			return definition, true
+		}
+	}
+	return phaseDefinition{}, false
 }
 
 // KnownPhase reports whether p is a phase the engine understands.
 func KnownPhase(p Phase) bool {
-	_, ok := requiredByPhase[p]
+	_, ok := definitionFor(p)
 	return ok
 }
 
+// ResumeVerb returns the public rite verb that resumes p. Terminal and unknown
+// phases return an empty string.
+func ResumeVerb(p Phase) string {
+	definition, ok := definitionFor(p)
+	if !ok {
+		return ""
+	}
+	return definition.resumeVerb
+}
+
+// ShippablePhase reports whether p is allowed to claim a sealed/shipped result.
+func ShippablePhase(p Phase) bool {
+	definition, ok := definitionFor(p)
+	return ok && definition.shippable
+}
+
+// PhaseForName resolves a canonical phase ID or compatibility alias. Callers
+// should normalize surrounding syntax before querying it.
+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
+}
+
 // RequiredSections returns the sections required to complete the given phase,
 // in canonical Sections order.
 func RequiredSections(p Phase) []Section {
-	want := requiredByPhase[p]
+	definition, ok := definitionFor(p)
+	if !ok {
+		return nil
+	}
+	want := definition.required
 	set := make(map[Section]bool, len(want))
 	for _, s := range want {
 		set[s] = true

package/engine/internal/state/snapshot.go

@@ -23,6 +23,7 @@ var (
 	snapshotSliceStateRe   = regexp.MustCompile(`[[:space:]]+(built|pending)[[:space:]]*$`)
 	snapshotSliceSepRe     = regexp.MustCompile(`[[:space:]]+[^[:alnum:][:space:]]+[[:space:]]*$`)
 	snapshotSliceCheckedRe = regexp.MustCompile(`\[[xX]\]`)
+	snapshotSliceHeadingRe = regexp.MustCompile(`(?m)^##[[:space:]]+(SLICE-[0-9]{3})(?:[[:space:]]+.*)?$`)
 	snapshotTouchedPathRe  = regexp.MustCompile("`([^`]+)`")
 )
 
@@ -163,13 +164,13 @@ func Snapshot(root, slug string) (*WorkspaceSnapshot, error) {
 
 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 action, ok := CursorField(strings.Split(string(raw), "\n"), CursorNextAction); ok {
 			if command := workflow.ForAction(action); command.Verb != "" {
 				return command
 			}
 		}
 	}
-	return workflow.ForPhase(string(phase))
+	return workflow.ForVerb(ResumeVerb(phase))
 }
 
 func readActiveSlug(root string) string {
@@ -191,6 +192,22 @@ func runMode(root string) string {
 }
 
 func currentSlice(workDir string) *SliceSnapshot {
+	if rawState, err := os.ReadFile(filepath.Join(workDir, LedgerFile)); err == nil {
+		if active, ok := CursorField(strings.Split(string(rawState), "\n"), CursorActiveSlice); ok {
+			fields := strings.Fields(active)
+			if len(fields) > 0 {
+				active = fields[0]
+				if rawTasks, taskErr := os.ReadFile(filepath.Join(workDir, "tasks.md")); taskErr == nil {
+					matches := snapshotSliceHeadingRe.FindAllStringSubmatch(string(rawTasks), -1)
+					for i, match := range matches {
+						if match[1] == active {
+							return &SliceSnapshot{Index: i + 1, Total: len(matches), Name: active, State: "pending"}
+						}
+					}
+				}
+			}
+		}
+	}
 	for _, name := range []string{"state.md", "tasks.md"} {
 		raw, err := os.ReadFile(filepath.Join(workDir, name))
 		if err != nil {
@@ -271,6 +288,9 @@ func driftSummary(workDir string) DriftSnapshot {
 			continue
 		}
 		open := countOpenMarkers(string(raw))
+		if name == "questions.md" {
+			open = countOpenQuestions(string(raw))
+		}
 		if open > 0 {
 			return DriftSnapshot{Status: "open", Open: open}
 		}
@@ -278,11 +298,37 @@ func driftSummary(workDir string) DriftSnapshot {
 	return DriftSnapshot{Status: "clear"}
 }
 
+func countOpenQuestions(text string) int {
+	open := 0
+	inQuestion := false
+	status := ""
+	finalize := func() {
+		if inQuestion && status == "open" {
+			open++
+		}
+	}
+	for _, line := range strings.Split(text, "\n") {
+		lower := strings.ToLower(strings.TrimSpace(line))
+		switch {
+		case strings.HasPrefix(lower, "## q-"):
+			finalize()
+			inQuestion, status = true, ""
+		case inQuestion && strings.HasPrefix(lower, "status:"):
+			status = strings.TrimSpace(strings.TrimPrefix(lower, "status:"))
+		case inQuestion && strings.HasPrefix(lower, "## "):
+			finalize()
+			inQuestion = false
+		}
+	}
+	finalize()
+	return open
+}
+
 func countOpenMarkers(text string) int {
 	open := 0
 	for _, line := range strings.Split(text, "\n") {
 		l := strings.ToLower(strings.TrimSpace(line))
-		if strings.Contains(l, "status: open") || strings.Contains(l, "- [ ]") || strings.Contains(l, "gate: blocking") {
+		if strings.Contains(l, "status: open") || strings.Contains(l, "- [ ]") {
 			open++
 		}
 	}