devrites 2.6.1 → 3.0.0

package/engine/internal/lib/adoption_test.go

@@ -0,0 +1,91 @@
+package lib
+
+import (
+	"bytes"
+	"os"
+	"path/filepath"
+	"runtime"
+	"strings"
+	"testing"
+	"time"
+)
+
+func TestDecisionsSearchFindsArchivedDecision(t *testing.T) {
+	root := t.TempDir()
+	p := filepath.Join(root, "archive", "auth-refresh", "decisions.md")
+	mustWrite(t, p, "# Decisions\n- Use short-lived refresh tokens for auth sessions.\n")
+	var out, err bytes.Buffer
+	if code := Decisions(root, []string{"search", "refresh", "tokens"}, &out, &err); code != 0 {
+		t.Fatalf("code=%d stderr=%s", code, err.String())
+	}
+	if !strings.Contains(out.String(), "auth-refresh") || !strings.Contains(out.String(), "refresh tokens") {
+		t.Fatalf("missing decision hit:\n%s", out.String())
+	}
+}
+
+func TestDecisionsIndexAcceptsLongDecisionLine(t *testing.T) {
+	root := t.TempDir()
+	decision := "- " + strings.Repeat("a", 128*1024) + " searchable-tail\n"
+	mustWrite(t, filepath.Join(root, "archive", "large", "decisions.md"), decision)
+	var out, err bytes.Buffer
+
+	if code := Decisions(root, []string{"index"}, &out, &err); code != 0 {
+		t.Fatalf("code=%d stderr=%s", code, err.String())
+	}
+	indexed, readErr := os.ReadFile(filepath.Join(root, "decisions-index.jsonl"))
+	if readErr != nil {
+		t.Fatal(readErr)
+	}
+	if !bytes.Contains(indexed, []byte("searchable-tail")) {
+		t.Fatal("long decision was silently omitted from the index")
+	}
+}
+
+func TestSecretScanBlocksHighSeverityTouchedFile(t *testing.T) {
+	project := t.TempDir()
+	root := filepath.Join(project, ".devrites")
+	mustWrite(t, filepath.Join(root, "ACTIVE"), "leak\n")
+	mustWrite(t, filepath.Join(root, "work", "leak", "touched-files.md"), "- secrets.txt\n")
+	mustWrite(t, filepath.Join(project, "secrets.txt"), "token=ghp_abcdefghijklmnopqrstuvwxyzABCDE12345\n")
+	var out, err bytes.Buffer
+	if code := SecretScan(root, nil, &out, &err); code != 3 {
+		t.Fatalf("want block rc=3 got %d stdout=%s stderr=%s", code, out.String(), err.String())
+	}
+}
+
+func TestSpecDedupeSearchesScratchPRDs(t *testing.T) {
+	project := t.TempDir()
+	root := filepath.Join(project, ".devrites")
+	mustWrite(t, filepath.Join(project, ".scratch", "webhooks", "PRD.md"), "# Webhook retries\nAdd retry backoff for failed webhooks.\n")
+	var out, err bytes.Buffer
+	if code := SpecDedupe(root, []string{"webhook", "retry", "backoff"}, &out, &err); code != 0 {
+		t.Fatalf("code=%d stderr=%s", code, err.String())
+	}
+	if !strings.Contains(out.String(), ".scratch/webhooks/PRD.md") {
+		t.Fatalf("missing dedupe hit:\n%s", out.String())
+	}
+}
+
+func TestBoundedCommandOutputStopsLongRunningProcess(t *testing.T) {
+	if runtime.GOOS == "windows" {
+		t.Skip("test command uses POSIX sh")
+	}
+
+	started := time.Now()
+	if _, err := boundedCommandOutput(50*time.Millisecond, "", "sh", "-c", "sleep 2"); err == nil {
+		t.Fatal("expected timed-out command to return an error")
+	}
+	if elapsed := time.Since(started); elapsed > time.Second {
+		t.Fatalf("timed-out command took %s", elapsed)
+	}
+}
+
+func mustWrite(t *testing.T, path, text string) {
+	t.Helper()
+	if err := os.MkdirAll(filepath.Dir(path), 0o755); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.WriteFile(path, []byte(text), 0o644); err != nil {
+		t.Fatal(err)
+	}
+}

