plain-forge 1.0.19 → 1.0.21-next.4f1def5

package/forge/rules/concise-specs-integration-examples.md

@@ -0,0 +1,272 @@
+---
+description: Worked BAD to GOOD examples of concise integration specs, where over-precision and obvious edge cases dominate
+---
+
+# Worked examples of concise integration specs
+
+`concise-specs.md` is the rule and `concise-specs-examples.md` is the general example bank. This file covers integration specs only, because they fail differently.
+
+An integration is technically demanding, the provider's contract is large, and the author has the provider's documentation open while writing. The result is a spec that is *too precise*: status codes, field lists, retry arithmetic, and every edge case the API can produce, written out as prose bullets. It reads as rigorous and is unreviewable.
+
+Conciseness here is almost never about covering less. `integrations.md` makes edge-case coverage a hard floor — auth, environments, versioning, pagination, rate limits, the error model, retries, idempotency, webhooks, data mapping, compliance, observability. Every one of those must be covered. The lever is **where** the coverage lives:
+
+- **Shapes and enumerations go to `resources/`** — schemas, error maps, retry policy, rate-limit headers. A spec bullet links to the file; it never restates its contents.
+- **The spec keeps behavior** — what the integration does with the shape, and what a caller observes.
+- **Mechanism goes to `***implementation reqs***`** — retry logic, exception hierarchies, token caching, connection handling. Integration precision is mostly HOW, and `impl-reqs.md` owns HOW. `***functional specs***` keeps only what a caller can observe.
+
+That last lever is easy to miss, so several examples below move a bullet between sections rather than shortening it. A fact in the wrong section is worse than a verbose one: the renderer reads each concept only from its owning section, so a misplaced fact is silently ignored.
+
+Applied consistently, a spec gets shorter as coverage goes *up*, because each new corner case adds a line to a resource file rather than a paragraph to the spec.
+
+The BAD blocks intentionally demonstrate the mistakes they name, including invalid syntax. Copy only from GOOD blocks.
+
+## Status codes and error categories enumerated inline
+
+BAD:
+
+```plain
+***definitions***
+
+- :ProviderApi: is the REST surface of the provider, defined by [resources/provider.openapi.yaml](resources/provider.openapi.yaml).
+
+***functional specs***
+
+- :ProviderClient: retries the request when :ProviderApi: returns 408, 425, 429, 500, 502, 503, or 504, and also on connection errors, DNS failures, socket timeouts, TLS handshake failures, and connection resets.
+
+- :ProviderClient: does not retry on 400, 401, 403, 404, 405, 409, 410, 415, or 422, and raises immediately.
+
+- On 429, :ProviderClient: waits and tries again, unless the retry budget is exhausted.
+```
+
+GOOD:
+
+```plain
+***definitions***
+
+- :ProviderApi: is the REST surface of the provider, defined by [resources/provider.openapi.yaml](resources/provider.openapi.yaml).
+
+***implementation reqs***
+
+- :ProviderClient: classifies every failure of :ProviderApi: through [resources/error-map.yaml](resources/error-map.yaml) and retries the transient ones under [resources/retry-policy.yaml](resources/retry-policy.yaml).
+```
+
+The status-code lists move into `error-map.yaml`, which the renderer already reads to generate the exception hierarchy and the transient predicate. Coverage is unchanged and the classification now has one source of truth instead of two that can disagree — see *Transient vs. permanent exception classification* in `integrations.md`.
+
+Note the section too. Classifying and retrying is mechanism, so it is an implementation req; what belongs in `***functional specs***` is only the part a caller observes — which exception each error category surfaces as.
+
+## Restating a schema the resource already carries
+
+BAD:
+
+```plain
+***definitions***
+
+- :ProviderApi: is the REST surface of the provider, defined by [resources/provider.openapi.yaml](resources/provider.openapi.yaml).
+
+- :Customer: is a customer record returned by :ProviderApi:. It has an `id` (string), an `email` (string), a `created_at` (ISO 8601 timestamp), a `status` (one of `active`, `pending`, `churned`), an optional `phone` (string or null), and a `metadata` object of string keys to string values.
+```
+
+GOOD:
+
+```plain
+***definitions***
+
+- :ProviderApi: is the REST surface of the provider, defined by [resources/provider.openapi.yaml](resources/provider.openapi.yaml).
+
+- :Customer: is a :ProviderApi: record, defined by [resources/provider.openapi.yaml](resources/provider.openapi.yaml) under `components.schemas.Customer`.
+```
+
+Field lists rot the moment the provider adds a field, and the renderer generates types from the schema, not from the sentence. Keep in the definition only what the schema cannot say — a stability or uniqueness guarantee, a unit, a lifecycle rule.
+
+## Specifying the provider instead of the integration
+
+BAD:
+
+```plain
+***definitions***
+
+- :ProviderApi: is the REST surface of the provider, defined by [resources/provider.openapi.yaml](resources/provider.openapi.yaml).
+
+- :Customer: is a :ProviderApi: record, at `components.schemas.Customer`.
+
+***functional specs***
+
+- :ProviderApi: returns `200` with a JSON body when a request succeeds.
+
+- :ProviderApi: returns `404` when the requested :Customer: does not exist.
+
+- :ProviderApi: rate-limits clients and includes the remaining quota in the response headers.
+
+- :ProviderApi: requires the `Authorization` header on every request.
+```
+
+GOOD:
+
+```plain
+***definitions***
+
+- :ProviderApi: is the REST surface of the provider, defined by [resources/provider.openapi.yaml](resources/provider.openapi.yaml).
+
+- :ProviderClient: is the component every call to :ProviderApi: goes through.
+
+- :Customer: is a :ProviderApi: record, at `components.schemas.Customer`.
+
+- :CustomerId: identifies a :Customer: and is stable across updates.
+
+- :CustomerNotFoundError: is raised when :ProviderApi: has no :Customer: for a :CustomerId:.
+
+***implementation reqs***
+
+- :ProviderClient: authenticates to :ProviderApi: with the credential in the environment variable `PROVIDER_API_KEY`.
+
+- :ProviderClient: raises :CustomerNotFoundError: when :ProviderApi: has no :Customer: for the requested :CustomerId:.
+
+***functional specs***
+
+- :ProviderClient: fetches a :Customer: from :ProviderApi: by :CustomerId:.
+```
+
+Every BAD bullet is true, and none of them is deleted — they are moved. The success shape, the `404`, and the `Authorization` requirement are what an OpenAPI file exists to state; the rate-limit model has its own conventional files. Provider behavior with no machine-readable home goes in `resources/<provider>-notes.md`. `integrations.md` carries the full artifact table.
+
+What stays in the sections is only what gets built. A bullet stating provider behavior renders into nothing — the renderer cannot build the provider, and no conformance test can assert a sentence that makes no claim about the integration. State instead what the integration does when the provider behaves that way.
+
+Note where the links hang: both artifacts attach to the :ProviderApi: concept, and everything else references the token. `linked-resources.md` requires each resource to be linked from exactly one place, so a second spec needing the contract cannot introduce a second, divergent reference to it.
+
+## One operation fragmented into several specs
+
+Integration work invites this: the author walks through the request lifecycle — credential check, discovery call, request shape, paging — and each step becomes its own spec.
+
+BAD — four specs, one operation:
+
+```plain
+***definitions***
+
+- :ProviderApi: is the REST surface of the provider, defined by [resources/provider.openapi.yaml](resources/provider.openapi.yaml).
+
+- :Record: is an account record of :ProviderApi:.
+
+***functional specs***
+
+- A call to `fetch` fails before any request to :ProviderApi: is sent when `PROVIDER_API_KEY` is unset or empty.
+  - The failure names `PROVIDER_API_KEY`.
+
+- A call to `fetch` reads the field catalogue from :ProviderApi: once, before requesting any :Record:.
+  - The catalogue yields the name of every field the account defines.
+  - A call to `fetch` whose catalogue read fails requests no :Record: items.
+
+- A request for :Record: items from :ProviderApi: names every field in the catalogue and asks for at most 100 records.
+  - Archived :Record: items are not requested.
+
+- A call to `fetch` requests pages until :ProviderApi: returns a response carrying no next-page cursor.
+  - Each page after the first is requested with the cursor from the previous response.
+  - The :Record: items of every page are carried forward together.
+```
+
+GOOD — one spec, with the result stated first:
+
+```plain
+***definitions***
+
+- :ProviderApi: is the REST surface of the provider, defined by [resources/provider.openapi.yaml](resources/provider.openapi.yaml).
+
+- :Record: is an account record of :ProviderApi:.
+
+- :RecordSource: is the component through which the integration reads :Record: items from :ProviderApi:.
+
+***functional specs***
+
+- :RecordSource: `fetch()` returns every non-archived :Record: with every field :ProviderApi: defines, paging under [resources/pagination.yaml](resources/pagination.yaml).
+  - :RecordSource: reads the field catalogue once per `fetch()`.
+  - `fetch()` fails before any request when `PROVIDER_API_KEY` is unset or empty, naming it.
+  - A failed catalogue read fails `fetch()` before any :Record: is requested.
+```
+
+Merging is not in tension with the complexity limit. Split a spec when it implies more than 200 changed lines of code (`analyze-if-func-spec-too-complex`, then `break-down-func-spec`); merge when several specs implement one operation that fits inside that budget. Fragment count is not a measure of size.
+
+## The auth flow narrated step by step
+
+BAD:
+
+```plain
+***functional specs***
+
+- :ProviderAuth: first reads the client id and the client secret, then builds a form-encoded body containing `grant_type=client_credentials`, the client id, and the client secret, then posts that body to the token endpoint, then parses the JSON response, then extracts the `access_token` and the `expires_in` fields, then stores the token in memory together with the moment it expires, and then attaches it to subsequent requests as a bearer token.
+
+- Before each request, :ProviderAuth: compares the current time to the stored expiry and, if the token has expired or is about to expire, repeats the whole procedure described above to obtain a new token.
+```
+
+GOOD:
+
+```plain
+***definitions***
+
+- :ProviderApi: is the REST surface of the provider, defined by [resources/provider.openapi.yaml](resources/provider.openapi.yaml).
+
+- :ProviderClient: is the component every call to :ProviderApi: goes through.
+
+- :AccessToken: is the bearer credential :ProviderApi: accepts.
+
+- :AuthTokenManager: manages the lifecycle of all :AccessToken:
+
+***implementation reqs***
+
+- :ProviderAuth: obtains an :AccessToken: by the grant in [resources/provider.openapi.yaml](resources/provider.openapi.yaml) under `components.securitySchemes.oauth2`.
+
+- :ProviderAuth: reads `PROVIDER_CLIENT_ID` and `PROVIDER_CLIENT_SECRET` from the environment.
+
+- :AuthTokenManager: refreshes an :AccessToken: 60 seconds before it expires, and once on a `401` from :ProviderApi:.
+
+- Concurrent requests finding the :AccessToken: expired cause one refresh.
+
+- :ProviderClient: uses :AuthTokenManager: to cache and refresh :AccessToken:.
+```
+
+The grant type, endpoint, body encoding, and response fields are in the security scheme. What
+survives is the policy the scheme does not describe: the env-var names, the refresh margin, the
+retry-once-on-401 rule, and the concurrency behavior.
+
+Almost all of it is implementation reqs — acquisition, caching, and refresh are machinery a caller never sees. Not all of it, though, and the rewrite has to name a component to say the rest. :ProviderAuth: performs the grant and has no observable surface; :AuthTokenManager: is what consumes it and hands tokens to :ProviderClient:, so it is the concept a functional spec can take as its subject. Without that consumer the section is left with a subject-less bullet, which `func-specs.md` rules out — and that one spec is the only line here a live conformance test can assert.
+
+## Per-endpoint test reqs
+
+BAD:
+
+```plain
+***definitions***
+
+- :ProviderApi: is the REST surface of the provider, defined by [resources/provider.openapi.yaml](resources/provider.openapi.yaml).
+
+***test reqs***
+
+- :ConformanceTests: for the customer list endpoint run against the live :ProviderApi: sandbox.
+
+- :ConformanceTests: for the customer retrieval endpoint run against the live :ProviderApi: sandbox.
+
+- :ConformanceTests: for the invoice list endpoint run against the live :ProviderApi: sandbox.
+
+- :ConformanceTests: for the webhook endpoint run against the live :ProviderApi: sandbox.
+
+- :ConformanceTests: for the customer list endpoint use the credentials from the environment.
+
+- :ConformanceTests: for the invoice list endpoint use the credentials from the environment.
+```
+
+GOOD:
+
+```plain
+***definitions***
+
+- :ProviderApi: is the REST surface of the provider, defined by [resources/provider.openapi.yaml](resources/provider.openapi.yaml).
+
+***test reqs***
+
+- :ConformanceTests: run against the live :ProviderApi: sandbox — no recorded fixtures and no mocking of provider calls.
+  - Credentials come from `PROVIDER_CLIENT_ID` and `PROVIDER_CLIENT_SECRET` in the environment.
+  - The `429` and forced-`5xx` paths mock that endpoint alone; every other path is live.
+
+- :ConformanceTests: are executed via the run script [test_scripts/run_conformance_tests_python.sh](test_scripts/run_conformance_tests_python.sh).
+```
+
+A policy that holds for every endpoint is stated once. Enumerate an endpoint only where it departs
+from the policy — here, the two paths that cannot be exercised live safely, which
+`integrations.md` requires to be documented explicitly.

