devrites 2.6.0 → 3.0.0

package/engine/internal/lib/reviewerstats.go

@@ -0,0 +1,199 @@
+package lib
+
+import (
+	"bufio"
+	"encoding/json"
+	"fmt"
+	"io"
+	"os"
+	"path/filepath"
+	"regexp"
+	"sort"
+	"strconv"
+)
+
+// gateStreak is how many consecutive zero-finding dispatches make a gateable
+// reviewer a gate-candidate. Deterministic and engine-owned: the skill reads the
+// verdict, it never re-derives the threshold.
+const gateStreak = 10
+
+// reviewerStatsFile is the project-level (cross-feature) dispatch-outcome ledger.
+const reviewerStatsFile = "reviewer-stats.jsonl"
+
+type reviewerStatEntry struct {
+	TS       string `json:"ts"`
+	Slug     string `json:"slug,omitempty"`
+	Agent    string `json:"agent"`
+	Findings int    `json:"findings"`
+}
+
+var reviewerAgentRe = regexp.MustCompile(`^devrites-[a-z][a-z-]*$`)
+
+// alwaysOnReviewers are the roster's unconditional axes — stats are recorded for
+// visibility but the verdict is always run.
+var alwaysOnReviewers = map[string]bool{
+	"devrites-spec-reviewer": true,
+	"devrites-code-reviewer": true,
+	"devrites-test-analyst":  true,
+}
+
+// insuranceReviewers are never gated regardless of streak: their value is the
+// absence of findings, so a dry streak is success, not waste.
+var insuranceReviewers = map[string]bool{
+	"devrites-security-auditor": true,
+	"devrites-doubt-reviewer":   true,
+}
+
+// ReviewerStats maintains the per-reviewer dispatch-outcome ledger the fan-out
+// consults before dispatching conditional reviewers.
+//
+//	record <agent> <surviving-findings> [slug]  append one dispatch outcome
+//	report [--json]                             per-agent verdict: run | gate-candidate
+func ReviewerStats(root string, args []string, stdout, stderr io.Writer) int {
+	switch argAt(args, 0) {
+	case "record":
+		agent := argAt(args, 1)
+		if !reviewerAgentRe.MatchString(agent) {
+			fmt.Fprintln(stderr, "reviewer-stats: agent must match ^devrites-[a-z][a-z-]*$")
+			return 2
+		}
+		n, err := strconv.Atoi(argAt(args, 2))
+		if err != nil || n < 0 {
+			fmt.Fprintln(stderr, "reviewer-stats: <surviving-findings> must be a non-negative integer")
+			return 2
+		}
+		slug := argAt(args, 3)
+		if slug == "" {
+			slug = activeSlug(root)
+		}
+		if err := os.MkdirAll(root, 0o755); err != nil {
+			fmt.Fprintf(stderr, "reviewer-stats: %v\n", err)
+			return 1
+		}
+		entry := reviewerStatEntry{TS: nowUTC(), Slug: slug, Agent: agent, Findings: n}
+		if err := appendJSONLine(filepath.Join(root, reviewerStatsFile), entry); err != nil {
+			fmt.Fprintf(stderr, "reviewer-stats: %v\n", err)
+			return 1
+		}
+		fmt.Fprintln(stdout, "reviewer-stats: recorded.")
+		return 0
+	case "report":
+		wantJSON := argAt(args, 1) == "--json"
+		rows, err := reviewerStatRows(root)
+		if err != nil {
+			fmt.Fprintf(stderr, "reviewer-stats: %v\n", err)
+			return 1
+		}
+		if len(rows) == 0 {
+			fmt.Fprintln(stdout, "reviewer-stats: no dispatches recorded.")
+			return 0
+		}
+		if wantJSON {
+			enc := json.NewEncoder(stdout)
+			return jsonEncodeRows(enc, rows, stderr)
+		}
+		for _, r := range rows {
+			fmt.Fprintf(stdout, "%s: %s (%d finding%s / %d dispatch%s, zero-streak %d)\n",
+				r.Agent, r.Verdict, r.Findings, plural(r.Findings), r.Dispatches, pluralES(r.Dispatches), r.ZeroStreak)
+		}
+		return 0
+	default:
+		fmt.Fprintln(stderr, "usage: devrites-engine reviewer-stats record <agent> <surviving-findings> [slug] | report [--json]")
+		return 2
+	}
+}
+
+type reviewerStatRow struct {
+	Agent      string `json:"agent"`
+	Dispatches int    `json:"dispatches"`
+	Findings   int    `json:"findings"`
+	ZeroStreak int    `json:"zero_streak"`
+	Verdict    string `json:"verdict"`
+}
+
+func jsonEncodeRows(enc *json.Encoder, rows []reviewerStatRow, stderr io.Writer) int {
+	for _, r := range rows {
+		if err := enc.Encode(r); err != nil {
+			fmt.Fprintf(stderr, "reviewer-stats: %v\n", err)
+			return 1
+		}
+	}
+	return 0
+}
+
+func reviewerStatRows(root string) ([]reviewerStatRow, error) {
+	f, err := os.Open(filepath.Join(root, reviewerStatsFile))
+	if err != nil {
+		if os.IsNotExist(err) {
+			return nil, nil
+		}
+		return nil, err
+	}
+	defer f.Close()
+
+	type acc struct {
+		dispatches, findings, zeroStreak int
+	}
+	byAgent := map[string]*acc{}
+	s := bufio.NewScanner(f)
+	s.Buffer(make([]byte, 64*1024), 1024*1024)
+	for s.Scan() {
+		var e reviewerStatEntry
+		if json.Unmarshal(s.Bytes(), &e) != nil || e.Agent == "" {
+			continue // a corrupt line degrades the report, never breaks it
+		}
+		a := byAgent[e.Agent]
+		if a == nil {
+			a = &acc{}
+			byAgent[e.Agent] = a
+		}
+		a.dispatches++
+		a.findings += e.Findings
+		if e.Findings == 0 {
+			a.zeroStreak++
+		} else {
+			a.zeroStreak = 0
+		}
+	}
+	if err := s.Err(); err != nil {
+		return nil, err
+	}
+
+	agents := make([]string, 0, len(byAgent))
+	for name := range byAgent {
+		agents = append(agents, name)
+	}
+	sort.Strings(agents)
+	rows := make([]reviewerStatRow, 0, len(agents))
+	for _, name := range agents {
+		a := byAgent[name]
+		rows = append(rows, reviewerStatRow{
+			Agent:      name,
+			Dispatches: a.dispatches,
+			Findings:   a.findings,
+			ZeroStreak: a.zeroStreak,
+			Verdict:    reviewerVerdict(name, a.zeroStreak),
+		})
+	}
+	return rows, nil
+}
+
+func reviewerVerdict(agent string, zeroStreak int) string {
+	switch {
+	case alwaysOnReviewers[agent]:
+		return "run (always-on)"
+	case insuranceReviewers[agent]:
+		return "run (insurance — never gated)"
+	case zeroStreak >= gateStreak:
+		return "gate-candidate"
+	default:
+		return "run"
+	}
+}
+
+func pluralES(n int) string {
+	if n == 1 {
+		return ""
+	}
+	return "es"
+}

