devrites 2.6.1 → 3.0.1

package/engine/internal/lib/jsonout_test.go

@@ -0,0 +1,57 @@
+package lib
+
+import (
+	"bytes"
+	"encoding/json"
+	"testing"
+)
+
+func TestNewEnvelopeOK(t *testing.T) {
+	env := NewEnvelope("preamble", 0, "phase: build\nstatus: running\n", "")
+	if !env.OK || env.ExitCode != 0 {
+		t.Fatalf("want ok/0, got ok=%v code=%d", env.OK, env.ExitCode)
+	}
+	if env.Data == nil || env.Data.Text != "phase: build\nstatus: running" {
+		t.Fatalf("data.text not captured verbatim: %+v", env.Data)
+	}
+	if len(env.Diagnostics) != 0 {
+		t.Fatalf("clean run should have no diagnostics, got %v", env.Diagnostics)
+	}
+}
+
+func TestNewEnvelopeParsesDiagnostics(t *testing.T) {
+	stderr := `ERROR:.devrites/work/feat/spec.md: Requirement "X" (line 2) is marked ADDED but already exists in ledger capability "theming"
+ERROR:.devrites/work/feat/spec.md: Requirement "Y" (line 9) has no THEN line`
+	env := NewEnvelope("spec-validate", 1, "", stderr)
+	if env.OK || env.ExitCode != 1 {
+		t.Fatalf("want not-ok/1, got ok=%v code=%d", env.OK, env.ExitCode)
+	}
+	if len(env.Diagnostics) != 2 {
+		t.Fatalf("want 2 diagnostics, got %d", len(env.Diagnostics))
+	}
+	d0 := env.Diagnostics[0]
+	if d0.Severity != "error" || d0.Path != ".devrites/work/feat/spec.md" || d0.Line != 2 {
+		t.Fatalf("diagnostic 0 misparsed: %+v", d0)
+	}
+	if d0.Code != "spec_validate_delta_mismatch" {
+		t.Fatalf("want delta_mismatch code, got %q", d0.Code)
+	}
+	if env.Diagnostics[1].Code != "spec_validate_grammar" {
+		t.Fatalf("want grammar code for THEN-line finding, got %q", env.Diagnostics[1].Code)
+	}
+}
+
+func TestWriteEnvelopeIsValidJSON(t *testing.T) {
+	var buf bytes.Buffer
+	WriteEnvelope(&buf, NewEnvelope("doctor", 3, "skew", "WARN: pack ahead of binary"))
+	var back Envelope
+	if err := json.Unmarshal(buf.Bytes(), &back); err != nil {
+		t.Fatalf("envelope is not valid JSON: %v", err)
+	}
+	if back.ExitCode != 3 || back.OK {
+		t.Fatalf("round-trip lost fields: %+v", back)
+	}
+	if len(back.Diagnostics) != 1 || back.Diagnostics[0].Severity != "warning" {
+		t.Fatalf("warning diagnostic not classified: %+v", back.Diagnostics)
+	}
+}

package/engine/internal/lib/lanes.go

