plain-forge 1.0.5 → 1.0.7

package/README.md

@@ -182,7 +182,6 @@ plain-forge keeps a single canonical source of truth under `forge/` and uses tin
 forge/                       # canonical, runtime-neutral content
   skills/                    # all skills used during spec writing
   rules/                     # workspace rules for spec validation
-  docs/                      # shared docs (PLAIN_REFERENCE.md, etc.)
 
 runtimes/                    # per-runtime adapters
   claude/

package/forge/rules/examples/integration-embedded-testing/prepare_environment_java.sh

@@ -0,0 +1,51 @@
+#!/bin/bash
+
+# Export Java 21
+#export JAVA_HOME="/opt/homebrew/opt/openjdk@21/libexec/openjdk.jdk/Contents/Home"
+#export PATH="$JAVA_HOME/bin:$PATH"
+echo "JAVA_HOME: $JAVA_HOME"
+
+# Check if build folder name is provided
+if [ -z "$1" ]; then
+  printf "Error: No build folder name provided.\n"
+  printf "Usage: $0 <build_folder_name>\n"
+  exit 1
+fi
+
+JAVA_BUILD_SUBFOLDER=../../../
+
+if [ "${VERBOSE:-}" -eq 1 ] 2>/dev/null; then
+  printf "Copying generated code to main project folder: $JAVA_BUILD_SUBFOLDER\n"
+fi
+
+# Check if the main project folder exists
+if [ ! -d "$JAVA_BUILD_SUBFOLDER" ]; then
+  echo "Error: Main project folder '$JAVA_BUILD_SUBFOLDER' does not exist."
+  exit 2
+fi
+
+# clean existing code from the main project folder
+rm -rf $JAVA_BUILD_SUBFOLDER/<placeholder for integration code>/*
+rm -rf $JAVA_BUILD_SUBFOLDER/<placeholder for integration code tests>/*
+
+# copy generated code to the main project folder
+# FIX: added the mkdir lines otherwise it complains that the cp destintation directory does not exist
+mkdir -p $JAVA_BUILD_SUBFOLDER/<placeholder for integration code>
+mkdir -p $JAVA_BUILD_SUBFOLDER/<placeholder for integration code tests>
+cp -R $1/<placeholder for integration code>/* $JAVA_BUILD_SUBFOLDER/<<placeholder for integration code>
+cp -R $1/<placeholder for integration code tests>/* $JAVA_BUILD_SUBFOLDER/<placeholder for integration code tests>
+
+# Move to the subfolder
+echo "Moving to: $JAVA_BUILD_SUBFOLDER"
+cd "$JAVA_BUILD_SUBFOLDER" 2>/dev/null
+
+if [ $? -ne 0 ]; then
+  printf "Error: Java build folder '$JAVA_BUILD_SUBFOLDER' does not exist.\n"
+  exit 2
+fi
+
+# Remove target directory to avoid conflicts
+rm -rf ./target || echo "Warning: some files may be locked"
+
+echo "Runinng maven install in the build folder..."
+mvn clean install -Dspring-boot.repackage.skip=true -DskipTests

package/forge/rules/examples/integration-embedded-testing/run_conformance_tests_java.sh

@@ -0,0 +1,99 @@
+#!/bin/bash
+
+# Export Java 21
+#export JAVA_HOME="/opt/homebrew/opt/openjdk@21/libexec/openjdk.jdk/Contents/Home"
+#export PATH="$JAVA_HOME/bin:$PATH"
+echo "JAVA_HOME: $JAVA_HOME"
+
+# Check if build folder name is provided
+if [ -z "$1" ]; then
+  printf "Error: No build folder name provided.\n"
+  printf "Usage: $0 <build_folder_name> <conformance_tests_folder>\n"
+  exit 1
+fi
+
+# Check if conformance tests folder name is provided
+if [ -z "$2" ]; then
+  printf "Error: No conformance tests folder name provided.\n"
+  printf "Usage: $0 <build_folder_name> <conformance_tests_folder>\n"
+  exit 1
+fi
+
+current_dir=$(pwd)
+
+CONFORMANCE_TESTS_FOLDER=".tmp/java_conformance"
+
+cd "$current_dir" 2>/dev/null
+
+printf "Preparing Java conformance tests subfolder: $CONFORMANCE_TESTS_FOLDER\n"
+
+# Check if the go build subfolder exists
+if [ -d "$CONFORMANCE_TESTS_FOLDER" ]; then
+  # Find and delete all files and folders
+  find "$CONFORMANCE_TESTS_FOLDER" -mindepth 1 -exec rm -rf {} +
+
+  if [ "${VERBOSE:-}" -eq 1 ] 2>/dev/null; then
+    printf "Cleanup completed.\n"
+  fi
+else
+  # print the current directory
+  printf "Current directory: $(pwd)\n"
+
+  printf "Subfolder does not exist. Creating it...\n"
+  mkdir -p $CONFORMANCE_TESTS_FOLDER
+fi
+
+printf "Copying all files and folders from $2 to $CONFORMANCE_TESTS_FOLDER...\n"
+cp -R $2/* $CONFORMANCE_TESTS_FOLDER
+
+# Move to the subfolder
+printf "Moving to $CONFORMANCE_TESTS_FOLDER...\n"
+cd "$CONFORMANCE_TESTS_FOLDER" 2>/dev/null
+
+if [ $? -ne 0 ]; then
+  printf "Error: Java conformance tests folder '$CONFORMANCE_TESTS_FOLDER' does not exist.\n"
+  exit 2
+fi
+
+echo "Running maven install in the conformance tests folder..."
+mvn clean install -DskipTests
+
+
+if [ $? -ne 0 ]; then
+  exit 2
+fi
+
+echo "Running maven test in the conformance tests folder..."
+
+output=$(mvn test --no-transfer-progress 2>&1)
+exit_code=$?
+
+echo "Finished running maven test in the conformance tests folder..."
+
+# Check if no tests were run
+if echo "$output" | grep -q 'Tests run: [1-9][0-9]*, Failures: 0, Errors: 0, Skipped: 0'; then
+    echo "All tests passed"
+    echo "$output"
+    exit $exit_code
+else
+    # Check if no tests were run
+    if echo "$output" | grep -q 'Tests run: 0, Failures: 0, Errors: 0, Skipped: 0'; then
+        echo "Tests run: 0"
+        echo "Error: No tests were executed (Tests run: 0)"
+        echo "You are seeing this cause the following appeared in the output: Tests run: 0, Failures: 0, Errors: 0, Skipped: 0"
+    else
+        echo "Some tests failed, had errors, or were skipped. This is not allowed. All tests must pass."
+    fi
+fi
+
+# If there was an error, print the output and exit with the error code
+if [ $exit_code -ne 0 ]; then
+    echo "Error: Maven test failed in the conformance tests folder with exit code $exit_code..."
+    echo "$output"
+    exit $exit_code
+fi
+
+echo "Finished running conformance tests..."
+echo "$output"
+# Echo the original exit code of the unittest command
+exit $exit_code

package/forge/rules/examples/integration-embedded-testing/run_unittests_java.sh

@@ -0,0 +1,51 @@
+#!/bin/bash
+
+# Export Java 21
+#export JAVA_HOME="/opt/homebrew/opt/openjdk@21/libexec/openjdk.jdk/Contents/Home"
+#export PATH="$JAVA_HOME/bin:$PATH"
+echo "JAVA_HOME: $JAVA_HOME"
+
+# Check if subfolder name is provided
+if [ -z "$1" ]; then
+  echo "Error: No subfolder name provided."
+  echo "Usage: $0 <subfolder_name>"
+  exit 1
+fi
+# FIX: Changed this line from "../../" to "../../.." to go up three levels to the main project folder
+MAIN_PROJECT_FOLDER="$(cd "$(dirname "$0")/../../.." && pwd)"
+
+if [ "${VERBOSE:-}" -eq 1 ] 2>/dev/null; then
+  printf "Copying generated code to main project folder: $MAIN_PROJECT_FOLDER\n"
+fi
+
+# Check if the main project folder exists
+if [ ! -d "$MAIN_PROJECT_FOLDER" ]; then
+  echo "Error: Main project folder '$MAIN_PROJECT_FOLDER' does not exist."
+  exit 2
+fi
+
+# clean existing code from the main project folder
+rm -rf $MAIN_PROJECT_FOLDER/<placeholder for integration code>/*
+rm -rf $MAIN_PROJECT_FOLDER/<placeholder for integration code tests>/*
+
+# copy generated code to the main project folder
+# FIX: added the mkdir lines otherwise it complains that the cp destintation directory does not exist
+mkdir -p $MAIN_PROJECT_FOLDER/<placeholder for integration code>
+mkdir -p $MAIN_PROJECT_FOLDER/<placeholder for integration code tests>
+cp -R $1/<placeholder for integration code>/* $MAIN_PROJECT_FOLDER/<placeholder for integration code>
+cp -R $1/<placeholder for integration code tests>/* $MAIN_PROJECT_FOLDER/<placeholder for integration code tests>
+
+# Move to the subfolder
+# FIX: added this line to print the current directory to help the LLM
+echo "Moving to: $MAIN_PROJECT_FOLDER"
+cd "$MAIN_PROJECT_FOLDER" 2>/dev/null
+
+if [ $? -ne 0 ]; then
+  printf "Error: Java build folder '$MAIN_PROJECT_FOLDER' does not exist.\n"
+  exit 2
+fi
+
+
+# Execute all Java unittests in the subfolder
+echo "Running Java unittests in $1..."
+mvn test -Dtest='<placeholder for integration code tests package>.**.*Test' checkstyle:check

package/forge/rules/impl-reqs.md

@@ -12,6 +12,12 @@ When writing or editing an `***implementation reqs***` section in a `.plain` fil
 - Observable behavior (endpoints, business rules, user-facing features) belongs in `***functional specs***`
 - Internal structure, technology choices, and coding guidance belong here
 
+## `:UnitTests:` lives here (hard rule)
+- **Everything** about `:UnitTests:` goes in `***implementation reqs***` — paths, approach, packages, framework, conventions, fixtures, mocking policy, file layout, naming, lint / static-analysis gates
+- `:UnitTests:` are part of the generated codebase (they sit inside `plain_modules/<module>/` alongside the implementation), so requirements that shape them are implementation reqs by definition
+- The unit-test generator reads **only** `***implementation reqs***` — anything about `:UnitTests:` placed elsewhere (e.g. `***test reqs***`) is silently ignored
+- Author each `:UnitTests:` requirement via `add-implementation-requirement` and phrase it in terms of `:UnitTests:` so the partition stays visible at a glance
+
 ## What belongs here
 - Technology choices: language, framework, runtime version
 - Architectural constraints: patterns, layering, dependency rules

package/forge/rules/integration-embedded-testing.md

@@ -0,0 +1,285 @@
+---
+description: Rules for authoring the three test scripts that an embedded ***plain integration ships
+globs: "**/*.plain"
+---
+
+# Rules for embedded-integration test scripts
+
+When an embedded integration ships its three `test_scripts/` (prepare-environment, unit, conformance) — whether you author them by hand or via the `implement-*-testing-script` skills — these rules apply on top of the shared testing-script rules in PLAIN_REFERENCE.md (exit-code conventions, the activate-only vs install-inline conformance distinction, `VERBOSE=1`, etc.).
+
+## Staging model (read this first)
+
+The three scripts do **not** all stage into the same place. Embedded integrations need a runnable host project, so the prepare and unit-test scripts operate **inside the host codebase itself**; only the conformance script uses a `.tmp/` scratch folder because the conformance suite lives in a separate project.
+
+| Script | Where it operates | What it does to the host source tree |
+|--------|-------------------|---------------------------------------|
+| `prepare_environment_<lang>` | Inside the host codebase | Copies `$1` into the module's package path under the host's source tree, then compiles / installs the host project |
+| `run_unittests_<lang>` | Inside the host codebase | Same copy as above (self-contained), then runs the module's unit tests + lint inside the host |
+| `run_conformance_tests_<lang>` | `.tmp/<lang>_conformance/` | Copies `$2` (the conformance-tests folder) into the scratch directory and runs the conformance suite there, which depends on the host build that `prepare_environment` already installed |
+
+This deliberately writes into the host's `src/main/...` and `src/test/...` (or the language equivalent). Two consequences flow from that:
+
+- **The host codebase root must come from a configured env var** (`HOST_CODEBASE_ROOT` is the conventional name; declare it in the integration's configuration concept). Scripts never hardcode it
+- **The destructive-op scoping rule below becomes critical.** `rm -rf` must target only the module's own package path under the host's source tree, never the host's `src/main/`, `target/`, `node_modules/`, or `build/` at the project root
+
+This rule covers the **mechanics each script must obey** regardless of language: argument handling, exit codes, idempotency, path resolution, output parsing, and the "what NOT to put here" guard rails. The language-specific install / test commands come from the skills; the contract below is invariant.
+
+## What the `.plain` spec must declare
+
+The three scripts are generated from facts in the integration's spec. For an embedded integration, those facts cannot be inferred — they have to be **declared explicitly** in the right section, partitioned by which predefined concept they describe:
+
+- **Everything about `:UnitTests:`** — paths, approach, packages, framework, conventions, fixtures, mocking policy — lives in `***implementation reqs***`. Unit tests are part of the generated codebase, so requirements that shape them are implementation reqs (see [`impl-reqs.md`](impl-reqs.md))
+- **Everything about `:ConformanceTests:`** — paths, approach, packages, framework, execution command, pass criteria, mocking policy — lives in `***test reqs***`. Conformance tests are external to the generated codebase, so requirements that shape them are test reqs (see [`test-reqs.md`](test-reqs.md))
+
+Authors use `add-implementation-requirement` for the first group and `add-test-requirement` for the second. The two groups are parallel — each predefined concept owns a complete authoring story in its own section.
+
+### In `***implementation reqs***` — everything about `:UnitTests:`
+
+These reqs feed `run_unittests_<lang>`. `prepare_environment_<lang>` is **not** part of the unit-test workflow — it exists for conformance (see the next subsection) and reads its own facts from `***test reqs***`. At minimum, declare:
+
+1. **Integration source path inside the host** — where `$1/<source>/*` gets copied to. Example: `src/main/java/com/example/integrations/foo`
+2. **`:UnitTests:` source path inside the host** — where `$1/<tests>/*` gets copied to, and where the test runner discovers unit tests. Example: `src/test/java/com/example/integrations/foo`
+3. **Fully qualified `:UnitTests:` package** — the package the test runner uses to scope discovery via its filter argument. Example: `com.example.integrations.foo`
+4. **`:UnitTests:` framework and conventions** — JUnit / pytest / Jest / Go's `testing` / etc., plus naming conventions (`*Test`, `test_*`, `*.test.ts`, …), fixture / mock / assertion style, file layout inside the test package
+5. **Quality gates that run alongside `:UnitTests:`** — Checkstyle / ESLint / Pylint / Ruff / `go vet` / `cargo clippy` — whatever the host project requires
+
+Author the location facts as one tight group, phrased in terms of `:UnitTests:`:
+
+```plain
+- :UnitTests: of :Implementation: live in `src/test/java/com/example/integrations/foo` inside the host codebase.
+  - The corresponding integration source code lives in `src/main/java/com/example/integrations/foo`.
+  - The fully qualified package used for :UnitTests: discovery is `com.example.integrations.foo`.
+  - :UnitTests: use JUnit 5 with the host's Checkstyle profile applied via `mvn checkstyle:check`.
+```
+
+These facts feed directly into the prepare and unit-test script bodies:
+
+```bash
+# clean existing code from the host
+rm -rf $MAIN_PROJECT_FOLDER/<integration source path>/*
+rm -rf $MAIN_PROJECT_FOLDER/<:UnitTests: source path>/*
+
+# create destinations and copy generated code into the host
+mkdir -p $MAIN_PROJECT_FOLDER/<integration source path>
+mkdir -p $MAIN_PROJECT_FOLDER/<:UnitTests: source path>
+cp -R $1/<integration source path>/* $MAIN_PROJECT_FOLDER/<integration source path>
+cp -R $1/<:UnitTests: source path>/* $MAIN_PROJECT_FOLDER/<:UnitTests: source path>
+
+# run :UnitTests: scoped to the integration's package
+mvn test -Dtest='<:UnitTests: package>.**.*Test' checkstyle:check
+```
+
+### In `***test reqs***` — everything about `:ConformanceTests:`
+
+These reqs feed `run_conformance_tests_<lang>`. At minimum, declare:
+
+1. **`:ConformanceTests:` source location** — where the conformance suite lives in the project (typically a sibling folder, e.g. `conformance_tests/<module>/`); the renderer passes the resolved path as `$2`
+2. **`:ConformanceTests:` framework and execution command** — `mvn test --no-transfer-progress`, `pytest`, `npm test`, `go test ./...`, etc., with any flags / profiles the project requires
+3. **Fully qualified `:ConformanceTests:` package** (or path / pattern) used to scope discovery, if the runner needs one
+4. **`:ConformanceTests:` network and secrets policy** — by default the suite runs against the **live provider** (see [`integrations.md`](integrations.md) → *`:ConformanceTests:` always run against the live integration*). Declare the env-var names the script reads (e.g. `<PROVIDER>_API_KEY`), whether the script loads a `.env` file before running, and any specific endpoints that are mocked because they can't be exercised live safely (429, forced 5xx)
+5. **`:ConformanceTests:` pass criteria** — the strict criteria from [*Pass criteria (strict)*](#pass-criteria-strict): at least one test ran AND zero failures / errors / skipped. Reaffirm this in the spec so the renderer knows the runner must parse the test tool's stdout
+6. **`:ConformanceTests:` build / install needs** — anything the conformance project needs before `mvn test` (or equivalent) will work: dependencies, fixtures, schema files, generated stubs
+
+Author the conformance facts as one or more entries, phrased in terms of `:ConformanceTests:`:
+
+```plain
+- :ConformanceTests: of :Implementation: live in `conformance_tests/foo/` and are implemented with JUnit 5 + Maven.
+  - The fully qualified package used for :ConformanceTests: discovery is `com.example.integrations.foo.conformance`.
+  - :ConformanceTests: are run via `mvn test --no-transfer-progress`; the host's Surefire plugin must be installed.
+  - :ConformanceTests: run against the live :ProviderName: sandbox — no mocking of provider calls.
+  - The conformance script reads `<PROVIDER>_API_KEY` (and any additional secrets) from the shell or from a `.env` file at the project root and fails fast (exit `69`) if any required var is missing after the optional `.env` load.
+  - The 429 (rate-limit) and forced-5xx paths use a local mock for that specific endpoint; every other path is live.
+  - :ConformanceTests: pass only when the Surefire summary line shows at least one test ran with zero failures, zero errors, and zero skipped.
+```
+
+These facts feed directly into the conformance script body:
+
+```bash
+# stage :ConformanceTests: source into the scratch directory
+find "$DIR" -mindepth 1 -exec rm -rf {} +
+cp -R $2/* $DIR
+cd $DIR
+
+# build the conformance project, then run :ConformanceTests:
+mvn clean install -DskipTests
+output=$(mvn test --no-transfer-progress 2>&1)
+
+# parse Surefire summary against the declared pass criteria, then exit accordingly
+```
+
+### Rules common to both sections
+
+- **The paths must agree across reqs.** The `:UnitTests:` source path, the `:UnitTests:` package, and the integration source path describe the same module from three angles. Same for the `:ConformanceTests:` location and its package. A mismatch (e.g. test path `src/test/java/com/example/foo` but test package `com.example.bar`) silently produces a green build with stale or zero tests
+- **Paths are host-relative**, not absolute. `MAIN_PROJECT_FOLDER` comes from `HOST_CODEBASE_ROOT` (declared in the configuration concept); the paths above join onto it
+- **The renderer's output folder `$1` mirrors the same layout.** `$1/<integration source path>/*` exists because the renderer emits the generated code into the same package directories it'll be copied into — the `cp -R` is a straight overlay, not a path translation
+- **Each fact lives in one place.** If two `***implementation reqs***` entries declare slightly different `:UnitTests:` paths (or two `***test reqs***` entries declare slightly different `:ConformanceTests:` packages), the renderer can't tell which to use. Author each group as a tight cluster (one bullet with sub-bullets) so a future reviewer sees them together
+- **Never duplicate a fact across sections.** `:UnitTests:` facts belong **only** in `***implementation reqs***`; `:ConformanceTests:` facts belong **only** in `***test reqs***`. The two groups never overlap — the script generators read each from its own section
+- **For non-Java languages**, the facts have language-specific equivalents — Python: `src/foo/`, `tests/foo/`, `tests.foo`; Node: `src/foo/`, `test/foo/`, `test/foo/**/*.test.ts`. The `implement-*-testing-script` skills know the mapping per language, but the spec still has to declare the host-relative paths and packages so the skill knows what to put in the script bodies
+
+## Common contract (all three scripts)
+
+All three scripts are invoked by the `codeplain` renderer with positional arguments. They MUST:
+
+1. **Be POSIX-bash (`.sh`) on macOS / Linux, PowerShell (`.ps1`) on Windows.** Executable, idempotent — re-running with the same inputs produces the same result
+2. **Validate every positional argument up front.** Exit with a clear `Usage:` line on bad args. Conventional exit codes (consistent with the shared testing-script rules):
+   - `1` — bad arguments / usage error (and "no tests discovered" for the conformance runner)
+   - `2` — missing or inaccessible input folder
+   - `69` — unrecoverable environment failure (missing toolchain, cannot enter working folder, install failed)
+   - Any other non-zero code — propagated verbatim from the underlying build / test tool
+3. **Echo the toolchain home at the top** — the first thing a developer checks when CI breaks. For Java: `JAVA_HOME`. For Python: the active interpreter (`python --version` / `which python`). For Node: `node --version`. For Go: `go env GOROOT`. Pick the variable whose value most often explains "why does it work locally but not on the CI runner?"
+4. **Respect `VERBOSE=1`.** Gate chatty diagnostic prints behind `if [ "${VERBOSE:-}" = "1" ]` (and the PowerShell equivalent). Errors and key step markers print unconditionally
+5. **Resolve paths relative to the script, not `$PWD`.** Use `"$(cd "$(dirname "$0")/<relative-path-to-anchor>" && pwd)"`. Hard-coded `../../` chains break the moment the renderer's `cwd` changes
+6. **Create destination directories before copying.** `mkdir -p` before any `cp -R` / `rsync` / `robocopy` — most copy commands do not create intermediate directories and fail silently in some shells
+7. **Scope destructive operations narrowly.** Any `rm -rf` (or `Remove-Item -Recurse -Force`) targets only the module's own package path inside the working folder — never the host's `src/`, `target/`, `node_modules/`, `build/`, or `dist/` at the project root. Only `prepare_environment` owns the build-output directory's lifecycle for its `.tmp/` working folder
+8. **Print where you are before you `cd`.** `echo "Moving to: $DIR"` saves an hour of debugging when paths are wrong. PowerShell: `Write-Host "Moving to: $DIR"`
+
+## 1. `prepare_environment_<lang>` — copy into the host, then compile
+
+Receives one positional argument: the renderer's build output folder (e.g. `plain_modules/<module>/`).
+
+Purpose: stage the generated code **into the host codebase at the module's package path**, then run the host's install / build so that downstream test projects (specifically the conformance suite) can depend on it from the local dependency cache.
+
+Required steps:
+
+1. Validate `$1` (the renderer's output folder); fail with usage if missing
+2. Resolve the host codebase root from the env var declared in the `host-codebase` concept (`HOST_CODEBASE_ROOT` is the conventional name; surface it in `--help` / usage)
+3. `rm -rf` the module's package directories under the host's source tree — both main / source AND test directories. Both, because stale tests in the target package cause confusing failures
+4. `mkdir -p` the destination directories
+5. Copy `$1/src/...` (or the language-equivalent layout) into the host's source tree at the module's package path
+6. `cd` into the host codebase root, verify with an explicit exit-code check (`if [ $? -ne 0 ]` / `if (! $?) { ... }`)
+7. Clean the host's build-output directory before compiling — stale class / object files from a previous build cause confusing link-time mismatches when the contract has changed. Maven: `rm -rf ./target`. Cargo: `cargo clean -p <pkg>`. Go: `go clean -cache` (usually unnecessary, but mention if applicable). For npm projects with incremental builds disabled, wipe the relevant `dist/` / `build/` folder
+8. Run the host's standard install / build command — but **skip the fat-artifact and skip tests** when the build system supports it:
+   - Maven: `mvn clean install -DskipTests` (plus any host-specific repackage-skip flag)
+   - npm / pnpm / yarn: `npm ci` (no test script; dependency install only)
+   - Python: `pip install -e .` (then any extra integration dependencies)
+   - Go: `go mod tidy && go build ./...`
+   - Cargo: `cargo fetch && cargo build --tests --no-run`
+9. Exit `0` on success; propagate the underlying build tool's exit code on failure
+
+**Why this script exists separately.** Conformance tests live in a separate project and resolve the integration's code as a dependency from a local cache (`~/.m2`, `node_modules`, the language equivalent). Without an explicit install step, conformance tests link against whatever was last built — which may not be the renderer's most recent output.
+
+## 2. `run_unittests_<lang>` — copy into the host, then run unit tests there
+
+Receives one positional argument: the renderer's build output folder.
+
+Purpose: stage the generated code **into the host codebase** (the same way `prepare_environment` does) and run the module's unit tests + language-appropriate quality gates against the host project from inside the host root.
+
+Required steps:
+
+1. Validate `$1`
+2. Resolve the host codebase root from the configured env var
+3. `rm -rf` the module's main + test package directories under the host's source tree
+4. `mkdir -p` and copy `$1/src/...` into place — **same staging as `prepare_environment`**
+5. `cd` into the host codebase root
+6. Run the test command **scoped to the module's package only**:
+   - Maven: `mvn test -Dtest='<fully.qualified.package>.**.*Test' <lint-check>:check`
+   - pytest: `pytest tests/<module>/` (or whatever path matches the module)
+   - Jest: `npm test -- --testPathPattern '<module>/'`
+   - Go: `go test ./<module>/...`
+7. Always include the host's lint / static-analysis gate in the same invocation when the build system has one (Checkstyle, ESLint, Pylint / Ruff, `go vet`, `cargo clippy`, …). Running tests without the lint gate produces a false-green when style violations would otherwise block the build
+
+Hard rules:
+
+- **Yes, this duplicates `prepare_environment`'s copy step.** That's intentional — `run_unittests` must be self-contained per the shared testing-script rules (there is no activate-only variant for unit tests). A user invoking the unit-test script independently must not need `prepare_environment` to have run first
+- **Never use a "clean and test" shortcut** (`mvn clean test`, `npm run rebuild`, …) — the cleanup belongs in `prepare_environment` and would erase whatever it installed
+- **Never run the full test suite** when scoping is possible. A per-module script that runs the entire host's tests wastes minutes on every render iteration
+
+## 3. `run_conformance_tests_<lang>` — copy into `.tmp/`, then run the external suite
+
+Receives two positional arguments: the renderer's build output folder (`$1`) and the conformance-tests folder (`$2`).
+
+Purpose: run the conformance suite in `$2` against the build that `prepare_environment` produced. The conformance suite is a separate project that consumes the integration as a dependency.
+
+Required steps:
+
+1. Validate `$1` and `$2`. **Only `$2` is actually used by the script body today** — but keep `$1` in the signature; the renderer passes both positionally
+2. Stage `$2/*` into a scratch directory under `.tmp/<lang>_conformance/`. Wipe it first if it exists. Use a deletion form that handles hidden files and odd shells safely:
+   - Bash: `find "$DIR" -mindepth 1 -exec rm -rf {} +` (safer than `rm -rf "$DIR"/*`)
+   - PowerShell: `Remove-Item -Recurse -Force "$DIR\*"` after confirming the path exists
+3. `cd` into the scratch directory
+4. Compile / set up the conformance project — exit early if this fails:
+   - Maven: `mvn clean install -DskipTests`
+   - npm: `npm ci`
+   - Python: `pip install -r requirements.txt`
+   - Go / Cargo: standard build
+5. Run the conformance test command and **capture stdout to a variable**:
+   - Bash: `output=$(mvn test --no-transfer-progress 2>&1)` (or the language equivalent)
+   - PowerShell: `$output = & <cmd> 2>&1 | Out-String`
+6. **Parse the captured output strictly** (see *Pass criteria* below) — don't trust the test tool's exit code alone
+7. On the failure path: print the captured output unconditionally so the renderer (and the user) can see what failed
+8. On the success path: print the output only if `VERBOSE=1`
+
+### Secrets and `.env` handling
+
+`:ConformanceTests:` run against the live provider (per [`integrations.md`](integrations.md) → *`:ConformanceTests:` always run against the live integration*), so the conformance script needs the user's credentials at runtime.
+
+- **Credentials are read from environment variables** named in `***test reqs***` and the auth concept. Never from a literal, never from a file checked into the repo
+- **The script may optionally load a `.env` file** before running the suite. Typical pattern in Bash:
+
+  ```bash
+  ENV_FILE="${ENV_FILE:-$MAIN_PROJECT_FOLDER/.env}"
+  if [ -f "$ENV_FILE" ]; then
+      echo "Loading env from $ENV_FILE"
+      set -a; . "$ENV_FILE"; set +a
+  fi
+  ```
+
+  PowerShell uses the equivalent `Get-Content` + `Set-Item Env:` loop. Absence of `.env` is **not** an error — CI provides the same vars directly through the shell
+- **Verify required env vars exist after the optional `.env` load** and fail fast if any are missing:
+
+  ```bash
+  for var in PROVIDER_API_KEY PROVIDER_ACCOUNT_ID; do
+      if [ -z "${!var:-}" ]; then
+          printf "Error: %s is required for :ConformanceTests:\n" "$var" >&2
+          exit 69
+      fi
+  done
+  ```
+
+- **Export the resolved vars** (already in scope thanks to `set -a`) so child processes started by the test runner inherit them — Maven, pytest, npm, Go all read env vars from their parent process
+- **Never log credential values.** Echo the env-var **name** when reporting "loaded", not its value. Redact in any error path that dumps captured output
+- **Document the secret names twice** — once in the auth concept (for the runtime), once in `***test reqs***` for `:ConformanceTests:` (for the script). They must be the same names; a divergence means the script reads different credentials than the runtime does, and conformance silently tests the wrong account
+
+### Pass criteria (strict)
+
+These are the **only** valid pass criteria. Anything outside this list is a failure:
+
+- At least one test ran AND zero failures AND zero errors AND zero skipped. Maven example: `Tests run: [1-9][0-9]*, Failures: 0, Errors: 0, Skipped: 0`. Each language's test runner has an equivalent summary line — match it with a regex, not by substring
+- Exit with the test tool's exit code on the success path (almost always `0`)
+
+Failure cases — each must be detected explicitly:
+
+- `Tests run: 0` (or the language equivalent) → **failure**. The renderer must never be told "green" when nothing ran. Exit `1` per the shared testing-script rules (the "no tests discovered" exit code)
+- Any non-zero `Failures:`, `Errors:`, or `Skipped:` count → **failure**. Dump the captured output and propagate the test tool's exit code
+- The test tool exited non-zero but the summary line shows `Tests run: 0` → still a `1` (no-tests-discovered), not the tool's own exit code
+
+**Why parse stdout instead of trusting the test tool's exit code.** Every major test runner returns `0` when zero test classes match a filter. Maven Surefire, pytest with no collected tests, `go test ./pkg/that/has/no/_test.go/files`, Jest with an empty pattern — all green-by-default. The renderer's contract is "tests must run AND must pass" — the exit code alone cannot express that.
+
+## Cross-cutting rules
+
+- **No secrets in scripts.** Read credentials from env vars the renderer (or the user's shell) already sets. If a required env var is missing, fail fast with a clear `Error: $FOO is required for ...` and exit `69`. Never hardcode an API key, never read from a checked-in file
+- **Mirror the package / module path exactly.** A typo in the package segment (e.g. one wrong directory in `com/example/foo/...` or `host_pkg/foo/bar/...`) makes `rm -rf` silently do nothing and the subsequent copy put files in the wrong place. Both produce a **green** build with stale code. Derive the package path from the `host-codebase` concept; never retype it inline
+- **Don't add cleverness to the script that belongs in the build.** If you're tempted to `grep` the test output for more than the pass/fail summary, change the test or the test-runner config instead. The script is a thin contract — keep it that way
+- **Don't use shortcut profiles that skip quality gates.** Maven's `-Pfast`, Gradle's `-x check`, npm's `--ignore-scripts`, pytest's `--no-cov`, `-DskipTests` outside `prepare_environment` — all defeat the purpose of these scripts. The build's full quality gate (tests + lint + coverage thresholds) must run for unit and conformance
+- **Failure messages are for humans.** `printf "Error: <what failed> at <where>\n"` then exit with the right code. No silent failures, no `|| true` to paper over errors, no `2>/dev/null` on commands whose stderr matters
+- **Use existing scripts as templates.** When you add a new embedded integration, copy from a known-good module, then search-and-replace only the package path and the test-filter argument. Resist the urge to "improve" structure mid-port — pattern-matching across many modules is a feature, not a bug
+
+## Reference implementation (Java + Maven)
+
+A working three-script set for a Java / Maven embedded integration lives under [`examples/integration-embedded-testing/`](examples/integration-embedded-testing/) next to this file:
+
+- [`prepare_environment_java.sh`](examples/integration-embedded-testing/prepare_environment_java.sh) — copies `$1` into the host's source tree, cleans `target/`, runs `mvn clean install -DskipTests`
+- [`run_unittests_java.sh`](examples/integration-embedded-testing/run_unittests_java.sh) — re-stages into the host and runs `mvn test -Dtest='<module-pkg>.**.*Test' checkstyle:check`
+- [`run_conformance_tests_java.sh`](examples/integration-embedded-testing/run_conformance_tests_java.sh) — copies `$2` into `.tmp/java_conformance/`, builds the conformance project, runs the suite, and parses the Surefire summary line per the strict pass criteria above
+
+Use them as a template when adding a new embedded integration in Java / Maven — copy, search-and-replace only the package segment and the `-Dtest` filter, then wire into `config.yaml`. For other languages (Python, Node.js, Go, Rust, …), the `implement-*-testing-script` skills generate the equivalent three-script set following the same contract.
+
+## Adding a script for a new module
+
+1. Copy the three scripts from a working embedded-integration module into the new module's directory
+2. Search-and-replace the package segment everywhere it appears — including the test-filter argument (the most commonly missed spot)
+3. `chmod +x` all three (and verify ACLs on Windows for the `.ps1` siblings)
+4. Wire them into the module's `config.yaml` via the `unittests-script`, `conformance-tests-script`, and `prepare-environment-script` keys. Use `init-config-file` to assemble the canonical form
+5. Smoke-test by running each script manually with the renderer's output folder as `$1` (and the conformance-tests folder as `$2` for the conformance runner). Confirm exit codes match what the renderer expects
+
+For non-Java languages, the plain-forge skills [`implement-prepare-environment-script`](../skills/implement-prepare-environment-script/SKILL.md), [`implement-unit-testing-script`](../skills/implement-unit-testing-script/SKILL.md), and [`implement-conformance-testing-script`](../skills/implement-conformance-testing-script/SKILL.md) adapt the contract above to Python, Node.js, Go, Rust, Flutter, and others. Always route script creation through these skills so the cross-cutting rules above are applied uniformly.

package/forge/rules/integration-embedded.md

@@ -9,6 +9,8 @@ When an integration `.plain` module is **embedded** — meaning the generated co
 
 Embedded means: the host codebase already exists, has its own language / framework / dependency manager / packaging layout, and the integration must conform to all of that without negotiation.
 
+> **For test-script authoring**, also follow [`integration-embedded-testing.md`](integration-embedded-testing.md). It defines the per-script contract (`prepare_environment_<lang>`, `run_unittests_<lang>`, `run_conformance_tests_<lang>`) — staging into the host vs `.tmp/`, arg validation, exit codes, output parsing, the three `***implementation reqs***` entries the spec must declare so the scripts can be generated, and a Java / Maven reference implementation. This file (`integration-embedded.md`) only summarizes the test-script wiring; the testing rule is the source of truth.
+
 ## The host codebase dictates the tech stack (hard rule)
 
 - Language, framework, dependency manager, packaging layout, coding standards, error model, logging library, and architecture are **inherited** from the host — they are **never chosen** by the integration spec
@@ -16,6 +18,29 @@ Embedded means: the host codebase already exists, has its own language / framewo
 - If a Phase 3 (`forge-plain`) tech-stack question seems to push back on a host rule, treat the host as ground truth and rewrite the question
 - Implementation reqs added in Phase 3 are **transcribed** from the host stack verbatim — host language and exact version, host framework + version, dependency manager and manifest path, packaging layout, host conventions the contract must follow, and every host-package version the contract pins
 
+## Project layout — the integration lives under `plain/` at the host root
+
+The embedded integration's `.plain` specs (and the rest of the ***plain project — `template/`, `resources/`, `test_scripts/`, `config.yaml`, generated `plain_modules/`) live in a single top-level `plain/` folder at the host repository root, alongside the host's own source tree:
+
+```
+<host repo>/
+├── docs/
+├── plain/          # ← the embedded ***plain integration lives here
+│   ├── <module>.plain
+│   ├── template/
+│   ├── resources/
+│   ├── test_scripts/
+│   ├── plain_modules/     # generated; gitignored
+│   └── config.yaml
+└── src/            # host source tree (Java, Python, etc.)
+```
+
+This keeps the integration self-contained in one directory the user can `cd` into to render, while leaving the host's own source layout untouched.
+
+- If the host **already** has a `plain/` directory, adopt it verbatim — see step 1 of *Discover before you ask* below
+- If the host does **not** yet have one, create `plain/` at the repo root; do not invent a different name (`specs/`, `plain_specs/`, …)
+- The three test scripts still `cd` into `$HOST_CODEBASE_ROOT` (the host repo root) to compile and run tests against the host project; the `plain/` folder is the integration's **authoring** root, not its **runtime** root
+
 ## Discover before you ask
 
 Run host discovery **before** the first Phase 1 question. Treat the results as ground truth for everything that follows.
@@ -91,47 +116,26 @@ The renderer reads the directives from the spec and the shapes from the linked s
 - If two reqs are in tension (one from the host, one newly authored), the host wins; rewrite or drop the newly authored req
 - Do not author a req that re-declares something the host already enforces — that's a maintenance burden with no benefit
 
-## Test-script wiring — merge `plain_modules` into the host, run tests there
+## Test-script wiring — copy into the host, run tests there
 
-Embedded integrations are tested **inside a working copy of the host codebase** with the generated `plain_modules/` overlaid on top. Both `run_unittests_<lang>` and `run_conformance_tests_<lang>` follow this pattern — neither uses `PYTHONPATH` / `NODE_PATH` tricks to stitch two trees together at import time. The host *is* the runtime environment; the generated module is dropped into it and exercised as if it had always lived there.
+Embedded integrations are tested **inside the host codebase itself**. The prepare and unit-test scripts copy the renderer's output (`$1`, i.e. `plain_modules/<module>/`) into the host's source tree at the module's package path, then compile / test the host project in place. Only the conformance script uses a `.tmp/` scratch folder, because the conformance suite is a separate project that consumes the host build as a dependency.
 
 This matters because the integration's generated code references host symbols by their full import path (e.g. `from host_project.integrations.base import IntegrationContract`). Those imports only resolve cleanly when the test process is rooted in the host's package layout — anything else creates path edge cases that bite later in conformance failures.
 
-### The merge step (used by both `prepare_environment` and `run_unittests`)
-
-Both scripts stage their own working copy under `.tmp/<lang>_<arg>/` per the shared testing-script rules (input folders are read-only). Inside that working folder:
-
-1. **Copy the host codebase into the working folder.** Use a recursive copy (`rsync -a --delete`, `cp -R`, or `robocopy`) so each test run starts from a clean, identical host tree
-2. **Overlay `plain_modules/<module>/` into the host's package tree at the target package path** recorded in the `host-codebase` concept (e.g. `plain_modules/integrations/<provider>/` → `<host_copy>/host_project/integrations/<provider>/`). Use a copy that overwrites — the generated module replaces any same-named files in the host copy
-3. **Install dependencies inside the merged tree.** The host's own manifest (`pyproject.toml` / `package.json` / `go.mod` / …) drives the install. The integration's extra dependencies are layered on top by either (a) the renderer having written them into the host's manifest already, or (b) the script installing them explicitly after the host install
-4. **Run the test command from inside the merged tree** — `cwd` is `<host_copy>`, and the test runner discovers tests using the host's normal layout
-
-### Per-script responsibilities
-
-- **`prepare_environment_<lang>`** performs the full merge once per render (host copy + plain_modules overlay + dependency install + any build artifacts) into `.tmp/<lang>_<arg>/`. The N subsequent `run_conformance_tests_<lang>` invocations attach to this populated folder (activate-only variant — see the shared testing-script rules)
-- **`run_unittests_<lang>`** performs its **own** merge into its **own** `.tmp/<lang>_<arg>/` working folder — it does not share `prepare`'s folder, and it does not depend on `prepare` having run. The host copy + overlay + install steps are duplicated inside the unit-test script for self-containedness
-- **`run_conformance_tests_<lang>`** does **not** re-merge. It `cd`s into the working folder that `prepare_environment` populated and runs the conformance command against the merged tree
-
-### Language-specific merge primitives
-
-| Language | Host copy | Overlay | Dependency install | Test invocation (inside merged tree) |
-|----------|-----------|---------|--------------------|--------------------------------------|
-| Python | `rsync -a <host>/ .tmp/python_<arg>/` | `rsync -a plain_modules/<module>/ .tmp/python_<arg>/<host_pkg_path>/` | `cd .tmp/python_<arg> && pip install -e .` (then integration extras) | `cd .tmp/python_<arg> && pytest …` |
-| Node.js | `rsync -a <host>/ .tmp/node_<arg>/` | `rsync -a plain_modules/<module>/ .tmp/node_<arg>/<host_pkg_path>/` | `cd .tmp/node_<arg> && npm ci` (then integration extras) | `cd .tmp/node_<arg> && npm test …` |
-| Go | `rsync -a <host>/ .tmp/go_<arg>/` | `rsync -a plain_modules/<module>/ .tmp/go_<arg>/<host_pkg_path>/` | `cd .tmp/go_<arg> && go mod tidy` | `cd .tmp/go_<arg> && go test ./…` |
-| Java / Kotlin | `rsync -a <host>/ .tmp/java_<arg>/` | `rsync -a plain_modules/<module>/ .tmp/java_<arg>/<host_pkg_path>/` | `cd .tmp/java_<arg> && mvn -q -DskipTests install` | `cd .tmp/java_<arg> && mvn test …` |
-| Rust | `rsync -a <host>/ .tmp/rust_<arg>/` | `rsync -a plain_modules/<module>/ .tmp/rust_<arg>/<host_pkg_path>/` | `cd .tmp/rust_<arg> && cargo fetch` | `cd .tmp/rust_<arg> && cargo test …` |
+See [`integration-embedded-testing.md`](integration-embedded-testing.md) for the full per-script contract (arg validation, exit codes, idempotency, output parsing, pass criteria, cross-cutting rules). The summary that belongs in *this* file:
 
-Adjust the language-specific install / test commands to whatever the host's manifest actually uses (Poetry instead of pip, pnpm instead of npm, Gradle instead of Maven, …). The merge primitive itself does not change.
+- **`prepare_environment_<lang>`** copies `$1` into the host's source tree at the module's package path, cleans the host's build-output directory, then runs the host's install / build (e.g. `mvn clean install -DskipTests`). The conformance suite later resolves the integration from the host's local dependency cache
+- **`run_unittests_<lang>`** repeats the same copy into the host (self-contained — must work without `prepare_environment` having run first), then runs the module's unit tests + lint scoped to the module's package
+- **`run_conformance_tests_<lang>`** copies `$2` (the conformance-tests folder) into `.tmp/<lang>_conformance/`, `cd`s in, builds the conformance project, and runs it against the build that `prepare_environment` already installed into the host
 
 ### Invariants the scripts must enforce
 
 - **Host root is a parameter, not a literal.** No script may hardcode an absolute host path. Read the host root from an env var (e.g. `HOST_CODEBASE_ROOT`) with a sensible default matching the user's layout (e.g. `../host_project`). Surface the env var in each script's `--help` / usage banner. Capture this env var in the integration's configuration concept so it has exactly one declared name across specs, scripts, and runtime
-- **Target package path is read from the `host-codebase` concept** — never inferred from a heuristic. The renderer writes that path into the generated module's location too, so the overlay destination is unambiguous
-- **The host source tree is read-only.** The merge writes into `.tmp/<lang>_<arg>/`; the user's `<host>` checkout is never modified. If a script appears to need to write into `<host>`, it is buggy — the working copy under `.tmp/` is what's mutable
-- **Each merge is idempotent.** Re-running the script (or two scripts back-to-back) yields the same merged tree
-- **No new `config.yaml` key is needed** — the merge happens inside the scripts. The renderer reads the `host-codebase` concept (for the package path) and the configuration concept (for `HOST_CODEBASE_ROOT`) to wire the script bodies correctly
-- **`***test reqs***` must document the merge contract** — name the merge primitive (`rsync` / `cp -R` / `robocopy`), the env var the host root is read from, the target package path inside the host where `plain_modules/<module>/` is overlaid, and the language-appropriate install + test commands. The renderer reads this req and emits the right script bodies
+- **Everything about `:UnitTests:` is declared in `***implementation reqs***`** — paths, approach, packages, framework, conventions. The prepare and unit-test scripts derive their copy destinations and test-filter argument from these reqs. See [`integration-embedded-testing.md`](integration-embedded-testing.md) for the exact reqs the spec must author (phrased in terms of `:UnitTests:`)
+- **Everything about `:ConformanceTests:` is declared in `***test reqs***`** — paths, approach, packages, framework, execution command, pass criteria, mocking policy. The conformance script derives its build and run steps from these reqs. See [`integration-embedded-testing.md`](integration-embedded-testing.md) for the exact reqs (phrased in terms of `:ConformanceTests:`)
+- **The two groups never overlap.** `:UnitTests:` facts belong only in `***implementation reqs***`; `:ConformanceTests:` facts belong only in `***test reqs***`. Neither lives in the `host-codebase` concept
+- **Destructive ops are scoped to the module's own package path** under the host's source tree. `rm -rf` never touches the host's `src/main/`, `target/`, `node_modules/`, `build/`, or `dist/` at the project root. Only the module-specific package directories are wiped
+- **Each script is idempotent.** Re-running the same script with the same `$1` yields the same result
 
 ## Embedded-specific completion checklist
 
@@ -143,13 +147,14 @@ Before declaring an embedded integration done, in addition to the shared checkli
 - [ ] Every host file the integration touches is linked at its **original host-relative path** — no host file has been copied into `resources/host/` or anywhere else, and no host file contents are inlined in any spec
 - [ ] `forge-plain` Phase 2's tech-stack decisions are transcribed verbatim from the host (no independent stack choices)
 - [ ] Host-package version pins are copied into `***implementation reqs***`
-- [ ] `prepare_environment` copies the host into `.tmp/<lang>_<arg>/`, overlays `plain_modules/<module>/` at the target package path, installs the merged tree's dependencies, and is the working folder conformance attaches to
-- [ ] `run_unittests` runs the same host-copy + overlay + install sequence into its **own** `.tmp/<lang>_<arg>/` and invokes the test runner from inside the merged tree
-- [ ] `run_conformance_tests` `cd`s into `prepare_environment`'s populated working folder and runs the conformance command from there — it does not re-merge and does not use import-path stitching
-- [ ] Host codebase root is read from a named env var (default value documented in each script's usage) — never hardcoded
-- [ ] Target package path (where `plain_modules/<module>/` is overlaid inside the host copy) is read from the `host-codebase` concept — never inferred
-- [ ] The host source tree itself is never written to — every script mutation lands in `.tmp/<lang>_<arg>/`
-- [ ] A `***test reqs***` entry documents the merge contract (primitive used, env var name, target package path inside the host, install + test commands)
+- [ ] `prepare_environment` copies `$1` into the host's source tree at the module's package path, cleans the host's build-output directory, and runs the host's install / build so the conformance suite can resolve the integration from the local dependency cache
+- [ ] `run_unittests` runs the same copy-into-host sequence (self-contained — does not depend on `prepare_environment` having run) and invokes the host's test runner scoped to the module's package
+- [ ] `run_conformance_tests` copies `$2` into `.tmp/<lang>_conformance/`, `cd`s in, builds the conformance project, and runs it against the host build that `prepare_environment` already installed
+- [ ] Host codebase root is read from a named env var (default value documented in each script's usage) — never hardcoded; the env var name is captured in the integration's configuration concept
+- [ ] `***implementation reqs***` declares **everything about `:UnitTests:`** — integration source path, `:UnitTests:` source path, `:UnitTests:` package, framework + conventions, lint / static-analysis gate — per [`integration-embedded-testing.md`](integration-embedded-testing.md)
+- [ ] `***test reqs***` declares **everything about `:ConformanceTests:`** — source location, framework + execution command, package, mocking / network policy, pass criteria, build / install needs — per [`integration-embedded-testing.md`](integration-embedded-testing.md)
+- [ ] Neither group is duplicated across sections: `:UnitTests:` facts never appear in `***test reqs***`, `:ConformanceTests:` facts never appear in `***implementation reqs***`, and neither lives in the `host-codebase` concept
+- [ ] Every `rm -rf` in the scripts is scoped to the module's own package directory under the host's source tree — never targets the host's `src/main/`, `target/`, `node_modules/`, `build/`, or `dist/` at the project root
 
 ## Anti-patterns specific to embedded integrations
 
@@ -160,6 +165,6 @@ Before declaring an embedded integration done, in addition to the shared checkli
 - **Hardcoding the host codebase path in any spec or script.** Read it from the env var declared in the configuration concept
 - **Asking the user to design the integration's tech stack.** Read it from the host's manifest files
 - **Authoring an integration spec that contradicts an existing integration in the same host** without first surfacing the conflict and getting explicit user confirmation
-- **Wiring tests with `PYTHONPATH` / `NODE_PATH` / Go `replace` directives instead of physically merging `plain_modules/<module>/` into a host copy.** The import-stitching approach is forbidden — every embedded test run starts by overlaying the generated module onto a working copy of the host tree
-- **Writing into the user's `<host>` checkout from any test script.** The host source is read-only; the merged tree lives in `.tmp/<lang>_<arg>/`
-- **Sharing one `.tmp/` working folder between `run_unittests` and `run_conformance_tests`.** Each script stages its own copy; only `run_conformance_tests` attaches to the folder `prepare_environment` populated
+- **Wiring tests with `PYTHONPATH` / `NODE_PATH` / Go `replace` directives instead of physically copying `$1` into the host's package tree.** The import-stitching approach is forbidden — every prepare / unit test starts by copying the generated module into the host's source tree at the module's package path
+- **Letting an `rm -rf` in a test script reach the host's `src/main/`, `target/`, `node_modules/`, `build/`, or `dist/` at the project root.** Destructive ops are scoped strictly to the module's own package directory. A wrong package path in the script silently does nothing and copies files in the wrong place — both produce a green build with stale code
+- **Running conformance tests against a stale local dependency cache.** `prepare_environment` must run before conformance for the conformance project to resolve the integration from `~/.m2` (or the language equivalent). If conformance gets invoked without a fresh prepare, dependent on which build last hit the cache, the suite tests the wrong code

package/forge/rules/integration-standalone.md

@@ -100,15 +100,17 @@ Separate from the provider's API version (which lives in the provider OpenAPI fi
 
 Capture as a contract-version concept; pin the version in every published schema.
 
-## Testing — live vs recorded, sandbox credentials, webhooks
+## Testing — live conformance, secrets from env, webhooks
 
-Standalone integrations get tested in isolation, so the testing strategy must be explicit (capture each decision as a `***test reqs***` entry):
+`:ConformanceTests:` for a standalone integration **run against the live provider** (see [`integrations.md`](integrations.md) → *`:ConformanceTests:` always run against the live integration*). The testing strategy is captured as `***test reqs***` entries authored via `add-test-requirement`:
 
-- **Live vs. recorded conformance tests.** Live tests hit the provider (requires sandbox creds in CI, may be rate-limited). Recorded tests use VCR-style cassettes or prerecorded responses under `resources/fixtures/`. Mock-server tests use a local stub (WireMock, Mockoon, MSW). Each has tradeoffs — pick one (or a mix) and document it
-- **Sandbox credentials in CI.** If live tests are in scope, name where credentials come from (CI secret store, dedicated test tenant) and the rotation / leak-response policy
-- **Webhook tests** (if webhooks are in scope) must cover signature verification end-to-end — including invalid signatures and replay attempts
-- **Rate-limit tests.** Tests that exercise the 429 path must **not** exhaust the live API's quota — use a local mock for those cases
-- **Idempotency tests.** Run the same mutating call twice (with the same idempotency key) and assert the same response — either against the live sandbox or against a recorded duplicate fixture
+- **Conformance is live by default.** No VCR cassettes, no prerecorded responses for the calls under test, no mock servers. A green conformance run that never touched the provider proves nothing. Recorded responses under `resources/fixtures/` exist for unit tests and for grounding the OpenAPI schemas — not for conformance
+- **Secrets come from environment variables.** Pin every credential as an env-var name (e.g. `<PROVIDER>_API_KEY`, `<PROVIDER>_CLIENT_ID` + `<PROVIDER>_CLIENT_SECRET`) in `***test reqs***` and in the auth concept. Use the names the provider's docs use so users don't have to translate
+- **The user supplies values via `.env` or the shell.** The project ships `.env.example` (gitignored `.env` for real values). CI provides the same env-var names from its secret store. The conformance script may optionally `source` a `.env` from the project root if one exists; it must verify every required var is set after that optional load and fail fast (exit `69`) on missing vars
+- **Sandbox credentials in CI.** Name where credentials come from (CI secret store, dedicated test tenant), the rotation / leak-response policy, and the env-var names CI must set
+- **Webhook tests** (if webhooks are in scope) must cover signature verification end-to-end — including invalid signatures and replay attempts. Signing keys are env vars, like every other secret
+- **Rate-limit (429) tests.** The 429 path must **not** exhaust the live API's quota — use a local mock for that specific endpoint, document the exception in `***test reqs***`. Every other path remains live
+- **Idempotency tests.** Run the same mutating call twice (with the same idempotency key) against the live sandbox and assert the same response
 
 ## Standalone-specific completion checklist
 

package/forge/rules/integrations.md

@@ -51,6 +51,39 @@ Documentation lies — it goes stale, omits undocumented fields, describes a dif
 - **Only `GET` / `HEAD` / `OPTIONS` on the cross-check.** Mutating calls (`POST`, `PATCH`, `PUT`, `DELETE`) require explicit per-call user confirmation and must target a sandbox account.
 - **Credentials are never written to `.plain` files or summaries.** Reference them by env-var name only.
 
+## `:ConformanceTests:` always run against the live integration (hard rule)
+
+Integrations exist to talk to a real third-party (or internal) API. Their `:ConformanceTests:` therefore **always run against the live integration** — no VCR cassettes, no recorded fixtures, no `nock` / `WireMock` / `MSW` mocks for the calls under test. A "green" conformance run that never touched the provider proves nothing about the integration.
+
+- The integration's `:ConformanceTests:` **must** make real network calls to the provider (typically a sandbox / staging environment, occasionally production for read-only paths). Fixtures under `resources/fixtures/` exist for unit tests and for grounding the schemas in the OpenAPI file — they are **not** a substitute for live conformance
+- The only exceptions are paths that **cannot** be exercised live safely:
+  - **Rate-limit (429) tests** — must not exhaust the live quota; use a local mock for that specific endpoint
+  - **Deliberately destructive failure modes** (forced 5xx) the provider doesn't let you trigger — same; mock the specific endpoint
+  Document each exception explicitly in `***test reqs***`; everything else is live by default
+
+### Secrets come from the environment
+
+Live conformance needs credentials. The integration spec must pin every credential as **an env var name, never a literal value**, and the conformance script must read those env vars at runtime:
+
+- **Author the env-var names in `***test reqs***`** (using `:ConformanceTests:`) and again in the auth concept. Examples: `STRIPE_API_KEY`, `GITHUB_TOKEN`, `SALESFORCE_CLIENT_ID` + `SALESFORCE_CLIENT_SECRET`. Use names that match what the provider's own docs use, so a user copying values from the provider console doesn't need to translate
+- **The user supplies the values out-of-band**, either:
+  - in a `.env` file at the project root (`.env` is gitignored; the project ships `.env.example` with the names but no values), or
+  - exported in the shell that invokes the test scripts (CI uses the same names from its secret store)
+- **`run_conformance_tests_<lang>` reads the env vars at runtime.** If a required var is missing, the script must fail fast with `Error: <NAME> is required for :ConformanceTests:` and exit `69` (per the testing-script exit-code conventions). Never default to a placeholder, never use a value baked into the script
+- **The script may optionally load a `.env` file** before running the suite — typical pattern is to look for `.env` in the project root and `source` / `dotenv -e` it if present, but never fail when it's absent (since CI provides the vars directly via the shell). If a `.env` loader is used, the script must verify each required var is set **after** loading, not before
+- **The conformance suite reads the same env-var names** the integration's runtime reads — so a credential that works at runtime is the same credential that exercises the suite
+- **Credentials never appear in `.plain` files, commits, summaries, logs, or fixtures.** The cross-check (see *Live API must be cross-checked*) already requires redacting credentials from saved fixtures; the same rule applies to conformance logs
+
+The `.plain` spec should make this discoverable. A minimal `***test reqs***` block for an integration looks like:
+
+```plain
+- :ConformanceTests: run against the live :ProviderName: sandbox — no mocking of provider calls.
+  - Credentials are read from the environment, never from a file checked into the repo.
+  - The conformance script reads `<PROVIDER>_API_KEY` (and any additional secrets) from the shell or from a `.env` file at the project root.
+  - The script must verify every required env var is set after the optional `.env` load and fail fast with a clear error if any is missing.
+  - The 429 (rate-limit) and forced-5xx paths use a local mock for that specific endpoint; every other path is live.
+```
+
 ## Embedded vs standalone — pick the shape early
 
 Every integration is either **embedded** (lives as a library/module inside an existing host codebase) or **standalone** (a service, daemon, CLI, scheduled job, or container). The choice is captured as a concept (`integration-shape: embedded | standalone`) so later specs can reference it.

package/forge/rules/test-reqs.md

@@ -13,6 +13,12 @@ When writing or editing a `***test reqs***` section in a `.plain` file, always f
 - Acceptance tests are nested under individual functional specs, not here
 - Behavioral requirements go in `***functional specs***`, not here
 
+## `:ConformanceTests:` lives here (hard rule)
+- **Everything** about `:ConformanceTests:` goes in `***test reqs***` — paths, approach, packages, framework, execution command, mocking / network policy, fixtures, pass criteria, environment prerequisites
+- `:ConformanceTests:` live outside the generated codebase (typically in a separate project under `conformance_tests/<module>/`), so requirements that shape them belong in test reqs by definition
+- The conformance-test generator reads **only** `***test reqs***` — anything about `:ConformanceTests:` placed elsewhere (e.g. `***implementation reqs***`) is silently ignored
+- Author each `:ConformanceTests:` requirement via `add-test-requirement` and phrase it in terms of `:ConformanceTests:` so the partition stays visible at a glance
+
 ## What belongs here
 - Test framework: which framework to use (e.g., pytest, Unittest, xUnit)
 - Execution method: the command to run the tests

package/forge/skills/add-implementation-requirement/SKILL.md

@@ -38,7 +38,15 @@ Implementation reqs are free-form instructions that steer code generation. Commo
 
 - **Behavior and features** — those go in `***functional specs***`
 - **Concept definitions** — those go in `***definitions***`
-- **Test instructions** — those go in `***test reqs***`
+- **Conformance-test instructions** — those go in `***test reqs***`. Note: **unit-test instructions belong HERE**, not in `***test reqs***` — see *Unit-test guidance belongs here* below
+
+## Unit-test guidance belongs here
+
+**Everything about `:UnitTests:` goes in `***implementation reqs***`** — paths, approach, packages, framework (JUnit / pytest / Jest / Go's `testing` / …), conventions, fixtures, mocking policy, file layout, naming, lint / static-analysis gates. Unit tests are part of the generated codebase, so requirements that shape them are implementation reqs by definition.
+
+- The unit-test generator reads **only** `***implementation reqs***`; anything about `:UnitTests:` placed in `***test reqs***` is silently ignored
+- Phrase each `:UnitTests:` requirement in terms of the predefined `:UnitTests:` concept so the partition stays visible at a glance
+- `***test reqs***` is exclusively for `:ConformanceTests:` — see [`add-test-requirement`](../add-test-requirement/SKILL.md)
 
 ## Key Principle: HOW vs WHAT
 

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

@@ -183,13 +183,19 @@ prepare-environment-script: test_scripts/prepare_environment_<language>.<sh|ps1>
 
 Use `.sh` on macOS/Linux and `.ps1` on Windows, matching what testing scripts. Preserve any existing fields in a `config.yaml` you are updating.
 
+**Hard partition reminder.** Throughout this phase:
+
+- **Everything about `:UnitTests:`** (framework, layout, packages, conventions, execution command, coverage, mocking policy — every fact) is authored into `***implementation reqs***` via `add-implementation-requirement`. The unit-test generator reads only that section
+- **Everything about `:ConformanceTests:`** (framework, layout, packages, execution command, mocking policy, environment prereqs — every fact) is authored into `***test reqs***` via `add-test-requirement`. The conformance-test generator reads only that section
+- A topic that mixes both kinds of facts is split: unit facts go to impl reqs, conformance facts go to test reqs. They never share a bullet
+
 Walk through these topics in order, running ask → author → review for each. Skip a topic only if it genuinely doesn't apply, and say so explicitly:
 
-1. **Testing framework** — e.g. pytest, Jest, JUnit, Go's `testing` package. If the user has no preference, suggest one that fits the language chosen in Phase 2.
-   - Author: a framework requirement in `***test reqs***` at the appropriate scope (template if shared, otherwise on the module). Generate `run_unittests` (and any framework config files it needs, e.g. `pytest.ini`, `jest.config.js`) via `implement-unit-testing-script`. Add the `unittests-script:` entry to the relevant `config.yaml`(s), creating each file if it doesn't exist yet.
+1. **Unit-test framework** — e.g. pytest, Jest, JUnit, Go's `testing` package. If the user has no preference, suggest one that fits the language chosen in Phase 2.
+   - Author: a `:UnitTests:` framework requirement in `***implementation reqs***` at the appropriate scope (template if shared, otherwise on the module) — e.g. "`:UnitTests:` should use pytest" plus "`:UnitTests:` are run via `pytest tests/`". Generate `run_unittests` (and any framework config files it needs, e.g. `pytest.ini`, `jest.config.js`) via `implement-unit-testing-script`. Add the `unittests-script:` entry to the relevant `config.yaml`(s), creating each file if it doesn't exist yet.
    - Review: the framework req, the generated script paths, and the new `config.yaml` entry.
-2. **Test types in scope** — unit tests and integration tests. Which combinations does the user want? How do tests map to the architectural layers established in Phase 2 (e.g. one test module per service, repository tests with an in-memory store, etc.)?
-   - Author: a test-types/scope requirement in `***test reqs***` describing which types are in scope and how they map to the architecture.
+2. **Unit-test types and architecture mapping** — unit tests and integration tests. Which combinations does the user want? How do tests map to the architectural layers established in Phase 2 (e.g. one test module per service, repository tests with an in-memory store, etc.)?
+   - Author: a `:UnitTests:` scope / architecture requirement in `***implementation reqs***` describing which types are in scope and how they map to the architecture — phrased in terms of `:UnitTests:` so the partition is visible.
    - Review: that requirement.
 3. **Conformance testing** — explicitly ask whether conformance/end-to-end tests should be part of the project. Conformance testing drives whether `run_conformance_tests` is generated and whether `***acceptance tests***` are authored. If the user is unsure, briefly explain the tradeoff (extra scripts + per-spec acceptance tests vs. lighter setup) and let them choose.
    - Author (if yes):
@@ -203,11 +209,11 @@ Walk through these topics in order, running ask → author → review for each.
    - Author (if yes): `prepare_environment` via `implement-prepare-environment-script`; add the `prepare-environment-script:` entry to the relevant `config.yaml`(s); if the script's responsibilities are non-trivial and worth pinning in the spec, also add a brief `***test reqs***` entry describing what `prepare_environment` is responsible for.
    - Author (if no): record the decision; skip the script and the config entry.
    - Review: the script (if any), the new config entry (if any), and the test req (if any).
-5. **Test layout & conventions** — directory layout for tests, naming conventions, fixtures/mocks strategy, anything that constrains the *shape* of test code beyond what topics 1 and 2 already established.
-   - Author: layout/convention requirements in `***test reqs***` at the appropriate scope.
+5. **Test layout & conventions** — directory layout, naming conventions, fixtures / mocks strategy, anything that constrains the *shape* of test code beyond what topics 1–4 already established. Ask about both kinds of tests where applicable; keep their facts in separate reqs in separate sections.
+   - Author: `:UnitTests:` layout / convention requirements in `***implementation reqs***`; `:ConformanceTests:` layout / convention requirements in `***test reqs***` (only when conformance is enabled). Phrase each one with the predefined concept it shapes so the partition is visible.
    - Review: each requirement snippet.
-6. **Execution & tooling** — how tests are run (commands, runners, options), coverage targets, CI integration, any environment setup tests rely on beyond `prepare_environment`. If the agreed execution command or options differ from what the script generated in topic 1 (or 3, or 4) currently uses, update the affected script(s) now.
-   - Author: execution requirements in `***test reqs***`; update any affected scripts under `test_scripts/`.
+6. **Execution & tooling** — how tests are run (commands, runners, options), coverage targets, CI integration, any environment setup tests rely on beyond `prepare_environment`. Split by concept the same way as topic 5. If the agreed execution command or options differ from what the script generated in topic 1 (or 3, or 4) currently uses, update the affected script(s) now.
+   - Author: `:UnitTests:` execution requirements in `***implementation reqs***`; `:ConformanceTests:` execution requirements in `***test reqs***`. Update any affected scripts under `test_scripts/`.
    - Review: each requirement snippet and any modified script.
 7. **Other testing constraints** — performance/load expectations, deterministic seeds, network isolation, secrets handling, anything stack-wide that constrains *how* tests are written and that hasn't already been covered.
    - Author: each constraint as its own requirement at the appropriate scope.

package/forge/skills/init-plain-project/SKILL.md

@@ -58,15 +58,17 @@ Use **AskUserQuestion** for one tight batch covering:
 
 Create the import module with `create-import-module`. It must contain:
 
-- `***implementation reqs***` — the base stack as requirements:
+- `***implementation reqs***` — the base stack as requirements **and everything about `:UnitTests:`**:
   - Programming language and version.
   - Primary framework (if any).
   - Dependency / package manager.
   - Project kind as a constraint (e.g. ":Implementation: should be a REST API service.").
+  - `:UnitTests:` framework (pytest / Jest / JUnit / Go's `testing` / …) and the command used to run them — phrased in terms of `:UnitTests:` so the partition is explicit.
   - Anything else the user added in the free-form catch-all.
-- `***test reqs***` — the base testing rules:
-  - Unit testing framework and the command used to run it.
-  - ":ConformanceTests: must be implemented and executed - do not skip tests." — only if conformance testing is enabled. Add framework + command for conformance tests too.
+- `***test reqs***` — the base **conformance**-testing rules (only added if conformance testing is enabled):
+  - ":ConformanceTests: must be implemented and executed - do not skip tests."
+  - The `:ConformanceTests:` framework and the command used to run them.
+  - **Do NOT** put unit-test framework / command here — that lives in `***implementation reqs***` above.
 
 Do **not** add a `***definitions***` section to `template/base.plain`. This skill does not author any concepts. Use only the predefined concepts (`:Implementation:`, `:ConformanceTests:`) in the reqs — no project-specific concepts like `:AppName:` or `:App:`. Do not declare `required_concepts` either.
 

package/forge/skills/load-plain-reference/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: load-plain-reference
 description: >-
-  Loads the full ***plain language reference into context: syntax, section types
+  Loads the full ***plain language reference into context (PLAIN_REFERENCE.md): syntax, section types
   (definitions, implementation reqs, test reqs, functional specs, acceptance tests),
   concept notation, frontmatter (import/requires/required_concepts/exported_concepts),
   templates, linked resources, module model, and authoring best practices. Use whenever

package/package.json

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