devrites 7.3.0 → 7.3.2

package/engine/internal/gate/readiness_binding.go

@@ -1,15 +1,18 @@
 package gate
 
 import (
+	"bytes"
 	"crypto/sha256"
 	"encoding/binary"
 	"encoding/hex"
 	"errors"
 	"fmt"
-	"hash"
+	"io"
 	"regexp"
+	"slices"
 	"strings"
 
+	"github.com/devrites/devrites/internal/acceptance"
 	"github.com/devrites/devrites/internal/markdowntext"
 	"github.com/devrites/devrites/internal/state"
 )
@@ -17,7 +20,7 @@ import (
 const (
 	readinessBindingLabel   = "Readiness inputs SHA-256: "
 	readinessBindingDomain  = "devrites-readiness-inputs"
-	readinessBindingVersion = "1"
+	readinessBindingVersion = "2"
 )
 
 type readinessInput struct {
@@ -37,11 +40,15 @@ var readinessInputs = [...]readinessInput{
 	{logical: "design-brief.md"},
 	{logical: "ai-spec.md"},
 	{logical: ".devrites/principles.md"},
+	{logical: acceptance.GatesFile},
 }
 
 // ReadinessBinding returns the exact line Vet records in eng-review.md.
+// Explicit sources resolve live first, then safely archived planning bytes.
+// Gate definitions are bound independently of proof progress. Older bindings
+// omitted those definitions and require normal re-Vet, never automatic refresh.
 func ReadinessBinding(root, slug string) (string, error) {
-	observation, err := state.ObserveWorkspace(root, slug)
+	observation, err := state.ObserveReferencedWorkspace(root, slug)
 	if err != nil {
 		return "", err
 	}
@@ -49,10 +56,6 @@ func ReadinessBinding(root, slug string) (string, error) {
 }
 
 func readinessBindingFromObservation(observation *state.WorkspaceObservation) (string, error) {
-	return bindReadinessInputs(observation, true)
-}
-
-func bindReadinessInputs(observation *state.WorkspaceObservation, blankProgress bool) (string, error) {
 	digest := sha256.New()
 	writeReadinessField(digest, readinessBindingDomain)
 	writeReadinessField(digest, readinessBindingVersion)
@@ -62,7 +65,7 @@ func bindReadinessInputs(observation *state.WorkspaceObservation, blankProgress
 		if err != nil {
 			return "", err
 		}
-		if blankProgress && input.logical == "traceability.md" {
+		if input.logical == "traceability.md" {
 			content = withoutProgressCells(content)
 		}
 		writeReadinessField(digest, string(input.logical))
@@ -84,12 +87,26 @@ func retainedReadinessInput(observation *state.WorkspaceObservation, input readi
 	}
 	switch fact.State() {
 	case state.ArtifactAbsent:
-		if input.required {
+		required := input.required
+		if input.logical == acceptance.GatesFile {
+			phase, err := observation.DeclaredPhase()
+			if err != nil {
+				return nil, false, err
+			}
+			policy, _ := state.PolicyFor(phase)
+			required = policyRequires(policy, input.logical)
+		}
+		if required {
 			return nil, false, fmt.Errorf("readiness input %s is missing", input.logical)
 		}
 		return nil, false, nil
 	case state.ArtifactEmpty, state.ArtifactPresent:
-		return fact.Bytes(), true, nil
+		content := fact.Bytes()
+		if input.logical == acceptance.GatesFile {
+			content, err := normalizedReadinessGates(content)
+			return content, true, err
+		}
+		return content, true, nil
 	case state.ArtifactMalformed, state.ArtifactUnsafe, state.ArtifactUnreadable:
 		diagnostic, _ := fact.Diagnostic()
 		return nil, false, readinessDiagnosticError(diagnostic)
@@ -98,6 +115,25 @@ func retainedReadinessInput(observation *state.WorkspaceObservation, input readi
 	}
 }
 
+// Vet approves obligations, not their checkbox, evidence, or progress prose.
+func normalizedReadinessGates(content []byte) ([]byte, error) {
+	doc := acceptance.ParseLedger(string(content))
+	if len(doc.Errors) > 0 {
+		return nil, fmt.Errorf("readiness input gates.md is malformed: %s", strings.Join(doc.Errors, "; "))
+	}
+	slices.SortFunc(doc.Gates, func(a, b *acceptance.Gate) int {
+		return strings.Compare(a.ID, b.ID)
+	})
+	var normalized bytes.Buffer
+	writeReadinessLength(&normalized, uint64(len(doc.Gates)))
+	for _, gate := range doc.Gates {
+		for _, field := range [...]string{gate.ID, gate.Title, gate.Check, gate.Expect, gate.Cwd, gate.Inputs, gate.Run} {
+			writeReadinessField(&normalized, field)
+		}
+	}
+	return normalized.Bytes(), nil
+}
+
 func readinessDiagnostics(observation *state.WorkspaceObservation) []state.ArtifactDiagnostic {
 	var diagnostics []state.ArtifactDiagnostic
 	for _, input := range readinessInputs {
@@ -117,12 +153,6 @@ func verifyReadinessBinding(observation *state.WorkspaceObservation) (string, er
 	if err != nil {
 		return "", err
 	}
-	// A line recorded over the raw bytes, before progress cells were blanked,
-	// still verifies while those bytes are unchanged.
-	legacy, err := bindReadinessInputs(observation, false)
-	if err != nil {
-		return "", err
-	}
 	fact, ok := observation.Fact("eng-review.md")
 	if !ok || fact.State() == state.ArtifactAbsent {
 		return expected, errors.New("readiness input eng-review.md is missing")
@@ -143,7 +173,7 @@ func verifyReadinessBinding(observation *state.WorkspaceObservation) (string, er
 			continue
 		}
 		attempts++
-		if line == expected || line == legacy {
+		if line == expected {
 			matches++
 		}
 	}
@@ -154,9 +184,9 @@ func verifyReadinessBinding(observation *state.WorkspaceObservation) (string, er
 }
 
 // ReadinessInputDigest is one readiness input's content identity at a moment
-// in time. The aggregate binding answers "did anything change"; the per-input
-// digest answers "which artifact changed", which is what a drift diagnosis and
-// a re-vet route need.
+// in time (canonical definitions only for gates.md). The aggregate binding
+// answers "did anything change"; the per-input digest answers "which artifact
+// changed", which is what a drift diagnosis and a re-vet route need.
 type ReadinessInputDigest struct {
 	Path    string `json:"path"`
 	Present bool   `json:"present"`
@@ -180,9 +210,9 @@ func withoutReviewedIdentity(content []byte) []byte {
 // ReadinessInputDigests returns each readiness input's content digest plus the
 // aggregate binding line Vet records in eng-review.md. A required input that
 // is missing, or any unreadable input, is an error — the same refusal the
-// readiness gate applies.
+// readiness gate applies. Source selection matches ReadinessBinding.
 func ReadinessInputDigests(root, slug string) ([]ReadinessInputDigest, string, error) {
-	observation, err := state.ObserveWorkspace(root, slug)
+	observation, err := state.ObserveReferencedWorkspace(root, slug)
 	if err != nil {
 		return nil, "", err
 	}
@@ -321,12 +351,12 @@ func policyRequires(policy state.PhasePolicy, name state.ArtifactPath) bool {
 	return false
 }
 
-func writeReadinessField(digest hash.Hash, value string) {
+func writeReadinessField(digest io.Writer, value string) {
 	writeReadinessLength(digest, uint64(len(value)))
 	_, _ = digest.Write([]byte(value))
 }
 
-func writeReadinessLength(digest hash.Hash, value uint64) {
+func writeReadinessLength(digest io.Writer, value uint64) {
 	var encoded [8]byte
 	binary.BigEndian.PutUint64(encoded[:], value)
 	_, _ = digest.Write(encoded[:])

package/engine/internal/install/apply.go

@@ -16,6 +16,10 @@ import (
 )
 
 func (r *runner) install() error {
+	if err := r.openTargetRoot(); err != nil {
+		return err
+	}
+	defer r.closeTargetRoot()
 	fmt.Fprintln(r.opts.Stdout, "DevRites installer")
 	fmt.Fprintf(r.opts.Stdout, "  target : %s\n", r.target)
 	fmt.Fprintf(r.opts.Stdout, "  payload: %s\n", r.payload)
@@ -43,6 +47,10 @@ func (r *runner) install() error {
 	if err := r.preflightInstall(); err != nil {
 		return err
 	}
+	// Complete binary installation before changing payload ownership or version.
+	if err := r.installBinary(); err != nil {
+		return fmt.Errorf("install engine binary: %w", err)
+	}
 
 	for _, tree := range hostpack.InstallTrees(r.opts.WithSkills, r.opts.WithAgents, r.opts.WithCodex, r.opts.WithOmp, r.opts.WithPi, r.opts.WithDevin, r.opts.WithDsh) {
 		if err := r.installTree(tree.PayloadPrefix, tree.TargetPrefix); err != nil {
@@ -106,9 +114,6 @@ func (r *runner) install() error {
 			return fmt.Errorf("write manifest: %w", err)
 		}
 	}
-	if err := r.installBinary(); err != nil {
-		return fmt.Errorf("install engine binary: %w", err)
-	}
 
 	fmt.Fprintln(r.opts.Stdout)
 	if r.opts.DryRun {
@@ -218,19 +223,32 @@ func (r *runner) installData(data []byte, rel string) error {
 	return nil
 }
 
-// writeConfined writes dest, which must lie under the install target, through
-// a root opened on the target so a directory component replaced by a symlink
-// after the path recheck cannot redirect the write.
-func (r *runner) writeConfined(dest string, data []byte, perm fs.FileMode) error {
-	rel, err := filepath.Rel(r.target, dest)
+func (r *runner) readConfined(path string) ([]byte, error) {
+	rel, err := filepath.Rel(r.target, path)
 	if err != nil {
-		return err
+		return nil, err
+	}
+	if r.targetRoot != nil {
+		return r.targetRoot.ReadFile(rel)
 	}
 	root, err := os.OpenRoot(r.target)
 	if err != nil {
-		return err
+		return nil, err
 	}
 	defer func() { _ = root.Close() }()
+	return root.ReadFile(rel)
+}
+
+// writeConfined uses the operation's validated root, not its mutable pathname.
+func (r *runner) writeConfined(dest string, data []byte, perm fs.FileMode) error {
+	rel, err := filepath.Rel(r.target, dest)
+	if err != nil {
+		return err
+	}
+	root := r.targetRoot
+	if root == nil {
+		return fmt.Errorf("install target is not open")
+	}
 	if info, err := root.Stat(rel); err == nil {
 		perm = info.Mode().Perm()
 	} else if !os.IsNotExist(err) {
@@ -239,18 +257,16 @@ func (r *runner) writeConfined(dest string, data []byte, perm fs.FileMode) error
 	return fsutil.WriteFileAtomicIn(root, rel, data, perm)
 }
 
-// removeConfined removes dest, which must lie under the install target,
-// through a root opened on the target.
+// removeConfined uses the same retained root as writes and managed reads.
 func (r *runner) removeConfined(dest string) error {
 	rel, err := filepath.Rel(r.target, dest)
 	if err != nil {
 		return err
 	}
-	root, err := os.OpenRoot(r.target)
-	if err != nil {
-		return err
+	root := r.targetRoot
+	if root == nil {
+		return fmt.Errorf("install target is not open")
 	}
-	defer func() { _ = root.Close() }()
 	return root.Remove(rel)
 }
 
@@ -285,11 +301,10 @@ func (r *runner) seedDevrites() error {
 		fmt.Fprintln(r.opts.Stdout, "  [seed] .devrites/ACTIVE (runtime state - preserved on uninstall)")
 		return nil
 	}
-	if err := os.MkdirAll(filepath.Dir(active), 0o755); err != nil {
+	if err := r.targetRoot.MkdirAll(".devrites", 0o755); err != nil {
 		return fmt.Errorf("create %s: %w", filepath.Dir(active), err)
 	}
-	// #nosec G304 -- active path is the operator-selected install dir (O_EXCL create)
-	f, err := os.OpenFile(active, os.O_CREATE|os.O_EXCL, 0o644)
+	f, err := r.targetRoot.OpenFile(filepath.Join(".devrites", "ACTIVE"), os.O_CREATE|os.O_EXCL, 0o644)
 	if err != nil {
 		if os.IsExist(err) {
 			return nil
@@ -342,7 +357,7 @@ func (r *runner) relinquishEditedHostConfigs() (map[string]bool, error) {
 func (r *runner) seedHostConfig(config hostpack.HostConfig) error {
 	if _, managed := r.prev[config.Rel]; !managed {
 		// #nosec G304 -- fixed host config path under the operator target
-		data, err := os.ReadFile(filepath.Join(r.target, filepath.FromSlash(config.Rel)))
+		data, err := r.readConfined(filepath.Join(r.target, filepath.FromSlash(config.Rel)))
 		if err == nil && string(data) != config.Content {
 			if !strings.Contains(string(data), config.Applied) {
 				fmt.Fprintf(r.opts.Stderr, "warning: %s exists and was not changed; to hide duplicate DevRites skills in %s, add: %s\n", config.Rel, config.Host, config.Advice)
@@ -408,7 +423,7 @@ func (r *runner) pruneDropped() error {
 			if err := r.removeConfined(dead); err != nil && !os.IsNotExist(err) {
 				return fmt.Errorf("remove %s: %w", rel, err)
 			}
-			pruneEmptyDirs(filepath.Dir(dead), r.target)
+			r.pruneEmptyDirs(filepath.Dir(dead))
 			fmt.Fprintf(r.opts.Stdout, "  [%s] %s\n", action, rel)
 		}
 		r.stats.pruned++

package/engine/internal/install/binary.go

@@ -63,11 +63,20 @@ func (r *runner) installBinary() error {
 	if err != nil {
 		return err
 	}
+	removeBackup := true
 	if backup != "" {
-		defer func() { _ = os.Remove(backup) }()
+		defer func() {
+			if removeBackup {
+				_ = os.Remove(backup)
+			}
+		}()
 	}
 	if err := fsutil.WriteFileAtomic(dest, data, 0o755); err != nil {
 		if restoreErr := restoreBinary(dest, backup, oldMode, hadOld); restoreErr != nil {
+			removeBackup = false
+			if backup != "" {
+				restoreErr = fmt.Errorf("%w (previous binary retained at %s)", restoreErr, backup)
+			}
 			return fmt.Errorf("install binary: %v; restore previous binary: %w", err, restoreErr)
 		}
 		return err
@@ -75,6 +84,10 @@ func (r *runner) installBinary() error {
 	_ = os.Chmod(dest, 0o755)
 	if _, err := verifyEngineBinary(dest, tag, 30*time.Second); err != nil {
 		if restoreErr := restoreBinary(dest, backup, oldMode, hadOld); restoreErr != nil {
+			removeBackup = false
+			if backup != "" {
+				restoreErr = fmt.Errorf("%w (previous binary retained at %s)", restoreErr, backup)
+			}
 			return fmt.Errorf("verify installed engine binary: %v; restore previous binary: %w", err, restoreErr)
 		}
 		if hadOld {
@@ -173,6 +186,44 @@ func (r *runner) acquireBinary(tag string) (string, func(), error) {
 	return path, func() {}, nil
 }
 
+func (r *runner) preflightBinaryRemoval() error {
+	if runtime.GOOS != "windows" || r.opts.DryRun || r.opts.KeepBinary || !r.opts.WithBinary || os.Getenv("DEVRITES_NO_BINARY") == "1" {
+		return nil
+	}
+	for _, path := range binaryCandidates() {
+		info, err := os.Lstat(path)
+		if os.IsNotExist(err) {
+			continue
+		}
+		if err != nil {
+			return fmt.Errorf("inspect engine binary %s: %w", path, err)
+		}
+		if info.Mode()&os.ModeSymlink != 0 {
+			info, err = os.Stat(path)
+			if os.IsNotExist(err) {
+				return nil
+			}
+			if err != nil {
+				return fmt.Errorf("inspect engine binary %s: %w", path, err)
+			}
+		}
+		executable, err := os.Executable()
+		if err != nil {
+			return fmt.Errorf("locate running engine binary: %w", err)
+		}
+		running, err := os.Stat(executable)
+		if err != nil {
+			return fmt.Errorf("inspect running engine binary %s: %w", executable, err)
+		}
+		if os.SameFile(info, running) {
+			return fmt.Errorf("cannot remove running engine binary %s on Windows; use npx devrites@latest uninstall --target %q or --keep-binary", path, r.target)
+		}
+		// Removal stops at the first existing candidate, even if another is running.
+		return nil
+	}
+	return nil
+}
+
 func (r *runner) removeBinary() error {
 	if r.opts.KeepBinary {
 		fmt.Fprintln(r.opts.Stdout, "  kept the global devrites-engine binary (--keep-binary).")
@@ -187,17 +238,24 @@ func (r *runner) removeBinary() error {
 		return nil
 	}
 	for _, p := range binaryCandidates() {
-		if p == "" || !exists(p) {
-			continue
-		}
 		if r.opts.DryRun {
+			if _, err := os.Lstat(p); err != nil {
+				if os.IsNotExist(err) {
+					continue
+				}
+				return fmt.Errorf("inspect engine binary %s: %w", p, err)
+			}
 			fmt.Fprintf(r.opts.Stdout, "  [remove] %s (global engine binary)\n", p)
 			continue
 		}
-		if err := os.Remove(p); err == nil {
-			fmt.Fprintf(r.opts.Stdout, "  [remove] %s\n", p)
-			return nil
+		if err := os.Remove(p); err != nil {
+			if os.IsNotExist(err) {
+				continue
+			}
+			return fmt.Errorf("remove %s: %w", p, err)
 		}
+		fmt.Fprintf(r.opts.Stdout, "  [remove] %s\n", p)
+		return nil
 	}
 	return nil
 }
@@ -220,10 +278,10 @@ func engineBinaryName() string {
 }
 
 func binaryCandidates() []string {
-	candidates := []string{}
 	if dir := os.Getenv("DEVRITES_BIN_DIR"); dir != "" {
-		candidates = append(candidates, filepath.Join(dir, engineBinaryName()))
+		return []string{filepath.Join(dir, engineBinaryName())}
 	}
+	candidates := []string{}
 	home, _ := os.UserHomeDir()
 	if home != "" {
 		candidates = append(candidates, filepath.Join(home, ".local", "bin", engineBinaryName()))

package/engine/internal/install/install.go

@@ -61,6 +61,8 @@ type stats struct {
 type runner struct {
 	opts              Options
 	target            string
+	targetInfo        fs.FileInfo
+	targetRoot        *os.Root
 	payload           string
 	payloadFS         fs.FS
 	source            string
@@ -246,6 +248,10 @@ func Apply(opts Options) error {
 		return fmt.Errorf("prepare installer: %w", err)
 	}
 	if opts.Mode == ModeUninstall {
+		if err := r.openTargetRoot(); err != nil {
+			return err
+		}
+		defer r.closeTargetRoot()
 		return r.uninstall()
 	}
 	if err := r.install(); err != nil {
@@ -297,27 +303,75 @@ func newRunner(opts Options) (*runner, error) {
 		}
 	}
 	r := &runner{
-		opts:      opts,
-		target:    target,
-		payload:   payload,
-		payloadFS: os.DirFS(payload),
-		source:    source,
-		prev:      map[string]managedRecord{},
-		records:   map[string]string{},
-		preflight: map[string]pathSnapshot{},
+		opts:       opts,
+		target:     target,
+		targetInfo: info,
+		payload:    payload,
+		payloadFS:  os.DirFS(payload),
+		source:     source,
+		prev:       map[string]managedRecord{},
+		records:    map[string]string{},
+		preflight:  map[string]pathSnapshot{},
 	}
 	if opts.Mode != ModeUninstall {
 		if err := r.validatePayload(); err != nil {
 			return nil, fmt.Errorf("validate payload: %w", err)
 		}
 	}
-	r.prev, err = readManifest(filepath.Join(target, ManifestName))
+	if err := r.openTargetRoot(); err != nil {
+		return nil, err
+	}
+	defer r.closeTargetRoot()
+	data, err := r.readConfined(filepath.Join(target, ManifestName))
+	if err != nil && !os.IsNotExist(err) {
+		return nil, fmt.Errorf("read manifest %s: %w", ManifestName, err)
+	}
+	r.prev, _, err = parseManifestData(data)
 	if err != nil {
 		return nil, err
 	}
 	return r, nil
 }
 
+func (r *runner) openTargetRoot() error {
+	root, err := os.OpenRoot(r.target)
+	if err != nil {
+		return err
+	}
+	info, err := root.Stat(".")
+	if err != nil || r.targetInfo == nil || !os.SameFile(r.targetInfo, info) {
+		_ = root.Close()
+		return fmt.Errorf("install target changed before operation: %s", r.target)
+	}
+	r.targetRoot = root
+	return nil
+}
+
+func (r *runner) closeTargetRoot() {
+	if r.targetRoot != nil {
+		_ = r.targetRoot.Close()
+		r.targetRoot = nil
+	}
+}
+
+func (r *runner) checkTargetIdentity() error {
+	info, err := os.Stat(r.target)
+	if err != nil || r.targetInfo == nil || !os.SameFile(r.targetInfo, info) {
+		return fmt.Errorf("install target changed during operation: %s", r.target)
+	}
+	return nil
+}
+
+func (r *runner) pruneEmptyDirs(start string) {
+	for start != r.target && start != filepath.Dir(start) {
+		rel, err := filepath.Rel(r.target, start)
+		if err != nil || r.targetRoot == nil || r.targetRoot.Remove(rel) != nil {
+			return
+		}
+		start = filepath.Dir(start)
+	}
+}
+
 func inferSourceDir() string {
 	if v := os.Getenv("DEVRITES_SOURCE_DIR"); v != "" {
 		return v
@@ -390,18 +444,6 @@ func isGlobalTarget(target string) bool {
 	return false
 }
 
-func pruneEmptyDirs(start, stop string) {
-	for {
-		if start == stop || start == filepath.Dir(start) || start == string(os.PathSeparator) {
-			return
-		}
-		if err := os.Remove(start); err != nil {
-			return
-		}
-		start = filepath.Dir(start)
-	}
-}
-
 func exists(path string) bool {
 	// #nosec G703 -- existence probe on managed install paths
 	_, err := os.Lstat(path)

package/engine/internal/install/manifest.go

@@ -19,11 +19,6 @@ func readManifest(path string) (map[string]managedRecord, error) {
 	return records, err
 }
 
-func readManifestList(path string) ([]string, error) {
-	_, entries, err := parseManifest(path)
-	return entries, err
-}
-
 func parseManifest(path string) (map[string]managedRecord, []string, error) {
 	// #nosec G304 -- install manifest under the operator-selected target
 	data, err := os.ReadFile(path)
@@ -33,6 +28,10 @@ func parseManifest(path string) (map[string]managedRecord, []string, error) {
 		}
 		return nil, nil, fmt.Errorf("read manifest %s: %w", path, err)
 	}
+	return parseManifestData(data)
+}
+
+func parseManifestData(data []byte) (map[string]managedRecord, []string, error) {
 	hashes := map[string]string{}
 	var out []string
 	for _, line := range strings.Split(string(data), "\n") {