@@ -0,0 +1,106 @@
+package lib
+
+import (
+	"fmt"
+	"io"
+	"path/filepath"
+	"regexp"
+	"slices"
+	"strings"
+)
+
+var lanePathRe = regexp.MustCompile("`([^`]+)`")
+
+// Lanes plans conservative parallelism for a feature without changing state. It
+// never authorizes parallel production writes; it only labels read-only lanes,
+// Forge candidates, and obviously independent slices so the human/agent can keep
+// DevRites' one-verified-slice default intact.
+func Lanes(root string, args []string, stdout, stderr io.Writer) int {
+	if argAt(args, 0) != "plan" {
+		fmt.Fprintln(stderr, "usage: devrites-engine lanes plan [slug]")
+		return 2
+	}
+	slug := argAt(args, 1)
+	if slug == "" {
+		slug = activeSlug(root)
+	}
+	if slug == "" {
+		fmt.Fprintln(stderr, "lanes: no active feature")
+		return 2
+	}
+	tasks, ok := readFileOK(filepath.Join(featureDir(root, slug), "tasks.md"))
+	if !ok {
+		fmt.Fprintf(stdout, "lanes: no tasks.md for %s — no parallel write lanes.\n", slug)
+		return 0
+	}
+	slices := parseLaneSlices(tasks)
+	fmt.Fprintf(stdout, "# Lane plan: %s\n\n", slug)
+	if len(slices) == 0 {
+		fmt.Fprintln(stdout, "No slice headings found. Keep the default single-slice build loop.")
+		return 0
+	}
+	groups := map[string][]string{}
+	for _, s := range slices {
+		key := "read-only/review"
+		if s.forge {
+			key = "forge-candidate"
+		} else if len(s.paths) > 0 {
+			key = strings.Join(s.paths, ",")
+		}
+		groups[key] = append(groups[key], s.name)
+	}
+	fmt.Fprintln(stdout, "Default: one production write slice at a time. Safe parallelism is advisory only.")
+	fmt.Fprintln(stdout)
+	for _, s := range slices {
+		kind := "serial-write"
+		if s.forge {
+			kind = "forge-candidate"
+		} else if len(s.paths) == 0 {
+			kind = "read-only/spike"
+		}
+		conflict := "unknown write surface"
+		if len(s.paths) > 0 {
+			conflict = strings.Join(s.paths, ", ")
+		}
+		fmt.Fprintf(stdout, "- %s: %s — %s\n", s.name, kind, conflict)
+	}
+	return 0
+}
+
+type laneSlice struct {
+	name  string
+	paths []string
+	forge bool
+}
+
+func parseLaneSlices(md string) []laneSlice {
+	var out []laneSlice
+	var cur *laneSlice
+	flush := func() {
+		if cur != nil {
+			out = append(out, *cur)
+		}
+	}
+	for _, line := range strings.Split(md, "\n") {
+		trim := strings.TrimSpace(line)
+		if sliceHeadRe.MatchString(trim) {
+			flush()
+			cur = &laneSlice{name: strings.TrimPrefix(trim, "## ")}
+			continue
+		}
+		if cur == nil {
+			continue
+		}
+		lower := strings.ToLower(trim)
+		if strings.Contains(lower, "forge: yes") || strings.Contains(lower, "forge yes") {
+			cur.forge = true
+		}
+		for _, m := range lanePathRe.FindAllStringSubmatch(trim, -1) {
+			if !slices.Contains(cur.paths, m[1]) {
+				cur.paths = append(cur.paths, m[1])
+			}
+		}
+	}
+	flush()
+	return out
+}

package/engine/internal/lib/learnings.go

