agnostic-prompt-aps 1.1.1__py3-none-any.whl

aps_cli/payload/agnostic-prompt-standard/references/01-vocabulary.md

@@ -0,0 +1,124 @@
+# 01 Vocabulary
+
+This document defines the **normative language** and the authoring vocabulary constraints used
+throughout APS.
+
+## Normative terms
+
+RFC 2119 terms **MUST**, **MUST NOT**, **SHOULD**, **SHOULD NOT**, **MAY** are normative.
+
+## Text types
+
+The following text types are normative and MAY be used to classify prose within a prompt or its
+supporting documentation:
+
+```yaml
+text_types:
+  - Procedure
+  - Description
+  - Safety
+  - Observation
+  - Requirement
+  - Definition
+  - Declaration
+  - Constraint
+  - Conditional
+```
+
+## Tense and voice
+
+```yaml
+tense_voice:
+  allowed_verbs:
+    - infinitive
+    - imperative
+    - simple_present
+    - simple_past
+    - simple_future_will
+  disallowed:
+    - progressive
+    - perfect
+    - going_to_future
+  procedures: active_only
+  descriptions: passive_only_if_agent_unknown
+```
+
+## Dictionary and terminology
+
+- Authors SHOULD use approved words from a Dictionary with approved POS/meaning.
+- Technical terms are allowed if defined on first use and linked by `term_id` and `lexicon_edition`.
+- Multi-word nouns MUST be ≤ 3 words unless explicitly whitelisted.
+
+## Identifiers
+
+In general, specification identifiers SHOULD be short, ASCII, and consistent.
+
+```yaml
+identifiers:
+  # Applies to glossary / lexicon identifiers and similar spec IDs.
+  spec_ids:
+    style: UpperCamel_Segments
+    ascii_only: true
+    no_hyphens: true
+    max_length: 30
+```
+
+> NOTE: Process/tool identifiers, symbols, and placeholders used by the agentic control DSL have
+> their own stricter patterns; see **03 Agentic control**.
+
+## Sentence, paragraph, and list limits
+
+```yaml
+sentence_limits:
+  procedures: 20
+  descriptions: 25
+
+paragraph_limits:
+  sentences_max: 6
+  one_topic: true
+
+lists:
+  steps_numbered: true
+  supportive_bullets: true
+```
+
+## Numbers, units, and time
+
+```yaml
+numbers_units_time:
+  numbers:
+    decimals: "."
+    thousands: "U+2009 (thin space)"
+
+  units:
+    format: "<number><space><unit>"
+    percent: "50 %"
+    temperature: "60 °C"
+    symbols: middle_dot_between_compounds # U+00B7
+    catalog: units.json (project)
+
+  time:
+    iso8601: true
+    default_tz: "Z"
+    local_times_require_offset_or_iana: true
+```
+
+## Safety vocabulary
+
+```yaml
+safety:
+  taxonomy: [WARNING, CAUTION, NOTICE]
+  wrapper: SAF
+  imperative_required: true
+```
+
+## `<instructions>` line discipline
+
+Inside `<instructions>`:
+
+- Instructions MUST use **one directive per line**.
+- Each line MUST be a single imperative or declarative that changes system behavior.
+- Multiple sentences per line are forbidden.
+- Blank lines inside `<instructions>` are forbidden.
+
+The engine/LSP MUST raise `AG-033` when this policy is violated.

aps_cli/payload/agnostic-prompt-standard/references/02-linting-and-formatting.md

