feat(authorization-obligations): hunter adjudicates intent without raising evidence

Task 3.3. For every finding that carries a route the hunter answers one closed
question, is this route meant to be public, and the answer is recorded as
public, protected or unknown with its rationale. Nothing else changes: not the
label, not the evidence, not the evidence level, and the hunter never authors a
pattern or a policy. The prompt carries the handler's own lines only and is
redacted before it leaves the process. Without a client one degradation is
recorded and the findings are identical.

Co-Authored-By: Claude Opus 5 (1M context) <[email protected]>
Claude-Session: https://claude.ai/code/session_01T7XD7x5KonMdmGRkp63EQG

src/openultrasast/semantic/obligations/intent.py

@@ -0,0 +1,100 @@
+"""Hunter adjudication of intent (authorization-obligations, Req 6.3).
+
+The hunter answers one closed question per route-bearing finding: is this route meant to be public? The answer is recorded
+on the finding as `intent` (public | protected | unknown) with its rationale, and nothing else changes: not the label, not
+the evidence, not the evidence level. Without a client one `intent_adjudication_unavailable` degradation is recorded.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+from collections.abc import Mapping
+from dataclasses import replace
+
+from ...redaction import redact_secrets
+from .check import ObligationFinding, ObligationResult
+
+INTENTS = ("public", "protected", "unknown")
+_SYSTEM = (
+    "You review web handlers for an application security tool. Answer one closed question about intent only. "
+    'Reply with JSON of the form {"intent": "public" | "protected" | "unknown", "rationale": "<one sentence>"}. '
+    "Do not assess exploitability and do not propose code."
+)
+
+
+def adjudicate_intent(result: ObligationResult, *, client: object | None, model: str, texts: Mapping[str, str]) -> ObligationResult:
+    """Annotate route-bearing findings with the hunter's intent verdict; identical findings when no client is available."""
+    if not any(finding.route for finding in result.findings):
+        return result  # nothing to adjudicate: no degradation for a run with no route-bearing obligation finding
+    if client is None or not model:
+        degradation: dict[str, object] = {
+            "stage": "obligations",
+            "reason": "intent_adjudication_unavailable",
+            "detail": "no hunter client or model",
+        }
+        return replace(result, degradations=(*result.degradations, degradation))
+    findings: list[ObligationFinding] = []
+    for finding in result.findings:
+        if not finding.route:
+            findings.append(finding)
+            continue
+        intent, rationale = _ask(client, model, finding, texts.get(finding.operation.path, ""))
+        findings.append(replace(finding, intent=intent, intent_rationale=rationale))
+    return replace(result, findings=tuple(findings))
+
+
+def _ask(client: object, model: str, finding: ObligationFinding, text: str) -> tuple[str, str | None]:
+    siblings = ", ".join(item for item in finding.evidence if "::" in item) or "none recorded"
+    handler = _handler_excerpt(text, finding.operation.function)
+    question = (
+        f"Route {finding.route} is served by {finding.operation.function} in {finding.operation.path}. "
+        f"It performs {finding.operation.kind} on {finding.operation.resource or 'a resource'} without {finding.missing}. "
+        f"Sibling handlers that discharge it: {siblings}. Is this route meant to be public?\n\n{handler}"
+    )
+    question = redact_secrets(question)  # design Security Considerations: the hunter receives redacted handler text
+    try:
+        response = client.complete(  # type: ignore[attr-defined]
+            model=model,
+            messages=[{"role": "system", "content": _SYSTEM}, {"role": "user", "content": question}],
+            tools=[],
+            timeout_seconds=30,
+        )
+    except Exception:  # noqa: BLE001 - the hunter is advisory; a failed call records unknown
+        return "unknown", None
+    return _parse(getattr(response, "content", None))
+
+
+def _parse(content: object) -> tuple[str, str | None]:
+    if not isinstance(content, str) or not content.strip():
+        return "unknown", None
+    match = re.search(r"\{.*\}", content, re.S)
+    if not match:
+        return "unknown", None
+    try:
+        payload = json.loads(match.group(0))
+    except json.JSONDecodeError:
+        return "unknown", None
+    intent = str(payload.get("intent", "unknown")).strip().lower()
+    rationale = payload.get("rationale")
+    return (intent if intent in INTENTS else "unknown"), (str(rationale)[:200] if rationale else None)
+
+
+def _handler_excerpt(text: str, function: str) -> str:
+    """The handler's own lines: its decorators through the end of its indented body, never another handler's."""
+    lines = text.splitlines()
+    start = next(
+        (i for i, line in enumerate(lines) if re.match(rf"\s*(?:async\s+)?(?:def|function)\s+{re.escape(function)}\b", line)), None
+    )
+    if start is None:
+        return ""
+    head = start
+    while head > 0 and lines[head - 1].strip().startswith("@"):
+        head -= 1
+    end = start + 1
+    while end < len(lines) and (not lines[end].strip() or lines[end].startswith((" ", "\t"))):
+        end += 1
+    return "\n".join(lines[head:end][:60])
+
+
+__all__ = ["INTENTS", "adjudicate_intent"]