devrites 3.0.6 → 3.1.0

package/engine/internal/forge/manifest.go

@@ -0,0 +1,402 @@
+package forge
+
+import (
+	"crypto/rand"
+	"encoding/hex"
+	"encoding/json"
+	"errors"
+	"fmt"
+	"io/fs"
+	"os"
+	"path/filepath"
+	"regexp"
+	"sort"
+	"strings"
+	"time"
+)
+
+const Schema = "devrites-forge/v1"
+
+var (
+	safeSlug  = regexp.MustCompile(`^[a-z0-9][a-z0-9._-]{0,63}$`)
+	safeRunID = regexp.MustCompile(`^forge-[a-f0-9]{24}$`)
+)
+
+type CandidateID string
+
+const (
+	CandidateA CandidateID = "A"
+	CandidateB CandidateID = "B"
+	CandidateC CandidateID = "C"
+)
+
+type CandidateState string
+
+const (
+	StatePlanned   CandidateState = "planned"
+	StateCreated   CandidateState = "created"
+	StateRunning   CandidateState = "running"
+	StateFinished  CandidateState = "finished"
+	StateFailed    CandidateState = "failed"
+	StateExtracted CandidateState = "extracted"
+	StateMerged    CandidateState = "merged"
+	StateCleaned   CandidateState = "cleaned"
+)
+
+type Primary struct {
+	Branch         string `json:"branch"`
+	BaseCommit     string `json:"base_commit"`
+	BaselineTree   string `json:"baseline_tree"`
+	BaselineSHA256 string `json:"baseline_sha256"`
+}
+
+type Worker struct {
+	ID           string `json:"id,omitempty"`
+	PID          int    `json:"pid,omitempty"`
+	ProcessStart string `json:"process_start,omitempty"`
+	StartedAt    string `json:"started_at,omitempty"`
+	FinishedAt   string `json:"finished_at,omitempty"`
+	Result       string `json:"result,omitempty"`
+}
+
+type Candidate struct {
+	ID             CandidateID    `json:"id"`
+	Strategy       string         `json:"strategy"`
+	Worktree       string         `json:"worktree"`
+	Branch         string         `json:"branch"`
+	InitialBase    string         `json:"initial_base"`
+	State          CandidateState `json:"state"`
+	Worker         Worker         `json:"worker"`
+	Commit         string         `json:"commit,omitempty"`
+	Tree           string         `json:"tree,omitempty"`
+	DeltaSHA256    string         `json:"delta_sha256,omitempty"`
+	Preservation   string         `json:"preservation,omitempty"`
+	LastTransition string         `json:"last_transition"`
+}
+
+type Winner struct {
+	Candidate  CandidateID `json:"candidate,omitempty"`
+	RecordedBy string      `json:"recorded_by,omitempty"`
+	RecordedAt string      `json:"recorded_at,omitempty"`
+}
+
+type MergeState struct {
+	State      string `json:"state,omitempty"`
+	Commit     string `json:"commit,omitempty"`
+	Tree       string `json:"tree,omitempty"`
+	RecordedAt string `json:"recorded_at,omitempty"`
+}
+
+type VerificationState struct {
+	State      string `json:"state,omitempty"`
+	RecordedBy string `json:"recorded_by,omitempty"`
+	RecordedAt string `json:"recorded_at,omitempty"`
+}
+
+type CleanupState struct {
+	State      string            `json:"state,omitempty"`
+	Preserved  map[string]string `json:"preserved,omitempty"`
+	RecordedAt string            `json:"recorded_at,omitempty"`
+}
+
+type Manifest struct {
+	Schema         string            `json:"schema"`
+	RunID          string            `json:"run_id"`
+	CreationNonce  string            `json:"creation_nonce"`
+	CreatedAt      string            `json:"created_at"`
+	FeatureSlug    string            `json:"feature_slug"`
+	SliceID        string            `json:"slice_id"`
+	AcceptanceHash string            `json:"acceptance_hash"`
+	TestPlanHash   string            `json:"test_plan_hash"`
+	PrimaryRoot    string            `json:"primary_root"`
+	GitCommonDir   string            `json:"git_common_dir"`
+	ForgeRoot      string            `json:"forge_root"`
+	Primary        Primary           `json:"primary"`
+	Candidates     []Candidate       `json:"candidates"`
+	Winner         Winner            `json:"winner"`
+	Merge          MergeState        `json:"merge"`
+	Verification   VerificationState `json:"verification"`
+	Cleanup        CleanupState      `json:"cleanup"`
+}
+
+func (m *Manifest) Candidate(id CandidateID) (*Candidate, error) {
+	for i := range m.Candidates {
+		if m.Candidates[i].ID == id {
+			return &m.Candidates[i], nil
+		}
+	}
+	return nil, fmt.Errorf("forge: candidate %q is not in manifest", id)
+}
+
+func ManifestPath(root, slug, runID string) (string, error) {
+	if !safeSlug.MatchString(slug) {
+		return "", fmt.Errorf("forge: invalid feature slug %q", slug)
+	}
+	if !safeRunID.MatchString(runID) {
+		return "", fmt.Errorf("forge: invalid run ID %q", runID)
+	}
+	root, err := physicalExisting(root)
+	if err != nil {
+		return "", err
+	}
+	return filepath.Join(root, ".devrites", "work", slug, ".forge", runID, "manifest.json"), nil
+}
+
+// Load returns the unique manifest for runID below root. Duplicate manifests
+// fail closed instead of letting a caller choose which ownership record wins.
+func Load(root, runID string) (*Manifest, string, error) {
+	if !safeRunID.MatchString(runID) {
+		return nil, "", fmt.Errorf("forge: invalid run ID %q", runID)
+	}
+	root, err := physicalExisting(root)
+	if err != nil {
+		return nil, "", err
+	}
+	paths, err := manifestPaths(root, "")
+	if err != nil {
+		return nil, "", err
+	}
+	var matches []string
+	for _, path := range paths {
+		if filepath.Base(filepath.Dir(path)) == runID {
+			matches = append(matches, path)
+		}
+	}
+	if len(matches) != 1 {
+		return nil, "", fmt.Errorf("forge: run %s has %d manifests; want exactly one", runID, len(matches))
+	}
+	m, err := loadAt(root, matches[0])
+	if err != nil {
+		return nil, "", err
+	}
+	return m, matches[0], nil
+}
+
+func loadAt(root, path string) (*Manifest, error) {
+	if err := validateNoSymlink(root, path); err != nil {
+		return nil, err
+	}
+	info, err := os.Lstat(path)
+	if err != nil {
+		return nil, fmt.Errorf("forge: stat manifest: %w", err)
+	}
+	if !info.Mode().IsRegular() {
+		return nil, fmt.Errorf("forge: manifest is not a regular file: %s", path)
+	}
+	raw, err := os.ReadFile(path)
+	if err != nil {
+		return nil, fmt.Errorf("forge: read manifest: %w", err)
+	}
+	var m Manifest
+	if err := json.Unmarshal(raw, &m); err != nil {
+		return nil, fmt.Errorf("forge: decode manifest: %w", err)
+	}
+	if err := validateManifest(root, path, &m); err != nil {
+		return nil, err
+	}
+	return &m, nil
+}
+
+func validateManifest(root, path string, m *Manifest) error {
+	if m.Schema != Schema || !safeRunID.MatchString(m.RunID) || !safeSlug.MatchString(m.FeatureSlug) {
+		return errors.New("forge: invalid manifest identity")
+	}
+	wantPath, _ := ManifestPath(root, m.FeatureSlug, m.RunID)
+	if filepath.Clean(path) != wantPath {
+		return fmt.Errorf("forge: manifest path mismatch: got %s want %s", path, wantPath)
+	}
+	if m.PrimaryRoot != root {
+		return fmt.Errorf("forge: primary root mismatch: got %s want %s", m.PrimaryRoot, root)
+	}
+	wantForge := forgeRoot(root, m.RunID)
+	if m.ForgeRoot != wantForge {
+		return fmt.Errorf("forge: staging root mismatch: got %s want %s", m.ForgeRoot, wantForge)
+	}
+	if len(m.Candidates) < 2 || len(m.Candidates) > 3 {
+		return fmt.Errorf("forge: manifest has %d candidates; want 2 or 3", len(m.Candidates))
+	}
+	seen := map[CandidateID]bool{}
+	for _, c := range m.Candidates {
+		if seen[c.ID] || !validCandidateID(c.ID) {
+			return fmt.Errorf("forge: invalid or duplicate candidate %q", c.ID)
+		}
+		seen[c.ID] = true
+		wantWorktree := filepath.Join(wantForge, "candidate-"+strings.ToLower(string(c.ID)))
+		wantBranch := candidateBranch(m.RunID, c.ID)
+		if c.Worktree != wantWorktree || c.Branch != wantBranch || c.InitialBase != m.Primary.BaseCommit {
+			return fmt.Errorf("forge: candidate %s ownership fields do not match derived values", c.ID)
+		}
+	}
+	return nil
+}
+
+func save(path string, m *Manifest) error {
+	root := m.PrimaryRoot
+	if err := validateManifest(root, path, m); err != nil {
+		return err
+	}
+	if err := validateNoSymlink(root, filepath.Dir(path)); err != nil && !errors.Is(err, fs.ErrNotExist) {
+		return err
+	}
+	if err := os.MkdirAll(filepath.Dir(path), 0o700); err != nil {
+		return fmt.Errorf("forge: create manifest directory: %w", err)
+	}
+	if err := validateNoSymlink(root, filepath.Dir(path)); err != nil {
+		return err
+	}
+	if info, err := os.Lstat(path); err == nil && !info.Mode().IsRegular() {
+		return fmt.Errorf("forge: refusing to replace non-regular manifest %s", path)
+	} else if err != nil && !errors.Is(err, fs.ErrNotExist) {
+		return fmt.Errorf("forge: stat manifest: %w", err)
+	}
+	raw, err := json.MarshalIndent(m, "", "  ")
+	if err != nil {
+		return fmt.Errorf("forge: encode manifest: %w", err)
+	}
+	raw = append(raw, '\n')
+	tmp, err := os.CreateTemp(filepath.Dir(path), ".manifest-*.tmp")
+	if err != nil {
+		return fmt.Errorf("forge: create manifest temp file: %w", err)
+	}
+	name := tmp.Name()
+	defer os.Remove(name)
+	if err := tmp.Chmod(0o600); err != nil {
+		_ = tmp.Close()
+		return fmt.Errorf("forge: chmod manifest temp file: %w", err)
+	}
+	if _, err := tmp.Write(raw); err != nil {
+		_ = tmp.Close()
+		return fmt.Errorf("forge: write manifest: %w", err)
+	}
+	if err := tmp.Sync(); err != nil {
+		_ = tmp.Close()
+		return fmt.Errorf("forge: sync manifest: %w", err)
+	}
+	if err := tmp.Close(); err != nil {
+		return fmt.Errorf("forge: close manifest: %w", err)
+	}
+	if err := os.Rename(name, path); err != nil {
+		return fmt.Errorf("forge: replace manifest: %w", err)
+	}
+	return nil
+}
+
+func manifestPaths(root, slug string) ([]string, error) {
+	base := filepath.Join(root, ".devrites", "work")
+	if err := validateNoSymlink(root, base); err != nil {
+		if errors.Is(err, fs.ErrNotExist) {
+			return nil, nil
+		}
+		return nil, err
+	}
+	var paths []string
+	err := filepath.WalkDir(base, func(path string, d fs.DirEntry, err error) error {
+		if errors.Is(err, fs.ErrNotExist) {
+			return nil
+		}
+		if err != nil {
+			return err
+		}
+		if d.Type()&os.ModeSymlink != 0 {
+			if d.IsDir() {
+				return filepath.SkipDir
+			}
+			return nil
+		}
+		if d.IsDir() {
+			return nil
+		}
+		rel, err := filepath.Rel(base, path)
+		if err != nil {
+			return err
+		}
+		parts := strings.Split(filepath.ToSlash(rel), "/")
+		if len(parts) == 4 && parts[1] == ".forge" && parts[3] == "manifest.json" && safeSlug.MatchString(parts[0]) && safeRunID.MatchString(parts[2]) {
+			if slug == "" || parts[0] == slug {
+				paths = append(paths, path)
+			}
+		}
+		return nil
+	})
+	if errors.Is(err, fs.ErrNotExist) {
+		return nil, nil
+	}
+	sort.Strings(paths)
+	return paths, err
+}
+
+func validatedManifestPaths(root string) ([]string, error) {
+	paths, err := manifestPaths(root, "")
+	if err != nil {
+		return nil, err
+	}
+	for _, path := range paths {
+		if _, err := loadAt(root, path); err != nil {
+			return nil, err
+		}
+	}
+	return paths, nil
+}
+
+func newIdentity() (runID, nonce string, err error) {
+	raw := make([]byte, 28)
+	if _, err := rand.Read(raw); err != nil {
+		return "", "", fmt.Errorf("forge: generate identity: %w", err)
+	}
+	return "forge-" + hex.EncodeToString(raw[:12]), hex.EncodeToString(raw[12:]), nil
+}
+
+func forgeRoot(root, runID string) string {
+	return filepath.Join(filepath.Dir(root), "."+filepath.Base(root)+".devrites-forge", runID)
+}
+
+func candidateBranch(runID string, id CandidateID) string {
+	return "devrites/forge/" + runID + "/" + strings.ToLower(string(id))
+}
+
+func validCandidateID(id CandidateID) bool {
+	return id == CandidateA || id == CandidateB || id == CandidateC
+}
+
+func now() string {
+	return time.Now().UTC().Format(time.RFC3339Nano)
+}
+
+func physicalExisting(path string) (string, error) {
+	abs, err := filepath.Abs(path)
+	if err != nil {
+		return "", fmt.Errorf("forge: resolve path: %w", err)
+	}
+	real, err := filepath.EvalSymlinks(abs)
+	if err != nil {
+		return "", fmt.Errorf("forge: resolve physical path %s: %w", abs, err)
+	}
+	return filepath.Clean(real), nil
+}
+
+func validateNoSymlink(root, path string) error {
+	root = filepath.Clean(root)
+	path = filepath.Clean(path)
+	rel, err := filepath.Rel(root, path)
+	if err != nil || rel == ".." || strings.HasPrefix(rel, ".."+string(filepath.Separator)) {
+		return fmt.Errorf("forge: path escapes primary root: %s", path)
+	}
+	current := root
+	if rel == "." {
+		return nil
+	}
+	for _, part := range strings.Split(rel, string(filepath.Separator)) {
+		current = filepath.Join(current, part)
+		info, err := os.Lstat(current)
+		if errors.Is(err, fs.ErrNotExist) {
+			return fs.ErrNotExist
+		}
+		if err != nil {
+			return fmt.Errorf("forge: inspect path %s: %w", current, err)
+		}
+		if info.Mode()&os.ModeSymlink != 0 {
+			return fmt.Errorf("forge: symlink is not allowed in manifest path: %s", current)
+		}
+	}
+	return nil
+}

