devrites 3.2.27 → 4.0.0

package/engine/internal/lib/conventions.go

@@ -1,449 +0,0 @@
-package lib
-
-import (
-	"bytes"
-	"embed"
-	"fmt"
-	"io"
-	"math"
-	"os"
-	"path/filepath"
-	"sort"
-	"strconv"
-	"strings"
-	"text/template"
-	"time"
-
-	"github.com/devrites/devrites/internal/fsutil"
-)
-
-//go:embed templates/conventions_ledger_header.md templates/conventions_orient_header.txt templates/conventions_drift.tmpl
-var conventionsTemplateFS embed.FS
-
-var (
-	conventionsHeader       = mustReadConventionsTemplate("templates/conventions_ledger_header.md")
-	conventionsOrientHeader = mustReadConventionsTemplate("templates/conventions_orient_header.txt")
-	conventionsDriftTmpl    = template.Must(template.ParseFS(conventionsTemplateFS, "templates/conventions_drift.tmpl"))
-)
-
-type conventionEntry struct {
-	Statement      string
-	Kind           string
-	Status         string
-	Proofs         []string
-	Corroborations int
-	Contradictions int
-}
-
-func Conventions(args []string, stdout, stderr io.Writer) int {
-	cmd := argAt(args, 0)
-	switch cmd {
-	case "band":
-		c, ok := intFlag(args[1:], "--corroborations", true, stderr)
-		if !ok {
-			return 2
-		}
-		k, ok := intFlag(args[1:], "--contradictions", false, stderr)
-		if !ok {
-			return 2
-		}
-		if b, active := conventionBand(c, k); active {
-			fmt.Fprintf(stdout, "%.2f\n", b)
-		} else {
-			fmt.Fprintln(stdout, "retired")
-		}
-		return 0
-	case "read":
-		root := stringFlag(args[1:], "--root", ".")
-		data, err := os.ReadFile(conventionsPath(root))
-		if err != nil {
-			return 0
-		}
-		_, _ = stdout.Write(data)
-		return 0
-	case "orient":
-		return conventionsOrient(args[1:], stdout, stderr)
-	case "promote":
-		return conventionsPromote(args[1:], stdout, stderr)
-	case "contradict":
-		return conventionsContradict(args[1:], stdout, stderr)
-	default:
-		fmt.Fprintln(stderr, "usage: devrites-engine conventions <band|read|orient|promote|contradict> [flags]")
-		return 2
-	}
-}
-
-func conventionBand(corroborations, contradictions int) (float64, bool) {
-	if corroborations-contradictions <= 0 {
-		return 0, false
-	}
-	raw := 0.4 + 0.1*float64(corroborations) - 0.2*float64(contradictions)
-	return math.Max(0.3, math.Min(0.9, math.Round(raw*10)/10)), true
-}
-
-func conventionsOrient(args []string, stdout, stderr io.Writer) int {
-	root := stringFlag(args, "--root", ".")
-	minBand := floatFlag(args, "--min-band", 0)
-	entries := loadConventions(root)
-	type row struct {
-		key string
-		b   float64
-		e   conventionEntry
-	}
-	var rows []row
-	for key, e := range entries {
-		b, active := conventionBand(e.Corroborations, e.Contradictions)
-		if !active || b < minBand {
-			continue
-		}
-		rows = append(rows, row{key: key, b: b, e: e})
-	}
-	if len(rows) == 0 {
-		return 0
-	}
-	sort.Slice(rows, func(i, j int) bool {
-		if rows[i].b != rows[j].b {
-			return rows[i].b > rows[j].b
-		}
-		return rows[i].key < rows[j].key
-	})
-	fmt.Fprintln(stdout, conventionsOrientHeader)
-	for _, r := range rows {
-		kind := ""
-		if r.e.Kind != "" {
-			kind = " (" + r.e.Kind + ")"
-		}
-		fmt.Fprintf(stdout, "- [%.2f] %s%s: %s\n", r.b, r.key, kind, r.e.Statement)
-	}
-	return 0
-}
-
-func conventionsPromote(args []string, stdout, stderr io.Writer) int {
-	root := stringFlag(args, "--root", ".")
-	key, ok := requiredStringFlag(args, "--key", stderr)
-	if !ok {
-		return 2
-	}
-	statement, ok := requiredStringFlag(args, "--statement", stderr)
-	if !ok {
-		return 2
-	}
-	kind, ok := requiredStringFlag(args, "--kind", stderr)
-	if !ok {
-		return 2
-	}
-	slug, ok := requiredStringFlag(args, "--slug", stderr)
-	if !ok {
-		return 2
-	}
-	evidence, ok := requiredStringFlag(args, "--evidence", stderr)
-	if !ok {
-		return 2
-	}
-	date := stringFlag(args, "--date", "")
-	entries := loadConventions(root)
-	e, exists := entries[key]
-	if !exists {
-		e = conventionEntry{Statement: statement, Kind: kind, Status: "active"}
-	} else {
-		if statement != "" {
-			e.Statement = statement
-		}
-		if kind != "" {
-			e.Kind = kind
-		}
-	}
-	already := false
-	for _, proof := range e.Proofs {
-		if proofSlug(proof) == slug {
-			already = true
-			break
-		}
-	}
-	if !already {
-		e.Corroborations++
-		e.Proofs = append(e.Proofs, fmt.Sprintf("%s %s: %s", slug, conventionDate(date), evidence))
-	}
-	entries[key] = e
-	if err := saveConventions(root, entries); err != nil {
-		fmt.Fprintln(stderr, err)
-		return 1
-	}
-	b, active := conventionBand(e.Corroborations, e.Contradictions)
-	band := "retired"
-	if active {
-		band = fmt.Sprintf("%.2f", b)
-	}
-	fmt.Fprintf(stdout, "promoted '%s' → band %s (%d corroboration(s))\n", key, band, e.Corroborations)
-	return 0
-}
-
-func conventionsContradict(args []string, stdout, stderr io.Writer) int {
-	root := stringFlag(args, "--root", ".")
-	key, ok := requiredStringFlag(args, "--key", stderr)
-	if !ok {
-		return 2
-	}
-	slug, ok := requiredStringFlag(args, "--slug", stderr)
-	if !ok {
-		return 2
-	}
-	evidence, ok := requiredStringFlag(args, "--evidence", stderr)
-	if !ok {
-		return 2
-	}
-	date := stringFlag(args, "--date", "")
-	driftFile := stringFlag(args, "--drift-file", "")
-	entries := loadConventions(root)
-	e, exists := entries[key]
-	if !exists {
-		fmt.Fprintf(stderr, "no such convention: '%s'\n", key)
-		return 3
-	}
-	when := conventionDate(date)
-	e.Contradictions++
-	e.Proofs = append(e.Proofs, fmt.Sprintf("%s %s: CONTRADICTED: %s", slug, when, evidence))
-	entries[key] = e
-	if err := saveConventions(root, entries); err != nil {
-		fmt.Fprintln(stderr, err)
-		return 1
-	}
-	b, active := conventionBand(e.Corroborations, e.Contradictions)
-	state := "retired"
-	if active {
-		state = fmt.Sprintf("band %.2f", b)
-	}
-	if driftFile != "" {
-		if err := os.MkdirAll(filepath.Dir(absPath(driftFile)), 0o755); err != nil {
-			fmt.Fprintln(stderr, err)
-			return 1
-		}
-		f, err := os.OpenFile(driftFile, os.O_CREATE|os.O_WRONLY|os.O_APPEND, 0o644)
-		if err != nil {
-			fmt.Fprintln(stderr, err)
-			return 1
-		}
-		entry, renderErr := renderConventionDrift(key, slug, evidence, state, when)
-		if renderErr != nil {
-			_ = f.Close()
-			fmt.Fprintln(stderr, renderErr)
-			return 1
-		}
-		_, writeErr := f.WriteString(entry)
-		closeErr := f.Close()
-		if writeErr != nil {
-			fmt.Fprintln(stderr, writeErr)
-			return 1
-		}
-		if closeErr != nil {
-			fmt.Fprintln(stderr, closeErr)
-			return 1
-		}
-	}
-	fmt.Fprintf(stdout, "DRIFT: convention '%s' contradicted by %s: now %s\n", key, slug, state)
-	return 0
-}
-
-func conventionsPath(root string) string {
-	return filepath.Join(root, ".devrites", "conventions.md")
-}
-
-func loadConventions(root string) map[string]conventionEntry {
-	data, err := os.ReadFile(conventionsPath(root))
-	if err != nil {
-		return map[string]conventionEntry{}
-	}
-	return parseConventions(string(data))
-}
-
-func parseConventions(text string) map[string]conventionEntry {
-	entries := map[string]conventionEntry{}
-	key := ""
-	for _, line := range strings.Split(text, "\n") {
-		if strings.HasPrefix(line, "## ") {
-			key = strings.TrimSpace(strings.TrimPrefix(line, "## "))
-			entries[key] = conventionEntry{Status: "active"}
-			continue
-		}
-		if key == "" {
-			continue
-		}
-		e := entries[key]
-		s := strings.TrimSpace(line)
-		switch {
-		case strings.HasPrefix(s, "- proof:"):
-			e.Proofs = append(e.Proofs, strings.TrimSpace(strings.TrimPrefix(s, "- proof:")))
-		case strings.HasPrefix(s, "- ") && strings.Contains(s, ":"):
-			field, value, _ := strings.Cut(strings.TrimPrefix(s, "- "), ":")
-			field = strings.TrimSpace(field)
-			value = strings.TrimSpace(value)
-			switch field {
-			case "corroborations":
-				if n, err := strconv.Atoi(value); err == nil {
-					e.Corroborations = n
-				}
-			case "contradictions":
-				if n, err := strconv.Atoi(value); err == nil {
-					e.Contradictions = n
-				}
-			case "statement":
-				e.Statement = value
-			case "kind":
-				e.Kind = value
-			case "status":
-				e.Status = value
-			}
-		}
-		entries[key] = e
-	}
-	return entries
-}
-
-func saveConventions(root string, entries map[string]conventionEntry) error {
-	path := conventionsPath(root)
-	if err := os.MkdirAll(filepath.Dir(path), 0o755); err != nil {
-		return fmt.Errorf("create conventions dir: %w", err)
-	}
-	return fsutil.WriteFileAtomic(path, []byte(serializeConventions(entries)), 0o644)
-}
-
-func serializeConventions(entries map[string]conventionEntry) string {
-	var keys []string
-	for key := range entries {
-		keys = append(keys, key)
-	}
-	sort.Strings(keys)
-	var out []string
-	out = append(out, conventionsHeader)
-	for _, key := range keys {
-		e := entries[key]
-		b, active := conventionBand(e.Corroborations, e.Contradictions)
-		status := "retired"
-		band := "retired"
-		if active {
-			status = "active"
-			band = fmt.Sprintf("%.2f", b)
-		}
-		out = append(out,
-			"## "+key,
-			"- statement: "+e.Statement,
-			"- kind: "+e.Kind,
-			"- band: "+band,
-			fmt.Sprintf("- corroborations: %d", e.Corroborations),
-			fmt.Sprintf("- contradictions: %d", e.Contradictions),
-			"- status: "+status,
-		)
-		for _, proof := range e.Proofs {
-			out = append(out, "- proof: "+proof)
-		}
-		out = append(out, "")
-	}
-	return strings.TrimRight(strings.Join(out, "\n"), "\n") + "\n"
-}
-
-func mustReadConventionsTemplate(path string) string {
-	data, err := conventionsTemplateFS.ReadFile(path)
-	if err != nil {
-		panic(err)
-	}
-	return strings.TrimRight(string(data), "\n")
-}
-
-func renderConventionDrift(key, slug, evidence, state, when string) (string, error) {
-	var buf bytes.Buffer
-	err := conventionsDriftTmpl.Execute(&buf, struct {
-		Key      string
-		Slug     string
-		Evidence string
-		State    string
-		When     string
-	}{
-		Key:      key,
-		Slug:     slug,
-		Evidence: evidence,
-		State:    state,
-		When:     when,
-	})
-	if err != nil {
-		return buf.String(), fmt.Errorf("render drift entry: %w", err)
-	}
-	return buf.String(), nil
-}
-
-func proofSlug(proof string) string {
-	slug, _, _ := strings.Cut(proof, " ")
-	return slug
-}
-
-func conventionDate(date string) string {
-	if date != "" {
-		return date
-	}
-	return time.Now().Format("2006-01-02")
-}
-
-func stringFlag(args []string, name, fallback string) string {
-	value, ok := flagValue(args, name)
-	if !ok {
-		return fallback
-	}
-	return value
-}
-
-func flagValue(args []string, name string) (string, bool) {
-	for i := 0; i < len(args); i++ {
-		if args[i] == name && i+1 < len(args) {
-			return args[i+1], true
-		}
-		if strings.HasPrefix(args[i], name+"=") {
-			return strings.TrimPrefix(args[i], name+"="), true
-		}
-	}
-	return "", false
-}
-
-func requiredStringFlag(args []string, name string, stderr io.Writer) (string, bool) {
-	value, ok := flagValue(args, name)
-	if !ok {
-		fmt.Fprintf(stderr, "missing required flag: %s\n", name)
-		return "", false
-	}
-	return value, true
-}
-
-func intFlag(args []string, name string, required bool, stderr io.Writer) (int, bool) {
-	value, present := flagValue(args, name)
-	if !present {
-		if required {
-			fmt.Fprintf(stderr, "missing required flag: %s\n", name)
-			return 0, false
-		}
-		return 0, true
-	}
-	n, err := strconv.Atoi(value)
-	if err != nil {
-		fmt.Fprintf(stderr, "invalid integer for %s: %s\n", name, value)
-		return 0, false
-	}
-	return n, true
-}
-
-func floatFlag(args []string, name string, fallback float64) float64 {
-	value := stringFlag(args, name, "")
-	if value == "" {
-		return fallback
-	}
-	f, err := strconv.ParseFloat(value, 64)
-	if err != nil {
-		return fallback
-	}
-	return f
-}
-
-func absPath(path string) string {
-	abs, err := filepath.Abs(path)
-	if err != nil {
-		return path
-	}
-	return abs
-}