package/engine/internal/lib/analyze.go

@@ -0,0 +1,225 @@
+package lib
+
+import (
+	"fmt"
+	"io"
+	"os"
+	"regexp"
+	"sort"
+	"strings"
+
+	"github.com/devrites/devrites/internal/workflow"
+)
+
+// Analyze cross-checks a feature's spec.md against its tasks.md before any code is
+// written, so a coverage gap surfaces as a one-line plan edit rather than a reslice
+// mid-build. It emits a markdown report and flags:
+//
+//	Coverage     — a spec [ACn] that no slice Satisfies                (CRITICAL)
+//	Consistency  — a slice that Satisfies an AC the spec never defines (CRITICAL)
+//	Orphan slice — a slice that satisfies no acceptance criterion       (warn)
+//	Ambiguity    — an unquantified vague adjective or unresolved
+//	               placeholder in the spec                              (warn)
+//
+// It closes with a Metrics line (criteria count, coverage %, orphan + ambiguity
+// counts) so the vet gate reports a number, not just a pass/fail.
+//
+// Exit codes: 0 clear · 1 at least one CRITICAL finding · 2 no workspace (no active
+// slug, or spec.md/tasks.md missing).
+var (
+	specACRe           = regexp.MustCompile(`\[AC[0-9]+\]`) // a bracketed [ACn] in the spec
+	taskACRe           = regexp.MustCompile(`\bAC[0-9]+\b`) // a bare ACn in the tasks
+	sliceHeadRe        = regexp.MustCompile(`^##[[:space:]]*Slice`)
+	sliceNamePrefixRe  = regexp.MustCompile(`^##[[:space:]]*`) // stripped to leave the slice name
+	analyzeSatisfiesRe = regexp.MustCompile(`^[[:space:]]*Satisfies:`)
+	// Ambiguity scan: a vague quality adjective with no number on the line is an
+	// unfalsifiable criterion; an unresolved placeholder is unfinished spec text.
+	vagueAdjRe     = regexp.MustCompile(`(?i)\b(fast|scalable|secure|intuitive|robust|performant|seamless|efficient|flexible|reliable|user-friendly|graceful(?:ly)?|snappy|lightweight)\b`)
+	analyzeDigitRe = regexp.MustCompile(`[0-9]`)
+	placeholderRe  = regexp.MustCompile(`(?i)(\bTODO\b|\bTKTK\b|\bFIXME\b|\bXXX\b|\?\?\?|<placeholder>)`)
+	fenceRe        = regexp.MustCompile("^[[:space:]]*```")
+)
+
+func Analyze(root string, args []string, stdout, stderr io.Writer) int {
+	slug := slugOrActive(root, args)
+	if slug == "" {
+		fmt.Fprintln(stderr, "analyze: no active workspace.")
+		return 2
+	}
+
+	spec := featureFile(root, slug, "spec.md")
+	tasks := featureFile(root, slug, "tasks.md")
+	if !isFile(spec) || !isFile(tasks) {
+		fmt.Fprintf(stderr, "analyze: need spec.md + tasks.md in %s.\n", featureDir(root, slug))
+		return 2
+	}
+
+	specData, _ := os.ReadFile(spec)
+	tasksData, _ := os.ReadFile(tasks)
+
+	specACs := sortedACIDs(specACRe, specData, true) // brackets stripped: "[AC1]" -> "AC1"
+	taskACs := sortedACIDs(taskACRe, tasksData, false)
+	specSet := stringSet(specACs)
+	taskSet := stringSet(taskACs)
+
+	crit := 0
+	fmt.Fprintf(stdout, "# Cross-artifact analysis: %s\n", slug)
+	fmt.Fprintln(stdout)
+
+	// Coverage: spec ACs with no slice reference.
+	covered := 0
+	fmt.Fprintln(stdout, "## Coverage")
+	if len(specACs) == 0 {
+		fmt.Fprintln(stdout, "- [warn] spec.md — no [ACn] acceptance ids found; tag criteria as '[AC1] ...' for a machine-checkable gate.")
+	} else {
+		for _, ac := range specACs {
+			if taskSet[ac] {
+				covered++
+				fmt.Fprintf(stdout, "- [ok] %s — covered\n", ac)
+			} else {
+				fmt.Fprintf(stdout, "- [CRITICAL] %s (spec.md) — no slice Satisfies it (uncovered)\n", ac)
+				crit++
+			}
+		}
+	}
+
+	// Dangling refs: tasks Satisfies an AC the spec doesn't define.
+	fmt.Fprintln(stdout)
+	fmt.Fprintln(stdout, "## Consistency")
+	if len(taskACs) > 0 {
+		for _, ac := range taskACs {
+			if !specSet[ac] {
+				fmt.Fprintf(stdout, "- [CRITICAL] %s (tasks.md) — referenced by a slice but not defined in spec.md (dangling)\n", ac)
+				crit++
+			}
+		}
+	}
+
+	// Orphan slices: a slice with no Satisfies line (printed directly, no blank before).
+	orphans := 0
+	for _, name := range orphanSlices(tasksData) {
+		if name != "" {
+			orphans++
+			fmt.Fprintf(stdout, "- [warn] slice '%s' — satisfies no acceptance criterion (add Satisfies: or justify)\n", name)
+		}
+	}
+
+	// Ambiguity: unquantified vague adjectives + unresolved placeholders in the spec.
+	fmt.Fprintln(stdout)
+	fmt.Fprintln(stdout, "## Ambiguity")
+	ambig := ambiguityFindings(specData)
+	if len(ambig) == 0 {
+		fmt.Fprintln(stdout, "- [ok] no unquantified adjectives or unresolved placeholders found")
+	} else {
+		for _, line := range ambig {
+			fmt.Fprintln(stdout, line)
+		}
+	}
+
+	// Metrics: a single machine-readable line so the vet gate reports a number.
+	fmt.Fprintln(stdout)
+	fmt.Fprintln(stdout, "## Metrics")
+	if len(specACs) == 0 {
+		fmt.Fprintf(stdout, "- Acceptance criteria: 0 (none tagged) · orphan slices %d · ambiguity flags %d\n", orphans, len(ambig))
+	} else {
+		fmt.Fprintf(stdout, "- Acceptance criteria: %d · covered %d/%d (%d%%) · orphan slices %d · ambiguity flags %d\n",
+			len(specACs), covered, len(specACs), covered*100/len(specACs), orphans, len(ambig))
+	}
+
+	fmt.Fprintln(stdout)
+	if crit > 0 {
+		fmt.Fprintf(stdout, "## Verdict: BLOCKED — %d CRITICAL finding(s). Resolve before %s.\n", crit, workflow.ForVerb("build").Both())
+		return 1
+	}
+	fmt.Fprintln(stdout, "## Verdict: clear — spec/tasks consistent and fully mapped.")
+	return 0
+}
+
+// ambiguityFindings scans spec text for unfalsifiable criteria: a vague quality
+// adjective (fast, robust, secure …) on a line with no number to pin it down, or an
+// unresolved placeholder (TODO, ???, <placeholder> …). Code fences are skipped. One
+// finding per line — a placeholder takes precedence over an adjective. 1-based lines.
+func ambiguityFindings(specData []byte) []string {
+	var out []string
+	inFence := false
+	for i, line := range splitLinesNoTrailing(specData) {
+		if fenceRe.MatchString(line) {
+			inFence = !inFence
+			continue
+		}
+		if inFence {
+			continue
+		}
+		ln := i + 1
+		if m := placeholderRe.FindString(line); m != "" {
+			out = append(out, fmt.Sprintf("- [warn] spec.md:L%d — unresolved placeholder %q", ln, m))
+			continue
+		}
+		// Strip the AC id before the digit gate — else the id's own digit
+		// ("[AC1]") masks a vague adjective on the very criterion line it tags.
+		bare := specACRe.ReplaceAllString(line, "")
+		bare = taskACRe.ReplaceAllString(bare, "")
+		if !analyzeDigitRe.MatchString(bare) {
+			if m := vagueAdjRe.FindString(bare); m != "" {
+				out = append(out, fmt.Sprintf("- [warn] spec.md:L%d — %q is not quantified; state a measurable target", ln, m))
+			}
+		}
+	}
+	return out
+}
+
+// sortedACIDs collects every acceptance id matched by re, deduplicated and sorted
+// lexicographically. When strip is set the surrounding brackets are removed, so
+// "[AC1]" becomes "AC1". Returns nil when there are none.
+func sortedACIDs(re *regexp.Regexp, data []byte, strip bool) []string {
+	seen := map[string]bool{}
+	var out []string
+	for _, line := range splitLinesNoTrailing(data) {
+		for _, m := range re.FindAllString(line, -1) {
+			if strip {
+				m = strings.NewReplacer("[", "", "]", "").Replace(m)
+			}
+			if !seen[m] {
+				seen[m] = true
+				out = append(out, m)
+			}
+		}
+	}
+	sort.Strings(out)
+	return out
+}
+
+// stringSet builds a membership set for O(1) lookups.
+func stringSet(in []string) map[string]bool {
+	m := make(map[string]bool, len(in))
+	for _, s := range in {
+		m[s] = true
+	}
+	return m
+}
+
+// orphanSlices returns the names of slices in tasks.md that have no Satisfies:
+// line. A "## Slice ..." header opens a slice; any Satisfies: line before the next
+// header marks it satisfied. Each header (and end of file) closes the previous
+// slice, emitting it when it went unsatisfied.
+func orphanSlices(data []byte) []string {
+	var out []string
+	name := ""
+	sat := false
+	for _, line := range splitLinesNoTrailing(data) {
+		if sliceHeadRe.MatchString(line) {
+			if name != "" && !sat {
+				out = append(out, name)
+			}
+			name = sliceNamePrefixRe.ReplaceAllString(line, "")
+			sat = false
+		}
+		if analyzeSatisfiesRe.MatchString(line) {
+			sat = true
+		}
+	}
+	if name != "" && !sat {
+		out = append(out, name)
+	}
+	return out
+}

