devrites 3.0.6 → 3.1.0

package/engine/internal/gate/gate_test.go

@@ -6,6 +6,7 @@ import (
 	"strings"
 	"testing"
 
+	"github.com/devrites/devrites/internal/reason"
 	"github.com/devrites/devrites/internal/testutil"
 )
 
@@ -24,13 +25,16 @@ func TestCheckAndRenderReadiness(t *testing.T) {
 	if !res.Blocked {
 		t.Fatalf("Check blocked=false, want true")
 	}
+	if res.ReasonID != reason.GateReadinessMissing {
+		t.Fatalf("Check reason=%q, want %q", res.ReasonID, reason.GateReadinessMissing)
+	}
 	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",
+		"then re-run: devrites-engine readiness alpha",
 	} {
 		if !strings.Contains(got, want) {
 			t.Fatalf("Render() missing %q in:\n%s", want, got)
@@ -38,6 +42,52 @@ func TestCheckAndRenderReadiness(t *testing.T) {
 	}
 }
 
+func TestCheckUsesConcreteWorkspaceRequirements(t *testing.T) {
+	root := t.TempDir()
+	files := map[string]string{
+		"state.md":             "| phase | vet |\n",
+		"brief.md":             "brief\n",
+		"spec.md":              "spec\n",
+		"decisions.md":         "decisions\n",
+		"assumptions.md":       "assumptions\n",
+		"questions.md":         "none\n",
+		"decision-coverage.md": "clear\n",
+		"architecture.md":      "architecture\n",
+		"plan.md":              "plan\n",
+		"tasks.md":             "tasks\n",
+		"traceability.md":      "traceability\n",
+		"eng-review.md":        "ready\n",
+		"test-plan.md":         "", // an empty required file must not satisfy the gate
+	}
+	writeWorkFeature(t, root, "concrete", files)
+
+	res, err := Check(Readiness, root, "concrete")
+	if err != nil {
+		t.Fatal(err)
+	}
+	if !res.Blocked || strings.Join(res.MissingFiles, ",") != "test-plan.md" {
+		t.Fatalf("blocked=%v missing=%v, want only test-plan.md", res.Blocked, res.MissingFiles)
+	}
+}
+
+func TestResultReasonIDsAreStableForEveryGateOutcome(t *testing.T) {
+	cases := []struct {
+		kind    Kind
+		blocked bool
+		want    reason.ID
+	}{
+		{Readiness, false, reason.GateReadinessPassed},
+		{Readiness, true, reason.GateReadinessMissing},
+		{Seal, false, reason.GateSealPassed},
+		{Seal, true, reason.GateSealMissing},
+	}
+	for _, tc := range cases {
+		if got := ResultReasonID(tc.kind, tc.blocked); got != tc.want {
+			t.Fatalf("ResultReasonID(%q, %v)=%q, want %q", tc.kind, tc.blocked, got, tc.want)
+		}
+	}
+}
+
 func TestStateAwaitingHumanReadsCanonicalCursor(t *testing.T) {
 	data := []byte("| Key | Value |\n| --- | --- |\n| status | awaiting_human |\n")
 	if !stateAwaitingHuman(data) {
@@ -51,6 +101,7 @@ func TestStopGateRestPointInvariants(t *testing.T) {
 		files         map[string]string
 		wantBlocked   bool
 		wantReasonSub string
+		wantReasonID  reason.ID
 	}{
 		{
 			name: "red blocks",
@@ -61,6 +112,7 @@ func TestStopGateRestPointInvariants(t *testing.T) {
 			},
 			wantBlocked:   true,
 			wantReasonSub: "tests/build RED",
+			wantReasonID:  reason.HookStopRed,
 		},
 		{
 			name: "unsurfaced human gate blocks",
@@ -71,6 +123,7 @@ func TestStopGateRestPointInvariants(t *testing.T) {
 			},
 			wantBlocked:   true,
 			wantReasonSub: "open blocking/validating human question",
+			wantReasonID:  reason.HookStopUnsurfacedHumanGate,
 		},
 		{
 			name: "awaiting human allows surfaced gate",
@@ -88,6 +141,7 @@ func TestStopGateRestPointInvariants(t *testing.T) {
 			},
 			wantBlocked:   true,
 			wantReasonSub: "proof.md is empty",
+			wantReasonID:  reason.HookStopMissingProof,
 		},
 		{
 			name: "done without proof blocks",
@@ -97,6 +151,7 @@ func TestStopGateRestPointInvariants(t *testing.T) {
 			},
 			wantBlocked:   true,
 			wantReasonSub: "proof.md is empty",
+			wantReasonID:  reason.HookStopMissingProof,
 		},
 	} {
 		t.Run(tc.name, func(t *testing.T) {
@@ -117,6 +172,13 @@ func TestStopGateRestPointInvariants(t *testing.T) {
 			if tc.wantReasonSub != "" && !strings.Contains(got.Reason, tc.wantReasonSub) {
 				t.Fatalf("StopGate reason=%q, want substring %q", got.Reason, tc.wantReasonSub)
 			}
+			wantReasonID := tc.wantReasonID
+			if wantReasonID == "" {
+				wantReasonID = reason.HookStopClear
+			}
+			if got.ReasonID != wantReasonID {
+				t.Fatalf("StopGate reason_id=%q, want %q", got.ReasonID, wantReasonID)
+			}
 		})
 	}
 }
@@ -127,7 +189,7 @@ func TestStopGateUsesWorkspaceOverride(t *testing.T) {
 	if err := os.MkdirAll(root, 0o755); err != nil {
 		t.Fatal(err)
 	}
-	override := filepath.Join(project, "custom", "alpha")
+	override := filepath.Join(root, "work", "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")
@@ -159,3 +221,10 @@ func writeFeature(t *testing.T, root, slug string, files map[string]string) {
 		testutil.WriteFile(t, filepath.Join(root, "features", slug, name), content)
 	}
 }
+
+func writeWorkFeature(t *testing.T, root, slug string, files map[string]string) {
+	t.Helper()
+	for name, content := range files {
+		testutil.WriteFile(t, filepath.Join(root, "work", slug, name), content)
+	}
+}

package/engine/internal/harness/compliance.go

@@ -5,31 +5,25 @@ import (
 	"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.
+// The compliance matrix records how each harness supports every enforcement
+// surface. `devrites-engine harness-matrix` renders this data, and CI compares
+// the result with the copy in docs.
 
 // 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 means the harness exposes and delivers the surface directly. The
+	// surface note says whether its policy blocks.
 	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 means a translation layer, such as a different verb or mirrored
+	// file tree, provides the surface.
 	Adapter
-	// Instruction — no runtime enforcement surface; the behaviour rides on a
-	// directive the model is asked to follow and may under-fire.
+	// Instruction means the runtime has no enforcement surface and relies on a
+	// directive that the model may not follow consistently.
 	Instruction
-	// Conditional — natively supported, but gated on an operator precondition
-	// that silently disables it when unmet.
+	// Conditional means native support depends on an operator precondition.
 	Conditional
 )
 
@@ -60,13 +54,15 @@ type Surface struct {
 	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.
+// complianceMatrix reflects the shipped wiring in pack/.claude/settings.json
+// for Claude and the generated host artifacts plus AGENTS.md 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."},
+	{"Destructive Git authority", Conditional, Conditional, "all shell tool calls", "human permission review; no exact one-shot proof", "yes", "high", "Both wire git-guard at PreToolUse. Standard and strict profiles enforce exact 15-minute one-shot authority; minimal profile or the explicit kill list disables the hook."},
 	{"PostToolUse sentinel (redwatch)", Native, Native, "prove/build rest points", "manual red/green check", "yes", "high", "Fail-on-red sentinel wired on both."},
+	{"WebFetch ingestion warning trial", Conditional, Instruction, "external research", "inspect retrieved content as untrusted data", "no", "medium", "Claude WebFetch PostToolUse can emit an opt-in metadata-only warning with DEVRITES_INGEST_WARNING=warn; a flagged result remains in context and is omitted from the local source cache. Codex has no matching result event, so this trial is unavailable and silent."},
 	{"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."},
@@ -75,16 +71,14 @@ var complianceMatrix = []Surface{
 	{"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.
+// Matrix markers identify the generated block that the drift check compares.
 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.
+// RenderMatrix returns the marker-delimited Markdown block. It has no timestamps,
+// so its output changes only when the matrix data changes.
 func RenderMatrix() string {
 	var b strings.Builder
 	b.WriteString(MatrixBeginMarker)

package/engine/internal/harness/harness.go

@@ -1,9 +1,6 @@
-// Package harness holds the thin per-harness adapters at the engine's edge.
-//
-// One binary serves both Claude Code and Codex. The shared gate/orientation
-// logic lives in the middle (internal/orient, internal/gate); this package
-// translates each harness's hook stdin schema and its exit/decision convention.
-// The engine never calls a model: these adapters only shape stdin/stdout.
+// Package harness translates Claude Code and Codex hook payloads into the shared
+// engine format. It handles stdin, stdout, and decision envelopes but never calls
+// a model.
 package harness
 
 import (
@@ -22,8 +19,8 @@ const (
 	Codex  Harness = "codex"
 )
 
-// Parse validates a --harness flag value. An unknown harness is an error so a
-// typo surfaces loudly rather than silently picking a default convention.
+// Parse validates a --harness value. Unknown values return an error instead of
+// choosing a default.
 func Parse(s string) (Harness, error) {
 	switch Harness(s) {
 	case Claude, Codex:
@@ -84,44 +81,45 @@ type stopDecision struct {
 	Reason   string `json:"reason"`
 }
 
-// StopInput is the subset of a Stop hook's stdin payload the gate reads. The
-// loop guard (stop_hook_active) is the one field that keeps a blocking gate from
-// wedging the session: once the harness reports it already re-entered the Stop
-// hook, the gate must let the turn end.
+// StopInput contains the fields the gate reads from a Stop hook payload.
+// stop_hook_active prevents a blocking gate from reentering indefinitely.
 type StopInput struct {
-	StopHookActive bool `json:"stop_hook_active"`
+	StopHookActive        bool `json:"stop_hook_active"`
+	StopHookActivePresent bool `json:"-"`
 }
 
 // ParseStopInput decodes a Stop hook's stdin. An empty or malformed payload is
-// not an error: it decodes to the zero value (StopHookActive false), so a
-// harness that sends nothing simply gets a first-pass gate check. This keeps the
-// hook fail-open: bad stdin never crashes it.
+// not an error, but it must not be confused with an explicit first pass. Only a
+// present boolean stop_hook_active is valid enough for a blocking gate.
 func (h Harness) ParseStopInput(r io.Reader) StopInput {
-	var in StopInput
+	var payload struct {
+		StopHookActive *bool `json:"stop_hook_active"`
+	}
 	data, err := io.ReadAll(r)
 	if err != nil || len(strings.TrimSpace(string(data))) == 0 {
-		return in
+		return StopInput{}
+	}
+	if json.Unmarshal(data, &payload) != nil || payload.StopHookActive == nil {
+		return StopInput{}
+	}
+	return StopInput{
+		StopHookActive:        *payload.StopHookActive,
+		StopHookActivePresent: true,
 	}
-	_ = json.Unmarshal(data, &in) // best-effort; zero value on failure
-	return in
 }
 
-// PreToolInput is the subset of a PreToolUse hook's stdin the reviewer-readonly
-// guard reads: which tool is about to run, its command, and: for the optional
-// agent-scoping gate: the calling subagent's name. Every field is best-effort:
-// a hook that can't identify the tool simply falls through to its silent no-op.
+// PreToolInput contains the tool, command, and optional agent identity read by
+// the reviewer-readonly guard. Missing fields leave the guard silent.
 type PreToolInput struct {
 	ToolName  string
 	Command   string
 	AgentType string // the calling subagent's name; empty on the main thread
 }
 
-// ParsePreToolInput decodes a PreToolUse payload. Like ParseStopInput it never
-// errors: an empty or malformed payload decodes to the zero value so a guard hook
-// stays fail-open. AgentType reads `agent_type` ONLY: matching
-// devrites-reviewer-readonly.sh's node parse exactly (it does not consult the
-// subagent_type / agentType aliases; SubagentAgentType does, for the subagent
-// hook that needs them).
+// ParsePreToolInput decodes a PreToolUse payload. Empty or malformed input
+// returns the zero value. AgentType reads only `agent_type` to match
+// devrites-reviewer-readonly.sh; SubagentAgentType handles the aliases needed by
+// the subagent hook.
 func (h Harness) ParsePreToolInput(r io.Reader) PreToolInput {
 	var raw struct {
 		ToolName  string `json:"tool_name"`
@@ -143,10 +141,9 @@ func (h Harness) ParsePreToolInput(r io.Reader) PreToolInput {
 	}
 }
 
-// SubagentAgentType decodes just the spawned subagent's name from a SubagentStart
-// payload, reading whichever of agent_type / subagent_type / agentType the harness
-// populates (Claude and Codex differ): the exact 3-way fallback
-// devrites-subagent-orient.sh uses. Never errors: bad stdin yields "".
+// SubagentAgentType reads the spawned agent name from agent_type, subagent_type,
+// or agentType. This matches the fallback order in
+// devrites-subagent-orient.sh. Invalid input returns an empty string.
 func (h Harness) SubagentAgentType(r io.Reader) string {
 	var raw struct {
 		AgentType    string `json:"agent_type"`
@@ -195,11 +192,9 @@ type preToolEnvelope struct {
 	} `json:"hookSpecificOutput"`
 }
 
-// GuardInput is the fuller PreToolUse / PostToolUse payload the write-guards read:
-// the tool + its command / target path, the calling subagent's identity (both the
-// agent_id Claude sends and the agent_type Codex sends), and the tool's response
-// text (for the post-hooks that inspect output). Best-effort: bad stdin yields
-// the zero value so a guard stays fail-open.
+// GuardInput contains the tool, command or target path, agent identity, and
+// response text used by write guards. Claude sends agent_id, while Codex sends
+// agent_type. Invalid input returns the zero value.
 type GuardInput struct {
 	ToolName     string
 	Command      string
@@ -279,11 +274,9 @@ type additionalContextEnvelope struct {
 	} `json:"hookSpecificOutput"`
 }
 
-// marshalCompact encodes v as compact JSON WITHOUT Go's default HTML escaping
-// (`<`, `>`, `&` → `<` …). The legacy shell hooks emit their JSON via
-// node's JSON.stringify, which does not HTML-escape; matching that is what keeps
-// a ported hook byte-parity with the script it replaces. The trailing newline
-// json.Encoder appends is trimmed so the caller controls line termination.
+// marshalCompact encodes v as compact JSON without Go's default HTML escaping.
+// Legacy shell hooks use JSON.stringify, so matching its output preserves byte
+// parity. The caller controls line endings.
 func marshalCompact(v any) (string, error) {
 	var buf bytes.Buffer
 	enc := json.NewEncoder(&buf)

package/engine/internal/harness/harness_test.go

@@ -81,11 +81,27 @@ func TestHarnessEnvelopes(t *testing.T) {
 }
 
 func TestHarnessParsersFailOpenAndFallbacks(t *testing.T) {
-	if got := Claude.ParseStopInput(strings.NewReader(`{"stop_hook_active":true}`)); !got.StopHookActive {
-		t.Fatalf("ParseStopInput did not read stop_hook_active")
-	}
-	if got := Claude.ParseStopInput(strings.NewReader(`not-json`)); got.StopHookActive {
-		t.Fatalf("ParseStopInput malformed payload = %#v, want zero value", got)
+	for _, test := range []struct {
+		name    string
+		payload string
+		present bool
+		active  bool
+	}{
+		{"explicit false", `{"stop_hook_active":false}`, true, false},
+		{"explicit true", `{"stop_hook_active":true}`, true, true},
+		{"empty", ``, false, false},
+		{"malformed", `not-json`, false, false},
+		{"missing", `{}`, false, false},
+		{"null", `{"stop_hook_active":null}`, false, false},
+		{"wrong type", `{"stop_hook_active":"false"}`, false, false},
+	} {
+		t.Run("stop/"+test.name, func(t *testing.T) {
+			got := Claude.ParseStopInput(strings.NewReader(test.payload))
+			if got.StopHookActivePresent != test.present || got.StopHookActive != test.active {
+				t.Fatalf("ParseStopInput(%q) = %#v, want present=%v active=%v",
+					test.payload, got, test.present, test.active)
+			}
+		})
 	}
 
 	pre := Codex.ParsePreToolInput(strings.NewReader(`{"tool_name":"Bash","tool_input":{"command":"go test ./..."},"agent_type":"reviewer"}`))