devrites 4.1.0 → 4.2.0

package/engine/internal/gate/readiness_binding_test.go

@@ -8,6 +8,7 @@ import (
 	"testing"
 
 	"github.com/devrites/devrites/internal/reason"
+	"github.com/devrites/devrites/internal/state"
 	"github.com/devrites/devrites/internal/testutil"
 )
 
@@ -135,12 +136,12 @@ func TestReadinessBindingRejectsUnsafeInputsWithoutDisclosure(t *testing.T) {
 			}
 		}},
 		{name: "per input limit", mutate: func(t *testing.T, workspace string) {
-			if err := os.WriteFile(filepath.Join(workspace, "test-plan.md"), bytes.Repeat([]byte("a"), int(maxReadinessInputBytes)+1), 0o644); err != nil {
+			if err := os.WriteFile(filepath.Join(workspace, "test-plan.md"), bytes.Repeat([]byte("a"), (1<<20)+1), 0o644); err != nil {
 				t.Fatal(err)
 			}
 		}},
 		{name: "aggregate limit", mutate: func(t *testing.T, workspace string) {
-			content := bytes.Repeat([]byte("a"), int(maxReadinessInputBytes))
+			content := bytes.Repeat([]byte("a"), 1<<20)
 			for _, name := range []string{"spec.md", "decision-coverage.md", "architecture.md", "plan.md", "tasks.md", "traceability.md", "test-plan.md", "strategy.md", "design-brief.md"} {
 				if err := os.WriteFile(filepath.Join(workspace, name), content, 0o644); err != nil {
 					t.Fatal(err)
@@ -173,11 +174,18 @@ func TestVerifyReadinessBindingRequiresOneStructuralStandaloneLine(t *testing.T)
 		wantErr bool
 	}{
 		{name: "exact", content: "# Engineering review\n\n" + expected + "\n"},
+		{name: "exact CRLF", content: "# Engineering review\r\n\r\n" + expected + "\r\n"},
 		{name: "exact plus fenced example", content: expected + "\n```text\n" + expected + "\n```\n"},
 		{name: "missing", content: "# Engineering review\n\nREADY\n", wantErr: true},
 		{name: "malformed", content: readinessBindingLabel + strings.Repeat("a", 63) + "\n", wantErr: true},
 		{name: "duplicate", content: expected + "\n" + expected + "\n", wantErr: true},
+		{name: "prefixed", content: "prefix " + expected + "\n", wantErr: true},
 		{name: "fenced only", content: "```text\n" + expected + "\n```\n", wantErr: true},
+		{name: "unterminated fence", content: "```text\n" + expected + "\n", wantErr: true},
+		{name: "tilde fenced only", content: "~~~text\n" + expected + "\n~~~~~\n", wantErr: true},
+		{name: "tilde fenced plus visible", content: "~~~text\n" + expected + "\n~~~~~\n" + expected + "\n"},
+		{name: "HTML comment remains structural", content: "<!--\n" + expected + "\n-->\n"},
+		{name: "inline comment marker does not hide binding", content: "`<!--`\n" + expected + "\n"},
 		{name: "mismatch", content: readinessBindingLabel + strings.Repeat("0", 64) + "\n", wantErr: true},
 		{name: "not standalone", content: " " + expected + "\n", wantErr: true},
 	}
@@ -185,7 +193,11 @@ func TestVerifyReadinessBindingRequiresOneStructuralStandaloneLine(t *testing.T)
 	for _, test := range tests {
 		t.Run(test.name, func(t *testing.T) {
 			testutil.WriteFile(t, filepath.Join(workspace, "eng-review.md"), test.content)
-			got, err := verifyReadinessBinding(root, "markers")
+			observation, observeErr := state.ObserveWorkspace(root, "markers")
+			if observeErr != nil {
+				t.Fatal(observeErr)
+			}
+			got, err := verifyReadinessBinding(observation)
 			if (err != nil) != test.wantErr {
 				t.Fatalf("verifyReadinessBinding() error=%v, wantErr=%v", err, test.wantErr)
 			}
@@ -238,6 +250,117 @@ func TestCheckUsesReadinessBindingForBuildAndSeal(t *testing.T) {
 	}
 }
 
+func TestReadinessBindingObservationUsesRetainedBytes(t *testing.T) {
+	root := t.TempDir()
+	workspace := writeReadinessFixture(t, root, "retained-binding", "build")
+	observation, err := state.ObserveWorkspace(root, "retained-binding")
+	if err != nil {
+		t.Fatal(err)
+	}
+	before, err := readinessBindingFromObservation(observation)
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	testutil.WriteFile(t, filepath.Join(workspace, "spec.md"), "# Spec\n\nChanged after observation.\n")
+	testutil.WriteFile(t, filepath.Join(workspace, "strategy.md"), "# Strategy\n\nAdded after observation.\n")
+	after, err := readinessBindingFromObservation(observation)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if after != before {
+		t.Fatalf("retained observation binding changed: before=%q after=%q", before, after)
+	}
+}
+
+func TestReadinessBindingOptionalEmptyFilesRemainPresent(t *testing.T) {
+	forms := []struct {
+		name string
+		body string
+	}{
+		{name: "zero-byte"},
+		{name: "heading-only", body: "# Optional\n"},
+		{name: "frontmatter-only", body: "---\nkind: optional\n---\n"},
+	}
+	for _, logical := range []string{"strategy.md", "design-brief.md", "ai-spec.md", ".devrites/principles.md"} {
+		for _, form := range forms {
+			t.Run(logical+"/"+form.name, func(t *testing.T) {
+				root := t.TempDir()
+				workspace := writeReadinessFixture(t, root, "optional-empty", "build")
+				baseline := mustReadinessBinding(t, root, "optional-empty")
+				path := filepath.Join(workspace, logical)
+				if logical == ".devrites/principles.md" {
+					path = filepath.Join(root, "principles.md")
+				}
+				testutil.WriteFile(t, path, form.body)
+				present := mustReadinessBinding(t, root, "optional-empty")
+				if present == baseline {
+					t.Fatalf("adding %s %s did not encode present bytes", form.name, logical)
+				}
+				if err := os.Remove(path); err != nil {
+					t.Fatal(err)
+				}
+				if restored := mustReadinessBinding(t, root, "optional-empty"); restored != baseline {
+					t.Fatalf("removing %s did not restore absent binding: got %q want %q", logical, restored, baseline)
+				}
+			})
+		}
+	}
+}
+
+func TestCheckReadinessBindingDetectsEmptyOptionalAddAndRemove(t *testing.T) {
+	for _, logical := range []string{"strategy.md", "design-brief.md", "ai-spec.md", ".devrites/principles.md"} {
+		t.Run(logical, func(t *testing.T) {
+			root := t.TempDir()
+			workspace := writeReadinessFixture(t, root, "empty-stale", "build")
+			binding := mustReadinessBinding(t, root, "empty-stale")
+			testutil.AppendFile(t, filepath.Join(workspace, "eng-review.md"), "\n"+binding+"\n")
+			path := filepath.Join(workspace, logical)
+			if logical == ".devrites/principles.md" {
+				path = filepath.Join(root, "principles.md")
+			}
+			testutil.WriteFile(t, path, "")
+
+			result, err := Check(Readiness, root, "empty-stale")
+			if err != nil {
+				t.Fatal(err)
+			}
+			if !result.Blocked || result.ReasonID != reason.GateReadinessStale {
+				t.Fatalf("empty optional add blocked=%v reason=%q", result.Blocked, result.ReasonID)
+			}
+			if err := os.Remove(path); err != nil {
+				t.Fatal(err)
+			}
+			result, err = Check(Readiness, root, "empty-stale")
+			if err != nil {
+				t.Fatal(err)
+			}
+			if result.Blocked {
+				t.Fatalf("empty optional removal remained blocked: %s", result.Render())
+			}
+		})
+	}
+}
+
+func TestReadinessDiagnosticPayloads(t *testing.T) {
+	for _, tc := range []struct {
+		diagnostic state.ArtifactDiagnostic
+		want       string
+	}{
+		{state.ArtifactDiagnostic{Path: "strategy.md", State: state.ArtifactMalformed, Code: state.DiagnosticMalformedMarkdown}, "readiness input strategy.md is malformed (malformed_markdown); replace invalid Markdown with valid Markdown"},
+		{state.ArtifactDiagnostic{Path: "strategy.md", State: state.ArtifactUnsafe, Code: state.DiagnosticParentSymlink}, "readiness input strategy.md is unsafe (parent_symlink); replace the symlinked parent with a real directory"},
+		{state.ArtifactDiagnostic{Path: "strategy.md", State: state.ArtifactUnsafe, Code: state.DiagnosticFinalSymlink}, "readiness input strategy.md is unsafe (final_symlink); replace the symlink with a regular file"},
+		{state.ArtifactDiagnostic{Path: "strategy.md", State: state.ArtifactUnsafe, Code: state.DiagnosticNonRegular}, "readiness input strategy.md is unsafe (non_regular); replace the non-regular entry with a regular file"},
+		{state.ArtifactDiagnostic{Path: "strategy.md", State: state.ArtifactUnsafe, Code: state.DiagnosticFileTooLarge}, "readiness input strategy.md is unsafe (file_too_large); reduce the file to at most 1 MiB"},
+		{state.ArtifactDiagnostic{Path: "strategy.md", State: state.ArtifactUnreadable, Code: state.DiagnosticPermissionDenied}, "readiness input strategy.md is unreadable (permission_denied); grant read permission"},
+		{state.ArtifactDiagnostic{Path: "strategy.md", State: state.ArtifactUnreadable, Code: state.DiagnosticReadFailure}, "readiness input strategy.md is unreadable (read_failure); restore a readable regular file"},
+	} {
+		if got := readinessDiagnosticError(tc.diagnostic).Error(); got != tc.want {
+			t.Errorf("readinessDiagnosticError(%+v)=%q, want %q", tc.diagnostic, got, tc.want)
+		}
+	}
+}
+
 func writeReadinessFixture(t *testing.T, root, slug, phase string) string {
 	t.Helper()
 	workspace := filepath.Join(root, "work", slug)

package/engine/internal/lib/resolve.go

@@ -286,15 +286,15 @@ func clearAwaiting(sfile, qid string) error {
 		return fmt.Errorf("read state %s: %w", sfile, err)
 	}
 	lines := splitLinesNoTrailing(data)
-	resumePhase := state.PhaseBuild
+	resumePolicy, _ := state.PolicyFor(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
+			if policy, known := state.PolicyFor(state.Phase(fields[0])); known && policy.ResumeVerb != "" {
+				resumePolicy = policy
 			}
 		}
 	}
-	resumeCommand := workflow.ForVerb(state.ResumeVerb(resumePhase))
+	resumeCommand := workflow.ForVerb(resumePolicy.ResumeVerb)
 	// First check whether the awaiting block references this question at all.
 	inAw := false
 	var awaitingLines []string
@@ -337,7 +337,7 @@ func clearAwaiting(sfile, qid string) error {
 			continue
 		case inLog && hdrSpaceRe.MatchString(line):
 			if !logAppended {
-				out = append(out, fmt.Sprintf("- %s %s: resolved %s", ts, resumePhase, qid))
+				out = append(out, fmt.Sprintf("- %s %s: resolved %s", ts, resumePolicy.Target, qid))
 				logAppended = true
 			}
 			inLog = false
@@ -347,7 +347,7 @@ func clearAwaiting(sfile, qid string) error {
 		out = append(out, line)
 	}
 	if inLog && !logAppended {
-		out = append(out, fmt.Sprintf("- %s %s: resolved %s", ts, resumePhase, qid))
+		out = append(out, fmt.Sprintf("- %s %s: resolved %s", ts, resumePolicy.Target, qid))
 	}
 	out, _ = state.SetCursorField(out, state.CursorStatus, "running")
 	out, _ = state.SetCursorField(out, state.CursorNextAction, "(resume: `"+resumeCommand.Both()+"` to continue the workflow)")

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

@@ -1,5 +1,5 @@
 // Command workflowmanifest writes the deterministic cross-language derivative
-// of state.WorkflowPhases. The typed Go registry remains the authority.
+// of state.PhasePolicies. The typed Go registry remains the authority.
 package main
 
 import (
@@ -12,6 +12,35 @@ import (
 	"github.com/devrites/devrites/internal/state"
 )
 
+type workflowPhase struct {
+	ID                  state.Phase          `json:"id"`
+	ResumeVerb          string               `json:"resumeVerb,omitempty"`
+	TransitionRight     string               `json:"transitionRight"`
+	RequiredSections    []state.Section      `json:"requiredSections,omitempty"`
+	WorkspaceRequired   []state.ArtifactPath `json:"workspaceRequired"`
+	ProofRequired       bool                 `json:"proofRequired,omitempty"`
+	BlocksOpenQuestions bool                 `json:"blocksOpenQuestions,omitempty"`
+	Shippable           bool                 `json:"shippable,omitempty"`
+}
+
+func workflowPhases() []workflowPhase {
+	policies := state.PhasePolicies()
+	phases := make([]workflowPhase, len(policies))
+	for i, policy := range policies {
+		phases[i] = workflowPhase{
+			ID:                  policy.Target,
+			ResumeVerb:          policy.ResumeVerb,
+			TransitionRight:     policy.TransitionRight,
+			RequiredSections:    policy.RequiredSections,
+			WorkspaceRequired:   policy.RequiredArtifacts,
+			ProofRequired:       policy.ProofRequired,
+			BlocksOpenQuestions: policy.BlocksOpenQuestions,
+			Shippable:           policy.Shippable,
+		}
+	}
+	return phases
+}
+
 func main() {
 	outPath := flag.String("out", "workflow_manifest.json", "output path")
 	check := flag.Bool("check", false, "fail when the output is stale")
@@ -21,13 +50,13 @@ func main() {
 		GeneratedBy      string                 `json:"generatedBy"`
 		SchemaVersion    int                    `json:"schemaVersion"`
 		AuthorityPolicy  state.AuthorityPolicy  `json:"authorityPolicy"`
-		Phases           []state.WorkflowPhase  `json:"phases"`
+		Phases           []workflowPhase        `json:"phases"`
 		CursorKeyAliases []state.CursorKeyAlias `json:"cursorKeyAliases"`
 	}{
 		GeneratedBy:      "go generate ./internal/state; DO NOT EDIT",
 		SchemaVersion:    state.SchemaVersion,
 		AuthorityPolicy:  state.WorkflowAuthorityPolicy(),
-		Phases:           state.WorkflowPhases(),
+		Phases:           workflowPhases(),
 		CursorKeyAliases: state.CursorKeyAliases(),
 	}
 	data, err := json.MarshalIndent(document, "", "  ")

package/engine/internal/state/feature.go

@@ -9,7 +9,6 @@ import (
 	"strings"
 
 	"github.com/devrites/devrites/internal/devritespaths"
-	"github.com/devrites/devrites/internal/markdowntext"
 	"github.com/devrites/devrites/internal/rootfacts"
 )
 
@@ -24,15 +23,6 @@ func ResolveRoot(override string) (string, error) {
 	return facts.PhysicalRoot, nil
 }
 
-// Feature is a loaded per-feature workspace: its declared phase plus which
-// completeness sections currently have real content.
-type Feature struct {
-	Slug         string
-	Phase        Phase
-	Present      map[Section]bool
-	PresentFiles map[string]bool
-}
-
 // featureDir is the canonical per-feature state directory under root.
 func featureDir(root, slug string) string {
 	return devritespaths.FeatureDir(root, slug)
@@ -71,74 +61,6 @@ func regularFileExists(path string) bool {
 	return err == nil && info.Mode().IsRegular()
 }
 
-// LoadFeature reads a canonical feature workspace. state.md is the sole
-// lifecycle authority; optional README.md metadata is not runtime state.
-func LoadFeature(root, slug string) (*Feature, error) {
-	dir := featureDir(root, slug)
-	if !regularFileExists(filepath.Join(dir, LedgerFile)) {
-		return nil, fmt.Errorf("feature %q not found", slug)
-	}
-
-	phase, ledgerDeclared, err := declaredPhaseFromLedger(filepath.Join(dir, LedgerFile))
-	if err != nil {
-		return nil, fmt.Errorf("feature %q: %w", slug, err)
-	}
-	if !ledgerDeclared {
-		return nil, fmt.Errorf("feature %q: no phase in %s ledger", slug, LedgerFile)
-	}
-	if !KnownPhase(phase) {
-		return nil, fmt.Errorf("feature %q: unknown phase %q", slug, phase)
-	}
-
-	present := make(map[Section]bool, len(Sections))
-	for _, section := range Sections {
-		present[section] = sectionPresentAny(dir, section)
-	}
-	presentFiles := make(map[string]bool)
-	for _, name := range WorkspaceFiles() {
-		presentFiles[name] = sectionPresent(filepath.Join(dir, name))
-	}
-	return &Feature{
-		Slug:         slug,
-		Phase:        phase,
-		Present:      present,
-		PresentFiles: presentFiles,
-	}, nil
-}
-
-func sectionPresentAny(dir string, s Section) bool {
-	for _, name := range sectionFiles[s] {
-		if sectionPresent(filepath.Join(dir, name)) {
-			return true
-		}
-	}
-	return false
-}
-
-func declaredPhaseFromLedger(path string) (Phase, bool, error) {
-	raw, err := os.ReadFile(path)
-	if err != nil {
-		if errors.Is(err, os.ErrNotExist) {
-			return "", false, nil
-		}
-		return "", false, fmt.Errorf("read %s: %w", LedgerFile, err)
-	}
-	structural, err := markdowntext.Structural(raw)
-	if err != nil {
-		return "", false, fmt.Errorf("read %s: %w", LedgerFile, err)
-	}
-	lines := strings.Split(string(structural), "\n")
-	value, ok := CursorField(lines, CursorPhase)
-	if !ok {
-		return "", false, nil
-	}
-	word := firstPhaseWord(value)
-	if phase, known := PhaseForName(word); known {
-		return phase, true, nil
-	}
-	return Phase(word), true, nil
-}
-
 func firstPhaseWord(value string) string {
 	word := strings.ToLower(strings.TrimSpace(value))
 	if i := strings.IndexAny(word, " 	"); i > 0 {
@@ -153,27 +75,6 @@ func blankOrHash(trimmed string) bool {
 	return trimmed == "" || strings.HasPrefix(trimmed, "#")
 }
 
-// sectionPresent reports whether a section file has real content: it exists
-// and, after removing a leading YAML frontmatter block, ATX (`#`) headings, and
-// whitespace, some content remains. A stub that is only a heading counts as
-// empty, so scaffolding a file never fakes completeness.
-func sectionPresent(path string) bool {
-	raw, err := os.ReadFile(path)
-	if err != nil {
-		return false
-	}
-	if _, err := markdowntext.Structural(raw); err != nil {
-		return false
-	}
-	body := stripFrontmatter(raw)
-	for _, line := range strings.Split(string(body), "\n") {
-		if !blankOrHash(strings.TrimSpace(line)) {
-			return true
-		}
-	}
-	return false
-}
-
 // stripFrontmatter removes a well-formed leading frontmatter block when
 // determining whether an artifact contains substantive body content. The
 // closing fence must be a line that is exactly `---`.
@@ -191,7 +92,7 @@ func stripFrontmatter(raw []byte) []byte {
 		}
 	}
 	if end < 0 {
-		return raw // no closing fence: treat as if there were no frontmatter
+		return raw
 	}
 	return []byte(strings.Join(lines[end+1:], "\n"))
 }