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<T>: 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).