package/engine/internal/gate/gate.go

@@ -1,10 +1,7 @@
-// Package gate implements DevRites' deterministic completeness gates.
-//
-// Enforcement is phase-relative, gate-scoped, and transition-fired: a gate
-// checks only the sections required to make its transition, and only when it is
-// run: never on every tool call. A block is a HITL pause (a structured
-// "missing X" the human resolves and retries), never a crash. Judgment gates
-// stay advisory; these deterministic gates are the ones allowed to block.
+// Package gate implements deterministic completeness checks. Each gate checks
+// only the files required for its transition when the command runs. Missing
+// content returns a human-resolvable block instead of an error. Judgment gates
+// remain advisory; only deterministic checks can block.
 package gate
 
 import (
@@ -15,6 +12,7 @@ import (
 
 	"github.com/devrites/devrites/internal/devritespaths"
 	"github.com/devrites/devrites/internal/orient"
+	"github.com/devrites/devrites/internal/reason"
 	"github.com/devrites/devrites/internal/state"
 )
 
@@ -33,19 +31,20 @@ 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
-	Blocked bool
+	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
 }
 
-// Check runs a gate against feature <slug> under root, reading the files
-// directly (the files are always the source of truth, so a gate never trusts a
-// possibly-stale cache). It returns an error only for a genuinely broken request
-// (unknown slug, unreadable state): a legitimately incomplete feature is a
-// Result with Blocked set, not an error.
+// Check runs a gate against feature <slug> under root. It reads workspace files
+// directly instead of trusting a cache. Invalid requests and unreadable state
+// return errors; missing required content returns a blocked Result.
 func Check(kind Kind, root, slug string) (*Result, error) {
 	f, err := state.LoadFeature(root, slug)
 	if err != nil {
@@ -56,19 +55,46 @@ func Check(kind Kind, root, slug string) (*Result, error) {
 		target = state.PhaseSeal
 	}
 	missing := state.MissingFor(f, target)
-	return &Result{
-		Kind:    kind,
-		Slug:    slug,
-		Phase:   f.Phase,
-		Target:  target,
-		Missing: missing,
-		Blocked: len(missing) > 0,
-	}, nil
+	var missingFiles []string
+	blocked := len(missing) > 0
+	if !f.LegacyLayout {
+		missingFiles = state.MissingWorkspaceFiles(f, target)
+		blocked = len(missingFiles) > 0
+	}
+	result := &Result{
+		Kind:         kind,
+		Slug:         slug,
+		Phase:        f.Phase,
+		Target:       target,
+		Missing:      missing,
+		MissingFiles: missingFiles,
+		LegacyLayout: f.LegacyLayout,
+		Blocked:      blocked,
+	}
+	result.ReasonID = ResultReasonID(kind, blocked)
+	return result, nil
+}
+
+// ResultReasonID returns the typed outcome owned by the lifecycle gate.
+func ResultReasonID(kind Kind, blocked bool) reason.ID {
+	switch kind {
+	case Readiness:
+		if blocked {
+			return reason.GateReadinessMissing
+		}
+		return reason.GateReadinessPassed
+	case Seal:
+		if blocked {
+			return reason.GateSealMissing
+		}
+		return reason.GateSealPassed
+	default:
+		return ""
+	}
 }
 
-// Render produces the deterministic, greppable gate output (with a trailing
-// newline). A block names exactly the missing sections and the resolve step, so
-// a human (or an AFK agent) knows precisely what to fix.
+// Render returns stable, greppable output with a trailing newline. A blocked
+// result names the missing files and the command to rerun.
 func (r *Result) Render() string {
 	var b strings.Builder
 	fmt.Fprintf(&b, "gate: %s\n", r.Kind)
@@ -78,26 +104,28 @@ func (r *Result) Render() string {
 		b.WriteString("result: pass\n")
 		return b.String()
 	}
-	names := sectionNames(r.Missing)
+	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 {
-		fmt.Fprintf(&b, "result: blocked (missing to seal: %s)\n", strings.Join(names, ", "))
+		fmt.Fprintf(&b, "result: blocked (missing to seal: %s)\n", strings.Join(missing, ", "))
 	} else {
-		fmt.Fprintf(&b, "result: blocked (missing to leave %q: %s)\n", r.Phase, strings.Join(names, ", "))
+		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(fileNames(r.Missing), ", "), r.Kind, r.Slug)
+		strings.Join(missing, ", "), r.Kind, r.Slug)
 	return b.String()
 }
 