package/engine/internal/lib/reviewerstats_test.go

@@ -0,0 +1,104 @@
+package lib
+
+import (
+	"fmt"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+)
+
+func recordStat(t *testing.T, root, agent string, findings int) {
+	t.Helper()
+	var out, errOut strings.Builder
+	if rc := ReviewerStats(root, []string{"record", agent, fmt.Sprint(findings)}, &out, &errOut); rc != 0 {
+		t.Fatalf("record %s %d: rc=%d stderr=%s", agent, findings, rc, errOut.String())
+	}
+}
+
+func reportStats(t *testing.T, root string) string {
+	t.Helper()
+	var out, errOut strings.Builder
+	if rc := ReviewerStats(root, []string{"report"}, &out, &errOut); rc != 0 {
+		t.Fatalf("report: rc=%d stderr=%s", rc, errOut.String())
+	}
+	return out.String()
+}
+
+func TestReviewerStatsGateCandidateAfterDryStreak(t *testing.T) {
+	root := t.TempDir()
+	for i := 0; i < gateStreak; i++ {
+		recordStat(t, root, "devrites-performance-reviewer", 0)
+	}
+	got := reportStats(t, root)
+	if !strings.Contains(got, "devrites-performance-reviewer: gate-candidate") {
+		t.Fatalf("want gate-candidate after %d dry dispatches, got %q", gateStreak, got)
+	}
+}
+
+func TestReviewerStatsFindingResetsStreak(t *testing.T) {
+	root := t.TempDir()
+	for i := 0; i < gateStreak; i++ {
+		recordStat(t, root, "devrites-devex-reviewer", 0)
+	}
+	recordStat(t, root, "devrites-devex-reviewer", 2)
+	got := reportStats(t, root)
+	if !strings.Contains(got, "devrites-devex-reviewer: run (") {
+		t.Fatalf("a finding must reset the streak to run, got %q", got)
+	}
+}
+
+func TestReviewerStatsInsuranceAndAlwaysOnNeverGate(t *testing.T) {
+	root := t.TempDir()
+	for i := 0; i < gateStreak+5; i++ {
+		recordStat(t, root, "devrites-security-auditor", 0)
+		recordStat(t, root, "devrites-spec-reviewer", 0)
+	}
+	got := reportStats(t, root)
+	if strings.Contains(got, "gate-candidate") {
+		t.Fatalf("insurance/always-on reviewers must never be gate-candidates, got %q", got)
+	}
+	if !strings.Contains(got, "devrites-security-auditor: run (insurance") {
+		t.Fatalf("want insurance verdict for security auditor, got %q", got)
+	}
+	if !strings.Contains(got, "devrites-spec-reviewer: run (always-on)") {
+		t.Fatalf("want always-on verdict for spec reviewer, got %q", got)
+	}
+}
+
+func TestReviewerStatsRejectsBadInput(t *testing.T) {
+	root := t.TempDir()
+	var out, errOut strings.Builder
+	if rc := ReviewerStats(root, []string{"record", "not a valid agent", "0"}, &out, &errOut); rc != 2 {
+		t.Fatalf("invalid agent name: want rc=2, got %d", rc)
+	}
+	if rc := ReviewerStats(root, []string{"record", "devrites-code-reviewer", "-1"}, &out, &errOut); rc != 2 {
+		t.Fatalf("negative findings: want rc=2, got %d", rc)
+	}
+}
+
+func TestReviewerStatsCorruptLineDegradesNotBreaks(t *testing.T) {
+	root := t.TempDir()
+	recordStat(t, root, "devrites-frontend-reviewer", 1)
+	f, err := os.OpenFile(filepath.Join(root, reviewerStatsFile), os.O_APPEND|os.O_WRONLY, 0o644)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if _, err := f.WriteString("{not json\n"); err != nil {
+		t.Fatal(err)
+	}
+	if err := f.Close(); err != nil {
+		t.Fatal(err)
+	}
+	got := reportStats(t, root)
+	if !strings.Contains(got, "devrites-frontend-reviewer: run (1 finding / 1 dispatch, zero-streak 0)") {
+		t.Fatalf("corrupt line must not break the report, got %q", got)
+	}
+}
+
+func TestReviewerStatsEmptyReport(t *testing.T) {
+	got := reportStats(t, t.TempDir())
+	if !strings.Contains(got, "no dispatches recorded") {
+		t.Fatalf("empty ledger: got %q", got)
+	}
+}

