feat(audit): emit guardrail_check on every mask/block/warn with opt-in evidence (closes #155)

[initializ-mk]

Summary

• The AuditGuardrail constant has been defined since FWS-7 but never emitted. LibraryGuardrailEngine logged redactions to the ops logger and that was it — operators tailing the audit socket / stderr NDJSON saw zero guardrail events. Docs claimed otherwise.
• This PR wires the audit logger into the engine and emits guardrail_check at every mask / block / warn site (inbound, outbound, tool_output × decision).
• Adds an opt-in evidence-capture knob so operators who need the offending text (false-positive triage, compliance proof) can flip a flag without changing the default metadata-only posture. Same shape as the OTel content-capture posture in OTel: honor capture_content + redact on span attributes (reuse FWS-8 audit redactor) #130.

Wire diagram

A2A request
  ├─ ctx { correlation_id, task_id, seq, workflow_* }
  ↓
guardrails.CheckInbound(ctx, msg)
  ├─ library InputGate → Result{Decision, Violations, MaskedContent}
  ├─ on Mask/Block: engine.emitGuardrailEvent(ctx, ...)
  │    ├─ build fields {direction, decision, guardrail, category, violation_count, [tool], [evidence]}
  │    ├─ evidence = prepareEvidence(originalText, cfg)   ← only when CaptureEvidence=true
  │    │            (redactSecrets → TruncateForAudit)
  │    └─ auditLogger.EmitFromContext(ctx, AuditEvent{Event: AuditGuardrail, Fields: ...})
  ↓
stderr safety net + (FORGE_AUDIT_SOCKET / FORGE_AUDIT_HTTP_ENDPOINT)

Default event shape (metadata-only)

{
  "ts": "2026-06-14T10:00:00Z",
  "event": "guardrail_check",
  "schema_version": "1.0",
  "seq": 2,
  "correlation_id": "fd111edd27c20101",
  "task_id": "slack-...",
  "fields": {
    "direction": "inbound",
    "decision": "masked",
    "guardrail": "pii",
    "category": "ssn",
    "violation_count": 1
  }
}

With evidence capture on (FORGE_GUARDRAIL_CAPTURE_EVIDENCE=true)

{
  "ts": "...",
  "event": "guardrail_check",
  "fields": {
    "direction": "inbound",
    "decision": "masked",
    "guardrail": "pii",
    "category": "ssn",
    "violation_count": 1,
    "evidence": "verify SSN 123-45-6789 with token [REDACTED] please"
  }
}

The [REDACTED] marker matches FWS-8's marker so audit consumers see one consistent token across both pipelines. The same regex set as the bundled secret rules is used for the defense-in-depth scrub.

Config knobs

Env var	Default	Meaning
FORGE_GUARDRAIL_CAPTURE_EVIDENCE	false	Include fields.evidence in the emitted event
FORGE_GUARDRAIL_REDACT	true	Run vendor-secret regex scrub before emission
FORGE_GUARDRAIL_MAX_BYTES	4096	Soft cap; overage truncated with …[truncated:N]

Behavior matrix

Direction	Decision	Audit emitted?	Result string
inbound	Mask	yes	masked
inbound	Block + warn mode	yes	warned
inbound	Block + enforce mode	yes (then error returned)	blocked
outbound	Mask	yes	masked
outbound	Block + warn mode	yes	warned
outbound	Block + enforce mode	yes (then error returned)	blocked
tool_output	Mask	yes	masked
tool_output	Block + warn mode	yes	warned
tool_output	Block + enforce mode	yes (then error returned)	blocked

Files

• forge-core/runtime/guardrails.go — interface now takes context.Context
• forge-core/runtime/guardrails_test.go — updated to match
• forge-cli/runtime/guardrails_audit.go — new — GuardrailAuditConfig, redact pipeline, emitGuardrailEvent helper
• forge-cli/runtime/guardrails_engine.go — calls emit at all 7 sites, WithAuditLogger for wiring
• forge-cli/runtime/guardrails_loader.go — BuildGuardrailChecker now takes (auditLogger, auditCfg)
• forge-cli/runtime/guardrails_engine_test.go — 4 new tests: inbound-mask emits, evidence omitted by default, prepareEvidence (table-driven), truncation cap
• forge-cli/runtime/runner.go — reordered audit-logger / guardrails construction, ctx threaded into all 7 call sites
• docs/security/guardrails.md — new Audit Events section with full schema + opt-in evidence table
• docs/security/audit-logging.md — updated guardrail_check row
• .claude/skills/forge.md — updated audit-event reference row

Test plan

• go test ./... clean in forge-core and forge-cli
• golangci-lint run ./... → 0 issues in all three modules
• gofmt -w applied
• End-to-end smoke: start socket listener (socat -u UNIX-LISTEN:/tmp/forge-audit.sock,fork -), run agent with FORGE_AUDIT_SOCKET=/tmp/forge-audit.sock, send PII-bearing message, confirm guardrail_check event appears alongside session_*, llm_call, invocation_complete
• With FORGE_GUARDRAIL_CAPTURE_EVIDENCE=true, confirm fields.evidence is present and a secret-shaped substring in the prompt is replaced with [REDACTED]
• With FORGE_GUARDRAIL_CAPTURE_EVIDENCE=false (default), confirm fields.evidence is absent

Closes #155