plain-forge 1.0.23 → 1.0.24-next.019bba8

package/forge/{rules → skills/load-plain-reference/rules}/concise-specs-examples.md

@@ -19,11 +19,14 @@ BAD:
 ```plain
 ***functional specs***
 
-- In order to provide users with a robust and seamless experience, :TaskService: exposes a comprehensive endpoint for the creation of new :Task: items.
+# create-task
+In order to provide users with a robust and seamless experience, :TaskService: exposes a comprehensive endpoint for the creation of new :Task: items.
 
-- The endpoint accepts a request and, provided that the incoming payload is valid and well-formed, proceeds to persist the :Task: appropriately.
+# persist-task
+The endpoint accepts a request and, provided that the incoming payload is valid and well-formed, proceeds to persist the :Task: appropriately.
 
-- If the payload is not valid, an appropriate error is returned to the caller so that the user is informed of the problem.
+# reject-invalid-payload
+If the payload is not valid, an appropriate error is returned to the caller so that the user is informed of the problem.
 ```
 
 GOOD:
@@ -31,10 +34,11 @@ GOOD:
 ```plain
 ***functional specs***
 
-- A :User: can create a :Task: via `POST /tasks`.
-  - The request body is a :Task: without `id`.
-  - The response is `201` with the created :Task:.
-  - A request without a name returns `400`.
+# create-task
+A :User: can create a :Task: via `POST /tasks`.
+- The request body is a :Task: without `id`.
+- The response is `201` with the created :Task:.
+- A request without a name returns `400`.
 ```
 
 Three bullets became one, and the rewrite names the method, the path, the request shape, and both status codes — none of which the padded version pinned down.
@@ -46,7 +50,8 @@ BAD:
 ```plain
 ***functional specs***
 
-- Because support staff frequently need to find customers quickly, and because scanning the full list is slow and error-prone, :CustomerDirectory: offers a search capability that greatly improves their daily workflow.
+# search-customers
+Because support staff frequently need to find customers quickly, and because scanning the full list is slow and error-prone, :CustomerDirectory: offers a search capability that greatly improves their daily workflow.
 ```
 
 GOOD:
@@ -54,7 +59,8 @@ GOOD:
 ```plain
 ***functional specs***
 
-- :CustomerDirectory: returns :Customer: items whose name or email contains a search term, case-insensitively.
+# search-customers
+:CustomerDirectory: returns :Customer: items whose name or email contains a search term, case-insensitively.
 ```
 
 Why the feature exists changes nothing about what is built. What "search" matches does.
@@ -86,11 +92,12 @@ BAD:
 ```plain
 ***functional specs***
 
-- :OrderApi: returns a list of :Order: items over HTTP.
-  - The list contains :Order: items.
-  - If there are no :Order: items, the list is empty.
-  - Each :Order: has an `id`, which is unique.
-  - The caller receives the response after the request is sent.
+# list-orders
+:OrderApi: returns a list of :Order: items over HTTP.
+- The list contains :Order: items.
+- If there are no :Order: items, the list is empty.
+- Each :Order: has an `id`, which is unique.
+- The caller receives the response after the request is sent.
 ```
 
 GOOD:
@@ -98,8 +105,9 @@ GOOD:
 ```plain
 ***functional specs***
 
-- :OrderApi: returns the :Order: items of the authenticated :User: via `GET /orders`, newest first.
-  - The response is `200` with a JSON array, empty when the :User: has no :Order: items.
+# list-orders
+:OrderApi: returns the :Order: items of the authenticated :User: via `GET /orders`, newest first.
+- The response is `200` with a JSON array, empty when the :User: has no :Order: items.
 ```
 
 Every cut line was already implied: a list of :Order: items contains :Order: items, an identifier identifies, and a response follows a request. What survives is what a reader could *not* have guessed — the ownership filter, the sort order, and the response shape.
@@ -113,11 +121,14 @@ BAD:
 ```plain
 ***functional specs***
 
-- :OrderService: validates all incoming data before processing it.
+# validate-input
+:OrderService: validates all incoming data before processing it.
 
-- :OrderService: handles errors and returns meaningful error messages.
+# handle-errors
+:OrderService: handles errors and returns meaningful error messages.
 
-- :OrderService: saves the :Order: to storage so that it is not lost.
+# save-order
+:OrderService: saves the :Order: to storage so that it is not lost.
 ```
 
 GOOD:
