devrites 5.11.0 → 5.12.0

package/engine/internal/lib/handoff.go

@@ -0,0 +1,194 @@
+package lib
+
+import (
+	"fmt"
+	"io"
+	"os"
+	"path/filepath"
+	"strings"
+
+	"github.com/devrites/devrites/internal/acceptance"
+	"github.com/devrites/devrites/internal/devritespaths"
+	"github.com/devrites/devrites/internal/gate"
+	"github.com/devrites/devrites/internal/state"
+)
+
+// deadEndCap bounds how many decisions.md "## Dead ends" bullets the resume
+// record replays; older entries stay in the artifact itself.
+const deadEndCap = 10
+
+// readNextOrder is the canonical resume read order inside a feature
+// workspace; only files that exist with content are emitted.
+var readNextOrder = []string{
+	"README.md",
+	"state.md",
+	"decisions.md",
+	"questions.md",
+	"gates.md",
+	"test-plan.md",
+	"evidence.md",
+	"touched-files.md",
+}
+
+// RunHandoff emits the deterministic resume record for one feature workspace:
+// cursor fields, blocking question gates, the acceptance-ledger reduction,
+// recorded dead ends, and the canonical read-next order. It never writes; the
+// record is a faithful reduction of durable artifacts so a fresh agent (or a
+// handoff writer) does not depend on transcript memory to resume.
+func RunHandoff(root string, args []string, stdout, stderr io.Writer) int {
+	slug, code, err := ActiveSlug(root, args)
+	if err != nil {
+		fmt.Fprintf(stderr, "handoff: %v\n", err)
+		if code == 0 {
+			code = 2
+		}
+		return code
+	}
+	featureDir, err := devritespaths.ExistingFeatureDirChecked(root, slug)
+	if err != nil {
+		fmt.Fprintf(stderr, "handoff: %v\n", err)
+		return 2
+	}
+	report, err := state.Status(root, slug)
+	if err != nil {
+		fmt.Fprintf(stderr, "handoff: %v\n", err)
+		return 2
+	}
+
+	fmt.Fprintf(stdout, "feature: %s\n", slug)
+	fmt.Fprintf(stdout, "phase: %s\n", report.Phase)
+	if report.Status == "" {
+		fmt.Fprintln(stdout, "status: unset")
+	} else {
+		fmt.Fprintf(stdout, "status: %s\n", report.Status)
+	}
+	if report.NextAction == "" {
+		fmt.Fprintln(stdout, "next_action: unset")
+	} else {
+		fmt.Fprintf(stdout, "next_action: %s\n", report.NextAction)
+	}
+	if report.SequenceParent != "" {
+		fmt.Fprintf(stdout, "sequence: parent=%s position=%s remaining=%s role=%s\n",
+			report.SequenceParent, report.SequencePosition, report.SequenceWorkspacesRemaining, report.SequenceRole)
+	}
+	fmt.Fprintf(stdout, "awaiting_human: %s\n", yesNo(report.Status == "awaiting_human"))
+
+	writeHandoffQuestions(featureDir, stdout)
+	writeHandoffLedger(featureDir, stdout)
+	writeHandoffDeadEnds(featureDir, stdout)
+
+	if report.Complete() {
+		fmt.Fprintln(stdout, "missing_required: none")
+	} else {
+		fmt.Fprintf(stdout, "missing_required: %s\n", strings.Join(report.MissingFiles, ", "))
+	}
+	fmt.Fprintf(stdout, "read_next: %s\n", strings.Join(readNext(featureDir), ", "))
+	return 0
+}
+
+func yesNo(ok bool) string {
+	if ok {
+		return "yes"
+	}
+	return "no"
+}
+
+func readWorkspaceFile(featureDir, name string) []byte {
+	data, err := os.ReadFile(filepath.Join(featureDir, filepath.FromSlash(name))) // #nosec G304 -- name is a workspace artifact selected by engine code
+	if err != nil {
+		return nil
+	}
+	return data
+}
+
+// writeHandoffQuestions reports open question count and which gate kinds block
+// progress, reusing the same parser the lifecycle gate applies.
+func writeHandoffQuestions(featureDir string, stdout io.Writer) {
+	questionsPath := filepath.Join(featureDir, "questions.md")
+	fmt.Fprintf(stdout, "open_questions: %d\n", countOpenQuestions(questionsPath))
+	gates := gate.OpenBlockingQuestionGates(readWorkspaceFile(featureDir, "questions.md"))
+	if len(gates) == 0 {
+		fmt.Fprintln(stdout, "blocking_question_gates: none")
+		return
+	}
+	fmt.Fprintf(stdout, "blocking_question_gates: %s\n", strings.Join(gates, ", "))
+}
+
+// writeHandoffLedger reduces gates.md against the vetted test-plan surface and
+// names the exact non-met ids so the resuming agent sees the compliance gap,
+// not just a count.
+func writeHandoffLedger(featureDir string, stdout io.Writer) {
+	data := readWorkspaceFile(featureDir, acceptance.GatesFile)
+	if data == nil {
+		fmt.Fprintln(stdout, "gates_ledger: absent")
+		return
+	}
+	doc := acceptance.ParseLedger(string(data))
+	approved := acceptance.ApprovedCommands(readWorkspaceFile(featureDir, "test-plan.md"))
+	r := doc.Reduce(approved)
+	fmt.Fprintf(stdout, "gates_total: %d\ngates_met: %d\ngates_unmet: %d\ngates_stale: %d\ngates_abandoned: %d\n",
+		r.Total, r.Met, r.Unmet, r.Stale, r.Abandoned)
+	for _, id := range r.UnmetIDs {
+		fmt.Fprintf(stdout, "unmet_id: %s\n", id)
+	}
+	for _, id := range r.StaleIDs {
+		fmt.Fprintf(stdout, "stale_id: %s\n", id)
+	}
+	for _, id := range r.UnapprIDs {
+		fmt.Fprintf(stdout, "unapproved_id: %s\n", id)
+	}
+	for _, id := range r.Handoffs {
+		fmt.Fprintf(stdout, "abandoned_id: %s\n", id)
+	}
+	for _, parseErr := range doc.Errors {
+		fmt.Fprintf(stdout, "ledger_error: %s\n", parseErr)
+	}
+}
+
+// writeHandoffDeadEnds replays the decisions.md "## Dead ends" bullets so a
+// resuming agent does not retry approaches already ruled out.
+func writeHandoffDeadEnds(featureDir string, stdout io.Writer) {
+	data := readWorkspaceFile(featureDir, "decisions.md")
+	ends := deadEnds(data)
+	if len(ends) == 0 {
+		fmt.Fprintln(stdout, "dead_ends: none")
+		return
+	}
+	for _, end := range ends {
+		fmt.Fprintf(stdout, "dead_end: %s\n", end)
+	}
+}
+
+func deadEnds(data []byte) []string {
+	var ends []string
+	inSection := false
+	for _, line := range strings.Split(string(data), "\n") {
+		trimmed := strings.TrimSpace(line)
+		if strings.HasPrefix(trimmed, "##") {
+			inSection = strings.EqualFold(trimmed, "## Dead ends")
+			continue
+		}
+		if !inSection || !strings.HasPrefix(trimmed, "-") {
+			continue
+		}
+		ends = append(ends, strings.TrimSpace(strings.TrimPrefix(trimmed, "-")))
+	}
+	if len(ends) > deadEndCap {
+		ends = ends[len(ends)-deadEndCap:]
+	}
+	return ends
+}
+
+func readNext(featureDir string) []string {
+	var next []string
+	for _, name := range readNextOrder {
+		path := filepath.Join(featureDir, filepath.FromSlash(name))
+		if info, err := os.Stat(path); err == nil && info.Size() > 0 {
+			next = append(next, name)
+		}
+	}
+	if len(next) == 0 {
+		return []string{"README.md"}
+	}
+	return next
+}