package/engine/internal/lib/coverage.go

@@ -1,145 +0,0 @@
-package lib
-
-import (
-	"fmt"
-	"io"
-	"os"
-	"path/filepath"
-	"regexp"
-	"sort"
-	"strings"
-
-	"github.com/devrites/devrites/internal/workflow"
-)
-
-// Coverage renders the AC → slice(s) → proven traceability matrix for a feature,
-// deterministically, from its workspace artifacts (spec.md / tasks.md / seal.md).
-// It is the living map /rite-prove and /rite-seal walk to prove every acceptance
-// criterion is covered by a slice and proven in the seal. Read-only.
-//
-// The convention pairs with check-acceptance: a criterion carries a stable id,
-// spec.md declares `- [ ] AC-###: …`, a tasks.md slice claims it with a
-// `Satisfies: AC-###` line, and seal.md proves it with `- [x] AC-###: …`.
-// Legacy [ACn] ids remain supported for existing workspaces.
-//
-// base is the project directory that contains the .devrites tree; slug defaults
-// to the active feature named in .devrites/ACTIVE. The matrix is the stdout
-// contract; stderr carries only the no-workspace / no-spec diagnostics.
-//
-//	0  matrix rendered
-//	2  no active workspace, no workspace directory, or no spec.md to map
-func Coverage(root string, args []string, stdout, stderr io.Writer) int {
-	slug := ""
-	if len(args) > 0 {
-		slug = args[0]
-	}
-	if slug == "" {
-		slug = activeSlug(root)
-	}
-	if slug == "" {
-		fmt.Fprintln(stderr, "coverage: no active workspace.")
-		return 2
-	}
-
-	dir := featureDir(root, slug)
-	if !isDir(dir) {
-		fmt.Fprintf(stderr, "coverage: no workspace at %s.\n", dir)
-		return 2
-	}
-
-	specBytes, err := os.ReadFile(filepath.Join(dir, "spec.md"))
-	if err != nil {
-		fmt.Fprintln(stderr, "coverage: no spec.md: nothing to map.")
-		return 2
-	}
-
-	// tasks.md / seal.md are optional inputs: a missing one just yields
-	// UNCOVERED slices / pending proof, never an error.
-	tasks, haveTasks := readFileOK(filepath.Join(dir, "tasks.md"))
-	seal, haveSeal := readFileOK(filepath.Join(dir, "seal.md"))
-
-	fmt.Fprintf(stdout, "# Coverage matrix: %s\n", slug)
-	fmt.Fprintln(stdout)
-	fmt.Fprintln(stdout, "| AC | Slice(s) | Proven in seal? |")
-	fmt.Fprintln(stdout, "|----|----------|-----------------|")
-
-	for _, ac := range acIDs(string(specBytes)) {
-		slices := ""
-		if haveTasks {
-			slices = slicesForAC(tasks, ac)
-		}
-		if slices == "" {
-			slices = "(UNCOVERED)"
-		}
-		proven := "pending"
-		if haveSeal && provenInSeal(seal, ac) {
-			proven = "yes"
-		}
-		fmt.Fprintf(stdout, "| %s | %s | %s |\n", ac, slices, proven)
-	}
-
-	fmt.Fprintln(stdout)
-	fmt.Fprintf(stdout, "_Generated by devrites-engine coverage from spec.md / tasks.md / seal.md. UNCOVERED rows block the analyze gate in %s._\n", workflow.ForVerb("vet").Both())
-	return 0
-}
-
-// acIDRe is shared with check-acceptance, which declares it.
-var (
-	sliceStripRe = regexp.MustCompile(`^##[[:space:]]*`)
-	satisfiesRe  = regexp.MustCompile(`^[[:space:]]*Satisfies:`)
-)
-
-// acIDs returns unique canonical AC-### and legacy [ACn] ids declared in
-// spec.md, bracket-stripped and byte-order sorted.
-func acIDs(spec string) []string {
-	seen := map[string]bool{}
-	var ids []string
-	for _, m := range acIDRe.FindAllString(spec, -1) {
-		id := strings.Trim(m, "[]")
-		if !seen[id] {
-			seen[id] = true
-			ids = append(ids, id)
-		}
-	}
-	sort.Strings(ids)
-	return ids
-}
-
-// slicesForAC returns the `;`-joined slice headers whose `Satisfies:` line names
-// ac, in file order. It reproduces the script's awk exactly, including its two
-// quirks: the current `## Slice …` header persists to the next Satisfies line,
-// and the match is a substring test, so ac "AC1" also matches a slice that
-// satisfies "AC10". Faithful parity requires preserving both.
-func slicesForAC(tasks, ac string) string {
-	var matched []string
-	cur := ""
-	sc := newLineScanner(strings.NewReader(tasks))
-	for sc.Scan() {
-		line := sc.Text()
-		if sliceHeadRe.MatchString(line) {
-			cur = sliceStripRe.ReplaceAllString(line, "")
-		}
-		if satisfiesRe.MatchString(line) && strings.Contains(line, ac) {
-			matched = append(matched, cur)
-		}
-	}
-	return strings.Join(matched, ";")
-}
-
-// provenInSeal reports whether seal.md contains a checked canonical or legacy
-// criterion line.
-func provenInSeal(seal, ac string) bool {
-	quoted := regexp.QuoteMeta(ac)
-	re := regexp.MustCompile(`(?m)^[[:space:]]*-[[:space:]]*\[x\][[:space:]]*(?:\[` + quoted + `\]|` + quoted + `\b)`)
-	return re.MatchString(seal)
-}
-
-// readFileOK reads a file, returning its contents and whether it existed and
-// read cleanly.
-func readFileOK(path string) (string, bool) {
-	b, err := os.ReadFile(path)
-	if err != nil {
-		return "", false
-	}
-	return string(b), true
-}