@@ -125,7 +136,8 @@ GOOD:
 ```plain
 ***functional specs***
 
-- :OrderService: rejects an :Order: whose `total` does not equal the sum of its :OrderLine: amounts, with `422`.
+# reject-wrong-total
+:OrderService: rejects an :Order: whose `total` does not equal the sum of its :OrderLine: amounts, with `422`.
 ```
 
 Validating input, reporting errors, and persisting on a save operation belong in the `***implementation reqs***` and a baseline is assumed. If there is a specific use case for a particular operation, it should be documented there, not in the `***functional specs***`. The one fact worth stating is *which* rule is enforced and what the caller sees when it fails.
@@ -218,7 +230,8 @@ BAD:
 ```plain
 ***functional specs***
 
-- :ReportGenerator: is responsible for facilitating the utilization of a plurality of :DataSource: instances in order to initiate the generation of a :Report: prior to the performance of the validation of the resulting output.
+# build-report
+:ReportGenerator: is responsible for facilitating the utilization of a plurality of :DataSource: instances in order to initiate the generation of a :Report: prior to the performance of the validation of the resulting output.
 ```
 
 GOOD:
@@ -226,7 +239,8 @@ GOOD:
 ```plain
 ***functional specs***
 
-- :ReportGenerator: builds a :Report: from one or more :DataSource: items, then validates it.
+# build-report
+:ReportGenerator: builds a :Report: from one or more :DataSource: items, then validates it.
 ```
 
 Same sequence, plain words. See the substitution table in `concise-specs.md`.
@@ -238,10 +252,11 @@ BAD:
 ```plain
 ***functional specs***
 
-- A :User: can archive a :Project:.
-  - Archiving is an action the user performs on a project.
-  - The archive action is available to users who have access to the project.
-  - Once archived, the project is in the archived state.
+# archive-project
+A :User: can archive a :Project:.
+- Archiving is an action the user performs on a project.
+- The archive action is available to users who have access to the project.
+- Once archived, the project is in the archived state.
 ```
 
 GOOD:
@@ -249,9 +264,10 @@ GOOD:
 ```plain
 ***functional specs***
 
-- A :User: can archive a :Project: they own.
-  - An archived :Project: is excluded from :ProjectList:.
-  - Archiving a :Project: that is already archived returns `409`.
+# archive-project
+A :User: can archive a :Project: they own.
+- An archived :Project: is excluded from :ProjectList:.
+- Archiving a :Project: that is already archived returns `409`.
 ```
 
 A sub-bullet earns its line by removing an ambiguity. If it only says the parent again in more words, it is filler.
@@ -263,9 +279,10 @@ BAD:
 ```plain
 ***functional specs***
 
-- :SessionStore: expires a :Session: 30 minutes after its last use.
-  - Sessions do not live forever; they time out.
-  - The timeout is 30 minutes.
+# expire-session
+:SessionStore: expires a :Session: 30 minutes after its last use.
+- Sessions do not live forever; they time out.
+- The timeout is 30 minutes.
 ```
 
 GOOD:
@@ -273,8 +290,9 @@ GOOD:
 ```plain
 ***functional specs***
 
-- :SessionStore: expires a :Session: 30 minutes after its last use.
-  - A request carrying an expired :Session: returns `401`.
+# expire-session
+:SessionStore: expires a :Session: 30 minutes after its last use.
+- A request carrying an expired :Session: returns `401`.
 ```
 
 ## Synonym drift
@@ -284,11 +302,14 @@ BAD:
 ```plain
 ***functional specs***
 
-- A :User: can upload a :Document:.
+# upload-document
+A :User: can upload a :Document:.
 
-- The system stores the submitted file in :DocumentStore:.
+# store-document
+The system stores the submitted file in :DocumentStore:.
 
-- The uploaded asset is retrievable by its identifier.
+# retrieve-document
+The uploaded asset is retrievable by its identifier.
 ```
 
 Three names — `:Document:`, "file", "asset" — read as three things. A reader cannot tell whether "asset" is a fourth concept, and the renderer cannot either.
