devrites 5.11.0 → 5.12.0

package/engine/internal/lib/dispatch.go

@@ -0,0 +1,302 @@
+package lib
+
+import (
+	"encoding/json"
+	"fmt"
+	"io"
+	"os"
+	"path/filepath"
+	"strings"
+	"time"
+
+	"github.com/devrites/devrites/internal/devritespaths"
+)
+
+// dispatch.go: launch-wave barrier for host-native agent dispatch. Hosts own
+// the actual agent sessions; this command owns the wave state machine so a
+// fan-out cannot silently degrade to serial (open -> every role started ->
+// seal -> returns -> complete). start/return also auto-record metrics events.
+//
+//	devrites-engine dispatch <slug> <sub> [--phase p] [--wave w] [--role r] [--handle h] [--reason s]
+
+const dispatchUsage = `usage: devrites-engine dispatch <slug> <open|start|seal|return|status|abandon> [--phase p] [--wave w] [--role r] [--handle h] [--reason s]
+
+Wave barrier for parallel agent dispatch: seal fails until every declared
+role has a distinct handle; return fails before seal; status exits nonzero
+while a wave is open, sealed, or abandoned.
+`
+
+type dispatchFile struct {
+	Waves map[string]*dispatchWave `json:"waves"`
+}
+
+type dispatchWave struct {
+	Phase string                   `json:"phase"`
+	State string                   `json:"state"` // open, sealed, abandoned, complete
+	Roles map[string]*dispatchRole `json:"roles"`
+}
+
+type dispatchRole struct {
+	Handle    string `json:"handle,omitempty"`
+	StartedAt string `json:"started,omitempty"`
+	Returned  bool   `json:"returned,omitempty"`
+}
+
+func dispatchPath(root, slug string) string {
+	return filepath.Join(devritespaths.FeatureDir(root, slug), "dispatch.json")
+}
+
+func loadDispatch(root, slug string) (*dispatchFile, string, error) {
+	path := dispatchPath(root, slug)
+	f := &dispatchFile{Waves: map[string]*dispatchWave{}}
+	data, err := os.ReadFile(path) // #nosec G304 -- path is a validated feature workspace artifact
+	if os.IsNotExist(err) {
+		return f, path, nil
+	}
+	if err != nil {
+		return nil, path, err
+	}
+	if err := json.Unmarshal(data, f); err != nil {
+		return nil, path, fmt.Errorf("dispatch.json is not valid JSON: %w", err)
+	}
+	if f.Waves == nil {
+		f.Waves = map[string]*dispatchWave{}
+	}
+	// Fail closed on hand-edited impossible state.
+	for name, w := range f.Waves {
+		if w.Roles == nil || w.State == "" {
+			return nil, path, fmt.Errorf("wave %q is malformed (missing state or roles)", name)
+		}
+	}
+	return f, path, nil
+}
+
+func saveDispatch(path string, f *dispatchFile) error {
+	data, err := json.MarshalIndent(f, "", "  ")
+	if err != nil {
+		return err
+	}
+	if err := os.MkdirAll(filepath.Dir(path), 0o755); err != nil {
+		return err
+	}
+	return os.WriteFile(path, data, 0o600)
+}
+
+func nowStamp() string { return time.Now().UTC().Format(time.RFC3339) }
+
+// RunDispatch implements the dispatch wave state machine.
+func RunDispatch(root string, args []string, stdout, stderr io.Writer) int {
+	var slug, sub, phase, wave, role, handle, reason string
+	var roles []string
+	var positional []string
+	for i := 0; i < len(args); i++ {
+		value := argAt(args, i+1)
+		switch args[i] {
+		case "--phase":
+			phase = value
+		case "--wave":
+			wave = value
+		case "--role":
+			roles = append(roles, value)
+			role = value
+		case "--handle":
+			handle = value
+		case "--reason":
+			reason = value
+		default:
+			if strings.HasPrefix(args[i], "-") {
+				fmt.Fprintf(stderr, "dispatch: unknown flag %q\n", args[i])
+				return 2
+			}
+			positional = append(positional, args[i])
+			continue
+		}
+		i++
+	}
+	if len(positional) != 2 {
+		fmt.Fprint(stderr, dispatchUsage)
+		return 2
+	}
+	slug, sub = positional[0], positional[1]
+	if _, err := devritespaths.ExistingFeatureDirChecked(root, slug); err != nil {
+		fmt.Fprintf(stderr, "dispatch: %v\n", err)
+		return 2
+	}
+	f, path, err := loadDispatch(root, slug)
+	if err != nil {
+		fmt.Fprintf(stderr, "dispatch: %v\n", err)
+		return 3
+	}
+
+	fail := func(format string, a ...any) int {
+		fmt.Fprintf(stderr, "dispatch: "+format+"\n", a...)
+		return 3
+	}
+	getWave := func() *dispatchWave {
+		w := f.Waves[wave]
+		if w == nil {
+			return nil
+		}
+		return w
+	}
+
+	switch sub {
+	case "open":
+		if phase == "" || wave == "" || len(roles) == 0 {
+			fmt.Fprint(stderr, dispatchUsage)
+			return 2
+		}
+		if w := getWave(); w != nil && w.State != "abandoned" {
+			return fail("wave %q already exists (state %s)", wave, w.State)
+		}
+		w := &dispatchWave{Phase: phase, State: "open", Roles: map[string]*dispatchRole{}}
+		for _, r := range roles {
+			if w.Roles[r] != nil {
+				return fail("duplicate role %q in wave", r)
+			}
+			w.Roles[r] = &dispatchRole{}
+		}
+		f.Waves[wave] = w
+		if err := saveDispatch(path, f); err != nil {
+			return fail("%v", err)
+		}
+		fmt.Fprintf(stdout, "dispatch: wave %s open, %d roles declared\n", wave, len(roles))
+		return 0
+
+	case "start":
+		w := getWave()
+		if w == nil || w.State != "open" {
+			return fail("wave %q is not open (state %s)", wave, waveState(w))
+		}
+		r := w.Roles[role]
+		if r == nil {
+			return fail("role %q not declared in wave %q", role, wave)
+		}
+		if handle == "" {
+			return fail("--handle is required (host agent id)")
+		}
+		for name, other := range w.Roles {
+			if name != role && other.Handle == handle {
+				return fail("handle %q already used by role %q — distinct handle required", handle, name)
+			}
+		}
+		if r.Handle != "" {
+			return fail("role %q already started (handle %q)", role, r.Handle)
+		}
+		r.Handle = handle
+		r.StartedAt = nowStamp()
+		if err := saveDispatch(path, f); err != nil {
+			return fail("%v", err)
+		}
+		recordMetric(root, slug, w.Phase, "dispatch", role, 0)
+		fmt.Fprintf(stdout, "dispatch: %s started (handle %s)\n", role, handle)
+		return 0
+
+	case "seal":
+		w := getWave()
+		if w == nil || w.State != "open" {
+			return fail("wave %q is not open (state %s)", wave, waveState(w))
+		}
+		var missing []string
+		for name, r := range w.Roles {
+			if r.Handle == "" {
+				missing = append(missing, name)
+			}
+		}
+		if len(missing) > 0 {
+			return fail("wave %q cannot seal: no start handle for %s", wave, strings.Join(missing, ","))
+		}
+		w.State = "sealed"
+		if err := saveDispatch(path, f); err != nil {
+			return fail("%v", err)
+		}
+		fmt.Fprintf(stdout, "dispatch: wave %s sealed (%d roles)\n", wave, len(w.Roles))
+		return 0
+
+	case "return":
+		w := getWave()
+		if w == nil || w.State != "sealed" {
+			return fail("wave %q is not sealed (state %s)", wave, waveState(w))
+		}
+		r := w.Roles[role]
+		if r == nil {
+			return fail("role %q not declared in wave %q", role, wave)
+		}
+		if r.Returned {
+			return fail("role %q already returned", role)
+		}
+		r.Returned = true
+		all := true
+		for _, o := range w.Roles {
+			if !o.Returned {
+				all = false
+			}
+		}
+		if all {
+			w.State = "complete"
+		}
+		if err := saveDispatch(path, f); err != nil {
+			return fail("%v", err)
+		}
+		recordMetric(root, slug, w.Phase, "return", role, 0)
+		fmt.Fprintf(stdout, "dispatch: %s returned (wave %s %s)\n", role, wave, w.State)
+		return 0
+
+	case "status":
+		if wave == "" {
+			for name, w := range f.Waves {
+				fmt.Fprintf(stdout, "dispatch: wave %s state=%s roles=%d\n", name, w.State, len(w.Roles))
+			}
+			if len(f.Waves) == 0 {
+				fmt.Fprintln(stdout, "dispatch: no waves")
+			}
+			return 0
+		}
+		w := getWave()
+		if w == nil {
+			return fail("no wave %q", wave)
+		}
+		var pending []string
+		for name, r := range w.Roles {
+			mark := "declared"
+			if r.Handle != "" {
+				mark = "started"
+			}
+			if r.Returned {
+				mark = "returned"
+			} else {
+				pending = append(pending, name)
+			}
+			fmt.Fprintf(stdout, "dispatch: %s %s=%s\n", wave, name, mark)
+		}
+		if w.State != "complete" {
+			return fail("wave %q state=%s pending=%s", wave, w.State, strings.Join(pending, ","))
+		}
+		fmt.Fprintf(stdout, "dispatch: wave %s complete\n", wave)
+		return 0
+
+	case "abandon":
+		w := getWave()
+		if w == nil {
+			return fail("no wave %q", wave)
+		}
+		if strings.TrimSpace(reason) == "" {
+			return fail("--reason is required (non-empty, surfaced in handoff)")
+		}
+		w.State = "abandoned"
+		if err := saveDispatch(path, f); err != nil {
+			return fail("%v", err)
+		}
+		fmt.Fprintf(stdout, "dispatch: wave %s abandoned: %s\n", wave, reason)
+		return fail("wave %q is abandoned — HANDOFF REQUIRED: %s", wave, reason)
+	}
+	fmt.Fprint(stderr, dispatchUsage)
+	return 2
+}
+
+func waveState(w *dispatchWave) string {
+	if w == nil {
+		return "absent"
+	}
+	return w.State
+}