package/forge/rules/concise-specs.md

@@ -0,0 +1,80 @@
+---
+description: Conciseness and plain-language rules that keep .plain specs reviewable by a human
+---
+
+# Rules for keeping `.plain` specs concise
+
+These rules apply to every section, to concept explanations, and to acceptance tests. `concise-specs-examples.md` holds a worked BAD to GOOD pair for each failure mode named here, and `concise-specs-integration-examples.md` covers the failure modes specific to integration specs.
+
+## Why this matters
+
+- A spec is the source of truth, so a human has to be able to review it
+- A long, dense, or ornate spec is skipped rather than reviewed — an unreviewed spec is an unverified spec, however correct it happens to be
+- Length is not a proxy for rigor: a spec earns trust by being checkable, not by being thorough-looking
+- Conciseness is about removing what carries no information, never about removing required detail — the deterministic-interface, disambiguation, and testability rules always win (see `func-specs.md`)
+
+## Do not write the obvious
+
+Delete any line a competent reader would already assume. Ask of every line: *if this were missing, would anything be built differently?* If not, cut it.
+
+Do not write:
+
+- Restatements of a concept's own name (`:UserEmail: is the email address of a :User:.` adds nothing beyond what `definitions.md` already requires the concept to carry)
+- Universal software defaults: that invalid input is rejected, that errors are reported, that data is saved when saving is the point of the operation
+- Rationale, motivation, benefits, or background — the spec states what is, not why it was chosen
+- Standard behavior of a technology already named in `***implementation reqs***` (an HTTP framework parses HTTP; a database driver opens connections)
+- Restatements of a nearby bullet in different words, or of anything already stated in an `import`ed or `require`d module
+- Anything about work the spec is not about ("no changes to the existing UI")
+- Meta-commentary about the spec itself ("this spec is intentionally small", "as described above")
+
+Worked pairs for every item above — padding, rationale, defaults, technology behavior,
+meta-commentary, and duplication of an `import` — are in `concise-specs-examples.md`.
+
+## Use plain words
+
+- Prefer the shortest word that is still exact; a technical term needs to be exact, an elaborate one is not
+- Write short sentences: one clause plus, at most, one qualifier
+- Use the same word for the same thing every time — synonym variety reads as two different things
+- Do not use adverbs and adjectives that no test can check: `robust`, `seamless`, `efficient`, `scalable`, `comprehensive`, `modern`, `properly`, `gracefully`, `as appropriate`, `where applicable`, `best practices`. Either state the checkable fact (`a response is returned within 200 ms`) or delete the word
+- Do not hedge: `should ideally`, `may optionally`, `typically`, `generally`, `if possible`. A spec states one behavior; a hedge tells the renderer to guess
+
+| Do not write | Write |
+|---|---|
+| utilize, leverage | use |
+| facilitate, enable the ability to | let, or name the action |
+| in order to | to |
+| prior to / subsequent to | before / after |
+| in the event that | if |
+| is responsible for handling | handles |
+| performs the validation of | validates |
+| a plurality of | several, or a number |
+| terminate, initiate | stop, start |
+| functionality for X | X |
+
+## Keep the shape small
+
+- One statement per bullet, one bullet per fact (see `bullet-continuation.md`)
+- Nest a sub-bullet only to remove a real ambiguity; a sub-bullet that merely elaborates is filler
+- Consecutive specs that share a subject are usually one spec: if a top-level bullet only tells part of the story of one operation, merge the set, lead with the operation's result, and demote the steps and failure modes to sub-bullets (see *One operation fragmented into several specs* in `concise-specs-integration-examples.md`)
+- Tables, prose paragraphs, and code blocks do not belong in a section; external artifacts are linked from `resources/` (see `linked-resources.md`)
+- A bullet that answers more than one of *what is it*, *what does it do*, *how is it built*, and *how is it tested* is not one fact — split it across the sections that own those facts, which reads better and is the only way the renderer sees each part (see `module-structure.md`, and *Split one crowded bullet across its owning sections* in `concise-specs-examples.md`)
+
+## Terse is not a defect
+
+A finished spec usually reads as abrupt: clipped bullets, no connective tissue, no lead-ins. That is the intended shape, not something to smooth out afterwards.
+
+- Add a word only to make a line correct, unambiguous, or checkable — never to make it read better
+- Do not merge short bullets into one sentence for rhythm, and do not open a section or a bullet with a lead-in
+- The bar is the other rules — correct, intent intact, reviewable, testable. A spec that clears them is finished however clipped it sounds
+- Filler is not neutral: the renderer reads every line as a requirement, so a line written for flow can invent one
+
+## Review pass before writing to disk
+
+Read the drafted lines once more and apply, in order:
+
+1. **The deletion test** — cut every line whose removal would change nothing about what gets built
+2. **The word test** — replace every ornate word with a plain one, and delete every uncheckable adjective, adverb, and hedge
+3. **The duplication test** — cut anything already stated in this file, an `import`, or a `requires` chain
+4. **The read-aloud test** — a line you cannot read aloud in one breath is either two facts or one padded one
+
+If a cut would remove an interface detail, a boundary case, or a disambiguation, keep the fact and shorten the wording instead — see *Do not over-cut* in `concise-specs-examples.md` for what a spec cut past its content looks like.