@@ -298,9 +319,10 @@ GOOD:
 ```plain
 ***functional specs***
 
-- A :User: can upload a :Document:.
-  - :DocumentStore: stores the :Document: and assigns it a :DocumentId:.
-  - A :User: can retrieve a :Document: by its :DocumentId:.
+# upload-document
+A :User: can upload a :Document:.
+- :DocumentStore: stores the :Document: and assigns it a :DocumentId:.
+- A :User: can retrieve a :Document: by its :DocumentId:.
 ```
 
 ## Meta-commentary and scope disclaimers
@@ -310,13 +332,17 @@ BAD:
 ```plain
 ***functional specs***
 
-- This spec is intentionally kept small so that it stays within the complexity limit.
+# export-csv-size-note
+This spec is intentionally kept small so that it stays within the complexity limit.
 
-- As described above, :ExportService: writes a :CsvFile:.
+# export-csv-reference
+As described above, :ExportService: writes a :CsvFile:.
 
-- No changes are made to the existing :ImportService: or to the user interface.
+# export-csv-no-changes
+No changes are made to the existing :ImportService: or to the user interface.
 
-- Future specs will extend this behavior with additional formats.
+# export-csv-future
+Future specs will extend this behavior with additional formats.
 ```
 
 GOOD:
@@ -324,9 +350,10 @@ GOOD:
 ```plain
 ***functional specs***
 
-- :ExportService: writes the :Order: items of a :BillingPeriod: to a :CsvFile:.
-  - The header row is `id,customer,total,currency`.
-  - An empty :BillingPeriod: produces a :CsvFile: with only the header row.
+# export-csv
+:ExportService: writes the :Order: items of a :BillingPeriod: to a :CsvFile:.
+- The header row is `id,customer,total,currency`.
+- An empty :BillingPeriod: produces a :CsvFile: with only the header row.
 ```
 
 A spec describes the software, not itself. What the spec does *not* change is everything it does not mention, and what later specs will add belongs to those specs.
@@ -338,13 +365,14 @@ BAD:
 ```plain
 ***functional specs***
 
-- :PricingEngine: applies discounts.
-  The discount matrix is as follows:
-  | Tier | Volume | Discount |
-  |---|---|---|
-  | Bronze | 0-99 | 0% |
-  | Silver | 100-499 | 5% |
-  | Gold | 500+ | 12% |
+# apply-discounts
+:PricingEngine: applies discounts.
+The discount matrix is as follows:
+| Tier | Volume | Discount |
+|---|---|---|
+| Bronze | 0-99 | 0% |
+| Silver | 100-499 | 5% |
+| Gold | 500+ | 12% |
 ```
 
 GOOD:
@@ -352,8 +380,9 @@ GOOD:
 ```plain
 ***functional specs***
 
-- :PricingEngine: applies the :DiscountTier: matrix in [resources/discount-tiers.json](resources/discount-tiers.json) to an :Order: total.
-  - An :Order: below the lowest tier threshold gets no discount.
+# apply-discounts
+:PricingEngine: applies the :DiscountTier: matrix in [resources/discount-tiers.json](resources/discount-tiers.json) to an :Order: total.
+- An :Order: below the lowest tier threshold gets no discount.
 ```
 
 A section holds `- ` list items. Matrices, schemas, and payloads are external artifacts and are linked from `resources/` — see `linked-resources.md`.
@@ -373,7 +402,8 @@ BAD — everything in one place:
 
 ***functional specs***
 
-- :ImageResizer:, implemented as a Python class using Pillow with a thread pool of 4 workers, resizes an uploaded :Image: to a thumbnail, where a thumbnail is defined as a JPEG at most 256 pixels on its longest edge.
+# resize-image
+:ImageResizer:, implemented as a Python class using Pillow with a thread pool of 4 workers, resizes an uploaded :Image: to a thumbnail, where a thumbnail is defined as a JPEG at most 256 pixels on its longest edge.
 ```
 
 GOOD — each fact in the section that owns it:
@@ -395,9 +425,10 @@ GOOD — each fact in the section that owns it:
 
 ***functional specs***
 
-- :ImageResizer: produces a :Thumbnail: from an :Image:.
-  - An :Image: already within the :Thumbnail: bounds is returned unchanged.
-  - An :Image: that is not a supported format raises :UnsupportedImageError:.
+# resize-image
+:ImageResizer: produces a :Thumbnail: from an :Image:.
+- An :Image: already within the :Thumbnail: bounds is returned unchanged.
+- An :Image: that is not a supported format raises :UnsupportedImageError:.
 ```
 
 Each section now answers one question, and the definition, the mechanism, and the behavior are each one line to check instead of clauses buried in a paragraph about resizing. Use the split whenever a bullet answers more than one of *what is it*, *what does it do*, *how is it built*, and *how is it tested* — see `module-structure.md` for section ownership and canonical section order.