package/engine/internal/lib/handoff_test.go

@@ -0,0 +1,83 @@
+package lib
+
+import (
+	"bytes"
+	"path/filepath"
+	"strings"
+	"testing"
+)
+
+func TestHandoffEmitsResumeRecord(t *testing.T) {
+	root, featureDir := newWorkspace(t, "build")
+	writeFile(t, filepath.Join(featureDir, "questions.md"), "# Questions\n\n## Q-1\nstatus: open\ngate: blocking\n")
+	writeFile(t, filepath.Join(featureDir, "decisions.md"), "# Decisions\n\n## Dead ends\n\n- cached lookup: races the writer\n- retry loop: masks the root cause\n")
+	writeFile(t, filepath.Join(featureDir, "gates.md"), "# Gates\n\n- [x] G1: builds\n  CHECK: go build ./...\n  EXPECT: ok\n  EVIDENCE: ran\n- [ ] G2: tests green\n  CHECK: go test ./...\n  EXPECT: ok\n")
+	writeFile(t, filepath.Join(featureDir, "spec.md"), "# Spec\n")
+
+	stdout, stderr := &bytes.Buffer{}, &bytes.Buffer{}
+	code := RunHandoff(root, []string{"feat"}, stdout, stderr)
+	if code != 0 {
+		t.Fatalf("code=%d err=%s", code, stderr.String())
+	}
+	out := stdout.String()
+	for _, want := range []string{
+		"feature: feat",
+		"phase: build",
+		"status: running",
+		"awaiting_human: no",
+		"open_questions: 1",
+		"blocking_question_gates: blocking",
+		"gates_total: 2",
+		"gates_met: 0",
+		"gates_unmet: 2",
+		"gates_stale: 1",
+		"unmet_id: G1",
+		"unmet_id: G2",
+		"stale_id: G1",
+		"dead_end: cached lookup: races the writer",
+		"dead_end: retry loop: masks the root cause",
+	} {
+		if !strings.Contains(out, want) {
+			t.Fatalf("missing %q in:\n%s", want, out)
+		}
+	}
+	if !strings.Contains(out, "read_next:") || !strings.Contains(out, "state.md") || !strings.Contains(out, "gates.md") {
+		t.Fatalf("read_next missing present artifacts:\n%s", out)
+	}
+}
+
+func TestHandoffMissingLedgerAndNoQuestions(t *testing.T) {
+	root, _ := newWorkspace(t, "spec")
+	stdout, stderr := &bytes.Buffer{}, &bytes.Buffer{}
+	code := RunHandoff(root, []string{"feat"}, stdout, stderr)
+	if code != 0 {
+		t.Fatalf("code=%d err=%s", code, stderr.String())
+	}
+	out := stdout.String()
+	for _, want := range []string{
+		"gates_ledger: absent",
+		"open_questions: 0",
+		"blocking_question_gates: none",
+		"dead_ends: none",
+	} {
+		if !strings.Contains(out, want) {
+			t.Fatalf("missing %q in:\n%s", want, out)
+		}
+	}
+}
+
+func TestHandoffRejectsMissingFeature(t *testing.T) {
+	root, _ := newWorkspace(t, "spec")
+	stdout, stderr := &bytes.Buffer{}, &bytes.Buffer{}
+	if code := RunHandoff(root, []string{"nope"}, stdout, stderr); code == 0 {
+		t.Fatalf("expected non-zero for missing feature, out=%s", stdout.String())
+	}
+}
+
+func TestDeadEndsBoundsAndSectionScope(t *testing.T) {
+	body := "# D\n\n## Dead ends\n\n- one\n- two\n\n## DEC-001 other\n- not a dead end\n"
+	ends := deadEnds([]byte(body))
+	if len(ends) != 2 || ends[0] != "one" || ends[1] != "two" {
+		t.Fatalf("ends=%v", ends)
+	}
+}

