compliance-check

name	COMPLIANCE_CHECK
description	Apply the OpenAI SDK compliance checklist to audit files or directories and produce a Markdown report with findings and suggested fixes. Use when asked to "check compliance", "run compliance check", or "audit against OpenAI SDK rules".

COMPLIANCE CHECK

Owner: QA

Goal

Audit a target (file set or directory) against .claude/checklists/openai-sdk-compliance-checklist.yaml and deliver a Markdown report with evidence and actionable fixes.

Workflow

1. Load Inputs

• Read target_path (file, directory, or list).
• Respect context: apply strictly to agent implementations, tools, and orchestration code.

2. Evaluate Rules

• Process rules top-down (A1 → A11).

• Apply activation_hint and stop_condition:

  • Stop on first HIGH unless --exhaustive is requested.
  • Stop if findings_count > 25.

• Enforce Kira Constitution and OpenAI Agents SDK standards:

  • A1. Primitives Only: Orchestration uses only run()/Runner.run() and handoff(); no extra verbs like routeAgent or pipeTo.
  • A2. Tool Categories Valid: Every tool is one of: Function | Hosted | Agent-as-Tool | MCP.
  • A3. No Custom Routing: No bespoke agent-to-agent communication (axios/fetch/custom) beyond SDK patterns.
  • A4. Tool Input Schema (Zod): All tools define parameters via tool({ parameters: z.object({...}) }).
  • A5. Structured Outputs (Zod): Agents with non-text outputs declare outputType: z.object({...}).
  • A6. Single RunContext: One canonical RunContext<T> shared across agents/tools/guardrails.
  • A7. History Threading: Conversation history flows via result.history → next run().
  • A8. Model Settings Casing: Uses modelSettings.toolChoice (camelCase), not tool_choice.
  • A9. Tracing Enabled/Declared: Tracing wired to Langfuse (or explicitly disabled with rationale).
  • A10. Vision & Whisper Usage: Use OpenAI Vision for images/PDFs and Whisper for audio; custom file analysis only for text formats.
  • A11. Deterministic IDs via Context: IDs (userId, wid, aid, etc.) come from RunContext; never inferred or generated by agents.

• For each rule:

  • Mark PASS/FAIL with evidence (file path + line/snippet).
  • For FAIL, provide a concrete fix that matches the rule’s fix guidance.
  • Preserve severity and autofix flags from the checklist.

3. Apply Lean Guards

• Do not expand scope beyond meta.scope.
• Prefer small, safe fixes.
• Refactor only when required by a rule.
• Skip large migrations.
• If a standard conflicts with a functional requirement, flag it for manual review rather than forcing a breaking change.

4. Produce Report

• Follow the checklist output_schema.
• Include:
  • Summary: counts by severity + decision (READY | NEEDS_REVISION | BLOCKED).
  • Findings: list items with id, severity, file, symbol (if known), evidence, fix, autofix.
  • Suggestions: targeted next steps based on findings.

5. Save Output

• Write Markdown to docs/qa/reports/compliance-{{target_slug}}.md.
• Create directories if missing.

Anti-Patterns

• Do not mark PASS without evidence.
• Do not invent IDs, symbols, or file paths.
• Do not ignore severity: HIGH violations.
• Do not propose custom orchestration verbs or "clever" routing logic that bypasses the SDK.
• Do not recommend using raw tool_choice or messages arrays without SDK types.
• Do not allow UUID generation inside agents (must come from context).