devrites 4.1.0 → 4.3.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/cli_observe.go

@@ -0,0 +1,66 @@
+package lib
+
+import (
+	"fmt"
+	"io"
+
+	"github.com/devrites/devrites/internal/devritespaths"
+)
+
+// RunTaskGraphCheck validates tasks.md for one slug.
+func RunTaskGraphCheck(root, slug string, stdout, stderr io.Writer) int {
+	graph, err := CheckTaskGraph(root, slug)
+	if err != nil {
+		fmt.Fprintf(stderr, "task-graph: %v\n", err)
+		return 2
+	}
+	if len(graph.Problems) > 0 {
+		for _, problem := range graph.Problems {
+			fmt.Fprintf(stdout, "task-graph: BLOCKED: %s\n", problem)
+		}
+		return 3
+	}
+	fmt.Fprintf(stdout, "task-graph: ok (%d slices)\n", len(graph.Slices))
+	return 0
+}
+
+// RunSkillTrustCheck scans one Markdown path.
+func RunSkillTrustCheck(path string, stdout, stderr io.Writer) int {
+	result, err := ScanSkillTrust(path)
+	if err != nil {
+		fmt.Fprintf(stderr, "skill-trust: %v\n", err)
+		return 2
+	}
+	fmt.Fprint(stdout, FormatSkillTrust(result))
+	if SkillTrustBlocks(result.Findings) {
+		return 3
+	}
+	return 0
+}
+
+// RunObserveSummary emits JSON for one slug.
+func RunObserveSummary(root, slug string, stdout, stderr io.Writer) int {
+	if err := WriteObserveSummaryJSON(root, slug, stdout); err != nil {
+		fmt.Fprintf(stderr, "observe: %v\n", err)
+		return 2
+	}
+	return 0
+}
+
+// ActiveSlug resolves slug from args or ACTIVE pointer.
+func ActiveSlug(root string, args []string) (string, int, error) {
+	if len(args) == 1 {
+		return args[0], 0, nil
+	}
+	if len(args) != 0 {
+		return "", 2, fmt.Errorf("expected one slug argument")
+	}
+	slug, err := devritespaths.ActiveSlug(root)
+	if err != nil {
+		return "", 2, err
+	}
+	if slug == "" {
+		return "", 2, fmt.Errorf("no slug and ACTIVE is empty")
+	}
+	return slug, 0, nil
+}

package/engine/internal/lib/observe_summary.go

@@ -0,0 +1,79 @@
+package lib
+
+import (
+	"encoding/json"
+	"io"
+
+	"github.com/devrites/devrites/internal/state"
+)
+
+// ObserveSummary is a sanitized, machine-readable workspace snapshot.
+type ObserveSummary struct {
+	Slug              string   `json:"slug"`
+	Phase             string   `json:"phase,omitempty"`
+	Status            string   `json:"status,omitempty"`
+	NextAction        string   `json:"next_action,omitempty"`
+	MissingSections   []string `json:"missing_sections,omitempty"`
+	MissingFiles      []string `json:"missing_files,omitempty"`
+	PrinciplesPresent bool     `json:"principles_present"`
+	TaskGraph         *struct {
+		SliceCount int      `json:"slice_count"`
+		Cycle      []string `json:"cycle,omitempty"`
+		Unknown    []string `json:"unknown_dependencies,omitempty"`
+		OK         bool     `json:"ok"`
+	} `json:"task_graph,omitempty"`
+}
+
+// ObserveSummaryFor builds a summary for one feature slug.
+func ObserveSummaryFor(root, slug string) (ObserveSummary, error) {
+	report, err := state.Status(root, slug)
+	if err != nil {
+		return ObserveSummary{}, err
+	}
+	summary := ObserveSummary{
+		Slug:              report.Slug,
+		Phase:             string(report.Phase),
+		Status:            report.Status,
+		NextAction:        report.NextAction,
+		PrinciplesPresent: report.PrinciplesPresent,
+		MissingFiles:      append([]string(nil), report.MissingFiles...),
+		MissingSections:   missingSectionNames(report.Missing),
+	}
+
+	if graph, graphErr := CheckTaskGraph(root, slug); graphErr == nil && len(graph.Slices) > 0 {
+		summary.TaskGraph = &struct {
+			SliceCount int      `json:"slice_count"`
+			Cycle      []string `json:"cycle,omitempty"`
+			Unknown    []string `json:"unknown_dependencies,omitempty"`
+			OK         bool     `json:"ok"`
+		}{
+			SliceCount: len(graph.Slices),
+			Cycle:      graph.Cycle,
+			Unknown:    graph.Unknown,
+			OK:         len(graph.Problems) == 0,
+		}
+	}
+	return summary, nil
+}
+
+func missingSectionNames(sections []state.Section) []string {
+	if len(sections) == 0 {
+		return nil
+	}
+	out := make([]string, len(sections))
+	for i, section := range sections {
+		out[i] = string(section)
+	}
+	return out
+}
+
+// WriteObserveSummaryJSON prints one JSON object to stdout.
+func WriteObserveSummaryJSON(root, slug string, stdout io.Writer) error {
+	summary, err := ObserveSummaryFor(root, slug)
+	if err != nil {
+		return err
+	}
+	enc := json.NewEncoder(stdout)
+	enc.SetIndent("", "  ")
+	return enc.Encode(summary)
+}

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/lib/skilltrust.go