package/forge/rules/definitions.md

@@ -13,7 +13,7 @@ When writing or editing a `***definitions***` section in a `.plain` file, always
 
 ## Uniqueness
 - Concept names must be globally unique across the spec and all its imports
-- Check for collisions with imported templates, `import` and `requires` modules before adding
+- Check for collisions with concepts coming from `import` and `requires` modules before adding
 
 ## Predefined concepts (do not redefine)
 - ***plain ships several predefined concepts that are available in every module without being defined
@@ -31,6 +31,10 @@ When writing or editing a `***definitions***` section in a `.plain` file, always
 | `:ConformanceTests:` | Auto-generated tests verifying conformance to the spec |
 | `:AcceptanceTest:` / `:AcceptanceTests:` | Tests validating specific aspects of the implementation |
 
+## Conciseness
+- A definition is one plain sentence plus, where needed, its attributes — see `concise-specs.md`
+- Never restate the concept name as its own definition, and never explain why the concept exists
+
 ## Define before use
 - A concept must be defined before it is referenced in any section (definitions, implementation reqs, functional specs, test reqs)
 - Sources of definitions: the module's own `***definitions***`, an `import`ed module's definitions, or a `require`d module's `exported_concepts`
@@ -60,8 +64,8 @@ Bad — circular:
 ```
 
 ## Exported concepts are not transitive
-- If module A exports a concept and module B `requires` A, module C `requires` B does **not** gain access to A's exports
-- Shared concepts belong in a common import module
+- If module A exports a concept and module B `requires` A, a module C with `requires: [B]` does **not** gain access to A's exports
+- To use an ancestor's exports, list that ancestor in `requires` as well; concepts shared more broadly belong in a common import module
 
 ## Description quality
 - Descriptions must be clear, concise, and language-agnostic
@@ -89,7 +93,6 @@ Example of defining technical components alongside their behavior:
 
 - :CsvFileReader: reads CSV rows in a batched manner.
 
-
 - :CsvJoiner: joins csvs and uses :CsvFileWriter: to create the merged CSV.
 ```
 

