feat: add Policy Verdict Layer for machine-readable agent decisions

[SergUdo]

Add Policy Verdict Layer — Structured Verdict for Autonomous Agents

---

Why

Currently ai-slop-gate produces a findings report — a list of issues intended
for human review. As AI-assisted development evolves toward background agents and
autonomous CI/CD pipelines, this output model becomes insufficient.

Agents cannot act on a findings array without implementing their own parsing and
decision logic. Every consumer of the gate re-implements the same severity-to-action
mapping — inconsistently, and without a shared contract.

The goal is to evolve ai-slop-gate from a reporting tool into a
governance layer that any autonomous agent can integrate with via a single,
stable verdict schema.

Reference context: background-agents.com — governance is identified as the
missing primitive in the autonomous agent stack. This feature directly addresses that gap.

---

What

Add a policy_engine.py module that:

• Consumes the aggregated findings from all providers
• Computes a single structured verdict
• Extends the final JSON output with verdict metadata
• Exposes fix_hints for auto-fixable issues
• Defines escalation targets for issues requiring human review

---

Verdict Schema (target)

{
  "verdict": "block" | "fix" | "escalate" | "pass",
  "reason": "short machine-readable reason code",
  "auto_fixable": true | false,
  "fix_hints": [
    {
      "file": "slop.py",
      "line": 23,
      "signal": "hardcoded_secret",
      "suggested_action": "move to environment variable"
    }
  ],
  "escalate_to": "human" | "security-team" | null,
  "findings": [...]
}

---

Verdict Logic

Condition	Verdict	Agent action
Any critical finding	block	Do not merge, stop pipeline
Any high finding with auto_fixable	fix	Attempt automated remediation
Any high finding, not auto_fixable	escalate	Request human / security-team review
Only medium / low findings	pass	Proceed, log findings as advisory

Important

The escalate verdict ensures a Human-in-the-loop (HITL) pattern for high-risk decisions, satisfying enterprise safety requirements and ensuring accountability in autonomous workflows.

---

Agent Interaction Model

GitHub Actions (autonomous agent flow)

- name: ai-slop-gate
  id: gate
  run: python run.py --output json > gate_result.json

- name: Act on verdict
  run: |
    VERDICT=$(jq -r '.verdict' gate_result.json)
    case $VERDICT in
      block)
        echo "::error::Gate blocked — critical findings detected"
        exit 1
        ;;
      fix)
        gh pr comment \
          --body "$(jq '.fix_hints' gate_result.json)"
        ;;
      escalate)
        gh pr request-review --reviewer security-team
        ;;
      pass)
        echo "✓ Gate passed"
        ;;
    esac

Background agent flow (future)

When agents generate PRs autonomously at high frequency
(background agents, scheduled pipelines), the gate runs
on each PR without human involvement:

Agent generates PR
       ↓
ai-slop-gate runs (event trigger)
       ↓
verdict: block   → PR auto-closed, agent retries with fix_hints
verdict: fix     → fix_hints posted as PR comment, agent reads and patches
verdict: escalate→ PR flagged, human reviewer assigned
verdict: pass    → PR proceeds to merge queue

The fix_hints array becomes the feedback loop between the gate
and the agent — enabling autonomous remediation without human intervention
for common, well-defined issues.

---

Implementation Plan

New file

• policy_engine.py — pure function compute_verdict(findings: list) -> dict

Modified files

• run.py — call compute_verdict() after findings aggregation, extend output
• providers/*.py — add auto_fixable: bool field to each finding category

Schema

• Document verdict schema in README.md as the public API contract
• This schema is the integration point for all future agent consumers

---

TODO

• Define auto_fixable flag per finding signal across all providers
• Implement policy_engine.py with verdict logic
• Extend run.py output with verdict envelope
• Add fix_hints generation for common auto-fixable signals
  (hardcoded secrets → env var, :latest tag → pinned digest, etc.)
• Update README with verdict schema documentation
• Add unit tests for compute_verdict() edge cases
• Test full agent interaction flow in GitHub Actions

---

Priority: Deferred — implement when autonomous agents begin generating PRs
in the project workflow
Depends on: existing findings JSON output (already in place)

---

References

• background-agents.com — governance as missing primitive
• Ona Veto announcement (March 3, 2026) — confirms commercial demand for this layer
• Existing Groq prompt (system_prompt) — fix_hints schema aligns with current
  signal/line/file structure

[SergUdo]

Note

Strategic Outlook: From Linter to Governance Service

While the immediate goal is to implement the local policy_engine.py, the long-term roadmap for this feature is to support the emerging Autonomous Agent Ecosystem.

Integration Plan:

• Verdict-as-a-Service: Moving logic to Cloud Run (Serverless) for REST/gRPC access.
• Observability: Exporting verdict distributions to Prometheus/Grafana to monitor "AI Slop" trends across the organization.
• M2M Security: Utilizing Workload Identity Federation (WIF) for secure agent-to-gate communication.

This positions ai-slop-gate as the central "Governance Brain" in a zero-trust, autonomous DevSecOps pipeline.