package/engine/internal/lib/archivesearch.go

@@ -0,0 +1,93 @@
+package lib
+
+import (
+	"fmt"
+	"io"
+	"os"
+	"path/filepath"
+	"sort"
+	"strings"
+)
+
+// ArchiveSearch surfaces shipped features whose spec.md overlaps a query, so
+// /rite-spec can spot prior art before writing a new spec — an extension, a
+// conflict, or a re-spec of solved work. It is advisory, not a gate: it always
+// exits 0 when it runs (empty output means no overlap), and reserves exit 2 for
+// a missing query. The query is the feature's key nouns, one or many args; a
+// quoted phrase is split on whitespace. Ranking is by the count of distinct query
+// terms a spec contains, highest first, ties broken by slug.
+//
+// args is `<term>...`. Terms shorter than three characters are dropped as noise.
+func ArchiveSearch(root string, args []string, stdout, stderr io.Writer) int {
+	var terms []string
+	seen := map[string]bool{}
+	for _, a := range args {
+		for _, t := range strings.Fields(strings.ToLower(a)) {
+			if len(t) >= 3 && !seen[t] {
+				seen[t] = true
+				terms = append(terms, t)
+			}
+		}
+	}
+	if len(terms) == 0 {
+		fmt.Fprintln(stderr, `usage: devrites-engine archive-search "<key nouns>"`)
+		return 2 // usage
+	}
+
+	entries, err := os.ReadDir(filepath.Join(root, "archive"))
+	if err != nil {
+		// No archive yet — no prior art to surface. Silent, successful no-op.
+		return 0
+	}
+
+	type hit struct {
+		slug  string
+		n     int
+		title string
+	}
+	var hits []hit
+	for _, e := range entries {
+		if !e.IsDir() {
+			continue
+		}
+		spec := filepath.Join(root, "archive", e.Name(), "spec.md")
+		b, err := os.ReadFile(spec)
+		if err != nil {
+			continue
+		}
+		body := strings.ToLower(string(b))
+		n := 0
+		for _, t := range terms {
+			if strings.Contains(body, t) {
+				n++
+			}
+		}
+		if n > 0 {
+			hits = append(hits, hit{slug: e.Name(), n: n, title: specTitle(b)})
+		}
+	}
+
+	sort.Slice(hits, func(i, j int) bool {
+		if hits[i].n != hits[j].n {
+			return hits[i].n > hits[j].n
+		}
+		return hits[i].slug < hits[j].slug
+	})
+	for _, h := range hits {
+		fmt.Fprintf(stdout, "%s\t%d/%d terms\t%s\n", h.slug, h.n, len(terms), h.title)
+	}
+	return 0
+}
+
+// specTitle returns the spec's first Markdown heading, or its first non-empty
+// line, as a one-line label — empty when the spec has neither.
+func specTitle(b []byte) string {
+	for _, line := range strings.Split(string(b), "\n") {
+		line = strings.TrimSpace(line)
+		if line == "" {
+			continue
+		}
+		return strings.TrimSpace(strings.TrimLeft(line, "#"))
+	}
+	return ""
+}