@@ -406,26 +437,26 @@ Use `resolve-section-ownership` to perform the split. It is not the same as spli
 
 The most common single case of this is a functional spec that states a mechanism rather than a result — a retry schedule, a cache, a token refresh. `impl-reqs.md` owns HOW; a functional spec keeps what a caller observes. `concise-specs-integration-examples.md` works through several.
 
-## Narrated acceptance tests
+## Narrated scenarios
 
 BAD:
 
 ```plain
-***acceptance tests***
+***conformance tests***
 
-- The tester should first open the application and log in with a valid account, then navigate to the projects area where they will be able to see the list of projects, and then they should create a new project by filling in the form, after which they should verify that everything worked as expected and the project shows up correctly.
+# create-project
+The tester should first open the application and log in with a valid account, then navigate to the projects area where they will be able to see the list of projects, and then they should create a new project by filling in the form, after which they should verify that everything worked as expected and the project shows up correctly.
 ```
 
 GOOD:
 
 ```plain
-***acceptance tests***
+***conformance tests***
 
-- A :User: creates a :Project: and finds it in :ProjectList:.
-  - Sign in as a :User: with no :Project: items.
-  - Create a :Project: named `Apollo`.
-  - :ProjectList: contains exactly one :Project:, named `Apollo`.
+# create-project
+A signed-in :User: with no :Project: items creates a :Project: named `Apollo` and finds it in :ProjectList:.
+- :ProjectList: contains exactly one :Project:, named `Apollo`.
 ```
 
-One narrated paragraph becomes an ordered set of checkable steps, and "everything worked as
+One narrated paragraph becomes one checkable sentence, and "everything worked as
 expected" becomes an assertion.

package/forge/{rules → skills/load-plain-reference/rules}/concise-specs-integration-examples.md

@@ -31,11 +31,14 @@ BAD:
 
 ***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.
+# retry-transient-errors
+: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.
+# no-retry-permanent-errors
+: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.
+# retry-on-429
+On 429, :ProviderClient: waits and tries again, unless the retry budget is exhausted.
 ```
 
 GOOD:
@@ -91,13 +94,17 @@ BAD:
 
 ***functional specs***
 
-- :ProviderApi: returns `200` with a JSON body when a request succeeds.
+# provider-success-response
+:ProviderApi: returns `200` with a JSON body when a request succeeds.
 
-- :ProviderApi: returns `404` when the requested :Customer: does not exist.
+# provider-not-found
+:ProviderApi: returns `404` when the requested :Customer: does not exist.
 
-- :ProviderApi: rate-limits clients and includes the remaining quota in the response headers.
+# provider-rate-limit
+:ProviderApi: rate-limits clients and includes the remaining quota in the response headers.
 
-- :ProviderApi: requires the `Authorization` header on every request.
+# provider-auth-header
+:ProviderApi: requires the `Authorization` header on every request.
 ```
 
 GOOD:
@@ -123,7 +130,8 @@ GOOD:
 
 ***functional specs***
 
-- :ProviderClient: fetches a :Customer: from :ProviderApi: by :CustomerId:.
+# fetch-customer
+: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.
@@ -147,19 +155,23 @@ BAD — four specs, one operation:
 
 ***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`.
+# fetch-requires-api-key
+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.
+# fetch-reads-catalogue
+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.
+# fetch-requests-records
+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.
+# fetch-pages-records
+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:
@@ -175,10 +187,11 @@ GOOD — one spec, with the result stated first:
 
 ***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.
+# fetch-records
+: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.
@@ -190,9 +203,11 @@ 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.
+# obtain-token
+: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.
+# refresh-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:

package/forge/{rules → skills/load-plain-reference/rules}/concise-specs.md

@@ -4,7 +4,7 @@ description: Conciseness and plain-language rules that keep .plain specs reviewa
 
 # 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.
+These rules apply to every section, to concept explanations, and to scenarios in test plain files. `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
 
