plain-forge 1.0.23 → 1.0.24-next.019bba8

package/README.md

@@ -20,7 +20,7 @@ Pick whichever entry point matches how much upfront design you want:
 ### 2. Grow an existing project
 
 - **`add-feature`** — takes a feature request in plain English and runs the same one-question-at-a-time loop that `forge-plain` uses, scoped to a single feature against an existing `.plain` file.
-- **Per-section authoring skills** — `add-functional-spec`, `add-functional-specs`, `add-implementation-requirement`, `add-test-requirement`, `add-concept`, `add-acceptance-test`, `add-resource`, `add-template`. Each enforces the relevant ***plain syntax rules (concept uniqueness, complexity limits, bullet syntax, linked-resource constraints, …) so hand-authoring doesn't drift from the language.
+- **Per-section authoring skills** — `add-functional-spec`, `add-functional-specs`, `add-implementation-requirement`, `add-test-requirement`, `add-concept`, `add-test-scenarios`, `add-resource`, `add-template`. Each enforces the relevant ***plain syntax rules (concept uniqueness, complexity limits, bullet syntax, linked-resource constraints, …) so hand-authoring doesn't drift from the language. `add-test-scenarios` writes the test plain file of a functionality — by convention `tests/<module>/<func-id>.plain` — with the conformance and acceptance scenarios the renderer implements, and nothing else.
 - **Module-management skills** — `create-import-module`, `create-requires-module`, `refactor-module`, `consolidate-concepts` for restructuring as the project grows.
 
 ### 3. Validate and maintain
@@ -87,23 +87,26 @@ Each install writes three subfolders under the chosen directory:
 
 ```
 <agent-dir>/
-  skills/    # every plain-forge skill
-  rules/     # spec-writing rules (see "How the rules get applied" below)
+  skills/    # every plain-forge skill; the spec-writing rules ship in skills/load-plain-reference/rules/
+  rules/     # plain-forge.md, a short pointer to load-plain-reference (see "How the rules get applied" below)
   docs/      # shared reference docs
 ```
 
 #### How the rules get applied per agent
 
-The `skills/` are discovered natively by every supported agent. The `load-plain-reference` skill
-loads only the rules relevant to the current task and skips rules already present in context. Some
-agents additionally support native rules wiring:
+The `skills/` are discovered natively by every supported agent. The spec-writing rules ship inside the
+`load-plain-reference` skill, which loads only the rules relevant to the current task and skips rules
+already present in context — so a session pays for the rules its task needs, not for the whole rule
+set. The installed `rules/` dir holds only `plain-forge.md`, a short pointer telling the agent to
+invoke `load-plain-reference` when it works on `.plain` files. Each agent picks that pointer up as
+follows:
 
 | Agent | How rules are applied |
 |-------|-----------------------|
-| **Claude Code** | Native — Claude Code auto-loads `.claude/rules/*.md` at launch. Each rule carries `paths: "**/*.plain"` frontmatter so Claude scopes it to `.plain` files. No extra wiring. |
+| **Claude Code** | Native — Claude Code auto-loads `.claude/rules/*.md`. The pointer carries `paths: "**/*.plain"` frontmatter, so it loads only once Claude reads or edits a `.plain` file. No extra wiring. |
 | **OpenCode** | OpenCode doesn't auto-load a `rules/` dir; it reads globs from the `instructions` array in `opencode.json`. plain-forge **merges** a rules glob there — `.opencode/rules/*.md` (project, written to `./opencode.json`) or the absolute `~/.config/opencode/rules/*.md` (global, written to `~/.config/opencode/opencode.json`; absolute because OpenCode doesn't expand `~`). |
 | **ForgeCode** | plain-forge also appends a fenced managed pointer block to `AGENTS.md`: repo-root `./AGENTS.md` for project installs or `~/forge/AGENTS.md` globally. |
-| **Codex / GitHub Copilot / Universal** | No extra instruction file is generated. Their discovered `load-plain-reference` skill loads applicable files from `.agents/rules/` when needed. |
+| **Codex / GitHub Copilot / Universal** | No extra instruction file is generated. Their discovered `load-plain-reference` skill loads applicable files from `.agents/skills/load-plain-reference/rules/` when needed. |
 
 When plain-forge touches `opencode.json` or ForgeCode's `AGENTS.md`, it merges into existing content
 and leaves unrelated configuration intact. `uninstall` removes only plain-forge's glob or block.
