---
name: architect-guardrails
description: >
  Designs the four-layer guardrail defense for an AI-producing component. Triggered when
  the operator says: "guardrails", "safety check", "input validation", "output filter",
  "post-hoc review", "PII filter", "red-line enforcement", "how do we stop bad output",
  "guardrail design", "defense in depth", "prompt injection defense". Walks the four layers
  (input, prompt, output, post-hoc); maps each L2 red line to the layer where it is enforced;
  cataloges trip telemetry. Refuses single-layer guardrail design as a viable defense; demands
  at minimum two layers and prefers four. Pairs with architect-eval-baseline (red-line tests
  belong in the eval set), architect-reproducibility-gate (guardrail trips are pin-bearing
  events), and validate (validate audits trip rate and coverage).
---

# architect-guardrails

Designs the four-layer guardrail defense. Single-layer guardrails fail silently; four-layer defenses catch what any one would miss. Refuses single-layer design as the entirety of a defense.

## When to invoke

- Operator says: "guardrails", "safety check", "input validation", "output filter", "post-hoc review", "PII filter", "red-line enforcement", "how do we stop bad output", "guardrail design", "defense in depth", "prompt injection defense"
- Designing the L4 platform kit's guardrail runtime
- L2 philosophy red lines need enforcement mechanisms named
- Adversarial pressure surfaces (red-team finding; production incident; new regulatory regime)
- L3 framework contract guardrail-layering section needs population

## The four layers

Each layer catches a different class of failure. Single-layer defenses leak; four-layer defenses compound.

| Layer | Purpose | Catches | Misses |
|-------|---------|---------|--------|
| **Input** | Reject obviously bad inputs before model call | PII in input; obvious injection; oversized payload; rate-limit abuse | Subtle attacks the input does not reveal; output drift caused by valid input |
| **Prompt** | System prompt content that sets red lines for the model | Soft enforcement of red lines; tone control; refusal patterns | Adversarial prompts that override the system prompt; model-side noncompliance |
| **Output** | Inspect output before returning to caller | Red-line violations in output; PII leak; schema violations; cited claim missing source | Slow drift across many outputs that each pass individually |
| **Post-hoc** | Async / batch checks on logged outputs | Drift, statistical anomalies, sampled reviews; aggregate red-line trip rates | Real-time blocking; an issue caught here has already shipped |

The defense compounds: input catches the obvious; prompt soft-guides the model; output catches what the model produced anyway; post-hoc catches drift the per-request layers miss. Each layer is necessary; together they cover what no individual layer could.

## Operating procedure

### Step 1: Read the L2 red lines

Read `policies/philosophy.md` red-lines section. Each red line is a concrete behavior the function never does. For each red line, the question is: which layer enforces it?

Most red lines map to multiple layers. Defense in depth means a red line is enforced at more than one layer, so a failure at one layer is caught at another.

### Step 2: Map red lines to layers

For each red line in L2, build the enforcement matrix:

