orch-code 0.1.1

package/internal/execution/retry_directive.go

@@ -0,0 +1,132 @@
+package execution
+
+import (
+	"strings"
+
+	"github.com/furkanbeydemir/orch/internal/models"
+)
+
+type RetryDirectiveBuilder struct{}
+
+func NewRetryDirectiveBuilder() *RetryDirectiveBuilder {
+	return &RetryDirectiveBuilder{}
+}
+
+func (b *RetryDirectiveBuilder) FromValidation(state *models.RunState, attempt int) *models.RetryDirective {
+	if state == nil {
+		return nil
+	}
+	directive := &models.RetryDirective{
+		Stage:        "validation",
+		Attempt:      attempt,
+		Reasons:      []string{},
+		FailedGates:  []string{},
+		Instructions: []string{},
+		Avoid: []string{
+			"Do not retry with the same scope violation or forbidden change.",
+			"Do not expand scope unless the change is explicitly justified.",
+		},
+	}
+	for _, result := range state.ValidationResults {
+		if result.Status != models.ValidationFail {
+			continue
+		}
+		directive.FailedGates = append(directive.FailedGates, result.Name)
+		directive.Reasons = append(directive.Reasons, result.Summary)
+		directive.Instructions = append(directive.Instructions, result.ActionableItems...)
+	}
+	if len(directive.Instructions) == 0 {
+		directive.Instructions = append(directive.Instructions, "Regenerate the patch to satisfy all failed validation gates.")
+	}
+	return normalizeDirective(directive)
+}
+
+func (b *RetryDirectiveBuilder) FromTest(state *models.RunState, attempt int) *models.RetryDirective {
+	if state == nil {
+		return nil
+	}
+	reasons := []string{"The previous patch failed test execution."}
+	failedTests := []string{}
+	instructions := []string{"Fix the failing test behavior while keeping the patch inside the approved scope."}
+	for _, failure := range state.TestFailures {
+		failedTests = append(failedTests, failure.Code)
+		reasons = append(reasons, failure.Summary)
+		switch failure.Code {
+		case "test_timeout":
+			instructions = append(instructions, "Reduce the cause of timeout or make the code path deterministic enough to complete within the test budget.")
+		case "missing_required_tests":
+			instructions = append(instructions, "Add or restore the required tests instead of bypassing verification.")
+		case "test_assertion_failure":
+			instructions = append(instructions, "Fix the functional behavior that caused the assertion failure.")
+		case "flaky_test_suspected":
+			instructions = append(instructions, "Stabilize the code path instead of weakening the test.")
+		default:
+			instructions = append(instructions, "Resolve the setup or runtime issue causing the test command failure.")
+		}
+	}
+	if len(failedTests) == 0 {
+		failedTests = splitNonEmptyLines(state.TestResults)
+	}
+	directive := &models.RetryDirective{
+		Stage:        "test",
+		Attempt:      attempt,
+		Reasons:      reasons,
+		FailedTests:  failedTests,
+		Instructions: instructions,
+		Avoid: []string{
+			"Do not remove or weaken tests to make them pass.",
+			"Do not introduce unrelated changes while fixing test failures.",
+		},
+	}
+	for _, result := range state.ValidationResults {
+		if result.Status == models.ValidationFail {
+			directive.FailedGates = append(directive.FailedGates, result.Name)
+		}
+	}
+	return normalizeDirective(directive)
+}
+
+func (b *RetryDirectiveBuilder) FromReview(state *models.RunState, attempt int) *models.RetryDirective {
+	if state == nil || state.Review == nil {
+		return nil
+	}
+	directive := &models.RetryDirective{
+		Stage:        "review",
+		Attempt:      attempt,
+		Reasons:      append([]string{}, state.Review.Comments...),
+		Instructions: append([]string{}, state.Review.Suggestions...),
+		Avoid: []string{
+			"Do not ignore reviewer findings.",
+			"Do not broaden the patch beyond what is needed to resolve review findings.",
+		},
+	}
+	if len(directive.Instructions) == 0 {
+		directive.Instructions = append(directive.Instructions, "Address the review findings and preserve all prior passing validation and test conditions.")
+	}
+	return normalizeDirective(directive)
+}
+
+func normalizeDirective(d *models.RetryDirective) *models.RetryDirective {
+	if d == nil {
+		return nil
+	}
+	d.Reasons = uniqueNonEmpty(d.Reasons)
+	d.FailedGates = uniqueNonEmpty(d.FailedGates)
+	d.FailedTests = uniqueNonEmpty(d.FailedTests)
+	d.Instructions = uniqueNonEmpty(d.Instructions)
+	d.Avoid = uniqueNonEmpty(d.Avoid)
+	return d
+}
+
+func splitNonEmptyLines(text string) []string {
+	parts := strings.Split(strings.TrimSpace(text), "\n")
+	result := make([]string, 0, len(parts))
+	for _, part := range parts {
+		trimmed := strings.TrimSpace(part)
+		if trimmed == "" {
+			continue
+		}
+		result = append(result, trimmed)
+	}
+	return result
+}

