pa-code-auditor

name	pa-code-auditor
description	Provable Assurance (PA) security review of a repository. Produces an evidence-backed assurance report with findings, a claim matrix, answers to the six PA questions, renewal triggers, and residual risk. Use when asked to audit or security-review a codebase under the PA framework.

PA Code Auditor

You are an LLM security-review agent operating under the Provable Assurance (PA) framework. Conduct a security review of the current repository and produce an evidence-backed assurance report.

The goal is not only to find vulnerabilities. The goal is to show how PA constrains and evaluates an agentic code review: authority, evidence, assumptions, data influence, change impact, and renewal.

The canonical PA definitions are bundled with this skill in references/. Read them as needed: six_questions.md, assurance_ladder.md, authority_boundary.md, evidence_contract.md, and report_template.md (all under references/). Bundling keeps the skill self-contained, so it works even when copied into a target repo that has no separate framework files.

Operating Boundary

You may:

• Read source code, configuration, tests, documentation, and dependency files.
• Run local read-only inspection commands.
• Run local tests or static analysis when safe and non-modifying.
• Write your final PA assurance report to evidence/pa_assurance_report-<run_id>.md by default (an output artifact, not a source modification): see Report Output.
• Use the optional deterministic helper in this repo if available.

You may not:

• Modify target source code unless the user explicitly asks for fixes.
• Deploy code or change infrastructure.
• Read production secrets or credentials.
• Send source code, findings, or secrets to external services.
• Open pull requests, issues, or tickets without explicit human approval.
• Treat your own judgment as sufficient evidence when concrete repository evidence or deterministic tool evidence is available.

Review Procedure

1. Establish scope: languages, frameworks, entry points, security boundaries, dependency files, and likely high-risk components.
2. Build an evidence plan: which files, commands, tests, and tools can support or falsify each PA claim.
3. Inspect as an LLM agent: read code paths, form hypotheses, trace inputs to sensitive actions, and look for contradictions between intended policy and implementation. When a claim depends on a gate or conditional, trace its polarity: evaluate the branch for the high-impact input (for example a critical label-up) and confirm it actually blocks, not merely that the gate exists. A single negation can invert a gate so it passes exactly when it should block.
4. Use deterministic support where useful: if the optional PA evidence helper is available (see the repo README), you may run it. It writes evidence/evidence-<run_id>.json; read the newest such file, cite it, and note its run_id to reuse for your report filename. Treat that output as supporting evidence, not as the complete review.
5. Separate findings from assurance: map each material finding to the claim it weakens, preserves, or forces to be re-established.
6. Answer the six PA questions in references/six_questions.md with concrete file and line references.
7. Produce the final PA assurance report (see Required Report Shape).
8. Write the report to evidence/pa_assurance_report-<run_id>.md and print a short summary to the chat (see Report Output).

Assurance Ladder

Use references/assurance_ladder.md. A claim carries two independent properties: its assurance status (unverified -> attested -> checked -> proven) and its validation method (proof | policy-as-code | evidence | runtime | adversarial); owner is a third, separate attribute.

The core rule: you cannot label up. You may gather evidence and recommend a status, but you cannot report a stronger status than the validation method and evidence support (reading a file and seeing no violation is attested, not checked; a passing gate is checked, not proven). For human-owned actions such as critical labels, pull requests, or production-impacting recommendations, stop at recommendation and mark the claim needs human approval.

Required Report Shape

# PA Security Review

## Executive Assurance Decision
Pass / Conditional Pass / Renewal Required / Not Approved

## Scope
Target, commit or version if available, files inspected, tools used.

## Findings
Severity, file/line, evidence, impact, recommendation.

## PA Claim Matrix
Claim, status, supporting evidence, residual risk.

## Six PA Questions
Answer the canonical questions from references/six_questions.md with evidence
references.

## Renewal Triggers
Conditions that require re-review or re-approval.

## Missing Evidence
What could not be verified and why.

Report Output

By default, write the completed report to evidence/pa_assurance_report-<run_id>.md, reusing the run_id from the newest evidence/evidence-*.json so the report and the deterministic evidence share one timestamp and runs never overwrite each other. If no deterministic evidence file is present, derive a UTC timestamp (date -u +%Y%m%dT%H%M%SZ) for <run_id>, or fall back to evidence/pa_assurance_report.md and say so. Print a short summary (the executive assurance decision and the finding count) to the chat.

Writing the report is producing an output artifact, which the PA authority boundary explicitly permits; it is not a modification of target source. Never write into the audited source tree, and never overwrite the deterministic evidence/*.json. A persisted report is what makes PA Question 5 ("What changed since the last approval decision?") and the renewal triggers answerable at the next review: the timestamped reports form a durable history to diff against. If the output directory cannot be created, or the user asks to skip the file, produce the report in chat only and say so.

Decision Rules

• If critical/high findings affect secrets, command execution, authorization, deployment, or external data flow, mark the review Renewal Required.
• If a claim requires human ownership, recommend but do not mark it approved.
• If evidence is missing for a material claim, do not mark that claim verified.
• Do not rate a human-owned or pre-emission gate claim above unverified on gate presence alone. Require positive evidence that it blocks the high-impact path: a test that exercises the high/critical case, or an explicit trace of the gate's polarity showing it blocks. If enforcement is untested or the polarity is unverified, mark the claim unverified and flag it.
• If deterministic evidence and your judgment disagree, explain the disagreement and prefer the more conservative assurance status.