Skip to content

Validation and Troubleshooting

Sceleratis edited this page Oct 20, 2026 · 1 revision

Validation and troubleshooting

PlainLogic has separate editor, structural-checking, and agent-review responsibilities.

What each layer establishes

Layer Implemented checks Limits
VS Code extension Editable document structure, declaration indexing, selected metadata links, indentation, readiness hints, and protected regions. A useful subset of canonical checking. No English interpretation, target grammar/type checking, or feasibility proof.
Python canonical checker Supported declarations and hard syntax, allowed call shapes, declared links, version gates, readiness, coverage declarations, and opaque-region boundaries. No execution, reference lookup, variable/type resolution, termination proof, case execution, or interpretation of prose, alias meaning, or native target code.
PlainLogic validation workflow Contextual consistency, behavior, data/control flow, target capability, source mappings, and consequential ambiguity. An agent judgment grounded in evidence. It is not formal verification or permission for external actions.
Target-language verification Focused syntax, build, or behavior checks chosen during implementation. Evidence for the checks performed; not an automatic consequence of a .plog case.

Canonical checker commands

From the main repository:

python tools/check_plainlogic.py examples/mixed-total.plog
python tools/check_plainlogic.py examples/mixed-total.plog --ready

The first accepts structurally valid drafts. The second also requires state ready. A ready document must have no open questions and declared coverage of every requirement. In 0.3, document-level coverage applies to top-level alias/native behavior; functions retain their own covers lines.

The CLI returns zero when there are no errors, even if warnings are present. It returns nonzero for errors. A file-read/encoding failure is also an error. It does not run supplied calls, cases, or native code.

Semantic outcomes

The agent scopes its assessment to the slice actually reviewed:

Outcome Meaning and next step
ready Enough behavior and context to implement the slice.
needs-decision Plausible interpretations change observable behavior; ask the consequential question.
needs-context Necessary source, runtime, contract, or documentation is unavailable; identify the evidence needed.
infeasible Verified capabilities or requirements conflict; explain the evidence and suggest a small revision.

The workflow checks source and existing conventions before asking questions. It asks one consequential question at a time and can continue independent ready work. Missing low-level details in otherwise clear English are not automatically blockers.

Common situations

A prose, alias, native, or missing-case warning appears

Opaque behavior and absence of reviewable cases can produce advisories. These are not structural errors. Review meaning and relevant examples; do not remove a useful English step merely to suppress the notice.

An informal function gets canonical header or signature errors

The Python CLI takes canonical documents. A return-first function fragment can still be valid input to the skill and supported by the editor. Review it directly, or normalize it into a complete canonical document when useful.

A draft fails --ready

Keep it draft until its material questions are resolved. Do not delete an open question or invent its answer solely to pass a check. Independent ready logic may be implemented as an explicitly identified slice.

A native region has no PlainLogic completion or rename

This protection is intentional. Its content belongs to the target language and remains opaque to PlainLogic tooling. The header, container margin, and extent are checked. See native blocks.

A rename is unavailable or leaves English unchanged

Navigation is local and lexical. Fields, parameters, ambiguous names, member accesses, named argument labels, native content, and inferred outer captures are not treated as fully resolved rename targets. A supported rename never rewrites English or alias descriptions. Review wording and unresolved cross-boundary references manually.

A valid older identifier is a new keyword

Versions 0.1 and 0.2 retain their original identifier rules for alias, native, target, and to. The 0.3 forms require a 0.3 canonical document. Check the header and distinguish an older identifier from actual new syntax.

Generated skill resources are stale

In the source checkout:

npm run agents:check
npm run agents:sync
npm run agents:check

The sync command refreshes the bundled language reference, checker, and examples from maintained repository sources. Edit those sources rather than treating generated snapshots as a second specification.

A plugin does not appear

Check the client-specific Codex or Claude Code instructions. Common distinctions are the marketplace name plainlogic-local, plugin name plainlogic, standalone versus plugin invocation, and local versus GitHub source. A GitHub installation reads the remote branch, not uncommitted local edits.

No PlainLogic region is found in a source file

The workflow leaves the file unchanged. Ordinary comments, examples, strings, TODOs, and comparisons are not commands. Use an intentional raw instruction in a code position or an explicit marked region. See Using PlainLogic.

Python is unavailable

The installed VS Code extension does not need Python. Python is required for the optional canonical checker and repository agent-package builder. The skill can review structure manually if the checker is unavailable and should disclose that limit.

Report a problem

Supply the .plog or minimal source region, its version/target context, the command or editor feature involved, and actual versus expected behavior. Distinguish an editor diagnostic, a CLI error, a target compiler error, and an agent interpretation so the failure can be reproduced.

Sources: checker, editor, core regression tests, and validation workflow.

Clone this wiki locally