Release v0.0.1.dev18

Author: Doug Ransom

.agents/AGENTS.md

@@ -42,6 +42,7 @@ All Prolog code (regardless of target engine) MUST follow the universal style an
   - Prefer coroutining (`freeze/2`, `when/2`) to suspend goals until variables are instantiated, preferring [`CLP(Z)`](https://github.com/mthom/scryer-prolog/blob/master/src/lib/clpz.pl)/`dif/2` over manual coroutining where specialized constraints apply.
   - **Direct Reification over `if_/3` for Booleans**: Always prefer direct reified predicates (e.g. `=(X, Y, Truth)`, `memberd_t/3`, `tpartition/4`) over wrapping boolean assignments inside `if_/3` (e.g. use `=(X, Y, Truth)` instead of `if_(X = Y, Truth = true, Truth = false)`). Reserve `if_/3` strictly for selecting non-boolean values (`if_(G, Val = 'yes', Val = 'no')`) or executing conditional branches with distinct control paths.
   - **Prefer `cond_t` over `if_` / `->` (DRY Principle)**: Aggressively prefer `cond_t` over `if_` and `->` when choosing between choices or values based on a test. Use `cond_t` to avoid repeating the same variable or assignment in both the true and false clauses of `if_` (Don't Repeat Yourself principle).
+  - **Meta-Predicate Declarations (`meta_predicate`)**: When defining module-level predicates that accept callable goals (`0`), closures (`1`..`N`), DCG non-terminals (`//` or `2`), or module-sensitive terms (`:`), always insert explicit `:- meta_predicate` declarations directly below the module header. Use exact closure arities for higher-order arguments and standard specifiers (`+`, `-`, `?`, `*`) for non-callable data arguments to prevent unwanted caller module expansion.
 - **Declarative AI Workflow**: [.agents/skills/prolog-declarative-workflow/SKILL.md](.agents/skills/prolog-declarative-workflow/SKILL.md)
   - Use declarative reasoning based on unification, constraints, and backtracking (never imperative thinking).
   - Specify mode (`+`/`-`), determinism (`det`, `semidet`, `nondet`), and choice-point expectations.

.agents/references/prolog_guidelines.md

@@ -108,6 +108,29 @@ Prefer higher-order predicates and closures over primitive recursive list traver
 - **Higher-Order DCGs (`call//N`)**: Parameterize DCG rules with closures or non-terminals using `call//N` (e.g. `call(Goal, Arg)` inside `-->`) to avoid writing duplicate grammar traversals.
 - **Lambda Expressions (`library(lambda)`)**: Use `:- use_module(library(lambda)).` and lambda abstractions (`\X^...`, `\X^Y^Goal`) for inline transformations, filtering, and mapping without creating single-use helper predicates.
 
+### Meta-Predicate Declarations (`meta_predicate`)
+
+When exporting or defining predicates inside a module that accept callable arguments (goals `0`, closures `1`..`N`, DCG rules `//` or `2`, dynamic goals `:`), always insert explicit `:- meta_predicate` declarations directly after the module header:
+
+- **Module Name Expansion**: Tells the module system to resolve meta-arguments in the context of the *caller module* rather than the library module, preventing runtime `existence_error` exceptions.
+- **Precise Arity Specifiers**:
+  - `0`: 0-argument goal (executed with `call(Goal)` or direct evaluation).
+  - `1`..`9`: Closures receiving $N$ additional arguments (e.g. `2` for `maplist/3`, `2` for `tfilter/3`, `3` for `foldl/4`).
+  - `//` or `2`: DCG non-terminal closures expanded with difference lists.
+  - `+`, `-`, `?`, `*`: Regular non-callable data arguments.
+- **Avoid Anti-Patterns**: Never declare `meta_predicate` on pure data predicates, and never mark data arguments as `:` or `0` (which would force unintended caller-module term wrapping).
+
+```prolog
+:- module(my_higher_order, [
+    custom_map/3,
+    delimited//3
+]).
+
+:- meta_predicate
+    custom_map(2, +, -),
+    delimited(//, //, //, ?, ?).
+```
+
 ### Use Term & Goal Expansion to Avoid Code Duplication
 
 Leverage Prolog's compile-time expansion hooks (`user:term_expansion/2` and `user:goal_expansion/2`) to eliminate repetitive code structures, redundant clause boilerplate, or macro-like patterns instead of duplicating logic across multiple rules.

.agents/skills/prolog-code-review/SKILL.md

@@ -16,6 +16,7 @@ Use this skill when reviewing Prolog pull requests, auditing code diffs, or eval
 | **Clean Data Representation** | - Can every data element kind be distinguished solely by its **principal functor** (e.g., `leaf(L)` vs `node(L, R)`)?<br>- Are defaulty representations avoided so argument indexing works automatically?<br>- Are external defaulty/unstructured inputs converted into clean trees early? |
 | **Determinism & Performance** | - Do deterministic predicates leave open choice points?<br>- Is the primary input placed in the first argument position for first-argument indexing?<br>- Is `zcompare/3` used for reified integer comparisons?<br>- Are recursive calls in tail position (TCO) with accumulators? |
 | **Variable Naming & Syntax** | - Are public API parameter names domain-descriptive (`Tree`, `TokenStream`) while standard short names (`X`, `Xs`, `N`) are kept in tight local contexts?<br>- Are DCG state pairs consistently named (`L0..L` / `S0..S`)?<br>- Are neck operators `:-` free of dropped characters (`:` instead of `:-`)?<br>- Are line comments formatted with `%` rather than `#` or `//`?<br>- Are DCG rules declared with `-->` rather than `->`?<br>- Are comparison operators Prolog-standard (`=\=`, `\=`, `=<`, `>=`) rather than C/Python symbols (`!=`, `<=`, `=>`)?<br>- Do module export lists (`:- module/2`), import lists (`:- use_module/2`), and doc comments use ISO `Name//Arity` indicator notation for DCG non-terminals? |
+| **Meta-Predicate Declarations** | - Do all exported and module-level predicates taking callable arguments (goals `0`, closures `1`..`N`, DCG non-terminals `//` or `2`, dynamic goals `:`) have explicit `:- meta_predicate` declarations?<br>- Are closure arity extensions accurate (e.g. `2` for `maplist/3`, `2` for `tfilter/3`, `3` for `foldl/4`)?<br>- Are non-callable data arguments marked with `+`, `-`, `?`, or `*` rather than `:` or `0` to prevent unintended caller module qualification? |
 | **Engine Portability** | - Are engine-specific types (SWI dicts, SWI strings) avoided in ISO / multi-engine code?<br>- Are explicit module imports declared (e.g. `:- use_module(library(dcgs)).`, `library(si)`, `library(clpz)`)? |
 | **Homoiconicity & Prolog Tooling** | - If this tool/program processes or generates Prolog source, is it itself implemented in Prolog?<br>- Does the implementation follow the **ISO core + flat shim** pattern: engine-agnostic logic in `core.pl`, engine-specific differences isolated to `scryer_shim.pl` / `swi_shim.pl` / etc.?<br>- If skill or capability metadata is declared, is it represented as `skill(Name, Caps)` Prolog facts rather than external YAML/JSON config?<br>- Is skill discovery expressed as Prolog queries (`skill(Name, Caps), member(Capability, Caps)`) rather than string-matching lookups? |
 | **Safety & Security** | - Is user input sanitized before `consult/1` or `read_term/2`?<br>- Are execution timeouts enforced via `prolog-safe`? |

.agents/skills/prolog-conventions/SKILL.md

@@ -74,16 +74,31 @@ While the module loading directive (e.g. `:- use_module(library(clpz)).` in Scry
        call(Sep, X),
        separated_by(Xs, Sep).
    ```
-9. **Explicit Library Declarations**: Always explicitly import required library modules (e.g. `:- use_module(library(reif)).`, `:- use_module(library(dcgs)).`, `:- use_module(library(charsio)).`, `:- use_module(library(lambda)).`, `:- use_module(library(clpz)).`). Do not assume SWI-style autoloading when targeting ISO or embedded engines.
-10. **Control Structures & CLP(Z) Constraints**: Use standard ISO control structures `(,)/2`, `(;)/2`. Prefer CLP(Z) constraints (`#=`, `#>`, `all_distinct/1`) and reified arithmetic (`zcompare/3`, `'#='(X, Y, Truth)`, `clpz_t/2`) over low-level evaluation (`is/2`, `>/2`). Always post domain declarations (`ins`, `in`) before posting complex relations to enable early constraint propagation. Link model flags via `#<==>` (e.g. `X #> 10 #<==> B #= 1`) and pass partial closures `(#<)(0)` to `tfilter/3`.
-11. **Coroutining & Goal Suspension**: Use `freeze/2` for single-variable activation guards (`nonvar/1`) and `when/2` for multi-variable or disjunctive activation conditions (`(nonvar(A) ; nonvar(B))`). Prefer CLP(Z)/`dif/2` over manual coroutining where domain-specific constraints apply.
-12. **Clean Data Representations**: Prefer clean data structures where element kinds are distinguished by principal functor (`leaf(L)` vs `node(L, R)`). Avoid defaulty representations that force runtime type tests (`var/1`) or procedural default branches. Convert raw input data into clean trees early.
-13. **Macro & Compile-Time Expansion**: Use Prolog's macro mechanism (`user:term_expansion/2` and `user:goal_expansion/2`) to transform clauses or rewrite inline goals at compile time to eliminate boilerplate and redundant rules. Prefer static compile-time expansion over dynamic database modification (`asserta`/`assertz`).
-14. **Avoid Non-Standard Extensions**: Do not rely on engine-specific types (e.g. SWI dicts or SWI string types) when writing standard Prolog code.
-15. **Library Steering vs Reading Source**: Rely on dialect-specific Standard Library Cheat Sheets for module header declarations and predicate exports. AI assistants MUST NOT read raw standard library implementation source files, relying instead on concise cheat sheets and pre-trained semantics to save context tokens.
-16. **Safety**: Execute code using `prolog-safe`.
-
-17. **Prolog Tooling in Prolog (ISO Core + Engine Shims)**: Programs that parse, rewrite, transform, analyze, or generate Prolog source code SHOULD themselves be implemented in Prolog, exploiting the language's homoiconicity (code = terms = data). Structure such tools using an ISO-common core with flat, engine-specific shim files:
+9. **Meta-Predicate Declarations (`meta_predicate`)**: When defining predicates in a module that accept callable arguments (goals `0`, closures `1`..`N`, DCG rules `//` or `2`, or module-sensitive terms `:`), ALWAYS insert a `:- meta_predicate` declaration directly after the `:- module/2` header and imports. This ensures the module system applies caller-module name expansion to meta-arguments across module boundaries:
+   ```prolog
+   :- module(my_combinators, [
+       my_maplist/3,
+       my_tfilter/3,
+       bracketed//3
+   ]).
+
+   :- meta_predicate
+       my_maplist(2, +, -),
+       my_tfilter(2, +, -),
+       bracketed(//, //, //, ?, ?).
+   ```
+   - Use exact closure arities: `0` for goals (`call(G)`), `1`..`9` for closures expecting additional arguments (`call(C, X)` -> `1`, `call(C, X, Y)` -> `2`), `//` (or `2`) for DCG rules.
+   - Use `+`, `-`, `?`, `*` for non-meta data terms. NEVER declare `meta_predicate` on first-order data predicates or mark data arguments as `:`/`0` (which would trigger unwanted module qualification wrapping).
+10. **Explicit Library Declarations**: Always explicitly import required library modules (e.g. `:- use_module(library(reif)).`, `:- use_module(library(dcgs)).`, `:- use_module(library(charsio)).`, `:- use_module(library(lambda)).`, `:- use_module(library(clpz)).`). Do not assume SWI-style autoloading when targeting ISO or embedded engines.
+11. **Control Structures & CLP(Z) Constraints**: Use standard ISO control structures `(,)/2`, `(;)/2`. Prefer CLP(Z) constraints (`#=`, `#>`, `all_distinct/1`) and reified arithmetic (`zcompare/3`, `'#='(X, Y, Truth)`, `clpz_t/2`) over low-level evaluation (`is/2`, `>/2`). Always post domain declarations (`ins`, `in`) before posting complex relations to enable early constraint propagation. Link model flags via `#<==>` (e.g. `X #> 10 #<==> B #= 1`) and pass partial closures `(#<)(0)` to `tfilter/3`.
+12. **Coroutining & Goal Suspension**: Use `freeze/2` for single-variable activation guards (`nonvar/1`) and `when/2` for multi-variable or disjunctive activation conditions (`(nonvar(A) ; nonvar(B))`). Prefer CLP(Z)/`dif/2` over manual coroutining where domain-specific constraints apply.
+13. **Clean Data Representations**: Prefer clean data structures where element kinds are distinguished by principal functor (`leaf(L)` vs `node(L, R)`). Avoid defaulty representations that force runtime type tests (`var/1`) or procedural default branches. Convert raw input data into clean trees early.
+14. **Macro & Compile-Time Expansion**: Use Prolog's macro mechanism (`user:term_expansion/2` and `user:goal_expansion/2`) to transform clauses or rewrite inline goals at compile time to eliminate boilerplate and redundant rules. Prefer static compile-time expansion over dynamic database modification (`asserta`/`assertz`).
+15. **Avoid Non-Standard Extensions**: Do not rely on engine-specific types (e.g. SWI dicts or SWI string types) when writing standard Prolog code.
+16. **Library Steering vs Reading Source**: Rely on dialect-specific Standard Library Cheat Sheets for module header declarations and predicate exports. AI assistants MUST NOT read raw standard library implementation source files, relying instead on concise cheat sheets and pre-trained semantics to save context tokens.
+17. **Safety**: Execute code using `prolog-safe`.
+
+18. **Prolog Tooling in Prolog (ISO Core + Engine Shims)**: Programs that parse, rewrite, transform, analyze, or generate Prolog source code SHOULD themselves be implemented in Prolog, exploiting the language's homoiconicity (code = terms = data). Structure such tools using an ISO-common core with flat, engine-specific shim files:
     - **ISO core** (`core.pl`): All term reading (`read_term/2`), DCG-based traversal and transformation, `copy_term/2`, `functor/3`, `=..`, and CLP(Z) constraints. This layer MUST NOT use engine-specific predicates or library paths.
     - **Flat shim files** (`scryer_shim.pl`, `swi_shim.pl`, `trealla_shim.pl`, etc.): Each shim defines only what differs per engine — module load paths, flag names, engine-specific built-ins — and exports a uniform interface consumed by the core.
     - **Entry point** (`run.pl`): Selects and loads the appropriate shim (e.g. via `PROLOG_ENGINE` flag or conditional compilation), then loads `core.pl`.

.agents/skills/prolog-dcg-mastery/SKILL.md

@@ -101,11 +101,18 @@ For complex programming languages or DSLs, split parsing into two pure DCG passe
 
 ---
 
-## 6. Higher-Order DCGs (`call//N`)
+## 6. Higher-Order DCGs (`call//N`) & Meta-Predicates
 
-Avoid duplicating DCG rules just to vary an element non-terminal or predicate. Use `call//N` to parameterize grammar rules:
+Avoid duplicating DCG rules just to vary an element non-terminal or predicate. Use `call//N` to parameterize grammar rules, and declare `:- meta_predicate` with `//` or `2` so closures resolve in the caller module context:
 
 ```prolog
+:- module(seq_combinators, [
+    seq_of//2
+]).
+
+:- meta_predicate
+    seq_of(?, //, ?, ?).
+
 % Generic DCG rule to match a list of elements using a parameter non-terminal nonterm//1
 seq_of([], _) --> [].
 seq_of([X|Xs], NonTerm) -->

CHANGELOG.md

@@ -1,3 +1,22 @@
+## [0.0.1.dev18] - 2026-08-31
+
+### Summary of Changes
+- Added Meta-Predicate Declarations (`:- meta_predicate`) guidelines and standards across `prolog-conventions`, `prolog-dcg-mastery`, `prolog-code-review`, `AGENTS.md`, and `prolog_guidelines.md`.
+- Added explicit rules for caller-module expansion, closure arity specifiers (`0`, `1`..`N`, `//`), and non-callable data term markings (`+`, `-`, `?`, `*`).
+- Updated Code Review checklist to audit module encapsulation and meta-predicate declarations.
+- Synchronized version `0.0.1.dev18` across manifests and documentation.
+
+### Added / Modified
+- `.agents/skills/prolog-conventions/SKILL.md`: Added Rule 9 on Meta-Predicate Declarations.
+- `.agents/skills/prolog-code-review/SKILL.md`: Added Meta-Predicate Declarations verification row to code review checklist.
+- `.agents/skills/prolog-dcg-mastery/SKILL.md`: Added meta-predicate declarations example for higher-order DCG non-terminals.
+- `.agents/AGENTS.md`: Added meta-predicate declaration standard to Universal Prolog Style & Purity Guidelines.
+- `.agents/references/prolog_guidelines.md`: Added detailed meta-predicate reference section.
+
+### Breaking Changes
+- None.
+
+
 ## [0.0.1.dev17] - 2026-08-29
 
 ### Summary of Changes

README.md

@@ -7,7 +7,7 @@
 [![Schema.org Metadata](https://img.shields.io/badge/schema.org-JSON--LD-brightgreen.svg)](schema.org.jsonld)
 [![Share on LinkedIn](https://img.shields.io/badge/Share_on-LinkedIn-0A66C2?logo=linkedin&logoColor=white)](https://www.linkedin.com/sharing/share-offsite/?url=https%3A%2F%2Fgithub.com%2Fdougransom%2Fprolog-agent-toolkit)
 
-**Version**: `0.0.1.dev17`  
+**Version**: `0.0.1.dev18`  
 **Category**: AI Assistant Developer Tools / Prolog Language Tooling  
 **Metadata**: [schema.org.jsonld](schema.org.jsonld)
 

docs/capability_manifest.json

@@ -1,6 +1,6 @@
 {
   "name": "Prolog Agent Toolkit Capability Manifest",
-  "version": "0.0.1.dev14",
+  "version": "0.0.1.dev18",
   "vendor_neutral": true,
   "description": "Reusable AI agent skills, coding standards, and safety execution toolkit for Prolog",
   "capabilities": {

docs/repository_ontology.json

@@ -2,7 +2,7 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "name": "Prolog Agent Toolkit Repository Ontology",
   "description": "Machine-readable graph mapping components, file dependencies, and structural relations",
-  "version": "0.0.1.dev14",
+  "version": "0.0.1.dev18",
   "nodes": [
     {
       "id": "pyproject.toml",

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "prolog-agent-toolkit"
-version = "0.0.1.dev17"
+version = "0.0.1.dev18"
 description = "Reusable AI agent skills, coding standards, and safety runner toolkit for multi-engine Prolog"
 readme = "README.md"
 requires-python = ">=3.9"