devrites 5.11.0 → 5.12.0

package/engine/internal/acceptance/approve.go

@@ -0,0 +1,142 @@
+package acceptance
+
+import (
+	"path/filepath"
+	"strings"
+
+	"github.com/devrites/devrites/internal/markdowntext"
+)
+
+// ApprovedCommand is one vetted runtime command row: the exact command text
+// and its normalized working directory. A gate CHECK may execute only when
+// (command, cwd) matches a row of test-plan.md's Build-entry preflight table —
+// approval is review of an exact pair, never a shell-equivalence judgment.
+type ApprovedCommand struct {
+	Command string
+	Cwd     string // normalized; "" means the repository root
+}
+
+// ApprovedCommands extracts the approved command surface of test-plan.md: the
+// Command and Cwd cells of every row under `## Build-entry preflight`. No
+// other section approves execution — fenced examples, prose mentions, and
+// consumptive-action rows are not re-runnable oracles. A test plan without
+// the section approves nothing, so every runnable gate stays unapproved.
+func ApprovedCommands(testPlan []byte) []ApprovedCommand {
+	structural, err := markdowntext.Structural(testPlan)
+	if err != nil {
+		return nil
+	}
+	var approved []ApprovedCommand
+	inSection := false
+	commandCol, cwdCol := -1, -1
+	for _, line := range strings.Split(string(structural), "\n") {
+		trimmed := strings.TrimSpace(line)
+		if strings.HasPrefix(trimmed, "##") {
+			inSection = strings.EqualFold(trimmed, "## Build-entry preflight")
+			commandCol, cwdCol = -1, -1
+			continue
+		}
+		if !inSection {
+			continue
+		}
+		cells, ok := preflightCells(line)
+		if !ok {
+			continue
+		}
+		if commandCol < 0 {
+			commandCol = columnIndex(cells, "command")
+			cwdCol = columnIndex(cells, "cwd")
+			continue
+		}
+		if isDividerRow(cells) || commandCol >= len(cells) {
+			continue
+		}
+		command := unquoteCode(strings.TrimSpace(cells[commandCol]))
+		if command == "" {
+			continue
+		}
+		cwd := ""
+		if cwdCol >= 0 && cwdCol < len(cells) {
+			cwd = normalizeApprovedCwd(cells[cwdCol])
+		}
+		approved = append(approved, ApprovedCommand{Command: command, Cwd: cwd})
+	}
+	return approved
+}
+
+// Approved reports whether (check, cwd) is a vetted pair. Approval is
+// exact-text equality on the command after outer-whitespace normalization,
+// plus exact equality on the normalized working directory: a differently
+// spelled command or a different directory is a different oracle that needs
+// its own preflight row.
+func Approved(check, cwd string, approved []ApprovedCommand) bool {
+	check = normalizeCommand(check)
+	cwd = normalizeApprovedCwd(cwd)
+	for _, row := range approved {
+		if row.Command == check && row.Cwd == cwd {
+			return true
+		}
+	}
+	return false
+}
+
+// normalizeApprovedCwd maps the preflight table's root conventions ("",
+// "repository", "root", ".") onto the empty root marker and cleans relative
+// paths so `engine/` and `engine` name the same directory.
+func normalizeApprovedCwd(cwd string) string {
+	cwd = strings.TrimSpace(strings.Trim(cwd, "`"))
+	switch strings.ToLower(cwd) {
+	case "", ".", "./", "repository", "root", "repo", "n/a", "-":
+		return ""
+	}
+	return filepath.ToSlash(filepath.Clean(filepath.FromSlash(cwd)))
+}
+
+func columnIndex(cells []string, name string) int {
+	for i, cell := range cells {
+		if strings.EqualFold(strings.TrimSpace(cell), name) {
+			return i
+		}
+	}
+	return -1
+}
+
+// preflightCells splits a table row on unescaped pipes and unescapes `\|`, so
+// a command containing a shell pipe survives as one cell.
+func preflightCells(line string) ([]string, bool) {
+	trimmed := strings.TrimSpace(line)
+	if !strings.HasPrefix(trimmed, "|") || !strings.HasSuffix(trimmed, "|") {
+		return nil, false
+	}
+	body := trimmed[1 : len(trimmed)-1]
+	var cells []string
+	var cell strings.Builder
+	for i := 0; i < len(body); i++ {
+		if body[i] == '\\' && i+1 < len(body) && body[i+1] == '|' {
+			cell.WriteByte('|')
+			i++
+			continue
+		}
+		if body[i] == '|' {
+			cells = append(cells, strings.TrimSpace(cell.String()))
+			cell.Reset()
+			continue
+		}
+		cell.WriteByte(body[i])
+	}
+	cells = append(cells, strings.TrimSpace(cell.String()))
+	return cells, true
+}
+
+func isDividerRow(cells []string) bool {
+	for _, cell := range cells {
+		c := strings.TrimSpace(cell)
+		if c == "" {
+			continue
+		}
+		if strings.Trim(c, ":-") != "" {
+			return false
+		}
+	}
+	return true
+}

