plain-forge 1.0.21 → 1.0.22-next.2d602b1

package/README.md

@@ -34,6 +34,7 @@ Pick whichever entry point matches how much upfront design you want:
 
 - **`debug-specs`** — when the rendered app misbehaves, this traces the generated code back to the spec that caused it and fixes the spec (never the generated code).
 - **`run-codeplain`** — experimental supervised render. Launches `codeplain` for you, tails the log, watches generated code appear under `plain_modules/`, and detects pathologies (stuck conformance loops, complexity errors, missing concepts, render failures). On approval it stops the renderer, hands off to the right spec-edit skill, and resumes.
+- **`render-spec`** — [pyro](https://github.com/plainlang/pyro), the open-source ***plain renderer, bundled with plain-forge. Renders a `.plain` module (and the modules it requires or imports) into working, tested code directly inside your agent. See [Render with pyro](#render-with-pyro).
 - **`implement-unit-testing-script`** / **`implement-conformance-testing-script`** / **`implement-prepare-environment-script`** — generate the per-language testing scripts that the renderer and you both invoke. New languages can be added by these skills without touching any other part of the project.
 
 Each skill operates on the same one-question-at-a-time, write-immediately, refine-through-follow-ups loop. Specs land on disk after every answer; later answers fix earlier writes in place. There is no batched interview, no "I'll gather context first," and no hand-authored functional specs — every new spec goes through the authoring skills so the complexity and conflict checks actually run.
@@ -187,6 +188,23 @@ If you'd rather have plain-forge babysit the run from your AI coding agent, invo
 
 This is an **experimental** feature — the default and most reliable way to render is still the manual `codeplain <module>.plain` invocation above.
 
+#### Render with pyro
+
+plain-forge ships [pyro](https://github.com/plainlang/pyro), an open-source renderer packaged as the `render-spec` skill that renders inside your AI coding agent. Invoke it with the module to render:
+
+```
+/render-spec <module>.plain
+```
+
+It resolves the modules the target requires or imports, renders them in dependency order, and writes:
+
+- implementation code and unit tests to `plain_module/code/`
+- conformance tests to `plain_module/tests/`
+- the target module's final output to `dist/`
+- its working files (render plan, dependencies, scenarios, requirement lists) to `.pyro/`
+
+pyro needs **Python 3.8 or newer** on the machine and nothing else. `npx plain-forge@latest update` updates pyro along with the rest of plain-forge.
+
 ### Debugging specs
 
 Hit a bug in the rendered app, a failing test, or behavior that doesn't match what you specified?
@@ -210,12 +228,39 @@ forge/                       # canonical content, copied verbatim on install
 bin/
   cli.mjs                    # the `plain-forge` CLI — `install` and `update` commands
 
+vendor/
+  pyro/                      # git submodule: plainlang/pyro, pinned to the release plain-forge ships
+
+scripts/
+  bundle-pyro.sh             # copies vendor/pyro's `render-spec` skill into forge/skills/ at publish time
+  deploy.sh                  # publishes a release to npm from a workstation
+
 test/
   cli.test.mjs               # tests for the install / update CLI
 
 package.json                 # ships only `bin/cli.mjs` and `forge/` to npm
 ```
 
+### Bundled pyro skill
+
+The `render-spec` skill comes from [pyro](https://github.com/plainlang/pyro), which has its own release cycle. It is included as a **git submodule** at [`vendor/pyro`](vendor/pyro), so the exact pyro commit plain-forge ships is visible in the repository. Clone with submodules:
+
+```bash
+git clone --recurse-submodules https://github.com/plainlang/plain-forge.git
+# or, in an existing clone:
+git submodule update --init
+```
+
+Agents only discover skills that sit directly under `skills/`, so the npm publish CI job copies `vendor/pyro/skills/render-spec` into `forge/skills/render-spec` (gitignored) with `scripts/bundle-pyro.sh` just before `npm publish`. Run the script yourself to try the skill locally.
+
+To ship a newer pyro, bump the submodule to pyro's `main` (it only ever points at pyro's latest stable release) and commit the new pointer:
+
+```bash
+git submodule update --remote vendor/pyro
+git add vendor/pyro
+git commit -m "Bump pyro to vX.Y.Z"
+```
+
 On `install`, the CLI reads `forge/skills` and `forge/rules` and writes them into the chosen agent directory (`.claude/`, `.agents/` for Codex/Copilot/universal, `.forge/`, or `.opencode/` — see the per-agent table above for global-scope paths), recording every file it wrote in `<agent-dir>/.plain-forge/manifest.json` so `update` can later refresh and prune precisely. For agents that need it, it also wires the rules into `opencode.json` or ForgeCode's `AGENTS.md` (see [How the rules get applied per agent](#how-the-rules-get-applied-per-agent)).
 
 ## Available Skills
@@ -227,6 +272,7 @@ On `install`, the CLI reads `forge/skills` and `forge/rules` and writes them int
 | `forge-plain` | End-to-end QA interview that produces complete `.plain` spec files for a new project |
 | `init-plain-project` | Lightweight project initializer — scaffolds `template/base.plain` (base impl + test reqs), a stub top-level module, the testing scripts, and `config.yaml`. No functional specs, no concepts, no dry-run. Pair with `add-feature` to grow the project feature-by-feature. |
 | `add-feature` | Interview the user about a single feature, then write all the specs for it |
+| `render-spec` | [pyro](https://github.com/plainlang/pyro), the open-source renderer: renders a `.plain` module and the modules it requires or imports into working, tested code, from inside your agent. See [Render with pyro](#render-with-pyro). |
 | `run-codeplain` | **Experimental.** Launch a `codeplain` render and supervise it end-to-end — tails `codeplain.log`, watches generated code appear, detects pathologies (stuck conformance loops, complexity errors, missing concepts, render failures), and on approval stops the renderer, hands off to the right spec-edit skill, and resumes with `--render-from`. The default render path is still the manual `codeplain <module>.plain` command. |
 
 ### Spec Authoring

package/forge/rules/linked-resources.md

@@ -61,6 +61,9 @@ A linked resource **must not** be any of the following:
 ```
 
 ## File location and path resolution
-- Paths are resolved relative to the directory where `codeplain` is run (the current working directory)
+- Paths are resolved against the directory that contains the `.plain` file passed to `codeplain`, not the directory where `codeplain` is run
+- This includes links inside imported and required modules — they resolve against that same directory, not against the directory the imported module itself lives in
+- A path that does not resolve there is then looked up in the `--template-dir` directory (if given), and last in the built-in `standard_template_library`
+- Because the `.plain` file's own directory is the anchor, a render gives the same result from any working directory
 - Relative paths may traverse into parent directories — `[resource](../../resources/resource.md)` is valid — as long as they resolve to a real text file on disk
-- The conventional location is a `resources/` directory; keep the resource inside the project so the path stays stable from wherever `codeplain` is run
+- The conventional location is a `resources/` directory next to the `.plain` file

package/forge/skills/add-resource/SKILL.md

@@ -40,7 +40,9 @@ Use standard markdown link syntax inside any spec section:
 
 ## Path Rules
 
-- Paths are resolved **relative to the directory where `codeplain` is run** (the current working directory).
+- Paths are resolved **against the directory that contains the `.plain` file passed to `codeplain`**, not the directory where `codeplain` is run.
+- This includes links inside imported and required modules — they resolve against that same directory, not against the directory the imported module itself lives in.
+- A path that does not resolve there is then looked up in the `--template-dir` directory (if given), and last in the built-in `standard_template_library`.
 - Relative paths may traverse into parent directories — `[resource](../../resources/resource.md)` is valid — as long as they resolve to a real text file on disk.
 - **No external URLs** — only local file references.
 - **No folder paths** — the target must be a file, not a directory.
@@ -69,7 +71,7 @@ The **only** exceptions are URLs and paths that are *values the produced softwar
 
 ### What a linked resource CAN be
 
-- A single file inside the project, reachable by a path relative to where `codeplain` is run — parent-directory traversal (`../`) is allowed (`resources/` is the conventional home).
+- A single file inside the project, reachable by a path relative to the `.plain` file — parent-directory traversal (`../`) is allowed (`resources/` is the conventional home).
 - A **text-based** file the renderer can read end-to-end: JSON, YAML, XML, HTML, Markdown, plain text, CSV, TSV, source code in any language (`.py`, `.js`, `.ts`, `.go`, `.java`, `.rb`, `.rs`, `.kt`, `.swift`, `.c`, `.cpp`, `.cs`, …), shell scripts, SQL, JSON Schema, OpenAPI, AsyncAPI, Protobuf `.proto`, GraphQL SDL, `.jolt`, `.env.example`, `.toml`, `.ini`, `.proto`, `Dockerfile`, etc.
 
 ## Common Resource Types
@@ -101,6 +103,6 @@ The **only** exceptions are URLs and paths that are *values the produced softwar
 - [ ] **Target is a text-based file** (no binary extensions: `.png`, `.jpg`, `.jpeg`, `.gif`, `.bmp`, `.tiff`, `.webp`, `.ico`, `.pdf`, `.docx`, `.xlsx`, `.pptx`, `.zip`, `.tar`, `.gz`, `.mp3`, `.mp4`, `.wav`, `.exe`, `.so`, `.dylib`, `.class`, `.wasm`, …)
 - [ ] **No URLs or folder paths anywhere in the surrounding `.plain` content** (not as link targets, not in body prose), with the sole exception of URLs / paths that are runtime values the generated software itself uses
 - [ ] Path is relative to the `.plain` file, not absolute
-- [ ] Path resolves to a real text file on disk from where `codeplain` is run (`../` traversal is allowed)
+- [ ] Path resolves to a real text file on disk relative to the `.plain` file (`../` traversal is allowed)
 - [ ] Markdown link syntax is correct: `[display text](relative/path)`
 - [ ] Resource content is relevant and adds value beyond what the spec text says

package/forge/skills/render-spec/SKILL.md

@@ -0,0 +1,164 @@
+---
+name: render-spec
+description: >-
+  Renders a .plain specification module into working, tested code. Use when
+  asked to render, build, or implement a .plain spec file or module: resolves
+  and renders its required/imported modules in dependency order, producing
+  implementation code in plain_module/code/, conformance tests in
+  plain_module/tests/, and the target module's output in dist/.
+metadata:
+  version: "0.4.0"
+---
+
+# Skill instructions
+
+When starting each step or substep, report with a message "Starting Step <Step_ID>: <Description>".
+
+Do every step yourself. Never hand any step to a subagent, Agent/Task tool or workflow. Module count or spec size are not exceptions.
+
+# Step 0: Python interpreter and version check
+
+`<skill_folder>` is the absolute path of the directory holding this `SKILL.md`. Resolve it now and reuse it everywhere in this skill where `<skill_folder>` is used:
+  * On Claude Code it is `${CLAUDE_SKILL_DIR}`; on other agents derive it from the location this skill was loaded from.
+  * Never reach a file inside this skill by a relative path.
+
+`<python>` is required Python 3.8 or newer. Resolve it now and reuse it everywhere in this skill where `<python>` is used. Try these candidates one at a time, in this order, and stop at the first one whose output contains a `current:` line - its interpreter is `<python>`. Do not run the remaining candidates once one has succeeded, and do not run them in parallel:
+1. `python3 "<skill_folder>/scripts/check_version.py" check`
+2. `py -3 "<skill_folder>/scripts/check_version.py" check`
+3. `python "<skill_folder>/scripts/check_version.py" check`
+
+Report the Python tool you settled on. If none of the three prints a `current:` line, Python is a missing dependency: abort the rendering and report it.
+
+From that same command's output report with a message "Running pyro: <current>".
+* If the output shows `status: update-available`, warn with a message: "A newer pyro release <latest> is available (this is <current>)".
+* On any other status, say nothing about updates and continue.
+
+# Step 1: Introduction, inputs and outputs
+
+Your mission is to implement software code as defined by .plain specifications (specs).
+To understand the specs language, load the complete `<skill_folder>/references/plain-lang.md`.
+
+Input arguments are:
+* <TargetModule> which is the filename of to the module spec to be rendered.
+
+Inputs artifacts are:
+* specs of <TargetModule> and the modules it requires or imports, including referenced files inside the specs.
+
+Generated artifacts are:
+* :RenderPlan: is a table listing all the modules for rendering and current render state. :RenderPlan: lives in `./.pyro/render-plan.md`.
+* :plainImplementationCode: lives under `./plain_module/code`. Every module is rendered into this same folder, each building on top of the previously rendered ones.
+* :ConformanceTests: are living under `./plain_module/tests`.
+* Internal working files (dependencies, per-module scenarios and requirements) live under `./.pyro`.
+
+### Available tools and paths
+
+`<python>` is the interpreter resolved in Step 0 - always run them with it, and never through a shell of your own, so the same command line works on macOS, Linux and Windows alike.
+
+`scripts/plain_sections.py` extracts one section out of any number of specs and prints it to stdout:
+  `<python> "<skill_folder>/scripts/plain_sections.py" [--include-filename] [--output <path>] <section> <spec.plain> [<spec.plain> ...]`
+  * `<section>` is one of `defs`, `impl-reqs`, `test-reqs`, `func-specs`, `acc-tests`, `all`.
+  * `--output <path>` writes the result to `<path>`.
+  * Always gather sections with this script - never transcribe or summarize them by hand.
+
+# Step 2: Prepare the :RenderPlan:
+
+Find and read the frontmatter of <TargetModule> and all specs that <TargetModule> requires.
+
+Ensure there are no loops in the dependency graph of modules. If there are, abandon the work and describe the error (loop).
+
+Prepare the optimal order for rendering <TargetModule> and all the required modules based on the dependency graph.
+
+Prepare a :RenderPlan: : List all the modules to be rendered in the planned rendering order in the example format from `<skill_folder>/references/render-plan.md` and write it to :RenderPlan: file (overwrite if already exists).
+
+
+## Step 3: Verifying the environment
+
+If any dependency is missing - DO NOT INSTALL ANYTHING, but do:
+* immediatly abort the rendering
+* report with message listing missing dependencies.
+
+### Step 3.1: Dependencies
+
+Report with a message "Step 3.1: Dependencies".
+
+Gather all :plainImplementationReqs: and :plainTestReqs: from all specs of the modules' to be rendered:
+* `<python> "<skill_folder>/scripts/plain_sections.py" --include-filename impl-reqs <all specs to be rendered>`
+* `<python> "<skill_folder>/scripts/plain_sections.py" --include-filename test-reqs <all specs to be rendered>`
+
+Write a list of all the required dependencies for implementation and for tests into `.pyro/dependencies.md` file. Verify all the all the dependendencies are present and update the list.
+
+Report with a message showing the `.pyro/dependencies.md`.
+
+
+## Step 4: Rendering
+
+Render every module yourself - never delegate any module to a subagent, Agent/Task tool or workflow.
+
+Before rendering the first module, create the folders `plain_module/code`, `plain_module/tests` and `.pyro` (skip any that already exist).
+
+Load the :RenderPlan: and for every module follow precisely the steps:
+
+### Step 4.1: Specs, reqs, test scenarios
+Report with a message "Step 4.1: Loading specs, writing reqs and test scenarios for: <module> + <required-or-imported-modules>".
+
+Run the command with helper script, where <specs> are the module's spec followed by the specs of its imported or required modules:
+`<python> "<skill_folder>/scripts/plain_sections.py" all <specs>`
+The output of this command are all the necessary specs for succesfully rendering this module.
+
+Write exhaustive conformance test scenarios for every :plainFunctionality: of the <module>'s spec into `.pyro/<module>/scenarios.md`.
+* Scenarios should exhaustively test every :plainFunctionality: and should include :AcceptanceTests:.
+* Get the <module>'s :AcceptanceTests: with `<python> "<skill_folder>/scripts/plain_sections.py" acc-tests <module spec>` and cover every one of them.
+
+Write the lists of requirements using the helper script, where <specs> are module's spec plus the specs of its imported modules:
+* impl. reqs: `<python> "<skill_folder>/scripts/plain_sections.py" impl-reqs <specs> --output .pyro/<module>/impl-reqs.md`
+* test reqs: `<python> "<skill_folder>/scripts/plain_sections.py" test-reqs <specs> --output .pyro/<module>/test-reqs.md`
+Both lists hold the requirements verbatim - never paraphrase, reorder or drop any of them.
+  
+### Step 4.2: Implement code and tests
+Report with a message "Step 4.2: Implementation of <module>".
+
+All the implementation code must be put in the self-contained `plain_module/code` folder. Nothing outside of `plain_module` and `.pyro` folders can be touched during this step.
+
+Implement all :plainFunctionality: of <module> specs while respecting all the requirements written in `.pyro/<module>/impl-reqs.md`.
+
+Implement :UnitTests:.
+
+Implement :ConformanceTests: covering all test scenarios:
+* Read all test scenarios from `.pyro/<module>/scenarios.md`.
+* Read test requirements in `.pyro/<module>/test-reqs.md`.
+* Implement the conformance tests covering all test scenarios and respecting test requirements into the `plain_module/tests` folder.
+
+### Step 4.3: Tests verification
+Report with a message "#Step 4.3: Tests verification of <module>".
+
+If any tests are failing, go back to the implementation step (4.2), debug it and fix implementation code:
+* Run and verify all :ConformanceTests: are passing.
+* Run and verify all :UnitTests: are passing.
+
+### Step 4.4: Reqs verification
+Report with a message "Step 4.4: Reqs verification of <module>".
+
+Read the list `.pyro/<module>/impl-reqs.md` and for every item:
+* Review if the implementation respects it.
+* Add checkbox with checked/unchecked status to the item.
+
+Read the list `.pyro/<module>/test-reqs.md` and for every item:
+* Review if the conformance tests respect it.
+* Add checkbox with checked/unchecked status to the item.
+
+IMPORTANT: if any requirement list item is not passing, go back to the implementation (step 4.2), debug and fix it in the code.
+
+
+When all 4.x steps are done, continue with rendering the next module until no more modules are left.
+
+## Step 5: Finalize and report
+
+When all modules are rendered do:
+- remove installed dependency artifacts (e.g. `node_modules/`, `.venv/`, `__pycache__/`, vendored packages) in `plain_module/code`, but keep the dependency manifests and lock files so dependencies can be reinstalled later.
+- copy all of the files in the `plain_module/code` folder to the `./dist` folder:
+  `<python> "<skill_folder>/scripts/copy_folder.py" plain_module/code dist`
+- prepare a short report on the :plainImplementationCode: and :ConformanceTests:
+- present commands to run tests (unit and/or conformance tests)
+- present the command to run the rendered <TargetModule>
+
+Finally, report with a message: "pyro <current> (latest: <latest>)" - reiterating pyro versions and update warning resolved in Step 0.

package/forge/skills/render-spec/references/plain-lang.md

@@ -0,0 +1,71 @@
+# .plain Language Reference
+
+.plain is a specification language designed for writing software requirements in a clear, structured format. It is used to generate production-ready code from `.plain` spec files using AI. The `.plain` files are the source of truth. They describe what the software should do, how it should be built, and how it should be tested. The generated code is a read-only artifact produced by the renderer.
+
+## .plain File Structure
+
+A `.plain` file has a YAML frontmatter section followed by standardized sections (marked with `***section name***` headers):
+- `***definitions***` — declares concepts used throughout the specification
+- `***implementation reqs***` — non-functional requirements about how the software should be built
+- `***test reqs***` — requirements for conformance testing
+- `***functional specs***` — describes what the software should do
+
+## Concept Notation
+
+Concepts are the building blocks of .plain specifications. They are written between colons: `:ConceptName:`. Valid characters include letters, digits, plus, minus, dot, and underscore.
+
+Concepts must be defined in `***definitions***` before being referenced in other sections. Concept names must be globally unique across the specification and its imports. Concept references must not form cycles — if concept A references concept B, then concept B must not reference concept A.
+
+### Predefined Concepts
+
+.plain provides predefined concepts available in all specifications without needing to be defined:
+
+| Concept | Meaning |
+|---------|---------|
+| `:plainDefinitions:` | Content of the `***definitions***` section |
+| `:plainImplementationReqs:` | Content of the `***implementation reqs***` section |
+| `:plainFunctionality:` | Content of the `***functional specs***` section |
+| `:plainTestReqs:` | Content of the `***test reqs***` section |
+| `:Implementation:` | The system implementing `:plainFunctionality:` |
+| `:plainImplementationCode:` | The generated implementation code |
+| `:UnitTests:` | Auto-generated unit tests for individual functionalities (configured in `***implementation reqs***`) |
+| `:ConformanceTests:` | Auto-generated tests that verify implementation conforms to specs |
+| `:AcceptanceTest:` / `:AcceptanceTests:` | Tests that validate specific aspects of the implementation |
+
+## Definitions Section (`***definitions***`)
+
+Declares concepts used throughout the specification. A concept's definition can come from the module's own `***definitions***` section, from an `import`ed module's definitions, or from a `require`d module's `exported_concepts` (but not transitively). Attributes, constraints and clarifications can be nested as sub-bullets (see the example above).
+
+## Implementation Reqs Section (`***implementation reqs***`)
+
+A free-form section for any instructions that steer code generation. Common uses include technology choices, architectural constraints, coding standards, and naming conventions, but it can also contain detailed implementation guidance — data formats, error handling strategies, algorithm descriptions, or any other context the renderer needs to produce correct code. These describe HOW to build the software, not WHAT it should do. Unit-testing specs also go here, not in `***test reqs***`.
+
+## Test Reqs Section (`***test reqs***`)
+
+Specifies requirements for conformance testing — test frameworks, execution methods, and testing constraints. It does not refer to unit tests, which are specified in the `***implementation reqs***` section.
+
+## Functional Specs Section (`***functional specs***`)
+
+Describes what the software should do. Each bullet point is a single piece of functionality that will be implemented.
+
+Each functional spec must be limited in complexity. If a spec is too complex, the renderer responds with "Functional spec too complex!" and it must be broken down into smaller specs. Complexity is measured in lines of code - each spec should imply no more than 200 lines of code.
+
+Functional specs are in **sequential order** and rendered incrementally, one by one. When a spec is rendered, only **previous** functional specs are in the renderer's context — those earlier in the list, plus any from `requires` modules; later specs are invisible, so a spec can never reference or anticipate what comes after it. This ordering matters for incremental rendering and for detecting conflicts between specs.
+
+## Acceptance Tests (`***acceptance tests***`)
+
+Nested under individual functional specs to specify how to verify correct implementation. They extend conformance tests.
+
+## YAML Frontmatter
+
+The frontmatter is enclosed between `---` markers and supports:
+
+- **`import`** — includes definitions, implementation reqs, and test reqs from templates. Imported modules must not contain functional specs. The default import directory is `template/` — the `template/` prefix is not needed (e.g., `airplain` resolves to `template/airplain.plain`).
+- **`requires`** — specifies dependencies on other root-level modules that must be built first. Unlike `import`, required modules can contain functional specs and represent complete software modules. Requires paths point to root-level modules (e.g., `auth`, `messaging`).
+- **`description`** — optional description of the specification.
+- **`required_concepts`** — concepts that must be defined by any module that imports this spec.
+- **`exported_concepts`** — concepts made available to modules that `require` this one. **Exports are not transitive.** A concept exported from module `A` is visible only to modules that `requires: A` directly. If `B` `requires: A` and `C` `requires: B`, the concepts `A` exports are not visible to `C` — only the concepts `B` itself lists in its own `exported_concepts` (re-declaring and forwarding them in its own `***definitions***` as needed).
+
+## Comments
+
+Lines starting with `>` are ignored when rendering:

package/forge/skills/render-spec/references/render-plan.md

@@ -0,0 +1,8 @@
+# Render Plan
+
+| Order | Module | Spec File | Imports | Requires | Functional Reqs | Status* |
+|-------|--------|-----------|---------|----------|-----|--------|
+| 1 | m_lib | m_lib.plain | base | - | 1 | done |
+| 2 | m_tool | m_tool.plain | base | m_lib | 3 | done |
+
+*Valid statuses: todo, in progress, retrying, done, failed

package/forge/skills/render-spec/scripts/check_version.py

@@ -0,0 +1,223 @@
+#!/usr/bin/env python3
+# Report the render-spec skill's own version and whether a newer stable
+# release has been published.
+#
+# Usage: check_version.py current [--skill-md <path>]
+#        check_version.py latest  [--url <url>]
+#        check_version.py check   [--skill-md <path>] [--url <url>]
+#
+# current  prints the version this copy of the skill ships with, read from
+#          the `metadata: version:` field of the SKILL.md next to this script.
+# latest   prints the latest published stable version, read from the
+#          [project] version in pyproject.toml on the repository's main
+#          branch. The release workflow fast-forwards main only when a stable
+#          release is published, so main's pyproject version IS the latest
+#          stable release - no git and no GitHub API (and its rate limits)
+#          needed. Exits 1 if it cannot be determined.
+# check    prints both plus a verdict, one `key: value` per line:
+#              current: 0.1.0
+#              latest: 0.2.0
+#              status: update-available
+#          status is one of:
+#              update-available  a newer stable release is published
+#              up-to-date        this copy is the latest stable release
+#              ahead             this copy is newer (a dev or rc checkout)
+#              unknown           the latest version could not be determined
+#          Unlike `latest`, network trouble is not an error here: check
+#          degrades to `latest: unknown` / `status: unknown` and exits 0,
+#          because an update hint must never break a render.
+#
+# --skill-md <path> and --url <url> (also the = spellings) override where the
+# current and latest versions are read from; the tests use them with fixture
+# files and file:// URLs.
+#
+# Versions are `X.Y.Z` with an optional `-rc.N` prerelease, and a release
+# outranks its own release candidates: 0.1.0 < 0.2.0-rc.1 < 0.2.0.
+#
+# Portability: the standard library only, Python 3.8+, no shell, no git. The
+# output is written as bytes to stay UTF-8 with LF endings on every platform.
+#
+# Exit: 0 ok, 1 SKILL.md missing or without a parseable version (or `latest`
+#       could not be determined), 2 usage error.
+
+import os
+import re
+import sys
+
+# Deliberately no f-strings anywhere in this file: it has to stay parseable by Python 2 so
+# that a probe landing on an old `python` reaches this guard and gets a clear message instead
+# of a SyntaxError traceback.
+if sys.version_info < (3, 8):
+    sys.stderr.write(
+        "check_version.py: error: Python 3.8 or newer is required, found %s\n"
+        % ".".join(str(part) for part in sys.version_info[:3])
+    )
+    sys.exit(1)
+
+PROG = os.path.basename(sys.argv[0])
+
+LATEST_URL = "https://raw.githubusercontent.com/plainlang/pyro/main/pyproject.toml"
+FETCH_TIMEOUT = 3  # seconds
+SKILL_MD = os.path.normpath(
+    os.path.join(os.path.dirname(os.path.abspath(__file__)), os.pardir, "SKILL.md")
+)
+
+VERSION_RE = re.compile(r"^(\d+)\.(\d+)\.(\d+)(?:-rc\.(\d+))?$")
+
+USAGE = """usage: %(prog)s current [--skill-md <path>]
+       %(prog)s latest  [--url <url>]
+       %(prog)s check   [--skill-md <path>] [--url <url>]
+
+current  print this skill's own version (from SKILL.md metadata)
+latest   print the latest published stable version (pyproject.toml on main)
+check    print both and a status: update-available | up-to-date | ahead | unknown
+""" % {"prog": PROG}
+
+
+def emit(text):
+    sys.stdout.buffer.write(text.encode("utf-8"))
+    sys.stdout.buffer.flush()
+
+
+def version_key(version):
+    """Sort key for a version string, or None if it is not one we understand.
+
+    A release sorts above its own release candidates: (X, Y, Z, 1, 0) for a
+    release, (X, Y, Z, 0, N) for X.Y.Z-rc.N.
+    """
+    match = VERSION_RE.match(version)
+    if not match:
+        return None
+    major, minor, patch, rc = match.groups()
+    if rc is None:
+        return (int(major), int(minor), int(patch), 1, 0)
+    return (int(major), int(minor), int(patch), 0, int(rc))
+
+
+def read_current(skill_md):
+    """The version from SKILL.md's frontmatter, or None.
+
+    The stdlib has no YAML parser, so this scans only the frontmatter block
+    (between the opening and closing --- lines) for the one indented
+    `version:` key, which lives under `metadata:`.
+    """
+    try:
+        with open(skill_md, "rb") as handle:
+            text = handle.read().decode("utf-8", "replace")
+    except OSError:
+        return None
+    lines = text.splitlines()
+    if not lines or lines[0].strip() != "---":
+        return None
+    frontmatter = []
+    for line in lines[1:]:
+        if line.strip() == "---":
+            break
+        frontmatter.append(line)
+    match = re.search(
+        r"(?m)^[ \t]+version:[ \t]*[\"']?([^\"'\s]+)", "\n".join(frontmatter)
+    )
+    return match.group(1) if match else None
+
+
+def fetch_latest(url):
+    """The [project] version from the pyproject.toml at `url`, or None.
+
+    Any failure - offline, DNS, TLS, HTTP error, timeout, garbage payload,
+    a version string that does not parse - just makes the latest version
+    unknown; the caller decides how loud to be. A non-None result is always
+    a valid version.
+    """
+    import urllib.request
+
+    try:
+        with urllib.request.urlopen(url, timeout=FETCH_TIMEOUT) as response:
+            text = response.read().decode("utf-8", "replace")
+    except Exception:
+        return None
+    project = re.search(r"(?ms)^\[project\][ \t]*\r?$(.*?)(?=^\[|\Z)", text)
+    if not project:
+        return None
+    match = re.search(r"(?m)^version[ \t]*=[ \t]*[\"']([^\"']+)[\"']", project.group(1))
+    if not match or version_key(match.group(1)) is None:
+        return None
+    return match.group(1)
+
+
+def compare(current, latest):
+    if latest is None:
+        return "unknown"
+    current_key = version_key(current)
+    latest_key = version_key(latest)
+    if latest_key > current_key:
+        return "update-available"
+    if latest_key < current_key:
+        return "ahead"
+    return "up-to-date"
+
+
+def parse_args(argv):
+    command = None
+    options = {"--skill-md": SKILL_MD, "--url": LATEST_URL}
+    index = 0
+    while index < len(argv):
+        name, equals, value = argv[index].partition("=")
+        if name in options:
+            if not equals:
+                index += 1
+                if index >= len(argv):
+                    usage_error("%s needs a value" % name)
+                value = argv[index]
+            options[name] = value
+        elif name in ("current", "latest", "check") and not equals:
+            if command is not None:
+                usage_error("only one command allowed, got %r after %r" % (name, command))
+            command = name
+        else:
+            usage_error("unknown argument %r" % argv[index])
+        index += 1
+    if command is None:
+        usage_error("a command is required")
+    return command, options["--skill-md"], options["--url"]
+
+
+def usage_error(message):
+    sys.stderr.write("%s: error: %s\n\n%s" % (PROG, message, USAGE))
+    sys.exit(2)
+
+
+def main(argv):
+    command, skill_md, url = parse_args(argv)
+
+    if command == "latest":
+        latest = fetch_latest(url)
+        if latest is None:
+            sys.stderr.write(
+                "%s: error: could not determine the latest published version\n" % PROG
+            )
+            return 1
+        emit(latest + "\n")
+        return 0
+
+    current = read_current(skill_md)
+    if current is None or version_key(current) is None:
+        sys.stderr.write(
+            "%s: error: no parseable metadata version in %s\n" % (PROG, skill_md)
+        )
+        return 1
+
+    if command == "current":
+        emit(current + "\n")
+        return 0
+
+    # check: never fail on account of the network.
+    latest = fetch_latest(url)
+    emit(
+        "current: %s\nlatest: %s\nstatus: %s\n"
+        % (current, latest or "unknown", compare(current, latest))
+    )
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main(sys.argv[1:]))

package/forge/skills/render-spec/scripts/copy_folder.py

@@ -0,0 +1,49 @@
+#!/usr/bin/env python3
+# Copy the complete contents of one folder into another, recursively.
+#
+# Usage: copy_folder.py <source> <destination>
+#
+# The destination folder is created if it does not exist. If it already
+# exists, the source contents are merged into it and files with the same
+# name are overwritten - the same semantics as `cp -r <source>/* <dest>/`
+# on unix, but working identically on macOS, Linux and Windows.
+#
+# Exits 0 on success, 1 on error (source missing or not a directory).
+#
+# Requires Python 3.8+ (shutil.copytree dirs_exist_ok).
+
+import argparse
+import shutil
+import sys
+from pathlib import Path
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(
+        description="Copy the complete contents of a folder to a destination folder."
+    )
+    parser.add_argument("source", help="folder to copy from")
+    parser.add_argument("destination", help="folder to copy into")
+    args = parser.parse_args()
+
+    source = Path(args.source)
+    destination = Path(args.destination)
+
+    if not source.exists():
+        print(f"error: source does not exist: {source}", file=sys.stderr)
+        return 1
+    if not source.is_dir():
+        print(f"error: source is not a directory: {source}", file=sys.stderr)
+        return 1
+
+    try:
+        shutil.copytree(source, destination, dirs_exist_ok=True)
+    except OSError as exc:
+        print(f"error: copy failed: {exc}", file=sys.stderr)
+        return 1
+
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/forge/skills/render-spec/scripts/plain_sections.py

@@ -0,0 +1,351 @@
+#!/usr/bin/env python3
+# Extract one section from .plain specs and print the bodies to stdout.
+#
+# Usage: plain_sections.py [--include-filename] [--output <path>] <section> <spec.plain> [spec.plain ...]
+#
+# Sections (case-insensitive, `-` and `_` interchangeable):
+#   definitions          defs        :plainDefinitions:
+#   implementation-reqs  impl-reqs   impl    :plainImplementationReqs:
+#   test-reqs                                :plainTestReqs:
+#   functional-specs     func-specs  specs   :plainFunctionality:
+#   acceptance-tests     acc-tests           :AcceptanceTests:
+#   all                  all-sections everything   - every section, in file order
+#
+# The ***section*** marker itself is never printed, except for `all`, which keeps every
+# section's own marker so the sections stay distinguishable. `>` comment lines are always
+# dropped. With --include-filename each body is preceded by a "## <path>" heading.
+#
+# --output <path> (or --output=<path>) writes the result to <path> instead of stdout, creating
+# missing parent folders, so callers never need shell redirection. Windows PowerShell 5.1
+# writes UTF-16LE for `>` and `>>`, which corrupts files that later steps read back, so
+# redirecting here rather than in the calling shell keeps the output UTF-8/LF on every
+# platform. Warnings stay on stderr.
+#
+# Portability: the standard library only, Python 3.8+, no shell and no awk - so the same
+# command line works from sh, PowerShell and cmd alike. Everything is written as bytes to
+# keep the output UTF-8 with LF endings even on a Windows console, whose text streams would
+# otherwise re-encode to cp1252 and translate \n to \r\n.
+#
+# Exit: 0 ok (a missing section only warns on stderr), 1 unreadable file or unwritable
+#       --output path, 2 usage error / unknown section.
+
+import os
+import re
+import sys
+
+# Deliberately no f-strings anywhere in this file: it has to stay parseable by Python 2 so
+# that a probe landing on an old `python` reaches this guard and gets a clear message instead
+# of a SyntaxError traceback.
+if sys.version_info < (3, 8):
+    sys.stderr.write(
+        "plain_sections.py: error: Python 3.8 or newer is required, found %s\n"
+        % ".".join(str(part) for part in sys.version_info[:3])
+    )
+    sys.exit(1)
+
+PROG = os.path.basename(sys.argv[0])
+
+USAGE = """usage: %(prog)s [--include-filename] [--output <path>] <section> <spec.plain> [spec.plain ...]
+
+sections (case-insensitive, - and _ interchangeable):
+  definitions          defs       :plainDefinitions:
+  implementation-reqs  impl-reqs  impl    :plainImplementationReqs:
+  test-reqs                               :plainTestReqs:
+  functional-specs     func-specs specs   :plainFunctionality:
+  acceptance-tests     acc-tests          :AcceptanceTests:
+  all                  all-sections everything
+"""
+
+# Every alias, normalized, mapped to the canonical section name the parser matches on.
+SECTIONS = {
+    "definitions": "definitions",
+    "defs": "definitions",
+    "plaindefinitions": "definitions",
+    "implementation reqs": "implementation reqs",
+    "impl reqs": "implementation reqs",
+    "impl": "implementation reqs",
+    "plainimplementationreqs": "implementation reqs",
+    "test reqs": "test reqs",
+    "plaintestreqs": "test reqs",
+    "functional specs": "functional specs",
+    "func specs": "functional specs",
+    "specs": "functional specs",
+    "plainfunctionality": "functional specs",
+    "acceptance tests": "acceptance tests",
+    "acc tests": "acceptance tests",
+    "acceptancetests": "acceptance tests",
+    "all": "all",
+    "all sections": "all",
+    "everything": "all",
+}
+
+COMMENT_RE = re.compile(r"^[ \t]*>")
+BLANK_RE = re.compile(r"^[ \t]*$")
+MARKER_RE = re.compile(r"^[ \t]*\*\*\*(.*)\*\*\*[ \t]*$")
+SPEC_ITEM_RE = re.compile(r"^-[ \t]")
+TRAILING_WS_RE = re.compile(r"[ \t]+$")
+
+
+def byte_sink(stream):
+    """The binary writer under a text stream - or the stream itself when it already is one."""
+    return getattr(stream, "buffer", stream)
+
+
+def write_text(sink, text):
+    """Write text as UTF-8 bytes, bypassing any encoding and newline translation on the way."""
+    try:
+        sink.write(text.encode("utf-8", "surrogateescape"))
+    except TypeError:  # a text-only stream substituted by a caller
+        sink.write(text)
+    sink.flush()
+
+
+def error(message):
+    write_text(byte_sink(sys.stderr), "%s: error: %s\n" % (PROG, message))
+
+
+def warning(message):
+    write_text(byte_sink(sys.stderr), "%s: warning: %s\n" % (PROG, message))
+
+
+def usage():
+    write_text(byte_sink(sys.stderr), USAGE % {"prog": PROG})
+    sys.exit(2)
+
+
+def normalize_section(name):
+    """Lowercase, - / _ -> space, collapse and trim whitespace, strip the colons of :Concept:."""
+    name = " ".join(name.lower().replace("_", " ").replace("-", " ").split())
+    if name.startswith(":"):
+        name = name[1:]
+    if name.endswith(":"):
+        name = name[:-1]
+    return name
+
+
+def marker_name(line):
+    """Section name of a ***marker*** line, normalized; None if the line is not a marker."""
+    match = MARKER_RE.match(line)
+    if match is None:
+        return None
+    name = re.sub(r"[ \t]+", " ", match.group(1).lower()).strip(" ")
+    if name == "":  # a bare ****** is not a section marker
+        return None
+    return name
+
+
+def indent_of(line):
+    width = 0
+    while width < len(line) and line[width] in " \t":
+        width += 1
+    return width
+
+
+def dedent(line, width):
+    return line[min(indent_of(line), width):]
+
+
+def read_lines(path):
+    """Records exactly as awk would see them: split on \\n only, one trailing \\r stripped."""
+    handle = open(path, "r", encoding="utf-8", errors="surrogateescape", newline="")
+    try:
+        text = handle.read()
+    finally:
+        handle.close()
+    if text == "":
+        return []
+    if text.endswith("\n"):
+        text = text[:-1]
+    return [line[:-1] if line.endswith("\r") else line for line in text.split("\n")]
+
+
+def extract(path, want, show_path):
+    """The body of `want` in `path`, newline-terminated; None when the section is absent."""
+    buf = []
+    pending = 0  # blank lines held back, so a trailing run never reaches the output
+    in_section = False
+    in_fs = False
+    in_block = False
+    block_indent = 0
+    block_content = False
+    parent = ""
+    last_parent = ""
+
+    def flush_blanks():
+        for _ in range(pending):
+            buf.append("")
+
+    for line in read_lines(path):
+        marker = marker_name(line)
+        col0 = line.startswith("***")
+
+        if want == "acceptance tests":
+            if marker is not None and col0:  # a top-level section starts
+                in_fs = marker == "functional specs"
+                in_block = False
+                continue
+            if not in_fs:
+                continue
+
+            if marker == "acceptance tests":  # nested, indented under one spec
+                in_block = True
+                block_indent = indent_of(line)
+                pending = 0
+                block_content = False
+                if parent != "" and parent != last_parent:
+                    if buf:
+                        buf.append("")
+                    buf.append(parent)
+                    last_parent = parent
+                continue
+            if marker is not None:
+                in_block = False
+                continue
+
+            if in_block:
+                if BLANK_RE.match(line):
+                    pending += 1
+                    continue
+                if indent_of(line) >= block_indent:
+                    if COMMENT_RE.match(line):
+                        continue
+                    if block_content:
+                        flush_blanks()
+                    pending = 0  # drop blank lines right after the marker
+                    block_content = True
+                    buf.append(dedent(line, block_indent))
+                    continue
+                in_block = False  # dedented out of the block; reconsider line
+
+            if SPEC_ITEM_RE.match(line):  # the functional spec this block belongs to
+                parent = TRAILING_WS_RE.sub("", line)
+            continue
+
+        # Top-level section mode.
+        if marker is not None and col0:
+            if want == "all":
+                if buf:
+                    buf.append("")  # blank line before each new section
+                buf.append(line)  # keep the ***marker*** verbatim
+                in_section = True
+                pending = 0
+            elif marker == want:
+                in_section = True
+                pending = 0
+            elif in_section:
+                in_section = False
+            continue
+        if not in_section:
+            continue
+        if COMMENT_RE.match(line):
+            continue
+        if BLANK_RE.match(line):
+            if buf:
+                pending += 1
+            continue
+        flush_blanks()
+        pending = 0
+        buf.append(line)
+
+    while buf and BLANK_RE.match(buf[-1]):
+        buf.pop()
+    if not buf:
+        return None
+
+    head = ["## " + path, ""] if show_path else []
+    return "\n".join(head + buf) + "\n"
+
+
+def parse_args(argv):
+    """Options are recognized wherever they appear, including after the positionals."""
+    show_path = False
+    out = None
+    positional = []
+
+    args = list(argv)
+    while args:
+        arg = args.pop(0)
+        if arg == "--include-filename":
+            show_path = True
+        elif arg == "--output":
+            if not args:
+                error("--output requires a path")
+                usage()
+            out = args.pop(0)
+        elif arg.startswith("--output="):
+            out = arg[len("--output="):]
+            if out == "":
+                error("--output requires a path")
+                usage()
+        elif arg in ("-h", "--help"):
+            usage()
+        else:
+            positional.append(arg)
+
+    return show_path, out, positional
+
+
+def main(argv):
+    show_path, out, positional = parse_args(argv)
+
+    if len(positional) < 2:
+        usage()
+
+    section_arg = positional[0]
+    want = SECTIONS.get(normalize_section(section_arg))
+    if want is None:
+        error("unknown section: %s" % section_arg)
+        usage()
+
+    # Open once, here, so every write below lands in the file. Truncating up front makes an
+    # unwritable path a clean error before any spec is read.
+    if out is None:
+        sink = byte_sink(sys.stdout)
+        handle = None
+    else:
+        try:
+            parent = os.path.dirname(out)
+            if parent and not os.path.isdir(parent):
+                os.makedirs(parent)
+            handle = open(out, "wb")
+        except (IOError, OSError):
+            error("cannot write %s" % out)
+            return 1
+        sink = handle
+
+    exit_status = 0
+    printed = False
+    try:
+        for path in positional[1:]:
+            if os.path.isdir(path) or not os.access(path, os.R_OK):
+                error("cannot read %s" % path)
+                exit_status = 1
+                continue
+
+            try:
+                body = extract(path, want, show_path)
+            except (IOError, OSError):
+                error("cannot read %s" % path)
+                exit_status = 1
+                continue
+
+            if body is None:
+                if want == "all":
+                    warning("no sections in %s" % path)
+                else:
+                    warning("no '%s' in %s" % (want, path))
+                continue
+
+            if printed:
+                write_text(sink, "\n")
+            write_text(sink, body)
+            printed = True
+    finally:
+        if handle is not None:
+            handle.close()
+
+    return exit_status
+
+
+if __name__ == "__main__":
+    sys.exit(main(sys.argv[1:]))

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "plain-forge",
-  "version": "1.0.21",
+  "version": "1.0.22-next.2d602b1",
   "description": "Conversational spec-writing tool for ***plain specification language",
   "type": "module",
   "engines": {