Pentest Orchestrator

The authoritative engagement lifecycle and skill router. It does not contain vulnerability payloads or tool matrices: load the matched phase playbook and specialist skill on demand.

Non-Negotiable Contract

• Test only an approved scope. Target-touching work uses violin_exec or violin_exec_burst; host-local preparation may use terminal.
• Maintain exactly one active [~] PTT task. Keep structured hypotheses, evidence, coverage, and phase state under $ENG_DIR.
• Store raw proof only under $ENG_DIR/evidence/<phase>/; never store secrets or evidence in skills/ or $ENG_DIR/state/.
• Do not close an engagement without reporting/report.md and retrospective/retrospective.md.
• One finding per vulnerability — never bundle. Each distinct vulnerability (a separate flaw, endpoint, or attack class) gets its own violin_submit_finding call. If one probe exposed two flaws (e.g. a JWT algorithm bypass AND a separate missing-access-control on an admin route), submit two findings, each naming its own decisive receipts and saved bodies. Bundling unrelated flaws under one finding blurs severity, remediation, and traceability — each report entry must stand alone and be independently attributable to one flaw.
• Do not stop at the first confirmed finding. Sweep every in-scope obligation until it is tested, not-applicable, or blocked with evidence. A partial pass that leaves obligations untested is an incomplete assessment.
• Every validated hypothesis becomes a finding. Before REPORTING, walk hypotheses.md and confirm each Validated hypothesis has a corresponding submitted finding. A validated flaw with no finding is a missed submission.

Load on Demand

Keep tool summaries to five lines or fewer: result, evidence path, and next validated action. Redact credentials and tokens in chat and state artifacts.

Output Budget

Keep batch summaries to 3-5 bullets. Save raw output strictly under $ENG_DIR/evidence/<phase>/; do not paste full scanner output into chat, quote only decisive lines. Never summarize away evidence needed for validation: preserve full output, command, timestamp, and artifact path in the saved file.

State & Context Continuity

On every phase change, write $ENG_DIR/state/phase-summary.md and update $ENG_DIR/state/checkpoint.json (phase_current, open_items). If context is at risk of compression, tell the user: "Continue in the current session; I will resume from $ENG_DIR/state/ files." Re-read $ENG_DIR/state/checkpoint.json, $ENG_DIR/state/ptt.md, and $ENG_DIR/state/phase-summary.md before the next action. Do not reconstruct tested state from memory after compression.

Engagement Loop

1. Bootstrap: Confirm $ENG_DIR/scope/scope.yaml and the engagement state are valid. In interactive mode, use playbooks/scoping.md; in non-interactive mode, do not call clarify.
2. Bind: Use violin_record_ptt to set one active task and skill. If it returns skill_prepared, load the delivered skill, then repeat the identical call; the PTT transition is applied only after the second call returns ok.
3. Discover: Use playbooks/recon.md, inventory routes, methods, parameters, roles, sessions, and application bundles. Start the coverage matrix in state/coverage-matrix.yaml.
4. Research: Use playbooks/vuln-research.md, record each candidate in hypotheses.md, and route its class using the table below.
5. Validate: Use playbooks/exploitation.md plus the matched specialist playbook. Capture baseline and decisive differential evidence through the guarded execution tools; call violin_review_batch after each batch.
6. Record immediately: After every reviewed batch, update the hypothesis, coverage cell, and PTT. A missing state record is not a completed result.
7. Report and improve: Use playbooks/reporting.md, then read references/retrospective.md and record gaps without rewriting history.

If a command fails twice, stop and read references/anti-stuck.md. If batch state is desynchronized, use violin_rebind_pending_batch before new work.

Phase Playbooks

Vulnerability Routing

vuln_class takes priority over candidate_source, which takes priority over the phase default. Load only the selected specialist skill and its matching playbook.

Evidence Minimum

Submit a finding through violin_submit_finding only after reviewing the signed execution receipts and saved evidence that demonstrate its claim. Capture the full HTTP status, headers, and body when HTTP is involved. Compare appropriate unauthenticated, low-privilege, and authorized contexts for identity-related findings. The guard assigns the finding ID and stores the typed record; do not write finding Markdown by hand.

• Prove the claim before marking it Validated. Read the saved request and response, identify the expected secure behavior, and check that the observed result demonstrates the claimed impact. Use relevant comparison controls (identity, privilege, ownership, or a negative input) to rule out ordinary behavior. A successful request or an interesting response alone is not proof. If the evidence is inconclusive, keep the hypothesis Candidate and run one bounded discriminating probe in the appropriate testing phase, or escalate the unresolved limitation; do not relabel it merely to complete closeout.
• Submission acceptance is not semantic validation. receipt_validation verifies authenticity. evidence_complete reports the HTTP-byte warning heuristic; even true does not establish vulnerability proof. A stored finding's validated status is not an independent review of the claim. Resolve proof warnings and inspect the cited bodies before closing the task.
• Save the decisive body, then cite it. Save the decisive request/response body to its own file under evidence/ (e.g. curl -i -o evidence/vuln-research/<vector>.txt ...). Declare that exact path through the violin_exec call's evidence_outputs, then pass it as evidence_paths alongside receipt_paths when submitting the finding. Undeclared files are not authenticated by the signed receipt and cannot support a finding.
• One finding per obligation. Submit a separate finding for each distinct vulnerability. If one probe spans multiple flaws, split it into one finding each instead of a single bundled finding. Do not submit a placeholder without a real signed receipt and a saved evidence body.
• Do not stop at the first finding. Sweep every in-scope obligation; a partial pass that leaves obligations untested is an incomplete assessment. Record each obligation as tested, not-applicable, or blocked with evidence — silence is not coverage.

Completion Checklist

• Scope and authorization are current.
• Every coverage cell is tested, not applicable, or blocked with a reason.
• Before REPORTING: sweep references/coverage-closeout.md and record negatives explicitly (silence is not coverage).
• Before REPORTING: review each claim against its saved decisive evidence and relevant controls; resolve or escalate inconclusive hypotheses.
• Every validated vulnerability has a receipt-backed finding submission.
• All command batches are reviewed and state files are current.
• Reporting and retrospective artifacts exist.