package/engine/internal/acceptance/cli.go

@@ -0,0 +1,426 @@
+package acceptance
+
+import (
+	"context"
+	"fmt"
+	"io"
+	"os"
+	"path/filepath"
+	"strconv"
+	"strings"
+	"time"
+
+	"github.com/devrites/devrites/internal/devritespaths"
+	"github.com/devrites/devrites/internal/state"
+)
+
+// Exit codes match the engine CLI conventions.
+const (
+	ExitOK      = 0
+	ExitUsage   = 2
+	ExitBlocked = 3
+)
+
+const gatesUsage = `usage: devrites-engine gates <subcommand> <slug>
+
+Subcommands:
+  scaffold <slug>            Create gates.md from spec.md AC ids (only when absent)
+  status <slug>              Reduce the ledger without executing; exit 3 unless ALL MET
+  run <slug> [--timeout N]   Execute unmet runnable gates and record evidence
+  reverify <slug> [--timeout N]  Re-execute every runnable gate, demoting stale passes
+  lint <slug> [--strict]     Audit oracle quality without executing
+  attest <slug> <id> <note>  Record human evidence on a manual gate
+  abandon <slug> <id> <why>  Record a terminal ABANDON handoff on a gate
+
+Exit codes: 0 ok, 2 usage, 3 blocked`
+
+// Run is the engine entrypoint for `gates …`; root is the resolved DevRites
+// root from the caller's single root resolution.
+func Run(root string, args []string, stdout, stderr io.Writer) int {
+	if len(args) == 0 {
+		fmt.Fprintln(stderr, gatesUsage)
+		return ExitUsage
+	}
+	sub, rest := args[0], args[1:]
+	switch sub {
+	case "-h", "-help", "--help", "help":
+		fmt.Fprintln(stdout, gatesUsage)
+		return ExitOK
+	case "scaffold":
+		return cmdScaffold(root, rest, stdout, stderr)
+	case "status":
+		return cmdStatus(root, rest, stdout, stderr)
+	case "run":
+		return cmdRun(root, rest, false, stdout, stderr)
+	case "reverify":
+		return cmdRun(root, rest, true, stdout, stderr)
+	case "lint":
+		return cmdLint(root, rest, stdout, stderr)
+	case "attest":
+		return cmdAttest(root, rest, stdout, stderr)
+	case "abandon":
+		return cmdAbandon(root, rest, stdout, stderr)
+	default:
+		fmt.Fprintf(stderr, "gates: unknown subcommand %q\n\n%s\n", sub, gatesUsage)
+		return ExitUsage
+	}
+}
+
+func featurePaths(root, slug string) (work, ledger, testPlan, project string, err error) {
+	work, err = devritespaths.ExistingFeatureDirChecked(root, slug)
+	if err != nil {
+		return "", "", "", "", fmt.Errorf("feature %q: %w", slug, err)
+	}
+	return work,
+		filepath.Join(work, GatesFile),
+		filepath.Join(work, "test-plan.md"),
+		filepath.Dir(root),
+		nil
+}
+
+// loadTestPlan returns the vetted command surface; an unreadable plan approves
+// nothing, so runnable gates stay unapproved rather than running unvetted code.
+func loadTestPlan(testPlanPath string) []ApprovedCommand {
+	// #nosec G304 -- workspace artifact path resolved from the operator root
+	raw, err := os.ReadFile(testPlanPath)
+	if err != nil {
+		return nil
+	}
+	return ApprovedCommands(raw)
+}
+
+func parseSlug(args []string) (string, bool) {
+	return args[0], len(args) == 1 && args[0] != "" && !strings.HasPrefix(args[0], "-")
+}
+
+// oneLine flattens an argument to a single ledger line so a pasted newline
+// cannot inject rows into the artifact.
+func oneLine(s string) string {
+	return strings.Join(strings.FieldsFunc(s, func(r rune) bool { return r == '\n' || r == '\r' }), " ")
+}
+
+func cmdScaffold(root string, args []string, stdout, stderr io.Writer) int {
+	slug, ok := parseSlug(args)
+	if !ok {
+		fmt.Fprintln(stderr, "usage: devrites-engine gates scaffold <slug>")
+		return ExitUsage
+	}
+	work, ledgerPath, _, _, err := featurePaths(root, slug)
+	if err != nil {
+		fmt.Fprintf(stderr, "gates scaffold: %v\n", err)
+		return ExitBlocked
+	}
+	var wrote bool
+	lockErr := state.WithFeatureLock(root, slug, func() error {
+		if _, statErr := os.Lstat(ledgerPath); statErr == nil {
+			return fmt.Errorf("%s already exists; scaffold never clobbers", GatesFile)
+		} else if !os.IsNotExist(statErr) {
+			return statErr
+		}
+		// #nosec G304 -- workspace artifact path resolved from the operator root
+		spec, _ := os.ReadFile(filepath.Join(work, "spec.md"))
+		if err := state.AtomicWrite(ledgerPath, []byte(ScaffoldLedger(slug, spec)), 0o644); err != nil {
+			return err
+		}
+		wrote = true
+		return nil
+	})
+	if lockErr != nil {
+		fmt.Fprintf(stderr, "gates scaffold: %v\n", lockErr)
+		return ExitBlocked
+	}
+	if wrote {
+		fmt.Fprintf(stdout, "created: %s\n", ledgerPath)
+	}
+	return ExitOK
+}
+
+func cmdStatus(root string, args []string, stdout, stderr io.Writer) int {
+	slug, ok := parseSlug(args)
+	if !ok {
+		fmt.Fprintln(stderr, "usage: devrites-engine gates status <slug>")
+		return ExitUsage
+	}
+	_, ledgerPath, testPlanPath, _, err := featurePaths(root, slug)
+	if err != nil {
+		fmt.Fprintf(stderr, "gates status: %v\n", err)
+		return ExitBlocked
+	}
+	return reportStatus(slug, ledgerPath, testPlanPath, stdout, stderr)
+}
+
+// reportStatus prints the stable greppable reduction. It returns ExitOK only
+// for a parse-clean ledger with every gate met and none abandoned.
+func reportStatus(slug, ledgerPath, testPlanPath string, stdout, stderr io.Writer) int {
+	text, err := ReadLedgerFile(ledgerPath)
+	if err != nil {
+		fmt.Fprintf(stderr, "gates status: %v\n", err)
+		return ExitBlocked
+	}
+	doc := ParseLedger(text)
+	approved := loadTestPlan(testPlanPath)
+	fmt.Fprintf(stdout, "feature: %s\n", slug)
+	fmt.Fprintf(stdout, "ledger: %s\n", GatesFile)
+	for _, parseErr := range doc.Errors {
+		fmt.Fprintf(stdout, "error: %s\n", parseErr)
+	}
+	reduction := doc.Reduce(approved)
+	fmt.Fprintf(stdout, "gates: %d\nmet: %d\nunmet: %d\nstale: %d\nabandoned: %d\nunapproved: %d\n",
+		reduction.Total, reduction.Met, reduction.Unmet, reduction.Stale, reduction.Abandoned, reduction.Unapproved)
+	for _, line := range reductionLines(reduction) {
+		fmt.Fprintln(stdout, line)
+	}
+	switch {
+	case len(doc.Errors) > 0:
+		fmt.Fprintln(stdout, "result: malformed")
+		return ExitBlocked
+	case reduction.HandoffRequired():
+		fmt.Fprintln(stdout, "result: handoff")
+		return ExitBlocked
+	case !reduction.AllMet():
+		fmt.Fprintln(stdout, "result: not-met")
+		return ExitBlocked
+	default:
+		fmt.Fprintln(stdout, "result: all-met")
+		return ExitOK
+	}
+}
+
+// reductionLines names the specific unmet/stale/unapproved/abandoned ids so a
+// report surfaces the exact compliance gap instead of a bare count.
+func reductionLines(r Reduction) []string {
+	var lines []string
+	for _, id := range r.UnmetIDs {
+		lines = append(lines, "unmet-id: "+id)
+	}
+	for _, id := range r.StaleIDs {
+		lines = append(lines, "stale-id: "+id)
+	}
+	for _, id := range r.UnapprIDs {
+		lines = append(lines, "unapproved-id: "+id)
+	}
+	for _, id := range r.Handoffs {
+		lines = append(lines, "handoff-id: "+id)
+	}
+	return lines
+}
+
+func cmdRun(root string, args []string, reverify bool, stdout, stderr io.Writer) int {
+	verb := "run"
+	if reverify {
+		verb = "reverify"
+	}
+	var slug string
+	timeout := DefaultTimeout
+	positional := 0
+	for i := 0; i < len(args); i++ {
+		if args[i] == "--timeout" {
+			if i+1 >= len(args) {
+				fmt.Fprintf(stderr, "gates %s: --timeout requires seconds\n", verb)
+				return ExitUsage
+			}
+			i++
+			n, err := strconv.Atoi(args[i])
+			if err != nil || n <= 0 {
+				fmt.Fprintf(stderr, "gates %s: --timeout must be positive seconds, got %q\n", verb, args[i])
+				return ExitUsage
+			}
+			timeout = time.Duration(n) * time.Second
+			continue
+		}
+		if strings.HasPrefix(args[i], "-") || positional > 0 {
+			fmt.Fprintf(stderr, "usage: devrites-engine gates %s <slug> [--timeout N]\n", verb)
+			return ExitUsage
+		}
+		slug = args[i]
+		positional++
+	}
+	if slug == "" {
+		fmt.Fprintf(stderr, "usage: devrites-engine gates %s <slug> [--timeout N]\n", verb)
+		return ExitUsage
+	}
+	_, ledgerPath, testPlanPath, project, err := featurePaths(root, slug)
+	if err != nil {
+		fmt.Fprintf(stderr, "gates %s: %v\n", verb, err)
+		return ExitBlocked
+	}
+
+	lockErr := state.WithFeatureLock(root, slug, func() error {
+		text, err := ReadLedgerFile(ledgerPath)
+		if err != nil {
+			return err
+		}
+		doc := ParseLedger(text)
+		if len(doc.Errors) > 0 {
+			for _, parseErr := range doc.Errors {
+				fmt.Fprintf(stdout, "error: %s\n", parseErr)
+			}
+			return nil
+		}
+		approved := loadTestPlan(testPlanPath)
+		for _, result := range RunGates(context.Background(), project, ledgerPath, doc, approved, reverify, timeout) {
+			switch {
+			case !result.Ran:
+				fmt.Fprintf(stdout, "gate %s: skipped (%s)\n", result.ID, result.Detail)
+			case result.Passed && !result.Discarded && result.WriteErr == nil:
+				fmt.Fprintf(stdout, "gate %s: pass\n", result.ID)
+			default:
+				fmt.Fprintf(stdout, "gate %s: fail (%s)\n", result.ID, result.Detail)
+			}
+		}
+		return nil
+	})
+	if lockErr != nil {
+		fmt.Fprintf(stderr, "gates %s: %v\n", verb, lockErr)
+		return ExitBlocked
+	}
+	fmt.Fprintln(stdout, "---")
+	return reportStatus(slug, ledgerPath, testPlanPath, stdout, stderr)
+}
+
+func cmdLint(root string, args []string, stdout, stderr io.Writer) int {
+	strict := false
+	var slug string
+	for _, arg := range args {
+		if arg == "--strict" {
+			strict = true
+			continue
+		}
+		if strings.HasPrefix(arg, "-") || slug != "" {
+			fmt.Fprintln(stderr, "usage: devrites-engine gates lint <slug> [--strict]")
+			return ExitUsage
+		}
+		slug = arg
+	}
+	if slug == "" {
+		fmt.Fprintln(stderr, "usage: devrites-engine gates lint <slug> [--strict]")
+		return ExitUsage
+	}
+	_, ledgerPath, testPlanPath, _, err := featurePaths(root, slug)
+	if err != nil {
+		fmt.Fprintf(stderr, "gates lint: %v\n", err)
+		return ExitBlocked
+	}
+	text, err := ReadLedgerFile(ledgerPath)
+	if err != nil {
+		fmt.Fprintf(stderr, "gates lint: %v\n", err)
+		return ExitBlocked
+	}
+	doc := ParseLedger(text)
+	findings := LintLedger(doc, loadTestPlan(testPlanPath))
+	for _, finding := range findings {
+		gate := finding.Gate
+		if gate == "" {
+			gate = "ledger"
+		}
+		fmt.Fprintf(stdout, "%s: %s: %s: %s\n", finding.Level, gate, finding.Rule, finding.Message)
+	}
+	errors, warnings := LintCounts(findings)
+	fmt.Fprintf(stdout, "lint: %d error(s), %d warning(s)\n", errors, warnings)
+	if errors > 0 || (strict && warnings > 0) {
+		fmt.Fprintln(stdout, "LINT FAIL")
+		return ExitBlocked
+	}
+	fmt.Fprintln(stdout, "LINT OK")
+	return ExitOK
+}
+
+func cmdAttest(root string, args []string, stdout, stderr io.Writer) int {
+	if len(args) < 3 {
+		fmt.Fprintln(stderr, "usage: devrites-engine gates attest <slug> <gate-id> <evidence note>")
+		return ExitUsage
+	}
+	slug, gateID := args[0], args[1]
+	note := oneLine(strings.Join(args[2:], " "))
+	if note == "" {
+		fmt.Fprintln(stderr, "gates attest: evidence note must be non-blank")
+		return ExitUsage
+	}
+	_, ledgerPath, _, _, err := featurePaths(root, slug)
+	if err != nil {
+		fmt.Fprintf(stderr, "gates attest: %v\n", err)
+		return ExitBlocked
+	}
+	lockErr := state.WithFeatureLock(root, slug, func() error {
+		text, err := ReadLedgerFile(ledgerPath)
+		if err != nil {
+			return err
+		}
+		doc := ParseLedger(text)
+		var gate *Gate
+		for _, candidate := range doc.Gates {
+			if candidate.ID == gateID {
+				gate = candidate
+			}
+		}
+		if gate == nil {
+			return fmt.Errorf("unknown gate id %q", gateID)
+		}
+		if _, abandoned := doc.Abandoned[gateID]; abandoned {
+			return fmt.Errorf("gate %s is abandoned; a handoff cannot take evidence", gateID)
+		}
+		if gate.Check != "" {
+			return fmt.Errorf("gate %s is runnable; evidence comes from `gates run`, not attestation", gateID)
+		}
+		return writeResult(ledgerPath, gate, note, true)
+	})
+	if lockErr != nil {
+		fmt.Fprintf(stderr, "gates attest: %v\n", lockErr)
+		return ExitBlocked
+	}
+	fmt.Fprintf(stdout, "attested: %s\n", gateID)
+	return ExitOK
+}
+
+func cmdAbandon(root string, args []string, stdout, stderr io.Writer) int {
+	if len(args) < 3 {
+		fmt.Fprintln(stderr, "usage: devrites-engine gates abandon <slug> <gate-id> <reason>")
+		return ExitUsage
+	}
+	slug, gateID := args[0], args[1]
+	reason := oneLine(strings.Join(args[2:], " "))
+	if reason == "" {
+		fmt.Fprintln(stderr, "gates abandon: reason must be non-blank")
+		return ExitUsage
+	}
+	_, ledgerPath, _, _, err := featurePaths(root, slug)
+	if err != nil {
+		fmt.Fprintf(stderr, "gates abandon: %v\n", err)
+		return ExitBlocked
+	}
+	lockErr := state.WithFeatureLock(root, slug, func() error {
+		text, err := ReadLedgerFile(ledgerPath)
+		if err != nil {
+			return err
+		}
+		doc := ParseLedger(text)
+		found := false
+		for _, gate := range doc.Gates {
+			if gate.ID == gateID {
+				found = true
+			}
+		}
+		if !found {
+			return fmt.Errorf("unknown gate id %q", gateID)
+		}
+		if _, already := doc.Abandoned[gateID]; already {
+			return fmt.Errorf("gate %s is already abandoned", gateID)
+		}
+		line := "ABANDON: " + gateID + " " + reason
+		switch {
+		case strings.HasSuffix(text, "\r\n"):
+			text += line + "\r\n"
+		case strings.HasSuffix(text, "\n"):
+			text += line + "\n"
+		default:
+			text += "\n" + line + "\n"
+		}
+		return state.AtomicWrite(ledgerPath, []byte(text), 0o644)
+	})
+	if lockErr != nil {
+		fmt.Fprintf(stderr, "gates abandon: %v\n", lockErr)
+		return ExitBlocked
+	}
+	fmt.Fprintf(stdout, "abandoned: %s\n", gateID)
+	return ExitOK
+}