package/engine/internal/lib/manifest_union_test.go

@@ -35,7 +35,7 @@ func unionWorkspace(t *testing.T, root, slug, rows string, archived bool) {
 	if err := os.MkdirAll(dir, 0o755); err != nil {
 		t.Fatal(err)
 	}
-	stateBody := "| phase | seal |\n| schema | 3 |\n"
+	stateBody := "| phase | seal |\n| schema | 4 |\n"
 	if err := os.WriteFile(filepath.Join(dir, "state.md"), []byte(stateBody), 0o644); err != nil {
 		t.Fatal(err)
 	}

package/engine/internal/lib/metrics.go

@@ -0,0 +1,256 @@
+package lib
+
+import (
+	"bufio"
+	"encoding/json"
+	"fmt"
+	"io"
+	"os"
+	"path/filepath"
+	"sort"
+	"strconv"
+	"strings"
+	"time"
+
+	"github.com/devrites/devrites/internal/devritespaths"
+)
+
+// MetricsFile is the per-feature append-only event ledger. One JSON object per
+// line keeps writes atomic-enough for a single appender and lets summaries
+// tolerate trailing partial lines.
+const MetricsFile = "metrics.jsonl"
+
+const metricsUsage = `usage: devrites-engine metrics <record|summary> ...
+
+  metrics record <slug> --phase <p> --event <e> [--role r] [--bytes n] [--note s]
+  metrics summary [slug]
+`
+
+type metricEvent struct {
+	TS    string `json:"ts"`
+	Phase string `json:"phase"`
+	Event string `json:"event"`
+	Role  string `json:"role,omitempty"`
+	Bytes int64  `json:"bytes,omitempty"`
+	Note  string `json:"note,omitempty"`
+}
+
+// RunMetrics records or summarizes per-feature workflow events.
+//
+//	metrics record <slug> --phase <p> --event <e> [--role r] [--bytes n] [--note s]
+//	metrics summary <slug>
+func RunMetrics(root string, args []string, stdout, stderr io.Writer) int {
+	if len(args) == 0 {
+		fmt.Fprint(stderr, metricsUsage)
+		return 2
+	}
+	sub, rest := args[0], args[1:]
+	switch sub {
+	case "record":
+		return metricsRecord(root, rest, stdout, stderr)
+	case "summary":
+		return metricsSummary(root, rest, stdout, stderr)
+	default:
+		fmt.Fprintf(stderr, "devrites: unknown metrics command %q\n", sub)
+		return 2
+	}
+}
+
+func metricsRecord(root string, args []string, stdout, stderr io.Writer) int {
+	if len(args) == 0 {
+		fmt.Fprint(stderr, metricsUsage)
+		return 2
+	}
+	slug := args[0]
+	event := metricEvent{TS: time.Now().UTC().Format(time.RFC3339)}
+	for i := 1; i < len(args); i++ {
+		value := argAt(args, i+1)
+		switch args[i] {
+		case "--phase":
+			event.Phase = value
+		case "--event":
+			event.Event = value
+		case "--role":
+			event.Role = value
+		case "--bytes":
+			n, err := strconv.ParseInt(value, 10, 64)
+			if err != nil || n < 0 {
+				fmt.Fprintf(stderr, "metrics: --bytes expects a non-negative integer, got %q\n", value)
+				return 2
+			}
+			event.Bytes = n
+		case "--note":
+			event.Note = value
+		default:
+			fmt.Fprintf(stderr, "metrics: unknown flag %q\n", args[i])
+			return 2
+		}
+		i++
+	}
+	if event.Phase == "" || event.Event == "" {
+		fmt.Fprintln(stderr, "metrics: record requires --phase and --event")
+		return 2
+	}
+	line, err := json.Marshal(event)
+	if err != nil {
+		fmt.Fprintf(stderr, "metrics: %v\n", err)
+		return 2
+	}
+	dir, err := devritespaths.ExistingFeatureDirChecked(root, slug)
+	if err != nil {
+		fmt.Fprintf(stderr, "metrics: %v\n", err)
+		return 2
+	}
+	path := filepath.Join(dir, MetricsFile)
+	f, err := os.OpenFile(path, os.O_APPEND|os.O_CREATE|os.O_WRONLY, 0o600) // #nosec G304 -- path is a validated workspace metrics file
+	if err != nil {
+		fmt.Fprintf(stderr, "metrics: %v\n", err)
+		return 2
+	}
+	_, werr := f.Write(append(line, '\n'))
+	cerr := f.Close()
+	if werr != nil {
+		fmt.Fprintf(stderr, "metrics: %v\n", werr)
+		return 2
+	}
+	if cerr != nil {
+		fmt.Fprintf(stderr, "metrics: %v\n", cerr)
+		return 2
+	}
+	fmt.Fprintf(stdout, "metrics: recorded %s/%s\n", event.Phase, event.Event)
+	return 0
+}
+
+// recordMetric is the in-process recorder for engine-owned events (context
+// bundle emission). It never fails the caller: a metrics write is observability,
+// not a gate.
+func recordMetric(root, slug, phase, event, role string, bytes int64) {
+	dir, err := devritespaths.ExistingFeatureDirChecked(root, slug)
+	if err != nil {
+		return
+	}
+	entry := metricEvent{
+		TS:    time.Now().UTC().Format(time.RFC3339),
+		Phase: phase,
+		Event: event,
+		Role:  role,
+		Bytes: bytes,
+	}
+	line, err := json.Marshal(entry)
+	if err != nil {
+		return
+	}
+	path := filepath.Join(dir, MetricsFile)
+	f, err := os.OpenFile(path, os.O_APPEND|os.O_CREATE|os.O_WRONLY, 0o600) // #nosec G304 -- path is a validated workspace metrics file
+	if err != nil {
+		return
+	}
+	_, _ = f.Write(append(line, '\n'))
+	_ = f.Close()
+}
+
+func metricsSummary(root string, args []string, stdout, stderr io.Writer) int {
+	slug, code, err := ActiveSlug(root, args)
+	if err != nil {
+		fmt.Fprintf(stderr, "metrics: %v\n", err)
+		if code == 0 {
+			code = 2
+		}
+		return code
+	}
+	dir, err := devritespaths.ExistingFeatureDirChecked(root, slug)
+	if err != nil {
+		fmt.Fprintf(stderr, "metrics: %v\n", err)
+		return 2
+	}
+	f, err := os.Open(filepath.Join(dir, MetricsFile)) // #nosec G304 -- dir is a validated workspace and filename is fixed
+	if err != nil {
+		fmt.Fprintf(stdout, "metrics: no events recorded for %s\n", slug)
+		return 0
+	}
+	defer func() { _ = f.Close() }()
+
+	type phaseAgg struct {
+		events int
+		bytes  int64
+		byKind map[string]int
+	}
+	type roleAgg struct {
+		events int
+		bytes  int64
+	}
+	phases := map[string]*phaseAgg{}
+	roles := map[string]*roleAgg{}
+	totalBytes := int64(0)
+	totalEvents := 0
+	bad := 0
+	scanner := bufio.NewScanner(f)
+	scanner.Buffer(make([]byte, 64<<10), 1<<20)
+	for scanner.Scan() {
+		line := strings.TrimSpace(scanner.Text())
+		if line == "" {
+			continue
+		}
+		var ev metricEvent
+		if json.Unmarshal([]byte(line), &ev) != nil || ev.Phase == "" || ev.Event == "" {
+			bad++
+			continue
+		}
+		agg, ok := phases[ev.Phase]
+		if !ok {
+			agg = &phaseAgg{byKind: map[string]int{}}
+			phases[ev.Phase] = agg
+		}
+		agg.events++
+		agg.bytes += ev.Bytes
+		agg.byKind[ev.Event]++
+		if ev.Role != "" {
+			ragg, ok := roles[ev.Role]
+			if !ok {
+				ragg = &roleAgg{}
+				roles[ev.Role] = ragg
+			}
+			ragg.events++
+			ragg.bytes += ev.Bytes
+		}
+		totalEvents++
+		totalBytes += ev.Bytes
+	}
+	if len(phases) == 0 && bad == 0 {
+		fmt.Fprintf(stdout, "metrics: no events recorded for %s\n", slug)
+		return 0
+	}
+	ordered := make([]string, 0, len(phases))
+	for phase := range phases {
+		ordered = append(ordered, phase)
+	}
+	sort.Strings(ordered)
+	fmt.Fprintf(stdout, "metrics summary: %s\n", slug)
+	for _, phase := range ordered {
+		agg := phases[phase]
+		kinds := make([]string, 0, len(agg.byKind))
+		for kind, n := range agg.byKind {
+			kinds = append(kinds, fmt.Sprintf("%s=%d", kind, n))
+		}
+		sort.Strings(kinds)
+		fmt.Fprintf(stdout, "  %-10s events=%d bytes=%d (%s)\n", phase, agg.events, agg.bytes, strings.Join(kinds, " "))
+	}
+	if len(roles) > 0 {
+		orderedRoles := make([]string, 0, len(roles))
+		for role := range roles {
+			orderedRoles = append(orderedRoles, role)
+		}
+		sort.Strings(orderedRoles)
+		fmt.Fprintln(stdout, "  roles:")
+		for _, role := range orderedRoles {
+			agg := roles[role]
+			fmt.Fprintf(stdout, "    %-24s events=%d bytes=%d\n", role, agg.events, agg.bytes)
+		}
+	}
+	fmt.Fprintf(stdout, "  total      events=%d bytes=%d", totalEvents, totalBytes)
+	if bad > 0 {
+		fmt.Fprintf(stdout, " unparsed=%d", bad)
+	}
+	fmt.Fprintln(stdout)
+	return 0
+}

package/engine/internal/lib/migrate_test.go

@@ -66,14 +66,14 @@ func TestMigrateExecutesCursorConversionAndStubs(t *testing.T) {
 	if strings.Contains(text, "- Next step:") {
 		t.Fatalf("legacy next step bullet survived:\n%s", text)
 	}
-	if !strings.Contains(text, "| schema | 3 |") {
+	if !strings.Contains(text, "| schema | 4 |") {
 		t.Fatalf("schema row missing:\n%s", text)
 	}
 	if !strings.Contains(text, "# Status\n\nMinting middleware landed.") {
 		t.Fatalf("prose not preserved:\n%s", text)
 	}
 	// Required artifacts for build exist as empty stubs.
-	for _, name := range []string{"spec.md", "brief.md", "eng-review.md", "test-plan.md"} {
+	for _, name := range []string{"spec.md", "brief.md", "eng-review.md", "test-plan.md", "gates.md"} {
 		info, err := os.Stat(filepath.Join(workspace, name))
 		if err != nil {
 			t.Fatalf("stub %s: %v", name, err)
@@ -111,7 +111,7 @@ func TestMigrateUnknownPhaseAsksAndWritesNothing(t *testing.T) {
 		t.Fatalf("answer rerun code=%d stderr=%q", code, stderr.String())
 	}
 	body, _ = os.ReadFile(filepath.Join(workspace, "state.md"))
-	if !strings.Contains(string(body), "| phase | build |") || !strings.Contains(string(body), "| schema | 3 |") {
+	if !strings.Contains(string(body), "| phase | build |") || !strings.Contains(string(body), "| schema | 4 |") {
 		t.Fatalf("answer rerun did not migrate:\n%s", body)
 	}
 }
@@ -127,17 +127,17 @@ func TestMigrateDoneWorkspaceNormalizesWithoutStubs(t *testing.T) {
 		t.Fatalf("code=%d stderr=%q", code, stderr.String())
 	}
 	body, _ := os.ReadFile(filepath.Join(workspace, "state.md"))
-	if !strings.Contains(string(body), "| schema | 3 |") {
+	if !strings.Contains(string(body), "| schema | 4 |") {
 		t.Fatalf("done workspace not normalized:\n%s", body)
 	}
-	if !strings.Contains(stdout.String(), "normalized to schema 3") {
+	if !strings.Contains(stdout.String(), "normalized to schema 4") {
 		t.Fatalf("stdout=%q", stdout.String())
 	}
 }
 
 func TestMigrateCurrentAndNewerSchemaAreRefused(t *testing.T) {
 	root, workspace := seedPreV5Workspace(t, "build")
-	if err := os.WriteFile(filepath.Join(workspace, "state.md"), []byte("| phase | build |\n| schema | 3 |\n"), 0o644); err != nil {
+	if err := os.WriteFile(filepath.Join(workspace, "state.md"), []byte("| phase | build |\n| schema | 4 |\n"), 0o644); err != nil {
 		t.Fatal(err)
 	}
 	var stdout, stderr strings.Builder