package/engine/internal/lib/drift.go

@@ -0,0 +1,219 @@
+package lib
+
+import (
+	"encoding/json"
+	"fmt"
+	"io"
+	"os"
+	"path/filepath"
+	"sort"
+	"strings"
+	"time"
+
+	"github.com/devrites/devrites/internal/devritespaths"
+	"github.com/devrites/devrites/internal/gate"
+	"github.com/devrites/devrites/internal/state"
+)
+
+// drift.go: readiness-input drift diagnosis. Vet records one aggregate
+// "Readiness inputs SHA-256" line in eng-review.md; readiness/seal refuse when
+// it no longer matches. That answer is binary — the agent learns the inputs
+// changed but not which artifact did, so repair starts by re-reading eleven
+// files. This check keeps a per-input digest baseline and attributes drift to
+// the exact artifact, so the Spec Drift Guard or a re-vet starts at the right
+// file.
+//
+//	devrites-engine check drift <slug>            compare vs recorded digests
+//	devrites-engine check drift <slug> --record   write the digest baseline
+//
+//	0  always — drift is advisory: a dated delta through the owning rite is
+//	   legal, so this command reports rather than blocks
+//	2  usage error or workspace unreadable
+//	3  baseline exists but cannot be parsed (fail closed on corrupt state)
+//
+// Without a baseline the check falls back to the aggregate binding recorded in
+// eng-review.md; attribution then lists inputs whose mtime is newer than
+// eng-review.md as candidates.
+
+const driftBaselineFile = "readiness-inputs.json"
+
+// driftBaseline is the recorded per-input digest set for one workspace.
+type driftBaseline struct {
+	Version    int                         `json:"version"`
+	RecordedAt string                      `json:"recorded_at"`
+	Binding    string                      `json:"binding"`
+	Inputs     []gate.ReadinessInputDigest `json:"inputs"`
+}
+
+// driftDiff is one input whose state differs from the baseline.
+type driftDiff struct {
+	Path string `json:"path"`
+	Kind string `json:"kind"` // changed | missing | added
+}
+
+// RunCheckDrift implements `devrites-engine check drift`.
+func RunCheckDrift(root string, args []string, stdout, stderr io.Writer) int {
+	if len(args) < 1 || len(args) > 2 {
+		fmt.Fprintln(stderr, driftUsage)
+		return 2
+	}
+	slug := args[0]
+	record := false
+	if len(args) == 2 {
+		if args[1] != "--record" {
+			fmt.Fprintln(stderr, driftUsage)
+			return 2
+		}
+		record = true
+	}
+	workspace, err := devritespaths.ExistingFeatureDirChecked(root, slug)
+	if err != nil {
+		fmt.Fprintf(stderr, "check drift: %v\n", err)
+		return 2
+	}
+	digests, binding, err := gate.ReadinessInputDigests(root, slug)
+	if err != nil {
+		fmt.Fprintf(stderr, "check drift: %v\n", err)
+		return 2
+	}
+	baselinePath := filepath.Join(workspace, driftBaselineFile)
+	if record {
+		return recordDriftBaseline(root, slug, baselinePath, digests, binding, stdout, stderr)
+	}
+	return compareDrift(workspace, baselinePath, digests, binding, stdout, stderr)
+}
+
+// recordDriftBaseline writes the current per-input digests as the baseline.
+func recordDriftBaseline(root, slug, baselinePath string, digests []gate.ReadinessInputDigest, binding string, stdout, stderr io.Writer) int {
+	baseline := driftBaseline{
+		Version:    1,
+		RecordedAt: time.Now().UTC().Format(time.RFC3339),
+		Binding:    binding,
+		Inputs:     digests,
+	}
+	payload, err := json.MarshalIndent(baseline, "", "  ")
+	if err != nil {
+		fmt.Fprintf(stderr, "check drift: marshal baseline: %v\n", err)
+		return 2
+	}
+	writeErr := state.WithFeatureLock(root, slug, func() error {
+		return state.AtomicWrite(baselinePath, append(payload, '\n'), 0o644)
+	})
+	if writeErr != nil {
+		fmt.Fprintf(stderr, "check drift: write baseline: %v\n", writeErr)
+		return 2
+	}
+	fmt.Fprintf(stdout, "check drift: baseline recorded (%d inputs, %s)\n", len(digests), binding)
+	recordMetric(root, slug, "", "drift-baseline", "", 0)
+	return 0
+}
+
+// compareDrift diffs current inputs against the baseline, or falls back to the
+// aggregate binding recorded in eng-review.md when no baseline exists.
+func compareDrift(workspace, baselinePath string, digests []gate.ReadinessInputDigest, binding string, stdout, stderr io.Writer) int {
+	baseline, hasBaseline, err := readDriftBaseline(baselinePath)
+	if err != nil {
+		fmt.Fprintf(stdout, "DRIFT: baseline %s unreadable: %v\ncheck drift: BLOCKED\n", driftBaselineFile, err)
+		return 3
+	}
+	if !hasBaseline {
+		return compareDriftFallback(workspace, binding, stdout)
+	}
+	diffs := diffInputs(baseline.Inputs, digests)
+	if len(diffs) == 0 && baseline.Binding == binding {
+		fmt.Fprintf(stdout, "check drift: none (baseline %s)\n", baseline.RecordedAt)
+		return 0
+	}
+	for _, d := range diffs {
+		fmt.Fprintf(stdout, "DRIFT: %s %s since baseline %s\n", d.Path, d.Kind, baseline.RecordedAt)
+	}
+	if baseline.Binding != binding && len(diffs) == 0 {
+		fmt.Fprintln(stdout, "DRIFT: aggregate binding changed without a recorded input diff; re-record the baseline")
+	}
+	fmt.Fprintf(stdout, "check drift: %d input(s) differ — a change is legal only as a dated delta through the owning rite; otherwise restore the input or rerun /rite-vet and --record\n", len(diffs))
+	return 0
+}
+
+// compareDriftFallback compares the aggregate binding recorded in eng-review.md
+// and attributes candidates by modification time.
+func compareDriftFallback(workspace, binding string, stdout io.Writer) int {
+	engReview := filepath.Join(workspace, "eng-review.md")
+	raw, err := os.ReadFile(engReview) // #nosec G304 -- workspace artifact
+	if err != nil {
+		fmt.Fprintf(stdout, "check drift: unproven — no %s baseline and no readable eng-review.md; run `check drift <slug> --record` after Vet writes the binding\n", driftBaselineFile)
+		return 0
+	}
+	recorded := ""
+	for _, line := range strings.Split(string(raw), "\n") {
+		if strings.Contains(line, "Readiness inputs SHA-256: ") {
+			recorded = strings.TrimSpace(line)
+		}
+	}
+	if recorded == "" {
+		fmt.Fprintf(stdout, "check drift: unproven — eng-review.md carries no readiness binding; run `check drift <slug> --record` after Vet writes it\n")
+		return 0
+	}
+	if recorded == binding {
+		fmt.Fprintln(stdout, "check drift: none (eng-review.md binding current)")
+		return 0
+	}
+	fmt.Fprintf(stdout, "DRIFT: readiness inputs changed since the eng-review.md binding\nrecorded: %s\ncurrent:  %s\n", recorded, binding)
+	reviewInfo, err := os.Stat(engReview)
+	if err == nil {
+		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", "ai-spec.md"} {
+			if info, err := os.Stat(filepath.Join(workspace, name)); err == nil && info.ModTime().After(reviewInfo.ModTime()) {
+				fmt.Fprintf(stdout, "candidate: %s modified after eng-review.md\n", name)
+			}
+		}
+	}
+	fmt.Fprintln(stdout, "check drift: route through the Spec Drift Guard or rerun /rite-vet")
+	return 0
+}
+
+// diffInputs compares baseline digests against current digests.
+func diffInputs(base, current []gate.ReadinessInputDigest) []driftDiff {
+	cur := make(map[string]gate.ReadinessInputDigest, len(current))
+	for _, d := range current {
+		cur[d.Path] = d
+	}
+	var diffs []driftDiff
+	for _, b := range base {
+		c, ok := cur[b.Path]
+		switch {
+		case !ok:
+			diffs = append(diffs, driftDiff{Path: b.Path, Kind: "missing"})
+		case b.Present != c.Present:
+			kind := "missing"
+			if c.Present {
+				kind = "added"
+			}
+			diffs = append(diffs, driftDiff{Path: b.Path, Kind: kind})
+		case b.Present && b.SHA256 != c.SHA256:
+			diffs = append(diffs, driftDiff{Path: b.Path, Kind: "changed"})
+		}
+	}
+	sort.Slice(diffs, func(i, j int) bool { return diffs[i].Path < diffs[j].Path })
+	return diffs
+}
+
+// readDriftBaseline loads the digest baseline; hasBaseline is false when it
+// does not exist.
+func readDriftBaseline(path string) (driftBaseline, bool, error) {
+	raw, err := os.ReadFile(path) // #nosec G304 -- workspace artifact
+	if err != nil {
+		if os.IsNotExist(err) {
+			return driftBaseline{}, false, nil
+		}
+		return driftBaseline{}, false, err
+	}
+	var baseline driftBaseline
+	if err := json.Unmarshal(raw, &baseline); err != nil {
+		return driftBaseline{}, false, fmt.Errorf("corrupt baseline: %w", err)
+	}
+	if baseline.Version != 1 {
+		return driftBaseline{}, false, fmt.Errorf("unsupported baseline version %d", baseline.Version)
+	}
+	return baseline, true, nil
+}
+
+const driftUsage = "usage: devrites-engine check drift <slug> [--record]"