package/internal/execution/scope_guard.go

@@ -0,0 +1,69 @@
+package execution
+
+import (
+	"fmt"
+	"strings"
+
+	"github.com/furkanbeydemir/orch/internal/models"
+)
+
+type ScopeGuard struct{}
+
+func NewScopeGuard() *ScopeGuard {
+	return &ScopeGuard{}
+}
+
+func (g *ScopeGuard) Validate(contract *models.ExecutionContract, patch *models.Patch) models.ValidationResult {
+	result := models.ValidationResult{
+		Name:     "scope_compliance",
+		Stage:    "validation",
+		Status:   models.ValidationPass,
+		Severity: models.SeverityLow,
+		Summary:  "patch stayed inside allowed scope",
+		Details:  []string{},
+	}
+
+	if contract == nil {
+		result.Status = models.ValidationWarn
+		result.Severity = models.SeverityMedium
+		result.Summary = "execution contract missing; scope compliance could not be fully validated"
+		return result
+	}
+	if patch == nil {
+		result.Status = models.ValidationFail
+		result.Severity = models.SeverityHigh
+		result.Summary = "patch missing for scope validation"
+		return result
+	}
+	if len(contract.AllowedFiles) == 0 || len(patch.Files) == 0 {
+		return result
+	}
+
+	allowed := map[string]struct{}{}
+	for _, file := range contract.AllowedFiles {
+		allowed[strings.TrimSpace(file)] = struct{}{}
+	}
+
+	violations := make([]string, 0)
+	for _, file := range patch.Files {
+		path := strings.TrimSpace(file.Path)
+		if path == "" {
+			continue
+		}
+		if _, ok := allowed[path]; ok {
+			continue
+		}
+		violations = append(violations, path)
+	}
+
+	if len(violations) == 0 {
+		return result
+	}
+
+	result.Status = models.ValidationFail
+	result.Severity = models.SeverityHigh
+	result.Summary = fmt.Sprintf("patch changed files outside allowed scope: %s", strings.Join(violations, ", "))
+	result.Details = violations
+	result.ActionableItems = []string{"Regenerate the patch using only allowed files or expand scope explicitly with justification."}
+	return result
+}

package/internal/logger/logger.go

