CLI reporter — beautiful terminal output + Three Questions framing

[rodchalski]

Goal

Render scan results as a polished, shareable terminal experience. The output IS marketing — developers screenshot this and share it.

Output Structure

The report is framed around PP's Three Questions:

  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  Permission Protocol — Agent Security Scan
  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

  Scan Results
  ──────────────────────────────────────────────────────────
  Path:           ./my-agent
  Framework:      langchain (+mcp)
  Files scanned:  14
  Agents: 2  Tools: 4  Prompts: 2
  PP SDK:         ✗ Not installed
  Duration:       0.8s

  ❶ Who approved this agent's access?
  ──────────────────────────────────────────────────────────

   CRITICAL  No approval gate on deploy tool [PP-HO-013]
    tools/deploy.py:45 — deploys to production with no human check
    Fix: pp.authorize({ action: "deploy", resource: "production" })
    Standards: OWASP:ASI01 | NIST:GOVERN-1.2

   HIGH  Autonomous email sending [PP-HO-015]
    agent/notifier.py:23 — sends customer emails without approval
    Fix: @requireApproval({ resource: "email", action: "send" })

  ❷ What happens when it goes wrong?
  ──────────────────────────────────────────────────────────

   HIGH  No kill switch detected [PP-HO-014]
    No mechanism to halt agent execution found in codebase
    Fix: Add pp.configure({ killSwitch: true })

   MEDIUM  Shared memory between users [PP-DL-010]
    main.py:8 — ConversationBufferMemory without user isolation
    Fix: Namespace memory stores per user_id/session_id

  ❸ Can you prove it to your board?
  ──────────────────────────────────────────────────────────

   HIGH  No audit trail [PP-HO-013]
    0 of 4 tools generate authority receipts
    Fix: Install @permission-protocol/sdk — every action logged

   MEDIUM  Hardcoded API key [PP-IA-016]
    .env.example:3 — real API key in example file
    Fix: Use secrets manager, rotate exposed key

  + 14 more findings across 6 domains

  Domain Scores
  ──────────────────────────────────────────────────────────
  Goal Integrity      ████████████████████░░░░░░░░░░ 68
  Tool Safety         ██████████████████████░░░░░░░░░ 74
  Data Leakage        █████████████████████████░░░░░░ 82
  Human Oversight     ████████████░░░░░░░░░░░░░░░░░░░ 41
  Identity & Access   ██████████████████████████████░ 97
  MCP Security        █████████████████████████████░░ 94

  Overall
  ──────────────────────────────────────────────────────────
  D  ████████████████████████░░░░░░░░░░░░░░░░ 62

  Findings: 2 critical · 4 high · 6 medium · 5 low · 3 info

  ──────────────────────────────────────────────────────────
  ⚡ Fix these with Permission Protocol:
     npm install @permission-protocol/sdk
     pp-scan init .
  
  📊 Track compliance: pp-scan . --upload
  ──────────────────────────────────────────────────────────

Design Requirements

Visual Polish

• Use chalk for colors: red (critical), yellow (high), blue (medium), dim (low/info)
• Unicode box drawing for borders
• Bar chart for domain scores (█ filled, ░ empty)
• Letter grade prominently displayed
• Clean spacing — this should look good in a screenshot

Three Questions Sections

The findings are grouped under PP's three questions, not by technical domain. Mapping:

• "Who approved this?" → Human Oversight + Identity & Access findings
• "What happens when it goes wrong?" → Tool Safety + Data Leakage + Goal Integrity findings
• "Can you prove it?" → All findings related to audit trail, logging, compliance gaps

PP Fix CTA

Every finding shows the PP-specific fix. The bottom CTA pushes to SDK install + pp-scan init.

Output Modes

• --format pretty (default) — colored terminal output as above
• --format json — structured JSON (for CI pipelines)
• --format sarif — SARIF for GitHub Code Scanning integration
• --format markdown — for pasting into PRs/docs

Acceptance Criteria

• Pretty output matches the mockup above (approximately)
• All 4 output formats working
• Three Questions framing with correct finding grouping
• Domain score bar charts
• Letter grade with color
• PP SDK install CTA at bottom
• Looks good on both dark and light terminals
• Screenshots in PR for visual QA

Depends On

• Issue Repo scaffold + CLI package setup #1 (scaffold)
• Issue Permission gap analyzer — find unprotected agent actions #3 (analyzer — provides findings + scores)