@@ -0,0 +1,122 @@
+# 02 Linting and formatting
+
+This document defines the **compile-time and lint-time** formatting rules.
+
+## Newlines and XML-like tags
+
+Newline rule (normative):
+
+- There MUST be exactly one newline after an opening XML-like tag.
+- There MUST be exactly one newline before a closing XML-like tag.
+
+This applies to top-level sections (`<instructions>`, `<constants>`, `<formats>`, `<runtime>`,
+`<triggers>`, `<processes>`, `<input>`) and to nested tags like `<format>` and `<process>`.
+
+## Tabs and whitespace
+
+- Tab characters (`\t`) are forbidden anywhere in a prompt. Tabs MUST raise `AG-011`.
+- Engines MUST treat excessive inter-token padding whitespace as a compile error (`AG-031`) when
+  compiled/normalized form requires exactly one ASCII space.
+
+## Comments
+
+Comments are denoted by `//` at the start of the line and are for explanatory purposes only.
+
+### Comment stripping
+
+If an engine implements comment stripping, it MUST:
+
+- Remove any full line whose first two non-whitespace characters are `//`.
+- NOT strip comments inside block constant bodies (see below).
+
+### Where comments are forbidden
+
+- Comments are forbidden inside **executable blocks**: `<triggers>` and `<processes>` (including
+  inside each `<process>` body). A detected comment in an executable block MUST raise `AG-010`.
+
+## Unicode and quotes
+
+- Prompts MUST be NFC normalized.
+- Strings MUST use ASCII double quotes (`"`) only. Smart quotes are forbidden.
+
+## Canonical JSON spacing
+
+Engines that compile or canonicalize JSON MUST emit **canonical JSON** using the rules below:
+
+- After `:`, exactly one ASCII space.
+- After `,`, exactly one ASCII space.
+- No interior spaces immediately inside `{` `}` `[` `]`.
+  - Empty containers are `{}` and `[]`.
+- Keys in objects MUST be in lexicographic order.
+
+Source form inside JSON block constants MAY contain arbitrary newlines/indentation, but engines
+MUST parse and re-emit canonical JSON at compile time.
+
+## `where:` key ordering
+
+In `where:` parameter lists, keys MUST appear in lexicographic order. Violation → `AG-012`.
+
+## Backticked ids
+
+Process and tool ids in statements MUST be wrapped in backticks.
+
+Examples:
+
+- `RUN \`process_id\``
+- `USE \`tool_name\``
+
+Violation → `AG-003` (InvalidId).
+
+## Constants inside JSON values
+
+An `UpperSym` appearing inside JSON objects/arrays denotes a **constant symbol reference**.
+Engines MUST resolve it from `<constants>` before execution or raise `AG-006`.
+
+## Block constants
+
+Block constants are allowed only inside `<constants>` (see **00 Structure**).
+
+Rules:
+
+- Block constant opening line MUST be `SYMBOL: JSON<<` or `SYMBOL: TEXT<<` (exactly one ASCII space
+  after `:`).
+- Block constant BODY is line-oriented and terminates at the first line whose content is exactly
+  `>>` starting at column 1.
+- Comment stripping (`//`) MUST NOT apply inside block constant BODY.
+- Unknown `<BLOCK_TYPE>` → `AG-046`.
+- Missing closing delimiter `>>` → `AG-045`.
+
+## Format blocks
+
+Rendered format outputs MUST be wrapped in a fenced code block whose info string is exactly
+`format:<ID>` where `<ID>` matches a defined `<format id="...">`.
+
+Rules:
+
+- The fence MUST start at column 1.
+- For any step that requires a format, the agent MUST emit exactly one `format:<ID>` fenced block.
+  Multiple blocks or surrounding prose → `AG-040`.
+
+### WHERE discipline (format contracts)
+
+Every rendered format block MUST include a terminating `WHERE:` section.
+
+Each `<PLACEHOLDER>` token that appears in the body MUST have exactly one definition line in
+`WHERE:`. No extra definitions are allowed.
+
+- Missing/extra/mismatched definitions → `AG-041` / `AG-042`.
+- Placeholders MUST be `<UPPER_SNAKE>`; any other style → `AG-043`.
+
+## RETURN values
+
+`RETURN` supports:
+
+- Symbol lists
+- `key=value` pairs
+- Artifact references of the form:
+
+```json
+{"$artifact":"SYMBOL","hash":"sha256:..."}
+```
+
+See **03 Agentic control** and **05 Grammar** for executable syntax.

aps_cli/payload/agnostic-prompt-standard/references/03-agentic-control.md