@@ -0,0 +1,196 @@
+package lib
+
+import (
+	"fmt"
+	"io"
+	"os"
+	"path/filepath"
+	"regexp"
+	"strings"
+	"unicode"
+)
+
+// SkillTrustFinding is one deterministic trust scan result.
+type SkillTrustFinding struct {
+	Severity string // HIGH or MEDIUM
+	Rule     string
+	Line     int
+	Detail   string
+}
+
+// SkillTrustResult summarizes a skill-trust scan.
+type SkillTrustResult struct {
+	Path     string
+	Findings []SkillTrustFinding
+}
+
+var skillTrustRules = []struct {
+	severity string
+	rule     string
+	re       *regexp.Regexp
+	detail   string
+}{
+	{
+		severity: "HIGH",
+		rule:     "prompt_injection_disregard",
+		re:       regexp.MustCompile(`(?i)\b(disregard|ignore)\b.{0,40}\b(prior|previous|above|system|instruction|rule|constraint|safety)\b`),
+		detail:   "instruction attempts to override prior constraints",
+	},
+	{
+		severity: "HIGH",
+		rule:     "credential_exfil_curl_env",
+		re:       regexp.MustCompile(`(?i)\bcurl\b.{0,120}\$(?:ENV|HOME|[A-Z_][A-Z0-9_]*)`),
+		detail:   "curl command references environment variables (possible exfiltration)",
+	},
+	{
+		severity: "HIGH",
+		rule:     "sensitive_path_reference",
+		re:       regexp.MustCompile(`(?i)(~/.ssh|~/.aws|/etc/passwd|id_rsa|\.pem\b|api[_-]?key\s*[:=])`),
+		detail:   "references sensitive filesystem or credential material",
+	},
+	{
+		severity: "MEDIUM",
+		rule:     "hidden_remote_fetch",
+		re:       regexp.MustCompile(`(?i)\b(curl|wget|fetch)\b.{0,80}\b(http|https)://`),
+		detail:   "network fetch instruction in skill prose",
+	},
+}
+
+// ScanSkillTrust reads one Markdown skill/agent file and returns structural trust findings.
+func ScanSkillTrust(path string) (SkillTrustResult, error) {
+	info, err := os.Stat(path)
+	if err != nil {
+		return SkillTrustResult{}, err
+	}
+	if info.IsDir() {
+		return SkillTrustResult{}, fmt.Errorf("skill-trust: %q is a directory", path)
+	}
+	if info.Size() > 1<<20 {
+		return SkillTrustResult{}, fmt.Errorf("skill-trust: %q exceeds 1 MiB limit", path)
+	}
+	file, err := os.Open(path)
+	if err != nil {
+		return SkillTrustResult{}, err
+	}
+	defer file.Close()
+	raw, err := io.ReadAll(io.LimitReader(file, 1<<20+1))
+	if err != nil {
+		return SkillTrustResult{}, err
+	}
+	if len(raw) > 1<<20 {
+		return SkillTrustResult{}, fmt.Errorf("skill-trust: %q exceeds 1 MiB limit", path)
+	}
+	return SkillTrustResult{Path: filepath.Clean(path), Findings: analyzeSkillTrustContent(string(raw))}, nil
+}
+
+func analyzeSkillTrustContent(text string) []SkillTrustFinding {
+	var findings []SkillTrustFinding
+	lines := strings.Split(text, "\n")
+	for i, line := range lines {
+		lineNum := i + 1
+		for _, r := range line {
+			if isSuspiciousUnicode(r) {
+				findings = append(findings, SkillTrustFinding{
+					Severity: "HIGH",
+					Rule:     "suspicious_unicode",
+					Line:     lineNum,
+					Detail:   fmt.Sprintf("suspicious Unicode U+%04X", r),
+				})
+				break
+			}
+		}
+		for _, rule := range skillTrustRules {
+			if rule.re.MatchString(line) {
+				findings = append(findings, SkillTrustFinding{
+					Severity: rule.severity,
+					Rule:     rule.rule,
+					Line:     lineNum,
+					Detail:   rule.detail,
+				})
+			}
+		}
+	}
+	findings = appendMissingNameFinding(text, findings)
+	return dedupeFindings(findings)
+}
+
+func looksLikeSkillFile(text string) bool {
+	lower := strings.ToLower(text)
+	return strings.Contains(lower, "user-invocable:") || strings.Contains(lower, "# /rite-") || strings.Contains(lower, "disable-model-invocation:")
+}
+
+func appendMissingNameFinding(text string, findings []SkillTrustFinding) []SkillTrustFinding {
+	if strings.Contains(text, "---") && !strings.Contains(text, "\nname:") && looksLikeSkillFile(text) {
+		findings = append(findings, SkillTrustFinding{
+			Severity: "MEDIUM",
+			Rule:     "missing_name_frontmatter",
+			Line:     1,
+			Detail:   "skill-like Markdown lacks name frontmatter",
+		})
+	}
+	return findings
+}
+
+func isSuspiciousUnicode(r rune) bool {
+	switch r {
+	case '\u200B', '\u200C', '\u200D', '\uFEFF', '\u2060':
+		return true
+	}
+	if r >= '\u202A' && r <= '\u202E' {
+		return true
+	}
+	if r >= '\u2066' && r <= '\u2069' {
+		return true
+	}
+	return false
+}
+
+func dedupeFindings(in []SkillTrustFinding) []SkillTrustFinding {
+	if len(in) == 0 {
+		return nil
+	}
+	seen := make(map[string]bool, len(in))
+	out := make([]SkillTrustFinding, 0, len(in))
+	for _, finding := range in {
+		key := finding.Rule + "|" + fmt.Sprint(finding.Line) + "|" + finding.Detail
+		if seen[key] {
+			continue
+		}
+		seen[key] = true
+		out = append(out, finding)
+	}
+	return out
+}
+
+// SkillTrustBlocks returns true when findings contain any HIGH severity item.
+func SkillTrustBlocks(findings []SkillTrustFinding) bool {
+	for _, finding := range findings {
+		if finding.Severity == "HIGH" {
+			return true
+		}
+	}
+	return false
+}
+
+// FormatSkillTrust writes a human-readable report.
+func FormatSkillTrust(result SkillTrustResult) string {
+	if len(result.Findings) == 0 {
+		return fmt.Sprintf("skill-trust: PASS (%s)\n", result.Path)
+	}
+	var b strings.Builder
+	fmt.Fprintf(&b, "skill-trust: FINDINGS (%s)\n", result.Path)
+	for _, finding := range result.Findings {
+		fmt.Fprintf(&b, "%s %s line=%d %s\n", finding.Severity, finding.Rule, finding.Line, finding.Detail)
+	}
+	return b.String()
+}
+
+// ContainsOnlyASCII returns false when non-ASCII control or bidi characters appear.
+func ContainsOnlyASCII(text string) bool {
+	for _, r := range text {
+		if r > unicode.MaxASCII && isSuspiciousUnicode(r) {
+			return false
+		}
+	}
+	return true
+}