package/engine/internal/lib/archivesearch_test.go

@@ -0,0 +1,110 @@
+package lib
+
+import (
+	"bytes"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+)
+
+func TestArchiveSearch(t *testing.T) {
+	root := t.TempDir()
+	writeArchiveSpec(t, root, "search-ranking", "# Search ranking\nRank results by relevance score.\n")
+	writeArchiveSpec(t, root, "auth-tokens", "# Auth token rotation\nRotate the search index credentials.\n")
+	writeArchiveSpec(t, root, "billing", "# Billing exports\nExport invoices.\n")
+
+	for _, tc := range []struct {
+		name     string
+		args     []string
+		wantCode int
+		// wantOrder lists slugs expected in stdout, in order; absent slugs must not appear.
+		wantOrder []string
+		absent    []string
+		wantErr   string
+	}{
+		{
+			name:      "ranks by distinct term hits",
+			args:      []string{"search", "ranking"},
+			wantCode:  0,
+			wantOrder: []string{"search-ranking", "auth-tokens"}, // 2/2 before 1/2
+			absent:    []string{"billing"},
+		},
+		{
+			name:     "phrase is split on whitespace",
+			args:     []string{"search ranking"},
+			wantCode: 0,
+			// same result as two args
+			wantOrder: []string{"search-ranking", "auth-tokens"},
+		},
+		{
+			name:     "no overlap is a silent success",
+			args:     []string{"kubernetes"},
+			wantCode: 0,
+			absent:   []string{"search-ranking", "auth-tokens", "billing"},
+		},
+		{
+			name:     "missing query is a usage error",
+			args:     nil,
+			wantCode: 2,
+			wantErr:  "usage: devrites-engine archive-search",
+		},
+		{
+			name:     "short noise terms are dropped",
+			args:     []string{"a", "to"},
+			wantCode: 2, // both under 3 chars → no terms → usage
+			wantErr:  "usage: devrites-engine archive-search",
+		},
+	} {
+		t.Run(tc.name, func(t *testing.T) {
+			stdout, stderr := &bytes.Buffer{}, &bytes.Buffer{}
+			code := ArchiveSearch(root, tc.args, stdout, stderr)
+			if code != tc.wantCode {
+				t.Fatalf("code=%d, want %d; stdout=%q stderr=%q", code, tc.wantCode, stdout.String(), stderr.String())
+			}
+			out := stdout.String()
+			last := -1
+			for _, slug := range tc.wantOrder {
+				idx := strings.Index(out, slug)
+				if idx < 0 {
+					t.Fatalf("stdout=%q missing expected slug %q", out, slug)
+				}
+				if idx < last {
+					t.Fatalf("stdout=%q: slug %q out of expected rank order", out, slug)
+				}
+				last = idx
+			}
+			for _, slug := range tc.absent {
+				if strings.Contains(out, slug) {
+					t.Fatalf("stdout=%q unexpectedly contains %q", out, slug)
+				}
+			}
+			if tc.wantErr != "" && !strings.Contains(stderr.String(), tc.wantErr) {
+				t.Fatalf("stderr=%q, want substring %q", stderr.String(), tc.wantErr)
+			}
+		})
+	}
+}
+
+// TestArchiveSearchNoArchive: absent archive dir → silent exit 0, not a crash.
+func TestArchiveSearchNoArchive(t *testing.T) {
+	root := t.TempDir()
+	stdout, stderr := &bytes.Buffer{}, &bytes.Buffer{}
+	if code := ArchiveSearch(root, []string{"anything"}, stdout, stderr); code != 0 {
+		t.Fatalf("code=%d, want 0; stderr=%q", code, stderr.String())
+	}
+	if stdout.String() != "" {
+		t.Fatalf("stdout=%q, want empty", stdout.String())
+	}
+}
+
+func writeArchiveSpec(t *testing.T, root, slug, content string) {
+	t.Helper()
+	dir := filepath.Join(root, "archive", slug)
+	if err := os.MkdirAll(dir, 0o755); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.WriteFile(filepath.Join(dir, "spec.md"), []byte(content), 0o644); err != nil {
+		t.Fatal(err)
+	}
+}