@@ -53,9 +53,10 @@ meta-commentary, and duplication of an `import` — are in `concise-specs-exampl
 
 ## Keep the shape small
 
+- The bullet rules here apply to `***definitions***`, `***implementation reqs***`, and `***test reqs***`; the body of a functionality and a scenario are free text
 - 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`)
+- Consecutive specs that share a subject are usually one spec: if a functionality 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 detail under it (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`)
 

package/forge/{rules → skills/load-plain-reference/rules}/func-specs.md

@@ -1,11 +1,17 @@
 ---
-description: Rules for writing ***functional specs*** and ***acceptance tests*** in .plain files
+description: Rules for writing ***functional specs*** in .plain files
 ---
 
 # Rules for writing `***functional specs***`
 
 When writing or editing a `***functional specs***` section in a `.plain` file, always follow these rules:
 
+## Shape
+- Each functional spec, called a functionality, is a `# <func-id>` heading followed by its body; the func-id follows `semantic-ids.md`
+- The body is free text that describes the behavior: prose, `- ` bullets, or any other shape the developer prefers; its first line states the behavior
+- No body line starts with `# ` (that starts the next functionality) or with `***`
+- The test scenarios of a functionality live in its test plain file, never in this section (see `test-plain-files.md`)
+
 ## Voice
 - Write each functional spec as a **statement of fact** — present tense, indicative mood — describing what the software *is* or *does* once built, not as a command telling a developer what to build
 - **Name a concrete subject**: an actor (`A :User: can …`), a named component or concept (`:PdfRenderer: lays out …`, `:Order: processing depends on …`), or the affected data in passive voice (`All :Resource: items are returned`)
@@ -18,11 +24,14 @@ BAD — imperative commands, or the vague "The system":
 ```plain
 ***functional specs***
 
-- Implement the entry point for :App:.
+# entry-point
+Implement the entry point for :App:.
 
-- The system shows :TaskList:.
+# show-task-list
+The system shows :TaskList:.
 
-- Add :Task:.
+# add-task
+Add :Task:.
 ```
 
 GOOD — statements of fact with concrete subjects:
@@ -30,11 +39,14 @@ GOOD — statements of fact with concrete subjects:
 ```plain
 ***functional specs***
 
-- :App: has an entry point.
+# entry-point
+:App: has an entry point.
 
-- The :TaskList: is displayed.
+# show-task-list
+The :TaskList: is displayed.
 
-- A :User: can add a :Task:. Only valid :Task: items are added.
+# add-task
+A :User: can add a :Task:. Only valid :Task: items are added.
 ```
 
 ## Conciseness
@@ -80,17 +92,17 @@ GOOD — statements of fact with concrete subjects:
 
 ## Disambiguation
 - Each functional spec must be unambiguous — the renderer should have only one reasonable interpretation
-- If a single line is not enough to fully disambiguate the behavior, use **nested sub-bullets** to add detail
-- Nested lines clarify the parent spec — they do not introduce separate functionality
-- Even with nested detail, the spec must still imply ≤ 200 lines of code
+- If the statement line is not enough to fully disambiguate the behavior, add `- ` bullets or sentences under it to add detail
+- The detail clarifies the statement — it does not introduce separate functionality
+- Even with the detail, the spec must still imply ≤ 200 lines of code
 
 ## Testability
 - Every functional spec must describe behavior that can be verified through an observable interface
 - State the triggering input or action and the deterministic outcome a test can observe
 - Include relevant outputs, state changes, errors, or externally visible side effects
 - Do not rely on generated implementation details as the only way to verify the behavior
-- If a black-box conformance test cannot be derived from the spec, make the behavior more explicit
-- Testability does not require an acceptance test; acceptance tests are reserved for full workflows
+- If a black-box conformance scenario cannot be written from the spec, make the behavior more explicit
+- When conformance tests are enabled, every functionality has a test plain file with at least one conformance scenario (see `test-plain-files.md`); write it in the same step as the functional spec
 
 ## Deterministic interface
 - Specs must be detailed enough that a developer can use the built software without reading the generated code
@@ -102,28 +114,25 @@ GOOD — statements of fact with concrete subjects:
 - `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
-- Nest `***acceptance tests***` under a functional spec when verification criteria are needed
-- Each acceptance test must be a **full workflow test** — a specific scenario that exercises the functional spec end-to-end, not a unit-level check of a single field or condition
-- Do not restate the obvious behavior from the functional spec — simple, direct verifications are already auto-generated as conformance tests. Acceptance tests must go beyond that: multi-step workflows, interactions between concepts, edge-case scenarios, or end-to-end sequences that prove the feature works in a realistic context
-- Each acceptance test must be a direct logical consequence of the parent spec — it illustrates, not extends
-- Acceptance tests must describe concrete, verifiable outcomes — not vague qualities
-- Acceptance tests must not contradict, narrow, or extend beyond the parent spec
+## Test scenarios live in test plain files
+- A spec plain file never holds a `***acceptance tests***` section, nested or top-level
+- Conformance and acceptance scenarios for a functionality go into its test plain file, by convention `tests/<module>/<func-id>.plain`, written with `add-test-scenarios` (see `test-plain-files.md`)
+- A functional spec and its test plain file change together: a spec edit without a scenario review is not finished
 
 ## Format
 
 ```plain
 ***functional specs***
 
-- :App: has an entry point.
-
-- A :User: can add a :Task:. Only valid :Task: items are added.
+# entry-point
+:App: has an entry point.
 
-- A :User: can send a :Message: to a :Conversation:.
-  - A :Message: must have non-empty content.
-  - The :Message: is appended to the end of the :Conversation:.
-  - All :Participant: members of the :Conversation: can see the new :Message:.
+# add-task
+A :User: can add a :Task:. Only valid :Task: items are added.
 
-  ***acceptance tests***
-  - Sending a :Message: to a :Conversation: with three participants should make the message visible to all three.
+# send-message
+A :User: can send a :Message: to a :Conversation:.
+- A :Message: must have non-empty content.
+- The :Message: is appended to the end of the :Conversation:.
+- All :Participant: members of the :Conversation: can see the new :Message:.
 ```

package/forge/{rules → skills/load-plain-reference/rules}/impl-reqs.md

@@ -32,7 +32,7 @@ When writing or editing an `***implementation reqs***` section in a `.plain` fil
 - Behavior and features → `***functional specs***`
 - Concept definitions → `***definitions***`
 - **Conformance-test guidance** → `***test reqs***`
-- **Acceptance-test scenarios** → `***acceptance tests***` nested under the relevant functional spec
+- **Test scenarios**, conformance and acceptance → the functionality's test plain file (see `test-plain-files.md`)
 
 ## Unit tests vs conformance tests (common mistake)
 - Unit-test guidance (`:UnitTests:` framework, structure, mocking) goes **here**, not in `***test reqs***`

package/forge/{rules → skills/load-plain-reference/rules}/integration-embedded-testing.md

@@ -286,4 +286,4 @@ Use them as a template when adding a new embedded integration in Java / Maven
 4. Wire them into the module's `config.yaml` via the `unittests-script`, `conformance-tests-script`, and `prepare-environment-script` keys. Use `init-config-file` to assemble the canonical form
 5. Smoke-test by running each script manually with the renderer's output folder as `$1` (and the conformance-tests folder as `$2` for the conformance runner). Confirm exit codes match what the renderer expects
 
-For non-Java languages, the plain-forge skills [`implement-prepare-environment-script`](../skills/implement-prepare-environment-script/SKILL.md), [`implement-unit-testing-script`](../skills/implement-unit-testing-script/SKILL.md), and [`implement-conformance-testing-script`](../skills/implement-conformance-testing-script/SKILL.md) adapt the contract above to Python, Node.js, Go, Rust, Flutter, and others. Always route script creation through these skills so the cross-cutting rules above are applied uniformly.
+For non-Java languages, the plain-forge skills [`implement-prepare-environment-script`](../../implement-prepare-environment-script/SKILL.md), [`implement-unit-testing-script`](../../implement-unit-testing-script/SKILL.md), and [`implement-conformance-testing-script`](../../implement-conformance-testing-script/SKILL.md) adapt the contract above to Python, Node.js, Go, Rust, Flutter, and others. Always route script creation through these skills so the cross-cutting rules above are applied uniformly.