package/forge/rules/exported-concepts.md

@@ -10,6 +10,7 @@ When adding or editing `exported_concepts` in a `.plain` file's frontmatter, alw
 - `exported_concepts` declares which concepts from this module are visible to modules that `require` it
 - Concepts not listed in `exported_concepts` are internal to the module and invisible to downstream modules
 - Only modules that use `requires` receive exported concepts — `import` gives access to all definitions, not just exports
+- An exported concept is visible with its full definition text
 
 ## When to use it
 - Use `exported_concepts` on any module that other modules will `require`
@@ -21,8 +22,8 @@ When adding or editing `exported_concepts` in a `.plain` file's frontmatter, alw
 - Do not export concepts that are not defined in the module
 
 ## Exports are not transitive
-- If module A exports `:Foo:` and module B `requires` A, module C `requires` B does **not** gain access to `:Foo:`
-- If module C also needs `:Foo:`, it must either `require` A directly or get it through a common import module
+- If module A exports `:Foo:` and module B `requires` A, a module C with `requires: [B]` does **not** gain access to `:Foo:`
+- If module C also needs `:Foo:`, it should list A in its `requires` as well (`requires: [A, B]`) or get `:Foo:` through a common import module
 
 ## Format
 

package/forge/rules/func-specs.md

@@ -37,8 +37,15 @@ GOOD — statements of fact with concrete subjects:
 - A :User: can add a :Task:. Only valid :Task: items are added.
 ```
 
+## Conciseness
+- A functional spec that a human will not read is not reviewed, so every spec must be as short as its content allows — see `concise-specs.md`
+- Cut anything obvious, any rationale, and every uncheckable adjective; keep every interface detail, boundary case, and disambiguation
+- Shorten the wording, never the facts: the rules below always win over brevity
+
 ## Complexity limit
-- Each functional spec must imply a **maximum of 200 changed lines of code**
+- The complexity limit is about breaking software into small, independently understandable behavior slices that people and AI can reason about, implement, and test reliably
+- The current mechanism for enforcing the complexity limit is that each functional spec must imply a **maximum of 200 changed lines of code**.
+- Smaller slices produce focused test failures, reduce hidden coupling and regression surface, and make review and incremental rendering more predictable
 - If a spec is too large, use `break-down-func-spec` to split it into multiple smaller, independent specs
 - Use `analyze-if-func-spec-too-complex` to verify before inserting
 - Use `analyze-func-specs` to check a spec (or a batch of specs) against all relevant existing specs in a single batched call; use `resolve-spec-conflict` for each conflicting pair it reports
@@ -57,7 +64,7 @@ GOOD — statements of fact with concrete subjects:
 - Specs are rendered incrementally, top to bottom
 - The renderer has **no knowledge of future specs** — only previously rendered specs are in context
 - A new spec can reference behavior from earlier specs but cannot assume anything about specs that come after it
-- Functional specs from `requires` modules are treated as previous requirements
+- Functional specs from `requires` modules are treated as previous requirements — transitively, across the whole ancestor chain
 
 ## No conflicts
 - The new spec must not contradict any existing functional spec
@@ -92,7 +99,7 @@ GOOD — statements of fact with concrete subjects:
 
 ## Encapsulation
 - Functionality must be self-contained in the spec text
-- `requires` modules only receive functional specs — do not rely on implementation reqs to convey behavior
+- `requires` modules only pass on functional specs and `exported_concepts` — never implementation reqs, so do not rely on implementation reqs to convey behavior
 - Behavior that downstream modules need must be expressed in functional specs, not elsewhere
 
 ## Acceptance tests

package/forge/rules/impl-reqs.md

@@ -13,7 +13,7 @@ When writing or editing an `***implementation reqs***` section in a `.plain` fil
 
 ## `: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
