# Piolium Output Structure

Piolium writes all audit artifacts under a `piolium/` directory in the target
repository. This file explains that directory layout and which files are meant
to be read, retained, or treated as transient implementation detail.

For phase-by-phase behavior, see [phase-reference.md](phase-reference.md).

## Top-level layout

```text
piolium/
  audit-state.json
  attack-surface/
  file-records/                 # optional; only with PIOLIUM_FILE_RECORDS=1
  findings-draft/
  findings/
  exports/
  final-audit-report.md
  confirmation-report.md
  confirm-workspace/
  chamber-workspace/
  adversarial-reviews/
  merge-workspace/
  quarantine/
  tmp/piolium/
  variant-summary.md
```

Not every command creates every path. Lite runs create `audit-state.json`,
`attack-surface/`, severity-prefixed `findings/<C|H|M><N>-<slug>/` directories
with `draft.md` + `poc.*` + `evidence/`, retained draft evidence, candidate
file records, and cleanup metadata. Balanced and deep runs add
`final-audit-report.md` and per-finding `report.md` files via downstream
review and assembly phases.

## Durable outputs

These paths are the primary outputs to keep after a run:

| Path | Produced by | Description |
| --- | --- | --- |
| `piolium/audit-state.json` | all audit commands | Run history, mode, status, phases, retry metadata, artifacts, commit, branch, and repository identity. |
| `piolium/attack-surface/` | lite, balanced, deep, diff, revisit, merge | Durable context used by later phases: recon, advisories, KB, SAST, probes, chamber summaries, and merge summaries. |
| `piolium/attack-surface/candidates.jsonl` | lite, balanced, deep, diff, revisit, longshot | Ranked deterministic candidate matches used to steer later phases toward high-risk files. |
| `piolium/attack-surface/candidates-summary.md` | lite, balanced, deep, diff, revisit, longshot | Human-readable candidate totals, top files, and highest-ranked matches. |
| `piolium/file-records/` | optional for lite, balanced, deep, diff, revisit, longshot | Per-source-file scan records with SHA-256, candidate count, risk score, and candidate snippets. Disabled by default; enable with `PIOLIUM_FILE_RECORDS=1` or `--plm-file-records true`. |
| `piolium/findings/` | lite, balanced, deep, revisit, merge | Final finding directories promoted from reviewed drafts (severity-prefixed `<C\|H\|M><N>-<slug>/` for lite Q3 and balanced L5 onward). |
| `piolium/exports/` | export command | JSON or markdown exports generated by `/piolium-export`. |
| `piolium/final-audit-report.md` | balanced, deep, revisit, merge | Consolidated final report across finalized findings. |
| `piolium/confirmation-report.md` | confirm, deep P16 | Confirmation verdict report for existing findings. |
| `piolium/variant-summary.md` | deep | Variant-search summary for confirmed findings. |
| `piolium/attack-surface/longshot-summary.md` | longshot | Curated, deduped summary of the hail-mary swarm output. |

## `audit-state.json`

`piolium/audit-state.json` is the resume and status file. It has this shape:

```json
{
  "audits": [
    {
      "audit_id": "2026-...",
      "commit": "...",
      "branch": "main",
      "repository": "owner/repo",
      "history_available": true,
      "mode": "balanced",
      "model": "...",
      "agent_sdk": "pi",
      "started_at": "...",
      "completed_at": "...",
      "status": "complete",
      "phases": {
        "L1": {
          "status": "complete",
          "started_at": "...",
          "completed_at": "...",
          "artifacts": ["piolium/attack-surface/advisory-summary.md"],
          "attempt": 1,
          "max_attempts": 3
        }
      }
    }
  ]
}
```

Phase status values are `pending`, `in_progress`, `complete`, `failed`, and
`skipped`.

## `attack-surface/`

`piolium/attack-surface/` is the durable working knowledge base. It is safe to
read directly and is intentionally retained by cleanup phases.

Common files include:

| File | Produced by | Description |
| --- | --- | --- |
| `lite-recon.md` | lite Q0 | Source snapshot, manifests, frameworks, entry points, git status, and scan exclusions. |
| `candidates.jsonl` | deterministic candidate scan | One JSON object per candidate match, sorted by risk/noise score. |
| `candidates-summary.md` | deterministic candidate scan | Candidate totals, top classes, top files, and highest-ranked matches. |
| `matcher-suggestions.json` | `/piolium-learn` | Suggested custom matcher rules derived from finalized findings. |
| `lite-q1-summary.md` | lite Q1 | Secrets scan backend, result count, and scan notes. |
| `lite-q2-summary.md` | lite Q2 | Fast SAST summary. |
| `lite-consolidation-manifest.json` | lite Q3 | Severity-prefixed ID assignments, source draft paths, and dropped low/info entries. |
| `lite-verification-summary.md` | lite Q4 | Final finding counts and lite cleanup summary. |
| `lite-cleanup-summary.json` | lite Q4 | Removed, missing, and retained paths from lite cleanup. |
| `advisory-summary.md` | balanced L1, deep P1 | Advisory and dependency intelligence. |
| `knowledge-base-report.md` | balanced L2, deep P3 | Architecture model, trust boundaries, DFD/CFD slices, threat model, and coverage gaps. |
| `architecture-entrypoints.md` | deep P3 | Entry points, attacker sources, sinks, routes, and key files. |
| `source-sink-flows-all-severities.md` | balanced L3, deep P4 | SAST findings and source-to-sink paths. |
| `manual-attack-surface-inventory.md` | balanced L4, deep P8 | Manually traced routes, sources, sinks, and exploit-relevant paths. |
| `balanced-probe-summary.md` | balanced L4 | Balanced probe summary. |
| `balanced-chamber-summary.md` | balanced L5 | Balanced chamber and FP-check summary. |
| `balanced-consolidation-manifest.json` | balanced L5 | Severity-prefixed ID assignments, source draft paths, and dropped low/info entries. |
| `balanced-verification-summary.md` | balanced L7 | Final folder verification and cleanup summary. |
| `balanced-cleanup-summary.json` | balanced L7 | Removed, missing, and retained paths from balanced cleanup. |
| `patch-bypass-summary.md` | deep P2 | Git history and bypass review. |
| `public-routes-authz-matrix.md` | deep P5 | Authorization matrix for routes or operations. |
| `state-concurrency-summary.md` | deep P6 | State, idempotency, and concurrency analysis. |
| `spec-gap-summary.md` | deep P7 | Spec, parser, and framework contract gaps. |
| `deep-probe-summary.md` | deep P8 | Deep manual probe summary. |
| `cross-service-edges.json` | deep P9 | Machine-readable cross-service edges, or a single-service marker. |
| `cross-service-edges.md` | deep P9 | Human-readable cross-service data-flow report. |
| `deep-cleanup-summary.json` | deep P17 | Removed, missing, and retained paths from final deep cleanup. |
| `diff-summary.md` | diff D1 | Changed files, scope decisions, touched routes/sources/sinks, and finding pointers. |
| `revisit-attack-surface-inventory.md` | revisit R5 | Revisit-specific attack-surface inventory. |
| `revisit-probe-summary.md` | revisit R5 | Fresh revisit probe summary. |
| `revisit-r7-chamber-summary.md` | revisit R7 | Revisit chamber summary for R7. |
| `revisit-r8-chamber-summary.md` | revisit R8 | Revisit chamber summary for R8. |
| `merge-summary.md` | merge M7 | Merged durable context summary. |
| `longshot-targets.json` | longshot X1 | Per-file target list with score, language, and per-file status (pending / in_progress / complete / failed). The X2 fan-out updates this file atomically as it makes progress. |
| `longshot-summary.md` | longshot X3 | Curated summary: run metadata, per-anchor table, ranked curated findings, and top concerns. |

## `findings-draft/`

`piolium/findings-draft/` contains candidate markdown findings before final
promotion. Draft names indicate the phase that created them.

Examples:

```text
piolium/findings-draft/
  q1-001-hardcoded-token.md
  q2-001-path-traversal.md
  p4-001-command-injection.md
  p8-001-idor.md
  p10-001-idor.md
  p12-001-idor-variant.md
  diff-001-new-ssrf.md
  r8-001-cache-poisoning.md
  longshot-a1b2c3d4-001-command-injection.md
  longshot-a1b2c3d4-000-no-finding.md
  longshot-curated-001-command-injection.md
```

Drafts usually include YAML frontmatter:

```md
---
id: p10-001
phase: P10
slug: idor
severity: high
---

# Finding body
```

Cleanup phases retain `findings-draft/` so rejected and intermediate drafts
remain inspectable. Treat this directory as evidence and audit context, not the
final report.

## `findings/`

`piolium/findings/<id>-<slug>/` is the final per-finding layout.

```text
piolium/findings/
  H-001-idor/
    draft.md
    report.md
    poc.py
    poc.theoretical.md
    evidence/
      confirmed-2026-05-01T10-00-00.log
```

Common files:

| File | Description |
| --- | --- |
| `draft.md` | Promoted draft with normalized frontmatter. |
| `report.md` | Final disclosure-style report. This is the per-finding source of truth for confirmation mode. |
| `poc.*` | Executable proof of concept, using the most natural language for the target. |
| `poc.theoretical.md` | Written when a real runtime exploit cannot be executed but the exploit chain is documented. |
| `evidence/` | Commands, HTTP exchanges, logs, screenshots, or other proof collected during PoC and confirmation work. |