@@ -0,0 +1,192 @@
+# 03 Agentic control
+
+This document defines the **agentic control DSL** used inside `<process>` bodies.
+
+## Keywords
+
+```yaml
+keywords:
+  control: [GIVEN, WHEN, IF, ELSE IF, ELSE, THEN]
+  actions: [RUN, USE, CAPTURE, SET, UNSET, RETURN, ASSERT]
+  story: [TELL, SNAP, MILESTONE]
+  blocks: [WITH, PAR, JOIN]
+  modifiers: [atomic, timeout_ms, retry]
+```
+
+## Identifiers and reserved tokens
+
+```yaml
+identifiers:
+  symbol:
+    regex: "^[A-Z0-9_]{2,24}$"
+    unique: true
+
+  process_id:
+    regex: "^[a-z][a-z0-9_-]{1,63}$"
+    unique: true
+
+  tool_name:
+    regex: "^[a-z][a-z0-9_-]{1,63}$"
+    registered_by_engine: true
+
+  placeholder:
+    syntax: "<UPPER_SNAKE>"
+    charset: "A-Z0-9_"
+    resolvable: true
+
+  reserved:
+    - GIVEN
+    - WHEN
+    - IF
+    - ELSE
+    - THEN
+    - RUN
+    - USE
+    - SET
+    - CAPTURE
+    - RETURN
+    - ASSERT
+    - SHOULD
+    - MAY
+    - AND
+    - OR
+    - NOT
+    - WITH
+    - PAR
+    - JOIN
+    - TELL
+    - SNAP
+    - MILESTONE
+```
+
+Reserved words cannot be used as ids/keys/symbols (`AG-002`).
+
+## Strings, booleans, and numbers
+
+```yaml
+strings_booleans_numbers:
+  strings:
+    quote: double_only
+  booleans: [true, false]
+  numbers:
+    grammar: JSON_number
+    thousands: forbidden
+```
+
+## Determinism
+
+- External `USE` invocations SHOULD be idempotent; engines MAY deduplicate based on a stable hash
+  of inputs.
+- `CAPTURE` is the binding point; `USE` does not mutate the symbol table by itself.
+
+## Storytelling
+
+These statements produce narrative/logging events and are not allowed to change program state
+except as explicitly defined by the engine:
+
+- `TELL`: emits a narrative event (what/why/outcome/level).
+- `SNAP`: snapshots selected symbols; supports delta and redact lists.
+- `MILESTONE`: semantic checkpoint message (sugar for `TELL` with `type="milestone"`).
+
+## WITH block
+
+- `WITH {defaults}:` applies key/value defaults (e.g., `endpoint=...`) to enclosed `RUN`/`USE`/
+  `CAPTURE` until the block end.
+- Nested `WITH` blocks shadow outer defaults; scope does not leak across the closing boundary.
+
+## PAR / JOIN concurrency
+
+`PAR` and `JOIN` define deterministic concurrency:
+
+- `PAR:` launches one-or-more `USE` statements concurrently in **lexical order**; each child gets
+  index `[0..n-1]`.
+- `JOIN:` is the first legal point to `CAPTURE` results of prior PAR tools.
+- `CAPTURE` order MUST follow the **lexical order** of the corresponding `USE` statements,
+  regardless of completion time.
+- If any child fails hard, `JOIN` raises a composite error including the first hard error and
+  aggregates others as `suppressed`.
+
+Engines SHOULD log deterministic span indices and MUST NOT perform speculative execution.
+
+## Invocation syntax (normative)
+
+The following describes statement syntax at a human-readable level. The authoritative grammar is
+in **05 Grammar**.
+
+```text
+RUN `process_id` [where: k1=V1, ...].
+
+USE `tool_name` [where: k1=V1, ...] [(atomic[, timeout_ms=NUM][, retry=NUM])].
+
+CAPTURE S1[, S2 ...] from `tool_name` [map: "path1"→S1, "path2?"→S2 ...].
+  - Optional field via suffix '?'; no error if missing; symbol unchanged.
+
+SET SYMBOL := VALUE [(from SOURCE)]
+  - SOURCE ∈ { `tool`, INP, UpperSym, "Agent Inference" }
+
+UNSET SYMBOL.
+
+RETURN: SYMBOL[, SYMBOL...].
+RETURN: key=VALUE[, key=VALUE ...].
+  - VALUE may be an artifact reference: {"$artifact":"SYMBOL","hash":"sha256:..."}.
+
+ASSERT <condition>.
+ASSERT ALL: [ <condition>, <condition>, ... ].
+
+TELL "message" [why:SYMBOL] [level={brief|full}] [outcome:"text"].
+MILESTONE "title".
+
+SNAP [SYM1, SYM2 ...] [delta=true|false] [redact=[SYM_A, SYM_B ...]].
+```
+
+## Arguments and values
+
+```yaml
+arguments:
+  allowed_values:
+    - String
+    - Number
+    - Boolean
+    - JSON
+    - UpperSym
+    - <PLACEHOLDER>
+    - enum(V1,V2,...)
+
+  choice_sets: "{V1|V2|...} allowed in spec text where indicated; engine turns into enum() at compile time."
+  const_refs: "UpperSym MAY appear inside JSON objects/arrays and are resolved from <constants>."
+  enums: "enum(A,B,...) becomes a choice set for validation."
+```
+
+## Placeholder resolution
+
+```yaml
+placeholder_resolution:
+  order: [INP, CONSTANTS, RUNTIME, Agent Inference (only if allowed)]
+  allow_agent_inference_placeholders: false
+```
+
+Rules:
+
+- Unresolved placeholder → `AG-006`.
+- If inference occurs under a non-strict policy, the engine MUST emit `AG-W03` with the inferred
+  value and a deterministic input hash in the invocation log.
+
+## Naming policy
+
+- IDs/keys MUST be lowercase.
+- Symbols MUST be `UPPER_SNAKE`.
+- Reserved words cannot be used as IDs/keys/symbols (`AG-002`).
+
+## Safety policy
+
+```yaml
+safety_policy:
+  defaults: { THR: 0.90, HARM_THR: 0.40 }
+  predicate: HARM := (HSC ≥ HARM_THR) OR (STY_JSON.policy_violation = true)
+  decision:
+    IF TS ≥ THR AND HARM=false: REC := "PROCEED"
+    ELSE IF NPR != "": REC := "PROCEED_WITH_CAUTION"
+    ELSE: REC := "HOLD_FOR_REVIEW"
+  log_thresholds: true
+  randomness: forbidden unless seed provided; otherwise AG-022 (RandomnessPolicy) if policy enabled.
+```

