@turri-dev/cli 0.0.0-stage → 0.1.2-next.48dacfc

package/genome/skills/create-requires-module/SKILL.md

@@ -0,0 +1,109 @@
+---
+name: create-requires-module
+description: >-
+  Create a ***plain module that uses requires to depend on another module in
+  the build chain. Use when the user wants to create a new .plain file that
+  builds on top of a previously built module, inheriting its functional specs
+  and generated code as a starting point.
+allowed-tools: [read, write, edit, bash, ls, grep, find]
+---
+
+# Create Requires Module
+
+## What Requires Does
+
+`requires` attaches the current module to the project's build chain. The required module is built **before** the current one, and its generated code — the accumulated output of that module and all its ancestors — is copied as the starting point. The current module does not need to functionally extend the required module, but their outputs are never independent: the current module's code physically contains the required module's.
+
+When this module is rendered:
+- The required module's generated code (`plain_modules/<required_module>/code`) is copied as the starting point.
+- The `***functional specs***` of the required module **and all its ancestors** become visible as **previous functional specs**.
+- Of the required module's definitions, only the concepts in its `exported_concepts` are visible, each with its full definition text. Export visibility is **not** transitive — to see an ancestor's exports, list that ancestor in `requires` too.
+
+All modules connected by `requires` form a single tree with a common root. **Diamond joins are prohibited**: multiple `requires` entries must lie on one root-to-tip ancestor path. The deepest entry is the attachment point; the other entries exist only to make those ancestors' exports visible.
+
+Use `requires` for:
+- Building on top of an existing module's functionality
+- Attaching a module at the right point in the build chain, even when it addresses a different concern
+
+If you only need shared definitions and reqs (no functional specs, no generated code), use `import` instead — see the `create-import-module` skill.
+
+## Workflow
+
+1. **Identify the attachment point.** Determine which existing module this new module attaches after in the build chain. That module must already exist and be renderable. If listing additional modules, verify each is an ancestor of the attachment point — no diamond joins.
+2. **Create the `.plain` file at the repository root** with YAML frontmatter containing the `requires` field. Modules with functional specs live at the root, not in `template/`.
+3. **Review the functional specs of the whole ancestor chain** — they will be treated as previous requirements. Your new functional specs must not conflict with any of them.
+4. **Review each listed module's `exported_concepts`** — only those concepts are available to reference; an ancestor's exports require listing that ancestor.
+5. **Add module-specific content** — definitions, implementation reqs, test reqs, and functional specs unique to this module.
+6. **Check for conflicts** between your new functional specs and any spec in the ancestor chain.
+
+## Format
+
+The `requires` field is a list of module paths in the YAML frontmatter:
+
+```plain
+---
+requires:
+  - base_module
+import:
+  - shared_template
+description: Extended module that builds on base_module
+---
+
+***definitions***
+
+- :NewFeature: is a feature added by this module.
+
+***functional specs***
+
+- :NewFeature: is available.
+```
+
+A module can use both `requires` and `import` together. `requires` points to other root-level modules; `import` resolves from the default `template/` directory (no prefix needed).
+
+Multiple `requires` entries are legal only when they lie on one ancestor path (e.g., `requires: [auth, messaging]` where `messaging` itself requires `auth`). The deepest entry (`messaging`) is the attachment point; `auth` is listed only to make its exports visible.
+
+## Exported Concepts
+
+The required module controls what concepts are visible via `exported_concepts`:
+
+```plain
+> In the required module's frontmatter:
+---
+exported_concepts: [":StorageClient:", ":BackupResult:"]
+---
+```
+
+Only `:StorageClient:` and `:BackupResult:` would be available to modules that `require` this one, each with its full definition text. All other concepts from the required module are internal.
+
+## Chronological Ordering with Requires
+
+Functional specs from the whole `requires` ancestor chain are considered **previous functional specs**. This means:
+- They are already rendered and their code exists.
+- Your new specs are rendered after them, with full awareness of what they defined.
+- Your new specs must not conflict with any spec in the ancestor chain.
+- The renderer sees the chain's functional specs as context when rendering yours.
+
+The current module may or may not be functionally related to the required module — `requires` places it at the right point in the accumulating build chain either way.
+
+## Import vs Requires
+
+| Aspect | `import` | `requires` |
+|--------|----------|------------|
+| Pulls in definitions | Yes | No (only `exported_concepts`) |
+| Pulls in implementation reqs | Yes | No |
+| Pulls in test reqs | Yes | No |
+| Pulls in functional specs | No | Yes (as previous requirements, transitively) |
+| Copies generated code | No | Yes (accumulated ancestor chain) |
+| Typical use | Templates, shared definitions | Attaching a module to the build chain |
+
+## Validation Checklist
+
+- [ ] Module file is at the repository root (not in `template/`)
+- [ ] Required module exists and is renderable
+- [ ] All `requires` entries lie on one ancestor path — no diamond joins
+- [ ] The deepest `requires` entry is the intended attachment point
+- [ ] Every listed module's `exported_concepts` provide the concepts you need
+- [ ] New functional specs do not conflict with any spec in the ancestor chain
+- [ ] Module has at least one functional spec and one implementation req
+- [ ] Both `requires` and `import` are used correctly (not mixed up)
+- [ ] YAML frontmatter is correctly formatted between `---` markers

package/genome/skills/debug-specs/SKILL.md