+- `:UnitTests:` are part of the generated codebase (they sit inside `plain_modules/<module>/code/` 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
 
@@ -41,17 +41,21 @@ When writing or editing an `***implementation reqs***` section in a `.plain` fil
 - Unit testing run scripts should be linked here as a linked resource
 
 ## Encapsulation warning
-- `requires` modules only receive functional specs from their dependencies — not implementation reqs
+- `requires` modules only pass on functional specs and `exported_concepts` — never implementation reqs
 - If downstream modules need certain behavior to be visible, express it in functional specs, not here
 
+## Conciseness
+- State each req in the fewest plain words that stay exact — see `concise-specs.md`
+- Do not restate the standard behavior of a technology this section already names
+
 ## No duplication
 - Do not duplicate guidance already present in the file or its imports
-- Check imported templates before adding a new req
+- Check imported modules before adding a new req
 
 ## Concept references
 - Reference defined `:Concepts:` where they add clarity
 - All referenced concepts must already be defined in `***definitions***`
-- Implementation reqs in non-leaf sections apply to all subsections
+- Make the component a req constrains its subject; `:Implementation:` is the whole codebase, so use it only for a fact that holds everywhere — language, dependency manager, stack-wide convention
 
 ## Format
 
@@ -59,6 +63,6 @@ When writing or editing an `***implementation reqs***` section in a `.plain` fil
 ***implementation reqs***
 - :Implementation: should be in Python 3.12.
 - :Implementation: should use pip for dependency management.
-- When writing CSV files, :Implementation: should use streaming writes to avoid holding large datasets in memory.
+- :ReportExporter: writes a :CsvFile: with streaming writes, never holding the full dataset in memory.
 - :UnitTests: are executed via the run script [test_scripts/run_unittests_python.sh](test_scripts/run_unittests_python.sh).
 ```

package/forge/rules/import-modules.md

@@ -10,18 +10,16 @@ When creating or editing a `.plain` file that uses `import` or is intended to be
 - An import module contains **only** `***definitions***`, `***implementation reqs***`, and/or `***test reqs***`
 - It must **not** contain `***functional specs***`
 - It must **not** use `requires` in its frontmatter
-- It must live in the **`template/`** directory
-- It may optionally `import` other modules or templates for layered reuse
+- It may optionally `import` other import modules for layered reuse
 
 ## What import does
 - `import` pulls in `***definitions***`, `***implementation reqs***`, and `***test reqs***` from the target module
 - It does **not** pull in `***functional specs***`
-- The default import directory is `template/` — the `template/` prefix is not needed in import paths
 - Import paths omit the `.plain` extension
 
 ## Concept visibility
-- All concepts defined in the imported module become available in the importing module
-- Check for concept name collisions between imports and local definitions before adding
+- All concepts defined in the imported module become available in the importing module — including concepts the imported module itself imports (layered imports are transitive)
+- Check for concept name collisions between imports and local definitions before adding — a collision is rejected as a syntax error ("Concepts were defined multiple times")
 
 ## Format
 
@@ -46,5 +44,5 @@ import:
 ## Combining import with requires
 - A module can use both `import` and `requires` together
 - `import` brings in shared definitions and reqs
-- `requires` brings in the build dependency chain and functional specs
+- `requires` attaches the module to the build chain — accumulated generated code and previous functional specs
 - An import module itself must **not** use `requires`

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

@@ -75,7 +75,7 @@ mvn test -Dtest='<:UnitTests: package>.**.*Test' checkstyle:check
 
 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`
+1. **`:ConformanceTests:` source location** — the generated suite lives under `plain_modules/<module>/tests/`, one folder per functional spec; the renderer passes the resolved path of the folder under test 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)
@@ -85,7 +85,7 @@ These reqs feed `run_conformance_tests_<lang>`. At minimum, declare:
 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.