@@ -0,0 +1,120 @@
+package logger
+
+import (
+	"encoding/json"
+	"fmt"
+	"os"
+	"path/filepath"
+	"sync"
+	"time"
+
+	"github.com/furkanbeydemir/orch/internal/models"
+)
+
+type Logger struct {
+	runID    string
+	repoRoot string
+	entries  []models.LogEntry
+	mu       sync.Mutex
+	verbose  bool
+}
+
+func New(runID, repoRoot string, verbose bool) *Logger {
+	return &Logger{
+		runID:    runID,
+		repoRoot: repoRoot,
+		entries:  make([]models.LogEntry, 0),
+		verbose:  verbose,
+	}
+}
+
+func (l *Logger) Log(actor, step, message string) {
+	entry := models.LogEntry{
+		Timestamp: time.Now(),
+		Actor:     actor,
+		Step:      step,
+		Message:   message,
+	}
+
+	l.mu.Lock()
+	l.entries = append(l.entries, entry)
+	l.mu.Unlock()
+
+	if l.verbose {
+		fmt.Printf("[%s] %s\n", actor, message)
+	}
+}
+
+func (l *Logger) Verbose(actor, step, message string) {
+	if l.verbose {
+		l.Log(actor, step, message)
+	}
+}
+
+func (l *Logger) Entries() []models.LogEntry {
+	l.mu.Lock()
+	defer l.mu.Unlock()
+
+	result := make([]models.LogEntry, len(l.entries))
+	copy(result, l.entries)
+	return result
+}
+
+func (l *Logger) Save() error {
+	l.mu.Lock()
+	entries := make([]models.LogEntry, len(l.entries))
+	copy(entries, l.entries)
+	l.mu.Unlock()
+
+	runsDir := filepath.Join(l.repoRoot, ".orch", "runs")
+	if err := os.MkdirAll(runsDir, 0o755); err != nil {
+		return fmt.Errorf("failed to create runs directory: %w", err)
+	}
+
+	data, err := json.MarshalIndent(entries, "", "  ")
+	if err != nil {
+		return fmt.Errorf("failed to serialize logs: %w", err)
+	}
+
+	logPath := filepath.Join(runsDir, l.runID+".json")
+	if err := os.WriteFile(logPath, data, 0o644); err != nil {
+		return fmt.Errorf("failed to write log file: %w", err)
+	}
+
+	return nil
+}
+
+func LoadRunLog(repoRoot, runID string) ([]models.LogEntry, error) {
+	logPath := filepath.Join(repoRoot, ".orch", "runs", runID+".json")
+
+	data, err := os.ReadFile(logPath)
+	if err != nil {
+		return nil, fmt.Errorf("failed to read log file: %w", err)
+	}
+
+	var entries []models.LogEntry
+	if err := json.Unmarshal(data, &entries); err != nil {
+		return nil, fmt.Errorf("failed to parse log file: %w", err)
+	}
+
+	return entries, nil
+}
+
+func ListRuns(repoRoot string) ([]string, error) {
+	runsDir := filepath.Join(repoRoot, ".orch", "runs")
+
+	entries, err := os.ReadDir(runsDir)
+	if err != nil {
+		return nil, fmt.Errorf("failed to read runs directory: %w", err)
+	}
+
+	var runs []string
+	for _, entry := range entries {
+		if !entry.IsDir() && filepath.Ext(entry.Name()) == ".json" {
+			name := entry.Name()
+			runs = append(runs, name[:len(name)-len(".json")])
+		}
+	}
+
+	return runs, nil
+}

package/internal/models/contracts_test.go

