plain-forge 1.0.18 → 1.0.19

package/forge/skills/load-plain-reference/references/project-model.md

@@ -0,0 +1,47 @@
+# ***plain project model
+
+Use this reference for project structure and language features not owned by a section-specific
+authoring rule.
+
+## Source-of-truth model
+
+`.plain` files are the source of truth. They describe observable behavior, implementation choices,
+and testing requirements. The renderer produces generated implementation and test artifacts from
+those specifications.
+
+## Typical repository structure
+
+```text
+*.plain                  # Root specification modules
+template/*.plain         # Reusable import modules
+resources/               # Linked text artifacts such as schemas and fixtures
+plain_modules/           # Generated implementation and unit tests
+conformance_tests/       # Generated conformance tests, grouped by module and functionality
+test_scripts/            # Unit, environment-preparation, and conformance runners
+config.yaml              # codeplain CLI configuration
+```
+
+The exact template directory can be configured. Follow the module and linked-resource rules for
+what these directories may contain and how a spec refers to them.
+
+## Template inclusion
+
+In addition to frontmatter `import`, ***plain supports parameterized template inclusion:
+
+```plain
+{% include "python-console-app-template.plain", main_executable_file_name: "my_app.py" %}
+```
+
+Parameters are key-value pairs. Templates access them with `{{ variable_name }}`. Only variable
+substitution is supported; conditionals, loops, and other Liquid features are not available.
+
+## Comments
+
+Lines beginning with `>` are ignored during rendering:
+
+```plain
+> This is a comment in ***plain.
+```
+
+Comments explain the specification to human authors. Do not use comments to carry requirements the
+renderer must implement.

package/forge/skills/load-plain-reference/references/rendering-and-testing.md

@@ -0,0 +1,57 @@
+# Rendering and testing workflow
+
+## Incremental rendering
+
+Functional specs render from top to bottom. When rendering one functional spec, the renderer knows
+the previous specs but not future specs. A required module's functional specs also count as previous
+specs according to the module rules.
+
+Each functional spec receives its own conformance-test folder. After a new spec renders, the
+renderer runs conformance tests for previous specs to detect regressions. A new failure can mean:
+
+1. The generated implementation does not satisfy the specification.
+2. The generated conformance test does not accurately test the specification.
+3. The new and previous specifications conflict.
+
+Diagnose which case applies, then correct the `.plain` source. Use the dedicated conflict-analysis
+and debugging skills rather than editing generated output.
+
+## Generated artifacts are read-only
+
+Everything under `plain_modules/` and `conformance_tests/` is generated. It may be read, executed,
+and debugged, but never edited directly. Apply fixes as follows:
+
+- Behavior or implementation/unit-test guidance: edit definitions, functional specs, or
+  implementation requirements as appropriate.
+- Conformance-test guidance: edit test requirements.
+- Acceptance-test guidance: edit the acceptance tests nested under their owning functional spec.
+
+Re-render after correcting the source specification.
+
+## Test-script roles
+
+Test scripts are renderer entry points as well as developer utilities:
+
+- `run_unittests_<lang>` receives the generated build folder and runs the complete generated unit
+  suite. It is self-contained and does not depend on environment preparation.
+- `prepare_environment_<lang>` optionally prepares a reusable system-temporary environment for
+  conformance testing once per render.
+- `run_conformance_tests_<lang>` receives the generated build folder and one functionality's
+  conformance-test folder. It may run repeatedly during a render.
+
+Invoke the corresponding `implement-*-script` skill when creating or changing a test script. Those
+skills own exact staging, cleanup, dependency-installation, shell, and exit-code contracts.
+
+## Common invocation shape
+
+Run project scripts from the repository root, using the filenames configured for that project:
+
+```bash
+./test_scripts/run_unittests.sh plain_modules/<module_name>
+./test_scripts/prepare_environment.sh plain_modules/<module_name>
+./test_scripts/run_conformance_tests.sh \
+  plain_modules/<module_name> conformance_tests/<module_name>/<functionality>
+```
+
+The renderer resolves script arguments to absolute paths. Test scripts must treat input directories
+as read-only and stage writes in their designated system-temporary working directory.

package/forge/skills/plain-healthcheck/SKILL.md

@@ -13,7 +13,7 @@ description: >-
 
 # Plain Healthcheck
 
-Always use the skill `load-plain-reference` to retrieve the ***plain syntax rules — but only if you haven't done so yet.
+Always use the skill `load-codeplain-reference` to retrieve the full `codeplain` CLI reference (every flag, path-resolution rules, `config.yaml` mapping, render banners, exit codes), and the skill `load-plain-reference` to retrieve the ***plain syntax rules — but only if you haven't done so yet. This skill runs `codeplain … --dry-run` and validates every `config.yaml`, so the CLI reference is required.
 
 ## When to run
 
@@ -54,7 +54,7 @@ For each `config.yaml` in the inventory, check **all** of the following. Collect
    - The path is a string ending in `.sh` (macOS/Linux) or `.ps1` (Windows). The extension must match the rest of the project — do not mix `.sh` and `.ps1` in a single config.
    - The referenced file actually exists on disk, resolved the way the renderer resolves it: absolute / `~` paths as-is, relative paths against the **config file's directory** (typically landing under `test_scripts/`). There is no other fallback — the renderer fails fast with a `FileNotFoundError` on a script path that doesn't resolve, so a path that only "works" from some other directory is a failure here.
    - On Unix, the script has the executable bit set (`-x`). If not, that is a fixable failure.
