Operator Audit

Feature Breakdown & Architecture

A complete inventory of what pr-to-spec does, how it's built, and what risks it classifies.

Features

PR Analysis

core

Analyze any GitHub PR into a structured spec with risk classification

Local Scan

core

Analyze local branches, staged changes, or last N commits

Intent Declaration

core

Declare expected scope, risk ceiling, and change type

Drift Detection

core

Detect scope creep, forbidden touches, risk escalation

MCP Server

new

6-tool Model Context Protocol server for IDE integration

Verification Contracts

v0.7

Declarative rules: no_new_dependencies, max_files_changed, etc.

Intent DAG

v0.7

Graph-based intent tracking with decision taxonomy

Agent Protocol

core

JSON envelope with version, status, exit codes, signals

Risk Classification

core

10 categories from authentication to large-change

AI Enhancement

opt

Optional Anthropic/OpenAI summaries with --ai-enhance

GitHub Action

core

Automated PR spec generation in CI/CD pipelines

Architecture

Source tree 
src/
  servers/        MCP server (6 tools via stdio transport)
  cli/            CLI entrypoints (analyze, scan, intent, check)
  action/         GitHub Action entrypoint
  core/
    schema/       Zod schema for the canonical prompt-spec format
    github/       Octokit-based PR data fetching
    sources/      DiffSource abstraction (GitHub PR, local branch, staged, commits)
    parsing/      Deterministic spec generation from diff metadata
    risk/         Rule-based risk classification heuristics
    intent/       Intent schema and YAML storage (.pr-to-spec/intent.yaml)
    drift/         Drift detection against declared intent
    protocol/     Agent protocol envelope (version, status, exit_code)
    rendering/    YAML, Markdown, JSON, and PR comment renderers
    ai/           Optional AI enhancement (Anthropic, OpenAI)
    diff/         Spec version diffing

Design Principles

Deterministic first : Core spec uses heuristics, not LLMs. Reproducible and auditable.
No execution : Never runs code — metadata and diffs only.
Agent-native : JSON envelope output, clean exit codes, field extraction. Built for piping.
Local-first : Works on local branches and staged changes without GitHub.
Minimal trust surface : Read-only by default. Zod-validated output.

Before & After

Before pr-to-spec

  • Agent reads raw diffs — no structure, no risk signals
  • No intent declaration — scope creep undetected
  • Manual PR review copy-paste to LLM context
  • No exit codes — agents can't gate on risk
  • No audit trail — "what did the agent see?"

After pr-to-spec

  • Structured JSON envelope — version, status, signals
  • Intent + drift detection catches scope creep early
  • One command: pr-to-spec check --json | agent review
  • Clean exit codes: 0 clean, 2 high-risk, 3 drift, 4 gate fail
  • Full spec artifact — reproducible, auditable, deterministic

Risk Classification

authentication

high

Auth, login, session, OAuth, JWT files

secrets

high

.env, .key, .pem, credentials files

database

high

Migrations, .sql, schema files

permissions

high

RBAC, ACL, policy files

payment

high

Stripe, billing, subscription files

dependencies

medium

Lockfiles, package managers

infrastructure

medium

Docker, Terraform, k8s, deploy configs

destructive-operations

medium

DROP TABLE, DELETE FROM in patches

security-config

medium

CORS, CSP, security headers

large-change

low

300+ line changes in a single file

Security Posture

No Execution

Never runs code — metadata and diffs only

Read-Only Default

Only reads PRs and diffs, writes nothing unless --comment

Zod-Validated Output

All spec output is schema-validated before rendering

SSRF Prevention

Webhook URLs validated: HTTPS required, private IPs blocked

No Command Injection

custom_command contract type removed, always fails

Prototype Pollution Guard

--field extraction blocks __proto__ traversal

A Quality Grade 384 tests passing · MIT licensed · Deterministic output