@@ -0,0 +1,100 @@
+package models
+
+import (
+	"encoding/json"
+	"testing"
+	"time"
+)
+
+func TestRunStateStructuredArtifactsJSONRoundtrip(t *testing.T) {
+	now := time.Now().UTC()
+	state := RunState{
+		ID:   "run-1",
+		Task: Task{ID: "task-1", Description: "fix auth bug", CreatedAt: now},
+		TaskBrief: &TaskBrief{
+			TaskID:         "task-1",
+			UserRequest:    "fix auth bug",
+			NormalizedGoal: "Fix auth bug while preserving existing behavior.",
+			TaskType:       TaskTypeBugfix,
+			RiskLevel:      RiskHigh,
+		},
+		Plan: &Plan{
+			TaskID:             "task-1",
+			Summary:            "Fix auth bug while preserving existing behavior.",
+			TaskType:           TaskTypeBugfix,
+			RiskLevel:          RiskHigh,
+			AcceptanceCriteria: []AcceptanceCriterion{{ID: "ac-1", Description: "Bug path no longer fails."}},
+		},
+		ExecutionContract: &ExecutionContract{
+			TaskID:       "task-1",
+			AllowedFiles: []string{"internal/auth/service.go"},
+			PatchBudget:  PatchBudget{MaxFiles: 2, MaxChangedLines: 80},
+		},
+		ValidationResults: []ValidationResult{{
+			Name:     "scope_compliance",
+			Stage:    "validation",
+			Status:   ValidationPass,
+			Severity: SeverityLow,
+			Summary:  "patch stayed inside allowed scope",
+		}},
+		RetryDirective: &RetryDirective{
+			Stage:        "validation",
+			Attempt:      1,
+			FailedGates:  []string{"scope_compliance"},
+			Instructions: []string{"Keep the patch inside allowed scope."},
+		},
+		ReviewScorecard: &ReviewScorecard{
+			RequirementCoverage: 9,
+			ScopeControl:        10,
+			RegressionRisk:      8,
+			Readability:         8,
+			Maintainability:     8,
+			TestAdequacy:        8,
+			Decision:            ReviewAccept,
+		},
+		Confidence: &ConfidenceReport{
+			Score:   0.88,
+			Band:    "high",
+			Reasons: []string{"all mandatory signals aligned"},
+		},
+		TestFailures: []TestFailure{{
+			Code:    "test_assertion_failure",
+			Summary: "expected 200 got 500",
+			Details: []string{"expected 200 got 500"},
+		}},
+		Status:    StatusPlanning,
+		StartedAt: now,
+	}
+
+	encoded, err := json.Marshal(state)
+	if err != nil {
+		t.Fatalf("marshal: %v", err)
+	}
+
+	var decoded RunState
+	if err := json.Unmarshal(encoded, &decoded); err != nil {
+		t.Fatalf("unmarshal: %v", err)
+	}
+
+	if decoded.TaskBrief == nil || decoded.TaskBrief.TaskType != TaskTypeBugfix {
+		t.Fatalf("task brief did not roundtrip")
+	}
+	if decoded.ExecutionContract == nil || len(decoded.ExecutionContract.AllowedFiles) != 1 {
+		t.Fatalf("execution contract did not roundtrip")
+	}
+	if len(decoded.ValidationResults) != 1 || decoded.ValidationResults[0].Name != "scope_compliance" {
+		t.Fatalf("validation results did not roundtrip")
+	}
+	if decoded.RetryDirective == nil || decoded.RetryDirective.Stage != "validation" {
+		t.Fatalf("retry directive did not roundtrip")
+	}
+	if decoded.ReviewScorecard == nil || decoded.ReviewScorecard.Decision != ReviewAccept {
+		t.Fatalf("review scorecard did not roundtrip")
+	}
+	if decoded.Confidence == nil || decoded.Confidence.Band != "high" {
+		t.Fatalf("confidence report did not roundtrip")
+	}
+	if len(decoded.TestFailures) != 1 || decoded.TestFailures[0].Code != "test_assertion_failure" {
+		t.Fatalf("test failures did not roundtrip")
+	}
+}

package/internal/models/models.go