aps_cli/payload/agnostic-prompt-standard/references/04-schemas-and-types.md

@@ -0,0 +1,137 @@
+# 04 Schemas and types
+
+This document defines the **schemas** and reusable **type contracts** used by APS.
+
+## Formats registry
+
+The `<formats>` section centralizes all human-readable output contracts that a prompt may ask the
+agent to render. This ensures outputs are verifiable, stable, and machine-checkable.
+
+### Requirements
+
+- All format contracts used anywhere in `<instructions>`, `<triggers>`, or `<processes>` MUST be
+  declared inside a single `<formats>` section using one-or-more `<format>` tags.
+- Each `<format>` MUST have a globally unique `id` within the prompt; `name` and `purpose`
+  attributes are RECOMMENDED.
+- The body of each `<format>` MUST describe the contract unambiguously (headers, columns,
+  wrappers, markers, row grammar, allowed values).
+- Rendered output MUST be a single fenced block starting with the exact fence label:
+
+  ```
+  ```format:<FORMAT_ID>
+  ```
+
+  (No spaces around the colon.)
+
+- No explanatory prose MAY appear outside the fenced block for a step that demands a format.
+- If a step references a format id that is not present in `<formats>` → `AG-039`.
+- If the rendered block does not satisfy the contract → `AG-036`.
+- If the block is not wrapped with the required ```format:<ID> fence → `AG-040`.
+
+### Structure
+
+Tag syntax:
+
+```text
+<format id="ID" [name="..."...] [purpose="..."]>
+  …
+</format>
+```
+
+Newline rules apply to `<formats>` and each `<format>` (see **02 Linting and formatting**).
+
+### Placeholders and WHERE
+
+Placeholders and WHERE sections are normative (see also **02 Linting and formatting**):
+
+- Placeholders that appear in the contract body MUST be written as `<UPPER_SNAKE>` using ASCII and
+  `UPPER_SNAKE` case.
+- Every `<format>` body MUST end with a `WHERE:` section that defines each placeholder exactly
+  once.
+- Each WHERE definition line MUST begin with `- <PLACEHOLDER> …` and normatively constrain the
+  placeholder (e.g., “is …”, “∈ { … }”, “matches …”, “format: …”, “example: …”).
+- No placeholder may appear in the body if it is not defined in WHERE → `AG-042`.
+- No placeholder may be defined in WHERE if it does not appear in the body → `AG-042`.
+- Any non-`<…>` placeholder notation (e.g., `{placeholder}`, `$PLACEHOLDER`) is forbidden →
+  `AG-043`.
+- The literal keyword `WHERE:` MUST be uppercase and followed by a newline; inline WHERE text is
+  forbidden → `AG-041`.
+
+### Expression guidance inside WHERE (RECOMMENDED)
+
+- Type: `is <type>` where `<type>` ∈ { String, Integer, Number, Boolean, ISO8601, Markdown, URI,
+  Path }.
+- Choice: `∈ { V1, V2, … }` or `is one of: V1, V2, …`.
+- Shape: `format: "## <TITLE> …"`, `table columns: | A | B | … |`, `regex: ^…$`.
+- Cardinality: `is non-empty`, `is ≤ N chars`, `is comma-separated list of UpperSym`.
+
+### References and phrasing
+
+Prompts SHOULD phrase requirements in `<instructions>` like:
+
+> You MUST conform human-readable outputs to `<formats>` by rendering a single fenced block
+> ```format:<ID>```.
+
+### Enforcement
+
+- WHERE presence/quality and placeholder discipline are enforced at lint time.
+- Violations map to `AG-041` / `AG-042` / `AG-043` or `AG-036` as applicable.
+
+## Result process pattern
+
+Intent: provide a standard **results** process that summarizes execution across processes in a
+pre-defined table for deterministic post-hoc analysis and artifact linking.
+
+Prompts that adopt this pattern MUST:
+
+1. Define `TABLE_PROCESS_RESULTS_V1` inside `<formats>`.
+2. Include a terminal process (RECOMMENDED id: `results` or short `res`) that emits exactly one
+   fenced block ```format:TABLE_PROCESS_RESULTS_V1``` summarizing all processes in lexical order.
+3. Record, at minimum: ProcessId, Name, Status, StartedAt, EndedAt, DurationMs, Outcome,
+   Artifacts, Errors.
+
+Status values MUST be one of: PENDING, RUNNING, OK, WARN, ERROR.
+
+Timestamps MUST be ISO 8601 with "Z" or explicit offset.
+
+Artifacts MUST list symbol names (comma-separated) that were RETURNed or CAPTUREd as outputs.
+
+## Supporting files (external)
+
+These files are **external** and MUST NOT appear in the prompt:
+
+- `config.json`: ALIAS only (see schema).
+- `predefinedTools.json`: tool signatures for lint/IDE help (replaces schema.json).
+- `units.json`: unit catalog used by STE layer.
+
+Policies:
+
+- If a host provides tools/config via higher-level system instructions, the engine MUST ignore any
+  duplicate local definitions to avoid prompt bloat.
+- Embedding `<config>` or `<import>` tags in a prompt is a hard error (`AG-035`).
+
+Style guidelines:
+
+- For `predefinedTools.json`, prefer one tool object per line to improve diffs/merges (best
+  practice; not enforced).
+- Engines that emit `predefinedTools.json` SHOULD preserve or adopt the one-line-per-tool layout;
+  engines MUST accept any valid JSON layout.
+
+## Example format contracts
+
+- Minimal error contract: [../assets/formats/format-error-v1.0.0.example.md](../assets/formats/format-error-v1.0.0.example.md)
+- API coverage table: [../assets/formats/format-table-api-coverage-v1.0.0.example.md](../assets/formats/format-table-api-coverage-v1.0.0.example.md)
+- Code map: [../assets/formats/format-code-map-v1.0.0.example.md](../assets/formats/format-code-map-v1.0.0.example.md)
+- Ideation list: [../assets/formats/format-ideation-list-v1.0.0.example.md](../assets/formats/format-ideation-list-v1.0.0.example.md)
+- Hierarchical outline: [../assets/formats/format-hierarchical-outline-v1.0.0.example.md](../assets/formats/format-hierarchical-outline-v1.0.0.example.md)
+- Markdown table: [../assets/formats/format-markdown-table-v1.0.0.example.md](../assets/formats/format-markdown-table-v1.0.0.example.md)
+- Code changes full: [../assets/formats/format-code-changes-full-v1.0.0.example.md](../assets/formats/format-code-changes-full-v1.0.0.example.md)
+
+## Example constants
+
+- JSON block constant example: [../assets/constants/constants-json-block-v1.0.0.example.md](../assets/constants/constants-json-block-v1.0.0.example.md)
+- TEXT block constant example: [../assets/constants/constants-text-block-v1.0.0.example.md](../assets/constants/constants-text-block-v1.0.0.example.md)
+
+## Example agents
+
+- VS Code orchestration agent: [../assets/agents/vscode-agent-v1.0.0.agent.md](../assets/agents/vscode-agent-v1.0.0.agent.md)

