devrites 2.6.1 → 3.0.1

package/engine/internal/gate/gate.go

@@ -0,0 +1,243 @@
+// Package gate implements DevRites' deterministic completeness gates.
+//
+// Enforcement is phase-relative, gate-scoped, and transition-fired: a gate
+// checks only the sections required to make its transition, and only when it is
+// run — never on every tool call. A block is a HITL pause (a structured
+// "missing X" the human resolves and retries), never a crash. Judgment gates
+// stay advisory; these deterministic gates are the ones allowed to block.
+package gate
+
+import (
+	"fmt"
+	"os"
+	"path/filepath"
+	"strings"
+
+	"github.com/devrites/devrites/internal/devritespaths"
+	"github.com/devrites/devrites/internal/orient"
+	"github.com/devrites/devrites/internal/state"
+)
+
+// Kind names a gate. Its string form is also the CLI subcommand.
+type Kind string
+
+const (
+	// Readiness checks the sections required to LEAVE the feature's current
+	// phase — the gate fired when advancing to the next phase.
+	Readiness Kind = "readiness"
+	// Seal checks the full seal-phase requirement set regardless of the
+	// feature's current phase — the final completeness gate before shipping.
+	Seal Kind = "seal"
+)
+
+// Result is a gate outcome. Blocked is true iff a required section is missing;
+// Missing lists them in canonical order for an actionable message.
+type Result struct {
+	Kind    Kind
+	Slug    string
+	Phase   state.Phase
+	Target  state.Phase // the phase whose requirements were checked
+	Missing []state.Section
+	Blocked bool
+}
+
+// Check runs a gate against feature <slug> under root, reading the files
+// directly (the files are always the source of truth, so a gate never trusts a
+// possibly-stale cache). It returns an error only for a genuinely broken request
+// (unknown slug, unreadable state) — a legitimately incomplete feature is a
+// Result with Blocked set, not an error.
+func Check(kind Kind, root, slug string) (*Result, error) {
+	f, err := state.LoadFeature(root, slug)
+	if err != nil {
+		return nil, fmt.Errorf("gate %s: %w", kind, err)
+	}
+	target := f.Phase
+	if kind == Seal {
+		target = state.PhaseSeal
+	}
+	missing := state.MissingFor(f, target)
+	return &Result{
+		Kind:    kind,
+		Slug:    slug,
+		Phase:   f.Phase,
+		Target:  target,
+		Missing: missing,
+		Blocked: len(missing) > 0,
+	}, nil
+}
+
+// Render produces the deterministic, greppable gate output (with a trailing
+// newline). A block names exactly the missing sections and the resolve step, so
+// a human — or an AFK agent — knows precisely what to fix.
+func (r *Result) Render() string {
+	var b strings.Builder
+	fmt.Fprintf(&b, "gate: %s\n", r.Kind)
+	fmt.Fprintf(&b, "feature: %s\n", r.Slug)
+	fmt.Fprintf(&b, "phase: %s\n", r.Phase)
+	if !r.Blocked {
+		b.WriteString("result: pass\n")
+		return b.String()
+	}
+	names := sectionNames(r.Missing)
+	if r.Kind == Seal {
+		fmt.Fprintf(&b, "result: blocked (missing to seal: %s)\n", strings.Join(names, ", "))
+	} else {
+		fmt.Fprintf(&b, "result: blocked (missing to leave %q: %s)\n", r.Phase, strings.Join(names, ", "))
+	}
+	fmt.Fprintf(&b, "next: add real content to %s, then re-run: devrites-engine %s %s\n",
+		strings.Join(fileNames(r.Missing), ", "), r.Kind, r.Slug)
+	return b.String()
+}
+
+// StopGate evaluates the stop-hook rest-point invariant for the active feature:
+// a feature that CLAIMS completion (it has advanced to the seal or ship phase)
+// must not have an empty proof section. This is a rest-point check, NOT
+// whole-feature completeness — normal in-progress incompleteness never trips it,
+// so a mid-build turn is never blocked.
+//
+// It returns a zero StopResult (Blocked false) — silent, no block — when there
+// is no active feature or the workspace can't be read, keeping the stop hook
+// fail-open.
+func StopGate(root string) (StopResult, error) {
+	slug, err := orient.ActiveSlug(root)
+	if err != nil || slug == "" {
+		return StopResult{}, nil
+	}
+	f, err := state.LoadFeature(root, slug)
+	if err != nil {
+		return StopResult{}, nil // fail-open: a broken workspace never wedges Stop
+	}
+	// Fail-on-red: the redwatch hook marks a known-red suite by writing .red. A turn
+	// must not rest while it is set — evidence over confidence. This is a rest-point
+	// invariant (a concrete, provable inconsistency), not whole-feature completeness.
+	featureDir := devritespaths.FeatureDir(root, slug)
+	if _, statErr := os.Stat(filepath.Join(featureDir, ".red")); statErr == nil {
+		return StopResult{
+			Slug:    slug,
+			Blocked: true,
+			Reason: fmt.Sprintf(
+				"feature %q has tests/build RED (.red is set) — fix to green, or record the failure and next step, before stopping",
+				slug),
+		}, nil
+	}
+	if gates, blocked := unsurfacedHumanGates(featureDir); blocked {
+		return StopResult{
+			Slug:    slug,
+			Blocked: true,
+			Reason: fmt.Sprintf(
+				"feature %q has open %s human question(s) in questions.md but state.md is not awaiting_human — surface the gate before stopping",
+				slug, strings.Join(gates, "/")),
+		}, nil
+	}
+	claimsDone := f.Phase == state.PhaseSeal || f.Phase == state.PhaseShip
+	if claimsDone && !f.Present[state.SectionProof] {
+		return StopResult{
+			Slug:    slug,
+			Blocked: true,
+			Reason: fmt.Sprintf(
+				"feature %q is at phase %q but proof.md is empty — record acceptance evidence, or move the phase back, before stopping",
+				slug, f.Phase),
+		}, nil
+	}
+	return StopResult{Slug: slug}, nil
+}
+
+const gateSpaceChars = " \t\n\v\f\r"
+
+func unsurfacedHumanGates(featureDir string) ([]string, bool) {
+	qdata, err := os.ReadFile(filepath.Join(featureDir, "questions.md"))
+	if err != nil {
+		return nil, false
+	}
+	gates := openBlockingQuestionGates(qdata)
+	if len(gates) == 0 {
+		return nil, false
+	}
+	sdata, err := os.ReadFile(filepath.Join(featureDir, "state.md"))
+	if err == nil && stateAwaitingHuman(sdata) {
+		return nil, false
+	}
+	return gates, true
+}
+
+func openBlockingQuestionGates(data []byte) []string {
+	lines := splitLinesNoTrailing(data)
+	seen := map[string]bool{}
+	var gates []string
+	inQ := false
+	status, gate := "", ""
+	finalize := func() {
+		if inQ && status == "open" && (gate == "blocking" || gate == "validating") && !seen[gate] {
+			seen[gate] = true
+			gates = append(gates, gate)
+		}
+	}
+	for _, line := range lines {
+		switch {
+		case strings.HasPrefix(line, "## q-"):
+			finalize()
+			inQ, status, gate = true, "", ""
+		case inQ && strings.HasPrefix(line, "status:"):
+			status = strings.TrimLeft(strings.TrimPrefix(line, "status:"), gateSpaceChars)
+		case inQ && strings.HasPrefix(line, "gate:"):
+			gate = strings.TrimLeft(strings.TrimPrefix(line, "gate:"), gateSpaceChars)
+		case inQ && isHeadingLine(line):
+			finalize()
+			inQ = false
+		}
+	}
+	finalize()
+	return gates
+}
+
+func stateAwaitingHuman(data []byte) bool {
+	for _, line := range splitLinesNoTrailing(data) {
+		if strings.HasPrefix(line, "- Status:") {
+			status := strings.TrimLeft(strings.TrimPrefix(line, "- Status:"), gateSpaceChars)
+			return status == "awaiting_human"
+		}
+	}
+	return false
+}
+
+func isHeadingLine(line string) bool {
+	if !strings.HasPrefix(line, "##") {
+		return false
+	}
+	rest := line[2:]
+	return rest != "" && strings.ContainsRune(gateSpaceChars, rune(rest[0]))
+}
+
+func splitLinesNoTrailing(data []byte) []string {
+	s := string(data)
+	s = strings.TrimSuffix(s, "\n")
+	if s == "" {
+		return nil
+	}
+	return strings.Split(s, "\n")
+}
+
+// StopResult is a stop-gate evaluation. Slug names the active feature (empty when
+// none); Blocked is true iff the rest-point invariant is violated; Reason is the
+// actionable explanation when Blocked.
+type StopResult struct {
+	Slug    string
+	Reason  string
+	Blocked bool
+}
+
+func sectionNames(ss []state.Section) []string {
+	out := make([]string, len(ss))
+	for i, s := range ss {
+		out[i] = string(s)
+	}
+	return out
+}
+
+func fileNames(ss []state.Section) []string {
+	out := make([]string, len(ss))
+	for i, s := range ss {
+		out[i] = string(s) + ".md"
+	}
+	return out
+}