package/engine/internal/lib/budget.go

@@ -0,0 +1,172 @@
+package lib
+
+import (
+	"fmt"
+	"io"
+	"os"
+	"path/filepath"
+)
+
+// The context-budget lint. A feature is deliberately a directory of small,
+// single-concern files rather than one long document: each file stays
+// context-cheap to read, and completeness is self-evident from which files
+// exist. That discipline only holds if the files stay small — a spec.md that
+// grows to 800 lines is a "sausage" that an agent must load whole, spending the
+// context window it was meant to conserve. Budget measures every workspace file
+// against a per-file line ceiling and flags the overgrown ones.
+//
+// It is advisory by default (exit 0): the ceilings are guidance, and a passing
+// build is never blocked on a long file. Pass --strict to turn an overflow into
+// the standard block exit (3), so a gate or hook can hold on it.
+
+// budgetLimits is the per-file line ceiling for the known workspace files, in the
+// order they are reported. The order is the workflow's reading order (manifest
+// first, then the spec-through-proof arc, then the working and cross-cutting
+// notes), not alphabetical, so the report reads top-to-bottom like the workspace.
+var budgetLimits = []struct {
+	name  string
+	limit int
+}{
+	{"README.md", 120},           // workspace map and read-next table
+	{"index.md", 120},            // workspace map alias
+	{"feature.md", 120},          // legacy workspace map alias
+	{"brief.md", 80},             // objective and bounds
+	{"spec.md", 260},             // product WHAT/WHY and acceptance contract
+	{"ai-spec.md", 160},          // optional AI/LLM annex
+	{"architecture.md", 180},     // technical map
+	{"flows.md", 160},            // useful diagrams only
+	{"plan.md", 220},             // approach and slice strategy
+	{"tasks.md", 280},            // vertical slices
+	{"traceability.md", 220},     // AC/REQ -> slice -> proof matrix
+	{"decisions.md", 200},        // ADR-style decision log
+	{"assumptions.md", 160},      // assumption register
+	{"questions.md", 180},        // human questions and gates
+	{"drift.md", 160},            // spec/plan drift register
+	{"state.md", 120},            // compact cursor
+	{"status.md", 120},           // status checkpoint alias
+	{"evidence.md", 280},         // command/action proof
+	{"proof.md", 280},            // evidence alias
+	{"browser-evidence.md", 220}, // UI/browser proof
+	{"touched-files.md", 160},    // implementation file map
+	{"design-brief.md", 160},     // UI design contract
+	{"handoff.md", 120},          // cold-resume summary
+	{"references.md", 160},       // source pointers
+	{"learnings.md", 200},        // retrospective ledger
+}
+
+// defaultBudget is the ceiling applied to any other *.md file in the workspace
+// that has no explicit budget above.
+const defaultBudget = 200
+
+// Budget lints every present workspace file for a feature against its line
+// ceiling. root is the .devrites directory; the slug defaults to the active
+// feature at <root>/ACTIVE. Args: an optional slug and an optional --strict flag.
+func Budget(root string, args []string, stdout, stderr io.Writer) int {
+	strict := false
+	slug := ""
+	for _, a := range args {
+		switch {
+		case a == "--strict":
+			strict = true
+		case slug == "":
+			slug = a
+		default:
+			fmt.Fprintln(stderr, "usage: devrites-engine budget [slug] [--strict]")
+			return 2
+		}
+	}
+	if slug == "" {
+		slug = activeSlug(root)
+	}
+	if slug == "" {
+		fmt.Fprintln(stderr, "budget: no active feature (set one via ACTIVE or pass a slug)")
+		return 2
+	}
+	dir := featureDir(root, slug)
+	if !isDir(dir) {
+		fmt.Fprintf(stderr, "budget: no such feature: %s\n", slug)
+		return 2
+	}
+
+	rows := collectBudgetRows(dir)
+
+	fmt.Fprintf(stdout, "budget: %s\n", slug)
+	over := 0
+	for _, r := range rows {
+		status := "ok"
+		if r.lines > r.limit {
+			status = fmt.Sprintf("OVER by %d", r.lines-r.limit)
+			over++
+		}
+		fmt.Fprintf(stdout, "  %-14s %5d lines  ~%5d tok  limit %4d  %s\n",
+			r.name, r.lines, r.tokens, r.limit, status)
+	}
+
+	if over == 0 {
+		fmt.Fprintf(stdout, "budget: all %d file(s) within budget\n", len(rows))
+		return 0
+	}
+	if strict {
+		fmt.Fprintf(stdout, "budget: %d file(s) over the line budget — split or trim them\n", over)
+		return 3
+	}
+	fmt.Fprintf(stdout, "budget: %d file(s) over the line budget (advisory — pass --strict to fail)\n", over)
+	return 0
+}
+
+// budgetRow is one measured file in the report.
+type budgetRow struct {
+	name   string
+	lines  int
+	tokens int
+	limit  int
+}
+
+// collectBudgetRows measures every present workspace file: the known files (in
+// canonical reading order) followed by any other *.md file (sorted), so the
+// output is a deterministic function of the directory contents.
+func collectBudgetRows(dir string) []budgetRow {
+	known := make(map[string]bool, len(budgetLimits))
+	var rows []budgetRow
+	for _, b := range budgetLimits {
+		known[b.name] = true
+		if lines, tokens, ok := measureFile(filepath.Join(dir, b.name)); ok {
+			rows = append(rows, budgetRow{b.name, lines, tokens, b.limit})
+		}
+	}
+	// Any other Markdown file in the workspace gets the default ceiling. feature.md
+	// et al. are already covered above; a stray notes.md is measured too so nothing
+	// grows unmeasured.
+	entries, err := os.ReadDir(dir)
+	if err != nil {
+		return rows
+	}
+	var extras []string
+	for _, e := range entries {
+		name := e.Name()
+		if e.IsDir() || known[name] || filepath.Ext(name) != ".md" {
+			continue
+		}
+		extras = append(extras, name)
+	}
+	for _, name := range extras {
+		if lines, tokens, ok := measureFile(filepath.Join(dir, name)); ok {
+			rows = append(rows, budgetRow{name, lines, tokens, defaultBudget})
+		}
+	}
+	return rows
+}
+
+// measureFile returns a file's line count and an approximate token count
+// (bytes/4, the standard rough English heuristic), or ok=false if it cannot be
+// read. Lines count text records, ignoring a single trailing newline, so a
+// newline-terminated N-line file measures N, not N+1.
+func measureFile(path string) (lines, tokens int, ok bool) {
+	data, err := os.ReadFile(path)
+	if err != nil {
+		return 0, 0, false
+	}
+	lines = len(splitLinesNoTrailing(data))
+	tokens = (len(data) + 3) / 4
+	return lines, tokens, true
+}