aps_cli/payload/agnostic-prompt-standard/references/05-grammar.md

@@ -0,0 +1,99 @@
+# 05 Grammar
+
+This document defines the normative EBNF for the agentic control DSL.
+
+> NOTE: This is a reference grammar. Engines MAY extend it, but prompts that claim APS v1.0
+> conformance MUST remain within this grammar unless the host explicitly opts into extensions.
+
+## EBNF
+
+```ebnf
+Letter        = "A"…"Z" | "a"…"z" ;
+Digit         = "0"…"9" ;
+Space         = " " ;
+Newline       = "\n" ;
+Tab           = "\t" ;
+
+UpperSym      = ( "A"…"Z" | "0"…"9" | "_" ){2,24} ;
+Placeholder   = "<", ( "A"…"Z" | "0"…"9" | "_" ){1,64}, ">" ;
+Bool          = "true" | "false" ;
+Number        = "-"? Digit, { Digit }, [ ".", Digit, { Digit } ] ;
+String        = "\"", { <any char except " or \"> | "\\\"" | "\\\\" }, "\"" ;
+EnumLit       = "enum(", UpperSym, { ",", UpperSym }, ")" ;
+
+BlockType     = "JSON" | "TEXT" ;
+BlockOpen     = UpperSym, ":", Space, BlockType, "<<", EOL ;
+BlockClose    = ">>" ;
+BlockValue    = BlockType, "<<", EOL, { <any line except BlockClose>, EOL }, BlockClose ;
+
+JsonKey       = Letter, { Letter | Digit | "_" | "-" } ;
+JsonValue     = String | Number | Bool | "null" | JsonObj | JsonArr | UpperSym ;
+JsonPair      = "\"", JsonKey, "\"", ":", Space?, JsonValue ;
+JsonObj       = "{", Space?, [ JsonPair, { ",", Space?, JsonPair } ], Space?, "}" ;
+JsonArr       = "[", Space?, [ JsonValue, { ",", Space?, JsonValue } ], Space?, "]" ;
+
+IdLower       = Letter, { Letter | Digit | "_" | "-" } ;
+Key           = IdLower ;
+Value         = String | Number | Bool | JsonObj | JsonArr | UpperSym | Placeholder | EnumLit ;
+
+StaticConst   = UpperSym, ":", Space, ( Value | BlockValue ) ;
+
+Param         = Key, "=", Value ;
+ParamList     = Param, { ",", Space, Param } ;
+
+BacktickId    = "`", IdLower, "`" ;
+
+RunStmt       = "RUN", Space, BacktickId, [ Space, "where:", Space, ParamList ] ;
+UseStmt       = "USE", Space, BacktickId, [ Space, "where:", Space, ParamList ],
+                [ Space, "(", "atomic", [ ",", Space, "timeout_ms", "=", Number ], [ ",", Space, "retry", "=", Number ], ")" ] ;
+CaptureStmt   = "CAPTURE", Space, UpperSym, { ",", Space, UpperSym }, Space, "from", Space, BacktickId,
+                [ Space, "map:", Space, "\"", <path>, "\"", "→", UpperSym, { ",", Space, "\"", <path>, "\"", "→", UpperSym } ] ;
+SetStmt       = "SET", Space, UpperSym, Space, ":=", Space, Value, [ Space, "(", "from ", ( BacktickId | "INP" | UpperSym | "Agent Inference" ), ")" ] ;
+UnsetStmt     = "UNSET", Space, UpperSym ;
+ReturnPairs   = IdLower, "=", Value, { ",", Space, IdLower, "=", Value } ;
+ReturnList    = UpperSym, { ",", Space, UpperSym } ;
+ReturnStmt    = "RETURN", ":", Space, ( ReturnList | ReturnPairs ) ;
+AssertStmt    = "ASSERT", Space, <expr> | "ASSERT ALL:", Space, "[", <expr>, { ",", Space, <expr> }, "]" ;
+TellStmt      = "TELL", [ Space, String ], [ Space, "why:", UpperSym ], [ Space, "level=", ("brief" | "full") ], [ Space, "outcome:", String ] ;
+MileStmt      = "MILESTONE", Space, String ;
+
+SnapList      = "[", UpperSym, { ",", Space, UpperSym }, "]" ;
+RedactList    = "[", UpperSym, { ",", Space, UpperSym }, "]" ;
+SnapStmt      = "SNAP", Space, SnapList, [ Space, "delta", "=", Bool ], [ Space, "redact", "=", RedactList ] ;
+
+IfStmt        = "IF", Space, <expr>, ":" ;
+ElseIfStmt    = "ELSE IF", Space, <expr>, ":" ;
+ElseStmt      = "ELSE", ":" ;
+WhenStmt      = "WHEN", Space, <condition-text-no-colon>, ":" ;
+GivenStmt     = "GIVEN", Space, <condition-text-no-colon>, ":" ;
+
+EOL           = Newline ;
+WithBlock     = "WITH", Space, JsonObj, ":", EOL, { <indented Statement>, EOL } ;
+ParBlock      = "PAR", ":", EOL, { <indented UseStmt>, EOL } ;
+JoinBlock     = "JOIN", ":", EOL, { <indented CaptureStmt>, EOL } ;
+
+ForEachStmt   = "FOREACH", Space, IdLower, Space, "IN", Space, UpperSym, ":", EOL, { <indented Statement>, EOL } ;
+
+TryBlock      = "TRY", ":", EOL, { <indented Statement>, EOL },
+                "RECOVER", Space, "(", IdLower, ")", ":", EOL, { <indented Statement>, EOL } ;
+
+WhereSection  = "WHERE:", EOL, { WhereDef, EOL } ;
+WhereDef      = "- ", Placeholder, Space, Constraint ;
+Constraint    = TypeConst | EnumConst | FormatConst | RegexConst ;
+
+TypeConst     = "is", Space, ("String" | "Number" | "Boolean" | "ISO8601" | "URI" | "Path") ;
+EnumConst     = "is one of:", Space, Value, { ",", Space, Value } ;
+FormatConst   = "matches format:", Space, UpperSym ;  # Recursive validation
+RegexConst    = "matches", Space, String ;
+
+Statement     = RunStmt | UseStmt | CaptureStmt | SetStmt | UnsetStmt | ReturnStmt | AssertStmt
+              | TellStmt | MileStmt | WithBlock | ParBlock | JoinBlock | ForEachStmt | TryBlock
+              | IfStmt | ElseIfStmt | ElseStmt | SnapStmt ;
+
+Program       = { Statement, EOL } ;
+```
+
+## Notes (non-normative)
+
+- Indentation is significant for block bodies (`WITH`, `PAR`, `JOIN`, `TRY`, `FOREACH`).
+- `<expr>` and `<path>` are intentionally unspecified in v1.0 and are engine-defined.