Plugins · CCPP PQL

Identifier cheatsheet

Every PQL keyword, HOW directive, connector, registered identifier, reference sigil and value type on one page.

Keywords and identifiers are case-sensitive. ccpp pql registry prints the same tables for the installed version (--json for tools).

Sigils and values

Written	Meaning	Example
`$`	First character of the prompt: PQL mode	`$ FROM @src { … }`
`@path`	Path reference (Claude Code's `@` mention), never a string	`@packages/pql`, `@"my dir"`, `@~/notes`
`!id`	CPO policy reference, kebab-case	`!ts-no-any;`
`#id(…)`	Function call, kebab-case	`#add-features("Lexer", 3);`
`{{ path }}`	Interpolation of a value path	`{{ params.name }}`, `{{ vars.i }}`
`"…"`	String on one line; escapes `\"` `\\` `\n` `\t` `\r` `\{` `\}` `\u{1F600}`	`ADD "A typed parser";`
`250`	Number; bounds are integers without sign	`LIMIT FILE TO 250 LINES;`
`[a, b]`	List (function arguments, `FOR`)	`["a", "b"]`
`true` `false` `null`	Literals (function arguments)
`// …` `/* … */`	Comments
`;` or `{ }`	Every statement ends with one of them

# and ! inside a string are text: ADD "Document #add-features"; calls nothing.

Role	Keyword	Parameters	Ends with
Scope	`FROM`	1 existing directory `@ref`	`;` (root header) or block
Scope	`MAKE`	1 new directory `@ref`	`;` (root header) or block
Objective	`ADD` `REMOVE` `MODIFY` `REFACTOR` `SKIP`	1 to N descriptions	`;`
Objective	`CONTINUE`	0 or 1 description	`;`
Condition	`IF HAPPEN` `IF NOT HAPPEN`	exactly 1 description	block
Condition	`ELSE IF HAPPEN` `ELSE IF NOT HAPPEN`	exactly 1 description	block
Condition	`ELSE`	none	block
Stop	`SESSION SUCCESS`	1 to N criteria, root scope only	`;`
Stop	`STOP WHEN` `ASK WHEN`	exactly 1 description	`;`
HOW	`HOW`	none, holds directives only	block
Control	`FOR v IN RANGE(a, b)`, `FOR v IN list`	loop variable	block

A description is a non-blank string. Several descriptions after one keyword are as many objectives or criteria.

Directive	Strength	Connectors
`STRUCTURE BY "…"`, `STYLE "…"`, `ERRORS USING "…"`, `STATE "…"`, `ASYNC USING "…"`, `TEST USING "…"`, `INTEGRATE VIA "…"`, `SPLIT WHEN "…"`	constraint
`PATTERN "…", …`, `DOCUMENT "…", …`	constraint
`BOUNDARY target EXPOSES "symbol", …`	constraint	`EXPOSES`, `CONSUMES`
`ISOLATE target FROM target, …`	constraint	`FROM`
`CONTRACT target ACCEPTS "type", … RETURNS "type"`	constraint	`ACCEPTS` (optional), `RETURNS`
`COLOCATE target WITH target`	constraint	`WITH`
`IMPLEMENT target USING "technique"`	constraint	`USING`
`LIMIT category TO n unit`	constraint	`TO`
`DEPTH MAX n`	constraint
`COMPLEXITY metric MAX n`	constraint	`MAX`
`NAMING category convention`	constraint
`MATCH aspect OF @source`	constraint	`OF`
`PACKAGES NO_NEW`, `PACKAGES STANDARD_ONLY`, `PACKAGES ALLOW "name", …`	constraint	`NO_NEW`, `STANDARD_ONLY`, `ALLOW`
`COMPATIBILITY mode WITH baseline`	constraint	`WITH`
`FOLLOW principle, …`	principle
`PREFER "a" OVER "b"`	preference	`OVER`
`REUSE @path, …`	preference

A target is a string or an @ reference; a baseline is an @ reference or a string.

Domain	Identifiers	Used by
limit-category	`FILE`, `FUNCTION`, `CLASS`, `PARAMETERS`	`LIMIT`
limit-unit	`LINES`, `B`, `KB` (1,000 bytes), `KIB` (1,024 bytes), `METHODS`	`LIMIT`
naming-category	`VARIABLES`, `FUNCTIONS`, `CLASSES`, `INTERFACES`, `CONSTANTS`, `FILES`	`NAMING`
naming-convention	`camelCase`, `PascalCase`, `snake_case`, `UPPER_SNAKE_CASE`, `kebab-case`	`NAMING`
match-aspect	`STYLE`, `NAMING`, `STRUCTURE`, `PATTERNS`	`MATCH`
principle	`KISS`, `DRY`, `YAGNI`, `SOLID`	`FOLLOW`
metric	`CYCLOMATIC` (McCabe, profile `cyclomatic-mccabe-v1`)	`COMPLEXITY`
compatibility-mode	`BACKWARD`, `RUNTIME`	`COMPATIBILITY`

Units per LIMIT category:

Field or name	Values
`kind`	`fragment` (default), `how`, `program`
Parameter types	`string`, `NonEmptyString`, `integer`, `number`, `boolean`, `array`, `PathRef`, `ExistingPathRef`, `ExistingDirectoryRef`, `NewDirectoryRef`, any identifier domain
Constraints	`minimum`, `maximum`, `minLength`, `maxLength`, `enum`, `items`
Reserved names	`params`, `vars`

Codes read PQL- + a category letter + a number, such as PQL-S005. ccpp pql diagnostics lists all of them.

Letter	Stage
`S`	syntax
`D`	document structure
`T`	types and cardinality
`C`	condition chains
`P`	placement
`H`	HOW semantics and conflicts
`O`	contradictions between objectives
`R`	`@` resolution
`F`	functions
`X`	policy references