Repository navigation
Validation and Troubleshooting
PlainLogic has separate editor, structural-checking, and agent-review responsibilities.
| 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. |
From the main repository:
python tools/check_plainlogic.py examples/mixed-total.plog
python tools/check_plainlogic.py examples/mixed-total.plog --readyThe 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.
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.
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.
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.
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.
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.
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.
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.
In the source checkout:
npm run agents:check
npm run agents:sync
npm run agents:checkThe 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.
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.
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.
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.
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.
PlainLogic 0.3 · Home · Implementation source · Validation limits
Learn
Install and use
Check and contribute