devrites 3.2.27 → 4.0.0

package/engine/internal/gate/gate.go

@@ -11,7 +11,6 @@ import (
 	"strings"
 
 	"github.com/devrites/devrites/internal/devritespaths"
-	"github.com/devrites/devrites/internal/orient"
 	"github.com/devrites/devrites/internal/reason"
 	"github.com/devrites/devrites/internal/state"
 )
@@ -31,15 +30,15 @@ const (
 // Result is a gate outcome. Blocked is true iff a required section is missing;
 // Missing lists them in canonical order for an actionable message.
 type Result struct {
-	Kind         Kind
-	Slug         string
-	Phase        state.Phase
-	Target       state.Phase     // the phase whose requirements were checked
-	Missing      []state.Section // compact legacy view
-	MissingFiles []string        // authoritative per-file view
-	LegacyLayout bool
-	Blocked      bool
-	ReasonID     reason.ID
+	Kind          Kind
+	Slug          string
+	Phase         state.Phase
+	Target        state.Phase     // the phase whose requirements were checked
+	Missing       []state.Section // compact legacy view
+	MissingFiles  []string        // authoritative per-file view
+	StateProblems []string        // deterministic cross-file invariant failures
+	Blocked       bool
+	ReasonID      reason.ID
 }
 
 // Check runs a gate against feature <slug> under root. It reads workspace files
@@ -55,23 +54,44 @@ func Check(kind Kind, root, slug string) (*Result, error) {
 		target = state.PhaseSeal
 	}
 	missing := state.MissingFor(f, target)
-	var missingFiles []string
-	blocked := len(missing) > 0
-	if !f.LegacyLayout {
-		missingFiles = state.MissingWorkspaceFiles(f, target)
-		blocked = len(missingFiles) > 0
+	missingFiles := state.MissingWorkspaceFiles(f, target)
+	blocked := len(missingFiles) > 0
+	readinessStale := false
+	var stateProblems []string
+	if gates, awaitingHuman := openHumanGates(devritespaths.FeatureDir(root, slug)); len(gates) > 0 {
+		problem := fmt.Sprintf("open %s human question(s) remain in questions.md", strings.Join(gates, "/"))
+		if !awaitingHuman {
+			problem += " but state.md is not awaiting_human"
+		}
+		stateProblems = append(stateProblems, problem)
+		blocked = true
+	}
+	if len(missingFiles) == 0 && phaseRequiresReadinessBinding(target) {
+		expected, bindingErr := verifyReadinessBinding(root, slug)
+		if bindingErr != nil {
+			readinessStale = true
+			blocked = true
+			if expected == "" {
+				stateProblems = append(stateProblems, bindingErr.Error()+"; repair the input and rerun /rite-vet")
+			} else {
+				stateProblems = append(stateProblems, "readiness inputs are stale or the binding is invalid; rerun /rite-vet and record exactly one standalone line: "+expected)
+			}
+		}
 	}
 	result := &Result{
-		Kind:         kind,
-		Slug:         slug,
-		Phase:        f.Phase,
-		Target:       target,
-		Missing:      missing,
-		MissingFiles: missingFiles,
-		LegacyLayout: f.LegacyLayout,
-		Blocked:      blocked,
+		Kind:          kind,
+		Slug:          slug,
+		Phase:         f.Phase,
+		Target:        target,
+		Missing:       missing,
+		MissingFiles:  missingFiles,
+		StateProblems: stateProblems,
+		Blocked:       blocked,
 	}
 	result.ReasonID = ResultReasonID(kind, blocked)
+	if readinessStale {
+		result.ReasonID = reason.GateReadinessStale
+	}
 	return result, nil
 }
 
@@ -102,82 +122,32 @@ func (r *Result) Render() string {
 	fmt.Fprintf(&b, "phase: %s\n", r.Phase)
 	if !r.Blocked {
 		b.WriteString("result: pass\n")
+		fmt.Fprintf(&b, "reason: %s\n", r.ReasonID)
 		return b.String()
 	}
 	missing := r.MissingFiles
-	if r.LegacyLayout {
-		missing = make([]string, len(r.Missing))
-		for i, section := range r.Missing {
-			missing[i] = string(section)
-		}
-	}
-	if r.Kind == Seal {
+	switch {
+	case len(missing) == 0:
+		b.WriteString("result: blocked (state invariant)\n")
+	case r.Kind == Seal:
 		fmt.Fprintf(&b, "result: blocked (missing to seal: %s)\n", strings.Join(missing, ", "))
-	} else {
+	default:
 		fmt.Fprintf(&b, "result: blocked (missing to leave %q: %s)\n", r.Phase, strings.Join(missing, ", "))
 	}
-	fmt.Fprintf(&b, "next: add real content to %s, then re-run: devrites-engine %s %s\n",
-		strings.Join(missing, ", "), r.Kind, r.Slug)
-	return b.String()
-}
-
-// StopGate checks whether the active feature can end a turn in its current state.
-// A feature in seal, ship, or done must have proof. Normal incompleteness during
-// earlier phases does not block.
-//
-// Missing or unreadable workspace state returns an unblocked zero result.
-func StopGate(root string) (StopResult, error) {
-	slug, err := orient.ActiveSlug(root)
-	if err != nil || slug == "" {
-		return StopResult{}, nil
+	fmt.Fprintf(&b, "reason: %s\n", r.ReasonID)
+	if len(missing) > 0 {
+		fmt.Fprintf(&b, "next: add real content to %s\n", strings.Join(missing, ", "))
 	}
-	f, err := state.LoadFeature(root, slug)
-	if err != nil {
-		return StopResult{}, nil // Unreadable state does not block Stop.
+	for _, problem := range r.StateProblems {
+		fmt.Fprintf(&b, "invariant: %s\n", problem)
 	}
-	// redwatch writes .red for a known failing suite. Stop blocks while that file
-	// exists, independently of whole-feature completeness.
-	featureDir := devritespaths.FeatureDir(root, slug)
-	if _, statErr := os.Stat(filepath.Join(featureDir, ".red")); statErr == nil {
-		return StopResult{
-			Slug:          slug,
-			Blocked:       true,
-			ReasonID:      reason.HookStopRed,
-			EvidenceFiles: []string{".red"},
-			Reason: fmt.Sprintf(
-				"feature %q has tests/build RED (.red is set): fix to green, or record the failure and next step, before stopping",
-				slug),
-		}, nil
-	}
-	if gates, blocked := unsurfacedHumanGates(featureDir); blocked {
-		return StopResult{
-			Slug:          slug,
-			Blocked:       true,
-			ReasonID:      reason.HookStopUnsurfacedHumanGate,
-			EvidenceFiles: []string{"questions.md", "state.md"},
-			Reason: fmt.Sprintf(
-				"feature %q has open %s human question(s) in questions.md but state.md is not awaiting_human: surface the gate before stopping",
-				slug, strings.Join(gates, "/")),
-		}, nil
-	}
-	claimsDone := state.ShippablePhase(f.Phase)
-	if claimsDone && !f.Present[state.SectionProof] {
-		return StopResult{
-			Slug:          slug,
-			Blocked:       true,
-			ReasonID:      reason.HookStopMissingProof,
-			EvidenceFiles: []string{"evidence.md", "proof.md", "state.md"},
-			Reason: fmt.Sprintf(
-				"feature %q is at phase %q but proof.md is empty: record acceptance evidence, or move the phase back, before stopping",
-				slug, f.Phase),
-		}, nil
-	}
-	return StopResult{Slug: slug, ReasonID: reason.HookStopClear}, nil
+	fmt.Fprintf(&b, "retry: devrites-engine check %s %s\n", r.Kind, r.Slug)
+	return b.String()
 }
 
 const gateSpaceChars = " \t\n\v\f\r"
 
-func unsurfacedHumanGates(featureDir string) ([]string, bool) {
+func openHumanGates(featureDir string) ([]string, bool) {
 	qdata, err := os.ReadFile(filepath.Join(featureDir, "questions.md"))
 	if err != nil {
 		return nil, false
@@ -187,10 +157,7 @@ func unsurfacedHumanGates(featureDir string) ([]string, bool) {
 		return nil, false
 	}
 	sdata, err := os.ReadFile(filepath.Join(featureDir, "state.md"))
-	if err == nil && stateAwaitingHuman(sdata) {
-		return nil, false
-	}
-	return gates, true
+	return gates, err == nil && stateAwaitingHuman(sdata)
 }
 
 func openBlockingQuestionGates(data []byte) []string {
@@ -199,13 +166,35 @@ func openBlockingQuestionGates(data []byte) []string {
 	var gates []string
 	inQ := false
 	status, gate := "", ""
+	tableOpen := false
+	statusColumn, gateColumn := -1, -1
+	add := func(questionStatus, questionGate string) {
+		questionStatus = strings.ToLower(strings.TrimSpace(questionStatus))
+		questionGate = strings.ToLower(strings.TrimSpace(questionGate))
+		if questionStatus == "open" && (questionGate == "blocking" || questionGate == "validating" || questionGate == "escalating") && !seen[questionGate] {
+			seen[questionGate] = true
+			gates = append(gates, questionGate)
+		}
+	}
 	finalize := func() {
-		if inQ && status == "open" && (gate == "blocking" || gate == "validating" || gate == "escalating") && !seen[gate] {
-			seen[gate] = true
-			gates = append(gates, gate)
+		if inQ {
+			add(status, gate)
 		}
 	}
 	for _, line := range lines {
+		if cells, ok := questionTableCells(line); ok {
+			if !tableOpen {
+				tableOpen = true
+				statusColumn = tableColumn(cells, "status")
+				gateColumn = tableColumn(cells, "gate")
+			}
+			if statusColumn >= 0 && statusColumn < len(cells) && gateColumn >= 0 && gateColumn < len(cells) {
+				add(cells[statusColumn], cells[gateColumn])
+			}
+		} else {
+			tableOpen = false
+			statusColumn, gateColumn = -1, -1
+		}
 		switch {
 		case strings.HasPrefix(strings.ToLower(line), "## q-"):
 			finalize()
@@ -223,6 +212,27 @@ func openBlockingQuestionGates(data []byte) []string {
 	return gates
 }
 
+func questionTableCells(line string) ([]string, bool) {
+	line = strings.TrimSpace(line)
+	if !strings.HasPrefix(line, "|") || !strings.HasSuffix(line, "|") {
+		return nil, false
+	}
+	parts := strings.Split(strings.Trim(line, "|"), "|")
+	for i := range parts {
+		parts[i] = strings.TrimSpace(parts[i])
+	}
+	return parts, true
+}
+
+func tableColumn(cells []string, name string) int {
+	for i, cell := range cells {
+		if strings.EqualFold(cell, name) {
+			return i
+		}
+	}
+	return -1
+}
+
 func stateAwaitingHuman(data []byte) bool {
 	status, _ := state.CursorField(splitLinesNoTrailing(data), state.CursorStatus)
 	return status == "awaiting_human"
@@ -244,14 +254,3 @@ func splitLinesNoTrailing(data []byte) []string {
 	}
 	return strings.Split(s, "\n")
 }
-
-// StopResult is a stop-gate evaluation. Slug names the active feature (empty when
-// none); Blocked is true iff the rest-point invariant is violated; Reason is the
-// actionable explanation when Blocked.
-type StopResult struct {
-	Slug          string
-	Reason        string
-	ReasonID      reason.ID
-	EvidenceFiles []string
-	Blocked       bool
-}

package/engine/internal/gate/gate_test.go

@@ -13,9 +13,17 @@ import (
 func TestCheckAndRenderReadiness(t *testing.T) {
 	root := t.TempDir()
 	writeFeature(t, root, "alpha", map[string]string{
-		"feature.md": "---\nphase: build\nschemaVersion: 1\n---\n",
-		"spec.md":    "real spec\n",
-		"plan.md":    "real plan\n",
+		"state.md":             "- Phase: build\n",
+		"brief.md":             "brief\n",
+		"spec.md":              "real spec\n",
+		"assumptions.md":       "none\n",
+		"questions.md":         "none\n",
+		"decision-coverage.md": "clear\n",
+		"architecture.md":      "architecture\n",
+		"plan.md":              "real plan\n",
+		"traceability.md":      "traceability\n",
+		"eng-review.md":        "ready\n",
+		"test-plan.md":         "tests\n",
 	})
 
 	res, err := Check(Readiness, root, "alpha")
@@ -33,8 +41,9 @@ func TestCheckAndRenderReadiness(t *testing.T) {
 		"gate: readiness",
 		"feature: alpha",
 		"phase: build",
-		`result: blocked (missing to leave "build": decisions, tasks)`,
-		"then re-run: devrites-engine readiness alpha",
+		"reason: DRV-GATE-READINESS-MISSING",
+		`result: blocked (missing to leave "build": decisions.md, tasks.md)`,
+		"retry: devrites-engine check readiness alpha",
 	} {
 		if !strings.Contains(got, want) {
 			t.Fatalf("Render() missing %q in:\n%s", want, got)
@@ -70,6 +79,51 @@ func TestCheckUsesConcreteWorkspaceRequirements(t *testing.T) {
 	}
 }
 
+func TestSealRequiresDurableReviewAndSealArtifacts(t *testing.T) {
+	root := t.TempDir()
+	files := map[string]string{
+		"state.md":             "| phase | seal |\n",
+		"brief.md":             "brief\n",
+		"spec.md":              "spec\n",
+		"decisions.md":         "decisions\n",
+		"assumptions.md":       "assumptions\n",
+		"questions.md":         "none\n",
+		"decision-coverage.md": "clear\n",
+		"architecture.md":      "architecture\n",
+		"plan.md":              "plan\n",
+		"tasks.md":             "tasks\n",
+		"traceability.md":      "traceability\n",
+		"eng-review.md":        "ready\n",
+		"test-plan.md":         "tests\n",
+		"evidence.md":          "evidence\n",
+		"touched-files.md":     "none\n",
+	}
+	writeWorkFeature(t, root, "final", files)
+
+	res, err := Check(Seal, root, "final")
+	if err != nil {
+		t.Fatal(err)
+	}
+	if !res.Blocked || strings.Join(res.MissingFiles, ",") != "review.md,seal.md" {
+		t.Fatalf("blocked=%v missing=%v, want review.md and seal.md", res.Blocked, res.MissingFiles)
+	}
+}
+
+func TestRenderIncludesReasonForPassedGate(t *testing.T) {
+	result := Result{
+		Kind:     Seal,
+		Slug:     "alpha",
+		Phase:    "seal",
+		ReasonID: reason.GateSealPassed,
+	}
+	got := result.Render()
+	for _, want := range []string{"result: pass", "reason: DRV-GATE-SEAL-PASSED"} {
+		if !strings.Contains(got, want) {
+			t.Fatalf("Render() missing %q in:\n%s", want, got)
+		}
+	}
+}
+
 func TestResultReasonIDsAreStableForEveryGateOutcome(t *testing.T) {
 	cases := []struct {
 		kind    Kind
@@ -95,95 +149,53 @@ func TestStateAwaitingHumanReadsCanonicalCursor(t *testing.T) {
 	}
 }
 
-func TestStopGateRestPointInvariants(t *testing.T) {
+func TestCheckBlocksOpenHumanQuestions(t *testing.T) {
 	for _, tc := range []struct {
-		name          string
-		files         map[string]string
-		wantBlocked   bool
-		wantReasonSub string
-		wantReasonID  reason.ID
+		name             string
+		status           string
+		wantInvariantSub string
 	}{
 		{
-			name: "red blocks",
-			files: map[string]string{
-				"feature.md": "---\nphase: build\nschemaVersion: 1\n---\n",
-				"state.md":   "- Phase: build\n",
-				".red":       "go test ./...\n",
-			},
-			wantBlocked:   true,
-			wantReasonSub: "tests/build RED",
-			wantReasonID:  reason.HookStopRed,
-		},
-		{
-			name: "unsurfaced human gate blocks",
-			files: map[string]string{
-				"feature.md":   "---\nphase: build\nschemaVersion: 1\n---\n",
-				"state.md":     "- Phase: build\n- Status: running\n",
-				"questions.md": "## q-1\nstatus: open\ngate: blocking\n\n## q-2\nstatus: open\ngate: validating\n",
-			},
-			wantBlocked:   true,
-			wantReasonSub: "open blocking/validating human question",
-			wantReasonID:  reason.HookStopUnsurfacedHumanGate,
-		},
-		{
-			name: "awaiting human allows surfaced gate",
-			files: map[string]string{
-				"feature.md":   "---\nphase: build\nschemaVersion: 1\n---\n",
-				"state.md":     "- Phase: build\n- Status: awaiting_human\n",
-				"questions.md": "## q-1\nstatus: open\ngate: blocking\n",
-			},
-		},
-		{
-			name: "seal without proof blocks",
-			files: map[string]string{
-				"feature.md": "---\nphase: seal\nschemaVersion: 1\n---\n",
-				"state.md":   "- Phase: seal\n",
-			},
-			wantBlocked:   true,
-			wantReasonSub: "proof.md is empty",
-			wantReasonID:  reason.HookStopMissingProof,
+			name:             "unsurfaced gate",
+			status:           "running",
+			wantInvariantSub: "state.md is not awaiting_human",
 		},
 		{
-			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",
-			wantReasonID:  reason.HookStopMissingProof,
+			name:             "surfaced gate",
+			status:           "awaiting_human",
+			wantInvariantSub: "open blocking/validating human question(s) remain",
 		},
 	} {
 		t.Run(tc.name, func(t *testing.T) {
 			root := t.TempDir()
-			testutil.WriteFile(t, filepath.Join(root, "ACTIVE"), "alpha\n")
-			writeFeature(t, root, "alpha", tc.files)
+			writeFeature(t, root, "alpha", map[string]string{
+				"state.md":     "- Phase: build\n- Status: " + tc.status + "\n",
+				"spec.md":      "spec\n",
+				"plan.md":      "plan\n",
+				"decisions.md": "decisions\n",
+				"tasks.md":     "tasks\n",
+				"questions.md": "## q-1\nstatus: open\ngate: blocking\n\n## q-2\nstatus: open\ngate: validating\n",
+			})
 
-			got, err := StopGate(root)
+			got, err := Check(Readiness, root, "alpha")
 			if err != nil {
 				t.Fatal(err)
 			}
-			if got.Slug != "alpha" {
-				t.Fatalf("StopGate slug=%q, want alpha", got.Slug)
-			}
-			if got.Blocked != tc.wantBlocked {
-				t.Fatalf("StopGate blocked=%v, want %v; reason=%q", got.Blocked, tc.wantBlocked, got.Reason)
-			}
-			if tc.wantReasonSub != "" && !strings.Contains(got.Reason, tc.wantReasonSub) {
-				t.Fatalf("StopGate reason=%q, want substring %q", got.Reason, tc.wantReasonSub)
+			if !got.Blocked {
+				t.Fatal("Check blocked=false, want true")
 			}
-			wantReasonID := tc.wantReasonID
-			if wantReasonID == "" {
-				wantReasonID = reason.HookStopClear
+			invariants := strings.Join(got.StateProblems, "\n")
+			if !strings.Contains(invariants, tc.wantInvariantSub) {
+				t.Fatalf("StateProblems=%q, want substring %q", invariants, tc.wantInvariantSub)
 			}
-			if got.ReasonID != wantReasonID {
-				t.Fatalf("StopGate reason_id=%q, want %q", got.ReasonID, wantReasonID)
+			if got.ReasonID != reason.GateReadinessMissing {
+				t.Fatalf("reason_id=%q, want %q", got.ReasonID, reason.GateReadinessMissing)
 			}
 		})
 	}
 }
 
-func TestStopGateUsesWorkspaceOverride(t *testing.T) {
+func TestCheckUsesWorkspaceOverrideForStateInvariants(t *testing.T) {
 	project := t.TempDir()
 	root := filepath.Join(project, ".devrites")
 	if err := os.MkdirAll(root, 0o755); err != nil {
@@ -191,19 +203,17 @@ func TestStopGateUsesWorkspaceOverride(t *testing.T) {
 	}
 	override := filepath.Join(root, "work", "alpha")
 	t.Setenv("DEVRITES_WORKSPACE", override)
-	testutil.WriteFile(t, filepath.Join(override, "feature.md"), "---\nphase: build\nschemaVersion: 1\n---\n")
-	testutil.WriteFile(t, filepath.Join(override, "state.md"), "- Phase: build\n")
-	testutil.WriteFile(t, filepath.Join(override, ".red"), "go test ./...\n")
+	testutil.WriteFile(t, filepath.Join(override, "README.md"), "---\nphase: spec\nschemaVersion: 1\n---\n")
+	testutil.WriteFile(t, filepath.Join(override, "state.md"), "- Phase: build\n- Status: running\n")
+	testutil.WriteFile(t, filepath.Join(override, "spec.md"), "spec\n")
+	testutil.WriteFile(t, filepath.Join(override, "questions.md"), "## q-1\nstatus: open\ngate: blocking\n")
 
-	got, err := StopGate(root)
+	got, err := Check(Readiness, root, "alpha")
 	if err != nil {
 		t.Fatal(err)
 	}
-	if got.Slug != "alpha" {
-		t.Fatalf("StopGate slug=%q, want alpha", got.Slug)
-	}
-	if !got.Blocked || !strings.Contains(got.Reason, "tests/build RED") {
-		t.Fatalf("StopGate did not block on override .red: blocked=%v reason=%q", got.Blocked, got.Reason)
+	if !got.Blocked || len(got.StateProblems) == 0 {
+		t.Fatalf("Check did not inspect override workspace: blocked=%v problems=%v", got.Blocked, got.StateProblems)
 	}
 }
 
@@ -218,7 +228,7 @@ func TestOpenBlockingQuestionGates(t *testing.T) {
 func writeFeature(t *testing.T, root, slug string, files map[string]string) {
 	t.Helper()
 	for name, content := range files {
-		testutil.WriteFile(t, filepath.Join(root, "features", slug, name), content)
+		testutil.WriteFile(t, filepath.Join(root, "work", slug, name), content)
 	}
 }