@miller-tech/uap 1.22.0 → 1.26.1

package/docs/architecture/EXPERT_STACK.md

@@ -0,0 +1,137 @@
+# Expert Stack: Forward-Design, HALO & Open-Collider
+
+This document covers the expert-system extensions added on top of the v1.23.0
+droid stack: forward-design experts, the activated experts-as-MCP-tools surface,
+HALO trace-based harness optimization, open-collider divergent ideation, and the
+expert-review hard gate.
+
+> Scope note: the base 33-droid roster, `ExpertOrchestrator`, `expert-route`
+> CLI, and `parallel-expert-review` skill already shipped in v1.23.0. This layer
+> closes real gaps in that stack and integrates two external tools.
+
+---
+
+## 1. Forward-design droids
+
+The pre-existing roster was review-heavy — the orchestrator's `plan`/`design`
+phases produced no up-front design. Three forward-design experts fill that gap:
+
+| Droid | Phase | Role |
+|---|---|---|
+| `strategic-architect` | plan | North-star architecture, technology selection (OSS-first), multi-quarter evolution, one-way-door decisions. Forward-design counterpart to `architect-reviewer`. |
+| `tactical-architect` | design | Concrete component/module boundaries, interfaces, data shapes, pattern selection, refactor strategy. |
+| `implementation-planner` | design | Executable work breakdown: ordered steps, file-level plan (reuse-first), test plan, risk/rollback. Feeds the `validate-plan-before-build` gate. |
+
+Wiring: `src/coordination/expert-orchestrator.ts` — `PHASE_ROSTER.plan` gains
+`strategic-architect`; `PHASE_ROSTER.design` gains `tactical-architect` and
+`implementation-planner`; `isRelevantForCapability` maps them to the
+`architecture`/`api-design` capabilities so they appear only on relevant tasks.
+
+```bash
+uap expert-route "Design a new billing subsystem" --files src/types/billing.ts --json
+# → plan: strategic-architect … design: tactical-architect, implementation-planner …
+```
+
+---
+
+## 2. Experts as MCP tools (activated)
+
+`src/mcp-router/experts/registry.ts` could already convert droids to virtual
+`experts.<name>` tools (`loadExpertTools`) but was never wired in. Now:
+
+- `McpRouter.loadTools()` (`src/mcp-router/server.ts`) calls `loadExpertTools(cwd)`
+  and adds the experts to the fuzzy search index.
+- `handleExecuteTool` (`src/mcp-router/tools/execute.ts`) intercepts
+  `experts.<droid>` paths and dispatches an in-process `consultExpert()` — it
+  loads the droid's instructions and returns them wrapped as a prompt (mirroring
+  `uap_droid_invoke`), instead of routing to an external MCP server.
+
+Result: `discover_tools "architecture review"` surfaces the right expert and
+`execute_tool experts.architect-reviewer` returns a consultation — all within
+the 2-tool token-saving router shape.
+
+---
+
+## 3. HALO — trace-based harness optimization
+
+[HALO](https://github.com/context-labs/HALO) analyzes large volumes of execution
+traces to find *systemic* harness/prompt failure modes (not one-off errors). UAP
+integrates it as an exporter + a droid + a CLI.
+
+**Exporter** (`src/observability/halo-exporter.ts`) — opt-in, zero-overhead when
+off. Emits one JSONL span per agent/LLM/tool call in HALO's OTLP/OpenInference
+shape: OTLP identity, `resource.attributes."service.name"`, and the four
+`inference.*` attributes (`project_id`, `observation_kind`, `export.schema_version`,
+`openinference.span.kind`), with nanosecond-precision timestamps.
+
+Tap points: `execute.ts:handleExecuteTool` (TOOL spans) and
+`session-telemetry.ts` `agentComplete`/`agentError` (AGENT spans).
+
+```bash
+export UAP_HALO_TRACE=1                  # enable collection
+export UAP_HALO_TRACE_PATH=.uap/halo/traces.jsonl
+# … run your workflow …
+uap harness status                       # enabled? path? span count?
+uap harness analyze -p "systemic failure modes?"   # wraps `halo <file> -p ...`
+```
+
+**Prerequisite:** `pip install halo-engine` (Python ≥3.10) + an OpenAI-compatible
+endpoint. Each analysis run incurs LLM cost. The `harness-optimizer` droid runs
+the loop: diagnose → **verify each claim against the repo** → route fixes →
+re-measure. Hard rule: *ask HALO about the trace data; never ask it to write code.*
+
+---
+
+## 4. Open-Collider — divergent ideation
+
+[open-collider](https://github.com/CL-ML/open-collider) escapes LLM "hivemind"
+clustering by colliding structurally distant knowledge domains (Koestler
+bisociation), then curating non-trivial ideas. Skill mode is free.
+
+- `ideation-expert` droid drives the brief → domains → collide → curate flow.
+- `uap ideate setup <name>` scaffolds the `projects/<name>/` file contract
+  (`brief_validated.json`, `input_bank.yaml`, `prompts/`, `texts/`).
+- `uap ideate run <name>` drives the brainstorm; `uap ideate ideas <name>` reads
+  the newest `curated_ideas.json`.
+- Orchestrator opt-in: `new ExpertOrchestrator({ includeIdeation: true })`
+  prepends an `ideate` phase feeding the plan-phase product/strategy droids.
+  `readCuratedIdeas()` (`src/cli/ideate.ts`) is the consumable artifact.
+
+Use it only when the solution space is wide; skip for convergent tasks.
+
+---
+
+## 5. Expert-review hard gate
+
+The `parallel-expert-review` skill claimed "REQUIRED by policy" but nothing
+enforced it. Two policy artifacts close that:
+
+- `expert-review-required` (`src/policies/schemas/policies/expert-review-required.md`
+  + `src/policies/enforcers/expert_review_required.py`): blocks ship actions
+  (`git commit`/`push`, `gh pr create`, merge/pr-ready/signoff) unless
+  `.uap/reviews/<branch-slug>.json` exists and covers `HEAD` (stale → block).
+  Fail-open on detached/non-git; override `UAP_NO_REVIEW=1`.
+- `architecture-review` (`…/policies/architecture-review.md`): the missing
+  backing doc for the previously-orphan `architecture_review.py` enforcer
+  (ADR-or-waiver on architecturally significant diffs).
+
+The review flow writes the artifact on consolidation:
+`{ "head": "<sha>", "verdict": "approve", "reviewers": [...] }`. Install with:
+
+```bash
+uap policy install expert-review-required   # attaches the enforcer to the hook
+```
+
+---
+
+## File map
+
+| Concern | Path |
+|---|---|
+| Forward-design droids | `.factory/droids/{strategic-architect,tactical-architect,implementation-planner}.md` |
+| Orchestrator wiring | `src/coordination/expert-orchestrator.ts` |
+| Experts-MCP dispatch | `src/mcp-router/experts/registry.ts`, `server.ts`, `tools/execute.ts` |
+| HALO exporter | `src/observability/halo-exporter.ts` |
+| HALO droid + CLI | `.factory/droids/harness-optimizer.md`, `src/cli/harness.ts` |
+| Ideation droid + CLI | `.factory/droids/ideation-expert.md`, `src/cli/ideate.ts` |
+| Review gate | `src/policies/{schemas/policies/expert-review-required.md,enforcers/expert_review_required.py}` |

package/docs/architecture/PLATFORM_GATING.md

@@ -0,0 +1,68 @@
+# Platform Gating
+
+How UAP's policy gate (the DB-driven enforcement that blocks tool calls via
+`policies.db` + `.policy-tools/*.py`) is applied across each supported agent
+harness, and where harness limits make it advisory.
+
+## Install & validate
+
+```bash
+uap hooks install            # all project platforms (Hermes is global → opt-in)
+uap hooks install -t hermes  # Hermes (writes global ~/.hermes/config.yaml)
+uap hooks doctor             # audit coverage; exits non-zero on gaps
+uap setup                    # now also installs hooks (Step 7)
+```
+
+The gate script `templates/hooks/uap-policy-gate.sh` is copied into each
+platform's hooks dir and registered on that platform's pre-tool event. It reads
+the tool payload on stdin, runs the active enforcers, and blocks with `exit 2`
+(Claude convention). Hermes uses a wrapper (`uap-policy-gate-hermes.sh`) that
+translates `exit 2` into a stdout `{"decision":"block"}` JSON.
+
+## Coverage matrix
+
+| Platform | Tier | Pre-tool mechanism | Config |
+|---|---|---|---|
+| claude | ✅ gated | `PreToolUse` hooks (Edit/Write/MultiEdit, Bash, Task/Agent/…) | `.claude/settings.local.json` |
+| vscode | ✅ gated | same (Claude format) | `.claude/settings.local.json` |
+| cursor | ✅ gated | `preToolUse` array | `.cursor/hooks.json` |
+| factory | ✅ gated | `PreToolUse` hooks | `.factory/settings.local.json` |
+| opencode | ✅ gated | `tool.execute.before` plugin hook (throws to abort) | `.opencode/plugin/uap-session-hooks.ts` |
+| omp | ✅ gated | `preToolUsePolicyGate` hook | `.uap/omp/settings.json` |
+| hermes | ✅ gated | `pre_tool_call` shell hook (stdout block JSON) | `~/.hermes/config.yaml` (global) |
+| codex | ⚠️ MCP-gated | no native pre-tool hook event | `.codex/config.toml` `[mcp_servers.uap]` |
+| forgecode | ⚠️ advisory | plugin injects policy context; no block path | `.forge/forgecode.plugin.sh` |
+
+## Harness limits (why two platforms are not hard-gated)
+
+- **Codex** has no pre-tool-use *hook event*, so it can't auto-run the gate
+  before every tool. Gating is **hard** for tools routed through the UAP MCP
+  server (`execute_tool` runs the PolicyGate) and **advisory** for codex-native
+  edit/bash (run `bash .codex/hooks/uap-policy-gate.sh` per AGENTS.md). `hooks
+  doctor` reports codex as MCP-gated.
+- **ForgeCode**'s plugin surfaces session/compaction lifecycle and injects the
+  active-policy list as context, but exposes no pre-tool interception point that
+  can *block*. Reported as advisory.
+
+## Hermes specifics
+
+- Config is **global** (`$HERMES_HOME` or `~/.hermes/config.yaml`), so it is
+  excluded from the default `uap hooks install` loop and installed explicitly
+  with `-t hermes`. `hooks doctor` treats an absent `~/.hermes` as optional, and
+  a present-but-unwired install as a real gap.
+- Hermes hooks are **fail-open** (a crashing/exit-non-zero/bad-JSON hook lets the
+  tool proceed). The UAP Hermes gate therefore always exits 0 and always emits a
+  valid decision JSON, so genuine blocks are enforced.
+- Hermes prompts once to approve each hook command (stored in
+  `~/.hermes/shell-hooks-allowlist.json`); approve the UAP gate, or set
+  `hooks_auto_accept: true`.
+- Hermes has no per-file persona registry, so UAP droids are surfaced via a
+  skills bridge (`~/.hermes/uap-skills/uap-experts/SKILL.md`) that routes to
+  `uap expert-route` and the MCP `experts.<name>` tools.
+
+## Key files
+
+- Installer + doctor: `src/cli/hooks.ts` (`copyHookScripts`, `installHermesHooks`, `auditPlatform`, `hooksDoctor`, `ALL_TARGETS`).
+- Gate scripts: `templates/hooks/uap-policy-gate.sh`, `templates/hooks/uap-policy-gate-hermes.sh`.
+- MCP-router gate (codex path): `src/mcp-router/tools/execute.ts:handleExecuteTool`.
+- Setup wiring: `src/cli/setup.ts`.

package/docs/reference/EXPERT_DROIDS.md

@@ -0,0 +1,219 @@
+# Expert Droids Reference
+
+UAP ships with a 30-droid expert stack covering the full SDLC — ideation,
+strategy, design, build, review, release, and operations. Droids are markdown
+files under `.factory/droids/` discoverable by the capability router, the MCP
+router's `expert-consultation` category (virtual `experts.<name>` tools), and
+the `ExpertOrchestrator`. The forward-design / HALO / ideation extensions are
+documented in [docs/architecture/EXPERT_STACK.md](../architecture/EXPERT_STACK.md).
+
+## Quick Look
+
+```bash
+uap droids list                         # see what's installed
+uap droids validate                     # CI-grade integrity check
+uap expert-route "<task description>"   # ask for the recommended chain
+```
+
+---
+
+## Base Roster (25 droids)
+
+> The 5 forward-design / HALO / ideation droids that bring the total to 30 are
+> listed under [Forward-Design, HALO & Ideation Extensions](#forward-design-halo--ideation-extensions) below.
+
+### Strategy (3)
+
+| Droid | Role |
+|---|---|
+| `product-strategist` | Acceptance criteria, hidden constraints, PRDs |
+| `architect-reviewer` | System design validation, ADRs, blast radius |
+| `api-designer` | Contract design, versioning, schema diff authority |
+
+### Build (8)
+
+| Droid | Role |
+|---|---|
+| `typescript-node-expert` | Strict TS, ESM, Node 18+ async patterns |
+| `javascript-pro` | Modern ES2023+, browser + Node |
+| `python-pro` | Type-safe Python 3.11+, async, packaging |
+| `rust-pro` | Ownership, lifetimes, async/await with Tokio |
+| `go-pro` | Idiomatic concurrency, errgroup, context |
+| `cli-design-expert` | Verb/noun discipline, exit codes, stdout/stderr split |
+| `debug-expert` | Root cause analysis, dependency conflicts |
+| `refactoring-specialist` | Behavior-preserving transformations |
+
+### Quality (4)
+
+| Droid | Role |
+|---|---|
+| `code-quality-guardian` | Full-file structural review, smells, metrics |
+| `code-quality-reviewer` | Per-diff quality with citations |
+| `security-auditor` | Full OWASP audit, secret detection, sec-context |
+| `security-code-reviewer` | Per-diff security regressions, CWE-cited |
+
+### Performance & Cost (3)
+
+| Droid | Role |
+|---|---|
+| `performance-optimizer` | Full perf analysis, bottleneck identification |
+| `performance-reviewer` | Per-diff regressions, N+1, allocation hotspots |
+| `cost-engineer` | Cloud spend modeling, FinOps, observability cost |
+
+### Testing & QA (4)
+
+| Droid | Role |
+|---|---|
+| `test-strategist` | Pyramid design, coverage targets, technique selection |
+| `test-plan-writer` | Authors test plans + scaffolds from acceptance criteria |
+| `test-coverage-reviewer` | Verifies new behavior is exercised |
+| `qa-expert` | Flaky test triage, regression bisect, release sign-off |
+
+### Documentation (2)
+
+| Droid | Role |
+|---|---|
+| `documentation-expert` | Authors comprehensive docs, READMEs, API docs |
+| `documentation-accuracy-reviewer` | Per-diff doc drift, broken examples |
+
+### Operations (5)
+
+| Droid | Role |
+|---|---|
+| `release-manager` | Semver decisions, CHANGELOG, deploy batch priority |
+| `compliance-officer` | Policy authoring, regulatory mapping, waivers |
+| `incident-responder` | War-room coordination, postmortems, runbooks |
+| `observability-engineer` | Logs/metrics/traces, SLOs, cardinality |
+| `dependency-auditor` | Supply chain, slopsquatting, CVE workflow |
+
+### Specialty (3)
+
+| Droid | Role |
+|---|---|
+| `ml-training-expert` | Model training, dataset processing, MTEB |
+| `sysadmin-expert` | Linux kernel, QEMU, networking, systemd |
+| `terminal-bench-optimizer` | Meta-orchestrator for benchmark tasks |
+| `accessibility-tester` | WCAG 2.2 AA, keyboard nav, screen readers |
+
+---
+
+## Routing
+
+The `ExpertOrchestrator` composes droid chains across five phases:
+
+```
+plan → design → implement → review → release
+```
+
+Each phase pulls from a roster but only includes droids relevant to the
+matched capabilities. Review-phase droids run in parallel.
+
+```bash
+# CLI surface
+uap expert-route "Add rate limiting to /api/login" --files src/auth/login.ts
+
+# JSON output (machine-readable, scriptable)
+uap expert-route "..." --json
+```
+
+Programmatic surface:
+
+```typescript
+import { ExpertOrchestrator } from '@miller-tech/uap/coordination/expert-orchestrator';
+
+const orch = new ExpertOrchestrator({
+  successRateFor: (droid) => adaptivePatterns.successRate(droid),
+});
+
+const plan = orch.plan(task, affectedFiles);
+for (const step of plan.steps) {
+  console.log(`${step.phase}: ${step.droid} (${step.parallel ? 'parallel' : 'sequential'})`);
+}
+```
+
+---
+
+## MCP Router Surface
+
+Every droid is exposed as a virtual MCP tool under the `experts` server,
+discoverable via the standard `discover_tools` interface. This preserves
+the 98% token-savings shape (just 2 meta tools exposed to the LLM).
+
+```typescript
+import { loadExpertTools } from '@miller-tech/uap/mcp-router';
+
+const tools = loadExpertTools(process.cwd());
+// tools[].serverName === 'experts'
+// tools[].name === '<droid-name>'
+
+// In the MCP router's tool index:
+index.addTools(tools);
+const matches = index.search('security review for auth code');
+// → [{ path: 'experts.security-auditor', ... }]
+```
+
+---
+
+## Authoring a New Droid
+
+1. Create `.factory/droids/<name>.md` with frontmatter:
+   ```yaml
+   ---
+   name: <droid-name>
+   description: <one-line summary, ≥5 chars>
+   model: inherit
+   coordination:
+     channels: ["review"]
+     claims: ["shared"]
+     batches_deploy: true
+   ---
+   ```
+2. Body sections: Mission, MANDATORY Pre-Checks, PROACTIVE ACTIVATION,
+   protocol/checklist, output shape, coordination notes.
+3. If routable: add entry to `DEFAULT_CAPABILITY_MAPPINGS` in
+   `src/coordination/capability-router.ts`.
+4. Run `uap droids validate` to confirm integrity.
+5. CI gate (`droids validate` step) will block merge if anything is off.
+
+See [`.factory/droids/code-quality-guardian.md`](../../.factory/droids/code-quality-guardian.md)
+for a canonical example.
+
+---
+
+## Forward-Design, HALO & Ideation Extensions
+
+Added on top of the base roster (see
+[docs/architecture/EXPERT_STACK.md](../architecture/EXPERT_STACK.md)):
+
+| Droid | Phase | Role |
+|---|---|---|
+| `strategic-architect` | plan | North-star architecture, technology selection, multi-quarter evolution (forward-design counterpart to `architect-reviewer`) |
+| `tactical-architect` | design | Concrete component boundaries, interfaces, data shapes, pattern selection |
+| `implementation-planner` | design | Executable work breakdown: steps, file plan, test plan, rollback |
+| `ideation-expert` | ideate | open-collider divergent ideation (bisociation) feeding plan/design |
+| `harness-optimizer` | review | HALO loop — diagnoses systemic harness failures from execution traces |
+
+## Policy Hooks
+
+| Policy | Level | Droid authority |
+|---|---|---|
+| `architecture-review` / `architecture-review-required` | REQUIRED | `architect-reviewer` |
+| `expert-review-required` | REQUIRED | parallel-expert-review reviewers |
+| `acceptance-criteria-defined` | RECOMMENDED | `product-strategist` |
+| `observability-required` | RECOMMENDED | `observability-engineer` |
+
+Architecture-review policy is enforced by
+`src/policies/enforcers/<uuid>_architecture_review.py` — blocks PR-ready
+operations on qualifying diffs unless an ADR or active waiver is present (backed
+by `architecture-review.md`). The `expert-review-required` policy
+(`expert_review_required.py`) blocks ship actions until a parallel review
+artifact `.uap/reviews/<branch>.json` covers HEAD.
+
+---
+
+## Related
+
+- [PARALLEL REVIEW PROTOCOL skill](../../.factory/skills/parallel-expert-review/SKILL.md)
+- [Capability Router](../../src/coordination/capability-router.ts)
+- [Expert Orchestrator](../../src/coordination/expert-orchestrator.ts)
+- [MCP Router expert registry](../../src/mcp-router/experts/registry.ts)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@miller-tech/uap",
-  "version": "1.22.0",
+  "version": "1.26.1",
   "description": "Autonomous AI agent memory system with CLAUDE.md protocol enforcement",
   "type": "module",
   "main": "dist/index.js",

package/templates/hooks/pre-tool-use-edit-write.sh

@@ -3,11 +3,17 @@
 # Event: PreToolUse (matcher: Edit|Write)
 # Exit 2 = BLOCK the edit/write. Exit 0 = allow.
 # Enforces: worktree-file-guard, worktree-enforcement policies.
+#
+# Scope: ONLY enforces inside the project repo (resolved via `git rev-parse
+# --show-toplevel` from PWD). Files outside the repo (e.g. ~/.claude/projects/
+# memory area, /tmp scratch, system files) are always allowed — the worktree
+# policy governs repo-tracked work only. See: _hook-fix-2026-04-29.
 set -euo pipefail
 
 # --- Loop Protection: track frequency of blocking events ---
 HOOK_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 if [ -f "${HOOK_DIR}/loop-protection.sh" ]; then
+  # shellcheck disable=SC1091
   source "${HOOK_DIR}/loop-protection.sh"
 fi
 
@@ -22,7 +28,25 @@ if [ -z "$FILE_PATH" ]; then
   exit 0
 fi
 
-# Exempt paths — runtime data, not source code
+# Resolve to canonical absolute path. -m allows the file to not exist yet
+# (common for Write to a new file).
+ABS_PATH="$(realpath -m "$FILE_PATH" 2>/dev/null || printf '%s' "$FILE_PATH")"
+
+# Resolve repo root from current working directory. If cwd is not inside a
+# git repo at all, allow — there's no worktree policy to enforce.
+REPO_ROOT="$(git rev-parse --show-toplevel 2>/dev/null || true)"
+if [ -z "$REPO_ROOT" ]; then
+  exit 0
+fi
+
+# Scope guard (the regression fix): if the file being edited is outside the
+# repo root, always allow. The worktree policy only applies to in-repo files.
+case "$ABS_PATH" in
+  "$REPO_ROOT"/*) : ;;       # inside repo — continue to in-repo checks
+  *) exit 0 ;;               # outside repo — allow
+esac
+
+# Exempt paths — runtime data, not source code (substring match, intentional)
 EXEMPT_PATTERNS=(
   "agents/data/"
   "node_modules/"
@@ -30,23 +54,20 @@ EXEMPT_PATTERNS=(
   ".uap/"
   ".git/"
   "dist/"
-  "/tmp/"
-  "/dev/"
 )
 
 for pattern in "${EXEMPT_PATTERNS[@]}"; do
-  if echo "$FILE_PATH" | grep -q "$pattern"; then
+  if echo "$ABS_PATH" | grep -q "$pattern"; then
     exit 0
   fi
 done
 
-# Allow if path is inside a worktree
-if echo "$FILE_PATH" | grep -q '\.worktrees/'; then
+# Allow if path is inside a worktree (substring match, handles nested worktrees)
+if echo "$ABS_PATH" | grep -q '\.worktrees/'; then
   exit 0
 fi
 
-# BLOCK: path is outside worktrees and not exempt
-# Record the block event for loop detection
+# BLOCK: path is inside the repo, not in a worktree, not exempt.
 if type lp_record_invocation &>/dev/null; then
   lp_record_invocation "pre-tool-edit-block"
 fi

package/templates/hooks/uap-policy-gate-hermes.sh

@@ -0,0 +1,42 @@
+#!/usr/bin/env bash
+# UAP policy gate — Hermes Agent (NousResearch) variant.
+#
+# Hermes `pre_tool_call` hooks decide via a JSON object on STDOUT, and are
+# FAIL-OPEN: a non-zero exit, timeout, or malformed JSON only logs a warning and
+# lets the tool proceed. The shared uap-policy-gate.sh instead signals a block
+# with `exit 2` (Claude Code convention), which Hermes would ignore.
+#
+# This wrapper runs the shared gate and TRANSLATES its verdict into the Hermes
+# contract: it always exits 0 and always prints valid JSON —
+#   {"decision":"block","reason":"…"}   when the gate blocks (exit 2)
+#   {}                                   otherwise (allow)
+# so a real block is reliably enforced rather than silently failing open.
+#
+# Hermes stdin payload: {"hook_event_name":"pre_tool_call","tool_name":...,
+# "tool_input":{...},"session_id":...,"cwd":...}. uap-policy-gate.sh reads the
+# same tool_name/tool_input fields, so the payload is passed through unchanged.
+
+set -o pipefail
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+GATE="$SCRIPT_DIR/uap-policy-gate.sh"
+
+PAYLOAD="$(cat)"
+
+# No shared gate present → allow (fail-open, consistent with non-UAP repos).
+if [ ! -f "$GATE" ]; then
+  echo '{}'
+  exit 0
+fi
+
+STDERR_FILE="$(mktemp 2>/dev/null || echo /tmp/uap-hermes-gate.$$)"
+printf '%s' "$PAYLOAD" | bash "$GATE" >/dev/null 2>"$STDERR_FILE"
+CODE=$?
+REASON="$(tr -d '\r' < "$STDERR_FILE" | tr '\n' ' ' | sed 's/\\/\\\\/g; s/"/\\"/g')"
+rm -f "$STDERR_FILE" 2>/dev/null || true
+
+if [ "$CODE" -eq 2 ]; then
+  printf '{"decision":"block","reason":"%s"}\n' "${REASON:-blocked by UAP policy}"
+else
+  echo '{}'
+fi
+exit 0