Shapes
Four objects. That's the spec.
Every artefact pakka produces or consumes is one of these four. The schema is versioned independently of the harness.
/ 01
plan
PRD shape
A goal, a non-goal, a list of changes, an acceptance test list. Published to an issue. Versioned, mutable, links back to the originating turn.
requiredbefore gate
/ 02
finding
gate output
One blocking or advisory observation. Carries: reviewer id, confidence, severity, line range, spec citation, optional patch.
0..nper gate
/ 03
decision
recall entry
One paragraph of long-lived knowledge in one of five categories. Cited; immutable; written to .pakka/recall/*.jsonl.
~3per session
/ 04
verdict
gate result
Aggregate. Exit code, reviewer roll-up, set of findings. The single source of truth for whether a diff ships.
1per gate
A finding, in full
Show me the JSON.
A real finding emitted by the security reviewer in the rate-limit engagement. JSON, single object, no surprises.
payload
{
"kind": "finding",
"reviewer": "security",
"severity": "blocking",
"confidence": 0.92,
"where": {
"file": "src/middleware/rate_limit.ts",
"lines": [42, 48]
},
"what": "Missing input validation on user_id.",
"cites": [
{ "kind": "spec", "ref": "§3.2" }
],
"patch": "…unified-diff, 4 lines…"
}