devrites 2.6.1 → 3.0.0

package/engine/internal/lib/conventions.go

@@ -0,0 +1,449 @@
+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

@@ -0,0 +1,147 @@
+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 `- [ ] [ACn] …`, a tasks.md slice claims it with a
+// `Satisfies: ACn` line, and seal.md proves it with `- [x] [ACn] …`. A criterion
+// is proven iff its `[ACn]` id is checked in seal.md.
+//
+// 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 (`\[AC[0-9]+\]`) is shared with check-acceptance, which declares it.
+var (
+	sliceHeaderRe = regexp.MustCompile(`^##[[:space:]]*Slice`)
+	sliceStripRe  = regexp.MustCompile(`^##[[:space:]]*`)
+	satisfiesRe   = regexp.MustCompile(`^[[:space:]]*Satisfies:`)
+)
+
+// acIDs returns the unique `[ACn]` ids declared in spec.md, bracket-stripped and
+// byte-order sorted — mirroring `grep -oE '\[AC[0-9]+\]' | tr -d '[]' | sort -u`
+// under LC_ALL=C.
+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 sliceHeaderRe.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 checks off ac's id — a line of the form
+// `- [x] [ACn]` (with optional surrounding whitespace), the same pattern the
+// script greps for.
+func provenInSeal(seal, ac string) bool {
+	re := regexp.MustCompile(`(?m)^[[:space:]]*-[[:space:]]*\[x\][[:space:]]*\[` + regexp.QuoteMeta(ac) + `\]`)
+	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/doubtcoverage.go

@@ -0,0 +1,88 @@
+package lib
+
+import (
+	"fmt"
+	"io"
+	"os"
+	"path/filepath"
+	"strings"
+)
+
+// DoubtCoverage answers a single deterministic question: did the build doubt the
+// decisions it stood? It reads only records /rite-build writes, so it is
+// zero-token and cannot fabricate a verdict-per-decision match — the seal's prose
+// gate and the reviewer fan-out judge the rest.
+//
+// Two signals, checked in order:
+//
+//  1. decisions.md `doubt: MISSING` — a stood decision recorded but never
+//     doubted. The unambiguous skip; checked first, on every path.
+//  2. footprint.log `wright` vs `doubt` lines — wright dispatch(es) with zero
+//     doubt is the coarse "no doubt ran at all" signal.
+//
+// base is the project directory that contains the .devrites tree.
+//
+//	0  doubt covered, or not assessable (no log / no wright / inline build) → pass
+//	1  wright dispatch(es) but ZERO doubt → verify against decisions.md
+//	2  usage (no slug)
+//	3  decisions.md records a stood decision with `doubt: MISSING`
+func DoubtCoverage(root string, args []string, stdout, stderr io.Writer) int {
+	slug := ""
+	if len(args) > 0 {
+		slug = args[0]
+	}
+	if slug == "" {
+		fmt.Fprintln(stderr, "usage: devrites-engine doubt-coverage <slug>")
+		return 2
+	}
+
+	dir := featureDir(root, slug)
+
+	// A recorded stood decision that was never doubted is the unambiguous
+	// failure — checked first, and on every path (it survives the inline-build
+	// case below, where the footprint heuristic cannot apply).
+	if dec, ok := readFileOK(filepath.Join(dir, "decisions.md")); ok && strings.Contains(dec, "doubt: MISSING") {
+		fmt.Fprintln(stdout, "doubt-coverage: SKIPPED — a '## Decisions stood' entry in decisions.md has doubt: MISSING.")
+		fmt.Fprintln(stdout, "A decision was stood and recorded but never doubted. Re-dispatch doubt or escalate.")
+		return 3
+	}
+
+	// Inline build (Task tool unavailable): the wright + doubt ran in-context,
+	// dispatching nothing, so the footprint heuristic does not apply — the
+	// decisions.md check above is the assessment.
+	if isFile(filepath.Join(dir, ".reconcile-inline")) {
+		fmt.Fprintln(stdout, "doubt-coverage: inline build (.reconcile-inline) — footprint heuristic n/a; no MISSING")
+		fmt.Fprintln(stdout, "verdict recorded. Verify by hand that each stood decision carries a devrites-doubt verdict.")
+		return 0
+	}
+
+	f, err := os.Open(filepath.Join(dir, "footprint.log"))
+	if err != nil {
+		fmt.Fprintln(stdout, "doubt-coverage: no footprint log — nothing to assess (pass)")
+		return 0
+	}
+	defer f.Close()
+
+	var wright, doubt int
+	sc := newLineScanner(f)
+	for sc.Scan() {
+		fields := strings.Fields(sc.Text())
+		if len(fields) < 2 {
+			continue
+		}
+		switch fields[1] {
+		case "wright":
+			wright++
+		case "doubt":
+			doubt++
+		}
+	}
+	fmt.Fprintf(stdout, "doubt-coverage: %d wright · %d doubt\n", wright, doubt)
+
+	if wright > 0 && doubt == 0 {
+		fmt.Fprintf(stdout, "doubt-coverage: no doubt dispatched across %d wright run(s). Either every slice's\n", wright)
+		fmt.Fprintln(stdout, "'Decisions stood' was genuinely empty, or doubt was skipped — verify against decisions.md.")
+		return 1
+	}
+	return 0
+}