+- :ConformanceTests: of :Implementation: live in `plain_modules/foo/tests/` 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.
@@ -139,7 +139,7 @@ All three scripts are invoked by the `codeplain` renderer with positional argume
 
 ## 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>/`).
+Receives one positional argument: the renderer's build output folder (e.g. `plain_modules/<module>/code/`).
 
 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.
 

package/forge/rules/integration-embedded.md

@@ -30,6 +30,9 @@ The embedded integration's `.plain` specs (and the rest of the ***plain project
 │   ├── resources/
 │   ├── test_scripts/
 │   ├── plain_modules/     # generated; gitignored
+│   │   └── <module>/
+│   │       ├── code/      #   implementation + unit tests
+│   │       └── tests/     #   conformance tests, per functional spec
 │   └── config.yaml
 └── src/            # host source tree (Java, Python, etc.)
 ```
@@ -79,7 +82,6 @@ This rule applies to **host source code only**. Other artifacts still live under
 
 - **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/`.
@@ -117,7 +119,7 @@ The renderer reads the directives from the spec and the shapes from the linked s
 
 ## Test-script wiring — copy into the host, run tests 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 scratch folder in the system temp directory (`/tmp/<lang>_conformance/`), because the conformance suite is a separate project that consumes the host build as a dependency.
+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>/code/`) 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 scratch folder in the system temp directory (`/tmp/<lang>_conformance/`), 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.
 

package/forge/rules/integration-standalone.md

@@ -103,7 +103,7 @@ Capture as a contract-version concept; pin the version in every published schema
 
 `: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`:
 
-- **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
+- **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 may back unit tests — never 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