package/engine/internal/gate/gate_test.go

@@ -0,0 +1,145 @@
+package gate
+
+import (
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+
+	"github.com/devrites/devrites/internal/testutil"
+)
+
+func TestCheckAndRenderReadiness(t *testing.T) {
+	root := t.TempDir()
+	writeFeature(t, root, "alpha", map[string]string{
+		"feature.md": "---\nphase: build\nschemaVersion: 1\n---\n",
+		"spec.md":    "real spec\n",
+		"plan.md":    "real plan\n",
+	})
+
+	res, err := Check(Readiness, root, "alpha")
+	if err != nil {
+		t.Fatal(err)
+	}
+	if !res.Blocked {
+		t.Fatalf("Check blocked=false, want true")
+	}
+	got := res.Render()
+	for _, want := range []string{
+		"gate: readiness",
+		"feature: alpha",
+		"phase: build",
+		`result: blocked (missing to leave "build": decisions, tasks)`,
+		"next: add real content to decisions.md, tasks.md, then re-run: devrites-engine readiness alpha",
+	} {
+		if !strings.Contains(got, want) {
+			t.Fatalf("Render() missing %q in:\n%s", want, got)
+		}
+	}
+}
+
+func TestStopGateRestPointInvariants(t *testing.T) {
+	for _, tc := range []struct {
+		name          string
+		files         map[string]string
+		wantBlocked   bool
+		wantReasonSub string
+	}{
+		{
+			name: "red blocks",
+			files: map[string]string{
+				"feature.md": "---\nphase: build\nschemaVersion: 1\n---\n",
+				"state.md":   "- Phase: build\n",
+				".red":       "go test ./...\n",
+			},
+			wantBlocked:   true,
+			wantReasonSub: "tests/build RED",
+		},
+		{
+			name: "unsurfaced human gate blocks",
+			files: map[string]string{
+				"feature.md":   "---\nphase: build\nschemaVersion: 1\n---\n",
+				"state.md":     "- Phase: build\n- Status: running\n",
+				"questions.md": "## q-1\nstatus: open\ngate: blocking\n\n## q-2\nstatus: open\ngate: validating\n",
+			},
+			wantBlocked:   true,
+			wantReasonSub: "open blocking/validating human question",
+		},
+		{
+			name: "awaiting human allows surfaced gate",
+			files: map[string]string{
+				"feature.md":   "---\nphase: build\nschemaVersion: 1\n---\n",
+				"state.md":     "- Phase: build\n- Status: awaiting_human\n",
+				"questions.md": "## q-1\nstatus: open\ngate: blocking\n",
+			},
+		},
+		{
+			name: "seal without proof blocks",
+			files: map[string]string{
+				"feature.md": "---\nphase: seal\nschemaVersion: 1\n---\n",
+				"state.md":   "- Phase: seal\n",
+			},
+			wantBlocked:   true,
+			wantReasonSub: "proof.md is empty",
+		},
+	} {
+		t.Run(tc.name, func(t *testing.T) {
+			root := t.TempDir()
+			testutil.WriteFile(t, filepath.Join(root, "ACTIVE"), "alpha\n")
+			writeFeature(t, root, "alpha", tc.files)
+
+			got, err := StopGate(root)
+			if err != nil {
+				t.Fatal(err)
+			}
+			if got.Slug != "alpha" {
+				t.Fatalf("StopGate slug=%q, want alpha", got.Slug)
+			}
+			if got.Blocked != tc.wantBlocked {
+				t.Fatalf("StopGate blocked=%v, want %v; reason=%q", got.Blocked, tc.wantBlocked, got.Reason)
+			}
+			if tc.wantReasonSub != "" && !strings.Contains(got.Reason, tc.wantReasonSub) {
+				t.Fatalf("StopGate reason=%q, want substring %q", got.Reason, tc.wantReasonSub)
+			}
+		})
+	}
+}
+
+func TestStopGateUsesWorkspaceOverride(t *testing.T) {
+	project := t.TempDir()
+	root := filepath.Join(project, ".devrites")
+	if err := os.MkdirAll(root, 0o755); err != nil {
+		t.Fatal(err)
+	}
+	override := filepath.Join(project, "custom", "alpha")
+	t.Setenv("DEVRITES_WORKSPACE", override)
+	testutil.WriteFile(t, filepath.Join(override, "feature.md"), "---\nphase: build\nschemaVersion: 1\n---\n")
+	testutil.WriteFile(t, filepath.Join(override, "state.md"), "- Phase: build\n")
+	testutil.WriteFile(t, filepath.Join(override, ".red"), "go test ./...\n")
+
+	got, err := StopGate(root)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if got.Slug != "alpha" {
+		t.Fatalf("StopGate slug=%q, want alpha", got.Slug)
+	}
+	if !got.Blocked || !strings.Contains(got.Reason, "tests/build RED") {
+		t.Fatalf("StopGate did not block on override .red: blocked=%v reason=%q", got.Blocked, got.Reason)
+	}
+}
+
+func TestOpenBlockingQuestionGates(t *testing.T) {
+	got := openBlockingQuestionGates([]byte("## q-1\nstatus: open\ngate: blocking\n\n## Not a question\n\n## q-2\nstatus: open\ngate: validating\n\n## q-3\nstatus: resolved\ngate: blocking\n\n## q-4\nstatus: open\ngate: blocking\n"))
+	want := []string{"blocking", "validating"}
+	if strings.Join(got, ",") != strings.Join(want, ",") {
+		t.Fatalf("openBlockingQuestionGates=%v, want %v", got, want)
+	}
+}
+
+func writeFeature(t *testing.T, root, slug string, files map[string]string) {
+	t.Helper()
+	for name, content := range files {
+		testutil.WriteFile(t, filepath.Join(root, "features", slug, name), content)
+	}
+}

