gemstone-nexus · Phase 6

DOC — GemStoneGuardRails

← Documents

Metadata

iddoc_idtitlecategorysource_pathsummarycontent_hashindexed_at
47DOC-GEMSTONEGUARDRAILSDOC — GemStoneGuardRailsreferenceDevResources/docs/DOC-GemStoneGuardRails.mdBefore GemStone answers (sovereign chat, Gemini Live, or ledger RAG), it checks **GemStoneGuardRails**. If the user question matches a rule (exact or inferred similarity), GemStone returns the **fixed response** — no freelancing.d0c4de025d4d1ddb3d03ec6c84fbba1d1b33755e2026-08-06 18:37:27

Content

# DOC — GemStoneGuardRails

*Mandatory framing pack · passcode-gated rule adds · SuperAdmin-managed*

**Product name:** `GemStoneGuardRails` (exact)

## Purpose

Before GemStone answers (sovereign chat, Gemini Live, or ledger RAG), it checks **GemStoneGuardRails**. If the user question matches a rule (exact or inferred similarity), GemStone returns the **fixed response** — no freelancing.

**Dev (External) / development mode:** hard short-circuit is **off by default** (`GUARDRAILS_HARD_ENFORCE_IN_DEV=false`). Research and general Q&A are answered normally; framing is soft. Set `GUARDRAILS_HARD_ENFORCE_IN_DEV=true` to force fixed responses in Dev. **Sovereign** always hard-enforces.

Matcher rejects short/generic substring hijacks (`this`, `application`, …) so long research prompts are not blocked by accidental trigger overlap.

## Seed rule

| Triggers (examples) | Fixed response |
| --- | --- |
| who created this / who built this / who made GemStone / similar | `GemStone was created by Mark Furiate and is part of the DataRight Horizon family of products.` |

## Add / update rules

1. User says e.g. `add to GemStoneGuardRails when … say …`
2. GemStone asks for the personal passcode
3. Passcode verified (hashed compare) → rule stored
4. Wrong / missing passcode → refuse (no write)

MCP / HTTP tools:

- `POST /mcp/guardrails_match` — `{ "query": "…" }`
- `GET|POST /mcp/guardrails_list`
- `POST /mcp/guardrails_add` — `{ "passcode", "triggers", "response" }` (passcode required)

## Who may manage what

| Action | Who |
| --- | --- |
| Add rules (with passcode) | Passcode holder; future: users with `guardrails_contributor` + passcode |
| Create/rotate passcode | **SuperAdmin only** (`PUT /api/admin/guardrails/passcode`) |
| Grant `guardrails_contributor` | **SuperAdmin only** |
| Org Admin | May list rules in Admin UI; **cannot** manage passcode or contributors |

Passcode storage: salted hash in Postgres (`gemstone_guardrails_meta`), same PBKDF2-SHA256 scheme as local user passwords. Optional first-boot seed from env `GEMSTONE_GUARDRAILS_PASSCODE` (plaintext never committed; discarded after hash). SuperAdmin can rotate anytime under `/app/admin` → **guardrails**.

## Injection points

1. Sovereign / Gemini chat — short-circuit **before** ledger RAG
2. `gather_context` — framing block prepended ahead of ledger / packs / Atlas
3. Gemini Live — system instruction + `guardrails_*` tools before ledger tools

## Admin UI

`/app/admin` → tab **guardrails**: list rules; **Edit** / **Save** / **Delete** (Cancel while editing) on existing rules via SuperAdmin JWT (`PATCH` / `DELETE /api/admin/guardrails/rules/{id}` — no passcode).

**Delete** opens an explicit confirm: **Inactivate** (soft `is_active=false`) vs **Remove permanently** (`DELETE ?permanent=true` hard-deletes the row) vs Cancel. Inactive rows can be **Reactivated** (`POST …/reactivate`).

**Add** still requires the passcode (`POST /mcp/guardrails_add`). The API rejects normalized duplicates (trim / collapse whitespace / case-insensitive triggers+response): active → 409 `duplicate_active`; inactive → 409 `duplicate_inactive` with `rule_id` so Admin can reactivate instead of creating another row.

SuperAdmin set/rotate passcode; grant/revoke contributor flag on users.

## Migration

Alembic `0010_gemstone_guardrails` (additive): rules table, meta table, `users.guardrails_contributor`.

## Smoke

1. Ask: `Who created this application?` → Mark Furiate / DataRight Horizon line
2. `add to GemStoneGuardRails …` without passcode → prompt / refuse write
3. Add with correct passcode → rule listed; subsequent match returns fixed text

Auth0 remains deferred.

## Boundary vs practitioner personal rules

`GemStoneGuardRails` is **product-wide** (passcode + SuperAdmin). Practitioner personal rules are a separate Atlas segment — see [`DOC-Practitioner-Rules.md`](./DOC-Practitioner-Rules.md) (MVP shipped).

| Concern | GemStoneGuardRails (now) | Practitioner personal rules (MVP) | HorizonIQ (later) |
| --- | --- | --- | --- |
| Scope | Product framing for all users | Personal Atlas segment only | Org-wide shared practitioner rules |
| Passcode | SuperAdmin passcode required to add | **No** passcode | Passcode gate on personal rules (deferred) |
| Merge / promote | N/A | Does not write into GuardRails | “Make that a rule” → GuardRails (deferred) |
| Approvals | Passcode gate | **keep original** vs **use new** via chat or voice; user must be signed in | — |
| Phrase | `add to GemStoneGuardRails …` | **Make that a rule** | — |

See punchlist: `DOC07-Punchlist.md` → Practitioner personal rules + **HorizonIQ (later)**.