plain-forge 1.0.6 → 1.0.8

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/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

@@ -5,7 +5,7 @@ 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.).
+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)
 
@@ -24,46 +24,97 @@ This deliberately writes into the host's `src/main/...` and `src/test/...` (or t
 
 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***`
+## 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 `***implementation reqs***` so the renderer (and the `implement-*-testing-script` skills) can fill them into the three placeholders that every script body needs:
+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. **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`
+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 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:
+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 test package used for test discovery is `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 three facts feed directly into the script bodies:
+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/<integration test 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/<integration test 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/<integration test source path>/* $MAIN_PROJECT_FOLDER/<integration test 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)
 
-# run the unit tests scoped to the integration's package
-mvn test -Dtest='<test package>.**.*Test' checkstyle:check
+# parse Surefire summary against the declared pass criteria, then exit accordingly
 ```
 
-Rules that flow from this:
+### Rules common to both sections
 
-- **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 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 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
+- **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)
 
@@ -158,6 +209,37 @@ Required steps:
 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:

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
@@ -129,10 +131,11 @@ See [`integration-embedded-testing.md`](integration-embedded-testing.md) for the
 ### 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 copy destination is unambiguous
+- **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
-- **`***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
 
@@ -147,10 +150,11 @@ Before declaring an embedded integration done, in addition to the shared checkli
 - [ ] `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 inside the host where `$1` is copied is read from the `host-codebase` concept — never inferred
+- [ ] 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
-- [ ] 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
 

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

@@ -44,6 +44,11 @@ A single `.plain` module can (and typically will) reference many resources. That
 
 Documentation lies — it goes stale, omits undocumented fields, describes a different API version, papers over breaking changes. Every integration spec must be grounded in what the API really returns, not what the docs claim it returns.
 
+- **Always `fetch` the provider's documentation — even if you already "know" the API.** Training-data memory of any third-party REST API is, by definition, stale: endpoints get renamed, fields get added or deprecated, auth flows change, error envelopes shift, and rate-limit headers are renamed between releases. The only acceptable source of truth for what the API looks like *today* is the provider's own live documentation, retrieved with `fetch` at spec-authoring time. This applies without exception — there is no API well-known enough to skip this step, and a spec authored from memory is a spec authored against the wrong contract. Concretely:
+  - Before authoring **any** endpoint, auth, error, pagination, or webhook concept, `fetch` the relevant documentation page(s) and quote concrete details (status codes, field names, header names, error formats) directly from the fetched content into the resources under `resources/`. Never paraphrase from memory.
+  - Save the fetched documentation snapshot under `resources/docs/<provider>/<page>.md` (or `.html` if structure matters) so the spec has a stable doc artifact the renderer and reviewers can consult, independent of the live URL changing or going behind auth.
+  - If a documentation page is unreachable (paywall, login wall, JS-only render that `fetch` can't see), say so explicitly and ask the user for the canonical content rather than filling the gap from memory.
+  - **The fetched documentation is then cross-checked against the live API** — see the rest of this section. Memory is not part of the loop at any point.
 - **Validate credentials against the live API** before authoring downstream specs. A 2xx on a low-risk read-only endpoint (`/v1/me`, `/account`, `/whoami`, `/health`) is the gate. On 401/403, stop and resolve before continuing.
 - **Issue the minimum cross-check coverage** with `fetch`: one discovery / schema endpoint if available, one list endpoint per primary entity in scope, one single-object retrieval per primary entity, one empty/boundary response, one 404, one 400/422, and one deliberate 401.
 - **Save every probe response under `resources/fixtures/`** with credentials redacted. The fixtures become the seed for `resources/<provider>.openapi.yaml` and feed conformance tests later.
@@ -51,6 +56,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.
@@ -89,3 +127,4 @@ A production-ready integration spec captures every corner case the API can throw
 - **Authoring against unverified credentials.** Validate first; if the user has no credentials yet, flag it in the module's frontmatter description and re-validate once credentials arrive
 - **`requires`-ing a separate-stack module** (a Python backend `requires`-ing a React frontend, or vice versa) — see [`requires-modules.md`](requires-modules.md). Use a shared API schema in `resources/` instead
 - **Authoring Phase 1 specs from the docs first and "reconciling" with the live API later.** Probe the API as you reach each topic; the live response is the source of truth from the moment it's captured
+- **Writing any integration spec from memory of the provider's API instead of `fetch`-ing its documentation first.** No matter how well-known the API (Stripe, GitHub, Slack, Salesforce, AWS, OpenAI, …), the documentation must be retrieved with `fetch` at spec-authoring time and saved under `resources/docs/<provider>/` — see *Live API must be cross-checked against the documentation*. Authoring from memory bakes in whatever version of the API was current during training, which is always older than the version the integration will actually call

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.6",
+  "version": "1.0.8",
   "description": "Conversational spec-writing tool for ***plain specification language",
   "type": "module",
   "engines": {