package/engine/internal/harness/compliance.go

@@ -0,0 +1,102 @@
+package harness
+
+import (
+	"fmt"
+	"strings"
+)
+
+// The harness adapter-compliance matrix.
+//
+// DevRites drives more than one agent runtime from one engine, but the runtimes
+// do not expose identical enforcement surfaces. Rather than pretend parity, this
+// frozen matrix states, per surface, whether each supported harness enforces it
+// natively, through an adapter, or only by instruction the model may ignore. It
+// is the single source of truth; `devrites-engine harness-matrix` renders it and
+// CI drift-checks the rendered copy in docs/, so the honest picture cannot rot.
+
+// Tier is how strongly a harness backs a given surface, from strongest to
+// weakest.
+type Tier int
+
+const (
+	// Native — the harness exposes and delivers the surface directly. Whether a
+	// delivered policy blocks is stated separately in the surface note.
+	Native Tier = iota
+	// Adapter — supported, but through a translation shim (a different verb,
+	// a mirrored file tree) rather than the harness's first-class path.
+	Adapter
+	// Instruction — no runtime enforcement surface; the behaviour rides on a
+	// directive the model is asked to follow and may under-fire.
+	Instruction
+	// Conditional — natively supported, but gated on an operator precondition
+	// that silently disables it when unmet.
+	Conditional
+)
+
+func (t Tier) String() string {
+	switch t {
+	case Native:
+		return "Native"
+	case Adapter:
+		return "Adapter-backed"
+	case Instruction:
+		return "Instruction-backed"
+	case Conditional:
+		return "Conditional"
+	default:
+		return "unknown"
+	}
+}
+
+// Surface is one enforcement surface and how each harness backs it.
+type Surface struct {
+	Name        string
+	Claude      Tier
+	Codex       Tier
+	PhaseImpact string
+	Fallback    string
+	DoctorCheck string
+	Confidence  string
+	Note        string
+}
+
+// complianceMatrix is grounded in the shipped wiring: pack/.claude/settings.json
+// for Claude, generated host artifacts + AGENTS.md merge for Codex.
+// Change a cell only when that wiring changes.
+var complianceMatrix = []Surface{
+	{"SessionStart orientation", Native, Native, "all phases", "manual preamble/snapshot", "yes", "high", "Both wire the orient hook; identical additionalContext envelope."},
+	{"PreToolUse policy (allow, a1-guard, reviewer-readonly, wright-scope)", Conditional, Conditional, "build/review safety", "observe-only findings + human review", "yes", "high", "Both deliver the event, but these policies are non-blocking by default; DEVRITES_HOOK_PROFILE=strict enables every guard, or each guard can be enabled through its documented specific variable."},
+	{"PostToolUse sentinel (redwatch)", Native, Native, "prove/build rest points", "manual red/green check", "yes", "high", "Fail-on-red sentinel wired on both."},
+	{"Stop gate", Conditional, Conditional, "all rest points", "observe-only finding + manual host-specific rite-status", "yes", "high", "Both deliver Stop; stop-gate blocks with DEVRITES_STOP_GATE=enforce or DEVRITES_HOOK_PROFILE=strict."},
+	{"SubagentStart discipline injection", Native, Native, "review/build fan-out", "agent file preamble", "yes", "high", "subagent-orient wired on both."},
+	{"Skill invocation", Native, Adapter, "all public rites", "explicit file read", "yes", "high", "Claude: native /rite. Codex: $rite over the mirrored .agents/skills tree."},
+	{"Reviewer subagent dispatch", Native, Instruction, "review/seal confidence", "labelled inline pass", "partial", "medium", "Codex under-fires embedded spawns (openai/codex#23496); falls back to .codex/agents + a labelled inline pass."},
+	{"Standards step-0 load", Native, Instruction, "all phases", "explicit standards read", "partial", "medium", "Claude: skill Reads core.md. Codex: an AGENTS.md directive to read it."},
+	{"Project activation", Native, Conditional, "Codex-only startup", "inspect hooks/config, decide trust, then rerun doctor", "yes", "medium", "Codex silently skips every .codex/ layer in an untrusted project; trust remains an operator decision after inspection."},
+}
+
+// Matrix markers delimit the generated block inside a docs file so drift-check
+// can extract and compare exactly the rendered region.
+const (
+	MatrixBeginMarker = "<!-- BEGIN harness-matrix (generated by `devrites-engine harness-matrix`) -->"
+	MatrixEndMarker   = "<!-- END harness-matrix -->"
+)
+
+// RenderMatrix returns the marker-delimited Markdown block for the matrix. It is
+// deterministic — no timestamps — so a committed copy only changes when the
+// matrix data does.
+func RenderMatrix() string {
+	var b strings.Builder
+	b.WriteString(MatrixBeginMarker)
+	b.WriteString("\n\n| Surface | Claude Code | Codex | Phase impact | Fallback | Doctor check | Confidence | Notes |\n")
+	b.WriteString("| --- | --- | --- | --- | --- | --- | --- | --- |\n")
+	for _, s := range complianceMatrix {
+		fmt.Fprintf(&b, "| %s | %s | %s | %s | %s | %s | %s | %s |\n", s.Name, s.Claude, s.Codex, s.PhaseImpact, s.Fallback, s.DoctorCheck, s.Confidence, s.Note)
+	}
+	b.WriteString("\nTiers: **Native** (the harness exposes and delivers the surface directly; policy notes state whether it blocks) · **Adapter-backed** ")
+	b.WriteString("(supported through a translation shim) · **Instruction-backed** ")
+	b.WriteString("(no runtime surface — rides on a directive the model may under-fire) · ")
+	b.WriteString("**Conditional** (native but gated on an operator precondition).\n\n")
+	b.WriteString(MatrixEndMarker)
+	return b.String()
+}