package/engine/internal/acceptance/evidence.go

@@ -0,0 +1,139 @@
+package acceptance
+
+import (
+	"crypto/sha256"
+	"encoding/hex"
+	"fmt"
+	"regexp"
+	"strings"
+)
+
+// Evidence state vocabulary. A runnable gate is met only when its recorded
+// evidence carries the current definition digest; every other runnable state
+// is unmet and schedules the gate for execution.
+const (
+	StateMet        = "met"
+	StateUnmet      = "unmet"
+	StateStaleUnmet = "stale-unmet"
+	StateAbandoned  = "abandoned"
+	StateUnapproved = "unapproved" // CHECK is not a vetted test-plan command
+)
+
+// EvidenceMarker is the versioned automatic-evidence prefix written by the
+// runner. Ordinary prose evidence on a runnable gate never satisfies it; a
+// manual gate keeps human attestation.
+const EvidenceMarker = "automatic-evidence=v1"
+
+var automaticEvidenceRE = regexp.MustCompile(`^automatic-evidence=v1; def=([0-9a-f]{64}); exit=0; expect=matched; output-sha256=([0-9a-f]{64}); output-bytes=([0-9]+); at=(\S+)$`)
+
+// DefinitionDigest is the environment-independent SHA-256 binding of the
+// parsed CHECK, EXPECT, and raw CWD fields. Editing any bound input renders
+// previously recorded evidence stale. The digest is unkeyed drift detection,
+// not tamper proof: a ledger editor can write a syntactically valid line.
+func DefinitionDigest(gate *Gate) string {
+	sum := sha256.Sum256([]byte("v1\x00" + gate.Check + "\x00" + gate.Expect + "\x00" + gate.Cwd))
+	return hex.EncodeToString(sum[:])
+}
+
+// FormatEvidence renders the canonical automatic evidence line payload.
+func FormatEvidence(gate *Gate, outputDigest string, outputBytes int, at string) string {
+	return fmt.Sprintf("%s; def=%s; exit=0; expect=matched; output-sha256=%s; output-bytes=%d; at=%s",
+		EvidenceMarker, DefinitionDigest(gate), outputDigest, outputBytes, at)
+}
+
+// OutputDigest is the recorded fingerprint of the canonical successful output
+// string. Raw output is never persisted.
+func OutputDigest(output string) string {
+	sum := sha256.Sum256([]byte(output))
+	return hex.EncodeToString(sum[:])
+}
+
+// GateState resolves a gate's state from the parsed ledger alone. No command
+// executes: status is a pure function of definition binding plus checkbox.
+func GateState(gate *Gate, doc *Document) string {
+	if _, ok := doc.Abandoned[gate.ID]; ok {
+		return StateAbandoned
+	}
+	if gate.Check == "" {
+		// Manual gate: met when checked with any non-empty human evidence.
+		evidence := strings.TrimSpace(gate.Evidence)
+		if gate.Checked && evidence != "" && evidence != "pending" {
+			return StateMet
+		}
+		return StateUnmet
+	}
+	if !gate.Checked {
+		return StateUnmet
+	}
+	evidence := strings.TrimSpace(gate.Evidence)
+	match := automaticEvidenceRE.FindStringSubmatch(evidence)
+	if match == nil || match[1] != DefinitionDigest(gate) {
+		return StateStaleUnmet
+	}
+	return StateMet
+}
+
+// Reduction is the non-executing ledger verdict shared by `gates status` and
+// the seal gate. Unmet counts every gate that is neither met nor abandoned;
+// Stale and Unapproved are diagnostic subsets of it.
+type Reduction struct {
+	Total      int
+	Met        int
+	Unmet      int
+	Stale      int
+	Abandoned  int
+	Unapproved int
+	Handoffs   []string // abandoned gate ids
+	UnmetIDs   []string // all non-met, non-abandoned ids
+	StaleIDs   []string
+	UnapprIDs  []string
+}
+
+// AllMet reports whether every gate is met and none is abandoned.
+func (r Reduction) AllMet() bool {
+	return r.Total > 0 && r.Met == r.Total && r.Abandoned == 0
+}
+
+// HandoffRequired reports whether at least one gate was visibly abandoned: a
+// terminal non-successful outcome that can never read as completion.
+func (r Reduction) HandoffRequired() bool {
+	return r.Abandoned > 0
+}
+
+// Reduce computes the ledger reduction. approved is the vetted (command, cwd)
+// surface from test-plan.md; a runnable gate whose CHECK is absent also
+// records an unapproved diagnostic but always counts as unmet.
+func (d *Document) Reduce(approved []ApprovedCommand) Reduction {
+	r := Reduction{Total: len(d.Gates)}
+	for _, gate := range d.Gates {
+		switch GateState(gate, d) {
+		case StateMet:
+			r.Met++
+		case StateAbandoned:
+			r.Abandoned++
+			r.Handoffs = append(r.Handoffs, gate.ID)
+		default:
+			r.Unmet++
+			r.UnmetIDs = append(r.UnmetIDs, gate.ID)
+			if gate.Check == "" {
+				continue
+			}
+			if GateState(gate, d) == StateStaleUnmet {
+				r.Stale++
+				r.StaleIDs = append(r.StaleIDs, gate.ID)
+			}
+			if approved != nil && !Approved(gate.Check, gate.Cwd, approved) {
+				r.Unapproved++
+				r.UnapprIDs = append(r.UnapprIDs, gate.ID)
+			}
+		}
+	}
+	return r
+}
+
+// normalizeCommand trims outer whitespace for the approval binding. Approval
+// is exact-text equality, not shell equivalence: a semantically identical but
+// differently spelled command is a different oracle requiring its own vet row.
+func normalizeCommand(command string) string {
+	return strings.TrimSpace(command)
+}