devrites 6.0.3 → 6.1.0

package/engine/internal/lib/handoff.go

@@ -148,7 +148,9 @@ func writeHandoffLedger(featureDir string, stdout io.Writer) {
 // 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")
+	// Lstat-checked: a symlinked decisions.md could replay lines from any
+	// file outside the workspace.
+	data, _ := readBoundedRegularFile(filepath.Join(featureDir, "decisions.md"), workspaceArtifactLimit)
 	ends := deadEnds(data)
 	if len(ends) == 0 {
 		fmt.Fprintln(stdout, "dead_ends: none")
@@ -164,14 +166,21 @@ func deadEnds(data []byte) []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")
+		rest := strings.TrimLeft(trimmed, "#")
+		if level := len(trimmed) - len(rest); level > 0 && (rest == "" || rest[0] == ' ' || rest[0] == '\t') {
+			// Only a level-one or level-two heading leaves the section; a
+			// ### subheading inside it does not.
+			if level <= 2 {
+				inSection = strings.EqualFold(trimmed, "## Dead ends")
+			}
 			continue
 		}
-		if !inSection || !strings.HasPrefix(trimmed, "-") {
+		// A bullet needs "- "; a "---" rule is not an entry.
+		entry, ok := strings.CutPrefix(trimmed, "- ")
+		if !inSection || !ok || strings.TrimSpace(entry) == "" {
 			continue
 		}
-		ends = append(ends, strings.TrimSpace(strings.TrimPrefix(trimmed, "-")))
+		ends = append(ends, strings.TrimSpace(entry))
 	}
 	if len(ends) > deadEndCap {
 		ends = ends[len(ends)-deadEndCap:]

package/engine/internal/lib/metrics.go

@@ -7,12 +7,14 @@ import (
 	"io"
 	"os"
 	"path/filepath"
+	"slices"
 	"sort"
 	"strconv"
 	"strings"
 	"time"
 
 	"github.com/devrites/devrites/internal/devritespaths"
+	"github.com/devrites/devrites/internal/state"
 )
 
 // MetricsFile is the per-feature append-only event ledger. One JSON object per
@@ -23,7 +25,7 @@ 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]
+  metrics summary [slug] [--by-slice]
 `
 
 type metricEvent struct {
@@ -149,7 +151,19 @@ func recordMetric(root, slug, phase, event, role string, bytes int64) {
 	_ = f.Close()
 }
 
+// cursorPhase is the feature's recorded cursor phase, or "" when state.md is
+// unreadable; engine checks label their metrics with it.
+func cursorPhase(root, slug string) string {
+	report, err := state.Status(root, slug)
+	if err != nil {
+		return ""
+	}
+	return string(report.Phase)
+}
+
 func metricsSummary(root string, args []string, stdout, stderr io.Writer) int {
+	bySlice := slices.Contains(args, "--by-slice")
+	args = slices.DeleteFunc(slices.Clone(args), func(a string) bool { return a == "--by-slice" })
 	slug, code, err := ActiveSlug(root, args)
 	if err != nil {
 		fmt.Fprintf(stderr, "metrics: %v\n", err)
@@ -163,11 +177,18 @@ func metricsSummary(root string, args []string, stdout, stderr io.Writer) int {
 		fmt.Fprintf(stderr, "metrics: %v\n", err)
 		return 2
 	}
+	if bySlice {
+		return sliceCostSummary(root, slug, stdout, stderr)
+	}
 	f, err := os.Open(filepath.Join(dir, MetricsFile)) // #nosec G304 -- dir is a validated workspace and filename is fixed
-	if err != nil {
+	if os.IsNotExist(err) {
 		fmt.Fprintf(stdout, "metrics: no events recorded for %s\n", slug)
 		return 0
 	}
+	if err != nil {
+		fmt.Fprintf(stderr, "metrics: ledger unreadable: %v\n", err)
+		return 2
+	}
 	defer func() { _ = f.Close() }()
 
 	type phaseAgg struct {
@@ -184,11 +205,20 @@ func metricsSummary(root string, args []string, stdout, stderr io.Writer) int {
 	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())
+	// A reader, not a Scanner: one event line carries an unbounded --note. A
+	// final line without a newline is handled, then the next read is ("", EOF).
+	reader := bufio.NewReader(f)
+	for {
+		raw, readErr := reader.ReadString('\n')
+		if readErr != nil && readErr != io.EOF {
+			fmt.Fprintf(stderr, "metrics: ledger unreadable after %d events: %v\n", totalEvents, readErr)
+			return 2
+		}
+		line := strings.TrimSpace(raw)
 		if line == "" {
+			if readErr == io.EOF {
+				break
+			}
 			continue
 		}
 		var ev metricEvent
@@ -216,10 +246,6 @@ func metricsSummary(root string, args []string, stdout, stderr io.Writer) int {
 		totalEvents++
 		totalBytes += ev.Bytes
 	}
-	if err := scanner.Err(); err != nil {
-		fmt.Fprintf(stderr, "metrics: ledger unreadable after %d events: %v\n", totalEvents, err)
-		return 2
-	}
 	if len(phases) == 0 && bad == 0 {
 		fmt.Fprintf(stdout, "metrics: no events recorded for %s\n", slug)
 		return 0
@@ -258,3 +284,70 @@ func metricsSummary(root string, args []string, stdout, stderr io.Writer) int {
 	fmt.Fprintln(stdout)
 	return 0
 }
+
+// sliceCostSummary reports, per slice named on dispatch waves, the build wright
+// rounds, slice-bound Vet rechecks, and agent-minutes (role start to return; a
+// wave naming several slices splits its minutes evenly). Abandoned waves are
+// excluded, and waves recorded before returns were timestamped count rounds only.
+func sliceCostSummary(root, slug string, stdout, stderr io.Writer) int {
+	f, _, err := loadDispatch(root, slug)
+	if err != nil {
+		fmt.Fprintf(stderr, "metrics: %v\n", err)
+		return 2
+	}
+	type cost struct {
+		wright, vet int
+		minutes     float64
+		timed       bool
+	}
+	per := map[string]*cost{}
+	for _, w := range f.Waves {
+		kind := roundKind(w)
+		if kind == "" || w.State == "abandoned" {
+			continue
+		}
+		minutes, timed := 0.0, false
+		for _, r := range w.Roles {
+			start, startErr := time.Parse(time.RFC3339, r.StartedAt)
+			end, endErr := time.Parse(time.RFC3339, r.ReturnedAt)
+			if startErr == nil && endErr == nil && !end.Before(start) {
+				minutes += end.Sub(start).Minutes()
+				timed = true
+			}
+		}
+		for _, id := range w.Slices {
+			c := per[id]
+			if c == nil {
+				c = &cost{}
+				per[id] = c
+			}
+			if kind == "wright" {
+				c.wright++
+			} else {
+				c.vet++
+			}
+			if timed {
+				c.minutes += minutes / float64(len(w.Slices))
+				c.timed = true
+			}
+		}
+	}
+	if len(per) == 0 {
+		fmt.Fprintf(stdout, "metrics: no slice-tagged dispatch waves for %s\n", slug)
+		return 0
+	}
+	ids := make([]string, 0, len(per))
+	for id := range per {
+		ids = append(ids, id)
+	}
+	sort.Strings(ids)
+	for _, id := range ids {
+		c := per[id]
+		minutes := "n/a"
+		if c.timed {
+			minutes = strconv.FormatFloat(c.minutes, 'f', 0, 64)
+		}
+		fmt.Fprintf(stdout, "metrics: %s wright_rounds=%d vet_rechecks=%d agent_minutes=%s\n", id, c.wright, c.vet, minutes)
+	}
+	return 0
+}

package/engine/internal/lib/migrate.go

@@ -31,7 +31,7 @@ type migratePlan struct {
 	questions []migrateQuestion
 }
 
-// Migrate normalizes a pre-v5 feature workspace to the current schema: it
+// Migrate normalizes an older-schema feature workspace to the current schema: it
 // converts legacy bullet cursor fields into canonical table rows, records the
 // schema row, and creates missing required artifacts as empty stubs. Bound
 // proof files are preserved byte-exact; content is never synthesized. The
@@ -130,6 +130,23 @@ func Migrate(root string, args []string, stdout, stderr io.Writer) int {
 			return nil
 		}
 
+		next := lines
+		for _, step := range plan.steps {
+			if step.kind == "phase" {
+				next = state.UpsertCursorField(next, state.CursorPhase, plan.phase)
+			}
+		}
+		if converted, changed := state.ConvertCursorToTable(next); changed {
+			next = converted
+		}
+		next = state.UpsertCursorField(next, state.CursorSchema, fmt.Sprint(state.SchemaVersion))
+		// Upserts silently decline what they cannot write (for example after
+		// an unclosed fence), so confirm the schema row reads back before
+		// touching anything.
+		if value, ok := state.CursorField(next, state.CursorSchema); !ok || strings.TrimSpace(value) != fmt.Sprint(state.SchemaVersion) {
+			return fmt.Errorf("state.md cannot be normalized: the schema row does not read back (check for an unclosed fence or malformed cursor); nothing written")
+		}
+
 		// New stub files go first: they are idempotent, never bound, and
 		// state.md is the commit point written last.
 		for _, step := range plan.steps {
@@ -145,16 +162,6 @@ func Migrate(root string, args []string, stdout, stderr io.Writer) int {
 			}
 			applied++
 		}
-		next := lines
-		for _, step := range plan.steps {
-			if step.kind == "phase" {
-				next = state.UpsertCursorField(next, state.CursorPhase, plan.phase)
-			}
-		}
-		if converted, changed := state.ConvertCursorToTable(next); changed {
-			next = converted
-		}
-		next = state.UpsertCursorField(next, state.CursorSchema, fmt.Sprint(state.SchemaVersion))
 		if err := fsutil.WriteFileAtomic(ledger, []byte(strings.Join(next, "\n")), 0o644); err != nil {
 			return err
 		}
@@ -175,6 +182,7 @@ func buildMigratePlan(root, slug string, lines []string, answered map[string]str
 	phase, hasPhase := state.CursorField(lines, state.CursorPhase)
 
 	if value, ok := answered["phase"]; ok {
+		value = phaseWord(value)
 		plan.steps = append(plan.steps, migrateStep{kind: "phase", detail: "record phase " + value + " from answer"})
 		phase, hasPhase = value, true
 	}
@@ -183,11 +191,12 @@ func buildMigratePlan(root, slug string, lines []string, answered map[string]str
 			prompt: "state.md records no phase; re-run with --answer phase=<phase>"})
 		return plan
 	}
-	if _, ok := state.PolicyFor(state.Phase(phase)); !ok {
+	if _, ok := state.PolicyFor(state.Phase(phaseWord(phase))); !ok {
 		plan.questions = append(plan.questions, migrateQuestion{id: "phase",
 			prompt: "state.md records unknown phase " + phase + "; re-run with --answer phase=<phase>"})
 		return plan
 	}
+	phase = phaseWord(phase)
 	plan.phase = phase
 
 	if state.CursorForm(lines) == "legacy" {
@@ -209,6 +218,15 @@ func buildMigratePlan(root, slug string, lines []string, answered map[string]str
 	return plan
 }
 
+// phaseWord reads a cursor phase the way the engine does: lower-cased first
+// word, so "Build" and "build (slice 2)" both mean build.
+func phaseWord(value string) string {
+	if fields := strings.Fields(strings.ToLower(value)); len(fields) > 0 {
+		return fields[0]
+	}
+	return ""
+}
+
 // stringSlice collects repeated string flag values.
 type stringSlice []string
 

package/engine/internal/lib/next.go

@@ -6,9 +6,11 @@ import (
 	"os"
 	"path/filepath"
 	"regexp"
+	"slices"
 	"strings"
 
 	"github.com/devrites/devrites/internal/devritespaths"
+	"github.com/devrites/devrites/internal/markdowntext"
 	"github.com/devrites/devrites/internal/state"
 	"github.com/devrites/devrites/internal/workflow"
 )
@@ -86,7 +88,11 @@ func RunNext(root string, args []string, stdout, stderr io.Writer) int {
 				continue
 			}
 			missing = missingArtifacts(featureDir, policy.RequiredArtifacts)
-			if len(missing) == 0 {
+			// A phase that adds no required artifact over the previous one
+			// (build after vet, polish after prove) cannot be proven done by
+			// artifact presence, so it is never skipped. Converge is the
+			// exception: a conditional recovery pass that build hands past.
+			if len(missing) == 0 && (addsArtifact(policies[i-1], policy) || policy.Target == state.PhaseConverge) {
 				skips = append(skips, fmt.Sprintf("%s (artifacts complete)", policy.Target))
 				continue
 			}
@@ -121,6 +127,15 @@ func printSkips(stdout io.Writer, skips []string) {
 	}
 }
 
+func addsArtifact(prev, policy state.PhasePolicy) bool {
+	for _, artifact := range policy.RequiredArtifacts {
+		if !slices.Contains(prev.RequiredArtifacts, artifact) {
+			return true
+		}
+	}
+	return false
+}
+
 func missingArtifacts(featureDir string, required []state.ArtifactPath) []string {
 	var missing []string
 	for _, artifact := range required {
@@ -139,12 +154,17 @@ var (
 )
 
 // countOpenQuestions tolerates both the block form ("status: open") and the
-// register table form ("| Q-001 | open | ... |").
+// register table form ("| Q-001 | open | ... |"), outside fenced blocks.
 func countOpenQuestions(path string) int {
 	data, err := os.ReadFile(path) // #nosec G304 -- path is a validated workspace artifact
 	if err != nil {
 		return 0
 	}
+	// Fenced examples are not live questions. Text Structural rejects is
+	// counted raw, so an unreadable register over-counts rather than hides.
+	if visible, err := markdowntext.Structural(data); err == nil {
+		data = visible
+	}
 	count := 0
 	for _, line := range strings.Split(string(data), "\n") {
 		if openStatusLine.MatchString(line) || openTableCell.MatchString(line) {

package/engine/internal/lib/observe_summary.go

@@ -51,6 +51,7 @@ type ObserveSummary struct {
 	ArtifactBudgets   []ArtifactBudget       `json:"artifact_budgets,omitempty"`
 	BulkFiles         []BulkFile             `json:"bulk_files,omitempty"`
 	Sequence          *ObserveSequenceCursor `json:"sequence,omitempty"`
+	InflightWaves     []InflightWave         `json:"inflight_waves,omitempty"`
 }
 
 // ObserveSummaryFor builds a summary for one feature slug.
@@ -91,6 +92,13 @@ func ObserveSummaryFor(root, slug string) (ObserveSummary, error) {
 			OK:         len(graph.Problems) == 0,
 		}
 	}
+	// Open or sealed waves are agents whose results the root never recorded;
+	// a resume reconciles them before starting new work.
+	if waves, _, err := loadDispatch(root, slug); err == nil {
+		summary.InflightWaves = inflightWaves(waves)
+	} else {
+		summary.Unreadable = append(summary.Unreadable, "dispatch.json")
+	}
 	if report.SequenceParent != "" || report.SequencePosition != "" || report.SequenceWorkspacesRemaining != "" || report.SequenceRole != "" {
 		summary.Sequence = &ObserveSequenceCursor{
 			Parent:              report.SequenceParent,

package/engine/internal/lib/open_visual.go

@@ -63,7 +63,9 @@ func OpenVisual(root string, args []string, stdout, stderr io.Writer) int {
 			return 2
 		}
 		visualDir := filepath.Join(feature, "visual")
-		if !safepath.WithinResolved(htmlPath, visualDir) {
+		// visual/ itself may be a symlink: resolving both sides would then
+		// accept any file under its target.
+		if !safepath.WithinResolved(visualDir, feature) || !safepath.WithinResolved(htmlPath, visualDir) {
 			fmt.Fprintf(stderr, "open-visual: refused: resolved path escapes workspace visual/\n")
 			return 2
 		}