@@ -0,0 +1,391 @@
+package lib
+
+import (
+	"fmt"
+	"io"
+	"os"
+	"path/filepath"
+	"regexp"
+	"sort"
+	"strconv"
+	"strings"
+	"time"
+
+	"github.com/devrites/devrites/internal/workflow"
+)
+
+// Learnings is the cross-feature learning ledger for /rite-learn. Its state is
+// project-wide, not per-feature: the ledger, the archive it mines, and the review
+// marker all live directly under root (the .devrites directory). Subcommands:
+//
+//	add <slug> "<text>" [tag] [conf]  append a dated entry (conf = 0..1 confidence)
+//	list                        print the ledger, or note that it is empty
+//	top                         print the high-confidence entries eligible for injection
+//	mine [archive-dir]          cluster finding/decision phrases that recur (>= 2)
+//	nudge [archive-dir]         surface a phrase recurring >= 3x, if new since review
+//
+// A ledger entry may carry a confidence token (`c=0.8`) in its metadata. Only
+// entries at or above DEVRITES_LEARNING_CONFIDENCE_THRESHOLD (default 0.7) are
+// injected into the SessionStart orientation, capped at
+// DEVRITES_MAX_INJECTED_LEARNINGS (default 5). An unmarked entry defaults to 0.5
+// — below the floor — so nothing auto-injects until a human promotes it via
+// /rite-learn. The human gate is preserved; only the bounded surfacing is new.
+//
+// Exit codes: 0 ok · 2 bad args.
+func Learnings(root string, args []string, stdout, stderr io.Writer) int {
+	ledger := filepath.Join(root, "learnings.md")
+	cmd := argAt(args, 0)
+
+	switch cmd {
+	case "add":
+		slug := argAt(args, 1)
+		text := argAt(args, 2)
+		tag := argAt(args, 3)
+		confArg := argAt(args, 4)
+		if tag == "" {
+			tag = "note"
+		}
+		if text == "" {
+			fmt.Fprintln(stderr, `usage: devrites-engine learnings add <slug> "<text>" [tag] [confidence 0..1]`)
+			return 2
+		}
+		meta := tag
+		if confArg != "" {
+			c, ok := parseConfidence(confArg)
+			if !ok {
+				fmt.Fprintln(stderr, "learnings: confidence must be a number in [0,1]")
+				return 2
+			}
+			meta = fmt.Sprintf("%s · c=%s", tag, strconv.FormatFloat(c, 'f', -1, 64))
+		}
+		if !isFile(ledger) {
+			if err := os.MkdirAll(root, 0o755); err != nil {
+				fmt.Fprintf(stderr, "learnings: create ledger directory: %v\n", err)
+				return 1
+			}
+			if err := os.WriteFile(ledger, []byte(learningsHeader), 0o644); err != nil {
+				fmt.Fprintf(stderr, "learnings: create ledger: %v\n", err)
+				return 1
+			}
+		}
+		if slug == "" {
+			slug = "?"
+		}
+		entry := fmt.Sprintf("- [%s] (%s · %s) %s\n", time.Now().Format("2006-01-02"), meta, slug, text)
+		f, err := os.OpenFile(ledger, os.O_APPEND|os.O_WRONLY, 0o644)
+		if err != nil {
+			fmt.Fprintf(stderr, "learnings: open ledger: %v\n", err)
+			return 1
+		}
+		if _, err := f.WriteString(entry); err != nil {
+			_ = f.Close()
+			fmt.Fprintf(stderr, "learnings: append ledger: %v\n", err)
+			return 1
+		}
+		if err := f.Sync(); err != nil {
+			_ = f.Close()
+			fmt.Fprintf(stderr, "learnings: sync ledger: %v\n", err)
+			return 1
+		}
+		if err := f.Close(); err != nil {
+			fmt.Fprintf(stderr, "learnings: close ledger: %v\n", err)
+			return 1
+		}
+		fmt.Fprintln(stdout, "learnings: recorded.")
+		return 0
+
+	case "list":
+		if isFile(ledger) {
+			if data, err := os.ReadFile(ledger); err == nil {
+				_, _ = stdout.Write(data)
+			}
+		} else {
+			fmt.Fprintf(stdout, "learnings: ledger empty (%s not present).\n", ledger)
+		}
+		return 0
+
+	case "top":
+		lines := TopLearnings(root, InjectMax(), InjectThreshold())
+		if len(lines) == 0 {
+			fmt.Fprintln(stdout, "learnings: no entries at or above the injection confidence floor.")
+			return 0
+		}
+		for _, l := range lines {
+			fmt.Fprintln(stdout, l)
+		}
+		return 0
+
+	case "mine":
+		arch := archiveDir(root, args)
+		if !isDir(arch) {
+			fmt.Fprintf(stdout, "learnings: no archive at %s — nothing to mine.\n", arch)
+			return 0
+		}
+		fmt.Fprintln(stdout, "learnings: repeated finding/decision phrases across archived features (count >= 2):")
+		clusters := clusterPhrases(minedPhrases(arch, 80, true))
+		printed := 0
+		for _, c := range clusters {
+			if c.count < 2 {
+				continue
+			}
+			if printed >= 25 {
+				break
+			}
+			fmt.Fprintf(stdout, "  %2d×  %s\n", c.count, c.phrase)
+			printed++
+		}
+		fmt.Fprintln(stdout, "(review these — a stable recurring class is a candidate for a project rule or a ledger entry.)")
+		return 0
+
+	case "nudge":
+		arch := archiveDir(root, args)
+		if !isDir(arch) {
+			return 0
+		}
+		// A cross-feature nudge needs at least two shipped features, and stays quiet
+		// once reviewed until something in the archive changes again.
+		if countSubdirs(arch) < 2 {
+			return 0
+		}
+		marker := filepath.Join(root, ".learnings-reviewed")
+		if fi, err := os.Stat(marker); err == nil && fi.Mode().IsRegular() && !anyFileNewerThan(arch, fi.ModTime()) {
+			return 0
+		}
+		clusters := clusterPhrases(minedPhrases(arch, 60, false))
+		var top phraseCount
+		for _, c := range clusters {
+			if c.count >= 3 {
+				top = c
+				break
+			}
+		}
+		if top.count == 0 {
+			return 0
+		}
+		phrase := top.phrase
+		if len(phrase) > 48 {
+			phrase = phrase[:48]
+		}
+		fmt.Fprintf(stdout, "learnings: a pattern recurs %sx across shipped features (\"%s…\") — review + maybe promote it to a rule with %s.\n",
+			strconv.Itoa(top.count), phrase, workflow.ForVerb("learn").Both())
+		return 0
+
+	default:
+		fmt.Fprintln(stderr, "usage: devrites-engine learnings add|list|top|mine|nudge [...]")
+		return 2
+	}
+}
+
+// Injection defaults — the threshold + cap that bound how much of the ledger
+// reaches the SessionStart orientation, so a growing ledger can never bloat the
+// context window.
+const (
+	defaultInjectThreshold = 0.7
+	defaultInjectMax       = 5
+)
+
+// confInLine pulls a confidence token (c=0.8 or c0.8, case-insensitive) out of a
+// ledger line. Anchored on a word boundary so it does not match inside a word.
+var confInLine = regexp.MustCompile(`(?i)\bc=?([01](?:\.[0-9]+)?)\b`)
+
+// TopLearnings returns up to max ledger entries whose confidence is at or above
+// threshold, highest-confidence first, each rendered as a single injection-ready
+// bullet. An unmarked entry is treated as 0.5 (below the default floor). max <= 0
+// disables injection entirely (returns nil).
+func TopLearnings(root string, max int, threshold float64) []string {
+	if max <= 0 {
+		return nil
+	}
+	data, err := os.ReadFile(filepath.Join(root, "learnings.md"))
+	if err != nil {
+		return nil
+	}
+	type scored struct {
+		line string
+		conf float64
+	}
+	var kept []scored
+	for _, line := range splitLinesNoTrailing(data) {
+		if !strings.HasPrefix(strings.TrimSpace(line), "- [") {
+			continue // only dated ledger entries, never the header prose
+		}
+		conf := 0.5
+		if m := confInLine.FindStringSubmatch(line); m != nil {
+			if c, err := strconv.ParseFloat(m[1], 64); err == nil {
+				conf = c
+			}
+		}
+		if conf+1e-9 < threshold {
+			continue
+		}
+		kept = append(kept, scored{line: strings.TrimSpace(line), conf: conf})
+	}
+	sort.SliceStable(kept, func(i, j int) bool { return kept[i].conf > kept[j].conf })
+	if len(kept) > max {
+		kept = kept[:max]
+	}
+	out := make([]string, len(kept))
+	for i, k := range kept {
+		out[i] = k.line
+	}
+	return out
+}
+
+// parseConfidence parses a 0..1 confidence, rejecting out-of-range or garbage.
+func parseConfidence(s string) (float64, bool) {
+	c, err := strconv.ParseFloat(strings.TrimSpace(s), 64)
+	if err != nil || c < 0 || c > 1 {
+		return 0, false
+	}
+	return c, true
+}
+
+// InjectThreshold / InjectMax read the injection-bound env knobs, falling back to
+// the defaults on empty or unparseable input.
+func InjectThreshold() float64 {
+	if v := os.Getenv("DEVRITES_LEARNING_CONFIDENCE_THRESHOLD"); v != "" {
+		if c, ok := parseConfidence(v); ok {
+			return c
+		}
+	}
+	return defaultInjectThreshold
+}
+
+func InjectMax() int {
+	if v := os.Getenv("DEVRITES_MAX_INJECTED_LEARNINGS"); v != "" {
+		if n, err := strconv.Atoi(strings.TrimSpace(v)); err == nil && n >= 0 {
+			return n
+		}
+	}
+	return defaultInjectMax
+}
+
+// archiveDir is the archive to mine — an explicit second argument, or archive/
+// under root by default.
+func archiveDir(root string, args []string) string {
+	if arch := argAt(args, 1); arch != "" {
+		return arch
+	}
+	return filepath.Join(root, "archive")
+}
+
+// learningsHeader is the ledger preamble written when `add` first creates it.
+const learningsHeader = "# DevRites learnings ledger\n\n" +
+	"Project-local lessons mined from shipped features — recurring corrections,\n" +
+	"dismissed-finding classes, and dead-ends. Loaded by the review skills before a fan-out so\n" +
+	"the same false positive or the same mistake does not recur. Untrusted prior: live code\n" +
+	"always overrides a ledger entry (see standards/security.md).\n\n"
+
+var (
+	// findingLine matches a bullet, or a line mentioning a finding/dead-end/drift/
+	// dismissal — the candidate lines worth clustering.
+	findingLine = regexp.MustCompile(`(?i)^[-*] |finding|dead end|drift|dismiss`)
+	// Normalisers applied to each candidate line so wording clusters despite
+	// incidental differences.
+	leadingBullet = regexp.MustCompile(`^[-*[:space:]]+`) // the leading bullet/indent
+	codeSpan      = regexp.MustCompile("`[^`]*`")         // inline `code`
+	digits        = regexp.MustCompile(`[0-9]+`)          // ids and counts
+	whitespaceRun = regexp.MustCompile(`[[:space:]]+`)    // runs of whitespace
+)
+
+// phraseCount is a normalised phrase and how many lines reduced to it.
+type phraseCount struct {
+	phrase string
+	count  int
+}
+
+// minedPhrases reads the decisions/drift/review notes of every archived feature and
+// returns the normalised candidate phrases. Normalisation strips the leading
+// bullet, inline code, and digits, collapses whitespace, and lowercases; phrases of
+// 12 characters or fewer are dropped as too short to be meaningful, and the rest are
+// truncated to trunc bytes. When collapse is set, leading/trailing whitespace is
+// trimmed and internal runs squeezed to single spaces before the length check.
+func minedPhrases(arch string, trunc int, collapse bool) []string {
+	var phrases []string
+	for _, leaf := range []string{"decisions.md", "drift.md", "review.md"} {
+		files, _ := filepath.Glob(filepath.Join(arch, "*", leaf))
+		for _, f := range files {
+			data, err := os.ReadFile(f)
+			if err != nil {
+				continue
+			}
+			for _, line := range splitLinesNoTrailing(data) {
+				if !findingLine.MatchString(line) {
+					continue
+				}
+				s := leadingBullet.ReplaceAllString(line, "")
+				s = codeSpan.ReplaceAllString(s, "")
+				s = digits.ReplaceAllString(s, "")
+				s = whitespaceRun.ReplaceAllString(s, " ")
+				s = asciiLower(s)
+				if collapse {
+					s = strings.Join(strings.Fields(s), " ")
+				}
+				if len(s) > 12 {
+					if len(s) > trunc {
+						s = s[:trunc]
+					}
+					phrases = append(phrases, s)
+				}
+			}
+		}
+	}
+	return phrases
+}
+
+// clusterPhrases groups identical phrases and orders them by frequency, most
+// frequent first. Equal counts keep ascending phrase order.
+func clusterPhrases(phrases []string) []phraseCount {
+	sort.Strings(phrases)
+	var clusters []phraseCount
+	for _, p := range phrases {
+		if n := len(clusters); n > 0 && clusters[n-1].phrase == p {
+			clusters[n-1].count++
+		} else {
+			clusters = append(clusters, phraseCount{phrase: p, count: 1})
+		}
+	}
+	sort.SliceStable(clusters, func(i, j int) bool { return clusters[i].count > clusters[j].count })
+	return clusters
+}
+
+// countSubdirs counts arch's immediate non-hidden subdirectories (its features).
+func countSubdirs(arch string) int {
+	entries, err := os.ReadDir(arch)
+	if err != nil {
+		return 0
+	}
+	n := 0
+	for _, e := range entries {
+		if e.IsDir() && !strings.HasPrefix(e.Name(), ".") {
+			n++
+		}
+	}
+	return n
+}
+
+// anyFileNewerThan reports whether any regular file under arch was modified after t.
+func anyFileNewerThan(arch string, t time.Time) bool {
+	newer := false
+	_ = filepath.WalkDir(arch, func(_ string, d os.DirEntry, err error) error {
+		if err != nil || d.IsDir() {
+			return nil
+		}
+		if info, err := d.Info(); err == nil && info.Mode().IsRegular() && info.ModTime().After(t) {
+			newer = true
+			return filepath.SkipAll
+		}
+		return nil
+	})
+	return newer
+}
+
+// asciiLower lowercases ASCII A–Z, leaving every other byte untouched.
+func asciiLower(s string) string {
+	return strings.Map(func(r rune) rune {
+		if r >= 'A' && r <= 'Z' {
+			return r + ('a' - 'A')
+		}
+		return r
+	}, s)
+}

