ck_finding
Record policy compliance findings with a governance decision (allow, warn, block, or escalate) to build a durable audit trail. Use for validation failures, security checks, or human reviews.
Instructions
Persist a governed finding with a ruling decision (allow, warn, block, escalate_to_human). Findings are the durable audit trail in ControlKeel: every policy check, validation failure, or human review should produce a finding. Write operation — creates or updates a DB record. Idempotent for the same rule_id within a session. Returns the finding ID, status, and ruling state. Required fields: session_id, category (e.g., security/compliance/performance), severity (critical/high/medium/low), rule_id (dotted policy identifier such as CK-SEC-001), and plain_message. decision defaults to block; use allow for approved exceptions. Use ck_finding to record issues discovered during agent work; use ck_memory_record for general knowledge or decisions not tied to a policy rule.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| category | Yes | Finding category (e.g., security, compliance, performance). | |
| decision | No | Governance decision: allow, warn, block, or escalate to human. | |
| metadata | No | ||
| plain_message | Yes | Human-readable finding description. | |
| rule_id | Yes | Policy rule identifier that triggered this finding. | |
| session_id | Yes | Unique session identifier for correlating findings, proofs, budget, and audit trail. | |
| severity | Yes | Severity level (e.g., critical, high, medium, low). | |
| task_id | No | Task identifier within the session for scoped operations. | |
| title | No | Human-readable title for display and search. |