plain-forge 1.0.4 → 1.0.6

package/README.md

@@ -4,18 +4,39 @@
 
 # plain-forge
 
-A conversational spec-writing tool that runs in any AI coding agent (Claude Code, Codex, OpenCode, and more) and is built on the [***plain](https://plainlang.org) specification language. Describe what you want to build in plain English, and plain-forge guides you through a structured interview to produce complete `.plain` spec files — which then generate production-ready code via the [Codeplain](https://codeplain.ai) renderer.
+A toolkit for working with [***plain](https://plainlang.org) projects from inside your AI coding agent of choice — Claude Code, Codex, ForgeCode, OpenCode, and any other agent that reads from a standard skills directory. plain-forge ships skills, rules, and docs that turn a conversation into complete `.plain` spec files, then keeps maintaining them across the lifetime of the project. The specs are rendered into production-ready code by the [codeplain](https://codeplain.ai) renderer.
 
-## How It Works
+## What plain-forge does
 
-The main entry point is `forge-plain`. It turns a conversation into ***plain specs through four phases:
+plain-forge is organized around four kinds of work, each with its own entry-point skill (and a long tail of supporting skills behind it).
 
-1. **What are we building?** — Walk through the product: description, users, scope, core entities, key features, user flows, business rules, and (if applicable) UI behavior. Produces the `***definitions***` and `***functional specs***` for each module.
-2. **What technologies should it use?** — Pick the stack and architecture: language, frameworks, data storage, external services, project structure, and any other stack-wide constraints. Produces the `***implementation reqs***`.
-3. **How should testing be done?** — Decide the testing strategy: framework, test types in scope, conformance/acceptance tests, environment-preparation scripts, layout, and execution. Produces the `***test reqs***`, any `***acceptance tests***`, the runnable scripts under `test_scripts/`, and the `config.yaml`(s) wiring them in. plain-forge then probes your machine to confirm everything those scripts need is actually installed.
-4. **Validate and hand off** — plain-forge identifies the final module in the dependency chain and runs `codeplain <module>.plain --dry-run` itself to catch any static errors (syntax, undefined concepts, broken `import`/`requires` chains, complexity violations, conflicts). It fixes the `.plain` files until the dry-run passes, then hands you the exact `codeplain <module>.plain` command (plus any test scripts) so the real render starts from a clean spec.
+### 1. Bootstrap a new project
 
-Each phase is **incremental**, not a single long questionnaire. plain-forge walks one topic at a time, runs an **ask → author → review** loop on every topic — structured questions, immediate edits to the `.plain` files (and `test_scripts/` / `config.yaml` in Phase 3), then snippet-by-snippet confirmation — and only moves on once every flagged snippet is explicitly approved.
+Pick whichever entry point matches how much upfront design you want:
+
+- **`forge-plain`** — full end-to-end interview. One question at a time, immediate writes to disk, covers product → tech stack → testing → validation in four phases. Produces a complete `.plain` project with `config.yaml`, test scripts, and a successful `codeplain --dry-run` before handing off.
+- **`init-plain-project`** — lightweight scaffold. Asks only about the base technology, project kind, and whether conformance testing is on; emits a template module, a stub top-level module, the testing scripts, and a `config.yaml`. No interview, no specs — pair it with `add-feature` to grow the project feature by feature.
+
+### 2. Grow an existing project
+
+- **`add-feature`** — takes a feature request in plain English and runs the same one-question-at-a-time loop that `forge-plain` uses, scoped to a single feature against an existing `.plain` file.
+- **Per-section authoring skills** — `add-functional-spec`, `add-functional-specs`, `add-implementation-requirement`, `add-test-requirement`, `add-concept`, `add-acceptance-test`, `add-resource`, `add-template`. Each enforces the relevant ***plain syntax rules (concept uniqueness, complexity limits, line-length, linked-resource constraints, …) so hand-authoring doesn't drift from the language.
+- **Module-management skills** — `create-import-module`, `create-requires-module`, `refactor-module`, `consolidate-concepts` for restructuring as the project grows.
+
+### 3. Validate and maintain
+
+- **`plain-healthcheck`** — the verification gate. Inventories every `.plain` module, validates every `config.yaml`, and dry-runs every top module with the right config. Returns `PASS` / `FAIL` with a numbered punch-list when something is broken.
+- **`init-config-file`** — assembles the canonical `config.yaml` per part of a project from the decisions made during interviewing.
+- **`check-plain-env`** — probes the host machine for everything the project needs (language toolchains, external services, system binaries, drivers, `codeplain` itself) and emits a `PASS` / `WARN` / `FAIL` report with OS-specific install commands.
+- **`analyze-func-specs`** / **`analyze-if-func-spec-too-complex`** / **`break-down-func-spec`** / **`resolve-spec-conflict`** — the spec-quality toolchain that runs behind `add-feature` and `forge-plain` but can also be invoked directly when reviewing or refactoring.
+
+### 4. Debug and render
+
+- **`debug-specs`** — when the rendered app misbehaves, this traces the generated code back to the spec that caused it and fixes the spec (never the generated code).
+- **`run-codeplain`** — experimental supervised render. Launches `codeplain` for you, tails the log, watches generated code appear under `plain_modules/`, and detects pathologies (stuck conformance loops, complexity errors, missing concepts, render failures). On approval it stops the renderer, hands off to the right spec-edit skill, and resumes.
+- **`implement-unit-testing-script`** / **`implement-conformance-testing-script`** / **`implement-prepare-environment-script`** — generate the per-language testing scripts that the renderer and you both invoke. New languages can be added by these skills without touching any other part of the project.
+
+Each skill operates on the same one-question-at-a-time, write-immediately, refine-through-follow-ups loop. Specs land on disk after every answer; later answers fix earlier writes in place. There is no batched interview, no "I'll gather context first," and no hand-authored functional specs — every new spec goes through the authoring skills so the complexity and conflict checks actually run.
 
 ## Getting Started
 

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/integration-embedded-testing.md

@@ -0,0 +1,203 @@
+---
+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](../docs/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 in `***implementation reqs***`
+
+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 `***implementation reqs***` so the renderer (and the `implement-*-testing-script` skills) can fill them into the three placeholders that every script body needs:
+
+1. **Integration source path inside the host** — where `$1/<source>/*` gets copied to. Example: `src/main/java/com/example/integrations/foo`
+2. **Integration test source path inside the host** — where `$1/<tests>/*` gets copied to, and where `:UnitTests:` are discovered. Example: `src/test/java/com/example/integrations/foo`
+3. **Test package for the test-filter argument** — the fully qualified package the test runner uses to scope discovery. Example: `com.example.integrations.foo`
+
+Author one `***implementation reqs***` entry per fact (use the `add-implementation-requirement` skill). Phrase each one in terms of `:UnitTests:` (the predefined concept) and the integration's other concepts, not as raw paths floating in the spec — that keeps the reqs reviewable and the renderer can resolve them when emitting scripts:
+
+```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 test package used for test discovery is `com.example.integrations.foo`.
+```
+
+These three facts feed directly into the script bodies:
+
+```bash
+# clean existing code from the host
+rm -rf $MAIN_PROJECT_FOLDER/<integration source path>/*
+rm -rf $MAIN_PROJECT_FOLDER/<integration test source path>/*
+
+# create destinations and copy generated code into the host
+mkdir -p $MAIN_PROJECT_FOLDER/<integration source path>
+mkdir -p $MAIN_PROJECT_FOLDER/<integration test source path>
+cp -R $1/<integration source path>/* $MAIN_PROJECT_FOLDER/<integration source path>
+cp -R $1/<integration test source path>/* $MAIN_PROJECT_FOLDER/<integration test source path>
+
+# run the unit tests scoped to the integration's package
+mvn test -Dtest='<test package>.**.*Test' checkstyle:check
+```
+
+Rules that flow from this:
+
+- **The three paths must agree.** The source path, the test-source path, and the test package describe the same module from three angles. 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` (per 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 test paths, the renderer can't tell which to use. Author the three reqs as a tight group (the example above is one bullet with two sub-bullets) so a future reviewer sees them together
+- **For non-Java languages**, the three 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 so the skill knows where to copy
+
+## 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`
+
+### 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

@@ -16,6 +16,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.
@@ -38,12 +61,27 @@ Run host discovery **before** the first Phase 1 question. Treat the results as g
 - The renderer is allowed to redefine **only** symbols the host does not provide and the contract schema does not capture
 - Naming the symbol by FQN is not optional decoration — it tells the renderer where the type comes from, which prevents a duplicate definition under `plain_modules/`
 
-## Add host files as linked resources, never restate them
+## Link host files at their original path — never copy them into `resources/`
+
+The integration's `.plain` module lives **inside the host codebase** (per the "adopt the host's `.plain` setup verbatim" step). That means host source files are already reachable as linked resources via their host-relative paths. The integration spec references them **in place**; it never duplicates them under `resources/host/`.
 
-- Every host file the integration touches (base classes, configuration modules, registries, exception classes, lifecycle hooks) is added under `resources/host/` via the `add-resource` skill and referenced from the relevant spec using `***linked resource***` syntax
+- Every host file the integration touches (base classes, configuration modules, registries, exception classes, lifecycle hooks) is referenced from the relevant spec using `***linked resource***` syntax with the **path as it exists in the host codebase** — e.g. `[base.py](host_project/integrations/base.py)` if the `.plain` module sits next to `host_project/`
+- **Do NOT copy host files into `resources/host/`.** A copy creates a second source of truth that drifts the moment the host file is edited; the rendered code will then disagree with whatever the host actually ships
+- **Do NOT add host files via the `add-resource` skill's default copy behavior** when that behavior would duplicate the file — point at the existing host path directly
 - **Never inline a host file's contents** into a spec
-- **Never describe a host symbol's shape from memory** — the renderer reads the linked file's bytes and that is the source of truth
-- This obeys the broader [`linked-resources.md`](linked-resources.md) rules — a directory is not a valid link, a URL is not a valid link, a binary is not a valid link
+- **Never describe a host symbol's shape from memory** — the renderer reads the linked file's bytes at its host path and that is the source of truth
+- This still obeys the broader [`linked-resources.md`](linked-resources.md) rules: a directory is not a valid link, a URL is not a valid link, a binary is not a valid link. Only the *location* changes — host files live where the host put them, not under `resources/`
+
+### What still belongs under `resources/`
+
+This rule applies to **host source code only**. Other artifacts still live under `resources/` exactly like in a non-embedded project:
+
+- **Contract schemas authored by the integration** — `resources/contract/<entry-point>.schema.json`
+- **Configuration schema** — `resources/config.schema.json`
+- **Captured probe responses** (from the live-API cross-check) — `resources/fixtures/<endpoint>.<case>.json`
+- **Static lookup tables** the integration owns — `resources/error-map.yaml`, `resources/retry-policy.yaml`, etc.
+
+The rule of thumb: if the host wrote it and ships it, link it where the host put it. If the integration is authoring it for the first time, it goes under `resources/`.
 
 ## The contract spec declares inheritance, not duplication
 
@@ -76,47 +114,25 @@ 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
+- **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 copy destination is unambiguous
+- **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
+- **`***test reqs***` must document the script contract** — name the env var the host root is read from, the target package path inside the host where `$1` is copied, and the language-appropriate install + test commands. The renderer reads this req and emits the right script bodies
 
 ## Embedded-specific completion checklist
 
@@ -125,25 +141,26 @@ Before declaring an embedded integration done, in addition to the shared checkli
 - [ ] `host-codebase` concept records host root path, host language + version, host dependency manager + manifest, target package path, host base class import path, target generated-class FQN, and the host conventions the contract follows
 - [ ] Contract spec carries renderer directives (target language, target file path, target class name, host base class to subclass, host-package pins) and **links** to the contract schema; no class body is inlined
 - [ ] Every host symbol referenced in any spec uses its fully qualified import path and is tagged "imported from the host codebase; do not redefine"
-- [ ] Every host file the integration touches has been added under `resources/host/` as a linked resource — no host file contents are inlined in any spec
+- [ ] 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
+- [ ] `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
-- [ ] 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)
+- [ ] Target package path inside the host where `$1` is copied is read from the `host-codebase` concept — never inferred
+- [ ] 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
+- [ ] A `***test reqs***` entry documents the script contract (env var name, target package path inside the host, install + test commands)
 
 ## Anti-patterns specific to embedded integrations
 
 - **Choosing a different language, framework, or dependency manager than the host.** The host stack is inherited; cross-stack `requires` chains are forbidden by [`requires-modules.md`](requires-modules.md)
 - **Redefining a host class under `plain_modules/`.** Reference the host symbol by FQN; let the renderer import it
-- **Inlining a host base class body into the contract spec.** Add the host file as a linked resource under `resources/host/` and reference it
+- **Inlining a host base class body into the contract spec.** Reference the host file as a linked resource **at its original host-relative path** — do not inline its contents and do not copy it into `resources/`
+- **Copying host source files into `resources/host/` (or anywhere under `resources/`).** That creates a second source of truth that silently drifts from the host. Link the host file in place; the integration `.plain` module already lives inside the host codebase, so the path resolves naturally
 - **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/skills/add-acceptance-test/SKILL.md

@@ -44,6 +44,30 @@ Key formatting rules:
 - Each test bullet is indented under the `***acceptance tests***` header.
 - Multiple acceptance tests can be listed under a single functional spec.
 
+### Line syntax (hard rule)
+
+**Every line inside `***acceptance tests***` must be its own list item starting with `- `.** ***plain has no concept of bare continuation lines — indented prose without a leading `- ` is **invalid syntax** and the renderer will reject it.
+
+- Hard limit: 120 characters per line. If a sentence is too long, **split it at a natural clause boundary into nested `- ` bullets** — never wrap onto an unprefixed line.
+- Nested clarifications are also `- ` items, indented under the parent. The indentation alone is not enough; the leading `- ` is required.
+
+BAD — bare continuation lines (invalid ***plain syntax, will not render):
+
+```plain
+  ***acceptance tests***
+  - Processing 250 :Task: items should result in 3 batches with the
+    last batch containing the remaining 50 items.
+```
+
+GOOD — every line starts with `- `:
+
+```plain
+  ***acceptance tests***
+  - Processing 250 :Task: items should result in 3 batches.
+    - The first two batches each contain 100 items.
+    - The last batch contains the remaining 50 items.
+```
+
 ## Rules
 
 ### Conformance with the Functional Spec

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

@@ -56,6 +56,29 @@ Attributes and constraints are nested sub-bullets:
   - Due Date - completion deadline (optional)
 ```
 
+## Line syntax (hard rule)
+
+**Every line inside `***definitions***` must be its own list item starting with `- `.** ***plain has no concept of bare continuation lines — indented prose without a leading `- ` is **invalid syntax** and the renderer will reject it.
+
+- Hard limit: 120 characters per line. If a sentence is too long, **split it at a natural clause boundary into nested `- ` bullets** — never wrap onto an unprefixed line.
+- Nested attributes are also `- ` items, indented under the parent. The indentation alone is not enough; the leading `- ` is required.
+
+BAD — bare continuation lines (invalid ***plain syntax, will not render):
+
+```plain
+- :Task: describes an activity that needs to be done by :User:.
+  - Name is a short description that the user provides when creating
+    the task and is shown in the task list.
+```
+
+GOOD — every line starts with `- `:
+
+```plain
+- :Task: describes an activity that needs to be done by :User:.
+  - Name is a short description provided when creating the task.
+  - The name is shown in the task list.
+```
+
 ## Validation Checklist
 
 - [ ] Name uses `:CamelCase:` notation

package/forge/skills/add-functional-spec/SKILL.md

@@ -57,6 +57,29 @@ Each functional spec must be unambiguous — the renderer should have only one r
   - All :Participant: members of the :Conversation: can see the new :Message:.
 ```
 
+### Line syntax (hard rule)
+
+**Every line inside `***functional specs***` must be its own list item starting with `- `.** ***plain has no concept of bare continuation lines — indented prose without a leading `- ` is **invalid syntax** and the renderer will reject it.
+
+- Hard limit: 120 characters per line. If a sentence is too long, **split it at a natural clause boundary into nested `- ` bullets** — never wrap onto an unprefixed line.
+- Nested clarifications are also `- ` items, indented under the parent. The indentation alone is not enough; the leading `- ` is required.
+
+BAD — bare continuation lines (invalid ***plain syntax, will not render):
+
+```plain
+- :GatewayWebhook: should hand off :StripeRequest: to :StripeIntegration:.handle(),
+  which returns a list of :EventEnvelope: dicts conforming to the gateway's
+  contract.
+```
+
+GOOD — every line starts with `- `:
+
+```plain
+- :GatewayWebhook: should hand off :StripeRequest: to :StripeIntegration:.handle().
+  - The method returns a list of :EventEnvelope: dicts.
+  - The dicts must conform to the gateway's :EventEnvelope: contract.
+```
+
 ### Deterministic Interface
 
 Specs must be detailed enough that a developer can use the built software without reading the generated code. All external interfaces must be explicit — REST endpoint paths and HTTP methods, CLI command names and arguments, file formats, message schemas, etc. Never leave interface details up to the renderer's discretion.

package/forge/skills/add-functional-specs/SKILL.md

@@ -80,6 +80,30 @@ Each functional spec must be unambiguous — the renderer should have only one r
   - All :Participant: members of the :Conversation: can see the new :Message:.
 ```
 
+### Line syntax (hard rule, per spec)
+
+**Every line inside `***functional specs***` must be its own list item starting with `- `.** ***plain has no concept of bare continuation lines — indented prose without a leading `- ` is **invalid syntax** and the renderer will reject the whole file.
+
+- Hard limit: 120 characters per line. If a sentence is too long, **split it at a natural clause boundary into nested `- ` bullets** — never wrap onto an unprefixed line.
+- Nested clarifications are also `- ` items, indented under the parent. The indentation alone is not enough; the leading `- ` is required.
+- This rule applies to **every** spec in the batch — one bad continuation line invalidates the entire insert.
+
+BAD — bare continuation lines (invalid ***plain syntax, will not render):
+
+```plain
+- :GatewayWebhook: should hand off :StripeRequest: to :StripeIntegration:.handle(),
+  which returns a list of :EventEnvelope: dicts conforming to the gateway's
+  contract.
+```
+
+GOOD — every line starts with `- `:
+
+```plain
+- :GatewayWebhook: should hand off :StripeRequest: to :StripeIntegration:.handle().
+  - The method returns a list of :EventEnvelope: dicts.
+  - The dicts must conform to the gateway's :EventEnvelope: contract.
+```
+
 ### Deterministic Interface
 
 Specs must be detailed enough that a developer can use the built software without reading the generated code. All external interfaces must be explicit — REST endpoint paths and HTTP methods, CLI command names and arguments, file formats, message schemas, etc. Never leave interface details up to the renderer's discretion.

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

@@ -60,6 +60,30 @@ Implementation reqs are bullet points in the `***implementation reqs***` section
 
 Reference defined `:Concepts:` where they add clarity. Implementation reqs in non-leaf sections apply to all subsections.
 
+## Line syntax (hard rule)
+
+**Every line inside a section must be its own list item starting with `- `.** ***plain has no concept of bare continuation lines — indented prose without a leading `- ` is **invalid syntax** and the renderer will reject it.
+
+- Hard limit: 120 characters per line. If a sentence is too long, **split it at a natural clause boundary into nested `- ` bullets** — never wrap onto an unprefixed line.
+- Nested detail is also a `- ` item, indented under its parent. The indentation alone is not enough; the leading `- ` is required.
+
+BAD — bare continuation lines (invalid ***plain syntax, will not render):
+
+```plain
+- :Implementation: tech stack will be finalized in Phase 2.
+  - Until then, treat this section as a placeholder so the renderer accepts
+    the file. Phase 2 will replace this with language, framework, HTTP
+    client, packaging, and architecture decisions.
+```
+
+GOOD — every line starts with `- `:
+
+```plain
+- :Implementation: tech stack will be finalized in Phase 2.
+  - Until then, treat this section as a placeholder so the renderer accepts the file.
+  - Phase 2 will replace it with language, framework, HTTP client, packaging, and architecture decisions.
+```
+
 ## Encapsulation Warning
 
 `requires` modules only receive functional specs from their dependencies — not implementation reqs. If downstream modules need certain behavior to be visible, that behavior must be expressed in functional specs, not here.

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

@@ -59,6 +59,28 @@ Test reqs are bullet points in the `***test reqs***` section:
 
 Reference predefined concepts like `:ConformanceTests:` and any defined `:Concepts:` where they add clarity.
 
+## Line syntax (hard rule)
+
+**Every line inside `***test reqs***` must be its own list item starting with `- `.** ***plain has no concept of bare continuation lines — indented prose without a leading `- ` is **invalid syntax** and the renderer will reject it.
+
+- Hard limit: 120 characters per line. If a sentence is too long, **split it at a natural clause boundary into nested `- ` bullets** — never wrap onto an unprefixed line.
+- Nested clarifications are also `- ` items, indented under the parent. The indentation alone is not enough; the leading `- ` is required.
+
+BAD — bare continuation lines (invalid ***plain syntax, will not render):
+
+```plain
+- :ConformanceTests: must mock all external HTTP calls so that the
+  test suite remains hermetic and does not depend on network access.
+```
+
+GOOD — every line starts with `- `:
+
+```plain
+- :ConformanceTests: must mock all external HTTP calls.
+  - The test suite must remain hermetic.
+  - Tests must not depend on network access.
+```
+
 ## Validation Checklist
 
 - [ ] Describes conformance testing concerns, not unit tests or behavior

package/package.json

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