-// StopGate evaluates the stop-hook rest-point invariant for the active feature:
-// 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.
+// 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.
 //
-// It returns a zero StopResult (Blocked false) (silent, no block) when there
-// is no active feature or the workspace can't be read, keeping the stop hook
-// fail-open.
+// 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 == "" {
@@ -105,16 +133,17 @@ func StopGate(root string) (StopResult, error) {
 	}
 	f, err := state.LoadFeature(root, slug)
 	if err != nil {
-		return StopResult{}, nil // fail-open: a broken workspace never wedges Stop
+		return StopResult{}, nil // Unreadable state does not block Stop.
 	}
-	// Fail-on-red: the redwatch hook marks a known-red suite by writing .red. A turn
-	// must not rest while it is set: evidence over confidence. This is a rest-point
-	// invariant (a concrete, provable inconsistency), not whole-feature completeness.
+	// 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,
+			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),
@@ -122,8 +151,10 @@ func StopGate(root string) (StopResult, error) {
 	}
 	if gates, blocked := unsurfacedHumanGates(featureDir); blocked {
 		return StopResult{
-			Slug:    slug,
-			Blocked: true,
+			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, "/")),
@@ -132,14 +163,16 @@ func StopGate(root string) (StopResult, error) {
 	claimsDone := state.ShippablePhase(f.Phase)
 	if claimsDone && !f.Present[state.SectionProof] {
 		return StopResult{
-			Slug:    slug,
-			Blocked: true,
+			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}, nil
+	return StopResult{Slug: slug, ReasonID: reason.HookStopClear}, nil
 }
 
 const gateSpaceChars = " \t\n\v\f\r"
@@ -216,23 +249,9 @@ func splitLinesNoTrailing(data []byte) []string {
 // 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
-	Blocked bool
-}
-
-func sectionNames(ss []state.Section) []string {
-	out := make([]string, len(ss))
-	for i, s := range ss {
-		out[i] = string(s)
-	}
-	return out
-}
-
-func fileNames(ss []state.Section) []string {
-	out := make([]string, len(ss))
-	for i, s := range ss {
-		out[i] = string(s) + ".md"
-	}
-	return out
+	Slug          string
+	Reason        string
+	ReasonID      reason.ID
+	EvidenceFiles []string
+	Blocked       bool
 }