@@ -254,7 +257,7 @@ git add vendor/pyro
 git commit -m "Bump pyro to vX.Y.Z"
 ```
 
-On `install`, the CLI reads `forge/skills` and `forge/rules` and writes them into the chosen agent directory (`.claude/`, `.agents/` for Codex/Copilot/universal, `.forge/`, or `.opencode/` — see the per-agent table above for global-scope paths), recording every file it wrote in `<agent-dir>/.plain-forge/manifest.json` so `update` can later refresh and prune precisely. For agents that need it, it also wires the rules into `opencode.json` or ForgeCode's `AGENTS.md` (see [How the rules get applied per agent](#how-the-rules-get-applied-per-agent)).
+On `install`, the CLI reads `forge/skills` and `forge/rules` and writes them into the chosen agent directory (`.claude/`, `.agents/` for Codex/Copilot/universal, `.forge/`, or `.opencode/` — see the per-agent table above for global-scope paths), recording every file it wrote in `<agent-dir>/.plain-forge/manifest.json` so `update` can later refresh and prune precisely. For agents that need it, it also wires the rules pointer into `opencode.json` or ForgeCode's `AGENTS.md` (see [How the rules get applied per agent](#how-the-rules-get-applied-per-agent)).
 
 ## Available Skills
 
@@ -276,7 +279,7 @@ On `install`, the CLI reads `forge/skills` and `forge/rules` and writes them int
 | `add-implementation-requirement` | Add a non-functional requirement to `***implementation reqs***` |
 | `add-test-requirement` | Add a testing requirement to `***test reqs***` |
 | `add-concept` | Define a new concept in `***definitions***` |
-| `add-acceptance-test` | Add verification criteria under a functional spec |
+| `add-test-scenarios` | Write or update the test plain file of a functionality (by convention `tests/<module>/<func-id>.plain`): conformance scenarios for its expected use and, when asked, acceptance scenarios for its unexpected use, in plain English |
 | `add-resource` | Link an external file (schema, API spec) to a spec |
 | `add-template` | Create or include a reusable Liquid template |
 
@@ -294,7 +297,7 @@ On `install`, the CLI reads `forge/skills` and `forge/rules` and writes them int
 | Skill | Description |
 |-------|-------------|
 | `init-config-file` | Build / finalize the project's `config.yaml` file(s) from the decisions made in Phase 3. Knows the full set of valid keys, refuses to write secrets or per-invocation options, and produces one config per part of the project. Run at the end of `forge-plain` (just before `plain-healthcheck`) and any time the testing surface changes. |
-| `plain-healthcheck` | Verification gate: validates every `config.yaml`, confirms each `*-script` field points at a real file in `test_scripts/`, runs `plain-parser check` on every top module, and checks every module against the rules. Run whenever anything in the project is finalized — at the end of `forge-plain`, at the end of `add-feature`, after `debug-specs`, and after any single-skill edit that touches the renderable surface. |
+| `plain-healthcheck` | Verification gate: validates every `config.yaml`, confirms each `*-script` field points at a real file in `test_scripts/`, runs `plain-parser check` on every top module, and checks every module and test plain file against the rules. Run whenever anything in the project is finalized — at the end of `forge-plain`, at the end of `add-feature`, after `debug-specs`, and after any single-skill edit that touches the renderable surface. |
 | `check-plain-env` | Read the project's `.plain` files, `test_scripts/`, `config.yaml`(s), and `resources/`, then probe the host for every requirement **the package manager can't install**: language toolchains (`python` + `pip`, `node` + `npm`, JDK + `mvn`, Go, Rust, .NET, etc.), external services (Postgres, Redis, Docker, ...), system binaries that language packages wrap (`ffmpeg`, `tesseract`, `pdftoppm`, browser binaries, ...), hardware / drivers / accelerators (NVIDIA driver → CUDA toolkit → cuDNN → framework-sees-GPU chain), credential env vars, and `plain-parser`. Does **not** probe individual language packages — `pip install -r requirements.txt` (and equivalents) handle those when the test scripts run. Emits a `PASS` / `WARN` / `FAIL` report with OS-specific install commands for any gaps. Read-only — never installs anything. Run on first-time setup, before rendering on a new machine, after adding a new tech to a project, or any time `command not found` shows up in test output. |
 | `analyze-if-func-spec-too-complex` | Check if a spec exceeds the 200-line complexity limit |
 | `analyze-func-specs` | Check a batch of specs (2+) against each other in one call and return every conflicting pair |

package/bin/cli.mjs

@@ -369,8 +369,8 @@ function opencodeConfigPath(scope) {
 // The instructions glob to add. Project scope uses a cwd-relative glob (opencode
 // resolves relative instruction paths against the launch cwd). Global scope must
 // be absolute: opencode does not expand ~ and would resolve a relative path
-// against the project cwd, not the config dir. Only top-level rules/*.md are
-// wired in — the examples/ subtree holds reference scripts, not instructions.
+// against the project cwd, not the config dir. rules/ holds only the pointer to
+// load-plain-reference; the authoring rules ship inside that skill and load on demand.
 function opencodeRulesGlob(scope) {
   if (scope === "global") {
     return toPosix(
@@ -531,8 +531,9 @@ function agentsMdBlock(glob) {
     "## ***plain authoring rules (plain-forge)",
     "",
     "When creating or editing `.plain` specification files, first read and follow",
-    `every rule file matching \`${glob}\`. Each file covers one section or topic of`,
-    "the ***plain language; they are installed and maintained by plain-forge.",
+    `every rule file matching \`${glob}\`. They route to the \`load-plain-reference\``,
+    "skill, which loads the ***plain authoring rules for the task; they are installed",
+    "and maintained by plain-forge.",
     AGENTS_MD_END,
   ].join("\n");
 }

package/forge/rules/plain-forge.md

@@ -0,0 +1,10 @@
+---
+description: Routes .plain work to the load-plain-reference skill, which loads the ***plain authoring rules
+paths:
+  - "**/*.plain"
+---
+
+# ***plain authoring rules
+
+- Before you read, edit, or write any `.plain` file, invoke the `load-plain-reference` skill and read the rule files it routes you to.
+- It loads only the ***plain authoring rules that apply to the task; they ship inside that skill under `rules/`.

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