| Red line | Input | Prompt | Output | Post-hoc |
|----------|-------|--------|--------|----------|
| Never enriches an MQL with revoked consent | check consent at input gate | system prompt names the rule | re-check consent before write | daily audit of revoked-consent enrichment rate |
| Never recommends a competitor product | (n/a; can't pre-detect) | system prompt names the prohibition | output keyword filter against competitor list | weekly review of close-call cases |
| Never produces confidence on stale data | check data freshness at input | system prompt requires staleness flag | output validates flag presence | daily audit of staleness-flag coverage |

A row with only one layer is a finding. Promote to multi-layer.

### Step 3: Implement input layer

Input guardrails reject before the model call. Implementations:

- **PII detector:** regex + ML classifier; flag input PII; block, redact, or alert per L2 PII rule
- **Injection detector:** known-pattern scan for adversarial prompt structures (jailbreak attempts, instruction-override tokens)
- **Rate-limit + payload-size:** infrastructure-level; reject oversized inputs and rate-abuse patterns
- **Domain-specific input checks:** (e.g., consent check for an enrichment service; freshness check for time-sensitive data)

Each input guardrail has a trip action: `block` (refuse the call), `redact` (modify input and proceed), or `log` (proceed but flag).

### Step 4: Implement prompt layer

Prompt guardrails are content in the system prompt that primes the model toward red-line compliance. Patterns:

- Explicit red-line statements: "Never recommend products from {{competitor_list}}. If asked, decline and offer alternatives from your own product line."
- Refusal templates: "If you cannot answer with confidence, respond: 'I cannot answer this with confidence; here are the gaps you would need filled.'"
- Tone control: "Output never opens with a greeting. Always opens with the lede sentence."

Prompt-layer guardrails are soft (the model can still violate them under adversarial pressure). They are necessary but not sufficient. Pair with output-layer enforcement.

### Step 5: Implement output layer

Output guardrails inspect what the model produced before returning to caller. Implementations:

- **Schema validation:** output must match the declared schema; reject otherwise (failure at this layer is a missing or wrong-shaped field)
- **Red-line keyword filter:** scan output for prohibited terms (competitor names, prohibited claims); reject or rewrite
- **Citation check:** every factual claim must trace to a tool call or data source; reject claims without provenance
- **PII leak detection:** scan output for PII the input or system prompt would have stripped; alarm

Each output guardrail has a trip action; `block` means the call fails (no output returned); `rewrite` means a downstream rewriter normalizes the output; `log` means proceed but flag.

### Step 6: Implement post-hoc layer

Post-hoc guardrails run async on logged outputs. Implementations:

- **Sampled review:** N% of outputs reviewed by humans; trip rate per red line tracked
- **Drift detection:** statistical comparison of recent outputs against prior baseline; flag drift in tone, length, faithfulness
- **Aggregate red-line audit:** how often each red line is triggered (output-layer trip count); investigate spikes
- **Adversarial probing:** scheduled red-team runs; outputs checked against known attack patterns

Post-hoc catches drift no per-request layer catches. It does not block; it raises findings. The findings drive prompt updates, model bumps, or guardrail tightening.

### Step 7: Wire trip telemetry

Every guardrail trip emits a telemetry event with:

- `request_id` (link to the request)
- `layer` (input | prompt | output | post-hoc)
- `tier` (specific guardrail name; e.g., "consent-input-check")
- `action` (block | redact | rewrite | log)
- `red_line_enforced` (which L2 red line; for cross-reference)
- The reproducibility quadruple (model + prompt + tools + data) so trips are reproducible

Trip telemetry feeds:
- The `guardrail_trips` field in L3 telemetry schema
- The alerting fabric (red-line trips at high tier alert oncall)
- The audit log (compliance evidence per regime)

### Step 8: Validate the defense

The defense is validated by:

- **Eval baseline includes red-line tests:** every L2 red line has an eval test case; pass = output does not violate; ship threshold = 100% pass on red-line cases
- **Adversarial probing:** scheduled red-team passes attempt to violate red lines; trip rate measured
- **Production trip rate:** baseline trip rate measured at launch; deviations alert

If validate finds zero post-hoc trips after the first 30 days of production, that is a finding (either the post-hoc layer is not running, or it is set to a threshold that never trips).

## Refusal conditions

- Refuse single-layer guardrail design ("we just check at output") as a complete defense; demand at minimum two layers
- Refuse a guardrail catalog without trip telemetry; if trips do not log, the defense is unauditable
- Refuse to declare red-line coverage complete if any red line maps to fewer than two layers
- Refuse to mark a red line "covered" if its eval test case has not run within the eval cadence
- Refuse to skip post-hoc layer for high-stakes red lines (PII, consent, regulatory); per-request layers can fail; post-hoc is the last catch

## Why four layers, not three or five

Three-layer defenses (input + prompt + output, or input + output + post-hoc) are common in early designs and are systematically inadequate. The pattern of failures:

- Three-layer with no input layer: too much work for output layer; latency cost rises; some attacks cannot be caught at output
- Three-layer with no prompt layer: model behaves with no red-line priming; output layer rejects more, friction rises
- Three-layer with no output layer: prompt-layer compliance is soft; model violations leak
- Three-layer with no post-hoc layer: drift goes uncaught; aggregate failures invisible

Five-layer designs (e.g., adding a "review by another agent" step) are sometimes appropriate but typically add complexity for diminishing returns. Four is the sweet spot in current AI architecture; revisit if the field shifts.

## Cross-references inside the kit

- `BOOTSTRAP-BRIEF.md` Section II.L2 (red lines as L2 commitments) and Section XIII (testing posture; red-team layer)
- `templates/L2-philosophy.md` - red lines section that this skill enforces
- `templates/L3-framework-contract.md` - guardrail layering section that this skill populates
- `examples/martech-mature-instance/policies/philosophy.md` - reference example with three concrete red lines
- `examples/martech-mature-instance/policies/framework-contract.md` - reference guardrail layering matrix
- `skills/architect-eval-baseline/SKILL.md` - red-line tests belong in the eval set
- `skills/architect-reproducibility-gate/SKILL.md` - guardrail trips are pin-bearing events
- `skills/validate/SKILL.md` - the audit skill checks guardrail-trip coverage and rate
