| name | governance-compliance |
| description | Audit logging, quality gates, and ethics procedures for the agent team. Use for periodic compliance reviews, when logging task completion events, or when an ethical concern arises that requires human escalation. |
| role | worker |
| user-invocable | true |
Governance & Compliance
Overview
Requirements and procedures for audit logging, multi-layer quality assurance, and ethical operation of the agent team. Ensures all agent activity is traceable, quality is validated at multiple levels, and ethical principles are maintained.
Constraints
- The audit changelog is append-only; never modify or delete existing entries
- Never log credentials, API keys, or PII in
.claude/metrics/ or .claude/memory/ files
- All agent decisions must be explainable on request — no black-box outputs
- Ethical concerns are never auto-resolved; always escalate to the human
Audit & Transparency
What Must Be Logged
| Event | Log Location | Retention |
|---|
| Task start/completion | .claude/metrics/{date}-task-log.jsonl | 90 days |
| Configuration change | .claude/metrics/config-changelog.jsonl | Indefinite |
| Human approval/override | .claude/metrics/config-changelog.jsonl — proposed/evidence_shown/risks_surfaced required (schema: human-oversight-protocol § Audit trail) | Indefinite |
| Hallucination detection | Task log entry (hallucination_detected flag) | 90 days |
| Context summarization | .claude/memory/{date}-{task-slug}.md | 90 days (30 active + 60 archive) |
Audit Trail Principles
- Append-only: Log entries are never modified or deleted
- Timestamped: Every entry has an ISO 8601 timestamp
- Attributed: Every entry identifies which agent acted and who approved
- Complete: No decision-making gap should exist between log entries
- Reconstructable: For every
approval/override gate-decision entry, the
decision, the proposal, the evidence, and the surfaced risks must all be
recoverable from the entry alone — see human-oversight-protocol § Audit trail
for the field schema. Entries predating this schema (no proposed/evidence_shown/
risks_surfaced) remain valid — never migrated — and are not reconstructable
to this standard; treat them as historical, not as a compliance gap.
Compliance Queries
To answer "why did the system do X?", trace through:
- Task log: which agents were involved
- Config changelog: what configuration was active at the time
- Memory summaries: what context the agents were working with
For a gate decision specifically ("what was this approval/override based on?"),
also check gate-record completeness: does the approval/override entry carry
proposed, evidence_shown, and risks_surfaced? An entry missing all three is
either a pre-schema entry (acceptable) or a write site that skipped the schema
(a gap — see human-oversight-protocol's Audit trail for the required write
sites).
Quality Assurance
Multi-Layer Validation
Quality is enforced at four progressive layers:
Layer 1: Agent Self-Validation
- Every agent applies the Quality Gate Pipeline before delivering output
- Confidence scoring on all major claims
- Tool-based verification for factual claims (file paths, APIs, data)
Layer 2: QA Agent Validation
When applicable (code generation, data analysis, architecture changes):
- QA agent reviews output against acceptance criteria
- Automated test generation and execution for code
- Consistency checks against existing codebase
Layer 3: Human Spot-Check
- User reviews delivered output
- Feedback captured via accept/reject/amend
- Patterns in rejections feed back through Feedback & Learning
Layer 4: Post-Hoc Monitoring
- Orchestrator reviews task metrics during learning loop
- Identifies trends: rising rework rate, hallucination frequency, cost outliers
- Triggers configuration amendments when patterns emerge (minimum 3 occurrences)
Quality Gates
No task output is delivered until it passes applicable quality gates:
| Task Type | Required Gates |
|---|
| Code implementation | Self-validation + QA review (if available) |
| Architecture design | Self-validation + human approval |
| Documentation | Self-validation + terminology consistency check |
| Bug fix | Self-validation + regression test |
| Data analysis | Self-validation + statistical validation |
Ethics & Responsibility
Core Principles
- Human accountability: Humans are ultimately responsible for all outputs. Agents assist and recommend; humans decide and own.
- Explainability: Every agent decision must be explainable. No "black box" outputs. When asked why, the agent must provide rationale.
- Bias awareness: Agents must flag when their output may be influenced by training biases, especially in:
- Technology recommendations (may favor popular over appropriate)
- Estimation (may anchor to common patterns)
- Design decisions (may default to familiar architectures)
- Privacy: Agents must not log, store, or transmit sensitive data (credentials, PII, API keys) in metrics or memory files.
- Proportionality: Agent autonomy should match the risk level of the task. Higher risk = more human oversight.
Sensitive Data Handling
| Data Type | Rule |
|---|
| Credentials, API keys | Never log, never store in .claude/memory/ or .claude/metrics/ |
| PII (names, emails, etc.) | Do not include in metrics entries or summaries |
| Business-sensitive data | Minimize in summaries; use references to source files instead |
| Source code | May be included in summaries when relevant to task continuity |
When Ethical Concerns Arise
- Agent identifies the concern and pauses
- Flags to Orchestrator with: what the concern is, why it matters, what the options are
- Orchestrator escalates to human (always - ethical concerns are never auto-resolved)
- Human decides
- Decision is logged with full rationale
Output
Compliance checklist results (pass/fail per item) and/or new audit log entries written to .claude/metrics/. Be concise — report failures and entries written; omit passing items.
Compliance Checklist
For periodic review (monthly recommended):
