devrites 3.0.1 → 3.0.3

package/CHANGELOG.md

@@ -2,6 +2,18 @@
 
 All notable changes to DevRites are documented here. The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and DevRites adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). Releases are generated automatically by [semantic-release](https://semantic-release.gitbook.io/) from Conventional Commits on `main`.
 
+## [3.0.3](https://github.com/ViktorsBaikers/DevRites/compare/v3.0.2...v3.0.3) (2026-07-20)
+
+### Fixed
+
+* **rite:** centralize workflow schema ([58bd55e](https://github.com/ViktorsBaikers/DevRites/commit/58bd55e8472a98be1073bcfa5fe7593e7bf0c5d1))
+
+## [3.0.2](https://github.com/ViktorsBaikers/DevRites/compare/v3.0.1...v3.0.2) (2026-07-20)
+
+### Fixed
+
+* **rite:** read canonical workspace cursor state ([e2fd60c](https://github.com/ViktorsBaikers/DevRites/commit/e2fd60c13aa53637e1af02a792f36f3efe32e1c9))
+
 ## [3.0.1](https://github.com/ViktorsBaikers/DevRites/compare/v3.0.0...v3.0.1) (2026-07-20)
 
 ### Fixed

package/README.md

@@ -115,7 +115,7 @@ Full diagram set (lifecycle, polish orchestrator, review fan-out, debug loop,
 rules carrier, workspace state, namespace map) →
 [`docs/flow.md`](docs/flow.md).
 
-**Status:** [`v3.0.1`](https://github.com/ViktorsBaikers/DevRites/releases/tag/v3.0.1) — see [`CHANGELOG.md`](CHANGELOG.md) for release notes.
+**Status:** [`v3.0.3`](https://github.com/ViktorsBaikers/DevRites/releases/tag/v3.0.3) — see [`CHANGELOG.md`](CHANGELOG.md) for release notes.
 
 ## Contents
 

package/docs/adr/0004-state-schema-phases-sections.md

@@ -0,0 +1,44 @@
+# ADR-0004: Phase-relative section completeness
+
+- **Status:** Accepted
+- **Date:** 2026-07-08 (backfilled)
+
+## Context
+
+A feature's working state must be legible to both humans and the engine, and
+"is it complete?" must be answerable deterministically at each step of the
+lifecycle. A single long document makes completeness opaque and burns context;
+a rigid "all fields required always" model blocks early phases on artifacts
+that don't exist yet (there's no proof during framing).
+
+## Decision
+
+Model feature state as **six single-concern section files** — `spec`, `plan`,
+`decisions`, `tasks`, `proof`, `status` (with transitional aliases
+`evidence→proof`, `state→status` that `migrate` normalizes). Drive the lifecycle
+through the ordered rite-\* arc:
+`frame → spec → temper → define → plan → vet → build → converge → prove → polish → review → seal → ship → done`.
+Completeness is **phase-relative and additive**: the typed phase registry maps
+each phase to the sections that must have real content to leave it; a section
+not yet required never blocks. `SchemaVersion = 1`; a feature may declare its
+own and the engine refuses anything newer than it understands. Files evolve
+additively.
+
+## Alternatives considered
+
+| Option | Why not |
+|--------|---------|
+| One `feature.md` mega-document | Completeness isn't self-evident; every read pays for the whole file. |
+| All sections required in every phase | Blocks framing/spec phases on proof/tasks that legitimately don't exist yet. |
+| Status inferred from git / external tracker | Couples state to a tool outside the workspace; breaks the git-diffable, self-contained record. |
+
+## Consequences
+
+- Completeness is a table lookup, not a judgment call — cheap and reproducible.
+- Small files stay context-cheap and make "what's missing" self-evident.
+- `SchemaVersion = 1` is young; migration is single-version. Hardening the
+  writer into one pure transition function is a recorded follow-up
+  (`docs/research/gsd-core-adoption.md` §3.2).
+- The typed registry in `engine/internal/state/schema.go` is the lifecycle
+  authority. Its invariant tests lock order, aliases, commands, requirements,
+  and cross-format manifest freshness.

package/docs/command-map.md

@@ -167,7 +167,7 @@ when available, falling back to file reads otherwise:
 See [`flow.md`](flow.md) for the Mermaid diagrams. The text path:
 
 ```
-/rite-spec → /rite-define → /rite-build ×N → /rite-prove → /rite-polish → /rite-review → /rite-seal → /rite-ship
+/rite-frame → /rite-spec → /rite-temper → /rite-define → /rite-vet → /rite-build ×N → /rite-converge → /rite-prove → /rite-polish → /rite-review → /rite-seal → /rite-ship
    │            │                │  ▲              │                          │             (decide)   (execute+close)
    │            │                │  └ Spec Drift Guard → /rite-plan repair ────┘
    │            │                └ devrites-frontend-craft / source-driven / doubt

package/docs/engine/state-schema.md

@@ -65,8 +65,9 @@ The per-feature index. Its YAML frontmatter carries:
 | `phase`         | current workflow phase (see below)             |
 | `schemaVersion` | schema version the file was written against    |
 
-A feature exists iff its `feature.md` exists. A `feature.md` with no `phase`, or
-an unknown `phase`, is an error.
+A feature exists when it has either a live `state.md` ledger or the transitional
+`feature.md` manifest. The mutable `state.md` cursor is authoritative when both
+declare a phase; an unknown declared phase is an error.
 
 ## Sections
 
@@ -91,16 +92,18 @@ requires only the sections needed to leave it, and the set grows additively down
 the arc. A section that is not yet required (e.g. `proof` during the `spec`
 phase) never blocks.
 
-| phase   | required sections                                     |
-| ------- | ----------------------------------------------------- |
-| `frame` | *(none)*                                              |
-| `spec`  | `spec`                                                |
-| `plan`  | `spec`, `plan`                                         |
-| `build` | `spec`, `plan`, `decisions`, `tasks`                  |
-| `prove` | `spec`, `plan`, `decisions`, `tasks`, `proof`         |
-| `vet`   | `spec`, `plan`, `decisions`, `tasks`, `proof`         |
-| `seal`  | `spec`, `plan`, `decisions`, `tasks`, `proof`, `status` |
-| `ship`  | `spec`, `plan`, `decisions`, `tasks`, `proof`, `status` |
+| phase | required sections |
+| --- | --- |
+| `frame` | *(none)* |
+| `spec`, `temper` | `spec` |
+| `define`, `plan` | `spec`, `plan` |
+| `vet`, `build`, `converge` | `spec`, `plan`, `decisions`, `tasks` |
+| `prove`, `polish`, `review` | `spec`, `plan`, `decisions`, `tasks`, `proof` |
+| `seal`, `ship`, `done` | `spec`, `plan`, `decisions`, `tasks`, `proof`, `status` |
+
+The authoritative typed definitions live in `engine/internal/state/schema.go`.
+`workflow_manifest.json` is a generated derivative for non-Go release tools;
+run `go generate ./internal/state` after editing the registry.
 
 ## `devrites-engine status <slug>`
 

package/docs/flow.md

@@ -270,7 +270,7 @@ erDiagram
         string slug PK ".devrites/work/<slug>/"
     }
     state {
-        string phase "spec | plan | build | prove | polish | review | seal | ship | done"
+        string phase "frame | spec | temper | define | plan | vet | build | converge | prove | polish | review | seal | ship | done"
         string status "running | awaiting_human | blocked | done"
         string active_slice "N — name"
         int afk_slices_remaining "from .devrites/AFK max_slices on first AFK build"

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_events_test.go

@@ -26,6 +26,21 @@ func makeHookWorkspace(t *testing.T) string {
 	return root
 }
 
+func TestHookStatuslineReadsCanonicalCursor(t *testing.T) {
+	root := makeHookWorkspace(t)
+	state := "| Key | Value |\n| --- | --- |\n| phase | temper |\n| status | running |\n"
+	if err := os.WriteFile(filepath.Join(root, "work", "demo", "state.md"), []byte(state), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	var stdout bytes.Buffer
+	if code := hookStatusline(strings.NewReader(""), &stdout, &bytes.Buffer{}); code != 0 {
+		t.Fatalf("hookStatusline code=%d", code)
+	}
+	if !strings.Contains(stdout.String(), "demo · temper ·") {
+		t.Fatalf("statusline ignored table phase: %s", stdout.String())
+	}
+}
+
 func TestHookEventWritesTimelineAndWorkspaceEvents(t *testing.T) {
 	root := makeHookWorkspace(t)
 	if code := hookEvent([]string{"subagent-stop"}, strings.NewReader(`{}`), &bytes.Buffer{}, &bytes.Buffer{}); code != 0 {

package/engine/hooks_workspace.go

@@ -22,20 +22,8 @@ import (
 	"github.com/devrites/devrites/internal/state"
 )
 
-// State-field patterns. Each hook reads a field the way the scripts do:
-// `grep -iE <find>` (case-INSENSITIVE) selects the first matching line, then
-// `sed -E s/<strip>//` (case-SENSITIVE, as sed is) removes the key prefix — a
-// no-op when the case differs, so the mismatched-case behavior is preserved.
 var (
-	findNextStep  = regexp.MustCompile(`(?i)^[-[:space:]]*Next step:`)
-	stripNextStep = regexp.MustCompile(`^[-[:space:]]*Next step:[[:space:]]*`)
-	findStatus    = regexp.MustCompile(`(?i)^[-[:space:]]*Status:`)
-	stripStatus   = regexp.MustCompile(`^[-[:space:]]*Status:[[:space:]]*`)
-	findPhase     = regexp.MustCompile(`(?i)^[-[:space:]]*Phase:`)
-	stripPhase    = regexp.MustCompile(`^[-[:space:]]*Phase:[[:space:]]*`)
-	findAFKRem    = regexp.MustCompile(`(?i)AFK slices remaining:`)
-	stripAFKRem   = regexp.MustCompile(`.*remaining:[[:space:]]*`)
-	openStatusRe  = regexp.MustCompile(`(?i)^[[:space:]]*status:[[:space:]]*open`)
+	openStatusRe = regexp.MustCompile(`(?i)^[[:space:]]*status:[[:space:]]*open`)
 )
 
 // resolveWorkspaceDir resolves the active feature's directory. New writes default
@@ -199,9 +187,9 @@ func hookHandoffSnapshot(stdin io.Reader, stdout, stderr io.Writer) int {
 		return exitOK
 	}
 	stateLines := wsReadLines(filepath.Join(dir, "state.md"))
-	phase := wsField(stateLines, findPhase, stripPhase)
-	status := wsField(stateLines, findStatus, stripStatus)
-	next := wsField(stateLines, findNextStep, stripNextStep)
+	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)
@@ -233,12 +221,12 @@ func hookCursor(stdin io.Reader, stdout, stderr io.Writer) int {
 	}
 	stateLines := wsReadLines(filepath.Join(dir, "state.md"))
 
-	next := wsField(stateLines, findNextStep, stripNextStep)
-	status := wsField(stateLines, findStatus, stripStatus)
+	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 = wsField(stateLines, findAFKRem, stripAFKRem)
+		afk, _ = state.CursorField(stateLines, state.CursorAFKSlicesRemaining)
 	}
 
 	fmt.Fprintf(stdout, "DevRites cursor — active feature: %s\n", slug)
@@ -267,7 +255,7 @@ func hookStatusline(stdin io.Reader, stdout, stderr io.Writer) int {
 	if !ok {
 		return exitOK
 	}
-	phase := wsField(wsReadLines(filepath.Join(dir, "state.md")), findPhase, stripPhase)
+	phase, _ := state.CursorField(wsReadLines(filepath.Join(dir, "state.md")), state.CursorPhase)
 	if phase == "" {
 		phase = "?"
 	}
@@ -536,17 +524,6 @@ func hookWrightScope(h harness.Harness, stdin io.Reader, stdout, stderr io.Write
 	return exitOK
 }
 
-// wsField mirrors `grep -iE <find> | head -1 | sed -E s/<strip>//`: the first line
-// matching find (case-insensitive) with strip removed (case-sensitive).
-func wsField(lines []string, find, strip *regexp.Regexp) string {
-	for _, line := range lines {
-		if find.MatchString(line) {
-			return strip.ReplaceAllString(line, "")
-		}
-	}
-	return ""
-}
-
 // wsGateCount mirrors `grep -ciE '^\s*status:\s*open' questions.md || echo 0`,
 // INCLUDING grep's quirk: on a present file with zero matches grep prints "0" and
 // exits 1, so `|| echo 0` appends a second "0" (the captured value is "0\n0").

package/engine/internal/gate/gate.go

@@ -90,7 +90,7 @@ func (r *Result) Render() string {
 }
 
 // StopGate evaluates the stop-hook rest-point invariant for the active feature:
-// a feature that CLAIMS completion (it has advanced to the seal or ship phase)
+// a feature that CLAIMS completion (it has advanced to seal, ship, or done)
 // must not have an empty proof section. This is a rest-point check, NOT
 // whole-feature completeness — normal in-progress incompleteness never trips it,
 // so a mid-build turn is never blocked.
@@ -129,7 +129,7 @@ func StopGate(root string) (StopResult, error) {
 				slug, strings.Join(gates, "/")),
 		}, nil
 	}
-	claimsDone := f.Phase == state.PhaseSeal || f.Phase == state.PhaseShip
+	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,13 +191,8 @@ func openBlockingQuestionGates(data []byte) []string {
 }
 
 func stateAwaitingHuman(data []byte) bool {
-	for _, line := range splitLinesNoTrailing(data) {
-		if strings.HasPrefix(line, "- Status:") {
-			status := strings.TrimLeft(strings.TrimPrefix(line, "- Status:"), gateSpaceChars)
-			return status == "awaiting_human"
-		}
-	}
-	return false
+	status, _ := state.CursorField(splitLinesNoTrailing(data), state.CursorStatus)
+	return status == "awaiting_human"
 }
 
 func isHeadingLine(line string) bool {

package/engine/internal/gate/gate_test.go

@@ -38,6 +38,13 @@ func TestCheckAndRenderReadiness(t *testing.T) {
 	}
 }
 
+func TestStateAwaitingHumanReadsCanonicalCursor(t *testing.T) {
+	data := []byte("| Key | Value |\n| --- | --- |\n| status | awaiting_human |\n")
+	if !stateAwaitingHuman(data) {
+		t.Fatal("stateAwaitingHuman ignored canonical cursor table")
+	}
+}
+
 func TestStopGateRestPointInvariants(t *testing.T) {
 	for _, tc := range []struct {
 		name          string
@@ -82,6 +89,15 @@ func TestStopGateRestPointInvariants(t *testing.T) {
 			wantBlocked:   true,
 			wantReasonSub: "proof.md is empty",
 		},
+		{
+			name: "done without proof blocks",
+			files: map[string]string{
+				"feature.md": "---\nphase: ship\nschemaVersion: 1\n---\n",
+				"state.md":   "| Key | Value |\n| --- | --- |\n| phase | done |\n",
+			},
+			wantBlocked:   true,
+			wantReasonSub: "proof.md is empty",
+		},
 	} {
 		t.Run(tc.name, func(t *testing.T) {
 			root := t.TempDir()
@@ -130,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/buildreadiness.go

@@ -7,6 +7,7 @@ import (
 	"regexp"
 	"strings"
 
+	"github.com/devrites/devrites/internal/state"
 	"github.com/devrites/devrites/internal/workflow"
 )
 
@@ -67,22 +68,15 @@ func BuildReadiness(root string, args []string, stdout, stderr io.Writer) int {
 // state.md field value.
 var fieldAnnotation = regexp.MustCompile(`[[:space:]]*(#|\|).*$`)
 
-// readinessField reads a `Key: value` field from state.md, tolerating a leading
-// "- " bullet and trimming any trailing annotation and blanks. It returns the
-// first match, or "" when the key is absent. A key may contain spaces (e.g.
-// "Plan approved") — it is matched literally.
+// readinessField reads canonical cursor tables and legacy bullet fields, then
+// trims the legacy trailing annotations accepted by the original command.
 func readinessField(lines []string, key string) string {
-	field := regexp.MustCompile(`^[[:space:]]*-?[[:space:]]*` + key + `:[[:space:]]*`)
-	for _, line := range lines {
-		loc := field.FindStringIndex(line)
-		if loc == nil {
-			continue
-		}
-		value := line[loc[1]:]
-		if m := fieldAnnotation.FindStringIndex(value); m != nil {
-			value = value[:m[0]]
-		}
-		return strings.TrimRight(value, spaceChars)
+	value, ok := state.CursorField(lines, key)
+	if !ok {
+		return ""
+	}
+	if m := fieldAnnotation.FindStringIndex(value); m != nil {
+		value = value[:m[0]]
 	}
-	return ""
+	return strings.TrimRight(value, spaceChars)
 }