devrites 3.0.5 → 3.0.7

package/engine/hookpolicy.go

@@ -7,7 +7,7 @@ import (
 
 // Hook control plane.
 //
-// Every wired hook has a canonical id — its `hook <name>` CLI verb (allow,
+// Every wired hook has a canonical id: its `hook <name>` CLI verb (allow,
 // orient, stop-gate, …). That id is the addressable handle for two orthogonal
 // runtime controls, both read from the environment so an operator tunes safety
 // vs speed without editing any JSON:
@@ -17,7 +17,7 @@ import (
 //
 // The profile is a floor: a hook runs when its tier is at or below the active
 // profile AND it is not in the kill list. Everything else short-circuits to a
-// clean fail-open no-op in cmdHook — identical to the inline `command -v … ||
+// clean fail-open no-op in cmdHook: identical to the inline `command -v … ||
 // exit 0` guard, so a disabled hook is indistinguishable from an absent binary.
 //
 // A SEPARATE axis is enforce-vs-observe: the OBSERVE-by-default guards (a1-guard,
@@ -31,23 +31,23 @@ type hookTier int
 
 const (
 	tierMinimal  hookTier = iota // orientation-only; never blocks or mutates flow
-	tierStandard                 // the default working set — gates, guards, caches
+	tierStandard                 // the default working set: gates, guards, caches
 	tierStrict                   // reserved for experimental/aggressive hooks
 )
 
 // hookRegistry maps each canonical hook id to the profile tier that first
 // activates it. A name absent from the registry is treated as tierMinimal
-// (always active) — fail-open: an unrecognised hook is never silently disabled
+// (always active): fail-open: an unrecognised hook is never silently disabled
 // by the profile mechanism.
 var hookRegistry = map[string]hookTier{
-	// minimal — orientation and auto-approval, which never interrupt work.
+	// minimal: orientation and auto-approval, which never interrupt work.
 	"allow":           tierMinimal,
 	"orient":          tierMinimal,
 	"subagent-orient": tierMinimal,
 	"cursor":          tierMinimal,
 	"statusline":      tierMinimal,
 
-	// standard — the default gates, guards, sentinels and caches.
+	// standard: the default gates, guards, sentinels and caches.
 	"a1-guard":          tierStandard,
 	"stop-gate":         tierStandard,
 	"reviewer-readonly": tierStandard,
@@ -62,7 +62,7 @@ var hookRegistry = map[string]hookTier{
 }
 
 // hookProfileTier resolves DEVRITES_HOOK_PROFILE to a tier, defaulting to
-// standard on empty or unrecognised input (fail-open — a typo never silently
+// standard on empty or unrecognised input (fail-open: a typo never silently
 // strips the working set below default).
 func hookProfileTier() hookTier {
 	switch strings.ToLower(strings.TrimSpace(os.Getenv("DEVRITES_HOOK_PROFILE"))) {
@@ -83,7 +83,7 @@ func hookActive(name string) bool {
 	}
 	tier, known := hookRegistry[name]
 	if !known {
-		return true // unknown id — never disabled by profile
+		return true // unknown id: never disabled by profile
 	}
 	return tier <= hookProfileTier()
 }
@@ -105,7 +105,7 @@ func hookDisabled(name string) bool {
 
 // hookEnforce reports whether an OBSERVE-default guard should block rather than
 // log. It is true when the guard's own DEVRITES_*=enforce var is set, OR when
-// the strict profile is active — strict enforces every guard at once.
+// the strict profile is active: strict enforces every guard at once.
 func hookEnforce(specificVar string) bool {
 	if os.Getenv(specificVar) == "enforce" {
 		return true

package/engine/hooks.go

@@ -22,13 +22,13 @@ import (
 // The engine's inline shell guard handles a missing binary; this handles a
 // present binary run outside a workspace.
 func hookOrient(h harness.Harness, stdin io.Reader, stdout, stderr io.Writer) int {
-	// The SessionStart payload is drained but unused — orientation is a pure read
+	// The SessionStart payload is drained but unused: orientation is a pure read
 	// of the workspace files, not a function of the harness's stdin.
 	_, _ = io.Copy(io.Discard, stdin)
 
 	root, err := orient.ResolveRoot(os.Getenv("DEVRITES_ROOT"))
 	if err != nil {
-		return exitOK // not a DevRites workspace — silent no-op
+		return exitOK // not a DevRites workspace: silent no-op
 	}
 	text, has, err := orient.Digest(root)
 	if err != nil {
@@ -58,7 +58,7 @@ func hookOrient(h harness.Harness, stdin io.Reader, stdout, stderr io.Writer) in
 func hookStopGate(h harness.Harness, stdin io.Reader, stdout, stderr io.Writer) int {
 	in := h.ParseStopInput(stdin)
 	if in.StopHookActive {
-		return exitOK // already re-entered this stop cycle — let it stop
+		return exitOK // already re-entered this stop cycle: let it stop
 	}
 	root, err := orient.ResolveRoot(os.Getenv("DEVRITES_ROOT"))
 	if err != nil {
@@ -89,7 +89,7 @@ func hookStopGate(h harness.Harness, stdin io.Reader, stdout, stderr io.Writer)
 }
 
 // allowReason is the auto-approval message the allow hook emits.
-const allowReason = "DevRites read-only orientation/gate command — auto-approved by the devrites-allow hook"
+const allowReason = "DevRites read-only orientation/gate command: auto-approved by the devrites-allow hook"
 
 var allowReadonlyCommands = map[string]bool{
 	"check-acceptance": true,
@@ -213,10 +213,10 @@ func safeAllowArg(arg string) bool {
 // reviewerReadonlyDenyReason is the exact denial message
 // devrites-reviewer-readonly.sh emits. It must stay byte-identical to keep the
 // parity oracle green.
-const reviewerReadonlyDenyReason = "DevRites: reviewers are read-only. This Bash command can mutate or exfiltrate; inspect with Read/Grep/Glob and return findings — do not modify the tree or reach the network. (devrites-reviewer-readonly)"
+const reviewerReadonlyDenyReason = "DevRites: reviewers are read-only. This Bash command can mutate or exfiltrate; inspect with Read/Grep/Glob and return findings: do not modify the tree or reach the network. (devrites-reviewer-readonly)"
 
 // reviewerMutateRe matches a Bash command that could mutate the tree or reach the
-// network — the deny-list ported verbatim from devrites-reviewer-readonly.sh. A
+// network: the deny-list ported verbatim from devrites-reviewer-readonly.sh. A
 // fresh-context reviewer reads untrusted source, so a silent write/exfil path is
 // a prompt-injection surface (standards/security.md). pack-scan-ignore: this is
 // the hook's own defensive deny-list, not a payload.
@@ -225,7 +225,7 @@ const reviewerReadonlyDenyReason = "DevRites: reviewers are read-only. This Bash
 // this matches against the WHOLE command, while the bash hook's
 // `read -r tool cmd agent_type` truncates the command at its first newline and so
 // only ever scans line 1. A reviewer running a multi-line Bash whose later lines
-// mutate (e.g. `cat x\nsed -i …`) slips past the bash hook but is denied here —
+// mutate (e.g. `cat x\nsed -i …`) slips past the bash hook but is denied here:
 // intentional hardening of a latent bash bug, not a parity regression. (RE2's
 // `[[:space:]]` already matches `\n`, so no `(?m)` flag is needed for the `-i$`
 // alternative to fire at an interior line break.)
@@ -240,7 +240,7 @@ func hookReviewerReadonly(h harness.Harness, stdin io.Reader, stdout, stderr io.
 	if err != nil {
 		return exitOK
 	}
-	// Fast path: a payload with no tool call is not ours — mirrors the script's
+	// Fast path: a payload with no tool call is not ours: mirrors the script's
 	// `case "$input" in *'"tool_name"'*`.
 	if !bytes.Contains(data, []byte(`"tool_name"`)) {
 		return exitOK
@@ -300,19 +300,19 @@ var subagentOrientContext string
 // hookSubagentOrient injects the DevRites discipline into every devrites-* subagent
 // at spawn: a spawned subagent starts in a fresh context and neither auto-loads the
 // rite-* framework nor discovers skills the way the main thread does. It mirrors
-// devrites-subagent-orient.sh — fire only for devrites-* agents, emit a fixed
+// devrites-subagent-orient.sh: fire only for devrites-* agents, emit a fixed
 // context envelope, stay silent + fail-open otherwise.
 func hookSubagentOrient(h harness.Harness, stdin io.Reader, stdout, stderr io.Writer) int {
 	agentType := h.SubagentAgentType(stdin)
 	if !strings.HasPrefix(agentType, "devrites-") {
-		return exitOK // not a DevRites subagent (or no identity) — silent no-op
+		return exitOK // not a DevRites subagent (or no identity): silent no-op
 	}
 	out, err := h.SubagentStartContext(strings.ReplaceAll(subagentOrientContext, "\r\n", "\n"))
 	if err != nil {
 		debugf(stderr, "subagent-orient: %v", err)
 		return exitOK
 	}
-	// No trailing newline — matches the script's `node ... process.stdout.write`.
+	// No trailing newline: matches the script's `node ... process.stdout.write`.
 	fmt.Fprint(stdout, out)
 	return exitOK
 }

package/engine/hooks_workspace.go

@@ -41,7 +41,7 @@ func resolveWorkspaceDir(root, slug string) string {
 }
 
 // resolveWorkspace resolves the active feature's directory.
-// ok is false — a silent no-op — when there is no .devrites root or no active
+// ok is false (a silent no-op) when there is no .devrites root or no active
 // feature, keeping the hooks fail-open outside a DevRites workspace.
 func resolveWorkspace() (root, slug, dir string, ok bool) {
 	root, err := orient.ResolveRoot(os.Getenv("DEVRITES_ROOT"))
@@ -74,8 +74,8 @@ type auqEventJSON struct {
 // bloats the timeline.
 const auqFieldMax = 300
 
-// hookAUQ deterministically captures an AskUserQuestion exchange — every
-// question with the user's chosen answer — into the session trace, so HITL
+// hookAUQ deterministically captures an AskUserQuestion exchange: every
+// question with the user's chosen answer: into the session trace, so HITL
 // decisions are recorded at the substrate rather than trusted to the model's
 // bookkeeping. Capture only: it never tunes, blocks, or replies. Fail-open like
 // every workspace hook: unparseable payload, unknown response shape, or no
@@ -192,7 +192,7 @@ func hookHandoffSnapshot(stdin io.Reader, stdout, stderr io.Writer) int {
 	next, _ := state.CursorField(stateLines, state.CursorNextAction)
 	stamp := time.Now().UTC().Format(time.RFC3339)
 	var b strings.Builder
-	fmt.Fprintf(&b, "\n## Handoff snapshot — %s\n", stamp)
+	fmt.Fprintf(&b, "\n## Handoff snapshot: %s\n", stamp)
 	fmt.Fprintf(&b, "- Feature: %s\n", slug)
 	if phase != "" {
 		fmt.Fprintf(&b, "- Phase: %s\n", phase)
@@ -229,7 +229,7 @@ func hookCursor(stdin io.Reader, stdout, stderr io.Writer) int {
 		afk, _ = state.CursorField(stateLines, state.CursorAFKSlicesRemaining)
 	}
 
-	fmt.Fprintf(stdout, "DevRites cursor — active feature: %s\n", slug)
+	fmt.Fprintf(stdout, "DevRites cursor: active feature: %s\n", slug)
 	if status != "" {
 		fmt.Fprintf(stdout, "  status: %s\n", status)
 	}
@@ -241,7 +241,7 @@ func hookCursor(stdin io.Reader, stdout, stderr io.Writer) int {
 		fmt.Fprintf(stdout, "  AFK slices remaining: %s\n", afk)
 	}
 	if wsIsFile(filepath.Join(dir, ".red")) {
-		fmt.Fprintln(stdout, "  ⚠ tests/build RED — resolve before stopping")
+		fmt.Fprintln(stdout, "  ⚠ tests/build RED: resolve before stopping")
 	}
 	return exitOK
 }
@@ -281,7 +281,7 @@ var (
 	redPassRe    = regexp.MustCompile(`(?im)PASS(ED)?|0[[:space:]]+(failed|failing|errors?)|all tests passed|BUILD SUCC(ESS|EEDED)|succeeded|no (errors|problems|issues)|(^|[^a-z])ok([^a-z]|$)|✓`)
 )
 
-const redReasonFmt = "DevRites: tests/build are RED (%s). Fix to green or record the failure + next step in state.md before stopping — the Stop gate blocks an end-of-turn while .red is set."
+const redReasonFmt = "DevRites: tests/build are RED (%s). Fix to green or record the failure + next step in state.md before stopping: the Stop gate blocks an end-of-turn while .red is set."
 
 // hookRedwatch is the fail-on-red sentinel (PostToolUse Bash). After a test / build
 // / lint command it sets or clears <featureDir>/.red so the Stop gate can refuse to
@@ -339,7 +339,7 @@ func redwatchSafe(cmd string) string {
 // node regex the shell guards use.
 var patchPathRe = regexp.MustCompile(`(?m)^\*\*\* (?:(?:Add|Update|Delete) File|Move to): (.+)$`)
 
-// isEditTool reports whether a tool can write source — the Edit family plus
+// isEditTool reports whether a tool can write source: the Edit family plus
 // Codex's apply_patch.
 func isEditTool(tool string) bool {
 	switch tool {
@@ -364,10 +364,10 @@ func underDevrites(abs, root string) bool {
 	return strings.HasPrefix(abs, root+string(filepath.Separator))
 }
 
-const a1DenyReason = "DevRites A1: the orchestrator must not edit source mid-build — the slice-wright is the only writer. Re-dispatch the wright (continue it once) or stop + escalate; do not patch the code yourself. (devrites-a1-guard)"
+const a1DenyReason = "DevRites A1: the orchestrator must not edit source mid-build: the slice-wright is the only writer. Re-dispatch the wright (continue it once) or stop + escalate; do not patch the code yourself. (devrites-a1-guard)"
 
 // hookA1Guard keeps the /rite-build orchestrator from editing source while a slice
-// is mid-build — the slice-wright (a subagent) is the only sanctioned writer of
+// is mid-build: the slice-wright (a subagent) is the only sanctioned writer of
 // code. Ported from devrites-a1-guard.sh onto the new schema: FAIL-OPEN, OBSERVE by
 // default (logs to .a1-guard.log), blocking only when the build window is open, the
 // edit is source from the MAIN thread, and enforce mode is on.
@@ -451,7 +451,7 @@ func hookA1Guard(h harness.Harness, stdin io.Reader, stdout, stderr io.Writer) i
 	return exitOK
 }
 
-const wrightDenyReason = "DevRites scope: this path is not in touched-files.md. Build only the slice contract; if the slice genuinely needs this file, return an Escalation so the orchestrator routes it through the Spec Drift Guard — do not widen scope yourself. (devrites-wright-scope)"
+const wrightDenyReason = "DevRites scope: this path is not in touched-files.md. Build only the slice contract; if the slice genuinely needs this file, return an Escalation so the orchestrator routes it through the Spec Drift Guard: do not widen scope yourself. (devrites-wright-scope)"
 
 // hookWrightScope fences the slice-wright to its slice: it denies an Edit/Write to a
 // path not listed in the feature's touched-files.md. Ported from

package/engine/internal/doctor/doctor.go

@@ -1,5 +1,5 @@
-// Package doctor reports the version triangle — the engine binary, the installed
-// DevRites pack, and the on-disk .devrites state schema — and a clear skew
+// Package doctor reports the version triangle: the engine binary, the installed
+// DevRites pack, and the on-disk .devrites state schema, and a clear skew
 // verdict. Version skew is a leading cause of silent breakage; doctor turns it
 // into one legible line. Everything here is a read; doctor never mutates state.
 package doctor
@@ -16,7 +16,7 @@ import (
 )
 
 // Unknown is the pack value reported when the installed pack version can't be
-// discovered — skew against an unknown pack is not asserted.
+// discovered: skew against an unknown pack is not asserted.
 const Unknown = "unknown"
 
 // Report is the resolved version triangle plus its verdict.
@@ -45,7 +45,7 @@ func Diagnose(projectDir, root string) (*Report, error) {
 		return nil, fmt.Errorf("read state schema: %w", err)
 	}
 	if stateSchema == 0 {
-		// Nothing on disk declares a version — treat it as the current schema;
+		// Nothing on disk declares a version: treat it as the current schema;
 		// undeclared state is read as the engine's own version.
 		stateSchema = state.SchemaVersion
 	}
@@ -61,10 +61,10 @@ func Diagnose(projectDir, root string) (*Report, error) {
 	switch {
 	case r.StateSchema > r.BinarySchema:
 		r.Refuse = true
-		r.Verdict = fmt.Sprintf("REFUSE: state schema v%d is newer than this binary supports (v%d) — update devrites",
+		r.Verdict = fmt.Sprintf("REFUSE: state schema v%d is newer than this binary supports (v%d): update devrites",
 			r.StateSchema, r.BinarySchema)
 	case r.packSkew():
-		r.Verdict = fmt.Sprintf("WARN: binary %s is older than the installed pack %s — update the devrites-engine binary",
+		r.Verdict = fmt.Sprintf("WARN: binary %s is older than the installed pack %s: update the devrites-engine binary",
 			r.Binary, r.Pack)
 	default:
 		r.Verdict = "ok: binary, pack, and state schema are compatible"
@@ -131,7 +131,7 @@ func driftChecks(projectDir string) []string {
 			checks = append(checks, "WARN: .claude/settings.json exists but does not reference devrites-engine hooks")
 		}
 	} else if isDir(filepath.Join(projectDir, ".claude")) {
-		checks = append(checks, "WARN: .claude/settings.json missing — Claude hooks/statusline may be absent")
+		checks = append(checks, "WARN: .claude/settings.json missing: Claude hooks/statusline may be absent")
 	}
 	if isDir(filepath.Join(projectDir, ".claude", "skills")) && !isDir(filepath.Join(projectDir, ".agents", "skills")) {
 		checks = append(checks, "WARN: Claude skills installed but Codex skill mirror .agents/skills is missing")

package/engine/internal/gate/gate.go

@@ -2,7 +2,7 @@
 //
 // 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
+// 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
@@ -23,10 +23,10 @@ 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.
+	// 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.
+	// feature's current phase: the final completeness gate before shipping.
 	Seal Kind = "seal"
 )
 
@@ -44,7 +44,7 @@ type Result struct {
 // 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
+// (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)
@@ -68,7 +68,7 @@ func Check(kind Kind, root, slug string) (*Result, error) {
 
 // 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.
+// 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)
@@ -92,10 +92,10 @@ func (r *Result) Render() string {
 // StopGate evaluates the stop-hook rest-point invariant for the active feature:
 // a feature that CLAIMS completion (it has advanced to seal, ship, or done)
 // must not have an empty proof section. This is a rest-point check, NOT
-// whole-feature completeness — normal in-progress incompleteness never trips it,
+// 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
+// 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) {
@@ -108,7 +108,7 @@ func StopGate(root string) (StopResult, error) {
 		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
+	// 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 {
@@ -116,7 +116,7 @@ func StopGate(root string) (StopResult, error) {
 			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",
+				"feature %q has tests/build RED (.red is set): fix to green, or record the failure and next step, before stopping",
 				slug),
 		}, nil
 	}
@@ -125,7 +125,7 @@ func StopGate(root string) (StopResult, error) {
 			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",
+				"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
 	}
@@ -135,7 +135,7 @@ func StopGate(root string) (StopResult, error) {
 			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",
+				"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
 	}

package/engine/internal/harness/compliance.go

@@ -95,7 +95,7 @@ func RenderMatrix() string {
 	}
 	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("(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()

package/engine/internal/harness/harness.go

@@ -3,7 +3,7 @@
 // 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.
+// The engine never calls a model: these adapters only shape stdin/stdout.
 package harness
 
 import (
@@ -93,7 +93,7 @@ type StopInput struct {
 }
 
 // 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
+// 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.
 func (h Harness) ParseStopInput(r io.Reader) StopInput {
@@ -107,8 +107,8 @@ func (h Harness) ParseStopInput(r io.Reader) StopInput {
 }
 
 // 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:
+// 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.
 type PreToolInput struct {
 	ToolName  string
@@ -118,7 +118,7 @@ type PreToolInput struct {
 
 // 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
+// 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).
@@ -145,7 +145,7 @@ 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
+// populates (Claude and Codex differ): the exact 3-way fallback
 // devrites-subagent-orient.sh uses. Never errors: bad stdin yields "".
 func (h Harness) SubagentAgentType(r io.Reader) string {
 	var raw struct {
@@ -198,7 +198,7 @@ type preToolEnvelope struct {
 // 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
+// text (for the post-hooks that inspect output). Best-effort: bad stdin yields
 // the zero value so a guard stays fail-open.
 type GuardInput struct {
 	ToolName     string

package/engine/internal/install/install.go

@@ -16,6 +16,7 @@ import (
 	"os/exec"
 	"path/filepath"
 	"reflect"
+	"runtime"
 	"slices"
 	"sort"
 	"strings"
@@ -30,6 +31,7 @@ import (
 
 const ManifestName = devritespaths.ManifestName
 const defaultRepo = "ViktorsBaikers/DevRites"
+const githubBaseURL = "https://github.com"
 
 type Mode string
 
@@ -69,15 +71,17 @@ type stats struct {
 }
 
 type runner struct {
-	opts      Options
-	target    string
-	payload   string
-	payloadFS fs.FS
-	source    string
-	manifest  []string
-	records   map[string]string
-	prev      map[string]bool
-	stats     stats
+	opts             Options
+	target           string
+	payload          string
+	payloadFS        fs.FS
+	source           string
+	manifest         []string
+	records          map[string]string
+	prev             map[string]bool
+	stats            stats
+	releaseBinaryTag string
+	preparedBinary   string
 }
 
 func DefaultOptions(mode Mode) Options {
@@ -849,7 +853,20 @@ func runUpdate(opts Options) error {
 	if opts.DryRun {
 		next.DryRun = true
 	}
-	return Apply(next)
+	r, err := newRunner(next)
+	if err != nil {
+		return fmt.Errorf("prepare installer: %w", err)
+	}
+	r.releaseBinaryTag = latestTag
+	if next.WithBinary && os.Getenv("DEVRITES_NO_BINARY") != "1" && !next.DryRun {
+		staged, cleanup, err := r.acquireBinary(latestTag, githubBaseURL)
+		if err != nil {
+			return fmt.Errorf("prepare engine binary: %w", err)
+		}
+		defer cleanup()
+		r.preparedBinary = staged
+	}
+	return r.install()
 }
 
 func resolveUpdateTag(opts Options) (string, error) {
@@ -1185,6 +1202,8 @@ func containsDevritesHook(v any) bool {
 
 func isDevritesHooksComment(comment string) bool {
 	return comment == "DevRites hooks" ||
+		strings.HasPrefix(comment, "DevRites hooks: every event invokes the global `devrites-engine` engine binary") ||
+		strings.HasPrefix(comment, "DevRites hooks: auto-approve the read-only orientation/gate scripts") ||
 		strings.HasPrefix(comment, "DevRites hooks — every event invokes the global `devrites-engine` engine binary") ||
 		strings.HasPrefix(comment, "DevRites hooks — auto-approve the read-only orientation/gate scripts") ||
 		strings.HasPrefix(comment, "DevRites hooks for Codex. Project hooks load only after")
@@ -1295,24 +1314,24 @@ func (r *runner) installBinary() error {
 			return nil
 		}
 	}
-	staged, cleanup, err := r.acquireBinary(tag)
-	if err != nil {
-		fmt.Fprintf(r.opts.Stderr, "warning: engine binary: %v - hooks fail open until you install it.\n", err)
-		return nil
+	staged, cleanup := r.preparedBinary, func() {}
+	if staged == "" {
+		var err error
+		staged, cleanup, err = r.acquireBinary(tag, githubBaseURL)
+		if err != nil {
+			return r.binaryInstallFailure(err)
+		}
 	}
 	defer cleanup()
 	if err := os.MkdirAll(filepath.Dir(dest), 0o755); err != nil {
-		fmt.Fprintf(r.opts.Stderr, "warning: engine binary: %v - hooks fail open until you install it.\n", err)
-		return nil
+		return r.binaryInstallFailure(err)
 	}
 	data, err := os.ReadFile(staged)
 	if err != nil {
-		fmt.Fprintf(r.opts.Stderr, "warning: engine binary: %v - hooks fail open until you install it.\n", err)
-		return nil
+		return r.binaryInstallFailure(err)
 	}
 	if err := fsutil.WriteFileAtomic(dest, data, 0o755); err != nil {
-		fmt.Fprintf(r.opts.Stderr, "warning: engine binary: %v - hooks fail open until you install it.\n", err)
-		return nil
+		return r.binaryInstallFailure(err)
 	}
 	_ = os.Chmod(dest, 0o755)
 	fmt.Fprintf(r.opts.Stdout, "  engine binary: installed %s\n", dest)
@@ -1322,12 +1341,23 @@ func (r *runner) installBinary() error {
 	return nil
 }
 
-func (r *runner) acquireBinary(tag string) (string, func(), error) {
+func (r *runner) binaryInstallFailure(err error) error {
+	if r.preparedBinary != "" {
+		return err
+	}
+	fmt.Fprintf(r.opts.Stderr, "warning: engine binary: %v - hooks fail open until you install it.\n", err)
+	return nil
+}
+
+func (r *runner) acquireBinary(tag, baseURL string) (string, func(), error) {
 	if v := os.Getenv("DEVRITES_ENGINE_CLI"); v != "" {
 		if exists(v) {
-			return v, func() {}, nil
+			if r.releaseBinaryTag == "" || strings.TrimPrefix(engineVersion(v), "v") == strings.TrimPrefix(r.releaseBinaryTag, "v") {
+				return v, func() {}, nil
+			}
+		} else {
+			return "", func() {}, fmt.Errorf("DEVRITES_ENGINE_CLI points to a missing binary: %s", v)
 		}
-		return "", func() {}, fmt.Errorf("DEVRITES_ENGINE_CLI points to a missing binary: %s", v)
 	}
 	tmp, err := os.MkdirTemp("", "devrites-engine-*")
 	if err != nil {
@@ -1335,19 +1365,60 @@ func (r *runner) acquireBinary(tag string) (string, func(), error) {
 	}
 	cleanup := func() { _ = os.RemoveAll(tmp) }
 	staged := filepath.Join(tmp, "devrites-engine")
+	var releaseErr error
+	if r.releaseBinaryTag != "" && os.Getenv("DEVRITES_UPDATE_BUNDLE") == "" {
+		repo := os.Getenv("DEVRITES_REPO")
+		if repo == "" {
+			repo = defaultRepo
+		}
+		downloaded, err := downloadReleaseBinary(baseURL, repo, r.releaseBinaryTag, staged)
+		if err == nil {
+			return staged, cleanup, nil
+		}
+		if downloaded {
+			return "", cleanup, err
+		}
+		releaseErr = err
+	}
 	if r.source != "" && exists(filepath.Join(r.source, "engine", "go.mod")) {
 		ctx, cancel := context.WithTimeout(context.Background(), 10*time.Minute)
 		defer cancel()
-		cmd := exec.CommandContext(ctx, "go", "build", "-trimpath", "-ldflags", "-s -w -X github.com/devrites/devrites/internal/version.Version="+tag, "-o", staged, ".")
+		cmd := exec.CommandContext(ctx, "go", "build", "-buildvcs=false", "-trimpath", "-ldflags", "-s -w -X github.com/devrites/devrites/internal/version.Version="+tag, "-o", staged, ".")
 		cmd.Dir = filepath.Join(r.source, "engine")
 		if out, err := cmd.CombinedOutput(); err != nil {
+			if releaseErr != nil {
+				return "", cleanup, fmt.Errorf("could not download release binary: %v; source fallback failed: %w: %s", releaseErr, err, strings.TrimSpace(string(out)))
+			}
 			return "", cleanup, fmt.Errorf("could not build from source: %w: %s", err, strings.TrimSpace(string(out)))
 		}
 		return staged, cleanup, nil
 	}
+	if releaseErr != nil {
+		return "", cleanup, fmt.Errorf("could not obtain a binary: %v; no Go source fallback", releaseErr)
+	}
 	return "", cleanup, fmt.Errorf("could not obtain a binary (no DEVRITES_ENGINE_CLI handoff, no Go source)")
 }
 
+func downloadReleaseBinary(baseURL, repo, tag, dest string) (bool, error) {
+	asset := fmt.Sprintf("devrites-%s-%s", runtime.GOOS, runtime.GOARCH)
+	if runtime.GOOS == "windows" {
+		asset += ".exe"
+	}
+	url := fmt.Sprintf("%s/%s/releases/download/%s/%s", strings.TrimRight(baseURL, "/"), repo, tag, asset)
+	if err := iohooks.DownloadFile(url, dest); err != nil {
+		return false, fmt.Errorf("download %s: %w", asset, err)
+	}
+	sumPath := dest + ".sha256"
+	defer os.Remove(sumPath)
+	if err := iohooks.DownloadFile(url+".sha256", sumPath); err != nil {
+		return true, fmt.Errorf("could not verify release binary %s: missing checksum: %w", asset, err)
+	}
+	if err := verifySHA256(dest, sumPath); err != nil {
+		return true, fmt.Errorf("could not verify release binary %s: %w", asset, err)
+	}
+	return true, nil
+}
+
 func (r *runner) removeBinary() error {
 	if r.opts.KeepBinary {
 		fmt.Fprintln(r.opts.Stdout, "  kept the global devrites-engine binary (--keep-binary).")