# Upgrade Guide — v0.17.0

<!-- bump: minor -->

## What Changed

### Coherence Gate (Response Review Pipeline)

An LLM-powered response review pipeline that evaluates every outbound agent message before it reaches users. Catches tone issues, fabricated claims, capability inaccuracies, information leakage, and value misalignment — before the user ever sees them.

The pipeline has three layers:

1. **Policy Enforcement Layer (PEL)** — Deterministic hard blocks. Catches credentials, PII, auth tokens, and schema violations without any LLM call. Zero-latency, zero-cost. Always active, even when the full pipeline is disabled.
2. **Gate Reviewer** — Fast LLM triage. Determines if a message needs full specialist review or can pass through. Most messages skip full review.
3. **9 Specialist Reviewers** — Parallel LLM calls checking specific dimensions:
   - Conversational Tone (no code dumps, no command pasting)
   - Claim Provenance (every claim traceable to tool output)
   - Settling Detection (catches when agent accepts failure too easily)
   - Context Completeness (ensures relevant context was considered)
   - Capability Accuracy (verifies feature claims against live system)
   - URL Validity (catches fabricated URLs)
   - Value Alignment (checks against AGENT.md values)
   - Information Leakage (prevents exposing internal details)
   - Custom reviewers loadable from `.instar/reviewers/`

Key design decisions:
- **15-row normative decision matrix** for deterministic pipeline state handling
- **Per-channel configuration** — Telegram, WhatsApp, and direct each have their own fail behavior (fail-open for chat, fail-closed for email)
- **Retry tracking** with conversation advancement detection
- **Observe-only mode** for gradual rollout — see what the gate would catch without blocking anything
- **Claude Code Stop hook integration** — reviews happen automatically via the hook system
- **Full observability** — audit logs, decision history, canary endpoint
- **Adaptive trust integration**

Configuration in `.instar/config.json`:
```json
{
  "responseReview": {
    "enabled": true,
    "observeOnly": false,
    "gateModel": "claude-haiku-4-5-20251001",
    "reviewerModel": "claude-haiku-4-5-20251001",
    "maxRetries": 2,
    "timeoutMs": 10000,
    "channels": {
      "telegram": { "failOpen": true },
      "whatsapp": { "failOpen": true }
    }
  }
}
```

Requires `ANTHROPIC_API_KEY` in environment for LLM-based reviewers.

### ScopeVerifier Rename

The pre-action scope verification system (previously named CoherenceGate) has been renamed to ScopeVerifier. The CoherenceGate name now belongs to the response review pipeline, matching the spec. Backward-compatible type aliases are maintained in the npm exports — no agent-side changes required.

### PlatformProbe

New system reviewer probe for monitoring platform-level health metrics.

### JobScheduler Machine-Scoped Improvements

Better machine identity filtering for multi-machine job scheduling. Jobs now filter more accurately by machine when running across paired devices.

### Test Coverage

~270 new tests across 9 test files: CoherenceGate, CoherenceGateCanary, CoherenceGateE2E, CoherenceGateHook, CoherenceGateObservability, PolicyEnforcementLayer, CoherenceReviewer, CustomReviewerLoader, and RecipientResolver.

## What to Tell Your User

- **"Your agent now reviews its own messages before sending them."** Every outbound message passes through a quality gate. If the agent is about to send something with a fabricated URL, dump terminal commands at you, or leak internal details — the gate catches it and the agent rewrites.
- **"It's off by default — I can turn it on when you're ready."** There's an observe-only mode too, so you can see what it would catch without actually blocking anything.
- **"The credential and PII scanner is always on."** Even without the full pipeline, the deterministic layer blocks sensitive data from ever appearing in outbound messages.
- **"It works with all messaging channels."** Telegram, WhatsApp, direct — each channel can have its own behavior.

## Summary of New Capabilities

| Capability | How to Use |
|-----------|-----------|
| Coherence Gate | Set `responseReview.enabled: true` in config |
| Observe-only mode | Set `responseReview.observeOnly: true` to audit without blocking |
| PEL (deterministic blocks) | Always active — no configuration needed |
| Per-channel fail behavior | Configure `responseReview.channels` per channel |
| Custom reviewers | Add reviewer files to `.instar/reviewers/` |
| Canary endpoint | Check pipeline health via the canary API |
| Audit logs | Full decision history for every reviewed message |
