Plugins · CCPP PQL
Diagnostics
PQL diagnostic codes: what each category covers, how severities block a prompt, and how to read a position.
Every stage of the compiler reports diagnostics with a code, a severity, a message and a position.
ccpp pql diagnostics prints the whole catalog (117 codes in this version).
| Severity | Effect |
|---|---|
| error | Blocks the submission: Claude receives nothing, your draft stays in the box. |
| warning | Does not block; when meant for Claude, listed under "Compiler notes" in the prompt. |
| info | Does not block, same as a warning. |
Some diagnostics are for you only: a policy that exposes nothing to Claude, for instance, is never described to it.
Categories
| Letter | Stage | Raised for | Page |
|---|---|---|---|
S | parser | Strings, comments, ;, }, unknown keywords, malformed ids, {{ }} expressions | Syntax |
D | validator | First instruction, header form, missing scope, a block where ; is expected | Scopes |
T | validator | Types and count of parameters, blank descriptions, integer bounds, unknown identifiers | Objectives |
C | validator | Missing block, orphan or repeated ELSE, branch after ELSE | Conditions |
P | validator | Rules after an executable instruction, SESSION SUCCESS outside a root scope, a function of the wrong kind | Stop rules |
H | validator | Clause shapes, LIMIT units, PACKAGES modes, inherited conflicts | HOW directives |
O | validator | Contradictions between objectives of one block | Objectives |
R | resolution | @ targets, perimeter, symbolic links, .git, HOW sources | Scopes |
F | functions | Definition files, calls, let, interpolation, FOR, recursion, limits | Functions |
X | policies | Unknown, disabled or invalid policies, nothing exposable, perimeter, duplicates | Policy references |
Reading a position
In the prompt box, the band shows line:column of the box text. In the CLI, positions are 1-based and count
from after the $, so add one column on line 1 to find them in the box. A diagnostic raised inside a function
definition carries the definition's file and the chain of calls that produced it.
Checks that wait
Inside a condition branch, checks that depend on the project's state (a FROM or MAKE target, a MATCH or
REUSE source) are warnings ending "It is checked again when the branch is selected": Claude checks them before
acting on the branch. Descriptions in quotes are never evaluated: only their structure is checked.
Look up a code
ccpp pql diagnostics | grep PQL-H010
ccpp pql diagnostics --json