@@ -0,0 +1,188 @@
+---
+name: debug-specs
+description: >-
+  Investigate a bug observed in the running application by reading the generated
+  code in plain_modules/, tracing the issue back to the specs, and fixing only
+  the .plain files. Generated code is never modified. Use when the user reports
+  unexpected behavior, visual glitches, crashes, or incorrect logic in the app.
+allowed-tools: [read, write, edit, bash, ls, grep, find]
+---
+
+# Debug Specs
+
+## When to Use
+
+- The user observes a bug in the running application (visual, behavioral, crash, performance).
+- A conformance test or unit test is failing.
+- The generated code does something unexpected or incorrect.
+- The user points to a specific functional spec that seems wrong.
+
+## Guiding Principle
+
+Generated code in `plain_modules/<module>/code/` and `plain_modules/<module>/tests/` is **read-only** — it exists solely as evidence for diagnosis. All fixes are applied exclusively to the `.plain` spec files. The workflow is: observe → read generated code → trace to spec → fix the spec.
+
+## Input
+
+1. **The module name** — identifies the `plain_modules/<module_name>/` directory (`code/` and `tests/`) and the corresponding `.plain` file(s).
+2. **The user's observation** — what is wrong? This can be a bug description, a screenshot, a test failure, an error message, or a general "this doesn't work right."
+3. **Optional: a specific functional spec** — if the user suspects a particular spec, start there. Otherwise, investigate broadly.
+
+## Phase 1 — Understand the Context
+
+1. **Read the `.plain` file(s)** for the module — frontmatter, definitions, implementation reqs, test reqs, and all functional specs. Also read `import` and `requires` chains.
+2. **Read the user's observation carefully.** Rephrase it back to confirm understanding. Identify:
+   - What is the expected behavior?
+   - What is the actual behavior?
+   - Is this a visual issue, a logic issue, a crash, or a data issue?
+
+## Phase 2 — Investigate the Generated Code
+
+Read files in `plain_modules/<module_name>/code/` to understand what the renderer produced. **Do not modify any generated files.**
+
+### 2a. Narrow the search
+
+If the user pointed to a specific spec or area:
+- Identify which generated files implement that spec's behavior.
+- Read those files to understand the current implementation.
+
+If the investigation is broad:
+- Start from the entry point and follow the execution path related to the observed bug.
+- Use the observation to narrow down: UI issue → look at widgets/views, logic issue → look at business logic/providers, data issue → look at models/repositories.
+
+### 2b. Read the relevant generated code
+
+For each relevant file:
+1. Read the code and understand what it does.
+2. Compare the behavior to what the spec says it should do.
+3. Note any discrepancies — places where the code doesn't match the spec's intent.
+
+### 2c. Check conformance tests and unit tests (if relevant)
+
+If the bug manifests as a test failure:
+1. Read the failing test — conformance tests in `plain_modules/<module_name>/tests/` (the module's whole suite, no per-functionality subfolders), unit tests inside `plain_modules/<module_name>/code/`.
+2. Understand what the test expects vs. what the implementation does.
+3. Determine whether the test expectation is correct (matches the spec) or incorrect (doesn't match the spec).
+
+## Phase 3 — Diagnose the Root Cause
+
+Trace the issue from the generated code back to the specs. There are five possible root causes — determine which one applies **before** making changes:
+
+| Root Cause | Symptom | Fix |
+|------------|---------|-----|
+| **Ambiguous spec** | The spec is correct in intent, but vague enough that the renderer interpreted it differently than intended. | Add explicit detail to the spec to eliminate the ambiguity. |
+| **Missing spec** | The desired behavior is not covered by any spec. The renderer had no guidance and either did nothing or made an arbitrary choice. | Add a new functional spec using the `add-functional-spec` skill. |
+| **Conflicting specs** | Two specs contradict each other, causing the renderer to produce inconsistent behavior. | Use the `resolve-spec-conflict` skill. |
+| **Incorrect spec** | The spec explicitly describes the wrong behavior. The renderer implemented it faithfully, but the spec itself is wrong. | Rewrite the spec to describe the correct behavior. |
+| **Missing implementation req** | The spec is correct, but the implementation req doesn't provide enough guidance for the renderer to produce the right code (e.g., missing library, missing architectural constraint, missing platform detail). | Add or update the implementation req using the `add-implementation-requirement` skill. |
+
+### How to diagnose
+
+1. **Read the spec that governs the buggy behavior.** Does it clearly and unambiguously describe the correct behavior?
+   - If the spec is clear and correct but the code is wrong → **ambiguous spec** (the renderer misinterpreted it) or **missing implementation req**.
+   - If the spec doesn't mention the behavior at all → **missing spec**.
+   - If the spec explicitly describes the wrong behavior → **incorrect spec**.
+2. **Check for conflicts.** Could another spec be overriding or contradicting this behavior?
+   - Read all functional specs that touch the same concepts.
+   - If two specs are in tension → **conflicting specs**.
+3. **Check implementation reqs.** Is the renderer missing guidance on how to implement correctly?
+   - Does the implementation req specify the right library, pattern, or constraint?
+   - If a platform-specific or framework-specific detail is missing → **missing implementation req**.
+
+## Phase 4 — Fix the Specs
+
+Apply the fix based on the diagnosed root cause. Use the appropriate skill:
+
+| Root Cause | Skill to Use |
+|------------|-------------|
+| Ambiguous spec | Edit the spec inline — add sub-bullets or reword for clarity |
+| Missing spec | `add-functional-spec` |
+| Conflicting specs | `resolve-spec-conflict` |
+| Incorrect spec | Edit the spec inline — rewrite the incorrect part |
+| Missing implementation req | `add-implementation-requirement` |
+
+### Fix guidelines
+
+- **Minimal changes.** Only modify what is necessary to fix the observed bug. Avoid rewriting unrelated specs.
+- **Preserve chronological order.** If adding a new spec, place it correctly relative to existing specs.
+- **Stay language-agnostic.** Functional specs describe behavior, not implementation. Platform-specific guidance belongs in implementation reqs.
+- **Respect the 200 LOC limit.** If a fix makes a spec too complex, use `break-down-func-spec` to split it.
+- **Check for new conflicts.** After editing, verify the fix doesn't conflict with other specs by running `analyze-func-specs` once with the edited spec(s) plus every existing spec that touches the same concepts. The batched analyzer reports all conflicting pairs in a single call; resolve each with `resolve-spec-conflict`.
+
+## Phase 5 — Verify and Report
+
+1. **Re-read the modified `.plain` file(s)** in full to confirm correctness.
+2. **Summarize the findings** for the user:
+   - What was observed (the bug)
+   - What the generated code was doing (the symptom in code)
+   - Which spec(s) caused the issue (the root cause)
+   - What was changed in the specs (the fix)
+   - What to expect after re-rendering
+3. **If uncertain**, present the diagnosis and proposed fix to the user for confirmation before making changes. Some bugs have multiple possible causes — when in doubt, explain the options and let the user decide.
+
+## Debugging Strategies
+
+### Strategy 1: Observation-Driven (most common)
+
+Start from the user's observation and work backward through the code to the spec.
+
+```
+User sees bug → Read generated code → Find the responsible code path →
+Identify which spec governs that code → Diagnose why the spec produced wrong code →
+Fix the spec
+```
+
+### Strategy 2: Spec-Focused
+
+The user suspects a specific spec. Compare the spec directly against the generated code.
+
+```
+User points to spec → Read the spec → Find the generated code that implements it →
+Compare spec intent vs. code behavior → Diagnose the gap → Fix the spec
+```
+
+### Strategy 3: Test-Failure-Driven
+
+A test is failing. Use the test as the entry point.
+
+```
+Read failing test → Understand what it expects → Read the implementation →
+Determine if the test or the implementation is wrong → Trace back to the spec →
+Fix the spec (or test reqs/acceptance tests if the test itself is wrong)
+```
+
+### Strategy 4: Differential
+
+The bug appeared after a new spec was added. Compare before and after.
+
+```
+Identify the newly added spec → Read the specs it might conflict with →
+Check if the new spec introduced the bug → Use resolve-spec-conflict or
+revise the new spec
+```
+
+## Common Pitfalls
+
+### Fixing the code instead of the spec
+Never modify files in `plain_modules/<module>/code/` or `plain_modules/<module>/tests/`. Even if the fix is obvious in the code, the change must be made in the `.plain` file so it persists across re-renders.
+
+### Treating symptoms instead of root causes
+If the user says "the button is in the wrong place," don't just add positioning detail. Investigate why the renderer placed it there — the root cause might be a missing layout spec, an ambiguous screen description, or a conflict with another spec.
+
+### Over-specifying the fix
+Adding too much implementation detail to a functional spec (e.g., specific pixel values, widget names, CSS properties) makes it brittle. Prefer behavior-level fixes. Use implementation reqs for platform-specific guidance.
+
+### Ignoring ripple effects
+A spec fix may affect other specs that reference the same concepts. Always check neighboring specs for conflicts after making a change.
+
+## Validation Checklist
+
+- [ ] User's observation is clearly understood (expected vs. actual behavior)
+- [ ] Generated code has been read to understand the current implementation
+- [ ] Root cause is diagnosed (ambiguous / missing / conflicting / incorrect / missing impl req)
+- [ ] Fix is applied in the `.plain` file(s) only — no generated code modified
+- [ ] Fix is minimal and targeted to the observed bug
+- [ ] Fix does not introduce new conflicts with existing specs
+- [ ] Modified specs respect the 200 LOC limit
+- [ ] Modified specs remain language-agnostic
+- [ ] Chronological ordering is preserved
+- [ ] Summary of findings and fix presented to the user

package/genome/skills/implement-conformance-testing-script/SKILL.md

@@ -0,0 +1,238 @@
+---
+name: implement-conformance-testing-script
+description: >-
+  Implement a self-contained conformance-test runner script (Bash, run by the
+  harness on the person's machine; an optional PowerShell copy for running it by hand on
+  Windows) for an arbitrary programming language. The script stages the build,
+  installs its dependencies in isolation, runs the static checks of the conformance
+  tests - formatter, linter, type checker - and runs a module's whole conformance
+  suite against it. Use when the user wants to add a conformance-test runner for
+  a new language (Node.js, Go, Rust, Flutter, etc.) to a ***plain project, or
+  wants to regenerate / adapt one of the existing runners.
+allowed-tools: [read, write, edit, bash, ls, grep, find]
+---
+
+# Implement Conformance Testing Script
+
+This skill produces a single executable script that runs the **conformance tests** for a generated build folder, following a consistent, language-agnostic pattern.
+
+The reference implementations are:
+
+- [assets/run_conformance_tests_java.sh](assets/run_conformance_tests_java.sh) — Java.
+- [assets/run_conformance_tests_python.sh](assets/run_conformance_tests_python.sh) — Python.
+- [assets/run_conformance_tests_<lang>.ps1](assets/run_conformance_tests_*.ps1) — Windows PowerShell equivalents, for running the scripts by hand on Windows.
+
+Read both `.sh` references before writing anything — every script you produce must be a faithful translation of the same pattern into the target language's tooling.
+
+## How the harness uses the script
+
+A module's conformance tests live in one folder, `plain_modules/<module>/tests` — the module's whole conformance suite: every functionality's tests, plus those carried up from the modules it requires. There are no per-functionality subfolders.
+
+The harness (not the rendering agent) runs the script once per check, against the whole suite:
+
+```
+bash run_conformance_tests_<lang>.sh <build_folder> <conformance_tests_folder>
+```
+
+Both arguments are absolute paths: `<build_folder>` is the module's generated code (`plain_modules/<module>/code`), and `<conformance_tests_folder>` is the folder holding the whole suite. The harness runs the script on the person's machine - macOS, Linux or WSL, with its toolchains, in the person's own environment - and its exit code alone decides whether the conformance tests pass.
+
+Every conformance script is self-contained: toolchain check, argument validation, stage the build into `<temp>/<lang>_<basename of $1>`, install dependencies there in isolation, check the tests in `$2` statically, run the suite in `$2` against it, clean up on exit. Nothing is prepared ahead of time by another script - unless the project already has a `prepare_environment*.sh` (codeplain's prepare script, or one `prepare-environment-script:` names): turri runs it on the same build before every run of the conformance script, so keep it, and let the conformance script rely on what it sets up rather than doing it again. Never write a prepare script yourself.
+
+## How conformance scripts differ from unit-test scripts
+
+A conformance script is structurally very close to a unit-test script (see the sibling skill [`implement-unit-testing-script`](../implement-unit-testing-script/SKILL.md)) but with two important differences:
+
+1. **Two positional arguments instead of one.** A conformance script takes both the **build folder** (source under test) and a **separate conformance tests folder** (the tests to execute against that build). Both arrive as **absolute paths** from current renderers (older renderer versions passed relative ones) — the script must work with both.
+2. **Tests are loaded from outside the working folder.** The build is staged into the working folder `<temp>/<lang>_<basename>` (system temp directory + language id + basename of `$1` — see [Conventions](#conventions)) and the script `cd`s into it, but the test command is pointed at the conformance tests folder, resolved to an **absolute path** up front (`$CONFORMANCE_TESTS_FOLDER` below). Tests are never copied into the staging area.
+
+Everything else — toolchain check, build staging, dependency isolation, exit codes — is the same.
+
+## Pick the Shell
+
+The harness runs only Bash (`.sh`) scripts, on macOS, Linux and WSL alike. Always write `run_conformance_tests_<lang>.sh`, and make it work on all of them.
+
+A PowerShell (`.ps1`) copy is optional and only for people who run the script by hand on native Windows; the harness never runs it. Write one only if the user asks for it. The same pattern applies to both — only the syntax changes.
+
+## The Pattern
+
+1. **Toolchain check.** Verify that the required language runtime / build tool (and the required version, if any) is installed. If not, print an error and exit with code `69`.
+2. **Argument validation.** Require **two** positional arguments: `<build_folder>` and `<conformance_tests_folder>`. If either is missing, print usage and exit with code `69`.
+3. **Resolve the conformance tests folder to an absolute path.** Current renderers pass `$2` as an absolute path; older ones passed it relative to the invocation directory. Resolve it once, up front, into a variable the test command in step 8 uses:
+   - Bash: `case "$2" in /*) CONFORMANCE_TESTS_FOLDER="$2" ;; *) CONFORMANCE_TESTS_FOLDER="$(pwd)/$2" ;; esac`
+   - PowerShell: `if (-not [System.IO.Path]::IsPathRooted($ConformanceTestsFolder)) { $ConformanceTestsFolder = Join-Path (Get-Location) $ConformanceTestsFolder }`
+
+   Never concatenate `$current_dir/$2` at the point of use — with an absolute `$2` that produces a doubled path (`/project//abs/path/...`), the classic symptom being `ImportError: Start directory is not importable` pointing at a path that contains the project root twice.
+4. **Working directory setup.** Define a working folder at `<temp>/<lang>_<basename>` (`/tmp/<lang>_$(basename "$1")` in Bash, `Join-Path ([System.IO.Path]::GetTempPath()) "<lang>_$(Split-Path $BuildFolder -Leaf)"` in PowerShell). Wipe it (`rm -rf` / `Remove-Item -Recurse -Force`) and recreate it. Register cleanup so the folder is removed when the script exits — `trap 'rm -rf "$WORKING_FOLDER"' EXIT` in Bash, `Remove-Item -Recurse -Force` in the `finally` block in PowerShell. This folder — and **only** this folder — is where every subsequent write must land.
+4b. **Refuse conformance tests in the build folder.** Conformance and acceptance tests live in the conformance tests folder (`$2`) and nowhere else. Before anything is staged, look for them in `$1`: any file carrying a conformance or acceptance label (`conformance tests of functionality`, `conformance tests of the spec`, `acceptance test <n> of functionality`), and any test file under a folder or name that says conformance or acceptance. Found any: print each path, say they belong in the conformance tests folder, and exit `1`. See [Tests in the build folder](#tests-in-the-build-folder).
+5. **Copy the build.** Recursively copy everything from `<build_folder>` (`$1`) into the working folder. **Do not** copy the conformance tests — they stay where they are. After this step both `$1` (build folder) and `$2` (conformance tests folder) are treated as **read-only** for the rest of the script.
+6. **Enter the working directory.** `cd` / `Set-Location` into `<temp>/<lang>_<basename>`. If that fails, exit with code `69`. All remaining steps run from inside the working folder; they must never write back to `$1` or `$2`.
+7. **Install dependencies into an isolated environment inside `<temp>/<lang>_<basename>`.** Set up a per-working-folder dependency location (a Python venv at `./.venv`, a local `./node_modules`, a project-scoped Maven repo at `./.m2`, etc.) and install/resolve all dependencies into it. **Never** install into the source build folder (`$1`), the conformance tests folder (`$2`), the user's global cache (`~/.m2`, system-wide `pip`, `~/.cargo`, `~/.npm`, ...), or anywhere outside `<temp>/<lang>_<basename>`. If the install command fails, propagate its exit code immediately and **do not** proceed to step 8. See [Dependency isolation](#dependency-isolation).
+7b. **Static checks of the conformance tests.** Once the build and the test libraries are installed - so the tests resolve against them as they do when they run - check **the conformance tests in `$CONFORMANCE_TESTS_FOLDER`, and only them**: the formatter in check mode, the linter, and the type checker where the language has one apart from its compiler. See [Static checks of the tests](#static-checks-of-the-tests). Run every check, even after one fails, print each one's whole output, remember whether any failed - and go on to step 8 whatever they said, so one run reports both.
+8. **Run the conformance tests.** Invoke the language's standard test command, **pointed at `$CONFORMANCE_TESTS_FOLDER`** (the absolute path resolved in step 3) **and at nothing else**, so it runs the whole suite in one go - and only it. The build's own tests (its unit tests, and anything else in it) are never collected: no discovery from the working folder, and no test configuration in the build (a `pytest.ini` / `pyproject.toml` `testpaths`, a Jest `roots`) allowed to widen the run beyond `$CONFORMANCE_TESTS_FOLDER`. The script's final exit code is whatever the test command returns — except for the "no tests discovered" case below.
+
+   Then exit: the test command's own non-zero code when the suite failed; else `80` when only the static checks of step 7b failed; else `0`.
+
+   The test command is **read-only** with respect to `$CONFORMANCE_TESTS_FOLDER`. It loads test files from there, but any artifacts the runner produces (caches, JUnit XML, coverage reports, compiled test classes, etc.) must land inside `<temp>/<lang>_<basename>`, not next to the test files. If your chosen runner defaults to writing output beside the tests, pass an explicit output-directory flag pointing inside the working folder (e.g. `pytest --basetemp=./.pytest_tmp`, `jest --cacheDirectory=./.jest_cache`, Maven `target/` under the working folder via `mvn -f "$CONFORMANCE_TESTS_FOLDER/pom.xml" -Dproject.build.directory="$(pwd)/target" test`).
+
+### Read-only inputs — hard rule
+
+A conformance script has **two** read-only inputs: the source build folder (`$1`) and the conformance tests folder (`$2`). Neither one may be written to under any circumstances. The script must never:
+
+- install dependencies into `$1` or `$2` (no `pip install` inside `$1`/`$2`, no `npm install` inside them, no `mvn install` writing into them, no Cargo build artifacts ending up under them),
+- write a virtualenv / `node_modules` / `.m2` / `.gocache` / `.cargo` directory inside `$1` or `$2`,
+- run the test command with its `cwd` set to `$1` or `$2` (every test command runs from inside `<temp>/<lang>_<basename>` after the `cd` in step 6),
+- create logs, caches, build outputs, JUnit XML, coverage reports, compiled test classes, or temp files inside `$1` or `$2`.
+
+Why each input is read-only:
+
+- **`$1` (build folder)** is shared with the renderer (`plain_modules/<module>/code` by default) and downstream tooling. Writing into it corrupts the renderer's view of "what was generated" and breaks subsequent renders. The whole point of staging into the system temp directory is so the source folder stays a clean, reproducible artifact of the render.
+- **`$2` (conformance tests folder)** is the user's authored test source — typically checked into version control. Writing into it pollutes the working tree, churns git status, and (with frameworks that auto-discover) can make subsequent runs pick up generated files as if they were tests.
+
+If you find yourself about to issue any command whose `cwd` is `$1` or `$2`, or whose target path starts with `$1/` or `$2/`, **stop**. Either move the operation into `<temp>/<lang>_<basename>`, or you're doing something the script must not do.
+
+### Tests in the build folder
+
+A conformance test written into the build folder is in the wrong place: nothing runs it as part of the conformance suite, and a runner that discovers tests from the working folder would run it as if it were one - a suite that seems to pass whatever `$2` holds. So the script catches it before it runs anything (step 4b), and says where it belongs. In Bash:
+
+```bash
+MISPLACED=$(grep -rlE --exclude=".turri*" --exclude-dir=.venv --exclude-dir=node_modules --exclude-dir=target \
+  "conformance tests of (functionality [0-9]|the spec)|acceptance test [0-9]+ of functionality" "$1" 2>/dev/null; \
+  find "$1" -type f \( -ipath "*conformance*" -o -ipath "*acceptance*" \) -iname "*test*" \
+  -not -name ".turri*" -not -path "*/.venv/*" -not -path "*/node_modules/*" -not -path "*/target/*" 2>/dev/null)
+if [ -n "$MISPLACED" ]; then
+  printf "Conformance tests found in the build folder %s - they belong in the conformance tests folder %s:\n%s\n" "$1" "$CONFORMANCE_TESTS_FOLDER" "$(echo "$MISPLACED" | sort -u)" >&2
+  exit 1
+fi
+```
+
+### Static checks of the tests
+
+The conformance tests are held to their language's formatter, linter and type checker, as the code is by the unit testing script. Three things make it work here:
+
+- **Check them where they run.** The tests import the test libraries - and, for a library, the build itself - so a check of `$2` on its own cannot resolve them. Run the checks in step 7b, after the install, against the staged environment: the venv the build was installed into, the tests' own Maven, Go or Cargo project with the build in reach as the suite has it. What passes in the merged world is what counts; the tests are never checked alone.
+- **Report the tests' findings only.** The code is checked by the unit testing script, and the conformance agent may not change it. Point each tool at `$CONFORMANCE_TESTS_FOLDER` and keep the code's findings out (`follow_imports = silent` for mypy, a tsconfig whose `include` is the tests alone).
+- **Pin the profile and the flags in the script.** The tests' own configuration files - a `pyproject.toml`, `tsconfig.json`, `Cargo.toml`, `pom.xml` in `$2` - are written by the conformance agent, which could relax a check to pass it. Pass every setting that decides pass or fail on the command line, or in a configuration file the script writes into the working folder, and do not read one from `$2` or `$1`.
+
+| Language | Formatter, in check mode | Linter | Type checker - a tests profile |
+|---|---|---|---|
+| Python | `ruff format --check --no-cache --isolated --output-format concise "$CONFORMANCE_TESTS_FOLDER"` | `ruff check --no-cache --isolated --output-format concise --no-fix "$CONFORMANCE_TESTS_FOLDER"` | `mypy --config-file <a file the script writes>` with `disallow_untyped_defs`, `follow_imports = silent` and `cache_dir` in the working folder - typed, not `--strict` |
+| TypeScript | `prettier --check` on the tests' files | `eslint --max-warnings 0` on the tests | `tsc --noEmit -p <a tsconfig the script writes>`: `strict`, `include` the tests alone, the build's types in reach |
+| JavaScript | `prettier --check` on the tests' files | `eslint --max-warnings 0` on the tests | none - unless the test reqs name one |
+| Go | `gofmt -l "$CONFORMANCE_TESTS_FOLDER"` | `go vet ./...` in the tests' own module | the compiler |
+| Rust | `cargo fmt --check --manifest-path "$CONFORMANCE_TESTS_FOLDER/Cargo.toml"` | `cargo clippy --all-targets --manifest-path "$CONFORMANCE_TESTS_FOLDER/Cargo.toml" -- -D warnings` | the compiler |
+| Java | only one the test reqs name (`google-java-format --dry-run --set-exit-if-changed`) | the tests compiled with `-Xlint:all -Werror` (`-Dmaven.compiler.failOnWarning=true`) | the compiler |
+| Dart / Flutter | `dart format --output=none --set-exit-if-changed "$CONFORMANCE_TESTS_FOLDER"` | `dart analyze --fatal-infos "$CONFORMANCE_TESTS_FOLDER"` (`flutter analyze` for Flutter) | the analyzer, in the same command |
+
+The tools come from where the tests' dependencies come from - the build's dev dependencies installed in step 7, or what the script installs beside them for the tests (`uv pip install ruff mypy`, as it installs `pytest`). A checker the machine lacks, which nothing installs, is `69`. Every build artifact and cache the checks make goes in the working folder, never in `$2` - a Cargo or Maven project in `$2` is built with its target directory in the working folder.
+
+turri reads exit `80` as the tests' own: the conformance agent is sent the findings, and no judge is asked whether the code or the tests are wrong. So `80` is only ever "the suite passed and only the checks of the tests failed".
+
+### "No tests discovered" detection
+
+The Python reference script grep's the test runner output for `"Ran 0 tests in"` and exits `1` if no tests ran. Replicate the equivalent check for the target language wherever that language's test runner silently passes when given an empty test set:
+
+- Python `unittest`: `"Ran 0 tests in"`
+- Node.js `jest`: `"No tests found"`
+- Go `go test`: `"no test files"` / `"no tests to run"`
+- Rust `cargo test`: `"running 0 tests"`
+- Java `mvn test`: usually fails loudly already; no extra check needed.
+
+A silently-passing zero-test run is the most dangerous failure mode of a conformance runner — always guard against it.
+
+## Conventions
+
+Shared across both shell flavors:
+
+- **Exit codes:**
+  - `69` — unrecoverable invocation error: missing argument, missing toolchain, can't enter working folder, can't create venv. Matches the reference scripts' `UNRECOVERABLE_ERROR_EXIT_CODE`.
+  - `1` — "no tests discovered" guard tripped (see above).
+  - `80` — the suite passed and only the static checks of the tests failed (step 7b).
+  - Any other non-zero code — propagated from the underlying test command.
+- **Working folder naming:** `<temp>/<lang>_<basename>` — the system temp directory (`/tmp` in Bash, `[System.IO.Path]::GetTempPath()` in PowerShell) plus a short identifier for the language (`java`, `python`, `node`, `go`, `rust`, ...) and the **basename** of the *first* argument (the build folder — `$(basename "$1")` / `Split-Path $BuildFolder -Leaf`), never the conformance tests folder and never the raw argument (it may be absolute; concatenating it produces broken doubled paths). All dependency installs, build outputs, caches, test runner artifacts, and the test invocation itself live inside this folder. Nothing the script does should touch `$1` after step 5, or `$2` at any point.
+- **Cleanup ownership:** the script owns its working folder and removes it on exit, success and failure alike (`trap 'rm -rf "$WORKING_FOLDER"' EXIT` in Bash; `Remove-Item -Recurse -Force` in the PowerShell `finally` block, after `Pop-Location`).
+- **Logging — be as verbose as possible.** The script is the only thing the operator sees between a `turri` render and a green/red conformance result; when it fails, the only forensic evidence anyone has is its stdout/stderr. Treat the script like a production runbook, not a quiet helper. Concretely:
+  - **Announce every step before doing it**, with the exact value of every variable involved — the resolved build folder, the resolved conformance-tests folder, the working folder, the language, the toolchain version detected, the isolation root being set up, and the test command about to run. "Running tests" alone is useless; "Running `python -m unittest discover -b -s /abs/path/to/tests` from working folder `/tmp/python_build/` with venv activated at `./.venv` (Python 3.11.6)" is triage-ready.
+  - **Echo every non-trivial command before executing it.** In Bash, use `set -x` for the body of the script (or `echo "+ <cmd>"` immediately before each call); in PowerShell, set `$VerbosePreference = 'Continue'` and use `Write-Verbose` / `Write-Host` to print each command line with its arguments.
+  - **Print clear section banners.** Each pattern step gets a banner like `===== [7/8] Install dependencies =====` so a long log can be navigated by eye.
+  - **Print resolved absolute paths**, not just the relative names. Operators reading the log on a different machine need to know where the venv / `.m2` / `node_modules` / `.gocache` / `.cargo` actually landed, and what `$2` resolved to.
+  - **Print the toolchain's own `--version` output** (and the path it resolved from) during step 1, even on success. This is the single most useful piece of forensic data when conformance passes on one machine but fails on another.
+  - **Surface the install output verbatim** — do not pipe it to `/dev/null`, do not redirect to a log file inside the working folder. The operator must see every dependency-resolver line in the script's own output stream. Drop the `VERBOSE`-gated wrapping from the Python reference — conformance output is where forensic data is most valuable.
+  - **On failure, print what was about to run before exiting** — the exact test command, the working directory, the resolved `$CONFORMANCE_TESTS_FOLDER`, and the relevant environment variables (`PYTHONPATH`, `NODE_PATH`, `GOMODCACHE`, `CARGO_HOME`, `MAVEN_OPTS`, `PATH`, plus `VIRTUAL_ENV` for Python).
+  - **Print a final summary line** that names the test command, the exit code, the resolved conformance-tests folder, and the working folder so the operator knows exactly what to re-run by hand if needed.
+  Verbosity is not noise here — a chatty script that documents itself in its own output is the difference between a 30-second triage and a 30-minute one. Never trade verbosity for terseness.
+- **Resolve `$2` before any `cd`.** This is the single most common bug in hand-written conformance scripts: using the conformance-tests argument after changing directory. Resolve it to an absolute path in step 3 (absolute → use as-is; relative → prefix the invocation directory) and use only the resolved variable afterwards. The resolved value must also appear in the verbose log (per the logging rule above) so misresolutions of `$2` are visible at a glance.
+
+### Dependency isolation
+
+The dependency environment must live **inside** `$WORKING_FOLDER` so the test run can't be polluted by — or pollute — the user's global caches. Pick the most idiomatic isolation mechanism for the language:
+
+| Language | Isolation mechanism | Install command (run inside `$WORKING_FOLDER`) | Test command (point at `$CONFORMANCE_TESTS_FOLDER`) |
+|---|---|---|---|
+| Python | `venv` at `./.venv` | `python3 -m venv .venv && source .venv/bin/activate && pip install -r requirements.txt` | `python -m unittest discover -b -s "$CONFORMANCE_TESTS_FOLDER"` (or `pytest "$CONFORMANCE_TESTS_FOLDER"`) |
+| Node.js | local `./node_modules` (default) | `npm ci` (preferred) or `npm install` | `npx jest --rootDir "$CONFORMANCE_TESTS_FOLDER"` |
+| Java | project-scoped Maven repo at `./.m2` | `mvn -Dmaven.repo.local=./.m2 install -DskipTests` (build + install artifact so the test pom can resolve it) | `mvn -f "$CONFORMANCE_TESTS_FOLDER/pom.xml" -Dmaven.repo.local="$(pwd)/.m2" test` |
+| Go | module cache at `./.gocache` | `GOMODCACHE="$PWD/.gocache" go mod download` (optional pre-warm) | `GOMODCACHE="$PWD/.gocache" go test "$CONFORMANCE_TESTS_FOLDER/..."` |
+| Rust | cargo home at `./.cargo` | `CARGO_HOME="$PWD/.cargo" cargo fetch` (optional pre-warm) | `CARGO_HOME="$PWD/.cargo" cargo test --manifest-path "$CONFORMANCE_TESTS_FOLDER/Cargo.toml"` |
+
+Notes:
+
+- **Every path in the install command and test command is relative to `<temp>/<lang>_<basename>`.** That's why the script `cd`s into the working folder in step 6 — from that point on, `./.venv`, `./node_modules`, `./.m2`, etc. all resolve under `<temp>/<lang>_<basename>`, never under `$1` or `$2`.
+- **Always pass the isolation flag/env var to both the install command and the test command.** They must agree on where deps live, otherwise the test command will silently fall back to the global cache **or** (worse) write into `$1` / `$2`.
+- **Python is the only ecosystem where the venv is mandatory** to satisfy "into a virtual environment" literally. The others use language-native equivalents that achieve the same isolation.
+- **Propagate the install exit code immediately.** In Bash: `<install cmd> || exit $?`. In PowerShell: check `$LASTEXITCODE` and `exit $LASTEXITCODE` if non-zero.
+- **Time the dependency setup** with `date +%s.%N` (Bash) / `Get-Date` (PowerShell) and print `"Requirements setup completed in X.XX seconds"`.
+
+### Bash specifics
+
+- **Shebang:** `#!/bin/bash`.
+- **File naming:** `run_conformance_tests_<lang>.sh`, placed in `assets/` (skill reference) or `test_scripts/` (target project).
+- **Arguments:** `$1` = build folder, `$2` = conformance tests folder.
+- **Make it executable:** `chmod +x` the produced script.
+- **`cd` failure check:** the reference scripts use the `cd ... 2>/dev/null` + `[ $? -ne 0 ]` pattern. Keep it.
+- **Portable:** the harness runs the script on macOS and Linux alike. Stick to POSIX tools and flags both have (e.g. `cp -R`, `mktemp`, plain `grep` - not GNU-only or BSD-only flags, not a macOS-only `/usr/libexec/java_home`), and let the toolchain check report clearly when the runtime is missing.
+
+### PowerShell specifics (by-hand Windows copy only)
+
+The harness never runs `.ps1` scripts. These notes apply only to an optional copy for people running the suite by hand on Windows.
+
+- **No shebang.** Use a `param([Parameter(Mandatory=$true)][string]$BuildFolder, [Parameter(Mandatory=$true)][string]$ConformanceTestsFolder)` block at the top instead.
+- **File naming:** `run_conformance_tests_<lang>.ps1`.
+- **Exit codes:** use `exit 69` etc. (PowerShell honors them just like Bash).
+- **Toolchain check:** prefer `Get-Command <tool> -ErrorAction SilentlyContinue` and, where a specific version is needed, parse the tool's `--version` output.
+- **Filesystem:** use `Test-Path`, `Remove-Item -Recurse -Force`, `New-Item -ItemType Directory`, `Copy-Item -Recurse`, `Set-Location`. Quote paths to handle spaces.
+- **Resolve `$ConformanceTestsFolder` to absolute** with `[System.IO.Path]::IsPathRooted` + `Join-Path (Get-Location) ...` **before** any `Set-Location` call.
+- **No `chmod` step needed.** If execution policy is likely to block the script, mention `Set-ExecutionPolicy -Scope CurrentUser RemoteSigned` to the user — don't bake it into the script.
+
+## Workflow
+
+1. Confirm the target **language** and **dependency manifest** (`pom.xml`, `requirements.txt` / `pyproject.toml`, `package.json`, `go.mod`, `Cargo.toml`, ...). Ask if either is unclear.
+2. Read [assets/run_conformance_tests_java.sh](assets/run_conformance_tests_java.sh) and [assets/run_conformance_tests_python.sh](assets/run_conformance_tests_python.sh) to refresh the exact structure.
+3. Translate each step into the equivalent Bash commands for the target language. The toolchain check, dependency install, and test invocation are the language-specific parts; the rest is mechanical.
+4. Pick the right row from the [Dependency isolation](#dependency-isolation) table — use the same flag/env var in steps 7, 7b and 8 — and the checks from [Static checks of the tests](#static-checks-of-the-tests).
+5. Add the language-appropriate "no tests discovered" guard from [No tests discovered detection](#no-tests-discovered-detection), and the guard against conformance tests in the build folder from [Tests in the build folder](#tests-in-the-build-folder).
+6. Save the new script as `test_scripts/run_conformance_tests_<lang>.sh` and `chmod +x` it. Write a `.ps1` copy only if the user wants to run it by hand on Windows.
+7. **Make sure turri finds the script.** Do not link it from the specs - turri finds the conformance testing script in the project root (the folder that holds `plain_modules/`) and puts it, whole, into the prompts of the agents that write and review the conformance tests itself, whenever conformance tests are written for a build; a link to it from a spec is ignored. It looks, in order, at `config.turri.yaml` in the root (`conformance-tests-script: <path relative to the root>`) - with the chosen stack's `config.turri.<stack>.yaml` over it, then for the one `run_conformance_tests*.sh` in the root, then for the one in `test_scripts/`. Saving the script in `test_scripts/` (or the root) is enough when it is the only one there. If the project keeps it elsewhere, name it in `config.turri.yaml` as `conformance-tests-script:` - and when the project has only a `config.yaml`, copy it to `config.turri.yaml` first (and each `config.<name>.yaml` to `config.turri.<name>.yaml`) and edit the copy; `config.yaml` may be another tool's, and is never written. If the project has modules on different stacks - e.g. a Python backend and a React frontend side by side, sharing only an imported module - each part is on a stack of its own, and each stack names its own script in its own file beside `config.turri.yaml`: `conformance-tests-script:` in `config.turri.backend.yaml` for the stack `backend`, in `config.turri.frontend.yaml` for the stack `frontend`. A stack is chosen, never worked out: tell the user to choose it with `/stack <stack>` (`--stack <stack>` on the command line) before building that part. turri never guesses between two. The script is required: with conformance testing on, a build without one stops before it starts. The `***test reqs***` still describe the conformance framework and command in words; do not paraphrase the script into them.
+
+## Anti-Patterns
+
+- **(Hard mistake) Don't install into, build into, or otherwise write to the source build folder (`$1`) or the conformance tests folder (`$2`).** Both arguments are read-only input. Every install, cache, build artifact, log, JUnit XML, coverage report, compiled test class, and temp file must land in `<temp>/<lang>_<basename>`. This includes never running `pip install`, `npm install`, `mvn install`, or `cargo build` with `$1` or `$2` as their `cwd` or target; never letting a venv / `node_modules` / `.m2` / `.gocache` / `.cargo` directory appear inside `$1` or `$2`; and never running the test command from inside either folder. The whole point of staging into the system temp directory is so the build folder remains a clean artifact of the render and the conformance tests folder remains a clean tree under the user's version control — writing to either one corrupts those guarantees.
+- **(Hard mistake) Don't build any path by concatenating a raw argument.** `$1` and `$2` arrive as absolute paths from current renderers. Patterns like `WORKING_FOLDER=.tmp/$1`, `WORKING_FOLDER=<lang>_$1`, or `"$current_dir/$2"` silently produce doubled paths (`/project//abs/path/...`) — the classic symptom is `ImportError: Start directory is not importable` or "folder does not exist" pointing at a path that contains the project root twice. Always derive the working folder from `$(basename "$1")` / `Split-Path -Leaf`, and use the `$CONFORMANCE_TESTS_FOLDER` resolved in step 3.
+- **Don't rely on anything being set up before the script runs.** The script is self-contained: it stages the build and installs dependencies itself, every time. Don't look for a pre-warmed working folder or environment left by an earlier run.
+- **Don't copy the conformance tests folder into the working folder.** Only the build folder is staged. The test folder is read in place from `$CONFORMANCE_TESTS_FOLDER`.
+- **Don't compute the test path after `cd`.** Resolve `$2` to an absolute path in step 3; otherwise a relative `$2` will be resolved against the working folder and silently miss the tests.
+- **Don't expect per-functionality subfolders in `$2`.** `$2` holds the module's whole conformance suite; point the test command at it and let the runner discover every test in it.
+- **Don't run tests from anywhere but the conformance tests folder, and don't let conformance tests in the build folder pass unnoticed.** The build's tests are the unit testing script's; a conformance test in the build folder is misplaced, and the script fails on it (step 4b) instead of running it or ignoring it.
+- **Don't skip the "no tests discovered" check.** A conformance suite that finds zero tests and exits `0` is the worst possible failure mode — it looks like success.
+- **Don't skip the toolchain check**, even when "everyone has it installed" — exit code `69` is what the calling system relies on to detect a missing runtime.
+- **Don't reuse the source folder in place.** Always copy into `<temp>/<lang>_<basename>` first; the renderer relies on this isolation.
+- **Don't skip cleanup.** Register the `trap` / `finally` removal of the working folder right after creating it, so it is removed on success and failure alike.
+- **Don't change the exit-code contract.** Other parts of the system branch on `69`, `1` and `80` specifically — and these codes must be identical between the Bash script and any PowerShell copy.
+- **Don't check the tests on their own, or the code with them.** The checks run after the install, against what the tests run with, and report the tests' findings alone.
+- **Don't let the tests' own configuration decide the checks.** The flags and the profile are the script's; a config file in `$2` is the conformance agent's to write.
+- **Don't skip the suite because a check failed, and don't exit `80` when the suite failed.** Both run every time; `80` means the suite passed.
+- **Don't write a cross-shell hybrid** (e.g. a `.sh` that detects PowerShell, or vice versa). Ship one script per shell, named with the appropriate extension.
+- **Don't ship only a `.ps1`.** The harness runs `.sh` scripts only; a project with just a PowerShell runner has no conformance testing script as far as turri is concerned.
+- **Don't install dependencies into the user's global location** (`~/.m2`, system-wide `pip`, `~/.cargo`, etc.). Always isolate inside `$WORKING_FOLDER` so concurrent runs and other projects can't interfere.
+- **Don't run the test command without first verifying the install succeeded.** A failed install followed by a "test" run produces misleading errors that look like test failures.
+- **Don't link the script from the specs, and don't leave turri guessing.** turri finds the script in `config.turri.yaml`, the project root, or `test_scripts/`, shows it to the agents that write the conformance tests itself, and stops before the build starts without it; a link to it from a spec is ignored. Put it where it is found, and when there are two conformance testing scripts in one folder, name the one to use as `conformance-tests-script:` - in each stack's `config.turri.<stack>.yaml` when they are for parts on different stacks (see Workflow step 7).
+- **Don't write a terse script.** Silent steps, `>/dev/null` redirects on the install output, missing `--version` prints, absent step banners, an un-logged resolved `$2`, and a missing final summary all make the script harder to debug than the tests it is running. Follow the *Logging — be as verbose as possible* rule under [Conventions](#conventions) literally: every step announces itself, every command is echoed, the resolved `$CONFORMANCE_TESTS_FOLDER` is printed, every failure prints what was about to run and where, and the final summary names the test command, exit code, and working folder.