plain-forge 1.0.20 → 1.0.21-next.55f13d7

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

@@ -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.md

@@ -82,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/`.

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

package/forge/rules/integrations.md

@@ -28,10 +28,11 @@ Pick the right format per artifact:
 | Error code → category mapping | YAML enum | `resources/error-map.yaml` |
 | Rate-limit header inventory | YAML enum | `resources/rate-limit-headers.yaml` |
 | Retry policy parameters | YAML enum | `resources/retry-policy.yaml` |
-| Captured probe responses | Raw JSON | `resources/fixtures/<endpoint>.<case>.json` |
+| Provider behavior with no machine-readable home | Markdown | `resources/<provider>-notes.md` |
 
 Rules that flow from this:
 
+- **Provider behavior is recorded, not specified.** How the provider itself works — its quota accounting, consistency guarantees, documented quirks, and any place the live API diverges from its docs — is true and worth capturing, but it is not a requirement on the software being built. Whatever has a machine-readable home in the table above goes there; the rest goes in `resources/<provider>-notes.md`. A functional spec never states provider behavior; it states what the integration does in the face of it.
 - **Concepts carry references, not data.** An endpoint concept names the endpoint and points at its OpenAPI `paths.<path>.<method>` entry; it does not duplicate the request/response shape in concept attributes. Same for webhook concepts, error-model concepts, pagination concepts, etc.
 - **Functional specs consume linked resources.** A spec describes **behavior** ("call endpoint X, parse the response, classify errors, retry on 5xx") and links to the resource that supplies the **shape**. Field names, types, and validation rules live in the resource file.
 - **Schemas are versioned by file path.** When the provider releases a new API version, copy the new OpenAPI file to a new path (e.g. `resources/<provider>.v2.openapi.yaml`); never mutate the v1 file in place.
@@ -47,13 +48,11 @@ Documentation lies — it goes stale, omits undocumented fields, describes a dif
   - If the environment has **no web-search tool** (only URL-based `fetch` is available), say so explicitly, construct the URL from the provider's well-known documentation root and crawl outward by `fetch`-ing that root and following its links, and ask the user for the canonical URL whenever you cannot reach the right page that way. Never substitute memory for the search-then-fetch step.
 - **Always `fetch` the provider's documentation — even if you already "know" the API.** 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, **web-search to locate the relevant documentation page(s), then `fetch` each one** 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.
 - **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. The credentials should be validated against the live API before any downstream specs are authored.
 - **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.
-- **Every discrepancy is recorded, not smoothed over.** Each finding goes into the relevant resource (the OpenAPI file, the error envelope schema, `rate-limit-headers.yaml`, …) as the source of truth, with a short note in the corresponding concept saying "docs claim X, live API returns Y; we follow the live API".
+- **Where the docs and the live API disagree, the live API wins** — the resource records what the API actually returns, and nothing records the disagreement itself.
 - **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.
 
@@ -61,7 +60,7 @@ Documentation lies — it goes stale, omits undocumented fields, describes a dif
 
 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 integration's `:ConformanceTests:` **must** make real network calls to the provider (typically a sandbox / staging environment, occasionally production for read-only paths). Recorded responses may back unit tests, but 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
@@ -128,11 +127,11 @@ A production-ready integration spec captures every corner case the API can throw
 ## Anti-patterns (do not do these)
 
 - **Restating an OpenAPI / JSON Schema field list in a concept or functional spec.** The schema lives in `resources/`; the spec links to it
-- **Pasting a webhook payload, error envelope, or list-endpoint response inline.** Save it as a fixture under `resources/fixtures/` and link the fixture
+- **Pasting a webhook payload, error envelope, or list-endpoint response inline.** Describe its shape in the applicable schema under `resources/` and link that schema
 - **Inlining a host base class body into the contract spec.** Add the host file as a linked resource under `resources/host/` and reference it by FQN
 - **Embedding credentials, tokens, or signing keys in a `.plain` file or in a summary** — credentials are referenced by env-var name only
 - **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 web-searching for its documentation and `fetch`-ing every relevant page first.** No matter how well-known the API (Stripe, GitHub, Slack, Salesforce, AWS, OpenAI, …), the canonical pages must be located with web search and then 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
+- **Writing any integration spec from memory of the provider's API instead of web-searching for its documentation and `fetch`-ing every relevant page first.** No matter how well-known the API (Stripe, GitHub, Slack, Salesforce, AWS, OpenAI, …), the canonical pages must be located with web search and then retrieved with `fetch` at spec-authoring time — 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
 - **Guessing a documentation URL from memory and `fetch`-ing it without searching first.** A remembered URL may 404, redirect to a stale version, or miss the page that actually documents the topic. Search to find the authoritative, current links, then fetch the full set

package/forge/rules/linked-resources.md

@@ -13,14 +13,15 @@ A linked resource **must not** be any of the following:
 1. **A folder / directory.** `[integrations](src/integrations/)`, `[host project](../host_project/)` are invalid — the renderer cannot ingest a directory. Pick the single most representative file inside (a `README.md`, an exemplar source file, a manifest) and link **that**.
 2. **A URL / external location.** `[Stripe docs](https://stripe.com/docs/api)`, any `http://` / `https://` / `ftp://` / `git://` / `s3://` / `gs://` target. Linked resources are local-file only. If a URL's content is essential, fetch it once, save the response to a text file under `resources/`, and link the saved file.
 3. **A binary file.** PNG, JPG, GIF, PDF, DOCX, XLSX, ZIP, MP3, MP4, compiled binaries (`.exe`, `.so`, `.class`, `.wasm`), and anything else that isn't human-readable text in its raw form. Binary content cannot be meaningfully consumed by the renderer — transcribe it into a text-based form first (a UI screenshot becomes a Markdown description, a PDF spec becomes a Markdown extract or the underlying JSON Schema / OpenAPI, an architecture diagram becomes a Mermaid block).
-4. **Another `.plain` file.** `[Auth Module](auth.plain)` is invalid. To reference another module, use the `require` or `import` frontmatter directives. Do not link it as a markdown resource; the `plain-dry-run` will flag this as a syntax error.
-
-
-## URLs and folder paths must not appear *anywhere* in `.plain` content
-- The constraint is not only about markdown links — URLs and folder paths must not appear **anywhere** in `.plain` content (concept body prose, functional-spec text, implementation reqs, test reqs)
-- The renderer cannot follow URLs or open folders; a URL in prose is a *ghost dependency* — it looks meaningful to a human reader but contributes nothing to code generation, and the spec silently drifts from reality
-- **The only exception** is for URLs and paths that are *values the produced software itself uses at runtime* — the base URL an integration calls, a database connection path, a CLI argument default. Those are configuration values, not external references
-- Litmus test: "Would the renderer benefit from reading the bytes at this URL / folder?" If yes, save it to a file and link the file. If no (it's a runtime value the code carries forward), it can stay as plain text
+4. **Another `.plain` file.** `[Auth Module](auth.plain)` is invalid. To reference another module, use the `require` or `import` frontmatter directives. Do not link it as a markdown resource; the renderer will flag this as a syntax error.
+
+## Never use a URL or folder path as a *reference* in prose
+- The hard constraint above is enforced only on markdown links. A bare URL or folder path in prose (concept body, functional-spec text, implementation reqs, test reqs) passes validation and is fed to the renderer verbatim as part of the spec text
+- That is exactly why it is dangerous as a *reference*: the renderer cannot fetch the URL or open the folder, so the model sees only the address, not the content behind it. To a human reader the line looks grounded in a source; to the renderer it is a *ghost dependency*, and the spec silently drifts from whatever the URL actually says
+- A URL or path in prose is fine when the *text itself* is the complete fact:
+  - **Runtime values** the produced software uses — the base URL an integration calls, a database connection path, a CLI argument default, an output directory layout
+  - **Provenance notes** for a snapshotted resource — recording the canonical URL a file saved under `resources/` was fetched from
+- Litmus test: "Would the renderer benefit from reading the bytes at this URL / folder?" If yes, save it to a file and link the file. If no (the address itself is the fact), it can stay as plain text
 
 ## Structured protocol artifacts must be linked, never transcribed
 - JSON Schema, OpenAPI / Swagger, GraphQL SDL, Protobuf `.proto`, Avro / Thrift schemas, XML XSDs, AsyncAPI specs, JSON-RPC method definitions, wire-protocol descriptions, payload examples — anything with a formal machine-readable shape — belongs in a file under `resources/` (or another directory within the project)