False-positive findings may be renamed with an `FP-` prefix during confirmation:

```text
piolium/findings/FP-H-001-idor/
```

## `confirm-workspace/`

`piolium/confirm-workspace/` stores confirmation inputs, live-run results, and
cleanup summaries.

| File | Produced by | Description |
| --- | --- | --- |
| `findings-inventory.json` | confirm V1 | Extracted finding metadata and exploitability classification. |
| `env-strategies.json` | confirm V2 | Ranked local startup and test strategies. |
| `auth-spec.json` | confirm V2 | Optional auth identity scaffolding. |
| `env-connection.json` | confirm V3 or remote target setup | Base URL, credentials/tokens when available, method used, cleanup command, and session metadata. |
| `healthcheck-failure.log` | confirm V3 | Startup or healthcheck failure details. |
| `poc-results.json` | confirm V4 | Aggregate PoC execution results. |
| `test-mapping.json` | confirm V5 | Generated test fallback results. |
| `false-positive-renames.json` | confirm V6/V7 | Finding directories renamed with an `FP-` prefix. |
| `cleanup-summary.json` | confirm V7 | Final layout checks, evidence directory creation, redaction summary, and skipped files. |

## Review and merge workspaces

These paths are useful for debugging and review, but some cleanup phases remove
them after final artifacts are written.

| Path | Produced by | Description |
| --- | --- | --- |
| `piolium/chamber-workspace/` | deep P10 | Review chamber transcripts and cluster index. |
| `piolium/chamber-workspace/index.md` | deep P10 | Index of chamber clusters and decisions. |
| `piolium/adversarial-reviews/` | deep P11 | Cold false-positive verification notes. |
| `piolium/merge-workspace/` | merge | Copied findings, source aliases, dedup decisions, and rename maps. |
| `piolium/quarantine/` | merge | Findings excluded from final merged output because they could not be safely normalized. |

## Agent transcripts and temporary files

Agent sessions write transcripts under:

```text
piolium/tmp/piolium/runs/<runId>/
  prompt.md
  transcript.jsonl
  result.md
  error.txt
```

These files are for debugging phase execution. Cleanup phases generally remove
`piolium/tmp/` after durable artifacts are written.

## Output by command

| Command | Primary outputs |
| --- | --- |
| `/piolium-lite` | `attack-surface/lite-*.md`, `attack-surface/lite-consolidation-manifest.json`, severity-prefixed `findings/<C\|H\|M><N>-<slug>/` (`draft.md`, `poc.*`, `evidence/`), `attack-surface/lite-cleanup-summary.json` |
| `/piolium-balanced` | `attack-surface/advisory-summary.md`, `knowledge-base-report.md`, SAST/probe/chamber summaries, `findings/`, `final-audit-report.md`, balanced cleanup summary |
| `/piolium-deep` | Full `attack-surface/` corpus, `findings/`, `variant-summary.md`, `final-audit-report.md`, optional `confirmation-report.md`, deep cleanup summary |
| `/piolium-export` | `exports/findings-*.json` or markdown export directory with filtered finding metadata and owners |
| `/piolium-learn` | `attack-surface/matcher-suggestions.json`, optional `matchers.json` |
| `/piolium-confirm` | `confirmation-report.md`, `confirm-workspace/*.json`, updated `findings/*/report.md`, evidence logs |
| `/piolium-diff` | `attack-surface/diff-summary.md`, `findings-draft/diff-*.md` |
| `/piolium-revisit` | Revisit summaries under `attack-surface/`, new or updated `findings/`, regenerated `final-audit-report.md` |
| `/piolium-merge` | `merge-workspace/`, merged `findings/`, `attack-surface/merge-summary.md`, `final-audit-report.md`, optional `quarantine/` |
| `/piolium-longshot` | `attack-surface/longshot-targets.json`, `attack-surface/longshot-summary.md`, `findings-draft/longshot-<sha8>-*.md` (raw), `findings-draft/longshot-curated-*.md` (deduped) |

## What to read first

For a completed audit, start with:

1. `piolium/final-audit-report.md`
2. `piolium/findings/<id>-<slug>/report.md`
3. `piolium/attack-surface/knowledge-base-report.md`
4. `piolium/attack-surface/source-sink-flows-all-severities.md`
5. `piolium/audit-state.json`

For confirmation results, start with:

1. `piolium/confirmation-report.md`
2. `piolium/confirm-workspace/poc-results.json`
3. `piolium/confirm-workspace/test-mapping.json`
4. `piolium/findings/<id>-<slug>/evidence/`