package/engine/internal/lib/learnings_inject_test.go

@@ -0,0 +1,77 @@
+package lib
+
+import (
+	"os"
+	"path/filepath"
+	"testing"
+)
+
+func writeLedger(t *testing.T, body string) string {
+	t.Helper()
+	root := t.TempDir()
+	if err := os.WriteFile(filepath.Join(root, "learnings.md"), []byte(body), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	return root
+}
+
+func TestTopLearningsThresholdAndCap(t *testing.T) {
+	root := writeLedger(t, learningsHeader+
+		"- [2026-07-01] (rule · slug · c=0.9) always pin actions\n"+
+		"- [2026-07-02] (note · slug) unmarked entry defaults to 0.5\n"+
+		"- [2026-07-03] (rule · slug · c=0.75) prefer table tests\n"+
+		"- [2026-07-04] (rule · slug · c=0.6) below the floor\n")
+
+	got := TopLearnings(root, 5, 0.7)
+	if len(got) != 2 {
+		t.Fatalf("expected 2 entries >= 0.7, got %d: %v", len(got), got)
+	}
+	// Highest confidence first.
+	if want := "always pin actions"; !contains(got[0], want) {
+		t.Errorf("expected highest-confidence first; got[0]=%q", got[0])
+	}
+	if contains(got[0]+got[1], "below the floor") || contains(got[0]+got[1], "defaults to 0.5") {
+		t.Error("sub-threshold entries must not be injected")
+	}
+
+	// Cap wins.
+	if capped := TopLearnings(root, 1, 0.7); len(capped) != 1 {
+		t.Errorf("cap=1 should yield 1 entry, got %d", len(capped))
+	}
+	// max<=0 disables entirely.
+	if off := TopLearnings(root, 0, 0.7); off != nil {
+		t.Errorf("max=0 should disable injection, got %v", off)
+	}
+}
+
+func TestTopLearningsMissingLedger(t *testing.T) {
+	if got := TopLearnings(t.TempDir(), 5, 0.7); got != nil {
+		t.Errorf("missing ledger should yield nil, got %v", got)
+	}
+}
+
+func TestParseConfidence(t *testing.T) {
+	for _, s := range []string{"0", "1", "0.5", "0.73"} {
+		if _, ok := parseConfidence(s); !ok {
+			t.Errorf("%q should parse", s)
+		}
+	}
+	for _, s := range []string{"-0.1", "1.5", "high", ""} {
+		if _, ok := parseConfidence(s); ok {
+			t.Errorf("%q should be rejected", s)
+		}
+	}
+}
+
+func contains(s, sub string) bool {
+	return len(s) >= len(sub) && (s == sub || indexOf(s, sub) >= 0)
+}
+
+func indexOf(s, sub string) int {
+	for i := 0; i+len(sub) <= len(s); i++ {
+		if s[i:i+len(sub)] == sub {
+			return i
+		}
+	}
+	return -1
+}

package/engine/internal/lib/learnings_remediation_test.go

@@ -0,0 +1,24 @@
+package lib
+
+import (
+	"bytes"
+	"os"
+	"path/filepath"
+	"testing"
+)
+
+func TestLearningsAddReportsPersistenceFailure(t *testing.T) {
+	parent := t.TempDir()
+	root := filepath.Join(parent, "not-a-directory")
+	if err := os.WriteFile(root, []byte("occupied"), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	var stdout, stderr bytes.Buffer
+
+	if code := Learnings(root, []string{"add", "feat", "lesson"}, &stdout, &stderr); code == 0 {
+		t.Fatalf("code = 0, want failure; stdout=%q stderr=%q", stdout.String(), stderr.String())
+	}
+	if stdout.Len() != 0 {
+		t.Fatalf("stdout = %q, want no success message", stdout.String())
+	}
+}