devrites 3.0.2 → 3.0.4

package/docs/research/go-authoritative-workflow-schema-and-quality-2026-07-20.md

@@ -0,0 +1,212 @@
+# Go Authoritative Workflow Schema and Quality Research
+
+Date: 2026-07-20
+
+## Question
+
+How should a Go CLI keep lifecycle and schema values authoritative, avoid
+shotgun changes, decide between code and configuration, safely generate
+derivatives, validate the model, and find dead or defective code?
+
+This note uses primary or first-party technical sources. Recommendations marked
+**Inference for DevRites** apply those sources to this repository.
+
+## Executive recommendation
+
+Use one typed, ordered Go registry as the authority for machine-readable
+workflow facts. A phase definition should own its stable identifier, order,
+required sections, aliases, and other phase-level policy. Consumers should ask
+the registry instead of maintaining their own phase slices, maps, or switches.
+
+Keep the registry in code, not runtime configuration: the lifecycle is versioned
+application behavior and should change with tests and a release. Generate files
+only where a second representation is genuinely required. Validate registry
+invariants in one test and make regeneration drift a CI failure.
+
+## 1. Model stable domain values as typed code
+
+Go supports defined string/numeric types with methods, typed constants, and
+related constant sets. The language specification explicitly shows defined
+types combined with constants and methods; `iota` is available for sequential
+integer sets ([Go specification: type definitions and constants](https://go.dev/ref/spec#Type_definitions),
+[Go specification: `iota`](https://go.dev/ref/spec#Iota)). Protocol Buffers uses
+the same broad shape when generating Go enums: a defined type, typed constants,
+a `String` method, and lookup metadata derived from the schema
+([Go generated code guide: enumerations](https://protobuf.dev/reference/go/go-generated/#enumerations)).
+
+**Inference for DevRites:** retain `type Phase string` because serialized state
+needs stable readable values, but make one ordered `[]PhaseDefinition` the
+machine authority. Keep named `Phase...` constants so callers remain type-safe;
+declare each serialized string only once. Derive or query all of the following
+from the registry:
+
+- known-phase validation;
+- lifecycle order and progress position;
+- required sections and proof/status requirements;
+- legacy aliases used by migration;
+- phase groups such as pre-build, proof-required, and terminal;
+- user-facing labels where labels are truly metadata.
+
+Do not replace several duplicated maps with one giant untyped map. A small
+struct gives each fact a name and lets the compiler check field types. Do not
+put unrelated constants such as filenames, parser field aliases, UI glyphs, and
+timeouts into a global `constants.go`; centralize a fact at the narrowest package
+that owns it.
+
+## 2. Code versus configuration
+
+The Twelve-Factor definition draws a useful boundary: configuration is what
+varies between deploys, while internal application configuration that does not
+vary between deploys is best kept in code
+([Twelve-Factor App: Config](https://www.12factor.net/config)).
+
+**Inference for DevRites:**
+
+| Value | Authority | Reason |
+| --- | --- | --- |
+| Phase IDs, order, required artifacts, legal aliases | Typed Go registry | Versioned product semantics; must change with tests and release |
+| Workspace state such as current phase and next action | Validated workspace data | Per-workspace mutable state |
+| Credentials, external service endpoints, machine-specific paths | Environment/CLI config | Deployment or machine variation |
+| User policy that is intentionally supported as an override | Explicit config with defaults and validation | Product feature, not an accidental escape hatch |
+
+Making the phase arc runtime-configurable would weaken compatibility guarantees
+and move failures from compile/test time to user runtime. Add configurability
+only when users have a real supported need to define a different lifecycle.
+
+## 3. Generate derivatives, never another authority
+
+The Go tool documents that `go generate` runs explicit author-defined commands,
+is **never** run automatically by `go build` or `go test`, and generated source
+should carry the standard `// Code generated ... DO NOT EDIT.` marker
+([`go generate` command documentation](https://pkg.go.dev/cmd/go#hdr-Generate_Go_files_by_processing_source)).
+The Go team also states that generated, tested source needed by clients must be
+checked into the repository
+([Go blog: Generating code](https://go.dev/blog/generate)).
+
+**Inference for DevRites:** start without a generator when all engine consumers
+can import/query the Go registry. Add a minimal stdlib generator only for
+representations that cannot consume Go directly, such as a compact machine
+manifest shipped in the skills pack or a lifecycle table in documentation.
+
+If generation is added:
+
+1. The generator reads/imports the authoritative registry; it must not parse a
+   copied list.
+2. Output is deterministic, formatted, marked generated, and checked in when
+   release consumers need it.
+3. CI runs generation and fails when `git diff --exit-code` is non-zero. This is
+   necessary because Go deliberately does not run generators during tests or
+   builds.
+4. Humans edit only the registry. Generated files say how to regenerate.
+
+Protobuf demonstrates when a separate schema language is justified: one schema
+generates typed code and lookup maps for multiple representations/languages
+([Protocol Buffers Go generated-code guide](https://protobuf.dev/reference/go/go-generated/)).
+DevRites does not need Protobuf, CUE, or JSON Schema merely to centralize a Go
+enum. Consider one only if the lifecycle becomes a cross-language public data
+contract. JSON Schema is specifically a language for annotating and validating
+JSON structure and constraints
+([JSON Schema specification](https://json-schema.org/specification)).
+
+## 4. Validate the authority, not every consumer independently
+
+The official Go testing guidance recommends table-driven tests when many cases
+share the same logic, avoiding copy-pasted tests
+([Go Wiki: Table-driven tests](https://go.dev/wiki/TableDrivenTests)). Go fuzzing
+is built into the toolchain and is intended to find edge cases humans miss
+([Go fuzzing documentation](https://go.dev/doc/security/fuzz/)).
+
+**Inference for DevRites:** add one registry-invariant test that iterates every
+definition and fails on:
+
+- an empty or duplicate phase ID;
+- an empty or duplicate alias;
+- duplicate or non-monotonic order;
+- an unknown required section;
+- a transition/group reference to an unknown phase;
+- a terminal phase with a successor;
+- a phase that should require proof/status but whose metadata says otherwise.
+
+Then keep small behavior tests at public boundaries: readiness, migration,
+progress, stop gates, and snapshots. These should consume the registry rather
+than restating the whole lifecycle as expected data. A single explicit expected
+phase list is still useful as a contract test; duplication in a test oracle is
+intentional because deriving both input and expected output from the same table
+cannot detect an accidentally missing phase.
+
+Fuzz the untrusted text boundary (cursor/state parsing), not the static registry.
+Useful properties are: parsing never panics, unknown phases remain errors,
+canonical writes round-trip, and legacy aliases normalize predictably.
+
+## 5. Prevent shotgun changes
+
+Centralization works only if consumers cannot quietly recreate the same facts.
+The minimum enforcement is architectural rather than magical:
+
+1. Put the registry and queries in the owning `state` package.
+2. Export query functions or read-only copies, not mutable global maps/slices.
+3. Replace lifecycle switches and local `[]Phase` values with registry queries.
+4. Allow consumer switches only for genuinely phase-specific behavior that
+   cannot be represented as metadata; require a default that rejects unknown
+   phases.
+5. Search CI or a focused test for duplicated full lifecycle literals in code
+   and machine templates. Do not ban phase words in prose; documentation must be
+   readable and is not executable policy.
+
+This is deliberately smaller than building a generic workflow framework. One
+data table plus a few queries solves the observed change-amplification problem.
+
+## 6. Static analysis and dead-code audit stack
+
+No single tool proves correctness. The Go `vet` documentation says it finds
+suspicious constructs missed by the compiler but uses heuristics and is not a
+firm correctness indicator ([`go vet` documentation](https://pkg.go.dev/cmd/vet)).
+The Go team's `deadcode` command builds a whole-program call graph and reports
+unreachable functions. Its `-test` flag includes test executables, and its docs
+warn that results are specific to one `GOOS`/`GOARCH`/build-tag configuration
+([`deadcode` documentation](https://pkg.go.dev/golang.org/x/tools/cmd/deadcode),
+[Go blog: Finding unreachable functions with deadcode](https://go.dev/blog/deadcode)).
+Staticcheck provides additional correctness and unused-code checks, including
+the `U1000` family ([Staticcheck checks](https://staticcheck.dev/docs/checks/)).
+`govulncheck` reports known vulnerabilities that are actually reachable through
+the program's call graph ([Go vulnerability management](https://go.dev/doc/security/vuln/)).
+
+**Recommended audit order:**
+
+```text
+go test ./...
+go vet ./...
+staticcheck ./...
+deadcode -test ./...
+govulncheck ./...
+```
+
+Run race-enabled tests for concurrency changes and a bounded fuzz job for state
+parsers. Run `deadcode` for every supported build configuration—at minimum the
+supported Unix and Windows targets—before deleting reported code. Review each
+finding; generated files, reflection, build tags, assembly, and external entry
+points can change reachability assumptions.
+
+## 7. Concrete DevRites adoption sequence
+
+1. Characterize current behavior with the existing test suite.
+2. Introduce `PhaseDefinition` and the single ordered registry in
+   `engine/internal/state`; keep serialized phase strings stable.
+3. Move `KnownPhase`, order, requirements, aliases, groups, and labels behind
+   registry queries.
+4. Migrate consumers subsystem by subsystem and delete their local lifecycle
+   tables in the same change.
+5. Add the invariant/contract tests and a generated-drift check only if a
+   generator is actually introduced.
+6. Run the audit stack, delete only confirmed dead code, and rerun all supported
+   platform tests.
+
+## Decision summary
+
+- **Choose:** one typed Go metadata registry, narrow query API, validation test.
+- **Do not choose yet:** runtime-configurable lifecycle, a general workflow DSL,
+  or a new schema/code-generation dependency.
+- **Generate only:** unavoidable cross-format derivatives, with deterministic
+  output and CI drift detection.
+- **Audit continuously:** compiler/tests, vet, Staticcheck, deadcode by supported
+  build configuration, govulncheck, and focused fuzzing.

package/engine/hooks_workspace.go

@@ -187,9 +187,9 @@ func hookHandoffSnapshot(stdin io.Reader, stdout, stderr io.Writer) int {
 		return exitOK
 	}
 	stateLines := wsReadLines(filepath.Join(dir, "state.md"))
-	phase, _ := state.CursorField(stateLines, "phase")
-	status, _ := state.CursorField(stateLines, "status")
-	next, _ := state.CursorField(stateLines, "next_action")
+	phase, _ := state.CursorField(stateLines, state.CursorPhase)
+	status, _ := state.CursorField(stateLines, state.CursorStatus)
+	next, _ := state.CursorField(stateLines, state.CursorNextAction)
 	stamp := time.Now().UTC().Format(time.RFC3339)
 	var b strings.Builder
 	fmt.Fprintf(&b, "\n## Handoff snapshot — %s\n", stamp)
@@ -221,12 +221,12 @@ func hookCursor(stdin io.Reader, stdout, stderr io.Writer) int {
 	}
 	stateLines := wsReadLines(filepath.Join(dir, "state.md"))
 
-	next, _ := state.CursorField(stateLines, "next_action")
-	status, _ := state.CursorField(stateLines, "status")
+	next, _ := state.CursorField(stateLines, state.CursorNextAction)
+	status, _ := state.CursorField(stateLines, state.CursorStatus)
 	gates := wsGateCount(filepath.Join(dir, "questions.md"))
 	afk := ""
 	if wsIsFile(filepath.Join(root, "AFK")) {
-		afk, _ = state.CursorField(stateLines, "afk_slices_remaining")
+		afk, _ = state.CursorField(stateLines, state.CursorAFKSlicesRemaining)
 	}
 
 	fmt.Fprintf(stdout, "DevRites cursor — active feature: %s\n", slug)
@@ -255,7 +255,7 @@ func hookStatusline(stdin io.Reader, stdout, stderr io.Writer) int {
 	if !ok {
 		return exitOK
 	}
-	phase, _ := state.CursorField(wsReadLines(filepath.Join(dir, "state.md")), "phase")
+	phase, _ := state.CursorField(wsReadLines(filepath.Join(dir, "state.md")), state.CursorPhase)
 	if phase == "" {
 		phase = "?"
 	}

package/engine/internal/gate/gate.go

@@ -129,7 +129,7 @@ func StopGate(root string) (StopResult, error) {
 				slug, strings.Join(gates, "/")),
 		}, nil
 	}
-	claimsDone := f.Phase == state.PhaseSeal || f.Phase == state.PhaseShip || f.Phase == state.PhaseDone
+	claimsDone := state.ShippablePhase(f.Phase)
 	if claimsDone && !f.Present[state.SectionProof] {
 		return StopResult{
 			Slug:    slug,
@@ -167,14 +167,14 @@ func openBlockingQuestionGates(data []byte) []string {
 	inQ := false
 	status, gate := "", ""
 	finalize := func() {
-		if inQ && status == "open" && (gate == "blocking" || gate == "validating") && !seen[gate] {
+		if inQ && status == "open" && (gate == "blocking" || gate == "validating" || gate == "escalating") && !seen[gate] {
 			seen[gate] = true
 			gates = append(gates, gate)
 		}
 	}
 	for _, line := range lines {
 		switch {
-		case strings.HasPrefix(line, "## q-"):
+		case strings.HasPrefix(strings.ToLower(line), "## q-"):
 			finalize()
 			inQ, status, gate = true, "", ""
 		case inQ && strings.HasPrefix(line, "status:"):
@@ -191,7 +191,7 @@ func openBlockingQuestionGates(data []byte) []string {
 }
 
 func stateAwaitingHuman(data []byte) bool {
-	status, _ := state.CursorField(splitLinesNoTrailing(data), "status")
+	status, _ := state.CursorField(splitLinesNoTrailing(data), state.CursorStatus)
 	return status == "awaiting_human"
 }
 

package/engine/internal/gate/gate_test.go

@@ -146,8 +146,8 @@ func TestStopGateUsesWorkspaceOverride(t *testing.T) {
 }
 
 func TestOpenBlockingQuestionGates(t *testing.T) {
-	got := openBlockingQuestionGates([]byte("## q-1\nstatus: open\ngate: blocking\n\n## Not a question\n\n## q-2\nstatus: open\ngate: validating\n\n## q-3\nstatus: resolved\ngate: blocking\n\n## q-4\nstatus: open\ngate: blocking\n"))
-	want := []string{"blocking", "validating"}
+	got := openBlockingQuestionGates([]byte("## Q-1\nstatus: open\ngate: blocking\n\n## Not a question\n\n## q-2\nstatus: open\ngate: validating\n\n## q-3\nstatus: resolved\ngate: blocking\n\n## q-4\nstatus: open\ngate: blocking\n\n## Q-5\nstatus: open\ngate: escalating\n"))
+	want := []string{"blocking", "validating", "escalating"}
 	if strings.Join(got, ",") != strings.Join(want, ",") {
 		t.Fatalf("openBlockingQuestionGates=%v, want %v", got, want)
 	}

package/engine/internal/lib/cursor_compat_test.go

@@ -88,4 +88,33 @@ func TestClearAwaitingSupportsCanonicalCursor(t *testing.T) {
 	if strings.Contains(text, "## Awaiting human") || !strings.Contains(text, "| status | running |") {
 		t.Fatalf("canonical awaiting state was not cleared:\n%s", text)
 	}
+	if !strings.Contains(text, "$rite-temper") || strings.Contains(text, "$rite-build") {
+		t.Fatalf("canonical awaiting state resumed the wrong phase:\n%s", text)
+	}
+}
+
+func TestProgressReadsCanonicalSlicesAndShowsPlanPhase(t *testing.T) {
+	root := t.TempDir()
+	dir := filepath.Join(root, "work", "demo")
+	if err := os.MkdirAll(dir, 0o755); err != nil {
+		t.Fatal(err)
+	}
+	stateText := strings.Replace(canonicalCursor, "| phase | temper |", "| phase | plan |", 1)
+	stateText = strings.Replace(stateText, "| afk_slices_remaining | 2 |", "| active_slice | SLICE-002 |", 1)
+	if err := os.WriteFile(filepath.Join(dir, "state.md"), []byte(stateText), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	tasks := "## SLICE-001 First\nStatus: built\n\n## SLICE-002 Second\nStatus: pending\n"
+	if err := os.WriteFile(filepath.Join(dir, "tasks.md"), []byte(tasks), 0o644); err != nil {
+		t.Fatal(err)
+	}
+
+	var stdout bytes.Buffer
+	if code := Progress(root, []string{"demo"}, &stdout, &bytes.Buffer{}); code != 0 {
+		t.Fatalf("code=%d", code)
+	}
+	text := stdout.String()
+	if !strings.Contains(text, "Slice 1/2") || !strings.Contains(text, "plan ◉") || strings.Contains(text, "build ◉") {
+		t.Fatalf("progress missed canonical slice/plan state:\n%s", text)
+	}
 }

package/engine/internal/lib/preamble.go

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

package/engine/internal/lib/preamble_questions_test.go

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

package/engine/internal/lib/progress.go

@@ -20,6 +20,7 @@ var (
 	sliceStateRe   = regexp.MustCompile(`[[:space:]]+(built|pending)[[:space:]]*$`)
 	sliceSepRe     = regexp.MustCompile(`[[:space:]]+[^[:alnum:][:space:]]+[[:space:]]*$`) // drop " — "
 	sliceCheckedRe = regexp.MustCompile(`\[[xX]\]`)
+	sliceHeadingRe = regexp.MustCompile(`^##[[:space:]]+(SLICE-[0-9]{3})(?:[[:space:]]+(.*))?$`)
 )
 
 // Progress renders the active feature's position — the deterministic footer every
@@ -50,6 +51,9 @@ func Progress(root string, args []string, stdout, stderr io.Writer) int {
 		phase = "spec"
 	}
 	total, built, lastbuilt := tallySlices(lines)
+	if total == 0 {
+		total, built, lastbuilt = tallyCanonicalSlices(workDir)
+	}
 
 	// Header rule: pad "── rite-<phase> " with box glyphs to ≥44 BYTES. Under the
 	// oracle's LC_ALL=C the bash `${#header}` counts bytes, which len() matches.
@@ -80,28 +84,28 @@ func Progress(root string, args []string, stdout, stderr io.Writer) int {
 
 	// Flow ribbon: the lifecycle spine; optional phases appear once their artifact
 	// exists or while they are the active phase, so the cursor is never omitted.
-	var order []string
-	if phase == "frame" {
-		order = append(order, "frame")
-	}
-	order = append(order, "spec")
-	if phase == "temper" || isFile(filepath.Join(workDir, "strategy.md")) {
-		order = append(order, "temper")
-	}
-	order = append(order, "define")
-	if phase == "vet" || isFile(filepath.Join(workDir, "eng-review.md")) {
-		order = append(order, "vet")
-	}
-	order = append(order, "build")
-	if phase == "converge" {
-		order = append(order, "converge")
+	order := make([]string, 0, len(state.LifecyclePhases()))
+	for _, lifecyclePhase := range state.LifecyclePhases() {
+		name := string(lifecyclePhase)
+		include := true
+		switch lifecyclePhase {
+		case state.PhaseFrame:
+			include = phase == name
+		case state.PhaseTemper:
+			include = phase == name || isFile(filepath.Join(workDir, "strategy.md"))
+		case state.PhaseDone:
+			include = false
+		case state.PhaseVet:
+			include = phase == name || isFile(filepath.Join(workDir, "eng-review.md"))
+		case state.PhaseConverge:
+			include = phase == name
+		}
+		if include {
+			order = append(order, name)
+		}
 	}
-	order = append(order, "prove", "polish", "review", "seal", "ship")
 
 	cur := phase
-	if cur == "plan" { // replan sits at build
-		cur = "build"
-	}
 	idx := -1
 	if phase == "done" { // past ship
 		idx = len(order)
@@ -127,9 +131,44 @@ func Progress(root string, args []string, stdout, stderr io.Writer) int {
 	return 0
 }
 
+func tallyCanonicalSlices(workDir string) (total, built int, lastbuilt string) {
+	raw, err := os.ReadFile(filepath.Join(workDir, "tasks.md"))
+	if err != nil {
+		return 0, 0, ""
+	}
+	name, sliceState := "", ""
+	finalize := func() {
+		if name == "" {
+			return
+		}
+		total++
+		if sliceState == "built" {
+			built++
+			lastbuilt = name
+		}
+	}
+	for _, line := range strings.Split(string(raw), "\n") {
+		if match := sliceHeadingRe.FindStringSubmatch(strings.TrimSpace(line)); match != nil {
+			finalize()
+			name = match[1]
+			if strings.TrimSpace(match[2]) != "" {
+				name += " " + strings.TrimSpace(match[2])
+			}
+			sliceState = "pending"
+			continue
+		}
+		if name != "" && strings.HasPrefix(strings.ToLower(strings.TrimSpace(line)), "status:") {
+			_, value, _ := strings.Cut(strings.TrimSpace(line), ":")
+			sliceState = strings.ToLower(strings.TrimSpace(value))
+		}
+	}
+	finalize()
+	return total, built, lastbuilt
+}
+
 // parsePhase returns the first token of the canonical or legacy phase field.
 func parsePhase(lines []string) string {
-	value, ok := state.CursorField(lines, "phase")
+	value, ok := state.CursorField(lines, state.CursorPhase)
 	if !ok {
 		return ""
 	}

package/engine/internal/lib/resolve.go

@@ -220,7 +220,7 @@ func resolveQuestion(qfile, qid, status, answer string, stderr io.Writer) int {
 }
 
 var (
-	qHeaderRe    = regexp.MustCompile(`^## q-`)
+	qHeaderRe    = regexp.MustCompile(`(?i)^## q-`)
 	statusLineRe = regexp.MustCompile(`^status:`)
 	statusStrip  = regexp.MustCompile(`^status:[[:space:]]*`)
 	answeredAtRe = regexp.MustCompile(`^answered_at:`)
@@ -299,6 +299,15 @@ func clearAwaiting(sfile, qid string) error {
 		return fmt.Errorf("read state %s: %w", sfile, err)
 	}
 	lines := splitLinesNoTrailing(data)
+	resumePhase := state.PhaseBuild
+	if rawPhase, ok := state.CursorField(lines, state.CursorPhase); ok {
+		if fields := strings.Fields(strings.ToLower(rawPhase)); len(fields) > 0 {
+			if phase, known := state.PhaseForName(fields[0]); known && state.ResumeVerb(phase) != "" {
+				resumePhase = phase
+			}
+		}
+	}
+	resumeCommand := workflow.ForVerb(state.ResumeVerb(resumePhase))
 	// First check whether the awaiting block references this question at all.
 	inAw := false
 	var awaitingLines []string
@@ -314,7 +323,7 @@ func clearAwaiting(sfile, qid string) error {
 			awaitingLines = append(awaitingLines, line)
 		}
 	}
-	waitingOn, _ := state.CursorField(awaitingLines, "question_id")
+	waitingOn, _ := state.CursorField(awaitingLines, state.CursorQuestionID)
 	if waitingOn != qid {
 		return nil
 	}
@@ -341,7 +350,7 @@ func clearAwaiting(sfile, qid string) error {
 			continue
 		case inLog && hdrSpaceRe.MatchString(line):
 			if !logAppended {
-				out = append(out, fmt.Sprintf("- %s build: resolved %s", ts, qid))
+				out = append(out, fmt.Sprintf("- %s %s: resolved %s", ts, resumePhase, qid))
 				logAppended = true
 			}
 			inLog = false
@@ -351,10 +360,10 @@ func clearAwaiting(sfile, qid string) error {
 		out = append(out, line)
 	}
 	if inLog && !logAppended {
-		out = append(out, fmt.Sprintf("- %s build: resolved %s", ts, qid))
+		out = append(out, fmt.Sprintf("- %s %s: resolved %s", ts, resumePhase, qid))
 	}
-	out, _ = state.SetCursorField(out, "status", "running")
-	out, _ = state.SetCursorField(out, "next_action", "(resume — `"+workflow.ForVerb("build").Both()+"` to continue the workflow)")
+	out, _ = state.SetCursorField(out, state.CursorStatus, "running")
+	out, _ = state.SetCursorField(out, state.CursorNextAction, "(resume — `"+resumeCommand.Both()+"` to continue the workflow)")
 	if err := fsutil.WriteFileAtomic(sfile, joinRecords(out), 0o644); err != nil {
 		return fmt.Errorf("update state %s: %w", sfile, err)
 	}

package/engine/internal/lib/resolve_remediation_test.go

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

package/engine/internal/lib/tickafk.go

@@ -65,7 +65,7 @@ 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) {
-	value, found = state.CursorField(lines, "afk_slices_remaining")
+	value, found = state.CursorField(lines, state.CursorAFKSlicesRemaining)
 	if !found {
 		return "", false
 	}
@@ -77,6 +77,6 @@ func readBudget(lines []string) (value string, found bool) {
 
 // setBudget preserves the cursor's canonical-table or legacy-bullet format.
 func setBudget(lines []string, n int) []byte {
-	updated, _ := state.SetCursorField(lines, "afk_slices_remaining", strconv.Itoa(n))
+	updated, _ := state.SetCursorField(lines, state.CursorAFKSlicesRemaining, strconv.Itoa(n))
 	return []byte(strings.Join(updated, "\n") + "\n")
 }

package/engine/internal/migrate/migrate.go

@@ -90,11 +90,11 @@ func featureDirsNeedingNormalization(root string) ([]normalizationTarget, error)
 }
 
 func needsNormalizeFeature(dir string) bool {
-	if !regularFileExists(filepath.Join(dir, "feature.md")) {
+	if !regularFileExists(filepath.Join(dir, state.WorkspaceMapFile)) {
 		return true
 	}
-	return regularFileExists(filepath.Join(dir, "evidence.md")) && !regularFileExists(filepath.Join(dir, "proof.md")) ||
-		regularFileExists(filepath.Join(dir, state.LedgerFile)) && !regularFileExists(filepath.Join(dir, "status.md"))
+	return regularFileExists(filepath.Join(dir, "proof.md")) && !regularFileExists(filepath.Join(dir, state.EvidenceFile)) ||
+		regularFileExists(filepath.Join(dir, "status.md")) && !regularFileExists(filepath.Join(dir, state.LedgerFile))
 }
 
 func regularFileExists(path string) bool {
@@ -103,16 +103,21 @@ func regularFileExists(path string) bool {
 }
 
 func normalizeFeatureDir(dir, slug string) error {
-	if !regularFileExists(filepath.Join(dir, "feature.md")) {
+	for _, alias := range state.WorkspaceMapFiles()[1:] {
+		if err := copyAliasFile(dir, alias, state.WorkspaceMapFile); err != nil {
+			return fmt.Errorf("copy %s to %s: %w", alias, state.WorkspaceMapFile, err)
+		}
+	}
+	if !regularFileExists(filepath.Join(dir, state.WorkspaceMapFile)) {
 		phase := derivePhase(filepath.Join(dir, state.LedgerFile))
-		if err := state.AtomicWrite(filepath.Join(dir, "feature.md"), []byte(featureIndex(slug, phase)), 0o644); err != nil {
-			return fmt.Errorf("write feature index: %w", err)
+		if err := state.AtomicWrite(filepath.Join(dir, state.WorkspaceMapFile), []byte(workspaceIndex(slug, phase)), 0o644); err != nil {
+			return fmt.Errorf("write workspace index: %w", err)
 		}
 	}
-	if err := copyAliasFile(dir, "evidence.md", "proof.md"); err != nil {
-		return fmt.Errorf("copy evidence.md to proof.md: %w", err)
+	if err := copyAliasFile(dir, "proof.md", state.EvidenceFile); err != nil {
+		return fmt.Errorf("copy proof.md to evidence.md: %w", err)
 	}
-	return copyAliasFile(dir, state.LedgerFile, "status.md")
+	return copyAliasFile(dir, "status.md", state.LedgerFile)
 }
 
 func copyAliasFile(dir, alias, canonical string) error {
@@ -128,8 +133,8 @@ func copyAliasFile(dir, alias, canonical string) error {
 	return state.AtomicWrite(dst, data, 0o644)
 }
 
-// featureIndex renders the manifest added to a normalized workspace.
-func featureIndex(slug string, phase state.Phase) string {
+// workspaceIndex renders the compact map added to a normalized workspace.
+func workspaceIndex(slug string, phase state.Phase) string {
 	return fmt.Sprintf(`---
 slug: %s
 title: %s
@@ -151,7 +156,7 @@ func derivePhase(statePath string) state.Phase {
 		return state.PhaseBuild
 	}
 	lines := strings.Split(string(raw), "\n")
-	for _, key := range []string{"phase", "status"} {
+	for _, key := range []string{state.CursorPhase, state.CursorStatus} {
 		if value, found := state.CursorField(lines, key); found {
 			if p, ok := mapLegacyPhase(value); ok {
 				return p
@@ -168,38 +173,7 @@ func mapLegacyPhase(word string) (state.Phase, bool) {
 	if i := strings.IndexAny(word, " \t—-"); i > 0 {
 		word = word[:i]
 	}
-	switch word {
-	case "frame":
-		return state.PhaseFrame, true
-	case "spec", "specced", "specifying":
-		return state.PhaseSpec, true
-	case "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 "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", "shipping":
-		return state.PhaseShip, true
-	case "done", "closed", "complete", "completed":
-		return state.PhaseDone, true
-	default:
-		return "", false
-	}
+	return state.PhaseForName(word)
 }
 
 // backupWorkspace snapshots mutable state (work/, features/, and the ACTIVE pointer) into