package/engine/internal/lib/dispatchwaive.go

@@ -1,31 +0,0 @@
-package lib
-
-import (
-	"fmt"
-	"io"
-)
-
-var dispatchWaiverReasons = map[string]struct{}{
-	"human-gate-before-dispatch": {},
-	"no-active-workspace":        {},
-	"no-eligible-work":           {},
-	"readiness-failed":           {},
-	"wrong-phase":                {},
-}
-
-func ValidDispatchWaiver(reason string) bool {
-	_, ok := dispatchWaiverReasons[reason]
-	return ok
-}
-
-// DispatchWaive validates the reason token used by the agent-dispatch hook.
-// The hook records the successful PostToolUse receipt; this command deliberately
-// owns no separate state.
-func DispatchWaive(args []string, stdout, stderr io.Writer) int {
-	if len(args) != 1 || !ValidDispatchWaiver(args[0]) {
-		fmt.Fprintln(stderr, "usage: devrites-engine dispatch-waive <human-gate-before-dispatch|no-active-workspace|no-eligible-work|readiness-failed|wrong-phase>")
-		return 2
-	}
-	fmt.Fprintf(stdout, "dispatch-waive: accepted %s\n", args[0])
-	return 0
-}

package/engine/internal/lib/dispatchwaive_test.go

@@ -1,23 +0,0 @@
-package lib
-
-import (
-	"bytes"
-	"strings"
-	"testing"
-)
-
-func TestDispatchWaiveAcceptsOnlyKnownSingleReason(t *testing.T) {
-	var stdout, stderr bytes.Buffer
-	if code := DispatchWaive([]string{"wrong-phase"}, &stdout, &stderr); code != 0 {
-		t.Fatalf("valid reason code=%d stderr=%s", code, stderr.String())
-	}
-	if !strings.Contains(stdout.String(), "accepted wrong-phase") {
-		t.Fatalf("missing receipt: %s", stdout.String())
-	}
-
-	stdout.Reset()
-	stderr.Reset()
-	if code := DispatchWaive([]string{"anything"}, &stdout, &stderr); code != 2 {
-		t.Fatalf("invalid reason code=%d, want 2", code)
-	}
-}