package/engine/internal/lib/reviewintegrity.go

@@ -0,0 +1,143 @@
+package lib
+
+import (
+	"fmt"
+	"io"
+	"path/filepath"
+	"regexp"
+	"strings"
+)
+
+// findingLabel matches a bold severity label — the shape a *real* finding carries
+// in review.md (`- **Critical** — ...`). A plain summary count ("Critical 0 /
+// Important 0") is deliberately NOT matched: an all-zero tally is the rubber-stamp
+// this gate exists to catch, not evidence that review happened.
+var findingLabel = regexp.MustCompile(`\*\*(Critical|Important|Suggestion|Nit|FYI)\*\*`)
+
+// noFindingsMarker matches the justification an adversarial reviewer must leave
+// when it genuinely finds nothing — the axis stayed clean, and here is the
+// account of the passes that came back empty. Presence is all this gate checks;
+// the quality of the account is the reviewer fan-out's job (same contract as
+// doubt-coverage's `doubt: MISSING` and footprint's roster).
+var noFindingsMarker = regexp.MustCompile(`(?i)no[- ]findings`)
+
+// reviewAxes are the adversarial axes rite-review always dispatches. Each writes a
+// `## Spec` / `## Code review` section into review.md; a section that carries
+// neither a finding nor a no-findings justification is a *silent* reviewer.
+var reviewAxes = []struct {
+	label   string   // display name
+	headers []string // lower-cased heading spellings that open the section
+}{
+	{"Spec", []string{"spec"}},
+	{"Code review", []string{"code review", "code-review"}},
+}
+
+// ReviewIntegrity guards the opposite failure from the rest of review discipline:
+// not the noisy false positive (which confidence-banding suppresses) but the
+// silent false negative — a reviewer that returns "looks good, nothing found".
+// An empty findings list is treated as suspicious, not as a pass: an adversarial
+// axis that reports nothing must justify the emptiness, exactly as it must quote a
+// line to raise a finding. Read-only; the workspace is <root>/work/<slug>.
+//
+//	0  every axis accounted for — has findings, has a no-findings justification, or review.md absent/freeform
+//	2  usage (no slug)
+//	1  an adversarial axis is silent AND unjustified — a suspected rubber-stamp
+func ReviewIntegrity(root string, args []string, stdout, stderr io.Writer) int {
+	slug := argAt(args, 0)
+	if slug == "" {
+		slug = activeSlug(root)
+	}
+	if slug == "" {
+		fmt.Fprintln(stderr, "usage: devrites-engine review-integrity <slug>")
+		return 2
+	}
+
+	dir := featureDir(root, slug)
+	review, ok := readFileOK(filepath.Join(dir, "review.md"))
+	if !ok {
+		fmt.Fprintln(stdout, "review-integrity: no review.md — nothing to assess (pass)")
+		return 0
+	}
+
+	sections := axisSections(review)
+	if len(sections) == 0 {
+		// A freeform review with no `## Spec` / `## Code review` headings can't be
+		// assessed mechanically — say so and pass rather than flag a format choice.
+		fmt.Fprintln(stdout, "review-integrity: no per-axis sections in review.md — heading-based check n/a (pass)")
+		return 0
+	}
+
+	var silent []string
+	for _, ax := range reviewAxes {
+		body, present := sections[ax.label]
+		if !present {
+			continue // axis not written as its own section — nothing to check here
+		}
+		hasFinding := findingLabel.MatchString(body)
+		justified := noFindingsMarker.MatchString(body)
+		switch {
+		case hasFinding:
+			fmt.Fprintf(stdout, "  %s: findings present\n", ax.label)
+		case justified:
+			fmt.Fprintf(stdout, "  %s: clean — no-findings justification present\n", ax.label)
+		default:
+			fmt.Fprintf(stdout, "  %s: SILENT (no finding, no justification)\n", ax.label)
+			silent = append(silent, ax.label)
+		}
+	}
+
+	if len(silent) > 0 {
+		fmt.Fprintf(stdout, "review-integrity: SILENT — %s reviewed nothing and justified nothing.\n", strings.Join(silent, ", "))
+		fmt.Fprintln(stdout, "A zero-findings axis is suspicious, not a pass. Re-run the axis, or record a")
+		fmt.Fprintln(stdout, "'No-findings:' justification naming the adversarial passes that came back empty.")
+		return 1
+	}
+	fmt.Fprintln(stdout, "review-integrity: OK — every adversarial axis has findings or a justified clean bill.")
+	return 0
+}
+
+// axisSections splits review.md into the `## Spec` / `## Code review` axis bodies,
+// keyed by the canonical axis label. A section runs from its `## ` heading to the
+// next `## ` (or end of file); deeper `### ` headings stay inside it.
+func axisSections(md string) map[string]string {
+	// Map every recognised heading spelling to its canonical axis label.
+	canon := map[string]string{}
+	for _, ax := range reviewAxes {
+		for _, h := range ax.headers {
+			canon[h] = ax.label
+		}
+	}
+
+	out := map[string]string{}
+	curLabel := ""
+	var cur strings.Builder
+	flush := func() {
+		if curLabel != "" {
+			out[curLabel] = cur.String()
+		}
+		cur.Reset()
+	}
+	for _, line := range strings.Split(md, "\n") {
+		if h, ok := cutH2(line); ok {
+			flush()
+			curLabel = canon[strings.ToLower(strings.TrimSpace(h))] // "" for a non-axis H2
+			continue
+		}
+		if curLabel != "" {
+			cur.WriteString(line)
+			cur.WriteByte('\n')
+		}
+	}
+	flush()
+	return out
+}
+
+// cutH2 returns the text of a level-2 heading ("## Foo" → "Foo", true) and false
+// for any other line. Deeper headings ("### ") are not level-2 and stay in the body.
+func cutH2(line string) (string, bool) {
+	t := strings.TrimRight(line, " \t")
+	if strings.HasPrefix(t, "## ") && !strings.HasPrefix(t, "### ") {
+		return strings.TrimSpace(t[len("## "):]), true
+	}
+	return "", false
+}