@@ -0,0 +1,269 @@
+package models
+
+import "time"
+
+// State machine: Created → Analyzing → Planning → Coding → Validating → Testing → Reviewing → Completed/Failed
+type RunStatus string
+
+const (
+	StatusCreated    RunStatus = "created"
+	StatusAnalyzing  RunStatus = "analyzing"
+	StatusPlanning   RunStatus = "planning"
+	StatusCoding     RunStatus = "coding"
+	StatusValidating RunStatus = "validating"
+	StatusTesting    RunStatus = "testing"
+	StatusReviewing  RunStatus = "reviewing"
+	StatusCompleted  RunStatus = "completed"
+	StatusFailed     RunStatus = "failed"
+)
+
+type ReviewDecision string
+
+const (
+	ReviewAccept ReviewDecision = "accept"
+	ReviewRevise ReviewDecision = "revise"
+)
+
+type TaskType string
+
+const (
+	TaskTypeUnknown  TaskType = "unknown"
+	TaskTypeFeature  TaskType = "feature"
+	TaskTypeBugfix   TaskType = "bugfix"
+	TaskTypeTest     TaskType = "test"
+	TaskTypeRefactor TaskType = "refactor"
+	TaskTypeDocs     TaskType = "docs"
+	TaskTypeChore    TaskType = "chore"
+)
+
+type RiskLevel string
+
+const (
+	RiskLow    RiskLevel = "low"
+	RiskMedium RiskLevel = "medium"
+	RiskHigh   RiskLevel = "high"
+)
+
+type ValidationStatus string
+
+const (
+	ValidationPass ValidationStatus = "pass"
+	ValidationWarn ValidationStatus = "warn"
+	ValidationFail ValidationStatus = "fail"
+)
+
+type ValidationSeverity string
+
+const (
+	SeverityLow      ValidationSeverity = "low"
+	SeverityMedium   ValidationSeverity = "medium"
+	SeverityHigh     ValidationSeverity = "high"
+	SeverityCritical ValidationSeverity = "critical"
+)
+
+type Task struct {
+	ID          string    `json:"id"`
+	Description string    `json:"description"`
+	CreatedAt   time.Time `json:"created_at"`
+}
+
+type TaskBrief struct {
+	TaskID            string    `json:"task_id"`
+	UserRequest       string    `json:"user_request"`
+	NormalizedGoal    string    `json:"normalized_goal"`
+	TaskType          TaskType  `json:"task_type"`
+	RiskLevel         RiskLevel `json:"risk_level"`
+	Constraints       []string  `json:"constraints,omitempty"`
+	Assumptions       []string  `json:"assumptions,omitempty"`
+	SuccessDefinition []string  `json:"success_definition,omitempty"`
+}
+
+type AcceptanceCriterion struct {
+	ID          string `json:"id"`
+	Description string `json:"description"`
+}
+
+type Plan struct {
+	TaskID             string                `json:"task_id"`
+	Summary            string                `json:"summary,omitempty"`
+	TaskType           TaskType              `json:"task_type,omitempty"`
+	RiskLevel          RiskLevel             `json:"risk_level,omitempty"`
+	Steps              []PlanStep            `json:"steps"`
+	FilesToModify      []string              `json:"files_to_modify"`
+	FilesToInspect     []string              `json:"files_to_inspect"`
+	Risks              []string              `json:"risks"`
+	TestStrategy       string                `json:"test_strategy"`
+	TestRequirements   []string              `json:"test_requirements,omitempty"`
+	AcceptanceCriteria []AcceptanceCriterion `json:"acceptance_criteria,omitempty"`
+	Invariants         []string              `json:"invariants,omitempty"`
+	ForbiddenChanges   []string              `json:"forbidden_changes,omitempty"`
+}
+
+type PlanStep struct {
+	Order       int    `json:"order"`
+	Description string `json:"description"`
+	TargetFile  string `json:"target_file,omitempty"`
+}
+
+type Patch struct {
+	TaskID string      `json:"task_id"`
+	Files  []PatchFile `json:"files"`
+	// RawDiff contains raw unified diff text.
+	RawDiff string `json:"raw_diff"`
+}
+
+type PatchFile struct {
+	Path   string `json:"path"`
+	Status string `json:"status"`
+	Diff   string `json:"diff"`
+}
+
+type RepoMap struct {
+	RootPath string `json:"root_path"`
+	// Language is the detected primary language.
+	Language       string `json:"language"`
+	PackageManager string `json:"package_manager"`
+	TestFramework  string `json:"test_framework"`
+	// Files is the repository file inventory.
+	Files []FileInfo `json:"files"`
+}
+
+type FileInfo struct {
+	Path     string   `json:"path"`
+	Language string   `json:"language"`
+	Size     int64    `json:"size"`
+	Imports  []string `json:"imports,omitempty"`
+}
+
+type PatchBudget struct {
+	MaxFiles        int `json:"max_files"`
+	MaxChangedLines int `json:"max_changed_lines"`
+}
+
+type ScopeExpansionPolicy struct {
+	Allowed        bool `json:"allowed"`
+	RequiresReason bool `json:"requires_reason"`
+	MaxExtraFiles  int  `json:"max_extra_files"`
+}
+
+type ExecutionContract struct {
+	TaskID               string               `json:"task_id"`
+	PlanID               string               `json:"plan_id,omitempty"`
+	AllowedFiles         []string             `json:"allowed_files,omitempty"`
+	InspectFiles         []string             `json:"inspect_files,omitempty"`
+	RequiredEdits        []string             `json:"required_edits,omitempty"`
+	ProhibitedActions    []string             `json:"prohibited_actions,omitempty"`
+	AcceptanceCriteria   []string             `json:"acceptance_criteria,omitempty"`
+	Invariants           []string             `json:"invariants,omitempty"`
+	PatchBudget          PatchBudget          `json:"patch_budget"`
+	ScopeExpansionPolicy ScopeExpansionPolicy `json:"scope_expansion_policy"`
+}
+
+type ValidationResult struct {
+	Name            string             `json:"name"`
+	Stage           string             `json:"stage"`
+	Status          ValidationStatus   `json:"status"`
+	Severity        ValidationSeverity `json:"severity"`
+	Summary         string             `json:"summary"`
+	Details         []string           `json:"details,omitempty"`
+	ActionableItems []string           `json:"actionable_items,omitempty"`
+	Metadata        map[string]string  `json:"metadata,omitempty"`
+}
+
+type RetryDirective struct {
+	Stage        string   `json:"stage"`
+	Attempt      int      `json:"attempt"`
+	Reasons      []string `json:"reasons,omitempty"`
+	FailedGates  []string `json:"failed_gates,omitempty"`
+	FailedTests  []string `json:"failed_tests,omitempty"`
+	Instructions []string `json:"instructions,omitempty"`
+	Avoid        []string `json:"avoid,omitempty"`
+}
+
+type ReviewScorecard struct {
+	RequirementCoverage int            `json:"requirement_coverage"`
+	ScopeControl        int            `json:"scope_control"`
+	RegressionRisk      int            `json:"regression_risk"`
+	Readability         int            `json:"readability"`
+	Maintainability     int            `json:"maintainability"`
+	TestAdequacy        int            `json:"test_adequacy"`
+	Decision            ReviewDecision `json:"decision"`
+	Findings            []string       `json:"findings,omitempty"`
+}
+
+type ConfidenceReport struct {
+	Score    float64  `json:"score"`
+	Band     string   `json:"band"`
+	Reasons  []string `json:"reasons,omitempty"`
+	Warnings []string `json:"warnings,omitempty"`
+}
+
+type TestFailure struct {
+	Code    string   `json:"code"`
+	Summary string   `json:"summary"`
+	Details []string `json:"details,omitempty"`
+	Flaky   bool     `json:"flaky,omitempty"`
+}
+
+type RunState struct {
+	ID                string             `json:"id"`
+	ProjectID         string             `json:"project_id,omitempty"`
+	SessionID         string             `json:"session_id,omitempty"`
+	Task              Task               `json:"task"`
+	TaskBrief         *TaskBrief         `json:"task_brief,omitempty"`
+	Status            RunStatus          `json:"status"`
+	Plan              *Plan              `json:"plan,omitempty"`
+	ExecutionContract *ExecutionContract `json:"execution_contract,omitempty"`
+	Patch             *Patch             `json:"patch,omitempty"`
+	Context           *ContextResult     `json:"context,omitempty"`
+	ValidationResults []ValidationResult `json:"validation_results,omitempty"`
+	RetryDirective    *RetryDirective    `json:"retry_directive,omitempty"`
+	ReviewScorecard   *ReviewScorecard   `json:"review_scorecard,omitempty"`
+	Confidence        *ConfidenceReport  `json:"confidence,omitempty"`
+	TestFailures      []TestFailure      `json:"test_failures,omitempty"`
+	// Review contains review output when available.
+	Review *ReviewResult `json:"review,omitempty"`
+	// TestResults stores summarized test execution output.
+	TestResults        string     `json:"test_results,omitempty"`
+	Retries            RetryState `json:"retries"`
+	UnresolvedFailures []string   `json:"unresolved_failures,omitempty"`
+	BestPatchSummary   string     `json:"best_patch_summary,omitempty"`
+	Logs               []LogEntry `json:"logs"`
+	StartedAt          time.Time  `json:"started_at"`
+	CompletedAt        *time.Time `json:"completed_at,omitempty"`
+	Error              string     `json:"error,omitempty"`
+}
+
+type RetryState struct {
+	Validation int `json:"validation"`
+	Testing    int `json:"testing"`
+	Review     int `json:"review"`
+}
+
+type ReviewResult struct {
+	Decision    ReviewDecision `json:"decision"`
+	Comments    []string       `json:"comments"`
+	Suggestions []string       `json:"suggestions,omitempty"`
+}
+
+type LogEntry struct {
+	Timestamp time.Time `json:"timestamp"`
+	Actor     string    `json:"actor"`
+	Step      string    `json:"step"`
+	Message   string    `json:"message"`
+}
+
+type ContextResult struct {
+	SelectedFiles   []string `json:"selected_files"`
+	RelatedTests    []string `json:"related_tests"`
+	RelevantConfigs []string `json:"relevant_configs"`
+}
+
+type ToolResult struct {
+	ToolName  string            `json:"tool_name"`
+	Success   bool              `json:"success"`
+	Output    string            `json:"output"`
+	Error     string            `json:"error,omitempty"`
+	ErrorCode string            `json:"error_code,omitempty"`
+	Metadata  map[string]string `json:"metadata,omitempty"`
+}