package/engine/internal/lib/drift_test.go

@@ -0,0 +1,106 @@
+package lib
+
+import (
+	"bytes"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+	"time"
+
+	"github.com/devrites/devrites/internal/gate"
+)
+
+// driftWorkspace builds a workspace with every required readiness input.
+func driftWorkspace(t *testing.T) (root, featureDir string) {
+	t.Helper()
+	root, featureDir = newWorkspace(t, "vet")
+	for _, name := range []string{
+		"spec.md", "decision-coverage.md", "architecture.md",
+		"plan.md", "tasks.md", "traceability.md", "test-plan.md",
+	} {
+		writeFile(t, filepath.Join(featureDir, name), "# "+name+"\n\ncontent\n")
+	}
+	return root, featureDir
+}
+
+func checkDrift(t *testing.T, root string, args ...string) (int, string) {
+	t.Helper()
+	stdout, stderr := &bytes.Buffer{}, &bytes.Buffer{}
+	code := RunCheckDrift(root, args, stdout, stderr)
+	return code, stdout.String() + stderr.String()
+}
+
+func TestDriftUnprovenWithoutBaselineOrBinding(t *testing.T) {
+	root, _ := driftWorkspace(t)
+	code, out := checkDrift(t, root, "feat")
+	if code != 0 || !strings.Contains(out, "unproven") {
+		t.Fatalf("code=%d out=%s", code, out)
+	}
+}
+
+func TestDriftRecordThenCleanPass(t *testing.T) {
+	root, _ := driftWorkspace(t)
+	code, out := checkDrift(t, root, "feat", "--record")
+	if code != 0 || !strings.Contains(out, "baseline recorded") {
+		t.Fatalf("record code=%d out=%s", code, out)
+	}
+	code, out = checkDrift(t, root, "feat")
+	if code != 0 || !strings.Contains(out, "drift: none") {
+		t.Fatalf("compare code=%d out=%s", code, out)
+	}
+}
+
+func TestDriftAttributesChangedFile(t *testing.T) {
+	root, featureDir := driftWorkspace(t)
+	if code, out := checkDrift(t, root, "feat", "--record"); code != 0 {
+		t.Fatalf("record code=%d out=%s", code, out)
+	}
+	writeFile(t, filepath.Join(featureDir, "plan.md"), "# plan.md\n\nrewritten\n")
+	writeFile(t, filepath.Join(featureDir, "strategy.md"), "# strategy\n\nnew optional input\n")
+	code, out := checkDrift(t, root, "feat")
+	if code != 0 {
+		t.Fatalf("code=%d out=%s", code, out)
+	}
+	if !strings.Contains(out, "plan.md changed") || !strings.Contains(out, "strategy.md added") {
+		t.Fatalf("expected per-file attribution:\n%s", out)
+	}
+	if strings.Contains(out, "spec.md changed") {
+		t.Fatalf("spec.md did not change:\n%s", out)
+	}
+}
+
+func TestDriftFallbackEngReviewBinding(t *testing.T) {
+	root, featureDir := driftWorkspace(t)
+	_, binding, err := gate.ReadinessInputDigests(root, "feat")
+	if err != nil {
+		t.Fatal(err)
+	}
+	writeFile(t, filepath.Join(featureDir, "eng-review.md"), "# Eng review\n\n"+binding+"\n")
+	code, out := checkDrift(t, root, "feat")
+	if code != 0 || !strings.Contains(out, "drift: none") {
+		t.Fatalf("code=%d out=%s", code, out)
+	}
+	writeFile(t, filepath.Join(featureDir, "tasks.md"), "# tasks\n\ndrifted\n")
+	// eng-review must predate the drifted file for the mtime heuristic.
+	old := time.Now().Add(-time.Hour)
+	if err := os.Chtimes(filepath.Join(featureDir, "eng-review.md"), old, old); err != nil {
+		t.Fatal(err)
+	}
+	code, out = checkDrift(t, root, "feat")
+	if code != 0 {
+		t.Fatalf("code=%d out=%s", code, out)
+	}
+	if !strings.Contains(out, "DRIFT: readiness inputs changed") || !strings.Contains(out, "tasks.md") {
+		t.Fatalf("expected aggregate drift + candidate:\n%s", out)
+	}
+}
+
+func TestDriftCorruptBaselineBlocks(t *testing.T) {
+	root, featureDir := driftWorkspace(t)
+	writeFile(t, filepath.Join(featureDir, driftBaselineFile), "{not json")
+	code, out := checkDrift(t, root, "feat")
+	if code != 3 || !strings.Contains(out, "BLOCKED") {
+		t.Fatalf("code=%d out=%s", code, out)
+	}
+}