package/engine/internal/lib/reviewintegrity_test.go

@@ -0,0 +1,103 @@
+package lib
+
+import (
+	"bytes"
+	"os"
+	"path/filepath"
+	"testing"
+)
+
+// writeReview drops a review.md into <root>/work/<slug>/ and returns the root.
+func writeReview(t *testing.T, root, slug, body string) {
+	t.Helper()
+	dir := filepath.Join(root, "work", slug)
+	if err := os.MkdirAll(dir, 0o755); err != nil {
+		t.Fatalf("mkdir: %v", err)
+	}
+	if err := os.WriteFile(filepath.Join(dir, "review.md"), []byte(body), 0o644); err != nil {
+		t.Fatalf("write review.md: %v", err)
+	}
+}
+
+func runReviewIntegrity(t *testing.T, root, slug string) (int, string) {
+	t.Helper()
+	stdout, stderr := &bytes.Buffer{}, &bytes.Buffer{}
+	code := ReviewIntegrity(root, []string{slug}, stdout, stderr)
+	return code, stdout.String() + stderr.String()
+}
+
+func TestReviewIntegritySilentAxisFails(t *testing.T) {
+	root := t.TempDir()
+	// Code review axis carries a real finding; Spec axis is an all-zero rubber stamp.
+	writeReview(t, root, "feat", `# Review
+
+## Spec
+Everything matches the spec. Nothing to report.
+Critical 0 / Important 0 / Suggestion 0
+
+## Code review
+- **Important** — off-by-one in pagination at api/list.go:42.
+`)
+	code, out := runReviewIntegrity(t, root, "feat")
+	if code != 1 {
+		t.Fatalf("silent Spec axis should fail with 1, got %d\n%s", code, out)
+	}
+	if !contains(out, "Spec: SILENT") {
+		t.Fatalf("want Spec flagged silent, got:\n%s", out)
+	}
+	if !contains(out, "Code review: findings present") {
+		t.Fatalf("want Code review recognised as having findings, got:\n%s", out)
+	}
+}
+
+func TestReviewIntegrityJustifiedCleanPasses(t *testing.T) {
+	root := t.TempDir()
+	writeReview(t, root, "feat", `# Review
+
+## Spec
+No-findings: ran the missing/partial/incorrect passes against each AC; every
+criterion is implemented and no scope creep found.
+
+## Code review
+- **Nit** — rename tmp to buf at util.go:9.
+`)
+	code, out := runReviewIntegrity(t, root, "feat")
+	if code != 0 {
+		t.Fatalf("justified clean axis should pass, got %d\n%s", code, out)
+	}
+	if !contains(out, "Spec: clean — no-findings justification present") {
+		t.Fatalf("want Spec recognised as justified, got:\n%s", out)
+	}
+}
+
+func TestReviewIntegrityBothWithFindingsPasses(t *testing.T) {
+	root := t.TempDir()
+	writeReview(t, root, "feat", `## Spec
+- **Critical** — AC-003 unimplemented.
+
+## Code review
+- **Important** — missing error path.
+`)
+	if code, out := runReviewIntegrity(t, root, "feat"); code != 0 {
+		t.Fatalf("both-with-findings should pass, got %d\n%s", code, out)
+	}
+}
+
+func TestReviewIntegrityNoReviewPasses(t *testing.T) {
+	root := t.TempDir()
+	if err := os.MkdirAll(filepath.Join(root, "work", "feat"), 0o755); err != nil {
+		t.Fatal(err)
+	}
+	if code, out := runReviewIntegrity(t, root, "feat"); code != 0 {
+		t.Fatalf("absent review.md should pass, got %d\n%s", code, out)
+	}
+}
+
+func TestReviewIntegrityFreeformPasses(t *testing.T) {
+	root := t.TempDir()
+	// No per-axis headings — can't assess mechanically, must not false-positive.
+	writeReview(t, root, "feat", "# Review\n\nLooks fine overall, shipping.\n")
+	if code, out := runReviewIntegrity(t, root, "feat"); code != 0 {
+		t.Fatalf("freeform review should pass, got %d\n%s", code, out)
+	}
+}