@@ -8,7 +8,7 @@ description: >-
 
 # Add Concept
 
-Always use the skill `load-plain-reference` to retrieve the ***plain syntax rules — but only if you haven't done so yet.
+**Load the rules first.** Before you read, edit, or write any `.plain` file, invoke the `load-plain-reference` skill and read the rule files it routes you to. Skip this only if `load-plain-reference` already ran in this conversation.
 
 ## Workflow
 

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

@@ -4,7 +4,7 @@ description: >-
   End-to-end feature addition on an existing ***plain project: runs a short feature-intent
   interview, then takes the confirmed request and, one question at a time, incrementally writes
   ***plain specs (concepts, implementation reqs, functional specs, test reqs,
-  acceptance tests) to disk — asking, authoring, and reviewing per
+  test scenarios) to disk — asking, authoring, and reviewing per
   functionality — then closes with a plain-healthcheck gate. Use when the user
   wants to add a feature to an existing project. Not for bootstrapping a new
   project from scratch (use forge-plain) or for editing generated code (the
@@ -13,7 +13,7 @@ description: >-
 
 # Add Feature
 
-Always use the skill `load-plain-reference` to retrieve the ***plain syntax rules — but only if you haven't done so yet.
+**Load the rules first.** Before you read, edit, or write any `.plain` file, invoke the `load-plain-reference` skill and read the rule files it routes you to. Skip this only if `load-plain-reference` already ran in this conversation.
 
 `add-feature` is the continuous-loop counterpart of `forge-plain`. Where `forge-plain` bootstraps an entire project from scratch, `add-feature` adds a single feature to an **existing** set of `.plain` specs. It begins with a short intent phase, then runs the authoring loop scoped to one feature.
 
@@ -49,7 +49,7 @@ Carry the confirmed brief into every later phase. Before advancing, check the Ph
 Keep this short. The goal is to know enough to ask the **very first** writable question — not to design the whole feature on paper.
 
 1. **Read the confirmed feature-intent brief.** Identify which existing `.plain` file(s) the feature most likely belongs to.
-2. **Read the target `.plain` file(s)**, following their `import` and `requires` chains, so the existing definitions, implementation reqs, functional specs, test reqs, and acceptance tests are in context. This is what lets Phase 2 recognize impact when it surfaces.
+2. **Read the target `.plain` file(s)**, following their `import` and `requires` chains, and the module's test plain files, so the existing definitions, implementation reqs, functional specs, test reqs, and scenarios are in context. This is what lets Phase 2 recognize impact when it surfaces.
 3. **Pick the target module with one question — only if it is genuinely ambiguous** which file to modify. Otherwise skip it and start authoring immediately.
 
 End Phase 1 the moment the target file and a single concrete starter question are clear. Do **not** ask framing, scope, or multi-part design questions here.
@@ -77,15 +77,16 @@ Route each answer to the right edit skill — never hand-author a `***plain` sec
 
 - **New concept** → `add-concept` (into `***definitions***`; define before any reference).
 - **New functional spec** → `add-functional-spec`. It runs `analyze-if-func-spec-too-complex` and `analyze-func-specs` for you — let it. **Never hand-author functional specs.** If it reports the spec is too complex, ask the user a follow-up question to split it (the next loop iteration) — do not break it down alone.
+- **Changed functional spec** → edit its statement line or `- ` bullets in place, then invoke `add-test-scenarios` so its test plain file follows the new text.
 - **New implementation req** → `add-implementation-requirement`. When the answer states HOW the functionality is built — a retry or error-handling policy, a data format, a library, an architectural pattern — and it is not already in the file or its imports.
-- **New acceptance test** → `add-acceptance-test`, under the relevant functional spec. Only when the *Conformance gate* is satisfied and the answer describes a concrete verification.
+- **New test scenario** → `add-test-scenarios`, on the functionality's test plain file. Only when the *Conformance gate* is satisfied and the answer describes a concrete verification.
 - **New test req** → `add-test-requirement`. Only when conformance testing is configured and the answer changes how conformance tests are run.
 
 If the answer contradicts or refines an earlier snippet, fix that snippet in place now (per *Fix contradictions in place* above).
 
 ### 2c. Handle conflicts just-in-time
 
-If `add-functional-spec` (via its analyzers) reports a conflict, or the snippet just written would **break** (contradict, invalidate) or **augment** (change the meaning of, add behavior to) an existing concept / functional spec / implementation req / test req / acceptance test, the **next question** must be about that conflict. Show the exact existing snippet in the question and offer:
+If `add-functional-spec` (via its analyzers) reports a conflict, or the snippet just written would **break** (contradict, invalidate) or **augment** (change the meaning of, add behavior to) an existing concept / functional spec / implementation req / test req / test scenario, the **next question** must be about that conflict. Show the exact existing snippet in the question and offer:
 
 - **(a) keep** the existing spec — back out or narrow what was just written,
 - **(b) augment** the existing spec — embed the proposed new wording in the question,
@@ -99,7 +100,7 @@ Ask the user whether the feature is fully covered. Yes → Phase 3. No → retur
 
 ### Conformance gate
 
-Author `***test reqs***` and `***acceptance tests***` **only** when the project has a `config.yaml` with a valid `conformance-tests-script` entry pointing at an existing script in `test_scripts/`. Check the `config.yaml` that covers this module (multi-part projects may have several) and confirm the referenced script exists. If conformance testing is not configured, skip those two authoring paths entirely — concepts, functional specs, and implementation reqs are still authored normally.
+Author `***test reqs***` and test plain files **only** when the project has a `config.yaml` with a valid `conformance-tests-script` entry pointing at an existing script in `test_scripts/`. Check the `config.yaml` that covers this module (multi-part projects may have several) and confirm the referenced script exists. If conformance testing is not configured, skip those two authoring paths entirely — concepts, functional specs, and implementation reqs are still authored normally.
 
 ## Phase 3 — Final review
 
@@ -111,7 +112,7 @@ Most checks already happened in the loop; this is a slim consistency pass whose
    - Chronological ordering is correct end-to-end — no spec depends on something that comes after it.
    - Functional specs are language-agnostic.
    - Every external interface is explicit (endpoint paths, methods, CLI args, formats).
-   - Acceptance tests (if any) are consistent with their parent specs.
+   - Every new or changed functionality has a test plain file whose scenarios follow from its spec, with at least one conformance scenario when conformance tests are enabled.
 3. Present the final diff for the modified file(s) and get the user's approval.
 4. If the user requests changes, drop **straight back into the one-question loop** — one question, one write, one fix at a time. Do not restart the loop from scratch.
 5. **Run `plain-healthcheck`** — the last check this skill runs. It validates every `config.yaml`, runs `plain-parser check` on every top module, and checks every module against the rules, so a feature is never finished while the project would fail to render. If it returns `FAIL`, work through its numbered list (fixing only `.plain` files / `config.yaml` / scripts — never generated code) by dropping back into the loop, then re-run. Repeat until `PASS`. Only then tell the user the feature is ready to render as `<module>.plain`.

package/forge/skills/add-feature/references/checklist.md

@@ -27,12 +27,12 @@ Use this to verify the workflow was followed — never as a substitute for it. R
 - [ ] New concepts defined before they are referenced, with no circular references.
 - [ ] Any answer that contradicted an earlier snippet was fixed in place before the next question — no stale intent left on disk.
 - [ ] Every conflict / break / augment surfaced by the analyzers was put to the user as the *next* question (keep / augment / replace) and resolved before continuing.
-- [ ] `***test reqs***` / `***acceptance tests***` authored only when the Conformance gate holds (a `config.yaml` with a valid `conformance-tests-script` pointing at an existing script).
+- [ ] `***test reqs***` / test plain files authored only when the Conformance gate holds (a `config.yaml` with a valid `conformance-tests-script` pointing at an existing script).
 - [ ] Asked the user whether the feature is fully covered before leaving the loop.
 
 ## Phase 3 — Final review
 
 - [ ] Read the modified `.plain` file(s) in full.
-- [ ] Verified: concepts defined before use, no cycles, chronological ordering correct end-to-end, functional specs language-agnostic, every external interface explicit (endpoints, methods, CLI args, formats), acceptance tests consistent with their parent specs.
+- [ ] Verified: concepts defined before use, no cycles, chronological ordering correct end-to-end, functional specs language-agnostic, every external interface explicit (endpoints, methods, CLI args, formats), every new or changed functionality's test plain file in step with its spec.
 - [ ] Presented the final diff and got the user's approval (change requests dropped back into the one-question loop, not a restart).
 - [ ] Ran `plain-healthcheck`; worked its numbered list to `PASS` (fixing only `.plain`/`config.yaml`/scripts — never generated code) before declaring the feature ready and reminding the user to re-render `<module>.plain`.

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

@@ -13,17 +13,18 @@ description: >-
 
 # Add Functional Spec
 
-Always use the skill `load-plain-reference` to retrieve the ***plain syntax rules — but only if you haven't done so yet.
+**Load the rules first.** Before you read, edit, or write any `.plain` file, invoke the `load-plain-reference` skill and read the rule files it routes you to. Skip this only if `load-plain-reference` already ran in this conversation.
 
 ## Workflow
 
 1. **Identify the target `.plain` file.** If ambiguous, ask the user.
 2. **Read the entire file** to understand existing definitions, implementation reqs, and all current functional specs (including those in `requires` modules).
-3. **Draft the functional spec** following the rules below, then run the review pass in `concise-specs.md` over the draft — trim it to the shortest wording that keeps every fact before any other check.
+3. **Pick the func-id and draft the functional spec.** Choose a func-id per `semantic-ids.md` and confirm no `# <func-id>` heading with that id exists in the module. Draft the body, a statement line and any detail under it, following the rules below, then run the review pass in `concise-specs.md` over the draft — trim it to the shortest wording that keeps every fact before any other check.
 4. **Analyze complexity** — use the `analyze-if-func-spec-too-complex` skill to verify the drafted spec implies ≤ 200 LOC. If too complex, use the `break-down-func-spec` skill to split it, then repeat from step 3 for each resulting spec.
 5. **Check for conflicts** with every existing functional spec — this is critical. Run `analyze-func-specs` **once** with the new spec plus all existing specs (in the file and in any `requires` chain) as a single batch. The batched analyzer returns every conflicting pair in one call — do **not** invoke a pair-by-pair analyzer. For each conflicting pair it reports, run `resolve-spec-conflict` on that pair; re-run `analyze-func-specs` over the touched set after each resolution until the verdict is `COMPATIBLE`.
-6. **Append the spec** to the end of the `***functional specs***` section (specs are chronological; new ones go last).
+6. **Append the spec** to the end of the `***functional specs***` section as a `# <func-id>` heading followed by its body, one blank line after the previous functionality (specs are chronological; new ones go last).
 7. **Read the file again** to confirm correct placement and syntax.
+8. **Write the test plain file.** When conformance tests are enabled for the module, invoke `add-test-scenarios` for the new functionality (see *Test Scenarios* below).
 
 ## Rules
 
@@ -48,15 +49,16 @@ The new spec must not contradict any existing functional spec. Conflicting specs
 
 ### 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 LOC.
+Each functional spec must be unambiguous — the renderer should have only one reasonable interpretation. If the statement line is not enough to fully disambiguate the behavior, add `- ` bullets or sentences under it. The detail clarifies the statement; it does not introduce separate functionality. Even with the detail, the spec must still imply ≤ 200 LOC.
 
 ```plain
 ***functional specs***
 
-- 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:.
+# 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:.
 ```
 
 
@@ -68,9 +70,9 @@ Specs must be detailed enough that a developer can use the built software withou
 
 Functionality must be self-contained in the spec text. `requires` modules only import functional specs, so do not rely on implementation reqs to convey behavior — they won't be visible in downstream modules.
 
-## Acceptance Tests
+## Test Scenarios
 
-If the functional spec needs verification, use the `add-acceptance-test` skill to add acceptance tests after inserting the spec.
+After inserting the spec, invoke `add-test-scenarios` for it. It writes the functionality's test plain file (by convention `tests/<module>/<func-id>.plain`) with at least one conformance scenario when conformance tests are enabled for the module.
 
 ## Validation Checklist
 
@@ -83,3 +85,5 @@ If the functional spec needs verification, use the `add-acceptance-test` skill t
 - [ ] Trimmed per `concise-specs.md`: nothing obvious, no rationale, no uncheckable adjectives or hedges, plain words throughout
 - [ ] No redundancy with existing specs
 - [ ] Placed in correct chronological position (usually at the end)
+- [ ] The func-id follows `semantic-ids.md` and is unique in the module
+- [ ] `add-test-scenarios` was invoked for the new functionality when conformance tests are enabled

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

@@ -12,7 +12,7 @@ description: >-
 
 # Add Functional Specs
 
-Always use the skill `load-plain-reference` to retrieve the ***plain syntax rules — but only if you haven't done so yet.
+**Load the rules first.** Before you read, edit, or write any `.plain` file, invoke the `load-plain-reference` skill and read the rule files it routes you to. Skip this only if `load-plain-reference` already ran in this conversation.
 
 ## When to Use
 
@@ -28,7 +28,7 @@ This skill is `add-functional-spec` applied **one spec at a time, in order**, wi
 
 1. **Identify the target `.plain` file.** If ambiguous, ask the user.
 2. **Read the entire file** to understand existing definitions, implementation reqs, and all current functional specs (including those reachable via `import` / `requires`).
-3. **Draft all the specs you intend to add**, in the chronological order they should appear. Keep the drafts in a working list — nothing is inserted yet. Run the review pass in `concise-specs.md` over every draft before continuing; trim each to the shortest wording that keeps every fact.
+3. **Draft all the specs you intend to add**, in the chronological order they should appear, each with its own func-id per `semantic-ids.md`, unique in the module and within the batch. Keep the drafts in a working list — nothing is inserted yet. Run the review pass in `concise-specs.md` over every draft before continuing; trim each to the shortest wording that keeps every fact.
 4. **For each drafted spec, in order:**
    1. **Analyze complexity.** Run `analyze-if-func-spec-too-complex` on the spec. If the verdict is `TOO COMPLEX`, run `break-down-func-spec`, replace the entry in the working list with the resulting smaller specs (preserving order), and restart this step on the first of the replacements.
    2. **Check for conflicts.** Run `analyze-func-specs` **once** with this single input set:
@@ -37,8 +37,9 @@ This skill is `add-functional-spec` applied **one spec at a time, in order**, wi
       - every spec from this batch that has already been inserted.
 
       The batched analyzer returns every conflicting pair in one call — do **not** loop over pairs invoking a per-pair analyzer. For each conflicting pair it reports, run `resolve-spec-conflict`. Apply the resolution — which may revise the new spec, an existing spec, or both — then re-run `analyze-func-specs` once over the touched set until the verdict is `COMPATIBLE`.
-   3. **Append the spec** to the `***functional specs***` section. Specs are chronological; the new entry goes at the end (unless an earlier existing spec must come *after* it — in that rare case, insert at the correct position).
+   3. **Append the spec** to the `***functional specs***` section as a `# <func-id>` heading followed by its body. Specs are chronological; the new entry goes at the end (unless an earlier existing spec must come *after* it — in that rare case, insert at the correct position).
 5. **Read the file again** to confirm correct placement, ordering, and syntax for the full batch.
+6. **Write the test plain files.** When conformance tests are enabled for the module, invoke `add-test-scenarios` once per inserted functionality, in order.
 
 Order matters: each new spec is inserted only after its complexity and conflict checks pass, so subsequent specs in the batch are always checked against an already-validated file.
 
@@ -71,15 +72,16 @@ That coverage is achieved by running `analyze-func-specs` **once per spec being
 
 ### Disambiguation (per spec)
 
-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 LOC.
+Each functional spec must be unambiguous — the renderer should have only one reasonable interpretation. If the statement line is not enough to fully disambiguate the behavior, add `- ` bullets or sentences under it. The detail clarifies the statement; it does not introduce separate functionality. Even with the detail, the spec must still imply ≤ 200 LOC.
 
 ```plain
 ***functional specs***
 
-- 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:.
+# 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:.
 ```
 
 
@@ -91,9 +93,9 @@ Specs must be detailed enough that a developer can use the built software withou
 
 Functionality must be self-contained in the spec text. `requires` modules only import functional specs, so do not rely on implementation reqs to convey behavior — they won't be visible in downstream modules.
 
-## Acceptance Tests
+## Test Scenarios
 
-If any of the newly added functional specs need verification, use the `add-acceptance-test` skill to add acceptance tests after the batch has been inserted. Do this per spec, not as part of the bulk pass.
+After the batch has been inserted, invoke `add-test-scenarios` once per inserted functionality, in order. It writes each functionality's test plain file (by convention `tests/<module>/<func-id>.plain`) with at least one conformance scenario when conformance tests are enabled for the module. Do this per spec, not as part of the bulk pass.
 
 ## Anti-Patterns
 
@@ -117,3 +119,5 @@ If any of the newly added functional specs need verification, use the `add-accep
 - [ ] Every spec trimmed per `concise-specs.md`: nothing obvious, no rationale, no uncheckable adjectives or hedges, plain words throughout
 - [ ] No redundancy with existing specs or within the batch
 - [ ] Specs placed in correct chronological positions
+- [ ] Every func-id follows `semantic-ids.md` and is unique in the module and within the batch
+- [ ] `add-test-scenarios` was invoked for every inserted functionality when conformance tests are enabled

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

@@ -10,7 +10,7 @@ description: >-
 
 # Add Implementation Requirement
 
-Always use the skill `load-plain-reference` to retrieve the ***plain syntax rules — but only if you haven't done so yet.
+**Load the rules first.** Before you read, edit, or write any `.plain` file, invoke the `load-plain-reference` skill and read the rule files it routes you to. Skip this only if `load-plain-reference` already ran in this conversation.
 
 ## Workflow
 

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

@@ -9,7 +9,7 @@ description: >-
 
 # Add Resource
 
-Always use the skill `load-plain-reference` to retrieve the ***plain syntax rules — but only if you haven't done so yet.
+**Load the rules first.** Before you read, edit, or write any `.plain` file, invoke the `load-plain-reference` skill and read the rule files it routes you to. Skip this only if `load-plain-reference` already ran in this conversation.
 
 Linked resources are external files referenced from within a `.plain` spec using markdown link syntax. The file contents are passed to the renderer alongside the spec, providing additional context for code generation.
 
@@ -35,7 +35,8 @@ Use standard markdown link syntax inside any spec section:
 
 ***functional specs***
 
-- An API conforming to the [API specification](resources/api_spec.yaml) is exposed.
+# expose-api
+An API conforming to the [API specification](resources/api_spec.yaml) is exposed.
 ```
 
 ## Path Rules

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

@@ -8,7 +8,7 @@ description: >-
 
 # Add Template
 
-Always use the skill `load-plain-reference` to retrieve the ***plain syntax rules — but only if you haven't done so yet.
+**Load the rules first.** Before you read, edit, or write any `.plain` file, invoke the `load-plain-reference` skill and read the rule files it routes you to. Skip this only if `load-plain-reference` already ran in this conversation.
 
 Templates use Liquid syntax (`{% include %}`) to reuse the same spec content across multiple `.plain` files. Each inclusion can pass different parameters, producing tailored output from a single source. This is distinct from `import` and `requires` — templates are about textual reuse with parameterization, not module dependencies.
 

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

@@ -9,7 +9,7 @@ description: >-
 
 # Add Test Requirement
 
-Always use the skill `load-plain-reference` to retrieve the ***plain syntax rules — but only if you haven't done so yet.
+**Load the rules first.** Before you read, edit, or write any `.plain` file, invoke the `load-plain-reference` skill and read the rule files it routes you to. Skip this only if `load-plain-reference` already ran in this conversation.
 
 ## Workflow
 
@@ -33,7 +33,7 @@ Test reqs specify how **conformance tests** should be written and run. Common co
 ## What Does NOT Belong Here
 
 - **Unit test guidance** — that goes in `***implementation reqs***`
-- **Acceptance tests** — those are nested under individual functional specs in `***functional specs***`
+- **Test scenarios** — conformance and acceptance scenarios live in test plain files, written with `add-test-scenarios` (see `test-plain-files.md`)
 - **Behavioral requirements** — those go in `***functional specs***`
 - **Technology choices for the implementation** — those go in `***implementation reqs***`
 
@@ -42,8 +42,8 @@ Test reqs specify how **conformance tests** should be written and run. Common co
 | Test Type | Where to Specify | Purpose |
 |-----------|-----------------|---------|
 | Unit tests | `***implementation reqs***` | Test individual functionalities in isolation |
-| Conformance tests | `***test reqs***` | Verify implementation conforms to the full spec |
-| Acceptance tests | `***acceptance tests***` under a functional spec | Verify a specific functional spec |
+| Conformance tests | how: `***test reqs***`; what: `***conformance tests***` of the test plain file | Verify the expected use of one functionality, its main path |
+| Acceptance tests | how: `***test reqs***`; what: `***acceptance tests***` of the test plain file | Verify one functionality under use that is not expected: invalid parameters, wrong or missing authentication, missing data |
 
 ## Format
 

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

@@ -0,0 +1,98 @@
+---
+name: add-test-scenarios
+description: >-
+  Write or update the test plain file of one functionality
+  (by convention tests/<module>/<func-id>.plain): conformance scenarios for its expected use
+  and, when the user asks for them, acceptance scenarios for its unexpected use, in plain English. Use after
+  a functional spec is added or changed, when a functionality has no
+  conformance scenario, or when the user asks for a test scenario.
+---
+
+# Add Test Scenarios
+
+**Load the rules first.** Before you read, edit, or write any `.plain` file, invoke the `load-plain-reference` skill and read the rule files it routes you to. Skip this only if `load-plain-reference` already ran in this conversation.
+
+## What this skill writes
+
+One test plain file per functionality, by convention at `tests/<module>/<func-id>.plain`, with the frontmatter keys `module:` and `func_id:` and the two sections `***conformance tests***` and `***acceptance tests***`. Every scenario is a `# <scenario-id>` heading, one plain-English statement line, and `- ` bullets when the line is not enough. Conformance scenarios are written with the spec; acceptance scenarios only when the user asks for them. The renderer generates one test per scenario and nothing else, so the scenarios in this file are the only tests the functionality gets.
+
+## When to Use
+
+- `add-functional-spec` or `add-functional-specs` inserted a functionality — those skills invoke this one for each new functionality.
+- A functional spec changed (edit, split, conflict resolution, move) and its scenarios must be brought back in step.
+- A functionality has no test plain file, or an empty `***conformance tests***` section, while conformance tests are enabled.
+- The user asks for a conformance or acceptance scenario.
+
+## Conformance gate
+
+Conformance tests are enabled for a module when the `config.yaml` that governs it has a `conformance-tests-script` entry pointing at an existing script. When they are enabled, every functionality must end up with at least one conformance scenario. When they are not enabled, write a test plain file only if the user asks for one, and say that conformance tests are off for the module.
+
+## Workflow
+
+1. **Identify the functionality.** Take the module name and func-id from the caller or the user. If the user points at a spec by its text, find its `# <func-id>` heading.
+2. **Read the context.** Read the functional spec (heading and body), the `***definitions***` the module sees (its own, its `import` modules, and the `exported_concepts` of its `requires` modules), the `***test reqs***`, and the functional specs that come before this one, because a scenario may rely on behavior they established.
+3. **Locate or create the test plain file.** Find every `.plain` file whose frontmatter binds to the pair `(module, func_id)`; by convention it is `tests/<module>/<func-id>.plain`, but only the frontmatter decides. Read every file found, so scenario-ids stay unique across the merged set. If none exists, create the file at the conventional path with the frontmatter and both sections.
+4. **List and sort the outcomes the spec states.** Walk the statement line and every clarification bullet. Write down the main path and each boundary, validation, and error case the spec names. Conformance scenarios cover the expected use (the main path and its valid variants). Use that is not expected (invalid parameters, wrong or missing authentication, missing data, an unavailable dependency) becomes an acceptance scenario only when the user asks for it; never draft one on your own. Do not add an outcome the spec does not state: a scenario may not extend the spec. If a needed outcome is missing from the spec, ask the user one question and route the answer into the functional spec through `add-functional-spec` (or an inline edit of the clarification bullets) before writing the scenario.
+5. **Draft one conformance scenario per expected-use outcome, and the acceptance scenarios the user asked for.** Give each a scenario-id per `semantic-ids.md` (short slug, unique for this functionality). Write the body in plain English:
+   - One statement line: a sentence that names the action and the expected result, with concrete values.
+   - When that line is not enough, `- ` bullets, in order: the state before the action, the one action under test, and each observable result, one fact per bullet.
+   - `given:` / `when:` / `then:` lists are allowed when the user asks for them; otherwise plain English, and one shape per project.
+   Test the functionality through the interface the spec names, as a black box. A scenario may use earlier functionalities for its setup; a scenario that spans several functionalities is bound to the last one it exercises and is written only when the user asks for it.
+6. **Check what the test can cause.** An acceptance scenario the user asked for that needs a dependency to fail (a backend that does not respond, a database that is unavailable) is written only when `***test reqs***` let the test cause that failure, for example with a local mock of that dependency. Otherwise ask the user one question: add such a test req, or leave the scenario out.
+7. **Run the review pass** from `concise-specs.md` over every scenario: no narration, no rationale, no step a reader would assume, concrete values, plain words.
+8. **Write the file and read it again.** Confirm the frontmatter keys, the section order, at least one conformance scenario when conformance tests are enabled, and that no body line starts with `# ` or `***`.
+9. **Review with the user** when running inside `forge-plain` or `add-feature`: show the scenarios as the snippet for that loop iteration and apply the response before moving on.
+
+## Updating existing scenarios
+
+- **The spec changed.** Compare every scenario with the new spec text. Remove or rewrite a scenario that no longer follows from the spec; add a scenario for every new outcome. Keep the scenario-id of a scenario whose meaning is unchanged, because the generated test carries it.
+- **The functionality was split.** Each new functionality gets its own test plain file; move each scenario to the functionality it tests and write new scenarios for outcomes that have none.
+- **The func-id was renamed.** Rename `func_id:` in every test plain file bound to it and move the file to the new conventional path.
+- **The functionality was deleted.** Delete its test plain file; confirm with the user first when it holds hand-written scenarios.
+- **The functionality moved to another module.** Update `module:` and move the file to the new conventional path.
+
+## Rules
+
+- A scenario is a direct consequence of the functional spec: it does not contradict, narrow, or extend it.
+- The kind of use decides the section, not the number of functionalities a scenario touches: expected use under `***conformance tests***`, everything else under `***acceptance tests***`.
+- Acceptance scenarios are written only on the user's explicit instruction; conformance scenarios come with the spec.
+- Scenarios are language-agnostic and black box: no function, class, or file of the implementation is named.
+- Values that matter to the check are concrete (`named "Buy milk"`, `returns 404`); descriptive values (`a valid name`) are not checkable.
+- One scenario per distinct outcome; the same outcome is never written twice in different words.
+- Framework, run command, and network policy belong in `***test reqs***`, never in a scenario.
+- No `***acceptance tests***` section is ever written into a spec plain file.
+
+## Format
+
+```plain
+---
+module: task-manager
+func_id: add-task
+---
+
+***conformance tests***
+
+# add-valid-task
+Adding a :Task: named "Buy milk" to an empty :TaskList: shows one :Task: named "Buy milk".
+
+***acceptance tests***
+
+# reject-short-name
+Adding a :Task: named "Go" to an empty :TaskList: is rejected.
+- :App: shows the error "Name must be at least 3 characters".
+- :TaskList: stays empty.
+```
+
+## Validation Checklist
+
+- [ ] The file's `module:` and `func_id:` name an existing functionality
+- [ ] `***conformance tests***` comes first, `***acceptance tests***` second; both sections exist
+- [ ] At least one conformance scenario when conformance tests are enabled for the module
+- [ ] Every expected-use outcome the functional spec states has one conformance scenario; no scenario states an outcome the spec does not
+- [ ] No unexpected-use scenario under `***conformance tests***`, no expected-use scenario under `***acceptance tests***`
+- [ ] Acceptance scenarios only where the user asked for them
+- [ ] Every scenario is a `# <scenario-id>` heading, a plain-English statement line, bullets when needed, and concrete values
+- [ ] Scenario-ids follow `semantic-ids.md` and are unique across every test plain file bound to this functionality
+- [ ] Scenarios are black box and language-agnostic
+- [ ] Trimmed per `concise-specs.md`
+- [ ] No `***acceptance tests***` section was written into the spec plain file

package/forge/skills/analyze-2-func-specs/SKILL.md

@@ -9,7 +9,7 @@ description: >-
 
 # Analyze Two Functional Specs
 
-Always use the skill `load-plain-reference` to retrieve the ***plain syntax rules — but only if you haven't done so yet.
+**Load the rules first.** Before you read, edit, or write any `.plain` file, invoke the `load-plain-reference` skill and read the rule files it routes you to. Skip this only if `load-plain-reference` already ran in this conversation.
 
 ## Input
 

package/forge/skills/analyze-func-specs/SKILL.md

@@ -9,7 +9,7 @@ description: >-
 
 # Analyze Functional Specs
 
-Always use the skill `load-plain-reference` to retrieve the ***plain syntax rules — but only if you haven't done so yet.
+**Load the rules first.** Before you read, edit, or write any `.plain` file, invoke the `load-plain-reference` skill and read the rule files it routes you to. Skip this only if `load-plain-reference` already ran in this conversation.
 
 ## Input
 
@@ -19,7 +19,7 @@ A **set of two or more functional specs** to check against each other. Callers t
 - A new spec (or batch of new specs) **plus** the existing specs from the same file and any `requires` modules.
 - An explicit list of spec snippets the user wants compared.
 
-Each spec must be identifiable. If the caller didn't label them, assign **stable identifiers** in order of appearance: `S1`, `S2`, `S3`, …. Use those identifiers in the output. If the caller provided their own IDs or quoted snippets, use those instead and keep them verbatim.
+Each spec must be identifiable. Use its func-id (`<module>:<func-id>` when the batch spans modules). A draft that has no func-id yet gets a **stable identifier** in order of appearance: `S1`, `S2`, `S3`, …. Use those identifiers in the output. If the caller provided its own labels or quoted snippets, use those instead and keep them verbatim.
 
 The skill also needs the `***definitions***` section (and any imported definitions) so referenced `:Concepts:` can be resolved.