plain-forge 1.0.18 → 1.0.20

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

@@ -0,0 +1,48 @@
+# ***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 output, one directory per module
+  <module>/code/         #   implementation and unit tests
+  <module>/tests/        #   conformance tests, one folder per functional spec
+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/` is generated — both `<module>/code/` and `<module>/tests/`. 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 (`plain_modules/<module_name>/tests/<functionality>`). 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>/code
+./test_scripts/prepare_environment.sh plain_modules/<module_name>/code
+./test_scripts/run_conformance_tests.sh \
+  plain_modules/<module_name>/code plain_modules/<module_name>/tests/<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).
@@ -90,7 +90,7 @@ Treat the dry-run as a hard gate: the healthcheck **only passes** when every top
 Iterate until it passes:
 
 1. Read the error output. If the first run was not verbose, immediately re-run with `--verbose`. Identify the offending `.plain` file, the line (if reported), and the kind of issue: missing concept, syntax error, cyclic definition, complexity violation (`Functional spec too complex!`), conflicting reqs, missing template, broken `import`/`requires`, missing config field, etc.
-2. Fix only the `.plain` files (or the relevant `config.yaml` / template) using the appropriate edit skill — `add-concept`, `add-functional-spec`, `add-functional-specs`, `add-implementation-requirement`, `resolve-spec-conflict`, `break-down-func-spec`, `consolidate-concepts`, or an inline edit. **Never** modify generated code under `plain_modules/` or `conformance_tests/`.
+2. Fix only the `.plain` files (or the relevant `config.yaml` / template) using the appropriate edit skill — `add-concept`, `add-functional-spec`, `add-functional-specs`, `add-implementation-requirement`, `resolve-spec-conflict`, `break-down-func-spec`, `consolidate-concepts`, or an inline edit. **Never** modify generated code under `plain_modules/<module>/code/` or `plain_modules/<module>/tests/`.
 3. If you are uncertain about ***plain syntax for the failing construct, re-load `load-plain-reference` before fixing.
 4. Re-run the same `codeplain <top_module>.plain --dry-run …` command with the same flags. Repeat until it exits successfully.
 

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
 
@@ -21,7 +21,7 @@ A **supervisor** around a live `codeplain` render. The renderer itself is the co
 1. Launches `codeplain <module>.plain` (or attaches to an in-flight run).
 2. Watches three signal sources in a tight loop, in priority order:
    - **`codeplain.log`** — the primary signal. Everything the renderer is doing, deciding, retrying, or failing at gets written here. This is the file you stare at.
-   - the generated **code outputs** under `plain_modules/<module>/` and `conformance_tests/<module>/` — a secondary signal, used to corroborate or contradict what the log says.
+   - the generated **code outputs** under `plain_modules/<module>/` and `plain_modules/<module>/tests/` — a secondary signal, used to corroborate or contradict what the log says.
    - the **process / TUI** itself (alive? exited? exit code?) — a tertiary signal, used only to know whether to keep monitoring.
 3. Surfaces what is happening to the user in plain English, in near-real-time.
 4. On pathology, stops the renderer (with user approval), hands off to the right edit skill, and resumes from the last completed functionality.
@@ -76,7 +76,7 @@ Before launching anything:
    - **What "pass" means**, exit-code-wise. Some scripts combine multiple checks (e.g. `unit_testing_typescript.sh` here runs `tsc --noEmit` *and* `vitest`, and its final exit code is the worst of the two — so a type error alone fails the unit-test gate).
    - **What "fail" means**, including any failures that the script deliberately downgrades to warnings (e.g. `prepare_environment_typescript.sh` here treats a failed `npm run build` as a non-fatal warning). Failures the script swallows are failures the renderer will **never see**, so a spec defect that depends on them will silently slip through.
    - **Where the scripts materialize their working environment** (current-convention scripts stage into the system temp directory, e.g. `/tmp/typescript_<build_folder_basename>/`; older scripts used project-local folders like `.tmp/typescript_<build_folder>/`, `build/`, `target/`). This is where the renderer's iteration actually runs; if you need to look at what is breaking, this is the directory — not `plain_modules/<module>/` directly.
-   - **How conformance tests are discovered and staged** (glob, naming convention, alias setup, etc.). Some scripts stage tests into the source tree (this repo flattens `conformance_tests/<module>/<fname>/` into `src/<module>/`); some run them in place; some require a specific file extension. This tells you exactly which conformance test file is in play for a given functionality.
+   - **How conformance tests are discovered and staged** (glob, naming convention, alias setup, etc.). Some scripts stage tests into the source tree (this repo flattens `plain_modules/<module>/tests/<fname>/` into `src/<module>/`); some run them in place; some require a specific file extension. This tells you exactly which conformance test file is in play for a given functionality.
    - **Toolchain prerequisites** the script asserts (Node version, Python version, specific binaries). If any are missing on the user's machine, stop now and tell them — the renderer will burn credits on phantom failures otherwise.
 
    Keep this synthesis short (5–10 bullets, project-specific). It is the single most important reference for the classifier in [Spec-deviation classification](#spec-deviation-classification). The healthcheck only checks that the scripts *exist* and are *referenced correctly*; this step is the only place that reads what they actually *do*.
@@ -132,7 +132,7 @@ All patterns below are taken from the actual codeplain runtime. Treat them as th
 | `Implementing conformance tests...` / `Implementing test requirements:` | Conformance phase starting for the current functionality. | Routine. |
 | `Running testing environment preparation script .* for build folder` | `prepare-environment-script` is running. | Routine. |
 | `\[#79FC96\]All Testing Environment Preparation scripts have passed successfully.\[/#79FC96\]` | Env prep green. | Routine. |
-| `Running conformance tests script .* for conformance_tests/<m>/<fname> \(functionality <N> in module <m>\)` | Conformance tests starting for functionality `<N>`. | Note `<fname>` — that is the on-disk folder where the latest conformance test lives. |
+| `Running conformance tests script .* for plain_modules/<m>/tests/<fname> \(functionality <N> in module <m>\)` | Conformance tests starting for functionality `<N>`. | Note `<fname>` — that is the on-disk folder where the latest conformance test lives. |
 | `Running conformance tests attempt <N>.` | Conformance retry loop. **Watch `<N>` carefully.** | Increment `ATTEMPT_COUNTER = <N>`. At `>=5`, trigger Pathology A. |
 | `Fixing conformance test for functionality <N> in module <m>.` | Renderer is patching its own conformance test between attempts. | On its own, routine. Combined with climbing `<N>`, smoking gun for Pathology A. |
 | `Functional spec too complex!` | Single spec implies >200 LOC. Renderer aborts. | Pathology B. |
@@ -199,7 +199,7 @@ What to extract from the framework output — stay framework-agnostic, look for
 - **Individual test names that failed**: lines beginning with `×`, `FAIL`, `✗`, `× should ...`, `FAIL src/.../foo.test.ts > <name>`. The *same* test failing across attempts is the smoking gun for an under-specified spec.
 - **Assertion bodies**: `expected X, got Y`. The values reveal exactly what the test expects vs what the implementation produced — the cleanest input to the classifier below.
 - **Compile / type errors** (when the script wraps a type-checker): `error TS<NNNN>`, `cannot find module`, `is not assignable to`. A unit-test gate that keeps re-failing on the same type error means the implementation req or the type-level spec is wrong, not the code.
-- **Stack traces**: which file under the prepared working folder threw, and at which line. Map the file back to `plain_modules/<module>/src/...` to find the code the spec is supposed to be governing.
+- **Stack traces**: which file under the prepared working folder threw, and at which line. Map the file back to `plain_modules/<module>/code/...` to find the code the spec is supposed to be governing.
 - **"No test files found" / "No tests collected"**: the script ran but discovered nothing. Almost always a path/glob mismatch in the staged working folder, not a spec problem. Treat as Pathology F.
 
 Always set the logs to be verbose in `config.yaml`. 
@@ -232,8 +232,8 @@ The inputs to the classifier are:
 1. The **spec** that governs the failing functionality — the functional spec and its acceptance test(s) in the `.plain` file.
 2. The **test-script output** for the most recent attempt, from `codeplain.log` per the section above.
 3. The renderer's own **`.memory/conformance_test_memory/<id>.json`** for this functionality (when present).
-4. The newest **conformance test file** the renderer just edited under `conformance_tests/<module>/<fname>/`.
-5. The newest **implementation file(s)** the renderer just edited under `plain_modules/<module>/`.
+4. The newest **conformance test file** the renderer just edited under `plain_modules/<module>/tests/<fname>/`.
+5. The newest **implementation file(s)** the renderer just edited under `plain_modules/<module>/code/`.
 
 With these in hand, place the current iteration into one of four buckets:
 
@@ -320,15 +320,15 @@ If the process is gone but you haven't yet seen a `✓` or `✗` banner in the l
 
 This is a secondary signal — it confirms what the log already said. Don't go on a fishing trip here.
 
-For the current module, the renderer drops generated code into `plain_modules/<module>/` and conformance tests into `conformance_tests/<module>/<functionality_name>/`. Each pass, inspect what is new:
+For the current module, the renderer drops generated code into `plain_modules/<module>/` and conformance tests into `plain_modules/<module>/tests/<functionality_name>/`. Each pass, inspect what is new:
 
-- New files under `plain_modules/<module>/src/` confirm the functionality is being implemented.
-- New folders under `conformance_tests/<module>/` confirm the functionality has reached the conformance phase.
+- New files under `plain_modules/<module>/code/` confirm the functionality is being implemented.
+- New folders under `plain_modules/<module>/tests/` confirm the functionality has reached the conformance phase.
 - Files that were rewritten between passes are the renderer's "fix" attempts — diffing them across iterations is what reveals whether the renderer is converging or thrashing.
 
 Read **only the newest** file(s) (the ones that changed since last pass), and read them to understand *what the renderer chose to do*, not just *that* it did something. This is the first line of defense against "the spec is ambiguous and the renderer guessed wrong" — you can often spot the wrong guess in the generated code long before tests fail.
 
-Generated code under `plain_modules/` and `conformance_tests/` is **read-only**. Never edit it. Edits go in the `.plain` files.
+Generated code under `plain_modules/<module>/code/` and `plain_modules/<module>/tests/` is **read-only**. Never edit it. Edits go in the `.plain` files.
 
 ### 1d. Cadence
 
@@ -384,7 +384,7 @@ Symptom: log shows the unit-test or conformance-test **script** itself failing (
 
 ```
 ImportError: Start directory is not importable
-/Users/x/project//Users/x/project/conformance_tests/module/spec
+/Users/x/project//Users/x/project/plain_modules/module/tests/spec
 ```
 
 The render then gets stuck "fixing" tests that can never pass. The fix is never a spec edit: stop the render and regenerate the affected scripts via the matching `implement-*-testing-script` skill (current convention: system-temp working folder from `basename "$1"`, `$2` resolved to absolute before any `cd`).
@@ -434,7 +434,7 @@ If the fix required regenerating a module's earlier output (e.g. a definition ch
 When the renderer exits successfully:
 
 1. Read the success banner from the log: render id, generated code folder, functionalities count, used credits, render time. Report it to the user verbatim — these are the numbers they actually care about.
-2. List the top-level files/folders that appeared (or changed) under `plain_modules/<module>/` and `conformance_tests/<module>/` so the user knows where to look.
+2. List the top-level files/folders that appeared (or changed) under `plain_modules/<module>/` and `plain_modules/<module>/tests/` so the user knows where to look.
 3. Remind the user of the **side-channel commands** they may want to run themselves, based on the config:
    - `./test_scripts/<unittests-script>` for unit tests,
    - `./test_scripts/<prepare-environment-script>` to set up the test env,
@@ -446,7 +446,7 @@ When the renderer exits with a failure that wasn't intercepted by Phase 2 (e.g.
 
 ## Anti-patterns
 
-- **Editing generated code to "fix" a render.** Never. Generated files under `plain_modules/` and `conformance_tests/` exist as evidence only; they are overwritten every render. All fixes go in `.plain` files.
+- **Editing generated code to "fix" a render.** Never. Generated files under `plain_modules/<module>/code/` and `plain_modules/<module>/tests/` exist as evidence only; they are overwritten every render. All fixes go in `.plain` files.
 - **Reading the test scripts' source code to understand what's failing.** Don't. The scripts run real frameworks (vitest, pytest, etc.) and the *output* of those frameworks — captured in `codeplain.log` and in `.memory/conformance_test_memory/*.json` — is what tells you what is failing and why. Reading the script source tells you nothing the log doesn't already say.
 - **Treating every conformance loop as under-specification.** Run the classifier. The renderer sometimes drifts (Bucket 3) by silently weakening its own tests; that is the opposite problem and the fix is different.
 - **Re-reading the whole log on every pass.** It grows. Track the byte offset and read only what was appended since the last pass. Full reads are reserved for "I just saw an error and need backstory."
@@ -480,4 +480,4 @@ When the renderer exits with a failure that wasn't intercepted by Phase 2 (e.g.
 - [ ] Spec fixes were delegated to the right edit skill, not done inside this skill
 - [ ] Resumes use `--render-from <N+1>` (or `--render-range`) — `--force-render` only with user approval
 - [ ] On success, final render id / credits / time were reported and side-channel test commands were surfaced
-- [ ] No generated code under `plain_modules/` or `conformance_tests/` was modified
+- [ ] No generated code under `plain_modules/<module>/code/` or `plain_modules/<module>/tests/` was modified

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "plain-forge",
-  "version": "1.0.18",
+  "version": "1.0.20",
   "description": "Conversational spec-writing tool for ***plain specification language",
   "type": "module",
   "engines": {
@@ -33,7 +33,7 @@
   "scripts": {
     "build": "tsx bin/forge-build.ts",
     "clean": "tsx bin/forge-build.ts --clean",
-    "test": "node --test \"test/**/*.test.mjs\""
+    "test": "node --test test/*.test.mjs"
   },
   "devDependencies": {
     "@types/node": "^22.10.0",

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