-4. **No mixed stacks per config.** Every script referenced from a single `config.yaml` must target the same language/stack. For example, `backend/config.yaml` should not reference `run_unittests_js.sh`. If a config crosses stacks, that is a failure — the project should have been split into multiple configs per the rule in `PLAIN_REFERENCE.md`.
+4. **No mixed stacks per config.** Every script referenced from a single `config.yaml` must target the same language/stack. For example, `backend/config.yaml` should not reference `run_unittests_js.sh`. If a config crosses stacks, that is a failure — the project should have been split into multiple configs per the applicable module rules loaded by `load-plain-reference`.
 5. **No dangling fields.** Any `*-script` field whose target file does not exist is a failure.
 6. **`prepare-environment-script` implies `conformance-tests-script`.** A `prepare-environment-script` only makes sense in service of conformance tests — the environment is what those tests run against. If a `config.yaml` declares `prepare-environment-script` but does **not** declare `conformance-tests-script`, that is a failure. Surface it to the user and offer to either (a) invoke `implement-conformance-testing-script` to add the missing script, or (b) remove the `prepare-environment-script` field if it was added in error. Do not auto-pick.
 7. **No orphan scripts.** Every script under `test_scripts/` should be referenced by *some* `config.yaml`. If a script is never referenced, surface it as a **warning** (not a hard failure — the user may be in the middle of authoring).

package/forge/skills/resolve-spec-conflict/SKILL.md

@@ -45,14 +45,22 @@ When the requirements truly conflict, choose a resolution strategy:
 
 **Strategy A: Add detail to disambiguate.** Often the specs aren't contradictory — they're just ambiguous enough that the renderer picks a conflicting interpretation. Adding explicit context to one or both specs eliminates the ambiguity.
 
-```
 Before (ambiguous):
-- The system should return all :Resource: items.
-- The system should return only active :Resource: items.
+```plain
+***functional specs***
+
+- All :Resource: items are returned.
+
+- Only active :Resource: items are returned.
+```
 
 After (disambiguated):
-- The system should return all :Resource: items when no filter is specified.
-- When the "active" filter is specified, the system should return only active :Resource: items.
+```plain
+***functional specs***
+
+- All :Resource: items are returned when no filter is specified.
+
+- When the "active" filter is specified, only active :Resource: items are returned.
 ```
 
 **Strategy B: Revise the newer spec.** If the new spec introduced the conflict, rewrite it to be compatible with the established behavior from earlier specs.

package/forge/skills/run-codeplain/SKILL.md

@@ -12,7 +12,7 @@ description: >-
 
 # Run Codeplain
 
-Always use the skill `load-plain-reference` to retrieve the ***plain syntax rules — but only if you haven't done so yet.
+Always use the skill `load-codeplain-reference` to retrieve the full `codeplain` CLI reference (every flag, path-resolution rules, `config.yaml` mapping, render banners, exit codes), and the skill `load-plain-reference` to retrieve the ***plain syntax rules — but only if you haven't done so yet. This skill drives the `codeplain` CLI, so the CLI reference is required before launching or resuming any render.
 
 ## What this skill is
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "plain-forge",
-  "version": "1.0.18",
+  "version": "1.0.19",
   "description": "Conversational spec-writing tool for ***plain specification language",
   "type": "module",
   "engines": {

package/forge/rules/line-length.md

@@ -1,45 +0,0 @@
----
-description: Line-length and bullet-continuation rules for every section in .plain files
----
-
-# Rules for line length in `.plain` files
-
-These rules apply to **every** section — `***definitions***`, `***implementation reqs***`, `***test reqs***`, `***functional specs***`, `***acceptance tests***` — and to concept explanations alike.
-
-## Hard limit: 120 characters per line
-- If a line exceeds 120 characters, split it at a natural clause boundary into nested `- ` bullets
-- Concision is in service of clarity, never the other way around — wordy-but-precise always beats terse-but-ambiguous
-- Prefer short, direct sentences and plain words; if a 10-cent word and a 50-cent word say the same thing, use the 10-cent one
-
-## Never use bare continuation lines (invalid ***plain syntax)
-- ***plain syntax requires every line inside a section to be its own list item starting with `- `
-- Indented continuation lines without a leading `- ` are syntactically invalid — they look reasonable to a human reader but the renderer cannot parse them
-- When a sentence is too long, **break it into multiple bullet items**, each on its own line, nested under the parent bullet so the meaning stays grouped
-
-## Examples
-
-BAD — line is too long:
-
-```plain
-- :GatewayWebhook: should hand off :StripeRequest: to :StripeIntegration:.handle(), which returns a list of :EventEnvelope: dicts conforming to the gateway's contract.
-```
-
-WRONG SYNTAX (AVOID AT ALL COSTS) — bare indented continuation without a leading `- `:
-
-```plain
-- :GatewayWebhook: should hand off :StripeRequest: to :StripeIntegration:.handle(),
-  which returns a list of :EventEnvelope: dicts conforming to the gateway's
-  contract.
-```
-
-GOOD — split at a natural clause boundary into nested `- ` bullets:
-
-```plain
-- :GatewayWebhook: should hand off :StripeRequest: to :StripeIntegration:.handle()
-  - The method returns a list of :EventEnvelope: dicts.
-  - The dicts must conform to the gateway's :EventEnvelope: contract.
-```
-
-## What never goes inline
-- Long URLs, schema fragments, or example payloads — those belong in `resources/` per [`linked-resources.md`](linked-resources.md)
-- If you find yourself pasting a multi-line block into a spec line, stop and link the file instead